leviathan-crypto 2.0.1 → 3.0.0

package/dist/mldsa/keygen.js

@@ -0,0 +1,232 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/keygen.ts
+//
+// FIPS 204 §6.1 Algorithm 6, ML-DSA.KeyGen_internal.
+// Implements the deterministic xi-seeded key generator used by both the
+// public keygen() (random ξ) and keygenDerand(ξ) entry points. Output is
+// (pk, sk) byte-encoded per Algorithms 22 (pkEncode) and 24 (skEncode).
+//
+// Slot map (matrix slot + 6 polyvec slots):
+//   MATRIX_SLOT      Â (matrix, k×ℓ polynomials in NTT domain, public)
+//   POLYVEC_SLOT_0   s₁ (time domain, preserved for skEncode bit_pack)
+//   POLYVEC_SLOT_1   s₂ (time domain, preserved for skEncode bit_pack)
+//   POLYVEC_SLOT_2   t = NTT⁻¹(Â · ŝ₁) + s₂  (intermediate, secret-derived)
+//   POLYVEC_SLOT_3   t₁ (high bits of t, public, encoded into pk)
+//   POLYVEC_SLOT_4   t₀ (low bits of t, secret, encoded into sk)
+//   POLYVEC_SLOT_5   ŝ₁ (NTT-domain Montgomery-form copy of s₁; consumed by
+//                       the matrix product, then wiped). Time-domain s₁
+//                       must survive in slot 0 for the sk BitPack step.
+//
+// POLY_SLOT_7 is reserved as scratch by polyvec_pointwise_acc_montgomery
+// (called via polyvec_matrix_pointwise_montgomery); we never touch it.
+import { wipe } from '../utils.js';
+import { shake256HashConcat } from './sha3-helpers.js';
+import { expandA, expandS } from './expand.js';
+const POLY_BYTES = 1024;
+const D = 13; // FIPS 204 §4 Table 1, d=13 for all sets
+// Bitlen helper. bitlen(n) = floor(log2(n)) + 1 for n > 0. For ML-DSA we
+// only ever feed it positive n, so the n=0 branch is a defensive return.
+function bitlen(n) {
+    let b = 0;
+    let x = n;
+    while (x > 0) {
+        b++;
+        x >>>= 1;
+    }
+    return b;
+}
+/**
+ * ML-DSA.KeyGen_internal, FIPS 204 Algorithm 6.
+ *
+ * Input  ξ (32 bytes): the keygen seed. Produced internally by `keygen()`
+ *                      via `randomBytes(32)`, or supplied by `keygenDerand`.
+ * Output (pk, sk) byte-encoded per Alg 22 (pkEncode) and Alg 24 (skEncode).
+ *
+ * Wipe contract on return: every WASM region that held a secret or
+ * secret-derived intermediate is zeroed. Public regions (matrix Â, t₁,
+ * pk, ρ) are deliberately not wiped, they can be re-derived from the
+ * returned pk/sk anyway. The caller is expected to wipe the local ξ
+ * buffer it allocated; this function does not own that buffer.
+ */
+export function mldsaKeygenInternal(mx, sx, params, xi) {
+    const { k, l, eta, paramSet, pkBytes, skBytes } = params;
+    const mlMem = new Uint8Array(mx.memory.buffer);
+    // ── Slot offsets ────────────────────────────────────────────────────
+    const matOff = mx.getMatrixSlot();
+    const s1Off = mx.getPolyvecSlot0();
+    const s2Off = mx.getPolyvecSlot1();
+    const tOff = mx.getPolyvecSlot2();
+    const t1Off = mx.getPolyvecSlot3();
+    const t0Off = mx.getPolyvecSlot4();
+    const s1NttOff = mx.getPolyvecSlot5();
+    const seedOff = mx.getSeedOffset();
+    const pkOff = mx.getPkOffset();
+    const skOff = mx.getSkOffset();
+    const trOff = mx.getTrOffset();
+    const xofOff = mx.getXofPrfOffset();
+    // Layout cross-check at runtime: confirm the matrix-slot sizing covers
+    // this parameter set's k·ℓ polys. Cheap ratchet against future changes
+    // to buffers.ts that might shrink the region.
+    const matSize = mx.getMatrixSlotSize();
+    if (k * l * POLY_BYTES > matSize)
+        throw new Error(`leviathan-crypto: mldsa MATRIX_SLOT too small for ${paramSet} `
+            + `(needs ${k * l * POLY_BYTES}, have ${matSize})`);
+    let rho;
+    let rhoPrime;
+    let kRand;
+    let seed128;
+    try {
+        // ── Step 1: H(ξ ‖ k_byte ‖ ℓ_byte, 1024 bits) → ρ‖ρ′‖K ─────────
+        // FIPS 204 §6.1 Algorithm 6 line 1. The k/ℓ domain-separator bytes
+        // are the post-IPD addition (FIPS 204 §D.3) defending against
+        // cross-parameter-set seed reuse, IntegerToBytes(k,1) and
+        // IntegerToBytes(ℓ,1).
+        const kByte = new Uint8Array([k & 0xFF]);
+        const lByte = new Uint8Array([l & 0xFF]);
+        seed128 = shake256HashConcat(sx, [xi, kByte, lByte], 128);
+        // Mirror H output into the WASM SEED region. This isn't strictly
+        // required (we only consume ρ/ρ′/K via TS-side slices below) but
+        // it lets the keygen-scratch-wipe gate verify that the SEED region
+        // is wiped, regardless of whether we pre-staged it. Wiped on exit.
+        mlMem.set(seed128, seedOff);
+        // Split: ρ(32) ‖ ρ′(64) ‖ K(32). Slice copies isolate each piece
+        // from the seed128 buffer so we can scrub each at known life-end.
+        rho = seed128.slice(0, 32);
+        rhoPrime = seed128.slice(32, 96);
+        kRand = seed128.slice(96, 128);
+        // ── Step 2: Â ← ExpandA(ρ) ────────────────────────────────────
+        // FIPS 204 Algorithm 32. Output is in NTT domain, regular form.
+        expandA(mx, sx, params, rho, matOff);
+        // ── Step 3: (s₁, s₂) ← ExpandS(ρ′) ────────────────────────────
+        // FIPS 204 Algorithm 33. Time-domain. expandS wipes its local
+        // seed scratch on exit.
+        expandS(mx, sx, params, rhoPrime, s1Off, s2Off);
+        // ── Step 4: t ← NTT⁻¹(Â · NTT(s₁)) + s₂ ───────────────────────
+        // FIPS 204 Algorithm 6 line 5. Stages:
+        //   (a) Copy s₁ → ŝ₁-slot. Time-domain s₁ in slot_0 must survive
+        //       for the BitPack step in skEncode (Algorithm 24); the
+        //       NTT/tomont/multiply chain destroys its argument.
+        //   (b) NTT(ŝ₁) in place, regular form.
+        //   (c) tomont(ŝ₁): each coefficient ×R so that the subsequent
+        //       pointwise_montgomery's R⁻¹ leaves a regular-form product.
+        //   (d) Matrix-vector product ·ŝ₁ → polyvec_slot_2.
+        //   (e) NTT⁻¹ in place → time-domain ·s₁.
+        //   (f) Add s₂ coefficient-wise.
+        //   (g) Reduce + caddq so coefficients are canonical [0, q-1],
+        //       required by power2round per the WASM polynomial-layer contract.
+        mlMem.copyWithin(s1NttOff, s1Off, s1Off + l * POLY_BYTES);
+        mx.polyvec_ntt(s1NttOff, l);
+        mx.polyvec_tomont(s1NttOff, l);
+        mx.polyvec_matrix_pointwise_montgomery(tOff, matOff, s1NttOff, k, l);
+        mx.polyvec_invntt(tOff, k);
+        mx.polyvec_add(tOff, tOff, s2Off, k);
+        mx.polyvec_reduce(tOff, k);
+        mx.polyvec_caddq(tOff, k);
+        // ── Step 5: (t₁, t₀) ← Power2Round(t, d) ──────────────────────
+        // FIPS 204 Algorithm 35. Per-coefficient on the canonical-residue
+        // polyvec t.
+        mx.polyvec_power2round(t1Off, t0Off, tOff, k);
+        // ── Step 6: pk ← pkEncode(ρ, t₁) ──────────────────────────────
+        // FIPS 204 Algorithm 22. pk = ρ ‖ Σ SimpleBitPack(t₁[i], 2^c-1)
+        // where c = bitlen(q-1) - d = 23 - 13 = 10 → 320 bytes per poly.
+        const t1Bitlen = bitlen(8380417 - 1) - D; // 23 - 13 = 10
+        const t1PolyBytes = (256 * t1Bitlen) >> 3; // 320
+        mlMem.set(rho, pkOff);
+        for (let i = 0; i < k; i++) {
+            mx.simple_bit_pack(pkOff + 32 + i * t1PolyBytes, t1Off + i * POLY_BYTES, t1Bitlen);
+        }
+        // ── Step 7: tr ← H(pk, 512 bits) ──────────────────────────────
+        // 64-byte SHAKE256 of the public key. Cached in sk so signing
+        // doesn't have to re-derive it.
+        const pkBytesView = mlMem.subarray(pkOff, pkOff + pkBytes);
+        const tr = shake256HashConcat(sx, [pkBytesView], 64);
+        mlMem.set(tr, trOff);
+        wipe(tr);
+        // ── Step 8: sk ← skEncode(ρ, K, tr, s₁, s₂, t₀) ───────────────
+        // FIPS 204 Algorithm 24. Layout:
+        //   ρ(32) ‖ K(32) ‖ tr(64) ‖
+        //   BitPack(s₁[i], η, η)    × ℓ   each = 32·bitlen(2η)
+        //   BitPack(s₂[i], η, η)    × k
+        //   BitPack(t₀[i], 2^(d-1)-1, 2^(d-1))  × k    each = 32·d = 416
+        const etaBitlen = bitlen(2 * eta); // 3 (η=2) or 4 (η=4)
+        const etaPolyBytes = (256 * etaBitlen) >> 3; // 96 or 128
+        const t0PolyBytes = (256 * D) >> 3; // 416
+        const t0LowEdge = (1 << (D - 1)) - 1; // 4095
+        const t0HighEdge = (1 << (D - 1)); // 4096
+        mlMem.set(rho, skOff);
+        mlMem.set(kRand, skOff + 32);
+        mlMem.set(mlMem.subarray(trOff, trOff + 64), skOff + 64);
+        let off = skOff + 32 + 32 + 64; // = skOff + 128
+        for (let i = 0; i < l; i++) {
+            mx.bit_pack(off + i * etaPolyBytes, s1Off + i * POLY_BYTES, eta, eta);
+        }
+        off += l * etaPolyBytes;
+        for (let i = 0; i < k; i++) {
+            mx.bit_pack(off + i * etaPolyBytes, s2Off + i * POLY_BYTES, eta, eta);
+        }
+        off += k * etaPolyBytes;
+        for (let i = 0; i < k; i++) {
+            mx.bit_pack(off + i * t0PolyBytes, t0Off + i * POLY_BYTES, t0LowEdge, t0HighEdge);
+        }
+        off += k * t0PolyBytes;
+        // Sanity: encoded sk length must match the parameter-set size.
+        // A miscompute here is the kind of silent failure ACVP eventually
+        // catches but the layout assertion catches faster.
+        if (off - skOff !== skBytes)
+            throw new Error(`leviathan-crypto: mldsa skEncode length mismatch for ${paramSet} `
+                + `(wrote ${off - skOff}, expected ${skBytes})`);
+        // ── Step 9: slice public outputs out of WASM memory ───────────
+        // Use slice() (copy) so the returned arrays are independent of
+        // the WASM linear memory we are about to wipe.
+        const pk = mlMem.slice(pkOff, pkOff + pkBytes);
+        const sk = mlMem.slice(skOff, skOff + skBytes);
+        // Wipe scratch per FIPS 204 §3.6.3. See
+        // docs/mldsa.md#wipe-discipline for the per-region severity
+        // ranking.
+        mlMem.fill(0, seedOff, seedOff + 128); // ρ ‖ ρ′ ‖ K
+        mlMem.fill(0, trOff, trOff + 64); // tr (public-derived but no need to keep)
+        mlMem.fill(0, skOff, skOff + skBytes); // encoded sk
+        mlMem.fill(0, s1Off, s1Off + l * POLY_BYTES); // s₁ (time-domain)
+        mlMem.fill(0, s1NttOff, s1NttOff + l * POLY_BYTES); // ŝ₁ (NTT/Montgomery)
+        mlMem.fill(0, s2Off, s2Off + k * POLY_BYTES); // s₂
+        mlMem.fill(0, tOff, tOff + k * POLY_BYTES); // t
+        mlMem.fill(0, t0Off, t0Off + k * POLY_BYTES); // t₀
+        mlMem.fill(0, xofOff, xofOff + 8192); // XOF/PRF scratch
+        // SHA3 module's input/state/output regions held ρ′ chunks and
+        // the H(ξ‖k‖ℓ) output. Wipe before returning so no residue
+        // persists across the public-API boundary.
+        sx.wipeBuffers();
+        return { verificationKey: pk, signingKey: sk };
+    }
+    finally {
+        // TS-side scratch, wipe even on early throw.
+        if (seed128)
+            wipe(seed128);
+        if (rho)
+            wipe(rho);
+        if (rhoPrime)
+            wipe(rhoPrime);
+        if (kRand)
+            wipe(kRand);
+    }
+}

