leviathan-crypto 2.0.1 → 3.0.0

package/dist/mldsa/sign.js

@@ -0,0 +1,380 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/sign.ts
+//
+// FIPS 204 §6.2 Algorithm 7, ML-DSA.Sign_internal. Drives the
+// rejection-sampling loop; wipe contract per §3.6.3 (see
+// docs/mldsa.md#wipe-discipline).
+//
+// Slot allocation through one iteration body:
+//   POLYVEC_SLOT_0  ŝ₁  (NTT, persistent through loop)
+//   POLYVEC_SLOT_1  ŝ₂  (NTT, persistent)
+//   POLYVEC_SLOT_2  t̂₀  (NTT, persistent)
+//   POLYVEC_SLOT_3  y_time → ⟨cs₂⟩ → r₀ → ⟨ct₀⟩ → h
+//   POLYVEC_SLOT_4  y_ntt → w₁ → ⟨cs₁⟩ → z
+//   POLYVEC_SLOT_5  w_ntt → w_time → (w − ⟨cs₂⟩)
+//   POLY_SLOT_0     signs (sample_in_ball signsOff)
+//   POLY_SLOT_1     c, then ĉ (NTT-domain)
+//   POLY_SLOT_7     polyvec_pointwise_acc_montgomery scratch
+//
+// XOF/PRF carries ExpandMask, w1Encode, and SampleInBall bytes; each
+// single-use per iteration.
+import { wipe } from '../utils.js';
+import { sha3Absorb, shake256HashConcat } from './sha3-helpers.js';
+import { expandA, expandMask } from './expand.js';
+import { getOid } from './hashvariant.js';
+import { constructMPrimeHash } from './format.js';
+const POLY_BYTES = 1024;
+const D = 13;
+const Q = 8380417;
+const SHAKE256_RATE = 136;
+// FIPS 204 Appendix C: expected 4-7 iterations, spec minimum bound 814.
+// 1000 is a liveness bound, not a probability tail-cut.
+const MAX_SIGN_ITERATIONS = 1000;
+function bitlen(n) {
+    let b = 0;
+    let x = n;
+    while (x > 0) {
+        b++;
+        x >>>= 1;
+    }
+    return b;
+}
+/**
+ * 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 function mldsaSignInternal(mx, sx, params, sk, MPrime, rnd) {
+    const { k, l, eta, tau, lambda, gamma1, gamma2, beta, omega, sigBytes } = params;
+    const lambdaOver4 = lambda >>> 2; // 32 / 48 / 64
+    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
+    const c = 1 + bitlen(gamma1 - 1); // 18 or 20
+    const zPolyBytes = 32 * c; // 576 or 640
+    // w₁ field: m = (q − 1) / (2γ₂); width = bitlen(m − 1).
+    // γ₂=(q-1)/88 ⇒ m=44 ⇒ width=6;  γ₂=(q-1)/32 ⇒ m=16 ⇒ width=4.
+    const w1Bitlen = bitlen(((Q - 1) / (2 * gamma2)) - 1);
+    const w1PolyBytes = (256 * w1Bitlen) >> 3;
+    const w1TotalBytes = k * w1PolyBytes;
+    // ── WASM offsets ─────────────────────────────────────────────────────
+    const matOff = mx.getMatrixSlot();
+    const slot0 = mx.getPolyvecSlot0(); // ŝ₁
+    const slot1 = mx.getPolyvecSlot1(); // ŝ₂
+    const slot2 = mx.getPolyvecSlot2(); // t̂₀
+    const slot3 = mx.getPolyvecSlot3(); // y_time / ⟨cs₂⟩ / r₀ / ⟨ct₀⟩ / h
+    const slot4 = mx.getPolyvecSlot4(); // y_ntt / w₁ / ⟨cs₁⟩ / z
+    const slot5 = mx.getPolyvecSlot5(); // w / w − ⟨cs₂⟩
+    const polySlotBase = mx.getPolySlotBase();
+    const polySlot0 = mx.getPolySlot0(); // signs (8 bytes)
+    const polySlot1 = mx.getPolySlot1(); // c → ĉ
+    const sigOff = mx.getSigOffset();
+    const xofOff = mx.getXofPrfOffset();
+    const seedOff = mx.getSeedOffset();
+    const trOff = mx.getTrOffset();
+    const skOff = mx.getSkOffset();
+    const cTildeOff = mx.getCTildeOffset();
+    const msgRepOff = mx.getMsgRepOffset();
+    const mlMem = new Uint8Array(mx.memory.buffer);
+    const sha3Mem = new Uint8Array(sx.memory.buffer);
+    const sha3OutOff = sx.getOutOffset();
+    // ── TS-side sensitive buffers, wiped in finally ─────────────────────
+    let mu;
+    let rhoPP;
+    let cTilde;
+    let w1Bytes;
+    try {
+        // ── skDecode, FIPS 204 §7.2 Algorithm 25 ────────────────────────
+        // sk = ρ ‖ K ‖ tr ‖ s₁ ‖ s₂ ‖ t₀  (offsets per Algorithm 24).
+        const rho = sk.subarray(0, 32);
+        const K = sk.subarray(32, 64);
+        const tr = sk.subarray(64, 128);
+        let off = 128;
+        // s₁, ℓ polynomials, BitUnpack(η, η) per Alg 25 line 4
+        for (let r = 0; r < l; r++) {
+            mlMem.set(sk.subarray(off, off + etaPolyBytes), xofOff);
+            mx.bit_unpack(slot0 + r * POLY_BYTES, xofOff, eta, eta);
+            off += etaPolyBytes;
+        }
+        // FIPS 204 §7.2 / Alg 25 line 5: s₁ coefficients must lie in [-η, η].
+        // bit_unpack at width bitlen(2η) overshoots that range for η ∈ {2,4}
+        // (η=2 yields [-5, 2]; η=4 yields [-11, 4]) when sk bytes are tampered
+        // or corrupted, reject before producing a wrong signature.
+        if (mx.polyvec_chknorm(slot0, eta + 1, l) !== 0)
+            throw new RangeError('leviathan-crypto: signing key s₁ coefficient out of [-η, η]');
+        // s₂, k polynomials, BitUnpack(η, η)
+        for (let r = 0; r < k; r++) {
+            mlMem.set(sk.subarray(off, off + etaPolyBytes), xofOff);
+            mx.bit_unpack(slot1 + r * POLY_BYTES, xofOff, eta, eta);
+            off += etaPolyBytes;
+        }
+        if (mx.polyvec_chknorm(slot1, eta + 1, k) !== 0)
+            throw new RangeError('leviathan-crypto: signing key s₂ coefficient out of [-η, η]');
+        // t₀, k polynomials, BitUnpack(2^(d-1)-1, 2^(d-1)), Alg 25 line 6
+        // bit_unpack(2^(d-1)-1, 2^(d-1)) decodes exactly to [-(2^(d-1)-1), 2^(d-1)]
+        // which matches the spec range, no caddq-style range check needed.
+        for (let r = 0; r < k; r++) {
+            mlMem.set(sk.subarray(off, off + t0PolyBytes), xofOff);
+            mx.bit_unpack(slot2 + r * POLY_BYTES, xofOff, t0LowEdge, t0HighEdge);
+            off += t0PolyBytes;
+        }
+        // ── FIPS 204 Alg 7 lines 2-5: ŝ₁ ← NTT(s₁); ŝ₂ ← NTT(s₂);
+        //                             t̂₀ ← NTT(t₀); Â ← ExpandA(ρ) ────
+        // Each NTT'd polyvec is then tomont'd so subsequent
+        // poly_pointwise_montgomery products with a regular-form ĉ yield
+        // regular (non-Montgomery) results, matches the keygen tomont
+        // pattern (src/ts/mldsa/keygen.ts step 4 (c)). Without tomont the
+        // post-invNTT values carry an extra R⁻¹ factor and ACVP fails.
+        mx.polyvec_ntt(slot0, l);
+        mx.polyvec_tomont(slot0, l);
+        mx.polyvec_ntt(slot1, k);
+        mx.polyvec_tomont(slot1, k);
+        mx.polyvec_ntt(slot2, k);
+        mx.polyvec_tomont(slot2, k);
+        expandA(mx, sx, params, rho, matOff);
+        // ── Line 6: μ ← H(BytesToBits(tr) ‖ M', 64) ───────────────────────
+        // Byte-oriented SHAKE wrapper: BytesToBits is a no-op (we absorb tr
+        // directly). ACVP gates byte-equality of μ implicitly through σ
+        // equality on the deterministic-rnd vectors.
+        mu = shake256HashConcat(sx, [tr, MPrime], 64);
+        // ── Line 7: ρ'' ← H(K ‖ rnd ‖ μ, 64) ──────────────────────────────
+        rhoPP = shake256HashConcat(sx, [K, rnd, mu], 64);
+        // ── Line 8: κ ← 0 ────────────────────────────────────────────────
+        let kappa = 0;
+        cTilde = new Uint8Array(lambdaOver4);
+        let success = false;
+        // ── Line 10-31: rejection-sampling loop ──────────────────────────
+        for (let iter = 0; iter < MAX_SIGN_ITERATIONS; iter++) {
+            // Line 11: y ← ExpandMask(ρ'', κ) at slot3 (time domain) ──────
+            expandMask(mx, sx, params, rhoPP, kappa, slot3);
+            // Line 12: w ← NTT⁻¹(Â · NTT(y))
+            // Copy y_time → slot4, NTT in place, matrix product → slot5,
+            // inverse NTT → time domain, caddq → canonical for HighBits.
+            mlMem.copyWithin(slot4, slot3, slot3 + l * POLY_BYTES);
+            mx.polyvec_ntt(slot4, l); // ŷ at slot4 (regular)
+            mx.polyvec_tomont(slot4, l); // ŷ ← ŷ·R so the matrix kernel's R⁻¹ leaves regular result
+            mx.polyvec_matrix_pointwise_montgomery(slot5, matOff, slot4, k, l);
+            mx.polyvec_invntt(slot5, k);
+            mx.polyvec_caddq(slot5, k); // w canonical at slot5
+            // Line 13: w₁ ← HighBits(w) at slot4 (overwrites ŷ, no longer needed)
+            mx.polyvec_highbits(slot4, slot5, k, gamma2);
+            // Line 14: c̃ ← H(μ ‖ w₁Encode(w₁), λ/4) ─────────────────────
+            // w₁Encode = Σ SimpleBitPack(w₁[i], (q-1)/(2γ₂) - 1), width per param set.
+            for (let r = 0; r < k; r++) {
+                mx.simple_bit_pack(xofOff + r * w1PolyBytes, slot4 + r * POLY_BYTES, w1Bitlen);
+            }
+            // w₁ from a rejected iteration is secret-derived (HighBits
+            // of NTT⁻¹(Â · NTT(y)); y came from ρ''). Wipe the prior
+            // slice before reslicing fresh bytes for this iteration.
+            if (w1Bytes)
+                wipe(w1Bytes);
+            w1Bytes = mlMem.slice(xofOff, xofOff + w1TotalBytes);
+            const cTildeNew = shake256HashConcat(sx, [mu, w1Bytes], lambdaOver4);
+            cTilde.set(cTildeNew);
+            // cTildeNew is public-derivable (c̃ ships inside σ) but TS-side
+            // hygiene matches the rest of the per-iteration scratch.
+            wipe(cTildeNew);
+            // Line 15: c ← SampleInBall(c̃) at polySlot1 (time domain) ──
+            // FIPS 204 Algorithm 29: SHAKE256(c̃) drives sign-bits (first
+            // 8 squeeze bytes) and position selection (subsequent bytes).
+            // Resumable kernel, squeeze further blocks until all τ samples
+            // land. polySlot0 is signs scratch; xofOff is position bytes.
+            mlMem.fill(0, polySlot1, polySlot1 + POLY_BYTES);
+            sx.shake256Init();
+            sha3Absorb(sx, cTilde);
+            sx.shakePad();
+            sx.shakeSqueezeBlock();
+            mlMem.set(sha3Mem.subarray(sha3OutOff, sha3OutOff + 8), polySlot0);
+            mlMem.set(sha3Mem.subarray(sha3OutOff + 8, sha3OutOff + SHAKE256_RATE), xofOff);
+            let sampleI = mx.sample_in_ball(polySlot1, polySlot0, xofOff, SHAKE256_RATE - 8, tau, 256 - tau);
+            while (sampleI < 256) {
+                sx.shakeSqueezeBlock();
+                mlMem.set(sha3Mem.subarray(sha3OutOff, sha3OutOff + SHAKE256_RATE), xofOff);
+                sampleI = mx.sample_in_ball(polySlot1, polySlot0, xofOff, SHAKE256_RATE, tau, sampleI);
+            }
+            // Line 16: ĉ ← NTT(c), single polynomial in place ─────────
+            mx.ntt(polySlot1);
+            // Line 17: ⟨cs₁⟩ ← NTT⁻¹(ĉ ∘ ŝ₁) at slot4 (overwrites w₁) ──
+            // The WASM polynomial layer exposes poly_pointwise_montgomery
+            // (per-poly) and polyvec_pointwise_montgomery (per-vec,
+            // expects same-length input). For c·s₁ where c is one
+            // polynomial and s₁ is a length-ℓ vec, drive a TS-side loop
+            // over the poly variant.
+            for (let r = 0; r < l; r++) {
+                mx.poly_pointwise_montgomery(slot4 + r * POLY_BYTES, polySlot1, slot0 + r * POLY_BYTES);
+            }
+            mx.polyvec_invntt(slot4, l);
+            // Line 19: z ← y + ⟨cs₁⟩ at slot4 ──────────────────────────
+            mx.polyvec_add(slot4, slot3, slot4, l);
+            // ‖z‖∞ check needs centered residues. polyvec_reduce produces
+            // (-q/2, q/2]; chknorm is correct on that form per the
+            // WASM polynomial-layer contract.
+            mx.polyvec_reduce(slot4, l);
+            // Line 21 (first half): ‖z‖∞ ≥ γ₁ − β ⇒ reject ─────────────
+            if (mx.polyvec_chknorm(slot4, gamma1 - beta, l) !== 0) {
+                kappa += l;
+                continue;
+            }
+            // Line 18: ⟨cs₂⟩ ← NTT⁻¹(ĉ ∘ ŝ₂) at slot3 (overwrites y_time) ─
+            for (let r = 0; r < k; r++) {
+                mx.poly_pointwise_montgomery(slot3 + r * POLY_BYTES, polySlot1, slot1 + r * POLY_BYTES);
+            }
+            mx.polyvec_invntt(slot3, k);
+            mx.polyvec_reduce(slot3, k);
+            mx.polyvec_caddq(slot3, k); // canonical for sub→reduce→caddq round-trip
+            // Line 20: r₀ ← LowBits(w − ⟨cs₂⟩). Compute (w − ⟨cs₂⟩) at
+            // slot5 (overwrites w, we no longer need w independently;
+            // downstream both r₀ and h derive from w − ⟨cs₂⟩).
+            mx.polyvec_sub(slot5, slot5, slot3, k);
+            mx.polyvec_reduce(slot5, k);
+            mx.polyvec_caddq(slot5, k); // canonical for lowbits + make_hint
+            // r₀ at slot3 (overwrites ⟨cs₂⟩, no longer needed)
+            mx.polyvec_lowbits(slot3, slot5, k, gamma2);
+            // Line 21 (second half): ‖r₀‖∞ ≥ γ₂ − β ⇒ reject ──────────
+            if (mx.polyvec_chknorm(slot3, gamma2 - beta, k) !== 0) {
+                kappa += l;
+                continue;
+            }
+            // Line 24: ⟨ct₀⟩ ← NTT⁻¹(ĉ ∘ t̂₀) at slot3 (overwrites r₀) ─
+            for (let r = 0; r < k; r++) {
+                mx.poly_pointwise_montgomery(slot3 + r * POLY_BYTES, polySlot1, slot2 + r * POLY_BYTES);
+            }
+            mx.polyvec_invntt(slot3, k);
+            mx.polyvec_reduce(slot3, k); // centered for chknorm
+            // Line 26 (first half): ‖⟨ct₀⟩‖∞ ≥ γ₂ ⇒ reject. Note the
+            // bound is γ₂ (NOT γ₂ − β), the missing β subtract is a
+            // common copy/paste error.
+            if (mx.polyvec_chknorm(slot3, gamma2, k) !== 0) {
+                kappa += l;
+                continue;
+            }
+            mx.polyvec_caddq(slot3, k); // canonical for make_hint z input
+            // Line 25: h ← MakeHint(−⟨ct₀⟩, w − ⟨cs₂⟩ + ⟨ct₀⟩).
+            // MakeHint(z, r) = [HighBits(r) ≠ HighBits(r + z)] is symmetric
+            // in (r, r+z), so passing z = ⟨ct₀⟩ and r = w − ⟨cs₂⟩ produces
+            // h[i] = [HighBits(w − ⟨cs₂⟩) ≠ HighBits(w − ⟨cs₂⟩ + ⟨ct₀⟩)],
+            // the same predicate. Avoids the explicit −⟨ct₀⟩ canonicalise.
+            // polyvec_make_hint aliases-safe with z; h overwrites slot3.
+            const popcount = mx.polyvec_make_hint(slot3, slot3, slot5, k, gamma2);
+            // Line 26 (second half): popcount > ω ⇒ reject ─────────────
+            if (popcount > omega) {
+                kappa += l;
+                continue;
+            }
+            // All four hard checks passed, encode signature.
+            // Line 32: σ ← sigEncode(c̃, z mod± q, h), Algorithm 26.
+            mlMem.set(cTilde, sigOff); // c̃ (λ/4 bytes)
+            const sigZOff = sigOff + lambdaOver4;
+            for (let r = 0; r < l; r++) {
+                // z is in centered residues post polyvec_reduce; bit_pack(γ₁-1, γ₁)
+                // expects [-(γ₁-1), γ₁]. ‖z‖∞ < γ₁ - β guarantees range.
+                mx.bit_pack(sigZOff + r * zPolyBytes, slot4 + r * POLY_BYTES, gamma1 - 1, gamma1);
+            }
+            mx.hint_bit_pack(sigZOff + l * zPolyBytes, slot3, k, omega);
+            success = true;
+            break;
+        }
+        if (!success) {
+            throw new Error(`leviathan-crypto: ML-DSA signing exceeded ${MAX_SIGN_ITERATIONS} rejection-sample iterations`
+                + ' (FIPS 204 Appendix C suggests min 814; bound here gives ~20% headroom)');
+        }
+        // Slice σ before any wipes, slice copies, so wipes after this
+        // don't touch the returned Uint8Array.
+        const sig = mlMem.slice(sigOff, sigOff + sigBytes);
+        return sig;
+    }
+    finally {
+        // Wipe scratch per FIPS 204 §3.6.3. Runs in finally so success
+        // and early-throw paths both clear. See
+        // docs/mldsa.md#wipe-discipline.
+        mlMem.fill(0, mx.getPolyvecSlotBase(), mx.getPolyvecSlotBase() + 6 * mx.getPolyvecSlotSize());
+        // Poly slots: signs (POLY_SLOT_0, public, c̃ derived), c (POLY_SLOT_1,
+        // public, derivable from c̃), and POLY_SLOT_7 holding the last
+        // matrix-vector product partial (secret-derived via y_ntt). Wipe all
+        // 8 contiguous slots in one fill, cheap and avoids residue gaps.
+        mlMem.fill(0, polySlotBase, polySlotBase + 8 * POLY_BYTES);
+        // XOF/PRF region last held SampleInBall position bytes (public, c̃-derived)
+        // or ExpandMask outputs (secret, ρ''-derived) on the rejected path.
+        mlMem.fill(0, xofOff, xofOff + 8192);
+        // Public-derivable but cheap to wipe for hygiene:
+        mlMem.fill(0, cTildeOff, cTildeOff + 64);
+        mlMem.fill(0, msgRepOff, msgRepOff + 64);
+        // Defensive: SEED, TR, SK regions, Sign_internal does not write
+        // to these (we extract sk components via TS subarrays), but a
+        // prior op may have left residue. Cheap wipe closes that window.
+        mlMem.fill(0, seedOff, seedOff + 128);
+        mlMem.fill(0, trOff, trOff + 64);
+        mlMem.fill(0, skOff, skOff + params.skBytes);
+        // SHA3 module: STATE / INPUT / OUT all carried K, μ, ρ'', c̃, and
+        // the SampleInBall stream. Wipe before returning.
+        sx.wipeBuffers();
+        // TS-side scratch, wipe last so any wipe()-throws don't skip
+        // the WASM cleanup above.
+        if (mu)
+            wipe(mu);
+        if (rhoPP)
+            wipe(rhoPP);
+        if (cTilde)
+            wipe(cTilde);
+        if (w1Bytes)
+            wipe(w1Bytes);
+    }
+}
+/**
+ * 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 function signWithPrehash(mx, sx, params, sk, prehash, algo, ctx, rnd) {
+    const oid = getOid(algo);
+    const MPrime = constructMPrimeHash(ctx, oid, prehash);
+    try {
+        return mldsaSignInternal(mx, sx, params, sk, MPrime, rnd);
+    }
+    finally {
+        wipe(MPrime);
+    }
+}

package/dist/mldsa/types.d.ts

@@ -0,0 +1,91 @@
+export interface MlDsaExports {
+    memory: WebAssembly.Memory;
+    getModuleId: () => number;
+    getMemoryPages: () => number;
+    getPolySlotBase: () => number;
+    getPolySlotSize: () => number;
+    getPolySlot0: () => number;
+    getPolySlot1: () => number;
+    getPolySlot2: () => number;
+    getPolySlot3: () => number;
+    getPolySlot4: () => number;
+    getPolySlot5: () => number;
+    getPolySlot6: () => number;
+    getPolySlot7: () => number;
+    getMatrixSlot: () => number;
+    getMatrixSlotSize: () => number;
+    getPolyvecSlotBase: () => number;
+    getPolyvecSlotSize: () => number;
+    getPolyvecSlot0: () => number;
+    getPolyvecSlot1: () => number;
+    getPolyvecSlot2: () => number;
+    getPolyvecSlot3: () => number;
+    getPolyvecSlot4: () => number;
+    getPolyvecSlot5: () => number;
+    getPolyvecSlot6: () => number;
+    getPolyvecSlot7: () => number;
+    getSeedOffset: () => number;
+    getTrOffset: () => number;
+    getMsgRepOffset: () => number;
+    getCTildeOffset: () => number;
+    getPkOffset: () => number;
+    getSkOffset: () => number;
+    getSigOffset: () => number;
+    getXofPrfOffset: () => number;
+    wipeBuffers: () => void;
+    montgomery_reduce: (a: bigint) => number;
+    barrett_reduce: (a: number) => number;
+    fqmul: (a: number, b: number) => number;
+    getZetasOffset: () => number;
+    getZeta: (i: number) => number;
+    BitRev8: (m: number) => number;
+    ntt: (polyOff: number) => void;
+    invntt: (polyOff: number) => void;
+    poly_add: (rOff: number, aOff: number, bOff: number) => void;
+    poly_sub: (rOff: number, aOff: number, bOff: number) => void;
+    poly_reduce: (polyOff: number) => void;
+    poly_caddq: (polyOff: number) => void;
+    poly_pointwise_montgomery: (rOff: number, aOff: number, bOff: number) => void;
+    poly_freeze: (polyOff: number) => void;
+    poly_chknorm: (polyOff: number, bound: number) => number;
+    poly_tomont: (polyOff: number) => void;
+    simple_bit_pack: (rByteOff: number, polyOff: number, bitlen: number) => void;
+    bit_pack: (rByteOff: number, polyOff: number, a: number, b: number) => void;
+    simple_bit_unpack: (polyOff: number, vByteOff: number, bitlen: number) => void;
+    bit_unpack: (polyOff: number, vByteOff: number, a: number, b: number) => void;
+    hint_bit_pack: (rByteOff: number, hPvOff: number, k: number, omega: number) => void;
+    hint_bit_unpack: (hPvOff: number, vByteOff: number, k: number, omega: number) => number;
+    power2round: (r1Off: number, r0Off: number, aOff: number) => void;
+    decompose: (r1Off: number, r0Off: number, aOff: number, gamma2: number) => void;
+    highbits: (rOff: number, aOff: number, gamma2: number) => void;
+    lowbits: (rOff: number, aOff: number, gamma2: number) => void;
+    make_hint: (hOff: number, zOff: number, rOff: number, gamma2: number) => void;
+    use_hint: (rOff: number, hOff: number, aOff: number, gamma2: number) => void;
+    polyvec_add: (rOff: number, aOff: number, bOff: number, len: number) => void;
+    polyvec_sub: (rOff: number, aOff: number, bOff: number, len: number) => void;
+    polyvec_reduce: (pvOff: number, len: number) => void;
+    polyvec_caddq: (pvOff: number, len: number) => void;
+    polyvec_freeze: (pvOff: number, len: number) => void;
+    polyvec_tomont: (pvOff: number, len: number) => void;
+    polyvec_ntt: (pvOff: number, len: number) => void;
+    polyvec_invntt: (pvOff: number, len: number) => void;
+    polyvec_pointwise_montgomery: (rOff: number, aOff: number, bOff: number, len: number) => void;
+    polyvec_pointwise_acc_montgomery: (rPolyOff: number, aPvOff: number, bPvOff: number, len: number) => void;
+    polyvec_matrix_pointwise_montgomery: (rPvOff: number, matOff: number, vPvOff: number, k: number, l: number) => void;
+    polyvec_chknorm: (pvOff: number, bound: number, len: number) => number;
+    polyvec_power2round: (r1pvOff: number, r0pvOff: number, aPvOff: number, len: number) => void;
+    polyvec_decompose: (r1pvOff: number, r0pvOff: number, aPvOff: number, len: number, gamma2: number) => void;
+    polyvec_highbits: (rPvOff: number, aPvOff: number, len: number, gamma2: number) => void;
+    polyvec_lowbits: (rPvOff: number, aPvOff: number, len: number, gamma2: number) => void;
+    polyvec_make_hint: (hPvOff: number, zPvOff: number, rPvOff: number, len: number, gamma2: number) => number;
+    polyvec_use_hint: (rPvOff: number, hPvOff: number, aPvOff: number, len: number, gamma2: number) => void;
+    rej_ntt_poly: (polyOff: number, ctrStart: number, bufOff: number, bufLen: number) => number;
+    rej_bounded_poly: (polyOff: number, ctrStart: number, bufOff: number, bufLen: number, eta: number) => number;
+    sample_in_ball: (polyOff: number, signsOff: number, posBytesOff: number, posBytesLen: number, tau: number, startI: number) => number;
+}
+export type { Sha3Exports } from '../mlkem/types.js';
+/** ML-DSA key pair returned by keygen / keygenDerand. */
+export interface MlDsaKeyPair {
+    verificationKey: Uint8Array;
+    signingKey: Uint8Array;
+}

