@tollxyz/guard 0.3.0 → 0.4.1

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/ticket.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 0.4.1: Toll's single-use ALLOW ticket. Ask for one with the `ticket` option; Toll signs a compact EIP-712 verdict
+ * bound to one exact call, one account, an optional consumer contract and a 60 second window. A contract built on
+ * toll-allow (https://github.com/t0ll-xyz/toll-allow) accepts the call only with a valid, unused ticket.
+ * A BLOCK is never signed. No ticket without `from`, or for a transaction with an EIP-7702 authorization list.
+ *
+ * appendTicketSuffix MUST match toll-allow's TollAllow.encodeSuffix / splitSuffix byte for byte:
+ *   body ‖ abi.encode((uint8,uint8,address,address,bytes32,uint64,uint64,bytes32,bytes32), bytes) ‖ uint32 len ‖ 0x900bc3e1
+ * where len is the byte length of the abi.encode part and 0x900bc3e1 = bytes4(keccak256("TollAllow.v1")).
+ */
+import type { Hex } from "./check.js";
+/** what to ask Toll for: `true` = scope "call", any consumer */
+export interface TicketAsk {
+    /** the contract that will check the ticket (its `consumer` field); unset = any contract */
+    consumer?: string;
+    /** "call" (default): bound to (target, value, keccak256(data)); "v4swap": bound to the swap a HookrRouter call makes */
+    scope?: "call" | "v4swap";
+}
+/** the ticket as Toll returns it (x-toll.ticket.ticket); uint64 times are unix seconds */
+export interface AllowTicket {
+    scope: number;
+    verdict: number;
+    account: string;
+    consumer: string;
+    subject: string;
+    validAfter: number | bigint | string;
+    validUntil: number | bigint | string;
+    nonce: string;
+    reportHash: string;
+}
+/** x-toll.ticket: a signed ticket, or why none was issued */
+export type TicketResult = {
+    ticket: AllowTicket;
+    signature: Hex;
+    signer: string;
+} | {
+    why: string;
+};
+/** bytes4(keccak256("TollAllow.v1")) */
+export declare const TICKET_SUFFIX_MAGIC = "0x900bc3e1";
+/** Toll's production ALLOW signer on Robinhood Chain (4663): pin it, or a TollSignerSet you control that includes it */
+export declare const TOLL_ALLOW_SIGNER = "0x4A2C93066d94F1E69f3EAd5438c4efDdf80a46ba";
+export declare const ALLOW_DOCS = "https://t0ll.xyz/agents/allow";
+/** the ask as the route reads it (`ticket: {consumer?, scope?}`), or null for none */
+export declare function ticketAskOf(t: boolean | TicketAsk | undefined | null): TicketAsk | null;
+/** the ticket in an answer, when the answer carries one (signed or with its why) */
+export declare function ticketOfAnswer(a: {
+    "x-toll"?: Record<string, unknown>;
+} | null | undefined): TicketResult | undefined;
+/** abi.encode(Ticket, bytes) as hex without 0x: the static tuple inline (9 words), then the offset and the bytes */
+export declare function encodeTicketAndSig(t: AllowTicket, signature: string): string;
+/**
+ * The calldata a ticket-checking router reads: `data ‖ abi.encode(ticket, signature) ‖ uint32 len ‖ 0x900bc3e1`.
+ * The ticket's subject is over `data` (the body) only. Identical to TollAllow.encodeSuffix in toll-allow.
+ */
+export declare function appendTicketSuffix(data: Hex, ticket: AllowTicket, signature: Hex): Hex;

package/dist/ticket.js

@@ -0,0 +1,90 @@
+/** bytes4(keccak256("TollAllow.v1")) */
+export const TICKET_SUFFIX_MAGIC = "0x900bc3e1";
+/** Toll's production ALLOW signer on Robinhood Chain (4663): pin it, or a TollSignerSet you control that includes it */
+export const TOLL_ALLOW_SIGNER = "0x4A2C93066d94F1E69f3EAd5438c4efDdf80a46ba";
+export const ALLOW_DOCS = "https://t0ll.xyz/agents/allow";
+/** the ask as the route reads it (`ticket: {consumer?, scope?}`), or null for none */
+export function ticketAskOf(t) {
+    if (t === undefined || t === null || t === false)
+        return null;
+    if (t === true)
+        return {};
+    const o = {};
+    if (t.consumer !== undefined)
+        o.consumer = t.consumer;
+    if (t.scope !== undefined)
+        o.scope = t.scope;
+    return o;
+}
+/** the ticket in an answer, when the answer carries one (signed or with its why) */
+export function ticketOfAnswer(a) {
+    const t = a?.["x-toll"]?.ticket;
+    if (!t || typeof t !== "object")
+        return undefined;
+    if (typeof t.why === "string")
+        return { why: t.why };
+    if (t.ticket && typeof t.ticket === "object" && typeof t.signature === "string" && typeof t.signer === "string") {
+        return { ticket: t.ticket, signature: t.signature, signer: t.signer };
+    }
+    return undefined;
+}
+/* ------------------------------------------------------------------ ABI encoding (no dependencies) */
+const hexBody = (h, what) => {
+    if (typeof h !== "string" || !/^0x([0-9a-fA-F]{2})*$/.test(h))
+        throw new TypeError(`${what} must be 0x hex with whole bytes`);
+    return h.slice(2).toLowerCase();
+};
+const word = (n, bits, what) => {
+    if (n < 0n || n >= 1n << BigInt(bits))
+        throw new RangeError(`${what} does not fit in uint${bits}`);
+    return n.toString(16).padStart(64, "0");
+};
+const uint = (v, bits, what) => {
+    let n;
+    try {
+        n = BigInt(v);
+    }
+    catch {
+        throw new TypeError(`${what} must be a whole number`);
+    }
+    return word(n, bits, what);
+};
+const addr = (a, what) => {
+    if (typeof a !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(a))
+        throw new TypeError(`${what} must be an address`);
+    return a.slice(2).toLowerCase().padStart(64, "0");
+};
+const b32 = (h, what) => {
+    if (typeof h !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(h))
+        throw new TypeError(`${what} must be 32 bytes`);
+    return h.slice(2).toLowerCase();
+};
+/** abi.encode(Ticket, bytes) as hex without 0x: the static tuple inline (9 words), then the offset and the bytes */
+export function encodeTicketAndSig(t, signature) {
+    const sig = hexBody(signature, "signature");
+    const head = uint(t.scope, 8, "ticket.scope") +
+        uint(t.verdict, 8, "ticket.verdict") +
+        addr(t.account, "ticket.account") +
+        addr(t.consumer, "ticket.consumer") +
+        b32(t.subject, "ticket.subject") +
+        uint(t.validAfter, 64, "ticket.validAfter") +
+        uint(t.validUntil, 64, "ticket.validUntil") +
+        b32(t.nonce, "ticket.nonce") +
+        b32(t.reportHash, "ticket.reportHash");
+    const offset = word(10n * 32n, 256, "offset"); // 9 tuple words + this offset word
+    const len = word(BigInt(sig.length / 2), 256, "signature length");
+    const padded = sig + "0".repeat((64 - (sig.length % 64)) % 64);
+    return head + offset + len + padded;
+}
+/**
+ * The calldata a ticket-checking router reads: `data ‖ abi.encode(ticket, signature) ‖ uint32 len ‖ 0x900bc3e1`.
+ * The ticket's subject is over `data` (the body) only. Identical to TollAllow.encodeSuffix in toll-allow.
+ */
+export function appendTicketSuffix(data, ticket, signature) {
+    const body = hexBody(data, "data");
+    const enc = encodeTicketAndSig(ticket, signature);
+    const n = enc.length / 2;
+    if (n >= 2 ** 32)
+        throw new RangeError("ticket encoding too long");
+    return `0x${body}${enc}${n.toString(16).padStart(8, "0")}${TICKET_SUFFIX_MAGIC.slice(2)}`;
+}

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