leviathan-crypto 2.0.1 → 3.0.0

package/dist/ratchet/skipped-key-store.js

@@ -0,0 +1,154 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/ratchet/skipped-key-store.ts
+//
+// SkippedKeyStore, MKSKIPPED cache for a single KDFChain (DR spec §3.2/§3.5).
+// Manages out-of-order and skipped message key storage with transactional
+// resolve via ResolveHandle. Split budgets: maxCacheSize bounds memory;
+// maxSkipPerResolve bounds per-message HKDF work (DoS mitigation).
+import { wipe } from '../utils.js';
+// Best-effort wipe if a handle is GC'd without settling. GC is non-deterministic
+// so this is a safety net only; the contract remains that callers MUST settle.
+const finalizer = new FinalizationRegistry(key => wipe(key));
+export class SkippedKeyStore {
+    _store;
+    _maxCacheSize;
+    _maxSkipPerResolve;
+    constructor(opts) {
+        const cache = opts?.maxCacheSize ?? opts?.ceiling ?? 100;
+        const skip = opts?.maxSkipPerResolve ?? opts?.ceiling ?? 50;
+        if (!Number.isSafeInteger(cache) || cache < 1)
+            throw new RangeError('SkippedKeyStore: maxCacheSize must be a safe integer >= 1');
+        if (!Number.isSafeInteger(skip) || skip < 1)
+            throw new RangeError('SkippedKeyStore: maxSkipPerResolve must be a safe integer >= 1');
+        if (skip > cache)
+            throw new RangeError(`SkippedKeyStore: maxSkipPerResolve (${skip}) must not exceed maxCacheSize (${cache})`);
+        this._store = new Map();
+        this._maxCacheSize = cache;
+        this._maxSkipPerResolve = skip;
+    }
+    // O(1) eviction, Map iteration is insertion order, and keys are inserted
+    // in strictly increasing counter order, so the first key yielded IS the
+    // oldest (lowest counter).
+    _evictOldest() {
+        const oldest = this._store.keys().next().value;
+        if (oldest === undefined)
+            return;
+        const val = this._store.get(oldest);
+        if (val !== undefined)
+            wipe(val);
+        this._store.delete(oldest);
+    }
+    // Resolve a message key for the given counter. Returns a ResolveHandle the
+    // caller settles via commit() (success, key wiped) or rollback()
+    // (failure, key returned to the store so a later legitimate message at
+    // the same counter can still decrypt).
+    //
+    // Three paths based on counter vs chain.n:
+    //   in-order   (=== n+1): step chain, wrap final key
+    //   skip-ahead (>   n+1): step chain storing intermediates, wrap final
+    //   past       (<=   n):  look up in map and delete; throw if absent
+    resolve(chain, counter) {
+        if (!Number.isSafeInteger(counter) || counter < 1)
+            throw new RangeError(`SkippedKeyStore: invalid counter ${counter}`);
+        let key;
+        if (counter === chain.n + 1) {
+            key = chain.step();
+        }
+        else if (counter > chain.n + 1) {
+            const skipNeeded = counter - chain.n - 1;
+            if (skipNeeded > this._maxSkipPerResolve)
+                throw new RangeError(`SkippedKeyStore: counter ${counter} requires ${skipNeeded} skip derivations, `
+                    + `exceeds maxSkipPerResolve=${this._maxSkipPerResolve}`);
+            while (chain.n < counter - 1) {
+                const k = chain.step();
+                if (this._store.size >= this._maxCacheSize)
+                    this._evictOldest();
+                this._store.set(chain.n, k);
+            }
+            key = chain.step();
+        }
+        else {
+            const stored = this._store.get(counter);
+            if (stored === undefined)
+                throw new Error(`SkippedKeyStore: unrecoverable. key for counter ${counter} not found`);
+            this._store.delete(counter);
+            key = stored;
+        }
+        return this._makeHandle(key, counter);
+    }
+    _makeHandle(key, counter) {
+        let settled = false;
+        const handle = {
+            get key() {
+                if (settled)
+                    throw new Error('SkippedKeyStore: handle already settled');
+                return key;
+            },
+            commit: () => {
+                if (settled)
+                    throw new Error('SkippedKeyStore: handle already settled');
+                settled = true;
+                finalizer.unregister(handle);
+                wipe(key);
+            },
+            rollback: () => {
+                if (settled)
+                    throw new Error('SkippedKeyStore: handle already settled');
+                settled = true;
+                finalizer.unregister(handle);
+                if (this._store.size >= this._maxCacheSize)
+                    this._evictOldest();
+                this._store.set(counter, key);
+            },
+        };
+        finalizer.register(handle, key, handle);
+        return handle;
+    }
+    // Step chain from its current position up to and including pn, storing each
+    // key. Used at epoch transitions so late-arriving old-epoch messages can
+    // still be decrypted. No-op when pn <= chain.n. Enforces maxSkipPerResolve
+    // so a malicious header can't force unbounded HKDF work.
+    advanceToBoundary(chain, pn) {
+        if (!Number.isSafeInteger(pn) || pn < 0)
+            throw new RangeError(`SkippedKeyStore: invalid pn ${pn}`);
+        const skipNeeded = pn - chain.n;
+        if (skipNeeded > this._maxSkipPerResolve)
+            throw new RangeError(`SkippedKeyStore: pn=${pn} requires ${skipNeeded} skip derivations, `
+                + `exceeds maxSkipPerResolve=${this._maxSkipPerResolve}`);
+        while (chain.n < pn) {
+            const key = chain.step();
+            if (this._store.size >= this._maxCacheSize)
+                this._evictOldest();
+            this._store.set(chain.n, key);
+        }
+    }
+    get size() {
+        return this._store.size;
+    }
+    // Wipe all stored key buffers and clear the map. Idempotent.
+    wipeAll() {
+        for (const v of this._store.values())
+            wipe(v);
+        this._store.clear();
+    }
+}

