x402-trust-layer 5.1.0

package/dist/lib/webhooks.js

@@ -0,0 +1,123 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { db } from "./db.js";
+import { assertSafeOutboundUrl, UnsafeUrlError } from "./ssrf.js";
+const LEGACY_STORE_PATH = join(process.cwd(), "data", "webhooks.json");
+const selectActive = db.prepare("SELECT * FROM webhook_subscriptions WHERE active = 1 ORDER BY created_at DESC");
+const selectByIdFleet = db.prepare("SELECT * FROM webhook_subscriptions WHERE id = ? AND fleet_id = ?");
+const insertSub = db.prepare(`
+  INSERT INTO webhook_subscriptions (id, fleet_id, url, events, secret, created_at, active)
+  VALUES (?, ?, ?, ?, ?, ?, 1)
+`);
+const deactivateSub = db.prepare("UPDATE webhook_subscriptions SET active = 0 WHERE id = ? AND fleet_id = ?");
+function rowToSub(row) {
+    return {
+        id: row.id,
+        fleetId: row.fleet_id,
+        url: row.url,
+        events: JSON.parse(row.events),
+        secret: row.secret,
+        createdAt: row.created_at,
+        active: row.active === 1,
+    };
+}
+async function migrateLegacyOnce() {
+    const count = db.prepare("SELECT COUNT(*) AS c FROM webhook_subscriptions").get()
+        .c;
+    if (count > 0)
+        return;
+    try {
+        const raw = await readFile(LEGACY_STORE_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        for (const s of parsed.subscriptions ?? []) {
+            insertSub.run(s.id, s.fleetId, s.url, JSON.stringify(s.events), s.secret, s.createdAt);
+            if (!s.active)
+                deactivateSub.run(s.id, s.fleetId);
+        }
+    }
+    catch {
+        /* no legacy file */
+    }
+}
+function signPayload(secret, body) {
+    return `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
+}
+/** Reject SSRF targets (localhost, metadata, private IPs) for outbound webhook delivery. */
+export function assertValidWebhookUrl(url) {
+    assertSafeOutboundUrl(url);
+    if (!url.startsWith("https://")) {
+        throw new UnsafeUrlError("Webhook URL must use HTTPS");
+    }
+}
+export async function registerWebhook(input) {
+    await migrateLegacyOnce();
+    assertValidWebhookUrl(input.url);
+    const sub = {
+        id: `wh_${randomBytes(8).toString("hex")}`,
+        fleetId: input.fleetId,
+        url: input.url,
+        events: input.events,
+        secret: randomBytes(24).toString("hex"),
+        createdAt: new Date().toISOString(),
+        active: true,
+    };
+    insertSub.run(sub.id, sub.fleetId, sub.url, JSON.stringify(sub.events), sub.secret, sub.createdAt);
+    return sub;
+}
+export async function listWebhooks(fleetId) {
+    await migrateLegacyOnce();
+    const subs = selectActive.all().map(rowToSub);
+    if (!fleetId)
+        return subs;
+    return subs.filter((s) => s.fleetId === fleetId);
+}
+export async function deactivateWebhook(id, fleetId) {
+    await migrateLegacyOnce();
+    const row = selectByIdFleet.get(id, fleetId);
+    if (!row)
+        return false;
+    deactivateSub.run(id, fleetId);
+    return true;
+}
+export async function dispatchWebhooks(event, payload, fleetId) {
+    const subs = (await listWebhooks(fleetId)).filter((s) => s.events.includes(event));
+    let delivered = 0;
+    let failed = 0;
+    const body = JSON.stringify({
+        event,
+        timestamp: new Date().toISOString(),
+        ...payload,
+    });
+    await Promise.all(subs.map(async (sub) => {
+        try {
+            assertValidWebhookUrl(sub.url);
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 8_000);
+            const res = await fetch(sub.url, {
+                method: "POST",
+                redirect: "manual",
+                headers: {
+                    "content-type": "application/json",
+                    "x-trust-layer-event": event,
+                    "x-hub-signature-256": signPayload(sub.secret, body),
+                },
+                body,
+                signal: controller.signal,
+            });
+            if (res.status >= 300 && res.status < 400) {
+                failed++;
+                return;
+            }
+            clearTimeout(timer);
+            if (res.ok)
+                delivered++;
+            else
+                failed++;
+        }
+        catch {
+            failed++;
+        }
+    }));
+    return { delivered, failed };
+}

package/dist/lib/webhooks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/webhooks.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { createHmac } from "node:crypto";
+function signPayload(secret, body) {
+    return `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
+}
+describe("webhook HMAC", () => {
+    it("uses HMAC not plain hash", () => {
+        const secret = "test-secret";
+        const body = '{"event":"guard.allowed"}';
+        const sig = signPayload(secret, body);
+        expect(sig.startsWith("sha256=")).toBe(true);
+        const expected = signPayload(secret, body);
+        expect(sig).toBe(expected);
+        expect(signPayload("other", body)).not.toBe(sig);
+    });
+});

package/dist/lib/x402-client-options.d.ts

@@ -0,0 +1,28 @@
+import { type WrapFetchOptions } from "@dexterai/x402/client";
+/** Public mainnet RPC — Dexter proxy can return shapes web3.js 1.98 cannot parse */
+export declare const DEFAULT_SOLANA_RPC_URL = "https://api.mainnet-beta.solana.com";
+/**
+ * Dexter createEvmKeypairWallet() only exposes signTypedData — Base Permit2 also needs
+ * sendTransaction for the one-time USDC → Permit2 approval tx.
+ */
+export declare function createEvmPermit2CapableWallet(privateKey: string, preferredNetwork?: string): Promise<{
+    address: `0x${string}`;
+    signTypedData: (params: Parameters<(<const typedData extends import("viem").TypedData | Record<string, unknown>, primaryType extends keyof typedData | "EIP712Domain" = keyof typedData>(parameters: import("viem").TypedDataDefinition<typedData, primaryType>) => Promise<import("viem").Hex>)>[0]) => Promise<`0x${string}`>;
+    sendTransaction: (tx: {
+        to: string;
+        data?: string;
+        value?: bigint;
+    }) => Promise<`0x${string}`>;
+}>;
+/** Paid fetch with Permit2-capable EVM wallet (use instead of wrapFetch + evmPrivateKey). */
+export declare function buildX402Fetch(fetchImpl?: typeof fetch, overrides?: Partial<WrapFetchOptions>): Promise<typeof fetch>;
+/** Shared wrapFetch options for demo, scripts, and integrators */
+export declare function buildWrapFetchOptions(overrides?: Partial<WrapFetchOptions>): WrapFetchOptions;
+export declare function assertPayerKeys(): {
+    evm: boolean;
+    solana: boolean;
+};
+/**
+ * Receive wallets (PAY_TO_*) must not be used as demo payers — facilitator rejects self-payment.
+ */
+export declare function assertDemoPayerNotReceiveWallet(): Promise<void>;

package/dist/lib/x402-client-options.js

@@ -0,0 +1,138 @@
+import { createEvmKeypairWallet, createKeypairWallet, createX402Client, } from "@dexterai/x402/client";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base, polygon } from "viem/chains";
+import { CHAIN_IDS } from "./chains.js";
+const EVM_CHAIN_BY_CAIP2 = {
+    [CHAIN_IDS.base]: base,
+    [CHAIN_IDS.polygon]: polygon,
+};
+/** Public mainnet RPC — Dexter proxy can return shapes web3.js 1.98 cannot parse */
+export const DEFAULT_SOLANA_RPC_URL = "https://api.mainnet-beta.solana.com";
+function preferredPaymentNetwork() {
+    const explicit = process.env.X402_PREFERRED_NETWORK?.trim();
+    if (explicit)
+        return explicit;
+    const nets = (process.env.NETWORKS ?? process.env.NETWORK ?? "base,solana").toLowerCase();
+    if (nets.split(",").map((s) => s.trim()).includes("base")) {
+        return CHAIN_IDS.base;
+    }
+    return CHAIN_IDS.solana;
+}
+function evmRpcUrl(network) {
+    if (network === CHAIN_IDS.polygon) {
+        return process.env.POLYGON_RPC_URL?.trim() || "https://polygon-rpc.com";
+    }
+    return process.env.BASE_RPC_URL?.trim() || "https://mainnet.base.org";
+}
+/**
+ * Dexter createEvmKeypairWallet() only exposes signTypedData — Base Permit2 also needs
+ * sendTransaction for the one-time USDC → Permit2 approval tx.
+ */
+export async function createEvmPermit2CapableWallet(privateKey, preferredNetwork = CHAIN_IDS.base) {
+    const normalizedKey = privateKey.startsWith("0x") ? privateKey : `0x${privateKey}`;
+    const account = privateKeyToAccount(normalizedKey);
+    const chain = EVM_CHAIN_BY_CAIP2[preferredNetwork] ?? base;
+    const client = createWalletClient({
+        account,
+        chain,
+        transport: http(evmRpcUrl(preferredNetwork)),
+    });
+    return {
+        address: account.address,
+        signTypedData: (params) => account.signTypedData(params),
+        sendTransaction: async (tx) => {
+            return client.sendTransaction({
+                account,
+                chain,
+                to: tx.to,
+                data: tx.data,
+                value: tx.value ?? 0n,
+            });
+        },
+    };
+}
+/** Paid fetch with Permit2-capable EVM wallet (use instead of wrapFetch + evmPrivateKey). */
+export async function buildX402Fetch(fetchImpl = fetch, overrides) {
+    const opts = buildWrapFetchOptions(overrides);
+    const evmKey = process.env.EVM_PRIVATE_KEY?.trim();
+    const solKey = process.env.SOLANA_PRIVATE_KEY?.trim();
+    const wallets = {};
+    if (solKey)
+        wallets.solana = await createKeypairWallet(solKey);
+    if (evmKey) {
+        const evmNet = opts.preferredNetwork ?? CHAIN_IDS.base;
+        wallets.evm = await createEvmPermit2CapableWallet(evmKey, evmNet);
+    }
+    const client = createX402Client({
+        wallets,
+        preferredNetwork: opts.preferredNetwork,
+        rpcUrls: opts.rpcUrls,
+        maxAmountAtomic: opts.maxAmountAtomic,
+        verbose: opts.verbose,
+        fetch: fetchImpl,
+        onPaymentRequired: opts.onPaymentRequired,
+        accessPass: opts.accessPass,
+    });
+    return client.fetch.bind(client);
+}
+/** Shared wrapFetch options for demo, scripts, and integrators */
+export function buildWrapFetchOptions(overrides) {
+    const evmKey = process.env.EVM_PRIVATE_KEY?.trim();
+    const solKey = process.env.SOLANA_PRIVATE_KEY?.trim();
+    const solRpc = process.env.SOLANA_RPC_URL?.trim() || DEFAULT_SOLANA_RPC_URL;
+    const opts = {
+        rpcUrls: {
+            [CHAIN_IDS.solana]: solRpc,
+        },
+    };
+    if (solKey)
+        opts.walletPrivateKey = solKey;
+    if (evmKey)
+        opts.evmPrivateKey = evmKey;
+    if (evmKey && solKey) {
+        opts.preferredNetwork = preferredPaymentNetwork();
+    }
+    else if (evmKey) {
+        opts.preferredNetwork = CHAIN_IDS.base;
+    }
+    if (process.env.X402_VERBOSE === "1" || overrides?.verbose)
+        opts.verbose = true;
+    return { ...opts, ...overrides };
+}
+export function assertPayerKeys() {
+    const evm = !!process.env.EVM_PRIVATE_KEY?.trim();
+    const solana = !!process.env.SOLANA_PRIVATE_KEY?.trim();
+    if (!evm && !solana) {
+        throw new Error("Set EVM_PRIVATE_KEY and/or SOLANA_PRIVATE_KEY in .env (demo payer only — never commit)");
+    }
+    return { evm, solana };
+}
+/**
+ * Receive wallets (PAY_TO_*) must not be used as demo payers — facilitator rejects self-payment.
+ */
+export async function assertDemoPayerNotReceiveWallet() {
+    const payToSol = process.env.PAY_TO_ADDRESS?.trim();
+    const payToEvm = (process.env.PAY_TO_EVM?.trim() ?? "").toLowerCase();
+    const solKey = process.env.SOLANA_PRIVATE_KEY?.trim();
+    const evmKey = process.env.EVM_PRIVATE_KEY?.trim();
+    if (solKey && payToSol) {
+        const wallet = await createKeypairWallet(solKey);
+        const pubkey = wallet.publicKey;
+        if (!pubkey) {
+            throw new Error("SOLANA_PRIVATE_KEY could not be loaded — check key format");
+        }
+        const payer = pubkey.toBase58();
+        if (payer === payToSol) {
+            throw new Error(`SOLANA_PRIVATE_KEY is your seller receive wallet (${payToSol}). ` +
+                "Use a different Solana key with USDC for demo payments, or set EVM_PRIVATE_KEY to a separate Base wallet.");
+        }
+    }
+    if (evmKey && payToEvm) {
+        const wallet = await createEvmKeypairWallet(evmKey);
+        if (wallet.address.toLowerCase() === payToEvm) {
+            throw new Error(`EVM_PRIVATE_KEY is your seller receive wallet (${payToEvm}). ` +
+                "Use a different Base wallet with USDC for demo payments.");
+        }
+    }
+}

