ZenithAuth 🛡️

ZenithAuth is a professional-grade, high-performance, and secure authentication and authorization library for modern Python applications. It combines the speed of stateless JWTs with the security of stateful Redis-backed revocation.

✨ Key Features

• Secure Hashing: Powered by Argon2id, the industry winner of the Password Hashing Competition.
• Hybrid Auth Engine: Stateless JWTs for speed, paired with a Redis-backed blacklist for instant token revocation (logouts).
• Modern Data Validation: Built on Pydantic V2 for strict type safety and performance.
• MFA (Multi-Factor Auth): Out-of-the-box support for TOTP (Google Authenticator) with built-in QR code generation.
• Fine-Grained Authorization: Role-Based Access Control (RBAC) and scoped permissions support.
• FastAPI Native: Includes first-class Dependency Injection helpers for FastAPI and Starlette.
• Agnostic Storage: Works with any database (SQLAlchemy, Tortoise, MongoDB) via the Repository Protocol.

🚀 Installation

pip install zenithauth

🛠️ Quick Start (FastAPI)

ZenithAuth makes protecting your API endpoints intuitive.

from fastapi import FastAPI, Depends
from zenithauth.manager import ZenithAuth
from zenithauth.integrations.fastapi import ZenithAuthFastAPI

app = FastAPI()

# 1. Initialize the library
# Ensure ZENITH_SECRET_KEY and ZENITH_REDIS_URL are in your .env
auth_manager = ZenithAuth()
zenith = ZenithAuthFastAPI(auth_manager)

@app.post("/login")
async def login(email: str, password: str):
    # This handles hashing verification and token generation
    result = await auth_manager.authenticate(email, password)
    return result

@app.get("/secure-data")
async def get_data(user: dict = Depends(zenith.get_current_user)):
    return {"message": f"Hello {user['sub']}, you are authorized!"}

@app.get("/admin-only")
async def admin_portal(user: dict = Depends(zenith.require_role("admin"))):
    return {"message": "Welcome, Administrator."}

🔐 Multi-Factor Authentication (MFA)

Implementing MFA is a two-step flow in ZenithAuth:

1. Enrollment

# Generate secret and QR code for the user to scan
setup_data = await auth.mfa_enroll_setup(user_id="123", email="user@example.com")
# setup_data contains: {"secret": "...", "qr_code_base64": "..."}

2. Verification

# Finalize the login using the 6-digit TOTP code
tokens = await auth.verify_mfa_and_login(user_id="123", code="123456")

🏗️ Architecture

ZenithAuth follows a Security-by-Default philosophy:

1. Stateless JWTs: Tokens carry user identity and roles, reducing database hits.
2. JTI Tracking: Every token has a unique ID (JTI).
3. Redis Guard: Upon logout, the JTI is blacklisted in Redis until its natural expiry time, preventing "ghost sessions."
4. Entropy-Based Passwords: We enforce password strength based on character diversity, not just simple length.

📝 Configuration

ZenithAuth is configured via environment variables for easy deployment:

📜 License

Distributed under the MIT License. See LICENSE for more information.