leviathan-crypto 2.0.1 → 3.0.0

package/dist/init.js

@@ -1,32 +1,98 @@
 import { loadWasm } from './loader.js';
 import { hasSIMD } from './utils.js';
-// 'keccak' is an alias for 'sha3' — same WASM binary, same instance slot
+// 'keccak' is an alias for 'sha3', same WASM binary, same instance slot
 const ALIASES = { keccak: 'sha3' };
 function resolve(mod) {
     return ALIASES[mod] ?? mod;
 }
-// Module-scope cache: one WebAssembly.Instance per canonical module
+// Per-canonical-module instance cache.
 const instances = new Map();
+// Coalesces concurrent initModule calls.
+const pending = new Map();
+// Per-module exclusivity token held by a stateful wrapper.
+const owners = new Map();
 export async function initModule(mod, source) {
     const resolved = resolve(mod);
     if (instances.has(resolved))
         return;
-    if ((resolved === 'serpent' || resolved === 'chacha20' || resolved === 'kyber') && !hasSIMD())
-        throw new Error('leviathan-crypto: serpent, chacha20, and kyber require WebAssembly SIMD — '
+    const inflight = pending.get(resolved);
+    if (inflight) {
+        await inflight;
+        return;
+    }
+    if ((resolved === 'serpent' || resolved === 'chacha20' || resolved === 'mlkem' || resolved === 'aes' || resolved === 'mldsa' || resolved === 'blake3') && !hasSIMD())
+        throw new Error('leviathan-crypto: serpent, chacha20, mlkem, aes, mldsa, and blake3 require WebAssembly SIMD, '
             + 'this runtime does not support it');
-    instances.set(resolved, await loadWasm(source));
+    const p = loadWasm(source);
+    pending.set(resolved, p);
+    try {
+        instances.set(resolved, await p);
+    }
+    finally {
+        pending.delete(resolved);
+    }
 }
 export function getInstance(mod) {
-    const inst = instances.get(resolve(mod));
+    const r = resolve(mod);
+    const inst = instances.get(r);
     if (!inst) {
         throw new Error(`leviathan-crypto: call init({ ${mod}: ... }) before using this class`);
     }
+    if (owners.has(r)) {
+        throw new Error(`leviathan-crypto: another stateful instance is using the '${r}' WASM module, `
+            + 'call dispose() on it before constructing a new one');
+    }
     return inst;
 }
 export function isInitialized(mod) {
     return instances.has(resolve(mod));
 }
-/** Reset all cached instances — for testing only */
+/**
+ * Acquire exclusive access to `mod`. Throws if another stateful instance
+ * currently holds it. Returned token must be passed to `_releaseModule`.
+ * @internal
+ */
+export function _acquireModule(mod) {
+    const r = resolve(mod);
+    if (owners.has(r))
+        throw new Error(`leviathan-crypto: another stateful instance is using the '${r}' WASM module, `
+            + 'call dispose() on it before constructing a new one');
+    const tok = Symbol(r);
+    owners.set(r, tok);
+    return tok;
+}
+/**
+ * Release exclusive access. No-op if the token doesn't match the current
+ * owner (makes dispose idempotent).
+ * @internal
+ */
+export function _releaseModule(mod, tok) {
+    const r = resolve(mod);
+    if (owners.get(r) === tok)
+        owners.delete(r);
+}
+/**
+ * True if a stateful instance currently holds the module.
+ * @internal
+ */
+export function _isModuleBusy(mod) {
+    return owners.has(resolve(mod));
+}
+/** @internal */
+export function _assertNotOwned(mod) {
+    const r = resolve(mod);
+    if (owners.has(r))
+        throw new Error(`leviathan-crypto: another stateful instance is using the '${r}' WASM module, `
+            + 'call dispose() on it before constructing a new one');
+}
+/**
+ * Reset all cached instances, for testing only. Clears `instances`, `pending`,
+ * and `owners` so tests can re-exercise module lifecycle (init, exclusivity,
+ * race) from a known-empty state.
+ * @internal
+ */
 export function _resetForTesting() {
     instances.clear();
+    pending.clear();
+    owners.clear();
 }

package/dist/keccak/embedded.js

@@ -22,6 +22,6 @@
 // src/ts/keccak/embedded.ts
 //
 // Re-exports the sha3 WASM blob under the keccak name.
-// The keccak alias shares the sha3 binary — no separate keccak.wasm exists.
+// The keccak alias shares the sha3 binary, no separate keccak.wasm exists.
 // Import via `leviathan-crypto/keccak/embedded`.
 export { WASM_GZ_BASE64 as keccakWasm } from '../embedded/sha3.js';

package/dist/keccak/index.d.ts

@@ -1,4 +1,6 @@
 import type { WasmSource } from '../wasm-source.js';
 export declare function keccakInit(source: WasmSource): Promise<void>;
 export type { WasmSource };
+export { isInitialized } from '../init.js';
 export { SHA3_224, SHA3_256, SHA3_384, SHA3_512, SHAKE128, SHAKE256 } from '../sha3/index.js';
+export { CSHAKE128, CSHAKE256, KMAC128, KMAC256, KMACXOF128, KMACXOF256 } from '../sha3/index.js';

package/dist/keccak/index.js

@@ -21,11 +21,13 @@
 //
 // src/ts/keccak/index.ts
 //
-// Keccak alias subpath — resolves to the sha3 WASM module slot.
-// Consumers who prefer the Keccak name (e.g. Kyber/ML-KEM implementations)
+// Keccak alias subpath, resolves to the sha3 WASM module slot.
+// Consumers who prefer the Keccak name (e.g. ML-KEM implementations)
 // can import from `leviathan-crypto/keccak` instead of `leviathan-crypto/sha3`.
 import { initModule } from '../init.js';
 export async function keccakInit(source) {
     return initModule('keccak', source);
 }
+export { isInitialized } from '../init.js';
 export { SHA3_224, SHA3_256, SHA3_384, SHA3_512, SHAKE128, SHAKE256 } from '../sha3/index.js';
+export { CSHAKE128, CSHAKE256, KMAC128, KMAC256, KMACXOF128, KMACXOF256 } from '../sha3/index.js';

package/dist/loader.d.ts

@@ -1,19 +1 @@
-import type { WasmSource } from './wasm-source.js';
-/**
- * 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.
- */
-export declare function decodeWasm(b64: string): Promise<Uint8Array>;
-/**
- * Compile a WASM source to a Module without instantiating.
- * Used by pool infrastructure to send compiled modules to workers.
- */
-export declare function compileWasm(source: WasmSource): Promise<WebAssembly.Module>;
-/**
- * Load a WASM module from any accepted source type.
- * The loading strategy is inferred from the argument type — no mode string.
- *
- * Throws `TypeError` for null, numeric, or unrecognised inputs.
- */
-export declare function loadWasm(source: WasmSource): Promise<WebAssembly.Instance>;
+export {};

package/dist/loader.js

@@ -1,8 +1,4 @@
 import { base64ToBytes as _b64 } from './utils.js';
-// Each WASM module gets its own fresh Memory — never shared between instances.
-function makeImports() {
-    return { env: { memory: new WebAssembly.Memory({ initial: 3, maximum: 3 }) } };
-}
 // TS 5.9 generified Uint8Array<TArrayBuffer> with default ArrayBufferLike, which
 // no longer satisfies BufferSource = ArrayBufferView<ArrayBuffer> | ArrayBuffer.
 // Convert Uint8Array to a proper ArrayBuffer before calling WebAssembly APIs.
@@ -17,14 +13,14 @@ 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.
     const compressed = _b64(b64);
-    if (!compressed)
-        throw new Error('leviathan-crypto: corrupt embedded WASM — base64 decode failed');
     const ds = new DecompressionStream('gzip');
     const writer = ds.writable.getWriter();
     const reader = ds.readable.getReader();
@@ -44,14 +40,23 @@ export async function decodeWasm(b64) {
     }
     return out;
 }
