ruby-mcp-client 1.0.1 → 2.0.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,15 +46,28 @@ 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). The URL itself is retained
+        # separately so a failed fetch is retried authoritatively by discovery.
+        @challenge_resource_metadata = nil
+        @challenge_metadata_url = nil
       end
 
       # @param url [String] Server URL to normalize
@@ -48,6 +75,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
@@ -142,16 +178,125 @@ module MCPClient
         www_authenticate = response.headers['WWW-Authenticate'] || response.headers['www-authenticate']
         return nil unless www_authenticate
 
-        # Parse WWW-Authenticate header to extract resource metadata URL
-        # Format: Bearer resource="https://example.com/.well-known/oauth-protected-resource"
-        if (match = www_authenticate.match(/resource="([^"]+)"/))
-          resource_metadata_url = match[1]
-          fetch_resource_metadata(resource_metadata_url)
+        # 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.
+        @challenge_scope = bearer_params && extract_challenge_param(bearer_params, 'scope')
+
+        url = extract_resource_metadata_url(www_authenticate)
+        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)
+        # Reuse this challenge-advertised metadata during the subsequent OAuth
+        # flow instead of re-deriving (and possibly missing) the well-known URL.
+        @challenge_resource_metadata = metadata
+        metadata
+      end
+
+      # 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. 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 = params.match(/resource_metadata\s*=\s*"([^"]+)"/))
+          return m[1]
         end
+
+        # Unquoted token form: resource_metadata = https://...
+        if (m = params.match(/resource_metadata\s*=\s*([^,\s]+)/))
+          return m[1]
+        end
+
+        # Legacy fallback: resource="https://..."
+        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
@@ -213,6 +358,55 @@ module MCPClient
           (uri.scheme == 'https' && uri.port == 443)
       end
 
+      # Build the scheme://host[:port] origin for a parsed URI.
+      # @param uri [URI] Parsed URI
+      # @return [String] origin string
+      def origin_of(uri)
+        origin = "#{uri.scheme}://#{uri.host}"
+        origin += ":#{uri.port}" if uri.port && !default_port?(uri)
+        origin
+      end
+
+      # Protected Resource Metadata well-known URLs to try, in priority order
+      # (RFC 9728 §3.1). When the resource identifier has a path, the well-known
+      # segment is inserted between the host and the path; a root-level URL is
+      # always tried as a fallback.
+      # @param server_url [String] the MCP server (protected resource) URL
+      # @return [Array<String>] ordered candidate URLs
+      def protected_resource_metadata_urls(server_url)
+        uri = URI.parse(server_url)
+        origin = origin_of(uri)
+        path = uri.path.to_s
+
+        urls = []
+        urls << "#{origin}/.well-known/oauth-protected-resource#{path}" unless path.empty? || path == '/'
+        urls << "#{origin}/.well-known/oauth-protected-resource"
+        urls.uniq
+      end
+
+      # Authorization Server Metadata well-known URLs to try, in priority order
+      # (RFC 8414 §3.1 path-insertion plus OpenID Connect Discovery). When the
+      # issuer has a path, the well-known segment is INSERTED between host and
+      # path (not appended); the OIDC path-append form is also tried.
+      # @param issuer [String] the authorization server issuer URL
+      # @return [Array<String>] ordered candidate URLs
+      def authorization_server_metadata_urls(issuer)
+        uri = URI.parse(issuer)
+        origin = origin_of(uri)
+        path = uri.path.to_s
+
+        urls = []
+        if path.empty? || path == '/'
+          urls << "#{origin}/.well-known/oauth-authorization-server"
+          urls << "#{origin}/.well-known/openid-configuration"
+        else
+          urls << "#{origin}/.well-known/oauth-authorization-server#{path}"
+          urls << "#{origin}/.well-known/openid-configuration#{path}"
+          urls << "#{origin}#{path}/.well-known/openid-configuration"
+        end
+        urls.uniq
+      end
+
       # Discover authorization server metadata
       # Tries multiple discovery patterns:
       # 1. oauth-authorization-server (MCP spec pattern - server is its own auth server)
@@ -220,69 +414,307 @@ module MCPClient
       # @return [ServerMetadata] Authorization server metadata
       # @raise [MCPClient::Errors::ConnectionError] if discovery fails
       def discover_authorization_server
