agent402-tollbooth 0.4.3 → 0.6.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
 
@@ -185,11 +194,40 @@ app.use(createTollbooth({
 | `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)`. |
+| `replayStore` | **this process's memory** | Shared single-use record for solved proof-of-work tokens. Required for multi-worker / multi-instance / serverless. Built-ins: `sqliteReplayStore(db)`, `redisReplayStore(client)`. See below. |
 
-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_REPLAY_SQLITE` | – | Path to a SQLite file every process shares as the single-use PoW record. Set it whenever more than one process serves the same `TOLLBOOTH_SECRET`. Needs Node 22.5+ (built-in `node:sqlite`) or an installed `better-sqlite3`; refuses to start if neither can open the file |
+| `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 +237,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 +264,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 +278,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 +310,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
@@ -283,6 +321,88 @@ type StatsSink = {
 };
 ```
 
+## Single-use proof-of-work across workers and instances (`replayStore`)
+
+**The default single-use record lives in ONE PROCESS'S MEMORY.** Read that
+sentence twice if you run more than one process, because the two settings
+interact:
+
+- A stable `TOLLBOOTH_SECRET` is what makes a token minted by worker 1 verify on
+  worker 2. Without it, multi-process deploys reject every solution.
+- With it, and with no shared replay store, each process keeps its own
+  "already used" list. One 18-bit solve is then redeemable **once per process**
+  inside the token's 5-minute TTL, and again after a worker recycles. Four
+  workers means four requests for one solve.
+
+Pass a `replayStore` and every process claims against the same record:
+
+```js
+// Several Node workers on one host (cluster, pm2, one container with N processes).
+import Database from "better-sqlite3";                 // or node:sqlite on Node 22.5+
+import { createTollbooth, sqliteReplayStore } from "agent402-tollbooth";
+
+const db = new Database("/var/lib/tollbooth/replay.db");
+db.pragma("journal_mode = WAL");     // concurrent writers
+db.pragma("busy_timeout = 5000");    // wait for the write lock instead of throwing
+
+app.use(createTollbooth({ replayStore: sqliteReplayStore(db) }));
+```
+
+```js
+// Instances across hosts, or a serverless runtime that can reach Redis.
+import { createClient } from "redis";
+import { createTollbooth, redisReplayStore } from "agent402-tollbooth";
+
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+app.use(createTollbooth({ replayStore: redisReplayStore(redis) }));
+```
+
+`redisReplayStore` also accepts an ioredis client (their `SET` signatures differ;
+the factory detects which one it was handed). Neither driver is a dependency of
+this package: you pass a client you already opened, so the tollbooth still
+installs with nothing but Express.
+
+The bundled reverse proxy takes the SQLite path from the environment, so the CLI
+needs no code:
+
+```bash
+TOLLBOOTH_SECRET=$(openssl rand -hex 32) \
+TOLLBOOTH_REPLAY_SQLITE=/var/lib/tollbooth/replay.db \
+TOLLBOOTH_UPSTREAM=https://your-origin.example \
+npx agent402-tollbooth
+```
+
+Store interface (build your own against Postgres, DynamoDB, a Durable Object -
+this is the same contract the edge gate's `store` option uses, so an
+implementation ports between the two unchanged):
+
+```ts
+type ReplayStore = {
+  // MUST be atomic: true only the first time this token is seen, false after.
+  claim(token: string, expiresAtMs: number): boolean | Promise<boolean>;
+};
+```
+
+Three things worth knowing before you write one:
+
+- **It may be async.** `claim` can return a promise; `verify()` then returns a
+  promise too, and the gate awaits it. A synchronous store keeps the gate
+  synchronous, so existing single-process deploys are unaffected.
+- **A throw is a refusal, not a pass.** If `claim` throws or rejects, the gate
+  answers `402` with `X-Pow-Error: replay store unavailable`. Let your store
+  throw when its backend is unreachable - guessing "probably unused" would hand
+  out exactly the free passes the store exists to stop.
+- **Non-atomic is not enough.** A separate "read, then write" pair lets two
+  concurrent redemptions of one token both see "unseen" and both pass. SQLite's
+  `INSERT OR IGNORE` on a primary key and Redis `SET NX` are atomic; a plain
+  eventually-consistent key/value `get` + `put` is not.
+
+Scope note: the SQLite store's guarantee is per **database file**, which covers
+many processes sharing a disk. It does not cover hosts sharing a network
+filesystem (SQLite locking is not reliable there) - use Redis or Postgres for
+that shape.
+
 ## Edge analytics (Cloudflare Worker / Next.js)
 
 The Cloudflare Worker entry (`worker.js`) auto-mounts both the dashboard and
@@ -292,7 +412,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,16 +423,23 @@ 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
-  solved token could be reused across isolates within its TTL. The Worker entry
-  warns when no KV is bound.
+- **If more than one process shares that secret, supply a `replayStore`.** The
+  default single-use record is per process, so a stable secret plus no shared
+  store means one solve buys one free request per worker within its TTL. Node:
+  `replayStore: sqliteReplayStore(db)` / `redisReplayStore(client)`, or
+  `TOLLBOOTH_REPLAY_SQLITE=<path>` for the bundled proxy
+  ([details](#single-use-proof-of-work-across-workers-and-instances-replaystore)).
+- **For serverless/edge, supply a durable replay `store`** (bind a Durable Object
+  as `TOLLBOOTH_REPLAY` for atomic claims; KV is eventually consistent and the
+  Worker entry refuses to enforce on it without an explicit override). The
+  in-memory default is per-isolate, so a solved token could otherwise be reused
+  across isolates within its TTL.
 - **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,8 +447,9 @@ 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
-  be replayed or reused on another.
+  the exact resource (path + query, dots and all) - a solution for one URL can't
+  be replayed or reused on another. Single-use is recorded **per process** unless
+  you pass a `replayStore`.
 - MIT licensed. Part of [Agent402](https://github.com/MikeyPetrillo/Agent402).
 
 ## Charge in USDG on Robinhood Chain

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

@@ -21,8 +21,56 @@ import { memorySink } from "./sinks.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";
 
 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([
@@ -40,6 +88,8 @@ const STRIP_INBOUND = new Set([
  * @param {string} [config.asset="USDC"]        stablecoin symbol in the quote (USDG on Robinhood Chain)
  * @param {boolean} [config.pow=true]          enable the free proof-of-work rail
  * @param {number} [config.powDifficulty]      PoW difficulty in leading zero bits
+ * @param {object} [config.replayStore]        shared single-use PoW backend, `{ claim(token, expiresAtMs) => boolean|Promise<boolean> }`.
+ *                                             Default is THIS PROCESS'S memory; required for multi-worker / multi-instance / serverless. See replay.js.
  * @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)
@@ -61,6 +111,12 @@ export function createTollbooth(config = {}) {
     pow = true,
     powDifficulty,
     powSecret,
+    // Shared single-use record for solved proof-of-work tokens. Unset means
+    // per-process memory, which is only single-use within ONE process: a stable
+    // TOLLBOOTH_SECRET (needed so tokens verify across workers at all) then makes
+    // one solve redeemable once per worker inside the token TTL. Pass a store
+    // from replay.js for any deploy with more than one process.
+    replayStore,
     botUserAgents = AI_BOTS,
     // Who pays. Default "bots" = the original behavior (charge AI crawler UAs).
     //  "all"    — charge every client except a `free()` match (UA detection is
@@ -90,7 +146,7 @@ export function createTollbooth(config = {}) {
   } = config;
 
   const isBot = makeBotMatcher(botUserAgents);
-  const powEngine = pow ? createPow({ difficulty: powDifficulty, secret: powSecret }) : null;
+  const powEngine = pow ? createPow({ difficulty: powDifficulty, secret: powSecret, replayStore }) : null;
 
   // Passive analytics — never affects request handling, just counts what happens.
   // `mem` is an always-on in-process mirror so `.stats()` stays synchronous for
@@ -139,7 +195,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 +213,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,33 +229,60 @@ 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);
     };
 
+    // 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 = () => {
+      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.
+        // 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(() => { ac.abort(); res.setHeader("X-Tollbooth-Error", "x402-verify-failed"); send402(); });
+      }
+
+      return send402();
+    };
+
     // Free rail: proof-of-work.
     const powHeader = req.headers["x-pow-solution"];
     if (powEngine && powHeader) {
-      const r = powEngine.verify(powHeader, resource);
-      if (r.ok) { incr("powSolved"); res.setHeader("X-Tollbooth-Paid", "pow"); return next(); }
-      res.setHeader("X-Pow-Error", r.reason);
-    }
-
-    // Paid rail: x402 (USDC). Settlement verification is operator-supplied so
-    // we reuse the standard, audited x402 stack rather than reinvent it.
-    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])
-        .then((ok) => {
-          if (ok) { incr("x402Paid"); res.setHeader("X-Tollbooth-Paid", "x402"); return next(); }
-          send402();
-        })
-        .catch(() => { res.setHeader("X-Tollbooth-Error", "x402-verify-failed"); send402(); });
+      const afterPow = (r) => {
+        if (r.ok) { incr("powSolved"); res.setHeader("X-Tollbooth-Paid", "pow"); return next(); }
+        res.setHeader("X-Pow-Error", r.reason);
+        return paidRail();
+      };
+      // pow.verify is synchronous with the default in-process replay store and
+      // returns a promise when a shared store (SQLite/Redis) answers with one.
+      // Branch on the shape instead of awaiting unconditionally: the default path
+      // must keep resolving inside this tick, because a synchronous caller (and
+      // our own single-process tests) would otherwise see the middleware return
+      // before it has decided anything.
+      const r = powEngine.verify(powHeader, powResource);
+      if (r && typeof r.then === "function") {
+        // A rejected verify would leave the request hanging with no response, so
+        // it degrades to the same refusal the store-throw path produces.
+        return r.then(afterPow, () => afterPow({ ok: false, reason: "replay store unavailable" }));
+      }
+      return afterPow(r);
     }
 
-    return send402();
+    return paidRail();
   }
 
   tollbooth.shouldCharge = shouldCharge;
@@ -262,11 +357,68 @@ 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);
+  }
+  // A stable secret makes one solved token verifiable by EVERY process sharing
+  // it, and the single-use record defaults to this process's memory, so behind a
+  // load balancer, or under `cluster`, one solve buys a free request per process
+  // for the token's lifetime. TOLLBOOTH_REPLAY_SQLITE points every process at one
+  // claim table and closes that. Opt-in, because a single-process proxy (the
+  // common case for this CLI) needs no file and no extra dependency.
+  let replayStore;
+  const replayPath = process.env.TOLLBOOTH_REPLAY_SQLITE;
+  if (replayPath) {
+    const { sqliteReplayStore } = await import("./replay.js");
+    // node:sqlite is built in (Node 22.5+); better-sqlite3 covers older Node and
+    // is what many operators already have installed. Neither is a dependency of
+    // this package: the store is opt-in, so its driver is too.
+    let db = null;
+    try {
+      const { DatabaseSync } = await import("node:sqlite");
+      db = new DatabaseSync(replayPath);
+    } catch {
+      try {
+        const { default: Database } = await import("better-sqlite3");
+        db = new Database(replayPath);
+      } catch { db = null; }
+    }
+    if (!db) {
+      // The operator asked for a shared store; starting without one would leave
+      // the replay hole open while the config says it is closed. Fail closed.
+      console.error(`✖ TOLLBOOTH_REPLAY_SQLITE=${replayPath} was set but no SQLite driver could be opened. Run Node 22.5+ (built-in node:sqlite) or install better-sqlite3. Refusing to start.`);
+      process.exit(1);
+    }
+    try {
+      // busy_timeout matters more than it looks: a claim that hits SQLITE_BUSY
+      // throws, pow.js fails closed on a throw, and the refusal lands on a
+      // crawler that did the work. WAL is best-effort because converting a
+      // brand-new file needs an exclusive lock a sibling worker may hold
+      // (measured: 2 of 160 simultaneous boots lost that lock); the winner writes
+      // the mode into the file, so the losers inherit it and nothing is lost.
+      db.exec("PRAGMA busy_timeout = 5000");
+      try { db.exec("PRAGMA journal_mode = WAL"); } catch { /* a sibling worker is setting it */ }
+      replayStore = sqliteReplayStore(db);
+    } catch (e) {
+      // Not retried: the failure this actually produces is a permanently broken
+      // file (for example an orphaned -wal/-shm left beside a deleted database),
+      // which no number of attempts clears. Refuse to start rather than serve
+      // with per-process-only replay protection while the config claims otherwise.
+      console.error(`✖ TOLLBOOTH_REPLAY_SQLITE=${replayPath} could not be initialised: ${e.message}. If a stale ${replayPath}-wal / -shm pair is present without its database, remove them. Refusing to start.`);
+      process.exit(1);
+    }
+    console.log(`shared proof-of-work replay store: sqlite ${replayPath}`);
+  } else if (_secret) {
+    console.warn("⚠ No shared proof-of-work replay store (TOLLBOOTH_REPLAY_SQLITE unset): solved tokens are single-use PER PROCESS only. Fine for one process; behind a load balancer or under `cluster`, one solve is redeemable once per process within its 5-minute TTL.");
   }
   const { default: express } = await import("express");
   const app = express();
-  const gate = createTollbooth({ resourceBaseUrl: process.env.TOLLBOOTH_RESOURCE_BASE || upstream || "" });
+  const gate = createTollbooth({ resourceBaseUrl: process.env.TOLLBOOTH_RESOURCE_BASE || upstream || "", replayStore });
   // Operator analytics — aggregate counts only (no per-request data), mounted
   // before the gate so they're always reachable and never themselves charged.
   // Two opt-in admin tokens (legacy `TOLLBOOTH_STATS_TOKEN` covers /stats only;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-tollbooth",
-  "version": "0.4.3",
+  "version": "0.6.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",
@@ -14,7 +14,9 @@
     "./worker": "./worker.js",
     "./worker.js": "./worker.js",
     "./dashboard.js": "./dashboard.js",
-    "./sinks.js": "./sinks.js"
+    "./sinks.js": "./sinks.js",
+    "./replay": "./replay.js",
+    "./replay.js": "./replay.js"
   },
   "files": [
     "index.js",
@@ -24,6 +26,7 @@
     "pow.js",
     "dashboard.js",
     "sinks.js",
+    "replay.js",
     "example.js",
     "demo.js",
     "README.md"
@@ -48,6 +51,7 @@
     "http-402",
     "402-payment-required",
     "proof-of-work",
+    "replay-protection",
     "usdc",
     "reverse-proxy",
     "express-middleware",

package/pow.js

@@ -6,6 +6,14 @@
 // exact resource they were minted for, expiry-checked, and single-use (a solved
 // token is remembered until it expires). Solving costs the caller CPU; issuing
 // and verifying cost us one hash + one HMAC.
+//
+// Single-use is only as wide as the store that records it. The default store is
+// THIS PROCESS'S memory, which is exactly right for a single-process deploy and
+// insufficient for anything else: a stable TOLLBOOTH_SECRET makes one token
+// verifiable by every worker/instance sharing it, so a single solve would buy
+// one free request PER PROCESS within the token's TTL (and again after a worker
+// recycle). Multi-worker, multi-instance and serverless operators must pass a
+// shared `replayStore` (see replay.js and the README).
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 
 const TTL_MS = 5 * 60 * 1000;
@@ -21,17 +29,52 @@ export function leadingZeroBits(buf) {
   return bits;
 }
 
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.secret]      HMAC secret binding challenges to this operator
+ * @param {number} [opts.difficulty]  leading zero bits a solution must carry
+ * @param {number} [opts.ttlMs]       challenge lifetime
+ * @param {{claim:(token:string,expiresAtMs:number)=>boolean|Promise<boolean>}} [opts.replayStore]
+ *        Shared single-use backend. `claim` must ATOMICALLY return true only the
+ *        first time it sees a token, false on every later call. Mirrors the
+ *        `store` contract of createEdgePow in edge.js (accepted here under that
+ *        name too, so an edge snippet ports across unchanged). Defaults to an
+ *        in-process Map: correct for one process, wrong for several.
+ */
 export function createPow({
   secret = process.env.TOLLBOOTH_SECRET || randomBytes(32).toString("hex"),
   difficulty = Number(process.env.TOLLBOOTH_POW_BITS) || 18,
   ttlMs = TTL_MS,
+  replayStore,
+  store,
 } = {}) {
-  const used = new Map(); // token -> expiry(ms)
-  const sweep = setInterval(() => {
+  const shared = replayStore || store;
+  if (shared && typeof shared.claim !== "function") {
+    // Loud at construction rather than silently falling back to per-process
+    // memory: an operator who passes a misshapen store believes they have
+    // cluster-wide single-use, and a silent fallback would leave the exact hole
+    // they configured the store to close.
+    throw new TypeError("createPow: replayStore must expose claim(token, expiresAtMs) => boolean | Promise<boolean>");
+  }
+  const used = new Map(); // token -> expiry(ms); only used by the default store
+  // Default replay backend, kept as the default so existing single-process
+  // deployments behave exactly as they did. The body is synchronous, so two
+  // concurrent claims of the same token in one process cannot both win, which a
+  // separate has()-then-set() would allow.
+  const memoryStore = {
+    claim: (token, expiresAtMs) => {
+      const seen = used.get(token);
+      if (seen !== undefined && seen >= Date.now()) return false; // a still-valid record => already spent
+      used.set(token, expiresAtMs);
+      return true;
+    },
+  };
+  const replay = shared || memoryStore;
+  const sweep = shared ? null : setInterval(() => {
     const now = Date.now();
     for (const [t, exp] of used) if (exp < now) used.delete(t);
   }, 60_000);
-  sweep.unref?.();
+  sweep?.unref?.();
 
   const sign = (payload) => createHmac("sha256", secret).update(payload).digest("base64url");
 
@@ -54,7 +97,37 @@ export function createPow({
     };
   }
 
-  /** Verify a "<token>:<nonce>" solution for a given resource. */
+  // Claim single-use, translating the store's answer into a verify() result.
+  //
+  // FAIL CLOSED: a store that throws or rejects means we cannot know whether this
+  // token was already spent, so we refuse the request. Same posture as edge.js,
+  // where a claim-store exception used to propagate out of verify instead of
+  // becoming a denial. An outage on the replay store costs the operator a few
+  // refused crawls; the alternative costs them the paywall.
+  function claimSingleUse(token, expiresAtMs) {
+    let claimed;
+    try { claimed = replay.claim(token, expiresAtMs); }
+    catch { return { ok: false, reason: "replay store unavailable" }; }
+    if (claimed && typeof claimed.then === "function") {
+      return claimed.then(
+        (granted) => (granted === true ? { ok: true } : { ok: false, reason: "already used" }),
+        () => ({ ok: false, reason: "replay store unavailable" }),
+      );
+    }
+    return claimed === true ? { ok: true } : { ok: false, reason: "already used" };
+  }
+
+  /** Verify a "<token>:<nonce>" solution for a given resource.
+   *
+   *  SYNC-OR-ASYNC BY DESIGN. Returns a plain result object whenever the replay
+   *  store answers synchronously (the default in-process store always does), and
+   *  a Promise of that object when a shared store answers with one. It is NOT
+   *  unconditionally async because verify() has always been synchronous here:
+   *  every existing caller reads `.ok` off the return value, and `.ok` on a
+   *  Promise is `undefined`, so a blanket change would deny every honest solve
+   *  while ALSO making the replay check a no-op for anyone who ignored the
+   *  promise. Callers that may be configured with an async store must handle a
+   *  thenable (index.js does; `await` works for both shapes). */
   function verify(headerValue, resource) {
     if (!headerValue || typeof headerValue !== "string") return { ok: false, reason: "missing solution" };
     const cut = headerValue.lastIndexOf(":");
@@ -72,12 +145,21 @@ export function createPow({
     if (a.length !== b.length || !timingSafeEqual(a, b)) return { ok: false, reason: "bad signature" };
     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" };
-    used.set(token, Number(expStr));
-    return { ok: true };
+    if (leadingZeroBits(hash) < claimed) return { ok: false, reason: "insufficient work" };
+    // Claim LAST, once the solution is known good: a forged, expired or
+    // under-worked attempt must never consume the token an honest solver is
+    // still holding, and with a shared store this is the only step that can
+    // cost a round trip.
+    return claimSingleUse(token, Number(expStr));
   }
 
-  return { challenge, verify, difficulty };
+  return { challenge, verify, difficulty, replayStore: replay };
 }

package/replay.js

@@ -0,0 +1,118 @@
+// Shared proof-of-work replay stores for the Node gate.
+//
+// The gate's default single-use record lives in one process's memory. That is
+// correct for a single-process deploy and a hole in every other shape: with a
+// stable TOLLBOOTH_SECRET (which multi-worker deploys need, so tokens verify at
+// all) one solved token is redeemable once per process inside its TTL, and again
+// after each worker recycle. These factories give the `replayStore` option a
+// backend every process shares.
+//
+// The contract is the one edge.js already uses, so a store written for the edge
+// gate works here unchanged:
+//
+//   { claim(token, expiresAtMs) => boolean | Promise<boolean> }
+//
+// `claim` must be ATOMIC: true only the very first time it sees a token, false
+// for every later call. A get-then-put pair that is not atomic lets two
+// concurrent redemptions of the same token both observe "unseen" and both pass.
+// A store that throws makes the gate REFUSE the request (pow.js fails closed),
+// so a claim implementation should throw rather than guess when its backend is
+// unreachable.
+//
+// No new runtime dependency: every factory takes an ALREADY-OPEN client the
+// operator constructed, so the tollbooth never pulls in a driver of its own.
+
+/**
+ * SQLite-backed claim, for the common case of several Node workers on one host
+ * (`cluster`, pm2, a container with N processes).
+ *
+ * Pass an open better-sqlite3 `Database`, or a node:sqlite `DatabaseSync` (Node
+ * 22.5+). Both expose the same `exec()` / `prepare().run()` surface this uses.
+ *
+ *   import Database from "better-sqlite3";
+ *   const db = new Database("/var/lib/tollbooth/replay.db");
+ *   db.pragma("journal_mode = WAL");           // concurrent writers
+ *   db.pragma("busy_timeout = 5000");          // wait for the write lock, do not throw
+ *   createTollbooth({ replayStore: sqliteReplayStore(db) });
+ *
+ * Set busy_timeout. A claim that hits SQLITE_BUSY throws, pow.js fails closed on
+ * a throw, and the refusal lands on an honest crawler that did the work. Waiting
+ * milliseconds for the write lock is strictly better than that.
+ *
+ * Atomicity comes from the PRIMARY KEY plus INSERT OR IGNORE: SQLite serializes
+ * writers on the database file, so exactly one process observes `changes === 1`
+ * for a given token. The scope of that guarantee is the FILE, which means this
+ * covers many processes sharing a disk and does NOT cover instances on different
+ * hosts (a network filesystem does not make SQLite locking reliable). Use Redis
+ * or Postgres across hosts.
+ */
+export function sqliteReplayStore(db, { table = "tollbooth_pow_replay", pruneEveryMs = 60_000 } = {}) {
+  if (!db || typeof db.prepare !== "function" || typeof db.exec !== "function") {
+    throw new TypeError("sqliteReplayStore(db): pass an open better-sqlite3 Database or node:sqlite DatabaseSync");
+  }
+  // Identifier, not a bindable value, so it is whitelisted rather than escaped.
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) throw new TypeError("sqliteReplayStore: table must be a plain identifier");
+  db.exec(`CREATE TABLE IF NOT EXISTS ${table} (token TEXT PRIMARY KEY, expires_ms INTEGER NOT NULL)`);
+  const insert = db.prepare(`INSERT OR IGNORE INTO ${table} (token, expires_ms) VALUES (?, ?)`);
+  const prune = db.prepare(`DELETE FROM ${table} WHERE expires_ms < ?`);
+  let prunedAt = 0;
+
+  return {
+    claim: (token, expiresAtMs) => {
+      const now = Date.now();
+      // Bounded growth without a background timer: the table only ever needs to
+      // hold unexpired tokens, and an expired row can be dropped because pow.js
+      // rejects an expired token before it ever claims. Time-gated so a busy
+      // gate does not run a DELETE on every request.
+      if (now - prunedAt > pruneEveryMs) { prunedAt = now; prune.run(now); }
+      const res = insert.run(String(token), Math.floor(Number(expiresAtMs) || now));
+      return Number(res.changes) === 1;
+    },
+  };
+}
+
+/**
+ * Redis-backed claim, for multiple instances across hosts (and the shape most
+ * serverless Node runtimes can reach).
+ *
+ * Pass an open client. Both major clients are supported because their SET
+ * signatures differ:
+ *
+ *   node-redis v4+:  createClient(...)  -> set(k, v, { NX: true, PX: ttl })
+ *   ioredis:         new Redis(...)     -> set(k, v, "PX", ttl, "NX")
+ *
+ *   createTollbooth({ replayStore: redisReplayStore(redis, { prefix: "tb:pow:" }) });
+ *
+ * SET NX is atomic server-side across every client, and the PX expiry is the
+ * token's own remaining lifetime, so the keyspace self-cleans. `claim` returns a
+ * PROMISE, which is why pow.js verify() has to tolerate a thenable.
+ *
+ * Errors are deliberately NOT caught here: pow.js turns a throw into a refusal.
+ * Swallowing a Redis outage and returning true would silently restore the
+ * per-process hole this store exists to close.
+ */
+export function redisReplayStore(client, { prefix = "tollbooth:pow:" } = {}) {
+  if (!client || typeof client.set !== "function") {
+    throw new TypeError("redisReplayStore(client): pass an open node-redis or ioredis client");
+  }
+  // defineCommand is ioredis-only, and ioredis is the client that takes the
+  // positional SET form. Detect rather than send one shape and hope: the failure
+  // mode of guessing wrong is not an exception but a SET without the NX flag,
+  // which overwrites the record and grants every replay.
+  const isIoredis = typeof client.defineCommand === "function";
+  return {
+    claim: async (token, expiresAtMs) => {
+      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
+      // key is evicted almost immediately.
+      const px = Math.max(1, Math.floor(Number(expiresAtMs) - Date.now()));
+      const res = isIoredis
+        ? await client.set(key, "1", "PX", px, "NX")
+        : await client.set(key, "1", { NX: true, PX: px });
+      // node-redis resolves null when NX declined; ioredis resolves null too,
+      // and "OK" on a win. Anything that is not a win is treated as already spent.
+      return res === "OK" || res === 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,
     });