xytara 3.3.0 → 3.5.0

package/README.md

@@ -135,8 +135,23 @@ POST /v1/credits/agents/:id/revoke owner key only; immediate; { reason } is stor
 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
+GET  /v1/credits/agents/log        the delegation log: every mint and revoke of the account's agent
+                                   keys (full events); an agent key sees only its own
+GET  /v1/credits/agents/:id/proof  delegation proof for one key: its events, the hash-only chain to
+                                   the head, the signed checkpoint, how to verify
+GET  /v1/delegation-log/head       public: event count, head hash, chain continuity
+GET  /v1/delegation-log/feed       public: seq, type, time and hashes only (never an account or key)
+GET  /v1/delegation-log/checkpoint public: naxytra-attestation/1 over the head (+ ctp/1 binding
+                                   while anchoring); POST .../checkpoint/verify is a free check
 ```
 
+Every mint and revoke is an append-only, hash-chained event (`naxytra-delegation-log/1`:
+`event_sha256 = sha256(JCS(event))`, `chain_hash = sha256(previous chain_hash + event_sha256)`).
+A relying party holding a key's delegation proof and a checkpoint can establish, without asking
+this runtime, that the key was minted with these caps before T and not revoked before a head
+anchored after T. Set `XYTARA_EXTERNAL_BINDING_JSON` while a chronology anchoring session is open
+and every checkpoint carries the binding inside its signed bytes.
+
 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
@@ -194,9 +209,14 @@ live RPC read, that you can hand to another party.
 `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
+unavailable) carries no attestation and is not charged. `bindings` holds external bindings and
+must be carried unchanged — it is inside the signed bytes. The one known scheme is a
+chronology-protocol binding, `{ "scheme": "ctp/1", "system_id": "NAXYTRA-ATTESTATION/1", "tag":
+"<64 hex>" }`: the tag derives from a proof-of-work block that did not exist before the issuer's
+anchoring session opened, so an attestation signed with it inside cannot predate that block; the
+anchor then commits to `attestation_sha256` = SHA-256 of the JCS form of the whole attestation
+(`attestationSha256` in the client; also returned by `GET /attestations/<id>` and
+`POST /attestations/verify`). 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

package/RELEASE_NOTES.md

@@ -1,6 +1,7 @@
-`xytara` 3.3.0 introduces the first paid products beyond pay-per-call tools: signed attestations and team spend authority.
+`xytara` 3.5.0 makes delegated authority provable at a point in time: the delegation log.
 
