xytara 3.2.1 → 3.3.0

package/README.md

@@ -22,6 +22,7 @@ This package ships:
 
 - `CommerceClient` — discover the catalog, quote, run the paid command path, read results
 - the delivery-receipt verifier — `verifyDeliveryReceipt`, `canonicalize`, `hashCanonical`, `keyRef`
+- the attestation verifier — `verifyAttestation`, `attestationRecipe`, `ATTESTATION_VERSION`
 - x402 header helpers — `encodeX402PaymentHeader`, `decodeX402Header`
 - the `xytara` / `xytara-run` CLIs (quote-only first, then funded execution)
 - `endpoints` (runtime, mcp, website) and `version`
@@ -117,6 +118,36 @@ tools/call  -> 402 Payment Required with a price
 Point any MCP client at the endpoint; the public integration guide is
 [github.com/naxytra/naxytra-mcp](https://github.com/naxytra/naxytra-mcp).
 
+## Teams: one owner key, many agent keys
+
+The spend credential a top-up returns is the **owner key** for its account. It can mint capped,
+revocable **agent keys** for each of your agents; every spend is audited. All routes take a spend
+credential as `Authorization: Bearer xytara_spend_...`.
+
+```
+POST /v1/credits/agents            owner key only -> 201 { agent, bearer_token }   (token shown once)
+     { label, max_units_per_call?, max_units_per_day?, max_units_total?, expires_at_iso?,
+       allowed_tools?: ["keccak256", ...], agent_public_key?: <ed25519 SPKI PEM> }
+GET  /v1/credits/agents            owner: every agent key (never tokens) with bounds, status,
+                                   spent_today_units / spent_total_units / last_used_at_iso;
+                                   an agent key sees only itself
+POST /v1/credits/agents/:id/revoke owner key only; immediate; { reason } is stored
+GET  /v1/credits/activity?limit=100&since=<iso>
+                                   recent spends with agent id/label, units, task_ref, tool_name,
+                                   credit_spend_id; owner sees the account, an agent sees its own
+```
+
+An agent key spends exactly like the owner key (`/v1/economics/rails/credits/consume`, or
+`credits_first` execution), but every spend is checked against its per-call, per-UTC-day and
+lifetime caps, its tool allow-list, its expiry and revocation. Refusals are explicit and never
+debit: `agent_call_cap_exceeded`, `agent_daily_cap_exceeded`, `agent_total_cap_exceeded`,
+`agent_tool_not_allowed`, `spend_credential_expired`, `spend_credential_inactive`. Owner keys have
+no caps. Agent keys cannot mint (`agent_key_cannot_mint`) or see other agents. A key minted with
+`agent_public_key` is key-bound: each spend must also carry `x-agent-signature` /
+`x-agent-timestamp` over `naxytra-spend-auth:<agent_credential_id>:<ts>:<sha256(JSON
+["naxytra-spend-binding/v1", account_id, String(units), task_ref])>`, so a captured signature cannot
+be replayed or stretched to a larger spend.
+
 ## Signed delivery receipts
 
 Every paid call returns a `naxytra-delivery-receipt/1`: the payment leg (network, asset, amount,
@@ -144,6 +175,50 @@ POST /v1/delivery-receipts/verify         # free signature check
 A receipt proves who delivered what for which paid call, unaltered since signing — **not** whether
 the output was correct or good. Check the settlement transaction on-chain yourself.
 
+## Attestations (verified answers)
+
+The MCP server's `x402.verify-receipt` and `tx.status` tools cost **$0.02 per call** (20000 USDC
+base units on Base mainnet, 2000 on Base Sepolia; 6 credits with a spend key — the free allowance
+covers them too) and return, next to the tool output, a signed `naxytra-attestation/1` in
+`result._meta["naxytra.com/attestation"]`: a statement of what the server observed on-chain from a
+live RPC read, that you can hand to another party.
+
+```json
+{ "version": "naxytra-attestation/1", "attestation_id": "att_…", "issued_at_iso": "…", "issuer": "xytara-mcp-executor",
+  "subject": { "kind": "x402_settlement", "network": "eip155:8453", "tx": "0x…", "payer": "0x…", "pay_to": "0x…", "asset": "0x…", "amount": "10000" },
+  "claim": { "verified": true, "method": "base-rpc-logs/1", "observed_at_iso": "…", "block_number": 4080, "status": "success", "details": { "verdict": "confirmed", "checks": { … }, "transfer": { … } } },
+  "evidence_sha256": "<sha256 of JCS { tool, arguments, output }>", "bindings": [],
+  "sig": { "suite": ["EdDSA", "ML-DSA-65"], "kids": { "EdDSA": "ed25519-spki-sha256:…", "ML-DSA-65": "ml-dsa-65-spki-sha256:…" }, "signatures": { "EdDSA": "…", "ML-DSA-65": "…" } } }
+```
+
+`subject.kind` is `x402_settlement` (method `base-rpc-logs/1`) or `transaction_status` (method
+`base-rpc-receipt/1`, with `confirmations`). A negative answer (`claim.verified: false` — the
+receipt does not match the chain, the transaction is unknown) is attested too; a tool error (RPC
+unavailable) carries no attestation and is not charged. `bindings` is reserved for external
+bindings (for example `{ "scheme": "ctp/1", "q": "…" }`) and must be carried unchanged — it is
+inside the signed bytes. Signed bytes = JCS of the attestation with `sig.signatures` removed
+(`sig.suite` and `sig.kids` stay signed), with the same keys as the delivery receipts.
+
+```js
+const { verifyAttestation, hashCanonical, attestationRecipe } = require("xytara");
+
+const keys = (await fetch("https://xytara-mcp-executor.onrender.com/.well-known/delivery-receipt-keys").then((r) => r.json())).keys;
+const check = verifyAttestation(attestation, keys);        // { valid, claim_verified, signatures: [{ alg, kid, valid }], ... }
+const evidenceMatches = hashCanonical({ tool, arguments, output }) === attestation.evidence_sha256;
+console.log(attestationRecipe("/.well-known/delivery-receipt-keys").steps);
+```
+
+```
+GET  /.well-known/delivery-receipt-keys   # keys + attestation_recipe (same keys as receipts)
+GET  /attestations/:attestation_id        # one of the last 5000 issued
+POST /attestations/verify                 # free signature check: { attestation } -> { valid, kids_known, ... }
+```
+
+Key-bound spend credentials: send your `X-Agent-Signature` / `X-Agent-Timestamp` headers with the
+MCP call; the executor forwards them to the credits debit unchanged. A request-bound signature
+commits to `{ account_id, units, task_ref: "adapter.mcp.invoke" }` with `units` = the tool's
+`credits_per_call` (3, or 6 for an attesting tool).
+
 ## Verify the package
 
 ```bash

package/RELEASE_NOTES.md

@@ -1,8 +1,6 @@
-`xytara` 3.2.1 makes paying plug-and-play for every kind of client.
+`xytara` 3.3.0 introduces the first paid products beyond pay-per-call tools: signed attestations and team spend authority.
 
-- **Free daily allowance** — every caller of the MCP server gets 20 free tool calls per UTC day, no key or wallet needed; each result reports the remaining allowance in `_meta["naxytra.com/allowance"]`.
-- **Spend-key mode** — a prepaid spend credential (`Authorization: Bearer xytara_spend_…`, `X-Naxytra-Key`, or `?key=` on the MCP URL for clients that cannot set headers) pays 3 credits per call from the runtime; failed calls are never debited, and a retried debit with the same id is never charged twice. The self-serve top-up ($1.00 USDC on Base = 400 credits) returns the key.
-- **Balance endpoint** — `GET /v1/credits/balance` with the spend credential; browser-callable (CORS) so the buy and setup pages can show it.
-- **Hosted-deploy hardening** — the credit lifecycle routes (reserve, release, reverse) now require the account's spend credential or the operator token; a bare account id is never authority.
-- **Payment-required results** now explain the allowance, the two ways to continue (spend key or x402) and the price. The server card no longer says "no API keys".
-- Client package (thin): unchanged surface; the MCP server itself is not distributed.
+- **Signed attestations (verified answers)** — `x402.verify-receipt` and `tx.status` now return, in `_meta["naxytra.com/attestation"]`, a signed `naxytra-attestation/1` statement of the on-chain fact they verified (settlement matched or not; transaction status, block, confirmations), JCS-canonical and signed Ed25519 + ML-DSA-65 with the same keys as delivery receipts, with an `evidence_sha256` and a reserved `bindings` field. Negative findings are attested too; nothing is attested without a live chain read. Price $0.02 per call via x402 (20000 units on Base mainnet, 2000 on Base Sepolia) or 6 credits with a spend key; still within the free daily allowance. Free: `GET /attestations/<id>`, `POST /attestations/verify`, and offline verification with the client (`verifyAttestation`).
+- **Teams (beta)** — an owner key (the key a top-up returns) mints capped agent keys: `POST /v1/credits/agents` (per-call, per-day and total caps, expiry, tool allow-list, optional key-binding so every spend needs a fresh request-bound signature), `GET /v1/credits/agents`, `POST /v1/credits/agents/:id/revoke`, `GET /v1/credits/activity` (audit trail). Caps are enforced before any provider work runs and again at commit; an agent key cannot mint keys, see other agents, or borrow another agent's caps.
+- **Fixes** — an uncapped authority binding no longer refuses every delegated spend; the daily report lists the most common detail behind each frequent failure reason and names unidentified callers by their user-agent token.
+- Client package (thin): adds `verifyAttestation`, `attestationRecipe`, `attestationSignedBytes`, `ATTESTATION_VERSION`; tarball otherwise unchanged.

package/client.js

@@ -7,11 +7,15 @@
 const commerceClient = require("./lib/commerce_client");
 const {
   RECEIPT_VERSION,
+  ATTESTATION_VERSION,
   canonicalize,
   hashCanonical,
   keyRef,
   verifyDeliveryReceipt,
-  verificationRecipe
+  verificationRecipe,
+  attestationSignedBytes,
+  verifyAttestation,
+  attestationRecipe
 } = require("./lib/delivery_receipt_verify");
 const { version } = require("./package.json");
 
@@ -70,6 +74,12 @@ module.exports = {
   keyRef,
   verifyDeliveryReceipt,
   verificationRecipe,
+  // Signed attestations (the MCP executor's verified answers): offline verification with the
+  // same published keys.
+  ATTESTATION_VERSION,
+  attestationSignedBytes,
+  verifyAttestation,
+  attestationRecipe,
   // x402 header helpers for the paid command path.
   X402_PAYMENT_HEADER,
   X402_PAYMENT_REQUIRED_HEADER,

package/lib/delivery_receipt_verify.js

@@ -12,6 +12,12 @@
 // 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.
 //
+// Signed attestations ("naxytra-attestation/1") share the same keys, kid format and verifier
+// pattern: a short, signed statement of an on-chain fact (an x402 settlement, a transaction's
+// status) that the MCP executor observed from a live RPC read, which the buyer can hand to a third
+// party who verifies it offline. The verification side (verifyAttestation, attestationRecipe) is
+// here too; issuing lives in delivery_receipt.js.
+//
 // Dependency-free (node:crypto). This file is shared verbatim by the xytara runtime
 // (lib/delivery_receipt_verify.js) and the MCP executor
 // (services/mcp-execution-target/delivery_receipt_verify.js); a verifier asserts the two copies
@@ -23,6 +29,12 @@ const RECEIPT_VERSION = "naxytra-delivery-receipt/1";
 const CANONICALIZATION = "JCS (RFC 8785) of the receipt without `sig`";
 const SUPPORTED_ALGS = { ed25519: "EdDSA", "ml-dsa-65": "ML-DSA-65" };
 
+const ATTESTATION_VERSION = "naxytra-attestation/1";
+// Attestation signed bytes: the attestation with `sig.signatures` removed. `sig.suite` and
+// `sig.kids` stay INSIDE the signed bytes, so a stripped algorithm or a swapped key id fails.
+const ATTESTATION_CANONICALIZATION = "JCS (RFC 8785) of the attestation with `sig.signatures` removed (`sig.suite` and `sig.kids` stay signed)";
+const ATTESTATION_ID_PATTERN = /^att_[0-9a-f]{12}$/;
+
 // JCS for the JSON values a receipt carries (strings, finite numbers, booleans, null, arrays,
 // objects). Object keys sorted by UTF-16 code units; `undefined` members dropped like JSON.
 function canonicalize(value) {
@@ -124,10 +136,86 @@ function verificationRecipe(keysUrl) {
   };
 }
 
+// --- attestations ------------------------------------------------------------------------------
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// The bytes every attestation signature covers (see ATTESTATION_CANONICALIZATION).
+function attestationSignedBytes(attestation) {
+  const { sig, ...rest } = attestation;
+  const { signatures: _omit, ...signedSig } = isPlainObject(sig) ? sig : {};
+  return Buffer.from(canonicalize({ ...rest, sig: signedSig }), "utf8");
+}
+
+// Verifies an attestation against a set of trusted public keys ([{ kid, alg, public_key_spki_der_base64 }]).
+// Valid only if the version is known, `bindings` is an array (reserved; carried unchanged), every
+// algorithm in the SIGNED suite has a kid in sig.kids and a signature in sig.signatures, every such
+// kid is in the trusted set, and every signature verifies over the signed bytes.
+function verifyAttestation(attestation, trustedKeys) {
+  const a = isPlainObject(attestation) ? attestation : null;
+  if (!a) return { valid: false, reason: "attestation_required" };
+  if (a.version !== ATTESTATION_VERSION) return { valid: false, reason: "unsupported_attestation_version", version: a.version || null };
+  if (!Array.isArray(a.bindings)) return { valid: false, reason: "bindings_must_be_an_array" };
+  const sig = isPlainObject(a.sig) ? a.sig : null;
+  if (!sig || !Array.isArray(sig.suite) || sig.suite.length === 0 || !isPlainObject(sig.kids) || !isPlainObject(sig.signatures)) {
+    return { valid: false, reason: "attestation_unsigned" };
+  }
+  const signedBytes = attestationSignedBytes(a);
+  const trusted = new Map((Array.isArray(trustedKeys) ? trustedKeys : []).map((key) => [key.kid, key]));
+  const results = sig.suite.map((alg) => {
+    const kid = typeof sig.kids[alg] === "string" ? sig.kids[alg] : null;
+    const value = typeof sig.signatures[alg] === "string" ? sig.signatures[alg] : null;
+    if (!kid) return { alg, kid: null, valid: false, reason: "kid_missing_for_signed_suite" };
+    if (!value) return { alg, kid, valid: false, reason: "signature_missing_for_signed_suite" };
+    const key = trusted.get(kid);
+    if (!key || key.alg !== alg) return { alg, kid, valid: false, reason: "kid_not_in_trusted_key_set" };
+    try {
+      const publicKey = crypto.createPublicKey({ key: Buffer.from(key.public_key_spki_der_base64, "base64"), format: "der", type: "spki" });
+      if (keyRef(publicKey) !== kid) return { alg, kid, valid: false, reason: "kid_does_not_match_key" };
+      const ok = crypto.verify(null, signedBytes, publicKey, Buffer.from(value, "base64"));
+      return { alg, kid, valid: ok, reason: ok ? null : "signature_invalid" };
+    } catch (error) {
+      return { alg, kid, valid: false, reason: "verification_error", detail: error && error.message ? error.message.slice(0, 120) : null };
+    }
+  });
+  const valid = results.length > 0 && results.every((item) => item.valid);
+  return {
+    valid,
+    reason: valid ? null : "signature_check_failed",
+    attestation_id: typeof a.attestation_id === "string" ? a.attestation_id : null,
+    issuer: typeof a.issuer === "string" ? a.issuer : null,
+    subject_kind: isPlainObject(a.subject) && typeof a.subject.kind === "string" ? a.subject.kind : null,
+    claim_verified: isPlainObject(a.claim) && typeof a.claim.verified === "boolean" ? a.claim.verified : null,
+    signatures: results,
+    signed_bytes_sha256: sha256Hex(signedBytes)
+  };
+}
+
+// A short, self-contained recipe for verifying an attestation without trusting the issuer's server.
+function attestationRecipe(keysUrl) {
+  return {
+    version: ATTESTATION_VERSION,
+    signed_bytes: `${ATTESTATION_CANONICALIZATION} (UTF-8).`,
+    keys: keysUrl || null,
+    steps: [
+      "1. Fetch the issuer's public keys; check every kid in attestation.sig.kids is listed (and pin them).",
+      "2. Remove attestation.sig.signatures (keep sig.suite and sig.kids) and JCS-canonicalize what is left: these are the signed bytes.",
+      "3. For every alg in sig.suite, verify sig.signatures[alg] over the signed bytes with the key whose kid is sig.kids[alg] (node:crypto crypto.verify(null, bytes, spkiPublicKey, signature), or xoonya's verifyExternalProofSignature({ material, signature, algorithm, public_key, expected_key_ref: kid })).",
+      "4. Read subject (what was checked), claim.verified / claim.status / claim.details (what was observed) and claim.observed_at_iso (when). evidence_sha256 = sha256(JCS({ tool, arguments, output })) of the tool call that produced it; recompute it when you hold that call. bindings is reserved for external bindings and must be carried unchanged."
+    ],
+    boundary: "Proves this issuer observed this claim about this subject from a live chain read at observed_at_iso, unaltered since signing — not that the chain cannot reorganize, and nothing beyond the stated claim."
+  };
+}
+
 module.exports = {
   RECEIPT_VERSION,
   CANONICALIZATION,
   SUPPORTED_ALGS,
+  ATTESTATION_VERSION,
+  ATTESTATION_CANONICALIZATION,
+  ATTESTATION_ID_PATTERN,
   canonicalize,
   sha256Hex,
   hashCanonical,
@@ -135,5 +223,8 @@ module.exports = {
   runtimeSupportsMlDsa,
   publicKeySet,
   verifyDeliveryReceipt,
-  verificationRecipe
+  verificationRecipe,
+  attestationSignedBytes,
+  verifyAttestation,
+  attestationRecipe
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "3.2.1",
+  "version": "3.3.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": {
@@ -95,7 +95,7 @@
     "verify:production-readiness": "node scripts/verify_production_readiness.js",
     "verify:final-activation": "node scripts/verify_final_activation.js",
     "verify:x402-facilitator": "node scripts/verify_x402_facilitator.js",
-    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_framework_provider_promotion.js && node scripts/verify_operator_observability_boundary.js && node scripts/verify_pricing_experiment_plan.js && node scripts/verify_treasury_public_boundary.js && node scripts/verify_market_lanes.js && node scripts/verify_market_lane_depth.js && node scripts/verify_market_lane_traces.js && node scripts/verify_market_lane_promotion.js && node scripts/verify_provider_runtime_breadth.js && node scripts/verify_provider_runtime_journeys.js && node scripts/verify_lifecycle_continuity.js && node scripts/verify_first_run_conversions.js && node scripts/verify_delivery_summary.js && node scripts/verify_runtime_durability.js && node scripts/verify_revenue_launch_paths.js && node scripts/verify_full_catalog.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js && node scripts/verify_x402_facilitator.js && node scripts/verify_cdp_facilitator.js && node scripts/verify_a2a_rpc.js && node scripts/verify_checkout_processor.js && node scripts/verify_l402_adapter.js && node scripts/verify_bolt_adapter.js && node scripts/verify_mpp_adapter.js && node scripts/verify_rate_limiter.js && node scripts/verify_execution_surfacing.js && node scripts/verify_agent_identity.js && node scripts/verify_verify_execute_settle.js && node scripts/verify_execution_dedupe.js && node scripts/verify_refund_credit.js && node scripts/verify_commerce_bridge.js && node scripts/verify_settlement.js && node scripts/verify_provider_network.js && node scripts/verify_external_execution_retry.js && node scripts/verify_runtime_state_guard.js && node scripts/state_backup_offsite.js selftest && node scripts/verify_lifecycle_spend_binding.js && node scripts/verify_buyer_safety.js && node scripts/verify_buyer_event_log.js && node scripts/verify_x402_settlement_recovery.js",
+    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_framework_provider_promotion.js && node scripts/verify_operator_observability_boundary.js && node scripts/verify_pricing_experiment_plan.js && node scripts/verify_treasury_public_boundary.js && node scripts/verify_market_lanes.js && node scripts/verify_market_lane_depth.js && node scripts/verify_market_lane_traces.js && node scripts/verify_market_lane_promotion.js && node scripts/verify_provider_runtime_breadth.js && node scripts/verify_provider_runtime_journeys.js && node scripts/verify_lifecycle_continuity.js && node scripts/verify_first_run_conversions.js && node scripts/verify_delivery_summary.js && node scripts/verify_runtime_durability.js && node scripts/verify_revenue_launch_paths.js && node scripts/verify_full_catalog.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js && node scripts/verify_x402_facilitator.js && node scripts/verify_cdp_facilitator.js && node scripts/verify_a2a_rpc.js && node scripts/verify_checkout_processor.js && node scripts/verify_l402_adapter.js && node scripts/verify_bolt_adapter.js && node scripts/verify_mpp_adapter.js && node scripts/verify_rate_limiter.js && node scripts/verify_execution_surfacing.js && node scripts/verify_agent_identity.js && node scripts/verify_verify_execute_settle.js && node scripts/verify_execution_dedupe.js && node scripts/verify_refund_credit.js && node scripts/verify_commerce_bridge.js && node scripts/verify_settlement.js && node scripts/verify_provider_network.js && node scripts/verify_external_execution_retry.js && node scripts/verify_runtime_state_guard.js && node scripts/state_backup_offsite.js selftest && node scripts/verify_lifecycle_spend_binding.js && node scripts/verify_buyer_safety.js && node scripts/verify_buyer_event_log.js && node scripts/verify_x402_settlement_recovery.js && node scripts/verify_team_spend.js",
     "prepublishOnly": "npm run verify:release-candidate",
     "verify:cdp-facilitator": "node scripts/verify_cdp_facilitator.js",
     "verify:a2a-rpc": "node scripts/verify_a2a_rpc.js",
@@ -119,6 +119,7 @@
     "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:team-spend": "node scripts/verify_team_spend.js",
     "verify:client": "node scripts/verify_client.js"
   }
 }

package/scripts/verify_client.js

@@ -6,6 +6,8 @@
 //    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.
+//    Signed attestations (naxytra-attestation/1): the same round trip, including the reserved
+//    `bindings` member surviving canonicalization and verification unchanged.
 // 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.
@@ -25,11 +27,15 @@ const client = require(path.join(PACKAGE_DIR, "client.js"));
 const {
   CommerceClient,
   RECEIPT_VERSION,
+  ATTESTATION_VERSION,
   canonicalize,
   hashCanonical,
   keyRef,
   verifyDeliveryReceipt,
   verificationRecipe,
+  attestationSignedBytes,
+  verifyAttestation,
+  attestationRecipe,
   encodeX402PaymentHeader,
   decodeX402Header,
   summarizeCommandResultPayload,
@@ -67,6 +73,22 @@ function signReceipt(body, signer) {
   };
 }
 
+// Attestation issuing, as the MCP executor does it (kept in-test: the client never issues them).
+// Signed bytes = JCS of the attestation with sig.signatures removed (sig.suite / sig.kids signed).
+function signAttestation(body, signer) {
+  const unsigned = {
+    version: ATTESTATION_VERSION,
+    bindings: [],
+    ...body,
+    sig: { suite: [signer.alg], kids: { [signer.alg]: signer.kid } }
+  };
+  const signedBytes = Buffer.from(canonicalize(unsigned), "utf8");
+  return {
+    ...unsigned,
+    sig: { ...unsigned.sig, signatures: { [signer.alg]: crypto.sign(null, signedBytes, signer.privateKey).toString("base64") } }
+  };
+}
+
 function makeSigner() {
   const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519");
   const kid = keyRef(publicKey);
@@ -230,10 +252,11 @@ function runCliAsync(args) {
 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"]) {
+    for (const name of ["verifyDeliveryReceipt", "canonicalize", "hashCanonical", "keyRef", "verificationRecipe", "verifyAttestation", "attestationRecipe", "attestationSignedBytes", "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(ATTESTATION_VERSION, "naxytra-attestation/1", "attestation 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");
@@ -283,6 +306,61 @@ async function main() {
     assert.strictEqual(verifyDeliveryReceipt(null, [signer.trustedKey]).reason, "receipt_required", "missing receipt must fail");
   });
 
+  check("attestation_offline_round_trip", () => {
+    const issuer = makeSigner();
+    const toolCall = { tool: "tx.status", arguments: { tx_hash: "0x" + "9b".repeat(32), network: "base" }, output: { ok: true, found: true, status: "success", block_number: 4080, confirmations: 17 } };
+    const bindings = [{ scheme: "ctp/1", q: "cid:example" }];
+    const attestation = signAttestation({
+      attestation_id: "att_0123456789ab",
+      issued_at_iso: "2026-01-01T00:00:02.000Z",
+      issuer: "xytara-mcp-executor",
+      subject: { kind: "transaction_status", network: "eip155:8453", tx: toolCall.arguments.tx_hash },
+      claim: { verified: true, method: "base-rpc-receipt/1", observed_at_iso: "2026-01-01T00:00:01.000Z", block_number: 4080, confirmations: 17, status: "success", details: { from: "0x" + "11".repeat(20), to: null } },
+      evidence_sha256: hashCanonical(toolCall),
+      bindings
+    }, issuer);
+    assert.strictEqual(attestation.version, ATTESTATION_VERSION, "attestation version");
+    assert.deepStrictEqual(Object.keys(attestation.sig).sort(), ["kids", "signatures", "suite"], "sig = { suite, kids, signatures }");
+    const result = verifyAttestation(attestation, [issuer.trustedKey]);
+    assert.strictEqual(result.valid, true, `genuine attestation must verify: ${JSON.stringify(result)}`);
+    assert.deepStrictEqual([result.attestation_id, result.subject_kind, result.claim_verified, result.signatures[0].alg, result.signed_bytes_sha256.length], ["att_0123456789ab", "transaction_status", true, "EdDSA", 64], "verify result reports id, subject kind, claim and signature");
+    assert.strictEqual(result.signed_bytes_sha256, crypto.createHash("sha256").update(attestationSignedBytes(attestation)).digest("hex"), "signed bytes are the attestation with sig.signatures removed");
+    assert.ok(canonicalize({ ...attestation, sig: { suite: attestation.sig.suite, kids: attestation.sig.kids } }) === attestationSignedBytes(attestation).toString("utf8") && canonicalize(attestation).includes("\"suite\":[\"EdDSA\"]"), "sig.suite and sig.kids are inside the signed bytes");
+    assert.strictEqual(hashCanonical(toolCall), attestation.evidence_sha256, "evidence hash recomputes from { tool, arguments, output }");
+    // bindings: reserved, round-trips unchanged through canonicalization + verification
+    const reordered = JSON.parse(JSON.stringify({ sig: attestation.sig, bindings: attestation.bindings, claim: attestation.claim, ...attestation }));
+    assert.strictEqual(verifyAttestation(reordered, [issuer.trustedKey]).valid, true, "key order must not matter (JCS)");
+    assert.deepStrictEqual(reordered.bindings, bindings, "bindings survive the round trip unchanged");
+    const negative = signAttestation({ ...attestation, claim: { ...attestation.claim, verified: false, status: "not_found" } }, issuer);
+    assert.strictEqual(verifyAttestation(negative, [issuer.trustedKey]).claim_verified, false, "a negative claim (verified:false) is a valid signed attestation");
+    // tamper -> reject
+    const tamperedClaim = JSON.parse(JSON.stringify(attestation));
+    tamperedClaim.claim.verified = false;
+    assert.strictEqual(verifyAttestation(tamperedClaim, [issuer.trustedKey]).valid, false, "tampered claim must fail");
+    const tamperedBindings = JSON.parse(JSON.stringify(attestation));
+    tamperedBindings.bindings.push({ scheme: "ctp/1", q: "added-later" });
+    assert.strictEqual(verifyAttestation(tamperedBindings, [issuer.trustedKey]).valid, false, "bindings are signed: adding one later must fail");
+    const removedBindings = JSON.parse(JSON.stringify(attestation));
+    removedBindings.bindings = [];
+    assert.strictEqual(verifyAttestation(removedBindings, [issuer.trustedKey]).valid, false, "removing a binding must fail");
+    assert.strictEqual(verifyAttestation({ ...attestation, bindings: null }, [issuer.trustedKey]).reason, "bindings_must_be_an_array", "bindings must be an array");
+    const swappedKid = JSON.parse(JSON.stringify(attestation));
+    swappedKid.sig.kids.EdDSA = makeSigner().kid;
+    assert.strictEqual(verifyAttestation(swappedKid, [issuer.trustedKey]).signatures[0].reason, "kid_not_in_trusted_key_set", "swapped kid must fail");
+    assert.strictEqual(verifyAttestation(attestation, [makeSigner().trustedKey]).signatures[0].reason, "kid_not_in_trusted_key_set", "untrusted key set must fail");
+    const stripped = JSON.parse(JSON.stringify(attestation));
+    stripped.sig.signatures = {};
+    assert.strictEqual(verifyAttestation(stripped, [issuer.trustedKey]).signatures[0].reason, "signature_missing_for_signed_suite", "stripped signature must fail");
+    const noSuite = JSON.parse(JSON.stringify(attestation));
+    delete noSuite.sig.suite;
+    assert.strictEqual(verifyAttestation(noSuite, [issuer.trustedKey]).reason, "attestation_unsigned", "missing suite must fail");
+    assert.strictEqual(verifyAttestation({ ...attestation, version: "naxytra-attestation/0" }, [issuer.trustedKey]).reason, "unsupported_attestation_version", "unknown version must fail");
+    assert.strictEqual(verifyAttestation(null, [issuer.trustedKey]).reason, "attestation_required", "missing attestation must fail");
+    const recipe = attestationRecipe("/.well-known/delivery-receipt-keys");
+    assert.deepStrictEqual([recipe.version, recipe.keys, recipe.steps.length], [ATTESTATION_VERSION, "/.well-known/delivery-receipt-keys", 4], "attestation recipe");
+    assert.ok(recipe.signed_bytes.includes("sig.signatures"), "recipe states the signed form");
+  });
+
   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) });