A SIMD-only BLAKE3 binding covering all three modes from the BLAKE3 specification (§2.3 Modes): hash, keyed_hash, and derive_key. Each mode ships as a one-shot class and a streaming class with an XOF reader (§2.6 Extendable Output). A stateless HashFn const plugs BLAKE3-256 into the Fortuna substrate.

Table of Contents

• Overview
• Module Init
• Security Notes
• API Reference
• Usage Examples
• Error Conditions
• Dispatch coverage
• Cross-References

BLAKE3 is a tree-mode cryptographic hash function published in 2020 by Aumasson, Neves, Wilcox-O'Hearn, and Williamson. It descends from BLAKE2 through Bao's Merkle-tree mode and supersedes the BLAKE2 family for new designs. Three modes share one chunk / tree machine, differing only in the starting chaining value and the per-compress mode-flag bits.

leviathan ships BLAKE3 as an independent WASM module (blake3.wasm) sitting alongside sha2.wasm and sha3.wasm in the hash tier. The module is SIMD-only: a v128-internal compress1 for single-block work, and a v128-external lane-parallel compress4 for batches of four independent compressions. No scalar fallback ships; runtimes without WebAssembly SIMD fail loudly at init().

This binding covers:

• Default-mode hash (§2.3 hash). BLAKE3, BLAKE3Stream. Variable- length XOF output via the §2.6 root-compress squeeze.
• Keyed hash (§2.3 keyed_hash). BLAKE3KeyedHash, BLAKE3KeyedHashStream. The 32-byte key seeds the chunk machine in place of the IV.
• derive_key (§2.3 derive_key). BLAKE3DeriveKey, BLAKE3DeriveKeyStream. Two-pass KDF with a domain-separating context string.
• XOF reader. BLAKE3OutputReader for unbounded XOF reads.
• Fortuna HashFn. BLAKE3Hash const for use as a Fortuna accumulator hash.

BLAKE3 is not a NIST-approved primitive. The library ships it as a performance-tier hash for transcripts, content-addressed storage, and KDF-style work where the cryptanalytic posture of BLAKE2 / BLAKE3 is acceptable. Use SHA-2 or SHA-3 when an approved primitive is mandated.

import { init }       from 'leviathan-crypto'
import { blake3Wasm } from 'leviathan-crypto/blake3/embedded'

await init({ blake3: blake3Wasm })

BLAKE3 has no module dependencies. The binding does not touch sha2, sha3, or any other module. Pure-BLAKE3 work needs only the blake3 slot.

For tree-shakeable imports the leviathan-crypto/blake3 subpath exports a standalone init function:

import { blake3Init } from 'leviathan-crypto/blake3'
import { blake3Wasm } from 'leviathan-crypto/blake3/embedded'

await blake3Init(blake3Wasm)

blake3Init(source) initializes only the blake3 WASM binary. Calling any BLAKE3* class before blake3 is initialized throws a clear error naming the missing module.

BLAKE3 requires WebAssembly SIMD. Runtimes without SIMD support throw at init() time, identical to the serpent, chacha20, aes, mlkem, and mldsa modules. There is no scalar fallback.

One-shot default-mode hash, BLAKE3 §2.3 Modes (hash). No module exclusivity (each call acquires and releases internally).

Streaming default-mode hash, BLAKE3 §2.3 Modes (hash). Holds the blake3 module exclusivity token from construction until finalize() / finalizeXof() / dispose().

One-shot keyed_hash, BLAKE3 §2.3 Modes.

Streaming keyed_hash, BLAKE3 §2.3 Modes. The 32-byte key is bound at construction and copied into instance-owned storage; the caller's key buffer is left untouched. Holds module exclusivity until finalize / dispose.

One-shot derive_key, BLAKE3 §2.3 Modes.

Streaming derive_key, BLAKE3 §2.3 Modes. Context is bound at construction and encoded once; update() streams the material; finalize() runs the two-pass derive.

XOF reader, BLAKE3 §2.6 Extendable Output. Constructed by finalizeXof() on any streaming class. Holds module exclusivity until dispose(). Cannot be constructed directly by consumer code.

Stateless BLAKE3-256 HashFn const. Shape mirrors SHA256Hash and SHA3_256Hash: 32-byte fixed output, single WASM module dependency (['blake3']), one-shot digest(msg). Pluggable into the Fortuna HashFn slot.

Standalone tree-shakeable init for the blake3 module.

import { init, BLAKE3 } from 'leviathan-crypto'
import { blake3Wasm }   from 'leviathan-crypto/blake3/embedded'

await init({ blake3: blake3Wasm })

const h      = new BLAKE3()
const digest = h.hash(new TextEncoder().encode('hello world'))   // 32 bytes
h.dispose()

import { init, BLAKE3Stream } from 'leviathan-crypto'
import { blake3Wasm }         from 'leviathan-crypto/blake3/embedded'

