architecture - xero/leviathan-crypto GitHub Wiki

Overview of Leviathan Crypto's architecture design, comprising six independent WASM modules unified by a misuse-resistant TypeScript API, which delivers both Serpent's paranoia and ChaCha's elegance as a zero-dependency, tree-shakable, post-quantum library.

Table of Contents

• Vision
• Scope
• Repository Structure
• Architecture: TypeScript over WASM
• Six Independent WASM Modules
• init() API
• Public API Classes
• Build Pipeline
• Module Relationships
• npm Package
• Buffer Layouts
• Test Suite
• Correctness Contract
• Known Limitations

leviathan-crypto is a post-quantum WASM cryptography library with zero dependencies, tree-shakable, and side-effect free.

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 executes outside the JIT entirely, running compiled bytecode with linear memory you control. No speculative optimization, no value-dependent branches between source and execution.

WebAssembly is the correctness layer. All algorithm logic lives in WASM. Six AssemblyScript modules (serpent, chacha20, sha2, sha3, kyber, and 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.

TypeScript is the ergonomics layer. The strongly-typed public API covers Seal, SealStream, SealStreamPool, Fortuna, HKDF, 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.

Serpent-256: 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.

XChaCha20-Poly1305: 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.

Two ciphers, one interface. Both share the CipherSuite shape and slot into Seal, SealStream, and SealStreamPool interchangeably. Post-quantum extends the same model, KyberSuite wraps MlKem512, MlKem768, or MlKem1024 around either cipher, and the SPQR ratchet builds forward-secret sessions on top.

Primitives. WASM algorithms with their TypeScript wrapper classes.

Cipher Suites. Composition of WASM modules into complete cipher packages.

High-Level Constructs. Pure TypeScript abstractions over cipher suites.

Utilities. Pure TypeScript helpers, no init() dependency.

Source lives under src/, split between AssemblyScript primitives in src/asm/ and the TypeScript API in src/ts/. Tests are in test/. Build, codegen, and tooling scripts go in scripts/. CI/CD configuration sits in .github/. The repository root holds project documentation, package metadata, and tool configs. Each subsection below shows the relevant tree and notes the conventions that apply across files in that tier.

.github/ holds GitHub-specific repository configuration: workflow definitions, the CI image build context, and platform metadata. Workflows split along functional lines.

Merge gate. build.yml, lint.yml, e2e.yml, test-suite.yml. test-suite.yml orchestrates the per-domain unit runners (unit-*.yml) plus verify-vectors.yml for parallel execution and per-domain failure isolation.

Test vectors. verify-vectors.yml validates the corpus against SHA256SUMS.

Release flow. Manual release.yml bumps the version and creates the tag; the resulting v* tag push triggers publish.yml, which runs the npm publish with provenance attestations. npm-remove.yml is the manual deprecate/unpublish escape hatch.

Wiki. wiki.yml syncs docs/ to the GitHub Wiki on every merge to main.

CI image. ci-image.yml rebuilds the test-runner container from ci.Dockerfile whenever the Dockerfile changes.

.github/
├── ci.Dockerfile
└── workflows/
    ├── build.yml
    ├── ci-image.yml
    ├── e2e.yml
    ├── lint.yml
    ├── npm-remove.yml
    ├── publish.yml
    ├── release.yml
    ├── test-suite.yml
    ├── unit-chacha20.yml
    ├── unit-core.yml
    ├── unit-hashing.yml
    ├── unit-kyber.yml
    ├── unit-montecarlo-cbc.yml
    ├── unit-montecarlo-ecb.yml
    ├── unit-nessie.yml
    ├── unit-ratchet.yml
    ├── unit-serpent.yml
    ├── unit-stream.yml
    ├── verify-vectors.yml
    └── wiki.yml

scripts/ holds the build, codegen, and tooling scripts that produce dist/ and the test-vector corpus. Three categories.

Build orchestration. build-asm.js drives AssemblyScript compilation across the six modules. embed-wasm.ts produces the gzip+base64 blob for each .wasm. embed-workers.ts bundles each pool worker into a self-contained IIFE via esbuild. copy-docs.ts ships the consumer doc subset into dist/. See Build Pipeline for the full sequence.

Codegen. generate_simd.ts produces src/asm/serpent/serpent_simd.ts from a template by translating S-box gate logic into v128 ops; the generator and its output are both committed and the output is never edited by hand. gen-seal-vectors.ts, gen-sealstream-vectors.ts, gen-fortuna-vectors.ts, and gen-ratchet-vectors.ts produce known-answer-test vectors for their respective primitives.

Tooling. gen-changelog.ts generates CHANGELOG entries. lint-asm.js lints the AssemblyScript sources. pin-actions.ts pins every GitHub Action reference to a SHA, run via bun pin after workflow changes.

scripts/
├── build-asm.js
├── copy-docs.ts
├── embed-wasm.ts
├── embed-workers.ts
├── gen-changelog.ts
├── gen-fortuna-vectors.ts
├── gen-ratchet-vectors.ts
├── gen-seal-vectors.ts
├── gen-sealstream-vectors.ts
├── generate_simd.ts
├── lint-asm.js
└── pin-actions.ts

src/asm/ holds the AssemblyScript sources for each WASM binary. Every subdirectory compiles to its own .wasm with fully independent linear memory and no cross-module imports.

Per-module conventions. Every module exposes an index.ts as the asc entry point; it re-exports the public surface that becomes the WASM exports. Every module except ct/ has a buffers.ts that defines the static memory layout and the offset getters that all other files in that module import. The ct/ module is intentionally minimal: a single index.ts whose layout is implicit in its single 64 KB page.

src/asm/
├── chacha20/
│   ├── index.ts
│   ├── chacha20.ts          ← block function (RFC 8439)
│   ├── chacha20_simd_4x.ts  ← SIMD 4-wide inter-block keystream
│   ├── poly1305.ts          ← one-time MAC
│   ├── wipe.ts              ← module-wide buffer zeroizer
│   └── buffers.ts
├── ct/
│   └── index.ts  ← v128 XOR-accumulate constant-time compare
├── kyber/
│   ├── index.ts
│   ├── ntt.ts        ← scalar NTT/invNTT + zetas table
│   ├── ntt_simd.ts   ← v128 NTT butterflies, fqmul_8x, barrett_reduce_8x
│   ├── reduce.ts     ← Montgomery/Barrett reduction, fqmul
│   ├── poly.ts       ← polynomial serialization, compression, basemul
│   ├── poly_simd.ts  ← SIMD poly add/sub/reduce/ntt wrappers
│   ├── polyvec.ts    ← k-wide polyvec operations
│   ├── cbd.ts        ← centered binomial distribution (η=2, η=3)
│   ├── sampling.ts   ← uniform rejection sampling
│   ├── verify.ts     ← constant-time compare and conditional move
│   ├── params.ts     ← Q, QINV, MONT, Barrett/compression constants
│   └── buffers.ts
├── serpent/
│   ├── index.ts
│   ├── serpent.ts           ← block function + key schedule
│   ├── serpent_unrolled.ts  ← unrolled S-boxes and round functions
│   ├── serpent_simd.ts      ← SIMD bitsliced block operations
│   ├── cbc.ts               ← CBC mode
│   ├── cbc_simd.ts          ← SIMD CBC decrypt
│   ├── ctr.ts               ← CTR mode
│   ├── ctr_simd.ts          ← SIMD CTR 4-wide inter-block
│   └── buffers.ts
├── sha2/
│   ├── index.ts
│   ├── sha256.ts
│   ├── sha512.ts   ← shared by SHA-512 and SHA-384
│   ├── hmac.ts     ← HMAC-SHA256
│   ├── hmac512.ts  ← HMAC-SHA512 and HMAC-SHA384
│   └── buffers.ts
└── sha3/
    ├── index.ts
    ├── keccak.ts   ← Keccak-f[1600] permutation, sponge absorb/squeeze
    └── buffers.ts

src/ts/ is the public API layer. Each subdirectory is a published npm subpath; top-level files cover cross-cutting concerns and standalone utilities.

Subpath conventions. Every cipher and hash module has an index.ts barrel, a types.ts for TypeScript-only declarations, and an embedded.ts that re-exports its gzip+base64 WASM blob from src/ts/embedded/. The keccak/ alias subpath omits types.ts and re-exports sha3's instead. The ratchet/ and stream/ modules have no embedded.ts because they compose other modules and ship no WASM of their own.

Cipher modules (serpent/, chacha20/) add a cipher-suite.ts (the CipherSuite implementation for STREAM), a pool-worker.ts (Web Worker source for SealStreamPool), a generator.ts (Fortuna Generator), and a shared-ops.ts (serpent) or ops.ts (chacha20) holding pure primitive functions shared between the cipher-suite and the pool worker.

Hash modules (sha2/, sha3/) add a hash.ts (the stateless Fortuna HashFn).

Build artifacts. ct-wasm.ts and the embedded/ directory hold auto-generated outputs that only exist after bun run build. Both are gitignored. ct-wasm.ts is the inline raw byte array of the ct WASM module. embedded/ holds gzip+base64 blobs of each WASM binary (from scripts/embed-wasm.ts) and IIFE source strings for each pool worker (from scripts/embed-workers.ts).

src/ts/
├── chacha20/
│   ├── cipher-suite.ts
│   ├── embedded.ts
│   ├── generator.ts
│   ├── index.ts
│   ├── ops.ts
│   ├── pool-worker.ts
│   └── types.ts
├── ct-wasm.ts      ← gitignored build artifact: raw ct WASM bytes
├── embedded/       ← gitignored build artifacts
│   ├── chacha20-pool-worker.ts  ← ChaCha20 pool-worker IIFE source string
│   ├── chacha20.ts              ← chacha20.wasm gzip+base64 blob
│   ├── kyber.ts                 ← kyber.wasm gzip+base64 blob
│   ├── serpent-pool-worker.ts   ← Serpent pool-worker IIFE source string
│   ├── serpent.ts               ← serpent.wasm gzip+base64 blob
│   ├── sha2.ts                  ← sha2.wasm gzip+base64 blob
│   └── sha3.ts                  ← sha3.wasm gzip+base64 blob
├── errors.ts       ← AuthenticationError
├── fortuna.ts      ← Fortuna CSPRNG (composes pluggable Generator + HashFn)
├── index.ts        ← root barrel + dispatching init()
├── init.ts         ← initModule(), module cache, isInitialized
├── keccak/         ← alias subpath; same WASM and instance slot as sha3
│   ├── embedded.ts
│   └── index.ts
├── kyber/
│   ├── embedded.ts
│   ├── indcpa.ts    ← IND-CPA encrypt/decrypt + matrix generation
│   ├── index.ts
│   ├── kem.ts       ← Fujisaki-Okamoto transform (keygen, encaps, decaps)
│   ├── params.ts    ← MLKEM512, MLKEM768, MLKEM1024 parameter sets
│   ├── suite.ts     ← KyberSuite (hybrid KEM+AEAD CipherSuite factory)
│   ├── types.ts
│   └── validate.ts  ← key validation (FIPS 203 §7.2, §7.3)
├── loader.ts       ← loadWasm()/compileWasm() WasmSource dispatch
├── ratchet/
│   ├── index.ts
│   ├── kdf-chain.ts          ← KDFChain (per-message KDF chain, DR §5.2)
│   ├── ratchet-keypair.ts    ← RatchetKeypair (single-use ek/dk wrapper)
│   ├── root-kdf.ts           ← ratchetInit, kemRatchetEncap, kemRatchetDecap (DR §7.2)
│   ├── skipped-key-store.ts  ← SkippedKeyStore (MKSKIPPED cache, DR §3.2/§3.5)
│   └── types.ts
├── serpent/
│   ├── cipher-suite.ts
│   ├── embedded.ts
│   ├── generator.ts
│   ├── index.ts
│   ├── pool-worker.ts
│   ├── serpent-cbc.ts   ← SerpentCbc (broken out to avoid circular import)
│   ├── shared-ops.ts
│   └── types.ts
├── sha2/
│   ├── embedded.ts
│   ├── hash.ts
│   ├── hkdf.ts      ← HKDF_SHA256, HKDF_SHA512 (pure TS over HMAC)
│   ├── index.ts
│   └── types.ts
├── sha3/
│   ├── embedded.ts
│   ├── hash.ts
│   ├── index.ts
│   └── types.ts
├── stream/
│   ├── constants.ts         ← HEADER_SIZE, CHUNK_MIN/MAX, TAG_DATA/FINAL, FLAG_FRAMED
│   ├── header.ts            ← wire format header encode/decode, counter nonce
│   ├── index.ts
│   ├── open-stream.ts       ← OpenStream (cipher-agnostic streaming decryption)
│   ├── seal-stream-pool.ts  ← SealStreamPool (worker-based parallel batch)
│   ├── seal-stream.ts       ← SealStream (cipher-agnostic streaming encryption)
│   ├── seal.ts              ← Seal (static one-shot AEAD)
│   └── types.ts
├── types.ts        ← shared interfaces: Hash, KeyedHash, Blockcipher, Streamcipher, AEAD, Generator, HashFn
├── utils.ts        ← encoding, wipe, randomBytes, constantTimeEqual, CT_MAX_BYTES, hasSIMD
└── wasm-source.ts  ← WasmSource union type

test/ holds three independent categories of files, used by separate workflows.

Unit tests (unit/) are Vitest suites that compile to a JS target for fast local iteration. The directory mirrors src/ts/ structure with one folder per module, plus a handful of top-level .test.ts files for cross-cutting concerns (init, errors, utils, fortuna). CI splits these by domain via unit-*.yml for parallel execution.

End-to-end tests (e2e/) are Playwright suites that exercise the actual WASM artifacts across V8, SpiderMonkey, and JavaScriptCore. They run after the full build, including pool-worker bundling.

Test vectors (vectors/) is the immutable known-answer-test corpus. Files are read-only reference data. Some come from authoritative specifications (FIPS, RFCs, ACVP, NIST CAVP); others are self generated as regression vectors by scripts/gen-*-vectors.ts. CI validates KAT file integrity against SHA256SUMS.

See test-suite.md for full testing methodology, vector corpus inventory with provenance, and gate discipline.

test/
├── e2e/      ← Playwright suites against built WASM in V8, SpiderMonkey, JSC
├── unit/
│   ├── chacha20/
│   ├── ct/
│   ├── errors.test.ts
│   ├── fortuna/
│   ├── fortuna.test.ts
│   ├── helpers.ts
│   ├── init/
│   ├── init.test.ts
│   ├── kyber/
│   ├── loader/
│   ├── ratchet/
│   ├── serpent/
│   ├── sha2/
│   ├── sha3/
│   ├── stream/
│   └── utils.test.ts
└── vectors/  ← KAT corpus; integrity verified against SHA256SUMS

The repository root holds project documentation, package metadata, and tool configuration. Build artifacts that only exist after bun run build are listed at the end.

Documentation. README.md is the entry point. SECURITY.md covers the vulnerability disclosure policy. AGENTS.md is the agent contract that governs how AI agents work in the repo. CHANGELOG tracks release history and LICENSE is MIT. The docs/ directory holds the full API reference, audits, benchmarks, and architecture notes (this file lives there).

Package metadata. package.json declares the npm manifest, subpath exports, and scripts. package-lock.json and bun.lock are the lockfiles for npm and bun respectively; both ship checked in so either tool can install reproducibly.

Tool configs. asconfig.json configures AssemblyScript compilation. eslint.config.ts is the active linter, run via bun fix. playwright.config.ts and vitest.config.ts configure the e2e and unit test runners. tsconfig.json is the base TypeScript config; tsconfig.test.json and tsconfig.e2e.json extend it for the test targets. tslint.json is a TSLint config (older format).

Build artifacts (gitignored; only exist after bun run build). build/ holds the raw .wasm outputs from AssemblyScript compilation. dist/ is the published npm package contents (compiled JS, declarations, copied WASM, embedded blobs, doc subset).

.
├── build/                ← gitignored: .wasm outputs from AS compilation
├── dist/                 ← gitignored: published npm package contents
├── docs/                 ← API reference, audits, benchmarks (this file lives here)
├── README.md
├── SECURITY.md
├── AGENTS.md
├── CHANGELOG
├── LICENSE
├── package.json
├── package-lock.json
├── bun.lock
├── asconfig.json
├── eslint.config.ts
├── playwright.config.ts
├── tsconfig.json
├── tsconfig.e2e.json
├── tsconfig.test.json
├── tslint.json
└── vitest.config.ts

The TypeScript layer never implements cryptographic algorithms. It manages the boundary between JavaScript and WebAssembly by writing inputs into WASM linear memory, calling exported functions, and reading back outputs. All algorithm logic resides within AssemblyScript.

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.

Each primitive family compiles to its own .wasm binary with fully independent linear memory and buffer layouts. No shared state, no cross-module interference. Five of the six modules load through init(). The sixth, ct, sits outside the public Module union and the init() gate; it occupies a single 64 KB memory page and lazy-loads on the first call to constantTimeEqual. The ct module backs the public constantTimeEqual and CT_MAX_BYTES exports from the root barrel; neither requires an init() call.

Size. Consumers who only use Serpent don't load the SHA-3 binary.

Isolation. Key material in serpent.wasm memory cannot bleed into sha3.wasm memory even in theory.

Each module's buffer layout starts at offset 0 and is defined in its own buffers.ts. Buffer layouts are fully independent across modules.

serpent.wasm implements Serpent-256, a 128-bit block cipher. It handles key scheduling, block encryption and decryption, and both CTR and CBC streaming modes with SIMD variants for inter-block parallelism. See: Serpent-256 WASM Module Reference

The TypeScript module wraps this with SerpentCipher, a CipherSuite that combines Serpent-CBC with HMAC-SHA256 and HKDF key derivation for the STREAM construction. Primitive operations (HMAC, CBC, PKCS7 padding) live in serpent/shared-ops.ts and are reused by both the main thread and pool workers, guaranteeing byte-identical output and consistent Vaudenay 2002 padding normalization. Requires serpent and sha2 to be initialized.

chacha20.wasm implements the full ChaCha20-Poly1305 AEAD family per RFC 8439 and draft-irtf-cfrg-xchacha. It includes ChaCha20 stream cipher, Poly1305 one-time MAC, the AEAD construction, HChaCha20 for nonce extension, and SIMD 4-wide inter-block parallelism. See: ChaCha20/Poly1305 WASM Reference

The TypeScript module exports XChaCha20Cipher, a CipherSuite implementation for STREAM using XChaCha20-Poly1305 with HKDF key derivation. Pool workers load internally via SealStreamPool at runtime and don't appear in the package exports map.

sha2.wasm implements SHA-256 and SHA-512 per FIPS 180-4, plus SHA-384 (which reuses SHA-512's buffer and compress function with different IVs and truncation). It also provides HMAC per RFC 2104 for all three variants. HKDF-SHA256 and HKDF-SHA512 (RFC 5869) are pure TypeScript compositions over HMAC with no new WASM logic. See: SHA-2 WASM Reference

sha3.wasm implements the Keccak-f[1600] permutation per FIPS 202. All SHA3 variants (SHA3-224, SHA3-256, SHA3-384, SHA3-512) and XOF variants (SHAKE128, SHAKE256) share a single permutation, differing only in rate, domain separation byte, and output length. SHAKE supports unbounded multi-squeeze output. See: SHA-3 WASM Reference

kyber.wasm implements ML-KEM polynomial arithmetic per FIPS 203. It includes Montgomery and Barrett reduction, 7-layer NTT and inverse NTT with SIMD butterflies, basemul in Z_q[X]/(X²-ζ), centered binomial distribution sampling (η=2 and η=3), compression and decompression across all five bit-width paths, rejection sampling for matrix generation, and constant-time byte comparison and conditional move. Requires WebAssembly SIMD (v128 instructions). Uses 3 memory pages (192 KB) with 10 polynomial slots, 8 polynomial vector slots, and dedicated buffers for keys and ciphertexts. See: Kyber WASM Reference

The TypeScript module exports MlKem512, MlKem768, and MlKem1024—KEM classes implementing the Fujisaki-Okamoto transform. All three require both kyber and sha3 to be initialized; the sha3 module provides the Keccak sponge for matrix generation (SHAKE128), noise sampling (SHAKE256), and finalization (SHA3-256 for H, SHA3-512 for G).

ct.wasm implements constant-time byte array equality with a single SIMD-only primitive. The module exports compare(aOff, bOff, len), which reads both arrays directly from caller-specified offsets in linear memory and returns 1 if all bytes match, 0 otherwise. Comparison is zero-copy: no internal staging buffers, no buffer slots, no wipeBuffers export. The implementation is structurally branch-free. A v128.xor/v128.or accumulator processes 16-byte blocks, a scalar tail handles any remainder, and the final zero-test is an arithmetic shift, not a conditional. Requires WebAssembly SIMD (v128 instructions); if the runtime lacks SIMD or compilation fails, the first call throws a branded error. See: Constant-Time WASM Reference

The TypeScript module exports constantTimeEqual and CT_MAX_BYTES from the root barrel. The wrapper instantiates the WASM synchronously on first call and caches it for subsequent calls. It writes both arrays into linear memory, calls compare, and zeroes both regions in a finally block before returning. CT_MAX_BYTES is 32 KB per side; the 64 KB page holds two equal-length inputs.

WASM instantiation is async. init() is the initialization gate, call it once before using any cryptographic class. The cost is explicit and the developer controls when it is paid.

type Module = 'serpent' | 'chacha20' | 'sha2' | 'sha3' | 'keccak' | 'kyber'

type WasmSource =
  | string                  // gzip+base64 embedded blob
  | URL                     // fetch + compileStreaming
  | ArrayBuffer             // compile from raw bytes
  | Uint8Array              // compile from raw bytes
  | WebAssembly.Module      // pre-compiled (edge runtimes)
  | Response                // instantiateStreaming
  | Promise<Response>       // deferred fetch

async function init(
  sources: Partial<Record<Module, WasmSource>>,
): Promise<void>

The loading strategy is inferred from the source type, so there is no need for a mode string. Each module also exports its own init function, such as serpentInit(source), chacha20Init(source), sha2Init(source), sha3Init(source), keccakInit(source), and kyberInit(source), enabling tree-shakeable imports.

Each module provides a /embedded subpath that exports the gzip+base64 blob as a ready-to-use WasmSource:

import { init } from 'leviathan-crypto'
import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'

await init({ serpent: serpentWasm, sha2: sha2Wasm })

Idempotent initialization. Calling init() on an already initialized module is a no-op. It is safe to call init() from multiple locations within the codebase.

Module-scope cache. Each WebAssembly.Instance is cached at module scope after initial instantiation. All subsequent class constructions use the cached instance with no recompilation.

Error before initialization. Invoking any cryptographic class before calling init() throws a clear error prompting the developer to call init({ <module>: ... }) first.

No implicit initialization. Classes never call init() automatically on first use. Explicit initialization is preferable to hidden costs.

Thread safety. The main thread uses a single WASM instance per module. SealStreamPool provides worker-based parallelism. Each pool worker is spawned from an IIFE bundled at build time and instantiates its own WASM modules with isolated linear memory, bypassing the main-thread cache entirely. For other primitives, create one instance per Worker if Workers are used.

• HMAC names use underscore separator (HMAC_SHA256) matching RFC convention.
• SHA-3 names use underscore separator (SHA3_256) for readability.
• Ratchet exports are KDF primitives from Signal's Sparse Post-Quantum Ratchet spec; session state, message ordering, and header format remain application concerns.
• Fortuna requires await Fortuna.create({ generator, hash }) rather than new Fortuna(). Required modules depend on the generator and hash you pass. See fortuna.md for valid combinations.
• SealStream, OpenStream, and SealStreamPool are cipher-agnostic; you select the cipher by passing XChaCha20Cipher or SerpentCipher at construction.

All WASM-backed classes follow the same pattern:

import { init, Seal, SerpentCipher, SHA3_256 } from 'leviathan-crypto'
import { serpentWasm } from 'leviathan-crypto/serpent/embedded'
import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded'
import { sha3Wasm }    from 'leviathan-crypto/sha3/embedded'

await init({ serpent: serpentWasm, sha2: sha2Wasm, sha3: sha3Wasm })

const key  = SerpentCipher.keygen()
const blob = Seal.encrypt(SerpentCipher, key, plaintext)

const hasher = new SHA3_256()
const digest = hasher.hash(message)

Pure TypeScript utilities ship alongside the WASM-backed primitives:

1. npm run build:asm: AssemblyScript compiler reads src/asm/*/index.ts, emits build/*.wasm
2. npm run build:embed: scripts/embed-wasm.ts reads each .wasm, gzip compresses, base64 encodes, writes to src/ts/embedded/*.ts and per-module src/ts/*/embedded.ts
3. npm run build:embed-workers: scripts/embed-workers.ts bundles each pool worker into a self-contained IIFE via esbuild and writes the source to src/ts/embedded/<cipher>-pool-worker.ts as a string export
4. npm run build:ts: TypeScript compiler emits dist/
5. cp build/*.wasm dist/: WASM binaries copied for URL-based consumers
6. At runtime (subpath): serpentInit(serpentWasm) → initModule() → loadWasm(source) → decode gzip+base64 → WebAssembly.instantiate → cache in init.ts
7. At runtime (root): init({ serpent: serpentWasm, sha2: sha2Wasm }) → dispatches to each module's init function via Promise.all → same path as step 6 per module

src/ts/embedded/ is gitignored; these files are build artifacts. The WASM blobs (<module>.ts) derive from the AssemblyScript source in src/asm/. The pool-worker bundles (<cipher>-pool-worker.ts) derive from the worker source in src/ts/<cipher>/pool-worker.ts, bundled as a self-contained IIFE by scripts/embed-workers.ts.

Each WASM module is fully independent. No cross-module imports exist.

Serpent (src/asm/serpent/)

buffers.ts
  <- serpent.ts            (offsets for key, block, subkey, work, CBC IV)
  <- serpent_unrolled.ts   (block offsets, subkey, work)
  <- serpent_simd.ts       (SIMD bitsliced block operations)
  <- cbc.ts                (IV, block, chunk offsets)
  <- cbc_simd.ts           (SIMD CBC decrypt)
  <- ctr.ts                (nonce, counter, block, chunk offsets)
  <- ctr_simd.ts           (SIMD CTR 4-wide inter-block)

serpent.ts
  <- serpent_unrolled.ts   (S-boxes sb0-sb7, si0-si7, lk, kl, keyXor)

serpent_unrolled.ts
  <- cbc.ts                (encryptBlock_unrolled, decryptBlock_unrolled)
  <- ctr.ts                (encryptBlock_unrolled)

serpent_simd.ts
  <- cbc_simd.ts           (SIMD block operations)
  <- ctr_simd.ts           (SIMD block operations)

index.ts
  re-exports: buffers + serpent + serpent_unrolled + serpent_simd + cbc + cbc_simd + ctr + ctr_simd

ChaCha (src/asm/chacha20/)

buffers.ts
  <- chacha20.ts           (key, nonce, counter, block, state, poly key, xchacha offsets)
  <- chacha20_simd_4x.ts   (SIMD work buffer, chunk offsets)
  <- poly1305.ts           (poly key, msg, buf, tag, h, r, rs, s offsets)
  <- wipe.ts               (all buffer offsets, zeroes everything)

index.ts
  re-exports: buffers + chacha20 + chacha20_simd_4x + poly1305 + wipe

SHA-2 (src/asm/sha2/)

buffers.ts
  <- sha256.ts             (H, block, W, out, input, partial, total offsets)
  <- sha512.ts             (H, block, W, out, input, partial, total offsets)
  <- hmac.ts               (SHA-256 input, out, ipad, opad, inner offsets)
  <- hmac512.ts            (SHA-512 input, out, ipad, opad, inner offsets)

sha256.ts
  <- hmac.ts               (sha256Init, sha256Update, sha256Final)

sha512.ts
  <- hmac512.ts            (sha512Init, sha384Init, sha512Update, sha512Final, sha384Final)

index.ts
  re-exports: buffers + sha256 + sha512 + hmac + hmac512
  defines: wipeBuffers() inline

SHA-3 (src/asm/sha3/)

buffers.ts
  <- keccak.ts             (state, rate, absorbed, dsbyte, input, out offsets)

index.ts
  re-exports: buffers + keccak

Kyber (src/asm/kyber/)

params.ts
  <- reduce.ts             (Q, QINV, BARRETT_V, BARRETT_SHIFT)
  <- poly.ts               (Q, POLY_BYTES, HALF_Q, compression constants)
  <- polyvec.ts            (Q, POLY_BYTES, compression constants)
  <- sampling.ts           (Q)

buffers.ts
  <- polyvec.ts            (POLY_ACC_OFFSET)

reduce.ts
  <- ntt.ts                (fqmul, barrett_reduce)
  <- ntt_simd.ts           (fqmul, barrett_reduce — scalar tail)
  <- poly.ts               (montgomery_reduce, barrett_reduce, fqmul)

ntt.ts
  <- ntt_simd.ts           (getZetasOffset — zetas table pointer)
  <- poly.ts               (ntt, invntt, basemul, getZeta)

ntt_simd.ts
  <- poly_simd.ts          (ntt_simd, invntt_simd, barrett_reduce_8x)

poly.ts
  <- polyvec.ts            (poly_tobytes, poly_frombytes, poly_basemul_montgomery)

poly_simd.ts
  <- polyvec.ts            (poly_add_simd, poly_reduce_simd, poly_ntt_simd, poly_invntt_simd)

cbd.ts
  <- poly.ts               (cbd2, cbd3)

index.ts
  re-exports: buffers + ntt (scalar aliases) + ntt_simd (as ntt/invntt) +
              reduce + poly (scalar serialization/compression/basemul) +
              poly_simd (as poly_add/sub/reduce/ntt/invntt) +
              polyvec + sampling + verify

Each module's init function (serpentInit, chacha20Init, sha2Init, sha3Init, kyberInit) calls initModule() from init.ts, passing a WasmSource. initModule() delegates to loadWasm(source) in loader.ts. The loader infers the loading strategy from the source type, with no mode string and no knowledge of module names or embedded file paths.

Pool workers (serpent/pool-worker.ts, chacha20/pool-worker.ts) instantiate their own WASM modules from pre-compiled WebAssembly.Module objects passed via postMessage. They do not use initModule() or the main-thread cache. Workers are spawned from blob URLs constructed in cipher-suite.ts over an IIFE source string built at lib build time (src/ts/embedded/<cipher>-pool-worker.ts). The pool-worker.ts file itself is the source the bundler reads, not the runtime spawn entry.

Each TS wrapper class maps to one WASM module and specific exported functions. Tier 2 composition classes are pure TypeScript; they call Tier 1 classes rather than WASM functions directly.

serpent/index.ts → asm/serpent/ (Tier 1: direct WASM callers)

chacha20/index.ts → asm/chacha20/ (Tier 1: direct WASM callers)

sha2/index.ts → asm/sha2/ (Tier 1: direct WASM callers)

sha3/index.ts → asm/sha3/ (Tier 1: direct WASM callers)

kyber/index.ts + kyber/kem.ts + kyber/indcpa.ts → asm/kyber/ (Tier 1)

All MlKem classes also call sha3 WASM via indcpa.ts: sha3_256Init, sha3_512Init, shake128Init, shake256Init, keccakAbsorb, sha3_256Final, sha3_512Final, shakeFinal, shakePad, shakeSqueezeBlock.

Tier 2: pure TS composition

The root barrel defines and exports the dispatching init() function. It is the only file that imports all four module-scoped init functions.

Each subpath export also exports its own module-specific init function for tree-shakeable loading: serpentInit(source), chacha20Init(source), sha2Init(source), sha3Init(source), keccakInit(source).

Subpath exports:

{
  "exports": {
    ".":                     "./dist/index.js",
    "./stream":              "./dist/stream/index.js",
    "./serpent":              "./dist/serpent/index.js",
    "./serpent/embedded":     "./dist/serpent/embedded.js",
    "./chacha20":             "./dist/chacha20/index.js",
    "./chacha20/embedded":    "./dist/chacha20/embedded.js",
    "./sha2":                 "./dist/sha2/index.js",
    "./sha2/embedded":        "./dist/sha2/embedded.js",
    "./sha3":                 "./dist/sha3/index.js",
    "./sha3/embedded":        "./dist/sha3/embedded.js",
    "./keccak":               "./dist/keccak/index.js",
    "./keccak/embedded":      "./dist/keccak/embedded.js",
    "./kyber":                "./dist/kyber/index.js",
    "./kyber/embedded":       "./dist/kyber/embedded.js",
   	"./ratchet":              "./dist/ratchet/index.js"
  }
}

The root . export re-exports everything. Subpath exports allow bundlers to tree-shake at the module level; a consumer importing only ./sha3 does not include the Serpent wrapper classes or their embedded WASM binaries in their bundle.

The /embedded subpaths provide gzip+base64 WASM blobs for zero-config usage. Consumers using URL-based or pre-compiled loading can skip the /embedded imports entirely, keeping them out of the bundle.

Tree-shaking: "sideEffects": false is set in package.json. Bundlers that support tree-shaking (webpack, Rollup, esbuild) can eliminate unused modules and their embedded WASM binaries from the final bundle.

Published. The npm package includes:

• dist/: compiled JS, TypeScript declarations, WASM binaries, pool worker source files (build inputs, not runtime spawn entries; see the NOTE above), and a subset of consumer-facing API docs for offline use.
• CLAUDE.md: agent-facing project context.
• SECURITY.md: vulnerability disclosure policy.

Not published. src/, test/, build/, scripts/, .github/, editor configs.

All offsets start at 0 per module. Independent linear memory. No offsets are shared or coordinated across modules.

Source: src/asm/serpent/buffers.ts

wipeBuffers() zeroes all 10 buffers (key, block pt/ct, nonce, counter, subkeys, work, chunk pt/ct, CBC IV).

Source: src/asm/chacha20/buffers.ts

wipeBuffers() zeroes all 15 buffer regions (key, chacha nonce/ctr/block/state, chunk pt/ct, poly key/msg/buf/tag/h/r/rs/s, xchacha nonce/subkey, SIMD work).

Source: src/asm/sha2/buffers.ts

wipeBuffers() zeroes all 20 buffer regions (SHA-256 state/block/W/out/input/partial/total, HMAC-256 ipad/opad/inner, SHA-512 state/block/W/out/input/partial/total, HMAC-512 ipad/opad/inner).

Source: src/asm/sha3/buffers.ts

wipeBuffers() zeroes all 6 buffer regions (state, rate, absorbed, dsbyte, input, output).

Source: src/asm/kyber/

Total mutable: 29344 bytes (4096–33440). End = 33440 < 192 KB.

wipeBuffers() zeroes all mutable regions (poly slots, polyvec slots, SEED, MSG, PK, SK, CT, CT_PRIME, XOF/PRF, accumulator). The zetas data segment is read-only and is not wiped.

For the full testing methodology and vector corpus, see: test-suite.md

Each primitive family has a gate test: the simplest authoritative vector for that primitive. The gate must pass before any other tests in that family are written or run. Gate tests are annotated with a // GATE comment.

• init() with each WasmSource type loads and caches the module correctly
• Idempotency: second init() call for same module is a no-op
• Error before init: clear error thrown for each class before its module is loaded
• Partial init: loading { serpent: ... } does not make sha3 classes available

leviathan-crypto must produce byte-identical output to the authoritative specification for every known test vector. Cross-checks against the leviathan TypeScript reference and external tools (OpenSSL, Python hashlib, Node.js crypto) provide additional verification layers.

The vector corpus in test/vectors/ act as a source of immutable known-answer-test truth. KAT files are reference data from authoritative specifications (FIPS, RFCs, ACVP, NIST CAVP, NESSIE) or are self generated as regression vectors by scripts/gen-*-vectors.ts. CI validates integrity against SHA256SUMS. See test-suite.md for the full corpus inventory, provenance, and gate discipline.

• SerpentCbc is unauthenticated: use Seal with SerpentCipher for authenticated Serpent encryption, or pair SerpentCbc with HMAC_SHA256 (Encrypt-then-MAC) if direct CBC access is required.
• Single-threaded WASM per instance: one WASM instance per binary per thread. SealStreamPool provides Worker-based parallelism for both cipher families; other primitives remain single-threaded.
• Max input per WASM call: CTR accepts at most 65536 bytes per call; CBC accepts at most 65552 bytes (65536 + 16 bytes PKCS7 maximum overhead). Wrappers handle splitting automatically for larger inputs.
• WASM side-channel posture: WebAssembly implementations offer the best available side-channel resistance (branchless, table-free), but lack hardware-level constant-time guarantees. For applications where timing side channels are a primary threat, a native cryptographic library with verified constant-time guarantees will be more appropriate than any WASM-based implementation.