xytara 3.1.0 → 3.1.2

package/lib/bolt_lane_contract.js

@@ -1,55 +1,55 @@
-"use strict";
-
-function buildBoltLanePack() {
-  return {
-    product: "xytara",
-    category: "machine-commerce-bolt-lane-pack",
-    pack_version: "xytara-bolt-lane-pack-v1",
-    lane_state: "adapter_front_contract_present",
-    posture: "utxo_native_or_spv_provable_payment_front",
-    settlement_family: "utxo_native_settlement",
-    proof_family: "spv_or_block_header_verifiable_payment_proof",
-    role_in_xytara: "optional_permissionless_payment_and_proof_front",
-    supported_surfaces: {
-      security_ref: "/v1/bolt/security",
-      commands_execute_ref: "/bolt/commands/execute",
-      mcp_invoke_ref: "/bolt/mcp/tools/invoke",
-      payment_protocols_ref: "/v1/payment-protocols",
-      payment_protocol_strategy_ref: "/v1/payment-protocols/strategy",
-      settlement_lane_ref: "/v1/settlement",
-      execution_truth_ref: "/v1/capability-registry/execution-truth"
-    },
-    integration_rules: [
-      "treat BOLT-style or UTXO-SPV payment fronts as adapter lanes into the same execution core",
-      "keep settlement proof and runtime proof composable rather than hardwiring one chain ideology into the package",
-      "bind chain-specific proof verification through explicit adapters or settlement runtimes"
-    ],
-    recommended_uses: [
-      "operators who want stronger peer-to-peer payment properties",
-      "architectures that value block-header or SPV-verifiable settlement proof",
-      "ecosystems that prefer native UTXO payment models"
-    ],
-    non_claims: [
-      "not claimed as a first-party launch-default lane",
-      "not claimed as fully bound unless operator-configured against a real runtime"
-    ]
-  };
-}
-
-function summarizeBoltLanePack() {
-  const pack = buildBoltLanePack();
-  return {
-    product: pack.product,
-    category: pack.category,
-    summary_version: "xytara-bolt-lane-pack-summary-v1",
-    lane_state: pack.lane_state,
-    posture: pack.posture,
-    supported_surface_count: Object.keys(pack.supported_surfaces).length,
-    linked_surfaces: pack.supported_surfaces
-  };
-}
-
-module.exports = {
-  buildBoltLanePack,
-  summarizeBoltLanePack
-};
+"use strict";
+
+function buildBoltLanePack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-bolt-lane-pack",
+    pack_version: "xytara-bolt-lane-pack-v1",
+    lane_state: "adapter_front_contract_present",
+    posture: "utxo_native_or_spv_provable_payment_front",
+    settlement_family: "utxo_native_settlement",
+    proof_family: "spv_or_block_header_verifiable_payment_proof",
+    role_in_xytara: "optional_permissionless_payment_and_proof_front",
+    supported_surfaces: {
+      security_ref: "/v1/bolt/security",
+      commands_execute_ref: "/bolt/commands/execute",
+      mcp_invoke_ref: "/bolt/mcp/tools/invoke",
+      payment_protocols_ref: "/v1/payment-protocols",
+      payment_protocol_strategy_ref: "/v1/payment-protocols/strategy",
+      settlement_lane_ref: "/v1/settlement",
+      execution_truth_ref: "/v1/capability-registry/execution-truth"
+    },
+    integration_rules: [
+      "treat BOLT-style or UTXO-SPV payment fronts as adapter lanes into the same execution core",
+      "keep settlement proof and runtime proof composable rather than hardwiring one chain ideology into the package",
+      "bind chain-specific proof verification through explicit adapters or settlement runtimes"
+    ],
+    recommended_uses: [
+      "operators who want stronger peer-to-peer payment properties",
+      "architectures that value block-header or SPV-verifiable settlement proof",
+      "ecosystems that prefer native UTXO payment models"
+    ],
+    non_claims: [
+      "not claimed as a first-party launch-default lane",
+      "not claimed as fully bound unless operator-configured against a real runtime"
+    ]
+  };
+}
+
+function summarizeBoltLanePack() {
+  const pack = buildBoltLanePack();
+  return {
+    product: pack.product,
+    category: pack.category,
+    summary_version: "xytara-bolt-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    posture: pack.posture,
+    supported_surface_count: Object.keys(pack.supported_surfaces).length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildBoltLanePack,
+  summarizeBoltLanePack
+};

package/lib/bolt_payment_front.js

@@ -1,172 +1,172 @@
-"use strict";
-
-const crypto = require("crypto");
-
-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 };
-}
-
-function verifyBoltAccessToken(headers, quote) {
-  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) {
-  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");
+
+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 };
+}
+
+function verifyBoltAccessToken(headers, quote) {
+  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) {
+  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
+};