@pooriaarab/foxpay 0.0.0-stage → 0.1.0

package/dist/intent.js

@@ -0,0 +1,263 @@
+// Payment intents: check an intent, quote it on the host side, ask foxgate,
+// and run the method one time after the human approves
+// (docs/failure-modes.md I1-I17).
+import { canonicalJson, normalizeHost } from "foxgate";
+/** The foxgate tool name of every payment. Register it with `payTools()`. */
+export const PAY_TOOL = "foxpay.pay";
+/**
+ * foxgate takes 3-letter currency codes. Test USDC on Base Sepolia counts as
+ * XTS, the ISO 4217 code for testing, in whole atomic units (6 decimals).
+ */
+export const GATE_CURRENCY = Object.freeze({ USDC: "XTS" });
+const gateCurrency = (currency) => GATE_CURRENCY[currency] ?? currency;
+/** The foxgate tool registry for foxpay. The amount comes from the quote, which foxpay puts in the args. */
+export function payTools() {
+    return {
+        [PAY_TOOL]: { scope: "pay", amount: (args) => ({ value: args.amount, currency: gateCurrency(args.currency) }) },
+    };
+}
+/** Throw it from a method to refuse with a reason that callers can switch on. From `pay`, only before any money can move. */
+export class PayRefusal extends Error {
+    reason;
+    constructor(reason, message = reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+const KEY = "foxpay";
+const INTENT_KEYS = new Set(["merchant", "amount", "currency", "reason", "method", "idempotencyKey", "target"]);
+const plain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const refused = (reason, message, id) => ({ status: "refused", ...(id && { id }), reason, message });
+const bad = (why) => {
+    throw new PayRefusal("bad-intent", `The intent is not valid: ${why}.`);
+};
+const summary = (rec) => ({ id: rec.id, merchant: rec.intent.merchant, amount: rec.quote.amount, currency: rec.quote.currency, reason: rec.intent.reason, method: rec.intent.method, payee: rec.quote.payee });
+// A method error that is not a PayRefusal can hold anything, so its message is dropped.
+async function guard(fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        throw error instanceof PayRefusal ? error : new PayRefusal("method-error", "The payment method failed.");
+    }
+}
+function parseIntent(input, methods) {
+    if (!plain(input))
+        return bad("not an object");
+    for (const k of Object.keys(input))
+        if (!INTENT_KEYS.has(k))
+            bad(`unknown field ${k}`);
+    const { merchant, amount, currency, reason, method, idempotencyKey, target } = input;
+    let host = "";
+    try {
+        host = normalizeHost(merchant);
+    }
+    catch {
+        bad("merchant must be a host name");
+    }
+    if (!Number.isSafeInteger(amount) || amount <= 0)
+        bad("amount must be a whole number of minor units above 0");
+    if (typeof currency !== "string" || !/^[A-Z]{3}$/.test(gateCurrency(currency)))
+        bad("currency must be a 3-letter code or USDC");
+    if (typeof reason !== "string" || reason.trim().length === 0 || reason.length > 200)
+        bad("reason must have 1 to 200 characters");
+    if (typeof method !== "string" || !Object.hasOwn(methods, method))
+        bad("unknown method");
+    if (typeof idempotencyKey !== "string" || idempotencyKey.length < 8 || idempotencyKey.length > 128)
+        bad("idempotencyKey must have 8 to 128 characters");
+    if (target !== undefined && !plain(target))
+        bad("target must be an object");
+    const intent = { merchant: host, amount, currency, reason, method, idempotencyKey, ...(target !== undefined && { target }) };
+    try {
+        canonicalJson(intent);
+    }
+    catch {
+        bad("not plain JSON");
+    }
+    return intent;
+}
+export function createFoxpay(options) {
+    const { gate, methods, store, onEvent } = options;
+    const now = options.now ?? Date.now;
+    let tail = Promise.resolve();
+    const locked = (fn) => {
+        const next = tail.then(fn);
+        tail = next.catch(() => undefined);
+        return next;
+    };
+    async function load() {
+        const raw = await store.get(KEY);
+        if (raw === undefined || raw === null)
+            return { v: 1, intents: {} };
+        if (!plain(raw) || raw.v !== 1 || !plain(raw.intents))
+            throw new PayRefusal("storage-error", "The stored foxpay record has a wrong shape.");
+        return raw;
+    }
+    const save = (data) => store.set(KEY, data);
+    // Intents that pay now, in this object. After a restart, "paying" means the outcome is not known.
+    const running = new Set();
+    const done = (rec) => {
+        if (rec.status !== "paying")
+            return { status: rec.status, id: rec.id, receipt: rec.receipt };
+        if (running.has(rec.id))
+            return refused("in-progress", "This intent pays now.", rec.id);
+        return refused("outcome-unknown", "A payment for this intent started, and its outcome is not known. foxpay does not pay it again.", rec.id);
+    };
+    async function emit(kind, data) {
+        try {
+            await onEvent?.({ actor: "foxpay", kind, data });
+        }
+        catch {
+            throw new PayRefusal("hook-failed", "The onEvent hook failed.");
+        }
+    }
+    // Ask foxgate about the stored action. A pending request comes back with the same id.
+    // The answer "pay" means that foxgate allowed it with no approval and counted the spend.
+    async function decide(data, rec) {
+        const decision = await gate.check(rec.action);
+        if (decision.decision === "deny") {
+            delete data.intents[rec.id];
+            await save(data);
+            await emit("pay.refused", { ...summary(rec), why: decision.reason }).catch(() => undefined);
+            return refused(decision.reason, decision.message, rec.id);
+        }
+        if (decision.decision === "ask") {
+            rec.requestId = decision.requestId;
+            data.intents[rec.id] = rec;
+            await save(data);
+            await emit("pay.ask", { ...summary(rec), requestId: decision.requestId });
+            return { status: "ask", id: rec.id, requestId: decision.requestId };
+        }
+        rec.status = "paying";
+        data.intents[rec.id] = rec;
+        await save(data);
+        running.add(rec.id);
+        await emit("pay.approved", { ...summary(rec), grantId: decision.grantId }).catch(() => undefined);
+        return "pay";
+    }
+    async function run(rec) {
+        const method = methods[rec.intent.method];
+        let outcome;
+        try {
+            outcome = await method.pay({ id: rec.id, intent: rec.intent, quote: rec.quote });
+        }
+        catch (error) {
+            // A PayRefusal is a promise that no money moved. Any other error can come
+            // after money moved, so the outcome is not known (I19).
+            outcome = error instanceof PayRefusal ? { status: "failed", reason: error.reason } : { status: "unsettled", reason: "method-error" };
+        }
+        const receipt = {
+            ...summary(rec),
+            status: outcome.status,
+            ...(outcome.reason && { failure: outcome.reason }),
+            ...(rec.requestId && { requestId: rec.requestId }),
+            paidAt: now(),
+            proof: outcome.proof ?? {},
+        };
+        return locked(async () => {
+            running.delete(rec.id);
+            // When the save fails, the store keeps "paying", so a later call refuses outcome-unknown.
+            try {
+                const data = await load();
+                data.intents[rec.id] = { ...(data.intents[rec.id] ?? rec), status: outcome.status, receipt };
+                await save(data);
+            }
+            catch {
+                // The result below is still true: the method ran.
+            }
+            // The money moved. A failed hook cannot undo that, so it does not change the result.
+            await emit("pay.result", { ...receipt }).catch(() => undefined);
+            return { status: outcome.status, id: rec.id, receipt, ...(outcome.body !== undefined && { body: outcome.body }) };
+        });
+    }
+    async function request(input) {
+        try {
+            const out = await locked(async () => {
+                const intent = parseIntent(input, methods);
+                const data = await load();
+                const id = `fpy-${intent.idempotencyKey}`;
+                const old = data.intents[id];
+                if (old) {
+                    if (canonicalJson(old.intent) !== canonicalJson(intent))
+                        return refused("key-reused", "This idempotency key belongs to a different intent.", id);
+                    if (old.status !== "awaiting")
+                        return done(old);
+                    // The grant can now allow it with no approval, so the method check runs first (I18).
+                    const check = methods[old.intent.method].check;
+                    const stop = check && (await guard(() => check({ id, intent: old.intent, quote: old.quote })));
+                    if (stop)
+                        return refused(stop, `The payment cannot run now: ${stop}.`, id);
+                    const again = await decide(data, old);
+                    return again === "pay" ? old : again;
+                }
+                await emit("pay.request", { merchant: intent.merchant, amount: intent.amount, currency: intent.currency, reason: intent.reason, method: intent.method });
+                const quote = await guard(() => methods[intent.method].quote(intent));
+                if (quote.currency !== intent.currency)
+                    return refused("currency-mismatch", `The merchant asks for ${quote.currency}, not ${intent.currency}. foxpay does not convert.`);
+                if (quote.amount !== intent.amount)
+                    return refused("amount-mismatch", `The merchant asks for ${quote.amount}, not ${intent.amount}.`);
+                const args = { intent: id, merchant: intent.merchant, amount: quote.amount, currency: quote.currency, reason: intent.reason, method: intent.method, payee: quote.payee, ...(quote.details && { details: quote.details }) };
+                const rec = { id, intent, quote, action: { tool: PAY_TOOL, scope: "pay", domain: intent.merchant, args }, status: "awaiting" };
+                const result = await decide(data, rec);
+                return result === "pay" ? rec : result;
+            });
+            return "action" in out ? run(out) : out;
+        }
+        catch (error) {
+            if (error instanceof PayRefusal)
+                return refused(error.reason, error.message);
+            return refused("storage-error", "Cannot read or save the foxpay record.");
+        }
+    }
+    async function complete(id, token) {
+        let rec;
+        try {
+            const out = await locked(async () => {
+                const data = await load();
+                const found = typeof id === "string" && Object.hasOwn(data.intents, id) ? data.intents[id] : undefined;
+                if (!found)
+                    return refused("not-found", "No intent has this id.");
+                if (found.status !== "awaiting")
+                    return done(found);
+                // The method checks the page or the vault before foxgate uses the token (I16, I17).
+                const check = methods[found.intent.method].check;
+                const stop = check && (await guard(() => check({ id, intent: found.intent, quote: found.quote })));
+                if (stop)
+                    return refused(stop, `The payment cannot run now: ${stop}.`, id);
+                await emit("pay.start", summary(found));
+                const decision = await gate.redeem(token, found.action);
+                if (decision.decision !== "allow") {
+                    const deny = decision.decision === "deny" ? decision : { reason: "bad-token", message: "The token is not valid." };
+                    return refused(deny.reason, deny.message, id);
+                }
+                found.status = "paying";
+                await save(data);
+                running.add(id);
+                await emit("pay.approved", { ...summary(found), requestId: found.requestId }).catch(() => undefined);
+                rec = found;
+                return undefined;
+            });
+            if (out)
+                return out;
+        }
+        catch (error) {
+            if (error instanceof PayRefusal)
+                return refused(error.reason, error.message, id);
+            return refused("storage-error", "Cannot read or save the foxpay record.", id);
+        }
+        // A second call at the same time sees "paying" above, so this runs one time (I8).
+        return run(rec);
+    }
+    async function list() {
+        return Object.values((await load()).intents);
+    }
+    return Object.freeze({
+        /** Check an intent, quote it, and ask foxgate. A retry with the same key gives the same answer. */
+        request,
+        /** Pay an approved intent with the foxgate token. It pays one time; later calls give the receipt. */
+        complete,
+        /** Every intent that waits, runs, or ran, with its quote and status. */
+        intents: async () => (await list()).map((r) => ({ ...summary(r), status: r.status, ...(r.requestId && { requestId: r.requestId }) })),
+        receipts: async () => (await list()).flatMap((r) => (r.receipt ? [r.receipt] : [])).toSorted((a, b) => a.paidAt - b.paidAt),
+    });
+}

package/dist/testing.d.ts

@@ -0,0 +1,52 @@
+import { type PaymentRequirements } from "./x402.js";
+export interface FakeX402Options {
+    /** The host of the API, for example `api.localhost`. */
+    host: string;
+    /** The recipient address. */
+    payTo: string;
+    /** The price in atomic USDC units (6 decimals). */
+    price: number;
+    /** The body of a paid answer. */
+    body?: string;
+    /** http for local E2E servers. Default: https. */
+    protocol?: "http:" | "https:";
+    now?: () => number;
+}
+/**
+ * A fake paid API. `handle` takes a Request and returns a Response, so a
+ * test can pass `api.fetch` to x402() and an E2E server can wrap `handle`.
+ * Change `price`, `override`, or `settle` between calls to test failures.
+ */
+export declare function fakeX402Api(options: FakeX402Options): {
+    price: number;
+    /** Fields that replace the honest requirements, for example `{ network: "eip155:8453" }`. */
+    override: Partial<PaymentRequirements> & {
+        resourceUrl?: string;
+    };
+    /** "ok" settles. The others answer success with no real settlement. */
+    settle: "ok" | "no-transaction" | "wrong-network" | "insufficient-funds";
+    /** When set, the API settles the payment and then answers with this status, as a failing proxy would. */
+    statusAfterSettle: number | null;
+    /** Settle, then answer 402 with success: false, as a payee that lies would. */
+    refuseAfterSettle: boolean;
+    /** Settle, then send a body stream that fails while it is read. */
+    breakBody: boolean;
+    /** When false, the URL answers 200 with no payment. */
+    paid: boolean;
+    /** Every request: the path and the payment header, if any. */
+    log: {
+        path: string;
+        payment: string | null;
+        status: number;
+    }[];
+    /** One entry for each settled payment. */
+    settled: {
+        payer: string;
+        value: string;
+        nonce: string;
+        transaction: string;
+    }[];
+    requirements(): PaymentRequirements;
+    handle(request: Request): Promise<Response>;
+    fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+};

package/dist/testing.js

@@ -0,0 +1,99 @@
+// Test doubles for foxpay: a fake x402 API with a local fake facilitator.
+// No chain, no money. Use them in tests and demos only.
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { recoverAuthorizer } from "./eip712.js";
+import { BASE_SEPOLIA, decodeHeader, encodeHeader } from "./x402.js";
+/**
+ * A fake paid API. `handle` takes a Request and returns a Response, so a
+ * test can pass `api.fetch` to x402() and an E2E server can wrap `handle`.
+ * Change `price`, `override`, or `settle` between calls to test failures.
+ */
+export function fakeX402Api(options) {
+    const now = options.now ?? Date.now;
+    const used = new Set();
+    const api = {
+        price: options.price,
+        /** Fields that replace the honest requirements, for example `{ network: "eip155:8453" }`. */
+        override: {},
+        /** "ok" settles. The others answer success with no real settlement. */
+        settle: "ok",
+        /** When set, the API settles the payment and then answers with this status, as a failing proxy would. */
+        statusAfterSettle: null,
+        /** Settle, then answer 402 with success: false, as a payee that lies would. */
+        refuseAfterSettle: false,
+        /** Settle, then send a body stream that fails while it is read. */
+        breakBody: false,
+        /** When false, the URL answers 200 with no payment. */
+        paid: true,
+        /** Every request: the path and the payment header, if any. */
+        log: [],
+        /** One entry for each settled payment. */
+        settled: [],
+        requirements() {
+            const { resourceUrl: _, ...rest } = api.override;
+            return { scheme: "exact", network: BASE_SEPOLIA.network, amount: String(api.price), asset: BASE_SEPOLIA.asset, payTo: options.payTo, maxTimeoutSeconds: 60, extra: { name: BASE_SEPOLIA.name, version: BASE_SEPOLIA.version }, ...rest };
+        },
+        async handle(request) {
+            const url = new URL(request.url);
+            const payment = request.headers.get("payment-signature");
+            const reply = (status, body, headers = {}) => {
+                api.log.push({ path: url.pathname, payment, status });
+                return new Response(body, { status, headers: { "access-control-allow-origin": "*", "access-control-expose-headers": "payment-required, payment-response", ...headers } });
+            };
+            if (!api.paid)
+                return reply(200, options.body ?? "ok");
+            const resource = { url: api.override.resourceUrl ?? `${options.protocol ?? "https:"}//${options.host}${url.pathname}`, description: "Fake paid API", mimeType: "text/plain" };
+            const required = (error) => reply(402, "{}", { "payment-required": encodeHeader({ x402Version: 2, error, resource, accepts: [api.requirements()] }) });
+            if (!payment)
+                return required("PAYMENT-SIGNATURE header is required");
+            const refuse = (errorReason) => reply(402, "{}", { "payment-response": encodeHeader({ success: false, errorReason, transaction: "", network: BASE_SEPOLIA.network }) });
+            let payload;
+            try {
+                payload = decodeHeader(payment);
+            }
+            catch {
+                return reply(400, "Invalid Payment");
+            }
+            // The fake facilitator: verify, then settle one time per nonce.
+            const want = api.requirements();
+            const a = payload?.payload?.authorization;
+            const got = payload?.accepted;
+            if (payload?.x402Version !== 2 || !a || !got)
+                return reply(400, "Invalid Payment");
+            if (got.network !== want.network || got.asset !== want.asset || got.payTo !== want.payTo || got.amount !== want.amount || a.value !== want.amount || a.to !== want.payTo)
+                return refuse("invalid_exact_evm_payload_mismatch");
+            const t = Math.floor(now() / 1000);
+            if (Number(a.validBefore) <= t || Number(a.validAfter) > t)
+                return refuse("invalid_exact_evm_payload_authorization_valid_before");
+            if (used.has(a.nonce.toLowerCase()))
+                return refuse("nonce_used");
+            if (api.settle === "insufficient-funds")
+                return refuse("insufficient_funds");
+            let payer;
+            try {
+                payer = recoverAuthorizer({ name: BASE_SEPOLIA.name, version: BASE_SEPOLIA.version, chainId: BASE_SEPOLIA.chainId, verifyingContract: want.asset }, a, payload.payload.signature);
+            }
+            catch {
+                return refuse("invalid_exact_evm_payload_signature");
+            }
+            if (payer !== a.from)
+                return refuse("invalid_exact_evm_payload_signature");
+            used.add(a.nonce.toLowerCase());
+            const transaction = `0x${Array.from(keccak_256(new TextEncoder().encode(a.nonce)), (b) => b.toString(16).padStart(2, "0")).join("")}`;
+            api.settled.push({ payer, value: a.value, nonce: a.nonce, transaction });
+            const settlement = { success: true, payer, network: api.settle === "wrong-network" ? "eip155:8453" : BASE_SEPOLIA.network, transaction: api.settle === "no-transaction" ? "" : transaction };
+            if (api.statusAfterSettle !== null)
+                return reply(api.statusAfterSettle, "error");
+            if (api.refuseAfterSettle)
+                return refuse("insufficient_funds");
+            if (api.breakBody) {
+                api.log.push({ path: url.pathname, payment, status: 200 });
+                const broken = new ReadableStream({ start: (c) => c.error(new Error("connection reset")) });
+                return new Response(broken, { status: 200, headers: { "payment-response": encodeHeader(settlement) } });
+            }
+            return reply(200, options.body ?? "ok", { "payment-response": encodeHeader(settlement) });
+        },
+        fetch: (input, init) => api.handle(new Request(input, init)),
+    };
+    return api;
+}

package/dist/x402.d.ts

@@ -0,0 +1,59 @@
+import type { Vault } from "foxvault";
+import { type Authorization } from "./eip712.js";
+import { type PayMethod } from "./intent.js";
+/** The only network that foxpay pays on: Base Sepolia, a testnet, with its test USDC. */
+export declare const BASE_SEPOLIA: Readonly<{
+    network: "eip155:84532";
+    chainId: 84532;
+    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+    name: "USDC";
+    version: "2";
+}>;
+export interface PaymentRequirements {
+    scheme: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: {
+        name?: string;
+        version?: string;
+    };
+}
+export interface PaymentPayload {
+    x402Version: 2;
+    resource?: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepted: PaymentRequirements;
+    payload: {
+        signature: string;
+        authorization: Authorization;
+    };
+}
+/** Base64 of the UTF-8 JSON, as the x402 HTTP headers carry it. */
+export declare function encodeHeader(value: unknown): string;
+/** The JSON in an x402 header. Throws for text that is not base64 JSON. */
+export declare function decodeHeader(text: string): unknown;
+export interface X402Options {
+    /** The foxvault vault that holds the wallet key. */
+    vault: Vault;
+    /** The handle of the wallet key: 0x and 64 hex digits. Use a testnet wallet. */
+    wallet: string;
+    /** The recipient that each merchant host must name, for example `{ "api.example.com": "0x..." }`. */
+    payTo: Record<string, string>;
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    /** Check the settlement yourself, for example on a Base Sepolia RPC node. When it says no, the receipt is `unsettled`. */
+    confirm?: (settlement: {
+        transaction: string;
+        network: string;
+        payer: string;
+    }) => Promise<boolean>;
+    /** The longest time a signed authorization stays valid. Default: 300 seconds. */
+    maxTimeoutSeconds?: number;
+    now?: () => number;
+}
+export declare function x402(options: X402Options): PayMethod;

package/dist/x402.js

@@ -0,0 +1,174 @@
+// x402 v2, scheme "exact", on Base Sepolia only: read the 402 answer, check
+// it against what the host expects, and after approval sign one EIP-3009
+// authorization with the wallet key in foxvault (docs/failure-modes.md X1-X12).
+import { normalizeHost } from "foxgate";
+import { addressOf, signAuthorization } from "./eip712.js";
+import { PayRefusal } from "./intent.js";
+/** The only network that foxpay pays on: Base Sepolia, a testnet, with its test USDC. */
+export const BASE_SEPOLIA = Object.freeze({ network: "eip155:84532", chainId: 84532, asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", name: "USDC", version: "2" });
+/** Base64 of the UTF-8 JSON, as the x402 HTTP headers carry it. */
+export function encodeHeader(value) {
+    return btoa(Array.from(new TextEncoder().encode(JSON.stringify(value)), (b) => String.fromCharCode(b)).join(""));
+}
+/** The JSON in an x402 header. Throws for text that is not base64 JSON. */
+export function decodeHeader(text) {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(atob(text), (c) => c.charCodeAt(0))));
+}
+const plain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const same = (a, b) => typeof a === "string" && a.toLowerCase() === b.toLowerCase();
+const loopback = (host) => host === "127.0.0.1" || host === "localhost" || host.endsWith(".localhost");
+const bytes32 = () => `0x${Array.from(crypto.getRandomValues(new Uint8Array(32)), (b) => b.toString(16).padStart(2, "0")).join("")}`;
+// Why one entry of `accepts` is not the payment the host expects, or undefined when it is (X1-X3, X6).
+function mismatch(r, payTo) {
+    if (r.scheme !== "exact")
+        return "scheme";
+    if (r.network !== BASE_SEPOLIA.network)
+        return "network";
+    if (!same(r.asset, BASE_SEPOLIA.asset))
+        return "asset";
+    if (!same(r.payTo, payTo))
+        return "recipient";
+    const extra = plain(r.extra) ? r.extra : {};
+    if (extra.name !== BASE_SEPOLIA.name || extra.version !== BASE_SEPOLIA.version)
+        return "token domain";
+    return undefined;
+}
+function target(intent) {
+    let url;
+    try {
+        url = new URL(String(intent.target?.url));
+    }
+    catch {
+        throw new PayRefusal("bad-target", "x402 needs target.url.");
+    }
+    // Plain http only to this machine, for local tests.
+    const ok = url.protocol === "https:" || (url.protocol === "http:" && loopback(url.hostname));
+    if (!ok || normalizeHost(url.hostname) !== intent.merchant)
+        throw new PayRefusal("merchant-mismatch", `The URL is not an https URL on ${intent.merchant}.`);
+    return url;
+}
+export function x402(options) {
+    const { vault, wallet } = options;
+    const http = options.fetch ?? ((input, init) => fetch(input, init));
+    const now = options.now ?? Date.now;
+    const maxTimeout = options.maxTimeoutSeconds ?? 300;
+    async function quote(intent) {
+        const url = target(intent);
+        const payTo = Object.hasOwn(options.payTo, intent.merchant) ? options.payTo[intent.merchant] : undefined;
+        if (!payTo)
+            throw new PayRefusal("no-recipient", `No recipient is set for ${intent.merchant}.`);
+        if (!(await vault.list()).some((s) => s.handle === wallet))
+            throw new PayRefusal("no-wallet", "The vault does not hold the wallet key.");
+        // No redirects: a signed payload must go to the approved URL only (X15).
+        const res = await http(url.href, { redirect: "manual" }).catch(() => undefined);
+        if (res?.status !== 402)
+            throw new PayRefusal("not-402", "The URL did not answer 402 Payment Required.");
+        let required;
+        try {
+            required = decodeHeader(res.headers.get("payment-required") ?? "");
+        }
+        catch {
+            throw new PayRefusal("bad-requirements", "The PAYMENT-REQUIRED header is not base64 JSON.");
+        }
+        if (!plain(required) || required.x402Version !== 2 || !Array.isArray(required.accepts))
+            throw new PayRefusal("bad-requirements", "The 402 answer is not x402 version 2.");
+        const resource = plain(required.resource) ? required.resource : {};
+        let resourceHost = "";
+        try {
+            resourceHost = normalizeHost(new URL(String(resource.url)).hostname);
+        }
+        catch {
+            throw new PayRefusal("bad-requirements", "The 402 answer has no resource URL.");
+        }
+        if (resourceHost !== intent.merchant)
+            throw new PayRefusal("merchant-mismatch", `The 402 resource is on ${resourceHost}, not ${intent.merchant}.`);
+        const accepts = required.accepts.filter(plain);
+        const fits = accepts.find((r) => mismatch(r, payTo) === undefined);
+        if (!fits)
+            throw new PayRefusal("requirements-mismatch", `The 402 answer asks for another ${accepts.map((r) => mismatch(r, payTo)).join(", ") || "payment"} than foxpay expects.`);
+        const amount = typeof fits.amount === "string" && /^[1-9]\d*$/.test(fits.amount) ? Number(fits.amount) : NaN;
+        const timeout = Number(fits.maxTimeoutSeconds);
+        if (!Number.isSafeInteger(amount) || !Number.isSafeInteger(timeout) || timeout <= 0)
+            throw new PayRefusal("bad-requirements", "The 402 amount or timeout is not a whole number that fits.");
+        const accepted = { scheme: "exact", network: BASE_SEPOLIA.network, amount: fits.amount, asset: fits.asset, payTo: fits.payTo, maxTimeoutSeconds: timeout, extra: { name: BASE_SEPOLIA.name, version: BASE_SEPOLIA.version } };
+        const hold = { url: url.href, resource: { url: String(resource.url) }, accepted };
+        return { amount, currency: "USDC", payee: `${accepted.payTo} on ${BASE_SEPOLIA.network}`, details: { url: url.href, resource: String(resource.url) }, hold };
+    }
+    // Before foxgate uses the token: the vault is open, and the 402 still asks for the approved payment (X12, X16).
+    async function check({ intent, quote: q }) {
+        if ((await vault.status()) !== "unlocked" && !(await vault.unlock().then(() => true, () => false)))
+            return "locked";
+        const { accepted } = q.hold;
+        try {
+            const now402 = await quote(intent);
+            const fresh = now402.hold.accepted;
+            return fresh.amount === accepted.amount && same(fresh.payTo, accepted.payTo) && same(fresh.asset, accepted.asset) ? undefined : "amount-changed";
+        }
+        catch (error) {
+            if (error instanceof PayRefusal)
+                return error.reason === "requirements-mismatch" ? "amount-changed" : error.reason;
+            throw error;
+        }
+    }
+    async function pay({ quote: q }) {
+        // Sign exactly the approved requirements, never fresh ones (I16, X10).
+        const { url, resource, accepted } = q.hold;
+        const t = Math.floor(now() / 1000);
+        const nonce = bytes32();
+        const domain = { name: BASE_SEPOLIA.name, version: BASE_SEPOLIA.version, chainId: BASE_SEPOLIA.chainId, verifyingContract: accepted.asset };
+        let signed;
+        try {
+            // The key exists only inside this function (X11).
+            signed = await vault.use(wallet, (key) => {
+                const authorization = { from: addressOf(key), to: accepted.payTo, value: accepted.amount, validAfter: String(t - 600), validBefore: String(t + Math.min(accepted.maxTimeoutSeconds, maxTimeout)), nonce };
+                return { authorization, signature: signAuthorization(key, domain, authorization) };
+            });
+        }
+        catch {
+            return { status: "failed", reason: "sign-error" };
+        }
+        const proof = { network: BASE_SEPOLIA.network, payer: signed.authorization.from, nonce };
+        const payload = { x402Version: 2, resource, accepted, payload: signed };
+        // One send per payload. foxpay never sends it again (X8).
+        const res = await http(url, { headers: { "payment-signature": encodeHeader(payload) }, redirect: "manual" }).catch(() => undefined);
+        if (!res)
+            return { status: "unsettled", reason: "no-response", proof };
+        // From here the payee holds a valid authorization until validBefore, so
+        // nothing below can prove that no money moved: the worst answer is
+        // "unsettled", never "failed" (X10, X14, X17, X18).
+        try {
+            return await outcome(res, proof);
+        }
+        catch {
+            return { status: "unsettled", reason: "read-error", proof };
+        }
+    }
+    async function outcome(res, proof) {
+        let settlement = {};
+        try {
+            const decoded = decodeHeader(res.headers.get("payment-response") ?? "");
+            if (plain(decoded))
+                settlement = decoded;
+        }
+        catch {
+            // No settlement header: handled below.
+        }
+        if (res.status < 200 || res.status > 299) {
+            // A refusal from the payee is its claim, not proof of no payment.
+            const why = typeof settlement.errorReason === "string" && /^[a-z0-9_]{1,64}$/.test(settlement.errorReason) ? settlement.errorReason : `http-${res.status}`;
+            return { status: "unsettled", reason: why, proof };
+        }
+        // The settlement header first: a body that fails to read does not hide a payment (X17).
+        const body = await res.text().catch(() => undefined);
+        const extra = body === undefined ? {} : { body };
+        const transaction = settlement.transaction;
+        const settled = settlement.success === true && typeof transaction === "string" && /^0x[0-9a-fA-F]{64}$/.test(transaction) && settlement.network === BASE_SEPOLIA.network;
+        if (!settled)
+            return { status: "unsettled", reason: "no-settlement", proof, ...extra };
+        const full = { ...proof, transaction: transaction };
+        if (options.confirm && !(await options.confirm(full).catch(() => false)))
+            return { status: "unsettled", reason: "not-confirmed", proof: full, ...extra };
+        return { status: "paid", proof: full, ...extra };
+    }
+    return { quote, check, pay };
+}