ruby-mcp-client 1.1.0 → 2.1.0

data/lib/mcp_client/auth/oauth_provider.rb

@@ -11,6 +11,18 @@ module MCPClient
     # Handles the complete OAuth flow including server discovery, client registration,
     # authorization, token exchange, and refresh
     class OAuthProvider
+      # One auth-param (name = token / quoted-string) as it appears in a
+      # WWW-Authenticate challenge (RFC 7235 §2.1, optional whitespace around
+      # '='). Mirrors HttpTransportBase::AUTH_PARAM so provider-side challenge
+      # parsing segments headers exactly like the transport does.
+      AUTH_PARAM = /[A-Za-z0-9._~+-]+\s*=\s*(?:"(?:[^"\\]|\\.)*"|[^,\s]*)/
+      # A run of comma/space separated auth-params anchored at the start of a
+      # string. The run ends before a token that is NOT followed by '=' — the
+      # auth-scheme introducing the next challenge — while commas inside quoted
+      # values are consumed by the quoted-string branch, not treated as
+      # boundaries. Mirrors HttpTransportBase::AUTH_PARAMS_RUN.
+      AUTH_PARAMS_RUN = /\A(?:[\s,]*#{AUTH_PARAM})*/
+
       # @!attribute [rw] redirect_uri
       #   @return [String] OAuth redirect URI
       # @!attribute [rw] scope
@@ -21,8 +33,10 @@ module MCPClient
       #   @return [Object] Storage backend for tokens and client info
       # @!attribute [r] server_url
       #   @return [String] The MCP server URL (normalized)
+      # @!attribute [r] client_id_metadata_url
+      #   @return [String, nil] HTTPS URL of this client's Client ID Metadata Document (SEP-991)
       attr_accessor :redirect_uri, :scope, :logger, :storage
-      attr_reader :server_url
+      attr_reader :server_url, :client_id_metadata_url
 
       # Initialize OAuth provider
       # @param server_url [String] The MCP server URL (used as OAuth resource parameter)
@@ -32,19 +46,30 @@ module MCPClient
       # @param storage [Object, nil] Storage backend for tokens and client info
       # @param client_metadata [Hash] Extra OIDC client metadata fields for DCR registration.
       #   Supported keys: :client_name, :client_uri, :logo_uri, :tos_uri, :policy_uri, :contacts
+      # @param client_id_metadata_url [String, nil] HTTPS URL identifying this client per
+      #   MCP 2025-11-25 Client ID Metadata Documents (SEP-991). The URL doubles as the OAuth
+      #   client_id when the authorization server advertises client_id_metadata_document_supported,
+      #   skipping dynamic registration. Hosting the metadata JSON at that URL is the
+      #   application's responsibility.
+      # @raise [ArgumentError] if client_id_metadata_url is not an HTTPS URL with a path component
       def initialize(server_url:, redirect_uri: 'http://localhost:8080/callback', scope: nil, logger: nil, storage: nil,
-                     client_metadata: {})
+                     client_metadata: {}, client_id_metadata_url: nil)
         self.server_url = server_url
         self.redirect_uri = redirect_uri
         self.scope = scope
         self.logger = logger || Logger.new($stdout, level: Logger::WARN)
         self.storage = storage || MemoryStorage.new
+        self.client_id_metadata_url = client_id_metadata_url
         @extra_client_metadata = client_metadata
         @http_client = create_http_client
         # Protected resource metadata learned from a 401 WWW-Authenticate
         # challenge, reused by discovery so a challenge-advertised metadata URL
-        # is not re-derived (and possibly missed).
+        # is not re-derived (and possibly missed). The URL itself is retained
+        # separately so a failed fetch is retried authoritatively by discovery.
         @challenge_resource_metadata = nil
+        @challenge_metadata_url = nil
+        # Why a peer-advertised challenge URL was refused, if one was
+        @challenge_error = nil
       end
 
       # @param url [String] Server URL to normalize
