@adastracomputing/ink 0.1.0-alpha.1 → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-All notable changes to INK and the reference implementation are recorded
+All notable changes to INK are recorded
 here. Pre-1.0 releases follow `0.Y.Z` semantics, see
 [`docs/maturity.md`](docs/maturity.md) for the versioning policy.
 
@@ -8,9 +8,48 @@ here. Pre-1.0 releases follow `0.Y.Z` semantics, see
 
 No unreleased changes.
 
+## 0.1.0-alpha.3, signed audit-query response
+
+Closes the last HIGH conformance-audit finding (witness audit-query
+response missing signature, proofs and protocol envelope).
+
+### Added
+
+- `signAuditQueryResponse(payload, privateKey)` and `verifyAuditQueryResponseSignature(payload, signature, publicKey)` primitives. Canonical signed bytes are `ink/audit-query-response/v1\n` + JCS(payload without serviceSignature). The payload binds `serviceDid`, `messageId`, `requester`, `events`, `proofs`, `treeSize`, `rootHash`, `timestamp`, so a valid signature cannot be rebound to a different witness, message, requester, or root.
+- `verifyAuditQueryResponse({response, witnessPublicKey, expectedRequester, expectedMessageId, verifyEventSignature, expectedServiceDid?, laterCheckpoint?})` is the recommended high-level verifier. `verifyEventSignature` is a REQUIRED callback that resolves the submitting agent's keys and validates each event's `agentSignature`. Without it, the verifier refuses to return valid, because Merkle inclusion alone does not prove agent provenance (§7.5). The function enforces envelope shape, requester binding, events/proofs strict one-to-one alignment, the §7.4 per-event scope rule, walks every Merkle proof via `computeAuditMerkleLeafHash` up to the response's `rootHash`, runs `verifyEventSignature` on every event and supports optional later-checkpoint cross-check. `verifyAuditQueryResponseSignature` alone is signature-only and is documented as a low-level primitive.
+- `computeAuditMerkleLeafHash(event)` primitive: the RFC 6962 leaf-hash rule for inclusion proofs, `SHA-256(0x00 || JCS(event-without-agentSignature))`. Distinct from `computeEventHash` (unprefixed, used only for `previousEventHash` chain linkage). Verifiers walking an inclusion proof MUST use this function, not `computeEventHash`.
+- Nix flake now exposes `apps.default`, so `nix run github:Ad-Astra-Computing/ink -- verify-inclusion --file r.json --witness URL` works without `npm install`.
+
+### Security
+
+- The §7.3 envelope now binds `requester`. Without this binding, a signed witness response generated for Alice could be replayed to Bob as Bob's authoritative view of the same `messageId`. Verifiers MUST check the response's `requester` equals their locally authenticated requester before accepting events as a complete view.
+- Witnesses MUST fail closed when the requester's visible event set for a `messageId` exceeds the response cap, returning an unsigned HTTP 413 rather than silently signing a partial response. The reference and OSS witnesses query `LIMIT MAX_QUERY_EVENTS + 1`, detect overflow and refuse to sign.
+- Witnesses MUST emit a deterministic, stable result-set order so signed bytes are reproducible. The reference and OSS witnesses use `ORDER BY event_id ASC`.
+- Storage-integrity failures during proof construction (missing event_hash, hash mismatch, missing Merkle node, unprovable leaf, malformed event_json) now return HTTP 500 instead of silently omitting events from a signed response.
+- All canonicalize-and-sign / canonicalize-and-verify paths now cap by UTF-8 byte length, not JS string length. With non-ASCII event data the prior cap could be undercounted and let oversized payloads through. Affects `buildSignatureBase`, `computeMessageHash`, `signAuditEvent` / `verifyAuditEventSignature`, `computeEventHash`, `signAuditResponse` / `verifyAuditResponseSignature`, `signAuditQueryResponse` / `verifyAuditQueryResponseSignature` and the witness `handleQuery` response-size guard.
+- `verifyAuditEventSignature`, `verifyAuditResponseSignature`, `verifyAuditQueryResponseSignature` now wrap canonicalization inside the try/catch, so payloads that pass the complexity precheck but throw inside `jcsCanonicalize` (e.g. objects with `undefined` values) return `false` instead of propagating.
+
+### Spec
+
+- `specs/ink-auditability.md` §7.3 (audit-query response) now defines the full signed-envelope shape: `{protocol, type: "network.tulpa.audit_query_response", serviceDid, messageId, requester, events, proofs[{eventId, leafIndex, inclusionProof}], treeSize, rootHash, timestamp, serviceSignature}`. Previous text described a bare `{events}` shape with no signature, no protocol envelope and no per-event proofs.
+- §7.3 leaf-hash text now references `computeAuditMerkleLeafHash` directly and warns implementers that `computeEventHash` (chain linkage) is NOT the leaf input.
+- §7.3 now explicitly forbids witnesses from signing partial results: truncation MUST be an unsigned error. A signed response is a complete enumeration of the requester's visible events at `(treeSize, rootHash)`.
+- §7.3 requires witnesses to emit `events` and `proofs` in a stable, deterministic order.
+
+## 0.1.0-alpha.2, inclusion-receipt verifier
+
+Adds a public verification path for INK Auditability Section 7
+inclusion receipts, plus a CLI any third party can run without
+trusting any specific operator's UI.
+
+### Added
+
+- `verifyInclusionReceipt({receipt, witnessPublicKey, eventHash?, laterCheckpoint?})` exported from the package root. Pure function. Returns `{valid, steps[]}` where each step explains pass/fail with detail. Always verifies structure + Ed25519 service signature against the canonical `ink/audit-inclusion/v1\n` + JCS format. Optionally walks the Merkle proof when `eventHash` is provided, and cross-checks against a `laterCheckpoint` for tree-grew-not-rewound + no-fork-at-same-treeSize.
+- `ink` CLI dispatcher with a `verify-inclusion` subcommand. `npx @adastracomputing/ink verify-inclusion --file receipt.json --witness https://witness.example.com` fetches the witness DID document + current checkpoint and runs the full verification. Witness URL is validated (https-only by default, `--allow-http` opt-in, no credentials). Exit code 0 = valid, 1 = invalid, 2 = usage / network / validation error. Self-contained ESM JavaScript so it works on any Node 22+ install with no TypeScript toolchain.
+
 ## 0.1.0-alpha.1, spec clarification
 
