leviathan-crypto 1.1.0 → 1.3.0

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

@@ -5,11 +5,19 @@ export declare class SerpentStreamSealer {
     private readonly _cbc;
     private readonly _hmac;
     private readonly _hkdf;
+    private readonly _framed;
     private readonly _ivs;
     private _ivIdx;
     private _index;
     private _state;
-    constructor(key: Uint8Array, chunkSize?: number, _nonce?: Uint8Array, _ivs?: Uint8Array[]);
+    /** Public: consumers use this 3-param form. */
+    constructor(key: Uint8Array, chunkSize?: number, opts?: {
+        framed?: boolean;
+    });
+    /** @internal Test-only overload to inject fixed nonce/IVs for deterministic KAT vectors. */
+    constructor(key: Uint8Array, chunkSize: number | undefined, opts: {
+        framed?: boolean;
+    } | undefined, _nonce: Uint8Array, _ivs?: Uint8Array[]);
     header(): Uint8Array;
     seal(plaintext: Uint8Array): Uint8Array;
     final(plaintext: Uint8Array): Uint8Array;
@@ -24,11 +32,19 @@ export declare class SerpentStreamOpener {
     private readonly _cbc;
     private readonly _hmac;
     private readonly _hkdf;
+    private readonly _framed;
+    private readonly _buf;
+    private readonly _maxFrame;
+    private _bufLen;
     private _index;
     private _dead;
-    constructor(key: Uint8Array, header: Uint8Array);
+    constructor(key: Uint8Array, header: Uint8Array, opts?: {
+        framed?: boolean;
+    });
     get closed(): boolean;
     open(chunk: Uint8Array): Uint8Array;
+    private _openRaw;
+    feed(bytes: Uint8Array): Uint8Array[];
     private _wipe;
     dispose(): void;
 }

package/dist/serpent/stream-sealer.js

@@ -63,12 +63,12 @@ export class SerpentStreamSealer {
     _cbc;
     _hmac;
     _hkdf;
+    _framed;
     _ivs; // test seam: fixed IVs
     _ivIdx;
     _index;
     _state;
-    // _nonce, _ivs: test seams — inject fixed nonce/IVs for deterministic KAT vectors
-    constructor(key, chunkSize, _nonce, _ivs) {
+    constructor(key, chunkSize, opts, _nonce, _ivs) {
         if (!_serpentReady())
             throw new Error('leviathan-crypto: call init([\'serpent\']) before using SerpentStreamSealer');
         if (!_sha2Ready())
@@ -80,6 +80,7 @@ export class SerpentStreamSealer {
             throw new RangeError(`SerpentStreamSealer chunkSize must be ${CHUNK_MIN}..${CHUNK_MAX} (got ${cs})`);
         this._key = key.slice();
         this._cs = cs;
+        this._framed = opts?.framed ?? false;
         this._nonce = new Uint8Array(16);
         if (_nonce && _nonce.length === 16) {
             this._nonce.set(_nonce);
@@ -138,7 +139,13 @@ export class SerpentStreamSealer {
         const ciphertext = this._cbc.encrypt(encKey, iv, plaintext);
         const tag = this._hmac.hash(macKey, concat(iv, ciphertext));
         this._index++;
-        return concat(concat(iv, ciphertext), tag);
+        const sealed = concat(concat(iv, ciphertext), tag);
+        if (!this._framed)
+            return sealed;
+        const out = new Uint8Array(4 + sealed.length);
+        out.set(u32be(sealed.length), 0);
+        out.set(sealed, 4);
+        return out;
     }
     _wipe() {
         wipe(this._key);
@@ -160,9 +167,13 @@ export class SerpentStreamOpener {
     _cbc;
     _hmac;
     _hkdf;
+    _framed;
+    _buf;
+    _maxFrame;
+    _bufLen;
     _index;
     _dead;
-    constructor(key, header) {
+    constructor(key, header, opts) {
         if (!_serpentReady())
             throw new Error('leviathan-crypto: call init([\'serpent\']) before using SerpentStreamOpener');
         if (!_sha2Ready())
@@ -174,11 +185,21 @@ export class SerpentStreamOpener {
         this._key = key.slice();
         this._nonce = header.slice(0, 16);
         this._cs = (header[16] << 24 | header[17] << 16 | header[18] << 8 | header[19]) >>> 0;
+        if (this._cs < CHUNK_MIN || this._cs > CHUNK_MAX)
+            throw new RangeError(`SerpentStreamOpener: header contains invalid chunkSize ${this._cs} (expected ${CHUNK_MIN}..${CHUNK_MAX})`);
+        this._framed = opts?.framed ?? false;
         this._cbc = new SerpentCbc({ dangerUnauthenticated: true });
         this._hmac = new HMAC_SHA256();
         this._hkdf = new HKDF_SHA256();
         this._index = 0;
         this._dead = false;
+        this._bufLen = 0;
+        if (this._framed) {
+            const cs = this._cs;
+            const maxSealed = 16 + (cs + (16 - (cs % 16))) + 32;
+            this._maxFrame = 4 + maxSealed;
+            this._buf = new Uint8Array(this._maxFrame);
+        }
     }
     get closed() {
         return this._dead;
@@ -186,6 +207,11 @@ export class SerpentStreamOpener {
     open(chunk) {
         if (this._dead)
             throw new Error('SerpentStreamOpener: stream is closed');
+        if (this._framed)
+            throw new Error('SerpentStreamOpener: call feed() on framed openers — open() expects raw sealed chunks without length prefix');
+        return this._openRaw(chunk);
+    }
+    _openRaw(chunk) {
         // Try isLast = true first, then false.
         // Whichever passes auth is the correct interpretation.
         for (const isLast of [true, false]) {
@@ -208,12 +234,104 @@ export class SerpentStreamOpener {
         }
         throw new Error('SerpentStreamOpener: authentication failed');
     }
+    feed(bytes) {
+        if (!this._framed)
+            throw new Error('SerpentStreamOpener: feed() requires { framed: true }');
+        if (this._dead)
+            throw new Error('SerpentStreamOpener: stream is closed');
+        const buf = this._buf;
+        const maxFrame = this._maxFrame;
+        const results = [];
+        let consumed = 0;
+        // ── Phase 1: drain carry-over ─────────────────────────────────────
+        if (this._bufLen > 0) {
+            // Sub-case A: partial prefix — we have < 4 bytes buffered
+            if (this._bufLen < 4) {
+                const need = 4 - this._bufLen;
+                const take = Math.min(need, bytes.length - consumed);
+                buf.set(bytes.subarray(consumed, consumed + take), this._bufLen);
+                this._bufLen += take;
+                consumed += take;
+                if (this._bufLen < 4)
+                    return results;
+            }
+            const sealedLen = (buf[0] << 24 | buf[1] << 16 | buf[2] << 8 | buf[3]) >>> 0;
+            if (sealedLen === 0 || sealedLen > (maxFrame - 4)) {
+                this._wipe();
+                throw new Error('SerpentStreamOpener: invalid sealed chunk length');
+            }
+            const frameLen = 4 + sealedLen;
+            // Sub-case B: partial frame body
+            const haveInBuf = this._bufLen;
+            const needMore = frameLen - haveInBuf;
+            if (needMore > 0) {
+                const take = Math.min(needMore, bytes.length - consumed);
+                buf.set(bytes.subarray(consumed, consumed + take), haveInBuf);
+                this._bufLen += take;
+                consumed += take;
+                if (this._bufLen < frameLen)
+                    return results;
+            }
+            const plaintext = this._openRaw(buf.subarray(4, frameLen));
+            results.push(plaintext);
+            this._bufLen = 0;
+            if (this._dead) {
+                if (consumed < bytes.length) {
+                    this._wipe();
+                    throw new Error('SerpentStreamOpener: unexpected bytes after final chunk');
+                }
+                return results;
+            }
+        }
+        // ── Phase 2: parse complete frames directly from bytes ────────────
+        let pos = consumed;
+        while (true) {
+            if (bytes.length - pos < 4)
+                break;
+            const sealedLen = (bytes[pos] << 24 | bytes[pos + 1] << 16 | bytes[pos + 2] << 8 | bytes[pos + 3]) >>> 0;
+            if (sealedLen === 0 || sealedLen > (maxFrame - 4)) {
+                this._wipe();
+                throw new Error('SerpentStreamOpener: invalid sealed chunk length');
+            }
+            const frameLen = 4 + sealedLen;
+            if (bytes.length - pos < frameLen)
+                break;
+            const plaintext = this._openRaw(bytes.subarray(pos + 4, pos + frameLen));
+            results.push(plaintext);
+            if (this._dead) {
+                const remaining = bytes.length - pos - frameLen;
+                if (remaining > 0) {
+                    this._wipe();
+                    throw new Error('SerpentStreamOpener: unexpected bytes after final chunk');
+                }
+                return results;
+            }
+            pos += frameLen;
+        }
+        // ── Carry over any incomplete trailing bytes into _buf ────────────
+        const leftover = bytes.length - pos;
+        if (leftover > 0) {
+            if (leftover > maxFrame) {
+                this._wipe();
+                throw new Error('SerpentStreamOpener: input exceeds maximum frame size');
+            }
+            buf.set(bytes.subarray(pos), 0);
+            this._bufLen = leftover;
+        }
+        return results;
+    }
     _wipe() {
+        if (this._dead)
+            return;
         wipe(this._key);
         wipe(this._nonce);
         this._cbc.dispose();
         this._hmac.dispose();
         this._hkdf.dispose();
+        if (this._framed) {
+            wipe(this._buf);
+            this._bufLen = 0;
+        }
         this._dead = true;
     }
     dispose() {

package/dist/utils.d.ts

@@ -24,3 +24,8 @@ export declare const xor: (a: Uint8Array, b: Uint8Array) => Uint8Array;
 export declare const concat: (a: Uint8Array, b: Uint8Array) => Uint8Array;
 /** Cryptographically secure random bytes via Web Crypto API. */
 export declare const randomBytes: (n: number) => Uint8Array;
+/**
+ * Detects WASM SIMD support once and caches the result.
+ * Gates CTR/CBC-decrypt dispatch in Serpent and encryptChunk dispatch in ChaCha20.
+ */
+export declare function hasSIMD(): boolean;

package/dist/utils.js

@@ -167,3 +167,28 @@ export const randomBytes = (n) => {
     crypto.getRandomValues(buf);
     return buf;
 };
+// ── SIMD detection ───────────────────────────────────────────────────────────
+let _simd = null;
+/**
+ * Detects WASM SIMD support once and caches the result.
+ * Gates CTR/CBC-decrypt dispatch in Serpent and encryptChunk dispatch in ChaCha20.
+ */
+export function hasSIMD() {
+    if (_simd !== null)
+        return _simd;
+    if (typeof WebAssembly === 'undefined' || typeof WebAssembly.validate !== 'function') {
+        _simd = false;
+        return _simd;
+    }
+    // Minimal WASM module using v128 — validates iff SIMD is supported
+    try {
+        _simd = WebAssembly.validate(new Uint8Array([
+            0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 123,
+            3, 2, 1, 0, 10, 10, 1, 8, 0, 65, 0, 253, 15, 253, 98, 11,
+        ]));
+    }
+    catch {
+        _simd = false;
+    }
+    return _simd;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leviathan-crypto",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "author": "xero (https://x-e.ro)",
   "license": "MIT",
   "description": "Zero-dependency WebAssembly cryptography library for TypeScript: Serpent-256, XChaCha20-Poly1305, SHA-2/3, HMAC, HKDF, and Fortuna CSPRNG, with a strictly typed API built on vector-verified primitives.",

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

@@ -1,20 +0,0 @@
-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

@@ -1,167 +0,0 @@
-//                  ▄▄▄▄▄▄▄▄▄▄
-//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
-//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
-//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
-//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
-//     ████████      ███▀▀     ████▀  █▀ █▀       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;
-}