leviathan-crypto 2.1.0 → 3.0.0

package/dist/blake3/types.d.ts

@@ -0,0 +1,102 @@
+/** BLAKE3 WASM exports. */
+export interface Blake3Exports {
+    memory: WebAssembly.Memory;
+    getModuleId: () => number;
+    getMemoryPages: () => number;
+    getInputStagingOffset: () => number;
+    getOutputStagingOffset: () => number;
+    getCvOffset: () => number;
+    getMsgOffset: () => number;
+    getCounterOffset: () => number;
+    getBlockLenOffset: () => number;
+    getFlagsOffset: () => number;
+    getCompressOutOffset: () => number;
+    getKeyedKeyOffset: () => number;
+    getDeriveCvOffset: () => number;
+    getCompress4CvInOffset: () => number;
+    getCompress4MsgInOffset: () => number;
+    getCompress4CtrInOffset: () => number;
+    getCompress4OutOffset: () => number;
+    getCompress4BlenInOffset: () => number;
+    getCompress4FlagsInOffset: () => number;
+    getModeCvOffset: () => number;
+    FLAG_CHUNK_START: {
+        value: number;
+    };
+    FLAG_CHUNK_END: {
+        value: number;
+    };
+    FLAG_PARENT: {
+        value: number;
+    };
+    FLAG_ROOT: {
+        value: number;
+    };
+    FLAG_KEYED_HASH: {
+        value: number;
+    };
+    FLAG_DERIVE_KEY_CONTEXT: {
+        value: number;
+    };
+    FLAG_DERIVE_KEY_MATERIAL: {
+        value: number;
+    };
+    BLAKE3_IV0: {
+        value: number;
+    };
+    BLAKE3_IV1: {
+        value: number;
+    };
+    BLAKE3_IV2: {
+        value: number;
+    };
+    BLAKE3_IV3: {
+        value: number;
+    };
+    BLAKE3_IV4: {
+        value: number;
+    };
+    BLAKE3_IV5: {
+        value: number;
+    };
+    BLAKE3_IV6: {
+        value: number;
+    };
+    BLAKE3_IV7: {
+        value: number;
+    };
+    compress: (cvOff: number, blockOff: number, counterLo: number, counterHi: number, blockLen: number, flags: number, outOff: number) => void;
+    compress4: () => void;
+    chunkInit: (chunkIndex: bigint) => void;
+    chunkUpdate: (blockOff: number, blockLen: number) => void;
+    chunkFinalize: (outCvOff: number, isRootSoloChunk: number) => void;
+    treeInit: () => void;
+    treePushChunk: (chunkCvOff: number) => void;
+    treeFinalizeRoot: (outOff: number) => void;
+    hash: (inputOff: number, inputLen: number, outOff: number, outLen: number) => void;
+    hashKeyed: (keyOff: number, inputOff: number, inputLen: number, outOff: number, outLen: number) => void;
+    deriveKey: (contextOff: number, contextLen: number, materialOff: number, materialLen: number, outOff: number, outLen: number) => void;
+    squeezeXofBlock: (counterLo: number, counterHi: number, outOff: number) => void;
+    wipeBuffers: () => void;
+}
+/**
+ * BLAKE3 WASM internal test exports. NOT part of the consumer surface,
+ * NOT re-exported from `src/ts/blake3/index.ts`. Wired exclusively for
+ * the tree-internals test suite (`test/unit/blake3/blake3-tree-internals
+ * .test.ts`) and the Merkle-tree substrate
+ * (`src/ts/merkle/blake3-tree.ts`) which casts
+ * `Blake3Exports & Blake3TestExports` inside the merkle module.
+ *
+ * Tests obtain these via `test/unit/blake3/helpers.ts`, which casts the
+ * public `Blake3Exports` to `Blake3Exports & Blake3TestExports`. Consumer
+ * code never sees the `_test*` surface.
+ */
+export interface Blake3TestExports {
+    _testChunkCV: (inputOff: number, inputLen: number, chunkIndex: bigint, startCvOff: number, modeFlags: number, outCvOff: number) => void;
+    _testParentCV: (leftCvOff: number, rightCvOff: number, startCvOff: number, modeFlags: number, isRoot: number, outCvOff: number) => void;
+    _testDeriveContextCV: (contextOff: number, contextLen: number, outCcvOff: number) => void;
+    _getBatch4CallCount: () => number;
+    _resetBatch4CallCount: () => void;
+    _getParentBatch4CallCount: () => number;
+    _resetParentBatch4CallCount: () => void;
+}