-Spec-only release. Reference-implementation code in `src/` is
+Spec-only release. Library code in `src/` is
 unchanged from `0.1.0-alpha.0`; the bundled spec text is updated.
 
 ### Spec changes
@@ -26,8 +65,7 @@ unchanged from `0.1.0-alpha.0`; the bundled spec text is updated.
 
 ## 0.1.0-alpha.0, first public alpha
 
-Initial open-source release of the INK protocol reference implementation
-and accompanying specification.
+Initial open-source release of the INK protocol library and specification.
 
 ### Protocol surface
 
@@ -42,7 +80,7 @@ and accompanying specification.
 - Optional containment extension: capability-gated visibility, handshake
   budgets, sender silent-drop after first rate-limit violation.
 
-### Reference implementation
+### Library
 
 - Public API exported from the package root, see README for the export
   surface.

package/CODE_OF_CONDUCT.md

@@ -11,7 +11,7 @@ Participate in this project as a professional. That means:
 - Assume good faith from contributors and maintainers. If you believe
   someone has acted in bad faith, raise it privately first.
 - Keep public discussions focused on the protocol, the spec, the
-  reference implementation, or related interoperability work.
+  library, or related interoperability work.
 
 ## Scope
 

package/README.md

@@ -65,7 +65,9 @@ const ok = await verifyInkSignature(input, signature, keypair.publicKey);
 
 For inbound request verification, `verifyInkAuth` parses the `Authorization: INK-Ed25519 <sig>` header, checks freshness, and applies the key-rotation authority rule. It requires a `nonceStore` option so the 5-minute freshness window does not silently accept replays; pass a `NonceStore` to have the middleware enforce single-use, or `"deferred"` to acknowledge that the caller will run `checkReplay` (or equivalent) elsewhere in the request pipeline.
 
