leviathan-crypto 1.3.0 → 1.4.0

package/CLAUDE.md

@@ -88,7 +88,7 @@ await serpentInit()
 | Classes | `init()` call |
 |---------|--------------|
 | `SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `Serpent`, `SerpentCtr`, `SerpentCbc` | `init(['serpent', 'sha2'])` |
-| `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Poly1305Pool` | `init(['chacha20'])` |
+| `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Seal`, `XChaCha20Poly1305Pool` | `init(['chacha20'])` |
 | `SHA256`, `SHA384`, `SHA512`, `HMAC_SHA256`, `HMAC_SHA384`, `HMAC_SHA512`, `HKDF_SHA256`, `HKDF_SHA512` | `init(['sha2'])` |
 | `SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256` | `init(['sha3'])` |
 | `Fortuna` | `init(['serpent', 'sha2'])` |
@@ -106,8 +106,9 @@ await init(['serpent', 'sha2'])
 
 const key = randomBytes(64)       // 64-byte key (encKey + macKey)
 const seal = new SerpentSeal()
-const ciphertext = seal.encrypt(key, plaintext)   // Serpent-CBC + HMAC-SHA256
-const decrypted  = seal.decrypt(key, ciphertext)  // throws on tamper
+const ciphertext = seal.encrypt(key, plaintext)        // Serpent-CBC + HMAC-SHA256
+const decrypted  = seal.decrypt(key, ciphertext)       // throws on tamper
+// Optional AAD: seal.encrypt(key, plaintext, aad) / seal.decrypt(key, ciphertext, aad)
 seal.dispose()
 ```
 
@@ -154,6 +155,23 @@ const opener = new SerpentStreamOpener(key, header, { framed: true })
 const chunks = opener.feed(frame0)       // Uint8Array[] — throws on auth failure
 ```
 
+### XChaCha20Seal (recommended)
+
+```typescript
+import { init, XChaCha20Seal, randomBytes } from 'leviathan-crypto'
+
+await init(['chacha20'])
+
+const seal = new XChaCha20Seal(randomBytes(32))   // 32-byte key
+const ct   = seal.encrypt(plaintext)              // nonce(24) || ct || tag(16)
+const pt   = seal.decrypt(ct)                     // throws on tamper
+seal.dispose()
+```
+
+Binds key at construction, generates a fresh nonce per `encrypt()` call. No nonce
+management needed. For protocol interop requiring explicit nonces, use
+`XChaCha20Poly1305` directly.
+
 ### XChaCha20-Poly1305
 
 ```typescript