@@ -52,6 +77,15 @@ module MCPClient
         @server_url = normalize_server_url(url)
       end
 
+      # Set the Client ID Metadata Document URL (SEP-991), validating it per the
+      # MCP spec: the client_id URL MUST use the "https" scheme and contain a
+      # path component (e.g. https://example.com/client.json).
+      # @param url [String, nil] HTTPS URL of this client's metadata document, or nil to clear
+      # @raise [ArgumentError] if the URL is not HTTPS or lacks a path component
+      def client_id_metadata_url=(url)
+        @client_id_metadata_url = url.nil? ? nil : validate_client_id_metadata_url(url)
+      end
+
       # Get current access token (refresh if needed)
       # @return [Token, nil] Current valid access token or nil
       def access_token
@@ -146,9 +180,34 @@ module MCPClient
         www_authenticate = response.headers['WWW-Authenticate'] || response.headers['www-authenticate']
         return nil unless www_authenticate
 
+        # Challenge parameters are read from the Bearer challenge's own
+        # segment only — never from the whole (possibly multi-challenge)
+        # header — so parameters belonging to Basic or another scheme cannot
+        # drive Bearer scope selection or resource metadata discovery. A
+        # header without a Bearer challenge carries no usable Bearer params.
+        bearer_params = bearer_challenge_segment(www_authenticate)
+
+        # MCP 2025-11-25: "Clients MUST treat the scopes provided in the
+        # challenge as authoritative for satisfying the current request" —
+        # including resetting a previously challenged scope when the current
+        # challenge carries none.
         url = extract_resource_metadata_url(www_authenticate)
+
+        # The challenge header is peer-controlled input: validate the
+        # advertised URL BEFORE storing, fetching, or recording any challenge
+        # state, so a malicious challenge cannot pivot this host into requests
+        # against internal services (SSRF) and cannot leave the provider
+        # holding half of a rejected challenge.
+        validate_peer_advertised_url!(url, 'resource metadata URL (from WWW-Authenticate challenge)') if url
+
+        @challenge_scope = bearer_params && extract_challenge_param(bearer_params, 'scope')
         return nil unless url
 
+        # Remember the advertised URL even if the fetch below fails, so a
+        # later discovery retries it instead of probing well-known URIs the
+        # challenge already superseded.
+        @challenge_metadata_url = url
+
         # This URL was explicitly advertised by the 401 challenge, so a 404 is a
         # misconfiguration to surface (strict), not a speculative miss to skip.
         metadata = fetch_resource_metadata(url, strict: true)
@@ -160,27 +219,93 @@ module MCPClient
 
       # Extract the protected-resource-metadata URL from a WWW-Authenticate header.
       # Per RFC 9728 the parameter is `resource_metadata`; a legacy `resource`
-      # parameter is accepted as a fallback for older servers.
+      # parameter is accepted as a fallback for older servers. Only the Bearer
+      # challenge's own segment is consulted, so a parameter belonging to
+      # another scheme's challenge can never drive discovery.
       # @param header [String] the WWW-Authenticate header value
       # @return [String, nil] the metadata URL if present
       def extract_resource_metadata_url(header)
+        params = bearer_challenge_segment(header)
+        return nil unless params
+
         # Auth-params may include optional whitespace around '=' (RFC 7235).
         # Quoted form: resource_metadata = "https://..."
-        if (m = header.match(/resource_metadata\s*=\s*"([^"]+)"/))
+        if (m = params.match(/resource_metadata\s*=\s*"([^"]+)"/))
           return m[1]
         end
 
         # Unquoted token form: resource_metadata = https://...
-        if (m = header.match(/resource_metadata\s*=\s*([^,\s]+)/))
+        if (m = params.match(/resource_metadata\s*=\s*([^,\s]+)/))
           return m[1]
         end
 
         # Legacy fallback: resource="https://..."
