leviathan-crypto 1.0.0

package/SECURITY.md

@@ -0,0 +1,174 @@
+# Leviathan Crypto Library Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| v1.x    | ✓         |
+
+> [!NOTE]
+> v1.0.0 is the current stable release.
+> This table will be updated as new versions ship.
+
+## Security Posture
+
+leviathan-crypto 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),
+[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
+ported from an existing implementation — the specs are the source of truth.
+
+All implementations are verified against published known-answer test vectors
+from NIST, RFC appendices, NESSIE, and the Argon2 reference suite. Vectors
+are immutable: if an implementation produces incorrect output, the
+implementation is fixed — vectors are never adjusted to match code.
+
+### Side-Channel Resistance
+
+Serpent's S-boxes are implemented as Boolean gate circuits — no table
+lookups, no data-dependent memory access, no data-dependent branches. Every
+bit is processed unconditionally on every block. This is the most
+timing-safe cipher implementation approach available in a WASM runtime,
+where JIT optimisation can otherwise introduce observable timing variation.
+
+All security-sensitive comparisons (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.
+
+### WASM Execution Model
+
+All cryptographic computation runs in WebAssembly, isolated outside the
+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 — key material in the Serpent
+module cannot interact with memory in the SHA-3 module even in principle.
+
+### Cryptanalytic Review
+
+The security margin of Serpent-256 has been independently researched and
+documented. The best known attack on the full 32-round cipher — biclique
+cryptanalysis — achieves a complexity of 2²⁵⁵·¹⁹ with 2⁴ chosen
+ciphertexts. This provides less than one bit of advantage over exhaustive
+key search and has zero practical impact. Independent research conducted
+against this implementation improved on the published result by −0.20 bits
+through systematic parameter search, confirming no structural weakness
+beyond what the published literature describes.
+
+See: [`xero/BicliqueFinder/biclique_research.md`][biclique] and
+[`leviathan-crypto/wiki/serpent_audit`][serpent-audit] for the full
+analysis.
+
+### 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.
+
+### Dependency Management
+
+The library has _zero_ runtime JavaScript dependencies by design.
+`sideEffects: false` is enforced in `package.json`. Argon2id integration
+is documented as an optional external dependency.
+See:" [`leviathan-crypto/wiki/argon2id`][argon2id-wiki].
+
+Build toolchain dependencies are pinned with exact version locks in
+`bun.lock`. GitHub Actions workflows use SHA-pinned action references
+throughout with no floating tags. Supply chain integrity is treated as a
+first-class concern for a cryptography library.
+
+### Explicit Initialisation
+
+No class silently auto-initialises. The [`init()`][init] gate is mandatory and
+explicit, giving consumers full control over when WASM modules are loaded
+and ensuring no hidden initialisation costs or race conditions. Classes
+throw immediately if used before initialisation rather than failing
+silently.
+
+### Agentic Development Contracts
+
+All AI-assisted development on this repository operates under a strict
+agentic contract defined in [`AGENTS.md`][agents]. The contract enforces
+spec authority over planning documents, immutable test vectors, gate
+discipline before extending any test suite, independent algorithm
+derivation from published standards, and constant-time/wipe requirements
+for all security-sensitive code paths. Agents are explicitly prohibited
+from guessing cryptographic values or resolving spec ambiguities silently.
+
+The contract has been verified against Claude, GitHub Copilot (VS Code),
+OpenHands, Kilo Code, Cursor, Windsurf, and Aider. Configuration files for
+each are present in the repository and all route to [`AGENTS.md`][agents]
+as the single source of authority.
+
+---
+
+## Reporting a Vulnerability
+
+> [!IMPORTANT]
+> **_Please do not open a public issue for security vulnerabilities._**
+
+### Private Advisory (preferred)
+
+Use GitHub's private vulnerability reporting form:
+[https://github.com/xero/leviathan-crypto/security/advisories/new][advisory]
+
+This opens a private channel between you and the maintainer. You will
+receive a response ASAP. If the vulnerability is confirmed, a fix will be
+prioritised and a coordinated disclosure timeline agreed upon before any
+public advisory is published.
+
+### Direct Contact
+
+If you prefer to contact the maintainer directly:
+
+- **Email:** x﹫xero.style — PGP: [`0xAC1D0000`][pgp]
+- **Matrix:** x0﹫rx.haunted.computer
+
+> [!NOTE]
+> Encrypted communication is welcome and _preferred_ for sensitive reports.
+
+### Scope
+
+Reports are in scope for:
+
+- Correctness bugs in cryptographic implementations (wrong output against
+  test vectors)
+- Side-channel vulnerabilities (timing, memory access patterns)
+- Authentication bypass in AEAD constructions
+- Key material exposure or improper zeroing
+- Supply chain issues (dependency tampering, workflow compromise)
+
+Out of scope:
+
+- Unpatched vulnerabilities in third-party packages not maintained by this
+  project
+- Issues requiring physical access to the user's device
+
+---
+
+[fips180]:       https://csrc.nist.gov/publications/detail/fips/180/4/final
+[fips202]:       https://csrc.nist.gov/publications/detail/fips/202/final
+[rfc8439]:       https://www.rfc-editor.org/rfc/rfc8439
+[rfc2104]:       https://www.rfc-editor.org/rfc/rfc2104
+[rfc5869]:       https://www.rfc-editor.org/rfc/rfc5869
+[serpent]:       https://www.cl.cam.ac.uk/~rja14/Papers/serpent.pdf
+[utils]:         https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal
+[biclique]:      https://github.com/xero/BicliqueFinder/blob/main/biclique-research.md
+[serpent-audit]: https://github.com/xero/leviathan-crypto/wiki/serpent_audit
+[argon2id-wiki]: https://github.com/xero/leviathan-crypto/wiki/argon2id
+[init]:          https://github.com/xero/leviathan-crypto/wiki/init
+[agents]:        https://github.com/xero/leviathan-crypto/blob/main/AGENTS.md
+[advisory]:      https://github.com/xero/leviathan-crypto/security/advisories/new
+[pgp]:           https://0w.nz/pgp.pub

package/dist/chacha20/index.d.ts

@@ -0,0 +1,49 @@
+import type { Mode, InitOpts } from '../init.js';
+export declare function chacha20Init(mode?: Mode, opts?: InitOpts): Promise<void>;
+export declare class ChaCha20 {
+    private readonly x;
+    constructor();
+    beginEncrypt(key: Uint8Array, nonce: Uint8Array): void;
+    encryptChunk(chunk: Uint8Array): Uint8Array;
+    beginDecrypt(key: Uint8Array, nonce: Uint8Array): void;
+    decryptChunk(chunk: Uint8Array): Uint8Array;
+    dispose(): void;
+}
+export declare class Poly1305 {
+    private readonly x;
+    constructor();
+    mac(key: Uint8Array, msg: Uint8Array): Uint8Array;
+    dispose(): void;
+}
+/**
+ * ChaCha20-Poly1305 AEAD (RFC 8439 §2.8).
+ *
+ * `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;
+    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;
+    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.
+ *
+ * `decrypt()` constant-time guarantee is inherited from the inner AEAD path.
+ */
+export declare class XChaCha20Poly1305 {
+    private readonly x;
+    constructor();
+    encrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    decrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    dispose(): void;
+}
+export declare function _chachaReady(): boolean;

package/dist/chacha20/index.js

@@ -0,0 +1,177 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/index.ts
+//
+// Public API classes for the ChaCha20 WASM module.
+// Uses the init() module cache — call init('chacha20') before constructing.
+import { getInstance, initModule } from '../init.js';
+import { aeadEncrypt, aeadDecrypt, xcEncrypt, xcDecrypt } from './ops.js';
+const _embedded = () => import('../embedded/chacha.js').then(m => m.WASM_BASE64);
+export async function chacha20Init(mode = 'embedded', opts) {
+    return initModule('chacha20', _embedded, mode, opts);
+}
+function getExports() {
+    return getInstance('chacha20').exports;
+}
+// ── ChaCha20 ──────────────────────────────────────────────────────────────────
+export class ChaCha20 {
+    x;
+    constructor() {
+        this.x = getExports();
+    }
+    beginEncrypt(key, nonce) {
+        if (key.length !== 32)
+            throw new RangeError(`ChaCha20 key must be 32 bytes (got ${key.length})`);
+        if (nonce.length !== 12)
+            throw new RangeError(`ChaCha20 nonce must be 12 bytes (got ${nonce.length})`);
+        const mem = new Uint8Array(this.x.memory.buffer);
+        mem.set(key, this.x.getKeyOffset());
+        mem.set(nonce, this.x.getChachaNonceOffset());
+        this.x.chachaSetCounter(1);
+        this.x.chachaLoadKey();
+    }
+    encryptChunk(chunk) {
+        const maxChunk = this.x.getChunkSize();
+        if (chunk.length > maxChunk)
+            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();
+        mem.set(chunk, ptOff);
+        this.x.chachaEncryptChunk(chunk.length);
+        return mem.slice(ctOff, ctOff + chunk.length);
+    }
+    beginDecrypt(key, nonce) {
+        this.beginEncrypt(key, nonce);
+    }
+    decryptChunk(chunk) {
+        return this.encryptChunk(chunk);
+    }
+    dispose() {
+        this.x.wipeBuffers();
+    }
+}
+// ── Poly1305 ──────────────────────────────────────────────────────────────────
+export class Poly1305 {
+    x;
+    constructor() {
+        this.x = getExports();
+    }
+    mac(key, msg) {
+        if (key.length !== 32)
+            throw new RangeError(`Poly1305 key must be 32 bytes (got ${key.length})`);
+        const mem = new Uint8Array(this.x.memory.buffer);
+        const keyOff = this.x.getPolyKeyOffset();
+        const msgOff = this.x.getPolyMsgOffset();
+        const tagOff = this.x.getPolyTagOffset();
+        mem.set(key, keyOff);
+        this.x.polyInit();
+        let pos = 0;
+        while (pos < msg.length) {
+            const chunk = Math.min(64, msg.length - pos);
+            mem.set(msg.subarray(pos, pos + chunk), msgOff);
+            this.x.polyUpdate(chunk);
+            pos += chunk;
+        }
+        this.x.polyFinal();
+        return new Uint8Array(this.x.memory.buffer).slice(tagOff, tagOff + 16);
+    }
+    dispose() {
+        this.x.wipeBuffers();
+    }
+}
+// ── ChaCha20Poly1305 ─────────────────────────────────────────────────────────
+/**
+ * ChaCha20-Poly1305 AEAD (RFC 8439 §2.8).
+ *
+ * `decrypt()` uses constant-time tag comparison — XOR-accumulate pattern,
+ * no early return on mismatch. Plaintext is never returned on failure.
+ */
+export class ChaCha20Poly1305 {
+    x;
+    constructor() {
+        this.x = getExports();
+    }
+    encrypt(key, nonce, plaintext, 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})`);
+        return aeadEncrypt(this.x, key, nonce, plaintext, aad);
+    }
+    decrypt(key, nonce, ciphertext, tag, 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);
+    }
+    dispose() {
+        this.x.wipeBuffers();
+    }
+}
+// ── 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.
+ *
+ * `decrypt()` constant-time guarantee is inherited from the inner AEAD path.
+ */
+export class XChaCha20Poly1305 {
+    x;
+    constructor() {
+        this.x = getExports();
+    }
+    encrypt(key, nonce, plaintext, aad = new Uint8Array(0)) {
+        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);
+    }
+    decrypt(key, nonce, ciphertext, aad = new Uint8Array(0)) {
+        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);
+    }
+    dispose() {
+        this.x.wipeBuffers();
+    }
+}
+// ── Ready check ──────────────────────────────────────────────────────────────
+export function _chachaReady() {
+    try {
+        getInstance('chacha20');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/chacha20/ops.d.ts

@@ -0,0 +1,16 @@
+import type { ChaChaExports } from './types.js';
+/** ChaCha20-Poly1305 AEAD encrypt (RFC 8439 §2.8). */
+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. */
+export declare function aeadDecrypt(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, tag: Uint8Array, aad: Uint8Array): 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. */
+export declare function innerNonce(nonce: Uint8Array): Uint8Array;
+/** XChaCha20-Poly1305 encrypt → ciphertext || tag. */
+export declare function xcEncrypt(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Uint8Array;
+/** XChaCha20-Poly1305 decrypt → plaintext (throws on auth failure). */
+export declare function xcDecrypt(x: ChaChaExports, key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array): Uint8Array;

package/dist/chacha20/ops.js

@@ -0,0 +1,146 @@
+// src/ts/chacha20/ops.ts
+//
+// Raw XChaCha20-Poly1305 operations — standalone functions that take
+// ChaChaExports explicitly. Used by both the class wrappers (index.ts)
+// and the pool worker (pool.worker.ts), eliminating duplication.
+import { constantTimeEqual } from '../utils.js';
+// ── Module-private helpers ───────────────────────────────────────────────────
+function polyFeed(x, data) {
+    if (data.length === 0)
+        return;
+    const mem = new Uint8Array(x.memory.buffer);
+    const msgOff = x.getPolyMsgOffset();
+    let pos = 0;
+    while (pos < data.length) {
+        const chunk = Math.min(64, data.length - pos);
+        mem.set(data.subarray(pos, pos + chunk), msgOff);
+        x.polyUpdate(chunk);
+        pos += chunk;
+    }
+}
+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;
+    }
+    return b;
+}
+// ── Inner AEAD (12-byte nonce) ───────────────────────────────────────────────
+/** ChaCha20-Poly1305 AEAD encrypt (RFC 8439 §2.8). */
+export function aeadEncrypt(x, key, nonce, plaintext, aad) {
+    const maxChunk = x.getChunkSize();
+    if (plaintext.length > maxChunk)
+        throw new RangeError(`plaintext exceeds ${maxChunk} bytes — split into smaller chunks`);
+    const mem = new Uint8Array(x.memory.buffer);
+    // 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
+    x.polyInit();
+    // Step 3: MAC AAD + pad
+    polyFeed(x, aad);
+    const aadPad = (16 - aad.length % 16) % 16;
+    if (aadPad > 0)
+        polyFeed(x, new Uint8Array(aadPad));
+    // Step 4: Re-init ChaCha20 at counter=1
+    x.chachaSetCounter(1);
+    x.chachaLoadKey();
+    // Step 5: Encrypt
+    mem.set(plaintext, x.getChunkPtOffset());
+    x.chachaEncryptChunk(plaintext.length);
+    const ctOff = x.getChunkCtOffset();
+    const ciphertext = new Uint8Array(x.memory.buffer).slice(ctOff, ctOff + plaintext.length);
+    // Step 6: MAC ciphertext + pad
+    polyFeed(x, ciphertext);
+    const ctPad = (16 - plaintext.length % 16) % 16;
+    if (ctPad > 0)
+        polyFeed(x, new Uint8Array(ctPad));
+    // Step 7: MAC length footer
+    polyFeed(x, lenBlock(aad.length, plaintext.length));
+    // Step 8: Finalise
+    x.polyFinal();
+    const tagOff = x.getPolyTagOffset();
+    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. */
+export function aeadDecrypt(x, key, nonce, ciphertext, tag, aad) {
+    const maxChunk = x.getChunkSize();
+    if (ciphertext.length > maxChunk)
+        throw new RangeError(`ciphertext exceeds ${maxChunk} bytes — split into smaller chunks`);
+    const mem = new Uint8Array(x.memory.buffer);
+    // Compute expected tag
+    mem.set(key, x.getKeyOffset());
+    mem.set(nonce, x.getChachaNonceOffset());
+    x.chachaSetCounter(1);
+    x.chachaLoadKey();
+    x.chachaGenPolyKey();
+    x.polyInit();
+    polyFeed(x, aad);
+    const aadPad = (16 - aad.length % 16) % 16;
+    if (aadPad > 0)
+        polyFeed(x, new Uint8Array(aadPad));
+    polyFeed(x, ciphertext);
+    const ctPad = (16 - ciphertext.length % 16) % 16;
+    if (ctPad > 0)
+        polyFeed(x, new Uint8Array(ctPad));
+    polyFeed(x, lenBlock(aad.length, ciphertext.length));
+    x.polyFinal();
+    // 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');
+    // Decrypt only after authentication succeeds
+    x.chachaSetCounter(1);
+    x.chachaLoadKey();
+    new Uint8Array(x.memory.buffer).set(ciphertext, x.getChunkPtOffset());
+    x.chachaEncryptChunk(ciphertext.length);
+    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. */
+export function deriveSubkey(x, key, nonce) {
+    const mem = new Uint8Array(x.memory.buffer);
+    mem.set(key, x.getKeyOffset());
+    mem.set(nonce.subarray(0, 16), x.getXChaChaNonceOffset());
+    x.hchacha20();
+    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. */
+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. */
+export function xcEncrypt(x, key, nonce, plaintext, aad) {
+    const subkey = deriveSubkey(x, key, nonce);
+    const inner = innerNonce(nonce);
+    const { ciphertext, tag } = aeadEncrypt(x, subkey, inner, plaintext, aad);
+    const result = new Uint8Array(ciphertext.length + 16);
+    result.set(ciphertext);
+    result.set(tag, ciphertext.length);
+    return result;
+}
+/** XChaCha20-Poly1305 decrypt → plaintext (throws on auth failure). */
+export function xcDecrypt(x, key, nonce, ciphertext, aad) {
+    const ct = ciphertext.subarray(0, ciphertext.length - 16);
+    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);
+}

package/dist/chacha20/pool.d.ts

@@ -0,0 +1,52 @@
+export interface PoolOpts {
+    /** Number of workers. Default: navigator.hardwareConcurrency ?? 4 */
+    workers?: number;
+}
+/**
+ * Parallel worker pool for XChaCha20-Poly1305 AEAD.
+ *
+ * Each worker owns its own `WebAssembly.Instance` with isolated linear memory.
+ * Jobs are dispatched round-robin to idle workers; excess jobs queue until a
+ * worker frees up.
+ *
+ * **Warning:** Input buffers (`key`, `nonce`, `plaintext`/`ciphertext`, `aad`)
+ * are transferred to the worker and neutered on the calling side. The caller
+ * must copy any buffer they need to retain after calling `encrypt()`/`decrypt()`.
+ */
+export declare class XChaCha20Poly1305Pool {
+    private readonly _workers;
+    private readonly _idle;
+    private readonly _queue;
+    private readonly _pending;
+    private _nextId;
+    private _disposed;
+    private constructor();
+    /**
+     * Create a new pool. Requires `init(['chacha20'])` to have been called.
+     * Compiles the WASM module once and distributes it to all workers.
+     */
+    static create(opts?: PoolOpts): Promise<XChaCha20Poly1305Pool>;
+    /**
+     * Encrypt plaintext with XChaCha20-Poly1305.
+     * Returns `ciphertext || tag` (plaintext.length + 16 bytes).
+     *
+     * **Warning:** All input buffers are transferred and neutered after dispatch.
+     */
+    encrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Decrypt ciphertext with XChaCha20-Poly1305.
+     * Input is `ciphertext || tag` (at least 16 bytes).
+     *
+     * **Warning:** All input buffers are transferred and neutered after dispatch.
+     */
+    decrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+    /** Terminates all workers. Rejects all pending and queued jobs. */
+    dispose(): void;
+    /** Number of workers in the pool. */
+    get size(): number;
+    /** Number of jobs currently queued (waiting for a free worker). */
+    get queueDepth(): number;
+    private _dispatch;
+    private _send;
+    private _onMessage;
+}