js-generate-password 0.1.9 → 1.1.0

package/package.json

@@ -1,39 +1,59 @@
-{
-  "name": "js-generate-password",
-  "version": "0.1.9",
-  "private": false,
-  "description": "Password Generator for using in javascirpt/typscript based projects.",
-  "Author": "Ahmad Joya <joya.abn@gmail.com>",
-  "main": "./dist/index.js",
-  "bin": "./dist/index.js",
-  "types": "./src/index.d.ts",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ahmadjoya/js-generate-password.git"
-  },
-  "keywords": [
-    "generate password",
-    "js-generate-password",
-    "password generator",
-    "password generator",
-    "random password generator",
-    "simple password generator",
-    "easy password generator",
-    "password",
-    "generator",
-    "unique",
-    "nodejs",
-    "nextjs",
-    "react",
-    "reactjs",
-    "random"
-  ],
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/ahmadjoya/js-generate-password/issues"
-  },
-  "homepage": "https://github.com/ahmadjoya/js-generate-password#readme"
-}
+{
+  "name": "js-generate-password",
+  "version": "1.1.0",
+  "private": false,
+  "description": "Tiny, dependency-free, cryptographically secure password generator for JavaScript and TypeScript projects.",
+  "author": "Ahmad Joya <joya.abn@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ahmadjoya/generate-password-lite.git"
+  },
+  "keywords": [
+    "password",
+    "password-generator",
+    "generate-password",
+    "generate-password-lite",
+    "js-generate-password",
+    "random-password",
+    "secure-password",
+    "crypto",
+    "csprng",
+    "generator",
+    "random",
+    "typescript",
+    "nodejs",
+    "react",
+    "nextjs",
+    "browser"
+  ],
+  "bugs": {
+    "url": "https://github.com/ahmadjoya/generate-password-lite/issues"
+  },
+  "homepage": "https://github.com/ahmadjoya/generate-password-lite#readme"
+}

package/src/index.ts

@@ -1,39 +1,22 @@
-import { generatePswd } from "./lib/password-generator";
-import { checkError } from "./lib/check-options-error";
-import { processOption } from "./lib/process-options";
-import { GenerateOptions } from "./lib/types";
-
-function GeneratePassword(options?: GenerateOptions) {
-  let pswd;
-  if (options) {
-    options = processOption(options);
-
-    checkError(options);
-
-    pswd = generatePswd(options);
-    return pswd;
-  } else {
-    let opt = {
-      length: 10,
-      lowercase: true,
-      uppercase: true,
-      numbers: true,
-      symbols: false,
-      exclude: "",
-      minLengthLowercase: 1,
-      minLengthUppercase: 1,
-      minLengthNumbers: 1,
-      minLengthSymbols: 0,
-    };
-    options = processOption(opt);
-
-    checkError(options);
-
-    pswd = generatePswd(options);
-    return pswd;
-  }
-}
-
-// console.log(GeneratePassword({ minLengthLowercase: 4 }));
-export { GeneratePassword };
-export default { GeneratePassword };
+import { generatePswd } from './lib/password-generator'
+import { checkError } from './lib/check-options-error'
+import { processOption } from './lib/process-options'
+import { GenerateOptions } from './types'
+
+/**
+ * Generates a random password using a cryptographically secure random source.
+ *
+ * @param options - Optional overrides. Every unset option falls back to its
+ * documented default.
+ * @returns The generated password.
+ */
+function GeneratePassword(options: GenerateOptions = {}): string {
+  const resolved = processOption(options)
+
+  checkError(resolved)
+
+  return generatePswd(resolved)
+}
+
+export { GeneratePassword, type GenerateOptions }
+export default GeneratePassword

package/src/lib/check-options-error.ts

