leviathan-crypto 1.3.1 → 2.0.0

package/dist/docs/chacha20.md

@@ -1,7 +1,22 @@
-# ChaCha20, Poly1305, and AEAD TypeScript API
+# ChaCha20 TypeScript API
 
 > [!NOTE]
-> See [ChaCha20-Poly1305 implementation audit](./chacha_audit.md) for algorithm correctness verifications.
+> API reference for `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, and `XChaCha20Cipher`. Covers initialization, all class methods, usage examples, and error conditions.
+
+> ### Table of Contents
+> - [Overview](#overview)
+> - [Security Notes](#security-notes)
+> - [Module Init](#module-init)
+> - [API Reference](#api-reference)
+>   - [`ChaCha20`](#chacha20)
+>   - [`Poly1305`](#poly1305)
+>   - [`ChaCha20Poly1305`](#chacha20poly1305)
+>   - [`XChaCha20Poly1305`](#xchacha20poly1305)
+> - [XChaCha20Cipher](#xchacha20cipher)
+> - [Usage Examples](#usage-examples)
+> - [Error Conditions](#error-conditions)
+
+---
 
 ## Overview
 
@@ -9,37 +24,40 @@
 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.
+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
 tampered with. The critical requirement is that each Poly1305 key is used **exactly
-once** — reusing a key completely breaks its security. You almost never need to use
+once**. Reusing a key completely breaks its security. You almost never need to use
 Poly1305 directly; the AEAD constructions below handle key derivation for you.
 
 **ChaCha20-Poly1305** (RFC 8439) combines both primitives into an AEAD
 (Authenticated Encryption with Associated Data). It encrypts your data and
 produces an authentication tag in a single operation. On decryption, it verifies
-the tag before returning any plaintext — if someone tampered with the ciphertext,
+the tag before returning any plaintext. If someone tampered with the ciphertext,
 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
+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, XChaCha20Poly1305 is the recommended choice.** It gives
-you encryption and authentication in one call, with a nonce size that eliminates
-the most common footgun (accidental nonce reuse).
+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.
+
+---
 
 ## Security Notes
 
 > [!IMPORTANT]
-> Read this section before writing any code. These are not theoretical concerns —
-> they are the mistakes that cause real-world breaches.
+> Read this section before writing any code. These are not theoretical concerns.
+> They are the mistakes that cause real-world breaches.
 
-- **Use `XChaCha20Poly1305` unless you have a specific reason not to.** It is the
-  safest default: authenticated encryption with a nonce large enough for random
-  generation. If you are unsure which class to pick, pick this one.
+- **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.
 
 - **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,
@@ -47,7 +65,7 @@ the most common footgun (accidental nonce reuse).
   With `ChaCha20Poly1305` (12-byte nonce), random generation has a meaningful
   collision risk after roughly 2^32 messages under one key. With
   `XChaCha20Poly1305` (24-byte nonce), random generation is safe for any practical
-  message count — just call `randomBytes(24)` for each message.
+  message count. Just call `randomBytes(24)` for each message.
 
 - **Poly1305 keys are single-use.** Each Poly1305 key must be used to authenticate
   exactly one message. The AEAD classes (`ChaCha20Poly1305` and
@@ -56,13 +74,12 @@ the most common footgun (accidental nonce reuse).
   `Poly1305` class directly, it is your responsibility to never reuse a key.
 
 - **AEAD protects both confidentiality and authenticity.** If authentication fails
-  during decryption, the plaintext is never returned — you get an error. This is
-  intentional. Do not try to work around it. If decryption fails, the ciphertext
-  was corrupted or tampered with.
+  during decryption, the plaintext is never returned. You get an error. This is
+  intentional. Do not try to work around it. If decryption fails, the ciphertext was corrupted or tampered with.
 
 - **Associated data (AAD) is authenticated but not encrypted.** Use AAD for data
   that must travel in the clear (headers, routing metadata, user IDs) but must be
-  verified as unmodified. If someone changes the AAD, decryption will fail — even
+  verified as unmodified. If someone changes the AAD, decryption will fail even
   if the ciphertext itself is untouched.
 
 - **Always call `dispose()` when you are done.** This wipes key material and
@@ -75,29 +92,32 @@ the most common footgun (accidental nonce reuse).
   building your own authenticated construction (and you probably should not be),
   use one of the AEAD classes instead.
 
+---
+
 ## Module Init
 
 Each module subpath exports its own init function for consumers who want
 tree-shakeable imports.
 
-### `chacha20Init(mode?, opts?)`
+### `chacha20Init(source)`
 
 Initializes only the chacha20 WASM binary. Equivalent to calling the
-root `init(['chacha20'], mode, opts)` but without pulling the other three
+root `init({ chacha20: chacha20Wasm })` but without pulling the other three
 modules into the bundle.
 
 **Signature:**
 
 ```typescript
