leviathan-crypto 2.0.1 → 3.0.0

package/dist/chacha20/index.d.ts

@@ -1,21 +1,73 @@
 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 };
+export { isInitialized } from '../init.js';
+/**
+ * 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;
 }
 /**
@@ -27,23 +79,45 @@ export declare class Poly1305 {
  * 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,
+ * `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 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;
 }
 /**
  * XChaCha20-Poly1305 AEAD (IETF draft-irtf-cfrg-xchacha).
  *
  * Recommended authenticated encryption primitive for most use cases.
- * Uses a 24-byte nonce — safe for random generation via crypto.getRandomValues.
+ * 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.
@@ -54,9 +128,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

@@ -22,24 +22,49 @@
 // src/ts/chacha20/index.ts
 //
 // Public API classes for the ChaCha20 WASM module.
-// Uses the init() module cache — call chacha20Init(source) before constructing.
-import { getInstance, initModule } from '../init.js';
+// Uses the init() module cache, call chacha20Init(source) before constructing.
+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);
 }
+export { isInitialized } from '../init.js';
+/** 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,10 +75,17 @@ 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`);
+            throw new RangeError(`chunk exceeds maximum size of ${maxChunk} bytes, split into smaller chunks`);
         const mem = new Uint8Array(this.x.memory.buffer);
         const ptOff = this.x.getChunkPtOffset();
         const ctOff = this.x.getChunkCtOffset();
@@ -61,23 +93,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 +162,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).
  *
@@ -110,7 +178,7 @@ export class Poly1305 {
  * 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,
+ * `decrypt()` uses constant-time tag comparison, XOR-accumulate pattern,
  * no early return on mismatch. Plaintext is never returned on failure.
  */
 export class ChaCha20Poly1305 {
@@ -119,43 +187,80 @@ 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;
+        try {
+            const { ciphertext, tag } = aeadEncrypt(this.x, key, nonce, plaintext, aad);
+            const out = new Uint8Array(ciphertext.length + 16);
+            out.set(ciphertext);
+            out.set(tag, ciphertext.length);
+            return out;
+        }
+        finally {
+            this.x.wipeBuffers();
+        }
     }
+    /**
+     * 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)
             throw new RangeError(`nonce must be 12 bytes (got ${nonce.length})`);
         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);
+            throw new RangeError(`ciphertext too short, must include 16-byte tag (got ${ciphertext.length})`);
+        try {
+            const ct = ciphertext.subarray(0, ciphertext.length - 16);
+            const tag = ciphertext.subarray(ciphertext.length - 16);
+            return aeadDecrypt(this.x, key, nonce, ct, tag, aad);
+        }
+        finally {
+            this.x.wipeBuffers();
+        }
     }
+    /** Wipe WASM cipher and MAC state. */
     dispose() {
+        _assertNotOwned('chacha20');
         this.x.wipeBuffers();
     }
 }
-// ── XChaCha20Poly1305 ────────────────────────────────────────────────────────
+// ── XChaCha20Poly1305 ───────────────────────────────────────────────────────
 /**
  * XChaCha20-Poly1305 AEAD (IETF draft-irtf-cfrg-xchacha).
  *
  * Recommended authenticated encryption primitive for most use cases.
- * Uses a 24-byte nonce — safe for random generation via crypto.getRandomValues.
+ * 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.
@@ -168,39 +273,68 @@ 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;
+        try {
+            return xcEncrypt(this.x, key, nonce, plaintext, aad);
+        }
+        finally {
+            this.x.wipeBuffers();
+        }
     }
+    /**
+     * 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)
             throw new RangeError(`XChaCha20 nonce must be 24 bytes (got ${nonce.length})`);
         if (ciphertext.length < 16)
-            throw new RangeError(`ciphertext too short — must include 16-byte tag (got ${ciphertext.length})`);
-        return xcDecrypt(this.x, key, nonce, ciphertext, aad);
+            throw new RangeError(`ciphertext too short, must include 16-byte tag (got ${ciphertext.length})`);
+        try {
+            return xcDecrypt(this.x, key, nonce, ciphertext, aad);
+        }
+        finally {
+            this.x.wipeBuffers();
+        }
     }
+    /** Wipe WASM cipher and MAC state. */
     dispose() {
+        _assertNotOwned('chacha20');
         this.x.wipeBuffers();
     }
 }
 export { XChaCha20Cipher } from './cipher-suite.js';
-// ── Ready check ──────────────────────────────────────────────────────────────
-export function _chachaReady() {
-    try {
-        getInstance('chacha20');
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+// ── ChaCha20Generator ───────────────────────────────────────────────────────
+export { ChaCha20Generator } from './generator.js';

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;