leviathan-crypto 2.0.1 → 3.0.0

package/dist/merkle/proof.js

@@ -0,0 +1,300 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/merkle/proof.ts
+//
+// Hash-agnostic, free-function proof verifiers and builders for the
+// RFC 9162 (Certificate Transparency Version 2.0) §2.1.3 / §2.1.4
+// proof formats. Every entry point takes a `Hasher`; SHA-256 and
+// BLAKE3 trees share the same wire format and the same algorithmic
+// core.
+//
+// Verifiers return boolean. Malformed-proof conditions (wrong inner /
+// border length, mismatched root) return false. Contract violations
+// (wrong-sized root for the hasher, leafIndex out of range, oldSize >
+// newSize) throw RangeError; the caller is responsible for staying
+// within the public contract.
+//
+// Builders accept a `getNode(level, index)` callback that abstracts
+// the storage layer. Memory, file, and database backends drive the
+// same builder without bringing storage details into the proof
+// algorithms.
+import { bitLen, popcount, splitPoint, trailingZeros } from './tree.js';
+import { constantTimeEqual } from '../utils.js';
+// ── Internal chaining primitives (RFC 9162 §2.1.3 / §2.1.4) ─────────────────
+/**
+ * Decompose an inclusion proof into its inner (path-up-the-tree) and
+ * border (left siblings completing the right edge) segments. The sum
+ * inner + border is the required proof length.
+ *
+ * RFC 9162 §2.1.3, Inclusion Proof Verification: the path from a leaf
+ * at index to the root of a size-n tree has bitLen(index XOR (size-1))
+ * inner levels and popcount(index >> inner) border levels.
+ */
+function decompInclProof(index, size) {
+    const inner = bitLen(index ^ (size - 1));
+    const border = popcount(Math.floor(index / 2 ** inner));
+    return { inner, border };
+}
+/**
+ * Chain `inner` proof entries up from `seed`. At level i, the bit
+ * (index >> i) & 1 selects whether the sibling is on the left or the
+ * right of `seed`. RFC 9162 §2.1.3.
+ */
+function chainInner(hasher, seed, proof, index) {
+    let acc = seed;
+    for (let i = 0; i < proof.length; i++) {
+        const bit = Math.floor(index / 2 ** i) & 1;
+        acc = bit === 0
+            ? hasher.hashInternal(acc, proof[i])
+            : hasher.hashInternal(proof[i], acc);
+    }
+    return acc;
+}
+/**
+ * Chain `inner` entries but only fold in left siblings (skip the right
+ * ones). Used by the consistency verifier to reconstruct the OLD root
+ * from the suffix shared with the inclusion proof. RFC 9162 §2.1.4.
+ */
+function chainInnerRight(hasher, seed, proof, index) {
+    let acc = seed;
+    for (let i = 0; i < proof.length; i++) {
+        const bit = Math.floor(index / 2 ** i) & 1;
+        if (bit === 1)
+            acc = hasher.hashInternal(proof[i], acc);
+    }
+    return acc;
+}
+/**
+ * Chain border entries: every remaining sibling is a left sibling
+ * along the size-1 path back to the root. RFC 9162 §2.1.3.
+ */
+function chainBorderRight(hasher, seed, proof) {
+    let acc = seed;
+    for (const h of proof)
+        acc = hasher.hashInternal(h, acc);
+    return acc;
+}
+function assertHashLen(hasher, label, h) {
+    if (h.length !== hasher.outputSize)
+        throw new RangeError(`${label}: wrong length ${h.length}, expected ${hasher.outputSize} for ${hasher.name}`);
+}
+/**
+ * RFC 9162 §2.1.3, Inclusion Proof Verification. Returns true if the
+ * proof reconstructs `rootHash` from `leafHash` at position
+ * (leafIndex, treeSize). Wrong proof length, wrong leaf-hash size, or
+ * a reconstructed root that differs from `rootHash` all return false.
+ * Contract violations (negative or out-of-range index, treeSize <= 0,
+ * wrong-sized rootHash) throw RangeError.
+ *
+ * `leafHash` is the leaf's MTH ({d_m} hashed under the leaf prefix), not
+ * the raw leaf bytes. Thin verifiers receiving a leaf over the wire
+ * should compute `hasher.hashLeaf(bytes)` before calling.
+ */
+export function verifyInclusionProof(input) {
+    const { hasher, leafHash, leafIndex, treeSize, proof, rootHash } = input;
+    if (!Number.isInteger(leafIndex) || leafIndex < 0)
+        throw new RangeError(`verifyInclusionProof: leafIndex must be a non-negative integer, got ${leafIndex}`);
+    if (!Number.isInteger(treeSize) || treeSize < 1)
+        throw new RangeError(`verifyInclusionProof: treeSize must be a positive integer, got ${treeSize}`);
+    if (leafIndex >= treeSize)
+        throw new RangeError(`verifyInclusionProof: leafIndex ${leafIndex} >= treeSize ${treeSize}`);
+    assertHashLen(hasher, 'verifyInclusionProof: rootHash', rootHash);
+    if (leafHash.length !== hasher.outputSize)
+        return false;
+    const { inner, border } = decompInclProof(leafIndex, treeSize);
+    if (proof.length !== inner + border)
+        return false;
+    for (const h of proof) {
+        if (h.length !== hasher.outputSize)
+            return false;
+    }
+    const innerProof = proof.slice(0, inner);
+    const borderProof = proof.slice(inner);
+    let res = chainInner(hasher, leafHash, innerProof, leafIndex);
+    res = chainBorderRight(hasher, res, borderProof);
+    return constantTimeEqual(res, rootHash);
+}
+/**
+ * RFC 9162 §2.1.4, Consistency Proof Verification. Returns true if
+ * `proof` proves that the size-`oldSize` tree with root `oldRoot` is a
+ * prefix of the size-`newSize` tree with root `newRoot`.
+ *
+ * Malformed-proof conditions (wrong proof length, non-empty proof when
+ * one is forbidden, mismatched old/new root reconstruction) return
+ * false. Contract violations (`oldSize > newSize`, wrong-sized root)
+ * throw RangeError; the special "consistency from empty tree" form is
+ * not part of the wire format and returns false.
+ */
+export function verifyConsistencyProof(input) {
+    const { hasher, oldSize, newSize, oldRoot, newRoot, proof } = input;
+    if (!Number.isInteger(oldSize) || oldSize < 0)
+        throw new RangeError(`verifyConsistencyProof: oldSize must be a non-negative integer, got ${oldSize}`);
+    if (!Number.isInteger(newSize) || newSize < 0)
+        throw new RangeError(`verifyConsistencyProof: newSize must be a non-negative integer, got ${newSize}`);
+    if (oldSize > newSize)
+        throw new RangeError(`verifyConsistencyProof: oldSize ${oldSize} > newSize ${newSize}`);
+    // Equal-size shortcut: RFC says the proof is empty and roots match.
+    // Byte-for-byte comparison; root hashes flow through unchanged because
+    // no reconstruction runs, so hash-length validation does not apply.
+    if (oldSize === newSize) {
+        if (proof.length > 0)
+            return false;
+        return oldRoot.length === newRoot.length && constantTimeEqual(oldRoot, newRoot);
+    }
+    // "Consistency from empty tree" is undefined: the verifier cannot
+    // recover oldRoot from no proof, so reject as malformed.
+    if (oldSize === 0)
+        return false;
+    if (proof.length === 0)
+        return false;
+    assertHashLen(hasher, 'verifyConsistencyProof: oldRoot', oldRoot);
+    assertHashLen(hasher, 'verifyConsistencyProof: newRoot', newRoot);
+    for (const h of proof) {
+        if (h.length !== hasher.outputSize)
+            return false;
+    }
+    const { inner: innerFull, border } = decompInclProof(oldSize - 1, newSize);
+    const shift = trailingZeros(oldSize);
+    const inner = innerFull - shift;
+    // If oldSize is a power of two, the verifier already knows the
+    // subtree's root (== oldRoot) and the proof omits it. Otherwise the
+    // proof's first element is the seed for both chains.
+    const oldIsPow2 = oldSize === 2 ** shift;
+    let seed;
+    let start;
+    if (oldIsPow2) {
+        seed = oldRoot;
+        start = 0;
+    }
+    else {
+        seed = proof[0];
+        start = 1;
+    }
+    const expectedLen = start + inner + border;
+    if (proof.length !== expectedLen)
+        return false;
+    const tail = proof.slice(start);
+    const innerProof = tail.slice(0, inner);
+    const borderProof = tail.slice(inner);
+    // Bit pattern for chainInnerRight: we re-derive the oldRoot from
+    // the proof. `mask` is (oldSize - 1) >> shift, the path bits above
+    // the size-`oldSize` subtree's root level.
+    const mask = Math.floor((oldSize - 1) / 2 ** shift);
+    let hash1 = chainInnerRight(hasher, seed, innerProof, mask);
+    hash1 = chainBorderRight(hasher, hash1, borderProof);
+    if (!constantTimeEqual(hash1, oldRoot))
+        return false;
+    let hash2 = chainInner(hasher, seed, innerProof, mask);
+    hash2 = chainBorderRight(hasher, hash2, borderProof);
+    return constantTimeEqual(hash2, newRoot);
+}
+/**
+ * RFC 9162 §2.1.3: build the inclusion proof for leaf `leafIndex` in
+ * a tree of size `treeSize`. The returned bytes are ordered from the
+ * lowest level upward (leaf sibling first, root-adjacent last), the
+ * order `verifyInclusionProof` consumes.
+ */
+export function buildInclusionProof(input) {
+    const { hasher, leafIndex, treeSize, getNode } = input;
+    if (!Number.isInteger(leafIndex) || leafIndex < 0)
+        throw new RangeError(`buildInclusionProof: leafIndex must be a non-negative integer, got ${leafIndex}`);
+    if (!Number.isInteger(treeSize) || treeSize < 1)
+        throw new RangeError(`buildInclusionProof: treeSize must be a positive integer, got ${treeSize}`);
+    if (leafIndex >= treeSize)
+        throw new RangeError(`buildInclusionProof: leafIndex ${leafIndex} >= treeSize ${treeSize}`);
+    return pathBuild(hasher, leafIndex, 0, treeSize, getNode);
+}
+/**
+ * RFC 9162 §2.1.4: build the consistency proof between two tree
+ * sizes. Returns an empty array when oldSize equals newSize or
+ * oldSize is zero (the verifier rejects the latter, but the builder
+ * is symmetric for inspection-time use).
+ */
+export function buildConsistencyProof(input) {
+    const { hasher, oldSize, newSize, getNode } = input;
+    if (!Number.isInteger(oldSize) || oldSize < 0)
+        throw new RangeError(`buildConsistencyProof: oldSize must be a non-negative integer, got ${oldSize}`);
+    if (!Number.isInteger(newSize) || newSize < 0)
+        throw new RangeError(`buildConsistencyProof: newSize must be a non-negative integer, got ${newSize}`);
+    if (oldSize > newSize)
+        throw new RangeError(`buildConsistencyProof: oldSize ${oldSize} > newSize ${newSize}`);
+    if (oldSize === newSize || oldSize === 0)
+        return [];
+    return subProof(hasher, oldSize, 0, newSize, true, getNode);
+}
+// RFC 9162 §2.1.4 SUBPROOF(m, D[n], b). `lo` and `hi` parameterise
+// the [lo, hi) range covered by the current subtree; `m` is the size
+// of the older subtree being witnessed.
+function subProof(hasher, m, lo, hi, b, getNode) {
+    const n = hi - lo;
+    if (m === n) {
+        // Whole subtree: emit its root only if b == false.
+        return b ? [] : [subtreeHash(hasher, lo, hi, getNode)];
+    }
+    const k = splitPoint(n);
+    if (m <= k) {
+        const sub = subProof(hasher, m, lo, lo + k, b, getNode);
+        sub.push(subtreeHash(hasher, lo + k, hi, getNode));
+        return sub;
+    }
+    const sub = subProof(hasher, m - k, lo + k, hi, false, getNode);
+    sub.push(subtreeHash(hasher, lo, lo + k, getNode));
+    return sub;
+}
+// Inclusion-proof path build: yields siblings ordered from the lowest
+// level (leaf sibling) up. Sibling = root of the other half of the
+// current subtree.
+function pathBuild(hasher, leafIndex, lo, hi, getNode) {
+    if (hi - lo <= 1)
+        return [];
+    const k = splitPoint(hi - lo);
+    if (leafIndex - lo < k) {
+        const sub = pathBuild(hasher, leafIndex, lo, lo + k, getNode);
+        sub.push(subtreeHash(hasher, lo + k, hi, getNode));
+        return sub;
+    }
+    const sub = pathBuild(hasher, leafIndex, lo + k, hi, getNode);
+    sub.push(subtreeHash(hasher, lo, lo + k, getNode));
+    return sub;
+}
+/**
+ * RFC 9162 §2.1.1 MTH(D[lo:hi]). For a perfect aligned subtree the
+ * value is stored at (level, index); otherwise the value is the
+ * internal hash of the perfect left half and the recursive right
+ * half. Visible to the tree class so `rootHash()` can share the
+ * recursion with the builders.
+ *
+ * @internal
+ */
+export function subtreeHash(hasher, lo, hi, getNode) {
+    const n = hi - lo;
+    if (n === 1)
+        return getNode(0, lo);
+    const k = splitPoint(n);
+    if (k === n / 2 && (lo % n) === 0) {
+        // Perfect aligned subtree: a stored internal node.
+        return getNode(bitLen(n) - 1, Math.floor(lo / n));
+    }
+    const left = subtreeHash(hasher, lo, lo + k, getNode);
+    const right = subtreeHash(hasher, lo + k, hi, getNode);
+    return hasher.hashInternal(left, right);
+}

