feat(auth): add Authlib-backed OAuth adapter (related to #1240)

[harsh543]

Problem

The MCP Python SDK maintains a 1,600+ line bespoke OAuth2 client stack that bundles metadata discovery, dynamic client registration, token exchange, PKCE, and refresh into a single monolithic class (OAuthClientProvider). As supported grant types and auth methods grow, this becomes expensive to maintain and extend — the motivation behind #1240.

Solution

Introduce AuthlibOAuthAdapter — an httpx.Auth-compatible plugin backed by Authlib's battle-tested AsyncOAuth2Client.

The adapter handles:

• client_credentials grant — fully self-contained, no browser interaction
• authorization_code + PKCE — S256 enforced, 128-char verifier ≈ 762-bit entropy
• Automatic token refresh — via Authlib's ensure_active_token + update_token hook
• TokenStorage bridge — bidirectional conversion between OAuthToken and Authlib's internal token dict; the storage protocol is unchanged
• Concurrency safety — anyio.Lock guards all mutable token state
• Secret hygiene — client_secret excluded from repr via Field(repr=False) to prevent accidental log leakage

Safety: incremental migration

This PR is purely additive. Nothing existing is modified:

• OAuthClientProvider — unchanged
• TokenStorage protocol — unchanged
• OAuthToken model — unchanged
• All existing tests pass unmodified

Both providers coexist. Callers can migrate one httpx.AsyncClient at a time.

Summary of Changes

Modified files

File	Change
pyproject.toml	Add authlib>=1.4.0 dependency
src/mcp/client/auth/__init__.py	Export AuthlibAdapterConfig, AuthlibOAuthAdapter

New files

File	Purpose
src/mcp/client/auth/authlib_adapter.py	AuthlibAdapterConfig (Pydantic config model) + AuthlibOAuthAdapter(httpx.Auth)
tests/client/auth/__init__.py	Test package marker
tests/client/auth/test_authlib_adapter.py	31 tests, 100% branch coverage

Architecture

httpx.AsyncClient(auth=AuthlibOAuthAdapter(...))
        │
        └── AuthlibOAuthAdapter(httpx.Auth)
                ├── AsyncOAuth2Client (Authlib)   ← owns token ops + auto-refresh
                ├── _initialize()                 ← OAuthToken → Authlib dict (on first use)
                ├── _on_token_update()            ← Authlib dict → OAuthToken (on every refresh)
                └── async_auth_flow()
                        1. ensure_active_token()  ← Authlib auto-refreshes if near expiry
                        2. inject Authorization: Bearer <token>
                        3. yield request → receive response
                        4. on 401: fetch fresh token (client_credentials or auth_code+PKCE)
                        5. re-inject header → yield retry request

AsyncOAuth2Client uses its own internal transport for token requests — no circular dependency with the parent httpx.AsyncClient.

Backward Compatibility

All existing public symbols from mcp.client.auth retain their current signatures. No deprecation warnings in this PR. Deprecation of OAuthClientProvider is planned for Phase 2 (announced one minor version in advance).

Test Coverage

31 tests covering all branches:

• Config defaults and field storage
• Scope list → space-separated string conversion
• _initialize: stored token, no token, partial token (missing optional fields)
• _on_token_update: full token dict, missing optional fields
• _fetch_client_credentials_token: with/without extra_token_params, token absent after fetch
• _perform_authorization_code_flow: missing endpoint, redirect_uri, redirect_handler, callback_handler; state mismatch; None state (or-guard short-circuit); empty code; token absent after fetch; happy path
• async_auth_flow: bearer injection, no-token path, 401 retry (client_credentials and auth_code), ensure_active_token called/skipped
• _inject_bearer: None token, missing access_token key, valid token
• Package import verification

Security

• PKCE S256 enforced; no plain method accepted
• State from secrets.token_urlsafe(32) (256 bits), validated via secrets.compare_digest
• client_secret excluded from repr — safe to log AuthlibAdapterConfig instances
• No access tokens logged at any level
• anyio.Lock prevents concurrent token mutation races

Future Work (not in this PR)

• Phase 2: Deprecate OAuthClientProvider; add resource indicator validation to adapter; add discovery helper to resolve PRM/OASM endpoints into AuthlibAdapterConfig
• Phase 3: Remove legacy providers; remove pyjwt[crypto]; add private_key_jwt via Authlib PrivateKeyJWT
• Phase 4: Token introspection (RFC 7662), DPoP (RFC 9449)

[harsh543]

This is a narrowly scoped, low‑risk foundation PR: it adds a minimal AuthProvider protocol and an Authlib‑based httpx.Auth adapter without touching existing OAuth behavior. It improves maintainability and future RFC coverage while preserving current defaults. Security posture is unchanged or better (no token logging, explicit Bearer injection, strict state validation). Recommended approve + merge.