refactor(mlkem)!: rename kyber module to FIPS 203 ML-KEM name

Renames the Kyber module to ML-KEM throughout the codebase to match
the official FIPS 203 (Module-Lattice-Based Key-Encapsulation
Mechanism Standard) name. NIST published the final standard as
ML-KEM, not Kyber; this commit aligns the codebase with that name.
The Rust verifier already shipped under the mlkem name, so this
brings the TS and AssemblyScript layers into line.

Module paths.

  src/asm/kyber/         → src/asm/mlkem/         (12 files)
  src/ts/kyber/          → src/ts/mlkem/          (8 files)
  test/unit/kyber/       → test/unit/mlkem/       (10 files)
  test/e2e/kyber_suite.spec.ts → test/e2e/mlkem_suite.spec.ts
  test/vectors/kyber*.ts → test/vectors/mlkem*.ts (3 files)
  docs/kyber.md          → docs/mlkem.md
  docs/asm_kyber.md      → docs/asm_mlkem.md
  .github/workflows/unit-kyber.yml → unit-mlkem.yml

**Breaking.** The consumer-facing subpath renames from
`leviathan-crypto/kyber` to `leviathan-crypto/mlkem`. Existing
imports break and need updating. The package.json `exports` map
moves correspondingly.

Author: xero

.github/workflows/test-suite.yml

@@ -64,9 +64,9 @@ jobs:
     with:
       bun-version: *bun_version
 
-  unit-kyber:
+  unit-mlkem:
     needs: [build]
-    uses: ./.github/workflows/unit-kyber.yml
+    uses: ./.github/workflows/unit-mlkem.yml
     with:
       bun-version: *bun_version
 
@@ -202,7 +202,7 @@ jobs:
       - unit-serpent
       - unit-chacha20
       - unit-stream
-      - unit-kyber
+      - unit-mlkem
       - unit-hashing
       - unit-montecarlo-cbc
       - unit-montecarlo-ecb

.github/workflows/unit-kyber.yml .github/workflows/unit-mlkem.yml.github/workflows/unit-kyber.yml renamed to .github/workflows/unit-mlkem.yml

@@ -1,4 +1,4 @@
-name: unit-kyber
+name: unit-mlkem
 on:
   workflow_call:
     inputs:
@@ -21,5 +21,5 @@ jobs:
           bun-version: ${{ inputs.bun-version }}
       - name: install dependencies
         run: bun i
-      - name: run kyber unit tests
-        run: bun scripts/test.ts unit:group kyber
+      - name: run mlkem unit tests
+        run: bun scripts/test.ts unit:group mlkem

AGENTS.md

@@ -194,7 +194,7 @@ Decisions already made. Don't relitigate without raising it first.
   layout, AS entry point. `cte.wasm` is the internal SIMD constant-time
   equality module backing the TS `constantTimeEqual`. `cte/shared.ts`
   is the AS source-level `ctEqual` inlined by other modules' compile
-  units (kyber, slhdsa, curve25519, p256) for in-WASM byte equality;
+  units (mlkem, slhdsa, curve25519, p256) for in-WASM byte equality;
   never emitted as a WASM export from any consumer binary.
 - **Static buffers only**: no dynamic allocation (`memory.grow()`
   unused). All buffers are fixed offsets in linear memory defined in
@@ -286,7 +286,7 @@ Playwright discovers e2e specs automatically; no CI change needed for
 e2e. For unit tests:
 
 - Find the `UNIT_GROUPS` entry in `scripts/lib/test-groups.ts` whose
-  `name` matches the test family (`aes`, `mldsa`, `kyber`, etc.). When
+  `name` matches the test family (`aes`, `mldsa`, `mlkem`, etc.). When
   unsure: `grep -l "test/unit/family" scripts/lib/test-groups.ts`.
 - Add or remove the test file path from that group's `files` array.
 - No workflow file edit is needed when adding a test to an existing

