leviathan-crypto 1.0.0

package/CLAUDE.md

@@ -0,0 +1,265 @@
+# leviathan-crypto — AI Assistant Guide
+
+This file ships with the package to help AI assistants use this library correctly.
+Full API documentation is in the `docs/` directory alongside this file.
+
+---
+
+## What This Library Is
+
+`leviathan-crypto` is a zero-dependency WebAssembly cryptography library for
+TypeScript and JavaScript. All cryptographic computation runs in WASM, outside
+the JavaScript JIT. The TypeScript layer provides the public API — input
+validation, type safety, and ergonomics. It never implements cryptographic
+algorithms itself.
+
+---
+
+## Critical: `init()` is required
+
+**No class works before `init()` is called.** Calling any class before its
+module is loaded throws immediately with a clear error. Call `init()` once at
+startup, before any cryptographic operations.
+
+```typescript
+import { init, SerpentSeal } from 'leviathan-crypto'
+
+await init(['serpent', 'sha2'])  // load only the modules you need
+```
+
+Available modules: `'serpent'`, `'chacha20'`, `'sha2'`, `'sha3'`
+
+---
+
+## Critical: call `dispose()` after use
+
+Every class holds WASM memory containing key material. Call `dispose()` when
+done — it zeroes that memory. Not calling `dispose()` leaks key material.
+
+```typescript
+const cipher = new SerpentSeal()
+try {
+    return cipher.encrypt(key, plaintext)
+} finally {
+    cipher.dispose()
+}
+```
+
+---
+
+## Critical: `decrypt()` throws on authentication failure — never returns null
+
+All AEAD `decrypt()` methods throw if authentication fails. Do not check for a
+null return — catch the exception.
+
+```typescript
+try {
+    const plaintext = seal.decrypt(key, ciphertext)
+} catch {
+    // wrong key or tampered data
+}
+```
+
+---
+
+## Critical: subpath init function names
+
+Each subpath export has its own module-specific init function — not `init()`.
+These are only needed for tree-shakeable imports. The root barrel `init()` is
+the normal path.
+
+| Subpath | Init function |
+|---------|---------------|
+| `leviathan-crypto/serpent` | `serpentInit()` |
+| `leviathan-crypto/chacha20` | `chacha20Init()` |
+| `leviathan-crypto/sha2` | `sha2Init()` |
+| `leviathan-crypto/sha3` | `sha3Init()` |
+
+```typescript
+// Tree-shakeable — loads only serpent WASM
+import { serpentInit, SerpentSeal } from 'leviathan-crypto/serpent'
+await serpentInit()
+```
+
+---
+
+## Which module does each class require?
+
+| Classes | `init()` call |
+|---------|--------------|
+| `SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `SerpentStreamEncoder`, `SerpentStreamDecoder`, `Serpent`, `SerpentCtr`, `SerpentCbc` | `init(['serpent', 'sha2'])` |
+| `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `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'])` |
+
+`Argon2id` is a separate subpath: `import { Argon2id } from 'leviathan-crypto/argon2id'`
+It does **not** require `init()` — it uses its own WASM loader.
+`'argon2id'` is **not** a valid module string for `init()`.
+
+---
+
+## Recommended patterns
+
+### Authenticated encryption (recommended default)
+
+```typescript
+import { init, SerpentSeal, randomBytes } from 'leviathan-crypto'
+
+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
+seal.dispose()
+```
+
+### Incremental streaming AEAD
+
+Use when you cannot buffer the full message before encrypting.
+
+```typescript
+import { init, SerpentStreamSealer, SerpentStreamOpener, randomBytes } from 'leviathan-crypto'
+
+await init(['serpent', 'sha2'])
+
+const key    = randomBytes(64)
+const sealer = new SerpentStreamSealer(key, 65536)
+const header = sealer.header()           // send to opener before any chunks
+
+const chunk0 = sealer.seal(data0)        // exactly chunkSize bytes
+const last   = sealer.final(tail)        // any size up to chunkSize; wipes key
+
+const opener = new SerpentStreamOpener(key, header)
+const pt0    = opener.open(chunk0)       // throws on auth failure
+const ptLast = opener.open(last)
+```
+
+### Length-prefixed streaming (for files and buffered transports)
+
+`SerpentStreamEncoder`/`SerpentStreamDecoder` wrap the sealer/opener with
+`u32be` length-prefixed framing so chunk boundaries are self-delimiting.
+
+```typescript
+import { init, SerpentStreamEncoder, SerpentStreamDecoder, randomBytes } from 'leviathan-crypto'
+
+await init(['serpent', 'sha2'])
+
+const key     = randomBytes(64)
+const encoder = new SerpentStreamEncoder(key, 65536)
+const header  = encoder.header()
+
+const frame0  = encoder.encode(data0)         // u32be(len) || sealed chunk
+const last    = encoder.encodeFinal(tail)
+
+const decoder = new SerpentStreamDecoder(key, header)
+const chunks  = decoder.feed(frame0)          // returns Uint8Array[], throws on auth failure
+```
+
+### XChaCha20-Poly1305
+
+```typescript
+import { init, XChaCha20Poly1305, randomBytes } from 'leviathan-crypto'
+
+await init(['chacha20'])
+
+const aead      = new XChaCha20Poly1305()
+const key       = randomBytes(32)
+const nonce     = randomBytes(24)
+const sealed    = aead.encrypt(key, nonce, plaintext, aad?)  // ciphertext || tag
+const plaintext = aead.decrypt(key, nonce, sealed, aad?)     // throws on tamper
+aead.dispose()
+```
+
+Note: `encrypt()` returns ciphertext with the 16-byte Poly1305 tag appended.
+`decrypt()` expects the same concatenated format — not separate ciphertext and tag.
+
+### Hashing
+
+```typescript
+import { init, SHA256, HMAC_SHA256 } from 'leviathan-crypto'
+
+await init(['sha2'])
+
+const hasher = new SHA256()
+const digest = hasher.hash(data)   // returns Uint8Array
+hasher.dispose()
+
+const mac = new HMAC_SHA256()
+const tag = mac.hash(key, data)
+mac.dispose()
+```
+
+### SHAKE (XOF — variable-length output)
+
+```typescript
+import { init, SHAKE128 } from 'leviathan-crypto'
+
+await init(['sha3'])
+
+const xof = new SHAKE128()
+xof.absorb(data)
+const out1 = xof.squeeze(32)   // first 32 bytes of output stream
+const out2 = xof.squeeze(32)   // next 32 bytes — contiguous XOF stream
+xof.dispose()
+```
+
+### Fortuna CSPRNG
+
+```typescript
+import { init, Fortuna } from 'leviathan-crypto'
+
+await init(['serpent', 'sha2'])
+
+const fortuna = await Fortuna.create()   // static factory — not new Fortuna()
+const bytes   = fortuna.get(32)
+fortuna.stop()
+```
+
+---
+
+## `SerpentCbc` arg order
+
+IV is the **second** argument, not the third:
+
+```typescript
+cipher.encrypt(key, iv, plaintext)   // correct
+cipher.decrypt(key, iv, ciphertext)  // correct
+```
+
+`SerpentCbc` is unauthenticated. Always pair with `HMAC_SHA256`
+(Encrypt-then-MAC) or use `SerpentSeal` instead.
+
+---
+
+## Utilities (no `init()` required)
+
+```typescript
+import { hexToBytes, bytesToHex, randomBytes, constantTimeEqual, wipe } from 'leviathan-crypto'
+
+// available immediately — no await init() needed
+const key  = randomBytes(32)
+const hex  = bytesToHex(key)
+const back = hexToBytes(hex)
+const safe = constantTimeEqual(a, b)   // constant-time equality — never use ===
+wipe(key)                               // zero a Uint8Array in place
+```
+
+---
+
+## Full documentation
+
+The complete API reference ships in `docs/` alongside this file:
+
+| File | Contents |
+|------|----------|
+| `docs/serpent.md` | `SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `SerpentStreamEncoder`, `SerpentStreamDecoder`, `Serpent`, `SerpentCtr`, `SerpentCbc` |
+| `docs/chacha20.md` | `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `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 |
+| `docs/init.md` | `init()` API, loading modes, subpath imports |
+| `docs/utils.md` | Encoding helpers, `constantTimeEqual`, `wipe`, `randomBytes` |
+| `docs/types.md` | `Hash`, `KeyedHash`, `Blockcipher`, `Streamcipher`, `AEAD` interfaces |
+| `docs/architecture.md` | Module structure, WASM layer, three-tier design |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leviathan Crypto Library
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+[![MIT Licensed](https://img.shields.io/github/license/xero/text0wnz?logo=wikiversity&logoColor=979da4&labelColor=262a2e&color=b1a268)](https://github.com/xero/text0wnz/blob/main/LICENSE)
+[![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)
+
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="Leviathan logo" width="400">
+
+# Leviathan-Crypto: Serpent-256 & XChaCha20-Poly1305 Cryptography for the Web
+
+Serpent-256, the most conservative AES finalist, employs 32 rounds and a
+maximum security margin, built to withstand future cryptanalytic advancements.
+Paired with the streamlined brilliance of ChaCha20-Poly1305, and complemented
+by SHA-2 and SHA-3. Two design philosophies, four cryptographic primitives,
+integrated into one coherent API.
+
+**WebAssembly (WASM) serves as the correctness layer.** It features spec-driven and
+vector-verified AssemblyScript implementations of Serpent-256, ChaCha20/Poly1305,
+SHA-2, and SHA-3. Each cryptographic primitive is compiled into its own isolated
+binary, executing outside the JavaScript JIT. This ensures no speculative
+optimization affects key material and eliminates data-dependent timing
+vulnerabilities from table lookups.
+
+**TypeScript acts as the ergonomics layer.** Fully typed classes, explicit
+`init()` gates, input validation, and authenticated compositions
+([`SerpentSeal`](https://github.com/xero/leviathan-crypto/wiki/serpent#serpentseal),
+[`SerpentStream`](https://github.com/xero/leviathan-crypto/wiki/serpent#serpentstream),
+[`SerpentStreamSealer`](https://github.com/xero/leviathan-crypto/wiki/serpent#serpentstreamsealer--serpentstreamopener))
+ensure primitives are connected correctly, simplifying development and ensuring
+correctness. Advanced users retain the ability to directly access the raw block
+cipher classes.
+
+## Why Serpent-256
+
+Serpent-256, an AES finalist, received more first-place security votes than
+Rijndael from the NIST evaluation committee. It was designed with a larger
+security margin: 32 rounds compared to AES's 10, 12, or 14.
+
+While Serpent won on security margin, AES (Rijndael) ultimately won the
+competition due to its  performance. Rijndael was selected because speed
+was paramount for the hardware and embedded targets NIST was optimizing for
+in 2001. However, for software running on modern hardware where milliseconds
+of encryption latency are acceptable, this tradeoff is no longer as relevant.
+
+**Security Margin.** Serpent has been a target of cryptanalytic research
+since the AES competition. The current state-of-the-art is as follows:
+
+- **Best known reduced-round attack:**
+    - multidimensional linear cryptanalysis reaching 12 of 32 rounds (Nguyen,
+      Wu & Wang, ACISP 2011), less than half the full cipher, requiring 2¹¹⁸
+      known plaintexts and 2²²⁸·⁸ time.
+    - Multidimensional linear cryptanalysis reaches 12 of 32 rounds (Nguyen,
+      Wu & Wang, ACISP 2011), less than half the full cipher. This requires
+      2¹¹⁸ known plaintexts and 2²²⁸·⁸ time. [source](https://personal.ntu.edu.sg/wuhj/research/publications/2011_ACISP_MLC.pdf) & [mirror](https://archive.is/6pwMM)
+- **Best known full-round attack:**
+    - biclique cryptanalysis of full 32-round Serpent-256 (de Carvalho & Kowada,
+      SBSeg 2020), time complexity 2²⁵⁵·²¹, only 0.79 bits below the 256-bit
+      brute-force ceiling of 2²⁵⁶, and requires 2⁸⁸ chosen ciphertexts, making
+      it strictly less practical than brute force. For comparison, the analogous
+      biclique attack on full-round AES-256 (Bogdanov et al., 2011) reaches
+      2²⁵⁴·⁴. Serpent-256 is marginally harder to attack by this method than AES-256.
+    - Biclique cryptanalysis of full 32-round Serpent-256 (de Carvalho & Kowada,
+      SBSeg 2020) has a time complexity of 2²⁵⁵·²¹, only 0.79 bits below the 256-bit
+      brute-force ceiling of 2²⁵⁶. It requires 2⁸⁸ chosen ciphertexts, making it
+      strictly less practical than brute force. For comparison, the analogous biclique
+      attack on full-round AES-256 (Bogdanov et al., 2011) reaches 2²⁵⁴·⁴.
+      Serpent-256 is marginally harder to attack by this method than AES-256. [source](https://sol.sbc.org.br/index.php/sbseg/article/view/19225/19054) & [mirror](https://archive.is/ZZjrT)
+    - Our independent research improved the published result by
+      −0.20 bits through systematic search over v position, biclique nibble
+      selection, and nabla pair. the best configuration (K31/K17, delta nibble 0,
+      nabla nibble 10, v = state 66 nibbles 8+9) achieves 2²⁵⁵·¹⁹ with only 2⁴
+      chosen ciphertexts. The K17 nabla result is a new finding not present in
+      the published papers.
+    - Our independent research improved the published result by −0.20 bits through
+      systematic search over v position, biclique nibble selection, and nabla pair.
+      The best configuration (K31/K17, delta nibble 0, nabla nibble 10, v = state
+      66 nibbles 8+9) achieves 2²⁵⁵·¹⁹ with only 2⁴ chosen ciphertexts. The K17 nabla
+      result is a new finding not present in the published papers. [`biclique_research`](https://github.com/xero/BicliqueFinder/blob/main/biclique-research.md)
+
+See: [`serpent_audit.md`](https://github.com/xero/leviathan-crypto/wiki/serpent_audit)
+for the full analysis.
+
+**Implementation.** Implementation: Serpent's S-boxes are implemented as Boolean gate
+circuits, meaning there are no table lookups, data-dependent memory access, or
+data-dependent branches. Every bit is processed unconditionally on every block.
+This approach provides the most timing-safe cipher implementation available in a
+JavaScript runtime, where JIT optimization can otherwise introduce observable
+timing variations.
+
+**Key Size:** The default API only supports 256-bit keys. The absence of 128 or
+192-bit variants mitigates the risk of key-size downgrade attacks.
+
+## Primitives
+
+| Classes | Module | Auth | Notes |
+|---------|--------|------|-------|
+| `SerpentSeal` | `serpent`, `sha2` | **Yes** | Authenticated encryption: Serpent-CBC + HMAC-SHA256. Recommended for most use cases. |
+| `SerpentStream`, `SerpentStreamPool` | `serpent`, `sha2` | **Yes** | Chunked one-shot AEAD for large payloads. Pool variant parallelises across workers. |
+| `SerpentStreamSealer`, `SerpentStreamOpener` | `serpent`, `sha2` | **Yes** | Incremental streaming AEAD: seal and open one chunk at a time without buffering the full message. |
+| `SerpentStreamEncoder`, `SerpentStreamDecoder` | `serpent`, `sha2` | **Yes** | Length-prefixed framing over SerpentStreamSealer/Opener for flat byte streams (files, buffered TCP). |
+| `Serpent`, `SerpentCtr`, `SerpentCbc` | `serpent` | **No** | Raw ECB, CTR, CBC modes. Pair with HMAC-SHA256 for authentication. |
+| `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305` | `chacha20` | Yes (AEAD) | RFC 8439 |
+| `SHA256`, `SHA384`, `SHA512`, `HMAC_SHA256`, `HMAC_SHA384`, `HMAC_SHA512` | `sha2` | -- | FIPS 180-4, RFC 2104 |
+| `HKDF_SHA256`, `HKDF_SHA512` | `sha2` | -- | Key derivation: RFC 5869. Extract-and-expand over HMAC. |
+| `SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256` | `sha3` | -- | FIPS 202 |
+| `Fortuna` | `fortuna` | -- | Fortuna CSPRNG (Ferguson & Schneier). Requires `Fortuna.create()`. |
+
+>[!IMPORTANT]
+> All cryptographic computation runs in WASM (AssemblyScript), isolated outside the JavaScript JIT.
+> The TypeScript layer provides the public API with input validation, type safety, and developer ergonomics.
+
+## Quick Start
+
+### Authenticated encryption with Serpent (recommended)
+
+```typescript
+import { init, SerpentSeal, randomBytes } from 'leviathan-crypto'
+
+await init(['serpent', 'sha2'])
+
+const key = randomBytes(64)  // 64-byte key (encKey + macKey)
+
+const seal = new SerpentSeal()
+
+// Encrypt and authenticate
+const ciphertext = seal.encrypt(key, plaintext)
+
+// Decrypt and verify (throws on tamper)
+const decrypted = seal.decrypt(key, ciphertext)
+
+seal.dispose()
+```
+
+### Incremental streaming AEAD
+
+Use `SerpentStreamSealer` when data arrives chunk by chunk and you cannot
+buffer the full message before encrypting.
+
+```typescript
+import { init, SerpentStreamSealer, SerpentStreamOpener, randomBytes } from 'leviathan-crypto'
+
+await init(['serpent', 'sha2'])
+
+const key = randomBytes(64)
+
+// Seal side
+const sealer = new SerpentStreamSealer(key, 65536)
+const header = sealer.header()       // transmit to opener before any chunks
+
+const chunk0 = sealer.seal(data0)    // exactly chunkSize bytes
+const chunk1 = sealer.seal(data1)
+const last   = sealer.final(tail)    // any size up to chunkSize; wipes key on return
+
+// Open side
+const opener = new SerpentStreamOpener(key, header)
+
+const pt0 = opener.open(chunk0)
+const pt1 = opener.open(chunk1)
+const ptN = opener.open(last)        // detects final chunk; wipes key on return
+
+// Reordering, truncation, and cross-stream splicing all throw on open()
+```
+
+### Large payload chunking
+
+```typescript
+import { init, SerpentStream, randomBytes } from 'leviathan-crypto'
+
+await init(['serpent', 'sha2'])
+
+const key = randomBytes(32)  // 32-byte key (HKDF handles expansion internally)
+
+const stream = new SerpentStream()
+const ciphertext = stream.seal(key, largePlaintext)   // default 64KB chunks
+const decrypted  = stream.open(key, ciphertext)
+
+stream.dispose()
+```
+
+### Fortuna CSPRNG
+
+```typescript
+import { init, Fortuna } from 'leviathan-crypto'
+
+await init(['serpent', 'sha2'])
+
+const fortuna = await Fortuna.create()
+const random = fortuna.get(32)  // 32 random bytes
+
+fortuna.stop()
+```
+
+### Hashing with SHA-3
+
+```typescript
+import { init, SHA3_256 } from 'leviathan-crypto'
+
+await init(['sha3'])
+
+const hasher = new SHA3_256()
+const digest = hasher.hash(new TextEncoder().encode('hello'))
+// digest is a 32-byte Uint8Array
+
+hasher.dispose()
+```
+
+## Utilities
+
+These helpers are available immediately on import: no `init()` required.
+
+| Function | Description |
+|----------|-------------|
+| `hexToBytes(hex)` | Hex string to `Uint8Array` (accepts uppercase, `0x` prefix) |
+| `bytesToHex(bytes)` | `Uint8Array` to lowercase hex string |
+| `utf8ToBytes(str)` | UTF-8 string to `Uint8Array` |
+| `bytesToUtf8(bytes)` | `Uint8Array` to UTF-8 string |
+| `base64ToBytes(b64)` | Base64/base64url string to `Uint8Array` (undefined on invalid) |
+| `bytesToBase64(bytes, url?)` | `Uint8Array` to base64 string (url=true for base64url) |
+| `constantTimeEqual(a, b)` | Constant-time byte comparison (XOR-accumulate) |
+| `wipe(data)` | Zero a typed array in place |
+| `xor(a, b)` | XOR two equal-length `Uint8Array`s |
+| `concat(a, b)` | Concatenate two `Uint8Array`s |
+| `randomBytes(n)` | Cryptographically secure random bytes via Web Crypto |
+
+## Authentication Warning
+
+`SerpentCtr` and `SerpentCbc` are **unauthenticated** cipher modes. They provide
+confidentiality but not integrity or authenticity. An attacker can modify
+ciphertext without detection.
+
+>[!TIP]
+> **For authenticated Serpent encryption:** use [`SerpentSeal`](https://github.com/xero/leviathan-crypto/wiki/serpent#serpentseal) or [`SerpentStreamSealer`](https://github.com/xero/leviathan-crypto/wiki/serpent#serpentstreamsealer--serpentstreamopener)
+>
+> **Using Serpent CBC/CTR directly:** pair with `HMAC_SHA256` using the Encrypt-then-MAC pattern
+
+>[!NOTE]
+> **[`SerpentStream`](https://github.com/xero/leviathan-crypto/wiki/serpent#serpentstream) and [`SerpentStreamSealer`](https://github.com/xero/leviathan-crypto/wiki/serpent#serpentstreamsealer--serpentstreamopener)
+> inherently satisfy the Cryptographic Doom Principle.** Message Authentication Code (MAC)
+> verification is the mandatory check on every `open()` call; decryption is impossible until
+> this verification succeeds. Per-chunk HKDF key derivation, using position-bound info,
+> extends this protection to stream integrity. Reordering, truncation, and cross-stream
+> substitution are all detected at the MAC layer, preventing any plaintext from being
+> produced in such cases. [Full analysis.](https://github.com/xero/leviathan-crypto/wiki/serpent_audit#24-serpentstream-encrypt-then-mac-and-the-cryptographic-doom-principle)
+
+## Installation
+
+```bash
+# use bun
+bun i leviathan-crypto
+# or npm
+npm install leviathan-crypto
+```
+
+## Loading Modes
+
+```typescript
+// Embedded (default): zero-config, base64-encoded WASM inline
+await init(['serpent', 'sha3'])
+
+// Streaming: uses instantiateStreaming for performance
+await init(['serpent'], 'streaming', { wasmUrl: '/assets/wasm/' })
+
+// Manual: provide your own binary
+await init(['serpent'], 'manual', { wasmBinary: { serpent: myBuffer } })
+```
+
+## Documentation
+
+**Full API documentation:** [./docs](./docs/README.md)
+
+| Module | Description |
+|--------|-------------|
+| [serpent.md](./docs/serpent.md) | Serpent-256 TypeScript API (`SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `Serpent`, `SerpentCtr`, `SerpentCbc`) |
+| [asm_serpent.md](./docs/asm_serpent.md) | Serpent-256 WASM implementation (bitslice S-boxes, key schedule, CTR/CBC) |
+| [chacha20.md](./docs/chacha20.md) | ChaCha20/Poly1305 TypeScript API (`ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`) |
+| [asm_chacha.md](./docs/asm_chacha.md) | ChaCha20/Poly1305 WASM implementation (quarter-round, HChaCha20) |
+| [sha2.md](./docs/sha2.md) | SHA-2 TypeScript API (`SHA256`, `SHA512`, `SHA384`, `HMAC_SHA256`, `HMAC_SHA512`, `HMAC_SHA384`) |
+| [asm_sha2.md](./docs/asm_sha2.md) | SHA-2 WASM implementation (compression functions, HMAC) |
+| [sha3.md](./docs/sha3.md) | SHA-3 TypeScript API (`SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256`) |
+| [asm_sha3.md](./docs/asm_sha3.md) | SHA-3 WASM implementation (Keccak-f[1600], sponge construction) |
+| [fortuna.md](./docs/fortuna.md) | Fortuna CSPRNG (forward secrecy, 32 entropy pools) |
+| [init.md](./docs/init.md) | `init()` API and WASM loading modes |
+| [utils.md](./docs/utils.md) | Encoding helpers, `constantTimeEqual`, `wipe`, `randomBytes` |
+| [types.md](./docs/types.md) | TypeScript interfaces (`Hash`, `KeyedHash`, `Blockcipher`, `Streamcipher`, `AEAD`) |
+| [architecture.md](./docs/architecture.md.md) | Architecture overview, build pipeline, module relationships |
+| [test-suite.md](./test-suite.md) | Test suite structure, vector corpus, gate discipline |
+
+## License
+leviathan is written under the [MIT license](http://www.opensource.org/licenses/MIT).
+
+```
+  ██     ▐█████ ██     ▐█▌  ▄█▌   ███▌ ▀███████▀▄██▌  ▐█▌  ███▌    ██▌   ▓▓
+ ▐█▌     ▐█▌    ▓█     ▐█▌  ▓██  ▐█▌██    ▐█▌   ███   ██▌ ▐█▌██    ▓██   ██
+ ██▌     ░███   ▐█▌    ██   ▀▀   ██ ▐█▌   ██   ▐██▌   █▓  ▓█ ▐█▌  ▐███▌  █▓
+ ██      ██     ▐█▌    █▓  ▐██  ▐█▌  █▓   ██   ▐██▄▄ ▐█▌ ▐█▌  ██  ▐█▌██ ▐█▌
+▐█▌     ▐█▌      ██   ▐█▌  ██   ██   ██  ▐█▌   ██▀▀████▌ ██   ██  ██ ▐█▌▐█▌
+▐▒▌     ▐▒▌      ▐▒▌  ██   ▒█   ██▀▀▀██▌ ▐▒▌   ▒█    █▓░ ▒█▀▀▀██▌ ▒█  ██▐█
+█▓ ▄▄▓█ █▓ ▄▄▓█   ▓▓ ▐▓▌  ▐▓▌  ▐█▌   ▐▒▌ █▓   ▐▓▌   ▐▓█ ▐▓▌   ▐▒▌▐▓▌  ▐███
+▓██▀▀   ▓██▀▀      ▓█▓█   ▐█▌  ▐█▌   ▐▓▌ ▓█   ▐█▌   ▐█▓ ▐█▌   ▐▓▌▐█▌   ██▓
+                    ▓█         ▄▄▄▄▄▄▄▄▄▄            ▀▀        ▐█▌▌▌
+                        ▄████████████████████▄▄
+                     ▄██████████████████████ ▀████▄
+                   ▄█████████▀▀▀     ▀███████▄▄███████▌
+                  ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+                  ████████      ███▀▀     ████▀  █▀ █▀
+                  ███████▌    ▀██▀         ██
+                   ███████   ▀███           ▀██ ▀█▄
+                    ▀██████   ▄▄██            ▀▀  ██▄
+                      ▀█████▄   ▄██▄             ▄▀▄▀
+                         ▀████▄   ▄██▄
+                           ▐████   ▐███
+                    ▄▄██████████    ▐███         ▄▄
+                 ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+               ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███
+                ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀
+               ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄
+               █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄███▀
+               ▀██████▀             ▀████▄▄▄████▀
+                                       ▀█████▀
+
+       Serpent256 & Xchacha20-Poly1305 Cryptography for the Web
+```