xytara 3.1.0 → 3.1.2

package/lib/treasury_egress_policy_contract.js

@@ -1,91 +1,91 @@
-"use strict";
-
-const { buildOperatorTreasuryDestinationsPack } = require("./treasury_destinations_contract");
-
-const RAILS = [
-  "bsv_teranode",
-  "evm",
-  "base",
-  "usdc",
-  "dai",
-  "monero"
-];
-
-function buildRailPolicies() {
-  const operatorPack = buildOperatorTreasuryDestinationsPack();
-  const bySettlementMode = new Map(
-    (operatorPack.profiles || []).map((profile) => [profile.settlement_mode, profile])
-  );
-  return RAILS.map((settlementMode) => {
-    const profile = bySettlementMode.get(settlementMode) || null;
-    return {
-      settlement_mode: settlementMode,
-      destination_configured: Boolean(profile && profile.configured),
-      egress_posture: "manual_review_only",
-      autonomous_release_allowed: false,
-      manual_reason_required: true,
-      signoff_required: true,
-      outbound_default_state: "blocked",
-      policy_scope: profile && profile.compliance_posture ? profile.compliance_posture : null
-    };
-  });
-}
-
-function buildTreasuryEgressPolicyPack() {
-  const railPolicies = buildRailPolicies();
-  return {
-    product: "xytara",
-    category: "machine-commerce-treasury-egress-policy-pack",
-    pack_version: "xytara-treasury-egress-policy-pack-v1",
-    posture: "black_hole_treasury_easy_inbound_manual_review_only_outbound",
-    autonomous_release_allowed: false,
-    operator_review_required: true,
-    manual_reason_required: true,
-    default_policy: {
-      inbound_posture: "open_to_configured_payment_and_settlement_paths",
-      outbound_posture: "blocked_until_manual_review_and_signoff",
-      autonomous_release_allowed: false,
-      operator_review_required: true,
-      manual_reason_required: true,
-      treasury_justification_required: true,
-      refund_signal_is_not_payout_authority: true,
-      dual_control_recommended: true
-    },
-    rail_policies: railPolicies,
-    control_points: [
-      "payment-ledger",
-      "reconciliation-report",
-      "treasury-signoff-pack",
-      "rail-signoff-pack",
-      "refund-review",
-      "market-signoff-pack"
-    ],
-    linked_surfaces: {
-      treasury_destinations_operator_pack_ref: "/v1/treasury-destinations/operator-pack",
-      treasury_signoff_pack_ref_template: "/v1/economics/accounts/:account_id/treasury-signoff-pack",
-      rail_signoff_pack_ref_template: "/v1/economics/accounts/:account_id/rail-signoff-pack",
-      market_signoff_pack_ref: "/v1/economics/markets/signoff-pack",
-      payment_ledger_ref: "/v1/payment-ledger",
-      reconciliation_report_ref: "/v1/reconciliation-report"
-    },
-    operator_rule: "no_funds_leave_treasury_autonomously_without_clear_manual_reason_and_operator_review"
-  };
-}
-
-function summarizeTreasuryEgressPolicyPack() {
-  const pack = buildTreasuryEgressPolicyPack();
-  return {
-    product: "xytara",
-    category: "machine-commerce-treasury-egress-policy-pack-summary",
-    summary_version: "xytara-treasury-egress-policy-pack-summary-v1",
-    rail_policy_count: pack.rail_policies.length,
-    configured_rail_count: pack.rail_policies.filter((entry) => entry.destination_configured).length,
-    autonomous_release_allowed: pack.default_policy.autonomous_release_allowed,
-    linked_surfaces: pack.linked_surfaces
-  };
-}
-
-module.exports = {
-  buildTreasuryEgressPolicyPack,
-  summarizeTreasuryEgressPolicyPack
-};
+"use strict";
+
+const { buildOperatorTreasuryDestinationsPack } = require("./treasury_destinations_contract");
+
+const RAILS = [
+  "bsv_teranode",
+  "evm",
+  "base",
+  "usdc",
+  "dai",
+  "monero"
+];
+
+function buildRailPolicies() {
+  const operatorPack = buildOperatorTreasuryDestinationsPack();
+  const bySettlementMode = new Map(
+    (operatorPack.profiles || []).map((profile) => [profile.settlement_mode, profile])
+  );
+  return RAILS.map((settlementMode) => {
+    const profile = bySettlementMode.get(settlementMode) || null;
+    return {
+      settlement_mode: settlementMode,
+      destination_configured: Boolean(profile && profile.configured),
+      egress_posture: "manual_review_only",
+      autonomous_release_allowed: false,
+      manual_reason_required: true,
+      signoff_required: true,
+      outbound_default_state: "blocked",
+      policy_scope: profile && profile.compliance_posture ? profile.compliance_posture : null
+    };
+  });
+}
+
+function buildTreasuryEgressPolicyPack() {
+  const railPolicies = buildRailPolicies();
+  return {
+    product: "xytara",
+    category: "machine-commerce-treasury-egress-policy-pack",
+    pack_version: "xytara-treasury-egress-policy-pack-v1",
+    posture: "black_hole_treasury_easy_inbound_manual_review_only_outbound",
+    autonomous_release_allowed: false,
+    operator_review_required: true,
+    manual_reason_required: true,
+    default_policy: {
+      inbound_posture: "open_to_configured_payment_and_settlement_paths",
+      outbound_posture: "blocked_until_manual_review_and_signoff",
+      autonomous_release_allowed: false,
+      operator_review_required: true,
+      manual_reason_required: true,
+      treasury_justification_required: true,
+      refund_signal_is_not_payout_authority: true,
+      dual_control_recommended: true
+    },
+    rail_policies: railPolicies,
+    control_points: [
+      "payment-ledger",
+      "reconciliation-report",
+      "treasury-signoff-pack",
+      "rail-signoff-pack",
+      "refund-review",
+      "market-signoff-pack"
+    ],
+    linked_surfaces: {
+      treasury_destinations_operator_pack_ref: "/v1/treasury-destinations/operator-pack",
+      treasury_signoff_pack_ref_template: "/v1/economics/accounts/:account_id/treasury-signoff-pack",
+      rail_signoff_pack_ref_template: "/v1/economics/accounts/:account_id/rail-signoff-pack",
+      market_signoff_pack_ref: "/v1/economics/markets/signoff-pack",
+      payment_ledger_ref: "/v1/payment-ledger",
+      reconciliation_report_ref: "/v1/reconciliation-report"
+    },
+    operator_rule: "no_funds_leave_treasury_autonomously_without_clear_manual_reason_and_operator_review"
+  };
+}
+
+function summarizeTreasuryEgressPolicyPack() {
+  const pack = buildTreasuryEgressPolicyPack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-treasury-egress-policy-pack-summary",
+    summary_version: "xytara-treasury-egress-policy-pack-summary-v1",
+    rail_policy_count: pack.rail_policies.length,
+    configured_rail_count: pack.rail_policies.filter((entry) => entry.destination_configured).length,
+    autonomous_release_allowed: pack.default_policy.autonomous_release_allowed,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+module.exports = {
+  buildTreasuryEgressPolicyPack,
+  summarizeTreasuryEgressPolicyPack
+};

package/lib/treasury_lane_contract.js

@@ -1,84 +1,84 @@
-"use strict";
-
-const {
-  buildPhase9TreasuryConnectivityPack,
-  summarizePhase9TreasuryConnectivityPack
-} = require("./phase_9_treasury_connectivity_pack");
-const {
-  buildPhase9TreasuryContinuityPack,
-  summarizePhase9TreasuryContinuityPack
-} = require("./phase_9_treasury_continuity_pack");
-
-function buildTreasuryLanePack() {
-  return {
-    product: "xytara",
-    category: "machine-commerce-treasury-lane-pack",
-    pack_version: "xytara-treasury-lane-pack-v1",
-    lane_state: "first_party_treasury_connectivity_present",
-    posture: "native_treasury_connectivity_with_internal_reserve_doctrine",
-    phase_alignment: {
-      connectivity: {
-        pack: buildPhase9TreasuryConnectivityPack(),
-        summary: summarizePhase9TreasuryConnectivityPack()
-      },
-      continuity: {
-        pack: buildPhase9TreasuryContinuityPack(),
-        summary: summarizePhase9TreasuryContinuityPack()
-      }
-    },
-    reserve_doctrine: {
-      strategic_native_treasury: "bsv_teranode",
-      stable_operating_reserves: ["dai", "usdc"],
-      optional_hidden_privacy_reserve: "monero",
-      privacy_guardrails: [
-        "monero_is_never_the_public_treasury_identity",
-        "monero_is_never_required_for_normal_settlement_or_reporting",
-        "monero_remains_an_internal_optional_reserve_technique_only_where_policy_explicitly_allows_it"
-      ]
-    },
-    supported_surfaces: {
-      treasury_connectivity_summary_ref: "/v1/phases/phase-9/summary",
-      treasury_continuity_summary_ref: "/v1/phases/phase-9/treasury-continuity/summary",
-      treasury_destinations_summary_ref: "/v1/phases/phase-9/treasury-destinations/summary",
-      custody_refs_summary_ref: "/v1/phases/phase-9/custody-refs/summary",
-      operator_accounting_bridges_summary_ref: "/v1/phases/phase-9/operator-accounting-bridges/summary",
-      stablecoin_lane_ref: "/v1/stablecoins",
-      settlement_family_ref: "/v1/settlement"
-    },
-    first_run_flows: [
-      {
-        flow_ref: "treasury_connectivity_posture",
-        recommended_reason: "best first path for understanding how received funds can route through native, stable, and accounting-aware treasury posture",
-        sequence: [
-          "inspect_treasury_lane_summary",
-          "inspect_phase_9_connectivity_summary",
-          "inspect_treasury_destinations_and_custody_refs",
-          "align_native_and_stable_reserve_posture_to_operator_policy"
-        ]
-      }
-    ],
-    guardrails: [
-      "treasury posture should stay subordinate to compliant reporting and operator accounting surfaces",
-      "internal reserve doctrine should never distort the public runtime or settlement identity"
-    ]
-  };
-}
-
-function summarizeTreasuryLanePack() {
-  const pack = buildTreasuryLanePack();
-  return {
-    product: "xytara",
-    category: "machine-commerce-treasury-lane-pack-summary",
-    summary_version: "xytara-treasury-lane-pack-summary-v1",
-    lane_state: pack.lane_state,
-    strategic_native_treasury: pack.reserve_doctrine.strategic_native_treasury,
-    stable_reserve_count: pack.reserve_doctrine.stable_operating_reserves.length,
-    first_run_flow_count: pack.first_run_flows.length,
-    linked_surfaces: pack.supported_surfaces
-  };
-}
-
-module.exports = {
-  buildTreasuryLanePack,
-  summarizeTreasuryLanePack
-};
+"use strict";
+
+const {
+  buildPhase9TreasuryConnectivityPack,
+  summarizePhase9TreasuryConnectivityPack
+} = require("./phase_9_treasury_connectivity_pack");
+const {
+  buildPhase9TreasuryContinuityPack,
+  summarizePhase9TreasuryContinuityPack
+} = require("./phase_9_treasury_continuity_pack");
+
+function buildTreasuryLanePack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-treasury-lane-pack",
+    pack_version: "xytara-treasury-lane-pack-v1",
+    lane_state: "first_party_treasury_connectivity_present",
+    posture: "native_treasury_connectivity_with_internal_reserve_doctrine",
+    phase_alignment: {
+      connectivity: {
+        pack: buildPhase9TreasuryConnectivityPack(),
+        summary: summarizePhase9TreasuryConnectivityPack()
+      },
+      continuity: {
+        pack: buildPhase9TreasuryContinuityPack(),
+        summary: summarizePhase9TreasuryContinuityPack()
+      }
+    },
+    reserve_doctrine: {
+      strategic_native_treasury: "bsv_teranode",
+      stable_operating_reserves: ["dai", "usdc"],
+      optional_hidden_privacy_reserve: "monero",
+      privacy_guardrails: [
+        "monero_is_never_the_public_treasury_identity",
+        "monero_is_never_required_for_normal_settlement_or_reporting",
+        "monero_remains_an_internal_optional_reserve_technique_only_where_policy_explicitly_allows_it"
+      ]
+    },
+    supported_surfaces: {
+      treasury_connectivity_summary_ref: "/v1/phases/phase-9/summary",
+      treasury_continuity_summary_ref: "/v1/phases/phase-9/treasury-continuity/summary",
+      treasury_destinations_summary_ref: "/v1/phases/phase-9/treasury-destinations/summary",
+      custody_refs_summary_ref: "/v1/phases/phase-9/custody-refs/summary",
+      operator_accounting_bridges_summary_ref: "/v1/phases/phase-9/operator-accounting-bridges/summary",
+      stablecoin_lane_ref: "/v1/stablecoins",
+      settlement_family_ref: "/v1/settlement"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "treasury_connectivity_posture",
+        recommended_reason: "best first path for understanding how received funds can route through native, stable, and accounting-aware treasury posture",
+        sequence: [
+          "inspect_treasury_lane_summary",
+          "inspect_phase_9_connectivity_summary",
+          "inspect_treasury_destinations_and_custody_refs",
+          "align_native_and_stable_reserve_posture_to_operator_policy"
+        ]
+      }
+    ],
+    guardrails: [
+      "treasury posture should stay subordinate to compliant reporting and operator accounting surfaces",
+      "internal reserve doctrine should never distort the public runtime or settlement identity"
+    ]
+  };
+}
+
+function summarizeTreasuryLanePack() {
+  const pack = buildTreasuryLanePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-treasury-lane-pack-summary",
+    summary_version: "xytara-treasury-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    strategic_native_treasury: pack.reserve_doctrine.strategic_native_treasury,
+    stable_reserve_count: pack.reserve_doctrine.stable_operating_reserves.length,
+    first_run_flow_count: pack.first_run_flows.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildTreasuryLanePack,
+  summarizeTreasuryLanePack
+};

