@tollxyz/guard 0.1.2 → 0.2.0

package/README.md

@@ -1,5 +1,10 @@
 # @tollxyz/guard
 
+> **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
 gets ALLOW / WARN / BLOCK with the reasons. Zero runtime dependencies, ESM only, Node >= 20.19, with types.
@@ -15,7 +20,7 @@ const wallet = guard(walletClient);   // viem WalletClient or ethers v6 Signer;
 ```ts
 import { guard, TollBlockedError } from "@tollxyz/guard";
 
-const wallet = guard(walletClient, { onWarn: "allow", onUnavailable: "allow" });
+const wallet = guard(walletClient, { onWarn: "block-high", onUnavailable: "allow" });
 try {
   await wallet.writeContract({ address: token, abi: erc20Abi, functionName: "approve", args: [spender, maxUint256] });
 } catch (e) {
@@ -107,10 +112,11 @@ is at most `maxRetryWaitMs` (default 10 s); a coin still not read stays WARN, ne
 
 | Option | Default | |
 | --- | --- | --- |
-| `onWarn` | `"allow"` | `"allow"` (logged and reported), `"block"`, or `(assessment) => boolean` (true lets it through) |
+| `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"` | Toll unreachable, timed out, 5xx, 429, or a request it could not read: `"allow"` (fail-open, logged) or `"block"` (fail-closed, TollUnavailableError) |
-| `onUnsupported` | `"allow"` | another chain, a deployment: `"allow"` or `"block"` |
+| `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) |
 | `onReport` | none | `(report) => void`: every decision, with `assessment`, `decision`, `basis`, `paidUrl` |
 | `logger` | `console.warn` | where WARN and unavailable lines go; `false` = silent |
@@ -126,13 +132,13 @@ Errors: `TollBlockedError` (`.assessment`, `.codes`, message lists each code and
 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"`.
+stalled agent, set `onUnavailable: "block"` (or `strict: true`, which also blocks every WARN and unsupported request).
 
 ## 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
 check (10 new coins a day per caller, coins already read stay free); past that the coin is not read and the answer
-is WARN `coin-over-quota` naming the paid route, `https://t0ll.xyz/api/x402/tx` (0.01 USDG over x402, no daily
+is WARN `coin-over-quota` naming the paid route, `https://t0ll.xyz/api/x402/tx` (0.005 USDG over x402, no daily
 limit). The guard never pays: it puts that URL in the log line, in `report.paidUrl` and in `paidUrlOf(assessment)`.
 
 ## Privacy

package/dist/check.d.ts

@@ -5,7 +5,7 @@
 export declare const DEFAULT_BASE_URL = "https://t0ll.xyz";
 /** Robinhood Chain: the only chain the pre-sign check reads for now */
 export declare const TX_CHAIN_ID = 4663;
-/** the paid route without the daily limit (0.01 USDG over x402); the guard never pays it */
+/** the paid route without the daily limit (0.005 USDG over x402); the guard never pays it */
 export declare const PAID_TX_PATH = "/api/x402/tx";
 export declare const PRESIGN_DOCS = "https://t0ll.xyz/agents/x402#presign";
 export declare const DEFAULT_TIMEOUT_MS = 15000;

package/dist/check.js

@@ -5,7 +5,7 @@
 export const DEFAULT_BASE_URL = "https://t0ll.xyz";
 /** Robinhood Chain: the only chain the pre-sign check reads for now */
 export const TX_CHAIN_ID = 4663;
-/** the paid route without the daily limit (0.01 USDG over x402); the guard never pays it */
+/** the paid route without the daily limit (0.005 USDG over x402); the guard never pays it */
 export const PAID_TX_PATH = "/api/x402/tx";
 export const PRESIGN_DOCS = "https://t0ll.xyz/agents/x402#presign";
 export const DEFAULT_TIMEOUT_MS = 15_000;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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 } from "./policy.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 type { ViemGuardOptions } from "./wallets.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 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 } from "./policy.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 { read8470, latestFinding8470, decodeGetObservation, decodeLatestFinding, encodeGetObservation, encodeLatestByToken, encodeLatestFinding, FINDING_KINDS, NOT_READ, OBS_REGISTRY, OBS_DETECTOR, OBS_CHAIN_ID, RH_RPC, } from "./erc8470.js";

package/dist/policy.d.ts

@@ -1,5 +1,5 @@
 import { TollUnavailableError, type CheckInput, type CheckOptions, type RiskAssessment } from "./check.js";