package/dist/merkle/sha256-tree.d.ts

@@ -0,0 +1,33 @@
+import type { Hasher, MerkleTree } from './tree.js';
+import type { MerkleStorage } from './storage.js';
+/**
+ * RFC 9162 §2.1.1, Merkle Hash Trees. The CT-flavoured SHA-256 hash
+ * function: empty-tree value `MTH({}) = SHA-256()`, leaf prefix `0x00`,
+ * internal-node prefix `0x01`.
+ *
+ * Stateless and reentrant: each method takes the sha2 module fresh,
+ * runs SHA-256 once, and releases. No `dispose()` is needed.
+ */
+export declare const Sha256Hasher: Hasher;
+/**
+ * Stateful SHA-256 Merkle log. Stores leaf hashes and every perfect
+ * aligned internal subtree's hash via the injected `MerkleStorage`;
+ * partial right-edge subtrees are recomputed on demand from the
+ * stored perfect subtrees.
+ *
+ * Constructed empty. `append` is the only mutator and is the leaf-hash
+ * factory; consumers feed leaf bytes, not pre-computed leaf hashes.
+ */
+export declare class Sha256Tree implements MerkleTree {
+    readonly hasher: Hasher;
+    private readonly storage;
+    constructor(storage: MerkleStorage);
+    size(): number;
+    rootHash(): Uint8Array;
+    append(leafBytes: Uint8Array): {
+        leafIndex: number;
+        leafHash: Uint8Array;
+    };
+    getInclusionProof(leafIndex: number, treeSize?: number): Uint8Array[];
+    getConsistencyProof(oldSize: number, newSize: number): Uint8Array[];
+}

