xytara 3.1.17 → 3.2.0

package/bin/xytara.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 "use strict";
 
+const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
+const RELEASE_TOOLING_NOTICE = "Release/operator tooling is not part of the xytara client package. See https://www.naxytra.com/agents";
+
 function printUsage() {
   process.stdout.write([
     "Usage: xytara <command> [options]",
     "",
     "Commands:",
-    "  release [args]    Open the release/adoption/reporting surface",
-    "  run [args]        Execute the paid runtime command path",
+    "  run [args]        Execute a paid command on the hosted naxytra runtime",
     "  first-run [args]  Guide or run the safe public quote-first path",
     "  start-here        Print the shortest first-run path",
     "  help              Show this help message",
@@ -20,8 +22,9 @@ function printUsage() {
     "  xytara first-run",
     "  xytara first-run --run-quote --account ACCOUNT_REF --pretty",
     "  xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty",
-    "  xytara release --summary",
-    "  xytara run --help"
+    "  xytara run --help",
+    "",
+    "The runtime is a hosted service (https://xytara.onrender.com); this package is the client."
   ].join("\n"));
 }
 
@@ -48,11 +51,14 @@ function printStartHere() {
     "  quote-only mode needs no wallet secret",
     "  funded execution needs direct payment material or reusable credits",
     "  proof stays in xoonya; runtime payment state stays in xytara",
+    "  the runtime is a hosted service; this package is the client",
     "",
     "Local package confidence:",
-    "  node examples/quickstart.js",
-    "  npm run verify:all",
-    "  xytara release --summary"
+    "  xytara first-run --offline --json",
+    "  xytara-run --help",
+    "  npm run verify:release-candidate",
+    "",
+    "Integration guide: https://www.naxytra.com/agents"
   ].join("\n"));
 }
 
