@theqrl/mldsa87 1.1.1 → 2.0.1

package/README.md

@@ -26,12 +26,13 @@ const pk = new Uint8Array(CryptoPublicKeyBytes);  // 2592 bytes
 const sk = new Uint8Array(CryptoSecretKeyBytes);  // 4896 bytes
 cryptoSignKeypair(null, pk, sk);  // null = random seed
 
-// Sign a message (uses default "ZOND" context)
+// Sign a message
 const message = new TextEncoder().encode('Hello, quantum world!');
-const signedMessage = cryptoSign(message, sk, false);  // false = deterministic
+const ctx = new Uint8Array([0x5a, 0x4f, 0x4e, 0x44]);  // "ZOND"
+const signedMessage = cryptoSign(message, sk, false, ctx);  // false = deterministic
 
-// Verify and extract
-const extracted = cryptoSignOpen(signedMessage, pk);
+// Verify and extract (context must match)
+const extracted = cryptoSignOpen(signedMessage, pk, ctx);
 if (extracted === undefined) {
   throw new Error('Invalid signature');
 }
@@ -40,20 +41,21 @@ console.log(new TextDecoder().decode(extracted));  // "Hello, quantum world!"
 
 ## Context Parameter
 
-ML-DSA-87 supports a context parameter for domain separation (FIPS 204 feature). This allows the same keypair to be used safely across different applications.
+ML-DSA-87 requires a context parameter for domain separation (FIPS 204 feature). This allows the same keypair to be used safely across different applications.
 
 ```javascript
-// With custom context
+// With application-specific context
 const ctx = new TextEncoder().encode('my-app-v1');
 const signed = cryptoSign(message, sk, false, ctx);
 const extracted = cryptoSignOpen(signed, pk, ctx);
 
 // Context must match for verification
-cryptoSignOpen(signed, pk);  // undefined - wrong context (default "ZOND")
-cryptoSignOpen(signed, pk, ctx);  // message - correct context
+const wrongCtx = new Uint8Array(0);
+cryptoSignOpen(signed, pk, wrongCtx);  // undefined - wrong context
+cryptoSignOpen(signed, pk, ctx);       // message - correct context
 ```
 
-The default context is `"ZOND"` (for QRL Zond network compatibility). Context can be 0-255 bytes.
+Context is a required `Uint8Array` and can be 0-255 bytes. Use an empty `Uint8Array(0)` if no domain separation is needed.
 
 ## API
 
