leviathan-crypto 2.0.1 → 3.0.0

package/dist/docs/init.md

@@ -1,302 +0,0 @@
-# Module Initialization and WASM Loading
-
-> [!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.
-
-> ### Table of Contents
-> - [Overview](#overview)
-> - [Security Notes](#security-notes)
-> - [API Reference](#api-reference)
-> - [Usage Examples](#usage-examples)
-> - [Error Conditions](#error-conditions)
-
----
-
-## Overview
-
-leviathan-crypto runs all cryptographic computation inside WebAssembly modules.
-These modules are not loaded automatically. You tell `init()` which modules you
-need and provide a source for each one. After that, every class backed by those
-modules is ready to use.
-
-`init()` is idempotent. Calling it multiple times with the same module is safe.
-It skips modules already loaded, so you can call `init()` in multiple places
-without redundant work. It returns a Promise. Always `await` it before
-constructing any class.
-
-If you try to use a cryptographic class before calling `init()`, you get a clear
-error telling you exactly which module to load.
-
----
-
-## Security Notes
-
-**WASM runs outside the JavaScript JIT.** Cryptographic code executes in
-WebAssembly, which provides more predictable execution timing than optimized
-JavaScript. This reduces the risk of timing side-channels introduced by the
-JIT compiler.
-
-**Each module gets its own linear memory.** Every WASM module receives 3 pages
-(192 KB) of independent memory. Key material in one module cannot be read by
-another. There is no shared memory between modules.
-
-**No silent auto-initialization.** Every wrapper class checks that its backing
-module has been initialized. If it has not, the class throws immediately rather
-than loading the module in the background. Initialization is explicit and
-auditable.
-
----
-
-## API Reference
-
-### Types
-
-```typescript
-type Module = 'serpent' | 'chacha20' | 'sha2' | 'sha3' | 'keccak' | 'kyber'
-```
-
-The WASM module families. Each one backs a group of related classes.
-`'keccak'` is an alias for `'sha3'` — same WASM binary, same instance slot.
-
-| Module | Classes it enables |
-|---|---|
-| `'serpent'` | `Serpent`, `SerpentCbc`, `SerpentCtr` |
-| `'serpent'` + `'sha2'` | `SerpentCipher`, `Seal` (with `SerpentCipher`), `SealStream`, `OpenStream`, `Fortuna` — see [aead.md](./aead.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` |
-| `'sha3'` / `'keccak'` | `SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256` |
-| `'kyber'` | `MlKem512`, `MlKem768`, `MlKem1024` (also requires `'sha3'`) — see [kyber.md](./kyber.md) |
-| `'kyber'` + `'sha3'` + inner cipher modules | `KyberSuite`, `MlKem512`, `MlKem768`, `MlKem1024` — see [kyber.md](./kyber.md) |
-
-```typescript
-type WasmSource = string | URL | ArrayBuffer | Uint8Array
-               | WebAssembly.Module | Response | Promise<Response>
-```
-
-A value that resolves to a WASM binary. The loading strategy is inferred from
-the type:
-
-| Source type | What happens |
-|---|---|
-| `string` | Treated as a gzip+base64 embedded blob. Decoded and decompressed. |
-| `URL` | Fetched with streaming compilation (`WebAssembly.compileStreaming`). |
-| `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`. |
-
----
-
-### Functions
-
-#### init()
-
-```typescript
-async function init(
-  sources: Partial<Record<Module, WasmSource>>,
-): Promise<void>
-```
-
-Initializes one or more WASM modules. Pass an object mapping module names to
-their `WasmSource`. Only modules present in the object are loaded. Others are
-left untouched.
-
----
-
-#### Per-module init functions
-
-Each module subpath exports its own init function for tree-shakeable imports.
-These take a single `WasmSource` argument.
-
-```typescript
-async function serpentInit(source: WasmSource): Promise<void>
-async function chacha20Init(source: WasmSource): Promise<void>
-async function sha2Init(source: WasmSource): Promise<void>
-async function sha3Init(source: WasmSource): Promise<void>
-async function keccakInit(source: WasmSource): Promise<void>
-async function kyberInit(source: WasmSource): Promise<void>
-```
-
-Each function initializes only its own WASM module, keeping other modules out
-of your bundle.
-
----
-
-#### Embedded subpath exports
-
-The `/embedded` subpath for each module provides the gzip+base64 blob as a
-ready-to-use `WasmSource`:
-
-| Subpath | Export |
-|---|---|
-| `leviathan-crypto/serpent/embedded` | `serpentWasm` |
-| `leviathan-crypto/chacha20/embedded` | `chacha20Wasm` |
-| `leviathan-crypto/sha2/embedded` | `sha2Wasm` |
-| `leviathan-crypto/sha3/embedded` | `sha3Wasm` |
-| `leviathan-crypto/keccak/embedded` | `keccakWasm` |
-| `leviathan-crypto/kyber/embedded` | `kyberWasm` |
-
-`keccakWasm` and `sha3Wasm` are the same gzip+base64 blob. Both point to `sha3.wasm`.
-
-> [!NOTE]
-> `MlKem512`, `MlKem768`, and `MlKem1024` require both `kyber` and `sha3`
-> (or `keccak`) to be initialized. The kyber module handles polynomial arithmetic.
-> The sha3 module provides the Keccak sponge operations used for key generation
-> and encapsulation.
-
----
-
-#### isInitialized()
-
-```typescript
-function isInitialized(mod: Module): boolean
-```
-
-Returns `true` if the given module has been loaded and cached. Exported from
-both `init.ts` and the root barrel.
-
-> [!NOTE]
-> `isInitialized` is a diagnostic indicator, not a control mechanism. Use
-> `init()` to load modules. Do not guard calls on this value.
-
----
-
-#### getInstance()
-
-```typescript
-function getInstance(mod: Module): WebAssembly.Instance
-```
-
-Returns the cached WebAssembly instance for a module. Used internally by
-wrapper classes. You do not normally need to call this yourself.
-
-Throws `'leviathan-crypto: call init({ <mod>: ... }) before using this class'`
-if the module has not been initialized.
-
----
-
-#### compileWasm()
-
-```typescript
-async function compileWasm(source: WasmSource): Promise<WebAssembly.Module>
-```
-
-Compiles a `WasmSource` to a `WebAssembly.Module` without instantiating it.
-Used by pool infrastructure to send compiled modules to workers. See
-[loader.md](./loader.md) for details.
-
----
-
-#### _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)
-
-The WASM binaries are bundled inside the package as gzip+base64 strings. Import
-the blob from the module's `/embedded` subpath and pass it to `init()`.
-
-```typescript
-import { init } from 'leviathan-crypto'
-import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
-import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded'
-
-await init({ serpent: serpentWasm, sha2: sha2Wasm })
-```
-
-### Per-module init (tree-shaking)
-
-Use the subpath init function when you need one module and want the smallest
-possible bundle:
-
-```typescript
-import { serpentInit } from 'leviathan-crypto/serpent'
-import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
-
-await serpentInit(serpentWasm)
-```
-
-### Keccak alias (for ML-KEM)
-
-`'keccak'` is an alias for `'sha3'`. Both resolve to the same WASM binary and
-the same instance slot. Use it when you want the semantically correct primitive
-name for ML-KEM consumers:
-
-```typescript
-import { init } from 'leviathan-crypto'
-import { keccakWasm } from 'leviathan-crypto/keccak/embedded'
-
-await init({ keccak: keccakWasm })
-// isInitialized('sha3') === true — same slot
-// isInitialized('keccak') === true — alias resolves symmetrically
-```
-
-Or via the subpath directly:
-
-```typescript
-import { keccakInit, SHAKE128, SHA3_256 } from 'leviathan-crypto/keccak'
-import { keccakWasm } from 'leviathan-crypto/keccak/embedded'
-
-await keccakInit(keccakWasm)
-```
-
-### URL-based loading (CDN)
-
-Pass a `URL` to fetch and compile the `.wasm` file via streaming compilation.
-The server must respond with `Content-Type: application/wasm`.
-
-```typescript
-await init({ serpent: new URL('https://unpkg.com/leviathan-crypto/dist/serpent.wasm') })
-```
-
-### Pre-compiled module (edge runtimes)
-
-If you have already compiled the binary, for example from a KV cache, pass the
-`WebAssembly.Module` directly:
-
-```typescript
-const mod = await WebAssembly.compile(bytes)
-await init({ serpent: mod })
-```
-
-### Checking initialization state
-
-```typescript
-import { isInitialized } from 'leviathan-crypto'
-
-if (!isInitialized('sha2')) {
-  // handle accordingly
-}
-```
-
----
-
-## Error Conditions
-
-| Situation | What happens |
-|---|---|
-| Using a class before calling `init()` | Throws: `"leviathan-crypto: call init({ ${mod}: ... }) before using this class"` |
-| Invalid `WasmSource` (null, number, etc.) | Throws: `TypeError` with a descriptive message |
-| Empty string source | Throws: `"leviathan-crypto: invalid WasmSource — empty string"` |
-| Calling `init()` for an already-loaded module | No error. Module is silently skipped. |
-
----
-
-> ## 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

package/dist/docs/loader.md

@@ -1,161 +0,0 @@
-# WASM Binary Loading Strategies
-
-> [!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.
-
-> ### Table of Contents
-> - [Overview](#overview)
-> - [Security Notes](#security-notes)
-> - [API Reference](#api-reference)
-> - [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:
-
-**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.
-
-**URL.** Fetches the `.wasm` file and uses the browser's streaming compilation API. The browser can start compiling while still downloading.
-
-**ArrayBuffer / Uint8Array.** Raw WASM bytes, compiled directly.
-
-**WebAssembly.Module.** Already compiled. Instantiated immediately. Useful for edge runtimes and KV-cached modules.
-
-**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.
-
----
-
-## Security Notes
-
-**Embedded mode requires no network access.** The WASM binary is part of the installed package. This eliminates the risk of a compromised CDN or man-in-the-middle attack altering the binary at load time.
-
-**URL-based loading requires correct MIME type.** The `.wasm` files must be served with `Content-Type: application/wasm`. This is a browser requirement for `WebAssembly.instantiateStreaming`. If the header is missing or wrong, the browser will reject the response.
-
-**Raw binary / Module sources place integrity responsibility on you.** The loader instantiates whatever binary you provide. If you supply your own bytes or pre-compiled Module, you are responsible for verifying authenticity.
-
-**Each module gets its own memory.** Every instantiation creates a fresh `WebAssembly.Memory` with 3 pages (192 KB). Modules cannot share or access each other's memory. Key material in one module's memory space is isolated from all other modules.
-
----
-
-## 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.
-
-### `loadWasm(source)`
-```typescript
-async function loadWasm(source: WasmSource): Promise<WebAssembly.Instance>
-```
-
-Loads and instantiates a WASM module from any accepted source type. Each
-instance receives a fresh 3-page `WebAssembly.Memory`.
-
-**Source type handling:**
-
-| Source type                    | Loading path                                                         |
-|--------------------------------|----------------------------------------------------------------------|
-| `string`                       | Decoded from gzip+base64 via `decodeWasm()`, then `WebAssembly.instantiate()`. |
-| `URL`                          | `WebAssembly.instantiateStreaming(fetch(url))`.                      |
-| `ArrayBuffer`                  | `WebAssembly.instantiate()`.                                         |
-| `Uint8Array`                   | `WebAssembly.instantiate()`.                                         |
-| `WebAssembly.Module`           | `WebAssembly.instantiate(module, imports)`.                          |
-| `Response` / `Promise<Response>` | `WebAssembly.instantiateStreaming()`.                              |
-
-**Throws:**
-
-- `TypeError` if `source` is null, numeric, or otherwise unrecognised.
-- `TypeError` with `"empty string"` if `source` is an empty string.
-
-**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).
-
----
-
-### `compileWasm(source)`
-```typescript
-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.
-
-**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()`.
-
----
-
-### `decodeWasm(b64)`
-```typescript
-async function decodeWasm(b64: string): Promise<Uint8Array>
-```
-
-Decodes a gzip-compressed, base64-encoded WASM string to raw bytes.
-
-1. Base64-decodes the string using the shared `base64ToBytes` utility.
-2. Decompresses the result using `DecompressionStream('gzip')`.
-
-**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).
-
-Exported for use by pool worker launchers that need to decode blobs
-before spawning threads.
-
----
-
-## Internal Details
-
-### Embedded binary structure
-
-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             |
-
-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.
-
-### 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.
-
-### 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.
-
----
-
-> ## 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