@juspay/neurolink 11.29.2 → 11.30.0

package/dist/proxy/shareProvisioning.js

@@ -0,0 +1,237 @@
+/**
+ * Split-PKCE provisioning — minting a resident credential without ever holding
+ * one.
+ *
+ * The earlier design had the lender complete an authorization and hand the
+ * borrower a file containing a live access token and a refresh token. That file
+ * is copyable, re-sharable, and exists on disk in plaintext at both ends for as
+ * long as anyone forgets to delete it. Nothing about the lease constrains a
+ * credential someone else already copied.
+ *
+ * This splits the flow along the seam PKCE was designed for:
+ *
+ * 1. The **borrower** generates a verifier and sends only its SHA-256
+ *    challenge, over its authenticated grant.
+ * 2. The **lender** authorizes in their own browser, against their own account,
+ *    with the borrower's challenge in the URL.
+ * 3. The **authorization code** comes back to the lender and is relayed to the
+ *    borrower.
+ * 4. The **borrower** exchanges code + verifier for tokens, on its own machine.
+ *
+ * The code is worthless to anyone who intercepts it: the token endpoint will not
+ * exchange it without the verifier, which never left the borrower. The lender
+ * never possesses a token for the credential it just authorized, so there is
+ * nothing for it to leak, re-send, or forget to delete.
+ *
+ * **What this module owns** is the lender's side of that conversation: the
+ * pending request, its binding to one grant, its expiry, and the rule that a
+ * code is handed over exactly once.
+ *
+ * @module proxy/shareProvisioning
+ */
+import { randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { AsyncMutex } from "../utils/asyncMutex.js";
+import { writeJsonSnapshotAtomically } from "./snapshotPersistence.js";
+const PROVISION_FILE = "proxy-share-provisioning.json";
+/**
+ * How long a challenge stays claimable.
+ *
+ * Long enough for a lender to notice a request and finish a browser login,
+ * short enough that a challenge left lying around is not a standing invitation.
+ */
+export const PROVISION_REQUEST_TTL_MS = 900_000;
+/** A base64url SHA-256 digest is always 43 characters, unpadded. */
+const CHALLENGE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+/** State is ours to choose; bound the shape so a peer cannot smuggle anything. */
+const STATE_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+let customFilePath = null;
+let cache = {};
+let loaded = false;
+const mutationMutex = new AsyncMutex();
+export function initShareProvisioning(filePath) {
+    customFilePath = filePath;
+    cache = {};
+    loaded = false;
+}
+function getFilePath() {
+    return customFilePath ?? join(homedir(), ".neurolink", PROVISION_FILE);
+}
+function isRequest(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.grantId === "string" &&
+        typeof candidate.codeChallenge === "string" &&
+        typeof candidate.state === "string" &&
+        typeof candidate.expiresAt === "number" &&
+        typeof candidate.status === "string");
+}
+async function ensureLoaded(options = {}) {
+    if (loaded && !options.force) {
+        return;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(getFilePath(), "utf8"));
+        cache = Object.fromEntries(Object.entries(parsed?.requests ?? {}).filter((entry) => isRequest(entry[1])));
+    }
+    catch {
+        cache = {};
+    }
+    loaded = true;
+}
+async function persist() {
+    const file = { schemaVersion: 1, requests: cache };
+    await writeJsonSnapshotAtomically(getFilePath(), file);
+}
+/**
+ * Narrow an open/authorize outcome to its failing half.
+ *
+ * One of the package's build steps compiles without `strictNullChecks`, where a
+ * boolean discriminant does not narrow. Callers reading `.reason` need this.
+ */
+export function isProvisionFailure(outcome) {
+    return !outcome.ok;
+}
+/** Is this request still live? Expiry and consumption both retire it. */
+export function isProvisionRequestOpen(request, now = Date.now()) {
+    return request.status !== "consumed" && request.expiresAt > now;
+}
+/**
+ * Record a borrower's challenge.
+ *
+ * One open request per grant: a second one replaces the first rather than
+ * queueing, because the borrower that just asked is the one waiting, and an
+ * abandoned challenge should not be claimable later by whoever finds it.
+ *
+ * Rejects anything that is not a well-formed S256 challenge. The lender is about
+ * to put this string into an authorization URL against its own account, so it
+ * is not the place to be relaxed about input.
+ */
+export async function openProvisionRequest(args) {
+    if (!CHALLENGE_PATTERN.test(args.codeChallenge)) {
+        return {
+            ok: false,
+            reason: "code_challenge must be a base64url S256 digest",
+        };
+    }
+    if (!STATE_PATTERN.test(args.state)) {
+        return { ok: false, reason: "state must be 16-128 base64url characters" };
+    }
+    const now = args.now ?? Date.now();
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const request = {
+            schemaVersion: 1,
+            grantId: args.grantId,
+            codeChallenge: args.codeChallenge,
+            challengeMethod: "S256",
+            state: args.state,
+            requestedAt: now,
+            expiresAt: now + PROVISION_REQUEST_TTL_MS,
+            status: "pending",
+        };
+        cache[args.grantId] = request;
+        await persist();
+        return { ok: true, request };
+    });
+}
+/** The open request for a grant, if there is one. */
+export async function getProvisionRequest(grantId, now = Date.now()) {
+    await ensureLoaded({ force: true });
+    const request = cache[grantId];
+    if (!request || !isProvisionRequestOpen(request, now)) {
+        return undefined;
+    }
+    return request;
+}
+/** Every open request, for a lender deciding which to authorize. */
+export async function listProvisionRequests(now = Date.now()) {
+    await ensureLoaded({ force: true });
+    return Object.values(cache).filter((request) => isProvisionRequestOpen(request, now));
+}
+/**
+ * Attach the authorization code the lender's browser produced.
+ *
+ * The code is bound to the grant that asked for it and to the account the lender
+ * authorized against — the same account the drift audit will later reconcile —
+ * so a code cannot be redirected to a different grant after the fact.
+ */
+export async function authorizeProvisionRequest(args) {
+    const now = args.now ?? Date.now();
+    const code = args.code.trim();
+    if (!code) {
+        return { ok: false, reason: "no authorization code" };
+    }
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const request = cache[args.grantId];
+        if (!request) {
+            return { ok: false, reason: "no provisioning request" };
+        }
+        if (!isProvisionRequestOpen(request, now)) {
+            return { ok: false, reason: "the request has expired" };
+        }
+        const authorized = {
+            ...request,
+            status: "authorized",
+            code,
+            authorizedAt: now,
+            ...(args.accountLabel ? { accountLabel: args.accountLabel } : {}),
+        };
+        cache[args.grantId] = authorized;
+        await persist();
+        return { ok: true, request: authorized };
+    });
+}
+/**
+ * Hand the code to the borrower — once.
+ *
+ * Single-use is the whole binding: an authorization code that could be claimed
+ * twice would let anyone who replayed the call mint a second credential on the
+ * lender's account. Consumption is recorded before the value is returned.
+ */
+export async function claimProvisionRequest(grantId, now = Date.now()) {
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const request = cache[grantId];
+        if (!request || !isProvisionRequestOpen(request, now)) {
+            return { status: "none" };
+        }
+        if (request.status !== "authorized" || !request.code) {
+            return { status: "pending" };
+        }
+        // Drop the code rather than carrying it through the spread: it has been
+        // handed over, it is single-use, and `persist()` would otherwise write a
+        // live authorization code to disk for the life of the record.
+        const { code: _claimed, ...spent } = request;
+        cache[grantId] = { ...spent, status: "consumed", claimedAt: now };
+        await persist();
+        return {
+            status: "ready",
+            code: request.code,
+            state: request.state,
+        };
+    });
+}
+/** Drop a grant's request — used when the grant itself goes away. */
+export async function clearProvisionRequest(grantId) {
+    await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        if (cache[grantId]) {
+            delete cache[grantId];
+            await persist();
+        }
+    });
+}
+/**
+ * A state value for a borrower to send alongside its challenge.
+ *
+ * Kept here so both ends agree on the shape `STATE_PATTERN` will accept.
+ */
+export function generateProvisionState() {
+    return randomBytes(24).toString("base64url");
+}

