Module mcp_oauth 

P5-2 (COMPOSABLE-HARNESS-DESIGN.md §2 module 15 D7 row 2 “OAuth”; §2.1 dep “model.oauth → trust-grade token storage” — the same security class applies here): OAuth PROTOCOL support for authenticated remote MCP servers.

Scope, stated plainly. This module implements:

• the OAuth 2.0 Device Authorization Grant (RFC 8628) — the non-interactive path: no browser/redirect listener needed, just a user_code/verification_uri a caller prints and a background poll;
• refresh-token exchange.

It does NOT implement the interactive authorization-code + PKCE + local-redirect-listener browser flow — that needs a UI to open a browser and a local HTTP listener to catch the redirect, which is tui’s job (P5 item #4, not yet built). This is a tui-deferred citation, not a silent gap: a server that only offers the browser flow (no device-code grant) simply isn’t reachable through this module yet.

Token storage is NOT this module’s job. This module only speaks the wire protocol and returns McpOAuthTokens values — persisting them is a CLI-layer concern (crates/cli/src/userconfig.rs’s save_mcp_oauth_tokens/load_mcp_oauth_tokens), same trust-grade posture (owner-only permissions, user/global-directory-only, never project-readable) as Config::api_key/save_api_key (§3.2 S13) — this crate never touches a filesystem for a credential.

Structs

DeviceAuthorization

The RFC 8628 device-authorization-response fields this module needs.

McpOAuthTokens

A trust-grade credential pair — see the module doc comment for why this crate never persists one itself.

OAuthEndpoints

The endpoints/identity an MCP server’s OAuth device-code flow needs. Carries no token — see the module doc comment.

Enums

DevicePollOutcome

One poll of the token endpoint for a device code — RFC 8628 §3.5. The server replies authorization_pending until the user finishes at verification_uri; the caller (e.g. poll_until_authorized) is expected to sleep interval_secs and retry.

Functions

bearer_header

Build the Authorization: Bearer <token> header value for a stored McpOAuthTokens — the shape crate::mcp::McpClient::connect_http/ connect_sse’s headers map expects.

poll_device_token

A single token-endpoint poll for the device-code grant.

refresh_token

Exchange a refresh token for a new access token.

run_device_flow

The whole non-interactive device-code flow: start authorization, invoke on_prompt exactly once with the DeviceAuthorization (so the caller can print verification_uri/user_code for the user), then poll until authorized/denied/expired — bounded by expires_in_secs, sleeping interval_secs between attempts (never faster, per RFC 8628’s slow_down semantics — a slow_down response widens the interval by a further 5s, same as the spec recommends).

start_device_authorization

Step 1 of RFC 8628: request a device/user code pair.