@tollxyz/guard 0.2.0 → 0.4.0

package/dist/wallets.js

@@ -2,8 +2,8 @@
  * The wallet wrappers. Duck-typed: viem and ethers are optional peer dependencies, never imported at load time.
  * The wrapper is a Proxy: every other method and field of the client passes through unchanged.
  */
-import { isAddress } from "./check.js";
-import { enforce, gateAuthorization } from "./policy.js";
+import { chainIdOf, isAddress } from "./check.js";
+import { commitSpend, enforce, enforceCalls, gateAuthorization, releaseSpend } from "./policy.js";
 /** wraps an object's methods; everything else passes through, bound to the original */
 function proxy(target, wrapped) {
     return new Proxy(target, {
@@ -15,6 +15,36 @@ function proxy(target, wrapped) {
         },
     });
 }
+/**
+ * One wrapped call: the check, then the send. With `spend` set, the day-cap reservations the check made are committed
+ * after the send and released when the check or the send throws. `confirm` is a preview's confirmId (tollConfirm).
+ */
+async function guarded(o, confirm, check, send) {
+    if (!o.spend && confirm === undefined) {
+        await check(o);
+        return send();
+    }
+    const col = [];
+    const io = { ...o, _collect: col, ...(confirm !== undefined ? { _confirm: confirm } : {}) };
+    let out;
+    try {
+        await check(io);
+        out = await send();
+    }
+    catch (e) {
+        await releaseSpend(col, o);
+        throw e;
+    }
+    await commitSpend(col, o);
+    return out;
+}
+/** a preview's confirmId on the request (tollConfirm), and the request without it (what the wallet gets) */
+function takeConfirm(args) {
+    if (!args || typeof args !== "object" || !Object.prototype.hasOwnProperty.call(args, "tollConfirm"))
+        return [undefined, args];
+    const { tollConfirm, ...rest } = args;
+    return [typeof tollConfirm === "string" && tollConfirm ? tollConfirm : undefined, rest];
+}
 /** a transaction that carries an EIP-7702 authorizationList (any entry at all) */
 const hasAuthorizations = (tx) => {
     const l = tx?.authorizationList;
@@ -26,6 +56,32 @@ const addrOf = (account) => {
     const a = account?.address;
     return isAddress(a) ? a : undefined;
 };
+/** a chain id as a number when it can be read, else as given (the check then calls it unreadable) */
+const chainOut = (v) => (v === undefined || v === null ? undefined : (chainIdOf(v) ?? v));
+const HEXDIGITS = "0123456789abcdef";
+const bytesHex = (b) => {
+    let s = "0x";
+    for (const x of b)
+        s += HEXDIGITS[x >> 4] + HEXDIGITS[x & 15];
+    return s;
+};
+/** a text message as the bytes a wallet signs (UTF-8), hex */
+const utf8Hex = (s) => bytesHex(new TextEncoder().encode(s));
+/** the request without its authorizationList (what is checked when onAuthorization "allow" let the list through) */
+const withoutAuths = (i) => {
+    const { authorizationList: _drop, ...rest } = i;
+    return rest;
+};
+/**
+ * One transaction: when it carries an authorizationList, onAuthorization decides first ("check": one Toll check of the
+ * whole transaction with its list, fail-closed; "block": refused; "allow": the list is let through and the rest is
+ * checked as usual).
+ */
+async function gateTx(where, build, auths, o) {
+    if (auths && (await gateAuthorization("transaction", where, build, o)))
+        return;
+    await enforce("transaction", async () => withoutAuths(await build()), o);
+}
 /* ------------------------------------------------------------------ viem */
 let viemEncode = null;
 async function loadViemEncode() {
@@ -38,11 +94,38 @@ async function loadViemEncode() {
     viemEncode = m.encodeFunctionData;
     return viemEncode;
 }
+/** a batch's calls as transactions: {to, data?, value?} or a contract call {to | address, abi, functionName, args} */
+async function callsOf(calls, chainId, from, o) {
+    if (!Array.isArray(calls))
+        throw new Error("calls must be an array");
+    const out = [];
+    for (const raw of calls) {
+        const k = (raw ?? {});
+        let data = typeof k.data === "string" ? k.data : "0x";
+        if (k.abi !== undefined && typeof k.functionName === "string") {
+            const enc = o.encodeFunctionData ?? (await loadViemEncode());
+            data = String(enc({ abi: k.abi, functionName: k.functionName, args: k.args }));
+            if (typeof k.dataSuffix === "string")
+                data += k.dataSuffix.replace(/^0x/, "");
+        }
+        out.push({ chainId: chainOut(chainId), from, to: k.to ?? k.address ?? undefined, data, value: k.value ?? 0n });
+    }
+    return out;
+}
+/** a viem / EIP-7702 authorization request as Toll reads it: one entry, the signer, the chain */
+function authInput(a, chainId, from) {
+    const address = a?.contractAddress ?? a?.address;
+    const entry = { address, chainId: chainOut(a?.chainId ?? chainId) };
+    if (a?.nonce !== undefined && a?.nonce !== null)
+        entry.nonce = a.nonce;
+    return { ...(chainId !== undefined && chainId !== null ? { chainId: chainOut(chainId) } : {}), from, authorizationList: [entry] };
+}
 /**
- * Wraps a viem WalletClient: sendTransaction, writeContract, signTransaction and signTypedData ask Toll first. An
- * EIP-7702 authorization (an authorizationList on any of them, or signAuthorization) goes to onAuthorization
- * (default: blocked). Wrap last: `client.extend(...)` on the wrapped client returns an unguarded client, and the
- * account's own sign methods (client.account.sign*) are not wrapped.
+ * Wraps a viem WalletClient. Asks Toll first: sendTransaction, writeContract, signTransaction, signTypedData,
+ * signMessage, sendCalls (EIP-5792, each call), signAuthorization, and request() for eth_sendTransaction,
+ * eth_signTransaction, personal_sign, eth_sign, eth_signTypedData_v4 and wallet_sendCalls. An EIP-7702 authorization
+ * goes to onAuthorization (default "check"). Wrap last: `client.extend(...)` on the wrapped client returns an unguarded
+ * client, and the account's own sign methods (client.account.sign*) are not wrapped.
  */
 export function guardViem(client, opts = {}) {
     const c = client;
@@ -54,54 +137,161 @@ export function guardViem(client, opts = {}) {
         to: args?.to ?? undefined,
         data: data ?? "0x",
         value: args?.value ?? 0n,
+        ...(hasAuthorizations(args) ? { authorizationList: args.authorizationList } : {}),
     });
+    const origin = opts.origin !== undefined ? { origin: opts.origin } : {};
     const wrapped = {};
-    if (typeof c.sendTransaction === "function") {
-        wrapped.sendTransaction = async (args, ...rest) => {
+    for (const m of ["sendTransaction", "signTransaction"]) {
+        if (typeof c[m] !== "function")
+            continue;
+        wrapped[m] = async (raw, ...rest) => {
+            const [confirm, args] = takeConfirm(raw);
             // a deployment (no `to`) goes to the unsupported policy
-            if (hasAuthorizations(args))
-                await gateAuthorization("transaction", "sendTransaction", txInput(args, args?.data), opts);
-            await enforce("transaction", () => txInput(args, args?.data), opts);
-            return c.sendTransaction(args, ...rest);
-        };
-    }
-    if (typeof c.signTransaction === "function") {
-        wrapped.signTransaction = async (args, ...rest) => {
-            if (hasAuthorizations(args))
-                await gateAuthorization("transaction", "signTransaction", txInput(args, args?.data), opts);
-            await enforce("transaction", () => txInput(args, args?.data), opts);
-            return c.signTransaction(args, ...rest);
+            return guarded(opts, confirm, (o) => gateTx(m, () => txInput(args, args?.data), hasAuthorizations(args), o), () => c[m](args, ...rest));
         };
     }
     if (typeof c.writeContract === "function") {
-        wrapped.writeContract = async (args, ...rest) => {
-            if (hasAuthorizations(args))
-                await gateAuthorization("transaction", "writeContract", null, opts);
-            await enforce("transaction", async () => {
+        wrapped.writeContract = async (raw, ...rest) => {
+            const [confirm, args] = takeConfirm(raw);
+            const build = async () => {
                 const enc = opts.encodeFunctionData ?? (await loadViemEncode());
                 let data = String(enc({ abi: args.abi, functionName: args.functionName, args: args.args }));
                 if (typeof args.dataSuffix === "string")
                     data += args.dataSuffix.replace(/^0x/, "");
                 return txInput({ ...args, to: args.address }, data);
-            }, opts);
-            return c.writeContract(args, ...rest);
+            };
+            return guarded(opts, confirm, (o) => gateTx("writeContract", build, hasAuthorizations(args), o), () => c.writeContract(args, ...rest));
         };
     }
     if (typeof c.signTypedData === "function") {
         wrapped.signTypedData = async (args, ...rest) => {
             const td = { domain: args?.domain ?? {}, types: args?.types ?? {}, primaryType: args?.primaryType, message: args?.message ?? {} };
-            await enforce("typedData", () => ({ typedData: td }), opts);
-            return c.signTypedData(args, ...rest);
+            // the signer (0.3.1): Toll reads what the signature lets someone take from it (a Permit2 message names no owner)
+            const from = fromOf(args);
+            return guarded(opts, undefined, (o) => enforce("typedData", () => ({ typedData: td, ...(from ? { from } : {}), ...origin }), o), () => c.signTypedData(args, ...rest));
+        };
+    }
+    if (typeof c.signMessage === "function") {
+        wrapped.signMessage = async (args, ...rest) => guarded(opts, undefined, (o) => enforce("message", () => {
+            const m = args?.message;
+            const raw = m && typeof m === "object" ? m.raw : undefined;
+            const data = typeof m === "string" ? utf8Hex(m) : typeof raw === "string" ? raw : raw instanceof Uint8Array ? bytesHex(raw) : null;
+            if (data === null)
+                throw new Error("signMessage: message must be a string or {raw}");
+            const from = fromOf(args);
+            return { message: { kind: "personal_sign", data, ...(from ? { from } : {}) }, ...origin };
+        }, o), () => c.signMessage(args, ...rest));
+    }
+    if (typeof c.sendCalls === "function") {
+        wrapped.sendCalls = async (args, ...rest) => {
+            return guarded(opts, undefined, (o) => enforceCalls(() => callsOf(args?.calls, chainOf(args), fromOf(args), opts), o), () => c.sendCalls(args, ...rest));
         };
     }
     if (typeof c.signAuthorization === "function") {
-        wrapped.signAuthorization = async (...args) => {
-            await gateAuthorization("transaction", "signAuthorization", null, opts);
-            return c.signAuthorization(...args);
+        wrapped.signAuthorization = async (args, ...rest) => {
+            return guarded(opts, undefined, (o) => gateAuthorization("transaction", "signAuthorization", () => authInput(args, c.chain?.id, fromOf(args)), o), () => c.signAuthorization(args, ...rest));
+        };
+    }
+    if (typeof c.request === "function") {
+        wrapped.request = async (args, ...rest) => {
+            return guarded(opts, undefined, (o) => checkRequest(args, c, fromOf({}), { ...opts, ...o }), () => c.request(args, ...rest));
         };
     }
     return proxy(client, wrapped);
 }
+/** the wallet RPC methods that sign: each asks Toll first; every other method passes through unchecked */
+async function checkRequest(args, c, from, o) {
+    const method = args?.method;
+    const params = Array.isArray(args?.params) ? args.params : [];
+    const origin = o.origin !== undefined ? { origin: o.origin } : {};
+    switch (method) {
+        case "personal_sign":
+        case "eth_sign":
+            await enforce("message", () => ({ rpc: { method, params }, ...origin }), o);
+            return;
+        case "eth_signTypedData_v4":
+            await enforce("typedData", () => ({ rpc: { method, params }, ...origin }), o);
+            return;
+        case "eth_sendTransaction":
+        case "eth_signTransaction": {
+            const tx = (params[0] ?? {});
+            const build = () => ({
+                chainId: chainOut(tx.chainId ?? c.chain?.id),
+                from: isAddress(tx.from) ? tx.from : from,
+                to: tx.to ?? undefined,
+                data: typeof tx.data === "string" ? tx.data : typeof tx.input === "string" ? tx.input : "0x",
+                value: tx.value ?? 0,
+                ...(hasAuthorizations(tx) ? { authorizationList: tx.authorizationList } : {}),
+            });
+            await gateTx(method, build, hasAuthorizations(tx), o);
+            return;
+        }
+        case "wallet_sendCalls": {
+            const p = (params[0] ?? {});
+            await enforceCalls(() => callsOf(p.calls, p.chainId ?? c.chain?.id, isAddress(p.from) ? p.from : from, o), o);
+            return;
+        }
+        default:
+            return;
+    }
+}
+/* ------------------------------------------------------------------ ERC-4337 smart accounts (viem account abstraction) */
+/** the user-operation fields passed on to Toll as given (bigints become decimal strings) */
+const USEROP_FIELDS = [
+    "factory",
+    "factoryData",
+    "initCode",
+    "paymaster",
+    "paymasterData",
+    "paymasterAndData",
+    "paymasterVerificationGasLimit",
+    "paymasterPostOpGasLimit",
+    "callGasLimit",
+    "verificationGasLimit",
+    "preVerificationGas",
+    "maxFeePerGas",
+    "maxPriorityFeePerGas",
+    "signature",
+];
+/**
+ * Wraps a viem bundler client (account abstraction): sendUserOperation and prepareUserOperation ask Toll first.
+ * `calls` are checked one by one as transactions from the smart account's address; a ready `callData` is sent as a
+ * user operation with the account's EntryPoint. An EIP-7702 `authorization` goes to onAuthorization.
+ */
+export function guardSmartAccount(client, sopts = {}) {
+    const c = client;
+    const check = async (where, args, opts) => {
+        const acct = args?.account ?? c.account;
+        const sender = addrOf(acct);
+        const chainId = args?.chain?.id ?? c.chain?.id;
+        if (args?.authorization)
+            await gateAuthorization("userOp", where, () => authInput(args.authorization, chainId, sender), opts);
+        if (Array.isArray(args?.calls)) {
+            await enforceCalls(() => callsOf(args.calls, chainId, sender, opts), opts);
+            return;
+        }
+        await enforce("userOp", async () => {
+            if (typeof args?.callData !== "string")
+                return {};
+            let nonce = args.nonce;
+            if ((nonce === undefined || nonce === null) && typeof acct?.getNonce === "function")
+                nonce = await acct.getNonce();
+            const op = { sender: isAddress(args.sender) ? args.sender : sender, nonce: nonce ?? 0n, callData: args.callData };
+            for (const k of USEROP_FIELDS)
+                if (args[k] !== undefined && args[k] !== null)
+                    op[k] = args[k];
+            const ep = acct?.entryPoint?.address ?? args.entryPointAddress;
+            return { userOp: op, ...(isAddress(ep) ? { entryPoint: ep } : {}) };
+        }, opts);
+    };
+    const wrapped = {};
+    for (const m of ["sendUserOperation", "prepareUserOperation"]) {
+        if (typeof c[m] !== "function")
+            continue;
+        wrapped[m] = async (args, ...rest) => guarded(sopts, undefined, (o) => check(m, args, { ...sopts, ...o }), () => c[m](args, ...rest));
+    }
+    return proxy(client, wrapped);
+}
 /* ------------------------------------------------------------------ ethers v6 */
 /** the EIP-712 primary type: the one type no other type refers to (as ethers' TypedDataEncoder.getPrimaryType) */
 export function primaryTypeOf(types) {
@@ -115,6 +305,10 @@ export function primaryTypeOf(types) {
         throw new Error(roots.length ? `ambiguous primary type: ${roots.join(", ")}` : "no primary type");
     return roots[0];
 }
+async function ethersChainId(signer) {
+    const net = typeof signer.provider?.getNetwork === "function" ? await signer.provider.getNetwork() : null;
+    return net?.chainId ?? undefined;
+}
 async function ethersTx(signer, tx) {
     let to = tx?.to;
     if (to && typeof to === "object" && typeof to.getAddress === "function")
@@ -127,10 +321,8 @@ async function ethersTx(signer, tx) {
         to = r;
     }
     let chainId = tx?.chainId;
-    if (chainId === undefined || chainId === null) {
-        const net = typeof signer.provider?.getNetwork === "function" ? await signer.provider.getNetwork() : null;
-        chainId = net?.chainId ?? undefined;
-    }
+    if (chainId === undefined || chainId === null)
+        chainId = await ethersChainId(signer);
     let from = tx?.from;
     if (from && typeof from === "object" && typeof from.getAddress === "function")
         from = await from.getAddress();
@@ -142,58 +334,74 @@ async function ethersTx(signer, tx) {
         to: (to ?? undefined),
         data: typeof tx?.data === "string" ? tx.data : "0x",
         value: tx?.value ?? 0n,
+        ...(hasAuthorizations(tx) ? { authorizationList: tx.authorizationList } : {}),
     };
 }
 /**
- * Wraps an ethers v6 Signer: sendTransaction, signTransaction and signTypedData ask Toll first. An EIP-7702
- * authorization (a transaction's authorizationList, or authorize()) goes to onAuthorization (default: blocked).
- * `signer.connect(provider)` returns an unguarded signer: wrap the connected one.
+ * Wraps an ethers v6 Signer: sendTransaction, signTransaction, signTypedData, signMessage and authorize() ask Toll
+ * first. An EIP-7702 authorization (a transaction's authorizationList, or authorize()) goes to onAuthorization
+ * (default "check"). `signer.connect(provider)` returns an unguarded signer: wrap the connected one.
  */
 export function guardEthers(signer, opts = {}) {
     const s = signer;
+    const origin = opts.origin !== undefined ? { origin: opts.origin } : {};
     const wrapped = {};
-    if (typeof s.sendTransaction === "function") {
-        wrapped.sendTransaction = async (tx, ...rest) => {
-            if (hasAuthorizations(tx))
-                await gateAuthorization("transaction", "sendTransaction", null, opts);
-            await enforce("transaction", () => ethersTx(s, tx), opts);
-            return s.sendTransaction(tx, ...rest);
-        };
-    }
-    if (typeof s.signTransaction === "function") {
-        wrapped.signTransaction = async (tx, ...rest) => {
-            if (hasAuthorizations(tx))
-                await gateAuthorization("transaction", "signTransaction", null, opts);
-            await enforce("transaction", () => ethersTx(s, tx), opts);
-            return s.signTransaction(tx, ...rest);
+    for (const m of ["sendTransaction", "signTransaction"]) {
+        if (typeof s[m] !== "function")
+            continue;
+        wrapped[m] = async (raw, ...rest) => {
+            const [confirm, tx] = takeConfirm(raw);
+            return guarded(opts, confirm, (o) => gateTx(m, () => ethersTx(s, tx), hasAuthorizations(tx), o), () => s[m](tx, ...rest));
         };
     }
     if (typeof s.signTypedData === "function") {
         wrapped.signTypedData = async (domain, types, value, ...rest) => {
-            await enforce("typedData", () => ({ typedData: { domain: domain ?? {}, types: types ?? {}, primaryType: primaryTypeOf(types ?? {}), message: value ?? {} } }), opts);
-            return s.signTypedData(domain, types, value, ...rest);
+            return guarded(opts, undefined, (o) => enforce("typedData", async () => {
+                // the signer (0.3.1): Toll reads what the signature lets someone take from it (a Permit2 message names no owner)
+                const from = typeof s.getAddress === "function" ? await s.getAddress() : undefined;
+                return { typedData: { domain: domain ?? {}, types: types ?? {}, primaryType: primaryTypeOf(types ?? {}), message: value ?? {} }, ...(isAddress(from) ? { from } : {}), ...origin };
+            }, o), () => s.signTypedData(domain, types, value, ...rest));
         };
     }
+    if (typeof s.signMessage === "function") {
+        wrapped.signMessage = async (message, ...rest) => guarded(opts, undefined, (o) => enforce("message", async () => {
+            // ethers signs a string as its UTF-8 bytes, even one that looks like hex
+            const data = typeof message === "string" ? utf8Hex(message) : message instanceof Uint8Array ? bytesHex(message) : null;
+            if (data === null)
+                throw new Error("signMessage: message must be a string or bytes");
+            const from = typeof s.getAddress === "function" ? await s.getAddress() : undefined;
+            return { message: { kind: "personal_sign", data, ...(isAddress(from) ? { from } : {}) }, ...origin };
+        }, o), () => s.signMessage(message, ...rest));
+    }
     if (typeof s.authorize === "function") {
-        wrapped.authorize = async (...args) => {
-            await gateAuthorization("transaction", "authorize", null, opts);
-            return s.authorize(...args);
+        wrapped.authorize = async (auth, ...rest) => {
+            const build = async () => {
+                const chainId = chainOut(await ethersChainId(s));
+                const from = typeof s.getAddress === "function" ? await s.getAddress() : undefined;
+                return authInput(auth ?? {}, chainId, isAddress(from) ? from : undefined);
+            };
+            return guarded(opts, undefined, (o) => gateAuthorization("transaction", "authorize", build, o), () => s.authorize(auth, ...rest));
         };
     }
     return proxy(signer, wrapped);
 }
-/* ------------------------------------------------------------------ either */
+/* ------------------------------------------------------------------ any */
 /** true for a viem WalletClient (has `extend` and `request`), false for an ethers Signer */
 export const isViemClient = (x) => !!x && typeof x.extend === "function" && typeof x.request === "function";
+/** true for a viem bundler client (account abstraction): it has sendUserOperation */
+export const isBundlerClient = (x) => !!x && typeof x.sendUserOperation === "function";
 /**
- * Puts Toll's pre-sign check in front of a wallet. A viem WalletClient or an ethers v6 Signer; the wrapped wallet has
- * the same type and methods.
+ * Puts Toll's pre-sign check in front of a wallet: a viem bundler client (smart account), a viem WalletClient or an
+ * ethers v6 Signer; the wrapped wallet has the same type and methods.
  */
 export function guard(wallet, opts = {}) {
+    // a bundler client is also a viem client: it is detected first
+    if (isBundlerClient(wallet))
+        return guardSmartAccount(wallet, opts);
     if (isViemClient(wallet))
         return guardViem(wallet, opts);
     if (typeof wallet.getAddress === "function" && (typeof wallet.sendTransaction === "function" || typeof wallet.signTypedData === "function")) {
         return guardEthers(wallet, opts);
     }
-    throw new TypeError("guard(): pass a viem WalletClient or an ethers v6 Signer (or use guardViem / guardEthers).");
+    throw new TypeError("guard(): pass a viem WalletClient, a viem bundler client or an ethers v6 Signer (or use guardViem / guardSmartAccount / guardEthers).");
 }

package/dist/x402.d.ts

@@ -14,9 +14,21 @@ export declare function readPaymentForms(res: Response): Promise<{
 export declare function readPaymentRequired(res: Response): Promise<PR | null>;
 /** true when the header and the body would pay differently (a payee, amount, asset or scheme in one and not the other) */
 export declare function paymentFormsDiffer(header: PR, body: PR): boolean;
+/**
+ * The x402 payment-identifier extension's id in a signed payment header (base64 JSON PaymentPayload):
+ * extensions["payment-identifier"].info.id (or .id); null when there is none.
+ */
+export declare function paymentIdOf(header: string | null): string | null;
 export interface X402GuardOptions extends GuardOptions {
     /** called with each 402's report (also passed to onReport) */
     on402?: (report: GuardReport, url: string) => void;
+    /**
+     * With `spend`: how long a checked 402's cap reservation waits for its paid retry before it is given back
+     * (default 120000 ms). The paid retry commits it on a non-402 answer and releases it on a 402 or an error.
+     */
+    holdMs?: number;
+    /** With `spend`: how long a paid payment-identifier is remembered (default 86400 s) */
+    paymentIdTtlS?: number;
 }
 /**
  * Wraps a fetch so every 402 is checked by Toll before an x402 client pays it. A 402 to a request that already

package/dist/x402.js

@@ -1,4 +1,4 @@
-import { enforce, refuse } from "./policy.js";
+import { commitSpend, enforce, policyRefuse, refuse, releaseSpend, storeOf } from "./policy.js";
 function decodeBase64Json(value) {
     const bin = atob(value.trim());
     return JSON.parse(new TextDecoder().decode(Uint8Array.from(bin, (c) => c.charCodeAt(0))));
@@ -59,19 +59,51 @@ const urlOf = (input) => {
     return typeof u === "string" ? u : String(input);
 };
 const PAY_HEADERS = ["payment-signature", "x-payment"];
-const hasPayment = (input, init) => {
+/** the payment header's value on the request (init headers first, then a Request's own), or null */
+const paymentHeader = (input, init) => {
     const read = (h) => {
         if (!h)
-            return false;
+            return null;
         try {
             const hs = new Headers(h);
-            return PAY_HEADERS.some((n) => hs.has(n));
+            for (const n of PAY_HEADERS)
+                if (hs.has(n))
+                    return hs.get(n) ?? "";
         }
         catch {
-            return false;
+            /* unreadable headers */
         }
+        return null;
     };
-    return read(init?.headers) || (typeof Request !== "undefined" && input instanceof Request && read(input.headers));
+    return read(init?.headers) ?? (typeof Request !== "undefined" && input instanceof Request ? read(input.headers) : null);
+};
+const hasPayment = (input, init) => paymentHeader(input, init) !== null;
+/**
+ * The x402 payment-identifier extension's id in a signed payment header (base64 JSON PaymentPayload):
+ * extensions["payment-identifier"].info.id (or .id); null when there is none.
+ */
+export function paymentIdOf(header) {
+    if (!header)
+        return null;
+    try {
+        const p = decodeBase64Json(header);
+        const ext = p?.extensions?.["payment-identifier"] ?? p?.payload?.extensions?.["payment-identifier"];
+        const id = ext?.info?.id ?? ext?.id ?? p?.paymentId;
+        return typeof id === "string" && id ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** the request URL without its query: the key a 402's hold waits under for its paid retry */
+const holdKey = (url) => {
+    try {
+        const u = new URL(url);
+        return u.origin + u.pathname;
+    }
+    catch {
+        return url;
+    }
 };
 /**
  * Wraps a fetch so every 402 is checked by Toll before an x402 client pays it. A 402 to a request that already
@@ -79,7 +111,97 @@ const hasPayment = (input, init) => {
  */
 export function guardX402Fetch(fetchLike, opts = {}) {
     const toll = { ...opts, fetch: opts.fetch ?? globalThis.fetch?.bind(globalThis) };
+    // spend mode: each checked 402's reservations wait here (oldest first per URL) for the paid retry
+    const holds = new Map();
+    const takeHold = (key) => {
+        const q = holds.get(key);
+        const h = q?.shift();
+        if (q && !q.length)
+            holds.delete(key);
+        if (h)
+            clearTimeout(h.timer);
+        return h ?? null;
+    };
+    // payment ids being sent right now, and the hold each id keeps across a retry after a network error
+    const inFlight = new Set();
+    const idHolds = new Map();
+    const keepForRetry = (id, reports) => {
+        const timer = setTimeout(() => {
+            if (idHolds.get(id)?.reports === reports) {
+                idHolds.delete(id);
+                void releaseSpend(reports, toll);
+            }
+        }, opts.holdMs ?? 120_000);
+        timer.unref?.();
+        idHolds.set(id, { reports, timer });
+    };
+    /**
+     * A paid request. With an x402 payment-identifier: an id the seller already accepted (non-402 answer) is refused,
+     * and so is a second send of an id still in flight; after a network error the same id may be sent again (the
+     * seller dedupes it) and it reuses the cap reservation of its 402, so nothing is counted twice.
+     */
+    const paidRetry = async (input, init, header) => {
+        const url = urlOf(input);
+        const id = paymentIdOf(header);
+        const store = storeOf(toll);
+        if (id !== null) {
+            if (await store.paymentSeen(id)) {
+                await policyRefuse("x402", { x402: { url } }, "duplicate-payment", `Not paid: payment-identifier ${id} was already paid; the guard never pays it twice.`, toll);
+            }
+            // checked after the await, right before the mark: no other send of this id can slip in between
+            if (inFlight.has(id)) {
+                await policyRefuse("x402", { x402: { url } }, "duplicate-payment", `Not paid: payment-identifier ${id} is being sent right now; the guard never sends it twice at once.`, toll);
+            }
+            inFlight.add(id);
+        }
+        let hold = null;
+        if (id !== null && idHolds.has(id)) {
+            const h = idHolds.get(id);
+            clearTimeout(h.timer);
+            idHolds.delete(id);
+            hold = h;
+        }
+        else
+            hold = takeHold(holdKey(url));
+        let res;
+        try {
+            res = await fetchLike(input, init);
+        }
+        catch (e) {
+            if (id !== null) {
+                // no answer: the seller may not have it; the same id may be retried and keeps this reservation
+                inFlight.delete(id);
+                if (hold)
+                    keepForRetry(id, hold.reports);
+            }
+            else if (hold)
+                await releaseSpend(hold.reports, toll);
+            throw e;
+        }
+        try {
+            if (res.status === 402) {
+                if (hold)
+                    await releaseSpend(hold.reports, toll);
+            }
+            else {
+                if (hold)
+                    await commitSpend(hold.reports, toll);
+                if (id !== null)
+                    await store.markPaid(id, opts.paymentIdTtlS ?? 86_400);
+            }
+        }
+        finally {
+            if (id !== null)
+                inFlight.delete(id);
+        }
+        return res;
+    };
     const wrapped = async (input, init) => {
+        if (toll.spend) {
+            const header = paymentHeader(input, init);
+            if (header !== null)
+                return paidRetry(input, init, header);
+        }
         const res = await fetchLike(input, init);
         if (res.status !== 402 || hasPayment(input, init))
             return res;
@@ -91,13 +213,32 @@ export function guardX402Fetch(fetchLike, opts = {}) {
             await refuse("x402", { x402: { ...forms.header, url } }, "x402-forms-differ", "The 402's PAYMENT-REQUIRED header and its JSON body ask for different payments (payee, amount, asset or scheme). A client pays from the one it reads, so it was not paid.", toll);
         }
         const pr = forms.header ?? forms.body;
+        const col = [];
+        const eo = toll.spend ? { ...toll, _collect: col, _endpoint: url } : toll;
         const r = await enforce("x402", () => {
             if (!pr)
                 return {}; // nothing readable: the unsupported policy decides
             const x402 = pr.resource || pr.url ? pr : { ...pr, url };
             const id = typeof opts.agentId === "function" ? opts.agentId(url) : opts.agentId;
             return { x402, ...(id !== undefined && id !== null ? { agentId: id } : {}) };
-        }, toll);
+        }, eo);
+        if (col.some((c) => c.spend?.reservations.length)) {
+            const key = holdKey(url);
+            const entry = { reports: col, timer: setTimeout(() => {
+                    const q = holds.get(key);
+                    const i = q ? q.indexOf(entry) : -1;
+                    if (q && i >= 0) {
+                        q.splice(i, 1);
+                        if (!q.length)
+                            holds.delete(key);
+                        void releaseSpend(col, toll);
+                    }
+                }, opts.holdMs ?? 120_000) };
+            entry.timer.unref?.();
+            const q = holds.get(key) ?? [];
+            q.push(entry);
+            holds.set(key, q);
+        }
         opts.on402?.(r, url);
         return res;
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tollxyz/guard",
-  "version": "0.2.0",
-  "description": "Toll's live pre-sign check in front of an AI agent's wallet: viem, ethers and x402 fetch wrappers that ask Toll (ALLOW / WARN / BLOCK, ERC-8265) before anything is signed on Robinhood Chain. Zero runtime dependencies.",
+  "version": "0.4.0",
+  "description": "Toll's live pre-sign check in front of an AI agent's wallet: viem, viem smart-account, ethers and x402 fetch wrappers that ask Toll (ALLOW / WARN / BLOCK, ERC-8265) before anything is signed on Robinhood Chain: transactions, messages, typed data, batches, user operations, EIP-7702 authorizations. Spend caps, allowlists and human approval around the verdict. Zero runtime dependencies.",
   "license": "MIT",
   "author": "Toll",
   "type": "module",