Home - xero/leviathan-crypto GitHub Wiki

  โ–ˆโ–ˆ     โ–โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ     โ–โ–ˆโ–Œ  โ–„โ–ˆโ–Œ   โ–ˆโ–ˆโ–ˆโ–Œ โ–€โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–€โ–„โ–ˆโ–ˆโ–Œ  โ–โ–ˆโ–Œ  โ–ˆโ–ˆโ–ˆโ–Œ    โ–ˆโ–ˆโ–Œ   โ–“โ–“
 โ–โ–ˆโ–Œ     โ–โ–ˆโ–Œ    โ–“โ–ˆ     โ–โ–ˆโ–Œ  โ–“โ–ˆโ–ˆ  โ–โ–ˆโ–Œโ–ˆโ–ˆ    โ–โ–ˆโ–Œ   โ–ˆโ–ˆโ–ˆ   โ–ˆโ–ˆโ–Œ โ–โ–ˆโ–Œโ–ˆโ–ˆ    โ–“โ–ˆโ–ˆ   โ–ˆโ–ˆ
 โ–ˆโ–ˆโ–Œ     โ–‘โ–ˆโ–ˆโ–ˆ   โ–โ–ˆโ–Œ    โ–ˆโ–ˆ   โ–€โ–€   โ–ˆโ–ˆ โ–โ–ˆโ–Œ   โ–ˆโ–ˆ   โ–โ–ˆโ–ˆโ–Œ   โ–ˆโ–“  โ–“โ–ˆ โ–โ–ˆโ–Œ  โ–โ–ˆโ–ˆโ–ˆโ–Œ  โ–ˆโ–“
 โ–ˆโ–ˆ      โ–ˆโ–ˆ     โ–โ–ˆโ–Œ    โ–ˆโ–“  โ–โ–ˆโ–ˆ  โ–โ–ˆโ–Œ  โ–ˆโ–“   โ–ˆโ–ˆ   โ–โ–ˆโ–ˆโ–„โ–„ โ–โ–ˆโ–Œ โ–โ–ˆโ–Œ  โ–ˆโ–ˆ  โ–โ–ˆโ–Œโ–ˆโ–ˆ โ–โ–ˆโ–Œ
โ–โ–ˆโ–Œ     โ–โ–ˆโ–Œ      โ–ˆโ–ˆ   โ–โ–ˆโ–Œ  โ–ˆโ–ˆ   โ–ˆโ–ˆ   โ–ˆโ–ˆ  โ–โ–ˆโ–Œ   โ–ˆโ–ˆโ–€โ–€โ–ˆโ–ˆโ–ˆโ–ˆโ–Œ โ–ˆโ–ˆ   โ–ˆโ–ˆ  โ–ˆโ–ˆ โ–โ–ˆโ–Œโ–โ–ˆโ–Œ
โ–โ–’โ–Œ     โ–โ–’โ–Œ      โ–โ–’โ–Œ  โ–ˆโ–ˆ   โ–’โ–ˆ   โ–ˆโ–ˆโ–€โ–€โ–€โ–ˆโ–ˆโ–Œ โ–โ–’โ–Œ   โ–’โ–ˆ    โ–ˆโ–“โ–‘ โ–’โ–ˆโ–€โ–€โ–€โ–ˆโ–ˆโ–Œ โ–’โ–ˆ  โ–ˆโ–ˆโ–โ–ˆ
โ–ˆโ–“ โ–„โ–„โ–“โ–ˆ โ–ˆโ–“ โ–„โ–„โ–“โ–ˆ   โ–“โ–“ โ–โ–“โ–Œ  โ–โ–“โ–Œ  โ–โ–ˆโ–Œ   โ–โ–’โ–Œ โ–ˆโ–“   โ–โ–“โ–Œ   โ–โ–“โ–ˆ โ–โ–“โ–Œ   โ–โ–’โ–Œโ–โ–“โ–Œ  โ–โ–ˆโ–ˆโ–ˆ
โ–“โ–ˆโ–ˆโ–€โ–€   โ–“โ–ˆโ–ˆโ–€โ–€      โ–“โ–ˆโ–“โ–ˆ   โ–โ–ˆโ–Œ  โ–โ–ˆโ–Œ   โ–โ–“โ–Œ โ–“โ–ˆ   โ–โ–ˆโ–Œ   โ–โ–ˆโ–“ โ–โ–ˆโ–Œ   โ–โ–“โ–Œโ–โ–ˆโ–Œ   โ–ˆโ–ˆโ–“
                    โ–“โ–ˆ                               โ–€โ–€        โ–โ–ˆโ–Œโ–Œโ–Œ

Leviathan Crypto Library

[!NOTE] A zero-dependency WebAssembly cryptography library. Two ciphers, opposite philosophies, same security properties.

bun add leviathan-crypto
# or
npm install leviathan-crypto

No bundler is required. See CDN usage.

AEAD

Seal, SealStream, OpenStream, and SealStreamPool are the primary API for authenticated encryption in leviathan-crypto. They are cipher-agnostic: you pass a CipherSuite object at construction and the implementation handles key derivation, nonce management, and authentication for you.

The classes form a natural progression:

  • Seal handles data that fits in memory (>~66k).
  • SealStream and OpenStream handle data that arrives in chunks or is too large to buffer.
  • SealStreamPool parallelizes the chunked approach across Web Workers.

All four produce and consume the same wire format, so a Seal blob can be opened by OpenStream and vice versa.

Session primitives

The ratchet module provides Double-Ratchet KDF primitives with post-quantum KEM steps, for consumers building forward-secret session protocols (secure messengers, streaming key-rotation systems) whose needs outgrow one-shot AEAD.

These are the primitives, not a full session. You compose them with your transport, header format, and epoch orchestration. See the ratchet guide for the construction.

Find the right tool

I want to...
Encrypt data Seal with SerpentCipher or XChaCha20Cipher
Encrypt a stream or large file SealStream to encrypt, OpenStream to decrypt
Encrypt in parallel SealStreamPool distributes chunks across Web Workers
Add post-quantum security KyberSuite wraps MlKem512, MlKem768, or MlKem1024 with any cipher suite
Build a forward-secret session ratchetInit, KDFChain, kemRatchetEncap / kemRatchetDecap, SkippedKeyStore
Hash data SHA256, SHA384, SHA512, SHA3_256, SHA3_512, SHAKE256 ...
Authenticate a message HMAC_SHA256, HMAC_SHA384, or HMAC_SHA512
Derive keys HKDF_SHA256 or HKDF_SHA512
Generate random bytes Fortuna for forward-secret generation, randomBytes for one-off use
Compare secrets safely constantTimeEqual uses a WASM SIMD path to prevent timing attacks
Work with bytes hexToBytes, bytesToHex, wipe, xor, concat ...

For raw primitives, low-level cipher access, and ASM internals see the full API reference.

[!TIP] New to crypto? We have a lot of technical jargon. Checkout the lexicon if you need a glossary of cryptographic terminology.

Demos

We maintain a number of demo applications for the library

cli [ npm ยท source ยท readme ]

lvthn 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.

bun add -g lvthn # or npm i -g lvthn
lvthn keygen --armor -o my.key
cat secret.txt | lvthn encrypt -k my.key --armor > secret.enc

COVCOM [ demo ยท source ยท readme ]

A full 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.

web [ demo ยท source ยท readme ]

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.

chat [ demo ยท source ยท readme ]

Simple end-to-end encrypted chat demo using 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.

kyber [ demo ยท source ยท readme ]

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.