Table of Contents

• Overview
• Security Model
• Wire Format
• API Reference

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 four classes form a natural progression. Seal handles data that fits in memory. 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.

Two cipher suites are included. A third 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 is individually authenticated. A tampered chunk is rejected immediately without decrypting anything that follows.

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). Truncating the stream by dropping the final chunk is detected because the opener expects a chunk marked final.

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

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.

AuthenticationError is thrown by Seal.decrypt(), OpenStream.pull(), OpenStream.finalize(), and SealStreamPool.open() 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.

Cross-References

• index — Project Documentation index
• architecture — architecture overview, module relationships, buffer layouts, and build pipeline
• ciphersuite — SerpentCipher, XChaCha20Cipher, KyberSuite, and the CipherSuite interface
• kyber — ML-KEM key encapsulation, parameter sets, and key management
• serpent — Serpent-256 raw primitives
• chacha20 — ChaCha20 raw primitives
• stream_audit — streaming AEAD composition audit
• exports — complete export reference
• init — WASM loading and WasmSource