Extract OAuth flow logic into reusable components for proxy use cases

Summary

Refactor OAuth implementation so the flow logic and state machine are usable by server-side proxy services, not just client-side browser flows.

Problem

The SDK's OAuth implementation is designed for local client-side flows (opening a browser locally). The business logic is embedded inside an httpx auth module, making it hard to reuse for other scenarios.

While individual helper functions have been extracted (PKCE utilities, token exchange, discovery), the core state machine that orchestrates the OAuth flow is not reusable. Proxy services that need to perform OAuth on behalf of users currently have to reimplement significant portions of the flow themselves — and when the SDK updates its OAuth logic, those reimplementations can fall out of sync.

Goal

• Make the OAuth portions of the SDK compatible with proxy/gateway services that currently use custom workarounds
• When an issue is fixed in the SDK, updating the SDK version should fix it everywhere — no custom OAuth reimplementations needed
• Keep existing client-side flows working

Design Requirements (from maintainer discussion, Feb 2026)

Modularization into zones: Break the monolithic OAuth flow into modular, overridable pieces:

• Discovery — obtaining and potentially customizing discovery URLs
• Client Registration — dynamic client registration
• Interactive Flow — authorization URL generation, redirect handling
• Token Fetching — code exchange, refresh, new token extensions (XA, WIF)
• Token Storage — pluggable storage (already exists)

Key requirements:

• Each zone should operate as a pure function requiring minimal state
• Every HTTP request in the flow must be interceptable — allow injection of a custom HTTP client/fetch interface (httpx client in Python, fetch in TypeScript) for custom headers, metrics, response handling
• Support an "Auth Required" state as an SDK primitive — when a server responds with 401/403 mid-flow, the SDK should capture discovery metadata, scope, and WWW-Authenticate info and surface it so the calling application can handle it (rather than assuming auth happens upfront)
• The flow must be resumable — a caller should be able to pick up an auth flow at any point (e.g., after a redirect returns on a different machine/request)
• Support bypassing discovery when configuration is provided directly (important for enterprise environments with broken discovery)
• Support new token-getting extensions (XA, WIF) that don't require interactive flows

Next steps:

• Draft code sketches (potentially TypeScript first) to validate the modular function approach
• Cross-SDK coordination — this applies to both Python and TypeScript SDKs

Related

• #1240 - Implement OAuth relying on Authlib
• #2053 - Replace Field(description=...) with docstrings in auth models

_{AI Disclaimer}

El issue no menciona archivos ni pruebas. Empieza localizando la implementación existente de OAuth y sus helpers de discovery, registro, flujo interactivo, obtención de tokens y almacenamiento; después, revisa #1240 y los requisitos de los maintainers. Valida un diseño modular y reanudable con bocetos de TypeScript antes de coordinar los cambios equivalentes en Python; se considerará terminado cuando los flujos existentes del cliente sigan funcionando y los casos de uso con proxy puedan interceptar solicitudes y reanudar la autenticación.