leviathan-crypto 1.3.1 → 2.0.0

package/dist/chacha20/pool.js

@@ -1,188 +0,0 @@
-// src/ts/chacha20/pool.ts
-//
-// XChaCha20Poly1305Pool — parallel worker pool for XChaCha20-Poly1305 AEAD.
-// Dispatches independent encrypt/decrypt jobs across Web Workers, each with
-// its own WebAssembly.Instance and isolated linear memory.
-import { isInitialized } from '../init.js';
-// ── Module-private base64 decoder (copied from loader.ts) ────────────────────
-function base64ToBytes(b64) {
-    if (typeof atob === 'function') {
-        const raw = atob(b64);
-        const out = new Uint8Array(raw.length);
-        for (let i = 0; i < raw.length; i++)
-            out[i] = raw.charCodeAt(i);
-        return out;
-    }
-    return new Uint8Array(Buffer.from(b64, 'base64'));
-}
-// ── WASM module singleton ────────────────────────────────────────────────────
-let _wasmModule;
-async function getWasmModule() {
-    if (_wasmModule)
-        return _wasmModule;
-    const { WASM_BASE64 } = await import('../embedded/chacha20.js');
-    const bytes = base64ToBytes(WASM_BASE64);
-    _wasmModule = await WebAssembly.compile(bytes.buffer);
-    return _wasmModule;
-}
-// ── Worker spawning ──────────────────────────────────────────────────────────
-function spawnWorker(mod) {
-    return new Promise((resolve, reject) => {
-        const worker = new Worker(new URL('./pool.worker.js', import.meta.url), { type: 'module' });
-        const onMessage = (e) => {
-            cleanup();
-            if (e.data.type === 'ready') {
-                resolve(worker);
-            }
-            else {
-                worker.terminate();
-                reject(new Error(`leviathan-crypto: worker init failed: ${e.data.message}`));
-            }
-        };
-        const onError = (e) => {
-            cleanup();
-            worker.terminate();
-            reject(new Error(`leviathan-crypto: worker init failed: ${e.message}`));
-        };
-        const cleanup = () => {
-            worker.removeEventListener('message', onMessage);
-            worker.removeEventListener('error', onError);
-        };
-        worker.addEventListener('message', onMessage);
-        worker.addEventListener('error', onError);
-        worker.postMessage({ type: 'init', module: mod });
-    });
-}
-// ── Pool class ───────────────────────────────────────────────────────────────
-/**
- * Parallel worker pool for XChaCha20-Poly1305 AEAD.
- *
- * Each worker owns its own `WebAssembly.Instance` with isolated linear memory.
- * Jobs are dispatched round-robin to idle workers; excess jobs queue until a
- * worker frees up.
- *
- * **Warning:** Input buffers (`key`, `nonce`, `plaintext`/`ciphertext`, `aad`)
- * are transferred to the worker and neutered on the calling side. The caller
- * must copy any buffer they need to retain after calling `encrypt()`/`decrypt()`.
- */
-export class XChaCha20Poly1305Pool {
-    _workers;
-    _idle;
-    _queue;
-    _pending;
-    _nextId;
-    _disposed;
-    constructor(workers) {
-        this._workers = workers;
-        this._idle = [...workers];
-        this._queue = [];
-        this._pending = new Map();
-        this._nextId = 0;
-        this._disposed = false;
-        for (const w of workers) {
-            w.onmessage = (e) => this._onMessage(w, e);
-        }
-    }
-    /**
-     * Create a new pool. Requires `init(['chacha20'])` to have been called.
-     * Compiles the WASM module once and distributes it to all workers.
-     */
-    static async create(opts) {
-        if (!isInitialized('chacha20'))
-            throw new Error('leviathan-crypto: call init([\'chacha20\']) before using XChaCha20Poly1305Pool');
-        const n = opts?.workers ?? (typeof navigator !== 'undefined' ? navigator.hardwareConcurrency : undefined) ?? 4;
-        const mod = await getWasmModule();
-        // Sequential spawn — compatible with inline-worker test environments
-        const workers = [];
-        for (let i = 0; i < n; i++)
-            workers.push(await spawnWorker(mod));
-        return new XChaCha20Poly1305Pool(workers);
-    }
-    /**
-     * Encrypt plaintext with XChaCha20-Poly1305.
-     * Returns `ciphertext || tag` (plaintext.length + 16 bytes).
-     *
-     * **Warning:** All input buffers are transferred and neutered after dispatch.
-     */
-    encrypt(key, nonce, plaintext, aad = new Uint8Array(0)) {
-        if (this._disposed)
-            return Promise.reject(new Error('leviathan-crypto: pool is disposed'));
-        if (key.length !== 32)
-            return Promise.reject(new RangeError(`key must be 32 bytes (got ${key.length})`));
-        if (nonce.length !== 24)
-            return Promise.reject(new RangeError(`XChaCha20 nonce must be 24 bytes (got ${nonce.length})`));
-        return this._dispatch('encrypt', key, nonce, plaintext, aad);
-    }
-    /**
-     * Decrypt ciphertext with XChaCha20-Poly1305.
-     * Input is `ciphertext || tag` (at least 16 bytes).
-     *
-     * **Warning:** All input buffers are transferred and neutered after dispatch.
-     */
-    decrypt(key, nonce, ciphertext, aad = new Uint8Array(0)) {
-        if (this._disposed)
-            return Promise.reject(new Error('leviathan-crypto: pool is disposed'));
-        if (key.length !== 32)
-            return Promise.reject(new RangeError(`key must be 32 bytes (got ${key.length})`));
-        if (nonce.length !== 24)
-            return Promise.reject(new RangeError(`XChaCha20 nonce must be 24 bytes (got ${nonce.length})`));
-        if (ciphertext.length < 16)
-            return Promise.reject(new RangeError(`ciphertext too short — must include 16-byte tag (got ${ciphertext.length})`));
-        return this._dispatch('decrypt', key, nonce, ciphertext, aad);
-    }
-    /** Terminates all workers. Rejects all pending and queued jobs. */
-    dispose() {
-        if (this._disposed)
-            return;
-        this._disposed = true;
-        for (const w of this._workers)
-            w.terminate();
-        const err = new Error('leviathan-crypto: pool disposed');
-        for (const { reject } of this._pending.values())
-            reject(err);
-        for (const job of this._queue)
-            this._pending.get(job.id)?.reject(err);
-        this._pending.clear();
-        this._queue.length = 0;
-    }
-    /** Number of workers in the pool. */
-    get size() {
-        return this._workers.length;
-    }
-    /** Number of jobs currently queued (waiting for a free worker). */
-    get queueDepth() {
-        return this._queue.length;
-    }
-    // ── Internals ────────────────────────────────────────────────────────────
-    _dispatch(op, key, nonce, data, aad) {
-        return new Promise((resolve, reject) => {
-            const id = this._nextId++;
-            const job = { id, op, key, nonce, data, aad };
-            this._pending.set(id, { resolve, reject });
-            const worker = this._idle.pop();
-            if (worker)
-                this._send(worker, job);
-            else
-                this._queue.push(job);
-        });
-    }
-    _send(worker, job) {
-        worker.postMessage({ type: 'job', ...job }, [job.key.buffer, job.nonce.buffer, job.data.buffer, job.aad.buffer]);
-    }
-    _onMessage(worker, e) {
-        const msg = e.data;
-        const job = this._pending.get(msg.id);
-        if (!job)
-            return;
-        this._pending.delete(msg.id);
-        if (msg.type === 'result')
-            job.resolve(msg.data);
-        else
-            job.reject(new Error(msg.message));
-        const next = this._queue.shift();
-        if (next)
-            this._send(worker, next);
-        else
-            this._idle.push(worker);
-    }
-}

