@juspay/neurolink 11.29.2 → 11.30.0

package/dist/proxy/shareAudit.js

@@ -0,0 +1,280 @@
+/**
+ * Trust-but-verify for complete-mode shares.
+ *
+ * A complete-mode borrower calls the provider directly, so the lender never sees
+ * its requests and its reported spend is, strictly, an assertion. This module is
+ * what stops that assertion from being the only evidence.
+ *
+ * **The signal.** The provider reports the account's own utilization, and the
+ * borrower cannot influence that number. If an account's window moved between
+ * two heartbeats, someone spent it. If the lender's own node served nothing on
+ * that account in the same interval, and the borrower reported nothing either,
+ * then something consumed the account that neither party is accounting for —
+ * which is exactly the shape of a borrower that stopped reporting.
+ *
+ * **Why it is conservative.** The check only fires when the lender's own traffic
+ * on that account was zero for the interval. A busy lender moves the same
+ * numbers, and a false accusation is worse than a missed one: the remedy here is
+ * to pause someone's access. Everything ambiguous is reported as `attributable`
+ * and left alone.
+ *
+ * This detects a borrower that under-reports. It does not, and cannot, detect
+ * one that reports honestly and simply spends what it was lent. It is also blind
+ * across a window reset: utilization that falls between two check-ins reads as
+ * no movement, so spend timed around a rollover goes unremarked. Closing that
+ * would mean trusting a reset timestamp the borrower also influences, which is
+ * a worse trade than the gap.
+ *
+ * @module proxy/shareAudit
+ */
+import { readFile, stat } 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 AUDIT_FILE = "proxy-share-audit.json";
+/**
+ * How much of a window may move unexplained before it counts as drift.
+ *
+ * Utilization is reported coarsely and can tick from rounding or from a request
+ * that was in flight across the boundary, so a hair-trigger would cry wolf.
+ */
+export const DRIFT_TOLERANCE_PCT = 2;
+/** Consecutive drifting heartbeats tolerated before the grant is paused. */
+export const DRIFT_STREAK_LIMIT = 3;
+/**
+ * How long a read may trust the cache before it stats the file again.
+ *
+ * The CLI reads and clears this trail from a separate process (`share audit`,
+ * `share resume`), so a load-once cache would let the proxy keep counting a
+ * drift streak an operator already cleared.
+ */
+const RELOAD_TTL_MS = 1_000;
+let customAuditFilePath = null;
+let cache = {};
+let cacheLoadedAt = 0;
+let cacheMtimeMs = -1;
+let cacheValid = false;
+const mutationMutex = new AsyncMutex();
+export function initShareAudit(auditFilePath) {
+    customAuditFilePath = auditFilePath;
+    cache = {};
+    cacheLoadedAt = 0;
+    cacheMtimeMs = -1;
+    cacheValid = false;
+}
+function getAuditFilePath() {
+    return customAuditFilePath ?? join(homedir(), ".neurolink", AUDIT_FILE);
+}
+/**
+ * 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";
+}
+async function ensureLoaded(options = {}) {
+    const now = Date.now();
+    if (!options.force && cacheValid && now - cacheLoadedAt < RELOAD_TTL_MS) {
+        return;
+    }
+    const path = getAuditFilePath();
+    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;
+        }
+        cache = {};
+        cacheMtimeMs = -1;
+        cacheLoadedAt = now;
+        cacheValid = true;
+        return;
+    }
+    // A forced load skips this. mtime is the fast path for a read, 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"));
+        cache = parsed?.records ?? {};
+    }
+    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 finish the corruption off.
+            // Abort instead and leave the file for a human. Reads stay tolerant.
+            throw error;
+        }
+        cache = {};
+    }
+    cacheMtimeMs = mtimeMs;
+    cacheLoadedAt = now;
+    cacheValid = true;
+}
+async function persist() {
+    const file = { schemaVersion: 1, records: cache };
+    await writeJsonSnapshotAtomically(getAuditFilePath(), file);
+    try {
+        cacheMtimeMs = (await stat(getAuditFilePath())).mtimeMs;
+    }
+    catch {
+        cacheMtimeMs = -1;
+    }
+    cacheLoadedAt = Date.now();
+    cacheValid = true;
+}
+/** Utilization movement between two observations, in whole percent. */
+function movementPct(before, after) {
+    if (before === null || after === null) {
+        return 0;
+    }
+    return Math.max(0, (after - before) * 100);
+}
+/**
+ * Compare one heartbeat against the account's real movement.
+ *
+ * Pure: the caller supplies the previous observation and the current one, so the
+ * decision is inspectable and testable without any I/O.
+ */
+export function evaluateDrift(previous, current, tolerancePct = DRIFT_TOLERANCE_PCT) {
+    if (!previous) {
+        return { drifted: false, reason: "no_baseline" };
+    }
+    // The lender's own traffic moves the same windows. With no way to split the
+    // two apart, an interval the lender also used is not evidence of anything.
+    if (current.lenderRequests > 0) {
+        return { drifted: false, reason: "attributable" };
+    }
+    const sessionMoved = movementPct(previous.sessionUsed, current.sessionUsed);
+    const weeklyMoved = movementPct(previous.weeklyUsed, current.weeklyUsed);
+    const moved = Math.max(sessionMoved, weeklyMoved);
+    if (moved <= tolerancePct) {
+        return { drifted: false, reason: "quiet" };
+    }
+    if (current.reportedCoins > 0) {
+        // The borrower owned up to spending. Whether the amount is exactly right is
+        // not knowable from utilization alone, and guessing would invent precision.
+        return { drifted: false, reason: "attributable" };
+    }
+    return {
+        drifted: true,
+        unexplainedSessionPct: sessionMoved,
+        unexplainedWeeklyPct: weeklyMoved,
+        detail: `the account moved ${moved.toFixed(1)}% of a window since the last check-in ` +
+            `while this node served none of it and the borrower reported no spend`,
+    };
+}
+export async function getAuditRecord(grantId) {
+    await ensureLoaded();
+    return cache[grantId];
+}
+export async function listAuditRecords() {
+    await ensureLoaded();
+    return Object.values(cache);
+}
+/**
+ * Fold a heartbeat into the audit trail.
+ *
+ * Returns whether the grant has now drifted past tolerance often enough to be
+ * paused — the caller owns that decision, because pausing is a policy action and
+ * this module only supplies evidence.
+ */
+export async function recordAuditObservation(args) {
+    const limit = args.streakLimit ?? DRIFT_STREAK_LIMIT;
+    return mutationMutex.runExclusive(async () => {
+        // Force: `persist()` writes the whole map back, so a mutation that ran on a
+        // TTL-fresh snapshot would resurrect a record the CLI cleared in the window
+        // since this process last read the file.
+        await ensureLoaded({ force: true });
+        const existing = cache[args.grantId];
+        // Difference the lifetime counter here so callers can hand over the raw
+        // total; an observation always carries the per-interval delta.
+        const observation = args.lenderRequestsTotal === undefined
+            ? args.observation
+            : {
+                ...args.observation,
+                lenderRequests: Math.max(0, args.lenderRequestsTotal - (existing?.lenderRequestsTotal ?? 0)),
+            };
+        const verdict = evaluateDrift(existing?.lastObservation, observation, args.tolerancePct);
+        const streak = verdict.drifted ? (existing?.driftStreak ?? 0) + 1 : 0;
+        const record = {
+            grantId: args.grantId,
+            accountLabel: args.accountLabel,
+            lastObservation: observation,
+            ...(args.lenderRequestsTotal !== undefined
+                ? { lenderRequestsTotal: args.lenderRequestsTotal }
+                : existing?.lenderRequestsTotal !== undefined
+                    ? { lenderRequestsTotal: existing.lenderRequestsTotal }
+                    : {}),
+            driftStreak: streak,
+            ...(verdict.drifted
+                ? { lastDriftAt: observation.at, lastDriftDetail: verdict.detail }
+                : {
+                    ...(existing?.lastDriftAt !== undefined
+                        ? { lastDriftAt: existing.lastDriftAt }
+                        : {}),
+                    ...(existing?.lastDriftDetail !== undefined
+                        ? { lastDriftDetail: existing.lastDriftDetail }
+                        : {}),
+                }),
+            ...(existing?.autoPausedAt !== undefined
+                ? { autoPausedAt: existing.autoPausedAt }
+                : {}),
+        };
+        const shouldPause = streak >= limit && record.autoPausedAt === undefined;
+        if (shouldPause) {
+            record.autoPausedAt = observation.at;
+        }
+        cache[args.grantId] = record;
+        await persist();
+        return { verdict, shouldPause };
+    });
+}
+/**
+ * Clear a grant's drift streak and its auto-pause marker.
+ *
+ * Called when the lender resumes a grant. Without it the marker is permanent
+ * and `shouldPause` can never fire again, so a grant auto-paused once would
+ * drift freely for the rest of its life. The observation baseline is kept: it
+ * is the account's real utilization and is still the right thing to difference
+ * the next heartbeat against.
+ */
+export async function clearAuditDrift(grantId) {
+    await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const record = cache[grantId];
+        if (!record) {
+            return;
+        }
+        const { autoPausedAt: _autoPausedAt, ...rest } = record;
+        cache[grantId] = { ...rest, driftStreak: 0 };
+        await persist();
+    });
+}
+/** Forget a grant's audit trail — used when the grant itself is deleted. */
+export async function clearAuditRecord(grantId) {
+    await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        if (cache[grantId]) {
+            delete cache[grantId];
+            await persist();
+        }
+    });
+}

