Merge pull request #97 from patvice/oauth-challenge-handling

OAuth challenge handling with automatic retry

Author: patvice

lib/ruby_llm/mcp/adapters/mcp_transports/sse.rb

@@ -12,10 +12,12 @@ def initialize(url:, headers: {}, version: :http2, request_timeout: 10_000)
 
       @native_transport = RubyLLM::MCP::Native::Transports::SSE.new(
         url: url,
-        headers: headers,
-        version: version,
         coordinator: @coordinator,
-        request_timeout: request_timeout
+        request_timeout: request_timeout,
+        options: {
+          headers: headers,
+          version: version
+        }
       )
     end
 

lib/ruby_llm/mcp/auth/browser_oauth_provider.rb

@@ -155,6 +155,38 @@ def complete_authorization_flow(code, state)
           @oauth_provider.complete_authorization_flow(code, state)
         end
 
+        # Handle authentication challenge with browser-based auth
+        # @param www_authenticate [String, nil] WWW-Authenticate header value
+        # @param resource_metadata_url [String, nil] Resource metadata URL from response
+        # @param requested_scope [String, nil] Scope from WWW-Authenticate challenge
+        # @return [Boolean] true if authentication was completed successfully
+        def handle_authentication_challenge(www_authenticate: nil, resource_metadata_url: nil, requested_scope: nil)
+          @logger.debug("BrowserOAuthProvider handling authentication challenge")
+
+          # Try standard provider's automatic handling first (token refresh, client credentials)
+          begin
+            return @oauth_provider.handle_authentication_challenge(
+              www_authenticate: www_authenticate,
+              resource_metadata_url: resource_metadata_url,
+              requested_scope: requested_scope
+            )
+          rescue Errors::AuthenticationRequiredError
+            # Standard provider couldn't handle it - need interactive auth
+            @logger.info("Automatic authentication failed, starting browser-based OAuth flow")
+          end
+
+          # Perform full browser-based authentication
+          authenticate(auto_open_browser: true)
+          true
+        end
+
+        # Parse WWW-Authenticate header (delegate to oauth_provider)
+        # @param header [String] WWW-Authenticate header value
+        # @return [Hash] parsed challenge information
+        def parse_www_authenticate(header)
+          @oauth_provider.parse_www_authenticate(header)
+        end
+
         private
 
         # Validate and synchronize redirect_uri between this provider and oauth_provider

lib/ruby_llm/mcp/auth/memory_storage.rb

@@ -12,6 +12,7 @@ def initialize
           @server_metadata = {}
           @pkce_data = {}
           @state_data = {}
+          @resource_metadata = {}
         end
 
         # Token storage
@@ -23,6 +24,10 @@ def set_token(server_url, token)
           @tokens[server_url] = token
         end
 
+        def delete_token(server_url)
+          @tokens.delete(server_url)
+        end
+
         # Client registration storage
         def get_client_info(server_url)
           @client_infos[server_url]
@@ -66,6 +71,19 @@ def set_state(server_url, state)
         def delete_state(server_url)
           @state_data.delete(server_url)
         end
+
+        # Resource metadata management
+        def get_resource_metadata(server_url)
+          @resource_metadata[server_url]
+        end
+
+        def set_resource_metadata(server_url, metadata)
+          @resource_metadata[server_url] = metadata
+        end
+
+        def delete_resource_metadata(server_url)
+          @resource_metadata.delete(server_url)
+        end
       end
     end
   end

lib/ruby_llm/mcp/auth/oauth_provider.rb

@@ -150,6 +150,88 @@ def apply_authorization(request)
           request.headers["Authorization"] = token.to_header
         end
 
