xytara 2.5.0 → 2.6.0

package/lib/go_live_operator_pack.js

@@ -0,0 +1,339 @@
+"use strict";
+
+const packageJson = require("../package.json");
+const {
+  buildCapabilityExecutionTruthBundle,
+  buildCapabilityCommercializationSummary
+} = require("./capability_execution_truth");
+const { buildPaymentProtocolStrategyPack } = require("./payment_protocol_contract");
+const { summarizeTreasuryDestinationsPack } = require("./treasury_destinations_contract");
+const { loadExecutionTargetRegistry } = require("./external_execution_runtime");
+const { buildCheckoutEventSecuritySummary } = require("./checkout_event_security");
+const {
+  buildOperatorIntelligencePack,
+  summarizeOperatorIntelligencePack
+} = require("./operator_intelligence");
+
+function normalizeFunction(fn, fallback) {
+  return typeof fn === "function" ? fn : fallback;
+}
+
+function buildDefaultRuntimeDurability() {
+  return {
+    ok: true,
+    recovery_posture: "unknown",
+    blockers: ["runtime_durability_unavailable"],
+    operator_guidance: "inspect /v1/runtime/durability from the live service to confirm persistence posture"
+  };
+}
+
+function buildDefaultSettlementReadiness() {
+  return {
+    ok: true,
+    ready: false,
+    runtime_mode: "unknown",
+    blockers: ["native_settlement_readiness_unavailable"],
+    next_manual_inputs: ["inspect_live_service_settlement_readiness"]
+  };
+}
+
+function rankBlockerSeverity(blocker) {
+  if (typeof blocker !== "string" || blocker.length === 0) return "medium";
+  if (
+    blocker.includes("missing")
+    || blocker.includes("failed")
+    || blocker.includes("unreachable")
+    || blocker.includes("not_ready")
+    || blocker.includes("not_writable")
+    || blocker.includes("mock")
+    || blocker.includes("too_weak")
+  ) {
+    return "high";
+  }
+  return "medium";
+}
+
+function buildBlockingIssues(executionTruth, commercialization, runtimeDurability, settlementReadiness, treasurySummary, checkoutSecurity) {
+  const issues = [];
+
+  (Array.isArray(runtimeDurability.blockers) ? runtimeDurability.blockers : []).forEach((blocker) => {
+    issues.push({
+      lane: "runtime_durability",
+      severity: rankBlockerSeverity(blocker),
+      blocker,
+      reason: runtimeDurability.operator_guidance || "runtime durability requires operator review",
+      ref: "/v1/runtime/durability"
+    });
+  });
+
+  (Array.isArray(settlementReadiness.blockers) ? settlementReadiness.blockers : []).forEach((blocker) => {
+    issues.push({
+      lane: "native_settlement",
+      severity: rankBlockerSeverity(blocker),
+      blocker,
+      reason: "native settlement readiness still has blocking configuration gaps",
+      ref: "/v1/settlement/bsv-teranode/readiness"
+    });
+  });
+
+  if (Number(treasurySummary.configured_profile_count || 0) < 1) {
+    issues.push({
+      lane: "treasury_destinations",
+      severity: "high",
+      blocker: "treasury_destinations_unconfigured",
+      reason: "no treasury destination profile is configured with a real landing reference",
+      ref: "/v1/treasury-destinations"
+    });
+  }
+
+  if (Number(executionTruth.counts.provider_wiring_required_count || 0) > 0) {
+    issues.push({
+      lane: "provider_execution",
+      severity: "high",
+      blocker: "provider_execution_targets_missing",
+      reason: `${executionTruth.counts.provider_wiring_required_count} capability lane(s) still need execution target bindings`,
+      ref: "/v1/capability-registry/execution-truth"
+    });
+  }
+
+  if (Number(executionTruth.counts.operator_classification_required_count || 0) > 0) {
+    issues.push({
+      lane: "capability_classification",
+      severity: "medium",
+      blocker: "capability_classification_incomplete",
+      reason: `${executionTruth.counts.operator_classification_required_count} capability lane(s) still require execution classification`,
+      ref: "/v1/capability-registry/execution-truth"
+    });
+  }
+
+  if (Number(commercialization.counts.hold_until_classified || 0) > 0) {
+    issues.push({
+      lane: "commercialization",
+      severity: "medium",
+      blocker: "catalog_items_not_ready_for_public_sale",
+      reason: `${commercialization.counts.hold_until_classified} capability lane(s) should stay off live public sale surfaces`,
+      ref: "/v1/capability-registry/commercialization-summary"
+    });
+  }
+
+  (Array.isArray(checkoutSecurity.blockers) ? checkoutSecurity.blockers : []).forEach((blocker) => {
+    issues.push({
+      lane: "hosted_checkout_ingress",
+      severity: rankBlockerSeverity(blocker),
+      blocker,
+      reason: checkoutSecurity.operator_guidance || "hosted checkout ingress security requires operator review",
+      ref: "/v1/checkout/events/security"
+    });
+  });
+
+  return issues;
+}
+
+function buildNextActions(blockingIssues, operatorIntelligence, executionTruth, treasurySummary, settlementReadiness) {
+  const actions = [];
+
+  if (blockingIssues.some((issue) => issue.blocker === "treasury_destinations_unconfigured")) {
+    actions.push({
+      priority: "high",
+      action: "configure_treasury_destinations",
+      reason: "real money should not land until treasury destinations are explicitly configured",
+      refs: [
+        "/v1/treasury-destinations",
+        "/v1/treasury-destinations/operator-pack"
+      ]
+    });
+  }
+
+  if (blockingIssues.some((issue) => issue.blocker === "provider_execution_targets_missing")) {
+    const providerRequiredTasks = (Array.isArray(executionTruth.tasks) ? executionTruth.tasks : [])
+      .filter((task) => task.execution_truth === "provider_wiring_required")
+      .map((task) => task.task_ref);
+    actions.push({
+      priority: "high",
+      action: "bind_provider_execution_targets",
+      reason: `provider-backed execution is still missing for ${providerRequiredTasks.join(", ") || "one or more capability lanes"}`,
+      refs: [
+        "/v1/capability-registry/execution-truth",
+        "/v1/capability-registry/commercialization-summary"
+      ]
+    });
+  }
+
+  if (settlementReadiness.ready !== true) {
+    actions.push({
+      priority: "high",
+      action: "close_native_settlement_inputs",
+      reason: `native settlement readiness is blocked by ${(settlementReadiness.blockers || []).join(", ") || "unresolved inputs"}`,
+      refs: [
+        "/v1/settlement/bsv-teranode/readiness",
+        "/v1/settlement/bsv-teranode"
+      ]
+    });
+  }
+
+  if (blockingIssues.some((issue) => issue.lane === "hosted_checkout_ingress")) {
+    actions.push({
+      priority: "high",
+      action: "configure_checkout_webhook_verification",
+      reason: "hosted checkout event ingress should be signed before xytara trusts payment-state transitions",
+      refs: [
+        "/v1/checkout/events/security",
+        "/v1/stripe-mpp"
+      ]
+    });
+  }
+
+  if (Number(treasurySummary.explicit_per_rail_configured_count || 0) < 1) {
+    actions.push({
+      priority: "medium",
+      action: "upgrade_from_fallback_to_per_rail_treasury_profiles",
+      reason: "explicit per-rail treasury profiles strengthen reconciliation and public claim integrity",
+      refs: [
+        "/v1/treasury-destinations",
+        "/v1/treasury-destinations/operator-pack"
+      ]
+    });
+  }
+
+  if (operatorIntelligence && operatorIntelligence.recommended_operator_motion) {
+    actions.push({
+      priority: operatorIntelligence.overall_operator_state && operatorIntelligence.overall_operator_state.top_priority
+        ? operatorIntelligence.overall_operator_state.top_priority
+        : "medium",
+      action: operatorIntelligence.recommended_operator_motion,
+      reason: "current operator intelligence indicates this as the next best runtime or adoption move",
+      refs: [
+        "/v1/operator-intelligence",
+        `/v1/economics/accounts/${encodeURIComponent(operatorIntelligence.account_id || "acct_demo")}/operator-dashboard`
+      ]
+    });
+  }
+
+  if (actions.length === 0) {
+    actions.push({
+      priority: "low",
+      action: "run_first_live_money_flow",
+      reason: "core launch blockers are cleared enough to run a first live end-to-end production transaction",
+      refs: [
+        "/v1/payment-ledger",
+        "/v1/activity-ledger",
+        "/v1/reconciliation-report"
+      ]
+    });
+  }
+
+  return actions;
+}
+
+function buildGoLiveOperatorPack(state, input, options) {
+  const payload = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const accountId = String(payload.account_id || "acct_demo").trim() || "acct_demo";
+  const runtimeDurabilityBuilder = normalizeFunction(options && options.buildRuntimeDurabilitySummary, buildDefaultRuntimeDurability);
+  const settlementReadinessBuilder = normalizeFunction(options && options.buildNativeSettlementReadinessSummary, buildDefaultSettlementReadiness);
+
+  const executionTruth = buildCapabilityExecutionTruthBundle();
+  const commercialization = buildCapabilityCommercializationSummary();
+  const paymentStrategy = buildPaymentProtocolStrategyPack();
+  const treasurySummary = summarizeTreasuryDestinationsPack();
+  const checkoutSecurity = buildCheckoutEventSecuritySummary();
+  const runtimeDurability = runtimeDurabilityBuilder();
+  const settlementReadiness = settlementReadinessBuilder();
+  const operatorIntelligence = buildOperatorIntelligencePack(state, { account_id: accountId });
+  const executionTargets = loadExecutionTargetRegistry();
+  const blockingIssues = buildBlockingIssues(
+    executionTruth,
+    commercialization,
+    runtimeDurability,
+    settlementReadiness,
+    treasurySummary,
+    checkoutSecurity
+  );
+  const nextActions = buildNextActions(
+    blockingIssues,
+    operatorIntelligence,
+    executionTruth,
+    treasurySummary,
+    settlementReadiness
+  );
+
+  return {
+    ok: true,
+    product: packageJson.name,
+    category: "machine-commerce-go-live-operator-pack",
+    pack_version: "xytara-go-live-operator-pack-v1",
+    account_id: accountId,
+    go_live_state: blockingIssues.length === 0 ? "launch_ready_for_first_live_money_flow" : "launch_blocked_pending_operator_closeout",
+    launch_posture: {
+      public_capability_count: executionTruth.counts.task_count,
+      self_serve_live_now_count: commercialization.counts.self_serve_live_now,
+      operator_enabled_after_config_count: commercialization.counts.operator_enabled_after_config,
+      configured_execution_target_count: executionTargets.length,
+      configured_treasury_profile_count: treasurySummary.configured_profile_count,
+      explicit_per_rail_treasury_profile_count: treasurySummary.explicit_per_rail_configured_count,
+      runtime_recovery_posture: runtimeDurability.recovery_posture,
+      native_settlement_ready: settlementReadiness.ready === true,
+      checkout_ingress_security_ready: checkoutSecurity.ready === true
+    },
+    payment_posture: {
+      machine_primary: paymentStrategy.primary_machine_payment_front || null,
+      repeat_use_primary: paymentStrategy.primary_repeat_use_payment_front || null,
+      human_primary: paymentStrategy.human_and_enterprise_procurement_front || null,
+      external_front_count: Array.isArray(paymentStrategy.adapter_ready_external_fronts)
+        ? paymentStrategy.adapter_ready_external_fronts.length
+        : 0
+    },
+    blocking_issues: blockingIssues,
+    next_actions: nextActions,
+    launch_sequence: [
+      "configure_treasury_and_wallet_security",
+      "bind_provider_execution_targets_for_external_capability_lanes",
+      "close_native_settlement_readiness_inputs",
+      "confirm_persistent_runtime_storage_and_recovery",
+      "run_first_live_end_to_end_money_flow",
+      "watch_activity_payment_and_reconciliation_surfaces"
+    ],
+    linked_surfaces: {
+      capability_execution_truth_ref: "/v1/capability-registry/execution-truth",
+      commercialization_summary_ref: "/v1/capability-registry/commercialization-summary",
+      payment_strategy_ref: "/v1/payment-protocols/strategy",
+      payment_fronts_ref: "/v1/payment-fronts",
+      checkout_event_security_ref: "/v1/checkout/events/security",
+      treasury_ref: "/v1/treasury-destinations",
+      native_settlement_ref: "/v1/settlement/bsv-teranode/readiness",
+      runtime_durability_ref: "/v1/runtime/durability",
+      operator_intelligence_ref: "/v1/operator-intelligence",
+      payment_ledger_ref: "/v1/payment-ledger",
+      reconciliation_ref: "/v1/reconciliation-report"
+    },
+    supporting_summaries: {
+      capability_counts: executionTruth.counts,
+      commercialization_counts: commercialization.counts,
+      treasury_summary: treasurySummary,
+      checkout_event_security: checkoutSecurity,
+      runtime_durability: runtimeDurability,
+      native_settlement: settlementReadiness,
+      operator_intelligence: summarizeOperatorIntelligencePack(state, { account_id: accountId })
+    }
+  };
+}
+
+function summarizeGoLiveOperatorPack(state, input, options) {
+  const pack = buildGoLiveOperatorPack(state, input, options);
+  return {
+    ok: true,
+    product: pack.product,
+    category: pack.category,
+    pack_version: pack.pack_version,
+    account_id: pack.account_id,
+    go_live_state: pack.go_live_state,
+    blocking_issue_count: pack.blocking_issues.length,
+    top_action: pack.next_actions[0] || null,
+    launch_posture: pack.launch_posture,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+module.exports = {
+  buildGoLiveOperatorPack,
+  summarizeGoLiveOperatorPack
+};

package/lib/http_transport.js

@@ -34,7 +34,39 @@ function readJsonBody(req) {
   });
 }
 