package/dist/mldsa/types.js

@@ -0,0 +1,25 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/types.ts
+//
+// ML-DSA type definitions: WASM export interfaces and signature API types.
+export {};

package/dist/mldsa/validate.d.ts

@@ -0,0 +1,55 @@
+import type { MlDsaParams } from './params.js';
+import { type PreHashAlgorithm } from './hashvariant.js';
+/**
+ * FIPS 204 §5.2 / §5.3 line 1, ctx must be ≤ 255 bytes (the byte that
+ * follows the domain separator in M' is ctx.length, so longer values
+ * cannot be encoded).
+ */
+export declare function validateContext(ctx: Uint8Array): void;
+/**
+ * FIPS 204 §3.6.2, verification key must be exactly pkBytes long for
+ * its parameter set. Throws here; the public verify() method catches
+ * the throw and returns false so wrong-length pk reads as "not a valid
+ * signature" rather than a caller error.
+ */
+export declare function validateVerificationKey(vk: Uint8Array, params: MlDsaParams): void;
+/**
+ * Signing key must be exactly skBytes long for its parameter set. Wrong
+ * length is a caller error (the caller produced this sk via keygen* or
+ * loaded it from storage they own); throw RangeError unconditionally.
+ */
+export declare function validateSigningKey(sk: Uint8Array, params: MlDsaParams): void;
+/**
+ * FIPS 204 §3.6.2, signature must be exactly sigBytes long for its
+ * parameter set. Throws here; the public verify() method catches and
+ * returns false (same protocol shape as wrong-length pk).
+ */
+export declare function validateSignature(sig: Uint8Array, params: MlDsaParams): void;
+/**
+ * FIPS 204 Algorithm 7 line 1, rnd must be 32 bytes. Used by signDerand
+ * (the testing/CAVP API). Hedged sign supplies rnd internally; deterministic
+ * sign uses zeros; only signDerand exposes rnd to the caller.
+ */
+export declare function validateRnd(rnd: Uint8Array): void;
+/**
+ * Confirms M is a Uint8Array. FIPS 204 places no length restriction on
+ * the message, M is absorbed into a SHAKE256 sponge (μ derivation,
+ * §6.2/§6.3) so any byte length is admissible. The bit-vs-byte
+ * distinction visible in §5.2/§5.3 (BytesToBits in M' construction)
+ * collapses at the byte boundary inside our SHAKE wrapper.
+ */
+export declare function validateMessage(M: Uint8Array): void;
+/**
+ * FIPS 204 §5.4.1, the prehash PH_M passed to HashML-DSA Sign_internal /
+ * Verify_internal must be exactly the digest size of `algo`. Used by the
+ * `*Prehashed` family where the caller computes PH externally; the
+ * non-prehashed family produces PH internally so this check is implicit.
+ *
+ * Throws `SigningError('sig-malformed-input')` on mismatch. The verify
+ * surface intercepts this to return false (a wrong-size digest is a
+ * structural mismatch, indistinguishable from a wrong signature), while
+ * the sign surface lets the throw propagate (the caller supplied bad
+ * input, that is a contract violation per the FIPS 204 §5.4 input
+ * contract).
+ */
+export declare function validateDigest(digest: Uint8Array, algo: PreHashAlgorithm): void;