leviathan-crypto 2.1.0 → 3.0.0

package/dist/aes/aes-gcm.js

@@ -0,0 +1,226 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/aes/aes-gcm.ts
+//
+// AESGCM, AES-128/192/256 in GCM mode (NIST SP 800-38D §7), atomic
+// authenticated AEAD. Tag length is fixed at 128 bits.
+import { getInstance, _acquireModule, _releaseModule } from '../init.js';
+import { constantTimeEqual } from '../utils.js';
+// SP 800-38D §5.2.1.1: max plaintext = 2^39 - 256 bits = 2^36 - 32 bytes.
+const MAX_PT_BYTES = 0x1000000000 - 32;
+// AAD_BUFFER is 64 KiB.
+const MAX_AAD_BYTES = 65536;
+// IV reuses CHUNK_PT_BUFFER scratch, 64 KiB cap.
+const MAX_IV_BYTES = 65536;
+// Per-call chunk size; seal/open iterate across this for larger inputs.
+const PT_CHUNK_LIMIT = 65536;
+const AUTH_FAILED = 'authentication failed';
+/** Returns the raw AES WASM export object. @internal */
+function getExports() {
+    return getInstance('aes').exports;
+}
+// ── AESGCM ──────────────────────────────────────────────────────────────────
+/**
+ * AES-128/192/256 in GCM mode (SP 800-38D §7). Authenticated AEAD with
+ * 128-bit tag. Tag length is fixed; shorter tags (32/64/96/104/112/120)
+ * are out of scope for this version.
+ *
+ * `seal(key, iv, aad, pt)` returns `ciphertext || tag` (length pt.length + 16).
+ * `open(key, iv, aad, sealed)` verifies the tag and returns the plaintext;
+ * throws `RangeError('authentication failed')` on any verification failure
+ * (the same generic error as a tag mismatch, no detail leak).
+ *
+ * Holds exclusive access to the `aes` WASM module from construction until
+ * `dispose()`. Constructing a second AES-using class while this instance is
+ * live throws. Always dispose when done so key material is wiped.
+ */
+export class AESGCM {
+    x;
+    _tok;
+    constructor() {
+        this.x = getExports();
+        this._tok = _acquireModule('aes');
+    }
+    /** View over WASM linear memory. Rebind every access, memory can be detached. @internal */
+    get mem() {
+        return new Uint8Array(this.x.memory.buffer);
+    }
+    /**
+     * Authenticated encryption.
+     *
+     * @param key  16, 24, or 32 bytes (AES-128 / 192 / 256)
+     * @param iv   1+ bytes; 12-byte (96-bit) IV is the recommended fast path
+     * @param aad  any length up to 64 KiB; may be empty
+     * @param pt   any length up to 2^36 - 32 bytes; may be empty
+     * @returns    ciphertext concatenated with the 128-bit tag
+     *             (length = pt.length + 16)
+     *
+     * @throws RangeError if key/iv/aad/pt lengths violate the spec or the
+     *         buffer-bounded API.
+     */
+    seal(key, iv, aad, pt) {
+        if (this._tok === undefined)
+            throw new Error('AESGCM: instance has been disposed');
+        this._validateInputs(key, iv, aad, pt.length);
+        try {
+            this._loadKey(key);
+            this._writeIv(iv);
+            this._writeAad(aad);
+            const startRc = this.x.gcmStart(iv.length, aad.length);
+            if (startRc !== 0)
+                throw new RangeError('invalid GCM input');
+            const output = new Uint8Array(pt.length + 16);
+            const ptOff = this.x.getChunkPtOffset();
+            const ctOff = this.x.getChunkCtOffset();
+            const tagOff = this.x.getTagOffset();
+            for (let off = 0; off < pt.length; off += PT_CHUNK_LIMIT) {
+                const chunkLen = Math.min(PT_CHUNK_LIMIT, pt.length - off);
+                this.mem.set(pt.subarray(off, off + chunkLen), ptOff);
+                const rc = this.x.gcmEncryptChunk(ptOff, ctOff, chunkLen);
+                if (rc !== 0)
+                    throw new RangeError('GCM counter overflow');
+                output.set(this.mem.subarray(ctOff, ctOff + chunkLen), off);
+            }
+            this.x.gcmFinalize();
+            output.set(this.mem.subarray(tagOff, tagOff + 16), pt.length);
+            return output;
+        }
+        finally {
+            this.x.wipeBuffers();
+        }
+    }
+    /**
+     * Authenticated decryption.
+     *
+     * Performs verify-before-decrypt (SP 800-38D §7.2 permits the tag check
+     * to precede plaintext computation): the entire ciphertext is absorbed
+     * into GHASH, the tag is computed and constant-time-compared with the
+     * received tag, and only then is the ciphertext decrypted to plaintext.
+     * This avoids leaking decrypted bytes to higher layers when the tag
+     * fails to verify.
+     *
+     * @param key     same constraints as `seal`
+     * @param iv      same iv used during the matching `seal` call
+     * @param aad     same aad used during the matching `seal` call
+     * @param sealed  output of a previous `seal` call (ciphertext || tag)
+     * @returns       plaintext (length = sealed.length - 16)
+     *
+     * @throws RangeError('authentication failed') if the tag fails to
+     *         verify, or if the sealed input is too short, or any input
+     *         length violates the spec. The same generic error covers all
+     *         failure modes, no detail is leaked about which check failed.
+     */
+    open(key, iv, aad, sealed) {
+        if (this._tok === undefined)
+            throw new Error('AESGCM: instance has been disposed');
+        if (sealed.length < 16)
+            throw new RangeError(AUTH_FAILED);
+        const ctLen = sealed.length - 16;
+        // Throw the generic auth-failed error rather than 'invalid input' on
+        // length validation, to keep failure modes indistinguishable.
+        try {
+            this._validateInputs(key, iv, aad, ctLen);
+        }
+        catch {
+            throw new RangeError(AUTH_FAILED);
+        }
+        try {
+            this._loadKey(key);
+            this._writeIv(iv);
+            this._writeAad(aad);
+            const startRc = this.x.gcmStart(iv.length, aad.length);
+            if (startRc !== 0)
+                throw new RangeError(AUTH_FAILED);
+            const ptOff = this.x.getChunkPtOffset();
+            const ctOff = this.x.getChunkCtOffset();
+            // Pass 1: absorb every CT chunk into GHASH (no decryption yet).
+            for (let off = 0; off < ctLen; off += PT_CHUNK_LIMIT) {
+                const chunkLen = Math.min(PT_CHUNK_LIMIT, ctLen - off);
+                this.mem.set(sealed.subarray(off, off + chunkLen), ctOff);
+                const rc = this.x.gcmAbsorbCtChunk(ctOff, chunkLen);
+                if (rc !== 0)
+                    throw new RangeError(AUTH_FAILED);
+            }
+            this.x.gcmFinalize();
+            const tagOff = this.x.getTagOffset();
+            const expectedTag = this.mem.slice(tagOff, tagOff + 16);
+            const providedTag = sealed.slice(ctLen, ctLen + 16);
+            if (!constantTimeEqual(expectedTag, providedTag))
+                throw new RangeError(AUTH_FAILED);
+            // Pass 2: re-init counter, GCTR-decrypt every CT chunk → output.
+            this.x.gcmResetCtrToJ0Plus1();
+            const output = new Uint8Array(ctLen);
+            for (let off = 0; off < ctLen; off += PT_CHUNK_LIMIT) {
+                const chunkLen = Math.min(PT_CHUNK_LIMIT, ctLen - off);
+                this.mem.set(sealed.subarray(off, off + chunkLen), ctOff);
+                const rc = this.x.gcmDecryptChunk(ctOff, ptOff, chunkLen);
+                if (rc !== 0)
+                    throw new RangeError(AUTH_FAILED);
+                output.set(this.mem.subarray(ptOff, ptOff + chunkLen), off);
+            }
+            return output;
+        }
+        finally {
+            this.x.wipeBuffers();
+        }
+    }
+    /** Wipe WASM state and release exclusive module access. Idempotent. */
+    dispose() {
+        if (this._tok === undefined)
+            return;
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('aes', this._tok);
+            this._tok = undefined;
+        }
+    }
+    // ── Internal helpers ───────────────────────────────────────────────────
+    _validateInputs(key, iv, aad, dataLen) {
+        if (key.length !== 16 && key.length !== 24 && key.length !== 32)
+            throw new RangeError(`AES key must be 16, 24, or 32 bytes (got ${key.length})`);
+        if (iv.length < 1)
+            throw new RangeError('GCM IV must be ≥ 1 byte');
+        if (iv.length > MAX_IV_BYTES)
+            throw new RangeError(`GCM IV must be ≤ ${MAX_IV_BYTES} bytes (got ${iv.length})`);
+        if (aad.length > MAX_AAD_BYTES)
+            throw new RangeError(`GCM AAD must be ≤ ${MAX_AAD_BYTES} bytes (got ${aad.length})`);
+        if (dataLen > MAX_PT_BYTES)
+            throw new RangeError(`GCM plaintext must be ≤ 2^36 - 32 bytes (got ${dataLen})`);
+    }
+    _loadKey(key) {
+        this.mem.set(key, this.x.getKeyOffset());
+        if (this.x.loadKey(key.length) !== 0) {
+            this.x.wipeBuffers();
+            throw new Error('AESGCM: loadKey failed');
+        }
+    }
+    _writeIv(iv) {
+        this.mem.set(iv, this.x.getChunkPtOffset());
+    }
+    _writeAad(aad) {
+        if (aad.length === 0)
+            return;
+        this.mem.set(aad, this.x.getAadOffset());
+    }
+}

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

