leviathan-crypto 1.4.0 → 2.0.0

package/dist/docs/sha3.md

@@ -1,27 +1,36 @@
 # SHA3 TypeScript API Reference
 
 > [!NOTE]
-> SHA-3 hash functions and SHAKE XOFs (TypeScript API)
->
-> See [SHA-3 implementation audit](./sha3_audit.md) for algorithm correctness verifications.
+> Covers the SHA-3 hash functions (SHA3-224 through SHA3-512) and the SHAKE extendable-output functions (SHAKE128, SHAKE256). See [SHA-3 implementation audit](./sha3_audit.md) for algorithm correctness verifications.
+
+> ### Table of Contents
+> - [Overview](#overview)
+> - [Security Notes](#security-notes)
+> - [Module Init](#module-init)
+> - [API Reference](#api-reference)
+> - [Incremental XOF API](#incremental-xof-api-absorb--squeeze--reset)
+> - [Usage Examples](#usage-examples)
+> - [Error Conditions](#error-conditions)
+
+---
 
 ## Overview
 
 The SHA-3 family provides six hash functions standardized in **FIPS 202**: four
 fixed-output hash functions (SHA3-224, SHA3-256, SHA3-384, SHA3-512) and two
 extendable-output functions, or XOFs (SHAKE128, SHAKE256). All six are built on
-the **Keccak sponge construction** -- a fundamentally different design from the
+the **Keccak sponge construction**, a fundamentally different design from the
 Merkle-Damgard structure used by SHA-2.
 
 SHA-3 is **not** a replacement for SHA-2. Both are considered secure, and both are
 standardized by NIST. SHA-3 exists to provide **defense-in-depth**: if a flaw is
 ever discovered in SHA-2, SHA-3 is completely unaffected because it uses a different
-mathematical foundation. Think of it as insurance -- you may never need it, but if
-you do, you will be very glad it is there.
+mathematical foundation. You may never need that insurance, but if you do, you will be
+very glad it is there.
 
 The SHAKE XOFs are particularly flexible. Unlike SHA3-256, which always produces
-exactly 32 bytes, SHAKE128 and SHAKE256 can produce variable-length output -- you
-tell them how many bytes you want. This is useful for key derivation, generating
+exactly 32 bytes, SHAKE128 and SHAKE256 can produce variable-length output. You
+tell them how many bytes you want, making them useful for key derivation, generating
 nonces, or any situation where you need more (or fewer) bytes than a standard hash
 provides.
 
@@ -41,7 +50,7 @@ secret. SHA-3's sponge construction makes this impossible.
 - **Length extension immunity.** Unlike SHA-2, the SHA-3 sponge construction does
   not leak enough internal state for length extension attacks. Computing
   `SHA3(secret + message)` does not let an attacker forge `SHA3(secret + message + extra)`.
-  That said, **HMAC is still the correct way to build a MAC** -- do not use raw
+  That said, **HMAC is still the correct way to build a MAC** — do not use raw
   `SHA3(key + message)` as a MAC construction, even though it is not vulnerable to
   length extension. HMAC provides a formally proven security reduction.
 
@@ -50,7 +59,7 @@ secret. SHA-3's sponge construction makes this impossible.
   sponge directly with `absorb()` / `squeeze()`. The only constraint is
   `outputLength >= 1`.
 
-- **Not for password hashing.** SHA-3 is a fast hash — that is the opposite of
+- **Not for password hashing.** SHA-3 is a fast hash, which is the opposite of
   what you want for password storage. Passwords must be hashed with a slow,
   memory-hardened algorithm like **Argon2id**. See [argon2id.md](./argon2id.md) for
   usage patterns including passphrase-based encryption with leviathan primitives.
@@ -68,27 +77,45 @@ secret. SHA-3's sponge construction makes this impossible.
 Each module subpath exports its own init function for consumers who want
 tree-shakeable imports.
 
-### `sha3Init(mode?, opts?)`
+### `sha3Init(source)`
 
 Initializes only the sha3 WASM binary. Equivalent to calling the
-root `init(['sha3'], mode, opts)` but without pulling the other three
+root `init({ sha3: source })` but without pulling the other three
 modules into the bundle.
 
 **Signature:**
 
 ```typescript
-async function sha3Init(mode?: Mode, opts?: InitOpts): Promise<void>
+async function sha3Init(source: WasmSource): Promise<void>
 ```
 
 **Usage:**
 
 ```typescript
 import { sha3Init, SHA3_256 } from 'leviathan-crypto/sha3'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await sha3Init()
+await sha3Init(sha3Wasm)
 const sha3 = new SHA3_256()
 ```
 
+### keccakInit() Alias
+
+`'keccak'` is an alias for `'sha3'`. Same WASM binary, same instance slot.
+`keccakInit()` and `sha3Init()` are interchangeable.
+
+```typescript
+import { keccakInit, SHAKE256, SHA3_256 } from 'leviathan-crypto/keccak'
+import { keccakWasm } from 'leviathan-crypto/keccak/embedded'
+
+await keccakInit(keccakWasm)
+// isInitialized('sha3') === true — same slot
+```
+
+Use the `keccak` subpath when the consuming context (such as ML-KEM) makes the
+Keccak primitive name semantically clearer. See [init.md](./init.md#keccak-alias-for-ml-kem)
+for full details.
+
 ---
 
 ## API Reference
@@ -97,19 +124,18 @@ All SHA-3 classes require initialization before use. Either the root `init()`:
 
 ```typescript
 import { init } from 'leviathan-crypto'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await init('sha3')
+await init({ sha3: sha3Wasm })
 ```
 
-Both `init('sha3')` and `init(['sha3'])` are valid — the root `init()` accepts
-a single `Module` string or an array.
-
 Or the subpath `sha3Init()`:
 
 ```typescript
 import { sha3Init } from 'leviathan-crypto/sha3'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await sha3Init()
+await sha3Init(sha3Wasm)
 ```
 
 If you use SHA-3 classes without calling `init()` first, the constructor
@@ -134,7 +160,7 @@ class SHA3_224 {
 ### SHA3_256
 
 Fixed-output hash function. Produces a **32-byte** (256-bit) digest. This is the
-most commonly used SHA-3 variant -- 256-bit security is suitable for most
+most commonly used SHA-3 variant; 256-bit security is suitable for most
 applications.
 
 ```typescript
@@ -255,8 +281,9 @@ Calling `absorb()` while squeezing throws:
 
 ```typescript
 import { init, SHAKE256 } from 'leviathan-crypto'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await init('sha3')
+await init({ sha3: sha3Wasm })
 
 const xof = new SHAKE256()
 xof.absorb(ikm)             // input key material
@@ -275,13 +302,14 @@ xof.dispose()
 
 ### Example 1: Hash a string with SHA3-256
 
-The most common use case -- hash some data and get a hex digest.
+The most common use case: hash some data and get a hex digest.
 
 ```typescript
 import { init, SHA3_256, bytesToHex, utf8ToBytes } from 'leviathan-crypto'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
 // Initialize the SHA-3 WASM module (once, at startup)
-await init('sha3')
+await init({ sha3: sha3Wasm })
 
 // Create a hasher
 const sha3 = new SHA3_256()
@@ -303,8 +331,9 @@ sha3.dispose()
 
 ```typescript
 import { init, SHA3_512, bytesToHex } from 'leviathan-crypto'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await init('sha3')
+await init({ sha3: sha3Wasm })
 
 const sha3 = new SHA3_512()
 
@@ -322,13 +351,14 @@ sha3.dispose()
 
 ### Example 3: Hash multiple messages
 
-Each call to `hash()` is independent -- the internal state is reset automatically.
+Each call to `hash()` is independent; the internal state resets automatically.
 You can reuse the same class instance for multiple hashes.
 
 ```typescript
 import { init, SHA3_256, bytesToHex, utf8ToBytes } from 'leviathan-crypto'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await init('sha3')
+await init({ sha3: sha3Wasm })
 
 const sha3 = new SHA3_256()
 
@@ -354,8 +384,9 @@ for key derivation or generating fixed-size tokens.
 
 ```typescript
 import { init, SHAKE128, bytesToHex, utf8ToBytes } from 'leviathan-crypto'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await init('sha3')
+await init({ sha3: sha3Wasm })
 
 const shake = new SHAKE128()
 
@@ -383,8 +414,9 @@ shake.dispose()
 
 ```typescript
 import { init, SHAKE256, bytesToHex } from 'leviathan-crypto'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await init('sha3')
+await init({ sha3: sha3Wasm })
 
 const shake = new SHAKE256()
 
@@ -400,17 +432,18 @@ shake.dispose()
 
 ---
 
-### Example 6: SHA-256 vs SHA3-256 -- different algorithms, different output
+### Example 6: SHA-256 vs SHA3-256
 
 SHA-256 (from the SHA-2 family) and SHA3-256 are completely different algorithms.
-They produce different output for the same input. Neither is "better" -- both
-are secure. SHA3-256 adds defense-in-depth.
+They produce different output for the same input. Both are secure; SHA3-256 adds defense-in-depth.
 
 ```typescript
 import { init, SHA256, SHA3_256, bytesToHex, utf8ToBytes } from 'leviathan-crypto'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
 // Initialize both modules
-await init(['sha2', 'sha3'])
+await init({ sha2: sha2Wasm, sha3: sha3Wasm })
 
 const sha2 = new SHA256()
 const sha3 = new SHA3_256()
@@ -437,8 +470,9 @@ deterministic output.
 
 ```typescript
 import { init, SHA3_256, bytesToHex } from 'leviathan-crypto'
+import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await init('sha3')
+await init({ sha3: sha3Wasm })
 
 const sha3 = new SHA3_256()
 const digest = sha3.hash(new Uint8Array(0))
@@ -453,16 +487,16 @@ sha3.dispose()
 
 ## Error Conditions
 
-### `init('sha3')` not called
+### SHA-3 module not initialized
 
 If you construct a SHA-3 class before initializing the module, the constructor
 throws immediately:
 
 ```
-Error: leviathan-crypto: call init(['sha3']) before using this class
+Error: leviathan-crypto: call init({ sha3: ... }) before using this class
 ```
 
-**Fix:** Call `await init('sha3')` once at application startup, before creating
+**Fix:** Call `await init({ sha3: sha3Wasm })` once at application startup, before creating
 any SHA-3 class instances.
 
 ---

package/dist/docs/types.md

@@ -1,21 +1,23 @@
-# Public TypeScript interfaces for cryptographic primitives
+# TypeScript Interfaces
 
-## Overview
+> [!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.
 
-This module defines the abstract interfaces that all leviathan-crypto cryptographic classes implement. These are **type-only exports** -- they contain no runtime code and generate no JavaScript output.
-
-Use these interfaces when you need to write generic code that works with any hash function, any cipher, or any AEAD scheme without depending on a specific implementation. They are available immediately on import with no `init()` call required.
-
----
-
-## Security Notes
-
-This module contains type definitions only. There are no security-sensitive operations.
+> ### Table of Contents
+> - [API Reference](#api-reference)
+> - [Usage Examples](#usage-examples)
+> - [WasmSource](#wasmsource)
+> - [CipherSuite](#ciphersuite)
+> - [DerivedKeys](#derivedkeys)
+> - [SealStreamOpts](#sealstreamopts)
+> - [PoolOpts](#poolopts)
 
 ---
 
 ## API Reference
 
+Use these interfaces when you need generic code that works with any hash function, any cipher, or any AEAD scheme without depending on a specific implementation. They are available immediately on import with no `init()` call required.
+
 ### Hash
 
 ```typescript
@@ -45,7 +47,7 @@ interface KeyedHash {
 
 Interface for keyed hash functions / MACs (e.g., HMAC-SHA256, HMAC-SHA512).
 
-Note: `KeyedHash` does **not** extend `Hash`. Its `hash` method takes a `key` parameter in addition to the message.
+`KeyedHash` does **not** extend `Hash`. Its `hash` method takes a `key` parameter in addition to the message.
 
 | Method | Description |
 |---|---|
@@ -109,7 +111,7 @@ Interface for authenticated encryption with associated data (e.g., XChaCha20-Pol
 | Method | Description |
 |---|---|
 | `encrypt(msg, aad?)` | Encrypts `msg` and authenticates both `msg` and optional `aad`. Returns ciphertext with appended authentication tag. |
-| `decrypt(ciphertext, aad?)` | Decrypts and verifies the authentication tag. Returns plaintext on success. Throws `Error` on authentication failure — never returns null. |
+| `decrypt(ciphertext, aad?)` | Decrypts and verifies the authentication tag. Returns plaintext on success. Throws `Error` on authentication failure. Never returns null. |
 | `dispose()` | Releases WASM resources and wipes internal buffers. |
 
 ---
@@ -128,7 +130,7 @@ function digestAndLog(hasher: Hash, data: Uint8Array): Uint8Array {
 }
 ```
 
-This function accepts any `Hash` implementation -- `SHA256`, `SHA512`, `SHA3_256`, etc. -- without importing any of them directly.
+This function accepts any `Hash` implementation (`SHA256`, `SHA512`, `SHA3_256`, etc.) without importing any of them directly.
 
 ---
 
@@ -142,7 +144,7 @@ function sealMessage(aead: AEAD, plaintext: Uint8Array, metadata: Uint8Array): U
 }
 
 function openMessage(aead: AEAD, ciphertext: Uint8Array, metadata: Uint8Array): Uint8Array {
-  // decrypt() throws on auth failure — no null check needed
+  // decrypt() throws on auth failure, no null check needed
   return aead.decrypt(ciphertext, metadata)
 }
 ```
@@ -186,13 +188,88 @@ function cleanup(ctx: EncryptionContext): void {
 
 ---
 
+## WasmSource
+
+Union type for WASM module sources. Accepted by `init()`, `serpentInit()`, etc.
+
+`string | URL | ArrayBuffer | Uint8Array | WebAssembly.Module | Response | Promise<Response>`
+
+---
+
+## CipherSuite
+
+Cipher-specific logic injected into `SealStream` and `OpenStream`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `formatEnum` | `number` | Wire format ID encoded in header byte 0 bits 0-5 (max 0x3f): bits 0-3 = cipher nibble (0x1=xchacha20, 0x2=serpent), bits 4-5 = KEM selector (0x00=none, 0x10=ML-KEM-512, 0x20=ML-KEM-768, 0x30=ML-KEM-1024), bit 6 reserved |
+| `formatName` | `string` | Human-readable label, e.g. `'xchacha20'`, `'serpent'`, `'mlkem768+xchacha20'` |
+| `hkdfInfo` | `string` | HKDF info string for key derivation |
+| `keySize` | `number` | Seal/encrypt key size in bytes (encapsulation key bytes for KEM suites) |
+| `decKeySize` | `number \| undefined` | Open/decrypt key size in bytes (decapsulation key bytes for KEM suites). Absent → same as `keySize` (symmetric case) |
+| `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) |
+| `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 |
+| `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 |
+
+Implementations: `XChaCha20Cipher`, `SerpentCipher` (plain `const` objects, not classes), and `KyberSuite` (factory function returning a `CipherSuite`). See [ciphersuite.md](./ciphersuite.md).
+
+> [!IMPORTANT]
+> All CipherSuite implementations use HKDF-SHA-256 in `deriveKeys()`. The stream layer requires
+> `sha2` to be initialized regardless of which cipher is selected.
+
+---
+
+## DerivedKeys
+
+Opaque key material returned by `CipherSuite.deriveKeys()`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `bytes` | `readonly Uint8Array` | Raw derived key bytes (opaque to the stream layer) |
+
+---
+
+## SealStreamOpts
+
+Options for `SealStream` constructor.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `chunkSize` | `number` | `65536` | Chunk size in bytes. Range: [1024, 16777215]. |
+| `framed` | `boolean` | `false` | Enable u32be length-prefixed framing. |
+
+---
+
+## PoolOpts
+
+Options for `SealStreamPool.create()`.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `wasm` | `WasmSource \| Record<string, WasmSource>` | | WASM module source(s). Single source for single-module ciphers, Record for multi-module. |
+| `workers` | `number` | `navigator.hardwareConcurrency ?? 4` | Number of Web Workers. |
+| `chunkSize` | `number` | `65536` | Chunk size in bytes. |
+| `framed` | `boolean` | `false` | Enable framed mode. |
+| `jobTimeout` | `number` | `30000` | Per-job timeout in milliseconds. |
+
+---
+
 > ## 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) — `XChaCha20Seal` and `XChaCha20StreamSealer`/`Opener` implement `AEAD`; `ChaCha20`/`ChaCha20Poly1305`/`XChaCha20Poly1305` are stateless primitives
+> - [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

package/dist/docs/utils.md

@@ -1,23 +1,23 @@
-# Encoding utilities, comparison functions, and random byte generation
+# Utilities
 
-## Overview
+> [!NOTE]
+> Pure TypeScript utilities that ship alongside the WASM-backed primitives. No `init()` call required; all functions work immediately on import.
 
-Pure TypeScript utilities that ship alongside the WASM-backed primitives. These functions have **no `init()` dependency** -- they work immediately on import, without loading any WASM module.
-
-The module covers four areas:
-
-- **Encoding** -- hex, UTF-8, and base64 conversions between strings and `Uint8Array`
-- **Security** -- constant-time comparison and secure memory wiping
-- **Byte manipulation** -- XOR and concatenation of byte arrays
-- **Random** -- cryptographically secure random byte generation
+> ### Table of Contents
+> - [Security Notes](#security-notes)
+> - [API Reference](#api-reference)
+> - [Usage Examples](#usage-examples)
+> - [Error Conditions](#error-conditions)
 
 ---
 
+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 an XOR-accumulate pattern with no early return on byte mismatch. Use this function whenever you compare MACs, hashes, authentication tags, or any secret-derived values. **Never** use `===`, `Buffer.equals`, or manual loop-with-break for security comparisons -- those leak timing information that can be exploited to recover secrets.
+**`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.
 
-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, you must 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.
 
@@ -75,7 +75,7 @@ Decodes UTF-8 bytes to a JavaScript string using the platform `TextDecoder`.
 base64ToBytes(b64: string): Uint8Array | undefined
 ```
 
-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 (e.g., illegal characters or `rem=1` length).
+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).
 
 ---
 
@@ -85,7 +85,7 @@ Decodes a base64 or base64url string to a `Uint8Array`. Handles padded, unpadded
 bytesToBase64(bytes: Uint8Array, url?: boolean): string
 ```
 
-Encodes a `Uint8Array` to a base64 string. Pass `url = true` for base64url (RFC 4648 §5 — uses `-` and `_` instead of `+` and `/`, no padding characters). Defaults to standard base64.
+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.
 
 ---
 
@@ -95,7 +95,40 @@ Encodes a `Uint8Array` to a base64 string. Pass `url = true` for base64url (RFC
 constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean
 ```
 
-Returns `true` if `a` and `b` contain identical bytes. Uses XOR-accumulate with no early return on mismatch. Returns `false` immediately if the arrays differ in length (length is non-secret).
+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.
+
+---
+
+### CT_MAX_BYTES
+
+```typescript
+const CT_MAX_BYTES: 32768
+```
+
+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).
+
+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'
+
+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)
+```
 
 ---
 
@@ -115,7 +148,7 @@ 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.
 
 ---
 
@@ -125,7 +158,7 @@ Returns a new `Uint8Array` where each byte is `a[i] ^ b[i]`. Both arrays must ha
 concat(...arrays: Uint8Array[]): Uint8Array
 ```
 
-Concatenate one or more `Uint8Array`s into a new array.
+Concatenates one or more `Uint8Array`s into a new array.
 
 ---
 
@@ -149,10 +182,10 @@ 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.
 
-This function is called internally by `SerpentCtr.encryptChunk`,
-`SerpentCbc.decrypt`, and `ChaCha20.encryptChunk` 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.
+`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.
 
 Supported in all modern browsers and Node.js 16+. Returns `false` in older
 environments, which fall back silently to the scalar path.
@@ -201,21 +234,62 @@ if (decoded) console.log(bytesToUtf8(decoded)) // "leviathan-crypto"
 
 ---
 
-### Secure MAC comparison
+### 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.
 
 ```typescript
-import { constantTimeEqual } from 'leviathan-crypto'
+import {
+  init, SerpentCbc, HMAC_SHA256,
+  constantTimeEqual, randomBytes, wipe, concat,
+} from 'leviathan-crypto'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded'
+
+await init({ serpent: serpentWasm, sha2: sha2Wasm })
+
+const encKey = randomBytes(32)
+const macKey = randomBytes(32)
+const iv     = randomBytes(16)
 
-// After computing a MAC over received data, compare it to the expected tag.
-// NEVER use === or .every() for this -- timing leaks enable forgery attacks.
-const computedMac: Uint8Array = hmac.hash(key, message)
-const receivedMac: Uint8Array = getTagFromNetwork()
+// ── Encrypt ──────────────────────────────────────────────────────────────────
 
-if (!constantTimeEqual(computedMac, receivedMac)) {
-  throw new Error('Authentication failed: MAC mismatch')
+const cbc = new SerpentCbc({ dangerUnauthenticated: true })
+const ct  = cbc.encrypt(encKey, iv, plaintext)
+cbc.dispose()
+
+// MAC covers iv || ct so the IV is authenticated too
+const hmac = new HMAC_SHA256()
+const tag  = hmac.hash(macKey, concat(iv, ct))
+hmac.dispose()
+
+const envelope = concat(iv, ct, tag)  // store or transmit this
+
+// ── Decrypt ──────────────────────────────────────────────────────────────────
+
+const receivedIv  = envelope.subarray(0, 16)
+const receivedCt  = envelope.subarray(16, envelope.length - 32)
+const receivedTag = envelope.subarray(envelope.length - 32)
+
+const hmac2       = new HMAC_SHA256()
+const expectedTag = hmac2.hash(macKey, concat(receivedIv, receivedCt))
+hmac2.dispose()
+
+// Always verify before decrypting — never decrypt unauthenticated ciphertext
+if (!constantTimeEqual(expectedTag, receivedTag)) {
+  wipe(expectedTag)
+  throw new Error('Authentication failed')
 }
+
+const cbc2 = new SerpentCbc({ dangerUnauthenticated: true })
+const pt   = cbc2.decrypt(encKey, receivedIv, receivedCt)
+cbc2.dispose()
+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.
+
 ---
 
 ### Generating random keys and nonces
@@ -223,9 +297,9 @@ if (!constantTimeEqual(computedMac, receivedMac)) {
 ```typescript
 import { randomBytes } from 'leviathan-crypto'
 
-const key = randomBytes(32)   // 256-bit symmetric key
-const nonce = randomBytes(24) // 192-bit nonce for XChaCha20
-const iv = randomBytes(16)    // 128-bit IV for Serpent-CBC
+const key   = randomBytes(32)  // 256-bit symmetric key
+const nonce = randomBytes(24)  // 192-bit nonce for XChaCha20
+const iv    = randomBytes(16)  // 128-bit IV for Serpent-CBC
 ```
 
 ---
@@ -272,6 +346,7 @@ console.log(combined.length) // 32
 | `hexToBytes` | Invalid hex characters | Bytes decode as `NaN` -> `0` |
 | `base64ToBytes` | Invalid length or characters | Returns `undefined` |
 | `constantTimeEqual` | Arrays differ in length | Returns `false` immediately |
+| `constantTimeEqual` | Either array exceeds `CT_MAX_BYTES` | Throws `RangeError` |
 | `xor` | Arrays differ in length | Throws `RangeError` |
 | `randomBytes` | `crypto` not available | Throws (runtime-dependent) |
 | `hasSIMD` | `WebAssembly` not available | Returns `false` |
@@ -286,5 +361,7 @@ console.log(combined.length) // 32
 > - [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