leviathan-crypto 2.0.0 → 2.1.0

package/dist/ratchet/root-kdf.js

@@ -0,0 +1,124 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ratchet/root-kdf.ts
+//
+// Root KDF functions for the Sparse Post-Quantum Ratchet (spec §7.2).
+// Implements KDF_SCKA_INIT (ratchetInit) and KDF_SCKA_RK (kemRatchetEncap/Decap).
+import { HKDF_SHA256 } from '../sha2/index.js';
+import { isInitialized } from '../init.js';
+import { wipe, concat, utf8ToBytes } from '../utils.js';
+// Signal Double Ratchet §7.2 — info strings
+const INFO_INIT = utf8ToBytes('leviathan-ratchet-v1 Chain Start');
+const INFO_ROOT = utf8ToBytes('leviathan-ratchet-v1 Chain Add Epoch');
+// INFO_CHAIN ('leviathan-ratchet-v1 Chain Step') is used in kdf-chain.ts
+const ZERO_SALT = new Uint8Array(32);
+// HKDF-SHA-256 root step (KDF_SCKA_INIT and KDF_SCKA_RK share this shape).
+// ikm    = 32-byte secret (shared secret or sk)
+// salt   = 32-byte salt (zero bytes for init, rk for KEM ratchet)
+// info   = protocol info bytes
+// length = 96
+// → { nextRootKey: [0:32], sendChainKey: [32:64], recvChainKey: [64:96] }
+// Wipes okm after slicing.
+function kdfRoot(secret, salt, info) {
+    const h = new HKDF_SHA256();
+    try {
+        const okm = h.derive(secret, salt, info, 96);
+        const nextRootKey = okm.slice(0, 32);
+        const sendChainKey = okm.slice(32, 64);
+        const recvChainKey = okm.slice(64, 96);
+        wipe(okm);
+        return { nextRootKey, sendChainKey, recvChainKey };
+    }
+    finally {
+        h.dispose();
+    }
+}
+// u32 big-endian length prefix — same convention as serpent/cipher-suite.ts AAD encoding.
+function u32be(n) {
+    if (!Number.isInteger(n) || n < 0 || n > 0xFFFFFFFF)
+        throw new RangeError(`u32be: n must be an integer in [0, 0xFFFFFFFF] (got ${n})`);
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n, false);
+    return b;
+}
+// KEM ratchet info — binds peerEk, kemCt, and context with u32be length prefixes.
+// Defense-in-depth: the HKDF output is tied to the exact (peerEk, kemCt, context)
+// tuple used, not just the KEM shared secret. An attacker who substitutes any of
+// these inputs derives a different chain key trio, regardless of the KEM transcript.
+function buildRootInfo(peerEk, kemCt, context) {
+    const ctxBytes = context ?? new Uint8Array(0);
+    return concat(INFO_ROOT, u32be(peerEk.length), peerEk, u32be(kemCt.length), kemCt, u32be(ctxBytes.length), ctxBytes);
+}
+// KDF_SCKA_INIT — spec §7.2
+// Derives initial root key, send chain key, and receive chain key from a
+// shared secret sk. Optional context bytes are appended to the info string.
+export function ratchetInit(sk, context) {
+    if (!isInitialized('sha2'))
+        throw new Error('leviathan-crypto: call init({ sha2: ... }) before using ratchetInit');
+    if (sk.length !== 32)
+        throw new RangeError('ratchetInit: sk must be 32 bytes');
+    const info = context != null && context.length > 0 ? concat(INFO_INIT, context) : INFO_INIT;
+    const { nextRootKey, sendChainKey, recvChainKey } = kdfRoot(sk, ZERO_SALT, info);
+    return { nextRootKey, sendChainKey, recvChainKey };
+}
+// KDF_SCKA_RK — encapsulation side (spec §7.2)
+// Generates a fresh KEM ciphertext, derives next epoch keys from the shared secret.
+// `peerEk` and `kemCt` are bound into the HKDF info string (defense-in-depth).
+export function kemRatchetEncap(kem, rk, peerEk, context) {
+    if (!isInitialized('sha2'))
+        throw new Error('leviathan-crypto: call init({ sha2: ... }) before using kemRatchetEncap');
+    if (rk.length !== 32)
+        throw new RangeError('kemRatchetEncap: rk must be 32 bytes');
+    const { ciphertext: kemCt, sharedSecret } = kem.encapsulate(peerEk);
+    const info = buildRootInfo(peerEk, kemCt, context);
+    try {
+        const { nextRootKey, sendChainKey, recvChainKey } = kdfRoot(sharedSecret, rk, info);
+        return { nextRootKey, sendChainKey, recvChainKey, kemCt };
+    }
+    finally {
+        wipe(sharedSecret);
+    }
+}
+// KDF_SCKA_RK — decapsulation side (spec §7.2)
+// Recovers the shared secret from the KEM ciphertext, derives next epoch keys.
+// The chain key slots are swapped relative to the encap side: what the KDF
+// labels 'sendChainKey' (A→B direction) becomes the decap side's recvChainKey,
+// and vice versa — Alice's send IS Bob's receive.
+//
+// `ownEk` is the local party's encapsulation key (the same public key the
+// encap side targeted as `peerEk`). It must be passed explicitly so both
+// sides bind the identical (peerEk, kemCt) pair into the HKDF info string.
+export function kemRatchetDecap(kem, rk, dk, kemCt, ownEk, context) {
+    if (!isInitialized('sha2'))
+        throw new Error('leviathan-crypto: call init({ sha2: ... }) before using kemRatchetDecap');
+    if (rk.length !== 32)
+        throw new RangeError('kemRatchetDecap: rk must be 32 bytes');
+    const sharedSecret = kem.decapsulate(dk, kemCt);
+    const info = buildRootInfo(ownEk, kemCt, context);
+    try {
+        const { nextRootKey, sendChainKey: recvChainKey, recvChainKey: sendChainKey } = kdfRoot(sharedSecret, rk, info);
+        return { nextRootKey, sendChainKey, recvChainKey };
+    }
+    finally {
+        wipe(sharedSecret);
+    }
+}