-For consumers of audit-exchange responses, call both `verifyAuditResponseSignature` (signed response wrapper) and `verifyAuditEventChain` (sequence-by-one and `previousEventHash` continuity, fork detection). The signature gate alone does not prevent a witness from returning a gapped or forked slice.
+For consumers of bilateral audit-exchange responses (`network.tulpa.audit_response`), call both `verifyAuditResponseSignature` (signed response wrapper) and `verifyAuditEventChain` (sequence-by-one and `previousEventHash` continuity, fork detection). The signature gate alone does not prevent a peer from returning a gapped or forked slice.
+
+For consumers of witness audit-query responses (`network.tulpa.audit_query_response`, Auditability §7.3, added in `0.1.0-alpha.3`), call `verifyAuditQueryResponse({response, witnessPublicKey, expectedRequester, expectedMessageId, verifyEventSignature, expectedServiceDid?, laterCheckpoint?})`. The `verifyEventSignature` callback is REQUIRED: it resolves the submitting agent's Ed25519 keys (typically via Agent Card §2) and validates each event's `agentSignature`. Without it, the verifier refuses to return valid, because Merkle inclusion alone does not prove a real agent produced the event (§7.5). The verifier enforces envelope shape, the `requester` binding (prevents cross-requester replay), events/proofs strict one-to-one alignment, the §7.4 per-event scope rule, walks every Merkle proof via `computeAuditMerkleLeafHash` up to the response's `rootHash`, runs `verifyEventSignature` on every event and supports an optional later-checkpoint cross-check. The lower-level `verifyAuditQueryResponseSignature` is signature-only and is not sufficient to accept a witness response on its own.
 
 ## Tests
 
@@ -76,12 +78,12 @@ npm run lint        # eslint
 npm run check:surface   # public-surface drift check
 ```
 
-For Nix users: `nix develop` gives a pinned Node 22 + git + gitleaks shell. `nix build` produces the publishable npm tarball under `result/`.
+For Nix users: `nix develop` gives a pinned Node 22 + git + gitleaks shell. `nix build` produces the publishable npm tarball under `result/`. `nix run github:Ad-Astra-Computing/ink -- verify-inclusion --file receipt.json --witness https://witness.example.com` runs the CLI without installing anything globally.
 
 ## Layout
 
 ```
-src/           reference implementation
+src/           library implementation
   crypto/      signing, multi-key verification, key encoding
   models/      Zod schemas for Agent Card, handshake, key entries
   middleware/  transport-level INK auth (verifyInkAuth)
@@ -93,7 +95,7 @@ test-vectors/  JSON interop vectors
 test/          vitest unit + integration tests
 ```
 
-The reference implementation runs on any runtime providing standard Web Crypto and `fetch`: Node 22+, Deno, Bun, Cloudflare Workers, browsers. The timestamp freshness window is enforced inside `verifyInkAuth`; nonce single-use is enforced when a `NonceStore` is passed (otherwise `checkReplay` must be called separately). Nonce backing storage and its TTL policy are the integrator's choice.
+The library runs on any runtime providing standard Web Crypto and `fetch`: Node 22+, Deno, Bun, Cloudflare Workers, browsers. The timestamp freshness window is enforced inside `verifyInkAuth`; nonce single-use is enforced when a `NonceStore` is passed (otherwise `checkReplay` must be called separately). Nonce backing storage and its TTL policy are the integrator's choice.
 
 ## What's stable in v0.1
 
