@salespark/toolkit 2.1.19 → 2.1.20

package/README.md

@@ -32,7 +32,7 @@ npm i @salespark/toolkit
 - **Defer utilities**: post-return microtask scheduling, non-critical timers, after-response hooks.
 - **Boolean utilities**: safe boolean conversion with common representations
 - **Validation utilities**: IBAN validator (ISO 13616), Portuguese tax ID validator
-- **Security utilities**: Markdown XSS protection, content sanitization, risk assessment, obfuscation helpers, reversible base36 code encoding/decoding
+- **Security utilities**: Markdown XSS protection, content sanitization, risk assessment, password generation, obfuscation helpers, reversible base36 code encoding/decoding
 - **UUID utilities**: uuidv4 generator (RFC 4122)
 - **Environment detection**: `isBrowser`, `isNode` runtime checks
 
@@ -53,6 +53,7 @@ import {
   clamp,
   isBrowser,
   toBool,
+  generatePassword,
   uuidv4,
 } from "@salespark/toolkit";
 
@@ -76,6 +77,9 @@ const safe = clamp(15, 0, 10); // 10
 // Convert to boolean
 const bool = toBool("yes"); // true
 
+// Generate a password (sync by default)
+const recoveryToken = generatePassword(96, false);
+
 // Generate UUID v4
 const id = uuidv4();
 
@@ -860,6 +864,34 @@ assessSecurityRisks([]);
 // Result: { score: 0, level: "safe", recommendations: ["Content appears safe to use"] }
 ```
 
+**`generatePassword(...)`** — Password generator with sync defaults and async-only options (`words`, `entropy`).
+
+```typescript
+import { generatePassword } from "@salespark/toolkit";
+
+// Sync usage (current default behavior)
+const recoveryToken = generatePassword(96, false);
+
+// Memorable password (override security recommendations if needed)
+const memorable = generatePassword({
+  length: 12,
+  memorable: true,
+  ignoreSecurityRecommendations: true,
+});
+
+// Async options (passphrase / deterministic entropy)
+const passphrase = await generatePassword({
+  words: 4,
+  ignoreSecurityRecommendations: true,
+});
+
+const deterministic = await generatePassword({
+  length: 24,
+  entropy: "seed-123",
+  ignoreSecurityRecommendations: true,
+});
+```
+
 **`encodeString(input: string, secret: string): SalesParkContract<any>`** — Base64-encodes a string and scrambles it with the provided secret (obfuscation only).
 
 ```javascript
@@ -1061,5 +1093,5 @@ MIT © [SalesPark](https://salespark.io)
 
 ---
 
-_Document version: 16_  
+_Document version: 17_  
 _Last update: 14-03-2026_

package/dist/index.cjs

@@ -2222,6 +2222,404 @@ var decodeBase36Code = (code, config) => {
   }
 };
 