-        # Try to get from storage first
-        if (cached = storage.get_server_metadata(server_url))
+        # A fresh 401 challenge is authoritative and overrides any cached
+        # (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.
+          validate_server_metadata!(cached)
           return cached
         end
 
-        server_metadata = nil
+        discover_and_cache_authorization_server
+      end
 
-        # Primary discovery: oauth-authorization-server (MCP spec pattern)
-        # Used by servers that are both resource and authorization server
-        begin
-          discovery_url = build_discovery_url(server_url, :authorization_server)
-          logger.debug("Attempting OAuth discovery: #{discovery_url}")
-          server_metadata = fetch_server_metadata(discovery_url)
-        rescue MCPClient::Errors::ConnectionError => e
-          logger.debug("oauth-authorization-server discovery failed: #{e.message}")
-        end
+      # Discover authorization server metadata, validate it, and cache it.
+      # @return [ServerMetadata]
+      # @raise [MCPClient::Errors::ConnectionError] if discovery or validation fails
+      def discover_and_cache_authorization_server
+        previous = storage.get_server_metadata(server_url)
 
-        # Fallback discovery: oauth-protected-resource (delegation pattern)
-        # Used by resource servers that delegate to external authorization servers
-        unless server_metadata
-          begin
-            discovery_url = build_discovery_url(server_url, :protected_resource)
-            logger.debug("Attempting OAuth discovery: #{discovery_url}")
-
-            resource_metadata = fetch_resource_metadata(discovery_url)
-            auth_server_url = resource_metadata.authorization_servers.first
-
-            if auth_server_url
-              server_metadata = fetch_server_metadata("#{auth_server_url}/.well-known/oauth-authorization-server")
-            end
-          rescue MCPClient::Errors::ConnectionError => e
-            logger.debug("oauth-protected-resource discovery failed: #{e.message}")
-          end
-        end
+        # RFC 9728: Protected Resource Metadata is authoritative — try it first,
+        # then fall back to treating the MCP server origin as its own AS.
+        server_metadata = discover_via_protected_resource || discover_via_direct_authorization_server
 
         unless server_metadata
           raise MCPClient::Errors::ConnectionError,
-                'OAuth discovery failed: no valid endpoints found'
+                'OAuth discovery failed: no valid authorization server metadata found'
         end
 
-        # Cache the metadata
+        # Validate BEFORE caching so invalid metadata is never persisted.
+        validate_server_metadata!(server_metadata)
+
+        invalidate_client_info_on_as_change(previous, server_metadata)
+
         storage.set_server_metadata(server_url, server_metadata)
+        @challenge_resource_metadata = nil # consumed
+        @challenge_metadata_url = nil # consumed
+        server_metadata
+      end
+
+      # When a 401 challenge changes the authorization server, per-AS state cached
+      # under this server_url becomes invalid: a client_id registered with the
+      # previous AS would fail as invalid_client, and memoized scopes belong to
+      # the old AS. Discard both so the new flow re-registers and re-discovers.
+      # @param previous [ServerMetadata, nil] previously cached AS metadata
+      # @param current [ServerMetadata] newly discovered AS metadata
+      def invalidate_client_info_on_as_change(previous, current)
+        return unless previous && previous.issuer != current.issuer
+
+        logger.debug('Authorization server changed; discarding client and scopes from the previous AS')
+
+        # Prefer an explicit delete; fall back to the always-available
+        # set_client_info(nil) so custom storage backends are handled too.
+        if storage.respond_to?(:delete_client_info)
+          storage.delete_client_info(server_url)
+        else
+          storage.set_client_info(server_url, nil)
+        end
+
+        @supported_scopes = nil
+      end
+
+      # Apply the PKCE-support and HTTPS-endpoint checks to server metadata.
+      # @param server_metadata [ServerMetadata]
+      # @raise [MCPClient::Errors::ConnectionError] if a check fails
+      def validate_server_metadata!(server_metadata)
+        verify_pkce_support!(server_metadata)
+        enforce_https_endpoints!(server_metadata)
+      end
+
+      # PRM-first discovery: fetch Protected Resource Metadata and then the
+      # authorization server it advertises.
+      # @return [ServerMetadata, nil] AS metadata, or nil if no PRM document exists
+      # @raise [MCPClient::Errors::ConnectionError] if PRM is malformed or mismatched
+      def discover_via_protected_resource
+        # A missing PRM document (return nil) permits the direct-AS fallback. But
+        # 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_or_well_known_resource_metadata
+        return nil unless resource_metadata
+
+        validate_resource_matches!(resource_metadata)
+
+        auth_server_url = Array(resource_metadata.authorization_servers).first
+        unless auth_server_url
+          raise MCPClient::Errors::ConnectionError,
+                'Protected resource metadata does not advertise any authorization_servers'
+        end
+
+        server_metadata = fetch_first_server_metadata(authorization_server_metadata_urls(auth_server_url))
+        unless server_metadata
+          raise MCPClient::Errors::ConnectionError,
+                "Authorization server advertised by protected resource metadata (#{auth_server_url}) " \
+                'could not be discovered'
+        end
 
         server_metadata
       end
 