package/dist/merkle/sha256-tree.js

@@ -0,0 +1,145 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/merkle/sha256-tree.ts
+//
+// SHA-256 specialisation of the Hasher / MerkleTree interfaces. Wraps
+// the existing `SHA256` class from the sha2 module under the RFC 9162
+// (Certificate Transparency Version 2.0) §2.1.1 leaf and internal-node
+// domain separators.
+//
+// Per-call WASM lifecycle: every Sha256Hasher method instantiates a
+// fresh SHA256 inside a try / finally + dispose pattern. There is no
+// long-lived module ownership; concurrent users are serialised by the
+// per-module exclusivity guard in the sha2 substrate. This mirrors
+// the SignatureSuite factories under src/ts/sign/suites/.
+import { SHA256 } from '../sha2/index.js';
+import { buildConsistencyProof, buildInclusionProof, subtreeHash, } from './proof.js';
+// ── Sha256Hasher const ──────────────────────────────────────────────────────
+const SHA256_OUTPUT = 32;
+const LEAF_PREFIX = new Uint8Array([0x00]);
+const INTERNAL_PREFIX = new Uint8Array([0x01]);
+const SHA256_WASM_MODULES = Object.freeze(['sha2']);
+function sha256Hash(input) {
+    const h = new SHA256();
+    try {
+        return h.hash(input);
+    }
+    finally {
+        h.dispose();
+    }
+}
+/**
+ * RFC 9162 §2.1.1, Merkle Hash Trees. The CT-flavoured SHA-256 hash
+ * function: empty-tree value `MTH({}) = SHA-256()`, leaf prefix `0x00`,
+ * internal-node prefix `0x01`.
+ *
+ * Stateless and reentrant: each method takes the sha2 module fresh,
+ * runs SHA-256 once, and releases. No `dispose()` is needed.
+ */
+export const Sha256Hasher = Object.freeze({
+    name: 'sha256',
+    outputSize: SHA256_OUTPUT,
+    wasmModules: SHA256_WASM_MODULES,
+    hashEmpty() {
+        // RFC 9162 §2.1.1: MTH({}) is the hash of an empty bit-string.
+        return sha256Hash(new Uint8Array(0));
+    },
+    hashLeaf(leaf) {
+        // RFC 9162 §2.1.1: MTH({d}) = HASH(0x00 || d). The 0x00 prefix
+        // is the domain separator that prevents an internal-node hash
+        // from being mistaken for a leaf hash.
+        const buf = new Uint8Array(1 + leaf.length);
+        buf.set(LEAF_PREFIX, 0);
+        buf.set(leaf, 1);
+        return sha256Hash(buf);
+    },
+    hashInternal(left, right) {
+        // RFC 9162 §2.1.1: MTH(D[n]) = HASH(0x01 || MTH(D[0:k]) ||
+        // MTH(D[k:n])). The 0x01 prefix is the other half of the
+        // second-preimage-resistance domain separator.
+        const buf = new Uint8Array(1 + left.length + right.length);
+        buf.set(INTERNAL_PREFIX, 0);
+        buf.set(left, 1);
+        buf.set(right, 1 + left.length);
+        return sha256Hash(buf);
+    },
+});
+// ── Sha256Tree class ────────────────────────────────────────────────────────
+/**
+ * Stateful SHA-256 Merkle log. Stores leaf hashes and every perfect
+ * aligned internal subtree's hash via the injected `MerkleStorage`;
+ * partial right-edge subtrees are recomputed on demand from the
+ * stored perfect subtrees.
+ *
+ * Constructed empty. `append` is the only mutator and is the leaf-hash
+ * factory; consumers feed leaf bytes, not pre-computed leaf hashes.
+ */
+export class Sha256Tree {
+    hasher = Sha256Hasher;
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    size() {
+        return this.storage.size();
+    }
+    rootHash() {
+        const n = this.storage.size();
+        if (n === 0)
+            return this.hasher.hashEmpty();
+        const getNode = (level, index) => this.storage.getNode(level, index);
+        return subtreeHash(this.hasher, 0, n, getNode);
+    }
+    append(leafBytes) {
+        const leafIndex = this.storage.size();
+        const leafHash = this.hasher.hashLeaf(leafBytes);
+        this.storage.appendLeaf(leafIndex, leafHash);
+        // Propagate completed internal nodes up the right edge. RFC 9162
+        // §2.1.1 makes the tree fill left-to-right; whenever a node lands
+        // at an odd index its left sibling already exists, so the parent
+        // becomes computable for free.
+        let level = 0;
+        let idx = leafIndex;
+        while ((idx & 1) === 1) {
+            const left = this.storage.getNode(level, idx - 1);
+            const right = this.storage.getNode(level, idx);
+            const parent = this.hasher.hashInternal(left, right);
+            this.storage.putNode(level + 1, idx >>> 1, parent);
+            idx = idx >>> 1;
+            level++;
+        }
+        return { leafIndex, leafHash };
+    }
+    getInclusionProof(leafIndex, treeSize) {
+        const ts = treeSize ?? this.storage.size();
+        if (!Number.isInteger(ts) || ts < 1 || ts > this.storage.size())
+            throw new RangeError(`Sha256Tree.getInclusionProof: treeSize ${ts} out of range [1, ${this.storage.size()}]`);
+        const getNode = (level, index) => this.storage.getNode(level, index);
+        return buildInclusionProof({ hasher: this.hasher, leafIndex, treeSize: ts, getNode });
+    }
+    getConsistencyProof(oldSize, newSize) {
+        if (!Number.isInteger(newSize) || newSize < 0 || newSize > this.storage.size())
+            throw new RangeError(`Sha256Tree.getConsistencyProof: newSize ${newSize} out of range [0, ${this.storage.size()}]`);
+        const getNode = (level, index) => this.storage.getNode(level, index);
+        return buildConsistencyProof({ hasher: this.hasher, oldSize, newSize, getNode });
+    }
+}

