leviathan-crypto 2.0.1 → 3.0.0

package/dist/merkle/sth.js

@@ -0,0 +1,31 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/sth.ts
+//
+// SignedTreeHead type: a c2sp.org/tlog-checkpoint body plus the
+// signature lines that authenticate it. The body and signatures pair
+// is the wire-format unit a SignedLog (built on top of MerkleTree in
+// a later phase) produces and a verifier consumes. The byte-stable
+// serialization is `emitSignedNote(serializeCheckpointBody(c), sigs)`;
+// the parse side is `parseSignedNote` followed by `parseCheckpointBody`
+// on the resulting body region.
+export {};

package/dist/merkle/storage.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Minimum surface a backend exposes to drive a MerkleTree. Sync
+ * everywhere: the merkle layer is synchronous and consumers that need
+ * async IO wrap externally.
+ *
+ * Storage records only perfect aligned subtree hashes. Roots of
+ * partial right-edge subtrees are recomputed on demand by the tree.
+ */
+export interface MerkleStorage {
+    /** Number of leaves appended so far. */
+    size(): number;
+    /** Record a leaf hash at the given index. The implementation must reject out-of-order indices. */
+    appendLeaf(leafIndex: number, leafHash: Uint8Array): void;
+    /** Read the leaf hash at index. Throws if absent. */
+    getLeaf(leafIndex: number): Uint8Array;
+    /** Record an internal node hash at the given (level, index). */
+    putNode(level: number, index: number, hash: Uint8Array): void;
+    /** Read an internal-node hash. Throws if absent. */
+    getNode(level: number, index: number): Uint8Array;
+    /** Probe an internal-node slot without throwing. */
+    hasNode(level: number, index: number): boolean;
+}
+/**
+ * In-process storage backed by a Map keyed on `${level}:${index}`. Sync.
+ * Suitable for tests, witnesses without persistent storage, and the
+ * MerkleVerifier short-lived flow. Production logs that need durability
+ * implement MerkleStorage over a file or DB and feed it to a
+ * MerkleTree the same way.
+ */
+export declare class MemoryStorage implements MerkleStorage {
+    private leafCount;
+    private readonly nodes;
+    private static key;
+    size(): number;
+    appendLeaf(leafIndex: number, leafHash: Uint8Array): void;
+    getLeaf(leafIndex: number): Uint8Array;
+    putNode(level: number, index: number, hash: Uint8Array): void;
+    getNode(level: number, index: number): Uint8Array;
+    hasNode(level: number, index: number): boolean;
+}

package/dist/merkle/storage.js

@@ -0,0 +1,71 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/storage.ts
+//
+// MerkleStorage abstracts the per-node persistence layer a tree uses
+// to materialise leaves and recomputed internal nodes. Two-axis key
+// (level, index): level 0 is the leaf row, level >= 1 stores the hash
+// of a perfect aligned subtree covering [index*2^level, (index+1)*2^level).
+//
+// MemoryStorage is the in-process implementation. File and database
+// backends are extension surface and ship as consumer code.
+/**
+ * In-process storage backed by a Map keyed on `${level}:${index}`. Sync.
+ * Suitable for tests, witnesses without persistent storage, and the
+ * MerkleVerifier short-lived flow. Production logs that need durability
+ * implement MerkleStorage over a file or DB and feed it to a
+ * MerkleTree the same way.
+ */
+export class MemoryStorage {
+    leafCount = 0;
+    nodes = new Map();
+    static key(level, index) {
+        return `${level}:${index}`;
+    }
+    size() {
+        return this.leafCount;
+    }
+    appendLeaf(leafIndex, leafHash) {
+        if (leafIndex !== this.leafCount)
+            throw new RangeError(`MemoryStorage.appendLeaf: out-of-order index ${leafIndex}, expected ${this.leafCount}`);
+        this.nodes.set(MemoryStorage.key(0, leafIndex), leafHash);
+        this.leafCount++;
+    }
+    getLeaf(leafIndex) {
+        const v = this.nodes.get(MemoryStorage.key(0, leafIndex));
+        if (!v)
+            throw new RangeError(`MemoryStorage.getLeaf: no leaf at index ${leafIndex}`);
+        return v;
+    }
+    putNode(level, index, hash) {
+        this.nodes.set(MemoryStorage.key(level, index), hash);
+    }
+    getNode(level, index) {
+        const v = this.nodes.get(MemoryStorage.key(level, index));
+        if (!v)
+            throw new RangeError(`MemoryStorage.getNode: no node at (${level}, ${index})`);
+        return v;
+    }
+    hasNode(level, index) {
+        return this.nodes.has(MemoryStorage.key(level, index));
+    }
+}

