xytara 3.1.4 → 3.1.5

package/.env.example

@@ -13,6 +13,10 @@ XYTARA_X402_SETTLE=true
 # credit units a single self-serve /x402/credits/topup grants (default 1000);
 # an accepts entry may override per-payment via its extra.credits
 XYTARA_X402_TOPUP_UNITS=1000
+# Coinbase CDP auth for the CDP-hosted facilitator (Base mainnet); Ed25519 Secret API Key.
+# The runtime mints a fresh CDP Bearer JWT per request when both are set.
+CDP_API_KEY_ID=
+CDP_API_KEY_SECRET=
 XYTARA_PAYMENT_MAX_AGE_SECONDS=300
 XYTARA_WALLET_REGISTRY_JSON=[]
 XYTARA_TREASURY_DESTINATION_ID=

package/REAL_PAYMENT_SETUP.md

@@ -72,21 +72,25 @@ settle it through a mainnet-capable facilitator.
 
 Important: the default `https://x402.org/facilitator` settles **Base Sepolia only** (its
 `/supported` list has no `eip155:8453`). Pointing a mainnet `accepts` entry at it fails
-closed and the route is unpayable. For mainnet you need a mainnet-capable facilitator, such
-as Coinbase CDP (`https://api.cdp.coinbase.com/platform/v2/x402`), which requires a CDP API
-key passed as auth:
+closed and the route is unpayable. For mainnet use a mainnet-capable facilitator, such as
+Coinbase CDP (`https://api.cdp.coinbase.com/platform/v2/x402`), which is supported natively:
+create a CDP Secret API Key (Ed25519) and set its id and secret, and the runtime mints a
+fresh short-lived CDP Bearer JWT per facilitator call (CDP rejects static tokens).
 
 ```env
 # advertise mainnet (real USDC on Base); you can keep a Sepolia entry in the array too
 XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"10000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
-# a mainnet-capable facilitator (CDP shown) and its auth header:
+# point at the CDP-hosted facilitator and supply the CDP Secret API Key:
 XYTARA_X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
-XYTARA_X402_FACILITATOR_HEADERS_JSON={"Authorization":"Bearer <cdp-access-token>"}
+CDP_API_KEY_ID=<your-cdp-key-id>
+CDP_API_KEY_SECRET=<your-cdp-ed25519-secret-base64>
 ```
 
-`amount` is in the asset's base units (USDC has 6 decimals, so `10000` = 0.01 USDC). Confirm
-your facilitator lists `eip155:8453` in its `/supported` response before advertising it, and
-remember that once mainnet is live, buyers spend real USDC.
+The CDP key must use the **Ed25519** signature algorithm (not ECDSA). `CDP_API_KEY_ID` /
+`CDP_API_KEY_SECRET` are the CDP-standard names; `XYTARA_X402_CDP_KEY_ID` /
+`XYTARA_X402_CDP_KEY_SECRET` are accepted as overrides. `amount` is in the asset's base units
+(USDC has 6 decimals, so `10000` = 0.01 USDC). Verify the CDP auth path locally with
+`npm run verify:cdp-facilitator`. Once mainnet is live, buyers spend real USDC.
 
 ## Minimum Production-Oriented Configuration
 

package/RELEASE_NOTES.md

@@ -1,9 +1,11 @@
-`xytara` 3.1.4 makes the self-serve credits capability discoverable and documents the path to Base mainnet.
+`xytara` 3.1.5 adds native Coinbase CDP facilitator support, unlocking Base mainnet settlement.
 
-This is a discovery and documentation release on top of the self-serve credits shipped earlier in the line. No existing behavior changes.
+The x402_facilitator mode now authenticates to facilitators that require a short-lived CDP Bearer token, so the runtime can settle real USDC on Base mainnet through the CDP-hosted facilitator, not just test USDC on Base Sepolia via the default facilitator.
 
 Highlights:
 
