Metadata-Version: 2.4
Name: bluefox-auth
Version: 0.9.0
Summary: JWT authentication, user management, and authorization for Bluefox apps
Project-URL: Homepage, https://bluefox-auth.bluefox.software
Project-URL: Documentation, https://bluefox-auth.bluefox.software/docs/
Project-URL: Repository, https://github.com/blue-fox-software/bluefox-auth
License-Expression: MIT
Requires-Python: >=3.12
Requires-Dist: bcrypt>=4.1
Requires-Dist: bluefox-core<1.0,>=0.1.0
Requires-Dist: email-validator>=2.0
Requires-Dist: pyjwt>=2.8
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: test
Requires-Dist: bluefox-test<1.0,>=0.1.0; extra == 'test'
Requires-Dist: httpx>=0.27; extra == 'test'
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# bluefox-auth

JWT authentication, user management, and authorization for Bluefox apps.

Part of the [Bluefox Stack](https://bluefox-stack.bluefox.software).

[Documentation](https://bluefox-auth.bluefox.software/docs/) &middot; [PyPI](https://pypi.org/project/bluefox-auth/)

---

## Install

```bash
uv add bluefox-auth
```

---

## One-liner setup

```python
from bluefox_core import BluefoxSettings, create_bluefox_app
from bluefox_auth import BluefoxAuth

settings = BluefoxSettings()
app = create_bluefox_app(settings)
BluefoxAuth(app, settings)
```

This mounts all auth routes under `/auth`, configures JWT tokens, sets up cookie + Bearer authentication, and wires CSRF protection.

---

## Protect routes

```python
from fastapi import Depends
from bluefox_auth import current_active_user, BluefoxUser

@app.get("/dashboard")
async def dashboard(user: BluefoxUser = Depends(current_active_user)):
    return {"message": f"Hello, {user.email}"}
```

---

## What you get

- **User registration and login** — bcrypt password hashing with timing-safe verification
- **JWT access + refresh tokens** — `jti`, `iat`, audience claims, configurable expiry
- **Dual transport** — Bearer header and HttpOnly cookies, auto-detected per request
- **Refresh token rotation** — family-based reuse detection revokes entire session on replay
- **CSRF protection** — plain double-submit cookie pattern, skipped for Bearer requests
- **Password reset** — stateless one-time-use tokens via async email hook
- **Email verification** — stateless one-time-use tokens via async email hook
- **One-liner setup** — `BluefoxAuth(app, settings)` wires everything

## Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/auth/register` | POST | Create a new user |
| `/auth/login` | POST | Authenticate and get tokens |
| `/auth/refresh` | POST | Rotate refresh token |
| `/auth/logout` | POST | Revoke token family |
| `/auth/me` | GET | Current user profile |
| `/auth/password-reset` | POST | Request password reset email |
| `/auth/password-reset/confirm` | POST | Confirm password reset |
| `/auth/email-verification` | POST | Request verification email |
| `/auth/email-verification/confirm` | POST | Confirm email verification |

---

## Documentation

Full docs at [bluefox-auth.bluefox.software/docs/](https://bluefox-auth.bluefox.software/docs/)

- [Getting started](https://bluefox-auth.bluefox.software/docs/getting-started/) — install and configure
- [Security](https://bluefox-auth.bluefox.software/docs/security/) — how authentication and authorization work
- [API auth guide](https://bluefox-auth.bluefox.software/docs/guides/api-auth/) — Bearer token flow
- [Cookie auth guide](https://bluefox-auth.bluefox.software/docs/guides/cookie-auth/) — browser cookie flow
- [Reference](https://bluefox-auth.bluefox.software/docs/reference/setup/) — API documentation
