xytara 3.1.13 → 3.1.14

package/lib/payment_verification.js

@@ -1,357 +1,357 @@
-"use strict";
-
-const crypto = require("crypto");
-const { loadPaymentConfig } = require("./payment_config");
-const {
-  createFacilitatorClient,
-  verifyX402Payment,
-  settleX402Payment,
-  encodePaymentResponse
-} = require("./x402_facilitator");
-const { parseL402Authorization, verifyL402AccessToken } = require("./l402_payment_front");
-const { parseBoltAuthorization, verifyBoltAccessToken } = require("./bolt_payment_front");
-const { parseStripeMppAuthorization, verifyStripeMppAccessToken } = require("./stripe_mpp_payment_front");
-const {
-  buildBsvTeranodeSettlementHints,
-  extractBsvTeranodePaymentReference,
-  isBsvTeranodeSettlementMode,
-  normalizeSettlementMode
-} = require("./settlement_bsv_teranode");
-
-function decodeBase64UrlJson(value) {
-  try {
-    return JSON.parse(Buffer.from(String(value || ""), "base64url").toString("utf8"));
-  } catch (_) {
-    return null;
-  }
-}
-
-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 parseNativePaymentHeaders(headers) {
-  return {
-    wallet_id: headers["x-wallet-id"] || null,
-    encoded: headers["x-payment"] || null,
-    signature: headers["x-payment-signature"] || null,
-    scheme: "native"
-  };
-}
-
-function parseInstantPaymentHeaders(headers) {
-  const decoded = decodeBase64UrlJson(headers["payment-signature"]);
-  if (!decoded || typeof decoded !== "object") return null;
-  return {
-    wallet_id: decoded.wallet_id || null,
-    encoded: decoded.payload || null,
-    signature: decoded.signature || null,
-    scheme: decoded.scheme || "exact"
-  };
-}
-
-function parsePayment(headers, requiredHeaders, options) {
-  const required = Array.isArray(requiredHeaders) ? requiredHeaders : [];
-  const opts = options || {};
-  if (required.includes("authorization")) {
-    if (opts.authorization_scheme === "mpp" || opts.payment_protocol === "mpp") return parseStripeMppAuthorization(headers);
-    if (opts.authorization_scheme === "bolt" || opts.payment_protocol === "bolt") return parseBoltAuthorization(headers);
-    return parseL402Authorization(headers);
-  }
-  if (required.includes("payment-signature")) return parseInstantPaymentHeaders(headers);
-  return parseNativePaymentHeaders(headers);
-}
-
-function decodePaymentPayload(encoded) {
-  try {
-    return JSON.parse(Buffer.from(String(encoded || ""), "base64url").toString("utf8"));
-  } catch (_) {
-    return null;
-  }
-}
-
-function verifyPaymentPayloadAgainstQuote(paymentPayload, quote, walletId, maxAgeSeconds) {
-  if (!paymentPayload || typeof paymentPayload !== "object") {
-    return { ok: false, reason: "payment_payload_invalid" };
-  }
-  if (!paymentPayload.quote_id || paymentPayload.quote_id !== quote.quote_id) {
-    return { ok: false, reason: "payment_quote_mismatch" };
-  }
-  if (paymentPayload.amount_minor !== quote.amount_minor) {
-    return { ok: false, reason: "payment_amount_mismatch" };
-  }
-  if (paymentPayload.currency !== quote.currency) {
-    return { ok: false, reason: "payment_currency_mismatch" };
-  }
-  if (paymentPayload.account_id && paymentPayload.account_id !== quote.account_id) {
-    return { ok: false, reason: "payment_account_mismatch" };
-  }
-  if (walletId && paymentPayload.wallet_id && paymentPayload.wallet_id !== walletId) {
-    return { ok: false, reason: "payment_wallet_mismatch" };
-  }
-  if (
-    paymentPayload.settlement_mode &&
-    normalizeSettlementMode(paymentPayload.settlement_mode) !== normalizeSettlementMode(quote.settlement_mode)
-  ) {
-    return { ok: false, reason: "payment_settlement_mode_mismatch" };
-  }
-  if (
-    quote.settlement_binding_hash
-    && paymentPayload.settlement_binding_hash
-    && paymentPayload.settlement_binding_hash !== quote.settlement_binding_hash
-  ) {
-    return { ok: false, reason: "payment_settlement_binding_mismatch" };
-  }
-  if (isBsvTeranodeSettlementMode(quote.settlement_mode)) {
-    const settlementHints = buildBsvTeranodeSettlementHints({
-      settlementMode: quote.settlement_mode,
-      amountMinor: quote.amount_minor,
-      currency: quote.currency,
-      settlementBindingHash: quote.settlement_binding_hash,
-      treasuryDestination: quote.treasury
-    });
-    const bsvReference = extractBsvTeranodePaymentReference(paymentPayload);
-    if (bsvReference) {
-      if (bsvReference.network && settlementHints && bsvReference.network !== settlementHints.network) {
-        return { ok: false, reason: "payment_bsv_network_mismatch" };
-      }
-      if (
-        settlementHints &&
-        settlementHints.merchant_address &&
-        bsvReference.merchant_address &&
-        bsvReference.merchant_address !== settlementHints.merchant_address
-      ) {
-        return { ok: false, reason: "payment_bsv_merchant_address_mismatch" };
-      }
-      if (
-        settlementHints &&
-        settlementHints.merchant_paymail &&
-        bsvReference.merchant_paymail &&
-        bsvReference.merchant_paymail !== settlementHints.merchant_paymail
-      ) {
-        return { ok: false, reason: "payment_bsv_merchant_paymail_mismatch" };
-      }
-      if (
-        settlementHints &&
-        Number.isFinite(Number(bsvReference.amount_satoshis)) &&
-        Number(bsvReference.amount_satoshis) !== settlementHints.amount_satoshis
-      ) {
-        return { ok: false, reason: "payment_bsv_amount_mismatch" };
-      }
-      if (
-        settlementHints &&
-        bsvReference.settlement_reference &&
-        bsvReference.settlement_reference !== settlementHints.settlement_reference
-      ) {
-        return { ok: false, reason: "payment_bsv_reference_mismatch" };
-      }
-    }
-  }
-  if (!paymentPayload.nonce || typeof paymentPayload.nonce !== "string") {
-    return { ok: false, reason: "payment_nonce_missing" };
-  }
-  if (!paymentPayload.issued_at_iso || Number.isNaN(Date.parse(paymentPayload.issued_at_iso))) {
-    return { ok: false, reason: "payment_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: "payment_expired" };
-  }
-  return { ok: true, age_seconds: ageSeconds };
-}
-
-async function verifyPaymentAcceptance(state, headers, requiredHeaders, quote, options) {
-  const config = loadPaymentConfig();
-  const required = Array.isArray(requiredHeaders) ? requiredHeaders : [];
-  const opts = options || {};
-  // Trustless on-chain pay-per-call: the PAYMENT-SIGNATURE carries an x402 v2 payment,
-  // which a facilitator verifies and settles on-chain before any work runs. This path is
-  // opt-in (XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator) and fails closed if the
-  // facilitator is unreachable or the payment does not settle.
-  if (config.verification_mode === "x402_facilitator" && required.includes("payment-signature")) {
-    const h = headers || {};
-    const facilitator = createFacilitatorClient({
-      url: config.x402.facilitator_url,
-      headers: config.x402.facilitator_headers,
-      timeoutMs: config.x402.facilitator_timeout_ms,
-      cdp: config.x402.cdp
-    });
-    const auth = await verifyX402Payment({
-      paymentHeader: h["payment-signature"],
-      accepts: config.x402.accepts,
-      resourceUrl: opts.resource_url || null,
-      facilitator
-    });
-    if (!auth.ok) {
-      return { ok: false, status: auth.status || 402, reason: auth.reason, detail: auth.detail || null };
-    }
-    const authorizationView = {
-      ok: true,
-      verification_mode: "x402_facilitator",
-      wallet_id: auth.authorization.payer,
-      payment_payload: {
-        x402_payer: auth.authorization.payer,
-        x402_network: auth.authorization.paymentRequirements.network,
-        x402_asset: auth.authorization.paymentRequirements.asset,
-        x402_amount: auth.authorization.paymentRequirements.amount,
-        x402_pay_to: auth.authorization.paymentRequirements.payTo || null
-      }
-    };
-    // Deferred settlement: verify now, settle only AFTER execution succeeds, so a
-    // failed call is never settled/charged. The caller must call settleDeferredPayment
-    // on success. (The EIP-3009 authorization stays valid for maxTimeoutSeconds, so
-    // verify->execute->settle must complete within that window.)
-    if (opts.deferSettlement) {
-      return {
-        ...authorizationView,
-        settlement: null,
-        payment_response_base64: null,
-        deferred_settlement: {
-          protocol: "x402_facilitator",
-          authorization: auth.authorization,
-          facilitator,
-          settle: config.x402.settle
-        }
-      };
-    }
-    const settled = await settleX402Payment({ authorization: auth.authorization, facilitator, settle: config.x402.settle });
-    if (!settled.ok) {
-      return { ok: false, status: settled.status || 402, reason: settled.reason, detail: settled.detail || null };
-    }
-    return {
-      ...authorizationView,
-      settlement: settled.settlement,
-      payment_response_base64: encodePaymentResponse(settled.settlement)
-    };
-  }
-  if (required.includes("authorization")) {
-    if (opts.authorization_scheme === "mpp" || opts.payment_protocol === "mpp") {
-      return verifyStripeMppAccessToken(headers || {}, quote, state);
-    }
-    if (opts.authorization_scheme === "bolt" || opts.payment_protocol === "bolt") {
-      return verifyBoltAccessToken(headers || {}, quote, state);
-    }
-    return verifyL402AccessToken(headers || {}, quote, state);
-  }
-  const payment = parsePayment(headers || {}, requiredHeaders, opts);
-  // x402_facilitator only governs the x402 (payment-signature) routes, handled above.
-  // On the native and instant routes it falls back to local_signed, so enabling the mode
-  // adds trustless on-chain settlement without disabling the existing paid lanes.
-  const nativeMode = config.verification_mode === "x402_facilitator" ? "local_signed" : config.verification_mode;
-  if (nativeMode === "presence") {
-    return {
-      ok: true,
-      verification_mode: "presence",
-      wallet_id: payment && payment.wallet_id ? payment.wallet_id : null,
-      payment_payload: payment && payment.encoded ? decodePaymentPayload(payment.encoded) : null
-    };
-  }
-
-  if (nativeMode !== "local_signed") {
-    return {
-      ok: false,
-      status: 400,
-      reason: "payment_verification_mode_unsupported"
-    };
-  }
-
-  if (!payment || !payment.wallet_id || !payment.encoded || !payment.signature) {
-    return {
-      ok: false,
-      status: 402,
-      reason: "payment_headers_incomplete"
-    };
-  }
-
-  const walletEntry = config.wallet_registry.get(payment.wallet_id);
-  if (!walletEntry || walletEntry.enabled === false) {
-    return {
-      ok: false,
-      status: 403,
-      reason: "wallet_not_registered"
-    };
-  }
-
-  const expectedSignature = crypto.createHmac("sha256", walletEntry.secret).update(payment.encoded).digest("hex");
-  if (!safeEqualHex(expectedSignature, payment.signature)) {
-    return {
-      ok: false,
-      status: 403,
-      reason: "payment_signature_invalid"
-    };
-  }
-
-  const paymentPayload = decodePaymentPayload(payment.encoded);
-  const payloadValidation = verifyPaymentPayloadAgainstQuote(
-    paymentPayload,
-    quote,
-    payment.wallet_id,
-    config.payment_max_age_seconds
-  );
-  if (!payloadValidation.ok) {
-    return {
-      ok: false,
-      status: 403,
-      reason: payloadValidation.reason
-    };
-  }
-
-  if (state && state.acceptedPaymentNonces && state.acceptedPaymentNonces.has(paymentPayload.nonce)) {
-    return {
-      ok: false,
-      status: 409,
-      reason: "payment_nonce_replayed"
-    };
-  }
-
-  return {
-    ok: true,
-    verification_mode: "local_signed",
-    wallet_id: payment.wallet_id,
-    payment_payload: paymentPayload,
-    age_seconds: payloadValidation.age_seconds
-  };
-}
-
-function markPaymentAccepted(state, verification) {
-  if (
-    state
-    && state.acceptedPaymentNonces
-    && verification
-    && verification.payment_payload
-    && verification.payment_payload.nonce
-  ) {
-    state.acceptedPaymentNonces.add(verification.payment_payload.nonce);
-  }
-}
-
-// Settle a payment whose settlement was deferred until after successful execution
-// (see opts.deferSettlement). For verification results WITHOUT a deferred settlement
-// — native/credit schemes, and the external rails (L402/BOLT/MPP) whose funds already
-// moved before the proof was presented — this is a no-op success (nothing for us to
-// settle). Returns { ok, settlement?, payment_response_base64? } | { ok:false, status, reason, detail }.
-async function settleDeferredPayment(verification) {
-  const deferred = verification && verification.deferred_settlement;
-  if (!deferred) return { ok: true };
-  if (deferred.protocol === "x402_facilitator") {
-    const settled = await settleX402Payment({
-      authorization: deferred.authorization,
-      facilitator: deferred.facilitator,
-      settle: deferred.settle
-    });
-    if (!settled.ok) {
-      return { ok: false, status: settled.status || 402, reason: settled.reason, detail: settled.detail || null };
-    }
-    return { ok: true, settlement: settled.settlement, payment_response_base64: encodePaymentResponse(settled.settlement) };
-  }
-  return { ok: true };
-}
-
-module.exports = {
-  markPaymentAccepted,
-  settleDeferredPayment,
-  verifyPaymentAcceptance
-};
+"use strict";
+
+const crypto = require("crypto");
+const { loadPaymentConfig } = require("./payment_config");
+const {
+  createFacilitatorClient,
+  verifyX402Payment,
+  settleX402Payment,
+  encodePaymentResponse
+} = require("./x402_facilitator");
+const { parseL402Authorization, verifyL402AccessToken } = require("./l402_payment_front");
+const { parseBoltAuthorization, verifyBoltAccessToken } = require("./bolt_payment_front");
+const { parseStripeMppAuthorization, verifyStripeMppAccessToken } = require("./stripe_mpp_payment_front");
+const {
+  buildBsvTeranodeSettlementHints,
+  extractBsvTeranodePaymentReference,
+  isBsvTeranodeSettlementMode,
+  normalizeSettlementMode
+} = require("./settlement_bsv_teranode");
+
+function decodeBase64UrlJson(value) {
+  try {
+    return JSON.parse(Buffer.from(String(value || ""), "base64url").toString("utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+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 parseNativePaymentHeaders(headers) {
+  return {
+    wallet_id: headers["x-wallet-id"] || null,
+    encoded: headers["x-payment"] || null,
+    signature: headers["x-payment-signature"] || null,
+    scheme: "native"
+  };
+}
+
+function parseInstantPaymentHeaders(headers) {
+  const decoded = decodeBase64UrlJson(headers["payment-signature"]);
+  if (!decoded || typeof decoded !== "object") return null;
+  return {
+    wallet_id: decoded.wallet_id || null,
+    encoded: decoded.payload || null,
+    signature: decoded.signature || null,
+    scheme: decoded.scheme || "exact"
+  };
+}
+
+function parsePayment(headers, requiredHeaders, options) {
+  const required = Array.isArray(requiredHeaders) ? requiredHeaders : [];
+  const opts = options || {};
+  if (required.includes("authorization")) {
+    if (opts.authorization_scheme === "mpp" || opts.payment_protocol === "mpp") return parseStripeMppAuthorization(headers);
+    if (opts.authorization_scheme === "bolt" || opts.payment_protocol === "bolt") return parseBoltAuthorization(headers);
+    return parseL402Authorization(headers);
+  }
+  if (required.includes("payment-signature")) return parseInstantPaymentHeaders(headers);
+  return parseNativePaymentHeaders(headers);
+}
+
+function decodePaymentPayload(encoded) {
+  try {
+    return JSON.parse(Buffer.from(String(encoded || ""), "base64url").toString("utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+function verifyPaymentPayloadAgainstQuote(paymentPayload, quote, walletId, maxAgeSeconds) {
+  if (!paymentPayload || typeof paymentPayload !== "object") {
+    return { ok: false, reason: "payment_payload_invalid" };
+  }
+  if (!paymentPayload.quote_id || paymentPayload.quote_id !== quote.quote_id) {
+    return { ok: false, reason: "payment_quote_mismatch" };
+  }
+  if (paymentPayload.amount_minor !== quote.amount_minor) {
+    return { ok: false, reason: "payment_amount_mismatch" };
+  }
+  if (paymentPayload.currency !== quote.currency) {
+    return { ok: false, reason: "payment_currency_mismatch" };
+  }
+  if (paymentPayload.account_id && paymentPayload.account_id !== quote.account_id) {
+    return { ok: false, reason: "payment_account_mismatch" };
+  }
+  if (walletId && paymentPayload.wallet_id && paymentPayload.wallet_id !== walletId) {
+    return { ok: false, reason: "payment_wallet_mismatch" };
+  }
+  if (
+    paymentPayload.settlement_mode &&
+    normalizeSettlementMode(paymentPayload.settlement_mode) !== normalizeSettlementMode(quote.settlement_mode)
+  ) {
+    return { ok: false, reason: "payment_settlement_mode_mismatch" };
+  }
+  if (
+    quote.settlement_binding_hash
+    && paymentPayload.settlement_binding_hash
+    && paymentPayload.settlement_binding_hash !== quote.settlement_binding_hash
+  ) {
+    return { ok: false, reason: "payment_settlement_binding_mismatch" };
+  }
+  if (isBsvTeranodeSettlementMode(quote.settlement_mode)) {
+    const settlementHints = buildBsvTeranodeSettlementHints({
+      settlementMode: quote.settlement_mode,
+      amountMinor: quote.amount_minor,
+      currency: quote.currency,
+      settlementBindingHash: quote.settlement_binding_hash,
+      treasuryDestination: quote.treasury
+    });
+    const bsvReference = extractBsvTeranodePaymentReference(paymentPayload);
+    if (bsvReference) {
+      if (bsvReference.network && settlementHints && bsvReference.network !== settlementHints.network) {
+        return { ok: false, reason: "payment_bsv_network_mismatch" };
+      }
+      if (
+        settlementHints &&
+        settlementHints.merchant_address &&
+        bsvReference.merchant_address &&
+        bsvReference.merchant_address !== settlementHints.merchant_address
+      ) {
+        return { ok: false, reason: "payment_bsv_merchant_address_mismatch" };
+      }
+      if (
+        settlementHints &&
+        settlementHints.merchant_paymail &&
+        bsvReference.merchant_paymail &&
+        bsvReference.merchant_paymail !== settlementHints.merchant_paymail
+      ) {
+        return { ok: false, reason: "payment_bsv_merchant_paymail_mismatch" };
+      }
+      if (
+        settlementHints &&
+        Number.isFinite(Number(bsvReference.amount_satoshis)) &&
+        Number(bsvReference.amount_satoshis) !== settlementHints.amount_satoshis
+      ) {
+        return { ok: false, reason: "payment_bsv_amount_mismatch" };
+      }
+      if (
+        settlementHints &&
+        bsvReference.settlement_reference &&
+        bsvReference.settlement_reference !== settlementHints.settlement_reference
+      ) {
+        return { ok: false, reason: "payment_bsv_reference_mismatch" };
+      }
+    }
+  }
+  if (!paymentPayload.nonce || typeof paymentPayload.nonce !== "string") {
+    return { ok: false, reason: "payment_nonce_missing" };
+  }
+  if (!paymentPayload.issued_at_iso || Number.isNaN(Date.parse(paymentPayload.issued_at_iso))) {
+    return { ok: false, reason: "payment_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: "payment_expired" };
+  }
+  return { ok: true, age_seconds: ageSeconds };
+}
+
+async function verifyPaymentAcceptance(state, headers, requiredHeaders, quote, options) {
+  const config = loadPaymentConfig();
+  const required = Array.isArray(requiredHeaders) ? requiredHeaders : [];
+  const opts = options || {};
+  // Trustless on-chain pay-per-call: the PAYMENT-SIGNATURE carries an x402 v2 payment,
+  // which a facilitator verifies and settles on-chain before any work runs. This path is
+  // opt-in (XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator) and fails closed if the
+  // facilitator is unreachable or the payment does not settle.
+  if (config.verification_mode === "x402_facilitator" && required.includes("payment-signature")) {
+    const h = headers || {};
+    const facilitator = createFacilitatorClient({
+      url: config.x402.facilitator_url,
+      headers: config.x402.facilitator_headers,
+      timeoutMs: config.x402.facilitator_timeout_ms,
+      cdp: config.x402.cdp
+    });
+    const auth = await verifyX402Payment({
+      paymentHeader: h["payment-signature"],
+      accepts: config.x402.accepts,
+      resourceUrl: opts.resource_url || null,
+      facilitator
+    });
+    if (!auth.ok) {
+      return { ok: false, status: auth.status || 402, reason: auth.reason, detail: auth.detail || null };
+    }
+    const authorizationView = {
+      ok: true,
+      verification_mode: "x402_facilitator",
+      wallet_id: auth.authorization.payer,
+      payment_payload: {
+        x402_payer: auth.authorization.payer,
+        x402_network: auth.authorization.paymentRequirements.network,
+        x402_asset: auth.authorization.paymentRequirements.asset,
+        x402_amount: auth.authorization.paymentRequirements.amount,
+        x402_pay_to: auth.authorization.paymentRequirements.payTo || null
+      }
+    };
+    // Deferred settlement: verify now, settle only AFTER execution succeeds, so a
+    // failed call is never settled/charged. The caller must call settleDeferredPayment
+    // on success. (The EIP-3009 authorization stays valid for maxTimeoutSeconds, so
+    // verify->execute->settle must complete within that window.)
+    if (opts.deferSettlement) {
+      return {
+        ...authorizationView,
+        settlement: null,
+        payment_response_base64: null,
+        deferred_settlement: {
+          protocol: "x402_facilitator",
+          authorization: auth.authorization,
+          facilitator,
+          settle: config.x402.settle
+        }
+      };
+    }
+    const settled = await settleX402Payment({ authorization: auth.authorization, facilitator, settle: config.x402.settle });
+    if (!settled.ok) {
+      return { ok: false, status: settled.status || 402, reason: settled.reason, detail: settled.detail || null };
+    }
+    return {
+      ...authorizationView,
+      settlement: settled.settlement,
+      payment_response_base64: encodePaymentResponse(settled.settlement)
+    };
+  }
+  if (required.includes("authorization")) {
+    if (opts.authorization_scheme === "mpp" || opts.payment_protocol === "mpp") {
+      return verifyStripeMppAccessToken(headers || {}, quote, state);
+    }
+    if (opts.authorization_scheme === "bolt" || opts.payment_protocol === "bolt") {
+      return verifyBoltAccessToken(headers || {}, quote, state);
+    }
+    return verifyL402AccessToken(headers || {}, quote, state);
+  }
+  const payment = parsePayment(headers || {}, requiredHeaders, opts);
+  // x402_facilitator only governs the x402 (payment-signature) routes, handled above.
+  // On the native and instant routes it falls back to local_signed, so enabling the mode
+  // adds trustless on-chain settlement without disabling the existing paid lanes.
+  const nativeMode = config.verification_mode === "x402_facilitator" ? "local_signed" : config.verification_mode;
+  if (nativeMode === "presence") {
+    return {
+      ok: true,
+      verification_mode: "presence",
+      wallet_id: payment && payment.wallet_id ? payment.wallet_id : null,
+      payment_payload: payment && payment.encoded ? decodePaymentPayload(payment.encoded) : null
+    };
+  }
+
+  if (nativeMode !== "local_signed") {
+    return {
+      ok: false,
+      status: 400,
+      reason: "payment_verification_mode_unsupported"
+    };
+  }
+
+  if (!payment || !payment.wallet_id || !payment.encoded || !payment.signature) {
+    return {
+      ok: false,
+      status: 402,
+      reason: "payment_headers_incomplete"
+    };
+  }
+
+  const walletEntry = config.wallet_registry.get(payment.wallet_id);
+  if (!walletEntry || walletEntry.enabled === false) {
+    return {
+      ok: false,
+      status: 403,
+      reason: "wallet_not_registered"
+    };
+  }
+
+  const expectedSignature = crypto.createHmac("sha256", walletEntry.secret).update(payment.encoded).digest("hex");
+  if (!safeEqualHex(expectedSignature, payment.signature)) {
+    return {
+      ok: false,
+      status: 403,
+      reason: "payment_signature_invalid"
+    };
+  }
+
+  const paymentPayload = decodePaymentPayload(payment.encoded);
+  const payloadValidation = verifyPaymentPayloadAgainstQuote(
+    paymentPayload,
+    quote,
+    payment.wallet_id,
+    config.payment_max_age_seconds
+  );
+  if (!payloadValidation.ok) {
+    return {
+      ok: false,
+      status: 403,
+      reason: payloadValidation.reason
+    };
+  }
+
+  if (state && state.acceptedPaymentNonces && state.acceptedPaymentNonces.has(paymentPayload.nonce)) {
+    return {
+      ok: false,
+      status: 409,
+      reason: "payment_nonce_replayed"
+    };
+  }
+
+  return {
+    ok: true,
+    verification_mode: "local_signed",
+    wallet_id: payment.wallet_id,
+    payment_payload: paymentPayload,
+    age_seconds: payloadValidation.age_seconds
+  };
+}
+
+function markPaymentAccepted(state, verification) {
+  if (
+    state
+    && state.acceptedPaymentNonces
+    && verification
+    && verification.payment_payload
+    && verification.payment_payload.nonce
+  ) {
+    state.acceptedPaymentNonces.add(verification.payment_payload.nonce);
+  }
+}
+
+// Settle a payment whose settlement was deferred until after successful execution
+// (see opts.deferSettlement). For verification results WITHOUT a deferred settlement
+// — native/credit schemes, and the external rails (L402/BOLT/MPP) whose funds already
+// moved before the proof was presented — this is a no-op success (nothing for us to
+// settle). Returns { ok, settlement?, payment_response_base64? } | { ok:false, status, reason, detail }.
+async function settleDeferredPayment(verification) {
+  const deferred = verification && verification.deferred_settlement;
+  if (!deferred) return { ok: true };
+  if (deferred.protocol === "x402_facilitator") {
+    const settled = await settleX402Payment({
+      authorization: deferred.authorization,
+      facilitator: deferred.facilitator,
+      settle: deferred.settle
+    });
+    if (!settled.ok) {
+      return { ok: false, status: settled.status || 402, reason: settled.reason, detail: settled.detail || null };
+    }
+    return { ok: true, settlement: settled.settlement, payment_response_base64: encodePaymentResponse(settled.settlement) };
+  }
+  return { ok: true };
+}
+
+module.exports = {
+  markPaymentAccepted,
+  settleDeferredPayment,
+  verifyPaymentAcceptance
+};