+        # Handle authentication challenge from server (401 response)
+        # Attempts to refresh token or raises error if interactive auth required
+        # @param www_authenticate [String, nil] WWW-Authenticate header value
+        # @param resource_metadata_url [String, nil] Resource metadata URL from response
+        # @param requested_scope [String, nil] Scope from WWW-Authenticate challenge
+        # @return [Boolean] true if authentication was refreshed successfully
+        # @raise [Errors::AuthenticationRequiredError] if interactive auth is required
+        def handle_authentication_challenge(www_authenticate: nil, resource_metadata_url: nil, requested_scope: nil)
+          logger.debug("Handling authentication challenge")
+          logger.debug("  WWW-Authenticate: #{www_authenticate}") if www_authenticate
+          logger.debug("  Resource metadata URL: #{resource_metadata_url}") if resource_metadata_url
+          logger.debug("  Requested scope: #{requested_scope}") if requested_scope
+
+          # Parse WWW-Authenticate header if provided
+          final_requested_scope = requested_scope
+          if www_authenticate
+            challenge_info = parse_www_authenticate(www_authenticate)
+            final_requested_scope ||= challenge_info[:scope]
+            # NOTE: resource_metadata_url from challenge_info could be used for future discovery
+          end
+
+          # Update scope if server requested different scope
+          if final_requested_scope && final_requested_scope != scope
+            logger.debug("Updating scope from '#{scope}' to '#{final_requested_scope}'")
+            self.scope = final_requested_scope
+          end
+
+          # Try to refresh existing token
+          token = storage.get_token(server_url)
+          if token&.refresh_token
+            logger.debug("Attempting token refresh with existing refresh token")
+            refreshed_token = refresh_token(token)
+            return true if refreshed_token
+          end
+
+          # If we have client credentials, try that flow
+          if grant_type == :client_credentials
+            logger.debug("Attempting client credentials flow")
+            begin
+              new_token = client_credentials_flow(scope: requested_scope)
+              return true if new_token
+            rescue StandardError => e
+              logger.warn("Client credentials flow failed: #{e.message}")
+            end
+          end
+
+          # Cannot automatically authenticate - interactive auth required
+          logger.warn("Cannot automatically authenticate - interactive authorization required")
+          raise Errors::AuthenticationRequiredError.new(
+            message: "OAuth authentication required. Token refresh failed and interactive authorization is needed."
+          )
+        end
+
+        # Parse WWW-Authenticate header to extract challenge parameters
+        # @param header [String] WWW-Authenticate header value
+        # @return [Hash] parsed challenge information
+        def parse_www_authenticate(header)
+          result = {}
+
+          # Example: Bearer realm="example", scope="mcp:read mcp:write", resource_metadata_url="https://..."
+          if header =~ /Bearer\s+(.+)/i
+            params = ::Regexp.last_match(1)
+
+            # Extract scope
+            if params =~ /scope="([^"]+)"/
+              result[:scope] = ::Regexp.last_match(1)
+            end
+
+            # Extract resource metadata URL
+            if params =~ /resource_metadata_url="([^"]+)"/
+              result[:resource_metadata_url] = ::Regexp.last_match(1)
+            end
+
+            # Extract realm
+            if params =~ /realm="([^"]+)"/
+              result[:realm] = ::Regexp.last_match(1)
+            end
+          end
+
+          result
+        end
+
         private
 
         # Create HTTP client for OAuth requests

lib/ruby_llm/mcp/native/transport.rb

@@ -58,9 +58,23 @@ def build_transport
             transport_config.merge!(options)
           end
 
+          # Handle SSE transport specially - it uses options hash pattern
+          if transport_type == :sse
+            url = transport_config.delete(:url) || transport_config.delete("url")
+            request_timeout = transport_config.delete(:request_timeout) ||
+                              transport_config.delete("request_timeout") ||
+                              MCP.config.request_timeout
+            # Everything else goes into options
+            options_hash = transport_config.dup
+            transport_config.clear
+            transport_config[:url] = url
+            transport_config[:request_timeout] = request_timeout
+            transport_config[:options] = options_hash
+          end
+
           # Remove OAuth-specific params from transports that don't support them
           # This allows other arbitrary params (like timeout) to pass through for testing
-          unless %i[streamable streamable_http].include?(transport_type)
+          unless %i[streamable streamable_http sse].include?(transport_type)
             transport_config.delete(:oauth_provider)
             transport_config.delete(:oauth)
           end