@bankofai/x402 0.5.9 → 0.6.0-beta.0

package/dist/middleware/express.js

@@ -0,0 +1,83 @@
+/**
+ * Express adapter for the x402 server middleware.
+ *
+ * Usage:
+ * ```ts
+ * import express from 'express';
+ * import { FacilitatorClient, x402Express } from '@bankofai/x402';
+ *
+ * const facilitator = new FacilitatorClient({ baseUrl: 'https://facilitator.example' });
+ * const app = express();
+ *
+ * app.use(
+ *   '/api/llm-summary',
+ *   x402Express({
+ *     facilitator,
+ *     accepts: [{
+ *       scheme: 'exact_permit',
+ *       network: 'eip155:97',
+ *       amount: '1000000',
+ *       asset: '0x...',
+ *       payTo: '0x...',
+ *     }],
+ *   }),
+ * );
+ *
+ * app.get('/api/llm-summary', (req, res) => res.json({ summary: '...' }));
+ * ```
+ *
+ * Express is imported via `peerDependencies`; consumers add it to their app.
+ */
+import { PAYMENT_SIGNATURE_HEADER, processX402Request, } from './core.js';
+/**
+ * Build an Express request handler that gates the route on x402 payment.
+ *
+ * Behavior matches the Hono adapter — see {@link X402MiddlewareConfig} and
+ * {@link processX402Request} for the underlying decision logic.
+ */
+export function x402Express(config) {
+    return async (req, res, next) => {
+        const signature = readHeader(req, PAYMENT_SIGNATURE_HEADER);
+        let decision;
+        try {
+            decision = await processX402Request(signature, config);
+        }
+        catch (err) {
+            next(err);
+            return;
+        }
+        switch (decision.kind) {
+            case 'paymentRequired':
+                for (const [k, v] of Object.entries(decision.headers)) {
+                    res.setHeader(k, v);
+                }
+                res.status(402).json(decision.paymentRequired);
+                return;
+            case 'invalid':
+                res.status(400).json({ error: decision.reason });
+                return;
+            case 'failed': {
+                const body = { error: decision.reason };
+                if (decision.transaction)
+                    body.txHash = decision.transaction;
+                if (decision.network)
+                    body.network = decision.network;
+                res.status(500).json(body);
+                return;
+            }
+            case 'allow':
+                for (const [k, v] of Object.entries(decision.headers)) {
+                    res.setHeader(k, v);
+                }
+                next();
+                return;
+        }
+    };
+}
+function readHeader(req, name) {
+    const raw = req.headers[name.toLowerCase()];
+    if (Array.isArray(raw))
+        return raw[0] ?? null;
+    return raw ?? null;
+}
+//# sourceMappingURL=express.js.map

package/dist/middleware/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/middleware/express.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,EACL,wBAAwB,EACxB,kBAAkB,GAEnB,MAAM,WAAW,CAAC;AAEnB;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAA4B;IACtD,OAAO,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QAC/D,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC;QAC5D,IAAI,QAAQ,CAAC;QACb,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,CAAC;YACV,OAAO;QACT,CAAC;QAED,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;YACtB,KAAK,iBAAiB;gBACpB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;oBACtD,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACtB,CAAC;gBACD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;gBAC/C,OAAO;YACT,KAAK,SAAS;gBACZ,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;gBACjD,OAAO;YACT,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;gBACjE,IAAI,QAAQ,CAAC,WAAW;oBAAE,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC;gBAC7D,IAAI,QAAQ,CAAC,OAAO;oBAAE,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;gBACtD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC3B,OAAO;YACT,CAAC;YACD,KAAK,OAAO;gBACV,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;oBACtD,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACtB,CAAC;gBACD,IAAI,EAAE,CAAC;gBACP,OAAO;QACX,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,GAAY,EAAE,IAAY;IAC5C,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC9C,OAAO,GAAG,IAAI,IAAI,CAAC;AACrB,CAAC"}

