@forestrie/receipt-verify 1.1.0 → 2.0.0

package/src/decode-checkpoint-consistency-proof.ts

@@ -0,0 +1,136 @@
+/**
+ * Decode the draft-bryce consistency proof `[tree-size-1, tree-size-2, paths,
+ * right-peaks]` carried under a checkpoint's verifiable-proofs UNPROTECTED
+ * header (draft-bryce label 396, key -2 = `VDP_CONSISTENCY_PROOF_KEY`).
+ *
+ * Single source of truth for this decode, shared by `parseCheckpoint`
+ * (build-receipt-offline.ts, lenient: an absent or malformed proof yields a
+ * `null` sealed size rather than a throw) and `checkpointConsistencyProof`
+ * (checkpoint-chain.ts, full validation: an absent proof or a malformed
+ * shape throws, and the SIGNED `tree-size-2` from the protected header —
+ * read separately via `readProtectedTreeSize2`, ADR-0066 D1 as amended —
+ * must match the `tree-size-2` decoded here; `tree-size-1` is unsigned
+ * prover context and is not cross-checked against a signed value).
+ */
+
+import {
+  COSE_LABEL_VDP,
+  VDP_CONSISTENCY_PROOF_KEY,
+  decodeCborDeterministic,
+} from "@forestrie/encoding";
+
+/** The declared (unprotected, unsigned) consistency proof of a checkpoint. */
+export type DecodedConsistencyProof = {
+  treeSize1: bigint;
+  treeSize2: bigint;
+  /** One inclusion path per tree-size-1 peak, proven at tree-size-2. */
+  paths: Uint8Array[][];
+  /** New peaks not covered by the proven roots (draft `right-peaks`). */
+  rightPeaks: Uint8Array[];
+};
+
+function asBigint(v: unknown, what: string): bigint {
+  // Unsigned only: a negative size flows into peakMMRIndexes /
+  // consistentRootsForSizes, which reject or spin on a non-positive
+  // argument — a malformed `.sth` must be rejected in bounded time, before
+  // any such call (FOR-414).
+  if (typeof v === "bigint") {
+    if (v < 0n) {
+      throw new Error(`${what}: must be an unsigned integer, got ${v}`);
+    }
+    return v;
+  }
+  if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0) {
+    return BigInt(v);
+  }
+  throw new Error(`${what}: expected an unsigned integer`);
+}
+
+function asBytesArray(v: unknown, what: string): Uint8Array[] {
+  if (
+    !Array.isArray(v) ||
+    v.some((e) => !(e instanceof Uint8Array) || e.length !== 32)
+  ) {
+    throw new Error(`${what}: expected an array of 32-byte strings`);
+  }
+  return v as Uint8Array[];
+}
+
+/**
+ * Decode the embedded consistency proof from a checkpoint's UNPROTECTED
+ * header map. Returns `null` when the checkpoint carries no verifiable-proofs
+ * header (396) or no consistency-proof bstr there (key -2) — an ABSENT
+ * proof, not a malformed one.
+ *
+ * @throws When a consistency-proof bstr IS present but its contents are not
+ *   the shape `[tree-size-1, tree-size-2, paths, right-peaks]`, either size
+ *   is not an unsigned integer, the proof does not grow the tree
+ *   (`tree-size-2 <= tree-size-1`), a path element or a right-peak is not a
+ *   32-byte string — or when header 396 is present but is not map-valued,
+ *   or its `-2` entry is present but not a byte string.
+ */
+export function decodeConsistencyProofFromUnprotected(
+  unprotected: Map<number, unknown>,
+): DecodedConsistencyProof | null {
+  const vdpRaw = unprotected.get(COSE_LABEL_VDP);
+  if (vdpRaw === undefined || vdpRaw === null) return null;
+  if (!(vdpRaw instanceof Map)) {
+    throw new Error("checkpoint carries no verifiable-proofs header (396)");
+  }
+  const proofBstr = vdpRaw.get(VDP_CONSISTENCY_PROOF_KEY);
+  if (proofBstr === undefined || proofBstr === null) return null;
+  if (!(proofBstr instanceof Uint8Array)) {
+    throw new Error("checkpoint carries no consistency proof (vdp key -2)");
+  }
+  const proof = decodeCborDeterministic(proofBstr);
+  if (!Array.isArray(proof) || proof.length < 4) {
+    throw new Error(
+      "consistency proof must be [tree-size-1, tree-size-2, paths, right-peaks]",
+    );
+  }
+  const pathsRaw = proof[2];
+  if (!Array.isArray(pathsRaw)) {
+    throw new Error("consistency paths must be arrays of 32-byte strings");
+  }
+  // Every path element is an MMR node, so it is 32 bytes — the same rule
+  // `asBytesArray` applies to right-peaks. Both reach the same places: the
+  // fold hashes them, and the peaks that come out are concatenated by
+  // `accumulatorPayload` with no length delimiter, so a node of any other
+  // length makes that payload ambiguous. Checking it here also bounds the
+  // work an unauthenticated `.sth` can ask for before its signature is
+  // consulted.
+  for (let i = 0; i < pathsRaw.length; i++) {
+    const path = pathsRaw[i] as unknown;
+    if (!Array.isArray(path)) {
+      throw new Error(
+        `consistency path ${i}: expected an array of 32-byte strings`,
+      );
+    }
+    for (let j = 0; j < path.length; j++) {
+      const node = path[j] as unknown;
+      if (!(node instanceof Uint8Array) || node.length !== 32) {
+        throw new Error(
+          `consistency path ${i} element ${j}: expected a 32-byte string`,
+        );
+      }
+    }
+  }
+  const treeSize1 = asBigint(proof[0], "tree-size-1");
+  const treeSize2 = asBigint(proof[1], "tree-size-2");
+  // A consistency proof strictly grows the tree; enforce `0 <= ts1 < ts2`
+  // (ts1 == 0 is a legitimate base-0 first link). This is the primary guard
+  // that keeps sizes non-negative and growing before they reach
+  // `consistentRootsForSizes` (FOR-414); the unsigned check in `asBigint`
+  // and `SizeMustIncrease` in `@forestrie/merklelog` are defence-in-depth.
+  if (treeSize2 <= treeSize1) {
+    throw new Error(
+      `consistency proof must grow the tree: tree-size-1 ${treeSize1} < tree-size-2 ${treeSize2}`,
+    );
+  }
+  return {
+    treeSize1,
+    treeSize2,
+    paths: pathsRaw as Uint8Array[][],
+    rightPeaks: asBytesArray(proof[3], "right-peaks"),
+  };
+}