package/dist/proxy/shareReceipts.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Receipts, and the reciprocal netting built on them.
+ *
+ * **The problem receipts solve.** Until now the lender's word was the only
+ * record of what a borrowed request cost. The lender settles from usage the
+ * borrower never sees a ledger of, and a complete-mode borrower self-reports
+ * spend the lender cannot see at all. Each side simply believed the other.
+ *
+ * A receipt is the lender's signed statement that one request was settled, for
+ * how much, and against what usage. It travels with the usage block, so the
+ * borrower does not have to accept the coin figure — it recomputes the charge
+ * from the response it actually received and compares. `sequence` is contiguous
+ * per grant, so a receipt withheld to hide a charge leaves a hole.
+ *
+ * What it cannot do: an HMAC proves authorship only to the holder of the key, so
+ * a receipt settles a dispute *between the two parties to it* and is worth
+ * nothing to a third. That is the deliberate trade — see `shareSigning.ts`.
+ *
+ * **Netting.** Two nodes that lend to each other otherwise accumulate two
+ * one-way debts that never meet. Netting forgives the overlap: if a borrower has
+ * consumed 300 coins of mine and I have consumed 500 of theirs, 300 cancels on
+ * both sides. It is expressed in *cumulative* totals rather than deltas, so a
+ * replayed or duplicated round nets zero rather than paying twice.
+ *
+ * @module proxy/shareReceipts
+ */
+import type { ProxyShareNettingResult, ProxyShareReceipt, ProxyShareStatement, ProxyShareUsage } from "../types/index.js";
+/**
+ * Receipts kept per grant.
+ *
+ * Enough that a borrower checking in daily never misses one, bounded so a busy
+ * grant cannot grow the file without limit. A borrower that falls further behind
+ * than this sees a gap, which is the honest answer — the alternative is silently
+ * dropping the evidence and reporting a clean run.
+ */
+export declare const RECEIPT_HISTORY_LIMIT = 500;
+export declare function initShareReceipts(filePath: string): void;
+/**
+ * Record and sign a settlement.
+ *
+ * Never throws: a receipt that could not be written must not turn a response the
+ * borrower already has into an error. A grant with no receipt secret — one
+ * issued before receipts existed — is skipped rather than signed with nothing.
+ */
+export declare function issueShareReceipt(args: {
+    grantId: string;
+    coins: number;
+    usage: ProxyShareUsage;
+    model?: string;
+    balanceAfter: number | null;
+    settledAt?: number;
+}): Promise<ProxyShareReceipt | undefined>;
+/** Receipts a borrower has not collected yet. */
+export declare function listShareReceipts(grantId: string, since?: number): Promise<ProxyShareReceipt[]>;
+/**
+ * Check a collected run of receipts against the secret and against itself.
+ *
+ * Three independent questions, because they have different answers:
+ * a signature that does not verify means the receipt did not come from this
+ * lender; a coin figure that disagrees with its own usage block means the
+ * lender's arithmetic (or its price table) differs from ours; a missing
+ * sequence means a charge was never shown to us at all.
+ */
+export declare function auditShareReceipts(grantId: string, collected: readonly ProxyShareReceipt[], secret: string | undefined): ProxyShareStatement;
+/** Cumulative coins a grant has consumed, as its receipts record it. */
+export declare function totalReceiptedCoins(grantId: string): Promise<number>;
+/** Cumulative coins already forgiven on a grant by netting. */
+export declare function nettedCoinsFor(grantId: string): Promise<number>;
+/**
+ * Settle one round of reciprocal netting, from the lender's side.
+ *
+ * Netting forgives the same amount on both sides, so the cumulative total
+ * forgiven is one number the two nodes hold a copy of each. The round is
+ * therefore the overlap that has not been forgiven yet:
+ *
+ * ```
+ * forgivable = min(coins they consumed of mine, coins I consumed of theirs)
+ * alreadyForgiven = max(my record, their record)
+ * round = max(0, forgivable - alreadyForgiven)
+ * ```
+ *
+ * **Why the totals and not a delta.** A delta is a number the caller chooses,
+ * and a replayed round would pay it out again. Deriving the round from
+ * cumulative positions makes a replay free by construction: the second call
+ * subtracts the first one's forgiveness and lands on zero.
+ *
+ * **Why `max` over the two records.** They should agree. When they do not — a
+ * round applied on one side and lost on the other — taking the larger forgives
+ * less, which is the direction that cannot hand out coins twice.
+ */
+export declare function applyReciprocalNetting(args: {
+    grantId: string;
+    /** Cumulative coins this node has consumed under the *peer's* grant to it. */
+    consumedFromPeer: number;
+    /** Cumulative coins the peer says it has already forgiven on its side. */
+    peerAlreadyNetted: number;
+}): Promise<ProxyShareNettingResult>;
+/** Drop a grant's receipts and netting position. Used when the grant goes. */
+export declare function clearShareReceipts(grantId: string): Promise<void>;