@@ -72,31 +74,31 @@ The default context is `"ZOND"` (for QRL Zond network compatibility). Context ca
 
 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`)
 
-#### `cryptoSign(message, sk, randomized, context?)`
+#### `cryptoSign(message, sk, randomized, context)`
 
 Sign a message (combined mode: returns signature || message).
 
 - `message`: `Uint8Array` or `string` - message bytes; if `string`, it must be hex only (optional `0x`, even length). Plain-text strings are not accepted.
 - `sk`: `Uint8Array(4896)` - secret key
 - `randomized`: `boolean` - `true` for hedged signing, `false` for deterministic
-- `context`: `Uint8Array` (optional) - context string, 0-255 bytes. Default: `"ZOND"`
+- `context`: `Uint8Array` - context string for domain separation, 0-255 bytes
 - Returns: `Uint8Array` containing signature + message
 
-#### `cryptoSignOpen(signedMessage, pk, context?)`
+#### `cryptoSignOpen(signedMessage, pk, context)`
 
 Verify and extract message from signed message.
 
 - `signedMessage`: `Uint8Array` - output from `cryptoSign()`
 - `pk`: `Uint8Array(2592)` - public key
-- `context`: `Uint8Array` (optional) - must match signing context
+- `context`: `Uint8Array` - must match signing context
 - Returns: Original message if valid, `undefined` if verification fails
 
-#### `cryptoSignSignature(sig, message, sk, randomized, context?)`
+#### `cryptoSignSignature(sig, message, sk, randomized, context)`
 
 Create a detached signature.
 
@@ -104,17 +106,17 @@ Create a detached signature.
 - `message`: `Uint8Array` or `string` - message bytes; if `string`, it must be hex only (optional `0x`, even length). Plain-text strings are not accepted.
 - `sk`: `Uint8Array(4896)` - secret key
 - `randomized`: `boolean` - `true` for hedged, `false` for deterministic
-- `context`: `Uint8Array` (optional) - context string, 0-255 bytes
+- `context`: `Uint8Array` - context string for domain separation, 0-255 bytes
 - Returns: `0` on success
 
-#### `cryptoSignVerify(sig, message, pk, context?)`
+#### `cryptoSignVerify(sig, message, pk, context)`
 
 Verify a detached signature.
 
 - `sig`: `Uint8Array(4627)` - signature to verify
 - `message`: `Uint8Array` or `string` - original message bytes; if `string`, it must be hex only (optional `0x`, even length). Plain-text strings are not accepted.
 - `pk`: `Uint8Array(2592)` - public key
-- `context`: `Uint8Array` (optional) - must match signing context
+- `context`: `Uint8Array` - must match signing context
 - Returns: `true` if valid, `false` otherwise
 
 **Note:** To sign or verify plain text, convert it to bytes (e.g., `new TextEncoder().encode('Hello')`). String inputs are interpreted as hex only.
@@ -123,10 +125,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
 
 Both this library and go-qrllib process ML-DSA-87 seeds identically. Raw seeds produce matching keys:

package/dist/cjs/mldsa87.js

@@ -539,12 +539,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;
@@ -553,7 +557,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) {
@@ -569,7 +573,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) {
@@ -706,10 +710,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;
     }
   }
@@ -1250,6 +1251,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];
@@ -1294,6 +1298,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;
@@ -1357,7 +1364,12 @@ function packSig(sigP, ctilde, 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; // ctilde
   const h = hP;
@@ -1452,6 +1464,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)) {
@@ -1474,6 +1488,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)) {
@@ -1486,26 +1501,15 @@ function isZero(buffer) {
   return acc === 0;
 }
 
-/**
- * Default signing context ("ZOND" in ASCII).
- * Used for domain separation per FIPS 204.
- * @constant {Uint8Array}
- */
-const DEFAULT_CTX = new Uint8Array([0x5a, 0x4f, 0x4e, 0x44]); // "ZOND"
-
 /**
  * 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) {
@@ -1514,11 +1518,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');
   }
@@ -1528,6 +1537,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);
@@ -1544,8 +1561,8 @@ function messageToBytes(message) {
  * Key generation follows FIPS 204, using domain separator [K, L] during
  * seed expansion to ensure algorithm binding.
  *
- * @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)
@@ -1566,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 });
     }
   }
 
@@ -1637,7 +1654,7 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
 }
 
 /**
- * Create a detached signature for a message with optional context.
+ * Create a detached signature for a message with context.
  *
  * Uses the ML-DSA-87 (FIPS 204) signing algorithm with rejection sampling.
  * The context parameter provides domain separation as required by FIPS 204.
@@ -1647,22 +1664,36 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
  * @param {Uint8Array} sk - Secret key (must be CryptoSecretKeyBytes = 4896 bytes)
  * @param {boolean} randomizedSigning - If true, use random nonce for hedged signing.
  *   If false, use deterministic nonce derived from message and key.
- * @param {Uint8Array} [ctx=DEFAULT_CTX] - Context string for domain separation (max 255 bytes).
- *   Defaults to "ZOND" for QRL compatibility.
+ * @param {Uint8Array} ctx - Context string for domain separation (required, max 255 bytes).
+ *   Pass an empty Uint8Array for no context.
  * @returns {number} 0 on success
- * @throws {Error} If sk is wrong size or context exceeds 255 bytes
+ * @throws {TypeError} If sig is not a Uint8Array or is smaller than CryptoBytes
+ * @throws {TypeError} If sk is not a Uint8Array
+ * @throws {TypeError} If ctx is not a Uint8Array
+ * @throws {TypeError} If randomizedSigning is not a boolean
+ * @throws {Error} If ctx exceeds 255 bytes
+ * @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);
- * // Or with custom context:
- * cryptoSignSignature(sig, message, sk, false, new Uint8Array([0x01, 0x02]));
+ * const ctx = new Uint8Array([0x01, 0x02]);
+ * cryptoSignSignature(sig, message, sk, false, ctx);
  */
-function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
-  if (!sig || sig.length < CryptoBytes) {
-    throw new Error(`sig must be at least ${CryptoBytes} bytes`);
+function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx) {
+  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 (!(ctx instanceof Uint8Array)) {
+    throw new TypeError('ctx is required and must be a Uint8Array');
   }
   if (ctx.length > 255) throw new Error(`invalid context length: ${ctx.length} (max 255)`);
+  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}`);
   }
