@theqrl/wallet.js 0.1.2 → 0.2.0

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "@theqrl/wallet.js",
-  "version": "0.1.2",
-  "description": "",
-  "main": "src/index.js",
+  "version": "0.2.0",
+  "description": "Quantum-resistant wallet library for The QRL using ML-DSA-87 (FIPS 204)",
+  "type": "module",
+  "main": "dist/cjs/wallet.js",
+  "module": "dist/mjs/wallet.js",
   "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/mjs/wallet.js",
+      "require": "./dist/cjs/wallet.js"
+    }
+  },
   "scripts": {
+    "build": "rollup -c && ./fixup",
+    "prepublishOnly": "npm run build",
     "test": "mocha",
     "lint-check": "eslint 'src/**/*.js' 'test/**/*.js'",
     "lint": "eslint --fix 'src/**/*.js' 'test/**/*.js'",
@@ -14,29 +25,32 @@
   "author": "QRL contributors <info@theqrl.org> (https://theqrl.org)",
   "license": "MIT",
   "dependencies": {
-    "@theqrl/dilithium5": "^0.0.9",
-    "randombytes": "^2.1.0",
-    "sha3": "^2.1.4"
+    "@noble/hashes": "^1.8.0",
+    "@theqrl/mldsa87": "^0.2.0",
+    "randombytes": "^2.1.0"
   },
   "directories": {
     "lib": "src",
     "test": "test"
   },
   "files": [
-    "src"
+    "dist",
+    "src",
+    "types"
   ],
   "devDependencies": {
     "@types/node": "^20.14.12",
     "c8": "^7.13.0",
     "chai": "^4.3.7",
-    "codecov": "^3.8.3",
     "eslint": "^8.37.0",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-prettier": "^8.8.0",
     "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-prettier": "^4.2.1",
+    "fast-check": "^4.5.3",
     "mocha": "^10.2.0",
     "prettier": "^2.8.7",
+    "rollup": "^4.55.1",
     "typescript": "^5.5.4"
   }
 }

package/src/index.js

@@ -1,15 +1,35 @@
-const dilithium = require('./dilithium.js');
-const mnemonic = require('./utils/mnemonic.js');
-const wordlist = require('./qrl/wordlist.js');
+/**
+ * Package entry: re-export modules at the root for convenience.
+ * @module index
+ */
 