-        header.match(/resource\s*=\s*"([^"]+)"/)&.captures&.first
+        params.match(/resource\s*=\s*"([^"]+)"/)&.captures&.first
+      end
+
+      # Extract the Bearer challenge's own parameter segment from a (possibly
+      # multi-challenge) WWW-Authenticate header, so params belonging to other
+      # schemes (e.g. `Basic resource_metadata="...", Bearer realm="x"`) are
+      # never attributed to the Bearer challenge. Mirrors
+      # HttpTransportBase#bearer_challenge_segment.
+      # @param header [String, nil] the WWW-Authenticate header value
+      # @return [String, nil] the Bearer challenge's parameters (possibly
+      #   empty), or nil when the header has no Bearer challenge
+      def bearer_challenge_segment(header)
+        return nil unless header
+
+        # Locate the Bearer scheme token only OUTSIDE quoted strings: a
+        # quoted value such as realm="prefix Bearer x" must not anchor the
+        # segment.
+        masked = header.gsub(/"(?:\\.|[^"\\])*"/) { |q| "\"#{' ' * (q.length - 2)}\"" }
+        match = masked.match(/(?:\A|[\s,])Bearer(?=[\s,]|\z)/i)
+        return nil unless match
+
+        header[match.end(0)..][AUTH_PARAMS_RUN]
       end
 
