@adastracomputing/ink 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.
 
+## 0.5.0, transparency-log consistency proofs
+
+This release adds RFC 6962 consistency-proof verification, so a verifier can
+confirm a transparency log only ever appended to its tree between two
+checkpoints rather than forking its history. The size comparison alone cannot
+detect a split view. It is published on the `next` dist-tag; this release is
+additive, with no breaking changes.
+
+### Additions
+
+- `verifyConsistencyProof(first, firstRoot, second, secondRoot, proof)` verifies
+  an RFC 6962 Section 2.1.2 consistency proof: that the tree of `first` leaves is
+  an append-only prefix of the tree of `second` leaves. It returns false (never
+  throws) for any malformed input or any proof that does not reconstruct both
+  roots with every node consumed.
+- The `verify-inclusion` CLI uses it: when `--origin` enables the checkpoint
+  cross-check and the signature-verified checkpoint is newer than the receipt's
+  tree, the CLI fetches a consistency proof and verifies the receipt's tree is an
+  append-only prefix of the checkpoint. A witness that serves no proof has the
+  step reported as skipped, not passed.
+
+The reference witness serves these proofs at `GET /ink/v1/consistency?first=N&second=M`.
+
 ## 0.4.0, stricter verification, message-size bounds, checkpoint and receipt verification
 
 This release tightens signature verification and input validation and adds

package/README.md

@@ -105,6 +105,10 @@ Verification helpers added in `0.4.0`:
 - `verifyInclusionReceipt` accepts an `event` option that recomputes the leaf hash and binds `event.id` to `receipt.eventId`, so the proof attests the named event's inclusion. Prefer it over the legacy unbound `eventHash`.
 - `verifyInkAuth` returns a prefix-independent `principal` alongside the raw `senderAgentId`. Per-sender security state (block lists, rate limits) MUST key on `principal`, because the `tulpa:` and `ink:` spellings of one key are the same actor; `canonicalAgentPrincipal(agentId)` exposes the same mapping.
 
+Added in `0.5.0`:
+
+- `verifyConsistencyProof(first, firstRoot, second, secondRoot, proof)` verifies an RFC 6962 consistency proof that the tree of `first` leaves is an append-only prefix of the tree of `second` leaves, so a witness that forks its history rather than only appending is detected. The witness serves these proofs at `GET /ink/v1/consistency?first=N&second=M`, and the `verify-inclusion` CLI checks one against the current checkpoint when `--origin` is passed.
+
 ## Agent-assisted implementation
 
 If you are asking an AI coding agent to add INK support to an existing service, the canonical packet for that workflow is the [Agent-assisted implementation](https://ink.tulpa.network/guides/agent-assisted-implementation/) guide. It contains the curated implementer prompt, a mandatory traceability matrix, the conformance checklist, and a human-review checklist. The guide is updated as the protocol evolves; treat it as the live source rather than copying its contents into your repo.

package/bin/verify-inclusion-impl.mjs

@@ -77,9 +77,16 @@ Usage:
 Options:
   -w, --witness <url>      Witness base URL (e.g. https://witness.tulpa.network)
       --origin <name>      Optional. Expected checkpoint origin (log identity)
-                            to bind the signed checkpoint to. When omitted, the
-                            checkpoint signature is still verified against the
-                            witness key and the body/signature origins must agree.
+                            to bind the signed checkpoint to. Enables the
+                            checkpoint cross-check: the current checkpoint's
+                            signature is verified against the witness key, and
+                            when it is newer than the receipt and the witness
+                            serves an RFC 6962 consistency proof, that proof is
+                            verified so a forked history is caught. If the witness
+                            serves no proof the consistency step is reported as
+                            skipped, not passed. When --origin is omitted the
+                            cross-check is skipped rather than trusting an
+                            unverified checkpoint body.
   -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)),
@@ -180,6 +187,47 @@ async function recomputeRoot(currentHash, proof, proofIdx, leafIndex, start, siz
   return hashPair(proof[proofIdx], rightResult);
 }
 