package/dist/proxy/shareContext.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Request-scoped peer-sharing context and the counters the rate gates read.
+ *
+ * The grant serving a borrowed request has to be visible deep inside the routing
+ * path — account selection filters on it, and settlement bills against it — but
+ * threading it through every call site of a 9,000-line route module would touch
+ * everything and be wrong the first time someone added a code path. An
+ * `AsyncLocalStorage` scope is the narrower change: the gate establishes it once
+ * per request, and anything downstream in the same async chain (including the
+ * `.then()` that settles a finished stream) can ask for it.
+ *
+ * Requests without a grant — the node's own client on loopback — run with no
+ * context at all, so `getShareContext()` returning `undefined` is the normal,
+ * hot case and means "this is my own traffic".
+ *
+ * @module proxy/shareContext
+ */
+import type { ProxyShareRequestContext } from "../types/index.js";
+/** Read the counters a policy evaluation needs, without mutating them. */
+export declare function readShareCounters(grantId: string, now?: number): {
+    requestsInLastMinute: number;
+    inFlight: number;
+};
+/**
+ * Claim a concurrency slot and record the request against the rate window.
+ * Returns the release function; it is idempotent because a request can end more
+ * than one way (normal return, thrown error, client disconnect) and double
+ * release would let a grant exceed its concurrency ceiling.
+ */
+export declare function acquireShareSlot(grantId: string, now?: number): () => void;
+/** Run `fn` with the grant visible to everything downstream. */
+export declare function runWithShareContext<T>(context: ProxyShareRequestContext, fn: () => T): T;
+/** The grant serving the current request, or undefined for the node's own traffic. */
+export declare function getShareContext(): ProxyShareRequestContext | undefined;
+/** True when the current request is borrowed rather than the node's own. */
+export declare function isBorrowedRequest(): boolean;
+/** Drop all counters. Test isolation only. */
+export declare function resetShareCountersForTests(): void;