package/dist/merkle/tree.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Minimum surface a hash function must expose to drive RFC 9162
+ * (Certificate Transparency Version 2.0) §2.1.1, Merkle Hash Trees.
+ *
+ * Implementations are `const` objects (no instantiation); each call site
+ * acquires the underlying WASM module fresh, runs the operation, and
+ * disposes. There is no long-lived state on a Hasher; concurrent users
+ * are serialised by the per-module exclusivity guard at the WASM layer.
+ */
+export interface Hasher {
+    /** Display name, used in error messages and the export catalog. */
+    readonly name: string;
+    /** Bytes per hash output. */
+    readonly outputSize: number;
+    /** WASM module ids this Hasher exercises during `init()`. */
+    readonly wasmModules: readonly string[];
+    /** RFC 9162 §2.1.1: MTH({}) = HASH(), the hash of the empty input. */
+    hashEmpty(): Uint8Array;
+    /** RFC 9162 §2.1.1: leaf domain separator `0x00` prefix. */
+    hashLeaf(leaf: Uint8Array): Uint8Array;
+    /** RFC 9162 §2.1.1: internal-node domain separator `0x01` prefix. */
+    hashInternal(left: Uint8Array, right: Uint8Array): Uint8Array;
+}
+/**
+ * Stateful Merkle tree with pluggable storage. Append a leaf, query
+ * size + root, build inclusion and consistency proofs. The tree owns
+ * the hash function via `hasher`; consumers do not pass it per call.
+ */
+export interface MerkleTree {
+    readonly hasher: Hasher;
+    size(): number;
+    rootHash(): Uint8Array;
+    append(leafBytes: Uint8Array): {
+        leafIndex: number;
+        leafHash: Uint8Array;
+    };
+    getInclusionProof(leafIndex: number, treeSize?: number): Uint8Array[];
+    getConsistencyProof(oldSize: number, newSize: number): Uint8Array[];
+}
+/**
+ * RFC 9162 §2.1.4, Consistency Proof Verification: "k is the largest
+ * power of two smaller than n". The split point at which an n-leaf
+ * tree decomposes into a perfect left subtree of size k and a right
+ * subtree of size n - k. Defined for n >= 2.
+ *
+ * Invariant for n >= 2: k < n <= 2*k.
+ */
+export declare function splitPoint(n: number): number;
+/**
+ * `bits.Len64(x)` analogue: position of the most-significant set bit
+ * of x, with `bitLen(0) = 0`. Used by the §2.1.3 / §2.1.4 inclusion
+ * and consistency verifiers to split a proof into inner and border
+ * segments.
+ */
+export declare function bitLen(x: number): number;
+/**
+ * Popcount of a non-negative integer (`bits.OnesCount64` analogue).
+ * Used to compute the "border" length of an inclusion proof per the
+ * RFC 9162 §2.1.3 decomposition.
+ */
+export declare function popcount(x: number): number;
+/**
+ * Number of trailing zero bits in a positive integer
+ * (`bits.TrailingZeros64` analogue). Used by RFC 9162 §2.1.4 to step
+ * the consistency verifier past the levels covered by the size1
+ * subtree. Defined for x >= 1.
+ */
+export declare function trailingZeros(x: number): number;

package/dist/merkle/tree.js

