password-analysis/README.md

A library for analyzing the strength of a password

# Password Analysis For React

`password-analysis` is a password strength analyzer library for React that evaluates password strength based on various metrics such as length, character diversity, and commonness. It provides a score and description of password strength to help users create secure passwords.

## Features

- **Length check**: Stronger passwords are longer.
- **Character diversity**: Considers the use of uppercase, lowercase, numbers, and special characters.
- **Common password check**: Flags common or weak passwords that are easy to guess.
- **Score system**: Generates a score to categorize the strength of the password.

## Installation

You can install the library via npm or yarn:

```bash
npm install password-analysis

or

yarn add password-analysis
```

### Usage 
Import the analyzePassword function

```javascript
import { analyzePassword } from 'password-analysis';
```

### Example of password analysis

```javascript
import { analyzePassword } from 'password-analysis';

const password = "P@ssw0rd1234!";
const result = analyzePassword(password);

console.log(result);
```

Result Format
The `analyzePassword` function returns an object with the following structure:

```javascript
{
    "score": 58,
    "strength": "medium",
    "metrics": {
        "length": 13,
        "uniqueChars": 12,
        "hasUpperCase": true,
        "hasLowerCase": true,
        "hasNumbers": true,
        "hasSpecialChars": true,
        "isCommon": false
    }
}
```

### Score Description
**Score (0-70)**: The strength of the password, with 70 being the strongest.
- **0-20**: Weak password.
- **21-50**: Medium strength password.
- **51-70**: Strong password.
- **70**: Very strong password.


### How is the score calculated?
The score is based on the following factors:

1. **Length (0–20 points)**: Passwords are stronger when they are longer.
2. **Unique Characters (0–10 points)**: More unique characters increase the score.
3. **Uppercase Letters (0–10 points)**: Presence of uppercase letters increases the score.
4. **Lowercase Letters (0–10 points)**: Presence of lowercase letters increases the score.
5. **Numbers (0–10 points)**: Inclusion of numbers increases the score.
6. **Special Characters (0–15 points)**: Passwords with special characters (e.g., !@#) increase the score significantly.
7. **Common Passwords (penalty)**: Passwords found in common password lists are penalized.


### Example Results
1. **Weak Password:**
```javascript
const password = "123456";
const result = analyzePassword(password);
console.log(result);
```

**Output:**
```javascript
{
    "score": 10,
    "strength": "weak",
    "metrics": {
        "length": 6,
        "uniqueChars": 3,
        "hasUpperCase": false,
        "hasLowerCase": false,
        "hasNumbers": true,
        "hasSpecialChars": false,
        "isCommon": true
    }
}
```
- **Score**: 10 (Weak password)
- **Strength**: Weak

2. **Medium Strength Password:**
```javascript
const password = "P@ssw0rd1234!";
const result = analyzePassword(password);
console.log(result);
```

**Output:**
```javascript
{
    "score": 58,
    "strength": "medium",
    "metrics": {
        "length": 13,
        "uniqueChars": 12,
        "hasUpperCase": true,
        "hasLowerCase": true,
        "hasNumbers": true,
        "hasSpecialChars": true,
        "isCommon": false
    }
}
```
- **Score**: 58 (Medium strength)
- **Strength**: Medium

3. **Strong Password**:
```javascript
const password = "A@z9d3Qr!lP0sXy7";
const result = analyzePassword(password);
console.log(result);
```

**Output:**
```javascript
{
    "score": 70,
    "strength": "strong",
    "metrics": {
        "length": 18,
        "uniqueChars": 18,
        "hasUpperCase": true,
        "hasLowerCase": true,
        "hasNumbers": true,
        "hasSpecialChars": true,
        "isCommon": false
    }
}
```
- **Score**: 70 (Strong password)
- **Strength**: Strong


# API
`analyzePassword(password: string): AnalysisResult`

#### Parameters:
- `password` (string): The password to analyze.

#### Returns:
- An object of type AnalysisResult containing:
    - `score` (number): The password score (0-70).
    - strength (string): The strength of the password (`weak`, `medium`, `strong`).
    - `metrics` (object):
        - `length` (number): Length of the password.
        - `uniqueChars` (number): Number of unique characters.
        - `hasUpperCase` (boolean): Whether the password contains uppercase letters.
        - `hasLowerCase` (boolean): Whether the password contains lowercase letters.
        - `hasNumbers` (boolean): Whether the password contains numbers.
        - `hasSpecialChars` (boolean): Whether the password contains special characters.
        - `isCommon` (boolean): Whether the password is common.

## License
MIT