@tollxyz/guard 0.4.1 → 0.6.0

package/dist/budget.d.ts

@@ -0,0 +1,96 @@
+import type { SpendPolicy } from "./policy.js";
+/** The budget's EIP-712 domain: no verifyingContract (nothing on chain checks it). */
+export declare const BUDGET_DOMAIN: {
+    readonly name: "Toll Facilitator Budget";
+    readonly version: "1";
+    readonly chainId: 4663;
+};
+export declare const BUDGET_TYPES: {
+    readonly Budget: readonly [{
+        readonly name: "payer";
+        readonly type: "address";
+    }, {
+        readonly name: "perPayment";
+        readonly type: "uint256";
+    }, {
+        readonly name: "perDay";
+        readonly type: "uint256";
+    }, {
+        readonly name: "perPayTo";
+        readonly type: "uint256";
+    }, {
+        readonly name: "payToCaps";
+        readonly type: "PayToCap[]";
+    }, {
+        readonly name: "allowedPayTos";
+        readonly type: "address[]";
+    }, {
+        readonly name: "validUntil";
+        readonly type: "uint64";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }];
+    readonly PayToCap: readonly [{
+        readonly name: "payTo";
+        readonly type: "address";
+    }, {
+        readonly name: "perDay";
+        readonly type: "uint256";
+    }];
+};
+/** at most this many payToCaps and allowedPayTos */
+export declare const BUDGET_MAX_PAYTOS = 50;
+export interface GuardBudgetOptions {
+    /** the agent's paying wallet (it signs the budget) */
+    payer: string;
+    /** newer wins at the facilitator: use a growing number, e.g. BigInt(Date.now()) */
+    nonce: bigint | number | string;
+    /** unix seconds the budget ends; 0 or unset = no end */
+    validUntil?: bigint | number | string;
+    /** the payTo of each perEndpoint prefix (same keys); a perEndpoint key that is itself an address is its own payTo */
+    endpointPayTo?: Record<string, string>;
+    /** one day cap for every payTo, base units; 0 or unset = not set */
+    perPayTo?: bigint;
+    /** perPayment when the policy has no assets[USDG].perCall (the facilitator needs one: 0 lets nothing through) */
+    perPayment?: bigint;
+    /** perDay when the policy has no assets[USDG].perDay */
+    perDay?: bigint;
+}
+export interface GuardBudgetMessage {
+    payer: string;
+    perPayment: bigint;
+    perDay: bigint;
+    perPayTo: bigint;
+    payToCaps: Array<{
+        payTo: string;
+        perDay: bigint;
+    }>;
+    allowedPayTos: string[];
+    validUntil: bigint;
+    nonce: bigint;
+}
+export interface GuardBudget {
+    /** the budget (the typed message), for @tollxyz/sdk's setBudget({ budget, signature }) */
+    budget: GuardBudgetMessage;
+    /** EIP-712 typed data for the payer to sign (viem: account.signTypedData(typedData)) */
+    typedData: {
+        domain: {
+            name: string;
+            version: string;
+            chainId: number;
+        };
+        types: typeof BUDGET_TYPES;
+        primaryType: "Budget";
+        message: GuardBudgetMessage;
+    };
+    /** guard rules the facilitator budget cannot hold (guard still enforces them in-process) */
+    notMirrored: string[];
+}
+/**
+ * The facilitator budget that mirrors a guard SpendPolicy. Throws when the policy has no USDG per-call or per-day cap
+ * and none is passed (the facilitator treats a missing cap as 0, which refuses every payment), or when a list is over 50.
+ */
+export declare function guardBudget(policy: SpendPolicy | {
+    spend?: SpendPolicy;
+}, opts: GuardBudgetOptions): GuardBudget;

package/dist/budget.js