@@ -0,0 +1,94 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/tree.ts
+//
+// MerkleTree + Hasher interfaces and the spec-anchored node-index math.
+// Hash-agnostic by design: every hash-touching surface (the tree class,
+// the free-function proof verifiers, the proof builders) is parameterised
+// by a `Hasher`, so SHA-256 and BLAKE3 trees share the same algorithmic
+// core and the same proof wire format.
+/**
+ * RFC 9162 §2.1.4, Consistency Proof Verification: "k is the largest
+ * power of two smaller than n". The split point at which an n-leaf
+ * tree decomposes into a perfect left subtree of size k and a right
+ * subtree of size n - k. Defined for n >= 2.
+ *
+ * Invariant for n >= 2: k < n <= 2*k.
+ */
+export function splitPoint(n) {
+    if (!Number.isInteger(n) || n < 2)
+        throw new RangeError(`splitPoint: n must be an integer >= 2, got ${n}`);
+    // Largest power of two strictly less than n: for n=2 -> 1, n=8 -> 4,
+    // n=2^k -> 2^(k-1). Equivalent to 1 << (bitLength(n - 1) - 1).
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+}
+/**
+ * `bits.Len64(x)` analogue: position of the most-significant set bit
+ * of x, with `bitLen(0) = 0`. Used by the §2.1.3 / §2.1.4 inclusion
+ * and consistency verifiers to split a proof into inner and border
+ * segments.
+ */
+export function bitLen(x) {
+    if (!Number.isInteger(x) || x < 0)
+        throw new RangeError(`bitLen: x must be a non-negative integer, got ${x}`);
+    let n = 0;
+    while (x > 0) {
+        x = Math.floor(x / 2);
+        n++;
+    }
+    return n;
+}
+/**
+ * Popcount of a non-negative integer (`bits.OnesCount64` analogue).
+ * Used to compute the "border" length of an inclusion proof per the
+ * RFC 9162 §2.1.3 decomposition.
+ */
+export function popcount(x) {
+    if (!Number.isInteger(x) || x < 0)
+        throw new RangeError(`popcount: x must be a non-negative integer, got ${x}`);
+    let n = 0;
+    while (x > 0) {
+        if (x & 1)
+            n++;
+        x = Math.floor(x / 2);
+    }
+    return n;
+}
+/**
+ * Number of trailing zero bits in a positive integer
+ * (`bits.TrailingZeros64` analogue). Used by RFC 9162 §2.1.4 to step
+ * the consistency verifier past the levels covered by the size1
+ * subtree. Defined for x >= 1.
+ */
+export function trailingZeros(x) {
+    if (!Number.isInteger(x) || x < 1)
+        throw new RangeError(`trailingZeros: x must be a positive integer, got ${x}`);
+    let n = 0;
+    while ((x & 1) === 0) {
+        x = Math.floor(x / 2);
+        n++;
+    }
+    return n;
+}

package/dist/mldsa/embedded.d.ts

@@ -0,0 +1 @@
+export { WASM_GZ_BASE64 as mldsaWasm } from '../embedded/mldsa.js';

package/dist/{kyber → mldsa}/embedded.js

@@ -19,9 +19,9 @@
 //   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
 //                           ▀█████▀▀
 //
-// src/ts/kyber/embedded.ts
+// src/ts/mldsa/embedded.ts
 //
-// Exports the gzip+base64 kyber WASM blob for use as a WasmSource.
-// This is the only file in the kyber subpath that references the embedded blob.
-// Import via `leviathan-crypto/kyber/embedded`.
-export { WASM_GZ_BASE64 as kyberWasm } from '../embedded/kyber.js';
+// Exports the gzip+base64 mldsa WASM blob for use as a WasmSource.
+// This is the only file in the mldsa subpath that references the embedded blob.
+// Import via `leviathan-crypto/mldsa/embedded`.
+export { WASM_GZ_BASE64 as mldsaWasm } from '../embedded/mldsa.js';

package/dist/mldsa/expand.d.ts

