Metadata-Version: 2.4
Name: pal-e-auth-ldraney
Version: 0.1.0
Summary: Shared JWT + Google OAuth auth middleware for pal-e platform services
License: MIT
Keywords: auth,jwt,google-oauth,fastapi,middleware
Author: Lucas Draney
Requires-Python: >=3.12
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: PyJWT[crypto] (>=2.8)
Requires-Dist: fastapi (>=0.115)
Requires-Dist: httpx (>=0.27)
Requires-Dist: pydantic (>=2.0)
Description-Content-Type: text/markdown

# pal-e-auth

Shared JWT + Google OAuth auth middleware for pal-e platform services.

## Install

```bash
pip install pal-e-auth-ldraney
```

## Quick Start

```python
from fastapi import FastAPI, Depends
from pal_e_auth import AuthConfig, auth_router, get_current_user, require_role, User

app = FastAPI()

config = AuthConfig(
    secret_key="your-jwt-secret",
    google_client_id="your-google-client-id",
    google_client_secret="your-google-client-secret",
)
app.state.auth_config = config
app.include_router(auth_router(config))

@app.get("/protected")
async def protected(user: User = Depends(get_current_user)):
    return {"email": user.email}

@app.get("/admin-only")
async def admin_only(user: User = Depends(require_role("admin"))):
    return {"email": user.email}
```

## Auth Flow

1. User visits `/auth/google` → redirected to Google consent screen
2. Google redirects back to `/auth/callback` with auth code
3. Server exchanges code for ID token, extracts user info
4. JWT created and set as `access_token` cookie
5. Subsequent requests authenticated via cookie or `Authorization: Bearer` header

## Dependencies

FastAPI apps provide auth by reading `app.state.auth_config`:
- `get_current_user` — requires valid JWT, returns `User`
- `optional_user` — returns `User | None`
- `require_role("admin", "coach")` — requires valid JWT + matching role

## Roles

`admin`, `coach`, `parent`, `viewer` (default)

## Development

```bash
poetry install
poetry run pytest
poetry run ruff check .
poetry run ruff format --check .
```