package/dist/blake3/types.js

@@ -0,0 +1,31 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/blake3/types.ts
+//
+// BLAKE3 WASM exports interface. Mirrors the AssemblyScript surface in
+// `src/asm/blake3/index.ts`. The consumer-facing TS surface (BLAKE3,
+// BLAKE3Stream and the keyed_hash / derive_key variants) calls the
+// top-level `hash` / `hashKeyed` / `deriveKey` entry points. Lower-level
+// primitives (`compress`, flag constants, buffer accessors) are typed
+// here for completeness and so test code can drive each layer in
+// isolation if needed.
+export {};

package/dist/blake3/validate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * BLAKE3 §2.3 Modes: keyed_hash takes a 32-byte key. The key seeds the chunk
+ * machine in place of the BLAKE3 IV and every compress carries the
+ * KEYED_HASH flag. A key of any other length is a contract violation.
+ */
+export declare function validateKey(key: Uint8Array): void;
+/**
+ * BLAKE3 §2.3 Modes: derive_key takes a context string and produces a
+ * derived key. The context string is a domain separator and is
+ * conventionally a UTF-8 hardcoded application constant. An empty context
+ * defeats the domain separation §2.3 is designed to provide; reject it.
+ *
+ * Accepts a JS string (UTF-8 encoded here) or a Uint8Array (passed
+ * through). No upper cap on length.
+ */
+export declare function validateContext(context: string | Uint8Array): Uint8Array;
+/**
+ * BLAKE3 §2.6 XOF: default-length output is 32 bytes; the XOF can in principle
+ * produce up to 2^64 - 1 bytes. The one-shot path (BLAKE3.hash /
+ * BLAKE3KeyedHash.hash / BLAKE3DeriveKey.derive and the streaming
+ * finalize(outLen) counterparts) writes outLen bytes through a single
+ * WASM call sized by the OUTPUT_STAGING region, so the practical
+ * upper bound is `OUTPUT_STAGING_SIZE` (1024 bytes); larger consumers
+ * use `finalizeXof()` and stream from `BLAKE3OutputReader.read(n)`
+ * which squeezes 64 bytes at a time off the WASM-side root snapshot.
+ * This validator rejects nonsense (zero, negative, non-finite,
+ * non-integer); the one-shot wrappers enforce the per-call ceiling.
+ */
+export declare function validateOutputLen(outLen: number): void;

package/dist/blake3/validate.js

