@mybucks.online/core 2.0.0 → 2.2.0

package/README.md

@@ -85,6 +85,19 @@ console.log("Network: ", network);
 console.log("Legacy token: ", legacy); // true if token was in legacy format
 ```
 
+### 4. Generate random credentials
+
+`randomPassphrase` and `randomPIN` generate cryptographically random credentials that are guaranteed to pass the zxcvbn strength thresholds required by `generateHash` (`PASSPHRASE_MIN_ZXCVBN_SCORE = 3`, `PIN_MIN_ZXCVBN_SCORE = 1`).
+
+```javascript
+import { randomPassphrase, randomPIN } from "@mybucks.online/core";
+
+const passphrase = randomPassphrase(); // e.g. "Ax3!-bQ2#-mK7@-zP1$"
+const pin = randomPIN();               // e.g. "k4r9w2"
+
+const hash = await generateHash(passphrase, pin, showProgress);
+```
+
 ## Changes (default vs legacy)
 
 To make the wallet more secure and resilient against attacks, and to meet standards and follow best practices (e.g. NIST SP 800-132, OWASP, RFC 7914), we introduced a new version that is now the default. A **`legacy`** flag is available for backward compatibility with existing wallets and tokens.
@@ -99,7 +112,7 @@ To make the wallet more secure and resilient against attacks, and to meet standa
 
 **Token generation (default)**  
 - Legacy encoded the transfer-link token by **concatenating** passphrase, pin and network with a delimiter, which is ambiguous for some inputs.  
-- The default uses **ABI encoding** for the payload so there is no concatenation ambiguity.  
+- The default uses a **compact length-prefixed** payload (version byte + lengths + UTF-8 bytes) so there is no concatenation ambiguity and the URL fragment stays short.  
 - `parseToken` accepts both legacy and default token formats automatically and returns `[passphrase, pin, network, legacy]`, where `legacy` is `true` if the token was in legacy format.
 
 Use `generateHash(passphrase, pin, cb, true)` or `generateToken(passphrase, pin, network, true)` only when you need to match existing legacy wallets or tokens.
@@ -119,6 +132,6 @@ Find the docs [here](https://docs.mybucks.online).
 - https://app.mybucks.online  
   passphrase: **DemoAccount5&**  
   PIN: **112324**
-- https://app.mybucks.online/#wallet=VWnsSGRGVtb0FjY291bnQ1JgIxMTIzMjQCb3B0aW1pc20=_wNovT
-- https://app.mybucks.online/#wallet=1jpFD8RGVtb0FjY291bnQ1JgIxMTIzMjQCYmFzZQ==fhk-GL
+- https://app.mybucks.online/#wallet=Db1zfXAg1EZW1vQWNjb3VudDUmBjExMjMyNAhvcHRpbWlzbQ==mlUEbO (default)
+- https://app.mybucks.online/#wallet=VWnsSGRGVtb0FjY291bnQ1JgIxMTIzMjQCb3B0aW1pc20=_wNovT (legacy)
 - https://codesandbox.io/p/sandbox/mybucks-online-key-generation-sandbox-lt53c3

package/index.js

@@ -1,234 +1,16 @@
-import { Buffer } from "buffer";
-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();
-
-// Domain separator for the default (non-legacy) KDF path to prevent
-// cross-protocol and cross-version hash reuse.
-const KDF_DOMAIN_SEPARATOR = "mybucks.online-core.generateHash.v2";
-
-const HASH_OPTIONS_LEGACY = {
-  N: 32768, // CPU/memory cost parameter, 2^15
-  r: 8, // block size parameter
-  p: 5, // parallelization parameter
-  keyLen: 64,
-};
-
-const HASH_OPTIONS = {
-  N: 131072, // CPU/memory cost parameter, 2^17, OWASP recommendation
-  r: 8, // block size parameter
-  p: 1, // parallelization parameter
-  keyLen: 64,
-};
-
-export const PASSPHRASE_MIN_LENGTH = 12;
-export const PASSPHRASE_MAX_LENGTH = 128;
-export const PIN_MIN_LENGTH = 6;
-export const PIN_MAX_LENGTH = 16;
-
-/**
- * This function computes the scrypt hash using provided passphrase and pin inputs.
- * Passphrase and pin are validated by length (see PASSPHRASE_MIN/MAX_LENGTH, PIN_MIN/MAX_LENGTH) and zxcvbn; invalid or weak values are rejected (returns "").
- *
- * @param {string} passphrase - Length in [PASSPHRASE_MIN_LENGTH, PASSPHRASE_MAX_LENGTH], zxcvbn score >= 3
- * @param {string} pin - Length in [PIN_MIN_LENGTH, PIN_MAX_LENGTH], zxcvbn score >= 1
- * @param {*} cb a callback function designed to receive the progress updates during the scrypt hashing process.
- * @param {boolean} legacy - when true, uses the legacy behavior (HASH_OPTIONS_LEGACY and the original salt generation using the last 4 characters of passphrase plus the full pin); when false, uses HASH_OPTIONS and a keccak256-based salt derived from ABI-encoding passphrase and pin
- * @returns hash result as string format, or "" if passphrase/pin missing or too weak
- */
-export async function generateHash(
-  passphrase,
-  pin,
-  cb = () => {},
-  legacy = false,
-) {
-  if (!passphrase || !pin) {
-    return "";
-  }
-
-  const passphraseLen = passphrase.length;
-  if (
-    passphraseLen < PASSPHRASE_MIN_LENGTH ||
-    passphraseLen > PASSPHRASE_MAX_LENGTH
-  ) {
-    return "";
-  }
-
-  const pinLen = pin.length;
-  if (pinLen < PIN_MIN_LENGTH || pinLen > PIN_MAX_LENGTH) {
-    return "";
-  }
-
-  const passphraseResult = zxcvbn(passphrase);
-  if (passphraseResult.score < 3) {
-    return "";
-  }
-
-  const pinResult = zxcvbn(pin);
-  if (pinResult.score < 1) {
-    return "";
-  }
-
-  const passwordBuffer = Buffer.from(passphrase);
-  let saltBuffer;
-
-  if (legacy) {
-    const legacySalt = `${passphrase.slice(-4)}${pin}`;
-    saltBuffer = Buffer.from(legacySalt);
-  } else {
-    const encoded = abi.encode(
-      ["string", "string", "string"],
-      [KDF_DOMAIN_SEPARATOR, passphrase, pin],
-    );
-    const saltHash = ethers.keccak256(encoded);
-    saltBuffer = Buffer.from(saltHash.slice(2), "hex");
-  }
-
-  const options = legacy ? HASH_OPTIONS_LEGACY : HASH_OPTIONS;
-
-  const hashBuffer = await scrypt(
-    passwordBuffer,
-    saltBuffer,
-    options.N,
-    options.r,
-    options.p,
-    options.keyLen,
-    cb,
-  );
-
-  return Buffer.from(hashBuffer).toString("hex");
-}
-
-/**
- * This function derives the EVM private key from a result of the scrypt hash.
- * @param {*} hash scrypt hash result
- * @returns private key as string format
- */
-export function getEvmPrivateKey(hash) {
-  return ethers.keccak256(abi.encode(["string"], [hash]));
-}
-
-/**
- * This function returns the EVM wallet address from a result of the scrypt hash.
- * @param {*} hash scrypt hash result
- * @returns address as string format
- */
-export function getEvmWalletAddress(hash) {
-  const privateKey = getEvmPrivateKey(hash);
-  const wallet = new ethers.Wallet(privateKey);
-  return wallet.address;
-}
-
-/**
- * This function returns the TRON wallet address from a result of the scrypt hash.
- * @param {*} hash scrypt hash result
- * @returns address as string format
- */
-export function getTronWalletAddress(hash) {
-  const privateKey = getEvmPrivateKey(hash);
-  return TronWeb.address.fromPrivateKey(privateKey.slice(2));
-}
-
-const URL_DELIMITER = "\u0002";
-const TOKEN_VERSION_ABI = 0x02;
-
-const NETWORKS = [
-  "ethereum",
-  "polygon",
-  "arbitrum",
-  "optimism",
-  "bsc",
-  "avalanche",
-  "base",
-  "tron",
-];
-/**
- * This function generates a transfer-link token by encoding passphrase, pin and network, 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 by length (see PASSPHRASE_MIN/MAX_LENGTH, PIN_MIN/MAX_LENGTH) and zxcvbn; invalid or weak values are rejected (returns null).
- * When legacy is false, payload is ABI-encoded to avoid concatenation ambiguity; when true, uses URL_DELIMITER concatenation.
- *
- * @param {string} passphrase - Length in [PASSPHRASE_MIN_LENGTH, PASSPHRASE_MAX_LENGTH], zxcvbn score >= 3
- * @param {string} pin - Length in [PIN_MIN_LENGTH, PIN_MAX_LENGTH], zxcvbn score >= 1
- * @param {string} network - ethereum | polygon | arbitrum | optimism | bsc | avalanche | base | tron
- * @param {boolean} legacy - when true, use URL_DELIMITER concatenation; when false, use ABI encoding for the payload
- * @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(passphrase, pin, network, legacy = false) {
-  if (!passphrase || !pin || !network) {
-    return null;
-  }
-  if (!NETWORKS.find((n) => n === network)) {
-    return null;
-  }
-
-  const passphraseLen = passphrase.length;
-  if (
-    passphraseLen < PASSPHRASE_MIN_LENGTH ||
-    passphraseLen > PASSPHRASE_MAX_LENGTH
-  ) {
-    return null;
-  }
-
-  const pinLen = pin.length;
-  if (pinLen < PIN_MIN_LENGTH || pinLen > PIN_MAX_LENGTH) {
-    return null;
-  }
-
-  if (zxcvbn(passphrase).score < 3) {
-    return null;
-  }
-  if (zxcvbn(pin).score < 1) {
-    return null;
-  }
-
-  let payloadBuffer;
-  if (legacy) {
-    payloadBuffer = Buffer.from(
-      passphrase + URL_DELIMITER + pin + URL_DELIMITER + network,
-      "utf-8",
-    );
-  } else {
-    const encoded = abi.encode(
-      ["string", "string", "string"],
-      [passphrase, pin, network],
-    );
-    const encodedBuffer = Buffer.from(encoded.slice(2), "hex");
-    payloadBuffer = Buffer.concat([
-      Buffer.from([TOKEN_VERSION_ABI]),
-      encodedBuffer,
-    ]);
-  }
-
-  const base64Encoded = payloadBuffer.toString("base64");
-  const padding = nanoid(12);
-  return padding.slice(0, 6) + base64Encoded + padding.slice(6);
-}
-
-/**
- * This function parses a transfer-link token generated by generateToken().
- * Tokens with version byte 0x02 are ABI-decoded; otherwise payload is treated as legacy (UTF-8 + URL_DELIMITER).
- * @param {string} token - token string returned by generateToken()
- * @returns {[string, string, string, boolean]} [passphrase, pin, network, legacy] - legacy is true if token was in legacy format, false if ABI-encoded
- */
-export function parseToken(token) {
-  const payload = token.slice(6, token.length - 6);
-  const decoded = Buffer.from(payload, "base64");
-
-  if (decoded[0] === TOKEN_VERSION_ABI) {
-    const hex = "0x" + decoded.subarray(1).toString("hex");
-    const [passphrase, pin, network] = abi.decode(
-      ["string", "string", "string"],
-      hex,
-    );
-    return [passphrase, pin, network, false];
-  }
-  const str = decoded.toString("utf-8");
-  const [passphrase, pin, network] = str.split(URL_DELIMITER);
-  return [passphrase, pin, network, true];
-}
+export {
+  PASSPHRASE_MIN_ZXCVBN_SCORE,
+  PIN_MIN_ZXCVBN_SCORE,
+  PASSPHRASE_MIN_LENGTH,
+  PASSPHRASE_MAX_LENGTH,
+  PIN_MIN_LENGTH,
+  PIN_MAX_LENGTH,
+  generateHash,
+  getEvmPrivateKey,
+  getEvmWalletAddress,
+  getTronWalletAddress,
+} from "./src/credentials.js";
+
+export { generateToken, parseToken } from "./src/token.js";
+
+export { randomPassphrase, randomPIN } from "./src/random.js";

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@mybucks.online/core",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Core module of Mybucks.online Crypto Wallet",
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "test": "node test/index.test.js && node test/legacy.test.js"
+    "test": "node test/index.test.js && node test/legacy.test.js && node test/random.test.js"
   },
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
     "ethers": "^6.13.5",
     "nanoid": "^5.0.9",
     "scrypt-js": "^3.0.1",
-    "tronweb": "^6.0.1",
+    "tronweb": "^6.2.2",
     "zxcvbn": "^4.4.2"
   }
 }

package/src/credentials.js

@@ -0,0 +1,137 @@
+import { Buffer } from "buffer";
+import { ethers } from "ethers";
+import scryptJS from "scrypt-js";
+import { TronWeb } from "tronweb";
+import zxcvbn from "zxcvbn";
+
+const { scrypt } = scryptJS;
+const abi = new ethers.AbiCoder();
+
+// Domain separator for the default (non-legacy) KDF path to prevent
+// cross-protocol and cross-version hash reuse.
+const KDF_DOMAIN_SEPARATOR = "mybucks.online-core.generateHash.v2";
+
+const HASH_OPTIONS_LEGACY = {
+  N: 32768, // CPU/memory cost parameter, 2^15
+  r: 8, // block size parameter
+  p: 5, // parallelization parameter
+  keyLen: 64,
+};
+
+const HASH_OPTIONS = {
+  N: 131072, // CPU/memory cost parameter, 2^17, OWASP recommendation
+  r: 8, // block size parameter
+  p: 1, // parallelization parameter
+  keyLen: 64,
+};
+
+export const PASSPHRASE_MIN_ZXCVBN_SCORE = 3;
+export const PIN_MIN_ZXCVBN_SCORE = 1;
+
+export const PASSPHRASE_MIN_LENGTH = 12;
+export const PASSPHRASE_MAX_LENGTH = 128;
+export const PIN_MIN_LENGTH = 6;
+export const PIN_MAX_LENGTH = 16;
+
+/**
+ * This function computes the scrypt hash using provided passphrase and pin inputs.
+ * Passphrase and pin are validated by length (see PASSPHRASE_MIN/MAX_LENGTH, PIN_MIN/MAX_LENGTH) and zxcvbn; invalid or weak values are rejected (returns "").
+ *
+ * @param {string} passphrase - Length in [PASSPHRASE_MIN_LENGTH, PASSPHRASE_MAX_LENGTH], zxcvbn score >= 3
+ * @param {string} pin - Length in [PIN_MIN_LENGTH, PIN_MAX_LENGTH], zxcvbn score >= 1
+ * @param {*} cb a callback function designed to receive the progress updates during the scrypt hashing process.
+ * @param {boolean} legacy - when true, uses the legacy behavior (HASH_OPTIONS_LEGACY and the original salt generation using the last 4 characters of passphrase plus the full pin); when false, uses HASH_OPTIONS and a keccak256-based salt derived from ABI-encoding passphrase and pin
+ * @returns hash result as string format, or "" if passphrase/pin missing or too weak
+ */
+export async function generateHash(
+  passphrase,
+  pin,
+  cb = () => {},
+  legacy = false,
+) {
+  if (!passphrase || !pin) {
+    return "";
+  }
+
+  const passphraseLen = passphrase.length;
+  if (
+    passphraseLen < PASSPHRASE_MIN_LENGTH ||
+    passphraseLen > PASSPHRASE_MAX_LENGTH
+  ) {
+    return "";
+  }
+
+  const pinLen = pin.length;
+  if (pinLen < PIN_MIN_LENGTH || pinLen > PIN_MAX_LENGTH) {
+    return "";
+  }
+
+  const passphraseResult = zxcvbn(passphrase);
+  if (passphraseResult.score < PASSPHRASE_MIN_ZXCVBN_SCORE) {
+    return "";
+  }
+
+  const pinResult = zxcvbn(pin);
+  if (pinResult.score < PIN_MIN_ZXCVBN_SCORE) {
+    return "";
+  }
+
+  const passwordBuffer = Buffer.from(passphrase);
+  let saltBuffer;
+
+  if (legacy) {
+    const legacySalt = `${passphrase.slice(-4)}${pin}`;
+    saltBuffer = Buffer.from(legacySalt);
+  } else {
+    const encoded = abi.encode(
+      ["string", "string", "string"],
+      [KDF_DOMAIN_SEPARATOR, passphrase, pin],
+    );
+    const saltHash = ethers.keccak256(encoded);
+    saltBuffer = Buffer.from(saltHash.slice(2), "hex");
+  }
+
+  const options = legacy ? HASH_OPTIONS_LEGACY : HASH_OPTIONS;
+
+  const hashBuffer = await scrypt(
+    passwordBuffer,
+    saltBuffer,
+    options.N,
+    options.r,
+    options.p,
+    options.keyLen,
+    cb,
+  );
+
+  return Buffer.from(hashBuffer).toString("hex");
+}
+
+/**
+ * This function derives the EVM private key from a result of the scrypt hash.
+ * @param {*} hash scrypt hash result
+ * @returns private key as string format
+ */
+export function getEvmPrivateKey(hash) {
+  return ethers.keccak256(abi.encode(["string"], [hash]));
+}
+
+/**
+ * This function returns the EVM wallet address from a result of the scrypt hash.
+ * @param {*} hash scrypt hash result
+ * @returns address as string format
+ */
+export function getEvmWalletAddress(hash) {
+  const privateKey = getEvmPrivateKey(hash);
+  const wallet = new ethers.Wallet(privateKey);
+  return wallet.address;
+}
+
+/**
+ * This function returns the TRON wallet address from a result of the scrypt hash.
+ * @param {*} hash scrypt hash result
+ * @returns address as string format
+ */
+export function getTronWalletAddress(hash) {
+  const privateKey = getEvmPrivateKey(hash);
+  return TronWeb.address.fromPrivateKey(privateKey.slice(2));
+}

package/src/random.js

@@ -0,0 +1,58 @@
+import { randomInt } from "crypto";
+import zxcvbn from "zxcvbn";
+import {
+  PASSPHRASE_MIN_ZXCVBN_SCORE,
+  PIN_MIN_ZXCVBN_SCORE,
+} from "./credentials.js";
+
+const UPPER = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const LOWER = "abcdefghijklmnopqrstuvwxyz";
+const DIGITS = "0123456789";
+const SYMBOLS = "`~!@#$%^&*()-_+={}[]\\|:;\"'<>,.?/";
+
+function randomChar(charset) {
+  return charset[randomInt(charset.length)];
+}
+
+function generateSegment(length, charset) {
+  return Array.from({ length }, () => randomChar(charset)).join("");
+}
+
+/**
+ * Generates a random passphrase in a UUID-inspired hyphen-separated block format (e.g. "xxxx-xxxx-xxxx-xxxx").
+ * Each block is composed of characters from uppercase, lowercase, digits, and symbols.
+ * Retries recursively until zxcvbn score >= 3 (required by generateHash).
+ *
+ * @param {number} blockLength - Number of characters per block (default: 4)
+ * @param {number} numBlocks - Number of blocks (default: 4)
+ * @returns {string} A randomly generated passphrase string
+ */
+export function randomPassphrase(blockLength = 4, numBlocks = 4) {
+  const segments = Array.from({ length: numBlocks }, () =>
+    generateSegment(blockLength, UPPER + LOWER + DIGITS + SYMBOLS),
+  );
+  const passphrase = segments.join("-");
+
+  if (zxcvbn(passphrase).score < PASSPHRASE_MIN_ZXCVBN_SCORE) {
+    return randomPassphrase(blockLength, numBlocks);
+  }
+
+  return passphrase;
+}
+
+/**
+ * Generates a random PIN composed of digits and lowercase letters.
+ * Retries until the PIN passes zxcvbn score >= 1 (required by generateHash).
+ *
+ * @param {number} length - Number of characters in the PIN (default: 6)
+ * @returns {string} A randomly generated PIN string
+ */
+export function randomPIN(length = 6) {
+  const pin = generateSegment(length, DIGITS + LOWER);
+
+  if (zxcvbn(pin).score < PIN_MIN_ZXCVBN_SCORE) {
+    return randomPIN(length);
+  }
+
+  return pin;
+}

