@forestrie/receipt-verify 2.1.0 → 3.0.0

package/dist/checkpoint-chain.js

@@ -20,11 +20,15 @@
  * "keyless first checkpoint" case). `tree-size-1` stays unsigned prover
  * context: the publisher relays several sealed steps and may re-base a step
  * under the head checkpoint's signature, so the declared base of a
- * checkpoint can differ from what the sealer had (D2 chain semantics is
- * withdrawn) — a signed size-1 comparison would reject every re-based
- * publish and every multi-link catch-up. A checkpoint without the signed
- * size-2 label, or whose signed size-2 disagrees with its declared proof,
- * is rejected before any fold is attempted.
+ * checkpoint can differ from what the sealer had (the signed origin
+ * ADR-0066 D2 first proposed was withdrawn) — a signed size-1 comparison
+ * would reject every re-based publish and every multi-link catch-up. One
+ * checkpoint may itself relay SEVERAL sealed steps (ADR-0066 D2): the
+ * draft carries them under vdp key -2 as
+ * `consistency-proofs = [ + consistency-proof ]`, folded here in order,
+ * with only the last step's size signed. A checkpoint without the signed
+ * size-2 label, or whose signed size-2 disagrees with the last proof it
+ * relays, is rejected before any fold is attempted.
  *
  * This rung depends only on the public log store — the complement of the
  * `CheckpointPublished` event scan (public chain data only); see the
@@ -38,11 +42,35 @@
  * the key, so no reason string chosen from it may mean anything more than
  * "these two sizes differ".
  */
-import { COSE_ALG_ES256, extractAlgFromProtected, isLowS, readProtectedTreeSize2, } from "@forestrie/encoding";
+import { COSE_ALG_ES256, ProtectedHeaderAlgError, isLowS, readProtectedAlg, readProtectedTreeSize2, } from "@forestrie/encoding";
 import { consistentRootsForSizes, mmrSizeForLeafCount, peakMMRIndexes, peaksBitmap, } from "@forestrie/merklelog";
 import { SubtleHasher } from "./subtle-hasher.js";
 import { parseCheckpoint } from "./build-receipt-offline.js";
