xytara 3.1.13 → 3.1.14

package/lib/bolt_adapter.js

@@ -1,187 +1,187 @@
-"use strict";
-
-// Provider-agnostic BSV / UTXO (BOLT) adapter.
-//
-// Makes the BOLT lane a REAL on-chain rail: it verifies that a presented BSV
-// transaction (txid) pays the operator's address for at least the required
-// amount, by fetching the transaction from a configured BSV chain API. The txid
-// is the proof of payment; replay is prevented by treating each txid as
-// single-use. Engages only when env configures a provider; otherwise the caller
-// preserves the existing bespoke token scheme. Dependency-free (node http/https).
-//
-// Env:
-//   XYTARA_BOLT_PROVIDER = "whatsonchain" | "generic"   (unset => not configured)
-//   XYTARA_BOLT_PAYTO_ADDRESS   (operator BSV address that must be paid)
-//   XYTARA_BOLT_PRICE_SATS      (minimum amount, satoshis)
-//   XYTARA_BOLT_MIN_CONFIRMATIONS (default 0 => accept mempool)
-//   XYTARA_BOLT_NETWORK = "main" | "test" (default main)
-//   XYTARA_BOLT_ROOT_KEY | XYTARA_BOLT_SHARED_SECRET (HMAC key for the per-quote
-//                                                     amount offset; recommended)
-//   whatsonchain: API base defaults to https://api.whatsonchain.com/v1/bsv/<network>
-//   generic:      XYTARA_BOLT_API_URL (tx-by-hash base; "/tx/hash/<txid>" appended)
-
-// REQUEST BINDING (production-safe) & LIMITATIONS:
-//  - FLAT-RATE lane: the base price is a flat XYTARA_BOLT_PRICE_SATS (BSV sats
-//    cannot be derived from a USD quote without a rate oracle). Use for flat-priced
-//    calls; do not expose high-value, variably-priced commands on this lane.
-//  - Per-quote binding: the front advertises a UNIQUE required amount
-//    (priceSats + an unpredictable HMAC-derived offset) per quote and asks the
-//    payer to pay it EXACTLY. verifyBsvPayment with options.requiredSats then
-//    requires paidSats === requiredSats, so a pre-existing/unrelated payment to
-//    the operator address cannot be reused. Each txid is also single-use.
-//    (When called without requiredSats the legacy ">= priceSats" check applies.)
-
-const https = require("https");
-const http = require("http");
-const crypto = require("crypto");
-const { URL } = require("url");
-
-function env(name) {
-  const v = process.env[name];
-  return typeof v === "string" && v.trim() ? v.trim() : "";
-}
-
-function loadBoltConfig() {
-  const provider = env("XYTARA_BOLT_PROVIDER").toLowerCase();
-  if (provider !== "whatsonchain" && provider !== "generic") return { provider: null };
-  const network = (env("XYTARA_BOLT_NETWORK") || env("XYTARA_BSV_TERANODE_NETWORK") || "main")
-    .replace("mainnet", "main")
-    .replace("testnet", "test");
-  return {
-    provider,
-    network,
-    apiUrl: env("XYTARA_BOLT_API_URL") || (provider === "whatsonchain" ? `https://api.whatsonchain.com/v1/bsv/${network}` : ""),
-    payToAddress: env("XYTARA_BOLT_PAYTO_ADDRESS"),
-    priceSats: Number(env("XYTARA_BOLT_PRICE_SATS") || "") || null,
-    // Default to 1 confirmation so an unconfirmed (double-spendable) mempool tx is
-    // not accepted as proof of payment. An operator may explicitly set 0 to accept
-    // 0-conf at their own risk.
-    minConfirmations: env("XYTARA_BOLT_MIN_CONFIRMATIONS") === "" ? 1 : Math.max(0, Number(env("XYTARA_BOLT_MIN_CONFIRMATIONS")) || 0),
-    // Secret + window for the per-quote amount offset (request binding). A secret
-    // key is recommended so the offset is unpredictable; it falls back to the
-    // (public) payToAddress, which still binds via exact-amount + single-use.
-    bindingSecret: env("XYTARA_BOLT_ROOT_KEY") || env("XYTARA_BOLT_SHARED_SECRET") || (env("XYTARA_BOLT_PAYTO_ADDRESS") + "|" + network),
-    bindingWindowSats: Math.max(1, Number(env("XYTARA_BOLT_BINDING_WINDOW_SATS")) || 10000)
-  };
-}
-
-function isConfigured(config) {
-  return Boolean(config && config.provider);
-}
-
-// Deterministic unique required amount for a quote: base price + an HMAC-derived
-// offset in [0, bindingWindowSats). Both challenge and verify derive the same
-// value from the (stored, stable) quote, so the payer is told an exact amount and
-// the tx must pay it precisely.
-function computeRequiredSats(config, quote) {
-  const base = Number(config && config.priceSats) || 0;
-  if (!quote || !quote.quote_id) return base;
-  const mac = crypto.createHmac("sha256", String(config.bindingSecret || "")).update(String(quote.quote_id)).digest("hex");
-  const offset = parseInt(mac.slice(0, 8), 16) % Math.max(1, Number(config.bindingWindowSats) || 10000);
-  return base + offset;
-}
-
-function httpGetJson(urlStr, timeoutMs) {
-  return new Promise((resolve, reject) => {
-    let u;
-    try {
-      u = new URL(urlStr);
-    } catch (e) {
-      return reject(new Error("invalid_url"));
-    }
-    const lib = u.protocol === "http:" ? http : https;
-    const req = lib.request(
-      { method: "GET", hostname: u.hostname, port: u.port || (u.protocol === "http:" ? 80 : 443), path: u.pathname + u.search, headers: { Accept: "application/json" } },
-      (res) => {
-        let d = "";
-        res.on("data", (c) => (d += c));
-        res.on("end", () => {
-          let j = null;
-          try {
-            j = d ? JSON.parse(d) : null;
-          } catch (_) {
-            j = null;
-          }
-          resolve({ status: res.statusCode, json: j, raw: d });
-        });
-      }
-    );
-    req.on("error", reject);
-    req.setTimeout(timeoutMs || 15000, () => req.destroy(new Error("bolt_api_timeout")));
-    req.end();
-  });
-}
-
-// Collect the payout addresses declared on a vout's scriptPubKey across the
-// shapes different BSV APIs use.
-function voutAddresses(vout) {
-  const spk = (vout && vout.scriptPubKey) || {};
-  if (Array.isArray(spk.addresses)) return spk.addresses;
-  if (spk.address) return [spk.address];
-  if (Array.isArray(vout && vout.addresses)) return vout.addresses;
-  return [];
-}
-
-// Verify a BSV txid pays >= priceSats to payToAddress. Returns
-// { ok, txid, paid_sats, confirmations, network } | { ok:false, reason, detail? }.
-async function verifyBsvPayment(config, txid, fetchTxOverride, options) {
-  if (!isConfigured(config)) return { ok: false, reason: "bolt_provider_not_configured" };
-  if (!config.payToAddress || !config.priceSats) return { ok: false, reason: "bolt_payto_or_price_missing" };
-  if (!config.apiUrl) return { ok: false, reason: "bolt_api_url_missing" };
-  if (!/^[0-9a-fA-F]{64}$/.test(String(txid || ""))) return { ok: false, reason: "bolt_txid_invalid" };
-  const fetchTx = typeof fetchTxOverride === "function" ? fetchTxOverride : (u) => httpGetJson(u, 15000);
-  let res;
-  try {
-    res = await fetchTx(config.apiUrl.replace(/\/$/, "") + "/tx/hash/" + txid);
-  } catch (e) {
-    return { ok: false, reason: "bolt_api_unreachable", detail: e && e.message ? e.message : "request_error" };
-  }
-  if (!res.json || res.status >= 400) return { ok: false, reason: "bolt_tx_not_found", detail: `HTTP ${res.status}` };
-  const j = res.json;
-  const confirmations = Number(j.confirmations || 0);
-  if (config.minConfirmations > 0 && confirmations < config.minConfirmations) {
-    return { ok: false, reason: "bolt_insufficient_confirmations", detail: `${confirmations}/${config.minConfirmations}` };
-  }
-  const vouts = Array.isArray(j.vout) ? j.vout : [];
-  let paidSats = 0;
-  for (const o of vouts) {
-    if (voutAddresses(o).includes(config.payToAddress)) {
-      // BSV APIs report value in BSV; convert to satoshis.
-      paidSats += Math.round(Number(o.value || 0) * 1e8);
-    }
-  }
-  // Per-quote binding: when a unique required amount is supplied, the tx must pay
-  // it EXACTLY (not merely >=), so an unrelated payment to the address cannot be
-  // reused. Without it, fall back to the flat ">= priceSats" check.
-  const requiredSats = options && Number.isFinite(Number(options.requiredSats)) ? Math.round(Number(options.requiredSats)) : null;
-  if (requiredSats !== null) {
-    if (paidSats !== requiredSats) {
-      return { ok: false, reason: "bolt_amount_mismatch", detail: `${paidSats}/${requiredSats}` };
-    }
-  } else if (paidSats < config.priceSats) {
-    return { ok: false, reason: "bolt_amount_insufficient", detail: `${paidSats}/${config.priceSats}` };
-  }
-  return { ok: true, txid: String(txid), paid_sats: paidSats, confirmations, network: config.network, required_sats: requiredSats };
-}
-
-// Parse "BOLT <txid>" (64-hex). Returns { txid } | null.
-function parseBoltHeader(authorization) {
-  const m = String(authorization || "").match(/^BOLT\s+([0-9a-fA-F]{64})\s*$/);
-  return m ? { txid: m[1] } : null;
-}
-
-// The challenge an unpaid caller needs: where to pay and how much. When a
-// per-quote required amount is supplied, advertise that exact amount (the payer
-// must pay it precisely) instead of the flat base price.
-function buildBoltChallenge(config, options) {
-  const requiredSats = options && Number.isFinite(Number(options.requiredSats)) ? Math.round(Number(options.requiredSats)) : null;
-  return {
-    address: config.payToAddress,
-    amount_sats: requiredSats !== null ? requiredSats : config.priceSats,
-    exact: requiredSats !== null,
-    network: config.network,
-    min_confirmations: config.minConfirmations
-  };
-}
-
-module.exports = { loadBoltConfig, isConfigured, verifyBsvPayment, parseBoltHeader, buildBoltChallenge, computeRequiredSats };
+"use strict";
+
+// Provider-agnostic BSV / UTXO (BOLT) adapter.
+//
+// Makes the BOLT lane a REAL on-chain rail: it verifies that a presented BSV
+// transaction (txid) pays the operator's address for at least the required
+// amount, by fetching the transaction from a configured BSV chain API. The txid
+// is the proof of payment; replay is prevented by treating each txid as
+// single-use. Engages only when env configures a provider; otherwise the caller
+// preserves the existing bespoke token scheme. Dependency-free (node http/https).
+//
+// Env:
+//   XYTARA_BOLT_PROVIDER = "whatsonchain" | "generic"   (unset => not configured)
+//   XYTARA_BOLT_PAYTO_ADDRESS   (operator BSV address that must be paid)
+//   XYTARA_BOLT_PRICE_SATS      (minimum amount, satoshis)
+//   XYTARA_BOLT_MIN_CONFIRMATIONS (default 0 => accept mempool)
+//   XYTARA_BOLT_NETWORK = "main" | "test" (default main)
+//   XYTARA_BOLT_ROOT_KEY | XYTARA_BOLT_SHARED_SECRET (HMAC key for the per-quote
+//                                                     amount offset; recommended)
+//   whatsonchain: API base defaults to https://api.whatsonchain.com/v1/bsv/<network>
+//   generic:      XYTARA_BOLT_API_URL (tx-by-hash base; "/tx/hash/<txid>" appended)
+
+// REQUEST BINDING (production-safe) & LIMITATIONS:
+//  - FLAT-RATE lane: the base price is a flat XYTARA_BOLT_PRICE_SATS (BSV sats
+//    cannot be derived from a USD quote without a rate oracle). Use for flat-priced
+//    calls; do not expose high-value, variably-priced commands on this lane.
+//  - Per-quote binding: the front advertises a UNIQUE required amount
+//    (priceSats + an unpredictable HMAC-derived offset) per quote and asks the
+//    payer to pay it EXACTLY. verifyBsvPayment with options.requiredSats then
+//    requires paidSats === requiredSats, so a pre-existing/unrelated payment to
+//    the operator address cannot be reused. Each txid is also single-use.
+//    (When called without requiredSats the legacy ">= priceSats" check applies.)
+
+const https = require("https");
+const http = require("http");
+const crypto = require("crypto");
+const { URL } = require("url");
+
+function env(name) {
+  const v = process.env[name];
+  return typeof v === "string" && v.trim() ? v.trim() : "";
+}
+
+function loadBoltConfig() {
+  const provider = env("XYTARA_BOLT_PROVIDER").toLowerCase();
+  if (provider !== "whatsonchain" && provider !== "generic") return { provider: null };
+  const network = (env("XYTARA_BOLT_NETWORK") || env("XYTARA_BSV_TERANODE_NETWORK") || "main")
+    .replace("mainnet", "main")
+    .replace("testnet", "test");
+  return {
+    provider,
+    network,
+    apiUrl: env("XYTARA_BOLT_API_URL") || (provider === "whatsonchain" ? `https://api.whatsonchain.com/v1/bsv/${network}` : ""),
+    payToAddress: env("XYTARA_BOLT_PAYTO_ADDRESS"),
+    priceSats: Number(env("XYTARA_BOLT_PRICE_SATS") || "") || null,
+    // Default to 1 confirmation so an unconfirmed (double-spendable) mempool tx is
+    // not accepted as proof of payment. An operator may explicitly set 0 to accept
+    // 0-conf at their own risk.
+    minConfirmations: env("XYTARA_BOLT_MIN_CONFIRMATIONS") === "" ? 1 : Math.max(0, Number(env("XYTARA_BOLT_MIN_CONFIRMATIONS")) || 0),
+    // Secret + window for the per-quote amount offset (request binding). A secret
+    // key is recommended so the offset is unpredictable; it falls back to the
+    // (public) payToAddress, which still binds via exact-amount + single-use.
+    bindingSecret: env("XYTARA_BOLT_ROOT_KEY") || env("XYTARA_BOLT_SHARED_SECRET") || (env("XYTARA_BOLT_PAYTO_ADDRESS") + "|" + network),
+    bindingWindowSats: Math.max(1, Number(env("XYTARA_BOLT_BINDING_WINDOW_SATS")) || 10000)
+  };
+}
+
+function isConfigured(config) {
+  return Boolean(config && config.provider);
+}
+
+// Deterministic unique required amount for a quote: base price + an HMAC-derived
+// offset in [0, bindingWindowSats). Both challenge and verify derive the same
+// value from the (stored, stable) quote, so the payer is told an exact amount and
+// the tx must pay it precisely.
+function computeRequiredSats(config, quote) {
+  const base = Number(config && config.priceSats) || 0;
+  if (!quote || !quote.quote_id) return base;
+  const mac = crypto.createHmac("sha256", String(config.bindingSecret || "")).update(String(quote.quote_id)).digest("hex");
+  const offset = parseInt(mac.slice(0, 8), 16) % Math.max(1, Number(config.bindingWindowSats) || 10000);
+  return base + offset;
+}
+
+function httpGetJson(urlStr, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try {
+      u = new URL(urlStr);
+    } catch (e) {
+      return reject(new Error("invalid_url"));
+    }
+    const lib = u.protocol === "http:" ? http : https;
+    const req = lib.request(
+      { method: "GET", hostname: u.hostname, port: u.port || (u.protocol === "http:" ? 80 : 443), path: u.pathname + u.search, headers: { Accept: "application/json" } },
+      (res) => {
+        let d = "";
+        res.on("data", (c) => (d += c));
+        res.on("end", () => {
+          let j = null;
+          try {
+            j = d ? JSON.parse(d) : null;
+          } catch (_) {
+            j = null;
+          }
+          resolve({ status: res.statusCode, json: j, raw: d });
+        });
+      }
+    );
+    req.on("error", reject);
+    req.setTimeout(timeoutMs || 15000, () => req.destroy(new Error("bolt_api_timeout")));
+    req.end();
+  });
+}
+
+// Collect the payout addresses declared on a vout's scriptPubKey across the
+// shapes different BSV APIs use.
+function voutAddresses(vout) {
+  const spk = (vout && vout.scriptPubKey) || {};
+  if (Array.isArray(spk.addresses)) return spk.addresses;
+  if (spk.address) return [spk.address];
+  if (Array.isArray(vout && vout.addresses)) return vout.addresses;
+  return [];
+}
+
+// Verify a BSV txid pays >= priceSats to payToAddress. Returns
+// { ok, txid, paid_sats, confirmations, network } | { ok:false, reason, detail? }.
+async function verifyBsvPayment(config, txid, fetchTxOverride, options) {
+  if (!isConfigured(config)) return { ok: false, reason: "bolt_provider_not_configured" };
+  if (!config.payToAddress || !config.priceSats) return { ok: false, reason: "bolt_payto_or_price_missing" };
+  if (!config.apiUrl) return { ok: false, reason: "bolt_api_url_missing" };
+  if (!/^[0-9a-fA-F]{64}$/.test(String(txid || ""))) return { ok: false, reason: "bolt_txid_invalid" };
+  const fetchTx = typeof fetchTxOverride === "function" ? fetchTxOverride : (u) => httpGetJson(u, 15000);
+  let res;
+  try {
+    res = await fetchTx(config.apiUrl.replace(/\/$/, "") + "/tx/hash/" + txid);
+  } catch (e) {
+    return { ok: false, reason: "bolt_api_unreachable", detail: e && e.message ? e.message : "request_error" };
+  }
+  if (!res.json || res.status >= 400) return { ok: false, reason: "bolt_tx_not_found", detail: `HTTP ${res.status}` };
+  const j = res.json;
+  const confirmations = Number(j.confirmations || 0);
+  if (config.minConfirmations > 0 && confirmations < config.minConfirmations) {
+    return { ok: false, reason: "bolt_insufficient_confirmations", detail: `${confirmations}/${config.minConfirmations}` };
+  }
+  const vouts = Array.isArray(j.vout) ? j.vout : [];
+  let paidSats = 0;
+  for (const o of vouts) {
+    if (voutAddresses(o).includes(config.payToAddress)) {
+      // BSV APIs report value in BSV; convert to satoshis.
+      paidSats += Math.round(Number(o.value || 0) * 1e8);
+    }
+  }
+  // Per-quote binding: when a unique required amount is supplied, the tx must pay
+  // it EXACTLY (not merely >=), so an unrelated payment to the address cannot be
+  // reused. Without it, fall back to the flat ">= priceSats" check.
+  const requiredSats = options && Number.isFinite(Number(options.requiredSats)) ? Math.round(Number(options.requiredSats)) : null;
+  if (requiredSats !== null) {
+    if (paidSats !== requiredSats) {
+      return { ok: false, reason: "bolt_amount_mismatch", detail: `${paidSats}/${requiredSats}` };
+    }
+  } else if (paidSats < config.priceSats) {
+    return { ok: false, reason: "bolt_amount_insufficient", detail: `${paidSats}/${config.priceSats}` };
+  }
+  return { ok: true, txid: String(txid), paid_sats: paidSats, confirmations, network: config.network, required_sats: requiredSats };
+}
+
+// Parse "BOLT <txid>" (64-hex). Returns { txid } | null.
+function parseBoltHeader(authorization) {
+  const m = String(authorization || "").match(/^BOLT\s+([0-9a-fA-F]{64})\s*$/);
+  return m ? { txid: m[1] } : null;
+}
+
+// The challenge an unpaid caller needs: where to pay and how much. When a
+// per-quote required amount is supplied, advertise that exact amount (the payer
+// must pay it precisely) instead of the flat base price.
+function buildBoltChallenge(config, options) {
+  const requiredSats = options && Number.isFinite(Number(options.requiredSats)) ? Math.round(Number(options.requiredSats)) : null;
+  return {
+    address: config.payToAddress,
+    amount_sats: requiredSats !== null ? requiredSats : config.priceSats,
+    exact: requiredSats !== null,
+    network: config.network,
+    min_confirmations: config.minConfirmations
+  };
+}
+
+module.exports = { loadBoltConfig, isConfigured, verifyBsvPayment, parseBoltHeader, buildBoltChallenge, computeRequiredSats };