xytara 3.1.17 → 3.2.0

package/scripts/verify_client.js

@@ -0,0 +1,418 @@
+"use strict";
+
+// Offline verification of the xytara client package. Node built-ins only; no network.
+//
+// 1. The package surface: CommerceClient, the receipt verification API, the x402 header helpers,
+//    the hosted endpoints and the package version.
+// 2. Signed delivery receipts: a receipt built in the documented canonical form and signed with an
+//    Ed25519 key generated here verifies; tampered, stripped, unsigned and wrong-key copies do not.
+// 3. The paid command path against a local stub of the hosted runtime: discover -> 402 challenge
+//    with x402 accepts -> pay with an x402 payment header -> 200 with the result, the settlement
+//    response and a signed delivery receipt that verifies against the stub's published keys.
+// 4. The CLIs start: `xytara start-here`, `xytara-run --help`, `xytara first-run --json --offline`,
+//    and `xytara-run --quote-only` against the stub.
+
+const assert = require("assert");
+const crypto = require("crypto");
+const fs = require("fs");
+const http = require("http");
+const path = require("path");
+const { spawn, spawnSync } = require("child_process");
+
+const PACKAGE_DIR = path.resolve(__dirname, "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf8"));
+const client = require(path.join(PACKAGE_DIR, "client.js"));
+const {
+  CommerceClient,
+  RECEIPT_VERSION,
+  canonicalize,
+  hashCanonical,
+  keyRef,
+  verifyDeliveryReceipt,
+  verificationRecipe,
+  encodeX402PaymentHeader,
+  decodeX402Header,
+  summarizeCommandResultPayload,
+  endpoints,
+  version
+} = client;
+
+const checks = [];
+function check(name, fn) {
+  fn();
+  checks.push(name);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Receipt issuing, as the hosted runtime does it (kept in-test: the client never issues receipts).
+function signReceipt(body, signer) {
+  const unsigned = {
+    ...body,
+    v: RECEIPT_VERSION,
+    hashing: { algorithm: "sha256", canonicalization: "JCS (RFC 8785)" },
+    signing: {
+      canonicalization: "JCS (RFC 8785) of the receipt without `sig`",
+      suite: [signer.alg],
+      kids: [signer.kid],
+      policy: "every_listed_signature_must_verify"
+    }
+  };
+  const signedBytes = Buffer.from(canonicalize(unsigned), "utf8");
+  return {
+    ...unsigned,
+    sig: {
+      state: "signed",
+      signatures: [{ alg: signer.alg, kid: signer.kid, value: crypto.sign(null, signedBytes, signer.privateKey).toString("base64") }]
+    }
+  };
+}
+
+function makeSigner() {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519");
+  const kid = keyRef(publicKey);
+  return {
+    alg: "EdDSA",
+    kid,
+    privateKey,
+    publicKey,
+    trustedKey: { kid, alg: "EdDSA", public_key_spki_der_base64: publicKey.export({ type: "spki", format: "der" }).toString("base64") }
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// A local stub of the hosted runtime's buyer-facing routes (x402 facilitator lane). It plays the
+// facilitator too: any well-formed x402 v2 payment that matches the advertised accepts settles.
+const ACCEPTS = [{
+  scheme: "exact",
+  network: "eip155:8453",
+  asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  amount: "10000",
+  payTo: "0x" + "ab".repeat(20),
+  maxTimeoutSeconds: 60,
+  extra: { name: "USD Coin", version: "2" }
+}];
+const PAYER = "0x" + "11".repeat(20);
+const SETTLEMENT_TX = "0x" + "5e".repeat(32);
+
+function readJsonBody(request) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    request.on("data", (chunk) => chunks.push(chunk));
+    request.on("end", () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"));
+      } catch (_) {
+        resolve({});
+      }
+    });
+  });
+}
+
+function sendJson(response, status, payload, headers) {
+  const text = JSON.stringify(payload);
+  response.writeHead(status, { "content-type": "application/json", "content-length": Buffer.byteLength(text), ...(headers || {}) });
+  response.end(text);
+}
+
+function startStubRuntime(signer) {
+  const quotes = new Map();
+  const keys = [signer.trustedKey];
+  const toolOutput = (body) => ({ summary: `Summary of: ${body && body.arguments && body.arguments.text ? body.arguments.text : ""}`.slice(0, 120) });
+
+  const server = http.createServer(async (request, response) => {
+    const url = new URL(request.url, "http://127.0.0.1");
+    if (request.method === "GET" && url.pathname === "/health") return sendJson(response, 200, { ok: true, status: "ok" });
+    if (request.method === "GET" && url.pathname === "/v1/catalog") {
+      return sendJson(response, 200, {
+        ok: true,
+        tasks: [{ task_ref: "adapter.mcp.invoke", category: "mcp", description: "Invoke a tool on the pay-per-call MCP server", price_minor: 1, currency: "USD_CENTS" }],
+        workflows: []
+      });
+    }
+    if (request.method === "GET" && url.pathname === "/.well-known/delivery-receipt-keys") {
+      return sendJson(response, 200, {
+        ok: true,
+        issuer: "xytara-runtime",
+        receipt_version: RECEIPT_VERSION,
+        signing_state: "signing",
+        suite: ["EdDSA"],
+        keys,
+        verification: verificationRecipe("/.well-known/delivery-receipt-keys")
+      });
+    }
+    if (request.method === "POST" && url.pathname === "/v1/delivery-receipts/verify") {
+      const body = await readJsonBody(request);
+      const receipt = body && body.receipt && typeof body.receipt === "object" ? body.receipt : body;
+      return sendJson(response, 200, { ok: true, ...verifyDeliveryReceipt(receipt, keys), issuer_expected: "xytara-runtime" });
+    }
+    if (request.method === "POST" && url.pathname === "/x402/commands/execute") {
+      const body = await readJsonBody(request);
+      if (!body.account_id || body.task_ref !== "adapter.mcp.invoke") return sendJson(response, 400, { ok: false, reason: "task_not_executable" });
+      const header = request.headers["payment-signature"];
+      if (!header) {
+        const quoteId = `quote_${crypto.randomBytes(6).toString("hex")}`;
+        quotes.set(quoteId, body);
+        const paymentRequired = {
+          x402Version: 2,
+          scheme: "exact",
+          resource: { url: `http://127.0.0.1:${server.address().port}/x402/commands/execute`, mimeType: "application/json", description: "naxytra runtime paid execution" },
+          accepts: ACCEPTS,
+          price: ACCEPTS.map((accept) => ({ network: accept.network, asset: accept.asset, amount: accept.amount, usd: "0.01" })),
+          quote: { quote_id: quoteId, status: "quoted", task_refs: ["adapter.mcp.invoke"], amount_minor: 1, currency: "USD_CENTS", payment_protocol: "x402", expires_at_iso: new Date(Date.now() + 60000).toISOString() }
+        };
+        return sendJson(response, 402, { ok: false, payment_required: paymentRequired }, {
+          "PAYMENT-REQUIRED": Buffer.from(JSON.stringify(paymentRequired), "utf8").toString("base64url"),
+          "WWW-Authenticate": "x402"
+        });
+      }
+      const payment = decodeX402Header(header);
+      if (!payment || Number(payment.x402Version) !== 2 || !payment.accepted || !payment.payload) {
+        return sendJson(response, 402, { ok: false, reason: "payment_signature_invalid" });
+      }
+      const accepted = ACCEPTS.find((entry) => entry.network === payment.accepted.network && entry.asset === payment.accepted.asset && entry.payTo === payment.accepted.payTo && String(entry.amount) === String(payment.accepted.amount));
+      if (!accepted) return sendJson(response, 402, { ok: false, reason: "payment_requirements_mismatch" });
+      if (!payment.payload.signature || !payment.payload.authorization) return sendJson(response, 402, { ok: false, reason: "payment_verification_failed" });
+      if (!quotes.has(body.quote_id)) return sendJson(response, 402, { ok: false, reason: "quote_not_found" });
+      const output = toolOutput(body.body);
+      const transactionId = `txn_${crypto.randomBytes(6).toString("hex")}`;
+      const runtimeReceiptId = `rcpt_${crypto.randomBytes(6).toString("hex")}`;
+      const settlement = { success: true, transaction: SETTLEMENT_TX, network: accepted.network, payer: PAYER };
+      const deliveryReceipt = signReceipt({
+        receipt_id: `drcpt_${runtimeReceiptId.replace(/^rcpt_/, "")}`,
+        issuer: "xytara-runtime",
+        issued_at: new Date().toISOString(),
+        call: { quote_id: body.quote_id, transaction_id: transactionId, runtime_receipt_id: runtimeReceiptId, task_ref: body.task_ref, tool_name: body.body && body.body.tool_name ? body.body.tool_name : null },
+        payment: { protocol: "x402", scheme: "exact", network: accepted.network, asset: accepted.asset, amount: accepted.amount, payer: PAYER, pay_to: accepted.payTo, settlement_tx: SETTLEMENT_TX, settled: true },
+        delivery: {
+          status: "completed",
+          provider_id: null,
+          routing: "runtime_native",
+          execution_target_id: null,
+          request_sha256: hashCanonical(body.body || {}),
+          request_hash_input: "the request `body` object (e.g. { tool_name, arguments })",
+          output_sha256: hashCanonical(output),
+          output_hash_input: "command.deliverables[0].output_payload (null when the task returns no payload)",
+          completed_at: new Date().toISOString()
+        }
+      }, signer);
+      return sendJson(response, 200, {
+        ok: true,
+        transaction: { transaction_id: transactionId, quote_id: body.quote_id, status: "completed", payment: { verification_mode: "x402_facilitator" } },
+        receipt: { receipt_id: runtimeReceiptId, settlement: { rail: "x402", mode: "x402_facilitator", txid: SETTLEMENT_TX, network: accepted.network, pay_to: accepted.payTo, status: "settled" } },
+        command: { deliverables: [{ task_ref: body.task_ref, output_payload: output }] },
+        delivery_receipt: deliveryReceipt
+      }, { "PAYMENT-RESPONSE": Buffer.from(JSON.stringify(settlement), "utf8").toString("base64") });
+    }
+    sendJson(response, 404, { ok: false, reason: "not_found" });
+  });
+  return new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve({ server, baseUrl: `http://127.0.0.1:${server.address().port}` })));
+}
+
+// ---------------------------------------------------------------------------------------------
+function runCli(args, options) {
+  return spawnSync(process.execPath, args, { cwd: PACKAGE_DIR, encoding: "utf8", ...(options || {}) });
+}
+
+// Non-blocking variant for a CLI that must talk to the stub runtime served by THIS process
+// (spawnSync would block the event loop and deadlock the stub).
+function runCliAsync(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, { cwd: PACKAGE_DIR });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("error", reject);
+    child.on("close", (status) => resolve({ status, stdout, stderr }));
+  });
+}
+
+async function main() {
+  check("package_surface", () => {
+    assert.strictEqual(typeof CommerceClient, "function", "CommerceClient export missing");
+    for (const name of ["verifyDeliveryReceipt", "canonicalize", "hashCanonical", "keyRef", "verificationRecipe", "encodeX402PaymentHeader", "decodeX402Header", "summarizeCommandResultPayload", "summarizeCatalogPayload", "summarizeReceiptPayload"]) {
+      assert.strictEqual(typeof client[name], "function", `${name} export missing`);
+    }
+    assert.strictEqual(RECEIPT_VERSION, "naxytra-delivery-receipt/1", "receipt version mismatch");
+    assert.strictEqual(endpoints.runtime, "https://xytara.onrender.com", "runtime endpoint mismatch");
+    assert.strictEqual(endpoints.mcp, "https://xytara-mcp-executor.onrender.com/mcp", "mcp endpoint mismatch");
+    assert.strictEqual(endpoints.website, "https://www.naxytra.com", "website endpoint mismatch");
+    assert.strictEqual(version, packageJson.version, "version export must come from package.json");
+    assert.strictEqual(require(path.join(PACKAGE_DIR, "client.js")), client, "client entry is a stable singleton");
+  });
+
+  check("canonical_form", () => {
+    assert.strictEqual(canonicalize({ b: 1, a: [1, { d: 2, c: 3 }], u: undefined, n: null }), "{\"a\":[1,{\"c\":3,\"d\":2}],\"b\":1,\"n\":null}", "JCS key ordering / undefined handling");
+    assert.strictEqual(hashCanonical({ a: 1, b: "x" }), hashCanonical({ b: "x", a: 1 }), "hashCanonical must be key-order independent");
+    assert.strictEqual(hashCanonical({ a: 1 }), crypto.createHash("sha256").update("{\"a\":1}").digest("hex"), "hashCanonical is sha256 over JCS");
+    const signer = makeSigner();
+    assert.ok(/^ed25519-spki-sha256:[0-9a-f]{64}$/.test(signer.kid), "key ref format");
+    const recipe = verificationRecipe("/.well-known/delivery-receipt-keys");
+    assert.strictEqual(recipe.keys, "/.well-known/delivery-receipt-keys", "recipe keys url");
+    assert.strictEqual(recipe.steps.length, 4, "recipe has four steps");
+  });
+
+  const signer = makeSigner();
+  const genuine = signReceipt({
+    receipt_id: "drcpt_test",
+    issuer: "xytara-runtime",
+    issued_at: "2026-01-01T00:00:00.000Z",
+    call: { quote_id: "quote_test", transaction_id: "txn_test", runtime_receipt_id: "rcpt_test", task_ref: "adapter.mcp.invoke", tool_name: "summarize" },
+    payment: { protocol: "x402", scheme: "exact", network: "eip155:8453", asset: ACCEPTS[0].asset, amount: "10000", payer: PAYER, pay_to: ACCEPTS[0].payTo, settlement_tx: SETTLEMENT_TX, settled: true },
+    delivery: { status: "completed", routing: "runtime_native", request_sha256: hashCanonical({ tool_name: "summarize", arguments: { text: "hi" } }), output_sha256: hashCanonical({ summary: "hi" }), completed_at: "2026-01-01T00:00:01.000Z" }
+  }, signer);
+
+  check("receipt_offline_verification", () => {
+    const result = verifyDeliveryReceipt(genuine, [signer.trustedKey]);
+    assert.strictEqual(result.valid, true, `genuine receipt must verify: ${JSON.stringify(result)}`);
+    assert.strictEqual(result.signatures[0].alg, "EdDSA", "signature algorithm");
+    assert.strictEqual(result.signed_bytes_sha256.length, 64, "signed bytes hash reported");
+    const reordered = JSON.parse(JSON.stringify({ sig: genuine.sig, delivery: genuine.delivery, ...genuine }));
+    assert.strictEqual(verifyDeliveryReceipt(reordered, [signer.trustedKey]).valid, true, "key order must not matter (JCS)");
+    const tampered = JSON.parse(JSON.stringify(genuine));
+    tampered.payment.amount = "1";
+    assert.strictEqual(verifyDeliveryReceipt(tampered, [signer.trustedKey]).valid, false, "tampered receipt must fail");
+    const stripped = JSON.parse(JSON.stringify(genuine));
+    stripped.sig.signatures = [];
+    assert.strictEqual(verifyDeliveryReceipt(stripped, [signer.trustedKey]).signatures[0].reason, "signature_missing_for_signed_suite", "stripped signature must fail");
+    const other = makeSigner();
+    assert.strictEqual(verifyDeliveryReceipt(genuine, [other.trustedKey]).signatures[0].reason, "kid_not_in_trusted_key_set", "untrusted kid must fail");
+    const unsigned = { ...genuine, sig: { state: "unsigned_signing_key_not_configured", signatures: [] } };
+    assert.strictEqual(verifyDeliveryReceipt(unsigned, [signer.trustedKey]).reason, "receipt_unsigned", "unsigned receipt must fail");
+    assert.strictEqual(verifyDeliveryReceipt({ ...genuine, v: "other/1" }, [signer.trustedKey]).reason, "unsupported_receipt_version", "unknown version must fail");
+    assert.strictEqual(verifyDeliveryReceipt(null, [signer.trustedKey]).reason, "receipt_required", "missing receipt must fail");
+  });
+
+  check("x402_header_helpers", () => {
+    const authorization = { from: PAYER, to: ACCEPTS[0].payTo, value: ACCEPTS[0].amount, validAfter: "0", validBefore: "9999999999", nonce: "0x" + "00".repeat(32) };
+    const header = encodeX402PaymentHeader({ accepted: ACCEPTS[0], authorization, signature: "0x" + "11".repeat(65) });
+    const decoded = decodeX402Header(header);
+    assert.strictEqual(decoded.x402Version, 2, "x402 v2");
+    assert.deepStrictEqual(decoded.accepted, ACCEPTS[0], "accepted roundtrip");
+    assert.deepStrictEqual(decoded.payload.authorization, authorization, "authorization roundtrip");
+    assert.strictEqual(decodeX402Header(Buffer.from("{\"a\":1}").toString("base64url")).a, 1, "base64url decodes too");
+    assert.strictEqual(decodeX402Header("not base64 json"), null, "garbage decodes to null");
+    assert.throws(() => encodeX402PaymentHeader({ accepted: ACCEPTS[0], authorization }), /signature/, "signature required");
+  });
+
+  const issuer = makeSigner();
+  const { server, baseUrl } = await startStubRuntime(issuer);
+  let paidResult = null;
+  try {
+    const runtime = new CommerceClient({ baseUrl, accountId: "acct_client_check" });
+    const payload = { command: "mcp.invoke:summarize", task_ref: "adapter.mcp.invoke", body: { tool_name: "summarize", arguments: { text: "Summarize the naxytra first-run path in one sentence." } } };
+
+    await (async () => {
+      const health = await runtime.getHealth();
+      assert.strictEqual(health.ok, true, "health");
+      const task = await runtime.getTask("adapter.mcp.invoke");
+      assert.ok(task && task.task_ref === "adapter.mcp.invoke", "catalog discovery");
+      const tasks = await runtime.listTasks();
+      assert.strictEqual(tasks.length, 1, "listTasks");
+      checks.push("runtime_discover");
+    })();
+
+    const quote = await runtime.previewExecutionQuote(payload, { instant: true });
+    assert.strictEqual(quote.payment_required, true, "quote preview must report payment_required");
+    assert.strictEqual(quote.x402Version, 2, "challenge is x402 v2");
+    assert.strictEqual(quote.accepts[0].amount, "10000", "challenge advertises the price");
+    assert.ok(quote.quote && quote.quote.quote_id, "challenge carries a quote id");
+    const raw = await runtime.postJson("/x402/commands/execute", {}, { account_id: "acct_client_check", ...payload });
+    assert.strictEqual(raw.status, 402, "raw challenge status");
+    assert.strictEqual(decodeX402Header(raw.headers.get("payment-required")).accepts[0].payTo, ACCEPTS[0].payTo, "PAYMENT-REQUIRED header decodes");
+    checks.push("runtime_402_challenge");
+
+    const accepted = quote.accepts[0];
+    const authorization = { from: PAYER, to: accepted.payTo, value: accepted.amount, validAfter: "0", validBefore: String(Math.floor(Date.now() / 1000) + 600), nonce: "0x" + crypto.randomBytes(32).toString("hex") };
+    const paymentHeader = encodeX402PaymentHeader({ accepted, authorization, signature: "0x" + crypto.randomBytes(65).toString("hex") });
+    const paid = await runtime.postJson("/x402/commands/execute", { "payment-signature": paymentHeader }, { account_id: "acct_client_check", ...payload, quote_id: quote.quote.quote_id });
+    assert.strictEqual(paid.status, 200, `paid call must succeed: ${JSON.stringify(paid.data)}`);
+    paidResult = paid.data;
+    assert.strictEqual(paid.data.transaction.status, "completed", "transaction completed");
+    assert.strictEqual(paid.data.command.deliverables[0].output_payload.summary.startsWith("Summary of:"), true, "deliverable returned");
+    const settlement = decodeX402Header(paid.headers.get("payment-response"));
+    assert.strictEqual(settlement.success, true, "PAYMENT-RESPONSE decodes to the settlement");
+    assert.strictEqual(settlement.transaction, SETTLEMENT_TX, "settlement tx");
+    const summary = summarizeCommandResultPayload(paid.data);
+    assert.ok(summary && typeof summary === "object", "summarizeCommandResultPayload");
+    checks.push("runtime_paid_execute");
+
+    const mismatched = await runtime.postJson("/x402/commands/execute", { "payment-signature": encodeX402PaymentHeader({ accepted: { ...accepted, amount: "1" }, authorization, signature: "0x00" }) }, { account_id: "acct_client_check", ...payload, quote_id: quote.quote.quote_id });
+    assert.strictEqual(mismatched.status, 402, "underpayment rejected");
+    assert.strictEqual(mismatched.data.reason, "payment_requirements_mismatch", "underpayment reason");
+    checks.push("runtime_underpayment_rejected");
+
+    const receipt = paid.data.delivery_receipt;
+    assert.strictEqual(receipt.v, RECEIPT_VERSION, "receipt version");
+    assert.strictEqual(receipt.payment.settlement_tx, SETTLEMENT_TX, "receipt binds the settlement tx");
+    assert.strictEqual(receipt.call.quote_id, quote.quote.quote_id, "receipt binds the quote");
+    assert.strictEqual(receipt.delivery.request_sha256, hashCanonical(payload.body), "request hash recomputes from the request body");
+    assert.strictEqual(receipt.delivery.output_sha256, hashCanonical(paid.data.command.deliverables[0].output_payload), "output hash recomputes from the deliverable");
+    const keys = await runtime.getJson("/.well-known/delivery-receipt-keys");
+    assert.strictEqual(keys.data.signing_state, "signing", "keys endpoint");
+    assert.strictEqual(verifyDeliveryReceipt(receipt, keys.data.keys).valid, true, "receipt verifies against the published keys");
+    const tamperedReceipt = JSON.parse(JSON.stringify(receipt));
+    tamperedReceipt.delivery.output_sha256 = hashCanonical({ summary: "something else" });
+    assert.strictEqual(verifyDeliveryReceipt(tamperedReceipt, keys.data.keys).valid, false, "tampered receipt rejected offline");
+    const remote = await runtime.postJson("/v1/delivery-receipts/verify", {}, { receipt });
+    assert.strictEqual(remote.data.valid, true, "remote verify endpoint accepts the receipt");
+    assert.strictEqual((await runtime.postJson("/v1/delivery-receipts/verify", {}, { receipt: tamperedReceipt })).data.valid, false, "remote verify rejects the tampered receipt");
+    checks.push("runtime_receipt_verification");
+
+    const quoteOnly = await runCliAsync([path.join(PACKAGE_DIR, "bin", "xytara-run.js"), "--url", baseUrl, "--account", "acct_client_check", "--task", "adapter.mcp.invoke", "--command", "mcp.invoke:summarize", "--body-json", JSON.stringify(payload.body), "--quote-only"]);
+    assert.strictEqual(quoteOnly.status, 0, `xytara-run --quote-only failed: ${quoteOnly.stderr}`);
+    const quoteOutput = JSON.parse(quoteOnly.stdout);
+    assert.strictEqual(quoteOutput.payment_required.accepts[0].amount, "10000", "xytara-run --quote-only returns the challenge");
+    checks.push("cli_run_quote_only");
+  } finally {
+    server.close();
+  }
+
+  check("cli_start_here", () => {
+    const result = runCli([path.join(PACKAGE_DIR, "bin", "xytara.js"), "start-here"]);
+    assert.strictEqual(result.status, 0, `xytara start-here failed: ${result.stderr}`);
+    assert.ok(result.stdout.includes("quote -> pay/credits -> execute -> prove"), "start-here spine line");
+    assert.ok(result.stdout.includes("xytara"), "start-here names the package");
+    assert.ok(result.stdout.includes("https://www.naxytra.com"), "start-here links the website");
+  });
+
+  check("cli_run_help", () => {
+    const result = runCli([path.join(PACKAGE_DIR, "bin", "xytara-run.js"), "--help"]);
+    assert.strictEqual(result.status, 0, "xytara-run --help failed");
+    assert.ok(result.stdout.includes("Usage: xytara-run"), "xytara-run usage text");
+    const viaDispatcher = runCli([path.join(PACKAGE_DIR, "bin", "xytara.js"), "run", "--help"]);
+    assert.strictEqual(viaDispatcher.status, 0, "xytara run --help failed");
+    assert.ok(viaDispatcher.stdout.includes("Usage: xytara-run"), "xytara run --help usage text");
+  });
+
+  check("cli_first_run_offline", () => {
+    const result = runCli([path.join(PACKAGE_DIR, "bin", "xytara.js"), "first-run", "--json", "--offline"]);
+    assert.strictEqual(result.status, 0, `xytara first-run --json --offline failed: ${result.stderr}`);
+    const guide = JSON.parse(result.stdout);
+    assert.strictEqual(guide.ok, true, "first-run guide ok");
+    assert.strictEqual(guide.product, "xytara", "first-run guide product");
+    assert.ok(String(guide.safe_quote_command).includes("--quote-only"), "first-run safe command is quote-only");
+  });
+
+  if (!fs.existsSync(path.join(PACKAGE_DIR, "bin", "xytara-release.js"))) {
+    check("cli_release_not_shipped", () => {
+      const result = runCli([path.join(PACKAGE_DIR, "bin", "xytara.js"), "release", "--summary"]);
+      assert.strictEqual(result.status, 2, "xytara release must exit 2 in the client package");
+      assert.ok(result.stderr.includes("not part of the xytara client package"), "xytara release notice");
+    });
+  }
+
+  console.log(JSON.stringify({
+    ok: true,
+    product: "xytara",
+    category: "xytara-client-verification",
+    version,
+    checks,
+    paid_receipt_id: paidResult && paidResult.delivery_receipt ? paidResult.delivery_receipt.receipt_id : null
+  }));
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error && error.stack ? error.stack : error}\n`);
+  process.exitCode = 1;
+});

package/scripts/verify_release_candidate.js

@@ -1,23 +1,84 @@
 "use strict";
 
+// Release-candidate gate for the xytara CLIENT package. Node built-ins only, so it runs both in
+// the private repository checkout (prepublishOnly) and inside an installed node_modules/xytara.
+//
+// In-repo mode (server.js present next to package.json): the npm tarball must contain EXACTLY the
+// thin client allowlist below — any extra file fails the gate — and package.json must point at
+// the client entry and the client bins.
+// Installed mode (no server.js): the installed package must carry nothing from the runtime side.
+// Both modes run scripts/verify_client.js (offline client tests) and check RELEASE_NOTES.md.
+
 const assert = require("assert");
 const fs = require("fs");
 const path = require("path");
-const { execFileSync, execSync } = require("child_process");
-const packageJson = require("../package.json");
+const { spawnSync } = require("child_process");
 
-function parsePackDryRun() {
-  const output = execSync("npm pack --dry-run --json", {
-    cwd: path.resolve(__dirname, ".."),
-    encoding: "utf8"
-  });
-  const parsed = JSON.parse(output);
-  return Array.isArray(parsed) ? parsed[0] : parsed;
+const PACKAGE_DIR = path.resolve(__dirname, "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf8"));
+
+// The complete published surface (package.json is always added by npm).
+const SHIPPED_FILES = [
+  "client.js",
+  "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",
+  "START_HERE.md",
+  "RELEASE_NOTES.md",
+  "LICENSE",
+  "NOTICE"
+];
+const TARBALL_FILES = ["package.json", ...SHIPPED_FILES];
+const SHIPPED_BINS = { xytara: "bin/xytara.js", "xytara-run": "bin/xytara-run.js" };
+
+// Nothing from the hosted service may be present in an installed copy.
+const FORBIDDEN_INSTALLED_PATHS = [
+  "server.js",
+  "index.js",
+  ".env.example",
+  "bin/xytara-release.js",
+  "fixtures",
+  "adapters",
+  "integrations",
+  "services",
+  "examples"
+];
+const ALLOWED_DIR_CONTENTS = {
+  lib: ["commerce_client.js", "delivery_receipt_verify.js"],
+  bin: ["xytara.js", "xytara-run.js", "xytara-first-run.js"],
+  scripts: ["verify_release_candidate.js", "verify_client.js"]
+};
+
+function sorted(list) {
+  return list.slice().sort();
+}
+
+function isRepoCheckout() {
+  return fs.existsSync(path.join(PACKAGE_DIR, "server.js"));
+}
+
+function verifyManifest() {
+  assert.strictEqual(packageJson.name, "xytara", "package name mismatch");
+  assert.strictEqual(packageJson.main, "client.js", "package.json main must be the client entry (client.js)");
+  assert.deepStrictEqual(packageJson.bin, SHIPPED_BINS, "package.json bin must be exactly xytara and xytara-run");
+  assert.deepStrictEqual(sorted(packageJson.files || []), sorted(SHIPPED_FILES), "package.json files must equal the thin client allowlist");
+  assert.strictEqual(packageJson.license, "Apache-2.0", "client package license must stay Apache-2.0");
+  assert.strictEqual(packageJson.publishConfig && packageJson.publishConfig.access, "public", "publishConfig.access must be public");
+  assert.strictEqual(packageJson.scripts && packageJson.scripts.prepublishOnly, "npm run verify:release-candidate", "prepublishOnly must run this gate");
+  assert.strictEqual(packageJson.exports && packageJson.exports["."], "./client.js", "exports['.'] must resolve to client.js");
+  assert.strictEqual(packageJson.exports && packageJson.exports["./package.json"], "./package.json", "exports must keep ./package.json reachable");
+  for (const relative of SHIPPED_FILES) {
+    assert.strictEqual(fs.existsSync(path.join(PACKAGE_DIR, relative)), true, `shipped file missing on disk: ${relative}`);
+  }
 }
 
 function verifyReleaseNotes() {
-  const notesPath = path.resolve(__dirname, "..", "RELEASE_NOTES.md");
-  const notes = fs.readFileSync(notesPath, "utf8");
+  const notes = fs.readFileSync(path.join(PACKAGE_DIR, "RELEASE_NOTES.md"), "utf8");
   assert.strictEqual(
     /^#\s+xytara\s+\d+\.\d+\.\d+\s+Release Notes\s*$/m.test(notes),
     false,
@@ -26,7 +87,7 @@ function verifyReleaseNotes() {
   assert.strictEqual(
     notes.includes(`xytara\` ${packageJson.version}`),
     true,
