leviathan-crypto 1.0.0

package/dist/docs/chacha20_pool.md

@@ -0,0 +1,306 @@
+# XChaCha20Poly1305Pool: Parallel Worker Pool for Authenticated Encryption
+
+> [!NOTE]
+> A worker pool that dispatches independent XChaCha20-Poly1305 AEAD operations
+> across multiple Web Workers, each with its own isolated WebAssembly instance.
+
+## Overview
+
+`XChaCha20Poly1305Pool` parallelizes XChaCha20-Poly1305 encrypt and decrypt
+operations across Web Workers. Each worker owns its own `WebAssembly.Instance`
+with its own linear memory -- there is no shared state between workers.
+
+Use the pool when you need to process many independent AEAD operations
+concurrently. Typical use cases include encrypting multiple independent messages,
+batch processing encrypted records, or any scenario where multiple independent
+encrypt/decrypt operations could benefit from parallelism.
+
+Use the single-instance `XChaCha20Poly1305` when operations are sequential, when
+you only process one message at a time, or when the overhead of worker
+communication is not justified by the operation size.
+
+**Throughput ceiling:** CPU-bound WASM throughput plateaus at
+`navigator.hardwareConcurrency`. Adding more workers beyond this adds scheduling
+overhead with no parallelism gain.
+
+**Per-job size limit:** Each job is limited to 64 KB, the same limit as the
+single-instance path. This is not a workaround limitation -- it is the correct
+security boundary for independent AEAD operations. Each job is one complete,
+independently authenticated AEAD operation. Do not split one logical message
+across multiple pool calls and concatenate results -- this provides no
+stream-level authenticity (reordering and truncation attacks go undetected).
+
+---
+
+## Security Notes
+
+- **Input buffers are transferred (neutered) after dispatch.** Once you call
+  `encrypt()` or `decrypt()`, the `key`, `nonce`, `plaintext`/`ciphertext`, and
+  `aad` buffers are transferred to the worker via `Transferable`. The caller's
+  `Uint8Array` views become detached -- reading them after the call returns
+  zero-length buffers. If you need to retain any input after calling
+  `encrypt()`/`decrypt()`, copy it first with `.slice()`.
+
+- **64 KB limit is per independent AEAD operation.** Do not split one logical
+  message across multiple pool calls and concatenate the results. This creates a
+  stream without authentication -- an attacker can reorder, duplicate, or
+  truncate chunks without detection. A future chunked-AEAD streaming API is the
+  correct tool for large files.
+
+- **All XChaCha20-Poly1305 security properties apply.** Nonce uniqueness per key
+  is required. The 24-byte nonce is safe for random generation via
+  `crypto.getRandomValues()` (collision probability is negligible for 2^64
+  messages).
+
+- **Each worker owns isolated WASM memory.** Key material in one worker's linear
+  memory cannot leak to another worker, even in theory.
+
+- **Workers are terminated on `dispose()`.** All WASM memory is released when
+  the worker process ends. There is no lingering key material.
+
+---
+
+## API Reference
+
+### `PoolOpts`
+
+```typescript
+interface PoolOpts {
+  /** Number of workers. Default: navigator.hardwareConcurrency ?? 4 */
+  workers?: number;
+}
+```
+
+---
+
+### `XChaCha20Poly1305Pool.create(opts?)`
+
+Static async factory. Returns a `Promise<XChaCha20Poly1305Pool>`.
+
+```typescript
+static async create(opts?: PoolOpts): Promise<XChaCha20Poly1305Pool>
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `opts.workers` | `number` | `navigator.hardwareConcurrency ?? 4` | Number of workers to spawn. |
+
+Throws if `init(['chacha20'])` has not been called.
+
+Direct construction with `new XChaCha20Poly1305Pool()` is not possible -- the
+constructor is private.
+
+---
+
+### `encrypt(key, nonce, plaintext, aad?)`
+
+Encrypt plaintext with XChaCha20-Poly1305.
+
+```typescript
+encrypt(
+  key: Uint8Array,       // 32 bytes
+  nonce: Uint8Array,     // 24 bytes
+  plaintext: Uint8Array, // up to 64 KB
+  aad?: Uint8Array,      // optional additional authenticated data
+): Promise<Uint8Array>   // ciphertext || tag (plaintext.length + 16 bytes)
+```
+
+| Parameter | Type | Constraints | Description |
+|-----------|------|-------------|-------------|
+| `key` | `Uint8Array` | 32 bytes | Encryption key |
+| `nonce` | `Uint8Array` | 24 bytes | Unique nonce |
+| `plaintext` | `Uint8Array` | 0--65536 bytes | Data to encrypt |
+| `aad` | `Uint8Array` | any length | Additional authenticated data (default: empty) |
+
+Returns `ciphertext || tag` (`plaintext.length + 16` bytes).
+
+> [!WARNING]
+> All input buffers are transferred and neutered after dispatch.
+
+### `decrypt(key, nonce, ciphertext, aad?)`
+
+Decrypt ciphertext with XChaCha20-Poly1305.
+
+```typescript
+decrypt(
+  key: Uint8Array,        // 32 bytes
+  nonce: Uint8Array,      // 24 bytes
+  ciphertext: Uint8Array, // ciphertext || tag (at least 16 bytes)
+  aad?: Uint8Array,       // must match the AAD used during encryption
+): Promise<Uint8Array>    // plaintext
+```
+
+| Parameter | Type | Constraints | Description |
+|-----------|------|-------------|-------------|
+| `key` | `Uint8Array` | 32 bytes | Decryption key |
+| `nonce` | `Uint8Array` | 24 bytes | Same nonce used for encryption |
+| `ciphertext` | `Uint8Array` | >= 16 bytes | `ciphertext || tag` from `encrypt()` |
+| `aad` | `Uint8Array` | any length | Same AAD used during encryption (default: empty) |
+
+Returns the decrypted plaintext.
+
+Rejects with `Error('ChaCha20Poly1305: authentication failed')` if the tag does
+not match (tampered ciphertext, wrong key, wrong nonce, or wrong AAD).
+
+> [!WARNING]
+> All input buffers are transferred and neutered after dispatch.
+
+### `dispose()`
+
+Terminate all workers and reject all pending and queued jobs.
+
+```typescript
+dispose(): void
+```
+
+After `dispose()`, all calls to `encrypt()` and `decrypt()` reject immediately.
+Calling `dispose()` multiple times is safe (idempotent).
+
+---
+
+### `size`
+
+Number of workers in the pool.
+
+```typescript
+get size(): number
+```
+
+---
+
+### `queueDepth`
+
+Number of jobs currently queued (waiting for a free worker).
+
+```typescript
+get queueDepth(): number
+```
+
+Returns 0 when all workers are idle.
+
+---
+
+## Performance Notes
+
+Throughput plateaus at `navigator.hardwareConcurrency` workers for CPU-bound
+WASM operations. Adding more workers beyond this count introduces scheduling
+overhead without additional parallelism.
+
+The `workers` option lets you tune the count:
+- **Default** (`navigator.hardwareConcurrency ?? 4`) -- optimal for most systems
+- **Fewer workers** -- useful if you need to leave cores available for other work
+- **More workers** -- only beneficial on hyperthreaded CPUs where
+  `hardwareConcurrency` includes virtual cores that provide some additional
+  throughput
+
+Each worker carries a fixed overhead: one `WebAssembly.Instance` (192 KB linear
+memory) plus the worker thread itself. For most workloads, the default is correct.
+
+Job dispatch uses `Transferable` buffers to avoid copy overhead on 64 KB payloads.
+The downside is that input buffers are neutered on the calling side -- see
+Security Notes.
+
+---
+
+## Usage Examples
+
+### Basic -- create pool, encrypt/decrypt one message
+
+```typescript
+import { init, XChaCha20Poly1305Pool, randomBytes } from 'leviathan-crypto'
+
+await init(['chacha20'])
+
+const pool = await XChaCha20Poly1305Pool.create()
+
+const key   = randomBytes(32)
+const nonce = randomBytes(24)
+const plaintext = new TextEncoder().encode('Hello, world!')
+
+// Copy inputs before passing to the pool (they will be neutered)
+const ct = await pool.encrypt(key.slice(), nonce.slice(), plaintext.slice())
+const pt = await pool.decrypt(key.slice(), nonce.slice(), ct)
+console.log(new TextDecoder().decode(pt))  // "Hello, world!"
+
+pool.dispose()
+```
+
+### Concurrent burst -- `Promise.all()` over many independent messages
+
+```typescript
+import { init, XChaCha20Poly1305Pool, randomBytes } from 'leviathan-crypto'
+
+await init(['chacha20'])
+const pool = await XChaCha20Poly1305Pool.create()
+
+const messages = ['message-1', 'message-2', 'message-3', 'message-4']
+const key = randomBytes(32)
+
+// Each message gets its own nonce -- all encrypt concurrently
+const encrypted = await Promise.all(
+  messages.map(msg => {
+    const nonce = randomBytes(24)
+    const pt = new TextEncoder().encode(msg)
+    return pool.encrypt(key.slice(), nonce, pt)
+  })
+)
+
+pool.dispose()
+```
+
+### Manual worker count
+
+```typescript
+const pool = await XChaCha20Poly1305Pool.create({ workers: 4 })
+console.log(pool.size)  // 4
+```
+
+### Correct dispose pattern -- `try/finally`
+
+```typescript
+const pool = await XChaCha20Poly1305Pool.create()
+try {
+  const ct = await pool.encrypt(key, nonce, plaintext)
+  // ... use ct ...
+} finally {
+  pool.dispose()
+}
+```
+
+### What NOT to do -- splitting one message across pool calls
+
+```typescript
+// WRONG -- this is NOT secure
+const chunk1 = await pool.encrypt(key, nonce1, largeFile.subarray(0, 65536))
+const chunk2 = await pool.encrypt(key, nonce2, largeFile.subarray(65536))
+const result = concat(chunk1, chunk2)
+// ^ An attacker can reorder, duplicate, or truncate chunks undetected.
+//   There is no stream-level authentication.
+//   Use a future chunked-AEAD streaming API for large files.
+```
+
+---
+
+## Error Conditions
+
+| Condition | What happens |
+|-----------|-------------|
+| `init()` not called | `create()` throws: `leviathan-crypto: call init(['chacha20']) before using XChaCha20Poly1305Pool` |
+| `new XChaCha20Poly1305Pool()` | Compile-time error -- the constructor is private |
+| Wrong key length | `encrypt()`/`decrypt()` reject with `RangeError` |
+| Wrong nonce length | `encrypt()`/`decrypt()` reject with `RangeError` |
+| Ciphertext shorter than 16 bytes | `decrypt()` rejects with `RangeError` |
+| Authentication failure | `decrypt()` rejects with `Error('ChaCha20Poly1305: authentication failed')` |
+| Pool disposed | `encrypt()`/`decrypt()` reject with `Error('leviathan-crypto: pool is disposed')` |
+| Worker init failure | `create()` rejects with error message from the worker |
+
+---
+
+## Cross-References
+
+- [chacha20.md](./chacha20.md) — single-instance XChaCha20-Poly1305 API
+- [asm_chacha.md](./asm_chacha.md) — WASM implementation details (quarter-round, Poly1305 accumulator, HChaCha20)
+- [wasm.md](./wasm.md) — WebAssembly primer: how one compiled module spawns many worker instances
+- [fortuna.md](./fortuna.md) — another class using the `static async create()` factory pattern
+- [architecture.md](./architecture.md) — library architecture and module relationships
+- [README.md](./README.md) — project overview and getting started

package/dist/docs/fortuna.md

@@ -0,0 +1,322 @@
+# Fortuna: Cryptographically Secure Pseudorandom Number Generator (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.
+
+## 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
+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.
+
+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
+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, 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.
+
+---
+
+## API Reference
+
+### `Fortuna.create(opts?)`
+
+Static async factory. Returns a `Promise<Fortuna>`.
+
+```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', 'sha2'])` 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 | undefined
+```
+
+Returns a `Uint8Array` of the requested length, or `undefined` if the generator
+has not been seeded yet (this should not happen under normal usage, since
+`create()` seeds the generator immediately).
+
+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 -- generate random bytes
+
+```typescript
+import { init, Fortuna } from 'leviathan-crypto'
+
+// Initialize both WASM modules that Fortuna depends on
+await init(['serpent', 'sha2'])
+
+// 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'
+
+await init(['serpent', 'sha2'])
+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'
+
+await init(['serpent', 'sha2'])
+
+// 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'
+
+await init(['serpent', 'sha2'])
+
+// 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. |
+| `get()` before first reseed | Returns `undefined`. Under normal usage this does not happen because `create()` seeds the generator during initialization. |
+| 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
+
+- [README.md](./README.md): Project overview and quick-start guide
+- [architecture.md](./architecture.md): Library architecture and module relationships
+- [serpent.md](./serpent.md): Serpent-256 TypeScript API (Fortuna uses Serpent ECB internally)
+- [sha2.md](./sha2.md): SHA-256 TypeScript API (Fortuna uses SHA-256 for entropy accumulation)
+- [asm_serpent.md](./asm_serpent.md): Serpent-256 WASM implementation details
+- [asm_sha2.md](./asm_sha2.md): SHA-256 WASM implementation details
+- [utils.md](./utils.md): `randomBytes()` for simpler random generation needs