or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-generate-password

Easy library for generating unique passwords with extensive customization options.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/generate-password@1.7.x

To install, run

npx @tessl/cli install tessl/npm-generate-password@1.7.0

index.mddocs/

Generate Password

Generate Password is a comprehensive library for generating secure, random passwords with extensive customization options. It provides cryptographically secure password generation using Node.js crypto module with configurable character pools, length requirements, exclusion rules, and strict mode validation to ensure passwords meet specific requirements.

Package Information

  • Package Name: generate-password
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install generate-password

Core Imports

const generator = require('generate-password');

For TypeScript:

import { generate, generateMultiple, GenerateOptions } from 'generate-password';

Basic Usage

const generator = require('generate-password');

// Generate a single password with default options
const password = generator.generate();
// Example output: 'Tbv95D8r1P'

// Generate a password with custom options
const customPassword = generator.generate({
  length: 12,
  numbers: true,
  symbols: true,
  lowercase: true,
  uppercase: true,
  excludeSimilarCharacters: true,
  strict: true
});
// Example output: 'L4kD9#pQ2!mN'

// Generate multiple passwords at once
const passwords = generator.generateMultiple(3, {
  length: 8,
  numbers: true
});
// Example output: ['uE8MrW32', 'kL9pQ4vX', 'N7xV2mR8']

Architecture

Generate Password employs a robust cryptographic architecture designed for security and flexibility:

  • Cryptographic Foundation: Uses Node.js crypto.randomBytes() for cryptographically secure random number generation
  • Character Pool System: Dynamically constructs character pools based on configuration options (lowercase, uppercase, numbers, symbols)
  • Unbiased Selection: Implements rejection sampling to ensure uniform distribution across character pools, eliminating modulo bias
  • Batch Processing: Generates random bytes in 256-byte batches to optimize crypto operations while maintaining security
  • Strict Mode Validation: Recursively regenerates passwords that don't meet complexity requirements using pattern matching
  • Configurable Exclusion: Supports character filtering through similar character exclusion and custom exclusion lists

Capabilities

Single Password Generation

Generate one password with customizable options.

/**
 * Generate one password with the given options
 * @param {GenerateOptions} [options] - Configuration options for password generation
 * @returns {string} Generated password
 * @throws {TypeError} "Length must correlate with strict guidelines" when strict mode constraints conflict with length
 * @throws {TypeError} "At least one rule for pools must be true" when all character pools are disabled
 */
function generate(options?: GenerateOptions): string;

Bulk Password Generation

Generate multiple passwords at once with the same configuration.

/**
 * Bulk generate multiple passwords at once, with the same options for all
 * @param {number} amount - Number of passwords to generate
 * @param {GenerateOptions} [options] - Configuration options for password generation
 * @returns {string[]} Array of generated passwords
 * @throws {TypeError} Same exceptions as generate()
 */
function generateMultiple(amount: number, options?: GenerateOptions): string[];

Configuration Options

GenerateOptions Interface

interface GenerateOptions {
  /**
   * Length of the generated password
   * @default 10
   */
  length?: number;
  
  /**
   * Should the password include numbers
   * @default false
   */
  numbers?: boolean;
  
  /**
   * Should the password include symbols, or symbols to include
   * @default false
   */
  symbols?: boolean | string;
  
  /**
   * Should the password include lowercase characters
   * @default true
   */
  lowercase?: boolean;
  
  /**
   * Should the password include uppercase characters
   * @default true
   */
  uppercase?: boolean;
  
  /**
   * Should exclude visually similar characters like 'i' and 'I'
   * @default false
   */
  excludeSimilarCharacters?: boolean;
  
  /**
   * List of characters to be excluded from the password
   * @default ""
   */
  exclude?: string;
  
  /**
   * Password should include at least one character from each pool
   * @default false
   */
  strict?: boolean;
}

Advanced Usage Examples

Custom Symbol Sets

You can specify custom symbols instead of using the default symbol set:

const passwordWithCustomSymbols = generator.generate({
  length: 12,
  numbers: true,
  symbols: '!@#$%', // Use only these specific symbols
  strict: true
});

Character Exclusion

Exclude specific characters that might be problematic in certain contexts:

const passwordWithoutConfusing = generator.generate({
  length: 15,
  numbers: true,
  symbols: true,
  excludeSimilarCharacters: true, // Excludes: i, l, L, I, |, `, o, O, 0
  exclude: 'aeiou', // Additionally exclude vowels
  strict: true
});

Strict Mode Requirements

Strict mode ensures the password contains at least one character from each enabled character pool:

// This will always contain at least one uppercase, one lowercase, one number, and one symbol
const strictPassword = generator.generate({
  length: 8,
  numbers: true,
  symbols: true,
  uppercase: true,
  lowercase: true,
  strict: true
});

Character Pools

The library uses the following default character sets:

  • Lowercase: abcdefghijklmnopqrstuvwxyz
  • Uppercase: ABCDEFGHIJKLMNOPQRSTUVWXYZ
  • Numbers: 0123456789
  • Symbols: !@#$%^&*()+_-=}{[]|:;"/?.><,~`
  • Similar Characters (excluded when excludeSimilarCharacters: true): i, l, L, I, |, `, o, O, 0

Error Handling

The library throws TypeError exceptions for invalid configurations:

// Error: Length must correlate with strict guidelines
try {
  generator.generate({
    length: 2,
    strict: true,
    numbers: true,
    symbols: true,
    uppercase: true
    // This requires at least 3 characters (one from each pool) but length is only 2
  });
} catch (error) {
  console.error(error.message);
}

// Error: At least one rule for pools must be true
try {
  generator.generate({
    uppercase: false,
    lowercase: false,
    numbers: false,
    symbols: false
    // No character pools enabled
  });
} catch (error) {
  console.error(error.message);
}

Security Features

  • Cryptographically Secure: Uses Node.js crypto.randomBytes() for secure random number generation
  • Unbiased Random Selection: Implements rejection sampling to ensure uniform distribution across character pools
  • Batch Random Generation: Uses efficient batching to minimize crypto calls while maintaining security
  • Strict Mode Validation: Ensures generated passwords meet complexity requirements through recursive regeneration

Platform Compatibility

  • Node.js: Full support (requires Node.js crypto module)
  • Browser: Not supported (use generate-password-browser package for browser environments)

Common Use Cases

User Registration Systems

// Generate secure passwords for new user accounts
const newUserPassword = generator.generate({
  length: 12,
  numbers: true,
  symbols: true,
  strict: true,
  excludeSimilarCharacters: true
});

API Key Generation

// Generate API keys with alphanumeric characters only
const apiKey = generator.generate({
  length: 32,
  numbers: true,
  symbols: false,
  excludeSimilarCharacters: true
});

Temporary Password Reset

// Generate temporary passwords that are easy to type
const tempPassword = generator.generate({
  length: 8,
  numbers: true,
  symbols: false,
  excludeSimilarCharacters: true,
  exclude: 'aeiouAEIOU' // Exclude vowels to avoid accidental words
});