@forestrie/receipt-verify 0.6.3 → 0.7.1

package/dist/checkpoint-chain.d.ts

@@ -0,0 +1,60 @@
+/** Draft-bryce consistency proof embedded in a v3 checkpoint. */
+export type CheckpointConsistencyProof = {
+    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 (`vdp` 396 key -2). */
+export declare function checkpointConsistencyProof(checkpointBytes: Uint8Array): CheckpointConsistencyProof;
+/**
+ * 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.
+ */
+export declare function computeCheckpointAccumulator(proof: CheckpointConsistencyProof, accumulatorFrom: Uint8Array[]): Promise<Uint8Array[]>;
+/** Detached payload the checkpoint signature covers (ADR-0046): the raw
+ * concatenation of the accumulator peaks in contract order. */
+export declare function accumulatorPayload(accumulator: Uint8Array[]): Uint8Array;
+export type CheckpointChainLink = {
+    treeSize1: bigint;
+    treeSize2: bigint;
+    accumulator: Uint8Array[];
+    signatureOk: boolean;
+};
+export type CheckpointChainResult = {
+    ok: true;
+    links: CheckpointChainLink[];
+    accumulator: Uint8Array[];
+} | {
+    ok: false;
+    reason: "empty_chain" | "legacy_chain_break" | "signature" | "proof_malformed";
+    /** Index of the offending checkpoint. */
+    at: number;
+    detail: string;
+    links: CheckpointChainLink[];
+};
+/**
+ * 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`).
+ * - 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).
+ */
+export declare function verifyCheckpointChain(opts: {
+    checkpoints: Uint8Array[];
+    verifySignature: (checkpointBytes: Uint8Array, detachedPayload: Uint8Array) => Promise<boolean>;
+    /** Trusted base accumulator for a suffix chain (absent: base must be 0). */
+    accumulatorFrom?: Uint8Array[];
+}): Promise<CheckpointChainResult>;
+//# sourceMappingURL=checkpoint-chain.d.ts.map

package/dist/checkpoint-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-chain.d.ts","sourceRoot":"","sources":["../src/checkpoint-chain.ts"],"names":[],"mappings":"AA6BA,iEAAiE;AACjE,MAAM,MAAM,0BAA0B,GAAG;IACvC,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;AA2BF,gEAAgE;AAChE,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,UAAU,GAC1B,0BAA0B,CA6C5B;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,0BAA0B,EACjC,eAAe,EAAE,UAAU,EAAE,GAC5B,OAAO,CAAC,UAAU,EAAE,CAAC,CAmBvB;AAED;+DAC+D;AAC/D,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,UAAU,CAQxE;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,GACrE;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EACF,aAAa,GACb,oBAAoB,GACpB,WAAW,GACX,iBAAiB,CAAC;IACtB,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,mBAAmB,EAAE,CAAC;CAC9B,CAAC;AAEN;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,eAAe,EAAE,CACf,eAAe,EAAE,UAAU,EAC3B,eAAe,EAAE,UAAU,KACxB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,UAAU,EAAE,CAAC;CAChC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAiGjC"}

package/dist/checkpoint-chain.js

@@ -0,0 +1,225 @@
+/**
+ * Retained-checkpoint chain verification (FOR-368 Phase 3, plan-2607-29).
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { decodeCborDeterministic } from "@forestrie/encoding";
+import { consistentRoots, peakMMRIndexes } 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);
+    }
+    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 (`vdp` 396 key -2). */
+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 proofBstr = vdpRaw.get(VDP_CONSISTENCY_PROOF_KEY);
+    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) ||
+        pathsRaw.some((p) => !Array.isArray(p) || p.some((n) => !(n instanceof Uint8Array)))) {
+        throw new Error("consistency paths must be arrays of byte strings");
+    }
+    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}`);
+    }
+    return {
+        treeSize1,
+        treeSize2,
+        paths: pathsRaw,
+        rightPeaks: asBytesArray(proof[3], "right-peaks"),
+    };
+}
+/**
+ * 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.
+ */
+export async function computeCheckpointAccumulator(proof, accumulatorFrom) {
+    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}`);
+    }
+    return accumulator;
+}
+/** Detached payload the checkpoint signature covers (ADR-0046): the raw
+ * concatenation of the accumulator peaks in contract order. */
+export function accumulatorPayload(accumulator) {
+    const out = new Uint8Array(accumulator.reduce((s, p) => s + p.length, 0));
+    let offset = 0;
+    for (const p of accumulator) {
+        out.set(p, offset);
+        offset += p.length;
+    }
+    return out;
+}
+/**
+ * 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`).
+ * - 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).
+ */
+export async function verifyCheckpointChain(opts) {
+    const links = [];
+    if (opts.checkpoints.length === 0) {
+        return {
+            ok: false,
+            reason: "empty_chain",
+            at: 0,
+            detail: "no checkpoints supplied",
+            links,
+        };
+    }
+    let accumulator = opts.accumulatorFrom ?? [];
+    let expectedBase = null;
+    for (let i = 0; i < opts.checkpoints.length; i++) {
+        const bytes = opts.checkpoints[i];
+        let proof;
+        try {
+            proof = checkpointConsistencyProof(bytes);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: "proof_malformed",
+                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,
+                    };
+                }
+            }
+        }
+        else if (proof.treeSize1 !== expectedBase) {
+            return {
+                ok: false,
+                reason: "legacy_chain_break",
+                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",
+                links,
+            };
+        }
+        let computed;
+        try {
+            computed = await computeCheckpointAccumulator(proof, accumulator);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: "proof_malformed",
+                at: i,
+                detail: err instanceof Error ? err.message : String(err),
+                links,
+            };
+        }
+        const signatureOk = await opts.verifySignature(bytes, accumulatorPayload(computed));
+        links.push({
+            treeSize1: proof.treeSize1,
+            treeSize2: proof.treeSize2,
+            accumulator: computed,
+            signatureOk,
+        });
+        if (!signatureOk) {
+            return {
+                ok: false,
+                reason: "signature",
+                at: i,
+                detail: `checkpoint ${i} signature does not cover the computed size-${proof.treeSize2} accumulator`,
+                links,
+            };
+        }
+        accumulator = computed;
+        expectedBase = proof.treeSize2;
+    }
+    return { ok: true, links, accumulator };
+}

