Metadata-Version: 2.4
Name: bdr-auth-library
Version: 0.1.0
Summary: Shared Supabase Auth library for FastAPI — JWT verification, tenant extraction, service tokens, and rate limiting
Project-URL: Repository, https://github.com/your-org/bdr-auth-packages
Author-email: MuralWorksAI <shri@muralworksai.com>
License-Expression: MIT
Keywords: auth,authentication,fastapi,jwt,multi-tenant,supabase
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: fastapi<1.0,>=0.100
Requires-Dist: httpx<1.0,>=0.24
Requires-Dist: pydantic-settings<3.0,>=2.0
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: python-jose[cryptography]<4.0,>=3.3
Provides-Extra: dev
Requires-Dist: coverage>=7.0; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# bdr-auth-library

Shared Supabase Auth library for FastAPI applications. Provides JWT verification via JWKS, tenant extraction, service-to-service tokens, token refresh coordination, rate limiting, and FastAPI dependencies.

## Installation

```bash
pip install bdr-auth-library
```

## Quick Start

```python
from fastapi import FastAPI, Depends
from auth_library.dependencies import get_current_user
from auth_library.models import User
from auth_library.errors import AuthError, auth_error_handler

app = FastAPI()
app.add_exception_handler(AuthError, auth_error_handler)

@app.get("/protected")
async def protected(user: User = Depends(get_current_user)):
    return {"uid": user.uid, "tenant": user.effective_tenant_id}
```

## Environment Variables

```env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_JWKS_URL=https://your-project.supabase.co/auth/v1/.well-known/jwks.json
APP_ENV=production
DISABLE_AUTH=false
```

## Features

- **JWT Verification** — RS256 via JWKS with automatic key rotation support
- **Issuer Registry** — Algorithm-confusion prevention; determines expected algorithm from trusted config, not token headers
- **JWKS Caching** — TTL-based caching (default 10min) with force-refresh on unknown `kid`
- **Tenant Extraction** — Priority resolution: custom claim → app_metadata → uid fallback
- **Service Tokens** — HS256 internal service-to-service tokens with dedicated signing secret
- **Token Refresh** — Proactive refresh with async lock to prevent parallel refresh storms
- **Rate Limiting** — Per-IP global limit, failed login throttling, per-account protection
- **Dual Verification** — Accept both Supabase and legacy Firebase tokens during migration
- **FastAPI Integration** — `get_current_user` dependency, standardized error responses
- **Secure Logging** — Redacts tokens/secrets from all log output

## API

### Dependencies

```python
from auth_library.dependencies import get_current_user
```

Returns an authenticated `User` model or raises HTTP 401 with a standardized error response.

### User Model

```python
from auth_library.models import User

# Fields: uid, email, email_verified, display_name, photo_url, role, tenant_id
# Computed: effective_tenant_id (tenant_id or uid fallback, never empty)
```

### Service Tokens

```python
from auth_library.service_client import ServiceTokenGenerator

generator = ServiceTokenGenerator(signing_secret="your-secret")
token = generator.generate(service_name="my-service", ttl=300)
```

### Token Refresh

```python
from auth_library.refresh import TokenRefreshCoordinator

coordinator = TokenRefreshCoordinator(settings)
access_token = await coordinator.get_valid_token()
```

## Configuration

All settings are loaded via Pydantic BaseSettings from environment variables:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SUPABASE_URL` | Yes | — | Supabase project URL |
| `SUPABASE_JWKS_URL` | Yes | — | JWKS endpoint for token verification |
| `APP_ENV` | No | `development` | Environment (development/test/staging/production) |
| `DISABLE_AUTH` | No | `false` | Bypass auth in dev/test only |
| `DUAL_VERIFICATION_ENABLED` | No | `false` | Accept legacy Firebase tokens |
| `SUPABASE_SERVICE_ROLE_KEY` | No | — | For ServiceRoleClient (bypasses RLS) |
| `SERVICE_TOKEN_SECRET` | No | — | Signing secret for internal service tokens |

## License

MIT
