Call init() before using any cryptographic class. It loads the WebAssembly modules that perform cryptographic work, caches them in memory, and makes them available to all wrapper classes.

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.

Cryptographic code executes in WebAssembly. See architecture.md §WebAssembly is the deployment vehicle and architecture.md §Where defense ends for the canonical WASM side-channel posture.

Each module gets its own linear memory. Every WASM module receives a few 64 KB pages of independent memory (3 pages for most modules, 4 for AES due to the GCM-SIV state). 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 = 'aes' | 'serpent' | 'chacha20' | 'sha2' | 'sha3' | 'keccak' | 'mlkem' | 'mldsa' | 'slhdsa' | 'blake3' | 'curve25519' | 'p256'

The WASM module families. Each one backs a group of related classes. 'keccak' is an alias for 'sha3', same WASM binary, same instance slot. 'ed25519' and 'x25519' are aliases for 'curve25519', same WASM binary, same instance slot.

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

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

Any PromiseLike<WasmSource> is accepted, Promise<ArrayBuffer>, Promise<Uint8Array>, Promise<string>, a fetch() response promise, and nested thenables up to depth 3 all resolve transparently. See loader.md for details.

type InitInput = Partial<Record<Module | 'ed25519' | 'x25519', WasmSource>>

The top-level init() parameter type. Each key is a module name (any Module value plus the 'ed25519' and 'x25519' aliases); each value is the WasmSource to load that module from. Keys are optional, only modules present in the object are loaded. The two aliases resolve to the underlying curve25519 slot and are de-duped if given identical sources.

async function init(sources: InitInput): 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 aesInit(source: WasmSource): Promise<void>
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 mlkemInit(source: WasmSource): Promise<void>
async function mldsaInit(source: WasmSource): Promise<void>
async function slhdsaInit(source: WasmSource): Promise<void>
async function blake3Init(source: WasmSource): Promise<void>
async function ed25519Init(source: WasmSource): Promise<void>  // alias for curve25519
async function x25519Init(source: WasmSource): Promise<void>   // alias for curve25519
async function ecdsaP256Init(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. Not exported from the leviathan-crypto root barrel, the wrapper classes consume it directly within the package. Documented here for completeness; consumers do not normally need to call it.

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. Not exported from the leviathan-crypto root barrel. See loader.md for details.

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)

The EcdsaP256 class and EcdsaP256Suite both need the p256 module; the suite additionally needs sha2 for the TS-side SHA-256 prehash. Pure-class callers who hand a pre-computed digest to EcdsaP256.sign(sk, pk, msgHash, rnd) only need p256.

import { init }     from 'leviathan-crypto'
import { p256Wasm } from 'leviathan-crypto/ecdsa/embedded'
import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'

await init({ p256: p256Wasm, sha2: sha2Wasm })

Or via the subpath init for tree-shakeable imports:

import { ecdsaP256Init } from 'leviathan-crypto/ecdsa'
import { p256Wasm }      from 'leviathan-crypto/ecdsa/embedded'

await ecdsaP256Init(p256Wasm)

The embedded subpath exports the same blob under two names (p256Wasm matches the WASM module name; ecdsaP256Wasm reads more naturally in the ecdsa subpath context).

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