leviathan-crypto 2.0.1 → 2.1.0

package/dist/docs/argon2id.md

@@ -1,9 +1,8 @@
-# Argon2id: Memory-Hardened Password Hashing and Key Derivation
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="logo" width="120" align="left" margin="10">
 
-> [!NOTE]
-> leviathan-crypto does not wrap Argon2id. This document covers how to use the
-> [`argon2id`](https://www.npmjs.com/package/argon2id) npm package directly and
-> how to pair it with leviathan primitives for passphrase-based encryption.
+### Argon2id: Memory-Hardened Password Hashing and Key Derivation
+
+leviathan-crypto does not wrap Argon2id. This document covers how to use the [`argon2id`](https://www.npmjs.com/package/argon2id) npm package directly and how to pair it with leviathan primitives for passphrase-based encryption.
 
 > ### Table of Contents
 > - [Why Argon2id](#why-argon2id)
@@ -291,12 +290,16 @@ xc2.dispose();
 
 ---
 
-> ## Cross-References
->
-> - [index](./README.md) — Project Documentation index
-> - [sha2](./sha2.md) — HKDF-SHA256 for key expansion from Argon2id root keys
-> - [serpent](./serpent.md) — `SerpentCipher`: Serpent-256 cipher suite (use with `Seal` and Argon2id-derived keys)
-> - [authenticated encryption](./aead.md) — `Seal`: one-shot AEAD over any `CipherSuite`
-> - [chacha20](./chacha20.md) — XChaCha20Poly1305: ChaCha20 authenticated encryption (pairs with Argon2id-derived keys)
-> - [utils](./utils.md) — `randomBytes` for generating salts, `constantTimeEqual` for hash verification
-> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
+
+## Cross-References
+
+| Document | Description |
+| -------- | ----------- |
+| [index](./README.md) | Project Documentation index |
+| [sha2](./sha2.md) | HKDF-SHA256 for key expansion from Argon2id root keys |
+| [serpent](./serpent.md) | `SerpentCipher`: Serpent-256 cipher suite (use with `Seal` and Argon2id-derived keys) |
+| [authenticated encryption](./aead.md) | `Seal`, `SealStream`, `OpenStream`: cipher-agnostic AEAD APIs using a `CipherSuite` such as `SerpentCipher` or `XChaCha20Cipher` |
+| [chacha20](./chacha20.md) | XChaCha20Poly1305: ChaCha20 authenticated encryption (pairs with Argon2id-derived keys) |
+| [utils](./utils.md) | `randomBytes` for generating salts, `constantTimeEqual` for hash verification |
+| [architecture](./architecture.md) | architecture overview, module relationships, buffer layouts, and build pipeline |
+

package/dist/docs/chacha20.md

@@ -1,7 +1,8 @@
-# ChaCha20 TypeScript API
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="logo" width="120" align="left" margin="10">
 
-> [!NOTE]
-> API reference for `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, and `XChaCha20Cipher`. Covers initialization, all class methods, usage examples, and error conditions.
+### ChaCha20 TypeScript API
+
+API reference for `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, and `XChaCha20Cipher`. Covers initialization, all class methods, usage examples, and error conditions.
 
 > ### Table of Contents
 > - [Overview](#overview)
@@ -12,6 +13,7 @@
 >   - [`Poly1305`](#poly1305)
 >   - [`ChaCha20Poly1305`](#chacha20poly1305)
 >   - [`XChaCha20Poly1305`](#xchacha20poly1305)
+>   - [`ChaCha20Generator`](#chacha20generator)
 > - [XChaCha20Cipher](#xchacha20cipher)
 > - [Usage Examples](#usage-examples)
 > - [Error Conditions](#error-conditions)
@@ -20,11 +22,13 @@
 
 ## Overview
 
-**ChaCha20** is a modern stream cipher designed by Daniel J. Bernstein. It is fast
-on all platforms (including those without hardware AES), resistant to timing attacks
-by design, and widely deployed in TLS, SSH, and WireGuard. ChaCha20 encrypts data
-by generating a pseudorandom keystream from a 256-bit key and a nonce, then XORing
-it with the plaintext. It does **not** provide authentication on its own. A modified message will decrypt to garbage with no warning.
+**ChaCha20** is a modern stream cipher designed by Daniel J. Bernstein. It is
+fast on all platforms (including those without hardware AES), resistant to
+timing attacks by design, and widely deployed in TLS, SSH, and WireGuard.
+ChaCha20 encrypts data by generating a pseudorandom keystream from a 256-bit
+key and a nonce, then XORing it with the plaintext. It does **not** provide
+authentication on its own. A modified message will decrypt to garbage with no
+warning.
 
 **Poly1305** is a one-time message authentication code (MAC). Given a unique 256-bit
 key and a message, it produces a 16-byte tag that proves the message has not been
@@ -41,10 +45,10 @@ you get an error instead of corrupted data. The nonce is 96 bits (12 bytes).
 **XChaCha20-Poly1305** extends the nonce to 192 bits (24 bytes) using the HChaCha20
 subkey derivation step. This makes random nonce generation completely safe. With a
 24-byte nonce, the probability of a collision is negligible even after billions of
-messages. **For most users, `Seal` with `XChaCha20Cipher` is the recommended choice.** It
-produces a self-contained authenticated blob with no nonce management, no
-instantiation, and no `dispose()`. For protocol interop requiring explicit nonce
-control, use `XChaCha20Poly1305` directly.
+messages. **For most users, [`Seal`](./aead.md#seal) with [`XChaCha20Cipher`](./ciphersuite.md#xchacha20cipher)
+is the recommended choice.** It produces a self-contained authenticated blob with
+no nonce management, no instantiation, and no `dispose()`. For protocol interop
+requiring explicit nonce control, use `XChaCha20Poly1305` directly.
 
 ---
 
@@ -54,10 +58,10 @@ control, use `XChaCha20Poly1305` directly.
 > Read this section before writing any code. These are not theoretical concerns.
 > They are the mistakes that cause real-world breaches.
 
-- **Use `Seal` with `XChaCha20Cipher` unless you need explicit nonce control.**
-  It is the safest default: authenticated encryption in a single static call.
-  If you are unsure which class to pick, pick this one. Use `XChaCha20Poly1305`
-  when protocol interop requires you to manage nonces yourself.
+- **Use [`Seal`](./aead.md#seal) with [`XChaCha20Cipher`](./ciphersuite.md#xchacha20cipher)
+  unless you need explicit nonce control.** It is the safest default: authenticated
+  encryption in a single static call. If you are unsure which class to pick, pick this
+  one. Use `XChaCha20Poly1305` when protocol interop requires you to manage nonces yourself.
 
 - **Never reuse a nonce with the same key.** This is the single most important
   rule. If you encrypt two different messages with the same key and the same nonce,
@@ -138,13 +142,21 @@ Error: leviathan-crypto: call init({ chacha20: ... }) before using this class
 Raw ChaCha20 stream cipher. **No authentication.** Use `XChaCha20Poly1305` instead
 unless you are building a custom protocol and understand the risks.
 
+> [!CAUTION]
+> `ChaCha20` is stateful and holds exclusive access to the `chacha20` WASM
+> module for its entire lifetime. Constructing a second `ChaCha20`, or any
+> atomic chacha20 class (`Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`,
+> or a `XChaCha20Cipher`-backed `Seal`/`SealStream`), while this instance is
+> live throws. Call `dispose()` when done. Pool workers are unaffected.
+
 #### Constructor
 
 ```typescript
 new ChaCha20()
 ```
 
-Throws if `init({ chacha20: chacha20Wasm })` has not been called.
+Throws if `init({ chacha20: chacha20Wasm })` has not been called, or if
+another stateful chacha20 instance is still live.
 
 ---
 
@@ -159,6 +171,13 @@ Prepares the cipher for encryption with the given key and nonce.
 
 **Throws** `RangeError` if `key` is not 32 bytes or `nonce` is not 12 bytes.
 
+> [!NOTE]
+> **Block counter convention.** `beginEncrypt()` starts the ChaCha20 keystream
+> at block counter 1, not 0. Block 0 is reserved for Poly1305 one-time key
+> generation per RFC 8439 §2.6. The class is designed for use inside an AEAD
+> construction; if you need to match RFC 8439 §2.4.2 verbatim (keystream
+> starting at counter 0), use the lower-level primitives directly.
+
 ---
 
 #### `encryptChunk(chunk: Uint8Array): Uint8Array`
@@ -176,7 +195,8 @@ a new `Uint8Array` containing the ciphertext (same length as input).
 
 #### `beginDecrypt(key: Uint8Array, nonce: Uint8Array): void`
 
-Prepares the cipher for decryption. Identical to `beginEncrypt`. ChaCha20 is symmetric; encryption and decryption are the same XOR operation.
+Prepares the cipher for decryption. Identical to `beginEncrypt`. ChaCha20 is
+symmetric; encryption and decryption are the same XOR operation.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -205,6 +225,11 @@ plaintext (same length as input).
 Wipes all key material and intermediate state from WASM memory. Always call this
 when you are done with the instance.
 
+After `dispose()`, all instance methods (`beginEncrypt`, `encryptChunk`,
+`beginDecrypt`, `decryptChunk`) throw `Error: ChaCha20: instance has been
+disposed`. Disposal is permanent; construct a new instance if you need to
+continue.
+
 ---
 
 ### `Poly1305`
@@ -272,6 +297,13 @@ appended.
 > Each `ChaCha20Poly1305` instance allows only **one** `encrypt()` call. A second
 > call throws to prevent accidental nonce reuse. Create a new instance for each
 > encryption, or use `Seal` with `XChaCha20Cipher` for automatic nonce management.
+>
+> **Strict single-use on any throw.** Any throw from `encrypt()`, including
+> `RangeError` from wrong-length `key` or `nonce`, exclusivity errors, or any
+> failure inside the WASM call, is *terminal*. The guard is set before
+> argument validation, so a subsequent `encrypt()` on the same instance throws
+> the single-use error rather than retrying. Always allocate a new AEAD
+> instance per message.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
@@ -283,9 +315,9 @@ appended.
 **Returns** `Uint8Array`: ciphertext + 16-byte tag (length = plaintext.length + 16).
 
 **Throws:**
-- `RangeError` if `key` is not 32 bytes
-- `RangeError` if `nonce` is not 12 bytes
-- `RangeError` if `plaintext` exceeds the maximum chunk size
+- `RangeError` if `key` is not 32 bytes *(terminal: instance locked)*
+- `RangeError` if `nonce` is not 12 bytes *(terminal: instance locked)*
+- `RangeError` if `plaintext` exceeds the maximum chunk size *(terminal: instance locked)*
 - `Error` if `encrypt()` has already been called on this instance
 
 ---
@@ -297,7 +329,8 @@ parameter must include the appended 16-byte tag (i.e., the exact output of
 `encrypt()`). If authentication fails, an error is thrown and no plaintext is
 returned.
 
-Tag comparison uses a constant-time XOR-accumulate pattern; no timing side channel leaks whether the tag was "close" to correct.
+Tag comparison uses a constant-time XOR-accumulate pattern; no timing side
+channel leaks whether the tag was "close" to correct.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
@@ -326,8 +359,8 @@ Wipes all key material and intermediate state from WASM memory.
 
 XChaCha20-Poly1305 AEAD (draft-irtf-cfrg-xchacha). RFC-faithful stateless
 primitive. Key and nonce are passed per-call. Use when protocol interop
-requires explicit nonce control. For most use cases, prefer `Seal` with
-`XChaCha20Cipher` (automatic nonce management, no instantiation).
+requires explicit nonce control. For most use cases, prefer [`Seal`](./aead.md#seal)
+with [`XChaCha20Cipher`](./ciphersuite.md#xchacha20cipher)(automatic nonce management, no instantiation).
 
 It uses a 24-byte (192-bit) nonce, which is large enough that randomly generated
 nonces will never collide in practice. Internally, it derives a subkey via
@@ -351,6 +384,19 @@ Throws if `init({ chacha20: chacha20Wasm })` has not been called.
 
 Encrypts plaintext and returns the ciphertext with the 16-byte tag appended.
 
+> [!WARNING]
+> Same single-use contract as `ChaCha20Poly1305.encrypt()`. Each instance
+> allows only **one** `encrypt()` call. A second call throws to prevent
+> accidental nonce reuse. Create a new instance for each encryption, or use
+> `Seal` with `XChaCha20Cipher` for automatic nonce management.
+>
+> **Strict single-use on any throw.** Any throw from `encrypt()` is *terminal*,
+> whether the cause is a `RangeError` from wrong-length `key` or `nonce`, an
+> exclusivity error, or a failure inside the WASM call. The guard is set
+> before argument validation, so a subsequent `encrypt()` on the same instance
+> throws the single-use error rather than retrying with a reused nonce. Always
+> allocate a new AEAD instance per message.
+
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `key` | `Uint8Array` | | 32 bytes (256-bit key) |
@@ -361,8 +407,10 @@ Encrypts plaintext and returns the ciphertext with the 16-byte tag appended.
 **Returns** `Uint8Array`: ciphertext + 16-byte tag (length = plaintext.length + 16).
 
 **Throws:**
-- `RangeError` if `key` is not 32 bytes
-- `RangeError` if `nonce` is not 24 bytes
+- `RangeError` if `key` is not 32 bytes *(terminal: instance locked)*
+- `RangeError` if `nonce` is not 24 bytes *(terminal: instance locked)*
+- `RangeError` if `plaintext` exceeds the maximum chunk size *(terminal: instance locked)*
+- `Error` if `encrypt()` has already been called on this instance
 
 ---
 
@@ -395,6 +443,59 @@ Wipes all key material and intermediate state from WASM memory.
 
 ---
 
+### ChaCha20Generator
+
+ChaCha20 block-function PRF for Fortuna's generator slot (RFC 8439 §2.3).
+Uses a fixed zero nonce; Fortuna's counter is the only varying input.
+Implements the `Generator` interface. Plain `const` object — no instantiation,
+no `dispose()`.
+
+Requires `init({ chacha20: chacha20Wasm })`. See [fortuna.md](./fortuna.md)
+for full usage with `Fortuna.create()`.
+
+| Property | Value |
+|----------|-------|
+| `keySize` | `32` |
+| `blockSize` | `64` |
+| `counterSize` | `4` |
+| `wasmModules` | `['chacha20']` |
+
+#### `ChaCha20Generator.generate(key, counter, n): Uint8Array`
+
+Produces `n` bytes from `(key, counter)`. Neither input is mutated. Wipes WASM
+key/state/keystream scratch before returning.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `Uint8Array` | 32 bytes |
+| `counter` | `Uint8Array` | 4 bytes, read as a little-endian u32 |
+| `n` | `number` | Output byte count: 0 ≤ n ≤ 2³⁰ |
+
+**Returns** a new `Uint8Array` of length `n`.
+
+**Throws:**
+- `RangeError('ChaCha20Generator: key must be 32 bytes (got N)')` if key length ≠ 32
+- `RangeError('ChaCha20Generator: counter must be 4 bytes (got N)')` if counter length ≠ 4
+- `RangeError('ChaCha20Generator: n must be a non-negative safe integer <= 2^30 (got N)')` if n is out of range
+- `Error` if another stateful instance currently owns the `chacha20` WASM module
+
+#### Usage with `Fortuna`
+
+```typescript
+import { init, Fortuna } from 'leviathan-crypto'
+import { ChaCha20Generator } from 'leviathan-crypto/chacha20'
+import { SHA256Hash } from 'leviathan-crypto/sha2'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
+
+await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })
+const rng = await Fortuna.create({ generator: ChaCha20Generator, hash: SHA256Hash })
+const bytes = rng.get(32)
+rng.stop()
+```
+
+---
+
 ## XChaCha20Cipher
 
 `CipherSuite` implementation for XChaCha20-Poly1305. Pass to `Seal`,
@@ -412,7 +513,7 @@ Requires `init({ chacha20: chacha20Wasm, sha2: sha2Wasm })`.
 | `keySize` | `32` |
 | `tagSize` | `16` (Poly1305) |
 | `padded` | `false` |
-| `wasmModules` | `['chacha20', 'sha2']` |
+| `wasmModules` | `['chacha20']` |
 
 #### `XChaCha20Cipher.keygen(): Uint8Array`
 
@@ -638,7 +739,7 @@ const pt2 = cipher.decryptChunk(ct2)
 
 // WARNING: Without authentication, an attacker can flip bits in ciphertext
 // and the corresponding plaintext bits will flip with no error.
-// Pair with HMAC (Encrypt-then-MAC) or use XChaCha20Poly1305 instead.
+// Use the seal api or XChaCha20Poly1305 instead.
 
 cipher.dispose()
 ```
@@ -660,15 +761,21 @@ cipher.dispose()
 | Chunk or plaintext exceeds WASM buffer size | `RangeError` | `plaintext exceeds N bytes — split into smaller chunks` / `chunk exceeds maximum size of N bytes — split into smaller chunks` |
 | Authentication tag does not match on decrypt | `Error` | `ChaCha20Poly1305: authentication failed` |
 | Empty plaintext | | Allowed. Encrypting zero bytes produces just a 16-byte tag (AEAD) or zero bytes (raw ChaCha20). |
+| `ChaCha20Generator.generate()` key ≠ 32 bytes | `RangeError` | `ChaCha20Generator: key must be 32 bytes (got N)` |
+| `ChaCha20Generator.generate()` counter ≠ 4 bytes | `RangeError` | `ChaCha20Generator: counter must be 4 bytes (got N)` |
+| `ChaCha20Generator.generate()` n out of range | `RangeError` | `ChaCha20Generator: n must be a non-negative safe integer <= 2^30 (got N)` |
+
+## Cross-References
+
+| Document | Description |
+| -------- | ----------- |
+| [index](./README.md) | Project Documentation index |
+| [lexicon](./lexicon.md) | Glossary of cryptographic terms |
+| [asm_chacha](./asm_chacha.md) | WASM (AssemblyScript) implementation details for the chacha20 module |
+| [authenticated encryption](./aead.md) | `Seal`, `SealStream`, `OpenStream`: use `XChaCha20Cipher` as the suite argument |
+| [serpent](./serpent.md) | `SerpentCipher`: alternative `CipherSuite` for `Seal` and streaming |
+| [sha2](./sha2.md) | SHA-2 hashes and HMAC. Needed for Encrypt-then-MAC if using raw ChaCha20 |
+| [types](./types.md) | `AEAD` and `Streamcipher` interfaces implemented by ChaCha20 classes |
+| [architecture](./architecture.md) | architecture overview, module relationships, buffer layouts, and build pipeline |
+| [chacha_audit](./chacha_audit.md) | XChaCha20-Poly1305 implementation audit |
 
-> ## Cross-References
->
-> - [index](./README.md) — Project Documentation index
-> - [lexicon](./lexicon.md) — Glossary of cryptographic terms
-> - [asm_chacha](./asm_chacha.md) — WASM (AssemblyScript) implementation details for the chacha20 module
-> - [authenticated encryption](./aead.md) — `Seal`, `SealStream`, `OpenStream`: use `XChaCha20Cipher` as the suite argument
-> - [serpent](./serpent.md) — `SerpentCipher`: alternative `CipherSuite` for `Seal` and streaming
-> - [sha2](./sha2.md) — SHA-2 hashes and HMAC. Needed for Encrypt-then-MAC if using raw ChaCha20
-> - [types](./types.md) — `AEAD` and `Streamcipher` interfaces implemented by ChaCha20 classes
-> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
-> - [chacha_audit](./chacha_audit.md) — XChaCha20-Poly1305 implementation audit

package/dist/docs/exports.md

@@ -1,7 +1,8 @@
-# All Exports
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="logo" width="120" align="left" margin="10">
 
-> [!NOTE]
-> Complete reference for every public export in leviathan-crypto, grouped by module. Follow the module links for deeper documentation on each class.
+### All Exports
+
+Complete reference for every public export in leviathan-crypto, grouped by module. Follow the module links for deeper documentation on each class.
 
 > ### Table of Contents
 > - [Initialization](#initialization)
@@ -14,6 +15,7 @@
 > - [Keccak (alias for SHA-3)](#keccak-alias-for-sha-3)
 > - [ML-KEM (Post-quantum KEM)](#ml-kem-post-quantum-kem)
 > - [Fortuna CSPRNG](#fortuna-csprng)
+> - [Ratchet (Sparse Post-Quantum Ratchet KDF)](#ratchet-sparse-post-quantum-ratchet-kdf)
 > - [Types](#types)
 > - [Utilities](#utilities)
 
@@ -191,11 +193,41 @@ Subpath: `leviathan-crypto/kyber`. See [kyber.md](./kyber.md).
 
 ## Fortuna CSPRNG
 
-Requires `init({ serpent: serpentWasm, sha2: sha2Wasm })`. See [fortuna.md](./fortuna.md).
+Takes a `Generator` and a `HashFn` at create time. Required `init()` modules depend on which pair you pass; valid combinations are listed in [fortuna.md](./fortuna.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `Fortuna`            | class    | Fortuna CSPRNG (Ferguson & Schneier). `Fortuna.create({ generator, hash })` static factory; `get(n)`, `addEntropy()`, `stop()`. |
+| `SerpentGenerator`   | const    | `Generator` const for `Fortuna`. Serpent-256 PRF in counter mode. Requires `init({ serpent })`. Re-exported from `'leviathan-crypto/serpent'`. |
+| `ChaCha20Generator`  | const    | `Generator` const for `Fortuna`. ChaCha20 PRF with fixed zero nonce. Requires `init({ chacha20 })`. Re-exported from `'leviathan-crypto/chacha20'`. |
+| `SHA256Hash`         | const    | `HashFn` const for `Fortuna`. Stateless SHA-256. Requires `init({ sha2 })`. Re-exported from `'leviathan-crypto/sha2'`. |
+| `SHA3_256Hash`       | const    | `HashFn` const for `Fortuna`. Stateless SHA3-256. Requires `init({ sha3 })`. Re-exported from `'leviathan-crypto/sha3'`. |
+| `Generator`          | type     | Interface implemented by `SerpentGenerator` and `ChaCha20Generator`. |
+| `HashFn`             | type     | Interface implemented by `SHA256Hash` and `SHA3_256Hash`. |
+
+---
+
+## Ratchet (Sparse Post-Quantum Ratchet KDF)
+
+`ratchetInit`, `KDFChain`, `ratchetReady` require `init({ sha2: sha2Wasm })`.
+`kemRatchetEncap`, `kemRatchetDecap` additionally require `init({ kyber: kyberWasm, sha3: sha3Wasm })`.
+Subpath: `leviathan-crypto/ratchet`. See [ratchet.md](./ratchet.md).
 
 | Export | Kind | Description |
 |--------|------|-------------|
-| `Fortuna` | class | Fortuna CSPRNG (Ferguson & Schneier). `Fortuna.create()` static factory, `get(n)`, `addEntropy()`, `stop()`. |
+| `ratchetInit` | function | `ratchetInit(sk, context?)` — derives initial root key, send chain key, and receive chain key from a 32-byte shared secret (`KDF_SCKA_INIT`). Returns `RatchetInitResult`. |
+| `KDFChain` | class | Stateful symmetric ratchet chain (`KDF_SCKA_CK`). `new KDFChain(ck)`, `step()` → 32-byte message key, `stepWithCounter()` → `{ key, counter }`, `dispose()`. |
+| `SkippedKeyStore` | class | MKSKIPPED cache for a single `KDFChain` (DR spec §3.2/§3.5). `new SkippedKeyStore({ maxCacheSize?, maxSkipPerResolve? })`. `resolve(chain, counter)` → `ResolveHandle` — call `handle.commit()` on successful decrypt, `handle.rollback()` on auth failure. `advanceToBoundary(chain, pn)`, `size`, `wipeAll()`. Requires `sha2`. |
+| `RatchetKeypair` | class | Single-use ek/dk lifecycle for one KEM ratchet step. `new RatchetKeypair(kem)`, `readonly ek`, `decap(kem, rk, kemCt, context?)`, `dispose()`. Requires `sha2`, `kyber`, `sha3`. |
+| `kemRatchetEncap` | function | `kemRatchetEncap(kem, rk, peerEk, context?)` — encapsulation side of a KEM ratchet step (`KDF_SCKA_RK`). Returns `KemEncapResult` including `kemCt` to transmit to peer. |
+| `kemRatchetDecap` | function | `kemRatchetDecap(kem, rk, dk, kemCt, ownEk, context?)` — decapsulation side of a KEM ratchet step. `ownEk` is the local party's encapsulation key, bound into the HKDF info string alongside `peerEk` and `kemCt` as defense-in-depth on top of the KEM FO transform. Returns `KemDecapResult` with chain key slots swapped to match Bob's perspective. |
+| `ratchetReady` | function | `ratchetReady(): boolean` — returns `true` if `sha2` has been initialized. |
+| `RatchetInitResult` | type | `{ nextRootKey, sendChainKey, recvChainKey }` — all 32-byte `Uint8Array` fields. |
+| `KemEncapResult` | type | `{ nextRootKey, sendChainKey, recvChainKey, kemCt }` — three 32-byte keys plus the ML-KEM ciphertext. |
+| `KemDecapResult` | type | `{ nextRootKey, sendChainKey, recvChainKey }` — all 32-byte `Uint8Array` fields. Slots are swapped relative to the encap side. |
+| `RatchetMessageHeader` | interface | `{ epoch, counter, pn?, kemCt? }` — canonical message header shape. `pn` and `kemCt` present only on the first message of a new epoch. |
+| `MlKemLike` | interface | Structural interface satisfied by `MlKem512`, `MlKem768`, `MlKem1024`. Used as the `kem` parameter type for `kemRatchetEncap`/`kemRatchetDecap`/`RatchetKeypair`. |
+| `ResolveHandle` | interface | Return type of `SkippedKeyStore.resolve()`. `readonly key` — 32-byte message key (throws after settlement). `commit()` — wipes key, marks settled (call on successful decrypt). `rollback()` — returns key to store, marks settled (call on auth failure). Double-settle throws. |
 
 ---
 
@@ -225,7 +257,7 @@ No `init()` required. See [utils.md](./utils.md).
 | `bytesToUtf8` | function | `Uint8Array` to UTF-8 string. |
 | `base64ToBytes` | function | Base64/base64url string to `Uint8Array`. Returns `undefined` on invalid input. |
 | `bytesToBase64` | function | `Uint8Array` to base64 string. Pass `url=true` for base64url. |
-| `constantTimeEqual` | function | Best-available constant-time byte-array equality. Uses WASM SIMD when available to eliminate JIT timing leaks; falls back to XOR-accumulate in JS. Returns `false` immediately on length mismatch. Throws `RangeError` if either input exceeds `CT_MAX_BYTES`. |
+| `constantTimeEqual` | function | Constant-time byte-array equality. Runs entirely inside a dedicated WASM SIMD module (v128 XOR-accumulate with branch-free reduction) to eliminate JIT timing leaks. Throws a branded error on runtimes without WebAssembly SIMD; no JS fallback. Returns `false` immediately on length mismatch. Throws `RangeError` if either input exceeds `CT_MAX_BYTES`. |
 | `CT_MAX_BYTES` | const | Maximum input size for `constantTimeEqual` per side (32768 bytes, one 64 KiB WASM page split between two buffers). |
 | `wipe` | function | Zero a typed array in place. |
 | `xor` | function | XOR two equal-length `Uint8Array`s, returns new array. |
@@ -235,7 +267,11 @@ No `init()` required. See [utils.md](./utils.md).
 
 ---
 
-> ## Cross-References
->
-> - [index](./README.md) — Project Documentation index
-> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
+
+## Cross-References
+
+| Document | Description |
+| -------- | ----------- |
+| [index](./README.md) | Project Documentation index |
+| [architecture](./architecture.md) | architecture overview, module relationships, buffer layouts, and build pipeline |
+