leviathan-crypto 2.1.0 → 3.0.0

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

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

package/dist/merkle/sha256-tree.js

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

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

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