@@ -1788,16 +1819,20 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
  * @param {string|Uint8Array} msg - Message to sign (hex string, optional 0x prefix, or Uint8Array)
  * @param {Uint8Array} sk - Secret key (must be CryptoSecretKeyBytes = 4896 bytes)
  * @param {boolean} randomizedSigning - If true, use random nonce; if false, deterministic
- * @param {Uint8Array} [ctx=DEFAULT_CTX] - Context string for domain separation (max 255 bytes).
- *   Defaults to "ZOND" for QRL compatibility.
+ * @param {Uint8Array} ctx - Context string for domain separation (required, max 255 bytes).
  * @returns {Uint8Array} Signed message (CryptoBytes + msg.length bytes)
- * @throws {Error} If signing fails
+ * @throws {TypeError} If ctx is not a Uint8Array
+ * @throws {TypeError} If sk or randomizedSigning fail type validation (see cryptoSignSignature)
+ * @throws {Error} If signing fails or message/sk/ctx are invalid
  *
  * @example
- * const signedMsg = cryptoSign(message, sk, false);
+ * const signedMsg = cryptoSign(message, sk, false, ctx);
  * // signedMsg contains: signature (4627 bytes) || message
  */
-function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
+function cryptoSign(msg, sk, randomizedSigning, ctx) {
+  if (!(ctx instanceof Uint8Array)) {
+    throw new TypeError('ctx is required and must be a Uint8Array');
+  }
   const msgBytes = messageToBytes(msg);
 
   const sm = new Uint8Array(CryptoBytes + msgBytes.length);
@@ -1816,7 +1851,7 @@ function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
 }
 
 /**
- * Verify a detached signature with optional context.
+ * Verify a detached signature with context.
  *
  * Performs constant-time verification to prevent timing side-channel attacks.
  * The context must match the one used during signing.
@@ -1824,17 +1859,20 @@ function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
  * @param {Uint8Array} sig - Signature to verify (must be CryptoBytes = 4627 bytes)
  * @param {string|Uint8Array} m - Message that was signed (hex string, optional 0x prefix, or Uint8Array)
  * @param {Uint8Array} pk - Public key (must be CryptoPublicKeyBytes = 2592 bytes)
- * @param {Uint8Array} [ctx=DEFAULT_CTX] - Context string used during signing (max 255 bytes).
- *   Defaults to "ZOND" for QRL compatibility.
+ * @param {Uint8Array} ctx - Context string used during signing (required, max 255 bytes).
  * @returns {boolean} true if signature is valid, false otherwise
+ * @throws {TypeError} If ctx is not a Uint8Array
  *
  * @example
- * const isValid = cryptoSignVerify(signature, message, pk);
+ * const isValid = cryptoSignVerify(signature, message, pk, ctx);
  * if (!isValid) {
  *   throw new Error('Invalid signature');
  * }
  */
