@tollxyz/guard 0.5.0 → 0.6.1

package/README.md

@@ -22,6 +22,17 @@
 > - `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.
 
+> **Default changed in 0.6.0: the guard fails closed.** When Toll cannot or will not answer (unreachable, timeout,
+> 429, 5xx, HTTP 400 or 413, an answer that is not a RiskAssessment) nothing is signed: `TollUnavailableError`, with
+> "Not signed" in the message. Before, such a request went ahead unchecked, so whoever built the request could
+> switch the check off (a request padded past Toll's 64 KB limit answers 413). To keep the old behaviour pass
+> `failOpen: true` (or `onUnavailable: "allow"`), and know that it lets anyone who can shape the request skip the check.
+
+> **Also in 0.6.0.** With a `spend` policy, a request whose spend cannot be read (a contract call Toll did not simulate,
+> an x402 amount such as `"+5000000"` or a value that does not parse) is refused by default: `onUnknownSpend: "allow"`
+> opts out. A WARN that says the coin was not read yet (`coin-not-read`) is refused under the default `block-high`.
+> Fixed: `transferFrom`'s recipient was read from the amount word, so an allowlist refused every `transferFrom`.
+
 > **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
@@ -93,6 +104,18 @@ Robinhood Chain (4663) only for now. A transaction on another chain, or a contra
 and goes through (`onUnsupported: "block"` to stop it instead). A signature for another chain is blocked
 (`onUnsupported: "allow"` lets it through).
 
+## Building on Hookr
+
+A wallet behind the guard that signs a call built by [Hookr](https://hookr.fun)'s MCP server
+(`https://hookr.fun/api/mcp`: `hookr_build_swap`, `hookr_build_launch`, `hookr_build_claim`, `hookr_build_agent_link`,
+`hookr_build_fill`, the liquidity builders) has that call checked like any other: the guard sends it to Toll with the
+wallet as `from` before anything is signed. Toll reads HookrRouter swaps, HookrLauncher launches (the token, the
+pools, who holds the liquidity, a dev buy), a launch's own withdrawal and fee collection, a pool core's claim, the
+Agent gate link and the order book fill. Each is named as Hookr's contract, not audited (`hookr-contract`, low); an
+unknown hook, rules contract or add-on is a warning, and a payout to anyone but `from` is `hookr-pays-other` (high).
+Any other function of those contracts is `calldata-undecoded`: WARN, never ALLOW. Nothing to configure: the checks are
+on Toll's server. Steps: <https://t0ll.xyz/hooks/hookr#agents>
+
 ## API
 
 ### `guard(wallet, opts?)`, `guardViem(client, opts?)`, `guardSmartAccount(bundler, opts?)`, `guardEthers(signer, opts?)`
@@ -166,7 +189,8 @@ is at most `maxRetryWaitMs` (default 10 s); a coin still not read stays WARN, ne
 | `strict` | `false` | preset: the defaults of `onWarn`, `onUnavailable` and `onUnsupported` become `"block"`; each one passed explicitly still wins |
 | `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) |
+| `onUnavailable` | `"block"` (since 0.6.0) | Toll unreachable, timed out, 5xx, 429, any other non-2xx (400, 413) or an answer that is not a RiskAssessment: `"block"` (fail-closed, TollUnavailableError) or `"allow"` (fail-open, logged). Passed explicitly it wins over `failOpen` and `strict` |
+| `failOpen` | `false` | 0.6.0: `true` = the old default: when Toll cannot or will not answer, the request goes ahead unchecked (logged). `strict` and an explicit `onUnavailable` win over it |
 | `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 |
