xytara 3.1.16 → 3.2.0

package/lib/x402_settlement_recovery.js

@@ -1,175 +0,0 @@
-"use strict";
-
-const { decodePaymentSignatureHeader } = require("./x402_facilitator");
-
-// Settlement-outcome recovery for the deferred x402 lane.
-//
-// A facilitator /settle that times out or drops the connection does NOT mean the transfer failed:
-// the facilitator may already have broadcast it. Telling the buyer "you were not charged" and
-// withholding the result could leave them charged with nothing. Instead we ask the chain: an
-// EIP-3009 authorization that was used is a settled payment (USDC authorizationState(authorizer,
-// nonce) == true). And every settled (or not-yet-confirmed) result is kept briefly under its
-// payment nonce, so a buyer who lost the response — or was told to wait — can resend the SAME
-// payment signature and receive the result instead of paying again.
-
-const AUTHORIZATION_STATE_SELECTOR = "0xe94a0102"; // authorizationState(address,bytes32)
-const DEFAULT_RPC_URLS = {
-  "eip155:8453": "https://mainnet.base.org",
-  "eip155:84532": "https://sepolia.base.org"
-};
-const REPLAY_TTL_MS = 15 * 60 * 1000;
-const REPLAY_MAX = 1000;
-
-function rpcUrlFor(network) {
-  const key = `XYTARA_RPC_URL_${String(network || "").replace(/[^0-9A-Za-z]/g, "_").toUpperCase()}`;
-  const fromEnv = String(process.env[key] || "").trim();
-  return fromEnv || DEFAULT_RPC_URLS[String(network || "").toLowerCase()] || null;
-}
-
-function hex32(value, bytes) {
-  const clean = String(value || "").toLowerCase().replace(/^0x/, "");
-  if (!/^[0-9a-f]*$/.test(clean) || clean.length > bytes * 2) return null;
-  return clean.padStart(64, "0");
-}
-
-// true = authorization used (payment settled), false = not used, null = could not tell.
-async function authorizationUsed({ network, asset, authorizer, nonce }, options = {}) {
-  const url = rpcUrlFor(network);
-  const from = hex32(authorizer, 20);
-  const n = hex32(nonce, 32);
-  if (!url || !from || !n || !/^0x[0-9a-fA-F]{40}$/.test(String(asset || ""))) return null;
-  const fetchImpl = options.fetch || fetch;
-  try {
-    const response = await fetchImpl(url, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to: asset, data: `${AUTHORIZATION_STATE_SELECTOR}${from}${n}` }, "latest"] }),
-      signal: AbortSignal.timeout(options.timeoutMs || 5000)
-    });
-    const json = await response.json();
-    if (!json || typeof json.result !== "string" || !/^0x[0-9a-fA-F]+$/.test(json.result)) return null;
-    return BigInt(json.result) !== 0n;
-  } catch (_) {
-    return null;
-  }
-}
-
-// A just-broadcast transfer may not be mined yet: poll a few times before concluding.
-async function confirmAuthorizationUsed(ref, options = {}) {
-  const attempts = options.attempts || 3;
-  const delayMs = options.delayMs === undefined ? 2000 : options.delayMs;
-  let sawAnswer = false;
-  for (let i = 0; i < attempts; i += 1) {
-    const used = await authorizationUsed(ref, options);
-    if (used === true) return true;
-    if (used === false) sawAnswer = true;
-    if (i < attempts - 1 && delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
-  }
-  return sawAnswer ? false : null;
-}
-
-// The on-chain reference of a deferred x402 verification (or of a raw payment header).
-function authorizationRefFromVerification(verification) {
-  const deferred = verification && verification.deferred_settlement;
-  const auth = deferred && deferred.authorization;
-  const paymentPayload = auth && auth.paymentPayload;
-  const signed = paymentPayload && paymentPayload.payload && paymentPayload.payload.authorization;
-  const requirements = (auth && auth.paymentRequirements) || (paymentPayload && paymentPayload.accepted) || {};
-  if (!signed || !signed.nonce || !signed.from) return null;
-  return { network: requirements.network, asset: requirements.asset, authorizer: signed.from, nonce: signed.nonce };
-}
-
-function authorizationRefFromHeaders(headers) {
-  const decoded = decodePaymentSignatureHeader((headers || {})["payment-signature"]);
-  const signed = decoded && decoded.payload && decoded.payload.authorization;
-  if (!signed || !signed.nonce || !signed.from) return null;
-  return { network: decoded.accepted.network, asset: decoded.accepted.asset, authorizer: signed.from, nonce: signed.nonce };
-}
-
-function replayKey(ref) {
-  return ref ? `${String(ref.network || "").toLowerCase()}:${String(ref.nonce || "").toLowerCase()}` : null;
-}
-
-function ensureReplayStore(state) {
-  if (!(state.x402SettledReplays instanceof Map)) {
-    // In-memory only: non-enumerable, so it is never written to the state snapshot.
-    Object.defineProperty(state, "x402SettledReplays", { value: new Map(), enumerable: false, writable: true });
-  }
-  return state.x402SettledReplays;
-}
-
-function pruneReplays(store) {
-  const now = Date.now();
-  for (const [key, entry] of store) {
-    if (entry.expires_at_ms <= now) store.delete(key);
-  }
-  while (store.size > REPLAY_MAX) store.delete(store.keys().next().value);
-}
-
-// entry: { status: "settled" | "unconfirmed", ref, response?, finalize?: async (settlement) => response }
-function rememberReplay(state, ref, entry) {
-  const key = replayKey(ref);
-  if (!key) return;
-  const store = ensureReplayStore(state);
-  pruneReplays(store);
-  store.set(key, { ...entry, ref, expires_at_ms: Date.now() + REPLAY_TTL_MS });
-}
-
-// A resent payment that we already settled (or were confirming) gets its result, not a re-run.
-// The payment authorization becomes public on-chain once settled, so it is not enough on its own:
-// the resent REQUEST must match the original too (request_digest), or nothing is returned.
-async function resolveReplay(state, headers, options = {}) {
-  const ref = authorizationRefFromHeaders(headers);
-  const key = replayKey(ref);
-  if (!key) return null;
-  const store = ensureReplayStore(state);
-  pruneReplays(store);
-  const entry = store.get(key);
-  if (!entry) return null;
-  if (String(entry.ref.authorizer || "").toLowerCase() !== String(ref.authorizer || "").toLowerCase()) return null;
-  if (!entry.request_digest || entry.request_digest !== options.request_digest) {
-    return {
-      status: 409,
-      payload: {
-        ok: false,
-        reason: "payment_already_used",
-        detail: "This payment authorization was already used for a different request. Sign a new payment for this request."
-      }
-    };
-  }
-  if (entry.status === "settled" && entry.response) {
-    return { ...entry.response, payload: { ...entry.response.payload, replayed: true } };
-  }
-  const used = await confirmAuthorizationUsed(entry.ref, { attempts: 1, ...(options.rpc || {}) });
-  if (used === true && typeof entry.finalize === "function") {
-    const response = await entry.finalize({ success: true, transaction: null, network: entry.ref.network, payer: entry.ref.authorizer, recovered_from: "authorization_state" });
-    store.set(key, { ...entry, status: "settled", response, finalize: undefined });
-    return { ...response, payload: { ...response.payload, replayed: true } };
-  }
-  if (used === false) {
-    // Never settled: forget it so the payment is verified and executed normally.
-    store.delete(key);
-    return null;
-  }
-  return {
-    status: 409,
-    payload: {
-      ok: false,
-      reason: "settlement_outcome_unknown",
-      detail: "We are still confirming whether this payment settled on-chain. Resend the same payment signature in a minute to receive the result; do not sign a new payment.",
-      payment_settled: null
-    },
-    headers: { "Retry-After": "30" }
-  };
-}
-
-module.exports = {
-  AUTHORIZATION_STATE_SELECTOR,
-  authorizationRefFromHeaders,
-  authorizationRefFromVerification,
-  authorizationUsed,
-  confirmAuthorizationUsed,
-  rememberReplay,
-  resolveReplay,
-  rpcUrlFor
-};

package/scripts/buyer_events_daily_report.js

@@ -1,79 +0,0 @@
-"use strict";
-
-// Daily buyer-journey report: reads the operator-only failure summary from the live runtime and
-// prints it as Markdown (to $GITHUB_STEP_SUMMARY when run in Actions). Exits 1 — so GitHub emails
-// the workflow owner — when money moved without a delivered result, or when failures that are OUR
-// fault exceed the threshold. Exits 0 with a notice when no operator token is configured.
-//
-// Usage: XYTARA_OPERATOR_READ_BEARER=... node scripts/buyer_events_daily_report.js [--days 1]
-// Env: XYTARA_URL (default https://xytara.onrender.com), BUYER_EVENTS_OURS_THRESHOLD (default 0).
-
-const fs = require("fs");
-
-function formatReport(summary, events, baseUrl) {
-  const t = summary.totals || {};
-  const lines = [
-    `## naxytra buyer journey — last ${summary.window_days} day(s)`,
-    "",
-    `Runtime: ${baseUrl} · generated ${summary.generated_at_iso}`,
-    "",
-    "| Paid calls served | 402 challenges | Failures | Our fault | Upstream | Buyer-side | Money moved, nothing delivered |",
-    "|---:|---:|---:|---:|---:|---:|---:|",
-    `| ${t.paid_ok || 0} | ${t.challenges_issued || 0} | ${t.failures || 0} | ${t.ours || 0} | ${t.upstream || 0} | ${t.buyer || 0} | ${t.money_moved || 0} |`,
-    ""
-  ];
-  const reasons = Array.isArray(summary.top_reasons) ? summary.top_reasons : [];
-  if (reasons.length) {
-    lines.push("### Top failure reasons", "", "| Service | Stage | Reason | Fault | Count |", "|---|---|---|---|---:|");
-    for (const r of reasons.slice(0, 15)) lines.push(`| ${r.service} | ${r.stage} | ${r.reason} | ${r.fault} | ${r.count} |`);
-    lines.push("");
-  }
-  const notable = (Array.isArray(events) ? events : []).filter((e) => e.money_moved || e.fault === "ours").slice(0, 20);
-  if (notable.length) {
-    lines.push("### Needs a look (money moved or our fault)", "", "| When (UTC) | Service | Route / tool | Reason | Request id |", "|---|---|---|---|---|");
-    for (const e of notable) lines.push(`| ${e.at_iso} | ${e.service} | ${e.task_or_tool || e.route || ""} | ${e.reason}${e.money_moved ? " (money moved)" : ""} | ${e.request_id || ""} |`);
-    lines.push("");
-  }
-  return lines.join("\n");
-}
-
-async function main() {
-  const token = String(process.env.XYTARA_OPERATOR_READ_BEARER || "").trim();
-  const baseUrl = String(process.env.XYTARA_URL || "https://xytara.onrender.com").replace(/\/+$/, "");
-  const daysArg = process.argv.indexOf("--days");
-  const days = daysArg > -1 ? Number(process.argv[daysArg + 1]) || 1 : 1;
-  const out = (text) => {
-    if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${text}\n`);
-    console.log(text);
-  };
-  if (!token) {
-    out("Buyer journey report skipped: set the XYTARA_OPERATOR_READ_BEARER secret to enable it.");
-    return;
-  }
-  const headers = { authorization: `Bearer ${token}` };
-  // The runtime may be asleep on a free tier: allow for a cold start.
-  const get = async (path) => {
-    const res = await fetch(`${baseUrl}${path}`, { headers, signal: AbortSignal.timeout(90000) });
-    if (!res.ok) throw new Error(`${path} -> HTTP ${res.status}`);
-    return res.json();
-  };
-  const since = new Date(Date.now() - days * 86400000).toISOString();
-  const summary = await get(`/v1/operator/buyer-events/summary?days=${days}`);
-  const listed = await get(`/v1/operator/buyer-events?since=${encodeURIComponent(since)}&limit=200`);
-  out(formatReport(summary, listed.events, baseUrl));
-  const threshold = Number(process.env.BUYER_EVENTS_OURS_THRESHOLD || 0);
-  const totals = summary.totals || {};
-  if ((totals.money_moved || 0) > 0 || (totals.ours || 0) > threshold) {
-    console.error(`ATTENTION: money_moved=${totals.money_moved || 0}, our-fault failures=${totals.ours || 0} (threshold ${threshold}).`);
-    process.exit(1);
-  }
-}
-
-if (require.main === module) {
-  main().catch((error) => {
-    console.error(`Buyer journey report failed: ${error && error.message ? error.message : error}`);
-    process.exit(1);
-  });
-}
-
-module.exports = { formatReport };

package/scripts/registry_cli.js

@@ -1,275 +0,0 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const {
-  createIntegrationRegistrySnapshotFromBundles,
-  exportIntegrationSubmissionBundleSet,
-  importIntegrationSubmissionBundle,
-  summarizeIntegrationPromotionActionPreview,
-  summarizeIntegrationPromotionActionSet,
-  summarizeIntegrationPromotionActionSetList,
-  summarizeIntegrationPromotionReadiness,
-  summarizeIntegrationPromotionWorkflow,
-  summarizeIntegrationPromotionWorkflowList,
-  summarizeIntegrationRegistrySnapshotReview,
-  summarizeIntegrationSubmissionBundleReview,
-  summarizeIntegrationSubmissionBundleSetReview,
-  validateIntegrationSubmissionBundle
-} = require("../integrations/registry");
-
-function readJson(filePath) {
-  return JSON.parse(fs.readFileSync(filePath, "utf8"));
-}
-
-function writeJson(payload) {
-  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
-}
-
-function resolveExampleBundle(name) {
-  const filename = name === "settlement"
-    ? "example-third-party-settlement-registration.submission-bundle.json"
-    : name === "identity"
-      ? "example-third-party-identity-registration.submission-bundle.json"
-    : "example-third-party-registration.submission-bundle.json";
-  return path.resolve(__dirname, "..", "adapters", "examples", filename);
-}
-
-function importExampleBundles() {
-  return [
-    importIntegrationSubmissionBundle(readJson(resolveExampleBundle("protocol")), {
-      source: "third_party_example",
-      protocols: ["mcp"],
-      execution_backends: ["mcp"],
-      adapter_lanes: ["mcp"],
-      task_refs: ["adapter.mcp.invoke"]
-    }),
-    importIntegrationSubmissionBundle(readJson(resolveExampleBundle("identity")), {
-      source: "third_party_example",
-      protocols: [],
-      execution_backends: ["http", "chain"],
-      adapter_lanes: ["http", "chain"],
-      task_refs: ["registry.register", "trust.handoff.emit", "trust.handoff.validate"]
-    }),
-    importIntegrationSubmissionBundle(readJson(resolveExampleBundle("settlement")), {
-      source: "third_party_example",
-      protocols: [],
-      execution_backends: ["chain"],
-      adapter_lanes: ["chain"],
-      task_refs: ["anchoring.submit"]
-    })
-  ];
-}
-
-function parseArgs(argv) {
-  const [command, ...rest] = argv;
-  const options = {};
-  for (let index = 0; index < rest.length; index += 1) {
-    const token = rest[index];
-    if (!token.startsWith("--")) continue;
-    const key = token.slice(2);
-    const next = rest[index + 1];
-    if (!next || next.startsWith("--")) {
-      options[key] = true;
-      continue;
-    }
-    options[key] = next;
-    index += 1;
-  }
-  return {
-    command: command || "",
-    options
-  };
-}
-
-function runValidateBundle(options) {
-  const filePath = options.file
-    ? path.resolve(process.cwd(), options.file)
-    : resolveExampleBundle(options.example === "settlement" ? "settlement" : options.example === "identity" ? "identity" : "protocol");
-  const bundle = readJson(filePath);
-  const validation = validateIntegrationSubmissionBundle(bundle);
-  writeJson({
-    ok: validation.ok,
-    file: filePath,
-    errors: validation.errors
-  });
-  process.exitCode = validation.ok ? 0 : 1;
-}
-
-function runExportBundleSet(options) {
-  const payload = exportIntegrationSubmissionBundleSet({
-    source: "third_party_example",
-    bundled: "false"
-  }, options.notes || "generated by registry_cli");
-  writeJson(payload);
-}
-
-function runExportSnapshot(options) {
-  const snapshot = createIntegrationRegistrySnapshotFromBundles(
-    importExampleBundles(),
-    { source: "third_party_example" },
-    { source: "third_party_example" }
-  );
-  writeJson({
-    generated_by: "registry_cli",
-    mode: options.mode || "examples",
-    snapshot
-  });
-}
-
-function runReviewBundle(options) {
-  const filePath = options.file
-    ? path.resolve(process.cwd(), options.file)
-    : resolveExampleBundle(options.example === "settlement" ? "settlement" : options.example === "identity" ? "identity" : "protocol");
-  const bundle = readJson(filePath);
-  writeJson({
-    file: filePath,
-    review: summarizeIntegrationSubmissionBundleReview(bundle)
-  });
-}
-
-function runReviewBundleSet(options) {
-  const payload = exportIntegrationSubmissionBundleSet({
-    source: "third_party_example",
-    bundled: "false"
-  }, options.notes || "generated by registry_cli");
-  writeJson({
-    review: summarizeIntegrationSubmissionBundleSetReview(payload)
-  });
-}
-
-function runReviewSnapshot() {
-  const snapshot = createIntegrationRegistrySnapshotFromBundles(
-    importExampleBundles(),
-    { source: "third_party_example" },
-    { source: "third_party_example" }
-  );
-  writeJson({
-    review: summarizeIntegrationRegistrySnapshotReview(snapshot)
-  });
-}
-
-function runPromotionReadiness(options) {
-  const integrationId = options.integration || "partner.protocol.acme_mcp";
-  writeJson({
-    integration_id: integrationId,
-    review: summarizeIntegrationPromotionReadiness(integrationId)
-  });
-}
-
-function runPromotionWorkflow(options) {
-  const integrationId = options.integration || "partner.protocol.acme_mcp";
-  writeJson({
-    integration_id: integrationId,
-    review: summarizeIntegrationPromotionWorkflow(integrationId)
-  });
-}
-
-function runPromotionWorkflowSummary(options) {
-  writeJson({
-    review: summarizeIntegrationPromotionWorkflowList({
-      source: options.source || "",
-      bundled: options.bundled || ""
-    })
-  });
-}
-
-function runPromotionActionPreview(options) {
-  writeJson({
-    review: summarizeIntegrationPromotionActionPreview({
-      integration_id: options.integration || "partner.protocol.acme_mcp",
-      action: options.action || "complete_certification"
-    })
-  });
-}
-
-function runPromotionActionSet(options) {
-  const integrationId = options.integration || "partner.protocol.acme_mcp";
-  writeJson({
-    integration_id: integrationId,
-    review: summarizeIntegrationPromotionActionSet(integrationId)
-  });
-}
-
-function runPromotionActionSetSummary(options) {
-  writeJson({
-    review: summarizeIntegrationPromotionActionSetList({
-      source: options.source || "",
-      bundled: options.bundled || ""
-    })
-  });
-}
-
-function main() {
-  const { command, options } = parseArgs(process.argv.slice(2));
-  if (command === "validate-bundle") {
-    runValidateBundle(options);
-    return;
-  }
-  if (command === "export-bundle-set") {
-    runExportBundleSet(options);
-    return;
-  }
-  if (command === "export-snapshot") {
-    runExportSnapshot(options);
-    return;
-  }
-  if (command === "review-bundle") {
-    runReviewBundle(options);
-    return;
-  }
-  if (command === "review-bundle-set") {
-    runReviewBundleSet(options);
-    return;
-  }
-  if (command === "review-snapshot") {
-    runReviewSnapshot();
-    return;
-  }
-  if (command === "promotion-readiness") {
-    runPromotionReadiness(options);
-    return;
-  }
-  if (command === "promotion-workflow") {
-    runPromotionWorkflow(options);
-    return;
-  }
-  if (command === "promotion-workflow-summary") {
-    runPromotionWorkflowSummary(options);
-    return;
-  }
-  if (command === "promotion-action-preview") {
-    runPromotionActionPreview(options);
-    return;
-  }
-  if (command === "promotion-action-set") {
-    runPromotionActionSet(options);
-    return;
-  }
-  if (command === "promotion-action-set-summary") {
-    runPromotionActionSetSummary(options);
-    return;
-  }
-
-  writeJson({
-    ok: false,
-    usage: [
-      "node scripts/registry_cli.js validate-bundle [--file <path>] [--example protocol|settlement]",
-      "node scripts/registry_cli.js validate-bundle [--file <path>] [--example identity]",
-      "node scripts/registry_cli.js export-bundle-set [--notes <text>]",
-      "node scripts/registry_cli.js export-snapshot",
-      "node scripts/registry_cli.js review-bundle [--file <path>] [--example protocol|identity|settlement]",
-      "node scripts/registry_cli.js review-bundle-set [--notes <text>]",
-      "node scripts/registry_cli.js review-snapshot",
-      "node scripts/registry_cli.js promotion-readiness [--integration <integration_id>]",
-      "node scripts/registry_cli.js promotion-workflow [--integration <integration_id>]",
-      "node scripts/registry_cli.js promotion-workflow-summary [--source <source>] [--bundled true|false]",
-      "node scripts/registry_cli.js promotion-action-preview [--integration <integration_id>] [--action <action>]",
-      "node scripts/registry_cli.js promotion-action-set [--integration <integration_id>]",
-      "node scripts/registry_cli.js promotion-action-set-summary [--source <source>] [--bundled true|false]"
-    ]
-  });
-  process.exitCode = 1;
-}
-
-main();