-- the x402 lane summary (`/v1/x402/summary`) and lane pack now advertise `credits_topup_ref` (`/x402/credits/topup`) and a `self_serve_credits` first-run flow, so agents discovering the runtime see the pay-once-get-credits path alongside direct command execution and paid MCP tooling
-- documents going to Base mainnet in `REAL_PAYMENT_SETUP.md`: the mainnet `accepts` profile (real USDC on `eip155:8453`) and the requirement for a mainnet-capable facilitator, since the default `x402.org` facilitator settles Base Sepolia only
-- no change to payment verification, settlement, the credits ledger, or any existing route
+- the facilitator client mints a fresh EdDSA (Ed25519) CDP Bearer JWT per `/verify` and `/settle` request, with the `uri` claim bound to each request and a 120-second expiry, because CDP rejects static tokens
+- enable it by setting `CDP_API_KEY_ID` and `CDP_API_KEY_SECRET` (or `XYTARA_X402_CDP_KEY_ID` / `XYTARA_X402_CDP_KEY_SECRET`) and pointing `XYTARA_X402_FACILITATOR_URL` at the CDP facilitator; the Ed25519 secret is the base64 64-byte key CDP issues
+- zero new dependencies: the JWT is signed with Node's built-in Ed25519
+- when no CDP key is configured, behavior is unchanged: static-header facilitators and the default Base Sepolia path work exactly as before
+- adds `npm run verify:cdp-facilitator`, which checks the per-request token minting, claim shape, and signature against a mock facilitator, and documents the Base mainnet setup in `REAL_PAYMENT_SETUP.md`

package/examples/generated.carried-handoff.json

@@ -6,9 +6,9 @@
     "source_ref": "spine.job.commitment",
     "committed_ref": "transaction.job.commitment",
     "precommit_pack_ref": "precommit.job.commitment.readiness",
-    "transaction_id": "txn_01b29e65db7d",
-    "receipt_id": "rcpt_b40aa20be45e",
-    "proof_ref": "proof_rcpt_b40aa20be45e",
+    "transaction_id": "txn_18742578ec28",
+    "receipt_id": "rcpt_fa3b4219d3c4",
+    "proof_ref": "proof_rcpt_fa3b4219d3c4",
     "payment_protocol": "x402",
     "settlement_mode": "evm_payment",
     "treasury_destination_id": "treasury_acct_demo",

package/lib/cdp_jwt.js

