@theqrl/dilithium5 1.1.0 → 1.1.2

package/README.md

@@ -55,7 +55,7 @@ console.log(new TextDecoder().decode(extracted));  // "Hello, quantum world!"
 
 Generate a keypair from a seed.
 
-- `seed`: `Uint8Array(32)` or `null` for random
+- `seed`: `Uint8Array(32)`, `null`, or `undefined` for random
 - `pk`: `Uint8Array(2592)` - output buffer for public key
 - `sk`: `Uint8Array(4896)` - output buffer for secret key
 - Returns: The seed used (useful when `seed` is `null`)
@@ -102,10 +102,17 @@ Verify a detached signature.
 
 Zero out sensitive data (best-effort, see security notes).
 
+- `buffer`: `Uint8Array` - the buffer to zero
+- Throws: `TypeError` if buffer is not a `Uint8Array`
+
 #### `isZero(buffer)`
 
 Check if buffer is all zeros (constant-time).
 
+- `buffer`: `Uint8Array` - the buffer to check
+- Returns: `true` if all bytes are zero
+- Throws: `TypeError` if buffer is not a `Uint8Array`
+
 ## Interoperability with go-qrllib
 
 go-qrllib pre-hashes seeds with SHAKE256 before key generation. To generate matching keys:

package/dist/cjs/dilithium5.js

@@ -1,8 +1,5 @@
 'use strict';
 
-var sha3_js = require('@noble/hashes/sha3.js');
-var utils_js = require('@noble/hashes/utils.js');
-
 const Shake128Rate = 168;
 const Shake256Rate = 136;
 const Stream128BlockBytes = Shake128Rate;
@@ -65,6 +62,386 @@ const zetas = [
   -1362209, 3937738, 1400424, -846154, 1976782,
 ];
 