CHANGELOG

@@ -11,10 +11,10 @@
   from `(masterKey, nonce, INFO || header)`, bytes 0..32 are the per-stream
   AES-GCM-SIV key, bytes 32..64 are a 32-byte commitment verified in
   constant time. Works with `Seal`, `SealStream`, `OpenStream`,
-  `SealStreamPool`, and `KyberSuite`. The standalone `AESGCMSIV` primitive
+  `SealStreamPool`, and `MlKemSuite`. The standalone `AESGCMSIV` primitive
   still supports both AES-128 and AES-256.
 
-- **`KyberSuite` AES variants.** `KyberSuite(MlKem512/768/1024,
+- **`MlKemSuite` AES variants.** `MlKemSuite(MlKem512/768/1024,
   AESGCMSIVCipher)` produces `formatEnum` 0x14, 0x24, 0x34 with preambles
   820 / 1140 / 1620 bytes, identical to the XChaCha20 KEM variants.
 
@@ -345,17 +345,17 @@
   | `_chachaReady()`       | `isInitialized('chacha20')`    |
   | `_sha2Ready()`         | `isInitialized('sha2')`        |
   | `_sha3Ready()`         | `isInitialized('sha3')`        |
-  | `_kyberReady()`        | `isInitialized('kyber')`       |
+  | `_kyberReady()`        | `isInitialized('mlkem')`       |
 
   Update the import: `import { isInitialized } from 'leviathan-crypto'`.
 
   One semantic narrowing: `_kyberReady()` previously checked **both** the
-  `kyber` and `sha3` modules. The replacement `isInitialized('kyber')`
-  checks only the `kyber` module. If the combined check matters, do
-  `isInitialized('kyber') && isInitialized('sha3')`.
+  `mlkem` and `sha3` modules. The replacement `isInitialized('mlkem')`
+  checks only the `mlkem` module. If the combined check matters, do
+  `isInitialized('mlkem') && isInitialized('sha3')`.
 
 - **`isInitialized(mod)` now re-exported from every submodule subpath.**
-  Previously only the root barrel and the kyber subpath re-exported it.
+  Previously only the root barrel and the mlkem subpath re-exported it.
   Purely additive on the seven other submodule subpaths.
 
 - **`CT_MAX_BYTES` renamed to `CTE_MAX_BYTES`.** The public const that
@@ -367,6 +367,32 @@
   `docs/asm_cte.md`. The TS function name `constantTimeEqual` and the
   WASM ABI are unchanged.
 
+- **`kyber` renamed to `mlkem` everywhere.** Identifiers, file paths,
+  subpath exports, init keys, CI handles, and feature-doc filenames now
+  use the FIPS 203 standardized name. Wire format is unchanged: locked
+  `formatEnum` bytes (0x12-0x34), KEM labels (`mlkem512`/`mlkem768`/
+  `mlkem1024`), and all `MlKem*`/`MLKEM*` symbols were already correct.
+
+  | Old                       | New                       |
+  |---                        |---                        |
+  | `import from 'leviathan-crypto/kyber'`          | `import from 'leviathan-crypto/mlkem'`          |
+  | `import from 'leviathan-crypto/kyber/embedded'` | `import from 'leviathan-crypto/mlkem/embedded'` |
+  | `KyberSuite`              | `MlKemSuite`              |
+  | `KyberParams`             | `MlKemParams`             |
+  | `KyberExports`            | `MlKemExports`            |
+  | `KyberKeyPair`            | `MlKemKeyPair`            |
+  | `KyberEncapsulation`      | `MlKemEncapsulation`      |
+  | `kyberInit(src)`          | `mlkemInit(src)`          |
+  | `kyberWasm`               | `mlkemWasm`               |
+  | `init({ kyber: src })`    | `init({ mlkem: src })`    |
+  | `isInitialized('kyber')`  | `isInitialized('mlkem')`  |
+
+  No backward-compat alias. The `MlKem512`/`MlKem768`/`MlKem1024` class
+  names, the `MLKEM512`/`MLKEM768`/`MLKEM1024` parameter consts, and
+  every wire-format byte and label are unchanged. The historical
+  `docs/kyber_audit.md` keeps its filename and wiki URL as the audit
+  trail for the original FIPS 203 implementation work.
+
 ### Security
 
 - **HtE explicit commitment on `AESGCMSIVCipher`.** Closes the Invisible
@@ -446,7 +472,7 @@
 
 - **`cte/shared.ts ctEqual` for in-WASM byte equality.** New `@inline`
   AssemblyScript helper exporting `ctEqual(aOff, bOff, len): i32`.
-  Imported by `kyber/verify.ts`, `slhdsa/hypertree.ts`,
+  Imported by `mlkem/verify.ts`, `slhdsa/hypertree.ts`,
   `curve25519/ed25519.ts`, and `p256/ecdsa.ts`; the AS compiler inlines
   the body at each call site so the symbol never appears in any consumer
   WASM exports table. Scalar XOR-accumulate with a branch-free
@@ -555,7 +581,7 @@
 
 - **`docs/architecture.md`** per-submodule export map drops the
   `_<module>Ready` entries, picks up the `ratchet/index.ts` row,
-  `kyberInit` in the subpath-init list, and a footnote noting
+  `mlkemInit` in the subpath-init list, and a footnote noting
   `isInitialized(mod)` is now reachable from every submodule subpath.
   New entries for ECDSA-P256, BLAKE3, SLH-DSA, ML-DSA, curve25519, and
   the merkle layer.
@@ -568,7 +594,7 @@
   latest release). SRI example keeps an explicit version pin since the
   integrity hash is bytes-specific. Adds a "Pinning" callout
   recommending pinned versions for production. WASM filenames table
-  picks up a missing `kyber.wasm` row.
+  picks up a missing `mlkem.wasm` row.
 
 - **New shipped docs.** `docs/signaturesuite.md`,
   `docs/phase-index.md`, `docs/blake3.md`, `docs/slhdsa.md`,

README.md

@@ -24,7 +24,7 @@
 
 **Above the cipher suites sits a cipher-agnostic [AEAD layer](https://github.com/xero/leviathan-crypto/wiki/aead):** `Seal`, `SealStream`, `OpenStream`, and `SealStreamPool`. Each takes a `CipherSuite` at construction, and the seal layer handles key derivation, nonce management, and authentication. `Seal` covers one-shot encryption for data that fits in memory. `SealStream` and `OpenStream` handle chunked data too large to buffer. WASM instances are single-threaded by design, so `SealStreamPool` distributes chunks across Web Workers to reach multi-core throughput. Any authentication failure kills the pool. Pending operations reject, workers zero their keys and terminate, and the master synchronously zeroes its copies. No retry, no partial results. All four share one wire format. A `Seal` blob is structurally a single-chunk `SealStream` output, and `OpenStream` decrypts it interchangeably.
 
-**[ML-KEM](https://github.com/xero/leviathan-crypto/wiki/kyber): post-quantum handshake.** `KyberSuite` is a fourth `CipherSuite` factory that wraps an ML-KEM parameter set (`MlKem512`, `MlKem768`, `MlKem1024`) around any of the three ciphers above. The result slots into `Seal`, `SealStream`, `OpenStream`, and `SealStreamPool` unchanged. Constant-time Fujisaki-Okamoto comparisons run inside the Kyber WASM module; the 32-byte shared secret derives directly from a SHA-3 output and never crosses the wire, so the leading-zero-trim timing leak that hit TLS-DH(E) (the Raccoon attack) has no structural analog here.
+**[ML-KEM](https://github.com/xero/leviathan-crypto/wiki/mlkem): post-quantum handshake.** `MlKemSuite` is a fourth `CipherSuite` factory that wraps an ML-KEM parameter set (`MlKem512`, `MlKem768`, `MlKem1024`) around any of the three ciphers above. The result slots into `Seal`, `SealStream`, `OpenStream`, and `SealStreamPool` unchanged. Constant-time Fujisaki-Okamoto comparisons run inside the ML-KEM WASM module; the 32-byte shared secret derives directly from a SHA-3 output and never crosses the wire, so the leading-zero-trim timing leak that hit TLS-DH(E) (the Raccoon attack) has no structural analog here.
 
 **[X25519](https://github.com/xero/leviathan-crypto/wiki/x25519): classical key agreement.** Curve25519 Diffie-Hellman per RFC 7748 §5, with a constant-time Montgomery ladder and TS-layer rejection of the all-zero shared secret. Same key-agreement role as ML-KEM but without post-quantum guarantees; use it for ecosystem interop, ML-KEM when the threat model assumes a future CRQC, or both together when you want a hybrid handshake.
 
@@ -70,7 +70,7 @@ npm install leviathan-crypto
 v3 is the current stable line; semver applies. Runs in modern browsers, Node.js 22+, Bun, Deno, and Cloudflare Workers.
 
 > [!IMPORTANT]
-> [Serpent](https://github.com/xero/leviathan-crypto/wiki/serpent), [ChaCha20](https://github.com/xero/leviathan-crypto/wiki/chacha20), [ML-KEM](https://github.com/xero/leviathan-crypto/wiki/kyber), [AES](https://github.com/xero/leviathan-crypto/wiki/aes), [ML-DSA](https://github.com/xero/leviathan-crypto/wiki/mldsa), [BLAKE3](https://github.com/xero/leviathan-crypto/wiki/blake3), and [constantTimeEqual](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal) require WebAssembly SIMD support. This has been a baseline feature of all major browsers and runtimes [since 2021](https://caniuse.com/wasm-simd).
+> [Serpent](https://github.com/xero/leviathan-crypto/wiki/serpent), [ChaCha20](https://github.com/xero/leviathan-crypto/wiki/chacha20), [ML-KEM](https://github.com/xero/leviathan-crypto/wiki/mlkem), [AES](https://github.com/xero/leviathan-crypto/wiki/aes), [ML-DSA](https://github.com/xero/leviathan-crypto/wiki/mldsa), [BLAKE3](https://github.com/xero/leviathan-crypto/wiki/blake3), and [constantTimeEqual](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal) require WebAssembly SIMD support. This has been a baseline feature of all major browsers and runtimes [since 2021](https://caniuse.com/wasm-simd).
 
 SIMD throughput on Apple Silicon peaks at ~1.3 GB/s for ChaCha20 and ~40 MB/s for Serpent, single-threaded; 1.2-3.2× over scalar. Full matrix across V8, SpiderMonkey, and JSC in [benchmarks](https://github.com/xero/leviathan-crypto/wiki/benchmarks).
 
@@ -126,13 +126,13 @@ import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 await serpentInit(serpentWasm)
 await sha2Init(sha2Wasm)
 
-// ML-KEM requires kyber + sha3
-import { kyberInit } from 'leviathan-crypto/kyber'
-import { kyberWasm } from 'leviathan-crypto/kyber/embedded'
+// ML-KEM requires mlkem + sha3
+import { mlkemInit } from 'leviathan-crypto/mlkem'
+import { mlkemWasm } from 'leviathan-crypto/mlkem/embedded'
 import { sha3Init } from 'leviathan-crypto/sha3'
 import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await kyberInit(kyberWasm)
+await mlkemInit(mlkemWasm)
 await sha3Init(sha3Wasm)
 ```
 
