Scheme-agnostic digital signatures for any scale. One-shot with Sign, chunked with SignStream and VerifyStream. All three share an envelope wire format and accept any SignatureSuite.

Table of Contents

• Overview
• Security Model
• Wire Format
• API Reference

Digital signatures in leviathan-crypto center on three classes: Sign, SignStream, and VerifyStream. All are scheme-agnostic. Pass a SignatureSuite object at the call site and they handle context binding, the M' construction, and authentication automatically.

These three form a natural progression by use case. Use Sign for messages that fit in memory. Use SignStream and VerifyStream for messages arriving in chunks or too large to buffer. Sign and SignStream share the same attached envelope, so a VerifyStream can verify a Sign.sign blob and vice versa.

leviathan-crypto ships 22 signature suites grouped into six families:

See signaturesuite.md for the full catalog, per-suite tables, hybrid composite wire formats, and the SignatureSuite interface.

Every signature binds the message bytes to a caller-supplied ctx. The envelope carries ctx on the wire and the verifier compares it against the receiver-supplied ctx in constant time before any cryptographic work runs. A mismatch fails fast with SigningError('sig-ctx-mismatch').

ML-DSA's NTT and rejection sampling, SLH-DSA's hash-tree authentication, Ed25519's scalar multiplication, and ECDSA-P256's scalar multiplication are written for constant-time execution at the algorithm level. See architecture.md §Where defense ends for the canonical WASM side-channel posture and threat-model boundaries.

Sign.sign and SignStream emit the same byte sequence. The layout is one suite byte, one ctx length byte, the user ctx bytes, a four-byte payload-length header, the payload, and finally the signature.

byte  0                                 : suite_byte    (u8, suite.formatEnum)
byte  1                                 : ctx_len       (u8, 0..255)
bytes 2 .. 2+ctx_len                    : ctx           (raw user_ctx, no domain prefix)
bytes 2+ctx_len .. 2+ctx_len+4          : payload_len   (u32 big-endian, 0..2^32 - 1)
bytes 2+ctx_len+4 .. payload_end        : payload       (exactly payload_len bytes)
bytes payload_end .. N                  : sig           (variable, <= suite.sigMaxSize bytes)

Total size is 2 + ctx_len + 4 + payload_len + sig.length. The explicit payload_len field lets the sig slot float, which is required for variable-length signature schemes (composite ECDSA, whose Ecdsa-Sig-Value DER encoding per RFC 3279 §2.2.3 varies with leading-zero stripping). For fixed-length suites the trailing sig fills exactly suite.sigMaxSize bytes; the suite's verify path enforces the exact length. The 4-byte overhead is rounding error on PQ signature sizes (under 0.2% on a ~2500-byte ML-DSA-44 sig) and irrelevant on multi-megabyte signed blobs.

1. Validate blob.length >= 6. The minimum legal blob carries the fixed 1+1+4-byte header even with empty ctx and empty payload. Fail with sig-blob-too-short.
2. Read suite_byte. Compare against suite.formatEnum. Fail with sig-suite-mismatch.
3. Read ctx_len.
4. Validate blob.length >= 2 + ctx_len + 4 so the payload_len u32 fits. Fail with sig-blob-too-short.
5. Read payload_len as a u32 big-endian at offset 2 + ctx_len.
6. Validate 2 + ctx_len + 4 + payload_len <= blob.length. Fail with sig-blob-too-short.
7. Validate that the trailing sig length fits the suite's catalog upper bound, blob.length - (2 + ctx_len + 4 + payload_len) <= suite.sigMaxSize. Fail with sig-blob-too-short.
8. Slice ctx, payload, and sig from the known offsets.
9. Compare caller ctx against wire ctx in constant time. Fail with sig-ctx-mismatch.
10. Call suite.verify(pk, payload, sig, wire_ctx). A false return becomes verify-failed. For fixed-length suites this is where the exact sig-length check happens; for variable-length suites the suite's verify path handles parsing the sig.
11. Return payload on success.

All wire-shape overflows fold into sig-blob-too-short so the discriminator count stays stable across the wire upgrade. The error message names the specific overflow (short header, ctx past blob end, payload past blob end, trailing sig over sigMaxSize); callers that want a sharper diagnostic read the thrown SigningError's .message. sig-suite-unknown is reserved for a future routing API that resolves the suite from the wire byte; callers always pass the suite explicitly today, so the discriminator never fires here.

Sign.signDetached returns raw signature bytes (length at most suite.sigMaxSize; for fixed-length suites the length is exactly the catalog value). No header, no metadata. The caller manages the (suite, pk, msg, sig, ctx) tuple out of band. Use detached signatures when the message is transported separately, or when the wire format must match an external standard (CMS, COSE, JWS) that frames the signature itself.

Sign is a static class, never instantiated. It handles one-shot signing and verification in both attached-envelope and detached forms, plus a peek helper for envelope inspection without verification. A Sign.sign blob is structurally identical to a single-update() SignStream output for the same suite, key, and inputs.

import { init, Sign, MlDsa65Suite } from 'leviathan-crypto'
import { mldsaWasm } from 'leviathan-crypto/mldsa/embedded'
import { sha3Wasm }  from 'leviathan-crypto/sha3/embedded'

await init({ mldsa: mldsaWasm, sha3: sha3Wasm })

