fastapi-auth-patterns

# FastAPI Authentication Patterns

**Purpose:** Autonomously implement, validate, and debug FastAPI authentication systems with multiple strategies.

**Activation Triggers:**
- Implementing user authentication
- Securing API endpoints
- JWT token generation/validation issues
- OAuth2 flow configuration
- Permission and role-based access control
- Supabase authentication integration
- Authentication errors (401, 403)
- Password hashing and security

**Key Resources:**
- `scripts/setup-jwt.sh` - Initialize JWT authentication system
- `scripts/validate-auth.sh` - Validate authentication configuration
- `templates/jwt_auth.py` - Complete JWT authentication implementation
- `templates/oauth2_flow.py` - OAuth2 password flow with scopes
- `templates/supabase_auth.py` - Supabase integration for FastAPI
- `examples/protected_routes.py` - Protected endpoint patterns
- `examples/permission_system.py` - Role and permission-based access

## Authentication Strategies

### 1. JWT Token Authentication

**Use When:**
- Need stateless authentication
- Building API for mobile/web clients
- Require token expiration control
- Implementing refresh token patterns

**Setup:**
```bash
./scripts/setup-jwt.sh
```

**Core Components:**
- Password hashing with Argon2 (pwdlib)
- JWT token generation with expiration
- Token validation and user extraction
- Secure secret key management

**Implementation Pattern:**
```python
# Hash passwords (never store plaintext)
password_hash = PasswordHash.recommended()
hashed = password_hash.hash(plain_password)

# Generate JWT token
def create_access_token(data: dict, expires_delta: timedelta):
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + expires_delta
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm="HS256")

# Validate token and extract user
async def get_current_user(token: str = Depends(oauth2_scheme)):
    payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
    username = payl