-    "RELEASE_NOTES.md must mention the current package version"
+    `RELEASE_NOTES.md must mention the current package version (${packageJson.version})`
   );
   const mentionedVersions = notes.match(/\b\d+\.\d+\.\d+\b/g) || [];
   assert.strictEqual(
@@ -36,46 +97,86 @@ function verifyReleaseNotes() {
   );
 }
 
-function main() {
-  const releaseOutput = execFileSync(process.execPath, [
-    path.resolve(__dirname, "..", "bin", "xytara-release.js"),
-    "--candidate",
-    "--summary"
-  ], {
-    cwd: path.resolve(__dirname, ".."),
-    encoding: "utf8"
+function parsePackDryRun() {
+  const result = spawnSync("npm pack --dry-run --json", {
+    cwd: PACKAGE_DIR,
+    encoding: "utf8",
+    shell: true,
+    maxBuffer: 16 * 1024 * 1024
   });
-  const releaseCandidate = JSON.parse(releaseOutput);
-  assert.strictEqual(releaseCandidate.product, "xytara", "release candidate product mismatch");
-  assert.strictEqual(releaseCandidate.publish_access, "public", "release candidate publish access mismatch");
-  assert.strictEqual(releaseCandidate.checklist_count >= 5, true, "release candidate checklist count mismatch");
-  verifyReleaseNotes();
+  assert.strictEqual(result.status, 0, `npm pack --dry-run failed: ${result.stderr || result.stdout}`);
+  const parsed = JSON.parse(result.stdout);
+  return Array.isArray(parsed) ? parsed[0] : parsed;
+}
 
+function verifyTarball() {
   const dryRun = parsePackDryRun();
   assert.strictEqual(dryRun.name, packageJson.name, "npm pack dry-run name mismatch");
   assert.strictEqual(dryRun.version, packageJson.version, "npm pack dry-run version mismatch");
   assert.strictEqual(Array.isArray(dryRun.files), true, "npm pack dry-run file list missing");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "bin/xytara-run.js"), true, "npm pack dry-run missing xytara-run");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "bin/xytara-first-run.js"), true, "npm pack dry-run missing xytara-first-run");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "bin/xytara-release.js"), true, "npm pack dry-run missing xytara-release");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "scripts/verify_release_candidate.js"), true, "npm pack dry-run missing release verifier script");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "scripts/verify_framework_provider_promotion.js"), true, "npm pack dry-run missing framework provider promotion verifier script");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "scripts/verify_operator_observability_boundary.js"), true, "npm pack dry-run missing operator observability boundary verifier script");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "scripts/verify_pricing_experiment_plan.js"), true, "npm pack dry-run missing pricing experiment verifier script");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "scripts/verify_treasury_public_boundary.js"), true, "npm pack dry-run missing treasury public boundary verifier script");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "scripts/verify_full_catalog.js"), true, "npm pack dry-run missing full catalog verifier script");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "scripts/verify_all.js"), true, "npm pack dry-run missing package verifier script");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "lib/framework_provider_promotion.js"), true, "npm pack dry-run missing framework provider promotion pack");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "README.md"), true, "npm pack dry-run missing README");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "RELEASE_NOTES.md"), true, "npm pack dry-run missing release notes");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "START_HERE.md"), true, "npm pack dry-run missing start-here");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "SERVICE_CONTRACT.md"), true, "npm pack dry-run missing service contract");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "OPERATOR_START_HERE.md"), false, "npm pack dry-run should not ship operator start-here");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "OPERATIONS_RUNBOOK.md"), false, "npm pack dry-run should not ship operations runbook");
