verify402-mcp 1.0.4 → 1.0.6

package/.env.example

@@ -3,9 +3,9 @@
 # The bridge runs without any of these. With no EVM_PRIVATE_KEY it exposes only
 # the free preflight_gate. Set a key only when you want the five paid checks.
 #
-# EVM_PRIVATE_KEY is a dedicated hot wallet that pays for calls in USDC. Use a
-# wallet with only the money you are willing to spend. NEVER commit the real
-# .env and never use a main wallet.
+# EVM_PRIVATE_KEY is a dedicated hot wallet that pays for calls in testnet
+# USDC on the public demo. Use a wallet with only the money you are willing to
+# spend. NEVER commit the real .env and never use a main wallet.
 EVM_PRIVATE_KEY=           # optional; omit for the free gate only
 VERIFY402_URL=https://verify402.onrender.com
 # spend controls (paid tools only)
@@ -13,8 +13,11 @@ MAX_PAYMENT_USD=0.25      # cap on ONE payment, enforced at signature time
 MAX_DAILY_USD=0.50        # cap on the whole UTC day, survives restarts; omit to disable
 SPEND_LEDGER_PATH=        # optional override for the ledger file (default .spend-ledger.json)
 
-# payment allowlist (paid tools only; these are the defaults)
-VERIFY402_NETWORKS=eip155:8453
+# payment allowlist (paid tools only; these are the public-demo defaults)
+# Base Sepolia testnet: the live demo's EVM payment rail.
+VERIFY402_NETWORKS=eip155:84532
 VERIFY402_PAY_TO=0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb
 # VERIFY402_RESOURCE_PREFIX=https://verify402.onrender.com
-# For local testnet, set VERIFY402_NETWORKS=eip155:84532 and the payee the local server names.
+# Explicit mainnet is a separate deployment, not a demo setting. Set this only
+# after separate readiness verification, with a mainnet facilitator and host:
+# VERIFY402_NETWORKS=eip155:8453

package/README.md

@@ -5,8 +5,18 @@ agent signs a payment or a chain transaction, plus five paid on-chain checks
 paid per call over x402.
 
 Works with Claude Desktop, Cursor, OpenCode, and any MCP client that speaks
-stdio. The free gate needs **no wallet**. The paid tools use a dedicated hot
-wallet that pays in USDC; the bridge never signs or sends a trade.
+stdio. The free gate needs **no wallet**. The public demo's paid tools use a
+dedicated hot wallet funded with **Base Sepolia testnet USDC** (`eip155:84532`).
+The analysis reads mainnet chain data, but the demo never settles mainnet
+payments. The bridge never signs or sends a trade.
+
+> **Published package note:** `verify402-mcp@1.0.6` is published to npm and
+> defaults paid calls to Base Sepolia testnet (`eip155:84532`) for the public
+> demo. Base mainnet (`eip155:8453`) requires an explicit `VERIFY402_NETWORKS`
+> opt-in in a separate deployment and is not enabled by this release. The
+> previously published `1.0.5` package is immutable; `1.0.4` is also immutable
+> and used Base mainnet by default. Do not republish or overwrite either
+> version.
 
 ## Tools
 
@@ -24,6 +34,13 @@ transaction or x402 payment request. If `sign_allowed` is false, **do not
 sign**. If `requires_ack` is true, surface the reasons to the operator. The
 receipt expires (default 90s); call again instead of reusing it.
 
+For payment intents, `policy.allowedResourceHosts` binds the host in
+`payment.resource`; a matching host can PASS and a foreign host is BLOCK.
+Without `allowedResourceHosts` or `expectedResource`, an otherwise valid
+resource is CAUTION `resource_identity_unverified` and `resource identity` is
+listed in `notChecked`. The bridge forwards this policy to the server; the
+server enforces it.
+
 The gate is advisory at this layer: the bridge does not hold the agent's
 transaction key and cannot stop an agent that ignores the answer. Enforcement
 belongs in the executor that signs — verify the receipt, then sign. See
@@ -85,11 +102,12 @@ To enable the 5 deep on-chain truth checks (`verify_arbitrage`, `check_token_saf
 1. **Create a Dedicated Hot Wallet**:
    - Create a brand new wallet in MetaMask, Rabby, or via `cast wallet new`.
    - ⚠️ **SECURITY WARNING**: Never use your primary personal wallet, cold storage, or vault.
-2. **Fund the Wallet on Base (EIP-155:8453)**:
-   - **USDC**: Transfer $2 to $10 of USDC on Base (the bridge pays per call: $0.03 to $0.10).
-   - **Gas (ETH on Base)**: Transfer ~$0.50 worth of ETH on Base for minimal gas allowances if needed.
+2. **Fund the Wallet on Base Sepolia testnet (EIP-155:84532)**:
+   - **USDC**: Get Base Sepolia testnet USDC from a faucet (the bridge pays per call: $0.03 to $0.10 in testnet USDC).
+   - **Gas (ETH on Base Sepolia)**: Get a small amount of Base Sepolia testnet ETH for gas if your client needs it. No mainnet funds are required for the public demo.
 3. **Configure Environment Variables in Your MCP Client**:
    - Set `EVM_PRIVATE_KEY` to the 64-character private key of the hot wallet.
+   - Set `VERIFY402_NETWORKS` to `eip155:84532` (Base Sepolia testnet).
    - Set safety caps `MAX_PAYMENT_USD` (e.g., `"0.25"`) and `MAX_DAILY_USD` (e.g., `"1.00"`).
 
 **Paid Configuration Block (Claude Desktop, Cursor, Cline, Windsurf)**:
@@ -104,7 +122,7 @@ To enable the 5 deep on-chain truth checks (`verify_arbitrage`, `check_token_saf
         "EVM_PRIVATE_KEY": "0xYOUR_HOT_WALLET_PRIVATE_KEY",
         "MAX_PAYMENT_USD": "0.25",
         "MAX_DAILY_USD": "1.00",
-        "VERIFY402_NETWORKS": "eip155:8453",
+        "VERIFY402_NETWORKS": "eip155:84532",
         "VERIFY402_PAY_TO": "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb"
       }
     }