-      # Fetch resource metadata from URL
+      # 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]
+      def discover_via_direct_authorization_server
+        origin = origin_of(URI.parse(server_url))
+        fetch_first_server_metadata(authorization_server_metadata_urls(origin))
+      end
+
+      # Fetch the first Protected Resource Metadata document that resolves.
+      #
+      # PRM is authoritative: a candidate that genuinely does not exist (HTTP
+      # 404) is skipped so the next candidate is tried, but a candidate that
+      # exists yet is malformed or errors (bad JSON, 5xx, network failure) is a
+      # HARD failure — it must not silently fall through to a root PRM or the
+      # direct-AS path, which could point at a different authorization server.
+      # @param urls [Array<String>] candidate URLs
+      # @return [ResourceMetadata, nil]
+      def fetch_first_resource_metadata(urls)
+        urls.each do |url|
+          md = fetch_resource_metadata(url) # returns nil only for a 404 (absent); raises otherwise
+          return md if md
+        end
+        nil
+      end
+
+      # Fetch the first Authorization Server Metadata document that resolves.
+      # The oauth-authorization-server and openid-configuration forms are
+      # genuine alternatives, so any failing candidate is skipped to try the next.
+      # @param urls [Array<String>] candidate URLs
+      # @return [ServerMetadata, nil]
+      def fetch_first_server_metadata(urls)
+        urls.each do |url|
+          md = try_fetch_server_metadata(url)
+          return md if md
+        end
+        nil
+      end
+
+      # Non-raising server-metadata fetch used while iterating candidates.
+      def try_fetch_server_metadata(url)
+        fetch_server_metadata(url)
+      rescue MCPClient::Errors::ConnectionError => e
+        logger.debug("Authorization server metadata candidate failed (#{url}): #{e.message}")
+        nil
+      end
+
+      # Verify the authorization server supports PKCE S256 (RFC 8414 / MCP).
+      # 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 PKCE S256 support cannot be verified
+      def verify_pkce_support!(server_metadata)
+        methods = server_metadata.code_challenge_methods_supported
+        if methods.nil?
+          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 ' \
+                '(code_challenge_methods_supported does not include "S256")'
+        end
+      end
+
+      # Require HTTPS for all discovered authorization server endpoints, with a
+      # localhost exception for local development.
+      # @param server_metadata [ServerMetadata]
+      def enforce_https_endpoints!(server_metadata)
+        enforce_https!(server_metadata.authorization_endpoint, 'authorization endpoint')
+        enforce_https!(server_metadata.token_endpoint, 'token endpoint')
+        return unless server_metadata.registration_endpoint
+
+        enforce_https!(server_metadata.registration_endpoint, 'registration endpoint')
+      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)
+      def enforce_https!(url, label)
+        return if url.nil?
+
+        uri = URI.parse(url)
+        return if uri.scheme == 'https'
+        # Dev exception is only for plain HTTP on a loopback host — not any other
+        # scheme (e.g. ftp://localhost). Use #hostname (not #host) so an IPv6
+        # loopback like http://[::1]:9292 matches without the surrounding brackets.
+        return if uri.scheme == 'http' && %w[localhost 127.0.0.1 ::1].include?(uri.hostname)
+
+        raise MCPClient::Errors::ConnectionError, "OAuth #{label} must use HTTPS: #{url}"
+      rescue URI::InvalidURIError
+        raise MCPClient::Errors::ConnectionError, "OAuth #{label} is not a valid URL: #{url}"
+      end
+
+      # Validate the PRM `resource` identifies this server (RFC 9728 confused
+      # deputy protection). Path/canonicalization differences on the same host
+      # are tolerated; a different host is rejected.
+      # @param resource_metadata [ResourceMetadata]
+      # @raise [MCPClient::Errors::ConnectionError] on host mismatch
+      def validate_resource_matches!(resource_metadata)
+        # RFC 9728 requires `resource`; without it the confused-deputy check is
+        # impossible, so a PRM that omits it must be rejected (not trusted).
+        if resource_metadata.resource.nil?
+          raise MCPClient::Errors::ConnectionError,
+                'Protected resource metadata is missing the required "resource" identifier'
+        end
+
+        # Require an EXACT canonical match (scheme/host/port/path). A same-host
+        # match is not enough: a host that serves multiple resources/tenants
+        # must not have one tenant's PRM trusted for another.
+        advertised = resource_identity(resource_metadata.resource)
+        expected = resource_identity(server_url)
+        return if advertised == expected
+
+        raise MCPClient::Errors::ConnectionError,
+              "Protected resource metadata resource (#{resource_metadata.resource}) " \
+              "does not match the server URL (#{server_url})"
+      end
+
+      # Canonical resource identity (scheme, host, port, path, query) used for
+      # the confused-deputy comparison. The query is included because the
+      # `resource` parameter sent in the authorization and token requests is the
+      # full server URL (some servers distinguish resources by query, e.g.
+      # ?serverId=a vs ?serverId=b); only the fragment is ignored. Rejects a
+      # non-absolute URL, since the value is untrusted server input.
+      # @param url [String] a resource URL
+      # @return [String] canonical identity string
+      # @raise [MCPClient::Errors::ConnectionError] if the URL is not an absolute URI
+      def resource_identity(url)
+        uri = URI.parse(url)
+        unless uri.scheme && uri.host
+          raise MCPClient::Errors::ConnectionError, "Invalid resource URL (must be absolute): #{url}"
+        end
+
+        scheme = uri.scheme.downcase
+        host = uri.host.downcase
+        port = uri.port
+        port = nil if (scheme == 'http' && port == 80) || (scheme == 'https' && port == 443)
+        path = uri.path.to_s
+        path = '' if path == '/'
+        path = path.chomp('/') while path.end_with?('/')
+        query = uri.query ? "?#{uri.query}" : ''
+
+        "#{scheme}://#{host}#{":#{port}" if port}#{path}#{query}"
+      rescue URI::InvalidURIError
+        raise MCPClient::Errors::ConnectionError, "Invalid resource URL: #{url}"
+      end
+
+      # Fetch resource metadata from URL.
+      #
+      # Returns nil when the document is genuinely absent (HTTP 404) so a
+      # discovery loop can try the next candidate. Any other failure — a
+      # non-404 error status, malformed JSON, or a network error — raises,
+      # because PRM is authoritative and such a response must not be silently
+      # skipped in favor of a different authorization server.
       # @param url [String] Resource metadata URL