-async function chacha20Init(mode?: Mode, opts?: InitOpts): Promise<void>
+async function chacha20Init(source: WasmSource): Promise<void>
 ```
 
 **Usage:**
 
 ```typescript
 import { chacha20Init, XChaCha20Poly1305 } from 'leviathan-crypto/chacha20'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
 
-await chacha20Init()
+await chacha20Init(chacha20Wasm)
 const aead = new XChaCha20Poly1305()
 ```
 
@@ -105,17 +125,17 @@ const aead = new XChaCha20Poly1305()
 
 ## API Reference
 
-All classes require calling `await init(['chacha20'])` or the subpath `chacha20Init()`
+All classes require calling `await init({ chacha20: chacha20Wasm })` or the subpath `chacha20Init()`
 before construction. If you construct a class before initialization, it throws:
 ```
-Error: leviathan-crypto: call init(['chacha20']) before using this class
+Error: leviathan-crypto: call init({ chacha20: ... }) before using this class
 ```
 
 ---
 
 ### `ChaCha20`
 
-Raw ChaCha20 stream cipher. **No authentication** — use `XChaCha20Poly1305` instead
+Raw ChaCha20 stream cipher. **No authentication.** Use `XChaCha20Poly1305` instead
 unless you are building a custom protocol and understand the risks.
 
 #### Constructor
@@ -124,7 +144,7 @@ unless you are building a custom protocol and understand the risks.
 new ChaCha20()
 ```
 
-Throws if `init(['chacha20'])` has not been called.
+Throws if `init({ chacha20: chacha20Wasm })` has not been called.
 
 ---
 
@@ -156,8 +176,7 @@ 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 |
 |-----------|------|-------------|
@@ -191,7 +210,7 @@ when you are done with the instance.
 ### `Poly1305`
 
 Standalone Poly1305 one-time MAC. **Each key must be used exactly once.** You
-almost certainly want `ChaCha20Poly1305` or `XChaCha20Poly1305` instead — they
+almost certainly want `ChaCha20Poly1305` or `XChaCha20Poly1305` instead. They
 handle Poly1305 key derivation automatically.
 
 #### Constructor
@@ -200,7 +219,7 @@ handle Poly1305 key derivation automatically.
 new Poly1305()
 ```
 
-Throws if `init(['chacha20'])` has not been called.
+Throws if `init({ chacha20: chacha20Wasm })` has not been called.
 
 ---
 
@@ -210,10 +229,10 @@ Computes a 16-byte Poly1305 authentication tag over the given message.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `key` | `Uint8Array` | 32 bytes — must be unique per message |
+| `key` | `Uint8Array` | 32 bytes. Must be unique per message. |
 | `msg` | `Uint8Array` | The message to authenticate (any length) |
 
-**Returns** `Uint8Array` — a 16-byte authentication tag.
+**Returns** `Uint8Array`: a 16-byte authentication tag.
 
 **Throws** `RangeError` if `key` is not 32 bytes.
 
@@ -240,54 +259,59 @@ to avoid collision risk.
 new ChaCha20Poly1305()
 ```
 
-Throws if `init(['chacha20'])` has not been called.
+Throws if `init({ chacha20: chacha20Wasm })` has not been called.
 
 ---
 
-#### `encrypt(key, nonce, plaintext, aad?): { ciphertext: Uint8Array; tag: Uint8Array }`
+#### `encrypt(key, nonce, plaintext, aad?): Uint8Array`
+
+Encrypts plaintext and returns the ciphertext with the 16-byte Poly1305 tag
+appended.
 
