feat: support a two-leg authorization code flow for web-hosted clients

A provider without a callback_handler now stops after the redirect:
Flow#run! saves a pending authorization in storage, keyed by state,
hands the authorization URL to redirect_handler, and returns :redirect,
and MCP::Client::HTTP raises Flow::AuthorizationPendingError instead of
retrying. Flow#finish! completes the authorization in the request that
receives the redirect, which may run in another process.

finish! looks the pending authorization up by state before any request,
validates the RFC 9207 iss against the recorded issuer before consuming
it, reads an error response only after that check, and redeems the code
at the recorded token endpoint with the recorded client registration,
resource, and redirect_uri, without running discovery again.

Author: atesgoral

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Support a two-leg authorization code flow for web-hosted clients (#573)
+
 ## [1.6.0] - 2026-09-21
 
 This release lets an application configure, on the OAuth provider, the requests the flow makes to

docs/_client/authorization.md

@@ -90,12 +90,14 @@ Required keyword arguments to `Provider.new`:
   an explicit value always wins.
 - `redirect_uri`: String. Must use HTTPS or be a loopback URL (`localhost`, `127.0.0.0/8`, `::1`); other values raise `Provider::InsecureRedirectURIError`.
 - `redirect_handler`: Callable invoked with the fully-built authorization `URI`. Typically opens the user's browser.
-- `callback_handler`: Callable that returns `[code, state]` or `[code, state, iss]` after the user is redirected back to `redirect_uri`. Returning the 3-element form
-  (with `iss` set to the RFC 9207 `iss` parameter from the redirect, or `nil` when absent) opts into SEP-2468 issuer validation: a present `iss` must match
-  the authorization server's issuer, and a missing one is rejected when the server advertises `authorization_response_iss_parameter_supported`.
 
 Optional keyword arguments:
 
+- `callback_handler`: Callable that returns `[code, state]` or `[code, state, iss]` after the user is redirected back to `redirect_uri`. Returning the 3-element form
+  (with `iss` set to the RFC 9207 `iss` parameter from the redirect, or `nil` when absent) opts into SEP-2468 issuer validation: a present `iss` must match
+  the authorization server's issuer, and a missing one is rejected when the server advertises `authorization_response_iss_parameter_supported`.
+  Omit it when the redirect arrives in a later request, as it does in a web application; see [Two-Leg Authorization for Web Applications](#two-leg-authorization-for-web-applications).
+- `pending_authorization_max_age`: Integer seconds a pending authorization stays redeemable after the redirect when `callback_handler` is omitted. Defaults to 600.
 - `scope`: Space-separated scopes to request when the server's `WWW-Authenticate` does not specify one.
 - `authorization_request_validator`: Callable invoked with an `MCP::Client::OAuth::AuthorizationRequest` before any authorization request is built.
   Returning a falsy value abandons the flow with `Flow::AuthorizationRefusedError`. See [Reviewing the authorization request](#reviewing-the-authorization-request).
@@ -106,7 +108,8 @@ Optional keyword arguments:
   issued it (SEP-2352): when the server's authorization server changes, the SDK discards the stale registration and its tokens and re-registers automatically
   (portable CIMD `client_id`s are kept). Saved `tokens` carry an `"issuer"` member of their own, recording the authorization server that minted them, which is what
   lets a later refresh refuse a server the MCP server has since renamed. Treat both hashes as opaque and persist them as-is; a storage that writes out selected members
-  instead drops these bindings with no error.
+  instead drops these bindings with no error. Without `callback_handler`, it must also hold pending authorizations; see
+  [Two-Leg Authorization for Web Applications](#two-leg-authorization-for-web-applications).
 - `client_id_metadata_document_url`: URL where you publish a Client ID Metadata Document
   (`draft-ietf-oauth-client-id-metadata-document` and the MCP authorization specification).
   When the authorization server advertises `client_id_metadata_document_supported: true`,
@@ -173,6 +176,74 @@ provider = MCP::Client::OAuth::Provider.new(
 )
 ```
 
+### Two-Leg Authorization for Web Applications
+
+`callback_handler` keeps the flow open until the code comes back, so the process that sent the user to the authorization server stays blocked for as long as
+the user takes to sign in and consent. That suits CLI and desktop clients. In a web application the redirect arrives as a separate HTTP request, often served
+by a different process, and relaying the code to a request held open for that long is impractical. Omit `callback_handler` and the flow runs in two legs,
+as the TypeScript SDK's `auth()` and `finishAuth()` and the Rust SDK's `get_authorization_url` and `exchange_code_for_token` do:
+
+1. When the transport meets a `401`, or a `403` step-up challenge, the flow runs discovery and registration as usual, saves a pending authorization in `storage`
+   keyed by the `state` it generated, hands the authorization URL to `redirect_handler`, and raises `MCP::Client::OAuth::Flow::AuthorizationPendingError`
+   instead of retrying. The error's `authorization_url` reader returns the same URL, so the application can send the user there from wherever is convenient.
+2. The request that receives the redirect calls `MCP::Client::OAuth::Flow#finish!` with the redirect's whole query. Requests made afterwards use the stored tokens.
+
+```ruby
+def mcp_oauth_provider(user)
+  MCP::Client::OAuth::Provider.new(
+    client_metadata: {
+      client_name: "My MCP App",
+      redirect_uris: ["https://app.example.com/oauth/mcp/callback"],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+    },
+    redirect_uri: "https://app.example.com/oauth/mcp/callback",
+    redirect_handler: ->(_authorization_url) {},
+    storage: McpCredentialStorage.new(user), # per-user storage, including pending authorizations
+  )
+end
+
+# In a request that talks to the MCP server:
+transport = MCP::Client::HTTP.new(url: server_url, oauth: mcp_oauth_provider(current_user))
+begin
+  tools = MCP::Client.new(transport: transport).tools
+rescue MCP::Client::OAuth::Flow::AuthorizationPendingError => e
+  redirect_to(e.authorization_url.to_s, allow_other_host: true)
+end
+
+# In the action serving `redirect_uri`:
+MCP::Client::OAuth::Flow.new(provider: mcp_oauth_provider(current_user)).finish!(
+  server_url: server_url,
+  callback_params: request.query_parameters,
+)
+```
+
+The first leg can also run without a request to the MCP server: `MCP::Client::OAuth::Flow.new(provider: provider).run!(server_url: server_url)` returns `:redirect`,
+and the flow's `authorization_url` reader returns the URL it handed to `redirect_handler`.
+
+The storage must also respond to `save_pending_authorization(state, pending)`, `pending_authorization(state)`, and `delete_pending_authorization(state)`;
+`Provider.new` raises `Provider::PendingAuthorizationStorageError` when it does not. A pending authorization is a Hash of JSON-compatible values that includes
+the PKCE verifier, so keep it where you keep credentials, persist it as-is, and share it between the processes that can receive the redirect.
+`InMemoryStorage` implements the methods for a single process.
+
+`finish!` redeems the code the way the authorization began, and refuses anything else with `Flow::AuthorizationError`:
+
+- The pending authorization is looked up by `state` before any request is made. An unknown, already used, or malformed one is refused,
+  and one older than `pending_authorization_max_age` is discarded and refused.
+- `server_url` must name the MCP server the authorization began with.
+- The RFC 9207 `iss` parameter is validated against the recorded issuer before the pending authorization is consumed, so a forged callback carrying a valid `state`
+  cannot discard the verifier the legitimate callback needs. Because `finish!` sees the whole query, a missing `iss` is refused whenever the authorization server
+  advertises `authorization_response_iss_parameter_supported`.
+- The pending authorization is then consumed, so it is redeemed at most once. An `error` response is raised with its `error` and `error_description`,
+  bounded as [token endpoint errors](#token-endpoint-errors) are; it is read only after the `iss` check, since in a mix-up those parameters are the attacker's.
+- The code is redeemed at the recorded token endpoint, with the client registration, `resource`, and `redirect_uri` used when the authorization began,
+  without running discovery again (SEP-2352). A registration replaced in the meantime is refused.
+
+{: .important }
+> `state` proves that this SDK started the authorization, not which user did. Binding the callback to the user who started it is the application's responsibility:
+> scope `storage` to that user, as in the example, so that a callback delivered to another user's session finds no pending authorization.
+
 ### Token Endpoint Errors
 
 When a token exchange or refresh fails, `MCP::Client::OAuth::Flow::AuthorizationError` includes the HTTP status and

lib/mcp/client/http.rb

@@ -902,15 +902,25 @@ def parse_www_authenticate_from_error(error)
         MCP::Client::OAuth::Discovery.parse_www_authenticate(header)
       end
 
+      # A provider without a `callback_handler` finishes the authorization in the request that receives the redirect,
+      # not here, so there is nothing to retry with yet: the pending authorization surfaces as
+      # `Flow::AuthorizationPendingError`, and requests made after `Flow#finish!` pick up the stored tokens.
       def run_full_authorization_flow!(flow:, params:)
         # Use the URL snapshotted at `initialize` time so a post-construction
         # mutation of `@url` cannot redirect PRM/AS discovery and the authorize
         # URL to an attacker-controlled host.
-        flow.run!(
+        result = flow.run!(
           server_url: @oauth_server_url,
           resource_metadata_url: params["resource_metadata"],
           scope: params["scope"],
         )
+        return unless result == :redirect
+
+        raise MCP::Client::OAuth::Flow::AuthorizationPendingError.new(
+          "Authorization is pending: the user was sent to the authorization server, and the request can be retried " \
+            "once `MCP::Client::OAuth::Flow#finish!` completes the authorization with the redirect's query.",
+          authorization_url: flow.authorization_url,
+        )
       end
 
       # Tries to swap a saved `refresh_token` for a fresh access token. Returns truthy