-- **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.
+- **Delegation log (`naxytra-delegation-log/1`)** — every agent-key mint (delegatee, key fingerprint, caps, expiry) and revoke (stated time, reason) is an append-only, hash-chained event: `event_sha256 = sha256(JCS(event))`, `chain_hash = sha256(previous chain_hash + event_sha256)`. Mint and revoke responses return the event reference (`delegation_event`).
+- **Public, key-less surface** — `GET /v1/delegation-log/head` (count, head hash, chain continuity), `GET /v1/delegation-log/feed?since_seq=&limit=` (seq, type, time and hashes only — never an account, a key or a label), `GET /v1/delegation-log/checkpoint` (a `naxytra-attestation/1` over the head, signed with the delivery-receipt keys; `POST /v1/delegation-log/checkpoint/verify` is a free check). The keys endpoint announces the log.
+- **Owner and agent views** — `GET /v1/credits/agents/log` (owner key: the account's full events; agent key: its own) and `GET /v1/credits/agents/:id/proof`: the key's events, the hash-only chain from its first event to the head, the current checkpoint and its digest, plus the verification recipe. A relying party holding a proof and a checkpoint establishes, without asking the runtime, that a key was minted with these caps before T and not revoked before a head anchored after T.
+- **Chronology binding on checkpoints** — `XYTARA_EXTERNAL_BINDING_JSON` (the `{scheme, system_id, tag}` object or the bare 64-hex tag, scheme `ctp/1`, system id `NAXYTRA-DELEGATION-LOG/1`) is carried inside every checkpoint's signed bytes while an anchoring session is open; `attestation_sha256` of the checkpoint is the digest an external anchor commits to.
+- Client package (thin): unchanged.

package/client.js

@@ -15,6 +15,9 @@ const {
   verificationRecipe,
   attestationSignedBytes,
   verifyAttestation,
+  attestationSha256,
+  normalizeExternalBinding,
+  EXTERNAL_BINDING_SCHEMES,
   attestationRecipe
 } = require("./lib/delivery_receipt_verify");
 const { version } = require("./package.json");
@@ -80,6 +83,11 @@ module.exports = {
   attestationSignedBytes,
   verifyAttestation,
   attestationRecipe,
+  // External bindings (chronology anchoring): the digest an anchor commits to, the binding shape
+  // check, and the known schemes.
+  attestationSha256,
+  normalizeExternalBinding,
+  EXTERNAL_BINDING_SCHEMES,
   // x402 header helpers for the paid command path.
   X402_PAYMENT_HEADER,
   X402_PAYMENT_REQUIRED_HEADER,

package/lib/delivery_receipt_verify.js

@@ -34,6 +34,15 @@ const ATTESTATION_VERSION = "naxytra-attestation/1";
 // `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}$/;
+// External bindings an attestation may carry INSIDE its signed bytes (attestation.bindings[]).
+// "ctp/1": a chronology-protocol binding tag — a value derived from a proof-of-work block that did
+// not exist when the attestation's session opened, so an attestation signed with it inside cannot
+// predate that block (the lower time bound); the anchor then commits to attestation_sha256 (the
+// upper bound). The tag is the derived binding tag, never the raw challenge, so records bound in
+// different systems cannot be correlated. Shape: { scheme: "ctp/1", system_id, tag: <64 hex> }.
+const EXTERNAL_BINDING_SCHEMES = ["ctp/1"];
+const EXTERNAL_BINDING_TAG_PATTERN = /^[0-9a-f]{64}$/;
+const EXTERNAL_BINDING_SYSTEM_ID_PATTERN = /^[\x21-\x7e]{1,64}$/;
 
 // 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.
@@ -193,6 +202,27 @@ function verifyAttestation(attestation, trustedKeys) {
   };
 }
 
+// The digest an external anchor (e.g. a chronology-protocol checkpoint) commits to: sha256 of the
+// JCS form of the WHOLE attestation, signatures included. Stable across re-serialisation because
+// it is computed over the canonical form, not the bytes a transport happened to send.
+function attestationSha256(attestation) {
+  return hashCanonical(attestation);
+}
+
+// Normalizes one external binding ({ scheme, system_id, tag }) for issuing or inspection.
+// Returns { binding } or { reason }; unknown schemes and malformed tags are refused so that an
+// attestation never carries a binding a verifier could not interpret.
+function normalizeExternalBinding(candidate) {
+  const c = isPlainObject(candidate) ? candidate : null;
+  if (!c) return { reason: "binding_must_be_an_object" };
+  if (!EXTERNAL_BINDING_SCHEMES.includes(c.scheme)) return { reason: "unsupported_binding_scheme", scheme: c.scheme === undefined ? null : c.scheme };
+  const systemId = typeof c.system_id === "string" ? c.system_id : "";
+  if (!EXTERNAL_BINDING_SYSTEM_ID_PATTERN.test(systemId)) return { reason: "binding_system_id_invalid" };
+  const tag = typeof c.tag === "string" ? c.tag.toLowerCase() : "";
+  if (!EXTERNAL_BINDING_TAG_PATTERN.test(tag)) return { reason: "binding_tag_must_be_64_hex" };
+  return { binding: { scheme: c.scheme, system_id: systemId, tag } };
+}
+
 // A short, self-contained recipe for verifying an attestation without trusting the issuer's server.
 function attestationRecipe(keysUrl) {
   return {
@@ -203,8 +233,9 @@ function attestationRecipe(keysUrl) {
       "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."
+      "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[] (inside the signed bytes; carry unchanged) may hold external bindings: { scheme: \"ctp/1\", system_id, tag } is a chronology-protocol binding tag, proving the attestation was created after the proof-of-work block that minted the tag; the external anchor commits to attestation_sha256 = sha256(JCS(attestation)) for the upper bound."
     ],
+    external_bindings: { schemes: EXTERNAL_BINDING_SCHEMES.slice(), digest: "attestation_sha256 = sha256(JCS(attestation)), signatures included" },
     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."
   };
 }
@@ -216,6 +247,7 @@ module.exports = {
   ATTESTATION_VERSION,
   ATTESTATION_CANONICALIZATION,
   ATTESTATION_ID_PATTERN,
+  EXTERNAL_BINDING_SCHEMES,
   canonicalize,
   sha256Hex,
   hashCanonical,
@@ -226,5 +258,7 @@ module.exports = {
   verificationRecipe,
   attestationSignedBytes,
   verifyAttestation,
+  attestationSha256,
+  normalizeExternalBinding,
   attestationRecipe
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "3.3.0",
+  "version": "3.5.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 && node scripts/verify_team_spend.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 && node scripts/verify_delegation_log.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",
@@ -120,6 +120,7 @@
     "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:delegation-log": "node scripts/verify_delegation_log.js",
     "verify:client": "node scripts/verify_client.js"
   }
 }

package/scripts/verify_client.js

@@ -252,7 +252,7 @@ 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", "verifyAttestation", "attestationRecipe", "attestationSignedBytes", "encodeX402PaymentHeader", "decodeX402Header", "summarizeCommandResultPayload", "summarizeCatalogPayload", "summarizeReceiptPayload"]) {
+    for (const name of ["verifyDeliveryReceipt", "canonicalize", "hashCanonical", "keyRef", "verificationRecipe", "verifyAttestation", "attestationRecipe", "attestationSignedBytes", "attestationSha256", "normalizeExternalBinding", "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");
@@ -309,7 +309,9 @@ async function main() {
   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 bindings = [{ scheme: "ctp/1", system_id: "NAXYTRA-ATTESTATION/1", tag: "7d".repeat(32) }];
+    assert.deepStrictEqual(client.normalizeExternalBinding(bindings[0]).binding, bindings[0], "a ctp/1 binding { scheme, system_id, tag } normalizes to itself");
+    assert.deepStrictEqual(client.EXTERNAL_BINDING_SCHEMES, ["ctp/1"], "known binding schemes");
     const attestation = signAttestation({
       attestation_id: "att_0123456789ab",
       issued_at_iso: "2026-01-01T00:00:02.000Z",
@@ -331,6 +333,8 @@ async function main() {
     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");
+    assert.strictEqual(client.attestationSha256(reordered), client.attestationSha256(attestation), "attestation_sha256 is the same digest whatever the key order (JCS, signatures included)");
+    assert.notStrictEqual(client.attestationSha256(attestation), result.signed_bytes_sha256, "attestation_sha256 (signatures included) differs from the signed-bytes hash");
     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
@@ -338,7 +342,7 @@ async function main() {
     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" });
+    tamperedBindings.bindings.push({ scheme: "ctp/1", system_id: "LATER", tag: "00".repeat(32) });
     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 = [];