package/dist/lib/x402-headers.d.ts

@@ -0,0 +1,10 @@
+import type { Request, Response } from "express";
+/** x402 HTTP transport v2 header names (December 2025+). */
+export declare const PAYMENT_SIGNATURE = "payment-signature";
+export declare const PAYMENT_RESPONSE = "PAYMENT-RESPONSE";
+export declare const PAYMENT_REQUIRED = "PAYMENT-REQUIRED";
+/** Read client payment signature (v2 primary, v1 legacy for probes). */
+export declare function getPaymentSignatureHeader(req: Request): string | undefined;
+export declare function hasPaymentSignatureHeader(req: Request): boolean;
+/** Normalize settlement response header reads (v2 + legacy). */
+export declare function getPaymentResponseHeader(res: Response): string | undefined;

package/dist/lib/x402-headers.js

@@ -0,0 +1,27 @@
+/** x402 HTTP transport v2 header names (December 2025+). */
+export const PAYMENT_SIGNATURE = "payment-signature";
+export const PAYMENT_RESPONSE = "PAYMENT-RESPONSE";
+export const PAYMENT_REQUIRED = "PAYMENT-REQUIRED";
+/** Read client payment signature (v2 primary, v1 legacy for probes). */
+export function getPaymentSignatureHeader(req) {
+    const raw = req.headers[PAYMENT_SIGNATURE] ??
+        req.headers["x-payment"] ??
+        req.headers["x402-payment"];
+    if (typeof raw === "string")
+        return raw;
+    if (Array.isArray(raw))
+        return raw[0];
+    return undefined;
+}
+export function hasPaymentSignatureHeader(req) {
+    return Boolean(getPaymentSignatureHeader(req));
+}
+/** Normalize settlement response header reads (v2 + legacy). */
+export function getPaymentResponseHeader(res) {
+    const h = res.getHeader(PAYMENT_RESPONSE) ?? res.getHeader("payment-response");
+    if (typeof h === "string")
+        return h;
+    if (Array.isArray(h))
+        return h[0];
+    return undefined;
+}

