npm package: @pranay921/smart-password-checker
Description: A comprehensive password strength checker that analyzes passwords and provides detailed scoring and feedback. Works in both frontend and backend environments.
Author: pranay921
Latest version: 1.0.0

# Smart Password Checker 🔐

A comprehensive password strength analyzer that provides detailed scoring and actionable feedback. **Now fully compatible with both frontend and backend environments!**

## ✨ Features

✅ **Frontend & Backend Compatible** - Works in browsers AND Node.js  
✅ **ES Modules** - Modern JavaScript module system  
✅ **Comprehensive Scoring** - Rates passwords on a scale of 0-100  
✅ **Detailed Feedback** - Provides specific suggestions for improvement  
✅ **Pattern Detection** - Identifies weak patterns like sequential or repeating characters  
✅ **Common Password Detection** - Checks against database of 100 most common passwords  
✅ **Character Variety Analysis** - Evaluates use of uppercase, lowercase, numbers, and symbols  
✅ **Zero Dependencies** - No external packages required  
✅ **Lightweight** - Small bundle size perfect for frontend use

## 📦 Installation

### For Published Package (When published to NPM)
```bash
npm install smart-password-checker
```

### For Local Development
```bash
cd smart-password-checker
npm link
```

## 🚀 Usage

### Frontend (Vanilla JavaScript)

```html
<!DOCTYPE html>
<html>
<head>
    <title>Password Checker</title>
</head>
<body>
    <input type="password" id="password" placeholder="Enter password">
    <div id="result"></div>

    <script type="module">
        // Import using ES modules
        import { checkPassword } from 'smart-password-checker';
        
        document.getElementById('password').addEventListener('input', (e) => {
            const result = checkPassword(e.target.value);
            document.getElementById('result').innerHTML = `
                <p>Score: ${result.score}/100</p>
                <p>Strength: ${result.strength}</p>
            `;
        });
    </script>
</body>
</html>
```

### Frontend (React)

```jsx
import { useState } from 'react';
import { checkPassword } from 'smart-password-checker';

function PasswordChecker() {
  const [password, setPassword] = useState('');
  const result = password ? checkPassword(password) : null;
  
  return (
    <div>
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
      />
      {result && (
        <div>
          <h2>Score: {result.score}/100</h2>
          <p>Strength: {result.strength}</p>
          <ul>
            {result.feedback.map((msg, i) => (
              <li key={i}>{msg}</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}
```

### Frontend (Vue.js)

```vue
<template>
  <div>
    <input v-model="password" type="password" />
    <div v-if="result">
      <h2>Score: {{ result.score }}/100</h2>
      <p>Strength: {{ result.strength }}</p>
    </div>
  </div>
</template>

<script>
import { checkPassword } from 'smart-password-checker';

export default {
  data() {
    return { password: '' };
  },
  computed: {
    result() {
      return this.password ? checkPassword(this.password) : null;
    }
  }
};
</script>
```

### Backend (Node.js)

```javascript
import { checkPassword } from 'smart-password-checker';

// Analyze a password
const result = checkPassword('MyP@ssw0rd123');

console.log(`Score: ${result.score}/100`);
console.log(`Strength: ${result.strength}`);
console.log('Feedback:', result.feedback);

// Use convenience methods
if (result.isStrong()) {
  console.log('This is a strong password!');
}
```

## 📖 API Reference

### `checkPassword(password)`

Analyzes a password and returns a detailed result object.

**Parameters:**
- `password` (string): The password to analyze

**Returns:** Object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `password` | string | The analyzed password |
| `score` | number | Password strength score (0-100) |
| `strength` | string | Strength level: "Very Weak", "Weak", "Fair", "Good", "Strong", or "Excellent" |
| `color` | string | Suggested color for display |
| `feedback` | array | Array of feedback messages |
| `details` | object | Breakdown of score components |
| `isWeak()` | function | Returns true if score < 40 |
| `isFair()` | function | Returns true if 40 ≤ score < 60 |
| `isGood()` | function | Returns true if 60 ≤ score < 80 |
| `isStrong()` | function | Returns true if score ≥ 80 |

**Example:**

```javascript
const result = checkPassword('Test123!@#');

console.log(result);
// {
//   password: 'Test123!@#',
//   score: 75,
//   strength: 'Good',
//   color: 'cyan',
//   feedback: [
//     'Excellent character variety!',
//     'Avoid sequential characters (abc, 123)'
//   ],
//   details: {
//     length: 20,
//     variety: 40,
//     bonus: 10,
//     penalties: 15
//   },
//   isWeak: [Function],
//   isFair: [Function],
//   isGood: [Function],
//   isStrong: [Function]
// }
```

## 📊 Scoring Criteria

The password strength is calculated based on:

### Length (0-40 points)
- < 6 characters: 0 points ⚠️
- 6-7 characters: 10 points
- 8-11 characters: 20 points
- 12-15 characters: 30 points
- 16+ characters: 40 points

### Character Variety (0-40 points)
- Lowercase letters: +10 points
- Uppercase letters: +10 points
- Numbers: +10 points
- Special characters: +10 points

### Bonus Points (0-20 points)
- Well-distributed character types: +10 points
- High entropy: +10 points

### Penalties
- Common password: -50 points
- Sequential characters (abc, 123): -15 points
- Repeating characters (aaa, 111): -15 points
- Only numbers: -20 points
- Only letters: -10 points

## 🎯 Strength Levels

| Score | Level | Description |
|-------|-------|-------------|
| 0-19 | Very Weak | ❌ Extremely unsafe |
| 20-39 | Weak | ⚠️ Easily cracked |
| 40-59 | Fair | ⚡ Basic protection |
| 60-79 | Good | ✅ Decent security |
| 80-89 | Strong | 🔒 Strong security |
| 90-100 | Excellent | 🛡️ Maximum security |

## 🎨 Live Demo

Check out the `frontend-demo.html` file for a beautiful, interactive demo showing real-time password analysis!

## 🌍 Browser Support

- ✅ Chrome/Edge (latest)
- ✅ Firefox (latest)
- ✅ Safari (latest)
- ✅ Node.js 14+

## 📝 Examples

```javascript
import { checkPassword } from 'smart-password-checker';

// Very Weak Password
checkPassword('123456');
// Score: 0, Strength: "Very Weak"

// Weak Password
checkPassword('password');
// Score: 10, Strength: "Very Weak"

// Fair Password
checkPassword('Password1');
// Score: 50, Strength: "Fair"

// Good Password
checkPassword('MyP@ssw0rd');
// Score: 65, Strength: "Good"

// Strong Password
checkPassword('MyP@ssw0rd123!');
// Score: 85, Strength: "Strong"

// Excellent Password
checkPassword('Tr0ub4dor&3_Secure!');
// Score: 95, Strength: "Excellent"
```

## 🔧 Development

```bash
# Clone the repository
git clone https://github.com/yourusername/smart-password-checker.git

# Install dependencies (none required!)
cd smart-password-checker

# Run tests
npm test
```

## 📄 License

MIT

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 🐛 Issues

If you find any bugs or have feature requests, please create an issue on GitHub.

---

**Made with ❤️ for developers who care about security**