aead - xero/leviathan-crypto GitHub Wiki

Cipher-agnostic authenticated encryption for any scale. One-shot with Seal, chunked with SealStream and OpenStream, or parallel with SealStreamPool. All four share a wire format and accept any CipherSuite.

Table of Contents

• Overview
• Security Model
• Wire Format
• API Reference

Authenticated encryption in leviathan-crypto centers on four classes: Seal, SealStream, OpenStream, and SealStreamPool. All are cipher-agnostic. Pass a CipherSuite object at construction and they handle key derivation, nonce management, and authentication automatically.

These four form a natural progression by use case. Use Seal for data that fits in memory. Use SealStream and OpenStream for data arriving in chunks or too large to buffer. Use SealStreamPool for parallel chunked encryption across Web Workers. All four share the same wire format, so OpenStream can decrypt a Seal blob and vice versa.

leviathan-crypto includes two cipher suites. A third suite wraps either with ML-KEM for post-quantum hybrid encryption.

See ciphersuite.md for full cipher suite documentation.

The STREAM construction is based on Hoang, Reyhanitabar, Rogaway, and Vizár (CRYPTO 2015). It provides online authenticated encryption with four guarantees.

Per-chunk authentication. Each chunk carries its own authentication tag. The stream rejects a tampered chunk immediately and stops decrypting.

Counter binding. Each chunk's nonce includes a monotonic counter. Reordering or duplicating chunks produces a counter mismatch and authentication fails.

Final-chunk detection. The last chunk uses a distinct nonce flag (TAG_FINAL vs TAG_DATA). The opener expects a chunk marked final and rejects any stream that ends without one.

Stream isolation. Each stream generates a fresh 16-byte random nonce on construction. Two streams with the same key derive independent subkeys via HKDF and cannot interfere with each other.

All cryptographic computation runs in WASM outside the JavaScript JIT. Serpent's bitsliced S-box implementation and ChaCha20's quarter-round construction are both branchless and table-free, which eliminates data-dependent timing variation at the algorithm level. WASM lacks hardware-level constant-time guarantees, so this provides stronger posture than pure JavaScript but weaker than native constant-time code. If timing side channels are your primary threat model, a native cryptographic library with verified constant-time guarantees is more appropriate.

Every stream begins with a 20-byte header:

bytes:
    0: compound enum (bit 7 = framed flag, bit 6 = reserved, bits 0-5 = format ID)
 1-16: random nonce (16 bytes)
17-19: chunk size as u24 big-endian

Format IDs: 0x01 = XChaCha20-Poly1305, 0x02 = Serpent-256. KEM suites encode both the parameter set and inner cipher in a single byte. See ciphersuite.md for the full format enum table.

The 16-byte nonce is a HKDF salt, not a direct cipher nonce. XChaCha20Cipher passes it to HChaCha20 for subkey derivation. SerpentCipher uses it as the HKDF-SHA-256 salt to derive 96 bytes of enc/mac/iv key material.

The framed flag (bit 7) prefixes each chunk with a u32be length. Use framed mode for flat byte streams where chunks are concatenated without an external framing layer. Leave it off when the transport provides its own message boundaries such as WebSocket frames or IPC messages.

Each chunk is encrypted with a 12-byte nonce:

bytes:
 0-10: 11-byte big-endian counter (monotonically increasing)
   11: final flag (0x00 = TAG_DATA, 0x01 = TAG_FINAL)

The counter starts at 0 and increments with each chunk. The final chunk uses TAG_FINAL instead of TAG_DATA. A data chunk at counter N and a final chunk at counter N produce distinct nonces, so the construction never reuses a nonce.

HKDF-SHA-256 derives cipher-specific key material from the master key and the random nonce at stream construction:

XChaCha20 performs an additional HChaCha20 subkey derivation step using the first 16 bytes of the nonce. The intermediate streamKey is wiped immediately after use.

Serpent derives three keys: an encryption key for CBC, a MAC key for HMAC-SHA-256, and an IV key for per-chunk IV derivation via HMAC-SHA-256(iv_key, counterNonce)[0:16]. The CBC IV is derived deterministically on both sides and never transmitted.

Seal is a static class, never instantiated. It handles one-shot authenticated encryption and decryption. A Seal blob is structurally identical to a single-chunk SealStream output: preamble || finalChunk(counter=0, TAG_FINAL). OpenStream.finalize() can open a Seal blob directly, and Seal.decrypt() can open a single-chunk SealStream.

import { init, Seal, XChaCha20Cipher } from 'leviathan-crypto'
import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'

await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })

const key  = XChaCha20Cipher.keygen()
const blob = Seal.encrypt(XChaCha20Cipher, key, plaintext)
const pt   = Seal.decrypt(XChaCha20Cipher, key, blob)  // throws AuthenticationError on tamper

opts.aad. Optional Uint8Array carrying Additional Authenticated Data. Authenticated but not encrypted. Pass the same value to both encrypt and decrypt.

import { init, SealStream } from 'leviathan-crypto'
import { XChaCha20Cipher } from 'leviathan-crypto/chacha20'
import { chacha20Wasm }    from 'leviathan-crypto/chacha20/embedded'
import { sha2Wasm }        from 'leviathan-crypto/sha2/embedded'

await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })

const key      = XChaCha20Cipher.keygen()
const sealer   = new SealStream(XChaCha20Cipher, key, { chunkSize: 65536 })
const preamble = sealer.preamble  // send first

const ct0    = sealer.push(chunk0)
const ct1    = sealer.push(chunk1)
const ctLast = sealer.finalize(lastChunk)  // keys wiped

Constructor: new SealStream(cipher, key, opts?)