package/dist/index.d.ts

@@ -38,4 +38,5 @@ export { findGrantLeafInMassif } from "./find-grant-leaf.js";
 export type { LocatedLeaf } from "./find-grant-leaf.js";
 /** Re-exported so callers of findGrantLeafInMassif can catch it (FOR-344). */
 export { MissingIndexError } from "@forestrie/merklelog";
+export { accumulatorPayload, checkpointConsistencyProof, computeCheckpointAccumulator, verifyCheckpointChain, type CheckpointChainLink, type CheckpointChainResult, type CheckpointConsistencyProof, } from "./checkpoint-chain.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,oFAAoF;AACpF,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,YAAY,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE;;;;GAIG;AACH,OAAO,EACL,iCAAiC,EACjC,4BAA4B,GAC7B,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,sCAAsC,EACtC,iCAAiC,GAClC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,YAAY,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,yEAAyE;AACzE,OAAO,EAAE,qCAAqC,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,iDAAiD,GAClD,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,6EAA6E;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,oEAAoE;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,oFAAoF;AACpF,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,YAAY,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE;;;;GAIG;AACH,OAAO,EACL,iCAAiC,EACjC,4BAA4B,GAC7B,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,sCAAsC,EACtC,iCAAiC,GAClC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,YAAY,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,yEAAyE;AACzE,OAAO,EAAE,qCAAqC,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,iDAAiD,GAClD,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,6EAA6E;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,oEAAoE;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,4BAA4B,EAC5B,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,GAChC,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -28,3 +28,4 @@ export { grantCommitmentHashFromGrant } from "./grant-commitment.js";
 export { findGrantLeafInMassif } from "./find-grant-leaf.js";
 /** Re-exported so callers of findGrantLeafInMassif can catch it (FOR-344). */
 export { MissingIndexError } from "@forestrie/merklelog";
+export { accumulatorPayload, checkpointConsistencyProof, computeCheckpointAccumulator, verifyCheckpointChain, } from "./checkpoint-chain.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "license": "MIT",
   "type": "module",
   "description": "Offline SCITT grant receipt verification (ADR-0045)",