@@ -0,0 +1,53 @@
+import type { MlDsaExports, Sha3Exports } from './types.js';
+import type { MlDsaParams } from './params.js';
+/**
+ * ExpandA, FIPS 204 Algorithm 32.
+ *
+ * For (i, j) ∈ [0, k) × [0, ℓ):
+ *   s ← ρ ‖ IntegerToBytes(j, 1) ‖ IntegerToBytes(i, 1)
+ *   Â[i, j] ← RejNTTPoly(SHAKE128(s))
+ *
+ * Output is row-major: Â[i, j] sits at matrixOff + (i·ℓ + j) · 1024.
+ * This matches `polyvec_matrix_pointwise_montgomery`'s row-stride contract.
+ *
+ * ρ is the public seed; the rej_ntt_poly inner loop has data-dependent
+ * branching but only on ρ-derived bytes (public), so no CT concern.
+ */
+export declare function expandA(mx: MlDsaExports, sx: Sha3Exports, params: MlDsaParams, rho: Uint8Array, matrixOff: number): void;
+/**
+ * ExpandS, FIPS 204 Algorithm 33.
+ *
+ * For r ∈ [0, ℓ): s₁[r] ← RejBoundedPoly(SHAKE256(ρ' ‖ IntegerToBytes(r, 2)))
+ * For r ∈ [0, k): s₂[r] ← RejBoundedPoly(SHAKE256(ρ' ‖ IntegerToBytes(r+ℓ, 2)))
+ *
+ * Note the index is 2 bytes (little-endian per FIPS 204 §7.1 Alg 11), mlkem
+ * uses 1 byte because k ≤ 4, but ML-DSA's max index is k+ℓ-1 = 14 (still
+ * ≤ 255 in practice but the spec mandates 2 bytes).
+ *
+ * ρ' is secret. The local seed scratch is wiped on exit; the caller is
+ * responsible for the WASM-resident ρ' source buffer.
+ */
+export declare function expandS(mx: MlDsaExports, sx: Sha3Exports, params: MlDsaParams, rhoPrime: Uint8Array, s1Off: number, s2Off: number): void;
+/**
+ * ExpandMask, FIPS 204 Algorithm 34.
+ *
+ * For r ∈ [0, ℓ):
+ *   v ← SHAKE256(ρ'' ‖ IntegerToBytes(κ + r, 2),  32·c)
+ *   y[r] ← BitUnpack(v, γ₁ − 1, γ₁)
+ *
+ * where c = 1 + bitlen(γ₁ − 1) is the per-coefficient byte width
+ * (18 when γ₁ = 2¹⁷, 20 when γ₁ = 2¹⁹). Output coefficients land in
+ * [-(γ₁ − 1), γ₁]; bit_unpack(a=γ₁−1, b=γ₁) covers exactly that range.
+ *
+ * y is produced in time domain at `yPvOff`. Sign_internal applies
+ * polyvec_ntt to y before the matrix-vector product  · NTT(y).
+ *
+ * ρ'' is secret (derived from K ‖ rnd ‖ μ). This function uses one
+ * one-shot SHAKE256 per polynomial (caller's full input is ≤ 168 B,
+ * fits in a single shake256HashConcat call); the SHAKE state is reset
+ * each iteration via shake256Init inside the helper, so no state
+ * carries between r values. The squeeze output lands in a TS-side
+ * buffer and is set into the WASM XOF/PRF region only long enough for
+ * bit_unpack to consume it.
+ */
+export declare function expandMask(mx: MlDsaExports, sx: Sha3Exports, params: MlDsaParams, rhoPrimePrime: Uint8Array, kappa: number, yPvOff: number): void;

package/dist/mldsa/expand.js

