@forestrie/receipt-verify 1.1.0 → 2.1.0

package/dist/checkpoint-chain.js

@@ -1,105 +1,160 @@
 /**
- * Retained-checkpoint chain verification (FOR-368 Phase 3, plan-2607-29).
+ * Retained-checkpoint chain verification (FOR-368 Phase 3, plan-2607-29;
+ * FOR-568/ADR-0066 signed size-2, plan-2609-10 §4.4, amended 2026-09-20).
  *
  * Post-FOR-410 (ADR-0056) every checkpoint's embedded consistency proof
  * spans its massif's ENTRY BOUNDARY to its seal, so the store's retained
  * `.sth` objects form a contiguous chain `0 → S₁ → S₂ → …`. Folding the
- * chain per the draft ("Chained proofs" / `consistent_roots`) reconstructs
- * each link's tree-size-2 accumulator — which is exactly the detached
- * payload its signature covers (ADR-0046: concat of the accumulator in
- * descending height order). The fold therefore yields, with NO tile access
- * and NO RPC: an authenticated accumulator at every retained seal, and the
- * final state to check a receipt's recomputed peak against.
+ * chain via the SIZE-DRIVEN {@link consistentRootsForSizes} (ADR-0066 D5;
+ * `@forestrie/merklelog`) reconstructs each link's tree-size-2 accumulator —
+ * which is exactly the detached payload its signature covers (ADR-0046:
+ * concat of the accumulator in descending height order). The fold therefore
+ * yields, with NO tile access and NO RPC: an authenticated accumulator at
+ * every retained seal, and the final state to check a receipt's recomputed
+ * peak against.
+ *
+ * Only `tree-size-2` is SIGNED (ADR-0066 D1 as amended: protected header
+ * label -65933) — the value folded here is the one the checkpoint's own
+ * signature covers, not merely the unprotected consistency proof's declared
+ * value, which an unsigned checkpoint could otherwise restate freely (the
+ * "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.
  *
  * This rung depends only on the public log store — the complement of the
  * `CheckpointPublished` event scan (public chain data only); see the
  * recorded both-paths decision in plan-2607-29.
  *
- * Legacy (pre-FOR-410) chains surface as a contiguity break
- * (`legacy_chain_break`): a permanent per-log condition — fall back to the
- * event scan, tile extension, or a holder cache.
+ * No pre-FOR-410 state is supported (ADR-0066 D6): the affected logs are
+ * re-anchored, so there is no drift condition to signal and no fallback to
+ * select. A declared `tree-size-1` that does not continue the state being
+ * folded is `size_mismatch` like any other size disagreement — and it has to
+ * be, because that value is unsigned: a relaying party can set it without
+ * the key, so no reason string chosen from it may mean anything more than
+ * "these two sizes differ".
  */
-import { decodeCborDeterministic } from "@forestrie/encoding";
-import { consistentRoots, peakMMRIndexes } from "@forestrie/merklelog";
+import { COSE_ALG_ES256, extractAlgFromProtected, isLowS, 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";
-const VDS_COSE_RECEIPT_PROOFS_TAG = 396;
-const VDP_CONSISTENCY_PROOF_KEY = -2;
-function asBigint(v, what) {
-    // Unsigned only: a negative size flows into `peakMMRIndexes`, whose
-    // `posHeight` spins forever 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);
+import { decodeConsistencyProofFromUnprotected } from "./decode-checkpoint-consistency-proof.js";
+/**
+ * The checkpoint's SIGNED `tree-size-2` (protected header, ADR-0066 D1 as
+ * amended) differs from the declared `tree-size-2` of its embedded
+ * (unprotected) consistency proof. Distinct from a structurally malformed
+ * proof: {@link verifyCheckpointChain} reports this as `"size_mismatch"`,
+ * not `"proof_malformed"`.
+ */
+export class CheckpointSignedSizeMismatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CheckpointSignedSizeMismatchError";
     }
-    throw new Error(`${what}: expected an unsigned integer`);
 }
-function asBytesArray(v, what) {
-    if (!Array.isArray(v) ||
-        v.some((e) => !(e instanceof Uint8Array) || e.length !== 32)) {
-        throw new Error(`${what}: expected an array of 32-byte strings`);
+/**
+ * The checkpoint's ES256 signature is the malleable high-s twin (`s > n/2`,
+ * `n` the P-256 group order): go-merklelog rejects these for checkpoint
+ * COSE_Sign1 signatures because the univocity contract's P-256 verifier
+ * does, so a receipt that verified here while carrying a high-s signature
+ * could be one the chain refuses (FOR-568 rollout item 4). Checked here,
+ * before any WebCrypto verify is attempted, so a rejected signature never
+ * reaches {@link verifyCheckpointChain}'s `verifySignature` callback. Scoped
+ * to the checkpoint receipt path only — this module never touches the WebAuthn
+ * (-65800) or session-key-endorsement (-65801) signature paths, which stay
+ * governed by their own canonical-form rules.
+ */
+export class CheckpointHighSSignatureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CheckpointHighSSignatureError";
     }
-    return v;
 }