@@ -117,7 +119,7 @@ You will see `network.tulpa.*` on the wire (e.g. `network.tulpa.intent`) and `in
 
 ## Relationship to Tulpa
 
-INK is developed by [Ad Astra Computing](https://adastracomputing.com) as the underlying protocol for [Tulpa](https://tulpa.network). The spec and the reference implementation in this repo are deliberately free of Tulpa product code so other agent platforms can adopt INK without inheriting Tulpa's surface area. Tulpa's product integration (message orchestration, marketplace, user-facing APIs) lives in a separate, closed-source codebase.
+INK is developed by [Ad Astra Computing](https://adastracomputing.com) as the underlying protocol for [Tulpa](https://tulpa.network). The spec and the library in this repo are deliberately free of Tulpa product code so other agent platforms can adopt INK without inheriting Tulpa's surface area. Tulpa's product integration (message orchestration, marketplace, user-facing APIs) lives in a separate, closed-source codebase.
 
 ## Security
 

package/SECURITY.md

@@ -39,7 +39,7 @@ In scope:
 
 Out of scope:
 
-- DoS via high-entropy inputs against the reference implementation
+- DoS via high-entropy inputs against the library
 - Attacks that require a compromised identity system (e.g., a malicious PDS returning a fabricated DID document)
 - Timing side-channels in the reference `@noble/ed25519` verification
 - Attacks on Tulpa's product infrastructure (separate codebase, separate disclosure process)

package/bin/ink.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * `ink` CLI dispatcher. Subcommands:
+ *   verify-inclusion   verify an INK inclusion receipt against a witness
+ *
+ * Usage:
+ *   npx @adastracomputing/ink verify-inclusion --file receipt.json --witness https://witness.tulpa.network
+ *
+ * Resolves npm's bin invocation pattern: with a single bin named `ink`
+ * matching the package's unscoped slug, `npx @adastracomputing/ink ...`
+ * routes all args to this dispatcher.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const SUBCOMMANDS = {
+  "verify-inclusion": "verify-inclusion-impl.mjs",
+};
+
+function printHelp() {
+  console.log(`ink: INK protocol command-line interface.
+
+Subcommands:
+  verify-inclusion   Verify an INK inclusion receipt against a witness.
+
+Run a subcommand with --help for details, e.g.:
+  npx @adastracomputing/ink verify-inclusion --help
+`);
+}
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+
+if (!sub || sub === "--help" || sub === "-h") {
+  printHelp();
+  process.exit(sub ? 0 : 2);
+}
+
+const impl = SUBCOMMANDS[sub];
+if (!impl) {
+  console.error(`Unknown subcommand: ${sub}`);
+  printHelp();
+  process.exit(2);
+}
+
+// Re-route remaining args to the subcommand implementation. The impl
+// reads from process.argv directly, so rewrite it before importing.
+process.argv = [process.argv[0], join(here, impl), ...argv.slice(1)];
+await import(`./${impl}`);

package/bin/verify-inclusion-impl.mjs

@@ -0,0 +1,483 @@
+#!/usr/bin/env node
+/**
+ * CLI: verify an INK inclusion receipt against a witness's published
+ * identity and current checkpoint. Self-contained ESM module so the
+ * shebang resolves on any Node 22+ install without a TS toolchain.
+ *
+ * Usage:
+ *
+ *   # Receipt on stdin
+ *   cat receipt.json | npx @adastracomputing/ink verify-inclusion \
+ *     --witness https://witness.tulpa.network
+ *
+ *   # Receipt from file
+ *   npx @adastracomputing/ink verify-inclusion \
+ *     --file receipt.json \
+ *     --witness https://witness.tulpa.network
+ *
+ *   # Also walk the inclusion proof
+ *   npx @adastracomputing/ink verify-inclusion \
+ *     --file receipt.json \
+ *     --witness https://witness.tulpa.network \
+ *     --event-hash 8a3c...
+ *
+ * Exit codes:
+ *   0  receipt is valid
+ *   1  receipt is invalid (a step failed)
+ *   2  usage / network / parsing error
+ */
+import { readFileSync, statSync } from "node:fs";
+import * as ed from "@noble/ed25519";
+import canonicalize from "canonicalize";
+
+// ── arg parsing ──
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--file" || a === "-f") out.file = argv[++i];
+    else if (a === "--witness" || a === "-w") out.witness = argv[++i];
+    else if (a === "--event-hash" || a === "-e") out.eventHash = argv[++i];
+    else if (a === "--allow-http") out.allowHttp = true;
+    else if (a === "--help" || a === "-h") out.help = true;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      process.exit(2);
+    }
+  }
+  return out;
+}
+
+/**
+ * Validate and normalize the --witness URL. Rejects unparseable URLs,
+ * schemes other than https (or http with --allow-http), and URLs that
+ * carry credentials. Returns scheme://host[:port] with no path.
+ */
+function validateWitnessUrl(raw, allowHttp) {
+  let u;
+  try { u = new URL(raw); }
+  catch { throw new Error(`--witness is not a valid URL: ${raw}`); }
+  if (u.username || u.password) throw new Error("--witness URL must not contain credentials");
+  if (u.protocol === "https:") return `${u.protocol}//${u.host}`;
+  if (u.protocol === "http:") {
+    if (!allowHttp) throw new Error("--witness URL must use https:// (pass --allow-http for plain http)");
+    return `${u.protocol}//${u.host}`;
+  }
+  throw new Error(`--witness URL scheme must be https:// or http://, got ${u.protocol}`);
+}
+
+function printHelp() {
+  console.log(`verify-inclusion: verify an INK inclusion receipt.
+
+Usage:
+  verify-inclusion --witness <url> [--file <receipt.json>] [--event-hash <hex>]
+
+Options:
+  -w, --witness <url>      Witness base URL (e.g. https://witness.tulpa.network)
+  -f, --file <path>        Receipt JSON file. Omit to read from stdin.
+  -e, --event-hash <hex>   Optional. RFC 6962 leaf hash for the audit event:
+                            SHA-256(0x00 || JCS(event-without-agentSignature)),
+                            hex-encoded. When set, the inclusion proof is
+                            re-walked from this leaf up to the claimed root.
+  -h, --help               Show this help.
+
+Exit codes:
+  0  receipt valid
+  1  receipt invalid
+  2  usage or network error
+`);
+}
+
+// ── encoding helpers (mirror src/crypto/ink.ts) ──
+
+function base64urlDecode(s) {
+  const padded = s.replace(/-/g, "+").replace(/_/g, "/") + "==".slice(0, (4 - (s.length % 4)) % 4);
+  const bin = Buffer.from(padded, "base64");
+  return new Uint8Array(bin.buffer, bin.byteOffset, bin.byteLength);
+}
+
+function hexToBytes(hex) {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    out[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+  }
+  return out;
+}
+
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// ── multibase Ed25519 key decode (z-prefix, base58btc, 0xed 0x01 multicodec) ──
+
+const BASE58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function decodePublicKeyMultibase(mb) {
+  if (typeof mb !== "string" || mb.length === 0 || mb[0] !== "z") {
+    throw new Error("publicKeyMultibase must start with 'z' (base58btc)");
+  }
+  const body = mb.slice(1);
+  let num = 0n;
+  for (const ch of body) {
+    const idx = BASE58.indexOf(ch);
+    if (idx < 0) throw new Error(`invalid base58btc char: ${ch}`);
+    num = num * 58n + BigInt(idx);
+  }
+  const bytes = [];
+  while (num > 0n) {
+    bytes.unshift(Number(num & 0xffn));
+    num >>= 8n;
+  }
+  for (const ch of body) {
+    if (ch !== "1") break;
+    bytes.unshift(0);
+  }
+  if (bytes.length < 2 || bytes[0] !== 0xed || bytes[1] !== 0x01) {
+    throw new Error("multibase key missing Ed25519 multicodec prefix (0xed 0x01)");
+  }
+  return new Uint8Array(bytes.slice(2));
+}
+
+// ── Merkle inclusion-proof walker (RFC 6962-derived) ──
+
+async function hashPair(left, right) {
+  const l = hexToBytes(left);
+  const r = hexToBytes(right);
+  const buf = new Uint8Array(1 + l.length + r.length);
+  buf[0] = 0x01;
+  buf.set(l, 1);
+  buf.set(r, 1 + l.length);
+  const out = new Uint8Array(await crypto.subtle.digest("SHA-256", buf));
+  return bytesToHex(out);
+}
+
+function largestPowerOf2LessThan(n) {
+  if (n <= 1) return 0;
+  let p = 1;
+  while (p * 2 < n) p *= 2;
+  return p;
+}
+
+async function recomputeRoot(currentHash, proof, proofIdx, leafIndex, start, size) {
+  if (size === 1) {
+    if (proofIdx !== proof.length) throw new Error("inclusion proof has unused entries");
+    return currentHash;
+  }
+  if (proofIdx >= proof.length) {
+    throw new Error("inclusion proof too short for declared treeSize");
+  }
+  const split = largestPowerOf2LessThan(size);
+  if (leafIndex - start < split) {
+    const leftResult = await recomputeRoot(currentHash, proof, proofIdx + 1, leafIndex, start, split);
+    return hashPair(leftResult, proof[proofIdx]);
+  }
+  const rightResult = await recomputeRoot(currentHash, proof, proofIdx + 1, leafIndex, start + split, size - split);
+  return hashPair(proof[proofIdx], rightResult);
+}
+
+// ── core verifier ──
+
+const MAX_PROOF_LENGTH = 64;
+const MAX_RECEIPT_BYTES = 64 * 1024;
+
+function checkCheckpointShape(cp) {
+  if (cp === null || typeof cp !== "object") return "laterCheckpoint must be an object";
+  if (!Number.isInteger(cp.treeSize) || cp.treeSize < 0) return "laterCheckpoint.treeSize must be a non-negative integer";
+  if (typeof cp.rootHash !== "string" || !/^[0-9a-f]{64}$/.test(cp.rootHash)) {
+    return "laterCheckpoint.rootHash must be 64 lowercase hex chars";
+  }
+  return null;
+}
+
+function checkReceiptShape(r) {
+  if (r === null || typeof r !== "object") return "receipt is not an object";
+  if (typeof r.eventId !== "string" || r.eventId.length === 0) return "eventId missing";
+  if (!Number.isInteger(r.leafIndex) || r.leafIndex < 0) return "leafIndex must be non-negative integer";
+  if (!Number.isInteger(r.treeSize) || r.treeSize < 1) return "treeSize must be positive integer";
+  if (r.leafIndex >= r.treeSize) return "leafIndex must be < treeSize";
+  if (typeof r.rootHash !== "string" || !/^[0-9a-f]{64}$/.test(r.rootHash)) return "rootHash must be 64 lowercase hex chars";
+  if (!Array.isArray(r.inclusionProof)) return "inclusionProof must be an array";
+  if (r.inclusionProof.length > MAX_PROOF_LENGTH) return `inclusionProof exceeds max length of ${MAX_PROOF_LENGTH} entries`;
+  for (const p of r.inclusionProof) {
+    if (typeof p !== "string" || !/^[0-9a-f]{64}$/.test(p)) return "every inclusionProof entry must be 64 lowercase hex chars";
+  }
+  if (typeof r.timestamp !== "string" || r.timestamp.length === 0) return "timestamp missing";
+  if (typeof r.serviceSignature !== "string" || r.serviceSignature.length === 0) return "serviceSignature missing";
+  return null;
+}
+
+async function verifyReceipt(receipt, witnessPublicKey, eventHash, laterCheckpoint) {
+  const steps = [];
+  const structuralProblem = checkReceiptShape(receipt);
+  if (structuralProblem) {
+    steps.push({ name: "structure", pass: false, detail: structuralProblem });
+    return { valid: false, steps };
+  }
+  steps.push({ name: "structure", pass: true });
+
+  const signedPayload = {
+    eventId: receipt.eventId,
+    leafIndex: receipt.leafIndex,
+    treeSize: receipt.treeSize,
+    rootHash: receipt.rootHash,
+    timestamp: receipt.timestamp,
+  };
+  const sigBase = `ink/audit-inclusion/v1\n${canonicalize(signedPayload)}`;
+  let sigValid = false;
+  try {
+    const sig = base64urlDecode(receipt.serviceSignature);
+    sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey);
+  } catch (e) {
+    steps.push({ name: "signature", pass: false, detail: e instanceof Error ? e.message : "signature decode failed" });
+    return { valid: false, steps };
+  }
+  if (!sigValid) {
+    steps.push({ name: "signature", pass: false, detail: "Ed25519 verification failed" });
+    return { valid: false, steps };
+  }
+  steps.push({ name: "signature", pass: true });
+
+  if (eventHash !== undefined) {
+    if (!/^[0-9a-f]{64}$/.test(eventHash)) {
+      steps.push({ name: "proof", pass: false, detail: "eventHash must be 64 lowercase hex chars" });
+      return { valid: false, steps };
+    }
+    let computed;
+    try {
+      computed = await recomputeRoot(eventHash, receipt.inclusionProof, 0, receipt.leafIndex, 0, receipt.treeSize);
+    } catch (e) {
+      steps.push({ name: "proof", pass: false, detail: e instanceof Error ? e.message : "proof walk failed" });
+      return { valid: false, steps };
+    }
+    if (computed !== receipt.rootHash) {
+      steps.push({ name: "proof", pass: false, detail: "leaf-to-root walk did not reach claimed rootHash" });
+      return { valid: false, steps };
+    }
+    steps.push({ name: "proof", pass: true });
+  }
+
+  if (laterCheckpoint !== undefined) {
+    const cpShape = checkCheckpointShape(laterCheckpoint);
+    if (cpShape) {
+      steps.push({ name: "checkpoint", pass: false, detail: cpShape });
+      return { valid: false, steps };
+    }
+    if (laterCheckpoint.treeSize < receipt.treeSize) {
+      steps.push({
+        name: "checkpoint",
+        pass: false,
+        detail: `checkpoint treeSize ${laterCheckpoint.treeSize} < receipt treeSize ${receipt.treeSize} (witness rewound the tree)`,
+      });
+      return { valid: false, steps };
+    }
+    if (laterCheckpoint.treeSize === receipt.treeSize && laterCheckpoint.rootHash !== receipt.rootHash) {
+      steps.push({
+        name: "checkpoint",
+        pass: false,
+        detail: "checkpoint rootHash differs from receipt rootHash at same treeSize (fork)",
+      });
+      return { valid: false, steps };
+    }
+    steps.push({ name: "checkpoint", pass: true });
+  }
+
+  return { valid: true, steps };
+}
+
+// ── witness HTTP helpers ──
+
+/** Hard caps to prevent a malicious or compromised --witness URL
+ *  from forcing unbounded memory growth via a streamed response. */
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * Fetch with byte cap and abort timeout. Aborts the response stream
+ * mid-read if it exceeds the cap so we never allocate beyond it.
+ * Returns the decoded UTF-8 text.
+ */
+async function fetchBounded(url) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(new Error("fetch timed out")), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal });
+    if (!res.ok) throw new Error(`fetch failed (${res.status}): ${url}`);
+    if (!res.body) return "";
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value) {
+          total += value.byteLength;
+          if (total > MAX_RESPONSE_BYTES) {
+            try { await reader.cancel(); } catch { /* ignore */ }
+            throw new Error(`response exceeds ${MAX_RESPONSE_BYTES} bytes`);
+          }
+          chunks.push(value);
+        }
+      }
+    } finally {
+      try { reader.releaseLock(); } catch { /* ignore */ }
+    }
+    const merged = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) { merged.set(c, off); off += c.byteLength; }
+    return new TextDecoder().decode(merged);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchWitnessPublicKey(witnessUrl) {
+  const url = `${witnessUrl.replace(/\/$/, "")}/.well-known/did.json`;
+  const body = await fetchBounded(url);
+  let doc;
+  try { doc = JSON.parse(body); }
+  catch { throw new Error(`DID document is not valid JSON: ${url}`); }
+  const vm = doc?.verificationMethod?.[0]?.publicKeyMultibase;
+  if (typeof vm !== "string") throw new Error("DID document missing verificationMethod[0].publicKeyMultibase");
+  return decodePublicKeyMultibase(vm);
+}
+
+/**
+ * Parse a C2SP tlog-checkpoint response. The body has three header
+ * lines (origin, treeSize, rootHash), each terminated by \n, then a
+ * blank line, then a signature line. We don't verify the signature
+ * here (it'd require pre-fetching the witness key, which the caller
+ * already does for the receipt). Just extract the header fields with
+ * strict regexes so a malformed checkpoint can't fake-pass.
+ */
+function parseCheckpointBody(body) {
+  const sepIdx = body.indexOf("\n\n");
+  if (sepIdx < 0) return null;
+  const header = body.slice(0, sepIdx);
+  const lines = header.split("\n");
+  if (lines.length !== 3) return null;
+  if (!lines[0]) return null;
+  if (!/^\d+$/.test(lines[1])) return null;
+  const treeSize = parseInt(lines[1], 10);
+  if (!Number.isInteger(treeSize) || treeSize < 0 || treeSize > Number.MAX_SAFE_INTEGER) return null;
+  if (!/^[0-9a-f]{64}$/.test(lines[2])) return null;
+  return { treeSize, rootHash: lines[2] };
+}
+
+async function fetchCurrentCheckpoint(witnessUrl) {
+  const url = `${witnessUrl.replace(/\/$/, "")}/ink/v1/checkpoint`;
+  let body;
+  try {
+    body = await fetchBounded(url);
+  } catch {
+    // Checkpoint cross-check is optional; downgrade fetch failures to
+    // 'not available' rather than crashing the verifier.
+    return null;
+  }
+  return parseCheckpointBody(body);
+}
+
+async function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+      if (data.length > MAX_RECEIPT_BYTES) {
+        reject(new Error(`receipt input exceeds ${MAX_RECEIPT_BYTES} bytes`));
+        process.stdin.destroy();
+      }
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", reject);
+  });
+}
+
+// ── main ──
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+  if (!args.witness) {
+    console.error("Error: --witness <url> is required.");
+    printHelp();
+    process.exit(2);
+  }
+
+  let witnessBase;
+  try {
+    witnessBase = validateWitnessUrl(args.witness, args.allowHttp);
+  } catch (e) {
+    console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(2);
+  }
+
+  let raw;
+  try {
+    if (args.file) {
+      // Stat first so a multi-GB file is rejected before allocation.
+      const st = statSync(args.file);
+      if (st.size > MAX_RECEIPT_BYTES) {
+        throw new Error(`receipt file exceeds ${MAX_RECEIPT_BYTES} bytes (${st.size} on disk)`);
+      }
+      raw = readFileSync(args.file, "utf8");
+    } else {
+      raw = await readStdin();
+    }
+    if (raw.length > MAX_RECEIPT_BYTES) {
+      throw new Error(`receipt exceeds ${MAX_RECEIPT_BYTES} bytes after decode`);
+    }
+  } catch (e) {
+    console.error(`Error reading receipt: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(2);
+  }
+
+  let receipt;
+  try {
+    receipt = JSON.parse(raw);
+  } catch (e) {
+    console.error(`Error parsing receipt JSON: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(2);
+  }
+
+  let witnessPublicKey;
+  try {
+    witnessPublicKey = await fetchWitnessPublicKey(witnessBase);
+  } catch (e) {
+    console.error(`Error fetching witness identity: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(2);
+  }
+
+  const laterCheckpoint = await fetchCurrentCheckpoint(witnessBase);
+
+  const result = await verifyReceipt(receipt, witnessPublicKey, args.eventHash, laterCheckpoint ?? undefined);
+
+  console.log(`Receipt: eventId=${receipt?.eventId} leafIndex=${receipt?.leafIndex} treeSize=${receipt?.treeSize}`);
+  console.log(`Witness: ${witnessBase}`);
+  if (laterCheckpoint) {
+    console.log(`Current checkpoint: treeSize=${laterCheckpoint.treeSize} rootHash=${laterCheckpoint.rootHash}`);
+  } else {
+    console.log("Current checkpoint: not available (skipping checkpoint cross-check)");
+  }
+  console.log("");
+  for (const step of result.steps) {
+    const mark = step.pass ? "PASS" : "FAIL";
+    console.log(`  [${mark}] ${step.name}${step.detail ? ": " + step.detail : ""}`);
+  }
+  console.log("");
+  if (result.valid) {
+    console.log("RECEIPT VALID");
+    process.exit(0);
+  } else {
+    console.log("RECEIPT INVALID");
+    process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  console.error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+  process.exit(2);
+});