leviathan-crypto 2.0.1 → 3.0.0

package/dist/slhdsa/index.js

@@ -0,0 +1,493 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/slhdsa/index.ts
+//
+// SLH-DSA public API, SlhDsa128f / SlhDsa192f / SlhDsa256f classes.
+// FIPS 205, Stateless Hash-Based Digital Signature Standard.
+//
+// Public surface: keygen / sign / verify, plus the HashSLH-DSA family
+// (signHash / verifyHash) and prehashed variants (signHashPrehashed /
+// verifyHashPrehashed). Use init({ slhdsa, ... }) before constructing
+// any class. Pure-mode usage needs only the slhdsa module; HashSLH-DSA
+// with SHA-2 pre-hash adds sha2, with SHA-3 / SHAKE pre-hash adds sha3.
+import { initModule, getInstance, isInitialized, _assertNotOwned } from '../init.js';
+import { randomBytes, wipe } from '../utils.js';
+import { SLHDSA128F, SLHDSA192F, SLHDSA256F } from './params.js';
+import { slhSignInternalTs, signWithPrehash } from './sign.js';
+import { slhVerifyInternalTs, verifyWithPrehash } from './verify.js';
+import { constructMPrimePure } from './prehash.js';
+import { validateContext, validateSigningKey, validateRnd, validateMessage, validateDigest, } from './validate.js';
+import { algoNeedsSha2, algoNeedsSha3, digestSize, preHashMessage, } from './prehash.js';
+export async function slhdsaInit(source) {
+    return initModule('slhdsa', source);
+}
+export { SLHDSA128F, SLHDSA192F, SLHDSA256F };
+export { isInitialized };
+/** Return the slhdsa WASM instance exports. Internal helper for tests that
+ *  need raw access to the ADRS / hash / sponge primitives; consumers use
+ *  the SlhDsa* classes below. */
+export function getSlhDsaExports() {
+    return getInstance('slhdsa').exports;
+}
+// ── Base class ──────────────────────────────────────────────────────────────
+export class SlhDsaBase {
+    params;
+    constructor(params) {
+        if (!isInitialized('slhdsa'))
+            throw new Error('leviathan-crypto: call init({ slhdsa: ... }) before using SlhDsa classes');
+        this.params = params;
+    }
+    get x() {
+        return getInstance('slhdsa').exports;
+    }
+    get sx() {
+        return getInstance('sha3').exports;
+    }
+    get sha2x() {
+        return getInstance('sha2').exports;
+    }
+    /**
+     * Deterministic key generation, FIPS 205 §9.1 Algorithm 18.
+     * @param seed 3n bytes laid out as `SK.seed ‖ SK.prf ‖ PK.seed`. Each
+     *             component is `n` bytes (16 for 128f, 24 for 192f, 32 for
+     *             256f). The slh_keygen_internal entry consumes this layout
+     *             directly.
+     */
+    keygenDerand(seed) {
+        _assertNotOwned('slhdsa');
+        const n = this.params.n;
+        if (!(seed instanceof Uint8Array))
+            throw new TypeError('leviathan-crypto: keygen seed must be a Uint8Array');
+        if (seed.length !== 3 * n)
+            throw new RangeError(`leviathan-crypto: keygen seed must be ${3 * n} bytes (SK.seed||SK.prf||PK.seed) for `
+                + `${this.params.paramSet} (got ${seed.length})`);
+        const x = this.x;
+        const mem = new Uint8Array(x.memory.buffer);
+        const inOff = x.getInputOffset();
+        const outOff = x.getOutOffset();
+        try {
+            this.params.wasmSelector();
+            mem.set(seed, inOff);
+            x.slhKeygenInternal();
+            const sk = mem.slice(outOff, outOff + this.params.skBytes);
+            const pk = mem.slice(outOff + this.params.skBytes, outOff + this.params.skBytes + this.params.pkBytes);
+            return { verificationKey: pk, signingKey: sk };
+        }
+        finally {
+            // INPUT held SK.seed ‖ SK.prf ‖ PK.seed; SK.seed and SK.prf are
+            // secret. Wipe the lib's staging copy unconditionally.
+            mem.fill(0, inOff, inOff + 3 * n);
+            x.wipeBuffers();
+        }
+    }
+    /** Random key generation, wraps `keygenDerand` with `randomBytes(3n)`. */
+    keygen() {
+        const seed = randomBytes(3 * this.params.n);
+        try {
+            return this.keygenDerand(seed);
+        }
+        finally {
+            wipe(seed);
+        }
+    }
+    /**
+     * Hedged signing, FIPS 205 §3.4 / §10.2.1 Algorithm 22.
+     * Generates a fresh n-byte addrnd (opt_rand) per signature; two
+     * signatures over the same (sk, M, ctx) produce different bytes.
+     * Hedged signing is recommended over deterministic because hedged
+     * signatures remain unforgeable under fault attacks that bias the
+     * rejection-sampling stream (FIPS 205 §3.4 / §9.2).
+     */
+    sign(sk, M, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        validateSigningKey(sk, this.params);
+        validateMessage(M);
+        validateContext(ctx);
+        const MPrime = constructMPrimePure(M, ctx);
+        const optRand = randomBytes(this.params.n);
+        try {
+            return slhSignInternalTs(this.x, this.params, sk, MPrime, optRand);
+        }
+        finally {
+            wipe(optRand);
+            wipe(MPrime);
+        }
+    }
+    /**
+     * Deterministic signing, FIPS 205 §3.4. Sets opt_rand ← PK.seed so two
+     * signatures over the same (sk, M, ctx) produce identical bytes.
+     * Caller accepts the §3.4 caveat: deterministic signatures are
+     * vulnerable to fault attacks that bias secret-derived intermediates;
+     * use only when no entropy is available or determinism is a hard
+     * protocol requirement. PK.seed lives at sk[2n..3n] inside the
+     * `SK.seed ‖ SK.prf ‖ PK.seed ‖ PK.root` encoding (FIPS 205 §9.1).
+     */
+    signDeterministic(sk, M, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        validateSigningKey(sk, this.params);
+        validateMessage(M);
+        validateContext(ctx);
+        const n = this.params.n;
+        // slice() keeps optRand self-contained for WASM INPUT staging.
+        const optRand = sk.slice(2 * n, 3 * n);
+        const MPrime = constructMPrimePure(M, ctx);
+        try {
+            return slhSignInternalTs(this.x, this.params, sk, MPrime, optRand);
+        }
+        finally {
+            wipe(MPrime);
+            // optRand is library scratch; wipe even though contents are sk-derivable.
+            wipe(optRand);
+        }
+    }
+    /**
+     * Externally-randomised signing, testing / CAVP API. Caller supplies
+     * the n-byte opt_rand; library does not mix in additional entropy.
+     * Hard contract on the caller: opt_rand MUST come from an approved
+     * RBG and MUST NOT be reused across signatures. ACVP SLH-DSA sigGen
+     * vectors (with a supplied additionalRandomness) drive this path.
+     */
+    signDerand(sk, M, optRand, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        validateSigningKey(sk, this.params);
+        validateMessage(M);
+        validateContext(ctx);
+        validateRnd(optRand, this.params);
+        const MPrime = constructMPrimePure(M, ctx);
+        try {
+            return slhSignInternalTs(this.x, this.params, sk, MPrime, optRand);
+        }
+        finally {
+            wipe(MPrime);
+        }
+    }
+    /**
+     * Pure SLH-DSA verify, FIPS 205 §10.3 Algorithm 24 / §9.3 Algorithm 20.
+     *
+     * Returns boolean. Wrong-length pk / sig return false (FIPS 205 §3.6.2
+     * structural mismatch; same posture as ML-DSA verify). Throws
+     * `SigningError('sig-ctx-too-long')` only on the caller-side contract
+     * violation `ctx.length > 255`.
+     */
+    verify(pk, M, sig, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        validateMessage(M);
+        // FIPS 205 §3.6.2 / §10.3 Algorithm 24 line 5, wrong-length pk or σ
+        // is not a caller bug; it is a structural mismatch that cannot
+        // verify. Return false rather than throw.
+        if (!(pk instanceof Uint8Array) || pk.length !== this.params.pkBytes)
+            return false;
+        if (!(sig instanceof Uint8Array) || sig.length !== this.params.sigBytes)
+            return false;
+        validateContext(ctx);
+        const MPrime = constructMPrimePure(M, ctx);
+        try {
+            return slhVerifyInternalTs(this.x, this.params, pk, MPrime, sig);
+        }
+        finally {
+            wipe(MPrime);
+        }
+    }
+    // ── HashSLH-DSA, FIPS 205 §10.2.2 / §10.3 (pre-hash variant) ─────────
+    //
+    // HashSLH-DSA wraps the same Sign_internal / Verify_internal primitives
+    // pure SLH-DSA uses, but pre-hashes M and builds M' with domain-sep
+    // byte 0x01 plus the hash function's OID DER bytes; signatures
+    // produced by sign / signHash on the same key are NOT interchangeable
+    // per FIPS 205 §10.2 narrative.
+    //
+    // `ph` is the LAST positional parameter on every HashSLH-DSA method
+    // (mirrors HashML-DSA's choice). There is no sensible default; callers
+    // must select one explicitly.
+    //
+    // `init({ sha2: ... })` is required only when `ph` is a SHA-2 family
+    // algorithm. `init({ sha3: ... })` is required when `ph` is a SHA-3
+    // or SHAKE algorithm. Pure-SLH-DSA usage needs neither (slhdsa-wasm
+    // has its own embedded Keccak permutation).
+    _assertHashPrereqs(ph) {
+        // Validate ph before any other dispatch so widened-type callers
+        // (e.g. parsing a vector file via `as PreHashAlgorithm`) hit the
+        // canonical "unsupported HashSLH-DSA pre-hash" RangeError rather
+        // than a downstream sha2-not-initialized error.
+        digestSize(ph);
+        // FIPS 205 §10.2.2: "SHA-256 and SHAKE128 are only appropriate
+        // for use with SLH-DSA parameter sets that are claimed to be in
+        // security category 1." Enforce this at the public surface: a
+        // category-3 or category-5 key may not be used with SHA-256 or
+        // SHAKE128 prehash.
+        if ((ph === 'SHA2-256' || ph === 'SHAKE128') && this.params.securityCategory !== 1)
+            throw new RangeError(`leviathan-crypto: HashSLH-DSA pre-hash '${ph}' is only appropriate for security category 1 `
+                + `(see FIPS 205 §10.2.2); ${this.params.paramSet} is security category ${this.params.securityCategory}`);
+        if (algoNeedsSha2(ph)) {
+            if (!isInitialized('sha2'))
+                throw new Error('leviathan-crypto: call init({ sha2: ... }) before HashSLH-DSA with SHA-2 pre-hash');
+            _assertNotOwned('sha2');
+        }
+        if (algoNeedsSha3(ph)) {
+            if (!isInitialized('sha3'))
+                throw new Error('leviathan-crypto: call init({ sha3: ... }) before HashSLH-DSA with SHA-3 / SHAKE pre-hash');
+            _assertNotOwned('sha3');
+        }
+    }
+    /**
+     * Hedged HashSLH-DSA sign, FIPS 205 §10.2.2 Algorithm 23.
+     *
+     * Pre-hashes `M` with the chosen approved function `ph`, builds
+     * M' = 0x01 ‖ |ctx| ‖ ctx ‖ OID(ph) ‖ PH_M, then drives
+     * slh_sign_internal with a fresh n-byte opt_rand (FIPS 205 §3.4
+     * recommended default; see {@link sign} for the rationale).
+     */
+    signHash(sk, M, ph, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        this._assertHashPrereqs(ph);
+        validateSigningKey(sk, this.params);
+        validateMessage(M);
+        validateContext(ctx);
+        const sha2x = algoNeedsSha2(ph) ? this.sha2x : undefined;
+        const sha3x = algoNeedsSha3(ph) ? this.sx : undefined;
+        const PH_M = preHashMessage(sha3x, sha2x, ph, M);
+        const optRand = randomBytes(this.params.n);
+        try {
+            return signWithPrehash(this.x, this.params, sk, PH_M, ph, ctx, optRand);
+        }
+        finally {
+            wipe(optRand);
+            wipe(PH_M);
+            if (sha2x)
+                sha2x.wipeBuffers();
+            if (sha3x)
+                sha3x.wipeBuffers();
+        }
+    }
+    /**
+     * Deterministic HashSLH-DSA sign, FIPS 205 §10.2.2 Algorithm 23 with
+     * opt_rand ← PK.seed (the deterministic substitute per FIPS 205 §3.4).
+     * Same fault-attack caveat as {@link signDeterministic}.
+     */
+    signHashDeterministic(sk, M, ph, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        this._assertHashPrereqs(ph);
+        validateSigningKey(sk, this.params);
+        validateMessage(M);
+        validateContext(ctx);
+        const n = this.params.n;
+        const optRand = sk.slice(2 * n, 3 * n);
+        const sha2x = algoNeedsSha2(ph) ? this.sha2x : undefined;
+        const sha3x = algoNeedsSha3(ph) ? this.sx : undefined;
+        const PH_M = preHashMessage(sha3x, sha2x, ph, M);
+        try {
+            return signWithPrehash(this.x, this.params, sk, PH_M, ph, ctx, optRand);
+        }
+        finally {
+            wipe(PH_M);
+            wipe(optRand);
+            if (sha2x)
+                sha2x.wipeBuffers();
+            if (sha3x)
+                sha3x.wipeBuffers();
+        }
+    }
+    /**
+     * Externally-randomised HashSLH-DSA sign, testing / CAVP API. Caller
+     * supplies the n-byte opt_rand (same contract as {@link signDerand}).
+     * Used to oracle ACVP HashSLH-DSA sigGen vectors with byte-identical
+     * output.
+     */
+    signHashDerand(sk, M, ph, optRand, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        this._assertHashPrereqs(ph);
+        validateSigningKey(sk, this.params);
+        validateMessage(M);
+        validateContext(ctx);
+        validateRnd(optRand, this.params);
+        const sha2x = algoNeedsSha2(ph) ? this.sha2x : undefined;
+        const sha3x = algoNeedsSha3(ph) ? this.sx : undefined;
+        const PH_M = preHashMessage(sha3x, sha2x, ph, M);
+        try {
+            return signWithPrehash(this.x, this.params, sk, PH_M, ph, ctx, optRand);
+        }
+        finally {
+            wipe(PH_M);
+            if (sha2x)
+                sha2x.wipeBuffers();
+            if (sha3x)
+                sha3x.wipeBuffers();
+        }
+    }
+    /**
+     * HashSLH-DSA verify, FIPS 205 §10.3 Algorithm 25.
+     *
+     * Same return / throw posture as {@link verify}: returns boolean for
+     * every signature outcome (including malformed-σ → false), throws
+     * `SigningError` only on caller-side contract violations
+     * (`ctx.length > 255`) or `RangeError` on category violations and
+     * unsupported `ph`.
+     */
+    verifyHash(pk, M, sig, ph, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        this._assertHashPrereqs(ph);
+        validateMessage(M);
+        if (!(pk instanceof Uint8Array) || pk.length !== this.params.pkBytes)
+            return false;
+        if (!(sig instanceof Uint8Array) || sig.length !== this.params.sigBytes)
+            return false;
+        validateContext(ctx);
+        const sha2x = algoNeedsSha2(ph) ? this.sha2x : undefined;
+        const sha3x = algoNeedsSha3(ph) ? this.sx : undefined;
+        const PH_M = preHashMessage(sha3x, sha2x, ph, M);
+        try {
+            return verifyWithPrehash(this.x, this.params, pk, PH_M, sig, ph, ctx);
+        }
+        finally {
+            wipe(PH_M);
+            if (sha2x)
+                sha2x.wipeBuffers();
+            if (sha3x)
+                sha3x.wipeBuffers();
+        }
+    }
+    // ── HashSLH-DSA prehashed variants, FIPS 205 §10.2.2 ──────────────────
+    //
+    // The "caller already computed PH" surface. signHash family above runs
+    // PH ← Hash(M, ph) internally; the prehashed family skips that step
+    // and accepts PH directly. Use them when M is not buffered in one
+    // place (streaming signers, protocols that already produced a digest
+    // as part of a transcript) or when a verifier prescribes a specific
+    // prehash and hands you the bytes.
+    //
+    // Wrong-size digest is a contract violation on the sign side (throws
+    // `SigningError('sig-malformed-input')`) and a structural verdict on
+    // the verify side (returns false, no throw), mirroring §3.6.2 for
+    // wrong-size pk / σ.
+    /**
+     * Hedged HashSLH-DSA sign with a caller-supplied prehash. FIPS 205
+     * §10.2.2 Algorithm 23 lines 18-25 (the post-PH path).
+     *
+     * `digest` must be exactly `digestSize(ph)` bytes; a mismatch throws
+     * `SigningError('sig-malformed-input')`. The caller owns `digest`
+     * and is responsible for wiping it; this method never mutates the
+     * buffer. Hedged variant generates a fresh n-byte opt_rand per call.
+     */
+    signHashPrehashed(sk, digest, ph, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        this._assertHashPrereqs(ph);
+        validateSigningKey(sk, this.params);
+        validateContext(ctx);
+        validateDigest(digest, ph);
+        const optRand = randomBytes(this.params.n);
+        try {
+            return signWithPrehash(this.x, this.params, sk, digest, ph, ctx, optRand);
+        }
+        finally {
+            wipe(optRand);
+        }
+    }
+    /**
+     * Deterministic HashSLH-DSA sign with a caller-supplied prehash,
+     * opt_rand ← PK.seed per FIPS 205 §3.4. Same fault-attack caveat as
+     * {@link signDeterministic}.
+     */
+    signHashPrehashedDeterministic(sk, digest, ph, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        this._assertHashPrereqs(ph);
+        validateSigningKey(sk, this.params);
+        validateContext(ctx);
+        validateDigest(digest, ph);
+        const n = this.params.n;
+        const optRand = sk.slice(2 * n, 3 * n);
+        try {
+            return signWithPrehash(this.x, this.params, sk, digest, ph, ctx, optRand);
+        }
+        finally {
+            wipe(optRand);
+        }
+    }
+    /**
+     * Externally-randomised HashSLH-DSA sign with a caller-supplied
+     * prehash, testing / CAVP API. Caller supplies the n-byte opt_rand:
+     * MUST come from an approved RBG and MUST NOT be reused across
+     * signatures.
+     */
+    signHashPrehashedDerand(sk, digest, ph, optRand, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        this._assertHashPrereqs(ph);
+        validateSigningKey(sk, this.params);
+        validateContext(ctx);
+        validateRnd(optRand, this.params);
+        validateDigest(digest, ph);
+        return signWithPrehash(this.x, this.params, sk, digest, ph, ctx, optRand);
+    }
+    /**
+     * HashSLH-DSA verify with a caller-supplied prehash. FIPS 205 §10.3
+     * Algorithm 25 lines 16-19 (the post-PH path).
+     *
+     * Returns boolean for every signature outcome. Wrong-length pk / σ
+     * and wrong-size `digest` all return `false` (FIPS 205 §3.6.2 /
+     * §10.3 structural mismatch). Throws on caller-side contract
+     * violations only (`ctx.length > 255`, unsupported `ph`, category
+     * mismatch).
+     */
+    verifyHashPrehashed(pk, digest, sig, ph, ctx = new Uint8Array(0)) {
+        _assertNotOwned('slhdsa');
+        this._assertHashPrereqs(ph);
+        if (!(pk instanceof Uint8Array) || pk.length !== this.params.pkBytes)
+            return false;
+        if (!(sig instanceof Uint8Array) || sig.length !== this.params.sigBytes)
+            return false;
+        if (!(digest instanceof Uint8Array) || digest.length !== digestSize(ph))
+            return false;
+        validateContext(ctx);
+        return verifyWithPrehash(this.x, this.params, pk, digest, sig, ph, ctx);
+    }
+    dispose() {
+        // SlhDsaBase is atomic-only (no per-instance state beyond the
+        // readonly params). Every public method already runs
+        // wipeBuffers() in its own finally, so this dispose is just a
+        // final hygiene pass for defence-in-depth.
+        try {
+            this.x.wipeBuffers();
+        }
+        catch {
+            // dispose() is idempotent and must not throw even if the
+            // module was somehow torn down before the user finished.
+        }
+    }
+}
+// ── Public classes ──────────────────────────────────────────────────────────
+/** SLH-DSA-SHAKE-128f, FIPS 205 §11.1 Table 2 (NIST security category 1). */
+export class SlhDsa128f extends SlhDsaBase {
+    constructor() {
+        super(SLHDSA128F);
+    }
+}
+/** SLH-DSA-SHAKE-192f, FIPS 205 §11.1 Table 2 (NIST security category 3). */
+export class SlhDsa192f extends SlhDsaBase {
+    constructor() {
+        super(SLHDSA192F);
+    }
+}
+/** SLH-DSA-SHAKE-256f, FIPS 205 §11.1 Table 2 (NIST security category 5). */
+export class SlhDsa256f extends SlhDsaBase {
+    constructor() {
+        super(SLHDSA256F);
+    }
+}

