bdr-auth-library 0.2.0

Shared Supabase Auth library for FastAPI — JWT verification, tenant extraction, service tokens, and rate limiting

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

pip install bdr-auth-library

Quick Start

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

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

from auth_library.dependencies import get_current_user

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

User Model

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

from auth_library.service_client import ServiceTokenGenerator

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

Token Refresh

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