-Encrypts plaintext and produces a 16-byte authentication tag.
+> [!WARNING]
+> 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.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `key` | `Uint8Array` | | 32 bytes (256-bit key) |
 | `nonce` | `Uint8Array` | | 12 bytes (96-bit nonce) |
 | `plaintext` | `Uint8Array` | | Data to encrypt (up to the module's chunk size limit) |
-| `aad` | `Uint8Array` | `new Uint8Array(0)` | Associated data — authenticated but not encrypted |
+| `aad` | `Uint8Array` | `new Uint8Array(0)` | Associated data. Authenticated but not encrypted. |
 
-**Returns** `{ ciphertext: Uint8Array; tag: Uint8Array }` — the ciphertext (same
-length as plaintext) and a 16-byte authentication tag. You need both to decrypt.
+**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
+- `Error` if `encrypt()` has already been called on this instance
 
 ---
 
-#### `decrypt(key, nonce, ciphertext, tag, aad?): Uint8Array`
+#### `decrypt(key, nonce, ciphertext, aad?): Uint8Array`
 
-Verifies the authentication tag and decrypts the ciphertext. If authentication
-fails, an error is thrown and no plaintext is returned.
+Verifies the authentication tag and decrypts the ciphertext. The `ciphertext`
+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 |
 |-----------|------|---------|-------------|
 | `key` | `Uint8Array` | | 32 bytes (same key used for encryption) |
 | `nonce` | `Uint8Array` | | 12 bytes (same nonce used for encryption) |
-| `ciphertext` | `Uint8Array` | | Encrypted data |
-| `tag` | `Uint8Array` | | 16-byte authentication tag from `encrypt()` |
+| `ciphertext` | `Uint8Array` | | Encrypted data with appended tag (output of `encrypt()`) |
 | `aad` | `Uint8Array` | `new Uint8Array(0)` | Associated data (must match what was passed to `encrypt()`) |
 
-**Returns** `Uint8Array` — the decrypted plaintext.
+**Returns** `Uint8Array`: the decrypted plaintext.
 
 **Throws:**
 - `RangeError` if `key` is not 32 bytes
 - `RangeError` if `nonce` is not 12 bytes
-- `RangeError` if `tag` is not 16 bytes
-- `RangeError` if `ciphertext` exceeds the maximum chunk size
+- `RangeError` if `ciphertext` is shorter than 16 bytes (no room for a tag)
 - `Error('ChaCha20Poly1305: authentication failed')` if the tag does not match
 
 ---
@@ -300,14 +324,16 @@ Wipes all key material and intermediate state from WASM memory.
 
 ### `XChaCha20Poly1305`
 
-XChaCha20-Poly1305 AEAD (draft-irtf-cfrg-xchacha). **This is the recommended
-authenticated encryption class for most use cases.**
+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).
 
 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
 HChaCha20 and delegates to `ChaCha20Poly1305`.
 
-Unlike `ChaCha20Poly1305`, the `encrypt()` method returns a single `Uint8Array`
+Like `ChaCha20Poly1305`, the `encrypt()` method returns a single `Uint8Array`
 with the tag appended to the ciphertext. The `decrypt()` method expects this
 combined format and splits it internally.
 