package/dist/slhdsa/params.d.ts

@@ -0,0 +1,26 @@
+export interface SlhDsaParams {
+    paramSet: 'SLH-DSA-SHAKE-128f' | 'SLH-DSA-SHAKE-192f' | 'SLH-DSA-SHAKE-256f';
+    n: number;
+    h: number;
+    d: number;
+    hPrime: number;
+    k: number;
+    a: number;
+    m: number;
+    pkBytes: number;
+    skBytes: number;
+    sigBytes: number;
+    securityCategory: 1 | 3 | 5;
+    /** Bind this parameter set into the WASM PARAMS slot. Called by every
+     *  SlhDsaBase public method before driving slh{Keygen,Sign,Verify}Internal
+     *  so the WASM dimension lookups (slhK, slhA, slhD, slhHPrime, etc.)
+     *  resolve to this set. Reads the slhdsa exports lazily so the function
+     *  reference can be shared across modules without baking in an instance. */
+    wasmSelector: () => void;
+}
+/** SLH-DSA-SHAKE-128f, FIPS 205 §11.1 Table 2 (NIST security category 1). */
+export declare const SLHDSA128F: SlhDsaParams;
+/** SLH-DSA-SHAKE-192f, FIPS 205 §11.1 Table 2 (NIST security category 3). */
+export declare const SLHDSA192F: SlhDsaParams;
+/** SLH-DSA-SHAKE-256f, FIPS 205 §11.1 Table 2 (NIST security category 5). */
+export declare const SLHDSA256F: SlhDsaParams;