+const EMPTY_TREE_ROOT = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+/**
+ * Verify an RFC 6962 Section 2.1.2 consistency proof (the first-sized tree is a
+ * prefix of the second). Mirrors verifyConsistencyProof() in
+ * src/audit/inclusion-receipt.ts — keep them in sync.
+ */
+async function verifyConsistencyProofCli(first, firstRoot, second, secondRoot, proof) {
+  const isHash = (s) => typeof s === "string" && /^[0-9a-f]{64}$/.test(s);
+  if (!Number.isSafeInteger(first) || !Number.isSafeInteger(second)) return false;
+  if (first < 0 || second < 0) return false;
+  if (!isHash(firstRoot) || !isHash(secondRoot)) return false;
+  if (!Array.isArray(proof) || !proof.every(isHash) || proof.length > 64) return false;
+  if (first > second) return false;
+  if (first === second) return proof.length === 0 && firstRoot === secondRoot;
+  if (first === 0) return proof.length === 0 && firstRoot === EMPTY_TREE_ROOT;
+
+  let node = first - 1;
+  let last = second - 1;
+  while (node % 2 === 1) { node = Math.floor(node / 2); last = Math.floor(last / 2); }
+  let i = 0;
+  const take = () => (i < proof.length ? proof[i++] : null);
+  let oldHash;
+  if (node > 0) { const h = take(); if (h === null) return false; oldHash = h; } else { oldHash = firstRoot; }
+  let newHash = oldHash;
+  while (node > 0) {
+    if (node % 2 === 1) {
+      const h = take(); if (h === null) return false;
+      oldHash = await hashPair(h, oldHash);
+      newHash = await hashPair(h, newHash);
+    } else if (node < last) {
+      const h = take(); if (h === null) return false;
+      newHash = await hashPair(newHash, h);
+    }
+    node = Math.floor(node / 2); last = Math.floor(last / 2);
+  }
+  while (last > 0) { const h = take(); if (h === null) return false; newHash = await hashPair(newHash, h); last = Math.floor(last / 2); }
+  if (i !== proof.length) return false;
+  return oldHash === firstRoot && newHash === secondRoot;
+}
+
 // ── core verifier ──
 
 const MAX_PROOF_LENGTH = 64;
@@ -414,6 +462,26 @@ async function fetchCurrentCheckpoint(witnessUrl, witnessPublicKey, expectedOrig
   return verifyCheckpointBody(body, witnessPublicKey, expectedOrigin);
 }
 
