Package Exports

secure-password-utilities
secure-password-utilities/constants
secure-password-utilities/csprng
secure-password-utilities/random

Readme

secure-password-utilities

Secure, zero-dependency utilities for generating passwords, 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
secure-password-utilities/constants
secure-password-utilities/csprng
- getRandomBytes
secure-password-utilities/random
- getRandomValues
- randomizeCharacters

secure-password-utilities

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

generatePassword

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

Generates a random password.

Uses a CSPRNG for randomness.

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

generatePin

function generatePin(length: number): string

Generate a random digit pin.

Uses a CSPRNG for randomness.

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.

Uses a CSPRNG for randomness.

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 {getRandomValues, randomizeCharacters} from 'secure-password-utilities/random'

getRandomValues

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.

Uses a CSPRNG for randomness.

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

License

The MIT License (MIT). See LICENSE file.