package/src/freshen-receipt.ts

@@ -48,8 +48,10 @@
 import {
   calculateRoot,
   inclusionProofPath,
+  mmrSizeForLeafCount,
   peakIndexForLeafProof,
   peakMMRIndexes,
+  peaksBitmap,
 } from "@forestrie/merklelog";
 import {
   assembleReceiptFromProof,
@@ -62,19 +64,33 @@ import {
 import { parseReceipt } from "./parse-receipt.js";
 import { SubtleHasher } from "./subtle-hasher.js";
 
+/**
+ * BREAKING (within the 2.0.0 major already in flight): the sizeless
+ * `accumulatorFrom?: Uint8Array[]` seed is replaced by `trustedBase`, which
+ * carries the seed's SIZE alongside its peaks. Without a size the fold ran
+ * each link against the size read off that link's own proof, which is what
+ * {@link computeCheckpointAccumulator} exists to prevent (ADR-0066 D5.4) —
+ * a seed could only ever be checked against the peak count the proof's own
+ * declared base implies, and many sizes share a peak count.
+ */
 export type FreshenReceiptInput = {
   /** The stale receipt (COSE Sign1 with a 396 inclusion proof). */
   oldReceiptBytes: Uint8Array;
   /** The leaf's committed value: `SHA-256(idtimestamp ‖ inner)` — the same
    * value `verify` recomputes from the entry (caller derives it). */
   leafValue: Uint8Array;
-  /** Consistency-proof chain covering [0 or a trusted seed] → the latest sealed
-   * size, in ascending contiguous order (the raw per-checkpoint proofs, with
-   * `paths`). The chain's last link must end at the checkpoint's sealed size. */
+  /** Consistency-proof chain covering [0 or the trusted base] → the latest
+   * sealed size, in ascending contiguous order (the raw per-checkpoint
+   * proofs, with `paths`). The chain's last link must end at the
+   * checkpoint's sealed size. */
   consistencyProofs: readonly CheckpointConsistencyProof[];
-  /** Trusted accumulator seed for a suffix chain; omit for a chain from base 0.
-   * Its peak count must match the first link's tree-size-1. */
-  accumulatorFrom?: Uint8Array[];
+  /** Trusted base for a suffix chain — the size the caller already trusts
+   * and that size's accumulator; omit for a chain from base 0 (size 0, an
+   * empty accumulator). The size must be a complete MMR size, the
+   * accumulator must hold one peak per peak of that size, and the first
+   * link's declared `tree-size-1` must equal the size. Same shape as
+   * `verifyCheckpointChain`'s `trustedBase`. */
+  trustedBase?: { size: bigint; accumulator: Uint8Array[] };
   /** The latest checkpoint (`.sth`): its pre-signed peak receipts + delegation
    * cert become the freshened receipt's signature. */
   latestCheckpointBytes: Uint8Array;
@@ -134,22 +150,32 @@ export async function freshenReceipt(
     );
   }
   const firstLink = links[0]!;
-  // Base: a base-0 chain starts from an empty accumulator; a suffix chain's
-  // trusted seed must have the peak count of its tree-size-1.
-  const baseCount = input.accumulatorFrom?.length ?? 0;
-  if (firstLink.treeSize1 === 0n) {
-    if (baseCount !== 0) {
-      throw new Error(
-        "base-0 consistency chain must start from an empty accumulator seed",
-      );
-    }
-  } else {
-    const wanted = peakMMRIndexes(firstLink.treeSize1 - 1n).length;
-    if (baseCount !== wanted) {
-      throw new Error(
-        `base accumulator has ${baseCount} peaks; first link size ${firstLink.treeSize1} requires ${wanted}`,
-      );
-    }
+  // Base: the CALLER's trusted size and its accumulator (size 0 and an empty
+  // accumulator for a whole-log chain). The size has to be a size an MMR can
+  // have — `peaksBitmap` rounds an incomplete one DOWN, so a size of 5 would
+  // fold the 4 -> N shape — and the accumulator has to hold that size's
+  // peaks, which is the check the proof's own declared base used to stand in
+  // for.
+  const baseSize = input.trustedBase?.size ?? 0n;
+  const baseAccumulator = input.trustedBase?.accumulator ?? [];
+  if (
+    baseSize < 0n ||
+    mmrSizeForLeafCount(peaksBitmap(baseSize)) !== baseSize
+  ) {
+    throw new Error(`trusted base size ${baseSize} is not a complete MMR size`);
+  }
+  const basePeaks = baseSize === 0n ? 0 : peakMMRIndexes(baseSize - 1n).length;
+  if (baseAccumulator.length !== basePeaks) {
+    throw new Error(
+      `base accumulator has ${baseAccumulator.length} peaks; trusted base size ${baseSize} has ${basePeaks}`,
+    );
+  }
+  // The first link must continue from that size, not from a size it names
+  // itself (ADR-0066 D5.4).
+  if (firstLink.treeSize1 !== baseSize) {
+    throw new Error(
+      `first consistency proof declares tree-size-1 ${firstLink.treeSize1}; the trusted base size is ${baseSize}`,
+    );
   }
   // Contiguity: each link continues where the previous one sealed.
   for (let i = 1; i < links.length; i++) {
@@ -167,10 +193,15 @@ export async function freshenReceipt(
     );
   }
 
-  // Fold the chain to the latest accumulator (self-check target).
-  let accumulator = input.accumulatorFrom ?? [];
+  // Fold the chain to the latest accumulator (self-check target). Each step
+  // runs against a size the caller trusts, never one read off the link being
+  // folded: the trusted base for the first link, and the size the previous
+  // link was just folded TO for every link after it.
+  let accumulator = baseAccumulator;
+  let sizeFrom = baseSize;
   for (const p of links) {
-    accumulator = await computeCheckpointAccumulator(p, accumulator);
+    accumulator = await computeCheckpointAccumulator(p, accumulator, sizeFrom);
+    sizeFrom = p.treeSize2;
   }
   const aLatest = accumulator;
 

package/src/index.ts

@@ -155,6 +155,8 @@ export {
   checkpointConsistencyProof,
   computeCheckpointAccumulator,
   verifyCheckpointChain,
+  CheckpointHighSSignatureError,
+  CheckpointSignedSizeMismatchError,
   type CheckpointChainLink,
   type CheckpointChainResult,
   type CheckpointConsistencyProof,

package/src/parse-receipt.ts

@@ -1,8 +1,6 @@
-import { decodeCborDeterministic } from "@forestrie/encoding";
+import { COSE_LABEL_VDP, decodeCborDeterministic } from "@forestrie/encoding";
 import type { Proof } from "@forestrie/merklelog";
 
-const VDS_COSE_RECEIPT_PROOFS_TAG = 396;
-
 export type CoseSign1 = [
   protectedHeader: Uint8Array,
   unprotectedHeader: Map<number, unknown> | Record<string, unknown>,
@@ -81,7 +79,7 @@ export function parseReceipt(receiptBytes: Uint8Array): {
   }
 
   const unprotected = toHeaderMap(coseSign1[1]);
-  const proofsRaw = unprotected.get(VDS_COSE_RECEIPT_PROOFS_TAG);
+  const proofsRaw = unprotected.get(COSE_LABEL_VDP);
   if (!proofsRaw || typeof proofsRaw !== "object") {
     throw new Error("Receipt missing header 396 (inclusion proof)");
   }