+async function fetchConsistencyProof(witnessUrl, first, second) {
+  const url = `${witnessUrl.replace(/\/$/, "")}/ink/v1/consistency?first=${first}&second=${second}`;
+  let body;
+  try {
+    body = await fetchBounded(url);
+  } catch {
+    // A witness that does not serve consistency proofs downgrades the check to
+    // 'not available' rather than failing the receipt.
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (!parsed || !Array.isArray(parsed.proof)) return null;
+  return parsed.proof;
+}
+
 async function readStdin() {
   return new Promise((resolve, reject) => {
     let data = "";
@@ -496,6 +564,43 @@ async function main() {
 
   const result = await verifyReceipt(receipt, witnessPublicKey, args.eventHash, laterCheckpoint ?? undefined);
 
+  // Append-only proof: when the signature-verified checkpoint is strictly newer
+  // than the receipt's tree, fetch and verify an RFC 6962 consistency proof, so
+  // a witness that forked its history between the two snapshots is caught. The
+  // checkpoint size comparison alone cannot detect a same-prefix fork.
+  if (laterCheckpoint && Number.isInteger(receipt?.treeSize) && laterCheckpoint.treeSize > receipt.treeSize) {
+    const proof = await fetchConsistencyProof(witnessBase, receipt.treeSize, laterCheckpoint.treeSize);
+    if (proof === null) {
+      // Honest downgrade: the witness did not serve a usable consistency proof.
+      // Mark it skipped (NOT passed) so a witness that forked cannot look clean
+      // by withholding the endpoint; the checkpoint signature, rewind, and
+      // same-size fork checks still ran.
+      result.steps.push({
+        name: "consistency",
+        skip: true,
+        detail: "not checked (witness did not serve a consistency proof); append-only growth was not verified",
+      });
+    } else {
+      const consistent = await verifyConsistencyProofCli(
+        receipt.treeSize, receipt.rootHash, laterCheckpoint.treeSize, laterCheckpoint.rootHash, proof,
+      );
+      if (consistent) {
+        result.steps.push({
+          name: "consistency",
+          pass: true,
+          detail: `receipt tree (size ${receipt.treeSize}) is an append-only prefix of the checkpoint (size ${laterCheckpoint.treeSize})`,
+        });
+      } else {
+        result.steps.push({
+          name: "consistency",
+          pass: false,
+          detail: `receipt tree (size ${receipt.treeSize}) is NOT an append-only prefix of the checkpoint (size ${laterCheckpoint.treeSize}); the witness forked its history`,
+        });
+        result.valid = false;
+      }
+    }
+  }
+
   console.log(`Receipt: eventId=${receipt?.eventId} leafIndex=${receipt?.leafIndex} treeSize=${receipt?.treeSize}`);
   console.log(`Witness: ${witnessBase}`);
   if (laterCheckpoint) {
@@ -507,7 +612,7 @@ async function main() {
   }
   console.log("");
   for (const step of result.steps) {
-    const mark = step.pass ? "PASS" : "FAIL";
+    const mark = step.skip ? "SKIP" : step.pass ? "PASS" : "FAIL";
     console.log(`  [${mark}] ${step.name}${step.detail ? ": " + step.detail : ""}`);
   }
   console.log("");

package/dist/audit/inclusion-receipt.d.ts

@@ -150,3 +150,18 @@ export declare function verifyAuditQueryResponse(opts: {
      *  audit), they MUST explicitly pass a callback that does so. */
     verifyEventSignature: (event: Record<string, unknown>) => Promise<boolean>;
 }): Promise<AuditQueryResponseVerifyResult>;
+/**
+ * Verify an RFC 6962 Section 2.1.2 consistency proof: that the Merkle tree of
+ * `first` leaves with root `firstRoot` is a prefix of the tree of `second`
+ * leaves with root `secondRoot`. A valid proof is proof the log only ever
+ * appended; it is what detects a witness that forks its history (split view)
+ * rather than merely growing, which the `second >= first` size comparison
+ * alone cannot.
+ *
+ * `firstRoot`, `secondRoot` and every proof entry are 64 lowercase hex chars
+ * (SHA-256). Internal nodes are hashed as SHA-256(0x01 || left || right), the
+ * same construction the inclusion verifier uses, so the two agree on tree
+ * shape. Returns false (never throws) for any malformed input or any proof that
+ * does not reconstruct both roots with every element consumed.
+ */
+export declare function verifyConsistencyProof(first: number, firstRoot: string, second: number, secondRoot: string, proof: string[]): Promise<boolean>;

package/dist/audit/inclusion-receipt.js

@@ -518,3 +518,99 @@ async function verifyInclusionProof(leafHash, proof, leafIndex, treeSize, expect
         return false;
     }
 }
+function isMerkleHashHex(s) {
+    return typeof s === "string" && /^[0-9a-f]{64}$/.test(s);
+}
+/**
+ * Verify an RFC 6962 Section 2.1.2 consistency proof: that the Merkle tree of
+ * `first` leaves with root `firstRoot` is a prefix of the tree of `second`
+ * leaves with root `secondRoot`. A valid proof is proof the log only ever
+ * appended; it is what detects a witness that forks its history (split view)
+ * rather than merely growing, which the `second >= first` size comparison
+ * alone cannot.
+ *
+ * `firstRoot`, `secondRoot` and every proof entry are 64 lowercase hex chars
+ * (SHA-256). Internal nodes are hashed as SHA-256(0x01 || left || right), the
+ * same construction the inclusion verifier uses, so the two agree on tree
+ * shape. Returns false (never throws) for any malformed input or any proof that
+ * does not reconstruct both roots with every element consumed.
+ */
+export async function verifyConsistencyProof(first, firstRoot, second, secondRoot, proof) {
+    if (!Number.isSafeInteger(first) || !Number.isSafeInteger(second))
+        return false;
+    if (first < 0 || second < 0)
+        return false;
+    if (!isMerkleHashHex(firstRoot) || !isMerkleHashHex(secondRoot))
+        return false;
+    if (!Array.isArray(proof) || !proof.every(isMerkleHashHex))
+        return false;
+    // A consistency proof for a tree of `second` safe-integer leaves has at most
+    // ceil(log2(second)) + 1 nodes, comfortably under 64. Cap it so a hostile
+    // caller cannot force unbounded hashing work.
+    if (proof.length > 64)
+        return false;
+    if (first > second)
+        return false;
+    // Same size: the roots must match and there is nothing to prove.
+    if (first === second)
+        return proof.length === 0 && firstRoot === secondRoot;
+    // The empty tree is a prefix of every tree; its root is fixed and the proof
+    // carries no nodes.
+    if (first === 0)
+        return proof.length === 0 && firstRoot === EMPTY_TREE_ROOT;
+    // 0 < first < second. Walk the path from leaf `first - 1` up to the roots,
+    // shifting `node`/`last` together. `node` indexes the first tree's rightmost
+    // leaf, `last` the second tree's.
+    let node = first - 1;
+    let last = second - 1;
+    while (node % 2 === 1) {
+        node = Math.floor(node / 2);
+        last = Math.floor(last / 2);
+    }
+    let i = 0;
+    const take = () => (i < proof.length ? proof[i++] : null);
+    // When `first` is an exact power of two, `node` has shifted to 0 and the old
+    // subtree hash is `firstRoot` itself; otherwise it is the first proof node.
+    let oldHash;
+    if (node > 0) {
+        const h = take();
+        if (h === null)
+            return false;
+        oldHash = h;
+    }
+    else {
+        oldHash = firstRoot;
+    }
+    let newHash = oldHash;
+    while (node > 0) {
+        if (node % 2 === 1) {
+            // Right child: the sibling on the left is shared by both trees.
+            const h = take();
+            if (h === null)
+                return false;
+            oldHash = await hashPair(h, oldHash);
+            newHash = await hashPair(h, newHash);
+        }
+        else if (node < last) {
+            // Left child with a right sibling that exists only in the second tree.
+            const h = take();
+            if (h === null)
+                return false;
+            newHash = await hashPair(newHash, h);
+        }
+        node = Math.floor(node / 2);
+        last = Math.floor(last / 2);
+    }
+    // Remaining nodes extend only the second tree to its root.
+    while (last > 0) {
+        const h = take();
+        if (h === null)
+            return false;
+        newHash = await hashPair(newHash, h);
+        last = Math.floor(last / 2);
+    }
+    // Every proof element must be consumed, and both reconstructions must match.
+    if (i !== proof.length)
+        return false;
+    return oldHash === firstRoot && newHash === secondRoot;
+}

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { verifyInkSignatureWithKeys } from "./crypto/multi-key-verify.js";
 export { generateKeypair, generateEncryptionKeypair, deriveAgentId, encodePublicKeyMultibase, encodeEncryptionKeyMultibase, decodePublicKeyMultibase, decodeEncryptionKeyMultibase, extractPublicKeyFromAgentId, canonicalAgentPrincipal, AGENT_ID_KEY_PREFIXES, } from "./crypto/keys.js";
 export { fetchAgentCard, extractCandidateKeys, resolveBaseUrl, } from "./discovery/agent-card.js";
 export { verifyInkAuth, type NonceStore } from "./middleware/ink-auth.js";
-export { verifyInclusionReceipt, verifyAuditQueryResponse, type InclusionReceipt, type InclusionReceiptVerifyResult, type AuditQueryResponse, type AuditQueryResponseVerifyResult, type VerifyStep, } from "./audit/inclusion-receipt.js";
+export { verifyInclusionReceipt, verifyConsistencyProof, verifyAuditQueryResponse, type InclusionReceipt, type InclusionReceiptVerifyResult, type AuditQueryResponse, type AuditQueryResponseVerifyResult, type VerifyStep, } from "./audit/inclusion-receipt.js";
 export { HandshakeBudgetTracker } from "./ink/handshake-budget.js";
 export { buildReceipt, verifyReceipt, shouldSendReceipt, sendReceiptFireAndForget, } from "./ink/receipts.js";
 export { resolveEffectiveTransports, checkTransportAllowed, } from "./ink/transport-auth.js";

package/dist/index.js

@@ -10,7 +10,7 @@ export { fetchAgentCard, extractCandidateKeys, resolveBaseUrl, } from "./discove
 // Middleware: transport-level INK auth
 export { verifyInkAuth } from "./middleware/ink-auth.js";
 // Audit: inclusion-receipt + audit-query-response verification
-export { verifyInclusionReceipt, verifyAuditQueryResponse, } from "./audit/inclusion-receipt.js";
+export { verifyInclusionReceipt, verifyConsistencyProof, verifyAuditQueryResponse, } from "./audit/inclusion-receipt.js";
 // Optional containment / governance primitives
 export { HandshakeBudgetTracker } from "./ink/handshake-budget.js";
 // Receipts: build, verify, and send INK delivery receipts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adastracomputing/ink",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Library and specification for the INK (Inter-agent Networking Kernel) protocol",
   "license": "MIT OR Apache-2.0",
   "author": "Ad Astra Computing Inc.",