@@ -1,42 +1,52 @@
-import { GenerateOptions } from "./types";
-
-export const checkError = (options: GenerateOptions) => {
-  const {
-    length,
-    lowercase,
-    uppercase,
-    numbers,
-    symbols,
-    minLengthLowercase,
-    minLengthUppercase,
-    minLengthNumbers,
-    minLengthSymbols,
-  } = options;
-
-  //Checking if the sum of minimum characters of Lowercase, uppercase, numbers and special case is greater than the total password length.
-  if (
-    minLengthLowercase! +
-      minLengthUppercase! +
-      minLengthNumbers! +
-      minLengthSymbols! >
-    length!
-  ) {
-    throw new Error(
-      "Sum of Minimum Characters in the passwords greater than the length of the Password to be generated."
-    );
-  }
-
-  //Checking if lowercase, uppercase , numbers and special characters have all been set to false.
-  if (
-    lowercase == false &&
-    uppercase == false &&
-    numbers == false &&
-    symbols == false
-  ) {
-    throw new Error(
-      "Alphabets, Numbers and Symbols are all set to False. No valid Characters to generate the Password."
-    );
-  }
-};
-
-// module.exports = checkError;
+import { ResolvedOptions } from '../types'
+
+const assertCount = (value: number, name: string) => {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `generate-password-lite: \`${name}\` must be a non-negative integer, received ${value}.`
+    )
+  }
+}
+
+export const checkError = (options: ResolvedOptions) => {
+  const {
+    length,
+    lowercase,
+    uppercase,
+    numbers,
+    symbols,
+    minLengthLowercase,
+    minLengthUppercase,
+    minLengthNumbers,
+    minLengthSymbols,
+  } = options
+
+  if (!Number.isInteger(length) || length < 1) {
+    throw new Error(
+      `generate-password-lite: \`length\` must be a positive integer, received ${length}.`
+    )
+  }
+
+  assertCount(minLengthLowercase, 'minLengthLowercase')
+  assertCount(minLengthUppercase, 'minLengthUppercase')
+  assertCount(minLengthNumbers, 'minLengthNumbers')
+  assertCount(minLengthSymbols, 'minLengthSymbols')
+
+  // Lowercase, uppercase, numbers and symbols have all been turned off, so
+  // there is no character class left to build a password from.
+  if (!lowercase && !uppercase && !numbers && !symbols) {
+    throw new Error(
+      'generate-password-lite: `lowercase`, `uppercase`, `numbers` and `symbols` are all false. No valid characters to generate the password from.'
+    )
+  }
+
+  // The guaranteed characters alone would already overflow the password.
+  const minimumTotal =
+    minLengthLowercase + minLengthUppercase + minLengthNumbers + minLengthSymbols
+
+  if (minimumTotal > length) {
+    throw new Error(
+      `generate-password-lite: the sum of the minimum character counts (${minimumTotal}) is greater than \`length\` (${length}).`
+    )
+  }
+}

package/src/lib/generate-random-number.ts

@@ -1,5 +1,48 @@
-export const generateRandomNumbers = (upperLimit: number) => {
-  return Math.floor(Math.random() * upperLimit);
-};
-
-// module.exports = generateRandomNumbers;
+/**
+ * Number of distinct values a Uint32 can hold.
+ */
+const UINT32_RANGE = 0x100000000
+
+const getWebCrypto = (): Crypto => {
+  const webCrypto = globalThis.crypto
+
+  if (!webCrypto || typeof webCrypto.getRandomValues !== 'function') {
+    throw new Error(
+      'generate-password-lite: no Web Crypto implementation found. ' +
+        'A secure random source is required to generate passwords. ' +
+        'Use Node.js 18+, a modern browser, or polyfill `globalThis.crypto`.'
+    )
+  }
+
+  return webCrypto
+}
+
+/**
+ * Returns a cryptographically secure integer in the range [0, upperLimit).
+ *
+ * Uses rejection sampling so that every value is equally likely. Taking a
+ * plain `random % upperLimit` would bias the low end of the range whenever
+ * `upperLimit` is not a power of two.
+ */
+export const generateRandomNumbers = (upperLimit: number): number => {
+  if (!Number.isInteger(upperLimit) || upperLimit <= 0) {
+    throw new RangeError(
+      `generate-password-lite: upperLimit must be a positive integer, received ${upperLimit}.`
+    )
+  }
+
+  const webCrypto = getWebCrypto()
+  const buffer = new Uint32Array(1)
+
+  // Largest multiple of upperLimit that fits in the Uint32 range. Draws at or
+  // above this cutoff are discarded rather than folded back into the range.
+  const cutoff = Math.floor(UINT32_RANGE / upperLimit) * upperLimit
+
+  let value: number
+  do {
+    webCrypto.getRandomValues(buffer)
+    value = buffer[0]!
+  } while (value >= cutoff)
+
+  return value % upperLimit
+}