@@ -0,0 +1,188 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/mldsa/expand.ts
+//
+// FIPS 204 Algorithms 32 (ExpandA), 33 (ExpandS), 34 (ExpandMask),
+// pseudorandom expansion of seeds into the matrix  (public), the noise
+// polyvecs s₁/s₂ (secret, time domain), and the masking polyvec y (per
+// signing iteration, time domain).
+//
+// ExpandA samples  directly in NTT domain (RejNTTPoly produces NTT
+// coefficients). ExpandS / ExpandMask sample in time domain; the
+// orchestration layer applies polyvec_ntt where needed for the matrix-
+// vector products in Sign_internal and Verify_internal.
+import { wipe } from '../utils.js';
+import { shake128Squeezer, shake256Squeezer, shake256HashConcat } from './sha3-helpers.js';
+const POLY_BYTES = 1024; // 256 × i32
+/**
+ * ExpandA, FIPS 204 Algorithm 32.
+ *
+ * For (i, j) ∈ [0, k) × [0, ℓ):
+ *   s ← ρ ‖ IntegerToBytes(j, 1) ‖ IntegerToBytes(i, 1)
+ *   Â[i, j] ← RejNTTPoly(SHAKE128(s))
+ *
+ * Output is row-major: Â[i, j] sits at matrixOff + (i·ℓ + j) · 1024.
+ * This matches `polyvec_matrix_pointwise_montgomery`'s row-stride contract.
+ *
+ * ρ is the public seed; the rej_ntt_poly inner loop has data-dependent
+ * branching but only on ρ-derived bytes (public), so no CT concern.
+ */
+export function expandA(mx, sx, params, rho, matrixOff) {
+    const { k, l } = params;
+    const xofPrfOff = mx.getXofPrfOffset();
+    const mlMem = new Uint8Array(mx.memory.buffer);
+    // XOF input: ρ(32) ‖ jByte ‖ iByte (FIPS 204 §7.3 Alg 32 line 4)
+    const xofSeed = new Uint8Array(34);
+    xofSeed.set(rho, 0);
+    for (let i = 0; i < k; i++) {
+        for (let j = 0; j < l; j++) {
+            xofSeed[32] = j;
+            xofSeed[33] = i;
+            const sq = shake128Squeezer(sx, xofSeed);
+            const polyOff = matrixOff + (i * l + j) * POLY_BYTES;
+            let ctr = 0;
+            while (ctr < 256) {
+                const block = sq.squeeze();
+                mlMem.set(block, xofPrfOff);
+                ctr += mx.rej_ntt_poly(polyOff, ctr, xofPrfOff, sq.rate);
+            }
+        }
+    }
+}
+/**
+ * ExpandS, FIPS 204 Algorithm 33.
+ *
+ * For r ∈ [0, ℓ): s₁[r] ← RejBoundedPoly(SHAKE256(ρ' ‖ IntegerToBytes(r, 2)))
+ * For r ∈ [0, k): s₂[r] ← RejBoundedPoly(SHAKE256(ρ' ‖ IntegerToBytes(r+ℓ, 2)))
+ *
+ * Note the index is 2 bytes (little-endian per FIPS 204 §7.1 Alg 11), mlkem
+ * uses 1 byte because k ≤ 4, but ML-DSA's max index is k+ℓ-1 = 14 (still
+ * ≤ 255 in practice but the spec mandates 2 bytes).
+ *
+ * ρ' is secret. The local seed scratch is wiped on exit; the caller is
+ * responsible for the WASM-resident ρ' source buffer.
+ */
+export function expandS(mx, sx, params, rhoPrime, s1Off, s2Off) {
+    const { k, l, eta } = params;
+    const xofPrfOff = mx.getXofPrfOffset();
+    const mlMem = new Uint8Array(mx.memory.buffer);
+    // PRF input: ρ'(64) ‖ idx_lo ‖ idx_hi
+    const seed = new Uint8Array(66);
+    seed.set(rhoPrime, 0);
+    try {
+        // s₁: ℓ polynomials at indices 0..ℓ-1
+        for (let r = 0; r < l; r++) {
+            seed[64] = r & 0xFF;
+            seed[65] = (r >>> 8) & 0xFF;
+            const sq = shake256Squeezer(sx, seed);
+            const off = s1Off + r * POLY_BYTES;
+            let ctr = 0;
+            while (ctr < 256) {
+                const block = sq.squeeze();
+                mlMem.set(block, xofPrfOff);
+                ctr += mx.rej_bounded_poly(off, ctr, xofPrfOff, sq.rate, eta);
+            }
+        }
+        // s₂: k polynomials at indices ℓ..ℓ+k-1
+        for (let r = 0; r < k; r++) {
+            const idx = r + l;
+            seed[64] = idx & 0xFF;
+            seed[65] = (idx >>> 8) & 0xFF;
+            const sq = shake256Squeezer(sx, seed);
+            const off = s2Off + r * POLY_BYTES;
+            let ctr = 0;
+            while (ctr < 256) {
+                const block = sq.squeeze();
+                mlMem.set(block, xofPrfOff);
+                ctr += mx.rej_bounded_poly(off, ctr, xofPrfOff, sq.rate, eta);
+            }
+        }
+    }
+    finally {
+        // Local seed buffer carries ρ' for the duration of this call; wipe
+        // even on early throw so it never persists in TS heap.
+        wipe(seed);
+    }
+}
+// Bitlen helper, bitlen(n) for n > 0 is floor(log2(n)) + 1, used to size
+// the BitUnpack output width inside ExpandMask. Identical to the helper in
+// keygen.ts; keeping a private copy here avoids cross-importing the keygen
+// module just for one tiny utility.
+function bitlen(n) {
+    let b = 0;
+    let x = n;
+    while (x > 0) {
+        b++;
+        x >>>= 1;
+    }
+    return b;
+}
+/**
+ * ExpandMask, FIPS 204 Algorithm 34.
+ *
+ * For r ∈ [0, ℓ):
+ *   v ← SHAKE256(ρ'' ‖ IntegerToBytes(κ + r, 2),  32·c)
+ *   y[r] ← BitUnpack(v, γ₁ − 1, γ₁)
+ *
+ * where c = 1 + bitlen(γ₁ − 1) is the per-coefficient byte width
+ * (18 when γ₁ = 2¹⁷, 20 when γ₁ = 2¹⁹). Output coefficients land in
+ * [-(γ₁ − 1), γ₁]; bit_unpack(a=γ₁−1, b=γ₁) covers exactly that range.
+ *
+ * y is produced in time domain at `yPvOff`. Sign_internal applies
+ * polyvec_ntt to y before the matrix-vector product  · NTT(y).
+ *
+ * ρ'' is secret (derived from K ‖ rnd ‖ μ). This function uses one
+ * one-shot SHAKE256 per polynomial (caller's full input is ≤ 168 B,
+ * fits in a single shake256HashConcat call); the SHAKE state is reset
+ * each iteration via shake256Init inside the helper, so no state
+ * carries between r values. The squeeze output lands in a TS-side
+ * buffer and is set into the WASM XOF/PRF region only long enough for
+ * bit_unpack to consume it.
+ */
+export function expandMask(mx, sx, params, rhoPrimePrime, kappa, yPvOff) {
+    const { l, gamma1 } = params;
+    const c = 1 + bitlen(gamma1 - 1); // 18 or 20
+    const polyBytesV = 32 * c; // 576 or 640
+    const xofPrfOff = mx.getXofPrfOffset();
+    const mlMem = new Uint8Array(mx.memory.buffer);
+    const idxBytes = new Uint8Array(2);
+    for (let r = 0; r < l; r++) {
+        const n = kappa + r;
+        idxBytes[0] = n & 0xFF;
+        idxBytes[1] = (n >>> 8) & 0xFF;
+        // SHAKE256(ρ'' ‖ idx, 32·c). For γ₁ ≤ 2¹⁹ the output never exceeds
+        // 640 bytes, well within the 8192-byte XOF region.
+        const v = shake256HashConcat(sx, [rhoPrimePrime, idxBytes], polyBytesV);
+        try {
+            mlMem.set(v, xofPrfOff);
+            // bit_unpack(a=γ₁-1, b=γ₁): bitlen(a+b) = bitlen(2γ₁-1) = c.
+            // Decodes to coefficients in [-(γ₁-1), γ₁], Alg 34 / Alg 19.
+            mx.bit_unpack(yPvOff + r * 1024, xofPrfOff, gamma1 - 1, gamma1);
+        }
+        finally {
+            // v held the SHAKE256(ρ'' ‖ idx) squeeze bytes, ρ''-derived,
+            // i.e. secret. These bytes become y for this iteration, so
+            // recovery would unmask the signing nonce on the rejected path.
+            wipe(v);
+        }
+    }
+}

