@theqrl/dilithium5 1.1.1 → 1.1.5

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:
@@ -137,6 +144,7 @@ See [SECURITY.md](../../SECURITY.md) for important information about:
 
 - JavaScript memory security limitations
 - Constant-time verification
+- **Signing timing variability** — signing is not constant-time due to the algorithm's rejection sampling loop; see SECURITY.md for measured impact and deployment mitigations
 - Secure key handling recommendations
 
 ## Requirements

package/dist/cjs/dilithium5.d.cts

@@ -0,0 +1,309 @@
+/**
+ * TypeScript definitions for @theqrl/dilithium5
+ * Dilithium-5 post-quantum digital signature scheme
+ */
+
+// Constants
+export const Shake128Rate: number;
+export const Shake256Rate: number;
+export const Stream128BlockBytes: number;
+export const Stream256BlockBytes: number;
+export const SeedBytes: number;
+export const CRHBytes: number;
+export const TRBytes: number;
+export const N: number;
+export const Q: number;
+export const QInv: number;
+export const D: number;
+export const K: number;
+export const L: number;
+export const ETA: number;
+export const TAU: number;
+export const BETA: number;
+export const GAMMA1: number;
+export const GAMMA2: number;
+export const OMEGA: number;
+export const PolyT1PackedBytes: number;
+export const PolyT0PackedBytes: number;
+export const PolyETAPackedBytes: number;
+export const PolyZPackedBytes: number;
+export const PolyVecHPackedBytes: number;
+export const PolyW1PackedBytes: number;
+export const CryptoPublicKeyBytes: number;
+export const CryptoSecretKeyBytes: number;
+export const CryptoBytes: number;
+export const PolyUniformNBlocks: number;
+export const PolyUniformETANBlocks: number;
+export const PolyUniformGamma1NBlocks: number;
+export const zetas: readonly number[];
+
+// Core signing functions
+
+/**
+ * Generate a Dilithium-5 key pair
+ * @param seed - Optional 32-byte seed for deterministic key generation (null for random)
+ * @param pk - Output buffer for public key (must be CryptoPublicKeyBytes length)
+ * @param sk - Output buffer for secret key (must be CryptoSecretKeyBytes length)
+ * @returns The seed used for key generation
+ * @throws Error if pk/sk buffers are wrong size or null
+ */
+export function cryptoSignKeypair(
+  seed: Uint8Array | null,
+  pk: Uint8Array,
+  sk: Uint8Array
+): Uint8Array;
+
+/**
+ * Create a signature for a message
+ * @param sig - Output buffer for signature (must be CryptoBytes length minimum)
+ * @param m - Message to sign (hex string or Uint8Array; strings are parsed as hex only)
+ * @param sk - Secret key
+ * @param randomizedSigning - If true, use random nonce; if false, deterministic
+ * @returns 0 on success
+ * @throws Error if sk is wrong size
+ */
+export function cryptoSignSignature(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  sk: Uint8Array,
+  randomizedSigning: boolean
+): number;
+
+/**
+ * Sign a message, returning signature concatenated with message
+ * @param msg - Message to sign
+ * @param sk - Secret key
+ * @param randomizedSigning - If true, use random nonce; if false, deterministic
+ * @returns Signed message (signature || message)
+ * @throws Error if signing fails
+ */
+export function cryptoSign(
+  msg: Uint8Array | string,
+  sk: Uint8Array,
+  randomizedSigning: boolean
+): Uint8Array;
+
+/**
+ * Verify a signature
+ * @param sig - Signature to verify
+ * @param m - Message that was signed (hex string or Uint8Array; strings are parsed as hex only)
+ * @param pk - Public key
+ * @returns true if signature is valid, false otherwise
+ */
+export function cryptoSignVerify(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  pk: Uint8Array
+): boolean;
+
+/**
+ * Open a signed message (verify and extract message)
+ * @param sm - Signed message (signature || message)
+ * @param pk - Public key
+ * @returns Message if valid, undefined if verification fails
+ */
+export function cryptoSignOpen(
+  sm: Uint8Array,
+  pk: Uint8Array
+): Uint8Array | undefined;
+
+// Utility functions
+
+/**
+ * Zero out a buffer (best-effort, see SECURITY.md for limitations)
+ * @param buffer - Buffer to zero
+ * @throws TypeError if buffer is not Uint8Array
+ */
+export function zeroize(buffer: Uint8Array): void;
+
+/**
+ * Check if buffer is all zeros using constant-time comparison
+ * @param buffer - Buffer to check
+ * @returns true if all bytes are zero
+ * @throws TypeError if buffer is not Uint8Array
+ */
+export function isZero(buffer: Uint8Array): boolean;
+
+// Internal classes (exported but primarily for internal use)
+
+export class Poly {
+  coeffs: Int32Array;
+  constructor();
+  copy(poly: Poly): void;
+}
+
+export class PolyVecK {
+  vec: Poly[];
+  constructor();
+}
+
+export class PolyVecL {
+  vec: Poly[];
+  constructor();
+  copy(polyVecL: PolyVecL): void;
+}
+
+export class KeccakState {
+  constructor();
+}
+
+// Internal functions (exported but primarily for internal use)
+export function polyNTT(a: Poly): void;
+export function polyInvNTTToMont(a: Poly): void;
+export function polyChallenge(c: Poly, seed: Uint8Array): void;
+export function ntt(a: Int32Array): void;
+export function invNTTToMont(a: Int32Array): void;
+export function montgomeryReduce(a: bigint): bigint;
+export function reduce32(a: number): number;
+export function cAddQ(a: number): number;
+export function decompose(a0: Int32Array, i: number, a: number): number;
+export function power2round(a0: Int32Array, i: number, a: number): number;
+export function makeHint(a0: number, a1: number): number;
+export function useHint(a: number, hint: number): number;
+export function packPk(pk: Uint8Array, rho: Uint8Array, t1: PolyVecK): void;
+export function packSk(
+  sk: Uint8Array,
+  rho: Uint8Array,
+  tr: Uint8Array,
+  key: Uint8Array,
+  t0: PolyVecK,
+  s1: PolyVecL,
+  s2: PolyVecK
+): void;
+export function packSig(
+  sig: Uint8Array,
+  c: Uint8Array,
+  z: PolyVecL,
+  h: PolyVecK
+): void;
+export function unpackPk(rho: Uint8Array, t1: PolyVecK, pk: Uint8Array): void;
+export function unpackSk(
+  rho: Uint8Array,
+  tr: Uint8Array,
+  key: Uint8Array,
+  t0: PolyVecK,
+  s1: PolyVecL,
+  s2: PolyVecK,
+  sk: Uint8Array
+): void;
+export function unpackSig(
+  c: Uint8Array,
+  z: PolyVecL,
+  h: PolyVecK,
+  sig: Uint8Array
+): number;
+
+// FIPS 202 SHAKE primitives (low-level XOF interface, primarily internal)
+export function shake128Init(state: KeccakState): void;
+export function shake128Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake128Finalize(state: KeccakState): void;
+export function shake128SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+export function shake256Init(state: KeccakState): void;
+export function shake256Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake256Finalize(state: KeccakState): void;
+export function shake256SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+
+// Dilithium-specific stream initializers
+export function dilithiumShake128StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+export function dilithiumShake256StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+
+// Polynomial operations (internal)
+export function polyReduce(a: Poly): void;
+export function polyCAddQ(a: Poly): void;
+export function polyAdd(c: Poly, a: Poly, b: Poly): void;
+export function polySub(c: Poly, a: Poly, b: Poly): void;
+export function polyShiftL(a: Poly): void;
+export function polyPointWiseMontgomery(c: Poly, a: Poly, b: Poly): void;
+export function polyPower2round(a1: Poly, a0: Poly, a: Poly): void;
+export function polyDecompose(a1: Poly, a0: Poly, a: Poly): void;
+export function polyMakeHint(h: Poly, a0: Poly, a1: Poly): number;
+export function polyUseHint(b: Poly, a: Poly, h: Poly): void;
+export function polyChkNorm(a: Poly, b: number): number;
+export function rejUniform(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniform(a: Poly, seed: Uint8Array, nonce: number): void;
+export function rejEta(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniformEta(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyZUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyUniformGamma1(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyEtaPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyEtaUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT1Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT0Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT0Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyZPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyW1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+
+// Polynomial vector operations (internal)
+export function polyVecMatrixExpand(mat: PolyVecL[], rho: Uint8Array): void;
+export function polyVecMatrixPointWiseMontgomery(
+  t: PolyVecK,
+  mat: PolyVecL[],
+  v: PolyVecL
+): void;
+export function polyVecLUniformEta(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLUniformGamma1(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLReduce(v: PolyVecL): void;
+export function polyVecLAdd(w: PolyVecL, u: PolyVecL, v: PolyVecL): void;
+export function polyVecLNTT(v: PolyVecL): void;
+export function polyVecLInvNTTToMont(v: PolyVecL): void;
+export function polyVecLPointWisePolyMontgomery(
+  r: PolyVecL,
+  a: Poly,
+  v: PolyVecL
+): void;
+export function polyVecLPointWiseAccMontgomery(
+  w: Poly,
+  u: PolyVecL,
+  v: PolyVecL
+): void;
+export function polyVecLChkNorm(v: PolyVecL, bound: number): number;
+export function polyVecKUniformEta(v: PolyVecK, seed: Uint8Array, nonce: number): void;
+export function polyVecKReduce(v: PolyVecK): void;
+export function polyVecKCAddQ(v: PolyVecK): void;
+export function polyVecKAdd(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKSub(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKShiftL(v: PolyVecK): void;
+export function polyVecKNTT(v: PolyVecK): void;
+export function polyVecKInvNTTToMont(v: PolyVecK): void;
+export function polyVecKPointWisePolyMontgomery(
+  r: PolyVecK,
+  a: Poly,
+  v: PolyVecK
+): void;
+export function polyVecKChkNorm(v: PolyVecK, bound: number): number;
+export function polyVecKPower2round(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKDecompose(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKMakeHint(h: PolyVecK, v0: PolyVecK, v1: PolyVecK): number;
+export function polyVecKUseHint(w: PolyVecK, u: PolyVecK, h: PolyVecK): void;
+export function polyVecKPackW1(r: Uint8Array, w1: PolyVecK): void;

package/dist/cjs/dilithium5.js

@@ -537,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;
@@ -551,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) {
@@ -567,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) {
@@ -704,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;
     }
   }
@@ -826,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;
@@ -833,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);
 
@@ -1246,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];
@@ -1290,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;
@@ -1345,6 +1354,12 @@ function packSig(sigP, c, z, h) {
   for (let i = 0; i < K; ++i) {
     for (let j = 0; j < N; ++j) {
       if (h.vec[i].coeffs[j] !== 0) {
+        if (h.vec[i].coeffs[j] !== 1) {
+          throw new Error('hint coefficients must be binary (0 or 1)');
+        }
+        if (k >= OMEGA) {
+          throw new Error(`hint count exceeds OMEGA (${OMEGA})`);
+        }
         sig[sigOffset + k++] = j;
       }
     }
@@ -1353,7 +1368,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;
@@ -1453,6 +1473,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)) {
@@ -1475,6 +1497,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)) {
@@ -1490,16 +1513,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) {
@@ -1508,11 +1527,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');
   }
@@ -1522,6 +1546,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);
@@ -1535,8 +1567,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)
@@ -1557,9 +1589,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 });
     }
   }
 
