leviathan-crypto 2.1.0 → 3.0.0

package/dist/loader.js

@@ -13,12 +13,13 @@ function toArrayBuffer(bytes) {
  * Decode a gzip+base64 embedded WASM string to raw bytes.
  * Guards against missing DecompressionStream (Node <18, non-browser runtimes).
  * Exported for pool worker launchers that decode blobs before spawning threads.
+ * @internal
  */
 export async function decodeWasm(b64) {
     if (typeof DecompressionStream === 'undefined')
-        throw new Error('leviathan-crypto: DecompressionStream not available — '
+        throw new Error('leviathan-crypto: DecompressionStream not available, '
             + 'use a URL, ArrayBuffer, or WebAssembly.Module source in this runtime');
-    // _b64 throws RangeError on invalid base64 — no nullish check required.
+    // _b64 throws RangeError on invalid base64, no nullish check required.
     const compressed = _b64(b64);
     const ds = new DecompressionStream('gzip');
     const writer = ds.writable.getWriter();
@@ -39,10 +40,7 @@ export async function decodeWasm(b64) {
     }
     return out;
 }
-// Max thenable nesting depth. A caller can pass `Promise<Response>` or even
-// `Promise<Promise<Response>>` (e.g. deferred fetch wrapped in another async
-// layer), but arbitrary `Promise<Promise<Promise<...>>>` chains would indicate
-// a caller bug — cap at 3 levels and throw a clear error beyond that.
+// Cap thenable-source nesting at 3 to prevent runaway recursion.
 const MAX_THENABLE_DEPTH = 3;
 /**
  * Compile a WASM source to a Module without instantiating.
@@ -51,13 +49,14 @@ const MAX_THENABLE_DEPTH = 3;
  * Thenable sources (Promise<Response>, Promise<ArrayBuffer>, etc.) are
  * resolved and then re-dispatched by the runtime type of the resolved value.
  * Depth is capped at `MAX_THENABLE_DEPTH` to prevent runaway recursion.
+ * @internal
  */
-export async function compileWasm(source, _depth = 0) {
-    if (_depth > MAX_THENABLE_DEPTH)
+export async function compileWasm(source, depth = 0) {
+    if (depth > MAX_THENABLE_DEPTH)
         throw new TypeError(`leviathan-crypto: thenable nesting too deep (max ${MAX_THENABLE_DEPTH})`);
     if (typeof source === 'string') {
         if (source.length === 0)
-            throw new TypeError('leviathan-crypto: invalid WasmSource — empty string');
+            throw new TypeError('leviathan-crypto: invalid WasmSource, empty string');
         return WebAssembly.compile(toArrayBuffer(await decodeWasm(source)));
     }
     if (source instanceof URL)
@@ -72,22 +71,20 @@ export async function compileWasm(source, _depth = 0) {
         return WebAssembly.compileStreaming(source);
     if (source != null && typeof source.then === 'function') {
         const resolved = await source;
-        return compileWasm(resolved, _depth + 1);
+        return compileWasm(resolved, depth + 1);
     }
-    throw new TypeError(`leviathan-crypto: invalid WasmSource — got ${source === null ? 'null' : typeof source}`);
+    throw new TypeError(`leviathan-crypto: invalid WasmSource, got ${source === null ? 'null' : typeof source}`);
 }
 /**
  * Load a WASM module from any accepted source type.
- * The loading strategy is inferred from the argument type — no mode string.
+ * The loading strategy is inferred from the argument type, no mode string.
  *
  * Throws `TypeError` for null, numeric, or unrecognised inputs, or if a
  * thenable source nests deeper than `MAX_THENABLE_DEPTH`.
+ * @internal
  */
 export async function loadWasm(source) {
-    // All leviathan-crypto WASM modules export their own memory and import
-    // nothing from the host. If a future module needs imports, they would be
-    // computed and passed here.
-    // compileWasm already handles thenable resolution + depth capping.
+    // All modules export their own memory; no host imports today.
     const mod = await compileWasm(source);
     return WebAssembly.instantiate(mod);
 }

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

@@ -0,0 +1,35 @@
+import type { Hasher, MerkleTree } from './tree.js';
+import type { MerkleStorage } from './storage.js';
+/**
+ * BLAKE3-native `Hasher` (BLAKE3 §2.3, §2.4, §2.5).
+ *
+ * Empty-tree value is `BLAKE3()`; leaves are `BLAKE3(leaf)`; internal
+ * nodes are the §2.5 parent compress over the two child CVs with the
+ * BLAKE3 IV as the starting CV and `modeFlags = 0`, `isRoot = 0`.
+ *
+ * Stateless and reentrant: each method acquires the blake3 module
+ * fresh, runs the operation, and releases. No `dispose()` is needed.
+ */
+export declare const Blake3Hasher: Hasher;
+/**
+ * Stateful BLAKE3 Merkle log. Same surface and storage discipline as
+ * `Sha256Tree`: leaf hashes and every perfect aligned internal subtree
+ * hash live in the injected `MerkleStorage`; partial right-edge subtrees
+ * are recomputed on demand.
+ *
+ * `append` is the only mutator and is the leaf-hash factory; consumers
+ * feed leaf bytes, not pre-computed leaf hashes.
+ */
+export declare class Blake3Tree 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/blake3-tree.js

@@ -0,0 +1,187 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/blake3-tree.ts
+//
+// BLAKE3 Hasher / MerkleTree. Domain separation comes from BLAKE3's own
+// §2.4 CHUNK_START / CHUNK_END / ROOT and §2.5 PARENT flags, not from
+// RFC 6962-style 0x00 / 0x01 prefix bytes (those would be redundant and
+// discard `compress4` parallelism at the internal-node layer).
+//
+// Composition:
+//   hashEmpty()                = BLAKE3()                                §2.5
+//   hashLeaf(leaf)             = BLAKE3(leaf)                            §2.4
+//   hashInternal(left, right)  = _testParentCV(left, right, IV, 0, 0)    §2.5
+//
+// Parent compress runs with modeFlags = 0 and isRoot = 0 at every level.
+// The root flag is the SignedLog layer's concern; the tree's top hash
+// exits as a plain CV, keeping `hashInternal` symmetric.
+import { BLAKE3 } from '../blake3/index.js';
+import { getInstance } from '../init.js';
+import { buildConsistencyProof, buildInclusionProof, subtreeHash, } from './proof.js';
+function getBlake3Exports() {
+    return getInstance('blake3').exports;
+}
+// ── Scratch layout for `_testParentCV` ──────────────────────────────────────
+//
+// Second-page offsets (past BUFFER_END = 26328 from
+// `src/asm/blake3/buffers.ts`) are untouched by the §2.4 chunk pipeline
+// and §2.5 tree-assembly queues; safe for caller-supplied scratch.
+const PARENT_LEFT_OFF = 65536;
+const PARENT_RIGHT_OFF = PARENT_LEFT_OFF + 32;
+const PARENT_START_OFF = PARENT_RIGHT_OFF + 32;
+const PARENT_OUT_OFF = PARENT_START_OFF + 32;
+const PARENT_SCRATCH_LEN = 128;
+// BLAKE3 §2.2 Table 1: the BLAKE3 IV equals the FIPS 180-4 SHA-256 IV,
+// packed as eight u32 little-endian words. The IV is the starting CV
+// for default-mode parent compresses (BLAKE3 §2.5, Tree Mode).
+const BLAKE3_IV_BYTES = (() => {
+    const iv32 = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+        0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    return new Uint8Array(iv32.buffer);
+})();
+const BLAKE3_OUTPUT = 32;
+const BLAKE3_WASM_MODULES = Object.freeze(['blake3']);
+// ── Blake3Hasher const ──────────────────────────────────────────────────────
+/**
+ * BLAKE3-native `Hasher` (BLAKE3 §2.3, §2.4, §2.5).
+ *
+ * Empty-tree value is `BLAKE3()`; leaves are `BLAKE3(leaf)`; internal
+ * nodes are the §2.5 parent compress over the two child CVs with the
+ * BLAKE3 IV as the starting CV and `modeFlags = 0`, `isRoot = 0`.
+ *
+ * Stateless and reentrant: each method acquires the blake3 module
+ * fresh, runs the operation, and releases. No `dispose()` is needed.
+ */
+export const Blake3Hasher = Object.freeze({
+    name: 'blake3',
+    outputSize: BLAKE3_OUTPUT,
+    wasmModules: BLAKE3_WASM_MODULES,
+    hashEmpty() {
+        // BLAKE3 §2.5, Tree Mode: the natural tree-mode root for an
+        // empty input is `BLAKE3()` itself. The chunk machine handles
+        // the single empty chunk (CHUNK_START | CHUNK_END | ROOT)
+        // internally and returns the 32-byte XOF prefix.
+        const h = new BLAKE3();
+        try {
+            return h.hash(new Uint8Array(0));
+        }
+        finally {
+            h.dispose();
+        }
+    },
+    hashLeaf(leaf) {
+        // BLAKE3 §2.4, Chunks: the chunk pipeline applies CHUNK_START,
+        // CHUNK_END, and ROOT flags internally. The caller sees a plain
+        // 32-byte hash; leaf-vs-internal domain separation is BLAKE3's
+        // job through these flag bytes, not the caller's job through
+        // prefix bytes.
+        const h = new BLAKE3();
+        try {
+            return h.hash(leaf);
+        }
+        finally {
+            h.dispose();
+        }
+    },
+    hashInternal(left, right) {
+        if (left.length !== BLAKE3_OUTPUT)
+            throw new RangeError(`Blake3Hasher.hashInternal: left must be ${BLAKE3_OUTPUT} bytes, got ${left.length}`);
+        if (right.length !== BLAKE3_OUTPUT)
+            throw new RangeError(`Blake3Hasher.hashInternal: right must be ${BLAKE3_OUTPUT} bytes, got ${right.length}`);
+        // BLAKE3 §2.5, Tree Mode: parent compress over (left || right)
+        // with IV as the starting CV and PARENT as the only flag bit
+        // (modeFlags = 0 selects default mode; isRoot = 0 keeps the
+        // node generic so callers can stack identical compresses up
+        // the tree).
+        const x = getBlake3Exports();
+        const mem = new Uint8Array(x.memory.buffer);
+        mem.set(left, PARENT_LEFT_OFF);
+        mem.set(right, PARENT_RIGHT_OFF);
+        mem.set(BLAKE3_IV_BYTES, PARENT_START_OFF);
+        try {
+            x._testParentCV(PARENT_LEFT_OFF, PARENT_RIGHT_OFF, PARENT_START_OFF, 0, 0, PARENT_OUT_OFF);
+            return mem.slice(PARENT_OUT_OFF, PARENT_OUT_OFF + BLAKE3_OUTPUT);
+        }
+        finally {
+            mem.fill(0, PARENT_LEFT_OFF, PARENT_LEFT_OFF + PARENT_SCRATCH_LEN);
+            x.wipeBuffers();
+        }
+    },
+});
+// ── Blake3Tree class ────────────────────────────────────────────────────────
+/**
+ * Stateful BLAKE3 Merkle log. Same surface and storage discipline as
+ * `Sha256Tree`: leaf hashes and every perfect aligned internal subtree
+ * hash live in the injected `MerkleStorage`; partial right-edge subtrees
+ * are recomputed on demand.
+ *
+ * `append` is the only mutator and is the leaf-hash factory; consumers
+ * feed leaf bytes, not pre-computed leaf hashes.
+ */
+export class Blake3Tree {
+    hasher = Blake3Hasher;
+    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);
+        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(`Blake3Tree.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(`Blake3Tree.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/checkpoint.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Decoded form of a c2sp.org/tlog-checkpoint body. The body shape is
+ * hash-and-algo-agnostic: `rootHash` is 32 bytes for both the SHA-256 and
+ * BLAKE3 trees Phase 7 ships, but the codec only enforces a caller-supplied
+ * length in `parseCheckpointBody`. The signed-note envelope that wraps a
+ * checkpoint is handled in `signed-note.ts`.
+ */
+export interface Checkpoint {
+    /**
+     * Log identity, non-empty UTF-8 with no Unicode spaces, plus signs, or
+     * embedded newlines. Per c2sp.org/tlog-checkpoint §Note text the origin
+     * SHOULD be a schemeless URL such as `example.com/log42`, but the codec
+     * only enforces the MUST-level structural constraints; broader URL
+     * shape policy is a caller concern.
+     */
+    readonly origin: string;
+    /**
+     * Number of leaves in the tree at signing time. Must be a non-negative
+     * safe integer; ASCII decimal serialization carries no leading zeroes
+     * (the literal `0` is the only valid string starting with `0`).
+     */
+    readonly treeSize: number;
+    /**
+     * Merkle root hash. 32 bytes for both Sha256Tree and Blake3Tree; the
+     * caller-supplied `expectedHashLen` parameter on `parseCheckpointBody`
+     * pins the exact length for a given hasher.
+     */
+    readonly rootHash: Uint8Array;
+}
+/**
+ * Serialize a Checkpoint into its canonical body bytes per
+ * c2sp.org/tlog-checkpoint §Note text. Layout:
+ *
+ *     utf8(origin) || 0x0A || utf8(decimal(treeSize)) || 0x0A
+ *         || base64(rootHash) || 0x0A
+ *
+ * Base64 uses the RFC 4648 §4 standard alphabet with `=` padding (NOT the
+ * URL-safe variant from §5 and NOT padding-stripped). The body has no
+ * leading or trailing whitespace beyond the final 0x0A; byte stability
+ * is the entire purpose of the codec, since the body bytes are what the
+ * STH signature is computed over.
+ */
+export declare function serializeCheckpointBody(c: Checkpoint): Uint8Array;
+/**
+ * Parse a canonical checkpoint body. Inverse of `serializeCheckpointBody`;
+ * round-trips byte-for-byte. Rejects extension lines, leading or trailing
+ * whitespace beyond the mandatory final 0x0A, non-newline ASCII control
+ * characters, malformed base64, and root hashes whose decoded length does
+ * not match `expectedHashLen` (default 32, the size for both Sha256Tree
+ * and Blake3Tree).
+ *
+ * The caller pins `expectedHashLen` to its hasher's `outputSize`; a future
+ * SignedLog (TASK-4) will bind this to the tree's hasher automatically.
+ *
+ * Per c2sp.org/tlog-checkpoint §Note text and c2sp.org/signed-note
+ * §Format.
+ */
+export declare function parseCheckpointBody(bytes: Uint8Array, expectedHashLen?: number): Checkpoint;

package/dist/merkle/checkpoint.js

@@ -0,0 +1,217 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/checkpoint.ts
+//
+// Canonical checkpoint body codec per c2sp.org/tlog-checkpoint (Transparency
+// Log Checkpoints) §Note text. Three newline-terminated lines: origin, tree
+// size in ASCII decimal with no leading zeroes, base64-encoded root hash.
+// The body bytes are exactly what the STH signature is computed over, so
+// producers and verifiers MUST serialize byte-for-byte identically.
+//
+// Extension lines are spec-listed as OPTIONAL and NOT RECOMMENDED. The
+// ML-DSA-44 cosignature format defined in c2sp.org/tlog-cosignature does
+// not commit to extension lines, so leviathan emits empty extension sections
+// and the parser rejects any input that contains extension lines.
+import { utf8ToBytes, bytesToUtf8, base64ToBytes, bytesToBase64 } from '../utils.js';
+// ── serialization ───────────────────────────────────────────────────────────
+const LF = 0x0a; // U+000A, the only legal line terminator in the body
+const SPACE = 0x20; // U+0020, illegal anywhere inside origin
+const PLUS = 0x2b; // U+002B, illegal anywhere inside origin
+/**
+ * Decimal-encode a non-negative integer per c2sp.org/tlog-checkpoint §Note
+ * text: ASCII digits, no leading zeroes, the literal `0` for an empty tree.
+ * `Number.toString(10)` is already in this form for non-negative safe
+ * integers, the explicit guard exists so a Number that slipped past the
+ * upstream call site does not silently produce `"1e+21"` or similar.
+ */
+function decimalTreeSize(n) {
+    if (!Number.isInteger(n) || n < 0 || n > Number.MAX_SAFE_INTEGER)
+        throw new RangeError(`serializeCheckpointBody: treeSize must be a non-negative safe integer, got ${n}`);
+    return n.toString(10);
+}
+/**
+ * Throw if `origin` violates the c2sp.org/tlog-checkpoint §Note text MUSTs:
+ * non-empty, no embedded newlines, no Unicode spaces, no plus characters.
+ * The "schemeless URL" advice from the spec is SHOULD-level and not
+ * enforced here, broader policy belongs to the application layer.
+ */
+function validateOrigin(origin) {
+    if (origin.length === 0)
+        throw new RangeError('checkpoint: origin must be non-empty');
+    // Unicode space classes are wider than ASCII 0x20; the c2sp spec text
+    // says "Unicode spaces", so we use \s which covers the same family.
+    if (/\s/.test(origin) || origin.includes('+'))
+        throw new RangeError('checkpoint: origin must not contain whitespace or plus characters');
+}
+/**
+ * Serialize a Checkpoint into its canonical body bytes per
+ * c2sp.org/tlog-checkpoint §Note text. Layout:
+ *
+ *     utf8(origin) || 0x0A || utf8(decimal(treeSize)) || 0x0A
+ *         || base64(rootHash) || 0x0A
+ *
+ * Base64 uses the RFC 4648 §4 standard alphabet with `=` padding (NOT the
+ * URL-safe variant from §5 and NOT padding-stripped). The body has no
+ * leading or trailing whitespace beyond the final 0x0A; byte stability
+ * is the entire purpose of the codec, since the body bytes are what the
+ * STH signature is computed over.
+ */
+export function serializeCheckpointBody(c) {
+    validateOrigin(c.origin);
+    const originBytes = utf8ToBytes(c.origin);
+    const sizeBytes = utf8ToBytes(decimalTreeSize(c.treeSize));
+    const rootB64 = bytesToBase64(c.rootHash);
+    const rootBytes = utf8ToBytes(rootB64);
+    const out = new Uint8Array(originBytes.length + 1 + sizeBytes.length + 1 + rootBytes.length + 1);
+    let off = 0;
+    out.set(originBytes, off);
+    off += originBytes.length;
+    out[off++] = LF;
+    out.set(sizeBytes, off);
+    off += sizeBytes.length;
+    out[off++] = LF;
+    out.set(rootBytes, off);
+    off += rootBytes.length;
+    out[off] = LF;
+    return out;
+}
+// ── parsing ─────────────────────────────────────────────────────────────────
+/**
+ * Reject ASCII control characters below U+0020 other than 0x0A. The
+ * signed-note spec at c2sp.org/signed-note §Format prohibits these in the
+ * envelope; the checkpoint body inherits the same rule because the body
+ * is the prefix of a signed-note text region.
+ */
+function hasIllegalControls(bytes) {
+    for (const b of bytes) {
+        if (b < 0x20 && b !== LF)
+            return true;
+        if (b === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * Validate that a decimal tree-size string carries no leading zeroes per
+ * c2sp.org/tlog-checkpoint §Note text. The literal `"0"` is the sole legal
+ * string starting with `0`.
+ */
+function parseTreeSize(s) {
+    if (s.length === 0)
+        throw new RangeError('checkpoint: empty tree-size line');
+    if (!/^[0-9]+$/.test(s))
+        throw new RangeError(`checkpoint: tree size '${s}' is not ASCII decimal`);
+    if (s.length > 1 && s.charCodeAt(0) === 0x30 /* '0' */)
+        throw new RangeError(`checkpoint: tree size '${s}' has a leading zero`);
+    const n = Number(s);
+    if (!Number.isInteger(n) || n < 0 || n > Number.MAX_SAFE_INTEGER)
+        throw new RangeError(`checkpoint: tree size '${s}' exceeds Number.MAX_SAFE_INTEGER`);
+    return n;
+}
+/**
+ * Parse a canonical checkpoint body. Inverse of `serializeCheckpointBody`;
+ * round-trips byte-for-byte. Rejects extension lines, leading or trailing
+ * whitespace beyond the mandatory final 0x0A, non-newline ASCII control
+ * characters, malformed base64, and root hashes whose decoded length does
+ * not match `expectedHashLen` (default 32, the size for both Sha256Tree
+ * and Blake3Tree).
+ *
+ * The caller pins `expectedHashLen` to its hasher's `outputSize`; a future
+ * SignedLog (TASK-4) will bind this to the tree's hasher automatically.
+ *
+ * Per c2sp.org/tlog-checkpoint §Note text and c2sp.org/signed-note
+ * §Format.
+ */
+export function parseCheckpointBody(bytes, expectedHashLen = 32) {
+    if (!(bytes instanceof Uint8Array))
+        throw new TypeError('parseCheckpointBody: input must be a Uint8Array');
+    if (bytes.length === 0)
+        throw new RangeError('parseCheckpointBody: empty body');
+    if (bytes[bytes.length - 1] !== LF)
+        throw new RangeError('parseCheckpointBody: body must end with U+000A');
+    if (hasIllegalControls(bytes))
+        throw new RangeError('parseCheckpointBody: body contains non-newline ASCII control characters');
+    // Collect line offsets without TextDecoder gymnastics, so an embedded
+    // newline inside the origin can be caught structurally rather than via
+    // post-hoc string checks.
+    const lineStarts = [0];
+    for (let i = 0; i < bytes.length; i++) {
+        if (bytes[i] === LF && i + 1 < bytes.length)
+            lineStarts.push(i + 1);
+    }
+    // Three mandatory lines, each newline-terminated, plus the trailing LF
+    // at end of body. Extension lines (4th line and beyond) are NOT
+    // RECOMMENDED per c2sp.org/tlog-checkpoint §Note text; the ML-DSA-44
+    // cosignature format does not sign them, so leviathan rejects them
+    // outright to keep the wire format witness-ready end to end.
+    if (lineStarts.length !== 3)
+        throw new RangeError(`parseCheckpointBody: expected exactly 3 lines, got ${lineStarts.length}`);
+    // Slice the three lines without their terminating LF.
+    const sliceLine = (idx) => {
+        const start = lineStarts[idx];
+        const end = idx + 1 < lineStarts.length ? lineStarts[idx + 1] - 1 : bytes.length - 1;
+        return bytes.subarray(start, end);
+    };
+    const originBytes = sliceLine(0);
+    const sizeBytes = sliceLine(1);
+    const rootB64Bytes = sliceLine(2);
+    if (originBytes.length === 0)
+        throw new RangeError('parseCheckpointBody: empty origin line');
+    let origin;
+    try {
+        origin = bytesToUtf8(originBytes);
+    }
+    catch {
+        throw new RangeError('parseCheckpointBody: origin is not valid UTF-8');
+    }
+    validateOrigin(origin);
+    // The byte-level scan caught most disallowed characters above; reject
+    // stray SP/PLUS bytes that slipped past the UTF-8 validation in case
+    // of a future encoding edge case.
+    for (const b of originBytes)
+        if (b === SPACE || b === PLUS)
+            throw new RangeError('parseCheckpointBody: origin contains space or plus');
+    const sizeStr = bytesToUtf8(sizeBytes);
+    const treeSize = parseTreeSize(sizeStr);
+    const rootB64 = bytesToUtf8(rootB64Bytes);
+    // RFC 4648 §4 standard alphabet, with padding. `base64ToBytes` accepts
+    // the URL-safe variant and the padding-stripped form; reject both
+    // explicitly so the codec stays strictly compliant with
+    // c2sp.org/tlog-checkpoint §Conventions. A standard padded base64
+    // string always has length divisible by 4.
+    if (/[-_]/.test(rootB64))
+        throw new RangeError('parseCheckpointBody: root hash uses URL-safe base64');
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(rootB64))
+        throw new RangeError('parseCheckpointBody: root hash is not standard base64');
+    if (rootB64.length % 4 !== 0)
+        throw new RangeError('parseCheckpointBody: root hash base64 length is not a multiple of 4 (padding missing)');
+    let rootHash;
+    try {
+        rootHash = base64ToBytes(rootB64);
+    }
+    catch {
+        throw new RangeError('parseCheckpointBody: root hash failed base64 decoding');
+    }
+    if (rootHash.length !== expectedHashLen)
+        throw new RangeError(`parseCheckpointBody: root hash length ${rootHash.length} != expected ${expectedHashLen}`);
+    return { origin, treeSize, rootHash };
+}

package/dist/merkle/index.d.ts

@@ -0,0 +1,19 @@
+export { splitPoint } from './tree.js';
+export type { Hasher, MerkleTree } from './tree.js';
+export { MemoryStorage } from './storage.js';
+export type { MerkleStorage } from './storage.js';
+export { verifyInclusionProof, verifyConsistencyProof, buildInclusionProof, buildConsistencyProof, } from './proof.js';
+export type { VerifyInclusionInput, VerifyConsistencyInput, BuildInclusionInput, BuildConsistencyInput, GetNode, } from './proof.js';
+export { Sha256Hasher, Sha256Tree } from './sha256-tree.js';
+export { Blake3Hasher, Blake3Tree } from './blake3-tree.js';
+export { serializeCheckpointBody, parseCheckpointBody } from './checkpoint.js';
+export type { Checkpoint } from './checkpoint.js';
+export { emitSignedNote, parseSignedNote, deriveKeyId, suiteFormatEnumToAlgoByte, lookupAlgoEntryByFormatEnum, lookupAlgoEntryByByte, buildCosigSignedMessage, buildCosignedMessage, emitCosigSignaturePayload, parseCosigSignaturePayload, ALGO_BYTE_ED25519_NOTE, ALGO_BYTE_ED25519_COSIG, ALGO_BYTE_MLDSA44_COSIG, } from './signed-note.js';
+export type { SignatureLine, SignedNote, AlgoEntry, MessageConstruction, SignaturePayload, CosignedMessageInput, } from './signed-note.js';
+export type { SignedTreeHead } from './sth.js';
+export { SignedLog } from './signed-log.js';
+export type { SignedLogOpts } from './signed-log.js';
+export { MerkleVerifier } from './merkle-verifier.js';
+export type { MerkleVerifierOpts } from './merkle-verifier.js';
+export { MerkleLog } from './merkle-log.js';
+export type { MerkleLogCreateOpts, MerkleLogGenerateOpts } from './merkle-log.js';

package/dist/merkle/index.js

@@ -0,0 +1,37 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/index.ts
+//
+// Public surface for the merkle log primitives. Interfaces, free
+// functions, and the SHA-256 specialisation. Hash-agnostic by design;
+// the BLAKE3 specialisation lives alongside this module and re-exports
+// the same interfaces.
+export { splitPoint } from './tree.js';
+export { MemoryStorage } from './storage.js';
+export { verifyInclusionProof, verifyConsistencyProof, buildInclusionProof, buildConsistencyProof, } from './proof.js';
+export { Sha256Hasher, Sha256Tree } from './sha256-tree.js';
+export { Blake3Hasher, Blake3Tree } from './blake3-tree.js';
+export { serializeCheckpointBody, parseCheckpointBody } from './checkpoint.js';
+export { emitSignedNote, parseSignedNote, deriveKeyId, suiteFormatEnumToAlgoByte, lookupAlgoEntryByFormatEnum, lookupAlgoEntryByByte, buildCosigSignedMessage, buildCosignedMessage, emitCosigSignaturePayload, parseCosigSignaturePayload, ALGO_BYTE_ED25519_NOTE, ALGO_BYTE_ED25519_COSIG, ALGO_BYTE_MLDSA44_COSIG, } from './signed-note.js';
+export { SignedLog } from './signed-log.js';
+export { MerkleVerifier } from './merkle-verifier.js';
+export { MerkleLog } from './merkle-log.js';