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}

A issue não nomeia arquivos nem testes. Comece localizando a implementação existente de OAuth e seus helpers de discovery, registro, fluxo interativo, obtenção de tokens e armazenamento; em seguida, revise a #1240 e os requisitos dos maintainers. Valide um design modular e retomável com esboços em TypeScript antes de coordenar as alterações equivalentes em Python; considera-se concluído quando os fluxos existentes do cliente continuarem funcionando e os casos de uso com proxy puderem interceptar requisições e retomar a autenticação.