leviathan-crypto 1.4.0 → 2.0.1

package/dist/docs/exports.md

@@ -0,0 +1,241 @@
+# All Exports
+
+> [!NOTE]
+> 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)
+> - [Serpent-256](#serpent-256)
+> - [Stream](#stream)
+> - [Errors](#errors)
+> - [XChaCha20 / Poly1305](#xchacha20--poly1305)
+> - [SHA-2](#sha-2)
+> - [SHA-3](#sha-3)
+> - [Keccak (alias for SHA-3)](#keccak-alias-for-sha-3)
+> - [ML-KEM (Post-quantum KEM)](#ml-kem-post-quantum-kem)
+> - [Fortuna CSPRNG](#fortuna-csprng)
+> - [Types](#types)
+> - [Utilities](#utilities)
+
+---
+
+## Initialization
+
+Root barrel `leviathan-crypto`. No module required.
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `init` | function | Load and cache WASM modules. `init(sources: Partial<Record<Module, WasmSource>>)`. |
+| `isInitialized` | function | `isInitialized(mod: Module): boolean`. Returns `true` if the given module has been loaded. Useful for diagnostic checks. |
+| `Module` | type | `'serpent' \| 'chacha20' \| 'sha2' \| 'sha3' \| 'keccak' \| 'kyber'` |
+| `WasmSource` | type | Union of all accepted WASM loading strategies. See below. |
+
+**`WasmSource`** accepted by every init function:
+
+| Value | Strategy |
+|-------|----------|
+| `string` | Decode gzip+base64 embedded blob |
+| `URL` | `fetch` + `instantiateStreaming` |
+| `ArrayBuffer` | Compile from raw WASM bytes |
+| `Uint8Array` | Compile from raw WASM bytes |
+| `WebAssembly.Module` | Instantiate pre-compiled module |
+| `Response` | `instantiateStreaming` from fetch response |
+| `Promise<Response>` | `instantiateStreaming` from deferred fetch |
+
+See [init.md](./init.md) for full loading documentation.
+
+---
+
+## Serpent-256
+
+Requires `init({ serpent: serpentWasm, sha2: sha2Wasm })` for authenticated classes, `init({ serpent: serpentWasm })` for raw modes.
+Subpath: `leviathan-crypto/serpent`. See [serpent.md](./serpent.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `serpentInit` | function | Module-scoped init. `serpentInit(source: WasmSource)` loads only serpent. |
+| `SerpentCipher` | const | `CipherSuite` for Serpent-256 CBC+HMAC-SHA-256. `keygen()` → 32-byte key. `formatEnum: 0x02`, `keySize: 32`, `tagSize: 32`, `padded: true`. Used with `Seal`, `SealStream`, `OpenStream`. |
+| `Serpent` | class | Serpent-256 ECB block cipher. `loadKey()`, `encryptBlock()`, `decryptBlock()`. Unauthenticated. |
+| `SerpentCtr` | class | Serpent-256 CTR mode. `beginEncrypt()`, `encryptChunk()`, `beginDecrypt()`, `decryptChunk()`. Unauthenticated. |
+| `SerpentCbc` | class | Serpent-256 CBC mode with PKCS7 padding. `encrypt(key, iv, plaintext)`, `decrypt(key, iv, ciphertext)`. Unauthenticated. |
+
+---
+
+## Stream
+
+Cipher-agnostic streaming encryption using the STREAM construction.
+Subpath: `leviathan-crypto/stream`. See [aead.md](./aead.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `Seal` | class (static) | One-shot AEAD. `Seal.encrypt(suite, key, plaintext)` / `Seal.decrypt(suite, key, blob)`. Works with any `CipherSuite` including `KyberSuite`. Never instantiated. |
+| `SealStream` | class | Cipher-agnostic streaming encryption (STREAM construction). `push(chunk)`, `finalize(chunk)`, `toTransformStream()`. |
+| `OpenStream` | class | Cipher-agnostic streaming decryption. `pull(chunk)`, `finalize(chunk)`, `seek(index)`, `toTransformStream()`. |
+| `SealStreamPool` | class | Parallel batch seal/open via Web Workers. `SealStreamPool.create(cipher, key, opts)` static factory. |
+| `CipherSuite` | interface | Cipher-specific logic injected into SealStream/OpenStream. Implementations: `XChaCha20Cipher`, `SerpentCipher`, `KyberSuite`. See [ciphersuite.md](./ciphersuite.md). |
+| `DerivedKeys` | interface | Opaque key material returned by `CipherSuite.deriveKeys()`. |
+| `SealStreamOpts` | type | Options for SealStream: `chunkSize?`, `framed?`. |
+| `PoolOpts` | type | Options for SealStreamPool: `wasm`, `workers?`, `chunkSize?`, `framed?`, `jobTimeout?`. |
+| `HEADER_SIZE` | const | Stream header size in bytes (20). |
+| `CHUNK_MIN` | const | Minimum chunk size (1024). |
+| `CHUNK_MAX` | const | Maximum chunk size (16777215, u24 max). |
+| `FLAG_FRAMED` | const | Header byte 0 framed flag (0x80). |
+| `TAG_DATA` | const | Counter nonce final flag for data chunks (0x00). |
+| `TAG_FINAL` | const | Counter nonce final flag for final chunk (0x01). |
+
+---
+
+## Errors
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `AuthenticationError` | class | Thrown on AEAD auth failure. Extends `Error`. Constructor takes cipher name string. |
+
+---
+
+## XChaCha20 / Poly1305
+
+Requires `init({ chacha20: chacha20Wasm })` or subpath `chacha20Init()`.
+Subpath: `leviathan-crypto/chacha20`. See [chacha20.md](./chacha20.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `chacha20Init` | function | Module-scoped init. `chacha20Init(source: WasmSource)` loads only chacha20. |
+| `XChaCha20Poly1305` | class | XChaCha20-Poly1305 AEAD. 24-byte nonce. `encrypt()` returns single `Uint8Array` (ct‖tag), `decrypt()` accepts same format. Single-use encrypt guard. |
+| `XChaCha20Cipher` | const | `CipherSuite` for XChaCha20-Poly1305. `keygen()` → 32-byte key. `formatEnum: 0x01`, `keySize: 32`, `tagSize: 16`, `padded: false`. Used with `Seal`, `SealStream`, `OpenStream`. |
+| `ChaCha20Poly1305` | class | ChaCha20-Poly1305 AEAD (RFC 8439). 12-byte nonce. `encrypt()` returns single `Uint8Array` (ct‖tag), `decrypt()` accepts same format. Single-use encrypt guard. |
+| `ChaCha20` | class | ChaCha20 stream cipher (RFC 8439). `beginEncrypt()`, `encryptChunk()`. Unauthenticated. |
+| `Poly1305` | class | Poly1305 one-time MAC (RFC 8439). `mac(key, msg)`. |
+
+---
+
+## SHA-2
+
+Requires `init({ sha2: sha2Wasm })` or subpath `sha2Init(source)`.
+Subpath: `leviathan-crypto/sha2`. See [sha2.md](./sha2.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `sha2Init` | function | Module-scoped init. `sha2Init(source: WasmSource)` loads only sha2. |
+| `SHA256` | class | SHA-256 hash (FIPS 180-4). `hash(msg)` returns 32 bytes. |
+| `SHA384` | class | SHA-384 hash (FIPS 180-4). `hash(msg)` returns 48 bytes. |
+| `SHA512` | class | SHA-512 hash (FIPS 180-4). `hash(msg)` returns 64 bytes. |
+| `HMAC_SHA256` | class | HMAC-SHA256 (RFC 2104). `hash(key, msg)` returns 32 bytes. |
+| `HMAC_SHA384` | class | HMAC-SHA384 (RFC 2104). `hash(key, msg)` returns 48 bytes. |
+| `HMAC_SHA512` | class | HMAC-SHA512 (RFC 2104). `hash(key, msg)` returns 64 bytes. |
+| `HKDF_SHA256` | class | HKDF with HMAC-SHA256 (RFC 5869). `derive(ikm, salt, info, length)`. |
+| `HKDF_SHA512` | class | HKDF with HMAC-SHA512 (RFC 5869). `derive(ikm, salt, info, length)`. |
+
+---
+
+## SHA-3
+
+Requires `init({ sha3: sha3Wasm })` or subpath `sha3Init(source)`.
+Subpath: `leviathan-crypto/sha3`. See [sha3.md](./sha3.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `sha3Init` | function | Module-scoped init. `sha3Init(source: WasmSource)` loads only sha3. |
+| `SHA3_224` | class | SHA3-224 hash (FIPS 202). `hash(msg)` returns 28 bytes. |
+| `SHA3_256` | class | SHA3-256 hash (FIPS 202). `hash(msg)` returns 32 bytes. |
+| `SHA3_384` | class | SHA3-384 hash (FIPS 202). `hash(msg)` returns 48 bytes. |
+| `SHA3_512` | class | SHA3-512 hash (FIPS 202). `hash(msg)` returns 64 bytes. |
+| `SHAKE128` | class | SHAKE128 XOF (FIPS 202). Unbounded output. `hash(msg, outputLength)`, `absorb(msg)`, `squeeze(n)`, `reset()`. |
+| `SHAKE256` | class | SHAKE256 XOF (FIPS 202). Unbounded output. `hash(msg, outputLength)`, `absorb(msg)`, `squeeze(n)`, `reset()`. |
+
+---
+
+## Keccak (alias for SHA-3)
+
+`'keccak'` is an alias for `'sha3'`. Same WASM binary, same instance slot.
+Both `init({ sha3: sha3Wasm })` and `init({ keccak: keccakWasm })` load the same module.
+Provided so Kyber/ML-KEM consumers can use the semantically correct primitive name.
+Subpath: `leviathan-crypto/keccak`.
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `keccakInit` | function | Alias init. `keccakInit(source: WasmSource)` loads the sha3 WASM slot via the keccak alias. |
+| `SHA3_224` | class | Re-exported from `leviathan-crypto/sha3`. |
+| `SHA3_256` | class | Re-exported from `leviathan-crypto/sha3`. |
+| `SHA3_384` | class | Re-exported from `leviathan-crypto/sha3`. |
+| `SHA3_512` | class | Re-exported from `leviathan-crypto/sha3`. |
+| `SHAKE128` | class | Re-exported from `leviathan-crypto/sha3`. |
+| `SHAKE256` | class | Re-exported from `leviathan-crypto/sha3`. |
+
+---
+
+## ML-KEM (Post-quantum KEM)
+
+Requires `init({ kyber: kyberWasm, sha3: sha3Wasm })`.
+Subpath: `leviathan-crypto/kyber`. See [kyber.md](./kyber.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `kyberInit` | function | Module-scoped init. `kyberInit(source: WasmSource)` loads only kyber WASM. |
+| `MlKemBase` | class | Abstract base class for all ML-KEM variants. Holds `params: KyberParams`. Not normally instantiated directly. Use `MlKem512`, `MlKem768`, or `MlKem1024`. |
+| `MlKem512` | class | ML-KEM-512. k=2, η₁=3. `keygen()`, `encapsulate(ek)`, `decapsulate(dk, c)`, `checkEncapsulationKey(ek)`, `checkDecapsulationKey(dk)`. |
+| `MlKem768` | class | ML-KEM-768. k=3, η₁=2. Recommended default. Same API as MlKem512. |
+| `MlKem1024` | class | ML-KEM-1024. k=4, η₁=2. Same API as MlKem512. |
+| `KyberSuite` | function | Factory. `KyberSuite(kem, innerCipher)` → `CipherSuite & { keygen(): KyberKeyPair }`. Wraps `MlKemBase` + `CipherSuite` into a hybrid KEM+AEAD suite for use with `Seal`, `SealStream`, `OpenStream`. |
+| `KyberKeyPair` | type | `{ encapsulationKey: Uint8Array, decapsulationKey: Uint8Array }` |
+| `KyberEncapsulation` | type | `{ ciphertext: Uint8Array, sharedSecret: Uint8Array }` |
+| `KyberParams` | type | Parameter set configuration (k, η₁, η₂, dᵤ, dᵥ, byte sizes). |
+| `MLKEM512` | const | Parameter set for ML-KEM-512. |
+| `MLKEM768` | const | Parameter set for ML-KEM-768. |
+| `MLKEM1024` | const | Parameter set for ML-KEM-1024. |
+
+> [!NOTE]
+> `ntt_scalar` and `invntt_scalar` are scalar NTT references exported for SIMD gate tests. They are not part of the public API.
+
+---
+
+## Fortuna CSPRNG
+
+Requires `init({ serpent: serpentWasm, sha2: sha2Wasm })`. See [fortuna.md](./fortuna.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `Fortuna` | class | Fortuna CSPRNG (Ferguson & Schneier). `Fortuna.create()` static factory, `get(n)`, `addEntropy()`, `stop()`. |
+
+---
+
+## Types
+
+No `init()` required. See [types.md](./types.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `Hash` | interface | `hash(msg): Uint8Array`, `dispose()` |
+| `KeyedHash` | interface | `hash(key, msg): Uint8Array`, `dispose()` |
+| `Blockcipher` | interface | `encrypt(block): Uint8Array`, `decrypt(block): Uint8Array`, `dispose()` |
+| `Streamcipher` | interface | `encrypt(msg): Uint8Array`, `decrypt(msg): Uint8Array`, `dispose()` |
+| `AEAD` | interface | `encrypt(msg, aad?): Uint8Array`, `decrypt(ciphertext, aad?): Uint8Array`, `dispose()` |
+
+---
+
+## Utilities
+
+No `init()` required. See [utils.md](./utils.md).
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `hexToBytes` | function | Hex string to `Uint8Array`. Accepts `0x` prefix, uppercase/lowercase. Throws `RangeError` on odd-length input. |
+| `bytesToHex` | function | `Uint8Array` to lowercase hex string. |
+| `utf8ToBytes` | function | UTF-8 string to `Uint8Array`. |
+| `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`. |
+| `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. |
+| `concat` | function | Concatenate one or more `Uint8Array`s into a new array. Variadic. |
+| `randomBytes` | function | Cryptographically secure random bytes via Web Crypto API. |
+| `hasSIMD` | function | Returns `true` if the runtime supports WebAssembly SIMD. Cached after first call. Used internally for CTR/CBC-decrypt and ChaCha20 dispatch. Exported for informational use. |
+
+---
+
+> ## Cross-References
+>
+> - [index](./README.md) — Project Documentation index
+> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline

package/dist/docs/fortuna.md

@@ -1,30 +1,37 @@
-# Fortuna: Cryptographically Secure Pseudorandom Number Generator (CSPRNG)
+# Fortuna CSPRNG
 
 > [!NOTE]
 > A CSPRNG that continuously collects entropy from the environment and generates
 > cryptographically secure random bytes, backed by WASM Serpent-256 and SHA-256.
 
+> ### Table of Contents
+> - [Overview](#overview)
+> - [Security Notes](#security-notes)
+> - [API Reference](#api-reference)
+> - [Usage Examples](#usage-examples)
+> - [Error Conditions](#error-conditions)
+> - [How It Works (Simplified)](#how-it-works-simplified)
+
+---
+
 ## Overview
 
 A cryptographically secure pseudorandom number generator (CSPRNG) produces random
 bytes that are indistinguishable from true randomness to any observer, even one
 with significant computational resources. This matters because many security
-operations -- generating encryption keys, initialization vectors, nonces, tokens
--- require randomness that an attacker cannot predict. If an attacker can predict
+operations require unpredictable randomness: generating encryption keys, initialization vectors, nonces, and tokens. If an attacker can predict
 the output of your random number generator, they can predict your keys, and your
 encryption provides no protection.
 
 Fortuna is a CSPRNG designed by Bruce Schneier and Niels Ferguson, published in
 *Practical Cryptography* (2003). It continuously collects entropy from multiple
-sources -- mouse movements, keyboard events, system timers, OS randomness -- and
+sources (mouse movements, keyboard events, system timers, OS randomness) and
 feeds that entropy into 32 independent pools. When you request random bytes,
 Fortuna combines pool contents and uses them to reseed an internal generator
 built on Serpent-256 (block cipher) and SHA-256 (hash function). Both primitives
 run entirely in WebAssembly.
 
-Why use Fortuna instead of `crypto.getRandomValues()`? The OS random source is
-good, and Fortuna seeds itself from it on creation. But Fortuna adds two
-properties on top. First, **forward secrecy**: after every call to `get()`, the
+Fortuna adds two properties on top of `crypto.getRandomValues()`. First, **forward secrecy**: after every call to `get()`, the
 internal generation key is replaced, so compromising the current state does not
 reveal any past outputs. Second, **defense-in-depth entropy pooling**: Fortuna
 collects entropy from many independent sources and distributes it across 32 pools
@@ -39,41 +46,19 @@ you must use the `Fortuna.create()` static factory rather than `new Fortuna()`.
 
 ## Security Notes
 
-- **Forward secrecy** -- The generation key is replaced after every call to
-  `get()`. If an attacker compromises the internal state at time T, they cannot
-  reconstruct any output produced before time T.
-
-- **32 entropy pools** -- Entropy is distributed across 32 independent pools
-  using round-robin assignment. Pool 0 is used on every reseed, pool 1 on every
-  second reseed, pool 2 on every fourth, and so on. This exponential schedule
-  means that even if an attacker can observe or influence some entropy sources,
-  higher-numbered pools accumulate enough entropy over time to produce a strong
-  reseed eventually.
-
-- **Immediate usability** -- Fortuna seeds itself from `crypto.getRandomValues()`
-  (browser) or `crypto.randomBytes()` (Node.js) during creation, so it is
-  immediately usable. You do not need to wait for entropy to accumulate before
-  calling `get()`.
-
-- **Browser entropy sources** -- mouse movements, keyboard events, click events,
-  scroll position, touch events, device motion and orientation,
-  `performance.now()` timing, DOM content hash, and periodic
-  `crypto.getRandomValues()`.
-
-- **Node.js entropy sources** -- `crypto.randomBytes()`, `process.hrtime` (nanosecond
-  timing jitter), `process.cpuUsage()`, `process.memoryUsage()`, `os.loadavg()`,
-  `os.freemem()`.
-
-- **Wipe state when done** -- Call `stop()` when you are finished with the
-  instance. This wipes the generation key and counter from memory and stops all
-  background entropy collectors. Key material should not persist longer than
-  necessary.
-
-- **Output quality depends on entropy** -- The initial seed from the OS random
-  source is strong. Over time, the additional entropy collectors improve the
-  state further. In environments with limited user interaction (headless servers,
-  automated tests), fewer entropy sources contribute, but the OS random seed
-  still provides a solid baseline.
+**Forward secrecy.** The generation key is replaced after every call to `get()`. If an attacker compromises the internal state at time T, they cannot reconstruct any output produced before time T.
+
+**32 entropy pools.** Entropy is distributed across 32 independent pools using round-robin assignment. Pool 0 is used on every reseed, pool 1 on every second reseed, pool 2 on every fourth, and so on. This exponential schedule means that even if an attacker can observe or influence some entropy sources, higher-numbered pools accumulate enough entropy over time to produce a strong reseed eventually.
+
+**Immediate usability.** Fortuna seeds itself from `crypto.getRandomValues()` (browser) or `crypto.randomBytes()` (Node.js) during creation. You do not need to wait for entropy to accumulate before calling `get()`.
+
+**Browser entropy sources.** Mouse movements, keyboard events, click events, scroll position, touch events, device motion and orientation, `performance.now()` timing, DOM content hash, and periodic `crypto.getRandomValues()`.
+
+**Node.js entropy sources.** `crypto.randomBytes()`, `process.hrtime` (nanosecond timing jitter), `process.cpuUsage()`, `process.memoryUsage()`, `os.loadavg()`, `os.freemem()`.
+
+**Wipe state when done.** Call `stop()` when you are finished with the instance. This wipes the generation key and counter from memory and stops all background entropy collectors. Key material should not persist longer than necessary.
+
+**Output quality depends on entropy.** The initial seed from the OS random source is strong. Over time the additional entropy collectors improve the state further. In environments with limited user interaction (headless servers, automated tests), fewer entropy sources contribute, but the OS random seed still provides a solid baseline.
 
 ---
 
@@ -82,7 +67,7 @@ you must use the `Fortuna.create()` static factory rather than `new Fortuna()`.
 ### `Fortuna.create(opts?)`
 
 Static async factory. Returns a `Promise<Fortuna>`. The returned instance is
-guaranteed to be seeded -- `create()` forces an initial reseed before resolving,
+guaranteed to be seeded. `create()` forces an initial reseed before resolving,
 so `get()` is immediately usable.
 
 ```typescript
@@ -95,12 +80,11 @@ static async create(opts?: {
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `opts.msPerReseed` | `number` | `100` | Minimum milliseconds between reseeds. |
-| `opts.entropy` | `Uint8Array` | -- | Optional extra entropy to mix in during creation. |
+| `opts.entropy` | `Uint8Array` | | Optional extra entropy to mix in during creation. |
 
-Throws if `init(['serpent', 'sha2'])` has not been called.
+Throws if `init({ serpent: serpentWasm, sha2: sha2Wasm })` has not been called.
 
-Direct construction with `new Fortuna()` is not possible -- the constructor is
-private. Always use `Fortuna.create()`.
+Direct construction with `new Fortuna()` is not possible. The constructor is private. Always use `Fortuna.create()`.
 
 ---
 
@@ -116,7 +100,7 @@ Returns a `Uint8Array` of the requested length. The instance is always seeded
 after `create()` resolves, so this method is guaranteed to return data.
 
 After producing the output, the generation key is replaced with fresh
-pseudorandom material. This is the forward secrecy mechanism -- the key used to
+pseudorandom material. This is the forward secrecy mechanism. The key used to
 produce this output no longer exists.
 
 ---
@@ -144,8 +128,7 @@ getEntropy(): number
 ```
 
 Returns the estimated total entropy accumulated across all pools, in bytes. This
-is an estimate, not a guarantee -- it reflects the sum of entropy credits assigned
-by each collector.
+is an estimate, not a guarantee. It reflects the sum of entropy credits assigned by each collector.
 
 ---
 
@@ -180,13 +163,15 @@ There is no `start()` or restart capability.
 
 ## Usage Examples
 
-### Basic usage -- generate random bytes
+### Basic usage
 
 ```typescript
 import { init, Fortuna } from 'leviathan-crypto'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
 // Initialize both WASM modules that Fortuna depends on
-await init(['serpent', 'sha2'])
+await init({ serpent: serpentWasm, sha2: sha2Wasm })
 
 // Create the CSPRNG
 const rng = await Fortuna.create()
@@ -197,7 +182,7 @@ const key = rng.get(32)
 // Generate 12 random bytes (e.g., for a nonce)
 const nonce = rng.get(12)
 
-// Clean up when done -- wipes key material from memory
+// Clean up when done, wipes key material from memory
 rng.stop()
 ```
 
@@ -205,8 +190,10 @@ rng.stop()
 
 ```typescript
 import { init, Fortuna, utf8ToBytes } from 'leviathan-crypto'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['serpent', 'sha2'])
+await init({ serpent: serpentWasm, sha2: sha2Wasm })
 const rng = await Fortuna.create()
 
 // Feed application-specific data as additional entropy.
@@ -227,8 +214,10 @@ rng.stop()
 
 ```typescript
 import { init, Fortuna } from 'leviathan-crypto'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['serpent', 'sha2'])
+await init({ serpent: serpentWasm, sha2: sha2Wasm })
 
 // Fortuna automatically registers browser event listeners on creation:
 // - mousemove (throttled to 50ms)
@@ -239,7 +228,7 @@ await init(['serpent', 'sha2'])
 // - devicemotion, deviceorientation, orientationchange
 //
 // Every user interaction feeds entropy into the pools.
-// No manual setup is needed -- it starts collecting immediately.
+// No manual setup is needed, it starts collecting immediately.
 
 const rng = await Fortuna.create()
 
@@ -259,8 +248,10 @@ window.addEventListener('beforeunload', () => rng.stop())
 
 ```typescript
 import { init, Fortuna } from 'leviathan-crypto'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['serpent', 'sha2'])
+await init({ serpent: serpentWasm, sha2: sha2Wasm })
 
 // You can pass extra entropy at creation time.
 // This is mixed into the pools during initialization, before the
@@ -279,9 +270,9 @@ rng.stop()
 
 | Condition | What happens |
 |-----------|-------------|
-| `init()` not called | `Fortuna.create()` throws: `leviathan-crypto: call init(['serpent', 'sha2']) before using Fortuna` |
-| Only one module initialized | Same error -- both `serpent` and `sha2` must be initialized. |
-| `new Fortuna()` | Compile-time error -- the constructor is private. TypeScript will not allow it. |
+| `init()` not called | `Fortuna.create()` throws: `leviathan-crypto: call init({ serpent: ..., sha2: ... }) before using Fortuna` |
+| Only one module initialized | Same error. Both `serpent` and `sha2` must be initialized. |
+| `new Fortuna()` | Compile-time error. The constructor is private. TypeScript will not allow it. |
 | Any method after `stop()` | Throws: `Fortuna instance has been disposed`. The instance is permanently disposed. |
 
 ---
@@ -291,21 +282,21 @@ rng.stop()
 For readers who want to understand what Fortuna does internally, without needing
 to read the spec:
 
-1. **Entropy collection** -- Background listeners and timers capture small,
+1. **Entropy collection.** Background listeners and timers capture small,
    unpredictable measurements (mouse coordinates, nanosecond timings, memory
    usage) and feed them into 32 separate pools via SHA-256 hash chaining.
 
-2. **Reseed** -- When pool 0 has accumulated enough entropy and enough time has
+2. **Reseed.** When pool 0 has accumulated enough entropy and enough time has
    passed since the last reseed, Fortuna combines the contents of eligible pools
    (determined by the reseed counter) into a seed, and derives a new generation
    key: `genKey = SHA-256(genKey || seed)`.
 
-3. **Generation** -- To produce output, the generator encrypts an incrementing
+3. **Generation.** To produce output, the generator encrypts an incrementing
    counter with Serpent-256 in ECB mode using the current generation key. The
    output is the concatenation of encrypted counter blocks, truncated to the
    requested length.
 
-4. **Key replacement** -- Immediately after producing output, the generation key
+4. **Key replacement.** Immediately after producing output, the generation key
    is replaced with fresh pseudorandom blocks. The old key is gone. This is what
    provides forward secrecy.
 
@@ -315,8 +306,8 @@ to read the spec:
 >
 > - [index](./README.md) — Project Documentation index
 > - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
-> - [serpent](./serpent.md): Serpent-256 TypeScript API (Fortuna uses Serpent ECB internally)
-> - [sha2](./sha2.md): SHA-256 TypeScript API (Fortuna uses SHA-256 for entropy accumulation)
-> - [asm_serpent](./asm_serpent.md): Serpent-256 WASM implementation details
-> - [asm_sha2](./asm_sha2.md): SHA-256 WASM implementation details
-> - [utils](./utils.md): `randomBytes()` for simpler random generation needs
+> - [serpent](./serpent.md) — Serpent-256 TypeScript API (Fortuna uses Serpent ECB internally)
+> - [sha2](./sha2.md) — SHA-256 TypeScript API (Fortuna uses SHA-256 for entropy accumulation)
+> - [asm_serpent](./asm_serpent.md) — Serpent-256 WASM implementation details
+> - [asm_sha2](./asm_sha2.md) — SHA-256 WASM implementation details
+> - [utils](./utils.md) — `randomBytes()` for simpler random generation needs