@@ -317,7 +343,7 @@ combined format and splits it internally.
 new XChaCha20Poly1305()
 ```
 
-Throws if `init(['chacha20'])` has not been called.
+Throws if `init({ chacha20: chacha20Wasm })` has not been called.
 
 ---
 
@@ -330,9 +356,9 @@ Encrypts plaintext and returns the ciphertext with the 16-byte tag appended.
 | `key` | `Uint8Array` | | 32 bytes (256-bit key) |
 | `nonce` | `Uint8Array` | | 24 bytes (192-bit nonce) |
 | `plaintext` | `Uint8Array` | | Data to encrypt |
-| `aad` | `Uint8Array` | `new Uint8Array(0)` | Associated data — authenticated but not encrypted |
+| `aad` | `Uint8Array` | `new Uint8Array(0)` | Associated data. Authenticated but not encrypted. |
 
-**Returns** `Uint8Array` — ciphertext + 16-byte tag (length = plaintext.length + 16).
+**Returns** `Uint8Array`: ciphertext + 16-byte tag (length = plaintext.length + 16).
 
 **Throws:**
 - `RangeError` if `key` is not 32 bytes
@@ -353,7 +379,7 @@ parameter must include the appended 16-byte tag (i.e., the exact output of
 | `ciphertext` | `Uint8Array` | | Encrypted data with appended tag (output of `encrypt()`) |
 | `aad` | `Uint8Array` | `new Uint8Array(0)` | Associated data (must match what was passed to `encrypt()`) |
 
-**Returns** `Uint8Array` — the decrypted plaintext.
+**Returns** `Uint8Array`: the decrypted plaintext.
 
 **Throws:**
 - `RangeError` if `key` is not 32 bytes
@@ -369,119 +395,159 @@ Wipes all key material and intermediate state from WASM memory.
 
 ---
 
-## Parallel pool — `XChaCha20Poly1305Pool`
+## XChaCha20Cipher
 
-For high-throughput workloads where multiple XChaCha20-Poly1305 operations should
-run concurrently, `XChaCha20Poly1305Pool` dispatches work across a configurable
-number of Web Workers, each holding an isolated `chacha20.wasm` instance in its own
-linear memory. This removes the single-threaded bottleneck of a shared WASM
-instance and allows encryption and decryption operations to proceed in parallel.
-The pool requires `init(['chacha20'])` to be called before construction and is
-created via the static factory `XChaCha20Poly1305Pool.create(opts?)` — see
-[chacha20_pool.md](./chacha20_pool.md) for the full API reference, pool sizing
-guidance, and lifecycle docs.
+`CipherSuite` implementation for XChaCha20-Poly1305. Pass to `Seal`,
+`SealStream`, or `OpenStream`. Never instantiated directly.
 
----
+Requires `init({ chacha20: chacha20Wasm, sha2: sha2Wasm })`.
 
-## Usage Examples
+> [!NOTE]
+> `sha2` is required by the stream layer for HKDF key derivation, not by
+> `XChaCha20Poly1305` itself.
+
+| Property | Value |
+|----------|-------|
+| `formatEnum` | `0x01` |
+| `keySize` | `32` |
+| `tagSize` | `16` (Poly1305) |
+| `padded` | `false` |
+| `wasmModules` | `['chacha20', 'sha2']` |
 
-### Example 1: XChaCha20Poly1305 — Encrypt and Decrypt (Recommended)
+#### `XChaCha20Cipher.keygen(): Uint8Array`
 
-This is the pattern most users should follow. Generate a random 24-byte nonce for
-each message — no counter management, no collision risk.
+Returns `randomBytes(32)`. Convenience method. Not on the `CipherSuite` interface.
+
+#### Usage with `Seal`
 
 ```typescript
-import { init, XChaCha20Poly1305, randomBytes, utf8ToBytes, bytesToUtf8 } from 'leviathan-crypto'
+import { init, Seal, XChaCha20Cipher } from 'leviathan-crypto'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
+import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'
 
-// Step 1: Initialize the chacha20 WASM module (once, at application startup)
-await init(['chacha20'])
+await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })
 
-// Step 2: Generate a 256-bit encryption key
-// In a real application, this comes from a key derivation function or key exchange.
-const key = randomBytes(32)
+const key  = XChaCha20Cipher.keygen()
+const blob = Seal.encrypt(XChaCha20Cipher, key, plaintext)
+const pt   = Seal.decrypt(XChaCha20Cipher, key, blob)   // throws on tamper
+```
 
-// Step 3: Create the AEAD instance
-const aead = new XChaCha20Poly1305()
+#### Usage with `SealStream` / `OpenStream`
 
-// Step 4: Encrypt
-const nonce = randomBytes(24)     // Safe to generate randomly — 24 bytes means no collision risk
-const plaintext = utf8ToBytes('Hello, world!')
-const sealed = aead.encrypt(key, nonce, plaintext)
-// `sealed` contains the ciphertext + 16-byte authentication tag
+```typescript
+import { SealStream, OpenStream } from 'leviathan-crypto/stream'
+import { XChaCha20Cipher } from 'leviathan-crypto/chacha20'
 
-// Step 5: Decrypt
-// You need the same key and nonce to decrypt.
-// Store or transmit the nonce alongside the ciphertext — the nonce is not secret.
-const decrypted = aead.decrypt(key, nonce, sealed)
-console.log(bytesToUtf8(decrypted))  // "Hello, world!"
+const sealer   = new SealStream(XChaCha20Cipher, key)
+const preamble = sealer.preamble        // 20 bytes, send before first chunk
+const ct0      = sealer.push(chunk0)
+const ctLast   = sealer.finalize(lastChunk)
 