package/dist/middleware/hono.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hono adapter for the x402 server middleware.
+ *
+ * Usage:
+ * ```ts
+ * import { Hono } from 'hono';
+ * import { FacilitatorClient, x402Hono } from '@bankofai/x402';
+ *
+ * const facilitator = new FacilitatorClient({ baseUrl: 'https://facilitator.example' });
+ * const app = new Hono();
+ *
+ * app.use(
+ *   '/api/llm-summary',
+ *   x402Hono({
+ *     facilitator,
+ *     accepts: [{
+ *       scheme: 'exact_permit',
+ *       network: 'tron:nile',
+ *       amount: '1000000',
+ *       asset: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+ *       payTo: 'TJWdoJ...',
+ *     }],
+ *   }),
+ * );
+ *
+ * app.get('/api/llm-summary', (c) => c.json({ summary: '...' }));
+ * ```
+ *
+ * Hono is imported via `peerDependencies`; consumers add it to their app.
+ */
+import type { MiddlewareHandler } from 'hono';
+import { type X402MiddlewareConfig } from './core.js';
+/**
+ * Build a Hono middleware that gates the wrapped route on x402 payment.
+ *
+ * Behavior:
+ * - No `PAYMENT-SIGNATURE` header → respond 402 with `PAYMENT-REQUIRED` header + body.
+ * - Malformed / mismatched payload → 400 JSON error.
+ * - Verify or settle failure → 500 JSON error.
+ * - Success → call `next()` and attach `PAYMENT-RESPONSE` header to the response.
+ */
+export declare function x402Hono(config: X402MiddlewareConfig): MiddlewareHandler;
+//# sourceMappingURL=hono.d.ts.map

package/dist/middleware/hono.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/middleware/hono.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAW,iBAAiB,EAAQ,MAAM,MAAM,CAAC;AAE7D,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,WAAW,CAAC;AAEnB;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,iBAAiB,CA6BxE"}

package/dist/middleware/hono.js

@@ -0,0 +1,72 @@
+/**
+ * Hono adapter for the x402 server middleware.
+ *
+ * Usage:
+ * ```ts
+ * import { Hono } from 'hono';
+ * import { FacilitatorClient, x402Hono } from '@bankofai/x402';
+ *
+ * const facilitator = new FacilitatorClient({ baseUrl: 'https://facilitator.example' });
+ * const app = new Hono();
+ *
+ * app.use(
+ *   '/api/llm-summary',
+ *   x402Hono({
+ *     facilitator,
+ *     accepts: [{
+ *       scheme: 'exact_permit',
+ *       network: 'tron:nile',
+ *       amount: '1000000',
+ *       asset: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+ *       payTo: 'TJWdoJ...',
+ *     }],
+ *   }),
+ * );
+ *
+ * app.get('/api/llm-summary', (c) => c.json({ summary: '...' }));
+ * ```
+ *
+ * Hono is imported via `peerDependencies`; consumers add it to their app.
+ */
+import { PAYMENT_SIGNATURE_HEADER, processX402Request, } from './core.js';
+/**
+ * Build a Hono middleware that gates the wrapped route on x402 payment.
+ *
+ * Behavior:
+ * - No `PAYMENT-SIGNATURE` header → respond 402 with `PAYMENT-REQUIRED` header + body.
+ * - Malformed / mismatched payload → 400 JSON error.
+ * - Verify or settle failure → 500 JSON error.
+ * - Success → call `next()` and attach `PAYMENT-RESPONSE` header to the response.
+ */
+export function x402Hono(config) {
+    return async (c, next) => {
+        const signature = c.req.header(PAYMENT_SIGNATURE_HEADER);
+        const decision = await processX402Request(signature, config);
+        switch (decision.kind) {
+            case 'paymentRequired': {
+                for (const [k, v] of Object.entries(decision.headers)) {
+                    c.header(k, v);
+                }
+                return c.json(decision.paymentRequired, 402);
+            }
+            case 'invalid':
+                return c.json({ error: decision.reason }, 400);
+            case 'failed': {
+                const body = { error: decision.reason };
+                if (decision.transaction)
+                    body.txHash = decision.transaction;
+                if (decision.network)
+                    body.network = decision.network;
+                return c.json(body, 500);
+            }
+            case 'allow': {
+                await next();
+                for (const [k, v] of Object.entries(decision.headers)) {
+                    c.header(k, v);
+                }
+                return;
+            }
+        }
+    };
+}
+//# sourceMappingURL=hono.js.map