@@ -125,6 +143,7 @@ In `opencode.jsonc` (or `~/.config/opencode/opencode.jsonc`):
         "environment": {
           "VERIFY402_URL": "https://verify402.onrender.com",
           "EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}",
+          "VERIFY402_NETWORKS": "eip155:84532",
           "MAX_PAYMENT_USD": "0.25",
           "MAX_DAILY_USD": "1.00"
         }
@@ -163,9 +182,20 @@ Once configured, your agent automatically sees the tools in its context. You can
   server and a known paid route, on an allowlisted EVM network, to the
   verify402 payee. It accepts only recognized default assets (USDC), caps the
   amount at `MAX_PAYMENT_USD`, and refuses redirects.
+- The whole 402 challenge is checked, not just the option the client picks:
+  every offered requirement must use an allowlisted network, the configured
+  payee, the canonical USDC contract **and** the canonical EIP-712 domain for
+  that network, an `extra.assetTransferMethod` of `eip3009`, a
+  `maxTimeoutSeconds` that is a positive integer no greater than `300`, and an
+  amount inside the cap. A challenge that also offers Base mainnet is refused
+  as a whole rather than filtered down to the testnet option. The client also
+  proves that the requirement it signs is the exact object the server sent.
 - The allowlist can be narrowed or pointed at another deployment with
   `VERIFY402_NETWORKS`, `VERIFY402_PAY_TO`, and `VERIFY402_RESOURCE_PREFIX`.
-  Defaults are Base mainnet and the public verify402 payee.
+  The bridge defaults are Base Sepolia testnet (`eip155:84532`) and the
+  public verify402 payee. `VERIFY402_NETWORKS` is constrained to the supported
+  map (`eip155:84532`, `eip155:8453`); an explicitly empty value fails closed
+  instead of falling back to a default.
 - `MAX_PAYMENT_USD` is enforced inside the x402 client, before a signature
   exists; removing it is a security regression. The caps limit what the bridge
   can authorize; they do **not** protect a compromised private key.
@@ -177,6 +207,23 @@ Once configured, your agent automatically sees the tools in its context. You can
 - Use the [reference executor](https://github.com/a32116150-ctrl/verify402/blob/master/examples/preflight-guard.mjs)
   when you want enforcement rather than advice.
 
+## Explicit mainnet configuration (not the public demo)
+
+Mainnet settlement is a separate deployment choice, not a bridge or demo
+default. Do not point this client at mainnet until the service-side mainnet
+readiness checks, facilitator, always-on host, and wallet funding have been
+verified independently.
+
+```bash
+# Only for a deliberate mainnet deployment, never against the public demo.
+VERIFY402_NETWORKS=eip155:8453
+VERIFY402_PAY_TO=<the payee named by the mainnet 402>
+```
+
+The public demo offers `eip155:84532`; a mainnet-only policy will refuse that
+challenge instead of silently spending mainnet funds. The reverse is also
+enforced: the demo policy refuses a mainnet-only challenge.
+
 ## Development
 
 ```bash

package/index.mjs

@@ -31,13 +31,24 @@ import { config } from "dotenv";
 import { z } from "zod";
 import { installConsoleRedaction, logInfo, logError } from "./log.mjs";
 import { paidPost } from "./paid-call.mjs";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
 
 installConsoleRedaction();
-config();
 
-const VERSION = "1.0.4";
+// Only the process entry point loads the operator's `.env`. Importing this
+// module (tests, tooling) must never read the wallet file.
+const IS_MAIN = isMainModule();
+if (IS_MAIN) config();
+
+const VERSION = "1.0.6";
 const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;
-const SERVER_URL = process.env.VERIFY402_URL || "https://verify402.onrender.com";
+// Normalise once so the axios base URL, the payment policy prefix, and the
+// per-tool expected resource are all the same string (no trailing slash).
+const SERVER_URL = (process.env.VERIFY402_URL || "https://verify402.onrender.com")
+  .trim()
+  .replace(/\/+$/, "");
 // Tell the server which client made the call. This is a label, not an identity:
 // it helps separate MCP use from generic HTTP probes without collecting keys or
 // wallet addresses.
@@ -59,6 +70,37 @@ const MAX_PAYMENT_USD = Number(process.env.MAX_PAYMENT_USD || 0.25);
 // registered only when a wallet is configured.
 const PAID_ENABLED = Boolean(EVM_PRIVATE_KEY);
 
+// Each paid MCP tool is bound to exactly one paid API route. This map is local,
+// trusted configuration: a 402 challenge can never choose which resource a tool
+// is allowed to pay for. The pre-sign guard compares the challenge's resource
+// against the route of the tool that is currently running.
+export const PAID_TOOL_ROUTES = Object.freeze({
+  verify_arbitrage: "/verify",
+  check_token_safety: "/safety",
+  get_best_route: "/route",
+  verify_quote_fairness: "/quotecheck",
+  get_trade_depth: "/depth",
+});
+
+// Carries the current tool's expected resource from the tool handler to the
+// pre-sign hook. AsyncLocalStorage keeps concurrent tool calls isolated and is
+// the only channel the guard trusts for the expected resource.
+const paymentContext = new AsyncLocalStorage();
+
+function paidCallContext(tool) {
+  const route = PAID_TOOL_ROUTES[tool];
+  if (!route) throw new Error(`unknown paid tool: ${String(tool)}`);
+  return { tool, route, expectedResource: `${SERVER_URL}${route}` };
+}
+
+/**
+ * Run `run` as the given paid tool. Exported so tests can drive the real
+ * binding without starting the MCP transport.
+ */
+export function runWithPaidTool(tool, run) {
+  return paymentContext.run(paidCallContext(tool), run);
+}
+
 if (process.argv.includes("--help") || process.argv.includes("-h")) {
   console.log(`verify402-mcp — MCP server for verify402
 
@@ -73,7 +115,7 @@ Environment:
   MAX_PAYMENT_USD   cap on one x402 payment (default 0.25)
   MAX_DAILY_USD     optional cap for the UTC day, persisted in a small ledger
   SPEND_LEDGER_PATH optional ledger path (default .spend-ledger.json)
-  VERIFY402_NETWORKS  comma-separated EVM networks for paid calls (default eip155:8453)
+  VERIFY402_NETWORKS  comma-separated EVM networks for paid calls (default eip155:84532, Base Sepolia testnet; eip155:8453 only by explicit opt-in)
   VERIFY402_PAY_TO    EVM payee the 402 must name (default the verify402 payee)
   VERIFY402_RESOURCE_PREFIX  resource origin/prefix the 402 must match (default VERIFY402_URL)
 
@@ -89,14 +131,12 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
 }
 
 // ---------------------------------------------------------------- payment ---