-// Step 6: Clean up — wipe key material from WASM memory
-aead.dispose()
+const opener = new OpenStream(XChaCha20Cipher, key, preamble)
+const pt0    = opener.pull(ct0)
+const ptLast = opener.finalize(ctLast)
+```
+
+See [aead.md](./aead.md) for the full `Seal`, `SealStream`, and `OpenStream` API.
+
+---
+
+## Usage Examples
+
+### Example 1: Seal with XChaCha20Cipher (recommended)
+
+One-shot AEAD. No instantiation, no `dispose()`. The blob format is
+`preamble(20) || ciphertext || tag(16)`.
+
+```typescript
+import { init, Seal, XChaCha20Cipher, utf8ToBytes, bytesToUtf8 } from 'leviathan-crypto'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
+import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'
+
+await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })
+
+const key  = XChaCha20Cipher.keygen()
+const blob = Seal.encrypt(XChaCha20Cipher, key, utf8ToBytes('Hello, world!'))
+const pt   = Seal.decrypt(XChaCha20Cipher, key, blob)   // throws on tamper
+
+console.log(bytesToUtf8(pt))  // "Hello, world!"
+
+// Optional: bind metadata without encrypting it (AAD)
+const aad  = utf8ToBytes('document-v2')
+const blob2 = Seal.encrypt(XChaCha20Cipher, key, utf8ToBytes('Hello, world!'), { aad })
+const pt2   = Seal.decrypt(XChaCha20Cipher, key, blob2, { aad })
 ```
 
-### Example 2: ChaCha20Poly1305 — Encrypt and Decrypt
+> For explicit nonce control, use `XChaCha20Poly1305` directly. Same
+> API shape, 24-byte nonce passed per call. See Example 2.
+
+### Example 2: ChaCha20Poly1305
 
 Same idea as above, but with a 12-byte nonce. Use this if you are implementing
 a protocol that specifies RFC 8439 ChaCha20-Poly1305 explicitly.
 
-Note the differences from `XChaCha20Poly1305`:
-- The nonce is 12 bytes, not 24
-- `encrypt()` returns `{ ciphertext, tag }` as separate fields
-- `decrypt()` takes the tag as a separate parameter
+Both `ChaCha20Poly1305` and `XChaCha20Poly1305` return a single `Uint8Array`
+with the tag appended, and `decrypt()` expects the same combined format.
+The only difference is the nonce size (12 vs 24 bytes).
+
+> [!NOTE]
+> Each `ChaCha20Poly1305` instance allows only one `encrypt()` call. A second
+> call throws to prevent accidental nonce reuse. Create a new instance for each
+> encryption.
 
 ```typescript
 import { init, ChaCha20Poly1305, randomBytes, utf8ToBytes, bytesToUtf8 } from 'leviathan-crypto'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
 
-await init(['chacha20'])
+await init({ chacha20: chacha20Wasm })
 
 const key = randomBytes(32)
 const aead = new ChaCha20Poly1305()
 
 // Encrypt
-const nonce = randomBytes(12)     // 12 bytes — be cautious with random generation under high volume
+const nonce = randomBytes(12)     // 12 bytes, use XChaCha20Poly1305 for high-volume random generation
 const plaintext = utf8ToBytes('Sensitive data')
-const { ciphertext, tag } = aead.encrypt(key, nonce, plaintext)
-// You must store/transmit nonce, ciphertext, AND tag — all three are needed to decrypt
+const sealed = aead.encrypt(key, nonce, plaintext)
+// sealed = ciphertext || tag(16), store/transmit nonce and sealed together
 
-// Decrypt
-const decrypted = aead.decrypt(key, nonce, ciphertext, tag)
+// Decrypt (new instance, encrypt is single-use)
+const aead2 = new ChaCha20Poly1305()
+const decrypted = aead2.decrypt(key, nonce, sealed)
 console.log(bytesToUtf8(decrypted))  // "Sensitive data"
 
 aead.dispose()
+aead2.dispose()
 ```
 
 ### Example 3: Detecting Tampered Ciphertext
 
-AEAD decryption fails loudly if anyone has modified the ciphertext, the tag, or
-the associated data. This is a feature — it prevents you from processing corrupted
-or maliciously altered data.
+AEAD decryption fails loudly if anyone has modified the ciphertext or
+the associated data. This is a feature. It prevents you from processing
+corrupted or maliciously altered data.
 
 ```typescript