-  assert.strictEqual(dryRun.files.some((entry) => entry.path === "PUBLISH_PLAN.md"), false, "npm pack dry-run should not ship publish plan");
-  assert.strictEqual(dryRun.files.length >= 10, true, "npm pack dry-run file count too small");
+  const packed = sorted(dryRun.files.map((entry) => String(entry.path).replace(/\\/g, "/")));
+  const expected = sorted(TARBALL_FILES);
+  const extra = packed.filter((file) => !expected.includes(file));
+  const missing = expected.filter((file) => !packed.includes(file));
+  assert.deepStrictEqual(
+    { extra, missing },
+    { extra: [], missing: [] },
+    `npm tarball must contain exactly the thin client files (extra: ${JSON.stringify(extra)}, missing: ${JSON.stringify(missing)})`
+  );
+  return packed;
+}
+
+function verifyInstalledLayout() {
+  for (const relative of FORBIDDEN_INSTALLED_PATHS) {
+    assert.strictEqual(fs.existsSync(path.join(PACKAGE_DIR, relative)), false, `installed client package must not contain ${relative}`);
+  }
+  for (const [dir, allowed] of Object.entries(ALLOWED_DIR_CONTENTS)) {
+    const entries = fs.readdirSync(path.join(PACKAGE_DIR, dir));
+    const unexpected = entries.filter((entry) => !allowed.includes(entry));
+    assert.deepStrictEqual(unexpected, [], `installed client package carries unexpected files in ${dir}/: ${JSON.stringify(unexpected)}`);
+  }
+}
 