package/src/token.js

@@ -0,0 +1,120 @@
+import { Buffer } from "buffer";
+import { nanoid } from "nanoid";
+import zxcvbn from "zxcvbn";
+import {
+  PASSPHRASE_MIN_LENGTH,
+  PASSPHRASE_MAX_LENGTH,
+  PIN_MIN_LENGTH,
+  PIN_MAX_LENGTH,
+} from "./credentials.js";
+
+const LEGACY_URL_DELIMITER = "\u0002";
+// Version byte for the default (non-legacy) token format.
+// Uses a compact length-prefixed encoding for passphrase, pin and network.
+const TOKEN_VERSION_COMPACT = 0x02;
+
+const NETWORKS = [
+  "ethereum",
+  "polygon",
+  "arbitrum",
+  "optimism",
+  "bsc",
+  "avalanche",
+  "base",
+  "tron",
+];
+
+/**
+ * This function generates a transfer-link token by encoding passphrase, pin and network, 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 by length (see PASSPHRASE_MIN/MAX_LENGTH, PIN_MIN/MAX_LENGTH) and zxcvbn; invalid or weak values are rejected (returns null).
+ * When legacy is false, payload is compact length-prefixed (version 0x02) to avoid concatenation ambiguity and keep the URL fragment short; when true, uses LEGACY_URL_DELIMITER concatenation.
+ *
+ * @param {string} passphrase - Length in [PASSPHRASE_MIN_LENGTH, PASSPHRASE_MAX_LENGTH], zxcvbn score >= 3
+ * @param {string} pin - Length in [PIN_MIN_LENGTH, PIN_MAX_LENGTH], zxcvbn score >= 1
+ * @param {string} network - ethereum | polygon | arbitrum | optimism | bsc | avalanche | base | tron
+ * @param {boolean} legacy - when true, use LEGACY_URL_DELIMITER concatenation; when false, use compact length-prefixed encoding for the payload
+ * @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(passphrase, pin, network, legacy = false) {
+  if (!passphrase || !pin || !network) {
+    return null;
+  }
+  if (!NETWORKS.find((n) => n === network)) {
+    return null;
+  }
+
+  const passphraseLen = passphrase.length;
+  if (
+    passphraseLen < PASSPHRASE_MIN_LENGTH ||
+    passphraseLen > PASSPHRASE_MAX_LENGTH
+  ) {
+    return null;
+  }
+
+  const pinLen = pin.length;
+  if (pinLen < PIN_MIN_LENGTH || pinLen > PIN_MAX_LENGTH) {
+    return null;
+  }
+
+  if (zxcvbn(passphrase).score < 3) {
+    return null;
+  }
+  if (zxcvbn(pin).score < 1) {
+    return null;
+  }
+
+  let payloadBuffer;
+  if (legacy) {
+    payloadBuffer = Buffer.from(
+      passphrase + LEGACY_URL_DELIMITER + pin + LEGACY_URL_DELIMITER + network,
+      "utf-8",
+    );
+  } else {
+    // Default format: compact length-prefixed encoding.
+    const passphraseBytes = Buffer.from(passphrase, "utf-8");
+    const pinBytes = Buffer.from(pin, "utf-8");
+    const networkBytes = Buffer.from(network, "utf-8");
+
+    payloadBuffer = Buffer.concat([
+      Buffer.from([TOKEN_VERSION_COMPACT]),
+      Buffer.from([passphraseBytes.length]),
+      passphraseBytes,
+      Buffer.from([pinBytes.length]),
+      pinBytes,
+      Buffer.from([networkBytes.length]),
+      networkBytes,
+    ]);
+  }
+
+  const base64Encoded = payloadBuffer.toString("base64");
+  const padding = nanoid(12);
+  return padding.slice(0, 6) + base64Encoded + padding.slice(6);
+}
+
+/**
+ * This function parses a transfer-link token generated by generateToken().
+ * Tokens whose payload starts with 0x02 are decoded as compact length-prefixed; otherwise payload is treated as legacy (UTF-8 + LEGACY_URL_DELIMITER).
+ * @param {string} token - token string returned by generateToken()
+ * @returns {[string, string, string, boolean]} [passphrase, pin, network, legacy] - legacy is true if token was in legacy format, false if compact-encoded
+ */
+export function parseToken(token) {
+  const payload = token.slice(6, token.length - 6);
+  const decoded = Buffer.from(payload, "base64");
+
+  if (decoded[0] === TOKEN_VERSION_COMPACT) {
+    let i = 1;
+    const lenP = decoded[i++];
+    const passphrase = decoded.subarray(i, i + lenP).toString("utf-8");
+    i += lenP;
+    const lenI = decoded[i++];
+    const pin = decoded.subarray(i, i + lenI).toString("utf-8");
+    i += lenI;
+    const lenN = decoded[i++];
+    const network = decoded.subarray(i, i + lenN).toString("utf-8");
+    return [passphrase, pin, network, false];
+  }
+  const str = decoded.toString("utf-8");
+  const [passphrase, pin, network] = str.split(LEGACY_URL_DELIMITER);
+  return [passphrase, pin, network, true];
+}