-import { init, XChaCha20Poly1305, randomBytes, utf8ToBytes } from 'leviathan-crypto'
+import { init, Seal, XChaCha20Cipher, randomBytes, utf8ToBytes } from 'leviathan-crypto'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
+import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'
 
-await init(['chacha20'])
+await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })
 
-const key = randomBytes(32)
-const nonce = randomBytes(24)
-const aead = new XChaCha20Poly1305()
-
-const sealed = aead.encrypt(key, nonce, utf8ToBytes('Original message'))
+const key    = XChaCha20Cipher.keygen()
+const sealed = Seal.encrypt(XChaCha20Cipher, key, utf8ToBytes('Original message'))
 
 // Simulate tampering: flip one bit in the ciphertext
 const tampered = new Uint8Array(sealed)
-tampered[0] ^= 0x01
+tampered[20] ^= 0x01  // byte 20 is the first ciphertext byte (after the 20-byte preamble)
 
 try {
-	const plaintext = aead.decrypt(key, nonce, tampered)
+	const plaintext = Seal.decrypt(XChaCha20Cipher, key, tampered)
 	// This line is never reached
 	console.log(plaintext)
 } catch (err) {
 	console.error(err.message)
 	// "ChaCha20Poly1305: authentication failed"
-	// The plaintext is never returned — decryption stops immediately on failure.
+	// The plaintext is never returned. Decryption stops immediately on failure.
 }
-
-aead.dispose()
 ```
 
 ### Example 4: Using Associated Data (AAD)
@@ -491,72 +557,69 @@ not encrypt. Common uses: user IDs, message sequence numbers, protocol version
 headers, routing information.
 
 ```typescript
-import { init, XChaCha20Poly1305, randomBytes, utf8ToBytes, bytesToUtf8 } from 'leviathan-crypto'
+import { init, Seal, XChaCha20Cipher, randomBytes, utf8ToBytes, bytesToUtf8 } from 'leviathan-crypto'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
+import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'
 
-await init(['chacha20'])
+await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })
 
-const key = randomBytes(32)
-const nonce = randomBytes(24)
-const aead = new XChaCha20Poly1305()
+const key     = XChaCha20Cipher.keygen()
 
 // The user ID travels in the clear, but decryption will fail if anyone changes it
-const userId = utf8ToBytes('user-12345')
+const userId  = utf8ToBytes('user-12345')
 const message = utf8ToBytes('Your account balance is $1,000,000')
 
-const sealed = aead.encrypt(key, nonce, message, userId)
+const sealed = Seal.encrypt(XChaCha20Cipher, key, message, { aad: userId })
 
-// Decrypt — pass the same AAD
-const decrypted = aead.decrypt(key, nonce, sealed, userId)
+// Decrypt, pass the same AAD
+const decrypted = Seal.decrypt(XChaCha20Cipher, key, sealed, { aad: userId })
 console.log(bytesToUtf8(decrypted))
 // "Your account balance is $1,000,000"
 
 // If someone changes the AAD, decryption fails
 const wrongUserId = utf8ToBytes('user-99999')
 try {
-	aead.decrypt(key, nonce, sealed, wrongUserId)
+	Seal.decrypt(XChaCha20Cipher, key, sealed, { aad: wrongUserId })
 } catch (err) {
 	console.error(err.message)
 	// "ChaCha20Poly1305: authentication failed"
 	// Even though the ciphertext was not modified, the AAD mismatch is detected.
 }
-
-aead.dispose()
 ```
 
 ### Example 5: Encrypting and Decrypting Binary Data
 
-The API works with raw bytes — not just text. Here is an example encrypting
+The API works with raw bytes, not just text. Here is an example encrypting
 arbitrary binary content.
 
 ```typescript
-import { init, XChaCha20Poly1305, randomBytes } from 'leviathan-crypto'
+import { init, Seal, XChaCha20Cipher, randomBytes } from 'leviathan-crypto'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
+import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'
 
-await init(['chacha20'])
+await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })
 
-const key = randomBytes(32)
-const nonce = randomBytes(24)
-const aead = new XChaCha20Poly1305()
+const key = XChaCha20Cipher.keygen()
 
 // Encrypt binary data (e.g., an image thumbnail, a protobuf, a file chunk)
 const binaryData = new Uint8Array([0x89, 0x50, 0x4e, 0x47, /* ...more bytes... */])