@@ -29,7 +29,7 @@
   "dependencies": {
     "@noble/hashes": "^1.7.1",
     "@forestrie/encoding": "0.5.0",
-    "@forestrie/merklelog": "0.1.1"
+    "@forestrie/merklelog": "0.2.1"
   },
   "devDependencies": {
     "esbuild": "^0.24.0",

package/src/checkpoint-chain.ts

@@ -0,0 +1,298 @@
+/**
+ * Retained-checkpoint chain verification (FOR-368 Phase 3, plan-2607-29).
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { decodeCborDeterministic } from "@forestrie/encoding";
+import { consistentRoots, peakMMRIndexes } 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;
+
+/** Draft-bryce consistency proof embedded in a v3 checkpoint. */
+export type CheckpointConsistencyProof = {
+  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`, 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);
+  }
+  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 (`vdp` 396 key -2). */
+export function checkpointConsistencyProof(
+  checkpointBytes: Uint8Array,
+): CheckpointConsistencyProof {
+  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 proofBstr = (vdpRaw as Map<number, unknown>).get(
+    VDP_CONSISTENCY_PROOF_KEY,
+  );
+  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) ||
+    pathsRaw.some(
+      (p) => !Array.isArray(p) || p.some((n) => !(n instanceof Uint8Array)),
+    )
+  ) {
+    throw new Error("consistency paths must be arrays of byte strings");
+  }
+  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}`,
+    );
+  }
+  return {
+    treeSize1,
+    treeSize2,
+    paths: pathsRaw as Uint8Array[][],
+    rightPeaks: asBytesArray(proof[3], "right-peaks"),
+  };
+}
+
+/**
+ * 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.
+ */
+export async function computeCheckpointAccumulator(
+  proof: CheckpointConsistencyProof,
+  accumulatorFrom: Uint8Array[],
+): Promise<Uint8Array[]> {
+  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}`,
+    );
+  }
+  return accumulator;
+}
+
+/** Detached payload the checkpoint signature covers (ADR-0046): the raw
+ * concatenation of the accumulator peaks in contract order. */
+export function accumulatorPayload(accumulator: Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(accumulator.reduce((s, p) => s + p.length, 0));
+  let offset = 0;
+  for (const p of accumulator) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+
+export type CheckpointChainLink = {
+  treeSize1: bigint;
+  treeSize2: bigint;
+  accumulator: Uint8Array[];
+  signatureOk: boolean;
+};
+
+export type CheckpointChainResult =
+  | { ok: true; links: CheckpointChainLink[]; accumulator: Uint8Array[] }
+  | {
+      ok: false;
+      reason:
+        | "empty_chain"
+        | "legacy_chain_break"
+        | "signature"
+        | "proof_malformed";
+      /** Index of the offending checkpoint. */
+      at: number;
+      detail: string;
+      links: CheckpointChainLink[];
+    };
+
+/**
+ * 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`).
+ * - 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).
+ */
+export async function verifyCheckpointChain(opts: {
+  checkpoints: Uint8Array[];
+  verifySignature: (
+    checkpointBytes: Uint8Array,
+    detachedPayload: Uint8Array,
+  ) => Promise<boolean>;
+  /** Trusted base accumulator for a suffix chain (absent: base must be 0). */
+  accumulatorFrom?: Uint8Array[];
+}): Promise<CheckpointChainResult> {
+  const links: CheckpointChainLink[] = [];
+  if (opts.checkpoints.length === 0) {
+    return {
+      ok: false,
+      reason: "empty_chain",
+      at: 0,
+      detail: "no checkpoints supplied",
+      links,
+    };
+  }
+  let accumulator = opts.accumulatorFrom ?? [];
+  let expectedBase: bigint | null = null;
+  for (let i = 0; i < opts.checkpoints.length; i++) {
+    const bytes = opts.checkpoints[i]!;
+    let proof: CheckpointConsistencyProof;
+    try {
+      proof = checkpointConsistencyProof(bytes);
+    } catch (err) {
+      return {
+        ok: false,
+        reason: "proof_malformed",
+        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,
+          };
+        }
+      }
+    } else if (proof.treeSize1 !== expectedBase) {
+      return {
+        ok: false,
+        reason: "legacy_chain_break",
+        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",
+        links,
+      };
+    }
+    let computed: Uint8Array[];
+    try {
+      computed = await computeCheckpointAccumulator(proof, accumulator);
+    } catch (err) {
+      return {
+        ok: false,
+        reason: "proof_malformed",
+        at: i,
+        detail: err instanceof Error ? err.message : String(err),
+        links,
+      };
+    }
+    const signatureOk = await opts.verifySignature(
+      bytes,
+      accumulatorPayload(computed),
+    );
+    links.push({
+      treeSize1: proof.treeSize1,
+      treeSize2: proof.treeSize2,
+      accumulator: computed,
+      signatureOk,
+    });
+    if (!signatureOk) {
+      return {
+        ok: false,
+        reason: "signature",
+        at: i,
+        detail: `checkpoint ${i} signature does not cover the computed size-${proof.treeSize2} accumulator`,
+        links,
+      };
+    }
+    accumulator = computed;
+    expectedBase = proof.treeSize2;
+  }
+  return { ok: true, links, accumulator };
+}

package/src/index.ts

@@ -62,3 +62,12 @@ export { findGrantLeafInMassif } from "./find-grant-leaf.js";
 export type { LocatedLeaf } from "./find-grant-leaf.js";
 /** Re-exported so callers of findGrantLeafInMassif can catch it (FOR-344). */
 export { MissingIndexError } from "@forestrie/merklelog";
+export {
+  accumulatorPayload,
+  checkpointConsistencyProof,
+  computeCheckpointAccumulator,
+  verifyCheckpointChain,
+  type CheckpointChainLink,
+  type CheckpointChainResult,
+  type CheckpointConsistencyProof,
+} from "./checkpoint-chain.js";