package/dist/proxy/shareContext.js

@@ -0,0 +1,92 @@
+/**
+ * Request-scoped peer-sharing context and the counters the rate gates read.
+ *
+ * The grant serving a borrowed request has to be visible deep inside the routing
+ * path — account selection filters on it, and settlement bills against it — but
+ * threading it through every call site of a 9,000-line route module would touch
+ * everything and be wrong the first time someone added a code path. An
+ * `AsyncLocalStorage` scope is the narrower change: the gate establishes it once
+ * per request, and anything downstream in the same async chain (including the
+ * `.then()` that settles a finished stream) can ask for it.
+ *
+ * Requests without a grant — the node's own client on loopback — run with no
+ * context at all, so `getShareContext()` returning `undefined` is the normal,
+ * hot case and means "this is my own traffic".
+ *
+ * @module proxy/shareContext
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+const counters = new Map();
+const RATE_WINDOW_MS = 60_000;
+function getCounters(grantId) {
+    let entry = counters.get(grantId);
+    if (!entry) {
+        entry = { timestamps: [], inFlight: 0 };
+        counters.set(grantId, entry);
+    }
+    return entry;
+}
+/** Drop timestamps that have aged out of the one-minute window. */
+function prune(entry, now) {
+    if (entry.timestamps.length === 0) {
+        return;
+    }
+    const cutoff = now - RATE_WINDOW_MS;
+    let firstLive = 0;
+    while (firstLive < entry.timestamps.length &&
+        entry.timestamps[firstLive] <= cutoff) {
+        firstLive += 1;
+    }
+    if (firstLive > 0) {
+        entry.timestamps.splice(0, firstLive);
+    }
+}
+/** Read the counters a policy evaluation needs, without mutating them. */
+export function readShareCounters(grantId, now = Date.now()) {
+    const entry = counters.get(grantId);
+    if (!entry) {
+        return { requestsInLastMinute: 0, inFlight: 0 };
+    }
+    prune(entry, now);
+    return {
+        requestsInLastMinute: entry.timestamps.length,
+        inFlight: entry.inFlight,
+    };
+}
+/**
+ * Claim a concurrency slot and record the request against the rate window.
+ * Returns the release function; it is idempotent because a request can end more
+ * than one way (normal return, thrown error, client disconnect) and double
+ * release would let a grant exceed its concurrency ceiling.
+ */
+export function acquireShareSlot(grantId, now = Date.now()) {
+    const entry = getCounters(grantId);
+    prune(entry, now);
+    entry.timestamps.push(now);
+    entry.inFlight += 1;
+    let released = false;
+    return () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        entry.inFlight = Math.max(0, entry.inFlight - 1);
+    };
+}
+/** Run `fn` with the grant visible to everything downstream. */
+export function runWithShareContext(context, fn) {
+    return storage.run(context, fn);
+}
+/** The grant serving the current request, or undefined for the node's own traffic. */
+export function getShareContext() {
+    return storage.getStore();
+}
+/** True when the current request is borrowed rather than the node's own. */
+export function isBorrowedRequest() {
+    return storage.getStore() !== undefined;
+}
+/** Drop all counters. Test isolation only. */
+export function resetShareCountersForTests() {
+    counters.clear();
+}