-const sealed = aead.encrypt(key, nonce, binaryData)
+const sealed = Seal.encrypt(XChaCha20Cipher, key, binaryData)
 
 // Decrypt
-const recovered = aead.decrypt(key, nonce, sealed)
+const recovered = Seal.decrypt(XChaCha20Cipher, key, sealed)
 // `recovered` is byte-identical to `binaryData`
-
-aead.dispose()
 ```
 
 ### Example 6: Raw ChaCha20 Stream Cipher (Advanced)
 
 Use this only if you are building a custom protocol and will add your own
-authentication layer. For almost all use cases, use `XChaCha20Poly1305` instead.
+authentication layer. For almost all use cases, use `Seal` with `XChaCha20Cipher` instead.
 
 ```typescript
 import { init, ChaCha20, randomBytes } from 'leviathan-crypto'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
 
-await init(['chacha20'])
+await init({ chacha20: chacha20Wasm })
 
 const key = randomBytes(32)
 const nonce = randomBytes(12)
@@ -567,7 +630,7 @@ cipher.beginEncrypt(key, nonce)
 const ct1 = cipher.encryptChunk(new Uint8Array([1, 2, 3, 4]))
 const ct2 = cipher.encryptChunk(new Uint8Array([5, 6, 7, 8]))
 
-// Decrypt — uses the same key and nonce
+// Decrypt, uses the same key and nonce
 cipher.beginDecrypt(key, nonce)
 const pt1 = cipher.decryptChunk(ct1)
 const pt2 = cipher.decryptChunk(ct2)
@@ -580,27 +643,32 @@ const pt2 = cipher.decryptChunk(ct2)
 cipher.dispose()
 ```
 
+---
+
 ## Error Conditions
 
 | Condition | Error Type | Message |
 |-----------|-----------|---------|
-| `init(['chacha20'])` not called before constructing a class | `Error` | `leviathan-crypto: call init(['chacha20']) before using this class` |
+| `init({ chacha20: ... })` not called before constructing a class | `Error` | `leviathan-crypto: call init({ chacha20: ... }) before using this class` |
 | Key is not 32 bytes | `RangeError` | `ChaCha20 key must be 32 bytes (got N)` / `key must be 32 bytes (got N)` / `Poly1305 key must be 32 bytes (got N)` |
 | `ChaCha20` nonce is not 12 bytes | `RangeError` | `ChaCha20 nonce must be 12 bytes (got N)` |
 | `ChaCha20Poly1305` nonce is not 12 bytes | `RangeError` | `nonce must be 12 bytes (got N)` |
 | `XChaCha20Poly1305` nonce is not 24 bytes | `RangeError` | `XChaCha20 nonce must be 24 bytes (got N)` |
-| `ChaCha20Poly1305` tag is not 16 bytes | `RangeError` | `tag must be 16 bytes (got N)` |
+| `ChaCha20Poly1305` ciphertext shorter than 16 bytes | `RangeError` | `ciphertext too short — must include 16-byte tag (got N)` |
 | `XChaCha20Poly1305` ciphertext shorter than 16 bytes | `RangeError` | `ciphertext too short — must include 16-byte tag (got N)` |
+| `ChaCha20Poly1305.encrypt()` called a second time | `Error` | Single-use encrypt guard. Create a new instance for each encryption. |
 | 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). |
+| Empty plaintext | | Allowed. Encrypting zero bytes produces just a 16-byte tag (AEAD) or zero bytes (raw ChaCha20). |
 
 > ## 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
-> - [chacha20_pool](./chacha20_pool.md) — `XChaCha20Poly1305Pool` worker-pool wrapper for parallel encryption
-> - [serpent](./serpent.md) — alternative: Serpent block cipher modes (CBC, CTR — unauthenticated, needs HMAC pairing)
-> - [sha2](./sha2.md) — SHA-2 hashes and HMAC — needed for Encrypt-then-MAC if using Serpent or raw ChaCha20
+> - [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
-> - [chacha_audit.md](./chacha_audit.md) — XChaCha20-Poly1305 implementation audit
+> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
+> - [chacha_audit](./chacha_audit.md) — XChaCha20-Poly1305 implementation audit