@adastracomputing/ink 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,81 @@ 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
+several verification helpers. It is published on the `next` dist-tag.
+
+### Potentially breaking validation tightenings
+
+These reject inputs that `0.3.0` accepted. Legitimate signer and receiver
+traffic is unaffected; the rejected inputs are malformed, malicious, or outside
+the documented profile.
+
+- Ed25519 signatures are now verified in strict RFC 8032 mode at every
+  verification site. Small-order public keys and non-canonical point encodings
+  are rejected.
+- Signed JSON numbers are constrained to the forms every canonicalizer
+  serializes identically: non-finite values, negative zero, and values whose
+  shortest form uses exponential notation are rejected at signing and
+  verification.
+- The agent card, audit, handshake, and discovery schemas now enforce maximum
+  field lengths and array sizes.
+- The `Authorization: INK-Ed25519` header is matched against single literal
+  spaces; a tab, carriage return, or line feed in the separator is rejected.
+
+### Additions
+
+- `verifyCheckpoint(signed, witnessPublicKey, expectedOrigin)` verifies a signed
+  C2SP checkpoint: the witness Ed25519 signature over the checkpoint body and the
+  log origin. A checkpoint used for the inclusion-receipt cross-check must be
+  verified this way first.
+- `verifyReceipt({ receipt, senderPublicKey, expected })` binds a delivery
+  receipt to the exact message it acknowledges: issuer key, `from`/`to`/
+  `messageId`, the recomputed message hash, and an optional `disposition`.
+- `verifyInclusionReceipt` accepts an `event` option that recomputes the leaf
+  hash and binds it to `receipt.eventId`. The legacy `eventHash` is retained but
+  does not provide that binding.
+- `verifyInkAuth` returns a prefix-independent `principal` alongside the raw
+  sender id; per-sender security state (blocks, rate limits) should key on
+  `principal`. `canonicalAgentPrincipal(agentId)` is exported for the same use.
+
+Per the pre-1.0 policy this release publishes under the `next` dist-tag; `latest`
+is unchanged.
+
+## 0.3.0, accept the ink: agentId alias for key extraction
+
+`extractPublicKeyFromAgentId` now accepts either the canonical `tulpa:` prefix or the `ink:` alias introduced in ink/0.4. Both carry the identical multibase Ed25519 key, so the bootstrap verification key is byte-identical and a signature made with that key verifies regardless of which accepted prefix carried it. The prefix is identity syntax, not signing authority.
+
+Emission is unchanged: `deriveAgentId` still returns `tulpa:` (accept both, emit one). The new `AGENT_ID_KEY_PREFIXES` export is frozen so a consumer cannot widen the accepted set at runtime. The change is additive and backward compatible. Existing `tulpa:` inputs behave exactly as before, and every previously rejected prefix other than `ink:` is still rejected. The wire protocol version is unchanged.
+
+A receiver that keys per-sender security state (blocks, rate limits, duplicate-payload checks, cached verification keys, connection identity) MUST collapse the two spellings to one prefix-independent principal so a sender cannot switch prefix to dodge a block or split a rate-limit window. See [Identity](https://ink.tulpa.network/spec/identity/).
+
+Per the pre-1.0 policy this release publishes under the `next` dist-tag.
+
 ## 0.2.0, version-keyed body-signature domain
 
 Version-keyed body-signature domain. The body message signature is now domain-separated by protocol version. ink/0.1 messages, and any object with no explicit ink/0.2 protocol, keep the legacy `tulpa/sign` domain so every signature produced to date still verifies. ink/0.2 messages are signed and verified under the neutral `ink/sign` domain. The verifier selects exactly one domain from the signed `protocol` field and never tries an alternate, so a signature made under one version's domain cannot be replayed under another.

package/README.md

@@ -98,6 +98,17 @@ For consumers of bilateral audit-exchange responses (`network.tulpa.audit_respon
 
 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.
 
+Verification helpers added in `0.4.0`:
+
+- `verifyCheckpoint(signed, witnessPublicKey, expectedOrigin)` verifies a signed C2SP checkpoint's witness Ed25519 signature and binds its log origin, returning the parsed `{origin, treeSize, rootHash}` or `null`. Any checkpoint passed to `verifyInclusionReceipt`'s `laterCheckpoint` cross-check must be verified this way first; an unverified checkpoint body is attacker-controllable and provides no anti-rollback value.
+- `verifyReceipt({receipt, senderPublicKey, expected})` verifies a delivery receipt against the message it acknowledges: the issuer's signature plus `from`/`to`/`messageId`, the recomputed message hash, and an optional `disposition`. It returns `{valid, reason?}`.
+- `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.
@@ -152,9 +163,11 @@ Subject to change before v1.0:
 
 You will see `network.tulpa.*` on the wire (e.g. `network.tulpa.intent`) and `ink.tulpa.network` for the docs site. Both are historical artifacts of the protocol's origin and do not imply a runtime dependency on Tulpa. A vendor-neutral namespace may be introduced in a future revision.
 
+As a first, non-breaking step in that direction, agentIds may use either the canonical `tulpa:` method prefix or the `ink:` alias; both encode the same Ed25519 key and denote the same actor. `deriveAgentId` still emits `tulpa:`, and `extractPublicKeyFromAgentId` accepts both (accept-both, emit-one). A receiver MUST collapse the two spellings to one prefix-independent principal for all per-sender security state (blocks, rate limits, duplicate-payload checks, cached keys, connection identity).
+
 ## 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 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.
+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 codebase.
 
 ## Interoperability
 

package/bin/verify-inclusion-impl.mjs

@@ -38,6 +38,7 @@ function parseArgs(argv) {
     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 === "--origin") out.origin = 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;
@@ -75,6 +76,17 @@ 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. 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)),
@@ -175,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;
@@ -226,7 +279,8 @@ async function verifyReceipt(receipt, witnessPublicKey, eventHash, laterCheckpoi
   let sigValid = false;
   try {
     const sig = base64urlDecode(receipt.serviceSignature);
-    sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey);
+    // RFC 8032 strict verification, matching the library (reject small-order keys).
+    sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey, { zip215: false });
   } catch (e) {
     steps.push({ name: "signature", pass: false, detail: e instanceof Error ? e.message : "signature decode failed" });
     return { valid: false, steps };
@@ -343,28 +397,59 @@ async function fetchWitnessPublicKey(witnessUrl) {
 }
 
 /**
- * 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.
+ * Verify a signed C2SP tlog-checkpoint and return { treeSize, rootHash,
+ * origin }, or null if the signature, origin, or format is invalid. The
+ * Ed25519 signature covers the body bytes `<origin>\n<treeSize>\n<rootHash>`
+ * (no trailing newline). The anti-rollback cross-check below only means
+ * anything against a checkpoint whose signature we have verified against the
+ * witness key, so this MUST verify, not just parse.
+ *
+ * Mirrors verifyCheckpoint() in src/ink/checkpoint.ts — keep them in sync.
  */
-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");
+async function verifyCheckpointBody(signed, witnessPublicKey, expectedOrigin) {
+  if (typeof signed !== "string" || signed.length === 0 || signed.length > 4096) return null;
+  const SEP = "\n\n-- ";
+  const idx = signed.indexOf(SEP);
+  if (idx < 0) return null;
+  const body = signed.slice(0, idx);
+  const lines = body.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);
+  const [origin, sizeLine, rootHash] = lines;
+  if (!origin || origin.length > 256) return null;
+  if (!/^\d+$/.test(sizeLine)) return null;
+  const treeSize = parseInt(sizeLine, 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] };
+  if (!/^[0-9a-f]{64}$/.test(rootHash)) return null;
+  // The expected origin must be supplied by the caller (a trusted value), not
+  // taken from the checkpoint body, so a witness key that signs several origins
+  // cannot substitute a checkpoint for a different log than the receipt's.
+  if (typeof expectedOrigin !== "string" || expectedOrigin.length === 0) return null;
+  if (origin !== expectedOrigin) return null;
+  const sigLines = signed.slice(idx + 2).split("\n").filter((l) => l.length > 0);
+  if (sigLines.length === 0 || sigLines.length > 8) return null;
+  const bodyBytes = new TextEncoder().encode(body);
+  for (const line of sigLines) {
+    if (!line.startsWith("-- ")) return null;
+    const rest = line.slice(3);
+    const sp = rest.indexOf(" ");
+    if (sp < 0) return null;
+    if (rest.slice(0, sp) !== expectedOrigin) continue;
+    try {
+      const sig = base64urlDecode(rest.slice(sp + 1));
+      if (sig.length !== 64) return null;
+      const ok = await ed.verifyAsync(sig, bodyBytes, witnessPublicKey, { zip215: false });
+      return ok ? { treeSize, rootHash, origin } : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
 }
 
-async function fetchCurrentCheckpoint(witnessUrl) {
+async function fetchCurrentCheckpoint(witnessUrl, witnessPublicKey, expectedOrigin) {
+  // No trusted origin, no cross-check: refuse to trust the checkpoint body's
+  // self-asserted origin. Pass --origin <witness-origin> to enable it.
+  if (typeof expectedOrigin !== "string" || expectedOrigin.length === 0) return null;
   const url = `${witnessUrl.replace(/\/$/, "")}/ink/v1/checkpoint`;
   let body;
   try {
@@ -374,7 +459,27 @@ async function fetchCurrentCheckpoint(witnessUrl) {
     // 'not available' rather than crashing the verifier.
     return null;
   }
-  return parseCheckpointBody(body);
+  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() {
@@ -451,20 +556,63 @@ async function main() {
     process.exit(2);
   }
 
-  const laterCheckpoint = await fetchCurrentCheckpoint(witnessBase);
+  // The checkpoint cross-check only carries weight against a checkpoint whose
+  // Ed25519 signature we have verified against the witness key. An unverified
+  // checkpoint (bad/absent signature, or origin mismatch) is dropped so the
+  // cross-check is skipped rather than trusting attacker-controlled values.
+  const laterCheckpoint = await fetchCurrentCheckpoint(witnessBase, witnessPublicKey, args.origin);
 
   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) {
-    console.log(`Current checkpoint: treeSize=${laterCheckpoint.treeSize} rootHash=${laterCheckpoint.rootHash}`);
+    console.log(`Current checkpoint (signature verified): treeSize=${laterCheckpoint.treeSize} rootHash=${laterCheckpoint.rootHash}`);
+  } else if (!args.origin) {
+    console.log("Current checkpoint: cross-check skipped (pass --origin <witness-origin> to enable the anti-rollback check)");
   } else {
-    console.log("Current checkpoint: not available (skipping checkpoint cross-check)");
+    console.log("Current checkpoint: not available or signature unverified (skipping checkpoint cross-check)");
   }
   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

@@ -26,21 +26,31 @@ export interface InclusionReceiptVerifyResult {
  *  - Service signature verification against `witnessPublicKey`
  *
  * Optionally performs (when the corresponding input is provided):
- *  - Leaf-to-root proof walk (`eventHash`)
+ *  - Leaf-to-root proof walk: pass `event` (recommended — recomputes the leaf
+ *    hash and binds it to `receipt.eventId`) or `eventHash` (legacy, unbound)
  *  - Cross-check against a later signed checkpoint (`laterCheckpoint`)
  */
 export declare function verifyInclusionReceipt(opts: {
     receipt: InclusionReceipt;
     /** Raw 32-byte Ed25519 public key of the witness service. */
     witnessPublicKey: Uint8Array;
-    /** Optional RFC 6962 leaf hash for the underlying audit event:
-     *  SHA-256(0x00 || JCS(event-without-agentSignature)), hex-encoded.
-     *  Use `computeAuditMerkleLeafHash` to derive it. When provided, the
-     *  inclusion proof is walked from this leaf up to the claimed rootHash. */
+    /** Optional audit event the receipt claims inclusion for. This is the
+     *  RECOMMENDED way to verify the proof: the leaf hash is recomputed from the
+     *  event with `computeAuditMerkleLeafHash`, and `event.id` is bound to
+     *  `receipt.eventId`, so the proof attests that the event named by the
+     *  receipt is in the tree — not merely that some caller-chosen hash is. */
+    event?: Record<string, unknown>;
+    /** Optional pre-computed RFC 6962 leaf hash (hex). LEGACY / lower-assurance:
+     *  unlike `event`, a bare hash is NOT bound to `receipt.eventId`, so the proof
+     *  only attests "this hash is in the tree", not "the event the receipt names
+     *  is in the tree". Prefer `event`. Ignored when `event` is provided. */
     eventHash?: string;
-    /** Optional later checkpoint to cross-check the receipt against.
-     *  Must come from a `/ink/v1/checkpoint` response that the verifier
-     *  has separately validated as authentic. */
+    /** Optional later checkpoint to cross-check the receipt against. This MUST be
+     *  the parsed body of a checkpoint whose Ed25519 signature and origin the
+     *  caller has already verified with `verifyCheckpoint` against the witness
+     *  key. Passing an unverified (merely parsed) checkpoint gives the
+     *  anti-rollback / fork cross-check no security, because the treeSize and
+     *  rootHash would then be attacker-controllable. */
     laterCheckpoint?: {
         treeSize: number;
         rootHash: string;
@@ -140,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

@@ -30,12 +30,13 @@ import { base64urlDecode, jcsCanonicalize, hexToBytes, bytesToHex, computeAuditM
  *  - Service signature verification against `witnessPublicKey`
  *
  * Optionally performs (when the corresponding input is provided):
- *  - Leaf-to-root proof walk (`eventHash`)
+ *  - Leaf-to-root proof walk: pass `event` (recommended — recomputes the leaf
+ *    hash and binds it to `receipt.eventId`) or `eventHash` (legacy, unbound)
  *  - Cross-check against a later signed checkpoint (`laterCheckpoint`)
  */
 export async function verifyInclusionReceipt(opts) {
     const steps = [];
-    const { receipt, witnessPublicKey, eventHash, laterCheckpoint } = opts;
+    const { receipt, witnessPublicKey, event, eventHash, laterCheckpoint } = opts;
     // ── Step 1: structural validation ──
     const structuralProblem = checkReceiptShape(receipt);
     if (structuralProblem) {
@@ -55,7 +56,7 @@ export async function verifyInclusionReceipt(opts) {
     let sigValid = false;
     try {
         const sig = base64urlDecode(receipt.serviceSignature);
-        sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey);
+        sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey, { zip215: false });
     }
     catch (e) {
         steps.push({
@@ -71,12 +72,35 @@ export async function verifyInclusionReceipt(opts) {
     }
     steps.push({ name: "signature", pass: true });
     // ── Step 3: inclusion-proof walk (optional) ──
-    if (eventHash !== undefined) {
+    // Prefer the `event` path: recompute the leaf hash from the event and bind it
+    // to receipt.eventId, so the proof attests the named event's inclusion.
+    let leafHash;
+    if (event !== undefined) {
+        if (typeof event.id !== "string") {
+            steps.push({ name: "proof", pass: false, detail: "event.id is missing or not a string" });
+            return { valid: false, steps };
+        }
+        if (event.id !== receipt.eventId) {
+            steps.push({ name: "proof", pass: false, detail: "event.id does not match receipt.eventId" });
+            return { valid: false, steps };
+        }
+        try {
+            leafHash = await computeAuditMerkleLeafHash(event);
+        }
+        catch {
+            steps.push({ name: "proof", pass: false, detail: "could not compute leaf hash from event" });
+            return { valid: false, steps };
+        }
+    }
+    else 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 };
         }
-        const verified = await verifyInclusionProof(eventHash, receipt.inclusionProof, receipt.leafIndex, receipt.treeSize, receipt.rootHash);
+        leafHash = eventHash;
+    }
+    if (leafHash !== undefined) {
+        const verified = await verifyInclusionProof(leafHash, receipt.inclusionProof, receipt.leafIndex, receipt.treeSize, receipt.rootHash);
         if (!verified) {
             steps.push({ name: "proof", pass: false, detail: "leaf-to-root walk did not reach claimed rootHash" });
             return { valid: false, steps };
@@ -494,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/crypto/ink.js

@@ -1,6 +1,7 @@
 import * as ed from "@noble/ed25519";
 import { x25519 } from "@noble/curves/ed25519.js";
 import canonicalize from "canonicalize";
+import { isJcsSafeNumber } from "./sign.js";
 // ── Encoding helpers ──
 const MAX_ENCODE_INPUT_BYTES = 2_000_000;
 function base64urlEncode(bytes) {
@@ -137,6 +138,11 @@ function isWithinCanonicalizeBounds(value) {
                 if (chars > MAX_PRECHECK_CHARS)
                     return false;
             }
+            else if (typeof v === "number" && !isJcsSafeNumber(v)) {
+                // Reject numbers that don't canonicalize identically across JSON
+                // serializers (non-finite, -0, exponential notation). See sign.ts.
+                return false;
+            }
             return true;
         }
         if (Array.isArray(v)) {
@@ -236,7 +242,9 @@ export async function verifyInkSignature(input, signatureBase64url, publicKey) {
     const bytes = new TextEncoder().encode(sigBase);
     try {
         const sig = base64urlDecode(signatureBase64url);
-        return await ed.verifyAsync(sig, bytes, publicKey);
+        // RFC 8032 strict verification (not the default ZIP-215): reject
+        // small-order keys and non-canonical encodings. See verifyMessage.
+        return await ed.verifyAsync(sig, bytes, publicKey, { zip215: false });
     }
     catch {
         return false;
@@ -629,7 +637,7 @@ export async function verifyAuditEventSignature(event, publicKey) {
         if (bytes.length > MAX_SIGBASE_BODY_BYTES)
             return false;
         const sig = base64urlDecode(signature);
-        return await ed.verifyAsync(sig, bytes, publicKey);
+        return await ed.verifyAsync(sig, bytes, publicKey, { zip215: false });
     }
     catch {
         return false;
@@ -739,7 +747,7 @@ export async function verifyAuditResponseSignature(events, signature, publicKey)
         if (bytes.length > MAX_SIGBASE_BODY_BYTES)
             return false;
         const sig = base64urlDecode(signature);
-        return await ed.verifyAsync(sig, bytes, publicKey);
+        return await ed.verifyAsync(sig, bytes, publicKey, { zip215: false });
     }
     catch {
         return false;
@@ -905,7 +913,7 @@ export async function verifyAuditQueryResponseSignature(responseWithoutSignature
         if (bytes.length > MAX_SIGBASE_BODY_BYTES)
             return false;
         const sig = base64urlDecode(signature);
-        return await ed.verifyAsync(sig, bytes, publicKey);
+        return await ed.verifyAsync(sig, bytes, publicKey, { zip215: false });
     }
     catch {
         return false;