const { pk, sk } = MlDsa65Suite.keygen()
const msg = new TextEncoder().encode('hello world')
const ctx = new TextEncoder().encode('myapp/v1')

const blob    = Sign.sign(MlDsa65Suite, sk, msg, ctx)
const payload = Sign.verify(MlDsa65Suite, pk, blob, ctx)  // recovers msg bytes

ctx. Required Uint8Array carrying authenticated context. Pass new Uint8Array(0) if you have no context. Authenticated but not encrypted; bound into the signature via the suite's effective_ctx construction. Pass the same value on sign and verify, or verify rejects with sig-ctx-mismatch.

const sig = Sign.signDetached(MlDsa65Suite, sk, msg, ctx)
const ok  = Sign.verifyDetached(MlDsa65Suite, pk, msg, sig, ctx)
// ok === true; for fixed-length suites sig is exactly MlDsa65Suite.sigMaxSize bytes

// blob is an attached envelope produced by Sign.sign or SignStream.
// peek validates structural shape only; it does NOT verify the signature
// and does NOT compare ctx.
const meta = Sign.peek(blob, MlDsa65Suite)
// meta.suiteByte      : number, the wire suite byte
// meta.ctx            : Uint8Array, the wire ctx
// meta.payloadOffset  : number, byte offset of the payload start
// meta.payloadLength  : number, payload length in bytes
// meta.sigOffset      : number, byte offset of the signature start

import { init, SignStream, MlDsa65PreHashSuite } from 'leviathan-crypto'
import { mldsaWasm } from 'leviathan-crypto/mldsa/embedded'
import { sha3Wasm }  from 'leviathan-crypto/sha3/embedded'

await init({ mldsa: mldsaWasm, sha3: sha3Wasm })

const { pk, sk } = MlDsa65PreHashSuite.keygen()
const ctx = new TextEncoder().encode('myapp/v1')

const signer = new SignStream(MlDsa65PreHashSuite, sk, ctx)
signer.update(chunk1)
signer.update(chunk2)
const sig = signer.finalize()
const payloadLen = chunk1.length + chunk2.length
const preamble   = signer.buildPreamble(payloadLen)
// wire output is preamble || chunk1 || chunk2 || sig
signer.dispose()

Constructor: new SignStream(suite, sk, ctx)

The canonical assembly pattern is finalize() first, then buildPreamble() with the payload length, then concatenate preamble || payload || sig. The ctx copy survives finalize() deliberately so buildPreamble() can read it; dispose() wipes the copy.

import { init, VerifyStream, MlDsa65PreHashSuite } from 'leviathan-crypto'
import { mldsaWasm } from 'leviathan-crypto/mldsa/embedded'
import { sha3Wasm }  from 'leviathan-crypto/sha3/embedded'

await init({ mldsa: mldsaWasm, sha3: sha3Wasm })

// pk and ctx must match the SignStream side
const verifier = new VerifyStream(MlDsa65PreHashSuite, pk, ctx)
verifier.update(preamble)
verifier.update(chunk1)
verifier.update(chunk2)
verifier.update(sig)
const payload = verifier.finalize()  // throws SigningError on bad sig
verifier.dispose()

Constructor: new VerifyStream(suite, pk, ctx)

Throws if the wire suite_byte does not match suite.formatEnum, or if the wire ctx does not match the caller-supplied ctx.

A receiver that does not yet know which suite produced the wire bytes can call Sign.peek against the leading bytes before constructing VerifyStream.

The signing layer holds two copies of secret-adjacent state for streams. The library wipes its copies on well-defined boundaries; caller-owned buffers (sk, pk, msg, sig, the user ctx) are never touched.

SignStream. new SignStream(suite, sk, ctx) copies ctx into a lib-owned Uint8Array. sk is held by reference and never wiped. The running prehash is disposed in both finalize() and dispose(). The ctx copy survives finalize() so buildPreamble() can still read it; call dispose() once the blob is assembled.

VerifyStream. update(chunk) copies every payload byte into an internally-owned chunk so a caller-side mutation cannot retroactively change the buffered payload. pk and the expected ctx are held by reference and never wiped. finalize() wipes payloadChunks, sigBuf, and headerBuf on every code path; the returned payload is a fresh concat(...) allocation, so wiping the internal chunks does not corrupt the result. dispose() performs the same wipe and is idempotent.

See signaturesuite.md for the suite-layer wipe discipline (effective_ctx, one-shot prehash digests, ECDSA-P256 hedging entropy).

Sign.sign, Sign.verify, Sign.signDetached, Sign.verifyDetached, Sign.peek, SignStream, and VerifyStream all throw SigningError(discriminator, message?) on contract violations and verification failures. The discriminator is the stable, machine-readable identifier; the message carries human-readable context.

import { SigningError } from 'leviathan-crypto'

try {
  const payload = Sign.verify(MlDsa65Suite, pk, tampered, ctx)
} catch (e) {
  if (e instanceof SigningError) {
    // e.discriminator: stable identifier (see table below)
    // e.message: human-readable context
  }
}

VerifyStream.finalize also throws verify-failed and sig-blob-too-short (the latter when finalize fires before enough bytes have arrived for a full signature).

Never attempt to recover the payload after a SigningError. VerifyStream.finalize wipes its internal buffers before throwing.