leviathan-crypto 2.0.1 → 3.0.0

package/dist/serpent/index.d.ts

@@ -1,12 +1,45 @@
 import type { WasmSource } from '../wasm-source.js';
+/**
+ * Load and initialise the Serpent WASM module from `source`.
+ * Must be called before constructing any Serpent class.
+ * @param source  WASM binary, gzip+base64 string, URL, ArrayBuffer, Uint8Array,
+ *                pre-compiled WebAssembly.Module, Response, or Promise<Response>
+ */
 export declare function serpentInit(source: WasmSource): Promise<void>;
 export type { WasmSource };
+export { isInitialized } from '../init.js';
+/**
+ * Low-level Serpent-256 block cipher, raw ECB encrypt/decrypt.
+ *
+ * Atomic (stateless) class: each method call is independent.
+ * Does not hold exclusive module access; cannot be used while a stateful
+ * instance (`SerpentCtr`, `SerpentCbc`, `SerpentCipher`) is alive.
+ * Call `dispose()` after use to wipe WASM key material.
+ */
 export declare class Serpent {
     private readonly x;
     constructor();
+    /**
+     * Expand `key` into the WASM key schedule. Must be called before
+     * `encryptBlock` / `decryptBlock`.
+     * @param key  16, 24, or 32 bytes
+     */
     loadKey(key: Uint8Array): void;
+    /**
+     * Encrypt one 128-bit block with the previously loaded key schedule.
+     * Serpent AES submission §2.2.
+     * @param plaintext  16-byte plaintext block
+     * @returns          16-byte ciphertext block
+     */
     encryptBlock(plaintext: Uint8Array): Uint8Array;
+    /**
+     * Decrypt one 128-bit block with the previously loaded key schedule.
+     * Serpent AES submission §2.2.
+     * @param ciphertext  16-byte ciphertext block
+     * @returns           16-byte plaintext block
+     */
     decryptBlock(ciphertext: Uint8Array): Uint8Array;
+    /** Wipe WASM key material and release memory. */
     dispose(): void;
 }
 /**
@@ -15,19 +48,47 @@ export declare class Serpent {
  * **WARNING: CTR mode is unauthenticated.** An attacker can flip ciphertext
  * bits without detection. Always pair with HMAC-SHA256 (Encrypt-then-MAC)
  * or use `XChaCha20Poly1305` instead.
+ *
+ * Holds exclusive access to the `serpent` WASM module from construction
+ * until `dispose()`. Constructing a second SerpentCtr/SerpentCbc/
+ * SerpentCipher or any other serpent user while this instance is live
+ * throws. Call `dispose()` when done.
  */
 export declare class SerpentCtr {
     private readonly x;
+    private _tok;
     constructor(opts?: {
         dangerUnauthenticated: true;
     });
+    /**
+     * Load key and nonce into WASM state and reset the block counter to 0.
+     * Must be called before each message.
+     * @param key    16, 24, or 32 bytes
+     * @param nonce  16 bytes, must be unique per (key, message)
+     */
     beginEncrypt(key: Uint8Array, nonce: Uint8Array): void;
+    /**
+     * XOR `chunk` with the next keystream block(s). Counter advances automatically.
+     * @param chunk  Plaintext chunk, must not exceed WASM CHUNK_SIZE
+     * @returns      Ciphertext of the same length
+     */
     encryptChunk(chunk: Uint8Array): Uint8Array;
+    /**
+     * Alias for `beginEncrypt`, CTR mode is symmetric.
+     * @param key    16, 24, or 32 bytes
+     * @param nonce  16 bytes, must match the value used to encrypt
+     */
     beginDecrypt(key: Uint8Array, nonce: Uint8Array): void;
+    /**
+     * Alias for `encryptChunk`, CTR mode is symmetric.
+     * @param chunk  Ciphertext chunk
+     * @returns      Plaintext of the same length
+     */
     decryptChunk(chunk: Uint8Array): Uint8Array;
+    /** Wipe WASM state and release exclusive module access. Idempotent. */
     dispose(): void;
 }
 export { SerpentCbc } from './serpent-cbc.js';
 export { AuthenticationError } from '../errors.js';
 export { SerpentCipher } from './cipher-suite.js';
