pwordgen

A tiny, TypeScript-native password generator for browser and Node.js environments.

Installation

npm install pwordgen

Quick Start

import { generatePassword, estimateEntropyBits } from 'pwordgen';

// Generate a password with defaults (16 chars, all character classes)
const password = generatePassword();

// Estimate entropy
const entropy = estimateEntropyBits({ length: 16 });
console.log(`Entropy: ${entropy.toFixed(1)} bits`);

API

generatePassword(options?): string

Generates a cryptographically secure password.

interface PasswordOptions {
  length: number; // Default: 16
  lowercase: boolean; // Default: true
  uppercase: boolean; // Default: true
  digits: boolean; // Default: true
  symbols: boolean; // Default: true
  custom: string; // Default: ''
  excludeSimilar: boolean; // Default: false (excludes il1Lo0O)
  exclude: string; // Default: ''
  requireEachSelectedClass: boolean; // Default: false
}

Examples

// Custom length
generatePassword({ length: 12 });

// Letters only
generatePassword({ digits: false, symbols: false });

// Exclude similar characters
generatePassword({ excludeSimilar: true });

// Custom character set
generatePassword({
  lowercase: false,
  uppercase: false,
  digits: false,
  symbols: false,
  custom: 'ABCDEF0123456789',
});

// Ensure at least one from each selected class
generatePassword({
  length: 12,
  requireEachSelectedClass: true,
});

estimateEntropyBits(options?): number

Calculates estimated entropy in bits for the given configuration.

const entropy = estimateEntropyBits({
  length: 12,
  digits: false,
  symbols: false,
});

Character Classes

import { CHARACTER_CLASSES } from 'pwordgen';

CHARACTER_CLASSES.lowercase; // "abcdefghijklmnopqrstuvwxyz"
CHARACTER_CLASSES.uppercase; // "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
CHARACTER_CLASSES.digits; // "0123456789"
CHARACTER_CLASSES.symbols; // "!@#$%^&*()_+-=[]{}|;:,.<>?"
CHARACTER_CLASSES.similar; // "il1Lo0O"

Security

• Uses Web Crypto API (browser) and Node.js crypto module
• Rejection sampling ensures uniform distribution
• No network calls or telemetry
• Cryptographically secure random number generation

Browser Support

Chrome 37+, Firefox 34+, Safari 7.1+, Edge 12+

Node.js Support

Node.js 16+

Development

npm install          # Install dependencies
npm test             # Run tests
npm run build        # Build package
npm run lint         # Lint code
npm run prettier:fix # Format code

License

MIT