🔐 @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 doruk.karaboncuk@interaktifis.com

📄 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: doruk.karaboncuk@interaktifis.com
GitHub Issues: Create an issue

Made with ❤️ by @chaisser

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
test		test
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

🔐 @chaisser/password-strength

✨ Features

📦 Installation

🚀 Quick Start

📖 What It Does

🎯 How It Works

🎨 What It's Useful For

💡 Usage Examples

Check Strength

Custom Options

Full Analysis

Crack Time Estimation

Validate Against Criteria

Generate Password

Compare Passwords

Suggest Improvements

Mask Password

Password Requirements Text

Check Against Common Lists

📚 API Reference

checkStrength(password, options?)

analyzePassword(password)

validateCriteria(password, criteria)

calculateEntropy(password)

calculateCrackTime(entropy, attemptsPerSecond?)

generatePassword(length?, options?)

suggestStronger(password, options?)

comparePasswords(password1, password2)

maskPassword(password, visibleChars?)

checkAgainstLists(password)

getPasswordRequirements(options?)

getStrengthPercentage(password, options?)

getStrengthMessage(password, options?)

Strength Levels

🔗 Related Packages

🔒 License

👨 Developed by

📄 Repository

🤝 Contributing

📞 Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`checkStrength(password, options?)`

`analyzePassword(password)`

`validateCriteria(password, criteria)`

`calculateEntropy(password)`

`calculateCrackTime(entropy, attemptsPerSecond?)`

`generatePassword(length?, options?)`

`suggestStronger(password, options?)`

`comparePasswords(password1, password2)`

`maskPassword(password, visibleChars?)`

`checkAgainstLists(password)`

`getPasswordRequirements(options?)`

`getStrengthPercentage(password, options?)`

`getStrengthMessage(password, options?)`

Packages