xytara 3.1.13 → 3.1.15

package/lib/mpp_adapter.js

@@ -1,237 +1,237 @@
-"use strict";
-
-// Provider-agnostic MPP (per-call card/stablecoin payment) adapter.
-//
-// Makes the MPP/SPT lane real by verifying a Stripe PaymentIntent or Checkout
-// Session referenced in the authorization: it must be paid/succeeded and cover
-// at least the quoted amount. The provider reference is the proof; replay is
-// prevented by treating each reference as single-use. Engages only when env
-// configures Stripe; otherwise the caller preserves the existing token scheme.
-// Dependency-free (node https + an injectable fetcher for tests).
-//
-// Env:
-//   XYTARA_MPP_PROVIDER = "stripe"            (anything else => not configured)
-//   XYTARA_MPP_STRIPE_SECRET_KEY | STRIPE_SECRET_KEY
-//   XYTARA_MPP_ROOT_KEY | STRIPE_WEBHOOK_SECRET  (HMAC key for the binding ref;
-//                                                 falls back to the secret key)
-
-// REQUEST BINDING (production-safe):
-//  - The runtime CREATES the PaymentIntent server-side for a specific quote and
-//    stamps metadata.naxytra_ref = HMAC(bindingSecret, quote). verifyMppPayment
-//    requires the presented object to carry that exact ref (timing-safe), so a
-//    paid Stripe object the caller controls for some OTHER purpose cannot be
-//    replayed to authorize this call. Each reference is also single-use.
-//  - Still a flat per-object check otherwise: it confirms paid + USD + covers the
-//    quote amount. Processor minimums apply (Stripe will reject amounts below its
-//    per-charge floor, ~$0.50 USD); price MPP calls at or above that floor.
-
-const https = require("https");
-
-function env(name) {
-  const v = process.env[name];
-  return typeof v === "string" && v.trim() ? v.trim() : "";
-}
-
-function loadMppConfig() {
-  const provider = env("XYTARA_MPP_PROVIDER").toLowerCase();
-  if (provider !== "stripe") return { provider: null };
-  const secretKey = env("XYTARA_MPP_STRIPE_SECRET_KEY") || env("STRIPE_SECRET_KEY");
-  return {
-    provider: "stripe",
-    secretKey,
-    bindingSecret: env("XYTARA_MPP_ROOT_KEY") || env("STRIPE_WEBHOOK_SECRET") || secretKey
-  };
-}
-
-function isConfigured(config) {
-  return Boolean(config && config.provider);
-}
-
-const crypto = require("crypto");
-
-// Deterministic, server-only reference binding a payment to one quote. The caller
-// cannot forge it without bindingSecret, so only a payment created by the runtime
-// for THIS quote carries a matching metadata.naxytra_ref.
-function computeBindingRef(bindingSecret, quote) {
-  const q = quote || {};
-  const basis = `${q.quote_id || ""}:${q.amount_minor || ""}:${q.currency || ""}`;
-  const mac = crypto.createHmac("sha256", String(bindingSecret || "")).update(basis).digest("hex");
-  return "nx_" + mac.slice(0, 32);
-}
-
-function refEquals(a, b) {
-  const x = Buffer.from(String(a || ""));
-  const y = Buffer.from(String(b || ""));
-  if (x.length === 0 || x.length !== y.length) return false;
-  try {
-    return crypto.timingSafeEqual(x, y);
-  } catch (_) {
-    return false;
-  }
-}
-
-function stripeGet(path, secretKey, timeoutMs) {
-  return new Promise((resolve, reject) => {
-    const req = https.request(
-      { method: "GET", hostname: "api.stripe.com", path, headers: { Authorization: "Bearer " + secretKey } },
-      (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 });
-        });
-      }
-    );
-    req.on("error", reject);
-    req.setTimeout(timeoutMs || 15000, () => req.destroy(new Error("stripe_get_timeout")));
-    req.end();
-  });
-}
-
-function stripePost(path, formParams, secretKey, timeoutMs) {
-  const body = new URLSearchParams(formParams).toString();
-  return new Promise((resolve, reject) => {
-    const req = https.request(
-      {
-        method: "POST",
-        hostname: "api.stripe.com",
-        path,
-        headers: {
-          Authorization: "Bearer " + secretKey,
-          "Content-Type": "application/x-www-form-urlencoded",
-          "Content-Length": Buffer.byteLength(body)
-        }
-      },
-      (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 });
-        });
-      }
-    );
-    req.on("error", reject);
-    req.setTimeout(timeoutMs || 15000, () => req.destroy(new Error("stripe_post_timeout")));
-    req.write(body);
-    req.end();
-  });
-}
-
-// Create a PaymentIntent for a quote, stamping the binding ref in metadata.
-// `intent` = { amountMinor, currency, ref, quoteId }. `postOverride` lets tests
-// inject a fetcher. Returns { ok, reference, client_secret } | { ok:false, reason, detail? }.
-async function createMppPaymentIntent(config, intent, postOverride) {
-  if (!isConfigured(config)) return { ok: false, reason: "mpp_provider_not_configured" };
-  if (config.provider !== "stripe") return { ok: false, reason: "unsupported_provider" };
-  if (!config.secretKey) return { ok: false, reason: "stripe_secret_key_missing" };
-  const amountMinor = Math.round(Number(intent && intent.amountMinor));
-  if (!Number.isFinite(amountMinor) || amountMinor <= 0) return { ok: false, reason: "invalid_amount" };
-  const currency = String((intent && intent.currency) || "usd").toLowerCase();
-  const params = {
-    amount: String(amountMinor),
-    currency: currency === "usd_cents" ? "usd" : currency,
-    "automatic_payment_methods[enabled]": "true",
-    "metadata[naxytra_ref]": String((intent && intent.ref) || ""),
-    "metadata[quote_id]": String((intent && intent.quoteId) || "")
-  };
-  const post = typeof postOverride === "function" ? postOverride : (p, f) => stripePost(p, f, config.secretKey, 15000);
-  let res;
-  try {
-    res = await post("/v1/payment_intents", params);
-  } catch (e) {
-    return { ok: false, reason: "stripe_unreachable", detail: e && e.message ? e.message : "request_error" };
-  }
-  if (!res.json || res.status >= 400) {
-    return { ok: false, reason: "stripe_payment_intent_create_failed", detail: (res.json && res.json.error && res.json.error.message) || `HTTP ${res.status}` };
-  }
-  return { ok: true, reference: res.json.id, client_secret: res.json.client_secret };
-}
-
-// Parse "SPT <stripe_reference>" (pi_... or cs_...). Returns { reference } | null.
-function parseMppHeader(authorization) {
-  const m = String(authorization || "").match(/^SPT\s+((?:pi|cs)_[A-Za-z0-9_]+)\s*$/);
-  return m ? { reference: m[1] } : null;
-}
-
-// Verify a Stripe reference is paid and covers requiredAmountMinor.
-// `getOverride` lets tests inject a fetcher. Returns
-// { ok, reference, amount_minor, currency, status } | { ok:false, reason, detail? }.
-async function verifyMppPayment(config, reference, requiredAmountMinor, getOverride, options) {
-  if (!isConfigured(config)) return { ok: false, reason: "mpp_provider_not_configured" };
-  if (config.provider === "stripe") {
-    if (!config.secretKey) return { ok: false, reason: "stripe_secret_key_missing" };
-    const ref = String(reference || "");
-    const path = ref.startsWith("pi_") ? "/v1/payment_intents/" + ref : ref.startsWith("cs_") ? "/v1/checkout/sessions/" + ref : null;
-    if (!path) return { ok: false, reason: "mpp_reference_invalid" };
-    const get = typeof getOverride === "function" ? getOverride : (p) => stripeGet(p, config.secretKey, 15000);
-    let res;
-    try {
-      res = await get(path);
-    } catch (e) {
-      return { ok: false, reason: "stripe_unreachable", detail: e && e.message ? e.message : "request_error" };
-    }
-    if (!res.json || res.status >= 400) {
-      return { ok: false, reason: "stripe_reference_not_found", detail: (res.json && res.json.error && res.json.error.message) || `HTTP ${res.status}` };
-    }
-    const obj = res.json;
-    const paid = ref.startsWith("pi_") ? obj.status === "succeeded" : obj.payment_status === "paid";
-    if (!paid) return { ok: false, reason: "mpp_not_paid", detail: obj.status || obj.payment_status || "unknown" };
-    const amount = Number(ref.startsWith("pi_") ? obj.amount_received || obj.amount : obj.amount_total);
-    const required = Number(requiredAmountMinor);
-    // Never authorize for free: a known, positive required amount is mandatory.
-    if (!Number.isFinite(required) || required <= 0) {
-      return { ok: false, reason: "mpp_required_amount_unknown" };
-    }
-    if (!Number.isFinite(amount) || amount < required) {
-      return { ok: false, reason: "mpp_amount_insufficient", detail: `${amount}/${required}` };
-    }
-    // The runtime prices in USD minor units; reject a payment in another currency
-    // (e.g. a high nominal amount in a zero-decimal currency) that would not match.
-    const currency = String(obj.currency || "").toLowerCase();
-    if (currency && currency !== "usd") {
-      return { ok: false, reason: "mpp_currency_mismatch", detail: currency };
-    }
-    // Request binding: when the caller expects a server-issued ref (it always
-    // does in production), the paid object must carry the matching
-    // metadata.naxytra_ref, proving it was created for THIS quote.
-    const expectedRef = options && options.expectedRef;
-    if (expectedRef) {
-      const presented = obj.metadata && obj.metadata.naxytra_ref;
-      if (!presented) return { ok: false, reason: "mpp_binding_ref_missing" };
-      if (!refEquals(presented, expectedRef)) return { ok: false, reason: "mpp_binding_ref_mismatch" };
-    }
-    return { ok: true, reference: ref, amount_minor: amount, currency: (obj.currency || "usd").toUpperCase(), status: "paid" };
-  }
-  return { ok: false, reason: "unsupported_provider" };
-}
-
-function buildMppChallenge(quote) {
-  return {
-    provider: "stripe",
-    amount_minor: quote && quote.amount_minor,
-    currency: quote && quote.currency,
-    instructions: "Create a Stripe PaymentIntent (or Checkout Session) for the quoted amount, then retry with 'Authorization: SPT <pi_... | cs_...>'."
-  };
-}
-
-module.exports = {
-  loadMppConfig,
-  isConfigured,
-  parseMppHeader,
-  verifyMppPayment,
-  buildMppChallenge,
-  createMppPaymentIntent,
-  computeBindingRef
-};
+"use strict";
+
+// Provider-agnostic MPP (per-call card/stablecoin payment) adapter.
+//
+// Makes the MPP/SPT lane real by verifying a Stripe PaymentIntent or Checkout
+// Session referenced in the authorization: it must be paid/succeeded and cover
+// at least the quoted amount. The provider reference is the proof; replay is
+// prevented by treating each reference as single-use. Engages only when env
+// configures Stripe; otherwise the caller preserves the existing token scheme.
+// Dependency-free (node https + an injectable fetcher for tests).
+//
+// Env:
+//   XYTARA_MPP_PROVIDER = "stripe"            (anything else => not configured)
+//   XYTARA_MPP_STRIPE_SECRET_KEY | STRIPE_SECRET_KEY
+//   XYTARA_MPP_ROOT_KEY | STRIPE_WEBHOOK_SECRET  (HMAC key for the binding ref;
+//                                                 falls back to the secret key)
+
+// REQUEST BINDING (production-safe):
+//  - The runtime CREATES the PaymentIntent server-side for a specific quote and
+//    stamps metadata.naxytra_ref = HMAC(bindingSecret, quote). verifyMppPayment
+//    requires the presented object to carry that exact ref (timing-safe), so a
+//    paid Stripe object the caller controls for some OTHER purpose cannot be
+//    replayed to authorize this call. Each reference is also single-use.
+//  - Still a flat per-object check otherwise: it confirms paid + USD + covers the
+//    quote amount. Processor minimums apply (Stripe will reject amounts below its
+//    per-charge floor, ~$0.50 USD); price MPP calls at or above that floor.
+
+const https = require("https");
+
+function env(name) {
+  const v = process.env[name];
+  return typeof v === "string" && v.trim() ? v.trim() : "";
+}
+
+function loadMppConfig() {
+  const provider = env("XYTARA_MPP_PROVIDER").toLowerCase();
+  if (provider !== "stripe") return { provider: null };
+  const secretKey = env("XYTARA_MPP_STRIPE_SECRET_KEY") || env("STRIPE_SECRET_KEY");
+  return {
+    provider: "stripe",
+    secretKey,
+    bindingSecret: env("XYTARA_MPP_ROOT_KEY") || env("STRIPE_WEBHOOK_SECRET") || secretKey
+  };
+}
+
+function isConfigured(config) {
+  return Boolean(config && config.provider);
+}
+
+const crypto = require("crypto");
+
+// Deterministic, server-only reference binding a payment to one quote. The caller
+// cannot forge it without bindingSecret, so only a payment created by the runtime
+// for THIS quote carries a matching metadata.naxytra_ref.
+function computeBindingRef(bindingSecret, quote) {
+  const q = quote || {};
+  const basis = `${q.quote_id || ""}:${q.amount_minor || ""}:${q.currency || ""}`;
+  const mac = crypto.createHmac("sha256", String(bindingSecret || "")).update(basis).digest("hex");
+  return "nx_" + mac.slice(0, 32);
+}
+
+function refEquals(a, b) {
+  const x = Buffer.from(String(a || ""));
+  const y = Buffer.from(String(b || ""));
+  if (x.length === 0 || x.length !== y.length) return false;
+  try {
+    return crypto.timingSafeEqual(x, y);
+  } catch (_) {
+    return false;
+  }
+}
+
+function stripeGet(path, secretKey, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      { method: "GET", hostname: "api.stripe.com", path, headers: { Authorization: "Bearer " + secretKey } },
+      (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 });
+        });
+      }
+    );
+    req.on("error", reject);
+    req.setTimeout(timeoutMs || 15000, () => req.destroy(new Error("stripe_get_timeout")));
+    req.end();
+  });
+}
+
+function stripePost(path, formParams, secretKey, timeoutMs) {
+  const body = new URLSearchParams(formParams).toString();
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      {
+        method: "POST",
+        hostname: "api.stripe.com",
+        path,
+        headers: {
+          Authorization: "Bearer " + secretKey,
+          "Content-Type": "application/x-www-form-urlencoded",
+          "Content-Length": Buffer.byteLength(body)
+        }
+      },
+      (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 });
+        });
+      }
+    );
+    req.on("error", reject);
+    req.setTimeout(timeoutMs || 15000, () => req.destroy(new Error("stripe_post_timeout")));
+    req.write(body);
+    req.end();
+  });
+}
+
+// Create a PaymentIntent for a quote, stamping the binding ref in metadata.
+// `intent` = { amountMinor, currency, ref, quoteId }. `postOverride` lets tests
+// inject a fetcher. Returns { ok, reference, client_secret } | { ok:false, reason, detail? }.
+async function createMppPaymentIntent(config, intent, postOverride) {
+  if (!isConfigured(config)) return { ok: false, reason: "mpp_provider_not_configured" };
+  if (config.provider !== "stripe") return { ok: false, reason: "unsupported_provider" };
+  if (!config.secretKey) return { ok: false, reason: "stripe_secret_key_missing" };
+  const amountMinor = Math.round(Number(intent && intent.amountMinor));
+  if (!Number.isFinite(amountMinor) || amountMinor <= 0) return { ok: false, reason: "invalid_amount" };
+  const currency = String((intent && intent.currency) || "usd").toLowerCase();
+  const params = {
+    amount: String(amountMinor),
+    currency: currency === "usd_cents" ? "usd" : currency,
+    "automatic_payment_methods[enabled]": "true",
+    "metadata[naxytra_ref]": String((intent && intent.ref) || ""),
+    "metadata[quote_id]": String((intent && intent.quoteId) || "")
+  };
+  const post = typeof postOverride === "function" ? postOverride : (p, f) => stripePost(p, f, config.secretKey, 15000);
+  let res;
+  try {
+    res = await post("/v1/payment_intents", params);
+  } catch (e) {
+    return { ok: false, reason: "stripe_unreachable", detail: e && e.message ? e.message : "request_error" };
+  }
+  if (!res.json || res.status >= 400) {
+    return { ok: false, reason: "stripe_payment_intent_create_failed", detail: (res.json && res.json.error && res.json.error.message) || `HTTP ${res.status}` };
+  }
+  return { ok: true, reference: res.json.id, client_secret: res.json.client_secret };
+}
+
+// Parse "SPT <stripe_reference>" (pi_... or cs_...). Returns { reference } | null.
+function parseMppHeader(authorization) {
+  const m = String(authorization || "").match(/^SPT\s+((?:pi|cs)_[A-Za-z0-9_]+)\s*$/);
+  return m ? { reference: m[1] } : null;
+}
+
+// Verify a Stripe reference is paid and covers requiredAmountMinor.
+// `getOverride` lets tests inject a fetcher. Returns
+// { ok, reference, amount_minor, currency, status } | { ok:false, reason, detail? }.
+async function verifyMppPayment(config, reference, requiredAmountMinor, getOverride, options) {
+  if (!isConfigured(config)) return { ok: false, reason: "mpp_provider_not_configured" };
+  if (config.provider === "stripe") {
+    if (!config.secretKey) return { ok: false, reason: "stripe_secret_key_missing" };
+    const ref = String(reference || "");
+    const path = ref.startsWith("pi_") ? "/v1/payment_intents/" + ref : ref.startsWith("cs_") ? "/v1/checkout/sessions/" + ref : null;
+    if (!path) return { ok: false, reason: "mpp_reference_invalid" };
+    const get = typeof getOverride === "function" ? getOverride : (p) => stripeGet(p, config.secretKey, 15000);
+    let res;
+    try {
+      res = await get(path);
+    } catch (e) {
+      return { ok: false, reason: "stripe_unreachable", detail: e && e.message ? e.message : "request_error" };
+    }
+    if (!res.json || res.status >= 400) {
+      return { ok: false, reason: "stripe_reference_not_found", detail: (res.json && res.json.error && res.json.error.message) || `HTTP ${res.status}` };
+    }
+    const obj = res.json;
+    const paid = ref.startsWith("pi_") ? obj.status === "succeeded" : obj.payment_status === "paid";
+    if (!paid) return { ok: false, reason: "mpp_not_paid", detail: obj.status || obj.payment_status || "unknown" };
+    const amount = Number(ref.startsWith("pi_") ? obj.amount_received || obj.amount : obj.amount_total);
+    const required = Number(requiredAmountMinor);
+    // Never authorize for free: a known, positive required amount is mandatory.
+    if (!Number.isFinite(required) || required <= 0) {
+      return { ok: false, reason: "mpp_required_amount_unknown" };
+    }
+    if (!Number.isFinite(amount) || amount < required) {
+      return { ok: false, reason: "mpp_amount_insufficient", detail: `${amount}/${required}` };
+    }
+    // The runtime prices in USD minor units; reject a payment in another currency
+    // (e.g. a high nominal amount in a zero-decimal currency) that would not match.
+    const currency = String(obj.currency || "").toLowerCase();
+    if (currency && currency !== "usd") {
+      return { ok: false, reason: "mpp_currency_mismatch", detail: currency };
+    }
+    // Request binding: when the caller expects a server-issued ref (it always
+    // does in production), the paid object must carry the matching
+    // metadata.naxytra_ref, proving it was created for THIS quote.
+    const expectedRef = options && options.expectedRef;
+    if (expectedRef) {
+      const presented = obj.metadata && obj.metadata.naxytra_ref;
+      if (!presented) return { ok: false, reason: "mpp_binding_ref_missing" };
+      if (!refEquals(presented, expectedRef)) return { ok: false, reason: "mpp_binding_ref_mismatch" };
+    }
+    return { ok: true, reference: ref, amount_minor: amount, currency: (obj.currency || "usd").toUpperCase(), status: "paid" };
+  }
+  return { ok: false, reason: "unsupported_provider" };
+}
+
+function buildMppChallenge(quote) {
+  return {
+    provider: "stripe",
+    amount_minor: quote && quote.amount_minor,
+    currency: quote && quote.currency,
+    instructions: "Create a Stripe PaymentIntent (or Checkout Session) for the quoted amount, then retry with 'Authorization: SPT <pi_... | cs_...>'."
+  };
+}
+
+module.exports = {
+  loadMppConfig,
+  isConfigured,
+  parseMppHeader,
+  verifyMppPayment,
+  buildMppChallenge,
+  createMppPaymentIntent,
+  computeBindingRef
+};

package/lib/openapi_contract.js

@@ -16,6 +16,10 @@ function buildOpenApiDocument() {
     },
     jsonSchemaDialect: "https://spec.openapis.org/oas/3.1/dialect/base",
     servers: [
+      {
+        url: String(process.env.XYTARA_PUBLIC_BASE_URL || "https://xytara.onrender.com").trim().replace(/\/+$/, ""),
+        description: "Hosted xytara runtime"
+      },
       {
         url: "http://127.0.0.1:4320",
         description: "Local xytara service"