Table of Contents

• Overview
• Security Notes
• API Reference
• Usage Examples
• Error Conditions

leviathan-crypto runs all cryptographic computation inside WebAssembly modules. These modules are not loaded automatically. You tell init() which modules you need and provide a source for each one. After that, every class backed by those modules is ready to use.

init() is idempotent. Calling it multiple times with the same module is safe. It skips modules already loaded, so you can call init() in multiple places without redundant work. It returns a Promise. Always await it before constructing any class.

If you try to use a cryptographic class before calling init(), you get a clear error telling you exactly which module to load.

WASM runs outside the JavaScript JIT. Cryptographic code executes in WebAssembly, which provides more predictable execution timing than optimized JavaScript. This reduces the risk of timing side-channels introduced by the JIT compiler.

Each module gets its own linear memory. Every WASM module receives 3 pages (192 KB) of independent memory. Key material in one module cannot be read by another. There is no shared memory between modules.

No silent auto-initialization. Every wrapper class checks that its backing module has been initialized. If it has not, the class throws immediately rather than loading the module in the background. Initialization is explicit and auditable.

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

The WASM module families. Each one backs a group of related classes. 'keccak' is an alias for 'sha3' — same WASM binary, same instance slot.

type WasmSource = string | URL | ArrayBuffer | Uint8Array
               | WebAssembly.Module | Response | Promise<Response>

A value that resolves to a WASM binary. The loading strategy is inferred from the type:

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

Initializes one or more WASM modules. Pass an object mapping module names to their WasmSource. Only modules present in the object are loaded. Others are left untouched.

Each module subpath exports its own init function for tree-shakeable imports. These take a single WasmSource argument.

async function serpentInit(source: WasmSource): Promise<void>
async function chacha20Init(source: WasmSource): Promise<void>
async function sha2Init(source: WasmSource): Promise<void>
async function sha3Init(source: WasmSource): Promise<void>
async function keccakInit(source: WasmSource): Promise<void>
async function kyberInit(source: WasmSource): Promise<void>

Each function initializes only its own WASM module, keeping other modules out of your bundle.

The /embedded subpath for each module provides the gzip+base64 blob as a ready-to-use WasmSource:

keccakWasm and sha3Wasm are the same gzip+base64 blob. Both point to sha3.wasm.

function isInitialized(mod: Module): boolean

Returns true if the given module has been loaded and cached. Exported from both init.ts and the root barrel.

function getInstance(mod: Module): WebAssembly.Instance

Returns the cached WebAssembly instance for a module. Used internally by wrapper classes. You do not normally need to call this yourself.

Throws 'leviathan-crypto: call init({ <mod>: ... }) before using this class' if the module has not been initialized.

async function compileWasm(source: WasmSource): Promise<WebAssembly.Module>

Compiles a WasmSource to a WebAssembly.Module without instantiating it. Used by pool infrastructure to send compiled modules to workers. See loader.md for details.

function _resetForTesting(): void

Clears all cached WASM instances. Testing utility only. Do not use in production code.

The WASM binaries are bundled inside the package as gzip+base64 strings. Import the blob from the module's /embedded subpath and pass it to init().

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 })

Use the subpath init function when you need one module and want the smallest possible bundle:

import { serpentInit } from 'leviathan-crypto/serpent'
import { serpentWasm } from 'leviathan-crypto/serpent/embedded'

await serpentInit(serpentWasm)

'keccak' is an alias for 'sha3'. Both resolve to the same WASM binary and the same instance slot. Use it when you want the semantically correct primitive name for ML-KEM consumers:

import { init } from 'leviathan-crypto'
import { keccakWasm } from 'leviathan-crypto/keccak/embedded'

await init({ keccak: keccakWasm })
// isInitialized('sha3') === true — same slot
// isInitialized('keccak') === true — alias resolves symmetrically

Or via the subpath directly:

import { keccakInit, SHAKE128, SHA3_256 } from 'leviathan-crypto/keccak'
import { keccakWasm } from 'leviathan-crypto/keccak/embedded'

await keccakInit(keccakWasm)

Pass a URL to fetch and compile the .wasm file via streaming compilation. The server must respond with Content-Type: application/wasm.

await init({ serpent: new URL('https://unpkg.com/leviathan-crypto/dist/serpent.wasm') })

If you have already compiled the binary, for example from a KV cache, pass the WebAssembly.Module directly:

const mod = await WebAssembly.compile(bytes)
await init({ serpent: mod })

import { isInitialized } from 'leviathan-crypto'

if (!isInitialized('sha2')) {
  // handle accordingly
}

Cross-References

• index — Project Documentation index
• architecture — architecture overview, module relationships, buffer layouts, and build pipeline
• loader — WASM binary loading strategies (internal details)
• wasm — WebAssembly primer: modules, instances, memory, and the init gate