-export declare function _serpentReady(): boolean;
+export { SerpentGenerator } from './generator.js';

package/dist/serpent/index.js

@@ -22,29 +22,60 @@
 // src/ts/serpent/index.ts
 //
 // Public API classes for the Serpent-256 WASM module.
-// Uses the init() module cache — call serpentInit(source) before constructing.
-import { getInstance, initModule } from '../init.js';
+// Uses the init() module cache, call serpentInit(source) before constructing.
+import { getInstance, initModule, _acquireModule, _releaseModule, _assertNotOwned } from '../init.js';
+/**
+ * Load and initialise the Serpent WASM module from `source`.
+ * Must be called before constructing any Serpent class.
+ * @param source  WASM binary, gzip+base64 string, URL, ArrayBuffer, Uint8Array,
+ *                pre-compiled WebAssembly.Module, Response, or Promise<Response>
+ */
 export async function serpentInit(source) {
     return initModule('serpent', source);
 }
+export { isInitialized } from '../init.js';
+/** Returns the raw serpent WASM export object. @internal */
 function getExports() {
     return getInstance('serpent').exports;
 }
-// ── Serpent ──────────────────────────────────────────────────────────────────
+// ── Serpent ─────────────────────────────────────────────────────────────────
+/**
+ * Low-level Serpent-256 block cipher, raw ECB encrypt/decrypt.
+ *
+ * Atomic (stateless) class: each method call is independent.
+ * Does not hold exclusive module access; cannot be used while a stateful
+ * instance (`SerpentCtr`, `SerpentCbc`, `SerpentCipher`) is alive.
+ * Call `dispose()` after use to wipe WASM key material.
+ */
 export class Serpent {
     x;
     constructor() {
         this.x = getExports();
     }
+    /**
+     * Expand `key` into the WASM key schedule. Must be called before
+     * `encryptBlock` / `decryptBlock`.
+     * @param key  16, 24, or 32 bytes
+     */
     loadKey(key) {
+        _assertNotOwned('serpent');
         if (key.length !== 16 && key.length !== 24 && key.length !== 32)
             throw new RangeError(`key must be 16, 24, or 32 bytes (got ${key.length})`);
         const mem = new Uint8Array(this.x.memory.buffer);
         mem.set(key, this.x.getKeyOffset());
-        if (this.x.loadKey(key.length) !== 0)
+        if (this.x.loadKey(key.length) !== 0) {
+            this.x.wipeBuffers();
             throw new Error('loadKey failed');
+        }
     }
+    /**
+     * Encrypt one 128-bit block with the previously loaded key schedule.
+     * Serpent AES submission §2.2.
+     * @param plaintext  16-byte plaintext block
+     * @returns          16-byte ciphertext block
+     */
     encryptBlock(plaintext) {
+        _assertNotOwned('serpent');
         if (plaintext.length !== 16)
             throw new RangeError(`block must be 16 bytes (got ${plaintext.length})`);
         const mem = new Uint8Array(this.x.memory.buffer);
@@ -54,7 +85,14 @@ export class Serpent {
         this.x.encryptBlock();
         return mem.slice(ctOff, ctOff + 16);
     }
+    /**
+     * Decrypt one 128-bit block with the previously loaded key schedule.
+     * Serpent AES submission §2.2.
+     * @param ciphertext  16-byte ciphertext block
+     * @returns           16-byte plaintext block
+     */
     decryptBlock(ciphertext) {
+        _assertNotOwned('serpent');
         if (ciphertext.length !== 16)
             throw new RangeError(`block must be 16 bytes (got ${ciphertext.length})`);
         const mem = new Uint8Array(this.x.memory.buffer);
@@ -64,28 +102,45 @@ export class Serpent {
         this.x.decryptBlock();
         return mem.slice(ptOff, ptOff + 16);
     }
+    /** Wipe WASM key material and release memory. */
     dispose() {
+        _assertNotOwned('serpent');
         this.x.wipeBuffers();
     }
 }
-// ── SerpentCtr ───────────────────────────────────────────────────────────────
+// ── SerpentCtr ──────────────────────────────────────────────────────────────
 /**
  * Serpent-256 in CTR mode.
  *
  * **WARNING: CTR mode is unauthenticated.** An attacker can flip ciphertext
  * bits without detection. Always pair with HMAC-SHA256 (Encrypt-then-MAC)
  * or use `XChaCha20Poly1305` instead.
+ *
+ * Holds exclusive access to the `serpent` WASM module from construction
+ * until `dispose()`. Constructing a second SerpentCtr/SerpentCbc/
+ * SerpentCipher or any other serpent user while this instance is live
+ * throws. Call `dispose()` when done.
  */
 export class SerpentCtr {
     x;
+    _tok;
     constructor(opts) {
         if (!opts?.dangerUnauthenticated) {
-            throw new Error('leviathan-crypto: SerpentCtr is unauthenticated — use Seal with SerpentCipher instead. ' +
+            throw new Error('leviathan-crypto: SerpentCtr is unauthenticated, use Seal with SerpentCipher instead. ' +
                 'To use SerpentCtr directly, pass { dangerUnauthenticated: true }.');
         }
         this.x = getExports();
+        this._tok = _acquireModule('serpent');
     }
+    /**
+     * Load key and nonce into WASM state and reset the block counter to 0.
+     * Must be called before each message.
+     * @param key    16, 24, or 32 bytes
+     * @param nonce  16 bytes, must be unique per (key, message)
+     */
     beginEncrypt(key, nonce) {
+        if (this._tok === undefined)
+            throw new Error('SerpentCtr: instance has been disposed');
         if (key.length !== 16 && key.length !== 24 && key.length !== 32)
             throw new RangeError('key must be 16, 24, or 32 bytes');
         if (nonce.length !== 16)
@@ -93,13 +148,23 @@ export class SerpentCtr {
         const mem = new Uint8Array(this.x.memory.buffer);
         mem.set(key, this.x.getKeyOffset());
         mem.set(nonce, this.x.getNonceOffset());
-        this.x.loadKey(key.length);
+        if (this.x.loadKey(key.length) !== 0) {
+            this.x.wipeBuffers();
+            throw new Error('SerpentCtr: loadKey failed');
+        }
         this.x.resetCounter();
     }
+    /**
+     * XOR `chunk` with the next keystream block(s). Counter advances automatically.
+     * @param chunk  Plaintext chunk, must not exceed WASM CHUNK_SIZE
+     * @returns      Ciphertext of the same length
+     */
     encryptChunk(chunk) {
+        if (this._tok === undefined)
+            throw new Error('SerpentCtr: instance has been disposed');
         const maxChunk = this.x.getChunkSize();
         if (chunk.length > maxChunk)
-            throw new RangeError(`chunk exceeds maximum size of ${maxChunk} bytes — split into smaller chunks`);
+            throw new RangeError(`chunk exceeds maximum size of ${maxChunk} bytes, split into smaller chunks`);
         const mem = new Uint8Array(this.x.memory.buffer);
         const ptOff = this.x.getChunkPtOffset();
         const ctOff = this.x.getChunkCtOffset();
@@ -107,28 +172,39 @@ export class SerpentCtr {
         this.x.encryptChunk_simd(chunk.length);
         return mem.slice(ctOff, ctOff + chunk.length);
     }
+    /**
+     * Alias for `beginEncrypt`, CTR mode is symmetric.
+     * @param key    16, 24, or 32 bytes
+     * @param nonce  16 bytes, must match the value used to encrypt
+     */
     beginDecrypt(key, nonce) {
         this.beginEncrypt(key, nonce);
     }
+    /**
+     * Alias for `encryptChunk`, CTR mode is symmetric.
+     * @param chunk  Ciphertext chunk
+     * @returns      Plaintext of the same length
+     */
     decryptChunk(chunk) {
         return this.encryptChunk(chunk);
     }
+    /** Wipe WASM state and release exclusive module access. Idempotent. */
     dispose() {
-        this.x.wipeBuffers();
+        if (this._tok === undefined)
+            return;
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('serpent', this._tok);
+            this._tok = undefined;
+        }
     }
 }
-// ── SerpentCbc ───────────────────────────────────────────────────────────────
+// ── SerpentCbc ──────────────────────────────────────────────────────────────
 export { SerpentCbc } from './serpent-cbc.js';
 export { AuthenticationError } from '../errors.js';
-// ── SerpentCipher re-export ───────────────────────────────────────────────────
+// ── SerpentCipher re-export ─────────────────────────────────────────────────
 export { SerpentCipher } from './cipher-suite.js';
-// ── Ready check ──────────────────────────────────────────────────────────────
-export function _serpentReady() {
-    try {
-        getInstance('serpent');
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+// ── SerpentGenerator ────────────────────────────────────────────────────────
+export { SerpentGenerator } from './generator.js';

package/dist/serpent/pool-worker.js

@@ -3,108 +3,31 @@
 //
 // Worker for SealStreamPool with SerpentCipher.
 // Holds 3 derived keys (enc/mac/iv) and raw WASM instances.
-// Direct WASM calls — no initModule (avoids same-thread module cache conflicts
+// Direct WASM calls, no initModule (avoids same-thread module cache conflicts
 // in @vitest/web-worker test environment).
+//
+// All HMAC / CBC / PKCS7 primitives come from `./shared-ops.js`, the same
+// module the main-thread `SerpentCipher` uses. Byte-identical output with
+// the main thread is the regression guard (see
+// test/unit/stream/pool-byte-exact.test.ts). Must NOT import from `../init.js`:
+// workers have their own isolated WASM instances, no shared-state registry.
 import { constantTimeEqual, wipe, concat } from '../utils.js';
 import { AuthenticationError } from '../errors.js';
+import { hmacSha256, cbcEncryptChunk, cbcDecryptChunk, } from './shared-ops.js';
 let sha2;
 let serpent;
 let keys;
-function hmacSha256(key, msg) {
-    const x = sha2;
-    let k = key;
-    if (k.length > 64) {
-        x.sha256Init();
-        feedSha2(k);
-        x.sha256Final();
-        const mem = new Uint8Array(x.memory.buffer);
-        k = mem.slice(x.getSha256OutOffset(), x.getSha256OutOffset() + 32);
-    }
-    const mem = new Uint8Array(x.memory.buffer);
-    mem.set(k, x.getSha256InputOffset());
-    x.hmac256Init(k.length);
-    feedHmac(msg);
-    x.hmac256Final();
-    return new Uint8Array(x.memory.buffer).slice(x.getSha256OutOffset(), x.getSha256OutOffset() + 32);
-}
-function feedSha2(data) {
-    const x = sha2;
-    const mem = new Uint8Array(x.memory.buffer);
-    const off = x.getSha256InputOffset();
-    let pos = 0;
-    while (pos < data.length) {
-        const n = Math.min(data.length - pos, 64);
-        mem.set(data.subarray(pos, pos + n), off);
-        x.sha256Update(n);
-        pos += n;
-    }
-}
-function feedHmac(data) {
-    const x = sha2;
-    const mem = new Uint8Array(x.memory.buffer);
-    const off = x.getSha256InputOffset();
-    let pos = 0;
-    while (pos < data.length) {
-        const n = Math.min(data.length - pos, 64);
-        mem.set(data.subarray(pos, pos + n), off);
-        x.hmac256Update(n);
-        pos += n;
-    }
-}
-function pkcs7Pad(data) {
-    const padLen = 16 - (data.length % 16);
-    const out = new Uint8Array(data.length + padLen);
-    out.set(data);
-    out.fill(padLen, data.length);
-    return out;
-}
-// pkcs7Strip is only called after HMAC authentication succeeds (verify-then-decrypt).
-// The early throw on invalid padLen is not a padding oracle in this context —
-// the HMAC check is the oracle gate and runs in constant time before this point.
-// If you move this call to a pre-auth site, revisit the timing properties.
-function pkcs7Strip(data) {
-    if (data.length === 0)
-        throw new RangeError('empty ciphertext');
-    const padLen = data[data.length - 1];
-    if (padLen === 0 || padLen > 16)
-        throw new RangeError('invalid PKCS7 padding');
-    if (padLen > data.length)
-        throw new RangeError('invalid PKCS7 padding');
-    let bad = 0;
-    for (let i = data.length - padLen; i < data.length; i++)
-        bad |= data[i] ^ padLen;
-    if (bad !== 0)
-        throw new RangeError('invalid PKCS7 padding');
-    return data.subarray(0, data.length - padLen);
-}
-function cbcEncrypt(encKey, iv, plaintext) {
-    const s = serpent;
-    const mem = new Uint8Array(s.memory.buffer);
-    mem.set(encKey, s.getKeyOffset());
-    s.loadKey(encKey.length);
-    mem.set(iv, s.getCbcIvOffset());
-    const padded = pkcs7Pad(plaintext);
-    mem.set(padded, s.getChunkPtOffset());
-    const ret = s.cbcEncryptChunk(padded.length);
-    if (ret < 0)
-        throw new RangeError(`cbcEncryptChunk rejected len=${padded.length}` +
-            ` (WASM CHUNK_SIZE=${s.getChunkSize()})`);
-    return new Uint8Array(s.memory.buffer).slice(s.getChunkCtOffset(), s.getChunkCtOffset() + padded.length);
-}
-function cbcDecrypt(encKey, iv, ct) {
-    const s = serpent;
-    const mem = new Uint8Array(s.memory.buffer);
-    mem.set(encKey, s.getKeyOffset());
-    s.loadKey(encKey.length);
-    mem.set(iv, s.getCbcIvOffset());
-    mem.set(ct, s.getChunkCtOffset());
-    const ret = s.cbcDecryptChunk(ct.length);
-    if (ret < 0)
-        throw new RangeError(`cbcDecryptChunk rejected len=${ct.length}` +
-            ` (WASM CHUNK_SIZE=${s.getChunkSize()})`);
-    const raw = new Uint8Array(s.memory.buffer).slice(s.getChunkPtOffset(), s.getChunkPtOffset() + ct.length);
-    return pkcs7Strip(raw);
-}
+/**
+ * Message handler for the Serpent pool worker.
+ *
+ * Accepts three message types:
+ * - `'init'` , instantiate sha2 + serpent WASM modules and store derived keys
+ * - `'wipe'` , zero keys and WASM buffers, then post `{ type: 'wiped' }`
+ * - `{ op: 'seal' | 'open', ... }`, encrypt or decrypt one chunk
+ *
+ * Replies with `{ type: 'result', id, data }` on success or
+ * `{ type: 'error', id, message, isAuthError }` on failure.
+ */
 self.onmessage = async (e) => {
     const msg = e.data;
     if (msg.type === 'init') {
@@ -122,6 +45,8 @@ self.onmessage = async (e) => {
             self.postMessage({ type: 'ready' });
         }
         catch (err) {
+            if (msg.derivedKeyBytes)
+                msg.derivedKeyBytes.fill(0);
             self.postMessage({ type: 'error', id: -1, message: err.message, isAuthError: false });
         }
         return;
@@ -136,6 +61,7 @@ self.onmessage = async (e) => {
             serpent.wipeBuffers();
         sha2 = undefined;
         serpent = undefined;
+        self.postMessage({ type: 'wiped' });
         return;
     }
     if (!keys || !sha2 || !serpent) {
@@ -151,14 +77,14 @@ self.onmessage = async (e) => {
         const ivKey = jobKey.subarray(64, 96);
         let result;
         if (op === 'seal') {
-            const ivFull = hmacSha256(ivKey, counterNonce);
+            const ivFull = hmacSha256(sha2, ivKey, counterNonce);
             const iv = ivFull.slice(0, 16);
             wipe(ivFull);
-            const ct = cbcEncrypt(encKey, iv, data);
+            const ct = cbcEncryptChunk(serpent, encKey, iv, data);
             const aadLenBuf = new Uint8Array(4);
             new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
             const tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
-            const tag = hmacSha256(macKey, tagInput);
+            const tag = hmacSha256(sha2, macKey, tagInput);
             result = concat(ct, tag);
             wipe(iv);
             wipe(tagInput);
@@ -166,13 +92,13 @@ self.onmessage = async (e) => {
         else {
             const ct = data.subarray(0, data.length - 32);
             const receivedTag = data.subarray(data.length - 32);
-            const ivFull = hmacSha256(ivKey, counterNonce);
+            const ivFull = hmacSha256(sha2, ivKey, counterNonce);
             const iv = ivFull.slice(0, 16);
             wipe(ivFull);
             const aadLenBuf = new Uint8Array(4);
             new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
             const tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
-            const expectedTag = hmacSha256(macKey, tagInput);
+            const expectedTag = hmacSha256(sha2, macKey, tagInput);
             // CRITICAL: verify HMAC before decrypting (Vaudenay 2002)
             if (!constantTimeEqual(expectedTag, receivedTag)) {
                 wipe(iv);
@@ -182,7 +108,7 @@ self.onmessage = async (e) => {
             }
             wipe(tagInput);
             wipe(expectedTag);
-            result = cbcDecrypt(encKey, iv, ct);
+            result = cbcDecryptChunk(serpent, encKey, iv, ct);
             wipe(iv);
         }
         const transfer = result.buffer instanceof ArrayBuffer ? [result.buffer] : [];

package/dist/serpent/serpent-cbc.d.ts

@@ -3,28 +3,38 @@
  *
  * **WARNING: CBC mode is unauthenticated.** Always authenticate the output
  * with HMAC-SHA256 (Encrypt-then-MAC) or use `XChaCha20Poly1305` instead.
+ *
+ * Holds exclusive access to the `serpent` WASM module from construction
+ * until `dispose()`. Constructing a second SerpentCbc/SerpentCtr/
+ * SerpentCipher or any other serpent user while this instance is live
+ * throws. Call `dispose()` when done.
  */
 export declare class SerpentCbc {
     private readonly x;
+    private _tok;
     constructor(opts?: {
         dangerUnauthenticated: true;
     });
-    private get mem();
     /**
    * Encrypt plaintext with Serpent-256 CBC + PKCS7 padding.
    *
    * @param key       16, 24, or 32 bytes
-   * @param iv        16 bytes — must be random and unique per (key, message)
-   * @param plaintext any length — PKCS7 padding applied automatically
+   * @param iv        16 bytes, must be random and unique per (key, message)
+   * @param plaintext any length, PKCS7 padding applied automatically
    * @returns         ciphertext (length = ceil((plaintext.length + 1) / 16) * 16)
    */
     encrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Uint8Array;
     /**
    * Decrypt Serpent-256 CBC + PKCS7.
-   * Throws if ciphertext length is not a non-zero multiple of 16 or PKCS7 is invalid.
+   *
+   * All failure modes, empty input, non-multiple-of-16 length, and any
+   * PKCS7 validation failure, throw the same generic `RangeError` with
+   * message `'invalid ciphertext'`. Padding validation runs branch-free
+   * over the last 16 bytes regardless of where the mismatch is, closing
+   * the Vaudenay 2002 padding-oracle surface for callers using
+   * `{ dangerUnauthenticated: true }` without an outer HMAC.
    */
     decrypt(key: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+    /** Wipe WASM state and release exclusive module access. Idempotent. */
     dispose(): void;
-    private _loadKey;
-    private _setIv;
 }