@juspay/neurolink 11.29.2 → 12.0.0

package/dist/proxy/shareNotes.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Transferable coin notes — A issues, B holds, C redeems against A.
+ *
+ * A grant's coins are bound to the pair that agreed them. A note is not: it is a
+ * bearer credit against the issuing node, redeemable by whoever presents it and
+ * holds a grant with that node. That is what lets capacity move through a mesh
+ * rather than only along the edge it was granted on.
+ *
+ * **Replay protection is the whole design.** A note is worth exactly one
+ * redemption, so the issuer keeps a record of every note it minted and marks it
+ * spent under the same lock that credits the balance. Two nodes racing the same
+ * note produce one credit and one `spent`.
+ *
+ * **What a holder can and cannot check.** Notes are signed with an HMAC keyed by
+ * a secret only the issuer has, so an intermediate holder cannot verify one
+ * offline — it can only ask the issuer, which is what `POST /peer/note` is for.
+ * That check is safe to expose because holding the note is itself the
+ * credential: the request must carry a note whose signature the issuer accepts,
+ * so it tells a stranger nothing they did not already have.
+ *
+ * An asymmetric signature would let a holder verify without asking. It is not
+ * available here — the package's browser bundle stubs `node:crypto` down to a
+ * subset with no Ed25519 — and the check-with-the-issuer step has to exist
+ * regardless, because a valid signature says nothing about whether the note has
+ * already been spent.
+ *
+ * @module proxy/shareNotes
+ */
+import type { ProxyShareNote, ProxyShareNoteRecord, ProxyShareNoteStatus } from "../types/index.js";
+/** Default life of a note. Long enough to hand over, short enough to expire. */
+export declare const DEFAULT_NOTE_TTL_MS = 2592000000;
+/** Wire prefix, so a note is never mistaken for a share token. */
+export declare const NOTE_PREFIX = "nln";
+/**
+ * How long a record outlives the note it tracks.
+ *
+ * Every mint appends a record and nothing ever removed one, so the file grew
+ * for the life of the node. A record past its `notAfter` cannot authorize
+ * anything — the note is refused as `expired` — so the only thing the extra
+ * retention buys is that a holder presenting a just-lapsed note is told
+ * `expired` rather than the more alarming `unknown`. A month of that is plenty.
+ */
+export declare const NOTE_RECORD_RETENTION_MS = 2592000000;
+export declare function initShareNotes(filePath: string): void;
+/** Render a note as one line that survives a chat window. */
+export declare function encodeShareNote(note: ProxyShareNote): string;
+/** Read a note back. Returns undefined for anything that is not one of ours. */
+export declare function decodeShareNote(encoded: string): ProxyShareNote | undefined;
+/**
+ * Mint a note against this node.
+ *
+ * The record is written before the note is returned, so a note can never exist
+ * that the issuer has no memory of — the case where a crash between the two
+ * would leave an unredeemable credit in someone's hands.
+ */
+export declare function issueShareNote(args: {
+    issuer: string;
+    coins: number;
+    ttlMs?: number;
+    memo?: string;
+    now?: number;
+}): Promise<ProxyShareNote>;
+/**
+ * What the issuer makes of a note it is shown.
+ *
+ * `forged` and `unknown` are kept apart deliberately: the first means the
+ * signature does not check out, the second means it does but this node has no
+ * record of minting it — which is what a note from a *different* issuer looks
+ * like, and is a different thing to tell the holder.
+ */
+export declare function inspectShareNote(note: ProxyShareNote, secret: string | undefined, now?: number): Promise<{
+    status: ProxyShareNoteStatus;
+    coins: number;
+}>;
+/**
+ * Redeem a note into a grant's balance.
+ *
+ * Marking spent and crediting happen under one lock, so two holders racing the
+ * same note produce exactly one credit. The record is marked **before** the
+ * credit: a crash between them costs the redeemer the note, which is the safe
+ * direction — the alternative is a note that can be redeemed twice.
+ */
+export declare function redeemShareNote(args: {
+    note: ProxyShareNote;
+    grantId: string;
+    secret: string | undefined;
+    now?: number;
+}): Promise<{
+    ok: true;
+    coins: number;
+    balance: number | undefined;
+} | {
+    ok: false;
+    status: ProxyShareNoteStatus;
+}>;
+/** Every note this node has minted, newest first. */
+export declare function listShareNotes(): Promise<ProxyShareNoteRecord[]>;

package/dist/proxy/shareNotes.js