package/dist/mldsa/params.d.ts

@@ -0,0 +1,21 @@
+export interface MlDsaParams {
+    paramSet: 'ML-DSA-44' | 'ML-DSA-65' | 'ML-DSA-87';
+    k: number;
+    l: number;
+    eta: number;
+    tau: number;
+    lambda: number;
+    gamma1: number;
+    gamma2: number;
+    omega: number;
+    beta: number;
+    pkBytes: number;
+    skBytes: number;
+    sigBytes: number;
+}
+/** ML-DSA-44, FIPS 204 §4 Table 1 (NIST security category 2). */
+export declare const MLDSA44: MlDsaParams;
+/** ML-DSA-65, FIPS 204 §4 Table 1 (NIST security category 3). */
+export declare const MLDSA65: MlDsaParams;
+/** ML-DSA-87, FIPS 204 §4 Table 1 (NIST security category 5). */
+export declare const MLDSA87: MlDsaParams;

package/dist/mldsa/params.js

@@ -0,0 +1,55 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/params.ts
+//
+// ML-DSA (FIPS 204) parameter sets, values from §4 Table 1 and Table 2.
+//
+// Sizes are derived per parameter set:
+//   pk  = 32 + k · 32 · (bitlen(q-1) - d)       , Alg 22 pkEncode
+//   sk  = 32 + 32 + 64 + 32·((ℓ+k)·bitlen(2η) + d·k) , Alg 24 skEncode
+//   sig = λ/4 + ℓ·32·(1 + bitlen(γ₁ - 1)) + ω + k   , Alg 26 sigEncode
+//
+// β = τ · η is precomputed; it bounds ‖cs1‖∞ and ‖cs2‖∞.
+/** ML-DSA-44, FIPS 204 §4 Table 1 (NIST security category 2). */
+export const MLDSA44 = {
+    paramSet: 'ML-DSA-44',
+    k: 4, l: 4, eta: 2, tau: 39, lambda: 128,
+    gamma1: 1 << 17, gamma2: ((8380417 - 1) / 88) | 0,
+    omega: 80, beta: 39 * 2,
+    pkBytes: 1312, skBytes: 2560, sigBytes: 2420,
+};
+/** ML-DSA-65, FIPS 204 §4 Table 1 (NIST security category 3). */
+export const MLDSA65 = {
+    paramSet: 'ML-DSA-65',
+    k: 6, l: 5, eta: 4, tau: 49, lambda: 192,
+    gamma1: 1 << 19, gamma2: ((8380417 - 1) / 32) | 0,
+    omega: 55, beta: 49 * 4,
+    pkBytes: 1952, skBytes: 4032, sigBytes: 3309,
+};
+/** ML-DSA-87, FIPS 204 §4 Table 1 (NIST security category 5). */
+export const MLDSA87 = {
+    paramSet: 'ML-DSA-87',
+    k: 8, l: 7, eta: 2, tau: 60, lambda: 256,
+    gamma1: 1 << 19, gamma2: ((8380417 - 1) / 32) | 0,
+    omega: 75, beta: 60 * 2,
+    pkBytes: 2592, skBytes: 4896, sigBytes: 4627,
+};

