@theqrl/mldsa87 1.0.5 → 1.0.7

package/LICENSE

@@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+

package/README.md

@@ -81,7 +81,7 @@ Generate a keypair from a seed.
 
 Sign a message (combined mode: returns signature || message).
 
-- `message`: `Uint8Array` - message to sign
+- `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"`
@@ -101,7 +101,7 @@ Verify and extract message from signed message.
 Create a detached signature.
 
 - `sig`: `Uint8Array(4627)` - output buffer for signature
-- `message`: `Uint8Array` - message to sign
+- `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
@@ -112,11 +112,13 @@ Create a detached signature.
 Verify a detached signature.
 
 - `sig`: `Uint8Array(4627)` - signature to verify
-- `message`: `Uint8Array` - original message
+- `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
 - 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.
+
 #### `zeroize(buffer)`
 
 Zero out sensitive data (best-effort, see security notes).
@@ -157,7 +159,7 @@ See [SECURITY.md](../../SECURITY.md) for important information about:
 
 ## Requirements
 
-- Node.js 18+ or modern browsers with ES2020 support
+- Node.js 18.20+ or modern browsers with ES2020 support
 - Full TypeScript definitions included
 
 ## License

package/dist/cjs/mldsa87.js

@@ -1,9 +1,9 @@
 'use strict';
 
 var sha3_js = require('@noble/hashes/sha3.js');
-var pkg = require('randombytes');
 var utils_js = require('@noble/hashes/utils.js');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 const Shake128Rate = 168;
 const Shake256Rate = 136;
 const Stream128BlockBytes = Shake128Rate;
