@tollxyz/guard 0.3.0 → 0.4.1

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.1",
+  "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; single-use ALLOW tickets for contracts that require one. Zero runtime dependencies.",
   "license": "MIT",
   "author": "Toll",
   "type": "module",
@@ -37,6 +37,7 @@
     "erc-8004",
     "erc-8470",
     "erc-8265",
+    "allow-ticket",
     "robinhood-chain",
     "viem",
     "ethers",