@@ -177,7 +201,7 @@ is at most `maxRetryWaitMs` (default 10 s); a coin still not read stays WARN, ne
 | `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 |
+| `failClosed` | `false` | with `spend`: a request whose spend cannot be read is blocked (the default since 0.6.0; `onUnknownSpend: "allow"` opts out) |
 | `ticket` | none | 0.4.1: `true` or `{consumer?, scope?}`: ask Toll for a single-use ALLOW ticket for this exact call; it comes back as `report.ticket` ([below](#allow-tickets)) |
 
 Errors: `TollBlockedError` (`.assessment`, `.codes`, message lists each code and message) and
@@ -241,7 +265,7 @@ Robinhood Chain, plus every asset you name in `assets` or `approveAbove`. A sell
 - 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`.
+  authorization. `onUnknownSpend` decides: `"block"` by default since 0.6.0 (caps that bind only on plain transfers are not caps), `"allow"` to opt out. An x402 amount or a transaction value the guard cannot parse is an unknown spend too.
 
 | `spend` field | |
 | --- | --- |
@@ -250,7 +274,7 @@ Robinhood Chain, plus every asset you name in `assets` or `approveAbove`. A sell
 | `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`) |
+| `onUnknownSpend` | `"block"` (default since 0.6.0) or `"allow"` |
 
 New options next to `spend`: `store` (where counters live, below) and `failClosed`.
 
@@ -342,12 +366,12 @@ export const redisStore: SpendStore = {
 const wallet = guard(walletClient, { spend: { /* ... */ }, store: redisStore });
 ```
 
-## 0.5.0: mirror the caps into the facilitator budget (coming)
+## 0.5.0: mirror the caps into the facilitator budget
 
-guard's caps live in the agent's process. Toll's x402 facilitator (https://x402.t0ll.xyz) is adding per-payer budgets: the
+guard's caps live in the agent's process. Toll's x402 facilitator (https://x402.t0ll.xyz) has per-payer budgets (live since 2026-11-11): the
 payer wallet signs its limits once and the facilitator refuses any payment past them where it settles, so a second
-process, a key used elsewhere or a bug in the agent cannot spend past them through it. Budgets are **coming**: the
-facilitator answers `404 budgets_off` until they are switched on. `guardBudget` builds that budget from your `spend`
+process, a key used elsewhere or a bug in the agent cannot spend past them through it. If budgets are ever switched
+off the facilitator answers `404 budgets_off`. `guardBudget` builds that budget from your `spend`
 policy; guard itself behaves exactly as before.
 
 ```ts
@@ -419,12 +443,18 @@ should keep an owner bypass behind a timelock in case Toll is unreachable.
 
 ## Fail-open or fail-closed
 
-The default is fail-open: if Toll cannot answer, the signature goes ahead, with a `[toll-guard] ... NOT checked`
-line and an `onReport` call with `basis: "unavailable"`. The agent must never get stuck because of Toll, and the
-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).
+The default is fail-closed since 0.6.0: if Toll cannot or will not answer, nothing is signed. The guard throws
+`TollUnavailableError` (its `reason` says why: `network`, `timeout`, `rate-limited`, `server-error`, `bad-request`,
+`bad-answer`) and calls `onReport` with `decision: "blocked"`, `basis: "unavailable"`. The reason for the default: a
+refusal can be caused on purpose. A request padded past Toll's size limit answers HTTP 413, and a guard that let
+"not checked" through would sign it.
+
+The free route is rate limited per IP (a busy agent will see 429s): catch `TollUnavailableError`, wait and ask again,
+or use the paid route the error names in `paidUrl`. If a stalled agent is worse for you than an unchecked signature,
+pass `failOpen: true`: the request then goes ahead with a `[toll-guard] ... NOT checked` line and an `onReport` call
+with `decision: "allowed"`, `basis: "unavailable"`. `strict: true` also blocks every WARN and unsupported request.
 
-Two requests fail closed whatever `onUnavailable` says: `eth_sign` (it signs any 32 bytes, a transaction hash
+Two requests fail closed whatever `onUnavailable` and `failOpen` say: `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

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,6 +1,6 @@
 {
   "name": "@tollxyz/guard",
-  "version": "0.5.0",
+  "version": "0.6.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",