@juspay/neurolink 11.29.2 → 11.30.0

package/dist/proxy/shareGrants.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 type { ProxyShareGrant, ProxyShareGrantInput, ProxyShareGrantPatch, ProxyShareGrantState, ProxyShareIssuedGrant } from "../types/index.js";
+/** Token prefix. Distinguishes a share token from a client's own credential. */
+export declare const SHARE_TOKEN_PREFIX = "nls";
+/** Point the store at an explicit file. Used by dev mode and by tests. */
+export declare function initShareGrants(grantsFilePath: string): void;
+/**
+ * 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 declare function getNodePublicUrl(): Promise<string | undefined>;
+export declare function setNodePublicUrl(url: string | undefined): Promise<void>;
+/**
+ * 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 declare function parseShareToken(token: string): {
+    grantId: string;
+    secret: string;
+} | null;
+export declare function looksLikeShareToken(token: string | undefined): boolean;
+export declare function listShareGrants(): Promise<ProxyShareGrant[]>;
+export declare function getShareGrant(id: string): Promise<ProxyShareGrant | undefined>;
+/** Look a grant up by peer label (case-insensitive), the CLI's addressing form. */
+export declare function findShareGrantByPeer(peerLabel: string): Promise<ProxyShareGrant | undefined>;
+export declare function createShareGrant(input: ProxyShareGrantInput): Promise<ProxyShareIssuedGrant>;
+/**
+ * Replace a grant's token, keeping every control intact.
+ * Used by `share revoke --rotate` and by any suspected token leak.
+ */
+export declare function rotateShareGrantToken(id: string): Promise<ProxyShareIssuedGrant | undefined>;
+export declare function setShareGrantState(id: string, state: ProxyShareGrantState): Promise<ProxyShareGrant | undefined>;
+export declare function updateShareGrant(id: string, patch: ProxyShareGrantPatch): Promise<ProxyShareGrant | undefined>;
+/**
+ * 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 declare function attachLeaseMaterial(id: string, leaseSecret: string, leasePolicy: {
+    ttlMs: number;
+    heartbeatEveryMs: number;
+    offlineGraceMs: number;
+}, provisionedAccount?: string): Promise<ProxyShareGrant | undefined>;
+/**
+ * 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 declare function debitShareGrantCoins(id: string, coins: number): Promise<number | undefined>;
+/**
+ * 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 declare function creditShareGrantCoins(id: string, coins: number): Promise<number | undefined>;
+/**
+ * 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 declare function getOrCreateNoteSecret(): Promise<string>;
+/** The note secret, without minting one. */
+export declare function getNoteSecret(): Promise<string | undefined>;
+export declare function deleteShareGrant(id: string): Promise<boolean>;
+/**
+ * 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 declare function resolveShareToken(token: string): Promise<ProxyShareGrant | undefined>;
+/**
+ * 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 declare function touchShareGrantUsage(id: string): void;