+// src/utils/password.ts
+var hasCrypto = typeof globalThis !== "undefined" && typeof globalThis.crypto !== "undefined";
+var cryptoSource = hasCrypto ? globalThis.crypto : void 0;
+var textEncoder = typeof TextEncoder !== "undefined" ? new TextEncoder() : null;
+var MAX_RANDOM_BYTES = 65536;
+var VOWELS = "aeiou";
+var CONSONANTS = "bcdfghjklmnpqrstvwxyz";
+var CONSONANT = new RegExp(`[${CONSONANTS}]$`, "i");
+var DEFAULT_PATTERN = /\w/;
+var DEFAULT_LENGTH = 12;
+var MIN_ENTROPY_BITS = 64;
+var MIN_WORD_LENGTH = 3;
+var MAX_WORD_LENGTH = 7;
+var MIN_MEMORABLE_LENGTH = (() => {
+  let bits = 0;
+  let len = 0;
+  let vowel = false;
+  while (bits < MIN_ENTROPY_BITS) {
+    bits += Math.log2(vowel ? VOWELS.length : CONSONANTS.length);
+    vowel = !vowel;
+    len += 1;
+  }
+  return len;
+})();
+var ensureCrypto = () => {
+  if (!cryptoSource) {
+    throw new Error("WebCrypto is required for password generation");
+  }
+  return cryptoSource;
+};
+var getRandomBytesSync = (length) => {
+  if (!Number.isFinite(length) || length < 0) {
+    throw new RangeError("length must be a non-negative finite number");
+  }
+  const crypto = ensureCrypto();
+  const buffer = new Uint8Array(length);
+  for (let offset = 0; offset < length; offset += MAX_RANDOM_BYTES) {
+    const end = Math.min(offset + MAX_RANDOM_BYTES, length);
+    crypto.getRandomValues(buffer.subarray(offset, end));
+  }
+  return buffer;
+};
+var getRandomBytes = async (length) => getRandomBytesSync(length);
+var createDeterministicRandomBytes = async (entropy, source = ensureCrypto()) => {
+  if (entropy.length === 0) {
+    throw new RangeError("entropy must not be empty");
+  }
+  if (!source.subtle) {
+    throw new Error("WebCrypto subtle is required for deterministic entropy");
+  }
+  const keyData = new Uint8Array(entropy).buffer;
+  const key = await source.subtle.importKey(
+    "raw",
+    keyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  let counter = 0n;
+  const counterBytes = new Uint8Array(8);
+  const counterView = new DataView(counterBytes.buffer);
+  const deterministicRandomBytes = async (length) => {
+    if (!Number.isFinite(length) || length < 0) {
+      throw new RangeError("length must be a non-negative finite number");
+    }
+    const buffer = new Uint8Array(length);
+    let offset = 0;
+    while (offset < length) {
+      counterView.setBigUint64(0, counter, false);
+      counter += 1n;
+      const block = new Uint8Array(
+        await source.subtle.sign("HMAC", key, counterBytes)
+      );
+      const take = Math.min(block.length, length - offset);
+      buffer.set(block.subarray(0, take), offset);
+      offset += take;
+    }
+    return buffer;
+  };
+  return deterministicRandomBytes;
+};
+var randomIntSync = (min, max, randomBytes = getRandomBytesSync) => {
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    throw new RangeError("min and max must be finite numbers");
+  }
+  if (max <= min) {
+    throw new RangeError("max must be greater than min");
+  }
+  const range = max - min;
+  if (range === 1) {
+    return min;
+  }
+  const bytesNeeded = Math.ceil(Math.log2(range) / 8);
+  const maxValue = 256 ** bytesNeeded;
+  const limit = maxValue - maxValue % range;
+  let value = limit;
+  while (value >= limit) {
+    const bytes = randomBytes(bytesNeeded);
+    value = 0;
+    for (const byte of bytes) {
+      value = value * 256 + byte;
+    }
+  }
+  return min + value % range;
+};
+var randomInt = async (min, max, randomBytes = getRandomBytes) => {
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    throw new RangeError("min and max must be finite numbers");
+  }
+  if (max <= min) {
+    throw new RangeError("max must be greater than min");
+  }
+  const range = max - min;
+  if (range === 1) {
+    return min;
+  }
+  const bytesNeeded = Math.ceil(Math.log2(range) / 8);
+  const maxValue = 256 ** bytesNeeded;
+  const limit = maxValue - maxValue % range;
+  let value = limit;
+  while (value >= limit) {
+    const bytes = await randomBytes(bytesNeeded);
+    value = 0;
+    for (const byte of bytes) {
+      value = value * 256 + byte;
+    }
+  }
+  return min + value % range;
+};
+var buildValidChars = (pattern) => {
+  const chars = [];
+  for (let i = 33; i <= 126; i += 1) {
+    const char = String.fromCharCode(i);
+    if (pattern.test(char)) {
+      chars.push(char);
+    }
+  }
+  if (chars.length === 0) {
+    throw new Error(
+      `Could not find characters that match the password pattern ${pattern}. Patterns must match individual characters, not the password as a whole.`
+    );
+  }
+  return chars;
+};
+var estimatePatternEntropy = (alphabetSize, length, prefixLength) => {
+  const bitsPerChar = alphabetSize > 1 ? Math.log2(alphabetSize) : 0;
+  return {
+    entropyBits: bitsPerChar * Math.max(0, length - prefixLength),
+    recommendedLength: bitsPerChar > 0 ? prefixLength + Math.ceil(MIN_ENTROPY_BITS / bitsPerChar) : null
+  };
+};
+var estimateMemorableEntropy = (length, prefix) => {
+  const effectiveLength = Math.max(0, length - prefix.length);
+  let entropyBits = 0;
+  let expectsVowel = CONSONANT.test(prefix);
+  for (let i = 0; i < effectiveLength; i += 1) {
+    entropyBits += Math.log2(expectsVowel ? VOWELS.length : CONSONANTS.length);
+    expectsVowel = !expectsVowel;
+  }
+  let recommendedLength = prefix.length;
+  let bits = 0;
+  expectsVowel = CONSONANT.test(prefix);
+  while (bits < MIN_ENTROPY_BITS) {
+    bits += Math.log2(expectsVowel ? VOWELS.length : CONSONANTS.length);
+    expectsVowel = !expectsVowel;
+    recommendedLength += 1;
+  }
+  return { entropyBits, recommendedLength };
+};
+var buildMemorableSync = (length, startsWithVowel, nextInt) => {
+  let expectsVowel = startsWithVowel;
+  let result = "";
+  for (let i = 0; i < length; i += 1) {
+    const alphabet = expectsVowel ? VOWELS : CONSONANTS;
+    result += alphabet[nextInt(0, alphabet.length)];
+    expectsVowel = !expectsVowel;
+  }
+  return result;
+};
+var buildMemorable = async (length, startsWithVowel, nextInt) => {
+  let expectsVowel = startsWithVowel;
+  let result = "";
+  for (let i = 0; i < length; i += 1) {
+    const alphabet = expectsVowel ? VOWELS : CONSONANTS;
+    result += alphabet[await nextInt(0, alphabet.length)];
+    expectsVowel = !expectsVowel;
+  }
+  return result;
+};
+var buildWordLengths = async (count, nextInt, targetLength) => {
+  const lengths = [];
+  let total = 0;
+  for (let i = 0; i < count; i += 1) {
+    const len = await nextInt(MIN_WORD_LENGTH, MAX_WORD_LENGTH + 1);
+    lengths.push(len);
+    total += len;
+  }
+  if (targetLength !== void 0 && total < targetLength) {
+    const adjustable = [];
+    for (let i = 0; i < count; i += 1) {
+      if (lengths[i] < MAX_WORD_LENGTH) adjustable.push(i);
+    }
+    let remaining = targetLength - total;
+    while (remaining > 0 && adjustable.length > 0) {
+      const pick2 = await nextInt(0, adjustable.length);
+      const wordIdx = adjustable[pick2];
+      lengths[wordIdx] = lengths[wordIdx] + 1;
+      remaining -= 1;
+      if (lengths[wordIdx] >= MAX_WORD_LENGTH) {
+        adjustable.splice(pick2, 1);
+      }
+    }
+  }
+  return lengths;
+};
+var parseEntropy = (entropy) => {
+  if (typeof entropy === "string") {
+    if (textEncoder) return textEncoder.encode(entropy);
+    if (typeof Buffer !== "undefined") return Buffer.from(entropy, "utf8");
+    throw new Error("TextEncoder is required for entropy strings");
+  }
+  if (entropy instanceof Uint8Array) {
+    return entropy;
+  }
+  throw new TypeError("entropy must be a Uint8Array or string");
+};
+var validateOptions = (options) => {
+  const length = options?.length ?? DEFAULT_LENGTH;
+  const memorable = options?.memorable ?? false;
+  const pattern = options?.pattern ?? DEFAULT_PATTERN;
+  const prefix = String(options?.prefix ?? "");
+  const ignoreSecurityRecommendations = options?.ignoreSecurityRecommendations ?? false;
+  const words = options?.words;
+  if (!Number.isSafeInteger(length)) {
+    throw new RangeError("length must be a safe integer");
+  }
+  if (length < 0) {
+    throw new RangeError("length must be a non-negative integer");
+  }
+  if (!(pattern instanceof RegExp)) {
+    throw new TypeError("pattern must be a RegExp");
+  }
+  if (words !== void 0) {
+    if (!Number.isSafeInteger(words)) {
+      throw new RangeError("words must be a safe integer");
+    }
+    if (words <= 0) {
+      throw new RangeError("words must be a positive integer");
+    }
+  }
+  if (words !== void 0 && prefix !== "") {
+    throw new Error("prefix is not supported when words are enabled");
+  }
+  return {
+    length,
+    memorable,
+    pattern,
+    prefix,
+    ignoreSecurityRecommendations,
+    words
+  };
+};
+var generatePasswordSync = (options) => {
+  const {
+    length,
+    memorable,
+    pattern,
+    prefix,
+    ignoreSecurityRecommendations,
+    words
+  } = validateOptions(options);
+  if (words !== void 0) {
+    throw new Error("words requires async password generation");
+  }
+  const nextInt = (min, max) => randomIntSync(min, max, getRandomBytesSync);
+  if (memorable) {
+    if (!ignoreSecurityRecommendations) {
+      const estimate = estimateMemorableEntropy(length, prefix);
+      if (estimate.entropyBits < MIN_ENTROPY_BITS) {
+        throw new Error(
+          `Security recommendation: estimated entropy ${estimate.entropyBits.toFixed(
+            1
+          )} bits is below ${MIN_ENTROPY_BITS} bits. Use length >= ${estimate.recommendedLength} or set memorable: false. To override, pass { ignoreSecurityRecommendations: true }.`
+        );
+      }
+    }
+    const charCount = Math.max(0, length - prefix.length);
+    return prefix + buildMemorableSync(charCount, CONSONANT.test(prefix), nextInt);
+  }
+  const validChars = buildValidChars(pattern);
+  if (!ignoreSecurityRecommendations) {
+    const estimate = estimatePatternEntropy(
+      validChars.length,
+      length,
+      prefix.length
+    );
+    if (estimate.entropyBits < MIN_ENTROPY_BITS) {
+      const recommendation = estimate.recommendedLength === null ? "Use a broader pattern to increase the character set." : `Use length >= ${estimate.recommendedLength} or broaden the pattern.`;
+      throw new Error(
+        `Security recommendation: estimated entropy ${estimate.entropyBits.toFixed(
+          1
+        )} bits is below ${MIN_ENTROPY_BITS} bits. ${recommendation} To override, pass { ignoreSecurityRecommendations: true }.`
+      );
+    }
+  }
+  let result = prefix;
+  while (result.length < length) {
+    result += validChars[nextInt(0, validChars.length)];
+  }
+  return result;
+};
+var generatePasswordAsync = async (options) => {
+  const {
+    length,
+    memorable,
+    pattern,
+    prefix,
+    ignoreSecurityRecommendations,
+    words
+  } = validateOptions(options);
+  const entropy = options?.entropy;
+  let entropyBytes;
+  if (entropy !== void 0) {
+    entropyBytes = parseEntropy(entropy);
+  }
+  const randomBytes = entropyBytes ? await createDeterministicRandomBytes(entropyBytes) : getRandomBytes;
+  const nextInt = (min, max) => randomInt(min, max, randomBytes);
+  if (words !== void 0) {
+    if (!ignoreSecurityRecommendations && words * MAX_WORD_LENGTH < MIN_MEMORABLE_LENGTH) {
+      const recommendedWords = Math.ceil(
+        MIN_MEMORABLE_LENGTH / MAX_WORD_LENGTH
+      );
+      throw new Error(
+        `Security recommendation: word count ${words} cannot reach ${MIN_ENTROPY_BITS} bits with ${MIN_WORD_LENGTH}-${MAX_WORD_LENGTH} letter words. Use words >= ${recommendedWords}. To override, pass { ignoreSecurityRecommendations: true }.`
+      );
+    }
+    const targetLength = ignoreSecurityRecommendations ? void 0 : MIN_MEMORABLE_LENGTH;
+    const lengths = await buildWordLengths(words, nextInt, targetLength);
+    const wordsList = [];
+    for (const wordLength of lengths) {
+      wordsList.push(await buildMemorable(wordLength, false, nextInt));
+    }
+    return wordsList.join(" ");
+  }
+  if (memorable) {
+    if (!ignoreSecurityRecommendations) {
+      const estimate = estimateMemorableEntropy(length, prefix);
+      if (estimate.entropyBits < MIN_ENTROPY_BITS) {
+        throw new Error(
+          `Security recommendation: estimated entropy ${estimate.entropyBits.toFixed(
+            1
+          )} bits is below ${MIN_ENTROPY_BITS} bits. Use length >= ${estimate.recommendedLength} or set memorable: false. To override, pass { ignoreSecurityRecommendations: true }.`
+        );
+      }
+    }
+    const charCount = Math.max(0, length - prefix.length);
+    return prefix + await buildMemorable(charCount, CONSONANT.test(prefix), nextInt);
+  }
+  const validChars = buildValidChars(pattern);
+  if (!ignoreSecurityRecommendations) {
+    const estimate = estimatePatternEntropy(
+      validChars.length,
+      length,
+      prefix.length
+    );
+    if (estimate.entropyBits < MIN_ENTROPY_BITS) {
+      const recommendation = estimate.recommendedLength === null ? "Use a broader pattern to increase the character set." : `Use length >= ${estimate.recommendedLength} or broaden the pattern.`;
+      throw new Error(
+        `Security recommendation: estimated entropy ${estimate.entropyBits.toFixed(
+          1
+        )} bits is below ${MIN_ENTROPY_BITS} bits. ${recommendation} To override, pass { ignoreSecurityRecommendations: true }.`
+      );
+    }
+  }
+  let result = prefix;
+  while (result.length < length) {
+    result += validChars[await nextInt(0, validChars.length)];
+  }
+  return result;
+};
+function generatePassword(lengthOrOptions, memorable, pattern, prefix) {
+  if (typeof lengthOrOptions === "object") {
+    const options2 = lengthOrOptions;
+    const requiresAsync = options2.words !== void 0 || options2.entropy !== void 0;
+    return requiresAsync ? generatePasswordAsync(options2) : generatePasswordSync(options2);
+  }
+  const options = {};
+  if (lengthOrOptions !== void 0) options.length = lengthOrOptions;
+  if (memorable !== void 0) options.memorable = memorable;
+  if (pattern !== void 0) options.pattern = pattern;
+  if (prefix !== void 0) options.prefix = prefix;
+  return generatePasswordSync(options);
+}
+var generatePasswordWithOptions = (options) => {
+  const requiresAsync = options?.words !== void 0 || options?.entropy !== void 0;
+  return requiresAsync ? generatePasswordAsync(options) : generatePasswordSync(options);
+};
+
 // src/index.ts
 var isBrowser = typeof globalThis !== "undefined" && typeof globalThis.document !== "undefined";
 var isNode = typeof process !== "undefined" && !!process.versions?.node;
@@ -2267,6 +2665,8 @@ exports.formatBytes = formatBytes;
 exports.formatCurrency = formatCurrency;
 exports.formatCurrencyPro = formatCurrencyPro;
 exports.formatDecimalNumber = formatDecimalNumber;
+exports.generatePassword = generatePassword;
+exports.generatePasswordWithOptions = generatePasswordWithOptions;
 exports.getStringSimilarity = getStringSimilarity;
 exports.groupBy = groupBy;
 exports.hasNilOrEmpty = hasNilOrEmpty;