package/dist/chacha20/pool.worker.js

@@ -1,37 +0,0 @@
-// / <reference lib="webworker" />
-// src/ts/chacha20/pool.worker.ts
-//
-// Worker entry point for XChaCha20Poly1305Pool. Runs in a Web Worker or
-// worker_threads context — no access to the main thread's module cache.
-// Owns its own WebAssembly.Instance with its own linear memory.
-import { xcEncrypt, xcDecrypt } from './ops.js';
-let x;
-self.onmessage = async (e) => {
-    const msg = e.data;
-    if (msg.type === 'init') {
-        try {
-            const mem = new WebAssembly.Memory({ initial: 3, maximum: 3 });
-            const inst = await WebAssembly.instantiate(msg.module, { env: { memory: mem } });
-            x = inst.exports;
-            self.postMessage({ type: 'ready' });
-        }
-        catch (err) {
-            self.postMessage({ type: 'error', id: -1, message: err.message });
-        }
-        return;
-    }
-    if (!x) {
-        self.postMessage({ type: 'error', id: msg.id, message: 'worker not initialized' });
-        return;
-    }
-    try {
-        const { id, op, key, nonce, data, aad } = msg;
-        const result = op === 'encrypt'
-            ? xcEncrypt(x, key, nonce, data, aad)
-            : xcDecrypt(x, key, nonce, data, aad);
-        self.postMessage({ type: 'result', id, data: result }, [result.buffer]);
-    }
-    catch (err) {
-        self.postMessage({ type: 'error', id: msg.id, message: err.message });
-    }
-};

