leviathan-crypto 2.0.1 → 3.0.0

package/dist/mldsa/validate.js

@@ -0,0 +1,125 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/validate.ts
+//
+// ML-DSA caller-side input validation. Pure length / type checks, no
+// content validation here. Semantic content validity (e.g. malformed hint
+// encoding) is handled inside Verify_internal via hint_bit_unpack's -1
+// sentinel (FIPS 204 Algorithm 21 / §D.3).
+//
+// Length checks throw RangeError. The public verify() method intercepts
+// pk/sig length mismatches and returns false instead of propagating the
+// throw, that is FIPS 204 §3.6.2 protocol shape, not a contract violation.
+// validateContext, validateSigningKey, validateRnd ARE contract violations
+// and propagate the throw.
+import { SigningError } from '../errors.js';
+import { digestSize } 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 function validateContext(ctx) {
+    if (!(ctx instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ctx must be a Uint8Array');
+    if (ctx.length > 255)
+        throw new RangeError(`leviathan-crypto: ctx must be ≤ 255 bytes (got ${ctx.length})`);
+}
+/**
+ * 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 function validateVerificationKey(vk, params) {
+    if (!(vk instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: verification key must be a Uint8Array');
+    if (vk.length !== params.pkBytes)
+        throw new RangeError(`leviathan-crypto: verification key must be ${params.pkBytes} bytes for ${params.paramSet} `
+            + `(got ${vk.length})`);
+}
+/**
+ * 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 function validateSigningKey(sk, params) {
+    if (!(sk instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: signing key must be a Uint8Array');
+    if (sk.length !== params.skBytes)
+        throw new RangeError(`leviathan-crypto: signing key must be ${params.skBytes} bytes for ${params.paramSet} `
+            + `(got ${sk.length})`);
+}
+/**
+ * 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 function validateSignature(sig, params) {
+    if (!(sig instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: signature must be a Uint8Array');
+    if (sig.length !== params.sigBytes)
+        throw new RangeError(`leviathan-crypto: signature must be ${params.sigBytes} bytes for ${params.paramSet} `
+            + `(got ${sig.length})`);
+}
+/**
+ * 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 function validateRnd(rnd) {
+    if (!(rnd instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: rnd must be a Uint8Array');
+    if (rnd.length !== 32)
+        throw new RangeError(`leviathan-crypto: rnd must be 32 bytes (got ${rnd.length})`);
+}
+/**
+ * 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 function validateMessage(M) {
+    if (!(M instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: message must be a Uint8Array');
+}
+/**
+ * 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 function validateDigest(digest, algo) {
+    if (!(digest instanceof Uint8Array))
+        throw new SigningError('sig-malformed-input', 'digest must be a Uint8Array');
+    const expected = digestSize(algo);
+    if (digest.length !== expected)
+        throw new SigningError('sig-malformed-input', `digest length ${digest.length} != ${expected} for ${algo}`);
+}

package/dist/mldsa/verify.d.ts

@@ -0,0 +1,29 @@
+import type { MlDsaExports, Sha3Exports } from './types.js';
+import type { MlDsaParams } from './params.js';
+import { type PreHashAlgorithm } from './hashvariant.js';
+/**
+ * ML-DSA.Verify_internal, FIPS 204 Algorithm 8.
+ *
+ * Inputs (all caller-validated for length by the public verify() method):
+ *   vk    , encoded verification key (pkBytes)
+ *   MPrime, domain-separated message bytes
+ *   sig   , encoded signature (sigBytes)
+ *
+ * Returns: boolean.
+ *   true , signature authenticates the message under vk.
+ *   false, wrong sig, malformed hint encoding, or norm check failure.
+ */
+export declare function mldsaVerifyInternal(mx: MlDsaExports, sx: Sha3Exports, params: MlDsaParams, vk: Uint8Array, MPrime: Uint8Array, sig: Uint8Array): boolean;
+/**
+ * HashML-DSA verify, post-prehash. FIPS 204 §5.4 Algorithm 5 lines 17-19.
+ * Builds M' = 0x01 ‖ |ctx| ‖ ctx ‖ OID(algo) ‖ prehash and drives
+ * Verify_internal.
+ *
+ * Same return / throw posture as `mldsaVerifyInternal`: returns a pure
+ * boolean for every signature outcome. Caller (in index.ts) is expected
+ * to have already filtered wrong-length vk / sig / digest with the
+ * appropriate verdict (false) before calling this helper.
+ *
+ * The caller owns `prehash`; this helper never wipes it.
+ */
+export declare function verifyWithPrehash(mx: MlDsaExports, sx: Sha3Exports, params: MlDsaParams, vk: Uint8Array, prehash: Uint8Array, sig: Uint8Array, algo: PreHashAlgorithm, ctx: Uint8Array): boolean;

package/dist/mldsa/verify.js

@@ -0,0 +1,269 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/verify.ts
+//
+// FIPS 204 §6.3 Algorithm 8, ML-DSA.Verify_internal.
+//
+// Verify is a pure boolean predicate: returns true iff the signature
+// passes the FIPS 204 norm check (‖z‖∞ < γ₁ − β) AND the constant-time
+// comparison of the recomputed c̃' against the σ-supplied c̃. There is
+// no analog to the FO transform's implicit-rejection branch (ML-KEM's
+// `return pseudorandom shared secret on failure`); ML-DSA verification
+// is binary.
+//
+// SUF-CMA-critical preconditions enforced here:
+//   1. Length check on pk and σ, caller (verify() in index.ts) returns
+//      false on mismatch BEFORE invoking this internal function, per
+//      FIPS 204 §3.6.2.
+//   2. HintBitUnpack-malformed → false (FIPS 204 §D.3 / Algorithm 21
+//      lines 4, 9, 17). The kernel returns -1; we propagate as false.
+//   3. Constant-time c̃ ↔ c̃' comparison via leviathan-crypto's
+//      `constantTimeEqual` (SIMD WASM XOR-accumulate, no early-exit).
+//
+// Slot allocation:
+//   POLYVEC_SLOT_0   t₁ → t₁·2^d (regular) → t̂₁·2^d (regular) → tomont
+//   POLYVEC_SLOT_1   z (time-domain) → ẑ (regular) → ẑ tomont
+//   POLYVEC_SLOT_2   h (hint polyvec; alive through use_hint)
+//   POLYVEC_SLOT_3   Â · ẑ → w'_approx → w'₁ (in place via use_hint aliasing)
+//   POLYVEC_SLOT_4   ĉ · t̂₁·2^d intermediate
+//   POLY_SLOT_0      signs (8 bytes, sample_in_ball signsOff)
+//   POLY_SLOT_1      c → ĉ
+//   POLY_SLOT_7      reserved scratch for polyvec_pointwise_acc_montgomery
+import { constantTimeEqual, wipe } from '../utils.js';
+import { sha3Absorb, shake256Hash, shake256HashConcat } from './sha3-helpers.js';
+import { expandA } 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;
+function bitlen(n) {
+    let b = 0;
+    let x = n;
+    while (x > 0) {
+        b++;
+        x >>>= 1;
+    }
+    return b;
+}
+/**
+ * ML-DSA.Verify_internal, FIPS 204 Algorithm 8.
+ *
+ * Inputs (all caller-validated for length by the public verify() method):
+ *   vk    , encoded verification key (pkBytes)
+ *   MPrime, domain-separated message bytes
+ *   sig   , encoded signature (sigBytes)
+ *
+ * Returns: boolean.
+ *   true , signature authenticates the message under vk.
+ *   false, wrong sig, malformed hint encoding, or norm check failure.
+ */
+export function mldsaVerifyInternal(mx, sx, params, vk, MPrime, sig) {
+    const { k, l, tau, lambda, gamma1, gamma2, beta, omega } = params;
+    const lambdaOver4 = lambda >>> 2; // 32 / 48 / 64
+    const c = 1 + bitlen(gamma1 - 1); // 18 or 20
+    const zPolyBytes = 32 * c;
+    const t1Bitlen = bitlen(Q - 1) - D; // 23 − 13 = 10
+    const t1PolyBytes = (256 * t1Bitlen) >> 3; // 320
+    const w1Bitlen = bitlen(((Q - 1) / (2 * gamma2)) - 1);
+    const w1PolyBytes = (256 * w1Bitlen) >> 3;
+    const w1TotalBytes = k * w1PolyBytes;
+    const t1ScalarShift = D; // multiply t₁ by 2^d in time domain
+    // ── WASM offsets ─────────────────────────────────────────────────────
+    const matOff = mx.getMatrixSlot();
+    const slot0 = mx.getPolyvecSlot0(); // t₁ then t̂₁·2^d (tomont)
+    const slot1 = mx.getPolyvecSlot1(); // z then ẑ (tomont)
+    const slot2 = mx.getPolyvecSlot2(); // h
+    const slot3 = mx.getPolyvecSlot3(); // ·ẑ → w'_approx → w'₁
+    const slot4 = mx.getPolyvecSlot4(); // ĉ·t̂₁·2^d
+    const polySlotBase = mx.getPolySlotBase();
+    const polySlot0 = mx.getPolySlot0(); // signs
+    const polySlot1 = mx.getPolySlot1(); // c → ĉ
+    const xofOff = mx.getXofPrfOffset();
+    const mlMem = new Uint8Array(mx.memory.buffer);
+    const sha3Mem = new Uint8Array(sx.memory.buffer);
+    const sha3OutOff = sx.getOutOffset();
+    // Public-derivable but wipe in finally for hygiene + symmetry with sign.
+    let mu;
+    let tr;
+    let cTilde;
+    let cTildeNew;
+    let w1Bytes;
+    try {
+        // ── Step 1: pkDecode (FIPS 204 §7.2 Algorithm 23) ────────────────
+        const rho = vk.subarray(0, 32);
+        for (let r = 0; r < k; r++) {
+            const srcOff = 32 + r * t1PolyBytes;
+            mlMem.set(vk.subarray(srcOff, srcOff + t1PolyBytes), xofOff);
+            mx.simple_bit_unpack(slot0 + r * POLY_BYTES, xofOff, t1Bitlen);
+        }
+        // ── Step 2: sigDecode (FIPS 204 §7.2 Algorithm 27) ────────────────
+        // σ = c̃ ‖ z_packed ‖ h_packed
+        cTilde = sig.slice(0, lambdaOver4);
+        let off = lambdaOver4;
+        for (let r = 0; r < l; r++) {
+            mlMem.set(sig.subarray(off, off + zPolyBytes), xofOff);
+            mx.bit_unpack(slot1 + r * POLY_BYTES, xofOff, gamma1 - 1, gamma1);
+            off += zPolyBytes;
+        }
+        // HintBitUnpack, FIPS 204 Algorithm 21. Returns -1 on any of the
+        // three malformed-input checks (lines 4, 9, 17). Propagate as
+        // false: this is the SUF-CMA fix from FIPS 204 §D.3.
+        mlMem.set(sig.subarray(off, off + omega + k), xofOff);
+        if (mx.hint_bit_unpack(slot2, xofOff, k, omega) < 0)
+            return false;
+        // ── Step (Alg 8 line 4) Â ← ExpandA(ρ) ─────────────────────────
+        expandA(mx, sx, params, rho, matOff);
+        // ── Step (Alg 8 line 5) tr ← H(BytesToBits(pk), 64) ──────────────
+        tr = shake256Hash(sx, vk, 64);
+        // ── Step (Alg 8 line 6) μ ← H(BytesToBits(tr) ‖ M', 64) ──────────
+        mu = shake256HashConcat(sx, [tr, MPrime], 64);
+        // ── Step (Alg 8 line 7) c ← SampleInBall(c̃) ───────────────────
+        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);
+        }
+        // ── Step (Alg 8 line 8) w'_approx ← NTT⁻¹(Â ∘ NTT(z) − NTT(c) ∘ NTT(t₁·2^d))
+        // (a) NTT z, then tomont so the matrix kernel's R⁻¹ leaves regular result.
+        mx.polyvec_ntt(slot1, l);
+        mx.polyvec_tomont(slot1, l);
+        // (b) Compute t₁·2^d in time domain. t₁[i] ∈ [0, 1023]; t₁[i]·2^13
+        //     ≤ 1023 · 8192 = 8,380,416 < q = 8,380,417, so no mod needed
+        //     and no overflow. Use Int32Array view over the slot region.
+        const t1View = new Int32Array(mlMem.buffer, slot0, k * 256);
+        for (let i = 0; i < k * 256; i++)
+            t1View[i] <<= t1ScalarShift;
+        mx.polyvec_ntt(slot0, k);
+        mx.polyvec_tomont(slot0, k);
+        // (c) ĉ ← NTT(c), single polynomial in place.
+        mx.ntt(polySlot1);
+        // (d) Â · ẑ → slot3 (regular form in NTT domain)
+        mx.polyvec_matrix_pointwise_montgomery(slot3, matOff, slot1, k, l);
+        // (e) ĉ · t̂₁·2^d → slot4, TS-side per-poly loop; ĉ regular, t̂₁·2^d
+        //     tomont so the kernel's R⁻¹ leaves the result regular.
+        for (let r = 0; r < k; r++) {
+            mx.poly_pointwise_montgomery(slot4 + r * POLY_BYTES, polySlot1, slot0 + r * POLY_BYTES);
+        }
+        // (f) w'_approx (NTT domain) ← ·ẑ − ĉ·t̂₁·2^d
+        mx.polyvec_sub(slot3, slot3, slot4, k);
+        mx.polyvec_invntt(slot3, k);
+        mx.polyvec_caddq(slot3, k); // canonical for use_hint
+        // ── Step (Alg 8 line 9) w'₁ ← UseHint(h, w'_approx) ─────────────
+        // use_hint is alias-safe between r and a (read both before write
+        // per coefficient), so overwrite w'_approx with w'₁ in slot3.
+        mx.polyvec_use_hint(slot3, slot2, slot3, k, gamma2);
+        // ── Step (Alg 8 line 10) c̃' ← H(μ ‖ w₁Encode(w'₁), λ/4) ─────────
+        for (let r = 0; r < k; r++) {
+            mx.simple_bit_pack(xofOff + r * w1PolyBytes, slot3 + r * POLY_BYTES, w1Bitlen);
+        }
+        w1Bytes = mlMem.slice(xofOff, xofOff + w1TotalBytes);
+        cTildeNew = shake256HashConcat(sx, [mu, w1Bytes], lambdaOver4);
+        // ── Step (Alg 8 line 11) return ‖z‖∞ < γ₁ − β AND c̃ = c̃' ───────
+        // The sigDecode bit_unpack output is in centered residues
+        // [-(γ₁-1), γ₁], chknorm consumes that form directly without
+        // polyvec_reduce. We must check norm AFTER the NTT path because
+        // our slot1 holds NTT-domain ẑ now. Re-decode z into a fresh slot
+        // for the norm check.
+        //
+        // Re-decode is cheap (bit_unpack is a single-pass kernel). Use
+        // slot4 (already overwritten above) as the destination.
+        off = lambdaOver4;
+        for (let r = 0; r < l; r++) {
+            mlMem.set(sig.subarray(off, off + zPolyBytes), xofOff);
+            mx.bit_unpack(slot4 + r * POLY_BYTES, xofOff, gamma1 - 1, gamma1);
+            off += zPolyBytes;
+        }
+        const normFail = mx.polyvec_chknorm(slot4, gamma1 - beta, l);
+        // Constant-time comparison via the SIMD ct WASM module. We
+        // evaluate normFail and the c̃ comparison both before returning,
+        // so that an attacker who can observe timing cannot distinguish
+        // "norm failed" from "c̃ mismatch", both run to completion before
+        // the boolean reduction. (The c̃ != c̃' branch is taken regardless
+        // of normFail; both signals are public-input-derived so this is
+        // not a CT requirement, but it preserves the symmetry.)
+        const cTildeEq = constantTimeEqual(cTilde, cTildeNew);
+        return normFail === 0 && cTildeEq;
+    }
+    catch {
+        // FIPS 204 verify is a pure predicate. Any unexpected exception
+        // (out-of-memory, kernel argument errors) is treated as "did not
+        // authenticate", never propagate. The SUF-CMA risk of swallowing
+        // is bounded by validate*.ts callers: the ones that throw on
+        // caller contract violations (oversize ctx) run BEFORE this
+        // function executes.
+        return false;
+    }
+    finally {
+        // Wipe TS-side scratch.
+        if (mu)
+            wipe(mu);
+        if (tr)
+            wipe(tr);
+        if (cTilde)
+            wipe(cTilde);
+        if (cTildeNew)
+            wipe(cTildeNew);
+        if (w1Bytes)
+            wipe(w1Bytes);
+        // Wipe WASM scratch, verify operates on public inputs (vk, sig,
+        // M, ctx all public; t₁, ẑ, w'_approx, h all public-derivable),
+        // but the discipline mirrors sign for review consistency. Cheap.
+        mlMem.fill(0, mx.getPolyvecSlotBase(), mx.getPolyvecSlotBase() + 5 * mx.getPolyvecSlotSize());
+        mlMem.fill(0, polySlotBase, polySlotBase + 8 * POLY_BYTES);
+        mlMem.fill(0, xofOff, xofOff + 8192);
+        // SHA3 module: wipe state across op boundary, same convention as
+        // keygen / sign. Holds vk (public), tr (public), μ (public-derivable).
+        sx.wipeBuffers();
+    }
+}
+/**
+ * HashML-DSA verify, post-prehash. FIPS 204 §5.4 Algorithm 5 lines 17-19.
+ * Builds M' = 0x01 ‖ |ctx| ‖ ctx ‖ OID(algo) ‖ prehash and drives
+ * Verify_internal.
+ *
+ * Same return / throw posture as `mldsaVerifyInternal`: returns a pure
+ * boolean for every signature outcome. Caller (in index.ts) is expected
+ * to have already filtered wrong-length vk / sig / digest with the
+ * appropriate verdict (false) before calling this helper.
+ *
+ * The caller owns `prehash`; this helper never wipes it.
+ */
+export function verifyWithPrehash(mx, sx, params, vk, prehash, sig, algo, ctx) {
+    const oid = getOid(algo);
+    const MPrime = constructMPrimeHash(ctx, oid, prehash);
+    try {
+        return mldsaVerifyInternal(mx, sx, params, vk, MPrime, sig);
+    }
+    finally {
+        wipe(MPrime);
+    }
+}