@@ -0,0 +1,110 @@
+/**
+ * Mirror guard's spend caps into a per-payer budget at Toll's x402 facilitator (x402.t0ll.xyz/budget, COMING: the
+ * facilitator answers 404 budgets_off until budgets are switched on). guard enforces caps in the agent's process; the
+ * facilitator budget enforces them again where the payment settles, so a second process, a leaked key used elsewhere or
+ * a bug in the agent cannot spend past them through that facilitator.
+ *
+ * The words match: guard's assets[USDG].perCall is the budget's perPayment, assets[USDG].perDay its perDay, perEndpoint
+ * day caps become payToCaps (the facilitator sees a payTo, not a URL, so each endpoint needs its payTo) and allow.payTo
+ * becomes allowedPayTos. Nothing here changes how guard itself behaves. Amounts are USDG base units (6 decimals).
+ */
+import { isAddress } from "./check.js";
+import { USDG } from "./spend.js";
+/** The budget's EIP-712 domain: no verifyingContract (nothing on chain checks it). */
+export const BUDGET_DOMAIN = { name: "Toll Facilitator Budget", version: "1", chainId: 4663 };
+export const BUDGET_TYPES = {
+    Budget: [
+        { name: "payer", type: "address" },
+        { name: "perPayment", type: "uint256" },
+        { name: "perDay", type: "uint256" },
+        { name: "perPayTo", type: "uint256" },
+        { name: "payToCaps", type: "PayToCap[]" },
+        { name: "allowedPayTos", type: "address[]" },
+        { name: "validUntil", type: "uint64" },
+        { name: "nonce", type: "uint256" },
+    ],
+    PayToCap: [
+        { name: "payTo", type: "address" },
+        { name: "perDay", type: "uint256" },
+    ],
+};
+/** at most this many payToCaps and allowedPayTos */
+export const BUDGET_MAX_PAYTOS = 50;
+const MAX_U64 = (1n << 64n) - 1n;
+function uint(v, name, max = (1n << 256n) - 1n) {
+    let n = null;
+    if (typeof v === "bigint")
+        n = v;
+    else if (typeof v === "number" && Number.isSafeInteger(v))
+        n = BigInt(v);
+    else if (typeof v === "string" && /^\d{1,78}$/.test(v.trim()))
+        n = BigInt(v.trim());
+    if (n === null || n < 0n || n > max)
+        throw new Error(`guardBudget: ${name} must be a whole number from 0`);
+    return n;
+}
+/**
+ * The facilitator budget that mirrors a guard SpendPolicy. Throws when the policy has no USDG per-call or per-day cap
+ * and none is passed (the facilitator treats a missing cap as 0, which refuses every payment), or when a list is over 50.
+ */
+export function guardBudget(policy, opts) {
+    const sp = (policy && "spend" in policy ? policy.spend : policy) ?? {};
+    if (!isAddress(opts.payer))
+        throw new Error("guardBudget: payer must be a 0x address");
+    const notMirrored = [];
+    const assets = sp.assets ?? {};
+    const usdgKey = Object.keys(assets).find((k) => k.toLowerCase() === USDG);
+    const caps = usdgKey ? assets[usdgKey] : undefined;
+    for (const k of Object.keys(assets))
+        if (k !== usdgKey)
+            notMirrored.push(`assets["${k}"]: the facilitator budget is USDG only`);
+    const perPayment = opts.perPayment ?? caps?.perCall;
+    const perDay = opts.perDay ?? caps?.perDay;
+    if (perPayment === undefined)
+        throw new Error("guardBudget: no USDG per-call cap (set spend.assets[USDG].perCall or pass perPayment)");
+    if (perDay === undefined)
+        throw new Error("guardBudget: no USDG per-day cap (set spend.assets[USDG].perDay or pass perDay)");
+    const byPayTo = new Map();
+    for (const [prefix, c] of Object.entries(sp.perEndpoint ?? {})) {
+        const payTo = opts.endpointPayTo?.[prefix] ?? (isAddress(prefix) ? prefix : undefined);
+        if (c.perCall !== undefined)
+            notMirrored.push(`perEndpoint["${prefix}"].perCall: the facilitator has no per-payTo per-payment cap (perPayment applies)`);
+        if (c.perDay === undefined)
+            continue;
+        if (!payTo) {
+            notMirrored.push(`perEndpoint["${prefix}"].perDay: no payTo known for it (pass endpointPayTo)`);
+            continue;
+        }
+        if (!isAddress(payTo))
+            throw new Error(`guardBudget: endpointPayTo["${prefix}"] must be a 0x address`);
+        const had = byPayTo.get(payTo.toLowerCase());
+        // two endpoints paying one wallet: the stricter day cap holds for both
+        if (!had || c.perDay < had.perDay)
+            byPayTo.set(payTo.toLowerCase(), { payTo, perDay: uint(c.perDay, `perEndpoint["${prefix}"].perDay`) });
+    }
+    const payToCaps = [...byPayTo.values()];
+    const allowed = [];
+    for (const a of sp.allow?.payTo ?? []) {
+        if (!isAddress(a))
+            throw new Error(`guardBudget: allow.payTo entry "${a}" is not an address`);
+        if (!allowed.some((x) => x.toLowerCase() === a.toLowerCase()))
+            allowed.push(a);
+    }
+    if (payToCaps.length > BUDGET_MAX_PAYTOS || allowed.length > BUDGET_MAX_PAYTOS)
+        throw new Error(`guardBudget: at most ${BUDGET_MAX_PAYTOS} payToCaps and allowed payTos`);
+    if (sp.allow?.to?.length || sp.allow?.spender?.length)
+        notMirrored.push("allow.to / allow.spender: the facilitator only sees x402 payments (payTo)");
+    if (sp.approveAbove || sp.approve)
+        notMirrored.push("approveAbove / approve: human approval stays in guard");
+    const budget = {
+        payer: opts.payer,
+        perPayment: uint(perPayment, "perPayment"),
+        perDay: uint(perDay, "perDay"),
+        perPayTo: uint(opts.perPayTo ?? 0n, "perPayTo"),
+        payToCaps,
+        allowedPayTos: allowed,
+        validUntil: uint(opts.validUntil ?? 0, "validUntil", MAX_U64),
+        nonce: uint(opts.nonce, "nonce"),
+    };
+    return { budget, typedData: { domain: { ...BUDGET_DOMAIN }, types: BUDGET_TYPES, primaryType: "Budget", message: budget }, notMirrored };
+}