@@ -370,6 +370,8 @@ function polyUniform(a, seed, nonce) {
 
   let ctr = rejUniform(a.coeffs, 0, N, buf, bufLen);
 
+  // Note: With current parameters, needing extra blocks is vanishingly unlikely.
+  /* c8 ignore start */
   while (ctr < N) {
     off = bufLen % 3;
     for (let i = 0; i < off; ++i) buf[i] = buf[bufLen - off + i];
@@ -378,6 +380,7 @@ function polyUniform(a, seed, nonce) {
     bufLen = Stream128BlockBytes + off;
     ctr += rejUniform(a.coeffs, ctr, N - ctr, buf, bufLen);
   }
+  /* c8 ignore stop */
 }
 
 function rejEta(aP, aOffset, len, buf, bufLen) {
@@ -473,10 +476,13 @@ function polyChallenge(cP, seed) {
   }
   for (let i = N - TAU; i < N; ++i) {
     do {
+      // Note: Re-squeezing here is extremely unlikely with TAU=60.
+      /* c8 ignore start */
       if (pos >= Shake256Rate) {
         shake256SqueezeBlocks(buf, 0, 1, state);
         pos = 0;
       }
+      /* c8 ignore stop */
 
       b = buf[pos++];
     } while (b > i);
@@ -1021,7 +1027,69 @@ function unpackSig(cP, z, hP, sig) {
   return 0;
 }
 
-const randomBytes = pkg;
+const MAX_BYTES = 65536;
+
+function getGlobalScope() {
+  if (typeof globalThis === 'object') return globalThis;
+  if (typeof self === 'object') return self;
+  if (typeof window === 'object') return window;
+  if (typeof global === 'object') return global;
+  return {};
+}
+
+function getWebCrypto() {
+  const scope = getGlobalScope();
+  return scope.crypto || scope.msCrypto || null;
+}
+
+function getNodeRandomBytes() {
+  /* c8 ignore next */
+  const isNode = typeof process === 'object' && process !== null && process.versions && process.versions.node;
+  if (!isNode) return null;
+
+  const req =
+    typeof module !== 'undefined' && module && typeof module.require === 'function'
+      ? module.require.bind(module)
+      : typeof module !== 'undefined' && module && typeof module.createRequire === 'function'
+        ? module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('mldsa87.js', document.baseURI).href)))
+        : typeof require === 'function'
+          ? require
+          : null;
+  if (!req) return null;
+
+  try {
+    const nodeCrypto = req('crypto');
+    if (nodeCrypto && typeof nodeCrypto.randomBytes === 'function') {
+      return nodeCrypto.randomBytes;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+function randomBytes(size) {
+  if (!Number.isSafeInteger(size) || size < 0) {
+    throw new RangeError('size must be a non-negative integer');
+  }
+
+  const cryptoObj = getWebCrypto();
+  if (cryptoObj && typeof cryptoObj.getRandomValues === 'function') {
+    const out = new Uint8Array(size);
+    for (let i = 0; i < size; i += MAX_BYTES) {
+      cryptoObj.getRandomValues(out.subarray(i, Math.min(size, i + MAX_BYTES)));
+    }
+    return out;
+  }
+
+  const nodeRandomBytes = getNodeRandomBytes();
+  if (nodeRandomBytes) {
+    return nodeRandomBytes(size);
+  }
+
+  throw new Error('Secure random number generation is not supported by this environment');
+}
 
 /**
  * Default signing context ("ZOND" in ASCII).
@@ -1032,15 +1100,27 @@ 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)
+ *
  * @param {string} hex - Hex string (optional 0x prefix, even length).
  * @returns {Uint8Array} Decoded bytes.
  * @private
  */
 function hexToBytes(hex) {
+  /* c8 ignore start */
   if (typeof hex !== 'string') {
     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 (clean.startsWith('0x') || clean.startsWith('0X')) {
     clean = clean.slice(2);
   }
@@ -1060,7 +1140,7 @@ function messageToBytes(message) {
   if (message instanceof Uint8Array) {
     return message;
   }
-  return null;
+  throw new Error('message must be Uint8Array or hex string');
 }
 
 /**
@@ -1208,9 +1288,6 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
   pre.set(ctx, 2);
 
   const mBytes = messageToBytes(m);
-  if (!mBytes) {
-    throw new Error('message must be Uint8Array or hex string');
-  }
 
   // mu = SHAKE256(tr || pre || m)
   const mu = sha3_js.shake256.create({}).update(tr).update(pre).update(mBytes).xof(CRHBytes);
@@ -1268,15 +1345,19 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
     polyVecKPointWisePolyMontgomery(h, cp, t0);
     polyVecKInvNTTToMont(h);
     polyVecKReduce(h);
+    /* c8 ignore start */
     if (polyVecKChkNorm(h, GAMMA2) !== 0) {
       continue;
     }
+    /* c8 ignore stop */
 
     polyVecKAdd(w0, w0, h);
     const n = polyVecKMakeHint(h, w0, w1);
+    /* c8 ignore start */
     if (n > OMEGA) {
       continue;
     }
+    /* c8 ignore stop */
 
     packSig(sig, ctilde, z, h);
     return 0;
@@ -1303,9 +1384,6 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
  */
 function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
   const msgBytes = messageToBytes(msg);
-  if (!msgBytes) {
-    throw new Error('message must be Uint8Array or hex string');
-  }
 
   const sm = new Uint8Array(CryptoBytes + msgBytes.length);
   const mLen = msgBytes.length;
@@ -1314,9 +1392,11 @@ function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
   }
   const result = cryptoSignSignature(sm, msgBytes, sk, randomizedSigning, ctx);
 
+  /* c8 ignore start */
   if (result !== 0) {
     throw new Error('failed to sign');
   }
+  /* c8 ignore stop */
   return sm;
 }
 
@@ -1383,9 +1463,6 @@ function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
   } catch {
     return false;
   }
-  if (!mBytes) {
-    return false;
-  }
   const muFull = sha3_js.shake256.create({}).update(tr).update(pre).update(mBytes).xof(CRHBytes);
   mu.set(muFull);
 

package/dist/mjs/mldsa87.js

@@ -1,5 +1,4 @@
 import { shake128, shake256 } from '@noble/hashes/sha3.js';
-import pkg from 'randombytes';
 import { hexToBytes as hexToBytes$1 } from '@noble/hashes/utils.js';
 
 const Shake128Rate = 168;
@@ -368,6 +367,8 @@ function polyUniform(a, seed, nonce) {
 
   let ctr = rejUniform(a.coeffs, 0, N, buf, bufLen);
 
+  // Note: With current parameters, needing extra blocks is vanishingly unlikely.
+  /* c8 ignore start */
   while (ctr < N) {
     off = bufLen % 3;
     for (let i = 0; i < off; ++i) buf[i] = buf[bufLen - off + i];
@@ -376,6 +377,7 @@ function polyUniform(a, seed, nonce) {
     bufLen = Stream128BlockBytes + off;
     ctr += rejUniform(a.coeffs, ctr, N - ctr, buf, bufLen);
   }
+  /* c8 ignore stop */
 }
 
 function rejEta(aP, aOffset, len, buf, bufLen) {
@@ -471,10 +473,13 @@ function polyChallenge(cP, seed) {
   }
   for (let i = N - TAU; i < N; ++i) {
     do {
+      // Note: Re-squeezing here is extremely unlikely with TAU=60.
+      /* c8 ignore start */
       if (pos >= Shake256Rate) {
         shake256SqueezeBlocks(buf, 0, 1, state);
         pos = 0;
       }
+      /* c8 ignore stop */
 
       b = buf[pos++];
     } while (b > i);
@@ -1019,7 +1024,69 @@ function unpackSig(cP, z, hP, sig) {
   return 0;
 }
 
-const randomBytes = pkg;
+const MAX_BYTES = 65536;
+
+function getGlobalScope() {
+  if (typeof globalThis === 'object') return globalThis;
+  if (typeof self === 'object') return self;
+  if (typeof window === 'object') return window;
+  if (typeof global === 'object') return global;
+  return {};
+}
+
+function getWebCrypto() {
+  const scope = getGlobalScope();
+  return scope.crypto || scope.msCrypto || null;
+}
+
+function getNodeRandomBytes() {
+  /* c8 ignore next */
+  const isNode = typeof process === 'object' && process !== null && process.versions && process.versions.node;
+  if (!isNode) return null;
+
+  const req =
+    typeof module !== 'undefined' && module && typeof module.require === 'function'
+      ? module.require.bind(module)
+      : typeof module !== 'undefined' && module && typeof module.createRequire === 'function'
+        ? module.createRequire(import.meta.url)
+        : typeof require === 'function'
+          ? require
+          : null;
+  if (!req) return null;
+
+  try {
+    const nodeCrypto = req('crypto');
+    if (nodeCrypto && typeof nodeCrypto.randomBytes === 'function') {
+      return nodeCrypto.randomBytes;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+function randomBytes(size) {
+  if (!Number.isSafeInteger(size) || size < 0) {
+    throw new RangeError('size must be a non-negative integer');
+  }
+
+  const cryptoObj = getWebCrypto();
+  if (cryptoObj && typeof cryptoObj.getRandomValues === 'function') {
+    const out = new Uint8Array(size);
+    for (let i = 0; i < size; i += MAX_BYTES) {
+      cryptoObj.getRandomValues(out.subarray(i, Math.min(size, i + MAX_BYTES)));
+    }
+    return out;
+  }
+
+  const nodeRandomBytes = getNodeRandomBytes();
+  if (nodeRandomBytes) {
+    return nodeRandomBytes(size);
+  }
+
+  throw new Error('Secure random number generation is not supported by this environment');
+}
 
 /**
  * Default signing context ("ZOND" in ASCII).
@@ -1030,15 +1097,27 @@ 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)
+ *
  * @param {string} hex - Hex string (optional 0x prefix, even length).
  * @returns {Uint8Array} Decoded bytes.
  * @private
  */
 function hexToBytes(hex) {
+  /* c8 ignore start */
   if (typeof hex !== 'string') {
     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 (clean.startsWith('0x') || clean.startsWith('0X')) {
     clean = clean.slice(2);
   }
@@ -1058,7 +1137,7 @@ function messageToBytes(message) {
   if (message instanceof Uint8Array) {
     return message;
   }
-  return null;
+  throw new Error('message must be Uint8Array or hex string');
 }
 
 /**
@@ -1206,9 +1285,6 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
   pre.set(ctx, 2);
 
   const mBytes = messageToBytes(m);
-  if (!mBytes) {
-    throw new Error('message must be Uint8Array or hex string');
-  }
 
   // mu = SHAKE256(tr || pre || m)
   const mu = shake256.create({}).update(tr).update(pre).update(mBytes).xof(CRHBytes);
@@ -1266,15 +1342,19 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
     polyVecKPointWisePolyMontgomery(h, cp, t0);
     polyVecKInvNTTToMont(h);
     polyVecKReduce(h);
+    /* c8 ignore start */
     if (polyVecKChkNorm(h, GAMMA2) !== 0) {
       continue;
     }
+    /* c8 ignore stop */
 
     polyVecKAdd(w0, w0, h);
     const n = polyVecKMakeHint(h, w0, w1);
+    /* c8 ignore start */
     if (n > OMEGA) {
       continue;
     }
+    /* c8 ignore stop */
 
     packSig(sig, ctilde, z, h);
     return 0;
@@ -1301,9 +1381,6 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
  */
 function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
   const msgBytes = messageToBytes(msg);
-  if (!msgBytes) {
-    throw new Error('message must be Uint8Array or hex string');
-  }
 
   const sm = new Uint8Array(CryptoBytes + msgBytes.length);
   const mLen = msgBytes.length;
@@ -1312,9 +1389,11 @@ function cryptoSign(msg, sk, randomizedSigning, ctx = DEFAULT_CTX) {
   }
   const result = cryptoSignSignature(sm, msgBytes, sk, randomizedSigning, ctx);
 
+  /* c8 ignore start */
   if (result !== 0) {
     throw new Error('failed to sign');
   }
+  /* c8 ignore stop */
   return sm;
 }
 
@@ -1381,9 +1460,6 @@ function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
   } catch {
     return false;
   }
-  if (!mBytes) {
-    return false;
-  }
   const muFull = shake256.create({}).update(tr).update(pre).update(mBytes).xof(CRHBytes);
   mu.set(muFull);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theqrl/mldsa87",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "ML-DSA-87 cryptography",
   "keywords": [
     "ml-dsa",
@@ -31,10 +31,12 @@
     "url": "git+https://github.com/theQRL/qrypto.js.git"
   },
   "scripts": {
-    "test": "../../node_modules/mocha/bin/mocha.js --timeout 10000",
+    "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/mldsa87.js --format cjs && rollup src/index.js --file ./dist/mjs/mldsa87.js --format esm && ./fixup",
     "lint-check": "eslint 'src/**/*.js' 'test/**/*.js'",
     "lint": "eslint --fix 'src/**/*.js' 'test/**/*.js'",
+    "coverage": "c8 npm run test",
     "report-coverage": "c8 --reporter=text-lcov npm run test > coverage.lcov"
   },
   "bugs": {
@@ -47,6 +49,9 @@
     }
   },
   "type": "module",
+  "engines": {
+    "node": ">=18.20.0"
+  },
   "devDependencies": {
     "@eslint/js": "^9.39.0",
     "c8": "^10.1.3",
@@ -61,7 +66,6 @@
     "rollup": "^4.55.1"
   },
   "dependencies": {
-    "@noble/hashes": "^2.0.1",
-    "randombytes": "^2.1.0"
+    "@noble/hashes": "^2.0.1"
   }
 }

package/src/index.d.ts

@@ -58,7 +58,7 @@ export function cryptoSignKeypair(
 /**
  * Create a signature for a message with optional context
  * @param sig - Output buffer for signature (must be CryptoBytes length minimum)
- * @param m - Message to sign (hex string or Uint8Array)
+ * @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")
@@ -92,7 +92,7 @@ export function cryptoSign(
 /**
  * Verify a signature with optional context
  * @param sig - Signature to verify
- * @param m - Message that was signed (hex string or Uint8Array)
+ * @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")
  * @returns true if signature is valid, false otherwise