-  console.log("xytara verify:release-candidate passed");
+function runClientVerification() {
+  const result = spawnSync(process.execPath, [path.join(__dirname, "verify_client.js")], {
+    cwd: PACKAGE_DIR,
+    stdio: ["ignore", "pipe", "inherit"],
+    encoding: "utf8"
+  });
+  assert.strictEqual(result.status, 0, "scripts/verify_client.js failed");
+  const lastLine = String(result.stdout || "").trim().split(/\r?\n/).pop();
+  let summary = null;
+  try {
+    summary = JSON.parse(lastLine);
+  } catch (_) {
+    summary = null;
+  }
+  assert.ok(summary && summary.ok === true, "verify_client.js did not report ok");
+  return summary;
+}
+
+function main() {
+  const mode = isRepoCheckout() ? "repo" : "installed";
+  verifyManifest();
+  verifyReleaseNotes();
+  let tarballFiles = null;
+  if (mode === "repo") {
+    tarballFiles = verifyTarball();
+  } else {
+    verifyInstalledLayout();
+  }
+  const clientSummary = runClientVerification();
+  console.log(JSON.stringify({
+    ok: true,
+    product: "xytara",
+    category: "xytara-release-candidate-verification",
+    mode,
+    version: packageJson.version,
+    main: packageJson.main,
+    bins: Object.keys(packageJson.bin),
+    tarball_file_count: tarballFiles ? tarballFiles.length : null,
+    client_checks: clientSummary.checks
+  }));
 }
 
 main();