agent402-tollbooth 0.9.3 → 0.10.1

package/README.md

@@ -1,11 +1,13 @@
 # agent402-tollbooth
 
+Part of [Agent402](https://agent402.tools), the open-source paid door for AI agents.
+
 **Open-source, self-hostable pay-per-crawl for x402 and MPP. Put it in front of
 any site or API: humans browse free, AI crawlers and agents pay per request** -
 in USDC over the [x402 protocol](https://x402.org), over
 [MPP](https://mpp.dev) (the Machine Payments Protocol `Payment` HTTP auth
 scheme, settled through the same stack), or for free by solving a
-proof-of-work. No Cloudflare, no Stripe, no Merchant-of-Record, no signup.
+proof-of-work. No platform lock-in, no card processor required, no Merchant-of-Record, no signup.
 The first self-hostable pay-per-crawl gate that speaks both wires on one 402 -
 the sell side of [Agentic Finance](https://agent402.tools/agentic-finance),
 where agents pay and sites get paid, per request, with no account in between.
@@ -156,8 +158,16 @@ export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)
 > On the edge, pass a stable `secret` (PoW tokens are HMAC-signed). For
 > single-use replay protection across stateless invocations, supply a `store`
 > (e.g. a Cloudflare KV wrapper - the Worker entry wires this for you).
-> The `x402:` middleware mode, MPP and the native Tempo rail are Node/Express
-> features today; the edge gate offers proof-of-work plus the `verifyX402` callback.
+> The `x402:` middleware mode and the native Tempo rail are Node/Express
+> features; the edge gate offers proof-of-work plus the `verifyX402` callback,
+> and since 0.10.0 **MPP on that same verifier**: with `secret`, `payTo` and
+> `verifyX402` set, every 402 also carries a `WWW-Authenticate: Payment`
+> evm/charge challenge for the quote, and an `Authorization: Payment`
+> credential (HMAC-bound to our challenge, unexpired, minted for that exact
+> resource) is translated to `PAYMENT-SIGNATURE` and handed to `verifyX402` as
+> if an x402 client had sent it. `mpp:false` turns it off; `mppAssetAddress` +
+> `mppAssetName` name a token outside the built-in USDC table (Base, Celo,
+> Polygon, Arbitrum, Optimism, Avalanche, Sei).
 
 ## Accepting USDC: x402 and MPP on the same 402
 
@@ -318,7 +328,7 @@ Read by the bundled proxy / Express entry point (`index.js`):
 | `TOLLBOOTH_PAYTO` | – | Wallet address; advertises a USDC x402 quote (and, with `TOLLBOOTH_FACILITATOR_URL`, settles it) |
 | `TOLLBOOTH_FACILITATOR_URL` | – | x402 facilitator that settles your network. With `TOLLBOOTH_PAYTO` the CLI builds a real `@x402/express` middleware and takes payment over x402 **and** MPP (0.8.0). Needs `@x402/express @x402/core @x402/evm` installed; refuses to start without them |
 | `TOLLBOOTH_FACILITATOR_HEADERS` | – | Optional JSON object of auth headers sent on the facilitator's `/verify`, `/settle`, `/supported` (e.g. `{"X-API-Key":"…"}`) |
-| `TOLLBOOTH_CDP_API_KEY_ID` + `TOLLBOOTH_CDP_API_KEY_SECRET` | – | Settle through Coinbase's facilitator (CDP) instead of a URL: fee-free on Base, and the endpoint is indexed in Coinbase's x402 Bazaar. Needs `npm i @coinbase/x402`. This is how a Coinbase Business account gets paid by agents: `TOLLBOOTH_PAYTO` = the account's USDC (Base) receive address. |
+| `TOLLBOOTH_CDP_API_KEY_ID` + `TOLLBOOTH_CDP_API_KEY_SECRET` | – | Settle through Coinbase's facilitator (CDP) instead of a URL (no fee is taken from the payment itself; Coinbase's facilitator is free for the first 1,000 settlements a month and $0.001 each after). Needs `npm i @coinbase/x402`. This is how a Coinbase Business account gets paid by agents: `TOLLBOOTH_PAYTO` = the account's USDC (Base) receive address. |
 | `TOLLBOOTH_PRICE` | `"$0.001"` | Advertised price per request |
 | `TOLLBOOTH_NETWORK` | `"base"` | x402 network. CLI settlement mode accepts `base`, `base-sepolia`, `polygon`, `arbitrum`, `optimism`, `avalanche`, `celo`, `sei`, `monad`, or a raw `eip155:<id>` |
 | `TOLLBOOTH_MPP` | on when `x402` set | `false` to switch MPP off |
@@ -617,7 +627,11 @@ TOLLBOOTH_PRICE='$0.005' TOLLBOOTH_UPSTREAM=http://localhost:8080 \
 npx agent402-tollbooth
 ```
 
-Every paid request settles as USDC into the Coinbase Business account; humans
+Load the three values from a `.env` or a secret store rather than typing the
+key on the command line. Live-proven 2026-08-27 with real USDC through
+Coinbase's facilitator ([tx](https://basescan.org/tx/0x8175178ac4e2229dfd9385a3c78c491ffe554b08fdf52cf92f99425c983ec5d1));
+note the facilitator refuses a payer paying itself (`self_send_not_allowed`),
+so test from a second wallet. Every paid request settles as USDC into the Coinbase Business account; humans
 browse your site normally. Full walkthrough with an Express example:
 https://agent402.tools/guides/coinbase-business-get-paid-by-agents
 

package/edge-mpp.js

@@ -0,0 +1,139 @@
+// MPP (Machine Payments Protocol) for the EDGE gate - Web Crypto HMAC, no
+// node:* imports, so it runs where edge.js runs (Cloudflare Workers, Next.js
+// edge middleware, Deno, Bun, Node 20+).
+//
+// Same design as the Node build's mpp.js: settlement authority stays with the
+// operator's x402 verifier, and MPP is pure header translation around it.
+//
+//   OUTBOUND  the gate's USDC quote (price / network / asset / payTo) becomes
+//             ONE HMAC-bound `WWW-Authenticate: Payment` evm/charge challenge
+//             on the 402, next to the JSON `accepts` block the x402 path reads.
+//             The x402-v2-shaped accept it stands for, plus the resource it
+//             was minted for, ride in the challenge's opaque slot so inbound
+//             is stateless and byte-exact.
+//   INBOUND   an `Authorization: Payment` credential whose challenge id
+//             HMAC-verifies, is unexpired and was minted for THIS resource is
+//             re-encoded as an x402 v2 PAYMENT-SIGNATURE and handed to the
+//             SAME verifyX402 callback the x402 path uses - so an operator who
+//             already settles x402 on the edge takes MPP with no new code.
+//
+// Receipts: the edge gate answers null (allow) and never sees the operator's
+// response, so it cannot mirror a Payment-Receipt; `receiptFor(tx)` is
+// exported for an operator whose verifier learns the settlement hash.
+import {
+  META_ACCEPTS_KEY, STABLECOIN_DECIMALS, encodeRequest, challengeIdInput, serializeChallenge, bytesToB64url,
+  decodeCredentialHeader, challengeShapeOk, metaFromChallenge, authorizationFromPayload, paymentSignatureFor, receiptFor,
+} from "./mpp-codec.js";
+export { receiptFor, isMppCredential } from "./mpp-codec.js";
+
+const META_RESOURCE_KEY = "resource";
+const te = new TextEncoder();
+
+/** USDC on the chains the CLI names (same table as CLI_NETWORKS, plus the
+ *  token address and its EIP-712 domain name, which a facilitator needs to
+ *  verify the EIP-3009 signature). Robinhood Chain (USDG) and non-EVM rails
+ *  are not MPP evm/charge targets here. */
+export const EDGE_USDC = {
+  8453: { asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", name: "USD Coin" },
+  42220: { asset: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C", name: "USDC" },
+  137: { asset: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", name: "USD Coin" },
+  42161: { asset: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", name: "USD Coin" },
+  10: { asset: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", name: "USD Coin" },
+  43114: { asset: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", name: "USD Coin" },
+  1329: { asset: "0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392", name: "USDC" },
+};
+const CHAIN_BY_NAME = { base: 8453, celo: 42220, polygon: 137, arbitrum: 42161, optimism: 10, avalanche: 43114, sei: 1329 };
+
+/** "base" | "eip155:8453" -> chain id, or null. */
+export function edgeChainId(network) {
+  const n = String(network || "").trim().toLowerCase();
+  if (CHAIN_BY_NAME[n]) return CHAIN_BY_NAME[n];
+  const m = n.match(/^eip155:(\d+)$/);
+  return m ? Number(m[1]) : null;
+}
+
+/** "$0.001" | "0.001" | 0.001 -> base units at 6 decimals ("1000"), or null. */
+export function toBaseUnits(price, decimals = STABLECOIN_DECIMALS) {
+  const s = String(price ?? "").trim().replace(/^\$/, "");
+  if (!/^\d+(\.\d+)?$/.test(s)) return null;
+  const [whole, frac = ""] = s.split(".");
+  if (frac.length > decimals) return null; // sub-unit prices cannot be settled
+  const units = BigInt(whole) * 10n ** BigInt(decimals) + BigInt((frac + "0".repeat(decimals)).slice(0, decimals));
+  return units > 0n ? units.toString() : null;
+}
+
+async function hmacId(secret, c) {
+  const key = await crypto.subtle.importKey("raw", te.encode(String(secret)), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return bytesToB64url(await crypto.subtle.sign("HMAC", key, te.encode(challengeIdInput(c))));
+}
+function constEq(a, b) {
+  if (a.length !== b.length) return false;
+  let r = 0;
+  for (let i = 0; i < a.length; i++) r |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return r === 0;
+}
+
+/**
+ * Mint the gate's one MPP challenge. Returns { header, accepted } or null when
+ * the quote cannot be expressed as evm/charge (unknown chain, non-USDC asset
+ * with no `assetAddress`, unparseable price, no secret).
+ */
+export async function mintEdgeChallenge({ secret, realm, price, network, asset = "USDC", assetAddress, assetName, payTo, resource, ttlSeconds = 300 } = {}) {
+  if (!secret || !realm || !payTo || !resource) return null;
+  const chainId = edgeChainId(network);
+  if (!chainId) return null;
+  const known = EDGE_USDC[chainId];
+  const token = assetAddress || (String(asset).toUpperCase() === "USDC" && known ? known.asset : null);
+  if (!token) return null;
+  const amount = toBaseUnits(price);
+  if (!amount) return null;
+  // Any finite non-zero ttl is honoured (a negative one mints an already-expired
+  // challenge - the refusal path tests use it); 0/unset = 300 s.
+  const ttl = Number.isFinite(Number(ttlSeconds)) && Number(ttlSeconds) !== 0 ? Number(ttlSeconds) : 300;
+  const accepted = {
+    scheme: "exact",
+    network: `eip155:${chainId}`,
+    amount,
+    asset: token,
+    payTo,
+    maxTimeoutSeconds: ttl,
+    extra: { name: assetName || (assetAddress ? String(asset) : known.name), version: "2" },
+  };
+  const c = {
+    realm,
+    method: "evm",
+    intent: "charge",
+    request: encodeRequest({
+      amount,
+      currency: token,
+      recipient: payTo,
+      methodDetails: { chainId, credentialTypes: ["authorization"], decimals: STABLECOIN_DECIMALS },
+    }),
+    expires: new Date(Date.now() + ttl * 1000).toISOString(),
+    opaque: encodeRequest({ [META_ACCEPTS_KEY]: JSON.stringify(accepted), [META_RESOURCE_KEY]: resource }),
+  };
+  c.id = await hmacId(secret, c);
+  return { header: serializeChallenge(c), accepted };
+}
+
+/**
+ * Validate an MPP credential against our HMAC binding and re-encode it as an
+ * x402 v2 PAYMENT-SIGNATURE value. Returns { paymentSignature, accepted,
+ * authorization, signature, resource } or null for anything that is not a
+ * valid, unexpired, HMAC-bound evm/charge credential of ours.
+ */
+export async function translateEdgeCredential(authorizationHeader, { secret } = {}) {
+  if (!secret) return null;
+  const wire = decodeCredentialHeader(authorizationHeader);
+  const ch = wire?.challenge;
+  if (!challengeShapeOk(ch)) return null;
+  if (!constEq(String(ch.id), await hmacId(secret, ch))) return null;
+  if (ch.expires && !(Date.parse(ch.expires) > Date.now())) return null;
+  const meta = metaFromChallenge(ch);
+  let accepted;
+  try { accepted = JSON.parse(meta[META_ACCEPTS_KEY]); } catch { return null; }
+  if (!accepted || typeof accepted !== "object") return null;
+  const auth = authorizationFromPayload(wire.payload);
+  if (!auth) return null;
+  return { paymentSignature: paymentSignatureFor(accepted, auth), accepted, ...auth, resource: typeof meta[META_RESOURCE_KEY] === "string" ? meta[META_RESOURCE_KEY] : null };
+}

package/edge.js

@@ -8,6 +8,7 @@
 // See worker.js for a Cloudflare Worker entry, and the README for Next.js.
 import { makeBotMatcher, AI_BOTS } from "./bots.js";
 import { memorySink } from "./sinks.js";
+import { mintEdgeChallenge, translateEdgeCredential, isMppCredential } from "./edge-mpp.js";
 
 export { memorySink, kvStatsSink, httpStatsSink } from "./sinks.js";
 
@@ -135,6 +136,17 @@ export function createEdgeTollbooth(config = {}) {
     // payment, which is why the accepts block below is withheld when it is
     // absent - see the note there.
     verifyX402 = null,
+    // MPP (the "Payment" HTTP auth scheme) on the same verifier: default ON
+    // whenever the USDC quote is live (payTo + verifyX402 + secret). The 402
+    // gains a WWW-Authenticate: Payment challenge and an Authorization: Payment
+    // credential is translated to PAYMENT-SIGNATURE and handed to verifyX402.
+    // See edge-mpp.js. `mppAssetAddress`/`mppAssetName` name a token the
+    // built-in USDC table does not know (the domain name is what a facilitator
+    // verifies the EIP-3009 signature under).
+    mpp = true,
+    mppAssetAddress,
+    mppAssetName,
+    mppRealm,
     botUserAgents = AI_BOTS,
     // "bots" (default, charge AI crawler UAs) | "all" (charge all but free()) |
     // "strict" (charge anything that isn't a real-browser request). An explicit
@@ -163,6 +175,7 @@ export function createEdgeTollbooth(config = {}) {
     );
   }
 
+  const mppOn = Boolean(mpp && secret && payTo && verifyX402);
   const isBot = makeBotMatcher(botUserAgents);
   const powEngine = pow ? createEdgePow({ secret, difficulty: powDifficulty, store }) : null;
   const mem = memorySink();
@@ -222,6 +235,23 @@ export function createEdgeTollbooth(config = {}) {
         paid = false;
       }
       if (paid) { incr("paid"); return null; }
+    } else if (mppOn && isMppCredential(request.headers.get("authorization"))) {
+      // MPP inbound: only a credential whose challenge id HMAC-verifies as
+      // OURS, unexpired, and minted for THIS resource (a credential for /a
+      // must not pay for /b - the challenge carries the resource it was minted
+      // for). The verifier sees the same request with PAYMENT-SIGNATURE in
+      // place of Authorization, exactly as an x402 client would have sent it.
+      let paid = false;
+      try {
+        const t = await translateEdgeCredential(request.headers.get("authorization"), { secret });
+        if (t && t.resource === resource) {
+          const headers = new Headers(request.headers);
+          headers.set("payment-signature", t.paymentSignature);
+          headers.delete("authorization");
+          paid = await verifyX402(new Request(request, { headers }), { price, network, asset, payTo, resource, accepted: t.accepted });
+        }
+      } catch { paid = false; }
+      if (paid) { incr("paid"); incr("mppPaid"); return null; }
     }
 
     const sol = request.headers.get("x-pow-solution");
@@ -242,10 +272,16 @@ export function createEdgeTollbooth(config = {}) {
       accepts: (payTo && verifyX402) ? [{ scheme: "exact", network, maxAmountRequired: String(price), asset, payTo, resource }] : [],
     };
     if (powEngine) body.proofOfWork = await powEngine.challenge(powResource);
-    return new Response(JSON.stringify(body), {
-      status: 402,
-      headers: { "content-type": "application/json", "x-tollbooth": "pay-per-crawl" },
-    });
+    const headers = { "content-type": "application/json", "x-tollbooth": "pay-per-crawl" };
+    if (mppOn) {
+      // One evm/charge challenge for the gate's quote (never a price the
+      // x402 path would not honour - both are built from the same fields).
+      try {
+        const minted = await mintEdgeChallenge({ secret, realm: mppRealm || u.host, price, network, asset, assetAddress: mppAssetAddress, assetName: mppAssetName, payTo, resource });
+        if (minted) headers["www-authenticate"] = minted.header;
+      } catch { /* a quote MPP cannot express is still a valid x402 402 */ }
+    }
+    return new Response(JSON.stringify(body), { status: 402, headers });
   }
 
   // Operator surface: in-process mirror (sync), durable snapshot (async),

package/index.js

@@ -12,7 +12,8 @@
 // The proof-of-work rail works out of the box with zero configuration. To also
 // accept USDC, set `payTo` and supply `verifyX402` (wire it to the standard
 // x402 server middleware / your facilitator — see README).
-import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { Readable } from "node:stream";
 import { randomBytes } from "node:crypto";
 import { createPow } from "./pow.js";
@@ -98,6 +99,8 @@ const STRIP_INBOUND = new Set([
   "host", "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
   "te", "trailer", "transfer-encoding", "upgrade", "content-length",
   "x-tollbooth-paid", "x-tollbooth-error", "x-pow-error", "x-forwarded-host", "forwarded",
+  // client-IP / scheme trust headers an upstream might honour (spoofable by the bot)
+  "x-real-ip", "cf-connecting-ip", "true-client-ip", "x-client-ip", "fastly-client-ip", "x-forwarded-proto", "x-forwarded-port", "via",
 ]);
 
 /**
@@ -689,8 +692,9 @@ export async function buildCliX402Middleware(env = process.env) {
   // Coinbase's facilitator (CDP) authenticates every verify/settle call with
   // a short-lived JWT signed by a CDP API key, so a static header cannot
   // reach it; @coinbase/x402's createFacilitatorConfig mints them. With the
-  // two keys set the CLI settles through CDP (fee-free on Base, and the
-  // endpoint is indexed in Coinbase's x402 Bazaar), no URL needed. This is
+  // two keys set the CLI settles through CDP (no fee is taken from the
+  // payment; CDP's own free tier is 1,000 settlements a month, then $0.001
+  // each), no URL needed. This is
   // the path a Coinbase Business account uses to get paid by agents.
   const cdpKeys = env.TOLLBOOTH_CDP_API_KEY_ID && env.TOLLBOOTH_CDP_API_KEY_SECRET;
   if (!payTo) return null;
@@ -715,7 +719,7 @@ export async function buildCliX402Middleware(env = process.env) {
     ({ HTTPFacilitatorClient, x402ResourceServer } = await import("@x402/core/server"));
     ({ ExactEvmScheme } = await import("@x402/evm/exact/server"));
   } catch (e) {
-    console.error(`✖ TOLLBOOTH_FACILITATOR_URL is set, so this gate must settle x402 payments, but the x402 packages are not installed (${String(e?.message || e).slice(0, 120)}). Install them next to agent402-tollbooth: npm i @x402/express @x402/core @x402/evm . Refusing to start rather than advertise a quote it cannot settle.`);
+    console.error(`✖ TOLLBOOTH_FACILITATOR_URL or TOLLBOOTH_CDP_API_KEY_ID/SECRET is set, so this gate must settle x402 payments, but the x402 packages are not installed (${String(e?.message || e).slice(0, 120)}). Install them next to agent402-tollbooth: npm i @x402/express @x402/core @x402/evm . Refusing to start rather than advertise a quote it cannot settle.`);
     process.exit(1);
   }
   // Optional facilitator auth headers, sent on /verify, /settle and /supported
@@ -726,13 +730,22 @@ export async function buildCliX402Middleware(env = process.env) {
   }
   let cdpConfig = null;
   if (cdpKeys) {
-    try {
-      const { createFacilitatorConfig } = await import("@coinbase/x402");
-      cdpConfig = createFacilitatorConfig(env.TOLLBOOTH_CDP_API_KEY_ID, env.TOLLBOOTH_CDP_API_KEY_SECRET);
-    } catch (e) {
+    if (facilitatorUrl || authHeaders) console.warn("⚠ TOLLBOOTH_CDP_API_KEY_ID/SECRET are set, so TOLLBOOTH_FACILITATOR_URL / TOLLBOOTH_FACILITATOR_HEADERS are ignored: settlement goes through Coinbase's facilitator.");
+    let createFacilitatorConfig;
+    try { ({ createFacilitatorConfig } = await import("@coinbase/x402")); } catch (e) {
       console.error(`✖ TOLLBOOTH_CDP_API_KEY_ID/SECRET are set, so this gate must settle through Coinbase's facilitator, but @coinbase/x402 is not installed (${String(e?.message || e).slice(0, 120)}). Install it: npm install @coinbase/x402`);
       process.exit(1);
     }
