agent402-tollbooth 0.9.0 → 0.9.2

package/README.md

@@ -256,6 +256,23 @@ 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`.
 
+**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
+ends with a yParity-style v byte (0x00/0x01) gets normalized by the Tempo
+node, so the canonical txid stops matching the hash of the submitted bytes
+and the relay's post-broadcast check refuses a settled payment; the buyer is
+told 402 and retries into a double charge. On any broadcast failure the gate
+now derives the only txids the credential's own signed bytes could have
+landed under (submitted form + v-swapped twin - the txid commits to the
+bytes, so the binding is exact) and, if one of them succeeded on-chain paying
+your recipient at least the challenge amount in the challenge currency,
+serves the response as paid. Verification only - nothing is re-broadcast, so
+it can never double-charge; every uncertainty fails closed to the 402.
+Options: `confirm: false` disables, `confirmRpcUrl` overrides the Tempo RPC
+(default `https://rpc.tempo.xyz`, env `TOLLBOOTH_TEMPO_RPC_URL`). Still
+dependency-free (keccak-256 is implemented in-package and pinned against the
+live incident transaction in the tests).
+
 ## Configuration
 
 | Option | Default | What |

package/index.js

@@ -19,7 +19,7 @@ import { createPow } from "./pow.js";
 import { makeBotMatcher, AI_BOTS } from "./bots.js";
 import { memorySink } from "./sinks.js";
 import { challengesFromPaymentRequired, translateCredential, receiptFromPaymentResponse, isMppCredential, DEFAULT_MPP_CHAIN_IDS } from "./mpp.js";
-import { tempoConfig, mintTempoChallenges, parseTempoCredential, checkTempoBinding, tempoRelay, relayInput, broadcastIdempotencyKey, tempoReceiptHeader, tempoProblem } from "./tempo.js";
+import { tempoConfig, mintTempoChallenges, parseTempoCredential, checkTempoBinding, tempoRelay, relayInput, broadcastIdempotencyKey, tempoReceiptHeader, tempoProblem, confirmTempoSettlement } from "./tempo.js";
 
 export { AI_BOTS, makeBotMatcher } from "./bots.js";
 export { createPow, leadingZeroBits } from "./pow.js";
