agent402-tollbooth 0.4.3 → 0.5.0

package/README.md

@@ -1,19 +1,19 @@
 # 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
+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
 proof-of-work. No Cloudflare, no Stripe, no Merchant-of-Record, no signup.
 
 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/)
 and now its [Monetization Gateway](https://blog.cloudflare.com/monetization-gateway/)
-(launched July 2026 — x402 charging in USDC on Base for anything behind Cloudflare:
+(launched July 2026 - x402 charging in USDC on Base for anything behind Cloudflare:
 pages, APIs, datasets, MCP tools) confirm that pay-per-request is the business model
 of the agentic web. Tollbooth is the **open-source monetization gateway**: the same
 idea, but MIT-licensed and live today, running in
 front of *any* origin (even a Cloudflare Worker), non-custodial (you hold the wallet,
-no signup or Merchant-of-Record), and — the wedge the platform gateways don't offer —
+no signup or Merchant-of-Record), and - the wedge the platform gateways don't offer -
 with a **proof-of-work free tier** so a walletless agent still has a path through.
 Built on the same hardened 402 + proof-of-work machinery as
 [Agent402](https://github.com/MikeyPetrillo/Agent402).
@@ -25,10 +25,10 @@ npx agent402-tollbooth   # then, in the repo:  npm run --prefix tollbooth demo
 ```
 
 ```text
-agent402-tollbooth — live pay-per-crawl demo
+agent402-tollbooth - live pay-per-crawl demo
 
 ① A human opens the page (normal browser)
-   → HTTP 200 FREE  "📄 The Future of Machine Payments — full article text…"
+   → HTTP 200 FREE  "📄 The Future of Machine Payments - full article text…"
    Humans are never charged.
 
 ② An AI crawler hits the same page (ClaudeBot)
@@ -38,9 +38,9 @@ agent402-tollbooth — live pay-per-crawl demo
 
 ③ The crawler has no wallet, so it spends CPU instead
    solved in 0.32s (nonce=100208)
-   → HTTP 200 OK (paid via pow)  "📄 The Future of Machine Payments — full article text…"
+   → HTTP 200 OK (paid via pow)  "📄 The Future of Machine Payments - full article text…"
 
-✓ Pay-per-crawl, end to end — humans free, bots pay (USDC or compute).
+✓ Pay-per-crawl, end to end - humans free, bots pay (USDC or compute).
 ```
 
 ## Install
@@ -81,12 +81,12 @@ The 402 body advertises both rails:
 ```
 
 A crawler that can't (or won't) pay USDC solves the puzzle and retries with
-`X-Pow-Solution: <token>:<nonce>` — sub-second of CPU, single-use, bound to that
+`X-Pow-Solution: <token>:<nonce>` - sub-second of CPU, single-use, bound to that
 exact URL.
 
 ## Use it as a reverse proxy (any language/framework)
 
-Point it at your existing site — no code changes there:
+Point it at your existing site - no code changes there:
 
 ```bash
 TOLLBOOTH_UPSTREAM=https://your-site.com \
@@ -97,17 +97,17 @@ npx agent402-tollbooth          # listens on :4021, proxies humans free, charges
 ## Run on the edge (Cloudflare Workers, Next.js, Deno, Bun)
 
 The same gate is also built on the Web Crypto + Fetch APIs (`edge.js`), so it runs
-anywhere — no Node required. The gate returns a `402 Response` when the client
+anywhere - no Node required. The gate returns a `402 Response` when the client
 must pay, or `null` to let it through.
 
 **Ready-to-deploy templates** (copy a folder, don't assemble from docs):
 
-- **Cloudflare Workers** → [`deploy/cloudflare/`](deploy/cloudflare/) — a ready
+- **Cloudflare Workers** → [`deploy/cloudflare/`](deploy/cloudflare/) - a ready
   `wrangler.toml` + a 3-step deploy guide (the open pay-per-crawl, on the
   incumbent's own platform).
-- **Next.js / Vercel** → [`deploy/nextjs/`](deploy/nextjs/) — a drop-in
+- **Next.js / Vercel** → [`deploy/nextjs/`](deploy/nextjs/) - a drop-in
   `middleware.js` + a 3-step deploy guide.
-- **Docker** → [`deploy/docker/`](deploy/docker/) — a `Dockerfile` +
+- **Docker** → [`deploy/docker/`](deploy/docker/) - a `Dockerfile` +
   `docker-compose.yml` to run the reverse proxy in front of any site with
   `docker compose up -d` (includes the live `/__tollbooth` dashboard).
 
@@ -141,29 +141,38 @@ 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).
+> (e.g. a Cloudflare KV wrapper - the Worker entry wires this for you).
 
 ## Accepting USDC (x402)
 
 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
+set `payTo` and supply `verifyX402` - wire it to the standard, audited x402
 server stack (`@x402/express` / your facilitator) rather than reinventing
 settlement:
 
 ```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",
-  // Reuse the standard middleware to verify the X-PAYMENT header:
-  verifyX402: (req) => new Promise((resolve) =>
-    x402(req, { setHeader() {}, status() { return this; }, json() { resolve(false); } }, () => resolve(true))),
+  // 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 }),
 }));
 ```
 
-(PoW is checked first, so an agent without a wallet always has a free path.)
+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.)
 
 ## Configuration
 
@@ -186,10 +195,37 @@ app.use(createTollbooth({
 | `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)`. |
 
-Environment variables: `TOLLBOOTH_UPSTREAM`, `TOLLBOOTH_PAYTO`, `TOLLBOOTH_PRICE`,
-`TOLLBOOTH_NETWORK`, `TOLLBOOTH_POW_BITS`, `TOLLBOOTH_MODE`, `TOLLBOOTH_ADAPTIVE`,
-`TOLLBOOTH_MAX_POW_BITS`, `TOLLBOOTH_ADAPTIVE_PER_BIT`, `TOLLBOOTH_SECRET`,
-`TOLLBOOTH_OBSERVE`, `TOLLBOOTH_STATS_TOKEN`, `TOLLBOOTH_STATS_BUCKET`, `PORT`.
+### Environment variables
+
+Read by the bundled proxy / Express entry point (`index.js`):
+
+| env | default | meaning |
+|---|---|---|
+| `TOLLBOOTH_UPSTREAM` | – | Origin the built-in reverse proxy forwards to |
+| `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_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` |
+| `TOLLBOOTH_ADAPTIVE` | `false` | Raise PoW difficulty as charged-request load climbs |
+| `TOLLBOOTH_ADAPTIVE_PER_BIT` | `300` | +1 difficulty bit per N charged requests/min |
+| `TOLLBOOTH_SECRET` | random | HMAC secret binding PoW challenges (set it to survive restarts / run multiple instances) |
+| `TOLLBOOTH_RESOURCE_BASE` | `TOLLBOOTH_UPSTREAM` | Absolute base used for the `resource` field / PoW binding |
+| `TOLLBOOTH_VERIFY_TIMEOUT_MS` | `10000` | Abort an x402 settlement check after this long |
+| `TOLLBOOTH_OBSERVE` | `false` | Observe-only: classify and count, never 402 |
+| `TOLLBOOTH_ADMIN_TOKEN` | – | Token gating the `/__tollbooth` dashboard **and** `/__tollbooth/stats`. Unset logs a warning and leaves the dashboard publicly reachable (aggregate counts only) |
+| `TOLLBOOTH_STATS_TOKEN` | – | Legacy token gating `/__tollbooth/stats` only |
+| `PORT` | `4021` | Listen port |
+
+Cloudflare Worker only (`worker.js`, bound in `wrangler.toml`):
+
+| binding / env | meaning |
+|---|---|
+| `TOLLBOOTH_REPLAY` | Durable Object binding giving **atomic**, strict single-use PoW replay protection across isolates. Required in enforcing mode |
+| `TOLLBOOTH_ALLOW_NON_ATOMIC_REPLAY` | `"true"` explicitly accepts non-atomic (KV or per-isolate) replay protection instead of a Durable Object. Without it, enforcing mode refuses to start |
+| `TOLLBOOTH_KV` | KV namespace for durable stats |
+| `TOLLBOOTH_STATS_BUCKET` | Stats bucket name within `TOLLBOOTH_KV` (default `"default"`) |
 
 ## How it decides who pays
 
@@ -199,25 +235,25 @@ Google-Extended, Amazonbot, …). Classic search indexers (Googlebot, Bingbot) a
 intentionally **not** charged so your SEO indexing stays free.
 
 **Don't want to play whack-a-mole with bot detection?** That's the point of the
-other modes — you stop trying to *identify* bots and instead make access *cost
+other modes - you stop trying to *identify* bots and instead make access *cost
 something*:
 - `mode: "all"` charges every client (except a `free()` match). A "more
-  sophisticated" bot gains nothing by disguising itself — everyone pays or solves
+  sophisticated" bot gains nothing by disguising itself - everyone pays or solves
   a proof-of-work.
 - `mode: "strict"` charges anything that isn't a real-browser request (browser-like
   UA **and** an HTML `Accept`), letting genuine human page-loads through free.
-  Heads-up: that's a heuristic, not a security boundary — a bot that sets
+  Heads-up: that's a heuristic, not a security boundary - a bot that sets
   `User-Agent: Mozilla/5.0 …` + `Accept: text/html` gets the same free pass a
   human gets. Use `mode: "all"` (or your own `charge:` predicate) for hard
   guarantees.
 - `adaptive: true` makes proof-of-work **harder as load climbs**, so a high-volume
-  scraper pays escalating CPU per request regardless of how it looks — detection is
+  scraper pays escalating CPU per request regardless of how it looks - detection is
   cat-and-mouse, economics isn't.
 
 ## Observe before charging
 
 Don't want to flip a meter on cold? **Run the gate in observe-only mode for a
-week first** — every request is still classified (bot vs. human) and counted,
+week first** - every request is still classified (bot vs. human) and counted,
 but nothing ever gets a 402:
 
 ```js
