Add OAuth2 middleware and enhance inbound auth docs

[loveyana]

📋 Description

Add a comprehensive OAuth2 3-Legged OAuth (3LO) middleware for Starlette-based frameworks with first-class VeIdentity User Pool integration.

✨ Features

Core OAuth2 Functionality

• OAuth2 Authorization Code Flow - Complete 3LO implementation with automatic token exchange
• PKCE Support - Enhanced security for public clients via Proof Key for Code Exchange
• Automatic Token Refresh - Seamlessly refresh tokens before expiration using refresh_token grant
• Signed Cookie Sessions - HMAC-SHA256 signed cookies with optional encryption for session storage
• State Parameter Protection - CSRF protection via secure random state with server-side validation

VeIdentity Integration

• OAuth2Config.from_veidentity() - Simplified configuration requiring only 3 parameters:

  OAuth2Config.from_veidentity(
      user_pool_name="my-app",
      client_name="my-app-web", 
      redirect_uri="https://myapp.com/oauth2/callback",
  )

• Auto Resource Management - Automatically creates user pool, client, and registers callbacks
• OIDC Discovery - Supports /.well-known/openid-configuration for endpoint discovery

Framework Support

• Starlette - Native support for the base ASGI framework
• FastAPI - Full compatibility (FastAPI extends Starlette)
• Any Starlette-based framework - Works with frameworks built on Starlette

Production-Ready Features

• Pluggable State Storage - StateStore Protocol for custom backends (Redis, database)
• Built-in InMemoryStateStore - Default implementation with TTL and probabilistic pruning
• API vs Browser Detection - Returns 401 JSON for API requests, redirects for browser requests
• HTTP Connection Pooling - Configurable httpx client with connection limits
• Cookie Size Warnings - Alerts when session cookies approach browser limits

🚀 Quick Start

from fastapi import FastAPI
from veadk.auth.middleware.oauth2_auth import OAuth2Config, setup_oauth2

app = FastAPI()

handler = setup_oauth2(
    app,
    OAuth2Config.from_veidentity(
        user_pool_name="my-app",
        client_name="my-app-web",
        redirect_uri="https://myapp.com/oauth2/callback",
    ),
)

@app.get("/")
async def home(request: Request):
    session = handler.get_session(request)
    return {"user": session.user_id}

📁 Files Changed

File	Description
veadk/auth/middleware/oauth2_auth.py	Main OAuth2 middleware implementation

🔧 Configuration Options

Category	Options
OAuth2	authorize_url, token_url, client_id, client_secret, scope, use_pkce
Session	session_cookie_name, session_timeout_seconds, cookie_secure, cookie_samesite
Token Refresh	token_refresh_threshold_seconds, auto_refresh_token
HTTP Client	http_timeout_seconds, http_max_connections, http_max_keepalive_connections
API Behavior	api_path_prefixes (paths that return 401 instead of redirect)

🔒 Security Features

• ✅ PKCE (Proof Key for Code Exchange)
• ✅ State parameter CSRF protection
• ✅ HMAC-SHA256 cookie signing
• ✅ Constant-time signature comparison
• ✅ Secure redirect validation (prevents open redirect)
• ✅ Cookie security attributes (Secure, HttpOnly, SameSite)

📖 Related Documentation

• OAuth 2.0 RFC 6749
• PKCE RFC 7636
• VeIdentity User Pool Documentation