package/dist/proxy/shareGate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Inbound gate for borrowed traffic.
+ *
+ * Transport-agnostic on purpose: it takes a header bag and returns a decision,
+ * so the same gate covers the Anthropic, OpenAI and Codex route groups from one
+ * place in the server bootstrap instead of being re-implemented per engine.
+ *
+ * **The refusal contract is the load-bearing part.** A borrower must be able to
+ * tell "you are out of credit" from "the upstream throttled me". If both arrive
+ * as a bare 429, the borrower's cooldown planner treats an exhausted grant as a
+ * transient rate limit and retries a peer that will never serve it again this
+ * week. Every refusal therefore carries `x-neurolink-grant-status` and
+ * `x-neurolink-grant-reason`, and the borrower routes on those, not the status
+ * code.
+ *
+ * @module proxy/shareGate
+ */
+import type { ProxyShareGateOutcome, ProxyShareGrant, ProxyShareRefusalReason, ProxyShareRefusalResponse } from "../types/index.js";
+/** Dedicated header, so a share token never collides with a client credential. */
+export declare const SHARE_TOKEN_HEADER = "x-neurolink-share-token";
+export declare const GRANT_STATUS_HEADER = "x-neurolink-grant-status";
+export declare const GRANT_REASON_HEADER = "x-neurolink-grant-reason";
+export declare const GRANT_COINS_HEADER = "x-neurolink-grant-remaining-coins";
+export declare const GRANT_PEER_HEADER = "x-neurolink-grant-peer";
+/**
+ * Pull a share token out of the request.
+ *
+ * `Authorization: Bearer` is accepted only when the value carries our token
+ * prefix — a bare client forwarding its own Anthropic credential must never be
+ * mistaken for a borrower, and a borrower must never have its token confused
+ * with an upstream credential.
+ */
+export declare function extractShareToken(headers: Record<string, string | undefined>): string | undefined;
+export declare function buildShareRefusal(reason: ProxyShareRefusalReason, options: {
+    status: number;
+    grant?: ProxyShareGrant;
+    retryAfterSeconds?: number;
+    message?: string;
+}): ProxyShareRefusalResponse;
+/**
+ * Should an untokened request be refused?
+ *
+ * Off by default so a node's own client keeps working on loopback exactly as
+ * before. It must be turned on before the listener is exposed — an exposed
+ * listener without it hands the lender's subscription to anyone who can reach
+ * the tunnel.
+ */
+export declare function isGrantRequiredByEnv(): boolean;
+/**
+ * Decide whether an inbound request may proceed.
+ *
+ * An admitted outcome owns a concurrency slot; the caller **must** call
+ * `release()` when the request finishes, including on error and on client
+ * disconnect, or the grant's concurrency ceiling leaks.
+ */
+export declare function admitInboundShareRequest(input: {
+    headers: Record<string, string | undefined>;
+    model?: string;
+    /** Requested output ceiling, used only to size the pre-authorization. */
+    maxTokens?: number;
+    requireGrant?: boolean;
+    coinBalanceLookup?: (grant: ProxyShareGrant) => Promise<number | undefined>;
+    now?: number;
+}): Promise<ProxyShareGateOutcome>;