package/dist/index.d.ts

@@ -14,3 +14,5 @@ export { MemorySpendStore, dayStart } from "./store.js";
 export type { SpendStore } from "./store.js";
 export { appendTicketSuffix, encodeTicketAndSig, ticketAskOf, ticketOfAnswer, TICKET_SUFFIX_MAGIC, TOLL_ALLOW_SIGNER, ALLOW_DOCS } from "./ticket.js";
 export type { TicketAsk, AllowTicket, TicketResult } from "./ticket.js";
+export { guardBudget, BUDGET_DOMAIN, BUDGET_TYPES, BUDGET_MAX_PAYTOS } from "./budget.js";
+export type { GuardBudget, GuardBudgetOptions, GuardBudgetMessage } from "./budget.js";

package/dist/index.js

@@ -6,3 +6,4 @@ export { read8470, latestFinding8470, decodeGetObservation, decodeLatestFinding,
 export { spendOf, NATIVE, USDG, WETH, DEFAULT_SPEND_ASSETS, UNLIMITED } from "./spend.js";
 export { MemorySpendStore, dayStart } from "./store.js";
 export { appendTicketSuffix, encodeTicketAndSig, ticketAskOf, ticketOfAnswer, TICKET_SUFFIX_MAGIC, TOLL_ALLOW_SIGNER, ALLOW_DOCS } from "./ticket.js";
+export { guardBudget, BUDGET_DOMAIN, BUDGET_TYPES, BUDGET_MAX_PAYTOS } from "./budget.js";

package/dist/policy.d.ts

@@ -79,7 +79,7 @@ export interface SpendPolicy {
         approved: boolean;
         approvalRef?: string;
     }>;
-    /** a request whose spend could not be read (a contract call Toll did not simulate): default "allow", "block" under failClosed */
+    /** a request whose spend could not be read (a contract call Toll did not simulate, an x402 amount or a value that does not parse): "block" (default since 0.6.0) or "allow" */
     onUnknownSpend?: "allow" | "block";
 }
 /** blocked by your own spend rules; a TollBlockedError, so existing catch blocks still see a block */