-function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
+function cryptoSignVerify(sig, m, pk, ctx) {
+  if (!(ctx instanceof Uint8Array)) {
+    throw new TypeError('ctx is required and must be a Uint8Array');
+  }
   if (ctx.length > 255) return false;
   let i;
   const buf = new Uint8Array(K * PolyW1PackedBytes);
@@ -1849,10 +1887,10 @@ function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
   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;
   }
 
@@ -1922,17 +1960,20 @@ function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
  *
  * @param {Uint8Array} sm - Signed message (signature || message)
  * @param {Uint8Array} pk - Public key (must be CryptoPublicKeyBytes = 2592 bytes)
- * @param {Uint8Array} [ctx=DEFAULT_CTX] - Context string used during signing (max 255 bytes).
- *   Defaults to "ZOND" for QRL compatibility.
+ * @param {Uint8Array} ctx - Context string used during signing (required, max 255 bytes).
  * @returns {Uint8Array|undefined} The original message if valid, undefined if verification fails
+ * @throws {TypeError} If ctx is not a Uint8Array
  *
  * @example
- * const message = cryptoSignOpen(signedMsg, pk);
+ * const message = cryptoSignOpen(signedMsg, pk, ctx);
  * if (message === undefined) {
  *   throw new Error('Invalid signature');
  * }
  */
-function cryptoSignOpen(sm, pk, ctx = DEFAULT_CTX) {
+function cryptoSignOpen(sm, pk, ctx) {
+  if (!(ctx instanceof Uint8Array)) {
+    throw new TypeError('ctx is required and must be a Uint8Array');
+  }
   if (sm.length < CryptoBytes) {
     return undefined;
   }

package/dist/mjs/mldsa87.js

@@ -160,12 +160,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 +178,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 +194,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 +331,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;
     }
   }