package/dist/slhdsa/params.js

@@ -0,0 +1,70 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/slhdsa/params.ts
+//
+// SLH-DSA (FIPS 205) parameter sets.
+//
+// Numeric values come from FIPS 205 §11.1 Table 2; derived sizes come from
+// FIPS 205 §11.2 (pk = 2·n, sk = 4·n) and the §9 sigEncode algorithm:
+//
+//   sigBytes = (1 + k·(a+1) + h + d·len) · n
+//
+// where w = 16 (the only approved Winternitz parameter in §11.1), so
+// len_1 = ⌈8·n/4⌉, len_2 = 3, len = len_1 + len_2.
+//
+// Current scope is the SHAKE-family fast variants (128f / 192f / 256f) only;
+// the slow variants and the SHA-2 family are explicitly out of scope.
+//
+// `securityCategory` (NIST PQC category 1 / 3 / 5) drives the per-set
+// HashSLH-DSA category gate in `validate.ts` / `index.ts`. `wasmSelector`
+// runs the corresponding `slhSetParams*` thunk on the WASM module so the
+// PARAMS slot reflects this set before any algorithm call.
+import { getInstance } from '../init.js';
+function selectorFor(name) {
+    return () => {
+        getInstance('slhdsa').exports[name]();
+    };
+}
+/** SLH-DSA-SHAKE-128f, FIPS 205 §11.1 Table 2 (NIST security category 1). */
+export const SLHDSA128F = {
+    paramSet: 'SLH-DSA-SHAKE-128f',
+    n: 16, h: 66, d: 22, hPrime: 3, k: 33, a: 6, m: 34,
+    pkBytes: 32, skBytes: 64, sigBytes: 17088,
+    securityCategory: 1,
+    wasmSelector: selectorFor('slhSetParams128f'),
+};
+/** SLH-DSA-SHAKE-192f, FIPS 205 §11.1 Table 2 (NIST security category 3). */
+export const SLHDSA192F = {
+    paramSet: 'SLH-DSA-SHAKE-192f',
+    n: 24, h: 66, d: 22, hPrime: 3, k: 33, a: 8, m: 42,
+    pkBytes: 48, skBytes: 96, sigBytes: 35664,
+    securityCategory: 3,
+    wasmSelector: selectorFor('slhSetParams192f'),
+};
+/** SLH-DSA-SHAKE-256f, FIPS 205 §11.1 Table 2 (NIST security category 5). */
+export const SLHDSA256F = {
+    paramSet: 'SLH-DSA-SHAKE-256f',
+    n: 32, h: 68, d: 17, hPrime: 4, k: 35, a: 9, m: 49,
+    pkBytes: 64, skBytes: 128, sigBytes: 49856,
+    securityCategory: 5,
+    wasmSelector: selectorFor('slhSetParams256f'),
+};

