safepassword-utils
Version:
A secure and flexible password generation and validation utility for TypeScript/JavaScript applications
573 lines (481 loc) • 15.6 kB
Markdown
# 🔒 safe-password-utils
[](https://github.com/TheRealPerson98/safe-password-utils/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/safepassword-utils)
[](https://opensource.org/licenses/MPL-2.0)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
A secure and flexible password validation utility for TypeScript/JavaScript applications with customizable strength requirements.
## ✨ Features
- 🎯 Accurate password strength assessment
- 🛠️ Customizable validation rules
- 📊 Detailed character analysis
- 💪 Multiple strength levels
- 🔍 Character type detection
- 📝 TypeScript support
- 🧪 Comprehensive test coverage
- 🚫 Common password detection (10k to 10M passwords)
- 🎲 Secure password generation
- 🔢 Password entropy calculation
- ⏱️ Crack time estimation
- 🔍 Pattern detection and analysis
- 🧠 Comprehensive password analysis
## 🚫 Common Password Detection
```typescript
import { isCommonPassword } from 'safepassword-utils';
// Check if a password is commonly used
const isCommon = await isCommonPassword('password123');
console.log(isCommon); // true
// Use different size password lists
const sizes = ['10k', '100k', '250k', '500k', '1m', '2m', '5m', '10m'];
const result = await isCommonPassword('mypassword', '1m'); // Checks against 1 million passwords
```
## 🎲 Password Generation
```typescript
import { generatePassword } from 'safepassword-utils';
// Generate a strong password with default options (16 characters, all character types)
const password = generatePassword();
// Generate a password with custom options
const customPassword = generatePassword({
length: 20, // Custom length
includeUppercase: true, // Include uppercase letters
includeLowercase: true, // Include lowercase letters
includeNumbers: true, // Include numbers
includeSymbols: true, // Include special characters
excludeSimilarCharacters: true, // Exclude similar characters (i, l, 1, L, o, 0, O)
excludeAmbiguousCharacters: true // Exclude ambiguous characters ({}, [], (), /\, etc.)
});
// Generate a simple password with only lowercase and numbers
const simplePassword = generatePassword({
includeUppercase: false,
includeSymbols: false
});
```
## 🔢 Password Entropy
```typescript
import { calculatePasswordEntropy } from 'safepassword-utils';
// Calculate password entropy
const result = calculatePasswordEntropy('MySecureP@ssw0rd');
console.log(result);
// {
// entropy: 75.98, // Entropy in bits
// poolSize: 95, // Size of character pool
// length: 14, // Password length
// characterSets: { // Used character types
// lowercase: true,
// uppercase: true,
// numbers: true,
// symbols: true
// }
// }
// Interpreting entropy values:
// < 28 bits = Very Weak (may be cracked instantly)
// 28-35 bits = Weak (may be cracked in seconds)
// 36-59 bits = Reasonable (may take hours to crack)
// 60-127 bits = Strong (may take years to crack)
// 128+ bits = Very Strong (practically uncrackable with current technology)
```
## ⏱️ Crack Time Estimation
```typescript
import { estimateCrackTime } from 'safepassword-utils';
// Estimate how long it would take to crack a password
const result = estimateCrackTime('MySecureP@ssw0rd');
console.log(result);
// {
// // Raw time estimates in seconds
// onlineThrottling100PerHour: 1.2e24,
// onlineNoThrottling10PerSecond: 3.4e20,
// offlineSlowHashing1e4PerSecond: 3.4e16,
// offlineFastHashing1e10PerSecond: 3.4e10,
//
// // Human readable estimates
// timeToCrack: {
// onlineThrottling: 'centuries', // Online attack, limited to 100 attempts per hour
// onlineNoThrottling: '108 years', // Online attack, 10 attempts per second
// offlineSlowHashing: '13 months', // Offline attack, 10k attempts per second
// offlineFastHashing: '4 days' // Offline attack, 10B attempts per second
// }
// }
// Different attack scenarios:
// 1. Online throttled: Simulates a login form with rate limiting (100 attempts/hour)
// 2. Online no throttling: Simulates unprotected online system (10 attempts/second)
// 3. Offline slow hash: Offline attack with slow hash function (10k attempts/second)
// 4. Offline fast hash: Offline attack with fast hash function (10B attempts/second)
```
## 🔍 Password Pattern Analysis
```typescript
import { analyzePasswordPatterns } from 'safepassword-utils';
// Analyze a password for common patterns
const analysis = analyzePasswordPatterns('qwerty123');
console.log(analysis);
// {
// hasKeyboardPattern: true,
// hasSequentialChars: false,
// hasRepeatedChars: false,
// hasDatePattern: false,
// patternRiskScore: 30,
// detectedPatterns: ['Keyboard pattern: "qwerty"'],
// suggestions: ['Avoid keyboard patterns like "qwerty" or "asdfgh"']
// }
// Analyze a password with multiple patterns
const complexAnalysis = analyzePasswordPatterns('abc123456');
console.log(complexAnalysis);
// {
// hasKeyboardPattern: false,
// hasSequentialChars: true,
// hasRepeatedChars: false,
// hasDatePattern: false,
// patternRiskScore: 25,
// detectedPatterns: ['Sequential letters: "abc"', 'Sequential numbers: "123"'],
// suggestions: ['Avoid sequential characters like "abc" or "123"']
// }
```
## 🧠 Comprehensive Password Analysis
```typescript
import { analyzePassword } from 'safepassword-utils';
// Get a complete analysis of a password
const fullAnalysis = analyzePassword('Password123!');
console.log(fullAnalysis);
// {
// // Strength assessment
// strength: {
// id: 2,
// value: 'Medium',
// contains: { lowercase: true, uppercase: true, number: true, symbol: true },
// length: 12,
// counts: { lowercase: 7, uppercase: 1, numbers: 3, special: 1 }
// },
// // Entropy calculation
// entropy: {
// entropy: 70.24,
// poolSize: 95,
// length: 12,
// characterSets: { lowercase: true, uppercase: true, numbers: true, symbols: true }
// },
// // Crack time estimation
// crackTime: {
// onlineThrottling100PerHour: 3.8e21,
// onlineNoThrottling10PerSecond: 1.1e18,
// offlineSlowHashing1e4PerSecond: 1.1e14,
// offlineFastHashing1e10PerSecond: 1.1e8,
// timeToCrack: {
// onlineThrottling: 'centuries',
// onlineNoThrottling: 'centuries',
// offlineSlowHashing: '3 years',
// offlineFastHashing: '3 days'
// }
// },
// // Pattern analysis
// patterns: {
// hasKeyboardPattern: false,
// hasSequentialChars: false,
// hasRepeatedChars: false,
// hasDatePattern: false,
// patternRiskScore: 0,
// detectedPatterns: [],
// suggestions: []
// }
// }
```
## 📦 Installation
```bash
npm install safepassword-utils
# or
yarn add safepassword-utils
# or
pnpm add safepassword-utils
```
## 🚀 Quick Start
```typescript
import { checkPasswordStrength } from 'safepassword-utils';
// Basic usage
const result = checkPasswordStrength('MyPassword123!');
console.log(result);
// {
// id: 3,
// value: 'Strong',
// contains: {
// lowercase: true,
// uppercase: true,
// number: true,
// symbol: true
// },
// length: 13,
// counts: {
// lowercase: 7,
// uppercase: 2,
// numbers: 3,
// special: 1
// }
// }
```
## 🛠️ Advanced Usage
### Custom Requirements
```typescript
import { checkPasswordStrength } from 'safepassword-utils';
const requirements = {
requireCapital: true,
requireNumber: true,
requireSpecial: true,
minCapitals: 2,
minNumbers: 2,
minSpecial: 1
};
const result = checkPasswordStrength('MyPass12!', requirements);
```
### Custom Strength Options
```typescript
import { checkPasswordStrength } from 'safepassword-utils';
const customOptions = [
{
id: 0,
value: "Too weak",
minDiversity: 0,
minLength: 0
},
{
id: 1,
value: "Weak",
minDiversity: 2,
minLength: 6
},
{
id: 2,
value: "Medium",
minDiversity: 3,
minLength: 8
},
{
id: 3,
value: "Strong",
minDiversity: 4,
minLength: 10
}
];
const result = checkPasswordStrength('MyPassword1!', undefined, customOptions);
```
## 📊 Return Examples
### Too Weak Password
```typescript
checkPasswordStrength('abc');
{
id: 0,
value: 'Too weak',
contains: {
lowercase: true,
uppercase: false,
number: false,
symbol: false
},
length: 3,
counts: {
lowercase: 3,
uppercase: 0,
numbers: 0,
special: 0
}
}
```
### Weak Password
```typescript
checkPasswordStrength('password123');
{
id: 1,
value: 'Weak',
contains: {
lowercase: true,
uppercase: false,
number: true,
symbol: false
},
length: 11,
counts: {
lowercase: 8,
uppercase: 0,
numbers: 3,
special: 0
}
}
```
### Medium Password
```typescript
checkPasswordStrength('Pass1!word');
{
id: 2,
value: 'Medium',
contains: {
lowercase: true,
uppercase: true,
number: true,
symbol: true
},
length: 10,
counts: {
lowercase: 5,
uppercase: 1,
numbers: 1,
special: 1
}
}
```
### Strong Password
```typescript
checkPasswordStrength('MySecureP@ss123');
{
id: 3,
value: 'Strong',
contains: {
lowercase: true,
uppercase: true,
number: true,
symbol: true
},
length: 15,
counts: {
lowercase: 8,
uppercase: 3,
numbers: 3,
special: 1
}
}
```
### With Custom Requirements (Failed)
```typescript
checkPasswordStrength('password123', { requireSpecial: true });
{
id: 0,
value: 'Too weak',
contains: {
lowercase: true,
uppercase: false,
number: true,
symbol: false
},
length: 11,
counts: {
lowercase: 8,
uppercase: 0,
numbers: 3,
special: 0
}
}
```
### With Custom Requirements (Passed)
```typescript
checkPasswordStrength('MyP@ss123!', {
requireCapital: true,
requireSpecial: true,
minSpecial: 2
});
{
id: 2,
value: 'Medium',
contains: {
lowercase: true,
uppercase: true,
number: true,
symbol: true
},
length: 10,
counts: {
lowercase: 3,
uppercase: 2,
numbers: 3,
special: 2
}
}
```
## 📋 API Reference
### `checkPasswordStrength(password, requirements?, options?)`
Analyzes password strength based on length, character diversity, and custom requirements.
#### Parameters
- `password: string` - The password to analyze
- `requirements?: PasswordRequirements` - Optional custom requirements
- `requireCapital?: boolean` - Require capital letters
- `requireNumber?: boolean` - Require numbers
- `requireSpecial?: boolean` - Require special characters
- `minCapitals?: number` - Minimum number of capital letters
- `minNumbers?: number` - Minimum number of numbers
- `minSpecial?: number` - Minimum number of special characters
- `options?: PasswordOption[]` - Custom strength level options
### `generatePassword(options?)`
Generates a secure random password with customizable options.
#### Parameters
- `options?: PasswordGenerationOptions` - Optional generation settings
- `length?: number` - Password length (default: 16)
- `includeUppercase?: boolean` - Include uppercase letters (default: true)
- `includeLowercase?: boolean` - Include lowercase letters (default: true)
- `includeNumbers?: boolean` - Include numbers (default: true)
- `includeSymbols?: boolean` - Include special characters (default: true)
- `excludeSimilarCharacters?: boolean` - Exclude similar characters like i, l, 1, O, 0 (default: false)
- `excludeAmbiguousCharacters?: boolean` - Exclude ambiguous characters like {}, [], () (default: false)
#### Default Strength Levels
| Level | Min Length | Min Diversity | Description |
|----------|------------|---------------|--------------------------------|
| Too weak | 0 | 0 | Fails minimum requirements |
| Weak | 8 | 2 | Basic requirements met |
| Medium | 10 | 4 | Good password strength |
| Strong | 12 | 4 | Excellent password strength |
### `calculatePasswordEntropy(password)`
Calculates the entropy (randomness) of a password in bits.
#### Parameters
- `password: string` - The password to analyze
#### Returns
- `EntropyDetails` object containing:
- `entropy: number` - Entropy value in bits
- `poolSize: number` - Size of the character pool
- `length: number` - Password length
- `characterSets: object` - Used character types
- `lowercase: boolean`
- `uppercase: boolean`
- `numbers: boolean`
- `symbols: boolean`
### `estimateCrackTime(password)`
Estimates the time required to crack a password under different attack scenarios.
#### Parameters
- `password: string` - The password to analyze
#### Returns
- `CrackTimeEstimates` object containing:
- Raw time estimates (in seconds):
- `onlineThrottling100PerHour: number`
- `onlineNoThrottling10PerSecond: number`
- `offlineSlowHashing1e4PerSecond: number`
- `offlineFastHashing1e10PerSecond: number`
- Human readable estimates:
- `timeToCrack: object`
- `onlineThrottling: string`
- `onlineNoThrottling: string`
- `offlineSlowHashing: string`
- `offlineFastHashing: string`
### `analyzePasswordPatterns(password)`
Analyzes a password for common patterns that might make it vulnerable to guessing or dictionary attacks.
#### Parameters
- `password: string` - The password to analyze
#### Returns
- `PasswordPatternAnalysis` object containing:
- `hasKeyboardPattern: boolean` - Whether the password contains keyboard patterns (e.g., 'qwerty')
- `hasSequentialChars: boolean` - Whether the password contains sequential characters (e.g., 'abc', '123')
- `hasRepeatedChars: boolean` - Whether the password contains repeated characters (e.g., 'aaa', '111')
- `hasDatePattern: boolean` - Whether the password contains date patterns (e.g., '1990', '2023')
- `patternRiskScore: number` - Overall risk score from 0 (no patterns) to 100 (highly patterned)
- `detectedPatterns: string[]` - Specific patterns detected in the password
- `suggestions: string[]` - Suggestions to improve the password
### `analyzePassword(password)`
Provides a comprehensive analysis of a password by combining strength checking, entropy calculation, crack time estimation, and pattern detection.
#### Parameters
- `password: string` - The password to analyze
#### Returns
- A comprehensive object containing:
- `strength: PasswordStrength` - Password strength assessment
- `entropy: EntropyDetails` - Entropy calculation
- `crackTime: CrackTimeEstimates` - Crack time estimation
- `patterns: PasswordPatternAnalysis` - Pattern analysis
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
This project is licensed under the Mozilla Public License Version 2.0 - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with TypeScript
- Tested with Jest
- Maintained by [Jace Sleeman](https://github.com/TheRealPerson98)
---
<p align="center">Made with ❤️ for the open source community</p>