@@ -349,7 +349,12 @@ export function createTollbooth(config = {}) {
       if (!claimed) return reject("invalid-challenge", "Challenge is invalid: this credential was already used or is in flight. Request the resource again for a fresh challenge.");
       const input = relayInput(cred);
       const v = await tempoRelayClient.validate(input).catch((e) => ({ ok: false, error: String(e?.message || e) }));
-      if (!v.ok) return reject("verification-failed", `Payment verification failed: ${String(v.error || "the Tempo relay rejected the credential").slice(0, 200)}.`);
+      if (!v.ok) {
+        // Operator log gets the relay's full message (`detail`); the buyer's
+        // 402 problem gets status + code only (`error`) - never an upstream body.
+        console.warn(`[agent402-tollbooth] tempo credential rejected by validate (${req.method} ${req.url}): ${v.detail || v.error}`);
+        return reject("verification-failed", `Payment verification failed: ${String(v.error || "the Tempo relay rejected the credential").slice(0, 160)}.`);
+      }
       // Buffer the handler's response (writeHead/write/end/flushHeaders) -
       // Node's real 'finish' never fires while end is buffered, so the sync
       // primitive is a promise resolved inside the buffered end.
@@ -382,15 +387,30 @@ export function createTollbooth(config = {}) {
       try { next(); } catch (err) { restore(); return next(err); }
       await endPromise;
       if (res.statusCode >= 400) { restore(); replay(); return; } // handler failed: never broadcast, nobody charged
-      const b = await tempoRelayClient.broadcast(input, { idempotencyKey: broadcastIdempotencyKey(input) }).catch((e) => ({ ok: false, error: String(e?.message || e) }));
+      let b = await tempoRelayClient.broadcast(input, { idempotencyKey: broadcastIdempotencyKey(input) }).catch((e) => ({ ok: false, error: String(e?.message || e) }));
+      if (!b.ok && tempoCfg.confirm) {
+        // The relay's verdict and the chain's truth can diverge (measured
+        // live 2026-08-20: a yParity-style v byte the node normalizes makes
+        // the relay's post-broadcast hash check fail a payment that SETTLED;
+        // the buyer retried into a double charge). Ask the chain whether this
+        // credential's own transaction landed before discarding the response —
+        // exact txid derivation from the signed bytes, verification never a
+        // re-broadcast, fails closed to the 402. See tempo.js.
+        const check = tempoCfg.confirmSettlement || ((c) => confirmTempoSettlement(c, { rpcUrl: tempoCfg.confirmRpcUrl, fetchImpl: tempoCfg.fetch }));
+        const confirmed = await Promise.resolve(check(cred)).catch(() => null);
+        if (confirmed?.txId) {
+          console.warn(`[agent402-tollbooth] tempo relay reported settlement failure but the credential's transaction SETTLED on-chain (${req.method} ${req.url} tx=${confirmed.txId}) - honouring the settlement (verified from the chain, nothing re-broadcast). Relay said: ${b.detail || b.error}`);
+          b = { ok: true, receipt: { method: "tempo", reference: confirmed.txId } };
+        }
+      }
       if (!b.ok) {
         // Broadcast failed AFTER a successful handler: discard the body, 402
         // (mirrors @x402/express's settle-failure path). Loud - this is the
         // one path that can be our latency rather than the relay's verdict.
-        console.warn(`[agent402-tollbooth] tempo broadcast failed after a successful handler (${req.method} ${req.url}) - answered 402, not charged: ${b.error}`);
+        console.warn(`[agent402-tollbooth] tempo broadcast failed after a successful handler (${req.method} ${req.url}) - answered 402, not charged: ${b.detail || b.error}`);
         buffered = [];
         restore();
-        return reject("verification-failed", `Payment verification failed: Tempo settlement was not accepted (${String(b.error || "no relay detail").slice(0, 200)}).`);
+        return reject("verification-failed", `Payment verification failed: Tempo settlement was not accepted (${String(b.error || "no relay detail").slice(0, 160)}).`);
       }
       incr("tempoPaid");
       restore();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-tollbooth",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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 - no Cloudflare, no Stripe, no signup.",
   "type": "module",
   "main": "index.js",

package/tempo.js

@@ -93,6 +93,12 @@ export function tempoConfig(cfg = {}) {
     fetch: cfg.fetch || globalThis.fetch,
     relay: cfg.relay || null, // { validate(input) -> {ok, error?}, broadcast(input, {idempotencyKey}) -> {ok, receipt?, error?} } (tests)
     relayTimeoutMs: Number.isFinite(cfg.relayTimeoutMs) ? cfg.relayTimeoutMs : 20_000,
+    // Chain-truth confirm on broadcast failure (see confirmTempoSettlement):
+    // `confirm: false` disables; `confirmRpcUrl` overrides the Tempo RPC;
+    // `confirmSettlement` injects the whole check (tests).
+    confirm: cfg.confirm !== false,
+    confirmRpcUrl: String(cfg.confirmRpcUrl || process.env.TOLLBOOTH_TEMPO_RPC_URL || "https://rpc.tempo.xyz").replace(/\/$/, ""),
+    confirmSettlement: typeof cfg.confirmSettlement === "function" ? cfg.confirmSettlement : null,
   };
 }
 
@@ -167,10 +173,18 @@ export function checkTempoBinding(credential, { secretKey, realm, price, tempo,
   return { ok: true, amount };
 }
 
+// Buyer-facing relay failure: status + the relay's error CODE only. The
+// relay's free-text `message` is an upstream body and goes to the operator
+// log (console.warn at the call sites), never into the 402 problem document
+// a buyer reads - a relay that echoes a key or account detail in an error
+// must not hand it to every buyer. (Leak audit 2026-08-19.)
 function relayFailure(res, body) {
   const code = body && typeof body === "object" && body.error && typeof body.error === "object" && typeof body.error.code === "string" ? body.error.code : null;
+  return `relay HTTP ${res?.status ?? "?"}${code ? ` ${code.slice(0, 60)}` : ""}`;
+}
+function relayFailureDetail(res, body) {
   const msg = body && typeof body === "object" && body.error && typeof body.error.message === "string" ? body.error.message : "";
-  return `relay HTTP ${res?.status ?? "?"}${code ? ` ${code}` : ""}${msg ? ` ${msg.slice(0, 160)}` : ""}`;
+  return `${relayFailure(res, body)}${msg ? ` ${msg.slice(0, 160)}` : ""}`;
 }
 
 /** The relay client. Injectable `relay` (tests) takes precedence. */
@@ -190,17 +204,17 @@ export function tempoRelay(tempo) {
     }
     let body = null;
     try { body = await res.json(); } catch { body = null; }
-    if (!res.ok || !body || body.success !== true) return { ok: false, error: relayFailure(res, body), body };
+    if (!res.ok || !body || body.success !== true) return { ok: false, error: relayFailure(res, body), detail: relayFailureDetail(res, body), body };
     return { ok: true, body };
   };
   return {
     async validate(input) {
       const r = await post("validate", input);
-      return r.ok ? { ok: true } : { ok: false, error: r.error };
+      return r.ok ? { ok: true } : { ok: false, error: r.error, detail: r.detail || r.error };
     },
     async broadcast(input, { idempotencyKey }) {
       const r = await post("broadcast", input, { "idempotency-key": idempotencyKey });
-      if (!r.ok) return { ok: false, error: r.error };
+      if (!r.ok) return { ok: false, error: r.error, detail: r.detail || r.error };
       const receipt = r.body.receipt;
       if (!receipt || typeof receipt !== "object" || typeof receipt.reference !== "string" || receipt.method !== "tempo") return { ok: false, error: "relay broadcast answered success without a tempo receipt" };
       return { ok: true, receipt };
@@ -209,7 +223,16 @@ export function tempoRelay(tempo) {
 }
 
 export function relayInput(credential) {
-  return { challenge: credential.challenge, payload: credential.payload, ...(credential.source ? { source: credential.source } : {}) };
+  // The relay's input is mppx's DESERIALIZED credential (Relay.js
+  // toRelayInput): the challenge with `request` as the decoded object, not
+  // the base64url string that rides on the wire. The first live proof
+  // (run 32295980187, 2026-08-19) sent the wire string and the relay refused
+  // every credential while the stub relay in the offline suite accepted
+  // either - the suite now pins the decoded shape.
+  const { request, ...challenge } = credential.challenge;
+  let decoded = request;
+  if (typeof request === "string") { try { decoded = JSON.parse(unb64url(request)); } catch { decoded = request; } }
+  return { challenge: { ...challenge, request: decoded }, payload: credential.payload, ...(credential.source ? { source: credential.source } : {}) };
 }
 export function broadcastIdempotencyKey(input) {
   return `mpp_${createHash("sha256").update(canonicalJson(input), "utf8").digest("hex")}`;
@@ -223,3 +246,127 @@ export function tempoProblem(kind, detail) {
   const titles = { "invalid-challenge": "Invalid Challenge", "verification-failed": "Verification Failed", "malformed-credential": "Malformed Credential", "payment-insufficient": "Payment Insufficient" };
   return { type: `https://paymentauth.org/problems/${kind}`, title: titles[kind] || kind, status: 402, detail };
 }
+
+// ---------------------------------------------------------------------------
+// Chain-truth confirm on broadcast failure (2026-08-20) — the relay's verdict
+// and the chain's truth can diverge: a buyer whose packed signature ends with
+// a yParity-style v byte (0x00/0x01) gets normalized to 27/28 by the Tempo
+// node, so the canonical txid stops matching keccak(submitted bytes) and the
+// relay's post-broadcast hash check reports `invalid_payment` for a payment
+// that SETTLED (measured live: two double charges in one buy attempt).
+// Before answering 402, ask the chain whether this credential's OWN
+// transaction landed. The txid commits to the signed bytes, so the candidates
+// are exact — the submitted form and its v-swapped twin — never a time-window
+// or payer heuristic. Fails closed on every uncertainty. Dependency-free like
+// the rest of this file: keccak-256 is implemented below (BigInt lanes — it
+// runs at most once per FAILED broadcast, so speed is irrelevant) and pinned
+// against standard vectors plus the live incident transaction in the tests.
+// ---------------------------------------------------------------------------
+
+const KECCAK_RC = [
+  "0x0000000000000001", "0x0000000000008082", "0x800000000000808a", "0x8000000080008000",
+  "0x000000000000808b", "0x0000000080000001", "0x8000000080008081", "0x8000000000008009",
+  "0x000000000000008a", "0x0000000000000088", "0x0000000080008009", "0x000000008000000a",
+  "0x000000008000808b", "0x800000000000008b", "0x8000000000008089", "0x8000000000008003",
+  "0x8000000000008002", "0x8000000000000080", "0x000000000000800a", "0x800000008000000a",
+  "0x8000000080008081", "0x8000000000008080", "0x0000000080000001", "0x8000000080008008",
+].map(BigInt);
+const KECCAK_RHO = [0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14];
+const U64 = (1n << 64n) - 1n;
+
+function keccakF(A) {
+  const rotl = (v, n) => n === 0n ? v : (((v << n) & U64) | (v >> (64n - n)));
+  for (let round = 0; round < 24; round++) {
+    const C = [0, 1, 2, 3, 4].map((x) => A[x] ^ A[x + 5] ^ A[x + 10] ^ A[x + 15] ^ A[x + 20]);
+    for (let x = 0; x < 5; x++) {
+      const D = C[(x + 4) % 5] ^ rotl(C[(x + 1) % 5], 1n);
+      for (let y = 0; y < 5; y++) A[x + 5 * y] ^= D;
+    }
+    const B = new Array(25);
+    for (let x = 0; x < 5; x++) for (let y = 0; y < 5; y++) B[y + 5 * ((2 * x + 3 * y) % 5)] = rotl(A[x + 5 * y], BigInt(KECCAK_RHO[x + 5 * y]));
+    for (let x = 0; x < 5; x++) for (let y = 0; y < 5; y++) A[x + 5 * y] = B[x + 5 * y] ^ ((~B[((x + 1) % 5) + 5 * y] & U64) & B[((x + 2) % 5) + 5 * y]);
+    A[0] ^= KECCAK_RC[round];
+  }
+}
+
+/** keccak-256 of a Buffer, as a 0x hex string. Original Keccak padding
+ *  (0x01 … 0x80), NOT SHA-3's 0x06 — Ethereum txids use the former. */
+export function keccak256Hex(buf) {
+  const rate = 136;
+  const padded = Buffer.alloc(Math.ceil((buf.length + 1) / rate) * rate);
+  buf.copy(padded);
+  padded[buf.length] = 0x01;
+  padded[padded.length - 1] |= 0x80;
+  const A = new Array(25).fill(0n);
+  for (let off = 0; off < padded.length; off += rate) {
+    for (let i = 0; i < rate / 8; i++) A[i] ^= padded.readBigUInt64LE(off + i * 8);
+    keccakF(A);
+  }
+  const out = Buffer.alloc(32);
+  for (let i = 0; i < 4; i++) out.writeBigUInt64LE(A[i], i * 8);
+  return `0x${out.toString("hex")}`;
+}
+
+/** The txids this signed Tempo transaction could have landed under: the
+ *  submitted bytes, plus (when the envelope verifiably ends with the 65-byte
+ *  packed signature — RLP string header 0xb841 at the right offset) the
+ *  v-swapped twin: yParity (0/1) <-> legacy (27/28). */
+export function candidateTxIds(signedTx) {
+  const hex = String(signedTx || "").toLowerCase();
+  if (!/^0x76[0-9a-f]{2,}$/.test(hex) || hex.length % 2 !== 0) return [];
+  const out = [keccak256Hex(Buffer.from(hex.slice(2), "hex"))];
+  // b841 = RLP header for a 65-byte string; 134 hex chars = header + 65 bytes.
+  const sigIsLast = hex.length >= 138 && hex.slice(-134, -130) === "b841";
+  if (!sigIsLast) return out;
+  const swap = { "00": "1b", "01": "1c", "1b": "00", "1c": "01" }[hex.slice(-2)];
+  if (swap) out.push(keccak256Hex(Buffer.from(hex.slice(2, -2) + swap, "hex")));
+  return out;
+}
+
+const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+
+/** Did this credential's transaction settle despite the relay's verdict?
+ *  Returns { txId } when a candidate receipt exists, succeeded (status 0x1),
+ *  and carries the challenge's transfer (currency + recipient + >= amount) —
+ *  else null. Polls briefly (a just-mined tx may not be indexed when the
+ *  relay answers). Never throws. */
+export async function confirmTempoSettlement(credential, { rpcUrl, fetchImpl = globalThis.fetch, attempts = 4, delayMs = 2000 } = {}) {
+  try {
+    const payload = credential?.payload;
+    if (payload?.type !== "transaction" || typeof payload.signature !== "string") return null;
+    let request = credential?.challenge?.request;
+    if (typeof request === "string") { try { request = JSON.parse(unb64url(request)); } catch { return null; } }
+    const currency = String(request?.currency || "").toLowerCase();
+    const recipient = String(request?.recipient || "").toLowerCase();
+    let minAmount;
+    try { minAmount = BigInt(String(request?.amount)); } catch { return null; }
+    if (!currency.startsWith("0x") || !recipient.startsWith("0x") || !(minAmount > 0n)) return null;
+    const candidates = candidateTxIds(payload.signature);
+    if (!candidates.length) return null;
+    for (let i = 0; i < attempts; i++) {
+      if (i > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+      for (const txId of candidates) {
+        let receipt;
+        try {
+          const res = await fetchImpl(rpcUrl, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_getTransactionReceipt", params: [txId] }) });
+          if (!res.ok) continue;
+          const body = await res.json();
+          if (body.error) continue;
+          receipt = body.result;
+        } catch { continue; }
+        if (!receipt || receipt.status !== "0x1") continue;
+        for (const log of receipt.logs || []) {
+          if (String(log.address || "").toLowerCase() !== currency) continue;
+          if ((log.topics || [])[0] !== TRANSFER_TOPIC) continue;
+          if (`0x${String(log.topics[2] || "").slice(-40)}`.toLowerCase() !== recipient) continue;
+          let value;
+          try { value = BigInt(log.data); } catch { continue; }
+          if (value >= minAmount) return { txId };
+        }
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}