-module.exports = {
-  Dilithium: dilithium.Dilithium,
-  extractMessage: dilithium.extractMessage,
-  extractSignature: dilithium.extractSignature,
-  getDilithiumAddressFromPK: dilithium.getDilithiumAddressFromPK,
-  getDilithiumDescriptor: dilithium.getDilithiumDescriptor,
-  isValidDilithiumAddress: dilithium.isValidDilithiumAddress,
-  MnemonicToSeedBin: mnemonic.MnemonicToSeedBin,
-  SeedBinToMnemonic: mnemonic.SeedBinToMnemonic,
-  WORD_LIST: wordlist.WordList,
+import { DESCRIPTOR_SIZE, EXTENDED_SEED_SIZE, SEED_SIZE } from './wallet/common/constants.js';
+import {
+  getAddressFromPKAndDescriptor,
+  stringToAddress,
+  isValidAddress,
+  addressToString,
+} from './wallet/common/address.js';
+import { ExtendedSeed, Seed } from './wallet/common/seed.js';
+import { newMLDSA87Descriptor } from './wallet/ml_dsa_87/descriptor.js';
+import { Descriptor } from './wallet/common/descriptor.js';
+import { newWalletFromExtendedSeed } from './wallet/factory.js';
+import { Wallet as MLDSA87 } from './wallet/ml_dsa_87/wallet.js';
+import { WalletType } from './wallet/common/wallettype.js';
+
+export {
+  Seed,
+  SEED_SIZE,
+  ExtendedSeed,
+  EXTENDED_SEED_SIZE,
+  Descriptor,
+  DESCRIPTOR_SIZE,
+  newMLDSA87Descriptor,
+  getAddressFromPKAndDescriptor,
+  addressToString,
+  stringToAddress,
+  isValidAddress,
+  WalletType,
+  newWalletFromExtendedSeed,
+  MLDSA87,
 };

package/src/qrl/wordlist.js

@@ -1,4 +1,14 @@
-const WordList = [
+/**
+ * Mnemonic word list used by encoding/decoding utilities.
+ * @module qrl/wordlist
+ */
+
+/**
+ * Ordered list of mnemonic words.
+ * @readonly
+ * @type {string[]}
+ */
+export const WordList = [
   'aback',
   'abbey',
   'abbot',
@@ -4096,7 +4106,3 @@ const WordList = [
   'zone',
   'zurich',
 ];
-
-module.exports = {
-  WordList,
-};

package/src/utils/bytes.js

@@ -0,0 +1,59 @@
+/**
+ * Shared byte/hex utils used across modules.
+ * @module utils/bytes
+ */
+
+import { hexToBytes } from '@noble/hashes/utils';
+
+/**
+ * @param {unknown} input
+ * @returns {boolean}
+ */
+export function isUint8(input) {
+  return input instanceof Uint8Array;
+}
+
+/**
+ * Accepts strings with optional 0x/0X prefix and separators(space, :, _, -).
+ * @param {unknown} input
+ * @returns {boolean}
+ */
+export function isHexLike(input) {
+  if (typeof input !== 'string') return false;
+  const s = input.trim().replace(/^0x/i, '');
+  return /^[0-9a-fA-F\s:_-]*$/.test(s);
+}
+
+/**
+ * Remove 0x prefix and all non-hex chars.
+ * @param {string} hex
+ * @returns {string}
+ */
+export function cleanHex(hex) {
+  return hex.replace(/^0x/i, '').replace(/[^0-9a-fA-F]/g, '');
+}
+
+/**
+ * Convert various inputs to a fixed-length byte array.
+ * Supports hex string(with/without 0x), Uint8Array, Buffer, number[].
+ * @param {string|Uint8Array|Buffer|number[]} input
+ * @param {number} expectedLen
+ * @param {string} [label='bytes']
+ * @returns {Uint8Array}
+ */
+export function toFixedU8(input, expectedLen, label = 'bytes') {
+  let bytes;
+  if (isUint8(input)) {
+    bytes = new Uint8Array(input);
+  } else if (isHexLike(input)) {
+    bytes = hexToBytes(cleanHex(input));
+  } else if (Array.isArray(input)) {
+    bytes = Uint8Array.from(input);
+  } else {
+    throw new Error(`${label}: unsupported input type; pass hex string or Uint8Array/Buffer`);
+  }
+  if (bytes.length !== expectedLen) {
+    throw new Error(`${label}: expected ${expectedLen} bytes, got ${bytes.length}`);
+  }
+  return bytes;
+}

package/src/wallet/common/address.js

@@ -0,0 +1,94 @@
+/**
+ * Address helpers.
+ * @module wallet/common/address
+ */
+
+/** @typedef {import('./descriptor.js').Descriptor} Descriptor */
+import { shake256 } from '@noble/hashes/sha3';
+import { CryptoPublicKeyBytes } from '@theqrl/mldsa87';
+import { ADDRESS_SIZE } from './constants.js';
+
+/**
+ * Convert address bytes to string form.
+ * @param {Uint8Array} addrBytes
+ * @returns {string}
+ * @throws {Error} If length mismatch.
+ */
+function addressToString(addrBytes) {
+  if (!addrBytes || addrBytes.length !== ADDRESS_SIZE) {
+    throw new Error(`address must be ${ADDRESS_SIZE} bytes`);
+  }
+  const hex = [...addrBytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+  return `Q${hex}`;
+}
+
+/**
+ * Convert address string to bytes.
+ * @param {string} addrStr - Address string starting with 'Q' followed by 40 hex characters.
+ * @returns {Uint8Array} 20-byte address.
+ * @throws {Error} If address format is invalid.
+ */
+function stringToAddress(addrStr) {
+  if (typeof addrStr !== 'string') {
+    throw new Error('address must be a string');
+  }
+  const trimmed = addrStr.trim();
+  if (!trimmed.startsWith('Q') && !trimmed.startsWith('q')) {
+    throw new Error('address must start with Q');
+  }
+  const hex = trimmed.slice(1);
+  if (hex.length !== ADDRESS_SIZE * 2) {
+    throw new Error(`address must be Q + ${ADDRESS_SIZE * 2} hex characters, got ${hex.length}`);
+  }
+  if (!/^[0-9a-fA-F]+$/.test(hex)) {
+    throw new Error('address contains invalid characters');
+  }
+  const bytes = new Uint8Array(ADDRESS_SIZE);
+  for (let i = 0; i < ADDRESS_SIZE; i += 1) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Check if a string is a valid QRL address format.
+ * @param {string} addrStr - Address string to validate.
+ * @returns {boolean} True if valid address format.
+ */
+function isValidAddress(addrStr) {
+  try {
+    stringToAddress(addrStr);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Derive an address from a public key and descriptor.
+ * @param {Uint8Array} pk
+ * @param {Descriptor} descriptor
+ * @returns {Uint8Array} 20-byte address.
+ * @throws {Error} If pk length mismatch.
+ */
+function getAddressFromPKAndDescriptor(pk, descriptor) {
+  if (!(pk instanceof Uint8Array)) throw new Error('pk must be Uint8Array');
+
+  const walletType = descriptor.type();
+  let expectedPKLen;
+  switch (walletType) {
+    default:
+      expectedPKLen = CryptoPublicKeyBytes;
+  }
+  if (pk.length !== expectedPKLen) {
+    throw new Error(`pk must be ${expectedPKLen} bytes for wallet type ${walletType}`);
+  }
+
+  const descBytes = descriptor.toBytes();
+  const input = new Uint8Array(descBytes.length + pk.length);
+  input.set(descBytes, 0);
+  input.set(pk, descBytes.length);
+  return shake256.create({ dkLen: ADDRESS_SIZE }).update(input).digest();
+}
+
+export { addressToString, stringToAddress, isValidAddress, getAddressFromPKAndDescriptor };

package/src/wallet/common/constants.js

@@ -0,0 +1,16 @@
+/**
+ * Constants used across wallet components.
+ * @module wallet/common/constants
+ */
+
+/** @type {number} Size in bytes of the 3-byte descriptor */
+export const DESCRIPTOR_SIZE = 3;
+
+/** @type {number} Address length in bytes */
+export const ADDRESS_SIZE = 20;
+
+/** @type {number} Seed length in bytes */
+export const SEED_SIZE = 48;
+
+/** @type {number} Extended seed length in bytes */
+export const EXTENDED_SEED_SIZE = DESCRIPTOR_SIZE + SEED_SIZE;

package/src/wallet/common/descriptor.js

@@ -0,0 +1,70 @@
+/**
+ * 3-byte descriptor for a wallet:
+ *  - byte 0: wallet type (e.g. ML_DSA_87)
+ *  - bytes 1..2: 2 bytes metadata
+ * @module wallet/common/descriptor
+ */
+
+import { DESCRIPTOR_SIZE } from './constants.js';
+import { isValidWalletType } from './wallettype.js';
+import { toFixedU8 } from '../../utils/bytes.js';
+
+class Descriptor {
+  /**
+   * @param {Uint8Array|number[]} bytes Must be exactly 3 bytes.
+   * @throws {Error} If size is not 3 or wallet type is invalid.
+   */
+  constructor(bytes) {
+    if (!bytes || bytes.length !== DESCRIPTOR_SIZE) {
+      throw new Error(`Descriptor must be ${DESCRIPTOR_SIZE} bytes`);
+    }
+    /** @private @type {Uint8Array} */
+    this.bytes = Uint8Array.from(bytes);
+    if (!isValidWalletType(this.bytes[0])) {
+      throw new Error('Invalid wallet type in descriptor');
+    }
+  }
+
+  /**
+   * @returns {number}
+   */
+  type() {
+    return this.bytes[0] >>> 0;
+  }
+
+  /**
+   * Copy of internal bytes.
+   * @returns {Uint8Array}
+   */
+  toBytes() {
+    return this.bytes.slice();
+  }
+
+  /**
+   * Constructor: accepts hex string / Uint8Array / Buffer / number[].
+   * @param {string|Uint8Array|Buffer|number[]} input
+   * @returns {Descriptor}
+   */
+  static from(input) {
+    return new Descriptor(toFixedU8(input, DESCRIPTOR_SIZE, 'Descriptor'));
+  }
+}
+
+/**
+ * Build descriptor bytes from parts.
+ * @param {number} walletType byte.
+ * @param {[number, number]} [metadata=[0,0]] Two metadata bytes.
+ * @returns {Uint8Array} 3 bytes.
+ */
+function getDescriptorBytes(walletType, metadata = [0, 0]) {
+  if (!isValidWalletType(walletType)) {
+    throw new Error('Invalid wallet type in descriptor');
+  }
+  const out = new Uint8Array(DESCRIPTOR_SIZE);
+  out[0] = walletType >>> 0;
+  out[1] = (metadata?.[0] ?? 0) >>> 0;
+  out[2] = (metadata?.[1] ?? 0) >>> 0;
+  return out;
+}
+
+export { Descriptor, getDescriptorBytes };

package/src/wallet/common/seed.js

@@ -0,0 +1,123 @@
+/**
+ * Seed(48 bytes) and ExtendedSeed(51 bytes) with constructors.
+ * @module wallet/common/seed
+ */
+
+import { sha256 } from '@noble/hashes/sha2.js';
+import { SEED_SIZE, EXTENDED_SEED_SIZE, DESCRIPTOR_SIZE } from './constants.js';
+import { toFixedU8 } from '../../utils/bytes.js';
+import { Descriptor } from './descriptor.js';
+import { isValidWalletType } from './wallettype.js';
+
+class Seed {
+  /**
+   * @param {Uint8Array} bytes Exactly 48 bytes.
+   * @throws {Error} If size mismatch.
+   */
+  constructor(bytes) {
+    if (!bytes || bytes.length !== SEED_SIZE) {
+      throw new Error(`Seed must be ${SEED_SIZE} bytes`);
+    }
+    this.bytes = Uint8Array.from(bytes);
+  }
+
+  /** @returns {Uint8Array} */
+  hashSHA256() {
+    return Uint8Array.from(sha256(this.bytes));
+  }
+
+  /**
+   * Copy of internal seed bytes.
+   * @returns {Uint8Array}
+   */
+  toBytes() {
+    return this.bytes.slice();
+  }
+
+  /**
+   * Constructor: accepts hex string / Uint8Array / Buffer / number[].
+   * @param {string|Uint8Array|Buffer|number[]} input
+   * @returns {Seed}
+   */
+  static from(input) {
+    return new Seed(toFixedU8(input, SEED_SIZE, 'Seed'));
+  }
+}
+
+class ExtendedSeed {
+  /**
+   * Layout: [3 bytes descriptor] || [48 bytes seed].
+   * @param {Uint8Array} bytes Exactly 51 bytes.
+   * @throws {Error} If size mismatch.
+   */
+  constructor(bytes) {
+    if (!bytes || bytes.length !== EXTENDED_SEED_SIZE) {
+      throw new Error(`ExtendedSeed must be ${EXTENDED_SEED_SIZE} bytes`);
+    }
+    /** @private @type {Uint8Array} */
+    this.bytes = Uint8Array.from(bytes);
+    if (!isValidWalletType(this.bytes[0])) {
+      throw new Error('Invalid wallet type in descriptor');
+    }
+  }
+
+  /**
+   * @returns {Descriptor}
+   */
+  getDescriptor() {
+    return new Descriptor(this.getDescriptorBytes());
+  }
+
+  /**
+   * @returns {Uint8Array} Descriptor(3 bytes).
+   */
+  getDescriptorBytes() {
+    return this.bytes.slice(0, DESCRIPTOR_SIZE);
+  }
+
+  /**
+   * @returns {Uint8Array} Seed bytes(48 bytes).
+   */
+  getSeedBytes() {
+    return this.bytes.slice(DESCRIPTOR_SIZE);
+  }
+
+  /**
+   * @returns {Seed}
+   */
+  getSeed() {
+    return new Seed(this.getSeedBytes());
+  }
+
+  /**
+   * Copy of internal seed bytes.
+   * @returns {Uint8Array}
+   */
+  toBytes() {
+    return this.bytes.slice();
+  }
+
+  /**
+   * Build from components.
+   * @param {Descriptor} desc
+   * @param {Seed} seed
+   * @returns {ExtendedSeed}
+   */
+  static newExtendedSeed(desc, seed) {
+    const out = new Uint8Array(EXTENDED_SEED_SIZE);
+    out.set(desc.toBytes(), 0);
+    out.set(seed.toBytes(), DESCRIPTOR_SIZE);
+    return new ExtendedSeed(out);
+  }
+
+  /**
+   * Constructor: accepts hex string / Uint8Array / Buffer / number[].
+   * @param {string|Uint8Array|Buffer|number[]} input
+   * @returns {ExtendedSeed}
+   */
+  static from(input) {
+    return new ExtendedSeed(toFixedU8(input, EXTENDED_SEED_SIZE, 'ExtendedSeed'));
+  }
+}
+
+export { Seed, ExtendedSeed };

package/src/wallet/common/wallettype.js

@@ -0,0 +1,21 @@
+/**
+ * Wallet type enumeration.
+ * @module wallet/common/wallettype
+ */
+
+/**
+ * @readonly
+ * @enum {number}
+ */
+export const WalletType = Object.freeze({
+  SPHINCSPLUS_256S: 0,
+  ML_DSA_87: 1,
+});
+
+/**
+ * @param {number} t
+ * @return {boolean}
+ */
+export function isValidWalletType(t) {
+  return t === WalletType.ML_DSA_87;
+}

package/src/wallet/factory.js

@@ -0,0 +1,39 @@
+/**
+ * Auto-select wallet implementation based on the ExtendedSeed descriptor.
+ * @module wallet/factory
+ */
+
+import { isHexLike } from '../utils/bytes.js';
+import { ExtendedSeed } from './common/seed.js';
+import { WalletType } from './common/wallettype.js';
+import { Wallet as MLDSA87 } from './ml_dsa_87/wallet.js';
+
+/**
+ * Construct a wallet from an ExtendedSeed by auto-selecting the correct implementation.
+ *
+ * @param {ExtendedSeed|Uint8Array|string} extendedSeed - ExtendedSeed instance, 51 bytes or hex string.
+ * @returns {MLDSA87} Wallet instance
+ * @throws {Error} If wallet type is unsupported
+ */
+function newWalletFromExtendedSeed(extendedSeed) {
+  let ext;
+  if (extendedSeed instanceof Uint8Array || isHexLike(extendedSeed)) {
+    ext = ExtendedSeed.from(extendedSeed);
+  } else if (extendedSeed instanceof ExtendedSeed) {
+    ext = extendedSeed;
+  } else {
+    throw new Error('Unsupported extendedSeed input');
+  }
+
+  const desc = ext.getDescriptor();
+  switch (desc.type()) {
+    case WalletType.ML_DSA_87:
+      return MLDSA87.newWalletFromExtendedSeed(ext);
+    // case WalletType.SPHINCSPLUS_256S:
+    //   Not yet implemented - reserved for future use
+    default:
+      throw new Error(`Unsupported wallet type: ${desc.type()}`);
+  }
+}
+
+export { newWalletFromExtendedSeed };

package/src/wallet/misc/mnemonic.js

@@ -0,0 +1,77 @@
+/**
+ * Minimal mnemonic adapters.
+ * @module wallet/misc/mnemonic
+ */
+
+import { WordList } from '../../qrl/wordlist.js';
+
+const WORD_LOOKUP = WordList.reduce((acc, word, i) => {
+  acc[word] = i;
+  return acc;
+}, Object.create(null));
+
+/**
+ * Encode bytes to a spaced hex mnemonic string.
+ * @param {Uint8Array} input
+ * @returns {string}
+ */
+function binToMnemonic(input) {
+  if (input.length % 3 !== 0) {
+    throw new Error('byte count needs to be a multiple of 3');
+  }
+
+  const words = [];
+  for (let nibble = 0; nibble < input.length * 2; nibble += 3) {
+    const p = nibble >> 1;
+    const b1 = input[p];
+    const b2 = p + 1 < input.length ? input[p + 1] : 0;
+    const idx = nibble % 2 === 0 ? (b1 << 4) + (b2 >> 4) : ((b1 & 0x0f) << 8) + b2;
+
+    if (idx >= WordList.length) {
+      throw new Error('mnemonic index out of range');
+    }
+    words.push(WordList[idx]);
+  }
+
+  return words.join(' ');
+}
+
+/**
+ * Decode spaced hex mnemonic to bytes.
+ * @param {string} mnemonic
+ * @returns {Uint8Array}
+ */
+function mnemonicToBin(mnemonic) {
+  const mnemonicWords = mnemonic.trim().toLowerCase().split(/\s+/);
+  if (mnemonicWords.length % 2 !== 0) throw new Error('word count must be even');
+
+  const result = new Uint8Array((mnemonicWords.length * 15) / 10);
+  let current = 0;
+  let buffering = 0;
+  let resultIndex = 0;
+
+  for (let i = 0; i < mnemonicWords.length; i += 1) {
+    const w = mnemonicWords[i];
+    const value = WORD_LOOKUP[w];
+    if (value === undefined) throw new Error('invalid word in mnemonic');
+
+    buffering += 3;
+    current = (current << 12) + value;
+    for (; buffering > 2; ) {
+      const shift = 4 * (buffering - 2);
+      const mask = (1 << shift) - 1;
+      const tmp = current >> shift;
+      buffering -= 2;
+      current &= mask;
+      result[resultIndex++] = tmp;
+    }
+  }
+
+  if (buffering > 0) {
+    result[resultIndex++] = current & 0xff;
+  }
+
+  return result;
+}
+
+export { mnemonicToBin, binToMnemonic };