package/dist/ratchet/skipped-key-store.d.ts

@@ -0,0 +1,14 @@
+import { KDFChain } from './kdf-chain.js';
+import type { ResolveHandle, SkippedKeyStoreOpts } from './types.js';
+export declare class SkippedKeyStore {
+    private _store;
+    private _maxCacheSize;
+    private _maxSkipPerResolve;
+    constructor(opts?: SkippedKeyStoreOpts);
+    private _evictOldest;
+    resolve(chain: KDFChain, counter: number): ResolveHandle;
+    private _makeHandle;
+    advanceToBoundary(chain: KDFChain, pn: number): void;
+    get size(): number;
+    wipeAll(): void;
+}

package/dist/ratchet/skipped-key-store.js

@@ -0,0 +1,154 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ratchet/skipped-key-store.ts
+//
+// SkippedKeyStore — MKSKIPPED cache for a single KDFChain (DR spec §3.2/§3.5).
+// Manages out-of-order and skipped message key storage with transactional
+// resolve via ResolveHandle. Split budgets: maxCacheSize bounds memory;
+// maxSkipPerResolve bounds per-message HKDF work (DoS mitigation).
+import { wipe } from '../utils.js';
+// Best-effort wipe if a handle is GC'd without settling. GC is non-deterministic
+// so this is a safety net only; the contract remains that callers MUST settle.
+const finalizer = new FinalizationRegistry(key => wipe(key));
+export class SkippedKeyStore {
+    _store;
+    _maxCacheSize;
+    _maxSkipPerResolve;
+    constructor(opts) {
+        const cache = opts?.maxCacheSize ?? opts?.ceiling ?? 100;
+        const skip = opts?.maxSkipPerResolve ?? opts?.ceiling ?? 50;
+        if (!Number.isSafeInteger(cache) || cache < 1)
+            throw new RangeError('SkippedKeyStore: maxCacheSize must be a safe integer >= 1');
+        if (!Number.isSafeInteger(skip) || skip < 1)
+            throw new RangeError('SkippedKeyStore: maxSkipPerResolve must be a safe integer >= 1');
+        if (skip > cache)
+            throw new RangeError(`SkippedKeyStore: maxSkipPerResolve (${skip}) must not exceed maxCacheSize (${cache})`);
+        this._store = new Map();
+        this._maxCacheSize = cache;
+        this._maxSkipPerResolve = skip;
+    }
+    // O(1) eviction — Map iteration is insertion order, and keys are inserted
+    // in strictly increasing counter order, so the first key yielded IS the
+    // oldest (lowest counter).
+    _evictOldest() {
+        const oldest = this._store.keys().next().value;
+        if (oldest === undefined)
+            return;
+        const val = this._store.get(oldest);
+        if (val !== undefined)
+            wipe(val);
+        this._store.delete(oldest);
+    }
+    // Resolve a message key for the given counter. Returns a ResolveHandle the
+    // caller settles via commit() (success — key wiped) or rollback()
+    // (failure — key returned to the store so a later legitimate message at
+    // the same counter can still decrypt).
+    //
+    // Three paths based on counter vs chain.n:
+    //   in-order   (=== n+1): step chain, wrap final key
+    //   skip-ahead (>   n+1): step chain storing intermediates, wrap final
+    //   past       (<=   n):  look up in map and delete; throw if absent
+    resolve(chain, counter) {
+        if (!Number.isSafeInteger(counter) || counter < 1)
+            throw new RangeError(`SkippedKeyStore: invalid counter ${counter}`);
+        let key;
+        if (counter === chain.n + 1) {
+            key = chain.step();
+        }
+        else if (counter > chain.n + 1) {
+            const skipNeeded = counter - chain.n - 1;
+            if (skipNeeded > this._maxSkipPerResolve)
+                throw new RangeError(`SkippedKeyStore: counter ${counter} requires ${skipNeeded} skip derivations, `
+                    + `exceeds maxSkipPerResolve=${this._maxSkipPerResolve}`);
+            while (chain.n < counter - 1) {
+                const k = chain.step();
+                if (this._store.size >= this._maxCacheSize)
+                    this._evictOldest();
+                this._store.set(chain.n, k);
+            }
+            key = chain.step();
+        }
+        else {
+            const stored = this._store.get(counter);
+            if (stored === undefined)
+                throw new Error(`SkippedKeyStore: unrecoverable. key for counter ${counter} not found`);
+            this._store.delete(counter);
+            key = stored;
+        }
+        return this._makeHandle(key, counter);
+    }
+    _makeHandle(key, counter) {
+        let settled = false;
+        const handle = {
+            get key() {
+                if (settled)
+                    throw new Error('SkippedKeyStore: handle already settled');
+                return key;
+            },
+            commit: () => {
+                if (settled)
+                    throw new Error('SkippedKeyStore: handle already settled');
+                settled = true;
+                finalizer.unregister(handle);
+                wipe(key);
+            },
+            rollback: () => {
+                if (settled)
+                    throw new Error('SkippedKeyStore: handle already settled');
+                settled = true;
+                finalizer.unregister(handle);
+                if (this._store.size >= this._maxCacheSize)
+                    this._evictOldest();
+                this._store.set(counter, key);
+            },
+        };
+        finalizer.register(handle, key, handle);
+        return handle;
+    }
+    // Step chain from its current position up to and including pn, storing each
+    // key. Used at epoch transitions so late-arriving old-epoch messages can
+    // still be decrypted. No-op when pn <= chain.n. Enforces maxSkipPerResolve
+    // so a malicious header can't force unbounded HKDF work.
+    advanceToBoundary(chain, pn) {
+        if (!Number.isSafeInteger(pn) || pn < 0)
+            throw new RangeError(`SkippedKeyStore: invalid pn ${pn}`);
+        const skipNeeded = pn - chain.n;
+        if (skipNeeded > this._maxSkipPerResolve)
+            throw new RangeError(`SkippedKeyStore: pn=${pn} requires ${skipNeeded} skip derivations, `
+                + `exceeds maxSkipPerResolve=${this._maxSkipPerResolve}`);
+        while (chain.n < pn) {
+            const key = chain.step();
+            if (this._store.size >= this._maxCacheSize)
+                this._evictOldest();
+            this._store.set(chain.n, key);
+        }
+    }
+    get size() {
+        return this._store.size;
+    }
+    // Wipe all stored key buffers and clear the map. Idempotent.
+    wipeAll() {
+        for (const v of this._store.values())
+            wipe(v);
+        this._store.clear();
+    }
+}

