@thecryptodonkey/toll-booth 3.7.0 → 3.8.0

package/dist/core/x402-rail.js

@@ -1,7 +1,52 @@
 import { randomBytes } from 'node:crypto';
-import { DEFAULT_USDC_ASSETS } from './x402-types.js';
+import { DEFAULT_USDC_ASSETS, X402_VERSION } from './x402-types.js';
+/**
+ * Normalise an inbound x402 v2 PAYMENT-SIGNATURE payload to the flat
+ * internal X402Payment format used by the facilitator interface.
+ */
+function normaliseV2Payload(wire) {
+    const auth = wire.payload?.authorization;
+    if (!auth)
+        return undefined;
+    const amount = Number(auth.value);
+    if (!Number.isFinite(amount))
+        return undefined;
+    return {
+        signature: wire.payload.signature,
+        sender: auth.from,
+        amount,
+        network: wire.accepted?.network ?? '',
+        nonce: auth.nonce,
+    };
+}
+/**
+ * Try to parse the payment from either the v2 PAYMENT-SIGNATURE header
+ * (base64-encoded JSON) or the legacy X-Payment header (raw JSON).
+ */
+function parsePayment(req) {
+    // v2: PAYMENT-SIGNATURE (base64-encoded JSON)
+    const sigHeader = req.headers['payment-signature'];
+    if (sigHeader && sigHeader.length <= 8192) {
+        try {
+            const decoded = JSON.parse(Buffer.from(sigHeader, 'base64').toString());
+            if (decoded.x402Version >= 2)
+                return normaliseV2Payload(decoded);
+        }
+        catch { /* fall through to legacy */ }
+    }
+    // Legacy: X-Payment (raw JSON)
+    const raw = req.headers['x-payment'];
+    if (!raw || raw.length > 4096)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function createX402Rail(config) {
-    const { receiverAddress, network, asset = DEFAULT_USDC_ASSETS[network], facilitator, creditMode = true, facilitatorUrl, storage, } = config;
+    const { receiverAddress, network, asset = DEFAULT_USDC_ASSETS[network], facilitator, creditMode = true, facilitatorUrl, maxTimeoutSeconds = 3600, storage, } = config;
     return {
         type: 'x402',
         creditSupported: true,
@@ -9,13 +54,33 @@ export function createX402Rail(config) {
             return price.usd !== undefined;
         },
         detect(req) {
-            return req.headers['x-payment'] !== undefined;
+            return req.headers['payment-signature'] !== undefined
+                || req.headers['x-payment'] !== undefined;
         },
-        async challenge(_route, price) {
+        async challenge(route, price) {
+            const requirements = {
+                x402Version: X402_VERSION,
+                accepts: [{
+                        scheme: 'exact',
+                        network,
+                        amount: String(price.usd),
+                        asset: asset ?? '',
+                        payTo: receiverAddress,
+                        maxTimeoutSeconds,
+                        extra: {
+                            ...(facilitatorUrl && { facilitatorUrl }),
+                        },
+                    }],
+                resource: { url: route },
+            };
+            const encoded = Buffer.from(JSON.stringify(requirements)).toString('base64');
             return {
-                headers: { 'X-Payment-Required': 'x402' },
+                headers: {
+                    'Payment-Required': encoded,
+                },
                 body: {
                     x402: {
+                        version: X402_VERSION,
                         receiver: receiverAddress,
                         network,
                         asset,
@@ -26,20 +91,12 @@ export function createX402Rail(config) {
             };
         },
         async verify(req) {
-            const raw = req.headers['x-payment'];
-            if (!raw || raw.length > 4096) {
-                return { authenticated: false, paymentId: '', mode: 'per-request', currency: 'usd' };
-            }
-            let payload;
-            try {
-                payload = JSON.parse(raw);
-            }
-            catch {
+            const payload = parsePayment(req);
+            if (!payload) {
                 return { authenticated: false, paymentId: '', mode: 'per-request', currency: 'usd' };
             }
             // Validate required fields before passing to facilitator
-            if (typeof payload !== 'object' || payload === null ||
-                typeof payload.signature !== 'string' || !payload.signature ||
+            if (typeof payload.signature !== 'string' || !payload.signature ||
                 typeof payload.sender !== 'string' || !payload.sender ||
                 typeof payload.amount !== 'number' || !Number.isFinite(payload.amount) || payload.amount <= 0 ||
                 typeof payload.network !== 'string' || !payload.network ||

package/dist/core/x402-types.d.ts

@@ -1,3 +1,4 @@
+/** Internal normalised payment (flat structure passed to facilitator). */
 export interface X402Payment {
     signature: string;
     sender: string;
@@ -21,9 +22,49 @@ export interface X402RailConfig {
     facilitator: X402Facilitator;
     creditMode?: boolean;
     facilitatorUrl?: string;
+    /** Max seconds before payment authorisation expires. Default 3600. */
+    maxTimeoutSeconds?: number;
     /** Storage backend — required for credit mode to persist balances. Injected by Booth. */
     storage?: import('../storage/interface.js').StorageBackend;
 }
 /** Default USDC contract addresses by network */
 export declare const DEFAULT_USDC_ASSETS: Record<string, string>;
+export declare const X402_VERSION = 2;
+export interface X402PaymentRequirements {
+    scheme: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+}
+export interface X402Resource {
+    url: string;
+    description?: string;
+    mimeType?: string;
+}
+/** PAYMENT-REQUIRED header (base64-encoded JSON). */
+export interface X402ChallengeWire {
+    x402Version: number;
+    accepts: X402PaymentRequirements[];
+    resource?: X402Resource;
+}
+/** PAYMENT-SIGNATURE header (base64-encoded JSON). */
+export interface X402PaymentWire {
+    x402Version: number;
+    resource?: X402Resource;
+    accepted?: X402PaymentRequirements;
+    payload: {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+    };
+}
 //# sourceMappingURL=x402-types.d.ts.map

package/dist/core/x402-types.js

@@ -4,4 +4,6 @@ export const DEFAULT_USDC_ASSETS = {
     'base-sepolia': '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
     'polygon': '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
 };
+// ── x402 v2 wire format types ──────────────────────────────────────
+export const X402_VERSION = 2;
 //# sourceMappingURL=x402-types.js.map

package/dist/index.d.ts

@@ -25,8 +25,8 @@ export { normalisePricing, normalisePricingTable, isTieredPricing } from './core
 export { createL402Rail } from './core/l402-rail.js';
 export type { L402RailConfig } from './core/l402-rail.js';
 export { createX402Rail } from './core/x402-rail.js';
-export type { X402RailConfig, X402Facilitator, X402Payment, X402VerifyResult } from './core/x402-types.js';
-export { DEFAULT_USDC_ASSETS } from './core/x402-types.js';
+export type { X402RailConfig, X402Facilitator, X402Payment, X402VerifyResult, X402ChallengeWire, X402PaymentWire, X402PaymentRequirements } from './core/x402-types.js';
+export { DEFAULT_USDC_ASSETS, X402_VERSION } from './core/x402-types.js';
 export { createXCashuRail } from './core/xcashu-rail.js';
 export type { XCashuConfig } from './types.js';
 export { meltToLightning } from './core/melt-to-lightning.js';

package/dist/index.js

@@ -16,7 +16,7 @@ export { createWebStandardMiddleware, createWebStandardInvoiceStatusHandler, cre
 export { normalisePricing, normalisePricingTable, isTieredPricing } from './core/payment-rail.js';
 export { createL402Rail } from './core/l402-rail.js';
 export { createX402Rail } from './core/x402-rail.js';
-export { DEFAULT_USDC_ASSETS } from './core/x402-types.js';
+export { DEFAULT_USDC_ASSETS, X402_VERSION } from './core/x402-types.js';
 export { createXCashuRail } from './core/xcashu-rail.js';
 export { meltToLightning } from './core/melt-to-lightning.js';
 // Utilities

package/dist/macaroon.js

@@ -1,5 +1,14 @@
+import { randomBytes } from 'node:crypto';
 import { newMacaroon, importMacaroon } from 'macaroon';
 const LOCATION = 'toll-booth';
+/**
+ * Aperture-compatible L402 identifier layout (version 0):
+ *   [0..1]   uint16 big-endian version (0)
+ *   [2..33]  32-byte payment hash
+ *   [34..65] 32-byte random token ID
+ */
+const L402_ID_VERSION = 0;
+const L402_ID_SIZE = 66;
 const KNOWN_CAVEATS = new Set(['payment_hash', 'credit_balance', 'currency', 'route', 'expires', 'ip']);
 /** Caveat keys that encode monetary value and must not be set via the caveats parameter. */
 const RESERVED_CAVEAT_KEYS = new Set(['payment_hash', 'credit_balance', 'currency']);
@@ -16,7 +25,7 @@ const MAX_CUSTOM_CAVEATS = 16;
 export function mintMacaroon(rootKey, paymentHash, creditBalanceSats, caveats, currency) {
     const keyBytes = hexToBytes(rootKey);
     const m = newMacaroon({
-        identifier: paymentHash,
+        identifier: encodeL402Identifier(paymentHash),
         location: LOCATION,
         rootKey: keyBytes,
         version: 2,
@@ -68,13 +77,15 @@ export function verifyMacaroon(rootKey, macaroonBase64, context) {
                 return 'duplicate caveat';
             return null;
         }, []);
-        // Use the immutable identifier as the authoritative payment hash —
-        // it is set at mint time and covered by the root signature.
-        const json = m.exportJSON();
-        const identifier = json.i;
+        // Decode the aperture-compatible binary identifier to extract the
+        // payment hash.  The identifier is set at mint time and covered by
+        // the root signature, so it cannot be tampered with.
+        const paymentHash = decodeL402Identifier(m.identifier);
+        if (!paymentHash)
+            return { valid: false };
         const caveats = parseCaveats(macaroonBase64);
         // Cross-check: the payment_hash caveat must match the identifier
-        if (caveats.payment_hash && caveats.payment_hash !== identifier) {
+        if (caveats.payment_hash && caveats.payment_hash !== paymentHash) {
             return { valid: false };
         }
         if (context) {
@@ -108,7 +119,7 @@ export function verifyMacaroon(rootKey, macaroonBase64, context) {
         const currency = caveats.currency ?? 'sat';
         return {
             valid: true,
-            paymentHash: identifier,
+            paymentHash,
             creditBalance,
             currency,
             customCaveats: Object.keys(customCaveats).length > 0 ? customCaveats : undefined,
@@ -153,6 +164,22 @@ export function parseCaveats(macaroonBase64) {
     }
     return result;
 }
+function encodeL402Identifier(paymentHash) {
+    const id = new Uint8Array(L402_ID_SIZE);
+    id[0] = (L402_ID_VERSION >> 8) & 0xff;
+    id[1] = L402_ID_VERSION & 0xff;
+    id.set(hexToBytes(paymentHash), 2);
+    id.set(randomBytes(32), 34);
+    return id;
+}
+function decodeL402Identifier(id) {
+    if (id.length < L402_ID_SIZE)
+        return undefined;
+    const version = (id[0] << 8) | id[1];
+    if (version !== L402_ID_VERSION)
+        return undefined;
+    return bytesToHex(id.slice(2, 34));
+}
 function hexToBytes(hex) {
     const bytes = new Uint8Array(hex.length / 2);
     for (let i = 0; i < hex.length; i += 2) {
@@ -160,6 +187,9 @@ function hexToBytes(hex) {
     }
     return bytes;
 }
+function bytesToHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
 function uint8ToBase64(bytes) {
     return Buffer.from(bytes).toString('base64');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecryptodonkey/toll-booth",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "type": "module",
   "description": "Monetise any API with HTTP 402 payments. Payment-rail agnostic middleware for Express, Hono, Deno, Bun, and Workers.",
   "license": "MIT",