package/dist/proxy/shareGate.js

@@ -0,0 +1,216 @@
+/**
+ * Inbound gate for borrowed traffic.
+ *
+ * Transport-agnostic on purpose: it takes a header bag and returns a decision,
+ * so the same gate covers the Anthropic, OpenAI and Codex route groups from one
+ * place in the server bootstrap instead of being re-implemented per engine.
+ *
+ * **The refusal contract is the load-bearing part.** A borrower must be able to
+ * tell "you are out of credit" from "the upstream throttled me". If both arrive
+ * as a bare 429, the borrower's cooldown planner treats an exhausted grant as a
+ * transient rate limit and retries a peer that will never serve it again this
+ * week. Every refusal therefore carries `x-neurolink-grant-status` and
+ * `x-neurolink-grant-reason`, and the borrower routes on those, not the status
+ * code.
+ *
+ * @module proxy/shareGate
+ */
+import { logger } from "../utils/logger.js";
+import { acquireShareSlot, readShareCounters } from "./shareContext.js";
+import { looksLikeShareToken, resolveShareToken, touchShareGrantUsage, } from "./shareGrants.js";
+import { applyRefillIfDue, availableCoins, estimateHoldCoins, openShareHold, releaseShareHold, } from "./shareLedger.js";
+import { evaluateShareAdmission, isShareRefusal, shareRefusalMessage, } from "./sharePolicy.js";
+/** Dedicated header, so a share token never collides with a client credential. */
+export const SHARE_TOKEN_HEADER = "x-neurolink-share-token";
+export const GRANT_STATUS_HEADER = "x-neurolink-grant-status";
+export const GRANT_REASON_HEADER = "x-neurolink-grant-reason";
+export const GRANT_COINS_HEADER = "x-neurolink-grant-remaining-coins";
+export const GRANT_PEER_HEADER = "x-neurolink-grant-peer";
+/**
+ * Pull a share token out of the request.
+ *
+ * `Authorization: Bearer` is accepted only when the value carries our token
+ * prefix — a bare client forwarding its own Anthropic credential must never be
+ * mistaken for a borrower, and a borrower must never have its token confused
+ * with an upstream credential.
+ */
+export function extractShareToken(headers) {
+    const dedicated = headers[SHARE_TOKEN_HEADER];
+    if (dedicated?.trim()) {
+        return dedicated.trim();
+    }
+    const authorization = headers.authorization ?? headers.Authorization;
+    if (!authorization) {
+        return undefined;
+    }
+    const trimmed = authorization.trim();
+    const bearer = trimmed.toLowerCase().startsWith("bearer ")
+        ? trimmed.slice("bearer ".length).trim()
+        : trimmed;
+    return looksLikeShareToken(bearer) ? bearer : undefined;
+}
+/** Anthropic-shaped error type for a status, so clients parse it as usual. */
+function errorTypeForStatus(status) {
+    if (status === 401) {
+        return "authentication_error";
+    }
+    if (status === 403) {
+        return "permission_error";
+    }
+    return "rate_limit_error";
+}
+/**
+ * Grant lifecycle state as the borrower sees it. Distinct from the refusal
+ * reason: the state answers "can this grant ever serve me again", the reason
+ * answers "why not this request".
+ */
+function grantStatusHeaderValue(reason, grant) {
+    switch (reason) {
+        case "paused":
+            return "paused";
+        case "revoked":
+            return "revoked";
+        case "expired":
+            return "expired";
+        case "exhausted":
+            return "exhausted";
+        case "out_of_window":
+            return "out-of-window";
+        case "missing_token":
+        case "unknown_token":
+        case "malformed_token":
+            return "unauthorized";
+        default:
+            return grant?.state ?? "active";
+    }
+}
+export function buildShareRefusal(reason, options) {
+    const { status, grant, retryAfterSeconds } = options;
+    const headers = {
+        [GRANT_STATUS_HEADER]: grantStatusHeaderValue(reason, grant),
+        [GRANT_REASON_HEADER]: reason,
+    };
+    if (grant) {
+        headers[GRANT_PEER_HEADER] = grant.peerLabel;
+        if (grant.entitlement.ledger === "coins") {
+            headers[GRANT_COINS_HEADER] = String(Math.max(0, Math.floor(grant.entitlement.coins ?? 0)));
+        }
+    }
+    if (retryAfterSeconds !== undefined) {
+        headers["retry-after"] = String(Math.max(1, Math.round(retryAfterSeconds)));
+    }
+    return {
+        status,
+        headers,
+        body: {
+            type: "error",
+            error: {
+                type: errorTypeForStatus(status),
+                message: options.message ?? shareRefusalMessage(reason),
+            },
+        },
+    };
+}
+function refusalOutcome(reason, options) {
+    return { kind: "refused", response: buildShareRefusal(reason, options) };
+}
+function toContext(grant, extra) {
+    return {
+        grantId: grant.id,
+        peerLabel: grant.peerLabel,
+        level: grant.level,
+        gates: grant.gates,
+        ledger: grant.entitlement.ledger,
+        ...(extra.holdId ? { holdId: extra.holdId } : {}),
+        ...(extra.model ? { model: extra.model } : {}),
+    };
+}
+/**
+ * Should an untokened request be refused?
+ *
+ * Off by default so a node's own client keeps working on loopback exactly as
+ * before. It must be turned on before the listener is exposed — an exposed
+ * listener without it hands the lender's subscription to anyone who can reach
+ * the tunnel.
+ */
+export function isGrantRequiredByEnv() {
+    const raw = (process.env.NEUROLINK_PROXY_REQUIRE_GRANT ?? "")
+        .trim()
+        .toLowerCase();
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+/**
+ * Decide whether an inbound request may proceed.
+ *
+ * An admitted outcome owns a concurrency slot; the caller **must** call
+ * `release()` when the request finishes, including on error and on client
+ * disconnect, or the grant's concurrency ceiling leaks.
+ */
+export async function admitInboundShareRequest(input) {
+    const now = input.now ?? Date.now();
+    const requireGrant = input.requireGrant ?? isGrantRequiredByEnv();
+    const token = extractShareToken(input.headers);
+    if (!token) {
+        if (!requireGrant) {
+            return { kind: "local" };
+        }
+        return refusalOutcome("missing_token", {
+            status: 401,
+            message: "This proxy requires a share token. Ask the lender for one with " +
+                "`neurolink proxy share create`.",
+        });
+    }
+    const resolved = await resolveShareToken(token);
+    if (!resolved) {
+        return refusalOutcome("unknown_token", { status: 401 });
+    }
+    // A standing allowance tops up here rather than on a timer: a node that was
+    // asleep across the boundary still refills on the next borrowed request.
+    const grant = resolved.state === "active"
+        ? await applyRefillIfDue(resolved, now)
+        : resolved;
+    const coinBalance = grant.entitlement.ledger === "coins"
+        ? ((await input.coinBalanceLookup?.(grant)) ?? availableCoins(grant))
+        : undefined;
+    const admission = evaluateShareAdmission({
+        grant,
+        now,
+        model: input.model,
+        counters: readShareCounters(grant.id, now),
+        ...(coinBalance !== undefined ? { coinBalance } : {}),
+    });
+    if (isShareRefusal(admission)) {
+        logger.debug(`[proxy] share refused peer=${grant.peerLabel} reason=${admission.reason}`);
+        return refusalOutcome(admission.reason, {
+            status: admission.status,
+            grant,
+            ...(admission.retryAfterSeconds !== undefined
+                ? { retryAfterSeconds: admission.retryAfterSeconds }
+                : {}),
+            message: admission.message,
+        });
+    }
+    // Pre-authorize before the request goes upstream. Without this, concurrent
+    // streams each pass the balance check and settle afterwards, overspending by
+    // one request per stream in flight.
+    const hold = grant.entitlement.ledger === "coins"
+        ? openShareHold(grant.id, estimateHoldCoins(input.model, input.maxTokens), now)
+        : undefined;
+    const releaseSlot = acquireShareSlot(grant.id, now);
+    // Cosmetic, in-memory, flushed at most once a minute — see the store.
+    touchShareGrantUsage(grant.id);
+    return {
+        kind: "admitted",
+        context: toContext(grant, {
+            ...(hold ? { holdId: hold.id } : {}),
+            ...(input.model ? { model: input.model } : {}),
+        }),
+        release: () => {
+            releaseSlot();
+            // Settlement normally consumes the hold; releasing here covers the paths
+            // that never settle at all — a handler that threw, a client that vanished
+            // before the upstream answered.
+            releaseShareHold(hold?.id);
+        },
+    };
+}