leviathan-crypto 2.0.1 → 2.1.0

package/SECURITY.md

@@ -2,275 +2,162 @@
 
 <img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="Leviathan logo" width="100" align="left">
 
-- **[Version Support](#supported-versions)**
 - **[Security Posture](#security-posture)**
 - **[Cryptanalytic Audits](#cryptanalytic-audits)**
+- **[Supported Versions](#supported-versions)**
 - **[Vulnerability Reporting](#reporting-a-vulnerability)**
 
 ---
 
-## Supported Versions
+## Security posture
 
-| Version | Supported |
-| ------- | --------- |
-| v2.0.x  | ✓         |
-| v1.4.x  | ✗         |
-| v1.3.x  | ✗         |
-| v1.2.x  | ✗         |
-| v1.1.x  | ✗         |
-| v1.0.x  | ✗         |
+[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]
-> **All v1.x releases are deprecated.** Upgrading to v2 is strongly
-> recommended. v1.x releases will not receive security patches.
-
-> [!WARNING]
-> **v1.x known issues** (addressed in v2):
-> - Partial WASM buffer wipe on AEAD and serpent auth failure.
-> - HMAC tag and HKDF operations do not zero intermediate key material.
-> - TransformStream error paths leak derived keys.
-> - Pool workers copy result buffers.
-> - Scalar JS `constantTimeEqual` was "best-effort only".
-
-> [!WARNING]
-> **v2.0.0 known issue** (addressed in v2.0.1):
-> - `SealStreamPool` with `SerpentCipher` and `chunkSize: 65536` silently
->   produces corrupt plaintext on decrypt for inputs >= 65536 bytes. No
->   authentication error is raised. Upgrade to v2.0.1 immediately.
-
-## Security Posture
-
-[`leviathan-crypto`](https://leviathan.3xi.club) is a cryptography library.
-Security is not an afterthought, it is the primary design constraint at every
-layer of the stack.
-
-### Algorithm Correctness
-
-Every primitive in this library was implemented by hand in AssemblyScript
-against the authoritative specification for that algorithm:
-[FIPS 180-4][fips180] (SHA-2), [FIPS 202][fips202] (SHA-3),
-[FIPS 203][fips203] (ML-KEM),
-[RFC 8439][rfc8439] (ChaCha20-Poly1305), [RFC 2104][rfc2104] (HMAC),
-[RFC 5869][rfc5869] (HKDF), and the original
-[Serpent-256 specification][serpent] and S-box reference. No algorithm was
-ported from an existing implementation. The specs are always the source of truth.
-
-All implementations are verified against published known-answer test vectors
-from NIST, RFC appendices, NESSIE, and the Argon2 reference suite. Vectors
-are immutable: if an implementation produces incorrect output, the
-implementation is fixed and vectors are never adjusted to match code.
-
-### Side-Channel Resistance
-
-Serpent's S-boxes are implemented as Boolean gate circuits designed with no table
-lookups, no data-dependent memory access, and no data-dependent branches. Every
-bit is processed unconditionally on every block. This is the most
-timing-safe cipher implementation approach available in a WASM runtime,
-where JIT optimisation can otherwise introduce observable timing variation.
-
-All security-sensitive comparisons (e.g. MAC verification, padding validation)
-use [`constantTimeEqual`][utils], which is backed by a dedicated WASM SIMD module
-(v128 XOR accumulate + `any_true`) when WebAssembly SIMD is available. The WASM
-execution path eliminates JIT short-circuiting and speculative optimization as
-theoretical side-channel vectors. On runtimes without SIMD (sha2/sha3-only
-consumers), the function falls back to a JS XOR-accumulate loop. This is best-effort
-constant-time, not a hardware-level guarantee. WASM comparison memory is
-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 optimisation. Each primitive family compiles to its own
-isolated binary with its own linear memory. For example, 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 is applied on
-`init()` alongside serpent and chacha20. Its linear memory is independent
-from all other modules. The kyber module's constant-time path (FO transform
-decapsulation) uses dedicated `ct_verify` and `ct_cmov` functions implemented
-in the kyber WASM binary. The comparison never passes through JavaScript.
-
-### Cryptanalytic Audits
-
-All primitives undergo periodic cryptographic implementation reviews. See the [audit index][audits] for a full summary.
-
-| Primitive                      | Audit Description                                                                      |
-| ------------------------------ | -------------------------------------------------------------------------------------- |
-| [serpent_audit][serpent_audit] | Correctness verification, side-channel analysis, cryptanalytic attack paper review     |
-| [chacha_audit][chacha_audit]   | XChaCha20-Poly1305 correctness, Poly1305 field arithmetic, HChaCha20 nonce extension   |
-| [sha2_audit][sha2_audit]       | SHA-256/512/384 correctness, HMAC and HKDF composition, constant verification          |
-| [sha3_audit][sha3_audit]       | Keccak permutation correctness, θ/ρ/π/χ/ι step verification, round constant derivation |
-| [hmac_audit][hmac_audit]       | HMAC-SHA256/512/384 construction, key processing, RFC 4231 vector coverage             |
-| [hkdf_audit][hkdf_audit]       | HKDF extract-then-expand, info field domain separation, stream key derivation          |
-| [kyber_audit][kyber_audit]     | ML-KEM FIPS 203 correctness, NTT/Montgomery/Barrett verification, FO transform CT analysis, ACVP validation |
-| [stream_audit][stream_audit]   | Streaming AEAD composition, counter nonce binding, final-chunk detection, key wipe paths |
-
-#### Additional Serpent-256 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`][biclique]
-
-### 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` uses encrypt-then-MAC
-(SerpentCbc + HMAC-SHA256). MAC verification is the unconditional gate on
-the open path. Decryption is unreachable until that 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` uses XChaCha20-Poly1305
-AEAD per chunk. The Poly1305 tag is verified inside the WASM `aeadDecrypt`
-call before any plaintext is produced. On authentication failure, the full
-chunk output buffer is wiped and plaintext bytes are never returned.
-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 kills all workers, wipes all key material, and marks the pool dead. No retry, no partial results.
-
-### Dependency Management
-
-The 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`][argon2id-wiki].
-
-Build toolchain dependencies are pinned with exact version locks in
-`bun.lock`. GitHub Actions workflows use [SHA-pinned action references][workflows]
-throughout with no floating tags. Supply chain integrity is treated as a
-first-class concern for a cryptography library.
-
-### Explicit Initialisation
-
-No class silently auto-initialises. The [`init()`][init] gate is mandatory and
-explicit, giving consumers full control over when WASM modules are loaded
-and ensuring no hidden initialisation costs or race conditions. Classes
-throw immediately if used before initialisation rather than failing
-silently.
-
-### Agentic Development Contracts
-
-All AI-assisted development on this repository operates under a strict
-agentic contract defined in [`AGENTS.md`][agents]. 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/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 present in the repository and all route to [`AGENTS.md`][agents]
-as the single source of authority.
+> 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
+## Reporting a vulnerability
 
 > [!IMPORTANT]
-> **_Please do not open a public issue for security vulnerabilities._**
+> Do not open a public issue for security vulnerabilities.
 
-### Private Advisory (preferred)
+### Private advisory (preferred)
 
-Use GitHub's private vulnerability reporting form:
-[https://github.com/xero/leviathan-crypto/security/advisories/new][advisory]
+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 will collaborate to fully understand the issue, including a review of
-proposed fixes, so you can track and validate firsthand. Before any public
-advisory is published, we will 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.
+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
+### Direct contact
 
-If you prefer to contact the maintainer directly:
+If you prefer direct contact:
 
-- **Email:** x﹫xero.style · PGP: [`0xAC1D0000`][pgp]
+- **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.
-
-### Scope
+> Encrypted communication is welcome and preferred for sensitive reports.
 
-**Reports are in scope for:**
+### 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)
+- 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:**
+### Out of scope
 
-- Vulnerabilities in third-party packages not maintained by this project.
-  This includes optional peer dependencies such as argon2id.
-  Please report those directly to their maintainers.
+- 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 (e.g. complexity
-  improvements that remain computationally infeasible)
-- Issues in the demo applications that do not affect the core library.
-  Please open an issue in the [`leviathan-demos`][demos] repository instead.
-
-[fips180]:        https://csrc.nist.gov/publications/detail/fips/180/4/final
-[fips202]:        https://csrc.nist.gov/publications/detail/fips/202/final
-[fips203]:        https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf
-[rfc8439]:        https://www.rfc-editor.org/rfc/rfc8439
-[rfc2104]:        https://www.rfc-editor.org/rfc/rfc2104
-[rfc5869]:        https://www.rfc-editor.org/rfc/rfc5869
-[serpent]:        https://www.cl.cam.ac.uk/~rja14/Papers/serpent.pdf
-[utils]:          https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal
-[demos]:          https://github.com/xero/leviathan-demos/
-[serpent_audit]:  https://github.com/xero/leviathan-crypto/wiki/serpent_audit
-[chacha_audit]:   https://github.com/xero/leviathan-crypto/wiki/chacha_audit
-[sha2_audit]:     https://github.com/xero/leviathan-crypto/wiki/sha2_audit
-[sha3_audit]:     https://github.com/xero/leviathan-crypto/wiki/sha3_audit
-[hmac_audit]:     https://github.com/xero/leviathan-crypto/wiki/hmac_audit
-[hkdf_audit]:     https://github.com/xero/leviathan-crypto/wiki/hkdf_audit
-[kyber_audit]:    https://github.com/xero/leviathan-crypto/wiki/kyber_audit
-[stream_audit]:   https://github.com/xero/leviathan-crypto/wiki/stream_audit
-[audits]:         https://github.com/xero/leviathan-crypto/wiki/audits
-[biclique]:       https://github.com/xero/BicliqueFinder/blob/main/biclique-research.md
-[argon2id-wiki]:  https://github.com/xero/leviathan-crypto/wiki/argon2id
-[workflows]:      https://github.com/xero/leviathan-crypto/blob/main/scripts/pin-actions.ts
-[init]:           https://github.com/xero/leviathan-crypto/wiki/init
-[agents]:         https://github.com/xero/leviathan-crypto/blob/main/AGENTS.md
-[advisory]:       https://github.com/xero/leviathan-crypto/security/advisories/new
-[pgp]:            https://0w.nz/pgp.pub
+- 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/chacha20/cipher-suite.d.ts

@@ -1,4 +1,14 @@
 import type { CipherSuite } from '../stream/types.js';
+/**
+ * `CipherSuite` implementation for the stream construction using XChaCha20-Poly1305.
+ *
+ * Each chunk is encrypted with ChaCha20-Poly1305 using a HChaCha20 subkey
+ * derived via HKDF-SHA-256 + HChaCha20. This is the recommended cipher suite
+ * for `SealStream` / `OpenStream` / `SealStreamPool`.
+ *
+ * Pass to `SealStream` / `OpenStream` / `SealStreamPool` instead of constructing
+ * this object directly. Use `XChaCha20Cipher.keygen()` to generate a 32-byte key.
+ */
 export declare const XChaCha20Cipher: CipherSuite & {
     keygen(): Uint8Array;
 };

package/dist/chacha20/cipher-suite.js

@@ -23,14 +23,26 @@
 //
 // XChaCha20Cipher — CipherSuite implementation for the STREAM construction.
 // HKDF-SHA-256 key derivation → HChaCha20 subkey → ChaCha20-Poly1305 per chunk.
-import { getInstance } from '../init.js';
+import { getInstance, _assertNotOwned } from '../init.js';
 import { HKDF_SHA256 } from '../sha2/index.js';
 import { aeadEncrypt, aeadDecrypt, deriveSubkey } from './ops.js';
 import { wipe, randomBytes } from '../utils.js';
+import { WORKER_SOURCE } from '../embedded/chacha20-pool-worker.js';
 const INFO = new TextEncoder().encode('xchacha20-sealstream-v2');
+/** Returns the raw chacha20 WASM export object. @internal */
 function getExports() {
     return getInstance('chacha20').exports;
 }
+/**
+ * `CipherSuite` implementation for the stream construction using XChaCha20-Poly1305.
+ *
+ * Each chunk is encrypted with ChaCha20-Poly1305 using a HChaCha20 subkey
+ * derived via HKDF-SHA-256 + HChaCha20. This is the recommended cipher suite
+ * for `SealStream` / `OpenStream` / `SealStreamPool`.
+ *
+ * Pass to `SealStream` / `OpenStream` / `SealStreamPool` instead of constructing
+ * this object directly. Use `XChaCha20Cipher.keygen()` to generate a 32-byte key.
+ */
 export const XChaCha20Cipher = {
     formatEnum: 0x01,
     formatName: 'xchacha20',
@@ -41,10 +53,19 @@ export const XChaCha20Cipher = {
     padded: false,
     wasmChunkSize: 65536, // src/asm/chacha20/buffers.ts CHUNK_SIZE
     wasmModules: ['chacha20'],
+    /** Generate a random 32-byte master key suitable for use with `XChaCha20Cipher`. @returns 32 cryptographically random bytes */
     keygen() {
         return randomBytes(32);
     },
+    /**
+     * Derive a 32-byte HChaCha20 subkey from `masterKey` and `nonce` via
+     * HKDF-SHA-256 followed by HChaCha20 subkey derivation.
+     * @param masterKey  32-byte master key
+     * @param nonce      Stream nonce (24 bytes minimum for XChaCha20 subkey derivation)
+     * @returns          `DerivedKeys` holding the 32-byte subkey
+     */
     deriveKeys(masterKey, nonce, _kemCt) {
+        _assertNotOwned('chacha20');
         const hkdf = new HKDF_SHA256();
         const streamKey = hkdf.derive(masterKey, nonce, INFO, 32);
         hkdf.dispose();
@@ -54,7 +75,17 @@ export const XChaCha20Cipher = {
         wipe(streamKey);
         return { bytes: subkey };
     },
+    /**
+     * Encrypt and authenticate one stream chunk with ChaCha20-Poly1305.
+     * Output: ciphertext || 16-byte Poly1305 tag.
+     * @param keys         Derived keys from `deriveKeys`
+     * @param counterNonce 12-byte per-chunk nonce (unique per chunk in the stream)
+     * @param chunk        Plaintext chunk
+     * @param aad          Optional additional authenticated data
+     * @returns            Authenticated ciphertext
+     */
     sealChunk(keys, counterNonce, chunk, aad) {
+        _assertNotOwned('chacha20');
         const x = getExports();
         const { ciphertext, tag } = aeadEncrypt(x, keys.bytes, counterNonce, chunk, aad ?? new Uint8Array(0));
         const out = new Uint8Array(ciphertext.length + 16);
@@ -62,7 +93,16 @@ export const XChaCha20Cipher = {
         out.set(tag, ciphertext.length);
         return out;
     },
+    /**
+     * Verify and decrypt one stream chunk. Throws `AuthenticationError` on tag mismatch.
+     * @param keys         Derived keys from `deriveKeys`
+     * @param counterNonce 12-byte per-chunk nonce — must match the value used by `sealChunk`
+     * @param chunk        Ciphertext || 16-byte Poly1305 tag
+     * @param aad          Optional additional authenticated data
+     * @returns            Plaintext
+     */
     openChunk(keys, counterNonce, chunk, aad) {
+        _assertNotOwned('chacha20');
         if (chunk.length < 16)
             throw new RangeError(`chunk too short for 16-byte tag (got ${chunk.length})`);
         const x = getExports();
@@ -70,10 +110,33 @@ export const XChaCha20Cipher = {
         const tag = chunk.subarray(chunk.length - 16);
         return aeadDecrypt(x, keys.bytes, counterNonce, ct, tag, aad ?? new Uint8Array(0), 'xchacha20-poly1305');
     },
+    /**
+     * Zero all derived key material in `keys`. Called by the stream layer on
+     * teardown and after auth failure.
+     * @param keys  Derived keys to wipe
+     */
     wipeKeys(keys) {
         wipe(keys.bytes);
     },
+    /**
+     * Spawn an XChaCha20 pool worker from the embedded IIFE bundle.
+     * The worker holds its own chacha20 WASM instance and derived subkey.
+     * @returns  Newly constructed `Worker` instance
+     */
     createPoolWorker() {
-        return new Worker(new URL('./pool-worker.js', import.meta.url), { type: 'module' });
+        // IIFE source is bundled at lib build time (scripts/embed-workers.ts).
+        // Avoids the syntactic `new Worker(new URL(..., import.meta.url))`
+        // pattern that triggers eager worker-chunk emission in Vite's
+        // transform hook (issue.md). Classic worker via blob URL —
+        // module workers fail on file:// in Chromium (issue2.md).
+        const blob = new Blob([WORKER_SOURCE], { type: 'application/javascript' });
+        const url = URL.createObjectURL(blob);
+        const w = new Worker(url);
+        // Worker spec fetches the URL synchronously at construction. Revoke
+        // in a macrotask so the spawn completes first; releases the Blob
+        // (~5 KB per spawn × N workers) instead of leaking it for the
+        // document's lifetime.
+        setTimeout(() => URL.revokeObjectURL(url), 0);
+        return w;
     },
 };

package/dist/chacha20/generator.d.ts

@@ -0,0 +1,12 @@
+import type { Generator } from '../types.js';
+/**
+ * ChaCha20 counter-mode PRF for Fortuna's generator slot.
+ *
+ * The 32-bit counter is read from `counter` as a little-endian u32. Each call
+ * to `generate()` encrypts zero blocks to produce keystream output (RFC 8439 §2.3).
+ * The nonce is fixed to zero — Fortuna's counter is the only varying input.
+ *
+ * Pass to `Fortuna.create({ generator: ChaCha20Generator, ... })` — do not
+ * call `generate()` directly outside of Fortuna.
+ */
+export declare const ChaCha20Generator: Generator;

package/dist/chacha20/generator.js

@@ -0,0 +1,91 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/chacha20/generator.ts
+//
+// RFC 8439 §2.3 — ChaCha20 block function as PRF
+// ChaCha20 counter-mode PRF for Fortuna's generator slot.
+//
+// Counter is treated as a 32-bit LE integer. Fortuna's 4-byte genCnt provides
+// 2^32 blocks × 64 bytes = 256 GiB of output between reseeds.
+import { _assertNotOwned, getInstance } from '../init.js';
+/**
+ * ChaCha20 counter-mode PRF for Fortuna's generator slot.
+ *
+ * The 32-bit counter is read from `counter` as a little-endian u32. Each call
+ * to `generate()` encrypts zero blocks to produce keystream output (RFC 8439 §2.3).
+ * The nonce is fixed to zero — Fortuna's counter is the only varying input.
+ *
+ * Pass to `Fortuna.create({ generator: ChaCha20Generator, ... })` — do not
+ * call `generate()` directly outside of Fortuna.
+ */
+export const ChaCha20Generator = {
+    keySize: 32,
+    blockSize: 64,
+    counterSize: 4,
+    wasmModules: ['chacha20'],
+    /**
+     * Generate `n` pseudorandom bytes using ChaCha20 with a zero nonce.
+     * @param key      32-byte ChaCha20 key
+     * @param counter  4-byte counter (little-endian u32)
+     * @param n        Number of bytes to generate (0 ≤ n ≤ 2^30)
+     * @returns        `n` pseudorandom bytes
+     */
+    generate(key, counter, n) {
+        _assertNotOwned('chacha20');
+        if (key.length !== 32)
+            throw new RangeError(`ChaCha20Generator: key must be 32 bytes (got ${key.length})`);
+        if (counter.length !== 4)
+            throw new RangeError(`ChaCha20Generator: counter must be 4 bytes (got ${counter.length})`);
+        if (!Number.isSafeInteger(n) || n < 0 || n > 2 ** 30)
+            throw new RangeError(`ChaCha20Generator: n must be a non-negative safe integer <= 2^30 (got ${n})`);
+        const x = getInstance('chacha20').exports;
+        const c = new DataView(counter.buffer, counter.byteOffset, 4).getUint32(0, true);
+        const mem = new Uint8Array(x.memory.buffer);
+        try {
+            mem.set(key, x.getKeyOffset());
+            // Fixed zero nonce — Fortuna's counter is the only varying input
+            mem.fill(0, x.getChachaNonceOffset(), x.getChachaNonceOffset() + 12);
+            x.chachaSetCounter(c);
+            x.chachaLoadKey();
+            const output = new Uint8Array(n);
+            let remaining = n;
+            let outPos = 0;
+            const maxChunk = x.getChunkSize();
+            const ptOff = x.getChunkPtOffset();
+            const ctOff = x.getChunkCtOffset();
+            while (remaining > 0) {
+                const chunkLen = Math.min(remaining, maxChunk);
+                mem.fill(0, ptOff, ptOff + chunkLen);
+                x.chachaEncryptChunk_simd(chunkLen);
+                output.set(mem.subarray(ctOff, ctOff + chunkLen), outPos);
+                outPos += chunkLen;
+                remaining -= chunkLen;
+            }
+            return output;
+        }
+        finally {
+            // Wipe the WASM key/state/keystream scratch so secret-derived bytes
+            // do not outlive this call in the shared chacha20 linear memory.
+            x.wipeBuffers();
+        }
+    },
+};