@@ -107,10 +107,18 @@ export interface GuardOptions extends CheckOptions {
     /** BLOCK: "throw" (default, TollBlockedError), or a function (e.g. ask a human); true lets it through */
     onBlock?: BlockPolicy;
     /**
-     * Toll unreachable, timed out, 5xx, 429, or a request it could not read: "allow" (default, fail-open, logged) or
-     * "block" (fail-closed, throws TollUnavailableError). `strict` makes "block" the default.
+     * Toll unreachable, timed out, 5xx, 429, any other non-2xx (400, 413), or an answer that is not a RiskAssessment:
+     * "block" (default since 0.6.0, fail-closed: nothing is signed, throws TollUnavailableError) or "allow" (fail-open,
+     * logged). Passed explicitly it wins over `failOpen` and `strict`.
      */
     onUnavailable?: "allow" | "block";
+    /**
+     * 0.6.0: the opt-in to the old default. `true` = when Toll cannot or will not answer, the request goes ahead
+     * unchecked (logged "NOT checked"). Know what it means: whoever builds the request can make Toll refuse it (a
+     * request padded past Toll's size limit answers HTTP 413) and so switch the check off. Default false.
+     * `strict` and an explicit `onUnavailable` win over it.
+     */
+    failOpen?: boolean;
     /** a request Toll does not read (another chain, a contract deploy): "allow" (default) or "block"; `strict`: "block" */
     onUnsupported?: "allow" | "block";
     /**
@@ -139,7 +147,7 @@ export interface GuardOptions extends CheckOptions {
     spend?: SpendPolicy;
     /** where caps and paid x402 ids are counted; default an in-process MemorySpendStore per SpendPolicy object */
     store?: SpendStore;
-    /** with `spend`: a request whose spend cannot be read is blocked (onUnknownSpend default "block") */
+    /** with `spend`: a request whose spend cannot be read is blocked. Since 0.6.0 that is the default anyway (onUnknownSpend "block"); kept for callers that set it */
     failClosed?: boolean;
 }
 /** fields the wrappers pass to enforce; not part of the public options */
@@ -159,7 +167,6 @@ export declare function resolvePolicy(o?: GuardOptions): {
     onUnavailable: "allow" | "block";
     onUnsupported: "allow" | "block";
 };
-/** true when any warning is high or critical */
 export declare const hasHighWarning: (a: RiskAssessment) => boolean;
 /** true for a signature request (typed data, a message, a signing RPC) rather than a transaction or an x402 payment */
 export declare const isSignature: (input: CheckInput | null | undefined) => boolean;

package/dist/policy.js

@@ -25,13 +25,15 @@ export function resolvePolicy(o = {}) {
     const strict = o.strict === true;
     return {
         onWarn: o.onWarn ?? (strict ? "block" : "block-high"),
-        onUnavailable: o.onUnavailable ?? (strict ? "block" : "allow"),
+        onUnavailable: o.onUnavailable ?? (strict ? "block" : o.failOpen === true ? "allow" : "block"),
         onUnsupported: o.onUnsupported ?? (strict ? "block" : "allow"),
     };
 }
 const HIGH = new Set(["high", "critical"]);
 /** true when any warning is high or critical */
