leviathan-crypto 2.1.0 → 3.0.0

package/dist/{kyber → mlkem}/indcpa.js

@@ -19,10 +19,10 @@
 //   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
 //                           ▀█████▀▀
 //
-// src/ts/kyber/indcpa.ts
+// src/ts/mlkem/indcpa.ts
 //
-// ML-KEM IND-CPA PKE scheme — FIPS 203 Algorithms 12, 13, 14 (K-PKE).
-// Orchestrates kyber WASM (polynomial math) and sha3 WASM (Keccak sponge).
+// ML-KEM IND-CPA PKE scheme, FIPS 203 Algorithms 12, 13, 14 (K-PKE).
+// Orchestrates mlkem WASM (polynomial math) and sha3 WASM (Keccak sponge).
 import { wipe } from '../utils.js';
 // ── SHA3 helpers ────────────────────────────────────────────────────────────
 // All operate directly on raw Sha3Exports, no init() system involved.
@@ -82,7 +82,7 @@ export function shake256Hash(sx, msg, n) {
  * Generate row `rowI` of matrix  (or Â^T) into polyvec slot `pvecSlot`.
  *
  * FIPS 203 Algorithm 6 (SampleNTT): each entry Â[i][j] = XOF(ρ, j, i).
- * The matrix entries are already in NTT domain by construction — no separate
+ * The matrix entries are already in NTT domain by construction, no separate
  * NTT call is needed after rej_uniform.
  *
  * transposed=false (keygen):  XOF input = ρ || j || i  → Â[i][j]
@@ -90,7 +90,7 @@ export function shake256Hash(sx, msg, n) {
  */
 function genMatrixRow(kx, sx, k, rho, transposed, pvecSlot, rowI) {
     const xofPrfOff = kx.getXofPrfOffset();
-    const kyberMem = new Uint8Array(kx.memory.buffer);
+    const mlkemMem = new Uint8Array(kx.memory.buffer);
     const sha3Mem = new Uint8Array(sx.memory.buffer);
     const outOff = sx.getOutOffset();
     // XOF seed buffer: ρ(32) || byte0 || byte1
@@ -115,7 +115,7 @@ function genMatrixRow(kx, sx, k, rho, transposed, pvecSlot, rowI) {
         let ctr = 0;
         while (ctr < 256) {
             sx.shakeSqueezeBlock(); // 168 bytes at sha3 OUT_OFFSET
-            kyberMem.set(sha3Mem.subarray(outOff, outOff + 168), xofPrfOff);
+            mlkemMem.set(sha3Mem.subarray(outOff, outOff + 168), xofPrfOff);
             ctr += kx.rej_uniform(polyOff, ctr, xofPrfOff, 168);
         }
     }
@@ -127,7 +127,7 @@ function genMatrixRow(kx, sx, k, rho, transposed, pvecSlot, rowI) {
  */
 function noisePolyvec(kx, sx, pvSlot, k, sigma, nonceStart, eta) {
     const xofPrfOff = kx.getXofPrfOffset();
-    const kyberMem = new Uint8Array(kx.memory.buffer);
+    const mlkemMem = new Uint8Array(kx.memory.buffer);
     const sha3Mem = new Uint8Array(sx.memory.buffer);
     const outOff = sx.getOutOffset();
     const prfLen = eta * 64; // 128 for η=2, 192 for η=3
@@ -145,7 +145,7 @@ function noisePolyvec(kx, sx, pvSlot, k, sigma, nonceStart, eta) {
             while (pos < prfLen) {
                 sx.shakeSqueezeBlock();
                 const take = Math.min(prfLen - pos, rate);
-                kyberMem.set(sha3Mem.subarray(outOff, outOff + take), xofPrfOff + pos);
+                mlkemMem.set(sha3Mem.subarray(outOff, outOff + take), xofPrfOff + pos);
                 pos += take;
             }
             kx.poly_getnoise(pvSlot + i * 512, xofPrfOff, eta);
@@ -160,7 +160,7 @@ function noisePolyvec(kx, sx, pvSlot, k, sigma, nonceStart, eta) {
  */
 function noisePoly(kx, sx, polyOff, sigma, nonce, eta) {
     const xofPrfOff = kx.getXofPrfOffset();
-    const kyberMem = new Uint8Array(kx.memory.buffer);
+    const mlkemMem = new Uint8Array(kx.memory.buffer);
     const sha3Mem = new Uint8Array(sx.memory.buffer);
     const outOff = sx.getOutOffset();
     const prfLen = eta * 64;
@@ -176,7 +176,7 @@ function noisePoly(kx, sx, polyOff, sigma, nonce, eta) {
         while (pos < prfLen) {
             sx.shakeSqueezeBlock();
             const take = Math.min(prfLen - pos, rate);
-            kyberMem.set(sha3Mem.subarray(outOff, outOff + take), xofPrfOff + pos);
+            mlkemMem.set(sha3Mem.subarray(outOff, outOff + take), xofPrfOff + pos);
             pos += take;
         }
         kx.poly_getnoise(polyOff, xofPrfOff, eta);
@@ -187,13 +187,13 @@ function noisePoly(kx, sx, polyOff, sigma, nonce, eta) {
 }
 // ── IND-CPA functions ───────────────────────────────────────────────────────
 /**
- * K-PKE.KeyGen (FIPS 203 Algorithm 12) — deterministic.
+ * 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)
+ *   pvec0, current row of  (overwritten per row)
+ *   pvec1, ŝ (noise, persistent through dot products)
+ *   pvec2, ê (noise)
+ *   pvec3, t̂ = ·ŝ + ê (output)
  */
 export function indcpaKeypairDerand(kx, sx, params, d) {
     const { k, eta1 } = params;
@@ -219,7 +219,7 @@ export function indcpaKeypairDerand(kx, sx, params, d) {
         kx.polyvec_ntt(pvec1, k);
         kx.polyvec_ntt(pvec2, k);
         // Step 5: For each row i, t̂[i] = Â[i] · ŝ
-        const kyberMem = new Uint8Array(kx.memory.buffer);
+        const mlkemMem = new Uint8Array(kx.memory.buffer);
         for (let i = 0; i < k; i++) {
             genMatrixRow(kx, sx, k, rho, false, pvec0, i);
             kx.polyvec_basemul_acc_montgomery(pvec3 + i * 512, pvec0, pvec1, k);
@@ -230,12 +230,12 @@ export function indcpaKeypairDerand(kx, sx, params, d) {
         kx.polyvec_reduce(pvec3, k);
         // Step 8: ek = polyvec_tobytes(t̂) || ρ
         kx.polyvec_tobytes(pkOff, pvec3, k);
-        kyberMem.set(rho, pkOff + k * 384);
+        mlkemMem.set(rho, pkOff + k * 384);
         // Step 9: sk = polyvec_tobytes(ŝ)
         kx.polyvec_tobytes(skOff, pvec1, k);
         return {
-            ekCpa: kyberMem.slice(pkOff, pkOff + params.ekBytes),
-            skCpa: kyberMem.slice(skOff, skOff + params.skCpaBytes),
+            ekCpa: mlkemMem.slice(pkOff, pkOff + params.ekBytes),
+            skCpa: mlkemMem.slice(skOff, skOff + params.skCpaBytes),
         };
     }
     finally {
@@ -244,21 +244,21 @@ export function indcpaKeypairDerand(kx, sx, params, d) {
     }
 }
 /**
- * K-PKE.Encrypt (FIPS 203 Algorithm 13) — deterministic.
+ * 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
+ *   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 function indcpaEncrypt(kx, sx, params, ek, m, coins) {
     const { k, eta1, eta2, du, dv } = params;
-    const kyberMem = new Uint8Array(kx.memory.buffer);
+    const mlkemMem = new Uint8Array(kx.memory.buffer);
     const pvec0 = kx.getPolyvecSlot0();
     const pvec1 = kx.getPolyvecSlot1();
     const pvec2 = kx.getPolyvecSlot2();
@@ -270,8 +270,8 @@ export function indcpaEncrypt(kx, sx, params, ek, m, coins) {
     const pkOff = kx.getPkOffset();
     const ctOff = kx.getCtOffset();
     const msgOff = kx.getMsgOffset();
-    // Step 1: Unpack ek — t̂ → pvec4, ρ from ek tail
-    kyberMem.set(ek, pkOff);
+    // Step 1: Unpack ek, t̂ → pvec4, ρ from ek tail
+    mlkemMem.set(ek, pkOff);
     kx.polyvec_frombytes(pvec4, pkOff, k);
     const rho = ek.slice(k * 384, k * 384 + 32);
     // Steps 2-4: Generate noise r, e₁, e₂ from coins
@@ -296,31 +296,31 @@ export function indcpaEncrypt(kx, sx, params, ek, m, coins) {
     kx.polyvec_basemul_acc_montgomery(poly2, pvec4, pvec1, k);
     kx.poly_invntt(poly2);
     // Step 12: decode message
-    kyberMem.set(m, msgOff);
+    mlkemMem.set(m, msgOff);
     kx.poly_frommsg(poly3, msgOff);
     // Steps 13-15: v = v + e₂ + msg, reduce
     kx.poly_add(poly2, poly2, poly1);
     kx.poly_add(poly2, poly2, poly3);
     kx.poly_reduce(poly2);
-    // Step 16: pack ciphertext — Compress_du(u) || Compress_dv(v)
+    // Step 16: pack ciphertext, Compress_du(u) || Compress_dv(v)
     const pvecCompBytes = k * du * 32;
     kx.polyvec_compress(ctOff, pvec3, k, du);
     kx.poly_compress(ctOff + pvecCompBytes, poly2, dv);
-    return kyberMem.slice(ctOff, ctOff + params.ctBytes);
+    return mlkemMem.slice(ctOff, ctOff + params.ctBytes);
 }
 /**
  * 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
+ *   pvec0, û (decompressed from ct)
+ *   pvec1, ŝ (from sk)
+ *   poly0 , v (decompressed from ct)
+ *   poly1 , w = invNTT(ŝ^T · NTT(û))
+ *   poly2 , m' = v - w
  */
 export function indcpaDecrypt(kx, params, skCpa, ct) {
     const { k, du, dv } = params;
-    const kyberMem = new Uint8Array(kx.memory.buffer);
+    const mlkemMem = new Uint8Array(kx.memory.buffer);
     const pvec0 = kx.getPolyvecSlot0();
     const pvec1 = kx.getPolyvecSlot1();
     const poly0 = kx.getPolySlot0();
@@ -329,9 +329,9 @@ export function indcpaDecrypt(kx, params, skCpa, ct) {
     const ctOff = kx.getCtOffset();
     const skOff = kx.getSkOffset();
     const msgOff = kx.getMsgOffset();
-    // Load ct and sk into kyber memory
-    kyberMem.set(ct, ctOff);
-    kyberMem.set(skCpa, skOff);
+    // Load ct and sk into mlkem memory
+    mlkemMem.set(ct, ctOff);
+    mlkemMem.set(skCpa, skOff);
     // Steps 1-2: Decompress û and v
     const pvecCompBytes = k * du * 32;
     kx.polyvec_decompress(pvec0, ctOff, k, du);
@@ -348,5 +348,5 @@ export function indcpaDecrypt(kx, params, skCpa, ct) {
     kx.poly_reduce(poly2);
     // Step 9-10: poly_tomsg → 32-byte message
     kx.poly_tomsg(msgOff, poly2);
-    return kyberMem.slice(msgOff, msgOff + 32);
+    return mlkemMem.slice(msgOff, msgOff + 32);
 }

package/dist/mlkem/index.d.ts

@@ -0,0 +1,37 @@
+import { isInitialized } from '../init.js';
+import type { WasmSource } from '../wasm-source.js';
+import type { MlKemExports, Sha3Exports, MlKemKeyPair, MlKemEncapsulation } from './types.js';
+import { MlKemParams, MLKEM512, MLKEM768, MLKEM1024 } from './params.js';
+export declare function mlkemInit(source: WasmSource): Promise<void>;
+export type { WasmSource };
+export type { MlKemKeyPair, MlKemEncapsulation, MlKemExports, Sha3Exports };
+export { MLKEM512, MLKEM768, MLKEM1024 };
+export type { MlKemParams };
+export { isInitialized };
+export { MlKemSuite } from './suite.js';
+export declare class MlKemBase {
+    readonly params: MlKemParams;
+    constructor(params: MlKemParams);
+    private get kx();
+    private get sx();
+    keygenDerand(d: Uint8Array, z: Uint8Array): MlKemKeyPair;
+    keygen(): MlKemKeyPair;
+    encapsulateDerand(ek: Uint8Array, m: Uint8Array): MlKemEncapsulation;
+    encapsulate(ek: Uint8Array): MlKemEncapsulation;
+    decapsulate(dk: Uint8Array, c: Uint8Array): Uint8Array;
+    checkEncapsulationKey(ek: Uint8Array): boolean;
+    checkDecapsulationKey(dk: Uint8Array): boolean;
+    dispose(): void;
+}
+/** ML-KEM-512, k=2, η₁=3, η₂=2, dᵤ=10, dᵥ=4. */
+export declare class MlKem512 extends MlKemBase {
+    constructor();
+}
+/** ML-KEM-768, k=3, η₁=2, η₂=2, dᵤ=10, dᵥ=4. */
+export declare class MlKem768 extends MlKemBase {
+    constructor();
+}
+/** ML-KEM-1024, k=4, η₁=2, η₂=2, dᵤ=11, dᵥ=5. */
+export declare class MlKem1024 extends MlKemBase {
+    constructor();
+}

package/dist/{kyber → mlkem}/index.js

@@ -19,31 +19,21 @@
 //   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
 //                           ▀█████▀▀
 //
-// src/ts/kyber/index.ts
+// src/ts/mlkem/index.ts
 //
-// ML-KEM public API — MlKem512, MlKem768, MlKem1024 classes.
-// Uses the init() module cache — call init({ kyber: ..., sha3: ... }) before constructing.
+// ML-KEM public API, MlKem512, MlKem768, MlKem1024 classes.
+// Uses the init() module cache, call init({ mlkem: ..., sha3: ... }) before constructing.
 import { getInstance, initModule, isInitialized, _assertNotOwned } from '../init.js';
 import { randomBytes, wipe } from '../utils.js';
 import { MLKEM512, MLKEM768, MLKEM1024 } from './params.js';
 import { kemKeypairDerand, kemEncapsulateDerand, kemDecapsulate } from './kem.js';
 import { checkEncapsulationKey, checkDecapsulationKey } from './validate.js';
-export async function kyberInit(source) {
-    return initModule('kyber', source);
-}
-export function _kyberReady() {
-    try {
-        getInstance('kyber');
-        getInstance('sha3');
-        return true;
-    }
-    catch {
-        return false;
-    }
+export async function mlkemInit(source) {
+    return initModule('mlkem', source);
 }
 export { MLKEM512, MLKEM768, MLKEM1024 };
 export { isInitialized };
-export { KyberSuite } from './suite.js';
+export { MlKemSuite } from './suite.js';
 // ── Layout assertion ────────────────────────────────────────────────────────
 function assertLayout(kx, p) {
     const pk = kx.getPkOffset();
@@ -52,34 +42,34 @@ function assertLayout(kx, p) {
     const ctPrime = kx.getCtPrimeOffset();
     const xof = kx.getXofPrfOffset();
     if (pk + p.ekBytes > sk)
-        throw new Error('leviathan-crypto: kyber buffer overflow — ek overflows into SK region');
+        throw new Error('leviathan-crypto: mlkem buffer overflow, ek overflows into SK region');
     if (sk + p.skCpaBytes > ct)
-        throw new Error('leviathan-crypto: kyber buffer overflow — sk overflows into CT region');
+        throw new Error('leviathan-crypto: mlkem buffer overflow, sk overflows into CT region');
     if (ct + p.ctBytes > ctPrime)
-        throw new Error('leviathan-crypto: kyber buffer overflow — ct overflows into CT_PRIME region');
+        throw new Error('leviathan-crypto: mlkem buffer overflow, ct overflows into CT_PRIME region');
     if (ctPrime + p.ctBytes > xof)
-        throw new Error('leviathan-crypto: kyber buffer overflow — ct_prime overflows into XOF region');
+        throw new Error('leviathan-crypto: mlkem buffer overflow, ct_prime overflows into XOF region');
 }
 // ── Base class ──────────────────────────────────────────────────────────────
 export class MlKemBase {
     params;
     constructor(params) {
-        if (!isInitialized('kyber'))
-            throw new Error('leviathan-crypto: call init({ kyber: ... }) before using MlKem classes');
+        if (!isInitialized('mlkem'))
+            throw new Error('leviathan-crypto: call init({ mlkem: ... }) before using MlKem classes');
         if (!isInitialized('sha3'))
             throw new Error('leviathan-crypto: call init({ sha3: ... }) before using MlKem classes');
         this.params = params;
         assertLayout(this.kx, params);
     }
     get kx() {
-        return getInstance('kyber').exports;
+        return getInstance('mlkem').exports;
     }
     get sx() {
         return getInstance('sha3').exports;
     }
     keygenDerand(d, z) {
         _assertNotOwned('sha3');
-        _assertNotOwned('kyber');
+        _assertNotOwned('mlkem');
         if (d.length !== 32)
             throw new RangeError(`d seed must be 32 bytes (got ${d.length})`);
         if (z.length !== 32)
@@ -99,7 +89,7 @@ export class MlKemBase {
     }
     encapsulateDerand(ek, m) {
         _assertNotOwned('sha3');
-        _assertNotOwned('kyber');
+        _assertNotOwned('mlkem');
         if (ek.length !== this.params.ekBytes)
             throw new RangeError(`encapsulation key must be ${this.params.ekBytes} bytes (got ${ek.length})`);
         if (m.length !== 32)
@@ -119,7 +109,7 @@ export class MlKemBase {
     }
     decapsulate(dk, c) {
         _assertNotOwned('sha3');
-        _assertNotOwned('kyber');
+        _assertNotOwned('mlkem');
         if (dk.length !== this.params.dkBytes)
             throw new RangeError(`decapsulation key must be ${this.params.dkBytes} bytes (got ${dk.length})`);
         if (c.length !== this.params.ctBytes)
@@ -130,39 +120,39 @@ export class MlKemBase {
     }
     checkEncapsulationKey(ek) {
         _assertNotOwned('sha3');
-        _assertNotOwned('kyber');
+        _assertNotOwned('mlkem');
         return checkEncapsulationKey(this.kx, this.params, ek);
     }
     checkDecapsulationKey(dk) {
         _assertNotOwned('sha3');
-        _assertNotOwned('kyber');
+        _assertNotOwned('mlkem');
         return checkDecapsulationKey(this.kx, this.sx, this.params, dk);
     }
     dispose() {
         this.kx.wipeBuffers();
-        // MlKemBase does not own the sha3 module — wiping this.sx.wipeBuffers()
+        // MlKemBase does not own the sha3 module, wiping this.sx.wipeBuffers()
         // here would clobber any SHAKE128/SHAKE256 instance live at the time
-        // of dispose(). The wipe is not needed: every public kyber op
+        // of dispose(). The wipe is not needed: every public mlkem op
         // (keygen, encapsulate, decapsulate, checkDecapsulationKey) calls
         // sx.wipeBuffers() before returning, under the _assertNotOwned('sha3')
         // guard it holds for the duration. sha3 scratch therefore carries no
-        // residue across a kyber op boundary — secret-derived or otherwise.
+        // residue across a mlkem op boundary, secret-derived or otherwise.
     }
 }
 // ── Public classes ──────────────────────────────────────────────────────────
-/** ML-KEM-512 — k=2, η₁=3, η₂=2, dᵤ=10, dᵥ=4. */
+/** ML-KEM-512, k=2, η₁=3, η₂=2, dᵤ=10, dᵥ=4. */
 export class MlKem512 extends MlKemBase {
     constructor() {
         super(MLKEM512);
     }
 }
-/** ML-KEM-768 — k=3, η₁=2, η₂=2, dᵤ=10, dᵥ=4. */
+/** ML-KEM-768, k=3, η₁=2, η₂=2, dᵤ=10, dᵥ=4. */
 export class MlKem768 extends MlKemBase {
     constructor() {
         super(MLKEM768);
     }
 }
-/** ML-KEM-1024 — k=4, η₁=2, η₂=2, dᵤ=11, dᵥ=5. */
+/** ML-KEM-1024, k=4, η₁=2, η₂=2, dᵤ=11, dᵥ=5. */
 export class MlKem1024 extends MlKemBase {
     constructor() {
         super(MLKEM1024);

package/dist/mlkem/kem.d.ts

@@ -0,0 +1,21 @@
+import type { MlKemExports, Sha3Exports, MlKemKeyPair, MlKemEncapsulation } from './types.js';
+import type { MlKemParams } from './params.js';
+/**
+ * ML-KEM.KeyGen_internal (FIPS 203 Algorithm 15).
+ *
+ * dk = skCpa || ek || H(ek) || z
+ */
+export declare function kemKeypairDerand(kx: MlKemExports, sx: Sha3Exports, params: MlKemParams, d: Uint8Array, z: Uint8Array): MlKemKeyPair;
+/**
+ * ML-KEM.Encaps_internal (FIPS 203 Algorithm 16).
+ *
+ * (K, r) = G(m || H(ek)), c = K-PKE.Encrypt(ek, m, r)
+ */
+export declare function kemEncapsulateDerand(kx: MlKemExports, sx: Sha3Exports, params: MlKemParams, ek: Uint8Array, m: Uint8Array): MlKemEncapsulation;
+/**
+ * ML-KEM.Decaps_internal (FIPS 203 Algorithm 17).
+ *
+ * Constant-time: uses ct_verify and ct_cmov from mlkem WASM.
+ * MUST NOT branch on secret data in JS, all comparison via WASM primitives.
+ */
+export declare function kemDecapsulate(kx: MlKemExports, sx: Sha3Exports, params: MlKemParams, dk: Uint8Array, c: Uint8Array): Uint8Array;

package/dist/{kyber → mlkem}/kem.js

@@ -19,9 +19,9 @@
 //   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
 //                           ▀█████▀▀
 //
-// src/ts/kyber/kem.ts
+// src/ts/mlkem/kem.ts
 //
-// ML-KEM KEM layer — Fujisaki-Okamoto transform.
+// ML-KEM KEM layer, Fujisaki-Okamoto transform.
 // FIPS 203 Algorithms 15, 16, 17 (ML-KEM internal).
 import { indcpaKeypairDerand, indcpaEncrypt, indcpaDecrypt, sha3_256Hash, sha3_512Hash, shake256Hash, } from './indcpa.js';
 import { wipe } from '../utils.js';
@@ -33,20 +33,13 @@ import { wipe } from '../utils.js';
 export function kemKeypairDerand(kx, sx, params, d, z) {
     // indcpaKeypairDerand handles its own sigma wipe
     const { ekCpa, skCpa } = indcpaKeypairDerand(kx, sx, params, d);
-    // Wipe kyber WASM scratch regions that held the CPA secret key and the
-    // keygen noise. After kemKeypairDerand returns, no secret or secret-
-    // derived data persists in kyber linear memory until the next kyber op
-    // or MlKem.dispose(). SK_OFFSET holds skCpa packed via polyvec_tobytes
-    // — same severity class as the decap-side SK_OFFSET residual (R-028):
-    // long-lived key material whose disclosure compromises every ciphertext
-    // under the corresponding ek. POLYVEC_SLOT_1/2 hold ŝ and ê in NTT
-    // domain. XOF_PRF_OFFSET holds the last PRF output block. POLYVEC_SLOT_3
-    // (t̂) and POLYVEC_SLOT_0 (Â rows) are public and intentionally skipped.
-    const kyberMem = new Uint8Array(kx.memory.buffer);
-    kyberMem.fill(0, kx.getSkOffset(), kx.getSkOffset() + params.skCpaBytes);
-    kyberMem.fill(0, kx.getPolyvecSlot1(), kx.getPolyvecSlot1() + 2048);
-    kyberMem.fill(0, kx.getPolyvecSlot2(), kx.getPolyvecSlot2() + 2048);
-    kyberMem.fill(0, kx.getXofPrfOffset(), kx.getXofPrfOffset() + 1024);
+    // Wipe CPA sk + keygen noise + PRF scratch. See
+    // docs/mlkem.md#wipe-discipline.
+    const mlkemMem = new Uint8Array(kx.memory.buffer);
+    mlkemMem.fill(0, kx.getSkOffset(), kx.getSkOffset() + params.skCpaBytes);
+    mlkemMem.fill(0, kx.getPolyvecSlot1(), kx.getPolyvecSlot1() + 2048);
+    mlkemMem.fill(0, kx.getPolyvecSlot2(), kx.getPolyvecSlot2() + 2048);
+    mlkemMem.fill(0, kx.getXofPrfOffset(), kx.getXofPrfOffset() + 1024);
     const h = sha3_256Hash(sx, ekCpa);
     try {
         const dk = new Uint8Array(params.dkBytes);
@@ -83,26 +76,17 @@ export function kemEncapsulateDerand(kx, sx, params, ek, m) {
         const K = gOut.slice(0, 32);
         r = gOut.slice(32, 64);
         const c = indcpaEncrypt(kx, sx, params, ek, m, r);
-        // Wipe kyber WASM scratch regions that held m / r / e₁ / e₂ / u / v /
-        // m-poly / PRF output. After kemEncapsulateDerand returns, no secret
-        // or secret-derived data persists in kyber linear memory until the
-        // next kyber op or MlKem.dispose(). MSG_OFFSET holds raw m —
-        // reproducing the shared secret K = G(m ‖ H(ek))[0..32] only needs m
-        // plus the public ek, so this is the highest-severity encap residual.
-        // POLYVEC_SLOT_1/2/3 hold r, e₁, and uncompressed u (u compression is
-        // lossy for du ∈ {10,11} — uncompressed u reveals low-order bits the
-        // public ciphertext hides). POLY_SLOT_1/2/3 hold e₂ (full 512B), v,
-        // and the m-polynomial. XOF_PRF_OFFSET holds the last PRF block.
-        // PK_OFFSET, CT_OFFSET, POLYVEC_SLOT_0/4 are public — skipped.
-        const kyberMem = new Uint8Array(kx.memory.buffer);
-        kyberMem.fill(0, kx.getMsgOffset(), kx.getMsgOffset() + 32);
-        kyberMem.fill(0, kx.getPolyvecSlot1(), kx.getPolyvecSlot1() + 2048);
-        kyberMem.fill(0, kx.getPolyvecSlot2(), kx.getPolyvecSlot2() + 2048);
-        kyberMem.fill(0, kx.getPolyvecSlot3(), kx.getPolyvecSlot3() + 2048);
-        kyberMem.fill(0, kx.getPolySlot1(), kx.getPolySlot1() + 512);
-        kyberMem.fill(0, kx.getPolySlot2(), kx.getPolySlot2() + 512);
-        kyberMem.fill(0, kx.getPolySlot3(), kx.getPolySlot3() + 512);
-        kyberMem.fill(0, kx.getXofPrfOffset(), kx.getXofPrfOffset() + 1024);
+        // Wipe m + r + e1/e2/u/v + m-poly + PRF scratch. See
+        // docs/mlkem.md#wipe-discipline.
+        const mlkemMem = new Uint8Array(kx.memory.buffer);
+        mlkemMem.fill(0, kx.getMsgOffset(), kx.getMsgOffset() + 32);
+        mlkemMem.fill(0, kx.getPolyvecSlot1(), kx.getPolyvecSlot1() + 2048);
+        mlkemMem.fill(0, kx.getPolyvecSlot2(), kx.getPolyvecSlot2() + 2048);
+        mlkemMem.fill(0, kx.getPolyvecSlot3(), kx.getPolyvecSlot3() + 2048);
+        mlkemMem.fill(0, kx.getPolySlot1(), kx.getPolySlot1() + 512);
+        mlkemMem.fill(0, kx.getPolySlot2(), kx.getPolySlot2() + 512);
+        mlkemMem.fill(0, kx.getPolySlot3(), kx.getPolySlot3() + 512);
+        mlkemMem.fill(0, kx.getXofPrfOffset(), kx.getXofPrfOffset() + 1024);
         sx.wipeBuffers();
         return { ciphertext: c, sharedSecret: K };
     }
@@ -118,8 +102,8 @@ export function kemEncapsulateDerand(kx, sx, params, ek, m) {
 /**
  * ML-KEM.Decaps_internal (FIPS 203 Algorithm 17).
  *
- * Constant-time: uses ct_verify and ct_cmov from kyber WASM.
- * MUST NOT branch on secret data in JS — all comparison via WASM primitives.
+ * Constant-time: uses ct_verify and ct_cmov from mlkem WASM.
+ * MUST NOT branch on secret data in JS, all comparison via WASM primitives.
  */
 export function kemDecapsulate(kx, sx, params, dk, c) {
     const { skCpaBytes, ekBytes, ctBytes } = params;
@@ -151,42 +135,38 @@ export function kemDecapsulate(kx, sx, params, dk, c) {
         jInput.set(z, 0);
         jInput.set(c, 32);
         kBar = shake256Hash(sx, jInput, 32);
-        // Re-encrypt c' = K-PKE.Encrypt(ek, m', r') — indcpaEncrypt handles its own prfInput wipe
+        // Re-encrypt c' = K-PKE.Encrypt(ek, m', r'), indcpaEncrypt handles its own prfInput wipe
         cPrime = indcpaEncrypt(kx, sx, params, ek, mPrime, rPrime);
-        // Constant-time comparison and conditional select via kyber WASM
-        const kyberMem = new Uint8Array(kx.memory.buffer);
+        // Constant-time comparison and conditional select via mlkem WASM
+        const mlkemMem = new Uint8Array(kx.memory.buffer);
         const ctOff = kx.getCtOffset();
         const ctPrimeOff = kx.getCtPrimeOffset();
-        // Write c and c' into named kyber memory regions
-        kyberMem.set(c, ctOff);
-        kyberMem.set(cPrime, ctPrimeOff);
+        // Write c and c' into named mlkem memory regions
+        mlkemMem.set(c, ctOff);
+        mlkemMem.set(cPrime, ctPrimeOff);
         // Write K' and K̄ into poly slots (512B each, 32B needed)
         const kPrimeOff = kx.getPolySlot0();
         const kBarOff = kx.getPolySlot1();
-        kyberMem.set(kPrime, kPrimeOff);
-        kyberMem.set(kBar, kBarOff);
+        mlkemMem.set(kPrime, kPrimeOff);
+        mlkemMem.set(kBar, kBarOff);
         // fail = 0 if c == c', non-zero if different
         const fail = kx.ct_verify(ctOff, ctPrimeOff, ctBytes);
         // If fail != 0 (mismatch): K' ← K̄
         kx.ct_cmov(kPrimeOff, kBarOff, 32, fail);
-        const sharedSecret = kyberMem.slice(kPrimeOff, kPrimeOff + 32);
-        // Wipe kyber WASM scratch regions that held the CPA secret key (skCpa),
-        // m' / K' / K̄ / e₂ / r / e₁ / u, and the PRF output buffer. Without
-        // this, residual secret and secret-derived bytes persist in linear
-        // memory until the next kyber op or MlKem.dispose() — a window during
-        // which any other code with a handle to the kyber exports could read
-        // them. skCpa is the highest-severity residual: it compromises every
-        // ciphertext under the corresponding ek, not just this message.
-        kyberMem.fill(0, kx.getMsgOffset(), kx.getMsgOffset() + 32); // m' (bytes)
-        kyberMem.fill(0, kPrimeOff, kPrimeOff + 32); // K' (final shared secret)
-        kyberMem.fill(0, kBarOff, kBarOff + 512); // K̄ (first 32B) + e₂ poly tail
-        kyberMem.fill(0, kx.getPolySlot2(), kx.getPolySlot2() + 512); // m'-poly / v residual
-        kyberMem.fill(0, kx.getPolySlot3(), kx.getPolySlot3() + 512); // indcpa message poly
-        kyberMem.fill(0, kx.getPolyvecSlot1(), kx.getPolyvecSlot1() + 2048); // r (NTT-domain noise polyvec)
-        kyberMem.fill(0, kx.getPolyvecSlot2(), kx.getPolyvecSlot2() + 2048); // e₁ (noise polyvec for u)
-        kyberMem.fill(0, kx.getPolyvecSlot3(), kx.getPolyvecSlot3() + 2048); // uncompressed u polyvec from FO re-encryption
-        kyberMem.fill(0, kx.getXofPrfOffset(), kx.getXofPrfOffset() + 1024); // last PRF output block
-        kyberMem.fill(0, kx.getSkOffset(), kx.getSkOffset() + skCpaBytes); // CPA secret key (long-lived — highest severity residual)
+        const sharedSecret = mlkemMem.slice(kPrimeOff, kPrimeOff + 32);
+        // Wipe CPA sk + m' + K'/K_bar + noise + PRF scratch. skCpa is the
+        // highest-severity residual (compromises every ciphertext under the
+        // corresponding ek). See docs/mlkem.md#wipe-discipline.
+        mlkemMem.fill(0, kx.getMsgOffset(), kx.getMsgOffset() + 32); // m' (bytes)
+        mlkemMem.fill(0, kPrimeOff, kPrimeOff + 32); // K' (final shared secret)
+        mlkemMem.fill(0, kBarOff, kBarOff + 512); // K̄ (first 32B) + e₂ poly tail
+        mlkemMem.fill(0, kx.getPolySlot2(), kx.getPolySlot2() + 512); // m'-poly / v residual
+        mlkemMem.fill(0, kx.getPolySlot3(), kx.getPolySlot3() + 512); // indcpa message poly
+        mlkemMem.fill(0, kx.getPolyvecSlot1(), kx.getPolyvecSlot1() + 2048); // r (NTT-domain noise polyvec)
+        mlkemMem.fill(0, kx.getPolyvecSlot2(), kx.getPolyvecSlot2() + 2048); // e₁ (noise polyvec for u)
+        mlkemMem.fill(0, kx.getPolyvecSlot3(), kx.getPolyvecSlot3() + 2048); // uncompressed u polyvec from FO re-encryption
+        mlkemMem.fill(0, kx.getXofPrfOffset(), kx.getXofPrfOffset() + 1024); // last PRF output block
+        mlkemMem.fill(0, kx.getSkOffset(), kx.getSkOffset() + skCpaBytes); // CPA secret key (long-lived, highest severity residual)
         sx.wipeBuffers();
         return sharedSecret;
     }

package/dist/{kyber → mlkem}/params.d.ts

@@ -1,4 +1,4 @@
-export interface KyberParams {
+export interface MlKemParams {
     k: number;
     eta1: number;
     eta2: number;
@@ -9,6 +9,6 @@ export interface KyberParams {
     ctBytes: number;
     skCpaBytes: number;
 }
-export declare const MLKEM512: KyberParams;
-export declare const MLKEM768: KyberParams;
-export declare const MLKEM1024: KyberParams;
+export declare const MLKEM512: MlKemParams;
+export declare const MLKEM768: MlKemParams;
+export declare const MLKEM1024: MlKemParams;

package/dist/{kyber → mlkem}/params.js

@@ -19,10 +19,10 @@
 //   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
 //                           ▀█████▀▀
 //
-// src/ts/kyber/params.ts
+// src/ts/mlkem/params.ts
 //
 // ML-KEM (FIPS 203) parameter set configurations.
-// FIPS 203 Table 2 — Parameter sets for ML-KEM.
+// FIPS 203 Table 2, Parameter sets for ML-KEM.
 export const MLKEM512 = {
     k: 2, eta1: 3, eta2: 2, du: 10, dv: 4,
     ekBytes: 800, dkBytes: 1632, ctBytes: 768, skCpaBytes: 768,

package/dist/mlkem/suite.d.ts

@@ -0,0 +1,12 @@
+import type { CipherSuite } from '../stream/types.js';
+import type { MlKemKeyPair, MlKemEncapsulation } from './types.js';
+import type { MlKemParams } from './params.js';
+export interface MlKemLike {
+    readonly params: MlKemParams;
+    encapsulate(ek: Uint8Array): MlKemEncapsulation;
+    decapsulate(dk: Uint8Array, c: Uint8Array): Uint8Array;
+    keygen(): MlKemKeyPair;
+}
+export declare function MlKemSuite(kem: MlKemLike, inner: CipherSuite): CipherSuite & {
+    keygen(): MlKemKeyPair;
+};