package/dist/ratchet/types.d.ts

@@ -0,0 +1,36 @@
+export type { MlKemLike } from '../kyber/suite.js';
+export interface RatchetInitResult {
+    readonly nextRootKey: Uint8Array;
+    readonly sendChainKey: Uint8Array;
+    readonly recvChainKey: Uint8Array;
+}
+export interface KemEncapResult {
+    readonly nextRootKey: Uint8Array;
+    readonly sendChainKey: Uint8Array;
+    readonly recvChainKey: Uint8Array;
+    readonly kemCt: Uint8Array;
+}
+export interface KemDecapResult {
+    readonly nextRootKey: Uint8Array;
+    readonly sendChainKey: Uint8Array;
+    readonly recvChainKey: Uint8Array;
+}
+export interface RatchetMessageHeader {
+    readonly epoch: number;
+    readonly counter: number;
+    readonly pn?: number;
+    readonly kemCt?: Uint8Array;
+}
+export interface ResolveHandle {
+    readonly key: Uint8Array;
+    commit(): void;
+    rollback(): void;
+}
+export interface SkippedKeyStoreOpts {
+    /** Max keys held in cache. Default 100. Must be >= maxSkipPerResolve. */
+    maxCacheSize?: number;
+    /** Max skip-ahead derivations per resolve() call. Default 50. */
+    maxSkipPerResolve?: number;
+    /** @deprecated use maxCacheSize + maxSkipPerResolve. If provided, sets both. */
+    ceiling?: number;
+}

