feat: Add authentication middleware and integration documentation

[elmorem]

Summary

• Adds AuthenticationMiddleware for automatic authentication enforcement across all routes
• Creates generate_auth_config.py script to generate JWT secrets and API keys for development
• Provides comprehensive authentication integration guide in docs/AUTHENTICATION.md
• Includes .env.auth.example template for easy configuration

What's Included

Authentication Middleware

• shared/auth/middleware.py: Automatic authentication enforcement
  • Validates JWT Bearer tokens and API keys
  • Configurable exempt paths (health, docs, metrics)
  • Returns 401 for invalid authentication
  • Attaches UserIdentity to request.state.user

Development Tools

• scripts/generate_auth_config.py: Generates JWT secrets and API keys
  • Executable script for quick setup
  • Creates secure random secrets
  • Provides example configuration

Configuration

• .env.auth.example: Complete configuration template
  • JWT settings (secret, algorithm, expiration)
  • API key settings
  • Authentication enforcement toggles
  • Exempt paths configuration

Documentation

• docs/AUTHENTICATION.md: Comprehensive 400+ line guide
  • Quick start instructions
  • Two integration patterns (middleware vs dependencies)
  • JWT token creation examples
  • API key management
  • Permission system documentation
  • Security best practices
  • Troubleshooting guide

Integration Options

Option 1: Middleware (Recommended)

app.add_middleware(
    AuthenticationMiddleware,
    jwt_handler=jwt_handler,
    api_key_handler=api_key_handler,
    exempt_paths=["/health", "/docs", "/metrics"],
)

Option 2: Dependencies

@app.get("/sessions")
async def list_sessions(
    user: Annotated[UserIdentity, Depends(get_current_user)],
):
    return {"user_id": user.user_id}

Test Plan

• Middleware created with proper authentication flow
• Generate script creates valid JWT secrets
• Generate script creates valid API keys
• Configuration template includes all settings
• Documentation covers all integration patterns
• Code formatted with black
• Type checking passed with mypy
• All files committed and pushed

🤖 Generated with Claude Code