agent402-tollbooth 0.8.2 → 0.9.0

package/README.md

@@ -222,6 +222,40 @@ for custom verifiers you wrote yourself, and now warns once at construction;
 everyone else should pass the middleware as `x402:` above. `verifyX402` still
 receives `opts.signal` (aborted on `TOLLBOOTH_VERIFY_TIMEOUT_MS`).
 
+## Native MPP on Tempo (0.9.0)
+
+Tollbooth can charge crawlers in USDC.e **natively on Tempo** - MPP's own
+payment method - with no x402 facilitator at all, and (optionally) split every
+payment with a platform fee in the same on-chain transaction:
+
+```js
+app.use(createTollbooth({
+  price: "$0.001",
+  tempo: {
+    apiKey: process.env.TEMPO_API_KEY,        // Tempo API key with the mpp:write scope
+    recipient: "0xYourTempoPayTo",
+    // currency: defaults to USDC.e on Tempo mainnet; currencies: [...] to offer more than one
+    splits: [{ recipient: "0xPlatform", amount: "0.0002" }], // optional, up to 10, total < price
+  },
+}));
+```
+
+Or from env on the CLI: `TOLLBOOTH_TEMPO_API_KEY`, `TOLLBOOTH_TEMPO_RECIPIENT`
+(defaults to `TOLLBOOTH_PAYTO`), optional `TOLLBOOTH_TEMPO_CURRENCY`,
+`TOLLBOOTH_TEMPO_SPLITS="0xabc:0.0002,0xdef:0.0001"`.
+
+Every 402 then carries a `WWW-Authenticate: Payment` tempo/charge challenge
+(next to any evm challenges from the x402 rail, if you run both); a stock
+`mppx` client with `tempo.charge({ account })` pays it. The gate validates the
+credential with Tempo's relay BEFORE your handler runs, buffers the response,
+and broadcasts ONLY after a successful (<400) response - the same
+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`.
+
 ## Configuration
 
 | Option | Default | What |

package/index.js

@@ -19,12 +19,14 @@ 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";
 
 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";
 export { challengesFromPaymentRequired, translateCredential, receiptFromPaymentResponse, DEFAULT_MPP_CHAIN_IDS } from "./mpp.js";
+export { tempoConfig, mintTempoChallenges, parseTempoCredential, checkTempoBinding, tempoRelay, toBaseUnits, TEMPO_USDC_E, TEMPO_PATHUSD, TEMPO_MAINNET_CHAIN_ID } from "./tempo.js";
 
 const VERIFY_TIMEOUT_MS = Number(process.env.TOLLBOOTH_VERIFY_TIMEOUT_MS) || 10_000;
 
@@ -127,6 +129,24 @@ const STRIP_INBOUND = new Set([
  * @param {boolean} [config.observe]           observe-only: classify, count, never 402 (deploy a week before enforcing)
  * @param {object} [config.statsSink]          pluggable durable-stats sink (default: in-memory). See sinks.js.
  */
+/** Tempo config from env (null when TOLLBOOTH_TEMPO_API_KEY is unset). */
+export function tempoFromEnv(env = process.env) {
+  const apiKey = (env.TOLLBOOTH_TEMPO_API_KEY || "").trim();
+  if (!apiKey) return null;
+  const recipient = (env.TOLLBOOTH_TEMPO_RECIPIENT || env.TOLLBOOTH_PAYTO || "").trim();
+  const currencies = (env.TOLLBOOTH_TEMPO_CURRENCY || "").split(",").map((s) => s.trim()).filter(Boolean);
+  const splits = (env.TOLLBOOTH_TEMPO_SPLITS || "").split(",").map((s) => s.trim()).filter(Boolean).map((pair) => {
+    const [recipient, amount] = pair.split(":").map((x) => x.trim());
+    return { recipient, amount };
+  });
+  return {
+    apiKey, recipient,
+    ...(currencies.length ? { currencies } : {}),
+    ...(splits.length ? { splits } : {}),
+    ...(env.TOLLBOOTH_TEMPO_API_BASE ? { apiBaseUrl: env.TOLLBOOTH_TEMPO_API_BASE } : {}),
+  };
+}
+
 export function createTollbooth(config = {}) {
   const {
     price = process.env.TOLLBOOTH_PRICE || "$0.001",
@@ -162,6 +182,13 @@ export function createTollbooth(config = {}) {
     mppNetworks = process.env.TOLLBOOTH_MPP_NETWORKS
       ? (process.env.TOLLBOOTH_MPP_NETWORKS.trim().toLowerCase() === "all" ? "all" : process.env.TOLLBOOTH_MPP_NETWORKS.split(",").map((s) => Number(s.trim())).filter(Number.isInteger))
       : DEFAULT_MPP_CHAIN_IDS,
+    // Native MPP on Tempo (0.9.0): { apiKey, recipient, currency|currencies,
+    // splits: [{recipient, amount}], decimals, chainId, apiBaseUrl }. Settles
+    // through Tempo's relay, independent of `x402` - a tollbooth can charge in
+    // USDC.e on Tempo with no x402 facilitator at all. From env:
+    // TOLLBOOTH_TEMPO_API_KEY + TOLLBOOTH_TEMPO_RECIPIENT (+ TOLLBOOTH_TEMPO_CURRENCY,
+    // TOLLBOOTH_TEMPO_SPLITS="0xabc:0.0002,0xdef:0.0001").
+    tempo = config.tempo !== undefined ? config.tempo : tempoFromEnv(process.env),
     resourceBaseUrl = process.env.TOLLBOOTH_RESOURCE_BASE || "",
     // Adaptive proof-of-work: raise difficulty as charged-request load climbs, so
     // high-volume abuse pays escalating CPU regardless of how it disguises itself.
@@ -193,6 +220,25 @@ export function createTollbooth(config = {}) {
   if (mppOn && !(mppSecret || powSecret || process.env.TOLLBOOTH_MPP_SECRET || process.env.TOLLBOOTH_SECRET)) {
     console.warn("[agent402-tollbooth] MPP enabled with a per-process random secret - set TOLLBOOTH_SECRET (or mppSecret) for multi-worker deploys.");
   }
+  const tempoCfg = tempo ? tempoConfig(tempo) : null; // throws on a bad config - never boot a gate that mints unpayable challenges
+  const tempoKey = tempoCfg
+    ? (mppKey || String(mppSecret || powSecret || process.env.TOLLBOOTH_MPP_SECRET || process.env.TOLLBOOTH_SECRET || randomBytes(32).toString("hex")))
+    : null;
+  if (tempoCfg && !mppKey && !(mppSecret || powSecret || process.env.TOLLBOOTH_MPP_SECRET || process.env.TOLLBOOTH_SECRET)) {
+    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;
+  // 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)
+  const tempoClaim = async (id, expiresAtMs) => {
+    if (replayStore && typeof replayStore.claim === "function") return replayStore.claim(`tempo:${id}`, expiresAtMs);
+    const now = Date.now();
+    for (const [k, exp] of tempoSeen) if (exp <= now) tempoSeen.delete(k);
+    if (tempoSeen.has(id)) return false;
+    tempoSeen.set(id, expiresAtMs);
+    return true;
+  };
 
   // Passive analytics — never affects request handling, just counts what happens.
   // `mem` is an always-on in-process mirror so `.stats()` stays synchronous for
@@ -279,10 +325,80 @@ export function createTollbooth(config = {}) {
         ...extra,
       };
       if (powEngine) body.proofOfWork = powEngine.challenge(powResource, difficultyNow());
+      // Native Tempo challenge(s) on every 402, next to whatever evm challenges
+      // the x402 rail lifted - a stock mppx client pays whichever it speaks.
+      if (tempoCfg) {
+        const tempoWww = mintTempoChallenges({ price, realm: mppRealm(req), secretKey: tempoKey, tempo: tempoCfg });
+        if (tempoWww) headers = { ...headers, "WWW-Authenticate": [headers["WWW-Authenticate"], tempoWww].filter(Boolean).join(", ") };
+      }
       for (const [k, v] of Object.entries(headers)) { if (v != null && v !== "") res.setHeader(k, v); }
       res.status(402).json(body);
     };
 
+    // Native Tempo rail: validate with the relay BEFORE the handler, buffer
+    // the handler's response, broadcast ONLY after a <400 response (the same
+    // settle-after-handler discipline @x402/express enforces), then replay
+    // the buffered response with a Payment-Receipt. A refused credential gets
+    // the gate's 402 with fresh challenges plus an RFC 9457 `problem`.
+    const tempoRail = async (cred) => {
+      const reject = (kind, detail) => { res.setHeader("X-Tollbooth-Error", `tempo-${kind}`); return send402({ problem: tempoProblem(kind, detail) }); };
+      const binding = checkTempoBinding(cred, { secretKey: tempoKey, realm: mppRealm(req), price, tempo: tempoCfg });
+      if (!binding.ok) return reject(/below this route's price/.test(binding.reason) ? "payment-insufficient" : "invalid-challenge", `Challenge is invalid: ${binding.reason}. Request the resource again for a fresh challenge.`);
+      let claimed;
+      try { claimed = await tempoClaim(cred.challenge.id, Date.parse(cred.challenge.expires) || Date.now() + 300_000); } catch { claimed = false; }
+      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)}.`);
+      // 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.
+      const originalWriteHead = res.writeHead.bind(res);
+      const originalWrite = res.write.bind(res);
+      const originalEnd = res.end.bind(res);
+      const originalFlushHeaders = typeof res.flushHeaders === "function" ? res.flushHeaders.bind(res) : null;
+      let buffered = [];
+      let settled = false;
+      let endCalled;
+      const endPromise = new Promise((resolve) => { endCalled = resolve; });
+      const restore = () => {
+        settled = true;
+        res.writeHead = originalWriteHead; res.write = originalWrite; res.end = originalEnd;
+        if (originalFlushHeaders) res.flushHeaders = originalFlushHeaders;
+      };
+      res.writeHead = (...a) => { if (!settled) { buffered.push(["writeHead", a]); return res; } return originalWriteHead(...a); };
+      res.write = (...a) => { if (!settled) { buffered.push(["write", a]); return true; } return originalWrite(...a); };
+      res.end = (...a) => { if (!settled) { buffered.push(["end", a]); endCalled(); return res; } return originalEnd(...a); };
+      if (originalFlushHeaders) res.flushHeaders = () => { if (!settled) { buffered.push(["flushHeaders", []]); return; } return originalFlushHeaders(); };
+      const replay = () => {
+        for (const [fn, a] of buffered) {
+          if (fn === "writeHead") originalWriteHead(...a);
+          else if (fn === "write") originalWrite(...a);
+          else if (fn === "flushHeaders") { if (originalFlushHeaders) originalFlushHeaders(); }
+          else originalEnd(...a);
+        }
+        buffered = [];
+      };
+      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) }));
+      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}`);
+        buffered = [];
+        restore();
+        return reject("verification-failed", `Payment verification failed: Tempo settlement was not accepted (${String(b.error || "no relay detail").slice(0, 200)}).`);
+      }
+      incr("tempoPaid");
+      restore();
+      res.setHeader("Payment-Receipt", tempoReceiptHeader(b.receipt));
+      res.setHeader("X-Tollbooth-Paid", "mpp-tempo");
+      replay();
+    };
+
     // Paid rail, middleware mode: delegate to the operator's x402 middleware
     // with the REAL response so verify -> handler -> settle run in ITS order,
     // exactly once. Its 402 (no/invalid payment) is intercepted and replaced by
@@ -403,6 +519,10 @@ export function createTollbooth(config = {}) {
     // 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 = () => {
+      if (tempoCfg) {
+        const cred = parseTempoCredential(req.headers.authorization);
+        if (cred) return tempoRail(cred);
+      }
       if (x402) return middlewareRail();
       const payHeader = req.headers["x-payment"] || req.headers["payment-signature"];
       if (payTo && typeof verifyX402 === "function" && payHeader) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-tollbooth",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "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",
@@ -27,6 +27,7 @@
     "bots.js",
     "pow.js",
     "mpp.js",
+    "tempo.js",
     "dashboard.js",
     "sinks.js",
     "replay.js",

package/tempo.js

@@ -0,0 +1,225 @@
+// Native MPP on Tempo for the tollbooth - dependency-free (0.9.0).
+//
+// MPP's own native payment method is `tempo/charge`: a TIP-20 stablecoin
+// transfer on Tempo (chain 4217), settled through Tempo's hosted relay
+// (`POST /v1/mpp/validate` before the handler, `POST /v1/mpp/broadcast` only
+// after a successful response). It is NOT EIP-3009, so it cannot ride an x402
+// facilitator the way mpp.js translates the `evm` method - it needs its own
+// gate, and that gate needs a Tempo API key with the `mpp:write` scope.
+//
+// Same posture as mpp.js: no mppx dependency. The challenge is minted with
+// the same HMAC id binding mpp.js uses (so a stock mppx client pays it and
+// mppx's Challenge.verify agrees on the id given the same secret), the
+// request shape is byte-for-byte what mppx's tempo/charge schema emits (base
+// units `amount` string, NO `decimals` on the wire, `methodDetails.chainId`,
+// optional `methodDetails.splits` in base units - every one of those drifts
+// bit the main app live in 2026-08), and the relay is spoken to over plain
+// fetch with the wire mppx's own Relay.js uses ({challenge, payload}, header
+// `tempo-api-key`, `idempotency-key` on broadcast, `{success:true}` /
+// `{success:true, receipt}` on the way back).
+//
+// Split payments (`splits`): Tempo settles one transfer to up to 10 extra
+// recipients atomically with the main one - a platform fee in the same
+// transaction, which x402 cannot express. Each split amount must be > 0 and
+// the splits must total strictly LESS than the price (the remainder is the
+// operator's); validated at config time so a bad split never mints a
+// challenge nobody can pay.
+import { createHmac, createHash, timingSafeEqual } from "node:crypto";
+
+const SCHEME = "Payment";
+export const TEMPO_MAINNET_CHAIN_ID = 4217;
+/** USDC.e on Tempo mainnet (138/141 registry sellers + mppx's mainnet default). */
+export const TEMPO_USDC_E = "0x20C000000000000000000000b9537d11c60E8b50";
+/** PathUSD - mppx's TESTNET default; accepted if the operator lists it. */
+export const TEMPO_PATHUSD = "0x20c0000000000000000000000000000000000000";
+const DEFAULT_API_BASE = "https://api.tempo.xyz";
+const HEX_ADDR = /^0x[0-9a-fA-F]{40}$/;
+const HEX = /^0x[0-9a-fA-F]+$/;
+
+export const b64url = (s) => Buffer.from(s, "utf8").toString("base64url");
+export const unb64url = (s) => Buffer.from(String(s), "base64url").toString("utf8");
+export function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+}
+function challengeId(secretKey, c) {
+  const input = [c.realm, c.method, c.intent, c.request, c.expires ?? "", c.digest ?? "", c.opaque ?? ""].join("|");
+  return createHmac("sha256", Buffer.from(secretKey, "utf8")).update(input, "utf8").digest("base64url");
+}
+function idMatches(secretKey, c) {
+  const a = Buffer.from(String(c.id || ""), "utf8");
+  const b = Buffer.from(challengeId(secretKey, c), "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+const authParam = (name, value) => {
+  const v = String(value);
+  if (/[\r\n]/.test(v)) throw new Error("invalid auth-param value");
+  return `${name}="${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+};
+
+/** "$0.001" | 0.001 | "0.001" -> base-units BigInt at `decimals`. */
+export function toBaseUnits(price, decimals = 6) {
+  const s = String(price).trim().replace(/^\$/, "");
+  if (!/^\d+(\.\d+)?$/.test(s)) throw new Error(`tempo: price "${price}" is not a decimal amount`);
+  const [int, frac = ""] = s.split(".");
+  if (frac.length > decimals) throw new Error(`tempo: price "${price}" has more than ${decimals} decimals`);
+  return BigInt(int + frac.padEnd(decimals, "0"));
+}
+
+/** Normalise + validate the operator's tempo config once, at createTollbooth time. */
+export function tempoConfig(cfg = {}) {
+  const apiKey = String(cfg.apiKey || "").trim();
+  const recipient = String(cfg.recipient || "").trim();
+  if (!apiKey) throw new Error("tollbooth tempo: `apiKey` (Tempo API key with the mpp:write scope) is required");
+  if (!HEX_ADDR.test(recipient)) throw new Error("tollbooth tempo: `recipient` must be a 0x EVM address (your Tempo payTo)");
+  const decimals = Number.isInteger(cfg.decimals) ? cfg.decimals : 6;
+  const currencies = (Array.isArray(cfg.currencies) ? cfg.currencies : [cfg.currency || TEMPO_USDC_E]).map((c) => String(c).trim()).filter(Boolean);
+  if (!currencies.length || !currencies.every((c) => HEX_ADDR.test(c))) throw new Error("tollbooth tempo: `currency`/`currencies` must be TIP-20 token addresses (default USDC.e)");
+  const chainId = Number.isInteger(cfg.chainId) ? cfg.chainId : TEMPO_MAINNET_CHAIN_ID;
+  const timeoutSeconds = Number.isFinite(cfg.timeoutSeconds) && cfg.timeoutSeconds > 0 ? cfg.timeoutSeconds : 300;
+  const splits = Array.isArray(cfg.splits) ? cfg.splits.map((s, i) => {
+    if (!s || !HEX_ADDR.test(String(s.recipient || ""))) throw new Error(`tollbooth tempo: splits[${i}].recipient must be a 0x address`);
+    const amount = toBaseUnits(s.amount, decimals);
+    if (amount <= 0n) throw new Error(`tollbooth tempo: splits[${i}].amount must be > 0`);
+    return { recipient: s.recipient, amount };
+  }) : [];
+  if (splits.length > 10) throw new Error("tollbooth tempo: at most 10 splits");
+  return {
+    apiKey, recipient, decimals, currencies, chainId, timeoutSeconds, splits,
+    apiBaseUrl: String(cfg.apiBaseUrl || DEFAULT_API_BASE).replace(/\/$/, ""),
+    description: cfg.description ? String(cfg.description).slice(0, 200) : undefined,
+    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,
+  };
+}
+
+/** Mint one tempo/charge challenge per currency. Returns the WWW-Authenticate
+ *  value ("Payment id=..., ..." joined by ", ") or null when unpriceable. */
+export function mintTempoChallenges({ price, realm, secretKey, tempo }) {
+  let amount;
+  try { amount = toBaseUnits(price, tempo.decimals); } catch { return null; }
+  if (amount <= 0n) return null;
+  const splitTotal = tempo.splits.reduce((a, s) => a + s.amount, 0n);
+  if (tempo.splits.length && !(splitTotal < amount)) return null; // config-time check should have caught it; never mint an unpayable challenge
+  const expires = new Date(Date.now() + tempo.timeoutSeconds * 1000).toISOString();
+  const out = [];
+  for (const currency of tempo.currencies) {
+    const request = {
+      amount: amount.toString(),
+      currency,
+      recipient: tempo.recipient,
+      ...(tempo.description ? { description: tempo.description } : {}),
+      methodDetails: {
+        chainId: tempo.chainId,
+        ...(tempo.splits.length ? { splits: tempo.splits.map((s) => ({ recipient: s.recipient, amount: s.amount.toString() })) } : {}),
+      },
+    };
+    const c = { realm, method: "tempo", intent: "charge", request: b64url(canonicalJson(request)), expires };
+    c.id = challengeId(secretKey, c);
+    out.push([authParam("id", c.id), authParam("realm", c.realm), authParam("method", c.method), authParam("intent", c.intent), authParam("request", c.request), authParam("expires", c.expires)].join(", "));
+  }
+  return out.map((p) => `${SCHEME} ${p}`).join(", ");
+}
+
+/** Parse an Authorization: Payment credential; null unless it is a
+ *  well-formed tempo/charge credential (no binding check here). */
+export function parseTempoCredential(authorizationHeader) {
+  if (typeof authorizationHeader !== "string") return null;
+  const m = authorizationHeader.match(/^Payment\s+([A-Za-z0-9_-]+=*)\s*$/i);
+  if (!m) return null;
+  let wire;
+  try { wire = JSON.parse(unb64url(m[1])); } catch { return null; }
+  const ch = wire?.challenge;
+  if (!ch || typeof ch !== "object" || ch.method !== "tempo" || (ch.intent || "charge") !== "charge") return null;
+  if (typeof ch.request !== "string" || typeof ch.id !== "string") return null;
+  const p = wire.payload;
+  if (!p || typeof p !== "object") return null;
+  if (p.type === "transaction" || p.type === "proof") { if (!HEX.test(String(p.signature || ""))) return null; }
+  else if (p.type === "hash") { if (!HEX.test(String(p.hash || ""))) return null; }
+  else return null;
+  return { challenge: ch, payload: p, ...(wire.source ? { source: wire.source } : {}) };
+}
+
+/** Binding: is this a challenge WE minted, unexpired, for our recipient, in a
+ *  currency we offer, on our chain, for at least this price? The relay checks
+ *  the signed transaction against the challenge's OWN request - never that we
+ *  minted it - so a forged 1-unit challenge would buy anything without this. */
+export function checkTempoBinding(credential, { secretKey, realm, price, tempo, now = Date.now() }) {
+  const bad = (reason) => ({ ok: false, reason });
+  const ch = credential?.challenge;
+  if (!ch) return bad("no challenge");
+  if (!secretKey) return bad("no secret to verify the challenge binding");
+  if (!idMatches(secretKey, ch)) return bad("challenge id does not HMAC-verify - not minted by this gate");
+  if (realm && ch.realm !== realm) return bad("challenge realm is not ours");
+  const exp = Date.parse(ch.expires);
+  if (!Number.isFinite(exp) || exp <= now) return bad("challenge expired");
+  let r;
+  try { r = JSON.parse(unb64url(ch.request)); } catch { return bad("challenge request does not decode"); }
+  if (!tempo.currencies.map((c) => c.toLowerCase()).includes(String(r.currency || "").toLowerCase())) return bad("challenge currency is not one this gate offers");
+  if (String(r.recipient || "").toLowerCase() !== tempo.recipient.toLowerCase()) return bad("challenge recipient is not this gate's payTo");
+  if (Number(r.methodDetails?.chainId) !== tempo.chainId) return bad("challenge chainId is not this gate's chain");
+  let amount, expected;
+  try { amount = BigInt(String(r.amount)); expected = toBaseUnits(price, tempo.decimals); } catch { return bad("challenge amount is not an integer base-units string"); }
+  if (amount < expected) return bad(`challenge amount ${amount} is below this route's price ${expected}`);
+  return { ok: true, amount };
+}
+
+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;
+  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)}` : ""}`;
+}
+
+/** The relay client. Injectable `relay` (tests) takes precedence. */
+export function tempoRelay(tempo) {
+  if (tempo.relay) return tempo.relay;
+  const post = async (path, input, headers = {}) => {
+    let res;
+    try {
+      res = await tempo.fetch(`${tempo.apiBaseUrl}/v1/mpp/${path}`, {
+        method: "POST",
+        headers: { Accept: "application/json", "content-type": "application/json", "tempo-api-key": tempo.apiKey, ...headers },
+        body: JSON.stringify(input),
+        signal: AbortSignal.timeout(tempo.relayTimeoutMs),
+      });
+    } catch (e) {
+      return { ok: false, error: `relay unreachable: ${String(e?.message || e).slice(0, 120)}` };
+    }
+    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 };
+    return { ok: true, body };
+  };
+  return {
+    async validate(input) {
+      const r = await post("validate", input);
+      return r.ok ? { ok: true } : { ok: false, error: r.error };
+    },
+    async broadcast(input, { idempotencyKey }) {
+      const r = await post("broadcast", input, { "idempotency-key": idempotencyKey });
+      if (!r.ok) return { ok: false, error: 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 };
+    },
+  };
+}
+
+export function relayInput(credential) {
+  return { challenge: credential.challenge, payload: credential.payload, ...(credential.source ? { source: credential.source } : {}) };
+}
+export function broadcastIdempotencyKey(input) {
+  return `mpp_${createHash("sha256").update(canonicalJson(input), "utf8").digest("hex")}`;
+}
+/** Payment-Receipt header value (base64url JSON, as mppx's Receipt.serialize). */
+export function tempoReceiptHeader(receipt) {
+  return b64url(JSON.stringify({ method: "tempo", status: "success", reference: receipt.reference, timestamp: receipt.timestamp || new Date().toISOString(), ...(receipt.externalId ? { externalId: receipt.externalId } : {}) }));
+}
+/** RFC 9457 problem document for a refused tempo credential. */
+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 };
+}