package/dist/ratchet/types.d.ts

@@ -0,0 +1,36 @@
+export type { MlKemLike } from '../mlkem/suite.js';
+export interface RatchetInitResult {
+    readonly nextRootKey: Uint8Array;
+    readonly sendChainKey: Uint8Array;
+    readonly recvChainKey: Uint8Array;
+}
+export interface KemEncapResult {
+    readonly nextRootKey: Uint8Array;
+    readonly sendChainKey: Uint8Array;
+    readonly recvChainKey: Uint8Array;
+    readonly kemCt: Uint8Array;
+}
+export interface KemDecapResult {
+    readonly nextRootKey: Uint8Array;
+    readonly sendChainKey: Uint8Array;
+    readonly recvChainKey: Uint8Array;
+}
+export interface RatchetMessageHeader {
+    readonly epoch: number;
+    readonly counter: number;
+    readonly pn?: number;
+    readonly kemCt?: Uint8Array;
+}
+export interface ResolveHandle {
+    readonly key: Uint8Array;
+    commit(): void;
+    rollback(): void;
+}
+export interface SkippedKeyStoreOpts {
+    /** Max keys held in cache. Default 100. Must be >= maxSkipPerResolve. */
+    maxCacheSize?: number;
+    /** Max skip-ahead derivations per resolve() call. Default 50. */
+    maxSkipPerResolve?: number;
+    /** @deprecated use maxCacheSize + maxSkipPerResolve. If provided, sets both. */
+    ceiling?: number;
+}

package/dist/ratchet/types.js

@@ -0,0 +1,26 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/ratchet/types.ts
+//
+// Shared types for the ratchet KDF construction.
+// Re-exports MlKemLike so consumers import from one place.
+export {};

package/dist/serpent/cipher-suite.d.ts

@@ -1,4 +1,14 @@
 import type { CipherSuite } from '../stream/types.js';
+/**
+ * `CipherSuite` implementation for the stream construction using Serpent-256.
+ *
+ * Each chunk is encrypted with Serpent-CBC (PKCS7) and authenticated with
+ * HMAC-SHA-256. Keys are derived via 3-way HKDF-SHA-256 (enc / mac / iv keys).
+ * Verify-then-decrypt ordering prevents padding oracle attacks (Vaudenay 2002).
+ *
+ * Pass to `SealStream` / `OpenStream` / `SealStreamPool` instead of constructing
+ * this object directly. Use `SerpentCipher.keygen()` to generate a 32-byte key.
+ */
 export declare const SerpentCipher: CipherSuite & {
     keygen(): Uint8Array;
 };

