verify402-mcp 1.0.6 → 1.0.8

package/README.md

@@ -10,13 +10,13 @@ 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
+> **Published package note:** `verify402-mcp@1.0.8` 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.
+> previously published `1.0.6` package is immutable; `1.0.5` and `1.0.4` are
+> also immutable, and `1.0.4` used Base mainnet by default. Do not republish or
+> overwrite any of them.
 
 ## Tools
 
@@ -41,6 +41,19 @@ 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.
 
+Two optional caller-supplied checks are forwarded as-is:
+
+- `payment.idempotencyKey` + `policy.obligation.settledKeys` rejects a key the
+  caller already settled; `policy.obligation.spentUsd` + `grantUsd` rejects
+  cumulative spend over the grant. The bridge does **not** persist this state.
+- `policy.sellerPayoutWallets` is a caller-supplied payout allowlist. A
+  mismatch is BLOCK, but a match is not provenance and never adds
+  `payee_payout_binding`.
+- `policy.sellerPayoutManifest` fetches a seller-signed manifest from a
+  caller-pinned HTTPS origin outside the 402. Only a verified manifest whose
+  `payTo` list matches adds `payee_payout_binding`. The response includes
+  `payeeBinding` with the source, origin, signer, expiry, and manifest hash.
+
 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
@@ -199,11 +212,16 @@ Once configured, your agent automatically sees the tools in its context. You can
 - `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.
+- The bridge sends `X-Verify402-Client: verify402-mcp/<version>` and the same
+  version in its User-Agent. This is an anonymous label for `/usage`, not an
+  account: it contains no wallet, key, or user id, and the server treats it as
+  self-declared and spoofable.
 - `preflight_gate` is a check, not a guarantee. Read `notChecked`: it does not
   screen recipient reputation or sanctions, audit contracts, simulate full
-  balance deltas, audit the counterparty, scan tool descriptions or responses
-  for prompt injection, or protect against MEV. It catches the measurable
-  signing mistakes, not every scam.
+  balance deltas, audit the counterparty, independently prove payee ownership,
+  persist an obligation ledger across processes, scan tool descriptions or
+  responses for prompt injection, or protect against MEV. It catches the
+  measurable signing mistakes, not every scam.
 - Use the [reference executor](https://github.com/a32116150-ctrl/verify402/blob/master/examples/preflight-guard.mjs)
   when you want enforcement rather than advice.
 

package/client-id.mjs

@@ -0,0 +1,17 @@
+// One shared, anonymous client label for every request the bridge makes.
+//
+// This is not an identity: it contains no wallet, key, account, or user id, and
+// the server treats it as a self-declared hint. Its only job is to let /usage
+// separate bridge traffic from generic HTTP probes. The version comes from the
+// package manifest so a release bump cannot leave the label stale.
+
+import { readFileSync } from "node:fs";
+
+const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+
+export const CLIENT_ID = "verify402-mcp";
+export const VERSION = pkg.version;
+export const CLIENT_HEADERS = Object.freeze({
+  "User-Agent": `${CLIENT_ID}/${VERSION}`,
+  "X-Verify402-Client": `${CLIENT_ID}/${VERSION}`,
+});

package/index.mjs

@@ -31,6 +31,7 @@ import { config } from "dotenv";
 import { z } from "zod";
 import { installConsoleRedaction, logInfo, logError } from "./log.mjs";
 import { paidPost } from "./paid-call.mjs";
+import { CLIENT_HEADERS, VERSION } from "./client-id.mjs";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -42,20 +43,14 @@ installConsoleRedaction();
 const IS_MAIN = isMainModule();
 if (IS_MAIN) config();
 
-const VERSION = "1.0.6";
 const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;
 // 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.
-const CLIENT_HEADERS = {
-  "User-Agent": `verify402-mcp/${VERSION}`,
-  "X-Verify402-Client": `mcp/${VERSION}`,
-};
+// CLIENT_HEADERS is a label, not an identity: it helps /usage separate MCP
+// calls from generic HTTP probes without collecting keys or wallet addresses.
 // Preflight is free, so it does not go through the paying client. Keeping the
 // two clients separate means a misconfigured 402 on a free route can never
 // turn into a signature.
@@ -222,7 +217,10 @@ const DESCRIPTIONS = {
     "operator before signing. The receipt expires (default 90s): call again rather than reuse it. " +
     "Free. Pass `from` (the wallet that will sign) to enable simulation and balance checks. For " +
     "kind=transaction, chainId is REQUIRED (400 missing_chain without it). For payment intents " +
-    "with no `from` or no proof, the response is PASS with structural_only:true and names what was not checked.",
+    "with no `from` or no proof, the response is PASS with structural_only:true and names what was not checked. " +
+    "Optional caller-supplied checks: policy.sellerPayoutWallets is a payout allowlist, not provenance; " +
+    "policy.sellerPayoutManifest fetches a seller-signed manifest from a caller-pinned HTTPS origin and is the only source of payee_payout_binding; " +
+    "policy.obligation checks a local settled-key ledger and cumulative spend against a grant. The gate does not persist either state.",
   verify_arbitrage:
     "Ask verify402 whether a cross-venue arbitrage opportunity is REAL, right now. " +
     "Quotes come from Uniswap's canonical QuoterV2 and each DEX router at one pinned block. " +
@@ -268,6 +266,7 @@ async function main() {
         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"),
         resource: z.string().optional().describe("The resource URL the payment is for"),
+        idempotencyKey: z.string().max(256).optional().describe("Caller-local payment idempotency key (not the paid-route x-idempotency-key header); enables the policy.obligation replay check"),
         maxTimeoutSeconds: z.number().optional().describe("maxTimeoutSeconds from the 402 challenge"),
         extra: z.object({
           validAfter: z.number().optional(),
@@ -289,6 +288,17 @@ async function main() {
         allowedAssets: z.array(z.string()).optional().describe("Allowlist of payment assets"),
         allowedFacilitators: z.array(z.string()).optional().describe("Allowlist of x402 facilitators"),
         expectedResource: z.string().optional().describe("The exact resource URL the agent intends to pay for"),
+        allowedResourceHosts: z.array(z.string()).optional().describe("Bare hostnames allowed in payment.resource; a foreign host is BLOCK"),
+        sellerPayoutWallets: z.array(z.string()).optional().describe("Caller-supplied seller payout allowlist; a payTo mismatch is BLOCK. This is not provenance and never adds payee_payout_binding"),
+        sellerPayoutManifest: z.object({
+          url: z.string().url().describe("HTTPS URL of a seller-signed manifest outside the 402"),
+          expectedSigner: z.string().optional().describe("Optional EVM address pin for the manifest signer"),
+        }).optional().describe("Seller-signed payout manifest; the only source of payee_payout_binding"),
+        obligation: z.object({
+          settledKeys: z.array(z.string()).optional().describe("Payment idempotency keys already settled"),
+          spentUsd: z.number().nonnegative().optional().describe("Already spent under the grant, in USD"),
+          grantUsd: z.number().nonnegative().optional().describe("Total grant in USD; spentUsd and grantUsd must be supplied together"),
+        }).optional().describe("Caller-supplied local obligation state. The public gate does not persist it"),
         forbidUnlimitedApproval: z.boolean().optional().describe("Turn an unlimited approve into a BLOCK"),
         maxTimeoutSeconds: z.number().optional().describe("Reject challenges with a longer timeout"),
       }).optional().describe("Operator policy. Omit for structural checks only."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verify402-mcp",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "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",
@@ -14,6 +14,7 @@
     "payment-policy.mjs",
     "paid-call.mjs",
     "log.mjs",
+    "client-id.mjs",
     "README.md",
     ".env.example",
     "LICENSE",