leviathan-crypto 1.4.0 → 2.0.1

package/dist/docs/serpent.md

@@ -1,24 +1,31 @@
-# Serpent-256 block cipher TypeScript API
+# Serpent-256 TypeScript API
 
 > [!NOTE]
-> Authenticated encryption via `SerpentSeal`, plus low-level block, CTR, and CBC
-> classes for advanced use.
->
 > See [Serpent implementation audit](./serpent_audit.md) for algorithm correctness verifications.
 
+> ### Table of Contents
+> - [Overview](#overview)
+> - [Security Notes](#security-notes)
+> - [Module Init](#module-init)
+> - [API Reference](#api-reference)
+> - [Usage Examples](#usage-examples)
+> - [Error Conditions](#error-conditions)
+
+---
+
 ## Overview
 
-`SerpentSeal` is the primary encryption API for the Serpent module. It provides
-authenticated Serpent-256 encryption in a single call -- no manual IV generation,
-no separate MAC step, no room for misuse. Internally it uses Encrypt-then-MAC
-(SerpentCbc + HMAC-SHA256) and verifies authentication before decryption.
+`SerpentCipher` is the primary API for authenticated Serpent-256 encryption. Pass it
+to `Seal` for one-shot AEAD, or to `SealStream`/`OpenStream` for streaming. There is
+no manual IV generation, no separate MAC step, and no room for misuse. Internally it
+uses Encrypt-then-MAC (Serpent-CBC + HMAC-SHA-256) with HKDF key derivation.
 
 For advanced use cases, three lower-level classes are available: `Serpent` (raw
 16-byte block operations), `SerpentCtr` (counter mode streaming), and `SerpentCbc`
 (cipher block chaining with PKCS7 padding). These are unauthenticated and require
 explicit opt-in.
 
-Serpent was an AES finalist. It uses 32 rounds versus AES's 10--14, yielding a
+Serpent was an AES finalist. It uses 32 rounds versus AES's 10 to 14, yielding a
 larger security margin at comparable speed in WASM.
 
 ---
@@ -33,35 +40,31 @@ larger security margin at comparable speed in WASM.
 
 This is the most dangerous mistake you can make with this module. An attacker who
 can modify ciphertext encrypted with `SerpentCbc` or `SerpentCtr` will produce
-corrupted plaintext on decryption -- and decryption will succeed without any
-indication of tampering. There is no integrity check. The caller receives garbage
-and has no way to distinguish it from the original message.
+corrupted plaintext on decryption. Decryption succeeds without any indication of
+tampering. There is no integrity check. Your caller receives garbage and has no way
+to distinguish it from the original message.
 
-`SerpentSeal` eliminates this problem. It computes an HMAC tag over the ciphertext
-and verifies it before decryption. If anything has been modified, `decrypt()` throws
-instead of returning corrupted data.
+`Seal` with `SerpentCipher` eliminates this problem. It computes an HMAC tag over
+the ciphertext and verifies it before decryption. If anything has been modified,
+`Seal.decrypt()` throws instead of returning corrupted data.
 
-Leviathan also offers a `XChaCha20Poly1305` implementation an alternative that
-provides authenticated encryption with a different cipher. See
-[chacha20.md](./chacha20.md).
+`Seal` with `XChaCha20Cipher` is an alternative using a different cipher.
+See [chacha20.md](./chacha20.md).
 
 ### Never reuse a nonce or IV with the same key
 
-- **CTR mode**: Reusing a nonce with the same key is catastrophic. It produces the
-  same keystream, which means an attacker can XOR two ciphertexts together and
-  recover both plaintexts. Always generate a fresh random nonce for each message.
-- **CBC mode**: The IV (initialization vector) must be random and unpredictable for
-  each encryption. A predictable IV enables chosen-plaintext attacks.
+In CTR mode, reusing a nonce with the same key is catastrophic. It produces the
+same keystream, which means an attacker can XOR two ciphertexts together and
+recover both plaintexts. Always generate a fresh random nonce for each message.
+In CBC mode, the IV must be random and unpredictable for each encryption. A predictable IV enables chosen-plaintext attacks.
 
-Use `randomBytes(16)` to generate nonces and IVs. `SerpentSeal` handles IV
-generation internally.
+Use `randomBytes(16)` to generate nonces and IVs. `Seal` with `SerpentCipher` handles IV generation internally.
 
 ### Always use 256-bit keys
 
 Unless you have a specific reason to use a shorter key, pass a 32-byte key to
 every Serpent operation. Shorter keys provide less security margin and there is no
-meaningful performance benefit to using them. `SerpentSeal` requires a 64-byte key
-(32 bytes encryption + 32 bytes MAC).
+meaningful performance benefit to using them. `SerpentCipher` requires a 32-byte key; HKDF derives enc/mac/iv keys internally.
 
 ### Call dispose() when done
 
@@ -77,24 +80,25 @@ in memory longer than necessary.
 Each module subpath exports its own init function for consumers who want
 tree-shakeable imports.
 
-### `serpentInit(mode?, opts?)`
+### `serpentInit(source)`
 
 Initializes only the serpent WASM binary. Equivalent to calling the
-root `init(['serpent'], mode, opts)` but without pulling the other three
+root `init({ serpent: serpentWasm })` but without pulling the other three
 modules into the bundle.
 
 **Signature:**
 
 ```typescript
-async function serpentInit(mode?: Mode, opts?: InitOpts): Promise<void>
+async function serpentInit(source: WasmSource): Promise<void>
 ```
 
 **Usage:**
 
 ```typescript
 import { serpentInit, Serpent } from 'leviathan-crypto/serpent'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
 
-await serpentInit()
+await serpentInit(serpentWasm)
 const cipher = new Serpent()
 ```
 
@@ -103,73 +107,66 @@ const cipher = new Serpent()
 ## API Reference
 
 All classes require their WASM modules to be initialized before construction.
-`SerpentSeal` requires both `serpent` and `sha2`. All other classes require
-`serpent` only.
+`SerpentCipher` (and therefore `Seal`, `SealStream`, `OpenStream`) requires both
+`serpent` and `sha2`. `Serpent`, `SerpentCtr`, and `SerpentCbc` require `serpent` only.
 
-### SerpentSeal
+### SerpentCipher
 
-Authenticated Serpent-256 encryption. Handles IV generation, HMAC computation,
-and verification internally -- no manual IV or MAC management required.
+`CipherSuite` implementation for Serpent-256 CBC+HMAC-SHA-256. Pass to `Seal`,
+`SealStream`, or `OpenStream`. Never instantiated directly.
 
-```typescript
-class SerpentSeal {
-	constructor()
-	encrypt(key: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array
-	decrypt(key: Uint8Array, data: Uint8Array, aad?: Uint8Array): Uint8Array
-	dispose(): void
-}
-```
-
-#### `constructor()`
-
-Creates a new SerpentSeal instance. Throws if `init(['serpent', 'sha2'])` has not
-been called.
+Requires `init({ serpent: serpentWasm, sha2: sha2Wasm })`.
 
----
+| Property | Value |
+|----------|-------|
+| `formatEnum` | `0x02` |
+| `keySize` | `32` |
+| `tagSize` | `32` (HMAC-SHA-256) |
+| `padded` | `true` (PKCS7) |
+| `wasmModules` | `['serpent', 'sha2']` |
 
-#### `encrypt(key: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array`
+#### `SerpentCipher.keygen(): Uint8Array`
 
-Encrypts plaintext and returns a sealed blob containing the ciphertext and
-authentication data. The output is opaque -- pass it directly to `decrypt()`.
+Returns `randomBytes(32)`. Convenience method. Not on the `CipherSuite` interface.
 
-- **key** -- exactly 64 bytes (32 bytes encryption key + 32 bytes MAC key).
-  Throws `RangeError` if the length is not 64.
-- **plaintext** -- any length.
-- **aad** -- optional associated data. Authenticated but not encrypted. Bound
-  into the HMAC-SHA256 tag. If omitted, equivalent to empty.
+#### Usage with `Seal`
 
-A fresh random IV is generated internally for each call. Two encryptions of the
-same plaintext with the same key produce different output.
+```typescript
+import { init, Seal, SerpentCipher } from 'leviathan-crypto'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded'
 
----
+await init({ serpent: serpentWasm, sha2: sha2Wasm })
 
-#### `decrypt(key: Uint8Array, data: Uint8Array, aad?: Uint8Array): Uint8Array`
+const key  = SerpentCipher.keygen()
+const blob = Seal.encrypt(SerpentCipher, key, plaintext)
+const pt   = Seal.decrypt(SerpentCipher, key, blob)   // throws on tamper
+```
 
-Verifies the authentication tag and decrypts the sealed blob. MAC verification
-happens before decryption -- if the data has been tampered with, `decrypt()` throws
-and never returns corrupted plaintext.
+#### Usage with `SealStream` / `OpenStream`
 
-- **key** -- exactly 64 bytes. Must be the same key used for encryption. Throws
-  `RangeError` if the length is not 64.
-- **data** -- the sealed blob from `encrypt()`. Must be at least 64 bytes. Throws
-  `RangeError` if shorter. Throws `Error` if authentication fails.
-- **aad** -- optional associated data. If `aad` was passed to `encrypt()`, the
-  same value must be passed to `decrypt()`. Mismatch causes authentication failure.
+```typescript
+import { SealStream, OpenStream } from 'leviathan-crypto/stream'
+import { SerpentCipher } from 'leviathan-crypto/serpent'
 
----
+const sealer   = new SealStream(SerpentCipher, key)
+const preamble = sealer.preamble       // 20 bytes, send before first chunk
+const ct0      = sealer.push(chunk0)
+const ctLast   = sealer.finalize(lastChunk)
 
-#### `dispose(): void`
+const opener = new OpenStream(SerpentCipher, key, preamble)
+const pt0    = opener.pull(ct0)
+const ptLast = opener.finalize(ctLast)
+```
 
-Wipes all key material and intermediate state from WASM memory. Delegates to both
-internal SerpentCbc and HMAC_SHA256 instances.
+See [aead.md](./aead.md) for the full `Seal`, `SealStream`, and `OpenStream` API.
 
 ---
 
 ### Serpent
 
 Raw Serpent block encryption and decryption. Operates on exactly 16-byte blocks.
-This class is a low-level building block, most users should use `SerpentSeal`
-instead.
+This class is a low-level building block; use `Seal` with `SerpentCipher` for most purposes.
 
 ```typescript
 class Serpent {
@@ -183,7 +180,7 @@ class Serpent {
 
 #### `constructor()`
 
-Creates a new Serpent instance. Throws if `init(['serpent'])` has not been called.
+Creates a new Serpent instance. Throws if `init({ serpent: serpentWasm })` has not been called.
 
 ---
 
@@ -192,7 +189,7 @@ Creates a new Serpent instance. Throws if `init(['serpent'])` has not been calle
 Loads and expands a key for subsequent block operations. Must be called before
 `encryptBlock()` or `decryptBlock()`.
 
-- **key** -- 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
+- **key**: 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
 
 ---
 
@@ -200,7 +197,7 @@ Loads and expands a key for subsequent block operations. Must be called before
 
 Encrypts a single 16-byte block and returns the 16-byte ciphertext.
 
-- **plaintext** -- exactly 16 bytes. Throws `RangeError` if the length is not 16.
+- **plaintext**: exactly 16 bytes. Throws `RangeError` if the length is not 16.
 
 ---
 
@@ -208,7 +205,7 @@ Encrypts a single 16-byte block and returns the 16-byte ciphertext.
 
 Decrypts a single 16-byte block and returns the 16-byte plaintext.
 
-- **ciphertext** -- exactly 16 bytes. Throws `RangeError` if the length is not 16.
+- **ciphertext**: exactly 16 bytes. Throws `RangeError` if the length is not 16.
 
 ---
 
@@ -226,7 +223,7 @@ stream of chunks.
 
 > [!WARNING]
 > CTR mode is unauthenticated. An attacker can modify ciphertext
-> without detection. Use `SerpentSeal` for authenticated encryption, or pair
+> without detection. Use `Seal` with `SerpentCipher` for authenticated encryption, or pair
 > with HMAC-SHA256 (Encrypt-then-MAC).
 
 ```typescript
@@ -242,11 +239,11 @@ class SerpentCtr {
 
 #### `constructor(opts: { dangerUnauthenticated: true })`
 
-Creates a new SerpentCtr instance. Throws if `init(['serpent'])` has not been
+Creates a new SerpentCtr instance. Throws if `init({ serpent: serpentWasm })` has not been
 called. Throws if `{ dangerUnauthenticated: true }` is not passed:
 
 ```
-leviathan-crypto: SerpentCtr is unauthenticated — use SerpentSeal instead.
+leviathan-crypto: SerpentCtr is unauthenticated — use Seal with SerpentCipher instead.
 To use SerpentCtr directly, pass { dangerUnauthenticated: true }.
 ```
 
@@ -257,8 +254,8 @@ To use SerpentCtr directly, pass { dangerUnauthenticated: true }.
 Initializes the CTR state for encryption. Loads the key, sets the nonce, and
 resets the internal counter to zero.
 
-- **key** -- 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
-- **nonce** -- exactly 16 bytes. Throws `RangeError` if the length is not 16.
+- **key**: 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
+- **nonce**: exactly 16 bytes. Throws `RangeError` if the length is not 16.
 
 ---
 
@@ -268,24 +265,19 @@ Encrypts a chunk of plaintext and returns the same-length ciphertext. Call this
 one or more times after `beginEncrypt()`. The internal counter advances
 automatically.
 
-- **chunk** -- any length up to the module's internal chunk buffer size. Throws
-  `RangeError` if the chunk exceeds the maximum size.
+- **chunk**: any length up to the module's internal chunk buffer size. Throws `RangeError` if the chunk exceeds the maximum size.
 
 > [!NOTE]
-> Automatically dispatches to the 4-wide SIMD path (`encryptChunk_simd`) when
-> the runtime supports WebAssembly SIMD (`hasSIMD()` returns `true`), otherwise
-> falls back to the scalar unrolled path. The dispatch is transparent — no API
-> change required.
+> Automatically dispatches to the 4-wide SIMD path (`encryptChunk_simd`) when the runtime supports WebAssembly SIMD (`hasSIMD()` returns `true`), otherwise falls back to the scalar unrolled path. The dispatch is transparent with no API change required.
 
 ---
 
 #### `beginDecrypt(key: Uint8Array, nonce: Uint8Array): void`
 
-Initializes the CTR state for decryption. Functionally identical to
-`beginEncrypt()` -- CTR mode uses the same operation in both directions.
+Initializes the CTR state for decryption. Functionally identical to `beginEncrypt()`. CTR mode uses the same operation in both directions.
 
-- **key** -- 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
-- **nonce** -- exactly 16 bytes. Throws `RangeError` if the length is not 16.
+- **key**: 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
+- **nonce**: exactly 16 bytes. Throws `RangeError` if the length is not 16.
 
 ---
 
@@ -294,8 +286,7 @@ Initializes the CTR state for decryption. Functionally identical to
 Decrypts a chunk of ciphertext and returns the same-length plaintext.
 Functionally identical to `encryptChunk()`.
 
-- **chunk** -- any length up to the module's internal chunk buffer size. Throws
-  `RangeError` if the chunk exceeds the maximum size.
+- **chunk**: any length up to the module's internal chunk buffer size. Throws `RangeError` if the chunk exceeds the maximum size.
 
 ---
 
@@ -312,7 +303,7 @@ Encrypts and decrypts entire messages in a single call.
 
 > [!WARNING]
 > CBC mode is unauthenticated. Always authenticate the output with
-> HMAC-SHA256 (Encrypt-then-MAC) or use `SerpentSeal` instead.
+> HMAC-SHA256 (Encrypt-then-MAC) or use `Seal` with `SerpentCipher` instead.
 
 ```typescript
 class SerpentCbc {
@@ -325,11 +316,11 @@ class SerpentCbc {
 
 #### `constructor(opts: { dangerUnauthenticated: true })`
 
-Creates a new SerpentCbc instance. Throws if `init(['serpent'])` has not been
+Creates a new SerpentCbc instance. Throws if `init({ serpent: serpentWasm })` has not been
 called. Throws if `{ dangerUnauthenticated: true }` is not passed:
 
 ```
-leviathan-crypto: SerpentCbc is unauthenticated — use SerpentSeal instead.
+leviathan-crypto: SerpentCbc is unauthenticated — use Seal with SerpentCipher instead.
 To use SerpentCbc directly, pass { dangerUnauthenticated: true }.
 ```
 
@@ -341,11 +332,9 @@ Encrypts plaintext with Serpent CBC and PKCS7 padding. The returned ciphertext i
 always a multiple of 16 bytes and is at least 16 bytes longer than the input (due
 to padding).
 
-- **key** -- 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
-- **iv** -- exactly 16 bytes. Must be random and unique for each (key, message)
-  pair. Throws `RangeError` if the length is not 16.
-- **plaintext** -- any length (including zero). PKCS7 padding is applied
-  automatically.
+- **key**: 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
+- **iv**: exactly 16 bytes. Must be random and unique per (key, message) pair. Throws `RangeError` if the length is not 16.
+- **plaintext**: any length including zero. PKCS7 padding is applied automatically.
 
 Returns the ciphertext as a new `Uint8Array`.
 
@@ -355,21 +344,14 @@ Returns the ciphertext as a new `Uint8Array`.
 
 Decrypts Serpent CBC ciphertext and strips PKCS7 padding.
 
-- **key** -- 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
-- **iv** -- exactly 16 bytes. Must be the same IV that was used for encryption.
-  Throws `RangeError` if the length is not 16.
-- **ciphertext** -- must be a non-zero multiple of 16 bytes. Throws `RangeError`
-  if the length is zero or not a multiple of 16. Also throws `RangeError` if PKCS7
-  padding is invalid (which typically indicates the wrong key, wrong IV, or
-  corrupted ciphertext).
+- **key**: 16, 24, or 32 bytes. Throws `RangeError` if the length is invalid.
+- **iv**: exactly 16 bytes. Must match the IV used for encryption. Throws `RangeError` if the length is not 16.
+- **ciphertext**: must be a non-zero multiple of 16 bytes. Throws `RangeError` if the length is zero or not a multiple of 16. Also throws if PKCS7 padding is invalid, which typically indicates the wrong key, wrong IV, or corrupted ciphertext.
 
 Returns the decrypted plaintext as a new `Uint8Array`.
 
 > [!NOTE]
-> Automatically dispatches to the 4-wide SIMD path (`cbcDecryptChunk_simd`) when
-> the runtime supports WebAssembly SIMD (`hasSIMD()` returns `true`), otherwise
-> falls back to the scalar unrolled path. CBC encryption has no SIMD variant —
-> each ciphertext block depends on the previous one.
+> Automatically dispatches to the 4-wide SIMD path (`cbcDecryptChunk_simd`) when the runtime supports WebAssembly SIMD (`hasSIMD()` returns `true`), otherwise falls back to the scalar unrolled path. CBC encryption has no SIMD variant since each ciphertext block depends on the previous one.
 
 ---
 
@@ -379,357 +361,40 @@ Wipes all key material and intermediate state from WASM memory.
 
 ---
 
-### SerpentStream
-
-Chunked authenticated encryption for large payloads. Each chunk is independently
-encrypted with Serpent-CTR and authenticated with HMAC-SHA256 using per-chunk
-keys derived via HKDF-SHA256. Position binding and truncation detection are
-enforced at the key-derivation layer.
-
-Use `SerpentStream` when the payload is large or when holding the entire
-plaintext in memory is undesirable. For small/medium payloads where a single
-`encrypt()`/`decrypt()` call is sufficient, use `SerpentSeal` instead.
-
-> [!NOTE]
-> `SerpentStream` takes a 32-byte key (HKDF handles expansion internally).
-> This differs from `SerpentSeal`, which takes 64 bytes.
-
-```typescript
-class SerpentStream {
-	constructor()
-	seal(key: Uint8Array, plaintext: Uint8Array, chunkSize?: number): Uint8Array
-	open(key: Uint8Array, ciphertext: Uint8Array): Uint8Array
-	dispose(): void
-}
-```
-
-#### `constructor()`
-
-Creates a new SerpentStream instance. Throws if `init(['serpent', 'sha2'])` has
-not been called.
-
----
-
-#### `seal(key: Uint8Array, plaintext: Uint8Array, chunkSize?: number): Uint8Array`
-
-Encrypts plaintext into a chunked authenticated wire format.
-
-- **key** -- exactly 32 bytes. Throws `RangeError` if not.
-- **plaintext** -- any length (including zero).
-- **chunkSize** -- optional, default 64KB. Valid range: 1KB to 64KB. Throws
-  `RangeError` if outside range.
-
-A fresh random stream nonce is generated internally for each call. Two seals of
-the same plaintext with the same key produce different output.
-
-Wire format: `stream_nonce (16) || chunk_size (4, u32_be) || chunk_count (8, u64_be) || chunk_0 || ... || chunk_N-1`
-
-Each chunk on the wire: `ciphertext || hmac_tag (32 bytes)`.
-
----
-
-#### `open(key: Uint8Array, ciphertext: Uint8Array): Uint8Array`
-
-Verifies authentication and decrypts the chunked wire format. Each chunk's MAC
-is verified before decryption (Encrypt-then-MAC). If any chunk fails
-authentication, `open()` throws immediately and never returns partial plaintext.
-
-- **key** -- exactly 32 bytes. Must be the same key used for `seal()`.
-- **ciphertext** -- the wire format from `seal()`. Throws `RangeError` if too
-  short.
-
----
-
-#### `dispose(): void`
-
-Wipes all key material and intermediate state from WASM memory. Delegates to
-internal SerpentCtr, HMAC_SHA256, and HKDF_SHA256 instances.
-
-**Security properties:**
-
-- **Per-chunk EtM** -- HMAC-SHA256 over ciphertext, verified before decrypt.
-- **Position binding** -- chunk index encoded in HKDF `info`. Reordering chunks
-  produces wrong keys; MAC fails.
-- **Truncation detection** -- final chunk derives different keys than any
-  intermediate chunk at the same index.
-- **Implicit header integrity** -- HKDF `info` embeds the full header. Tampering
-  with any header field invalidates every chunk's MAC.
-- **Domain separation** -- `"serpent-stream-v1"` prefix prevents key confusion
-  with SerpentSeal or other constructions.
-
-> [!IMPORTANT]
-> This is a bespoke construction (no external RFC). The compositional security
-> argument rests on HKDF (RFC 5869), HMAC-EtM, and Serpent-CTR. See
-> [sha2.md](./sha2.md) for HKDF details.
-
-> [!NOTE]
-> `sealChunk` and `openChunk` are exported from the serpent submodule for
-> internal use by the pool worker. They are not public API -- callers should use
-> `SerpentStream` or `SerpentStreamPool`.
-
----
-
-### SerpentStreamPool
-
-Parallel worker pool for `SerpentStream`. Same wire format, same security
-properties, faster on multi-core hardware for large payloads. Each worker owns
-its own `serpent.wasm` and `sha2.wasm` instances with isolated linear memory.
-
-`SerpentStream.seal()` and `SerpentStreamPool.seal()` produce compatible wire
-formats -- either can decrypt the other's output.
-
-```typescript
-class SerpentStreamPool {
-	static async create(opts?: StreamPoolOpts): Promise<SerpentStreamPool>
-	seal(key: Uint8Array, plaintext: Uint8Array, chunkSize?: number): Promise<Uint8Array>
-	open(key: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>
-	dispose(): void
-	get size(): number
-	get queueDepth(): number
-}
-```
-
-#### `static async create(opts?: StreamPoolOpts): Promise<SerpentStreamPool>`
-
-Creates a new pool. Requires `init(['serpent', 'sha2'])` to have been called.
-Compiles both WASM modules once and distributes them to all workers.
-
-- **opts.workers** -- number of workers to spawn. Default:
-  `navigator.hardwareConcurrency ?? 4`.
-
-Uses a static factory pattern because worker initialization is async (WASM
-compilation and instantiation happen per worker).
-
----
-
-#### `seal(key, plaintext, chunkSize?)`
-
-Same parameters as `SerpentStream.seal()`, but returns a `Promise`. Key
-derivation happens on the main thread; chunk encryption is parallelised across
-workers.
-
----
-
-#### `open(key, ciphertext)`
-
-Same parameters as `SerpentStream.open()`, but returns a `Promise`. If any chunk
-fails authentication, the promise rejects immediately -- no partial plaintext is
-returned.
-
----
-
-#### `dispose()`
-
-Terminates all workers. Rejects all pending and queued jobs. Must be called to
-release worker resources when the pool is no longer needed.
-
----
-
-### SerpentStreamSealer / SerpentStreamOpener
-
-Incremental streaming AEAD — seal and open one chunk at a time without holding
-the full message in memory. Unlike `SerpentStream` (which is one-shot),
-`SerpentStreamSealer` produces chunks as data arrives and `SerpentStreamOpener`
-authenticates and decrypts them individually.
-
-**Wire format (v1.4.0+):**
-```
-header:  nonce (16) || chunkSize_u32be (4)                          = 20 bytes
-chunk:   isLast (1) || IV (16) || CBC_ciphertext (PKCS7-padded) || HMAC-SHA256 (32)
-```
-
-> [!WARNING]
-> **Breaking change from v1.3.x:** Each chunk now prepends an explicit `isLast`
-> flag byte, and AAD is folded into the HMAC input with a 4-byte length prefix.
-> Ciphertexts produced by v1.3.x are not compatible with v1.4.0 openers, and
-> vice versa, even with empty AAD.
-
-Per-chunk keys are derived via HKDF-SHA256 from the stream key and a `chunkInfo`
-blob binding the stream nonce, chunk size, chunk index, and `isLast` flag. Each
-chunk is independently authenticated and position-bound — reordering, truncation,
-and cross-stream splicing are all detected.
-
-> [!NOTE]
-> `SerpentStreamSealer` requires a 64-byte key (same as `SerpentSeal`). HKDF
-> derives a fresh `encKey` + `macKey` pair for every chunk.
-
-> [!IMPORTANT]
-> The sealer produces a 20-byte header that **must** be transmitted to the opener
-> before any chunks. The opener is initialized with this header.
-
-```typescript
-class SerpentStreamSealer {
-	constructor(key: Uint8Array, chunkSize?: number, opts?: {
-		framed?: boolean;
-		aad?: Uint8Array;   // authenticated per-chunk, not encrypted
-	})
-	header(): Uint8Array        // call once before seal() — returns 20 bytes
-	seal(plaintext: Uint8Array): Uint8Array   // exactly chunkSize bytes
-	final(plaintext: Uint8Array): Uint8Array  // <= chunkSize bytes; wipes on return
-	dispose(): void             // abort mid-stream; wipes without final chunk
-}
-
-class SerpentStreamOpener {
-	constructor(key: Uint8Array, header: Uint8Array, opts?: {
-		framed?: boolean;
-		aad?: Uint8Array;   // must match value used by sealer
-	})
-	open(chunk: Uint8Array): Uint8Array  // throws on auth failure or post-final
-	feed(bytes: Uint8Array): Uint8Array[]  // framed mode only — accumulates and parses frames
-	dispose(): void
-}
-```
-
-#### Sealer state machine
-
-| State | Valid calls |
-|---|---|
-| `fresh` | `header()`, `dispose()` |
-| `sealing` | `seal()`, `final()`, `dispose()` |
-| `dead` | `dispose()` (no-op) |
-
-`header()` transitions `fresh → sealing`. `final()` seals the last chunk, wipes
-all key material, and transitions to `dead`. `dispose()` wipes and transitions to
-`dead` from any state — use it to abort a stream before `final()` is called.
-
-Calling `header()` twice, `seal()` before `header()`, or any method after `final()`
-all throw immediately.
-
----
-
-#### Opener state machine
-
-The opener is ready as soon as it is constructed. It calls `open()` for each
-chunk in order. Once a chunk with `isLast` set passes authentication, the opener
-wipes its key material and transitions to `dead`. Subsequent `open()` calls throw.
-
-`dispose()` wipes and marks the instance dead from any state.
-
----
-
-#### `constructor(key, chunkSize?, opts?)`
-
-- **key** — 64-byte key. Throws `RangeError` if wrong length.
-- **chunkSize** — bytes per chunk. Must be 1024–65536. Default: 65536. Throws
-  `RangeError` if out of range.
-
-##### Options (`opts`)
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `framed` | `boolean` | `false` | Prepend `u32be(sealedLen)` to each `seal()`/`final()` output. Use for flat byte streams (files, pipes, TCP). Omit when the transport already frames messages (WebSocket, IPC). |
-| `aad` | `Uint8Array` | `undefined` | Associated data — authenticated but not encrypted. Bound into each chunk's HMAC-SHA256 tag with a 4-byte length prefix for domain separation. If omitted, equivalent to empty. |
-
----
-
-#### `header()`
-
-Returns the 20-byte stream header (`nonce || u32be(chunkSize)`). Must be called
-once before the first `seal()`. Throws if called a second time or after `final()`.
-
----
-
-#### `seal(plaintext)`
-
-Seals one chunk. **Plaintext must be exactly `chunkSize` bytes.** Returns
-`IV (16) || ciphertext || HMAC (32)`. Throws `RangeError` if wrong size. Throws
-if called before `header()` or after `final()`.
-
----
-
-#### `final(plaintext)`
-
-Seals the last chunk. Plaintext may be 0–`chunkSize` bytes (partial chunk is
-valid). After producing output, wipes all key material and marks the sealer dead.
-Throws `RangeError` if plaintext exceeds `chunkSize`.
-
----
-
-#### `dispose()` (sealer)
-
-Aborts the stream. Wipes key material without producing a final chunk. The opener
-will see an incomplete stream and throw when it detects a missing final chunk.
-Safe to call after `final()` — no-op if already dead.
-
----
-
-#### `constructor(key, header, opts?)` (opener)
-
-- **key** — 64-byte key. Throws `RangeError` if wrong length.
-- **header** — 20-byte stream header from `sealer.header()`. Throws `RangeError`
-  if wrong length.
-
-##### Options (`opts`)
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `framed` | `boolean` | `false` | Enable byte-accumulation mode. Parses `u32be` length prefixes and dispatches complete frames to `open()` internally. Required to use `feed()`. |
-| `aad` | `Uint8Array` | `undefined` | Associated data — must match the value used by the sealer. Mismatch causes authentication failure on `open()`. |
-
----
-
-#### `open(chunk)`
-
-Authenticates and decrypts one chunk. Throws `Error` on authentication failure.
-Throws `Error` if called after the final chunk has already been opened. Returns
-plaintext bytes (PKCS7 padding stripped).
-
----
-
-#### `feed(bytes: Uint8Array): Uint8Array[]`
-
-Only callable when constructed with `{ framed: true }`. Accumulates incoming bytes,
-parses `u32be` length prefixes, dispatches complete frames to `open()` internally.
-Returns an array of decrypted chunks — zero, one, or more per call depending on how
-many complete frames were buffered. Throws if called on an unframed opener.
-
----
-
-#### `dispose()` (opener)
-
-Wipes key material. Safe to call at any point — use to abort opening a stream
-early.
-
----
-
 ## Usage Examples
 
-### Example 1: SerpentSeal (authenticated encryption)
+### Example 1: Seal with SerpentCipher (authenticated encryption)
 
 ```typescript
-import { init, SerpentSeal, randomBytes } from 'leviathan-crypto';
-
-await init(['serpent', 'sha2']);
+import { init, Seal, SerpentCipher } from 'leviathan-crypto'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded'
 
-// 64-byte key: 32 bytes encryption + 32 bytes MAC
-const key = randomBytes(64);
+await init({ serpent: serpentWasm, sha2: sha2Wasm })
 
-const seal = new SerpentSeal();
+const key       = SerpentCipher.keygen()
+const plaintext = new TextEncoder().encode('Authenticated secret message.')
+const blob      = Seal.encrypt(SerpentCipher, key, plaintext)
+const decrypted = Seal.decrypt(SerpentCipher, key, blob)
 
-const plaintext  = new TextEncoder().encode('Authenticated secret message.');
-const ciphertext = seal.encrypt(key, plaintext);
-const decrypted  = seal.decrypt(key, ciphertext);
-
-console.log(new TextDecoder().decode(decrypted));
+console.log(new TextDecoder().decode(decrypted))
 // "Authenticated secret message."
-
-seal.dispose();
 ```
 
 ### Example 2: CTR mode (advanced)
 
-Advanced use. For authenticated encryption, use `SerpentSeal`.
-
-Use `SerpentCtr` to encrypt data of any length. CTR mode produces ciphertext
-that is the same length as the plaintext -- no padding overhead.
+For authenticated encryption, use `Seal` with `SerpentCipher`. Use `SerpentCtr` to
+encrypt data of any length. CTR mode produces ciphertext the same length as the
+plaintext with no padding overhead.
 
 ```typescript
 import { init, SerpentCtr, randomBytes } from 'leviathan-crypto';
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded';
 
-await init(['serpent']);
+await init({ serpent: serpentWasm });
 
 const key   = randomBytes(32); // 256-bit key
-const nonce = randomBytes(16); // 16-byte nonce -- NEVER reuse with the same key
+const nonce = randomBytes(16); // 16-byte nonce, NEVER reuse with the same key
 
 const ctr = new SerpentCtr({ dangerUnauthenticated: true });
 
@@ -752,21 +417,21 @@ ctr.dispose();
 
 > [!IMPORTANT]
 > CTR mode is unauthenticated. An attacker can tamper with the
-> ciphertext without detection. Use `SerpentSeal` for authenticated encryption.
+> ciphertext without detection. Use `Seal` with `SerpentCipher` for authenticated encryption.
 
 ### Example 3: CBC mode (advanced)
 
-Advanced use. For authenticated encryption, use `SerpentSeal`.
-
-Use `SerpentCbc` for message-level encryption with automatic PKCS7 padding.
+For authenticated encryption, use `Seal` with `SerpentCipher`. Use `SerpentCbc` for
+message-level encryption with automatic PKCS7 padding.
 
 ```typescript
 import { init, SerpentCbc, randomBytes } from 'leviathan-crypto';
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded';
 
-await init(['serpent']);
+await init({ serpent: serpentWasm });
 
 const key = randomBytes(32); // 256-bit key
-const iv  = randomBytes(16); // Random IV -- must be unique per message
+const iv  = randomBytes(16); // Random IV, must be unique per message
 
 const cbc = new SerpentCbc({ dangerUnauthenticated: true });
 
@@ -783,109 +448,18 @@ cbc.dispose();
 ```
 
 > [!IMPORTANT]
-> CBC mode is unauthenticated. Use `SerpentSeal` for authenticated encryption.
-
-### Example 4: SerpentStream (chunked authenticated encryption)
-
-Use `SerpentStream` for large payloads where holding the entire plaintext in
-memory is undesirable.
-
-```typescript
-import { init, SerpentStream, randomBytes } from 'leviathan-crypto';
-
-await init(['serpent', 'sha2']);
+> CBC mode is unauthenticated. Use `Seal` with `SerpentCipher` for authenticated encryption.
 
-const key = randomBytes(32); // 32-byte key (HKDF handles expansion)
+### Example 4: Raw block operations (low-level)
 
-const stream = new SerpentStream();
-
-const plaintext  = new Uint8Array(1024 * 1024); // 1 MB
-crypto.getRandomValues(plaintext);
-
-const ciphertext = stream.seal(key, plaintext);       // default 64KB chunks
-const decrypted  = stream.open(key, ciphertext);
-
-// decrypted is byte-identical to plaintext
-
-stream.dispose();
-```
-
-### Example 5: SerpentStreamPool (parallel chunked encryption)
-
-Use `SerpentStreamPool` for maximum throughput on multi-core hardware.
-
-```typescript
-import { init, SerpentStreamPool, randomBytes } from 'leviathan-crypto';
-
-await init(['serpent', 'sha2']);
-
-const pool = await SerpentStreamPool.create({ workers: 4 });
-
-const key       = randomBytes(32);
-const plaintext = new Uint8Array(10 * 1024 * 1024); // 10 MB
-
-const ciphertext = await pool.seal(key, plaintext);
-const decrypted  = await pool.open(key, ciphertext);
-
-// decrypted is byte-identical to plaintext
-
-pool.dispose(); // terminates workers
-```
-
-### Example 6: SerpentStreamSealer / SerpentStreamOpener (incremental streaming)
-
-Use `SerpentStreamSealer` when data arrives in chunks and you cannot buffer the
-entire plaintext before encrypting — network streams, file processors, live feeds.
-
-```typescript
-import { init, SerpentStreamSealer, SerpentStreamOpener, randomBytes } from 'leviathan-crypto';
-
-await init(['serpent', 'sha2']);
-
-const key       = randomBytes(64);  // 64-byte key
-const chunkSize = 65536;            // 64 KB chunks
-
-// ── Seal side ────────────────────────────────────────────────────────────────
-
-const sealer = new SerpentStreamSealer(key, chunkSize);
-const header = sealer.header();  // transmit this to the opener first
-
-// seal() as data arrives — each chunk must be exactly chunkSize bytes
-const chunk0 = sealer.seal(plaintext0);
-const chunk1 = sealer.seal(plaintext1);
-
-// final() for the last chunk — may be shorter than chunkSize
-const lastChunk = sealer.final(lastPlaintext);
-// sealer is now dead — key material wiped
-
-// ── Open side ────────────────────────────────────────────────────────────────
-
-const opener = new SerpentStreamOpener(key, header);
-
-const pt0  = opener.open(chunk0);
-const pt1  = opener.open(chunk1);
-const ptN  = opener.open(lastChunk);  // opener detects isLast, wipes on return
-// opener is now dead
-
-// Truncation and reordering are detected — open() throws on auth failure
-```
-
-To abort a stream mid-way (e.g. on connection drop):
-
-```typescript
-sealer.dispose();  // wipes key material without producing a final chunk
-// opener will throw when it receives no more chunks
-```
-
-### Example 7: Raw block operations (low-level)
-
-Use the `Serpent` class for single 16-byte block operations. This is the lowest
-level API, most users should use `SerpentSeal` instead.
+Use the `Serpent` class for single 16-byte block operations. This is the lowest-level
+API; use `Seal` with `SerpentCipher` for most purposes.
 
 ```typescript
 import { init, Serpent } from 'leviathan-crypto';
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded';
 
-await init(['serpent']);
+await init({ serpent: serpentWasm });
 
 const cipher = new Serpent();
 
@@ -915,13 +489,9 @@ cipher.dispose();
 
 | Condition | Error type | Message |
 |-----------|-----------|---------|
-| `SerpentSeal` constructed before `init(['serpent', 'sha2'])` | `Error` | `leviathan-crypto: call init(['serpent', 'sha2']) before using SerpentSeal` |
-| `SerpentSeal` key is not 64 bytes | `RangeError` | `SerpentSeal key must be 64 bytes (got N)` |
-| `SerpentSeal` data too short for decrypt | `RangeError` | `SerpentSeal ciphertext too short` |
-| `SerpentSeal` authentication failed | `Error` | `SerpentSeal: authentication failed` |
-| `init(['serpent'])` not called before constructing `Serpent` | `Error` | `leviathan-crypto: call init(['serpent']) before using this class` |
-| `SerpentCbc` constructed without `{ dangerUnauthenticated: true }` | `Error` | `leviathan-crypto: SerpentCbc is unauthenticated — use SerpentSeal instead. To use SerpentCbc directly, pass { dangerUnauthenticated: true }.` |
-| `SerpentCtr` constructed without `{ dangerUnauthenticated: true }` | `Error` | `leviathan-crypto: SerpentCtr is unauthenticated — use SerpentSeal instead. To use SerpentCtr directly, pass { dangerUnauthenticated: true }.` |
+| `init({ serpent: ... })` not called before constructing `Serpent` | `Error` | `leviathan-crypto: call init({ serpent: ... }) before using this class` |
+| `SerpentCbc` constructed without `{ dangerUnauthenticated: true }` | `Error` | `leviathan-crypto: SerpentCbc is unauthenticated — use Seal with SerpentCipher instead. To use SerpentCbc directly, pass { dangerUnauthenticated: true }.` |
+| `SerpentCtr` constructed without `{ dangerUnauthenticated: true }` | `Error` | `leviathan-crypto: SerpentCtr is unauthenticated — use Seal with SerpentCipher instead. To use SerpentCtr directly, pass { dangerUnauthenticated: true }.` |
 | Key is not 16, 24, or 32 bytes (`Serpent.loadKey`) | `RangeError` | `key must be 16, 24, or 32 bytes (got N)` |
 | Key is not 16, 24, or 32 bytes (`SerpentCbc`) | `RangeError` | `Serpent key must be 16, 24, or 32 bytes (got N)` |
 | Key is not 16, 24, or 32 bytes (`SerpentCtr`) | `RangeError` | `key must be 16, 24, or 32 bytes` |
@@ -931,38 +501,19 @@ cipher.dispose();
 | IV is not 16 bytes (`SerpentCbc`) | `RangeError` | `CBC IV must be 16 bytes (got N)` |
 | Ciphertext length is zero or not a multiple of 16 (`SerpentCbc.decrypt`) | `RangeError` | `ciphertext length must be a non-zero multiple of 16` |
 | Invalid PKCS7 padding on decrypt (`SerpentCbc.decrypt`) | `RangeError` | `invalid PKCS7 padding` |
-| `SerpentStream` constructed before `init(['serpent', 'sha2'])` | `Error` | `leviathan-crypto: call init(['serpent', 'sha2']) before using SerpentStream` |
-| `SerpentStream` key is not 32 bytes | `RangeError` | `SerpentStream key must be 32 bytes (got N)` |
-| `SerpentStream` chunkSize out of range | `RangeError` | `SerpentStream chunkSize must be 1024..65536 (got N)` |
-| `SerpentStream` ciphertext too short | `RangeError` | `SerpentStream: ciphertext too short` |
-| `SerpentStream` authentication failed | `Error` | `SerpentStream: authentication failed` |
-| `SerpentStreamPool.create()` before `init(['serpent', 'sha2'])` | `Error` | `leviathan-crypto: call init(['serpent', 'sha2']) before using SerpentStreamPool` |
-| `SerpentStreamPool` methods after `dispose()` | `Error` | `leviathan-crypto: pool is disposed` |
-| `SerpentStreamSealer` constructed before `init(['serpent', 'sha2'])` | `Error` | `leviathan-crypto: call init(['serpent']) before using SerpentStreamSealer` |
-| `SerpentStreamSealer` key is not 64 bytes | `RangeError` | `SerpentStreamSealer key must be 64 bytes (got N)` |
-| `SerpentStreamSealer` chunkSize out of range | `RangeError` | `SerpentStreamSealer chunkSize must be 1024..65536 (got N)` |
-| `SerpentStreamSealer.header()` called twice | `Error` | `SerpentStreamSealer: header() already called` |
-| `SerpentStreamSealer.seal()` before `header()` | `Error` | `SerpentStreamSealer: call header() first` |
-| `SerpentStreamSealer.seal()` or `final()` after `final()` or `dispose()` | `Error` | `SerpentStreamSealer: stream is closed` |
-| `SerpentStreamSealer.seal()` wrong plaintext size | `RangeError` | `SerpentStreamSealer: seal() requires exactly N bytes (got M)` |
-| `SerpentStreamSealer.final()` plaintext exceeds chunkSize | `RangeError` | `SerpentStreamSealer: final() plaintext exceeds chunkSize (got N)` |
-| `SerpentStreamOpener` constructed before `init(['serpent', 'sha2'])` | `Error` | `leviathan-crypto: call init(['serpent']) before using SerpentStreamOpener` |
-| `SerpentStreamOpener` key is not 64 bytes | `RangeError` | `SerpentStreamOpener key must be 64 bytes (got N)` |
-| `SerpentStreamOpener` header is not 20 bytes | `RangeError` | `SerpentStreamOpener header must be 20 bytes (got N)` |
-| `SerpentStreamOpener.open()` authentication failed | `Error` | `SerpentStreamOpener: authentication failed` |
-| `SerpentStreamOpener.open()` after stream closed | `Error` | `SerpentStreamOpener: stream is closed` |
 
 ---
 
 > ## Cross-References
 >
 > - [index](./README.md) — Project Documentation index
+> - [lexicon](./lexicon.md) — Glossary of cryptographic terms
 > - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
 > - [asm_serpent](./asm_serpent.md) — WASM implementation details and buffer layout
 > - [serpent_reference](./serpent_reference.md) — algorithm specification, S-boxes, linear transform, and known attacks
 > - [serpent_audit](./serpent_audit.md) — security audit findings (correctness, side-channel analysis)
-> - [chacha20](./chacha20.md) — XChaCha20Poly1305 authenticated encryption (alternative AEAD)
-> - [sha2](./sha2.md) — HMAC-SHA256 and HKDF used internally by SerpentSeal and SerpentStream
+> - [authenticated encryption](./aead.md) — `Seal`, `SealStream`, `OpenStream`: use `SerpentCipher` as the suite argument
+> - [chacha20](./chacha20.md) — `XChaCha20Cipher`: alternative `CipherSuite` for `Seal` and streaming
+> - [sha2](./sha2.md) — HMAC-SHA256 and HKDF used internally by `SerpentCipher`
 > - [types](./types.md) — `Blockcipher`, `Streamcipher`, and `AEAD` interfaces implemented by Serpent classes
 > - [utils](./utils.md) — `constantTimeEqual`, `wipe`, `randomBytes` used by Serpent wrappers
-