@juspay/neurolink 11.29.2 → 11.30.0

package/dist/proxy/shareLease.js

@@ -0,0 +1,192 @@
+/**
+ * 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 { generateShareSecret, secretsMatch, signSharePayload, } from "./shareSigning.js";
+/** A week: long enough to survive a holiday, short enough to be a real bound. */
+export const DEFAULT_LEASE_TTL_MS = 604_800_000;
+/** Fifteen minutes — frequent enough that a pause lands the same session. */
+export const DEFAULT_HEARTBEAT_MS = 900_000;
+/** Twenty-four hours of running unheard-from. The headline trade-off. */
+export const DEFAULT_OFFLINE_GRACE_MS = 86_400_000;
+/**
+ * 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 function isLeaseRefusal(verdict) {
+    return !verdict.usable;
+}
+export function generateLeaseSecret() {
+    return generateShareSecret();
+}
+/**
+ * The signed portion of a lease — everything but the signature itself.
+ *
+ * Field order is irrelevant: `signSharePayload` canonicalises before hashing.
+ * The explicit list is still worth keeping, because it says which fields a
+ * borrower is entitled to rely on rather than signing whatever happens to be on
+ * the object.
+ */
+function leasePayload(lease) {
+    return {
+        schemaVersion: lease.schemaVersion,
+        grantId: lease.grantId,
+        peerLabel: lease.peerLabel,
+        issuedAt: lease.issuedAt,
+        notAfter: lease.notAfter,
+        heartbeatEveryMs: lease.heartbeatEveryMs,
+        offlineGraceMs: lease.offlineGraceMs,
+        gates: lease.gates,
+        entitlementSnapshot: lease.entitlementSnapshot,
+    };
+}
+function sign(payload, secret) {
+    return signSharePayload(payload, secret);
+}
+/**
+ * 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 function issueLease(grant, now = Date.now()) {
+    const policy = grant.leasePolicy;
+    const secret = grant.leaseSecret;
+    if (!secret) {
+        throw new Error(`Grant ${grant.id} has no lease secret — provision it before issuing a lease.`);
+    }
+    const ttl = policy?.ttlMs ?? DEFAULT_LEASE_TTL_MS;
+    // A lease can never outlive the grant's own expiry.
+    const notAfter = Math.min(now + ttl, grant.gates.notAfter ?? Number.POSITIVE_INFINITY);
+    const unsigned = {
+        schemaVersion: 1,
+        grantId: grant.id,
+        peerLabel: grant.peerLabel,
+        issuedAt: now,
+        notAfter,
+        heartbeatEveryMs: policy?.heartbeatEveryMs ?? DEFAULT_HEARTBEAT_MS,
+        offlineGraceMs: policy?.offlineGraceMs ?? DEFAULT_OFFLINE_GRACE_MS,
+        gates: grant.gates,
+        entitlementSnapshot: grant.entitlement.ledger === "coins"
+            ? (grant.entitlement.coins ?? 0)
+            : "unlimited",
+    };
+    return { ...unsigned, signature: sign(leasePayload(unsigned), secret) };
+}
+/** Does this lease actually come from the lender it claims to? */
+export function isLeaseAuthentic(lease, secret) {
+    const { signature, ...unsigned } = lease;
+    return secretsMatch(sign(leasePayload(unsigned), secret), signature);
+}
+/**
+ * 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 function evaluateLease(args) {
+    const now = args.now ?? Date.now();
+    if (!isLeaseAuthentic(args.lease, args.secret)) {
+        return {
+            usable: false,
+            reason: "unsigned",
+            detail: "lease signature does not match the lender's secret",
+        };
+    }
+    if (args.lease.notAfter <= now) {
+        return {
+            usable: false,
+            reason: "expired",
+            detail: "the lease's hard expiry has passed",
+        };
+    }
+    // The lease's own issue time is the first heartbeat: a freshly provisioned
+    // borrower has not failed to check in, it simply has not had to yet.
+    const lastContact = args.lastHeartbeatAt ?? args.lease.issuedAt;
+    const graceDeadline = lastContact + args.lease.offlineGraceMs;
+    if (graceDeadline <= now) {
+        return {
+            usable: false,
+            reason: "grace_elapsed",
+            detail: "the lender has been unreachable for longer than this lease allows",
+        };
+    }
+    return {
+        usable: true,
+        nextHeartbeatDueAt: lastContact + args.lease.heartbeatEveryMs,
+    };
+}
+/** Should the borrower check in now? */
+export function isHeartbeatDue(lease, lastHeartbeatAt, now = Date.now()) {
+    const lastContact = lastHeartbeatAt ?? lease.issuedAt;
+    return now - lastContact >= lease.heartbeatEveryMs;
+}
+/** The gates a resident grant must enforce on itself, from its lease. */
+export function leasedGates(lease) {
+    return lease.gates;
+}
+/**
+ * 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 function buildProvisionClaim(args) {
+    const now = args.now ?? Date.now();
+    if (!args.grant.leaseSecret) {
+        throw new Error(`Grant ${args.grant.id} has no lease secret — attach lease material first.`);
+    }
+    return {
+        code: args.code,
+        state: args.state,
+        accountLabel: `${args.grant.peerLabel}-via-${args.lenderName}`,
+        leaseSecret: args.grant.leaseSecret,
+        lease: issueLease(args.grant, now),
+        lenderUrl: (args.lenderUrl ?? "").replace(/\/+$/, ""),
+    };
+}

package/dist/proxy/shareLedger.d.ts

@@ -0,0 +1,105 @@
+/**
+ * NeuroCoin ledger and per-window consumption tracking for borrowed traffic.
+ *
+ * Two jobs, deliberately in one module because they settle from the same event:
+ *
+ * 1. **Coins.** A grant with a coin entitlement spends against a balance. The
+ *    balance itself lives on the grant (one source of truth); this module holds
+ *    the entries and drives the deduction.
+ * 2. **Window buckets.** How much of an account's 5h/7d window a grant has taken,
+ *    keyed by that window's reset timestamp so the counter starts fresh when the
+ *    window does. This is what makes a slice ceiling mean "a fifth of *this*
+ *    window" rather than "a fifth, once, forever".
+ *
+ * **Why hold-then-settle.** Real usage is only known when the response finishes
+ * — for a stream, at `message_delta`. A balance checked at admission and
+ * deducted at completion lets N concurrent streams each pass the same check and
+ * overspend by N-1 requests. So admission opens a *hold* for an estimate, the
+ * available balance is `balance - Σ open holds`, and settlement replaces the
+ * hold with the real figure. A crash loses in-flight holds, which is the safe
+ * direction: the balance is only ever reduced by traffic that actually happened.
+ *
+ * @module proxy/shareLedger
+ */
+import type { ProxyShareGrant, ProxyShareGrantUsageSummary, ProxyShareHold, ProxySharePoolUsage, ProxyShareSettlement, ProxyShareUsage, ProxyShareWindowObservation } from "../types/index.js";
+/** Normalized tokens per coin. */
+export declare const TOKENS_PER_COIN = 1000;
+export declare function initShareLedger(ledgerFilePath: string): void;
+export declare function modelCoinWeight(model: string | undefined): number;
+/** Convert real usage into coins. Pure — the pricing table is the whole story. */
+export declare function usageToCoins(usage: ProxyShareUsage, model: string | undefined): number;
+/**
+ * What to hold at admission, before anything is known about the response.
+ *
+ * Intentionally rough: the hold exists to stop concurrent streams from each
+ * spending the last coin, not to predict the bill. Settlement replaces it with
+ * the real figure moments later.
+ */
+export declare function estimateHoldCoins(model: string | undefined, maxTokens: number | undefined): number;
+/** Coins currently held against a grant by in-flight requests. */
+export declare function heldCoins(grantId: string): number;
+/**
+ * Balance a new request may draw on: the stored balance minus what in-flight
+ * requests have already claimed.
+ */
+export declare function availableCoins(grant: ProxyShareGrant): number;
+export declare function openShareHold(grantId: string, coins: number, now?: number): ProxyShareHold;
+/** Drop a hold without spending it — the request never reached the upstream. */
+export declare function releaseShareHold(holdId: string | undefined): void;
+/**
+ * Record how much of an account's windows a borrowed request consumed.
+ *
+ * Never throws: a bookkeeping failure must not turn a response the borrower has
+ * already received into an error.
+ */
+export declare function recordShareWindowDelta(observation: ProxyShareWindowObservation): Promise<void>;
+/**
+ * Charge a finished borrowed request against its grant and close the hold.
+ *
+ * Never throws, for the same reason as above.
+ */
+export declare function settleShareUsage(settlement: ProxyShareSettlement): Promise<number>;
+/**
+ * What a grant has taken from one account's current windows.
+ *
+ * Buckets whose reset timestamp no longer matches the account's are reported as
+ * zero: they describe a window that has since rolled over.
+ */
+export declare function readShareWindowUsage(grantId: string, accountKey: string, currentSessionResetAt: number | null, currentWeeklyResetAt: number | null): Promise<{
+    sessionFraction: number;
+    weeklyFraction: number;
+}>;
+/**
+ * What a grant has taken from the pool as a whole, normalised to one window.
+ *
+ * Summing the per-account fractions and dividing by the account count is what
+ * makes a ceiling mean the same thing on a one-account pool and a ten-account
+ * one. Without the division, `--max-slice 20` would silently grant 20% of every
+ * credential — 200% of a single window's worth across ten accounts.
+ *
+ * Buckets whose reset timestamp no longer matches contribute zero: they
+ * describe a window that has since rolled over.
+ */
+export declare function readSharePoolWindowUsage(grantId: string, accounts: ReadonlyArray<{
+    accountKey: string;
+    sessionResetAt: number | null;
+    weeklyResetAt: number | null;
+}>): Promise<ProxySharePoolUsage>;
+/** Per-grant rollup across accounts, for `share status`. */
+export declare function summarizeGrantUsage(grantId: string): Promise<ProxyShareGrantUsageSummary>;
+/**
+ * Apply a standing allowance for every period that has elapsed.
+ *
+ * Called opportunistically at admission — there is no timer, so a node that is
+ * off across one or more refill boundaries pays them on its next borrowed
+ * request. Paying only the newest period would quietly turn "100 a week" into
+ * "100 whenever you next happen to ask", which is not what the operator wrote.
+ *
+ * `lastAt` advances by whole periods rather than to `now`, so the schedule stays
+ * anchored to when the grant was issued instead of drifting later with every
+ * catch-up. It advances past the periods the cap refused to pay as well — see
+ * {@link MAX_REFILL_CATCHUP_PERIODS}.
+ */
+export declare function applyRefillIfDue(grant: ProxyShareGrant, now?: number): Promise<ProxyShareGrant>;
+/** Drop all ledger state. Test isolation only. */
+export declare function resetShareLedgerForTests(): void;