package/test/index.test.js

@@ -21,6 +21,7 @@ const DEMO_WALLET_EVM_ADDRESS = "0xC3Bb18Ed137577e5482fA7C6AEaca8b3F68Dafba";
 const DEMO_WALLET_TRON_ADDRESS = "TTp8uDeig42XdefAoTGWTj61uNMYvEVnXR";
 
 const DEMO_LEGACY_TOKEN = "VWnsSGRGVtb0FjY291bnQ1JgIxMTIzMjQCb3B0aW1pc20=_wNovT";
+const DEMO_DEFAULT_TOKEN = "Db1zfXAg1EZW1vQWNjb3VudDUmBjExMjMyNAhvcHRpbWlzbQ==mlUEbO";
 
 describe("generateHash (default)", () => {
   test("should return empty string if passphrase or pin is blank", async () => {
@@ -282,6 +283,13 @@ describe("generateToken", () => {
       );
     }
   });
+
+  test("should handle passphrase containing URL_DELIMITER when legacy=false", () => {
+    const delimiter = String.fromCharCode(2);
+    const trickyPassphrase = `Demo${delimiter}Account5&`;
+    const token = generateToken(trickyPassphrase, DEMO_PIN, DEMO_NETWORK, false);
+    assert.ok(token !== null);
+  });
 });
 
 describe("parseToken", () => {
@@ -310,6 +318,14 @@ describe("parseToken", () => {
     assert.strictEqual(network, DEMO_NETWORK);
     assert.strictEqual(legacy, true);
   });
+
+  test("should parse DEMO_DEFAULT_TOKEN and return DEMO_PASSPHRASE, DEMO_PIN, DEMO_NETWORK and legacy=false", () => {
+    const [passphrase, pin, network, legacy] = parseToken(DEMO_DEFAULT_TOKEN);
+    assert.strictEqual(passphrase, DEMO_PASSPHRASE);
+    assert.strictEqual(pin, DEMO_PIN);
+    assert.strictEqual(network, DEMO_NETWORK);
+    assert.strictEqual(legacy, false);
+  });
 });
 
 describe("generateToken and parseToken", () => {
@@ -325,6 +341,20 @@ describe("generateToken and parseToken", () => {
     assert.strictEqual(network, testNetwork);
   });
 
+  test("should round-trip passphrase containing URL_DELIMITER when legacy=false", () => {
+    const delimiter = String.fromCharCode(2);
+    const testPassphrase = `My${delimiter}-1st-car-was-a-red-Ford-2005!`;
+    const testPin = "909011";
+    const testNetwork = "polygon";
+    const token = generateToken(testPassphrase, testPin, testNetwork, false);
+
+    const [passphrase, pin, network, legacy] = parseToken(token);
+    assert.strictEqual(passphrase, testPassphrase);
+    assert.strictEqual(pin, testPin);
+    assert.strictEqual(network, testNetwork);
+    assert.strictEqual(legacy, false);
+  });
+
   test("should round-trip when legacy=true", () => {
     const testPassphrase = "My-1st-car-was-a-red-Ford-2005!";
     const testPin = "909011";
@@ -336,4 +366,20 @@ describe("generateToken and parseToken", () => {
     assert.strictEqual(pin, testPin);
     assert.strictEqual(network, testNetwork);
   });
+
+  test("should not safely round-trip passphrase containing URL_DELIMITER when legacy=true", () => {
+    const delimiter = String.fromCharCode(2);
+    const testPassphrase = `My${delimiter}-1st-car-was-a-red-Ford-2005!`;
+    const testPin = "909011";
+    const testNetwork = "polygon";
+    const token = generateToken(testPassphrase, testPin, testNetwork, true);
+
+    const [passphrase, pin, network, legacy] = parseToken(token);
+    assert.notStrictEqual(
+      passphrase,
+      testPassphrase,
+      "legacy format cannot safely encode passphrase containing URL_DELIMITER",
+    );
+    assert.strictEqual(legacy, true);
+  });
 });

package/test/random.test.js

@@ -0,0 +1,84 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import zxcvbn from "zxcvbn";
+import { randomPassphrase, randomPIN } from "../index.js";
+import {
+  PASSPHRASE_MIN_ZXCVBN_SCORE,
+  PIN_MIN_ZXCVBN_SCORE,
+} from "../src/credentials.js";
+
+describe("randomPassphrase", () => {
+  test("should return a string", () => {
+    const passphrase = randomPassphrase();
+    assert.strictEqual(typeof passphrase, "string");
+  });
+
+  test("should have correct total length", () => {
+    const passphrase = randomPassphrase(4, 4);
+    // blockLength * numBlocks + (numBlocks - 1) hyphens as separators
+    assert.strictEqual(passphrase.length, 4 * 4 + 3);
+  });
+
+  test("should respect custom blockLength and numBlocks", () => {
+    const passphrase = randomPassphrase(6, 3);
+    assert.strictEqual(passphrase.length, 6 * 3 + 2);
+  });
+
+  test("should have zxcvbn score >= 3", () => {
+    const passphrase = randomPassphrase();
+    assert.ok(
+      zxcvbn(passphrase).score >= PASSPHRASE_MIN_ZXCVBN_SCORE,
+      `passphrase zxcvbn score is below ${PASSPHRASE_MIN_ZXCVBN_SCORE}`,
+    );
+  });
+
+  test("should return different values on each call", () => {
+    const results = Array.from({ length: 10 }, () => randomPassphrase());
+    results.forEach((p, i) => console.log(`  passphrase[${i}]: ${p}`));
+    assert.strictEqual(
+      new Set(results).size,
+      results.length,
+      "randomPassphrase returned duplicate values",
+    );
+  });
+});
+
+describe("randomPIN", () => {
+  test("should return a string", () => {
+    const pin = randomPIN();
+    assert.strictEqual(typeof pin, "string");
+  });
+
+  test("should default to length 6", () => {
+    const pin = randomPIN();
+    assert.strictEqual(pin.length, 6);
+  });
+
+  test("should respect custom length", () => {
+    const pin = randomPIN(10);
+    assert.strictEqual(pin.length, 10);
+  });
+
+  test("should only contain digits and lowercase letters", () => {
+    const pin = randomPIN(32);
+    assert.ok(/^[0-9a-z]+$/.test(pin), "PIN contains invalid characters");
+  });
+
+  test("should have zxcvbn score >= 1", () => {
+    const pin = randomPIN();
+    assert.ok(
+      zxcvbn(pin).score >= PIN_MIN_ZXCVBN_SCORE,
+      `PIN zxcvbn score is below ${PIN_MIN_ZXCVBN_SCORE}`,
+    );
+  });
+
+  test("should return different values on each call", () => {
+    const results = Array.from({ length: 10 }, () => randomPIN());
+    results.forEach((p, i) => console.log(`  pin[${i}]: ${p}`));
+    assert.strictEqual(
+      new Set(results).size,
+      results.length,
+      "randomPIN returned duplicate values",
+    );
+  });
+});