@@ -0,0 +1,234 @@
+/**
+ * Transferable coin notes — A issues, B holds, C redeems against A.
+ *
+ * A grant's coins are bound to the pair that agreed them. A note is not: it is a
+ * bearer credit against the issuing node, redeemable by whoever presents it and
+ * holds a grant with that node. That is what lets capacity move through a mesh
+ * rather than only along the edge it was granted on.
+ *
+ * **Replay protection is the whole design.** A note is worth exactly one
+ * redemption, so the issuer keeps a record of every note it minted and marks it
+ * spent under the same lock that credits the balance. Two nodes racing the same
+ * note produce one credit and one `spent`.
+ *
+ * **What a holder can and cannot check.** Notes are signed with an HMAC keyed by
+ * a secret only the issuer has, so an intermediate holder cannot verify one
+ * offline — it can only ask the issuer, which is what `POST /peer/note` is for.
+ * That check is safe to expose because holding the note is itself the
+ * credential: the request must carry a note whose signature the issuer accepts,
+ * so it tells a stranger nothing they did not already have.
+ *
+ * An asymmetric signature would let a holder verify without asking. It is not
+ * available here — the package's browser bundle stubs `node:crypto` down to a
+ * subset with no Ed25519 — and the check-with-the-issuer step has to exist
+ * regardless, because a valid signature says nothing about whether the note has
+ * already been spent.
+ *
+ * @module proxy/shareNotes
+ */
+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 { creditShareGrantCoins, getOrCreateNoteSecret } from "./shareGrants.js";
+import { signSharePayload, verifySharePayload } from "./shareSigning.js";
+const NOTES_FILE = "proxy-share-notes.json";
+/** Default life of a note. Long enough to hand over, short enough to expire. */
+export const DEFAULT_NOTE_TTL_MS = 2_592_000_000;
+/** Wire prefix, so a note is never mistaken for a share token. */
+export const NOTE_PREFIX = "nln";
+/**
+ * How long a record outlives the note it tracks.
+ *
+ * Every mint appends a record and nothing ever removed one, so the file grew
+ * for the life of the node. A record past its `notAfter` cannot authorize
+ * anything — the note is refused as `expired` — so the only thing the extra
+ * retention buys is that a holder presenting a just-lapsed note is told
+ * `expired` rather than the more alarming `unknown`. A month of that is plenty.
+ */
+export const NOTE_RECORD_RETENTION_MS = 2_592_000_000;
+let customFilePath = null;
+let notes = {};
+let loaded = false;
+const mutationMutex = new AsyncMutex();
+export function initShareNotes(filePath) {
+    customFilePath = filePath;
+    notes = {};
+    loaded = false;
+}
+function getFilePath() {
+    return customFilePath ?? join(homedir(), ".neurolink", NOTES_FILE);
+}
+async function ensureLoaded(options = {}) {
+    if (loaded && !options.force) {
+        return;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(getFilePath(), "utf8"));
+        notes = parsed?.notes ?? {};
+    }
+    catch {
+        notes = {};
+    }
+    loaded = true;
+}
+async function persist() {
+    const { writeJsonSnapshotAtomically } = await import("./snapshotPersistence.js");
+    const file = { schemaVersion: 1, notes };
+    await writeJsonSnapshotAtomically(getFilePath(), file);
+}
+/** Everything the signature covers. */
+function notePayload(note) {
+    return note;
+}
+/** Render a note as one line that survives a chat window. */
+export function encodeShareNote(note) {
+    return `${NOTE_PREFIX}_${Buffer.from(JSON.stringify(note), "utf8").toString("base64url")}`;
+}
+/** Read a note back. Returns undefined for anything that is not one of ours. */
+export function decodeShareNote(encoded) {
+    const trimmed = encoded.trim();
+    if (!trimmed.startsWith(`${NOTE_PREFIX}_`)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(trimmed.slice(NOTE_PREFIX.length + 1), "base64url").toString("utf8"));
+        if (typeof parsed?.noteId !== "string" ||
+            typeof parsed.coins !== "number" ||
+            typeof parsed.signature !== "string" ||
+            typeof parsed.notAfter !== "number") {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Mint a note against this node.
+ *
+ * The record is written before the note is returned, so a note can never exist
+ * that the issuer has no memory of — the case where a crash between the two
+ * would leave an unredeemable credit in someone's hands.
+ */
+export async function issueShareNote(args) {
+    if (!(args.coins > 0)) {
+        throw new Error("A note must carry a positive number of coins.");
+    }
+    const secret = await getOrCreateNoteSecret();
+    const now = args.now ?? Date.now();
+    const unsigned = {
+        schemaVersion: 1,
+        noteId: randomBytes(12).toString("base64url"),
+        issuer: args.issuer,
+        coins: args.coins,
+        issuedAt: now,
+        notAfter: now + (args.ttlMs ?? DEFAULT_NOTE_TTL_MS),
+        ...(args.memo ? { memo: args.memo } : {}),
+    };
+    const note = {
+        ...unsigned,
+        signature: signSharePayload(notePayload(unsigned), secret),
+    };
+    await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        // Minting is the only thing that grows this file, so it is also where the
+        // pruning belongs — no timer, and the cost is paid by the operation that
+        // caused it.
+        pruneExpiredNotes(now);
+        notes[note.noteId] = {
+            noteId: note.noteId,
+            coins: note.coins,
+            issuedAt: note.issuedAt,
+            notAfter: note.notAfter,
+            ...(note.memo ? { memo: note.memo } : {}),
+        };
+        await persist();
+    });
+    return note;
+}
+/**
+ * Drop records for notes that can no longer be redeemed or usefully explained.
+ *
+ * Must be called under the mutation mutex, by something that persists after.
+ */
+function pruneExpiredNotes(now) {
+    for (const [noteId, record] of Object.entries(notes)) {
+        if (record.notAfter + NOTE_RECORD_RETENTION_MS <= now) {
+            delete notes[noteId];
+        }
+    }
+}
+/**
+ * What the issuer makes of a note it is shown.
+ *
+ * `forged` and `unknown` are kept apart deliberately: the first means the
+ * signature does not check out, the second means it does but this node has no
+ * record of minting it — which is what a note from a *different* issuer looks
+ * like, and is a different thing to tell the holder.
+ */
+export async function inspectShareNote(note, secret, now = Date.now()) {
+    const { signature, ...unsigned } = note;
+    if (!secret || !verifySharePayload(unsigned, signature, secret)) {
+        return { status: "forged", coins: 0 };
+    }
+    await ensureLoaded({ force: true });
+    const record = notes[note.noteId];
+    if (!record) {
+        return { status: "unknown", coins: 0 };
+    }
+    if (record.redeemedAt !== undefined) {
+        return { status: "spent", coins: record.coins };
+    }
+    if (record.notAfter <= now) {
+        return { status: "expired", coins: record.coins };
+    }
+    return { status: "valid", coins: record.coins };
+}
+/**
+ * Redeem a note into a grant's balance.
+ *
+ * Marking spent and crediting happen under one lock, so two holders racing the
+ * same note produce exactly one credit. The record is marked **before** the
+ * credit: a crash between them costs the redeemer the note, which is the safe
+ * direction — the alternative is a note that can be redeemed twice.
+ */
+export async function redeemShareNote(args) {
+    const now = args.now ?? Date.now();
+    const { signature, ...unsigned } = args.note;
+    if (!args.secret || !verifySharePayload(unsigned, signature, args.secret)) {
+        return { ok: false, status: "forged" };
+    }
+    const claimed = await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const record = notes[args.note.noteId];
+        if (!record) {
+            return { status: "unknown", coins: 0 };
+        }
+        if (record.redeemedAt !== undefined) {
+            return { status: "spent", coins: record.coins };
+        }
+        if (record.notAfter <= now) {
+            return { status: "expired", coins: record.coins };
+        }
+        notes[record.noteId] = {
+            ...record,
+            redeemedAt: now,
+            redeemedByGrant: args.grantId,
+        };
+        await persist();
+        return { status: "valid", coins: record.coins };
+    });
+    if (claimed.status !== "valid") {
+        return { ok: false, status: claimed.status };
+    }
+    const balance = await creditShareGrantCoins(args.grantId, claimed.coins);
+    return { ok: true, coins: claimed.coins, balance };
+}
+/** Every note this node has minted, newest first. */
+export async function listShareNotes() {
+    await ensureLoaded({ force: true });
+    return Object.values(notes).sort((a, b) => b.issuedAt - a.issuedAt);
+}

