Merge pull request #579 from atesgoral/ag/oauth-explicit-empty-scope

Add a scope selector for OAuth authorization-code clients

Author: koic

docs/_client/authorization.md

@@ -47,9 +47,9 @@ pass an `MCP::Client::OAuth::Provider` to the transport instead of a static `Aut
 - On a `403 Forbidden` whose `WWW-Authenticate` header carries `error="insufficient_scope"` (OAuth 2.0 step-up, RFC 6750 Section 3.1 and the MCP scope-selection-strategy),
   run a fresh authorization request for the union of the currently granted scope and the scope named in the challenge, then retry the failed request once.
   The refresh path is bypassed because refreshing would re-issue the same scope set the server just rejected. A `403` without that challenge is surfaced unchanged.
-- Request the `offline_access` scope when `client_metadata[:grant_types]` includes `refresh_token` and the authorization server advertises `offline_access` in its metadata
-  `scopes_supported` (SEP-2207). This is what lets the server issue the `refresh_token` used above. As an SDK-level safeguard, when the authorization server does not advertise
-  `offline_access` the scope is also stripped from any other source (challenge, PRM, or provider-supplied scope) so a server that does not support it never receives it.
+- Request `offline_access` when the client declares the `refresh_token` grant and the authorization server advertises it in
+  `scopes_supported` (SEP-2207). The PRM scope selector below runs before this augmentation and cannot disable it.
+  Unsupported `offline_access` is stripped from resolved challenge, PRM, and provider scopes.
 
 ```ruby
 require "mcp"