@@ -871,6 +872,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];
@@ -915,6 +919,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;
@@ -978,7 +985,12 @@ function packSig(sigP, ctilde, 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; // ctilde
   const h = hP;
@@ -1073,6 +1085,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)) {
@@ -1095,6 +1109,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)) {
@@ -1107,26 +1122,15 @@ function isZero(buffer) {
   return acc === 0;
 }
 
-/**
- * Default signing context ("ZOND" in ASCII).
- * Used for domain separation per FIPS 204.
- * @constant {Uint8Array}
- */
-const DEFAULT_CTX = new Uint8Array([0x5a, 0x4f, 0x4e, 0x44]); // "ZOND"
-
 /**
  * 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) {
@@ -1135,11 +1139,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');
   }
@@ -1149,6 +1158,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);
@@ -1165,8 +1182,8 @@ function messageToBytes(message) {
  * Key generation follows FIPS 204, using domain separator [K, L] during
  * seed expansion to ensure algorithm binding.
  *
- * @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)
@@ -1187,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,7 +1275,7 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
 }
 
 /**
- * Create a detached signature for a message with optional context.
+ * Create a detached signature for a message with context.
  *
  * Uses the ML-DSA-87 (FIPS 204) signing algorithm with rejection sampling.
  * The context parameter provides domain separation as required by FIPS 204.
@@ -1268,22 +1285,36 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
  * @param {Uint8Array} sk - Secret key (must be CryptoSecretKeyBytes = 4896 bytes)
  * @param {boolean} randomizedSigning - If true, use random nonce for hedged signing.
  *   If false, use deterministic nonce derived from message and key.
- * @param {Uint8Array} [ctx=DEFAULT_CTX] - Context string for domain separation (max 255 bytes).
- *   Defaults to "ZOND" for QRL compatibility.
+ * @param {Uint8Array} ctx - Context string for domain separation (required, max 255 bytes).
+ *   Pass an empty Uint8Array for no context.
  * @returns {number} 0 on success
- * @throws {Error} If sk is wrong size or context exceeds 255 bytes
+ * @throws {TypeError} If sig is not a Uint8Array or is smaller than CryptoBytes
+ * @throws {TypeError} If sk is not a Uint8Array
+ * @throws {TypeError} If ctx is not a Uint8Array
+ * @throws {TypeError} If randomizedSigning is not a boolean
+ * @throws {Error} If ctx exceeds 255 bytes
+ * @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);
- * // Or with custom context:
- * cryptoSignSignature(sig, message, sk, false, new Uint8Array([0x01, 0x02]));
+ * const ctx = new Uint8Array([0x01, 0x02]);
+ * cryptoSignSignature(sig, message, sk, false, ctx);
  */
-function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
-  if (!sig || sig.length < CryptoBytes) {
-    throw new Error(`sig must be at least ${CryptoBytes} bytes`);
+function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx) {
+  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 (!(ctx instanceof Uint8Array)) {
+    throw new TypeError('ctx is required and must be a Uint8Array');
   }
   if (ctx.length > 255) throw new Error(`invalid context length: ${ctx.length} (max 255)`);
+  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}`);
   }
@@ -1409,16 +1440,20 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
  * @param {string|Uint8Array} msg - Message to sign (hex string, optional 0x prefix, or Uint8Array)
  * @param {Uint8Array} sk - Secret key (must be CryptoSecretKeyBytes = 4896 bytes)
  * @param {boolean} randomizedSigning - If true, use random nonce; if false, deterministic
- * @param {Uint8Array} [ctx=DEFAULT_CTX] - Context string for domain separation (max 255 bytes).
- *   Defaults to "ZOND" for QRL compatibility.
+ * @param {Uint8Array} ctx - Context string for domain separation (required, max 255 bytes).
  * @returns {Uint8Array} Signed message (CryptoBytes + msg.length bytes)
- * @throws {Error} If signing fails
+ * @throws {TypeError} If ctx is not a Uint8Array
+ * @throws {TypeError} If sk or randomizedSigning fail type validation (see cryptoSignSignature)
+ * @throws {Error} If signing fails or message/sk/ctx are invalid
  *
  * @example
- * const signedMsg = cryptoSign(message, sk, false);
+ * const signedMsg = cryptoSign(message, sk, false, ctx);
  * // signedMsg contains: signature (4627 bytes) || message
  */
-function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
+function cryptoSign(msg, sk, randomizedSigning, ctx) {
+  if (!(ctx instanceof Uint8Array)) {
+    throw new TypeError('ctx is required and must be a Uint8Array');
+  }
   const msgBytes = messageToBytes(msg);
 
   const sm = new Uint8Array(CryptoBytes + msgBytes.length);
@@ -1437,7 +1472,7 @@ function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
 }
 
 /**
- * Verify a detached signature with optional context.
+ * Verify a detached signature with context.
  *
  * Performs constant-time verification to prevent timing side-channel attacks.
  * The context must match the one used during signing.
@@ -1445,17 +1480,20 @@ function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
  * @param {Uint8Array} sig - Signature to verify (must be CryptoBytes = 4627 bytes)
  * @param {string|Uint8Array} m - Message that was signed (hex string, optional 0x prefix, or Uint8Array)
  * @param {Uint8Array} pk - Public key (must be CryptoPublicKeyBytes = 2592 bytes)
- * @param {Uint8Array} [ctx=DEFAULT_CTX] - Context string used during signing (max 255 bytes).
- *   Defaults to "ZOND" for QRL compatibility.
+ * @param {Uint8Array} ctx - Context string used during signing (required, max 255 bytes).
  * @returns {boolean} true if signature is valid, false otherwise
+ * @throws {TypeError} If ctx is not a Uint8Array
  *
  * @example
- * const isValid = cryptoSignVerify(signature, message, pk);
+ * const isValid = cryptoSignVerify(signature, message, pk, ctx);
  * if (!isValid) {
  *   throw new Error('Invalid signature');
  * }
  */
-function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
+function cryptoSignVerify(sig, m, pk, ctx) {
+  if (!(ctx instanceof Uint8Array)) {
+    throw new TypeError('ctx is required and must be a Uint8Array');
+  }
   if (ctx.length > 255) return false;
   let i;
   const buf = new Uint8Array(K * PolyW1PackedBytes);
@@ -1470,10 +1508,10 @@ function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
   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;
   }
 
@@ -1543,17 +1581,20 @@ function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
  *
  * @param {Uint8Array} sm - Signed message (signature || message)
  * @param {Uint8Array} pk - Public key (must be CryptoPublicKeyBytes = 2592 bytes)
- * @param {Uint8Array} [ctx=DEFAULT_CTX] - Context string used during signing (max 255 bytes).
- *   Defaults to "ZOND" for QRL compatibility.
+ * @param {Uint8Array} ctx - Context string used during signing (required, max 255 bytes).
  * @returns {Uint8Array|undefined} The original message if valid, undefined if verification fails
+ * @throws {TypeError} If ctx is not a Uint8Array
  *
  * @example
- * const message = cryptoSignOpen(signedMsg, pk);
+ * const message = cryptoSignOpen(signedMsg, pk, ctx);
  * if (message === undefined) {
  *   throw new Error('Invalid signature');
  * }
  */
-function cryptoSignOpen(sm, pk, ctx = DEFAULT_CTX) {
+function cryptoSignOpen(sm, pk, ctx) {
+  if (!(ctx instanceof Uint8Array)) {
+    throw new TypeError('ctx is required and must be a Uint8Array');
+  }
   if (sm.length < CryptoBytes) {
     return undefined;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theqrl/mldsa87",
-  "version": "1.1.1",
+  "version": "2.0.1",
   "description": "ML-DSA-87 cryptography",
   "keywords": [
     "ml-dsa",
@@ -53,20 +53,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

@@ -56,12 +56,12 @@ export function cryptoSignKeypair(
 ): Uint8Array;
 
 /**
- * Create a signature for a message with optional context
+ * 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
- * @param ctx - Optional context string (max 255 bytes, defaults to "ZOND")
+ * @param ctx - Context string (max 255 bytes)
  * @returns 0 on success
  * @throws Error if sk is wrong size or context too long
  */
@@ -70,7 +70,7 @@ export function cryptoSignSignature(
   m: Uint8Array | string,
   sk: Uint8Array,
   randomizedSigning: boolean,
-  ctx?: Uint8Array
+  ctx: Uint8Array
 ): number;
 
 /**
@@ -78,7 +78,7 @@ export function cryptoSignSignature(
  * @param msg - Message to sign
  * @param sk - Secret key
  * @param randomizedSigning - If true, use random nonce; if false, deterministic
- * @param ctx - Optional context string (max 255 bytes, defaults to "ZOND")
+ * @param ctx - Context string (max 255 bytes)
  * @returns Signed message (signature || message)
  * @throws Error if signing fails
  */
@@ -86,35 +86,35 @@ export function cryptoSign(
   msg: Uint8Array | string,
   sk: Uint8Array,
   randomizedSigning: boolean,
-  ctx?: Uint8Array
+  ctx: Uint8Array
 ): Uint8Array;
 
 /**
- * Verify a signature with optional context
+ * 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
- * @param ctx - Optional context string (max 255 bytes, defaults to "ZOND")
+ * @param ctx - Context string (max 255 bytes)
  * @returns true if signature is valid, false otherwise
  */
 export function cryptoSignVerify(
   sig: Uint8Array,
   m: Uint8Array | string,
   pk: Uint8Array,
-  ctx?: Uint8Array
+  ctx: Uint8Array
 ): boolean;
 
 /**
  * Open a signed message (verify and extract message)
  * @param sm - Signed message (signature || message)
  * @param pk - Public key
- * @param ctx - Optional context string (max 255 bytes, defaults to "ZOND")
+ * @param ctx - Context string (max 255 bytes)
  * @returns Message if valid, undefined if verification fails
  */
 export function cryptoSignOpen(
   sm: Uint8Array,
   pk: Uint8Array,
-  ctx?: Uint8Array
+  ctx: Uint8Array
 ): Uint8Array | undefined;
 
 // Utility functions