🔐 @chaisser/password-strength

Password strength checker with entropy calculation, crack time estimation, and detailed analysis

✨ Features

• 🎯 Type-safe - Full TypeScript support with detailed result interfaces
• 📊 Scoring - 0-100 score with 6 strength levels
• 🧮 Entropy - Shannon entropy calculation
• ⏱️ Crack Time - Estimated time to brute-force
• 🔍 Analysis - Detailed breakdown of character types, patterns, common passwords
• ✅ Validation - Configurable criteria validation (length, numbers, special chars, etc.)
• 🔑 Generation - Generate strong random passwords
• 💡 Suggestions - Get tips to improve weak passwords
• 📋 Comparison - Compare two passwords and see which is stronger
• 🎭 Masking - Mask passwords for safe display
• 🪶 Zero dependencies - Lightweight and tree-shakeable
• 🏎️ ESM + CJS - Dual module format support

📦 Installation

npm install @chaisser/password-strength
# or
yarn add @chaisser/password-strength
# or
pnpm add @chaisser/password-strength

🚀 Quick Start

import {
  checkStrength,
  analyzePassword,
  validateCriteria,
  generatePassword,
  calculateCrackTime,
} from '@chaisser/password-strength';

// Check strength
const result = checkStrength('MyP@ssw0rd!');
console.log(result.score);     // 0-100
console.log(result.strength);  // 'very weak' | 'weak' | 'fair' | 'good' | 'strong' | 'very strong'
console.log(result.warning);   // Improvement suggestion
console.log(result.entropy);   // Shannon entropy

// Full analysis
const analysis = analyzePassword('MyP@ssw0rd!');
console.log(analysis.timeToCrack);    // "X years"
console.log(analysis.hasUppercase);   // true
console.log(analysis.hasSpecialChars); // true

// Validate against custom rules
const { valid, errors } = validateCriteria('pass', {
  minLength: 8,
  minNumbers: 1,
  minSpecialChars: 1,
  minUppercase: 1,
});
console.log(valid);   // false
console.log(errors);  // ["Password must be at least 8 characters", ...]

// Generate a strong password
const password = generatePassword(16);

📖 What It Does

This package provides comprehensive password strength analysis. It calculates Shannon entropy, detects common passwords and keyboard patterns, checks character variety, estimates brute-force crack time, and produces an overall strength score. It also includes utilities for password generation, validation against custom criteria, comparison, and masking.

🎯 How It Works

The package uses multiple analysis layers:

• Length check - Minimum length gate (configurable, default 8)
• Common password list - Blocks known weak passwords
• Shannon entropy - Measures information density of the password
• Character variety - Checks for lowercase, uppercase, numbers, special chars
• Pattern detection - Flags sequences (abc, 123), repeats, keyboard patterns (qwerty)
• Crack time estimation - Calculates time to brute-force at 10B guesses/sec

🎨 What It's Useful For

• Registration Forms - Show real-time password strength feedback
• Password Policies - Enforce custom validation rules
• Security Audits - Analyze password strength across user accounts
• Password Generators - Build secure password creation tools
• User Guidance - Provide actionable suggestions for improving passwords
• Compliance - Meet password policy requirements (NIST, PCI-DSS)

💡 Usage Examples

Check Strength

import { checkStrength } from '@chaisser/password-strength';

checkStrength('password');
// { score: 0, strength: 'very weak', warning: 'Password is too common', entropy: 0 }

checkStrength('MyP@ssw0rd!2024');
// { score: 80, strength: 'very strong', warning: 'Excellent password', entropy: 47.2 }

Custom Options

checkStrength('abc123', {
  minPasswordLength: 6,   // minimum length (default: 8)
  minEntropy: 30,         // minimum entropy (default: 40)
  useEntropy: true,       // include entropy in scoring (default: true)
  checkCommonPasswords: true, // check common list (default: true)
});

Full Analysis

import { analyzePassword } from '@chaisser/password-strength';

const analysis = analyzePassword('K#9m$Xp2!vLq');

console.log(analysis);
// {
//   length: 12,
//   hasLowercase: true,
//   hasUppercase: true,
//   hasNumbers: true,
//   hasSpecialChars: true,
//   common: false,
//   entropy: 48.5,
//   score: 92,
//   strength: 'very strong',
//   timeToCrack: '245 years'
// }

Crack Time Estimation

import { calculateCrackTime } from '@chaisser/password-strength';

calculateCrackTime(0);    // 'instant'
calculateCrackTime(20);   // '1 seconds'
calculateCrackTime(40);   // '38 days'
calculateCrackTime(60);   // '107 years'
calculateCrackTime(80);   // '10907 years'

// Custom attack speed (1 trillion guesses/sec)
calculateCrackTime(60, 1_000_000_000_000);

Validate Against Criteria

import { validateCriteria } from '@chaisser/password-strength';

const { valid, errors } = validateCriteria('pass123', {
  minLength: 8,
  maxLength: 128,
  minNumbers: 2,
  minSpecialChars: 1,
  minLowercase: 1,
  minUppercase: 1,
});

console.log(valid);   // false
console.log(errors);
// [
//   'Password must be at least 8 characters',
//   'Password must contain at least 1 special character(s)',
//   'Password must contain at least 1 uppercase letter(s)'
// ]

Generate Password