@@ -69,7 +75,14 @@ if (!command || command === "help" || command === "--help" || command === "-h")
 } else if (command === "start-here" || command === "--start-here") {
   printStartHere();
 } else if (command === "release") {
-  delegate("xytara-release.js", rest);
+  // The release/operator surface is not shipped in the client package. It only exists in the
+  // private repository checkout, where the script sits next to this file.
+  if (fs.existsSync(path.join(__dirname, "xytara-release.js"))) {
+    delegate("xytara-release.js", rest);
+  } else {
+    process.stderr.write(`${RELEASE_TOOLING_NOTICE}\n`);
+    process.exitCode = 2;
+  }
 } else if (command === "run") {
   delegate("xytara-run.js", rest);
 } else if (command === "first-run" || command === "firstrun") {

package/client.js

@@ -1,3 +1,81 @@
 "use strict";
 
-module.exports = require("./lib/commerce_client");
+// The xytara client package entry. Everything here talks to the HOSTED naxytra runtime or checks
+// what it returns; nothing here runs a runtime. The runtime, payment/settlement engine, routing,
+// state store and operator tooling are a hosted service and are not distributed.
+
+const commerceClient = require("./lib/commerce_client");
+const {
+  RECEIPT_VERSION,
+  canonicalize,
+  hashCanonical,
+  keyRef,
+  verifyDeliveryReceipt,
+  verificationRecipe
+} = require("./lib/delivery_receipt_verify");
+const { version } = require("./package.json");
+
+// The hosted endpoints this client is built for. `runtime` serves the paid command path
+// (POST /x402/commands/execute), credits (POST /x402/credits/topup), the catalog (GET /v1/catalog)
+// and receipt verification (GET /.well-known/delivery-receipt-keys, POST /v1/delivery-receipts/verify).
+// `mcp` is the pay-per-call MCP server (Streamable HTTP).
+const endpoints = Object.freeze({
+  runtime: "https://xytara.onrender.com",
+  mcp: "https://xytara-mcp-executor.onrender.com/mcp",
+  website: "https://www.naxytra.com"
+});
+
+// Header names of the x402 exchange on the runtime's paid routes.
+const X402_PAYMENT_HEADER = "payment-signature";
+const X402_PAYMENT_REQUIRED_HEADER = "payment-required";
+const X402_PAYMENT_RESPONSE_HEADER = "payment-response";
+
+// Builds the PAYMENT-SIGNATURE header value for an x402 v2 payment: the `accepted` entry copied
+// from the 402 challenge's `accepts`, plus the EIP-3009 `authorization` you signed and its
+// `signature`. Signing the authorization is the wallet's job (viem, ethers, or a hosted signer);
+// this only encodes the result the way the runtime decodes it.
+function encodeX402PaymentHeader({ accepted, authorization, signature }) {
+  if (!accepted || typeof accepted !== "object") throw new Error("encodeX402PaymentHeader requires accepted (one entry from payment_required.accepts)");
+  if (!authorization || typeof authorization !== "object") throw new Error("encodeX402PaymentHeader requires the signed EIP-3009 authorization");
+  if (!signature || typeof signature !== "string") throw new Error("encodeX402PaymentHeader requires the authorization signature");
+  const payload = {
+    x402Version: 2,
+    accepted,
+    payload: { signature, authorization }
+  };
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+}
+
+// Decodes a PAYMENT-REQUIRED or PAYMENT-RESPONSE header value (base64 / base64url JSON).
+function decodeX402Header(value) {
+  const raw = value == null ? "" : String(value).trim();
+  if (!raw) return null;
+  for (const encoding of ["base64url", "base64"]) {
+    try {
+      const parsed = JSON.parse(Buffer.from(raw, encoding).toString("utf8"));
+      if (parsed && typeof parsed === "object") return parsed;
+    } catch (_) {
+      // try the next encoding
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  ...commerceClient,
+  // Signed delivery receipts: offline verification against the issuer's published keys.
+  RECEIPT_VERSION,
+  canonicalize,
+  hashCanonical,
+  keyRef,
+  verifyDeliveryReceipt,
+  verificationRecipe,
+  // x402 header helpers for the paid command path.
+  X402_PAYMENT_HEADER,
+  X402_PAYMENT_REQUIRED_HEADER,
+  X402_PAYMENT_RESPONSE_HEADER,
+  encodeX402PaymentHeader,
+  decodeX402Header,
+  endpoints,
+  version
+};

package/lib/{delivery_receipt.js → delivery_receipt_verify.js}

@@ -1,24 +1,21 @@
 "use strict";
 
-// Signed delivery receipts ("naxytra-delivery-receipt/1"). One per paid call, binding WHAT was
-// paid (the x402 settlement or other payment fact), WHO delivered (provider), and WHAT was
-// delivered (sha256 of the canonical request and of the canonical output) — signed so anyone can
-// re-verify it offline against the issuer's published keys.
-//
-// Boundary: a valid receipt proves this issuer attests that this provider returned this exact
-// output for this paid call, unaltered since signing. It does NOT judge whether the output was
-// correct or good — that is the consumer's (e.g. an arbitrator's) decision.
+// Verification side of signed delivery receipts ("naxytra-delivery-receipt/1"). Everything a
+// CONSUMER needs to check a receipt offline: the canonical form, the hashes, the key-ref format,
+// the public-key-set shape and the verifier itself. No signing keys, no issuing — that side lives
+// in delivery_receipt.js (runtime and MCP executor only) and is not part of the client package.
 //
 // Signed bytes  = JCS (RFC 8785) canonical JSON of the receipt WITHOUT its `sig` member.
-// Signatures    = one per algorithm in `signing.suite` (Ed25519 always; ML-DSA-65 when configured
-//                 and the runtime supports it). The suite and key ids are INSIDE the signed bytes,
-//                 so stripping a signature (downgrade) fails verification.
+// Signatures    = one per algorithm in `signing.suite` (Ed25519 always; ML-DSA-65 when the issuer
+//                 holds a post-quantum key and the runtime supports it). The suite and key ids are
+//                 INSIDE the signed bytes, so stripping a signature (downgrade) fails verification.
 // Key ids       = "<key type>-spki-sha256:<hex>", the same key-ref format the xoonya verifier
 //                 reports, so a receipt verifies with xoonya's verifyExternalProofSignature too.
 //
 // Dependency-free (node:crypto). This file is shared verbatim by the xytara runtime
-// (lib/delivery_receipt.js) and the MCP executor (services/mcp-execution-target/delivery_receipt.js);
-// a verifier asserts the two copies stay byte-identical.
+// (lib/delivery_receipt_verify.js) and the MCP executor
+// (services/mcp-execution-target/delivery_receipt_verify.js); a verifier asserts the two copies
+// stay byte-identical.
 
 const crypto = require("crypto");
 
@@ -55,53 +52,6 @@ function keyRef(publicKey) {
   return `${publicKey.asymmetricKeyType}-spki-sha256:${sha256Hex(spki)}`;
 }
 
-function parsePrivateKey(raw) {
-  const text = String(raw || "").trim();
-  if (!text) return null;
-  if (text.includes("BEGIN ")) return crypto.createPrivateKey({ key: text, format: "pem" });
-  return crypto.createPrivateKey({ key: Buffer.from(text, "base64"), format: "der", type: "pkcs8" });
-}
-
-// Loads the issuer's signing keys from environment variables `${prefix}_ED25519_KEY` and
-// `${prefix}_MLDSA65_KEY` (base64 PKCS#8 DER, or PEM). Never throws: a missing or unusable key is
-// reported in `problems` and simply not used, so receipts degrade to fewer signatures (or to
-// unsigned) and say so — they never claim a signature that was not made.
-const signerCache = new Map();
-function loadDeliveryReceiptSigners(prefix, env = process.env) {
-  const sources = [
-    { variable: `${prefix}_ED25519_KEY`, expected: "ed25519" },
-    { variable: `${prefix}_MLDSA65_KEY`, expected: "ml-dsa-65" }
-  ];
-  const cacheKey = sources.map((source) => `${source.variable}=${env[source.variable] || ""}`).join("\n");
-  if (signerCache.has(cacheKey)) return signerCache.get(cacheKey);
-  const signers = [];
-  const problems = [];
-  for (const source of sources) {
-    const raw = env[source.variable];
-    if (!raw || !String(raw).trim()) continue;
-    try {
-      const privateKey = parsePrivateKey(raw);
-      if (privateKey.asymmetricKeyType !== source.expected) {
-        problems.push({ variable: source.variable, reason: "key_type_mismatch", detail: `expected ${source.expected}, got ${privateKey.asymmetricKeyType}` });
-        continue;
-      }
-      const publicKey = crypto.createPublicKey(privateKey);
-      signers.push({ alg: SUPPORTED_ALGS[source.expected], kid: keyRef(publicKey), privateKey, publicKey });
-    } catch (error) {
-      problems.push({
-        variable: source.variable,
-        reason: source.expected === "ml-dsa-65" ? "ml_dsa_key_unusable_or_unsupported_on_this_runtime" : "key_unparseable",
-        detail: error && error.message ? error.message.slice(0, 160) : "unparseable"
-      });
-    }
-  }
-  // Deterministic suite order: EdDSA first, then ML-DSA-65.
-  signers.sort((a, b) => (a.alg === "EdDSA" ? -1 : 1) - (b.alg === "EdDSA" ? -1 : 1));
-  const loaded = { signers, problems };
-  signerCache.set(cacheKey, loaded);
-  return loaded;
-}
-
 let mlDsaSupport = null;
 function runtimeSupportsMlDsa() {
   if (mlDsaSupport === null) {
@@ -114,44 +64,7 @@ function runtimeSupportsMlDsa() {
   return mlDsaSupport;
 }
 
-// Builds and signs a receipt. `fields` = { receipt_id, issuer, call, payment, delivery }.
-function issueDeliveryReceipt(fields, signers, now = new Date()) {
-  const f = fields && typeof fields === "object" ? fields : {};
-  const activeSigners = Array.isArray(signers) ? signers : [];
-  const body = {
-    v: RECEIPT_VERSION,
-    receipt_id: f.receipt_id || `drcpt_${crypto.randomBytes(8).toString("hex")}`,
-    issuer: f.issuer || null,
-    issued_at: now.toISOString(),
-    call: f.call || null,
-    payment: f.payment || null,
-    delivery: f.delivery || null,
-    hashing: { algorithm: "sha256", canonicalization: "JCS (RFC 8785)" },
-    signing: {
-      canonicalization: CANONICALIZATION,
-      suite: activeSigners.map((signer) => signer.alg),
-      kids: activeSigners.map((signer) => signer.kid),
-      policy: "every_listed_signature_must_verify"
-    }
-  };
-  if (activeSigners.length === 0) {
-    return { ...body, sig: { state: "unsigned_signing_key_not_configured", signatures: [] } };
-  }
-  const signedBytes = Buffer.from(canonicalize(body), "utf8");
-  return {
-    ...body,
-    sig: {
-      state: "signed",
-      signatures: activeSigners.map((signer) => ({
-        alg: signer.alg,
-        kid: signer.kid,
-        value: crypto.sign(null, signedBytes, signer.privateKey).toString("base64")
-      }))
-    }
-  };
-}
-
-// The issuer's public key set (safe to publish).
+// The issuer's public key set (safe to publish). `signers` = [{ alg, kid, publicKey }].
 function publicKeySet(signers) {
   return (Array.isArray(signers) ? signers : []).map((signer) => ({
     kid: signer.kid,
@@ -213,12 +126,13 @@ function verificationRecipe(keysUrl) {
 
 module.exports = {
   RECEIPT_VERSION,
+  CANONICALIZATION,
+  SUPPORTED_ALGS,
   canonicalize,
+  sha256Hex,
   hashCanonical,
   keyRef,
-  loadDeliveryReceiptSigners,
   runtimeSupportsMlDsa,
-  issueDeliveryReceipt,
   publicKeySet,
   verifyDeliveryReceipt,
   verificationRecipe

package/package.json

@@ -1,12 +1,22 @@
 {
   "name": "xytara",
-  "version": "3.1.17",
-  "description": "x402 pay-per-call agent-commerce runtime: gasless USDC on Base, an open settling provider network with a ledger-reconciled revenue split and automated on-chain payouts (key-less runtime, delegated signer), and bounded cryptographic delegated spend. Proven live on Base mainnet.",
-  "main": "index.js",
+  "version": "3.2.0",
+  "description": "Client for the hosted naxytra runtime: discover a capability, pay per call with x402 (gasless USDC on Base) or credits, get the deliverable and a signed delivery receipt you can verify offline. The runtime is a hosted service; this package is the client.",
+  "main": "client.js",
+  "exports": {
+    ".": "./client.js",
+    "./client": "./client.js",
+    "./client.js": "./client.js",
+    "./lib/commerce_client": "./lib/commerce_client.js",
+    "./lib/commerce_client.js": "./lib/commerce_client.js",
+    "./lib/delivery_receipt_verify": "./lib/delivery_receipt_verify.js",
+    "./lib/delivery_receipt_verify.js": "./lib/delivery_receipt_verify.js",
+    "./bin/*": "./bin/*",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "xytara": "bin/xytara.js",
-    "xytara-run": "bin/xytara-run.js",
-    "xytara-release": "bin/xytara-release.js"
+    "xytara-run": "bin/xytara-run.js"
   },
   "type": "commonjs",
   "license": "Apache-2.0",
@@ -37,38 +47,17 @@
     "node": ">=18"
   },
   "files": [
-    "index.js",
     "client.js",
-    "server.js",
-    "bin/",
-    "scripts/",
-    "fixtures/",
-    "integrations/",
-    "lib/",
-    "adapters/",
-    "RELEASE_NOTES.md",
-    ".env.example",
+    "lib/commerce_client.js",
+    "lib/delivery_receipt_verify.js",
+    "bin/xytara.js",
+    "bin/xytara-run.js",
+    "bin/xytara-first-run.js",
+    "scripts/verify_release_candidate.js",
+    "scripts/verify_client.js",
     "README.md",
-    "WHY_XYTARA_XOONYA.md",
-    "CARRIED_HANDOFF_DEMO.md",
-    "PARTNER_READY_PATH.md",
-    "EXAMPLE_PATHS.md",
-    "PUBLIC_DEMO_SCRIPT.md",
-    "SUPABASE_RUNTIME_STATE_SETUP.md",
-    "ADAPTER_START_HERE.md",
-    "examples/",
-    "BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md",
-    "REAL_PAYMENT_SETUP.md",
     "START_HERE.md",
-    "XYTARA_EXECUTION_TRUTH_MODEL.md",
-    "XT1_EXECUTION_TRUTH_STANDARD.md",
-    "XYTARA_DEFAULT_PATH_MODEL.md",
-    "XYTARA_PAYMENT_RAIL_TRUTH_MODEL.md",
-    "XYTARA_ADAPTER_PROTOCOL_TRUTH_MODEL.md",
-    "XYTARA_AUTONOMOUS_ENTRY_MODEL.md",
-    "FINAL_CONTRACT.md",
-    "SERVICE_CONTRACT.md",
-    "TERMINOLOGY.md",
+    "RELEASE_NOTES.md",
     "LICENSE",
     "NOTICE"
   ],
@@ -129,6 +118,7 @@
     "verify:lifecycle-spend-binding": "node scripts/verify_lifecycle_spend_binding.js",
     "verify:buyer-safety": "node scripts/verify_buyer_safety.js",
     "verify:buyer-event-log": "node scripts/verify_buyer_event_log.js",
-    "verify:x402-settlement-recovery": "node scripts/verify_x402_settlement_recovery.js"
+    "verify:x402-settlement-recovery": "node scripts/verify_x402_settlement_recovery.js",
+    "verify:client": "node scripts/verify_client.js"
   }
 }