+    cdpConfig = createFacilitatorConfig(env.TOLLBOOTH_CDP_API_KEY_ID, env.TOLLBOOTH_CDP_API_KEY_SECRET);
+    // Prove the key can sign BEFORE claiming to settle: createFacilitatorConfig
+    // validates nothing, and a key that cannot mint a JWT would otherwise boot
+    // "settling via Coinbase CDP" and answer every paid request 500 (nobody
+    // charged, every agent turned away). Minting one JWT is local, no network.
+    try { await cdpConfig.createAuthHeaders(); } catch (e) {
+      const why = String(e?.message || e).replace(env.TOLLBOOTH_CDP_API_KEY_SECRET, "<secret>").slice(0, 160);
+      console.error(`✖ TOLLBOOTH_CDP_API_KEY_SECRET cannot sign a facilitator request (${why}). Check the CDP API key secret; nothing is being charged.`);
+      process.exit(1);
+    }
   }
   const client = new HTTPFacilitatorClient(cdpConfig || {
     url: facilitatorUrl,
@@ -873,12 +886,39 @@ async function startCli() {
   } else {
     app.use((_req, res) => res.json({ ok: true, note: "Bare tollbooth gate (no TOLLBOOTH_UPSTREAM set). Clients that reach here paid or solved a proof-of-work." }));
   }
-  app.listen(port, () => {
+  const server = app.listen(port, () => {
     const paidLabel = x402mw ? `x402 + MPP (${process.env.TOLLBOOTH_ASSET || "USDC"}, settling via ${process.env.TOLLBOOTH_CDP_API_KEY_ID && process.env.TOLLBOOTH_CDP_API_KEY_SECRET ? "Coinbase CDP" : process.env.TOLLBOOTH_FACILITATOR_URL})` : (process.env.TOLLBOOTH_PAYTO ? `x402 quote only (${process.env.TOLLBOOTH_ASSET || "USDC"}, NOT settling - set TOLLBOOTH_FACILITATOR_URL)` : "");
     const rails = [gate.pow ? "proof-of-work" : "", paidLabel].filter(Boolean).join(" + ");
-    console.log(`agent402-tollbooth listening on :${port} — charging AI bots via ${rails || "proof-of-work"}`);
+    // The BOUND port, so PORT=0 (let the OS pick) prints something a caller can use.
+    const bound = server.address()?.port ?? port;
+    console.log(`agent402-tollbooth listening on :${bound} — charging AI bots via ${rails || "proof-of-work"}`);
     if (upstream) console.log(`  proxying → ${upstream}`);
   });
+  // Evidence for a process that leaves without being told to. Four times
+  // (2026-08-19, 08-22, 08-26, 08-27; CI only, never locally) the CLI printed the
+  // banner above and then exited 0 with no signal and no --trace-exit stack: the
+  // event loop drained under a LISTENING server, which should be impossible while
+  // the handle is ref'd. `beforeExit` is the one hook that fires exactly then;
+  // naming the live handles and the server's own state at that instant is the
+  // record every earlier occurrence lacked. Costs nothing in a healthy process
+  // (it never fires while the server listens).
+  server.on("close", () => console.error("[agent402-tollbooth] http server closed"));
+  server.on("error", (e) => console.error(`[agent402-tollbooth] http server error: ${e?.code || ""} ${e?.message || e}`));
+  process.on("beforeExit", (code) => {
+    let active = "?";
+    try { active = JSON.stringify(process.getActiveResourcesInfo()); } catch { /* older node */ }
+    console.error(`[agent402-tollbooth] event loop drained (exit code ${code}) while listening=${server.listening} address=${JSON.stringify(server.address())} active=${active}`);
+  });
 }
 
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) startCli();
+// THE BIN SYMLINK. npm links the bin as `.bin/agent402-tollbooth`, so argv[1]
+// is the SYMLINK path while import.meta.url is the realpath - they never match,
+// and the documented install path (`npx agent402-tollbooth`) started nothing at
+// all while `node index.js` worked fine. Exactly the defect found and fixed in
+// agent402-openclaw 0.1.2; it survived here because every test invokes
+// index.js by path, which is the one way to call it that cannot see the bug.
+// Compare the REALPATH, the way openclaw/cli.js does.
+function invokedDirectly() {
+  try { return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href; } catch { return false; }
+}
+if (process.argv[1] && invokedDirectly()) startCli();

package/mpp-codec.js

@@ -0,0 +1,139 @@
+// MPP wire codec shared by the Node build (mpp.js, HMAC via node:crypto) and
+// the edge build (edge-mpp.js, HMAC via Web Crypto). Runtime-agnostic on
+// purpose: no node:* imports, no Buffer - only TextEncoder/TextDecoder,
+// btoa/atob, which every Fetch-API runtime (Workers, Next.js edge, Deno, Bun,
+// Node 20+) provides. Nothing in here signs or verifies; the two builds own
+// that, so this file cannot mint a challenge on its own.
+//
+// Wire (tempoxyz/mpp, paymentauth.org):
+//   challenge   WWW-Authenticate: Payment id="...", realm="...", method="evm",
+//               intent="charge", request="<b64url JCS>", expires="...", opaque="<b64url JCS>"
+//   credential  Authorization: Payment <b64url JSON{challenge, payload, source?}>
+//   receipt     Payment-Receipt: <b64url JSON{method, status, reference, timestamp}>
+export const SCHEME = "Payment";
+export const META_ACCEPTS_KEY = "x402";
+export const STABLECOIN_DECIMALS = 6; // Circle USDC + Paxos USDG on every EVM rail
+// What a stock mppx client can auto-sign (its built-in asset registry covers
+// Base + Celo mainnets); every extra challenge costs ~800 bytes on every 402.
+export const DEFAULT_MPP_CHAIN_IDS = [8453, 42220];
+
+const te = new TextEncoder();
+const td = new TextDecoder();
+function bytesToBinary(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+  return s;
+}
+const binaryToBytes = (bin) => Uint8Array.from(bin, (c) => c.charCodeAt(0));
+/** utf8 string -> standard base64 */
+export const b64std = (s) => btoa(bytesToBinary(te.encode(String(s))));
+/** standard base64 -> utf8 string (throws on junk) */
+export const unb64std = (s) => td.decode(binaryToBytes(atob(String(s).replace(/-/g, "+").replace(/_/g, "/").replace(/\s+/g, ""))));
+/** utf8 string -> base64url (no padding) */
+export const b64url = (s) => b64std(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+/** base64url -> utf8 string (padding optional; throws on junk) */
+export function unb64url(s) {
+  let v = String(s).replace(/-/g, "+").replace(/_/g, "/");
+  while (v.length % 4) v += "=";
+  return td.decode(binaryToBytes(atob(v)));
+}
+/** bytes -> base64url, for HMAC digests */
+export const bytesToB64url = (bytes) => btoa(bytesToBinary(new Uint8Array(bytes))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+/** RFC 8785-style canonical JSON (sorted object keys, no whitespace) - what the
+ *  reference implementation uses for the `request`/`opaque` slots. */
+export function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+}
+export const encodeRequest = (obj) => b64url(canonicalJson(obj));
+
+/** Positional id-binding input - the same slot layout the reference
+ *  implementation HMACs, so its Challenge.verify() agrees with ours given the
+ *  same secret. The builds sign this string. */
+export const challengeIdInput = (c) =>
+  [c.realm, c.method, c.intent, c.request, c.expires ?? "", c.digest ?? "", c.opaque ?? ""].join("|");
+
+export const authParam = (name, value) => {
+  const v = String(value);
+  if (/[\r\n]/.test(v)) throw new Error("invalid auth-param value");
+  return `${name}="${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+};
+
+/** One serialized challenge (the caller has already set `c.id`). */
+export function serializeChallenge(c) {
+  return `${SCHEME} ` + [
+    authParam("id", c.id), authParam("realm", c.realm), authParam("method", c.method), authParam("intent", c.intent),
+    authParam("request", c.request), authParam("expires", c.expires), authParam("opaque", c.opaque),
+  ].join(", ");
+}
+
+/** The evm/charge request slot for one x402-shaped accept. */
+export function chargeRequestFor({ amount, asset, chainId }) {
+  return encodeRequest({
+    amount: String(amount),
+    currency: asset,
+    // `recipient` is filled by the caller's accept; kept explicit there.
+    methodDetails: { chainId, credentialTypes: ["authorization"], decimals: STABLECOIN_DECIMALS },
+  });
+}
+
+/** True when the header looks like an MPP credential (scheme check only). */
+export function isMppCredential(authorizationHeader) {
+  return typeof authorizationHeader === "string" && /^Payment\s+\S/i.test(authorizationHeader);
+}
+
+/** Decode `Authorization: Payment <b64url JSON>` to its wire object, or null. */
+export function decodeCredentialHeader(authorizationHeader) {
+  if (typeof authorizationHeader !== "string") return null;
+  const m = authorizationHeader.match(/^Payment\s+([A-Za-z0-9_-]+=*)\s*$/i);
+  if (!m) return null;
+  try { return JSON.parse(unb64url(m[1])); } catch { return null; }
+}
+
+/** Shape-check an evm/charge challenge object from a credential (no HMAC here). */
+export function challengeShapeOk(ch) {
+  return !!ch && typeof ch === "object" && ch.method === "evm" && ch.intent === "charge"
+    && typeof ch.request === "string" && typeof ch.opaque === "string" && typeof ch.id === "string";
+}
+
+/** The meta object bound into the challenge's opaque slot, or null. */
+export function metaFromChallenge(ch) {
+  try {
+    const meta = JSON.parse(unb64url(ch.opaque));
+    return meta && typeof meta === "object" ? meta : null;
+  } catch { return null; }
+}
+
+const HEX_ADDR = /^0x[0-9a-fA-F]{40}$/;
+const HEX_32 = /^0x[0-9a-fA-F]{64}$/;
+const HEX_SIG = /^0x[0-9a-fA-F]+$/;
+const UINT = /^\d+$/;
+/** Validate an `authorization` payload; returns {authorization, signature} or null. */
+export function authorizationFromPayload(p) {
+  if (!p || p.type !== "authorization") return null;
+  const { from, to, value, validAfter, validBefore, nonce, signature } = p;
+  if (!HEX_ADDR.test(String(from)) || !HEX_ADDR.test(String(to)) || !HEX_32.test(String(nonce)) || !HEX_SIG.test(String(signature))) return null;
+  if (!UINT.test(String(value)) || !UINT.test(String(validAfter)) || !UINT.test(String(validBefore))) return null;
+  return { authorization: { from, to, value: String(value), validAfter: String(validAfter), validBefore: String(validBefore), nonce }, signature };
+}
+
+/** x402 v2 PAYMENT-SIGNATURE value (standard base64 JSON) for an accept + authorization. */
+export function paymentSignatureFor(accepted, { authorization, signature }) {
+  return b64std(JSON.stringify({ x402Version: 2, accepted, payload: { authorization, signature } }));
+}
+
+/** MPP Payment-Receipt value for a settled transaction reference. */
+export function receiptFor(transaction) {
+  return b64url(JSON.stringify({ method: "evm", status: "success", reference: transaction, timestamp: new Date().toISOString() }));
+}
+
+/** Decode a settled x402 PAYMENT-RESPONSE header to its transaction, or null. */
+export function transactionFromPaymentResponse(paymentResponseHeader) {
+  let settle;
+  try { settle = JSON.parse(unb64std(paymentResponseHeader)); } catch { return null; }
+  if (!settle || settle.success !== true || typeof settle.transaction !== "string") return null;
+  return settle.transaction;
+}

package/mpp.js

@@ -29,47 +29,28 @@
 // reference client is proven by scripts/test-tollbooth-mpp.js in the parent
 // repo, which drives a REAL mppx client through this codec.
 import { createHmac, timingSafeEqual } from "node:crypto";
+import {
+  META_ACCEPTS_KEY, STABLECOIN_DECIMALS, DEFAULT_MPP_CHAIN_IDS, b64url, unb64url, b64std, unb64std,
+  canonicalJson, encodeRequest, challengeIdInput, serializeChallenge, decodeCredentialHeader, challengeShapeOk,
+  metaFromChallenge, authorizationFromPayload, paymentSignatureFor, receiptFor, transactionFromPaymentResponse,
+} from "./mpp-codec.js";
 
-const SCHEME = "Payment";
-const META_ACCEPTS_KEY = "x402";
-const STABLECOIN_DECIMALS = 6; // Circle USDC + Paxos USDG on every EVM rail
-// What a stock mppx client can auto-sign (its built-in asset registry covers
-// Base + Celo mainnets); every extra challenge costs ~800 bytes on every 402.
-export const DEFAULT_MPP_CHAIN_IDS = [8453, 42220];
-
-// ---- encoding primitives ---------------------------------------------------
-export const b64url = (s) => Buffer.from(s, "utf8").toString("base64url");
-export const unb64url = (s) => Buffer.from(String(s), "base64url").toString("utf8");
-const b64std = (s) => Buffer.from(s, "utf8").toString("base64");
-const unb64std = (s) => Buffer.from(String(s), "base64").toString("utf8");
-
-/** RFC 8785-style canonical JSON (sorted object keys, no whitespace) - what the
- *  reference implementation uses for the `request`/`opaque` slots. */
-export function canonicalJson(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
-}
-const encodeRequest = (obj) => b64url(canonicalJson(obj));
+// The wire primitives live in mpp-codec.js (runtime-agnostic, shared with the
+// edge build); this file adds the node:crypto HMAC binding on top.
+export { DEFAULT_MPP_CHAIN_IDS, b64url, unb64url, canonicalJson };
+export { isMppCredential } from "./mpp-codec.js";
 
 // Positional HMAC binding of the challenge id - the same slot layout the
 // reference implementation uses, so its Challenge.verify() agrees with ours
 // given the same secret (handy in tests; the spec only requires that WE bind).
 function challengeId(secretKey, c) {
-  const input = [c.realm, c.method, c.intent, c.request, c.expires ?? "", c.digest ?? "", c.opaque ?? ""].join("|");
-  return createHmac("sha256", Buffer.from(secretKey, "utf8")).update(input, "utf8").digest("base64url");
+  return createHmac("sha256", Buffer.from(secretKey, "utf8")).update(challengeIdInput(c), "utf8").digest("base64url");
 }
 function idMatches(secretKey, c) {
   const a = Buffer.from(String(c.id || ""), "utf8");
   const b = Buffer.from(challengeId(secretKey, c), "utf8");
   return a.length === b.length && timingSafeEqual(a, b);
 }
-const authParam = (name, value) => {
-  const v = String(value);
-  if (/[\r\n]/.test(v)) throw new Error("invalid auth-param value");
-  return `${name}="${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-};
 
 // ---- OUTBOUND: PAYMENT-REQUIRED -> WWW-Authenticate: Payment ---------------
 /**
@@ -110,67 +91,37 @@ export function challengesFromPaymentRequired(paymentRequiredHeader, { secretKey
       opaque: encodeRequest({ [META_ACCEPTS_KEY]: JSON.stringify(a) }),
     };
     c.id = challengeId(secretKey, c);
-    out.push([
-      authParam("id", c.id), authParam("realm", c.realm), authParam("method", c.method), authParam("intent", c.intent),
-      authParam("request", c.request), authParam("expires", c.expires), authParam("opaque", c.opaque),
-    ].join(", "));
+    out.push(serializeChallenge(c));
   }
   if (!out.length) return null;
-  return out.map((p) => `${SCHEME} ${p}`).join(", ");
+  return out.join(", ");
 }
 
 // ---- INBOUND: Authorization: Payment -> PAYMENT-SIGNATURE ------------------
-const HEX_ADDR = /^0x[0-9a-fA-F]{40}$/;
-const HEX_32 = /^0x[0-9a-fA-F]{64}$/;
-const HEX_SIG = /^0x[0-9a-fA-F]+$/;
-const UINT = /^\d+$/;
-
 /**
  * Validate an MPP credential against our HMAC binding and re-encode it as an
  * x402 v2 PAYMENT-SIGNATURE value. Returns null for anything that is not a
  * valid, unexpired, HMAC-bound evm/charge credential of ours.
  */
 export function translateCredential(authorizationHeader, { secretKey } = {}) {
-  if (!secretKey || typeof authorizationHeader !== "string") return null;
-  const m = authorizationHeader.match(/^Payment\s+([A-Za-z0-9_-]+=*)\s*$/i);
-  if (!m) return null;
-  let wire;
-  try { wire = JSON.parse(unb64url(m[1])); } catch { return null; }
+  if (!secretKey) return null;
+  const wire = decodeCredentialHeader(authorizationHeader);
   const ch = wire?.challenge;
-  if (!ch || typeof ch !== "object") return null;
-  if (ch.method !== "evm" || ch.intent !== "charge") return null;
-  if (typeof ch.request !== "string" || typeof ch.opaque !== "string") return null;
+  if (!challengeShapeOk(ch)) return null;
   // HMAC binding (spec: servers MUST bind ids to challenge params). This also
   // proves the echoed accepts entry in opaque is ours and untampered.
   if (!idMatches(secretKey, ch)) return null;
   if (ch.expires && !(Date.parse(ch.expires) > Date.now())) return null;
   let accepted;
-  try {
-    const meta = JSON.parse(unb64url(ch.opaque));
-    accepted = JSON.parse(meta[META_ACCEPTS_KEY]);
-  } catch { return null; }
+  try { accepted = JSON.parse(metaFromChallenge(ch)[META_ACCEPTS_KEY]); } catch { return null; }
   if (!accepted || typeof accepted !== "object") return null;
-  const p = wire.payload;
-  if (!p || p.type !== "authorization") return null;
-  const { from, to, value, validAfter, validBefore, nonce, signature } = p;
-  if (!HEX_ADDR.test(String(from)) || !HEX_ADDR.test(String(to)) || !HEX_32.test(String(nonce)) || !HEX_SIG.test(String(signature))) return null;
-  if (!UINT.test(String(value)) || !UINT.test(String(validAfter)) || !UINT.test(String(validBefore))) return null;
-  return b64std(JSON.stringify({
-    x402Version: 2,
-    accepted,
-    payload: { authorization: { from, to, value: String(value), validAfter: String(validAfter), validBefore: String(validBefore), nonce }, signature },
-  }));
+  const auth = authorizationFromPayload(wire.payload);
+  if (!auth) return null;
+  return paymentSignatureFor(accepted, auth);
 }
 
 // ---- RECEIPT: PAYMENT-RESPONSE -> Payment-Receipt -------------------------
 export function receiptFromPaymentResponse(paymentResponseHeader) {
-  let settle;
-  try { settle = JSON.parse(unb64std(paymentResponseHeader)); } catch { return null; }
-  if (!settle || settle.success !== true || typeof settle.transaction !== "string") return null;
-  return b64url(JSON.stringify({ method: "evm", status: "success", reference: settle.transaction, timestamp: new Date().toISOString() }));
-}
-
-/** True when the header looks like an MPP credential (scheme check only). */
-export function isMppCredential(authorizationHeader) {
-  return typeof authorizationHeader === "string" && /^Payment\s+\S/i.test(authorizationHeader);
+  const tx = transactionFromPaymentResponse(paymentResponseHeader);
+  return tx ? receiptFor(tx) : null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-tollbooth",
-  "version": "0.9.3",
+  "version": "0.10.1",
   "description": "Agent402 tollbooth: open-source, self-hostable pay-per-crawl for x402 AND MPP (the sell side of Agentic Finance): charge AI bots per request (USDC via x402, or MPP - the Machine Payments Protocol - through the same settlement, or USDG on Robinhood Chain, or free proof-of-work) while humans browse free. Drop-in Express middleware or reverse proxy that settles both wires from env alone - no Cloudflare, no Stripe, no signup.",
   "type": "module",
   "main": "index.js",
@@ -18,7 +18,10 @@
     "./replay": "./replay.js",
     "./replay.js": "./replay.js",
     "./mpp": "./mpp.js",
-    "./mpp.js": "./mpp.js"
+    "./mpp.js": "./mpp.js",
+    "./edge-mpp": "./edge-mpp.js",
+    "./edge-mpp.js": "./edge-mpp.js",
+    "./mpp-codec.js": "./mpp-codec.js"
   },
   "files": [
     "index.js",
@@ -27,6 +30,8 @@
     "bots.js",
     "pow.js",
     "mpp.js",
+    "mpp-codec.js",
+    "edge-mpp.js",
     "tempo.js",
     "dashboard.js",
     "sinks.js",