@@ -257,7 +275,7 @@ The complete API reference ships in `docs/` alongside this file:
 | File | Contents |
 |------|----------|
 | `docs/serpent.md` | `SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `Serpent`, `SerpentCtr`, `SerpentCbc` |
-| `docs/chacha20.md` | `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Poly1305Pool` |
+| `docs/chacha20.md` | `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Seal`, `XChaCha20Poly1305Pool` |
 | `docs/sha2.md` | `SHA256`, `SHA384`, `SHA512`, `HMAC_SHA256`, `HMAC_SHA384`, `HMAC_SHA512`, `HKDF_SHA256`, `HKDF_SHA512` |
 | `docs/sha3.md` | `SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256` |
 | `docs/fortuna.md` | `Fortuna` CSPRNG |

package/README.md

@@ -1,6 +1,6 @@
-[![Version](https://img.shields.io/github/package-json/version/xero/leviathan-crypto?labelColor=33383e&logo=npm&&logoColor=979da4&color=6e2aa5)](https://github.com/xero/leviathan-crypto/releases/latest) [![GitHub repo size](https://img.shields.io/github/repo-size/xero/leviathan-crypto?labelColor=262a2e&logo=googlecontaineroptimizedos&logoColor=979da4&color=6e2aa5)](https://github.com/xero/leviathan-crypto/) [![test suite](https://github.com/xero/leviathan-crypto/actions/workflows/test-suite.yml/badge.svg)](https://github.com/xero/leviathan-crypto/actions/workflows/test-suite.yml) [![wiki](https://github.com/xero/leviathan-crypto/actions/workflows/wiki.yml/badge.svg)](https://github.com/xero/leviathan-crypto/wiki)
+[![GitHub Release](https://img.shields.io/github/v/release/xero/leviathan-crypto?sort=semver&display_name=tag&style=flat&logo=github&logoColor=989da4&label=latest%20release&labelColor=161925&color=1c7293)](https://github.com/xero/leviathan-crypto/releases/latest) [![npm package minimized gzipped size](https://img.shields.io/bundlejs/size/leviathan-crypto?format=both&style=flat&logo=googlecontaineroptimizedos&logoColor=989da4&label=package%20size&labelColor=161925&color=1c7293)](https://www.npmjs.com/package/leviathan-crypto) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/xero/leviathan-crypto/test-suite.yml?branch=main&style=flat&logo=github&logoColor=989da4&label=test%20suite&labelColor=161925&color=1a936f)](https://github.com/xero/leviathan-crypto/actions/workflows/test-suite.yml) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/xero/leviathan-crypto/wiki.yml?branch=main&style=flat&logo=gitbook&logoColor=989da4&label=wiki%20publish&labelColor=161925&color=1a936f)](https://github.com/xero/leviathan-crypto/wiki)
 
-![side-effect free](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-side-effect-free.svg) ![tree-shakeable](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-tree-shakable.svg) ![zero dependencies](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-zero-dependancies.svg) [![MIT Licensed](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-mit-license.svg)](https://github.com/xero/text0wnz/blob/main/LICENSE)
+![simd webassembly](https://img.shields.io/badge/SIMD%20-%20WASM?style=flat&logo=wasmer&logoColor=1a936f&label=WASM&labelColor=33383e&color=161925) ![side-effect free](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-side-effect-free.svg) ![tree-shakeable](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-tree-shakable.svg) ![zero dependencies](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-zero-dependancies.svg) [![MIT Licensed](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-mit-license.svg)](https://github.com/xero/leviathan-crypto/blob/main/LICENSE)
 
 <img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="Leviathan logo" width="400" >
 
@@ -77,15 +77,15 @@ npm install leviathan-crypto
 
 > [!NOTE]
 > The Serpent and ChaCha20 modules require a runtime with WebAssembly SIMD
-> support. This has been a feature of all major browsers and runtimes since
-> 2021. All other primitives (SHA-2, SHA-3, Poly1305) run on any WASM-capable
-> runtime.
+> support. [This has been a feature of all major browsers and runtimes since
+> 2021](https://caniuse.com/wasm-simd). All other primitives (SHA-2, SHA-3,
+> Poly1305) run on any WASM-capable runtime.
 
 ---
 
 ## Demos
 
-**`lvthn-web`** [ [demo](https://leviathan.3xi.club/web) · [source](https://github.com/xero/leviathan-demos/tree/main/lvthn-web) · [readme](https://github.com/xero/leviathan-demos/blob/main/lvthn-web/README.md) ]
+**`lvthn-web`** [ [demo](https://leviathan.3xi.club/web) · [source](https://github.com/xero/leviathan-demos/tree/main/web) · [readme](https://github.com/xero/leviathan-demos/blob/main/web/README.md) ]
 
 A browser encryption tool in a single, self-contained HTML file. Encrypt text
 or files using Serpent-256-CBC and Argon2id key derivation, then share the
@@ -94,7 +94,7 @@ initial load. The code is written to be read. The Encrypt-then-MAC
 construction, HMAC input (header with HMAC field zeroed + ciphertext), and
 Argon2id parameters are all intentional examples worth reading.
 
-**`lvthn-chat`** [ [demo](https://leviathan.3xi.club/chat) · [source](https://github.com/xero/leviathan-demos/tree/main/lvthn-chat) · [readme](https://github.com/xero/leviathan-demos/blob/main/lvthn-chat/README.md) ]
+**`lvthn-chat`** [ [demo](https://leviathan.3xi.club/chat) · [source](https://github.com/xero/leviathan-demos/tree/main/chat) · [readme](https://github.com/xero/leviathan-demos/blob/main/chat/README.md) ]
 
 End-to-end encrypted chat featuring two-party messaging over X25519 key
 exchange and XChaCha20-Poly1305 message encryption. The relay server functions
@@ -126,17 +126,20 @@ cat secret.txt | lvthn encrypt -k my.key --armor > secret.enc
 | Class                                                       | Module            | Auth    | Notes                                                                                                                                              |
 | ----------------------------------------------------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Authenticated encryption**                                |                   |         |                                                                                                                                                    |
-| `SerpentSeal`                                               | `serpent`, `sha2` | **Yes** | Serpent-CBC + HMAC-SHA256. Recommended default for most use cases. 64-byte key.                                                                    |
+| `SerpentSeal`                                               | `serpent`, `sha2` | **Yes** | Serpent-CBC + HMAC-SHA256. Recommended Serpent default. 64-byte key.                                                                                |
+| `XChaCha20Seal`                                             | `chacha20`        | **Yes** | XChaCha20-Poly1305 with internal nonce management. Recommended ChaCha20 default. 32-byte key.                                                      |
 | `SerpentStream`, `SerpentStreamPool`                        | `serpent`, `sha2` | **Yes** | Chunked one-shot AEAD for large payloads. Pool variant parallelises across workers. 32-byte key.                                                   |
 | `SerpentStreamSealer`, `SerpentStreamOpener`                | `serpent`, `sha2` | **Yes** | Incremental streaming AEAD: seal/open one chunk at a time. Pass `{ framed: true }` for self-delimiting `u32be` length-prefix framing. 64-byte key. |
-| `XChaCha20Poly1305`                                         | `chacha20`        | **Yes** | XChaCha20-Poly1305 AEAD. Recommended when you want a simpler API or a 192-bit nonce safe for random generation. 32-byte key.                       |
+| `XChaCha20StreamSealer`, `XChaCha20StreamOpener`            | `chacha20`        | **Yes** | Incremental streaming AEAD using XChaCha20-Poly1305. Per-chunk random nonces, position-bound AAD. `{ framed: true }` for length-prefixed framing. 32-byte key. |
 | `XChaCha20Poly1305Pool`                                     | `chacha20`        | **Yes** | Worker-pool wrapper for `XChaCha20Poly1305`. Parallelises encryption across isolated WASM instances.                                               |
-| `ChaCha20Poly1305`                                          | `chacha20`        | **Yes** | ChaCha20-Poly1305 AEAD — RFC 8439. 12-byte nonce; prefer `XChaCha20Poly1305` unless you need RFC 8439 exact compliance.                            |
+| **Stateless primitives** _caller manages nonces_            |                   |         |                                                                                                                                                    |
+| `XChaCha20Poly1305`                                         | `chacha20`        | **Yes** | RFC-faithful stateless AEAD. 24-byte nonce, caller-managed. Use `XChaCha20Seal` unless you need explicit nonce control.                            |
+| `ChaCha20Poly1305`                                          | `chacha20`        | **Yes** | RFC 8439 stateless AEAD. 12-byte nonce, caller-managed. Prefer `XChaCha20Seal` unless you need RFC 8439 exact compliance.                          |
 | **Unauthenticated primitives** _pair with HMAC or use AEAD_ |                   |         |                                                                                                                                                    |
 | `Serpent`                                                   | `serpent`         | **No**  | Serpent-256 ECB block cipher. Single-block encrypt/decrypt.                                                                                        |
 | `SerpentCtr`                                                | `serpent`         | **No**  | Serpent-256 CTR mode stream cipher. Requires `{ dangerUnauthenticated: true }`.                                                                    |
 | `SerpentCbc`                                                | `serpent`         | **No**  | Serpent-256 CBC mode with PKCS7 padding. Requires `{ dangerUnauthenticated: true }`.                                                               |
-| `ChaCha20`                                                  | `chacha20`        | **No**  | ChaCha20 stream cipher — RFC 8439. Unauthenticated; use `XChaCha20Poly1305` unless you need raw keystream.                                         |
+| `ChaCha20`                                                  | `chacha20`        | **No**  | ChaCha20 stream cipher — RFC 8439. Unauthenticated; use `XChaCha20Seal` unless you need raw keystream.                                             |
 | `Poly1305`                                                  | `chacha20`        | **No**  | Poly1305 one-time MAC — RFC 8439. Use via the AEAD classes unless you have a specific reason not to.                                               |
 | **Hashing and key derivation**                              |                   |         |                                                                                                                                                    |
 | `SHA256`, `SHA384`, `SHA512`                                | `sha2`            | —       | SHA-2 family — FIPS 180-4.                                                                                                                         |
@@ -174,25 +177,24 @@ const decrypted = seal.decrypt(key, ciphertext)
 seal.dispose()
 ```
 