+/**
+ * Internal helpers for u64. BigUint64Array is too slow as per 2025, so we implement it using Uint32Array.
+ * @todo re-check https://issues.chromium.org/issues/42212588
+ * @module
+ */
+const U32_MASK64 = /* @__PURE__ */ BigInt(2 ** 32 - 1);
+const _32n = /* @__PURE__ */ BigInt(32);
+function fromBig(n, le = false) {
+    if (le)
+        return { h: Number(n & U32_MASK64), l: Number((n >> _32n) & U32_MASK64) };
+    return { h: Number((n >> _32n) & U32_MASK64) | 0, l: Number(n & U32_MASK64) | 0 };
+}
+function split(lst, le = false) {
+    const len = lst.length;
+    let Ah = new Uint32Array(len);
+    let Al = new Uint32Array(len);
+    for (let i = 0; i < len; i++) {
+        const { h, l } = fromBig(lst[i], le);
+        [Ah[i], Al[i]] = [h, l];
+    }
+    return [Ah, Al];
+}
+// Left rotate for Shift in [1, 32)
+const rotlSH = (h, l, s) => (h << s) | (l >>> (32 - s));
+const rotlSL = (h, l, s) => (l << s) | (h >>> (32 - s));
+// Left rotate for Shift in (32, 64), NOTE: 32 is special case.
+const rotlBH = (h, l, s) => (l << (s - 32)) | (h >>> (64 - s));
+const rotlBL = (h, l, s) => (h << (s - 32)) | (l >>> (64 - s));
+
+/**
+ * Utilities for hex, bytes, CSPRNG.
+ * @module
+ */
+/*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+/** Checks if something is Uint8Array. Be careful: nodejs Buffer will return true. */
+function isBytes(a) {
+    return a instanceof Uint8Array || (ArrayBuffer.isView(a) && a.constructor.name === 'Uint8Array');
+}
+/** Asserts something is positive integer. */
+function anumber(n, title = '') {
+    if (!Number.isSafeInteger(n) || n < 0) {
+        const prefix = title && `"${title}" `;
+        throw new Error(`${prefix}expected integer >= 0, got ${n}`);
+    }
+}
+/** Asserts something is Uint8Array. */
+function abytes(value, length, title = '') {
+    const bytes = isBytes(value);
+    const len = value?.length;
+    const needsLen = length !== undefined;
+    if (!bytes || (needsLen)) {
+        const prefix = title && `"${title}" `;
+        const ofLen = '';
+        const got = bytes ? `length=${len}` : `type=${typeof value}`;
+        throw new Error(prefix + 'expected Uint8Array' + ofLen + ', got ' + got);
+    }
+    return value;
+}
+/** Asserts a hash instance has not been destroyed / finished */
+function aexists(instance, checkFinished = true) {
+    if (instance.destroyed)
+        throw new Error('Hash instance has been destroyed');
+    if (checkFinished && instance.finished)
+        throw new Error('Hash#digest() has already been called');
+}
+/** Asserts output is properly-sized byte array */
+function aoutput(out, instance) {
+    abytes(out, undefined, 'digestInto() output');
+    const min = instance.outputLen;
+    if (out.length < min) {
+        throw new Error('"digestInto() output" expected to be of length >=' + min);
+    }
+}
+/** Cast u8 / u16 / u32 to u32. */
+function u32(arr) {
+    return new Uint32Array(arr.buffer, arr.byteOffset, Math.floor(arr.byteLength / 4));
+}
+/** Zeroize a byte array. Warning: JS provides no guarantees. */
+function clean(...arrays) {
+    for (let i = 0; i < arrays.length; i++) {
+        arrays[i].fill(0);
+    }
+}
+/** Is current platform little-endian? Most are. Big-Endian platform: IBM */
+const isLE = /* @__PURE__ */ (() => new Uint8Array(new Uint32Array([0x11223344]).buffer)[0] === 0x44)();
+/** The byte swap operation for uint32 */
+function byteSwap(word) {
+    return (((word << 24) & 0xff000000) |
+        ((word << 8) & 0xff0000) |
+        ((word >>> 8) & 0xff00) |
+        ((word >>> 24) & 0xff));
+}
+/** In place byte swap for Uint32Array */
+function byteSwap32(arr) {
+    for (let i = 0; i < arr.length; i++) {
+        arr[i] = byteSwap(arr[i]);
+    }
+    return arr;
+}
+const swap32IfBE = isLE
+    ? (u) => u
+    : byteSwap32;
+// Built-in hex conversion https://caniuse.com/mdn-javascript_builtins_uint8array_fromhex
+const hasHexBuiltin = /* @__PURE__ */ (() => 
+// @ts-ignore
+typeof Uint8Array.from([]).toHex === 'function' && typeof Uint8Array.fromHex === 'function')();
+// We use optimized technique to convert hex string to byte array
+const asciis = { _0: 48, _9: 57, A: 65, F: 70, a: 97, f: 102 };
+function asciiToBase16(ch) {
+    if (ch >= asciis._0 && ch <= asciis._9)
+        return ch - asciis._0; // '2' => 50-48
+    if (ch >= asciis.A && ch <= asciis.F)
+        return ch - (asciis.A - 10); // 'B' => 66-(65-10)
+    if (ch >= asciis.a && ch <= asciis.f)
+        return ch - (asciis.a - 10); // 'b' => 98-(97-10)
+    return;
+}
+/**
+ * Convert hex string to byte array. Uses built-in function, when available.
+ * @example hexToBytes('cafe0123') // Uint8Array.from([0xca, 0xfe, 0x01, 0x23])
+ */
+function hexToBytes$1(hex) {
+    if (typeof hex !== 'string')
+        throw new Error('hex string expected, got ' + typeof hex);
+    // @ts-ignore
+    if (hasHexBuiltin)
+        return Uint8Array.fromHex(hex);
+    const hl = hex.length;
+    const al = hl / 2;
+    if (hl % 2)
+        throw new Error('hex string expected, got unpadded hex of length ' + hl);
+    const array = new Uint8Array(al);
+    for (let ai = 0, hi = 0; ai < al; ai++, hi += 2) {
+        const n1 = asciiToBase16(hex.charCodeAt(hi));
+        const n2 = asciiToBase16(hex.charCodeAt(hi + 1));
+        if (n1 === undefined || n2 === undefined) {
+            const char = hex[hi] + hex[hi + 1];
+            throw new Error('hex string expected, got non-hex character "' + char + '" at index ' + hi);
+        }
+        array[ai] = n1 * 16 + n2; // multiply first octet, e.g. 'a3' => 10*16+3 => 160 + 3 => 163
+    }
+    return array;
+}
+/** Creates function with outputLen, blockLen, create properties from a class constructor. */
+function createHasher(hashCons, info = {}) {
+    const hashC = (msg, opts) => hashCons(opts).update(msg).digest();
+    const tmp = hashCons(undefined);
+    hashC.outputLen = tmp.outputLen;
+    hashC.blockLen = tmp.blockLen;
+    hashC.create = (opts) => hashCons(opts);
+    Object.assign(hashC, info);
+    return Object.freeze(hashC);
+}
+/** Creates OID opts for NIST hashes, with prefix 06 09 60 86 48 01 65 03 04 02. */
+const oidNist = (suffix) => ({
+    oid: Uint8Array.from([0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, suffix]),
+});
+
+/**
+ * SHA3 (keccak) hash function, based on a new "Sponge function" design.
+ * Different from older hashes, the internal state is bigger than output size.
+ *
+ * Check out [FIPS-202](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf),
+ * [Website](https://keccak.team/keccak.html),
+ * [the differences between SHA-3 and Keccak](https://crypto.stackexchange.com/questions/15727/what-are-the-key-differences-between-the-draft-sha-3-standard-and-the-keccak-sub).
+ *
+ * Check out `sha3-addons` module for cSHAKE, k12, and others.
+ * @module
+ */
+// No __PURE__ annotations in sha3 header:
+// EVERYTHING is in fact used on every export.
+// Various per round constants calculations
+const _0n = BigInt(0);
+const _1n = BigInt(1);
+const _2n = BigInt(2);
+const _7n = BigInt(7);
+const _256n = BigInt(256);
+const _0x71n = BigInt(0x71);
+const SHA3_PI = [];
+const SHA3_ROTL = [];
+const _SHA3_IOTA = []; // no pure annotation: var is always used
+for (let round = 0, R = _1n, x = 1, y = 0; round < 24; round++) {
+    // Pi
+    [x, y] = [y, (2 * x + 3 * y) % 5];
+    SHA3_PI.push(2 * (5 * y + x));
+    // Rotational
+    SHA3_ROTL.push((((round + 1) * (round + 2)) / 2) % 64);
+    // Iota
+    let t = _0n;
+    for (let j = 0; j < 7; j++) {
+        R = ((R << _1n) ^ ((R >> _7n) * _0x71n)) % _256n;
+        if (R & _2n)
+            t ^= _1n << ((_1n << BigInt(j)) - _1n);
+    }
+    _SHA3_IOTA.push(t);
+}
+const IOTAS = split(_SHA3_IOTA, true);
+const SHA3_IOTA_H = IOTAS[0];
+const SHA3_IOTA_L = IOTAS[1];
+// Left rotation (without 0, 32, 64)
+const rotlH = (h, l, s) => (s > 32 ? rotlBH(h, l, s) : rotlSH(h, l, s));
+const rotlL = (h, l, s) => (s > 32 ? rotlBL(h, l, s) : rotlSL(h, l, s));
+/** `keccakf1600` internal function, additionally allows to adjust round count. */
+function keccakP(s, rounds = 24) {
+    const B = new Uint32Array(5 * 2);
+    // NOTE: all indices are x2 since we store state as u32 instead of u64 (bigints to slow in js)
+    for (let round = 24 - rounds; round < 24; round++) {
+        // Theta θ
+        for (let x = 0; x < 10; x++)
+            B[x] = s[x] ^ s[x + 10] ^ s[x + 20] ^ s[x + 30] ^ s[x + 40];
+        for (let x = 0; x < 10; x += 2) {
+            const idx1 = (x + 8) % 10;
+            const idx0 = (x + 2) % 10;
+            const B0 = B[idx0];
+            const B1 = B[idx0 + 1];
+            const Th = rotlH(B0, B1, 1) ^ B[idx1];
+            const Tl = rotlL(B0, B1, 1) ^ B[idx1 + 1];
+            for (let y = 0; y < 50; y += 10) {
+                s[x + y] ^= Th;
+                s[x + y + 1] ^= Tl;
+            }
+        }
+        // Rho (ρ) and Pi (π)
+        let curH = s[2];
+        let curL = s[3];
+        for (let t = 0; t < 24; t++) {
+            const shift = SHA3_ROTL[t];
+            const Th = rotlH(curH, curL, shift);
+            const Tl = rotlL(curH, curL, shift);
+            const PI = SHA3_PI[t];
+            curH = s[PI];
+            curL = s[PI + 1];
+            s[PI] = Th;
+            s[PI + 1] = Tl;
+        }
+        // Chi (χ)
+        for (let y = 0; y < 50; y += 10) {
+            for (let x = 0; x < 10; x++)
+                B[x] = s[y + x];
+            for (let x = 0; x < 10; x++)
+                s[y + x] ^= ~B[(x + 2) % 10] & B[(x + 4) % 10];
+        }
+        // Iota (ι)
+        s[0] ^= SHA3_IOTA_H[round];
+        s[1] ^= SHA3_IOTA_L[round];
+    }
+    clean(B);
+}
+/** Keccak sponge function. */
+class Keccak {
+    state;
+    pos = 0;
+    posOut = 0;
+    finished = false;
+    state32;
+    destroyed = false;
+    blockLen;
+    suffix;
+    outputLen;
+    enableXOF = false;
+    rounds;
+    // NOTE: we accept arguments in bytes instead of bits here.
+    constructor(blockLen, suffix, outputLen, enableXOF = false, rounds = 24) {
+        this.blockLen = blockLen;
+        this.suffix = suffix;
+        this.outputLen = outputLen;
+        this.enableXOF = enableXOF;
+        this.rounds = rounds;
+        // Can be passed from user as dkLen
+        anumber(outputLen, 'outputLen');
+        // 1600 = 5x5 matrix of 64bit.  1600 bits === 200 bytes
+        // 0 < blockLen < 200
+        if (!(0 < blockLen && blockLen < 200))
+            throw new Error('only keccak-f1600 function is supported');
+        this.state = new Uint8Array(200);
+        this.state32 = u32(this.state);
+    }
+    clone() {
+        return this._cloneInto();
+    }
+    keccak() {
+        swap32IfBE(this.state32);
+        keccakP(this.state32, this.rounds);
+        swap32IfBE(this.state32);
+        this.posOut = 0;
+        this.pos = 0;
+    }
+    update(data) {
+        aexists(this);
+        abytes(data);
+        const { blockLen, state } = this;
+        const len = data.length;
+        for (let pos = 0; pos < len;) {
+            const take = Math.min(blockLen - this.pos, len - pos);
+            for (let i = 0; i < take; i++)
+                state[this.pos++] ^= data[pos++];
+            if (this.pos === blockLen)
+                this.keccak();
+        }
+        return this;
+    }
+    finish() {
+        if (this.finished)
+            return;
+        this.finished = true;
+        const { state, suffix, pos, blockLen } = this;
+        // Do the padding
+        state[pos] ^= suffix;
+        if ((suffix & 0x80) !== 0 && pos === blockLen - 1)
+            this.keccak();
+        state[blockLen - 1] ^= 0x80;
+        this.keccak();
+    }
+    writeInto(out) {
+        aexists(this, false);
+        abytes(out);
+        this.finish();
+        const bufferOut = this.state;
+        const { blockLen } = this;
+        for (let pos = 0, len = out.length; pos < len;) {
+            if (this.posOut >= blockLen)
+                this.keccak();
+            const take = Math.min(blockLen - this.posOut, len - pos);
+            out.set(bufferOut.subarray(this.posOut, this.posOut + take), pos);
+            this.posOut += take;
+            pos += take;
+        }
+        return out;
+    }
+    xofInto(out) {
+        // Sha3/Keccak usage with XOF is probably mistake, only SHAKE instances can do XOF
+        if (!this.enableXOF)
+            throw new Error('XOF is not possible for this instance');
+        return this.writeInto(out);
+    }
+    xof(bytes) {
+        anumber(bytes);
+        return this.xofInto(new Uint8Array(bytes));
+    }
+    digestInto(out) {
+        aoutput(out, this);
+        if (this.finished)
+            throw new Error('digest() was already called');
+        this.writeInto(out);
+        this.destroy();
+        return out;
+    }
+    digest() {
+        return this.digestInto(new Uint8Array(this.outputLen));
+    }
+    destroy() {
+        this.destroyed = true;
+        clean(this.state);
+    }
+    _cloneInto(to) {
+        const { blockLen, suffix, outputLen, rounds, enableXOF } = this;
+        to ||= new Keccak(blockLen, suffix, outputLen, enableXOF, rounds);
+        to.state32.set(this.state32);
+        to.pos = this.pos;
+        to.posOut = this.posOut;
+        to.finished = this.finished;
+        to.rounds = rounds;
+        // Suffix can change in cSHAKE
+        to.suffix = suffix;
+        to.outputLen = outputLen;
+        to.enableXOF = enableXOF;
+        to.destroyed = this.destroyed;
+        return to;
+    }
+}
+const genShake = (suffix, blockLen, outputLen, info = {}) => createHasher((opts = {}) => new Keccak(blockLen, suffix, opts.dkLen === undefined ? outputLen : opts.dkLen, true), info);
+/** SHAKE128 XOF with 128-bit security. */
+const shake128 = 
+/* @__PURE__ */
+genShake(0x1f, 168, 16, /* @__PURE__ */ oidNist(0x0b));
+/** SHAKE256 XOF with 256-bit security. */
+const shake256 = 
+/* @__PURE__ */
+genShake(0x1f, 136, 32, /* @__PURE__ */ oidNist(0x0c));
+
 /**
  * FIPS 202 SHAKE functions using @noble/hashes
  * Provides streaming XOF (extendable output function) interface
@@ -85,7 +462,7 @@ class KeccakState {
 // SHAKE-128 functions
 
 function shake128Init(state) {
-  state.hasher = sha3_js.shake128.create({});
+  state.hasher = shake128.create({});
   state.finalized = false;
 }
 
@@ -107,7 +484,7 @@ function shake128SqueezeBlocks(out, outputOffset, nBlocks, state) {
 // SHAKE-256 functions
 
 function shake256Init(state) {
-  state.hasher = sha3_js.shake256.create({});
+  state.hasher = shake256.create({});
   state.finalized = false;
 }
 
@@ -160,12 +537,16 @@ function montgomeryReduce(a) {
   return t;
 }
 
+// Partial reduction modulo Q. Input must satisfy |a| < 2^31 - 2^22.
+// Output is in (-Q, Q). Mirrors the reference C implementation.
 function reduce32(a) {
   let t = (a + (1 << 22)) >> 23;
   t = a - t * Q;
   return t;
 }
 
+// Conditional add Q: if a is negative, add Q. Input must satisfy -Q < a < 2^31.
+// Output is in [0, Q). Mirrors the reference C implementation.
 function cAddQ(a) {
   let ar = a;
   ar += (ar >> 31) & Q;
@@ -174,7 +555,7 @@ function cAddQ(a) {
 
 function ntt(a) {
   let k = 0;
-  let j = 0;
+  let j;
 
   for (let len = 128; len > 0; len >>= 1) {
     for (let start = 0; start < N; start = j + len) {
@@ -190,7 +571,7 @@ function ntt(a) {
 
 function invNTTToMont(a) {
   const f = 41978n; // mont^2/256
-  let j = 0;
+  let j;
   let k = 256;
 
   for (let len = 1; len < N; len <<= 1) {
@@ -327,10 +708,7 @@ function polyChkNorm(a, b) {
   }
 
   for (let i = 0; i < N; i++) {
-    let t = a.coeffs[i] >> 31;
-    t = a.coeffs[i] - (t & (2 * a.coeffs[i]));
-
-    if (t >= b) {
+    if (Math.abs(a.coeffs[i]) >= b) {
       return 1;
     }
   }
@@ -449,6 +827,8 @@ function polyUniformGamma1(a, seed, nonce) {
 }
 
 function polyChallenge(cP, seed) {
+  if (seed.length !== SeedBytes) throw new Error('invalid seed length');
+
   let b;
   let pos;
   const c = cP;
@@ -456,7 +836,7 @@ function polyChallenge(cP, seed) {
 
   const state = new KeccakState();
   shake256Init(state);
-  shake256Absorb(state, seed.slice(0, SeedBytes));
+  shake256Absorb(state, seed);
   shake256Finalize(state);
   shake256SqueezeBlocks(buf, 0, 1, state);
 
@@ -869,6 +1249,9 @@ function packPk(pkp, rho, t1) {
 }
 
 function unpackPk(rhop, t1, pk) {
+  if (!(pk instanceof Uint8Array) || pk.length !== CryptoPublicKeyBytes) {
+    throw new Error(`pk must be a Uint8Array of ${CryptoPublicKeyBytes} bytes`);
+  }
   const rho = rhop;
   for (let i = 0; i < SeedBytes; ++i) {
     rho[i] = pk[i];
@@ -913,6 +1296,9 @@ function packSk(skp, rho, tr, key, t0, s1, s2) {
 }
 
 function unpackSk(rhoP, trP, keyP, t0, s1, s2, sk) {
+  if (!(sk instanceof Uint8Array) || sk.length !== CryptoSecretKeyBytes) {
+    throw new Error(`sk must be a Uint8Array of ${CryptoSecretKeyBytes} bytes`);
+  }
   let skOffset = 0;
   const rho = rhoP;
   const tr = trP;
@@ -976,7 +1362,12 @@ function packSig(sigP, c, z, h) {
   }
 }
 
+// Returns 0 on success, 1 on failure. On failure, output buffers (c, z, h)
+// may contain partial data and must not be used.
 function unpackSig(cP, z, hP, sig) {
+  if (!(sig instanceof Uint8Array) || sig.length !== CryptoBytes) {
+    throw new Error(`sig must be a Uint8Array of ${CryptoBytes} bytes`);
+  }
   let sigOffset = 0;
   const c = cP;
   const h = hP;
@@ -1076,6 +1467,8 @@ function randomBytes(size) {
  *
  * @param {Uint8Array} buffer - The buffer to zero
  * @returns {void}
+ * @throws {TypeError} If buffer is not a Uint8Array
+ * @throws {Error} If zeroization verification fails
  */
 function zeroize(buffer) {
   if (!(buffer instanceof Uint8Array)) {
@@ -1098,6 +1491,7 @@ function zeroize(buffer) {
  *
  * @param {Uint8Array} buffer - The buffer to check
  * @returns {boolean} True if all bytes are zero
+ * @throws {TypeError} If buffer is not a Uint8Array
  */
 function isZero(buffer) {
   if (!(buffer instanceof Uint8Array)) {
@@ -1113,16 +1507,12 @@ function isZero(buffer) {
 /**
  * Convert hex string to Uint8Array with strict validation.
  *
- * NOTE: This function accepts multiple hex formats (with/without 0x prefix,
- * leading/trailing whitespace). While user-friendly, this flexibility could
- * mask input errors. Applications requiring strict format validation should
- * validate hex format before calling cryptographic functions, e.g.:
- *   - Reject strings with 0x prefix if raw hex is expected
- *   - Reject strings with whitespace
- *   - Enforce consistent casing (lowercase/uppercase)
+ * Accepts an optional 0x/0X prefix. Leading/trailing whitespace is rejected.
+ * Empty strings and whitespace-only strings are rejected.
  *
- * @param {string} hex - Hex string (optional 0x prefix, even length).
+ * @param {string} hex - Hex string (optional 0x prefix, even length, no whitespace).
  * @returns {Uint8Array} Decoded bytes.
+ * @throws {Error} If input is not a valid hex string
  * @private
  */
 function hexToBytes(hex) {
@@ -1131,20 +1521,33 @@ function hexToBytes(hex) {
     throw new Error('message must be a hex string');
   }
   /* c8 ignore stop */
-  let clean = hex.trim();
-  // Accepts both "0x..." and raw hex formats for convenience
+  if (hex !== hex.trim()) {
+    throw new Error('hex string must not have leading or trailing whitespace');
+  }
+  let clean = hex;
   if (clean.startsWith('0x') || clean.startsWith('0X')) {
     clean = clean.slice(2);
   }
+  if (clean.length === 0) {
+    throw new Error('hex string must not be empty');
+  }
   if (clean.length % 2 !== 0) {
     throw new Error('hex string must have an even length');
   }
   if (!/^[0-9a-fA-F]*$/.test(clean)) {
     throw new Error('hex string contains non-hex characters');
   }
-  return utils_js.hexToBytes(clean);
+  return hexToBytes$1(clean);
 }
 
+/**
+ * Convert a message to Uint8Array.
+ *
+ * @param {string|Uint8Array} message - Message as hex string (optional 0x prefix) or Uint8Array.
+ * @returns {Uint8Array} Message bytes.
+ * @throws {Error} If message is not a Uint8Array or valid hex string
+ * @private
+ */
 function messageToBytes(message) {
   if (typeof message === 'string') {
     return hexToBytes(message);
@@ -1158,8 +1561,8 @@ function messageToBytes(message) {
 /**
  * Generate a Dilithium-5 key pair.
  *
- * @param {Uint8Array|null} passedSeed - Optional 32-byte seed for deterministic key generation.
- *   Pass null for random key generation.
+ * @param {Uint8Array|null} [passedSeed=null] - Optional 32-byte seed for deterministic key generation.
+ *   Pass null or undefined for random key generation.
  * @param {Uint8Array} pk - Output buffer for public key (must be CryptoPublicKeyBytes = 2592 bytes)
  * @param {Uint8Array} sk - Output buffer for secret key (must be CryptoSecretKeyBytes = 4896 bytes)
  * @returns {Uint8Array} The seed used for key generation (useful when passedSeed is null)
@@ -1180,9 +1583,9 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
     }
   } catch (e) {
     if (e instanceof TypeError) {
-      throw new Error(`pk/sk cannot be null`);
+      throw new Error(`pk/sk cannot be null`, { cause: e });
     } else {
-      throw new Error(`${e.message}`);
+      throw new Error(`${e.message}`, { cause: e });
     }
   }
 
@@ -1203,7 +1606,7 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
   const seed = passedSeed || randomBytes(SeedBytes);
 
   const outputLength = 2 * SeedBytes + CRHBytes;
-  const seedBuf = sha3_js.shake256.create({}).update(seed).xof(outputLength);
+  const seedBuf = shake256.create({}).update(seed).xof(outputLength);
   const rho = seedBuf.slice(0, SeedBytes);
   const rhoPrime = seedBuf.slice(SeedBytes, SeedBytes + CRHBytes);
   const key = seedBuf.slice(SeedBytes + CRHBytes);
@@ -1234,7 +1637,7 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
     packPk(pk, rho, t1);
 
     // Compute H(rho, t1) and write secret key
-    const tr = sha3_js.shake256.create({}).update(pk).xof(TRBytes);
+    const tr = shake256.create({}).update(pk).xof(TRBytes);
     packSk(sk, rho, tr, key, t0, s1, s2);
 
     return seed;
@@ -1260,15 +1663,25 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
  * @param {boolean} randomizedSigning - If true, use random nonce for hedged signing.
  *   If false, use deterministic nonce derived from message and key.
  * @returns {number} 0 on success
- * @throws {Error} If sk is wrong size
+ * @throws {TypeError} If sig is not a Uint8Array or is smaller than CryptoBytes
+ * @throws {TypeError} If sk is not a Uint8Array
+ * @throws {TypeError} If randomizedSigning is not a boolean
+ * @throws {Error} If sk length does not equal CryptoSecretKeyBytes
+ * @throws {Error} If message is not a Uint8Array or valid hex string
  *
  * @example
  * const sig = new Uint8Array(CryptoBytes);
  * cryptoSignSignature(sig, message, sk, false);
  */
 function cryptoSignSignature(sig, m, sk, randomizedSigning) {
-  if (!sig || sig.length < CryptoBytes) {
-    throw new Error(`sig must be at least ${CryptoBytes} bytes`);
+  if (!(sig instanceof Uint8Array) || sig.length < CryptoBytes) {
+    throw new TypeError(`sig must be at least ${CryptoBytes} bytes and a Uint8Array`);
+  }
+  if (!(sk instanceof Uint8Array)) {
+    throw new TypeError('sk must be a Uint8Array');
+  }
+  if (typeof randomizedSigning !== 'boolean') {
+    throw new TypeError('randomizedSigning must be a boolean');
   }
   if (sk.length !== CryptoSecretKeyBytes) {
     throw new Error(`invalid sk length ${sk.length} | Expected length ${CryptoSecretKeyBytes}`);
@@ -1297,12 +1710,12 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
   try {
     unpackSk(rho, tr, key, t0, s1, s2, sk);
 
-    const mu = sha3_js.shake256.create({}).update(tr).update(mBytes).xof(CRHBytes);
+    const mu = shake256.create({}).update(tr).update(mBytes).xof(CRHBytes);
 
     if (randomizedSigning) {
       rhoPrime = new Uint8Array(randomBytes(CRHBytes));
     } else {
-      rhoPrime = sha3_js.shake256.create({}).update(key).update(mu).xof(CRHBytes);
+      rhoPrime = shake256.create({}).update(key).update(mu).xof(CRHBytes);
     }
 
     polyVecMatrixExpand(mat, rho);
@@ -1324,14 +1737,14 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
       polyVecKDecompose(w1, w0, w1);
       polyVecKPackW1(sig, w1);
 
-      const cHash = sha3_js.shake256
+      const cHash = shake256
         .create({})
         .update(mu)
         .update(sig.slice(0, K * PolyW1PackedBytes))
         .xof(SeedBytes);
       sig.set(cHash);
 
-      polyChallenge(cp, sig);
+      polyChallenge(cp, sig.slice(0, SeedBytes));
       polyNTT(cp);
 
       // Compute z, reject if it reveals secret
@@ -1391,7 +1804,8 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
  * @param {Uint8Array} sk - Secret key (must be CryptoSecretKeyBytes = 4896 bytes)
  * @param {boolean} randomizedSigning - If true, use random nonce; if false, deterministic
  * @returns {Uint8Array} Signed message (CryptoBytes + msg.length bytes)
- * @throws {Error} If signing fails
+ * @throws {TypeError} If sk or randomizedSigning fail type validation (see cryptoSignSignature)
+ * @throws {Error} If signing fails or message/sk are invalid
  *
  * @example
  * const signedMsg = cryptoSign(message, sk, false);
@@ -1445,10 +1859,10 @@ function cryptoSignVerify(sig, m, pk) {
   const w1 = new PolyVecK();
   const h = new PolyVecK();
 
-  if (sig.length !== CryptoBytes) {
+  if (!(sig instanceof Uint8Array) || sig.length !== CryptoBytes) {
     return false;
   }
-  if (pk.length !== CryptoPublicKeyBytes) {
+  if (!(pk instanceof Uint8Array) || pk.length !== CryptoPublicKeyBytes) {
     return false;
   }
 
@@ -1461,7 +1875,7 @@ function cryptoSignVerify(sig, m, pk) {
   }
 
   /* Compute CRH(H(rho, t1), msg) */
-  const tr = sha3_js.shake256.create({}).update(pk).xof(TRBytes);
+  const tr = shake256.create({}).update(pk).xof(TRBytes);
   mu.set(tr);
 
   let mBytes;
@@ -1470,7 +1884,7 @@ function cryptoSignVerify(sig, m, pk) {
   } catch {
     return false;
   }
-  const muFull = sha3_js.shake256.create({}).update(mu.slice(0, TRBytes)).update(mBytes).xof(CRHBytes);
+  const muFull = shake256.create({}).update(mu.slice(0, TRBytes)).update(mBytes).xof(CRHBytes);
   mu.set(muFull);
 
   /* Matrix-vector multiplication; compute Az - c2^dt1 */
@@ -1495,7 +1909,7 @@ function cryptoSignVerify(sig, m, pk) {
   polyVecKPackW1(buf, w1);
 
   /* Call random oracle and verify challenge */
-  const c2Hash = sha3_js.shake256.create({}).update(mu).update(buf).xof(SeedBytes);
+  const c2Hash = shake256.create({}).update(mu).update(buf).xof(SeedBytes);
   c2.set(c2Hash);
 
   // Constant-time comparison to prevent timing attacks

package/dist/mjs/dilithium5.js

@@ -158,12 +158,16 @@ function montgomeryReduce(a) {
   return t;
 }
 
+// Partial reduction modulo Q. Input must satisfy |a| < 2^31 - 2^22.
+// Output is in (-Q, Q). Mirrors the reference C implementation.
 function reduce32(a) {
   let t = (a + (1 << 22)) >> 23;
   t = a - t * Q;
   return t;
 }
 
+// Conditional add Q: if a is negative, add Q. Input must satisfy -Q < a < 2^31.
+// Output is in [0, Q). Mirrors the reference C implementation.
 function cAddQ(a) {
   let ar = a;
   ar += (ar >> 31) & Q;
@@ -172,7 +176,7 @@ function cAddQ(a) {
 
 function ntt(a) {
   let k = 0;
-  let j = 0;
+  let j;
 
   for (let len = 128; len > 0; len >>= 1) {
     for (let start = 0; start < N; start = j + len) {
@@ -188,7 +192,7 @@ function ntt(a) {
 
 function invNTTToMont(a) {
   const f = 41978n; // mont^2/256
-  let j = 0;
+  let j;
   let k = 256;
 
   for (let len = 1; len < N; len <<= 1) {
@@ -325,10 +329,7 @@ function polyChkNorm(a, b) {
   }
 
   for (let i = 0; i < N; i++) {
-    let t = a.coeffs[i] >> 31;
-    t = a.coeffs[i] - (t & (2 * a.coeffs[i]));
-
-    if (t >= b) {
+    if (Math.abs(a.coeffs[i]) >= b) {
       return 1;
     }
   }
@@ -447,6 +448,8 @@ function polyUniformGamma1(a, seed, nonce) {
 }
 
 function polyChallenge(cP, seed) {
+  if (seed.length !== SeedBytes) throw new Error('invalid seed length');
+
   let b;
   let pos;
   const c = cP;
@@ -454,7 +457,7 @@ function polyChallenge(cP, seed) {
 
   const state = new KeccakState();
   shake256Init(state);
-  shake256Absorb(state, seed.slice(0, SeedBytes));
+  shake256Absorb(state, seed);
   shake256Finalize(state);
   shake256SqueezeBlocks(buf, 0, 1, state);
 
@@ -867,6 +870,9 @@ function packPk(pkp, rho, t1) {
 }
 
 function unpackPk(rhop, t1, pk) {
+  if (!(pk instanceof Uint8Array) || pk.length !== CryptoPublicKeyBytes) {
+    throw new Error(`pk must be a Uint8Array of ${CryptoPublicKeyBytes} bytes`);
+  }
   const rho = rhop;
   for (let i = 0; i < SeedBytes; ++i) {
     rho[i] = pk[i];
@@ -911,6 +917,9 @@ function packSk(skp, rho, tr, key, t0, s1, s2) {
 }
 
 function unpackSk(rhoP, trP, keyP, t0, s1, s2, sk) {
+  if (!(sk instanceof Uint8Array) || sk.length !== CryptoSecretKeyBytes) {
+    throw new Error(`sk must be a Uint8Array of ${CryptoSecretKeyBytes} bytes`);
+  }
   let skOffset = 0;
   const rho = rhoP;
   const tr = trP;
@@ -974,7 +983,12 @@ function packSig(sigP, c, z, h) {
   }
 }
 
+// Returns 0 on success, 1 on failure. On failure, output buffers (c, z, h)
+// may contain partial data and must not be used.
 function unpackSig(cP, z, hP, sig) {
+  if (!(sig instanceof Uint8Array) || sig.length !== CryptoBytes) {
+    throw new Error(`sig must be a Uint8Array of ${CryptoBytes} bytes`);
+  }
   let sigOffset = 0;
   const c = cP;
   const h = hP;
@@ -1074,6 +1088,8 @@ function randomBytes(size) {
  *
  * @param {Uint8Array} buffer - The buffer to zero
  * @returns {void}
+ * @throws {TypeError} If buffer is not a Uint8Array
+ * @throws {Error} If zeroization verification fails
  */
 function zeroize(buffer) {
   if (!(buffer instanceof Uint8Array)) {
@@ -1096,6 +1112,7 @@ function zeroize(buffer) {
  *
  * @param {Uint8Array} buffer - The buffer to check
  * @returns {boolean} True if all bytes are zero
+ * @throws {TypeError} If buffer is not a Uint8Array
  */
 function isZero(buffer) {
   if (!(buffer instanceof Uint8Array)) {
@@ -1111,16 +1128,12 @@ function isZero(buffer) {
 /**
  * Convert hex string to Uint8Array with strict validation.
  *
- * NOTE: This function accepts multiple hex formats (with/without 0x prefix,
- * leading/trailing whitespace). While user-friendly, this flexibility could
- * mask input errors. Applications requiring strict format validation should
- * validate hex format before calling cryptographic functions, e.g.:
- *   - Reject strings with 0x prefix if raw hex is expected
- *   - Reject strings with whitespace
- *   - Enforce consistent casing (lowercase/uppercase)
+ * Accepts an optional 0x/0X prefix. Leading/trailing whitespace is rejected.
+ * Empty strings and whitespace-only strings are rejected.
  *
- * @param {string} hex - Hex string (optional 0x prefix, even length).
+ * @param {string} hex - Hex string (optional 0x prefix, even length, no whitespace).
  * @returns {Uint8Array} Decoded bytes.
+ * @throws {Error} If input is not a valid hex string
  * @private
  */
 function hexToBytes(hex) {
@@ -1129,11 +1142,16 @@ function hexToBytes(hex) {
     throw new Error('message must be a hex string');
   }
   /* c8 ignore stop */
-  let clean = hex.trim();
-  // Accepts both "0x..." and raw hex formats for convenience
+  if (hex !== hex.trim()) {
+    throw new Error('hex string must not have leading or trailing whitespace');
+  }
+  let clean = hex;
   if (clean.startsWith('0x') || clean.startsWith('0X')) {
     clean = clean.slice(2);
   }
+  if (clean.length === 0) {
+    throw new Error('hex string must not be empty');
+  }
   if (clean.length % 2 !== 0) {
     throw new Error('hex string must have an even length');
   }
@@ -1143,6 +1161,14 @@ function hexToBytes(hex) {
   return hexToBytes$1(clean);
 }
 
+/**
+ * Convert a message to Uint8Array.
+ *
+ * @param {string|Uint8Array} message - Message as hex string (optional 0x prefix) or Uint8Array.
+ * @returns {Uint8Array} Message bytes.
+ * @throws {Error} If message is not a Uint8Array or valid hex string
+ * @private
+ */
 function messageToBytes(message) {
   if (typeof message === 'string') {
     return hexToBytes(message);
@@ -1156,8 +1182,8 @@ function messageToBytes(message) {
 /**
  * Generate a Dilithium-5 key pair.
  *
- * @param {Uint8Array|null} passedSeed - Optional 32-byte seed for deterministic key generation.
- *   Pass null for random key generation.
+ * @param {Uint8Array|null} [passedSeed=null] - Optional 32-byte seed for deterministic key generation.
+ *   Pass null or undefined for random key generation.
  * @param {Uint8Array} pk - Output buffer for public key (must be CryptoPublicKeyBytes = 2592 bytes)
  * @param {Uint8Array} sk - Output buffer for secret key (must be CryptoSecretKeyBytes = 4896 bytes)
  * @returns {Uint8Array} The seed used for key generation (useful when passedSeed is null)
@@ -1178,9 +1204,9 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
     }
   } catch (e) {
     if (e instanceof TypeError) {
-      throw new Error(`pk/sk cannot be null`);
+      throw new Error(`pk/sk cannot be null`, { cause: e });
     } else {
-      throw new Error(`${e.message}`);
+      throw new Error(`${e.message}`, { cause: e });
     }
   }
 
@@ -1258,15 +1284,25 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
  * @param {boolean} randomizedSigning - If true, use random nonce for hedged signing.
  *   If false, use deterministic nonce derived from message and key.
  * @returns {number} 0 on success
- * @throws {Error} If sk is wrong size
+ * @throws {TypeError} If sig is not a Uint8Array or is smaller than CryptoBytes
+ * @throws {TypeError} If sk is not a Uint8Array
+ * @throws {TypeError} If randomizedSigning is not a boolean
+ * @throws {Error} If sk length does not equal CryptoSecretKeyBytes
+ * @throws {Error} If message is not a Uint8Array or valid hex string
  *
  * @example
  * const sig = new Uint8Array(CryptoBytes);
  * cryptoSignSignature(sig, message, sk, false);
  */
 function cryptoSignSignature(sig, m, sk, randomizedSigning) {
-  if (!sig || sig.length < CryptoBytes) {
-    throw new Error(`sig must be at least ${CryptoBytes} bytes`);
+  if (!(sig instanceof Uint8Array) || sig.length < CryptoBytes) {
+    throw new TypeError(`sig must be at least ${CryptoBytes} bytes and a Uint8Array`);
+  }
+  if (!(sk instanceof Uint8Array)) {
+    throw new TypeError('sk must be a Uint8Array');
+  }
+  if (typeof randomizedSigning !== 'boolean') {
+    throw new TypeError('randomizedSigning must be a boolean');
   }
   if (sk.length !== CryptoSecretKeyBytes) {
     throw new Error(`invalid sk length ${sk.length} | Expected length ${CryptoSecretKeyBytes}`);
@@ -1329,7 +1365,7 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
         .xof(SeedBytes);
       sig.set(cHash);
 
-      polyChallenge(cp, sig);
+      polyChallenge(cp, sig.slice(0, SeedBytes));
       polyNTT(cp);
 
       // Compute z, reject if it reveals secret
@@ -1389,7 +1425,8 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
  * @param {Uint8Array} sk - Secret key (must be CryptoSecretKeyBytes = 4896 bytes)
  * @param {boolean} randomizedSigning - If true, use random nonce; if false, deterministic
  * @returns {Uint8Array} Signed message (CryptoBytes + msg.length bytes)
- * @throws {Error} If signing fails
+ * @throws {TypeError} If sk or randomizedSigning fail type validation (see cryptoSignSignature)
+ * @throws {Error} If signing fails or message/sk are invalid
  *
  * @example
  * const signedMsg = cryptoSign(message, sk, false);
@@ -1443,10 +1480,10 @@ function cryptoSignVerify(sig, m, pk) {
   const w1 = new PolyVecK();
   const h = new PolyVecK();
 
-  if (sig.length !== CryptoBytes) {
+  if (!(sig instanceof Uint8Array) || sig.length !== CryptoBytes) {
     return false;
   }
-  if (pk.length !== CryptoPublicKeyBytes) {
+  if (!(pk instanceof Uint8Array) || pk.length !== CryptoPublicKeyBytes) {
     return false;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theqrl/dilithium5",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Dilithium-5 cryptography",
   "keywords": [
     "dilithium",
@@ -33,7 +33,7 @@
   "scripts": {
     "test": "../../node_modules/mocha/bin/mocha.js --require ../../scripts/node-test-setup.cjs --timeout 10000",
     "test:browser": "playwright test",
-    "build": "rollup src/index.js --file ./dist/cjs/dilithium5.js --format cjs && rollup src/index.js --file ./dist/mjs/dilithium5.js --format esm && ./fixup",
+    "build": "rollup -c && ./fixup",
     "lint-check": "eslint 'src/**/*.js' 'test/**/*.js'",
     "lint": "eslint --fix 'src/**/*.js' 'test/**/*.js'",
     "coverage": "c8 npm run test",
@@ -53,19 +53,39 @@
     "node": ">=20.19.0"
   },
   "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "c8": "^10.1.3",
-    "chai": "^6.2.2",
-    "eslint": "^10.0.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-import-x": "^4.15.0",
-    "eslint-plugin-prettier": "^5.5.4",
-    "globals": "^17.3.0",
-    "mocha": "^11.7.5",
-    "prettier": "^3.8.1",
-    "rollup": "^4.57.1"
+    "@eslint/js": "10.0.1",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "c8": "11.0.0",
+    "chai": "6.2.2",
+    "eslint": "10.0.3",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-import-x": "4.16.2",
+    "eslint-plugin-prettier": "5.5.5",
+    "globals": "17.4.0",
+    "minimatch": "10.2.4",
+    "mocha": "11.7.5",
+    "prettier": "3.8.1",
+    "rollup": "4.59.0",
+    "serialize-javascript": "7.0.4",
+    "tar": "7.5.11"
   },
   "dependencies": {
-    "@noble/hashes": "^2.0.1"
+    "@noble/hashes": "2.0.1"
+  },
+  "overrides": {
+    "diff": "8.0.3",
+    "minimatch": "10.2.4"
+  },
+  "c8": {
+    "include": [
+      "src/**"
+    ],
+    "exclude": [
+      "**/dist/**",
+      "**/test/**",
+      "**/browser-tests/**",
+      "**/*.d.ts"
+    ],
+    "all": true
   }
 }