leviathan-crypto 2.0.0 → 2.1.0

package/dist/docs/types.md

@@ -1,11 +1,14 @@
-# TypeScript Interfaces
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="logo" width="120" align="left" margin="10">
 
-> [!NOTE]
-> Defines the abstract interfaces all leviathan-crypto cryptographic classes implement. These are type-only exports; they contain no runtime code and generate no JavaScript output.
+### TypeScript Interfaces
+
+Defines the abstract interfaces all leviathan-crypto cryptographic classes implement. These are type-only exports; they contain no runtime code and generate no JavaScript output.
 
 > ### Table of Contents
 > - [API Reference](#api-reference)
 > - [Usage Examples](#usage-examples)
+> - [Generator](#generator)
+> - [HashFn](#hashfn)
 > - [WasmSource](#wasmsource)
 > - [CipherSuite](#ciphersuite)
 > - [DerivedKeys](#derivedkeys)
@@ -188,6 +191,60 @@ function cleanup(ctx: EncryptionContext): void {
 
 ---
 
+## Generator
+
+```typescript
+interface Generator {
+  readonly keySize: number;       // bytes
+  readonly blockSize: number;     // bytes per cipher block
+  readonly counterSize: number;   // bytes
+  readonly wasmModules: readonly string[];
+  generate(key: Uint8Array, counter: Uint8Array, n: number): Uint8Array;
+}
+```
+
+Stateless cipher PRF. Used by `Fortuna` as the generator slot.
+Implementations are plain const objects; they assert that no stateful
+instance owns the underlying WASM module before each call but do not
+acquire it themselves.
+
+| Member | Description |
+|---|---|
+| `keySize` | Generator key size in bytes. Must equal the paired `HashFn.outputSize` when used with `Fortuna`. |
+| `blockSize` | Bytes per cipher block. Used by `Fortuna` to compute counter advancement. |
+| `counterSize` | Counter width in bytes. `Fortuna` allocates its `genCnt` of this size. |
+| `wasmModules` | List of WASM module names the generator depends on. Used for `init()` preflight in `Fortuna.create()`. |
+| `generate(key, counter, n)` | Produces `n` bytes of keystream from `(key, counter)`. Stateless; does not mutate either input. |
+
+Shipped implementations: `SerpentGenerator` (from `'leviathan-crypto/serpent'`), `ChaCha20Generator` (from `'leviathan-crypto/chacha20'`).
+
+---
+
+## HashFn
+
+```typescript
+interface HashFn {
+  readonly outputSize: number;    // bytes
+  readonly wasmModules: readonly string[];
+  digest(msg: Uint8Array): Uint8Array;
+}
+```
+
+Stateless hash function. Used by `Fortuna` for the accumulator chain and
+the reseed key derivation. Distinct from the existing `Hash` interface
+above, which describes class-shaped instances that own scratch state and
+require `dispose()`.
+
+| Member | Description |
+|---|---|
+| `outputSize` | Digest size in bytes. Must equal the paired `Generator.keySize` when used with `Fortuna`. |
+| `wasmModules` | List of WASM module names the hash depends on. |
+| `digest(msg)` | Produces a digest of the input. Stateless; safe to call concurrently with itself within a single JavaScript turn. |
+
+Shipped implementations: `SHA256Hash` (from `'leviathan-crypto/sha2'`), `SHA3_256Hash` (from `'leviathan-crypto/sha3'`).
+
+---
+
 ## WasmSource
 
 Union type for WASM module sources. Accepted by `init()`, `serpentInit()`, etc.
@@ -210,15 +267,16 @@ Cipher-specific logic injected into `SealStream` and `OpenStream`.
 | `kemCtSize` | `number` | KEM ciphertext byte length appended to the header in the preamble. `0` for symmetric suites |
 | `tagSize` | `number` | Authentication tag size in bytes |
 | `padded` | `boolean` | Whether ciphertext includes padding (PKCS7 for CBC) |
+| `wasmChunkSize` | `number` | WASM buffer capacity for one padded chunk. `SealStreamPool.create()` validates `paddedFull ≤ wasmChunkSize` at startup for padded ciphers and throws `RangeError` if the check fails. `SerpentCipher`: 65552. `XChaCha20Cipher`: 65536. `KyberSuite` forwards from its inner cipher. |
 | `wasmModules` | `readonly string[]` | Cipher-specific WASM modules used by pool workers and per-chunk operations (not transitive dependencies such as HKDF-SHA-256 used by `deriveKeys()`) |
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `deriveKeys` | `(masterKey, nonce) → DerivedKeys` | HKDF key derivation |
+| `deriveKeys` | `(masterKey, nonce, kemCt?) → DerivedKeys` | HKDF key derivation. `kemCt` is the KEM ciphertext; present only for hybrid suites. |
 | `sealChunk` | `(keys, counterNonce, chunk, aad?) → Uint8Array` | Encrypt one chunk |
 | `openChunk` | `(keys, counterNonce, chunk, aad?) → Uint8Array` | Decrypt one chunk |
 | `wipeKeys` | `(keys) → void` | Zero derived key material |
-| `createPoolWorker` | `() → Worker` | Create a Web Worker for pool use |
+| `createPoolWorker` | `() → Worker` | Create a Web Worker for pool use. Default spawns a classic worker from a blob URL over a build-time IIFE; override via spread for strict-CSP environments. See [ciphersuite.md](./ciphersuite.md). |
 
 Implementations: `XChaCha20Cipher`, `SerpentCipher` (plain `const` objects, not classes), and `KyberSuite` (factory function returning a `CipherSuite`). See [ciphersuite.md](./ciphersuite.md).
 
@@ -235,6 +293,7 @@ Opaque key material returned by `CipherSuite.deriveKeys()`.
 | Field | Type | Description |
 |-------|------|-------------|
 | `bytes` | `readonly Uint8Array` | Raw derived key bytes (opaque to the stream layer) |
+| `kemCiphertext?` | `readonly Uint8Array \| undefined` | KEM ciphertext produced during encapsulation. Present only for hybrid KEM suites; absent for symmetric suites. |
 
 ---
 
@@ -263,13 +322,95 @@ Options for `SealStreamPool.create()`.
 
 ---
 
-> ## Cross-References
->
-> - [index](./README.md) — Project Documentation index
-> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
-> - [utils](./utils.md) — encoding utilities and `constantTimeEqual` for verifying MACs from `KeyedHash`
-> - [serpent](./serpent.md) — Serpent classes implement `Blockcipher`, `Streamcipher`, and `AEAD`
-> - [chacha20](./chacha20.md) — `XChaCha20Cipher` is a `CipherSuite` for `SealStream`/`OpenStream`/`Seal`; `Seal` provides one-shot AEAD over any `CipherSuite`; `ChaCha20`/`ChaCha20Poly1305`/`XChaCha20Poly1305` are stateless primitives
-> - [sha2](./sha2.md) — SHA-2 classes implement `Hash`; HMAC classes implement `KeyedHash`
-> - [sha3](./sha3.md) — SHA-3 classes implement `Hash`; SHAKE classes extend with XOF API
-> - [test-suite](./test-suite.md) — test suite structure and vector corpus
+## Ratchet types
+
+Shared types for the ratchet KDF module. See [ratchet.md](./ratchet.md) for full API.
+
+### MlKemLike
+
+Structural interface satisfied by `MlKem512`, `MlKem768`, and `MlKem1024`. Used as the `kem` parameter type for `kemRatchetEncap`, `kemRatchetDecap`, and `RatchetKeypair`.
+
+```typescript
+interface MlKemLike {
+  readonly params: KyberParams
+  keygen(): { encapsulationKey: Uint8Array; decapsulationKey: Uint8Array }
+  encapsulate(ek: Uint8Array): { ciphertext: Uint8Array; sharedSecret: Uint8Array }
+  decapsulate(dk: Uint8Array, ct: Uint8Array): Uint8Array
+}
+```
+
+### RatchetInitResult
+
+```typescript
+interface RatchetInitResult {
+  readonly nextRootKey:  Uint8Array  // 32 bytes
+  readonly sendChainKey: Uint8Array  // 32 bytes
+  readonly recvChainKey: Uint8Array  // 32 bytes
+}
+```
+
+### KemEncapResult
+
+```typescript
+interface KemEncapResult {
+  readonly nextRootKey:  Uint8Array  // 32 bytes
+  readonly sendChainKey: Uint8Array  // 32 bytes
+  readonly recvChainKey: Uint8Array  // 32 bytes
+  readonly kemCt:        Uint8Array  // ML-KEM ciphertext — transmit in-band
+}
+```
+
+### KemDecapResult
+
+```typescript
+interface KemDecapResult {
+  readonly nextRootKey:  Uint8Array  // 32 bytes
+  readonly sendChainKey: Uint8Array  // 32 bytes
+  readonly recvChainKey: Uint8Array  // 32 bytes
+}
+```
+
+### RatchetMessageHeader
+
+```typescript
+interface RatchetMessageHeader {
+  readonly epoch:   number        // sender's epoch at seal time; starts 0, increments on ratchet step
+  readonly counter: number        // KDFChain.n at seal time (post-step value, first message = 1)
+  readonly pn?:     number        // previous chain length — present only on the first message of a new epoch
+  readonly kemCt?:  Uint8Array    // ML-KEM ciphertext — present only on the first message of a new epoch (encap side)
+}
+```
+
+Canonical header shape for a ratchet-protected message. `pn` and `kemCt` are absent on every message except the first one of a new epoch, where both must be present together.
+
+### ResolveHandle
+
+Return type of `SkippedKeyStore.resolve()`.
+
+```typescript
+interface ResolveHandle {
+  readonly key: Uint8Array  // 32-byte message key — throws after settlement
+  commit():   void          // wipe key and mark settled — call on successful decrypt
+  rollback(): void          // return key to store and mark settled — call on auth failure
+}
+```
+
+`commit()` and `rollback()` are mutually exclusive; calling either a second time (or calling the other after settling) throws `Error: 'SkippedKeyStore: handle already settled'`. Accessing `.key` after settlement also throws. This enforces the delete-on-use contract: a key is consumed exactly once, either by committing (decrypt succeeded, key wiped) or rolling back (decrypt failed, key returned to the store for a future legitimate delivery at the same counter).
+
+---
+
+
+## Cross-References
+
+| Document | Description |
+| -------- | ----------- |
+| [index](./README.md) | Project Documentation index |
+| [architecture](./architecture.md) | architecture overview, module relationships, buffer layouts, and build pipeline |
+| [utils](./utils.md) | encoding utilities and `constantTimeEqual` for verifying MACs from `KeyedHash` |
+| [serpent](./serpent.md) | Serpent classes implement `Blockcipher`, `Streamcipher`, and `AEAD` |
+| [chacha20](./chacha20.md) | `XChaCha20Cipher` is a `CipherSuite` for `SealStream`/`OpenStream`/`Seal`; `Seal` provides one-shot AEAD over any `CipherSuite`; `ChaCha20`/`ChaCha20Poly1305`/`XChaCha20Poly1305` are stateless primitives |
+| [sha2](./sha2.md) | SHA-2 classes implement `Hash`; HMAC classes implement `KeyedHash` |
+| [sha3](./sha3.md) | SHA-3 classes implement `Hash`; SHAKE classes extend with XOF API |
+| [ratchet](./ratchet.md) | ratchet KDF primitives; `MlKemLike`, `RatchetInitResult`, `KemEncapResult`, `KemDecapResult`, `RatchetMessageHeader`, `ResolveHandle` |
+| [test-suite](./test-suite.md) | test suite structure and vector corpus |
+

package/dist/docs/utils.md

@@ -1,7 +1,8 @@
-# Utilities
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="logo" width="120" align="left" margin="10">
 
-> [!NOTE]
-> Pure TypeScript utilities that ship alongside the WASM-backed primitives. No `init()` call required; all functions work immediately on import.
+### Utilities
+
+Pure TypeScript utilities that ship alongside the WASM-backed primitives. No `init()` call required; all functions work immediately on import.
 
 > ### Table of Contents
 > - [Security Notes](#security-notes)
@@ -11,125 +12,201 @@
 
 ---
 
-The module covers encoding (hex, UTF-8, and base64 conversions between strings and `Uint8Array`), security (constant-time comparison and secure memory wiping), byte manipulation (XOR and concatenation), and random byte generation.
+The module covers encoding (hex, UTF-8, and base64 conversions between strings
+and `Uint8Array`), security (constant-time comparison and secure memory
+wiping), byte manipulation (XOR and concatenation), and random byte generation.
 
 ## Security Notes
 
-**`constantTimeEqual`** uses a WASM SIMD module when available to remove the JS JIT compiler from the timing picture, falling back to an XOR-accumulate loop on older runtimes. Use this function whenever you compare MACs, hashes, authentication tags, or any secret-derived values. Never use `===`, `Buffer.equals`, or a manual loop-with-break for security comparisons. Those leak timing information that attackers can exploit to recover secrets. Inputs are limited to [`CT_MAX_BYTES`](#ct_max_bytes) (32768 bytes) per side.
+**`constantTimeEqual`** runs inside a WASM SIMD module that removes the JS JIT
+compiler from the timing picture. Use this function whenever you compare MACs,
+hashes, authentication tags, or any secret-derived values. Never use `===`,
+`Buffer.equals`, or a manual loop-with-break for security comparisons. Those
+leak timing information that attackers can exploit to recover secrets. Inputs
+are limited to [`CT_MAX_BYTES`](#ct_max_bytes) (32768 bytes) per side.
 
-The length check in `constantTimeEqual` is not constant-time, because array length is non-secret in all standard protocols. If your use case treats length as secret, pad to equal length before comparing.
+The length check in `constantTimeEqual` is not constant-time, because array
+length is non-secret in all standard protocols. If your use case treats length
+as secret, pad to equal length before comparing.
 
-**`wipe`** zeroes a typed array in-place. Call it on keys, plaintext buffers, and any other sensitive data as soon as you are done with them. JavaScript's garbage collector does not guarantee timely or complete erasure of memory.
+**`wipe`** zeroes a typed array in-place. Call it on keys, plaintext buffers,
+and any other sensitive data as soon as you are done with them. JavaScript's
+garbage collector does not guarantee timely or complete erasure of memory.
 
-**`randomBytes`** delegates to `crypto.getRandomValues` (Web Crypto API), which is cryptographically secure in all modern browsers and Node.js 19+. It does not fall back to `Math.random` or any insecure source.
+**`randomBytes`** delegates to `crypto.getRandomValues` (Web Crypto API), which
+is cryptographically secure in all modern browsers and Node.js 19+. It does not
+fall back to `Math.random` or any insecure source.
 
-The encoding functions (`hexToBytes`, `bytesToHex`, `utf8ToBytes`, `bytesToUtf8`, `base64ToBytes`, `bytesToBase64`) perform no security-sensitive operations.
+The encoding functions (`hexToBytes`, `bytesToHex`, `utf8ToBytes`,
+`bytesToUtf8`, `base64ToBytes`, `bytesToBase64`) perform no security-sensitive
+operations.
 
 ---
 
 ## API Reference
 
-### hexToBytes
+### constantTimeEqual
 
 ```typescript
-hexToBytes(hex: string): Uint8Array
+constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean
 ```
 
-Converts a hex string to a `Uint8Array`. Accepts lowercase or uppercase characters. An optional `0x` or `0X` prefix is stripped automatically. Throws `RangeError` on odd-length input.
+Returns `true` if `a` and `b` contain identical bytes. Returns `false`
+immediately if the arrays differ in length (length is non-secret in all
+standard protocols).
+
+The comparison runs inside a WASM SIMD module, removing the JS JIT compiler
+from the timing picture. Speculative optimisation and branch prediction inside
+the engine cannot short-circuit the loop. This function requires WebAssembly
+SIMD; on runtimes without SIMD support it throws `Error: leviathan-crypto:
+constantTimeEqual requires WebAssembly SIMD — this runtime does not support it`
+at first call. SIMD has been a baseline feature of all major browsers and
+Node.js 16.4+ since 2021, and the library's symmetric and post-quantum
+primitives require SIMD already; this function tightens that posture
+consistently.
+
+The WASM module ORs the two 64-bit lanes of the SIMD accumulator into a scalar,
+then folds it to 0/1 via `~((diff | -diff) >> 63) & 1`. The only remaining
+observable control flow is the outer length check, which operates on non-secret
+input.
+
+**Zero-copy design.** The WASM module has no internal staging buffers. The
+wrapper writes `a` into WASM linear memory at offset 0 and `b` immediately
+after at offset `a.length`, then passes those two offsets directly to the
+`compare` function. No data is duplicated inside the WASM binary; the
+comparison reads in-place from the caller-owned positions. This eliminates an
+entire class of residual-data risk: there is no intermediate copy that outlives
+the operation.
+
+**Guaranteed memory zeroing.** After every comparison, the wrapper clears both
+input regions via `mem.fill(0, 0, a.length * 2)` inside a `finally` block. The
+wipe runs whether the comparison succeeds, throws, or is interrupted. Sensitive
+material written into WASM linear memory does not persist past the end of the
+call.
+
+WASM SIMD JITs do not guarantee cycle-level constant time; the branch-free tail
+is best-effort hardening against branch-prediction side channels. For
+defence-in-depth against timing attacks on tag comparisons, pair this primitive
+with an authenticated construction (`SerpentCipher`, `XChaCha20Cipher`) that
+terminates on mismatch with a generic error message.
+
+Maximum input size is [`CT_MAX_BYTES`](#ct_max_bytes) (32768 bytes) per side.
+Throws `RangeError` if either array exceeds this limit.
+
+See [asm_ct.md](./asm_ct.md) for the full WASM module reference, including the
+SIMD algorithm, reduction technique, instantiation model, and memory layout.
+
+Use this function when working with lower-level unauthenticated primitives or
+building custom authenticated protocols on top of the hashing and KDF APIs.
+Common cases:
+
+- **Encrypt-then-MAC with `SerpentCbc` or `SerpentCtr`.** If you use the
+  `dangerUnauthenticated` primitive directly and compute your own HMAC-SHA256
+  tag, compare that tag with `constantTimeEqual`. See the [example
+  below](#encrypt-then-mac-with-serpentcbc).
+- **Argon2id key verification.** When re-deriving an Argon2id hash to verify a
+  passphrase, the final comparison must be constant-time. See
+  [argon2id.md](./argon2id.md#password-hashing-and-verification) for the full
+  example.
+- **Custom HMAC protocols.** Any protocol where you derive a MAC with
+  `HMAC_SHA256` or `HMAC_SHA512` and compare it against a received value. See
+  [examples.md](./examples.md#hmac-sha256-message-authentication) for a
+  complete example.
 
 ---
 
-### bytesToHex
+### CT_MAX_BYTES
 
 ```typescript
-bytesToHex(bytes: Uint8Array): string
+const CT_MAX_BYTES: 32768
 ```
 
-Converts a `Uint8Array` to a lowercase hex string (no prefix).
-
----
+Maximum input size accepted by [`constantTimeEqual`](#constanttimeequal) per
+side, in bytes. Reflects the physical layout of the WASM comparison module: one
+64 KiB page of linear memory split equally between the two input buffers (32
+KiB each).
 
-### utf8ToBytes
+In practice the largest comparison performed anywhere in this library is a
+32-byte HMAC-SHA-256 tag. This limit only matters for custom protocols that
+compare unusually large values. Use this constant to guard your own inputs
+rather than hardcoding the magic number:
 
 ```typescript
-utf8ToBytes(str: string): Uint8Array
-```
+import { constantTimeEqual, CT_MAX_BYTES } from 'leviathan-crypto'
 
-Encodes a JavaScript string as UTF-8 bytes using the platform `TextEncoder`.
+if (a.length > CT_MAX_BYTES || b.length > CT_MAX_BYTES) {
+  throw new RangeError(`comparison input exceeds CT_MAX_BYTES (${CT_MAX_BYTES})`)
+}
+const match = constantTimeEqual(a, b)
+```
 
 ---
 
-### bytesToUtf8
+### hexToBytes
 
 ```typescript
-bytesToUtf8(bytes: Uint8Array): string
+hexToBytes(hex: string): Uint8Array
 ```
 
-Decodes UTF-8 bytes to a JavaScript string using the platform `TextDecoder`.
+Converts a hex string to a `Uint8Array`. Accepts lowercase or uppercase
+characters. An optional `0x` or `0X` prefix is stripped automatically. Throws
+`RangeError` on odd-length or non-hex input.
 
 ---
 
-### base64ToBytes
+### bytesToHex
 
 ```typescript
-base64ToBytes(b64: string): Uint8Array | undefined
+bytesToHex(bytes: Uint8Array): string
 ```
 
-Decodes a base64 or base64url string to a `Uint8Array`. Handles padded, unpadded, and legacy `%3d` padding. Unpadded base64url input is accepted (RFC 4648 §5). Returns `undefined` if the input is not valid base64 (illegal characters or `rem=1` length).
+Converts a `Uint8Array` to a lowercase hex string (no prefix).
 
 ---
 
-### bytesToBase64
+### utf8ToBytes
 
 ```typescript
-bytesToBase64(bytes: Uint8Array, url?: boolean): string
+utf8ToBytes(str: string): Uint8Array
 ```
 
-Encodes a `Uint8Array` to a base64 string. Pass `url = true` for base64url (RFC 4648 §5), which uses `-` and `_` instead of `+` and `/` with no padding characters. Defaults to standard base64.
+Encodes a JavaScript string as UTF-8 bytes using the platform `TextEncoder`.
 
 ---
 
-### constantTimeEqual
+### bytesToUtf8
 
 ```typescript
-constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean
+bytesToUtf8(bytes: Uint8Array): string
 ```
 
-Returns `true` if `a` and `b` contain identical bytes. Returns `false` immediately if the arrays differ in length (length is non-secret in all standard protocols).
-
-When WebAssembly SIMD is available the comparison runs inside a WASM module, removing the JS JIT compiler from the timing picture. Speculative optimisation and branch prediction inside the engine cannot short-circuit the loop. On runtimes without SIMD support the function falls back to an XOR-accumulate loop in JavaScript, which is best-effort but not a hardware-level guarantee. The overall posture is best-available constant-time, not a cryptographic proof of timing safety.
-
-Maximum input size is [`CT_MAX_BYTES`](#ct_max_bytes) (32768 bytes) per side. Throws `RangeError` if either array exceeds this limit.
-
-Use this function when working with lower-level unauthenticated primitives or building custom authenticated protocols on top of the hashing and KDF APIs. Three common cases:
-
-**Encrypt-then-MAC with `SerpentCbc` or `SerpentCtr`.** If you use the `dangerUnauthenticated` primitive directly and compute your own HMAC-SHA256 tag, compare that tag with `constantTimeEqual`. See the [example below](#encrypt-then-mac-with-serpentcbc).
-
-**Argon2id key verification.** When re-deriving an Argon2id hash to verify a passphrase, the final comparison must be constant-time. See [argon2id.md](./argon2id.md#password-hashing-and-verification) for the full example.
-
-**Custom HMAC protocols.** Any protocol where you derive a MAC with `HMAC_SHA256` or `HMAC_SHA512` and compare it against a received value. See [examples.md](./examples.md#hmac-sha256-message-authentication) for a complete example.
+Decodes UTF-8 bytes to a JavaScript string using the platform `TextDecoder`.
 
 ---
 
-### CT_MAX_BYTES
+### base64ToBytes
 
 ```typescript
-const CT_MAX_BYTES: 32768
+base64ToBytes(b64: string): Uint8Array
 ```
 
-Maximum input size accepted by [`constantTimeEqual`](#constanttimeequal) per side, in bytes. Reflects the physical layout of the WASM comparison module: one 64 KiB page of linear memory split equally between the two input buffers (32 KiB each).
+Decodes a base64 or base64url string to a `Uint8Array`. Handles padded,
+unpadded, and legacy `%3d` padding. Unpadded base64url input is accepted (RFC
+4648 §5). Throws `RangeError` if the input is not valid base64 (illegal
+characters or `rem=1` length).
 
-In practice the largest comparison performed anywhere in this library is a 32-byte HMAC-SHA-256 tag. This limit only matters for custom protocols that compare unusually large values. Use this constant to guard your own inputs rather than hardcoding the magic number:
+---
 
-```typescript
-import { constantTimeEqual, CT_MAX_BYTES } from 'leviathan-crypto'
+### bytesToBase64
 
-if (a.length > CT_MAX_BYTES || b.length > CT_MAX_BYTES) {
-  throw new RangeError(`comparison input exceeds CT_MAX_BYTES (${CT_MAX_BYTES})`)
-}
-const match = constantTimeEqual(a, b)
+```typescript
+bytesToBase64(bytes: Uint8Array, url?: boolean): string
 ```
 
+Encodes a `Uint8Array` to a base64 string. Pass `url = true` for base64url (RFC
+4648 §5), which uses `-` and `_` instead of `+` and `/` with no padding
+characters. Defaults to standard base64.
+
 ---
 
 ### wipe
@@ -138,7 +215,8 @@ const match = constantTimeEqual(a, b)
 wipe(data: Uint8Array | Uint16Array | Uint32Array): void
 ```
 
-Zeroes a typed array in-place by calling `fill(0)`. Use this to clear keys, plaintext, or any sensitive material when you are done with it.
+Zeroes a typed array in-place by calling `fill(0)`. Use this to clear keys,
+plaintext, or any sensitive material when you are done with it.
 
 ---
 
@@ -148,7 +226,8 @@ Zeroes a typed array in-place by calling `fill(0)`. Use this to clear keys, plai
 xor(a: Uint8Array, b: Uint8Array): Uint8Array
 ```
 
-Returns a new `Uint8Array` where each byte is `a[i] ^ b[i]`. Both arrays must have the same length. Throws `RangeError` if they differ.
+Returns a new `Uint8Array` where each byte is `a[i] ^ b[i]`. Both arrays must
+have the same length. Throws `RangeError` if they differ.
 
 ---
 
@@ -168,7 +247,8 @@ Concatenates one or more `Uint8Array`s into a new array.
 randomBytes(n: number): Uint8Array
 ```
 
-Returns `n` cryptographically secure random bytes via the Web Crypto API (`crypto.getRandomValues`).
+Returns `n` cryptographically secure random bytes via the Web Crypto API
+(`crypto.getRandomValues`).
 
 ---
 
@@ -182,13 +262,12 @@ Returns `true` if the current runtime supports WebAssembly SIMD (the `v128`
 type and associated operations). The result is computed once on first call by
 validating a minimal v128 WASM module, then cached for subsequent calls.
 
-`SerpentCtr.encryptChunk`, `SerpentCbc.decrypt`, and `ChaCha20.encryptChunk`
-call this internally to select the fast SIMD path at runtime. It is exported
-for informational purposes. You do not need to call it yourself. SIMD dispatch
-is fully automatic.
+A public utility for consumers who want to feature-detect before calling
+`init()`. The library requires SIMD for `serpent`, `chacha20`, and
+`constantTimeEqual`; calls into those modules throw a branded error on
+non-SIMD runtimes. `sha2` and `sha3` do not require SIMD.
 
-Supported in all modern browsers and Node.js 16+. Returns `false` in older
-environments, which fall back silently to the scalar path.
+Supported in all modern browsers and Node.js 16+.
 
 ---
 
@@ -229,14 +308,17 @@ console.log(b64url) // "bGV2aWF0aGFuLWNyeXB0bw"
 
 // Decoding (accepts both standard and url variants)
 const decoded = base64ToBytes(b64)
-if (decoded) console.log(bytesToUtf8(decoded)) // "leviathan-crypto"
+console.log(bytesToUtf8(decoded)) // "leviathan-crypto"
 ```
 
 ---
 
 ### Encrypt-then-MAC with SerpentCbc
 
-If you use `SerpentCbc` or `SerpentCtr` directly with `{ dangerUnauthenticated: true }`, you are responsible for authentication. The correct pattern is Encrypt-then-MAC: encrypt first, then compute HMAC-SHA256 over the ciphertext, and use `constantTimeEqual` to verify on decrypt.
+If you use `SerpentCbc` or `SerpentCtr` directly with `{ dangerUnauthenticated:
+true }`, you are responsible for authentication. The correct pattern is
+Encrypt-then-MAC: encrypt first, then compute HMAC-SHA256 over the ciphertext,
+and use `constantTimeEqual` to verify on decrypt.
 
 ```typescript
 import {
@@ -288,7 +370,10 @@ wipe(expectedTag)
 ```
 
 > [!NOTE]
-> `Seal` with `SerpentCipher` does all of this for you — key derivation, IV handling, Encrypt-then-MAC, and constant-time verification — with no manual steps. The pattern above is only relevant if you need direct access to the raw `SerpentCbc` primitive.
+> `Seal` with `SerpentCipher` does all of this for you; key derivation, IV
+> handling, Encrypt-then-MAC, and constant-time verification, with no manual
+> steps. The pattern above is only relevant if you need direct access to the
+> raw `SerpentCbc` primitive.
 
 ---
 
@@ -343,8 +428,8 @@ console.log(combined.length) // 32
 | Function | Condition | Behavior |
 |---|---|---|
 | `hexToBytes` | Odd-length string | Throws `RangeError` |
-| `hexToBytes` | Invalid hex characters | Bytes decode as `NaN` -> `0` |
-| `base64ToBytes` | Invalid length or characters | Returns `undefined` |
+| `hexToBytes` | Invalid hex characters | Throws `RangeError` |
+| `base64ToBytes` | Invalid length or characters | Throws `RangeError` |
 | `constantTimeEqual` | Arrays differ in length | Returns `false` immediately |
 | `constantTimeEqual` | Either array exceeds `CT_MAX_BYTES` | Throws `RangeError` |
 | `xor` | Arrays differ in length | Throws `RangeError` |
@@ -353,15 +438,20 @@ console.log(combined.length) // 32
 
 ---
 
-> ## Cross-References
->
-> - [index](./README.md) — Project Documentation index
-> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
-> - [serpent](./serpent.md) — Serpent modes consume keys from `randomBytes`; wrappers use `wipe` and `constantTimeEqual`
-> - [chacha20](./chacha20.md) — ChaCha20/Poly1305 classes use `randomBytes` for nonce generation
-> - [sha2](./sha2.md) — SHA-2 and HMAC classes; output often converted with `bytesToHex`
-> - [sha3](./sha3.md) — SHA-3 and SHAKE classes; output often converted with `bytesToHex`
-> - [argon2id](./argon2id.md) — passphrase-based encryption; uses `constantTimeEqual` for hash verification
-> - [examples](./examples.md) — full HMAC-SHA256 custom protocol example using `constantTimeEqual`
-> - [types](./types.md) — public interfaces whose implementations rely on these utilities
-> - [test-suite](./test-suite.md) — test suite structure and vector corpus
+
+## Cross-References
+
+| Document | Description |
+| -------- | ----------- |
+| [index](./README.md) | Project Documentation index |
+| [architecture](./architecture.md) | architecture overview, module relationships, buffer layouts, and build pipeline |
+| [asm_ct](./asm_ct.md) | WASM module reference for `constantTimeEqual`: SIMD algorithm, zero-copy layout, instantiation model, and memory zeroing |
+| [serpent](./serpent.md) | Serpent modes consume keys from `randomBytes`; wrappers use `wipe` and `constantTimeEqual` |
+| [chacha20](./chacha20.md) | ChaCha20/Poly1305 classes use `randomBytes` for nonce generation |
+| [sha2](./sha2.md) | SHA-2 and HMAC classes; output often converted with `bytesToHex` |
+| [sha3](./sha3.md) | SHA-3 and SHAKE classes; output often converted with `bytesToHex` |
+| [argon2id](./argon2id.md) | passphrase-based encryption; uses `constantTimeEqual` for hash verification |
+| [examples](./examples.md) | full HMAC-SHA256 custom protocol example using `constantTimeEqual` |
+| [types](./types.md) | public interfaces whose implementations rely on these utilities |
+| [test-suite](./test-suite.md) | test suite structure and vector corpus |
+

package/dist/embedded/chacha20-pool-worker.d.ts

@@ -0,0 +1 @@
+export declare const WORKER_SOURCE = "\"use strict\";(()=>{var U=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]);var v=null,k=null,O=!1,A=null,T=32768;function P(){if(O){if(A)throw A;return}if(O=!0,!R())throw A=new Error(\"leviathan-crypto: constantTimeEqual requires WebAssembly SIMD \\u2014 this runtime does not support it\"),A;try{let t=U.buffer.slice(U.byteOffset,U.byteOffset+U.byteLength),r=new WebAssembly.Module(t),e=new WebAssembly.Instance(r).exports;k=e.memory,v=e.compare}catch(t){throw A=new Error(`leviathan-crypto: ct WASM module failed to instantiate: ${t.message}`),A}}var B=(t,r)=>{if(t.length!==r.length)return!1;if(t.length>T)throw new RangeError(`constantTimeEqual: max ${T} bytes (got ${t.length})`);P();let n=k,e=v;if(!n||!e)throw new Error(\"leviathan-crypto: ct init invariant violated\");let o=new Uint8Array(n.buffer);o.set(t,0),o.set(r,t.length);try{return e(0,t.length,t.length)===1}finally{o.fill(0,0,t.length*2)}};var m=null;function R(){if(m!==null)return m;if(typeof WebAssembly>\"u\"||typeof WebAssembly.validate!=\"function\")return m=!1,m;try{m=WebAssembly.validate(new Uint8Array([0,97,115,109,1,0,0,0,1,5,1,96,0,1,123,3,2,1,0,10,10,1,8,0,65,0,253,15,253,98,11]))}catch{m=!1}return m}var d=class t extends Error{constructor(r){super(`${r}: authentication failed`),this.name=\"AuthenticationError\",Object.setPrototypeOf(this,t.prototype)}};function l(t,r){if(r.length===0)return;let n=new Uint8Array(t.memory.buffer),e=t.getPolyMsgOffset(),o=0;for(;o<r.length;){let a=Math.min(64,r.length-o);n.set(r.subarray(o,o+a),e),t.polyUpdate(a),o+=a}}function M(t,r){let n=new Uint8Array(16),e=new DataView(n.buffer);return e.setUint32(0,t>>>0,!0),e.setUint32(4,Math.floor(t/4294967296)>>>0,!0),e.setUint32(8,r>>>0,!0),e.setUint32(12,Math.floor(r/4294967296)>>>0,!0),n}function W(t,r,n,e,o){let a=t.getChunkSize();if(e.length>a)throw new RangeError(`plaintext exceeds ${a} bytes \\u2014 split into smaller chunks`);let u=new Uint8Array(t.memory.buffer);u.set(r,t.getKeyOffset()),u.set(n,t.getChachaNonceOffset()),t.chachaLoadKey(),t.chachaGenPolyKey(),t.polyInit(),l(t,o);let f=(16-o.length%16)%16;f>0&&l(t,new Uint8Array(f)),t.chachaSetCounter(1),u.set(e,t.getChunkPtOffset()),t.chachaEncryptChunk_simd(e.length);let i=t.getChunkCtOffset(),s=new Uint8Array(t.memory.buffer).slice(i,i+e.length);l(t,s);let g=(16-e.length%16)%16;g>0&&l(t,new Uint8Array(g)),l(t,M(o.length,e.length)),t.polyFinal();let c=t.getPolyTagOffset(),p=new Uint8Array(t.memory.buffer).slice(c,c+16);return{ciphertext:s,tag:p}}function K(t,r,n,e,o,a,u=\"chacha20-poly1305\"){let f=t.getChunkSize();if(e.length>f)throw new RangeError(`ciphertext exceeds ${f} bytes \\u2014 split into smaller chunks`);let i=new Uint8Array(t.memory.buffer);i.set(r,t.getKeyOffset()),i.set(n,t.getChachaNonceOffset()),t.chachaLoadKey(),t.chachaGenPolyKey(),t.polyInit(),l(t,a);let s=(16-a.length%16)%16;s>0&&l(t,new Uint8Array(s)),l(t,e);let g=(16-e.length%16)%16;g>0&&l(t,new Uint8Array(g)),l(t,M(a.length,e.length)),t.polyFinal();let c=t.getPolyTagOffset(),p=new Uint8Array(t.memory.buffer).slice(c,c+16);if(!B(p,o)){let b=t.getChunkCtOffset();i.fill(0,b,b+f);let C=t.getChachaBlockOffset();i.fill(0,C,C+64);let E=t.getPolyKeyOffset();throw i.fill(0,E,E+32),new d(u)}t.chachaSetCounter(1),t.chachaLoadKey(),new Uint8Array(t.memory.buffer).set(e,t.getChunkPtOffset()),t.chachaEncryptChunk_simd(e.length);let w=t.getChunkCtOffset();return new Uint8Array(t.memory.buffer).slice(w,w+e.length)}var y,h;self.onmessage=async t=>{let r=t.data;if(r.type===\"init\"){try{let n=new WebAssembly.Memory({initial:3,maximum:3}),e=r.modules.chacha20;if(y=(await WebAssembly.instantiate(e,{env:{memory:n}})).exports,h=new Uint8Array(r.derivedKeyBytes),h.length!==32)throw new Error(`expected 32 derived key bytes (got ${h.length})`);r.derivedKeyBytes.fill(0),self.postMessage({type:\"ready\"})}catch(n){self.postMessage({type:\"error\",id:-1,message:n.message,isAuthError:!1})}return}if(r.type===\"wipe\"){h&&h.fill(0),h=void 0,y&&y.wipeBuffers(),y=void 0,self.postMessage({type:\"wiped\"});return}if(!y||!h){self.postMessage({type:\"error\",id:r.id,message:\"worker not initialized\",isAuthError:!1});return}try{let{id:n,op:e,counterNonce:o,data:a,aad:u}=r,f=u??new Uint8Array(0),i=r.derivedKeyBytes??h,s;if(e===\"seal\"){let{ciphertext:c,tag:p}=W(y,i,o,a,f);s=new Uint8Array(c.length+16),s.set(c),s.set(p,c.length)}else{let c=a.subarray(0,a.length-16),p=a.subarray(a.length-16);s=K(y,i,o,c,p,f,\"xchacha20-poly1305\")}let g=s.buffer instanceof ArrayBuffer?[s.buffer]:[];self.postMessage({type:\"result\",id:n,data:s},{transfer:g})}catch(n){let e=n instanceof d;self.postMessage({type:\"error\",id:r.id,message:n.message,cipher:e?\"xchacha20-poly1305\":void 0,isAuthError:e})}finally{r.derivedKeyBytes&&r.derivedKeyBytes.fill(0),y&&y.wipeBuffers()}};})();\n";

package/dist/embedded/chacha20-pool-worker.js

@@ -0,0 +1,5 @@
+// Generated by scripts/embed-workers.ts — do not edit
+// IIFE-bundled pool worker source. Spawned via blob URL by
+// the cipher-suite.ts createPoolWorker; consumers do not
+// import this directly.
+export const WORKER_SOURCE = "\"use strict\";(()=>{var U=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]);var v=null,k=null,O=!1,A=null,T=32768;function P(){if(O){if(A)throw A;return}if(O=!0,!R())throw A=new Error(\"leviathan-crypto: constantTimeEqual requires WebAssembly SIMD \\u2014 this runtime does not support it\"),A;try{let t=U.buffer.slice(U.byteOffset,U.byteOffset+U.byteLength),r=new WebAssembly.Module(t),e=new WebAssembly.Instance(r).exports;k=e.memory,v=e.compare}catch(t){throw A=new Error(`leviathan-crypto: ct WASM module failed to instantiate: ${t.message}`),A}}var B=(t,r)=>{if(t.length!==r.length)return!1;if(t.length>T)throw new RangeError(`constantTimeEqual: max ${T} bytes (got ${t.length})`);P();let n=k,e=v;if(!n||!e)throw new Error(\"leviathan-crypto: ct init invariant violated\");let o=new Uint8Array(n.buffer);o.set(t,0),o.set(r,t.length);try{return e(0,t.length,t.length)===1}finally{o.fill(0,0,t.length*2)}};var m=null;function R(){if(m!==null)return m;if(typeof WebAssembly>\"u\"||typeof WebAssembly.validate!=\"function\")return m=!1,m;try{m=WebAssembly.validate(new Uint8Array([0,97,115,109,1,0,0,0,1,5,1,96,0,1,123,3,2,1,0,10,10,1,8,0,65,0,253,15,253,98,11]))}catch{m=!1}return m}var d=class t extends Error{constructor(r){super(`${r}: authentication failed`),this.name=\"AuthenticationError\",Object.setPrototypeOf(this,t.prototype)}};function l(t,r){if(r.length===0)return;let n=new Uint8Array(t.memory.buffer),e=t.getPolyMsgOffset(),o=0;for(;o<r.length;){let a=Math.min(64,r.length-o);n.set(r.subarray(o,o+a),e),t.polyUpdate(a),o+=a}}function M(t,r){let n=new Uint8Array(16),e=new DataView(n.buffer);return e.setUint32(0,t>>>0,!0),e.setUint32(4,Math.floor(t/4294967296)>>>0,!0),e.setUint32(8,r>>>0,!0),e.setUint32(12,Math.floor(r/4294967296)>>>0,!0),n}function W(t,r,n,e,o){let a=t.getChunkSize();if(e.length>a)throw new RangeError(`plaintext exceeds ${a} bytes \\u2014 split into smaller chunks`);let u=new Uint8Array(t.memory.buffer);u.set(r,t.getKeyOffset()),u.set(n,t.getChachaNonceOffset()),t.chachaLoadKey(),t.chachaGenPolyKey(),t.polyInit(),l(t,o);let f=(16-o.length%16)%16;f>0&&l(t,new Uint8Array(f)),t.chachaSetCounter(1),u.set(e,t.getChunkPtOffset()),t.chachaEncryptChunk_simd(e.length);let i=t.getChunkCtOffset(),s=new Uint8Array(t.memory.buffer).slice(i,i+e.length);l(t,s);let g=(16-e.length%16)%16;g>0&&l(t,new Uint8Array(g)),l(t,M(o.length,e.length)),t.polyFinal();let c=t.getPolyTagOffset(),p=new Uint8Array(t.memory.buffer).slice(c,c+16);return{ciphertext:s,tag:p}}function K(t,r,n,e,o,a,u=\"chacha20-poly1305\"){let f=t.getChunkSize();if(e.length>f)throw new RangeError(`ciphertext exceeds ${f} bytes \\u2014 split into smaller chunks`);let i=new Uint8Array(t.memory.buffer);i.set(r,t.getKeyOffset()),i.set(n,t.getChachaNonceOffset()),t.chachaLoadKey(),t.chachaGenPolyKey(),t.polyInit(),l(t,a);let s=(16-a.length%16)%16;s>0&&l(t,new Uint8Array(s)),l(t,e);let g=(16-e.length%16)%16;g>0&&l(t,new Uint8Array(g)),l(t,M(a.length,e.length)),t.polyFinal();let c=t.getPolyTagOffset(),p=new Uint8Array(t.memory.buffer).slice(c,c+16);if(!B(p,o)){let b=t.getChunkCtOffset();i.fill(0,b,b+f);let C=t.getChachaBlockOffset();i.fill(0,C,C+64);let E=t.getPolyKeyOffset();throw i.fill(0,E,E+32),new d(u)}t.chachaSetCounter(1),t.chachaLoadKey(),new Uint8Array(t.memory.buffer).set(e,t.getChunkPtOffset()),t.chachaEncryptChunk_simd(e.length);let w=t.getChunkCtOffset();return new Uint8Array(t.memory.buffer).slice(w,w+e.length)}var y,h;self.onmessage=async t=>{let r=t.data;if(r.type===\"init\"){try{let n=new WebAssembly.Memory({initial:3,maximum:3}),e=r.modules.chacha20;if(y=(await WebAssembly.instantiate(e,{env:{memory:n}})).exports,h=new Uint8Array(r.derivedKeyBytes),h.length!==32)throw new Error(`expected 32 derived key bytes (got ${h.length})`);r.derivedKeyBytes.fill(0),self.postMessage({type:\"ready\"})}catch(n){self.postMessage({type:\"error\",id:-1,message:n.message,isAuthError:!1})}return}if(r.type===\"wipe\"){h&&h.fill(0),h=void 0,y&&y.wipeBuffers(),y=void 0,self.postMessage({type:\"wiped\"});return}if(!y||!h){self.postMessage({type:\"error\",id:r.id,message:\"worker not initialized\",isAuthError:!1});return}try{let{id:n,op:e,counterNonce:o,data:a,aad:u}=r,f=u??new Uint8Array(0),i=r.derivedKeyBytes??h,s;if(e===\"seal\"){let{ciphertext:c,tag:p}=W(y,i,o,a,f);s=new Uint8Array(c.length+16),s.set(c),s.set(p,c.length)}else{let c=a.subarray(0,a.length-16),p=a.subarray(a.length-16);s=K(y,i,o,c,p,f,\"xchacha20-poly1305\")}let g=s.buffer instanceof ArrayBuffer?[s.buffer]:[];self.postMessage({type:\"result\",id:n,data:s},{transfer:g})}catch(n){let e=n instanceof d;self.postMessage({type:\"error\",id:r.id,message:n.message,cipher:e?\"xchacha20-poly1305\":void 0,isAuthError:e})}finally{r.derivedKeyBytes&&r.derivedKeyBytes.fill(0),y&&y.wipeBuffers()}};})();\n";