-### Authenticated encryption with XChaCha20-Poly1305
+### Authenticated encryption with XChaCha20
 
 ```typescript
-import { init, XChaCha20Poly1305, randomBytes } from 'leviathan-crypto'
+import { init, XChaCha20Seal, randomBytes } from 'leviathan-crypto'
 
 await init(['chacha20'])
 
-const key   = randomBytes(32)  // 32-byte key
-const nonce = randomBytes(24)  // 24-byte nonce (XChaCha20 extended nonce)
+const key = randomBytes(32)  // 32-byte key
 
-const chacha = new XChaCha20Poly1305()
+const seal = new XChaCha20Seal(key)
 
-// Encrypt and authenticate
-const ciphertext = chacha.encrypt(key, nonce, plaintext)
+// Encrypt and authenticate (nonce generated internally)
+const ciphertext = seal.encrypt(plaintext)
 
 // Decrypt and verify (throws on tamper)
-const decrypted = chacha.decrypt(key, nonce, ciphertext)
+const decrypted = seal.decrypt(ciphertext)
 
-chacha.dispose()
+seal.dispose()
 ```
 
 For more examples, including streaming, chunking, hashing, and key derivation,
@@ -224,7 +226,7 @@ import { serpentInit, SerpentSeal } from 'leviathan-crypto/serpent'
 await serpentInit()
 
 // Only chacha20.wasm ends up in your bundle