package/dist/ratchet/types.js

@@ -0,0 +1,26 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ratchet/types.ts
+//
+// Shared types for the ratchet KDF construction.
+// Re-exports MlKemLike so consumers import from one place.
+export {};

package/dist/serpent/cipher-suite.d.ts

@@ -1,4 +1,14 @@
 import type { CipherSuite } from '../stream/types.js';
+/**
+ * `CipherSuite` implementation for the stream construction using Serpent-256.
+ *
+ * Each chunk is encrypted with Serpent-CBC (PKCS7) and authenticated with
+ * HMAC-SHA-256. Keys are derived via 3-way HKDF-SHA-256 (enc / mac / iv keys).
+ * Verify-then-decrypt ordering prevents padding oracle attacks (Vaudenay 2002).
+ *
+ * Pass to `SealStream` / `OpenStream` / `SealStreamPool` instead of constructing
+ * this object directly. Use `SerpentCipher.keygen()` to generate a 32-byte key.
+ */
 export declare const SerpentCipher: CipherSuite & {
     keygen(): Uint8Array;
 };

package/dist/serpent/cipher-suite.js

@@ -24,12 +24,23 @@
 // SerpentCipher — CipherSuite implementation for the STREAM construction.
 // 3-key HKDF derivation, HMAC-derived CBC IV, Serpent-CBC + HMAC-SHA-256.
 // Verify-then-decrypt ordering prevents padding oracle attacks (Vaudenay 2002).