-async function createPaidClient() {
+export function createBridgeClientFromEnv() {
   if (!Number.isFinite(MAX_PAYMENT_USD) || MAX_PAYMENT_USD <= 0) {
     throw new Error("MAX_PAYMENT_USD must be a positive number");
   }
-  const policy = createPaymentPolicy({
-    networks: process.env.VERIFY402_NETWORKS || DEFAULT_NETWORKS,
-    payTo: process.env.VERIFY402_PAY_TO || DEFAULT_PAY_TO,
-    resourcePrefix: process.env.VERIFY402_RESOURCE_PREFIX || SERVER_URL,
+  const policy = createPaymentPolicyFromEnv({
+    resourcePrefix: SERVER_URL,
     paidRoutes: Object.keys(DEFAULT_PRICES),
   });
   const account = privateKeyToAccount(EVM_PRIVATE_KEY);
@@ -108,12 +148,29 @@ async function createPaidClient() {
   for (const network of policy.allowedNetworks) {
     client.register(network, new ExactEvmScheme(account));
   }
-  client.onBeforePaymentCreation((context) => policy.checkBeforeSign(context));
+  // Full-challenge guard (version, every EVM offer, canonical asset/domain,
+  // payee, amount cap, timeout, EIP-3009) plus the resource/route layer. It
+  // runs after the SDK has selected a requirement and before the signer.
+  // The expected resource is resolved per invocation from the tool handler
+  // context, never from the 402 challenge.
+  client.onBeforePaymentCreation(
+    createPaymentGuard(policy, {
+      maxAmountUsd: MAX_PAYMENT_USD,
+      expectedResource: () => paymentContext.getStore()?.expectedResource,
+    }),
+  );
   logInfo(
     `paid policy: networks=${policy.allowedNetworks.join(",")} ` +
       `payee=${policy.allowedPayTo} resources=${policy.resourcePrefix} ` +
       `{${policy.paidRoutes.join(",")}}`,
   );
+  return client;
+}
+
+export async function createBridgePaidClient(client = createBridgeClientFromEnv()) {
+  if (!Number.isFinite(MAX_PAYMENT_USD) || MAX_PAYMENT_USD <= 0) {
+    throw new Error("MAX_PAYMENT_USD must be a positive number");
+  }
   const axiosInstance = axios.create({ baseURL: SERVER_URL, timeout: 120_000, maxRedirects: 0, headers: CLIENT_HEADERS });
   return wrapAxiosWithPayment(axiosInstance, client);
 }
@@ -123,22 +180,38 @@ async function createPaidClient() {
 // (optional) caps the whole UTC day across restarts, persisted in a tiny
 // ledger file. Attempted charges are counted conservatively (before payment).
 import { createDailyBudget, DEFAULT_PRICES } from "./budget.mjs";
-import { createPaymentPolicy, DEFAULT_NETWORKS, DEFAULT_PAY_TO } from "./payment-policy.mjs";
+import { createPaymentGuard, createPaymentPolicyFromEnv } from "./payment-policy.mjs";
 const dailyBudget = createDailyBudget({
   maxDailyUsd: process.env.MAX_DAILY_USD,
 });
 
-async function guardedPaidCall(route, run) {
-  if (dailyBudget.enabled) dailyBudget.assert(route);
-  const res = await run();
+async function guardedPaidCall(tool, run) {
+  const context = paidCallContext(tool);
+  if (dailyBudget.enabled) dailyBudget.assert(context.route);
+  const res = await paymentContext.run(context, run);
   if (res?.data?.recovery?.replayed) {
     // Visible to the operator without exposing the bearer key. The same flag
     // is already in the JSON returned to the MCP client.
-    logInfo(`${route}: recovery.replayed=true (settled verdict returned without a second charge)`);
+    logInfo(`${context.route}: recovery.replayed=true (settled verdict returned without a second charge)`);
   }
   return res;
 }
 
+/**
+ * Run one paid MCP tool. The route is resolved from local tool configuration
+ * (PAID_TOOL_ROUTES), recorded in the async context, and used for both the HTTP
+ * request and the pre-sign expected-resource check, so the 402 challenge can
+ * never redirect a tool to a different paid resource.
+ */
+export async function runPaidTool({ tool, client, body }) {
+  if (!Object.hasOwn(PAID_TOOL_ROUTES, tool)) {
+    throw new Error(`unknown paid tool: ${String(tool)}`);
+  }
+  if (!client) throw new Error(`paid client is not configured for tool ${tool}`);
+  const route = PAID_TOOL_ROUTES[tool];
+  return guardedPaidCall(tool, () => paidPost(client, route, body));
+}
+
 // ------------------------------------------------------------------ tools ---
 const DESCRIPTIONS = {
   preflight_gate:
@@ -177,7 +250,7 @@ const DESCRIPTIONS = {
 };
 
 async function main() {
-  const paidApi = PAID_ENABLED ? await createPaidClient() : null;
+  const paidApi = PAID_ENABLED ? await createBridgePaidClient() : null;
 
   const server = new McpServer({ name: "verify402", version: VERSION });
 
@@ -190,7 +263,7 @@ async function main() {
       from: z.string().optional().describe("The wallet that will sign. Strongly recommended: enables simulation and balance checks."),
       payment: z.object({
         scheme: z.string().optional().describe('x402 scheme, normally "exact"'),
-        network: z.string().describe('CAIP-2 network, e.g. "eip155:8453" or "solana:..."'),
+        network: z.string().describe('CAIP-2 network, e.g. "eip155:84532" for the public demo or "solana:..."'),
         asset: z.string().describe("Token address or mint, e.g. canonical USDC on that network"),
         amount: z.string().describe("RAW amount in the asset's smallest unit, as a string"),
         payTo: z.string().describe("Recipient address from the 402 challenge"),
@@ -267,12 +340,16 @@ async function main() {
       size: z.number().optional().describe("Trade size in whole base units, e.g. 100000 (default 100000)"),
     },
     async (args) => {
-      const res = await guardedPaidCall("/verify", () => paidPost(paidApi, "/verify", {
-        chainId: args.chainId,
-        target: String(args.target ?? "WETH").toUpperCase(),
-        base: String(args.base ?? "USDC").toUpperCase(),
-        size: args.size ?? 100000,
-      }));
+      const res = await runPaidTool({
+        tool: "verify_arbitrage",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          target: String(args.target ?? "WETH").toUpperCase(),
+          base: String(args.base ?? "USDC").toUpperCase(),
+          size: args.size ?? 100000,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -287,12 +364,16 @@ async function main() {
       offeredPriceUsd: z.number().optional().describe("Optional price per token someone offered you"),
     },
     async (args) => {
-      const res = await guardedPaidCall("/safety", () => paidPost(paidApi, "/safety", {
-        chainId: args.chainId,
-        tokenAddress: String(args.tokenAddress ?? "").trim(),
-        intendedUsd: args.intendedUsd ?? 500,
-        offeredPriceUsd: args.offeredPriceUsd ?? null,
-      }));
+      const res = await runPaidTool({
+        tool: "check_token_safety",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          tokenAddress: String(args.tokenAddress ?? "").trim(),
+          intendedUsd: args.intendedUsd ?? 500,
+          offeredPriceUsd: args.offeredPriceUsd ?? null,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -307,12 +388,16 @@ async function main() {
       chainId: z.number().int().describe("REQUIRED. 1 Ethereum, 42161 Arbitrum, 8453 Base. There is no default; omitting it returns 400 missing_chain."),
     },
     async (args) => {
-      const res = await guardedPaidCall("/route", () => paidPost(paidApi, "/route", {
-        chainId: args.chainId,
-        tokenIn: args.tokenIn,
-        tokenOut: args.tokenOut,
-        amountIn: args.amountIn,
-      }));
+      const res = await runPaidTool({
+        tool: "get_best_route",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          tokenIn: args.tokenIn,
+          tokenOut: args.tokenOut,
+          amountIn: args.amountIn,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -329,14 +414,18 @@ async function main() {
       chainId: z.number().int().describe("REQUIRED. 1 Ethereum, 42161 Arbitrum, 8453 Base. There is no default; omitting it returns 400 missing_chain."),
     },
     async (args) => {
-      const res = await guardedPaidCall("/quotecheck", () => paidPost(paidApi, "/quotecheck", {
-        chainId: args.chainId,
-        tokenIn: args.tokenIn,
-        tokenOut: args.tokenOut,
-        amountIn: args.amountIn,
-        quotedOut: args.quotedOut,
-        venueClaimed: args.venueClaimed ?? null,
-      }));
+      const res = await runPaidTool({
+        tool: "verify_quote_fairness",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          tokenIn: args.tokenIn,
+          tokenOut: args.tokenOut,
+          amountIn: args.amountIn,
+          quotedOut: args.quotedOut,
+          venueClaimed: args.venueClaimed ?? null,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -352,13 +441,17 @@ async function main() {
       maxRoundTripPct: z.number().optional().describe("Your round-trip cost tolerance, default 1%"),
     },
     async (args) => {
-      const res = await guardedPaidCall("/depth", () => paidPost(paidApi, "/depth", {
-        chainId: args.chainId,
-        tokenAddress: args.tokenAddress,
-        baseSymbol: args.baseSymbol ?? "USDC",
-        sizesUsd: args.sizesUsd ?? null,
-        maxRoundTripPct: args.maxRoundTripPct ?? 1.0,
-      }));
+      const res = await runPaidTool({
+        tool: "get_trade_depth",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          tokenAddress: args.tokenAddress,
+          baseSymbol: args.baseSymbol ?? "USDC",
+          sizesUsd: args.sizesUsd ?? null,
+          maxRoundTripPct: args.maxRoundTripPct ?? 1.0,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -373,7 +466,23 @@ async function main() {
   );
 }
 
-main().catch((e) => {
-  logError("bridge failed", e);
-  process.exit(1);
-});
+// True only when this file is the process entry point. The published package
+// is installed through a `bin` symlink, so both sides are compared by real
+// path: Node resolves import.meta.url through the symlink but keeps the
+// symlink path in process.argv[1].
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (IS_MAIN) {
+  main().catch((e) => {
+    logError("bridge failed", e);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verify402-mcp",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "mcpName": "io.github.a32116150-ctrl/verify402-mcp",
   "description": "MCP server for verify402: a free, fail-closed preflight gate before signing, plus five paid on-chain checks paid per call via x402.",
   "type": "module",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "start": "node index.mjs",
-    "test": "node --test test/payment-policy.test.mjs"
+    "test": "node --test test/payment-policy.test.mjs test/first-payment.test.mjs test/paid-call.test.mjs test/bridge-client.test.mjs"
   },
   "engines": {
     "node": ">=20"

package/payment-policy.mjs

@@ -3,20 +3,284 @@
 // The bridge is a payer, not a blank cheque for any remote 402. Before a
 // signature exists, the policy requires:
 //
-//   - the network to be explicitly allowlisted (default Base mainnet);
+//   - the network to be explicitly allowlisted (the public demo default is
+//     Base Sepolia testnet, eip155:84532);
 //   - payTo to be the verify402 payee (default the EVM payTo);
 //   - the 402 resource to be on the configured server and a known paid route.
 //
-// The amount cap and the default-asset (USDC) allowlist are enforced by
-// x402Client's spendControls, which run before this policy. Redirects are
-// refused by the axios client in index.mjs.
+// The amount cap and the canonical-USDC allowlist are enforced both by
+// x402Client's spendControls and by validatePaymentChallenge(), which runs
+// before the signing hook in first-payment.mjs and index.mjs. Redirects are
+// refused by the axios clients in index.mjs and first-payment.mjs.
+//
+// Mainnet is available only through an explicit VERIFY402_NETWORKS value. The
+// demo default must never silently select Base mainnet.
 //
 // Free-only mode never imports or constructs this policy.
 
-export const DEFAULT_NETWORKS = ["eip155:8453"];
+export const DEMO_NETWORK = "eip155:84532";
+export const MAINNET_NETWORK = "eip155:8453";
+export const DEFAULT_NETWORKS = [DEMO_NETWORK];
 export const DEFAULT_PAY_TO = "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb";
 export const DEFAULT_PAID_ROUTES = ["/verify", "/safety", "/route", "/quotecheck", "/depth"];
 
+// Hard upper bound for a single EIP-3009 authorization. The SDK signs
+// `validBefore = now + maxTimeoutSeconds`; an unbounded value hands the payee a
+// long-lived transferable authorization. 300 seconds is the documented cap and
+// matches the live verify402 challenge.
+export const MAX_TIMEOUT_SECONDS = 300;
+
+// The canonical USDC contract for each network this bridge knows how to pay.
+// A 402 that names a different asset on one of these networks is a different
+// payment, not a cheaper one, so the guard refuses it.
+export const DEMO_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+export const MAINNET_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export const NETWORK_USDC = {
+  [DEMO_NETWORK]: DEMO_USDC,
+  [MAINNET_NETWORK]: MAINNET_USDC,
+};
+
+// EIP-712 domain parameters for the canonical USDC contract on each supported
+// network. These are signing-relevant: a server that supplies a different
+// `extra.name`/`extra.version` asks the wallet to sign a different token
+// domain. Values mirror the installed @x402/evm default-asset table.
+export const NETWORK_USDC_DOMAIN = {
+  [DEMO_NETWORK]: { name: "USDC", version: "2" },
+  [MAINNET_NETWORK]: { name: "USD Coin", version: "2" },
+};
+
+// The only networks the bridge will ever register a signer for. VERIFY402_NETWORKS
+// is constrained to this map; an arbitrary eip155:<chainId> is refused rather
+// than inferred from an asset the SDK happens to recognise.
+export const SUPPORTED_PAYMENT_NETWORKS = new Set(Object.keys(NETWORK_USDC));
+
+const EVM_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const CAIP2_RE = /^[a-z0-9][a-z0-9-]*:[A-Za-z0-9._:-]+$/;
+const SUPPORTED_NETWORK_NAMESPACES = new Set(["eip155", "solana"]);
+
+// `extra` fields that do not change how a payload is signed. Everything else on
+// an EVM requirement is a signing-mode extension and is refused until it is
+// explicitly validated here.
+const EVM_EXTRA_ALLOWED_KEYS = new Set(["name", "version", "assetTransferMethod", "paymentFlow"]);
+
+/**
+ * Convert a USD amount to six-decimal atomic units. Returns null when the
+ * value is not a positive finite number, so callers fail closed instead of
+ * rounding a bad cap into zero or Infinity.
+ */
+export function usdToAtomic(value) {
+  const parsed = typeof value === "string" ? Number(value.replace(/^\$/, "").trim()) : Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return BigInt(Math.round(parsed * 1e6));
+}
+
+function normalizeUrl(value) {
+  try {
+    const url = new URL(String(value));
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+// Exact resource identity: origin + path are compared with no trailing-slash
+// normalisation, so `/route/` is not `/route`.
+function resourceKey(url) {
+  return `${url.origin}${url.pathname}`;
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validate `maxTimeoutSeconds` as a positive integer no greater than the
+ * documented cap. Strings, floats, NaN, infinities, zero and negatives are all
+ * refused before any arithmetic happens.
+ */
+function validateTimeoutSeconds(value) {
+  if (typeof value !== "number") return "maxTimeoutSeconds must be a number";
+  if (!Number.isInteger(value)) return "maxTimeoutSeconds must be an integer";
+  if (value <= 0) return "maxTimeoutSeconds must be positive";
+  if (value > MAX_TIMEOUT_SECONDS) {
+    return `maxTimeoutSeconds ${value} exceeds the ${MAX_TIMEOUT_SECONDS}s maximum`;
+  }
+  return null;
+}
+
+/**
+ * Validate the EIP-712 domain and transfer mode of an EVM requirement. The
+ * installed SDK selects EIP-3009 unless `extra.assetTransferMethod === "permit2"`,
+ * so permit2 (and any unvalidated extension key) is refused here.
+ */
+function validateEvmExtra(requirement, index, expectedDomainByNetwork) {
+  const prefix = `402 accepts[${index}]`;
+  const extra = requirement.extra;
+  if (!isPlainObject(extra)) return `${prefix} has no valid extra`;
+  if (extra.assetTransferMethod !== undefined && extra.assetTransferMethod !== "eip3009") {
+    return `${prefix} transfer method ${String(extra.assetTransferMethod)} is not supported`;
+  }
+  if (extra.paymentFlow !== undefined && extra.paymentFlow !== "authorization") {
+    return `${prefix} paymentFlow ${String(extra.paymentFlow)} is not supported`;
+  }
+  for (const key of Object.keys(extra)) {
+    if (!EVM_EXTRA_ALLOWED_KEYS.has(key)) {
+      return `${prefix} extra.${key} is not a supported signing extension`;
+    }
+  }
+  if (typeof extra.name !== "string" || !extra.name.trim()) {
+    return `${prefix} EIP-712 domain name is missing`;
+  }
+  if (typeof extra.version !== "string" || !extra.version.trim()) {
+    return `${prefix} EIP-712 domain version is missing`;
+  }
+  const expectedDomain = expectedDomainByNetwork?.[requirement.network];
+  if (expectedDomain) {
+    if (extra.name !== expectedDomain.name || extra.version !== expectedDomain.version) {
+      return `${prefix} EIP-712 domain ${extra.name}/${extra.version} is not the canonical USDC domain for ${requirement.network}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate a complete x402 v2 challenge before a payer is allowed to sign.
+ *
+ * This is deliberately stricter than "pick an acceptable requirement": every
+ * offered requirement is checked, and every EVM option must be on an
+ * allowlisted network, name the configured payee, use the canonical USDC asset
+ * and EIP-712 domain for that network, pin EIP-3009, and stay under the
+ * per-payment cap. A mixed challenge that also offers Base mainnet is refused
+ * as a whole, not silently filtered down to the testnet option.
+ *
+ * Returns `{ ok: true, requirement }` for the selected EVM requirement, or
+ * `{ ok: false, reason }`. Missing or malformed fields are failures.
+ */
+export function validatePaymentChallenge(challenge, {
+  allowedNetworks = DEFAULT_NETWORKS,
+  allowedPayTo = DEFAULT_PAY_TO,
+  expectedResource,
+  maxAmountUsd,
+  expectedAssetByNetwork = NETWORK_USDC,
+  expectedDomainByNetwork = NETWORK_USDC_DOMAIN,
+} = {}) {
+  const fail = (reason) => ({ ok: false, reason });
+
+  if (!isPlainObject(challenge)) {
+    return fail("402 challenge is not an object");
+  }
+  if (challenge.x402Version !== 2) {
+    return fail("402 challenge is not x402 v2");
+  }
+  if (!Array.isArray(challenge.accepts) || challenge.accepts.length === 0) {
+    return fail("402 challenge has no accepts[]");
+  }
+
+  const resource = normalizeUrl(challenge.resource?.url ?? challenge.resource);
+  if (!resource) {
+    return fail("402 challenge has no valid resource URL");
+  }
+  if (resource.search || resource.hash) {
+    return fail("402 resource must not contain a query or fragment");
+  }
+  if (expectedResource !== undefined) {
+    const expected = normalizeUrl(expectedResource);
+    if (!expected) return fail("expected resource is not a valid http(s) URL");
+    if (resourceKey(resource) !== resourceKey(expected)) {
+      return fail(`402 resource ${resource.href} is not the expected ${expected.href}`);
+    }
+  }
+
+  const networks = new Set(allowedNetworks);
+  const expectedPayTo = String(allowedPayTo ?? "").trim().toLowerCase();
+  if (!EVM_ADDRESS_RE.test(expectedPayTo)) {
+    return fail("no valid expected payee is configured");
+  }
+
+  const maxAtomic = maxAmountUsd === undefined ? null : usdToAtomic(maxAmountUsd);
+  if (maxAmountUsd !== undefined && maxAtomic === null) {
+    return fail("configured maximum payment amount is not a positive USD value");
+  }
+
+  let selected = null;
+  for (const [index, requirement] of challenge.accepts.entries()) {
+    const prefix = `402 accepts[${index}]`;
+
+    if (!isPlainObject(requirement)) {
+      return fail(`${prefix} is not an object`);
+    }
+
+    const network = requirement.network;
+    if (typeof network !== "string" || !CAIP2_RE.test(network)) {
+      return fail(`${prefix} has no valid network`);
+    }
+    const namespace = network.split(":")[0];
+    if (!SUPPORTED_NETWORK_NAMESPACES.has(namespace)) {
+      return fail(`${prefix} network ${network} is unsupported`);
+    }
+
+    const scheme = requirement.scheme;
+    if (scheme !== "exact") {
+      return fail(`${prefix} scheme ${String(scheme)} is not exact`);
+    }
+
+    const timeoutError = validateTimeoutSeconds(requirement.maxTimeoutSeconds);
+    if (timeoutError) {
+      return fail(`${prefix} ${timeoutError}`);
+    }
+
+    const amount = requirement.amount;
+    if (typeof amount !== "string" || !/^\d+$/.test(amount) || BigInt(amount) <= 0n) {
+      return fail(`${prefix} has no valid amount`);
+    }
+
+    const asset = requirement.asset;
+    if (typeof asset !== "string" || !asset.trim()) {
+      return fail(`${prefix} has no asset`);
+    }
+
+    if (namespace !== "eip155") continue;
+
+    if (!networks.has(network)) {
+      return fail(`${prefix} network ${network} is not an allowed EVM network`);
+    }
+    if (!EVM_ADDRESS_RE.test(asset)) {
+      return fail(`${prefix} asset is not an EVM token address`);
+    }
+
+    const expectedAsset = expectedAssetByNetwork?.[network];
+    if (!expectedAsset) {
+      return fail(`no canonical USDC asset is configured for ${network}`);
+    }
+    if (asset.toLowerCase() !== expectedAsset.toLowerCase()) {
+      return fail(`${prefix} asset ${asset} is not the canonical USDC for ${network}`);
+    }
+
+    const payTo = String(requirement.payTo ?? "").trim();
+    if (!EVM_ADDRESS_RE.test(payTo)) {
+      return fail(`${prefix} has no valid payee`);
+    }
+    if (payTo.toLowerCase() !== expectedPayTo) {
+      return fail(`${prefix} payee ${payTo} is not the configured payee`);
+    }
+
+    const extraError = validateEvmExtra(requirement, index, expectedDomainByNetwork);
+    if (extraError) return fail(extraError);
+
+    if (maxAtomic !== null && BigInt(amount) > maxAtomic) {
+      return fail(`${prefix} amount ${amount} exceeds the ${maxAmountUsd} USD cap`);
+    }
+
+    if (!selected) selected = requirement;
+  }
+
+  if (!selected) {
+    return fail("402 challenge offers no allowed EVM payment requirement");
+  }
+  return { ok: true, requirement: selected };
+}
+
 function parseNetworks(raw) {
   const values = Array.isArray(raw) ? raw : String(raw ?? "").split(",");
   const networks = values.map((value) => String(value).trim()).filter(Boolean);
@@ -27,6 +291,12 @@ function parseNetworks(raw) {
     if (!/^eip155:\d+$/.test(network)) {
       throw new Error(`VERIFY402_NETWORKS: ${network} is not an eip155:<chainId> network`);
     }
+    if (!SUPPORTED_PAYMENT_NETWORKS.has(network)) {
+      throw new Error(
+        `VERIFY402_NETWORKS: ${network} is not a supported payment network ` +
+          `(supported: ${[...SUPPORTED_PAYMENT_NETWORKS].join(", ")})`,
+      );
+    }
   }
   return [...new Set(networks)];
 }
@@ -102,6 +372,10 @@ export function createPaymentPolicy({
     /**
      * x402Client onBeforePaymentCreation hook: runs after selection and before
      * the scheme creates a signature. Returning `{ abort: true }` fails closed.
+     *
+     * This is the resource/route layer of the policy. The full challenge and
+     * the selected requirement are validated by createPaymentGuard(), which
+     * wraps this method for both payers.
      */
     checkBeforeSign(context) {
       const rawResource = context?.paymentRequired?.resource;
@@ -117,6 +391,10 @@ export function createPaymentPolicy({
         return { abort: true, reason: `402 resource is not a URL: ${String(resourceUrl)}` };
       }
 
+      if (url.search || url.hash) {
+        return { abort: true, reason: "402 resource must not contain a query or fragment" };
+      }
+
       if (url.origin !== prefix.origin) {
         return {
           abort: true,
@@ -143,7 +421,7 @@ export function createPaymentPolicy({
       }
 
       const requirement = context?.selectedRequirements;
-      if (!requirement) {
+      if (!requirement || typeof requirement !== "object") {
         return { abort: true, reason: "402 selected no payment requirement" };
       }
       if (
@@ -160,3 +438,116 @@ export function createPaymentPolicy({
     },
   };
 }
+
+/**
+ * Build the pre-signature guard shared by every payer. It validates the whole
+ * 402 challenge, proves the SDK's selected requirement is the exact object that
+ * was validated, re-validates that object, and then applies the resource/route
+ * layer in policy.checkBeforeSign().
+ *
+ * `expectedResource` may be a fixed string (the standalone payer and the smoke
+ * preflight, which know their one resource) or a resolver returning the
+ * resource bound to the current invocation (the MCP bridge, where each paid
+ * tool names its own route). A resolver that returns nothing aborts: the guard
+ * never signs a challenge that is not tied to locally known tool configuration.
+ *
+ * Returns a hook `(context) => { abort: true, reason } | undefined` suitable
+ * for x402Client.onBeforePaymentCreation().
+ */
+export function createPaymentGuard(policy, {
+  expectedResource,
+  maxAmountUsd,
+  expectedAssetByNetwork = NETWORK_USDC,
+  expectedDomainByNetwork = NETWORK_USDC_DOMAIN,
+} = {}) {
+  if (!policy || !Array.isArray(policy.allowedNetworks)) {
+    throw new Error("createPaymentGuard requires a payment policy");
+  }
+  if (
+    expectedResource !== undefined &&
+    typeof expectedResource !== "string" &&
+    typeof expectedResource !== "function"
+  ) {
+    throw new Error("expectedResource must be a string or a resolver function");
+  }
+
+  const isResolver = typeof expectedResource === "function";
+  const resolveExpectedResource = (context) => {
+    const value = isResolver ? expectedResource(context) : expectedResource;
+    if (typeof value === "string" && value !== "") return value;
+    return null;
+  };
+
+  const baseOptions = {
+    allowedNetworks: policy.allowedNetworks,
+    allowedPayTo: policy.allowedPayTo,
+    maxAmountUsd,
+    expectedAssetByNetwork,
+    expectedDomainByNetwork,
+  };
+
+  return function guard(context) {
+    const challenge = context?.paymentRequired;
+    const resolvedExpectedResource = resolveExpectedResource(context);
+    if (isResolver && resolvedExpectedResource === null) {
+      return { abort: true, reason: "no expected payment resource is bound to this call" };
+    }
+    if (!isResolver && expectedResource !== undefined && resolvedExpectedResource === null) {
+      return { abort: true, reason: "no expected payment resource for this payment" };
+    }
+    const options = resolvedExpectedResource === null
+      ? baseOptions
+      : { ...baseOptions, expectedResource: resolvedExpectedResource };
+
+    const validation = validatePaymentChallenge(challenge, options);
+    if (!validation.ok) return { abort: true, reason: validation.reason };
+
+    const selected = context?.selectedRequirements;
+    if (!selected || typeof selected !== "object") {
+      return { abort: true, reason: "402 selected no payment requirement" };
+    }
+
+    const selectedValidation = validatePaymentChallenge(
+      { ...challenge, accepts: [selected] },
+      options,
+    );
+    if (!selectedValidation.ok) return { abort: true, reason: selectedValidation.reason };
+    if (selectedValidation.requirement !== selected) {
+      return { abort: true, reason: "selected payment requirement changed after validation" };
+    }
+
+    // Reference identity: the SDK selector returns an element of
+    // paymentRequired.accepts, so a clone/substitution is refused here.
+    if (!Array.isArray(challenge.accepts) || !challenge.accepts.includes(selected)) {
+      return { abort: true, reason: "selected payment requirement is not from the 402 challenge" };
+    }
+
+    if (typeof policy.checkBeforeSign === "function") {
+      const resourceCheck = policy.checkBeforeSign(context);
+      if (resourceCheck?.abort) return resourceCheck;
+    }
+
+    return;
+  };
+}
+
+/**
+ * Build the paid-call policy from the bridge's documented environment.
+ *
+ * The default is deliberately Base Sepolia testnet. Base mainnet is selected
+ * only when VERIFY402_NETWORKS explicitly names eip155:8453. An explicitly
+ * empty network list or payee throws, so a typo cannot widen the policy.
+ */
+export function createPaymentPolicyFromEnv({
+  resourcePrefix,
+  paidRoutes = DEFAULT_PAID_ROUTES,
+  env = process.env,
+} = {}) {
+  return createPaymentPolicy({
+    networks: env.VERIFY402_NETWORKS === undefined ? DEFAULT_NETWORKS : env.VERIFY402_NETWORKS,
+    payTo: env.VERIFY402_PAY_TO === undefined ? DEFAULT_PAY_TO : env.VERIFY402_PAY_TO,
+    resourcePrefix:
+      env.VERIFY402_RESOURCE_PREFIX === undefined ? resourcePrefix : env.VERIFY402_RESOURCE_PREFIX,
+    paidRoutes,
+  });
+}