package/dist/slhdsa/prehash.d.ts

@@ -0,0 +1,68 @@
+import type { Sha3Exports } from '../mldsa/types.js';
+import type { Sha2Exports } from '../sha2/types.js';
+/** FIPS 205 §10.2.2 approved pre-hash functions, same surface as FIPS 204
+ *  §5.4.1. Names follow the FIPS 204 / FIPS 205 spelling (no hyphen
+ *  between SHAKE and the digit). The SHAKE entries are XOFs with fixed
+ *  output lengths set by FIPS 205 §10.2.2 Algorithm 23: SHAKE128 → 256-bit
+ *  (32-byte) output, SHAKE256 → 512-bit (64-byte). */
+export type PreHashAlgorithm = 'SHA2-224' | 'SHA2-256' | 'SHA2-384' | 'SHA2-512' | 'SHA2-512/224' | 'SHA2-512/256' | 'SHA3-224' | 'SHA3-256' | 'SHA3-384' | 'SHA3-512' | 'SHAKE128' | 'SHAKE256';
+/** Look up the FIPS 205 §10.2.2 OID DER bytes for `algo`. Returns a fresh
+ *  Uint8Array each call so callers can wipe / mutate without aliasing the
+ *  module-private constant. */
+export declare function getOid(algo: PreHashAlgorithm): Uint8Array;
+/** FIPS 205 §10.2.2 PH_M byte length for `algo`. SHAKE128 / SHAKE256 are
+ *  XOFs but the spec fixes their HashSLH-DSA output to 32 / 64 bytes
+ *  respectively; the SHA-3 and SHA-2 entries return their natural digest
+ *  size. Used by `validateDigest` to bound the caller-supplied prehash.
+ *
+ *  Duplicated from `src/ts/mldsa/hashvariant.ts:digestSize`; extraction
+ *  is deferred until a third consumer materialises. */
+export declare function digestSize(algo: PreHashAlgorithm): number;
+/** True iff `algo` is one of the SHA-2 family pre-hashes (and therefore
+ *  requires `init({ sha2: ... })`). The SHA-3 family and SHAKE variants
+ *  use the `sha3` module. */
+export declare function algoNeedsSha2(algo: PreHashAlgorithm): boolean;
+/** True iff `algo` is a SHA-3 or SHAKE pre-hash (and therefore requires
+ *  `init({ sha3: ... })`). slhdsa's own embedded Keccak permutation is
+ *  used internally by `slh_sign_internal` / `slh_verify_internal`, but the
+ *  HashSLH-DSA prehash dispatcher routes through the `sha3` module to keep
+ *  the public surface byte-identical with `src/ts/mldsa/hashvariant.ts`
+ *  (which also uses the sha3 module). */
+export declare function algoNeedsSha3(algo: PreHashAlgorithm): boolean;
+/**
+ * Build the HashSLH-DSA M' = 0x01 ‖ |ctx| ‖ ctx ‖ OID ‖ PH_M.
+ *
+ * FIPS 205 §10.2.2 Algorithm 23 lines 18-19 (sign) and §10.3 Algorithm 25
+ * lines 16-17 (verify). The leading byte is 0x01 (vs 0x00 for pure
+ * SLH-DSA), domain separation across pure / pre-hash modes per FIPS 205
+ * §10.2 narrative. Caller has already validated ctx.length ≤ 255.
+ *
+ * Byte-identical to FIPS 204 §5.4 Algorithm 4 M' construction; see
+ * src/ts/mldsa/hashvariant.ts and src/ts/mldsa/format.ts:constructMPrimeHash
+ * for the ML-DSA mirror. Q7 resolution: duplicate, do not extract.
+ */
+export declare function constructMPrimeHash(digest: Uint8Array, ph: PreHashAlgorithm, ctx: Uint8Array): Uint8Array;
+/**
+ * Build the pure-mode M' = 0x00 ‖ |ctx| ‖ ctx ‖ M for FIPS 205 §10.2.1
+ * Algorithm 22 line 8 (sign) and §10.3 Algorithm 24 line 8 (verify).
+ *
+ * Caller has already validated ctx.length ≤ 255. The leading byte is 0x00,
+ * which separates pure SLH-DSA signatures from HashSLH-DSA signatures (the
+ * latter prepends 0x01 via constructMPrimeHash) on the same key per the
+ * §10.2 narrative.
+ */
+export declare function constructMPrimePure(M: Uint8Array, ctx: Uint8Array): Uint8Array;
+/**
+ * Pre-hash dispatcher, applies the FIPS 205 §10.2.2 hash function `algo`
+ * to message `M` and returns PH_M (the bytes that go into M' alongside
+ * the OID).
+ *
+ * `sx` is the sha3-wasm Sha3Exports, required for SHA-3 / SHAKE prehashes.
+ * `sha2x` is the sha2-wasm Sha2Exports, required for SHA-2 prehashes.
+ * Either argument may be `undefined` when the chosen `algo` does not need
+ * that module; the dispatcher throws a clear error if a required module
+ * is missing rather than NPE'ing on a member access. Pure-SLH-DSA users
+ * call neither (slhdsa-wasm has its own embedded Keccak permutation), so
+ * both modules are strictly optional.
+ */
+export declare function preHashMessage(sx: Sha3Exports | undefined, sha2x: Sha2Exports | undefined, algo: PreHashAlgorithm, M: Uint8Array): Uint8Array;