-import { SerpentCbc } from './serpent-cbc.js';
-import { HKDF_SHA256, HMAC_SHA256 } from '../sha2/index.js';
+import { HKDF_SHA256 } from '../sha2/index.js';
 import { constantTimeEqual, wipe, concat, randomBytes } from '../utils.js';
 import { AuthenticationError } from '../errors.js';
-import { getInstance } from '../init.js';
+import { getInstance, _assertNotOwned } from '../init.js';
+import { hmacSha256, cbcEncryptChunk, cbcDecryptChunk, } from './shared-ops.js';
+import { WORKER_SOURCE } from '../embedded/serpent-pool-worker.js';
 const INFO = new TextEncoder().encode('serpent-sealstream-v2');
+/**
+ * `CipherSuite` implementation for the stream construction using Serpent-256.
+ *
+ * Each chunk is encrypted with Serpent-CBC (PKCS7) and authenticated with
+ * HMAC-SHA-256. Keys are derived via 3-way HKDF-SHA-256 (enc / mac / iv keys).
+ * Verify-then-decrypt ordering prevents padding oracle attacks (Vaudenay 2002).
+ *
+ * Pass to `SealStream` / `OpenStream` / `SealStreamPool` instead of constructing
+ * this object directly. Use `SerpentCipher.keygen()` to generate a 32-byte key.
+ */
 export const SerpentCipher = {
     formatEnum: 0x02,
     formatName: 'serpent',
@@ -38,10 +49,19 @@ export const SerpentCipher = {
     kemCtSize: 0,
     tagSize: 32,
     padded: true,
+    wasmChunkSize: 65552, // src/asm/serpent/buffers.ts CHUNK_SIZE (65536 + 16 PKCS7 max overhead)
     wasmModules: ['serpent', 'sha2'],
+    /** Generate a random 32-byte master key suitable for use with `SerpentCipher`. @returns 32 cryptographically random bytes */
     keygen() {
         return randomBytes(32);
     },
+    /**
+     * Derive 96 bytes of keying material from `masterKey` and `nonce` via HKDF-SHA-256.
+     * Layout: bytes[0:32]=enc_key, bytes[32:64]=mac_key, bytes[64:96]=iv_key.
+     * @param masterKey  32-byte master key
+     * @param nonce      Stream nonce (16 bytes minimum)
+     * @returns          `DerivedKeys` holding the 96-byte material
+     */
     deriveKeys(masterKey, nonce, _kemCt) {
         const hkdf = new HKDF_SHA256();
         const derived = hkdf.derive(masterKey, nonce, INFO, 96);
@@ -49,73 +69,139 @@ export const SerpentCipher = {
         // bytes[0:32]=enc_key, bytes[32:64]=mac_key, bytes[64:96]=iv_key
         return { bytes: derived };
     },
+    /**
+     * Encrypt and authenticate one stream chunk.
+     * IV is derived from `counterNonce` via HMAC-SHA-256 with the iv_key.
+     * Output: ciphertext (PKCS7-padded) || 32-byte HMAC tag.
+     * @param keys         Derived keys from `deriveKeys`
+     * @param counterNonce Per-chunk nonce (unique per chunk in the stream)
+     * @param chunk        Plaintext chunk
+     * @param aad          Optional additional authenticated data
+     * @returns            Authenticated ciphertext
+     */
     sealChunk(keys, counterNonce, chunk, aad) {
+        // shared-ops functions operate directly on the module exports without
+        // going through `_acquireModule`. Assert no stateful instance owns
+        // either module before touching WASM memory.
+        _assertNotOwned('serpent');
+        _assertNotOwned('sha2');
+        const sx = getInstance('sha2').exports;
+        const kx = getInstance('serpent').exports;
         const encKey = keys.bytes.subarray(0, 32);
         const macKey = keys.bytes.subarray(32, 64);
         const ivKey = keys.bytes.subarray(64, 96);
         const aadBytes = aad ?? new Uint8Array(0);
-        const hmac = new HMAC_SHA256();
-        // Derive IV from counter nonce
-        const ivFull = hmac.hash(ivKey, counterNonce);
-        const iv = ivFull.slice(0, 16);
-        wipe(ivFull);
-        // Encrypt: Serpent-CBC with PKCS7 padding
-        const cbc = new SerpentCbc({ dangerUnauthenticated: true });
-        const ct = cbc.encrypt(encKey, iv, chunk);
-        cbc.dispose();
-        // Compute HMAC tag: HMAC-SHA-256(mac_key, counterNonce || u32be(aad_len) || aad || ct)
-        const aadLenBuf = new Uint8Array(4);
-        new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
-        const tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
-        const tag = hmac.hash(macKey, tagInput);
-        hmac.dispose();
-        wipe(iv);
-        wipe(tagInput);
-        // Output: ct || tag (IV is NOT included)
-        return concat(ct, tag);
+        let iv;
+        let tagInput;
+        try {
+            // Derive IV from counter nonce
+            const ivFull = hmacSha256(sx, ivKey, counterNonce);
+            iv = ivFull.slice(0, 16);
+            wipe(ivFull);
+            // Encrypt: Serpent-CBC with PKCS7 padding
+            const ct = cbcEncryptChunk(kx, encKey, iv, chunk);
+            // Compute HMAC tag: HMAC-SHA-256(mac_key, counterNonce || u32be(aad_len) || aad || ct)
+            const aadLenBuf = new Uint8Array(4);
+            new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
+            tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
+            const tag = hmacSha256(sx, macKey, tagInput);
+            // Output: ct || tag (IV is NOT included)
+            return concat(ct, tag);
+        }
+        finally {
+            if (iv)
+                wipe(iv);
+            if (tagInput)
+                wipe(tagInput);
+            // No hmac/cbc instance to dispose — shared-ops functions are instance-free.
+        }
     },
+    /**
+     * Verify and decrypt one stream chunk. HMAC is verified before decryption
+     * to prevent padding oracle attacks (Vaudenay 2002). Throws
+     * `AuthenticationError` on tag mismatch.
+     * @param keys         Derived keys from `deriveKeys`
+     * @param counterNonce Per-chunk nonce — must match the value used by `sealChunk`
+     * @param chunk        Ciphertext || 32-byte HMAC tag
+     * @param aad          Optional additional authenticated data
+     * @returns            Plaintext with PKCS7 padding removed
+     */
     openChunk(keys, counterNonce, chunk, aad) {
         if (chunk.length < 32)
             throw new RangeError(`chunk too short for 32-byte tag (got ${chunk.length})`);
+        _assertNotOwned('serpent');
+        _assertNotOwned('sha2');
+        const sx = getInstance('sha2').exports;
+        const kx = getInstance('serpent').exports;
         const encKey = keys.bytes.subarray(0, 32);
         const macKey = keys.bytes.subarray(32, 64);
         const ivKey = keys.bytes.subarray(64, 96);
         const aadBytes = aad ?? new Uint8Array(0);
         const ct = chunk.subarray(0, chunk.length - 32);
         const receivedTag = chunk.subarray(chunk.length - 32);
-        const hmac = new HMAC_SHA256();
-        // Derive IV from counter nonce
-        const ivFull = hmac.hash(ivKey, counterNonce);
-        const iv = ivFull.slice(0, 16);
-        wipe(ivFull);
-        // Compute expected tag: HMAC-SHA-256(mac_key, counterNonce || u32be(aad_len) || aad || ct)
-        const aadLenBuf = new Uint8Array(4);
-        new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
-        const tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
-        const expectedTag = hmac.hash(macKey, tagInput);
-        hmac.dispose();
-        // CRITICAL: Verify HMAC BEFORE decrypting.
-        // Evaluating PKCS7 padding on unauthenticated data is a padding oracle (Vaudenay 2002).
-        if (!constantTimeEqual(expectedTag, receivedTag)) {
-            wipe(iv);
-            wipe(tagInput);
-            wipe(expectedTag);
-            getInstance('serpent').exports.wipeBuffers();
-            throw new AuthenticationError('serpent');
+        let iv;
+        let tagInput;
+        let expectedTag;
+        try {
+            // Derive IV from counter nonce
+            const ivFull = hmacSha256(sx, ivKey, counterNonce);
+            iv = ivFull.slice(0, 16);
+            wipe(ivFull);
+            // Compute expected tag: HMAC-SHA-256(mac_key, counterNonce || u32be(aad_len) || aad || ct)
+            const aadLenBuf = new Uint8Array(4);
+            new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
+            tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
+            expectedTag = hmacSha256(sx, macKey, tagInput);
+            // CRITICAL: Verify HMAC BEFORE decrypting.
+            // Evaluating PKCS7 padding on unauthenticated data is a padding oracle (Vaudenay 2002).
+            // Belt-and-suspenders: explicit wipes here cover the auth-fail path before
+            // throwing; the finally block below covers every other path.
+            if (!constantTimeEqual(expectedTag, receivedTag)) {
+                wipe(iv);
+                wipe(tagInput);
+                wipe(expectedTag);
+                getInstance('serpent').exports.wipeBuffers();
+                throw new AuthenticationError('serpent');
+            }
+            // ONLY decrypt after authentication succeeds
+            return cbcDecryptChunk(kx, encKey, iv, ct);
+        }
+        finally {
+            if (iv)
+                wipe(iv);
+            if (tagInput)
+                wipe(tagInput);
+            if (expectedTag)
+                wipe(expectedTag);
         }
-        wipe(tagInput);
-        wipe(expectedTag);
-        // ONLY decrypt after authentication succeeds
-        const cbc = new SerpentCbc({ dangerUnauthenticated: true });
-        const plaintext = cbc.decrypt(encKey, iv, ct);
-        cbc.dispose();
-        wipe(iv);
-        return plaintext;
     },
+    /**
+     * Zero all derived key material in `keys`. Called by the stream layer on
+     * teardown and after auth failure.
+     * @param keys  Derived keys to wipe
+     */
     wipeKeys(keys) {
         wipe(keys.bytes);
     },
+    /**
+     * Spawn a Serpent pool worker from the embedded IIFE bundle.
+     * The worker holds its own serpent + sha2 WASM instances.
+     * @returns  Newly constructed `Worker` instance
+     */
     createPoolWorker() {
-        return new Worker(new URL('./pool-worker.js', import.meta.url), { type: 'module' });
+        // IIFE source is bundled at lib build time (scripts/embed-workers.ts).
+        // Avoids the syntactic `new Worker(new URL(..., import.meta.url))`
+        // pattern that triggers eager worker-chunk emission in Vite's
+        // transform hook (issue.md). Classic worker via blob URL —
+        // module workers fail on file:// in Chromium (issue2.md).
+        const blob = new Blob([WORKER_SOURCE], { type: 'application/javascript' });
+        const url = URL.createObjectURL(blob);
+        const w = new Worker(url);
+        // Worker spec fetches the URL synchronously at construction. Revoke
+        // in a macrotask so the spawn completes first; releases the Blob
+        // (~5 KB per spawn × N workers) instead of leaking it for the
+        // document's lifetime.
+        setTimeout(() => URL.revokeObjectURL(url), 0);
+        return w;
     },
 };

package/dist/serpent/generator.d.ts

@@ -0,0 +1,12 @@
+import type { Generator } from '../types.js';
+/**
+ * Serpent-256 ECB counter-mode PRF for Fortuna's generator slot.
+ *
+ * Each 16-byte counter value is encrypted as a plaintext block to produce
+ * one block of pseudorandom output. Practical Cryptography (Ferguson &
+ * Schneier, 2003) §9.4.
+ *
+ * Pass to `Fortuna.create({ generator: SerpentGenerator, ... })` — do not
+ * call `generate()` directly outside of Fortuna.
+ */
+export declare const SerpentGenerator: Generator;