blenx-auth

Reusable authentication library for FastAPI applications.

Status: Phase 1 — extracted from apps/api, not yet wired into the API. The existing API in apps/api continues to use its original auth code.

Features

• JWT-based access and refresh token rotation
• Email verification and password reset flows
• Google OIDC OAuth client
• Argon2id password hashing
• Account lockout after repeated failures
• Role / permission guards
• Protocol-based repository contracts (SQLAlchemy backends included)
• Framework-agnostic core (no FastAPI required to use services)

Installation

# Core — no web framework dependency
pip install blenx-auth

# With FastAPI integration layer
pip install blenx-auth[fastapi]

Structure

src/blenx_auth/
├── __init__.py
├── settings.py          # AuthSettings protocol (pure Python)
├── email.py             # EmailSender protocol + NullEmailSender
├── constants.py         # Security invariants
├── exceptions.py        # Domain exceptions
├── types.py             # Protocol contracts
├── password.py          # Argon2id hashing + policy
├── jwt.py               # TokenService
├── service.py           # Auth business logic
├── schemas.py           # Pydantic request/response models
├── google_oauth.py      # Google OIDC client (pure httpx-oauth)
├── db/
│   ├── __init__.py
│   ├── base.py          # AuthBase declarative base
│   └── session.py       # Async session factory helper
├── fastapi/             # FastAPI integration subpackage (optional)
│   ├── __init__.py
│   ├── dependencies.py  # get_settings, get_db_session, repo deps, current-user guards
│   ├── routes.py        # /auth and /users routers
│   ├── oauth.py         # Google OAuth authorize/callback routes
│   └── permissions.py   # require_admin / require_role dependency factories
├── models/
│   ├── __init__.py
│   ├── user.py
│   ├── oauth_account.py
│   └── refresh_token.py
└── repositories/
    ├── __init__.py
    ├── users.py
    ├── oauth_accounts.py
    └── refresh_tokens.py

Examples

See the examples/ directory for:

• standalone.py — wiring core services to in-memory fakes (no DB, no web framework)
• sqlalchemy_example.py — using the SQLAlchemy repositories

License

MIT