+// Cap thenable-source nesting at 3 to prevent runaway recursion.
+const MAX_THENABLE_DEPTH = 3;
 /**
  * Compile a WASM source to a Module without instantiating.
  * Used by pool infrastructure to send compiled modules to workers.
+ *
+ * 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) {
+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)
@@ -64,33 +69,22 @@ export async function compileWasm(source) {
         return source;
     if (typeof Response !== 'undefined' && source instanceof Response)
         return WebAssembly.compileStreaming(source);
-    if (source != null && typeof source.then === 'function')
-        return WebAssembly.compileStreaming(source);
-    throw new TypeError(`leviathan-crypto: invalid WasmSource — got ${source === null ? 'null' : typeof source}`);
+    if (source != null && typeof source.then === 'function') {
+        const resolved = await source;
+        return compileWasm(resolved, depth + 1);
+    }
+    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.
+ * 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) {
-    if (typeof source === 'string') {
-        if (source.length === 0)
-            throw new TypeError('leviathan-crypto: invalid WasmSource — empty string');
-        return (await WebAssembly.instantiate(toArrayBuffer(await decodeWasm(source)), makeImports())).instance;
-    }
-    if (source instanceof URL)
-        return (await WebAssembly.instantiateStreaming(fetch(source.href), makeImports())).instance;
-    if (source instanceof ArrayBuffer)
-        return (await WebAssembly.instantiate(source, makeImports())).instance;
-    if (source instanceof Uint8Array)
-        return (await WebAssembly.instantiate(toArrayBuffer(source), makeImports())).instance;
-    if (source instanceof WebAssembly.Module)
-        return WebAssembly.instantiate(source, makeImports());
-    if (typeof Response !== 'undefined' && source instanceof Response)
-        return (await WebAssembly.instantiateStreaming(source, makeImports())).instance;
-    if (source != null && typeof source.then === 'function')
-        return (await WebAssembly.instantiateStreaming(source, makeImports())).instance;
-    throw new TypeError(`leviathan-crypto: invalid WasmSource — got ${source === null ? 'null' : typeof source}`);
+    // 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;