js-generate-password 1.0.0 → 1.1.0

package/package.json

@@ -1,51 +1,59 @@
-{
-  "name": "js-generate-password",
-  "version": "1.0.0",
-  "private": false,
-  "description": "Password Generator for using in javascript/typescript based projects.",
-  "Author": "Ahmad Joya <joya.abn@gmail.com>",
-  "scripts": {
-    "build": "rollup -c"
-  },
-  "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",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "bin": "./dist/index.js",
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-terser": "^0.4.4",
-    "rollup": "^4.6.1",
-    "rollup-plugin-dts": "^6.1.0",
-    "rollup-plugin-typescript2": "^0.36.0"
-  }
-}
+{
+  "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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,52 @@
+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

@@ -0,0 +1,48 @@
+/**
+ * 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

@@ -0,0 +1,92 @@
+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

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,21 @@
+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('')
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+export interface GenerateOptions {
+  /**
+   * Length of the generated password.
+   * @default 10
+   */
+  length?: number
+  /**
+   * Should the password include lowercase characters.
+   * @default true
+   */
+  lowercase?: boolean
+  /**
+   * Should the password include uppercase characters.
+   * @default true
+   */
+  uppercase?: boolean
+  /**
+   * Should the password include numbers.
+   * @default true
+   */
+  numbers?: boolean
+  /**
+   * Should the password include symbol characters.
+   * @default false
+   */
+  symbols?: boolean
+  /**
+   * Characters to exclude from the password.
+   * @default ""
+   */
+  exclude?: string
+  /**
+   * Minimum number of lowercase characters. Forced to 0 when `lowercase` is false.
+   * @default 1 when `lowercase` is true, otherwise 0
+   */
+  minLengthLowercase?: number
+  /**
+   * Minimum number of uppercase characters. Forced to 0 when `uppercase` is false.
+   * @default 1 when `uppercase` is true, otherwise 0
+   */
+  minLengthUppercase?: number
+  /**
+   * Minimum number of numeric characters. Forced to 0 when `numbers` is false.
+   * @default 1 when `numbers` is true, otherwise 0
+   */
+  minLengthNumbers?: number
+  /**
+   * Minimum number of symbol characters. Forced to 0 when `symbols` is false.
+   * @default 1 when `symbols` is true, otherwise 0
+   */
+  minLengthSymbols?: number
+}
+
+/**
+ * Every option resolved to a concrete value by `processOption`.
+ */
+export type ResolvedOptions = Required<GenerateOptions>

package/dist/index.js

