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
generatePinis less than a kilobyte gzipped
npm install secure-password-utilities
Basic usage:
import {generatePassword, generatePin} from 'secure-password-utilities';
// Defaults include all uppercase/lowercase characters, digits, and symbols.
const password = generatePassword(12);
console.log(password); // l[Nz8UfU.o4g
const pin = generatePin(6);
console.log(pin); // 036919- secure-password-utilities
- secure-password-utilities/constants
- secure-password-utilities/csprng
- secure-password-utilities/random
- secure-password-utilities/wordlists
import {generatePassword, generatePassphrase, generatePin, generateCharacters} from 'secure-password-utilities'function generatePassword(length: number, options?: PasswordOptionsType): stringGenerates a random password.
PasswordOptionsType is defined as:
type PasswordOptionType =
// `true` means include [character type], `false` means exclude [character type]
| boolean
// <number> means include exactly <number> [character type]s
| number
// { min: <number> } means include at least <number> [character type]s
| { min: number };
export type PasswordOptionsType = {
digits?: PasswordOptionType;
symbols?: PasswordOptionType;
lowercase?: PasswordOptionType;
uppercase?: PasswordOptionType;
charset?: {
digits?: string;
symbols?: string;
lowercase?: string;
uppercase?: string;
};
};Examples:
// Contains only letters (upper and lowercase) and digits.
const alphanumericPassword = generatePassword(10, { symbols: false });
console.log(alphanumericPassword); // 49Faqzd8jx
const password = generatePassword(12, {
symbols: 2, // Resulting password must contain exactly two symbols.
uppercase: { min: 1 }, // Resulting password must contain a minimum of 1 upperase character.
});
console.log(password); // b1yT6$jO`kvf
const uppercasePassword = generatePassword(10, {
digits: false, // Resulting password must NOT contain any digits.
symbols: false, // Resulting password must NOT contain any symbols.
lowercase: false, // Resulting password must NOT contain any lowercase characters.
});
console.log(uppercasePassword); // IHDPPZRNPSYou can override the character set used for each option using the charset option, e.g.:
// Ensure exactly three symbols are present in the resulting
// password using the following values for 'symbols':
//
// ! @ # $ %
//
const password = generatePassword(12, {
symbols: 3,
charset: { symbols: '!@#$%' },
});
console.log(password); // A@D#tkG!ymFE
// Generate a 12-character password with at least 3 digits and no symbols.
// For the digits, only use even digits, i.e., 0, 2, 4, 6, 8.
const evenDigitPassword = generatePassword(12, {
digits: { min: 3 },
symbols: false,
charset: { digits: '02468' }
});
console.log(evenDigitPassword); // e6V8zy0kfTANfunction generatePassphrase(length: number, wordlist: readonly string[], sep?: string): stringGenerate 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.
import {DEFAULT_WORDLIST} from 'secure-password-utilities/wordlists';
generatePassphrase(6, DEFAULT_WORDLIST); // canopener-uncanny-hatchet-murky-agony-traitor
generatePassphrase(6, DEFAULT_WORDLIST); // backpack-craftwork-sweat-postcard-imaging-litterThe word separator defaults to a dash (-), but you can customize this behavior using the third argument.
generatePassphrase(6, DEFAULT_WORDLIST, '_'); // goldfish_scorpion_antiviral_pursuit_demanding_mottofunction generatePin(length: number): stringGenerate a random digit pin.
generatePin(6); // 036919
generatePin(8); // 45958396function generateCharacters(length: number, charset: string): stringGenerate a string of length characters chosen randomly from the given charset.
generateCharacters(4, '$%^&'); // &$&^
generateCharacters(6, '0123456789'); // 947682
generateCharacters(6, 'abcdefghijklmnopqrstuvwxyz'); // ihdrnnimport {DIGIT_CHARSET, LOWERCASE_CHARSET, UPPERCASE_CHARSET, SYMBOL_CHARSET} from 'secure-password-utilities/constants'const DIGIT_CHARSET = "0123456789";const LOWERCASE_CHARSET = "abcdefghijklmnopqrstuvwxyz";const UPPERCASE_CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";// OWASP password special characters except space and backslash.
//
// See https://owasp.org/www-community/password-special-characters
//
const SYMBOL_CHARSET = "!\"#$%&'()*+,-./:;<=>?@[]{}^_`|~";import {getRandomBytes} from 'secure-password-utilities/csprng'function 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.
import {getRandomNumbersInRange, getRandomValues, randomizeCharacters} from 'secure-password-utilities/random'function 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.
getRandomNumbersInRange(6, 0, 10) // [8, 2, 1, 3, 5, 0]
getRandomNumbersInRange(6, 10, 20); // [ 18, 10, 13, 12, 12, 19 ]
getRandomNumbersInRange(6, 0, 1000); // [111, 752, 41, 420, 360, 630]Note: This is deprecated, use getRandomNumbersInRange instead.
function getRandomValues(numValues: number, rangeMax?: number): Uint8ArrayGet 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.
function randomizeCharacters(characters: string): stringRandomize the ordering of the characters in the given string.
randomizeCharacters('randomize me'); // e znmaedimro
randomizeCharacters('randomize me'); // arndimz moee
randomizeCharacters('randomize me'); // ai emdonmrzeimport {DEFAULT_WORDLIST, EFF_LONG_WORDLIST} from 'secure-password-utilities/wordlists'const 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.
const 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.
The MIT License (MIT). See LICENSE file.