@juspay/neurolink 11.29.2 → 11.30.0

package/dist/proxy/shareGrants.js

@@ -0,0 +1,590 @@
+/**
+ * Peer-sharing grant store.
+ *
+ * A grant is one lender-issued, revocable authorization for one borrower. This
+ * module owns the persisted grant file and the token contract; it deliberately
+ * knows nothing about admission policy (see `sharePolicy.ts`) or transport.
+ *
+ * **Token contract.** A share token looks like `nls_<grantId>_<secret>`. The
+ * grant id is carried in the token so a lookup is a map hit rather than a scan
+ * over every grant, and only then is the secret compared — in constant time —
+ * against `sha256(salt + secret)`. The raw token exists exactly once, in the
+ * return value of `createShareGrant`; nothing persists it.
+ *
+ * **Cross-process freshness.** The CLI mutates this file in one process while
+ * the proxy reads it in another, so `share pause` has to land in a running
+ * proxy without a restart. Reads therefore re-stat the file and reload when its
+ * mtime moves, bounded by a short TTL so the hot path pays one `stat` per
+ * second at most.
+ *
+ * @module proxy/shareGrants
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { readFile, stat } 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 { writeJsonSnapshotAtomically } from "./snapshotPersistence.js";
+const GRANTS_FILE = "proxy-grants.json";
+/** Token prefix. Distinguishes a share token from a client's own credential. */
+export const SHARE_TOKEN_PREFIX = "nls";
+/** How long a loaded snapshot is trusted before the file is re-stat'd. */
+const RELOAD_TTL_MS = 1_000;
+let customGrantsFilePath = null;
+let cache = {};
+let cacheLoadedAt = 0;
+let cacheMtimeMs = -1;
+let cacheValid = false;
+let cachedPublicUrl;
+let cachedNoteSecret;
+const mutationMutex = new AsyncMutex();
+/** How often in-memory `lastUsedAt` updates are flushed to disk. */
+const USAGE_FLUSH_INTERVAL_MS = 60_000;
+let lastUsageFlushAt = 0;
+/** `lastUsedAt` stamps awaiting a flush, kept across the reload that flush does. */
+let pendingUsage = {};
+/** Point the store at an explicit file. Used by dev mode and by tests. */
+export function initShareGrants(grantsFilePath) {
+    customGrantsFilePath = grantsFilePath;
+    cache = {};
+    cacheLoadedAt = 0;
+    cacheMtimeMs = -1;
+    cacheValid = false;
+    cachedPublicUrl = undefined;
+    cachedNoteSecret = undefined;
+    lastUsageFlushAt = 0;
+    pendingUsage = {};
+}
+/**
+ * This node's stable public address.
+ *
+ * Recorded once — by `share url`, or by whatever already fronts this proxy — so
+ * a link can be minted without retyping the domain. Nothing here assumes the
+ * address came from `proxy expose`; a reverse proxy, a permanent named tunnel
+ * or a plain DNS record are all the same thing to a borrower.
+ */
+export async function getNodePublicUrl() {
+    await ensureLoaded();
+    return cachedPublicUrl;
+}
+export async function setNodePublicUrl(url) {
+    await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        cachedPublicUrl = url ? url.trim().replace(/\/+$/, "") : undefined;
+        await persist();
+    });
+}
+function getGrantsFilePath() {
+    return customGrantsFilePath ?? join(homedir(), ".neurolink", GRANTS_FILE);
+}
+function isShareGrant(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.id === "string" &&
+        typeof candidate.peerLabel === "string" &&
+        typeof candidate.tokenHash === "string" &&
+        typeof candidate.tokenSalt === "string" &&
+        (candidate.level === "live" || candidate.level === "complete") &&
+        typeof candidate.state === "string" &&
+        typeof candidate.entitlement === "object" &&
+        candidate.entitlement !== null &&
+        typeof candidate.gates === "object" &&
+        candidate.gates !== null);
+}
+/**
+ * Is this error simply "the file is not there yet"?
+ *
+ * The distinction is load-bearing. An absent file genuinely is an empty map —
+ * nothing has been written yet. Every *other* `stat`/read failure (`EACCES`,
+ * `EIO`, `EMFILE`, a full descriptor table) is a failure to observe the file,
+ * and answering one with an empty map is how a whole store gets erased: a
+ * caller passing `force` is about to `persist()` the map back over the real
+ * contents it just failed to read.
+ */
+function isMissingFileError(error) {
+    return error?.code === "ENOENT";
+}
+/**
+ * Load the grant file when the cache is cold or the file changed underneath us.
+ *
+ * A missing or unparseable file yields an empty set rather than an error: a node
+ * that has never shared anything is the common case, and a corrupt file must not
+ * take the proxy's hot path down. Corruption is announced once per load.
+ */
+async function ensureLoaded(options = {}) {
+    const now = Date.now();
+    if (!options.force &&
+        !options.revalidate &&
+        cacheValid &&
+        now - cacheLoadedAt < RELOAD_TTL_MS) {
+        return;
+    }
+    const path = getGrantsFilePath();
+    let mtimeMs;
+    try {
+        mtimeMs = (await stat(path)).mtimeMs;
+    }
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            // Not "no file" but "could not look" — see `isMissingFileError`. Let it
+            // out: a mutation must abort rather than persist an empty map over a
+            // store it never managed to read.
+            throw error;
+        }
+        // Missing file — an empty grant set, not an error.
+        cache = {};
+        cacheMtimeMs = -1;
+        cacheLoadedAt = now;
+        cacheValid = true;
+        return;
+    }
+    // This is where `revalidate` and `force` part company. `revalidate` wants a
+    // fresh answer cheaply and stops here when the file has not moved — that is
+    // the read path, and it must not pay for a parse per request. `force` goes
+    // on regardless, because mtime is the fast path for a read and not a
+    // correctness check for a write: several filesystems stamp it at one-second
+    // granularity, so a write landing in the same second as our last read is
+    // indistinguishable from no write at all — and every caller passing `force`
+    // is about to persist the whole map back over whatever it missed.
+    if (!options.force && cacheValid && mtimeMs === cacheMtimeMs) {
+        cacheLoadedAt = now;
+        return;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        const grants = parsed?.grants ?? {};
+        cachedPublicUrl = parsed?.publicUrl;
+        cachedNoteSecret = parsed?.noteSecret;
+        cache = Object.fromEntries(Object.entries(grants).filter((entry) => isShareGrant(entry[1])));
+    }
+    catch (error) {
+        if (options.force) {
+            // A mutation is about to write the whole map back. Treating a corrupt
+            // file as empty here would make that write the thing that finishes the
+            // corruption off — and it would take `publicUrl` and `noteSecret` with
+            // it, which no grant carries a second copy of. Abort and leave the file.
+            throw error;
+        }
+        logger.always(`[proxy] share grants unreadable, treating as empty: ${error instanceof Error ? error.message : String(error)}`);
+        cache = {};
+        cachedPublicUrl = undefined;
+        cachedNoteSecret = undefined;
+    }
+    cacheMtimeMs = mtimeMs;
+    cacheLoadedAt = now;
+    cacheValid = true;
+}
+async function persist() {
+    const file = {
+        schemaVersion: 1,
+        grants: cache,
+        ...(cachedPublicUrl ? { publicUrl: cachedPublicUrl } : {}),
+        ...(cachedNoteSecret ? { noteSecret: cachedNoteSecret } : {}),
+    };
+    await writeJsonSnapshotAtomically(getGrantsFilePath(), file);
+    try {
+        cacheMtimeMs = (await stat(getGrantsFilePath())).mtimeMs;
+    }
+    catch {
+        // A stat failure only costs one redundant reload on the next read.
+        cacheMtimeMs = -1;
+    }
+    cacheLoadedAt = Date.now();
+    cacheValid = true;
+}
+function hashSecret(salt, secret) {
+    return createHash("sha256").update(`${salt}:${secret}`).digest("hex");
+}
+/**
+ * Compare two hex digests without leaking their divergence point via timing.
+ *
+ * Hand-rolled rather than `crypto.timingSafeEqual` because the package's
+ * browser bundle stubs `node:crypto` down to a subset that does not include it,
+ * and this module is reachable from that build. Both inputs are fixed-length
+ * SHA-256 hex, so the length check leaks nothing about the secret.
+ */
+function digestsMatch(left, right) {
+    if (left.length !== right.length || left.length === 0) {
+        return false;
+    }
+    let difference = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
+    }
+    return difference === 0;
+}
+/**
+ * Split a share token into its grant id and secret.
+ * Returns null for anything that is not one of our tokens — including a client's
+ * own Anthropic credential, which must never be mistaken for a share token.
+ */
+export function parseShareToken(token) {
+    if (!token.startsWith(`${SHARE_TOKEN_PREFIX}_`)) {
+        return null;
+    }
+    // Split on the first two separators only. The secret is base64url, whose
+    // alphabet includes "_", so a naive three-way split rejects most valid
+    // tokens — every one that happens to contain an underscore.
+    const idStart = SHARE_TOKEN_PREFIX.length + 1;
+    const idEnd = token.indexOf("_", idStart);
+    if (idEnd <= idStart) {
+        return null;
+    }
+    const grantId = token.slice(idStart, idEnd);
+    const secret = token.slice(idEnd + 1);
+    if (!grantId || !secret) {
+        return null;
+    }
+    return { grantId, secret };
+}
+export function looksLikeShareToken(token) {
+    return typeof token === "string" && parseShareToken(token) !== null;
+}
+/** Expire-on-read: a grant past `notAfter` is expired regardless of its state. */
+function withDerivedState(grant, now) {
+    if (grant.state === "active" &&
+        grant.gates.notAfter !== undefined &&
+        grant.gates.notAfter <= now) {
+        return { ...grant, state: "expired" };
+    }
+    return grant;
+}
+export async function listShareGrants() {
+    await ensureLoaded();
+    const now = Date.now();
+    return Object.values(cache)
+        .map((grant) => withDerivedState(grant, now))
+        .sort((a, b) => a.createdAt - b.createdAt);
+}
+export async function getShareGrant(id) {
+    await ensureLoaded();
+    const grant = cache[id];
+    return grant ? withDerivedState(grant, Date.now()) : undefined;
+}
+/** Look a grant up by peer label (case-insensitive), the CLI's addressing form. */
+export async function findShareGrantByPeer(peerLabel) {
+    const wanted = peerLabel.trim().toLowerCase();
+    const grants = await listShareGrants();
+    return (grants.find((grant) => grant.peerLabel.toLowerCase() === wanted && grant.state !== "revoked") ??
+        grants.find((grant) => grant.id === peerLabel) ??
+        // A revoked grant is still addressable for management. Excluding it
+        // outright stranded it in the file: `share delete` could not find it by
+        // name, and only its id — which nothing prints after issue — would do.
+        grants.find((grant) => grant.peerLabel.toLowerCase() === wanted));
+}
+export async function createShareGrant(input) {
+    return mutationMutex.runExclusive(async () => {
+        // Force: `persist()` writes the whole map back, so a mutation that ran on a
+        // TTL-fresh snapshot would resurrect a grant the CLI deleted, or revert a
+        // pause it set, in the window since this process last read the file.
+        await ensureLoaded({ force: true });
+        const now = Date.now();
+        const id = randomBytes(6).toString("hex");
+        const secret = randomBytes(32).toString("base64url");
+        const tokenSalt = randomBytes(16).toString("hex");
+        const grant = {
+            schemaVersion: 1,
+            id,
+            peerLabel: input.peerLabel.trim(),
+            tokenHash: hashSecret(tokenSalt, secret),
+            tokenSalt,
+            // Keyed separately from the token so rotating the token does not
+            // invalidate every receipt already issued under it.
+            receiptSecret: randomBytes(32).toString("base64url"),
+            level: input.level,
+            state: "active",
+            entitlement: input.entitlement,
+            gates: input.gates,
+            createdAt: now,
+            updatedAt: now,
+            ...(input.note ? { note: input.note } : {}),
+        };
+        cache[id] = grant;
+        await persist();
+        return {
+            grant,
+            token: `${SHARE_TOKEN_PREFIX}_${id}_${secret}`,
+        };
+    });
+}
+/**
+ * Replace a grant's token, keeping every control intact.
+ * Used by `share revoke --rotate` and by any suspected token leak.
+ */
+export async function rotateShareGrantToken(id) {
+    return mutationMutex.runExclusive(async () => {
+        // Force: `persist()` writes the whole map back, so a mutation that ran on a
+        // TTL-fresh snapshot would resurrect a grant the CLI deleted, or revert a
+        // pause it set, in the window since this process last read the file.
+        await ensureLoaded({ force: true });
+        const grant = cache[id];
+        if (!grant) {
+            return undefined;
+        }
+        const secret = randomBytes(32).toString("base64url");
+        const tokenSalt = randomBytes(16).toString("hex");
+        const updated = {
+            ...grant,
+            tokenSalt,
+            tokenHash: hashSecret(tokenSalt, secret),
+            updatedAt: Date.now(),
+        };
+        cache[id] = updated;
+        await persist();
+        return {
+            grant: updated,
+            token: `${SHARE_TOKEN_PREFIX}_${id}_${secret}`,
+        };
+    });
+}
+export async function setShareGrantState(id, state) {
+    return mutationMutex.runExclusive(async () => {
+        // Force: `persist()` writes the whole map back, so a mutation that ran on a
+        // TTL-fresh snapshot would resurrect a grant the CLI deleted, or revert a
+        // pause it set, in the window since this process last read the file.
+        await ensureLoaded({ force: true });
+        const grant = cache[id];
+        if (!grant) {
+            return undefined;
+        }
+        const updated = {
+            ...grant,
+            state,
+            updatedAt: Date.now(),
+        };
+        cache[id] = updated;
+        await persist();
+        return updated;
+    });
+}
+export async function updateShareGrant(id, patch) {
+    return mutationMutex.runExclusive(async () => {
+        // Force: `persist()` writes the whole map back, so a mutation that ran on a
+        // TTL-fresh snapshot would resurrect a grant the CLI deleted, or revert a
+        // pause it set, in the window since this process last read the file.
+        await ensureLoaded({ force: true });
+        const grant = cache[id];
+        if (!grant) {
+            return undefined;
+        }
+        const updated = {
+            ...grant,
+            ...(patch.level ? { level: patch.level } : {}),
+            ...(patch.note !== undefined ? { note: patch.note } : {}),
+            entitlement: patch.entitlement
+                ? { ...grant.entitlement, ...patch.entitlement }
+                : grant.entitlement,
+            gates: patch.gates ? { ...grant.gates, ...patch.gates } : grant.gates,
+            updatedAt: Date.now(),
+        };
+        cache[id] = updated;
+        await persist();
+        return updated;
+    });
+}
+/**
+ * Attach complete-mode lease material to a grant.
+ *
+ * Separate from `updateShareGrant` because these are not policy the operator
+ * edits — the secret is generated once and the borrower's copy is keyed to it,
+ * so overwriting it silently would invalidate every lease already in the field.
+ */
+export async function attachLeaseMaterial(id, leaseSecret, leasePolicy, provisionedAccount) {
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const grant = cache[id];
+        if (!grant) {
+            return undefined;
+        }
+        const updated = {
+            ...grant,
+            leaseSecret: grant.leaseSecret ?? leaseSecret,
+            leasePolicy,
+            ...(provisionedAccount
+                ? { provisionedAccount }
+                : grant.provisionedAccount
+                    ? { provisionedAccount: grant.provisionedAccount }
+                    : {}),
+            updatedAt: Date.now(),
+        };
+        cache[id] = updated;
+        await persist();
+        return updated;
+    });
+}
+/**
+ * Subtract settled spend from a metered grant's balance.
+ *
+ * Read-modify-write **inside** the store's mutex, because settlement is
+ * concurrent by nature: two streams finishing together would otherwise both read
+ * the same balance, and the second write would erase the first one's deduction.
+ * Returns the new balance, or `undefined` for a grant that is not metered.
+ */
+export async function debitShareGrantCoins(id, coins) {
+    return mutationMutex.runExclusive(async () => {
+        // Force: `persist()` writes the whole map back, so a mutation that ran on a
+        // TTL-fresh snapshot would resurrect a grant the CLI deleted, or revert a
+        // pause it set, in the window since this process last read the file.
+        await ensureLoaded({ force: true });
+        const grant = cache[id];
+        if (!grant || grant.entitlement.ledger !== "coins") {
+            return undefined;
+        }
+        const remaining = Math.max(0, (grant.entitlement.coins ?? 0) - coins);
+        cache[id] = {
+            ...grant,
+            entitlement: { ...grant.entitlement, coins: remaining },
+            updatedAt: Date.now(),
+        };
+        await persist();
+        return remaining;
+    });
+}
+/**
+ * Add coins to a metered grant's balance.
+ *
+ * The mirror of `debitShareGrantCoins`, and under the same lock for the same
+ * reason. Used by reciprocal netting, by `share topup`'s successor paths, and by
+ * redeeming a coin note — all of which can land while requests are settling.
+ */
+export async function creditShareGrantCoins(id, coins) {
+    if (!(coins > 0)) {
+        return undefined;
+    }
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const grant = cache[id];
+        if (!grant || grant.entitlement.ledger !== "coins") {
+            return undefined;
+        }
+        const balance = (grant.entitlement.coins ?? 0) + coins;
+        cache[id] = {
+            ...grant,
+            entitlement: { ...grant.entitlement, coins: balance },
+            updatedAt: Date.now(),
+        };
+        await persist();
+        return balance;
+    });
+}
+/**
+ * This node's secret for signing coin notes.
+ *
+ * Node-level rather than per-grant: a note may be redeemed by a grant that did
+ * not exist when it was issued, which is the entire point of a transferable
+ * one. Minted on first use so a node that never issues a note never has one.
+ */
+export async function getOrCreateNoteSecret() {
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        if (!cachedNoteSecret) {
+            cachedNoteSecret = randomBytes(32).toString("base64url");
+            await persist();
+        }
+        return cachedNoteSecret;
+    });
+}
+/** The note secret, without minting one. */
+export async function getNoteSecret() {
+    await ensureLoaded();
+    return cachedNoteSecret;
+}
+export async function deleteShareGrant(id) {
+    return mutationMutex.runExclusive(async () => {
+        // Force: `persist()` writes the whole map back, so a mutation that ran on a
+        // TTL-fresh snapshot would resurrect a grant the CLI deleted, or revert a
+        // pause it set, in the window since this process last read the file.
+        await ensureLoaded({ force: true });
+        if (!cache[id]) {
+            return false;
+        }
+        delete cache[id];
+        await persist();
+        return true;
+    });
+}
+/**
+ * Resolve a presented token to its grant.
+ *
+ * Returns the grant whatever its state — admission is `sharePolicy`'s decision,
+ * and a paused grant must still be identifiable so the refusal can say *why*
+ * rather than "unknown token".
+ */
+export async function resolveShareToken(token) {
+    const parsed = parseShareToken(token);
+    if (!parsed) {
+        return undefined;
+    }
+    await ensureLoaded();
+    let grant = cache[parsed.grantId];
+    if (!grant) {
+        // A token minted moments ago would otherwise read as unknown until the
+        // snapshot TTL lapsed, so a miss re-stats before concluding anything.
+        //
+        // `revalidate`, emphatically not `force`. This runs on the inbound path
+        // before anything has authenticated, and every unknown token reaches it —
+        // so a client repeating one invalid token must not be able to buy a
+        // `readFile` plus a `JSON.parse` per request. Costing one `stat` and
+        // stopping on an unchanged mtime is the whole point.
+        await ensureLoaded({ revalidate: true });
+        grant = cache[parsed.grantId];
+    }
+    if (!grant) {
+        return undefined;
+    }
+    if (!digestsMatch(grant.tokenHash, hashSecret(grant.tokenSalt, parsed.secret))) {
+        return undefined;
+    }
+    return withDerivedState(grant, Date.now());
+}
+/**
+ * Record that a grant served traffic.
+ *
+ * `lastUsedAt` is cosmetic, so it is held in memory and flushed at most once a
+ * minute. Persisting it per request would put a file write on the hot path and —
+ * worse — move the file's mtime constantly, forcing every reader to reload the
+ * snapshot it just loaded.
+ */
+export function touchShareGrantUsage(id) {
+    const grant = cache[id];
+    if (!grant) {
+        return;
+    }
+    const now = Date.now();
+    // Patch the live map so an in-process read sees it immediately, and remember
+    // the stamp separately: the flush below reloads the file first, which
+    // replaces `cache` wholesale and would otherwise drop the patch.
+    cache[id] = { ...grant, lastUsedAt: now };
+    pendingUsage[id] = now;
+    if (now - lastUsageFlushAt < USAGE_FLUSH_INTERVAL_MS) {
+        return;
+    }
+    lastUsageFlushAt = now;
+    void mutationMutex
+        .runExclusive(async () => {
+        // Reload before writing. `persist()` serializes the whole map, so
+        // flushing a cosmetic timestamp onto a stale snapshot would resurrect a
+        // grant the CLI deleted in the meantime — the timestamp is not worth
+        // that. Stamps for grants that are gone are simply dropped.
+        await ensureLoaded({ force: true });
+        const stamps = pendingUsage;
+        pendingUsage = {};
+        let touched = false;
+        for (const [grantId, lastUsedAt] of Object.entries(stamps)) {
+            const current = cache[grantId];
+            if (current) {
+                cache[grantId] = { ...current, lastUsedAt };
+                touched = true;
+            }
+        }
+        if (touched) {
+            await persist();
+        }
+    })
+        .catch(() => {
+        // Cosmetic only — never surfaced to the request.
+    });
+}

