xytara 3.3.0 → 3.4.0

package/README.md

@@ -194,9 +194,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,9 @@
-`xytara` 3.3.0 introduces the first paid products beyond pay-per-call tools: signed attestations and team spend authority.
+`xytara` 3.4.0 makes the open provider network pay correctly at the current price, anchors attestations in time, and gives buyers a console.
 
-- **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.
+- **Provider revenue at the $0.01 price** — a provider's exact share (`settled × bps / 10000`) is now credited in whole cents with the sub-cent remainder carried into its next settlement (`rollup.share_carry_bp`; ledger rows record `share_carry_before_bp` / `share_carry_after_bp`), so a 70% provider earns 7 cents over ten $0.01 calls instead of flooring to zero on every call. Nothing changes for whole-cent amounts.
+- **Payout sweep** — `POST /v1/provider-network/payouts/sweep` (operator) pays every active provider whose available balance reaches `XYTARA_PROVIDER_PAYOUT_MIN_MINOR` (default 100 cents) through the signer, one idempotent dispatch each; a weekly job runs it (Mondays, `state-backup.yml`). Activation through the operator route now requires a `payout_address` on the record (`payout_address_required_for_activation`).
+- **Delivery rule** — a provider's 2xx without `result.output`, `output_payload` or `output` is `external_execution_empty_output`: not charged, nothing accrues, not retried elsewhere. Routing prefers the most specific capability match (tool name over task ref over integration), then reputation. Providers rotate their `owner_secret` at `POST /v1/provider-network/providers/:id/rotate-secret`. The public contract (`/v1/provider-network/contract`) states all of this.
+- **Operator visibility** — the daily report lists pending provider registrations (and flags a missing payout address) and the network's owed/accrued/paid totals, and fails (emails) while a registration waits.
+- **Attestation external bindings** — `bindings[]` inside the signed bytes may carry `{ scheme: "ctp/1", system_id, tag }`, a chronology-protocol binding tag set with `MCP_EXECUTOR_EXTERNAL_BINDING_JSON` on the MCP executor while an anchoring session is open; the active binding is shown on `/.well-known/delivery-receipt-keys` and `/health`. `GET /attestations/<id>` and `POST /attestations/verify` return `attestation_sha256` (SHA-256 of the JCS form, signatures included), the digest an external anchor commits to.
+- **Buyer console** — `https://www.naxytra.com/console`: paste a spend key to read the balance, the credit activity and the agent keys straight from the runtime, and mint or revoke agent keys; the key stays in the browser.
+- Client package (thin): adds `attestationSha256`, `normalizeExternalBinding`, `EXTERNAL_BINDING_SCHEMES`; tarball otherwise 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.4.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": {

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 = [];