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}

该 issue 未指明文件或测试。首先定位现有的 OAuth 实现，以及用于 discovery、registration、interactive flow、token fetching 和 storage 的辅助工具，然后查看 #1240 和 maintainer 的要求。在协调等效的 Python 修改之前，先使用 TypeScript 草图验证模块化、可恢复的设计；当现有 client flow 仍能正常工作，并且 proxy 用例能够拦截请求并恢复认证时，即视为完成。