agent402-tollbooth 0.10.6 → 0.10.8

package/README.md

@@ -271,8 +271,14 @@ settle-after-handler discipline as the x402 rail - then replays the response
 with a `Payment-Receipt` header and `X-Tollbooth-Paid: mpp-tempo`. A refused
 credential gets a 402 with fresh challenges and an RFC 9457 `problem` in the
 body. Challenges are HMAC-bound to your `TOLLBOOTH_SECRET`; each credential is
-single-use (share a `replayStore` across workers). No new dependency: the
-relay is spoken to over plain `fetch`.
+single-use through the same `replayStore` that records proof-of-work solves
+(keys prefixed `tempo:`). **Without a `replayStore` that record is per
+process**: behind a load balancer, under `cluster`, or across instances, one
+Tempo credential is accepted once per process until its challenge expires, and
+the gate logs a warning at startup. Pass `sqliteReplayStore(db)` or
+`redisReplayStore(client)` (or `TOLLBOOTH_REPLAY_SQLITE` for the CLI) in any
+deploy with more than one process. No new dependency: the relay is spoken to
+over plain `fetch`.
 
 **Chain-truth confirm (0.9.2):** a relay can report settlement failure for a
 payment that actually landed - measured live: a buyer whose packed signature
@@ -318,7 +324,7 @@ live incident transaction in the tests).
 | `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. |
+| `replayStore` | **this process's memory** | Shared single-use record for solved proof-of-work tokens and Tempo credentials. Required for multi-worker / multi-instance / serverless. Built-ins: `sqliteReplayStore(db)`, `redisReplayStore(client)`. See below. |
 
 ### Environment variables
 

package/edge.js

@@ -98,8 +98,13 @@ export function createEdgePow({ secret, difficulty = 18, ttlMs = 5 * 60 * 1000,
     if (!constEq(sig, expected)) 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" };
+    // Hold every solution to the configured difficulty too, not only the one the
+    // token claims (same rule as pow.js), so a token minted under a lower
+    // setting, or by another gate sharing the secret, buys no discount.
+    const claimedBits = Number(diffStr);
+    if (!Number.isFinite(claimedBits) || claimedBits < difficulty) return { ok: false, reason: "difficulty below policy" };
     const h = await sha256(`${chal}:${nonce}`);
-    if (leadingZeroBits(h) < Number(diffStr)) return { ok: false, reason: "insufficient work" };
+    if (leadingZeroBits(h) < claimedBits) 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.
     // F05: FAIL CLOSED, if the claim store is unavailable, deny rather than let

package/index.js

@@ -17,6 +17,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { Readable } from "node:stream";
 import { randomBytes } from "node:crypto";
 import { createPow } from "./pow.js";
+import { CLIENT_TRUST_HEADERS, HOP_BY_HOP_HEADERS } from "./strip-headers.js";
 import { makeBotMatcher, AI_BOTS } from "./bots.js";
 import { memorySink } from "./sinks.js";
 import { challengesFromPaymentRequired, translateCredential, receiptFromPaymentResponse, isMppCredential, DEFAULT_MPP_CHAIN_IDS } from "./mpp.js";
@@ -94,14 +95,9 @@ export function x402VerifierFromExpress(paymentMiddleware, { timeoutMs } = {}) {
   });
 }
 // 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([
-  "host", "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
-  "te", "trailer", "transfer-encoding", "upgrade", "content-length",
-  "x-tollbooth-paid", "x-tollbooth-error", "x-pow-error", "x-forwarded-host", "forwarded",
-  // client-IP / scheme trust headers an upstream might honour (spoofable by the bot)
-  "x-real-ip", "cf-connecting-ip", "true-client-ip", "x-client-ip", "fastly-client-ip", "x-forwarded-proto", "x-forwarded-port", "via",
-]);
+// trust signals and forwarding/hop-by-hop headers (strip-headers.js, shared with
+// the edge Worker).
+const STRIP_INBOUND = new Set([...HOP_BY_HOP_HEADERS, ...CLIENT_TRUST_HEADERS]);
 
 /**
  * Create the tollbooth Express middleware.
@@ -231,6 +227,9 @@ export function createTollbooth(config = {}) {
     console.warn("[agent402-tollbooth] Tempo enabled with a per-process random secret - set TOLLBOOTH_SECRET (or mppSecret) for multi-worker deploys.");
   }
   const tempoRelayClient = tempoCfg ? tempoRelay(tempoCfg) : null;
+  if (tempoCfg && !(replayStore && typeof replayStore.claim === "function")) {
+    console.warn("[agent402-tollbooth] WARNING: Tempo rail enabled with NO shared replayStore - each Tempo credential is single-use PER PROCESS only. With more than one process or instance, one credential is accepted once per process until its challenge expires. Pass replayStore (sqliteReplayStore / redisReplayStore, or TOLLBOOTH_REPLAY_SQLITE for the CLI) for any multi-process deploy.");
+  }
   // Single-use record for tempo credentials (challenge id), sharing the
   // operator's replayStore when given (same atomic `claim` contract as PoW).
   const tempoSeen = new Map(); // id -> expiresAt (in-process fallback)
@@ -887,7 +886,7 @@ async function startCli() {
   if (upstream) {
     app.use(createProxy(upstream));
   } else {
-    app.use((_req, res) => res.json({ ok: true, note: "Bare tollbooth gate (no TOLLBOOTH_UPSTREAM set). Clients that reach here paid or solved a proof-of-work." }));
+    app.use((_req, res) => res.json({ ok: true, note: "Bare tollbooth gate (no TOLLBOOTH_UPSTREAM set). This answer means the request passed the gate (free, paid or solved); it is not a verifier response." }));
   }
   const server = app.listen(port, () => {
     const paidLabel = x402mw ? `x402 + MPP (${process.env.TOLLBOOTH_ASSET || "USDC"}, settling via ${process.env.TOLLBOOTH_CDP_API_KEY_ID && process.env.TOLLBOOTH_CDP_API_KEY_SECRET ? "Coinbase CDP" : process.env.TOLLBOOTH_FACILITATOR_URL})` : (process.env.TOLLBOOTH_PAYTO ? `x402 quote only (${process.env.TOLLBOOTH_ASSET || "USDC"}, NOT settling - set TOLLBOOTH_FACILITATOR_URL)` : "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-tollbooth",
-  "version": "0.10.6",
+  "version": "0.10.8",
   "description": "Agent402 tollbooth: open-source, self-hostable pay-per-crawl for x402 AND MPP (the sell side of Agentic Finance): charge AI bots per request (USDC via x402, or MPP - the Machine Payments Protocol - through the same settlement, or USDG on Robinhood Chain, or free proof-of-work) while humans browse free. Drop-in Express middleware or reverse proxy that settles both wires from env alone, on your own server with no account or signup.",
   "type": "module",
   "main": "index.js",
@@ -36,6 +36,7 @@
     "dashboard.js",
     "sinks.js",
     "replay.js",
+    "strip-headers.js",
     "example.js",
     "demo.js",
     "README.md"
@@ -52,10 +53,10 @@
     "express": "^5.0.0"
   },
   "peerDependencies": {
-    "@coinbase/x402": ">=2.0.0",
-    "@x402/core": ">=2.0.0",
-    "@x402/evm": ">=2.0.0",
-    "@x402/express": ">=2.0.0"
+    "@coinbase/x402": ">=2.0.0 <3",
+    "@x402/core": ">=2.0.0 <3",
+    "@x402/evm": ">=2.0.0 <3",
+    "@x402/express": ">=2.0.0 <3"
   },
   "peerDependenciesMeta": {
     "@coinbase/x402": {

package/strip-headers.js

@@ -0,0 +1,19 @@
+// Inbound headers the tollbooth never forwards to the origin. Shared by the
+// Node reverse proxy (index.js) and the edge Worker (worker.js) so both strip
+// the same client-forgeable set. No node:* imports: the Worker loads this too.
+
+// The gate's own trust signals, forwarding headers, and client-IP / scheme
+// headers an origin might honor. A client can send any of these, so none of
+// them is passed through.
+export const CLIENT_TRUST_HEADERS = Object.freeze([
+  "x-tollbooth-paid", "x-tollbooth-error", "x-pow-error", "x-forwarded-host", "forwarded",
+  "x-real-ip", "cf-connecting-ip", "true-client-ip", "x-client-ip", "fastly-client-ip",
+  "x-forwarded-proto", "x-forwarded-port", "via",
+]);
+
+// Hop-by-hop and framing headers the Node proxy rebuilds itself. The Worker's
+// fetch manages these on its own, so the Worker does not strip them.
+export const HOP_BY_HOP_HEADERS = Object.freeze([
+  "host", "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+  "te", "trailer", "transfer-encoding", "upgrade", "content-length",
+]);

package/worker.js

@@ -15,6 +15,7 @@
 //   # ↑ same TOLLBOOTH_KV is reused for durable stats aggregation across isolates.
 import { createEdgeTollbooth, kvStatsSink } from "./edge.js";
 import { dashboardHtml } from "./dashboard.js";
+import { CLIENT_TRUST_HEADERS } from "./strip-headers.js";
 
 // Constant-time string compare, Cloudflare Workers don't ship node:crypto's
 // timingSafeEqual. Short-circuiting `===` on a secret token leaks length and
@@ -27,6 +28,9 @@ function constEq(a, b) {
   return r === 0;
 }
 
+// Same rule as the CLI (index.js startCli): any value starting "change-me".
+export const isPlaceholderSecret = (s) => /^change-me/i.test(String(s || ""));
+
 const kvStore = (kv) => ({
   // Best-effort claim. KV has no native compare-and-set, so this is get-then-put
   // (eventually consistent), concurrent dupes across isolates/locations can
@@ -74,6 +78,11 @@ export default {
     if (!env.TOLLBOOTH_SECRET) {
       return new Response("Tollbooth misconfigured: set TOLLBOOTH_SECRET (wrangler secret put TOLLBOOTH_SECRET)", { status: 500 });
     }
+    // The deploy template's placeholder is public, so tokens signed with it can
+    // be minted by anyone. Refuse it, as the CLI does.
+    if (isPlaceholderSecret(env.TOLLBOOTH_SECRET)) {
+      return new Response("Tollbooth misconfigured: TOLLBOOTH_SECRET is the public placeholder from the deploy template. Generate a real secret (openssl rand -hex 32) and set it with wrangler secret put TOLLBOOTH_SECRET.", { status: 500 });
+    }
     // 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
@@ -151,9 +160,10 @@ export default {
     target.protocol = origin.protocol;
     target.hostname = origin.hostname;
     target.port = origin.port;
-    // Strip client-forgeable trust/forwarding headers before forwarding to origin.
+    // Strip client-forgeable trust/forwarding/client-IP headers before
+    // forwarding to origin (the same list the Node proxy strips).
     const headers = new Headers(request.headers);
-    for (const h of ["x-tollbooth-paid", "x-tollbooth-error", "x-pow-error", "x-forwarded-host", "forwarded"]) headers.delete(h);
+    for (const h of CLIENT_TRUST_HEADERS) headers.delete(h);
     headers.set("x-forwarded-for", request.headers.get("cf-connecting-ip") || "");
     const init = { method: request.method, headers, redirect: "manual" };
     if (request.method !== "GET" && request.method !== "HEAD") init.body = request.body;