@tollxyz/guard 0.2.0 → 0.4.0

package/README.md

@@ -1,12 +1,31 @@
 # @tollxyz/guard
 
+> **New in 0.4.0: spend caps, allowlists, human approval and preview** (`spend` option). Unset, nothing changes.
+> See [0.4.0: spend caps, allowlists, approval, preview](#040-spend-caps-allowlists-approval-preview).
+
+> **0.3.1:** `signTypedData` (viem and ethers) now sends the signing account as `from`, so Toll can say what a Permit2 signature lets someone take.
+>
+> **What changed in 0.3.0: every signing method is checked.**
+> - Messages: viem and ethers `signMessage`, and `request()` for `personal_sign` and `eth_sign`.
+> - Typed data: `request()` for `eth_signTypedData_v4` too, any EIP-712 (orders, permits, sign-ins).
+> - Batches: viem `sendCalls` (EIP-5792) and `request()` for `wallet_sendCalls`, each call checked.
+> - Smart accounts: `guardSmartAccount` wraps a viem bundler client's `sendUserOperation` and `prepareUserOperation`;
+>   `guard()` picks it for a bundler client.
+> - EIP-7702: `onAuthorization` now defaults to `"check"`: Toll reads the authorization and decides (a known, verified
+>   delegate is WARN medium and goes ahead under `block-high`; an unknown one is BLOCK). `"block"` and `"allow"` stay.
+>   An authorization Toll cannot read is blocked.
+> - A signature for another chain is blocked (before 0.3.0 it went through as unsupported); `onUnsupported: "allow"`
+>   lets it through.
+> - `eth_sign` always fails closed: it can sign any 32 bytes, a transaction included, so when Toll cannot answer it is
+>   blocked whatever `onUnavailable` says.
+
 > **Defaults changed in 0.2.0.** A WARN with any `high` or `critical` warning is now blocked (`onWarn: "block-high"`,
 > the new default); a WARN with only `medium`/`low` warnings still goes ahead, logged. To keep the 0.1.x behaviour,
 > pass `onWarn: "allow"`. New `strict: true` preset: WARN, unavailable and unsupported all block. Any option you pass
 > explicitly still wins over the preset (`{ strict: true, onUnavailable: "allow" }` stays fail-open).
 
-Toll's live pre-sign check in front of an AI agent's wallet. Before the agent signs a transaction, an EIP-712
-signature or an x402 payment on Robinhood Chain, the guard asks [Toll](https://t0ll.xyz/agents/x402#presign) and
+Toll's live pre-sign check in front of an AI agent's wallet. Before the agent signs a transaction, a message, an
+EIP-712 signature, a batch, a user operation, an EIP-7702 authorization or an x402 payment on Robinhood Chain, the guard asks [Toll](https://t0ll.xyz/agents/x402#presign) and
 gets ALLOW / WARN / BLOCK with the reasons. Zero runtime dependencies, ESM only, Node >= 20.19, with types.
 
 ```sh
@@ -14,7 +33,7 @@ npm install @tollxyz/guard
 ```
 
 ```ts
-const wallet = guard(walletClient);   // viem WalletClient or ethers v6 Signer; same methods, checked first
+const wallet = guard(walletClient);   // viem WalletClient, viem bundler client or ethers v6 Signer; same methods, checked first
 ```
 
 ```ts
@@ -62,23 +81,43 @@ The answer is an [ERC-8265](https://github.com/ethereum/ERCs/pull/1753) RiskAsse
 `{ action, warnings: [{ code, severity, message, "x-toll-evidence" }], scanners, "x-toll": { decoded, link, checked_at, note } }`.
 Critical = BLOCK, high or medium = WARN, low or none = ALLOW.
 
-Robinhood Chain (4663) only for now. A request on another chain, or a contract deployment, is not sent to Toll and
-goes through (`onUnsupported: "block"` to stop it instead).
+Robinhood Chain (4663) only for now. A transaction on another chain, or a contract deployment, is not sent to Toll
+and goes through (`onUnsupported: "block"` to stop it instead). A signature for another chain is blocked
+(`onUnsupported: "allow"` lets it through).
 
 ## API
 
-### `guard(wallet, opts?)`, `guardViem(client, opts?)`, `guardEthers(signer, opts?)`
+### `guard(wallet, opts?)`, `guardViem(client, opts?)`, `guardSmartAccount(bundler, opts?)`, `guardEthers(signer, opts?)`
 
 Returns the same wallet behind a Proxy. Checked first:
 
 - viem WalletClient: `sendTransaction`, `writeContract` (calldata encoded with your viem's `encodeFunctionData`),
-  `signTransaction`, `signTypedData`
-- ethers v6 Signer: `sendTransaction`, `signTransaction`, `signTypedData`
+  `signTransaction`, `signTypedData`, `signMessage`, `sendCalls`, `signAuthorization`, and `request()` for
+  `eth_sendTransaction`, `eth_signTransaction`, `personal_sign`, `eth_sign`, `eth_signTypedData_v4` and
+  `wallet_sendCalls` (every other method passes through)
+- viem bundler client (account abstraction): `sendUserOperation`, `prepareUserOperation`. `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
+- ethers v6 Signer: `sendTransaction`, `signTransaction`, `signTypedData`, `signMessage`, `authorize`
+
+A batch is checked call by call, in order; the first call blocked stops the whole batch.
+
+An EIP-7702 authorization sets the wallet's code to another contract, which can then move everything it holds: a
+transaction with an `authorizationList` on any method above, viem's `signAuthorization`, ethers' `authorize`, a user
+operation's `authorization`. By default (`onAuthorization: "check"`) Toll reads it and decides; if Toll cannot read it
+(unreachable, another chain) it is blocked (TollBlockedError, code `eip7702-authorization`). `"block"` refuses every
+authorization without asking; `"allow"` lets it through unchecked. The account's own sign methods
+(`client.account.sign*`) are not wrapped.
+
+```ts
+const wallet = guard(walletClient, { origin: "https://app.example" }); // origin: the site asking, for sign-ins
+await wallet.signMessage({ message: "Sign in to app.example" });     // checked as personal_sign
+await wallet.request({ method: "personal_sign", params: [hexMessage, address] });
+await wallet.request({ method: "eth_sign", params: [address, hash] }); // blocked when Toll blocks it, or cannot answer
 
-An EIP-7702 authorization sets the wallet's code to another contract, which can then move everything it holds. Toll
-does not read one yet, so the guard blocks it itself (TollBlockedError, code `eip7702-authorization`) unless
-`onAuthorization: "allow"`: a transaction with an `authorizationList` on any method above, viem's
-`signAuthorization` and ethers' `authorize`. The account's own sign methods (`client.account.sign*`) are not wrapped.
+const smart = guard(bundlerClient);                                    // detected by sendUserOperation
+await smart.sendUserOperation({ calls: [{ to: token, abi: erc20Abi, functionName: "transfer", args: [to, amount] }] });
+```
 
 Everything else passes through unchanged. Wrap last: `client.extend(...)` or `signer.connect(...)` on the wrapped
 wallet returns an unguarded one. viem and ethers are optional peer dependencies, never imported at load time.
@@ -102,8 +141,12 @@ const pay = wrapFetchWithPayment(guardX402Fetch(fetch, { agentId: 123 }), accoun
 
 ### `checkTx(input, opts?)`
 
-The raw call. `input`: `{ chainId, from, to, data, value }` for a transaction, `{ typedData }` for an EIP-712
-request, `{ x402, agentId?, payment? }` for an x402 payment, or several together. Returns the RiskAssessment. When a
+The raw call. `input`: `{ chainId, from, to, data, value, authorizationList? }` for a transaction,
+`{ chainId, from, authorizationList }` for an authorization alone, `{ typedData }` for an EIP-712 request,
+`{ message: { kind: "personal_sign" | "eth_sign", data, from? } }` for a message, `{ rpc: { method, params } }` for a
+wallet request (`personal_sign`, `eth_sign`, `eth_signTypedData_v4`, `eth_sendTransaction`), `{ userOp, entryPoint? }`
+for an ERC-4337 user operation, `{ x402, agentId?, payment? }` for an x402 payment, or several together; `origin` is
+the site asking. Returns the RiskAssessment. When a
 coin is still being read, Toll answers WARN `coin-not-read` with `Retry-After`: `checkTx` asks once more if the wait
 is at most `maxRetryWaitMs` (default 10 s); a coin still not read stays WARN, never ALLOW. Throws
 `TollUnavailableError` when Toll cannot answer.
@@ -116,17 +159,180 @@ is at most `maxRetryWaitMs` (default 10 s); a coin still not read stays WARN, ne
 | `onWarn` | `"block-high"` | `"block-high"` (blocked when any warning is `high` or `critical`, else allowed and logged), `"allow"` (every WARN goes ahead, logged; the 0.1.x default), `"block"`, or `(assessment) => boolean` (true lets it through) |
 | `onBlock` | `"throw"` | `"throw"` (TollBlockedError), or `(assessment) => boolean`, e.g. ask a human; true lets it through |
 | `onUnavailable` | `"allow"` (`strict`: `"block"`) | Toll unreachable, timed out, 5xx, 429, or a request it could not read: `"allow"` (fail-open, logged) or `"block"` (fail-closed, TollUnavailableError) |
-| `onUnsupported` | `"allow"` (`strict`: `"block"`) | another chain, a deployment: `"allow"` or `"block"` |
-| `onAuthorization` | `"block"` | an EIP-7702 authorization: `"block"` (TollBlockedError) or `"allow"` (unchecked, logged) |
+| `onUnsupported` | `"allow"` (`strict`: `"block"`) | a transaction on another chain, a deployment: `"allow"` or `"block"`. A signature for another chain is blocked unless this is `"allow"` explicitly |
+| `onAuthorization` | `"check"` | an EIP-7702 authorization: `"check"` (Toll decides; blocked when Toll cannot read it), `"block"` (TollBlockedError, Toll not asked) or `"allow"` (unchecked, logged) |
+| `origin` | none | the site asking for a signature, sent with messages and typed data |
 | `onReport` | none | `(report) => void`: every decision, with `assessment`, `decision`, `basis`, `paidUrl` |
 | `logger` | `console.warn` | where WARN and unavailable lines go; `false` = silent |
 | `timeoutMs` | `15000` | one request to Toll |
 | `retry`, `maxRetryWaitMs` | `true`, `10000` | the one retry after Retry-After |
 | `baseUrl`, `fetch` | `https://t0ll.xyz`, global fetch | |
+| `spend` | none | 0.4.0: caps, allowlists, approval ([below](#040-spend-caps-allowlists-approval-preview)); unset = 0.3.x behaviour |
+| `store` | in-process `MemorySpendStore` | where spend counters and paid x402 ids live |
+| `failClosed` | `false` | with `spend`: a request whose spend cannot be read is blocked |
 
 Errors: `TollBlockedError` (`.assessment`, `.codes`, message lists each code and message) and
 `TollUnavailableError` (`.reason`, `.status`, `.paidUrl`).
 
+## 0.4.0: spend caps, allowlists, approval, preview
+
+Toll's verdict says whether a request looks safe. `spend` adds your own limits on top: how much the agent may spend
+per call and per UTC day, who it may pay, and when a human has to say yes. Without `spend` nothing changes: 0.4.0
+behaves exactly like 0.3.x.
+
+The order for every request:
+
+1. **Allowlists** (`allow.to`, `allow.spender`, `allow.payTo`): read from the request itself, before Toll is asked.
+   Off the list = blocked, and Toll is not called.
+2. **Toll's verdict**: ALLOW / WARN / BLOCK with your `onWarn`, `onBlock`, `onUnavailable` as before. A WARN that
+   `block-high` blocks is still blocked, however small the amount.
+3. **Caps** (`assets`, `perEndpoint`): per call, then per day. The day amount is reserved.
+4. **Approval** (`approveAbove` + `approve`): above the threshold your `approve` function decides.
+5. **After the send**: the reservation is committed. If the send throws (rejected, nonce too low, RPC down), it is
+   released, so failures never use up the day cap.
+
+Caps never relax Toll's verdict, and Toll's ALLOW never lifts a cap: a request must pass both.
+
+```ts
+import { guard, NATIVE, USDG, TollPolicyError } from "@tollxyz/guard";
+
+const wallet = guard(walletClient, {
+  spend: {
+    // base units: ETH in wei, USDG with 6 decimals
+    assets: {
+      [NATIVE]: { perCall: 10n ** 16n, perDay: 5n * 10n ** 16n }, // 0.01 ETH a call, 0.05 ETH a day
+      [USDG]: { perCall: 20_000_000n, perDay: 100_000_000n },    // 20 USDG a call, 100 USDG a day
+    },
+    allow: { spender: ["0xYourRouter..."] },                     // approvals only to your router
+    approveAbove: { [USDG]: 10_000_000n },                       // above 10 USDG a human decides
+    approve: async (req) => {
+      const ok = await askOnTelegram(`Spend ${req.over[0].amount} of ${req.over[0].asset}?`);
+      return { approved: ok, approvalRef: ok ? "tg-msg-1234" : undefined };
+    },
+  },
+  failClosed: true, // a contract call whose spend cannot be read is blocked
+});
+
+try {
+  await wallet.sendTransaction(tx);
+} catch (e) {
+  if (e instanceof TollPolicyError) console.log(e.code, e.amount, e.limit); // "cap-per-day", ...
+  else throw e;
+}
+```
+
+**What counts as spend.** Only what leaves the wallet in a spend asset. The defaults are native ETH, WETH and USDG on
+Robinhood Chain, plus every asset you name in `assets` or `approveAbove`. A sell of any other coin is never capped.
+
+- Read locally, with no Toll answer needed: the transaction's value, ERC-20 `transfer` / `transferFrom` / `approve` /
+  `increaseAllowance` on a spend asset, EIP-2612 permits, Permit2 permits, EIP-3009 transfer authorizations, and an
+  x402 402's amount. So caps hold even when Toll is unreachable.
+- Any other contract call (a swap, a router): the amount comes from Toll's simulation (`x-toll.simulation.deltas`).
+  When the simulation shows more leaving than the call declares, the larger amount counts.
+- An approval counts against the per-call cap at its full size (an unlimited approval is over any cap) and must fit
+  in what is left of the day cap; it is not added to the day total (the later swap is).
+- Unknown spend: a contract call with no simulation (Toll unreachable), a raw user operation, a bare EIP-7702
+  authorization. `onUnknownSpend` decides: `"allow"` by default, `"block"` under `failClosed: true`.
+
+| `spend` field | |
+| --- | --- |
+| `assets` | `{ [asset]: { perCall?, perDay? } }`, asset = `"native"` or a token address, amounts in base units |
+| `perEndpoint` | x402 caps per URL prefix (origin + path), e.g. `{ "https://api.example.com/v1/": { perDay: 1_000_000n } }` |
+| `allow` | `{ to?, spender?, payTo? }`: every recipient (or called contract), approval spender, x402 payee must be listed |
+| `approveAbove` | `{ [asset]: amount }`: above it, `approve` must say yes |
+| `approve` | `(req) => Promise<{ approved, approvalRef? }>`; no function = denied. `approvalRef` lands in `report.spend.approvalRef` |
+| `onUnknownSpend` | `"allow"` (default) or `"block"` (default under `failClosed`) |
+
+New options next to `spend`: `store` (where counters live, below) and `failClosed`.
+
+`TollPolicyError` extends `TollBlockedError` (existing `catch` blocks still see a block). `.code` is one of
+`not-allowlisted`, `cap-per-call`, `cap-per-day`, `cap-endpoint`, `approval-denied`, `duplicate-payment`,
+`unknown-spend`; `.asset`, `.amount`, `.limit` when they apply. The report has `basis: "policy"` and `policy: code`.
+
+### Preview, then confirm
+
+```ts
+import { preview } from "@tollxyz/guard";
+
+const p = await preview({ chainId: 4663, from, to, data, value }, opts); // same opts as the guard
+// p.decision "allowed" | "blocked", p.basis, p.policy, p.spend, p.needsApproval, p.reason
+if (p.decision === "allowed") await wallet.sendTransaction({ to, data, value, tollConfirm: p.confirmId });
+```
+
+`preview` asks Toll and checks every rule, but reserves nothing, calls no `approve` and no `onReport`. Passing its
+`confirmId` as `tollConfirm` within 30 seconds reuses that Toll answer (one Toll call instead of two). It is used
+once, and only for the identical request; anything else is checked again. The guard strips `tollConfirm` before the
+wallet sees the request (viem `sendTransaction` / `signTransaction` / `writeContract`, ethers `sendTransaction` /
+`signTransaction`).
+
+### x402: payment ids and per-endpoint caps
+
+With `spend` set, `guardX402Fetch` also:
+
+- counts a 402's amount against `assets` and `perEndpoint` caps when it is checked. The reservation waits for the
+  paid retry: committed when the seller answers, released on another 402 or an error, released after `holdMs`
+  (default 2 minutes) when no paid retry comes.
+- never pays the same x402 `payment-identifier` twice. An id is marked paid only when the seller accepts the paid
+  request (any answer but 402); sending that id again throws `TollPolicyError` `duplicate-payment` (ids are kept
+  `paymentIdTtlS`, default 1 day). A second send of an id that is still in flight is refused too. After a network
+  error or timeout the same id may be retried (the seller dedupes it): the retry reuses the reservation of its 402,
+  so nothing is counted twice. A different id is a new payment.
+
+### Where the counters live
+
+The default store is a `MemorySpendStore` in this process, one per `spend` object. **It resets when the process
+restarts and is not shared between processes**: two workers each get the full day cap. For a cap that survives
+restarts or spans workers, pass your own `store` implementing `SpendStore`:
+
+```ts
+interface SpendStore {
+  reserve(k: string, amt: bigint, limit: bigint, windowStart: number): Promise<{ ok: boolean; id: string; used: bigint }>;
+  commit(id: string): Promise<void>;
+  release(id: string): Promise<void>;
+  paymentSeen(id: string): Promise<boolean>;
+  markPaid(id: string, ttlS: number): Promise<void>;
+}
+```
+
+A Redis store (example only, not shipped; `reserve` must be atomic, hence the Lua script):
+
+```ts
+import Redis from "ioredis";
+import type { SpendStore } from "@tollxyz/guard";
+
+const redis = new Redis(process.env.REDIS_URL!);
+const RESERVE = `
+local used = tonumber(redis.call('GET', KEYS[1]) or '0')
+local amt, limit = tonumber(ARGV[1]), tonumber(ARGV[2])
+if used + amt > limit then return {0, tostring(used)} end
+redis.call('INCRBY', KEYS[1], ARGV[1])
+redis.call('EXPIRE', KEYS[1], 172800)
+redis.call('SET', KEYS[2], KEYS[1] .. '|' .. ARGV[1], 'EX', 3600)
+return {1, tostring(used + amt)}`;
+const RELEASE = `
+local v = redis.call('GET', KEYS[1])
+if not v then return 0 end
+local sep = string.find(v, '|', 1, true)
+redis.call('DECRBY', string.sub(v, 1, sep - 1), string.sub(v, sep + 1))
+redis.call('DEL', KEYS[1])
+return 1`;
+
+export const redisStore: SpendStore = {
+  async reserve(k, amt, limit, windowStart) {
+    const id = `toll:res:${crypto.randomUUID()}`;
+    // amounts as numbers in Lua: fine below 2^53 base units; use string math for larger caps
+    const [ok, used] = (await redis.eval(RESERVE, 2, `toll:cap:${k}:${windowStart}`, id, amt.toString(), limit.toString())) as [number, string];
+    return { ok: ok === 1, id: ok === 1 ? id : "", used: BigInt(used) };
+  },
+  async commit(id) { await redis.del(id); },          // the amount stays in the day counter
+  async release(id) { await redis.eval(RELEASE, 1, id); },
+  async paymentSeen(id) { return (await redis.exists(`toll:paid:${id}`)) === 1; },
+  async markPaid(id, ttlS) { await redis.set(`toll:paid:${id}`, "1", "EX", ttlS); },
+};
+
+const wallet = guard(walletClient, { spend: { /* ... */ }, store: redisStore });
+```
+
 ## Fail-open or fail-closed
 
 The default is fail-open: if Toll cannot answer, the signature goes ahead, with a `[toll-guard] ... NOT checked`
@@ -134,6 +340,9 @@ line and an `onReport` call with `basis: "unavailable"`. The agent must never ge
 free route is rate limited per IP (a busy agent will see 429s). If an unchecked signature is worse for you than a
 stalled agent, set `onUnavailable: "block"` (or `strict: true`, which also blocks every WARN and unsupported request).
 
+Two requests fail closed whatever `onUnavailable` says: `eth_sign` (it signs any 32 bytes, a transaction hash
+included, so an unchecked one could be anything) and an EIP-7702 authorization under `onAuthorization: "check"`.
+
 ## Free limit and the paid route
 
 The check is free, rate limited per IP. The coin a swap buys is read through the same free coins as Toll's coin

package/dist/check.d.ts

@@ -61,8 +61,22 @@ export interface TypedDataLike {
     primaryType: string;
     message: Record<string, unknown>;
 }
+/** A personal_sign / eth_sign message: data is hex (the bytes signed) or text. */
+export interface SignMessageLike {
+    kind: "personal_sign" | "eth_sign";
+    data: string;
+    origin?: string;
+    from?: string;
+}
+/** A wallet RPC request Toll reads as the body it stands for: personal_sign, eth_sign, eth_signTypedData_v4, eth_sendTransaction. */
+export interface RpcLike {
+    method: string;
+    params?: readonly unknown[];
+}
 /**
- * What to check. A transaction ({chainId, from, to, data, value}), an EIP-712 request ({typedData}), an x402 payment
+ * What to check. A transaction ({chainId, from, to, data, value}, with an EIP-7702 authorizationList or not), an
+ * authorization list alone ({chainId, from, authorizationList}), an EIP-712 request ({typedData}), a message
+ * ({message}), a wallet request ({rpc}), an ERC-4337 user operation ({userOp, entryPoint?}), an x402 payment
  * ({x402, agentId?, payment?}), or several together.
  */
 export interface CheckInput {
@@ -71,7 +85,17 @@ export interface CheckInput {
     to?: string;
     data?: string;
     value?: Numberish;
+    /** EIP-7702 authorizations: with to/data a type-4 transaction, alone a signAuthorization */
+    authorizationList?: readonly unknown[];
     typedData?: TypedDataLike;
+    message?: SignMessageLike;
+    rpc?: RpcLike;
+    /** an ERC-4337 user operation (v0.6, v0.7 packed or the RPC form) */
+    userOp?: Record<string, unknown>;
+    /** the user operation's EntryPoint */
+    entryPoint?: string;
+    /** the site asking for the signature (a URL or host name) */
+    origin?: string;
     /** the 402's PaymentRequired, or one of its accepts entries */
     x402?: Record<string, unknown>;
     /** the seller's ERC-8004 agent id, when known */
@@ -97,7 +121,7 @@ export interface CheckOptions {
 export declare class TollBlockedError extends Error {
     readonly assessment: RiskAssessment;
     readonly codes: string[];
-    constructor(assessment: RiskAssessment, why?: Action);
+    constructor(assessment: RiskAssessment, why?: Action | "policy");
 }
 export type UnavailableReason = "network" | "timeout" | "rate-limited" | "server-error" | "bad-request" | "bad-answer" | "unsupported" | "encode";
 export declare class TollUnavailableError extends Error {

package/dist/check.js

@@ -19,7 +19,7 @@ export class TollBlockedError extends Error {
         const top = ws.filter((w) => w.severity !== "low").slice(0, 5);
         const lines = (top.length ? top : ws.slice(0, 5)).map((w) => `${w.code}: ${w.message}`);
         const link = assessment["x-toll"]?.link;
-        super(`Toll ${why}, not signed. ${lines.join(" | ") || "No reason given."}${link ? ` More: ${link}` : ""}`);
+        super(`${why === "policy" ? "Spend policy" : `Toll ${why}`}, not signed. ${lines.join(" | ") || "No reason given."}${link ? ` More: ${link}` : ""}`);
         this.name = "TollBlockedError";
         this.assessment = assessment;
         this.codes = ws.map((w) => w.code);
@@ -61,6 +61,7 @@ const trimBase = (b) => b.replace(/\/+$/, "");
 /** the request body as the route reads it (lib/txcheck.ts parseTxCheckBody): payment rides inside x402 */
 export function bodyOf(input) {
     const b = {};
+    const auths = input.authorizationList !== undefined && input.authorizationList !== null && input.authorizationList.length > 0;
     if (input.to !== undefined || input.data !== undefined) {
         if (input.chainId !== undefined)
             b.chainId = input.chainId;
@@ -69,9 +70,34 @@ export function bodyOf(input) {
         b.to = input.to;
         b.data = input.data ?? "0x";
         b.value = input.value ?? 0;
+        if (auths)
+            b.authorizationList = input.authorizationList;
     }
-    if (input.typedData)
+    else if (auths) {
+        // a signAuthorization alone: the list and its signer
+        if (input.chainId !== undefined)
+            b.chainId = input.chainId;
+        if (input.from !== undefined)
+            b.from = input.from;
+        b.authorizationList = input.authorizationList;
+    }
+    if (input.typedData) {
         b.typedData = input.typedData;
+        // the signer of typed data alone (0.3.1): Toll reads what the signature lets someone take from it
+        if (b.from === undefined && input.from !== undefined)
+            b.from = input.from;
+    }
+    if (input.message)
+        b.message = input.message;
+    if (input.rpc)
+        b.rpc = input.rpc;
+    if (input.userOp) {
+        b.userOp = input.userOp;
+        if (input.entryPoint !== undefined)
+            b.entryPoint = input.entryPoint;
+    }
+    if (input.origin !== undefined)
+        b.origin = input.origin;
     if (input.x402)
         b.x402 = input.payment ? { ...input.x402, payment: input.payment } : input.x402;
     if (input.agentId !== undefined && input.agentId !== null)

package/dist/index.d.ts

@@ -1,10 +1,14 @@
-export { checkTx, chainIdOf, paidUrlOf, isAssessment, TollBlockedError, TollUnavailableError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_RETRY_WAIT_MS, PAID_TX_PATH, PRESIGN_DOCS, TX_CHAIN_ID, } from "./check.js";
-export type { Action, Severity, RiskWarning, ScannerVerdict, TollExtra, RiskAssessment, CheckInput, CheckOptions, TypedDataLike, FetchLike, Hex, Numberish, UnavailableReason, } from "./check.js";
-export { enforce, unsupportedWhy, refuse, gateAuthorization, resolvePolicy, hasHighWarning } from "./policy.js";
-export type { GuardOptions, GuardReport, GuardKind, WarnPolicy, BlockPolicy } from "./policy.js";
-export { guard, guardViem, guardEthers, isViemClient, primaryTypeOf } from "./wallets.js";
+export { checkTx, bodyOf, chainIdOf, paidUrlOf, isAssessment, TollBlockedError, TollUnavailableError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_RETRY_WAIT_MS, PAID_TX_PATH, PRESIGN_DOCS, TX_CHAIN_ID, } from "./check.js";
+export type { Action, Severity, RiskWarning, ScannerVerdict, TollExtra, RiskAssessment, SignMessageLike, RpcLike, CheckInput, CheckOptions, TypedDataLike, FetchLike, Hex, Numberish, UnavailableReason, } from "./check.js";
+export { enforce, enforceCalls, unsupportedWhy, refuse, gateAuthorization, resolvePolicy, hasHighWarning, isSignature, isEthSign, TollPolicyError, commitSpend, releaseSpend, preview } from "./policy.js";
+export type { GuardOptions, GuardReport, GuardKind, WarnPolicy, BlockPolicy, SpendPolicy, Caps, ApprovalRequest, PolicyCode, GuardDecision } from "./policy.js";
+export { guard, guardViem, guardEthers, guardSmartAccount, isViemClient, isBundlerClient, primaryTypeOf } from "./wallets.js";
 export type { ViemGuardOptions } from "./wallets.js";
-export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiffer } from "./x402.js";
+export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiffer, paymentIdOf } from "./x402.js";
 export type { X402GuardOptions } from "./x402.js";
 export { read8470, latestFinding8470, decodeGetObservation, decodeLatestFinding, encodeGetObservation, encodeLatestByToken, encodeLatestFinding, FINDING_KINDS, NOT_READ, OBS_REGISTRY, OBS_DETECTOR, OBS_CHAIN_ID, RH_RPC, } from "./erc8470.js";
 export type { Observation8470, Finding8470, LatestFinding8470, Read8470Options, Lean, KeyKind, Unit } from "./erc8470.js";
+export { spendOf, NATIVE, USDG, WETH, DEFAULT_SPEND_ASSETS, UNLIMITED } from "./spend.js";
+export type { Spend, SpendItem } from "./spend.js";
+export { MemorySpendStore, dayStart } from "./store.js";
+export type { SpendStore } from "./store.js";

package/dist/index.js

@@ -1,5 +1,7 @@
-export { checkTx, chainIdOf, paidUrlOf, isAssessment, TollBlockedError, TollUnavailableError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_RETRY_WAIT_MS, PAID_TX_PATH, PRESIGN_DOCS, TX_CHAIN_ID, } from "./check.js";
-export { enforce, unsupportedWhy, refuse, gateAuthorization, resolvePolicy, hasHighWarning } from "./policy.js";
-export { guard, guardViem, guardEthers, isViemClient, primaryTypeOf } from "./wallets.js";
-export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiffer } from "./x402.js";
+export { checkTx, bodyOf, chainIdOf, paidUrlOf, isAssessment, TollBlockedError, TollUnavailableError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_RETRY_WAIT_MS, PAID_TX_PATH, PRESIGN_DOCS, TX_CHAIN_ID, } from "./check.js";
+export { enforce, enforceCalls, unsupportedWhy, refuse, gateAuthorization, resolvePolicy, hasHighWarning, isSignature, isEthSign, TollPolicyError, commitSpend, releaseSpend, preview } from "./policy.js";
+export { guard, guardViem, guardEthers, guardSmartAccount, isViemClient, isBundlerClient, primaryTypeOf } from "./wallets.js";
+export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiffer, paymentIdOf } from "./x402.js";
 export { read8470, latestFinding8470, decodeGetObservation, decodeLatestFinding, encodeGetObservation, encodeLatestByToken, encodeLatestFinding, FINDING_KINDS, NOT_READ, OBS_REGISTRY, OBS_DETECTOR, OBS_CHAIN_ID, RH_RPC, } from "./erc8470.js";
+export { spendOf, NATIVE, USDG, WETH, DEFAULT_SPEND_ASSETS, UNLIMITED } from "./spend.js";
+export { MemorySpendStore, dayStart } from "./store.js";

package/dist/policy.d.ts

@@ -1,7 +1,9 @@
-import { TollUnavailableError, type CheckInput, type CheckOptions, type RiskAssessment } from "./check.js";
+import { TollBlockedError, TollUnavailableError, type CheckInput, type CheckOptions, type RiskAssessment } from "./check.js";
+import { type Spend } from "./spend.js";
+import { type SpendStore } from "./store.js";
 export type WarnPolicy = "allow" | "block" | "block-high" | ((assessment: RiskAssessment) => boolean | Promise<boolean>);
 export type BlockPolicy = "throw" | ((assessment: RiskAssessment) => boolean | Promise<boolean>);
-export type GuardKind = "transaction" | "typedData" | "x402";
+export type GuardKind = "transaction" | "typedData" | "x402" | "message" | "userOp" | "calls";
 export interface GuardReport {
     kind: GuardKind;
     /** what was sent to Toll (null when nothing was sent) */
@@ -10,11 +12,85 @@ export interface GuardReport {
     assessment: RiskAssessment | null;
     /** what the guard did */
     decision: "allowed" | "blocked";
-    /** why: Toll's action, "unavailable" (Toll could not answer) or "unsupported" (not a request Toll reads) */
-    basis: "ALLOW" | "WARN" | "BLOCK" | "unavailable" | "unsupported";
+    /**
+     * why: Toll's action, "unavailable" (Toll could not answer), "unsupported" (not a request Toll reads) or "policy"
+     * (blocked by your own spend rules: allowlist, cap, approval; `policy` says which)
+     */
+    basis: "ALLOW" | "WARN" | "BLOCK" | "unavailable" | "unsupported" | "policy";
     /** the paid route (no daily limit) when this caller's free checks are used */
     paidUrl: string | null;
     error?: TollUnavailableError;
+    /** the spend rule that blocked it (basis "policy") */
+    policy?: PolicyCode;
+    /** with `spend` set: what the request spends, the day-cap reservations it holds, and the approval reference */
+    spend?: {
+        spend: Spend;
+        reservations: string[];
+        approvalRef?: string;
+        needsApproval?: boolean;
+    };
+}
+export type PolicyCode = "not-allowlisted" | "cap-per-call" | "cap-per-day" | "cap-endpoint" | "approval-denied" | "duplicate-payment" | "unknown-spend";
+export interface Caps {
+    /** the most one request may spend, base units */
+    perCall?: bigint;
+    /** the most all requests together may spend in one UTC day, base units */
+    perDay?: bigint;
+}
+export interface ApprovalRequest {
+    kind: GuardKind;
+    input: CheckInput | null;
+    /** Toll's answer (null when Toll could not answer) */
+    assessment: RiskAssessment | null;
+    spend: Spend;
+    /** each asset over its approveAbove threshold */
+    over: Array<{
+        asset: string;
+        amount: bigint;
+        threshold: bigint;
+    }>;
+}
+/**
+ * Your own rules around Toll's verdict. Order: allowlists (before Toll is asked) -> Toll's ALLOW / WARN / BLOCK
+ * (unchanged) -> per-call and per-day caps -> human approval -> the day reservation is committed after the send
+ * (released when the send throws). Keys are "native" or a token address (any case); amounts are base units.
+ */
+export interface SpendPolicy {
+    /** caps per spend asset; the spend assets are native, WETH and USDG plus every key here and in approveAbove */
+    assets?: Record<string, Caps>;
+    /** x402 caps per endpoint: a URL prefix (origin + path), in the payment asset's base units */
+    perEndpoint?: Record<string, Caps>;
+    /** when a list is given, every recipient / called contract, approval spender or x402 payee must be on it */
+    allow?: {
+        to?: string[];
+        spender?: string[];
+        payTo?: string[];
+    };
+    /** a spend (or allowance) above this amount needs `approve` to say yes */
+    approveAbove?: Record<string, bigint>;
+    /** asks a human (or another system); no function = denied */
+    approve?: (r: ApprovalRequest) => Promise<{
+        approved: boolean;
+        approvalRef?: string;
+    }>;
+    /** a request whose spend could not be read (a contract call Toll did not simulate): default "allow", "block" under failClosed */
+    onUnknownSpend?: "allow" | "block";
+}
+/** blocked by your own spend rules; a TollBlockedError, so existing catch blocks still see a block */
+export declare class TollPolicyError extends TollBlockedError {
+    readonly code: PolicyCode;
+    readonly asset?: string;
+    readonly amount?: bigint;
+    readonly limit?: bigint;
+    /** the guard's report of this request */
+    readonly report?: GuardReport;
+    constructor(code: PolicyCode, message: string, x?: {
+        asset?: string;
+        amount?: bigint;
+        limit?: bigint;
+        assessment?: RiskAssessment | null;
+        report?: GuardReport;
+    });
 }
 export interface GuardOptions extends CheckOptions {
     /**
@@ -44,10 +120,32 @@ export interface GuardOptions extends CheckOptions {
     agentId?: number | string | ((url: string) => number | string | undefined | null);
     /**
      * An EIP-7702 authorization (a transaction's authorizationList, signAuthorization / authorize): it sets the
-     * wallet's code to another contract, which can then move everything the wallet holds. Toll does not read one yet.
-     * "block" (default): TollBlockedError, nothing is signed. "allow": let it through unchecked (logged, reported).
+     * wallet's code to another contract, which can then move everything the wallet holds.
+     * "check" (default since 0.3.0): Toll reads it and decides (a known, verified delegate comes back WARN medium and
+     * passes under onWarn "block-high"; an unknown one comes back BLOCK). It fails closed: when Toll cannot read it
+     * (unreachable, another chain, a request it refuses) it is blocked, whatever onUnavailable / onUnsupported say.
+     * "block": TollBlockedError, nothing is signed, Toll is not asked. "allow": let it through unchecked (logged, reported).
      */
-    onAuthorization?: "block" | "allow";
+    onAuthorization?: "check" | "block" | "allow";
+    /** the site asking for a signature (a URL or host name), sent with messages so Toll can match a sign-in's domain */
+    origin?: string;
+    /** 0.4.0: spend caps, allowlists and human approval around Toll's verdict; unset = 0.3.x behaviour */
+    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") */
+    failClosed?: boolean;
+}
+/** fields the wrappers pass to enforce; not part of the public options */
+export interface InternalOptions extends GuardOptions {
+    /** spend-mode reports of one wrapped call, committed after the send or released when it throws */
+    _collect?: GuardReport[];
+    /** a preview's confirm id: Toll's answer from that preview is reused once when the request is identical */
+    _confirm?: string;
+    /** preview: check everything, reserve nothing, never ask for approval */
+    _preview?: boolean;
+    /** the x402 endpoint URL (per-endpoint caps) */
+    _endpoint?: string;
 }
 /** the effective policy: explicit options win, then the strict preset, then the defaults */
 export declare function resolvePolicy(o?: GuardOptions): {
@@ -57,6 +155,10 @@ export declare function resolvePolicy(o?: GuardOptions): {
 };
 /** 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;
+/** true for eth_sign: it signs any 32 bytes (a transaction hash included), so it fails closed when Toll cannot answer */
+export declare const isEthSign: (input: CheckInput | null | undefined) => boolean;
 /** why Toll would not read this request, or null when it does */
 export declare function unsupportedWhy(input: CheckInput): string | null;
 /**
@@ -70,5 +172,48 @@ export declare function enforce(kind: GuardKind, build: () => CheckInput | Promi
  * disagree): reported as a BLOCK with one critical warning, then TollBlockedError. Nothing is sent to Toll.
  */
 export declare function refuse(kind: GuardKind, input: CheckInput | null, code: string, message: string, o?: GuardOptions): Promise<never>;
-/** the onAuthorization policy for an EIP-7702 authorization: resolves when it may go ahead, else throws */
-export declare function gateAuthorization(kind: GuardKind, where: string, input: CheckInput | null, o?: GuardOptions): Promise<void>;
+/**
+ * The onAuthorization policy for an EIP-7702 authorization. Resolves true when Toll checked the whole request (the
+ * "check" default: the caller asks nothing more), false when "allow" let it through unchecked (the caller still checks
+ * the rest of the request); throws when it is blocked. `input` is the request with its authorizationList, or a function
+ * that builds it; under "check", null is blocked (nothing to send).
+ */
+export declare function gateAuthorization(kind: GuardKind, where: string, input: CheckInput | null | (() => CheckInput | Promise<CheckInput>), o?: GuardOptions): Promise<boolean>;
+/**
+ * A batch (EIP-5792 sendCalls, wallet_sendCalls, a smart account's calls): each call is checked as its own transaction
+ * from the batch's sender, in order; the first one blocked stops the batch. Reports carry kind "calls".
+ */
+export declare function enforceCalls(build: () => CheckInput[] | Promise<CheckInput[]>, o?: GuardOptions): Promise<GuardReport[]>;
+/** the store for these options: the one given, else one in-process store per SpendPolicy object */
+export declare function storeOf(o: GuardOptions): SpendStore;
+/** the reservations of these reports, committed: the request was sent */
+export declare function commitSpend(reports: GuardReport | GuardReport[], o: GuardOptions): Promise<void>;
+/** the reservations of these reports, released: the request was refused or the send threw */
+export declare function releaseSpend(reports: GuardReport | GuardReport[], o: GuardOptions): Promise<void>;
+/** a request the spend policy refuses outside enforce (a repeated x402 payment id): reported, then TollPolicyError */
+export declare function policyRefuse(kind: GuardKind, input: CheckInput | null, code: PolicyCode, message: string, o: GuardOptions): Promise<never>;
+export interface GuardDecision {
+    decision: "allowed" | "blocked";
+    basis: GuardReport["basis"];
+    /** Toll's answer (null when Toll was not asked or could not answer) */
+    assessment: RiskAssessment | null;
+    /** the spend rule that would block it */
+    policy?: PolicyCode;
+    /** what it would spend (with `spend` set) */
+    spend?: Spend;
+    /** over an approveAbove threshold: the send will ask `approve` */
+    needsApproval?: boolean;
+    /** why it would be blocked */
+    reason?: string;
+    paidUrl: string | null;
+}
+/**
+ * What the guard would do with this request, without doing it: Toll is asked and every spend rule is checked, but
+ * nothing is reserved, `approve` is not called and onReport is not called. When allowed, `confirmId` passed as
+ * `tollConfirm` on the send within 30 s skips the second Toll call (once, and only for the identical request).
+ */
+export declare function preview(input: CheckInput, opts?: GuardOptions & {
+    kind?: GuardKind;
+}): Promise<GuardDecision & {
+    confirmId: string;
+}>;