Metadata-Version: 2.4
Name: dwarapaal
Version: 1.0.0
Summary: Production-ready authentication system for Python web applications
Home-page: https://github.com/unkown812/dwarapaal-auth-py
Author: Jay Jogane
Author-email: unkown812 <jayjogane@gmail.com>
License: ISC
Project-URL: Homepage, https://github.com/unkown812/dwarapaal-auth-py
Project-URL: Documentation, https://github.com/unkown812/dwarapaal-auth-py
Project-URL: Repository, https://github.com/unkown812/dwarapaal-auth-py
Project-URL: Bug Tracker, https://github.com/unkown812/dwarapaal-auth-py/issues
Keywords: authentication,auth,jwt,flask,fastapi,django,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<h1 align="center">
Dwarapaal
</h1>
<div align="center">

**Production-ready authentication system for Python web applications**

<!-- [![PyPI version](https://img.shields.io/pypi/v/dwarapaal-auth-py.svg)](https://pypi.org/project/dwarapaal-auth-py/)
[![Python Versions](https://img.shields.io/pypi/pyversions/dwarapaal-auth-py.svg)](https://pypi.org/project/dwarapaal-auth-py/)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) -->

A flexible, secure authentication solution for Flask, FastAPI, and Django applications. Built with Python, MongoDB, and JWT.

[Features](#-features)
[Installation](#-installation)
[Quick Start](#-quick-start)
[Documentation](#-documentation)
[Examples](#-examples)

</div>

---

## Features

-  **User Registration** with email verification
-  **Email Verification** via secure tokens
-  **User Login** with JWT access and refresh tokens
-  **Password Reset** with secure token-based flow
-  **Role-Based Authorization** (user, admin, moderator)
-  **Protected Routes** with JWT middleware
-  **Input Validation** using Pydantic
-  **Password Hashing** with bcrypt
-  **Token Security** with SHA-256 hashing
-  **Professional Email Templates** 
-  **Type Safety** with Python type hints
-  **Multi-Framework**: Flask, FastAPI, Django

## Why dwarapaal Auth?

- **Quick Integration** – Add authentication in minutes
- **Enterprise Security** – Battle-tested security practices
- **Framework Agnostic** – Works with Flask, FastAPI, Django
- **Email Ready** – Built-in verification and password reset
- **Role-Based Access** – Easy authorization
- **Type Safe** – Full type hints and Pydantic models
- **Production Ready** – Used in production applications

---

## Installation

```bash
# Basic installation
pip install dwarapaal

# With Flask support
pip install dwarapaal[flask]

# With FastAPI support
pip install dwarapaal[fastapi]

# With Django support
pip install dwarapaal[django]

# With email support
pip install dwarapaal[email]

# All features
pip install dwarapaal[flask,fastapi,django,email]
```

**Requirements:**
- Python 3.8+
- MongoDB 4.0+

---

## Quick Start

### Flask Example

```python
from flask import Flask, request, jsonify
from dwarapaal_auth import (
    dwarapaalConfig,
    EmailConfig,
    init_dwarapaal,
    require_auth,
    require_role,
)

app = Flask(__name__)

# Configure dwarapaal Auth
email_config = EmailConfig(
    host="smtp.gmail.com",
    port=587,
    username="your-email@gmail.com",
    password="your-app-password",
    from_address="noreply@yourapp.com",
    use_tls=True
)

config = dwarapaalConfig(
    mongo_uri="mongodb://localhost:27017/myapp",
    jwt_secret="your-secret-key-change-in-production",
    email_config=email_config,
)

# Initialize
db = init_dwarapaal(config)

# Protected route
@app.route("/api/profile")
@require_auth
def get_profile():
    user = request.current_user
    return jsonify({"user": user})

# Admin-only route
@app.route("/api/admin/users")
@require_auth
@require_role(["admin"])
def get_users():
    users = db.users.find({})
    return jsonify({"users": list(users)})

if __name__ == "__main__":
    app.run()
```

### FastAPI Example

```python
from fastapi import FastAPI, Depends
from dwarapaal_auth import dwarapaalConfig, init_dwarapaal
from dwarapaal_auth.fastapi import get_current_user, require_roles

app = FastAPI()

# Configure and initialize
config = dwarapaalConfig(
    mongo_uri="mongodb://localhost:27017/myapp",
    jwt_secret="your-secret-key",
)
db = init_dwarapaal(config)

# Protected route
@app.get("/api/profile")
async def get_profile(current_user: dict = Depends(get_current_user)):
    return {"user": current_user}

# Admin-only route
@app.get("/api/admin/users")
async def get_users(current_user: dict = Depends(require_roles(["admin"]))):
    users = list(db.users.find({}))
    return {"users": users}
```

---

## Configuration

### Environment Variables

Create a `.env` file:

```env
# Database
MONGO_URI=mongodb://localhost:27017/dwarapaal_auth

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production

# Email (SMTP)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-specific-password
EMAIL_FROM=noreply@yourapp.com

# Application
PORT=5000
```

### Configuration Object

```python
from dwarapaal_auth import dwarapaalConfig, EmailConfig

email_config = EmailConfig(
    host="smtp.gmail.com",
    port=587,
    username="your-email@gmail.com",
    password="your-password",
    from_address="noreply@yourapp.com",
    use_tls=True
)

config = dwarapaalConfig(
    # Database
    mongo_uri="mongodb://localhost:27017/myapp",
    database_name="auth_db",
    
    # JWT
    jwt_secret="your-secret-key",
    jwt_algorithm="HS256",
    access_token_expire_minutes=15,
    refresh_token_expire_days=7,
    
    # Security
    bcrypt_rounds=12,
    
    # Email
    email_config=email_config,
    
    # Tokens
    verification_token_expire_hours=24,
    reset_token_expire_hours=1,
    
    # Application
    base_url="http://localhost:5000",
)
```

---

## API Reference

### Authentication Service

```python
from dwarapaal_auth.services import AuthService

auth_service = AuthService()

# Register user
await auth_service.register(user_data)

# Verify email
await auth_service.verify_email(token)

# Login
result = await auth_service.login(credentials)

# Forgot password
await auth_service.forgot_password(email)

# Reset password
await auth_service.reset_password(token, new_password)
```

### Models

```python
from dwarapaal_auth.models import (
    UserCreate,
    UserLogin,
    User,
    UserRole,
    TokenPair,
)

# Create user
user_data = UserCreate(
    username="johndoe",
    email="john@example.com",
    password="SecurePass123!"
)

# Login credentials
credentials = UserLogin(
    email="john@example.com",
    password="SecurePass123!"
)

# User roles
role = UserRole.ADMIN  # or UserRole.USER, UserRole.MODERATOR
```

---

## Middleware

### Flask Decorators

```python
from dwarapaal_auth import require_auth, require_role

@app.route("/api/profile")
@require_auth
def get_profile():
    user = request.current_user
    return jsonify(user)

@app.route("/api/admin/dashboard")
@require_auth
@require_role(["admin"])
def admin_dashboard():
    return jsonify({"message": "Admin dashboard"})
```

### FastAPI Dependencies

```python
from fastapi import Depends
from dwarapaal_auth.fastapi import get_current_user, require_roles

@app.get("/api/profile")
async def get_profile(current_user: dict = Depends(get_current_user)):
    return {"user": current_user}

@app.get("/api/admin/dashboard")
async def admin_dashboard(
    current_user: dict = Depends(require_roles(["admin"]))
):
    return {"message": "Admin dashboard"}
```

---

## Security

### Password Requirements

-  Minimum 8 characters
-  Maximum 100 characters
-  At least one uppercase letter
-  At least one lowercase letter
-  At least one number
-  At least one special character

### Security Features

| Feature | Implementation |
|---------|---------------|
| Password Hashing | Bcrypt (12 rounds) |
| Token Hashing | SHA-256 |
| JWT | HS256 algorithm |
| Email Verification | Required before login |
| Input Validation | Pydantic models |
| Role-Based Access | Middleware decorators |

---

## Complete Examples

### Flask Application

```python
from flask import Flask, request, jsonify
from dwarapaal_auth import (
    dwarapaalConfig,
    EmailConfig,
    init_dwarapaal,
    require_auth,
    require_role,
)
from dwarapaal_auth.routes.auth_routes import create_flask_auth_routes
import os

app = Flask(__name__)

# Initialize
config = dwarapaalConfig(
    mongo_uri=os.getenv("MONGO_URI"),
    jwt_secret=os.getenv("JWT_SECRET"),
    email_config=EmailConfig(
        host=os.getenv("EMAIL_HOST"),
        port=int(os.getenv("EMAIL_PORT")),
        username=os.getenv("EMAIL_USER"),
        password=os.getenv("EMAIL_PASS"),
        from_address=os.getenv("EMAIL_FROM"),
    ),
)

db = init_dwarapaal(config)

# Register auth routes
auth_bp = create_flask_auth_routes()
app.register_blueprint(auth_bp, url_prefix="/api/auth")

# Your routes
@app.route("/api/profile")
@require_auth
def get_profile():
    return jsonify({"user": request.current_user})

@app.route("/api/admin/users")
@require_auth
@require_role(["admin"])
def get_users():
    users = db.users.find({}, {"password": 0})
    return jsonify({"users": list(users)})

if __name__ == "__main__":
    app.run(port=5000)
```

### FastAPI Application

```python
from fastapi import FastAPI, Depends
from dwarapaal_auth import dwarapaalConfig, init_dwarapaal
from dwarapaal_auth.fastapi import get_current_user, require_roles
from dwarapaal_auth.routes.auth_routes import create_fastapi_auth_routes

app = FastAPI()

# Initialize
config = dwarapaalConfig(
    mongo_uri="mongodb://localhost:27017/myapp",
    jwt_secret="your-secret-key",
)
db = init_dwarapaal(config)

# Include auth routes
app.include_router(
    create_fastapi_auth_routes(),
    prefix="/api/auth",
    tags=["Authentication"]
)

# Your routes
@app.get("/api/profile")
async def get_profile(current_user: dict = Depends(get_current_user)):
    return {"user": current_user}

@app.get("/api/admin/users")
async def get_users(current_user: dict = Depends(require_roles(["admin"]))):
    users = list(db.users.find({}, {"password": 0}))
    return {"users": users}
```

---

## Testing

```bash
# Install dev dependencies
pip install dwarapaal-auth-py[dev]

# Run tests
pytest

# Run with coverage
pytest --cov=dwarapaal_auth --cov-report=html

# Run specific test
pytest tests/test_auth.py::test_register
```

---

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/unkown812/dwarapaal-auth-py.git
cd dwarapaal-auth-py

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

### Building

```bash
# Build package
python -m build

# Install locally
pip install dist/dwarapaal_auth_py-1.0.0-py3-none-any.whl
```

### Publishing

```bash
# Test on TestPyPI
python -m twine upload --repository testpypi dist/*

# Publish to PyPI
python -m twine upload dist/*
```

---

## Troubleshooting

### Email Not Sending

**For Gmail users:**
1. Enable 2-factor authentication
2. Create an App Password: https://myaccount.google.com/apppasswords
3. Use the App Password in your configuration

### JWT Token Issues

```python
# Check token expiration
from dwarapaal_auth.services import TokenService

token_service = TokenService()
payload = token_service.verify_token(token)
print(payload)
```

### MongoDB Connection

```bash
# Check MongoDB is running
mongosh

# Test connection
from pymongo import MongoClient
client = MongoClient("mongodb://localhost:27017/")
print(client.server_info())
```

---

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Guidelines

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass
5. Format code with Black
6. Submit a pull request

```bash
# Format code
black dwarapaal_auth/

# Check types
mypy dwarapaal_auth/

# Lint
flake8 dwarapaal_auth/

# Run tests
pytest
```

---

## License

ISC License - see [LICENSE](LICENSE) file for details.

---

## Author

**Jay Jogane**

- GitHub: [@unkown812](https://github.com/unkown812)
- LinkedIn: [Jay Jogane](https://linkedin.com/in/unkown812)

---

## Acknowledgments

Built with:

- [PyMongo](https://pymongo.readthedocs.io/) - MongoDB driver
- [PyJWT](https://pyjwt.readthedocs.io/) - JWT implementation
- [Bcrypt](https://github.com/pyca/bcrypt/) - Password hashing
- [Pydantic](https://pydantic-docs.helpmanual.io/) - Data validation
- [Flask](https://flask.palletsprojects.com/) - Web framework
- [FastAPI](https://fastapi.tiangolo.com/) - Modern web framework

---

## Roadmap

### Version 1.x (Current)
-  Core authentication
-  Flask support
-  FastAPI support
-  Role-based auth

### Version 2.0 (Planned)
- [ ] Django support
- [ ] OAuth integration
- [ ] Two-factor authentication
- [ ] Session management
- [ ] Account lockout

### Version 3.0 (Future)
- [ ] SAML support
- [ ] Multi-tenancy
- [ ] Advanced rate limiting
- [ ] Admin dashboard

---

## Performance

Benchmarks on typical hardware:

| Operation | Avg Time |
|-----------|----------|
| Registration | 180ms |
| Login | 120ms |
| Token Verification | 5ms |
| Password Hashing | 150ms |

---

<div align="center">

**If this project helped you, please star it on GitHub!**

Coded and Crafted by [Jay Jogane](https://github.com/unkown812)

[Back to Top](#-dwarapaal)

</div>
