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 用例能夠攔截請求並恢復驗證時，即視為完成。