-export type WarnPolicy = "allow" | "block" | ((assessment: RiskAssessment) => boolean | Promise<boolean>);
+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 interface GuardReport {
@@ -17,17 +17,25 @@ export interface GuardReport {
     error?: TollUnavailableError;
 }
 export interface GuardOptions extends CheckOptions {
-    /** WARN: "allow" (default, reported and logged), "block", or a function; true lets it through */
+    /**
+     * WARN: "block-high" (default since 0.2.0: 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 a function (true lets it through)
+     */
     onWarn?: WarnPolicy;
     /** 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).
+     * "block" (fail-closed, throws TollUnavailableError). `strict` makes "block" the default.
      */
     onUnavailable?: "allow" | "block";
-    /** a request Toll does not read (another chain, a contract deploy): "allow" (default) or "block" */
+    /** a request Toll does not read (another chain, a contract deploy): "allow" (default) or "block"; `strict`: "block" */
     onUnsupported?: "allow" | "block";
+    /**
+     * The strict preset: the defaults become onWarn "block", onUnavailable "block" and onUnsupported "block".
+     * Any of those three passed explicitly (not undefined) still wins over the preset.
+     */
+    strict?: boolean;
     /** every decision, with Toll's answer; errors thrown here are caught and logged */
     onReport?: (report: GuardReport) => void | Promise<void>;
     /** where WARN / unavailable lines go (default console.warn); false = silent */
@@ -41,6 +49,14 @@ export interface GuardOptions extends CheckOptions {
      */
     onAuthorization?: "block" | "allow";
 }
+/** the effective policy: explicit options win, then the strict preset, then the defaults */
+export declare function resolvePolicy(o?: GuardOptions): {
+    onWarn: WarnPolicy;
+    onUnavailable: "allow" | "block";
+    onUnsupported: "allow" | "block";
+};
+/** true when any warning is high or critical */
+export declare const hasHighWarning: (a: RiskAssessment) => boolean;
 /** why Toll would not read this request, or null when it does */
 export declare function unsupportedWhy(input: CheckInput): string | null;
 /**

package/dist/policy.js

@@ -1,4 +1,16 @@
 import { TX_CHAIN_ID, TollBlockedError, TollUnavailableError, checkTx, chainIdOf, paidUrlOf, } from "./check.js";
+/** the effective policy: explicit options win, then the strict preset, then the defaults */
+export function resolvePolicy(o = {}) {
+    const strict = o.strict === true;
+    return {
+        onWarn: o.onWarn ?? (strict ? "block" : "block-high"),
+        onUnavailable: o.onUnavailable ?? (strict ? "block" : "allow"),
+        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()));
 const say = (o, msg) => {
     if (o.logger === false)
         return;
@@ -57,11 +69,11 @@ export async function enforce(kind, build, o = {}) {
     }
     const why = unsupportedWhy(input);
     if (why) {
-        const blocked = o.onUnsupported === "block";
+        const blocked = resolvePolicy(o).onUnsupported === "block";
         const r = { kind, input, assessment: null, decision: blocked ? "blocked" : "allowed", basis: "unsupported", paidUrl: null };
         await report(o, r);
         if (blocked)
-            throw new TollUnavailableError(`Not checked by Toll: ${why}. onUnsupported is "block".`, { reason: "unsupported" });
+            throw new TollUnavailableError(`Not checked by Toll: ${why}. onUnsupported is "block"${o.strict === true && o.onUnsupported === undefined ? " (strict)" : ""}.`, { reason: "unsupported" });
         return r;
     }
     let a;
@@ -90,8 +102,8 @@ export async function enforce(kind, build, o = {}) {
         throw new TollBlockedError(a, "BLOCK");
     }
     // WARN, and anything that is not one of the three actions: never treated as an ALLOW
-    const p = o.onWarn ?? "allow";
-    const ok = p === "allow" ? true : p === "block" ? false : (await p(a)) === true;
+    const p = resolvePolicy(o).onWarn;
+    const ok = p === "allow" ? true : p === "block" ? false : p === "block-high" ? !hasHighWarning(a) : (await p(a)) === true;
     if (ok) {
         say(o, `WARN (${kind}), going ahead: ${a.warnings.map((w) => `${w.code}: ${w.message}`).join(" | ")}${paidUrl ? ` Paid, no daily limit: ${paidUrl}` : ""}`);
         return done("allowed", "WARN");
@@ -100,7 +112,7 @@ export async function enforce(kind, build, o = {}) {
     throw new TollBlockedError(a, "WARN");
 }
 async function unavailable(kind, input, err, o) {
-    const blocked = o.onUnavailable === "block";
+    const blocked = resolvePolicy(o).onUnavailable === "block";
     const r = { kind, input, assessment: null, decision: blocked ? "blocked" : "allowed", basis: "unavailable", paidUrl: err.paidUrl, error: err };
     await report(o, r);
     if (blocked)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tollxyz/guard",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Toll's live pre-sign check in front of an AI agent's wallet: viem, ethers and x402 fetch wrappers that ask Toll (ALLOW / WARN / BLOCK, ERC-8265) before anything is signed on Robinhood Chain. Zero runtime dependencies.",
   "license": "MIT",
   "author": "Toll",