@tollxyz/guard 0.1.1 → 0.1.2

package/README.md

@@ -70,6 +70,11 @@ Returns the same wallet behind a Proxy. Checked first:
   `signTransaction`, `signTypedData`
 - ethers v6 Signer: `sendTransaction`, `signTransaction`, `signTypedData`
 
+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.
+
 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.
 
@@ -79,6 +84,10 @@ Wraps the fetch your x402 client uses. When a 402 arrives, its payment requireme
 pays; on BLOCK the 402 never reaches the payer (TollBlockedError is thrown). The paid retry (a request with a
 `PAYMENT-SIGNATURE` or `X-PAYMENT` header) and every non-402 answer pass through.
 
+A 402 can carry its requirement in the `PAYMENT-REQUIRED` header and in the JSON body, and a client pays from the one
+it reads (`x402-fetch` v1 reads the body). The guard reads both: when they ask for different payments (payee, amount,
+asset or scheme), it blocks without asking Toll (code `x402-forms-differ`).
+
 ```ts
 import { wrapFetchWithPayment } from "x402-fetch";
 const pay = wrapFetchWithPayment(guardX402Fetch(fetch, { agentId: 123 }), account);
@@ -102,6 +111,7 @@ is at most `maxRetryWaitMs` (default 10 s); a coin still not read stays WARN, ne
 | `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"` |
+| `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 |
 | `timeoutMs` | `15000` | one request to Toll |

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 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 } from "./policy.js";
+export { enforce, unsupportedWhy, refuse, gateAuthorization } 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";
-export { guardX402Fetch, readPaymentRequired } from "./x402.js";
+export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiffer } 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";

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 } from "./policy.js";
+export { enforce, unsupportedWhy, refuse, gateAuthorization } from "./policy.js";
 export { guard, guardViem, guardEthers, isViemClient, primaryTypeOf } from "./wallets.js";
-export { guardX402Fetch, readPaymentRequired } from "./x402.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

@@ -34,6 +34,12 @@ export interface GuardOptions extends CheckOptions {
     logger?: ((message: string) => void) | false;
     /** the seller's ERC-8004 agent id for x402 payments (or a function of the URL) */
     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).
+     */
+    onAuthorization?: "block" | "allow";
 }
 /** why Toll would not read this request, or null when it does */
 export declare function unsupportedWhy(input: CheckInput): string | null;
@@ -43,3 +49,10 @@ export declare function unsupportedWhy(input: CheckInput): string | null;
  * `build` may throw (e.g. calldata that could not be encoded): that counts as unavailable.
  */
 export declare function enforce(kind: GuardKind, build: () => CheckInput | Promise<CheckInput>, o?: GuardOptions): Promise<GuardReport>;
+/**
+ * A request the guard refuses itself, without asking Toll (EIP-7702 authorizations, an x402 402 whose header and body
+ * 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>;

package/dist/policy.js

@@ -108,3 +108,21 @@ async function unavailable(kind, input, err, o) {
     say(o, `Toll unavailable, NOT checked, going ahead (onUnavailable "allow"): ${err.message}`);
     return r;
 }
+/**
+ * A request the guard refuses itself, without asking Toll (EIP-7702 authorizations, an x402 402 whose header and body
+ * disagree): reported as a BLOCK with one critical warning, then TollBlockedError. Nothing is sent to Toll.
+ */
+export async function refuse(kind, input, code, message, o = {}) {
+    const a = { action: "BLOCK", warnings: [{ code, severity: "critical", message }] };
+    await report(o, { kind, input, assessment: a, decision: "blocked", basis: "BLOCK", paidUrl: null });
+    throw new TollBlockedError(a, "BLOCK");
+}
+/** the onAuthorization policy for an EIP-7702 authorization: resolves when it may go ahead, else throws */
+export async function gateAuthorization(kind, where, input, o = {}) {
+    if (o.onAuthorization === "allow") {
+        say(o, `EIP-7702 authorization (${where}) NOT checked, going ahead (onAuthorization "allow")`);
+        await report(o, { kind, input, assessment: null, decision: "allowed", basis: "unsupported", paidUrl: null });
+        return;
+    }
+    await refuse(kind, input, "eip7702-authorization", `${where} carries an EIP-7702 authorization, which sets this wallet's code to another contract that can then move everything it holds. Toll does not read authorizations yet; onAuthorization: "allow" lets it through unchecked.`, o);
+}