package/dist/lib/x402-paid.d.ts

@@ -0,0 +1,5 @@
+import { x402Middleware } from "@dexterai/x402/server";
+type PaidMw = ReturnType<typeof x402Middleware>;
+/** x402 middleware with PAYMENT-REQUIRED header + Bazaar extension for Agentic Market */
+export declare function createPaidMiddleware(): (amount: string, description: string) => PaidMw;
+export {};

package/dist/lib/x402-paid.js

@@ -0,0 +1,252 @@
+import { USDC_BASE, x402Middleware } from "@dexterai/x402/server";
+import { config, isAllowedNetwork } from "../config.js";
+import { CHAIN_IDS, usdcAssetForCaip2 } from "./chains.js";
+import { bazaarExtensionForRequest } from "./bazaar-extension.js";
+import { resolvePaidResourceUrl } from "./paid-resource-url.js";
+import { getPaymentSignatureHeader, PAYMENT_REQUIRED } from "./x402-headers.js";
+import { extractNonceFromPaymentHeader, isNonceAlreadyUsed, markNonceUsed, isIdempotencyKeyConsumed, markIdempotencyKeyUsed, } from "./x402-payment-replay.js";
+import { incCounter } from "./telemetry.js";
+import { isTrustedPayTo } from "./payto-guard.js";
+import { enrichAcceptFromFacilitator, ensureFacilitatorExtras } from "./facilitator-extra.js";
+import { paymentRequestAls } from "./payment-request-context.js";
+import { guardResponseWrites, isResponseLocked, lockResponse } from "./response-guard.js";
+function resolvePayTo() {
+    if (!config.payToEvm)
+        return config.payTo;
+    const map = {
+        [CHAIN_IDS.solana]: config.payTo,
+        [CHAIN_IDS.base]: config.payToEvm,
+    };
+    for (const chain of config.chains) {
+        if (chain === "solana" || chain === "solana_devnet") {
+            map[CHAIN_IDS[chain]] = config.payTo;
+        }
+        else if (chain === "base" || chain === "polygon" || chain === "base_sepolia") {
+            map[CHAIN_IDS[chain]] = config.payToEvm;
+        }
+    }
+    return map;
+}
+function syncResourceUrl(parsed, req) {
+    const resource = parsed.resource;
+    if (resource) {
+        resource.url = resolvePaidResourceUrl(req);
+    }
+}
+const PAID_REQUEST_BUDGET_MS = Number(process.env.PAID_REQUEST_TIMEOUT_MS ?? 70_000);
+const baseMiddleware = {
+    payTo: resolvePayTo(),
+    facilitatorUrl: config.facilitatorUrl,
+    network: [...config.networks],
+    onSettlement: (info) => {
+        console.log(`[x402] settled tx=${info.transaction} payer=${info.payer} network=${info.network}`);
+    },
+};
+function withPaidRequestBudget(handler) {
+    return async (req, res, next) => {
+        guardResponseWrites(res);
+        let done = false;
+        const timer = setTimeout(() => {
+            if (done || isResponseLocked(res))
+                return;
+            console.error("[x402-paid] request budget exceeded", PAID_REQUEST_BUDGET_MS, "ms", req.path);
+            lockResponse(res);
+            res.status(504).json({
+                error: "Payment settlement or handler timed out",
+                code: "gateway_timeout",
+                budgetMs: PAID_REQUEST_BUDGET_MS,
+                hint: "Set X402_FACILITATOR_TIMEOUT_MS=25000 and X402_FACILITATOR_MAX_RETRIES=1 on Railway; or pay on Solana.",
+            });
+        }, PAID_REQUEST_BUDGET_MS);
+        try {
+            await handler(req, res, next);
+        }
+        catch (err) {
+            if (!isResponseLocked(res))
+                next(err);
+            else
+                console.error("[x402-paid] error after response locked:", err);
+        }
+        finally {
+            done = true;
+            clearTimeout(timer);
+        }
+    };
+}
+function attachBazaarToPayload(parsed, req) {
+    const bazaar = bazaarExtensionForRequest(req);
+    const extensions = parsed.extensions ?? {};
+    parsed.extensions = { ...extensions, bazaar };
+    if (parsed.x402Version == null)
+        parsed.x402Version = 2;
+}
+function normalizeAccepts(parsed) {
+    const accepts = parsed.accepts;
+    if (!Array.isArray(accepts))
+        return;
+    const chainOrder = config.chains.map((c) => CHAIN_IDS[c]);
+    for (const accept of accepts) {
+        if (!accept.network)
+            continue;
+        if (!isAllowedNetwork(accept.network))
+            continue;
+        if (accept.payTo && !isTrustedPayTo(accept.payTo))
+            continue;
+        enrichAcceptFromFacilitator(accept);
+        if (accept.network === CHAIN_IDS.base) {
+            accept.asset = USDC_BASE;
+        }
+        else if (accept.network.startsWith("solana:")) {
+            accept.asset = usdcAssetForCaip2(accept.network) ?? accept.asset;
+        }
+        else {
+            const correctAsset = usdcAssetForCaip2(accept.network);
+            if (correctAsset)
+                accept.asset = correctAsset;
+        }
+    }
+    accepts.sort((a, b) => {
+        const ia = chainOrder.indexOf(a.network ?? "");
+        const ib = chainOrder.indexOf(b.network ?? "");
+        return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+    });
+    parsed.accepts = accepts;
+}
+function injectBazaarExtension(encoded, req) {
+    try {
+        const parsed = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+        normalizeAccepts(parsed);
+        attachBazaarToPayload(parsed, req);
+        syncResourceUrl(parsed, req);
+        return Buffer.from(JSON.stringify(parsed)).toString("base64");
+    }
+    catch (err) {
+        console.error("[x402-paid] injectBazaarExtension failed:", err);
+        return encoded;
+    }
+}
+function bodyHasAccepts(body) {
+    return (!!body &&
+        typeof body === "object" &&
+        Array.isArray(body.accepts));
+}
+/** x402 middleware with PAYMENT-REQUIRED header + Bazaar extension for Agentic Market */
+export function createPaidMiddleware() {
+    return (amount, description) => {
+        const inner = x402Middleware({
+            ...baseMiddleware,
+            amount,
+            description,
+            verbose: process.env.X402_VERBOSE === "1",
+            timeoutSeconds: 120,
+            getResourceUrl: (req) => resolvePaidResourceUrl(req),
+            onSettlement: (info) => {
+                incCounter("x402_settlements");
+                const store = paymentRequestAls.getStore();
+                const pending = store?.x402PendingNonce;
+                if (pending) {
+                    void markNonceUsed(pending.nonce, pending.network).catch((err) => {
+                        console.error("[x402-paid] markNonceUsed failed:", err);
+                    });
+                }
+                if (store) {
+                    void markIdempotencyKeyUsed(store, store.path).catch((err) => {
+                        console.error("[x402-paid] idempotency mark failed:", err);
+                    });
+                }
+                baseMiddleware.onSettlement(info);
+            },
+        });
+        const paidHandler = async (req, res, next) => {
+            const paymentSig = getPaymentSignatureHeader(req);
+            if (!paymentSig) {
+                try {
+                    await ensureFacilitatorExtras();
+                }
+                catch (err) {
+                    console.warn("[x402-paid] facilitator extras cache:", err instanceof Error ? err.message : err);
+                }
+            }
+            const paymentReq = req;
+            if (paymentSig && isIdempotencyKeyConsumed(req, req.path)) {
+                incCounter("idempotency_replay");
+                res.status(409).json({
+                    error: "Idempotency-Key already fulfilled for this resource — use a new key",
+                });
+                return;
+            }
+            if (paymentSig) {
+                const { nonce, network, payTo } = extractNonceFromPaymentHeader(paymentSig);
+                if (payTo && !isTrustedPayTo(payTo)) {
+                    res.status(403).json({
+                        error: "Payment address mismatch — possible payTo redirect attack",
+                    });
+                    return;
+                }
+                if (network && !isAllowedNetwork(network)) {
+                    res.status(403).json({ error: `Network not allowed: ${network}` });
+                    return;
+                }
+                if (nonce) {
+                    if (isNonceAlreadyUsed(nonce)) {
+                        incCounter("replay_blocked");
+                        res.status(409).json({ error: "Replay attack detected: nonce already used" });
+                        return;
+                    }
+                    paymentReq.x402PendingNonce = { nonce, network: network ?? "unknown" };
+                }
+            }
+            const origJson = res.json.bind(res);
+            res.json = ((body) => {
+                if (isResponseLocked(res))
+                    return res;
+                if (body && typeof body === "object") {
+                    const payload = body;
+                    if (res.statusCode === 402 &&
+                        payload.error === "Payment settlement failed" &&
+                        payload.reason) {
+                        incCounter("x402_settlement_failures");
+                        if (!res.headersSent) {
+                            res.setHeader("Retry-After", String(process.env.SETTLEMENT_RETRY_AFTER_SEC ?? "15"));
+                        }
+                        console.error("[x402] settlement failed:", payload.reason);
+                    }
+                }
+                if (bodyHasAccepts(body)) {
+                    const payload = body;
+                    normalizeAccepts(payload);
+                    attachBazaarToPayload(payload, req);
+                    syncResourceUrl(payload, req);
+                    const message = typeof payload.error === "string" ? payload.error : "Payment required";
+                    const out = { error: message };
+                    if (typeof payload.reason === "string")
+                        out.reason = payload.reason;
+                    return origJson(out);
+                }
+                return origJson(body);
+            });
+            const origSetHeader = res.setHeader.bind(res);
+            res.setHeader = ((name, value) => {
+                if (isResponseLocked(res))
+                    return res;
+                let headerValue = value;
+                if (name.toUpperCase() === PAYMENT_REQUIRED && typeof headerValue === "string") {
+                    headerValue = injectBazaarExtension(headerValue, req);
+                }
+                return origSetHeader(name, headerValue);
+            });
+            try {
+                await paymentRequestAls.run(paymentReq, async () => {
+                    await inner(req, res, next);
+                });
+            }
+            catch (err) {
+                if (!isResponseLocked(res))
+                    next(err);
+                else
+                    console.error("[x402-paid] inner error after response locked:", err);
+            }
+        };
+        return withPaidRequestBudget(paidHandler);
+    };
+}

package/dist/lib/x402-payment-replay.d.ts

@@ -0,0 +1,22 @@
+import { extractIdempotencyKey } from "./nonce-store.js";
+export { extractIdempotencyKey };
+/** True if this nonce was already used for a successful settlement. */
+export declare function isNonceAlreadyUsed(nonce: string): boolean;
+/** Record nonce only after facilitator settlement succeeds. */
+export declare function markNonceUsed(nonce: string, network: string): Promise<void>;
+export declare function checkAndConsumeNonce(nonce: string, network: string): Promise<boolean>;
+export declare function idempotencyCompositeKey(req: {
+    headers: Record<string, unknown>;
+}, resourcePath: string): string | undefined;
+/** Block only after a prior request with this key completed settlement. */
+export declare function isIdempotencyKeyConsumed(req: {
+    headers: Record<string, unknown>;
+}, resourcePath: string): boolean;
+export declare function markIdempotencyKeyUsed(req: {
+    headers: Record<string, unknown>;
+}, resourcePath: string): Promise<void>;
+export declare function extractNonceFromPaymentHeader(header: string): {
+    nonce?: string;
+    network?: string;
+    payTo?: string;
+};