xytara 3.1.13 → 3.1.14

package/lib/commerce_bridge.js

@@ -1,274 +1,274 @@
-"use strict";
-
-// Generic external-commerce bridge — the name-neutral server-side contract an upstream
-// fiat SaaS front calls after a confirmed payment. Two jobs:
-//   1. /v1/commerce/grants         -> mint internal units for a confirmed purchase
-//      (reuses the proven external-credit-grant primitive; idempotent per upstream event
-//      so a payment-webhook retry never double-mints).
-//   2. /v1/commerce/prepare-execution -> issue a time-boxed DELEGATED-SPEND CREDENTIAL
-//      (the identity bridge) so the paying customer's agent can spend those units here,
-//      gated on sufficient balance.
-//   3. /v1/commerce/state          -> read-only unit balance for an account.
-//
-// This module names no upstream brand and the upstream names nothing here — the only
-// things crossing the seam are opaque refs + units. Routes are gated by the commerce-
-// bridge bearer (verifyCommerceBridgeAccess in server.js).
-
-const { createExternalCreditGrant } = require("./external_credit_bridge");
-const { createAuthorityBinding } = require("./account_auth");
-const { normalizeAgentPublicKey } = require("./agent_identity");
-const { buildCreditBalanceSummary, consumeAccountCredits } = require("./commerce_economics");
-const { findCreditPack } = require("../fixtures/catalog");
-
-function normalizeString(value, fallback = null) {
-  const s = typeof value === "string" ? value.trim() : "";
-  return s || fallback;
-}
-function ensureObject(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-
-function loadCommercePackMap() {
-  const raw = String(process.env.XYTARA_COMMERCE_PACK_MAP_JSON || "").trim();
-  if (!raw) return {};
-  try {
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
-  } catch (_) {
-    return {};
-  }
-}
-
-// How many internal units a package/plan grants: explicit pack map first
-// (packageRef/planRef -> units), then a catalog credit pack's issued_units.
-function resolveCommerceUnits(packageRef, planRef) {
-  const map = loadCommercePackMap();
-  const key = packageRef || planRef;
-  if (key && Object.prototype.hasOwnProperty.call(map, key)) {
-    const n = Number(map[key]);
-    if (Number.isFinite(n) && n > 0) return { units: n, pack_id: key };
-  }
-  const pack = key ? findCreditPack(key) : null;
-  if (pack && Number.isFinite(Number(pack.issued_units)) && Number(pack.issued_units) > 0) {
-    return { units: Number(pack.issued_units), pack_id: pack.pack_id };
-  }
-  return { units: null, pack_id: key || null };
-}
-
-function availableUnits(state, accountId) {
-  const summary = buildCreditBalanceSummary(state, accountId);
-  if (!summary) return 0;
-  if (typeof summary.available_units === "number") return summary.available_units;
-  if (summary.balance && typeof summary.balance.available_units === "number") return summary.balance.available_units;
-  if (summary.lifecycle_totals && typeof summary.lifecycle_totals.available_units === "number") return summary.lifecycle_totals.available_units;
-  return 0;
-}
-
-// POST /v1/commerce/grants
-function grantCommerceAllocation(state, body) {
-  const b = ensureObject(body);
-  const accountRef = normalizeString(b.accountRef);
-  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
-  // Require a single stable, globally-unique dedup anchor (the upstream event id). No
-  // fallback chain: an ambiguous anchor could either double-mint (retry omits eventRef)
-  // or wrongly dedup a distinct purchase whose ref collides with a prior eventRef.
-  const eventRef = normalizeString(b.eventRef);
-  if (!eventRef) return { http_status: 400, body: { ok: false, reason: "event_ref_required" } };
-  const { units, pack_id } = resolveCommerceUnits(normalizeString(b.packageRef), normalizeString(b.planRef));
-  if (!Number.isFinite(units) || units <= 0) {
-    return { http_status: 422, body: { ok: false, reason: "unknown_package", detail: "no unit mapping for the package/plan; set XYTARA_COMMERCE_PACK_MAP_JSON" } };
-  }
-  // Both the grant_id and the idempotency_key are account-namespaced so a shared eventRef
-  // across two accounts (upstreams whose event ids are per-account sequences) cannot
-  // collide on grant_id (checked first by createExternalCreditGrant) and under-mint one.
-  const dedupeAnchor = `${accountRef}:${eventRef}`;
-  const idempotencyKey = `commerce_grant:${dedupeAnchor}`;
-  const grant = createExternalCreditGrant(state, {
-    grant_id: `commerce_grant_${dedupeAnchor}`,
-    idempotency_key: idempotencyKey,
-    account_id: accountRef,
-    // units is explicit; do NOT pass pack_id (createExternalCreditGrant validates pack_id
-    // against the catalog and the package ref is an upstream key, not a catalog pack).
-    units,
-    source: "commerce_bridge",
-    rail_kind: "commerce_bridge",
-    reason: "commerce_grant",
-    provider_reference: normalizeString(b.providerRef),
-    purchase_reference: normalizeString(b.purchaseRef),
-    metadata: {
-      order_type: normalizeString(b.orderType),
-      checkout_surface: ensureObject(b.metadata).checkoutSurface || "public_checkout",
-      package_ref: pack_id || null,
-      event_ref: eventRef
-    }
-  });
-  if (grant && grant.ok === false) {
-    return { http_status: 422, body: { ok: false, reason: grant.reason || "commerce_grant_failed" } };
-  }
-  // Response fields mirror what the upstream client reads (camelCase) + snake aliases.
-  return {
-    http_status: 200,
-    body: {
-      ok: true,
-      status: "granted",
-      grantId: grant.grant_id,
-      grant_id: grant.grant_id,
-      accountRef,
-      account_ref: accountRef,
-      hiddenAccountRef: accountRef,
-      hidden_account_ref: accountRef,
-      units,
-      unitsGranted: units,
-      entitlementRef: grant.entitlement_id || null,
-      economicRef: grant.entitlement_id || null
-    }
-  };
-}
-
-// POST /v1/commerce/prepare-execution
-function prepareCommerceExecution(state, body) {
-  const b = ensureObject(body);
-  const accountRef = normalizeString(b.accountRef);
-  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
-  const featureRef = normalizeString(b.featureRef);
-  const quotedUnits = Number.isFinite(Number(b.quotedUnits)) ? Number(b.quotedUnits) : 0;
-  const delegatedSpend = ensureObject(b.delegatedSpend);
-  const available = availableUnits(state, accountRef);
-
-  const refuse = (decision, extra) => ({
-    http_status: 200,
-    body: Object.assign({
-      ok: true,
-      authorized: false,
-      authorityMode: "delegated_spend_credential",
-      authorityDecision: decision,
-      spendAuthorityRef: null,
-      spendAuthorityToken: null,
-      validUntil: null,
-      delegatedSpendAccepted: false,
-      availableUnits: available,
-      quotedUnits,
-      capabilitySummary: []
-    }, extra || {})
-  });
-
-  // A bounded authorization requires a positive quote — the credential is capped to it.
-  if (!(quotedUnits > 0)) return refuse("quoted_units_required");
-  // Economic gate: only authorize when the account can cover the quote.
-  if (available < quotedUnits) return refuse("insufficient_units");
-
-  // Optional cryptographic agent-key binding. If an upstream intends identity binding
-  // but sends an unparseable key, REFUSE rather than silently downgrade to bearer-only
-  // (createSpendCredential would otherwise drop the key and still authorize).
-  const agentPublicKey = normalizeString(delegatedSpend.agent_public_key || delegatedSpend.agentPublicKey, null);
-  if (agentPublicKey && !normalizeAgentPublicKey(agentPublicKey)) {
-    return refuse("invalid_agent_key");
-  }
-
-  const ttlMs = Math.max(60000, Number(process.env.XYTARA_COMMERCE_PREP_TTL_MS || 900000) || 900000);
-  const validUntil = new Date(Date.now() + ttlMs).toISOString();
-
-  // Issue a BOUND delegated-spend credential via an authority binding: each spend action
-  // is capped at quotedUnits (max_commit/reserve/reversal), so the token can never commit
-  // more than the quote in one action and cannot drain the whole balance. Total spend is
-  // additionally hard-capped by the account balance at commit time. (Without a binding the
-  // credential is open_spend and the quote is not enforced.)
-  const binding = createAuthorityBinding(state, {
-    account_id: accountRef,
-    scope: "runtime_spend",
-    labels: [featureRef, "commerce_prepared"].filter(Boolean),
-    expires_at_iso: validUntil,
-    issued_by: "commerce_bridge",
-    // Constrain to spend/commit only — this credential is for executing paid work, not
-    // for driving reserve/release/reverse lifecycle actions.
-    authority_scope: ["runtime.execute"],
-    allowed_consequence_families: ["commit"],
-    max_commit_units: quotedUnits,
-    max_reserve_units: quotedUnits,
-    max_reversal_units: quotedUnits,
-    ...(agentPublicKey ? { agent_public_key: agentPublicKey } : {})
-  });
-  const credentialView = (binding && binding.spend_credential) || {};
-
-  return {
-    http_status: 200,
-    body: {
-      ok: true,
-      authorized: true,
-      authorityMode: "delegated_spend_credential",
-      authorityDecision: "authorized",
-      // The binding is the authority ref; its credential's bearer token is what the
-      // paying customer's agent presents to spend here. Opaque upstream.
-      spendAuthorityRef: binding.binding_id,
-      spendAuthorityToken: credentialView.bearer_token || null,
-      credentialRef: binding.credential_id || null,
-      identityBound: Boolean(credentialView.agent_key_ref),
-      boundUnits: quotedUnits,
-      proofMode: "credential_issued",
-      proofRef: binding.binding_id,
-      economicRef: binding.credential_id || null,
-      validUntil,
-      delegatedSpendAccepted: Boolean(b.delegatedSpend),
-      availableUnits: available,
-      quotedUnits,
-      capabilitySummary: [featureRef].filter(Boolean)
-    }
-  };
-}
-
-// POST /v1/commerce/settle
-// Server-side settlement for the trusted upstream seam: burn units against an account
-// after it has executed the paid work. The commerce bearer IS the authority here (this is
-// not a delegated-agent path), so there is no per-action bound — the account balance is
-// the hard cap (consumeAccountCredits refuses an overdraw). Returns the raw consume
-// result so an upstream caller reads the same credit_spend/usage_meter shape as the
-// direct consume route.
-function settleCommerceConsumption(state, body) {
-  const b = ensureObject(body);
-  const accountRef = normalizeString(b.accountRef || b.account_id);
-  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
-  const units = Number(b.units);
-  if (!Number.isFinite(units) || units <= 0) {
-    return { http_status: 400, body: { ok: false, reason: "units_required" } };
-  }
-  const result = consumeAccountCredits(state, {
-    account_id: accountRef,
-    units,
-    task_ref: normalizeString(b.taskRef || b.task_ref),
-    workflow_ref: normalizeString(b.workflowRef || b.workflow_ref),
-    transaction_id: normalizeString(b.transactionRef || b.transaction_id),
-    quote_id: normalizeString(b.quoteRef || b.quote_id),
-    pack_id: normalizeString(b.packId || b.pack_id),
-    reason: normalizeString(b.reason, "commerce_settle")
-  });
-  if (result && result.ok === false) {
-    const http_status = result.reason === "insufficient_credits" ? 409 : 403;
-    return { http_status, body: result };
-  }
-  return { http_status: 200, body: result };
-}
-
-// GET /v1/commerce/state
-function inspectCommerceState(state, query) {
-  const accountRef = normalizeString(query && (query.accountRef || query.account_ref));
-  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
-  const available = availableUnits(state, accountRef);
-  return {
-    http_status: 200,
-    body: {
-      ok: true,
-      accountRef,
-      account_ref: accountRef,
-      availableUnits: available,
-      available_units: available
-    }
-  };
-}
-
-module.exports = {
-  grantCommerceAllocation,
-  prepareCommerceExecution,
-  settleCommerceConsumption,
-  inspectCommerceState,
-  resolveCommerceUnits
-};
+"use strict";
+
+// Generic external-commerce bridge — the name-neutral server-side contract an upstream
+// fiat SaaS front calls after a confirmed payment. Two jobs:
+//   1. /v1/commerce/grants         -> mint internal units for a confirmed purchase
+//      (reuses the proven external-credit-grant primitive; idempotent per upstream event
+//      so a payment-webhook retry never double-mints).
+//   2. /v1/commerce/prepare-execution -> issue a time-boxed DELEGATED-SPEND CREDENTIAL
+//      (the identity bridge) so the paying customer's agent can spend those units here,
+//      gated on sufficient balance.
+//   3. /v1/commerce/state          -> read-only unit balance for an account.
+//
+// This module names no upstream brand and the upstream names nothing here — the only
+// things crossing the seam are opaque refs + units. Routes are gated by the commerce-
+// bridge bearer (verifyCommerceBridgeAccess in server.js).
+
+const { createExternalCreditGrant } = require("./external_credit_bridge");
+const { createAuthorityBinding } = require("./account_auth");
+const { normalizeAgentPublicKey } = require("./agent_identity");
+const { buildCreditBalanceSummary, consumeAccountCredits } = require("./commerce_economics");
+const { findCreditPack } = require("../fixtures/catalog");
+
+function normalizeString(value, fallback = null) {
+  const s = typeof value === "string" ? value.trim() : "";
+  return s || fallback;
+}
+function ensureObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function loadCommercePackMap() {
+  const raw = String(process.env.XYTARA_COMMERCE_PACK_MAP_JSON || "").trim();
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (_) {
+    return {};
+  }
+}
+
+// How many internal units a package/plan grants: explicit pack map first
+// (packageRef/planRef -> units), then a catalog credit pack's issued_units.
+function resolveCommerceUnits(packageRef, planRef) {
+  const map = loadCommercePackMap();
+  const key = packageRef || planRef;
+  if (key && Object.prototype.hasOwnProperty.call(map, key)) {
+    const n = Number(map[key]);
+    if (Number.isFinite(n) && n > 0) return { units: n, pack_id: key };
+  }
+  const pack = key ? findCreditPack(key) : null;
+  if (pack && Number.isFinite(Number(pack.issued_units)) && Number(pack.issued_units) > 0) {
+    return { units: Number(pack.issued_units), pack_id: pack.pack_id };
+  }
+  return { units: null, pack_id: key || null };
+}
+
+function availableUnits(state, accountId) {
+  const summary = buildCreditBalanceSummary(state, accountId);
+  if (!summary) return 0;
+  if (typeof summary.available_units === "number") return summary.available_units;
+  if (summary.balance && typeof summary.balance.available_units === "number") return summary.balance.available_units;
+  if (summary.lifecycle_totals && typeof summary.lifecycle_totals.available_units === "number") return summary.lifecycle_totals.available_units;
+  return 0;
+}
+
+// POST /v1/commerce/grants
+function grantCommerceAllocation(state, body) {
+  const b = ensureObject(body);
+  const accountRef = normalizeString(b.accountRef);
+  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
+  // Require a single stable, globally-unique dedup anchor (the upstream event id). No
+  // fallback chain: an ambiguous anchor could either double-mint (retry omits eventRef)
+  // or wrongly dedup a distinct purchase whose ref collides with a prior eventRef.
+  const eventRef = normalizeString(b.eventRef);
+  if (!eventRef) return { http_status: 400, body: { ok: false, reason: "event_ref_required" } };
+  const { units, pack_id } = resolveCommerceUnits(normalizeString(b.packageRef), normalizeString(b.planRef));
+  if (!Number.isFinite(units) || units <= 0) {
+    return { http_status: 422, body: { ok: false, reason: "unknown_package", detail: "no unit mapping for the package/plan; set XYTARA_COMMERCE_PACK_MAP_JSON" } };
+  }
+  // Both the grant_id and the idempotency_key are account-namespaced so a shared eventRef
+  // across two accounts (upstreams whose event ids are per-account sequences) cannot
+  // collide on grant_id (checked first by createExternalCreditGrant) and under-mint one.
+  const dedupeAnchor = `${accountRef}:${eventRef}`;
+  const idempotencyKey = `commerce_grant:${dedupeAnchor}`;
+  const grant = createExternalCreditGrant(state, {
+    grant_id: `commerce_grant_${dedupeAnchor}`,
+    idempotency_key: idempotencyKey,
+    account_id: accountRef,
+    // units is explicit; do NOT pass pack_id (createExternalCreditGrant validates pack_id
+    // against the catalog and the package ref is an upstream key, not a catalog pack).
+    units,
+    source: "commerce_bridge",
+    rail_kind: "commerce_bridge",
+    reason: "commerce_grant",
+    provider_reference: normalizeString(b.providerRef),
+    purchase_reference: normalizeString(b.purchaseRef),
+    metadata: {
+      order_type: normalizeString(b.orderType),
+      checkout_surface: ensureObject(b.metadata).checkoutSurface || "public_checkout",
+      package_ref: pack_id || null,
+      event_ref: eventRef
+    }
+  });
+  if (grant && grant.ok === false) {
+    return { http_status: 422, body: { ok: false, reason: grant.reason || "commerce_grant_failed" } };
+  }
+  // Response fields mirror what the upstream client reads (camelCase) + snake aliases.
+  return {
+    http_status: 200,
+    body: {
+      ok: true,
+      status: "granted",
+      grantId: grant.grant_id,
+      grant_id: grant.grant_id,
+      accountRef,
+      account_ref: accountRef,
+      hiddenAccountRef: accountRef,
+      hidden_account_ref: accountRef,
+      units,
+      unitsGranted: units,
+      entitlementRef: grant.entitlement_id || null,
+      economicRef: grant.entitlement_id || null
+    }
+  };
+}
+
+// POST /v1/commerce/prepare-execution
+function prepareCommerceExecution(state, body) {
+  const b = ensureObject(body);
+  const accountRef = normalizeString(b.accountRef);
+  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
+  const featureRef = normalizeString(b.featureRef);
+  const quotedUnits = Number.isFinite(Number(b.quotedUnits)) ? Number(b.quotedUnits) : 0;
+  const delegatedSpend = ensureObject(b.delegatedSpend);
+  const available = availableUnits(state, accountRef);
+
+  const refuse = (decision, extra) => ({
+    http_status: 200,
+    body: Object.assign({
+      ok: true,
+      authorized: false,
+      authorityMode: "delegated_spend_credential",
+      authorityDecision: decision,
+      spendAuthorityRef: null,
+      spendAuthorityToken: null,
+      validUntil: null,
+      delegatedSpendAccepted: false,
+      availableUnits: available,
+      quotedUnits,
+      capabilitySummary: []
+    }, extra || {})
+  });
+
+  // A bounded authorization requires a positive quote — the credential is capped to it.
+  if (!(quotedUnits > 0)) return refuse("quoted_units_required");
+  // Economic gate: only authorize when the account can cover the quote.
+  if (available < quotedUnits) return refuse("insufficient_units");
+
+  // Optional cryptographic agent-key binding. If an upstream intends identity binding
+  // but sends an unparseable key, REFUSE rather than silently downgrade to bearer-only
+  // (createSpendCredential would otherwise drop the key and still authorize).
+  const agentPublicKey = normalizeString(delegatedSpend.agent_public_key || delegatedSpend.agentPublicKey, null);
+  if (agentPublicKey && !normalizeAgentPublicKey(agentPublicKey)) {
+    return refuse("invalid_agent_key");
+  }
+
+  const ttlMs = Math.max(60000, Number(process.env.XYTARA_COMMERCE_PREP_TTL_MS || 900000) || 900000);
+  const validUntil = new Date(Date.now() + ttlMs).toISOString();
+
+  // Issue a BOUND delegated-spend credential via an authority binding: each spend action
+  // is capped at quotedUnits (max_commit/reserve/reversal), so the token can never commit
+  // more than the quote in one action and cannot drain the whole balance. Total spend is
+  // additionally hard-capped by the account balance at commit time. (Without a binding the
+  // credential is open_spend and the quote is not enforced.)
+  const binding = createAuthorityBinding(state, {
+    account_id: accountRef,
+    scope: "runtime_spend",
+    labels: [featureRef, "commerce_prepared"].filter(Boolean),
+    expires_at_iso: validUntil,
+    issued_by: "commerce_bridge",
+    // Constrain to spend/commit only — this credential is for executing paid work, not
+    // for driving reserve/release/reverse lifecycle actions.
+    authority_scope: ["runtime.execute"],
+    allowed_consequence_families: ["commit"],
+    max_commit_units: quotedUnits,
+    max_reserve_units: quotedUnits,
+    max_reversal_units: quotedUnits,
+    ...(agentPublicKey ? { agent_public_key: agentPublicKey } : {})
+  });
+  const credentialView = (binding && binding.spend_credential) || {};
+
+  return {
+    http_status: 200,
+    body: {
+      ok: true,
+      authorized: true,
+      authorityMode: "delegated_spend_credential",
+      authorityDecision: "authorized",
+      // The binding is the authority ref; its credential's bearer token is what the
+      // paying customer's agent presents to spend here. Opaque upstream.
+      spendAuthorityRef: binding.binding_id,
+      spendAuthorityToken: credentialView.bearer_token || null,
+      credentialRef: binding.credential_id || null,
+      identityBound: Boolean(credentialView.agent_key_ref),
+      boundUnits: quotedUnits,
+      proofMode: "credential_issued",
+      proofRef: binding.binding_id,
+      economicRef: binding.credential_id || null,
+      validUntil,
+      delegatedSpendAccepted: Boolean(b.delegatedSpend),
+      availableUnits: available,
+      quotedUnits,
+      capabilitySummary: [featureRef].filter(Boolean)
+    }
+  };
+}
+
+// POST /v1/commerce/settle
+// Server-side settlement for the trusted upstream seam: burn units against an account
+// after it has executed the paid work. The commerce bearer IS the authority here (this is
+// not a delegated-agent path), so there is no per-action bound — the account balance is
+// the hard cap (consumeAccountCredits refuses an overdraw). Returns the raw consume
+// result so an upstream caller reads the same credit_spend/usage_meter shape as the
+// direct consume route.
+function settleCommerceConsumption(state, body) {
+  const b = ensureObject(body);
+  const accountRef = normalizeString(b.accountRef || b.account_id);
+  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
+  const units = Number(b.units);
+  if (!Number.isFinite(units) || units <= 0) {
+    return { http_status: 400, body: { ok: false, reason: "units_required" } };
+  }
+  const result = consumeAccountCredits(state, {
+    account_id: accountRef,
+    units,
+    task_ref: normalizeString(b.taskRef || b.task_ref),
+    workflow_ref: normalizeString(b.workflowRef || b.workflow_ref),
+    transaction_id: normalizeString(b.transactionRef || b.transaction_id),
+    quote_id: normalizeString(b.quoteRef || b.quote_id),
+    pack_id: normalizeString(b.packId || b.pack_id),
+    reason: normalizeString(b.reason, "commerce_settle")
+  });
+  if (result && result.ok === false) {
+    const http_status = result.reason === "insufficient_credits" ? 409 : 403;
+    return { http_status, body: result };
+  }
+  return { http_status: 200, body: result };
+}
+
+// GET /v1/commerce/state
+function inspectCommerceState(state, query) {
+  const accountRef = normalizeString(query && (query.accountRef || query.account_ref));
+  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
+  const available = availableUnits(state, accountRef);
+  return {
+    http_status: 200,
+    body: {
+      ok: true,
+      accountRef,
+      account_ref: accountRef,
+      availableUnits: available,
+      available_units: available
+    }
+  };
+}
+
+module.exports = {
+  grantCommerceAllocation,
+  prepareCommerceExecution,
+  settleCommerceConsumption,
+  inspectCommerceState,
+  resolveCommerceUnits
+};