safepassword-utils/dist/types/index.d.ts

A secure and flexible password generation and validation utility for TypeScript/JavaScript applications

export interface PasswordRequirements {
    requireCapital?: boolean;
    requireNumber?: boolean;
    requireSpecial?: boolean;
    minCapitals?: number;
    minNumbers?: number;
    minSpecial?: number;
    rejectCommonPasswords?: boolean;
    commonPasswordListSize?: '10k' | '100k' | '250k' | '500k' | '1m' | '2m' | '5m' | '10m';
}
export interface PasswordOption {
    id: 0 | 1 | 2 | 3;
    value: 'Too weak' | 'Weak' | 'Medium' | 'Strong';
    minDiversity: number;
    minLength: number;
}
export declare const defaultOptions: PasswordOption[];
export interface PasswordStrength {
    id: 0 | 1 | 2 | 3;
    value: 'Too weak' | 'Weak' | 'Medium' | 'Strong';
    contains: {
        lowercase: boolean;
        uppercase: boolean;
        number: boolean;
        symbol: boolean;
    };
    length: number;
    counts?: {
        lowercase: number;
        uppercase: number;
        numbers: number;
        special: number;
    };
}
/**
 * Checks if a password is in the list of common passwords
 * @param password The password to check
 * @param listSize Size of the common password list to check against ('10k', '100k', '250k', '500k', '1m', '2m', '5m', '10m')
 * @returns true if the password is common, false otherwise
 */
export declare function isCommonPassword(password: string, listSize?: '10k' | '100k' | '250k' | '500k' | '1m' | '2m' | '5m' | '10m'): Promise<boolean>;
export declare function checkPasswordStrength(password: string, requirements?: Omit<PasswordRequirements, 'rejectCommonPasswords' | 'commonPasswordListSize'>, options?: PasswordOption[]): PasswordStrength;
export interface PasswordGenerationOptions {
    length?: number;
    includeUppercase?: boolean;
    includeLowercase?: boolean;
    includeNumbers?: boolean;
    includeSymbols?: boolean;
    excludeSimilarCharacters?: boolean;
    excludeAmbiguousCharacters?: boolean;
}
export declare function generatePassword(options?: PasswordGenerationOptions): string;
/**
 * Calculates the entropy of a password in bits
 * @param password The password to analyze
 * @returns The entropy value in bits and a breakdown of the calculation
 */
export interface EntropyDetails {
    entropy: number;
    poolSize: number;
    length: number;
    characterSets: {
        lowercase: boolean;
        uppercase: boolean;
        numbers: boolean;
        symbols: boolean;
    };
}
export declare function calculatePasswordEntropy(password: string): EntropyDetails;
/**
 * Represents the estimated time it would take to crack a password
 * under different attack scenarios
 */
export interface CrackTimeEstimates {
    onlineThrottling100PerHour: number;
    onlineNoThrottling10PerSecond: number;
    offlineSlowHashing1e4PerSecond: number;
    offlineFastHashing1e10PerSecond: number;
    timeToCrack: {
        onlineThrottling: string;
        onlineNoThrottling: string;
        offlineSlowHashing: string;
        offlineFastHashing: string;
    };
}
/**
 * Estimates how long it would take to crack a password under different attack scenarios
 * @param password The password to analyze
 * @returns Estimated crack times under different scenarios
 */
export declare function estimateCrackTime(password: string): CrackTimeEstimates;
/**
 * Represents detected patterns in a password that might make it vulnerable
 */
export interface PasswordPatternAnalysis {
    /** Whether the password contains keyboard patterns (e.g., 'qwerty', 'asdfgh') */
    hasKeyboardPattern: boolean;
    /** Whether the password contains sequential characters (e.g., 'abc', '123') */
    hasSequentialChars: boolean;
    /** Whether the password contains repeated characters (e.g., 'aaa', '111') */
    hasRepeatedChars: boolean;
    /** Whether the password contains date patterns (e.g., '1990', '2023') */
    hasDatePattern: boolean;
    /** Overall risk score from 0 (no patterns) to 100 (highly patterned) */
    patternRiskScore: number;
    /** Specific patterns detected in the password */
    detectedPatterns: string[];
    /** Suggestions to improve the password */
    suggestions: string[];
}
/**
 * Analyzes a password for common patterns that might make it vulnerable
 * @param password The password to analyze
 * @returns Analysis of patterns found in the password
 *
 * @example
 * ```typescript
 * // Check if a password contains predictable patterns
 * const analysis = analyzePasswordPatterns('qwerty123');
 * console.log(analysis.hasKeyboardPattern); // true
 * console.log(analysis.patternRiskScore); // 75
 * console.log(analysis.suggestions); // ['Avoid keyboard patterns like "qwerty"', ...]
 * ```
 */
export declare function analyzePasswordPatterns(password: string): PasswordPatternAnalysis;
/**
 * Comprehensive password analysis that combines strength checking, entropy calculation,
 * crack time estimation, and pattern detection
 * @param password The password to analyze
 * @returns A comprehensive analysis of the password
 *
 * @example
 * ```typescript
 * // Get a comprehensive analysis of a password
 * const analysis = analyzePassword('Password123!');
 * console.log(analysis.strength.value); // 'Medium'
 * console.log(analysis.entropy.entropy); // 75.24
 * console.log(analysis.patterns.patternRiskScore); // 25
 * console.log(analysis.crackTime.timeToCrack.offlineSlowHashing); // '3 months'
 * ```
 */
export declare function analyzePassword(password: string): {
    strength: PasswordStrength;
    entropy: EntropyDetails;
    crackTime: CrackTimeEstimates;
    patterns: PasswordPatternAnalysis;
};