-import { chacha20Init, XChaCha20Poly1305 } from 'leviathan-crypto/chacha20'
+import { chacha20Init, XChaCha20Seal } from 'leviathan-crypto/chacha20'
 await chacha20Init()
 ```
 
@@ -252,7 +254,7 @@ await chacha20Init()
 | ----------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | serpent     | [▼](./docs/serpent.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/serpent)         | Serpent-256 TypeScript API (`SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `Serpent`, `SerpentCtr`, `SerpentCbc`) |
 | asm_serpent | [▼](./docs/asm_serpent.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/asm_serpent) | Serpent-256 WASM implementation (bitslice S-boxes, key schedule, CTR/CBC)                                                                                             |
-| chacha20    | [▼](./docs/chacha20.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/chacha20)       | ChaCha20/Poly1305 TypeScript API (`ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Poly1305Pool`)                                           |
+| chacha20    | [▼](./docs/chacha20.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/chacha20)       | ChaCha20/Poly1305 TypeScript API (`XChaCha20Seal`, `XChaCha20StreamSealer`, `XChaCha20StreamOpener`, `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Poly1305Pool`) |
 | asm_chacha  | [▼](./docs/asm_chacha.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/asm_chacha)   | ChaCha20/Poly1305 WASM implementation (quarter-round, HChaCha20)                                                                                                      |
 | sha2        | [▼](./docs/sha2.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/sha2)               | SHA-2 TypeScript API (`SHA256`, `SHA512`, `SHA384`, `HMAC_SHA256`, `HMAC_SHA512`, `HMAC_SHA384`)                                                                      |
 | asm_sha2    | [▼](./docs/asm_sha2.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/asm_sha2)       | SHA-2 WASM implementation (compression functions, HMAC)                                                                                                               |