package/dist/middleware/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.js","sourceRoot":"","sources":["../../src/middleware/hono.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,EACL,wBAAwB,EACxB,kBAAkB,GAEnB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,MAA4B;IACnD,OAAO,KAAK,EAAE,CAAU,EAAE,IAAU,EAAE,EAAE;QACtC,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC;QACzD,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAE7D,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;YACtB,KAAK,iBAAiB,CAAC,CAAC,CAAC;gBACvB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;oBACtD,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACjB,CAAC;gBACD,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;YAC/C,CAAC;YACD,KAAK,SAAS;gBACZ,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;YACjD,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;gBACjE,IAAI,QAAQ,CAAC,WAAW;oBAAE,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC;gBAC7D,IAAI,QAAQ,CAAC,OAAO;oBAAE,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;gBACtD,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC3B,CAAC;YACD,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,IAAI,EAAE,CAAC;gBACb,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;oBACtD,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACjB,CAAC;gBACD,OAAO;YACT,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * x402 server middleware.
+ *
+ * - {@link x402Hono} — Hono adapter
+ * - {@link x402Express} — Express adapter
+ * - {@link processX402Request} — framework-agnostic core (build your own adapter)
+ */
+export { processX402Request, X402_VERSION } from './core.js';
+export type { X402Decision, X402MiddlewareConfig } from './core.js';
+export { x402Hono } from './hono.js';
+export { x402Express } from './express.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/middleware/index.js

