leviathan-crypto 2.0.0 → 2.1.0

package/dist/fortuna.js

@@ -22,18 +22,16 @@
 // src/ts/fortuna.ts
 //
 // Fortuna CSPRNG — Ferguson & Schneier, Practical Cryptography (2003), Chapter 9.
-// Backed by WASM Serpent-256 ECB (generator) and WASM SHA-256 (accumulator pools).
-// Requires init({ serpent: ..., sha2: ... }) before Fortuna.create().
-import { isInitialized } from './init.js';
-import { Serpent } from './serpent/index.js';
-import { SHA256 } from './sha2/index.js';
+// Backed by a pluggable Generator (cipher PRF) and HashFn (accumulator hash).
+// Requires init() for the modules used by the chosen generator and hash pair.
+import { isInitialized, getInstance } from './init.js';
 import { wipe, utf8ToBytes, concat } from './utils.js';
 const isBrowser = typeof window !== 'undefined';
 const isNode = typeof process !== 'undefined' && typeof process.pid === 'number';
 /**
  * Fortuna CSPRNG — spec §9.3–§9.5
  *
- * Use `Fortuna.create()` to instantiate. Direct construction is not allowed.
+ * Use `Fortuna.create({ generator, hash })` to instantiate. Direct construction is not allowed.
  */
 export class Fortuna {
     // ── Constants ──────────────────────────────────────────────────────────
@@ -43,9 +41,9 @@ export class Fortuna {
     static NODE_STATS_INTERVAL = 1000; // ms — OS stats collector interval
     static CRYPTO_INTERVAL = 3000; // ms — crypto.randomBytes interval
     // ── State ─────────────────────────────────────────────────────────────
-    serpent;
-    sha;
-    poolHash; // 32 running SHA-256 chain hashes (32 bytes each)
+    gen;
+    hash;
+    poolHash; // 32 running hash chain values
     poolEntropy;
     genKey;
     genCnt;
@@ -62,25 +60,33 @@ export class Fortuna {
     timers = [];
     // ── Static factory ────────────────────────────────────────────────────
     static async create(opts) {
-        if (!isInitialized('serpent'))
-            throw new Error('leviathan-crypto: call init({ serpent: ..., sha2: ... }) before using Fortuna');
-        if (!isInitialized('sha2'))
-            throw new Error('leviathan-crypto: call init({ serpent: ..., sha2: ... }) before using Fortuna');
-        const f = new Fortuna(opts?.msPerReseed ?? Fortuna.MS_PER_RESEED);
-        f.initialize(opts?.entropy);
+        if (!opts || !opts.generator || !opts.hash)
+            throw new TypeError('leviathan-crypto: Fortuna.create() requires { generator, hash }');
+        if (opts.hash.outputSize !== opts.generator.keySize)
+            throw new RangeError(`leviathan-crypto: Fortuna requires hash.outputSize (${opts.hash.outputSize}) `
+                + `to match generator.keySize (${opts.generator.keySize})`);
+        const required = new Set([...opts.generator.wasmModules, ...opts.hash.wasmModules]);
+        for (const mod of required) {
+            if (!isInitialized(mod)) {
+                const args = [...required].map(m => `${m}: ...`).join(', ');
+                throw new Error(`leviathan-crypto: call init({ ${args} }) before using Fortuna`);
+            }
+        }
+        const f = new Fortuna(opts.generator, opts.hash, opts.msPerReseed ?? Fortuna.MS_PER_RESEED);
+        f.initialize(opts.entropy);
         // Force the first reseed — pool[0] is saturated by initialize(),
         // so this call triggers an immediate reseed and guarantees get() never
         // returns undefined. The byte is discarded.
         f.get(1);
         return f;
     }
-    constructor(msPerReseed) {
-        this.serpent = new Serpent();
-        this.sha = new SHA256();
+    constructor(gen, hash, msPerReseed) {
+        this.gen = gen;
+        this.hash = hash;
         this.poolHash = [];
         this.poolEntropy = [];
-        this.genKey = new Uint8Array(32);
-        this.genCnt = new Uint8Array(16);
+        this.genKey = new Uint8Array(gen.keySize);
+        this.genCnt = new Uint8Array(gen.counterSize);
         this.reseedCnt = 0;
         this.lastReseed = 0;
         this.entropyLevel = 0;
@@ -90,7 +96,7 @@ export class Fortuna {
         this.msPerReseed = msPerReseed;
         this.robin = { kbd: 0, mouse: 0, scroll: 0, touch: 0, motion: 0, time: 0, rnd: 0, dom: 0 };
         for (let i = 0; i < Fortuna.NUM_POOLS; i++) {
-            this.poolHash.push(new Uint8Array(32)); // zero-initialized chain value
+            this.poolHash.push(new Uint8Array(hash.outputSize)); // zero-initialized chain value
             this.poolEntropy.push(0);
         }
     }
@@ -109,17 +115,23 @@ export class Fortuna {
             let seed = new Uint8Array(0);
             let strength = 0;
             for (let i = 0; i < Fortuna.NUM_POOLS; i++) {
-                if ((this.reseedCnt & (1 << i)) !== 0) {
+                // Practical Cryptography (Ferguson & Schneier, 2003) §9.5.5:
+                // pool P_i is used in reseed r iff 2^i divides r.
+                if ((this.reseedCnt & ((1 << i) - 1)) === 0) {
                     // Pool digest = current chain hash
                     seed = concat(seed, this.poolHash[i]);
                     strength += this.poolEntropy[i];
-                    // Reset pool
-                    this.poolHash[i] = new Uint8Array(32);
+                    // Reset pool — wipe old chain hash before dropping the reference.
+                    const old = this.poolHash[i];
+                    this.poolHash[i] = new Uint8Array(this.hash.outputSize);
+                    wipe(old);
                     this.poolEntropy[i] = 0;
                 }
             }
             this.entropyLevel -= strength;
             this.reseed(seed);
+            // seed is built from concatenated pool-hash copies; wipe the temp.
+            wipe(seed);
         }
         return this.pseudoRandomData(length);
     }
@@ -140,11 +152,33 @@ export class Fortuna {
     stop() {
         if (this.disposed)
             throw new Error('Fortuna instance has been disposed');
+        // Mark disposed FIRST. WASM wipeBuffers can throw if a stateful instance
+        // holds the module; we must not allow get()/addEntropy()/getEntropy() to
+        // run on a partially-disposed instance.
+        this.disposed = true;
         this.stopCollectors();
         wipe(this.genKey);
         wipe(this.genCnt);
+        // Wipe all 32 pool-hash chain values so residual entropy-bearing
+        // bytes do not outlive the instance.
+        for (const p of this.poolHash)
+            wipe(p);
         this.reseedCnt = 0;
-        this.disposed = true;
+        // Best-effort wipe of WASM scratch buffers for every module the chosen
+        // generator and hash touched. Surface the first error so the caller
+        // knows the WASM scratch leak occurred.
+        const required = new Set([...this.gen.wasmModules, ...this.hash.wasmModules]);
+        let err;
+        for (const mod of required) {
+            try {
+                getInstance(mod).exports.wipeBuffers();
+            }
+            catch (e) {
+                err ??= e;
+            }
+        }
+        if (err)
+            throw err;
     }
     // ── Test-only accessors ───────────────────────────────────────────────
     /** @internal — exposed for testing key replacement */
@@ -159,45 +193,93 @@ export class Fortuna {
     _getReseedCnt() {
         return this.reseedCnt;
     }
-    // ── Generator (spec §9.4) ─────────────────────────────────────────────
-    /** Generate n blocks of 16 bytes each. — spec §9.4 */
-    generateBlocks(n) {
-        const out = new Uint8Array(n * 16);
-        for (let i = 0; i < n; i++) {
-            // Encrypt genCnt with Serpent-256 ECB
-            this.serpent.loadKey(this.genKey);
-            out.set(this.serpent.encryptBlock(this.genCnt), i * 16);
-            this.incrementCounter();
+    /** @internal — exposed for testing pool-hash backing arrays */
+    _getPoolHash() {
+        return this.poolHash;
+    }
+    /**
+     * @internal — test-only deterministic factory. Seeds pool[0] with the provided
+     * entropy and triggers one reseed directly, bypassing all OS entropy collection
+     * and the hrtime jitter capture in get(). This makes KAT vectors reproducible
+     * across runs. Not suitable for production use.
+     */
+    static async _createDeterministicForTesting(opts) {
+        if (!opts || !opts.generator || !opts.hash)
+            throw new TypeError('Fortuna._createDeterministicForTesting() requires { generator, hash, entropy }');
+        if (opts.hash.outputSize !== opts.generator.keySize)
+            throw new RangeError(`leviathan-crypto: Fortuna requires hash.outputSize (${opts.hash.outputSize}) `
+                + `to match generator.keySize (${opts.generator.keySize})`);
+        const required = new Set([...opts.generator.wasmModules, ...opts.hash.wasmModules]);
+        for (const mod of required) {
+            if (!isInitialized(mod)) {
+                const args = [...required].map(m => `${m}: ...`).join(', ');
+                throw new Error(`leviathan-crypto: call init({ ${args} }) before using Fortuna`);
+            }
         }
-        return out;
+        const f = new Fortuna(opts.generator, opts.hash, 0);
+        // Seed pool[0] with the provided entropy, no OS collection.
+        f.addRandomEvent(opts.entropy, 0, opts.entropy.length * 8);
+        // Manually trigger reseed #1 without calling get() — get() calls captureHrtime()
+        // in Node.js which adds non-deterministic data before the reseed fires.
+        f.reseedFromPool0();
+        return f;
     }
+    // ── Generator (spec §9.4) ─────────────────────────────────────────────
     /** Get length pseudo-random bytes. — spec §9.4 */
     pseudoRandomData(length) {
-        // Generate ceil(length/16) blocks — spec §9.4
-        const blocks = Math.ceil(length / 16);
-        const raw = this.generateBlocks(blocks);
-        const output = raw.slice(0, length);
-        // Key replacement — mandatory forward secrecy (spec §9.4)
-        this.genKey = this.generateBlocks(2);
-        return output;
+        const blocks = Math.ceil(length / this.gen.blockSize);
+        const out = this.gen.generate(this.genKey, this.genCnt, length);
+        // External counter advance — generator is stateless and does not mutate caller's counter
+        for (let i = 0; i < blocks; i++)
+            this.incrementCounter();
+        // Key replacement — mandatory forward secrecy (spec §9.4).
+        // Wipe the prior key BEFORE dropping its reference so no key bytes are
+        // reachable after key replacement; anyone holding a Uint8Array view to
+        // the old key now observes zero.
+        const newKey = this.gen.generate(this.genKey, this.genCnt, this.gen.keySize);
+        for (let i = 0; i < Math.ceil(this.gen.keySize / this.gen.blockSize); i++)
+            this.incrementCounter();
+        wipe(this.genKey);
+        this.genKey = newKey;
+        return out;
     }
     /** Reseed the generator — spec §9.4 */
     reseed(seed) {
-        // genKey = SHA256(genKey ‖ seed)
-        this.genKey = this.sha.hash(concat(this.genKey, seed));
+        // genKey = hash(genKey ‖ seed). Wipe both the hash input and the
+        // prior key before dropping references.
+        const combined = concat(this.genKey, seed);
+        const newKey = this.hash.digest(combined);
+        wipe(combined);
+        wipe(this.genKey);
+        this.genKey = newKey;
         // Increment counter — makes it nonzero on first reseed, marking generator as seeded
         this.incrementCounter();
         this.lastReseed = Date.now();
     }
-    /** Increment 16-byte little-endian counter. — spec §9.4 */
+    /** Drain pool 0 into a fresh seed and reseed. Used by the deterministic
+     *  test factory; production reseeds in get() walk the §9.5.5 schedule
+     *  across all pools, not just pool 0. Caller is responsible for any
+     *  entropy-threshold check. */
+    reseedFromPool0() {
+        this.reseedCnt = (this.reseedCnt + 1) >>> 0;
+        const seed = this.poolHash[0].slice();
+        const old = this.poolHash[0];
+        this.poolHash[0] = new Uint8Array(this.hash.outputSize);
+        wipe(old);
+        this.entropyLevel -= this.poolEntropy[0];
+        this.poolEntropy[0] = 0;
+        this.reseed(seed);
+        wipe(seed);
+    }
+    /** Increment little-endian counter. — spec §9.4 */
     incrementCounter() {
-        for (let i = 0; i < 16; i++) {
+        for (let i = 0; i < this.genCnt.length; i++) {
             if (++this.genCnt[i] !== 0)
                 break;
         }
     }
     // ── Accumulator (spec §9.5) ───────────────────────────────────────────
-    /** Add an event to a pool via hash chaining: poolHash[i] = SHA256(poolHash[i] ‖ eventId ‖ data). */
+    /** Add an event to a pool via hash chaining: poolHash[i] = hash(poolHash[i] ‖ eventId ‖ data). */
     addRandomEvent(data, poolIdx, entropyBits) {
         // Encode eventId as 4 bytes little-endian
         const id = new Uint8Array(4);
@@ -206,8 +288,13 @@ export class Fortuna {
         id[2] = (this.eventId >>> 16) & 0xff;
         id[3] = (this.eventId >>> 24) & 0xff;
         this.eventId = (this.eventId + 1) >>> 0; // u32 wrap
-        // Chain: poolHash[i] = SHA256(poolHash[i] ‖ id ‖ data)
-        this.poolHash[poolIdx] = this.sha.hash(concat(this.poolHash[poolIdx], id, data));
+        // Chain: poolHash[i] = hash(poolHash[i] ‖ id ‖ data).
+        // Wipe the chain input and the prior chain value before dropping refs.
+        const combined = concat(this.poolHash[poolIdx], id, data);
+        const newChain = this.hash.digest(combined);
+        wipe(combined);
+        wipe(this.poolHash[poolIdx]);
+        this.poolHash[poolIdx] = newChain;
         this.poolEntropy[poolIdx] += entropyBits;
         this.entropyLevel += entropyBits;
     }
@@ -226,6 +313,13 @@ export class Fortuna {
             this.addRandomEvent(entropy, this.robin.rnd, entropy.length * 8);
             this.robin.rnd = (this.robin.rnd + 1) % Fortuna.NUM_POOLS;
         }
+        // F-2 invariant: fail loudly if no OS entropy source delivered anything.
+        // The try/catch in collectorCryptoRandom is preserved to protect against
+        // platforms where crypto.getRandomValues itself throws (non-standard
+        // runtimes). This post-init check covers all silent-failure paths uniformly.
+        if (this.poolEntropy[0] < Fortuna.RESEED_LIMIT)
+            throw new Error('leviathan-crypto: Fortuna initialization could not gather sufficient entropy. '
+                + 'No working crypto.getRandomValues or node:crypto in this environment.');
         this.startCollectors();
     }
     // ── Collectors ────────────────────────────────────────────────────────
@@ -358,7 +452,7 @@ export class Fortuna {
     }
     collectorDom() {
         if (typeof document !== 'undefined' && document.documentElement) {
-            this.addRandomEvent(this.sha.hash(utf8ToBytes(document.documentElement.innerHTML)), this.robin.dom, 2);
+            this.addRandomEvent(this.hash.digest(utf8ToBytes(document.documentElement.innerHTML)), this.robin.dom, 2);
             this.robin.dom = (this.robin.dom + 1) % Fortuna.NUM_POOLS;
         }
     }

package/dist/index.d.ts

@@ -13,17 +13,19 @@ import type { WasmSource } from './wasm-source.js';
  */
 export declare function init(sources: Partial<Record<Module, WasmSource>>): Promise<void>;
 export type { Module, WasmSource };
-export { isInitialized, _resetForTesting } from './init.js';
+export { isInitialized } from './init.js';
 export { AuthenticationError } from './errors.js';
-export { serpentInit, Serpent, SerpentCtr, SerpentCbc, SerpentCipher, _serpentReady } from './serpent/index.js';
-export { chacha20Init, ChaCha20, Poly1305, ChaCha20Poly1305, XChaCha20Poly1305, XChaCha20Cipher, _chachaReady } from './chacha20/index.js';
-export { sha2Init, SHA256, SHA512, SHA384, HMAC_SHA256, HMAC_SHA512, HMAC_SHA384, HKDF_SHA256, HKDF_SHA512, _sha2Ready } from './sha2/index.js';
-export { sha3Init, SHA3_224, SHA3_256, SHA3_384, SHA3_512, SHAKE128, SHAKE256, _sha3Ready } from './sha3/index.js';
+export { serpentInit, Serpent, SerpentCtr, SerpentCbc, SerpentCipher, SerpentGenerator, _serpentReady } from './serpent/index.js';
+export { chacha20Init, ChaCha20, Poly1305, ChaCha20Poly1305, XChaCha20Poly1305, XChaCha20Cipher, ChaCha20Generator, _chachaReady } from './chacha20/index.js';
+export { sha2Init, SHA256, SHA512, SHA384, HMAC_SHA256, HMAC_SHA512, HMAC_SHA384, HKDF_SHA256, HKDF_SHA512, SHA256Hash, _sha2Ready } from './sha2/index.js';
+export { sha3Init, SHA3_224, SHA3_256, SHA3_384, SHA3_512, SHAKE128, SHAKE256, SHA3_256Hash, _sha3Ready } from './sha3/index.js';
 export { keccakInit } from './keccak/index.js';
 export { kyberInit, MlKem512, MlKem768, MlKem1024, MlKemBase, KyberSuite, _kyberReady } from './kyber/index.js';
 export type { KyberKeyPair, KyberEncapsulation, KyberParams } from './kyber/index.js';
 export { SealStream, OpenStream, Seal, SealStreamPool, FLAG_FRAMED, TAG_DATA, TAG_FINAL, HEADER_SIZE, CHUNK_MIN, CHUNK_MAX } from './stream/index.js';
 export type { CipherSuite, DerivedKeys, SealStreamOpts, PoolOpts } from './stream/index.js';
 export { Fortuna } from './fortuna.js';
-export type { Hash, KeyedHash, Blockcipher, Streamcipher, AEAD } from './types.js';
+export type { Hash, KeyedHash, Blockcipher, Streamcipher, AEAD, Generator, HashFn } from './types.js';
+export { KDFChain, ratchetInit, kemRatchetEncap, kemRatchetDecap, ratchetReady, SkippedKeyStore, RatchetKeypair, } from './ratchet/index.js';
+export type { RatchetInitResult, KemEncapResult, KemDecapResult, MlKemLike, RatchetMessageHeader, ResolveHandle, SkippedKeyStoreOpts, } from './ratchet/index.js';
 export { hexToBytes, bytesToHex, utf8ToBytes, bytesToUtf8, base64ToBytes, bytesToBase64, constantTimeEqual, CT_MAX_BYTES, wipe, xor, concat, randomBytes, hasSIMD, } from './utils.js';

package/dist/index.js

@@ -60,14 +60,15 @@ export async function init(sources) {
     }
     await Promise.all(entries.map(([mod, src]) => _dispatchers[mod](src)));
 }
-export { isInitialized, _resetForTesting } from './init.js';
+export { isInitialized } from './init.js';
 export { AuthenticationError } from './errors.js';
-export { serpentInit, Serpent, SerpentCtr, SerpentCbc, SerpentCipher, _serpentReady } from './serpent/index.js';
-export { chacha20Init, ChaCha20, Poly1305, ChaCha20Poly1305, XChaCha20Poly1305, XChaCha20Cipher, _chachaReady } from './chacha20/index.js';
-export { sha2Init, SHA256, SHA512, SHA384, HMAC_SHA256, HMAC_SHA512, HMAC_SHA384, HKDF_SHA256, HKDF_SHA512, _sha2Ready } from './sha2/index.js';
-export { sha3Init, SHA3_224, SHA3_256, SHA3_384, SHA3_512, SHAKE128, SHAKE256, _sha3Ready } from './sha3/index.js';
+export { serpentInit, Serpent, SerpentCtr, SerpentCbc, SerpentCipher, SerpentGenerator, _serpentReady } from './serpent/index.js';
+export { chacha20Init, ChaCha20, Poly1305, ChaCha20Poly1305, XChaCha20Poly1305, XChaCha20Cipher, ChaCha20Generator, _chachaReady } from './chacha20/index.js';
+export { sha2Init, SHA256, SHA512, SHA384, HMAC_SHA256, HMAC_SHA512, HMAC_SHA384, HKDF_SHA256, HKDF_SHA512, SHA256Hash, _sha2Ready } from './sha2/index.js';
+export { sha3Init, SHA3_224, SHA3_256, SHA3_384, SHA3_512, SHAKE128, SHAKE256, SHA3_256Hash, _sha3Ready } from './sha3/index.js';
 export { keccakInit } from './keccak/index.js';
 export { kyberInit, MlKem512, MlKem768, MlKem1024, MlKemBase, KyberSuite, _kyberReady } from './kyber/index.js';
 export { SealStream, OpenStream, Seal, SealStreamPool, FLAG_FRAMED, TAG_DATA, TAG_FINAL, HEADER_SIZE, CHUNK_MIN, CHUNK_MAX } from './stream/index.js';
 export { Fortuna } from './fortuna.js';
+export { KDFChain, ratchetInit, kemRatchetEncap, kemRatchetDecap, ratchetReady, SkippedKeyStore, RatchetKeypair, } from './ratchet/index.js';
 export { hexToBytes, bytesToHex, utf8ToBytes, bytesToUtf8, base64ToBytes, bytesToBase64, constantTimeEqual, CT_MAX_BYTES, wipe, xor, concat, randomBytes, hasSIMD, } from './utils.js';

package/dist/init.d.ts

@@ -3,5 +3,3 @@ export type Module = 'serpent' | 'chacha20' | 'sha2' | 'sha3' | 'keccak' | 'kybe
 export declare function initModule(mod: Module, source: WasmSource): Promise<void>;
 export declare function getInstance(mod: Module): WebAssembly.Instance;
 export declare function isInitialized(mod: Module): boolean;
-/** Reset all cached instances — for testing only */
-export declare function _resetForTesting(): void;

package/dist/init.js

@@ -7,26 +7,106 @@ function resolve(mod) {
 }
 // Module-scope cache: one WebAssembly.Instance per canonical module
 const instances = new Map();
+// Pending inits — coalesces concurrent initModule calls for the same module.
+const pending = new Map();
+// Exclusivity registry: per-module ownership token held by a stateful wrapper
+// for its entire lifetime. Prevents shared-WASM-state clobber when two
+// instances from the same module would otherwise trample each other's memory.
+const owners = new Map();
 export async function initModule(mod, source) {
     const resolved = resolve(mod);
     if (instances.has(resolved))
         return;
+    const inflight = pending.get(resolved);
+    if (inflight) {
+        await inflight;
+        return;
+    }
     if ((resolved === 'serpent' || resolved === 'chacha20' || resolved === 'kyber') && !hasSIMD())
         throw new Error('leviathan-crypto: serpent, chacha20, and kyber require WebAssembly SIMD — '
             + 'this runtime does not support it');
-    instances.set(resolved, await loadWasm(source));
+    const p = loadWasm(source);
+    pending.set(resolved, p);
+    try {
+        instances.set(resolved, await p);
+    }
+    finally {
+        pending.delete(resolved);
+    }
 }
 export function getInstance(mod) {
-    const inst = instances.get(resolve(mod));
+    const r = resolve(mod);
+    const inst = instances.get(r);
     if (!inst) {
         throw new Error(`leviathan-crypto: call init({ ${mod}: ... }) before using this class`);
     }
+    if (owners.has(r)) {
+        throw new Error(`leviathan-crypto: another stateful instance is using the '${r}' WASM module — `
+            + 'call dispose() on it before constructing a new one');
+    }
     return inst;
 }
 export function isInitialized(mod) {
     return instances.has(resolve(mod));
 }
-/** Reset all cached instances — for testing only */
+/**
+ * Acquire exclusive access to `mod`. Throws if another stateful instance
+ * currently holds it. Returned token must be passed to `_releaseModule`.
+ * @internal
+ */
+export function _acquireModule(mod) {
+    const r = resolve(mod);
+    if (owners.has(r))
+        throw new Error(`leviathan-crypto: another stateful instance is using the '${r}' WASM module — `
+            + 'call dispose() on it before constructing a new one');
+    const tok = Symbol(r);
+    owners.set(r, tok);
+    return tok;
+}
+/**
+ * Release exclusive access. No-op if the token doesn't match the current
+ * owner (makes dispose idempotent).
+ * @internal
+ */
+export function _releaseModule(mod, tok) {
+    const r = resolve(mod);
+    if (owners.get(r) === tok)
+        owners.delete(r);
+}
+/**
+ * True if a stateful instance currently holds the module.
+ * @internal
+ */
+export function _isModuleBusy(mod) {
+    return owners.has(resolve(mod));
+}
+/**
+ * Throw if `mod` is currently held by a stateful instance. Called at the top
+ * of every atomic WASM-touching method so that cached-exports access paths
+ * cannot silently clobber a live stateful instance's WASM state.
+ *
+ * The error message is intentionally identical to `_acquireModule`'s so that
+ * error handlers matching on text work uniformly across construction-time and
+ * method-time ownership failures.
+ * @internal
+ */
+export function _assertNotOwned(mod) {
+    // Deliberately unoptimized. Do not add caching or epoch tracking: the
+    // check must read current ownership on every call so an atomic op cannot
+    // race ahead of a stateful acquirer.
+    const r = resolve(mod);
+    if (owners.has(r))
+        throw new Error(`leviathan-crypto: another stateful instance is using the '${r}' WASM module — `
+            + 'call dispose() on it before constructing a new one');
+}
+/**
+ * Reset all cached instances — for testing only. Clears `instances`, `pending`,
+ * and `owners` so tests can re-exercise module lifecycle (init, exclusivity,
+ * race) from a known-empty state.
+ * @internal
+ */
 export function _resetForTesting() {
     instances.clear();
+    pending.clear();
+    owners.clear();
 }

package/dist/kyber/indcpa.js

@@ -24,7 +24,7 @@
 // ML-KEM IND-CPA PKE scheme — FIPS 203 Algorithms 12, 13, 14 (K-PKE).
 // Orchestrates kyber WASM (polynomial math) and sha3 WASM (Keccak sponge).
 import { wipe } from '../utils.js';
-// ── SHA3 helpers ──────────────────────────────────────────────────────────────
+// ── SHA3 helpers ────────────────────────────────────────────────────────────
 // All operate directly on raw Sha3Exports, no init() system involved.
 /** Absorb msg into the sha3 sponge in 168-byte chunks (max rate). */
 function sha3Absorb(sx, msg) {
@@ -77,7 +77,7 @@ export function shake256Hash(sx, msg, n) {
     }
     return out;
 }
-// ── Matrix generation ─────────────────────────────────────────────────────────
+// ── Matrix generation ───────────────────────────────────────────────────────
 /**
  * Generate row `rowI` of matrix  (or Â^T) into polyvec slot `pvecSlot`.
  *
@@ -120,7 +120,7 @@ function genMatrixRow(kx, sx, k, rho, transposed, pvecSlot, rowI) {
         }
     }
 }
-// ── Noise generation ──────────────────────────────────────────────────────────
+// ── Noise generation ────────────────────────────────────────────────────────
 /**
  * CBD noise polyvec: SHAKE256(σ || nonce) for each entry.
  * FIPS 203 Algorithm 7: PRF_η(σ, N) = SHAKE256(σ || N)[0..64η-1].
@@ -185,7 +185,7 @@ function noisePoly(kx, sx, polyOff, sigma, nonce, eta) {
         wipe(prfInput);
     }
 }
-// ── IND-CPA functions ─────────────────────────────────────────────────────────
+// ── IND-CPA functions ───────────────────────────────────────────────────────
 /**
  * K-PKE.KeyGen (FIPS 203 Algorithm 12) — deterministic.
  *

package/dist/kyber/index.js

@@ -23,7 +23,7 @@
 //
 // ML-KEM public API — MlKem512, MlKem768, MlKem1024 classes.
 // Uses the init() module cache — call init({ kyber: ..., sha3: ... }) before constructing.
-import { getInstance, initModule, isInitialized } from '../init.js';
+import { getInstance, initModule, isInitialized, _assertNotOwned } from '../init.js';
 import { randomBytes, wipe } from '../utils.js';
 import { MLKEM512, MLKEM768, MLKEM1024 } from './params.js';
 import { kemKeypairDerand, kemEncapsulateDerand, kemDecapsulate } from './kem.js';
@@ -44,7 +44,7 @@ export function _kyberReady() {
 export { MLKEM512, MLKEM768, MLKEM1024 };
 export { isInitialized };
 export { KyberSuite } from './suite.js';
-// ── Layout assertion ──────────────────────────────────────────────────────────
+// ── Layout assertion ────────────────────────────────────────────────────────
 function assertLayout(kx, p) {
     const pk = kx.getPkOffset();
     const sk = kx.getSkOffset();
@@ -60,7 +60,7 @@ function assertLayout(kx, p) {
     if (ctPrime + p.ctBytes > xof)
         throw new Error('leviathan-crypto: kyber buffer overflow — ct_prime overflows into XOF region');
 }
-// ── Base class ────────────────────────────────────────────────────────────────
+// ── Base class ──────────────────────────────────────────────────────────────
 export class MlKemBase {
     params;
     constructor(params) {
@@ -78,6 +78,8 @@ export class MlKemBase {
         return getInstance('sha3').exports;
     }
     keygenDerand(d, z) {
+        _assertNotOwned('sha3');
+        _assertNotOwned('kyber');
         if (d.length !== 32)
             throw new RangeError(`d seed must be 32 bytes (got ${d.length})`);
         if (z.length !== 32)
@@ -96,10 +98,14 @@ export class MlKemBase {
         }
     }
     encapsulateDerand(ek, m) {
+        _assertNotOwned('sha3');
+        _assertNotOwned('kyber');
         if (ek.length !== this.params.ekBytes)
             throw new RangeError(`encapsulation key must be ${this.params.ekBytes} bytes (got ${ek.length})`);
         if (m.length !== 32)
             throw new RangeError(`randomness m must be 32 bytes (got ${m.length})`);
+        if (!checkEncapsulationKey(this.kx, this.params, ek))
+            throw new RangeError('leviathan-crypto: encapsulation key failed FIPS 203 §7.2 validity check');
         return kemEncapsulateDerand(this.kx, this.sx, this.params, ek, m);
     }
     encapsulate(ek) {
@@ -112,24 +118,38 @@ export class MlKemBase {
         }
     }
     decapsulate(dk, c) {
+        _assertNotOwned('sha3');
+        _assertNotOwned('kyber');
         if (dk.length !== this.params.dkBytes)
             throw new RangeError(`decapsulation key must be ${this.params.dkBytes} bytes (got ${dk.length})`);
         if (c.length !== this.params.ctBytes)
             throw new RangeError(`ciphertext must be ${this.params.ctBytes} bytes (got ${c.length})`);
+        if (!checkDecapsulationKey(this.kx, this.sx, this.params, dk))
+            throw new RangeError('leviathan-crypto: decapsulation key failed FIPS 203 §7.3 validity check');
         return kemDecapsulate(this.kx, this.sx, this.params, dk, c);
     }
     checkEncapsulationKey(ek) {
+        _assertNotOwned('sha3');
+        _assertNotOwned('kyber');
         return checkEncapsulationKey(this.kx, this.params, ek);
     }
     checkDecapsulationKey(dk) {
+        _assertNotOwned('sha3');
+        _assertNotOwned('kyber');
         return checkDecapsulationKey(this.kx, this.sx, this.params, dk);
     }
     dispose() {
         this.kx.wipeBuffers();
-        this.sx.wipeBuffers();
+        // MlKemBase does not own the sha3 module — wiping this.sx.wipeBuffers()
+        // here would clobber any SHAKE128/SHAKE256 instance live at the time
+        // of dispose(). The wipe is not needed: every public kyber op
+        // (keygen, encapsulate, decapsulate, checkDecapsulationKey) calls
+        // sx.wipeBuffers() before returning, under the _assertNotOwned('sha3')
+        // guard it holds for the duration. sha3 scratch therefore carries no
+        // residue across a kyber op boundary — secret-derived or otherwise.
     }
 }
-// ── Public classes ────────────────────────────────────────────────────────────
+// ── Public classes ──────────────────────────────────────────────────────────
 /** ML-KEM-512 — k=2, η₁=3, η₂=2, dᵤ=10, dᵥ=4. */
 export class MlKem512 extends MlKemBase {
     constructor() {