thebuyside-x402-agent 0.2.0

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * thebuyside-x402-agent — MCP gateway for x402-priced APIs.
+ * Entry point. See src/server.ts for the actual server.
+ */
+import { logger } from './log.js';
+import { startServer } from './server.js';
+startServer().catch((err) => {
+    logger.error('fatal startup error', { err: String(err) });
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IACnC,MAAM,CAAC,KAAK,CAAC,qBAAqB,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/log.d.ts

@@ -0,0 +1,14 @@
+/**
+ * stderr-only structured logger.
+ *
+ * IMPORTANT: MCP servers communicate over stdio — stdout is reserved for the
+ * JSON-RPC wire protocol. Any stray write to stdout will corrupt the stream
+ * and confuse the client. All logs MUST go to stderr.
+ */
+export declare const logger: {
+    info: (msg: string, fields?: Record<string, unknown>) => void;
+    warn: (msg: string, fields?: Record<string, unknown>) => void;
+    error: (msg: string, fields?: Record<string, unknown>) => void;
+    debug: (msg: string, fields?: Record<string, unknown>) => void;
+};
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,eAAO,MAAM,MAAM;gBACL,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBACxC,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;iBACvC,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;iBACxC,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CACtD,CAAC"}

package/dist/log.js

@@ -0,0 +1,24 @@
+/**
+ * stderr-only structured logger.
+ *
+ * IMPORTANT: MCP servers communicate over stdio — stdout is reserved for the
+ * JSON-RPC wire protocol. Any stray write to stdout will corrupt the stream
+ * and confuse the client. All logs MUST go to stderr.
+ */
+function emit(level, msg, fields) {
+    const ts = new Date().toISOString();
+    const tail = fields
+        ? ' ' +
+            Object.entries(fields)
+                .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+                .join(' ')
+        : '';
+    process.stderr.write(`[${ts}] ${level.toUpperCase().padEnd(5)} ${msg}${tail}\n`);
+}
+export const logger = {
+    info: (msg, fields) => emit('info', msg, fields),
+    warn: (msg, fields) => emit('warn', msg, fields),
+    error: (msg, fields) => emit('error', msg, fields),
+    debug: (msg, fields) => emit('debug', msg, fields),
+};
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,SAAS,IAAI,CAAC,KAAY,EAAE,GAAW,EAAE,MAAgC;IACvE,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM;QACjB,CAAC,CAAC,GAAG;YACH,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;iBACnB,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC5C,IAAI,CAAC,GAAG,CAAC;QACd,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,IAAI,IAAI,CAAC,CAAC;AACnF,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,IAAI,EAAE,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC;IAClF,IAAI,EAAE,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC;IAClF,KAAK,EAAE,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC;IACpF,KAAK,EAAE,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC;CACrF,CAAC"}

package/dist/policy/allowlist.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Host allowlist — the gateway only pays hosts in this set, unless the
+ * caller explicitly overrides with X402_ALLOW_UNVERIFIED=1.
+ *
+ * The default allowlist is derived from the registry (`src/registry/seed.json`)
+ * so it auto-tracks the curated set of x402-priced APIs we ship with.
+ *
+ * Override via env:
+ *   X402_ALLOWLIST=news-ep.com,api.example.com  (comma-separated hostnames)
+ *   X402_ALLOW_UNVERIFIED=1                      (bypass — for dev/testing)
+ */
+export type AllowDecision = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare class Allowlist {
+    private readonly hosts;
+    private readonly allowAny;
+    constructor(opts?: {
+        hosts?: string[];
+        allowAny?: boolean;
+    });
+    /**
+     * Build an Allowlist from environment variables, with `defaultHosts`
+     * (typically the registry's host list) used when X402_ALLOWLIST is unset.
+     */
+    static fromEnv(opts?: {
+        defaultHosts?: string[];
+    }): Allowlist;
+    check(url: string): AllowDecision;
+    get allowedHosts(): string[];
+    get isUnrestricted(): boolean;
+}
+//# sourceMappingURL=allowlist.d.ts.map

package/dist/policy/allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../../src/policy/allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;gBAEvB,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO;IAM/D;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO,GAAG,SAAS;IAUjE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAsBjC,IAAI,YAAY,IAAI,MAAM,EAAE,CAE3B;IAED,IAAI,cAAc,IAAI,OAAO,CAE5B;CACF"}

package/dist/policy/allowlist.js

@@ -0,0 +1,61 @@
+/**
+ * Host allowlist — the gateway only pays hosts in this set, unless the
+ * caller explicitly overrides with X402_ALLOW_UNVERIFIED=1.
+ *
+ * The default allowlist is derived from the registry (`src/registry/seed.json`)
+ * so it auto-tracks the curated set of x402-priced APIs we ship with.
+ *
+ * Override via env:
+ *   X402_ALLOWLIST=news-ep.com,api.example.com  (comma-separated hostnames)
+ *   X402_ALLOW_UNVERIFIED=1                      (bypass — for dev/testing)
+ */
+const FALLBACK_HOSTS = ['news-ep.com'];
+export class Allowlist {
+    hosts;
+    allowAny;
+    constructor(opts = {}) {
+        const hosts = opts.hosts && opts.hosts.length > 0 ? opts.hosts : FALLBACK_HOSTS;
+        this.hosts = new Set(hosts);
+        this.allowAny = opts.allowAny ?? false;
+    }
+    /**
+     * Build an Allowlist from environment variables, with `defaultHosts`
+     * (typically the registry's host list) used when X402_ALLOWLIST is unset.
+     */
+    static fromEnv(opts = {}) {
+        const fromEnv = process.env.X402_ALLOWLIST?.split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        return new Allowlist({
+            hosts: fromEnv && fromEnv.length > 0 ? fromEnv : opts.defaultHosts,
+            allowAny: process.env.X402_ALLOW_UNVERIFIED === '1',
+        });
+    }
+    check(url) {
+        if (this.allowAny)
+            return { ok: true };
+        let host;
+        try {
+            host = new URL(url).hostname;
+        }
+        catch {
+            return { ok: false, reason: `invalid URL: ${url}` };
+        }
+        if (this.hosts.has(host))
+            return { ok: true };
+        const sorted = [...this.hosts].sort();
+        return {
+            ok: false,
+            reason: `host "${host}" is not in the allowlist ` +
+                `(allowed: ${sorted.length > 0 ? sorted.join(', ') : '(none)'}). ` +
+                `Set X402_ALLOWLIST=<hosts> to permit, or X402_ALLOW_UNVERIFIED=1 to bypass.`,
+        };
+    }
+    get allowedHosts() {
+        return [...this.hosts].sort();
+    }
+    get isUnrestricted() {
+        return this.allowAny;
+    }
+}
+//# sourceMappingURL=allowlist.js.map

package/dist/policy/allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../../src/policy/allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,cAAc,GAAG,CAAC,aAAa,CAAC,CAAC;AAIvC,MAAM,OAAO,SAAS;IACH,KAAK,CAAc;IACnB,QAAQ,CAAU;IAEnC,YAAY,OAAiD,EAAE;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC;QAChF,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,OAAoC,EAAE;QACnD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,GAAG,CAAC;aACnD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC,CAAC;QACnB,OAAO,IAAI,SAAS,CAAC;YACnB,KAAK,EAAE,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY;YAClE,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,GAAG;SACpD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAW;QACf,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QAEvC,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,GAAG,EAAE,EAAE,CAAC;QACtD,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QAE9C,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACtC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,SAAS,IAAI,4BAA4B;gBACzC,aAAa,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK;gBAClE,6EAA6E;SAChF,CAAC;IACJ,CAAC;IAED,IAAI,YAAY;QACd,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF"}

package/dist/policy/caps.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Spend caps — per-call and sliding-24-hour daily limits.
+ *
+ * Both limits are atomic USDC (`bigint`, 6 decimals). Defaults are deliberately
+ * conservative for v0 ("safe out-of-the-box"). Override via env:
+ *   X402_PER_CALL_LIMIT=0.05      (USDC, decimal) or 50000 (atomic units)
+ *   X402_DAILY_LIMIT=1.00          ditto
+ */
+import type { Receipts } from './receipts.js';
+export type CapConfig = {
+    perCallLimitAtomic: bigint;
+    dailyLimitAtomic: bigint;
+};
+export declare const DEFAULT_CAPS: CapConfig;
+export type CapDecision = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    spentSoFarAtomic: bigint;
+};
+export declare class CapPolicy {
+    readonly config: CapConfig;
+    private readonly receipts;
+    constructor(config: CapConfig, receipts: Receipts);
+    static fromEnv(receipts: Receipts): CapPolicy;
+    /**
+     * Check whether a payment of `amountAtomic` is allowed under both caps.
+     * Returns `{ ok: true }` if allowed, otherwise an explanatory reason.
+     */
+    check(amountAtomic: bigint): Promise<CapDecision>;
+    spentTodayAtomic(): Promise<bigint>;
+}
+//# sourceMappingURL=caps.d.ts.map

package/dist/policy/caps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caps.d.ts","sourceRoot":"","sources":["../../src/policy/caps.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,SAG1B,CAAC;AAEF,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,qBAAa,SAAS;aAEF,MAAM,EAAE,SAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADT,MAAM,EAAE,SAAS,EAChB,QAAQ,EAAE,QAAQ;IAGrC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS;IAc7C;;;OAGG;IACG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA+BjD,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;CAG1C"}

package/dist/policy/caps.js

@@ -0,0 +1,67 @@
+/**
+ * Spend caps — per-call and sliding-24-hour daily limits.
+ *
+ * Both limits are atomic USDC (`bigint`, 6 decimals). Defaults are deliberately
+ * conservative for v0 ("safe out-of-the-box"). Override via env:
+ *   X402_PER_CALL_LIMIT=0.05      (USDC, decimal) or 50000 (atomic units)
+ *   X402_DAILY_LIMIT=1.00          ditto
+ */
+import { formatUsdcAtomic, parseUsdcLimit } from './format.js';
+export const DEFAULT_CAPS = {
+    perCallLimitAtomic: 50000n, // $0.05
+    dailyLimitAtomic: 1000000n, // $1.00
+};
+export class CapPolicy {
+    config;
+    receipts;
+    constructor(config, receipts) {
+        this.config = config;
+        this.receipts = receipts;
+    }
+    static fromEnv(receipts) {
+        return new CapPolicy({
+            perCallLimitAtomic: process.env.X402_PER_CALL_LIMIT
+                ? parseUsdcLimit(process.env.X402_PER_CALL_LIMIT)
+                : DEFAULT_CAPS.perCallLimitAtomic,
+            dailyLimitAtomic: process.env.X402_DAILY_LIMIT
+                ? parseUsdcLimit(process.env.X402_DAILY_LIMIT)
+                : DEFAULT_CAPS.dailyLimitAtomic,
+        }, receipts);
+    }
+    /**
+     * Check whether a payment of `amountAtomic` is allowed under both caps.
+     * Returns `{ ok: true }` if allowed, otherwise an explanatory reason.
+     */
+    async check(amountAtomic) {
+        if (amountAtomic <= 0n) {
+            return {
+                ok: false,
+                reason: `payment amount must be positive, got ${amountAtomic}`,
+                spentSoFarAtomic: 0n,
+            };
+        }
+        if (amountAtomic > this.config.perCallLimitAtomic) {
+            return {
+                ok: false,
+                reason: `payment of $${formatUsdcAtomic(amountAtomic)} exceeds per-call cap of ` +
+                    `$${formatUsdcAtomic(this.config.perCallLimitAtomic)} (set X402_PER_CALL_LIMIT to raise)`,
+                spentSoFarAtomic: 0n,
+            };
+        }
+        const spent = await this.receipts.spentSinceHours(24);
+        if (spent + amountAtomic > this.config.dailyLimitAtomic) {
+            return {
+                ok: false,
+                reason: `payment of $${formatUsdcAtomic(amountAtomic)} would exceed daily cap ` +
+                    `(already spent $${formatUsdcAtomic(spent)} of $${formatUsdcAtomic(this.config.dailyLimitAtomic)} ` +
+                    `in the last 24h; set X402_DAILY_LIMIT to raise)`,
+                spentSoFarAtomic: spent,
+            };
+        }
+        return { ok: true };
+    }
+    async spentTodayAtomic() {
+        return this.receipts.spentSinceHours(24);
+    }
+}
+//# sourceMappingURL=caps.js.map

package/dist/policy/caps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caps.js","sourceRoot":"","sources":["../../src/policy/caps.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ/D,MAAM,CAAC,MAAM,YAAY,GAAc;IACrC,kBAAkB,EAAE,MAAO,EAAE,QAAQ;IACrC,gBAAgB,EAAE,QAAU,EAAE,QAAQ;CACvC,CAAC;AAMF,MAAM,OAAO,SAAS;IAEF;IACC;IAFnB,YACkB,MAAiB,EAChB,QAAkB;QADnB,WAAM,GAAN,MAAM,CAAW;QAChB,aAAQ,GAAR,QAAQ,CAAU;IAClC,CAAC;IAEJ,MAAM,CAAC,OAAO,CAAC,QAAkB;QAC/B,OAAO,IAAI,SAAS,CAClB;YACE,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;gBACjD,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;gBACjD,CAAC,CAAC,YAAY,CAAC,kBAAkB;YACnC,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;gBAC5C,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;gBAC9C,CAAC,CAAC,YAAY,CAAC,gBAAgB;SAClC,EACD,QAAQ,CACT,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,YAAoB;QAC9B,IAAI,YAAY,IAAI,EAAE,EAAE,CAAC;YACvB,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,wCAAwC,YAAY,EAAE;gBAC9D,gBAAgB,EAAE,EAAE;aACrB,CAAC;QACJ,CAAC;QACD,IAAI,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;YAClD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EACJ,eAAe,gBAAgB,CAAC,YAAY,CAAC,2BAA2B;oBACxE,IAAI,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,qCAAqC;gBAC3F,gBAAgB,EAAE,EAAE;aACrB,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;QACtD,IAAI,KAAK,GAAG,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;YACxD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EACJ,eAAe,gBAAgB,CAAC,YAAY,CAAC,0BAA0B;oBACvE,mBAAmB,gBAAgB,CAAC,KAAK,CAAC,QAAQ,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,GAAG;oBACnG,iDAAiD;gBACnD,gBAAgB,EAAE,KAAK;aACxB,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/dist/policy/confirm.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Confirm policy — asks the human to approve a payment via MCP elicitation
+ * before the gateway signs it.
+ *
+ * Three modes via `X402_REQUIRE_CONFIRM`:
+ *   - `always` (default): every payment, regardless of size
+ *   - `never`: skip elicitation entirely; caps are the only gate
+ *   - a USDC amount (e.g. `0.01`): confirm only at or above that amount
+ *
+ * Fallback when the client doesn't declare elicitation capability:
+ *   - default: log a one-time warning and proceed (caps still apply)
+ *   - `X402_CONFIRM_STRICT=1`: refuse the payment instead
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export type ConfirmMode = {
+    type: 'always';
+} | {
+    type: 'never';
+} | {
+    type: 'threshold';
+    minAtomic: bigint;
+};
+export type ConfirmConfig = {
+    mode: ConfirmMode;
+    strict: boolean;
+};
+export declare const DEFAULT_CONFIRM_MODE: ConfirmMode;
+export type ConfirmDecision = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type ConfirmAskArgs = {
+    amountAtomic: bigint;
+    host: string;
+    method: string;
+    url: string;
+    todaySpentAtomic: bigint;
+    dailyCapAtomic: bigint;
+};
+export declare class ConfirmPolicy {
+    readonly config: ConfirmConfig;
+    private warnedNoElicitation;
+    constructor(config: ConfirmConfig);
+    static fromEnv(): ConfirmPolicy;
+    /** Pure decision: would a payment of this amount need a prompt? */
+    shouldConfirm(amountAtomic: bigint): boolean;
+    /**
+     * Send an elicitation if needed. Returns `{ ok: true }` to proceed,
+     * `{ ok: false, reason }` to abort. Safe to call regardless of mode —
+     * if `shouldConfirm` is false, returns ok immediately without touching
+     * the server.
+     */
+    ask(server: McpServer, args: ConfirmAskArgs): Promise<ConfirmDecision>;
+}
+//# sourceMappingURL=confirm.d.ts.map

package/dist/policy/confirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.d.ts","sourceRoot":"","sources":["../../src/policy/confirm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,WAAgC,CAAC;AAEpE,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,MAAM,cAAc,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,qBAAa,aAAa;aAGI,MAAM,EAAE,aAAa;IAFjD,OAAO,CAAC,mBAAmB,CAAS;gBAER,MAAM,EAAE,aAAa;IAEjD,MAAM,CAAC,OAAO,IAAI,aAAa;IAqB/B,mEAAmE;IACnE,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAW5C;;;;;OAKG;IACG,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;CAyD7E"}

package/dist/policy/confirm.js

@@ -0,0 +1,131 @@
+/**
+ * Confirm policy — asks the human to approve a payment via MCP elicitation
+ * before the gateway signs it.
+ *
+ * Three modes via `X402_REQUIRE_CONFIRM`:
+ *   - `always` (default): every payment, regardless of size
+ *   - `never`: skip elicitation entirely; caps are the only gate
+ *   - a USDC amount (e.g. `0.01`): confirm only at or above that amount
+ *
+ * Fallback when the client doesn't declare elicitation capability:
+ *   - default: log a one-time warning and proceed (caps still apply)
+ *   - `X402_CONFIRM_STRICT=1`: refuse the payment instead
+ */
+import { logger } from '../log.js';
+import { formatUsdcAtomic, parseUsdcLimit } from './format.js';
+export const DEFAULT_CONFIRM_MODE = { type: 'always' };
+export class ConfirmPolicy {
+    config;
+    warnedNoElicitation = false;
+    constructor(config) {
+        this.config = config;
+    }
+    static fromEnv() {
+        const raw = process.env.X402_REQUIRE_CONFIRM?.trim().toLowerCase();
+        let mode;
+        if (raw === undefined || raw === '' || raw === 'always') {
+            mode = { type: 'always' };
+        }
+        else if (raw === 'never' || raw === 'off') {
+            mode = { type: 'never' };
+        }
+        else {
+            try {
+                const minAtomic = parseUsdcLimit(raw);
+                mode = { type: 'threshold', minAtomic };
+            }
+            catch {
+                throw new Error(`X402_REQUIRE_CONFIRM must be 'always', 'never', or a USDC amount; got "${raw}"`);
+            }
+        }
+        const strict = process.env.X402_CONFIRM_STRICT === '1';
+        return new ConfirmPolicy({ mode, strict });
+    }
+    /** Pure decision: would a payment of this amount need a prompt? */
+    shouldConfirm(amountAtomic) {
+        switch (this.config.mode.type) {
+            case 'never':
+                return false;
+            case 'always':
+                return true;
+            case 'threshold':
+                return amountAtomic >= this.config.mode.minAtomic;
+        }
+    }
+    /**
+     * Send an elicitation if needed. Returns `{ ok: true }` to proceed,
+     * `{ ok: false, reason }` to abort. Safe to call regardless of mode —
+     * if `shouldConfirm` is false, returns ok immediately without touching
+     * the server.
+     */
+    async ask(server, args) {
+        if (!this.shouldConfirm(args.amountAtomic))
+            return { ok: true };
+        const caps = server.server.getClientCapabilities();
+        const elicitationSupported = caps?.elicitation !== undefined;
+        if (!elicitationSupported) {
+            if (this.config.strict) {
+                return {
+                    ok: false,
+                    reason: "client doesn't support MCP elicitation but X402_CONFIRM_STRICT=1 is set",
+                };
+            }
+            if (!this.warnedNoElicitation) {
+                logger.warn('client does not support MCP elicitation; payments will proceed without per-call confirmation (caps still enforced)');
+                this.warnedNoElicitation = true;
+            }
+            return { ok: true };
+        }
+        let result;
+        try {
+            result = await server.server.elicitInput({
+                message: formatPrompt(args),
+                requestedSchema: {
+                    type: 'object',
+                    properties: {
+                        approve: {
+                            type: 'boolean',
+                            title: 'Approve',
+                            description: `Approve $${formatUsdcAtomic(args.amountAtomic)} USDC payment to ${args.host}?`,
+                        },
+                    },
+                    required: ['approve'],
+                },
+                task: { ttl: 30_000 },
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn('elicitation request failed', { err: msg });
+            return { ok: false, reason: `confirmation failed: ${msg}` };
+        }
+        if (result.action === 'cancel') {
+            return { ok: false, reason: 'payment cancelled by user' };
+        }
+        if (result.action === 'decline') {
+            return { ok: false, reason: 'payment declined by user' };
+        }
+        if (result.content?.approve !== true) {
+            return { ok: false, reason: 'payment declined by user' };
+        }
+        return { ok: true };
+    }
+}
+function formatPrompt(args) {
+    const path = (() => {
+        try {
+            const u = new URL(args.url);
+            return u.pathname + u.search;
+        }
+        catch {
+            return args.url;
+        }
+    })();
+    return [
+        `Confirm payment to ${args.host}`,
+        `  Amount:   $${formatUsdcAtomic(args.amountAtomic)} USDC (Base mainnet)`,
+        `  Resource: ${args.method} ${path}`,
+        `  Today:    $${formatUsdcAtomic(args.todaySpentAtomic)} of $${formatUsdcAtomic(args.dailyCapAtomic)} daily cap`,
+    ].join('\n');
+}
+//# sourceMappingURL=confirm.js.map

package/dist/policy/confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../../src/policy/confirm.ts"],"names":[],"mappings":"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"}

package/dist/policy/format.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Format helpers for atomic USDC amounts.
+ *
+ * USDC has 6 decimals: 1 USDC = 1,000,000 atomic units. We hold amounts as
+ * `bigint` of atomic units everywhere, and only format to dollars-and-cents
+ * strings at the I/O boundary (logs, error messages, MCP tool responses).
+ */
+/** Format an atomic USDC value (6 decimals) as `D.dddddd`. */
+export declare function formatUsdcAtomic(atomic: bigint): string;
+/**
+ * Parse a USDC limit string. Accepts either `0.05` (decimal USDC) or
+ * `50000` (atomic units). Returns `bigint` atomic units.
+ */
+export declare function parseUsdcLimit(raw: string): bigint;
+//# sourceMappingURL=format.d.ts.map

package/dist/policy/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/policy/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBlD"}

package/dist/policy/format.js

@@ -0,0 +1,40 @@
+/**
+ * Format helpers for atomic USDC amounts.
+ *
+ * USDC has 6 decimals: 1 USDC = 1,000,000 atomic units. We hold amounts as
+ * `bigint` of atomic units everywhere, and only format to dollars-and-cents
+ * strings at the I/O boundary (logs, error messages, MCP tool responses).
+ */
+/** Format an atomic USDC value (6 decimals) as `D.dddddd`. */
+export function formatUsdcAtomic(atomic) {
+    if (atomic < 0n)
+        return '-' + formatUsdcAtomic(-atomic);
+    const whole = atomic / 1000000n;
+    const frac = atomic % 1000000n;
+    return `${whole}.${frac.toString().padStart(6, '0')}`;
+}
+/**
+ * Parse a USDC limit string. Accepts either `0.05` (decimal USDC) or
+ * `50000` (atomic units). Returns `bigint` atomic units.
+ */
+export function parseUsdcLimit(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        throw new Error('parseUsdcLimit: empty input');
+    if (trimmed.includes('.')) {
+        const [whole, frac = ''] = trimmed.split('.');
+        if (!/^\d+$/.test(whole) || !/^\d*$/.test(frac)) {
+            throw new Error(`parseUsdcLimit: invalid decimal "${raw}"`);
+        }
+        if (frac.length > 6) {
+            throw new Error(`parseUsdcLimit: USDC has 6 decimals, "${raw}" has more`);
+        }
+        const padded = (frac + '000000').slice(0, 6);
+        return BigInt(whole) * 1000000n + BigInt(padded);
+    }
+    if (!/^\d+$/.test(trimmed)) {
+        throw new Error(`parseUsdcLimit: invalid integer "${raw}"`);
+    }
+    return BigInt(trimmed);
+}
+//# sourceMappingURL=format.js.map

package/dist/policy/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/policy/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,IAAI,MAAM,GAAG,EAAE;QAAE,OAAO,GAAG,GAAG,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,GAAG,QAAU,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,GAAG,QAAU,CAAC;IACjC,OAAO,GAAG,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACzE,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,GAAG,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,yCAAyC,GAAG,YAAY,CAAC,CAAC;QAC5E,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,QAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,GAAG,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC"}

package/dist/policy/receipts.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Receipts log — append-only JSON-lines record of every settled payment.
+ *
+ * One receipt per line keeps the file trivially inspectable and recoverable.
+ * No locking is needed because the gateway is a single-process MCP server.
+ *
+ * Default location: `<project>/.local/receipts.jsonl` (gitignored).
+ * Override with `X402_RECEIPTS_PATH` in the env.
+ */
+export declare const DEFAULT_RECEIPTS_PATH: string;
+export type Receipt = {
+    id: string;
+    ts: string;
+    host: string;
+    url: string;
+    method: string;
+    /** Atomic units of the asset, as a decimal string (e.g. "5000" = $0.005 USDC). */
+    amount_atomic: string;
+    asset: string;
+    chain: string;
+    tx_hash: string | null;
+};
+export type ReceiptInput = Omit<Receipt, 'id' | 'ts'>;
+export declare class Receipts {
+    readonly filepath: string;
+    constructor(filepath?: string);
+    static fromEnv(): Receipts;
+    record(input: ReceiptInput): Promise<Receipt>;
+    list(): Promise<Receipt[]>;
+    /** Sum of `amount_atomic` for receipts in the last `hours` window. */
+    spentSinceHours(hours: number): Promise<bigint>;
+}
+//# sourceMappingURL=receipts.d.ts.map

package/dist/policy/receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipts.d.ts","sourceRoot":"","sources":["../../src/policy/receipts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,eAAO,MAAM,qBAAqB,QAAmD,CAAC;AAEtF,MAAM,MAAM,OAAO,GAAG;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;AAEtD,qBAAa,QAAQ;aACS,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,GAAE,MAA8B;IAEpE,MAAM,CAAC,OAAO,IAAI,QAAQ;IAKpB,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAgB7C,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAoBhC,sEAAsE;IAChE,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAWtD"}