+function readJsonBodyWithRaw(req) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk;
+      if (body.length > 1024 * 1024) {
+        reject(new Error("request body too large"));
+        req.destroy();
+      }
+    });
+    req.on("end", () => {
+      if (!body) {
+        resolve({
+          body: {},
+          raw_body: ""
+        });
+        return;
+      }
+      try {
+        resolve({
+          body: JSON.parse(body),
+          raw_body: body
+        });
+      } catch (error) {
+        reject(new Error("body must be valid JSON"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
 module.exports = {
   readJsonBody,
+  readJsonBodyWithRaw,
   sendJson
 };

package/lib/integration_matrix_contract.js

@@ -7,6 +7,8 @@ const { summarizeMcpLanePack } = require("./mcp_lane_contract");
 const { summarizeA2ALanePack } = require("./a2a_lane_contract");
 const { summarizeA2CLanePack } = require("./a2c_lane_contract");
 const { summarizeX402LanePack } = require("./x402_lane_contract");
+const { summarizeL402LanePack } = require("./l402_lane_contract");
+const { summarizeBoltLanePack } = require("./bolt_lane_contract");
 const { summarizeSettlementLanePack } = require("./settlement_lane_contract");
 const { summarizeStablecoinLanePack } = require("./stablecoin_lane_contract");
 const { summarizeMajorRailsLanePack } = require("./major_rails_lane_contract");
@@ -41,6 +43,8 @@ function buildIntegrationMatrixPack(integrations = []) {
       a2a: summarizeA2ALanePack(),
       a2c: summarizeA2CLanePack(),
       x402: summarizeX402LanePack(),
+      l402: summarizeL402LanePack(),
+      bolt: summarizeBoltLanePack(),
       settlement: summarizeSettlementLanePack(),
       stablecoins: summarizeStablecoinLanePack(),
       major_rails: summarizeMajorRailsLanePack(),
@@ -60,6 +64,8 @@ function buildIntegrationMatrixPack(integrations = []) {
       framework_lane_ref: "/v1/frameworks",
       protocol_lane_ref: "/v1/protocols",
       mcp_lane_ref: "/v1/mcp",
+      l402_lane_ref: "/v1/l402",
+      bolt_lane_ref: "/v1/bolt",
       settlement_lane_ref: "/v1/settlement",
       event_system_lane_ref: "/v1/event-systems",
       telemetry_lane_ref: "/v1/telemetry",

package/lib/l402_lane_contract.js

@@ -0,0 +1,55 @@
+"use strict";
+
+function buildL402LanePack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-l402-lane-pack",
+    pack_version: "xytara-l402-lane-pack-v1",
+    lane_state: "adapter_front_contract_present",
+    posture: "lightning_plus_http_402_permissionless_payment_front",
+    settlement_family: "bitcoin_lightning",
+    auth_family: "macaroon_scoped_access",
+    role_in_xytara: "optional_permissionless_machine_payment_front",
+    supported_surfaces: {
+      security_ref: "/v1/l402/security",
+      commands_execute_ref: "/l402/commands/execute",
+      mcp_invoke_ref: "/l402/mcp/tools/invoke",
+      payment_protocols_ref: "/v1/payment-protocols",
+      payment_protocol_strategy_ref: "/v1/payment-protocols/strategy",
+      capability_commercialization_ref: "/v1/capability-registry/commercialization-summary",
+      execution_truth_ref: "/v1/capability-registry/execution-truth"
+    },
+    integration_rules: [
+      "use L402 as an adapter payment front into the same execution, proof, and governance core",
+      "do not fork runtime semantics by payment front",
+      "bind Lightning-native verification and access issuance through an adapter or gateway layer"
+    ],
+    recommended_uses: [
+      "permission-sensitive agents",
+      "micropayment-heavy workloads",
+      "operators who want lower dependency on card or stablecoin facilitators"
+    ],
+    non_claims: [
+      "not claimed as the launch-default machine payment lane",
+      "not claimed as a built-in first-party Lightning settlement runtime today"
+    ]
+  };
+}
+
+function summarizeL402LanePack() {
+  const pack = buildL402LanePack();
+  return {
+    product: pack.product,
+    category: pack.category,
+    summary_version: "xytara-l402-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 = {
+  buildL402LanePack,
+  summarizeL402LanePack
+};

package/lib/l402_payment_front.js

@@ -0,0 +1,192 @@
+"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 loadL402FrontConfig() {
+  const sharedSecret = normalizeString(process.env.XYTARA_L402_SHARED_SECRET);
+  return {
+    enabled: String(process.env.XYTARA_L402_ENABLED || (sharedSecret ? "true" : "false")).trim().toLowerCase() !== "false",
+    shared_secret: sharedSecret || null,
+    max_age_seconds: Math.max(30, Number(process.env.XYTARA_L402_MAX_AGE_SECONDS || 300) || 300),
+    required_headers: ["authorization"],
+    auth_scheme: "L402",
+    token_shape: "base64url_json_with_macaroon_and_hmac_signed_payload"
+  };
+}
+
+function parseL402Authorization(headers) {
+  const authorization = headers && typeof headers.authorization === "string"
+    ? headers.authorization.trim()
+    : "";
+  const match = authorization.match(/^L402\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 || "l402_gateway",
+    encoded: decoded.payload || null,
+    signature: decoded.signature || null,
+    macaroon: decoded.macaroon || null,
+    invoice_id: decoded.invoice_id || null,
+    preimage_hash: decoded.preimage_hash || null,
+    scheme: "l402"
+  };
+}
+
+function verifyL402PaymentPayload(paymentPayload, quote, walletId, maxAgeSeconds) {
+  if (!paymentPayload || typeof paymentPayload !== "object") {
+    return { ok: false, reason: "l402_payload_invalid" };
+  }
+  if (!paymentPayload.quote_id || paymentPayload.quote_id !== quote.quote_id) {
+    return { ok: false, reason: "l402_quote_mismatch" };
+  }
+  if (paymentPayload.amount_minor !== quote.amount_minor) {
+    return { ok: false, reason: "l402_amount_mismatch" };
+  }
+  if (paymentPayload.currency !== quote.currency) {
+    return { ok: false, reason: "l402_currency_mismatch" };
+  }
+  if (paymentPayload.account_id && paymentPayload.account_id !== quote.account_id) {
+    return { ok: false, reason: "l402_account_mismatch" };
+  }
+  if (walletId && paymentPayload.wallet_id && paymentPayload.wallet_id !== walletId) {
+    return { ok: false, reason: "l402_wallet_mismatch" };
+  }
+  if (!paymentPayload.nonce || typeof paymentPayload.nonce !== "string") {
+    return { ok: false, reason: "l402_nonce_missing" };
+  }
+  if (!paymentPayload.issued_at_iso || Number.isNaN(Date.parse(paymentPayload.issued_at_iso))) {
+    return { ok: false, reason: "l402_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: "l402_token_expired" };
+  }
+  if (!normalizeString(paymentPayload.macaroon_id || paymentPayload.macaroon)) {
+    return { ok: false, reason: "l402_macaroon_missing" };
+  }
+  if (!normalizeString(paymentPayload.invoice_id || paymentPayload.invoice_reference)) {
+    return { ok: false, reason: "l402_invoice_reference_missing" };
+  }
+  return { ok: true, age_seconds: ageSeconds };
+}
+
+function verifyL402AccessToken(headers, quote) {
+  const config = loadL402FrontConfig();
+  if (!config.enabled) {
+    return {
+      ok: false,
+      status: 503,
+      reason: "l402_not_enabled"
+    };
+  }
+  if (!config.shared_secret) {
+    return {
+      ok: false,
+      status: 503,
+      reason: "l402_shared_secret_missing"
+    };
+  }
+  const payment = parseL402Authorization(headers || {});
+  if (!payment || !payment.encoded || !payment.signature || !payment.macaroon) {
+    return {
+      ok: false,
+      status: 402,
+      reason: "l402_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: "l402_signature_invalid"
+    };
+  }
+  const payload = decodeBase64UrlJson(payment.encoded);
+  const validation = verifyL402PaymentPayload(payload, quote, payment.wallet_id, config.max_age_seconds);
+  if (!validation.ok) {
+    return {
+      ok: false,
+      status: 403,
+      reason: validation.reason
+    };
+  }
+  return {
+    ok: true,
+    verification_mode: "l402_gateway_signed",
+    wallet_id: payment.wallet_id,
+    payment_payload: payload,
+    age_seconds: validation.age_seconds,
+    l402: {
+      macaroon: payment.macaroon,
+      invoice_id: payment.invoice_id || payload.invoice_id || null,
+      preimage_hash: payment.preimage_hash || payload.preimage_hash || null
+    }
+  };
+}
+
+function buildL402SecuritySummary() {
+  const config = loadL402FrontConfig();
+  const blockers = [];
+  if (config.enabled && !config.shared_secret) blockers.push("l402_shared_secret_missing");
+  return {
+    ok: true,
+    category: "machine-commerce-l402-security-summary",
+    summary_version: "xytara-l402-security-summary-v1",
+    enabled: config.enabled,
+    shared_secret_configured: Boolean(config.shared_secret),
+    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: {
+      l402_lane_ref: "/v1/l402",
+      commands_execute_ref: "/l402/commands/execute",
+      mcp_invoke_ref: "/l402/mcp/tools/invoke"
+    }
+  };
+}
+
+function buildL402ChallengePayload(quote) {
+  return {
+    ok: false,
+    payment_required: {
+      scheme: "l402",
+      quote,
+      operator_requirements: {
+        auth_scheme: "L402",
+        token_shape: "base64url_json_with_macaroon_and_hmac_signed_payload",
+        security_ref: "/v1/l402/security"
+      }
+    }
+  };
+}
+
+module.exports = {
+  buildL402ChallengePayload,
+  buildL402SecuritySummary,
+  loadL402FrontConfig,
+  parseL402Authorization,
+  verifyL402AccessToken
+};