leviathan-crypto 2.0.1 → 3.0.0

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';

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

@@ -0,0 +1,130 @@
+import type { Hasher } from './tree.js';
+import type { SignatureSuite } from '../sign/types.js';
+/**
+ * Options for `MerkleLog.create`. The signing key and pubkey are
+ * caller-supplied: `MerkleLog` does not persist keys. For ephemeral
+ * use cases the companion factory `MerkleLog.generate` materialises a
+ * fresh keypair via `suite.keygen()` and returns the keypair to the
+ * caller so it can be persisted externally.
+ */
+export interface MerkleLogCreateOpts {
+    /**
+     * Log identity, the first line of every checkpoint body. Validated
+     * by the inner `SignedLog` (non-empty, no whitespace, no plus
+     * characters) per c2sp.org/tlog-checkpoint §Note text.
+     */
+    readonly origin: string;
+    /** Signing key. Length must equal `suite.skSize`. */
+    readonly signingKey: Uint8Array;
+    /** Public key. Length must equal `suite.pkSize`. */
+    readonly pubkey: Uint8Array;
+    /**
+     * Hash function the tree uses. `'sha256'` (default) resolves to
+     * `Sha256Tree`, `'blake3'` resolves to `Blake3Tree`. SHA-256 is the
+     * C2SP-interop choice; the BLAKE3 specialisation is for callers who
+     * already invest in BLAKE3 elsewhere in their stack.
+     */
+    readonly hashing?: 'sha256' | 'blake3';
+    /**
+     * Cosignature signature suite. Defaults to `MlDsa44Suite` per the
+     * project's PQ-first principle and c2sp.org/tlog-checkpoint
+     * §Format's MUST/SHOULD wording on ML-DSA-44. Must be registered
+     * in the c2sp.org/tlog-cosignature §Format algorithm-byte registry;
+     * other suites raise `MerkleLogError('unsupported-suite')`.
+     */
+    readonly suite?: SignatureSuite;
+}
+/**
+ * Options for `MerkleLog.generate`. Identical to `MerkleLogCreateOpts`
+ * minus the key fields; `generate` materialises a fresh keypair via
+ * `suite.keygen()`.
+ */
+export interface MerkleLogGenerateOpts {
+    readonly origin: string;
+    readonly hashing?: 'sha256' | 'blake3';
+    readonly suite?: SignatureSuite;
+}
+/**
+ * Memory-backed signed transparency log. The normie producer surface.
+ * Construct via `MerkleLog.create` (caller supplies keys) or
+ * `MerkleLog.generate` (the class materialises a fresh keypair and
+ * returns it). Methods after construction are synchronous; module-init
+ * readiness and keygen are the only async steps.
+ *
+ * Methods delegate to an inner `SignedLog<S>` with a fresh
+ * `MemoryStorage` backend. For file or database storage, construct
+ * `SignedLog` directly with a custom `MerkleStorage` implementation,
+ * see `docs/merkle.md` for the extension pattern.
+ */
+export declare class MerkleLog {
+    readonly origin: string;
+    readonly hasher: Hasher;
+    readonly suite: SignatureSuite;
+    private readonly _inner;
+    private constructor();
+    /**
+     * Construct a `MerkleLog` with caller-supplied keys. Validates the
+     * suite against the c2sp.org/tlog-cosignature §Format algorithm-byte
+     * registry before instantiating the inner `SignedLog`; an
+     * unregistered suite raises `MerkleLogError('unsupported-suite')`
+     * with a message naming the suite and pointing at the spec.
+     *
+     * Async to keep the construction surface uniform with `generate`,
+     * which is async because `suite.keygen()` may route through async
+     * WASM acquisition under load. The hot-path methods (`append`,
+     * `head`, `size`, etc.) stay sync per the merkle layer's locked
+     * sync invariant.
+     */
+    static create(opts: MerkleLogCreateOpts): Promise<MerkleLog>;
+    /**
+     * Construct a `MerkleLog` with a freshly generated keypair. Returns
+     * the log plus the keypair; the caller is responsible for
+     * persisting the keys externally if the log outlives the process.
+     *
+     * The returned `signingKey` is a copy, the log retains its own
+     * internal copy that `dispose()` wipes; modifying the returned
+     * buffer after construction does not affect the log.
+     */
+    static generate(opts: MerkleLogGenerateOpts): Promise<{
+        log: MerkleLog;
+        signingKey: Uint8Array;
+        pubkey: Uint8Array;
+    }>;
+    /**
+     * Append a leaf and return its index, hash, and inclusion proof
+     * against the post-append tree size. Delegates to the inner
+     * `SignedLog.append`.
+     */
+    append(leafBytes: Uint8Array): {
+        leafIndex: number;
+        leafHash: Uint8Array;
+        inclusionProof: Uint8Array[];
+    };
+    /**
+     * Emit the current checkpoint as a signed-note envelope. Re-signed
+     * on every call; the body reflects the live tree size and root
+     * hash. Timestamp defaults to `Math.floor(Date.now() / 1000)`.
+     */
+    head(opts?: {
+        timestamp?: number;
+    }): Uint8Array;
+    /** Current number of leaves in the tree. */
+    size(): number;
+    /** Current Merkle root hash. */
+    rootHash(): Uint8Array;
+    /**
+     * Inclusion proof for `leafIndex` in a tree of the given size, or
+     * the current tree size if omitted. Per RFC 9162 §2.1.3.
+     */
+    inclusionProof(leafIndex: number, treeSize?: number): Uint8Array[];
+    /**
+     * Consistency proof between two tree sizes per RFC 9162 §2.1.4.
+     * `oldSize` must be `<= newSize <= size()`.
+     */
+    consistencyProof(oldSize: number, newSize: number): Uint8Array[];
+    /**
+     * Zero the stored signing-key copy. Idempotent. Subsequent calls
+     * to any public method throw.
+     */
+    dispose(): void;
+}