import { OpenStream }      from 'leviathan-crypto/stream'
import { XChaCha20Cipher } from 'leviathan-crypto/chacha20'
import { chacha20Wasm }    from 'leviathan-crypto/chacha20/embedded'
import { sha2Wasm }        from 'leviathan-crypto/sha2/embedded'

// init already called — preamble, key, and ciphertext chunks received from sender
const opener = new OpenStream(XChaCha20Cipher, key, preamble)

const pt0    = opener.pull(ct0)
const pt1    = opener.pull(ct1)
const ptLast = opener.finalize(ctLast)  // keys wiped

Constructor: new OpenStream(cipher, key, preamble)

Throws if the preamble format enum doesn't match the cipher or if the preamble is too short.

Parallel batch encryption and decryption using Web Workers. Each worker holds its own WASM instance and a copy of the derived keys.

import { init, SealStreamPool } from 'leviathan-crypto'
import { XChaCha20Cipher }      from 'leviathan-crypto/chacha20'
import { chacha20Wasm }         from 'leviathan-crypto/chacha20/embedded'
import { sha2Wasm }             from 'leviathan-crypto/sha2/embedded'

await init({ chacha20: chacha20Wasm, sha2: sha2Wasm })

const pool = await SealStreamPool.create(XChaCha20Cipher, key, {
  wasm: chacha20Wasm,
  workers: 4,
  chunkSize: 65536,
})

const ciphertext = await pool.seal(plaintext)
const decrypted  = await pool.open(ciphertext)
pool.destroy()

SealStreamPool.create(cipher, key, opts). Async factory.

Failure model. Any error is fatal. Authentication failure, worker crash, and timeout all terminate every worker, wipe all keys, and mark the pool permanently dead. Pending promises reject. There is no retry and no worker replacement. Create a new pool for the next operation. destroy() is synchronous from the caller's perspective. The pool flips to dead, pending jobs reject, and main-thread keys are zeroed before the call returns. Worker teardown is bounded-async. The pool requests that each worker zero its in-memory key material and terminates workers after a short ACK window.

Lifecycle.

• After seal() completes successfully, the pool holds the derived keys and master key in memory until you call destroy(). Call destroy() explicitly when you are finished; forgetting leaves key material resident until garbage collection.
• After seal(), the pool is marked sealed and further seal() calls throw. But open() is still valid and can decrypt other ciphertexts using the same master key. This is intentional because a pool is a stateful encrypt/decrypt context tied to a master key, not a single-use seal operation. The word "sealed" can still mislead. If your usage is encrypt-once-then-discard, the idiom is try { await pool.seal(pt) } finally { pool.destroy() }.
• On any job throw (worker crash, auth failure, timeout), the pool's _killAll runs. All workers terminate, all keys are wiped, and the pool is marked dead. Subsequent calls throw 'pool is dead'.

Interop with SealStream.push(). In unframed mode, pool.open() splits the body into chunks at fixed chunkSize boundaries. This works when the ciphertext came from SealStreamPool.seal() or from a SealStream that emitted every non-final chunk at exactly chunkSize plaintext bytes. A SealStream that called push() with sub-chunkSize chunks produces a valid blob that OpenStream can decrypt, but pool.open() cannot. The pool splits at the wrong boundary, stamps the wrong domain separator on the final chunk, and fails authentication. Use framed: true on both sides if producer and consumer may have different chunk shapes. Framed chunks carry a u32be length prefix that makes the split unambiguous.

KyberSuite wraps an ML-KEM instance and an inner CipherSuite into a hybrid post-quantum construction. The result plugs into Seal, SealStream, OpenStream, and SealStreamPool identically to a symmetric suite.

import { init, SealStream, OpenStream } from 'leviathan-crypto'
import { KyberSuite, MlKem768 }         from 'leviathan-crypto/kyber'
import { XChaCha20Cipher }              from 'leviathan-crypto/chacha20'
import { kyberWasm }    from 'leviathan-crypto/kyber/embedded'
import { sha3Wasm }     from 'leviathan-crypto/sha3/embedded'
import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'

await init({ kyber: kyberWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })

const suite = KyberSuite(new MlKem768(), XChaCha20Cipher)
const { encapsulationKey: ek, decapsulationKey: dk } = suite.keygen()

// sender — encrypts with the public key
const sealer   = new SealStream(suite, ek)
const preamble = sealer.preamble  // 1108 bytes for MlKem768
const ct0      = sealer.push(chunk0)
const ctLast   = sealer.finalize(lastChunk)

// recipient — decrypts with the private key
const opener = new OpenStream(suite, dk, preamble)
const pt0    = opener.pull(ct0)
const ptLast = opener.finalize(ctLast)

See kyber.md for key management, parameter set selection, and the full ML-KEM reference. See ciphersuite.md for format enum values and key derivation details.

push() and finalize() on SealStream and pull() and finalize() on OpenStream all accept an optional { aad } parameter for Additional Authenticated Data. AAD is authenticated but not encrypted. It binds each chunk to external context such as sequence numbers, metadata, or routing information without including that data in the ciphertext.

AAD applies per chunk, not per stream. Each chunk can carry different AAD. If you sealed a chunk with AAD you must provide the same value when opening it. A mismatch causes authentication to fail.

Seal.decrypt(), OpenStream.pull(), OpenStream.finalize(), and SealStreamPool.open() throw AuthenticationError when authentication fails. It extends Error and carries the cipher name in the message.

import { AuthenticationError } from 'leviathan-crypto'

try {
  const pt = Seal.decrypt(XChaCha20Cipher, key, tampered)
} catch (e) {
  if (e instanceof AuthenticationError) {
    // ciphertext was modified
  }
}

Never attempt to recover plaintext after an AuthenticationError. The stream layer wipes output buffers before throwing.