agent402-tollbooth 0.5.0 → 0.6.1

package/README.md

@@ -194,6 +194,7 @@ on abort. (PoW is checked first, so an agent without a wallet always has a free
 | `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
 
@@ -211,6 +212,7 @@ Read by the bundled proxy / Express entry point (`index.js`):
 | `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 |
@@ -319,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
@@ -341,10 +425,17 @@ as drop-in copyable snippets.
 - **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
   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.
@@ -357,7 +448,8 @@ as drop-in copyable snippets.
 
 - 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.
+  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

@@ -130,6 +130,11 @@ export function createEdgeTollbooth(config = {}) {
     powDifficulty,
     secret,
     store,
+    // Same contract as the Node build's verifyX402: (request, requirements) =>
+    // boolean | Promise<boolean>. Without it this build has NO way to accept a
+    // payment, which is why the accepts block below is withheld when it is
+    // absent - see the note there.
+    verifyX402 = null,
     botUserAgents = AI_BOTS,
     // "bots" (default, charge AI crawler UAs) | "all" (charge all but free()) |
     // "strict" (charge anything that isn't a real-browser request). An explicit
@@ -148,6 +153,16 @@ export function createEdgeTollbooth(config = {}) {
     message = "This resource charges automated / AI clients per request. Humans browse free; bots pay in USDC via x402 or by solving a proof-of-work.",
   } = config;
 
+  // Say it at construction, not when a buyer gives up. An operator who sets a
+  // payTo here reasonably believes they are charging; without a verifier this
+  // build can only ever serve proof-of-work, and the price would be fiction.
+  if (payTo && !verifyX402) {
+    console.warn(
+      "agent402-tollbooth: payTo is set but no verifyX402 was supplied, so this edge build cannot accept a USDC payment. " +
+      "The USDC quote is being WITHHELD from the 402 (proof-of-work still works). Pass verifyX402 to charge, or drop payTo to stop implying it."
+    );
+  }
+
   const isBot = makeBotMatcher(botUserAgents);
   const powEngine = pow ? createEdgePow({ secret, difficulty: powDifficulty, store }) : null;
   const mem = memorySink();
@@ -194,6 +209,21 @@ export function createEdgeTollbooth(config = {}) {
     // stays a plain URL for wire compatibility).
     const powResource = `${request.method || "GET"} ${resource}`;
 
+    // An x402 payment presented on either header name. @x402/core emits
+    // PAYMENT-SIGNATURE while older clients send X-PAYMENT, and a gate that
+    // reads only one of them refuses buyers who did everything right.
+    const paymentHeader = request.headers.get("payment-signature") || request.headers.get("x-payment");
+    if (paymentHeader && verifyX402) {
+      let paid = false;
+      try {
+        paid = await verifyX402(request, { price, network, asset, payTo, resource });
+      } catch {
+        // Fail CLOSED: a verifier that throws must not open the gate.
+        paid = false;
+      }
+      if (paid) { incr("paid"); return null; }
+    }
+
     const sol = request.headers.get("x-pow-solution");
     if (powEngine && sol) {
       const r = await powEngine.verify(sol, powResource);
@@ -204,7 +234,12 @@ export function createEdgeTollbooth(config = {}) {
     const body = {
       error: "Payment Required",
       message,
-      accepts: payTo ? [{ scheme: "exact", network, maxAmountRequired: String(price), asset, payTo, resource }] : [],
+      // Only advertise USDC when this build can actually ACCEPT it. Emitting an
+      // accepts block with no verifier configured published a price that no
+      // code path could honour: a crawler that paid correctly was 402'd
+      // forever, money never moved, and the operator believed they were
+      // charging. Quoting a price you cannot take is worse than quoting none.
+      accepts: (payTo && verifyX402) ? [{ scheme: "exact", network, maxAmountRequired: String(price), asset, payTo, resource }] : [],
     };
     if (powEngine) body.proofOfWork = await powEngine.challenge(powResource);
     return new Response(JSON.stringify(body), {

package/index.js

@@ -21,6 +21,7 @@ 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;
 
@@ -87,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)
@@ -108,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
@@ -137,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
@@ -224,35 +233,56 @@ export function createTollbooth(config = {}) {
       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 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.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.
-      // 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(); });
+      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;
@@ -335,9 +365,60 @@ async function startCli() {
     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.5.0",
+  "version": "0.6.1",
   "description": "Open-source, self-hostable x402 pay-per-crawl tollbooth: charge AI bots per request (USDC via x402 — or USDG on Robinhood Chain — or free proof-of-work) while humans browse free. Drop-in Express middleware or reverse proxy — no Cloudflare, no Stripe, no signup.",
   "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,7 +145,6 @@ 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
@@ -82,9 +154,12 @@ export function createPow({
     if (!Number.isFinite(claimed) || claimed < difficulty) return { ok: false, reason: "difficulty below policy" };
     const hash = createHash("sha256").update(`${chal}:${nonce}`).digest();
     if (leadingZeroBits(hash) < claimed) return { ok: false, reason: "insufficient work" };
-    used.set(token, Number(expStr));
-    return { ok: true };
+    // 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,153 @@
+// 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";
+  const isNodeRedis = typeof client.sendCommand === "function" || typeof client.sSet === "function" || Boolean(client.options && client.options.socket);
+  if (!isIoredis && !isNodeRedis) {
+    // Fail CLOSED on an unrecognised client instead of guessing a SET shape.
+    // The failure mode of a wrong guess is not an exception: the flag argument
+    // is silently ignored, the key is overwritten every time, and single-use
+    // stops existing while everything still looks healthy.
+    throw new TypeError(
+      "redisReplayStore(client): could not identify this client as node-redis or ioredis. " +
+      "Pass one of those, or supply your own { claim(token, expiresAtMs) } store - guessing the SET argument shape risks dropping NX and granting every replay."
+    );
+  }
+  // Prove NX is actually being honoured, once, before this store is trusted.
+  // Detection above is a heuristic; this is the observation. Two claims of a
+  // throwaway key must produce a win and then a refusal. Anything else means
+  // single-use is not working, and the store refuses rather than pretending.
+  let nxProven = null;
+  const proveNx = async () => {
+    if (nxProven !== null) return nxProven;
+    const probe = `${prefix}__nxselftest__${Math.random().toString(36).slice(2)}${Date.now()}`;
+    const px = 5000;
+    const set = (k) => (isIoredis ? client.set(k, "1", "PX", px, "NX") : client.set(k, "1", { NX: true, PX: px }));
+    const first = await set(probe);
+    const second = await set(probe);
+    const firstWon = first === "OK" || first === true;
+    const secondRefused = !(second === "OK" || second === true);
+    nxProven = firstWon && secondRefused;
+    if (!nxProven) {
+      throw new Error(
+        "redisReplayStore: SET NX did not behave as required (first claim won: " + firstWon + ", second refused: " + secondRefused + "). " +
+        "Proof-of-work single-use cannot be enforced against this client, so the gate refuses rather than granting replays."
+      );
+    }
+    return nxProven;
+  };
+  return {
+    claim: async (token, expiresAtMs) => {
+      await proveNx();
+      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;
+    },
+  };
+}