package/dist/merkle/merkle-log.js

@@ -0,0 +1,207 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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-log.ts
+//
+// `MerkleLog`, the producer-side normie surface. Memory-backed via
+// `MemoryStorage`. Real deployments drop down to `SignedLog<S>` with a
+// custom `MerkleStorage`.
+//
+// Defaults: `hashing: 'sha256'`, `suite: MlDsa44Suite`. ML-DSA-44 is
+// the PQ default per c2sp.org/tlog-checkpoint, the only PQ suite
+// currently in the c2sp.org/tlog-cosignature §Format algorithm-byte
+// registry. Sigsum interop: pass `suite: Ed25519Suite`.
+import { isInitialized } from '../init.js';
+import { MerkleLogError } from '../errors.js';
+import { SignedLog } from './signed-log.js';
+import { MemoryStorage } from './storage.js';
+import { Sha256Tree, Sha256Hasher } from './sha256-tree.js';
+import { Blake3Tree, Blake3Hasher } from './blake3-tree.js';
+import { lookupAlgoEntryByFormatEnum } from './signed-note.js';
+import { MlDsa44Suite } from '../sign/suites/mldsa.js';
+const SHA2_MODULE = 'sha2';
+/**
+ * Memory-backed signed transparency log. The normie producer surface.
+ * Construct via `MerkleLog.create` (caller supplies keys) or
+ * `MerkleLog.generate` (the class materialises a fresh keypair and
+ * returns it). Methods after construction are synchronous; module-init
+ * readiness and keygen are the only async steps.
+ *
+ * Methods delegate to an inner `SignedLog<S>` with a fresh
+ * `MemoryStorage` backend. For file or database storage, construct
+ * `SignedLog` directly with a custom `MerkleStorage` implementation,
+ * see `docs/merkle.md` for the extension pattern.
+ */
+export class MerkleLog {
+    origin;
+    hasher;
+    suite;
+    _inner;
+    constructor(inner) {
+        this._inner = inner;
+        this.origin = inner.origin;
+        this.hasher = inner.tree.hasher;
+        this.suite = inner.suite;
+    }
+    /**
+     * Construct a `MerkleLog` with caller-supplied keys. Validates the
+     * suite against the c2sp.org/tlog-cosignature §Format algorithm-byte
+     * registry before instantiating the inner `SignedLog`; an
+     * unregistered suite raises `MerkleLogError('unsupported-suite')`
+     * with a message naming the suite and pointing at the spec.
+     *
+     * Async to keep the construction surface uniform with `generate`,
+     * which is async because `suite.keygen()` may route through async
+     * WASM acquisition under load. The hot-path methods (`append`,
+     * `head`, `size`, etc.) stay sync per the merkle layer's locked
+     * sync invariant.
+     */
+    static async create(opts) {
+        const hashing = opts.hashing ?? 'sha256';
+        const suite = opts.suite ?? MlDsa44Suite;
+        if (lookupAlgoEntryByFormatEnum(suite.formatEnum) === undefined)
+            throw new MerkleLogError('unsupported-suite', `MerkleLog: 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');
+        const tree = buildTree(hashing);
+        assertModulesInitialized([
+            ...suite.wasmModules,
+            ...tree.hasher.wasmModules,
+            SHA2_MODULE,
+        ]);
+        const inner = new SignedLog({
+            tree,
+            suite,
+            origin: opts.origin,
+            signingKey: opts.signingKey,
+            pubkey: opts.pubkey,
+        });
+        return new MerkleLog(inner);
+    }
+    /**
+     * Construct a `MerkleLog` with a freshly generated keypair. Returns
+     * the log plus the keypair; the caller is responsible for
+     * persisting the keys externally if the log outlives the process.
+     *
+     * The returned `signingKey` is a copy, the log retains its own
+     * internal copy that `dispose()` wipes; modifying the returned
+     * buffer after construction does not affect the log.
+     */
+    static async generate(opts) {
+        const hashing = opts.hashing ?? 'sha256';
+        const suite = opts.suite ?? MlDsa44Suite;
+        if (lookupAlgoEntryByFormatEnum(suite.formatEnum) === undefined)
+            throw new MerkleLogError('unsupported-suite', `MerkleLog.generate: 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');
+        // suite.keygen() requires the suite's modules already initialised;
+        // the same modules are checked again inside create() before
+        // instantiating SignedLog. Checking here keeps the throw surface
+        // consistent regardless of which factory the caller used.
+        const tmpHasher = resolveHasher(hashing);
+        assertModulesInitialized([
+            ...suite.wasmModules,
+            ...tmpHasher.wasmModules,
+            SHA2_MODULE,
+        ]);
+        const { pk, sk } = suite.keygen();
+        const log = await MerkleLog.create({
+            origin: opts.origin,
+            signingKey: sk,
+            pubkey: pk,
+            hashing,
+            suite,
+        });
+        return { log, signingKey: sk, pubkey: pk };
+    }
+    /**
+     * Append a leaf and return its index, hash, and inclusion proof
+     * against the post-append tree size. Delegates to the inner
+     * `SignedLog.append`.
+     */
+    append(leafBytes) {
+        return this._inner.append(leafBytes);
+    }
+    /**
+     * Emit the current checkpoint as a signed-note envelope. Re-signed
+     * on every call; the body reflects the live tree size and root
+     * hash. Timestamp defaults to `Math.floor(Date.now() / 1000)`.
+     */
+    head(opts) {
+        return this._inner.signCheckpoint(opts);
+    }
+    /** Current number of leaves in the tree. */
+    size() {
+        return this._inner.size();
+    }
+    /** Current Merkle root hash. */
+    rootHash() {
+        return this._inner.rootHash();
+    }
+    /**
+     * Inclusion proof for `leafIndex` in a tree of the given size, or
+     * the current tree size if omitted. Per RFC 9162 §2.1.3.
+     */
+    inclusionProof(leafIndex, treeSize) {
+        return this._inner.getInclusionProof(leafIndex, treeSize);
+    }
+    /**
+     * Consistency proof between two tree sizes per RFC 9162 §2.1.4.
+     * `oldSize` must be `<= newSize <= size()`.
+     */
+    consistencyProof(oldSize, newSize) {
+        return this._inner.getConsistencyProof(oldSize, newSize);
+    }
+    /**
+     * Zero the stored signing-key copy. Idempotent. Subsequent calls
+     * to any public method throw.
+     */
+    dispose() {
+        this._inner.dispose();
+    }
+}
+function buildTree(hashing) {
+    if (hashing === 'sha256')
+        return new Sha256Tree(new MemoryStorage());
+    if (hashing === 'blake3')
+        return new Blake3Tree(new MemoryStorage());
+    throw new MerkleLogError('unsupported-hashing', `MerkleLog: hashing must be 'sha256' or 'blake3', got '${hashing}'`);
+}
+function resolveHasher(hashing) {
+    if (hashing === 'sha256')
+        return Sha256Hasher;
+    if (hashing === 'blake3')
+        return Blake3Hasher;
+    throw new MerkleLogError('unsupported-hashing', `MerkleLog: 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', `MerkleLog: WASM module '${mod}' is not initialized; `
+                + 'call init() with the appropriate sources before constructing MerkleLog');
+    }
+}