-/** Decode the embedded consistency proof (`vdp` 396 key -2). */
+/**
+ * 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.
+ *
+ * Also rejects a malleable high-s ES256 signature (see
+ * {@link CheckpointHighSSignatureError}) before any fold or WebCrypto verify
+ * work — a checkpoint signed with any other algorithm (e.g. KS256) is not
+ * 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
+ *   carries no signed tree-size-2 label
+ * @throws {CheckpointSignedSizeMismatchError} when the signed tree-size-2
+ *   differs from the declared proof's tree-size-2
+ * @throws {CheckpointHighSSignatureError} when the checkpoint is ES256-signed
+ *   with a high-s (malleable) signature
+ */
 export function checkpointConsistencyProof(checkpointBytes) {
-    const { unprotected } = parseCheckpoint(checkpointBytes);
-    const vdpRaw = unprotected.get(VDS_COSE_RECEIPT_PROOFS_TAG);
-    if (!(vdpRaw instanceof Map)) {
-        throw new Error("checkpoint carries no verifiable-proofs header (396)");
+    const { coseSign1, unprotected } = parseCheckpoint(checkpointBytes);
+    const alg = extractAlgFromProtected(coseSign1[0]);
+    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 proofBstr = vdpRaw.get(VDP_CONSISTENCY_PROOF_KEY);
-    if (!(proofBstr instanceof Uint8Array)) {
+    const declared = decodeConsistencyProofFromUnprotected(unprotected);
+    if (declared === null) {
         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) ||
-        pathsRaw.some((p) => !Array.isArray(p) || p.some((n) => !(n instanceof Uint8Array)))) {
-        throw new Error("consistency paths must be arrays of byte strings");
+    const signedTreeSize2 = readProtectedTreeSize2(coseSign1[0]);
+    if (signedTreeSize2 === null) {
+        throw new Error("checkpoint protected header carries no signed tree-size-2 (-65933)");
     }
-    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 `treeSize2 - 1` / `treeSize1 - 1` non-negative before they
-    // reach `peakMMRIndexes` (FOR-414); the unsigned check in `asBigint` and
-    // the `posHeight` guard 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}`);
+    if (signedTreeSize2 !== declared.treeSize2) {
+        throw new CheckpointSignedSizeMismatchError(`signed tree-size-2 (-65933) ${signedTreeSize2} != declared consistency-proof tree-size-2 ${declared.treeSize2}`);
     }
     return {
-        treeSize1,
-        treeSize2,
-        paths: pathsRaw,
-        rightPeaks: asBytesArray(proof[3], "right-peaks"),
+        treeSize1: declared.treeSize1,
+        treeSize2: declared.treeSize2,
+        signedTreeSize2,
+        paths: declared.paths,
+        rightPeaks: declared.rightPeaks,
     };
 }
 /**
- * One fold step: from the trusted accumulator at `proof.treeSize1`,
- * produce the `treeSize2` accumulator (draft: `consistent_roots` output
- * plus the supplied right-peaks). Structural sanity: the result must have
- * exactly the peak count of a size-`treeSize2` MMR.
+ * 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).
+ *
+ * `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.
+ *
+ * @throws {Error} when `proof.treeSize1 !== sizeFrom`, or when the 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
  */
-export async function computeCheckpointAccumulator(proof, accumulatorFrom) {
+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}`);
+    }
     const hasher = new SubtleHasher();
-    const proven = proof.treeSize1 === 0n
-        ? []
-        : await consistentRoots(hasher, proof.treeSize1 - 1n, accumulatorFrom, proof.paths);
-    const accumulator = [...proven, ...proof.rightPeaks];
-    const expected = peakMMRIndexes(proof.treeSize2 - 1n).length;
-    if (accumulator.length !== expected) {
-        throw new Error(`computed accumulator has ${accumulator.length} peaks; size ${proof.treeSize2} requires ${expected}`);
+    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}`);
     }
-    return accumulator;
+    return [...roots, ...proof.rightPeaks];
 }
 /** Detached payload the checkpoint signature covers (ADR-0046): the raw
  * concatenation of the accumulator peaks in contract order. */