@@ -159,8 +159,8 @@ Real bundle sizes (esbuild minified + gzip):
 | `leviathan-crypto/sha3/embedded`     | SHA-3 WASM blob                                         |
 | `leviathan-crypto/keccak`            | Keccak alias for SHA-3                                  |
 | `leviathan-crypto/keccak/embedded`   | Keccak WASM blob (same bytes as `sha3/embedded`)        |
-| `leviathan-crypto/kyber`             | ML-KEM                                                  |
-| `leviathan-crypto/kyber/embedded`    | ML-KEM WASM blob                                        |
+| `leviathan-crypto/mlkem`             | ML-KEM                                                  |
+| `leviathan-crypto/mlkem/embedded`    | ML-KEM WASM blob                                        |
 | `leviathan-crypto/aes`               | AES-256-GCM-SIV                                         |
 | `leviathan-crypto/aes/embedded`      | AES WASM blob                                           |
 | `leviathan-crypto/blake3`            | BLAKE3                                                  |
@@ -260,16 +260,16 @@ const decrypted = await pool.open(encrypted)
 pool.destroy()
 ```
 
-**_Want post-quantum security?_** [`KyberSuite`](https://github.com/xero/leviathan-crypto/wiki/kyber#kybersuite) wraps ML-KEM and a cipher suite into a hybrid construction. It plugs directly into [`SealStream`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstream). The sender encrypts with the public encapsulation key and only the recipient's private decapsulation key can open it.
+**_Want post-quantum security?_** [`MlKemSuite`](https://github.com/xero/leviathan-crypto/wiki/mlkem#mlkemsuite) wraps ML-KEM and a cipher suite into a hybrid construction. It plugs directly into [`SealStream`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstream). The sender encrypts with the public encapsulation key and only the recipient's private decapsulation key can open it.
 
 ```typescript
