quantum-coin-js-sdk 1.0.37 → 1.0.39

package/README.md

@@ -168,6 +168,7 @@ Example Project: https://github.com/quantumcoinproject/quantum-coin-js-sdk/tree/
     * [~publicKeyFromSignature(digest, signature)](#module_quantum-coin-js-sdk..publicKeyFromSignature) ⇒ <code>string</code>
     * [~publicKeyFromPrivateKey(privateKey)](#module_quantum-coin-js-sdk..publicKeyFromPrivateKey) ⇒ <code>string</code>
     * [~addressFromPublicKey(publicKey)](#module_quantum-coin-js-sdk..addressFromPublicKey) ⇒ <code>string</code>
+    * [~scryptDeriveKey(secret, salt, N, r, p, dkLen)](#module_quantum-coin-js-sdk..scryptDeriveKey) ⇒ <code>Array.&lt;number&gt;</code>
     * [~combinePublicKeySignature(publicKey, signature)](#module_quantum-coin-js-sdk..combinePublicKeySignature) ⇒ <code>string</code>
     * [~packMethodData(abiJSON, methodName, ...args)](#module_quantum-coin-js-sdk..packMethodData) ⇒ <code>PackUnpackResult</code>
     * [~unpackMethodData(abiJSON, methodName, hexData)](#module_quantum-coin-js-sdk..unpackMethodData) ⇒ <code>PackUnpackResult</code>
@@ -1541,6 +1542,25 @@ The addressFromPublicKey returns the address corresponding to the public key.
 | --- | --- | --- |
 | publicKey | <code>Array.&lt;number&gt;</code> | An array of bytes containing the public key. |
 
+<a name="module_quantum-coin-js-sdk..scryptDeriveKey"></a>
+
+### quantum-coin-js-sdk~scryptDeriveKey(secret, salt, N, r, p, dkLen) ⇒ <code>Array.&lt;number&gt;</code>
+The scryptDeriveKey function derives a key from a secret and salt using the scrypt KDF.
+
+Note: Only the specific scrypt parameter set N=262144, r=8, p=1, dkLen=32 is supported currently. Passing any other values returns null.
+
+**Kind**: inner method of [<code>quantum-coin-js-sdk</code>](#module_quantum-coin-js-sdk)  
+**Returns**: <code>Array.&lt;number&gt;</code> - - Returns the 32-byte derived key as a byte array. Returns null if the operation failed or the parameters are unsupported.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| secret | <code>string</code> | The secret/passphrase to derive the key from. |
+| salt | <code>Uint8Array</code> \| <code>Array.&lt;number&gt;</code> | The salt as a byte array. |
+| N | <code>number</code> | The scrypt CPU/memory cost parameter. Must be 262144. |
+| r | <code>number</code> | The scrypt block size parameter. Must be 8. |
+| p | <code>number</code> | The scrypt parallelization parameter. Must be 1. |
+| dkLen | <code>number</code> | The derived key length in bytes. Must be 32. |
+
 <a name="module_quantum-coin-js-sdk..combinePublicKeySignature"></a>
 
 ### quantum-coin-js-sdk~combinePublicKeySignature(publicKey, signature) ⇒ <code>string</code>

package/example/node_modules/.package-lock.json

@@ -5,7 +5,7 @@
   "requires": true,
   "packages": {
     "..": {
-      "version": "1.0.37",
+      "version": "1.0.39",
       "license": "MIT",
       "dependencies": {
         "seed-words": "1.0.2"

package/example/package-lock.json

@@ -14,7 +14,7 @@
       }
     },
     "..": {
-      "version": "1.0.37",
+      "version": "1.0.39",
       "license": "MIT",
       "dependencies": {
         "seed-words": "1.0.2"

package/index.d.ts

@@ -726,6 +726,22 @@ export function publicKeyFromPrivateKey(privateKey: number[]): string;
  * @return {string} - Returns the address corresponding to the public key as a hex string. Returns null if the operation failed.
  */
 export function addressFromPublicKey(publicKey: number[]): string;
+/**
+ * The scryptDeriveKey function derives a key from a secret and salt using the scrypt KDF.
+ *
+ * Note: Only the specific scrypt parameter set N=262144, r=8, p=1, dkLen=32 is supported
+ * currently. Passing any other values returns null.
+ *
+ * @function scryptDeriveKey
+ * @param {string} secret - The secret/passphrase to derive the key from.
+ * @param {Uint8Array|number[]} salt - The salt as a byte array.
+ * @param {number} N - The scrypt CPU/memory cost parameter. Must be 262144.
+ * @param {number} r - The scrypt block size parameter. Must be 8.
+ * @param {number} p - The scrypt parallelization parameter. Must be 1.
+ * @param {number} dkLen - The derived key length in bytes. Must be 32.
+ * @return {number[]} - Returns the 32-byte derived key as a byte array. Returns null if the operation failed or the parameters are unsupported.
+ */
+export function scryptDeriveKey(secret: string, salt: Uint8Array | number[], N: number, r: number, p: number, dkLen: number): number[];
 /**
  * The combinePublicKeySignature combines the public key and signature.
  *

package/index.js

@@ -62,6 +62,10 @@ const BASE_SEED_BYTES_HYBRIDEDS = 96;
 const BASE_SEED_BYTES_HYBRIDEDMLDSASLHDSA5 = 72;
 const BASE_SEED_BYTES_HYBRIDEDMLDSASLHDSA = 64;
 const MIN_PASSPHRASE_LENGTH = 12;
+const SCRYPT_SUPPORTED_N = 262144;
+const SCRYPT_SUPPORTED_R = 8;
+const SCRYPT_SUPPORTED_P = 1;
+const SCRYPT_SUPPORTED_DKLEN = 32;
 const INVALID_KEY_TYPE = -1001;
 const CIRCL_CRYPTO_FAILURE = -1002;
 const EXPECTED_WASM_SHA256 = "17aff465c5879e2ff94d33e8ce9d98d6ad6a70849b3e3cad7cccbcc9728e5a02";
@@ -2658,6 +2662,53 @@ function addressFromPublicKey(publicKey) {
     return PublicKeyToAddress(publicKey);
 }
 
+/**
+ * The scryptDeriveKey function derives a key from a secret and salt using the scrypt KDF.
+ *
+ * Note: Only the specific scrypt parameter set N=262144, r=8, p=1, dkLen=32 is supported
+ * currently. Passing any other values returns null.
+ *
+ * @function scryptDeriveKey
+ * @param {string} secret - The secret/passphrase to derive the key from.
+ * @param {Uint8Array|number[]} salt - The salt as a byte array.
+ * @param {number} N - The scrypt CPU/memory cost parameter. Must be 262144.
+ * @param {number} r - The scrypt block size parameter. Must be 8.
+ * @param {number} p - The scrypt parallelization parameter. Must be 1.
+ * @param {number} dkLen - The derived key length in bytes. Must be 32.
+ * @return {number[]} - Returns the 32-byte derived key as a byte array. Returns null if the operation failed or the parameters are unsupported.
+ */
+function scryptDeriveKey(secret, salt, N, r, p, dkLen) {
+    if (isInitialized === false) {
+        return -1000;
+    }
+
+    if (typeof secret !== 'string' && !(secret instanceof String)) {
+        return null;
+    }
+
+    if (isByteArray(salt) === false) {
+        return null;
+    }
+
+    if (typeof N !== 'number' || typeof r !== 'number' || typeof p !== 'number' || typeof dkLen !== 'number') {
+        return null;
+    }
+
+    if (N !== SCRYPT_SUPPORTED_N || r !== SCRYPT_SUPPORTED_R || p !== SCRYPT_SUPPORTED_P || dkLen !== SCRYPT_SUPPORTED_DKLEN) {
+        return null;
+    }
+
+    const saltU8 = salt instanceof Uint8Array ? salt : new Uint8Array(salt);
+    const saltBase64 = bytesToBase64(saltU8);
+
+    const derivedBase64 = Scrypt(secret, saltBase64);
+    if (derivedBase64 == null || (typeof derivedBase64 !== 'string' && !(derivedBase64 instanceof String))) {
+        return null;
+    }
+
+    return Array.from(base64ToBytes(derivedBase64));
+}
+
 /**
  * The combinePublicKeySignature combines the public key and signature.
  *
@@ -3162,6 +3213,7 @@ module.exports = {
     publicKeyFromSignature,
     publicKeyFromPrivateKey,
     addressFromPublicKey,
+    scryptDeriveKey,
     combinePublicKeySignature,
     TransactionSigningRequest,
     signRawTransaction,

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "quantum-coin-js-sdk",
-  "version": "1.0.37",
+  "version": "1.0.39",
   "description": "Quantum Coin - Q SDK in JavaScript",
   "main": "index.js",
   "scripts": {
-    "test": "node --test tests/non-transactional.preinit.test.js tests/non-transactional.test.js tests/sign-raw-transaction.test.js tests/sign-verify.test.js tests/get-gas-price.test.js tests/transactional.rpc.test.js tests/transactional.relay.test.js",
+    "test": "node --test tests/non-transactional.preinit.test.js tests/non-transactional.test.js tests/sign-raw-transaction.test.js tests/sign-verify.test.js tests/scrypt.test.js tests/get-gas-price.test.js tests/transactional.rpc.test.js tests/transactional.relay.test.js",
     "build": "npx -p typescript tsc index.js --declaration --allowJs --emitDeclarationOnly"
   },
   "repository": {

package/tests/scrypt.test.js

@@ -0,0 +1,128 @@
+/**
+ * Tests for scryptDeriveKey(secret, salt, N, r, p, dkLen).
+ *
+ * Only the fixed scrypt parameter set N=262144, r=8, p=1, dkLen=32 is supported currently,
+ * so the derived key is always 32 bytes and any other parameter values return null.
+ */
+const { describe, test, before } = require('node:test');
+const assert = require('node:assert/strict');
+
+const qcsdk = require('..');
+
+const MAINNET_CHAIN_ID = 123123;
+const READ_RELAY_URL = 'https://sdk.readrelay.quantumcoinapi.com';
+const WRITE_RELAY_URL = 'https://sdk.writerelay.quantumcoinapi.com';
+
+const SALT = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]);
+
+// Supported scrypt parameters.
+const N = 262144;
+const R = 8;
+const P = 1;
+const DKLEN = 32;
+
+function toBase64(bytes) {
+  return Buffer.from(bytes).toString('base64');
+}
+
+// This block intentionally runs before initialize() is called.
+describe('scryptDeriveKey (pre-init)', () => {
+  test('returns -1000 before initialize', () => {
+    assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, P, DKLEN), -1000);
+  });
+});
+
+describe('scryptDeriveKey', () => {
+  before(async () => {
+    const cfg = new qcsdk.Config(READ_RELAY_URL, WRITE_RELAY_URL, MAINNET_CHAIN_ID, '', '');
+    const initResult = await qcsdk.initialize(cfg);
+    assert.equal(initResult, true, 'SDK initialize should succeed');
+  });
+
+  test('derives a 32-byte key for a valid secret and salt', () => {
+    const key = qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, P, DKLEN);
+    assert.ok(Array.isArray(key), 'result should be a byte array');
+    assert.equal(key.length, 32, 'derived key must be 32 bytes');
+  });
+
+  test('is deterministic for the same secret and salt', () => {
+    const key1 = qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, P, DKLEN);
+    const key2 = qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, P, DKLEN);
+    assert.deepEqual(key1, key2, 'same inputs must produce the same key');
+  });
+
+  test('produces a different key for a different salt', () => {
+    const otherSalt = new Uint8Array(SALT);
+    otherSalt[0] = (otherSalt[0] + 1) & 0xff;
+    const key1 = qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, P, DKLEN);
+    const key2 = qcsdk.scryptDeriveKey('test-passphrase-123', otherSalt, N, R, P, DKLEN);
+    assert.notDeepEqual(key1, key2, 'different salt must produce a different key');
+  });
+
+  test('produces a different key for a different secret', () => {
+    const key1 = qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, P, DKLEN);
+    const key2 = qcsdk.scryptDeriveKey('test-passphrase-124', SALT, N, R, P, DKLEN);
+    assert.notDeepEqual(key1, key2, 'different secret must produce a different key');
+  });
+
+  test('accepts a plain number[] salt (equivalent to Uint8Array)', () => {
+    const key1 = qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, P, DKLEN);
+    const key2 = qcsdk.scryptDeriveKey('test-passphrase-123', Array.from(SALT), N, R, P, DKLEN);
+    assert.deepEqual(key1, key2, 'number[] and Uint8Array salt must match');
+  });
+
+  test('matches known-answer vector', () => {
+    const key = qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, P, DKLEN);
+    assert.equal(
+      toBase64(key),
+      'YCJuvOP0hUtJpNfmRp7PMP5Evkr4gXFUXPKl4zaXnHo=',
+      'derived key must match the hardcoded vector'
+    );
+  });
+
+  test('returns null for a null secret', () => {
+    assert.equal(qcsdk.scryptDeriveKey(null, SALT, N, R, P, DKLEN), null);
+  });
+
+  test('returns null for a non-string secret', () => {
+    assert.equal(qcsdk.scryptDeriveKey(12345, SALT, N, R, P, DKLEN), null);
+  });
+
+  test('returns null for a null salt', () => {
+    assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', null, N, R, P, DKLEN), null);
+  });
+
+  test('returns null for a non-array salt', () => {
+    assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', {}, N, R, P, DKLEN), null);
+  });
+
+  describe('unsupported parameters return null', () => {
+    test('returns null for an unsupported N', () => {
+      assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', SALT, 16384, R, P, DKLEN), null);
+    });
+
+    test('returns null for an unsupported r', () => {
+      assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, 16, P, DKLEN), null);
+    });
+
+    test('returns null for an unsupported p', () => {
+      assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, 2, DKLEN), null);
+    });
+
+    test('returns null for an unsupported dkLen', () => {
+      assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', SALT, N, R, P, 64), null);
+    });
+
+    test('returns null for a non-number N (null)', () => {
+      assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', SALT, null, R, P, DKLEN), null);
+    });
+
+    test('returns null for a non-number N (string)', () => {
+      assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', SALT, '262144', R, P, DKLEN), null);
+    });
+
+    test('returns null when parameters are omitted', () => {
+      assert.equal(qcsdk.scryptDeriveKey('test-passphrase-123', SALT), null);
+    });
+  });
+});