@@ -1637,15 +1669,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}`);
@@ -1708,7 +1750,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
@@ -1768,7 +1810,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);
@@ -1822,10 +1865,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/dist/mjs/dilithium5.d.mts

@@ -0,0 +1,309 @@
+/**
+ * TypeScript definitions for @theqrl/dilithium5
+ * Dilithium-5 post-quantum digital signature scheme
+ */
+
+// Constants
+export const Shake128Rate: number;
+export const Shake256Rate: number;
+export const Stream128BlockBytes: number;
+export const Stream256BlockBytes: number;
+export const SeedBytes: number;
+export const CRHBytes: number;
+export const TRBytes: number;
+export const N: number;
+export const Q: number;
+export const QInv: number;
+export const D: number;
+export const K: number;
+export const L: number;
+export const ETA: number;
+export const TAU: number;
+export const BETA: number;
+export const GAMMA1: number;
+export const GAMMA2: number;
+export const OMEGA: number;
+export const PolyT1PackedBytes: number;
+export const PolyT0PackedBytes: number;
+export const PolyETAPackedBytes: number;
+export const PolyZPackedBytes: number;
+export const PolyVecHPackedBytes: number;
+export const PolyW1PackedBytes: number;
+export const CryptoPublicKeyBytes: number;
+export const CryptoSecretKeyBytes: number;
+export const CryptoBytes: number;
+export const PolyUniformNBlocks: number;
+export const PolyUniformETANBlocks: number;
+export const PolyUniformGamma1NBlocks: number;
+export const zetas: readonly number[];
+
+// Core signing functions
+
+/**
+ * Generate a Dilithium-5 key pair
+ * @param seed - Optional 32-byte seed for deterministic key generation (null for random)
+ * @param pk - Output buffer for public key (must be CryptoPublicKeyBytes length)
+ * @param sk - Output buffer for secret key (must be CryptoSecretKeyBytes length)
+ * @returns The seed used for key generation
+ * @throws Error if pk/sk buffers are wrong size or null
+ */
+export function cryptoSignKeypair(
+  seed: Uint8Array | null,
+  pk: Uint8Array,
+  sk: Uint8Array
+): Uint8Array;
+
+/**
+ * Create a signature for a message
+ * @param sig - Output buffer for signature (must be CryptoBytes length minimum)
+ * @param m - Message to sign (hex string or Uint8Array; strings are parsed as hex only)
+ * @param sk - Secret key
+ * @param randomizedSigning - If true, use random nonce; if false, deterministic
+ * @returns 0 on success
+ * @throws Error if sk is wrong size
+ */
+export function cryptoSignSignature(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  sk: Uint8Array,
+  randomizedSigning: boolean
+): number;
+
+/**
+ * Sign a message, returning signature concatenated with message
+ * @param msg - Message to sign
+ * @param sk - Secret key
+ * @param randomizedSigning - If true, use random nonce; if false, deterministic
+ * @returns Signed message (signature || message)
+ * @throws Error if signing fails
+ */
+export function cryptoSign(
+  msg: Uint8Array | string,
+  sk: Uint8Array,
+  randomizedSigning: boolean
+): Uint8Array;
+
+/**
+ * Verify a signature
+ * @param sig - Signature to verify
+ * @param m - Message that was signed (hex string or Uint8Array; strings are parsed as hex only)
+ * @param pk - Public key
+ * @returns true if signature is valid, false otherwise
+ */
+export function cryptoSignVerify(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  pk: Uint8Array
+): boolean;
+
+/**
+ * Open a signed message (verify and extract message)
+ * @param sm - Signed message (signature || message)
+ * @param pk - Public key
+ * @returns Message if valid, undefined if verification fails
+ */
+export function cryptoSignOpen(
+  sm: Uint8Array,
+  pk: Uint8Array
+): Uint8Array | undefined;
+
+// Utility functions
+
+/**
+ * Zero out a buffer (best-effort, see SECURITY.md for limitations)
+ * @param buffer - Buffer to zero
+ * @throws TypeError if buffer is not Uint8Array
+ */
+export function zeroize(buffer: Uint8Array): void;
+
+/**
+ * Check if buffer is all zeros using constant-time comparison
+ * @param buffer - Buffer to check
+ * @returns true if all bytes are zero
+ * @throws TypeError if buffer is not Uint8Array
+ */
+export function isZero(buffer: Uint8Array): boolean;
+
+// Internal classes (exported but primarily for internal use)
+
+export class Poly {
+  coeffs: Int32Array;
+  constructor();
+  copy(poly: Poly): void;
+}
+
+export class PolyVecK {
+  vec: Poly[];
+  constructor();
+}
+
+export class PolyVecL {
+  vec: Poly[];
+  constructor();
+  copy(polyVecL: PolyVecL): void;
+}
+
+export class KeccakState {
+  constructor();
+}
+
+// Internal functions (exported but primarily for internal use)
+export function polyNTT(a: Poly): void;
+export function polyInvNTTToMont(a: Poly): void;
+export function polyChallenge(c: Poly, seed: Uint8Array): void;
+export function ntt(a: Int32Array): void;
+export function invNTTToMont(a: Int32Array): void;
+export function montgomeryReduce(a: bigint): bigint;
+export function reduce32(a: number): number;
+export function cAddQ(a: number): number;
+export function decompose(a0: Int32Array, i: number, a: number): number;
+export function power2round(a0: Int32Array, i: number, a: number): number;
+export function makeHint(a0: number, a1: number): number;
+export function useHint(a: number, hint: number): number;
+export function packPk(pk: Uint8Array, rho: Uint8Array, t1: PolyVecK): void;
+export function packSk(
+  sk: Uint8Array,
+  rho: Uint8Array,
+  tr: Uint8Array,
+  key: Uint8Array,
+  t0: PolyVecK,
+  s1: PolyVecL,
+  s2: PolyVecK
+): void;
+export function packSig(
+  sig: Uint8Array,
+  c: Uint8Array,
+  z: PolyVecL,
+  h: PolyVecK
+): void;
+export function unpackPk(rho: Uint8Array, t1: PolyVecK, pk: Uint8Array): void;
+export function unpackSk(
+  rho: Uint8Array,
+  tr: Uint8Array,
+  key: Uint8Array,
+  t0: PolyVecK,
+  s1: PolyVecL,
+  s2: PolyVecK,
+  sk: Uint8Array
+): void;
+export function unpackSig(
+  c: Uint8Array,
+  z: PolyVecL,
+  h: PolyVecK,
+  sig: Uint8Array
+): number;
+
+// FIPS 202 SHAKE primitives (low-level XOF interface, primarily internal)
+export function shake128Init(state: KeccakState): void;
+export function shake128Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake128Finalize(state: KeccakState): void;
+export function shake128SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+export function shake256Init(state: KeccakState): void;
+export function shake256Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake256Finalize(state: KeccakState): void;
+export function shake256SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+
+// Dilithium-specific stream initializers
+export function dilithiumShake128StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+export function dilithiumShake256StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+
+// Polynomial operations (internal)
+export function polyReduce(a: Poly): void;
+export function polyCAddQ(a: Poly): void;
+export function polyAdd(c: Poly, a: Poly, b: Poly): void;
+export function polySub(c: Poly, a: Poly, b: Poly): void;
+export function polyShiftL(a: Poly): void;
+export function polyPointWiseMontgomery(c: Poly, a: Poly, b: Poly): void;
+export function polyPower2round(a1: Poly, a0: Poly, a: Poly): void;
+export function polyDecompose(a1: Poly, a0: Poly, a: Poly): void;
+export function polyMakeHint(h: Poly, a0: Poly, a1: Poly): number;
+export function polyUseHint(b: Poly, a: Poly, h: Poly): void;
+export function polyChkNorm(a: Poly, b: number): number;
+export function rejUniform(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniform(a: Poly, seed: Uint8Array, nonce: number): void;
+export function rejEta(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniformEta(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyZUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyUniformGamma1(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyEtaPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyEtaUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT1Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT0Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT0Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyZPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyW1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+
+// Polynomial vector operations (internal)
+export function polyVecMatrixExpand(mat: PolyVecL[], rho: Uint8Array): void;
+export function polyVecMatrixPointWiseMontgomery(
+  t: PolyVecK,
+  mat: PolyVecL[],
+  v: PolyVecL
+): void;
+export function polyVecLUniformEta(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLUniformGamma1(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLReduce(v: PolyVecL): void;
+export function polyVecLAdd(w: PolyVecL, u: PolyVecL, v: PolyVecL): void;
+export function polyVecLNTT(v: PolyVecL): void;
+export function polyVecLInvNTTToMont(v: PolyVecL): void;
+export function polyVecLPointWisePolyMontgomery(
+  r: PolyVecL,
+  a: Poly,
+  v: PolyVecL
+): void;
+export function polyVecLPointWiseAccMontgomery(
+  w: Poly,
+  u: PolyVecL,
+  v: PolyVecL
+): void;
+export function polyVecLChkNorm(v: PolyVecL, bound: number): number;
+export function polyVecKUniformEta(v: PolyVecK, seed: Uint8Array, nonce: number): void;
+export function polyVecKReduce(v: PolyVecK): void;
+export function polyVecKCAddQ(v: PolyVecK): void;
+export function polyVecKAdd(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKSub(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKShiftL(v: PolyVecK): void;
+export function polyVecKNTT(v: PolyVecK): void;
+export function polyVecKInvNTTToMont(v: PolyVecK): void;
+export function polyVecKPointWisePolyMontgomery(
+  r: PolyVecK,
+  a: Poly,
+  v: PolyVecK
+): void;
+export function polyVecKChkNorm(v: PolyVecK, bound: number): number;
+export function polyVecKPower2round(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKDecompose(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKMakeHint(h: PolyVecK, v0: PolyVecK, v1: PolyVecK): number;
+export function polyVecKUseHint(w: PolyVecK, u: PolyVecK, h: PolyVecK): void;
+export function polyVecKPackW1(r: Uint8Array, w1: PolyVecK): void;

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;
@@ -966,6 +975,12 @@ function packSig(sigP, c, z, h) {
   for (let i = 0; i < K; ++i) {
     for (let j = 0; j < N; ++j) {
       if (h.vec[i].coeffs[j] !== 0) {
+        if (h.vec[i].coeffs[j] !== 1) {
+          throw new Error('hint coefficients must be binary (0 or 1)');
+        }
+        if (k >= OMEGA) {
+          throw new Error(`hint count exceeds OMEGA (${OMEGA})`);
+        }
         sig[sigOffset + k++] = j;
       }
     }
@@ -974,7 +989,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 +1094,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 +1118,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 +1134,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 +1148,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 +1167,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 +1188,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 +1210,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 +1290,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 +1371,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 +1431,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 +1486,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.1",
+  "version": "1.1.5",
   "description": "Dilithium-5 cryptography",
   "keywords": [
     "dilithium",
@@ -44,8 +44,14 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/mjs/dilithium5.js",
-      "require": "./dist/cjs/dilithium5.js"
+      "import": {
+        "types": "./dist/mjs/dilithium5.d.mts",
+        "default": "./dist/mjs/dilithium5.js"
+      },
+      "require": {
+        "types": "./dist/cjs/dilithium5.d.cts",
+        "default": "./dist/cjs/dilithium5.js"
+      }
     }
   },
   "type": "module",
@@ -53,20 +59,39 @@
     "node": ">=20.19.0"
   },
   "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "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
   }
 }

package/src/index.d.ts

@@ -192,3 +192,118 @@ export function unpackSig(
   h: PolyVecK,
   sig: Uint8Array
 ): number;
+
+// FIPS 202 SHAKE primitives (low-level XOF interface, primarily internal)
+export function shake128Init(state: KeccakState): void;
+export function shake128Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake128Finalize(state: KeccakState): void;
+export function shake128SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+export function shake256Init(state: KeccakState): void;
+export function shake256Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake256Finalize(state: KeccakState): void;
+export function shake256SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+
+// Dilithium-specific stream initializers
+export function dilithiumShake128StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+export function dilithiumShake256StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+
+// Polynomial operations (internal)
+export function polyReduce(a: Poly): void;
+export function polyCAddQ(a: Poly): void;
+export function polyAdd(c: Poly, a: Poly, b: Poly): void;
+export function polySub(c: Poly, a: Poly, b: Poly): void;
+export function polyShiftL(a: Poly): void;
+export function polyPointWiseMontgomery(c: Poly, a: Poly, b: Poly): void;
+export function polyPower2round(a1: Poly, a0: Poly, a: Poly): void;
+export function polyDecompose(a1: Poly, a0: Poly, a: Poly): void;
+export function polyMakeHint(h: Poly, a0: Poly, a1: Poly): number;
+export function polyUseHint(b: Poly, a: Poly, h: Poly): void;
+export function polyChkNorm(a: Poly, b: number): number;
+export function rejUniform(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniform(a: Poly, seed: Uint8Array, nonce: number): void;
+export function rejEta(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniformEta(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyZUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyUniformGamma1(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyEtaPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyEtaUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT1Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT0Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT0Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyZPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyW1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+
+// Polynomial vector operations (internal)
+export function polyVecMatrixExpand(mat: PolyVecL[], rho: Uint8Array): void;
+export function polyVecMatrixPointWiseMontgomery(
+  t: PolyVecK,
+  mat: PolyVecL[],
+  v: PolyVecL
+): void;
+export function polyVecLUniformEta(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLUniformGamma1(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLReduce(v: PolyVecL): void;
+export function polyVecLAdd(w: PolyVecL, u: PolyVecL, v: PolyVecL): void;
+export function polyVecLNTT(v: PolyVecL): void;
+export function polyVecLInvNTTToMont(v: PolyVecL): void;
+export function polyVecLPointWisePolyMontgomery(
+  r: PolyVecL,
+  a: Poly,
+  v: PolyVecL
+): void;
+export function polyVecLPointWiseAccMontgomery(
+  w: Poly,
+  u: PolyVecL,
+  v: PolyVecL
+): void;
+export function polyVecLChkNorm(v: PolyVecL, bound: number): number;
+export function polyVecKUniformEta(v: PolyVecK, seed: Uint8Array, nonce: number): void;
+export function polyVecKReduce(v: PolyVecK): void;
+export function polyVecKCAddQ(v: PolyVecK): void;
+export function polyVecKAdd(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKSub(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKShiftL(v: PolyVecK): void;
+export function polyVecKNTT(v: PolyVecK): void;
+export function polyVecKInvNTTToMont(v: PolyVecK): void;
+export function polyVecKPointWisePolyMontgomery(
+  r: PolyVecK,
+  a: Poly,
+  v: PolyVecK
+): void;
+export function polyVecKChkNorm(v: PolyVecK, bound: number): number;
+export function polyVecKPower2round(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKDecompose(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKMakeHint(h: PolyVecK, v0: PolyVecK, v1: PolyVecK): number;
+export function polyVecKUseHint(w: PolyVecK, u: PolyVecK, h: PolyVecK): void;
+export function polyVecKPackW1(r: Uint8Array, w1: PolyVecK): void;