-export const hasHighWarning = (a) => (a.warnings ?? []).some((w) => HIGH.has(String(w?.severity).toLowerCase()));
+/** warnings that say "this was not checked": refused under block-high whatever their severity (0.6.0) */
+const UNCHECKED = new Set(["coin-not-read"]);
+export const hasHighWarning = (a) => (a.warnings ?? []).some((w) => HIGH.has(String(w?.severity).toLowerCase()) || UNCHECKED.has(String(w?.code)));
 const say = (o, msg) => {
     if (o.logger === false)
         return;
@@ -187,9 +189,13 @@ async function unavailable(kind, input, err, o) {
     const blocked = resolvePolicy(o).onUnavailable === "block" || isEthSign(input);
     const r = { kind, input, assessment: null, decision: blocked ? "blocked" : "allowed", basis: "unavailable", paidUrl: err.paidUrl, error: err };
     await report(o, r);
-    if (blocked)
-        throw err;
-    say(o, `Toll unavailable, NOT checked, going ahead (onUnavailable "allow"): ${err.message}`);
+    if (blocked) {
+        // the same error class and fields; the message says nothing was signed and names the opt-out
+        if (/^Not signed/.test(err.message))
+            throw err;
+        throw new TollUnavailableError(`Not signed: Toll did not check this request. ${err.message} The guard fails closed; failOpen: true lets unchecked requests through.`, { reason: err.reason, status: err.status, paidUrl: err.paidUrl, cause: err });
+    }
+    say(o, `Toll unavailable, NOT checked, going ahead (${o.failOpen === true && o.onUnavailable === undefined ? "failOpen: true" : 'onUnavailable "allow"'}): ${err.message}`);
     return r;
 }
 /**
@@ -395,7 +401,9 @@ async function enforceSpend(kind, build, o) {
     const why = offList(sp, s);
     if (why)
         return blockWith(base, "not-allowlisted", `Not signed: ${why}.`, s);
-    if (s.unknown && (sp.onUnknownSpend ?? (o.failClosed ? "block" : "allow")) === "block") {
+    // 0.6.0: with a spend policy set, what cannot be read is refused by default (it was allowed unless failClosed):
+    // caps that bind only on plain transfers are not caps. onUnknownSpend "allow" is the opt-out
+    if (s.unknown && (sp.onUnknownSpend ?? "block") === "block") {
         return blockWith(base, "unknown-spend", 'Not signed: what this request spends could not be read (no simulation), and onUnknownSpend is "block".', s);
     }
     const caps = lower(sp.assets);

package/dist/spend.js

@@ -94,7 +94,11 @@ class Acc {
 function decodeTx(i, acc) {
     const from = isAddress(i.from) ? lc(i.from) : null;
     const target = lc(i.to);
-    const value = big(i.value ?? 0) ?? 0n;
+    // a value that cannot be read (a JS number past 2^53, text) is not "nothing sent": unknown (0.6.0)
+    const read = big(i.value ?? 0);
+    if (read === null)
+        acc.unknown = true;
+    const value = read ?? 0n;
     const data = typeof i.data === "string" ? i.data : "0x";
     if (value > 0n)
         acc.out(NATIVE, value, { kind: "value", to: target });
@@ -113,7 +117,8 @@ function decodeTx(i, acc) {
     }
     if (sel === SEL.transferFrom && w.length >= 3) {
         const src = wAddr(w[0]);
-        const to = wAddr(w[2]);
+        // transferFrom(from, to, amount): the recipient is the SECOND word (0.6.0: it was read from the amount word)
+        const to = wAddr(w[1]);
         acc.to.add(to);
         // only the signer's own tokens are its spend
         if (!from || src === from)
@@ -182,9 +187,12 @@ function decodeX402(x, acc) {
         if (payTo)
             acc.payTo.add(payTo);
         const amt = big(e.amount ?? e.maxAmountRequired);
-        // the client pays one entry: the largest per asset counts
+        // the client pays one entry: the largest per asset counts. An amount that cannot be read (0.6.0: "+5000000",
+        // "5e6", none) is not zero: the caps cannot be applied to it, so the spend is unknown
         if (amt !== null)
             acc.out(lc(e.asset), amt, { kind: "x402", payTo }, true);
+        else
+            acc.unknown = true;
     }
 }
 function readSim(a, from, acc) {

package/package.json

@@ -1,70 +1,70 @@
-{
-  "name": "@tollxyz/guard",
-  "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",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=20.19"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/t0ll-xyz/toll-plugins.git",
-    "directory": "packages/guard"
-  },
-  "homepage": "https://t0ll.xyz/agents/plugins",
-  "keywords": [
-    "agent-wallet",
-    "transaction-guard",
-    "pre-sign",
-    "x402",
-    "erc-8004",
-    "erc-8470",
-    "erc-8265",
-    "allow-ticket",
-    "robinhood-chain",
-    "viem",
-    "ethers",
-    "ai-agent",
-    "toll"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "tsc -p tsconfig.json --noEmit && tsx --test tests/*.test.ts",
-    "smoke": "node scripts/smoke.mjs",
-    "prepublishOnly": "npm run build"
-  },
-  "peerDependencies": {
-    "ethers": "^6.0.0",
-    "viem": "^2.0.0"
-  },
-  "peerDependenciesMeta": {
-    "ethers": {
-      "optional": true
-    },
-    "viem": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.6.0"
-  }
-}
+{
+  "name": "@tollxyz/guard",
+  "version": "0.6.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; single-use ALLOW tickets for contracts that require one. Zero runtime dependencies.",
+  "license": "MIT",
+  "author": "Toll",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t0ll-xyz/toll-plugins.git",
+    "directory": "packages/guard"
+  },
+  "homepage": "https://t0ll.xyz/agents/plugins",
+  "keywords": [
+    "agent-wallet",
+    "transaction-guard",
+    "pre-sign",
+    "x402",
+    "erc-8004",
+    "erc-8470",
+    "erc-8265",
+    "allow-ticket",
+    "robinhood-chain",
+    "viem",
+    "ethers",
+    "ai-agent",
+    "toll"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json --noEmit && tsx --test tests/*.test.ts",
+    "smoke": "node scripts/smoke.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "ethers": "^6.0.0",
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ethers": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}