package/src/lib/password-generator.ts

@@ -1,92 +1,92 @@
-// const generategenerateRandomNumberss = require("./generate-random-number");
-// const shuffleString = require("./shuffle-string");
-import { generateRandomNumbers } from "./generate-random-number";
-import { shuffleString } from "./shuffle-string";
-import { GenerateOptions } from "./types";
-export const generatePswd = (options: GenerateOptions) => {
-  let pswd = "";
-  let minChar = "";
-  let {
-    length,
-    lowercase,
-    uppercase,
-    numbers,
-    symbols,
-    minLengthLowercase,
-    minLengthUppercase,
-    minLengthNumbers,
-    minLengthSymbols,
-    exclude,
-  } = options;
-
-  let lowercaseChar = "abcdefghijklmnopqrstuvwxyz";
-  lowercaseChar = removeExceptions(lowercaseChar, exclude!);
-
-  let uppercaseChar = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
-  uppercaseChar = removeExceptions(uppercaseChar, exclude!);
-
-  let numberChar = "0123456789";
-  numberChar = removeExceptions(numberChar, exclude!);
-
-  let specialChar = "!#$%&'()*+,-./:;<=>?@[]^_{|}~";
-  specialChar = removeExceptions(specialChar, exclude!);
-
-  //  Generating a minChar string that holds minimum number of characters on the User Option Selection.
-  // The minChar variable will store the minimum number of characters for each type - lowercase, uppercase, numbers, and symbols.
-  //  Then, the minChar variable is shuffled to make the password random.
-
-  let upperLimit = lowercaseChar.length;
-  for (let i = 0; i < minLengthLowercase!; i++) {
-    minChar += lowercaseChar.charAt(generateRandomNumbers(upperLimit));
-  }
-
-  upperLimit = uppercaseChar.length;
-  for (let i = 0; i < minLengthUppercase!; i++) {
-    minChar += uppercaseChar.charAt(generateRandomNumbers(upperLimit));
-  }
-
-  upperLimit = numberChar.length;
-  for (let i = 0; i < minLengthNumbers!; i++) {
-    minChar += numberChar.charAt(generateRandomNumbers(upperLimit));
-  }
-
-  upperLimit = specialChar.length;
-  for (let i = 0; i < minLengthSymbols!; i++) {
-    minChar += specialChar.charAt(generateRandomNumbers(upperLimit));
-  }
-
-  //Shuffling the minChar to generate a password that holds minimum criteria.
-  pswd = pswd + shuffleString(minChar);
-
-  let characterString = "";
-
-  characterString = lowercase
-    ? characterString + lowercaseChar
-    : characterString;
-
-  characterString = uppercase
-    ? characterString + uppercaseChar
-    : characterString;
-
-  characterString = numbers ? characterString + numberChar : characterString;
-
-  characterString = symbols ? characterString + specialChar : characterString;
-
-  let remainingChar = length! - pswd.length;
-
-  upperLimit = characterString.length;
-
-  for (let i = 0; i < remainingChar; i++) {
-    pswd += characterString.charAt(generateRandomNumbers(upperLimit));
-  }
-  return pswd;
-};
-
-const removeExceptions = (str: string, EXCEPTIONS: string) => {
-  EXCEPTIONS?.split("").forEach((char) => {
-    str = str.replace(char, "");
-  });
-  return str;
-};
-
-// module.exports = generatePassword;
+import { generateRandomNumbers } from './generate-random-number'
+import { shuffleString } from './shuffle-string'
+import { ResolvedOptions } from '../types'
+
+const LOWERCASE_CHARS = 'abcdefghijklmnopqrstuvwxyz'
+const UPPERCASE_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+const NUMBER_CHARS = '0123456789'
+const SYMBOL_CHARS = "!#$%&'()*+,-./:;<=>?@[]^_{|}~"
+
+/**
+ * Drops every excluded character. `String.replace` with a string pattern only
+ * removes the first match, so the exclusion is done with a set instead.
+ */
+const removeExceptions = (str: string, exclude: string): string => {
+  if (!exclude) return str
+
+  const banned = new Set([...exclude])
+  return [...str].filter(char => !banned.has(char)).join('')
+}
+
+/**
+ * Picks `count` characters from `pool`. Throws when the caller asked for
+ * guaranteed characters out of a pool that `exclude` emptied.
+ */
+const pickFrom = (pool: string, count: number, name: string): string => {
+  if (count === 0) return ''
+
+  if (pool.length === 0) {
+    throw new Error(
+      `generate-password-lite: \`exclude\` removed every ${name} character, but \`minLength${name[0]!.toUpperCase()}${name.slice(1)}\` is ${count}.`
+    )
+  }
+
+  let picked = ''
+  for (let i = 0; i < count; i++) {
+    picked += pool.charAt(generateRandomNumbers(pool.length))
+  }
+  return picked
+}
+
+export const generatePswd = (options: ResolvedOptions): string => {
+  const {
+    length,
+    lowercase,
+    uppercase,
+    numbers,
+    symbols,
+    minLengthLowercase,
+    minLengthUppercase,
+    minLengthNumbers,
+    minLengthSymbols,
+    exclude,
+  } = options
+
+  const lowercaseChar = removeExceptions(LOWERCASE_CHARS, exclude)
+  const uppercaseChar = removeExceptions(UPPERCASE_CHARS, exclude)
+  const numberChar = removeExceptions(NUMBER_CHARS, exclude)
+  const symbolChar = removeExceptions(SYMBOL_CHARS, exclude)
+
+  // Characters that must appear, so that the password satisfies every
+  // `minLength*` the caller asked for.
+  const guaranteed =
+    pickFrom(lowercaseChar, minLengthLowercase, 'lowercase') +
+    pickFrom(uppercaseChar, minLengthUppercase, 'uppercase') +
+    pickFrom(numberChar, minLengthNumbers, 'numbers') +
+    pickFrom(symbolChar, minLengthSymbols, 'symbols')
+
+  // Every character the enabled classes still allow after exclusions.
+  const characterPool =
+    (lowercase ? lowercaseChar : '') +
+    (uppercase ? uppercaseChar : '') +
+    (numbers ? numberChar : '') +
+    (symbols ? symbolChar : '')
+
+  const remaining = length - guaranteed.length
+
+  if (remaining > 0 && characterPool.length === 0) {
+    throw new Error(
+      'generate-password-lite: `exclude` removed every character of every enabled class. No valid characters to generate the password from.'
+    )
+  }
+
+  let filler = ''
+  for (let i = 0; i < remaining; i++) {
+    filler += characterPool.charAt(generateRandomNumbers(characterPool.length))
+  }
+
+  // Shuffle the whole password, not just the guaranteed part. Shuffling only
+  // the guaranteed characters would pin them to the leading positions and make
+  // the layout of the password predictable.
+  return shuffleString(guaranteed + filler)
+}