package/dist/proxy/shareLease.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Leases — how a lender keeps control of a credential that lives on someone
+ * else's machine.
+ *
+ * In **live** sharing the lender's gate is in the request path, so control is
+ * immediate and total. **Complete** sharing trades that away: the borrower holds
+ * its own credential on the lender's account and calls the upstream directly, so
+ * the lender is not consulted per request. What is left is this — a signed,
+ * time-boxed statement of consent that the borrower enforces on itself and must
+ * keep renewing.
+ *
+ * The design turns on one number: **how long may the borrower run without
+ * hearing from me.** `offlineGraceMs` is that number. Set it to zero and
+ * complete mode collapses into live mode's availability; set it to a day and the
+ * borrower keeps working through a weekend when the lender's laptop is shut, at
+ * the cost of a day's revocation latency. Both are legitimate; neither is free.
+ *
+ * `notAfter` is the backstop that does not depend on the borrower's cooperation
+ * at all — it is baked into the signed payload, so a borrower that simply never
+ * calls home still stops.
+ *
+ * **Signing.** HMAC-SHA256 keyed by a per-grant secret shared with the borrower
+ * at provisioning time. Asymmetric signatures would be tidier, but the key
+ * distribution problem they solve does not exist here — exactly two parties are
+ * involved and they already share a secret — and the package's browser bundle
+ * stubs `node:crypto` down to a subset with no Ed25519 in it.
+ *
+ * @module proxy/shareLease
+ */
+import type { ProxyShareGates, ProxyShareGrant, ProxyShareLease, ProxyShareLeaseRefusal, ProxyShareLeaseVerdict, ProxyShareProvisionClaim } from "../types/index.js";
+/** A week: long enough to survive a holiday, short enough to be a real bound. */
+export declare const DEFAULT_LEASE_TTL_MS = 604800000;
+/** Fifteen minutes — frequent enough that a pause lands the same session. */
+export declare const DEFAULT_HEARTBEAT_MS = 900000;
+/** Twenty-four hours of running unheard-from. The headline trade-off. */
+export declare const DEFAULT_OFFLINE_GRACE_MS = 86400000;
+/**
+ * Narrow a verdict to its refusing half.
+ *
+ * One of the package's build steps compiles without `strictNullChecks`, where
+ * TypeScript will not narrow a boolean discriminant. An explicit predicate holds
+ * in both modes — see the same pattern in `sharePolicy.isShareRefusal`.
+ */
+export declare function isLeaseRefusal(verdict: ProxyShareLeaseVerdict): verdict is ProxyShareLeaseRefusal;
+export declare function generateLeaseSecret(): string;
+/**
+ * Issue a lease for a grant.
+ *
+ * The gates are snapshotted rather than referenced: the borrower enforces what
+ * the lender agreed to at issue time, and a tightened policy reaches them at the
+ * next heartbeat rather than silently mid-lease.
+ */
+export declare function issueLease(grant: ProxyShareGrant, now?: number): ProxyShareLease;
+/** Does this lease actually come from the lender it claims to? */
+export declare function isLeaseAuthentic(lease: ProxyShareLease, secret: string): boolean;
+/**
+ * May the borrower serve from this lease right now?
+ *
+ * Three independent stops, in the order that matters:
+ *
+ * 1. **Unsigned** — someone edited the file. Nothing else is worth checking.
+ * 2. **Expired** — `notAfter` passed. Immune to a borrower that never checks in.
+ * 3. **Grace elapsed** — the lender has been unreachable for longer than it
+ *    agreed to be trusted for. This is the one that makes "the lender turned
+ *    their laptop off" survivable and "the lender revoked me" eventually
+ *    binding.
+ */
+export declare function evaluateLease(args: {
+    lease: ProxyShareLease;
+    secret: string;
+    lastHeartbeatAt?: number;
+    now?: number;
+}): ProxyShareLeaseVerdict;
+/** Should the borrower check in now? */
+export declare function isHeartbeatDue(lease: ProxyShareLease, lastHeartbeatAt: number | undefined, now?: number): boolean;
+/** The gates a resident grant must enforce on itself, from its lease. */
+export declare function leasedGates(lease: ProxyShareLease): ProxyShareGates;
+/**
+ * Assemble what the borrower collects once the lender has authorized.
+ *
+ * Carries no token, by construction. The borrower already holds the verifier
+ * that turns the enclosed code into tokens, and it exchanges the two on its own
+ * machine — so nothing here is worth intercepting, and the lender never holds a
+ * credential for the account it just authorized.
+ *
+ * `accountLabel` is the lender's *suggestion*, not the key the credential ends
+ * up under. The borrower names the account itself — `<peer>-shared` unless
+ * `--label` says otherwise — and refuses to install over an existing one,
+ * because Anthropic quota snapshots are keyed by the bare label and two
+ * accounts sharing one would merge each other's windows. Derived from both
+ * parties' names so that a lender running `share list` and a borrower running
+ * `auth list` are looking at recognisably the same thing.
+ */
+export declare function buildProvisionClaim(args: {
+    grant: ProxyShareGrant;
+    lenderName: string;
+    lenderUrl?: string;
+    code: string;
+    state: string;
+    now?: number;
+}): ProxyShareProvisionClaim;