-import { KyberSuite, MlKem768 } from 'leviathan-crypto/kyber'
-import { kyberWasm }    from 'leviathan-crypto/kyber/embedded'
+import { MlKemSuite, MlKem768 } from 'leviathan-crypto/mlkem'
+import { mlkemWasm }    from 'leviathan-crypto/mlkem/embedded'
 import { sha3Wasm }     from 'leviathan-crypto/sha3/embedded'
 
-await init({ kyber: kyberWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })
+await init({ mlkem: mlkemWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })
 
-const suite = KyberSuite(new MlKem768(), XChaCha20Cipher)
+const suite = MlKemSuite(new MlKem768(), XChaCha20Cipher)
 const { encapsulationKey: ek, decapsulationKey: dk } = suite.keygen()
 
 // sender: encrypts with the public key
@@ -356,7 +356,7 @@ ECDSA-P256 is classical (not post-quantum); pair it with an ML-DSA or SLH-DSA su
 ```typescript
 import { ratchetInit, KDFChain } from 'leviathan-crypto/ratchet'
 
-await init({ sha2: sha2Wasm })   // KDF layer only; add kyber + sha3 for KEM steps
+await init({ sha2: sha2Wasm })   // KDF layer only; add mlkem + sha3 for KEM steps
 
 const { nextRootKey, sendChainKey, recvChainKey } = ratchetInit(sharedSecret)
 const chain = new KDFChain(sendChainKey)
@@ -393,13 +393,13 @@ lvthn keygen --armor -o my.key
 cat secret.txt | lvthn encrypt -k my.key --armor > secret.enc
 ```
 
