leviathan-crypto 2.1.0 → 3.0.0

package/README.md

@@ -1,30 +1,54 @@
 [![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)
 
-![simd webassembly](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-wasm-simd.svg) ![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)
+![simd webassembly](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-wasm-simd.svg) ![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-shakeable.svg) ![zero dependencies](https://github.com/xero/leviathan-crypto/raw/main/docs/badge-zero-dependencies.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" >
 
 # Leviathan Crypto: post-quantum WASM cryptography
 
-**JS is the problem, SIMD WASM is the solution.** JavaScript engines offer no formal constant-time guarantees. JIT compilers optimize based on runtime patterns, which leak secrets through cache access and instruction timing. By contrast, [WebAssembly](https://github.com/xero/leviathan-crypto/wiki/wasm) executes outside the JIT entirely, running compiled bytecode with linear memory you control. No speculative optimization, no value-dependent branches between source and execution.
+**Zero runtime dependencies.** No NPM graph to audit. No supply chain attack surface.
 
-**WebAssembly is the correctness layer.** All algorithm logic lives in WASM. Six AssemblyScript modules ([`serpent`](https://github.com/xero/leviathan-crypto/wiki/asm_serpent), [`chacha20`](https://github.com/xero/leviathan-crypto/wiki/asm_chacha), [`sha2`](https://github.com/xero/leviathan-crypto/wiki/asm_sha2), [`sha3`](https://github.com/xero/leviathan-crypto/wiki/asm_sha3), [`kyber`](https://github.com/xero/leviathan-crypto/wiki/asm_kyber), and [`ct`](https://github.com/xero/leviathan-crypto/wiki/asm_ct)) compile independently to WASM with SIMD where it pays off. Each module is its own instance with its own linear memory. Within a module, stateful primitives share the instance, and a runtime exclusivity model keeps them from interfering with each other.
+**Tree-shakeable.** Import only what you use. Subpath exports let bundlers exclude everything else.
 
-**TypeScript is the ergonomics layer.** The strongly-typed public API covers [`Seal`](https://github.com/xero/leviathan-crypto/wiki/aead#seal), [`SealStream`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstream), [`SealStreamPool`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstreampool), [`Fortuna`](https://github.com/xero/leviathan-crypto/wiki/fortuna), [`HKDF`](https://github.com/xero/leviathan-crypto/wiki/sha2#hkdf_sha256), [`SkippedKeyStore`](https://github.com/xero/leviathan-crypto/wiki/ratchet#skippedkeystore), and others. The design is misuse-resistant by default. Authentication is verify-then-decrypt; key material wipes on dispose; validation runs before any crypto path; one-shot AEADs lock on first call. TypeScript never implements cryptographic algorithms. It orchestrates the WASM layer and enforces best practice through API shape, not convention.
+**Side-effect free.** Nothing runs on import. [`init()`](https://github.com/xero/leviathan-crypto/wiki/init) is explicit and asynchronous.
 
-**[Serpent-256](https://github.com/xero/leviathan-crypto/wiki/serpent_reference): maximum paranoia.** 32 rounds of S-boxes in pure Boolean logic with no table lookups. An ouroboros devouring every bit, in every block, through every round.
+**Cipher Triptych.** Leviathan provides three ciphers. The implementations all use a round structure that operates as a bitsliced Boolean circuit, implemented with register-only logic and no S-box lookup tables. Each compiles to an independent, v128 SIMD-optimized WebAssembly module with isolated linear memory, which prevents cross-module memory access by design. Every operation zeroes key material on exit, including on failure.
 
-**[XChaCha20-Poly1305](https://github.com/xero/leviathan-crypto/wiki/chacha_reference): precise elegance.** 20 rounds of add-rotate-XOR, choreography without S-boxes or cache-timing leakage. A dance closing with Poly1305's unconditional forgery bound.
+**[Serpent-256](https://github.com/xero/leviathan-crypto/wiki/serpent_reference): maximum paranoia.** 32 rounds of eight different 4-bit S-boxes, each bitsliced as a Boolean circuit with no table lookups. An ouroboros devouring every bit, in every block, through every round.
 
-**Two ciphers, one interface.** Both share the [`CipherSuite`](https://github.com/xero/leviathan-crypto/wiki/ciphersuite) shape and slot into [`Seal`](https://github.com/xero/leviathan-crypto/wiki/aead#seal), [`SealStream`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstream), and [`SealStreamPool`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstreampool) interchangeably. Post-quantum extends the same model, [`KyberSuite`](https://github.com/xero/leviathan-crypto/wiki/ciphersuite#kybersuite) wraps [`MlKem512`](https://github.com/xero/leviathan-crypto/wiki/kyber#parameter-sets), [`MlKem768`](https://github.com/xero/leviathan-crypto/wiki/kyber#parameter-sets), or [`MlKem1024`](https://github.com/xero/leviathan-crypto/wiki/kyber#parameter-sets) around either cipher, and the [SPQR ratchet](https://github.com/xero/leviathan-crypto/wiki/ratchet) builds forward-secret sessions on top.
+**[XChaCha20-Poly1305](https://github.com/xero/leviathan-crypto/wiki/chacha_reference): precise elegance.** 20 rounds of add-rotate-XOR alternating column and diagonal quarter-rounds, choreography without S-boxes or cache-timing leakage. A dance closing with Poly1305's unconditional forgery bound.
 
-**Zero dependencies.** No npm graph to audit. No supply chain attack surface.
+**[AES-256-GCM-SIV](https://github.com/xero/leviathan-crypto/wiki/aes_reference): industry standard, sharpened.** 14 rounds bitsliced into Boolean gates with tower-field S-box with no table lookups. A fresh POLYVAL key per nonce leaves GHASH-key recovery with no target.
 
-**Tree-shakeable.** Import only what you use. Subpath exports let bundlers exclude everything else.
+**A uniform API.** The same call shape drives [authenticated encryption](https://github.com/xero/leviathan-crypto/wiki/aead), [signatures and key agreement](https://github.com/xero/leviathan-crypto/wiki/signing), [post-quantum KEM](https://github.com/xero/leviathan-crypto/wiki/mlkem), [hashing](https://github.com/xero/leviathan-crypto/wiki/hashing), [transparency logs](https://github.com/xero/leviathan-crypto/wiki/merkle), [post-quantum ratchet](https://github.com/xero/leviathan-crypto/wiki/ratchet), the [Fortuna CSPRNG](https://github.com/xero/leviathan-crypto/wiki/fortuna), [utilities](https://github.com/xero/leviathan-crypto/wiki/utils), and [types](https://github.com/xero/leviathan-crypto/wiki/types).
 
-**Side-effect free.** Nothing runs on import. [`init()`](https://github.com/xero/leviathan-crypto/wiki/init) is explicit and asynchronous.
+**The correctness contract.** Every cipher, hash, KEM, and signature scheme derives independently from its authoritative spec, never ported from another implementation. Known-answer test vectors come from spec authors, and cross-checks run against multiple independent reference implementations. The test suite covers unit tests at the primitive level plus end-to-end tests across three browser engines (Chromium, Firefox, WebKit) and Node.js. Detailed reference documentation ships at the [project wiki](https://github.com/xero/leviathan-crypto/wiki).
+
+---
+
+## Highlights
+
+| **_I want to..._** | |
+|---|---|
+| Encrypt data | [`Seal`](https://github.com/xero/leviathan-crypto/wiki/aead#seal) with [`SerpentCipher`](https://github.com/xero/leviathan-crypto/wiki/serpent#serpentcipher), [`XChaCha20Cipher`](https://github.com/xero/leviathan-crypto/wiki/chacha20#xchacha20cipher), or [`AESGCMSIVCipher`](https://github.com/xero/leviathan-crypto/wiki/aes#aesgcmsivcipher) |
+| Encrypt a stream or large file | [`SealStream`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstream) to encrypt, [`OpenStream`](https://github.com/xero/leviathan-crypto/wiki/aead#openstream) to decrypt |
+| Encrypt in parallel | [`SealStreamPool`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstreampool) distributes chunks across Web Workers |
+| Add post-quantum security | [`MlKemSuite`](https://github.com/xero/leviathan-crypto/wiki/mlkem#mlkemsuite) wraps [`MlKem512`](https://github.com/xero/leviathan-crypto/wiki/mlkem#parameter-sets), [`MlKem768`](https://github.com/xero/leviathan-crypto/wiki/mlkem#parameter-sets), or [`MlKem1024`](https://github.com/xero/leviathan-crypto/wiki/mlkem#parameter-sets) with any cipher suite |
+| Build a forward-secret session | [`ratchetInit`](https://github.com/xero/leviathan-crypto/wiki/ratchet#ratchetinit), [`KDFChain`](https://github.com/xero/leviathan-crypto/wiki/ratchet#kdfchain), [`kemRatchetEncap`](https://github.com/xero/leviathan-crypto/wiki/ratchet#kemratchetencap) / [`kemRatchetDecap`](https://github.com/xero/leviathan-crypto/wiki/ratchet#kemratchetdecap), [`SkippedKeyStore`](https://github.com/xero/leviathan-crypto/wiki/ratchet#skippedkeystore) |
+| Sign data with a classical signature | [`Ed25519Suite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#ed25519-suites) / [`Ed25519PreHashSuite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#ed25519-suites) ([ed25519](https://github.com/xero/leviathan-crypto/wiki/ed25519)) or [`EcdsaP256Suite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#ecdsa-p256-suite) ([ecdsa-p256](https://github.com/xero/leviathan-crypto/wiki/ecdsa-p256)) via [`Sign`](https://github.com/xero/leviathan-crypto/wiki/signing#sign) / [`SignStream`](https://github.com/xero/leviathan-crypto/wiki/signing#signstream) / [`VerifyStream`](https://github.com/xero/leviathan-crypto/wiki/signing#verifystream) |
+| Sign data with a post-quantum signature | `MlDsa44/65/87Suite` (+ `*PreHashSuite`) for lattice ML-DSA ([mldsa](https://github.com/xero/leviathan-crypto/wiki/mldsa)) or `SlhDsa128f/192f/256fSuite` (+ `*PreHashSuite`) for hash-based SLH-DSA ([slhdsa](https://github.com/xero/leviathan-crypto/wiki/slhdsa)). Full catalog in [signaturesuite](https://github.com/xero/leviathan-crypto/wiki/signaturesuite) |
+| Sign data with a classical+PQ hybrid | [`MlDsa44Ed25519Suite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#classicalpq-hybrid-composite-encoding), [`MlDsa65Ed25519Suite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#classicalpq-hybrid-composite-encoding), [`MlDsa44EcdsaP256Suite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#classicalpq-hybrid-composite-encoding), [`MlDsa65EcdsaP256Suite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#classicalpq-hybrid-composite-encoding) for `draft-ietf-lamps-pq-composite-sigs` |
+| Sign data with a PQ-only hybrid | [`MlDsa44SlhDsa128fSuite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#pq-only-hybrid-suites), [`MlDsa65SlhDsa192fSuite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#pq-only-hybrid-suites), [`MlDsa87SlhDsa256fSuite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#pq-only-hybrid-suites) for ML-DSA + SLH-DSA composites at matching NIST categories |
+| Build a transparency log | [`MerkleLog`](https://github.com/xero/leviathan-crypto/wiki/merkle#merklelog) for append plus inclusion / consistency proofs, [`MerkleVerifier`](https://github.com/xero/leviathan-crypto/wiki/merkle#merkleverifier) for clients, [`SignedLog`](https://github.com/xero/leviathan-crypto/wiki/merkle#signedlog) for custom storage backends |
+| Exchange a key with a peer | [`X25519`](https://github.com/xero/leviathan-crypto/wiki/x25519) for Curve25519 Diffie-Hellman |
+| Hash data | [`SHA256`](https://github.com/xero/leviathan-crypto/wiki/sha2#sha256), [`SHA384`](https://github.com/xero/leviathan-crypto/wiki/sha2#sha384), [`SHA512`](https://github.com/xero/leviathan-crypto/wiki/sha2#sha512), [`SHA3_256`](https://github.com/xero/leviathan-crypto/wiki/sha3#sha3_256), [`SHA3_512`](https://github.com/xero/leviathan-crypto/wiki/sha3#sha3_512), [`SHAKE256`](https://github.com/xero/leviathan-crypto/wiki/sha3#shake256) ... |
+| Authenticate a message | [`HMAC_SHA256`](https://github.com/xero/leviathan-crypto/wiki/sha2#hmac_sha256), [`HMAC_SHA384`](https://github.com/xero/leviathan-crypto/wiki/sha2#hmac_sha384), [`HMAC_SHA512`](https://github.com/xero/leviathan-crypto/wiki/sha2#hmac_sha512), or [`KMAC256`](https://github.com/xero/leviathan-crypto/wiki/kmac#kmac256) |
+| Derive keys | [`HKDF_SHA256`](https://github.com/xero/leviathan-crypto/wiki/sha2#hkdf_sha256) or [`HKDF_SHA512`](https://github.com/xero/leviathan-crypto/wiki/sha2#hkdf_sha512) |
+| Generate random bytes | [`Fortuna`](https://github.com/xero/leviathan-crypto/wiki/fortuna#api-reference) for forward-secret generation, [`randomBytes`](https://github.com/xero/leviathan-crypto/wiki/utils#randombytes) for one-off use |
+| Compare secrets safely | [`constantTimeEqual`](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal) uses a WASM SIMD path to prevent timing attacks |
+| Work with bytes | [`hexToBytes`](https://github.com/xero/leviathan-crypto/wiki/utils#hextobytes), [`bytesToHex`](https://github.com/xero/leviathan-crypto/wiki/utils#bytestohex), [`wipe`](https://github.com/xero/leviathan-crypto/wiki/utils#wipe), [`xor`](https://github.com/xero/leviathan-crypto/wiki/utils#xor), [`concat`](https://github.com/xero/leviathan-crypto/wiki/utils#concat) ... |
 
-**Audited primitives.** Every implementation is [verified against its specification](https://github.com/xero/leviathan-crypto/wiki/audits).
+*For raw primitives, low-level cipher access, and ASM internals see the [full API reference](https://github.com/xero/leviathan-crypto/wiki/index).*
 
 ---
 
@@ -36,6 +60,8 @@ The TypeScript layer never implements cryptographic algorithms. It manages the b
 
 Higher-level classes like `Seal`, `SealStream`, and `SealStreamPool` are pure TypeScript, but they compose WASM-backed primitives (Serpent-CBC, HMAC-SHA256, ChaCha20-Poly1305, and HKDF-SHA256) rather than implementing new cryptographic logic. TypeScript orchestrates, while WASM computes. Pool workers instantiate their own WASM modules and directly call primitives, bypassing the main-thread module cache.
 
+See [wasm.md](https://github.com/xero/leviathan-crypto/wiki/wasm) for a fuller primer on WebAssembly in the context of this library.
+
 ---
 
 ## Installation
@@ -47,8 +73,15 @@ bun i leviathan-crypto
 npm install leviathan-crypto
 ```
 
+v3 is the current stable line; semver applies. Runs in modern browsers, Node.js 22+, Bun, Deno, and Cloudflare Workers.
+
 > [!IMPORTANT]
-> [Serpent](https://github.com/xero/leviathan-crypto/wiki/serpent), [ChaCha20](https://github.com/xero/leviathan-crypto/wiki/chacha20), [ML-KEM](https://github.com/xero/leviathan-crypto/wiki/kyber), and [constantTimeEqual](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal) require WebAssembly SIMD support. This has been a baseline feature of all major browsers and runtimes [since 2021](https://caniuse.com/wasm-simd).
+> [Serpent](https://github.com/xero/leviathan-crypto/wiki/serpent), [ChaCha20](https://github.com/xero/leviathan-crypto/wiki/chacha20), [ML-KEM](https://github.com/xero/leviathan-crypto/wiki/mlkem), [AES](https://github.com/xero/leviathan-crypto/wiki/aes), [ML-DSA](https://github.com/xero/leviathan-crypto/wiki/mldsa), [BLAKE3](https://github.com/xero/leviathan-crypto/wiki/blake3), and [constantTimeEqual](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal) require WebAssembly SIMD support. This has been a baseline feature of all major browsers and runtimes [since 2021](https://caniuse.com/wasm-simd).
+
+SIMD throughput on Apple Silicon peaks at ~1.3 GB/s for ChaCha20 and ~40 MB/s for Serpent, single-threaded; 1.2-3.2× over scalar. Full matrix across V8, SpiderMonkey, and JSC in [benchmarks](https://github.com/xero/leviathan-crypto/wiki/benchmarks).
+
+> [!NOTE]
+> Found a security issue? Don't open a public issue. See [SECURITY.md](./SECURITY.md#reporting-a-vulnerability) for the disclosure policy.
 
 ### Loading
 
@@ -70,6 +103,21 @@ const compiledModule = await WebAssembly.compileStreaming(fetch('/assets/wasm/se
 await init({ serpent: compiledModule })
 ```
 
+All three patterns also work straight from a CDN with no install or bundler:
+
+```html
+<script type="module">
+  import { init, Seal, SerpentCipher } from 'https://unpkg.com/leviathan-crypto/dist/index.js'
+  import { serpentWasm } from 'https://unpkg.com/leviathan-crypto/dist/serpent/embedded.js'
+  import { sha2Wasm }    from 'https://unpkg.com/leviathan-crypto/dist/sha2/embedded.js'
+
+  await init({ serpent: serpentWasm, sha2: sha2Wasm })
+  // ... use as normal
+</script>
+```
+
+See the [CDN reference](https://github.com/xero/leviathan-crypto/wiki/cdn) for unpkg/esm.sh, version pinning, SRI, and import maps.
+
 ### Tree-shaking with subpath imports
 
 Each module ships as its own subpath export. Bundlers with tree-shaking support and `"sideEffects": false` drop every module you don't import.
@@ -84,33 +132,66 @@ import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 await serpentInit(serpentWasm)
 await sha2Init(sha2Wasm)
 
-// ML-KEM requires kyber + sha3
-import { kyberInit } from 'leviathan-crypto/kyber'
-import { kyberWasm } from 'leviathan-crypto/kyber/embedded'
+// ML-KEM requires mlkem + sha3
+import { mlkemInit } from 'leviathan-crypto/mlkem'
+import { mlkemWasm } from 'leviathan-crypto/mlkem/embedded'
 import { sha3Init } from 'leviathan-crypto/sha3'
 import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
 
-await kyberInit(kyberWasm)
+await mlkemInit(mlkemWasm)
 await sha3Init(sha3Wasm)
 ```
 
-| Subpath                              | Entry point                    |
-| ------------------------------------ | ------------------------------ |
-| `leviathan-crypto`                   | `./dist/index.js`              |
-| `leviathan-crypto/stream`            | `./dist/stream/index.js`       |
-| `leviathan-crypto/serpent`           | `./dist/serpent/index.js`      |
-| `leviathan-crypto/serpent/embedded`  | `./dist/serpent/embedded.js`   |
-| `leviathan-crypto/chacha20`          | `./dist/chacha20/index.js`     |
-| `leviathan-crypto/chacha20/embedded` | `./dist/chacha20/embedded.js`  |
-| `leviathan-crypto/sha2`              | `./dist/sha2/index.js`         |
-| `leviathan-crypto/sha2/embedded`     | `./dist/sha2/embedded.js`      |
-| `leviathan-crypto/sha3`              | `./dist/sha3/index.js`         |
-| `leviathan-crypto/sha3/embedded`     | `./dist/sha3/embedded.js`      |
-| `leviathan-crypto/kyber`             | `./dist/kyber/index.js`        |
-| `leviathan-crypto/kyber/embedded`    | `./dist/kyber/embedded.js`     |
-| `leviathan-crypto/ratchet`           | `./dist/ratchet/index.js`      |
-
-See the [WASM loading reference](https://github.com/xero/leviathan-crypto/wiki/loader) for details.
+Real bundle sizes (esbuild minified + gzip):
+
+| Use case | gzip bundle |
+|---|---:|
+| `Seal` + `XChaCha20Cipher` | ~17 KB |
+| `Seal` + `SerpentCipher` | ~29 KB |
+| Merkle log + ML-DSA-44 cosig | ~29 KB |
+| Full root barrel (every export) | ~53 KB |
+
+| Subpath                              | Module                                                  |
+| ------------------------------------ | ------------------------------------------------------- |
+| `leviathan-crypto`                   | root barrel (all exports)                               |
+| `leviathan-crypto/stream`            | cipher-agnostic seal layer                              |
+| `leviathan-crypto/serpent`           | Serpent-256                                             |
+| `leviathan-crypto/serpent/embedded`  | Serpent-256 WASM blob                                   |
+| `leviathan-crypto/chacha20`          | XChaCha20-Poly1305                                      |
+| `leviathan-crypto/chacha20/embedded` | XChaCha20-Poly1305 WASM blob                            |
+| `leviathan-crypto/sha2`              | SHA-2 family (224 / 256 / 384 / 512, HMAC, HKDF)        |
+| `leviathan-crypto/sha2/embedded`     | SHA-2 WASM blob                                         |
+| `leviathan-crypto/sha3`              | SHA-3 / SHAKE family                                    |
+| `leviathan-crypto/sha3/embedded`     | SHA-3 WASM blob                                         |
+| `leviathan-crypto/keccak`            | Keccak alias for SHA-3                                  |
+| `leviathan-crypto/keccak/embedded`   | Keccak WASM blob (same bytes as `sha3/embedded`)        |
+| `leviathan-crypto/mlkem`             | ML-KEM                                                  |
+| `leviathan-crypto/mlkem/embedded`    | ML-KEM WASM blob                                        |
+| `leviathan-crypto/aes`               | AES-256-GCM-SIV                                         |
+| `leviathan-crypto/aes/embedded`      | AES WASM blob                                           |
+| `leviathan-crypto/blake3`            | BLAKE3                                                  |
+| `leviathan-crypto/blake3/embedded`   | BLAKE3 WASM blob                                        |
+| `leviathan-crypto/ecdsa`             | ECDSA-P256                                              |
+| `leviathan-crypto/ecdsa/embedded`    | NIST P-256 WASM blob                                    |
+| `leviathan-crypto/ed25519`           | Ed25519 (pure and Ed25519ph)                            |
+| `leviathan-crypto/ed25519/embedded`  | Curve25519 WASM blob                                    |
+| `leviathan-crypto/mldsa`             | ML-DSA                                                  |
+| `leviathan-crypto/mldsa/embedded`    | ML-DSA WASM blob                                        |
+| `leviathan-crypto/slhdsa`            | SLH-DSA                                                 |
+| `leviathan-crypto/slhdsa/embedded`   | SLH-DSA WASM blob                                       |
+| `leviathan-crypto/x25519`            | X25519 (Curve25519 Diffie-Hellman)                      |
+| `leviathan-crypto/x25519/embedded`   | Curve25519 WASM blob (same bytes as `ed25519/embedded`) |
+| `leviathan-crypto/ratchet`           | forward-secret ratchet (SPQR)                           |
+| `leviathan-crypto/sign`              | scheme-agnostic signature layer                         |
+| `leviathan-crypto/merkle`            | Merkle log substrate                                    |
+
+Subpaths resolve to `./dist/<mod>/index.js` and `./dist/<mod>/embedded.js`.
+
+> [!NOTE]
+> See also:
+> - [`package.json`](https://github.com/xero/leviathan-crypto/blob/main/package.json) for the exact export map
+> - [exports reference](https://github.com/xero/leviathan-crypto/wiki/exports) for what each subpath exports
+> - [WASM loading reference](https://github.com/xero/leviathan-crypto/wiki/loader) for the three loading strategies
 
 ---
 
@@ -189,36 +270,103 @@ const decrypted = await pool.open(encrypted)
 pool.destroy()
 ```
 
-**_Want post-quantum security?_** [`KyberSuite`](https://github.com/xero/leviathan-crypto/wiki/kyber#kybersuite) wraps ML-KEM and a cipher suite into a hybrid construction. It plugs directly into [`SealStream`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstream). The sender encrypts with the public encapsulation key and only the recipient's private decapsulation key can open it.
+**_Want post-quantum security?_** [`MlKemSuite`](https://github.com/xero/leviathan-crypto/wiki/mlkem#mlkemsuite) wraps ML-KEM and a cipher suite into a hybrid construction. It plugs directly into [`SealStream`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstream). The sender encrypts with the public encapsulation key and only the recipient's private decapsulation key can open it.
 
 ```typescript
-import { KyberSuite, MlKem768 } from 'leviathan-crypto/kyber'
-import { kyberWasm }    from 'leviathan-crypto/kyber/embedded'
+import { MlKemSuite, MlKem768 } from 'leviathan-crypto/mlkem'
+import { mlkemWasm }    from 'leviathan-crypto/mlkem/embedded'
 import { sha3Wasm }     from 'leviathan-crypto/sha3/embedded'
 
-await init({ kyber: kyberWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })
+await init({ mlkem: mlkemWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })
 
-const suite = KyberSuite(new MlKem768(), XChaCha20Cipher)
+const suite = MlKemSuite(new MlKem768(), XChaCha20Cipher)
 const { encapsulationKey: ek, decapsulationKey: dk } = suite.keygen()
 
-// sender — encrypts with the public key
+// sender: encrypts with the public key
 const sealer   = new SealStream(suite, ek)
 const preamble = sealer.preamble       // 1108 bytes: 20B header + 1088B KEM ciphertext
 const ct0      = sealer.push(chunk0)
 const ctLast   = sealer.finalize(lastChunk)
 
-// recipient — decrypts with the private key
+// recipient: decrypts with the private key
 const opener = new OpenStream(suite, dk, preamble)
 const pt0    = opener.pull(ct0)
 const ptLast = opener.finalize(ctLast)
 ```
 
+**_Need post-quantum signatures?_** The [sign module](https://github.com/xero/leviathan-crypto/wiki/signing) wraps ML-DSA (FIPS 204) behind a `SignatureSuite` abstraction. `Sign` covers single-shot attached / detached signatures; `SignStream` and `VerifyStream` handle chunked input via HashML-DSA.
+
+```typescript
+import { init, Sign, SignStream, MlDsa65Suite, MlDsa65PreHashSuite } from 'leviathan-crypto'
+import { mldsaWasm } from 'leviathan-crypto/mldsa/embedded'
+import { sha3Wasm }  from 'leviathan-crypto/sha3/embedded'
+
+await init({ mldsa: mldsaWasm, sha3: sha3Wasm })
+
+const { pk, sk } = MlDsa65Suite.keygen()
+const msg = new TextEncoder().encode('hello world')
+const ctx = new TextEncoder().encode('myapp/v1')
+
+// single-shot
+const blob    = Sign.sign(MlDsa65Suite, sk, msg, ctx)
+const payload = Sign.verify(MlDsa65Suite, pk, blob, ctx)
+
+// streamed (over chunked input)
+const signer = new SignStream(MlDsa65PreHashSuite, sk, ctx)
+signer.update(chunk1)
+signer.update(chunk2)
+const sig = signer.finalize()
+// wire output is signer.preamble + chunk1 + chunk2 + sig
+```
+
+Six ML-DSA suites ship: `MlDsa44Suite` / `MlDsa65Suite` / `MlDsa87Suite` for pure ML-DSA, and `MlDsa44PreHashSuite` / `MlDsa65PreHashSuite` / `MlDsa87PreHashSuite` for HashML-DSA. See the [signing reference](https://github.com/xero/leviathan-crypto/wiki/signing) for the wire format and error reference, and the [signaturesuite reference](https://github.com/xero/leviathan-crypto/wiki/signaturesuite) for the full 22-entry catalog.
+
+**_Want belt-and-suspenders post-quantum signatures?_** Three PQ-only hybrid suites pair ML-DSA (lattice) with SLH-DSA (hash-based) at each NIST security category. The combined signature is secure as long as either family holds; a future break in one PQ assumption does not transfer to the other. The wire is one combined byte string the receiver verifies through the same `Sign` entry points.
+
+```typescript
+import { init, Sign, MlDsa65SlhDsa192fSuite } from 'leviathan-crypto'
+import { mldsaWasm }  from 'leviathan-crypto/mldsa/embedded'
+import { sha3Wasm }   from 'leviathan-crypto/sha3/embedded'
+import { slhdsaWasm } from 'leviathan-crypto/slhdsa/embedded'
+
+await init({ mldsa: mldsaWasm, sha3: sha3Wasm, slhdsa: slhdsaWasm })
+
+const { pk, sk } = MlDsa65SlhDsa192fSuite.keygen()
+const msg = new TextEncoder().encode('release manifest v1.2.3')
+const ctx = new TextEncoder().encode('release-signing/v1')
+
+const blob    = Sign.sign  (MlDsa65SlhDsa192fSuite, sk, msg, ctx)
+const payload = Sign.verify(MlDsa65SlhDsa192fSuite, pk, blob, ctx)
+// throws SigningError if either half fails to verify
+```
+
+Three hybrid suites ship at the matching NIST categories: `MlDsa44SlhDsa128fSuite` (category 1), `MlDsa65SlhDsa192fSuite` (category 3), `MlDsa87SlhDsa256fSuite` (category 5). The PQ-only hybrids complement the planned classical+PQ hybrids; the two families defend against different threat models and the [signaturesuite reference](https://github.com/xero/leviathan-crypto/wiki/signaturesuite) covers when to pick which.
+
+**_Need classical ECDSA for X.509, JWS, or TLS interop?_** [`EcdsaP256Suite`](https://github.com/xero/leviathan-crypto/wiki/signaturesuite#ecdsa-p256-suite) wraps ECDSA over NIST P-256 (FIPS 186-5 §6) with SHA-256 prehash baked in. Hedged-by-default per `draft-irtf-cfrg-det-sigs-with-noise-05`, low-S enforced on signer and verifier per RFC 6979 §3.5. Wire bytes are 64-byte raw `r || s`; the [`ecdsaSignatureToDer`](https://github.com/xero/leviathan-crypto/wiki/ecdsa-p256#der-utility) / [`ecdsaSignatureFromDer`](https://github.com/xero/leviathan-crypto/wiki/ecdsa-p256#der-utility) helpers convert between raw and the RFC 3279 §2.2.3 DER form for ecosystem interop.
+
+```typescript
+import { init, Sign, EcdsaP256Suite, ecdsaSignatureToDer } from 'leviathan-crypto'
+import { p256Wasm } from 'leviathan-crypto/ecdsa/embedded'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
+
+await init({ p256: p256Wasm, sha2: sha2Wasm })
+
+const { pk, sk } = EcdsaP256Suite.keygen()
+const msg = new TextEncoder().encode('hello world')
+const sig = Sign.signDetached(EcdsaP256Suite, sk, msg, new Uint8Array(0))
+const ok  = Sign.verifyDetached(EcdsaP256Suite, pk, msg, sig, new Uint8Array(0))
+
+const der = ecdsaSignatureToDer(sig)   // X.509 / JWS / TLS interop
+```
+
+ECDSA-P256 is classical (not post-quantum); pair it with an ML-DSA or SLH-DSA suite when the threat model assumes a future CRQC. ECDSA has no native context parameter, so `EcdsaP256Suite` rejects non-empty `user_ctx`; the reserved classical+PQ hybrid suites at `0x22` / `0x23` will provide context-bound classical+PQ signing.
+
 **_Building a secure messenger?_** The [ratchet module](https://github.com/xero/leviathan-crypto/wiki/ratchet) provides Sparse Post-Quantum Ratchet primitives for consumers who need forward secrecy and post-compromise security at the session layer. [`ratchetInit`](https://github.com/xero/leviathan-crypto/wiki/ratchet#ratchetinit) bootstraps the symmetric chains, [`KDFChain`](https://github.com/xero/leviathan-crypto/wiki/ratchet#kdfchain) derives per-message keys, [`kemRatchetEncap`](https://github.com/xero/leviathan-crypto/wiki/ratchet#kemratchetencap) / [`kemRatchetDecap`](https://github.com/xero/leviathan-crypto/wiki/ratchet#kemratchetdecap) perform the ML-KEM ratchet step, and [`SkippedKeyStore`](https://github.com/xero/leviathan-crypto/wiki/ratchet#skippedkeystore) handles out-of-order delivery.
 
 ```typescript
 import { ratchetInit, KDFChain } from 'leviathan-crypto/ratchet'
 
-await init({ sha2: sha2Wasm })   // KDF layer only; add kyber + sha3 for KEM steps
+await init({ sha2: sha2Wasm })   // KDF layer only; add mlkem + sha3 for KEM steps
 
 const { nextRootKey, sendChainKey, recvChainKey } = ratchetInit(sharedSecret)
 const chain = new KDFChain(sendChainKey)
@@ -239,15 +387,15 @@ for full construction details.
 
 **`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 self-contained browser encryption tool in a single HTML file. Encrypt text or files with Serpent-256-CBC and Argon2id key derivation, then share the armored output. No server, no install, no network connection after initial load. The code is written to be read. The Encrypt-then-MAC construction, HMAC input, and Argon2id parameters are all intentional examples worth studying.
+A self-contained browser encryption tool in a single HTML file. Encrypt text or files with Serpent-256-CBC and scrypt key derivation, then share the armored output. No server, no install, no network connection after initial load. The code is written to be read. The Encrypt-then-MAC construction, HMAC input, and scrypt parameters are all intentional examples worth studying.
 
-**`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) ]
+**`tamper`** [ [demo](https://leviathan.3xi.club/tamper) · [source](https://github.com/xero/leviathan-demos/tree/main/tamper) · [readme](https://github.com/xero/leviathan-demos/blob/main/tamper/README.md) ]
 
-End-to-end encrypted chat over X25519 key exchange and XChaCha20-Poly1305 message encryption. The relay server is a dumb WebSocket pipe that never sees plaintext. Messages carry sequence numbers so the protocol detects and rejects replayed messages. The demo deconstructs the protocol step by step with visual feedback for injection and replay attacks.
+A crypto attack-resilience demo. It runs a real two-party encrypted channel, then lets you attack it: forge a replay and the sequence check rejects it, tamper with a frame and the Poly1305 tag fails. Key exchange uses X25519 with HKDF-SHA256, message encryption uses XChaCha20-Poly1305, and the relay server is a dumb WebSocket pipe that never sees plaintext. The demo deconstructs the protocol step by step with visual feedback for injection and replay attacks. For a real, production-ready secure messenger built on the same library, see [COVCOM](https://github.com/xero/covcom).
 
 **`cli`** [ [npm](https://www.npmjs.com/package/lvthn) · [source](https://github.com/xero/leviathan-demos/tree/main/cli) · [readme](https://github.com/xero/leviathan-demos/blob/main/cli/README.md) ]
 
-Command-line file encryption tool supporting both Serpent-256 and XChaCha20-Poly1305 via `--cipher`. A single keyfile works with both ciphers. The header byte determines decryption automatically. Chunks distribute across a worker pool sized to `hardwareConcurrency`. Each worker owns an isolated WASM instance with no shared memory. The tool can export its own interactive completions for a variety of shells.
+Command-line file encryption tool supporting Serpent-256-CBC+HMAC-SHA256, XChaCha20-Poly1305, and AES-256-GCM-SIV via `--cipher`. A single keyfile works with all three ciphers. The header byte determines decryption automatically. Chunks distribute across a worker pool sized to `hardwareConcurrency`. Each worker owns an isolated WASM instance with no shared memory. The tool can export its own interactive completions for a variety of shells.
 
 ```sh
 bun add -g lvthn
@@ -259,29 +407,13 @@ cat secret.txt | lvthn encrypt -k my.key --armor > secret.enc
 
 Post-quantum cryptography demo simulating a complete ML-KEM key encapsulation ceremony between two browser-side clients. A live wire at the top of the page logs every value that crosses the channel; importantly, the shared secret never appears in the wire. After the ceremony completes, both sides independently derive a symmetric key using HKDF-SHA256 and exchange messages encrypted with XChaCha20-Poly1305. Each wire frame is expandable, revealing the raw nonce, ciphertext, Poly1305 tag, and AAD.
 
-**`COVCOM`** [ [demo](https://leviathan.3xi.club/covcom) · [source](https://github.com/xero/covcom/) · [readme](https://github.com/xero/covcom/blob/master/README.md) ]
-
-A covert communications application for end-to-end encrypted group conversations. Share an invite, talk, exit, and it's gone. Clients available for both the web and cli, along with a containerized dumb server for managing rooms. No secrets or cleartext beyond the handle you chose to join a room with are ever visible to the server. Featuring sparse post-quantum ratcheting, ML-KEM-768, KDFChains, Seal+KyberSuite, and a XChaCha20-Poly1305 core.
+**`jwt`** [ [demo](https://leviathan.3xi.club/jwt) · [source](https://github.com/xero/leviathan-demos/tree/main/jwt) · [readme](https://github.com/xero/leviathan-demos/blob/main/jwt/README.md) ]
 
----
-
-## Highlights
+Classical and post-quantum JSON Web Token signing demo in a single self-contained HTML file. It signs the same claims across eleven algorithms: EdDSA and ES256, the post-quantum ML-DSA and SLH-DSA families, and the leviathan hybrid composites. Every algorithm runs through one uniform path on the `Sign` suite API, with no per-algorithm branching. The token renders with its three segments color-coded and a live byte readout, so the cost of quantum resistance is visible: the same token grows from about 220 bytes under Ed25519 to past 66 kilobytes under SLH-DSA-SHAKE-256f. Tamper with the payload and verification rejects it, because the signature covers the original bytes.
 
-| **_I want to..._** | |
-|---|---|
-| Encrypt data | [`Seal`](https://github.com/xero/leviathan-crypto/wiki/aead#seal) with [`SerpentCipher`](https://github.com/xero/leviathan-crypto/wiki/serpent#serpentcipher) or [`XChaCha20Cipher`](https://github.com/xero/leviathan-crypto/wiki/chacha20#xchacha20cipher) |
-| Encrypt a stream or large file | [`SealStream`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstream) to encrypt, [`OpenStream`](https://github.com/xero/leviathan-crypto/wiki/aead#openstream) to decrypt |
-| Encrypt in parallel | [`SealStreamPool`](https://github.com/xero/leviathan-crypto/wiki/aead#sealstreampool) distributes chunks across Web Workers |
-| Add post-quantum security | [`KyberSuite`](https://github.com/xero/leviathan-crypto/wiki/kyber#kybersuite) wraps [`MlKem512`](https://github.com/xero/leviathan-crypto/wiki/kyber#parameter-sets), [`MlKem768`](https://github.com/xero/leviathan-crypto/wiki/kyber#parameter-sets), or [`MlKem1024`](https://github.com/xero/leviathan-crypto/wiki/kyber#parameter-sets) with any cipher suite |
-| Build a forward-secret session | [`ratchetInit`](https://github.com/xero/leviathan-crypto/wiki/ratchet#ratchetinit), [`KDFChain`](https://github.com/xero/leviathan-crypto/wiki/ratchet#kdfchain), [`kemRatchetEncap`](https://github.com/xero/leviathan-crypto/wiki/ratchet#kemratchetencap) / [`kemRatchetDecap`](https://github.com/xero/leviathan-crypto/wiki/ratchet#kemratchetdecap), [`SkippedKeyStore`](https://github.com/xero/leviathan-crypto/wiki/ratchet#skippedkeystore) |
-| Hash data | [`SHA256`](https://github.com/xero/leviathan-crypto/wiki/sha2#sha256), [`SHA384`](https://github.com/xero/leviathan-crypto/wiki/sha2#sha384), [`SHA512`](https://github.com/xero/leviathan-crypto/wiki/sha2#sha512), [`SHA3_256`](https://github.com/xero/leviathan-crypto/wiki/sha3#sha3_256), [`SHA3_512`](https://github.com/xero/leviathan-crypto/wiki/sha3#sha3_512), [`SHAKE256`](https://github.com/xero/leviathan-crypto/wiki/sha3#shake256) ... |
-| Authenticate a message | [`HMAC_SHA256`](https://github.com/xero/leviathan-crypto/wiki/sha2#hmac_sha256), [`HMAC_SHA384`](https://github.com/xero/leviathan-crypto/wiki/sha2#hmac_sha384), or [`HMAC_SHA512`](https://github.com/xero/leviathan-crypto/wiki/sha2#hmac_sha512) |
-| Derive keys | [`HKDF_SHA256`](https://github.com/xero/leviathan-crypto/wiki/sha2#hkdf_sha256) or [`HKDF_SHA512`](https://github.com/xero/leviathan-crypto/wiki/sha2#hkdf_sha512) |
-| Generate random bytes | [`Fortuna`](https://github.com/xero/leviathan-crypto/wiki/fortuna#api-reference) for forward-secret generation, [`randomBytes`](https://github.com/xero/leviathan-crypto/wiki/utils#randombytes) for one-off use |
-| Compare secrets safely | [`constantTimeEqual`](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal) uses a WASM SIMD path to prevent timing attacks |
-| Work with bytes | [`hexToBytes`](https://github.com/xero/leviathan-crypto/wiki/utils#hextobytes), [`bytesToHex`](https://github.com/xero/leviathan-crypto/wiki/utils#bytestohex), [`wipe`](https://github.com/xero/leviathan-crypto/wiki/utils#wipe), [`xor`](https://github.com/xero/leviathan-crypto/wiki/utils#xor), [`concat`](https://github.com/xero/leviathan-crypto/wiki/utils#concat) ... |
+**`COVCOM`** [ [demo](https://leviathan.3xi.club/covcom) · [source](https://github.com/xero/covcom/) · [readme](https://github.com/xero/covcom/blob/master/README.md) ]
 
-*For raw primitives, low-level cipher access, and ASM internals see the [full API reference](https://github.com/xero/leviathan-crypto/wiki/index).*
+Covert communications app suite for private group conversations. Invite, talk, close the client, and the chat vanishes. Every message is encrypted with XChaCha20 and signed with Ed25519. A BLAKE3 fingerprint on each key allows peers to verify one another. SPQR's manual and epoch ratchets add forward secrecy, while post-quantum ML-KEM-768 encapsulation keeps recorded communications unreadable and secure against future cryptanalysis.
 
 ---
 
@@ -292,6 +424,7 @@ A covert communications application for end-to-end encrypted group conversations
 | [Architecture](https://github.com/xero/leviathan-crypto/wiki/architecture) | Repository structure, module relationships, build pipeline, and buffer layouts |
 | [Test Suite](https://github.com/xero/leviathan-crypto/wiki/test-suite) | How the test suite works, vector corpus, and gate discipline |
 | [Security Policy](./SECURITY.md) | Security posture and vulnerability disclosure details |
+| [Audits](https://github.com/xero/leviathan-crypto/wiki/audits) | Every primitive has a published audit covering spec conformance, known-answer tests, constant-time discipline, and ACVP validation where applicable. |
 | [Lexicon](https://github.com/xero/leviathan-crypto/wiki/lexicon) | Glossary of cryptographic terms |
 | [WASM Primer](https://github.com/xero/leviathan-crypto/wiki/wasm) | WebAssembly primer in the context of this library |
 | [CDN](https://github.com/xero/leviathan-crypto/wiki/cdn) | Use leviathan-crypto directly from a CDN with no bundler |

package/dist/aes/aes-cbc.d.ts

@@ -0,0 +1,40 @@
+/**
+ * AES-128/192/256 in CBC mode with PKCS7 padding.
+ *
+ * **WARNING: CBC mode is unauthenticated.** Always authenticate the output
+ * with HMAC-SHA256 (Encrypt-then-MAC) or use an authenticated cipher
+ * (`XChaCha20Poly1305`, `Seal` with `SerpentCipher`) instead.
+ *
+ * Holds exclusive access to the `aes` WASM module from construction until
+ * `dispose()`. Constructing a second AES-using class while this instance
+ * is live throws. Call `dispose()` when done.
+ */
+export declare class AESCbc {
+    private readonly x;
+    private _tok;
+    constructor(opts?: {
+        dangerUnauthenticated: true;
+    });
+    /**
+     * Encrypt plaintext with AES CBC + PKCS7 padding.
+     *
+     * @param key       16, 24, or 32 bytes (AES-128 / 192 / 256)
+     * @param iv        16 bytes, must be random and unique per (key, message)
+     * @param plaintext any length, PKCS7 padding applied automatically
+     * @returns         ciphertext (length = ceil((plaintext.length + 1) / 16) * 16)
+     */
+    encrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Uint8Array;
+    /**
+     * Decrypt AES CBC + PKCS7.
+     *
+     * All failure modes, empty input, non-multiple-of-16 length, and any
+     * PKCS7 validation failure, throw the same generic `RangeError` with
+     * message `'invalid ciphertext'`. Padding validation runs branch-free
+     * over the last 16 bytes regardless of where the mismatch is, closing
+     * the Vaudenay 2002 padding-oracle surface for callers using
+     * `{ dangerUnauthenticated: true }` without an outer HMAC.
+     */
+    decrypt(key: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+    /** Wipe WASM state and release exclusive module access. Idempotent. */
+    dispose(): void;
+}

package/dist/aes/aes-cbc.js

@@ -0,0 +1,158 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/aes/aes-cbc.ts
+//
+// AESCbc, AES-128/192/256 CBC + PKCS7, stateful TS wrapper.
+// SP 800-38A §6.2 (mode), RFC 5652 §6.3 (PKCS7 padding).
+// Mirrors `src/ts/serpent/serpent-cbc.ts` exactly in shape; only the
+// underlying WASM module and the PKCS7 import path differ.
+import { getInstance, _acquireModule, _releaseModule } from '../init.js';
+import { pkcs7Pad, pkcs7Strip, PKCS7_INVALID } from '../shared/pkcs7.js';
+/** Returns the raw AES WASM export object. @internal */
+function getExports() {
+    return getInstance('aes').exports;
+}
+// ── AESCbc ──────────────────────────────────────────────────────────────────
+/**
+ * AES-128/192/256 in CBC mode with PKCS7 padding.
+ *
+ * **WARNING: CBC mode is unauthenticated.** Always authenticate the output
+ * with HMAC-SHA256 (Encrypt-then-MAC) or use an authenticated cipher
+ * (`XChaCha20Poly1305`, `Seal` with `SerpentCipher`) instead.
+ *
+ * Holds exclusive access to the `aes` WASM module from construction until
+ * `dispose()`. Constructing a second AES-using class while this instance
+ * is live throws. Call `dispose()` when done.
+ */
+export class AESCbc {
+    x;
+    _tok;
+    constructor(opts) {
+        if (!opts?.dangerUnauthenticated) {
+            throw new Error('leviathan-crypto: AESCbc is unauthenticated, use Seal with SerpentCipher or XChaCha20Cipher instead. ' +
+                'To use AESCbc directly, pass { dangerUnauthenticated: true }.');
+        }
+        this.x = getExports();
+        this._tok = _acquireModule('aes');
+    }
+    /** View over WASM linear memory. Rebind on every access, memory can be detached after grow. @internal */
+    get mem() {
+        return new Uint8Array(this.x.memory.buffer);
+    }
+    /**
+     * Encrypt plaintext with AES CBC + PKCS7 padding.
+     *
+     * @param key       16, 24, or 32 bytes (AES-128 / 192 / 256)
+     * @param iv        16 bytes, must be random and unique per (key, message)
+     * @param plaintext any length, PKCS7 padding applied automatically
+     * @returns         ciphertext (length = ceil((plaintext.length + 1) / 16) * 16)
+     */
+    encrypt(key, iv, plaintext) {
+        if (this._tok === undefined)
+            throw new Error('AESCbc: instance has been disposed');
+        this._loadKey(key);
+        this._setIv(iv);
+        const padded = pkcs7Pad(plaintext);
+        const output = new Uint8Array(padded.length);
+        const ptOff = this.x.getChunkPtOffset();
+        const ctOff = this.x.getChunkCtOffset();
+        const maxChunk = this.x.getChunkSize();
+        for (let off = 0; off < padded.length; off += maxChunk) {
+            const chunk = padded.subarray(off, Math.min(off + maxChunk, padded.length));
+            this.mem.set(chunk, ptOff);
+            const ret = this.x.cbcEncryptChunk(chunk.length);
+            if (ret < 0)
+                throw new RangeError(`cbcEncryptChunk rejected len=${chunk.length}` +
+                    ` (WASM CHUNK_SIZE=${this.x.getChunkSize()})`);
+            output.set(new Uint8Array(this.x.memory.buffer).subarray(ctOff, ctOff + chunk.length), off);
+        }
+        return output;
+    }
+    /**
+     * Decrypt AES CBC + PKCS7.
+     *
+     * All failure modes, empty input, non-multiple-of-16 length, and any
+     * PKCS7 validation failure, throw the same generic `RangeError` with
+     * message `'invalid ciphertext'`. Padding validation runs branch-free
+     * over the last 16 bytes regardless of where the mismatch is, closing
+     * the Vaudenay 2002 padding-oracle surface for callers using
+     * `{ dangerUnauthenticated: true }` without an outer HMAC.
+     */
+    decrypt(key, iv, ciphertext) {
+        if (this._tok === undefined)
+            throw new Error('AESCbc: instance has been disposed');
+        if (ciphertext.length === 0 || ciphertext.length % 16 !== 0)
+            throw new RangeError(PKCS7_INVALID);
+        this._loadKey(key);
+        this._setIv(iv);
+        const output = new Uint8Array(ciphertext.length);
+        const ctOff = this.x.getChunkCtOffset();
+        const ptOff = this.x.getChunkPtOffset();
+        const maxChunk = this.x.getChunkSize();
+        for (let off = 0; off < ciphertext.length; off += maxChunk) {
+            const chunk = ciphertext.subarray(off, Math.min(off + maxChunk, ciphertext.length));
+            this.mem.set(chunk, ctOff);
+            const ret = this.x.cbcDecryptChunk_simd(chunk.length);
+            if (ret < 0)
+                throw new RangeError(`cbcDecryptChunk_simd rejected len=${chunk.length}` +
+                    ` (WASM CHUNK_SIZE=${this.x.getChunkSize()})`);
+            output.set(new Uint8Array(this.x.memory.buffer).subarray(ptOff, ptOff + chunk.length), off);
+        }
+        return pkcs7Strip(output);
+    }
+    /** Wipe WASM state and release exclusive module access. Idempotent. */
+    dispose() {
+        if (this._tok === undefined)
+            return;
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('aes', this._tok);
+            this._tok = undefined;
+        }
+    }
+    /**
+     * Validate and load `key` into the WASM key schedule.
+     * @param key  16, 24, or 32 bytes
+     * @internal
+     */
+    _loadKey(key) {
+        if (key.length !== 16 && key.length !== 24 && key.length !== 32)
+            throw new RangeError(`AES key must be 16, 24, or 32 bytes (got ${key.length})`);
+        this.mem.set(key, this.x.getKeyOffset());
+        if (this.x.loadKey(key.length) !== 0) {
+            this.x.wipeBuffers();
+            throw new Error('AESCbc: loadKey failed');
+        }
+    }
+    /**
+     * Write `iv` into the WASM CBC IV buffer.
+     * @param iv  16 bytes
+     * @internal
+     */
+    _setIv(iv) {
+        if (iv.length !== 16)
+            throw new RangeError(`CBC IV must be 16 bytes (got ${iv.length})`);
+        this.mem.set(iv, this.x.getCbcIvOffset());
+    }
+}