package/dist/mldsa/sha3-helpers.d.ts

@@ -0,0 +1,30 @@
+import type { Sha3Exports } from '../mlkem/types.js';
+/** Absorb msg into the sponge in ≤168-byte chunks. Caller must have
+ *  already invoked the appropriate Init function (shake128Init etc.). */
+export declare function sha3Absorb(sx: Sha3Exports, msg: Uint8Array): void;
+/** SHAKE256(msg, n), fixed-length output. Resets sha3 state. */
+export declare function shake256Hash(sx: Sha3Exports, msg: Uint8Array, n: number): Uint8Array;
+/** SHAKE256(p₀ ‖ p₁ ‖ … ‖ p_{n-1}, outLen). Avoids the temporary buffer
+ *  callers would otherwise allocate just to concatenate fixed-size pieces.
+ *  Used for keygen's H(ξ ‖ k_byte ‖ ℓ_byte, 128). */
+export declare function shake256HashConcat(sx: Sha3Exports, parts: readonly Uint8Array[], outLen: number): Uint8Array;
+/**
+ * Set up SHAKE128 over `seed` and return an incremental block-squeezer.
+ * Each call returns the next 168-byte block as a Uint8Array view into the
+ * sha3 OUT region (lifetime: until the next squeeze call). Callers copy
+ * into the consuming module's XOF buffer before invoking the rejection
+ * sampler. Used by ExpandA (FIPS 204 Algorithm 32, RejNTTPoly driver).
+ */
+export declare function shake128Squeezer(sx: Sha3Exports, seed: Uint8Array): {
+    rate: number;
+    squeeze: () => Uint8Array;
+};
+/**
+ * Set up SHAKE256 over `seed` and return an incremental block-squeezer.
+ * Same shape as shake128Squeezer with rate 136. Used by ExpandS
+ * (FIPS 204 Algorithm 33, RejBoundedPoly driver).
+ */
+export declare function shake256Squeezer(sx: Sha3Exports, seed: Uint8Array): {
+    rate: number;
+    squeeze: () => Uint8Array;
+};

