leviathan-crypto 2.0.1 → 3.0.0

package/dist/aes/aes-cbc.js

@@ -0,0 +1,158 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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-cbc.ts
+//
+// AESCbc, AES-128/192/256 CBC + PKCS7, stateful TS wrapper.
+// SP 800-38A §6.2 (mode), RFC 5652 §6.3 (PKCS7 padding).
+// Mirrors `src/ts/serpent/serpent-cbc.ts` exactly in shape; only the
+// underlying WASM module and the PKCS7 import path differ.
+import { getInstance, _acquireModule, _releaseModule } from '../init.js';
+import { pkcs7Pad, pkcs7Strip, PKCS7_INVALID } from '../shared/pkcs7.js';
+/** Returns the raw AES WASM export object. @internal */
+function getExports() {
+    return getInstance('aes').exports;
+}
+// ── AESCbc ──────────────────────────────────────────────────────────────────
+/**
+ * AES-128/192/256 in CBC mode with PKCS7 padding.
+ *
+ * **WARNING: CBC mode is unauthenticated.** Always authenticate the output
+ * with HMAC-SHA256 (Encrypt-then-MAC) or use an authenticated cipher
+ * (`XChaCha20Poly1305`, `Seal` with `SerpentCipher`) instead.
+ *
+ * Holds exclusive access to the `aes` WASM module from construction until
+ * `dispose()`. Constructing a second AES-using class while this instance
+ * is live throws. Call `dispose()` when done.
+ */
+export class AESCbc {
+    x;
+    _tok;
+    constructor(opts) {
+        if (!opts?.dangerUnauthenticated) {
+            throw new Error('leviathan-crypto: AESCbc is unauthenticated, use Seal with SerpentCipher or XChaCha20Cipher instead. ' +
+                'To use AESCbc directly, pass { dangerUnauthenticated: true }.');
+        }
+        this.x = getExports();
+        this._tok = _acquireModule('aes');
+    }
+    /** View over WASM linear memory. Rebind on every access, memory can be detached after grow. @internal */
+    get mem() {
+        return new Uint8Array(this.x.memory.buffer);
+    }
+    /**
+     * Encrypt plaintext with AES CBC + PKCS7 padding.
+     *
+     * @param key       16, 24, or 32 bytes (AES-128 / 192 / 256)
+     * @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) {
+        if (this._tok === undefined)
+            throw new Error('AESCbc: instance has been disposed');
+        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 = this.x.getChunkSize();
+        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);
+            const ret = this.x.cbcEncryptChunk(chunk.length);
+            if (ret < 0)
+                throw new RangeError(`cbcEncryptChunk rejected len=${chunk.length}` +
+                    ` (WASM CHUNK_SIZE=${this.x.getChunkSize()})`);
+            output.set(new Uint8Array(this.x.memory.buffer).subarray(ctOff, ctOff + chunk.length), off);
+        }
+        return output;
+    }
+    /**
+     * Decrypt AES CBC + PKCS7.
+     *
+     * All failure modes, empty input, non-multiple-of-16 length, and any
+     * PKCS7 validation failure, throw the same generic `RangeError` with
+     * message `'invalid ciphertext'`. Padding validation runs branch-free
+     * over the last 16 bytes regardless of where the mismatch is, closing
+     * the Vaudenay 2002 padding-oracle surface for callers using
+     * `{ dangerUnauthenticated: true }` without an outer HMAC.
+     */
+    decrypt(key, iv, ciphertext) {
+        if (this._tok === undefined)
+            throw new Error('AESCbc: instance has been disposed');
+        if (ciphertext.length === 0 || ciphertext.length % 16 !== 0)
+            throw new RangeError(PKCS7_INVALID);
+        this._loadKey(key);
+        this._setIv(iv);
+        const output = new Uint8Array(ciphertext.length);
+        const ctOff = this.x.getChunkCtOffset();
+        const ptOff = this.x.getChunkPtOffset();
+        const maxChunk = this.x.getChunkSize();
+        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);
+            const ret = this.x.cbcDecryptChunk_simd(chunk.length);
+            if (ret < 0)
+                throw new RangeError(`cbcDecryptChunk_simd rejected len=${chunk.length}` +
+                    ` (WASM CHUNK_SIZE=${this.x.getChunkSize()})`);
+            output.set(new Uint8Array(this.x.memory.buffer).subarray(ptOff, ptOff + chunk.length), off);
+        }
+        return pkcs7Strip(output);
+    }
+    /** 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;
+        }
+    }
+    /**
+     * Validate and load `key` into the WASM key schedule.
+     * @param key  16, 24, or 32 bytes
+     * @internal
+     */
+    _loadKey(key) {
+        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})`);
+        this.mem.set(key, this.x.getKeyOffset());
+        if (this.x.loadKey(key.length) !== 0) {
+            this.x.wipeBuffers();
+            throw new Error('AESCbc: loadKey failed');
+        }
+    }
+    /**
+     * Write `iv` into the WASM CBC IV buffer.
+     * @param iv  16 bytes
+     * @internal
+     */
+    _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());
+    }
+}

package/dist/aes/aes-ctr.d.ts

@@ -0,0 +1,50 @@
+/**
+ * AES-128/192/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 an authenticated cipher (`AESGCM`, `AESGCMSIV`, or `Seal` with
+ * `AESGCMSIVCipher` / `SerpentCipher` / `XChaCha20Cipher`) instead.
+ *
+ * The constructor requires `{ dangerUnauthenticated: true }` so callers
+ * cannot reach the unauthenticated path by accident, same gate as
+ * `AESCbc` and `SerpentCtr`.
+ *
+ * The counter is 128-bit big-endian (SP 800-38A Appendix B.1 / §F.5).
+ *
+ * Stateful, the counter advances across `encrypt`/`decrypt` calls. Reset
+ * with `setNonce()` before each new message. Holds exclusive access to the
+ * `aes` WASM module from construction until `dispose()`.
+ */
+export declare class AESCtr {
+    private readonly x;
+    private _tok;
+    constructor(opts?: {
+        dangerUnauthenticated: true;
+    });
+    /**
+     * Expand `key` into the WASM key schedule. Must be called before
+     * `setNonce` / `encrypt` / `decrypt`.
+     * @param key  16, 24, or 32 bytes (AES-128 / 192 / 256)
+     */
+    loadKey(key: Uint8Array): void;
+    /**
+     * Set the 128-bit initial counter block (the full IC, not a separate
+     * nonce/counter split). Resets the working counter so subsequent
+     * encrypt/decrypt calls start at this value.
+     * @param nonce  16 bytes, must be unique per (key, message)
+     */
+    setNonce(nonce: Uint8Array): void;
+    /**
+     * XOR `plaintext` with AES CTR keystream. The counter advances by
+     * ceil(plaintext.length / 16) blocks; counter state persists across
+     * calls until `setNonce()` resets it.
+     * @param plaintext  any length; internally chunked to WASM CHUNK_SIZE
+     * @returns          ciphertext of the same length
+     */
+    encrypt(plaintext: Uint8Array): Uint8Array;
+    /** Alias for `encrypt`, CTR mode is symmetric. */
+    decrypt(ciphertext: Uint8Array): Uint8Array;
+    /** Wipe WASM state and release exclusive module access. Idempotent. */
+    dispose(): void;
+}

package/dist/aes/aes-ctr.js

@@ -0,0 +1,141 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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-ctr.ts
+//
+// AESCtr, AES-128/192/256 in CTR mode, stateful TS wrapper.
+// SP 800-38A §6.5 (mode), Appendix B.1 (counter increment).
+// Counter direction: 128-bit big-endian, matching the SP 800-38A §F.5
+// worked examples and the canonical AES CTR convention. Configured in
+// the underlying WASM (`src/asm/aes/ctr.ts`).
+import { getInstance, _acquireModule, _releaseModule } from '../init.js';
+/** Returns the raw AES WASM export object. @internal */
+function getExports() {
+    return getInstance('aes').exports;
+}
+// ── AESCtr ──────────────────────────────────────────────────────────────────
+/**
+ * AES-128/192/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 an authenticated cipher (`AESGCM`, `AESGCMSIV`, or `Seal` with
+ * `AESGCMSIVCipher` / `SerpentCipher` / `XChaCha20Cipher`) instead.
+ *
+ * The constructor requires `{ dangerUnauthenticated: true }` so callers
+ * cannot reach the unauthenticated path by accident, same gate as
+ * `AESCbc` and `SerpentCtr`.
+ *
+ * The counter is 128-bit big-endian (SP 800-38A Appendix B.1 / §F.5).
+ *
+ * Stateful, the counter advances across `encrypt`/`decrypt` calls. Reset
+ * with `setNonce()` before each new message. Holds exclusive access to the
+ * `aes` WASM module from construction until `dispose()`.
+ */
+export class AESCtr {
+    x;
+    _tok;
+    constructor(opts) {
+        if (!opts?.dangerUnauthenticated) {
+            throw new Error('leviathan-crypto: AESCtr is unauthenticated, use Seal with AESGCMSIVCipher, SerpentCipher, or XChaCha20Cipher instead. ' +
+                'To use AESCtr directly, pass { dangerUnauthenticated: true }.');
+        }
+        this.x = getExports();
+        this._tok = _acquireModule('aes');
+    }
+    /** View over WASM linear memory. Rebind on every access, memory can be detached after grow. @internal */
+    get mem() {
+        return new Uint8Array(this.x.memory.buffer);
+    }
+    /**
+     * Expand `key` into the WASM key schedule. Must be called before
+     * `setNonce` / `encrypt` / `decrypt`.
+     * @param key  16, 24, or 32 bytes (AES-128 / 192 / 256)
+     */
+    loadKey(key) {
+        if (this._tok === undefined)
+            throw new Error('AESCtr: instance has been disposed');
+        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})`);
+        this.mem.set(key, this.x.getKeyOffset());
+        if (this.x.loadKey(key.length) !== 0) {
+            this.x.wipeBuffers();
+            throw new Error('loadKey failed');
+        }
+    }
+    /**
+     * Set the 128-bit initial counter block (the full IC, not a separate
+     * nonce/counter split). Resets the working counter so subsequent
+     * encrypt/decrypt calls start at this value.
+     * @param nonce  16 bytes, must be unique per (key, message)
+     */
+    setNonce(nonce) {
+        if (this._tok === undefined)
+            throw new Error('AESCtr: instance has been disposed');
+        if (nonce.length !== 16)
+            throw new RangeError(`AES CTR nonce must be 16 bytes (got ${nonce.length})`);
+        this.mem.set(nonce, this.x.getNonceOffset());
+        this.x.resetCounter();
+    }
+    /**
+     * XOR `plaintext` with AES CTR keystream. The counter advances by
+     * ceil(plaintext.length / 16) blocks; counter state persists across
+     * calls until `setNonce()` resets it.
+     * @param plaintext  any length; internally chunked to WASM CHUNK_SIZE
+     * @returns          ciphertext of the same length
+     */
+    encrypt(plaintext) {
+        if (this._tok === undefined)
+            throw new Error('AESCtr: instance has been disposed');
+        const output = new Uint8Array(plaintext.length);
+        if (plaintext.length === 0)
+            return output;
+        const ptOff = this.x.getChunkPtOffset();
+        const ctOff = this.x.getChunkCtOffset();
+        const maxChunk = this.x.getChunkSize();
+        for (let off = 0; off < plaintext.length; off += maxChunk) {
+            const chunk = plaintext.subarray(off, Math.min(off + maxChunk, plaintext.length));
+            this.mem.set(chunk, ptOff);
+            const ret = this.x.encryptChunk_simd(chunk.length);
+            if (ret < 0)
+                throw new RangeError(`encryptChunk_simd rejected len=${chunk.length}` +
+                    ` (WASM CHUNK_SIZE=${this.x.getChunkSize()})`);
+            output.set(new Uint8Array(this.x.memory.buffer).subarray(ctOff, ctOff + chunk.length), off);
+        }
+        return output;
+    }
+    /** Alias for `encrypt`, CTR mode is symmetric. */
+    decrypt(ciphertext) {
+        return this.encrypt(ciphertext);
+    }
+    /** 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;
+        }
+    }
+}

package/dist/aes/aes-gcm-siv.d.ts

@@ -0,0 +1,67 @@
+/**
+ * AES-128-GCM-SIV / AES-256-GCM-SIV (RFC 8452). Nonce-misuse-resistant
+ * authenticated AEAD with a 128-bit tag. AES-192 keys are rejected
+ * (RFC 8452 §6, no AES-192-GCM-SIV variant exists).
+ *
+ * Single-shot only: each `seal` / `open` call processes one complete
+ * message bounded by 64 KiB of plaintext. Larger messages are out of
+ * scope for this primitive; a future streaming variant will lift the
+ * cap via the seal/sealstream layer.
+ *
+ * `seal(nonce, plaintext, aad?)` returns `ciphertext || tag` (length
+ * pt.length + 16). `open(nonce, sealed, aad?)` verifies the tag and
+ * returns the plaintext; throws `AuthenticationError('siv')` on any
+ * verification failure.
+ *
+ * Atomic, does not hold exclusive access between calls. `dispose()`
+ * wipes the stored key from the JS-side cache.
+ */
+export declare class AESGCMSIV {
+    private readonly _key;
+    private _disposed;
+    /**
+     * @param key  16 bytes (AES-128-GCM-SIV) or 32 bytes (AES-256-GCM-SIV).
+     *             24-byte keys are rejected, RFC 8452 §6 does not define
+     *             an AES-192-GCM-SIV variant.
+     */
+    constructor(key: Uint8Array);
+    /**
+     * Authenticated encryption.
+     *
+     * @param nonce  exactly 12 bytes (RFC 8452 §6 fixes nonce length)
+     * @param plaintext  any length up to 64 KiB; may be empty
+     * @param aad  any length up to 64 KiB; may be empty
+     * @returns  ciphertext concatenated with the 128-bit tag
+     *           (length = plaintext.length + 16)
+     *
+     * @throws RangeError if any input length violates the spec or the
+     *         buffer-bounded API.
+     */
+    seal(nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    /**
+     * Authenticated decryption. `sealed` is the output of a matching
+     * `seal(nonce, plaintext, aad)` call.
+     *
+     * Verification routes through `constantTimeEqual` from
+     * `../utils.js` (the dedicated `ct` WASM module). On mismatch the
+     * WASM `sivWipeOnFail` helper zeroes the decrypted-but-
+     * unauthenticated plaintext at CHUNK_PT_OFFSET before this method
+     * throws, the bytes never become reachable from JS.
+     *
+     * @throws AuthenticationError('siv') if the tag fails to verify, or
+     *         if `sealed` is too short, or any input length violates the
+     *         spec.
+     */
+    open(nonce: Uint8Array, sealed: Uint8Array, aad?: Uint8Array): Uint8Array;
+    /**
+     * Wipe the in-memory copy of the key. Idempotent. Subsequent calls
+     * to `seal` / `open` throw. WASM-side state is wiped at the end of
+     * every successful operation regardless of `dispose()`.
+     */
+    dispose(): void;
+    private _mem;
+    private _assertAlive;
+    private _validate;
+    /** Push KGK + nonce + AAD into WASM memory. Common to seal/open. */
+    private _stage;
+}

package/dist/aes/aes-gcm-siv.js

@@ -0,0 +1,217 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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-siv.ts
+import { getInstance, _acquireModule, _releaseModule } from '../init.js';
+import { constantTimeEqual, wipe } from '../utils.js';
+import { AuthenticationError } from '../errors.js';
+// RFC 8452 §6: K_LEN ∈ {16, 32}, AES-128-GCM-SIV or AES-256-GCM-SIV.
+const KEY_LEN_128 = 16;
+const KEY_LEN_256 = 32;
+// RFC 8452 §6: nonce length is fixed at 96 bits (12 bytes).
+const NONCE_LEN = 12;
+// Single-shot bound: plaintext fits in CHUNK_PT (64 KiB). Larger inputs
+// would need a streaming SIV API; not currently in scope.
+const MAX_PT_BYTES = 65536;
+// AAD is bounded by the dedicated AAD_BUFFER (64 KiB).
+const MAX_AAD_BYTES = 65536;
+// 16-byte authentication tag.
+const TAG_LEN = 16;
+/** Returns the raw AES WASM export object. @internal */
+function getExports() {
+    return getInstance('aes').exports;
+}
+// ── AESGCMSIV ───────────────────────────────────────────────────────────────
+/**
+ * AES-128-GCM-SIV / AES-256-GCM-SIV (RFC 8452). Nonce-misuse-resistant
+ * authenticated AEAD with a 128-bit tag. AES-192 keys are rejected
+ * (RFC 8452 §6, no AES-192-GCM-SIV variant exists).
+ *
+ * Single-shot only: each `seal` / `open` call processes one complete
+ * message bounded by 64 KiB of plaintext. Larger messages are out of
+ * scope for this primitive; a future streaming variant will lift the
+ * cap via the seal/sealstream layer.
+ *
+ * `seal(nonce, plaintext, aad?)` returns `ciphertext || tag` (length
+ * pt.length + 16). `open(nonce, sealed, aad?)` verifies the tag and
+ * returns the plaintext; throws `AuthenticationError('siv')` on any
+ * verification failure.
+ *
+ * Atomic, does not hold exclusive access between calls. `dispose()`
+ * wipes the stored key from the JS-side cache.
+ */
+export class AESGCMSIV {
+    _key;
+    _disposed = false;
+    /**
+     * @param key  16 bytes (AES-128-GCM-SIV) or 32 bytes (AES-256-GCM-SIV).
+     *             24-byte keys are rejected, RFC 8452 §6 does not define
+     *             an AES-192-GCM-SIV variant.
+     */
+    constructor(key) {
+        if (key.length !== KEY_LEN_128 && key.length !== KEY_LEN_256) {
+            throw new RangeError(`AESGCMSIV key must be 16 or 32 bytes (got ${key.length}); `
+                + 'AES-192-GCM-SIV is not defined by RFC 8452');
+        }
+        // Defensive copy so external mutation cannot change the live key.
+        this._key = new Uint8Array(key);
+    }
+    /**
+     * Authenticated encryption.
+     *
+     * @param nonce  exactly 12 bytes (RFC 8452 §6 fixes nonce length)
+     * @param plaintext  any length up to 64 KiB; may be empty
+     * @param aad  any length up to 64 KiB; may be empty
+     * @returns  ciphertext concatenated with the 128-bit tag
+     *           (length = plaintext.length + 16)
+     *
+     * @throws RangeError if any input length violates the spec or the
+     *         buffer-bounded API.
+     */
+    seal(nonce, plaintext, aad = new Uint8Array(0)) {
+        this._assertAlive();
+        this._validate(nonce, plaintext.length, aad);
+        const x = getExports();
+        const tok = _acquireModule('aes');
+        try {
+            this._stage(x, nonce, aad);
+            this._mem(x).set(plaintext, x.getChunkPtOffset());
+            x.sivDeriveKeys(x.getNonceOffset());
+            x.sivSeal(aad.length, plaintext.length);
+            const ctOff = x.getChunkPtOffset();
+            const tagOff = x.getTagOffset();
+            const out = new Uint8Array(plaintext.length + TAG_LEN);
+            out.set(this._mem(x).subarray(ctOff, ctOff + plaintext.length), 0);
+            out.set(this._mem(x).subarray(tagOff, tagOff + TAG_LEN), plaintext.length);
+            return out;
+        }
+        finally {
+            x.wipeBuffers();
+            _releaseModule('aes', tok);
+        }
+    }
+    /**
+     * Authenticated decryption. `sealed` is the output of a matching
+     * `seal(nonce, plaintext, aad)` call.
+     *
+     * Verification routes through `constantTimeEqual` from
+     * `../utils.js` (the dedicated `ct` WASM module). On mismatch the
+     * WASM `sivWipeOnFail` helper zeroes the decrypted-but-
+     * unauthenticated plaintext at CHUNK_PT_OFFSET before this method
+     * throws, the bytes never become reachable from JS.
+     *
+     * @throws AuthenticationError('siv') if the tag fails to verify, or
+     *         if `sealed` is too short, or any input length violates the
+     *         spec.
+     */
+    open(nonce, sealed, aad = new Uint8Array(0)) {
+        this._assertAlive();
+        if (sealed.length < TAG_LEN) {
+            throw new AuthenticationError('siv');
+        }
+        const ctLen = sealed.length - TAG_LEN;
+        try {
+            this._validate(nonce, ctLen, aad);
+        }
+        catch {
+            // Same generic error so failure modes are indistinguishable.
+            throw new AuthenticationError('siv');
+        }
+        const ct = sealed.subarray(0, ctLen);
+        const providedTag = sealed.subarray(ctLen, sealed.length);
+        const x = getExports();
+        const tok = _acquireModule('aes');
+        try {
+            this._stage(x, nonce, aad);
+            this._mem(x).set(ct, x.getChunkCtOffset());
+            // Stage the provided tag at SIV_IC_OFFSET, sivOpen will
+            // read it from there as the input to the CTR initial counter.
+            this._mem(x).set(providedTag, x.getSivIcOffset());
+            x.sivDeriveKeys(x.getNonceOffset());
+            x.sivOpen(aad.length, ctLen);
+            // Read the EXPECTED tag computed by sivOpen from TAG_OFFSET.
+            // Use slice() rather than subarray() so the buffer survives
+            // any subsequent WASM memory growth or wipe.
+            const expectedTag = this._mem(x).slice(x.getTagOffset(), x.getTagOffset() + TAG_LEN);
+            // Defensive copy of providedTag for the constant-time compare,
+            // the input may be a view over a caller-controlled buffer.
+            const providedTagCopy = new Uint8Array(providedTag);
+            const ok = constantTimeEqual(expectedTag, providedTagCopy);
+            if (!ok) {
+                // Wipe before finally; covers JS-heap tag copies.
+                x.sivWipeOnFail();
+                wipe(expectedTag);
+                wipe(providedTagCopy);
+                throw new AuthenticationError('siv');
+            }
+            // Match, read PT before wiping. pt is a JS-heap slice copy.
+            const ptOff = x.getChunkPtOffset();
+            const pt = this._mem(x).slice(ptOff, ptOff + ctLen);
+            wipe(expectedTag);
+            wipe(providedTagCopy);
+            return pt;
+        }
+        finally {
+            x.wipeBuffers();
+            _releaseModule('aes', tok);
+        }
+    }
+    /**
+     * Wipe the in-memory copy of the key. Idempotent. Subsequent calls
+     * to `seal` / `open` throw. WASM-side state is wiped at the end of
+     * every successful operation regardless of `dispose()`.
+     */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._key.fill(0);
+        this._disposed = true;
+    }
+    // ── Internal helpers ───────────────────────────────────────────────────
+    _mem(x) {
+        return new Uint8Array(x.memory.buffer);
+    }
+    _assertAlive() {
+        if (this._disposed)
+            throw new Error('AESGCMSIV: instance has been disposed');
+    }
+    _validate(nonce, dataLen, aad) {
+        if (nonce.length !== NONCE_LEN)
+            throw new RangeError(`AESGCMSIV nonce must be ${NONCE_LEN} bytes (got ${nonce.length})`);
+        if (dataLen > MAX_PT_BYTES)
+            throw new RangeError(`AESGCMSIV plaintext must be ≤ ${MAX_PT_BYTES} bytes (got ${dataLen})`);
+        if (aad.length > MAX_AAD_BYTES)
+            throw new RangeError(`AESGCMSIV AAD must be ≤ ${MAX_AAD_BYTES} bytes (got ${aad.length})`);
+    }
+    /** Push KGK + nonce + AAD into WASM memory. Common to seal/open. */
+    _stage(x, nonce, aad) {
+        const mem = this._mem(x);
+        mem.set(this._key, x.getKeyOffset());
+        if (x.loadKey(this._key.length) !== 0) {
+            x.wipeBuffers();
+            throw new Error('AESGCMSIV: loadKey failed');
+        }
+        mem.set(nonce, x.getNonceOffset());
+        if (aad.length > 0) {
+            mem.set(aad, x.getAadOffset());
+        }
+    }
+}