Metadata-Version: 2.4
Name: blenx-auth
Version: 0.2.0
Summary: Reusable authentication library for FastAPI applications
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx-oauth>=0.17.0
Requires-Dist: pwdlib[argon2]<1.0,>=0.2
Requires-Dist: pydantic-settings<3.0,>=2.5
Requires-Dist: pydantic<3.0,>=2.9
Requires-Dist: pyjwt<3.0,>=2.8
Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0
Provides-Extra: fastapi
Requires-Dist: fastapi[standard]<1.0,>=0.115; extra == 'fastapi'
Description-Content-Type: text/markdown

# 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

```bash
# 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