@@ -116,15 +171,34 @@ export function accumulatorPayload(accumulator) {
  * Verify a retained checkpoint chain (ascending massif order) and fold out
  * the final authenticated accumulator.
  *
- * - The first link must be boundary-based from 0 (a whole-log chain), or
- *   the caller supplies `accumulatorFrom` matching its base (a suffix
- *   chain rooted in an already-trusted accumulator).
- * - Every subsequent link's base must equal the previous link's sealed
- *   size — a mismatch is the legacy (pre-FOR-410) drift signature and is
- *   permanent for that log (`legacy_chain_break`).
+ * - The first link's trusted starting size is `trustedBase?.size ?? 0n`
+ *   (base 0 for a whole-log chain) with `trustedBase?.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`.
+ * - 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
+ *   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`.
  * - 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).
+ *   roots, caller-known keys, or the label-1000 delegation path). A link
+ *   joins `links` only once its signature has verified, so on any failure
+ *   `links` is the verified prefix and never holds an accumulator nothing
+ *   attested.
  */
 export async function verifyCheckpointChain(opts) {
     const links = [];
@@ -137,8 +211,38 @@ export async function verifyCheckpointChain(opts) {
             links,
         };
     }
-    let accumulator = opts.accumulatorFrom ?? [];
-    let expectedBase = null;
+    const trustedBase = opts.trustedBase;
+    if (trustedBase !== undefined) {
+        // A size that is not a complete MMR size describes no state: the fold
+        // would silently use the largest MMR below it (`peaksBitmap` rounds
+        // down) while every link reported the supplied value as its base.
+        if (trustedBase.size < 0n ||
+            mmrSizeForLeafCount(peaksBitmap(trustedBase.size)) !== trustedBase.size) {
+            return {
+                ok: false,
+                reason: "proof_malformed",
+                at: 0,
+                detail: `trusted base size ${trustedBase.size} is not a complete MMR size`,
+                links,
+            };
+        }
+        // …and the accumulator must hold exactly the peaks that size has, which
+        // the fold otherwise only compares against the rounded-down count.
+        const basePeaks = trustedBase.size === 0n
+            ? 0
+            : peakMMRIndexes(trustedBase.size - 1n).length;
+        if (trustedBase.accumulator.length !== basePeaks) {
+            return {
+                ok: false,
+                reason: "proof_malformed",
+                at: 0,
+                detail: `trusted base accumulator has ${trustedBase.accumulator.length} peaks; size ${trustedBase.size} has ${basePeaks}`,
+                links,
+            };
+        }
+    }
+    let accumulator = trustedBase?.accumulator ?? [];
+    let expectedBase = trustedBase?.size ?? 0n;
     for (let i = 0; i < opts.checkpoints.length; i++) {
         const bytes = opts.checkpoints[i];
         let proof;
@@ -146,52 +250,43 @@ export async function verifyCheckpointChain(opts) {
             proof = checkpointConsistencyProof(bytes);
         }
         catch (err) {
+            const reason = err instanceof CheckpointSignedSizeMismatchError
+                ? "size_mismatch"
+                : err instanceof CheckpointHighSSignatureError
+                    ? "signature_malleable"
+                    : "proof_malformed";
             return {
                 ok: false,
-                reason: "proof_malformed",
+                reason,
                 at: i,
                 detail: err instanceof Error ? err.message : String(err),
                 links,
             };
         }
-        if (expectedBase === null) {
-            // First link: base 0 for a whole-log chain, else the caller's
-            // trusted accumulator must be FOR this base (peak-count check).
-            if (proof.treeSize1 !== 0n) {
-                const wanted = peakMMRIndexes(proof.treeSize1 - 1n).length;
-                if (opts.accumulatorFrom === undefined) {
-                    return {
-                        ok: false,
-                        reason: "legacy_chain_break",
-                        at: i,
-                        detail: `first checkpoint base ${proof.treeSize1} != 0 and no trusted base accumulator was supplied`,
-                        links,
-                    };
-                }
-                if (accumulator.length !== wanted) {
-                    return {
-                        ok: false,
-                        reason: "proof_malformed",
-                        at: i,
-                        detail: `trusted base accumulator has ${accumulator.length} peaks; base size ${proof.treeSize1} requires ${wanted}`,
-                        links,
-                    };
-                }
+        if (proof.treeSize1 !== expectedBase) {
+            if (i === 0) {
+                return {
+                    ok: false,
+                    reason: "size_mismatch",
+                    at: i,
+                    detail: trustedBase === undefined
+                        ? `first checkpoint declared tree-size-1 ${proof.treeSize1} != whole-log base size ${expectedBase} and no trusted base was supplied`
+                        : `first checkpoint declared tree-size-1 ${proof.treeSize1} != trusted base size ${expectedBase}`,
+                    links,
+                };
             }
-        }
-        else if (proof.treeSize1 !== expectedBase) {
             return {
                 ok: false,
-                reason: "legacy_chain_break",
+                reason: "size_mismatch",
                 at: i,
-                detail: `checkpoint ${i} base ${proof.treeSize1} != previous sealed size ${expectedBase} — ` +
-                    "pre-FOR-410 drifted chain (permanent for this log); fall back to the event scan, tile extension, or a holder cache",
+                detail: `checkpoint ${i} declared tree-size-1 ${proof.treeSize1} != the previous link's tree-size-2 ${expectedBase} — ` +
+                    "the declared origin is unsigned, so the chain is treated as not continuous",
                 links,
             };
         }
         let computed;
         try {
-            computed = await computeCheckpointAccumulator(proof, accumulator);
+            computed = await computeCheckpointAccumulator(proof, accumulator, expectedBase);
         }
         catch (err) {
             return {
@@ -203,13 +298,10 @@ export async function verifyCheckpointChain(opts) {
             };
         }
         const signatureOk = await opts.verifySignature(bytes, accumulatorPayload(computed));
-        links.push({
-            treeSize1: proof.treeSize1,
-            treeSize2: proof.treeSize2,
-            accumulator: computed,
-            signatureOk,
-        });
         if (!signatureOk) {
+            // `links` stays the verified prefix: the computed accumulator of a
+            // link whose signature did not verify is attested by nothing, so it
+            // is not handed back.
             return {
                 ok: false,
                 reason: "signature",
@@ -218,6 +310,13 @@ export async function verifyCheckpointChain(opts) {
                 links,
             };
         }
+        links.push({
+            treeSize1: proof.treeSize1,
+            treeSize2: proof.treeSize2,
+            signedTreeSize2: proof.signedTreeSize2,
+            accumulator: computed,
+            signatureOk,
+        });
         accumulator = computed;
         expectedBase = proof.treeSize2;
     }

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

@@ -0,0 +1,38 @@
+/**
+ * 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).
+ */
+/** 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[];
+};
+/**
+ * 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 declare function decodeConsistencyProofFromUnprotected(unprotected: Map<number, unknown>): DecodedConsistencyProof | null;
+//# sourceMappingURL=decode-checkpoint-consistency-proof.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,108 @@
+/**
+ * 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";
+function asBigint(v, what) {
+    // 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, what) {
+    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;
+}
+/**
+ * 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)");
+    }
+    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];
+        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];
+            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,
+        rightPeaks: asBytesArray(proof[3], "right-peaks"),
+    };
+}

package/dist/freshen-receipt.d.ts

@@ -1,17 +1,34 @@
 import { type CheckpointConsistencyProof } from "./checkpoint-chain.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;

package/dist/freshen-receipt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"freshen-receipt.d.ts","sourceRoot":"","sources":["../src/freshen-receipt.ts"],"names":[],"mappings":"AAyDA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,uBAAuB,CAAC;AAI/B,MAAM,MAAM,mBAAmB,GAAG;IAChC,iEAAiE;IACjE,eAAe,EAAE,UAAU,CAAC;IAC5B;uEACmE;IACnE,SAAS,EAAE,UAAU,CAAC;IACtB;;mFAE+E;IAC/E,iBAAiB,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACzD;iEAC6D;IAC7D,eAAe,CAAC,EAAE,UAAU,EAAE,CAAC;IAC/B;wDACoD;IACpD,qBAAqB,EAAE,UAAU,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,wEAAwE;IACxE,OAAO,EAAE,UAAU,CAAC;IACpB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AASF;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAyJ/B"}
+{"version":3,"file":"freshen-receipt.d.ts","sourceRoot":"","sources":["../src/freshen-receipt.ts"],"names":[],"mappings":"AA2DA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,uBAAuB,CAAC;AAI/B;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,iEAAiE;IACjE,eAAe,EAAE,UAAU,CAAC;IAC5B;uEACmE;IACnE,SAAS,EAAE,UAAU,CAAC;IACtB;;;mCAG+B;IAC/B,iBAAiB,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACzD;;;;;kDAK8C;IAC9C,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IAC1D;wDACoD;IACpD,qBAAqB,EAAE,UAAU,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,wEAAwE;IACxE,OAAO,EAAE,UAAU,CAAC;IACpB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AASF;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAwK/B"}