leviathan-crypto 1.0.0

package/dist/serpent/index.js

@@ -0,0 +1,242 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/serpent/index.ts
+//
+// Public API classes for the Serpent-256 WASM module.
+// Uses the init() module cache — call init('serpent') before constructing.
+import { getInstance, initModule } from '../init.js';
+const _embedded = () => import('../embedded/serpent.js').then(m => m.WASM_BASE64);
+export async function serpentInit(mode = 'embedded', opts) {
+    return initModule('serpent', _embedded, mode, opts);
+}
+function getExports() {
+    return getInstance('serpent').exports;
+}
+// ── Serpent ──────────────────────────────────────────────────────────────────
+export class Serpent {
+    x;
+    constructor() {
+        this.x = getExports();
+    }
+    loadKey(key) {
+        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)
+            throw new Error('loadKey failed');
+    }
+    encryptBlock(plaintext) {
+        if (plaintext.length !== 16)
+            throw new RangeError(`block must be 16 bytes (got ${plaintext.length})`);
+        const mem = new Uint8Array(this.x.memory.buffer);
+        const ptOff = this.x.getBlockPtOffset();
+        const ctOff = this.x.getBlockCtOffset();
+        mem.set(plaintext, ptOff);
+        this.x.encryptBlock();
+        return mem.slice(ctOff, ctOff + 16);
+    }
+    decryptBlock(ciphertext) {
+        if (ciphertext.length !== 16)
+            throw new RangeError(`block must be 16 bytes (got ${ciphertext.length})`);
+        const mem = new Uint8Array(this.x.memory.buffer);
+        const ptOff = this.x.getBlockPtOffset();
+        const ctOff = this.x.getBlockCtOffset();
+        mem.set(ciphertext, ctOff);
+        this.x.decryptBlock();
+        return mem.slice(ptOff, ptOff + 16);
+    }
+    dispose() {
+        this.x.wipeBuffers();
+    }
+}
+// ── 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.
+ */
+export class SerpentCtr {
+    x;
+    constructor(opts) {
+        if (!opts?.dangerUnauthenticated) {
+            throw new Error('leviathan-crypto: SerpentCtr is unauthenticated — use SerpentSeal instead. ' +
+                'To use SerpentCtr directly, pass { dangerUnauthenticated: true }.');
+        }
+        this.x = getExports();
+    }
+    beginEncrypt(key, nonce) {
+        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)
+            throw new RangeError(`nonce must be 16 bytes (got ${nonce.length})`);
+        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);
+        this.x.resetCounter();
+    }
+    encryptChunk(chunk) {
+        const maxChunk = this.x.getChunkSize();
+        if (chunk.length > maxChunk)
+            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();
+        mem.set(chunk, ptOff);
+        this.x.encryptChunk(chunk.length);
+        return mem.slice(ctOff, ctOff + chunk.length);
+    }
+    beginDecrypt(key, nonce) {
+        this.beginEncrypt(key, nonce);
+    }
+    decryptChunk(chunk) {
+        return this.encryptChunk(chunk);
+    }
+    dispose() {
+        this.x.wipeBuffers();
+    }
+}
+// ── PKCS7 helpers ────────────────────────────────────────────────────────────
+function pkcs7Pad(data) {
+    const padLen = 16 - (data.length % 16); // 1..16
+    const out = new Uint8Array(data.length + padLen);
+    out.set(data);
+    out.fill(padLen, data.length);
+    return out;
+}
+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 byte: ${padLen}`);
+    if (padLen > data.length)
+        throw new RangeError(`invalid PKCS7 padding: pad length ${padLen} exceeds data length ${data.length}`);
+    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);
+}
+// ── SerpentCbc ───────────────────────────────────────────────────────────────
+/**
+ * Serpent-256 in CBC mode with PKCS7 padding.
+ *
+ * **WARNING: CBC mode is unauthenticated.** Always authenticate the output
+ * with HMAC-SHA256 (Encrypt-then-MAC) or use `XChaCha20Poly1305` instead.
+ */
+export class SerpentCbc {
+    x;
+    constructor(opts) {
+        if (!opts?.dangerUnauthenticated) {
+            throw new Error('leviathan-crypto: SerpentCbc is unauthenticated — use SerpentSeal instead. ' +
+                'To use SerpentCbc directly, pass { dangerUnauthenticated: true }.');
+        }
+        this.x = getExports();
+    }
+    get mem() {
+        return new Uint8Array(this.x.memory.buffer);
+    }
+    /**
+   * 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
+   * @returns         ciphertext (length = ceil((plaintext.length + 1) / 16) * 16)
+   */
+    encrypt(key, iv, plaintext) {
+        this._loadKey(key);
+        this._setIv(iv);
+        const padded = pkcs7Pad(plaintext);
+        const output = new Uint8Array(padded.length);
+        const ptOff = this.x.getChunkPtOffset();
+        const ctOff = this.x.getChunkCtOffset();
+        const maxChunk = 65536;
+        for (let off = 0; off < padded.length; off += maxChunk) {
+            const chunk = padded.subarray(off, Math.min(off + maxChunk, padded.length));
+            this.mem.set(chunk, ptOff);
+            this.x.cbcEncryptChunk(chunk.length);
+            output.set(new Uint8Array(this.x.memory.buffer).subarray(ctOff, ctOff + chunk.length), off);
+        }
+        return output;
+    }
+    /**
+   * Decrypt Serpent-256 CBC + PKCS7.
+   * Throws if ciphertext length is not a non-zero multiple of 16 or PKCS7 is invalid.
+   */
+    decrypt(key, iv, ciphertext) {
+        if (ciphertext.length === 0 || ciphertext.length % 16 !== 0)
+            throw new RangeError('ciphertext length must be a non-zero multiple of 16');
+        this._loadKey(key);
+        this._setIv(iv);
+        const output = new Uint8Array(ciphertext.length);
+        const ctOff = this.x.getChunkCtOffset();
+        const ptOff = this.x.getChunkPtOffset();
+        const maxChunk = 65536;
+        for (let off = 0; off < ciphertext.length; off += maxChunk) {
+            const chunk = ciphertext.subarray(off, Math.min(off + maxChunk, ciphertext.length));
+            this.mem.set(chunk, ctOff);
+            this.x.cbcDecryptChunk(chunk.length);
+            output.set(new Uint8Array(this.x.memory.buffer).subarray(ptOff, ptOff + chunk.length), off);
+        }
+        return pkcs7Strip(output);
+    }
+    dispose() {
+        this.x.wipeBuffers();
+    }
+    _loadKey(key) {
+        if (key.length !== 16 && key.length !== 24 && key.length !== 32)
+            throw new RangeError(`Serpent key must be 16, 24, or 32 bytes (got ${key.length})`);
+        this.mem.set(key, this.x.getKeyOffset());
+        this.x.loadKey(key.length);
+    }
+    _setIv(iv) {
+        if (iv.length !== 16)
+            throw new RangeError(`CBC IV must be 16 bytes (got ${iv.length})`);
+        this.mem.set(iv, this.x.getCbcIvOffset());
+    }
+}
+// ── SerpentSeal re-export ─────────────────────────────────────────────────────
+export { SerpentSeal } from './seal.js';
+// ── SerpentStream re-export ───────────────────────────────────────────────────
+export { SerpentStream, sealChunk, openChunk } from './stream.js';
+// ── SerpentStreamPool re-export ───────────────────────────────────────────────
+export { SerpentStreamPool } from './stream-pool.js';
+// ── SerpentStreamSealer / SerpentStreamOpener re-export ───────────────────────
+export { SerpentStreamSealer, SerpentStreamOpener } from './stream-sealer.js';
+// ── SerpentStreamEncoder / SerpentStreamDecoder re-export ─────────────────────
+export { SerpentStreamEncoder, SerpentStreamDecoder } from './stream-encoder.js';
+// ── Ready check ──────────────────────────────────────────────────────────────
+export function _serpentReady() {
+    try {
+        getInstance('serpent');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/serpent/seal.d.ts

@@ -0,0 +1,8 @@
+export declare class SerpentSeal {
+    private readonly _cbc;
+    private readonly _hmac;
+    constructor();
+    encrypt(key: Uint8Array, plaintext: Uint8Array, _iv?: Uint8Array): Uint8Array;
+    decrypt(key: Uint8Array, data: Uint8Array): Uint8Array;
+    dispose(): void;
+}

package/dist/serpent/seal.js

@@ -0,0 +1,70 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/serpent/seal.ts
+//
+// SerpentSeal — authenticated Serpent-256 encryption.
+// Encrypt-then-MAC: SerpentCbc + HMAC-SHA256. Tier 2 pure-TS composition.
+import { SerpentCbc, _serpentReady } from './index.js';
+import { HMAC_SHA256, _sha2Ready } from '../sha2/index.js';
+import { concat, constantTimeEqual } from '../utils.js';
+export class SerpentSeal {
+    _cbc;
+    _hmac;
+    constructor() {
+        if (!_serpentReady() || !_sha2Ready())
+            throw new Error('leviathan-crypto: call init([\'serpent\', \'sha2\']) before using SerpentSeal');
+        this._cbc = new SerpentCbc({ dangerUnauthenticated: true });
+        this._hmac = new HMAC_SHA256();
+    }
+    // _iv: test seam only — inject a fixed IV for deterministic KAT vectors
+    encrypt(key, plaintext, _iv) {
+        if (key.length !== 64)
+            throw new RangeError(`SerpentSeal key must be 64 bytes (got ${key.length})`);
+        const encKey = key.subarray(0, 32);
+        const macKey = key.subarray(32, 64);
+        const iv = (_iv && _iv.length === 16) ? _iv : new Uint8Array(16);
+        if (!_iv || _iv.length !== 16)
+            crypto.getRandomValues(iv);
+        const ciphertext = this._cbc.encrypt(encKey, iv, plaintext);
+        const tag = this._hmac.hash(macKey, concat(iv, ciphertext));
+        return concat(concat(iv, ciphertext), tag);
+    }
+    decrypt(key, data) {
+        if (key.length !== 64)
+            throw new RangeError(`SerpentSeal key must be 64 bytes (got ${key.length})`);
+        if (data.length < 64)
+            throw new RangeError('SerpentSeal ciphertext too short');
+        const encKey = key.subarray(0, 32);
+        const macKey = key.subarray(32, 64);
+        const iv = data.subarray(0, 16);
+        const tag = data.subarray(data.length - 32);
+        const ciphertext = data.subarray(16, data.length - 32);
+        const expectedTag = this._hmac.hash(macKey, concat(iv, ciphertext));
+        if (!constantTimeEqual(tag, expectedTag))
+            throw new Error('SerpentSeal: authentication failed');
+        return this._cbc.decrypt(encKey, iv, ciphertext);
+    }
+    dispose() {
+        this._cbc.dispose();
+        this._hmac.dispose();
+    }
+}

package/dist/serpent/stream-encoder.d.ts

@@ -0,0 +1,20 @@
+export declare class SerpentStreamEncoder {
+    private readonly _sealer;
+    private _state;
+    constructor(key: Uint8Array, chunkSize?: number, _nonce?: Uint8Array, _ivs?: Uint8Array[]);
+    header(): Uint8Array;
+    encode(plaintext: Uint8Array): Uint8Array;
+    encodeFinal(plaintext: Uint8Array): Uint8Array;
+    dispose(): void;
+}
+export declare class SerpentStreamDecoder {
+    private readonly _opener;
+    private readonly _buf;
+    private readonly _maxFrame;
+    private _bufLen;
+    private _dead;
+    constructor(key: Uint8Array, header: Uint8Array);
+    feed(bytes: Uint8Array): Uint8Array[];
+    private _wipe;
+    dispose(): void;
+}

package/dist/serpent/stream-encoder.js

@@ -0,0 +1,167 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/serpent/stream-encoder.ts
+//
+// Tier 2 pure-TS composition: SerpentStreamSealer / SerpentStreamOpener
+// with u32be length-prefixed framing.
+//
+// SerpentStreamEncoder: wraps SerpentStreamSealer, prepends u32be(sealedLen)
+// SerpentStreamDecoder: wraps SerpentStreamOpener, buffers input and assembles
+//                       complete frames before dispatching to opener.open()
+//
+// Wire format per chunk:
+//   u32be(sealedLen) || IV(16) || CBC_ciphertext(padded) || HMAC(32)
+//
+// Use these classes when chunks will be concatenated into a flat byte array
+// (files, buffered TCP, etc). Use SerpentStreamSealer/Opener directly when
+// the transport already frames messages (WebSocket, IPC, etc).
+import { SerpentStreamSealer, SerpentStreamOpener } from './stream-sealer.js';
+import { _serpentReady } from './index.js';
+import { _sha2Ready } from '../sha2/index.js';
+import { wipe } from '../utils.js';
+import { u32be } from './stream.js';
+export class SerpentStreamEncoder {
+    _sealer;
+    _state;
+    // _nonce, _ivs: test seams — passed through to SerpentStreamSealer
+    constructor(key, chunkSize, _nonce, _ivs) {
+        if (!_serpentReady())
+            throw new Error('leviathan-crypto: call init([\'serpent\']) before using SerpentStreamEncoder');
+        if (!_sha2Ready())
+            throw new Error('leviathan-crypto: call init([\'sha2\']) before using SerpentStreamEncoder');
+        this._sealer = new SerpentStreamSealer(key, chunkSize, _nonce, _ivs);
+        this._state = 'fresh';
+    }
+    header() {
+        if (this._state === 'encoding')
+            throw new Error('SerpentStreamEncoder: header() already called');
+        if (this._state === 'dead')
+            throw new Error('SerpentStreamEncoder: stream is closed');
+        this._state = 'encoding';
+        return this._sealer.header();
+    }
+    encode(plaintext) {
+        if (this._state === 'fresh')
+            throw new Error('SerpentStreamEncoder: call header() first');
+        if (this._state === 'dead')
+            throw new Error('SerpentStreamEncoder: stream is closed');
+        const sealed = this._sealer.seal(plaintext);
+        return _prependLen(sealed);
+    }
+    encodeFinal(plaintext) {
+        if (this._state === 'fresh')
+            throw new Error('SerpentStreamEncoder: call header() first');
+        if (this._state === 'dead')
+            throw new Error('SerpentStreamEncoder: stream is closed');
+        const sealed = this._sealer.final(plaintext);
+        this._state = 'dead';
+        return _prependLen(sealed);
+    }
+    dispose() {
+        if (this._state !== 'dead') {
+            this._sealer.dispose();
+            this._state = 'dead';
+        }
+    }
+}
+// ── SerpentStreamDecoder ─────────────────────────────────────────────────────
+export class SerpentStreamDecoder {
+    _opener;
+    _buf; // fixed-size accumulation buffer
+    _maxFrame; // 4 + max sealed chunk size
+    _bufLen; // valid bytes currently in _buf
+    _dead;
+    constructor(key, header) {
+        if (!_serpentReady())
+            throw new Error('leviathan-crypto: call init([\'serpent\']) before using SerpentStreamDecoder');
+        if (!_sha2Ready())
+            throw new Error('leviathan-crypto: call init([\'sha2\']) before using SerpentStreamDecoder');
+        this._opener = new SerpentStreamOpener(key, header);
+        // Parse chunkSize from stream header (bytes 16..20, u32be)
+        const cs = (header[16] << 24 | header[17] << 16 | header[18] << 8 | header[19]) >>> 0;
+        // Max sealed chunk size: IV(16) + PKCS7-padded ciphertext + HMAC(32)
+        // PKCS7: plaintext always padded to next multiple of 16 (minimum 1 pad byte)
+        const maxSealed = 16 + (cs + (16 - (cs % 16))) + 32;
+        this._maxFrame = 4 + maxSealed;
+        this._buf = new Uint8Array(this._maxFrame);
+        this._bufLen = 0;
+        this._dead = false;
+    }
+    feed(bytes) {
+        if (this._dead)
+            throw new Error('SerpentStreamDecoder: stream is closed');
+        // Append incoming bytes to accumulation buffer
+        if (this._bufLen + bytes.length > this._maxFrame) {
+            throw new Error('SerpentStreamDecoder: input exceeds maximum frame size');
+        }
+        this._buf.set(bytes, this._bufLen);
+        this._bufLen += bytes.length;
+        const results = [];
+        while (true) {
+            // Need at least 4 bytes for the length prefix
+            if (this._bufLen < 4)
+                break;
+            const sealedLen = ((this._buf[0] << 24 | this._buf[1] << 16 |
+                this._buf[2] << 8 | this._buf[3]) >>> 0);
+            const frameLen = 4 + sealedLen;
+            // Need the full frame
+            if (this._bufLen < frameLen)
+                break;
+            // Complete frame — dispatch to opener
+            const sealedChunk = this._buf.subarray(4, frameLen);
+            const plaintext = this._opener.open(sealedChunk);
+            results.push(plaintext);
+            if (this._opener.closed) {
+                // After final chunk: any leftover bytes are a protocol error
+                const remaining = this._bufLen - frameLen;
+                if (remaining > 0) {
+                    this._wipe();
+                    throw new Error('SerpentStreamDecoder: unexpected bytes after final chunk');
+                }
+                this._wipe();
+                return results;
+            }
+            // Shift remaining bytes to front of buffer — no allocation
+            const remaining = this._bufLen - frameLen;
+            this._buf.copyWithin(0, frameLen, frameLen + remaining);
+            this._bufLen = remaining;
+        }
+        return results;
+    }
+    _wipe() {
+        wipe(this._buf);
+        this._bufLen = 0;
+        this._opener.dispose();
+        this._dead = true;
+    }
+    dispose() {
+        if (!this._dead)
+            this._wipe();
+    }
+}
+// ── helpers ──────────────────────────────────────────────────────────────────
+function _prependLen(chunk) {
+    const out = new Uint8Array(4 + chunk.length);
+    out.set(u32be(chunk.length), 0);
+    out.set(chunk, 4);
+    return out;
+}

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

@@ -0,0 +1,48 @@
+export interface StreamPoolOpts {
+    /** Number of workers. Default: navigator.hardwareConcurrency ?? 4 */
+    workers?: number;
+}
+/**
+ * Parallel worker pool for SerpentStream chunked authenticated encryption.
+ *
+ * Each worker owns its own `serpent.wasm` and `sha2.wasm` instances with
+ * isolated linear memory. Key derivation happens on the main thread; workers
+ * receive pre-derived encKey/macKey per chunk.
+ *
+ * Produces the same wire format as `SerpentStream` -- either can decrypt
+ * the other's output.
+ */
+export declare class SerpentStreamPool {
+    private readonly _workers;
+    private readonly _idle;
+    private readonly _queue;
+    private readonly _pending;
+    private readonly _hkdf;
+    private _nextId;
+    private _disposed;
+    private constructor();
+    /**
+     * Create a new pool. Requires `init(['serpent', 'sha2'])` to have been called.
+     * Compiles both WASM modules once and distributes them to all workers.
+     */
+    static create(opts?: StreamPoolOpts): Promise<SerpentStreamPool>;
+    /**
+     * Encrypt plaintext with SerpentStream chunked authenticated encryption.
+     * Returns the complete wire format (header + encrypted chunks).
+     */
+    seal(key: Uint8Array, plaintext: Uint8Array, chunkSize?: number): Promise<Uint8Array>;
+    /**
+     * Decrypt SerpentStream wire format.
+     * If any chunk fails authentication, rejects immediately -- no partial plaintext.
+     */
+    open(key: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
+    /** Terminates all workers. Rejects all pending and queued jobs. */
+    dispose(): void;
+    /** Number of workers in the pool. */
+    get size(): number;
+    /** Number of jobs currently queued (waiting for a free worker). */
+    get queueDepth(): number;
+    private _dispatch;
+    private _send;
+    private _onMessage;
+}