xytara 3.1.13 → 3.1.15

package/lib/l402_adapter.js

@@ -1,241 +1,241 @@
-"use strict";
-
-// Provider-agnostic Lightning (L402) adapter.
-//
-// Makes the L402 lane a REAL Lightning rail: it creates bolt11 invoices through a
-// configured Lightning provider and verifies payment CRYPTOGRAPHICALLY
-// (preimage -> sha256 -> payment_hash). The macaroon is an HMAC-signed token that
-// binds the invoice's payment_hash; the runtime issues and verifies it, and the
-// client treats it as opaque and echoes it back with the preimage (standard L402
-// flow). Preimage verification needs no node — only invoice creation does.
-//
-// Engages only when env configures a provider; otherwise every function reports
-// not-configured and the caller preserves the existing bespoke token behavior.
-// Dependency-free (node http/https + crypto).
-//
-// Env:
-//   XYTARA_L402_PROVIDER = "lnbits" | "generic"        (unset => not configured)
-//   XYTARA_L402_ROOT_KEY                                (HMAC key for macaroons)
-//   XYTARA_L402_PRICE_SATS            (default invoice amount, sats)
-//   XYTARA_L402_MACAROON_TTL_SECONDS  (default 900)
-//   lnbits:  XYTARA_LNBITS_URL, XYTARA_LNBITS_INVOICE_KEY
-//   generic: XYTARA_L402_INVOICE_URL, XYTARA_L402_INVOICE_AUTH_HEADER ("Header: value")
-
-// SECURITY / LIMITATIONS (harden before enabling in production):
-//  - FLAT-RATE lane: each call is priced at a flat XYTARA_L402_PRICE_SATS, not
-//    the per-request USD quote amount (sats cannot be derived from USD without a
-//    rate oracle). Use for flat-priced calls.
-//  - DoS surface: each UNPAID request triggers a live invoice creation against
-//    the configured Lightning provider. Deploy the L402 routes behind rate
-//    limiting / a cheap pre-challenge gate so an unauthenticated flood cannot
-//    amplify into unbounded outbound invoice creation.
-
-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 loadL402Config() {
-  const provider = env("XYTARA_L402_PROVIDER").toLowerCase();
-  if (provider !== "lnbits" && provider !== "generic") return { provider: null };
-  return {
-    provider,
-    rootKey: env("XYTARA_L402_ROOT_KEY") || env("XYTARA_L402_SHARED_SECRET"),
-    priceSats: Number(env("XYTARA_L402_PRICE_SATS") || "") || null,
-    macaroonTtlSeconds: Math.max(60, Number(env("XYTARA_L402_MACAROON_TTL_SECONDS") || 900) || 900),
-    lnbitsUrl: env("XYTARA_LNBITS_URL"),
-    lnbitsInvoiceKey: env("XYTARA_LNBITS_INVOICE_KEY"),
-    genericInvoiceUrl: env("XYTARA_L402_INVOICE_URL"),
-    genericAuthHeader: env("XYTARA_L402_INVOICE_AUTH_HEADER")
-  };
-}
-
-function isConfigured(config) {
-  return Boolean(config && config.provider);
-}
-
-function httpPostJson(urlStr, headers, bodyObj, timeoutMs) {
-  return new Promise((resolve, reject) => {
-    let u;
-    try {
-      u = new URL(urlStr);
-    } catch (e) {
-      return reject(new Error("invalid_url"));
-    }
-    const body = JSON.stringify(bodyObj || {});
-    const lib = u.protocol === "http:" ? http : https;
-    const req = lib.request(
-      {
-        method: "POST",
-        hostname: u.hostname,
-        port: u.port || (u.protocol === "http:" ? 80 : 443),
-        path: u.pathname + u.search,
-        headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body), ...(headers || {}) }
-      },
-      (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("l402_invoice_timeout")));
-    req.write(body);
-    req.end();
-  });
-}
-
-// Create a real bolt11 invoice. Returns { ok, payment_request, payment_hash } | { ok:false, reason, detail? }.
-async function createLightningInvoice(config, options) {
-  if (!isConfigured(config)) return { ok: false, reason: "l402_provider_not_configured" };
-  const sats = Number((options && options.amountSats) || config.priceSats);
-  if (!Number.isFinite(sats) || sats <= 0) return { ok: false, reason: "invalid_amount_sats" };
-  const memo = (options && options.memo) || "naxytra L402";
-  if (config.provider === "lnbits") {
-    if (!config.lnbitsUrl || !config.lnbitsInvoiceKey) return { ok: false, reason: "lnbits_not_configured" };
-    let res;
-    try {
-      res = await httpPostJson(
-        config.lnbitsUrl.replace(/\/$/, "") + "/api/v1/payments",
-        { "X-Api-Key": config.lnbitsInvoiceKey },
-        { out: false, amount: Math.round(sats), memo },
-        15000
-      );
-    } catch (e) {
-      return { ok: false, reason: "lnbits_unreachable", detail: e && e.message ? e.message : "request_error" };
-    }
-    if (!res.json || res.status >= 400) {
-      return { ok: false, reason: "lnbits_invoice_failed", detail: (res.json && (res.json.detail || res.json.message)) || `HTTP ${res.status}` };
-    }
-    const pr = res.json.payment_request || res.json.bolt11;
-    const ph = res.json.payment_hash || res.json.checking_id;
-    if (!pr || !ph) return { ok: false, reason: "lnbits_invoice_missing_fields" };
-    return { ok: true, payment_request: pr, payment_hash: ph };
-  }
-  if (config.provider === "generic") {
-    if (!config.genericInvoiceUrl) return { ok: false, reason: "generic_invoice_url_missing" };
-    const headers = {};
-    if (config.genericAuthHeader) {
-      const i = config.genericAuthHeader.indexOf(":");
-      if (i > 0) headers[config.genericAuthHeader.slice(0, i).trim()] = config.genericAuthHeader.slice(i + 1).trim();
-    }
-    let res;
-    try {
-      res = await httpPostJson(config.genericInvoiceUrl, headers, { amount_sats: Math.round(sats), memo }, 15000);
-    } catch (e) {
-      return { ok: false, reason: "generic_invoice_unreachable", detail: e && e.message ? e.message : "request_error" };
-    }
-    if (!res.json || res.status >= 400) return { ok: false, reason: "generic_invoice_failed", detail: `HTTP ${res.status}` };
-    const pr = res.json.payment_request || res.json.bolt11 || res.json.invoice;
-    const ph = res.json.payment_hash;
-    if (!pr || !ph) return { ok: false, reason: "generic_invoice_missing_fields" };
-    return { ok: true, payment_request: pr, payment_hash: ph };
-  }
-  return { ok: false, reason: "unsupported_provider" };
-}
-
-function b64url(buf) {
-  return Buffer.from(buf).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function b64urlDecode(s) {
-  s = String(s).replace(/-/g, "+").replace(/_/g, "/");
-  while (s.length % 4) s += "=";
-  return Buffer.from(s, "base64");
-}
-
-// Issue an HMAC-signed macaroon binding a payment_hash. Returns "<payload>.<sig>" or null.
-function issueL402Macaroon(config, options) {
-  if (!config || !config.rootKey) return null;
-  const payload = {
-    ph: String(options && options.payment_hash),
-    exp: Math.floor(Date.now() / 1000) + config.macaroonTtlSeconds,
-    nonce: b64url(crypto.randomBytes(12)),
-    amt: (options && options.amountSats) || null
-  };
-  const encoded = b64url(JSON.stringify(payload));
-  const sig = crypto.createHmac("sha256", config.rootKey).update(encoded, "utf8").digest("hex");
-  return `${encoded}.${sig}`;
-}
-
-// Verify macaroon integrity + expiry. Returns { ok, payment_hash } | { ok:false, reason }.
-function verifyL402Macaroon(config, macaroon) {
-  if (!config || !config.rootKey) return { ok: false, reason: "l402_root_key_missing" };
-  const parts = String(macaroon || "").split(".");
-  if (parts.length !== 2) return { ok: false, reason: "l402_macaroon_malformed" };
-  const [encoded, sig] = parts;
-  const expected = crypto.createHmac("sha256", config.rootKey).update(encoded, "utf8").digest("hex");
-  let ok = false;
-  try {
-    ok = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex"));
-  } catch (_) {
-    ok = false;
-  }
-  if (!ok) return { ok: false, reason: "l402_macaroon_signature_invalid" };
-  let payload;
-  try {
-    payload = JSON.parse(b64urlDecode(encoded).toString("utf8"));
-  } catch (_) {
-    return { ok: false, reason: "l402_macaroon_payload_invalid" };
-  }
-  if (!payload.ph) return { ok: false, reason: "l402_macaroon_no_payment_hash" };
-  if (payload.exp && Math.floor(Date.now() / 1000) > Number(payload.exp)) return { ok: false, reason: "l402_macaroon_expired" };
-  return { ok: true, payment_hash: String(payload.ph) };
-}
-
-// Does preimage (hex) hash (sha256) to payment_hash (hex)? This is the real proof of payment.
-function verifyPreimage(preimageHex, paymentHashHex) {
-  try {
-    const h = crypto.createHash("sha256").update(Buffer.from(String(preimageHex), "hex")).digest("hex");
-    return h.toLowerCase() === String(paymentHashHex).toLowerCase();
-  } catch (_) {
-    return false;
-  }
-}
-
-// Parse "L402 <macaroon>:<preimage>" (also tolerates the legacy "LSAT" scheme).
-function parseL402Header(authorization) {
-  const m = String(authorization || "").match(/^(?:L402|LSAT)\s+([^:\s]+):([0-9a-fA-F]+)\s*$/);
-  if (!m) return null;
-  return { macaroon: m[1], preimage: m[2] };
-}
-
-function buildWwwAuthenticate(macaroon, invoice) {
-  return `L402 macaroon="${macaroon}", invoice="${invoice}"`;
-}
-
-// Full verification of an L402 Authorization header.
-// Returns { ok, payment_hash, preimage } | { ok:false, reason }.
-function verifyL402Authorization(config, authorization) {
-  if (!isConfigured(config)) return { ok: false, reason: "l402_provider_not_configured" };
-  const parsed = parseL402Header(authorization);
-  if (!parsed) return { ok: false, reason: "l402_authorization_malformed" };
-  const mac = verifyL402Macaroon(config, parsed.macaroon);
-  if (!mac.ok) return mac;
-  if (!verifyPreimage(parsed.preimage, mac.payment_hash)) return { ok: false, reason: "l402_preimage_mismatch" };
-  return { ok: true, payment_hash: mac.payment_hash, preimage: parsed.preimage };
-}
-
-module.exports = {
-  loadL402Config,
-  isConfigured,
-  createLightningInvoice,
-  issueL402Macaroon,
-  verifyL402Macaroon,
-  verifyPreimage,
-  parseL402Header,
-  buildWwwAuthenticate,
-  verifyL402Authorization
-};
+"use strict";
+
+// Provider-agnostic Lightning (L402) adapter.
+//
+// Makes the L402 lane a REAL Lightning rail: it creates bolt11 invoices through a
+// configured Lightning provider and verifies payment CRYPTOGRAPHICALLY
+// (preimage -> sha256 -> payment_hash). The macaroon is an HMAC-signed token that
+// binds the invoice's payment_hash; the runtime issues and verifies it, and the
+// client treats it as opaque and echoes it back with the preimage (standard L402
+// flow). Preimage verification needs no node — only invoice creation does.
+//
+// Engages only when env configures a provider; otherwise every function reports
+// not-configured and the caller preserves the existing bespoke token behavior.
+// Dependency-free (node http/https + crypto).
+//
+// Env:
+//   XYTARA_L402_PROVIDER = "lnbits" | "generic"        (unset => not configured)
+//   XYTARA_L402_ROOT_KEY                                (HMAC key for macaroons)
+//   XYTARA_L402_PRICE_SATS            (default invoice amount, sats)
+//   XYTARA_L402_MACAROON_TTL_SECONDS  (default 900)
+//   lnbits:  XYTARA_LNBITS_URL, XYTARA_LNBITS_INVOICE_KEY
+//   generic: XYTARA_L402_INVOICE_URL, XYTARA_L402_INVOICE_AUTH_HEADER ("Header: value")
+
+// SECURITY / LIMITATIONS (harden before enabling in production):
+//  - FLAT-RATE lane: each call is priced at a flat XYTARA_L402_PRICE_SATS, not
+//    the per-request USD quote amount (sats cannot be derived from USD without a
+//    rate oracle). Use for flat-priced calls.
+//  - DoS surface: each UNPAID request triggers a live invoice creation against
+//    the configured Lightning provider. Deploy the L402 routes behind rate
+//    limiting / a cheap pre-challenge gate so an unauthenticated flood cannot
+//    amplify into unbounded outbound invoice creation.
+
+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 loadL402Config() {
+  const provider = env("XYTARA_L402_PROVIDER").toLowerCase();
+  if (provider !== "lnbits" && provider !== "generic") return { provider: null };
+  return {
+    provider,
+    rootKey: env("XYTARA_L402_ROOT_KEY") || env("XYTARA_L402_SHARED_SECRET"),
+    priceSats: Number(env("XYTARA_L402_PRICE_SATS") || "") || null,
+    macaroonTtlSeconds: Math.max(60, Number(env("XYTARA_L402_MACAROON_TTL_SECONDS") || 900) || 900),
+    lnbitsUrl: env("XYTARA_LNBITS_URL"),
+    lnbitsInvoiceKey: env("XYTARA_LNBITS_INVOICE_KEY"),
+    genericInvoiceUrl: env("XYTARA_L402_INVOICE_URL"),
+    genericAuthHeader: env("XYTARA_L402_INVOICE_AUTH_HEADER")
+  };
+}
+
+function isConfigured(config) {
+  return Boolean(config && config.provider);
+}
+
+function httpPostJson(urlStr, headers, bodyObj, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try {
+      u = new URL(urlStr);
+    } catch (e) {
+      return reject(new Error("invalid_url"));
+    }
+    const body = JSON.stringify(bodyObj || {});
+    const lib = u.protocol === "http:" ? http : https;
+    const req = lib.request(
+      {
+        method: "POST",
+        hostname: u.hostname,
+        port: u.port || (u.protocol === "http:" ? 80 : 443),
+        path: u.pathname + u.search,
+        headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body), ...(headers || {}) }
+      },
+      (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("l402_invoice_timeout")));
+    req.write(body);
+    req.end();
+  });
+}
+
+// Create a real bolt11 invoice. Returns { ok, payment_request, payment_hash } | { ok:false, reason, detail? }.
+async function createLightningInvoice(config, options) {
+  if (!isConfigured(config)) return { ok: false, reason: "l402_provider_not_configured" };
+  const sats = Number((options && options.amountSats) || config.priceSats);
+  if (!Number.isFinite(sats) || sats <= 0) return { ok: false, reason: "invalid_amount_sats" };
+  const memo = (options && options.memo) || "naxytra L402";
+  if (config.provider === "lnbits") {
+    if (!config.lnbitsUrl || !config.lnbitsInvoiceKey) return { ok: false, reason: "lnbits_not_configured" };
+    let res;
+    try {
+      res = await httpPostJson(
+        config.lnbitsUrl.replace(/\/$/, "") + "/api/v1/payments",
+        { "X-Api-Key": config.lnbitsInvoiceKey },
+        { out: false, amount: Math.round(sats), memo },
+        15000
+      );
+    } catch (e) {
+      return { ok: false, reason: "lnbits_unreachable", detail: e && e.message ? e.message : "request_error" };
+    }
+    if (!res.json || res.status >= 400) {
+      return { ok: false, reason: "lnbits_invoice_failed", detail: (res.json && (res.json.detail || res.json.message)) || `HTTP ${res.status}` };
+    }
+    const pr = res.json.payment_request || res.json.bolt11;
+    const ph = res.json.payment_hash || res.json.checking_id;
+    if (!pr || !ph) return { ok: false, reason: "lnbits_invoice_missing_fields" };
+    return { ok: true, payment_request: pr, payment_hash: ph };
+  }
+  if (config.provider === "generic") {
+    if (!config.genericInvoiceUrl) return { ok: false, reason: "generic_invoice_url_missing" };
+    const headers = {};
+    if (config.genericAuthHeader) {
+      const i = config.genericAuthHeader.indexOf(":");
+      if (i > 0) headers[config.genericAuthHeader.slice(0, i).trim()] = config.genericAuthHeader.slice(i + 1).trim();
+    }
+    let res;
+    try {
+      res = await httpPostJson(config.genericInvoiceUrl, headers, { amount_sats: Math.round(sats), memo }, 15000);
+    } catch (e) {
+      return { ok: false, reason: "generic_invoice_unreachable", detail: e && e.message ? e.message : "request_error" };
+    }
+    if (!res.json || res.status >= 400) return { ok: false, reason: "generic_invoice_failed", detail: `HTTP ${res.status}` };
+    const pr = res.json.payment_request || res.json.bolt11 || res.json.invoice;
+    const ph = res.json.payment_hash;
+    if (!pr || !ph) return { ok: false, reason: "generic_invoice_missing_fields" };
+    return { ok: true, payment_request: pr, payment_hash: ph };
+  }
+  return { ok: false, reason: "unsupported_provider" };
+}
+
+function b64url(buf) {
+  return Buffer.from(buf).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function b64urlDecode(s) {
+  s = String(s).replace(/-/g, "+").replace(/_/g, "/");
+  while (s.length % 4) s += "=";
+  return Buffer.from(s, "base64");
+}
+
+// Issue an HMAC-signed macaroon binding a payment_hash. Returns "<payload>.<sig>" or null.
+function issueL402Macaroon(config, options) {
+  if (!config || !config.rootKey) return null;
+  const payload = {
+    ph: String(options && options.payment_hash),
+    exp: Math.floor(Date.now() / 1000) + config.macaroonTtlSeconds,
+    nonce: b64url(crypto.randomBytes(12)),
+    amt: (options && options.amountSats) || null
+  };
+  const encoded = b64url(JSON.stringify(payload));
+  const sig = crypto.createHmac("sha256", config.rootKey).update(encoded, "utf8").digest("hex");
+  return `${encoded}.${sig}`;
+}
+
+// Verify macaroon integrity + expiry. Returns { ok, payment_hash } | { ok:false, reason }.
+function verifyL402Macaroon(config, macaroon) {
+  if (!config || !config.rootKey) return { ok: false, reason: "l402_root_key_missing" };
+  const parts = String(macaroon || "").split(".");
+  if (parts.length !== 2) return { ok: false, reason: "l402_macaroon_malformed" };
+  const [encoded, sig] = parts;
+  const expected = crypto.createHmac("sha256", config.rootKey).update(encoded, "utf8").digest("hex");
+  let ok = false;
+  try {
+    ok = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex"));
+  } catch (_) {
+    ok = false;
+  }
+  if (!ok) return { ok: false, reason: "l402_macaroon_signature_invalid" };
+  let payload;
+  try {
+    payload = JSON.parse(b64urlDecode(encoded).toString("utf8"));
+  } catch (_) {
+    return { ok: false, reason: "l402_macaroon_payload_invalid" };
+  }
+  if (!payload.ph) return { ok: false, reason: "l402_macaroon_no_payment_hash" };
+  if (payload.exp && Math.floor(Date.now() / 1000) > Number(payload.exp)) return { ok: false, reason: "l402_macaroon_expired" };
+  return { ok: true, payment_hash: String(payload.ph) };
+}
+
+// Does preimage (hex) hash (sha256) to payment_hash (hex)? This is the real proof of payment.
+function verifyPreimage(preimageHex, paymentHashHex) {
+  try {
+    const h = crypto.createHash("sha256").update(Buffer.from(String(preimageHex), "hex")).digest("hex");
+    return h.toLowerCase() === String(paymentHashHex).toLowerCase();
+  } catch (_) {
+    return false;
+  }
+}
+
+// Parse "L402 <macaroon>:<preimage>" (also tolerates the legacy "LSAT" scheme).
+function parseL402Header(authorization) {
+  const m = String(authorization || "").match(/^(?:L402|LSAT)\s+([^:\s]+):([0-9a-fA-F]+)\s*$/);
+  if (!m) return null;
+  return { macaroon: m[1], preimage: m[2] };
+}
+
+function buildWwwAuthenticate(macaroon, invoice) {
+  return `L402 macaroon="${macaroon}", invoice="${invoice}"`;
+}
+
+// Full verification of an L402 Authorization header.
+// Returns { ok, payment_hash, preimage } | { ok:false, reason }.
+function verifyL402Authorization(config, authorization) {
+  if (!isConfigured(config)) return { ok: false, reason: "l402_provider_not_configured" };
+  const parsed = parseL402Header(authorization);
+  if (!parsed) return { ok: false, reason: "l402_authorization_malformed" };
+  const mac = verifyL402Macaroon(config, parsed.macaroon);
+  if (!mac.ok) return mac;
+  if (!verifyPreimage(parsed.preimage, mac.payment_hash)) return { ok: false, reason: "l402_preimage_mismatch" };
+  return { ok: true, payment_hash: mac.payment_hash, preimage: parsed.preimage };
+}
+
+module.exports = {
+  loadL402Config,
+  isConfigured,
+  createLightningInvoice,
+  issueL402Macaroon,
+  verifyL402Macaroon,
+  verifyPreimage,
+  parseL402Header,
+  buildWwwAuthenticate,
+  verifyL402Authorization
+};