leviathan-crypto 2.1.0 → 3.0.0

package/SECURITY.md

@@ -1,163 +0,0 @@
-# Leviathan Crypto Library Security Policy
-
-<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="Leviathan logo" width="100" align="left">
-
-- **[Security Posture](#security-posture)**
-- **[Cryptanalytic Audits](#cryptanalytic-audits)**
-- **[Supported Versions](#supported-versions)**
-- **[Vulnerability Reporting](#reporting-a-vulnerability)**
-
----
-
-## Security posture
-
-[leviathan-crypto](https://leviathan.3xi.club/) is a cryptography library. Security shapes every layer of the stack.
-
-### Algorithm correctness
-
-Every primitive in this library was implemented by hand in AssemblyScript against the authoritative specification: [FIPS 180-4](https://csrc.nist.gov/publications/detail/fips/180/4/final) for SHA-2, [FIPS 202](https://csrc.nist.gov/publications/detail/fips/202/final) for SHA-3, [FIPS 203](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf) for ML-KEM, [RFC 8439](https://www.rfc-editor.org/rfc/rfc8439) for ChaCha20-Poly1305, [RFC 2104](https://www.rfc-editor.org/rfc/rfc2104) for HMAC, [RFC 5869](https://www.rfc-editor.org/rfc/rfc5869) for HKDF, and the original [Serpent-256 specification](https://www.cl.cam.ac.uk/~rja14/Papers/serpent.pdf) with S-box reference. No algorithm came from an existing implementation. The spec is the source of truth.
-
-All implementations verify against published known-answer test vectors from NIST, RFC appendices, NESSIE, and the Argon2 reference suite. Test vectors are immutable; if an implementation produces incorrect output, we fix the code and never adjust the vectors to match.
-
-### Side-channel resistance
-
-Serpent's S-boxes use Boolean gate circuits with no table lookups, no data-dependent memory access, and no data-dependent branches. Every bit processes unconditionally on every block. This is the most timing-safe cipher approach available in WASM, where JIT optimization can otherwise introduce observable timing variation.
-
-Security-sensitive comparisons (MAC verification, padding validation) use [`constantTimeEqual`](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal), backed by a dedicated WASM SIMD module. The v128 XOR accumulate with branch-free scalar tail reduction eliminates JIT short-circuiting and speculative optimization as side-channel vectors. The function requires WebAssembly SIMD and throws a branded error on runtimes without it, matching the library-wide SIMD requirement. WASM comparison memory gets wiped after every call.
-
-### WASM execution model
-
-All cryptographic computation runs in WebAssembly, isolated outside the JavaScript JIT. WASM execution is deterministic and not subject to JIT speculation or optimization. Each primitive family compiles to its own isolated binary with its own linear memory. Key material in the Serpent module cannot interact with memory in the SHA-3 module, even in principle. A dedicated WASM module handles constant-time comparison with its own single-page memory that is wiped after every call.
-
-Serpent and ChaCha20 modules require WebAssembly SIMD (v128 instructions). `init()` and `initModule()` perform a SIMD preflight check and throw a clear error on runtimes without support. SIMD has been a baseline feature of all major browsers and runtimes since 2021. SHA-2 and SHA-3 modules run on any WASM-capable runtime.
-
-The kyber module requires WebAssembly SIMD for NTT and polynomial arithmetic (v128 instructions). The SIMD preflight check applies on `init()` alongside serpent and chacha20. Its linear memory is independent from all other modules. Kyber's constant-time path (FO transform decapsulation) uses dedicated `ct_verify` and `ct_cmov` functions implemented in the kyber WASM binary; comparison never passes through JavaScript.
-
-Stateful classes (`SHAKE128/256`, `ChaCha20`, `SerpentCtr`, `SerpentCbc`, `MlKem*`) enforce module exclusivity at runtime. A live instance holds an exclusivity token on its backing WASM module; constructing a second instance against the same module throws until the first is disposed. Cross-module operations (kyber decapsulate invoking sha3 hashing) assert non-ownership of the modules they touch before writing to them, preventing silent re-initialization of a live sponge or cipher state.
-
-### Memory hygiene
-
-Every public cryptographic operation zeros its secret and secret-derived scratch before returning. Across all three ML-KEM operations (`keygen`, `encapsulate`, `decapsulate`), no kyber secret or secret-derived data persists in kyber or sha3 linear memory between operations. The CPA secret key, per-message noise polynomials, raw message bytes, PRF output buffers, and FO re-encryption intermediates all get wiped at the operation boundary. AEAD authentication failures wipe the full keystream block and the Poly1305 one-time subkey. Fortuna's `stop()` is a complete teardown: generator key, generator counter, all 32 pool-hash chain values, and a `wipeBuffers()` call on every WASM module the chosen generator and hash touched. Stream constructions (`SealStream`/`OpenStream`) transition to a terminal `'failed'` state on any mid-operation throw, wiping derived keys before the exception propagates.
-
-This wipe discipline defends against a narrow but concrete threat: an adversary with read access to WASM linear memory between operations. JS-side memory disclosure, host CPU side channels (cache, branch predictor, speculative execution beyond what WASM neuters), and physical device access remain out of scope; those are the runtime's and the hardware's responsibility.
-
-Key-validation helpers (`checkEncapsulationKey`, `checkDecapsulationKey`) operate on public material only and require no wipe. They are side-effect-free with respect to module state.
-
-### Authenticated encryption by default
-
-Raw unauthenticated cipher modes (`SerpentCbc`, `SerpentCtr`, `ChaCha20`) and stateless caller-managed-nonce primitives (`ChaCha20Poly1305`, `XChaCha20Poly1305`) are exposed for power users but are not the recommended entry point. The primary API surfaces (`Seal`, `SealStream`, `OpenStream`, `SealStreamPool`, and `KyberSuite`) are authenticated by construction with internally managed nonces.
-
-All streaming constructions satisfy the _Cryptographic Doom Principle_.
-
-**SealStream/OpenStream with SerpentCipher.** Encrypt-then-MAC (SerpentCbc + HMAC-SHA256). The HMAC tag is compared against the expected tag via `constantTimeEqual` — backed by the dedicated WASM SIMD CT module — and that compare is the unconditional gate into the CBC WASM decrypt path; decryption is unreachable until the gate clears. HKDF key derivation with the stream nonce and counter-nonce domain separation extends this guarantee to full stream integrity.
-
-**SealStream/OpenStream with XChaCha20Cipher.** XChaCha20-Poly1305 AEAD per chunk. The Poly1305 tag is compared against the expected tag via `constantTimeEqual` — backed by the dedicated WASM SIMD CT module — before any call to the chacha20 WASM decrypt path. On authentication failure, the full chunk output buffer is wiped and plaintext bytes never return. Counter nonces with TAG_DATA/TAG_FINAL final-flag domain separation ensure reorder, splice, truncation, and cross-stream substitution all fail AEAD verification before decryption.
-
-**SealStreamPool.** Delegates per-chunk AEAD to isolated Web Workers. Each worker holds its own derived subkey and WASM instance. Any authentication error marks the pool dead, rejects all pending operations, requests that each worker zero its in-memory key material, and terminates workers after a short ACK window. Main-thread copies of the derived keys and master key are zeroed synchronously. No retry, no partial results.
-
-The stateless AEADs (`ChaCha20Poly1305`, `XChaCha20Poly1305`) enforce strict single-use; any throw from `encrypt()` (including length validation errors on `key` or `nonce`) terminates the instance. A retry with valid arguments always raises the single-use guard rather than potentially reusing a nonce. Consumers allocate a fresh AEAD per message.
-
-### Key-material lifecycle
-
-`SkippedKeyStore.resolve` returns a transactional `ResolveHandle` rather than a raw key. The caller settles the handle via `commit()` on successful decryption (the key is wiped) or `rollback()` on authentication failure (the key returns to the store under its counter, so a subsequent legitimate delivery at the same counter can still decrypt). This closes a delete-on-retrieval DoS where an adversary injecting a garbage ciphertext at a valid counter would otherwise consume that counter's cached key before the legitimate message arrived. A `FinalizationRegistry` wipes the key best-effort if a handle is GC'd unsettled.
-
-`SkippedKeyStore` splits its work budget into `maxCacheSize` (memory bound, default 100) and `maxSkipPerResolve` (per-message HKDF work bound, default 50). A malicious header with a very high counter cannot force unbounded HKDF derivations on the receiver; eviction is O(1) via insertion-order iteration.
-
-`OpenStream.seek(index)` only moves forward. Backward seeks would reuse an already-consumed per-chunk counter nonce against a new ciphertext, permitting plaintext replay against a stale opener. The call throws rather than silently reusing the nonce.
-
-### Dependency management
-
-This library has zero runtime dependencies by design. `sideEffects: false` is enforced in `package.json`. Argon2id integration is documented as an _optional_ external dependency. See: [leviathan-crypto/wiki/argon2id](https://github.com/xero/leviathan-crypto/wiki/argon2id).
-
-Build toolchain dependencies use exact version locks in `bun.lock`. GitHub Actions workflows use [SHA-pinned action references](https://github.com/xero/leviathan-crypto/blob/main/scripts/pin-actions.ts) throughout with no floating tags. Supply chain integrity is a first-class concern for a cryptography library.
-
-### Explicit initialization
-
-No class silently auto-initializes. The [`init()`](https://github.com/xero/leviathan-crypto/wiki/init) gate is mandatory and explicit, giving you full control over when WASM modules load and ensuring no hidden initialization costs or race conditions. Classes throw immediately if used before initialization rather than failing silently.
-
-### Agentic development contracts
-
-All AI-assisted development on this repository operates under a strict agentic contract defined in [AGENTS.md](https://github.com/xero/leviathan-crypto/blob/main/AGENTS.md). The contract enforces spec authority over planning documents, immutable test vectors, gate discipline before extending any test suite, independent algorithm derivation from published standards, and constant-time and wipe requirements for all security-sensitive code paths. Agents are explicitly prohibited from guessing cryptographic values or resolving spec ambiguities silently.
-
-The contract has been verified against Claude, GitHub Copilot (VS Code), OpenHands, Kilo Code, Cursor, Windsurf, and Aider. Configuration files for each are in the repository and all route to [AGENTS.md](https://github.com/xero/leviathan-crypto/blob/main/AGENTS.md) as the single source of authority.
-
----
-
-## Cryptanalytic audits
-
-All primitives undergo periodic cryptographic implementation reviews. See the [audit index](https://github.com/xero/leviathan-crypto/wiki/audits) for a full summary.
-
-| Primitive | Audit description |
-| --- | --- |
-| [serpent_audit](https://github.com/xero/leviathan-crypto/wiki/serpent_audit) | Correctness verification, side-channel analysis, cryptanalytic attack paper review |
-| [chacha_audit](https://github.com/xero/leviathan-crypto/wiki/chacha_audit) | XChaCha20-Poly1305 correctness, Poly1305 field arithmetic, HChaCha20 nonce extension, post-auth-fail wipe hygiene |
-| [sha2_audit](https://github.com/xero/leviathan-crypto/wiki/sha2_audit) | SHA-256/512/384 correctness, HMAC and HKDF composition, constant verification |
-| [sha3_audit](https://github.com/xero/leviathan-crypto/wiki/sha3_audit) | Keccak permutation correctness, θ/ρ/π/χ/ι step verification, round constant derivation |
-| [hmac_audit](https://github.com/xero/leviathan-crypto/wiki/hmac_audit) | HMAC-SHA256/512/384 construction, key processing, RFC 4231 vector coverage |
-| [hkdf_audit](https://github.com/xero/leviathan-crypto/wiki/hkdf_audit) | HKDF extract-then-expand, info field domain separation, stream key derivation |
-| [kyber_audit](https://github.com/xero/leviathan-crypto/wiki/kyber_audit) | ML-KEM FIPS 203 correctness (§7.2/§7.3 direct coefficient-range validation), NTT/Montgomery/Barrett verification, FO transform CT analysis, per-op memory hygiene across keygen/encap/decap, ACVP validation |
-| [stream_audit](https://github.com/xero/leviathan-crypto/wiki/stream_audit) | Streaming AEAD composition, counter nonce binding, final-chunk detection, key wipe paths, `'failed'` terminal state |
-| [ratchet_audit](https://github.com/xero/leviathan-crypto/wiki/ratchet_audit) | SPQR KDF primitives: HKDF parameter assignments with full transcript binding (peerEk, kemCt, context), wipe coverage, counter encoding, direction slot alignment, transactional `ResolveHandle` DoS mitigation |
-
-### Serpent-256 security margin research
-
-The security margin of Serpent-256 has been independently researched and documented. The best known attack on the full 32-round cipher, _biclique cryptanalysis_, achieves a complexity of 2²⁵⁵·¹⁹ with 2⁴ chosen ciphertexts. This provides less than one bit of advantage over exhaustive key search and has zero practical impact. Independent research conducted against this implementation improved on the published result by −0.20 bits through systematic parameter search, confirming no structural weakness beyond what the published literature describes.
-
-See: [xero/BicliqueFinder/biclique_research.md](https://github.com/xero/BicliqueFinder/blob/main/biclique-research.md)
-
----
-
-## Supported versions
-
-Every fix is documented in the full [CHANGELOG](https://github.com/xero/leviathan-crypto/blob/main/CHANGELOG). Each version below links to the release notes documenting its fixes.
-
-| Version | Status | Summary |
-| --- | --- | --- |
-| [v2.1.x](https://github.com/xero/leviathan-crypto/blob/main/CHANGELOG#v2-1-0-XXXX-XX-XX) | ✓ supported | Adds SPQR post-quantum KEM ratchet primitives |
-| [v2.0.x](https://github.com/xero/leviathan-crypto/blob/main/CHANGELOG#v2-0-1-2026-04-10) | ✗ superseded | FIPS 203 key validation, per-op wipe hygiene, padding-oracle closure, and ratchet DoS mitigation. Upgrade to v2.1.x |
-| [v1.x](https://github.com/xero/leviathan-crypto/blob/main/CHANGELOG#v2-0-0-2026-04-10) | ✗ deprecated | Multiple partial-wipe and auth-handling issues. Upgrade to v2.1.x |
-
-> [!CAUTION]
-> v2.0.0 has a known silent-corruption bug. `SealStreamPool` with `SerpentCipher` silently produces corrupt plaintext with no authentication error on decrypt for inputs ≥ 65536 bytes. See [v2.0.1 release notes](https://github.com/xero/leviathan-crypto/blob/main/CHANGELOG#v2-0-1-2026-04-10) and update to the latest version immediately.
-
----
-
-## Reporting a vulnerability
-
-> [!IMPORTANT]
-> Do not open a public issue for security vulnerabilities.
-
-### Private advisory (preferred)
-
-Use GitHub's private vulnerability reporting form: [https://github.com/xero/leviathan-crypto/security/advisories/new](https://github.com/xero/leviathan-crypto/security/advisories/new)
-
-This opens a private channel between you and the maintainer, and you will receive a response promptly. If the vulnerability is confirmed, we collaborate to fully understand the issue, including a review of proposed fixes, so you can track and validate firsthand. Before any public advisory publishes, we agree on a coordinated disclosure timeline. After disclosure, you are encouraged to publish your own write-up, blog post, or research notes for full hacker scene credit.
-
-### Direct contact
-
-If you prefer direct contact:
-
-- **Email:** x﹫xero.style · PGP: [0xAC1D0000](https://0w.nz/pgp.pub)
-- **Matrix:** x0﹫rx.haunted.computer
-
-> [!NOTE]
-> Encrypted communication is welcome and preferred for sensitive reports.
-
-### In scope
-
-- Authentication bypass in AEAD constructions
-- Key material exposure or improper zeroing
-- Incorrect entropy or CSPRNG weaknesses in Fortuna
-- Side-channel vulnerabilities (timing, memory access patterns)
-- Correctness bugs in cryptographic implementations (wrong output against test vectors)
-- Platform-specific behavioral differences (WASM execution, binary output, or timing characteristics that differ across operating systems or CPU architectures)
-- Supply chain issues (dependency tampering, workflow compromise)
-- Improper scope of exported symbols
-
-### Out of scope
-
-- Vulnerabilities in third-party packages not maintained by this project. This includes optional peer dependencies such as argon2id. Report those directly to their maintainers.
-- Issues requiring physical access to the user's device
-- Theoretical attacks with no practical exploit path (complexity improvements that remain computationally infeasible)
-- Issues in the demo applications that do not affect the core library. Open an issue in [leviathan-demos](https://github.com/xero/leviathan-demos/) instead.
-

package/dist/ct-wasm.d.ts

@@ -1 +0,0 @@
-export declare const CT_WASM: Uint8Array<ArrayBuffer>;

package/dist/ct-wasm.js

@@ -1,3 +0,0 @@
-// auto-generated — do not edit
-// raw WASM bytes for constant-time comparison module
-export const CT_WASM = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 1, 8, 1, 96, 3, 127, 127, 127, 1, 127, 3, 2, 1, 0, 5, 4, 1, 1, 1, 1, 7, 20, 2, 7, 99, 111, 109, 112, 97, 114, 101, 0, 0, 6, 109, 101, 109, 111, 114, 121, 2, 0, 10, 133, 1, 1, 130, 1, 3, 2, 127, 1, 126, 1, 123, 3, 64, 32, 3, 65, 16, 106, 34, 4, 32, 2, 76, 4, 64, 32, 6, 32, 0, 32, 3, 106, 253, 0, 4, 0, 32, 1, 32, 3, 106, 253, 0, 4, 0, 253, 81, 253, 80, 33, 6, 32, 4, 33, 3, 12, 1, 11, 11, 3, 64, 32, 2, 32, 3, 74, 4, 64, 32, 5, 32, 0, 32, 3, 106, 49, 0, 0, 32, 1, 32, 3, 106, 49, 0, 0, 133, 132, 33, 5, 32, 3, 65, 1, 106, 33, 3, 12, 1, 11, 11, 66, 0, 32, 5, 32, 6, 253, 29, 0, 32, 6, 253, 29, 1, 132, 132, 34, 5, 125, 32, 5, 132, 66, 63, 135, 66, 127, 133, 167, 65, 1, 113, 11]);

package/dist/docs/aead.md

@@ -1,363 +0,0 @@
-<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="logo" width="120" align="left" margin="10">
-
-### Authenticated Encryption
-
-Cipher-agnostic authenticated encryption for any scale. One-shot with `Seal`, chunked with `SealStream` and `OpenStream`, or parallel with `SealStreamPool`. All four share a wire format and accept any `CipherSuite`.
-
-> ### Table of Contents
-> - [Overview](#overview)
-> - [Security Model](#security-model)
-> - [Wire Format](#wire-format)
-> - [API Reference](#api-reference)
-
----
-
-## Overview
-
-Authenticated encryption in leviathan-crypto centers on four classes: `Seal`, `SealStream`, `OpenStream`, and `SealStreamPool`. All are cipher-agnostic. Pass a `CipherSuite` object at construction and they handle key derivation, nonce management, and authentication automatically.
-
-These four form a natural progression by use case. Use `Seal` for data that fits in memory. Use `SealStream` and `OpenStream` for data arriving in chunks or too large to buffer. Use `SealStreamPool` for parallel chunked encryption across Web Workers. All four share the same wire format, so `OpenStream` can decrypt a `Seal` blob and vice versa.
-
-leviathan-crypto includes two cipher suites. A third suite wraps either with ML-KEM for post-quantum hybrid encryption.
-
-| Suite | Cipher | Tag | Modules |
-|---|---|---|---|
-| `SerpentCipher` | Serpent-256 CBC + HMAC-SHA-256 | 32 B | `serpent`, `sha2` |
-| `XChaCha20Cipher` | XChaCha20-Poly1305 | 16 B | `chacha20`, `sha2` |
-| `KyberSuite` | ML-KEM + inner cipher | depends | `kyber`, `sha3`, + inner |
-
-See [ciphersuite.md](./ciphersuite.md) for full cipher suite documentation.
-
----
-
-## Security Model
-
-The STREAM construction is based on [Hoang, Reyhanitabar, Rogaway, and Vizár (CRYPTO 2015)](https://eprint.iacr.org/2015/189.pdf). It provides online authenticated encryption with four guarantees.
-
-**Per-chunk authentication.** Each chunk carries its own authentication tag. The stream rejects a tampered chunk immediately and stops decrypting.
-
-**Counter binding.** Each chunk's nonce includes a monotonic counter. Reordering or duplicating chunks produces a counter mismatch and authentication fails.
-
-**Final-chunk detection.** The last chunk uses a distinct nonce flag (`TAG_FINAL` vs `TAG_DATA`). The opener expects a chunk marked final and rejects any stream that ends without one.
-
-**Stream isolation.** Each stream generates a fresh 16-byte random nonce on construction. Two streams with the same key derive independent subkeys via HKDF and cannot interfere with each other.
-
-> [!IMPORTANT]
-> `SealStream` is single-use. After `finalize()` is called the derived keys are wiped and no further chunks can be sealed. Create a new `SealStream` for each message. `SealStreamPool.seal()` enforces this with a guard that throws on subsequent calls.
->
-> **`SealStream` / `OpenStream` have a three-state machine: `ready` → `finalized` | `failed`.** An auth failure, WASM error, or cipher exception inside `push()`, `pull()`, or `finalize()` wipes the derived keys and transitions the stream to `failed`. Subsequent method calls (`push`, `pull`, `finalize`, and `OpenStream.seek`) throw with `'failed'` in the message, never `'finalized'`. `dispose()` on a `failed` stream is a no-op. Construct a new stream to continue.
->
-> **Argument-validation errors are non-terminal on both `SealStream` and `OpenStream`.** A `RangeError` from `push()` or `finalize()` for a chunk larger than `chunkSize` throws without wiping keys or entering `'failed'`. Symmetrically, a `RangeError` from `pull()` or `finalize()` throws without wiping keys when a chunk is too short to contain a tag, exceeds the maximum wire size, or (in framed mode) has a length prefix that does not match the payload length. The stream stays in `'ready'` and the caller can retry with a corrected chunk.
->
-> This is safe because every validation error depends only on attacker-observable input lengths and never on secret-derived state. Distinguishing a validation throw from an auth failure gives an attacker no information they did not already have. Auth failures from `cipher.openChunk` remain terminal, as they are the crypto-path case.
->
-> **`OpenStream.seek(index)` validates `index` before mutating state.** Indices that are not non-negative safe integers — `NaN`, `Infinity`, fractional, negative, or `> Number.MAX_SAFE_INTEGER` — throw `RangeError` without changing `counter`, so the caller can retry with a corrected index. The check uses `Number.isSafeInteger(index) && index >= 0` so values above `2^53 - 1` (where IEEE 754 doubles have integer gaps) are rejected directly rather than relying on a separate magnitude comparison. Backward seeks (`index < counter`) throw `'forward-only'` for the same reason (plaintext replay prevention). See `seek()` in the OpenStream API table.
->
-> **AEAD `encrypt()` is strict single-use.** `ChaCha20Poly1305.encrypt()` and `XChaCha20Poly1305.encrypt()` are terminal on any throw, including key and nonce length validation. A retry on the same instance always raises the single-use guard, never a fresh length error. This tightens the 2.0-beta semantics where length validation was recoverable. Always allocate a new AEAD per message.
->
-> **`SealStreamPool.seal()` is terminal on any throw.** Auth failures, worker crashes, job timeouts, output-size overflows (`RangeError` from assembling ciphertext that exceeds the runtime's typed-array max), or any other rejection kill the pool. Pending jobs reject, workers terminate, `_masterKey` and `_keys` are wiped, and subsequent calls throw `"pool is dead"`. Construct a new pool to continue. Any throw is terminal, which keeps the failure contract uniform with the strict single-use posture of `ChaCha20Poly1305.encrypt()`.
-
-### WASM Side-Channel Posture
-
-All cryptographic computation runs in WASM outside the JavaScript JIT. Serpent's bitsliced S-box implementation and ChaCha20's quarter-round construction are both branchless and table-free, which eliminates data-dependent timing variation at the algorithm level. WASM lacks hardware-level constant-time guarantees, so this provides stronger posture than pure JavaScript but weaker than native constant-time code. If timing side channels are your primary threat model, a native cryptographic library with verified constant-time guarantees is more appropriate.
-
----
-
-## Wire Format
-
-### Header (20 bytes)
-
-Every stream begins with a 20-byte header:
-
-```
-bytes:
-    0: compound enum (bit 7 = framed flag, bit 6 = reserved, bits 0-5 = format ID)
- 1-16: random nonce (16 bytes)
-17-19: chunk size as u24 big-endian
-```
-
-**Format IDs:** `0x01` = XChaCha20-Poly1305, `0x02` = Serpent-256. KEM suites encode both the parameter set and inner cipher in a single byte. See [ciphersuite.md](./ciphersuite.md#kybersuite) for the full format enum table.
-
-The 16-byte nonce is a HKDF salt, not a direct cipher nonce. `XChaCha20Cipher` passes it to HChaCha20 for subkey derivation. `SerpentCipher` uses it as the HKDF-SHA-256 salt to derive 96 bytes of enc/mac/iv key material.
-
-The framed flag (bit 7) prefixes each chunk with a `u32be` length. Use framed mode for flat byte streams where chunks are concatenated without an external framing layer. Leave it off when the transport provides its own message boundaries such as WebSocket frames or IPC messages.
-
-### Counter Nonce (12 bytes)
-
-Each chunk is encrypted with a 12-byte nonce:
-
-```
-bytes:
- 0-10: 11-byte big-endian counter (monotonically increasing)
-   11: final flag (0x00 = TAG_DATA, 0x01 = TAG_FINAL)
-```
-
-The counter starts at 0 and increments with each chunk. The final chunk uses `TAG_FINAL` instead of `TAG_DATA`. A data chunk at counter N and a final chunk at counter N produce distinct nonces, so the construction never reuses a nonce.
-
-### Key Derivation
-
-HKDF-SHA-256 derives cipher-specific key material from the master key and the random nonce at stream construction:
-
-| Cipher | HKDF info | Output | Structure |
-|---|---|---|---|
-| XChaCha20 | `xchacha20-sealstream-v2` | 32 B | HKDF → streamKey → HChaCha20 → subkey |
-| Serpent | `serpent-sealstream-v2` | 96 B | `enc_key[0:32] \| mac_key[32:64] \| iv_key[64:96]` |
-
-XChaCha20 performs an additional HChaCha20 subkey derivation step using the first 16 bytes of the nonce. The intermediate streamKey is wiped immediately after use.
-
-Serpent derives three keys: an encryption key for CBC, a MAC key for HMAC-SHA-256, and an IV key for per-chunk IV derivation via `HMAC-SHA-256(iv_key, counterNonce)[0:16]`. The CBC IV is derived deterministically on both sides and never transmitted.
-
----
-
-## API Reference
-
-### Seal
-
-`Seal` is a static class, never instantiated. It handles one-shot authenticated encryption and decryption. A `Seal` blob is structurally identical to a single-chunk `SealStream` output: `preamble || finalChunk(counter=0, TAG_FINAL)`. `OpenStream.finalize()` can open a `Seal` blob directly, and `Seal.decrypt()` can open a single-chunk `SealStream`.
-
-```typescript
-import { init, Seal, XChaCha20Cipher } 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, plaintext)
-const pt   = Seal.decrypt(XChaCha20Cipher, key, blob)  // throws AuthenticationError on tamper
-```
-
-| Method | Returns | Description |
-|---|---|---|
-| `Seal.encrypt(suite, key, plaintext, opts?)` | `Uint8Array` | One-shot encrypt. Returns `preamble \|\| chunk`. |
-| `Seal.decrypt(suite, key, blob, opts?)` | `Uint8Array` | One-shot decrypt. Throws `AuthenticationError` on tamper. |
-
-**`opts.aad`.** Optional `Uint8Array` carrying Additional Authenticated Data. Authenticated but not encrypted. Pass the same value to both `encrypt` and `decrypt`.
-
-> [!NOTE]
-> **`chunkSize` in the wire header is a maximum, not an actual size.** For `Seal.encrypt` (single-chunk), the header always declares `max(plaintext.length, CHUNK_MIN)`, so a zero-byte seal still declares `chunkSize = CHUNK_MIN = 1024`. This is self-consistent on decode (the single final chunk is processed regardless of its actual length up to the declared bound) and prevents leaking the exact plaintext length through header analysis when `plaintext.length < CHUNK_MIN`. `SealStream` writes the configured `opts.chunkSize` verbatim; the receiver treats it as an upper bound on any incoming chunk's plaintext size.
-
----
-
-### SealStream
-
-> [!NOTE]
-> All stream classes require `sha2` for HKDF key derivation. Load it alongside your cipher module before constructing any stream.
-
-```typescript
-import { init, SealStream } from 'leviathan-crypto'
-import { XChaCha20Cipher } from 'leviathan-crypto/chacha20'
-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 sealer   = new SealStream(XChaCha20Cipher, key, { chunkSize: 65536 })
-const preamble = sealer.preamble  // send first
-
-const ct0    = sealer.push(chunk0)
-const ct1    = sealer.push(chunk1)
-const ctLast = sealer.finalize(lastChunk)  // keys wiped
-```
-
-**Constructor:** `new SealStream(cipher, key, opts?)`
-
-| Parameter | Type | Description |
-|---|---|---|
-| `cipher` | `CipherSuite` | `XChaCha20Cipher`, `SerpentCipher`, or a `KyberSuite` instance. |
-| `key` | `Uint8Array` | Master key. Must be `cipher.keySize` bytes (32 for both symmetric suites). |
-| `opts.chunkSize` | `number` | Max plaintext bytes per chunk. Range: [1024, 16777215]. Default: 65536. |
-| `opts.framed` | `boolean` | Prepend `u32be` length prefix to each chunk. Default: false. |
-
-| Method | Returns | Description |
-|---|---|---|
-| `push(chunk, { aad? })` | `Uint8Array` | Encrypt a data chunk. Must be ≤ chunkSize bytes. |
-| `finalize(chunk, { aad? })` | `Uint8Array` | Encrypt the final chunk and wipe keys. Must be ≤ chunkSize bytes. |
-| `toTransformStream()` | `TransformStream` | Web Streams API wrapper. Emits preamble first, then sealed chunks. Finalizes on stream close. |
-| `preamble` | `Uint8Array` | The stream preamble (read-only). 20 bytes for symmetric suites. 20B header + KEM ciphertext for KEM suites. |
-
----
-
-### OpenStream
-
-```typescript
-import { OpenStream }      from 'leviathan-crypto/stream'
-import { XChaCha20Cipher } from 'leviathan-crypto/chacha20'
-import { chacha20Wasm }    from 'leviathan-crypto/chacha20/embedded'
-import { sha2Wasm }        from 'leviathan-crypto/sha2/embedded'
-
-// init already called — preamble, key, and ciphertext chunks received from sender
-const opener = new OpenStream(XChaCha20Cipher, key, preamble)
-
-const pt0    = opener.pull(ct0)
-const pt1    = opener.pull(ct1)
-const ptLast = opener.finalize(ctLast)  // keys wiped
-```
-
-**Constructor:** `new OpenStream(cipher, key, preamble)`
-
-Throws if the preamble format enum doesn't match the cipher or if the preamble is too short.
-
-| Parameter | Type | Description |
-|---|---|---|
-| `cipher` | `CipherSuite` | Must match the cipher that produced the preamble. |
-| `key` | `Uint8Array` | Same master key used for sealing. |
-| `preamble` | `Uint8Array` | The preamble from `SealStream.preamble`. Pass it directly. |
-
-| Method | Returns | Description |
-|---|---|---|
-| `pull(chunk, { aad? })` | `Uint8Array` | Decrypt a data chunk. Throws `AuthenticationError` on tamper. |
-| `finalize(chunk, { aad? })` | `Uint8Array` | Decrypt the final chunk and wipe keys. |
-| `seek(index)` | `void` | Set the counter to `index`. The stream is forward-only; `index < counter` throws `RangeError` with `'forward-only'` in the message. `index` must satisfy `Number.isSafeInteger(index) && index >= 0` (i.e. a non-negative safe integer ≤ `Number.MAX_SAFE_INTEGER`). Argument-validation throws do not mutate `counter`; the stream stays usable and can retry with a corrected index. Throws on failed/finalized state (state guard fires before range check). |
-| `toTransformStream()` | `TransformStream` | Web Streams API wrapper. Buffers one chunk to detect the final chunk. |
-
-> [!IMPORTANT]
-> **`OpenStream.seek` is forward-only.** Backward seeks (`index < this.counter`) throw a `RangeError` with `'forward-only'` in the message. A backward seek would reuse an already-consumed per-chunk counter nonce against a new ciphertext, permitting plaintext replay against a stale opener. Construct a fresh `OpenStream` from the same preamble to restart from the beginning.
-
----
-
-### SealStreamPool
-
-Parallel batch encryption and decryption using Web Workers. Each worker holds its own WASM instance and a copy of the derived keys.
-
-```typescript
-import { init, SealStreamPool } from 'leviathan-crypto'
-import { XChaCha20Cipher }      from 'leviathan-crypto/chacha20'
-import { chacha20Wasm }         from 'leviathan-crypto/chacha20/embedded'
-import { sha2Wasm }             from 'leviathan-crypto/sha2/embedded'
-
-await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })
-
-const pool = await SealStreamPool.create(XChaCha20Cipher, key, {
-  wasm: chacha20Wasm,
-  workers: 4,
-  chunkSize: 65536,
-})
-
-const ciphertext = await pool.seal(plaintext)
-const decrypted  = await pool.open(ciphertext)
-pool.destroy()
-```
-
-**`SealStreamPool.create(cipher, key, opts)`.** Async factory.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `wasm` | `WasmSource` or `Record<string, WasmSource>` | required | WASM source(s). Single value for XChaCha20. Record for Serpent: `{ serpent, sha2 }`. |
-| `workers` | `number` | `navigator.hardwareConcurrency` (4 if unset) | Worker count. |
-| `chunkSize` | `number` | `65536` | Chunk size in bytes. |
-| `framed` | `boolean` | `false` | Framed mode. |
-| `jobTimeout` | `number` | `30000` | Per-job timeout in ms. |
-
-> [!NOTE]
-> For padded ciphers (`SerpentCipher`), `create()` validates at startup that a full plaintext chunk fits in the WASM buffer after PKCS7 padding. If `chunkSize` is too large it throws a `RangeError` with the actual values before any workers are launched. The default `chunkSize: 65536` is valid for both built-in cipher suites.
-
-**Failure model.** Any error is fatal. Authentication failure, worker crash, and timeout all terminate every worker, wipe all keys, and mark the pool permanently dead. Pending promises reject. There is no retry and no worker replacement. Create a new pool for the next operation. `destroy()` is synchronous from the caller's perspective. The pool flips to `dead`, pending jobs reject, and main-thread keys are zeroed before the call returns. Worker teardown is bounded-async. The pool requests that each worker zero its in-memory key material and terminates workers after a short ACK window.
-
-| Method / Property | Description |
-|---|---|
-| `seal(plaintext)` | Encrypt. Returns `Promise<Uint8Array>`. Single-use. Throws on subsequent calls. |
-| `open(ciphertext)` | Decrypt. Returns `Promise<Uint8Array>`. Rejects empty ciphertext. |
-| `destroy()` | Wipes keys and terminates workers. Safe to call multiple times. |
-| `header` | The 20-byte stream header. `SealStreamPool` exposes `.header` while `SealStream` exposes `.preamble`, which also supports KEM preambles. |
-| `dead` | `true` after any fatal error or `destroy()`. |
-| `size` | Number of workers. |
-
-**Lifecycle.**
-
-- After `seal()` completes successfully, the pool holds the derived keys and
-  master key in memory until you call `destroy()`. Call `destroy()` explicitly
-  when you are finished; forgetting leaves key material resident until garbage
-  collection.
-- After `seal()`, the pool is marked sealed and further `seal()` calls throw.
-  But `open()` is still valid and can decrypt other ciphertexts using the same
-  master key. This is intentional because a pool is a stateful encrypt/decrypt
-  context tied to a master key, not a single-use seal operation. The word
-  "sealed" can still mislead. If your usage is encrypt-once-then-discard, the
-  idiom is `try { await pool.seal(pt) } finally { pool.destroy() }`.
-- On any job throw (worker crash, auth failure, timeout), the pool's
-  `_killAll` runs. All workers terminate, all keys are wiped, and the pool is
-  marked dead. Subsequent calls throw `'pool is dead'`.
-
-**Interop with `SealStream.push()`.** In unframed mode, `pool.open()` splits the body into chunks at fixed `chunkSize` boundaries. This works when the ciphertext came from `SealStreamPool.seal()` or from a `SealStream` that emitted every non-final chunk at exactly `chunkSize` plaintext bytes. A `SealStream` that called `push()` with sub-`chunkSize` chunks produces a valid blob that `OpenStream` can decrypt, but `pool.open()` cannot. The pool splits at the wrong boundary, stamps the wrong domain separator on the final chunk, and fails authentication. Use `framed: true` on both sides if producer and consumer may have different chunk shapes. Framed chunks carry a `u32be` length prefix that makes the split unambiguous.
-
----
-
-### KyberSuite
-
-`KyberSuite` wraps an ML-KEM instance and an inner `CipherSuite` into a hybrid post-quantum construction. The result plugs into `Seal`, `SealStream`, `OpenStream`, and `SealStreamPool` identically to a symmetric suite.
-
-```typescript
-import { init, SealStream, OpenStream } from 'leviathan-crypto'
-import { KyberSuite, MlKem768 }         from 'leviathan-crypto/kyber'
-import { XChaCha20Cipher }              from 'leviathan-crypto/chacha20'
-import { kyberWasm }    from 'leviathan-crypto/kyber/embedded'
-import { sha3Wasm }     from 'leviathan-crypto/sha3/embedded'
-import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
-import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'
-
-await init({ kyber: kyberWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })
-
-const suite = KyberSuite(new MlKem768(), XChaCha20Cipher)
-const { encapsulationKey: ek, decapsulationKey: dk } = suite.keygen()
-
-// sender — encrypts with the public key
-const sealer   = new SealStream(suite, ek)
-const preamble = sealer.preamble  // 1108 bytes for MlKem768
-const ct0      = sealer.push(chunk0)
-const ctLast   = sealer.finalize(lastChunk)
-
-// recipient — decrypts with the private key
-const opener = new OpenStream(suite, dk, preamble)
-const pt0    = opener.pull(ct0)
-const ptLast = opener.finalize(ctLast)
-```
-
-See [kyber.md](./kyber.md) for key management, parameter set selection, and the full ML-KEM reference. See [ciphersuite.md](./ciphersuite.md#kybersuite) for format enum values and key derivation details.
-
----
-
-### Per-chunk AAD
-
-`push()` and `finalize()` on `SealStream` and `pull()` and `finalize()` on `OpenStream` all accept an optional `{ aad }` parameter for Additional Authenticated Data. AAD is authenticated but not encrypted. It binds each chunk to external context such as sequence numbers, metadata, or routing information without including that data in the ciphertext.
-
-AAD applies per chunk, not per stream. Each chunk can carry different AAD. If you sealed a chunk with AAD you must provide the same value when opening it. A mismatch causes authentication to fail.
-
----
-
-### AuthenticationError
-
-`Seal.decrypt()`, `OpenStream.pull()`, `OpenStream.finalize()`, and `SealStreamPool.open()` throw `AuthenticationError` when authentication fails. It extends `Error` and carries the cipher name in the message.
-
-```typescript
-import { AuthenticationError } from 'leviathan-crypto'
-
-try {
-  const pt = Seal.decrypt(XChaCha20Cipher, key, tampered)
-} catch (e) {
-  if (e instanceof AuthenticationError) {
-    // ciphertext was modified
-  }
-}
-```
-
-Never attempt to recover plaintext after an `AuthenticationError`. The stream layer wipes output buffers before throwing.
-
----
-
-
-## Cross-References
-
-| Document | Description |
-| -------- | ----------- |
-| [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 |
-| [ciphersuite](./ciphersuite.md) | `SerpentCipher`, `XChaCha20Cipher`, `KyberSuite`, and the `CipherSuite` interface |
-| [kyber](./kyber.md) | ML-KEM key encapsulation, parameter sets, and key management |
-| [serpent](./serpent.md) | Serpent-256 raw primitives |
-| [chacha20](./chacha20.md) | ChaCha20 raw primitives |
-| [stream_audit](./stream_audit.md) | streaming AEAD composition audit |
-| [exports](./exports.md) | complete export reference |
-| [init](./init.md) | WASM loading and `WasmSource` |