secure-password-utilities

Secure, zero-dependency utilities for generating passwords, passphrases, pins, and more.

• 0️⃣ Zero dependencies
• 💯 Works in browsers (using webcrypto) and node 12.x+ (using node:crypto)
• ✅ Supports both CJS and ESM formats
• 🪶 Lightweight package, e.g., importing generatePin is less than a kilobyte gzipped

Usage

npm install secure-password-utilities

Basic usage:

1import {generatePassword, generatePin} from 'secure-password-utilities';
2
3// Defaults include all uppercase/lowercase characters, digits, and symbols.
4const password = generatePassword(12);
5console.log(password); // l[Nz8UfU.o4g
6
7const pin = generatePin(6);
8console.log(pin); // 036919

API

• secure-password-utilities
  • generatePassword
  • generatePassphrase
  • generatePin
  • generateCharacters
• secure-password-utilities/constants
  • DIGIT_CHARSET
  • LOWERCASE_CHARSET
  • UPPERCASE_CHARSET
  • SYMBOL_CHARSET
• secure-password-utilities/csprng
  • getRandomBytes
• secure-password-utilities/random
  • getRandomNumbersInRange
  • getRandomValues
  • randomizeCharacters
• secure-password-utilities/wordlists
  • DEFAULT_WORDLIST
  • EFF_LONG_WORDLIST

secure-password-utilities

1import {generatePassword, generatePassphrase, generatePin, generateCharacters} from 'secure-password-utilities'

generatePassword

1function generatePassword(length: number, options?: PasswordOptionsType): string

Generates a random password.

PasswordOptionsType is defined as:

1type PasswordOptionType =
2  // `true` means include [character type], `false` means exclude [character type]
3  | boolean
4  // <number> means include exactly <number> [character type]s
5  | number
6  // { min: <number> } means include at least <number> [character type]s
7  | { min: number };
8
9export type PasswordOptionsType = {
10  digits?: PasswordOptionType;
11  symbols?: PasswordOptionType;
12  lowercase?: PasswordOptionType;
13  uppercase?: PasswordOptionType;
14  charset?: {
15    digits?: string;
16    symbols?: string;
17    lowercase?: string;
18    uppercase?: string;
19  };
20};

Examples:

1// Contains only letters (upper and lowercase) and digits.
2const alphanumericPassword = generatePassword(10, { symbols: false });
3console.log(alphanumericPassword); // 49Faqzd8jx
4
5const password = generatePassword(12, {
6  symbols: 2,               // Resulting password must contain exactly two symbols.
7  uppercase: { min: 1 },    // Resulting password must contain a minimum of 1 upperase character.
8});
9console.log(password); // b1yT6$jO`kvf
10
11const uppercasePassword = generatePassword(10, {
12  digits: false,            // Resulting password must NOT contain any digits.
13  symbols: false,           // Resulting password must NOT contain any symbols.
14  lowercase: false,         // Resulting password must NOT contain any lowercase characters.
15});
16console.log(uppercasePassword); // IHDPPZRNPS

You can override the character set used for each option using the charset option, e.g.:

1// Ensure exactly three symbols are present in the resulting
2// password using the following values for 'symbols':
3//
4//     ! @ # $ %
5//
6const password = generatePassword(12, {
7  symbols: 3,
8  charset: { symbols: '!@#$%' },
9});
10console.log(password); // A@D#tkG!ymFE
11
12// Generate a 12-character password with at least 3 digits and no symbols.
13// For the digits, only use even digits, i.e., 0, 2, 4, 6, 8.
14const evenDigitPassword = generatePassword(12, {
15  digits: { min: 3 },
16  symbols: false,
17  charset: { digits: '02468' }
18});
19console.log(evenDigitPassword); // e6V8zy0kfTAN

generatePassphrase

1function generatePassphrase(length: number, wordlist: readonly string[], sep?: string): string

Generate a memorable passphrase comprised of words chosen randomly from the given wordlist.

There are wordlists available in the wordlist module, or you can provide your own.

1import {DEFAULT_WORDLIST} from 'secure-password-utilities/wordlists';
2
3generatePassphrase(6, DEFAULT_WORDLIST); // canopener-uncanny-hatchet-murky-agony-traitor
4generatePassphrase(6, DEFAULT_WORDLIST); // backpack-craftwork-sweat-postcard-imaging-litter