package/dist/docs/chacha20_pool.md

@@ -1,309 +0,0 @@
-# XChaCha20Poly1305Pool: Parallel Worker Pool for Authenticated Encryption
-
-> [!NOTE]
-> A worker pool that dispatches independent XChaCha20-Poly1305 AEAD operations
-> across multiple Web Workers, each with its own isolated WebAssembly instance.
->
-> See [ChaCha20-Poly1305 implementation audit](./chacha_audit.md) for algorithm correctness verifications.
-
-## Overview
-
-`XChaCha20Poly1305Pool` parallelizes XChaCha20-Poly1305 encrypt and decrypt
-operations across Web Workers. Each worker owns its own `WebAssembly.Instance`
-with its own linear memory -- there is no shared state between workers.
-
-Use the pool when you need to process many independent AEAD operations
-concurrently. Typical use cases include encrypting multiple independent messages,
-batch processing encrypted records, or any scenario where multiple independent
-encrypt/decrypt operations could benefit from parallelism.
-
-Use the single-instance `XChaCha20Poly1305` when operations are sequential, when
-you only process one message at a time, or when the overhead of worker
-communication is not justified by the operation size.
-
-**Throughput ceiling:** CPU-bound WASM throughput plateaus at
-`navigator.hardwareConcurrency`. Adding more workers beyond this adds scheduling
-overhead with no parallelism gain.
-
-**Per-job size limit:** Each job is limited to 64 KB, the same limit as the
-single-instance path. This is not a workaround limitation -- it is the correct
-security boundary for independent AEAD operations. Each job is one complete,
-independently authenticated AEAD operation. Do not split one logical message
-across multiple pool calls and concatenate results -- this provides no
-stream-level authenticity (reordering and truncation attacks go undetected).
-
----
-
-## Security Notes
-
-- **Input buffers are transferred (neutered) after dispatch.** Once you call
-  `encrypt()` or `decrypt()`, the `key`, `nonce`, `plaintext`/`ciphertext`, and
-  `aad` buffers are transferred to the worker via `Transferable`. The caller's
-  `Uint8Array` views become detached -- reading them after the call returns
-  zero-length buffers. If you need to retain any input after calling
-  `encrypt()`/`decrypt()`, copy it first with `.slice()`.
-
-- **64 KB limit is per independent AEAD operation.** Do not split one logical
-  message across multiple pool calls and concatenate the results. This creates a
-  stream without authentication -- an attacker can reorder, duplicate, or
-  truncate chunks without detection. A future chunked-AEAD streaming API is the
-  correct tool for large files.
-
-- **All XChaCha20-Poly1305 security properties apply.** Nonce uniqueness per key
-  is required. The 24-byte nonce is safe for random generation via
-  `crypto.getRandomValues()` (collision probability is negligible for 2^64
-  messages).
-
-- **Each worker owns isolated WASM memory.** Key material in one worker's linear
-  memory cannot leak to another worker, even in theory.
-
-- **Workers are terminated on `dispose()`.** All WASM memory is released when
-  the worker process ends. There is no lingering key material.
-
----
-
-## API Reference
-
-### `PoolOpts`
-
-```typescript
-interface PoolOpts {
-  /** Number of workers. Default: navigator.hardwareConcurrency ?? 4 */
-  workers?: number;
-}
-```
-
----
-
-### `XChaCha20Poly1305Pool.create(opts?)`
-
-Static async factory. Returns a `Promise<XChaCha20Poly1305Pool>`.
-
-```typescript
-static async create(opts?: PoolOpts): Promise<XChaCha20Poly1305Pool>
-```
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `opts.workers` | `number` | `navigator.hardwareConcurrency ?? 4` | Number of workers to spawn. |
-
-Throws if `init(['chacha20'])` has not been called.
-
-Direct construction with `new XChaCha20Poly1305Pool()` is not possible -- the
-constructor is private.
-
----
-
-### `encrypt(key, nonce, plaintext, aad?)`
-
-Encrypt plaintext with XChaCha20-Poly1305.
-
-```typescript
-encrypt(
-  key: Uint8Array,       // 32 bytes
-  nonce: Uint8Array,     // 24 bytes
-  plaintext: Uint8Array, // up to 64 KB
-  aad?: Uint8Array,      // optional additional authenticated data
-): Promise<Uint8Array>   // ciphertext || tag (plaintext.length + 16 bytes)
-```
-
-| Parameter | Type | Constraints | Description |
-|-----------|------|-------------|-------------|
-| `key` | `Uint8Array` | 32 bytes | Encryption key |
-| `nonce` | `Uint8Array` | 24 bytes | Unique nonce |
-| `plaintext` | `Uint8Array` | 0--65536 bytes | Data to encrypt |
-| `aad` | `Uint8Array` | any length | Additional authenticated data (default: empty) |
-
-Returns `ciphertext || tag` (`plaintext.length + 16` bytes).
-
-> [!WARNING]
-> All input buffers are transferred and neutered after dispatch.
-
-### `decrypt(key, nonce, ciphertext, aad?)`
-
-Decrypt ciphertext with XChaCha20-Poly1305.
-
-```typescript
-decrypt(
-  key: Uint8Array,        // 32 bytes
-  nonce: Uint8Array,      // 24 bytes
-  ciphertext: Uint8Array, // ciphertext || tag (at least 16 bytes)
-  aad?: Uint8Array,       // must match the AAD used during encryption
-): Promise<Uint8Array>    // plaintext
-```
-
-| Parameter | Type | Constraints | Description |
-|-----------|------|-------------|-------------|
-| `key` | `Uint8Array` | 32 bytes | Decryption key |
-| `nonce` | `Uint8Array` | 24 bytes | Same nonce used for encryption |
-| `ciphertext` | `Uint8Array` | >= 16 bytes | `ciphertext || tag` from `encrypt()` |
-| `aad` | `Uint8Array` | any length | Same AAD used during encryption (default: empty) |
-
-Returns the decrypted plaintext.
-
-Rejects with `Error('ChaCha20Poly1305: authentication failed')` if the tag does
-not match (tampered ciphertext, wrong key, wrong nonce, or wrong AAD).
-
-> [!WARNING]
-> All input buffers are transferred and neutered after dispatch.
-
-### `dispose()`
-
-Terminate all workers and reject all pending and queued jobs.
-
-```typescript
-dispose(): void
-```
-
-After `dispose()`, all calls to `encrypt()` and `decrypt()` reject immediately.
-Calling `dispose()` multiple times is safe (idempotent).
-
----
-
-### `size`
-
-Number of workers in the pool.
-
-```typescript
-get size(): number
-```
-
----
-
-### `queueDepth`
-
-Number of jobs currently queued (waiting for a free worker).
-
-```typescript
-get queueDepth(): number
-```
-
-Returns 0 when all workers are idle.
-
----
-
-## Performance Notes
-
-Throughput plateaus at `navigator.hardwareConcurrency` workers for CPU-bound
-WASM operations. Adding more workers beyond this count introduces scheduling
-overhead without additional parallelism.
-
-The `workers` option lets you tune the count:
-- **Default** (`navigator.hardwareConcurrency ?? 4`) -- optimal for most systems
-- **Fewer workers** -- useful if you need to leave cores available for other work
-- **More workers** -- only beneficial on hyperthreaded CPUs where
-  `hardwareConcurrency` includes virtual cores that provide some additional
-  throughput
-
-Each worker carries a fixed overhead: one `WebAssembly.Instance` (192 KB linear
-memory) plus the worker thread itself. For most workloads, the default is correct.
-
-Job dispatch uses `Transferable` buffers to avoid copy overhead on 64 KB payloads.
-The downside is that input buffers are neutered on the calling side -- see
-Security Notes.
-
----
-
-## Usage Examples
-
-### Basic -- create pool, encrypt/decrypt one message
-
-```typescript
-import { init, XChaCha20Poly1305Pool, randomBytes } from 'leviathan-crypto'
-
-await init(['chacha20'])
-
-const pool = await XChaCha20Poly1305Pool.create()
-
-const key   = randomBytes(32)
-const nonce = randomBytes(24)
-const plaintext = new TextEncoder().encode('Hello, world!')
-
-// Copy inputs before passing to the pool (they will be neutered)
-const ct = await pool.encrypt(key.slice(), nonce.slice(), plaintext.slice())
-const pt = await pool.decrypt(key.slice(), nonce.slice(), ct)
-console.log(new TextDecoder().decode(pt))  // "Hello, world!"
-
-pool.dispose()
-```
-
-### Concurrent burst -- `Promise.all()` over many independent messages
-
-```typescript
-import { init, XChaCha20Poly1305Pool, randomBytes } from 'leviathan-crypto'
-
-await init(['chacha20'])
-const pool = await XChaCha20Poly1305Pool.create()
-
-const messages = ['message-1', 'message-2', 'message-3', 'message-4']
-const key = randomBytes(32)
-
-// Each message gets its own nonce -- all encrypt concurrently
-const encrypted = await Promise.all(
-  messages.map(msg => {
-    const nonce = randomBytes(24)
-    const pt = new TextEncoder().encode(msg)
-    return pool.encrypt(key.slice(), nonce, pt)
-  })
-)
-
-pool.dispose()
-```
-
-### Manual worker count
-
-```typescript
-const pool = await XChaCha20Poly1305Pool.create({ workers: 4 })
-console.log(pool.size)  // 4
-```
-
-### Correct dispose pattern -- `try/finally`
-
-```typescript
-const pool = await XChaCha20Poly1305Pool.create()
-try {
-  const ct = await pool.encrypt(key, nonce, plaintext)
-  // ... use ct ...
-} finally {
-  pool.dispose()
-}
-```
-
-### What NOT to do -- splitting one message across pool calls
-
-```typescript
-// WRONG -- this is NOT secure
-const chunk1 = await pool.encrypt(key, nonce1, largeFile.subarray(0, 65536))
-const chunk2 = await pool.encrypt(key, nonce2, largeFile.subarray(65536))
-const result = concat(chunk1, chunk2)
-// ^ An attacker can reorder, duplicate, or truncate chunks undetected.
-//   There is no stream-level authentication.
-//   Use a future chunked-AEAD streaming API for large files.
-```
-
----
-
-## Error Conditions
-
-| Condition | What happens |
-|-----------|-------------|
-| `init()` not called | `create()` throws: `leviathan-crypto: call init(['chacha20']) before using XChaCha20Poly1305Pool` |
-| `new XChaCha20Poly1305Pool()` | Compile-time error -- the constructor is private |
-| Wrong key length | `encrypt()`/`decrypt()` reject with `RangeError` |
-| Wrong nonce length | `encrypt()`/`decrypt()` reject with `RangeError` |
-| Ciphertext shorter than 16 bytes | `decrypt()` rejects with `RangeError` |
-| Authentication failure | `decrypt()` rejects with `Error('ChaCha20Poly1305: authentication failed')` |
-| Pool disposed | `encrypt()`/`decrypt()` reject with `Error('leviathan-crypto: pool is disposed')` |
-| Worker init failure | `create()` rejects with error message from the worker |
-
----
-
-> ## Cross-References
->
-> - [index](./README.md) — Project Documentation index
-> - [chacha20](./chacha20.md) — single-instance XChaCha20-Poly1305 API
-> - [asm_chacha](./asm_chacha.md) — WASM implementation details (quarter-round, Poly1305 accumulator, HChaCha20)
-> - [wasm](./wasm.md) — WebAssembly primer: how one compiled module spawns many worker instances
-> - [fortuna](./fortuna.md) — another class using the `static async create()` factory pattern
-> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
-> - [chacha_audit.md](./chacha_audit.md) — XChaCha20-Poly1305 implementation audit