package/dist/mldsa/format.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Build M' = domSep ‖ |ctx| ‖ ctx ‖ M.
+ *
+ * domSep = 0x00 for pure ML-DSA, 0x01 for HashML-DSA.
+ * Caller has already validated ctx.length ≤ 255.
+ */
+export declare function constructMPrime(domSep: number, ctx: Uint8Array, M: Uint8Array): Uint8Array;
+/**
+ * Build the HashML-DSA M' = 0x01 ‖ |ctx| ‖ ctx ‖ OID ‖ PH_M.
+ *
+ * FIPS 204 §5.4 / Algorithm 4 line 23 (sign) and Algorithm 5 line 18 (verify).
+ * The leading byte is 0x01 (vs 0x00 for pure ML-DSA), domain separation
+ * across pure / pre-hash modes per FIPS 204 §3.6.4. Caller has already
+ * validated ctx.length ≤ 255.
+ */
+export declare function constructMPrimeHash(ctx: Uint8Array, oid: Uint8Array, PH_M: Uint8Array): Uint8Array;

package/dist/mldsa/format.js

@@ -0,0 +1,68 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/mldsa/format.ts
+//
+// External-API M' construction. Lives in its own file because HashML-DSA
+// reuses the same byte layout with a different domain separator (0x01)
+// and a hash-of-message tail.
+//
+// FIPS 204 Algorithm 2 line 10 (Sign) and Algorithm 3 line 5 (Verify):
+//   M' ← BytesToBits(IntegerToBytes(domSep, 1)
+//                    ‖ IntegerToBytes(|ctx|, 1)
+//                    ‖ ctx
+//                    ‖ <message-bytes>)
+//
+// In a byte-oriented SHAKE wrapper, BytesToBits is a no-op, the absorbed
+// bytes are the same. So we hand the absorber a contiguous Uint8Array
+// laid out exactly as the spec describes, plus the domain-separator byte
+// up front.
+/**
+ * Build M' = domSep ‖ |ctx| ‖ ctx ‖ M.
+ *
+ * domSep = 0x00 for pure ML-DSA, 0x01 for HashML-DSA.
+ * Caller has already validated ctx.length ≤ 255.
+ */
+export function constructMPrime(domSep, ctx, M) {
+    const out = new Uint8Array(2 + ctx.length + M.length);
+    out[0] = domSep & 0xFF;
+    out[1] = ctx.length & 0xFF;
+    out.set(ctx, 2);
+    out.set(M, 2 + ctx.length);
+    return out;
+}
+/**
+ * Build the HashML-DSA M' = 0x01 ‖ |ctx| ‖ ctx ‖ OID ‖ PH_M.
+ *
+ * FIPS 204 §5.4 / Algorithm 4 line 23 (sign) and Algorithm 5 line 18 (verify).
+ * The leading byte is 0x01 (vs 0x00 for pure ML-DSA), domain separation
+ * across pure / pre-hash modes per FIPS 204 §3.6.4. Caller has already
+ * validated ctx.length ≤ 255.
+ */
+export function constructMPrimeHash(ctx, oid, PH_M) {
+    const out = new Uint8Array(2 + ctx.length + oid.length + PH_M.length);
+    out[0] = 0x01;
+    out[1] = ctx.length & 0xFF;
+    out.set(ctx, 2);
+    out.set(oid, 2 + ctx.length);
+    out.set(PH_M, 2 + ctx.length + oid.length);
+    return out;
+}