package/dist/mldsa/sha3-helpers.js

@@ -0,0 +1,124 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/sha3-helpers.ts
+//
+// SHAKE-driving helpers shared by ExpandA / ExpandS / keygen / sign / verify.
+// All operate directly on raw Sha3Exports; no init() system involved.
+//
+// ML-DSA uses both SHAKE rates (FIPS 202): SHAKE128 (rate 168) for ExpandA
+// and SHAKE256 (rate 136) for the rest of the scheme. The absorb path is
+// rate-agnostic, keccakAbsorb consumes whatever buffer length the caller
+// hands it as long as length ≤ 168 (the wider rate). One-shot SHAKE256
+// helpers and the incremental SHAKE128 / SHAKE256 squeezers below cover
+// every call shape ML-DSA needs.
+const SHAKE128_RATE = 168;
+const SHAKE256_RATE = 136;
+/** Absorb msg into the sponge in ≤168-byte chunks. Caller must have
+ *  already invoked the appropriate Init function (shake128Init etc.). */
+export function sha3Absorb(sx, msg) {
+    const mem = new Uint8Array(sx.memory.buffer);
+    const inOff = sx.getInputOffset();
+    let pos = 0;
+    while (pos < msg.length) {
+        const chunk = Math.min(msg.length - pos, SHAKE128_RATE);
+        mem.set(msg.subarray(pos, pos + chunk), inOff);
+        sx.keccakAbsorb(chunk);
+        pos += chunk;
+    }
+}
+/** SHAKE256(msg, n), fixed-length output. Resets sha3 state. */
+export function shake256Hash(sx, msg, n) {
+    sx.shake256Init();
+    sha3Absorb(sx, msg);
+    sx.shakePad();
+    const sha3Mem = new Uint8Array(sx.memory.buffer);
+    const outOff = sx.getOutOffset();
+    const out = new Uint8Array(n);
+    let pos = 0;
+    while (pos < n) {
+        sx.shakeSqueezeBlock();
+        const take = Math.min(n - pos, SHAKE256_RATE);
+        out.set(sha3Mem.subarray(outOff, outOff + take), pos);
+        pos += take;
+    }
+    return out;
+}
+/** SHAKE256(p₀ ‖ p₁ ‖ … ‖ p_{n-1}, outLen). Avoids the temporary buffer
+ *  callers would otherwise allocate just to concatenate fixed-size pieces.
+ *  Used for keygen's H(ξ ‖ k_byte ‖ ℓ_byte, 128). */
+export function shake256HashConcat(sx, parts, outLen) {
+    sx.shake256Init();
+    for (const p of parts)
+        sha3Absorb(sx, p);
+    sx.shakePad();
+    const sha3Mem = new Uint8Array(sx.memory.buffer);
+    const outOff = sx.getOutOffset();
+    const out = new Uint8Array(outLen);
+    let pos = 0;
+    while (pos < outLen) {
+        sx.shakeSqueezeBlock();
+        const take = Math.min(outLen - pos, SHAKE256_RATE);
+        out.set(sha3Mem.subarray(outOff, outOff + take), pos);
+        pos += take;
+    }
+    return out;
+}
+/**
+ * Set up SHAKE128 over `seed` and return an incremental block-squeezer.
+ * Each call returns the next 168-byte block as a Uint8Array view into the
+ * sha3 OUT region (lifetime: until the next squeeze call). Callers copy
+ * into the consuming module's XOF buffer before invoking the rejection
+ * sampler. Used by ExpandA (FIPS 204 Algorithm 32, RejNTTPoly driver).
+ */
+export function shake128Squeezer(sx, seed) {
+    sx.shake128Init();
+    sha3Absorb(sx, seed);
+    sx.shakePad();
+    const sha3Mem = new Uint8Array(sx.memory.buffer);
+    const outOff = sx.getOutOffset();
+    return {
+        rate: SHAKE128_RATE,
+        squeeze: () => {
+            sx.shakeSqueezeBlock();
+            return sha3Mem.subarray(outOff, outOff + SHAKE128_RATE);
+        },
+    };
+}
+/**
+ * Set up SHAKE256 over `seed` and return an incremental block-squeezer.
+ * Same shape as shake128Squeezer with rate 136. Used by ExpandS
+ * (FIPS 204 Algorithm 33, RejBoundedPoly driver).
+ */
+export function shake256Squeezer(sx, seed) {
+    sx.shake256Init();
+    sha3Absorb(sx, seed);
+    sx.shakePad();
+    const sha3Mem = new Uint8Array(sx.memory.buffer);
+    const outOff = sx.getOutOffset();
+    return {
+        rate: SHAKE256_RATE,
+        squeeze: () => {
+            sx.shakeSqueezeBlock();
+            return sha3Mem.subarray(outOff, outOff + SHAKE256_RATE);
+        },
+    };
+}

