@forestrie/receipt-verify 1.0.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/decode-genesis-cbor-map.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared decode step for a genesis document's CBOR body: deterministic CBOR
+ * decodes an integer-keyed map either as a native `Map` or as a plain
+ * object (encoder-dependent), so callers that read genesis labels normalise
+ * to a `Map<number, unknown>` once here rather than each re-implementing
+ * the same fallback. Used by {@link decodeTrustRootFromGenesis} and
+ * {@link decodeChainBindingFromGenesis}.
+ */
+export function decodeGenesisBodyAsIntKeyMap(
+  raw: unknown,
+): Map<number, unknown> | null {
+  if (raw instanceof Map) return raw as Map<number, unknown>;
+  if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+    const out = new Map<number, unknown>();
+    for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+      const n = Number(k);
+      if (Number.isFinite(n)) out.set(n, v);
+    }
+    return out;
+  }
+  return null;
+}
+
+/** Narrow a decoded genesis field to `Uint8Array`, or `null` if it is not one. */
+export function asGenesisUint8Array(v: unknown): Uint8Array | null {
+  return v instanceof Uint8Array ? v : null;
+}

package/src/decode-trust-root-from-genesis.ts

@@ -17,39 +17,35 @@ import {
   FOREST_GENESIS_SCHEMA_V2,
 } from "./forest-genesis-labels.js";
 import { decodeTrustRootCbor } from "./decode-trust-root-cbor.js";
-import type { RootVerifyKey } from "./root-verify-key.js";
-
-function decodeBodyAsIntKeyMap(raw: unknown): Map<number, unknown> | null {
-  if (raw instanceof Map) return raw as Map<number, unknown>;
-  if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
-    const out = new Map<number, unknown>();
-    for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
-      const n = Number(k);
-      if (Number.isFinite(n)) out.set(n, v);
-    }
-    return out;
-  }
-  return null;
-}
-
-function asGenesisUint8Array(v: unknown): Uint8Array | null {
-  return v instanceof Uint8Array ? v : null;
-}
+import { isParsedKs256RootKey, type RootVerifyKey } from "./root-verify-key.js";
+import {
+  asGenesisUint8Array,
+  decodeGenesisBodyAsIntKeyMap,
+} from "./decode-genesis-cbor-map.js";
+import type { DecodedTrustRoot } from "./decoded-trust-root.js";
 
 /**
- * Extract receipt verify key from a forest genesis document CBOR blob.
- * Offline path: genesis-only trust anchor (ADR-0045).
+ * Extract the receipt verify key from a forest genesis document CBOR blob,
+ * alongside `bootstrapKeyXy` when the bootstrap key is ES256. Offline path:
+ * genesis-only trust anchor (ADR-0045). See {@link DecodedTrustRoot}.
+ * `bootstrapKeyXy` is read directly from the genesis-encoded bytes (never
+ * exported from the non-extractable `CryptoKey` in `key`), and is
+ * `undefined` for a KS256 v2 bootstrap key (an on-chain address — there is
+ * no P-256 public key to give up in that case).
+ *
+ * This is the single decode path: {@link decodeTrustRootFromGenesis} is
+ * `(await decodeTrustRootDetailsFromGenesis(genesisCbor)).key`.
  */
