leviathan-crypto 2.0.1 → 2.1.0

package/dist/chacha20/index.d.ts

@@ -1,21 +1,72 @@
 import type { WasmSource } from '../wasm-source.js';
 import { AuthenticationError } from '../errors.js';
 export { AuthenticationError };
+/**
+ * Load and initialise the ChaCha20 WASM module from `source`.
+ * Must be called before constructing any ChaCha20 class.
+ * @param source  WASM binary — gzip+base64 string, URL, ArrayBuffer, Uint8Array,
+ *                pre-compiled WebAssembly.Module, Response, or Promise<Response>
+ */
 export declare function chacha20Init(source: WasmSource): Promise<void>;
 export type { WasmSource };
+/**
+ * Raw ChaCha20 stream cipher (RFC 8439 §2.4).
+ *
+ * Holds exclusive access to the `chacha20` WASM module from construction
+ * until `dispose()`. Constructing a second ChaCha20 or any other chacha20
+ * user while this instance is live throws. Call `dispose()` when done.
+ */
 export declare class ChaCha20 {
     private readonly x;
+    private _tok;
     constructor();
+    /**
+     * Load key and nonce into WASM state and set the block counter to 1.
+     * Must be called before each message (RFC 8439 §2.4).
+     * @param key    32 bytes
+     * @param nonce  12 bytes — must be unique per (key, message)
+     */
     beginEncrypt(key: Uint8Array, nonce: Uint8Array): void;
+    /**
+     * XOR `chunk` with the next keystream block(s). Counter advances automatically.
+     * @param chunk  Plaintext chunk — must not exceed WASM CHUNK_SIZE
+     * @returns      Ciphertext of the same length
+     */
     encryptChunk(chunk: Uint8Array): Uint8Array;
+    /**
+     * Alias for `beginEncrypt` — ChaCha20 is a stream cipher (symmetric).
+     * @param key    32 bytes
+     * @param nonce  12 bytes — must match the value used to encrypt
+     */
     beginDecrypt(key: Uint8Array, nonce: Uint8Array): void;
+    /**
+     * Alias for `encryptChunk` — ChaCha20 is a stream cipher (symmetric).
+     * @param chunk  Ciphertext chunk
+     * @returns      Plaintext of the same length
+     */
     decryptChunk(chunk: Uint8Array): Uint8Array;
+    /** Wipe WASM state and release exclusive module access. Idempotent. */
     dispose(): void;
 }
+/**
+ * Poly1305 one-time MAC (RFC 8439 §2.5).
+ *
+ * Atomic (stateless) class: each `mac()` call is independent.
+ * The key must never be reused across messages. For most use cases, prefer
+ * `ChaCha20Poly1305` or `XChaCha20Poly1305` which manage the one-time key
+ * automatically.
+ */
 export declare class Poly1305 {
     private readonly x;
     constructor();
+    /**
+     * Compute a 16-byte Poly1305 MAC for `msg` using `key`.
+     * @param key  32-byte one-time key — must not be reused across messages
+     * @param msg  Message to authenticate
+     * @returns    16-byte Poly1305 tag
+     */
     mac(key: Uint8Array, msg: Uint8Array): Uint8Array;
+    /** Wipe WASM MAC state. */
     dispose(): void;
 }
 /**
@@ -34,9 +85,31 @@ export declare class ChaCha20Poly1305 {
     private readonly x;
     private _used;
     constructor();
+    /**
+     * Encrypt and authenticate `plaintext` with ChaCha20-Poly1305 (RFC 8439 §2.8).
+     *
+     * **Single-use guard:** `encrypt()` may only be called once per instance.
+     * Any throw — including validation errors — permanently locks this instance.
+     * Always create a new `ChaCha20Poly1305` per message.
+     * @param key        32 bytes
+     * @param nonce      12 bytes — must be unique per (key, message)
+     * @param plaintext  Data to encrypt
+     * @param aad        Additional authenticated data (optional)
+     * @returns          Ciphertext || 16-byte Poly1305 tag
+     */
     encrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    /**
+     * Verify and decrypt a ChaCha20-Poly1305 ciphertext (RFC 8439 §2.8).
+     * Throws `AuthenticationError` if the tag does not match.
+     * @param key         32 bytes
+     * @param nonce       12 bytes — must match the value used to encrypt
+     * @param ciphertext  Ciphertext || 16-byte tag (combined format from `encrypt`)
+     * @param aad         Additional authenticated data (optional)
+     * @returns           Plaintext
+     */
     decrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, // ciphertext || tag(16) combined
     aad?: Uint8Array): Uint8Array;