@@ -0,0 +1,80 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/blake3/validate.ts
+//
+// BLAKE3 caller-side input validation. Pure length / type checks, no
+// crypto. BLAKE3 is a hash family, not a signature scheme; rejected
+// inputs throw `RangeError` / `TypeError` (no `SigningError`).
+/**
+ * BLAKE3 §2.3 Modes: keyed_hash takes a 32-byte key. The key seeds the chunk
+ * machine in place of the BLAKE3 IV and every compress carries the
+ * KEYED_HASH flag. A key of any other length is a contract violation.
+ */
+export function validateKey(key) {
+    if (!(key instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: blake3 key must be a Uint8Array');
+    if (key.length !== 32)
+        throw new RangeError(`leviathan-crypto: blake3 key must be 32 bytes (got ${key.length})`);
+}
+/**
+ * BLAKE3 §2.3 Modes: derive_key takes a context string and produces a
+ * derived key. The context string is a domain separator and is
+ * conventionally a UTF-8 hardcoded application constant. An empty context
+ * defeats the domain separation §2.3 is designed to provide; reject it.
+ *
+ * Accepts a JS string (UTF-8 encoded here) or a Uint8Array (passed
+ * through). No upper cap on length.
+ */
+export function validateContext(context) {
+    let bytes;
+    if (typeof context === 'string') {
+        bytes = new TextEncoder().encode(context);
+    }
+    else if (context instanceof Uint8Array) {
+        bytes = context;
+    }
+    else {
+        throw new TypeError('leviathan-crypto: blake3 derive_key context must be a string or Uint8Array');
+    }
+    if (bytes.length === 0)
+        throw new RangeError('leviathan-crypto: blake3 derive_key context must be non-empty '
+            + '(empty context defeats §2.3 domain separation)');
+    return bytes;
+}
+/**
+ * BLAKE3 §2.6 XOF: default-length output is 32 bytes; the XOF can in principle
+ * produce up to 2^64 - 1 bytes. The one-shot path (BLAKE3.hash /
+ * BLAKE3KeyedHash.hash / BLAKE3DeriveKey.derive and the streaming
+ * finalize(outLen) counterparts) writes outLen bytes through a single
+ * WASM call sized by the OUTPUT_STAGING region, so the practical
+ * upper bound is `OUTPUT_STAGING_SIZE` (1024 bytes); larger consumers
+ * use `finalizeXof()` and stream from `BLAKE3OutputReader.read(n)`
+ * which squeezes 64 bytes at a time off the WASM-side root snapshot.
+ * This validator rejects nonsense (zero, negative, non-finite,
+ * non-integer); the one-shot wrappers enforce the per-call ceiling.
+ */
+export function validateOutputLen(outLen) {
+    if (typeof outLen !== 'number' || !Number.isFinite(outLen) || !Number.isInteger(outLen))
+        throw new RangeError(`leviathan-crypto: blake3 outLen must be a finite integer (got ${String(outLen)})`);
+    if (outLen < 1)
+        throw new RangeError(`leviathan-crypto: blake3 outLen must be >= 1 (got ${outLen})`);
+}

package/dist/chacha20/cipher-suite.js

@@ -21,14 +21,15 @@
 //
 // src/ts/chacha20/cipher-suite.ts
 //
-// XChaCha20Cipher — CipherSuite implementation for the STREAM construction.
+// XChaCha20Cipher, CipherSuite implementation for the STREAM construction.
 // HKDF-SHA-256 key derivation → HChaCha20 subkey → ChaCha20-Poly1305 per chunk.
 import { getInstance, _assertNotOwned } from '../init.js';
 import { HKDF_SHA256 } from '../sha2/index.js';
 import { aeadEncrypt, aeadDecrypt, deriveSubkey } from './ops.js';
-import { wipe, randomBytes } from '../utils.js';
+import { wipe, randomBytes, concat } from '../utils.js';
+import { HEADER_SIZE } from '../stream/constants.js';
 import { WORKER_SOURCE } from '../embedded/chacha20-pool-worker.js';
-const INFO = new TextEncoder().encode('xchacha20-sealstream-v2');
+const INFO = new TextEncoder().encode('xchacha20-sealstream-v3');
 /** Returns the raw chacha20 WASM export object. @internal */
 function getExports() {
     return getInstance('chacha20').exports;
@@ -44,11 +45,12 @@ function getExports() {
  * this object directly. Use `XChaCha20Cipher.keygen()` to generate a 32-byte key.
  */
 export const XChaCha20Cipher = {
-    formatEnum: 0x01,
+    formatEnum: 0x03,
     formatName: 'xchacha20',
-    hkdfInfo: 'xchacha20-sealstream-v2',
+    hkdfInfo: 'xchacha20-sealstream-v3',
     keySize: 32,
     kemCtSize: 0,
+    commitmentSize: 32,
     tagSize: 16,
     padded: false,
     wasmChunkSize: 65536, // src/asm/chacha20/buffers.ts CHUNK_SIZE
@@ -58,22 +60,50 @@ export const XChaCha20Cipher = {
         return randomBytes(32);
     },
     /**
-     * Derive a 32-byte HChaCha20 subkey from `masterKey` and `nonce` via
-     * HKDF-SHA-256 followed by HChaCha20 subkey derivation.
+     * Derive a 32-byte HChaCha20 subkey and a 32-byte key commitment from
+     * `masterKey` and `nonce` via HKDF-SHA-256 followed by HChaCha20 subkey
+     * derivation. The full 20-byte preamble header is appended to the HKDF
+     * info string, binding `formatEnum`, framed flag, nonce, and chunkSize
+     * into the derived material, header tampering causes derived keys to
+     * differ and AEAD fails on the first chunk.
+     *
+     * The 64-byte HKDF output is split: bytes 0..32 feed HChaCha20 subkey
+     * derivation, bytes 32..64 are the key commitment that ends up in the
+     * preamble. Verifying the commitment before any chunk is processed
+     * closes the Invisible Salamanders attack surface, Poly1305 alone is
+     * not key-committing, so without this an adversary with control over
+     * two master keys could craft a single ciphertext + tag that decrypts
+     * validly under both.
+     *
      * @param masterKey  32-byte master key
-     * @param nonce      Stream nonce (24 bytes minimum for XChaCha20 subkey derivation)
-     * @returns          `DerivedKeys` holding the 32-byte subkey
+     * @param nonce      Stream nonce (16 bytes, also used as HChaCha20 input)
+     * @param _kemCt     Unused for symmetric XChaCha20; KEM wrappers pass it through
+     * @param header     20-byte preamble header, required (throws otherwise)
+     * @returns          `DerivedKeys` holding the 32-byte HChaCha20 subkey and 32-byte commitment
      */
-    deriveKeys(masterKey, nonce, _kemCt) {
+    deriveKeys(masterKey, nonce, _kemCt, header) {
+        if (!header || header.length !== HEADER_SIZE)
+            throw new Error(`XChaCha20Cipher.deriveKeys: header binding required (got ${header?.length ?? 'undefined'} bytes)`);
         _assertNotOwned('chacha20');
         const hkdf = new HKDF_SHA256();
-        const streamKey = hkdf.derive(masterKey, nonce, INFO, 32);
-        hkdf.dispose();
-        // HChaCha20 subkey derivation — nonce[0:16] as XChaCha input
+        let okm;
+        try {
+            // INFO || header, binds formatEnum, framed flag, nonce, chunkSize into the KDF.
+            // Any header tampering produces different keys, AEAD fails on the first chunk.
+            const info = concat(INFO, header);
+            okm = hkdf.derive(masterKey, nonce, info, 64);
+        }
+        finally {
+            hkdf.dispose();
+        }
+        // Bytes 0..32: streamKey for HChaCha20 subkey derivation.
+        // Bytes 32..64: key commitment for the seal preamble.
+        const streamKey = okm.subarray(0, 32);
+        const commitment = okm.slice(32, 64); // independent backing, survives okm wipe
         const x = getExports();
         const subkey = deriveSubkey(x, streamKey, nonce);
-        wipe(streamKey);
-        return { bytes: subkey };
+        wipe(okm); // wipe both halves of okm; commitment is safe (independent backing)
+        return { bytes: subkey, commitment };
     },
     /**
      * Encrypt and authenticate one stream chunk with ChaCha20-Poly1305.
@@ -96,7 +126,7 @@ export const XChaCha20Cipher = {
     /**
      * Verify and decrypt one stream chunk. Throws `AuthenticationError` on tag mismatch.
      * @param keys         Derived keys from `deriveKeys`
-     * @param counterNonce 12-byte per-chunk nonce — must match the value used by `sealChunk`
+     * @param counterNonce 12-byte per-chunk nonce, must match the value used by `sealChunk`
      * @param chunk        Ciphertext || 16-byte Poly1305 tag
      * @param aad          Optional additional authenticated data
      * @returns            Plaintext
@@ -124,18 +154,10 @@ export const XChaCha20Cipher = {
      * @returns  Newly constructed `Worker` instance
      */
     createPoolWorker() {
-        // IIFE source is bundled at lib build time (scripts/embed-workers.ts).
-        // Avoids the syntactic `new Worker(new URL(..., import.meta.url))`
-        // pattern that triggers eager worker-chunk emission in Vite's
-        // transform hook (issue.md). Classic worker via blob URL —
-        // module workers fail on file:// in Chromium (issue2.md).
+        // See docs/architecture.md#pool-worker-spawn-pattern.
         const blob = new Blob([WORKER_SOURCE], { type: 'application/javascript' });
         const url = URL.createObjectURL(blob);
         const w = new Worker(url);
-        // Worker spec fetches the URL synchronously at construction. Revoke
-        // in a macrotask so the spawn completes first; releases the Blob
-        // (~5 KB per spawn × N workers) instead of leaking it for the
-        // document's lifetime.
         setTimeout(() => URL.revokeObjectURL(url), 0);
         return w;
     },

package/dist/chacha20/generator.d.ts

@@ -4,9 +4,9 @@ import type { Generator } from '../types.js';
  *
  * The 32-bit counter is read from `counter` as a little-endian u32. Each call
  * to `generate()` encrypts zero blocks to produce keystream output (RFC 8439 §2.3).
- * The nonce is fixed to zero — Fortuna's counter is the only varying input.
+ * The nonce is fixed to zero, Fortuna's counter is the only varying input.
  *
- * Pass to `Fortuna.create({ generator: ChaCha20Generator, ... })` — do not
+ * Pass to `Fortuna.create({ generator: ChaCha20Generator, ... })`, do not
  * call `generate()` directly outside of Fortuna.
  */
 export declare const ChaCha20Generator: Generator;

package/dist/chacha20/generator.js

@@ -21,7 +21,7 @@
 //
 // src/ts/chacha20/generator.ts
 //
-// RFC 8439 §2.3 — ChaCha20 block function as PRF
+// RFC 8439 §2.3, ChaCha20 block function as PRF
 // ChaCha20 counter-mode PRF for Fortuna's generator slot.
 //
 // Counter is treated as a 32-bit LE integer. Fortuna's 4-byte genCnt provides
@@ -32,9 +32,9 @@ import { _assertNotOwned, getInstance } from '../init.js';
  *
  * The 32-bit counter is read from `counter` as a little-endian u32. Each call
  * to `generate()` encrypts zero blocks to produce keystream output (RFC 8439 §2.3).
- * The nonce is fixed to zero — Fortuna's counter is the only varying input.
+ * The nonce is fixed to zero, Fortuna's counter is the only varying input.
  *
- * Pass to `Fortuna.create({ generator: ChaCha20Generator, ... })` — do not
+ * Pass to `Fortuna.create({ generator: ChaCha20Generator, ... })`, do not
  * call `generate()` directly outside of Fortuna.
  */
 export const ChaCha20Generator = {
@@ -62,7 +62,7 @@ export const ChaCha20Generator = {
         const mem = new Uint8Array(x.memory.buffer);
         try {
             mem.set(key, x.getKeyOffset());
-            // Fixed zero nonce — Fortuna's counter is the only varying input
+            // Fixed zero nonce, Fortuna's counter is the only varying input
             mem.fill(0, x.getChachaNonceOffset(), x.getChachaNonceOffset() + 12);
             x.chachaSetCounter(c);
             x.chachaLoadKey();

package/dist/chacha20/index.d.ts

@@ -4,11 +4,12 @@ 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,
+ * @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).
  *
@@ -24,23 +25,23 @@ export declare class 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)
+     * @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
+     * @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).
+     * Alias for `beginEncrypt`, ChaCha20 is a stream cipher (symmetric).
      * @param key    32 bytes
-     * @param nonce  12 bytes — must match the value used to encrypt
+     * @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).
+     * Alias for `encryptChunk`, ChaCha20 is a stream cipher (symmetric).
      * @param chunk  Ciphertext chunk
      * @returns      Plaintext of the same length
      */
@@ -61,7 +62,7 @@ export declare class Poly1305 {
     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 key  32-byte one-time key, must not be reused across messages
      * @param msg  Message to authenticate
      * @returns    16-byte Poly1305 tag
      */
@@ -78,7 +79,7 @@ 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 {
@@ -89,10 +90,10 @@ export declare class ChaCha20Poly1305 {
      * 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.
+     * 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 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
@@ -102,7 +103,7 @@ export declare class ChaCha20Poly1305 {
      * 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 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
@@ -116,7 +117,7 @@ export declare class ChaCha20Poly1305 {
  * 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.
@@ -132,10 +133,10 @@ export declare class XChaCha20Poly1305 {
      * (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.
+     * 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 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
@@ -145,7 +146,7 @@ export declare class XChaCha20Poly1305 {
      * 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 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