@@ -0,0 +1,57 @@
+"use strict";
+
+// Zero-dependency Coinbase CDP Bearer JWT signer, used to authenticate requests to the
+// CDP-hosted x402 facilitator (https://api.cdp.coinbase.com/platform/v2/x402), which
+// settles Base mainnet. CDP authenticates each request with a short-lived (<=120s) EdDSA
+// (Ed25519) JWT generated from a CDP Secret API Key, so a static Authorization header is
+// not usable; a fresh token is minted per request with a `uri` claim bound to that request.
+//
+// Secret format: base64-encoded Ed25519, 64 bytes (first 32 = seed, last 32 = public key).
+// Reference: https://docs.cdp.coinbase.com/get-started/docs/cdp-api-keys
+
+const crypto = require("crypto");
+
+// DER PKCS#8 prefix for an Ed25519 private key carrying a 32-byte seed.
+const ED25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+
+function base64url(input) {
+  const buf = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function privateKeyFromSecret(keySecret) {
+  const decoded = Buffer.from(String(keySecret || "").trim(), "base64");
+  if (decoded.length !== 64) {
+    throw new Error("cdp_key_secret_invalid: expected a base64 Ed25519 key of 64 bytes");
+  }
+  const seed = decoded.subarray(0, 32);
+  const pkcs8 = Buffer.concat([ED25519_PKCS8_PREFIX, seed]);
+  return crypto.createPrivateKey({ key: pkcs8, format: "der", type: "pkcs8" });
+}
+
+// Build a CDP Bearer JWT for a single request.
+//   keyId      CDP API key id (UUID)
+//   keySecret  base64 Ed25519 secret (64 bytes)
+//   method     HTTP method, e.g. "POST"
+//   host       request host, e.g. "api.cdp.coinbase.com"
+//   path       request path, e.g. "/platform/v2/x402/verify"
+function buildCdpBearerToken({ keyId, keySecret, method, host, path }) {
+  const id = String(keyId || "").trim();
+  if (!id) throw new Error("cdp_key_id_missing");
+  const privateKey = privateKeyFromSecret(keySecret);
+  const now = Math.floor(Date.now() / 1000);
+  const header = { alg: "EdDSA", typ: "JWT", kid: id, nonce: crypto.randomBytes(16).toString("hex") };
+  const claims = {
+    sub: id,
+    iss: "cdp",
+    aud: ["cdp_service"],
+    nbf: now,
+    exp: now + 120,
+    uri: `${String(method || "POST").toUpperCase()} ${host}${path}`
+  };
+  const signingInput = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(claims))}`;
+  const signature = crypto.sign(null, Buffer.from(signingInput), privateKey);
+  return `${signingInput}.${base64url(signature)}`;
+}
+
+module.exports = { buildCdpBearerToken, base64url };

package/lib/payment_config.js

@@ -1,242 +1,253 @@
-"use strict";
-
-const fs = require("fs");
-const {
-  buildBsvTeranodeTreasuryDestination,
-  normalizeSettlementMode
-} = require("./settlement_bsv_teranode");
-
-function safeParseJson(text, fallback) {
-  try {
-    return JSON.parse(text);
-  } catch (_) {
-    return fallback;
-  }
-}
-
-function readJsonFromEnvOrPath(jsonValue, pathValue, fallback) {
-  if (typeof jsonValue === "string" && jsonValue.trim()) {
-    return safeParseJson(jsonValue, fallback);
-  }
-  if (typeof pathValue === "string" && pathValue.trim()) {
-    try {
-      return safeParseJson(fs.readFileSync(pathValue, "utf8"), fallback);
-    } catch (_) {
-      return fallback;
-    }
-  }
-  return fallback;
-}
-
-function loadWalletRegistry() {
-  const raw = readJsonFromEnvOrPath(
-    process.env.XYTARA_WALLET_REGISTRY_JSON,
-    process.env.XYTARA_WALLET_REGISTRY_PATH,
-    []
-  );
-  const entries = Array.isArray(raw)
-    ? raw
-    : Array.isArray(raw && raw.wallets) ? raw.wallets : [];
-  const byWalletId = new Map();
-  for (const entry of entries) {
-    if (!entry || typeof entry !== "object") continue;
-    const walletId = typeof entry.wallet_id === "string" ? entry.wallet_id.trim() : "";
-    const secret = typeof entry.secret === "string" ? entry.secret : "";
-    if (!walletId || !secret) continue;
-    byWalletId.set(walletId, {
-      wallet_id: walletId,
-      secret,
-      account_id: typeof entry.account_id === "string" && entry.account_id.trim() ? entry.account_id.trim() : null,
-      enabled: entry.enabled !== false
-    });
-  }
-  return byWalletId;
-}
-
-function loadTreasuryDestinationMap() {
-  const raw = readJsonFromEnvOrPath(
-    process.env.XYTARA_TREASURY_DESTINATIONS_JSON,
-    process.env.XYTARA_TREASURY_DESTINATIONS_PATH,
-    {}
-  );
-  const input = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
-  const normalized = {};
-  for (const [settlementMode, entry] of Object.entries(input)) {
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
-    normalized[normalizeSettlementMode(settlementMode)] = {
-      destination_id: typeof entry.destination_id === "string" && entry.destination_id.trim()
-        ? entry.destination_id.trim()
-        : null,
-      destination_kind: typeof entry.destination_kind === "string" && entry.destination_kind.trim()
-        ? entry.destination_kind.trim()
-        : null,
-      account_id: typeof entry.account_id === "string" && entry.account_id.trim()
-        ? entry.account_id.trim()
-        : null,
-      external_ref: typeof entry.external_ref === "string" && entry.external_ref.trim()
-        ? entry.external_ref.trim()
-        : null,
-      custody_ref: typeof entry.custody_ref === "string" && entry.custody_ref.trim()
-        ? entry.custody_ref.trim()
-        : null,
-      reporting_ref: typeof entry.reporting_ref === "string" && entry.reporting_ref.trim()
-        ? entry.reporting_ref.trim()
-        : null,
-      wallet_ref: typeof entry.wallet_ref === "string" && entry.wallet_ref.trim()
-        ? entry.wallet_ref.trim()
-        : null,
-      provider_ref: typeof entry.provider_ref === "string" && entry.provider_ref.trim()
-        ? entry.provider_ref.trim()
-        : null,
-      network: typeof entry.network === "string" && entry.network.trim()
-        ? entry.network.trim()
-        : null,
-      chain_id: typeof entry.chain_id === "string" && entry.chain_id.trim()
-        ? entry.chain_id.trim()
-        : null,
-      asset_symbol: typeof entry.asset_symbol === "string" && entry.asset_symbol.trim()
-        ? entry.asset_symbol.trim()
-        : null,
-      policy_scope: typeof entry.policy_scope === "string" && entry.policy_scope.trim()
-        ? entry.policy_scope.trim()
-        : null,
-      storage_class: typeof entry.storage_class === "string" && entry.storage_class.trim()
-        ? entry.storage_class.trim()
-        : null,
-      enabled: entry.enabled !== false,
-      accept_inbound: entry.accept_inbound !== false
-    };
-  }
-  return normalized;
-}
-
-function loadPaymentConfig() {
-  // Default is fail-closed: signed payment acceptance. "presence" (accept any non-empty payment header)
-  // must now be opted into explicitly and is only appropriate for local development.
-  const verificationModeInput = String(process.env.XYTARA_PAYMENT_VERIFICATION_MODE || "local_signed").trim() || "local_signed";
-  const verificationMode = verificationModeInput === "signed" ? "local_signed" : verificationModeInput;
-  const maxAgeSeconds = Number(process.env.XYTARA_PAYMENT_MAX_AGE_SECONDS || 300);
-  return {
-    verification_mode: verificationMode,
-    verification_mode_input: verificationModeInput,
-    payment_max_age_seconds: Number.isFinite(maxAgeSeconds) && maxAgeSeconds > 0 ? maxAgeSeconds : 300,
-    wallet_registry: loadWalletRegistry(),
-    x402: loadX402FacilitatorConfig(),
-    treasury_destination_id: String(process.env.XYTARA_TREASURY_DESTINATION_ID || "").trim() || null,
-    treasury_destination_kind: String(process.env.XYTARA_TREASURY_DESTINATION_KIND || "").trim() || null,
-    treasury_account_id: String(process.env.XYTARA_TREASURY_ACCOUNT_ID || "").trim() || null,
-    treasury_external_ref: String(process.env.XYTARA_TREASURY_EXTERNAL_REF || "").trim() || null,
-    treasury_destinations_by_settlement_mode: loadTreasuryDestinationMap()
-  };
-}
-
-// Configuration for the x402_facilitator verification mode: the on-chain, trustless
-// pay-per-call path. The advertised accepts tell a buyer how to pay; the facilitator
-// verifies and settles the signed payment before any work runs.
-function loadX402FacilitatorConfig() {
-  let accepts = [];
-  const rawAccepts = String(process.env.XYTARA_X402_ACCEPTS_JSON || "").trim();
-  if (rawAccepts) {
-    try {
-      const parsed = JSON.parse(rawAccepts);
-      if (Array.isArray(parsed)) {
-        accepts = parsed
-          .map((entry) => ({
-            scheme: String((entry && entry.scheme) || "exact").trim(),
-            network: String((entry && entry.network) || "").trim(),
-            asset: String((entry && entry.asset) || "").trim(),
-            amount: String((entry && entry.amount) || "").trim(),
-            payTo: String((entry && entry.payTo) || "").trim(),
-            ...(entry && entry.extra && typeof entry.extra === "object" ? { extra: entry.extra } : {}),
-            ...(Number(entry && entry.maxTimeoutSeconds) > 0 ? { maxTimeoutSeconds: Number(entry.maxTimeoutSeconds) } : {})
-          }))
-          .filter((entry) => entry.network && entry.asset && entry.amount && entry.payTo);
-      }
-    } catch (_) {
-      accepts = [];
-    }
-  }
-  let headers = {};
-  const rawHeaders = String(process.env.XYTARA_X402_FACILITATOR_HEADERS_JSON || "").trim();
-  if (rawHeaders) {
-    try {
-      const parsed = JSON.parse(rawHeaders);
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) headers = parsed;
-    } catch (_) {
-      headers = {};
-    }
-  }
-  return {
-    accepts,
-    facilitator_url: String(process.env.XYTARA_X402_FACILITATOR_URL || "https://x402.org/facilitator").trim().replace(/\/$/, ""),
-    facilitator_headers: headers,
-    facilitator_timeout_ms: Math.max(1000, Number(process.env.XYTARA_X402_FACILITATOR_TIMEOUT_MS || 15000) || 15000),
-    settle: String(process.env.XYTARA_X402_SETTLE || "true").trim().toLowerCase() !== "false",
-    // Credit units a single self-serve x402 top-up grants, unless the matched accepts
-    // entry carries its own `extra.credits`.
-    topup_units_default: Math.max(0, Number(process.env.XYTARA_X402_TOPUP_UNITS || 1000) || 0)
-  };
-}
-
-function buildConfiguredTreasuryDestination(accountId, settlementMode) {
-  const config = loadPaymentConfig();
-  const normalizedSettlementMode = normalizeSettlementMode(settlementMode);
-  const mapEntry = normalizedSettlementMode && config.treasury_destinations_by_settlement_mode[normalizedSettlementMode]
-    ? config.treasury_destinations_by_settlement_mode[normalizedSettlementMode]
-    : null;
-  const destinationId = mapEntry && typeof mapEntry.destination_id === "string" && mapEntry.destination_id.trim()
-    ? mapEntry.destination_id.trim()
-    : config.treasury_destination_id;
-  if (!destinationId) {
-    return buildBsvTeranodeTreasuryDestination(accountId, normalizedSettlementMode);
-  }
-  return {
-    destination_id: destinationId,
-    destination_kind:
-      (mapEntry && typeof mapEntry.destination_kind === "string" && mapEntry.destination_kind.trim())
-      || config.treasury_destination_kind
-      || "merchant_treasury",
-    account_id:
-      (mapEntry && typeof mapEntry.account_id === "string" && mapEntry.account_id.trim())
-      || config.treasury_account_id
-      || accountId
-      || null,
-    settlement_mode: normalizedSettlementMode || null,
-    external_ref:
-      (mapEntry && typeof mapEntry.external_ref === "string" && mapEntry.external_ref.trim())
-      || config.treasury_external_ref
-      || null,
-    custody_ref: mapEntry && typeof mapEntry.custody_ref === "string" && mapEntry.custody_ref.trim()
-      ? mapEntry.custody_ref.trim()
-      : null,
-    reporting_ref: mapEntry && typeof mapEntry.reporting_ref === "string" && mapEntry.reporting_ref.trim()
-      ? mapEntry.reporting_ref.trim()
-      : null,
-    wallet_ref: mapEntry && typeof mapEntry.wallet_ref === "string" && mapEntry.wallet_ref.trim()
-      ? mapEntry.wallet_ref.trim()
-      : null,
-    provider_ref: mapEntry && typeof mapEntry.provider_ref === "string" && mapEntry.provider_ref.trim()
-      ? mapEntry.provider_ref.trim()
-      : null,
-    network: mapEntry && typeof mapEntry.network === "string" && mapEntry.network.trim()
-      ? mapEntry.network.trim()
-      : null,
-    chain_id: mapEntry && typeof mapEntry.chain_id === "string" && mapEntry.chain_id.trim()
-      ? mapEntry.chain_id.trim()
-      : null,
-    asset_symbol: mapEntry && typeof mapEntry.asset_symbol === "string" && mapEntry.asset_symbol.trim()
-      ? mapEntry.asset_symbol.trim()
-      : null,
-    policy_scope: mapEntry && typeof mapEntry.policy_scope === "string" && mapEntry.policy_scope.trim()
-      ? mapEntry.policy_scope.trim()
-      : null,
-    storage_class: mapEntry && typeof mapEntry.storage_class === "string" && mapEntry.storage_class.trim()
-      ? mapEntry.storage_class.trim()
-      : null
-  };
-}
-
-module.exports = {
-  buildConfiguredTreasuryDestination,
-  loadPaymentConfig
-};
+"use strict";
+
+const fs = require("fs");
+const {
+  buildBsvTeranodeTreasuryDestination,
+  normalizeSettlementMode
+} = require("./settlement_bsv_teranode");
+
+function safeParseJson(text, fallback) {
+  try {
+    return JSON.parse(text);
+  } catch (_) {
+    return fallback;
+  }
+}
+
+function readJsonFromEnvOrPath(jsonValue, pathValue, fallback) {
+  if (typeof jsonValue === "string" && jsonValue.trim()) {
+    return safeParseJson(jsonValue, fallback);
+  }
+  if (typeof pathValue === "string" && pathValue.trim()) {
+    try {
+      return safeParseJson(fs.readFileSync(pathValue, "utf8"), fallback);
+    } catch (_) {
+      return fallback;
+    }
+  }
+  return fallback;
+}
+
+function loadWalletRegistry() {
+  const raw = readJsonFromEnvOrPath(
+    process.env.XYTARA_WALLET_REGISTRY_JSON,
+    process.env.XYTARA_WALLET_REGISTRY_PATH,
+    []
+  );
+  const entries = Array.isArray(raw)
+    ? raw
+    : Array.isArray(raw && raw.wallets) ? raw.wallets : [];
+  const byWalletId = new Map();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    const walletId = typeof entry.wallet_id === "string" ? entry.wallet_id.trim() : "";
+    const secret = typeof entry.secret === "string" ? entry.secret : "";
+    if (!walletId || !secret) continue;
+    byWalletId.set(walletId, {
+      wallet_id: walletId,
+      secret,
+      account_id: typeof entry.account_id === "string" && entry.account_id.trim() ? entry.account_id.trim() : null,
+      enabled: entry.enabled !== false
+    });
+  }
+  return byWalletId;
+}
+
+function loadTreasuryDestinationMap() {
+  const raw = readJsonFromEnvOrPath(
+    process.env.XYTARA_TREASURY_DESTINATIONS_JSON,
+    process.env.XYTARA_TREASURY_DESTINATIONS_PATH,
+    {}
+  );
+  const input = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  const normalized = {};
+  for (const [settlementMode, entry] of Object.entries(input)) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    normalized[normalizeSettlementMode(settlementMode)] = {
+      destination_id: typeof entry.destination_id === "string" && entry.destination_id.trim()
+        ? entry.destination_id.trim()
+        : null,
+      destination_kind: typeof entry.destination_kind === "string" && entry.destination_kind.trim()
+        ? entry.destination_kind.trim()
+        : null,
+      account_id: typeof entry.account_id === "string" && entry.account_id.trim()
+        ? entry.account_id.trim()
+        : null,
+      external_ref: typeof entry.external_ref === "string" && entry.external_ref.trim()
+        ? entry.external_ref.trim()
+        : null,
+      custody_ref: typeof entry.custody_ref === "string" && entry.custody_ref.trim()
+        ? entry.custody_ref.trim()
+        : null,
+      reporting_ref: typeof entry.reporting_ref === "string" && entry.reporting_ref.trim()
+        ? entry.reporting_ref.trim()
+        : null,
+      wallet_ref: typeof entry.wallet_ref === "string" && entry.wallet_ref.trim()
+        ? entry.wallet_ref.trim()
+        : null,
+      provider_ref: typeof entry.provider_ref === "string" && entry.provider_ref.trim()
+        ? entry.provider_ref.trim()
+        : null,
+      network: typeof entry.network === "string" && entry.network.trim()
+        ? entry.network.trim()
+        : null,
+      chain_id: typeof entry.chain_id === "string" && entry.chain_id.trim()
+        ? entry.chain_id.trim()
+        : null,
+      asset_symbol: typeof entry.asset_symbol === "string" && entry.asset_symbol.trim()
+        ? entry.asset_symbol.trim()
+        : null,
+      policy_scope: typeof entry.policy_scope === "string" && entry.policy_scope.trim()
+        ? entry.policy_scope.trim()
+        : null,
+      storage_class: typeof entry.storage_class === "string" && entry.storage_class.trim()
+        ? entry.storage_class.trim()
+        : null,
+      enabled: entry.enabled !== false,
+      accept_inbound: entry.accept_inbound !== false
+    };
+  }
+  return normalized;
+}
+
+function loadPaymentConfig() {
+  // Default is fail-closed: signed payment acceptance. "presence" (accept any non-empty payment header)
+  // must now be opted into explicitly and is only appropriate for local development.
+  const verificationModeInput = String(process.env.XYTARA_PAYMENT_VERIFICATION_MODE || "local_signed").trim() || "local_signed";
+  const verificationMode = verificationModeInput === "signed" ? "local_signed" : verificationModeInput;
+  const maxAgeSeconds = Number(process.env.XYTARA_PAYMENT_MAX_AGE_SECONDS || 300);
+  return {
+    verification_mode: verificationMode,
+    verification_mode_input: verificationModeInput,
+    payment_max_age_seconds: Number.isFinite(maxAgeSeconds) && maxAgeSeconds > 0 ? maxAgeSeconds : 300,
+    wallet_registry: loadWalletRegistry(),
+    x402: loadX402FacilitatorConfig(),
+    treasury_destination_id: String(process.env.XYTARA_TREASURY_DESTINATION_ID || "").trim() || null,
+    treasury_destination_kind: String(process.env.XYTARA_TREASURY_DESTINATION_KIND || "").trim() || null,
+    treasury_account_id: String(process.env.XYTARA_TREASURY_ACCOUNT_ID || "").trim() || null,
+    treasury_external_ref: String(process.env.XYTARA_TREASURY_EXTERNAL_REF || "").trim() || null,
+    treasury_destinations_by_settlement_mode: loadTreasuryDestinationMap()
+  };
+}
+
+// Configuration for the x402_facilitator verification mode: the on-chain, trustless
+// pay-per-call path. The advertised accepts tell a buyer how to pay; the facilitator
+// verifies and settles the signed payment before any work runs.
+function loadX402FacilitatorConfig() {
+  let accepts = [];
+  const rawAccepts = String(process.env.XYTARA_X402_ACCEPTS_JSON || "").trim();
+  if (rawAccepts) {
+    try {
+      const parsed = JSON.parse(rawAccepts);
+      if (Array.isArray(parsed)) {
+        accepts = parsed
+          .map((entry) => ({
+            scheme: String((entry && entry.scheme) || "exact").trim(),
+            network: String((entry && entry.network) || "").trim(),
+            asset: String((entry && entry.asset) || "").trim(),
+            amount: String((entry && entry.amount) || "").trim(),
+            payTo: String((entry && entry.payTo) || "").trim(),
+            ...(entry && entry.extra && typeof entry.extra === "object" ? { extra: entry.extra } : {}),
+            ...(Number(entry && entry.maxTimeoutSeconds) > 0 ? { maxTimeoutSeconds: Number(entry.maxTimeoutSeconds) } : {})
+          }))
+          .filter((entry) => entry.network && entry.asset && entry.amount && entry.payTo);
+      }
+    } catch (_) {
+      accepts = [];
+    }
+  }
+  let headers = {};
+  const rawHeaders = String(process.env.XYTARA_X402_FACILITATOR_HEADERS_JSON || "").trim();
+  if (rawHeaders) {
+    try {
+      const parsed = JSON.parse(rawHeaders);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) headers = parsed;
+    } catch (_) {
+      headers = {};
+    }
+  }
+  return {
+    accepts,
+    facilitator_url: String(process.env.XYTARA_X402_FACILITATOR_URL || "https://x402.org/facilitator").trim().replace(/\/$/, ""),
+    facilitator_headers: headers,
+    facilitator_timeout_ms: Math.max(1000, Number(process.env.XYTARA_X402_FACILITATOR_TIMEOUT_MS || 15000) || 15000),
+    settle: String(process.env.XYTARA_X402_SETTLE || "true").trim().toLowerCase() !== "false",
+    // Credit units a single self-serve x402 top-up grants, unless the matched accepts
+    // entry carries its own `extra.credits`.
+    topup_units_default: Math.max(0, Number(process.env.XYTARA_X402_TOPUP_UNITS || 1000) || 0),
+    // Optional Coinbase CDP auth for the CDP-hosted facilitator (Base mainnet). When both a
+    // key id and secret are present, the facilitator client mints a fresh EdDSA Bearer JWT
+    // per request. Accepts the CDP-standard env names or XYTARA_X402_CDP_* overrides.
+    cdp: loadCdpFacilitatorAuth()
+  };
+}
+
+function loadCdpFacilitatorAuth() {
+  const keyId = String(process.env.XYTARA_X402_CDP_KEY_ID || process.env.CDP_API_KEY_ID || "").trim();
+  const keySecret = String(process.env.XYTARA_X402_CDP_KEY_SECRET || process.env.CDP_API_KEY_SECRET || "").trim();
+  if (!keyId || !keySecret) return null;
+  return { key_id: keyId, key_secret: keySecret };
+}
+
+function buildConfiguredTreasuryDestination(accountId, settlementMode) {
+  const config = loadPaymentConfig();
+  const normalizedSettlementMode = normalizeSettlementMode(settlementMode);
+  const mapEntry = normalizedSettlementMode && config.treasury_destinations_by_settlement_mode[normalizedSettlementMode]
+    ? config.treasury_destinations_by_settlement_mode[normalizedSettlementMode]
+    : null;
+  const destinationId = mapEntry && typeof mapEntry.destination_id === "string" && mapEntry.destination_id.trim()
+    ? mapEntry.destination_id.trim()
+    : config.treasury_destination_id;
+  if (!destinationId) {
+    return buildBsvTeranodeTreasuryDestination(accountId, normalizedSettlementMode);
+  }
+  return {
+    destination_id: destinationId,
+    destination_kind:
+      (mapEntry && typeof mapEntry.destination_kind === "string" && mapEntry.destination_kind.trim())
+      || config.treasury_destination_kind
+      || "merchant_treasury",
+    account_id:
+      (mapEntry && typeof mapEntry.account_id === "string" && mapEntry.account_id.trim())
+      || config.treasury_account_id
+      || accountId
+      || null,
+    settlement_mode: normalizedSettlementMode || null,
+    external_ref:
+      (mapEntry && typeof mapEntry.external_ref === "string" && mapEntry.external_ref.trim())
+      || config.treasury_external_ref
+      || null,
+    custody_ref: mapEntry && typeof mapEntry.custody_ref === "string" && mapEntry.custody_ref.trim()
+      ? mapEntry.custody_ref.trim()
+      : null,
+    reporting_ref: mapEntry && typeof mapEntry.reporting_ref === "string" && mapEntry.reporting_ref.trim()
+      ? mapEntry.reporting_ref.trim()
+      : null,
+    wallet_ref: mapEntry && typeof mapEntry.wallet_ref === "string" && mapEntry.wallet_ref.trim()
+      ? mapEntry.wallet_ref.trim()
+      : null,
+    provider_ref: mapEntry && typeof mapEntry.provider_ref === "string" && mapEntry.provider_ref.trim()
+      ? mapEntry.provider_ref.trim()
+      : null,
+    network: mapEntry && typeof mapEntry.network === "string" && mapEntry.network.trim()
+      ? mapEntry.network.trim()
+      : null,
+    chain_id: mapEntry && typeof mapEntry.chain_id === "string" && mapEntry.chain_id.trim()
+      ? mapEntry.chain_id.trim()
+      : null,
+    asset_symbol: mapEntry && typeof mapEntry.asset_symbol === "string" && mapEntry.asset_symbol.trim()
+      ? mapEntry.asset_symbol.trim()
+      : null,
+    policy_scope: mapEntry && typeof mapEntry.policy_scope === "string" && mapEntry.policy_scope.trim()
+      ? mapEntry.policy_scope.trim()
+      : null,
+    storage_class: mapEntry && typeof mapEntry.storage_class === "string" && mapEntry.storage_class.trim()
+      ? mapEntry.storage_class.trim()
+      : null
+  };
+}
+
+module.exports = {
+  buildConfiguredTreasuryDestination,
+  loadPaymentConfig
+};