package/dist/proxy/shareReceipts.js

@@ -0,0 +1,303 @@
+/**
+ * Receipts, and the reciprocal netting built on them.
+ *
+ * **The problem receipts solve.** Until now the lender's word was the only
+ * record of what a borrowed request cost. The lender settles from usage the
+ * borrower never sees a ledger of, and a complete-mode borrower self-reports
+ * spend the lender cannot see at all. Each side simply believed the other.
+ *
+ * A receipt is the lender's signed statement that one request was settled, for
+ * how much, and against what usage. It travels with the usage block, so the
+ * borrower does not have to accept the coin figure — it recomputes the charge
+ * from the response it actually received and compares. `sequence` is contiguous
+ * per grant, so a receipt withheld to hide a charge leaves a hole.
+ *
+ * What it cannot do: an HMAC proves authorship only to the holder of the key, so
+ * a receipt settles a dispute *between the two parties to it* and is worth
+ * nothing to a third. That is the deliberate trade — see `shareSigning.ts`.
+ *
+ * **Netting.** Two nodes that lend to each other otherwise accumulate two
+ * one-way debts that never meet. Netting forgives the overlap: if a borrower has
+ * consumed 300 coins of mine and I have consumed 500 of theirs, 300 cancels on
+ * both sides. It is expressed in *cumulative* totals rather than deltas, so a
+ * replayed or duplicated round nets zero rather than paying twice.
+ *
+ * @module proxy/shareReceipts
+ */
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { AsyncMutex } from "../utils/asyncMutex.js";
+import { logger } from "../utils/logger.js";
+import { signSharePayload, verifySharePayload } from "./shareSigning.js";
+import { usageToCoins } from "./shareLedger.js";
+import { creditShareGrantCoins, getShareGrant } from "./shareGrants.js";
+const RECEIPTS_FILE = "proxy-share-receipts.json";
+/**
+ * Receipts kept per grant.
+ *
+ * Enough that a borrower checking in daily never misses one, bounded so a busy
+ * grant cannot grow the file without limit. A borrower that falls further behind
+ * than this sees a gap, which is the honest answer — the alternative is silently
+ * dropping the evidence and reporting a clean run.
+ */
+export const RECEIPT_HISTORY_LIMIT = 500;
+let customFilePath = null;
+let receipts = {};
+let netted = {};
+/**
+ * Lifetime coins and highest sequence per grant.
+ *
+ * Both exist because `receipts` is trimmed to {@link RECEIPT_HISTORY_LIMIT}.
+ * Deriving either from the retained history is correct only until the first
+ * trim, after which a busy grant's cumulative position silently resets — which
+ * on the netting path would forgive coins that were already forgiven, and on
+ * the issuing path would reuse sequence numbers the borrower has already seen.
+ */
+let consumedTotal = {};
+let highestSequence = {};
+let loaded = false;
+const mutationMutex = new AsyncMutex();
+export function initShareReceipts(filePath) {
+    customFilePath = filePath;
+    receipts = {};
+    netted = {};
+    consumedTotal = {};
+    highestSequence = {};
+    loaded = false;
+}
+function getFilePath() {
+    return customFilePath ?? join(homedir(), ".neurolink", RECEIPTS_FILE);
+}
+async function ensureLoaded(options = {}) {
+    if (loaded && !options.force) {
+        return;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(getFilePath(), "utf8"));
+        receipts = parsed?.receipts ?? {};
+        netted = parsed?.netted ?? {};
+        // A file written before these were tracked carries neither. Seeding them
+        // from the retained history is the best available answer and is exact for
+        // any grant that has not yet been trimmed.
+        consumedTotal =
+            parsed?.consumedTotal ??
+                seedFromHistory((sum, receipt) => sum + receipt.coins);
+        highestSequence =
+            parsed?.highestSequence ??
+                seedFromHistory((top, receipt) => Math.max(top, receipt.sequence));
+    }
+    catch {
+        receipts = {};
+        netted = {};
+        consumedTotal = {};
+        highestSequence = {};
+    }
+    loaded = true;
+}
+/** Rebuild a per-grant total from whatever history survived trimming. */
+function seedFromHistory(fold) {
+    return Object.fromEntries(Object.entries(receipts).map(([grantId, history]) => [
+        grantId,
+        history.reduce(fold, 0),
+    ]));
+}
+async function persist() {
+    const { writeJsonSnapshotAtomically } = await import("./snapshotPersistence.js");
+    const file = {
+        schemaVersion: 1,
+        receipts,
+        netted,
+        consumedTotal,
+        highestSequence,
+    };
+    await writeJsonSnapshotAtomically(getFilePath(), file);
+}
+/** Everything the signature covers — the receipt minus the signature itself. */
+function receiptPayload(receipt) {
+    return receipt;
+}
+/**
+ * Record and sign a settlement.
+ *
+ * Never throws: a receipt that could not be written must not turn a response the
+ * borrower already has into an error. A grant with no receipt secret — one
+ * issued before receipts existed — is skipped rather than signed with nothing.
+ */
+export async function issueShareReceipt(args) {
+    try {
+        const grant = await getShareGrant(args.grantId);
+        const secret = grant?.receiptSecret;
+        if (!secret) {
+            return undefined;
+        }
+        return await mutationMutex.runExclusive(async () => {
+            await ensureLoaded();
+            const history = receipts[args.grantId] ?? [];
+            // From the recorded high-water mark, not the retained tail: the tail is
+            // trimmed, and restarting the sequence would read as a replay.
+            const previous = highestSequence[args.grantId] ?? 0;
+            const unsigned = {
+                schemaVersion: 1,
+                grantId: args.grantId,
+                sequence: previous + 1,
+                settledAt: args.settledAt ?? Date.now(),
+                ...(args.model ? { model: args.model } : {}),
+                usage: args.usage,
+                coins: args.coins,
+                balanceAfter: args.balanceAfter,
+            };
+            const receipt = {
+                ...unsigned,
+                signature: signSharePayload(receiptPayload(unsigned), secret),
+            };
+            history.push(receipt);
+            // Oldest first, so trimming the front is trimming the oldest.
+            receipts[args.grantId] = history.slice(-RECEIPT_HISTORY_LIMIT);
+            highestSequence[args.grantId] = receipt.sequence;
+            consumedTotal[args.grantId] =
+                (consumedTotal[args.grantId] ?? 0) + args.coins;
+            await persist();
+            return receipt;
+        });
+    }
+    catch (error) {
+        logger.always(`[proxy] could not record a receipt for grant=${args.grantId}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+/** Receipts a borrower has not collected yet. */
+export async function listShareReceipts(grantId, since = 0) {
+    await ensureLoaded({ force: true });
+    return (receipts[grantId] ?? []).filter((receipt) => receipt.sequence > since);
+}
+/**
+ * Check a collected run of receipts against the secret and against itself.
+ *
+ * Three independent questions, because they have different answers:
+ * a signature that does not verify means the receipt did not come from this
+ * lender; a coin figure that disagrees with its own usage block means the
+ * lender's arithmetic (or its price table) differs from ours; a missing
+ * sequence means a charge was never shown to us at all.
+ */
+export function auditShareReceipts(grantId, collected, secret) {
+    let coins = 0;
+    let unverified = 0;
+    let miscounted = 0;
+    const seen = new Set();
+    for (const receipt of collected) {
+        coins += receipt.coins;
+        seen.add(receipt.sequence);
+        const { signature, ...unsigned } = receipt;
+        if (!secret || !verifySharePayload(unsigned, signature, secret)) {
+            unverified += 1;
+        }
+        const expected = usageToCoins(receipt.usage, receipt.model);
+        // A tenth of a coin is a hundred normalized tokens — below any rounding
+        // this pipeline introduces, and far below a charge worth arguing about.
+        if (Math.abs(expected - receipt.coins) > 0.1) {
+            miscounted += 1;
+        }
+    }
+    const latestSequence = collected.reduce((highest, receipt) => Math.max(highest, receipt.sequence), 0);
+    // Anchored to the lowest sequence actually collected, not to 1. A borrower
+    // that collects incrementally asks for everything after the last sequence it
+    // holds, and every earlier receipt — already collected, or trimmed from the
+    // lender's bounded history — would otherwise be reported as a withheld one.
+    const earliestSequence = collected.reduce((lowest, receipt) => Math.min(lowest, receipt.sequence), latestSequence);
+    const gaps = [];
+    for (let sequence = earliestSequence; sequence <= latestSequence; sequence += 1) {
+        if (!seen.has(sequence)) {
+            gaps.push(sequence);
+        }
+    }
+    return {
+        grantId,
+        receipts: collected.length,
+        coins,
+        unverified,
+        miscounted,
+        gaps,
+        latestSequence,
+    };
+}
+/** Cumulative coins a grant has consumed, as its receipts record it. */
+export async function totalReceiptedCoins(grantId) {
+    await ensureLoaded({ force: true });
+    return consumedTotal[grantId] ?? 0;
+}
+/** Cumulative coins already forgiven on a grant by netting. */
+export async function nettedCoinsFor(grantId) {
+    await ensureLoaded({ force: true });
+    return netted[grantId] ?? 0;
+}
+/**
+ * Settle one round of reciprocal netting, from the lender's side.
+ *
+ * Netting forgives the same amount on both sides, so the cumulative total
+ * forgiven is one number the two nodes hold a copy of each. The round is
+ * therefore the overlap that has not been forgiven yet:
+ *
+ * ```
+ * forgivable = min(coins they consumed of mine, coins I consumed of theirs)
+ * alreadyForgiven = max(my record, their record)
+ * round = max(0, forgivable - alreadyForgiven)
+ * ```
+ *
+ * **Why the totals and not a delta.** A delta is a number the caller chooses,
+ * and a replayed round would pay it out again. Deriving the round from
+ * cumulative positions makes a replay free by construction: the second call
+ * subtracts the first one's forgiveness and lands on zero.
+ *
+ * **Why `max` over the two records.** They should agree. When they do not — a
+ * round applied on one side and lost on the other — taking the larger forgives
+ * less, which is the direction that cannot hand out coins twice.
+ */
+export async function applyReciprocalNetting(args) {
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        // The lifetime figure, not the retained history: netting forgives against
+        // cumulative positions, and a trimmed sum would forgive the same coins
+        // again on the next round.
+        const consumedByPeer = consumedTotal[args.grantId] ?? 0;
+        const alreadyNetted = Math.max(netted[args.grantId] ?? 0, Math.max(0, args.peerAlreadyNetted));
+        const forgivable = Math.min(consumedByPeer, Math.max(0, args.consumedFromPeer));
+        const round = Math.max(0, forgivable - alreadyNetted);
+        if (round <= 0) {
+            return {
+                netted: 0,
+                totalNetted: alreadyNetted,
+                detail: consumedByPeer <= alreadyNetted
+                    ? "nothing of mine left to forgive"
+                    : "nothing of theirs left to offset it against",
+            };
+        }
+        netted[args.grantId] = alreadyNetted + round;
+        await persist();
+        // Forgiveness is a credit: the borrower gets back what its own lending
+        // cancelled out. An unlimited grant has no balance to credit, and netting
+        // there is bookkeeping only.
+        await creditShareGrantCoins(args.grantId, round);
+        return {
+            netted: round,
+            totalNetted: netted[args.grantId],
+            detail: `forgave ${round.toFixed(1)} coins against reciprocal use`,
+        };
+    });
+}
+/** Drop a grant's receipts and netting position. Used when the grant goes. */
+export async function clearShareReceipts(grantId) {
+    await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        if (receipts[grantId] ||
+            netted[grantId] !== undefined ||
+            consumedTotal[grantId] !== undefined ||
+            highestSequence[grantId] !== undefined) {
+            delete receipts[grantId];
+            delete netted[grantId];
+            delete consumedTotal[grantId];
+            delete highestSequence[grantId];
+            await persist();
+        }
+    });
+}

package/dist/proxy/shareSigning.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The one HMAC used across peer sharing.
+ *
+ * Leases, receipts and coin notes all need the same thing: a statement one node
+ * makes that another can check without being able to forge. They had grown
+ * separate copies of the same twenty lines, which is how two of them end up with
+ * different canonicalisation and a signature that verifies on one path and not
+ * the other.
+ *
+ * **Why HMAC and not a signature scheme.** The key-distribution problem that
+ * asymmetric keys solve does not exist here: every one of these statements
+ * passes between exactly two nodes that already share a secret. The package's
+ * browser bundle also stubs `node:crypto` down to a subset with no Ed25519 in
+ * it, and these modules are reachable from that build.
+ *
+ * **What that costs.** A MAC proves authorship only to someone holding the key,
+ * so a receipt is evidence between the two parties to it and not to a third.
+ * Coin notes are built around that limit rather than against it — see
+ * `shareNotes.ts`.
+ *
+ * @module proxy/shareSigning
+ */
+/** A secret suitable for keying any of the statements in this subsystem. */
+export declare function generateShareSecret(): string;
+/**
+ * Canonicalise and sign.
+ *
+ * The payload is serialized with its keys sorted, so two nodes that built the
+ * same object in a different order still agree on the bytes being signed.
+ */
+export declare function signSharePayload(payload: unknown, secret: string): string;
+/** Does `signature` match what this secret would produce for this payload? */
+export declare function verifySharePayload(payload: unknown, signature: string, secret: string): boolean;
+/**
+ * Compare two strings without leaking where they diverge.
+ *
+ * Hand-rolled rather than `crypto.timingSafeEqual` because that is one of the
+ * things the browser bundle's `node:crypto` stub does not carry.
+ */
+export declare function secretsMatch(expected: string, presented: string): boolean;