leviathan-crypto 2.0.1 → 2.1.0

package/dist/docs/init.md

@@ -1,9 +1,8 @@
-# Module Initialization and WASM Loading
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="logo" width="120" align="left" margin="10">
 
-> [!IMPORTANT]
-> Call `init()` before using any cryptographic class. It loads the WebAssembly
-> modules that perform cryptographic work, caches them in memory, and makes them
-> available to all wrapper classes.
+### Module Initialization and WASM Loading
+
+Call `init()` before using any cryptographic class. It loads the WebAssembly modules that perform cryptographic work, caches them in memory, and makes them available to all wrapper classes.
 
 > ### Table of Contents
 > - [Overview](#overview)
@@ -63,7 +62,8 @@ The WASM module families. Each one backs a group of related classes.
 | Module | Classes it enables |
 |---|---|
 | `'serpent'` | `Serpent`, `SerpentCbc`, `SerpentCtr` |
-| `'serpent'` + `'sha2'` | `SerpentCipher`, `Seal` (with `SerpentCipher`), `SealStream`, `OpenStream`, `Fortuna` — see [aead.md](./aead.md) |
+| `'serpent'` + `'sha2'` | `SerpentCipher`, `Seal` (with `SerpentCipher`), `SealStream`, `OpenStream` — see [aead.md](./aead.md) |
+| `Fortuna` combinations | `Fortuna` accepts a `Generator` + `HashFn` pair. Valid module combinations: `'serpent' + 'sha2'`, `'serpent' + 'sha3'`, `'chacha20' + 'sha2'`, `'chacha20' + 'sha3'`. See [fortuna.md](./fortuna.md). |
 | `'chacha20'` | `ChaCha20`, `ChaCha20Poly1305`, `XChaCha20Poly1305` |
 | `'chacha20'` + `'sha2'` | `XChaCha20Cipher`, `Seal` (with `XChaCha20Cipher`), `SealStream`, `OpenStream` — see [aead.md](./aead.md) |
 | `'sha2'` | `SHA256`, `SHA384`, `SHA512`, `HMAC` (SHA-2 based), `HKDF` |
@@ -73,7 +73,7 @@ The WASM module families. Each one backs a group of related classes.
 
 ```typescript
 type WasmSource = string | URL | ArrayBuffer | Uint8Array
-               | WebAssembly.Module | Response | Promise<Response>
+               | WebAssembly.Module | Response | PromiseLike<WasmSource>
 ```
 
 A value that resolves to a WASM binary. The loading strategy is inferred from
@@ -86,7 +86,13 @@ the type:
 | `ArrayBuffer` | Compiled directly via `WebAssembly.instantiate`. |
 | `Uint8Array` | Compiled directly via `WebAssembly.instantiate`. |
 | `WebAssembly.Module` | Already compiled. Instantiated immediately. |
-| `Response` / `Promise<Response>` | Streaming compilation via `WebAssembly.instantiateStreaming`. |
+| `Response` | Streaming compilation via `WebAssembly.instantiateStreaming`. |
+| `PromiseLike<WasmSource>` | Awaited and re-dispatched by the resolved runtime type. |
+
+Any `PromiseLike<WasmSource>` is accepted — `Promise<ArrayBuffer>`,
+`Promise<Uint8Array>`, `Promise<string>`, a `fetch()` response promise, and
+nested thenables up to depth 3 all resolve transparently. See
+[loader.md](./loader.md) for details.
 
 ---
 
@@ -190,17 +196,6 @@ Used by pool infrastructure to send compiled modules to workers. See
 
 ---
 
-#### _resetForTesting()
-
-```typescript
-function _resetForTesting(): void
-```
-
-Clears all cached WASM instances. Testing utility only. Do not use in
-production code.
-
----
-
 ## Usage Examples
 
 ### Embedded init (most common)
@@ -294,9 +289,13 @@ if (!isInitialized('sha2')) {
 
 ---
 
-> ## Cross-References
->
-> - [index](./README.md) — Project Documentation index
-> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
-> - [loader](./loader.md) — WASM binary loading strategies (internal details)
-> - [wasm](./wasm.md) — WebAssembly primer: modules, instances, memory, and the init gate
+
+## Cross-References
+
+| Document | Description |
+| -------- | ----------- |
+| [index](./README.md) | Project Documentation index |
+| [architecture](./architecture.md) | architecture overview, module relationships, buffer layouts, and build pipeline |
+| [loader](./loader.md) | WASM binary loading strategies (internal details) |
+| [wasm](./wasm.md) | WebAssembly primer: modules, instances, memory, and the init gate |
+

package/dist/docs/loader.md

@@ -1,23 +1,21 @@
-# WASM Binary Loading Strategies
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="logo" width="120" align="left" margin="10">
 
-> [!NOTE]
-> Internal module used by `init()` that handles the actual loading and
-> instantiation of WebAssembly binaries. You normally do not interact
-> with this module directly.
+### WASM Binary Loading Strategies
+
+Internal module used by `init()` that handles the actual loading and instantiation of WebAssembly binaries. You normally do not interact with this module directly.
 
 > ### Table of Contents
 > - [Overview](#overview)
 > - [Security Notes](#security-notes)
 > - [API Reference](#api-reference)
+> - [Examples](#examples)
 > - [Internal Details](#internal-details)
 
 ---
 
 ## Overview
 
-When you call [`init()`](./init.md), it delegates the work of obtaining and compiling the
-WASM binary to the loader. The loading strategy is inferred from the
-`WasmSource` type, so no mode string is required:
+When you call [`init()`](./init.md), it delegates the work of obtaining and compiling the WASM binary to the loader. The loading strategy is inferred from the `WasmSource` type, so no mode string is required:
 
 **Embedded string.** gzip-compressed, base64-encoded WASM bundled in the package. Decoded and decompressed at [`init()`](./init.md) time using `DecompressionStream`. No network requests. This is the default and simplest option.
 
@@ -29,8 +27,9 @@ WASM binary to the loader. The loading strategy is inferred from the
 
 **Response / Promise\<Response\>.** Streaming compilation from an in-flight or deferred fetch.
 
-All strategies produce the same result: a `WebAssembly.Instance` that the
-wrapper classes use to perform cryptographic operations.
+**Any other thenable (`PromiseLike<WasmSource>`).** The loader `await`s the thenable and recursively re-dispatches by the runtime type of the resolved value. `Promise<ArrayBuffer>`, `Promise<Uint8Array>`, `Promise<string>` (gzip+base64 blob), and even nested `Promise<Promise<Response>>` all work. Nesting is capped at depth 3 — deeper chains throw a `TypeError: thenable nesting too deep (max 3)`.
+
+All strategies produce the same result: a `WebAssembly.Instance` that the wrapper classes use to perform cryptographic operations.
 
 ---
 
@@ -48,8 +47,7 @@ wrapper classes use to perform cryptographic operations.
 
 ## API Reference
 
-These functions are exported from `loader.ts` and called by `init.ts`. They
-are not part of the public API. They are documented here for completeness and for contributors working on the internals.
+These functions are exported from `loader.ts` and called by `init.ts`. They are not part of the public API. They are documented here for completeness and for contributors working on the internals.
 
 ### `loadWasm(source)`
 ```typescript
@@ -68,16 +66,16 @@ instance receives a fresh 3-page `WebAssembly.Memory`.
 | `ArrayBuffer`                  | `WebAssembly.instantiate()`.                                         |
 | `Uint8Array`                   | `WebAssembly.instantiate()`.                                         |
 | `WebAssembly.Module`           | `WebAssembly.instantiate(module, imports)`.                          |
-| `Response` / `Promise<Response>` | `WebAssembly.instantiateStreaming()`.                              |
+| `Response`                     | `WebAssembly.instantiateStreaming()`.                                |
+| `PromiseLike<WasmSource>`      | `await` the thenable, re-dispatch by resolved type (recursive, max depth 3). |
 
 **Throws:**
 
 - `TypeError` if `source` is null, numeric, or otherwise unrecognised.
 - `TypeError` with `"empty string"` if `source` is an empty string.
+- `TypeError` with `"thenable nesting too deep (max 3)"` if a thenable source resolves to another thenable more than three levels deep.
 
-**Runtime guards:** `Response` and `Promise` checks are guarded with
-`typeof Response !== 'undefined'` to avoid `ReferenceError` in runtimes
-where these globals do not exist (Node < 18).
+**Runtime guards:** `Response` and `Promise` checks are guarded with `typeof Response !== 'undefined'` to avoid `ReferenceError` in runtimes where these globals do not exist (Node < 18).
 
 ---
 
@@ -86,12 +84,9 @@ where these globals do not exist (Node < 18).
 async function compileWasm(source: WasmSource): Promise<WebAssembly.Module>
 ```
 
-Compiles a `WasmSource` to a `WebAssembly.Module` without instantiating it.
-Used by pool infrastructure to send a compiled module to workers. Each worker receives the `Module` and instantiates it with their own isolated memory.
+Compiles a `WasmSource` to a `WebAssembly.Module` without instantiating it. Used by pool infrastructure to send a compiled module to workers. Each worker receives the `Module` and instantiates it with their own isolated memory.
 
-**Source type handling:** Same dispatch table as `loadWasm()`, but calls
-`WebAssembly.compile()` / `WebAssembly.compileStreaming()` instead of the
-`instantiate` variants. `WebAssembly.Module` sources are returned as-is.
+**Source type handling:** Same dispatch table as `loadWasm()`, but calls `WebAssembly.compile()` / `WebAssembly.compileStreaming()` instead of the `instantiate` variants. `WebAssembly.Module` sources are returned as-is.
 
 **Throws:** Same as `loadWasm()`.
 
@@ -109,13 +104,114 @@ Decodes a gzip-compressed, base64-encoded WASM string to raw bytes.
 
 **Throws:**
 
-- `Error` if `DecompressionStream` is not available in the runtime.
-  The error message directs the user to provide a URL, ArrayBuffer, or
-  WebAssembly.Module source instead.
-- `Error` if base64 decoding fails (corrupt embedded blob).
+- `Error` if `DecompressionStream` is not available in the runtime. The error message directs the user to provide a URL, ArrayBuffer, or WebAssembly.Module source instead.
+- `RangeError` with message `'base64ToBytes: invalid base64 input'` if the input is not valid base64 (corrupt embedded blob, wrong-length string, or non-base64 characters). Propagated unchanged from the shared `base64ToBytes` utility.
+
+Exported for use by the cipher-suite spawn paths that may need to decode blobs before passing pre-compiled modules to pool workers.
+
+---
+
+# Examples
+
+These examples show how to pass different source types to `init()` depending on your runtime, bundler, and deployment target.
+
+## Embedded (default, bundled)
+
+Use the compressed WASM blobs included in the package. No network call. Ideal for browser bundles and Node servers.
+
+```typescript
+import { init } from 'leviathan-crypto'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
+import { kyberWasm } from 'leviathan-crypto/kyber/embedded'
+
+await init({
+  serpent: serpentWasm,
+  sha2: sha2Wasm,
+  chacha20: chacha20Wasm,
+  kyber: kyberWasm
+})
+```
+
+## URL-based (streaming from CDN or public folder)
+
+Fetch the `.wasm` file from a served asset. The browser streams and compiles while downloading. Requires `Content-Type: application/wasm`.
+
+```typescript
+import { init } from 'leviathan-crypto'
+
+// From a CDN
+await init({
+  serpent: new URL('https://cdn.example.com/wasm/serpent.wasm'),
+  sha2: new URL('https://cdn.example.com/wasm/sha2.wasm'),
+  chacha20: new URL('https://cdn.example.com/wasm/chacha20.wasm'),
+  kyber: new URL('https://cdn.example.com/wasm/kyber.wasm')
+})
+
+// From a local /public folder
+await init({
+  serpent: new URL('/assets/wasm/serpent.wasm', import.meta.url),
+  sha2: new URL('/assets/wasm/sha2.wasm', import.meta.url)
+})
+```
+
+## Pre-compiled Module (edge runtimes, KV cache)
+
+Compile the WASM once, cache the `WebAssembly.Module`, and reuse it across requests. Each instantiation gets its own isolated memory.
+
+```typescript
+import { init, compileWasm } from 'leviathan-crypto/loader'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+
+// Compile once (at module load time or in an init handler)
+const serpentModule = await compileWasm(serpentWasm)
+
+// Reuse across requests
+async function handleRequest(req) {
+  await init({ serpent: serpentModule })
+  // Each request gets a fresh instance with isolated memory
+  // ...
+}
+```
+
+## Deferred loading (lazy initialization)
+
+Load the WASM only when needed. Pass a Promise that resolves to any valid source.
+
+```typescript
+import { init } from 'leviathan-crypto'
+
+const serpentPromise = fetch('/assets/wasm/serpent.wasm')
+  .then(res => res.arrayBuffer())
+
+await init({
+  serpent: serpentPromise,
+  sha2: new URL('/assets/wasm/sha2.wasm', import.meta.url)
+})
+```
+
+## Worker pool with pre-compiled modules
+
+Pass a compiled `WebAssembly.Module` to workers so each worker instantiates it with isolated memory. Used internally by `SealStreamPool` for parallel encryption.
+
+```typescript
+import { compileWasm } from 'leviathan-crypto/loader'
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
+
+// Main thread: compile once
+const serpentModule = await compileWasm(serpentWasm)
 
-Exported for use by pool worker launchers that need to decode blobs
-before spawning threads.
+// Pass to worker via postMessage
+worker.postMessage({ type: 'init', module: serpentModule })
+
+// Inside worker: instantiate with isolated memory
+self.onmessage = async (ev) => {
+  if (ev.data.type === 'init') {
+    await init({ serpent: ev.data.module })
+  }
+}
+```
 
 ---
 
@@ -125,37 +221,36 @@ before spawning threads.
 
 Each module provides two paths to its embedded blob:
 
-| Path                                   | Export          | Used by                     |
-|----------------------------------------|-----------------|-----------------------------|
-| `src/ts/embedded/serpent.ts`           | (raw blob)      | Build artifact, gitignored  |
-| `src/ts/serpent/embedded.ts`           | `serpentWasm`   | Consumer import             |
+| Path                                       | Export             | Used by                                   |
+|--------------------------------------------|--------------------|-------------------------------------------|
+| `src/ts/embedded/serpent.ts`               | (raw blob)         | Build artifact, gitignored                |
+| `src/ts/serpent/embedded.ts`               | `serpentWasm`      | Consumer import                           |
+| `src/ts/embedded/serpent-pool-worker.ts`   | `WORKER_SOURCE`    | Internal, consumed by `cipher-suite.ts`   |
 
-The per-module `embedded.ts` re-exports the generated blob as a named
-export. Consumers import from the `/embedded` subpath:
+The per-module `embedded.ts` re-exports the generated blob as a named export. Consumers import from the `/embedded` subpath:
 ```typescript
 import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
 ```
 
-The `src/ts/embedded/` directory is generated by `scripts/embed-wasm.ts`
-and is gitignored. These files are not meant to be created or edited by hand.
+The `src/ts/embedded/` directory is generated by `scripts/embed-wasm.ts` (WASM blobs) and `scripts/embed-workers.ts` (pool-worker IIFE bundles), and is gitignored. These files are not meant to be created or edited by hand.
 
 ### Embedded compression
 
-The embedded files contain gzip-compressed WASM encoded as base64.
-Compression reduces the embedded footprint from ~198 KB to ~33 KB across
-all four modules, with Serpent alone shrinking from ~167 KB to ~20 KB.
+The embedded files contain gzip-compressed WASM encoded as base64. Compression reduces the embedded footprint from ~198 KB to ~33 KB across all four modules, with Serpent alone shrinking from \~167 KB to \~20 KB.
 
 ### Memory allocation
 
-Every WASM instance receives a `WebAssembly.Memory` with exactly 3 pages
-(192 KB total). The memory size is fixed; modules do not grow their memory at runtime. This is a deliberate design choice: fixed memory prevents
-unexpected allocations and makes the memory layout predictable and auditable.
+Every WASM instance receives a `WebAssembly.Memory` with exactly 3 pages (192 KB total). The memory size is fixed; modules do not grow their memory at runtime. This is a deliberate design choice: fixed memory prevents unexpected allocations and makes the memory layout predictable and auditable.
 
 ---
 
-> ## Cross-References
->
-> - [index](./README.md) — Project Documentation index
-> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
-> - [init](./init.md) — the public `init()` API that uses this loader
-> - [wasm](./wasm.md) — WebAssembly primer: modules, instances, and memory model
+
+## Cross-References
+
+| Document | Description |
+| -------- | ----------- |
+| [index](./README.md) | Project Documentation index |
+| [architecture](./architecture.md) | architecture overview, module relationships, buffer layouts, and build pipeline |
+| [init](./init.md) | the public `init()` API that uses this loader |
+| [wasm](./wasm.md) | WebAssembly primer: modules, instances, and memory model |
+