leviathan-crypto 2.0.0 → 2.1.0

package/dist/chacha20/pool-worker.js

@@ -8,6 +8,17 @@ import { aeadEncrypt, aeadDecrypt } from './ops.js';
 import { AuthenticationError } from '../errors.js';
 let x;
 let subkey;
+/**
+ * Message handler for the XChaCha20 pool worker.
+ *
+ * Accepts three message types:
+ * - `'init'`  — instantiate the chacha20 WASM module and store the derived subkey
+ * - `'wipe'`  — zero subkey and WASM buffers, then post `{ type: 'wiped' }`
+ * - `{ op: 'seal' | 'open', ... }` — encrypt or decrypt one chunk
+ *
+ * Replies with `{ type: 'result', id, data }` on success or
+ * `{ type: 'error', id, message, isAuthError }` on failure.
+ */
 self.onmessage = async (e) => {
     const msg = e.data;
     if (msg.type === 'init') {
@@ -34,6 +45,7 @@ self.onmessage = async (e) => {
         if (x)
             x.wipeBuffers();
         x = undefined;
+        self.postMessage({ type: 'wiped' });
         return;
     }
     if (!x || !subkey) {

package/dist/chacha20/types.d.ts

@@ -1,32 +1 @@
-/** WASM exports for the chacha module */
-export interface ChaChaExports {
-    memory: WebAssembly.Memory;
-    getModuleId(): number;
-    getKeyOffset(): number;
-    getChachaNonceOffset(): number;
-    getChachaCtrOffset(): number;
-    getChachaBlockOffset(): number;
-    getChachaStateOffset(): number;
-    getChunkPtOffset(): number;
-    getChunkCtOffset(): number;
-    getChunkSize(): number;
-    getPolyKeyOffset(): number;
-    getPolyMsgOffset(): number;
-    getPolyTagOffset(): number;
-    getPolyBufLenOffset(): number;
-    getXChaChaNonceOffset(): number;
-    getXChaChaSubkeyOffset(): number;
-    chachaLoadKey(): void;
-    chachaSetCounter(n: number): void;
-    chachaResetCounter(): void;
-    chachaEncryptChunk(n: number): number;
-    chachaDecryptChunk(n: number): number;
-    chachaEncryptChunk_simd(n: number): number;
-    chachaDecryptChunk_simd(n: number): number;
-    chachaGenPolyKey(): void;
-    hchacha20(): void;
-    polyInit(): void;
-    polyUpdate(n: number): void;
-    polyFinal(): void;
-    wipeBuffers(): void;
-}
+export {};

package/dist/ct-wasm.js

@@ -1,3 +1,3 @@
 // 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, 2, 16, 1, 3, 101, 110, 118, 6, 109, 101, 109, 111, 114, 121, 2, 1, 1, 1, 3, 2, 1, 0, 7, 20, 2, 7, 99, 111, 109, 112, 97, 114, 101, 0, 0, 6, 109, 101, 109, 111, 114, 121, 2, 0, 10, 111, 1, 109, 2, 3, 127, 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, 45, 0, 0, 32, 1, 32, 3, 106, 45, 0, 0, 115, 114, 33, 5, 32, 3, 65, 1, 106, 33, 3, 12, 1, 11, 11, 32, 6, 253, 83, 4, 64, 65, 0, 15, 11, 32, 5, 69, 11]);
+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,7 +1,8 @@
-# Authenticated Encryption
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="logo" width="120" align="left" margin="10">
 
-> [!NOTE]
-> 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`.
+### 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)
@@ -13,11 +14,11 @@
 
 ## Overview
 
-`Seal`, `SealStream`, `OpenStream`, and `SealStreamPool` are the primary API for authenticated encryption in leviathan-crypto. They are cipher-agnostic: you pass a `CipherSuite` object at construction and the implementation handles key derivation, nonce management, and authentication for you.
+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.
 
-The four classes form a natural progression. `Seal` handles data that fits in memory. `SealStream` and `OpenStream` handle data that arrives in chunks or is too large to buffer. `SealStreamPool` parallelizes the chunked approach across Web Workers. All four produce and consume the same wire format, so a `Seal` blob can be opened by `OpenStream` and vice versa.
+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.
 
-Two cipher suites are included. A third wraps either with ML-KEM for post-quantum hybrid encryption.
+leviathan-crypto includes two cipher suites. A third suite wraps either with ML-KEM for post-quantum hybrid encryption.
 
 | Suite | Cipher | Tag | Modules |
 |---|---|---|---|
@@ -33,16 +34,28 @@ See [ciphersuite.md](./ciphersuite.md) for full cipher suite documentation.
 
 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 is individually authenticated. A tampered chunk is rejected immediately without decrypting anything that follows.
+**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`). Truncating the stream by dropping the final chunk is detected because the opener expects a chunk marked final.
+**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
 
@@ -119,7 +132,10 @@ const pt   = Seal.decrypt(XChaCha20Cipher, key, blob)  // throws AuthenticationE
 | `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`. Additional Authenticated Data: authenticated but not encrypted. Pass the same value to both `encrypt` and `decrypt`.
+**`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.
 
 ---
 
@@ -181,7 +197,7 @@ 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.
+Throws if the preamble format enum doesn't match the cipher or if the preamble is too short.
 
 | Parameter | Type | Description |
 |---|---|---|
@@ -193,9 +209,12 @@ Throws if the preamble format enum doesn't match the cipher, or if the preamble
 |---|---|---|
 | `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`. Enables random access decryption. Must be a non-negative integer. |
+| `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
@@ -221,7 +240,7 @@ const decrypted  = await pool.open(ciphertext)
 pool.destroy()
 ```
 
-**`SealStreamPool.create(cipher, key, opts)`** — async factory.
+**`SealStreamPool.create(cipher, key, opts)`.** Async factory.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
@@ -231,7 +250,10 @@ pool.destroy()
 | `framed` | `boolean` | `false` | Framed mode. |
 | `jobTimeout` | `number` | `30000` | Per-job timeout in ms. |
 
-**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.
+> [!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 |
 |---|---|
@@ -242,6 +264,24 @@ pool.destroy()
 | `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
@@ -288,7 +328,7 @@ AAD applies per chunk, not per stream. Each chunk can carry different AAD. If yo
 
 ### AuthenticationError
 
-`AuthenticationError` is thrown by `Seal.decrypt()`, `OpenStream.pull()`, `OpenStream.finalize()`, and `SealStreamPool.open()` when authentication fails. It extends `Error` and carries the cipher name in the message.
+`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'
@@ -306,15 +346,18 @@ Never attempt to recover plaintext after an `AuthenticationError`. The stream la
 
 ---
 
-> ## 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
-> - [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`
+
+## 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` |