await init({ blake3: blake3Wasm })

const s = new BLAKE3Stream()
s.update(chunkA).update(chunkB).update(chunkC)
const digest = s.finalize()   // 32 bytes by default; disposes the stream

import { init, BLAKE3KeyedHash, randomBytes } from 'leviathan-crypto'
import { blake3Wasm } from 'leviathan-crypto/blake3/embedded'

await init({ blake3: blake3Wasm })

const key = randomBytes(32)
const mac = new BLAKE3KeyedHash()
const tag = mac.hash(key, message)
mac.dispose()

import { init, BLAKE3DeriveKey } from 'leviathan-crypto'
import { blake3Wasm }            from 'leviathan-crypto/blake3/embedded'

await init({ blake3: blake3Wasm })

// Context string is a hardcoded application constant per BLAKE3 §2.3.
const CONTEXT = '2026-05 example.app session keys v1'

const kdf       = new BLAKE3DeriveKey()
const sessionKey = kdf.derive(CONTEXT, sharedSecret, 32)
kdf.dispose()

import { init, BLAKE3Stream } from 'leviathan-crypto'
import { blake3Wasm }         from 'leviathan-crypto/blake3/embedded'

await init({ blake3: blake3Wasm })

const s = new BLAKE3Stream()
s.update(transcript)
const reader = s.finalizeXof()
try {
    const head = reader.read(64)
    const tail = reader.read(4096)
    // ... continue reading as needed
} finally {
    reader.dispose()
}

import { init, Fortuna, BLAKE3Hash, SerpentGenerator } from 'leviathan-crypto'
import { blake3Wasm }  from 'leviathan-crypto/blake3/embedded'
import { serpentWasm } from 'leviathan-crypto/serpent/embedded'

await init({ blake3: blake3Wasm, serpent: serpentWasm })

const rng = await Fortuna.create({
    generator: new SerpentGenerator(),
    hash:      BLAKE3Hash,
})
const bytes = rng.get(64)

The BLAKE3 SIMD hot paths (compress4 driving chunk-level and parent-level batches) carry dispatch-coverage tests that confirm the kernel actually fires for inputs that should hit it, not just KAT-equivalence on small inputs.

test/unit/blake3/blake3-parent-dispatch.test.ts proves the multi-chunk hash hot path drives parent merges through the v128-external compress4 kernel (via parentBatch4 in src/asm/blake3/tree_simd.ts) for inputs producing >= 8 chunks.

The queue-per-level discipline in src/asm/blake3/tree.ts defers push-time merges: a chunk CV lands in level 0's queue, and when a level's queue reaches 8 entries parentBatch4 batches 4 parent merges in parallel. The 4 outputs propagate to the next level's queue, possibly cascading further batches at upper levels.

The WASM module carries a test-only parentBatch4 invocation counter held as a WASM global, not in linear memory, so wipeBuffers() does not clear it. Each exact-count assertion resets the counter, fires a hash, and verifies the counter equals the predicted cascade depth for that input size.

Predicted cascade per input size (chunks = ceil(inputLen / 1024)):

A KAT regression over every upstream corpus record with inputLen >= 8192 confirms the queue-per-level discipline produces byte-identical output to the prior ctz-stack implementation. The BLAKE3 §2.5 reorganisation changes WHEN merges happen, not WHAT they compute, so KAT regression is the bit-correctness gate.

test/unit/blake3/blake3-compress4-dispatch.test.ts proves the multi-chunk hash hot path in hashCore (src/asm/blake3/index.ts) actually dispatches 4-chunk batches through the v128-external compress4 kernel for inputs >= 4096 bytes, rather than silently falling through to the per-block single-chunk path.

The WASM module carries a test-only chunkBatch4 invocation counter held as a WASM global, not in linear memory, so wipeBuffers() does not clear it. Each assertion resets the counter, fires a hash, and verifies the counter reflects the expected number of 4-chunk batches.

A KAT regression over every upstream corpus record with inputLen >= 4096 confirms the dispatch produces bit-identical output to the previous single-chunk implementation. The 35-case KAT corpus is already gated by test/unit/blake3/blake3-kat.test.ts; the explicit subset here makes the dispatched-via-compress4 coverage legible.

test/unit/blake3/blake3-compress4-equiv.test.ts is the bit-equivalence gate between compress4 and four sequential compress calls. compress4 (v128-external SIMD, lane K = compress operation K) must be bit-identical to four sequential compress calls on the same inputs.

Equivalence is checked across deterministic randomised inputs from a fixed seed across 64 iterations, exercising independently distributed CV, message, counter, block_len, and flag values.

If compress has already passed its BLAKE3 §2.2 gate against the BLAKE3 KAT (test/unit/blake3/blake3-compress.test.ts), matching compress4 to it under random inputs establishes compress4's correctness without embedding additional cryptographic values in this file.