package/dist/wallets.d.ts

@@ -16,8 +16,10 @@ export interface ViemGuardOptions extends GuardOptions {
     }) => Hex | string;
 }
 /**
- * Wraps a viem WalletClient: sendTransaction, writeContract, signTransaction and signTypedData ask Toll first.
- * Wrap last: `client.extend(...)` on the wrapped client returns an unguarded client.
+ * Wraps a viem WalletClient: sendTransaction, writeContract, signTransaction and signTypedData ask Toll first. An
+ * EIP-7702 authorization (an authorizationList on any of them, or signAuthorization) goes to onAuthorization
+ * (default: blocked). Wrap last: `client.extend(...)` on the wrapped client returns an unguarded client, and the
+ * account's own sign methods (client.account.sign*) are not wrapped.
  */
 export declare function guardViem<T extends object>(client: T, opts?: ViemGuardOptions): T;
 /** the EIP-712 primary type: the one type no other type refers to (as ethers' TypedDataEncoder.getPrimaryType) */
@@ -26,7 +28,8 @@ export declare function primaryTypeOf(types: Record<string, Array<{
     type: string;
 }>>): string;
 /**
- * Wraps an ethers v6 Signer: sendTransaction, signTransaction and signTypedData ask Toll first.
+ * Wraps an ethers v6 Signer: sendTransaction, signTransaction and signTypedData ask Toll first. An EIP-7702
+ * authorization (a transaction's authorizationList, or authorize()) goes to onAuthorization (default: blocked).
  * `signer.connect(provider)` returns an unguarded signer: wrap the connected one.
  */
 export declare function guardEthers<T extends object>(signer: T, opts?: GuardOptions): T;

package/dist/wallets.js

@@ -3,7 +3,7 @@
  * The wrapper is a Proxy: every other method and field of the client passes through unchanged.
  */
 import { isAddress } from "./check.js";
-import { enforce } from "./policy.js";
+import { enforce, gateAuthorization } from "./policy.js";
 /** wraps an object's methods; everything else passes through, bound to the original */
 function proxy(target, wrapped) {
     return new Proxy(target, {
@@ -15,6 +15,11 @@ function proxy(target, wrapped) {
         },
     });
 }