@@ -226,8 +262,8 @@ app.use(createTollbooth({ observe: true })); // or: TOLLBOOTH_OBSERVE=true
 
 On the edge / Cloudflare Worker / Next.js: set `TOLLBOOTH_OBSERVE=true` in env.
 
-The dashboard grows a **"Would charge"** counter so you can show your team —
-or your client — exactly how much of their traffic is AI bots **before** you
+The dashboard grows a **"Would charge"** counter so you can show your team -
+or your client - exactly how much of their traffic is AI bots **before** you
 start returning 402s. Removing the flag flips on enforcement with no other
 changes. Bots see a `X-Tollbooth-Observed: would-charge` header in observe mode
 (handy for log filtering); humans see nothing.
@@ -240,12 +276,12 @@ The middleware keeps aggregate counters (no per-request data):
 - `gate.flush()` → flush any buffered deltas to the durable sink (call inside `ctx.waitUntil` on edge runtimes).
 
 The reverse-proxy CLI exposes them as JSON at **`/__tollbooth/stats`** and as a
-live **dashboard at `/__tollbooth`** — requests, how many were charged,
+live **dashboard at `/__tollbooth`** - requests, how many were charged,
 proof-of-work solves, USDC collected, and what share of your traffic is bots.
 
 ## Durable stats (survive restart, aggregate across instances)
 
