agent402-tollbooth 0.6.1 → 0.7.0

package/README.md

@@ -1,9 +1,12 @@
 # agent402-tollbooth
 
-**Open-source, self-hostable x402 "pay-per-crawl". Put it in front of any site or
-API: humans browse free, AI crawlers and agents pay per request** - either in
-USDC over the [x402 protocol](https://x402.org), or for free by solving a
+**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.
+The first self-hostable pay-per-crawl gate that speaks both wires on one 402.
 
 The big platforms are converging on the same model: Cloudflare's
 [pay-per-crawl](https://stackoverflow.blog/2026/02/26/how-pay-per-crawl-is-reshaping-data-monetization/)
@@ -142,37 +145,65 @@ 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 and MPP are Node/Express features today; the
+> edge gate offers proof-of-work plus the `verifyX402` callback.
 
-## Accepting USDC (x402)
+## Accepting USDC: x402 and MPP on the same 402
 
-The proof-of-work rail works with **zero config**. To also settle real USDC,
-set `payTo` and supply `verifyX402` - wire it to the standard, audited x402
-server stack (`@x402/express` / your facilitator) rather than reinventing
-settlement:
+The proof-of-work rail works with **zero config**. To also settle real money,
+hand the gate your standard, audited x402 middleware (`@x402/express` v2) as
+`x402:` - the gate never reinvents settlement, it delegates to it:
 
 ```js
-import { createTollbooth, x402VerifierFromExpress } from "agent402-tollbooth";
-import { paymentMiddleware } from "x402-express"; // or @x402/express
-const x402 = paymentMiddleware(/* your wallet + facilitator config */);
-
-app.use(createTollbooth({
-  payTo: "0xYourWallet",
-  network: "base",
-  // First-party verifier that OWNS timeout + cancellation: it honors the
-  // AbortSignal the gate passes on the SECOND argument (opts.signal), so a slow
-  // middleware can't hang the gate or settle after the gate already returned 402.
-  verifyX402: x402VerifierFromExpress(x402, { timeoutMs: 9000 }),
-}));
+import { createTollbooth } from "agent402-tollbooth";
+import { paymentMiddleware } from "@x402/express";
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+
+const server = new x402ResourceServer(new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" }))
+  .register("eip155:8453", new ExactEvmScheme());
+const x402 = paymentMiddleware(
+  { "GET /*": { accepts: [{ scheme: "exact", network: "eip155:8453", price: "$0.001", payTo: "0xYourWallet" }] } },
+  server,
+);
+
+app.use(createTollbooth({ payTo: "0xYourWallet", x402 }));
 ```
 
-The gate calls `verifyX402(req, opts)` and puts an `AbortSignal` on `opts.signal`
-(aborted when its `TOLLBOOTH_VERIFY_TIMEOUT_MS` fires). `x402VerifierFromExpress`
-honors it and stops treating a late result as valid. Note @x402/express settles
-by broadcasting and has no cancel hook, so keep the timeout above your settle
-latency (the abort is a backstop); a verifier that ignores the signal entirely
-can still charge a buyer who already received a 402. If you write your own
-verifier instead of using the helper, destructure `opts.signal` and reject/stop
-on abort. (PoW is checked first, so an agent without a wallet always has a free path.)
+What you get on every charged request:
+
+- **x402 v2 clients pay.** The gate lifts the middleware's `PAYMENT-REQUIRED`
+  header onto its own 402, so a stock `@x402/fetch` client negotiates and pays
+  as if the middleware were mounted bare. Verify, your handler, and settlement
+  run in the middleware's own order (v2 settles after the handler ends the
+  response) - exactly once.
+- **MPP clients pay** (default on when `x402` is set; `mpp: false` to turn off).
+  The same 402 gains `WWW-Authenticate: Payment` challenges (`evm`/`charge`,
+  one per EVM chain the middleware advertises among `mppNetworks`, default
+  Base + Celo). An inbound `Authorization: Payment` credential whose challenge
+  id HMAC-verifies is re-encoded as `PAYMENT-SIGNATURE` and settled by the
+  same middleware; the settled response carries a `Payment-Receipt`. A stock
+  [`mppx`](https://www.npmjs.com/package/mppx) client works unmodified. The
+  codec is dependency-free (no mppx on the server side) and byte-compatible
+  with the reference client - proven in the parent repo's CI by a real mppx
+  purchase through this package.
+- **Proof-of-work first**, unchanged: a walletless agent always has a free path.
+
+Set a stable `TOLLBOOTH_SECRET` (or `mppSecret`) so MPP challenge ids verify
+across workers - the same caveat as proof-of-work tokens.
+
+### `verifyX402` (legacy, deprecated in 0.7.0)
+
+Older versions took a verify-only callback (`verifyX402(req, opts) => boolean`)
+and shipped `x402VerifierFromExpress()` to build one from a payment middleware.
+**With `@x402/express` v2 that helper grants on verify and never settles**: v2
+settles after the handler ends the response, and the helper handed it a stub
+response the real handler never ended, so buyers were served and never charged
+(measured in the parent repo's test suite). It only ever settled with v1
+middlewares that settled before calling `next()`. It still works for those and
+for custom verifiers you wrote yourself, and now warns once at construction;
+everyone else should pass the middleware as `x402:` above. `verifyX402` still
+receives `opts.signal` (aborted on `TOLLBOOTH_VERIFY_TIMEOUT_MS`).
 
 ## Configuration
 
@@ -190,7 +221,11 @@ on abort. (PoW is checked first, so an agent without a wallet always has a free
 | `botUserAgents` | `AI_BOTS` | User-agents to charge in `"bots"` mode |
 | `charge(req)` | mode | Custom "should this client pay?" predicate (wins over `mode`) |
 | `free(req)` | – | Custom force-allow predicate (wins over everything) |
-| `verifyX402(req, reqs)` | – | Async USDC settlement check (return `true` to allow) |
+| `x402` | – | Your `@x402/express` `paymentMiddleware(...)`: owns verify + settle; enables x402 v2 clients and (by default) MPP |
+| `mpp` | `true` when `x402` set | Accept MPP (`WWW-Authenticate: Payment` / `Authorization: Payment`) through the `x402` middleware |
+| `mppSecret` | `powSecret` / `TOLLBOOTH_SECRET` | HMAC secret binding MPP challenge ids (stable across workers) |
+| `mppNetworks` | `[8453, 42220]` | EVM chain ids to offer as MPP challenges (`"all"` = every EVM chain the middleware advertises) |
+| `verifyX402(req, opts)` | – | Legacy verify-only USDC check (deprecated for settle-after-handler middlewares; see above) |
 | `resourceBaseUrl` | `""` | Absolute base used for the `resource` field / PoW binding |
 | `observe` | `false` | Observe-only: classify and count, but never 402. For pre-launch traffic measurement. |
 | `statsSink` | in-memory | Durable stats backend. Built-ins: `memorySink`, `kvStatsSink(kv)`, `httpStatsSink(url)`. |
@@ -206,6 +241,9 @@ Read by the bundled proxy / Express entry point (`index.js`):
 | `TOLLBOOTH_PAYTO` | – | Wallet address; set to advertise a USDC x402 quote |
 | `TOLLBOOTH_PRICE` | `"$0.001"` | Advertised price per request |
 | `TOLLBOOTH_NETWORK` | `"base"` | x402 network |
+| `TOLLBOOTH_MPP` | on when `x402` set | `false` to switch MPP off |
+| `TOLLBOOTH_MPP_SECRET` | `TOLLBOOTH_SECRET` | HMAC secret for MPP challenge ids |
+| `TOLLBOOTH_MPP_NETWORKS` | `8453,42220` | CSV of EVM chain ids to offer as MPP challenges, or `all` |
 | `TOLLBOOTH_ASSET` | `"USDC"` | Asset symbol in the quote (`USDG` charges in USDG on Robinhood Chain) |
 | `TOLLBOOTH_POW_BITS` | `18` | Proof-of-work difficulty in leading zero bits |
 | `TOLLBOOTH_MODE` | `"bots"` | Who pays: `bots` · `all` · `strict` |
@@ -273,7 +311,7 @@ changes. Bots see a `X-Tollbooth-Observed: would-charge` header in observe mode
 ## Analytics
 
 The middleware keeps aggregate counters (no per-request data):
-- `gate.stats()` → sync, in-process mirror: `{ requests, freeAllowed, wouldCharge, charged, powSolved, x402Paid, difficultyNow, observe }`.
+- `gate.stats()` → sync, in-process mirror: `{ requests, freeAllowed, wouldCharge, charged, powSolved, x402Paid, mppPaid, difficultyNow, observe }`.
 - `gate.snapshot()` → async, reads from the configured durable sink (defaults to memory).
 - `gate.flush()` → flush any buffered deltas to the durable sink (call inside `ctx.waitUntil` on edge runtimes).
 
@@ -465,9 +503,12 @@ TOLLBOOTH_ASSET=USDG \
 npx agent402-tollbooth
 ```
 
-or in code: `createTollbooth({ payTo, network: "eip155:4663", asset: "USDG", verifyX402 })`.
-Wire `verifyX402` to an x402 facilitator that settles chain 4663. Defaults
-are unchanged (USDC on Base).
+or in code: `createTollbooth({ payTo, network: "eip155:4663", asset: "USDG", x402 })`,
+where `x402` is a `@x402/express` middleware whose facilitator settles chain
+4663 (advertise `eip155:4663` in its `accepts`). Defaults are unchanged (USDC
+on Base). MPP challenges are only minted for chains in `mppNetworks` (Base +
+Celo by default - what a stock mppx client can sign); add `4663` there or pass
+`"all"` if your buyers' MPP clients can sign USDG on Robinhood Chain.
 
 ## Legal
 

package/dashboard.js

@@ -101,7 +101,7 @@ export function dashboardHtml() {
     </div>
     <div class="probe">
       <div class="label"><span>KPI grep — single-line dashboard for a shell</span><button class="copy" data-target="p5">copy</button></div>
-      <pre id="p5">curl -s &lt;origin&gt;/__tollbooth/stats | jq '{requests, charged, powSolved, x402Paid}'</pre>
+      <pre id="p5">curl -s &lt;origin&gt;/__tollbooth/stats | jq '{requests, charged, powSolved, x402Paid, mppPaid}'</pre>
     </div>
   </div>
   <footer>Aggregate counts only (no per-request data). Raw JSON: <a href="/__tollbooth/stats">/__tollbooth/stats</a>.</footer>
@@ -113,7 +113,8 @@ const cards=[
   ["wouldCharge","Would charge (observe)","accent"],
   ["charged","Charged (402)","accent"],
   ["powSolved","Proof-of-work paid","accent"],
-  ["x402Paid","USDC paid (x402)","accent"],
+  ["x402Paid","Paid via x402","accent"],
+  ["mppPaid","Paid via MPP","accent"],
   ["difficultyNow","PoW difficulty",false]
 ];
 // Rolling poll-delta series for the sparkline. We retain up to MAX_POINTS
@@ -211,7 +212,7 @@ async function tick(){
     document.getElementById("botpct").textContent=pct+"%";
     // Paid conversion: of all requests, what share actually settled (either
     // PoW or USDC). Answers "is the gate converting traffic into payment?"
-    var pow=Number(s.powSolved)||0, usd=Number(s.x402Paid)||0, paid=pow+usd;
+    var pow=Number(s.powSolved)||0, usd=(Number(s.x402Paid)||0)+(Number(s.mppPaid)||0), paid=pow+usd;
     var paidPct=reqs?Math.round((paid/reqs)*100):0;
     document.getElementById("paidpct").textContent=paidPct+"%";
     // Paid-in-USDC share: of *paid* requests, how many settled in USDC vs PoW.
@@ -224,7 +225,7 @@ async function tick(){
     // per-poll arrival rate. First tick seeds lastRequests/lastPaid with no
     // plot — we need a baseline to subtract on tick #2.
     var now=Number(s.requests); if(!Number.isFinite(now)) now=0;
-    var nowPaid=(Number(s.powSolved)||0)+(Number(s.x402Paid)||0);
+    var nowPaid=(Number(s.powSolved)||0)+(Number(s.x402Paid)||0)+(Number(s.mppPaid)||0);
     if(lastRequests!==null){
       var delta=Math.max(0,now-lastRequests);
       var pDelta=Math.max(0,nowPaid-lastPaid);

package/index.js

@@ -14,14 +14,17 @@
 // x402 server middleware / your facilitator — see README).
 import { fileURLToPath } from "node:url";
 import { Readable } from "node:stream";
+import { randomBytes } from "node:crypto";
 import { createPow } from "./pow.js";
 import { makeBotMatcher, AI_BOTS } from "./bots.js";
 import { memorySink } from "./sinks.js";
+import { challengesFromPaymentRequired, translateCredential, receiptFromPaymentResponse, isMppCredential, DEFAULT_MPP_CHAIN_IDS } from "./mpp.js";
 
 export { AI_BOTS, makeBotMatcher } from "./bots.js";
 export { createPow, leadingZeroBits } from "./pow.js";
 export { memorySink, kvStatsSink, httpStatsSink } from "./sinks.js";
 export { sqliteReplayStore, redisReplayStore } from "./replay.js";
+export { challengesFromPaymentRequired, translateCredential, receiptFromPaymentResponse, DEFAULT_MPP_CHAIN_IDS } from "./mpp.js";
 
 const VERIFY_TIMEOUT_MS = Number(process.env.TOLLBOOTH_VERIFY_TIMEOUT_MS) || 10_000;
 
@@ -34,15 +37,31 @@ const VERIFY_TIMEOUT_MS = Number(process.env.TOLLBOOTH_VERIFY_TIMEOUT_MS) || 10_
 // the gate hanging or produce a charged-then-denied result after the gate has
 // returned 402. Grants on next(); denies when the middleware writes a 402.
 //
+// DEPRECATED (0.7.0) - use `createTollbooth({ x402: paymentMiddleware })` instead.
+// @x402/express v2's default `authorization` flow verifies BEFORE the handler
+// but SETTLES AFTER the handler ends the response (it wraps res.end and awaits
+// it). This wrapper hands the middleware a stub response that the real handler
+// never ends, so with a v2 middleware it grants on verify and the settlement
+// never runs: the buyer is served and never charged. It only ever settled with
+// v1 middlewares that settled before calling next(). Kept for those callers;
+// warns once at construction. The `x402` option delegates to the middleware
+// with the REAL response, so verify, handler and settle happen in the
+// middleware's own order, exactly once.
+//
 // LIMITATION (documented): @x402/express settles by BROADCASTING and exposes no
 // cancel hook, so this wrapper cannot abort an on-chain settle already in flight.
 // Keep TOLLBOOTH_VERIFY_TIMEOUT_MS comfortably above your settle latency so the
 // abort is a backstop, not the normal path; or front it with a facilitator that
 // supports cancellation.
+let warnedVerifierFromExpress = false;
 export function x402VerifierFromExpress(paymentMiddleware, { timeoutMs } = {}) {
   if (typeof paymentMiddleware !== "function") {
     throw new TypeError("x402VerifierFromExpress: paymentMiddleware must be a function");
   }
+  if (!warnedVerifierFromExpress) {
+    warnedVerifierFromExpress = true;
+    console.warn("[agent402-tollbooth] x402VerifierFromExpress is deprecated: with @x402/express v2 (settle-after-handler) it grants on verify and never settles. Pass the middleware as createTollbooth({ x402: paymentMiddleware }) instead.");
+  }
   return (req, opts = {}) => new Promise((resolve, reject) => {
     const signal = opts?.signal;
     let done = false;
@@ -93,7 +112,16 @@ const STRIP_INBOUND = new Set([
  * @param {string[]} [config.botUserAgents]    user-agents to charge (default: AI_BOTS)
  * @param {(req)=>boolean} [config.charge]     custom "should this client pay?" predicate
  * @param {(req)=>boolean} [config.free]       custom force-allow predicate (wins over charge)
- * @param {(req, requirements)=>boolean|Promise<boolean>} [config.verifyX402]  USDC settlement check
+ * @param {(req, requirements)=>boolean|Promise<boolean>} [config.verifyX402]  legacy verify-only USDC check (deprecated for settle-after-handler middlewares; see `x402`)
+ * @param {Function} [config.x402]              an @x402/express `paymentMiddleware(...)` (or compatible (req,res,next)) that owns
+ *                                             verify + settle. The gate delegates paid requests to it with the REAL response, so
+ *                                             settlement runs in the middleware's own order (v2: after the handler), and it lifts
+ *                                             the middleware's PAYMENT-REQUIRED onto the gate's 402 so stock x402 v2 clients can pay.
+ * @param {boolean} [config.mpp]               accept MPP (Machine Payments Protocol) clients too - default true when `x402` is set.
+ *                                             Adds WWW-Authenticate: Payment challenges to the 402 and settles Authorization: Payment
+ *                                             credentials through the same `x402` middleware (evm/charge on the chains it advertises).
+ * @param {string} [config.mppSecret]          HMAC secret binding MPP challenge ids (default: powSecret / TOLLBOOTH_SECRET, else per-process random)
+ * @param {number[]|"all"} [config.mppNetworks] EVM chain ids to offer as MPP challenges (default Base + Celo, what a stock mppx client can sign)
  * @param {string} [config.resourceBaseUrl]    absolute base for the x402 `resource`/PoW binding
  * @param {string} [config.message]            human-readable note included in the 402
  * @param {boolean} [config.observe]           observe-only: classify, count, never 402 (deploy a week before enforcing)
@@ -128,6 +156,12 @@ export function createTollbooth(config = {}) {
     charge,
     free,
     verifyX402,
+    x402 = null,
+    mpp = config.mpp ?? (process.env.TOLLBOOTH_MPP ? process.env.TOLLBOOTH_MPP !== "false" : !!x402),
+    mppSecret,
+    mppNetworks = process.env.TOLLBOOTH_MPP_NETWORKS
+      ? (process.env.TOLLBOOTH_MPP_NETWORKS.trim().toLowerCase() === "all" ? "all" : process.env.TOLLBOOTH_MPP_NETWORKS.split(",").map((s) => Number(s.trim())).filter(Number.isInteger))
+      : DEFAULT_MPP_CHAIN_IDS,
     resourceBaseUrl = process.env.TOLLBOOTH_RESOURCE_BASE || "",
     // Adaptive proof-of-work: raise difficulty as charged-request load climbs, so
     // high-volume abuse pays escalating CPU regardless of how it disguises itself.
@@ -147,6 +181,18 @@ export function createTollbooth(config = {}) {
 
   const isBot = makeBotMatcher(botUserAgents);
   const powEngine = pow ? createPow({ difficulty: powDifficulty, secret: powSecret, replayStore }) : null;
+  if (x402 && typeof x402 !== "function") throw new TypeError("createTollbooth: `x402` must be an Express middleware function");
+  // MPP rides the x402 middleware (settlement authority) - without one there
+  // is nothing to settle an MPP credential with, so it stays off.
+  const mppOn = !!(mpp && x402);
+  // Challenge ids are HMAC-bound; a stable secret is needed across workers.
+  // Same caveat as PoW: per-process random works for one process only.
+  const mppKey = mppOn
+    ? String(mppSecret || powSecret || process.env.TOLLBOOTH_MPP_SECRET || process.env.TOLLBOOTH_SECRET || randomBytes(32).toString("hex"))
+    : null;
+  if (mppOn && !(mppSecret || powSecret || process.env.TOLLBOOTH_MPP_SECRET || process.env.TOLLBOOTH_SECRET)) {
+    console.warn("[agent402-tollbooth] MPP enabled with a per-process random secret - set TOLLBOOTH_SECRET (or mppSecret) for multi-worker deploys.");
+  }
 
   // Passive analytics — never affects request handling, just counts what happens.
   // `mem` is an always-on in-process mirror so `.stats()` stays synchronous for
@@ -218,7 +264,10 @@ export function createTollbooth(config = {}) {
     // stays a plain URL (below) for wire compatibility.
     const powResource = `${(req.method || "GET").toUpperCase()} ${resource}`;
 
-    const send402 = (extra = {}) => {
+    // `headers` = extra response headers to carry on the 402 (the x402
+    // middleware's own PAYMENT-REQUIRED and, when MPP is on, the derived
+    // WWW-Authenticate: Payment challenges).
+    const send402 = (extra = {}, headers = {}) => {
       incr("charged");
       if (adaptive) chargedWindow.push(Date.now());
       const body = {
@@ -230,14 +279,131 @@ export function createTollbooth(config = {}) {
         ...extra,
       };
       if (powEngine) body.proofOfWork = powEngine.challenge(powResource, difficultyNow());
+      for (const [k, v] of Object.entries(headers)) { if (v != null && v !== "") res.setHeader(k, v); }
       res.status(402).json(body);
     };
 
+    // Paid rail, middleware mode: delegate to the operator's x402 middleware
+    // with the REAL response so verify -> handler -> settle run in ITS order,
+    // exactly once. Its 402 (no/invalid payment) is intercepted and replaced by
+    // the gate's 402 - same body contract as ever (accepts + proofOfWork +
+    // message) plus the middleware's PAYMENT-REQUIRED header lifted verbatim,
+    // so a stock x402 v2 client can pay a tollbooth-gated site, and - when MPP
+    // is on - WWW-Authenticate: Payment challenges derived from that same
+    // header, so a stock mppx client can too. Anything the middleware writes
+    // that is NOT a 402 (facilitator 5xx, its own paywall HTML) passes through
+    // untouched: it is the operator's stack answering, not ours to rewrite.
+    const middlewareRail = () => {
+      // ---- MPP inbound: Authorization: Payment -> PAYMENT-SIGNATURE ----
+      // Only when the request is not already speaking x402 (pass-through is
+      // the no-regression rule), and only a credential whose challenge id
+      // HMAC-verifies as OURS. Anything else is ignored: the middleware
+      // answers 402 and the interceptor below mints fresh challenges.
+      let viaMpp = false;
+      if (mppOn && !req.headers["payment-signature"] && !req.headers["x-payment"] && isMppCredential(req.headers.authorization)) {
+        const sig = translateCredential(req.headers.authorization, { secretKey: mppKey });
+        if (sig) {
+          req.headers["payment-signature"] = sig;
+          delete req.headers.authorization; // consumed - never let it be double-read downstream
+          viaMpp = true;
+        }
+      }
+      // ---- MPP outbound receipt: mirror PAYMENT-RESPONSE as Payment-Receipt ----
+      // The middleware sets PAYMENT-RESPONSE after settlement and then replays
+      // the handler's buffered writeHead, so hooking writeHead HERE (before the
+      // middleware wraps it) sees the settled header at replay time.
+      if (viaMpp) {
+        const origWriteHead = res.writeHead;
+        res.writeHead = function tollboothMppWriteHead(...args) {
+          try {
+            if (res.statusCode === 200 && !res.getHeader("Payment-Receipt")) {
+              const settle = res.getHeader("PAYMENT-RESPONSE") || res.getHeader("payment-response");
+              const receipt = settle ? receiptFromPaymentResponse(String(settle)) : null;
+              if (receipt) res.setHeader("Payment-Receipt", receipt);
+            }
+          } catch { /* receipts are additive - never break the response */ }
+          return origWriteHead.apply(this, args);
+        };
+      }
+      // ---- 402 interceptor around the real response ----
+      // The middleware answers "no/invalid payment" with res.status(402) +
+      // setHeader(PAYMENT-REQUIRED ...) + json({}) (or send(html) for its
+      // paywall). Swallow THAT write and emit the gate's 402 instead, carrying
+      // the headers it set. Everything else reaches the real response.
+      let intercepting = true;
+      let granted = false;
+      const realStatus = res.status.bind(res);
+      const realJson = res.json.bind(res);
+      const realSend = res.send.bind(res);
+      const realEnd = res.end.bind(res);
+      const restore = () => { intercepting = false; res.status = realStatus; res.json = realJson; res.send = realSend; res.end = realEnd; };
+      const finish402 = () => {
+        // Collect the middleware's 402 headers before restoring; the gate's
+        // own send402 re-applies them on top of its body.
+        const lifted = {};
+        for (const name of ["PAYMENT-REQUIRED", "payment-required", "X-PAYMENT-REQUIRED", "x-payment-required"]) {
+          const v = res.getHeader(name);
+          if (v) lifted[name.toUpperCase() === "PAYMENT-REQUIRED" ? "PAYMENT-REQUIRED" : name] = String(v);
+        }
+        if (mppOn && lifted["PAYMENT-REQUIRED"]) {
+          const www = challengesFromPaymentRequired(lifted["PAYMENT-REQUIRED"], { secretKey: mppKey, realm: mppRealm(req), chainIds: mppNetworks });
+          if (www) lifted["WWW-Authenticate"] = www;
+        }
+        restore();
+        // The middleware may have set a Content-Type for its own body; the
+        // gate answers JSON.
+        try { res.removeHeader("Content-Type"); } catch { /* ignore */ }
+        send402({}, lifted);
+      };
+      // Pass-through never reassigns res.* here: on grant, @x402/express has
+      // already captured these guards as its "original" methods and installed
+      // its own buffering wrappers on top (that is how settle-after-handler
+      // works). Reassigning would clobber those wrappers and the middleware
+      // would wait forever for a res.end it never sees - i.e. serve without
+      // settling. Only the 402 path restores (nothing is wrapped there).
+      const guard = (write) => (...args) => {
+        if (intercepting && !granted && res.statusCode === 402) { finish402(); return res; }
+        return write(...args);
+      };
+      res.status = (code) => { realStatus(code); return res; };
+      res.json = guard(realJson);
+      res.send = guard(realSend);
+      res.end = guard(realEnd);
+      const grant = () => {
+        granted = true;
+        intercepting = false;
+        incr(viaMpp ? "mppPaid" : "x402Paid");
+        res.setHeader("X-Tollbooth-Paid", viaMpp ? "mpp" : "x402");
+        return next();
+      };
+      let out;
+      try {
+        out = x402(req, res, grant);
+      } catch (e) {
+        restore();
+        res.setHeader("X-Tollbooth-Error", "x402-middleware-threw");
+        return send402();
+      }
+      return Promise.resolve(out).catch(() => {
+        if (granted || res.headersSent) return; // the middleware's own settle-failure 402 already went out
+        restore();
+        res.setHeader("X-Tollbooth-Error", "x402-middleware-threw");
+        send402();
+      });
+    };
+    const mppRealm = (r) => {
+      // Protection-space identifier for the challenge: the site's host, or the
+      // configured resource base's host - the same origin the PoW binds.
+      try { if (resourceBaseUrl) return new URL(resourceBaseUrl).host; } catch { /* fall through */ }
+      return String(r.headers?.host || (r.get && r.get("host")) || "tollbooth").toLowerCase();
+    };
+
     // Paid rail: x402 (USDC). Settlement verification is operator-supplied so
     // we reuse the standard, audited x402 stack rather than reinvent it. Reached
     // either directly or after the free rail declined, so it lives in a function
     // the (possibly async) proof-of-work branch can hand control back to.
     const paidRail = () => {
+      if (x402) return middlewareRail();
       const payHeader = req.headers["x-payment"] || req.headers["payment-signature"];
       if (payTo && typeof verifyX402 === "function" && payHeader) {
         // Bound verification time so a slow/hung verifier can't exhaust resources.

package/mpp.js

@@ -0,0 +1,176 @@
+// MPP (Machine Payments Protocol) for the tollbooth - dependency-free codec.
+//
+// MPP is the IETF-track "Payment" HTTP authentication scheme (tempoxyz/mpp,
+// paymentauth.org): the same 402 lifecycle as x402 with standard headers:
+//
+//   challenge   WWW-Authenticate: Payment id="...", realm="...", method="evm",
+//               intent="charge", request="<b64url JSON>", expires="...", opaque="..."
+//   credential  Authorization: Payment <b64url JSON{challenge, payload, source?}>
+//   receipt     Payment-Receipt: <b64url JSON{method, status, reference, timestamp}>
+//
+// MPP's `evm` charge method is the same primitive as x402 `exact` on EVM
+// (an EIP-3009 transferWithAuthorization signed by the buyer), so a tollbooth
+// that already settles x402 through the operator's @x402/express middleware can
+// accept MPP clients as pure header translation - settlement authority stays
+// with the x402 stack, exactly once per purchase:
+//
+//   OUTBOUND  the middleware's own PAYMENT-REQUIRED header (its advertised
+//             `accepts`) is turned into one HMAC-bound MPP challenge per
+//             eligible EVM entry; the verbatim accepts entry rides in the
+//             challenge's opaque slot so inbound is stateless and byte-exact.
+//   INBOUND   an Authorization: Payment credential whose challenge id
+//             HMAC-verifies is re-encoded as a PAYMENT-SIGNATURE header and
+//             handed to the SAME middleware, which verifies + settles it as if
+//             an x402 client had sent it.
+//   RECEIPT   the settled PAYMENT-RESPONSE is mirrored as an MPP Payment-Receipt.
+//
+// No mppx dependency: it pulls in ox/zod and a viem peer, too heavy for a
+// drop-in middleware, and the wire is small. Byte-compatibility with the
+// 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";
+
+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));
+
+// 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");
+}
+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 ---------------
+/**
+ * Decode an x402 v2 PAYMENT-REQUIRED header (base64 JSON envelope) and mint one
+ * HMAC-bound MPP evm/charge challenge per eligible EVM `accepts` entry.
+ * @returns {string|null} WWW-Authenticate value, or null when nothing qualifies.
+ */
+export function challengesFromPaymentRequired(paymentRequiredHeader, { secretKey, realm, chainIds = DEFAULT_MPP_CHAIN_IDS } = {}) {
+  if (!secretKey || !paymentRequiredHeader) return null;
+  let envelope;
+  try { envelope = JSON.parse(unb64std(paymentRequiredHeader)); } catch { return null; }
+  const accepts = Array.isArray(envelope?.accepts) ? envelope.accepts : [];
+  const allowAll = chainIds === "all";
+  const allowed = new Set(allowAll ? [] : (chainIds || []).map(Number));
+  const out = [];
+  for (const a of accepts) {
+    if (!a || a.scheme !== "exact" || typeof a.network !== "string" || !a.network.startsWith("eip155:")) continue;
+    const chainId = Number(a.network.slice("eip155:".length));
+    if (!Number.isInteger(chainId)) continue;
+    if (!allowAll && !allowed.has(chainId)) continue;
+    if (typeof a.amount !== "string" || typeof a.asset !== "string" || typeof a.payTo !== "string") continue;
+    const timeout = Number(a.maxTimeoutSeconds) > 0 ? Number(a.maxTimeoutSeconds) : 300;
+    const c = {
+      realm,
+      method: "evm",
+      intent: "charge",
+      request: encodeRequest({
+        amount: a.amount,
+        currency: a.asset,
+        recipient: a.payTo,
+        methodDetails: { chainId, credentialTypes: ["authorization"], decimals: STABLECOIN_DECIMALS },
+      }),
+      // Native MPP clients sign validBefore = expires; keep it inside the
+      // advertised x402 window so facilitator timeout semantics match.
+      expires: new Date(Date.now() + timeout * 1000).toISOString(),
+      // The verbatim accepts entry (RAW, not normalised - the middleware's
+      // requirement matching deep-equals the full advertised object).
+      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(", "));
+  }
+  if (!out.length) return null;
+  return out.map((p) => `${SCHEME} ${p}`).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; }
+  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;
+  // 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; }
+  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 },
+  }));
+}
+
+// ---- 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);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent402-tollbooth",
-  "version": "0.6.1",
-  "description": "Open-source, self-hostable x402 pay-per-crawl tollbooth: charge AI bots per request (USDC via x402 — or USDG on Robinhood Chain — or free proof-of-work) while humans browse free. Drop-in Express middleware or reverse proxy — no Cloudflare, no Stripe, no signup.",
+  "version": "0.7.0",
+  "description": "Open-source, self-hostable pay-per-crawl tollbooth for x402 AND MPP: 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 - no Cloudflare, no Stripe, no signup.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -16,7 +16,9 @@
     "./dashboard.js": "./dashboard.js",
     "./sinks.js": "./sinks.js",
     "./replay": "./replay.js",
-    "./replay.js": "./replay.js"
+    "./replay.js": "./replay.js",
+    "./mpp": "./mpp.js",
+    "./mpp.js": "./mpp.js"
   },
   "files": [
     "index.js",
@@ -24,6 +26,7 @@
     "worker.js",
     "bots.js",
     "pow.js",
+    "mpp.js",
     "dashboard.js",
     "sinks.js",
     "replay.js",
@@ -65,7 +68,10 @@
     "tollbooth",
     "base",
     "robinhood-chain",
-    "usdg"
+    "usdg",
+    "mpp",
+    "machine-payments-protocol",
+    "payment-auth"
   ],
   "author": "Havok Holdings LLC <mike@agent402.tools> (https://agent402.tools)",
   "license": "MIT",

package/replay.js

@@ -115,12 +115,29 @@ export function redisReplayStore(client, { prefix = "tollbooth:pow:" } = {}) {
   // Detection above is a heuristic; this is the observation. Two claims of a
   // throwaway key must produce a win and then a refusal. Anything else means
   // single-use is not working, and the store refuses rather than pretending.
+  // Tri-state on PURPOSE: null = not yet observed, true = proven, false = proven
+  // BROKEN and permanently refused.
+  //
+  // A verdict of false must keep throwing on EVERY later call, not just the one
+  // that discovered it. Memoising false and returning it as a resolved value
+  // would make the store refuse exactly once and then grant every replay
+  // forever - the precise failure this self-test exists to prevent, reached one
+  // request later. A caller that solves one challenge could then replay that
+  // token for its whole TTL.
+  //
+  // A probe that THROWS (Redis unreachable) leaves the verdict at null so the
+  // next call re-probes: a transient outage must not be remembered as a verdict.
   let nxProven = null;
+  const NX_BROKEN =
+    "redisReplayStore: SET NX is not honoured by this client, so proof-of-work single-use cannot be enforced. " +
+    "The gate refuses rather than granting replays. Pass a client whose SET supports NX, or supply your own { claim(token, expiresAtMs) } store.";
   const proveNx = async () => {
-    if (nxProven !== null) return nxProven;
+    if (nxProven === true) return true;
+    if (nxProven === false) throw new Error(NX_BROKEN);
     const probe = `${prefix}__nxselftest__${Math.random().toString(36).slice(2)}${Date.now()}`;
     const px = 5000;
     const set = (k) => (isIoredis ? client.set(k, "1", "PX", px, "NX") : client.set(k, "1", { NX: true, PX: px }));
+    // Deliberately NOT wrapped: a throw here leaves nxProven null (re-probe).
     const first = await set(probe);
     const second = await set(probe);
     const firstWon = first === "OK" || first === true;
@@ -128,15 +145,16 @@ export function redisReplayStore(client, { prefix = "tollbooth:pow:" } = {}) {
     nxProven = firstWon && secondRefused;
     if (!nxProven) {
       throw new Error(
-        "redisReplayStore: SET NX did not behave as required (first claim won: " + firstWon + ", second refused: " + secondRefused + "). " +
-        "Proof-of-work single-use cannot be enforced against this client, so the gate refuses rather than granting replays."
+        `${NX_BROKEN} (first claim won: ${firstWon}, second refused: ${secondRefused})`
       );
     }
-    return nxProven;
+    return true;
   };
   return {
     claim: async (token, expiresAtMs) => {
-      await proveNx();
+      // Respect the verdict: proveNx throws when unproven, but assert anyway so
+      // no future refactor can turn "unproven" into a silently ignored value.
+      if ((await proveNx()) !== true) throw new Error(NX_BROKEN);
       const key = prefix + token;
       // Floor of 1ms: Redis rejects a non-positive PX. pow.js has already
       // refused anything actually expired, so a tiny window here just means the

package/sinks.js

@@ -16,7 +16,7 @@
 // Want strong consistency on Cloudflare? Back it with a Durable Object that
 // implements the same { incr, snapshot } interface and pass it as `statsSink`.
 
-const KNOWN_FIELDS = ["requests", "freeAllowed", "wouldCharge", "charged", "powSolved", "x402Paid"];
+const KNOWN_FIELDS = ["requests", "freeAllowed", "wouldCharge", "charged", "powSolved", "x402Paid", "mppPaid"];
 const ZERO = () => Object.fromEntries(KNOWN_FIELDS.map((k) => [k, 0]));
 
 // Filter an untrusted JSON blob (KV value or HTTP collector response) to only