@tollxyz/guard 0.3.0 → 0.4.0

package/dist/store.js

@@ -0,0 +1,78 @@
+/**
+ * Where the guard keeps its spend counters and the x402 payment ids it has paid. The default MemorySpendStore lives in
+ * this process: it resets on restart and is not shared between processes. Pass your own SpendStore (Redis, a database)
+ * for counters that survive restarts or span several workers.
+ */
+/** the start of the UTC day holding `t` (ms) */
+export const dayStart = (t) => t - (((t % 86_400_000) + 86_400_000) % 86_400_000);
+/** an in-process SpendStore: resets on restart, not shared between processes */
+export class MemorySpendStore {
+    buckets = new Map();
+    where = new Map();
+    paid = new Map();
+    now;
+    seq = 0;
+    constructor(o = {}) {
+        this.now = o.now ?? Date.now;
+    }
+    prune(windowStart) {
+        // windows older than the previous day are dropped
+        for (const b of this.buckets.keys()) {
+            const ws = Number(b.slice(b.lastIndexOf("@") + 1));
+            if (ws < windowStart - 86_400_000)
+                this.buckets.delete(b);
+        }
+    }
+    async reserve(k, amt, limit, windowStart) {
+        // no await before the check and the write: atomic within this process
+        const bk = `${k}@${windowStart}`;
+        let b = this.buckets.get(bk);
+        if (!b) {
+            this.prune(windowStart);
+            b = { committed: 0n, pending: new Map() };
+            this.buckets.set(bk, b);
+        }
+        let used = b.committed;
+        for (const v of b.pending.values())
+            used += v;
+        if (amt < 0n || used + amt > limit)
+            return { ok: false, id: "", used };
+        const id = `r${++this.seq}`;
+        b.pending.set(id, amt);
+        this.where.set(id, bk);
+        return { ok: true, id, used: used + amt };
+    }
+    async commit(id) {
+        const bk = this.where.get(id);
+        const b = bk ? this.buckets.get(bk) : undefined;
+        this.where.delete(id);
+        const v = b?.pending.get(id);
+        if (!b || v === undefined)
+            return;
+        b.pending.delete(id);
+        b.committed += v;
+    }
+    async release(id) {
+        const bk = this.where.get(id);
+        this.where.delete(id);
+        if (bk)
+            this.buckets.get(bk)?.pending.delete(id);
+    }
+    async paymentSeen(id) {
+        const until = this.paid.get(id);
+        if (until === undefined)
+            return false;
+        if (until <= this.now()) {
+            this.paid.delete(id);
+            return false;
+        }
+        return true;
+    }
+    async markPaid(id, ttlS) {
+        const t = this.now();
+        for (const [k, until] of this.paid)
+            if (until <= t)
+                this.paid.delete(k);
+        this.paid.set(id, t + ttlS * 1000);
+    }
+}

package/dist/wallets.d.ts

@@ -28,7 +28,7 @@ export declare function guardViem<T extends object>(client: T, opts?: ViemGuardO
  * `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 declare function guardSmartAccount<T extends object>(client: T, opts?: ViemGuardOptions): T;
+export declare function guardSmartAccount<T extends object>(client: T, sopts?: ViemGuardOptions): T;
 /** the EIP-712 primary type: the one type no other type refers to (as ethers' TypedDataEncoder.getPrimaryType) */
 export declare function primaryTypeOf(types: Record<string, Array<{
     name: string;

package/dist/wallets.js

@@ -3,7 +3,7 @@
  * The wrapper is a Proxy: every other method and field of the client passes through unchanged.
  */
 import { chainIdOf, isAddress } from "./check.js";
-import { enforce, enforceCalls, gateAuthorization } from "./policy.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;
@@ -114,61 +144,57 @@ export function guardViem(client, opts = {}) {
     for (const m of ["sendTransaction", "signTransaction"]) {
         if (typeof c[m] !== "function")
             continue;
-        wrapped[m] = async (args, ...rest) => {
+        wrapped[m] = async (raw, ...rest) => {
+            const [confirm, args] = takeConfirm(raw);
             // a deployment (no `to`) goes to the unsupported policy
-            await gateTx(m, () => txInput(args, args?.data), hasAuthorizations(args), opts);
-            return c[m](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) => {
-            await gateTx("writeContract", 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);
-            }, hasAuthorizations(args), 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, ...origin }), 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) => {
-            await 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 };
-            }, opts);
-            return c.signMessage(args, ...rest);
-        };
+        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) => {
-            await enforceCalls(() => callsOf(args?.calls, chainOf(args), fromOf(args), opts), opts);
-            return c.sendCalls(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, ...rest) => {
-            await gateAuthorization("transaction", "signAuthorization", () => authInput(args, c.chain?.id, fromOf(args)), opts);
-            return c.signAuthorization(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) => {
-            await checkRequest(args, c, fromOf({}), opts);
-            return c.request(args, ...rest);
+            return guarded(opts, undefined, (o) => checkRequest(args, c, fromOf({}), { ...opts, ...o }), () => c.request(args, ...rest));
         };
     }
     return proxy(client, wrapped);
@@ -232,9 +258,9 @@ const USEROP_FIELDS = [
  * `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, opts = {}) {
+export function guardSmartAccount(client, sopts = {}) {
     const c = client;
-    const check = async (where, args) => {
+    const check = async (where, args, opts) => {
         const acct = args?.account ?? c.account;
         const sender = addrOf(acct);
         const chainId = args?.chain?.id ?? c.chain?.id;
@@ -262,10 +288,7 @@ export function guardSmartAccount(client, opts = {}) {
     for (const m of ["sendUserOperation", "prepareUserOperation"]) {
         if (typeof c[m] !== "function")
             continue;
-        wrapped[m] = async (args, ...rest) => {
-            await check(m, args);
-            return c[m](args, ...rest);
-        };
+        wrapped[m] = async (args, ...rest) => guarded(sopts, undefined, (o) => check(m, args, { ...sopts, ...o }), () => c[m](args, ...rest));
     }
     return proxy(client, wrapped);
 }
@@ -326,38 +349,38 @@ export function guardEthers(signer, opts = {}) {
     for (const m of ["sendTransaction", "signTransaction"]) {
         if (typeof s[m] !== "function")
             continue;
-        wrapped[m] = async (tx, ...rest) => {
-            await gateTx(m, () => ethersTx(s, tx), hasAuthorizations(tx), opts);
-            return s[m](tx, ...rest);
+        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 ?? {} }, ...origin }), 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) => {
-            await 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 };
-            }, opts);
-            return s.signMessage(message, ...rest);
-        };
+        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 (auth, ...rest) => {
-            await gateAuthorization("transaction", "authorize", async () => {
+            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);
-            }, opts);
-            return s.authorize(auth, ...rest);
+            };
+            return guarded(opts, undefined, (o) => gateAuthorization("transaction", "authorize", build, o), () => s.authorize(auth, ...rest));
         };
     }
     return proxy(signer, wrapped);

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.3.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. 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",