package/src/lib/process-options.ts

@@ -1,61 +1,34 @@
-import { GenerateOptions } from "./types";
-
-export const processOption = (options: GenerateOptions) => {
-  {
-    options.length = typeof options.length == "undefined" ? 10 : options.length;
-
-    options.lowercase =
-      typeof options.lowercase == "undefined" ? true : options.lowercase;
-
-    options.uppercase =
-      typeof options.uppercase == "undefined" ? true : options.uppercase;
-
-    options.numbers =
-      typeof options.numbers == "undefined" ? true : options.numbers;
-
-    options.symbols =
-      typeof options.symbols == "undefined" ? false : options.symbols;
-
-    if (options.lowercase) {
-      options.minLengthLowercase =
-        typeof options.minLengthLowercase == "undefined"
-          ? 1
-          : options.minLengthLowercase;
-    } else {
-      options.minLengthLowercase = 0;
-    }
-
-    if (options.uppercase) {
-      options.minLengthUppercase =
-        typeof options.minLengthUppercase == "undefined"
-          ? 1
-          : options.minLengthUppercase;
-    } else {
-      options.minLengthUppercase = 0;
-    }
-
-    if (options.numbers) {
-      options.minLengthNumbers =
-        typeof options.minLengthNumbers == "undefined"
-          ? 1
-          : options.minLengthNumbers;
-    } else {
-      options.minLengthNumbers = 0;
-    }
-
-    if (options.symbols) {
-      options.minLengthSymbols =
-        typeof options.minLengthSymbols == "undefined"
-          ? 1
-          : options.minLengthSymbols;
-    } else {
-      options.minLengthSymbols = 0;
-    }
-
-    options.exclude =
-      typeof options.exclude == "undefined" ? "" : options.exclude;
-  }
-  return options;
-};
-
-// module.exports = processOption;
+import { GenerateOptions, ResolvedOptions } from '../types'
+
+const withDefault = <T>(value: T | undefined, fallback: T): T =>
+  typeof value === 'undefined' ? fallback : value
+
+/**
+ * Fills in every unset option. Returns a new object so that the caller's
+ * options are never mutated.
+ */
+export const processOption = (options: GenerateOptions): ResolvedOptions => {
+  const lowercase = withDefault(options.lowercase, true)
+  const uppercase = withDefault(options.uppercase, true)
+  const numbers = withDefault(options.numbers, true)
+  const symbols = withDefault(options.symbols, false)
+
+  // A disabled character class can never contribute a minimum, regardless of
+  // what the caller passed in.
+  return {
+    length: withDefault(options.length, 10),
+    lowercase,
+    uppercase,
+    numbers,
+    symbols,
+    exclude: withDefault(options.exclude, ''),
+    minLengthLowercase: lowercase
+      ? withDefault(options.minLengthLowercase, 1)
+      : 0,
+    minLengthUppercase: uppercase
+      ? withDefault(options.minLengthUppercase, 1)
+      : 0,
+    minLengthNumbers: numbers ? withDefault(options.minLengthNumbers, 1) : 0,
+    minLengthSymbols: symbols ? withDefault(options.minLengthSymbols, 1) : 0,
+  }
+}

package/src/lib/shuffle-string.ts

@@ -1,14 +1,21 @@
-export const shuffleString = (str: string) => {
-  let arr = str.split("");
-  let n = arr.length;
-
-  for (let i = n - 1; i > 0; i--) {
-    let j = Math.floor(Math.random() * (i + 1));
-    let tmp = arr[i];
-    arr[i] = arr[j];
-    arr[j] = tmp;
-  }
-  return arr.join("");
-};
-
-// module.exports = shuffleString;
+import { generateRandomNumbers } from './generate-random-number'
+
+/**
+ * Fisher-Yates shuffle backed by the same cryptographically secure source
+ * used to pick the characters themselves.
+ *
+ * Spreads across code points rather than UTF-16 units so that a surrogate
+ * pair supplied through `exclude` handling is never split in half.
+ */
+export const shuffleString = (str: string): string => {
+  const chars = [...str]
+
+  for (let i = chars.length - 1; i > 0; i--) {
+    const j = generateRandomNumbers(i + 1)
+    const tmp = chars[i]!
+    chars[i] = chars[j]!
+    chars[j] = tmp
+  }
+
+  return chars.join('')
+}