+/** a transaction that carries an EIP-7702 authorizationList (any entry at all) */
+const hasAuthorizations = (tx) => {
+    const l = tx?.authorizationList;
+    return l !== undefined && l !== null && (!Array.isArray(l) || l.length > 0);
+};
 const addrOf = (account) => {
     if (isAddress(account))
         return account;
@@ -34,8 +39,10 @@ async function loadViemEncode() {
     return viemEncode;
 }
 /**
- * Wraps a viem WalletClient: sendTransaction, writeContract, signTransaction and signTypedData ask Toll first.
- * Wrap last: `client.extend(...)` on the wrapped client returns an unguarded client.
+ * Wraps a viem WalletClient: sendTransaction, writeContract, signTransaction and signTypedData ask Toll first. An
+ * EIP-7702 authorization (an authorizationList on any of them, or signAuthorization) goes to onAuthorization
+ * (default: blocked). Wrap last: `client.extend(...)` on the wrapped client returns an unguarded client, and the
+ * account's own sign methods (client.account.sign*) are not wrapped.
  */
 export function guardViem(client, opts = {}) {
     const c = client;
@@ -52,18 +59,24 @@ export function guardViem(client, opts = {}) {
     if (typeof c.sendTransaction === "function") {
         wrapped.sendTransaction = async (args, ...rest) => {
             // a deployment (no `to`) goes to the unsupported policy
+            if (hasAuthorizations(args))
+                await gateAuthorization("transaction", "sendTransaction", txInput(args, args?.data), opts);
             await enforce("transaction", () => txInput(args, args?.data), opts);
             return c.sendTransaction(args, ...rest);
         };
     }
     if (typeof c.signTransaction === "function") {
         wrapped.signTransaction = async (args, ...rest) => {
+            if (hasAuthorizations(args))
+                await gateAuthorization("transaction", "signTransaction", txInput(args, args?.data), opts);
             await enforce("transaction", () => txInput(args, args?.data), opts);
             return c.signTransaction(args, ...rest);
         };
     }
     if (typeof c.writeContract === "function") {
         wrapped.writeContract = async (args, ...rest) => {
+            if (hasAuthorizations(args))
+                await gateAuthorization("transaction", "writeContract", null, opts);
             await enforce("transaction", async () => {
                 const enc = opts.encodeFunctionData ?? (await loadViemEncode());
                 let data = String(enc({ abi: args.abi, functionName: args.functionName, args: args.args }));
@@ -81,6 +94,12 @@ export function guardViem(client, opts = {}) {
             return c.signTypedData(args, ...rest);
         };
     }
+    if (typeof c.signAuthorization === "function") {
+        wrapped.signAuthorization = async (...args) => {
+            await gateAuthorization("transaction", "signAuthorization", null, opts);
+            return c.signAuthorization(...args);
+        };
+    }
     return proxy(client, wrapped);
 }
 /* ------------------------------------------------------------------ ethers v6 */
@@ -126,7 +145,8 @@ async function ethersTx(signer, tx) {
     };
 }
 /**
- * Wraps an ethers v6 Signer: sendTransaction, signTransaction and signTypedData ask Toll first.
+ * Wraps an ethers v6 Signer: sendTransaction, signTransaction and signTypedData ask Toll first. An EIP-7702
+ * authorization (a transaction's authorizationList, or authorize()) goes to onAuthorization (default: blocked).
  * `signer.connect(provider)` returns an unguarded signer: wrap the connected one.
  */
 export function guardEthers(signer, opts = {}) {
@@ -134,12 +154,16 @@ export function guardEthers(signer, opts = {}) {
     const wrapped = {};
     if (typeof s.sendTransaction === "function") {
         wrapped.sendTransaction = async (tx, ...rest) => {
+            if (hasAuthorizations(tx))
+                await gateAuthorization("transaction", "sendTransaction", null, opts);
             await enforce("transaction", () => ethersTx(s, tx), opts);
             return s.sendTransaction(tx, ...rest);
         };
     }
     if (typeof s.signTransaction === "function") {
         wrapped.signTransaction = async (tx, ...rest) => {
+            if (hasAuthorizations(tx))
+                await gateAuthorization("transaction", "signTransaction", null, opts);
             await enforce("transaction", () => ethersTx(s, tx), opts);
             return s.signTransaction(tx, ...rest);
         };
@@ -150,6 +174,12 @@ export function guardEthers(signer, opts = {}) {
             return s.signTypedData(domain, types, value, ...rest);
         };
     }
+    if (typeof s.authorize === "function") {
+        wrapped.authorize = async (...args) => {
+            await gateAuthorization("transaction", "authorize", null, opts);
+            return s.authorize(...args);
+        };
+    }
     return proxy(signer, wrapped);
 }
 /* ------------------------------------------------------------------ either */

package/dist/x402.d.ts

@@ -1,7 +1,19 @@
 import { type GuardOptions, type GuardReport } from "./policy.js";
 type AnyFetch = (input: any, init?: any) => Promise<Response>;
+type PR = Record<string, unknown>;
+/**
+ * Both places a 402 can carry its PaymentRequired: the PAYMENT-REQUIRED header (v2) and the JSON body (v1, and v2
+ * servers that also put it there). A client pays from the one it reads (x402-fetch v1 reads the body), so the guard
+ * reads both.
+ */
+export declare function readPaymentForms(res: Response): Promise<{
+    header: PR | null;
+    body: PR | null;
+}>;
 /** the 402's PaymentRequired: v2 from the PAYMENT-REQUIRED header, else v1 from the JSON body; null when neither */
-export declare function readPaymentRequired(res: Response): Promise<Record<string, unknown> | null>;
+export declare function readPaymentRequired(res: Response): Promise<PR | null>;
+/** true when the header and the body would pay differently (a payee, amount, asset or scheme in one and not the other) */
+export declare function paymentFormsDiffer(header: PR, body: PR): boolean;
 export interface X402GuardOptions extends GuardOptions {
     /** called with each 402's report (also passed to onReport) */
     on402?: (report: GuardReport, url: string) => void;

package/dist/x402.js

@@ -1,30 +1,54 @@
-import { enforce } from "./policy.js";
+import { enforce, refuse } from "./policy.js";
 function decodeBase64Json(value) {
     const bin = atob(value.trim());
     return JSON.parse(new TextDecoder().decode(Uint8Array.from(bin, (c) => c.charCodeAt(0))));
 }
-/** the 402's PaymentRequired: v2 from the PAYMENT-REQUIRED header, else v1 from the JSON body; null when neither */
-export async function readPaymentRequired(res) {
+const withAccepts = (x) => x && typeof x === "object" && Array.isArray(x.accepts) && x.accepts.length ? x : null;
+/**
+ * Both places a 402 can carry its PaymentRequired: the PAYMENT-REQUIRED header (v2) and the JSON body (v1, and v2
+ * servers that also put it there). A client pays from the one it reads (x402-fetch v1 reads the body), so the guard
+ * reads both.
+ */
+export async function readPaymentForms(res) {
+    let header = null;
+    let body = null;
     const h = res.headers.get("payment-required");
     if (h) {
         try {
-            const pr = decodeBase64Json(h);
-            if (pr && Array.isArray(pr.accepts) && pr.accepts.length)
-                return pr;
+            header = withAccepts(decodeBase64Json(h));
         }
         catch {
-            /* fall back to the body */
+            /* not base64 JSON */
         }
     }
     try {
-        const body = JSON.parse(await res.clone().text());
-        if (body && Array.isArray(body.accepts) && body.accepts.length)
-            return body;
+        body = withAccepts(JSON.parse(await res.clone().text()));
     }
     catch {
         /* not JSON */
     }
-    return null;
+    return { header, body };
+}
+/** the 402's PaymentRequired: v2 from the PAYMENT-REQUIRED header, else v1 from the JSON body; null when neither */
+export async function readPaymentRequired(res) {
+    const { header, body } = await readPaymentForms(res);
+    return header ?? body;
+}
+/** what a client would pay under each accepts entry: scheme, asset, amount (v2 amount or v1 maxAmountRequired), payee */
+function terms(pr) {
+    const low = (v) => String(v ?? "").trim().toLowerCase();
+    return pr.accepts
+        .map((a) => {
+        const x = (a && typeof a === "object" ? a : {});
+        return [low(x.scheme), low(x.asset), low(x.amount ?? x.maxAmountRequired), low(x.payTo)].join("|");
+    })
+        .sort();
+}
+/** true when the header and the body would pay differently (a payee, amount, asset or scheme in one and not the other) */
+export function paymentFormsDiffer(header, body) {
+    const a = terms(header);
+    const b = terms(body);
+    return a.length !== b.length || a.some((t, i) => t !== b[i]);
 }
 const urlOf = (input) => {
     if (typeof input === "string")
@@ -60,7 +84,13 @@ export function guardX402Fetch(fetchLike, opts = {}) {
         if (res.status !== 402 || hasPayment(input, init))
             return res;
         const url = urlOf(input);
-        const pr = await readPaymentRequired(res);
+        const forms = await readPaymentForms(res);
+        // A harmless header and another payTo or amount in the body: the guard cannot know which one the client pays
+        // (x402-fetch v1 pays the body), so it refuses the 402.
+        if (forms.header && forms.body && paymentFormsDiffer(forms.header, forms.body)) {
+            await refuse("x402", { x402: { ...forms.header, url } }, "x402-forms-differ", "The 402's PAYMENT-REQUIRED header and its JSON body ask for different payments (payee, amount, asset or scheme). A client pays from the one it reads, so it was not paid.", toll);
+        }
+        const pr = forms.header ?? forms.body;
         const r = await enforce("x402", () => {
             if (!pr)
                 return {}; // nothing readable: the unsupported policy decides

package/package.json

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