leviathan-crypto 2.1.0 → 3.0.0

package/dist/merkle/merkle-verifier.js

@@ -0,0 +1,296 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/merkle-verifier.ts
+//
+// `MerkleVerifier`, verify-only normie surface. Wire format per
+// c2sp.org/signed-note §Format, c2sp.org/tlog-checkpoint §Note text,
+// and c2sp.org/tlog-cosignature §Format.
+import { isInitialized } from '../init.js';
+import { MerkleLogError, MerkleCodecError } from '../errors.js';
+import { constantTimeEqual } from '../utils.js';
+import { parseSignedNote, lookupAlgoEntryByFormatEnum, deriveKeyId, buildCosigSignedMessage, buildCosignedMessage, parseCosigSignaturePayload, } from './signed-note.js';
+import { parseCheckpointBody } from './checkpoint.js';
+import { verifyInclusionProof, verifyConsistencyProof } from './proof.js';
+import { Sha256Hasher } from './sha256-tree.js';
+import { Blake3Hasher } from './blake3-tree.js';
+// Empty ctx for suite.verify; domain separation lives in the
+// cosignature signed-message construction (cosignature/v1 prefix for
+// Ed25519, cosigned_message label for ML-DSA-44) per
+// c2sp.org/tlog-cosignature §Format.
+const EMPTY_CTX = new Uint8Array(0);
+const SHA2_MODULE = 'sha2';
+/**
+ * Trust-anchored verifier for c2sp.org/tlog-checkpoint envelopes.
+ * Takes a fixed log identity at construction and exposes three verify
+ * methods (`verifyCheckpoint`, `verifyInclusion`, `verifyConsistency`)
+ * that return `boolean`.
+ *
+ * Construction is the only place this class throws; every verify path
+ * returns `false` on any failure mode including malformed bytes,
+ * tampered envelopes, wrong origin, wrong leaf, and signature failure.
+ * The convention matches `SignatureSuite.verify` and lets normie
+ * callers write a single `if (!verifier.verifyX(...)) reject()` line
+ * per check without a try / catch.
+ */
+export class MerkleVerifier {
+    origin;
+    pubkey;
+    hasher;
+    suite;
+    _algoEntry;
+    _keyId;
+    constructor(opts) {
+        const { origin, pubkey, hashing, suite } = opts;
+        if (typeof origin !== 'string' || origin.length === 0)
+            throw new MerkleLogError('origin-invalid', 'MerkleVerifier: origin must be a non-empty string');
+        // c2sp.org/tlog-checkpoint §Note text MUSTs, mirrored from
+        // `SignedLog`'s constructor: the origin is the first body line
+        // and may not contain whitespace or plus characters.
+        if (/\s/.test(origin) || origin.includes('+'))
+            throw new MerkleLogError('origin-invalid', 'MerkleVerifier: origin must not contain whitespace or plus characters');
+        if (!(pubkey instanceof Uint8Array))
+            throw new MerkleLogError('pubkey-size', 'MerkleVerifier: pubkey must be a Uint8Array');
+        const hasher = resolveHasher(hashing);
+        const algoEntry = lookupAlgoEntryByFormatEnum(suite.formatEnum);
+        if (algoEntry === undefined)
+            throw new MerkleLogError('unsupported-suite', `MerkleVerifier: suite '${suite.formatName}' (formatEnum 0x${suite.formatEnum
+                .toString(16)
+                .padStart(2, '0')}) has no c2sp.org/tlog-cosignature §Format algorithm byte; `
+                + 'use Ed25519Suite or MlDsa44Suite, or open an issue for a newly C2SP-registered suite');
+        if (pubkey.length !== suite.pkSize)
+            throw new MerkleLogError('pubkey-size', `MerkleVerifier: pubkey length ${pubkey.length} != suite.pkSize ${suite.pkSize}`);
+        // Same modules `SignedLog` requires: the suite's modules, the
+        // hasher's module, and sha2 for `deriveKeyId`. Constructor-time
+        // check so a verifier built before `init()` fails at construction
+        // rather than on first `verifyCheckpoint` call.
+        assertModulesInitialized([
+            ...suite.wasmModules,
+            ...hasher.wasmModules,
+            SHA2_MODULE,
+        ]);
+        this.origin = origin;
+        this.pubkey = pubkey.slice();
+        this.hasher = hasher;
+        this.suite = suite;
+        this._algoEntry = algoEntry;
+        this._keyId = deriveKeyId(origin, algoEntry.algoByte, this.pubkey);
+    }
+    /**
+     * Verify a signed-note envelope against this verifier's identity.
+     * Returns `true` iff the envelope parses, the body's origin equals
+     * the constructor origin, the body's root-hash length equals the
+     * hasher's `outputSize`, a signature line's keyId equals the
+     * pubkey-derived keyId, the `timestamped_signature` payload on
+     * that line decodes cleanly, and `suite.verify` accepts the
+     * reconstructed cosignature signed message.
+     *
+     * Returns `false` on every other path. Never throws on envelope
+     * content.
+     */
+    verifyCheckpoint(envelopeBytes) {
+        const parsed = this._parseAndVerify(envelopeBytes);
+        return parsed !== null;
+    }
+    /**
+     * Verify a leaf's inclusion in the tree committed by an envelope.
+     * Runs `verifyCheckpoint` first; on failure returns `false`
+     * without examining the proof. On success, hashes `leafBytes`
+     * with the verifier's `Hasher` and calls `verifyInclusionProof`
+     * against the body's `treeSize` and `rootHash` per RFC 9162 §2.1.3.
+     *
+     * The "verify checkpoint first" ordering is the security-critical
+     * step: the proof is bound to the root hash inside the signed body,
+     * so trusting the proof before checking the signature would let any
+     * forger pair a malicious proof with their own root.
+     */
+    verifyInclusion(opts) {
+        const parsed = this._parseAndVerify(opts.envelopeBytes);
+        if (parsed === null)
+            return false;
+        if (!(opts.leafBytes instanceof Uint8Array))
+            return false;
+        if (!Number.isInteger(opts.leafIndex) || opts.leafIndex < 0)
+            return false;
+        if (opts.leafIndex >= parsed.treeSize)
+            return false;
+        if (!Array.isArray(opts.proof))
+            return false;
+        for (const h of opts.proof)
+            if (!(h instanceof Uint8Array))
+                return false;
+        // RFC 9162 §2.1.1: leaf-hash domain separation happens here;
+        // the proof verifier expects the MTH({d}) of the leaf, not the
+        // raw leaf bytes. Computing it locally rather than accepting a
+        // caller-supplied leaf hash closes the "we trust the proof
+        // because we trust the leaf hash the caller gave us" gap.
+        const leafHash = this.hasher.hashLeaf(opts.leafBytes);
+        try {
+            return verifyInclusionProof({
+                hasher: this.hasher,
+                leafHash,
+                leafIndex: opts.leafIndex,
+                treeSize: parsed.treeSize,
+                proof: opts.proof,
+                rootHash: parsed.rootHash,
+            });
+        }
+        catch {
+            // `verifyInclusionProof` throws on a wrong-sized rootHash or
+            // out-of-range leafIndex. Convert to a verify-false: the
+            // normie surface keeps a single failure mode.
+            return false;
+        }
+    }
+    /**
+     * Verify that the tree committed by `oldEnvelopeBytes` is a prefix
+     * of the tree committed by `newEnvelopeBytes`. Both envelopes must
+     * verify under this verifier's identity; if either fails, returns
+     * `false`. On success, calls `verifyConsistencyProof` per
+     * RFC 9162 §2.1.4 against the two sizes and roots.
+     */
+    verifyConsistency(opts) {
+        const oldParsed = this._parseAndVerify(opts.oldEnvelopeBytes);
+        if (oldParsed === null)
+            return false;
+        const newParsed = this._parseAndVerify(opts.newEnvelopeBytes);
+        if (newParsed === null)
+            return false;
+        if (!Array.isArray(opts.proof))
+            return false;
+        for (const h of opts.proof)
+            if (!(h instanceof Uint8Array))
+                return false;
+        try {
+            return verifyConsistencyProof({
+                hasher: this.hasher,
+                oldSize: oldParsed.treeSize,
+                newSize: newParsed.treeSize,
+                oldRoot: oldParsed.rootHash,
+                newRoot: newParsed.rootHash,
+                proof: opts.proof,
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── internal ────────────────────────────────────────────────────────
+    /**
+     * Parse a signed-note envelope, verify the cosignature, and return
+     * the decoded `Checkpoint`. Returns `null` on any failure mode:
+     * malformed envelope, malformed body, wrong origin, wrong root-hash
+     * length, no matching keyId line, malformed payload, signature
+     * failure. Keyed-ID comparison uses `constantTimeEqual` for hygiene
+     * around key-material-adjacent state.
+     */
+    _parseAndVerify(bytes) {
+        if (!(bytes instanceof Uint8Array))
+            return null;
+        let env;
+        try {
+            env = parseSignedNote(bytes);
+        }
+        catch {
+            return null;
+        }
+        let checkpoint;
+        try {
+            checkpoint = parseCheckpointBody(env.body, this.hasher.outputSize);
+        }
+        catch {
+            return null;
+        }
+        if (checkpoint.origin !== this.origin)
+            return null;
+        if (checkpoint.rootHash.length !== this.hasher.outputSize)
+            return null;
+        const matching = env.signatures.find(s => s.keyId.length === this._keyId.length
+            && constantTimeEqual(s.keyId, this._keyId));
+        if (!matching)
+            return null;
+        let payload;
+        try {
+            payload = parseCosigSignaturePayload(matching.signature, this._algoEntry.sigSize);
+        }
+        catch (err) {
+            if (err instanceof MerkleCodecError)
+                return null;
+            throw err;
+        }
+        let signedMessage;
+        try {
+            signedMessage = this._buildSignedMessage(env.body, payload.timestamp, checkpoint);
+        }
+        catch {
+            return null;
+        }
+        const ok = this.suite.verify(this.pubkey, signedMessage, payload.signature, EMPTY_CTX);
+        return ok ? checkpoint : null;
+    }
+    /**
+     * Dispatch cosignature signed-message construction on the algorithm
+     * registry entry's `messageConstruction`. Mirrors `SignedLog`'s
+     * dispatch so producer and verifier always agree on the bytes the
+     * suite verifies against.
+     *
+     *   '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". cosigner_name and
+     *                       log_origin both equal the checkpoint origin
+     *                       for a log's self-cosignature; start == 0;
+     *                       end == treeSize; hash == rootHash.
+     */
+    _buildSignedMessage(body, timestamp, cp) {
+        if (this._algoEntry.messageConstruction === 'cosig')
+            return buildCosigSignedMessage(body, timestamp);
+        return buildCosignedMessage({
+            cosignerName: this.origin,
+            timestamp,
+            logOrigin: this.origin,
+            start: 0,
+            end: cp.treeSize,
+            hash: cp.rootHash,
+        });
+    }
+}
+function resolveHasher(hashing) {
+    if (hashing === 'sha256')
+        return Sha256Hasher;
+    if (hashing === 'blake3')
+        return Blake3Hasher;
+    throw new MerkleLogError('unsupported-hashing', `MerkleVerifier: hashing must be 'sha256' or 'blake3', got '${hashing}'`);
+}
+function assertModulesInitialized(modules) {
+    const seen = new Set();
+    for (const mod of modules) {
+        if (seen.has(mod))
+            continue;
+        seen.add(mod);
+        if (!isInitialized(mod))
+            throw new MerkleLogError('module-not-initialized', `MerkleVerifier: WASM module '${mod}' is not initialized; `
+                + 'call init() with the appropriate sources before constructing MerkleVerifier');
+    }
+}

package/dist/merkle/proof.d.ts

@@ -0,0 +1,70 @@
+import type { Hasher } from './tree.js';
+export interface VerifyInclusionInput {
+    hasher: Hasher;
+    leafHash: Uint8Array;
+    leafIndex: number;
+    treeSize: number;
+    proof: readonly Uint8Array[];
+    rootHash: Uint8Array;
+}
+/**
+ * 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 declare function verifyInclusionProof(input: VerifyInclusionInput): boolean;
+export interface VerifyConsistencyInput {
+    hasher: Hasher;
+    oldSize: number;
+    newSize: number;
+    oldRoot: Uint8Array;
+    newRoot: Uint8Array;
+    proof: readonly Uint8Array[];
+}
+/**
+ * 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 declare function verifyConsistencyProof(input: VerifyConsistencyInput): boolean;
+/** Callback the builders use to read the tree without knowing how it is stored. */
+export type GetNode = (level: number, index: number) => Uint8Array;
+export interface BuildInclusionInput {
+    hasher: Hasher;
+    leafIndex: number;
+    treeSize: number;
+    getNode: GetNode;
+}
+/**
+ * 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 declare function buildInclusionProof(input: BuildInclusionInput): Uint8Array[];
+export interface BuildConsistencyInput {
+    hasher: Hasher;
+    oldSize: number;
+    newSize: number;
+    getNode: 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 declare function buildConsistencyProof(input: BuildConsistencyInput): Uint8Array[];

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);
+}