package/lib/trust_portability_boundary_contract.js

@@ -1,72 +1,72 @@
-"use strict";
-
-const packageJson = require("../package.json");
-
-function buildTrustPortabilityBoundaryContractPack() {
-  return {
-    ok: true,
-    product: packageJson.name,
-    category: "naxytra-trust-portability-boundary-contract",
-    pack_version: "naxytra-trust-portability-boundary-contract-v1",
-    doctrine: "xytara_treats_trust_portability_as_bounded_followthrough_and_not_as_global_identity_or_custody_truth",
-    model_state: "core_now",
-    core_claim: "trust portability is portable evidence across bounded axes, not universal authority or universal login truth",
-    portable_axes: [
-      { axis_id: "agent_identity_portability", axis_label: "agent identity portability", claim: "reviewable agent identity references can follow handoff and proof surfaces" },
-      { axis_id: "delegation_capability_portability", axis_label: "delegation and capability portability", claim: "delegated capability context can follow runtime-to-proof handoff" },
-      { axis_id: "delivery_history_portability", axis_label: "delivery history portability", claim: "result-package and delivery history can remain inspectable across proof review surfaces" },
-      { axis_id: "settlement_linked_trust_portability", axis_label: "settlement-linked trust portability", claim: "settlement and anchor context can remain reviewable without overclaiming chain truth" }
-    ],
-    non_claims: [
-      "global_login_truth",
-      "external_issuer_truth",
-      "session_authority_truth",
-      "runtime_execution_truth",
-      "custody_truth"
-    ],
-    evidence_requirements: [
-      "identity_interop_surface",
-      "auth_interop_surface",
-      "result_package_or_handoff_review_surface",
-      "proof_bridge_or_proof_followthrough_surface",
-      "receipt_or_verification_surface"
-    ],
-    linked_surfaces: {
-      identity_interop_ref: "/v1/identity-interop",
-      auth_interop_ref: "/v1/auth-profiles",
-      result_package_trust_ref: "/v1/result-package-trust",
-      proof_bridge_ref: "/v1/proof-center/bridge",
-      verification_services_ref: "/v1/proof-center/verification-services",
-      trust_continuity_ref: "/v1/phases/phase-4/trust-continuity"
-    },
-    claim_boundary: "claim_only_the_listed_portable_axes_and_listed_surfaces_without_claiming_universal_login_session_or_custody_truth"
-  };
-}
-
-function summarizeTrustPortabilityBoundaryContractPack() {
-  const pack = buildTrustPortabilityBoundaryContractPack();
-  return {
-    ok: true,
-    product: pack.product,
-    category: pack.category,
-    summary_version: "naxytra-trust-portability-boundary-contract-summary-v1",
-    pack_version: pack.pack_version,
-    model_state: pack.model_state,
-    portable_axis_count: pack.portable_axes.length,
-    non_claim_count: pack.non_claims.length,
-    evidence_requirement_count: pack.evidence_requirements.length,
-    linked_surfaces: pack.linked_surfaces
-  };
-}
-
-function getTrustPortabilityAxisDetail(axisId) {
-  const normalized = String(axisId || "").trim().toLowerCase();
-  return (buildTrustPortabilityBoundaryContractPack().portable_axes || []).find((entry) => entry.axis_id === normalized) || null;
-}
-
-module.exports = {
-  buildTrustPortabilityBoundaryContractPack,
-  summarizeTrustPortabilityBoundaryContractPack,
-  getTrustPortabilityAxisDetail
-};
-
+"use strict";
+
+const packageJson = require("../package.json");
+
+function buildTrustPortabilityBoundaryContractPack() {
+  return {
+    ok: true,
+    product: packageJson.name,
+    category: "naxytra-trust-portability-boundary-contract",
+    pack_version: "naxytra-trust-portability-boundary-contract-v1",
+    doctrine: "xytara_treats_trust_portability_as_bounded_followthrough_and_not_as_global_identity_or_custody_truth",
+    model_state: "core_now",
+    core_claim: "trust portability is portable evidence across bounded axes, not universal authority or universal login truth",
+    portable_axes: [
+      { axis_id: "agent_identity_portability", axis_label: "agent identity portability", claim: "reviewable agent identity references can follow handoff and proof surfaces" },
+      { axis_id: "delegation_capability_portability", axis_label: "delegation and capability portability", claim: "delegated capability context can follow runtime-to-proof handoff" },
+      { axis_id: "delivery_history_portability", axis_label: "delivery history portability", claim: "result-package and delivery history can remain inspectable across proof review surfaces" },
+      { axis_id: "settlement_linked_trust_portability", axis_label: "settlement-linked trust portability", claim: "settlement and anchor context can remain reviewable without overclaiming chain truth" }
+    ],
+    non_claims: [
+      "global_login_truth",
+      "external_issuer_truth",
+      "session_authority_truth",
+      "runtime_execution_truth",
+      "custody_truth"
+    ],
+    evidence_requirements: [
+      "identity_interop_surface",
+      "auth_interop_surface",
+      "result_package_or_handoff_review_surface",
+      "proof_bridge_or_proof_followthrough_surface",
+      "receipt_or_verification_surface"
+    ],
+    linked_surfaces: {
+      identity_interop_ref: "/v1/identity-interop",
+      auth_interop_ref: "/v1/auth-profiles",
+      result_package_trust_ref: "/v1/result-package-trust",
+      proof_bridge_ref: "/v1/proof-center/bridge",
+      verification_services_ref: "/v1/proof-center/verification-services",
+      trust_continuity_ref: "/v1/phases/phase-4/trust-continuity"
+    },
+    claim_boundary: "claim_only_the_listed_portable_axes_and_listed_surfaces_without_claiming_universal_login_session_or_custody_truth"
+  };
+}
+
+function summarizeTrustPortabilityBoundaryContractPack() {
+  const pack = buildTrustPortabilityBoundaryContractPack();
+  return {
+    ok: true,
+    product: pack.product,
+    category: pack.category,
+    summary_version: "naxytra-trust-portability-boundary-contract-summary-v1",
+    pack_version: pack.pack_version,
+    model_state: pack.model_state,
+    portable_axis_count: pack.portable_axes.length,
+    non_claim_count: pack.non_claims.length,
+    evidence_requirement_count: pack.evidence_requirements.length,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+function getTrustPortabilityAxisDetail(axisId) {
+  const normalized = String(axisId || "").trim().toLowerCase();
+  return (buildTrustPortabilityBoundaryContractPack().portable_axes || []).find((entry) => entry.axis_id === normalized) || null;
+}
+
+module.exports = {
+  buildTrustPortabilityBoundaryContractPack,
+  summarizeTrustPortabilityBoundaryContractPack,
+  getTrustPortabilityAxisDetail
+};
+

package/lib/x402_facilitator.js

@@ -0,0 +1,155 @@
+"use strict";
+
+// 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);
+
+  async function post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetch(`${url}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json", ...headers },
+        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 };
+    } 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" };
+  }
+  const requirementsForFacilitator = { ...paymentRequirements, resource: resourceUrl };
+  const verification = await facilitator.verify(paymentPayload, requirementsForFacilitator);
+  if (!verification.ok || !verification.json) {
+    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: verification.error || `facilitator verify returned HTTP ${verification.status}` };
+  }
+  if (verification.json.isValid !== true) {
+    return { ok: false, status: 402, reason: "payment_verification_failed", detail: normalizeString(verification.json.invalidReason) || "facilitator rejected the payment" };
+  }
+  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);
+  if (!settlement.ok || !settlement.json) {
+    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: settlement.error || `facilitator settle returned HTTP ${settlement.status}` };
+  }
+  if (settlement.json.success !== true) {
+    return { ok: false, status: 402, reason: "payment_settlement_failed", detail: normalizeString(settlement.json.errorReason) || "facilitator could not settle the payment" };
+  }
+  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
+};