package/dist/merkle/signed-log.d.ts

@@ -0,0 +1,156 @@
+import type { SignedTreeHead } from './sth.js';
+import type { MerkleTree } from './tree.js';
+import type { SignatureSuite } from '../sign/types.js';
+/**
+ * Constructor options for `SignedLog`.
+ */
+export interface SignedLogOpts<S extends SignatureSuite> {
+    /** Underlying Merkle tree, holds the stateful append + proof surface. */
+    tree: MerkleTree;
+    /**
+     * Signature suite. Must have an entry in the C2SP cosignature
+     * algorithm-byte registry (currently `Ed25519Suite` and
+     * `MlDsa44Suite`); other suites throw `SigningError`.
+     */
+    suite: S;
+    /**
+     * Log identity, the first line of every checkpoint body. Validated
+     * at construction (non-empty, no whitespace, no plus characters)
+     * per c2sp.org/tlog-checkpoint §Note text.
+     */
+    origin: string;
+    /**
+     * Signing key, exactly `suite.skSize` bytes. The SignedLog stores
+     * a private copy; `dispose()` zeroes that copy. The caller's view
+     * of the buffer is left untouched.
+     */
+    signingKey: Uint8Array;
+    /**
+     * Public key, exactly `suite.pkSize` bytes. Used to derive the
+     * 4-byte keyId stamped on every emitted signature line and to
+     * match incoming signature lines during verify.
+     */
+    pubkey: Uint8Array;
+}
+/**
+ * Signed transparency log substrate. Combines a `MerkleTree` with a
+ * registered cosignature `SignatureSuite` and an origin string;
+ * exposes append, proof, and cosignature sign / verify operations.
+ *
+ * Per-call WASM lifecycle is enforced by the suite itself (see the
+ * SignatureSuite factories under `src/ts/sign/suites/`). `SignedLog`
+ * does not wrap additional try/finally around `suite.sign` /
+ * `suite.verify` because the suite already does. Internally the
+ * SignedLog owns a private copy of the signing key wiped by
+ * `dispose()`.
+ */
+export declare class SignedLog<S extends SignatureSuite> {
+    readonly tree: MerkleTree;
+    readonly suite: S;
+    readonly origin: string;
+    readonly pubkey: Uint8Array;
+    readonly wasmModules: readonly string[];
+    private readonly _algoEntry;
+    private readonly _keyId;
+    private _signingKey;
+    private _disposed;
+    constructor(opts: SignedLogOpts<S>);
+    /**
+     * Append a leaf to the underlying tree and return the new leaf's
+     * index, hash, and inclusion proof against the post-append tree size.
+     */
+    append(leafBytes: Uint8Array): {
+        leafIndex: number;
+        leafHash: Uint8Array;
+        inclusionProof: Uint8Array[];
+    };
+    size(): number;
+    rootHash(): Uint8Array;
+    getInclusionProof(leafIndex: number, treeSize?: number): Uint8Array[];
+    getConsistencyProof(oldSize: number, newSize: number): Uint8Array[];
+    /**
+     * Issue a cosignature over the current checkpoint and emit the
+     * signed-note envelope per c2sp.org/signed-note §Format. The
+     * signature line carries the `timestamped_signature` payload
+     * from c2sp.org/tlog-cosignature §Format; the bytes the suite
+     * signs are dispatched on the algorithm's
+     * `messageConstruction`:
+     *
+     *   - `'cosig'`             → `buildCosigSignedMessage(body, ts)`
+     *                              (Ed25519, §"Ed25519 signed message")
+     *   - `'cosigned-message'`  → `buildCosignedMessage(...)`
+     *                              (ML-DSA-44, §"ML-DSA-44 signed message")
+     *
+     * `timestamp` defaults to current wall-clock POSIX seconds. The
+     * c2sp.org/tlog-witness `add-checkpoint` rule mandates a non-zero
+     * timestamp on production cosignatures; `0` is accepted by this
+     * function for test reproducibility but witness verifiers will
+     * reject envelopes that carry it. Tests and vector generators
+     * pass an explicit value to lock byte stability.
+     */
+    signCheckpoint(opts?: {
+        timestamp?: number;
+    }): Uint8Array;
+    /**
+     * Parse a signed-note envelope into the structured `SignedTreeHead`
+     * form per c2sp.org/signed-note §Format. Surfaces the body's
+     * decoded `Checkpoint`, the signature lines that survived the
+     * permissive signed-note parse, and the primary log cosignature's
+     * POSIX-seconds timestamp (extracted via
+     * `parseCosigSignaturePayload` on the line whose keyId matches
+     * this log's pubkey-derived keyId).
+     *
+     * If no signature line matches, `timestamp` is reported as 0. The
+     * field is informational at parse time; cryptographic verification
+     * lives in `verifyCheckpoint`. Throws `RangeError` on whole-envelope
+     * structural failure (the parseSignedNote / parseCheckpointBody
+     * contract); does not throw on signature line content issues.
+     */
+    parseCheckpoint(bytes: Uint8Array): SignedTreeHead;
+    /**
+     * Verify a signed-note envelope against this SignedLog's origin,
+     * pubkey, suite, and tree hasher. Returns `true` iff the envelope
+     * parses, carries a signature line whose keyId matches this log's
+     * pubkey-derived keyId, the `timestamped_signature` payload on
+     * that line decodes cleanly, and the signature verifies under
+     * `suite.verify` over the cosignature signed message reconstructed
+     * with the parsed timestamp.
+     *
+     * Returns `false` on every soft-fail mode: wrong origin, wrong
+     * root-hash length, no matching keyId line, malformed payload,
+     * signature failure. Throws only on this log's own disposed
+     * state; never on envelope content (envelope content is public,
+     * so timing distinctions on its content are not security-sensitive).
+     *
+     * The keyId comparison uses `constantTimeEqual` for hygiene around
+     * key-material-adjacent state; the origin and root-hash-length
+     * early returns are intentional non-constant-time exits since
+     * both fields are public per the spec.
+     */
+    verifyCheckpoint(bytes: Uint8Array): boolean;
+    /**
+     * Zero the stored signing-key copy. Idempotent. Subsequent calls
+     * to any public method throw.
+     */
+    dispose(): void;
+    private _assertNotDisposed;
+    /**
+     * Dispatch the cosignature signed-message construction on the
+     * algorithm-byte registry entry's `messageConstruction`. The
+     * `body` argument is the canonical checkpoint body from
+     * `serializeCheckpointBody`, ending in 0x0A.
+     *
+     *   'cosig'             c2sp.org/tlog-cosignature §"Ed25519 signed
+     *                       message". The full envelope body is
+     *                       embedded verbatim after the
+     *                       cosignature/v1 + time prefix.
+     *
+     *   'cosigned-message'  c2sp.org/tlog-cosignature §"ML-DSA-44
+     *                       signed message". The body is decomposed
+     *                       into origin, tree size, and root hash;
+     *                       cosigner_name == origin (Phase 7 logs sign
+     *                       their own checkpoints); start == 0; end ==
+     *                       tree size; hash == root hash.
+     */
+    private _buildSignedMessage;
+}