xytara 3.1.13 → 3.1.14

package/lib/x402_facilitator.js

@@ -1,191 +1,191 @@
-"use strict";
-
-const { buildCdpBearerToken } = require("./cdp_jwt");
-
-// Self-contained x402 v2 facilitator client for the main runtime.
-//
-// This mirrors the proven logic in services/mcp-execution-target/server.js but takes
-// all configuration as explicit arguments so it has no dependency on any global state
-// and can be reused by any paid route. It is intentionally duplicated rather than shared
-// with the standalone MCP executor, which deploys from its own subdirectory.
-//
-// The trust model is the same one proven live: this process never verifies balances or
-// broadcasts transfers itself. It asks an x402 facilitator to verify the buyer's signed
-// EIP-3009 authorization and to settle it on-chain, and refuses to serve work unless the
-// facilitator confirms both. If the facilitator is unreachable, access fails closed.
-
-function normalizeString(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function normalizeAddress(value) {
-  return normalizeString(value).toLowerCase();
-}
-
-// Decode a PAYMENT-SIGNATURE header into an x402 v2 payment payload.
-function decodePaymentSignatureHeader(value) {
-  const raw = normalizeString(value);
-  if (!raw) return null;
-  for (const encoding of ["base64url", "base64"]) {
-    try {
-      const decoded = Buffer.from(raw, encoding).toString("utf8");
-      const parsed = JSON.parse(decoded);
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
-      if (Number(parsed.x402Version) !== 2) continue;
-      if (!parsed.accepted || typeof parsed.accepted !== "object") continue;
-      if (!parsed.payload || typeof parsed.payload !== "object") continue;
-      return parsed;
-    } catch (_) {
-      // try the next encoding
-    }
-  }
-  return null;
-}
-
-// Find the advertised requirements entry the buyer claims to be paying.
-function matchAcceptedRequirements(paymentPayload, accepts) {
-  const accepted = paymentPayload && paymentPayload.accepted ? paymentPayload.accepted : null;
-  if (!accepted || !Array.isArray(accepts)) return null;
-  return (
-    accepts.find(
-      (entry) =>
-        entry.scheme === normalizeString(accepted.scheme) &&
-        entry.network === normalizeString(accepted.network) &&
-        normalizeAddress(entry.asset) === normalizeAddress(accepted.asset) &&
-        normalizeAddress(entry.payTo) === normalizeAddress(accepted.payTo) &&
-        String(entry.amount) === String(accepted.amount)
-    ) || null
-  );
-}
-
-function createFacilitatorClient(config) {
-  const url = normalizeString(config && config.url).replace(/\/$/, "");
-  const headers = config && config.headers && typeof config.headers === "object" ? config.headers : {};
-  const timeoutMs = Math.max(1000, Number(config && config.timeoutMs) || 15000);
-  // Optional Coinbase CDP auth: when a CDP Secret API Key is configured, a fresh short-lived
-  // EdDSA Bearer JWT is minted per request (CDP rejects static tokens). This is what unlocks
-  // the CDP-hosted facilitator and Base mainnet settlement.
-  const cdp = config && config.cdp && typeof config.cdp === "object" ? config.cdp : null;
-  const cdpKeyId = cdp ? normalizeString(cdp.key_id || cdp.keyId) : "";
-  const cdpKeySecret = cdp ? String((cdp.key_secret || cdp.keySecret) || "").trim() : "";
-  const cdpEnabled = Boolean(cdpKeyId && cdpKeySecret);
-
-  async function post(path, body) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    let authHeaders = {};
-    if (cdpEnabled) {
-      try {
-        const target = new URL(`${url}${path}`);
-        const token = buildCdpBearerToken({ keyId: cdpKeyId, keySecret: cdpKeySecret, method: "POST", host: target.host, path: target.pathname });
-        authHeaders = { Authorization: `Bearer ${token}` };
-      } catch (error) {
-        clearTimeout(timer);
-        return { ok: false, status: 0, json: null, error: error && error.message ? error.message : "cdp_jwt_failed" };
-      }
-    }
-    try {
-      const response = await fetch(`${url}${path}`, {
-        method: "POST",
-        headers: { "content-type": "application/json", accept: "application/json", ...headers, ...authHeaders },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      const text = await response.text();
-      let json = null;
-      try {
-        json = text ? JSON.parse(text) : null;
-      } catch (_) {
-        json = null;
-      }
-      return { ok: response.ok, status: response.status, json, bodyExcerpt: text ? text.slice(0, 400) : "" };
-    } catch (error) {
-      return { ok: false, status: 0, json: null, error: error && error.message ? error.message : "facilitator_request_failed" };
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  return {
-    verify: (payload, requirements) => post("/verify", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements }),
-    settle: (payload, requirements) => post("/settle", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements })
-  };
-}
-
-// Verify a buyer's x402 payment against the advertised requirements via the facilitator.
-// Returns { ok:true, authorization } or { ok:false, status:402, reason, detail }.
-async function verifyX402Payment({ paymentHeader, accepts, resourceUrl, facilitator }) {
-  const header = normalizeString(paymentHeader);
-  if (!header) {
-    return { ok: false, status: 402, reason: "payment_required" };
-  }
-  const paymentPayload = decodePaymentSignatureHeader(header);
-  if (!paymentPayload) {
-    return { ok: false, status: 402, reason: "payment_signature_invalid", detail: "PAYMENT-SIGNATURE must be a base64 JSON x402 v2 payment payload" };
-  }
-  const paymentRequirements = matchAcceptedRequirements(paymentPayload, accepts);
-  if (!paymentRequirements) {
-    return { ok: false, status: 402, reason: "payment_requirements_mismatch", detail: "accepted requirements do not match any advertised payment option" };
-  }
-  // The x402 v2 PaymentRequirements shape is exactly {scheme, network, asset, amount, payTo,
-  // maxTimeoutSeconds, extra} with no `resource` field (resource lives on the payload in v2).
-  // Adding one makes strict facilitators (e.g. Coinbase CDP) reject the request with HTTP 400
-  // and makes paymentRequirements diverge from paymentPayload.accepted, so send it clean.
-  // resourceUrl is accepted for API compatibility but intentionally not sent to the facilitator.
-  void resourceUrl;
-  const requirementsForFacilitator = { ...paymentRequirements };
-  const verification = await facilitator.verify(paymentPayload, requirementsForFacilitator);
-  // A facilitator signals an invalid payment either with a 200 and isValid:false (x402.org) or
-  // with a non-2xx status and the same body (Coinbase CDP returns HTTP 400). Treat any response
-  // that carries an isValid flag as a verification result; only a missing/garbled body is a
-  // genuine transport failure.
-  if (!verification.json || typeof verification.json.isValid === "undefined") {
-    const body = verification.bodyExcerpt ? ` body=${verification.bodyExcerpt}` : "";
-    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: verification.error || `facilitator verify returned HTTP ${verification.status}${body}` };
-  }
-  if (verification.json.isValid !== true) {
-    const detail = normalizeString(verification.json.invalidReason) || normalizeString(verification.json.invalidMessage) || "facilitator rejected the payment";
-    return { ok: false, status: 402, reason: "payment_verification_failed", detail };
-  }
-  return {
-    ok: true,
-    authorization: {
-      paymentPayload,
-      paymentRequirements: requirementsForFacilitator,
-      payer: normalizeString(verification.json.payer) || null
-    }
-  };
-}
-
-// Settle a verified payment on-chain via the facilitator (unless settlement is disabled).
-// Returns { ok:true, settlement } or { ok:false, status:402, reason, detail }.
-async function settleX402Payment({ authorization, facilitator, settle }) {
-  if (settle === false) {
-    return { ok: true, settlement: { success: true, skipped: true, reason: "settlement_disabled_by_operator", payer: authorization.payer } };
-  }
-  const settlement = await facilitator.settle(authorization.paymentPayload, authorization.paymentRequirements);
-  // As with verify, a facilitator may report a failed settlement with a non-2xx status and a
-  // body carrying success:false; only a missing/garbled body is a genuine transport failure.
-  if (!settlement.json || typeof settlement.json.success === "undefined") {
-    const body = settlement.bodyExcerpt ? ` body=${settlement.bodyExcerpt}` : "";
-    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: settlement.error || `facilitator settle returned HTTP ${settlement.status}${body}` };
-  }
-  if (settlement.json.success !== true) {
-    const detail = normalizeString(settlement.json.errorReason) || normalizeString(settlement.json.errorMessage) || "facilitator could not settle the payment";
-    return { ok: false, status: 402, reason: "payment_settlement_failed", detail };
-  }
-  return { ok: true, settlement: settlement.json };
-}
-
-function encodePaymentResponse(settlement) {
-  return Buffer.from(JSON.stringify(settlement), "utf8").toString("base64");
-}
-
-module.exports = {
-  decodePaymentSignatureHeader,
-  matchAcceptedRequirements,
-  createFacilitatorClient,
-  verifyX402Payment,
-  settleX402Payment,
-  encodePaymentResponse
-};
+"use strict";
+
+const { buildCdpBearerToken } = require("./cdp_jwt");
+
+// Self-contained x402 v2 facilitator client for the main runtime.
+//
+// This mirrors the proven logic in services/mcp-execution-target/server.js but takes
+// all configuration as explicit arguments so it has no dependency on any global state
+// and can be reused by any paid route. It is intentionally duplicated rather than shared
+// with the standalone MCP executor, which deploys from its own subdirectory.
+//
+// The trust model is the same one proven live: this process never verifies balances or
+// broadcasts transfers itself. It asks an x402 facilitator to verify the buyer's signed
+// EIP-3009 authorization and to settle it on-chain, and refuses to serve work unless the
+// facilitator confirms both. If the facilitator is unreachable, access fails closed.
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeAddress(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+// Decode a PAYMENT-SIGNATURE header into an x402 v2 payment payload.
+function decodePaymentSignatureHeader(value) {
+  const raw = normalizeString(value);
+  if (!raw) return null;
+  for (const encoding of ["base64url", "base64"]) {
+    try {
+      const decoded = Buffer.from(raw, encoding).toString("utf8");
+      const parsed = JSON.parse(decoded);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      if (Number(parsed.x402Version) !== 2) continue;
+      if (!parsed.accepted || typeof parsed.accepted !== "object") continue;
+      if (!parsed.payload || typeof parsed.payload !== "object") continue;
+      return parsed;
+    } catch (_) {
+      // try the next encoding
+    }
+  }
+  return null;
+}
+
+// Find the advertised requirements entry the buyer claims to be paying.
+function matchAcceptedRequirements(paymentPayload, accepts) {
+  const accepted = paymentPayload && paymentPayload.accepted ? paymentPayload.accepted : null;
+  if (!accepted || !Array.isArray(accepts)) return null;
+  return (
+    accepts.find(
+      (entry) =>
+        entry.scheme === normalizeString(accepted.scheme) &&
+        entry.network === normalizeString(accepted.network) &&
+        normalizeAddress(entry.asset) === normalizeAddress(accepted.asset) &&
+        normalizeAddress(entry.payTo) === normalizeAddress(accepted.payTo) &&
+        String(entry.amount) === String(accepted.amount)
+    ) || null
+  );
+}
+
+function createFacilitatorClient(config) {
+  const url = normalizeString(config && config.url).replace(/\/$/, "");
+  const headers = config && config.headers && typeof config.headers === "object" ? config.headers : {};
+  const timeoutMs = Math.max(1000, Number(config && config.timeoutMs) || 15000);
+  // Optional Coinbase CDP auth: when a CDP Secret API Key is configured, a fresh short-lived
+  // EdDSA Bearer JWT is minted per request (CDP rejects static tokens). This is what unlocks
+  // the CDP-hosted facilitator and Base mainnet settlement.
+  const cdp = config && config.cdp && typeof config.cdp === "object" ? config.cdp : null;
+  const cdpKeyId = cdp ? normalizeString(cdp.key_id || cdp.keyId) : "";
+  const cdpKeySecret = cdp ? String((cdp.key_secret || cdp.keySecret) || "").trim() : "";
+  const cdpEnabled = Boolean(cdpKeyId && cdpKeySecret);
+
+  async function post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let authHeaders = {};
+    if (cdpEnabled) {
+      try {
+        const target = new URL(`${url}${path}`);
+        const token = buildCdpBearerToken({ keyId: cdpKeyId, keySecret: cdpKeySecret, method: "POST", host: target.host, path: target.pathname });
+        authHeaders = { Authorization: `Bearer ${token}` };
+      } catch (error) {
+        clearTimeout(timer);
+        return { ok: false, status: 0, json: null, error: error && error.message ? error.message : "cdp_jwt_failed" };
+      }
+    }
+    try {
+      const response = await fetch(`${url}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json", ...headers, ...authHeaders },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      const text = await response.text();
+      let json = null;
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch (_) {
+        json = null;
+      }
+      return { ok: response.ok, status: response.status, json, bodyExcerpt: text ? text.slice(0, 400) : "" };
+    } catch (error) {
+      return { ok: false, status: 0, json: null, error: error && error.message ? error.message : "facilitator_request_failed" };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return {
+    verify: (payload, requirements) => post("/verify", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements }),
+    settle: (payload, requirements) => post("/settle", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements })
+  };
+}
+
+// Verify a buyer's x402 payment against the advertised requirements via the facilitator.
+// Returns { ok:true, authorization } or { ok:false, status:402, reason, detail }.
+async function verifyX402Payment({ paymentHeader, accepts, resourceUrl, facilitator }) {
+  const header = normalizeString(paymentHeader);
+  if (!header) {
+    return { ok: false, status: 402, reason: "payment_required" };
+  }
+  const paymentPayload = decodePaymentSignatureHeader(header);
+  if (!paymentPayload) {
+    return { ok: false, status: 402, reason: "payment_signature_invalid", detail: "PAYMENT-SIGNATURE must be a base64 JSON x402 v2 payment payload" };
+  }
+  const paymentRequirements = matchAcceptedRequirements(paymentPayload, accepts);
+  if (!paymentRequirements) {
+    return { ok: false, status: 402, reason: "payment_requirements_mismatch", detail: "accepted requirements do not match any advertised payment option" };
+  }
+  // The x402 v2 PaymentRequirements shape is exactly {scheme, network, asset, amount, payTo,
+  // maxTimeoutSeconds, extra} with no `resource` field (resource lives on the payload in v2).
+  // Adding one makes strict facilitators (e.g. Coinbase CDP) reject the request with HTTP 400
+  // and makes paymentRequirements diverge from paymentPayload.accepted, so send it clean.
+  // resourceUrl is accepted for API compatibility but intentionally not sent to the facilitator.
+  void resourceUrl;
+  const requirementsForFacilitator = { ...paymentRequirements };
+  const verification = await facilitator.verify(paymentPayload, requirementsForFacilitator);
+  // A facilitator signals an invalid payment either with a 200 and isValid:false (x402.org) or
+  // with a non-2xx status and the same body (Coinbase CDP returns HTTP 400). Treat any response
+  // that carries an isValid flag as a verification result; only a missing/garbled body is a
+  // genuine transport failure.
+  if (!verification.json || typeof verification.json.isValid === "undefined") {
+    const body = verification.bodyExcerpt ? ` body=${verification.bodyExcerpt}` : "";
+    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: verification.error || `facilitator verify returned HTTP ${verification.status}${body}` };
+  }
+  if (verification.json.isValid !== true) {
+    const detail = normalizeString(verification.json.invalidReason) || normalizeString(verification.json.invalidMessage) || "facilitator rejected the payment";
+    return { ok: false, status: 402, reason: "payment_verification_failed", detail };
+  }
+  return {
+    ok: true,
+    authorization: {
+      paymentPayload,
+      paymentRequirements: requirementsForFacilitator,
+      payer: normalizeString(verification.json.payer) || null
+    }
+  };
+}
+
+// Settle a verified payment on-chain via the facilitator (unless settlement is disabled).
+// Returns { ok:true, settlement } or { ok:false, status:402, reason, detail }.
+async function settleX402Payment({ authorization, facilitator, settle }) {
+  if (settle === false) {
+    return { ok: true, settlement: { success: true, skipped: true, reason: "settlement_disabled_by_operator", payer: authorization.payer } };
+  }
+  const settlement = await facilitator.settle(authorization.paymentPayload, authorization.paymentRequirements);
+  // As with verify, a facilitator may report a failed settlement with a non-2xx status and a
+  // body carrying success:false; only a missing/garbled body is a genuine transport failure.
+  if (!settlement.json || typeof settlement.json.success === "undefined") {
+    const body = settlement.bodyExcerpt ? ` body=${settlement.bodyExcerpt}` : "";
+    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: settlement.error || `facilitator settle returned HTTP ${settlement.status}${body}` };
+  }
+  if (settlement.json.success !== true) {
+    const detail = normalizeString(settlement.json.errorReason) || normalizeString(settlement.json.errorMessage) || "facilitator could not settle the payment";
+    return { ok: false, status: 402, reason: "payment_settlement_failed", detail };
+  }
+  return { ok: true, settlement: settlement.json };
+}
+
+function encodePaymentResponse(settlement) {
+  return Buffer.from(JSON.stringify(settlement), "utf8").toString("base64");
+}
+
+module.exports = {
+  decodePaymentSignatureHeader,
+  matchAcceptedRequirements,
+  createFacilitatorClient,
+  verifyX402Payment,
+  settleX402Payment,
+  encodePaymentResponse
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "3.1.13",
+  "version": "3.1.14",
   "description": "x402 pay-per-call agent-commerce runtime: gasless USDC on Base, an open settling provider network with a ledger-reconciled revenue split and automated on-chain payouts (key-less runtime, delegated signer), and bounded cryptographic delegated spend. Proven live on Base mainnet.",
   "main": "index.js",
   "bin": {
@@ -106,7 +106,7 @@
     "verify:production-readiness": "node scripts/verify_production_readiness.js",
     "verify:final-activation": "node scripts/verify_final_activation.js",
     "verify:x402-facilitator": "node scripts/verify_x402_facilitator.js",
-    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_framework_provider_promotion.js && node scripts/verify_operator_observability_boundary.js && node scripts/verify_pricing_experiment_plan.js && node scripts/verify_treasury_public_boundary.js && node scripts/verify_market_lanes.js && node scripts/verify_market_lane_depth.js && node scripts/verify_market_lane_traces.js && node scripts/verify_market_lane_promotion.js && node scripts/verify_provider_runtime_breadth.js && node scripts/verify_provider_runtime_journeys.js && node scripts/verify_lifecycle_continuity.js && node scripts/verify_first_run_conversions.js && node scripts/verify_delivery_summary.js && node scripts/verify_runtime_durability.js && node scripts/verify_revenue_launch_paths.js && node scripts/verify_full_catalog.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js && node scripts/verify_x402_facilitator.js && node scripts/verify_cdp_facilitator.js && node scripts/verify_a2a_rpc.js && node scripts/verify_checkout_processor.js && node scripts/verify_l402_adapter.js && node scripts/verify_bolt_adapter.js && node scripts/verify_mpp_adapter.js && node scripts/verify_rate_limiter.js && node scripts/verify_execution_surfacing.js && node scripts/verify_agent_identity.js && node scripts/verify_verify_execute_settle.js && node scripts/verify_execution_dedupe.js && node scripts/verify_refund_credit.js && node scripts/verify_commerce_bridge.js && node scripts/verify_settlement.js && node scripts/verify_provider_network.js && node scripts/verify_external_execution_retry.js",
+    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_framework_provider_promotion.js && node scripts/verify_operator_observability_boundary.js && node scripts/verify_pricing_experiment_plan.js && node scripts/verify_treasury_public_boundary.js && node scripts/verify_market_lanes.js && node scripts/verify_market_lane_depth.js && node scripts/verify_market_lane_traces.js && node scripts/verify_market_lane_promotion.js && node scripts/verify_provider_runtime_breadth.js && node scripts/verify_provider_runtime_journeys.js && node scripts/verify_lifecycle_continuity.js && node scripts/verify_first_run_conversions.js && node scripts/verify_delivery_summary.js && node scripts/verify_runtime_durability.js && node scripts/verify_revenue_launch_paths.js && node scripts/verify_full_catalog.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js && node scripts/verify_x402_facilitator.js && node scripts/verify_cdp_facilitator.js && node scripts/verify_a2a_rpc.js && node scripts/verify_checkout_processor.js && node scripts/verify_l402_adapter.js && node scripts/verify_bolt_adapter.js && node scripts/verify_mpp_adapter.js && node scripts/verify_rate_limiter.js && node scripts/verify_execution_surfacing.js && node scripts/verify_agent_identity.js && node scripts/verify_verify_execute_settle.js && node scripts/verify_execution_dedupe.js && node scripts/verify_refund_credit.js && node scripts/verify_commerce_bridge.js && node scripts/verify_settlement.js && node scripts/verify_provider_network.js && node scripts/verify_external_execution_retry.js && node scripts/verify_runtime_state_guard.js && node scripts/state_backup_offsite.js selftest",
     "prepublishOnly": "npm run verify:release-candidate",
     "verify:cdp-facilitator": "node scripts/verify_cdp_facilitator.js",
     "verify:a2a-rpc": "node scripts/verify_a2a_rpc.js",
@@ -123,6 +123,8 @@
     "verify:commerce-bridge": "node scripts/verify_commerce_bridge.js",
     "verify:settlement": "node scripts/verify_settlement.js",
     "verify:provider-network": "node scripts/verify_provider_network.js",
-    "verify:external-execution-retry": "node scripts/verify_external_execution_retry.js"
+    "verify:external-execution-retry": "node scripts/verify_external_execution_retry.js",
+    "verify:runtime-state-guard": "node scripts/verify_runtime_state_guard.js",
+    "verify:state-backup": "node scripts/state_backup_offsite.js selftest"
   }
 }

package/scripts/state_backup_offsite.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+"use strict";
+
+// Off-site, encrypted backups of the runtime's durable state (the Supabase snapshot row).
+//
+//   backup  <out_dir>                 read the live row, sanity-check it, gzip + AES-256-GCM encrypt
+//                                     it, verify the ciphertext decrypts back, write <out_dir>/
+//                                     xytara-state-<persisted>.enc + manifest.json (no secrets)
+//   decrypt <file.enc> <out.json>     decrypt a backup to the plain row { state_key, persisted_at_iso,
+//                                     snapshot }
+//   restore <file.enc> --runtime-stopped [--state-key k]
+//                                     write a decrypted backup back as the live row. ONLY with the
+//                                     runtime stopped (suspended on Render): a running runtime would
+//                                     overwrite it with its in-memory state on the next flush.
+//   selftest                          offline round-trip check (used by verify:all)
+//
+// Env: XYTARA_SUPABASE_URL, XYTARA_SUPABASE_SERVICE_ROLE_KEY, XYTARA_SUPABASE_STATE_TABLE
+// (default xytara_runtime_state), XYTARA_SUPABASE_STATE_KEY (default "default"), STATE_BACKUP_KEY
+// (base64, 32 bytes — keep a copy OFF this system: without it no backup can be decrypted),
+// STATE_BACKUP_MIN_PROVIDERS (default 1), STATE_BACKUP_MIN_BYTES (default 10000).
+// The snapshot contains secrets (provider owner secrets, auth tokens): it is only ever written
+// encrypted, and the manifest carries counts and digests only.
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const zlib = require("zlib");
+
+const ENVELOPE_VERSION = "xytara-state-backup/1";
+
+function fail(message) {
+  console.error(`state backup: ${message}`);
+  process.exit(1);
+}
+
+function backupKey() {
+  const raw = String(process.env.STATE_BACKUP_KEY || "").trim();
+  if (!raw) fail("STATE_BACKUP_KEY is not set");
+  const key = Buffer.from(raw, "base64");
+  if (key.length !== 32) fail("STATE_BACKUP_KEY must be 32 bytes, base64-encoded");
+  return key;
+}
+
+function encrypt(rowJson, key) {
+  const plaintext = zlib.gzipSync(Buffer.from(rowJson, "utf8"), { level: 9 });
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  cipher.setAAD(Buffer.from(ENVELOPE_VERSION, "utf8"));
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return {
+    v: ENVELOPE_VERSION,
+    alg: "AES-256-GCM",
+    compression: "gzip",
+    iv: iv.toString("base64"),
+    tag: cipher.getAuthTag().toString("base64"),
+    plaintext_sha256: crypto.createHash("sha256").update(rowJson, "utf8").digest("hex"),
+    ciphertext: ciphertext.toString("base64")
+  };
+}
+
+function decrypt(envelope, key) {
+  if (!envelope || envelope.v !== ENVELOPE_VERSION) throw new Error("not a xytara state backup envelope");
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(envelope.iv, "base64"));
+  decipher.setAAD(Buffer.from(ENVELOPE_VERSION, "utf8"));
+  decipher.setAuthTag(Buffer.from(envelope.tag, "base64"));
+  const plaintext = Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, "base64")), decipher.final()]);
+  const rowJson = zlib.gunzipSync(plaintext).toString("utf8");
+  if (crypto.createHash("sha256").update(rowJson, "utf8").digest("hex") !== envelope.plaintext_sha256) {
+    throw new Error("decrypted content digest mismatch");
+  }
+  return rowJson;
+}
+
+function entryCount(value) {
+  if (value && value.__runtime_state_kind && Array.isArray(value.value)) return value.value.length;
+  if (Array.isArray(value)) return value.length;
+  return value && typeof value === "object" ? Object.keys(value).length : 0;
+}
+
+function summarize(row, rowJson) {
+  const snapshot = row.snapshot || {};
+  const counts = {};
+  for (const key of ["providerRegistry", "providerSettlementLedger", "providerPayouts", "externalCreditGrants", "accountSpendCredentials", "transactions", "deliveryReceipts", "quotes"]) {
+    if (snapshot[key] !== undefined) counts[key] = entryCount(snapshot[key]);
+  }
+  return { state_key: row.state_key, persisted_at_iso: row.persisted_at_iso, snapshot_bytes: Buffer.byteLength(JSON.stringify(snapshot), "utf8"), row_bytes: Buffer.byteLength(rowJson, "utf8"), section_count: Object.keys(snapshot).length, counts };
+}
+
+function supabaseConfig() {
+  const url = String(process.env.XYTARA_SUPABASE_URL || "").trim().replace(/\/+$/, "");
+  const serviceKey = String(process.env.XYTARA_SUPABASE_SERVICE_ROLE_KEY || "").trim();
+  if (!url || !serviceKey) fail("XYTARA_SUPABASE_URL and XYTARA_SUPABASE_SERVICE_ROLE_KEY are required");
+  return {
+    url,
+    serviceKey,
+    table: String(process.env.XYTARA_SUPABASE_STATE_TABLE || "xytara_runtime_state").trim(),
+    stateKey: String(process.env.XYTARA_SUPABASE_STATE_KEY || "default").trim()
+  };
+}
+
+async function fetchRow(cfg) {
+  const endpoint = `${cfg.url}/rest/v1/${encodeURIComponent(cfg.table)}?state_key=eq.${encodeURIComponent(cfg.stateKey)}&select=state_key,snapshot,persisted_at_iso&limit=1`;
+  let lastError = null;
+  for (let attempt = 1; attempt <= 4; attempt += 1) {
+    try {
+      const response = await fetch(endpoint, {
+        headers: { apikey: cfg.serviceKey, authorization: `Bearer ${cfg.serviceKey}` },
+        signal: AbortSignal.timeout(45000)
+      });
+      if (!response.ok) throw new Error(`HTTP ${response.status}: ${(await response.text()).slice(0, 200)}`);
+      const rows = await response.json();
+      if (!Array.isArray(rows) || !rows[0]) throw new Error(`no row for state_key "${cfg.stateKey}"`);
+      return rows[0];
+    } catch (error) {
+      lastError = error;
+      if (attempt < 4) await new Promise((resolve) => setTimeout(resolve, attempt * 15000));
+    }
+  }
+  throw lastError;
+}
+
+async function backup(outDir) {
+  if (!outDir) fail("usage: backup <out_dir>");
+  const key = backupKey();
+  const row = await fetchRow(supabaseConfig()).catch((error) => fail(`could not read the state row: ${error.message}`));
+  const rowJson = JSON.stringify(row);
+  const summary = summarize(row, rowJson);
+  // Sanity gate: a near-empty snapshot means something already went wrong — fail loudly (the
+  // failed scheduled run is the alert) instead of quietly storing an empty backup.
+  const minProviders = Number(process.env.STATE_BACKUP_MIN_PROVIDERS || 1);
+  const minBytes = Number(process.env.STATE_BACKUP_MIN_BYTES || 10000);
+  if ((summary.counts.providerRegistry || 0) < minProviders) fail(`snapshot has ${summary.counts.providerRegistry || 0} providers (< ${minProviders}): refusing to treat it as healthy`);
+  if (summary.snapshot_bytes < minBytes) fail(`snapshot is only ${summary.snapshot_bytes} bytes (< ${minBytes}): refusing to treat it as healthy`);
+  const envelope = encrypt(rowJson, key);
+  if (decrypt(envelope, key) !== rowJson) fail("round-trip check failed");
+  fs.mkdirSync(outDir, { recursive: true });
+  const stamp = String(row.persisted_at_iso || new Date().toISOString()).replace(/[^0-9A-Za-z]/g, "").slice(0, 15);
+  const fileName = `xytara-state-${stamp}.enc`;
+  fs.writeFileSync(path.join(outDir, fileName), JSON.stringify(envelope));
+  const manifest = { v: ENVELOPE_VERSION, file: fileName, created_at_iso: new Date().toISOString(), plaintext_sha256: envelope.plaintext_sha256, ...summary };
+  fs.writeFileSync(path.join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  console.log(JSON.stringify(manifest, null, 2));
+}
+
+function decryptCommand(inFile, outFile) {
+  if (!inFile || !outFile) fail("usage: decrypt <file.enc> <out.json>");
+  const rowJson = decrypt(JSON.parse(fs.readFileSync(inFile, "utf8")), backupKey());
+  fs.writeFileSync(outFile, rowJson);
+  console.log(JSON.stringify(summarize(JSON.parse(rowJson), rowJson), null, 2));
+}
+
+async function restoreCommand(inFile, args) {
+  if (!inFile || !args.includes("--runtime-stopped")) {
+    fail("usage: restore <file.enc> --runtime-stopped [--state-key k]  (suspend the runtime first, or it will overwrite the restored row)");
+  }
+  const cfg = supabaseConfig();
+  const keyIndex = args.indexOf("--state-key");
+  const stateKey = keyIndex >= 0 && args[keyIndex + 1] ? args[keyIndex + 1] : cfg.stateKey;
+  const row = JSON.parse(decrypt(JSON.parse(fs.readFileSync(inFile, "utf8")), backupKey()));
+  const response = await fetch(`${cfg.url}/rest/v1/${encodeURIComponent(cfg.table)}?on_conflict=state_key`, {
+    method: "POST",
+    headers: { apikey: cfg.serviceKey, authorization: `Bearer ${cfg.serviceKey}`, "content-type": "application/json", prefer: "resolution=merge-duplicates,return=minimal" },
+    body: JSON.stringify([{ state_key: stateKey, snapshot: row.snapshot, persisted_at_iso: row.persisted_at_iso }]),
+    signal: AbortSignal.timeout(60000)
+  });
+  if (!response.ok) fail(`restore write failed: HTTP ${response.status}`);
+  console.log(`restored ${row.state_key}@${row.persisted_at_iso} into state_key "${stateKey}". Resume the runtime now.`);
+}
+
+function selftest() {
+  const key = crypto.randomBytes(32);
+  const row = { state_key: "default", persisted_at_iso: "2026-10-17T00:00:00.000Z", snapshot: { providerRegistry: { __runtime_state_kind: "Map", value: [["p", { status: "active", owner_secret: "prvown_x" }]] } } };
+  const rowJson = JSON.stringify(row);
+  const envelope = encrypt(rowJson, key);
+  if (decrypt(envelope, key) !== rowJson) fail("selftest: round trip mismatch");
+  if (JSON.stringify(envelope).includes("prvown_x")) fail("selftest: plaintext secret visible in the envelope");
+  let wrongKeyRejected = false;
+  try { decrypt(envelope, crypto.randomBytes(32)); } catch (_) { wrongKeyRejected = true; }
+  if (!wrongKeyRejected) fail("selftest: a wrong key decrypted the backup");
+  const tampered = { ...envelope, ciphertext: Buffer.from(Buffer.from(envelope.ciphertext, "base64").map((b, i) => (i === 0 ? b ^ 1 : b))).toString("base64") };
+  let tamperRejected = false;
+  try { decrypt(tampered, key); } catch (_) { tamperRejected = true; }
+  if (!tamperRejected) fail("selftest: tampered ciphertext was accepted");
+  console.log("xytara state-backup selftest passed (round trip, no plaintext secrets, wrong key + tamper rejected)");
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (command === "backup") return backup(args[0]);
+  if (command === "decrypt") return decryptCommand(args[0], args[1]);
+  if (command === "restore") return restoreCommand(args[0], args);
+  if (command === "selftest") return selftest();
+  fail("usage: state_backup_offsite.js backup <out_dir> | decrypt <file.enc> <out.json> | restore <file.enc> --runtime-stopped | selftest");
+}
+
+main().catch((error) => fail(error && error.message ? error.message : String(error)));