xytara 3.1.13 → 3.1.15

package/lib/bolt_payment_front.js

@@ -1,224 +1,224 @@
-"use strict";
-
-const crypto = require("crypto");
-const boltAdapter = require("./bolt_adapter");
-
-function normalizeString(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function safeEqualHex(left, right) {
-  const a = Buffer.from(String(left || ""), "hex");
-  const b = Buffer.from(String(right || ""), "hex");
-  if (a.length === 0 || b.length === 0 || a.length !== b.length) return false;
-  return crypto.timingSafeEqual(a, b);
-}
-
-function decodeBase64UrlJson(value) {
-  try {
-    return JSON.parse(Buffer.from(String(value || ""), "base64url").toString("utf8"));
-  } catch (_) {
-    return null;
-  }
-}
-
-function loadBoltFrontConfig() {
-  const sharedSecret = normalizeString(process.env.XYTARA_BOLT_SHARED_SECRET);
-  return {
-    enabled: String(process.env.XYTARA_BOLT_ENABLED || (sharedSecret ? "true" : "false")).trim().toLowerCase() !== "false",
-    shared_secret: sharedSecret || null,
-    network: normalizeString(process.env.XYTARA_BOLT_NETWORK) || normalizeString(process.env.XYTARA_BSV_TERANODE_NETWORK) || "mainnet",
-    proof_mode: normalizeString(process.env.XYTARA_BOLT_PROOF_MODE) || "spv_or_block_header_verifiable",
-    max_age_seconds: Math.max(30, Number(process.env.XYTARA_BOLT_MAX_AGE_SECONDS || 300) || 300),
-    required_headers: ["authorization"],
-    auth_scheme: "BOLT",
-    token_shape: "base64url_json_with_utxo_spv_proof_and_hmac_signed_payload"
-  };
-}
-
-function parseBoltAuthorization(headers) {
-  const authorization = headers && typeof headers.authorization === "string"
-    ? headers.authorization.trim()
-    : "";
-  const match = authorization.match(/^BOLT\s+(.+)$/i);
-  if (!match) return null;
-  const decoded = decodeBase64UrlJson(match[1]);
-  if (!decoded || typeof decoded !== "object") return null;
-  return {
-    wallet_id: decoded.wallet_id || decoded.gateway_id || "bolt_gateway",
-    encoded: decoded.payload || null,
-    signature: decoded.signature || null,
-    txid: decoded.txid || null,
-    spv_proof_ref: decoded.spv_proof_ref || null,
-    merkle_path_ref: decoded.merkle_path_ref || null,
-    block_header_ref: decoded.block_header_ref || null,
-    network: decoded.network || null,
-    proof_bundle_ref: decoded.proof_bundle_ref || null,
-    scheme: "bolt"
-  };
-}
-
-function verifyBoltPaymentPayload(paymentPayload, quote, walletId, maxAgeSeconds, config) {
-  if (!paymentPayload || typeof paymentPayload !== "object") return { ok: false, reason: "bolt_payload_invalid" };
-  if (!paymentPayload.quote_id || paymentPayload.quote_id !== quote.quote_id) return { ok: false, reason: "bolt_quote_mismatch" };
-  if (paymentPayload.amount_minor !== quote.amount_minor) return { ok: false, reason: "bolt_amount_mismatch" };
-  if (paymentPayload.currency !== quote.currency) return { ok: false, reason: "bolt_currency_mismatch" };
-  if (paymentPayload.account_id && paymentPayload.account_id !== quote.account_id) return { ok: false, reason: "bolt_account_mismatch" };
-  if (walletId && paymentPayload.wallet_id && paymentPayload.wallet_id !== walletId) return { ok: false, reason: "bolt_wallet_mismatch" };
-  if (!paymentPayload.nonce || typeof paymentPayload.nonce !== "string") return { ok: false, reason: "bolt_nonce_missing" };
-  if (!paymentPayload.issued_at_iso || Number.isNaN(Date.parse(paymentPayload.issued_at_iso))) return { ok: false, reason: "bolt_issued_at_invalid" };
-  const ageSeconds = Math.max(0, Math.floor((Date.now() - Date.parse(paymentPayload.issued_at_iso)) / 1000));
-  if (ageSeconds > maxAgeSeconds) return { ok: false, reason: "bolt_token_expired" };
-  if (!normalizeString(paymentPayload.txid || paymentPayload.transaction_id)) return { ok: false, reason: "bolt_txid_missing" };
-  if (
-    !normalizeString(paymentPayload.spv_proof_ref || paymentPayload.proof_bundle_ref)
-    && !normalizeString(paymentPayload.merkle_path_ref)
-    && !normalizeString(paymentPayload.block_header_ref)
-  ) {
-    return { ok: false, reason: "bolt_proof_missing" };
-  }
-  if (
-    normalizeString(paymentPayload.network)
-    && normalizeString(config && config.network)
-    && normalizeString(paymentPayload.network) !== normalizeString(config.network)
-  ) {
-    return { ok: false, reason: "bolt_network_mismatch" };
-  }
-  return { ok: true, age_seconds: ageSeconds };
-}
-
-async function verifyBoltAccessToken(headers, quote, state) {
-  // Real BSV path: when a chain provider is configured, verify an on-chain BSV
-  // payment ("BOLT <txid>") that pays the operator address >= the required amount,
-  // with single-use (per-txid) replay protection. Otherwise fall through to the
-  // existing gateway-signed token scheme below (unchanged).
-  const bsvConfig = boltAdapter.loadBoltConfig();
-  if (boltAdapter.isConfigured(bsvConfig)) {
-    const authorization = headers && typeof headers.authorization === "string" ? headers.authorization : "";
-    const parsed = boltAdapter.parseBoltHeader(authorization);
-    if (!parsed) return { ok: false, status: 402, reason: "bolt_authorization_malformed" };
-    if (state && state.acceptedPaymentNonces && state.acceptedPaymentNonces.has(parsed.txid)) {
-      return { ok: false, status: 403, reason: "bolt_txid_replayed" };
-    }
-    const requiredSats = boltAdapter.computeRequiredSats(bsvConfig, quote);
-    const result = await boltAdapter.verifyBsvPayment(bsvConfig, parsed.txid, undefined, { requiredSats });
-    if (!result.ok) return { ok: false, status: 403, reason: result.reason, detail: result.detail || null };
-    return {
-      ok: true,
-      verification_mode: "bolt_bsv_onchain",
-      wallet_id: "bolt",
-      payment_payload: {
-        nonce: result.txid,
-        txid: result.txid,
-        paid_sats: result.paid_sats,
-        confirmations: result.confirmations,
-        quote_id: quote && quote.quote_id,
-        issued_at_iso: new Date().toISOString()
-      },
-      bolt: { txid: result.txid, paid_sats: result.paid_sats, confirmations: result.confirmations, network: result.network }
-    };
-  }
-
-  const config = loadBoltFrontConfig();
-  if (!config.enabled) return { ok: false, status: 503, reason: "bolt_not_enabled" };
-  if (!config.shared_secret) return { ok: false, status: 503, reason: "bolt_shared_secret_missing" };
-  const payment = parseBoltAuthorization(headers || {});
-  if (!payment || !payment.encoded || !payment.signature) {
-    return { ok: false, status: 402, reason: "bolt_headers_incomplete" };
-  }
-  const expectedSignature = crypto.createHmac("sha256", config.shared_secret).update(payment.encoded).digest("hex");
-  if (!safeEqualHex(expectedSignature, payment.signature)) {
-    return { ok: false, status: 403, reason: "bolt_signature_invalid" };
-  }
-  const payload = decodeBase64UrlJson(payment.encoded);
-  const validation = verifyBoltPaymentPayload(payload, quote, payment.wallet_id, config.max_age_seconds, config);
-  if (!validation.ok) return { ok: false, status: 403, reason: validation.reason };
-  return {
-    ok: true,
-    verification_mode: "bolt_gateway_signed",
-    wallet_id: payment.wallet_id,
-    payment_payload: payload,
-    age_seconds: validation.age_seconds,
-    bolt: {
-      txid: payment.txid || payload.txid || payload.transaction_id || null,
-      spv_proof_ref: payment.spv_proof_ref || payload.spv_proof_ref || payload.proof_bundle_ref || null,
-      merkle_path_ref: payment.merkle_path_ref || payload.merkle_path_ref || null,
-      block_header_ref: payment.block_header_ref || payload.block_header_ref || null,
-      proof_bundle_ref: payment.proof_bundle_ref || payload.proof_bundle_ref || null,
-      network: payment.network || payload.network || config.network,
-      proof_mode: config.proof_mode
-    }
-  };
-}
-
-function buildBoltSecuritySummary() {
-  const config = loadBoltFrontConfig();
-  const blockers = [];
-  if (config.enabled && !config.shared_secret) blockers.push("bolt_shared_secret_missing");
-  return {
-    ok: true,
-    category: "machine-commerce-bolt-security-summary",
-    summary_version: "xytara-bolt-security-summary-v1",
-    enabled: config.enabled,
-    shared_secret_configured: Boolean(config.shared_secret),
-    network: config.network,
-    proof_mode: config.proof_mode,
-    max_age_seconds: config.max_age_seconds,
-    auth_scheme: config.auth_scheme,
-    token_shape: config.token_shape,
-    ready: config.enabled && blockers.length === 0,
-    blockers,
-    linked_surfaces: {
-      bolt_lane_ref: "/v1/bolt",
-      commands_execute_ref: "/bolt/commands/execute",
-      mcp_invoke_ref: "/bolt/mcp/tools/invoke"
-    }
-  };
-}
-
-function buildBoltChallengePayload(quote) {
-  // Real BSV path: advertise where to pay and how much so the caller can send a
-  // BSV transaction and retry with "BOLT <txid>".
-  const bsvConfig = boltAdapter.loadBoltConfig();
-  if (boltAdapter.isConfigured(bsvConfig) && bsvConfig.payToAddress && bsvConfig.priceSats) {
-    const requiredSats = boltAdapter.computeRequiredSats(bsvConfig, quote);
-    return {
-      ok: false,
-      payment_required: {
-        scheme: "bolt",
-        quote,
-        bsv: boltAdapter.buildBoltChallenge(bsvConfig, { requiredSats }),
-        operator_requirements: {
-          auth_scheme: "BOLT",
-          token_shape: "authorization_header_BOLT_txid",
-          security_ref: "/v1/bolt/security",
-          proof_requirements: ["pay_the_exact_amount_sats_to_address_then_present_txid"]
-        }
-      }
-    };
-  }
-  return {
-    ok: false,
-    payment_required: {
-      scheme: "bolt",
-      quote,
-      operator_requirements: {
-        auth_scheme: "BOLT",
-        token_shape: "base64url_json_with_utxo_spv_proof_and_hmac_signed_payload",
-        security_ref: "/v1/bolt/security",
-        proof_requirements: [
-          "txid",
-          "one_of:spv_proof_ref|merkle_path_ref|block_header_ref|proof_bundle_ref"
-        ]
-      }
-    }
-  };
-}
-
-module.exports = {
-  buildBoltChallengePayload,
-  buildBoltSecuritySummary,
-  loadBoltFrontConfig,
-  parseBoltAuthorization,
-  verifyBoltAccessToken
-};
+"use strict";
+
+const crypto = require("crypto");
+const boltAdapter = require("./bolt_adapter");
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function safeEqualHex(left, right) {
+  const a = Buffer.from(String(left || ""), "hex");
+  const b = Buffer.from(String(right || ""), "hex");
+  if (a.length === 0 || b.length === 0 || a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+function decodeBase64UrlJson(value) {
+  try {
+    return JSON.parse(Buffer.from(String(value || ""), "base64url").toString("utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+function loadBoltFrontConfig() {
+  const sharedSecret = normalizeString(process.env.XYTARA_BOLT_SHARED_SECRET);
+  return {
+    enabled: String(process.env.XYTARA_BOLT_ENABLED || (sharedSecret ? "true" : "false")).trim().toLowerCase() !== "false",
+    shared_secret: sharedSecret || null,
+    network: normalizeString(process.env.XYTARA_BOLT_NETWORK) || normalizeString(process.env.XYTARA_BSV_TERANODE_NETWORK) || "mainnet",
+    proof_mode: normalizeString(process.env.XYTARA_BOLT_PROOF_MODE) || "spv_or_block_header_verifiable",
+    max_age_seconds: Math.max(30, Number(process.env.XYTARA_BOLT_MAX_AGE_SECONDS || 300) || 300),
+    required_headers: ["authorization"],
+    auth_scheme: "BOLT",
+    token_shape: "base64url_json_with_utxo_spv_proof_and_hmac_signed_payload"
+  };
+}
+
+function parseBoltAuthorization(headers) {
+  const authorization = headers && typeof headers.authorization === "string"
+    ? headers.authorization.trim()
+    : "";
+  const match = authorization.match(/^BOLT\s+(.+)$/i);
+  if (!match) return null;
+  const decoded = decodeBase64UrlJson(match[1]);
+  if (!decoded || typeof decoded !== "object") return null;
+  return {
+    wallet_id: decoded.wallet_id || decoded.gateway_id || "bolt_gateway",
+    encoded: decoded.payload || null,
+    signature: decoded.signature || null,
+    txid: decoded.txid || null,
+    spv_proof_ref: decoded.spv_proof_ref || null,
+    merkle_path_ref: decoded.merkle_path_ref || null,
+    block_header_ref: decoded.block_header_ref || null,
+    network: decoded.network || null,
+    proof_bundle_ref: decoded.proof_bundle_ref || null,
+    scheme: "bolt"
+  };
+}
+
+function verifyBoltPaymentPayload(paymentPayload, quote, walletId, maxAgeSeconds, config) {
+  if (!paymentPayload || typeof paymentPayload !== "object") return { ok: false, reason: "bolt_payload_invalid" };
+  if (!paymentPayload.quote_id || paymentPayload.quote_id !== quote.quote_id) return { ok: false, reason: "bolt_quote_mismatch" };
+  if (paymentPayload.amount_minor !== quote.amount_minor) return { ok: false, reason: "bolt_amount_mismatch" };
+  if (paymentPayload.currency !== quote.currency) return { ok: false, reason: "bolt_currency_mismatch" };
+  if (paymentPayload.account_id && paymentPayload.account_id !== quote.account_id) return { ok: false, reason: "bolt_account_mismatch" };
+  if (walletId && paymentPayload.wallet_id && paymentPayload.wallet_id !== walletId) return { ok: false, reason: "bolt_wallet_mismatch" };
+  if (!paymentPayload.nonce || typeof paymentPayload.nonce !== "string") return { ok: false, reason: "bolt_nonce_missing" };
+  if (!paymentPayload.issued_at_iso || Number.isNaN(Date.parse(paymentPayload.issued_at_iso))) return { ok: false, reason: "bolt_issued_at_invalid" };
+  const ageSeconds = Math.max(0, Math.floor((Date.now() - Date.parse(paymentPayload.issued_at_iso)) / 1000));
+  if (ageSeconds > maxAgeSeconds) return { ok: false, reason: "bolt_token_expired" };
+  if (!normalizeString(paymentPayload.txid || paymentPayload.transaction_id)) return { ok: false, reason: "bolt_txid_missing" };
+  if (
+    !normalizeString(paymentPayload.spv_proof_ref || paymentPayload.proof_bundle_ref)
+    && !normalizeString(paymentPayload.merkle_path_ref)
+    && !normalizeString(paymentPayload.block_header_ref)
+  ) {
+    return { ok: false, reason: "bolt_proof_missing" };
+  }
+  if (
+    normalizeString(paymentPayload.network)
+    && normalizeString(config && config.network)
+    && normalizeString(paymentPayload.network) !== normalizeString(config.network)
+  ) {
+    return { ok: false, reason: "bolt_network_mismatch" };
+  }
+  return { ok: true, age_seconds: ageSeconds };
+}
+
+async function verifyBoltAccessToken(headers, quote, state) {
+  // Real BSV path: when a chain provider is configured, verify an on-chain BSV
+  // payment ("BOLT <txid>") that pays the operator address >= the required amount,
+  // with single-use (per-txid) replay protection. Otherwise fall through to the
+  // existing gateway-signed token scheme below (unchanged).
+  const bsvConfig = boltAdapter.loadBoltConfig();
+  if (boltAdapter.isConfigured(bsvConfig)) {
+    const authorization = headers && typeof headers.authorization === "string" ? headers.authorization : "";
+    const parsed = boltAdapter.parseBoltHeader(authorization);
+    if (!parsed) return { ok: false, status: 402, reason: "bolt_authorization_malformed" };
+    if (state && state.acceptedPaymentNonces && state.acceptedPaymentNonces.has(parsed.txid)) {
+      return { ok: false, status: 403, reason: "bolt_txid_replayed" };
+    }
+    const requiredSats = boltAdapter.computeRequiredSats(bsvConfig, quote);
+    const result = await boltAdapter.verifyBsvPayment(bsvConfig, parsed.txid, undefined, { requiredSats });
+    if (!result.ok) return { ok: false, status: 403, reason: result.reason, detail: result.detail || null };
+    return {
+      ok: true,
+      verification_mode: "bolt_bsv_onchain",
+      wallet_id: "bolt",
+      payment_payload: {
+        nonce: result.txid,
+        txid: result.txid,
+        paid_sats: result.paid_sats,
+        confirmations: result.confirmations,
+        quote_id: quote && quote.quote_id,
+        issued_at_iso: new Date().toISOString()
+      },
+      bolt: { txid: result.txid, paid_sats: result.paid_sats, confirmations: result.confirmations, network: result.network }
+    };
+  }
+
+  const config = loadBoltFrontConfig();
+  if (!config.enabled) return { ok: false, status: 503, reason: "bolt_not_enabled" };
+  if (!config.shared_secret) return { ok: false, status: 503, reason: "bolt_shared_secret_missing" };
+  const payment = parseBoltAuthorization(headers || {});
+  if (!payment || !payment.encoded || !payment.signature) {
+    return { ok: false, status: 402, reason: "bolt_headers_incomplete" };
+  }
+  const expectedSignature = crypto.createHmac("sha256", config.shared_secret).update(payment.encoded).digest("hex");
+  if (!safeEqualHex(expectedSignature, payment.signature)) {
+    return { ok: false, status: 403, reason: "bolt_signature_invalid" };
+  }
+  const payload = decodeBase64UrlJson(payment.encoded);
+  const validation = verifyBoltPaymentPayload(payload, quote, payment.wallet_id, config.max_age_seconds, config);
+  if (!validation.ok) return { ok: false, status: 403, reason: validation.reason };
+  return {
+    ok: true,
+    verification_mode: "bolt_gateway_signed",
+    wallet_id: payment.wallet_id,
+    payment_payload: payload,
+    age_seconds: validation.age_seconds,
+    bolt: {
+      txid: payment.txid || payload.txid || payload.transaction_id || null,
+      spv_proof_ref: payment.spv_proof_ref || payload.spv_proof_ref || payload.proof_bundle_ref || null,
+      merkle_path_ref: payment.merkle_path_ref || payload.merkle_path_ref || null,
+      block_header_ref: payment.block_header_ref || payload.block_header_ref || null,
+      proof_bundle_ref: payment.proof_bundle_ref || payload.proof_bundle_ref || null,
+      network: payment.network || payload.network || config.network,
+      proof_mode: config.proof_mode
+    }
+  };
+}
+
+function buildBoltSecuritySummary() {
+  const config = loadBoltFrontConfig();
+  const blockers = [];
+  if (config.enabled && !config.shared_secret) blockers.push("bolt_shared_secret_missing");
+  return {
+    ok: true,
+    category: "machine-commerce-bolt-security-summary",
+    summary_version: "xytara-bolt-security-summary-v1",
+    enabled: config.enabled,
+    shared_secret_configured: Boolean(config.shared_secret),
+    network: config.network,
+    proof_mode: config.proof_mode,
+    max_age_seconds: config.max_age_seconds,
+    auth_scheme: config.auth_scheme,
+    token_shape: config.token_shape,
+    ready: config.enabled && blockers.length === 0,
+    blockers,
+    linked_surfaces: {
+      bolt_lane_ref: "/v1/bolt",
+      commands_execute_ref: "/bolt/commands/execute",
+      mcp_invoke_ref: "/bolt/mcp/tools/invoke"
+    }
+  };
+}
+
+function buildBoltChallengePayload(quote) {
+  // Real BSV path: advertise where to pay and how much so the caller can send a
+  // BSV transaction and retry with "BOLT <txid>".
+  const bsvConfig = boltAdapter.loadBoltConfig();
+  if (boltAdapter.isConfigured(bsvConfig) && bsvConfig.payToAddress && bsvConfig.priceSats) {
+    const requiredSats = boltAdapter.computeRequiredSats(bsvConfig, quote);
+    return {
+      ok: false,
+      payment_required: {
+        scheme: "bolt",
+        quote,
+        bsv: boltAdapter.buildBoltChallenge(bsvConfig, { requiredSats }),
+        operator_requirements: {
+          auth_scheme: "BOLT",
+          token_shape: "authorization_header_BOLT_txid",
+          security_ref: "/v1/bolt/security",
+          proof_requirements: ["pay_the_exact_amount_sats_to_address_then_present_txid"]
+        }
+      }
+    };
+  }
+  return {
+    ok: false,
+    payment_required: {
+      scheme: "bolt",
+      quote,
+      operator_requirements: {
+        auth_scheme: "BOLT",
+        token_shape: "base64url_json_with_utxo_spv_proof_and_hmac_signed_payload",
+        security_ref: "/v1/bolt/security",
+        proof_requirements: [
+          "txid",
+          "one_of:spv_proof_ref|merkle_path_ref|block_header_ref|proof_bundle_ref"
+        ]
+      }
+    }
+  };
+}
+
+module.exports = {
+  buildBoltChallengePayload,
+  buildBoltSecuritySummary,
+  loadBoltFrontConfig,
+  parseBoltAuthorization,
+  verifyBoltAccessToken
+};

package/lib/buyer_event_log.js

@@ -0,0 +1,215 @@
+"use strict";
+
+const crypto = require("crypto");
+
+// Buyer-journey event log: every failed buyer attempt (ours, upstream, or the buyer's) is recorded
+// so the operator can see who tried to use the system and why it did not work — plus counters for
+// the normal steps (402 challenges issued, paid calls served) as denominators.
+//
+// Privacy: events never carry payment signatures/headers, request bodies, tokens, IP addresses or
+// full wallet addresses. Payer addresses are reduced to a salted hash prefix; detail text is
+// truncated and stripped of long hex/base64 runs.
+//
+// Storage: state.buyerEventLog (bounded ring, newest last) and state.buyerEventDaily (per-day
+// counters, 30 days) are ordinary runtime state, so they persist with the Supabase snapshot and the
+// daily off-site backup. The MCP executor forwards its own events to POST /v1/operator/buyer-events/ingest.
+
+const DAILY_RETENTION_DAYS = 30;
+
+function maxEvents() {
+  const value = Number(process.env.XYTARA_BUYER_EVENT_LOG_MAX || 500);
+  return Number.isFinite(value) && value >= 10 ? Math.min(5000, Math.floor(value)) : 500;
+}
+
+function ensureBuyerEventCollections(state) {
+  if (!Array.isArray(state.buyerEventLog)) state.buyerEventLog = [];
+  if (!(state.buyerEventDaily instanceof Map)) state.buyerEventDaily = new Map();
+}
+
+function cleanText(value, max) {
+  if (value === null || value === undefined) return null;
+  const text = String(value)
+    .replace(/0x[0-9a-fA-F]{40,}/g, "0x…")
+    .replace(/[A-Za-z0-9+/=_-]{40,}/g, "…")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text ? text.slice(0, max) : null;
+}
+
+function payerHash(address) {
+  const value = String(address || "").trim().toLowerCase();
+  if (!value) return null;
+  const salt = String(process.env.XYTARA_BUYER_EVENT_SALT || "naxytra-buyer-events");
+  return crypto.createHash("sha256").update(`${salt}:${value}`).digest("hex").slice(0, 12);
+}
+
+// Path template without ids: segments that look like identifiers become ":id".
+function routeTemplate(pathname) {
+  return String(pathname || "/")
+    .split("/")
+    .map((segment) => (/(^0x[0-9a-f]{6,})|([0-9a-f]{12,})|(_[0-9a-z]{6,}$)|(^\d{3,}$)/i.test(segment) ? ":id" : segment))
+    .join("/")
+    .slice(0, 120);
+}
+
+// reason -> [stage, fault]. fault: "ours" (our bug/infra), "upstream" (facilitator, RPC, provider),
+// "buyer" (bad input / bad payment), "none" (expected protocol step).
+const REASON_RULES = [
+  [/^(capability_not_executable|task_ref_required|task_not_found|unknown_tool)/, "route", "buyer"],
+  [/^(body_must_be_valid_json|invalid_json|request_body_too_large)/, "parse", "buyer"],
+  [/^payment_(signature_invalid|requirements_mismatch|header)/, "payment_match", "buyer"],
+  [/^payment_authorization_in_progress/, "payment_verify", "buyer"],
+  [/^payment_verification_failed|^invalid_exact/, "payment_verify", "buyer"],
+  [/^facilitator_|_unreachable$/, "payment_verify", "upstream"],
+  [/^(payment_settlement_failed|settlement_failed|settle_)/, "payment_settle", "upstream"],
+  [/^(external_execution|no_healthy_provider|provider_)/, "provider", "upstream"],
+  [/^(insufficient_credits|credit_spend_|delegated_)/, "credit", "buyer"],
+  [/^agent_signature|^spend_credential|_bearer|^unauthorized|^forbidden/, "auth", "buyer"],
+  [/^rate_limit/, "rate_limit", "buyer"],
+  [/^(state_restore_pending|runtime_state)/, "state", "ours"],
+  [/^quote_(expired|already_used)/, "quote", "buyer"]
+];
+
+function classify(reason, httpStatus) {
+  const text = String(reason || "");
+  for (const [pattern, stage, fault] of REASON_RULES) {
+    if (pattern.test(text)) return { stage, fault };
+  }
+  if (httpStatus >= 500) return { stage: "internal", fault: "ours" };
+  if (httpStatus === 404) return { stage: "route", fault: "buyer" };
+  return { stage: "other", fault: httpStatus >= 400 && httpStatus < 500 ? "buyer" : "ours" };
+}
+
+function dayKey(iso) {
+  return String(iso).slice(0, 10);
+}
+
+function bumpDaily(state, iso, service, key) {
+  const day = dayKey(iso);
+  let bucket = state.buyerEventDaily.get(day);
+  if (!bucket) {
+    bucket = {};
+    state.buyerEventDaily.set(day, bucket);
+    // Drop days beyond retention (keys are ISO dates, so lexical order is chronological).
+    const days = Array.from(state.buyerEventDaily.keys()).sort();
+    while (days.length > DAILY_RETENTION_DAYS) state.buyerEventDaily.delete(days.shift());
+  }
+  const counterKey = `${service}|${key}`;
+  bucket[counterKey] = (Number(bucket[counterKey]) || 0) + 1;
+}
+
+// Count a normal step without logging an event (challenge issued, paid call served, ...).
+function countBuyerStep(state, step, options = {}) {
+  try {
+    ensureBuyerEventCollections(state);
+    bumpDaily(state, new Date().toISOString(), options.service || "runtime", `step:${step}|${routeTemplate(options.route)}`);
+  } catch (_) { /* observability must never break a buyer response */ }
+}
+
+function recordBuyerEvent(state, input) {
+  try {
+    ensureBuyerEventCollections(state);
+    const at = typeof input.at_iso === "string" && !Number.isNaN(Date.parse(input.at_iso)) ? new Date(input.at_iso).toISOString() : new Date().toISOString();
+    const httpStatus = Number.isFinite(Number(input.http_status)) ? Number(input.http_status) : null;
+    const reason = cleanText(input.reason, 80) || (httpStatus ? `http_${httpStatus}` : "unknown");
+    const classified = classify(reason, httpStatus || 0);
+    const event = {
+      id: `bev_${crypto.randomBytes(6).toString("hex")}`,
+      at_iso: at,
+      service: cleanText(input.service, 40) || "runtime",
+      request_id: cleanText(input.request_id, 40),
+      stage: cleanText(input.stage, 30) || classified.stage,
+      reason,
+      fault: cleanText(input.fault, 10) || classified.fault,
+      http_status: httpStatus,
+      route: input.route ? routeTemplate(input.route) : null,
+      method: cleanText(input.method, 8),
+      task_or_tool: cleanText(input.task_or_tool, 80),
+      rail: cleanText(input.rail, 20),
+      network: cleanText(input.network, 30),
+      amount_atomic: /^\d{1,30}$/.test(String(input.amount_atomic || "")) ? String(input.amount_atomic) : null,
+      payer_hash: input.payer_hash ? cleanText(input.payer_hash, 16) : payerHash(input.payer),
+      money_moved: input.money_moved === true,
+      latency_ms: Number.isFinite(Number(input.latency_ms)) ? Math.round(Number(input.latency_ms)) : null,
+      detail: cleanText(input.detail, 160),
+      ua: cleanText(String(input.ua || "").split(/[\s/]/)[0], 32)
+    };
+    state.buyerEventLog.push(event);
+    const cap = maxEvents();
+    if (state.buyerEventLog.length > cap) state.buyerEventLog.splice(0, state.buyerEventLog.length - cap);
+    bumpDaily(state, at, event.service, `fail:${event.stage}:${event.reason}:${event.fault}`);
+    if (event.money_moved) bumpDaily(state, at, event.service, "money_moved");
+    return event;
+  } catch (_) {
+    return null;
+  }
+}
+
+function listBuyerEvents(state, query = {}) {
+  ensureBuyerEventCollections(state);
+  const since = query.since && !Number.isNaN(Date.parse(query.since)) ? Date.parse(query.since) : null;
+  const limit = Math.max(1, Math.min(500, Number(query.limit) || 100));
+  const matches = state.buyerEventLog.filter((event) => {
+    if (since !== null && Date.parse(event.at_iso) < since) return false;
+    if (query.service && event.service !== query.service) return false;
+    if (query.stage && event.stage !== query.stage) return false;
+    if (query.fault && event.fault !== query.fault) return false;
+    if (query.money_moved === "true" && !event.money_moved) return false;
+    return true;
+  });
+  return { count: matches.length, events: matches.slice(-limit).reverse() };
+}
+
+function summarizeBuyerEvents(state, days = 7) {
+  ensureBuyerEventCollections(state);
+  const window = Math.max(1, Math.min(DAILY_RETENTION_DAYS, Number(days) || 7));
+  const keys = Array.from(state.buyerEventDaily.keys()).sort().slice(-window);
+  const totals = { failures: 0, ours: 0, upstream: 0, buyer: 0, money_moved: 0, challenges_issued: 0, paid_ok: 0 };
+  const byReason = {};
+  const perDay = keys.map((day) => {
+    const bucket = state.buyerEventDaily.get(day) || {};
+    const dayTotals = { day, failures: 0, ours: 0, upstream: 0, money_moved: 0, challenges_issued: 0, paid_ok: 0 };
+    for (const [key, count] of Object.entries(bucket)) {
+      const [service, rest] = [key.slice(0, key.indexOf("|")), key.slice(key.indexOf("|") + 1)];
+      if (rest === "money_moved") { dayTotals.money_moved += count; totals.money_moved += count; continue; }
+      if (rest.startsWith("step:challenge_issued")) { dayTotals.challenges_issued += count; totals.challenges_issued += count; continue; }
+      if (rest.startsWith("step:paid_ok")) { dayTotals.paid_ok += count; totals.paid_ok += count; continue; }
+      if (!rest.startsWith("fail:")) continue;
+      const [, stage, reason, fault] = rest.split(":");
+      dayTotals.failures += count;
+      totals.failures += count;
+      if (fault === "ours") { dayTotals.ours += count; totals.ours += count; }
+      if (fault === "upstream") { dayTotals.upstream += count; totals.upstream += count; }
+      if (fault === "buyer") totals.buyer += count;
+      const reasonKey = `${service}:${stage}:${reason}:${fault}`;
+      byReason[reasonKey] = (byReason[reasonKey] || 0) + count;
+    }
+    return dayTotals;
+  });
+  const topReasons = Object.entries(byReason)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 25)
+    .map(([key, count]) => {
+      const [service, stage, reason, fault] = key.split(":");
+      return { service, stage, reason, fault, count };
+    });
+  return {
+    window_days: window,
+    totals,
+    // Needs attention: money moved without a delivered result, or failures that are our fault.
+    attention: totals.money_moved > 0 || totals.ours > 0,
+    per_day: perDay,
+    top_reasons: topReasons,
+    generated_at_iso: new Date().toISOString()
+  };
+}
+
+module.exports = {
+  countBuyerStep,
+  ensureBuyerEventCollections,
+  listBuyerEvents,
+  payerHash,
+  recordBuyerEvent,
+  routeTemplate,
+  summarizeBuyerEvents
+};