@theqrl/wallet.js 1.0.2 → 1.0.3

package/README.md

@@ -116,6 +116,10 @@ const wallet = newWalletFromExtendedSeed('0x01000000...'); // 51-byte hex
 
 ### Address Utilities
 
+**Address Format:** `Q` prefix + 40 lowercase hex characters (41 chars total).
+- Output is always lowercase; input parsing is case-insensitive
+- No checksum encoding (unlike EIP-55)
+
 ```javascript
 import {
   addressToString,
@@ -126,8 +130,9 @@ import {
 // Convert bytes to string
 const addrStr = addressToString(addressBytes); // 'Qabc...'
 
-// Convert string to bytes
+// Convert string to bytes (case-insensitive)
 const addrBytes = stringToAddress('Qabc123...');
+const same = stringToAddress('QABC123...');  // Also valid
 
 // Validate address format
 if (isValidAddress(userInput)) {

package/dist/cjs/wallet.js

@@ -4,9 +4,9 @@ var sha3 = require('@noble/hashes/sha3');
 var mldsa87 = require('@theqrl/mldsa87');
 var sha2_js = require('@noble/hashes/sha2.js');
 var utils = require('@noble/hashes/utils');
-var randomBytes = require('randombytes');
 var utils_js = require('@noble/hashes/utils.js');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 /**
  * Constants used across wallet components.
  * @module wallet/common/constants
@@ -27,6 +27,13 @@ const EXTENDED_SEED_SIZE = DESCRIPTOR_SIZE + SEED_SIZE;
 /**
  * Address helpers.
  * @module wallet/common/address
+ *
+ * Address Format:
+ *   - String form: "Q" prefix followed by 40 lowercase hex characters (41 chars total)
+ *   - Byte form: 20-byte SHAKE-256 hash of (descriptor || public key)
+ *   - Output is always lowercase hex; input parsing is case-insensitive for both
+ *     the "Q"/"q" prefix and hex characters
+ *   - Unlike EIP-55, no checksum encoding is used in the address itself
  */
 
 
@@ -405,6 +412,86 @@ function newMLDSA87Descriptor(metadata = [0, 0]) {
   return new Descriptor(getDescriptorBytes(WalletType.ML_DSA_87, metadata));
 }
 
+/**
+ * Secure random number generation for browser and Node.js environments.
+ * @module utils/random
+ */
+
+const MAX_BYTES = 65536;
+
+function getGlobalScope() {
+  if (typeof globalThis === 'object') return globalThis;
+  // eslint-disable-next-line no-restricted-globals
+  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;
+
+  let req = null;
+  if (typeof module !== 'undefined' && module && typeof module.require === 'function') {
+    req = module.require.bind(module);
+  } else if (typeof module !== 'undefined' && module && typeof module.createRequire === 'function') {
+    req = module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('wallet.js', document.baseURI).href)));
+  } else if (typeof require === 'function') {
+    req = require;
+  }
+  if (!req) return null;
+
+  try {
+    const nodeCrypto = req('crypto');
+    if (nodeCrypto && typeof nodeCrypto.randomBytes === 'function') {
+      return nodeCrypto.randomBytes;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Generate cryptographically secure random bytes.
+ *
+ * Uses Web Crypto API (getRandomValues) in browsers and crypto.randomBytes in Node.js.
+ *
+ * @param {number} size - Number of random bytes to generate
+ * @returns {Uint8Array} Random bytes
+ * @throws {RangeError} If size is invalid or too large
+ * @throws {Error} If no secure random source is available
+ */
+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');
+}
+
 /**
  * Mnemonic word list used by encoding/decoding utilities.
  * @module qrl/wordlist
@@ -4553,8 +4640,12 @@ function binToMnemonic(input) {
  * Decode spaced hex mnemonic to bytes.
  * @param {string} mnemonic
  * @returns {Uint8Array}
+ *
+ * Note: Mnemonic words are normalized to lowercase for user convenience.
+ * This is by design to reduce errors from capitalization differences.
  */
 function mnemonicToBin(mnemonic) {
+  // Normalize to lowercase for user-friendly input (case-insensitive matching)
   const mnemonicWords = mnemonic.trim().toLowerCase().split(/\s+/);
   if (mnemonicWords.length % 2 !== 0) throw new Error('word count must be even');
 
@@ -4594,11 +4685,18 @@ function mnemonicToBin(mnemonic) {
 
 /**
  * Generate a keypair.
+ *
+ * Note: ML-DSA-87 (FIPS 204) requires a 32-byte seed for key generation.
+ * QRL uses a 48-byte seed for mnemonic compatibility across wallet types.
+ * SHA-256 hashing reduces the 48-byte seed to the required 32 bytes per spec.
+ * This matches go-qrllib behavior for cross-implementation compatibility.
+ *
  * @returns {{ pk: Uint8Array, sk: Uint8Array }}
  */
 function keygen(seed) {
   const pk = new Uint8Array(mldsa87.CryptoPublicKeyBytes);
   const sk = new Uint8Array(mldsa87.CryptoSecretKeyBytes);
+  // FIPS 204 requires 32-byte seed; hash 48-byte QRL seed to derive it
   const seedBytes = new Uint8Array(seed.hashSHA256());
   mldsa87.cryptoSignKeypair(seedBytes, pk, sk);
   return { pk, sk };

package/dist/mjs/wallet.js

@@ -2,7 +2,6 @@ import { shake256 } from '@noble/hashes/sha3';
 import { CryptoPublicKeyBytes, cryptoSignKeypair, CryptoSecretKeyBytes, cryptoSign, CryptoBytes, cryptoSignVerify } from '@theqrl/mldsa87';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { hexToBytes } from '@noble/hashes/utils';
-import randomBytes from 'randombytes';
 import { bytesToHex } from '@noble/hashes/utils.js';
 
 /**
@@ -25,6 +24,13 @@ const EXTENDED_SEED_SIZE = DESCRIPTOR_SIZE + SEED_SIZE;
 /**
  * Address helpers.
  * @module wallet/common/address
+ *
+ * Address Format:
+ *   - String form: "Q" prefix followed by 40 lowercase hex characters (41 chars total)
+ *   - Byte form: 20-byte SHAKE-256 hash of (descriptor || public key)
+ *   - Output is always lowercase hex; input parsing is case-insensitive for both
+ *     the "Q"/"q" prefix and hex characters
+ *   - Unlike EIP-55, no checksum encoding is used in the address itself
  */
 
 
@@ -403,6 +409,86 @@ function newMLDSA87Descriptor(metadata = [0, 0]) {
   return new Descriptor(getDescriptorBytes(WalletType.ML_DSA_87, metadata));
 }
 
+/**
+ * Secure random number generation for browser and Node.js environments.
+ * @module utils/random
+ */
+
+const MAX_BYTES = 65536;
+
+function getGlobalScope() {
+  if (typeof globalThis === 'object') return globalThis;
+  // eslint-disable-next-line no-restricted-globals
+  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;
+
+  let req = null;
+  if (typeof module !== 'undefined' && module && typeof module.require === 'function') {
+    req = module.require.bind(module);
+  } else if (typeof module !== 'undefined' && module && typeof module.createRequire === 'function') {
+    req = module.createRequire(import.meta.url);
+  } else if (typeof require === 'function') {
+    req = require;
+  }
+  if (!req) return null;
+
+  try {
+    const nodeCrypto = req('crypto');
+    if (nodeCrypto && typeof nodeCrypto.randomBytes === 'function') {
+      return nodeCrypto.randomBytes;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Generate cryptographically secure random bytes.
+ *
+ * Uses Web Crypto API (getRandomValues) in browsers and crypto.randomBytes in Node.js.
+ *
+ * @param {number} size - Number of random bytes to generate
+ * @returns {Uint8Array} Random bytes
+ * @throws {RangeError} If size is invalid or too large
+ * @throws {Error} If no secure random source is available
+ */
+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');
+}
+
 /**
  * Mnemonic word list used by encoding/decoding utilities.
  * @module qrl/wordlist
@@ -4551,8 +4637,12 @@ function binToMnemonic(input) {
  * Decode spaced hex mnemonic to bytes.
  * @param {string} mnemonic
  * @returns {Uint8Array}
+ *
+ * Note: Mnemonic words are normalized to lowercase for user convenience.
+ * This is by design to reduce errors from capitalization differences.
  */
 function mnemonicToBin(mnemonic) {
+  // Normalize to lowercase for user-friendly input (case-insensitive matching)
   const mnemonicWords = mnemonic.trim().toLowerCase().split(/\s+/);
   if (mnemonicWords.length % 2 !== 0) throw new Error('word count must be even');
 
@@ -4592,11 +4682,18 @@ function mnemonicToBin(mnemonic) {
 
 /**
  * Generate a keypair.
+ *
+ * Note: ML-DSA-87 (FIPS 204) requires a 32-byte seed for key generation.
+ * QRL uses a 48-byte seed for mnemonic compatibility across wallet types.
+ * SHA-256 hashing reduces the 48-byte seed to the required 32 bytes per spec.
+ * This matches go-qrllib behavior for cross-implementation compatibility.
+ *
  * @returns {{ pk: Uint8Array, sk: Uint8Array }}
  */
 function keygen(seed) {
   const pk = new Uint8Array(CryptoPublicKeyBytes);
   const sk = new Uint8Array(CryptoSecretKeyBytes);
+  // FIPS 204 requires 32-byte seed; hash 48-byte QRL seed to derive it
   const seedBytes = new Uint8Array(seed.hashSHA256());
   cryptoSignKeypair(seedBytes, pk, sk);
   return { pk, sk };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theqrl/wallet.js",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Quantum-resistant wallet library for The QRL using ML-DSA-87 (FIPS 204)",
   "type": "module",
   "main": "dist/cjs/wallet.js",
@@ -17,6 +17,7 @@
     "build": "rollup -c && ./fixup",
     "prepublishOnly": "npm run build",
     "test": "mocha",
+    "test:browser": "playwright test",
     "lint-check": "eslint 'src/**/*.js' 'test/**/*.js'",
     "lint": "eslint --fix 'src/**/*.js' 'test/**/*.js'",
     "report-coverage": "c8 --reporter=text-lcov npm run test > coverage.lcov",
@@ -30,8 +31,7 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.8.0",
-    "@theqrl/mldsa87": "^1.0.5",
-    "randombytes": "^2.1.0"
+    "@theqrl/mldsa87": "^1.0.6"
   },
   "directories": {
     "lib": "src",
@@ -43,6 +43,7 @@
     "types"
   ],
   "devDependencies": {
+    "@playwright/test": "^1.49.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
@@ -57,6 +58,7 @@
     "eslint-plugin-prettier": "^4.2.1",
     "fast-check": "^4.5.3",
     "mocha": "^10.2.0",
+    "playwright": "^1.57.0",
     "prettier": "^2.8.7",
     "rollup": "^4.55.1",
     "typescript": "^5.5.4"

package/src/utils/random.js

@@ -0,0 +1,84 @@
+/**
+ * Secure random number generation for browser and Node.js environments.
+ * @module utils/random
+ */
+
+const MAX_BYTES = 65536;
+const MAX_UINT32 = 0xffffffff;
+
+function getGlobalScope() {
+  if (typeof globalThis === 'object') return globalThis;
+  // eslint-disable-next-line no-restricted-globals
+  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;
+
+  let req = null;
+  if (typeof module !== 'undefined' && module && typeof module.require === 'function') {
+    req = module.require.bind(module);
+  } else if (typeof module !== 'undefined' && module && typeof module.createRequire === 'function') {
+    req = module.createRequire(import.meta.url);
+  } else if (typeof require === 'function') {
+    req = require;
+  }
+  if (!req) return null;
+
+  try {
+    const nodeCrypto = req('crypto');
+    if (nodeCrypto && typeof nodeCrypto.randomBytes === 'function') {
+      return nodeCrypto.randomBytes;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Generate cryptographically secure random bytes.
+ *
+ * Uses Web Crypto API (getRandomValues) in browsers and crypto.randomBytes in Node.js.
+ *
+ * @param {number} size - Number of random bytes to generate
+ * @returns {Uint8Array} Random bytes
+ * @throws {RangeError} If size is invalid or too large
+ * @throws {Error} If no secure random source is available
+ */
+export function randomBytes(size) {
+  if (!Number.isSafeInteger(size) || size < 0) {
+    throw new RangeError('size must be a non-negative integer');
+  }
+  if (size > MAX_UINT32) {
+    throw new RangeError('requested too many random bytes');
+  }
+  if (size === 0) return new Uint8Array(0);
+
+  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');
+}

package/src/wallet/common/address.js

@@ -1,6 +1,13 @@
 /**
  * Address helpers.
  * @module wallet/common/address
+ *
+ * Address Format:
+ *   - String form: "Q" prefix followed by 40 lowercase hex characters (41 chars total)
+ *   - Byte form: 20-byte SHAKE-256 hash of (descriptor || public key)
+ *   - Output is always lowercase hex; input parsing is case-insensitive for both
+ *     the "Q"/"q" prefix and hex characters
+ *   - Unlike EIP-55, no checksum encoding is used in the address itself
  */
 
 /** @typedef {import('./descriptor.js').Descriptor} Descriptor */

package/src/wallet/misc/mnemonic.js

@@ -38,8 +38,12 @@ function binToMnemonic(input) {
  * Decode spaced hex mnemonic to bytes.
  * @param {string} mnemonic
  * @returns {Uint8Array}
+ *
+ * Note: Mnemonic words are normalized to lowercase for user convenience.
+ * This is by design to reduce errors from capitalization differences.
  */
 function mnemonicToBin(mnemonic) {
+  // Normalize to lowercase for user-friendly input (case-insensitive matching)
   const mnemonicWords = mnemonic.trim().toLowerCase().split(/\s+/);
   if (mnemonicWords.length % 2 !== 0) throw new Error('word count must be even');
 

package/src/wallet/ml_dsa_87/crypto.js

@@ -13,11 +13,18 @@ import {
 
 /**
  * Generate a keypair.
+ *
+ * Note: ML-DSA-87 (FIPS 204) requires a 32-byte seed for key generation.
+ * QRL uses a 48-byte seed for mnemonic compatibility across wallet types.
+ * SHA-256 hashing reduces the 48-byte seed to the required 32 bytes per spec.
+ * This matches go-qrllib behavior for cross-implementation compatibility.
+ *
  * @returns {{ pk: Uint8Array, sk: Uint8Array }}
  */
 function keygen(seed) {
   const pk = new Uint8Array(CryptoPublicKeyBytes);
   const sk = new Uint8Array(CryptoSecretKeyBytes);
+  // FIPS 204 requires 32-byte seed; hash 48-byte QRL seed to derive it
   const seedBytes = new Uint8Array(seed.hashSHA256());
   cryptoSignKeypair(seedBytes, pk, sk);
   return { pk, sk };

package/src/wallet/ml_dsa_87/wallet.js

@@ -4,8 +4,8 @@
  */
 
 /** @typedef {import('../common/descriptor.js').Descriptor} Descriptor */
-import randomBytes from 'randombytes';
 import { bytesToHex } from '@noble/hashes/utils.js';
+import { randomBytes } from '../../utils/random.js';
 import { mnemonicToBin, binToMnemonic } from '../misc/mnemonic.js';
 import { getAddressFromPKAndDescriptor, addressToString } from '../common/address.js';
 import { Descriptor } from '../common/descriptor.js';