leviathan-crypto 2.0.1 → 3.0.0

package/CLAUDE.md

@@ -1,320 +1,127 @@
-# leviathan-crypto — AI Assistant Guide
+# leviathan-crypto: AI Assistant Guide
 
 > [!NOTE]
-> 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.
+> Ships with the npm package. Inside the repo? Read `AGENTS.md` instead.
 
-> ### Table of Contents
-> - [What This Library Is](#what-this-library-is)
-> - [Critical: `init()` is required](#critical-init-is-required)
-> - [Critical: call `dispose()` after use](#critical-call-dispose-after-use)
-> - [Critical: `decrypt()` throws on authentication failure](#critical-decrypt-throws-on-authentication-failure--never-returns-null)
-> - [Critical: subpath init function names](#critical-subpath-init-function-names)
-> - [Which module does each class require?](#which-module-does-each-class-require)
-> - [Recommended patterns](#recommended-patterns)
-> - [`SerpentCbc` arg order](#serpentcbc-arg-order)
-> - [Utilities (no `init()` required)](#utilities-no-init-required)
-> - [Full documentation](#full-documentation)
+## What this is
 
----
+Zero-dependency WASM crypto for TS/JS. All compute in WASM (outside JS JIT); TS layer = input validation + ergonomics.
 
-## What This Library Is
+| Family | Primitives |
+|---|---|
+| Symmetric AEAD | Serpent-256, XChaCha20-Poly1305, AES-256-GCM-SIV |
+| Post-quantum sig | ML-DSA, SLH-DSA, PQ-only hybrid composites |
+| Classical sig | Ed25519, ECDSA-P256, classical+PQ hybrid composites |
+| Key agreement | ML-KEM, X25519 |
+| Transparency log | Merkle log (C2SP-conformant) |
+| Forward-secret ratchet | Signal SPQR KDF (rule 8) |
 
-`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.
+## API shape
 
----
+Two hierarchies, one suite extension point. Tier = data shape. Suite = crypto choice.
 
-## Critical: `init()` is required
+| Tier | AEAD | Signatures |
+|---|---|---|
+| One-shot | Seal | Sign |
+| Streaming | SealStream / OpenStream | SignStream / VerifyStream |
+| Parallel | SealStreamPool (Web Workers) | n/a |
+| Suite arg | CipherSuite | SignatureSuite |
 
-**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.
+`Seal` blob = single-chunk `SealStream` output (interchangeable). Symmetric: `SerpentCipher`, `XChaCha20Cipher`, `AESGCMSIVCipher`. `MlKemSuite(MlKem*, inner)` wraps any of them for PQ hybrid (same `CipherSuite` interface).
 
-```typescript
-import { init, Serpent } from 'leviathan-crypto'
-import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
-import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded'
-
-await init({ serpent: serpentWasm, sha2: sha2Wasm })
-```
-
-`init()` accepts a `Partial<Record<Module, WasmSource>>`. Each value is a
-`WasmSource`: a gzip+base64 string, `URL`, `ArrayBuffer`, `Uint8Array`,
-pre-compiled `WebAssembly.Module`, `Response`, or `Promise<Response>`.
-
-The `/embedded` subpath exports are the simplest WasmSource: they are the
-gzip+base64 blobs for each module, bundled with the package.
-
----
-
-## 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 XChaCha20Poly1305()
-try {
-    return cipher.encrypt(key, nonce, 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.
-
-Each init function takes a single `WasmSource` argument. Use the module's
-`/embedded` subpath to get the bundled blob as a ready-to-use WasmSource.
-
-| Subpath | Init function | Embedded blob |
-|---------|---------------|---------------|
-| `leviathan-crypto/serpent` | `serpentInit(source)` | `leviathan-crypto/serpent/embedded` → `serpentWasm` |
-| `leviathan-crypto/chacha20` | `chacha20Init(source)` | `leviathan-crypto/chacha20/embedded` → `chacha20Wasm` |
-| `leviathan-crypto/sha2` | `sha2Init(source)` | `leviathan-crypto/sha2/embedded` → `sha2Wasm` |
-| `leviathan-crypto/sha3` | `sha3Init(source)` | `leviathan-crypto/sha3/embedded` → `sha3Wasm` |
-| `leviathan-crypto/keccak` | `keccakInit(source)` | `leviathan-crypto/keccak/embedded` → `keccakWasm` |
-| `leviathan-crypto/kyber` | `kyberInit(source)` | `leviathan-crypto/kyber/embedded` → `kyberWasm` |
-
-```typescript
-// Tree-shakeable — loads only serpent WASM
-import { serpentInit, Serpent } from 'leviathan-crypto/serpent'
-import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
-await serpentInit(serpentWasm)
-```
-
----
-
-## Which module does each class require?
-
-| Classes | Required modules |
-|---------|-----------------|
-| `Serpent`, `SerpentCtr`, `SerpentCbc`, `SerpentCipher` | `init({ serpent: serpentWasm, sha2: sha2Wasm })` |
-| `SealStream`, `OpenStream`, `SerpentCipher` (when using SerpentCipher) | `init({ serpent: serpentWasm, sha2: sha2Wasm })` |
-| `SealStream`, `OpenStream`, `XChaCha20Cipher` (when using XChaCha20Cipher) | `init({ chacha20: chacha20Wasm, sha2: sha2Wasm })` |
-| `SealStreamPool` | depends on cipher: same modules as the cipher suite + `sha2` |
-| `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305` | `init({ chacha20: chacha20Wasm })` |
-| `SHA256`, `SHA384`, `SHA512`, `HMAC_SHA256`, `HMAC_SHA384`, `HMAC_SHA512`, `HKDF_SHA256`, `HKDF_SHA512` | `init({ sha2: sha2Wasm })` |
-| `SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256` | `init({ sha3: sha3Wasm })` or `init({ keccak: keccakWasm })` — `'keccak'` is an alias for `'sha3'` |
-| `MlKem512`, `MlKem768`, `MlKem1024` | `init({ kyber: kyberWasm, sha3: sha3Wasm })` — both modules required |
-| `Fortuna` | `init({ serpent: serpentWasm, sha2: sha2Wasm })` |
-
----
-
-## Recommended patterns
-
-### Authenticated encryption (recommended default)
-
-```typescript
-import { init, Seal, SerpentCipher, randomBytes } from 'leviathan-crypto'
-import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
-import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded'
+**Prefer the high-level surface (Seal / Sign / Fortuna).** Handles KDF, nonce management, auth, key wipes, counter binding. Rejects tampered/reordered/spliced inputs before plaintext release. Low-level primitives (raw `ChaCha20`, `SerpentCbc`, etc.) require reading their wiki page first.
 
-await init({ serpent: serpentWasm, sha2: sha2Wasm })
-
-const key       = SerpentCipher.keygen()
-const blob      = Seal.encrypt(SerpentCipher, key, plaintext)
-const decrypted = Seal.decrypt(SerpentCipher, key, blob)
-```
-
-### Incremental streaming AEAD
-
-Use when you cannot buffer the full message before encrypting.
-
-```typescript
-import { init, SealStream, OpenStream, SerpentCipher, randomBytes } from 'leviathan-crypto'
-import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
-import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
-
-await init({ serpent: serpentWasm, sha2: sha2Wasm })
-
-const key    = randomBytes(32)
-const sealer = new SealStream(SerpentCipher, key)
-const preamble = sealer.preamble        // 20 bytes — send first
-const ct0      = sealer.push(chunk0)
-const ct1      = sealer.push(chunk1)
-const ctLast   = sealer.finalize(lastChunk)
-
-const opener   = new OpenStream(SerpentCipher, key, preamble)
-const pt0    = opener.pull(ct0)
-const pt1    = opener.pull(ct1)
-const ptLast = opener.finalize(ctLast)
-```
-
-### Length-prefixed streaming (for files and buffered transports)
-
-Pass `{ framed: true }` to `SealStream` for self-delimiting `u32be` length-prefixed
-framing. Use when chunks will be concatenated into a flat byte stream. Omit when the
-transport frames messages itself (WebSocket, IPC).
-
-```typescript
-const sealer = new SealStream(SerpentCipher, key, { framed: true })
-```
-
-### XChaCha20-Poly1305
-
-```typescript
-import { init, XChaCha20Poly1305, randomBytes } from 'leviathan-crypto'
-import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
-
-await init({ chacha20: chacha20Wasm })
-
-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()
-```
+## Rules (cross-cutting foot-guns)
 
-Note: `encrypt()` returns ciphertext with the 16-byte Poly1305 tag appended.
-`decrypt()` expects the same concatenated format, not separate ciphertext and tag.
+1. **`init()` required.** Nothing works before `init()`. Throws on missing module. Idempotent. Use `/embedded` subpath for bundled gzip+base64 blob.
 
-### Hashing
+2. **`dispose()` stateful in `finally`.** Stateful classes hold key material in WASM until `dispose()` zeros it. Wrap in `try { ... } finally { x.dispose() }`. Atomic one-shots (`Seal.encrypt`, `Sign.sign`, hashes, MACs) self-wipe.
 
-```typescript
-import { init, SHA256, HMAC_SHA256 } from 'leviathan-crypto'
-import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
+3. **Stateful = exclusive module access.** A stateful class (`SHAKE128`, `ChaCha20`, `SerpentCtr/Cbc`, `SealStream`, `MlKem*`, etc.) owns its WASM module for its lifetime. Second stateful instance on same module throws. Atomic methods on same module throw while a stateful holder is alive. Pool workers isolated.
 
-await init({ sha2: sha2Wasm })
+4. **AEAD `decrypt()` throws on auth failure.** `Seal.decrypt`, AEAD `decrypt()`, `OpenStream.pull` never return null or corrupted plaintext. Wrong key, tampered blob, corrupted bytes all surface as exceptions.
 
-const hasher = new SHA256()
-const digest = hasher.hash(data)   // returns Uint8Array
-hasher.dispose()
+5. **Raw `verify()` returns bool. `Sign.verify` throws.** Raw primitives (`MlDsa*.verify`, `SlhDsa*.verify`, hybrid `verifyPrehashed`) return `false` on bad sig; only contract violations throw. `Sign.verify` envelope throws on bad sig (parity with `Seal.decrypt`).
 
-const mac = new HMAC_SHA256()
-const tag = mac.hash(key, data)
-mac.dispose()
-```
+6. **Pure-mode and prehash sigs NOT interchangeable.** `dsa.sign` vs `dsa.verifyHash` bind different M' domain bytes (0x00 vs 0x01, FIPS 204 §3.6.4 / FIPS 205 §10.2.2). Sigs don't cross even with identical messages. SignatureSuite enforces at the type level.
 
-### SHAKE (XOF — variable-length output)
+7. **v3 sign envelope: `ctx` required.** `Sign.sign` / `Sign.verify` / `SignStream` / `VerifyStream` all require `ctx`. Pass `new Uint8Array()` for empty. Each suite prepends `ctxDomain` (blocks cross-suite verify). Per-call `ctx` ≤ 255 bytes (FIPS 204 §3.6.1); longer throws `SigningError('sig-ctx-too-long')`. Per-call ceiling = `253 - len(ctxDomain)` (221-234 bytes across catalog).
 
-```typescript
-import { init, SHAKE128 } from 'leviathan-crypto'
-import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
+8. **Ratchet = KDF primitives, not a session.** Forward secrecy + post-compromise security primitives only. State machine, message counters, header format, epoch orchestration, transport = app concerns. NOT a drop-in Signal client.
 
-await init({ sha3: sha3Wasm })
+## Subpath imports
 
-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()
-```
+Pattern: `leviathan-crypto/<mod>` exports `<mod>Init(source)`; `leviathan-crypto/<mod>/embedded` exports `<mod>Wasm`. Twelve modules: `serpent`, `chacha20`, `aes`, `sha2`, `sha3`, `keccak`, `mlkem`, `mldsa`, `slhdsa`, `blake3`, `curve25519`, `p256`.
 
-### ML-KEM post-quantum key encapsulation
+Aliases share binary + instance slot:
 
-```typescript
-import { init, MlKem768 } from 'leviathan-crypto'
-import { kyberWasm } from 'leviathan-crypto/kyber/embedded'
-import { sha3Wasm } from 'leviathan-crypto/sha3/embedded'
+| Alias | Backed by |
+|---|---|
+| keccak | sha3 |
+| ed25519 | curve25519 |
+| x25519 | curve25519 |
+| ecdsa | p256 |
 
-await init({ kyber: kyberWasm, sha3: sha3Wasm })
+No `/embedded`: `leviathan-crypto/ratchet`, `leviathan-crypto/stream`, `leviathan-crypto/sign`, `leviathan-crypto/merkle`.
 
-const kem = new MlKem768()
-const { encapsulationKey, decapsulationKey } = kem.keygen()
+## Class → init modules + wiki
 
-// Encapsulation (sender — public encapsulationKey only)
-const { ciphertext, sharedSecret: senderSecret } = kem.encapsulate(encapsulationKey)
+| Class | init modules | wiki |
+|---|---|---|
+| Seal / SealStream / OpenStream / SealStreamPool | varies by suite | https://github.com/xero/leviathan-crypto/wiki/aead |
+| SerpentCipher | serpent, sha2 | https://github.com/xero/leviathan-crypto/wiki/serpent |
+| XChaCha20Cipher | chacha20, sha2 | https://github.com/xero/leviathan-crypto/wiki/chacha20 |
+| AESGCMSIVCipher | aes, sha2 | https://github.com/xero/leviathan-crypto/wiki/aes |
+| MlKemSuite(MlKem*, inner) | mlkem, sha3 + inner | https://github.com/xero/leviathan-crypto/wiki/mlkem |
+| Sign / SignStream / VerifyStream | varies by suite | https://github.com/xero/leviathan-crypto/wiki/signing |
+| MlDsa{44,65,87}Suite (pure, prehash) | mldsa, sha3 (+sha2 for SHA-2 prehash) | https://github.com/xero/leviathan-crypto/wiki/mldsa |
+| SlhDsa{128f,192f,256f}Suite | slhdsa, sha3 (+sha2 for SHA-2 prehash) | https://github.com/xero/leviathan-crypto/wiki/slhdsa |
+| Ed25519Suite / Ed25519PreHashSuite | curve25519 (+sha2 for PreHash) | https://github.com/xero/leviathan-crypto/wiki/ed25519 |
+| EcdsaP256Suite (hedged, low-S) | p256, sha2 | https://github.com/xero/leviathan-crypto/wiki/ecdsa-p256 |
+| MlDsa{44,65}Ed25519Suite (0x20, 0x21) | mldsa, sha3, curve25519, sha2 | https://github.com/xero/leviathan-crypto/wiki/signaturesuite |
+| MlDsa{44,65}EcdsaP256Suite (0x22, 0x23) | mldsa, sha3, p256, sha2 | https://github.com/xero/leviathan-crypto/wiki/signaturesuite |
+| MlDsa{44,65,87}SlhDsa{128f,192f,256f}Suite (0x30-0x32) | mldsa, sha3, slhdsa | https://github.com/xero/leviathan-crypto/wiki/signaturesuite |
+| X25519 | curve25519 | https://github.com/xero/leviathan-crypto/wiki/x25519 |
+| MerkleVerifier / MerkleLog | sha2 + suite (+blake3 if `hashing: 'blake3'`) | https://github.com/xero/leviathan-crypto/wiki/merkle |
+| Sparse PQ Ratchet (KDF, rule 8) | sha2, mlkem, sha3 | https://github.com/xero/leviathan-crypto/wiki/ratchet |
+| Fortuna | one cipher + one hash | https://github.com/xero/leviathan-crypto/wiki/fortuna |
+| SHA-2 / HMAC / HKDF | sha2 | https://github.com/xero/leviathan-crypto/wiki/sha2 |
+| SHA-3 / SHAKE | sha3 | https://github.com/xero/leviathan-crypto/wiki/sha3 |
+| CSHAKE / KMAC / KMACXOF | sha3 | https://github.com/xero/leviathan-crypto/wiki/kmac |
+| BLAKE3 family | blake3 | https://github.com/xero/leviathan-crypto/wiki/blake3 |
 
-// Decapsulation (recipient — private decapsulationKey)
-const recipientSecret = kem.decapsulate(decapsulationKey, ciphertext)
+Other refs:
 
-// senderSecret === recipientSecret (32 bytes)
-kem.dispose()
-```
+| Topic | wiki |
+|---|---|
+| init() / WasmSource | https://github.com/xero/leviathan-crypto/wiki/init |
+| Loading strategies | https://github.com/xero/leviathan-crypto/wiki/loader |
+| CDN usage | https://github.com/xero/leviathan-crypto/wiki/cdn |
+| Content-Security-Policy | https://github.com/xero/leviathan-crypto/wiki/csp |
+| Worked examples | https://github.com/xero/leviathan-crypto/wiki/examples |
+| Utilities | https://github.com/xero/leviathan-crypto/wiki/utils |
+| Argon2id integration | https://github.com/xero/leviathan-crypto/wiki/argon2id |
+| CipherSuite interface | https://github.com/xero/leviathan-crypto/wiki/ciphersuite |
+| SignatureSuite catalog | https://github.com/xero/leviathan-crypto/wiki/signaturesuite |
 
-Kyber classes require **both** `kyber` and `sha3` initialized. ML-KEM produces
-a 32-byte shared secret suitable for use as a symmetric key.
+## Canonical example
 
-### Fortuna CSPRNG
+`Seal` + `SerpentCipher` round-trip:
 
 ```typescript
-import { init, Fortuna } from 'leviathan-crypto'
+import { init, Seal, SerpentCipher } from 'leviathan-crypto'
 import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
 import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded'
 
 await init({ serpent: serpentWasm, sha2: sha2Wasm })
 
-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 `Seal` with `SerpentCipher` instead.
-
----
-
-## Utilities (no `init()` required)
-
-```typescript
-import { hexToBytes, bytesToHex, randomBytes, constantTimeEqual, wipe, hasSIMD } 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
+const key  = SerpentCipher.keygen()
+const blob = Seal.encrypt(SerpentCipher, key, plaintext)
+try {
+  const pt = Seal.decrypt(SerpentCipher, key, blob)
+} catch {
+  // wrong key, tampered blob, or corrupted bytes
+}
 ```
 
-`hasSIMD()` returns `true` if the runtime supports WebAssembly SIMD.
-Serpent, ChaCha20, and Kyber modules all require SIMD; `init()` throws
-a clear error on runtimes without support. SIMD has been a baseline
-feature of all major browsers and runtimes since 2021. SHA-2 and SHA-3
-modules run on any WASM-capable runtime.
-
----
-
-## Full documentation
-
-The complete API reference ships in `docs/` alongside this file:
-
-| File | Contents |
-|------|----------|
-| `docs/serpent.md` | `SerpentCipher`, `Serpent`, `SerpentCtr`, `SerpentCbc` |
-| `docs/chacha20.md` | `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Cipher` |
-| `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/aead.md` | `Seal`, `SealStream`, `OpenStream`, `SealStreamPool`, `CipherSuite` |
-| `docs/kyber.md` | `MlKem512`, `MlKem768`, `MlKem1024`, `KyberSuite` — ML-KEM (FIPS 203) API reference |
-| `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; `CipherSuite`, `DerivedKeys`, `SealStreamOpts`, `PoolOpts`, `WasmSource` |
-| `docs/architecture.md` | Module structure, WASM layer, three-tier design |
+Streaming: `Seal` → `SealStream` + `OpenStream`. PQ hybrid: `SerpentCipher` → `MlKemSuite(new MlKem768(), SerpentCipher)`. Same call site, wire format, catch semantics.

package/LICENSE

@@ -2,6 +2,10 @@ MIT License
 
 Copyright (c) 2026 Leviathan Crypto Library
 
+https://leviathan.3xi.club
+https://github.com/xero/leviathan-crypto
+https://npmjs.com/package/leviathan-crypto
+
 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