import { generatePassword } from '@chaisser/password-strength';

// Generate 16-character password
generatePassword(16); // 'K#9m$Xp2!vLqR@n7'

// Generate with minimum requirements
generatePassword(20, { minPasswordLength: 12, minEntropy: 50 });

Compare Passwords

import { comparePasswords } from '@chaisser/password-strength';

comparePasswords('password', 'K#9m$Xp2!');
// { stronger: 'K#9m$Xp2!', weaker: 'password', tie: false }

Suggest Improvements

import { suggestStronger } from '@chaisser/password-strength';

suggestStronger('monkey');
// ['monkey!', 'MONKEY', 'monkeykey']

suggestStronger('K#9m$Xp2!vLq');
// [] (already very strong)

Mask Password

import { maskPassword } from '@chaisser/password-strength';

maskPassword('MySecretPass123', 2);  // 'My*************'
maskPassword('short', 3);            // 'short' (too short to mask)

Password Requirements Text

import { getPasswordRequirements } from '@chaisser/password-strength';

getPasswordRequirements({
  minLength: 12,
  minNumbers: 1,
  minSpecialChars: 1,
  minUppercase: 1,
});
// [
//   'At least 12 characters',
//   'At least 1 number(s)',
//   'At least 1 special character(s)',
//   'At least 1 uppercase letter(s)'
// ]

Check Against Common Lists

import { checkAgainstLists } from '@chaisser/password-strength';

checkAgainstLists('password');
// { foundIn: ['top10'], recommendations: ['Avoid using this common password'] }

checkAgainstLists('hello');
// { foundIn: ['singleWord'], recommendations: ['Consider using a passphrase'] }

📚 API Reference

checkStrength(password, options?)

Returns a strength assessment.

| Parameter | Type | Default | Description | |---|---|---|---| | password | string | - | Password to check | | options.minPasswordLength | number | 8 | Minimum acceptable length | | options.minEntropy | number | 40 | Minimum entropy threshold | | options.useEntropy | boolean | true | Include entropy in scoring | | options.checkCommonPasswords | boolean | true | Check against common list |

Returns: { score, strength, warning, entropy }

analyzePassword(password)

Full password analysis with all metrics.

Returns: { length, hasLowercase, hasUppercase, hasNumbers, hasSpecialChars, common, entropy, score, strength, timeToCrack }

validateCriteria(password, criteria)

Validate against custom rules.

| Criteria | Type | Description | |---|---|---| | minLength | number | Minimum length | | maxLength | number | Maximum length | | minNumbers | number | Minimum digit count | | minSpecialChars | number | Minimum special char count | | minLowercase | number | Minimum lowercase letters | | minUppercase | number | Minimum uppercase letters |

Returns: { valid, errors }

calculateEntropy(password)

Calculate Shannon entropy of a password.

Returns: number

calculateCrackTime(entropy, attemptsPerSecond?)

Estimate brute-force crack time.

| Parameter | Type | Default | Description | |---|---|---|---| | entropy | number | - | Entropy value | | attemptsPerSecond | number | 10_000_000_000 | Attack speed |

Returns: string (e.g. "245 years")

generatePassword(length?, options?)

Generate a random strong password.

Returns: string

suggestStronger(password, options?)

Suggest stronger variations of a password.

Returns: string[]

comparePasswords(password1, password2)

Compare strength of two passwords.

Returns: { stronger, weaker, tie }

maskPassword(password, visibleChars?)

Mask a password for display.

Returns: string

checkAgainstLists(password)

Check against common password lists.

Returns: { foundIn, recommendations }

getPasswordRequirements(options?)

Get human-readable password requirements.

Returns: string[]

getStrengthPercentage(password, options?)

Get strength score as a number (0-100).

Returns: number

getStrengthMessage(password, options?)

Get a descriptive strength message.

Returns: string

Strength Levels

| Score Range | Strength | |---|---| | 0-19 | very weak | | 20-39 | weak | | 40-59 | fair | | 60-79 | good | | 80+ | very strong |

🔗 Related Packages

Explore our other utility packages in the @chaisser namespace:

• @chaisser/password-strength (this package) - Password strength checker
• @chaisser/string-wizard - Advanced string manipulation
• @chaisser/type-guard - Runtime type guards and validators
• @chaisser/uuid-v7 - Time-ordered UUID v7 generator
• @chaisser/wait-for - Promise-based wait utilities
• @chaisser/regex-humanizer - Regex to human-readable descriptions
• @chaisser/human-time - Human-readable time formatting
• @chaisser/obj-path - Object path traversal
• @chaisser/debounce-throttle - Rate limiting utilities
• @chaisser/color-utils - Color conversion utilities
• @chaisser/deep-clone - Deep cloning functions
• @chaisser/array-group-by - Array grouping utilities
• @chaisser/merge-objects - Object merge utilities
• @chaisser/chunk-array - Array chunking functions
• @chaisser/event-emitter - Typed event emitter

🔒 License

MIT - Free to use in personal and commercial projects

👨 Developed by

Doruk Karaboncuk [email protected]

📄 Repository

• GitHub: @chaisser
• NPM: @chaisser/password-strength

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📞 Support

For issues, questions, or suggestions, please reach out through:

• Email: [email protected]
• GitHub Issues: Create an issue

Made with ❤️ by @chaisser