leviathan-crypto 1.3.1 → 2.0.0

package/SECURITY.md

@@ -4,7 +4,7 @@
 
 - **[Version Support](#supported-versions)**
 - **[Security Posture](#security-posture)**
-- **[Cryptanalytic Audits](#cryptanalytic-reviews)**
+- **[Cryptanalytic Audits](#cryptanalytic-audits)**
 - **[Vulnerability Reporting](#reporting-a-vulnerability)**
 
 ---
@@ -12,26 +12,39 @@
 ## Supported Versions
 
 | Version | Supported |
-|---------|-----------|
-| v1.3.x  | ︎✓         |
-| v1.2.x  | ✓         |
+| ------- | --------- |
+| v2.0.x  | ✓         |
+| v1.4.x  | ✗         |
+| v1.3.x  | ✗         |
+| v1.2.x  | ✗         |
 | v1.1.x  | ✗         |
 | v1.0.x  | ✗         |
 
+> [!CAUTION]
+> **All v1.x releases are deprecated.** Upgrading to v2 is strongly
+> recommended. v1.x releases will not receive security patches.
+
 > [!WARNING]
-> v1.0.x does not zero intermediate key material in HMAC and HKDF operations.
-> Upgrading to v1.1.0 or later is strongly recommended.
+> **v1.x known issues** (addressed in v2):
+> - Partial WASM buffer wipe on AEAD and serpent auth failure.
+> - HMAC tag and HKDF operations do not zero intermediate key material.
+> - TransformStream error paths leak derived keys.
+> - Pool workers copy result buffers.
+> - Scalar JS `constantTimeEqual` was "best-effort only".
+
 
 ## Security Posture
 
-[`leviathan-crypto`](https://leviathan.3xi.club) is a cryptography library. Security is not an afterthought,
-it is the primary design constraint at every layer of the stack.
+[`leviathan-crypto`](https://leviathan.3xi.club) is a cryptography library.
+Security is not an afterthought, it is the primary design constraint at every
+layer of the stack.
 
 ### Algorithm Correctness
 
 Every primitive in this library was implemented by hand in AssemblyScript
 against the authoritative specification for that algorithm:
 [FIPS 180-4][fips180] (SHA-2), [FIPS 202][fips202] (SHA-3),
+[FIPS 203][fips203] (ML-KEM),
 [RFC 8439][rfc8439] (ChaCha20-Poly1305), [RFC 2104][rfc2104] (HMAC),
 [RFC 5869][rfc5869] (HKDF), and the original
 [Serpent-256 specification][serpent] and S-box reference. No algorithm was
@@ -51,9 +64,13 @@ timing-safe cipher implementation approach available in a WASM runtime,
 where JIT optimisation can otherwise introduce observable timing variation.
 
 All security-sensitive comparisons (e.g. MAC verification, padding validation)
-use XOR-accumulate patterns with no early return on mismatch.
-[`constantTimeEqual`][utils] is the mandated comparison function throughout
-the library and its [demos][demos].
+use [`constantTimeEqual`][utils], which is backed by a dedicated WASM SIMD module
+(v128 XOR accumulate + `any_true`) when WebAssembly SIMD is available. The WASM
+execution path eliminates JIT short-circuiting and speculative optimization as
+theoretical side-channel vectors. On runtimes without SIMD (sha2/sha3-only
+consumers), the function falls back to a JS XOR-accumulate loop. This is best-effort
+constant-time, not a hardware-level guarantee. WASM comparison memory is
+wiped after every call.
 
 ### WASM Execution Model
 
@@ -62,20 +79,36 @@ JavaScript JIT. WASM execution is deterministic and not subject to JIT
 speculation or optimisation. Each primitive family compiles to its own
 isolated binary with its own linear memory. For example, key material in
 the Serpent module cannot interact with memory in the SHA-3 module,
-even in principle.
-
-### Cryptanalytic Reviews
-
-All of our primitives undergo periodic cryptographic implementation reviews.
-
-| Primitive | Audit Description |
-|-----------|-------------------|
-| [serpent_audit][serpent_audit] | Correctness verification, side-channel analysis, cryptanalytic attack paper review |
-| [chacha_audit][chacha_audit] | XChaCha20-Poly1305 correctness, Poly1305 field arithmetic, HChaCha20 nonce extension |
-| [sha2_audit][sha2_audit] | SHA-256/512/384 correctness, HMAC and HKDF composition, constant verification |
-| [sha3_audit][sha3_audit] | Keccak permutation correctness, θ/ρ/π/χ/ι step verification, round constant derivation |
-| [hmac_audit][hmac_audit] | HMAC-SHA256/512/384 construction, key processing, RFC 4231 vector coverage |
-| [hkdf_audit][hkdf_audit] | HKDF extract-then-expand, info field domain separation, SerpentStream key derivation |
+even in principle. A dedicated WASM module handles constant-time comparison
+with its own single-page memory that is wiped after every call.
+
+Serpent and ChaCha20 modules require WebAssembly SIMD (`v128` instructions).
+`init()` and `initModule()` perform a SIMD preflight check and throw a
+clear error on runtimes without support. SIMD has been a baseline feature
+of all major browsers and runtimes since 2021. SHA-2 and SHA-3 modules
+run on any WASM-capable runtime.
+
+The `kyber` module requires WebAssembly SIMD for NTT and polynomial
+arithmetic (`v128` instructions). The SIMD preflight check is applied on
+`init()` alongside serpent and chacha20. Its linear memory is independent
+from all other modules. The kyber module's constant-time path (FO transform
+decapsulation) uses dedicated `ct_verify` and `ct_cmov` functions implemented
+in the kyber WASM binary. The comparison never passes through JavaScript.
+
+### Cryptanalytic Audits
+
+All primitives undergo periodic cryptographic implementation reviews. See the [audit index][audits] for a full summary.
+
+| Primitive                      | Audit Description                                                                      |
+| ------------------------------ | -------------------------------------------------------------------------------------- |
+| [serpent_audit][serpent_audit] | Correctness verification, side-channel analysis, cryptanalytic attack paper review     |
+| [chacha_audit][chacha_audit]   | XChaCha20-Poly1305 correctness, Poly1305 field arithmetic, HChaCha20 nonce extension   |
+| [sha2_audit][sha2_audit]       | SHA-256/512/384 correctness, HMAC and HKDF composition, constant verification          |
+| [sha3_audit][sha3_audit]       | Keccak permutation correctness, θ/ρ/π/χ/ι step verification, round constant derivation |
+| [hmac_audit][hmac_audit]       | HMAC-SHA256/512/384 construction, key processing, RFC 4231 vector coverage             |
+| [hkdf_audit][hkdf_audit]       | HKDF extract-then-expand, info field domain separation, stream key derivation          |
+| [kyber_audit][kyber_audit]     | ML-KEM FIPS 203 correctness, NTT/Montgomery/Barrett verification, FO transform CT analysis, ACVP validation |
+| [stream_audit][stream_audit]   | Streaming AEAD composition, counter nonce binding, final-chunk detection, key wipe paths |
 
 #### Additional Serpent-256 research
 
@@ -92,17 +125,32 @@ See: [`xero/BicliqueFinder/biclique_research.md`][biclique]
 
 ### Authenticated Encryption by Default
 
-Raw unauthenticated cipher modes (`SerpentCbc`, `SerpentCtr`) are exposed
-for power users but are not the recommended entry point. The primary API
-surfaces — `SerpentSeal`, `SerpentStream`, `SerpentStreamSealer` — are
-authenticated by construction.
-
-**`SerpentStreamSealer` satisfies the _Cryptographic Doom Principle_:**
-
-MAC verification is the unconditional gate on the open path,
-decryption is unreachable until that gate clears, and per-chunk
-HKDF key derivation with position-bound info extends this
-guarantee to full stream integrity.
+Raw unauthenticated cipher modes (`SerpentCbc`, `SerpentCtr`, `ChaCha20`) and
+stateless caller-managed-nonce primitives (`ChaCha20Poly1305`,
+`XChaCha20Poly1305`) are exposed for power users but are not the recommended
+entry point. The primary API surfaces (`Seal`, `SealStream`, `OpenStream`,
+`SealStreamPool`, and `KyberSuite`) are authenticated by construction with
+internally managed nonces.
+
+**All streaming constructions satisfy the _Cryptographic Doom Principle_:**
+
+`SealStream` / `OpenStream` with `SerpentCipher` uses encrypt-then-MAC
+(SerpentCbc + HMAC-SHA256). MAC verification is the unconditional gate on
+the open path. Decryption is unreachable until that gate clears. HKDF key
+derivation with the stream nonce and counter-nonce domain separation
+extends this guarantee to full stream integrity.
+
+`SealStream` / `OpenStream` with `XChaCha20Cipher` uses XChaCha20-Poly1305
+AEAD per chunk. The Poly1305 tag is verified inside the WASM `aeadDecrypt`
+call before any plaintext is produced. On authentication failure, the full
+chunk output buffer is wiped and plaintext bytes are never returned.
+Counter nonces with TAG_DATA/TAG_FINAL final-flag domain separation ensure
+reorder, splice, truncation, and cross-stream substitution all fail AEAD
+verification before decryption.
+
+`SealStreamPool` delegates per-chunk AEAD to isolated Web Workers. Each
+worker holds its own derived subkey and WASM instance. Any authentication
+error kills all workers, wipes all key material, and marks the pool dead. No retry, no partial results.
 
 ### Dependency Management
 
@@ -163,7 +211,7 @@ or research notes, for full hacker scene credit.
 
 If you prefer to contact the maintainer directly:
 
-- **Email:** x﹫xero.style — PGP: [`0xAC1D0000`][pgp]
+- **Email:** x﹫xero.style · PGP: [`0xAC1D0000`][pgp]
 - **Matrix:** x0﹫rx.haunted.computer
 
 > [!NOTE]
@@ -198,6 +246,7 @@ If you prefer to contact the maintainer directly:
 
 [fips180]:        https://csrc.nist.gov/publications/detail/fips/180/4/final
 [fips202]:        https://csrc.nist.gov/publications/detail/fips/202/final
+[fips203]:        https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf
 [rfc8439]:        https://www.rfc-editor.org/rfc/rfc8439
 [rfc2104]:        https://www.rfc-editor.org/rfc/rfc2104
 [rfc5869]:        https://www.rfc-editor.org/rfc/rfc5869
@@ -210,6 +259,9 @@ If you prefer to contact the maintainer directly:
 [sha3_audit]:     https://github.com/xero/leviathan-crypto/wiki/sha3_audit
 [hmac_audit]:     https://github.com/xero/leviathan-crypto/wiki/hmac_audit
 [hkdf_audit]:     https://github.com/xero/leviathan-crypto/wiki/hkdf_audit
+[kyber_audit]:    https://github.com/xero/leviathan-crypto/wiki/kyber_audit
+[stream_audit]:   https://github.com/xero/leviathan-crypto/wiki/stream_audit
+[audits]:         https://github.com/xero/leviathan-crypto/wiki/audits
 [biclique]:       https://github.com/xero/BicliqueFinder/blob/main/biclique-research.md
 [argon2id-wiki]:  https://github.com/xero/leviathan-crypto/wiki/argon2id
 [workflows]:      https://github.com/xero/leviathan-crypto/blob/main/scripts/pin-actions.ts

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

@@ -0,0 +1,4 @@
+import type { CipherSuite } from '../stream/types.js';
+export declare const XChaCha20Cipher: CipherSuite & {
+    keygen(): Uint8Array;
+};

package/dist/chacha20/cipher-suite.js

@@ -0,0 +1,78 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/chacha20/cipher-suite.ts
+//
+// XChaCha20Cipher — CipherSuite implementation for the STREAM construction.
+// HKDF-SHA-256 key derivation → HChaCha20 subkey → ChaCha20-Poly1305 per chunk.
+import { getInstance } from '../init.js';
+import { HKDF_SHA256 } from '../sha2/index.js';
+import { aeadEncrypt, aeadDecrypt, deriveSubkey } from './ops.js';
+import { wipe, randomBytes } from '../utils.js';
+const INFO = new TextEncoder().encode('xchacha20-sealstream-v2');
+function getExports() {
+    return getInstance('chacha20').exports;
+}
+export const XChaCha20Cipher = {
+    formatEnum: 0x01,
+    formatName: 'xchacha20',
+    hkdfInfo: 'xchacha20-sealstream-v2',
+    keySize: 32,
+    kemCtSize: 0,
+    tagSize: 16,
+    padded: false,
+    wasmModules: ['chacha20'],
+    keygen() {
+        return randomBytes(32);
+    },
+    deriveKeys(masterKey, nonce, _kemCt) {
+        const hkdf = new HKDF_SHA256();
+        const streamKey = hkdf.derive(masterKey, nonce, INFO, 32);
+        hkdf.dispose();
+        // HChaCha20 subkey derivation — nonce[0:16] as XChaCha input
+        const x = getExports();
+        const subkey = deriveSubkey(x, streamKey, nonce);
+        wipe(streamKey);
+        return { bytes: subkey };
+    },
+    sealChunk(keys, counterNonce, chunk, aad) {
+        const x = getExports();
+        const { ciphertext, tag } = aeadEncrypt(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;
+    },
+    openChunk(keys, counterNonce, chunk, aad) {
+        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 aeadDecrypt(x, keys.bytes, counterNonce, ct, tag, aad ?? new Uint8Array(0), 'xchacha20-poly1305');
+    },
+    wipeKeys(keys) {
+        wipe(keys.bytes);
+    },
+    createPoolWorker() {
+        return new Worker(new URL('./pool-worker.js', import.meta.url), { type: 'module' });
+    },
+};

package/dist/chacha20/embedded.d.ts

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

package/dist/chacha20/embedded.js

@@ -0,0 +1,27 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/chacha20/embedded.ts
+//
+// Exports the gzip+base64 chacha20 WASM blob for use as a WasmSource.
+// This is the only file in the chacha20 subpath that references the embedded blob.
+// Import via `leviathan-crypto/chacha20/embedded`.
+export { WASM_GZ_BASE64 as chacha20Wasm } from '../embedded/chacha20.js';

package/dist/chacha20/index.d.ts

@@ -1,5 +1,8 @@
-import type { Mode, InitOpts } from '../init.js';
-export declare function chacha20Init(mode?: Mode, opts?: InitOpts): Promise<void>;
+import type { WasmSource } from '../wasm-source.js';
+import { AuthenticationError } from '../errors.js';
+export { AuthenticationError };
+export declare function chacha20Init(source: WasmSource): Promise<void>;
+export type { WasmSource };
 export declare class ChaCha20 {
     private readonly x;
     constructor();
@@ -18,17 +21,22 @@ export declare class Poly1305 {
 /**
  * ChaCha20-Poly1305 AEAD (RFC 8439 §2.8).
  *
+ * `encrypt()` returns ciphertext || tag(16) as a single Uint8Array.
+ * `decrypt()` accepts the same combined format and splits internally.
+ *
+ * Single-use encrypt guard: `encrypt()` may only be called once per instance.
+ * Create a new instance for each encryption to prevent nonce reuse.
+ *
  * `decrypt()` uses constant-time tag comparison — XOR-accumulate pattern,
  * no early return on mismatch. Plaintext is never returned on failure.
  */
 export declare class ChaCha20Poly1305 {
     private readonly x;
+    private _used;
     constructor();
-    encrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): {
-        ciphertext: Uint8Array;
-        tag: Uint8Array;
-    };
-    decrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, tag: Uint8Array, aad?: Uint8Array): Uint8Array;
+    encrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    decrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, // ciphertext || tag(16) combined
+    aad?: Uint8Array): Uint8Array;
     dispose(): void;
 }
 /**
@@ -37,13 +45,18 @@ export declare class ChaCha20Poly1305 {
  * Recommended authenticated encryption primitive for most use cases.
  * Uses a 24-byte nonce — safe for random generation via crypto.getRandomValues.
  *
+ * Single-use encrypt guard: `encrypt()` may only be called once per instance.
+ * Create a new instance for each encryption to prevent nonce reuse.
+ *
  * `decrypt()` constant-time guarantee is inherited from the inner AEAD path.
  */
 export declare class XChaCha20Poly1305 {
     private readonly x;
+    private _used;
     constructor();
     encrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
     decrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
     dispose(): void;
 }
+export { XChaCha20Cipher } from './cipher-suite.js';
 export declare function _chachaReady(): boolean;

package/dist/chacha20/index.js

@@ -22,13 +22,13 @@
 // src/ts/chacha20/index.ts
 //
 // Public API classes for the ChaCha20 WASM module.
-// Uses the init() module cache — call init('chacha20') before constructing.
+// Uses the init() module cache — call chacha20Init(source) before constructing.
 import { getInstance, initModule } from '../init.js';
 import { aeadEncrypt, aeadDecrypt, xcEncrypt, xcDecrypt } from './ops.js';
-import { hasSIMD } from '../utils.js';
-const _embedded = () => import('../embedded/chacha20.js').then(m => m.WASM_BASE64);
-export async function chacha20Init(mode = 'embedded', opts) {
-    return initModule('chacha20', _embedded, mode, opts);
+import { AuthenticationError } from '../errors.js';
+export { AuthenticationError };
+export async function chacha20Init(source) {
+    return initModule('chacha20', source);
 }
 function getExports() {
     return getInstance('chacha20').exports;
@@ -58,8 +58,7 @@ export class ChaCha20 {
         const ptOff = this.x.getChunkPtOffset();
         const ctOff = this.x.getChunkCtOffset();
         mem.set(chunk, ptOff);
-        const fn = hasSIMD() ? this.x.chachaEncryptChunk_simd : this.x.chachaEncryptChunk;
-        fn(chunk.length);
+        this.x.chachaEncryptChunk_simd(chunk.length);
         return mem.slice(ctOff, ctOff + chunk.length);
     }
     beginDecrypt(key, nonce) {
@@ -105,29 +104,47 @@ export class Poly1305 {
 /**
  * ChaCha20-Poly1305 AEAD (RFC 8439 §2.8).
  *
+ * `encrypt()` returns ciphertext || tag(16) as a single Uint8Array.
+ * `decrypt()` accepts the same combined format and splits internally.
+ *
+ * Single-use encrypt guard: `encrypt()` may only be called once per instance.
+ * Create a new instance for each encryption to prevent nonce reuse.
+ *
  * `decrypt()` uses constant-time tag comparison — XOR-accumulate pattern,
  * no early return on mismatch. Plaintext is never returned on failure.
  */
 export class ChaCha20Poly1305 {
     x;
+    _used = false;
     constructor() {
         this.x = getExports();
     }
     encrypt(key, nonce, plaintext, aad = new Uint8Array(0)) {
+        if (this._used)
+            throw new Error('leviathan-crypto: encrypt() already called on this instance. '
+                + 'Create a new instance for each encryption to prevent nonce reuse.');
         if (key.length !== 32)
             throw new RangeError(`key must be 32 bytes (got ${key.length})`);
         if (nonce.length !== 12)
             throw new RangeError(`nonce must be 12 bytes (got ${nonce.length})`);
-        return aeadEncrypt(this.x, key, nonce, plaintext, aad);
-    }
-    decrypt(key, nonce, ciphertext, tag, aad = new Uint8Array(0)) {
+        const { ciphertext, tag } = aeadEncrypt(this.x, key, nonce, plaintext, aad);
+        this._used = true;
+        const out = new Uint8Array(ciphertext.length + 16);
+        out.set(ciphertext);
+        out.set(tag, ciphertext.length);
+        return out;
+    }
+    decrypt(key, nonce, ciphertext, // ciphertext || tag(16) combined
+    aad = new Uint8Array(0)) {
         if (key.length !== 32)
             throw new RangeError(`key must be 32 bytes (got ${key.length})`);
         if (nonce.length !== 12)
             throw new RangeError(`nonce must be 12 bytes (got ${nonce.length})`);
-        if (tag.length !== 16)
-            throw new RangeError(`tag must be 16 bytes (got ${tag.length})`);
-        return aeadDecrypt(this.x, key, nonce, ciphertext, tag, aad);
+        if (ciphertext.length < 16)
+            throw new RangeError(`ciphertext too short — must include 16-byte tag (got ${ciphertext.length})`);
+        const ct = ciphertext.subarray(0, ciphertext.length - 16);
+        const tag = ciphertext.subarray(ciphertext.length - 16);
+        return aeadDecrypt(this.x, key, nonce, ct, tag, aad);
     }
     dispose() {
         this.x.wipeBuffers();
@@ -140,19 +157,28 @@ export class ChaCha20Poly1305 {
  * Recommended authenticated encryption primitive for most use cases.
  * Uses a 24-byte nonce — safe for random generation via crypto.getRandomValues.
  *
+ * Single-use encrypt guard: `encrypt()` may only be called once per instance.
+ * Create a new instance for each encryption to prevent nonce reuse.
+ *
  * `decrypt()` constant-time guarantee is inherited from the inner AEAD path.
  */
 export class XChaCha20Poly1305 {
     x;
+    _used = false;
     constructor() {
         this.x = getExports();
     }
     encrypt(key, nonce, plaintext, aad = new Uint8Array(0)) {
+        if (this._used)
+            throw new Error('leviathan-crypto: encrypt() already called on this instance. '
+                + 'Create a new instance for each encryption to prevent nonce reuse.');
         if (key.length !== 32)
             throw new RangeError(`key must be 32 bytes (got ${key.length})`);
         if (nonce.length !== 24)
             throw new RangeError(`XChaCha20 nonce must be 24 bytes (got ${nonce.length})`);
-        return xcEncrypt(this.x, key, nonce, plaintext, aad);
+        const result = xcEncrypt(this.x, key, nonce, plaintext, aad);
+        this._used = true;
+        return result;
     }
     decrypt(key, nonce, ciphertext, aad = new Uint8Array(0)) {
         if (key.length !== 32)
@@ -167,6 +193,7 @@ export class XChaCha20Poly1305 {
         this.x.wipeBuffers();
     }
 }
+export { XChaCha20Cipher } from './cipher-suite.js';
 // ── Ready check ──────────────────────────────────────────────────────────────
 export function _chachaReady() {
     try {

package/dist/chacha20/ops.d.ts

@@ -5,7 +5,7 @@ export declare function aeadEncrypt(x: ChaChaExports, key: Uint8Array, nonce: Ui
     tag: Uint8Array;
 };
 /** ChaCha20-Poly1305 AEAD decrypt (RFC 8439 §2.8). Constant-time tag comparison. */
-export declare function aeadDecrypt(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, tag: Uint8Array, aad: Uint8Array): Uint8Array;
+export declare function aeadDecrypt(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, tag: Uint8Array, aad: Uint8Array, cipherName?: string): Uint8Array;
 /** HChaCha20 subkey derivation — first 16 bytes of nonce. */
 export declare function deriveSubkey(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array): Uint8Array;
 /** Build inner 12-byte nonce from bytes 16–23 of XChaCha nonce. */

package/dist/chacha20/ops.js

@@ -4,6 +4,7 @@
 // ChaChaExports explicitly. Used by both the class wrappers (index.ts)
 // and the pool worker (pool.worker.ts), eliminating duplication.
 import { constantTimeEqual } from '../utils.js';
+import { AuthenticationError } from '../errors.js';
 // ── Module-private helpers ───────────────────────────────────────────────────
 function polyFeed(x, data) {
     if (data.length === 0)
@@ -20,16 +21,14 @@ function polyFeed(x, data) {
 }
 function lenBlock(aadLen, ctLen) {
     const b = new Uint8Array(16);
-    let n = aadLen;
-    for (let i = 0; i < 4; i++) {
-        b[i] = n & 0xff;
-        n >>>= 8;
-    }
-    n = ctLen;
-    for (let i = 0; i < 4; i++) {
-        b[8 + i] = n & 0xff;
-        n >>>= 8;
-    }
+    const dv = new DataView(b.buffer);
+    // RFC 8439 §2.8 — 64-bit LE lengths.
+    // JS numbers are f64 — write low 32 bits directly, high bits via
+    // Math.floor(n / 2^32). Safe for n ≤ Number.MAX_SAFE_INTEGER.
+    dv.setUint32(0, aadLen >>> 0, true);
+    dv.setUint32(4, Math.floor(aadLen / 0x100000000) >>> 0, true);
+    dv.setUint32(8, ctLen >>> 0, true);
+    dv.setUint32(12, Math.floor(ctLen / 0x100000000) >>> 0, true);
     return b;
 }
 // ── Inner AEAD (12-byte nonce) ───────────────────────────────────────────────
@@ -42,7 +41,6 @@ export function aeadEncrypt(x, key, nonce, plaintext, aad) {
     // Step 1: Generate Poly1305 one-time key at counter=0 (RFC 8439 §2.6)
     mem.set(key, x.getKeyOffset());
     mem.set(nonce, x.getChachaNonceOffset());
-    x.chachaSetCounter(1);
     x.chachaLoadKey();
     x.chachaGenPolyKey();
     // Step 2: Initialise Poly1305
@@ -57,7 +55,7 @@ export function aeadEncrypt(x, key, nonce, plaintext, aad) {
     x.chachaLoadKey();
     // Step 5: Encrypt
     mem.set(plaintext, x.getChunkPtOffset());
-    x.chachaEncryptChunk(plaintext.length);
+    x.chachaEncryptChunk_simd(plaintext.length);
     const ctOff = x.getChunkCtOffset();
     const ciphertext = new Uint8Array(x.memory.buffer).slice(ctOff, ctOff + plaintext.length);
     // Step 6: MAC ciphertext + pad
@@ -74,7 +72,7 @@ export function aeadEncrypt(x, key, nonce, plaintext, aad) {
     return { ciphertext, tag };
 }
 /** ChaCha20-Poly1305 AEAD decrypt (RFC 8439 §2.8). Constant-time tag comparison. */
-export function aeadDecrypt(x, key, nonce, ciphertext, tag, aad) {
+export function aeadDecrypt(x, key, nonce, ciphertext, tag, aad, cipherName = 'chacha20-poly1305') {
     const maxChunk = x.getChunkSize();
     if (ciphertext.length > maxChunk)
         throw new RangeError(`ciphertext exceeds ${maxChunk} bytes — split into smaller chunks`);
@@ -82,7 +80,6 @@ export function aeadDecrypt(x, key, nonce, ciphertext, tag, aad) {
     // Compute expected tag
     mem.set(key, x.getKeyOffset());
     mem.set(nonce, x.getChachaNonceOffset());
-    x.chachaSetCounter(1);
     x.chachaLoadKey();
     x.chachaGenPolyKey();
     x.polyInit();
@@ -99,13 +96,17 @@ export function aeadDecrypt(x, key, nonce, ciphertext, tag, aad) {
     // Constant-time tag comparison
     const tagOff = x.getPolyTagOffset();
     const expectedTag = new Uint8Array(x.memory.buffer).slice(tagOff, tagOff + 16);
-    if (!constantTimeEqual(expectedTag, tag))
-        throw new Error('ChaCha20Poly1305: authentication failed');
+    if (!constantTimeEqual(expectedTag, tag)) {
+        // Wipe the full chunk output buffer — defense-in-depth before throwing
+        const ctOff = x.getChunkCtOffset();
+        mem.fill(0, ctOff, ctOff + maxChunk);
+        throw new AuthenticationError(cipherName);
+    }
     // Decrypt only after authentication succeeds
     x.chachaSetCounter(1);
     x.chachaLoadKey();
     new Uint8Array(x.memory.buffer).set(ciphertext, x.getChunkPtOffset());
-    x.chachaEncryptChunk(ciphertext.length);
+    x.chachaEncryptChunk_simd(ciphertext.length);
     const ptOff = x.getChunkCtOffset();
     return new Uint8Array(x.memory.buffer).slice(ptOff, ptOff + ciphertext.length);
 }
@@ -142,5 +143,5 @@ export function xcDecrypt(x, key, nonce, ciphertext, aad) {
     const tag = ciphertext.subarray(ciphertext.length - 16);
     const subkey = deriveSubkey(x, key, nonce);
     const inner = innerNonce(nonce);
-    return aeadDecrypt(x, subkey, inner, ct, tag, aad);
+    return aeadDecrypt(x, subkey, inner, ct, tag, aad, 'xchacha20-poly1305');
 }