+    /** Wipe WASM cipher and MAC state. */
     dispose(): void;
 }
 /**
@@ -54,9 +127,32 @@ export declare class XChaCha20Poly1305 {
     private readonly x;
     private _used;
     constructor();
+    /**
+     * Encrypt and authenticate `plaintext` with XChaCha20-Poly1305
+     * (draft-irtf-cfrg-xchacha). Recommended for general-purpose AEAD.
+     *
+     * **Single-use guard:** `encrypt()` may only be called once per instance.
+     * Any throw — including validation errors — permanently locks this instance.
+     * Always create a new `XChaCha20Poly1305` per message to prevent nonce reuse.
+     * @param key        32 bytes
+     * @param nonce      24 bytes — safe to generate randomly via `randomBytes(24)`
+     * @param plaintext  Data to encrypt
+     * @param aad        Additional authenticated data (optional)
+     * @returns          Ciphertext || 16-byte Poly1305 tag
+     */
     encrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    /**
+     * Verify and decrypt an XChaCha20-Poly1305 ciphertext.
+     * Throws `AuthenticationError` if the tag does not match.
+     * @param key         32 bytes
+     * @param nonce       24 bytes — must match the value used to encrypt
+     * @param ciphertext  Ciphertext || 16-byte tag (combined format from `encrypt`)
+     * @param aad         Additional authenticated data (optional)
+     * @returns           Plaintext
+     */
     decrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    /** Wipe WASM cipher and MAC state. */
     dispose(): void;
 }
 export { XChaCha20Cipher } from './cipher-suite.js';
-export declare function _chachaReady(): boolean;
+export { ChaCha20Generator } from './generator.js';

package/dist/chacha20/index.js

@@ -23,23 +23,47 @@
 //
 // Public API classes for the ChaCha20 WASM module.
 // Uses the init() module cache — call chacha20Init(source) before constructing.
-import { getInstance, initModule } from '../init.js';
+import { getInstance, initModule, _acquireModule, _releaseModule, _assertNotOwned } from '../init.js';
 import { aeadEncrypt, aeadDecrypt, xcEncrypt, xcDecrypt } from './ops.js';
 import { AuthenticationError } from '../errors.js';
 export { AuthenticationError };
+/**
+ * Load and initialise the ChaCha20 WASM module from `source`.
+ * Must be called before constructing any ChaCha20 class.
+ * @param source  WASM binary — gzip+base64 string, URL, ArrayBuffer, Uint8Array,
+ *                pre-compiled WebAssembly.Module, Response, or Promise<Response>
+ */
 export async function chacha20Init(source) {
     return initModule('chacha20', source);
 }
+/** Returns the raw chacha20 WASM export object. @internal */
 function getExports() {
     return getInstance('chacha20').exports;
 }