@@ -99,7 +99,22 @@ Optional keyword arguments:
   Omit it when the redirect arrives in a later request, as it does in a web application; see [Authorization in Web Applications](#authorization-in-web-applications).
 - `pending_authorization_max_age`: Integer seconds a pending authorization stays redeemable, counted from the moment `run!` saves it, when `callback_handler`
   is omitted. Defaults to 600.
-- `scope`: Space-separated scopes to request when the server's `WWW-Authenticate` does not specify one.
+- `scope`: Space-separated fallback scopes when neither a challenge nor PRM advertises scopes.
+- `scope_selector`: Optional callable for narrowing Protected Resource Metadata (PRM) defaults in the authorization-code flow.
+  It is invoked only when no nonempty challenged scope was supplied and PRM supplies the default `scopes_supported` list,
+  before `offline_access` augmentation, request validation, and client registration. It receives a read-only array of PRM tokens.
+  Malformed PRM tokens raise `Flow::AuthorizationError` before the callback. It must return an array containing a subset;
+  custom scopes and `nil` results raise `ArgumentError`. Return `[]` to request
+  none of those PRM defaults. Challenged scopes, including the step-up union, and provider fallback bypass the selector;
+  use `authorization_request_validator` to accept or refuse challenged scopes. With no selector, default behavior is unchanged.
+  This hook does not control `offline_access` augmentation or alter authorization-endpoint query parameters. Returning `[]`
+  does not guarantee an omitted `scope` parameter: refresh policy can add `offline_access`, and a prefilled endpoint scope
+  survives when the flow has no scope of its own and is included in the validator's scope list. Repeated endpoint `scope`
+  parameters that would survive are rejected before registration. The authorization server can also apply defaults or reject
+  the request ([RFC 6749 Section 3.3](https://www.rfc-editor.org/rfc/rfc6749#section-3.3)); inspect the granted scopes.
+  For example, with PRM defaults `mcp:read mcp:write`, `scope_selector: ->(scopes) { scopes & ["mcp:read"] }` narrows the
+  default request to `mcp:read`; `scope_selector: ->(_scopes) { [] }` requests no PRM defaults. If the authorization server supports
+  `offline_access` and the client declares `refresh_token`, either request still includes `offline_access` afterward.
 - `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).
 - `http_client_customizer`: Callable invoked with the Faraday connection the SDK builds for the OAuth flow's own requests, after its defaults and before its origin guard.
@@ -436,8 +451,8 @@ provider = MCP::Client::OAuth::Provider.new(
 )
 ```
 
-The argument is an `MCP::Client::OAuth::AuthorizationRequest` carrying `authorization_server` (the selected issuer), `scopes` (an Array, empty when neither
-the challenge nor the metadata named any), `server_url`, and `resource`. It is one object rather than keyword arguments so that later revisions of the specification
+The argument is an `MCP::Client::OAuth::AuthorizationRequest` carrying `authorization_server` (the selected issuer), `scopes` (an Array of explicit requested scope tokens),
+`server_url`, and `resource`. It is one object rather than keyword arguments so that later revisions of the specification
 can add to it without changing the shape you wrote. Only the named readers are the contract. The positional access a `Struct` also happens to provide
 (`request[0]`, `to_a`, `each`) is not, and can break when the representation changes.
 
@@ -450,7 +465,10 @@ Compare the issuer as a whole string, the way the SDK compares it everywhere els
 and a legacy authorization server whose metadata never named an issuer arrives as `nil`, which an exact comparison refuses instead of raising.
 
 The provider is only half of the decision. The MCP server chose the scopes too, so a request naming a provider you allow can still ask for more than that server has
-any business asking for. `scopes` rides on the request so that a host with a policy per server can apply it:
+any business asking for. `scopes` rides on the request so that a host with a policy per server can apply it. On the authorization-code flow,
+this includes any single prefilled endpoint scope that survives when the flow has no scope of its own, including after a selector returns `[]`.
+The query names are decoded the same way as the URL builder; repeated `scope` parameters that would survive are rejected before registration.
+The following policy therefore checks the explicit scopes that the authorization URL will send:
 
 ```ruby
 ALLOWED_SCOPES = { "https://api.example.com/mcp" => ["mcp:read", "mcp:write"] }
@@ -463,6 +481,9 @@ provider = MCP::Client::OAuth::Provider.new(
 )
 ```
 
+In this example, an empty `request.scopes` approves a request with no explicit scope tokens. This is not a ceiling on what the authorization server may grant:
+it can still apply defaults, so inspect the granted token scopes before treating a connection as unscoped.
+
 A host with a user to ask can put the decision to them instead. The request carries what such a prompt has to name: the provider, the scopes, and the server that asked for them.
 
 It runs on all three grants, after that server's metadata has been fetched (which is where the validated issuer comes from) and before any registration, credential,

lib/mcp/client/oauth/flow.rb

@@ -19,6 +19,9 @@ class Flow
         METADATA_DIAGNOSTIC_MAX_LENGTH = 128
         METADATA_URL_MAX_LENGTH = 2048
 
+        # RFC 6749 scope-token: visible ASCII except space, double quote, and backslash.
+        SCOPE_TOKEN_FORMAT = /\A[\x21\x23-\x5B\x5D-\x7E]+\z/.freeze
+
         # Token request parameters the flow sets itself. Its values win over a provider's `token_request_params`,
         # so a provider naming one of these is refused rather than left believing its value was sent.
         RESERVED_TOKEN_REQUEST_PARAMS = [
@@ -264,20 +267,23 @@ def run!(server_url:, resource_metadata_url: nil, scope: nil)
 
           ensure_pkce_supported!(as_metadata)
 
-          effective_scope = resolve_scope(scope: scope, prm: prm)
+          effective_scope = resolve_scope(scope: scope, prm: prm, select_prm_scope: true)
           effective_scope = normalize_offline_access_scope(effective_scope, as_metadata: as_metadata)
+          endpoint_uri, endpoint_params = authorization_endpoint_parameters(as_metadata: as_metadata)
+          request_scope = authorization_request_scope(scope: effective_scope, endpoint_params: endpoint_params)
 
           # Asked before registering, not after: a refusal must not leave this client registered at an authorization server
-          # the embedding application has just rejected.
-          authorize_request!(as_metadata: as_metadata, scope: effective_scope, server_url: server_url, resource: resource)
+          # the embedding application has just rejected. Use the scopes that will actually reach the browser URL.
+          authorize_request!(as_metadata: as_metadata, scope: request_scope, server_url: server_url, resource: resource)
 
           client_info = ensure_client_registered(as_metadata: as_metadata)
 
           pkce = PKCE.generate
           state = SecureRandom.urlsafe_base64(32)
 
           authorization_url = build_authorization_url(
-            as_metadata: as_metadata,
+            endpoint_uri: endpoint_uri,
+            endpoint_params: endpoint_params,
             client_id: client_info_required_value(client_info, "client_id"),
             scope: effective_scope,
             state: state,
@@ -850,16 +856,16 @@ def ensure_same_origin!(url, label:, server_url:)
         # Hands the embedding application the authorization server and the scopes that are about to be requested,
         # and abandons the flow when it refuses them.
         #
-        # Both values are chosen by the MCP server: it names its own authorization server in Protected
-        # Resource Metadata and states the scopes in `scopes_supported` or the `WWW-Authenticate` challenge.
+        # The MCP server names its authorization server in Protected Resource Metadata and states scopes
+        # in `scopes_supported` or the `WWW-Authenticate` challenge. Authorization-code policy also sees
+        # any prefilled endpoint scope that will survive URL assembly.
         # Neither the specification nor any MCP SDK binds that choice to the server's own identity,
         # and validating that a token was issued for the intended audience is a responsibility the specification
         # places on MCP servers rather than on clients.
         # A host that knows which providers its user deals with can apply that knowledge here.
         #
-        # The scopes are passed on unchanged whatever the host decides, because the specification requires
-        # a client to treat the challenged scopes as authoritative for the operation; the choice offered is
-        # to proceed or to stop, not to quietly ask for less. A provider without the hook proceeds as before.
+        # Challenged scopes are authoritative for the operation and bypass the PRM scope selector.
+        # The validator can accept or refuse them, not quietly request fewer scopes.
         #
         # Only asked when a new grant is being requested. A refresh is not a new grant, and the host already answered
         # this question for that authorization server, so `refresh!` enforces `ensure_token_issuer!` instead:
@@ -1302,17 +1308,18 @@ def authorization_response_error(error, description)
           AuthorizationError.new(message, error: error, error_description: description)
         end
 
-        # Per MCP 2025-11-25 Authorization and the TS/Python SDKs, scope resolution
-        # prefers the `WWW-Authenticate` challenge first, then `scopes_supported`
-        # from the Protected Resource Metadata, and falls back to a provider-supplied
-        # scope only if both are absent. The provider-supplied scope must not pre-empt
-        # a server-advertised one.
-        def resolve_scope(scope:, prm:)
+        # MCP scope selection prefers the challenge, then PRM `scopes_supported`, then the provider's fallback.
+        # Authorization-code clients may narrow only the PRM default, before `offline_access` augmentation.
+        def resolve_scope(scope:, prm:, select_prm_scope: false)
           return scope if scope && !scope.empty?
 
           # `prm` is nil on the legacy path, where nothing advertises scopes.
           supported = prm && prm["scopes_supported"]
-          return supported.join(" ") if supported.is_a?(Array) && !supported.empty?
+          if supported.is_a?(Array) && !supported.empty?
+            return select_prm_scopes(supported) if select_prm_scope
+
+            return supported.join(" ")
+          end
 
           return @provider.scope if @provider.scope && !@provider.scope.empty?
 
@@ -1334,7 +1341,8 @@ def resolve_scope(scope:, prm:)
         #   the authorization request even though the AS will not honour it. Stripping here keeps the SDK's
         #   own request consistent with the AS's advertisement.
         #
-        # Returns `nil` when the result is empty so `build_authorization_url` omits the `scope` parameter entirely.
+        # Returns `nil` when empty so the URL builder adds no flow-owned scope parameter; a prefilled scope
+        # can still survive and is checked by the authorization-request validator.
         # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2207
         def normalize_offline_access_scope(scope, as_metadata:)
           scopes = scope.to_s.split
@@ -1354,6 +1362,28 @@ def server_supports_offline_access?(as_metadata)
           supported.is_a?(Array) && supported.include?("offline_access")
         end
 
+        # Selects a subset of the PRM default without changing challenges, provider fallback, or refresh policy.
+        def select_prm_scopes(scopes)
+          selector = @provider.scope_selector if @provider.respond_to?(:scope_selector)
+          return scopes.join(" ") unless selector
+
+          unless scopes.all? { |token| token.is_a?(String) && SCOPE_TOKEN_FORMAT.match?(token) }
+            raise AuthorizationError, "Protected Resource Metadata `scopes_supported` contains invalid OAuth scope tokens."
+          end
+
+          candidates = scopes.map { |token| token.dup.freeze }.freeze
+          candidate_index = candidates.to_h { |token| [token, true] }
+          selected = selector.call(candidates)
+          valid = selected.is_a?(Array) && selected.all? do |token|
+            token.is_a?(String) && SCOPE_TOKEN_FORMAT.match?(token) && candidate_index.key?(token)
+          end
+          unless valid
+            raise ArgumentError, "scope_selector must return an Array containing only scopes from PRM scopes_supported."
+          end
+
+          selected.empty? ? nil : selected.join(" ")
+        end
+
         def wants_refresh_token?
           metadata = @provider.client_metadata
           grant_types = metadata[:grant_types] || metadata["grant_types"]
@@ -1398,7 +1428,7 @@ def provider_client_id_metadata_document_url
           @provider.client_id_metadata_document_url
         end
 
-        def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_challenge:, resource:)
+        def authorization_endpoint_parameters(as_metadata:)
           authorization_endpoint = as_metadata["authorization_endpoint"]
           unless authorization_endpoint
             raise AuthorizationError,
@@ -1412,6 +1442,23 @@ def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_chall
               "Authorization server metadata `authorization_endpoint` is not a valid URI: #{e.message}."
           end
 
+          [uri, URI.decode_www_form(uri.query.to_s)]
+        end
+
+        # A flow scope replaces every endpoint scope; otherwise a single prefilled value survives.
+        # Decode once before policy approval and reuse those parameters when building the URL.
+        def authorization_request_scope(scope:, endpoint_params:)
+          return scope if scope
+
+          endpoint_scopes = endpoint_params.filter_map { |name, value| value if name == "scope" }
+          if endpoint_scopes.length > 1
+            raise AuthorizationError, "Authorization endpoint contains repeated `scope` parameters."
+          end
+
+          endpoint_scopes.first
+        end
+
+        def build_authorization_url(endpoint_uri:, endpoint_params:, client_id:, scope:, state:, code_challenge:, resource:)
           # A parameter the flow sets replaces any of the same name the endpoint URL already carries.
           # RFC 6749 Section 3.1 forbids sending a parameter twice, and which of two values a server would honor is
           # its own choice; on the legacy path the endpoint URL is served by the MCP server, whose query must not speak
@@ -1433,10 +1480,10 @@ def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_chall
           own_params << ["resource", resource] if resource
           dropped_names = own_params.map(&:first) + ["request", "request_uri"]
 
-          params = URI.decode_www_form(uri.query.to_s).reject { |name, _value| dropped_names.include?(name) }
-          uri.query = URI.encode_www_form(params + own_params)
+          params = endpoint_params.reject { |name, _value| dropped_names.include?(name) }
+          endpoint_uri.query = URI.encode_www_form(params + own_params)
 
-          uri
+          endpoint_uri
         end
 
         def exchange_authorization_code(as_metadata:, client_info:, code:, code_verifier:, resource:, redirect_uri: @provider.redirect_uri)

lib/mcp/client/oauth/provider.rb

@@ -37,6 +37,10 @@ module OAuth
       #   `run!` saves it, when `callback_handler` is omitted. Defaults to `DEFAULT_PENDING_AUTHORIZATION_MAX_AGE`.
       # - `scope`   - String of space-separated scopes to request when the server's
       #   `WWW-Authenticate` does not specify one.
+      # - `scope_selector` - Callable receiving a read-only Array of PRM `scopes_supported` tokens when
+      #   those defaults are selected without a challenged scope. Return an Array containing a subset;
+      #   `[]` requests none of the PRM defaults. Challenged scopes and provider fallback bypass it.
+      #   The existing `offline_access` policy runs afterward; endpoint query parameters are unchanged.
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
       #   an `InMemoryStorage`. Persisted `client_information` is stamped with
@@ -108,6 +112,7 @@ class PendingAuthorizationStorageError < ArgumentError; end
         attr_reader :client_metadata,
           :redirect_uri,
           :scope,
+          :scope_selector,
           :storage,
           :redirect_handler,
           :callback_handler,
@@ -120,6 +125,7 @@ def initialize(
           redirect_handler:,
           callback_handler: nil,
           scope: nil,
+          scope_selector: nil,
           storage: nil,
           client_id_metadata_document_url: nil,
           authorization_request_validator: nil,
@@ -147,6 +153,10 @@ def initialize(
                 "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
           end
 
+          unless scope_selector.nil? || scope_selector.respond_to?(:call)
+            raise ArgumentError, "scope_selector must respond to call (got #{scope_selector.class})."
+          end
+
           http_client_customizer = validated_http_client_customizer(http_client_customizer)
 
           unless pending_authorization_max_age.is_a?(Integer) && pending_authorization_max_age.positive?
@@ -170,6 +180,7 @@ def initialize(
           @redirect_handler = redirect_handler
           @callback_handler = callback_handler
           @scope = scope
+          @scope_selector = scope_selector
           @storage = storage
           @client_id_metadata_document_url = client_id_metadata_document_url
           @authorization_request_validator = authorization_request_validator