leviathan-crypto 2.0.1 → 3.0.0

package/dist/docs/exports.md

@@ -1,241 +0,0 @@
-# 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,313 +0,0 @@
-# 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 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
-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.
-
-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
-with exponentially increasing reseed intervals, making it resilient to entropy
-estimation attacks and individual source failures.
-
-Fortuna is the only class in leviathan-crypto that requires two WASM modules.
-You must initialize both `serpent` and `sha2` before creating an instance, and
-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. 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.
-
----
-
-## API Reference
-
-### `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,
-so `get()` is immediately usable.
-
-```typescript
-static async create(opts?: {
-	msPerReseed?: number;
-	entropy?: Uint8Array;
-}): Promise<Fortuna>
-```
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `opts.msPerReseed` | `number` | `100` | Minimum milliseconds between reseeds. |
-| `opts.entropy` | `Uint8Array` | | Optional extra entropy to mix in during creation. |
-
-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()`.
-
----
-
-### `get(length)`
-
-Generate `length` random bytes.
-
-```typescript
-get(length: number): Uint8Array
-```
-
-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
-produce this output no longer exists.
-
----
-
-### `addEntropy(entropy)`
-
-Manually add entropy to the pools.
-
-```typescript
-addEntropy(entropy: Uint8Array): void
-```
-
-Use this to feed application-specific randomness into the generator. The entropy
-is distributed across pools using round-robin assignment. Each call advances to
-the next pool.
-
----
-
-### `getEntropy()`
-
-Get the estimated available entropy in bytes.
-
-```typescript
-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.
-
----
-
-### `stop()`
-
-Permanently dispose this Fortuna instance.
-
-```typescript
-stop(): void
-```
-
-> [!WARNING]
-> Do not attempt to reuse a stopped instance. `stop()` is a permanent dispose
-> operation. If a new Fortuna instance is needed, call `Fortuna.create()`.
-
-Call this when you are done with the Fortuna instance. `stop()`:
-- Removes all browser event listeners
-- Clears all background timers (Node.js stats collection, periodic crypto random)
-- Zeroes the generation key and counter
-- Resets the reseed counter to 0
-- Marks the instance as disposed
-
-All subsequent method calls (`get()`, `addEntropy()`, `getEntropy()`, `stop()`)
-on a disposed instance throw immediately:
-```
-Error: Fortuna instance has been disposed
-```
-
-There is no `start()` or restart capability.
-
----
-
-## Usage Examples
-
-### 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: serpentWasm, sha2: sha2Wasm })
-
-// Create the CSPRNG
-const rng = await Fortuna.create()
-
-// Generate 32 random bytes (e.g., for an encryption key)
-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
-rng.stop()
-```
-
-### Adding custom entropy
-
-```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: serpentWasm, sha2: sha2Wasm })
-const rng = await Fortuna.create()
-
-// Feed application-specific data as additional entropy.
-// This supplements (never replaces) the automatic entropy collection.
-const userData = utf8ToBytes(crypto.randomUUID())
-rng.addEntropy(userData)
-
-// Server-side: feed in request-specific data
-const requestEntropy = new Uint8Array(16)
-crypto.getRandomValues(requestEntropy)
-rng.addEntropy(requestEntropy)
-
-const token = rng.get(32)
-rng.stop()
-```
-
-### Browser with automatic entropy collection
-
-```typescript
-import { init, Fortuna } from 'leviathan-crypto'
-import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
-import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
-
-await init({ serpent: serpentWasm, sha2: sha2Wasm })
-
-// Fortuna automatically registers browser event listeners on creation:
-// - mousemove (throttled to 50ms)
-// - keydown
-// - click
-// - scroll
-// - touchstart, touchmove, touchend
-// - devicemotion, deviceorientation, orientationchange
-//
-// Every user interaction feeds entropy into the pools.
-// No manual setup is needed, it starts collecting immediately.
-
-const rng = await Fortuna.create()
-
-// The longer the user interacts with the page before you generate,
-// the more entropy has been accumulated. But the initial OS seed
-// is strong enough for immediate use.
-document.querySelector('#generate')?.addEventListener('click', () => {
-	const bytes = rng.get(32)
-	console.log('Generated:', bytes)
-})
-
-// When the page unloads or the component unmounts, stop the collectors
-window.addEventListener('beforeunload', () => rng.stop())
-```
-
-### Providing initial entropy at creation
-
-```typescript
-import { init, Fortuna } from 'leviathan-crypto'
-import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
-import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
-
-await init({ serpent: serpentWasm, sha2: sha2Wasm })
-
-// You can pass extra entropy at creation time.
-// This is mixed into the pools during initialization, before the
-// generator is first seeded.
-const extraSeed = new Uint8Array(64)
-crypto.getRandomValues(extraSeed)
-
-const rng = await Fortuna.create({ entropy: extraSeed })
-const bytes = rng.get(32)
-rng.stop()
-```
-
----
-
-## Error Conditions
-
-| 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. |
-| Any method after `stop()` | Throws: `Fortuna instance has been disposed`. The instance is permanently disposed. |
-
----
-
-## How It Works (Simplified)
-
-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,
-   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
-   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
-   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
-   is replaced with fresh pseudorandom blocks. The old key is gone. This is what
-   provides forward secrecy.
-
----
-
-> ## Cross-References
->
-> - [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