-By default, stats live in process memory — fine for single-instance Node,
+By default, stats live in process memory - fine for single-instance Node,
 useless across multiple replicas or on the edge. Pass a `statsSink` to make
 them survive:
 
@@ -272,7 +308,7 @@ app.use(createTollbooth({
 }));
 ```
 
-Sink interface (build your own — e.g. a Cloudflare Durable Object for strict
+Sink interface (build your own - e.g. a Cloudflare Durable Object for strict
 consistency):
 
 ```ts
@@ -292,7 +328,7 @@ JSON endpoint, BEFORE the gate so they're never paywalled:
 - **`/__tollbooth/stats`** → JSON snapshot (gate with `TOLLBOOTH_STATS_TOKEN` for bearer-auth)
 
 With a `TOLLBOOTH_KV` namespace bound, the stats aggregate across all isolates
-of all Cloudflare colos serving the Worker — one consistent view.
+of all Cloudflare colos serving the Worker - one consistent view.
 
 On Next.js / Vercel Edge, middleware can't mount dashboards itself (it'd gate
 them), so a companion **route handler** at `app/__tollbooth/stats/route.js`
@@ -303,7 +339,7 @@ as drop-in copyable snippets.
 ## Production checklist (read this)
 
 - **Set a stable `TOLLBOOTH_SECRET`.** Required for any multi-process/clustered