-// ── ChaCha20 ──────────────────────────────────────────────────────────────────
+// ── ChaCha20 ────────────────────────────────────────────────────────────────
+/**
+ * Raw ChaCha20 stream cipher (RFC 8439 §2.4).
+ *
+ * Holds exclusive access to the `chacha20` WASM module from construction
+ * until `dispose()`. Constructing a second ChaCha20 or any other chacha20
+ * user while this instance is live throws. Call `dispose()` when done.
+ */
 export class ChaCha20 {
     x;
+    _tok;
     constructor() {
         this.x = getExports();
+        this._tok = _acquireModule('chacha20');
     }
+    /**
+     * Load key and nonce into WASM state and set the block counter to 1.
+     * Must be called before each message (RFC 8439 §2.4).
+     * @param key    32 bytes
+     * @param nonce  12 bytes — must be unique per (key, message)
+     */
     beginEncrypt(key, nonce) {
+        if (this._tok === undefined)
+            throw new Error('ChaCha20: instance has been disposed');
         if (key.length !== 32)
             throw new RangeError(`ChaCha20 key must be 32 bytes (got ${key.length})`);
         if (nonce.length !== 12)
@@ -50,7 +74,14 @@ export class ChaCha20 {
         this.x.chachaSetCounter(1);
         this.x.chachaLoadKey();
     }
+    /**
+     * XOR `chunk` with the next keystream block(s). Counter advances automatically.
+     * @param chunk  Plaintext chunk — must not exceed WASM CHUNK_SIZE
+     * @returns      Ciphertext of the same length
+     */
     encryptChunk(chunk) {
+        if (this._tok === undefined)
+            throw new Error('ChaCha20: instance has been disposed');
         const maxChunk = this.x.getChunkSize();
         if (chunk.length > maxChunk)
             throw new RangeError(`chunk exceeds maximum size of ${maxChunk} bytes — split into smaller chunks`);
@@ -61,23 +92,57 @@ export class ChaCha20 {
         this.x.chachaEncryptChunk_simd(chunk.length);
         return mem.slice(ctOff, ctOff + chunk.length);
     }
+    /**
+     * Alias for `beginEncrypt` — ChaCha20 is a stream cipher (symmetric).
+     * @param key    32 bytes
+     * @param nonce  12 bytes — must match the value used to encrypt
+     */
     beginDecrypt(key, nonce) {
         this.beginEncrypt(key, nonce);
     }
+    /**
+     * Alias for `encryptChunk` — ChaCha20 is a stream cipher (symmetric).
+     * @param chunk  Ciphertext chunk
+     * @returns      Plaintext of the same length
+     */
     decryptChunk(chunk) {
         return this.encryptChunk(chunk);
     }
+    /** Wipe WASM state and release exclusive module access. Idempotent. */
     dispose() {
-        this.x.wipeBuffers();
+        if (this._tok === undefined)
+            return;
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('chacha20', this._tok);
+            this._tok = undefined;
+        }
     }
 }
-// ── Poly1305 ──────────────────────────────────────────────────────────────────
+// ── Poly1305 ────────────────────────────────────────────────────────────────
+/**
+ * Poly1305 one-time MAC (RFC 8439 §2.5).
+ *
+ * Atomic (stateless) class: each `mac()` call is independent.
+ * The key must never be reused across messages. For most use cases, prefer
+ * `ChaCha20Poly1305` or `XChaCha20Poly1305` which manage the one-time key
+ * automatically.
+ */
 export class Poly1305 {
     x;
     constructor() {
         this.x = getExports();
     }
+    /**
+     * Compute a 16-byte Poly1305 MAC for `msg` using `key`.
+     * @param key  32-byte one-time key — must not be reused across messages
+     * @param msg  Message to authenticate
+     * @returns    16-byte Poly1305 tag
+     */
     mac(key, msg) {
+        _assertNotOwned('chacha20');
         if (key.length !== 32)
             throw new RangeError(`Poly1305 key must be 32 bytes (got ${key.length})`);
         const mem = new Uint8Array(this.x.memory.buffer);
@@ -96,11 +161,13 @@ export class Poly1305 {
         this.x.polyFinal();
         return new Uint8Array(this.x.memory.buffer).slice(tagOff, tagOff + 16);
     }
+    /** Wipe WASM MAC state. */
     dispose() {
+        _assertNotOwned('chacha20');
         this.x.wipeBuffers();
     }
 }
-// ── ChaCha20Poly1305 ─────────────────────────────────────────────────────────
+// ── ChaCha20Poly1305 ────────────────────────────────────────────────────────
 /**
  * ChaCha20-Poly1305 AEAD (RFC 8439 §2.8).
  *
@@ -119,23 +186,48 @@ export class ChaCha20Poly1305 {
     constructor() {
         this.x = getExports();
     }
+    /**
+     * Encrypt and authenticate `plaintext` with ChaCha20-Poly1305 (RFC 8439 §2.8).
+     *
+     * **Single-use guard:** `encrypt()` may only be called once per instance.
+     * Any throw — including validation errors — permanently locks this instance.
+     * Always create a new `ChaCha20Poly1305` per message.
+     * @param key        32 bytes
+     * @param nonce      12 bytes — must be unique per (key, message)
+     * @param plaintext  Data to encrypt
+     * @param aad        Additional authenticated data (optional)
+     * @returns          Ciphertext || 16-byte Poly1305 tag
+     */
     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.');
+        // Strict single-use: lock FIRST, before anything else. Any subsequent
+        // throw — including validation errors — terminates the instance.
+        this._used = true;
+        _assertNotOwned('chacha20');
         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})`);
         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;
     }
+    /**
+     * Verify and decrypt a ChaCha20-Poly1305 ciphertext (RFC 8439 §2.8).
+     * Throws `AuthenticationError` if the tag does not match.
+     * @param key         32 bytes
+     * @param nonce       12 bytes — must match the value used to encrypt
+     * @param ciphertext  Ciphertext || 16-byte tag (combined format from `encrypt`)
+     * @param aad         Additional authenticated data (optional)
+     * @returns           Plaintext
+     */
     decrypt(key, nonce, ciphertext, // ciphertext || tag(16) combined
     aad = new Uint8Array(0)) {
+        _assertNotOwned('chacha20');
         if (key.length !== 32)
             throw new RangeError(`key must be 32 bytes (got ${key.length})`);
         if (nonce.length !== 12)
@@ -146,11 +238,13 @@ export class ChaCha20Poly1305 {
         const tag = ciphertext.subarray(ciphertext.length - 16);
         return aeadDecrypt(this.x, key, nonce, ct, tag, aad);
     }
+    /** Wipe WASM cipher and MAC state. */
     dispose() {
+        _assertNotOwned('chacha20');
         this.x.wipeBuffers();
     }
 }
-// ── XChaCha20Poly1305 ────────────────────────────────────────────────────────
+// ── XChaCha20Poly1305 ───────────────────────────────────────────────────────
 /**
  * XChaCha20-Poly1305 AEAD (IETF draft-irtf-cfrg-xchacha).
  *
@@ -168,19 +262,44 @@ export class XChaCha20Poly1305 {
     constructor() {
         this.x = getExports();
     }
+    /**
+     * Encrypt and authenticate `plaintext` with XChaCha20-Poly1305
+     * (draft-irtf-cfrg-xchacha). Recommended for general-purpose AEAD.
+     *
+     * **Single-use guard:** `encrypt()` may only be called once per instance.
+     * Any throw — including validation errors — permanently locks this instance.
+     * Always create a new `XChaCha20Poly1305` per message to prevent nonce reuse.
+     * @param key        32 bytes
+     * @param nonce      24 bytes — safe to generate randomly via `randomBytes(24)`
+     * @param plaintext  Data to encrypt
+     * @param aad        Additional authenticated data (optional)
+     * @returns          Ciphertext || 16-byte Poly1305 tag
+     */
     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.');
+        // Strict single-use: lock FIRST, before anything else. Any subsequent
+        // throw — including validation errors — terminates the instance.
+        this._used = true;
+        _assertNotOwned('chacha20');
         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})`);
