ruby-mcp-client 1.0.0 → 1.1.0

data/lib/mcp_client/auth/oauth_provider.rb

@@ -14,7 +14,7 @@ module MCPClient
       # @!attribute [rw] redirect_uri
       #   @return [String] OAuth redirect URI
       # @!attribute [rw] scope
-      #   @return [String, nil] OAuth scope
+      #   @return [String, Symbol, nil] OAuth scope (use :all for all server-supported scopes)
       # @!attribute [rw] logger
       #   @return [Logger] Logger instance
       # @!attribute [rw] storage
@@ -27,16 +27,24 @@ module MCPClient
       # Initialize OAuth provider
       # @param server_url [String] The MCP server URL (used as OAuth resource parameter)
       # @param redirect_uri [String] OAuth redirect URI (default: http://localhost:8080/callback)
-      # @param scope [String, nil] OAuth scope
+      # @param scope [String, Symbol, nil] OAuth scope (use :all for all server-supported scopes)
       # @param logger [Logger, nil] Optional logger
       # @param storage [Object, nil] Storage backend for tokens and client info
-      def initialize(server_url:, redirect_uri: 'http://localhost:8080/callback', scope: nil, logger: nil, storage: nil)
+      # @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
+      def initialize(server_url:, redirect_uri: 'http://localhost:8080/callback', scope: nil, logger: nil, storage: nil,
+                     client_metadata: {})
         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
+        @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).
+        @challenge_resource_metadata = nil
       end
 
       # @param url [String] Server URL to normalize
@@ -58,6 +66,14 @@ module MCPClient
         refresh_token(token) if token.refresh_token
       end
 
+      # Return the scopes supported by the authorization server
+      # Discovers server metadata and returns the scopes_supported list.
+      # @return [Array<String>] supported scopes, or empty array if not advertised
+      # @raise [MCPClient::Errors::ConnectionError] if server discovery fails
+      def supported_scopes
+        @supported_scopes ||= discover_authorization_server.scopes_supported || []
+      end
+
       # Start OAuth authorization flow
       # @return [String] Authorization URL to redirect user to
       # @raise [MCPClient::Errors::ConnectionError] if server discovery fails
@@ -130,12 +146,37 @@ 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)
+        url = extract_resource_metadata_url(www_authenticate)
+        return nil unless 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.
+      # @param header [String] the WWW-Authenticate header value
+      # @return [String, nil] the metadata URL if present
+      def extract_resource_metadata_url(header)
+        # Auth-params may include optional whitespace around '=' (RFC 7235).
+        # Quoted form: resource_metadata = "https://..."
+        if (m = header.match(/resource_metadata\s*=\s*"([^"]+)"/))
+          return m[1]
         end
+
+        # Unquoted token form: resource_metadata = https://...
+        if (m = header.match(/resource_metadata\s*=\s*([^,\s]+)/))
+          return m[1]
+        end
+
+        # Legacy fallback: resource="https://..."
+        header.match(/resource\s*=\s*"([^"]+)"/)&.captures&.first
       end
 
       private
@@ -201,6 +242,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)
@@ -208,63 +298,274 @@ 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.
+        cached = storage.get_server_metadata(server_url) unless @challenge_resource_metadata
+        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
+        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_resource_metadata ||
+                            fetch_first_resource_metadata(protected_resource_metadata_urls(server_url))
+        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
+      # 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).
+      # Refuses when S256 is explicitly not offered; warns (and proceeds, since
+      # the client always uses S256) when the field is not advertised at all.
+      # @param server_metadata [ServerMetadata]
+      # @raise [MCPClient::Errors::ConnectionError] if S256 is explicitly unsupported
+      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'
+          )
+        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
@@ -328,12 +629,15 @@ 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
           grant_types: %w[authorization_code refresh_token],
           response_types: ['code'],
-          scope: scope
+          scope: resolved_scope,
+          **@extra_client_metadata
         )
 
         response = @http_client.post(server_metadata.registration_endpoint) do |req|
@@ -355,7 +659,13 @@ module MCPClient
           token_endpoint_auth_method: data['token_endpoint_auth_method'] || 'none',
           grant_types: data['grant_types'] || %w[authorization_code refresh_token],
           response_types: data['response_types'] || ['code'],
-          scope: data['scope']
+          scope: data['scope'],
+          client_name: data['client_name'],
+          client_uri: data['client_uri'],
+          logo_uri: data['logo_uri'],
+          tos_uri: data['tos_uri'],
+          policy_uri: data['policy_uri'],
+          contacts: data['contacts']
         )
 
         # Warn if server changed redirect_uri
@@ -396,11 +706,13 @@ 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,
           redirect_uri: registered_redirect_uri,
-          scope: scope,
+          scope: resolved_scope,
           state: state,
           code_challenge: pkce.code_challenge,
           code_challenge_method: pkce.code_challenge_method,
@@ -589,6 +901,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