secure-password-utilities v0.2.1

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:

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

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

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

generatePassword

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

Generates 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); // IHDPPZRNPS

You 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); // e6V8zy0kfTAN

generatePassphrase

function 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.

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-litter

The 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_motto

generatePin

function generatePin(length: number): string

Generate a random digit pin.

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

generateCharacters

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

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

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

secure-password-utilities/constants

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

DIGIT_CHARSET

const DIGIT_CHARSET = "0123456789";

LOWERCASE_CHARSET

const LOWERCASE_CHARSET = "abcdefghijklmnopqrstuvwxyz";

UPPERCASE_CHARSET

const UPPERCASE_CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";

SYMBOL_CHARSET

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

secure-password-utilities/csprng

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

getRandomBytes

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.

secure-password-utilities/random

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

getRandomNumbersInRange

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]

getRandomValues

Note: This is deprecated, use getRandomNumbersInRange instead.

function 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

function randomizeCharacters(characters: string): string

Randomize the ordering of the characters in the given string.

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

secure-password-utilities/wordlists

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

DEFAULT_WORDLIST

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.

EFF_LONG_WORDLIST

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.

License

The MIT License (MIT). See LICENSE file.