-**`kyber`** [ [demo](https://leviathan.3xi.club/kyber) · [source](https://github.com/xero/leviathan-demos/tree/main/kyber) · [readme](https://github.com/xero/leviathan-demos/blob/main/kyber/README.md) ]
+**`mlkem`** [ [demo](https://leviathan.3xi.club/mlkem) · [source](https://github.com/xero/leviathan-demos/tree/main/mlkem) · [readme](https://github.com/xero/leviathan-demos/blob/main/mlkem/README.md) ]
 
 Post-quantum cryptography demo simulating a complete ML-KEM key encapsulation ceremony between two browser-side clients. A live wire at the top of the page logs every value that crosses the channel; importantly, the shared secret never appears in the wire. After the ceremony completes, both sides independently derive a symmetric key using HKDF-SHA256 and exchange messages encrypted with XChaCha20-Poly1305. Each wire frame is expandable, revealing the raw nonce, ciphertext, Poly1305 tag, and AAD.
 
 **`COVCOM`** [ [demo](https://leviathan.3xi.club/covcom) · [source](https://github.com/xero/covcom/) · [readme](https://github.com/xero/covcom/blob/master/README.md) ]
 
-A covert communications application for end-to-end encrypted group conversations. Share an invite, talk, exit, and it's gone. Clients available for both the web and cli, along with a containerized dumb server for managing rooms. No secrets or cleartext beyond the handle you chose to join a room with are ever visible to the server. Featuring sparse post-quantum ratcheting, ML-KEM-768, KDFChains, Seal+KyberSuite, and a XChaCha20-Poly1305 core.
+A covert communications application for end-to-end encrypted group conversations. Share an invite, talk, exit, and it's gone. Clients available for both the web and cli, along with a containerized dumb server for managing rooms. No secrets or cleartext beyond the handle you chose to join a room with are ever visible to the server. Featuring sparse post-quantum ratcheting, ML-KEM-768, KDFChains, Seal+MlKemSuite, and a XChaCha20-Poly1305 core.
 
 ---
 
@@ -410,7 +410,7 @@ A covert communications application for end-to-end encrypted group conversations
 | Encrypt data | [`Seal`](./aead.md#seal) with [`SerpentCipher`](./serpent.md#serpentcipher), [`XChaCha20Cipher`](./chacha20.md#xchacha20cipher), or [`AESGCMSIVCipher`](./aes.md#aesgcmsivcipher) |
 | Encrypt a stream or large file | [`SealStream`](./aead.md#sealstream) to encrypt, [`OpenStream`](./aead.md#openstream) to decrypt |
 | Encrypt in parallel | [`SealStreamPool`](./aead.md#sealstreampool) distributes chunks across Web Workers |
-| Add post-quantum security | [`KyberSuite`](./kyber.md#kybersuite) wraps [`MlKem512`](./kyber.md#parameter-sets), [`MlKem768`](./kyber.md#parameter-sets), or [`MlKem1024`](./kyber.md#parameter-sets) with any cipher suite |
+| Add post-quantum security | [`MlKemSuite`](./mlkem.md#mlkemsuite) wraps [`MlKem512`](./mlkem.md#parameter-sets), [`MlKem768`](./mlkem.md#parameter-sets), or [`MlKem1024`](./mlkem.md#parameter-sets) with any cipher suite |
 | Build a forward-secret session | [`ratchetInit`](./ratchet.md#ratchetinit), [`KDFChain`](./ratchet.md#kdfchain), [`kemRatchetEncap`](./ratchet.md#kemratchetencap) / [`kemRatchetDecap`](./ratchet.md#kemratchetdecap), [`SkippedKeyStore`](./ratchet.md#skippedkeystore) |
 | Sign data with a classical signature | [`Ed25519Suite`](./signaturesuite.md#ed25519-suites) / [`Ed25519PreHashSuite`](./signaturesuite.md#ed25519-suites) ([ed25519.md](./ed25519.md)) or [`EcdsaP256Suite`](./signaturesuite.md#ecdsa-p256-suite) ([ecdsa-p256.md](./ecdsa-p256.md)) via [`Sign`](./signing.md#sign) / [`SignStream`](./signing.md#signstream) / [`VerifyStream`](./signing.md#verifystream) |
 | Sign data with a post-quantum signature | `MlDsa44/65/87Suite` (+ `*PreHashSuite`) for lattice ML-DSA ([mldsa.md](./mldsa.md)) or `SlhDsa128f/192f/256fSuite` (+ `*PreHashSuite`) for hash-based SLH-DSA ([slhdsa.md](./slhdsa.md)). Full catalog in [signaturesuite.md](./signaturesuite.md) |