@@ -0,0 +1,11 @@
+/**
+ * x402 server middleware.
+ *
+ * - {@link x402Hono} — Hono adapter
+ * - {@link x402Express} — Express adapter
+ * - {@link processX402Request} — framework-agnostic core (build your own adapter)
+ */
+export { processX402Request, X402_VERSION } from './core.js';
+export { x402Hono } from './hono.js';
+export { x402Express } from './express.js';
+//# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/server/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * High-level x402 server API.
+ *
+ * For framework-agnostic protocol handling, see also `src/middleware/core.ts`.
+ * {@link X402Server} sits above that — it owns mechanism registration, price
+ * parsing, anti-tamper validation, and facilitator coordination.
+ */
+export { DefaultServerMechanism, X402Server } from './x402Server.js';
+export type { BuildPaymentRequiredOptions } from './x402Server.js';
+export { PAYMENT_ONLY } from './types.js';
+export type { ResourceConfig, ServerMechanism } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACrE,YAAY,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,10 @@
+/**
+ * High-level x402 server API.
+ *
+ * For framework-agnostic protocol handling, see also `src/middleware/core.ts`.
+ * {@link X402Server} sits above that — it owns mechanism registration, price
+ * parsing, anti-tamper validation, and facilitator coordination.
+ */
+export { DefaultServerMechanism, X402Server } from './x402Server.js';
+export { PAYMENT_ONLY } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/server/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Server-side type contracts for x402 SDK.
+ *
+ * - {@link ResourceConfig} — high-level config for a protected endpoint
+ * - {@link ServerMechanism} — per-(network, scheme) plugin used by {@link X402Server}
+ */
+import type { AssetAmount } from '../tokens.js';
+import type { PaymentPermit, PaymentRequirements } from '../types/index.js';
+/**
+ * Delivery modes for a protected resource. Only `PAYMENT_ONLY` ships today;
+ * future modes (e.g. `RECEIPT_REQUIRED`) plug in here.
+ */
+export declare const PAYMENT_ONLY = "PAYMENT_ONLY";
+/**
+ * One protected endpoint's payment configuration.
+ *
+ * Mirrors Python `bankofai.x402.server.ResourceConfig`.
+ *
+ * @example
+ * ```ts
+ * const cfg: ResourceConfig = {
+ *   scheme: 'exact_permit',
+ *   network: 'tron:nile',
+ *   price: '1 USDT',
+ *   payTo: 'TJWdoJ...',
+ * };
+ * ```
+ */
+export interface ResourceConfig {
+    /** Payment scheme (`"exact"`, `"exact_permit"`, `"exact_gasfree"`, ...). */
+    scheme: string;
+    /** CAIP-2 network identifier (`"tron:nile"`, `"eip155:97"`, ...). */
+    network: string;
+    /** Human-readable price string parsed by {@link parsePrice} (e.g. `"1 USDT"`). */
+    price: string;
+    /** Recipient address. */
+    payTo: string;
+    /** Authorization validity window in seconds. Default 3600. */
+    validFor?: number;
+    /** Delivery mode. Default {@link PAYMENT_ONLY}. */
+    deliveryMode?: string;
+}
+/**
+ * Server-side mechanism interface.
+ *
+ * One instance per `(network, scheme)`. Implementations live in the
+ * mechanism packages (TRON / EVM / ...) and plug into {@link X402Server} via
+ * `register(network, mechanism)`.
+ *
+ * Mirrors Python `bankofai.x402.server.x402_server.ServerMechanism`.
+ */
+export interface ServerMechanism {
+    /** Scheme name (matches `ResourceConfig.scheme`). */
+    scheme(): string;
+    /**
+     * Resolve a `"<amount> <symbol>"` price string into a typed asset amount.
+     * The default mechanism implementation delegates to {@link parsePrice}.
+     */
+    parsePrice(price: string, network: string): Promise<AssetAmount>;
+    /**
+     * Hook to attach scheme-specific extra fields onto `PaymentRequirements`
+     * (e.g. `extra.name` / `extra.version` for permit tokens). Should return
+     * the requirements (possibly mutated, but a fresh object is preferred).
+     */
+    enhancePaymentRequirements(requirements: PaymentRequirements, deliveryMode: string): Promise<PaymentRequirements>;
+    /** Sanity check on requirements (return false to reject the config). */
+    validatePaymentRequirements(requirements: PaymentRequirements): boolean;
+    /**
+     * Optional server-side signature verification before delegating to facilitator.
+     * Defense-in-depth — facilitator also verifies, but a misbehaving client / proxy
+     * should be rejected here too. Return `true` if the signature is valid.
+     *
+     * Implementations that don't perform local verification should be omitted entirely;
+     * {@link X402Server} treats an absent method as "trust the facilitator".
+     */
+    verifySignature?(permit: PaymentPermit | null | undefined, signature: string, network: string): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,MAAM,IAAI,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACjE;;;;OAIG;IACH,0BAA0B,CACxB,YAAY,EAAE,mBAAmB,EACjC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChC,wEAAwE;IACxE,2BAA2B,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC;IACxE;;;;;;;OAOG;IACH,eAAe,CAAC,CACd,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACxC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB"}

package/dist/server/types.js

@@ -0,0 +1,12 @@
+/**
+ * Server-side type contracts for x402 SDK.
+ *
+ * - {@link ResourceConfig} — high-level config for a protected endpoint
+ * - {@link ServerMechanism} — per-(network, scheme) plugin used by {@link X402Server}
+ */
+/**
+ * Delivery modes for a protected resource. Only `PAYMENT_ONLY` ships today;
+ * future modes (e.g. `RECEIPT_REQUIRED`) plug in here.
+ */
+export const PAYMENT_ONLY = 'PAYMENT_ONLY';
+//# sourceMappingURL=types.js.map

package/dist/server/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC"}

package/dist/server/x402Server.d.ts

@@ -0,0 +1,115 @@
+/**
+ * X402Server — TypeScript port of `bankofai.x402.server.X402Server`.
+ *
+ * High-level server orchestration:
+ * - Registry of {@link ServerMechanism}s keyed by `(network, scheme)`
+ * - Build {@link PaymentRequirements} from {@link ResourceConfig} via `parsePrice`
+ *   + optional facilitator `feeQuote` enrichment for permit-style schemes
+ * - Anti-tamper validation of incoming `PaymentPayload` against server's
+ *   original requirements
+ * - Delegates `/verify` and `/settle` to a {@link FacilitatorClient}
+ *
+ * This sits **above** the framework-agnostic {@link processX402Request} core
+ * (see `src/middleware/core.ts`). Framework middleware (Hono / Express)
+ * can be wired against either:
+ * - Raw `accepts[]` + `FacilitatorClient` (lower-level, `processX402Request`)
+ * - `X402Server` + `ResourceConfig[]` (higher-level, this file)
+ */
+import type { FacilitatorClient } from '../facilitator/client.js';
+import type { PaymentPayload, PaymentRequired, PaymentRequirements, SettleResponse, VerifyResponse } from '../types/index.js';
+import { type ResourceConfig, type ServerMechanism } from './types.js';
+/** Resource info echoed back in the 402 response body. */
+export interface ResourceInfo {
+    url?: string;
+    description?: string;
+    mimeType?: string;
+}
+/** Optional overrides when building the 402 response. */
+export interface BuildPaymentRequiredOptions {
+    resource?: ResourceInfo;
+    paymentId?: string;
+    nonce?: string;
+    validAfter?: number;
+    validBefore?: number;
+}
+/**
+ * Default {@link ServerMechanism} that delegates `parsePrice` to the token
+ * registry and applies a no-op `enhancePaymentRequirements`. Useful when a
+ * chain/scheme needs no scheme-specific enrichment.
+ */
+export declare class DefaultServerMechanism implements ServerMechanism {
+    private readonly schemeName;
+    constructor(schemeName: string);
+    scheme(): string;
+    parsePrice(price: string, network: string): Promise<import("../tokens.js").AssetAmount>;
+    enhancePaymentRequirements(requirements: PaymentRequirements, _deliveryMode: string): Promise<PaymentRequirements>;
+    validatePaymentRequirements(_requirements: PaymentRequirements): boolean;
+}
+/**
+ * Core server orchestration. One instance per resource server.
+ *
+ * @example
+ * ```ts
+ * const facilitator = new FacilitatorClient({ baseUrl: 'https://fac.example' });
+ * const server = new X402Server()
+ *   .register('tron:nile', new DefaultServerMechanism('exact_permit'))
+ *   .setFacilitator(facilitator);
+ *
+ * const accepts = await server.buildPaymentRequirements([
+ *   { scheme: 'exact_permit', network: 'tron:nile', price: '1 USDT', payTo: 'T...' },
+ * ]);
+ * const challenge = server.createPaymentRequiredResponse(accepts);
+ * ```
+ */
+export declare class X402Server {
+    /** network → scheme → mechanism */
+    private readonly mechanisms;
+    private facilitator;
+    /** Register a {@link ServerMechanism} for one network. Chainable. */
+    register(network: string, mechanism: ServerMechanism): this;
+    /** Set the facilitator client. Required before {@link verifyPayment} / {@link settlePayment}. */
+    setFacilitator(client: FacilitatorClient): this;
+    /**
+     * Turn a list of {@link ResourceConfig} into ready-to-serve {@link PaymentRequirements}.
+     *
+     * Pipeline per config:
+     * 1. Find mechanism by `(network, scheme)`; throw if not registered.
+     * 2. Parse `price` → asset + amount via mechanism.
+     * 3. Build initial `PaymentRequirements`.
+     * 4. Let mechanism `enhancePaymentRequirements` attach extras (token name/version, etc.).
+     * 5. Normalize EVM addresses via checksum.
+     *
+     * If a facilitator is configured, permit-style requirements (`scheme !== 'exact'`)
+     * get enriched with `extra.fee` from `/fee/quote`. Unsupported (network, scheme, asset)
+     * tuples returned by the facilitator are silently dropped from the result.
+     *
+     * Mirrors Python `X402Server.build_payment_requirements`.
+     */
+    buildPaymentRequirements(configs: ResourceConfig[]): Promise<PaymentRequirements[]>;
+    /**
+     * Build the 402 PaymentRequired challenge body. The facilitator is not
+     * consulted here — the caller has already obtained `requirements` via
+     * {@link buildPaymentRequirements} or constructed them by hand.
+     */
+    createPaymentRequiredResponse(requirements: PaymentRequirements[], options?: BuildPaymentRequiredOptions): PaymentRequired;
+    /**
+     * Anti-tamper validation + optional server-side signature check, then
+     * delegate to the facilitator. Mirrors Python `verify_payment`.
+     */
+    verifyPayment(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /** Delegate settlement to the facilitator. Mirrors Python `settle_payment`. */
+    settlePayment(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Anti-tampering: the client's `payload.accepted` must match server's
+     * canonical `requirements`, and the embedded authorization / permit must
+     * point at the right asset / payTo / amount.
+     *
+     * Two flavors:
+     * - `exact` (ERC-3009): inspects `payload.payload.authorization`
+     * - other (permit-style): inspects `payload.payload.paymentPermit`
+     */
+    private validatePayloadMatchesRequirements;
+    private findMechanism;
+    private normalizeEvmRequirements;
+}
+//# sourceMappingURL=x402Server.d.ts.map

package/dist/server/x402Server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402Server.d.ts","sourceRoot":"","sources":["../../src/server/x402Server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAgB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAErF,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yDAAyD;AACzD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,MAAM;IAE/C,MAAM,IAAI,MAAM;IAIV,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAIzC,0BAA0B,CAC9B,YAAY,EAAE,mBAAmB,EACjC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,CAAC;IAI/B,2BAA2B,CAAC,aAAa,EAAE,mBAAmB,GAAG,OAAO;CAGzE;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IACrB,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmD;IAC9E,OAAO,CAAC,WAAW,CAAkC;IAErD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,GAAG,IAAI;IAW3D,iGAAiG;IACjG,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAK/C;;;;;;;;;;;;;;;OAeG;IACG,wBAAwB,CAC5B,OAAO,EAAE,cAAc,EAAE,GACxB,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAiEjC;;;;OAIG;IACH,6BAA6B,CAC3B,YAAY,EAAE,mBAAmB,EAAE,EACnC,OAAO,GAAE,2BAAgC,GACxC,eAAe;IAwBlB;;;OAGG;IACG,aAAa,CACjB,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC;IAqB1B,+EAA+E;IACzE,aAAa,CACjB,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC;IAW1B;;;;;;;;OAQG;IACH,OAAO,CAAC,kCAAkC;IAkD1C,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,wBAAwB;CA0BjC"}