# Genovation Advanced Auth

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

A comprehensive FastAPI authentication library with JWT and Multi-Factor Authentication (MFA) support.

## Features

- ✅ **User Registration & Login** - Secure user authentication
- ✅ **JWT Tokens** - Token-based authentication with automatic refresh
- ✅ **Multi-Factor Authentication (MFA)** - TOTP-based 2FA with Google Authenticator support
- ✅ **Backup Codes** - Recovery codes for MFA
- ✅ **Password Security** - Bcrypt hashing with configurable rounds
- ✅ **QR Code Generation** - For easy authenticator app setup
- ✅ **Type Safe** - Full type hints and Pydantic validation
- ✅ **Production Ready** - Security best practices built-in

## Installation

pip install genovation-advanced-auth


With SQLAlchemy support:

pip install genovation-advanced-auth[sqlalchemy]


## Quick Start
Create `.env` file:
AUTH_SECRET_KEY=your-super-secret-key-here
AUTH_MFA_ISSUER_NAME=MyCompany
AUTH_ACCESS_TOKEN_EXPIRE_MINUTES=30

The library auto-loads these settings.

### Advanced Configuration

Override settings in code:
from genovation_advanced_auth.core.config import AuthConfig, set_config

config = AuthConfig(
secret_key="your-secret",
mfa_issuer_name="MyApp",
mfa_backup_codes_count=15
)
set_config(config)


### Available Settings

| Setting | Environment Variable | Default | Description |
|---------|---------------------|---------|-------------|
| `secret_key` | `AUTH_SECRET_KEY` | *Required* | JWT signing key |
| `algorithm` | `AUTH_ALGORITHM` | `HS256` | JWT algorithm |
| `access_token_expire_minutes` | `AUTH_ACCESS_TOKEN_EXPIRE_MINUTES` | `30` | Token lifetime |
| `mfa_issuer_name` | `AUTH_MFA_ISSUER_NAME` | `MyApp` | Shown in authenticator apps |
| `mfa_backup_codes_count` | `AUTH_MFA_BACKUP_CODES_COUNT` | `10` | Number of backup codes |


### Basic Setup

from fastapi import FastAPI, Depends
from genovation_advanced_auth import AuthRouter, UsersRouter, get_current_user

app = FastAPI()
Include authentication routes

app.include_router(AuthRouter, prefix="/api/v1/auth", tags=["authentication"])
app.include_router(UsersRouter, prefix="/api/v1/users", tags=["users"])
Protected endpoint example

@app.get("/protected")
async def protected_route(current_user = Depends(get_current_user)):
return {"message": f"Hello {current_user['username']}!"}


### Configuration

from genovation_advanced_auth import AuthConfig

config = AuthConfig(
secret_key="your-secret-key-here",
algorithm="HS256",
access_token_expire_minutes=30,
mfa_issuer_name="YourApp"
)


## API Endpoints

### Authentication
- `POST /auth/register` - Register new user
- `POST /auth/login` - Login and get JWT token
- `POST /auth/refresh` - Refresh access token

### MFA
- `POST /auth/mfa/setup` - Setup MFA (returns QR code)
- `POST /auth/mfa/verify` - Verify and enable MFA
- `POST /auth/mfa/disable` - Disable MFA

### User Management
- `GET /users/me` - Get current user profile
- `PUT /users/me` - Update user profile
- `POST /users/change-password` - Change password

## Documentation

Full documentation is available in the [docs](./docs) directory.

## Development


Clone repository

git clone https://github.com/genovation/genovation-advanced-auth.git
cd genovation-advanced-auth
Install with dev dependencies

pip install -e ".[dev]"
Run tests

pytest
Run with coverage

pytest --cov=genovation_advanced_auth


## License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

## Support

- 📧 Email: Connect@genovationsolutions.com
- 🐛 Issues: [GitHub Issues](https://github.com/genovation/genovation-advanced-auth/issues)

---

**Version:** 0.1.0  
**Status:** Alpha - Under Active Development
