leviathan-crypto 2.0.1 → 2.1.0

package/dist/sha3/index.d.ts

@@ -26,13 +26,20 @@ export declare class SHA3_224 {
     hash(msg: Uint8Array): Uint8Array;
     dispose(): void;
 }
-/** SHAKE128 XOF — extendable output, multi-squeeze capable. */
+/**
+ * SHAKE128 XOF — extendable output, multi-squeeze capable.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()`. Constructing a second SHAKE128/SHAKE256 or any other sha3
+ * user while this instance is live throws. Call `dispose()` when done.
+ */
 export declare class SHAKE128 {
     private readonly x;
     private readonly _rate;
     private _squeezing;
     private _block;
     private _blockPos;
+    private _tok;
     constructor();
     reset(): this;
     absorb(msg: Uint8Array): this;
@@ -40,13 +47,20 @@ export declare class SHAKE128 {
     hash(msg: Uint8Array, outputLength: number): Uint8Array;
     dispose(): void;
 }
-/** SHAKE256 XOF — extendable output, multi-squeeze capable. */
+/**
+ * SHAKE256 XOF — extendable output, multi-squeeze capable.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()`. Constructing a second SHAKE128/SHAKE256 or any other sha3
+ * user while this instance is live throws. Call `dispose()` when done.
+ */
 export declare class SHAKE256 {
     private readonly x;
     private readonly _rate;
     private _squeezing;
     private _block;
     private _blockPos;
+    private _tok;
     constructor();
     reset(): this;
     absorb(msg: Uint8Array): this;
@@ -54,3 +68,4 @@ export declare class SHAKE256 {
     hash(msg: Uint8Array, outputLength: number): Uint8Array;
     dispose(): void;
 }
+export { SHA3_256Hash } from './hash.js';

package/dist/sha3/index.js

@@ -23,7 +23,7 @@
 //
 // Public API classes for the SHA-3 WASM module.
 // Uses the init() module cache — call sha3Init(source) before constructing.
-import { getInstance, initModule } from '../init.js';
+import { getInstance, initModule, _acquireModule, _releaseModule, _assertNotOwned } from '../init.js';
 export async function sha3Init(source) {
     return initModule('sha3', source);
 }
@@ -58,6 +58,7 @@ export class SHA3_256 {
         this.x = getExports();
     }
     hash(msg) {
+        _assertNotOwned('sha3');
         this.x.sha3_256Init();
         absorb(this.x, msg);
         this.x.sha3_256Final();
@@ -65,6 +66,7 @@ export class SHA3_256 {
         return mem.slice(this.x.getOutOffset(), this.x.getOutOffset() + 32);
     }
     dispose() {
+        _assertNotOwned('sha3');
         this.x.wipeBuffers();
     }
 }
@@ -75,6 +77,7 @@ export class SHA3_512 {
         this.x = getExports();
     }
     hash(msg) {
+        _assertNotOwned('sha3');
         this.x.sha3_512Init();
         absorb(this.x, msg);
         this.x.sha3_512Final();
@@ -82,6 +85,7 @@ export class SHA3_512 {
         return mem.slice(this.x.getOutOffset(), this.x.getOutOffset() + 64);
     }
     dispose() {
+        _assertNotOwned('sha3');
         this.x.wipeBuffers();
     }
 }
@@ -92,6 +96,7 @@ export class SHA3_384 {
         this.x = getExports();
     }
     hash(msg) {
+        _assertNotOwned('sha3');
         this.x.sha3_384Init();
         absorb(this.x, msg);
         this.x.sha3_384Final();
@@ -99,6 +104,7 @@ export class SHA3_384 {
         return mem.slice(this.x.getOutOffset(), this.x.getOutOffset() + 48);
     }
     dispose() {
+        _assertNotOwned('sha3');
         this.x.wipeBuffers();
     }
 }
@@ -109,6 +115,7 @@ export class SHA3_224 {
         this.x = getExports();
     }
     hash(msg) {
+        _assertNotOwned('sha3');
         this.x.sha3_224Init();
         absorb(this.x, msg);
         this.x.sha3_224Final();
@@ -116,22 +123,40 @@ export class SHA3_224 {
         return mem.slice(this.x.getOutOffset(), this.x.getOutOffset() + 28);
     }
     dispose() {
+        _assertNotOwned('sha3');
         this.x.wipeBuffers();
     }
 }
 // ── SHAKE128 ────────────────────────────────────────────────────────────────
-/** SHAKE128 XOF — extendable output, multi-squeeze capable. */
+/**
+ * SHAKE128 XOF — extendable output, multi-squeeze capable.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()`. Constructing a second SHAKE128/SHAKE256 or any other sha3
+ * user while this instance is live throws. Call `dispose()` when done.
+ */
 export class SHAKE128 {
     x;
     _rate = 168;
     _squeezing = false;
     _block = new Uint8Array(168);
     _blockPos = 168;
+    _tok;
     constructor() {
         this.x = getExports();
-        this.x.shake128Init();
+        this._tok = _acquireModule('sha3');
+        try {
+            this.x.shake128Init();
+        }
+        catch (e) {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+            throw e;
+        }
     }
     reset() {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128: instance has been disposed');
         this.x.shake128Init();
         this._squeezing = false;
         this._block.fill(0);
@@ -139,12 +164,16 @@ export class SHAKE128 {
         return this;
     }
     absorb(msg) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128: instance has been disposed');
         if (this._squeezing)
             throw new Error('SHAKE128: cannot absorb after squeeze — call reset() first');
         absorb(this.x, msg);
         return this;
     }
     squeeze(n) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128: instance has been disposed');
         if (n < 1)
             throw new RangeError(`squeeze length must be >= 1 (got ${n})`);
         if (!this._squeezing) {
@@ -170,6 +199,8 @@ export class SHAKE128 {
         return out;
     }
     hash(msg, outputLength) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128: instance has been disposed');
         if (outputLength < 1)
             throw new RangeError(`outputLength must be >= 1 (got ${outputLength})`);
         this.reset();
@@ -177,23 +208,48 @@ export class SHAKE128 {
         return this.squeeze(outputLength);
     }
     dispose() {
+        if (this._tok === undefined)
+            return;
         this._block.fill(0);
-        this.x.wipeBuffers();
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+        }
     }
 }
 // ── SHAKE256 ────────────────────────────────────────────────────────────────
-/** SHAKE256 XOF — extendable output, multi-squeeze capable. */
+/**
+ * SHAKE256 XOF — extendable output, multi-squeeze capable.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()`. Constructing a second SHAKE128/SHAKE256 or any other sha3
+ * user while this instance is live throws. Call `dispose()` when done.
+ */
 export class SHAKE256 {
     x;
     _rate = 136;
     _squeezing = false;
     _block = new Uint8Array(136);
     _blockPos = 136;
+    _tok;
     constructor() {
         this.x = getExports();
-        this.x.shake256Init();
+        this._tok = _acquireModule('sha3');
+        try {
+            this.x.shake256Init();
+        }
+        catch (e) {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+            throw e;
+        }
     }
     reset() {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256: instance has been disposed');
         this.x.shake256Init();
         this._squeezing = false;
         this._block.fill(0);
@@ -201,12 +257,16 @@ export class SHAKE256 {
         return this;
     }
     absorb(msg) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256: instance has been disposed');
         if (this._squeezing)
             throw new Error('SHAKE256: cannot absorb after squeeze — call reset() first');
         absorb(this.x, msg);
         return this;
     }
     squeeze(n) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256: instance has been disposed');
         if (n < 1)
             throw new RangeError(`squeeze length must be >= 1 (got ${n})`);
         if (!this._squeezing) {
@@ -232,6 +292,8 @@ export class SHAKE256 {
         return out;
     }
     hash(msg, outputLength) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256: instance has been disposed');
         if (outputLength < 1)
             throw new RangeError(`outputLength must be >= 1 (got ${outputLength})`);
         this.reset();
@@ -239,7 +301,17 @@ export class SHAKE256 {
         return this.squeeze(outputLength);
     }
     dispose() {
+        if (this._tok === undefined)
+            return;
         this._block.fill(0);
-        this.x.wipeBuffers();
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+        }
     }
 }
+// ── SHA3_256Hash ────────────────────────────────────────────────────────────
+export { SHA3_256Hash } from './hash.js';

package/dist/stream/header.js

@@ -22,7 +22,7 @@
 // src/ts/stream/header.ts
 //
 // Wire format header encoding/decoding and counter nonce construction.
-import { FLAG_FRAMED, HEADER_SIZE, TAG_DATA, TAG_FINAL } from './constants.js';
+import { CHUNK_MAX, CHUNK_MIN, FLAG_FRAMED, HEADER_SIZE, TAG_DATA, TAG_FINAL } from './constants.js';
 // The 16-byte nonce is a HKDF salt — not a direct cipher nonce.
 // Both XChaCha20Cipher and SerpentCipher derive their actual key material
 // and nonces from this value via HKDF-SHA-256. The 16-byte size is chosen
@@ -33,8 +33,8 @@ export function writeHeader(formatEnum, framed, nonce, chunkSize) {
         throw new RangeError(`formatEnum must be an integer in [0, 0x3f] (got ${formatEnum})`);
     if (nonce.length !== 16)
         throw new RangeError(`nonce must be 16 bytes (got ${nonce.length})`);
-    if (!Number.isInteger(chunkSize) || chunkSize < 0 || chunkSize > 0xffffff)
-        throw new RangeError(`chunkSize must be an integer in [0, 0xFFFFFF] (got ${chunkSize})`);
+    if (!Number.isInteger(chunkSize) || chunkSize < CHUNK_MIN || chunkSize > CHUNK_MAX)
+        throw new RangeError(`chunkSize must be an integer in [${CHUNK_MIN}, ${CHUNK_MAX}] (got ${chunkSize})`);
     const h = new Uint8Array(HEADER_SIZE);
     h[0] = (framed ? FLAG_FRAMED : 0) | formatEnum;
     h.set(nonce, 1);
@@ -59,8 +59,8 @@ export function readHeader(header) {
 }
 /** 12-byte counter nonce: 11-byte BE counter + 1-byte final flag. */
 export function makeCounterNonce(counter, finalFlag) {
-    if (!Number.isInteger(counter) || counter < 0 || counter > Number.MAX_SAFE_INTEGER)
-        throw new RangeError(`counter must be an integer in [0, ${Number.MAX_SAFE_INTEGER}]`);
+    if (!Number.isSafeInteger(counter) || counter < 0)
+        throw new RangeError(`counter must be a safe integer in [0, ${Number.MAX_SAFE_INTEGER}]`);
     if (finalFlag !== TAG_DATA && finalFlag !== TAG_FINAL)
         throw new RangeError(`finalFlag must be TAG_DATA (0x00) or TAG_FINAL (0x01) (got 0x${finalFlag.toString(16).padStart(2, '0')})`);
     const n = new Uint8Array(12);

package/dist/stream/open-stream.js

@@ -65,42 +65,64 @@ export class OpenStream {
     }
     pull(chunk, opts) {
         if (this.state !== 'ready')
-            throw new Error('OpenStream: cannot pull after finalize');
+            throw new Error(`OpenStream: cannot pull in state '${this.state}'`);
+        // Argument and wire-format validation runs before the crypto-failure
+        // try/catch so a malformed chunk throws without wiping keys or
+        // transitioning to 'failed'. The caller can retry with a corrected
+        // chunk. Symmetric with SealStream.push.
         const data = this.framed ? this._stripFrame(chunk) : chunk;
         if (data.length < this.cipher.tagSize)
             throw new RangeError(`chunk too short to contain ${this.cipher.tagSize}-byte tag (got ${data.length} bytes)`);
         if (data.length > this.maxWireChunk)
             throw new RangeError(`chunk exceeds max wire size (${data.length} > ${this.maxWireChunk})`);
-        const nonce = makeCounterNonce(this.counter, TAG_DATA);
-        const plaintext = this.cipher.openChunk(this.keys, nonce, data, opts?.aad);
-        this.counter++;
-        return plaintext;
+        try {
+            const nonce = makeCounterNonce(this.counter, TAG_DATA);
+            const plaintext = this.cipher.openChunk(this.keys, nonce, data, opts?.aad);
+            this.counter++;
+            return plaintext;
+        }
+        catch (err) {
+            this.cipher.wipeKeys(this.keys);
+            this.state = 'failed';
+            throw err;
+        }
     }
     finalize(chunk, opts) {
         if (this.state !== 'ready')
-            throw new Error('OpenStream: already finalized');
+            throw new Error(`OpenStream: cannot finalize in state '${this.state}'`);
         const data = this.framed ? this._stripFrame(chunk) : chunk;
         if (data.length < this.cipher.tagSize)
             throw new RangeError(`chunk too short to contain ${this.cipher.tagSize}-byte tag (got ${data.length} bytes)`);
         if (data.length > this.maxWireChunk)
             throw new RangeError(`chunk exceeds max wire size (${data.length} > ${this.maxWireChunk})`);
-        const nonce = makeCounterNonce(this.counter, TAG_FINAL);
-        const plaintext = this.cipher.openChunk(this.keys, nonce, data, opts?.aad);
-        this.cipher.wipeKeys(this.keys);
-        this.state = 'finalized';
-        return plaintext;
+        try {
+            const nonce = makeCounterNonce(this.counter, TAG_FINAL);
+            const plaintext = this.cipher.openChunk(this.keys, nonce, data, opts?.aad);
+            this.cipher.wipeKeys(this.keys);
+            this.state = 'finalized';
+            return plaintext;
+        }
+        catch (err) {
+            this.cipher.wipeKeys(this.keys);
+            this.state = 'failed';
+            throw err;
+        }
     }
     dispose() {
         if (this.state === 'ready') {
             this.cipher.wipeKeys(this.keys);
             this.state = 'finalized';
         }
+        // 'failed' already wiped keys; 'finalized' already wiped keys — no-op.
     }
     seek(index) {
         if (this.state !== 'ready')
-            throw new Error('OpenStream: cannot seek after finalize');
-        if (!Number.isInteger(index) || index < 0)
-            throw new RangeError(`seek index must be a non-negative integer (got ${index})`);
+            throw new Error(`OpenStream: cannot seek in state '${this.state}'`);
+        if (!Number.isSafeInteger(index) || index < 0)
+            throw new RangeError(`seek index must be a non-negative safe integer ≤ Number.MAX_SAFE_INTEGER (got ${index})`);
+        if (index < this.counter)
+            throw new RangeError(`OpenStream: seek is forward-only — current counter ${this.counter}, requested ${index}. `
+                + 'Backward seeks would permit plaintext replay; construct a new OpenStream to restart.');
         this.counter = index;
     }
     _stripFrame(chunk) {

package/dist/stream/seal-stream-pool.d.ts

@@ -35,4 +35,5 @@ export declare class SealStreamPool {
     private _onMessage;
     private _onError;
     private _killAll;
+    private _wipeThenTerminate;
 }

package/dist/stream/seal-stream-pool.js

@@ -379,15 +379,14 @@ export class SealStreamPool {
             reject(error);
         this._pending.clear();
         this._queue.length = 0;
-        for (const w of this._workers) {
-            try {
-                w.postMessage({ type: 'wipe' });
-            }
-            catch { /* worker may be terminated */ }
-            w.terminate();
-        }
-        this._workers.length = 0;
+        const workers = this._workers;
+        this._workers = [];
         this._idle.length = 0;
+        // Fire-and-forget: wipe each worker's key material, then terminate.
+        // On timeout, terminate anyway — the main-thread key handles are
+        // wiped below so the owning surface no longer has access.
+        for (const w of workers)
+            this._wipeThenTerminate(w);
         if (this._keys) {
             wipe(this._keys.bytes);
             this._keys = null;
@@ -397,4 +396,35 @@ export class SealStreamPool {
             this._masterKey = null;
         }
     }
+    _wipeThenTerminate(w) {
+        const WIPE_ACK_TIMEOUT_MS = 100;
+        let done = false;
+        // prefer-const false positive: `finish` (defined below) closes over
+        // `t` and is invoked synchronously from the catch path before the
+        // `t = setTimeout(...)` assignment runs.
+        // eslint-disable-next-line prefer-const
+        let t;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            if (t !== undefined)
+                clearTimeout(t);
+            w.removeEventListener('message', onMsg);
+            w.terminate();
+        };
+        const onMsg = (e) => {
+            if (e.data && e.data.type === 'wiped')
+                finish();
+        };
+        w.addEventListener('message', onMsg);
+        try {
+            w.postMessage({ type: 'wipe' });
+        }
+        catch {
+            finish();
+            return;
+        }
+        t = setTimeout(finish, WIPE_ACK_TIMEOUT_MS);
+    }
 }

package/dist/stream/seal-stream.js

@@ -80,30 +80,48 @@ export class SealStream {
     }
     push(chunk, opts) {
         if (this.state !== 'ready')
-            throw new Error('SealStream: cannot push after finalize');
+            throw new Error(`SealStream: cannot push in state '${this.state}'`);
+        // Argument validation runs before the crypto-failure try/catch so a
+        // too-big chunk throws without wiping keys or transitioning to 'failed'.
+        // The caller can retry with a correctly-sized chunk.
         if (chunk.length > this.chunkSize)
             throw new RangeError(`chunk exceeds chunkSize (${chunk.length} > ${this.chunkSize})`);
-        const nonce = makeCounterNonce(this.counter, TAG_DATA);
-        const result = this.cipher.sealChunk(this.keys, nonce, chunk, opts?.aad);
-        this.counter++;
-        return this.framed ? concat(u32beFrame(result.length), result) : result;
+        try {
+            const nonce = makeCounterNonce(this.counter, TAG_DATA);
+            const result = this.cipher.sealChunk(this.keys, nonce, chunk, opts?.aad);
+            this.counter++;
+            return this.framed ? concat(u32beFrame(result.length), result) : result;
+        }
+        catch (err) {
+            this.cipher.wipeKeys(this.keys);
+            this.state = 'failed';
+            throw err;
+        }
     }
     finalize(chunk, opts) {
         if (this.state !== 'ready')
-            throw new Error('SealStream: already finalized');
+            throw new Error(`SealStream: cannot finalize in state '${this.state}'`);
         if (chunk.length > this.chunkSize)
             throw new RangeError(`chunk exceeds chunkSize (${chunk.length} > ${this.chunkSize})`);
-        const nonce = makeCounterNonce(this.counter, TAG_FINAL);
-        const result = this.cipher.sealChunk(this.keys, nonce, chunk, opts?.aad);
-        this.cipher.wipeKeys(this.keys);
-        this.state = 'finalized';
-        return this.framed ? concat(u32beFrame(result.length), result) : result;
+        try {
+            const nonce = makeCounterNonce(this.counter, TAG_FINAL);
+            const result = this.cipher.sealChunk(this.keys, nonce, chunk, opts?.aad);
+            this.cipher.wipeKeys(this.keys);
+            this.state = 'finalized';
+            return this.framed ? concat(u32beFrame(result.length), result) : result;
+        }
+        catch (err) {
+            this.cipher.wipeKeys(this.keys);
+            this.state = 'failed';
+            throw err;
+        }
     }
     dispose() {
         if (this.state === 'ready') {
             this.cipher.wipeKeys(this.keys);
             this.state = 'finalized';
         }
+        // 'failed' already wiped keys; 'finalized' already wiped keys — no-op.
     }
     toTransformStream() {
         let headerSent = false;

package/dist/types.d.ts

@@ -22,3 +22,24 @@ export interface AEAD {
     decrypt(ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
     dispose(): void;
 }
+/**
+ * Stateless cipher PRF for Fortuna's generator slot. Produces `n` bytes of
+ * keystream from `(key, counter)` without mutating either input. Implementations
+ * are plain const objects, not classes.
+ */
+export interface Generator {
+    readonly keySize: number;
+    readonly blockSize: number;
+    readonly counterSize: number;
+    readonly wasmModules: readonly string[];
+    generate(key: Uint8Array, counter: Uint8Array, n: number): Uint8Array;
+}
+/**
+ * Stateless hash function for Fortuna's accumulator and reseed slots. Output
+ * size must match the generator's key size when paired in Fortuna.
+ */
+export interface HashFn {
+    readonly outputSize: number;
+    readonly wasmModules: readonly string[];
+    digest(msg: Uint8Array): Uint8Array;
+}

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-/** Hex string to Uint8Array. Accepts lowercase/uppercase, optional 0x prefix. Throws RangeError on odd-length input. */
+/** Hex string to Uint8Array. Accepts lowercase/uppercase, optional 0x prefix. Throws RangeError on odd-length or non-hex input. */
 export declare const hexToBytes: (hex: string) => Uint8Array;
 /** Uint8Array to lowercase hex string. */
 export declare const bytesToHex: (bytes: Uint8Array) => string;
@@ -6,18 +6,17 @@ export declare const bytesToHex: (bytes: Uint8Array) => string;
 export declare const utf8ToBytes: (str: string) => Uint8Array;
 /** Uint8Array to UTF-8 string. */
 export declare const bytesToUtf8: (bytes: Uint8Array) => string;
-/** Base64 or base64url string to Uint8Array. Handles padded, unpadded, and legacy %3d padding. Returns undefined on invalid input. */
-export declare const base64ToBytes: (b64: string) => Uint8Array | undefined;
+/** Base64 or base64url string to Uint8Array. Handles padded, unpadded, and legacy %3d padding. Throws RangeError on invalid input. */
+export declare const base64ToBytes: (b64: string) => Uint8Array;
 /** Uint8Array to base64 string. Pass url=true for base64url (RFC 4648 §5 — no padding characters). */
 export declare const bytesToBase64: (bytes: Uint8Array, url?: boolean) => string;
 export declare const CT_MAX_BYTES = 32768;
 /**
  * Constant-time byte-array equality.
- * Uses WASM SIMD when available (no JIT short-circuiting, no speculative
- * optimization). Falls back to a JS XOR-accumulate loop on runtimes
- * without SIMD support.
- * Length check is not constant-time (length is non-secret in all protocols).
- * Max input size: 32768 bytes per side (enforced regardless of code path).
+ * Runs entirely inside a WASM SIMD module (v128 XOR accumulate with
+ * branch-free reduction). Throws on runtimes without SIMD support —
+ * no JS fallback. Length check is not constant-time (length is
+ * non-secret in all protocols). Max input size: 32768 bytes per side.
  */
 export declare const constantTimeEqual: (a: Uint8Array, b: Uint8Array) => boolean;
 /** Zero a typed array in place. */