leviathan-crypto 1.3.1 → 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) — ChaCha20/Poly1305 classes implement `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