leviathan-crypto 1.0.0

package/dist/docs/init.md

@@ -0,0 +1,308 @@
+# Module Initialization and WASM Loading
+
+> [!NOTE]
+> The `init()` function is the entry point for leviathan-crypto. You must call it
+> before using any cryptographic class. It loads the WebAssembly modules that
+> perform the actual cryptographic work, caches them in memory, and makes them
+> available to all wrapper classes.
+
+## Overview
+
+leviathan-crypto runs all cryptographic computation inside WebAssembly modules.
+These modules are not available automatically, they need to be loaded and
+compiled before any cryptographic class (`Serpent`, `SHA256`, `ChaCha20`, etc.)
+can be used.
+
+`init()` handles this process for you. You tell it which modules you need, and
+it loads them. After that, every class backed by those modules is ready to use.
+
+Key properties:
+
+- **Required before use.** If you try to create a cryptographic class before
+  calling `init()`, you will get a clear error telling you what to do.
+- **Three loading modes.** Embedded (default, zero-config), streaming
+  (better performance for large apps), and manual (full control over how
+  binaries are provided).
+- **Idempotent.** Calling `init()` multiple times with the same module is
+  safe, it skips modules that are already loaded. This means you can call
+  `init()` in multiple places in your application without worrying about
+  redundant work.
+- **Async.** `init()` returns a Promise. Use `await` or `.then()` before
+  proceeding.
+
+---
+
+## Security Notes
+
+- **WASM runs outside the JavaScript JIT.** Cryptographic code executes in
+  WebAssembly, which provides more predictable execution timing compared to
+  optimized JavaScript. This reduces the risk of timing side-channels
+  introduced by the JIT compiler.
+- **Independent memory per module.** Each WASM module gets its own linear
+  memory (3 pages, 192 KB). Key material loaded into one module's memory
+  cannot be read by another module. There is no shared memory between modules.
+- **No silent auto-initialization.** Every wrapper class checks that its
+  backing module has been initialized. If it hasn't, the class throws an
+  error immediately rather than silently loading the module in the
+  background. This makes initialization explicit and auditable.
+
+---
+
+## API Reference
+
+### Types
+
+```typescript
+type Module = 'serpent' | 'chacha20' | 'sha2' | 'sha3'
+```
+
+The four WASM module families. Each one backs a group of related classes:
+
+| Module      | Classes it enables                                              |
+|-------------|----------------------------------------------------------------|
+| `'serpent'` | `Serpent`, `SerpentCbc`, `SerpentCtr`, `SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `Fortuna` |
+| `'chacha20'`| `ChaCha20`, `XChaCha20Poly1305`                                |
+| `'sha2'`    | `SHA256`, `SHA384`, `SHA512`, `HMAC` (SHA-2 based), `Fortuna`  |
+| `'sha3'`    | `SHA3`, `SHAKE128`, `SHAKE256`                                 |
+
+```typescript
+type Mode = 'embedded' | 'streaming' | 'manual'
+```
+
+How the WASM binary is loaded. See the [Usage Examples](#usage-examples) section
+for when to use each mode.
+
+```typescript
+interface InitOpts {
+  wasmUrl?: URL | string
+  wasmBinary?: Partial<Record<Module, Uint8Array | ArrayBuffer>>
+}
+```
+
+Optional configuration object. Which fields are required depends on the mode:
+
+| Mode        | Required fields    | Description                                     |
+|-------------|--------------------|-------------------------------------------------|
+| `embedded`  | (none)             | Binaries are bundled in the package              |
+| `streaming` | `wasmUrl`          | Base URL where `.wasm` files are served          |
+| `manual`    | `wasmBinary`       | A map of module names to raw WASM binary data    |
+
+---
+
+### Functions
+
+#### `init(modules, mode?, opts?)` — public API (exported from root barrel)
+
+> [!NOTE]
+> `init()` is no longer exported from `init.ts`. It is defined in the
+> root barrel (`src/ts/index.ts`) and dispatches to each module's own init
+> function (`serpentInit`, `chacha20Init`, `sha2Init`, `sha3Init`).
+> See [README.md](./README.md) for details.
+
+The public `init()` signature is unchanged:
+
+```typescript
+async function init(
+  modules: Module | Module[],
+  mode?: Mode,        // default: 'embedded'
+  opts?: InitOpts,
+): Promise<void>
+```
+
+---
+
+#### `initModule(mod, embeddedThunk, mode?, opts?)` — internal
+
+```typescript
+async function initModule(
+  mod: Module,
+  embeddedThunk: () => Promise<string>,
+  mode?: Mode,        // default: 'embedded'
+  opts?: InitOpts,
+): Promise<void>
+```
+
+Internal initialization function. Called by each module's own init function
+(`serpentInit`, `chacha20Init`, `sha2Init`, `sha3Init`), not by consumers
+directly. Each module passes its own embedded thunk so the
+dependency graph stays isolated per module, enabling tree-shaking.
+
+**Parameters:**
+
+- `mod`: The module name to initialize.
+- `embeddedThunk`: A function that returns a Promise resolving to the
+  base64-encoded WASM binary. Each module defines its own thunk pointing to
+  its own embedded file.
+- `mode`: The loading strategy. Defaults to `'embedded'`.
+- `opts`: Configuration for `'streaming'` and `'manual'` modes.
+
+**Returns:** A Promise that resolves when the module is loaded and cached.
+
+**Idempotent:** If the module is already initialized, returns immediately.
+
+**Throws:**
+
+- `'leviathan-crypto: streaming mode requires wasmUrl'` if mode is
+  `'streaming'` and `opts.wasmUrl` is not provided.
+- `'leviathan-crypto: manual mode requires wasmBinary['<mod>']'` if mode
+  is `'manual'` and the binary for the requested module is missing.
+- `'leviathan-crypto: unknown mode '<mode>''` if an invalid mode string
+  is passed.
+
+> [!NOTE]
+> The previous design exported `init()` from `init.ts`,
+> which contained a central `embeddedLoaders` record mapping every module name
+> to its embedded import. This meant any consumer importing `init()`,
+> even through a subpath like `leviathan-crypto/serpent`, pulled all four
+> embedded binaries into the bundle. Moving `init()` to the root barrel and
+> giving each module its own thunk isolates the dependency graph so bundlers
+> can tree-shake unused modules, optimizing build size.
+
+---
+
+#### `getInstance(mod)`
+
+```typescript
+function getInstance(mod: Module): WebAssembly.Instance
+```
+
+Returns the cached WebAssembly instance for a module. This is used internally
+by wrapper classes, you do not normally need to call it yourself.
+
+**Throws:**
+`'leviathan-crypto: call init(['<mod>']) before using this class'` if the
+module has not been initialized.
+
+---
+
+#### `isInitialized(mod)`
+
+```typescript
+function isInitialized(mod: Module): boolean
+```
+
+Returns `true` if the given module has been loaded and cached (read-only).
+Exported from both `init.ts` and the root barrel (`src/ts/index.ts`).
+
+> [!NOTE]
+> `isInitialized` is a diagnostic indicator only — not a control mechanism.
+> Use `init()` to initialize modules; do not guard calls on this value.
+
+---
+
+#### `_resetForTesting()`
+
+```typescript
+function _resetForTesting(): void
+```
+
+Clears all cached WASM instances. This is a testing utility, it allows test
+suites to reset the initialization state between test runs. Do not use this in
+production code.
+
+---
+
+## Usage Examples
+
+### Embedded mode (default: simplest)
+
+This is the recommended mode for most applications. The WASM binaries are
+bundled inside the package as base64-encoded strings, so there are no extra
+files to serve or fetch.
+
+```typescript
+import { init, SHA256 } from 'leviathan-crypto'
+
+await init('sha2')
+
+const hash = new SHA256()
+const digest = hash.hash(myData)
+```
+
+### Initializing multiple modules at once
+
+Pass an array to load several modules in a single call:
+
+```typescript
+import { init, Serpent, SHA256 } from 'leviathan-crypto'
+
+await init(['serpent', 'sha2'])
+
+const cipher = new Serpent(key)
+const hash = new SHA256()
+```
+
+### Streaming mode (better performance for large apps)
+
+Streaming mode fetches `.wasm` files from a URL and uses the browser's
+streaming compilation (`WebAssembly.instantiateStreaming`). This can be
+faster than embedded mode because the browser can begin compiling the WASM
+binary while it is still downloading.
+
+You must serve the `.wasm` files from your web server and provide the base
+URL where they are hosted. The files must be served with the
+`Content-Type: application/wasm` header.
+
+```typescript
+import { init, Serpent } from 'leviathan-crypto'
+
+await init('serpent', 'streaming', {
+  wasmUrl: '/static/wasm/'
+})
+
+const cipher = new Serpent(key)
+```
+
+The library knows the filename for each module (e.g. `serpent.wasm`,
+`sha2.wasm`). You only need to provide the directory URL.
+
+### Manual mode (full control)
+
+Manual mode lets you provide the raw WASM binary yourself. This is useful if
+you have a custom build pipeline, want to load binaries from a non-standard
+source, or need to verify the binary before passing it to the library.
+
+```typescript
+import { init, SHA256 } from 'leviathan-crypto'
+
+// Load the binary however you like
+const wasmBinary = await fetch('/my-custom-path/sha2.wasm')
+  .then(r => r.arrayBuffer())
+
+await init('sha2', 'manual', {
+  wasmBinary: { sha2: new Uint8Array(wasmBinary) }
+})
+
+const hash = new SHA256()
+```
+
+### Checking if a module is initialized
+
+```typescript
+import { isInitialized } from 'leviathan-crypto'
+
+if (!isInitialized('sha2')) {
+  await init('sha2')
+}
+```
+
+---
+
+## Error Conditions
+
+| Situation                                 | What happens                                                                                 |
+|-------------------------------------------|----------------------------------------------------------------------------------------------|
+| Using a class before calling `init()`     | Throws: `"leviathan-crypto: call init(['<mod>']) before using this class"`                    |
+| Streaming mode without `wasmUrl`          | Throws: `"leviathan-crypto: streaming mode requires wasmUrl"`                                |
+| Manual mode without the needed binary     | Throws: `"leviathan-crypto: manual mode requires wasmBinary['<mod>']"`                       |
+| Unknown mode string                       | Throws: `"leviathan-crypto: unknown mode '<mode>'"`                                          |
+| Calling `init()` for an already-loaded module | No error. Module is silently skipped (idempotent behavior)                          |
+
+---
+
+## Cross-References
+
+- [README.md](./README.md) — package overview and quick-start guide
+- [loader.md](./loader.md) — WASM binary loading strategies (internal details)
+- [architecture.md](./architecture.md) — architecture overview, module structure, and build pipeline
+- [wasm.md](./wasm.md) — WebAssembly primer: modules, instances, memory, and the init gate

package/dist/docs/loader.md

@@ -0,0 +1,206 @@
+# 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.
+
+## Overview
+
+When you call `init()`, it delegates the work of obtaining and compiling the
+WASM binary to the loader. The loader supports three strategies:
+
+- **Embedded** -- The WASM binary is already bundled in the package as a
+  base64-encoded string. The loader decodes it and instantiates the module.
+  No network requests are made. This is the default and simplest option.
+- **Streaming** -- The loader fetches the `.wasm` file from a URL you provide
+  and uses the browser's streaming compilation API. The browser can start
+  compiling the binary while it is still downloading, which can improve
+  load times for larger modules.
+- **Manual** -- You provide the raw binary data (as a `Uint8Array` or
+  `ArrayBuffer`) and the loader instantiates it directly. This gives you
+  full control over how the binary is obtained.
+
+All three 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.
+- **Streaming mode 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.
+- **Manual mode places integrity responsibility on you.** The loader
+  instantiates whatever binary you provide. If you use manual mode, you are
+  responsible for verifying that the binary is authentic and unmodified.
+- **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. This means key material loaded into 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.
+
+### `loadEmbedded(thunk)`
+
+```typescript
+async function loadEmbedded(
+  thunk: () => Promise<string>,
+): Promise<WebAssembly.Instance>
+```
+
+Loads a WASM module from an embedded base64-encoded string obtained by calling
+the provided thunk.
+
+**How it works:**
+
+1. Calls the thunk, which dynamically imports the embedded binary file and
+   returns the base64-encoded WASM string.
+2. Decodes the base64 string to raw bytes.
+3. Instantiates the WASM module with a fresh 3-page `WebAssembly.Memory`.
+
+The thunk is provided by each module's own `init()` function (e.g.
+`serpent/index.ts` passes `() => import('../embedded/serpent.js').then(m => m.WASM_BASE64)`).
+This design means `loader.ts` has no knowledge of module names or embedded file
+paths -- each module owns its own embedded import, enabling tree-shaking.
+
+**Parameters:**
+
+- `thunk` -- A function that returns a Promise resolving to a base64-encoded
+  WASM binary string. Each module's `index.ts` defines its own thunk pointing
+  to its own embedded file.
+
+**Returns:** A Promise that resolves to a `WebAssembly.Instance`.
+
+**Error conditions:**
+
+- If the embedded binary file does not exist, this means the build step
+  (`scripts/embed-wasm.ts`) has not been run. Run `npm run build` to
+  generate the embedded files.
+
+---
+
+### `loadStreaming(mod, baseUrl, filename)`
+
+```typescript
+async function loadStreaming(
+  _mod: Module,
+  baseUrl: URL | string,
+  filename: string,
+): Promise<WebAssembly.Instance>
+```
+
+Loads a WASM module by fetching it from a URL and using streaming compilation.
+
+**How it works:**
+
+1. Constructs the full URL by combining `baseUrl` and `filename`
+   (e.g. `https://example.com/wasm/` + `serpent.wasm`).
+2. Calls `WebAssembly.instantiateStreaming(fetch(url), imports)`, which
+   allows the browser to compile the module while it downloads.
+3. Creates a fresh 3-page `WebAssembly.Memory` for the instance.
+
+**Parameters:**
+
+- `_mod` -- The module name (currently unused in the function body, but
+  passed for consistency).
+- `baseUrl` -- The base URL where `.wasm` files are hosted. Can be a
+  `URL` object or a string.
+- `filename` -- The `.wasm` filename (e.g. `'serpent.wasm'`). This is
+  determined by `init.ts` using its internal filename mapping.
+
+**Returns:** A Promise that resolves to a `WebAssembly.Instance`.
+
+**Error conditions:**
+
+- Network failure (server unreachable, 404, etc.) will cause the Promise
+  to reject.
+- If the server does not respond with `Content-Type: application/wasm`,
+  the browser will reject the streaming compilation. This is a common
+  issue with misconfigured web servers -- ensure your server is configured
+  to serve `.wasm` files with the correct MIME type.
+
+---
+
+### `loadManual(binary)`
+
+```typescript
+async function loadManual(
+  binary: Uint8Array | ArrayBuffer,
+): Promise<WebAssembly.Instance>
+```
+
+Loads a WASM module from a raw binary you provide directly.
+
+**How it works:**
+
+1. Converts `ArrayBuffer` to `Uint8Array` if needed.
+2. Instantiates the WASM module with a fresh 3-page `WebAssembly.Memory`.
+
+**Parameters:**
+
+- `binary` -- The raw WASM binary as a `Uint8Array` or `ArrayBuffer`.
+
+**Returns:** A Promise that resolves to a `WebAssembly.Instance`.
+
+**Error conditions:**
+
+- If the binary is not a valid WASM module, `WebAssembly.instantiate` will
+  throw. The error message will come from the browser's WASM engine and
+  will typically mention a validation or compilation failure.
+
+---
+
+## Internal Details
+
+### Embedded binary ownership
+
+Each module's `index.ts` owns the dynamic import to its own embedded binary
+file. The loader has no knowledge of module names or file paths -- it receives
+a thunk from `initModule()` and calls it. This means `loader.ts` has no
+dependency on any embedded file, which enables bundlers to tree-shake unused
+modules.
+
+| Module      | Thunk defined in              | Embedded file path         |
+|-------------|-------------------------------|----------------------------|
+| `serpent`   | `serpent/index.ts`            | `./embedded/serpent.js`    |
+| `chacha20`  | `chacha20/index.ts`           | `./embedded/chacha.js`     |
+| `sha2`      | `sha2/index.ts`               | `./embedded/sha2.js`       |
+| `sha3`      | `sha3/index.ts`               | `./embedded/sha3.js`       |
+
+The embedded `.js` files are generated by the build script
+(`scripts/embed-wasm.ts`) and are gitignored. They are not meant to be
+created or edited by hand.
+
+### Base64 decoding
+
+The loader handles base64 decoding in both browser and Node.js environments:
+
+- **Browser:** Uses the built-in `atob()` function.
+- **Node.js:** Falls back to `Buffer.from(b64, 'base64')`.
+
+### 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
+
+- [README.md](./README.md) — package overview and quick-start guide
+- [architecture.md](./architecture.md) — architecture overview and build pipeline
+- [init.md](./init.md) — the public `init()` API that uses this loader
+- [wasm.md](./wasm.md) — WebAssembly primer: modules, instances, and memory model