-        const result = xcEncrypt(this.x, key, nonce, plaintext, aad);
-        this._used = true;
-        return result;
+        return xcEncrypt(this.x, key, nonce, plaintext, aad);
     }
+    /**
+     * Verify and decrypt an XChaCha20-Poly1305 ciphertext.
+     * Throws `AuthenticationError` if the tag does not match.
+     * @param key         32 bytes
+     * @param nonce       24 bytes — must match the value used to encrypt
+     * @param ciphertext  Ciphertext || 16-byte tag (combined format from `encrypt`)
+     * @param aad         Additional authenticated data (optional)
+     * @returns           Plaintext
+     */
     decrypt(key, nonce, ciphertext, aad = new Uint8Array(0)) {
+        _assertNotOwned('chacha20');
         if (key.length !== 32)
             throw new RangeError(`key must be 32 bytes (got ${key.length})`);
         if (nonce.length !== 24)
@@ -189,12 +308,21 @@ export class XChaCha20Poly1305 {
             throw new RangeError(`ciphertext too short — must include 16-byte tag (got ${ciphertext.length})`);
         return xcDecrypt(this.x, key, nonce, ciphertext, aad);
     }
+    /** Wipe WASM cipher and MAC state. */
     dispose() {
+        _assertNotOwned('chacha20');
         this.x.wipeBuffers();
     }
 }
 export { XChaCha20Cipher } from './cipher-suite.js';