package/dist/serpent/cipher-suite.js

@@ -21,102 +21,190 @@
 //
 // src/ts/serpent/cipher-suite.ts
 //
-// SerpentCipher — CipherSuite implementation for the STREAM construction.
+// SerpentCipher, CipherSuite implementation for the STREAM construction.
 // 3-key HKDF derivation, HMAC-derived CBC IV, Serpent-CBC + HMAC-SHA-256.
 // Verify-then-decrypt ordering prevents padding oracle attacks (Vaudenay 2002).
-import { SerpentCbc } from './serpent-cbc.js';
-import { HKDF_SHA256, HMAC_SHA256 } from '../sha2/index.js';
+//
+// Salamander immunity: HMAC-SHA-256 is key-committing under SHA-256 collision
+// resistance, so Serpent suites need no separate commitment in the preamble
+// (commitmentSize: 0). Two distinct master keys cannot produce a tag that
+// validates under both for the same chunk.
+import { HKDF_SHA256 } from '../sha2/index.js';
 import { constantTimeEqual, wipe, concat, randomBytes } from '../utils.js';
 import { AuthenticationError } from '../errors.js';
-import { getInstance } from '../init.js';
-const INFO = new TextEncoder().encode('serpent-sealstream-v2');
+import { getInstance, _assertNotOwned } from '../init.js';
+import { hmacSha256, cbcEncryptChunk, cbcDecryptChunk, } from './shared-ops.js';
+import { WORKER_SOURCE } from '../embedded/serpent-pool-worker.js';
+const INFO = new TextEncoder().encode('serpent-sealstream-v3');
+/**
+ * `CipherSuite` implementation for the stream construction using Serpent-256.
+ *
+ * Each chunk is encrypted with Serpent-CBC (PKCS7) and authenticated with
+ * HMAC-SHA-256. Keys are derived via 3-way HKDF-SHA-256 (enc / mac / iv keys).
+ * Verify-then-decrypt ordering prevents padding oracle attacks (Vaudenay 2002).
+ *
+ * Pass to `SealStream` / `OpenStream` / `SealStreamPool` instead of constructing
+ * this object directly. Use `SerpentCipher.keygen()` to generate a 32-byte key.
+ */
 export const SerpentCipher = {
     formatEnum: 0x02,
     formatName: 'serpent',
-    hkdfInfo: 'serpent-sealstream-v2',
+    hkdfInfo: 'serpent-sealstream-v3',
     keySize: 32,
     kemCtSize: 0,
+    commitmentSize: 0,
     tagSize: 32,
     padded: true,
     wasmChunkSize: 65552, // src/asm/serpent/buffers.ts CHUNK_SIZE (65536 + 16 PKCS7 max overhead)
     wasmModules: ['serpent', 'sha2'],
+    /** Generate a random 32-byte master key suitable for use with `SerpentCipher`. @returns 32 cryptographically random bytes */
     keygen() {
         return randomBytes(32);
     },
-    deriveKeys(masterKey, nonce, _kemCt) {
+    /**
+     * Derive 96 bytes of keying material from `masterKey` and `nonce` via HKDF-SHA-256.
+     * Layout: bytes[0:32]=enc_key, bytes[32:64]=mac_key, bytes[64:96]=iv_key.
+     * @param masterKey  32-byte master key
+     * @param nonce      Stream nonce (16 bytes minimum)
+     * @returns          `DerivedKeys` holding the 96-byte material
+     */
+    deriveKeys(masterKey, nonce, _kemCt, _header) {
         const hkdf = new HKDF_SHA256();
-        const derived = hkdf.derive(masterKey, nonce, INFO, 96);
-        hkdf.dispose();
+        let derived;
+        try {
+            derived = hkdf.derive(masterKey, nonce, INFO, 96);
+        }
+        finally {
+            hkdf.dispose();
+        }
         // bytes[0:32]=enc_key, bytes[32:64]=mac_key, bytes[64:96]=iv_key
         return { bytes: derived };
     },
+    /**
+     * Encrypt and authenticate one stream chunk.
+     * IV is derived from `counterNonce` via HMAC-SHA-256 with the iv_key.
+     * Output: ciphertext (PKCS7-padded) || 32-byte HMAC tag.
+     * @param keys         Derived keys from `deriveKeys`
+     * @param counterNonce Per-chunk nonce (unique per chunk in the stream)
+     * @param chunk        Plaintext chunk
+     * @param aad          Optional additional authenticated data
+     * @returns            Authenticated ciphertext
+     */
     sealChunk(keys, counterNonce, chunk, aad) {
+        // shared-ops functions operate directly on the module exports without
+        // going through `_acquireModule`. Assert no stateful instance owns
+        // either module before touching WASM memory.
+        _assertNotOwned('serpent');
+        _assertNotOwned('sha2');
+        const sx = getInstance('sha2').exports;
+        const kx = getInstance('serpent').exports;
         const encKey = keys.bytes.subarray(0, 32);
         const macKey = keys.bytes.subarray(32, 64);
         const ivKey = keys.bytes.subarray(64, 96);
         const aadBytes = aad ?? new Uint8Array(0);
-        const hmac = new HMAC_SHA256();
-        // Derive IV from counter nonce
-        const ivFull = hmac.hash(ivKey, counterNonce);
-        const iv = ivFull.slice(0, 16);
-        wipe(ivFull);
-        // Encrypt: Serpent-CBC with PKCS7 padding
-        const cbc = new SerpentCbc({ dangerUnauthenticated: true });
-        const ct = cbc.encrypt(encKey, iv, chunk);
-        cbc.dispose();
-        // Compute HMAC tag: HMAC-SHA-256(mac_key, counterNonce || u32be(aad_len) || aad || ct)
-        const aadLenBuf = new Uint8Array(4);
-        new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
-        const tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
-        const tag = hmac.hash(macKey, tagInput);
-        hmac.dispose();
-        wipe(iv);
-        wipe(tagInput);
-        // Output: ct || tag (IV is NOT included)
-        return concat(ct, tag);
+        let iv;
+        let tagInput;
+        try {
+            // Derive IV from counter nonce
+            const ivFull = hmacSha256(sx, ivKey, counterNonce);
+            iv = ivFull.slice(0, 16);
+            wipe(ivFull);
+            // Encrypt: Serpent-CBC with PKCS7 padding
+            const ct = cbcEncryptChunk(kx, encKey, iv, chunk);
+            // Compute HMAC tag: HMAC-SHA-256(mac_key, counterNonce || u32be(aad_len) || aad || ct)
+            const aadLenBuf = new Uint8Array(4);
+            new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
+            tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
+            const tag = hmacSha256(sx, macKey, tagInput);
+            // Output: ct || tag (IV is NOT included)
+            return concat(ct, tag);
+        }
+        finally {
+            if (iv)
+                wipe(iv);
+            if (tagInput)
+                wipe(tagInput);
+            // No hmac/cbc instance to dispose, shared-ops functions are instance-free.
+        }
     },
+    /**
+     * Verify and decrypt one stream chunk. HMAC is verified before decryption
+     * to prevent padding oracle attacks (Vaudenay 2002). Throws
+     * `AuthenticationError` on tag mismatch.
+     * @param keys         Derived keys from `deriveKeys`
+     * @param counterNonce Per-chunk nonce, must match the value used by `sealChunk`
+     * @param chunk        Ciphertext || 32-byte HMAC tag
+     * @param aad          Optional additional authenticated data
+     * @returns            Plaintext with PKCS7 padding removed
+     */
     openChunk(keys, counterNonce, chunk, aad) {
         if (chunk.length < 32)
             throw new RangeError(`chunk too short for 32-byte tag (got ${chunk.length})`);
+        _assertNotOwned('serpent');
+        _assertNotOwned('sha2');
+        const sx = getInstance('sha2').exports;
+        const kx = getInstance('serpent').exports;
         const encKey = keys.bytes.subarray(0, 32);
         const macKey = keys.bytes.subarray(32, 64);
         const ivKey = keys.bytes.subarray(64, 96);
         const aadBytes = aad ?? new Uint8Array(0);
         const ct = chunk.subarray(0, chunk.length - 32);
         const receivedTag = chunk.subarray(chunk.length - 32);
-        const hmac = new HMAC_SHA256();
-        // Derive IV from counter nonce
-        const ivFull = hmac.hash(ivKey, counterNonce);
-        const iv = ivFull.slice(0, 16);
-        wipe(ivFull);
-        // Compute expected tag: HMAC-SHA-256(mac_key, counterNonce || u32be(aad_len) || aad || ct)
-        const aadLenBuf = new Uint8Array(4);
-        new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
-        const tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
-        const expectedTag = hmac.hash(macKey, tagInput);
-        hmac.dispose();
-        // CRITICAL: Verify HMAC BEFORE decrypting.
-        // Evaluating PKCS7 padding on unauthenticated data is a padding oracle (Vaudenay 2002).
-        if (!constantTimeEqual(expectedTag, receivedTag)) {
-            wipe(iv);
-            wipe(tagInput);
-            wipe(expectedTag);
-            getInstance('serpent').exports.wipeBuffers();
-            throw new AuthenticationError('serpent');
+        let iv;
+        let tagInput;
+        let expectedTag;
+        try {
+            // Derive IV from counter nonce
+            const ivFull = hmacSha256(sx, ivKey, counterNonce);
+            iv = ivFull.slice(0, 16);
+            wipe(ivFull);
+            // Compute expected tag: HMAC-SHA-256(mac_key, counterNonce || u32be(aad_len) || aad || ct)
+            const aadLenBuf = new Uint8Array(4);
+            new DataView(aadLenBuf.buffer).setUint32(0, aadBytes.length, false);
+            tagInput = concat(counterNonce, aadLenBuf, aadBytes, ct);
+            expectedTag = hmacSha256(sx, macKey, tagInput);
+            // CRITICAL: Verify HMAC BEFORE decrypting.
+            // Evaluating PKCS7 padding on unauthenticated data is a padding oracle (Vaudenay 2002).
+            // Belt-and-suspenders: explicit wipes here cover the auth-fail path before
+            // throwing; the finally block below covers every other path.
+            if (!constantTimeEqual(expectedTag, receivedTag)) {
+                wipe(iv);
+                wipe(tagInput);
+                wipe(expectedTag);
+                getInstance('serpent').exports.wipeBuffers();
+                throw new AuthenticationError('serpent');
+            }
+            // ONLY decrypt after authentication succeeds
+            return cbcDecryptChunk(kx, encKey, iv, ct);
+        }
+        finally {
+            if (iv)
+                wipe(iv);
+            if (tagInput)
+                wipe(tagInput);
+            if (expectedTag)
+                wipe(expectedTag);
         }
-        wipe(tagInput);
-        wipe(expectedTag);
-        // ONLY decrypt after authentication succeeds
-        const cbc = new SerpentCbc({ dangerUnauthenticated: true });
-        const plaintext = cbc.decrypt(encKey, iv, ct);
-        cbc.dispose();
-        wipe(iv);
-        return plaintext;
     },
+    /**
+     * Zero all derived key material in `keys`. Called by the stream layer on
+     * teardown and after auth failure.
+     * @param keys  Derived keys to wipe
+     */
     wipeKeys(keys) {
         wipe(keys.bytes);
     },
+    /**
+     * Spawn a Serpent pool worker from the embedded IIFE bundle.
+     * The worker holds its own serpent + sha2 WASM instances.
+     * @returns  Newly constructed `Worker` instance
+     */
     createPoolWorker() {
-        return new Worker(new URL('./pool-worker.js', import.meta.url), { type: 'module' });
+        // See docs/architecture.md#pool-worker-spawn-pattern.
+        const blob = new Blob([WORKER_SOURCE], { type: 'application/javascript' });
+        const url = URL.createObjectURL(blob);
+        const w = new Worker(url);
+        setTimeout(() => URL.revokeObjectURL(url), 0);
+        return w;
     },
 };

package/dist/serpent/generator.d.ts

@@ -0,0 +1,12 @@
+import type { Generator } from '../types.js';
+/**
+ * Serpent-256 ECB counter-mode PRF for Fortuna's generator slot.
+ *
+ * Each 16-byte counter value is encrypted as a plaintext block to produce
+ * one block of pseudorandom output. Practical Cryptography (Ferguson &
+ * Schneier, 2003) §9.4.
+ *
+ * Pass to `Fortuna.create({ generator: SerpentGenerator, ... })`, do not
+ * call `generate()` directly outside of Fortuna.
+ */
+export declare const SerpentGenerator: Generator;

package/dist/serpent/generator.js

@@ -0,0 +1,97 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/generator.ts
+//
+// Practical Cryptography (Ferguson & Schneier, 2003) §9.4, generator
+// Serpent-256 ECB counter-mode PRF for Fortuna's generator slot.
+import { _assertNotOwned, getInstance } from '../init.js';
+import { wipe } from '../utils.js';
+/**
+ * Serpent-256 ECB counter-mode PRF for Fortuna's generator slot.
+ *
+ * Each 16-byte counter value is encrypted as a plaintext block to produce
+ * one block of pseudorandom output. Practical Cryptography (Ferguson &
+ * Schneier, 2003) §9.4.
+ *
+ * Pass to `Fortuna.create({ generator: SerpentGenerator, ... })`, do not
+ * call `generate()` directly outside of Fortuna.
+ */
+export const SerpentGenerator = {
+    keySize: 32,
+    blockSize: 16,
+    counterSize: 16,
+    wasmModules: ['serpent'],
+    /**
+     * Generate `n` pseudorandom bytes by encrypting successive 16-byte counter
+     * values in ECB mode. The counter is incremented as a 128-bit little-endian
+     * integer after each block.
+     * @param key      32-byte Serpent-256 key
+     * @param counter  16-byte initial counter value (little-endian)
+     * @param n        Number of bytes to generate (0 ≤ n ≤ 2^30)
+     * @returns        `n` pseudorandom bytes
+     */
+    generate(key, counter, n) {
+        _assertNotOwned('serpent');
+        if (key.length !== 32)
+            throw new RangeError(`SerpentGenerator: key must be 32 bytes (got ${key.length})`);
+        if (counter.length !== 16)
+            throw new RangeError(`SerpentGenerator: counter must be 16 bytes (got ${counter.length})`);
+        if (!Number.isSafeInteger(n) || n < 0 || n > 2 ** 30)
+            throw new RangeError(`SerpentGenerator: n must be a non-negative safe integer <= 2^30 (got ${n})`);
+        const x = getInstance('serpent').exports;
+        const mem = new Uint8Array(x.memory.buffer);
+        const c = counter.slice();
+        try {
+            mem.set(key, x.getKeyOffset());
+            if (x.loadKey(32) !== 0)
+                throw new Error('SerpentGenerator: loadKey failed');
+            const blocks = Math.ceil(n / 16);
+            const output = new Uint8Array(n);
+            const ptOff = x.getBlockPtOffset();
+            const ctOff = x.getBlockCtOffset();
+            for (let i = 0; i < blocks; i++) {
+                mem.set(c, ptOff);
+                x.encryptBlock();
+                // Last-block trim: copy only what the caller asked for. The
+                // unused tail stays in WASM memory (wiped in finally) instead
+                // of landing on the JS heap where callers could reach it via
+                // `result.buffer`. Mirrors ChaCha20Generator's exact-size output.
+                const offset = i * 16;
+                const writeLen = Math.min(16, n - offset);
+                output.set(mem.subarray(ctOff, ctOff + writeLen), offset);
+                // Increment c as a 16-byte little-endian integer
+                for (let j = 0; j < 16; j++) {
+                    if (++c[j] !== 0)
+                        break;
+                }
+            }
+            return output;
+        }
+        finally {
+            // Wipe WASM key/key-schedule/last-block scratch and the JS-heap
+            // counter copy so secret-derived state does not outlive this call
+            // in either the WASM linear memory or the JS heap.
+            x.wipeBuffers();
+            wipe(c);
+        }
+    },
+};