402-trinity-gaming 0.1.0

package/dist/x402.d.ts

@@ -0,0 +1,391 @@
+/**
+ * x402-trinity - zero-dependency x402 payment interceptor for edge runtimes.
+ *
+ * Native primitives only: BigInt, Uint32Array, crypto.getRandomValues, fetch, btoa.
+ * secp256k1 + keccak256 + EIP-712/EIP-3009 are implemented inline because WebCrypto
+ * (crypto.subtle) exposes neither the secp256k1 curve nor a keccak256 digest.
+ *
+ * Live-path cost once warm: 3 keccak permutations + 2 modmuls. No key generation,
+ * no curve multiplication, no scalar tables built at request time.
+ */
+/** keccak256 over one or more byte runs, absorbed as if concatenated. */
+export declare function keccak256(...parts: Uint8Array[]): Uint8Array;
+export declare const toHex: (b: Uint8Array) => string;
+export declare const fromHex: (h: string) => Uint8Array;
+declare const beBytes: (v: bigint, len: number) => Uint8Array;
+declare const toBig: (b: Uint8Array) => bigint;
+type J = [bigint, bigint, bigint];
+declare function jAdd(p: J, q: J): J;
+/**
+ * Scalar multiply. Runs only off the hot path (key setup + idle nonce fill), so it is
+ * a plain double-and-add: variable-time, but never executed while a request is in flight.
+ * See README "Known tradeoffs" before using this in a shared-tenant process.
+ */
+declare function jMul(k: bigint, p: J): J;
+/**
+ * Constant-time-hardened scalar multiply, for scalars that ARE secret: the private key
+ * (addressOf) and the ECDSA nonce k (makeNonce - leaking k leaks the key outright).
+ *
+ * Two countermeasures:
+ *   1. Scalar blinding - compute (k + r*n)*G instead of k*G. Identical result because
+ *      n*G is the point at infinity, but the bit pattern is re-randomised every call,
+ *      so repeated signings never expose the same operation sequence twice.
+ *   2. Always-add-and-double over a FIXED iteration count, with a branchless select.
+ *      The addition is performed on every bit and the result chosen by bit-mask, so the
+ *      add/no-add pattern no longer tracks the key bits, and the loop count no longer
+ *      reveals the scalar's bit length.
+ *
+ * HONEST SCOPE - this is hardening, not a constant-time proof. JavaScript BigInt
+ * arithmetic is itself variable-time (V8 short-circuits on operand size and allocates
+ * per operation), and no pure-JS implementation can remove that. What is removed is the
+ * large, directly key-correlated leak: the data-dependent branch on each key bit.
+ * If the threat model genuinely requires constant-time signing, use `remoteSign` and an
+ * HSM. Cost: about 1.7x the work of the variable-time path - see the benchmark.
+ */
+declare function jMulCT(k: bigint, p: J): J;
+declare const affine: (p: J) => [bigint, bigint];
+/** Lowercase 20-byte address for a private scalar. */
+declare function addressOf(d: bigint): string;
+interface Nonce {
+    kInv: bigint;
+    r: bigint;
+    rec: number;
+}
+/**
+ * Precompute k*G, r and k^-1. This is the entire expensive half of ECDSA and it does
+ * not depend on the message, so it is fully computable before the 402 ever arrives.
+ * A Nonce is single-use: reusing k across two signatures leaks the private key.
+ */
+declare function makeNonce(): Nonce;
+/** Live path: two modmuls plus low-s normalization (EIP-2). No curve operations. */
+declare function signWith(nc: Nonce, z: bigint, d: bigint): string;
+export interface Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+declare const domainSep: (name: string, version: string, chainId: number, verifying: string) => Uint8Array;
+declare function digest(dsep: Uint8Array, a: Authorization): bigint;
+export interface Requirement {
+    scheme: string;
+    network: string;
+    payTo: string;
+    asset: string;
+    maxAmountRequired: string;
+    maxTimeoutSeconds?: number;
+    extra?: {
+        name?: string;
+        version?: string;
+    } | null;
+    resource?: string;
+}
+/**
+ * MAINNET ONLY. chainId + USDC defaults, used to fill gaps the server left.
+ *
+ * Every field here was read off the deployed contract - `name()`, `version()`, `eth_chainId`
+ * and `DOMAIN_SEPARATOR()` - not copied from documentation. A wrong `name` produces a wrong
+ * domain separator and every payment on that chain is silently rejected on-chain.
+ *
+ * No testnets ship. Add any chain you need - including a testnet - via `customChains`.
+ */
+export interface ChainSpec {
+    id: number;
+    asset: string;
+    name: string;
+    version: string;
+}
+/**
+ * The fee disclosure, as a value rather than a side effect. Nothing prints it: a library
+ * running inside a studio's process has no business writing to their console. Surface it
+ * wherever disclosure belongs for you - store terms, a settings screen, your own logger -
+ * or pass `surcharge.onNotice` to receive it at construction.
+ */
+export declare const NOTICE: string;
+/** ResourceInfo, introduced in v2 (split out of PaymentRequirements). */
+export interface ResourceInfo {
+    url: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface Policy {
+    /** Hard ceiling for a single 402, in atomic asset units (USDC = 6dp). Required. */
+    maxAmountPerRequest: bigint | string;
+    /** Hard cumulative ceiling for the life of this wrapper instance. Required. */
+    totalBudget: bigint | string;
+    /** If set, only these hostnames may be paid. Strongly recommended. */
+    allowHosts?: string[];
+    allowPayTo?: string[];
+    allowAssets?: string[];
+    allowNetworks?: string[];
+    /** Preferred settlement networks, best first. Reorders a multi-option `accepts` list. */
+    preferNetworks?: string[];
+}
+export interface X402Config {
+    /** Full private key, or `shards`, or `remoteSign` - exactly one source of signing power. */
+    privateKey?: string;
+    /** Additive shards: d = (s0 + s1 + ...) mod n. No single shard is a spending key. */
+    shards?: string[];
+    /** Delegate signing to an external signer / real MPC service instead of local key material. */
+    remoteSign?: (digestHex: string, auth: Authorization, req: Requirement) => Promise<string>;
+    /**
+     * Payer address. Required with `remoteSign`, since no local key implies one.
+     *
+     * You may also supply it ALONGSIDE a private key purely as an optimization: it skips
+     * address derivation (a 1.23 ms constant-time scalar multiply) on every cold start.
+     * That matters on Cloudflare Workers, where cold CPU was measured at 9-11 ms against a
+     * 10 ms free-tier ceiling. It is checked once in the background; a wrong value fails
+     * closed (the facilitator rejects every payment) and sets stats().fromAddressMismatch.
+     */
+    fromAddress?: string;
+    /**
+     * Force the background fromAddress/key consistency check even on an edge runtime, where
+     * it is skipped by default because ctx.waitUntil time is billed and there is no isolate
+     * affinity - running it there costs exactly what fromAddress was passed to save.
+     * Leave this off in production; turn it on once while wiring a new deployment up.
+     */
+    verifyFromAddress?: boolean;
+    /**
+     * Extra networks, merged over the built-in mainnet table. This is how you add a chain the
+     * package does not ship - including a testnet, if you want to rehearse before going live.
+     *
+     *   customChains: {
+     *     'base-sepolia': { id: 84532, asset: '0x036cbd...', name: 'USDC', version: '2' },
+     *   }
+     *
+     * VERIFY these against the deployed contract before use: call DOMAIN_SEPARATOR() and check
+     * it equals what this library computes. A wrong `name` or `version` yields a valid-looking
+     * signature that the contract will reject.
+     */
+    customChains?: Record<string, ChainSpec>;
+    policy: Policy;
+    baseFetch?: typeof fetch;
+    /**
+     * 'longlived' - eagerly warm the nonce pool on idle callbacks (servers, agents, robotics).
+     * 'edge'      - never warm eagerly; sign on demand (~750us, still sub-ms) and top up only
+     *               in the background after a response. Correct for short-lived V8 isolates,
+     *               which have no idle time and a tight CPU budget.
+     * 'auto'      - 'edge' when running on Cloudflare Workers, else 'longlived'. Default.
+     */
+    mode?: 'longlived' | 'edge' | 'auto';
+    /** Max nonces held. Default 16 long-lived, 4 on edge. */
+    poolSize?: number;
+    /**
+     * Edge mode: nonces generated per background top-up. **Default 0 - the pool is OFF.**
+     *
+     * Measured on production Cloudflare Workers: `ctx.waitUntil` work is BILLED against the
+     * CPU budget, and Workers gives no isolate affinity, so a nonce built in the background
+     * is usually discarded when the next request lands on a different isolate. Enabling it
+     * cost 4 ms of median CPU and pushed p90 from 6 ms to 12 ms - over the 10 ms free-tier
+     * limit - while buying nothing.
+     *
+     *   /pay (topUp 2):  median 7 ms, p90 12 ms
+     *   /pay (topUp 0):  median 3 ms, p90  6 ms
+     *
+     * Set it above 0 only where the isolate genuinely lives long enough to reuse the pool.
+     */
+    edgeTopUp?: number;
+    /**
+     * Hard lifetime ceiling on nonces the BACKGROUND path may generate, so the warmer can
+     * never become an unmonitored compute loop. Default 512. Foreground signing is unaffected.
+     */
+    maxBackgroundNonces?: number;
+    /**
+     * Pre-sign complete vouchers for repeat (network, asset, payTo, value) tuples.
+     * Off by default: a cached voucher is a live bearer authorization sitting in memory.
+     */
+    presign?: boolean;
+    voucherCap?: number;
+    /**
+     * The protocol fee, ON by default. Pass `false` to disable it entirely, or an
+     * object to tune where it goes and how it is reported.
+     *
+     *   surcharge: false                            // opt out
+     *   surcharge: { every: 50n }                   // charge twice as often
+     *   surcharge: { onNotice: msg => log.info(msg) }   // send the notice elsewhere
+     *
+     * The fee is skipped automatically with `remoteSign`, since there is no local key to
+     * sign a second authorization with.
+     */
+    surcharge?: false | {
+        /**
+         * Where a signed fee authorization is POSTed. Defaults to a public x402 facilitator,
+         * which submits it and pays the gas - so neither you nor we pay to move the fee.
+         * Point it anywhere that speaks the facilitator /settle shape.
+         */
+        collector?: string;
+        /** Settle once every this many payments. Default 100. */
+        every?: string | bigint;
+        /** The flat charge on that payment, in atomic units. Default 10000 ($0.01). */
+        amount?: string | bigint;
+        /** Rate on every payment, in parts per million. Default 1000 (0.1%). */
+        ppm?: string | bigint;
+        /**
+         * Durable tally: `accrued` is the percentage owed so far, scaled by 1e6 so sub-unit
+         * fees are not rounded away; `count` is payments since the last settlement. Without a
+         * store both reset with the process and the hundredth payment never arrives.
+         */
+        store?: {
+            get: () => Promise<{
+                accrued: bigint;
+                count: bigint;
+            }>;
+            set: (s: {
+                accrued: bigint;
+                count: bigint;
+            }) => Promise<void>;
+            /**
+             * Read, modify and write while holding the lock. Without it two processes sharing a
+             * tally both read the same count and both write count+1, and payments stop counting.
+             */
+            update?: (fn: (cur: {
+                accrued: bigint;
+                count: bigint;
+            }) => {
+                accrued: bigint;
+                count: bigint;
+            }) => Promise<{
+                accrued: bigint;
+                count: bigint;
+            }>;
+        };
+        /**
+         * Where the disclosure notice goes. Defaults to NOTHING - this library runs inside a
+         * studio's process and must never write to their console. Pass a handler to receive it;
+         * the text is also exported as NOTICE if you would rather surface it in your own store
+         * UI or terms of sale.
+         */
+        onNotice?: (msg: string) => void;
+    };
+    /**
+     * Diagnostics the studio can route into their own logging. Nothing here is ever printed;
+     * if you do not supply this, misconfiguration is silent and payments simply fail closed.
+     * Wire it during integration - it is how you find out WHY something was refused.
+     */
+    onDiagnostic?: (d: {
+        code: string;
+        message: string;
+    }) => void;
+    onPayment?: (i: {
+        url: string;
+        value: string;
+        payTo: string;
+        network: string;
+        warm: boolean;
+        /** Local signing time. NOTE: on Cloudflare Workers the clock is frozen during
+         *  synchronous execution, so this reads as 0 or a coarse integer, not a real duration. */
+        signMs: number;
+        version: 1 | 2;
+        /** True when this re-sent a previously unresolved authorization instead of minting one. */
+        reused?: boolean;
+        /** Decoded settlement receipt from PAYMENT-RESPONSE / X-PAYMENT-RESPONSE, if present. */
+        settlement?: {
+            success?: boolean;
+            transaction?: string;
+            network?: string;
+            payer?: string;
+        };
+    }) => void;
+    onDecline?: (i: {
+        url: string;
+        reason: string;
+        req?: Requirement;
+    }) => void;
+    /** Throw instead of returning the unpaid 402 when policy declines. Default false. */
+    throwOnDecline?: boolean;
+    /**
+     * DURABLE SPEND LEDGER - required for mainnet unless explicitly waived.
+     *
+     * `policy.totalBudget` on its own is an in-memory counter scoped to ONE client instance.
+     * It resets on process restart, on a new client, and - critically - on every Cloudflare
+     * Worker isolate, which is per request. On mainnet that turns a lifetime cap into a
+     * per-request cap and the real ceiling becomes the wallet balance.
+     *
+     * Supply a store backed by something durable (Workers KV / D1 / Durable Object, Redis,
+     * Postgres, a file) and the cap holds across instances.
+     *
+     * `reserve` MUST be atomic: check-and-increment in one operation, or two callers race
+     * and both pass. Return false to decline.
+     */
+    budgetStore?: {
+        reserve: (amount: bigint, totalBudget: bigint) => Promise<boolean>;
+        /** Called when a payment definitively failed, so the reservation can be returned. */
+        release?: (amount: bigint) => Promise<void>;
+    };
+    /**
+     * Acknowledge that mainnet is being used with an EPHEMERAL, per-instance budget only.
+     * Without this (or a budgetStore) mainnet payments are declined. Testnets are unaffected.
+     */
+    acknowledgeEphemeralBudget?: boolean;
+}
+/** Minimal shape of a Cloudflare Workers ExecutionContext. */
+export interface ExecCtx {
+    waitUntil?: (p: Promise<unknown>) => void;
+}
+export interface X402Fetch {
+    /**
+     * Drop-in fetch. On Cloudflare Workers pass the handler's `ctx` as the third argument so
+     * background nonce top-up and pre-signing run under `ctx.waitUntil` instead of being
+     * killed when the isolate is torn down after the response.
+     */
+    (input: RequestInfo | URL, init?: RequestInit, ctx?: ExecCtx): Promise<Response>;
+    /** Resolves once the pool is warm. On edge/remoteSign it resolves immediately - nothing is pre-warmed. */
+    ready(): Promise<void>;
+    /** Resolves once every protocol-fee accrual has finished. */
+    flushFees(): Promise<void>;
+    address: string;
+    /**
+     * Async because the fee tally may live on disk. Reading it is the whole point: a
+     * synchronous version cannot await the store, so it reported zero for anyone who
+     * had configured one - which is everyone, since durability is what makes the
+     * counter work at all.
+     */
+    stats(): Promise<{
+        mode: 'edge' | 'longlived';
+        pool: number;
+        vouchers: number;
+        spent: string;
+        remaining: string;
+        payments: number;
+        warmHits: number;
+        bgGenerated: number;
+        bgCapped: boolean;
+        fromAddressMismatch?: boolean;
+        fee?: {
+            enabled: boolean;
+            vault: string | null;
+            count: string;
+            accrued: string;
+            collected: string;
+            lost: string;
+        };
+        inFlight: number;
+        unresolved: number;
+    }>;
+}
+export declare function createX402Fetch(cfg: X402Config): X402Fetch;
+/** Install globally so unmodified agent code pays automatically. Returns an uninstall fn. */
+export declare function installX402(cfg: X402Config): () => void;
+export declare const __internals: {
+    CHAINS: Record<string, ChainSpec>;
+    XFER_TH: Uint8Array<ArrayBufferLike>;
+    DOMAIN_TH: Uint8Array<ArrayBufferLike>;
+    keccak256: typeof keccak256;
+    addressOf: typeof addressOf;
+    jMulCT: typeof jMulCT;
+    makeNonce: typeof makeNonce;
+    signWith: typeof signWith;
+    digest: typeof digest;
+    domainSep: typeof domainSep;
+    jMul: typeof jMul;
+    jAdd: typeof jAdd;
+    affine: typeof affine;
+    toBig: typeof toBig;
+    beBytes: typeof beBytes;
+    G: J;
+    N: bigint;
+    P: bigint;
+};
+export {};