@@ -278,7 +280,7 @@ These helpers are available immediately on import with no `init()` required.
 | `constantTimeEqual(a, b)`    | [▼](./docs/utils.md#constanttimeequal) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal) | Constant-time byte comparison (XOR-accumulate)                                                            |
 | `wipe(data)`                 | [▼](./docs/utils.md#wipe) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#wipe)                           | Zero a typed array in place                                                                               |
 | `xor(a, b)`                  | [▼](./docs/utils.md#xor) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#xor)                             | XOR two equal-length `Uint8Array`s                                                                        |
-| `concat(a, b)`               | [▼](./docs/utils.md#concat) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#concat)                       | Concatenate two `Uint8Array`s                                                                             |
+| `concat(...arrays)`          | [▼](./docs/utils.md#concat) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#concat)                       | Concatenate `Uint8Array`s (variadic)                                                                      |
 | `hasSIMD()`                  | [▼](./docs/utils.md#hassimd) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#hassimd)                     | Detects WebAssembly SIMD support. Cached after first call. Used internally for CTR/CBC/ChaCha20 dispatch. |
 
 ### Algorithm correctness and verifications

package/SECURITY.md

@@ -13,8 +13,9 @@
 
 | Version | Supported |
 |---------|-----------|
-| v1.3.x  | ︎✓         |
-| v1.2.x  | ✓         |
+| v1.4.x  | ✓         |
+| v1.3.x  | ✓         |
+| v1.2.x  | ✗         |
 | v1.1.x  | ✗         |
 | v1.0.x  | ✗         |
 
@@ -92,18 +93,29 @@ See: [`xero/BicliqueFinder/biclique_research.md`][biclique]
 
 ### Authenticated Encryption by Default
 
-Raw unauthenticated cipher modes (`SerpentCbc`, `SerpentCtr`) are exposed
-for power users but are not the recommended entry point. The primary API
-surfaces — `SerpentSeal`, `SerpentStream`, `SerpentStreamSealer` — are
-authenticated by construction.
+Raw unauthenticated cipher modes (`SerpentCbc`, `SerpentCtr`, `ChaCha20`) and
+stateless caller-managed-nonce primitives (`ChaCha20Poly1305`,
+`XChaCha20Poly1305`) are exposed for power users but are not the recommended
+entry point. The primary API surfaces — `SerpentSeal`, `SerpentStream`,
+`SerpentStreamSealer`, `XChaCha20Seal`, and `XChaCha20StreamSealer` — are
+authenticated by construction with internally managed nonces.
 
-**`SerpentStreamSealer` satisfies the _Cryptographic Doom Principle_:**
+**Both streaming constructions satisfy the _Cryptographic Doom Principle_:**
 
-MAC verification is the unconditional gate on the open path,
-decryption is unreachable until that gate clears, and per-chunk
+`SerpentStreamSealer` uses encrypt-then-MAC (SerpentCbc + HMAC-SHA256).
+MAC verification is the unconditional gate on the open path.
+Decryption is unreachable until that gate clears. Per-chunk
 HKDF key derivation with position-bound info extends this
 guarantee to full stream integrity.
 
+`XChaCha20StreamSealer` uses XChaCha20-Poly1305 AEAD per chunk.
+The Poly1305 tag is verified inside the WASM `xcDecrypt` call
+before any plaintext is produced. On authentication failure,
+plaintext bytes are never generated and never returned. Stream-level
+binding via per-chunk AAD (`stream_id || index || isLast || user AAD`)
+ensures reorder, splice, truncation, and cross-stream substitution
+all fail AEAD verification before decryption.
+
 ### Dependency Management
 
 The library has **zero** runtime dependencies by design.

package/dist/chacha20/index.d.ts

@@ -46,4 +46,24 @@ export declare class XChaCha20Poly1305 {
     decrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
     dispose(): void;
 }
+/**
+ * XChaCha20-Poly1305 AEAD with bound key and automatic nonce management.
+ * Implements the AEAD interface — encrypt()/decrypt() require only plaintext
+ * and optional AAD. Each encrypt() call generates a fresh 24-byte random nonce.
+ *
+ * Wire format: nonce(24) || ciphertext || tag(16)
+ *
+ * Use this when you want the simplest correct API and do not need to manage
+ * nonces yourself. For protocol interop requiring explicit nonce control,
+ * use XChaCha20Poly1305 directly.
+ */
+export declare class XChaCha20Seal {
+    private readonly _x;
+    private readonly _key;
+    constructor(key: Uint8Array);
+    encrypt(plaintext: Uint8Array, aad?: Uint8Array, _nonce?: Uint8Array): Uint8Array;
+    decrypt(ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    dispose(): void;
+}
+export { XChaCha20StreamSealer, XChaCha20StreamOpener } from './stream-sealer.js';
 export declare function _chachaReady(): boolean;

package/dist/chacha20/index.js

@@ -25,8 +25,8 @@
 // Uses the init() module cache — call init('chacha20') before constructing.
 import { getInstance, initModule } from '../init.js';
 import { aeadEncrypt, aeadDecrypt, xcEncrypt, xcDecrypt } from './ops.js';
-import { hasSIMD } from '../utils.js';
-const _embedded = () => import('../embedded/chacha.js').then(m => m.WASM_BASE64);
+import { hasSIMD, randomBytes, wipe } from '../utils.js';
+const _embedded = () => import('../embedded/chacha20.js').then(m => m.WASM_GZ_BASE64);
 export async function chacha20Init(mode = 'embedded', opts) {
     return initModule('chacha20', _embedded, mode, opts);
 }
@@ -167,6 +167,52 @@ export class XChaCha20Poly1305 {
         this.x.wipeBuffers();
     }
 }
+// ── XChaCha20Seal ────────────────────────────────────────────────────────────
+/**
+ * XChaCha20-Poly1305 AEAD with bound key and automatic nonce management.
+ * Implements the AEAD interface — encrypt()/decrypt() require only plaintext
+ * and optional AAD. Each encrypt() call generates a fresh 24-byte random nonce.
+ *
+ * Wire format: nonce(24) || ciphertext || tag(16)
+ *
+ * Use this when you want the simplest correct API and do not need to manage
+ * nonces yourself. For protocol interop requiring explicit nonce control,
+ * use XChaCha20Poly1305 directly.
+ */
+export class XChaCha20Seal {
+    _x;
+    _key;
+    constructor(key) {
+        if (!_chachaReady())
+            throw new Error('leviathan-crypto: call init([\'chacha20\']) before using XChaCha20Seal');
+        if (key.length !== 32)
+            throw new RangeError(`XChaCha20Seal key must be 32 bytes (got ${key.length})`);
+        this._x = getExports();
+        this._key = key.slice();
+    }
+    // _nonce: test seam only — inject a fixed nonce for deterministic KAT vectors
+    encrypt(plaintext, aad = new Uint8Array(0), _nonce) {
+        const nonce = (_nonce && _nonce.length === 24) ? _nonce : randomBytes(24);
+        const sealed = xcEncrypt(this._x, this._key, nonce, plaintext, aad);
+        // Prepend nonce to sealed output (ciphertext || tag)
+        const out = new Uint8Array(24 + sealed.length);
+        out.set(nonce, 0);
+        out.set(sealed, 24);
+        return out;
+    }
+    decrypt(ciphertext, aad = new Uint8Array(0)) {
+        if (ciphertext.length < 40)
+            throw new RangeError(`XChaCha20Seal ciphertext too short — need nonce(24)+tag(16)=40 bytes minimum (got ${ciphertext.length})`);
+        const nonce = ciphertext.subarray(0, 24);
+        const payload = ciphertext.subarray(24);
+        return xcDecrypt(this._x, this._key, nonce, payload, aad);
+    }
+    dispose() {
+        wipe(this._key);
+        this._x.wipeBuffers();
+    }
+}
+export { XChaCha20StreamSealer, XChaCha20StreamOpener } from './stream-sealer.js';
 // ── Ready check ──────────────────────────────────────────────────────────────
 export function _chachaReady() {
     try {

package/dist/chacha20/pool.js

@@ -4,24 +4,14 @@
 // Dispatches independent encrypt/decrypt jobs across Web Workers, each with
 // its own WebAssembly.Instance and isolated linear memory.
 import { isInitialized } from '../init.js';
-// ── Module-private base64 decoder (copied from loader.ts) ────────────────────
-function base64ToBytes(b64) {
-    if (typeof atob === 'function') {
-        const raw = atob(b64);
-        const out = new Uint8Array(raw.length);
-        for (let i = 0; i < raw.length; i++)
-            out[i] = raw.charCodeAt(i);
-        return out;
-    }
-    return new Uint8Array(Buffer.from(b64, 'base64'));
-}
+import { decodeWasm } from '../loader.js';
 // ── WASM module singleton ────────────────────────────────────────────────────
 let _wasmModule;
 async function getWasmModule() {
     if (_wasmModule)
         return _wasmModule;
-    const { WASM_BASE64 } = await import('../embedded/chacha.js');
-    const bytes = base64ToBytes(WASM_BASE64);
+    const { WASM_GZ_BASE64 } = await import('../embedded/chacha20.js');
+    const bytes = await decodeWasm(WASM_GZ_BASE64);
     _wasmModule = await WebAssembly.compile(bytes.buffer);
     return _wasmModule;
 }

package/dist/chacha20/stream-sealer.d.ts

@@ -0,0 +1,49 @@
+export declare class XChaCha20StreamSealer {
+    private readonly _x;
+    private readonly _key;
+    private readonly _cs;
+    private readonly _id;
+    private readonly _framed;
+    private readonly _aad;
+    private _index;
+    private _state;
+    /** Public: consumers use this 3-param form. */
+    constructor(key: Uint8Array, chunkSize?: number, opts?: {
+        framed?: boolean;
+        aad?: Uint8Array;
+    });
+    /** @internal Test-only overload to inject fixed stream_id for deterministic output. */
+    constructor(key: Uint8Array, chunkSize: number | undefined, opts: {
+        framed?: boolean;
+        aad?: Uint8Array;
+    } | undefined, _id: Uint8Array);
+    header(): Uint8Array;
+    seal(plaintext: Uint8Array): Uint8Array;
+    final(plaintext: Uint8Array): Uint8Array;
+    private _sealChunk;
+    private _wipe;
+    dispose(): void;
+}
+export declare class XChaCha20StreamOpener {
+    private readonly _x;
+    private readonly _key;
+    private readonly _cs;
+    private readonly _id;
+    private readonly _framed;
+    private readonly _aad;
+    private readonly _buf;
+    private readonly _maxFrame;
+    private _bufLen;
+    private _index;
+    private _dead;
+    constructor(key: Uint8Array, header: Uint8Array, opts?: {
+        framed?: boolean;
+        aad?: Uint8Array;
+    });
+    get closed(): boolean;
+    open(chunk: Uint8Array): Uint8Array;
+    private _openRaw;
+    feed(bytes: Uint8Array): Uint8Array[];
+    private _wipe;
+    dispose(): void;
+}