-  Node deploy and for all edge deploys — without it, proof-of-work tokens use a
+  Node deploy and for all edge deploys - without it, proof-of-work tokens use a
   random per-process secret and are rejected across restarts/workers/isolates.
 - **For serverless/edge, supply a durable replay `store`** (e.g. bind a Cloudflare
   KV namespace as `TOLLBOOTH_KV`). The in-memory default is per-isolate, so a
@@ -312,7 +348,7 @@ as drop-in copyable snippets.
 - **The reverse proxy pins the host** to your configured upstream (a client can't
   redirect it elsewhere) and **strips client-forged trust/forwarding headers**
   (`X-Tollbooth-Paid`, `X-Forwarded-Host`, etc.) before forwarding.
-- **UA matching is the default, not a security boundary** — a bot can forge a
+- **UA matching is the default, not a security boundary** - a bot can forge a
   human UA to get the *same free access a human gets* (it gains nothing more). To
   stop relying on detection entirely, use `mode: "all"` / `mode: "strict"`, and
   turn on `adaptive` so high-volume abuse pays escalating proof-of-work.
@@ -320,7 +356,7 @@ as drop-in copyable snippets.
 ## Notes
 
 - Proof-of-work tokens are HMAC-signed, expiry-checked, single-use, and bound to
-  the exact resource (path + query, dots and all) — a solution for one URL can't
+  the exact resource (path + query, dots and all) - a solution for one URL can't
   be replayed or reused on another.
 - MIT licensed. Part of [Agent402](https://github.com/MikeyPetrillo/Agent402).
 

package/edge.js

@@ -101,7 +101,14 @@ export function createEdgePow({ secret, difficulty = 18, ttlMs = 5 * 60 * 1000,
     if (leadingZeroBits(h) < Number(diffStr)) return { ok: false, reason: "insufficient work" };
     // Atomically claim single-use only AFTER the work is validated, so an invalid
     // attempt never consumes the token and concurrent dupes can't both pass.
-    if (!(await used.claim(token, Number(expStr)))) return { ok: false, reason: "already used" };
+    // F05: FAIL CLOSED — if the claim store is unavailable, deny rather than let
+    // the exception propagate (or, worse, grant). Strict single-use needs an
+    // atomic store (Durable Object); see worker.js durableObjectStore + the
+    // wrangler template. A get-then-put KV store is best-effort only.
+    let claimed;
+    try { claimed = await used.claim(token, Number(expStr)); }
+    catch { return { ok: false, reason: "replay store unavailable" }; }
+    if (!claimed) return { ok: false, reason: "already used" };
     return { ok: true };
   }
 
@@ -177,11 +184,19 @@ export function createEdgeTollbooth(config = {}) {
     if (!shouldCharge(request)) { incr("freeAllowed"); return null; }
     if (observe) { incr("wouldCharge"); return null; }
     const u = new URL(request.url);
-    const resource = (resourceBaseUrl ? resourceBaseUrl.replace(/\/$/, "") : "") + u.pathname + u.search;
+    // F18: bind the canonical ORIGIN, not just path+query — otherwise a proof
+    // for /x transfers to any other site sharing the secret. On the edge the
+    // request URL already carries the real origin; prefer an explicit
+    // resourceBaseUrl when configured.
+    const origin = resourceBaseUrl ? resourceBaseUrl.replace(/\/$/, "") : u.origin;
+    const resource = origin + u.pathname + u.search;
+    // Additionally bind the HTTP METHOD in the PoW challenge (x402 `resource`
+    // stays a plain URL for wire compatibility).
+    const powResource = `${request.method || "GET"} ${resource}`;
 
     const sol = request.headers.get("x-pow-solution");
     if (powEngine && sol) {
-      const r = await powEngine.verify(sol, resource);
+      const r = await powEngine.verify(sol, powResource);
       if (r.ok) { incr("powSolved"); return null; }
     }
 
@@ -191,7 +206,7 @@ export function createEdgeTollbooth(config = {}) {
       message,
       accepts: payTo ? [{ scheme: "exact", network, maxAmountRequired: String(price), asset, payTo, resource }] : [],
     };
-    if (powEngine) body.proofOfWork = await powEngine.challenge(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" },

package/index.js

@@ -23,6 +23,53 @@ export { createPow, leadingZeroBits } from "./pow.js";
 export { memorySink, kvStatsSink, httpStatsSink } from "./sinks.js";
 
 const VERIFY_TIMEOUT_MS = Number(process.env.TOLLBOOTH_VERIFY_TIMEOUT_MS) || 10_000;
+
+// P1.5 / FR4-10: a first-party `verifyX402` built from a standard @x402/express
+// payment middleware, that OWNS timeout + cancellation. The gate calls
+// verifyX402(req, opts) and puts an AbortSignal on `opts.signal` (aborted when
+// the gate's own verify timeout fires); this wrapper honors it — once the signal
+// aborts (or its own optional backstop timeout fires) it settles the verify
+// promise immediately and reports NOT-verified, so a slow middleware can't leave
+// 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.
+//
+// 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.
+export function x402VerifierFromExpress(paymentMiddleware, { timeoutMs } = {}) {
+  if (typeof paymentMiddleware !== "function") {
+    throw new TypeError("x402VerifierFromExpress: paymentMiddleware must be a function");
+  }
+  return (req, opts = {}) => new Promise((resolve, reject) => {
+    const signal = opts?.signal;
+    let done = false;
+    let timer = null;
+    const finish = (fn, v) => {
+      if (done) return;
+      done = true;
+      if (timer) clearTimeout(timer);
+      signal?.removeEventListener?.("abort", onAbort);
+      fn(v);
+    };
+    const onAbort = () => finish(resolve, false); // gate timed out → treat as not verified
+    if (signal?.aborted) return finish(resolve, false);
+    signal?.addEventListener?.("abort", onAbort, { once: true });
+    if (timeoutMs > 0) timer = setTimeout(() => finish(resolve, false), timeoutMs);
+    // Minimal response shim: the middleware calls next() to GRANT, or writes a
+    // 402 via status/json/send/end to DENY.
+    const res = {
+      setHeader() { return this; }, getHeader() {}, removeHeader() { return this; }, getHeaders() { return {}; },
+      status() { return this; }, json() { finish(resolve, false); return this; },
+      send() { finish(resolve, false); return this; }, end() { finish(resolve, false); return this; },
+      writeHead() { return this; }, write() { return true; }, flushHeaders() {},
+    };
+    try {
+      Promise.resolve(paymentMiddleware(req, res, () => finish(resolve, true))).catch((e) => finish(reject, e));
+    } catch (e) { finish(reject, e); }
+  });
+}
 // Headers a client must never be able to forge through the proxy: the gate's own
 // trust signals and forwarding/hop-by-hop headers.
 const STRIP_INBOUND = new Set([
@@ -139,7 +186,15 @@ export function createTollbooth(config = {}) {
     const raw = req.originalUrl || req.url || "/";
     let pathAndSearch = raw;
     try { const u = new URL(raw, "http://internal.invalid"); pathAndSearch = u.pathname + u.search; } catch { /* keep raw */ }
-    return (resourceBaseUrl ? resourceBaseUrl.replace(/\/$/, "") : "") + pathAndSearch;
+    // F18: bind the canonical ORIGIN, not just path+query, so a proof minted for
+    // /x on site A cannot be replayed on site B. Prefer a configured
+    // resourceBaseUrl; otherwise derive the origin from the request host (same
+    // site => same origin; a different host => a different resource). Reusing one
+    // TOLLBOOTH_SECRET across sites should ALSO use a unique secret per site.
+    const origin = resourceBaseUrl
+      ? resourceBaseUrl.replace(/\/$/, "")
+      : `${req.protocol || "https"}://${String(req.headers?.host || (req.get && req.get("host")) || "").toLowerCase()}`;
+    return origin + pathAndSearch;
   };
 
   function tollbooth(req, res, next) {
@@ -149,6 +204,10 @@ export function createTollbooth(config = {}) {
     // measure bot traffic on a live site before turning on enforcement.
     if (observe) { incr("wouldCharge"); res.setHeader("X-Tollbooth-Observed", "would-charge"); return next(); }
     const resource = resourceOf(req);
+    // F18: the PoW challenge additionally binds the HTTP METHOD, so a proof
+    // solved for GET /x can't be replayed against POST /x. The x402 `resource`
+    // stays a plain URL (below) for wire compatibility.
+    const powResource = `${(req.method || "GET").toUpperCase()} ${resource}`;
 
     const send402 = (extra = {}) => {
       incr("charged");
@@ -161,14 +220,14 @@ export function createTollbooth(config = {}) {
           : [],
         ...extra,
       };
-      if (powEngine) body.proofOfWork = powEngine.challenge(resource, difficultyNow());
+      if (powEngine) body.proofOfWork = powEngine.challenge(powResource, difficultyNow());
       res.status(402).json(body);
     };
 
     // Free rail: proof-of-work.
     const powHeader = req.headers["x-pow-solution"];
     if (powEngine && powHeader) {
-      const r = powEngine.verify(powHeader, resource);
+      const r = powEngine.verify(powHeader, powResource);
       if (r.ok) { incr("powSolved"); res.setHeader("X-Tollbooth-Paid", "pow"); return next(); }
       res.setHeader("X-Pow-Error", r.reason);
     }
@@ -178,13 +237,19 @@ export function createTollbooth(config = {}) {
     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.
-      const timeout = new Promise((resolve) => setTimeout(() => resolve(false), VERIFY_TIMEOUT_MS));
-      return Promise.race([Promise.resolve(verifyX402(req, { price, network, asset, payTo, resource })), timeout])
+      // F19: pass an AbortSignal and ABORT it on timeout, so a slow verifier that
+      // also SETTLES cannot move money after we have already returned 402 (a
+      // charged denial). A pure-verification callback may ignore the signal; a
+      // settling one MUST cancel/drain in-flight work on it before returning.
+      const ac = new AbortController();
+      const timeout = new Promise((resolve) => setTimeout(() => { ac.abort(); resolve(false); }, VERIFY_TIMEOUT_MS));
+      return Promise.race([Promise.resolve(verifyX402(req, { price, network, asset, payTo, resource, signal: ac.signal })), timeout])
         .then((ok) => {
+          ac.abort(); // verification resolved: cancel anything still in flight
           if (ok) { incr("x402Paid"); res.setHeader("X-Tollbooth-Paid", "x402"); return next(); }
           send402();
         })
-        .catch(() => { res.setHeader("X-Tollbooth-Error", "x402-verify-failed"); send402(); });
+        .catch(() => { ac.abort(); res.setHeader("X-Tollbooth-Error", "x402-verify-failed"); send402(); });
     }
 
     return send402();
@@ -262,7 +327,13 @@ async function startCli() {
   if (!_secret) {
     console.warn("⚠ TOLLBOOTH_SECRET not set — proof-of-work tokens use a random per-process secret: they won't survive a restart and will be rejected across multiple workers/instances. Set a stable TOLLBOOTH_SECRET in production.");
   } else if (/^change-me/i.test(_secret) || _secret === "change-me-to-a-long-random-string") {
-    console.warn("⚠ TOLLBOOTH_SECRET is the public placeholder from the deploy template — it's readable by anyone, so proof-of-work tokens can be FORGED to bypass your gate for free. Set a real random secret: `openssl rand -hex 32`.");
+    // FATAL, not a warning. The placeholder is published in our own deploy
+    // template, so anyone can read it, mint a token with difficulty 0 and walk
+    // through the gate without doing any work - the operator believes they are
+    // charging while everything is free. A warning scrolls past in a container
+    // log; refusing to start cannot be missed, and it fails CLOSED.
+    console.error("✖ TOLLBOOTH_SECRET is the public placeholder from the deploy template. It is readable by anyone, so proof-of-work tokens can be forged and your gate bypassed for free. Refusing to start. Generate a real secret: openssl rand -hex 32");
+    process.exit(1);
   }
   const { default: express } = await import("express");
   const app = express();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-tollbooth",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "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.",
   "type": "module",
   "main": "index.js",

package/pow.js

@@ -73,8 +73,15 @@ export function createPow({
     if (res !== resource) return { ok: false, reason: "wrong resource" };
     if (Date.now() > Number(expStr)) return { ok: false, reason: "expired" };
     if (used.has(token)) return { ok: false, reason: "already used" };
+    // Defence in depth: the difficulty rides INSIDE the signed token, so a
+    // forged or downgraded token could claim difficulty 0 and pass with no work
+    // at all. Hold every solution to the configured difficulty as well, so a
+    // leaked or placeholder secret still costs a real solve instead of handing
+    // over free passage.
+    const claimed = Number(diffStr);
+    if (!Number.isFinite(claimed) || claimed < difficulty) return { ok: false, reason: "difficulty below policy" };
     const hash = createHash("sha256").update(`${chal}:${nonce}`).digest();
-    if (leadingZeroBits(hash) < Number(diffStr)) return { ok: false, reason: "insufficient work" };
+    if (leadingZeroBits(hash) < claimed) return { ok: false, reason: "insufficient work" };
     used.set(token, Number(expStr));
     return { ok: true };
   }

package/worker.js

@@ -28,9 +28,10 @@ function constEq(a, b) {
 }
 
 const kvStore = (kv) => ({
-  // Best-effort atomic claim. KV has no native compare-and-set, so this is
-  // get-then-put (eventually consistent); for strict single-use, back it with a
-  // Durable Object. Returns true only the first time a token is seen.
+  // Best-effort claim. KV has no native compare-and-set, so this is get-then-put
+  // (eventually consistent) — concurrent dupes across isolates/locations can
+  // both observe "unseen" and both pass. For STRICT single-use use the Durable
+  // Object store below. Returns true only the first time a token is seen.
   claim: async (k, expMs) => {
     if ((await kv.get(k)) != null) return false;
     await kv.put(k, "1", { expiration: Math.ceil(expMs / 1000) });
@@ -38,15 +39,67 @@ const kvStore = (kv) => ({
   },
 });
 
+// F05: strict single-use replay claim via a Durable Object. A DO instance is
+// single-threaded — every request addressed to one DO id is serialized — so the
+// get-then-put INSIDE it is ATOMIC across all isolates and locations (KV is
+// eventually consistent and has no compare-and-set). Each token is routed to its
+// own DO id, so claims only ever contend on the exact token they concern.
+export class TollboothReplay {
+  constructor(state) { this.state = state; }
+  async fetch(request) {
+    let expMs = 0;
+    try { expMs = Number((await request.json()).expMs) || 0; } catch { /* */ }
+    const already = await this.state.storage.get("claimed");
+    if (already != null) return Response.json({ granted: false });
+    await this.state.storage.put("claimed", 1);
+    // Auto-expire the DO storage at the token's expiry — the token is worthless
+    // after that, so the claim record can be dropped and storage stays bounded.
+    if (expMs > Date.now()) { try { await this.state.storage.setAlarm(expMs); } catch { /* */ } }
+    return Response.json({ granted: true });
+  }
+  async alarm() { try { await this.state.storage.deleteAll(); } catch { /* */ } }
+}
+
+export const durableObjectStore = (namespace) => ({
+  claim: async (k, expMs) => {
+    const stub = namespace.get(namespace.idFromName(k));
+    const resp = await stub.fetch("https://tollbooth-replay/claim", { method: "POST", body: JSON.stringify({ expMs }) });
+    const { granted } = await resp.json();
+    return granted === true;
+  },
+});
+
 export default {
   async fetch(request, env, ctx) {
     if (!env.TOLLBOOTH_SECRET) {
       return new Response("Tollbooth misconfigured: set TOLLBOOTH_SECRET (wrangler secret put TOLLBOOTH_SECRET)", { status: 500 });
     }
-    if (!env.TOLLBOOTH_KV) {
-      // No durable store → replay protection is per-isolate only; a solved token
-      // can be reused across isolates within its TTL. Bind a KV namespace for prod.
-      console.warn("agent402-tollbooth: no TOLLBOOTH_KV bound — proof-of-work replay protection is per-isolate only. Bind a KV namespace for production.");
+    // F05: pick the replay store, strongest first. A Durable Object
+    // (TOLLBOOTH_REPLAY) gives ATOMIC, strict single-use across isolates and
+    // locations. KV is a best-effort fallback (eventually consistent; concurrent
+    // dupes can both pass). With neither, protection is per-isolate only.
+    const enforcing = env.TOLLBOOTH_OBSERVE !== "true";
+    // FR4-04: FAIL CLOSED in enforcing mode without an ATOMIC replay store. A
+    // Durable Object (TOLLBOOTH_REPLAY) gives strict single-use across isolates
+    // and locations. KV is eventually consistent (get-then-put, NOT atomic), so
+    // concurrent duplicate PoW solutions can both pass — a warning does not
+    // protect a production deployment. Refuse to enforce on a non-atomic (or
+    // absent) store unless the operator sets an explicit, loud insecure override.
+    const allowNonAtomic = env.TOLLBOOTH_ALLOW_NON_ATOMIC_REPLAY === "true";
+    if (enforcing && !env.TOLLBOOTH_REPLAY && !allowNonAtomic) {
+      return new Response(
+        "Tollbooth misconfigured: enforcing mode requires an ATOMIC replay store. Bind a Durable Object as TOLLBOOTH_REPLAY (see deploy/cloudflare/wrangler.toml), run in observe mode (TOLLBOOTH_OBSERVE=true), or accept non-atomic replay explicitly with TOLLBOOTH_ALLOW_NON_ATOMIC_REPLAY=true.",
+        { status: 500 }
+      );
+    }
+    let replayStore;
+    if (env.TOLLBOOTH_REPLAY) {
+      replayStore = durableObjectStore(env.TOLLBOOTH_REPLAY);
+    } else if (env.TOLLBOOTH_KV) {
+      replayStore = kvStore(env.TOLLBOOTH_KV);
+      if (enforcing) console.warn("agent402-tollbooth: ENFORCING on eventually-consistent KV via explicit TOLLBOOTH_ALLOW_NON_ATOMIC_REPLAY override (get-then-put is NOT atomic — concurrent duplicate solutions across isolates/locations can both pass). Bind a Durable Object as TOLLBOOTH_REPLAY for strict single-use.");
+    } else if (enforcing) {
+      console.warn("agent402-tollbooth: ENFORCING with NO replay store via explicit TOLLBOOTH_ALLOW_NON_ATOMIC_REPLAY override — proof-of-work replay protection is per-isolate only. Bind a Durable Object for production.");
     }
     // Durable stats live in KV if a namespace is bound. Without it, the dashboard
     // is per-isolate (dies on cold start) — fine for dev, useless for prod.
@@ -60,7 +113,7 @@ export default {
       network: env.TOLLBOOTH_NETWORK || "base",
       asset: env.TOLLBOOTH_ASSET || "USDC",
       powDifficulty: env.TOLLBOOTH_POW_BITS ? Number(env.TOLLBOOTH_POW_BITS) : undefined,
-      store: env.TOLLBOOTH_KV ? kvStore(env.TOLLBOOTH_KV) : undefined,
+      store: replayStore,
       observe: env.TOLLBOOTH_OBSERVE === "true",
       statsSink,
     });