-export async function decodeTrustRootFromGenesis(
+export async function decodeTrustRootDetailsFromGenesis(
   genesisCbor: Uint8Array,
-): Promise<RootVerifyKey> {
+): Promise<DecodedTrustRoot> {
   let raw: unknown;
   try {
     raw = decodeCborDeterministic(genesisCbor);
   } catch {
     throw new Error("genesis CBOR decode failed");
   }
-  const m = decodeBodyAsIntKeyMap(raw);
+  const m = decodeGenesisBodyAsIntKeyMap(raw);
   if (!m) throw new Error("genesis document must be a CBOR map");
 
   const versionRaw = m.get(FOREST_GENESIS_LABEL_GENESIS_VERSION);
@@ -61,7 +57,11 @@ export async function decodeTrustRootFromGenesis(
     if (bootstrapKey === null) {
       throw new Error("v2 genesis missing bootstrapKey");
     }
-    return decodeTrustRootCbor({ alg, key: bootstrapKey });
+    const key = await decodeTrustRootCbor({ alg, key: bootstrapKey });
+    return {
+      key,
+      bootstrapKeyXy: isParsedKs256RootKey(key) ? undefined : bootstrapKey,
+    };
   }
 
   const kty = m.get(COSE_KEY_KTY);
@@ -76,7 +76,8 @@ export async function decodeTrustRootFromGenesis(
     const xy = new Uint8Array(64);
     xy.set(x, 0);
     xy.set(y, 32);
-    return decodeTrustRootCbor({ alg: COSE_ALG_ES256, key: xy });
+    const key = await decodeTrustRootCbor({ alg: COSE_ALG_ES256, key: xy });
+    return { key, bootstrapKeyXy: xy };
   }
 
   if (versionRaw === FOREST_GENESIS_SCHEMA_V1 || versionRaw === undefined) {
@@ -85,3 +86,17 @@ export async function decodeTrustRootFromGenesis(
 
   throw new Error("unsupported genesis document");
 }
+
+/**
+ * Extract the receipt verify key from a forest genesis document CBOR blob.
+ * Offline path: genesis-only trust anchor (ADR-0045). The origin/main
+ * signature and behaviour (including a KS256 v2 bootstrap key resolving to
+ * the `ParsedKs256RootKey` on-chain address, not a throw): callers pinned
+ * to `RootVerifyKey` keep working unchanged. For the raw bootstrap public
+ * key bytes as well, use {@link decodeTrustRootDetailsFromGenesis}.
+ */
+export async function decodeTrustRootFromGenesis(
+  genesisCbor: Uint8Array,
+): Promise<RootVerifyKey> {
+  return (await decodeTrustRootDetailsFromGenesis(genesisCbor)).key;
+}

package/src/decoded-trust-root.ts

@@ -0,0 +1,17 @@
+import type { RootVerifyKey } from "./root-verify-key.js";
+
+/**
+ * Result of {@link decodeTrustRootDetailsFromGenesis}: the decoded verify
+ * key (an ES256 `CryptoKey`, or a KS256 on-chain address) plus, for the
+ * ES256 case, the raw 64-byte x||y P-256 public key coordinates the genesis
+ * document carries. `bootstrapKeyXy` is read directly from the
+ * genesis-encoded bytes, not exported from `key` (`key` stays
+ * non-extractable) — plan-2609-07 L3, for callers that need the
+ * serialisable public key material the `CryptoKey` cannot give up.
+ * `bootstrapKeyXy` is `undefined` for a KS256 v2 bootstrap key (an on-chain
+ * address — there is no P-256 public key to give up).
+ */
+export interface DecodedTrustRoot {
+  key: RootVerifyKey;
+  bootstrapKeyXy?: Uint8Array;
+}

package/src/forest-genesis-labels.ts

@@ -1,6 +1,13 @@
 export const FOREST_GENESIS_LABEL_GENESIS_VERSION = -68009;
 export const FOREST_GENESIS_LABEL_GENESIS_ALG = -68014;
 export const FOREST_GENESIS_LABEL_BOOTSTRAP_KEY = -68015;
+/**
+ * The forest's own log id, wire-encoded as 32 bytes: 16 zero bytes then the
+ * 16-byte forest bootstrap log id (plan-2609-07 L3; mirrors mcp-resolve's
+ * `genesis-binding.ts` naming so that consumer can import this instead of
+ * defining it locally). See {@link decodeChainBindingFromGenesis}.
+ */
+export const FOREST_GENESIS_LABEL_LOG_ID = -68010;
 export const FOREST_GENESIS_LABEL_UNIVOCITY_ADDR = -68011;
 export const FOREST_GENESIS_LABEL_CHAIN_ID = -68013;
 export const FOREST_GENESIS_SCHEMA_V2 = 2;

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

@@ -31,7 +31,37 @@ export type {
  * re-exported here to preserve the receipt-verify public surface.
  */
 export { peakMMRIndexes } from "@forestrie/merklelog";
-export { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
+/**
+ * `decodeTrustRootFromGenesis` keeps its origin/main signature and
+ * behaviour (`Promise<RootVerifyKey>`, including a KS256 v2 bootstrap key
+ * resolving without a throw) so pinned consumers (mcp-verify 1.0.0) are
+ * unaffected. `decodeTrustRootDetailsFromGenesis` is the additive sibling
+ * (plan-2609-07 L3) carrying `bootstrapKeyXy` alongside `key`.
+ */
+export {
+  decodeTrustRootDetailsFromGenesis,
+  decodeTrustRootFromGenesis,
+} from "./decode-trust-root-from-genesis.js";
+export type { DecodedTrustRoot } from "./decoded-trust-root.js";
+/**
+ * Genesis document label constants (plan-2609-07 L3): exported from the
+ * package root so consumers stop redefining them locally (mcp-resolve's own
+ * `genesis-binding.ts` did, before this).
+ */
+export {
+  FOREST_GENESIS_LABEL_BOOTSTRAP_KEY,
+  FOREST_GENESIS_LABEL_CHAIN_ID,
+  FOREST_GENESIS_LABEL_GENESIS_ALG,
+  FOREST_GENESIS_LABEL_GENESIS_VERSION,
+  FOREST_GENESIS_LABEL_LOG_ID,
+  FOREST_GENESIS_LABEL_UNIVOCITY_ADDR,
+} from "./forest-genesis-labels.js";
+/**
+ * Genesis-bound chain binding (plan-2609-07 L3): mirrors mcp-resolve's own
+ * `decodeChainBindingFromGenesis` so that consumer can delete its copy.
+ */
+export { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+export type { ChainBinding } from "./chain-binding.js";
 export { verifyGrantReceiptOffline } from "./verify-grant-receipt-offline.js";
 export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
 /**
@@ -125,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)");
   }