-import { decodeConsistencyProofFromUnprotected } from "./decode-checkpoint-consistency-proof.js";
+import { decodeConsistencyProofsFromUnprotected, EmptyConsistencyProofsError, } from "./decode-checkpoint-consistency-proof.js";
+/**
+ * A relayed consistency-proof chain does not join up: a proof's declared
+ * `tree-size-1` is not the size the fold has reached — the caller's trusted
+ * size for the first proof, the previous proof's `tree-size-2` after that —
+ * or, having applied every proof, the fold reaches a size other than the
+ * chain link's own declared `tree-size-2` (F3: a caller-assembled link —
+ * `freshenReceipt` callers build these from on-chain calldata, never
+ * through {@link checkpointConsistencyProof} — can set `proofs` and
+ * `treeSize2` independently, which `checkpointConsistencyProof` itself
+ * never allows to disagree). go-merklelog reuses its equivalent
+ * `ErrProofChainNotContiguous` for this same end-of-chain comparison
+ * (`checkpointverify.go:245-251`, folded size vs. signed size). Reported as
+ * `"size_mismatch"` by {@link verifyCheckpointChain}, the same as any other
+ * size disagreement, because the sizes it names are unsigned (ADR-0066 D2):
+ * nothing distinguishes a relay assembled in the wrong order from one
+ * assembled over a different log.
+ */
+export class ConsistencyChainNotContiguousError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConsistencyChainNotContiguousError";
+    }
+}
+export { EmptyConsistencyProofsError };
 /**
  * The checkpoint's SIGNED `tree-size-2` (protected header, ADR-0066 D1 as
  * amended) differs from the declared `tree-size-2` of its embedded
@@ -75,12 +103,32 @@ export class CheckpointHighSSignatureError extends Error {
     }
 }
 /**
- * Decode the embedded consistency proof (`vdp` 396 key -2) and require its
- * declared `tree-size-2` to equal the checkpoint's SIGNED `tree-size-2` from
- * the protected header (ADR-0066 D1 as amended, D5.5, label -65933).
- * `tree-size-1` is not signed and is not checked here (D2 is withdrawn); see
- * {@link verifyCheckpointChain} for its comparison against the trusted
- * origin.
+ * The checkpoint's protected header carries no integer `alg` (label 1).
+ *
+ * The univocity contract rejects such a header outright — the structural
+ * walk finds the size, and the `alg` requirement in the same call raises
+ * `ClaimNotFound(1)` or `UnexpectedMajorType`. Off-chain the header used to
+ * read as "no algorithm stated", which both turned OFF the high-s rejection
+ * below (gated on the algorithm being ES256) and still yielded a signed size
+ * to fold from — so a checkpoint the chain will never anchor verified here
+ * under weaker rules than a well-formed one (review finding S-1). Reported
+ * as `"proof_malformed"` by {@link verifyCheckpointChain}.
+ */
+export class CheckpointProtectedHeaderAlgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CheckpointProtectedHeaderAlgError";
+    }
+}
+/**
+ * Decode the embedded consistency proofs (`vdp` 396 key -2, one or more in
+ * relay order) and require the LAST proof's declared `tree-size-2` to equal
+ * the checkpoint's SIGNED `tree-size-2` from the protected header (ADR-0066
+ * D1 as amended, D2, D5.5, label -65933). The earlier proofs' sizes are not
+ * signed: the fold checks them against each other
+ * ({@link computeCheckpointAccumulator}). `tree-size-1` is not signed
+ * either; see {@link verifyCheckpointChain} for its comparison against the
+ * trusted origin.
  *
  * Also rejects a malleable high-s ES256 signature (see
  * {@link CheckpointHighSSignatureError}) before any fold or WebCrypto verify
@@ -88,73 +136,135 @@ export class CheckpointHighSSignatureError extends Error {
  * subject to this check, since it does not go through the P-256 WebCrypto
  * path this guards.
  *
- * @throws {Error} when the protected header carries no consistency proof,
- *   the proof is structurally malformed (see
- *   {@link decodeConsistencyProofFromUnprotected}), or the protected header
+ * @throws {Error} when the unprotected header carries no consistency proof,
+ *   a proof is structurally malformed (see
+ *   {@link decodeConsistencyProofsFromUnprotected}), or the protected header
  *   carries no signed tree-size-2 label
+ * @throws {EmptyConsistencyProofsError} when the consistency-proofs array is
+ *   present but empty
  * @throws {CheckpointSignedSizeMismatchError} when the signed tree-size-2
- *   differs from the declared proof's tree-size-2
+ *   differs from the LAST declared proof's tree-size-2
  * @throws {CheckpointHighSSignatureError} when the checkpoint is ES256-signed
  *   with a high-s (malleable) signature
+ * @throws {CheckpointProtectedHeaderAlgError} when the protected header
+ *   carries no integer `alg` (label 1)
  */
 export function checkpointConsistencyProof(checkpointBytes) {
     const { coseSign1, unprotected } = parseCheckpoint(checkpointBytes);
-    const alg = extractAlgFromProtected(coseSign1[0]);
+    // Strict: a header with no integer alg is one the contract rejects, and
+    // reading it leniently would switch the high-s rejection below off while
+    // the signed size was still taken from it (S-1).
+    let alg;
+    try {
+        alg = readProtectedAlg(coseSign1[0]);
+    }
+    catch (err) {
+        if (err instanceof ProtectedHeaderAlgError) {
+            throw new CheckpointProtectedHeaderAlgError(`checkpoint protected header carries no integer alg (label 1): ${err.message}`);
+        }
+        throw err;
+    }
     const signature = coseSign1[3];
     if (alg === COSE_ALG_ES256 && signature.length === 64 && !isLowS(signature)) {
         throw new CheckpointHighSSignatureError("checkpoint ES256 signature is not low-s canonical (s > n/2); rejected " +
             "to match the univocity contract's P-256 verifier and go-merklelog");
     }
-    const declared = decodeConsistencyProofFromUnprotected(unprotected);
-    if (declared === null) {
+    const proofs = decodeConsistencyProofsFromUnprotected(unprotected);
+    if (proofs === null) {
         throw new Error("checkpoint carries no consistency proof (vdp key -2)");
     }
+    const last = proofs[proofs.length - 1];
     const signedTreeSize2 = readProtectedTreeSize2(coseSign1[0]);
     if (signedTreeSize2 === null) {
         throw new Error("checkpoint protected header carries no signed tree-size-2 (-65933)");
     }
-    if (signedTreeSize2 !== declared.treeSize2) {
-        throw new CheckpointSignedSizeMismatchError(`signed tree-size-2 (-65933) ${signedTreeSize2} != declared consistency-proof tree-size-2 ${declared.treeSize2}`);
+    // The signature covers the size the LAST proof reaches, and only that
+    // size: a relay may hold any number of steps before it, none of them
+    // signed (ADR-0066 D2).
+    if (signedTreeSize2 !== last.treeSize2) {
+        throw new CheckpointSignedSizeMismatchError(`signed tree-size-2 (-65933) ${signedTreeSize2} != declared consistency-proof tree-size-2 ${last.treeSize2}`);
     }
     return {
-        treeSize1: declared.treeSize1,
-        treeSize2: declared.treeSize2,
+        proofs,
+        treeSize1: proofs[0].treeSize1,
+        treeSize2: last.treeSize2,
         signedTreeSize2,
-        paths: declared.paths,
-        rightPeaks: declared.rightPeaks,
     };
 }
 /**
- * One fold step: from the CALLER-TRUSTED accumulator at `sizeFrom`, produce
- * the `proof.treeSize2` accumulator via the size-driven
- * {@link consistentRootsForSizes} (ADR-0066 D5) — `roots` (the proven
- * prefix) followed by the proof's supplied right-peaks (the target peaks no
- * path reaches).
+ * Fold a checkpoint's relayed consistency proofs, in order, from the
+ * CALLER-TRUSTED accumulator at `sizeFrom` to the accumulator at the last
+ * proof's `tree-size-2` — the value the checkpoint's signature covers.
+ *
+ * Each proof is applied by the size-driven {@link consistentRootsForSizes}
+ * (ADR-0066 D5), which yields `roots` (the proven prefix); the proof's own
+ * right-peaks (the target peaks no path reaches) complete that step's
+ * accumulator, and it becomes the next step's input. A checkpoint sealing
+ * one step carries the chain of one and runs the same loop once.
  *
- * `sizeFrom` is a parameter, not read off `proof`, because the fold must run
- * against a size the CALLER already trusts (the previous link's verified
- * `treeSize2`, or the caller's anchor for a first link) — reading it from
- * the proof instead would let an unsigned or substituted proof dictate its
- * own starting point. `proof.treeSize1` must equal it regardless: the two
- * disagreeing means this proof does not continue from the state being
- * folded, not a mere shape defect, so it is checked before any fold work.
+ * `sizeFrom` is a parameter, not read off the proofs, because the fold must
+ * start from a size the CALLER already trusts (the previous checkpoint's
+ * verified `treeSize2`, or the caller's anchor for a first link) — reading
+ * it from the relay instead would let an unsigned or substituted proof
+ * dictate its own starting point (ADR-0066 D5.4). Every proof after the
+ * first is held to the size the previous one reached for the same reason:
+ * only the last step's size is signed, so the intermediate sizes are worth
+ * no more than their agreement with each other.
  *
- * @throws {Error} when `proof.treeSize1 !== sizeFrom`, or when the proof
- *   supplies a right-peaks count other than
+ * `proof.proofs` must hold at least one step and, once every step has been
+ * applied, the fold must have reached exactly `proof.treeSize2` (F3).
+ * `checkpointConsistencyProof` already guarantees both — the decode rejects
+ * an empty `consistency-proofs` array (`EmptyConsistencyProofsError`) and
+ * sets `treeSize2` from the last decoded proof — but a caller-assembled
+ * link (`freshenReceipt` callers building from on-chain calldata) is not
+ * decoded through it, so both are re-checked here rather than trusted from
+ * the type.
+ *
+ * @throws {EmptyConsistencyProofsError} when `proof.proofs` is empty — an
+ *   already-decoded link the caller assembled themselves rather than one
+ *   `checkpointConsistencyProof` produced, which never returns one
+ * @throws {ConsistencyChainNotContiguousError} when the first proof's
+ *   `treeSize1` is not `sizeFrom`, a later proof's `treeSize1` is not the
+ *   previous proof's `treeSize2`, or the size the fold reaches after every
+ *   proof is not `proof.treeSize2`
+ * @throws {Error} when a proof supplies a right-peaks count other than
  *   {@link consistentRootsForSizes}'s `expectedRight`
- * @throws {ConsistencyShapeError} (`@forestrie/merklelog`) when the proof
- *   does not have the shape MMR(sizeFrom) -> MMR(proof.treeSize2) implies
+ * @throws {ConsistencyShapeError} (`@forestrie/merklelog`) when a proof does
+ *   not have the shape its two sizes imply
  */
 export async function computeCheckpointAccumulator(proof, accumulatorFrom, sizeFrom) {
-    if (proof.treeSize1 !== sizeFrom) {
-        throw new Error(`consistency proof base tree-size-1 ${proof.treeSize1} does not match the trusted size ${sizeFrom}`);
+    if (proof.proofs.length === 0) {
+        throw new EmptyConsistencyProofsError("consistency proof relays no proofs (empty proofs array); at least " +
+            "one is required to fold");
     }
     const hasher = new SubtleHasher();
-    const { roots, expectedRight } = await consistentRootsForSizes(hasher, sizeFrom, proof.treeSize2, accumulatorFrom, proof.paths);
-    if (proof.rightPeaks.length !== expectedRight) {
-        throw new Error(`checkpoint supplies ${proof.rightPeaks.length} right-peaks; size ${proof.treeSize2} requires ${expectedRight}`);
+    let accumulator = accumulatorFrom;
+    let size = sizeFrom;
+    for (let i = 0; i < proof.proofs.length; i++) {
+        const step = proof.proofs[i];
+        if (step.treeSize1 !== size) {
+            throw new ConsistencyChainNotContiguousError(i === 0
+                ? `consistency proof base tree-size-1 ${step.treeSize1} does not match the trusted size ${size}`
+                : `consistency-proofs entry ${i} declares tree-size-1 ${step.treeSize1}; the previous proof reached ${size}`);
+        }
+        const { roots, expectedRight } = await consistentRootsForSizes(hasher, size, step.treeSize2, accumulator, step.paths);
+        if (step.rightPeaks.length !== expectedRight) {
+            throw new Error(`checkpoint supplies ${step.rightPeaks.length} right-peaks; size ${step.treeSize2} requires ${expectedRight}`);
+        }
+        accumulator = [...roots, ...step.rightPeaks];
+        size = step.treeSize2;
+    }
+    // The fold must land exactly on the size the LINK itself declares —
+    // `proof.treeSize2` — not merely on whatever size its last proof happened
+    // to reach: a caller-assembled link can set the two independently (e.g.
+    // proofs folding 1 -> 3 alongside a declared treeSize2 of 7), which would
+    // otherwise fold to 3 and be reported as size 7 to every downstream
+    // caller reading the declared field instead of the fold. Mirrors
+    // go-merklelog's own end-of-chain check (checkpointverify.go:245-251).
+    if (size !== proof.treeSize2) {
+        throw new ConsistencyChainNotContiguousError(`consistency proof folds to tree-size-2 ${size}; the chain's declared tree-size-2 is ${proof.treeSize2}`);
     }
-    return [...roots, ...proof.rightPeaks];
+    return accumulator;
 }
 /** Detached payload the checkpoint signature covers (ADR-0046): the raw
  * concatenation of the accumulator peaks in contract order. */
@@ -176,23 +286,31 @@ export function accumulatorPayload(accumulator) {
  *   as the fold's starting accumulator (a suffix chain rooted in an
  *   already-trusted accumulator supplies both).
  * - A supplied `trustedBase` must describe a state an MMR can be in: its
- *   `size` a complete MMR size, and its `accumulator` holding one peak per
- *   peak of that size. `peaksBitmap` rounds an incomplete size DOWN to the
- *   largest MMR below it, so without the completeness check a size of 5
- *   folds the 4 -> N shape while every link reports a base of 5 — a node
- *   count no MMR has. Both are `proof_malformed`.
+ *   `size` a complete MMR size, its `accumulator` holding one peak per peak
+ *   of that size, and every one of those peaks a 32-byte node value.
+ *   `peaksBitmap` rounds an incomplete size DOWN to the largest MMR below
+ *   it, so without the completeness check a size of 5 folds the 4 -> N shape
+ *   while every link reports a base of 5 — a node count no MMR has; and
+ *   without the byte-length check an origin peak of any length is copied
+ *   through the empty-path branch into the detached payload. All three are
+ *   `proof_malformed`.
  * - The first link's declared `tree-size-1` must equal that trusted
  *   starting size, and every subsequent link's must equal the previous
  *   link's sealed `tree-size-2`; either disagreement is `size_mismatch`.
- *   `tree-size-1` itself is never compared with a signed value (D2 is
- *   withdrawn): only this trusted-origin comparison applies. Because it is
+ *   `tree-size-1` itself is never compared with a signed value (the signed
+ *   origin ADR-0066 D2 first proposed was withdrawn): only this
+ *   trusted-origin comparison applies. Because it is
  *   unsigned, the reason it produces carries no more meaning than the size
  *   disagreement itself (ADR-0066 D6: no pre-FOR-410 state is supported, so
  *   there is no drift condition to fall back from).
- * - Each checkpoint's SIGNED `tree-size-2` (ADR-0066 D1 as amended) must
- *   equal its declared consistency-proof `tree-size-2`
- *   ({@link checkpointConsistencyProof}); a disagreement is
- *   `size_mismatch`.
+ * - A checkpoint may relay SEVERAL consistency proofs under one signature
+ *   (ADR-0066 D2; draft `consistency-proofs = [ + consistency-proof ]`).
+ *   Its SIGNED `tree-size-2` (ADR-0066 D1 as amended) must equal the LAST
+ *   proof's declared `tree-size-2` ({@link checkpointConsistencyProof}),
+ *   and each relayed proof must continue the one before it
+ *   ({@link computeCheckpointAccumulator}); either disagreement is
+ *   `size_mismatch`. A checkpoint sealing one step is the relay of one and
+ *   takes the same path.
  * - Each link's signature is checked over its computed accumulator via
  *   the injected verifier (the caller owns trust resolution — genesis
  *   roots, caller-known keys, or the label-1000 delegation path). A link
@@ -240,6 +358,25 @@ export async function verifyCheckpointChain(opts) {
                 links,
             };
         }
+        // …and every peak must be a 32-byte node value, the check arbor's
+        // producer applies to both path elements and right-peaks (`toNode32`).
+        // The count alone does not reach it: on the empty-path branch an origin
+        // peak is copied into the result verbatim, so a 0/31/33/64-byte peak
+        // reaches `accumulatorPayload` and shortens or lengthens the detached
+        // payload, with only the signature left to reject it (review finding
+        // I2, canopy C6).
+        for (let i = 0; i < trustedBase.accumulator.length; i++) {
+            const peak = trustedBase.accumulator[i];
+            if (!(peak instanceof Uint8Array) || peak.length !== 32) {
+                return {
+                    ok: false,
+                    reason: "proof_malformed",
+                    at: 0,
+                    detail: `trusted base accumulator peak ${i} is not a 32-byte node value (${describePeak(peak)})`,
+                    links,
+                };
+            }
+        }
     }
     let accumulator = trustedBase?.accumulator ?? [];
     let expectedBase = trustedBase?.size ?? 0n;
@@ -289,9 +426,14 @@ export async function verifyCheckpointChain(opts) {
             computed = await computeCheckpointAccumulator(proof, accumulator, expectedBase);
         }
         catch (err) {
+            // A relay that does not join up is a size disagreement like any
+            // other: every size it names but the last is unsigned, so the reason
+            // can say no more than that two sizes differ.
             return {
                 ok: false,
-                reason: "proof_malformed",
+                reason: err instanceof ConsistencyChainNotContiguousError
+                    ? "size_mismatch"
+                    : "proof_malformed",
                 at: i,
                 detail: err instanceof Error ? err.message : String(err),
                 links,
@@ -322,3 +464,13 @@ export async function verifyCheckpointChain(opts) {
     }
     return { ok: true, links, accumulator };
 }
+/** Name what was found where a 32-byte accumulator peak was required. */
+function describePeak(peak) {
+    if (peak instanceof Uint8Array)
+        return `${peak.length} bytes`;
+    if (peak === null)
+        return "null";
+    if (Array.isArray(peak))
+        return "an array";
+    return typeof peak;
+}

package/dist/decode-checkpoint-consistency-proof.d.ts

@@ -1,7 +1,20 @@
 /**
- * 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`).
+ * Decode the draft-bryce consistency proofs carried under a checkpoint's
+ * verifiable-proofs UNPROTECTED header (draft-bryce label 396, key -2 =
+ * `VDP_CONSISTENCY_PROOF_KEY`).
+ *
+ * The draft's CDDL is
+ * `consistency-proofs = [ + consistency-proof ]`, with each
+ * `consistency-proof = bstr .cbor [tree-size-1, tree-size-2, paths,
+ * right-peaks]` — one or more proofs, relayed in chain order under a single
+ * signature (ADR-0066 D2). Both shapes are accepted under the -2 key:
+ *
+ * - an ARRAY of one or more proof bstrs — the draft's wire form, and the
+ *   only form that can carry a relayed chain;
+ * - a BARE proof bstr — the shape every checkpoint sealed before the array
+ *   form carries, and the shape the pinned `checkpoint-receipt-kat39.json`
+ *   vector's `conventions.receipt` still states. It decodes to the array of
+ *   one, so nothing downstream distinguishes it.
  *
  * Single source of truth for this decode, shared by `parseCheckpoint`
  * (build-receipt-offline.ts, lenient: an absent or malformed proof yields a
@@ -9,10 +22,11 @@
  * (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).
+ * must match the `tree-size-2` of the LAST proof decoded here;
+ * `tree-size-1` is unsigned prover context and is not cross-checked against
+ * a signed value).
  */
-/** The declared (unprotected, unsigned) consistency proof of a checkpoint. */
+/** One declared (unprotected, unsigned) consistency proof of a checkpoint. */
 export type DecodedConsistencyProof = {
     treeSize1: bigint;
     treeSize2: bigint;
@@ -22,17 +36,35 @@ export type DecodedConsistencyProof = {
     rightPeaks: 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.
+ * The verifiable-proofs header carries the consistency-proof key with an
+ * EMPTY array. Distinct from an absent proof (no -2 key at all, which
+ * decodes to `null`): the key is present and claims to relay a chain, but
+ * the chain has no links, so there is nothing to fold and no last proof for
+ * the signed `tree-size-2` to equal. `consistency-proofs = [ + ... ]`
+ * requires at least one.
+ */
+export declare class EmptyConsistencyProofsError extends Error {
+    constructor(message: string);
+}
+/**
+ * Decode the embedded consistency proofs from a checkpoint's UNPROTECTED
+ * header map, in the order they are relayed. Returns `null` when the
+ * checkpoint carries no verifiable-proofs header (396) or no
+ * consistency-proof entry there (key -2) — an ABSENT proof, not a malformed
+ * one. A returned array always holds at least one proof.
+ *
+ * This decode establishes each proof's shape only. Nothing here relates one
+ * proof to the next, or to a signed size: the chain has to be checked
+ * against state the CALLER trusts, which is `computeCheckpointAccumulator`
+ * and `checkpointConsistencyProof` (ADR-0066 D5.4).
  *
- * @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
+ * @throws {EmptyConsistencyProofsError} when the -2 entry is an empty array
+ * @throws When a consistency proof 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, a 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.
+ *   or its `-2` entry is neither a byte string nor an array of byte strings.
  */
-export declare function decodeConsistencyProofFromUnprotected(unprotected: Map<number, unknown>): DecodedConsistencyProof | null;
+export declare function decodeConsistencyProofsFromUnprotected(unprotected: Map<number, unknown>): DecodedConsistencyProof[] | null;
 //# sourceMappingURL=decode-checkpoint-consistency-proof.d.ts.map

package/dist/decode-checkpoint-consistency-proof.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode-checkpoint-consistency-proof.d.ts","sourceRoot":"","sources":["../src/decode-checkpoint-consistency-proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,8EAA8E;AAC9E,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;IACtB,uEAAuE;IACvE,UAAU,EAAE,UAAU,EAAE,CAAC;CAC1B,CAAC;AA6BF;;;;;;;;;;;;GAYG;AACH,wBAAgB,qCAAqC,CACnD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,uBAAuB,GAAG,IAAI,CA8DhC"}
+{"version":3,"file":"decode-checkpoint-consistency-proof.d.ts","sourceRoot":"","sources":["../src/decode-checkpoint-consistency-proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAQH,8EAA8E;AAC9E,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;IACtB,uEAAuE;IACvE,UAAU,EAAE,UAAU,EAAE,CAAC;CAC1B,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AA8GD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sCAAsC,CACpD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,uBAAuB,EAAE,GAAG,IAAI,CA6BlC"}

package/dist/decode-checkpoint-consistency-proof.js

@@ -1,7 +1,20 @@
 /**
- * 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`).
+ * Decode the draft-bryce consistency proofs carried under a checkpoint's
+ * verifiable-proofs UNPROTECTED header (draft-bryce label 396, key -2 =
+ * `VDP_CONSISTENCY_PROOF_KEY`).
+ *
+ * The draft's CDDL is
+ * `consistency-proofs = [ + consistency-proof ]`, with each
+ * `consistency-proof = bstr .cbor [tree-size-1, tree-size-2, paths,
+ * right-peaks]` — one or more proofs, relayed in chain order under a single
+ * signature (ADR-0066 D2). Both shapes are accepted under the -2 key:
+ *
+ * - an ARRAY of one or more proof bstrs — the draft's wire form, and the
+ *   only form that can carry a relayed chain;
+ * - a BARE proof bstr — the shape every checkpoint sealed before the array
+ *   form carries, and the shape the pinned `checkpoint-receipt-kat39.json`
+ *   vector's `conventions.receipt` still states. It decodes to the array of
+ *   one, so nothing downstream distinguishes it.
  *
  * Single source of truth for this decode, shared by `parseCheckpoint`
  * (build-receipt-offline.ts, lenient: an absent or malformed proof yields a
@@ -9,10 +22,25 @@
  * (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).
+ * must match the `tree-size-2` of the LAST proof 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 verifiable-proofs header carries the consistency-proof key with an
+ * EMPTY array. Distinct from an absent proof (no -2 key at all, which
+ * decodes to `null`): the key is present and claims to relay a chain, but
+ * the chain has no links, so there is nothing to fold and no last proof for
+ * the signed `tree-size-2` to equal. `consistency-proofs = [ + ... ]`
+ * requires at least one.
+ */
+export class EmptyConsistencyProofsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EmptyConsistencyProofsError";
+    }
+}
 function asBigint(v, what) {
     // Unsigned only: a negative size flows into peakMMRIndexes /
     // consistentRootsForSizes, which reject or spin on a non-positive
@@ -36,35 +64,15 @@ function asBytesArray(v, what) {
     }
     return v;
 }
-/**
- * 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) {
-    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)");
-    }
+/** Decode one `bstr .cbor [tree-size-1, tree-size-2, paths, right-peaks]`. */
+function decodeOneProof(proofBstr) {
     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]");
+    // Exactly 4 — the draft's CDDL names a fixed-arity array, and
+    // go-merklelog's decoder rejects any other length (F2). A 5th element
+    // (e.g. another proof tuple, mistaken for a chain of two) is as malformed
+    // as a 3rd missing.
+    if (!Array.isArray(proof) || proof.length !== 4) {
+        throw new Error(`consistency proof must be [tree-size-1, tree-size-2, paths, right-peaks] (4 elements), got ${Array.isArray(proof) ? proof.length : typeof proof}`);
     }
     const pathsRaw = proof[2];
     if (!Array.isArray(pathsRaw)) {
@@ -106,3 +114,67 @@ export function decodeConsistencyProofFromUnprotected(unprotected) {
         rightPeaks: asBytesArray(proof[3], "right-peaks"),
     };
 }
+/**
+ * Decode proof `at` of a relayed chain, naming its position in the message
+ * so a chain of several says which link is malformed. A header carrying a
+ * single proof names no position: its message is the one a single-proof
+ * checkpoint has always produced.
+ */
+function decodeProofAt(proofBstr, at) {
+    if (at === null)
+        return decodeOneProof(proofBstr);
+    try {
+        return decodeOneProof(proofBstr);
+    }
+    catch (err) {
+        throw new Error(`consistency-proofs entry ${at}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Decode the embedded consistency proofs from a checkpoint's UNPROTECTED
+ * header map, in the order they are relayed. Returns `null` when the
+ * checkpoint carries no verifiable-proofs header (396) or no
+ * consistency-proof entry there (key -2) — an ABSENT proof, not a malformed
+ * one. A returned array always holds at least one proof.
+ *
+ * This decode establishes each proof's shape only. Nothing here relates one
+ * proof to the next, or to a signed size: the chain has to be checked
+ * against state the CALLER trusts, which is `computeCheckpointAccumulator`
+ * and `checkpointConsistencyProof` (ADR-0066 D5.4).
+ *
+ * @throws {EmptyConsistencyProofsError} when the -2 entry is an empty array
+ * @throws When a consistency proof 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, a 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 neither a byte string nor an array of byte strings.
+ */
+export function decodeConsistencyProofsFromUnprotected(unprotected) {
+    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 entry = vdpRaw.get(VDP_CONSISTENCY_PROOF_KEY);
+    if (entry === undefined || entry === null)
+        return null;
+    if (entry instanceof Uint8Array) {
+        // The pre-array shape: a single proof written straight under -2. It is
+        // the array of one, and is reported as such.
+        return [decodeOneProof(entry)];
+    }
+    if (!Array.isArray(entry)) {
+        throw new Error("checkpoint carries no consistency proof (vdp key -2)");
+    }
+    if (entry.length === 0) {
+        throw new EmptyConsistencyProofsError("consistency-proofs (vdp key -2) is empty; at least one proof is required");
+    }
+    return entry.map((proofBstr, i) => {
+        if (!(proofBstr instanceof Uint8Array)) {
+            throw new Error(`consistency-proofs entry ${i} is not a byte string (vdp key -2)`);
+        }
+        return decodeProofAt(proofBstr, entry.length === 1 ? null : i);
+    });
+}