xytara 3.1.13 → 3.1.15

package/lib/buyer_safety_policy.js

@@ -0,0 +1,132 @@
+"use strict";
+
+// Money-safety policy for the buyer path. Like the provider endpoint policy, each rule is
+// "strict" by default on a hosted deploy (RENDER is set) and "permissive" locally, so the local
+// verification suites (which exercise catalog tasks without a live execution target) keep working.
+//
+//  - Paid execution: only a task that resolves to a REAL execution target (an operator-pinned
+//    env target or an active open-network provider) may be quoted for payment. Anything else is
+//    refused up front with capability_not_executable, so a buyer is never charged for a
+//    synthetic result. (XYTARA_PAID_EXECUTION_POLICY=strict|permissive)
+//  - Credit spend: spending an account's credits requires a spend credential (xytara_spend_…
+//    bearer) bound to that account. A bare account_id is never authority — payer addresses are
+//    public on-chain. (XYTARA_CREDIT_SPEND_POLICY=strict|permissive)
+
+function policyMode(envName) {
+  const raw = String(process.env[envName] || "").trim().toLowerCase();
+  if (raw === "strict" || raw === "permissive") return raw;
+  return process.env.RENDER ? "strict" : "permissive";
+}
+
+function paidExecutionPolicyMode() {
+  return policyMode("XYTARA_PAID_EXECUTION_POLICY");
+}
+
+function creditSpendPolicyMode() {
+  return policyMode("XYTARA_CREDIT_SPEND_POLICY");
+}
+
+// Ledger/business reads (payer addresses, every quote, receipts, operations, revenue metrics) are
+// operator-only on a hosted deploy. (XYTARA_LEDGER_READ_POLICY=strict|permissive)
+function ledgerReadPolicyMode() {
+  return policyMode("XYTARA_LEDGER_READ_POLICY");
+}
+
+const PRIVATE_READ_PREFIXES = [
+  "/v1/payment-ledger",
+  "/v1/operator-export-pack",
+  "/v1/receipts",
+  "/v1/operations/",
+  "/v1/economics/accounts/",
+  "/v1/pricing-optimization/",
+  "/v1/revenue-signal",
+  "/v1/activity-ledger"
+];
+
+// Whether a GET is a private ledger read. A single quote by id stays public (its holder needs it).
+function isPrivateLedgerRead(method, pathname) {
+  if (String(method || "").toUpperCase() !== "GET") return false;
+  if (pathname === "/v1/payment-quotes") return true;
+  return PRIVATE_READ_PREFIXES.some((prefix) => pathname === prefix || pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`) || pathname.startsWith(`${prefix}-`));
+}
+
+// Test networks: their USDC is free from faucets, so by default it cannot buy credits that are
+// spendable on real (mainnet-paid-out) provider work. Pay-per-call on a testnet is unaffected.
+const TESTNET_NETWORKS = new Set(["eip155:84532", "eip155:11155111"]);
+
+function isTestnetNetwork(network) {
+  return TESTNET_NETWORKS.has(String(network || "").trim().toLowerCase());
+}
+
+// What one credit unit costs, in the payment asset's base units (USDC: 6 decimals). Default
+// 2500 = $0.0025, so a decision-support call (3 units) costs $0.0075 — never more than the flat
+// pay-per-call price for the executable lanes.
+function creditUnitPriceAtomic() {
+  const value = Number(process.env.XYTARA_CREDIT_UNIT_PRICE_ATOMIC || 2500);
+  return Number.isFinite(value) && value >= 1 ? Math.floor(value) : 2500;
+}
+
+// A top-up is priced as a multiple of the per-call accepts amount (default 100x: $0.01 -> $1.00).
+function topupAmountMultiplier() {
+  const value = Number(process.env.XYTARA_X402_TOPUP_AMOUNT_MULTIPLIER || 100);
+  return Number.isFinite(value) && value >= 1 ? Math.floor(value) : 100;
+}
+
+// The accepts a credit top-up is paid with: mainnet-only unless testnet top-ups are explicitly
+// enabled, each amount scaled to the top-up price.
+function buildTopupAccepts(accepts) {
+  const allowTestnet = String(process.env.XYTARA_X402_TESTNET_TOPUP || "").trim() === "1";
+  const multiplier = BigInt(topupAmountMultiplier());
+  return (Array.isArray(accepts) ? accepts : [])
+    .filter((accept) => accept && (allowTestnet || !isTestnetNetwork(accept.network)))
+    .filter((accept) => /^\d{1,30}$/.test(String(accept.amount)))
+    .map((accept) => ({ ...accept, amount: (BigInt(String(accept.amount)) * multiplier).toString() }));
+}
+
+// Credits granted for a settled top-up: always derived from what was actually paid, so a unit is
+// never worth less than creditUnitPriceAtomic(). An accepts entry's own extra.credits may lower
+// that, never raise it.
+function topupUnitsForAccept(accept) {
+  const amount = accept && /^\d{1,30}$/.test(String(accept.amount)) ? Number(accept.amount) : 0;
+  const derived = Math.floor(amount / creditUnitPriceAtomic());
+  const explicit = accept && accept.extra ? Number(accept.extra.credits) : NaN;
+  return Number.isFinite(explicit) && explicit > 0 ? Math.min(Math.floor(explicit), derived) : derived;
+}
+
+// While the durable state has not been restored yet (boot, or a Supabase outage), balances read
+// as empty: a credit spend would wrongly say "insufficient credits" and a top-up could be lost if
+// the process died before the restore merged. Those routes answer 503 + Retry-After instead.
+let stateRestorePendingProbe = () => false;
+
+function setStateRestorePendingProbe(probe) {
+  stateRestorePendingProbe = typeof probe === "function" ? probe : () => false;
+}
+
+function isStateRestorePending() {
+  try {
+    return stateRestorePendingProbe() === true;
+  } catch (_) {
+    return false;
+  }
+}
+
+const STATE_RESTORE_PENDING_RESPONSE = Object.freeze({
+  ok: false,
+  reason: "state_restore_pending",
+  detail: "Account balances are being restored after a restart. Retry in about 30 seconds; nothing was charged. Pay-per-call x402 (without payment_preference) works meanwhile."
+});
+
+module.exports = {
+  STATE_RESTORE_PENDING_RESPONSE,
+  isPrivateLedgerRead,
+  ledgerReadPolicyMode,
+  isStateRestorePending,
+  setStateRestorePendingProbe,
+  paidExecutionPolicyMode,
+  creditSpendPolicyMode,
+  isTestnetNetwork,
+  creditUnitPriceAtomic,
+  topupAmountMultiplier,
+  buildTopupAccepts,
+  topupUnitsForAccept
+};

package/lib/checkout_processor_adapter.js

@@ -1,217 +1,217 @@
-"use strict";
-
-// Provider-agnostic hosted-checkout processor adapter (fiat money-in).
-//
-// Turns the synthetic hosted-checkout scaffold into a real fiat rail WITHOUT
-// provider lock-in and WITHOUT changing existing behavior: it engages only when
-// env configures a processor. When unconfigured, every function reports
-// "not configured" and the caller preserves the current synthetic flow.
-//
-// First provider: Stripe (Checkout Sessions + webhooks). Dependency-free
-// (node https + crypto). To add another processor, extend the provider
-// switches below; nothing else changes.
-//
-// Env:
-//   XYTARA_CHECKOUT_PROCESSOR = "stripe"   (unset/empty => not configured)
-//   STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
-//   XYTARA_CHECKOUT_SUCCESS_URL, XYTARA_CHECKOUT_CANCEL_URL
-//   XYTARA_CHECKOUT_PRODUCT_NAME (optional), STRIPE_WEBHOOK_TOLERANCE_SECONDS (optional)
-
-const https = require("https");
-const crypto = require("crypto");
-
-function env(name) {
-  const v = process.env[name];
-  return typeof v === "string" && v.trim() ? v.trim() : "";
-}
-
-function loadCheckoutProcessorConfig() {
-  const provider = env("XYTARA_CHECKOUT_PROCESSOR").toLowerCase();
-  if (provider === "stripe") {
-    return {
-      provider: "stripe",
-      secretKey: env("STRIPE_SECRET_KEY"),
-      webhookSecret: env("STRIPE_WEBHOOK_SECRET"),
-      successUrl: env("XYTARA_CHECKOUT_SUCCESS_URL") || env("STRIPE_SUCCESS_URL"),
-      cancelUrl: env("XYTARA_CHECKOUT_CANCEL_URL") || env("STRIPE_CANCEL_URL"),
-      productName: env("XYTARA_CHECKOUT_PRODUCT_NAME") || "naxytra runtime credits",
-      webhookToleranceSeconds: Math.max(60, Number(env("STRIPE_WEBHOOK_TOLERANCE_SECONDS") || 300) || 300)
-    };
-  }
-  return { provider: null };
-}
-
-function isConfigured(config) {
-  return Boolean(config && config.provider);
-}
-
-function normalizeCurrency(currency) {
-  const c = String(currency || "usd").toLowerCase();
-  // The runtime books some prices as USD_CENTS; the minor-unit amount is already
-  // in cents, so the processor currency is plain "usd".
-  return c === "usd_cents" ? "usd" : c;
-}
-
-// Minimal form-encoded POST to Stripe. Resolves { status, json, raw }.
-function stripePost(path, formParams, secretKey, timeoutMs) {
-  const body = new URLSearchParams(formParams).toString();
-  return new Promise((resolve, reject) => {
-    const req = https.request(
-      {
-        method: "POST",
-        hostname: "api.stripe.com",
-        path,
-        headers: {
-          Authorization: "Bearer " + secretKey,
-          "Content-Type": "application/x-www-form-urlencoded",
-          "Content-Length": Buffer.byteLength(body)
-        }
-      },
-      (res) => {
-        let data = "";
-        res.on("data", (chunk) => {
-          data += chunk;
-        });
-        res.on("end", () => {
-          let json = null;
-          try {
-            json = data ? JSON.parse(data) : null;
-          } catch (_) {
-            json = null;
-          }
-          resolve({ status: res.statusCode, json, raw: data });
-        });
-      }
-    );
-    req.on("error", reject);
-    req.setTimeout(timeoutMs || 15000, () => {
-      req.destroy(new Error("stripe_request_timeout"));
-    });
-    req.write(body);
-    req.end();
-  });
-}
-
-// Create a real processor checkout session for a purchase intent.
-// `intent` = { amountMinor, currency, units, accountId, purchaseIntentId, successUrl?, cancelUrl? }
-// Returns { ok, checkout_url, checkout_reference, checkout_provider } | { ok:false, reason, detail? }.
-async function createProcessorCheckoutSession(config, intent) {
-  if (!isConfigured(config)) return { ok: false, reason: "processor_not_configured" };
-  if (config.provider === "stripe") {
-    if (!config.secretKey) return { ok: false, reason: "stripe_secret_key_missing" };
-    const amountMinor = Number(intent && intent.amountMinor);
-    if (!Number.isFinite(amountMinor) || amountMinor <= 0) return { ok: false, reason: "invalid_amount" };
-    const successUrl = (intent && intent.successUrl) || config.successUrl;
-    const cancelUrl = (intent && intent.cancelUrl) || config.cancelUrl;
-    if (!successUrl || !cancelUrl) return { ok: false, reason: "success_or_cancel_url_missing" };
-    const params = {
-      mode: "payment",
-      success_url: successUrl,
-      cancel_url: cancelUrl,
-      "line_items[0][quantity]": "1",
-      "line_items[0][price_data][currency]": normalizeCurrency(intent.currency),
-      "line_items[0][price_data][unit_amount]": String(Math.round(amountMinor)),
-      "line_items[0][price_data][product_data][name]": config.productName,
-      "metadata[purchase_intent_id]": String((intent && intent.purchaseIntentId) || ""),
-      "metadata[account_id]": String((intent && intent.accountId) || ""),
-      "metadata[credits_units]": String((intent && intent.units) || "")
-    };
-    let res;
-    try {
-      res = await stripePost("/v1/checkout/sessions", params, config.secretKey, 15000);
-    } catch (e) {
-      return { ok: false, reason: "stripe_unreachable", detail: e && e.message ? e.message : "request_error" };
-    }
-    if (!res.json || res.status >= 400) {
-      const detail = res.json && res.json.error ? res.json.error.message : `HTTP ${res.status}`;
-      return { ok: false, reason: "stripe_session_create_failed", detail };
-    }
-    return { ok: true, checkout_url: res.json.url, checkout_reference: res.json.id, checkout_provider: "stripe" };
-  }
-  return { ok: false, reason: "unsupported_processor" };
-}
-
-// Verify a processor webhook request. Returns { ok, event } | { ok:false, reason }.
-// Uses the PROCESSOR's own signature scheme (Stripe: Stripe-Signature "t=,v1=").
-function verifyProcessorWebhook(config, headers, rawBody) {
-  if (!isConfigured(config)) return { ok: false, reason: "processor_not_configured" };
-  if (config.provider === "stripe") {
-    if (!config.webhookSecret) return { ok: false, reason: "stripe_webhook_secret_missing" };
-    const lower = {};
-    for (const k in headers || {}) lower[k.toLowerCase()] = headers[k];
-    const sigHeader = String(lower["stripe-signature"] || "");
-    const parts = {};
-    sigHeader.split(",").forEach((piece) => {
-      const idx = piece.indexOf("=");
-      if (idx === -1) return;
-      const k = piece.slice(0, idx).trim();
-      const v = piece.slice(idx + 1).trim();
-      (parts[k] = parts[k] || []).push(v);
-    });
-    const t = parts.t && parts.t[0];
-    const v1s = parts.v1 || [];
-    if (!t || !v1s.length) return { ok: false, reason: "stripe_signature_malformed" };
-    const ageSeconds = Math.abs(Date.now() / 1000 - Number(t));
-    if (!Number.isFinite(ageSeconds) || ageSeconds > config.webhookToleranceSeconds) {
-      return { ok: false, reason: "stripe_timestamp_out_of_tolerance" };
-    }
-    const expected = crypto.createHmac("sha256", config.webhookSecret).update(`${t}.${rawBody}`, "utf8").digest("hex");
-    const match = v1s.some((v) => {
-      try {
-        return v.length === expected.length && crypto.timingSafeEqual(Buffer.from(v, "hex"), Buffer.from(expected, "hex"));
-      } catch (_) {
-        return false;
-      }
-    });
-    if (!match) return { ok: false, reason: "stripe_signature_invalid" };
-    let event = null;
-    try {
-      event = JSON.parse(rawBody);
-    } catch (_) {
-      return { ok: false, reason: "stripe_body_not_json" };
-    }
-    return { ok: true, event };
-  }
-  return { ok: false, reason: "unsupported_processor" };
-}
-
-// Build the Stripe-Signature header value for a raw body (used by tests and by
-// anyone generating a signed event). Not used in production verification.
-function buildStripeSignatureHeader(webhookSecret, rawBody, timestampSeconds) {
-  const t = String(timestampSeconds || Math.floor(Date.now() / 1000));
-  const v1 = crypto.createHmac("sha256", webhookSecret).update(`${t}.${rawBody}`, "utf8").digest("hex");
-  return `t=${t},v1=${v1}`;
-}
-
-// Translate a verified webhook event into a credit-grant body (matches
-// createExternalCreditGrant), or null when it is not a completed payment.
-function mapProcessorEventToGrant(config, event) {
-  if (!isConfigured(config) || !event || typeof event !== "object") return null;
-  if (config.provider === "stripe") {
-    if (event.type !== "checkout.session.completed") return null;
-    const s = (event.data && event.data.object) || {};
-    if (s.payment_status !== "paid") return null;
-    const md = s.metadata || {};
-    return {
-      account_id: md.account_id || null,
-      units: Number(md.credits_units) || null,
-      source: "stripe",
-      provider_reference: s.payment_intent || s.id || null,
-      idempotency_key: "stripe:" + (event.id || s.id),
-      amount_minor: Number(s.amount_total),
-      currency: String(s.currency || "usd").toUpperCase(),
-      purchase_intent_id: md.purchase_intent_id || null,
-      metadata: { processor: "stripe", checkout_session_id: s.id, event_id: event.id }
-    };
-  }
-  return null;
-}
-
-module.exports = {
-  loadCheckoutProcessorConfig,
-  isConfigured,
-  createProcessorCheckoutSession,
-  verifyProcessorWebhook,
-  buildStripeSignatureHeader,
-  mapProcessorEventToGrant
-};
+"use strict";
+
+// Provider-agnostic hosted-checkout processor adapter (fiat money-in).
+//
+// Turns the synthetic hosted-checkout scaffold into a real fiat rail WITHOUT
+// provider lock-in and WITHOUT changing existing behavior: it engages only when
+// env configures a processor. When unconfigured, every function reports
+// "not configured" and the caller preserves the current synthetic flow.
+//
+// First provider: Stripe (Checkout Sessions + webhooks). Dependency-free
+// (node https + crypto). To add another processor, extend the provider
+// switches below; nothing else changes.
+//
+// Env:
+//   XYTARA_CHECKOUT_PROCESSOR = "stripe"   (unset/empty => not configured)
+//   STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
+//   XYTARA_CHECKOUT_SUCCESS_URL, XYTARA_CHECKOUT_CANCEL_URL
+//   XYTARA_CHECKOUT_PRODUCT_NAME (optional), STRIPE_WEBHOOK_TOLERANCE_SECONDS (optional)
+
+const https = require("https");
+const crypto = require("crypto");
+
+function env(name) {
+  const v = process.env[name];
+  return typeof v === "string" && v.trim() ? v.trim() : "";
+}
+
+function loadCheckoutProcessorConfig() {
+  const provider = env("XYTARA_CHECKOUT_PROCESSOR").toLowerCase();
+  if (provider === "stripe") {
+    return {
+      provider: "stripe",
+      secretKey: env("STRIPE_SECRET_KEY"),
+      webhookSecret: env("STRIPE_WEBHOOK_SECRET"),
+      successUrl: env("XYTARA_CHECKOUT_SUCCESS_URL") || env("STRIPE_SUCCESS_URL"),
+      cancelUrl: env("XYTARA_CHECKOUT_CANCEL_URL") || env("STRIPE_CANCEL_URL"),
+      productName: env("XYTARA_CHECKOUT_PRODUCT_NAME") || "naxytra runtime credits",
+      webhookToleranceSeconds: Math.max(60, Number(env("STRIPE_WEBHOOK_TOLERANCE_SECONDS") || 300) || 300)
+    };
+  }
+  return { provider: null };
+}
+
+function isConfigured(config) {
+  return Boolean(config && config.provider);
+}
+
+function normalizeCurrency(currency) {
+  const c = String(currency || "usd").toLowerCase();
+  // The runtime books some prices as USD_CENTS; the minor-unit amount is already
+  // in cents, so the processor currency is plain "usd".
+  return c === "usd_cents" ? "usd" : c;
+}
+
+// Minimal form-encoded POST to Stripe. Resolves { status, json, raw }.
+function stripePost(path, formParams, secretKey, timeoutMs) {
+  const body = new URLSearchParams(formParams).toString();
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      {
+        method: "POST",
+        hostname: "api.stripe.com",
+        path,
+        headers: {
+          Authorization: "Bearer " + secretKey,
+          "Content-Type": "application/x-www-form-urlencoded",
+          "Content-Length": Buffer.byteLength(body)
+        }
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => {
+          data += chunk;
+        });
+        res.on("end", () => {
+          let json = null;
+          try {
+            json = data ? JSON.parse(data) : null;
+          } catch (_) {
+            json = null;
+          }
+          resolve({ status: res.statusCode, json, raw: data });
+        });
+      }
+    );
+    req.on("error", reject);
+    req.setTimeout(timeoutMs || 15000, () => {
+      req.destroy(new Error("stripe_request_timeout"));
+    });
+    req.write(body);
+    req.end();
+  });
+}
+
+// Create a real processor checkout session for a purchase intent.
+// `intent` = { amountMinor, currency, units, accountId, purchaseIntentId, successUrl?, cancelUrl? }
+// Returns { ok, checkout_url, checkout_reference, checkout_provider } | { ok:false, reason, detail? }.
+async function createProcessorCheckoutSession(config, intent) {
+  if (!isConfigured(config)) return { ok: false, reason: "processor_not_configured" };
+  if (config.provider === "stripe") {
+    if (!config.secretKey) return { ok: false, reason: "stripe_secret_key_missing" };
+    const amountMinor = Number(intent && intent.amountMinor);
+    if (!Number.isFinite(amountMinor) || amountMinor <= 0) return { ok: false, reason: "invalid_amount" };
+    const successUrl = (intent && intent.successUrl) || config.successUrl;
+    const cancelUrl = (intent && intent.cancelUrl) || config.cancelUrl;
+    if (!successUrl || !cancelUrl) return { ok: false, reason: "success_or_cancel_url_missing" };
+    const params = {
+      mode: "payment",
+      success_url: successUrl,
+      cancel_url: cancelUrl,
+      "line_items[0][quantity]": "1",
+      "line_items[0][price_data][currency]": normalizeCurrency(intent.currency),
+      "line_items[0][price_data][unit_amount]": String(Math.round(amountMinor)),
+      "line_items[0][price_data][product_data][name]": config.productName,
+      "metadata[purchase_intent_id]": String((intent && intent.purchaseIntentId) || ""),
+      "metadata[account_id]": String((intent && intent.accountId) || ""),
+      "metadata[credits_units]": String((intent && intent.units) || "")
+    };
+    let res;
+    try {
+      res = await stripePost("/v1/checkout/sessions", params, config.secretKey, 15000);
+    } catch (e) {
+      return { ok: false, reason: "stripe_unreachable", detail: e && e.message ? e.message : "request_error" };
+    }
+    if (!res.json || res.status >= 400) {
+      const detail = res.json && res.json.error ? res.json.error.message : `HTTP ${res.status}`;
+      return { ok: false, reason: "stripe_session_create_failed", detail };
+    }
+    return { ok: true, checkout_url: res.json.url, checkout_reference: res.json.id, checkout_provider: "stripe" };
+  }
+  return { ok: false, reason: "unsupported_processor" };
+}
+
+// Verify a processor webhook request. Returns { ok, event } | { ok:false, reason }.
+// Uses the PROCESSOR's own signature scheme (Stripe: Stripe-Signature "t=,v1=").
+function verifyProcessorWebhook(config, headers, rawBody) {
+  if (!isConfigured(config)) return { ok: false, reason: "processor_not_configured" };
+  if (config.provider === "stripe") {
+    if (!config.webhookSecret) return { ok: false, reason: "stripe_webhook_secret_missing" };
+    const lower = {};
+    for (const k in headers || {}) lower[k.toLowerCase()] = headers[k];
+    const sigHeader = String(lower["stripe-signature"] || "");
+    const parts = {};
+    sigHeader.split(",").forEach((piece) => {
+      const idx = piece.indexOf("=");
+      if (idx === -1) return;
+      const k = piece.slice(0, idx).trim();
+      const v = piece.slice(idx + 1).trim();
+      (parts[k] = parts[k] || []).push(v);
+    });
+    const t = parts.t && parts.t[0];
+    const v1s = parts.v1 || [];
+    if (!t || !v1s.length) return { ok: false, reason: "stripe_signature_malformed" };
+    const ageSeconds = Math.abs(Date.now() / 1000 - Number(t));
+    if (!Number.isFinite(ageSeconds) || ageSeconds > config.webhookToleranceSeconds) {
+      return { ok: false, reason: "stripe_timestamp_out_of_tolerance" };
+    }
+    const expected = crypto.createHmac("sha256", config.webhookSecret).update(`${t}.${rawBody}`, "utf8").digest("hex");
+    const match = v1s.some((v) => {
+      try {
+        return v.length === expected.length && crypto.timingSafeEqual(Buffer.from(v, "hex"), Buffer.from(expected, "hex"));
+      } catch (_) {
+        return false;
+      }
+    });
+    if (!match) return { ok: false, reason: "stripe_signature_invalid" };
+    let event = null;
+    try {
+      event = JSON.parse(rawBody);
+    } catch (_) {
+      return { ok: false, reason: "stripe_body_not_json" };
+    }
+    return { ok: true, event };
+  }
+  return { ok: false, reason: "unsupported_processor" };
+}
+
+// Build the Stripe-Signature header value for a raw body (used by tests and by
+// anyone generating a signed event). Not used in production verification.
+function buildStripeSignatureHeader(webhookSecret, rawBody, timestampSeconds) {
+  const t = String(timestampSeconds || Math.floor(Date.now() / 1000));
+  const v1 = crypto.createHmac("sha256", webhookSecret).update(`${t}.${rawBody}`, "utf8").digest("hex");
+  return `t=${t},v1=${v1}`;
+}
+
+// Translate a verified webhook event into a credit-grant body (matches
+// createExternalCreditGrant), or null when it is not a completed payment.
+function mapProcessorEventToGrant(config, event) {
+  if (!isConfigured(config) || !event || typeof event !== "object") return null;
+  if (config.provider === "stripe") {
+    if (event.type !== "checkout.session.completed") return null;
+    const s = (event.data && event.data.object) || {};
+    if (s.payment_status !== "paid") return null;
+    const md = s.metadata || {};
+    return {
+      account_id: md.account_id || null,
+      units: Number(md.credits_units) || null,
+      source: "stripe",
+      provider_reference: s.payment_intent || s.id || null,
+      idempotency_key: "stripe:" + (event.id || s.id),
+      amount_minor: Number(s.amount_total),
+      currency: String(s.currency || "usd").toUpperCase(),
+      purchase_intent_id: md.purchase_intent_id || null,
+      metadata: { processor: "stripe", checkout_session_id: s.id, event_id: event.id }
+    };
+  }
+  return null;
+}
+
+module.exports = {
+  loadCheckoutProcessorConfig,
+  isConfigured,
+  createProcessorCheckoutSession,
+  verifyProcessorWebhook,
+  buildStripeSignatureHeader,
+  mapProcessorEventToGrant
+};