-      # @return [ResourceMetadata] Resource metadata
-      # @raise [MCPClient::Errors::ConnectionError] if fetch fails
-      def fetch_resource_metadata(url)
+      # @param strict [Boolean] when true, a 404 raises instead of returning nil
+      #   (used for a URL explicitly advertised by a 401 challenge)
+      # @return [ResourceMetadata, nil] metadata, or nil if a speculative URL returns 404
+      # @raise [MCPClient::Errors::ConnectionError] on any non-404 failure, or on 404 when strict
+      def fetch_resource_metadata(url, strict: false)
         logger.debug("Fetching resource metadata from: #{url}")
 
         response = @http_client.get(url) do |req|
           req.headers['Accept'] = 'application/json'
         end
 
+        return nil if response.status == 404 && !strict
+
         unless response.success?
           raise MCPClient::Errors::ConnectionError, "Failed to fetch resource metadata: HTTP #{response.status}"
         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
@@ -312,18 +744,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)
@@ -333,6 +775,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
@@ -340,8 +843,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
@@ -417,8 +918,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,
@@ -612,6 +1111,10 @@ module MCPClient
           @client_infos[server_url] = client_info
         end
 
+        def delete_client_info(server_url)
+          @client_infos.delete(server_url)
+        end
+
         def get_server_metadata(server_url)
           @server_metadata[server_url]
         end