Metadata-Version: 2.4
Name: python-auth-toolkit
Version: 0.1.0
Summary: All-in-one Python authentication toolkit: password validation, password hashing, email validation.
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bcrypt>=4.0
Requires-Dist: argon2-cffi>=21.3
Requires-Dist: email-validator>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# python-auth-toolkit

[![PyPI version](https://img.shields.io/pypi/v/python-auth-toolkit.svg)](https://pypi.org/project/python-auth-toolkit/)
[![Python versions](https://img.shields.io/pypi/pyversions/python-auth-toolkit.svg)](https://pypi.org/project/python-auth-toolkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An all-in-one, highly secure, and configurable Python authentication toolkit. It provides robust password strength validation, secure password hashing (Bcrypt & Argon2), and custom validation error feedback.

---

## Features

- **Password Validator**: Fully customizable rules (minimum/maximum length, uppercase/lowercase requirements, digit requirements, and special character requirements).
- **Common Passwords Protection**: Built-in protection to block the most common easily guessable passwords (e.g., "123456", "password", "qwerty").
- **Password Hasher**: Secure password hashing supporting **Bcrypt** and **Argon2id** with timing-safe verification.
- **Upgrades & Re-hashing**: Easy checking for out-of-date password hashes (e.g., when cost factors are increased) to allow seamless re-hashing.
- **Type Safety**: Full PEP 561 type annotation support.

---

## Installation

Install using `pip`:

```bash
pip install python-auth-toolkit
```

---

## Quick Start

### 1. Password Hashing

```python
from python_auth_toolkit import PasswordHasher

# Initialize with default settings (Bcrypt with 12 rounds)
hasher = PasswordHasher()

# Hash a password
hashed = hasher.hash("my_secure_password")
print(hashed)  # Output: $2b$12$... (embedded salt and rounds)

# Verify a password
is_match = hasher.verify("my_secure_password", hashed)
print(is_match)  # True

# Check if a hash needs to be regenerated (e.g., after increasing security defaults)
upgraded_hasher = PasswordHasher(rounds=14)
if upgraded_hasher.needs_rehash(hashed):
    new_hash = upgraded_hasher.hash("my_secure_password")
```

Using **Argon2**:

```python
from python_auth_toolkit import PasswordHasher

# Initialize with Argon2id
hasher = PasswordHasher(algorithm="argon2", time_cost=3, memory_cost=65536)

# Hash and verify
hashed = hasher.hash("another_password")
is_match = hasher.verify("another_password", hashed)
```

### 2. Password Strength Validation

```python
from python_auth_toolkit import PasswordValidator

# Initialize validator with custom rules
validator = PasswordValidator(
    min_length=10,
    required_uppercase=True,
    required_lowercase=True,
    required_digits=True,
    required_special=True,
    block_common_passwords=True
)

# Validate a password
result = validator.validate("P@ssw0rd123")

if result.is_valid:
    print(f"Valid! Strength Score: {result.strength_score}/100")
else:
    print("Invalid Password. Errors:")
    for error in result.errors:
        print(f" - {error}")
```

---

## Configuration Options

### `PasswordValidator` parameters:
- `min_length` (int, default: 8): Minimum length required.
- `max_length` (int, default: 128): Maximum length allowed.
- `required_uppercase` (bool, default: True): Require at least one uppercase letter.
- `required_lowercase` (bool, default: True): Require at least one lowercase letter.
- `required_digits` (bool, default: True): Require at least one digit.
- `required_special` (bool, default: True): Require at least one special character.
- `block_common_passwords` (bool, default: True): Reject passwords present in the common passwords list.

### `PasswordHasher` parameters:
- `algorithm` (str, default: 'bcrypt'): Choose between `'bcrypt'` or `'argon2'`.
- `rounds` (int, default: 12): Cost factor rounds for Bcrypt.
- `time_cost` (int, default: 3): Time cost for Argon2.
- `memory_cost` (int, default: 65536): Memory cost in KiB for Argon2.
- `parallelism` (int, default: 4): Parallelism factor threads for Argon2.

---

## Requirements

- Python >= 3.9
- bcrypt >= 4.0
- argon2-cffi >= 21.3
- email-validator >= 2.0

---

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.
