@mybucks.online/core 1.0.11 → 1.1.0

package/README.md

@@ -4,11 +4,11 @@ This is a core part of [mybucks.online](https://mybucks.online) crypto wallet, i
 
 ## mybucks.online
 
-[Mybucks.online](https://mybucks.online) is a **seedless, disposable crypto wallet** designed for **speed and convenience**. It generates a private key from your password and passcode using an industry-standard, verified **one-way hash function**. Your private key forms your account, allowing you to transfer, receive, and hold your crypto assets instantly.
+[Mybucks.online](https://mybucks.online) is a **seedless, disposable crypto wallet** designed for **speed and convenience**. It generates a private key from your **passphrase and PIN** using an industry-standard, verified **one-way hash function**. Your private key forms your account, allowing you to transfer, receive, and hold your crypto assets instantly.
 
-As a hash function, the **scrypt** Key Derivation Function (KDF) increases the computational effort required to crack passwords, effectively delaying **brute-force** attacks and making them impractical.
+As a hash function, the **Scrypt** Key Derivation Function (KDF) increases the computational effort required to crack credentials, effectively delaying **brute-force** attacks and making them impractical.
 
-It fully runs on your **browser side** without using any storage or invoking any 3rd-party APIs for key management. It instantly generates your private key from your password input, and whenever you close or refresh, there is **no footprint**. This absolutely protects your privacy.
+It fully runs on your **browser side** without using any storage or invoking any 3rd-party APIs for key management. It instantly generates your private key from your credentials input, and whenever you close or refresh, there is **no footprint**. This absolutely protects your privacy.
 
 ### Zero Footprint  
 - No servers, no databases, no storage and no tracking.
@@ -19,7 +19,7 @@ It fully runs on your **browser side** without using any storage or invoking any
 ### Fast and Easy
 - No app installs, no browser extensions, no registration and no KYC.
 - You can create or open your wallet in seconds - all you need is your browser.
-- Password is easier to handle and remember than seed phrases
+- Passphrase is easier to handle and remember than seed phrases.
 
 ### 1-Click Gifting
 - Stop asking your friends for their wallet addresses.
@@ -51,7 +51,7 @@ const showProgress = (p) => {
   console.log(`progress: ${p * 100}%`);
 };
 
-const hash = await generateHash(password, passcode, showProgress);
+const hash = await generateHash(passphrase, pin, showProgress);
 
 const privateKey = getEvmPrivateKey(hash);
 console.log("Private key: ", privateKey);
@@ -66,15 +66,15 @@ console.log("TRON Address: ", address2);
 ### 3. Generate and parse (transfer-link's)token
 ```javascript
 import { generateToken } from "@mybucks.online/core";
-const token = generateToken(password, passcode, network);
+const token = generateToken(passphrase, pin, network);
 
 console.log("https://app.mybucks.online/#wallet=" + token);
 ```
 
 ```javascript
 import { parseToken } from "@mybucks.online/core";
-const [password, passcode, network] = parseToken(token);
-console.log("Account credentials are: ", password, passcode);
+const [passphrase, pin, network] = parseToken(token);
+console.log("Account credentials are: ", passphrase, pin);
 console.log("Network: ", network);
 ```
 
@@ -91,8 +91,8 @@ Find the docs [here](https://docs.mybucks.online).
 
 - https://github.com/mybucks-online/app
 - https://app.mybucks.online  
-  password: **DemoAccount5&**  
-  passcode: **112324**
+  passphrase: **DemoAccount5&**  
+  PIN: **112324**
 - https://app.mybucks.online/#wallet=VWnsSGRGVtb0FjY291bnQ1JgIxMTIzMjQCb3B0aW1pc20=_wNovT
 - https://app.mybucks.online/#wallet=1jpFD8RGVtb0FjY291bnQ1JgIxMTIzMjQCYmFzZQ==fhk-GL
 - https://codesandbox.io/p/sandbox/mybucks-online-key-generation-sandbox-lt53c3

package/index.js

@@ -3,6 +3,7 @@ import { ethers } from "ethers";
 import scryptJS from "scrypt-js";
 import { nanoid } from "nanoid";
 import { TronWeb } from "tronweb";
+import zxcvbn from "zxcvbn";
 
 const { scrypt } = scryptJS;
 const abi = new ethers.AbiCoder();
@@ -15,21 +16,32 @@ const HASH_OPTIONS = {
 };
 
 /**
- * This function computes the scrypt hash using provided password and passcode inputs.
+ * This function computes the scrypt hash using provided passphrase and pin inputs.
+ * Passphrase and pin are validated with zxcvbn; weak values are rejected (returns "").
  *
- * @param {*} password
- * @param {*} passcode
+ * @param {*} passphrase - Must have zxcvbn score >= 3
+ * @param {*} pin - Must have zxcvbn score >= 1
  * @param {*} cb a callback function designed to receive the progress updates during the scrypt hashing process.
- * @returns hash result as string format
+ * @returns hash result as string format, or "" if passphrase/pin missing or too weak
  */
-export async function generateHash(password, passcode, cb = () => {}) {
-  if (!password || !passcode) {
+export async function generateHash(passphrase, pin, cb = () => {}) {
+  if (!passphrase || !pin) {
     return "";
   }
 
-  const salt = `${password.slice(-4)}${passcode}`;
+  const passphraseResult = zxcvbn(passphrase);
+  if (passphraseResult.score < 3) {
+    return "";
+  }
+
+  const pinResult = zxcvbn(pin);
+  if (pinResult.score < 1) {
+    return "";
+  }
+
+  const salt = `${passphrase.slice(-4)}${pin}`;
 
-  const passwordBuffer = Buffer.from(password);
+  const passwordBuffer = Buffer.from(passphrase);
   const saltBuffer = Buffer.from(salt);
 
   const hashBuffer = await scrypt(
@@ -87,23 +99,32 @@ const NETWORKS = [
   "tron",
 ];
 /**
- * This function generates a transfer-link by combining credentials and randomly generated padding.
- * The transfer-link introduces a nice feature that enables the transfer of full ownership of a wallet account.
- * @param {*} password
- * @param {*} passcode
+ * This function generates a transfer-link token by encoding passphrase and PIN by Base64 and adding random padding.
+ * The transfer-link enables users to send their full ownership of a wallet account to another user for gifting or airdropping.
+ * Passphrase and PIN are validated with zxcvbn; weak values are rejected (returns null).
+ *
+ * @param {*} passphrase - Must have zxcvbn score >= 3
+ * @param {*} PIN - Must have zxcvbn score >= 1
  * @param {*} network ethereum | polygon | arbitrum | optimism | bsc | avalanche | base | tron
- * @returns A string formatted as a transfer-link token, which can be appended to `https://app.mybucks.online?wallet=`
+ * @returns A string formatted as a transfer-link token, which can be appended to `https://app.mybucks.online#wallet=`, or null if invalid/weak
  */
-export function generateToken(password, passcode, network) {
-  if (!password || !passcode || !network) {
+export function generateToken(passphrase, pin, network) {
+  if (!passphrase || !pin || !network) {
     return null;
   }
   if (!NETWORKS.find((n) => n === network)) {
     return null;
   }
 
+  if (zxcvbn(passphrase).score < 3) {
+    return null;
+  }
+  if (zxcvbn(pin).score < 1) {
+    return null;
+  }
+
   const merged = Buffer.from(
-    password + URL_DELIMITER + passcode + URL_DELIMITER + network,
+    passphrase + URL_DELIMITER + pin + URL_DELIMITER + network,
     "utf-8"
   );
   const base64Encoded = merged.toString("base64");
@@ -114,11 +135,11 @@ export function generateToken(password, passcode, network) {
 /**
  * This function parses a transfer-link token generated by generateToken().
  * @param {*} token
- * @returns an array of strings, including the password, passcode and network.
+ * @returns an array of strings, including the passphrase, pin and network.
  */
 export function parseToken(token) {
   const payload = token.slice(6, token.length - 6);
   const base64Decoded = Buffer.from(payload, "base64").toString("utf-8");
-  const [password, passcode, network] = base64Decoded.split(URL_DELIMITER);
-  return [password, passcode, network];
+  const [passphrase, pin, network] = base64Decoded.split(URL_DELIMITER);
+  return [passphrase, pin, network];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mybucks.online/core",
-  "version": "1.0.11",
+  "version": "1.1.0",
   "description": "Core module of Mybucks.online Crypto Wallet",
   "main": "index.js",
   "type": "module",
@@ -38,6 +38,7 @@
     "ethers": "^6.13.5",
     "nanoid": "^5.0.9",
     "scrypt-js": "^3.0.1",
-    "tronweb": "^6.0.1"
+    "tronweb": "^6.0.1",
+    "zxcvbn": "^4.4.2"
   }
 }

package/test/index.test.js

@@ -9,8 +9,8 @@ import {
   parseToken,
 } from "../index.js";
 
-const DEMO_PASSWORD = "DemoAccount5&";
-const DEMO_PASSCODE = "112324";
+const DEMO_PASSPHRASE = "DemoAccount5&";
+const DEMO_PIN = "112324";
 const DEMO_NETWORK = "optimism";
 
 const DEMO_HASH =
@@ -24,20 +24,54 @@ const DEMO_TRANSFER_TOKEN =
   "VWnsSGRGVtb0FjY291bnQ1JgIxMTIzMjQCb3B0aW1pc20=_wNovT";
 
 describe("generateHash", () => {
-  test("should return empty string if password or passcode is blank", async () => {
+  test("should return empty string if passphrase or pin is blank", async () => {
     const hash = await generateHash("", "");
     assert.strictEqual(hash, "");
   });
 
+  test("should return empty string for weak passphrase (zxcvbn score < 3)", async () => {
+    const weakPassphrases = [
+      "password",
+      "asdfasdf",
+      "123123123",
+      "P@ssw0rd",
+      "London123",
+      "oxford2024",
+      "John19821012",
+      "asdfASDFaSdf",
+      "qwerqwerqwer",
+      "1234567890",
+      "Julia18921012",
+    ];
+    for (const passphrase of weakPassphrases) {
+      const hash = await generateHash(passphrase, DEMO_PIN);
+      assert.strictEqual(hash, "");
+    }
+  });
+
+  test("should return empty string for weak pin (zxcvbn score < 1)", async () => {
+    const weakPins = [
+      "111111",
+      "111111111111111",
+      "12341234",
+      "aaaaaaaaaa",
+      "asdfasdf",
+    ];
+    for (const pin of weakPins) {
+      const hash = await generateHash(DEMO_PASSPHRASE, pin);
+      assert.strictEqual(hash, "", `Expected "" for weak pin "${pin}"`);
+    }
+  });
+
   test("should return scrypt hash result", async () => {
-    const hash = await generateHash(DEMO_PASSWORD, DEMO_PASSCODE);
+    const hash = await generateHash(DEMO_PASSPHRASE, DEMO_PIN);
     assert.strictEqual(hash, DEMO_HASH);
   });
 });
 
 describe("getEvmPrivateKey", () => {
   test("should return 256bit private key", async () => {
-    const hash = await generateHash(DEMO_PASSWORD, DEMO_PASSCODE);
+    const hash = await generateHash(DEMO_PASSPHRASE, DEMO_PIN);
     const privateKey = getEvmPrivateKey(hash);
 
     assert.strictEqual(privateKey, DEMO_PRIVATE_KEY);
@@ -46,7 +80,7 @@ describe("getEvmPrivateKey", () => {
 
 describe("getEvmWalletAddress", () => {
   test("should return a valid wallet address", async () => {
-    const hash = await generateHash(DEMO_PASSWORD, DEMO_PASSCODE);
+    const hash = await generateHash(DEMO_PASSPHRASE, DEMO_PIN);
     const address = getEvmWalletAddress(hash);
 
     assert.strictEqual(address, DEMO_WALLET_EVM_ADDRESS);
@@ -55,7 +89,7 @@ describe("getEvmWalletAddress", () => {
 
 describe("getTronWalletAddress", () => {
   test("should return a valid wallet address", async () => {
-    const hash = await generateHash(DEMO_PASSWORD, DEMO_PASSCODE);
+    const hash = await generateHash(DEMO_PASSPHRASE, DEMO_PIN);
     const address = getTronWalletAddress(hash);
 
     assert.strictEqual(address, DEMO_WALLET_TRON_ADDRESS);
@@ -63,16 +97,52 @@ describe("getTronWalletAddress", () => {
 });
 
 describe("generateToken", () => {
-  test("should return null if password, passcode or network is invalid", () => {
+  test("should return null if passphrase, pin or network is invalid", () => {
     assert.strictEqual(generateToken("", "123345", "ethereum"), null);
     assert.strictEqual(generateToken("", "123345"), null);
-    assert.strictEqual(generateToken("password", "", "ethereum"), null);
-    assert.strictEqual(generateToken("password", "123456", ""), null);
-    assert.strictEqual(generateToken("password", "123456", "invalid"), null);
+    assert.strictEqual(generateToken("passphrase", "", "ethereum"), null);
+    assert.strictEqual(generateToken("passphrase", "123456", ""), null);
+    assert.strictEqual(generateToken("passphrase", "123456", "invalid"), null);
+  });
+
+  test("should return null for weak passphrase (zxcvbn score < 3)", () => {
+    const weakPassphrases = [
+      "password",
+      "asdfasdf",
+      "123123123",
+      "P@ssw0rd",
+      "London123",
+      "oxford2024",
+      "asdfASDFaSdf",
+      "qwerqwerqwer",
+      "1234567890",
+    ];
+    for (const passphrase of weakPassphrases) {
+      assert.strictEqual(
+        generateToken(passphrase, DEMO_PIN, DEMO_NETWORK),
+        null
+      );
+    }
+  });
+
+  test("should return null for weak pin (zxcvbn score < 1)", () => {
+    const weakPins = [
+      "111111",
+      "111111111111111",
+      "12341234",
+      "aaaaaaaaaa",
+      "asdfasdf",
+    ];
+    for (const pin of weakPins) {
+      assert.strictEqual(
+        generateToken(DEMO_PASSPHRASE, pin, DEMO_NETWORK),
+        null
+      );
+    }
   });
 
   test("should return valid token", async () => {
-    const token = generateToken(DEMO_PASSWORD, DEMO_PASSCODE, DEMO_NETWORK);
+    const token = generateToken(DEMO_PASSPHRASE, DEMO_PIN, DEMO_NETWORK);
 
     // The first and last 6 characters serve as random padding.
     assert.strictEqual(
@@ -83,60 +153,60 @@ describe("generateToken", () => {
 
   test("should return valid token for all networks", async () => {
     assert.notStrictEqual(
-      generateToken(DEMO_PASSWORD, DEMO_PASSCODE, "ethereum"),
+      generateToken(DEMO_PASSPHRASE, DEMO_PIN, "ethereum"),
       null
     );
     assert.notStrictEqual(
-      generateToken(DEMO_PASSWORD, DEMO_PASSCODE, "polygon"),
+      generateToken(DEMO_PASSPHRASE, DEMO_PIN, "polygon"),
       null
     );
     assert.notStrictEqual(
-      generateToken(DEMO_PASSWORD, DEMO_PASSCODE, "arbitrum"),
+      generateToken(DEMO_PASSPHRASE, DEMO_PIN, "arbitrum"),
       null
     );
     assert.notStrictEqual(
-      generateToken(DEMO_PASSWORD, DEMO_PASSCODE, "optimism"),
+      generateToken(DEMO_PASSPHRASE, DEMO_PIN, "optimism"),
       null
     );
     assert.notStrictEqual(
-      generateToken(DEMO_PASSWORD, DEMO_PASSCODE, "bsc"),
+      generateToken(DEMO_PASSPHRASE, DEMO_PIN, "bsc"),
       null
     );
     assert.notStrictEqual(
-      generateToken(DEMO_PASSWORD, DEMO_PASSCODE, "avalanche"),
+      generateToken(DEMO_PASSPHRASE, DEMO_PIN, "avalanche"),
       null
     );
     assert.notStrictEqual(
-      generateToken(DEMO_PASSWORD, DEMO_PASSCODE, "base"),
+      generateToken(DEMO_PASSPHRASE, DEMO_PIN, "base"),
       null
     );
     assert.notStrictEqual(
-      generateToken(DEMO_PASSWORD, DEMO_PASSCODE, "tron"),
+      generateToken(DEMO_PASSPHRASE, DEMO_PIN, "tron"),
       null
     );
   });
 });
 
 describe("parseToken", () => {
-  test("should return array of password, passcode, and network", () => {
-    const [password, passcode, network] = parseToken(DEMO_TRANSFER_TOKEN);
+  test("should return array of passphrase, pin, and network", () => {
+    const [passphrase, pin, network] = parseToken(DEMO_TRANSFER_TOKEN);
 
-    assert.strictEqual(password, DEMO_PASSWORD);
-    assert.strictEqual(passcode, DEMO_PASSCODE);
+    assert.strictEqual(passphrase, DEMO_PASSPHRASE);
+    assert.strictEqual(pin, DEMO_PIN);
     assert.strictEqual(network, DEMO_NETWORK);
   });
 });
 
 describe("generateToken and parseToken", () => {
   test("should be compatible and return correct result", () => {
-    const testPassword = "random^Password9";
-    const testPasscode = "909011";
+    const testPassphrase = "My-1st-car-was-a-red-Ford-2005!";
+    const testPin = "909011";
     const testNetwork = "polygon";
-    const token = generateToken(testPassword, testPasscode, testNetwork);
+    const token = generateToken(testPassphrase, testPin, testNetwork);
 
-    const [password, passcode, network] = parseToken(token);
-    assert.strictEqual(password, testPassword);
-    assert.strictEqual(passcode, testPasscode);
+    const [passphrase, pin, network] = parseToken(token);
+    assert.strictEqual(passphrase, testPassphrase);
+    assert.strictEqual(pin, testPin);
     assert.strictEqual(network, testNetwork);
   });
 });