The word separator defaults to a dash (-), but you can customize this behavior using the third argument.

1generatePassphrase(6, DEFAULT_WORDLIST, '_'); // goldfish_scorpion_antiviral_pursuit_demanding_motto

generatePin

1function generatePin(length: number): string

Generate a random digit pin.

1generatePin(6); // 036919
2generatePin(8); // 45958396

generateCharacters

1function generateCharacters(length: number, charset: string): string

Generate a string of length characters chosen randomly from the given charset.

1generateCharacters(4, '$%^&');                          // &$&^
2generateCharacters(6, '0123456789');                    // 947682
3generateCharacters(6, 'abcdefghijklmnopqrstuvwxyz');    // ihdrnn

secure-password-utilities/constants

1import {DIGIT_CHARSET, LOWERCASE_CHARSET, UPPERCASE_CHARSET, SYMBOL_CHARSET} from 'secure-password-utilities/constants'

DIGIT_CHARSET

1const DIGIT_CHARSET = "0123456789";

LOWERCASE_CHARSET

1const LOWERCASE_CHARSET = "abcdefghijklmnopqrstuvwxyz";

UPPERCASE_CHARSET

1const UPPERCASE_CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";

SYMBOL_CHARSET

1// OWASP password special characters except space and backslash.
2//
3//     See https://owasp.org/www-community/password-special-characters
4//
5const SYMBOL_CHARSET = "!\"#$%&'()*+,-./:;<=>?@[]{}^_`|~";

secure-password-utilities/csprng

1import {getRandomBytes} from 'secure-password-utilities/csprng'

getRandomBytes

1function getRandomBytes(numBytes: number): Uint8Array;

Generates random bytes. This is a wrapper around the platform's native CSPRNG. In node, this will be randomBytes from the standard library. In the browser, this will be crypto.getRandomValues.

secure-password-utilities/random

1import {getRandomNumbersInRange, getRandomValues, randomizeCharacters} from 'secure-password-utilities/random'

getRandomNumbersInRange

1function getRandomNumbersInRange(length: number, start: number, end: number): number[]

Get a list of random numbers where each number is greater than or equal to start and less than end.

The end of the range must be less than or equal to 2^16.

1getRandomNumbersInRange(6, 0, 10) // [8, 2, 1, 3, 5, 0]
2getRandomNumbersInRange(6, 10, 20); // [ 18, 10, 13, 12, 12, 19 ]
3getRandomNumbersInRange(6, 0, 1000); // [111, 752, 41, 420, 360, 630]

getRandomValues

Note: This is deprecated, use getRandomNumbersInRange instead.

1function getRandomValues(numValues: number, rangeMax?: number): Uint8Array

Get random values between 0 and rangeMax (at most, 256 exclusive) from a CSPRNG.

This is a helper function to safely filter random byte values into a desired range. "safely" here meaning careful use of the modulo operator to avoid modulo bias.

randomizeCharacters

1function randomizeCharacters(characters: string): string

Randomize the ordering of the characters in the given string.

1randomizeCharacters('randomize me');     // e znmaedimro
2randomizeCharacters('randomize me');     // arndimz moee
3randomizeCharacters('randomize me');     // ai emdonmrze

secure-password-utilities/wordlists

1import {DEFAULT_WORDLIST, EFF_LONG_WORDLIST} from 'secure-password-utilities/wordlists'

DEFAULT_WORDLIST

1const DEFAULT_WORDLIST = Object.freeze([/* EFF long wordlist minus a few entries (see below) */]);

This is the "default" wordlist for use with this library. It is the same as the EFF long wordlist but with the following entries removed:

• drop-down
• flet-tip
• t-shirt
• yo-yo

The reason for this is that a frequent passphrase separator is the "-" which can then result in ambiguous word separations. This keeps the resulting passphrase prettier (in the case where it's joined by dashes) with an unambiguous and deterministic number of dashes.

EFF_LONG_WORDLIST

1const EFF_LONG_WORDLIST = Object.freeze([/* EFF long wordlist, see https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt */]);

The EFF recommended wordlist for passphrases.

License

The MIT License (MIT). See LICENSE file.