package/dist/mldsa/sign.d.ts

@@ -0,0 +1,36 @@
+import type { MlDsaExports, Sha3Exports } from './types.js';
+import type { MlDsaParams } from './params.js';
+import { type PreHashAlgorithm } from './hashvariant.js';
+/**
+ * ML-DSA.Sign_internal, FIPS 204 Algorithm 7.
+ *
+ * Inputs:
+ *   sk    , encoded signing key (skBytes per parameter set)
+ *   MPrime, domain-separated message bytes (caller-built via constructMPrime)
+ *   rnd   , 32-byte randomness (random for hedged, all-zero for deterministic,
+ *            caller-supplied for derand/CAVP)
+ *
+ * Output: σ (sigBytes), encoded per Algorithm 26 (sigEncode).
+ *
+ * Wipe contract: every WASM region that held a secret or secret-derived
+ * intermediate is zeroed before return. TS-side scratch (μ, ρ'', c̃, the
+ * w1 byte slice) wipes via try/finally even on early throw.
+ */
+export declare function mldsaSignInternal(mx: MlDsaExports, sx: Sha3Exports, params: MlDsaParams, sk: Uint8Array, MPrime: Uint8Array, rnd: Uint8Array): Uint8Array;
+/**
+ * HashML-DSA sign, post-prehash. FIPS 204 §5.4 Algorithm 4 lines 22-24.
+ * Builds M' = 0x01 ‖ |ctx| ‖ ctx ‖ OID(algo) ‖ prehash and drives
+ * Sign_internal with the caller-supplied rnd.
+ *
+ * The caller owns `prehash` (it may be a slice of WASM memory, a
+ * caller-controlled digest, or an internally-computed PH_M); this helper
+ * never wipes it. The caller also owns `rnd` (hedged: caller wipes a
+ * freshly-generated value; deterministic: rnd is zeros, no wipe; derand:
+ * caller-supplied per FIPS 204 §3.4 contract).
+ *
+ * The 12 approved pre-hash functions (`algo`) and their OIDs are FIPS 204
+ * §5.4.1's full catalog. Domain-sep byte 0x01 inside the M' construction
+ * separates HashML-DSA signatures from pure-ML-DSA signatures on the same
+ * key per §3.6.4.
+ */
+export declare function signWithPrehash(mx: MlDsaExports, sx: Sha3Exports, params: MlDsaParams, sk: Uint8Array, prehash: Uint8Array, algo: PreHashAlgorithm, ctx: Uint8Array, rnd: Uint8Array): Uint8Array;