+      # Extract an auth-param value from a WWW-Authenticate header
+      # (quoted or unquoted form, optional whitespace around '=').
+      # @param header [String] the WWW-Authenticate header value
+      # @param name [String] the auth-param name
+      # @return [String, nil] the parameter value if present
+      def extract_challenge_param(header, name)
+        if (m = header.match(/(?:^|[\s,])#{Regexp.escape(name)}\s*=\s*"([^"]*)"/i))
+          return m[1]
+        end
+
+        header.match(/(?:^|[\s,])#{Regexp.escape(name)}\s*=\s*([^,\s]+)/i)&.captures&.first
+      end
+
+      # Scope requested by the most recent WWW-Authenticate challenge.
+      # @return [String, nil]
+      attr_reader :challenge_scope
+
       private
 
+      # Resolve the scope for authorization/registration requests using the
+      # MCP 2025-11-25 scope selection strategy: the challenge's scope
+      # parameter is authoritative; then an explicitly configured scope
+      # (:all resolves to the AS-advertised scope list); then the Protected
+      # Resource Metadata's scopes_supported; otherwise omit scope entirely.
+      # @return [String, nil]
+      def resolved_scope
+        return @challenge_scope if @challenge_scope && !@challenge_scope.empty?
+
+        if scope == :all
+          all_scopes = supported_scopes
+          return all_scopes.join(' ') unless all_scopes.empty?
+        elsif scope
+          return scope
+        end
+
+        prm = @challenge_resource_metadata || @resource_metadata
+        prm_scopes = prm&.scopes_supported
+        return prm_scopes.join(' ') if prm_scopes && !prm_scopes.empty?
+
+        nil
+      end
+
       # Normalize server URL to canonical form
       # @param url [String] Server URL
       # @return [String] Normalized URL
@@ -298,9 +423,18 @@ module MCPClient
       # @return [ServerMetadata] Authorization server metadata
       # @raise [MCPClient::Errors::ConnectionError] if discovery fails
       def discover_authorization_server
+        # A challenge we refused is still authoritative: it says the cached
+        # authorization server is no longer the right one. Falling back to
+        # that cache (or to speculative well-known probing) would quietly
+        # undo the rejection, so surface it instead.
+        raise MCPClient::Errors::ConnectionError, @challenge_error if @challenge_error
+
         # A fresh 401 challenge is authoritative and overrides any cached
-        # (possibly stale or direct-discovered) authorization server metadata.
-        cached = storage.get_server_metadata(server_url) unless @challenge_resource_metadata
+        # (possibly stale or direct-discovered) authorization server metadata —
+        # whether the challenge-advertised PRM was already fetched or only its
+        # URL is pending (e.g. the initial fetch failed and must be retried).
+        challenge_pending = @challenge_resource_metadata || @challenge_metadata_url
+        cached = storage.get_server_metadata(server_url) unless challenge_pending
         if cached
           # Validate the cached entry before use so a persisted/older cache with
           # an HTTP endpoint or without S256 is still rejected.
@@ -333,6 +467,8 @@ module MCPClient
 
         storage.set_server_metadata(server_url, server_metadata)
         @challenge_resource_metadata = nil # consumed
+        @challenge_metadata_url = nil # consumed
+        @challenge_error = nil
         server_metadata
       end
 
@@ -375,8 +511,7 @@ module MCPClient
         # once PRM IS found it is authoritative: any subsequent failure must be a
         # hard error, never a silent fallback to an authorization server the PRM
         # did not advertise.
-        resource_metadata = @challenge_resource_metadata ||
-                            fetch_first_resource_metadata(protected_resource_metadata_urls(server_url))
+        resource_metadata = challenge_or_well_known_resource_metadata
         return nil unless resource_metadata
 
         validate_resource_matches!(resource_metadata)
@@ -387,6 +522,13 @@ module MCPClient
                 'Protected resource metadata does not advertise any authorization_servers'
         end
 
+        # authorization_servers is untrusted PRM content: validate the
+        # advertised origin BEFORE constructing and fetching well-known URLs
+        # on it, so a malicious protected resource cannot drive discovery GETs
+        # against internal services (SSRF).
+        validate_peer_advertised_url!(auth_server_url,
+                                      'authorization server (advertised by protected resource metadata)')
+
         server_metadata = fetch_first_server_metadata(authorization_server_metadata_urls(auth_server_url))
         unless server_metadata
           raise MCPClient::Errors::ConnectionError,
@@ -397,6 +539,25 @@ module MCPClient
         server_metadata
       end
 
+      # Resolve the Protected Resource Metadata for discovery.
+      #
+      # MCP 2025-11-25 MUST: use the resource metadata URL from the parsed
+      # WWW-Authenticate headers when present; otherwise fall back to the
+      # well-known URIs. A challenge-advertised URL is therefore authoritative:
+      # it is fetched strictly, and any failure (including a 404) raises rather
+      # than falling through to constructed well-known candidates the challenge
+      # superseded.
+      # @return [ResourceMetadata, nil] metadata, or nil when no PRM exists at
+      #   the speculative well-known URLs (permitting the direct-AS fallback)
+      # @raise [MCPClient::Errors::ConnectionError] if the challenge-advertised
+      #   URL cannot be fetched, or a well-known candidate exists but is invalid
+      def challenge_or_well_known_resource_metadata
+        return @challenge_resource_metadata if @challenge_resource_metadata
+        return fetch_resource_metadata(@challenge_metadata_url, strict: true) if @challenge_metadata_url
+
+        fetch_first_resource_metadata(protected_resource_metadata_urls(server_url))
+      end
+
       # Legacy/self-hosted discovery: treat the MCP server ORIGIN as its own
       # authorization server issuer.
       # @return [ServerMetadata, nil]
@@ -444,17 +605,18 @@ module MCPClient
       end
 
       # Verify the authorization server supports PKCE S256 (RFC 8414 / MCP).
-      # Refuses when S256 is explicitly not offered; warns (and proceeds, since
-      # the client always uses S256) when the field is not advertised at all.
+      # Per MCP 2025-11-25, "If code_challenge_methods_supported is absent,
+      # the authorization server does not support PKCE and MCP clients MUST
+      # refuse to proceed" — absence is a hard stop, not a warning, because
+      # proceeding would defeat the authorization-code downgrade protection.
       # @param server_metadata [ServerMetadata]
-      # @raise [MCPClient::Errors::ConnectionError] if S256 is explicitly unsupported
+      # @raise [MCPClient::Errors::ConnectionError] if PKCE S256 support cannot be verified
       def verify_pkce_support!(server_metadata)
         methods = server_metadata.code_challenge_methods_supported
         if methods.nil?
-          logger.warn(
-            'Authorization server metadata omits code_challenge_methods_supported; ' \
-            'proceeding with PKCE S256'
-          )
+          raise MCPClient::Errors::ConnectionError,
+                'Authorization server metadata omits code_challenge_methods_supported; ' \
+                'the server does not support PKCE and the client must refuse to proceed'
         elsif !methods.include?('S256')
           raise MCPClient::Errors::ConnectionError,
                 'Authorization server does not support PKCE S256 ' \
@@ -473,6 +635,71 @@ module MCPClient
         enforce_https!(server_metadata.registration_endpoint, 'registration endpoint')
       end
 
+      # Validate a URL that a peer advertised to us (a 401 challenge's
+      # resource_metadata, or PRM authorization_servers).
+      #
+      # Stricter than enforce_https!, which exists for URLs the OPERATOR
+      # configured and therefore tolerates plain-HTTP loopback for local
+      # development. Applying that exception to peer-supplied input would
+      # leave the reported SSRF intact against the most sensitive targets of
+      # all — services listening only on localhost. The loopback exception is
+      # honored here only when the configured MCP server is itself loopback,
+      # i.e. the developer is already pointed at a local stack.
+      #
+      # The rejection is recorded so a later discovery fails closed instead of
+      # silently reusing cached authorization-server metadata.
+      #
+      # NOTE: hostnames are checked literally. This does not resolve DNS, so a
+      # public name that resolves to a private address is not caught here;
+      # that needs resolution-time checking in the HTTP layer.
+      # @param url [String] the peer-advertised URL
+      # @param label [String] human-readable name for errors
+      # @raise [MCPClient::Errors::ConnectionError] if the URL is not acceptable
+      def validate_peer_advertised_url!(url, label)
+        uri = URI.parse(url)
+        host = uri.hostname.to_s.downcase
+
+        if uri.scheme != 'https' && !(uri.scheme == 'http' && local_development?)
+          reject_challenge!("OAuth #{label} must use HTTPS: #{url}")
+        end
+        reject_challenge!("OAuth #{label} must not target a loopback or private address: #{url}") if
+          local_address?(host) && !local_development?
+      rescue URI::InvalidURIError
+        reject_challenge!("OAuth #{label} is not a valid URL: #{url}")
+      end
+
+      # @param message [String] why the challenge was refused
+      # @raise [MCPClient::Errors::ConnectionError] always
+      def reject_challenge!(message)
+        # Drop every scrap of the refused challenge so nothing half-applied
+        # survives, and remember why for the next discovery attempt.
+        @challenge_scope = nil
+        @challenge_metadata_url = nil
+        @challenge_resource_metadata = nil
+        @challenge_error = message
+        raise MCPClient::Errors::ConnectionError, message
+      end
+
+      # @return [Boolean] whether the configured MCP server is itself local,
+      #   in which case local discovery targets are expected
+      def local_development?
+        local_address?(URI.parse(server_url).hostname.to_s.downcase)
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # @param host [String] a downcased hostname
+      # @return [Boolean] whether it names a loopback, private or link-local address
+      def local_address?(host)
+        return true if %w[localhost 127.0.0.1 ::1 0.0.0.0].include?(host)
+        return true if host.end_with?('.localhost', '.local', '.internal')
+        return true if host.start_with?('127.', '10.', '192.168.', '169.254.')
+        return true if host.match?(/\A172\.(1[6-9]|2\d|3[01])\./)
+        return true if host.match?(/\A\[?(fc|fd|fe80)/)
+
+        false
+      end
+
       # @param url [String, nil] endpoint URL
       # @param label [String] human-readable endpoint name for errors
       # @raise [MCPClient::Errors::ConnectionError] if the URL is not HTTPS (non-localhost)
@@ -571,7 +798,11 @@ module MCPClient
         end
 
         data = JSON.parse(response.body)
-        ResourceMetadata.from_h(data)
+        metadata = ResourceMetadata.from_h(data)
+        # Retain the most recently fetched PRM so scope resolution can fall
+        # back to its scopes_supported (MCP scope selection priority 2).
+        @resource_metadata = metadata
+        metadata
       rescue JSON::ParserError => e
         raise MCPClient::Errors::ConnectionError, "Invalid resource metadata JSON: #{e.message}"
       rescue Faraday::Error => e
@@ -601,18 +832,28 @@ module MCPClient
         raise MCPClient::Errors::ConnectionError, "Network error fetching server metadata: #{e.message}"
       end
 
-      # Get or register OAuth client
+      # Get or register OAuth client, following the MCP 2025-11-25 client
+      # registration priority order: pre-registered/cached client information
+      # first, then Client ID Metadata Documents (SEP-991) when the
+      # authorization server advertises support and a metadata URL is
+      # configured, then Dynamic Client Registration as a fallback.
       # @param server_metadata [ServerMetadata] Authorization server metadata
       # @return [ClientInfo] Client information
       # @raise [MCPClient::Errors::ConnectionError] if registration fails
       def get_or_register_client(server_metadata)
-        # Try to get existing client info from storage
+        # 1. Pre-registered or previously registered client info from storage
         if (client_info = storage.get_client_info(server_url)) && !client_info.client_secret_expired?
           logger.debug("Using cached OAuth client for #{server_url}")
           return client_info
         end
 
-        # Register new client if server supports it
+        # 2. Client ID Metadata Documents (SEP-991): the HTTPS metadata URL is
+        # itself the client_id — no registration request is needed.
+        if client_id_metadata_url && server_metadata.supports_client_id_metadata_documents?
+          return client_info_from_metadata_url
+        end
+
+        # 3. Dynamic Client Registration (RFC 7591) fallback
         logger.debug('No cached client found, registering new OAuth client...')
         if server_metadata.supports_registration?
           register_client(server_metadata)
@@ -622,6 +863,67 @@ module MCPClient
         end
       end
 
+      # Build client information for a Client ID Metadata Document client
+      # (SEP-991): the configured HTTPS metadata URL is used directly as the
+      # client_id in authorization and token requests, without a dynamic
+      # registration POST. Serving the metadata JSON at that URL is the
+      # application's responsibility, not this library's.
+      # @return [ClientInfo] Client information with the metadata URL as client_id
+      def client_info_from_metadata_url
+        logger.debug("Using Client ID Metadata Document URL as client_id: #{client_id_metadata_url}")
+
+        metadata = ClientMetadata.new(
+          redirect_uris: [redirect_uri],
+          token_endpoint_auth_method: 'none', # Public client
+          grant_types: %w[authorization_code refresh_token],
+          response_types: ['code'],
+          scope: resolved_scope,
+          **@extra_client_metadata
+        )
+
+        client_info = ClientInfo.new(client_id: client_id_metadata_url, metadata: metadata)
+
+        # Persist so complete_authorization_flow and token refresh can find it
+        storage.set_client_info(server_url, client_info)
+
+        client_info
+      end
+
+      # Validate a Client ID Metadata Document URL (SEP-991): "The client_id
+      # URL MUST use the 'https' scheme and contain a path component, e.g.
+      # https://example.com/client.json". Per the Client ID Metadata Document
+      # draft the URL must also have a host and must not contain userinfo,
+      # a fragment, or single-/double-dot path segments.
+      # @param url [String] Candidate metadata URL
+      # @return [String] The validated URL
+      # @raise [ArgumentError] if the URL is invalid, not HTTPS, lacks a host or path
+      #   component, or contains userinfo, a fragment, or dot path segments
+      def validate_client_id_metadata_url(url)
+        uri = URI.parse(url)
+        raise ArgumentError, "client_id_metadata_url must be an HTTPS URL: #{url.inspect}" unless uri.is_a?(URI::HTTPS)
+
+        raise ArgumentError, "client_id_metadata_url must include a host: #{url.inspect}" if uri.host.to_s.empty?
+
+        raise ArgumentError, "client_id_metadata_url must not contain userinfo: #{url.inspect}" if uri.userinfo
+
+        raise ArgumentError, "client_id_metadata_url must not contain a fragment: #{url.inspect}" if uri.fragment
+
+        if uri.path.to_s.empty? || uri.path == '/'
+          raise ArgumentError,
+                'client_id_metadata_url must contain a path component ' \
+                "(e.g. https://example.com/client.json): #{url.inspect}"
+        end
+
+        if uri.path.split('/').intersect?(['.', '..'])
+          raise ArgumentError,
+                "client_id_metadata_url must not contain '.' or '..' path segments: #{url.inspect}"
+        end
+
+        url
+      rescue URI::InvalidURIError
+        raise ArgumentError, "client_id_metadata_url is not a valid URL: #{url.inspect}"
+      end
+
       # Register OAuth client dynamically
       # @param server_metadata [ServerMetadata] Authorization server metadata
       # @return [ClientInfo] Registered client information
@@ -629,8 +931,6 @@ module MCPClient
       def register_client(server_metadata)
         logger.debug("Registering OAuth client at: #{server_metadata.registration_endpoint}")
 
-        resolved_scope = scope == :all ? supported_scopes.join(' ') : scope
-
         metadata = ClientMetadata.new(
           redirect_uris: [redirect_uri],
           token_endpoint_auth_method: 'none', # Public client
@@ -706,8 +1006,6 @@ module MCPClient
         # Use the redirect_uri that was actually registered
         registered_redirect_uri = client_info.metadata.redirect_uris.first
 
-        resolved_scope = scope == :all ? supported_scopes.join(' ') : scope
-
         params = {
           response_type: 'code',
           client_id: client_info.client_id,
@@ -845,7 +1143,7 @@ module MCPClient
         storage.set_token(server_url, new_token)
         new_token
       rescue JSON::ParserError => e
-        logger.warn("Invalid token refresh response: #{e.message}")
+        logger.warn("Invalid token refresh response: #{describe_parse_error(e)}")
         nil
       rescue Faraday::Error => e
         logger.warn("Network error during token refresh: #{e.message}")

data/lib/mcp_client/auth.rb

@@ -100,13 +100,11 @@ module MCPClient
       # @param tos_uri [String, nil] URL of the client terms of service
       # @param policy_uri [String, nil] URL of the client privacy policy
       # @param contacts [Array<String>, nil] List of contact emails for the client
-      # rubocop:disable Metrics/ParameterLists
       def initialize(redirect_uris:, token_endpoint_auth_method: 'none',
                      grant_types: %w[authorization_code refresh_token],
                      response_types: ['code'], scope: nil,
                      client_name: nil, client_uri: nil, logo_uri: nil,
                      tos_uri: nil, policy_uri: nil, contacts: nil)
-        # rubocop:enable Metrics/ParameterLists
         @redirect_uris = redirect_uris
         @token_endpoint_auth_method = token_endpoint_auth_method
         @grant_types = grant_types
@@ -226,7 +224,7 @@ module MCPClient
     class ServerMetadata
       attr_reader :issuer, :authorization_endpoint, :token_endpoint, :registration_endpoint,
                   :scopes_supported, :response_types_supported, :grant_types_supported,
-                  :code_challenge_methods_supported
+                  :code_challenge_methods_supported, :client_id_metadata_document_supported
 
       # @param issuer [String] Issuer identifier URL
       # @param authorization_endpoint [String] Authorization endpoint URL
@@ -236,9 +234,11 @@ module MCPClient
       # @param response_types_supported [Array<String>, nil] Supported response types
       # @param grant_types_supported [Array<String>, nil] Supported grant types
       # @param code_challenge_methods_supported [Array<String>, nil] Supported PKCE code challenge methods (RFC 8414)
+      # @param client_id_metadata_document_supported [Boolean, nil] Whether the server accepts
+      #   Client ID Metadata Document client IDs (MCP 2025-11-25 / SEP-991)
       def initialize(issuer:, authorization_endpoint:, token_endpoint:, registration_endpoint: nil,
                      scopes_supported: nil, response_types_supported: nil, grant_types_supported: nil,
-                     code_challenge_methods_supported: nil)
+                     code_challenge_methods_supported: nil, client_id_metadata_document_supported: nil)
         @issuer = issuer
         @authorization_endpoint = authorization_endpoint
         @token_endpoint = token_endpoint
@@ -247,6 +247,7 @@ module MCPClient
         @response_types_supported = response_types_supported
         @grant_types_supported = grant_types_supported
         @code_challenge_methods_supported = code_challenge_methods_supported
+        @client_id_metadata_document_supported = client_id_metadata_document_supported
       end
 
       # Check if dynamic client registration is supported
@@ -255,6 +256,13 @@ module MCPClient
         !@registration_endpoint.nil?
       end
 
+      # Check if the server accepts clients using Client ID Metadata Documents
+      # (MCP 2025-11-25 / SEP-991), i.e. HTTPS URLs as client identifiers
+      # @return [Boolean] true if client_id_metadata_document_supported is true
+      def supports_client_id_metadata_documents?
+        @client_id_metadata_document_supported == true
+      end
+
       # Convert to hash
       # @return [Hash] Hash representation
       def to_h
@@ -266,7 +274,8 @@ module MCPClient
           scopes_supported: @scopes_supported,
           response_types_supported: @response_types_supported,
           grant_types_supported: @grant_types_supported,
-          code_challenge_methods_supported: @code_challenge_methods_supported
+          code_challenge_methods_supported: @code_challenge_methods_supported,
+          client_id_metadata_document_supported: @client_id_metadata_document_supported
         }.compact
       end
 
@@ -283,20 +292,36 @@ module MCPClient
           response_types_supported: data[:response_types_supported] || data['response_types_supported'],
           grant_types_supported: data[:grant_types_supported] || data['grant_types_supported'],
           code_challenge_methods_supported: data[:code_challenge_methods_supported] ||
-            data['code_challenge_methods_supported']
+            data['code_challenge_methods_supported'],
+          client_id_metadata_document_supported: fetch_boolean(data, :client_id_metadata_document_supported)
         )
       end
+
+      # Fetch a possibly-false value from a hash by symbol or string key.
+      # Unlike the `||` chains above, this preserves an explicit false.
+      # @param data [Hash] Source hash
+      # @param key [Symbol] Key to fetch
+      # @return [Object, nil] The value, or nil when absent under both keys
+      def self.fetch_boolean(data, key)
+        return data[key] if data.key?(key)
+
+        data[key.to_s]
+      end
+      private_class_method :fetch_boolean
     end
 
     # Protected resource metadata for authorization server discovery
     class ResourceMetadata
-      attr_reader :resource, :authorization_servers
+      attr_reader :resource, :authorization_servers, :scopes_supported
 
       # @param resource [String] Resource server identifier
       # @param authorization_servers [Array<String>] List of authorization server URLs
-      def initialize(resource:, authorization_servers:)
+      # @param scopes_supported [Array<String>, nil] Scopes the resource supports (RFC 9728);
+      #   per MCP, the default scope set when a challenge provides none
+      def initialize(resource:, authorization_servers:, scopes_supported: nil)
         @resource = resource
         @authorization_servers = authorization_servers
+        @scopes_supported = scopes_supported
       end
 
       # Convert to hash
@@ -304,8 +329,9 @@ module MCPClient
       def to_h
         {
           resource: @resource,
-          authorization_servers: @authorization_servers
-        }
+          authorization_servers: @authorization_servers,
+          scopes_supported: @scopes_supported
+        }.compact
       end
 
       # Create resource metadata from hash
@@ -314,7 +340,8 @@ module MCPClient
       def self.from_h(data)
         new(
           resource: data[:resource] || data['resource'],
-          authorization_servers: data[:authorization_servers] || data['authorization_servers']
+          authorization_servers: data[:authorization_servers] || data['authorization_servers'],
+          scopes_supported: data[:scopes_supported] || data['scopes_supported']
         )
       end
     end