-// ── Ready check ──────────────────────────────────────────────────────────────
+// ── ChaCha20Generator ───────────────────────────────────────────────────────
+export { ChaCha20Generator } from './generator.js';
+// ── Ready check ─────────────────────────────────────────────────────────────
+/**
+ * Returns `true` if the chacha20 WASM module has been initialised.
+ * Used by tests and internal guards; not part of the public API.
+ * @internal
+ */
 export function _chachaReady() {
     try {
         getInstance('chacha20');

package/dist/chacha20/ops.d.ts

@@ -1,16 +1,67 @@
 import type { ChaChaExports } from './types.js';
-/** ChaCha20-Poly1305 AEAD encrypt (RFC 8439 §2.8). */
+/**
+ * ChaCha20-Poly1305 AEAD encrypt (RFC 8439 §2.8).
+ * @param x          ChaCha20 WASM exports
+ * @param key        32-byte key
+ * @param nonce      12-byte nonce — must be unique per (key, message)
+ * @param plaintext  Data to encrypt (must be ≤ WASM CHUNK_SIZE)
+ * @param aad        Additional authenticated data
+ * @returns          `{ ciphertext, tag }` — tag is 16 bytes
+ */
 export declare function aeadEncrypt(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): {
     ciphertext: Uint8Array;
     tag: Uint8Array;
 };
-/** ChaCha20-Poly1305 AEAD decrypt (RFC 8439 §2.8). Constant-time tag comparison. */
+/**
+ * ChaCha20-Poly1305 AEAD decrypt with constant-time tag comparison (RFC 8439 §2.8).
+ * Throws `AuthenticationError` on tag mismatch; never returns plaintext on failure.
+ * @param x           ChaCha20 WASM exports
+ * @param key         32-byte key
+ * @param nonce       12-byte nonce — must match the value used to encrypt
+ * @param ciphertext  Ciphertext bytes (must be ≤ WASM CHUNK_SIZE)
+ * @param tag         16-byte Poly1305 tag
+ * @param aad         Additional authenticated data
+ * @param cipherName  Error label for `AuthenticationError` (default 'chacha20-poly1305')
+ * @returns           Plaintext
+ */
 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. */
+/**
+ * Derive a 32-byte HChaCha20 subkey from `key` and the first 16 bytes of `nonce`.
+ * Used as the inner key for XChaCha20-Poly1305 (draft-irtf-cfrg-xchacha §2.3).
+ * @param x      ChaCha20 WASM exports
+ * @param key    32-byte master key
+ * @param nonce  24-byte XChaCha20 nonce (only bytes 0–15 are used)
+ * @returns      32-byte HChaCha20 subkey
+ */
 export declare function deriveSubkey(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array): Uint8Array;
-/** Build inner 12-byte nonce from bytes 16–23 of XChaCha nonce. */
+/**
+ * Build the inner 12-byte ChaCha20 nonce for XChaCha20 from bytes 16–23 of the
+ * 24-byte XChaCha nonce (draft-irtf-cfrg-xchacha §2.3).
+ * @param nonce  24-byte XChaCha20 nonce
+ * @returns      12-byte inner nonce (bytes 0–3 are zero, bytes 4–11 are nonce[16:24])
+ */
 export declare function innerNonce(nonce: Uint8Array): Uint8Array;
-/** XChaCha20-Poly1305 encrypt → ciphertext || tag. */
+/**
+ * XChaCha20-Poly1305 encrypt (draft-irtf-cfrg-xchacha).
+ * Derives HChaCha20 subkey from `key` + nonce[0:16], then runs
+ * ChaCha20-Poly1305 with a 12-byte inner nonce (nonce[16:24]).
+ * @param x          ChaCha20 WASM exports
+ * @param key        32-byte key
+ * @param nonce      24-byte nonce
+ * @param plaintext  Data to encrypt
+ * @param aad        Additional authenticated data
+ * @returns          Ciphertext || 16-byte Poly1305 tag
+ */
 export declare function xcEncrypt(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Uint8Array;
-/** XChaCha20-Poly1305 decrypt → plaintext (throws on auth failure). */
+/**
+ * XChaCha20-Poly1305 decrypt (draft-irtf-cfrg-xchacha).
+ * Derives HChaCha20 subkey, verifies the Poly1305 tag, then decrypts.
+ * Throws `AuthenticationError` on tag mismatch.
+ * @param x           ChaCha20 WASM exports
+ * @param key         32-byte key
+ * @param nonce       24-byte nonce — must match the value used to encrypt
+ * @param ciphertext  Ciphertext || 16-byte tag (combined format from `xcEncrypt`)
+ * @param aad         Additional authenticated data
+ * @returns           Plaintext
+ */
 export declare function xcDecrypt(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array): Uint8Array;

package/dist/chacha20/ops.js

@@ -5,7 +5,14 @@
 // and the pool worker (pool.worker.ts), eliminating duplication.
 import { constantTimeEqual } from '../utils.js';
 import { AuthenticationError } from '../errors.js';
-// ── Module-private helpers ───────────────────────────────────────────────────
+// ── Module-private helpers ──────────────────────────────────────────────────
+/**
+ * Feed `data` into the active Poly1305 accumulator via the WASM message buffer.
+ * No-op when `data` is empty.
+ * @param x     ChaCha20 WASM exports
+ * @param data  Bytes to absorb
+ * @internal
+ */
 function polyFeed(x, data) {
     if (data.length === 0)
         return;
@@ -19,6 +26,14 @@ function polyFeed(x, data) {
         pos += chunk;
     }
 }
+/**
+ * Build the 16-byte Poly1305 length footer from AAD and ciphertext lengths.
+ * Both lengths are encoded as 64-bit little-endian integers (RFC 8439 §2.8).
+ * @param aadLen  AAD byte length
+ * @param ctLen   Ciphertext byte length
+ * @returns       16-byte length block
+ * @internal
+ */
 function lenBlock(aadLen, ctLen) {
     const b = new Uint8Array(16);
     const dv = new DataView(b.buffer);
@@ -31,8 +46,16 @@ function lenBlock(aadLen, ctLen) {
     dv.setUint32(12, Math.floor(ctLen / 0x100000000) >>> 0, true);
     return b;
 }
-// ── Inner AEAD (12-byte nonce) ───────────────────────────────────────────────
-/** ChaCha20-Poly1305 AEAD encrypt (RFC 8439 §2.8). */
+// ── Inner AEAD (12-byte nonce) ──────────────────────────────────────────────
+/**
+ * ChaCha20-Poly1305 AEAD encrypt (RFC 8439 §2.8).
+ * @param x          ChaCha20 WASM exports
+ * @param key        32-byte key
+ * @param nonce      12-byte nonce — must be unique per (key, message)
+ * @param plaintext  Data to encrypt (must be ≤ WASM CHUNK_SIZE)
+ * @param aad        Additional authenticated data
+ * @returns          `{ ciphertext, tag }` — tag is 16 bytes
+ */
 export function aeadEncrypt(x, key, nonce, plaintext, aad) {
     const maxChunk = x.getChunkSize();
     if (plaintext.length > maxChunk)
@@ -50,9 +73,13 @@ export function aeadEncrypt(x, key, nonce, plaintext, aad) {
     const aadPad = (16 - aad.length % 16) % 16;
     if (aadPad > 0)
         polyFeed(x, new Uint8Array(aadPad));
-    // Step 4: Re-init ChaCha20 at counter=1
+    // Step 4: Re-init ChaCha20 at counter=1.
+    // `chachaGenPolyKey` mutated CHACHA_STATE + 48 (the counter word) to 0 but
+    // left every other state word intact (constants, key, nonce). Writing
+    // counter=1 via `chachaSetCounter` restores the state for encryption —
+    // no second `chachaLoadKey()` is needed (the key/nonce buffers and the
+    // non-counter state words are already correct).
     x.chachaSetCounter(1);
-    x.chachaLoadKey();
     // Step 5: Encrypt
     mem.set(plaintext, x.getChunkPtOffset());
     x.chachaEncryptChunk_simd(plaintext.length);
@@ -71,7 +98,18 @@ export function aeadEncrypt(x, key, nonce, plaintext, aad) {
     const tag = new Uint8Array(x.memory.buffer).slice(tagOff, tagOff + 16);
     return { ciphertext, tag };
 }
-/** ChaCha20-Poly1305 AEAD decrypt (RFC 8439 §2.8). Constant-time tag comparison. */
+/**
+ * ChaCha20-Poly1305 AEAD decrypt with constant-time tag comparison (RFC 8439 §2.8).
+ * Throws `AuthenticationError` on tag mismatch; never returns plaintext on failure.
+ * @param x           ChaCha20 WASM exports
+ * @param key         32-byte key
+ * @param nonce       12-byte nonce — must match the value used to encrypt
+ * @param ciphertext  Ciphertext bytes (must be ≤ WASM CHUNK_SIZE)
+ * @param tag         16-byte Poly1305 tag
+ * @param aad         Additional authenticated data
+ * @param cipherName  Error label for `AuthenticationError` (default 'chacha20-poly1305')
+ * @returns           Plaintext
+ */
 export function aeadDecrypt(x, key, nonce, ciphertext, tag, aad, cipherName = 'chacha20-poly1305') {
     const maxChunk = x.getChunkSize();
     if (ciphertext.length > maxChunk)
@@ -97,9 +135,19 @@ export function aeadDecrypt(x, key, nonce, ciphertext, tag, aad, cipherName = 'c
     const tagOff = x.getPolyTagOffset();
     const expectedTag = new Uint8Array(x.memory.buffer).slice(tagOff, tagOff + 16);
     if (!constantTimeEqual(expectedTag, tag)) {
-        // Wipe the full chunk output buffer — defense-in-depth before throwing
+        // Wipe the full chunk output buffer — defense-in-depth before throwing.
         const ctOff = x.getChunkCtOffset();
         mem.fill(0, ctOff, ctOff + maxChunk);
+        // Also zero the 64-byte chacha block buffer — it holds keystream bytes
+        // generated by chachaGenPolyKey() that would otherwise persist until
+        // the next op or dispose().
+        const blockOff = x.getChachaBlockOffset();
+        mem.fill(0, blockOff, blockOff + 64);
+        // And the 32-byte Poly1305 one-time subkey copy at POLY_KEY_OFFSET.
+        // chachaGenPolyKey copies keystream[0..32] here; wiping CHACHA_BLOCK
+        // zeroes the source but not this copy.
+        const polyKeyOff = x.getPolyKeyOffset();
+        mem.fill(0, polyKeyOff, polyKeyOff + 32);
         throw new AuthenticationError(cipherName);
     }
     // Decrypt only after authentication succeeds
@@ -110,8 +158,15 @@ export function aeadDecrypt(x, key, nonce, ciphertext, tag, aad, cipherName = 'c
     const ptOff = x.getChunkCtOffset();
     return new Uint8Array(x.memory.buffer).slice(ptOff, ptOff + ciphertext.length);
 }
-// ── XChaCha20 helpers ────────────────────────────────────────────────────────
-/** HChaCha20 subkey derivation — first 16 bytes of nonce. */
+// ── XChaCha20 helpers ───────────────────────────────────────────────────────
+/**
+ * Derive a 32-byte HChaCha20 subkey from `key` and the first 16 bytes of `nonce`.
+ * Used as the inner key for XChaCha20-Poly1305 (draft-irtf-cfrg-xchacha §2.3).
+ * @param x      ChaCha20 WASM exports
+ * @param key    32-byte master key
+ * @param nonce  24-byte XChaCha20 nonce (only bytes 0–15 are used)
+ * @returns      32-byte HChaCha20 subkey
+ */
 export function deriveSubkey(x, key, nonce) {
     const mem = new Uint8Array(x.memory.buffer);
     mem.set(key, x.getKeyOffset());
@@ -120,14 +175,29 @@ export function deriveSubkey(x, key, nonce) {
     const off = x.getXChaChaSubkeyOffset();
     return new Uint8Array(x.memory.buffer).slice(off, off + 32);
 }
-/** Build inner 12-byte nonce from bytes 16–23 of XChaCha nonce. */
+/**
+ * Build the inner 12-byte ChaCha20 nonce for XChaCha20 from bytes 16–23 of the
+ * 24-byte XChaCha nonce (draft-irtf-cfrg-xchacha §2.3).
+ * @param nonce  24-byte XChaCha20 nonce
+ * @returns      12-byte inner nonce (bytes 0–3 are zero, bytes 4–11 are nonce[16:24])
+ */
 export function innerNonce(nonce) {
     const n = new Uint8Array(12);
     n.set(nonce.subarray(16, 24), 4);
     return n;
 }
-// ── Full XChaCha20-Poly1305 ──────────────────────────────────────────────────
-/** XChaCha20-Poly1305 encrypt → ciphertext || tag. */
+// ── Full XChaCha20-Poly1305 ─────────────────────────────────────────────────
+/**
+ * XChaCha20-Poly1305 encrypt (draft-irtf-cfrg-xchacha).
+ * Derives HChaCha20 subkey from `key` + nonce[0:16], then runs
+ * ChaCha20-Poly1305 with a 12-byte inner nonce (nonce[16:24]).
+ * @param x          ChaCha20 WASM exports
+ * @param key        32-byte key
+ * @param nonce      24-byte nonce
+ * @param plaintext  Data to encrypt
+ * @param aad        Additional authenticated data
+ * @returns          Ciphertext || 16-byte Poly1305 tag
+ */
 export function xcEncrypt(x, key, nonce, plaintext, aad) {
     const subkey = deriveSubkey(x, key, nonce);
     const inner = innerNonce(nonce);
@@ -137,7 +207,17 @@ export function xcEncrypt(x, key, nonce, plaintext, aad) {
     result.set(tag, ciphertext.length);
     return result;
 }
-/** XChaCha20-Poly1305 decrypt → plaintext (throws on auth failure). */
+/**
+ * XChaCha20-Poly1305 decrypt (draft-irtf-cfrg-xchacha).
+ * Derives HChaCha20 subkey, verifies the Poly1305 tag, then decrypts.
+ * Throws `AuthenticationError` on tag mismatch.
+ * @param x           ChaCha20 WASM exports
+ * @param key         32-byte key
+ * @param nonce       24-byte nonce — must match the value used to encrypt
+ * @param ciphertext  Ciphertext || 16-byte tag (combined format from `xcEncrypt`)
+ * @param aad         Additional authenticated data
+ * @returns           Plaintext
+ */
 export function xcDecrypt(x, key, nonce, ciphertext, aad) {
     const ct = ciphertext.subarray(0, ciphertext.length - 16);
     const tag = ciphertext.subarray(ciphertext.length - 16);