@@ -1 +0,0 @@
-"use strict";var e=function(e){return Math.floor(Math.random()*e)},n=function(n){var t="",s="",o=n.length,a=n.lowercase,m=n.uppercase,h=n.numbers,i=n.symbols,l=n.minLengthLowercase,c=n.minLengthUppercase,g=n.minLengthNumbers,u=n.minLengthSymbols,L=n.exclude,p="abcdefghijklmnopqrstuvwxyz";p=r(p,L);var b="ABCDEFGHIJKLMNOPQRSTUVWXYZ";b=r(b,L);var d="0123456789";d=r(d,L);var v="!#$%&'()*+,-./:;<=>?@[]^_{|}~";v=r(v,L);for(var w=p.length,f=0;f<l;f++)s+=p.charAt(e(w));w=b.length;for(f=0;f<c;f++)s+=b.charAt(e(w));w=d.length;for(f=0;f<g;f++)s+=d.charAt(e(w));w=v.length;for(f=0;f<u;f++)s+=v.charAt(e(w));t+=function(e){for(var n=e.split(""),r=n.length-1;r>0;r--){var t=Math.floor(Math.random()*(r+1)),s=n[r];n[r]=n[t],n[t]=s}return n.join("")}(s);var y="";y=a?y+p:y,y=m?y+b:y,y=h?y+d:y,y=i?y+v:y;var N=o-t.length;w=y.length;for(f=0;f<N;f++)t+=y.charAt(e(w));return t},r=function(e,n){return null==n||n.split("").forEach((function(n){e=e.replace(n,"")})),e},t=function(e){var n=e.length,r=e.lowercase,t=e.uppercase,s=e.numbers,o=e.symbols;if(e.minLengthLowercase+e.minLengthUppercase+e.minLengthNumbers+e.minLengthSymbols>n)throw new Error("Sum of Minimum Characters in the passwords greater than the length of the Password to be generated.");if(0==r&&0==t&&0==s&&0==o)throw new Error("Alphabets, Numbers and Symbols are all set to False. No valid Characters to generate the Password.")},s=function(e){return e.length=void 0===e.length?10:e.length,e.lowercase=void 0===e.lowercase||e.lowercase,e.uppercase=void 0===e.uppercase||e.uppercase,e.numbers=void 0===e.numbers||e.numbers,e.symbols=void 0!==e.symbols&&e.symbols,e.lowercase?e.minLengthLowercase=void 0===e.minLengthLowercase?1:e.minLengthLowercase:e.minLengthLowercase=0,e.uppercase?e.minLengthUppercase=void 0===e.minLengthUppercase?1:e.minLengthUppercase:e.minLengthUppercase=0,e.numbers?e.minLengthNumbers=void 0===e.minLengthNumbers?1:e.minLengthNumbers:e.minLengthNumbers=0,e.symbols?e.minLengthSymbols=void 0===e.minLengthSymbols?1:e.minLengthSymbols:e.minLengthSymbols=0,e.exclude=void 0===e.exclude?"":e.exclude,e};exports.GeneratePassword=function(e){return e?(e=s(e),t(e),n(e)):(e=s({length:10,lowercase:!0,uppercase:!0,numbers:!0,symbols:!1,exclude:"",minLengthLowercase:1,minLengthUppercase:1,minLengthNumbers:1,minLengthSymbols:0}),t(e),n(e))};

package/dist/lib/check-options-error.d.ts

@@ -1,2 +0,0 @@
-import { GenerateOptions } from '../types';
-export declare const checkError: (options: GenerateOptions) => void;

package/dist/lib/generate-random-number.d.ts

@@ -1 +0,0 @@
-export declare const generateRandomNumbers: (upperLimit: number) => number;

package/dist/lib/password-generator.d.ts

@@ -1,2 +0,0 @@
-import { GenerateOptions } from '../types';
-export declare const generatePswd: (options: GenerateOptions) => string;

package/dist/lib/process-options.d.ts

@@ -1,2 +0,0 @@
-import { GenerateOptions } from '../types';
-export declare const processOption: (options: GenerateOptions) => GenerateOptions;

package/dist/lib/shuffle-string.d.ts

@@ -1 +0,0 @@
-export declare const shuffleString: (str: string) => string;

package/dist/types.d.ts

@@ -1,58 +0,0 @@
-interface GenerateOptions {
-  /**
-   * lenght of the password
-   * @default 10
-   */
-  length?: number
-  /**
-   * Should the password include lowercase characters
-   * @default true
-   */
-  lowercase?: boolean
-  /**
-   * Should the password include uppercase characters
-   * @default true
-   */
-  uppercase?: boolean
-  /**
-   * Should the password include numbers
-   * @default true
-   */
-  numbers?: boolean
-  /**
-   * Should the password include symbol characters
-   * @default false
-   */
-  symbols?: boolean
-  /**
-   * List of characters to be excluded from the password
-   * @default ""
-   */
-  exclude?: string
-  /**
-   * min lentgh of lowercase character
-   * @default 1
-   */
-  minLengthLowercase?: number
-  /**
-   * min lentgh of uppercase character
-   * @default 1
-   */
-  minLengthUppercase?: number
-  /**
-   * min length of numbers
-   * @default 1
-   */
-  minLengthNumbers?: number
-  /**
-   * min length of symbols
-   * @default 0
-   */
-  minLengthSymbols?: number
-}
-
-declare namespace GeneratePassword {}
-
-declare function GeneratePassword(options?: GenerateOptions): string
-
-export { type GenerateOptions, GeneratePassword };