package/dist/proxy/sharePolicy.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Peer-sharing admission policy.
+ *
+ * Pure evaluation, no I/O — every input is passed in, so this module is cheap on
+ * the hot path and directly exercisable from a test.
+ *
+ * The gate set is deliberately **orthogonal and AND-ed**: a grant may carry a
+ * headroom floor *and* a window-slice ceiling *and* a model allowlist, and each
+ * is checked independently. The effective allowance is therefore the minimum
+ * across whatever is configured, which is what lets "share only what I am not
+ * using, and never more than a fifth of it" be one grant rather than two
+ * competing modes.
+ *
+ * Evaluation splits in two, because the two halves answer different questions:
+ *
+ * - `evaluateShareAdmission` — request-level. Is this borrower allowed to ask at
+ *   all, right now, for this model?
+ * - `filterAccountsForGrant` — account-level. Of the lender's accounts, which
+ *   may serve this borrower? Headroom and slice ceilings live here because they
+ *   are properties of an individual account's windows, not of the request.
+ *
+ * @module proxy/sharePolicy
+ */
+import type { ProxyShareAccountExclusion, ProxyShareAccountFilterResult, ProxyShareAccountView, ProxyShareAdmission, ProxyShareAdmissionInput, ProxyShareGates, ProxyShareGrant, ProxyShareRefusalReason, ProxyShareRefusedAdmission, ProxySharePoolUsage } from "../types/index.js";
+/**
+ * Narrow an admission to its refusing half.
+ *
+ * A plain `!admission.admitted` check would do this under `strict`, but one of
+ * the package's build steps compiles without `strictNullChecks`, where TypeScript
+ * declines to narrow a boolean discriminant at all. An explicit predicate holds
+ * in both modes.
+ */
+export declare function isShareRefusal(admission: ProxyShareAdmission): admission is ProxyShareRefusedAdmission;
+export declare function shareRefusalMessage(reason: ProxyShareRefusalReason): string;
+/** HTTP status for a refusal. 401 is "who are you", 403 is "not you, not ever
+ *  under this grant", 429 is "not now" — the borrower retries only the last. */
+export declare function shareRefusalStatus(reason: ProxyShareRefusalReason): number;
+/**
+ * Is `now` inside the grant's allowed hours?
+ *
+ * A window whose start hour is greater than its end hour wraps midnight
+ * (`21 → 9` means the night shift), which is the common case for lending
+ * capacity you are asleep through.
+ */
+export declare function isWithinSchedule(schedule: {
+    fromHour: number;
+    toHour: number;
+}, now: number): boolean;
+/**
+ * Does the requested model fall inside the allowlist?
+ *
+ * Entries are matched as case-insensitive substrings so a grant can name a tier
+ * (`sonnet`) rather than having to track every dated model id.
+ */
+export declare function isModelAllowed(models: string[] | undefined, model: string | undefined): boolean;
+/**
+ * Request-level admission.
+ *
+ * Order matters: identity and lifecycle first (they are permanent refusals),
+ * then scope, then the transient limits that carry a `Retry-After`. A borrower
+ * that is told "paused" must not also be told "slow down".
+ */
+export declare function evaluateShareAdmission(input: ProxyShareAdmissionInput): ProxyShareAdmission;
+/**
+ * Is the account inside its spillover window — close enough to a reset, with
+ * little enough consumed, that the remaining capacity would otherwise expire?
+ *
+ * Unknown reset times fail closed. A spillover grant is a promise about capacity
+ * that is *about to be lost*; without a reset time there is no such promise to
+ * keep, and guessing would hand out capacity the lender still intends to use.
+ */
+export declare function isSpilloverActive(gates: ProxyShareGates, account: ProxyShareAccountView, now: number): boolean;
+/**
+ * Split the pool into the accounts this grant may draw on and the rest.
+ *
+ * An entry in `gates.accounts` matches either the full store key
+ * (`anthropic:alice`) or the bare label (`alice`), because operators think in
+ * labels and the routing path thinks in keys.
+ *
+ * Exported because the scope decides more than admission: it is also the
+ * denominator of the pool-wide slice, and computing that over accounts the grant
+ * can never touch would loosen the ceiling in proportion to how many there are.
+ */
+export declare function accountsInGrantScope(gates: ProxyShareGates, accounts: readonly ProxyShareAccountView[]): {
+    inScope: ProxyShareAccountView[];
+    outOfScope: ProxyShareAccountView[];
+};
+/**
+ * Decide which of the lender's accounts this grant may draw on.
+ *
+ * Returning exclusions alongside the survivors is deliberate: when nothing
+ * survives, the caller needs to say *why* — "your slice is spent" and "I am
+ * holding back my reserve" are different answers, and only one of them will
+ * change on its own.
+ */
+export declare function filterAccountsForGrant(grant: ProxyShareGrant, accounts: readonly ProxyShareAccountView[], now: number, 
+/**
+ * Required, not optional. `gates.maxSlice` is a ceiling on what this grant
+ * has already drawn from the pool, and with nothing to compare against the
+ * only available answer is "not yet" — so an omitted argument would not relax
+ * the ceiling, it would remove it. `readSharePoolWindowUsage` returns zeroed
+ * fractions for a grant with no history, which is the honest empty value.
+ */
+poolUsage: ProxySharePoolUsage): ProxyShareAccountFilterResult;
+/**
+ * Collapse per-account exclusions into the single reason the borrower is told
+ * when nothing survived. A transient cause outranks a structural one so the
+ * borrower learns whether waiting is worth anything.
+ */
+export declare function summarizeAccountExclusions(excluded: readonly ProxyShareAccountExclusion[]): ProxyShareRefusalReason;