package/dist/mlkem/embedded.d.ts

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

package/dist/mlkem/embedded.js

@@ -0,0 +1,27 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/mlkem/embedded.ts
+//
+// Exports the gzip+base64 ML-KEM WASM blob for use as a WasmSource.
+// This is the only file in the mlkem subpath that references the embedded blob.
+// Import via `leviathan-crypto/mlkem/embedded`.
+export { WASM_GZ_BASE64 as mlkemWasm } from '../embedded/mlkem.js';

package/dist/mlkem/indcpa.d.ts

@@ -0,0 +1,49 @@
+import type { MlKemExports, Sha3Exports } from './types.js';
+import type { MlKemParams } from './params.js';
+/** SHA3-512(msg) → 64 bytes. Resets sha3 state. */
+export declare function sha3_512Hash(sx: Sha3Exports, msg: Uint8Array): Uint8Array;
+/** SHA3-256(msg) → 32 bytes. Resets sha3 state. */
+export declare function sha3_256Hash(sx: Sha3Exports, msg: Uint8Array): Uint8Array;
+/**
+ * SHAKE256(msg, n) → n bytes. Resets sha3 state.
+ * Used for J function (z || c) and PRF seeding in kem.ts.
+ */
+export declare function shake256Hash(sx: Sha3Exports, msg: Uint8Array, n: number): Uint8Array;
+/**
+ * K-PKE.KeyGen (FIPS 203 Algorithm 12), deterministic.
+ *
+ * Slot map:
+ *   pvec0, current row of  (overwritten per row)
+ *   pvec1, ŝ (noise, persistent through dot products)
+ *   pvec2, ê (noise)
+ *   pvec3, t̂ = ·ŝ + ê (output)
+ */
+export declare function indcpaKeypairDerand(kx: MlKemExports, sx: Sha3Exports, params: MlKemParams, d: Uint8Array): {
+    ekCpa: Uint8Array;
+    skCpa: Uint8Array;
+};
+/**
+ * K-PKE.Encrypt (FIPS 203 Algorithm 13), deterministic.
+ *
+ * Slot map:
+ *   pvec0, current row of Â^T (transposed, overwritten per row)
+ *   pvec1, r̂ = NTT(r)
+ *   pvec2, e₁ (noise)
+ *   pvec3, u = invNTT(Â^T · r̂) + e₁
+ *   pvec4, t̂ (unpacked from ek)
+ *   poly1 , e₂ (noise)
+ *   poly2 , v = invNTT(t̂^T · r̂) + e₂ + msg
+ *   poly3 , message polynomial
+ */
+export declare function indcpaEncrypt(kx: MlKemExports, sx: Sha3Exports, params: MlKemParams, ek: Uint8Array, m: Uint8Array, coins: Uint8Array): Uint8Array;
+/**
+ * K-PKE.Decrypt (FIPS 203 Algorithm 14).
+ *
+ * Slot map:
+ *   pvec0, û (decompressed from ct)
+ *   pvec1, ŝ (from sk)
+ *   poly0 , v (decompressed from ct)
+ *   poly1 , w = invNTT(ŝ^T · NTT(û))
+ *   poly2 , m' = v - w
+ */
+export declare function indcpaDecrypt(kx: MlKemExports, params: MlKemParams, skCpa: Uint8Array, ct: Uint8Array): Uint8Array;