@@ -0,0 +1,21 @@
+import type { CipherSuite } from '../stream/types.js';
+/**
+ * `CipherSuite` implementation for the stream construction using
+ * AES-256-GCM-SIV (RFC 8452).
+ *
+ * Each chunk is encrypted with AES-256-GCM-SIV using a per-stream
+ * AES key derived via HKDF-SHA-256. Unlike `XChaCha20Cipher` there is
+ * no intermediate subkey derivation step, AES-GCM-SIV uses a 12-byte
+ * nonce natively, so the 32 bytes from HKDF feed straight into the
+ * cipher.
+ *
+ * Pass to `Seal` / `SealStream` / `OpenStream` / `SealStreamPool`
+ * instead of constructing this object directly. Use
+ * `AESGCMSIVCipher.keygen()` to generate a 32-byte master key.
+ *
+ * The cipher suite is AES-256 only; the standalone `AESGCMSIV` primitive
+ * class continues to support both AES-128 and AES-256 (RFC 8452 §6).
+ */
+export declare const AESGCMSIVCipher: CipherSuite & {
+    keygen(): Uint8Array;
+};

package/dist/aes/cipher-suite.js

@@ -0,0 +1,179 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/aes/cipher-suite.ts
+//
+// AESGCMSIVCipher, CipherSuite implementation for the STREAM construction.
+// HKDF-SHA-256 key derivation → AES-256-GCM-SIV per chunk. Mirrors the
+// XChaCha20Cipher HtE explicit-commitment construction byte-for-byte
+// modulo the cipher backend, since AES-GCM-SIV's POLYVAL-based MAC is
+// not key-committing on its own.
+import { getInstance, _assertNotOwned } from '../init.js';
+import { HKDF_SHA256 } from '../sha2/index.js';
+import { sivAeadEncrypt, sivAeadDecrypt } from './ops.js';
+import { wipe, randomBytes, concat } from '../utils.js';
+import { HEADER_SIZE } from '../stream/constants.js';
+import { WORKER_SOURCE } from '../embedded/aes-pool-worker.js';
+const INFO = new TextEncoder().encode('aes-gcm-siv-sealstream-v3');
+/** Returns the raw aes WASM export object. @internal */
+function getExports() {
+    return getInstance('aes').exports;
+}
+/**
+ * `CipherSuite` implementation for the stream construction using
+ * AES-256-GCM-SIV (RFC 8452).
+ *
+ * Each chunk is encrypted with AES-256-GCM-SIV using a per-stream
+ * AES key derived via HKDF-SHA-256. Unlike `XChaCha20Cipher` there is
+ * no intermediate subkey derivation step, AES-GCM-SIV uses a 12-byte
+ * nonce natively, so the 32 bytes from HKDF feed straight into the
+ * cipher.
+ *
+ * Pass to `Seal` / `SealStream` / `OpenStream` / `SealStreamPool`
+ * instead of constructing this object directly. Use
+ * `AESGCMSIVCipher.keygen()` to generate a 32-byte master key.
+ *
+ * The cipher suite is AES-256 only; the standalone `AESGCMSIV` primitive
+ * class continues to support both AES-128 and AES-256 (RFC 8452 §6).
+ */
+export const AESGCMSIVCipher = {
+    formatEnum: 0x04,
+    formatName: 'aes-gcm-siv',
+    hkdfInfo: 'aes-gcm-siv-sealstream-v3',
+    keySize: 32,
+    kemCtSize: 0,
+    commitmentSize: 32,
+    tagSize: 16,
+    padded: false,
+    wasmChunkSize: 65536, // src/asm/aes/buffers.ts AES_CHUNK_SIZE
+    wasmModules: ['aes'],
+    /** Generate a random 32-byte master key suitable for use with `AESGCMSIVCipher`. @returns 32 cryptographically random bytes */
+    keygen() {
+        return randomBytes(32);
+    },
+    /**
+     * Derive a 32-byte AES-256-GCM-SIV key and a 32-byte key commitment
+     * from `masterKey` and `nonce` via HKDF-SHA-256. The full 20-byte
+     * preamble header is appended to the HKDF info string, binding
+     * `formatEnum`, framed flag, nonce, and chunkSize into the derived
+     * material, header tampering causes derived keys to differ and AEAD
+     * fails on the first chunk.
+     *
+     * The 64-byte HKDF output is split: bytes 0..32 are the per-stream
+     * AES-GCM-SIV key, bytes 32..64 are the key commitment that ends up
+     * in the preamble. Verifying the commitment before any chunk is
+     * processed closes the Invisible Salamanders attack surface,
+     * AES-GCM-SIV's POLYVAL-based MAC is not key-committing on its own,
+     * so without this an adversary with control over two master keys
+     * could craft a single ciphertext + tag that decrypts validly under
+     * both.
+     *
+     * Unlike `XChaCha20Cipher` there is no subkey-derivation step:
+     * AES-GCM-SIV's nonce is 12 bytes, used directly per chunk; there
+     * is no HChaCha20 analog.
+     *
+     * @param masterKey  32-byte master key
+     * @param nonce      Stream nonce (16 bytes)
+     * @param _kemCt     Unused for symmetric AES-GCM-SIV; KEM wrappers pass it through
+     * @param header     20-byte preamble header, required (throws otherwise)
+     * @returns          `DerivedKeys` holding the 32-byte AES-GCM-SIV key and 32-byte commitment
+     */
+    deriveKeys(masterKey, nonce, _kemCt, header) {
+        if (!header || header.length !== HEADER_SIZE)
+            throw new Error(`AESGCMSIVCipher.deriveKeys: header binding required (got ${header?.length ?? 'undefined'} bytes)`);
+        _assertNotOwned('aes');
+        _assertNotOwned('sha2');
+        const hkdf = new HKDF_SHA256();
+        let okm;
+        try {
+            // INFO || header, binds formatEnum, framed flag, nonce, chunkSize into the KDF.
+            // Any header tampering produces different keys, AEAD fails on the first chunk.
+            const info = concat(INFO, header);
+            okm = hkdf.derive(masterKey, nonce, info, 64);
+        }
+        finally {
+            hkdf.dispose();
+        }
+        // Bytes 0..32: per-stream AES-GCM-SIV key (no subkey derivation step).
+        // Bytes 32..64: key commitment for the seal preamble.
+        const aesKey = okm.slice(0, 32); // independent backing, survives okm wipe
+        const commitment = okm.slice(32, 64); // independent backing, survives okm wipe
+        wipe(okm);
+        return { bytes: aesKey, commitment };
+    },
+    /**
+     * Encrypt and authenticate one stream chunk with AES-256-GCM-SIV.
+     * Output: ciphertext || 16-byte tag.
+     * @param keys         Derived keys from `deriveKeys`
+     * @param counterNonce 12-byte 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) {
+        _assertNotOwned('aes');
+        const x = getExports();
+        const { ciphertext, tag } = sivAeadEncrypt(x, keys.bytes, counterNonce, chunk, aad ?? new Uint8Array(0));
+        const out = new Uint8Array(ciphertext.length + 16);
+        out.set(ciphertext);
+        out.set(tag, ciphertext.length);
+        return out;
+    },
+    /**
+     * Verify and decrypt one stream chunk. Throws `AuthenticationError('aes-gcm-siv')`
+     * on tag mismatch.
+     * @param keys         Derived keys from `deriveKeys`
+     * @param counterNonce 12-byte per-chunk nonce, must match the value used by `sealChunk`
+     * @param chunk        Ciphertext || 16-byte tag
+     * @param aad          Optional additional authenticated data
+     * @returns            Plaintext
+     */
+    openChunk(keys, counterNonce, chunk, aad) {
+        _assertNotOwned('aes');
+        if (chunk.length < 16)
+            throw new RangeError(`chunk too short for 16-byte tag (got ${chunk.length})`);
+        const x = getExports();
+        const ct = chunk.subarray(0, chunk.length - 16);
+        const tag = chunk.subarray(chunk.length - 16);
+        return sivAeadDecrypt(x, keys.bytes, counterNonce, ct, tag, aad ?? new Uint8Array(0), 'aes-gcm-siv');
+    },
+    /**
+     * 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 an AES pool worker from the embedded IIFE bundle. The worker
+     * holds its own aes WASM instance and derived AES-GCM-SIV key.
+     * @returns  Newly constructed `Worker` instance
+     */
+    createPoolWorker() {
+        // 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/aes/embedded.d.ts

@@ -0,0 +1 @@
+export { WASM_GZ_BASE64 as aesWasm } from '../embedded/aes.js';

package/dist/aes/embedded.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/aes/embedded.ts
+//
+// Exports the gzip+base64 AES WASM blob for use as a WasmSource.
+// Import via `leviathan-crypto/aes/embedded`.
+export { WASM_GZ_BASE64 as aesWasm } from '../embedded/aes.js';

package/dist/aes/generator.d.ts

@@ -0,0 +1,14 @@
+import type { Generator } from '../types.js';
+/**
+ * AES-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. This is the original Fortuna spec primitive,
+ * `SerpentGenerator` and `ChaCha20Generator` are deliberate spec
+ * deviations; `AESGenerator` is the canonical choice.
+ *
+ * Pass to `Fortuna.create({ generator: AESGenerator, ... })`, do not
+ * call `generate()` directly outside of Fortuna.
+ */
+export declare const AESGenerator: Generator;

package/dist/aes/generator.js

@@ -0,0 +1,103 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/aes/generator.ts
+//
+// Practical Cryptography (Ferguson & Schneier, 2003) §9.4, generator
+// AES-256 ECB counter-mode PRF for Fortuna's generator slot. This is the
+// original Fortuna spec primitive; the library previously deviated by
+// shipping only Serpent and ChaCha20 generators. AES restores the
+// canonical construction.
+import { _assertNotOwned, getInstance } from '../init.js';
+import { wipe } from '../utils.js';
+/**
+ * AES-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. This is the original Fortuna spec primitive,
+ * `SerpentGenerator` and `ChaCha20Generator` are deliberate spec
+ * deviations; `AESGenerator` is the canonical choice.
+ *
+ * Pass to `Fortuna.create({ generator: AESGenerator, ... })`, do not
+ * call `generate()` directly outside of Fortuna.
+ */
+export const AESGenerator = {
+    keySize: 32,
+    blockSize: 16,
+    counterSize: 16,
+    wasmModules: ['aes'],
+    /**
+     * 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 AES-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('aes');
+        if (key.length !== 32)
+            throw new RangeError(`AESGenerator: key must be 32 bytes (got ${key.length})`);
+        if (counter.length !== 16)
+            throw new RangeError(`AESGenerator: counter must be 16 bytes (got ${counter.length})`);
+        if (!Number.isSafeInteger(n) || n < 0 || n > 2 ** 30)
+            throw new RangeError(`AESGenerator: n must be a non-negative safe integer <= 2^30 (got ${n})`);
+        const x = getInstance('aes').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('AESGenerator: 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 SerpentGenerator/ChaCha20Generator
+                // 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);
+        }
+    },
+};

package/dist/aes/index.d.ts

@@ -0,0 +1,58 @@
+import type { WasmSource } from '../wasm-source.js';
+/**
+ * Load and initialise the AES WASM module from `source`.
+ * Must be called before constructing any AES class.
+ * @param source  WASM binary, gzip+base64 string, URL, ArrayBuffer, Uint8Array,
+ *                pre-compiled WebAssembly.Module, Response, or Promise<Response>
+ */
+export declare function aesInit(source: WasmSource): Promise<void>;
+export type { WasmSource };
+export { isInitialized } from '../init.js';
+/**
+ * Low-level AES block cipher, raw ECB encrypt + decrypt.
+ *
+ * AES-128/192/256 supported. `loadKey` accepts 16, 24, or 32 byte keys;
+ * Nr (10, 12, or 14) is derived and persisted in WASM memory between
+ * `loadKey` and the cipher calls.
+ *
+ * Decrypt uses the FIPS 197 §5.3.5 Equivalent Inverse Cipher: the round
+ * loop mirrors encrypt, and round keys 1..Nr-1 are pre-transformed by
+ * InvMixColumns inside `loadKey`.
+ *
+ * Atomic (stateless): each method call is independent. Does not hold
+ * exclusive module access. Call `dispose()` after use to wipe WASM key
+ * material.
+ */
+export declare class AES {
+    private readonly x;
+    constructor();
+    /**
+     * Expand `key` into the WASM key schedule (forward + EqInvCipher
+     * inverse round keys). Must be called before `encryptBlock` or
+     * `decryptBlock`.
+     * @param key  16, 24, or 32 bytes (AES-128 / 192 / 256)
+     */
+    loadKey(key: Uint8Array): void;
+    /**
+     * Encrypt one 128-bit block with the previously loaded key schedule.
+     * FIPS 197 §5.1 Algorithm 1, Nr ∈ {10, 12, 14}.
+     * @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.
+     * FIPS 197 §5.3.5 Equivalent Inverse Cipher, Nr ∈ {10, 12, 14}.
+     * @param ciphertext  16-byte ciphertext block
+     * @returns           16-byte plaintext block
+     */
+    decryptBlock(ciphertext: Uint8Array): Uint8Array;
+    /** Wipe WASM key material and intermediate buffers. */
+    dispose(): void;
+}
+export { AESCbc } from './aes-cbc.js';
+export { AESCtr } from './aes-ctr.js';
+export { AESGCM } from './aes-gcm.js';
+export { AESGCMSIV } from './aes-gcm-siv.js';
+export { AESGenerator } from './generator.js';
+export { AESGCMSIVCipher } from './cipher-suite.js';