ruby_llm_swarm-mcp 0.8.0

data/lib/ruby_llm/mcp/auth/flows/client_credentials_flow.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      module Flows
+        # Orchestrates OAuth 2.1 Client Credentials flow
+        # Used for application authentication without user interaction
+        class ClientCredentialsFlow
+          attr_reader :discoverer, :client_registrar, :token_manager, :storage, :logger
+
+          def initialize(discoverer:, client_registrar:, token_manager:, storage:, logger:)
+            @discoverer = discoverer
+            @client_registrar = client_registrar
+            @token_manager = token_manager
+            @storage = storage
+            @logger = logger
+          end
+
+          # Perform client credentials flow
+          # @param server_url [String] MCP server URL
+          # @param redirect_uri [String] redirect URI (used for registration only)
+          # @param scope [String, nil] requested scope
+          # @return [Token] access token
+          def execute(server_url, redirect_uri, scope)
+            logger.debug("Starting OAuth client credentials flow")
+
+            # 1. Discover authorization server
+            server_metadata = discoverer.discover(server_url)
+            raise Errors::TransportError.new(message: "OAuth server discovery failed") unless server_metadata
+
+            # 2. Register client (or get cached client) with client credentials grant
+            client_info = client_registrar.get_or_register(
+              server_url,
+              server_metadata,
+              :client_credentials,
+              redirect_uri,
+              scope
+            )
+
+            # 3. Validate that we have a client secret
+            unless client_info.client_secret
+              raise Errors::TransportError.new(
+                message: "Client credentials flow requires client_secret"
+              )
+            end
+
+            # 4. Exchange client credentials for token
+            token = token_manager.exchange_client_credentials(
+              server_metadata,
+              client_info,
+              scope,
+              server_url
+            )
+
+            # 5. Store token
+            storage.set_token(server_url, token)
+
+            logger.info("Client credentials authentication completed successfully")
+            token
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/grant_strategies/authorization_code.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      module GrantStrategies
+        # Authorization Code grant strategy
+        # Used for user authorization with PKCE (OAuth 2.1)
+        class AuthorizationCode < Base
+          # Public clients don't use client_secret
+          # @return [String] "none"
+          def auth_method
+            "none"
+          end
+
+          # Authorization code and refresh token grants
+          # @return [Array<String>] grant types
+          def grant_types_list
+            %w[authorization_code refresh_token]
+          end
+
+          # Only "code" response type for authorization code flow
+          # @return [Array<String>] response types
+          def response_types_list
+            ["code"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/grant_strategies/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      module GrantStrategies
+        # Base strategy for OAuth grant types
+        # Defines interface for grant-specific configuration
+        class Base
+          # Get token endpoint authentication method
+          # @return [String] auth method (e.g., "none", "client_secret_post")
+          def auth_method
+            raise NotImplementedError, "#{self.class} must implement #auth_method"
+          end
+
+          # Get list of grant types to request during registration
+          # @return [Array<String>] grant types
+          def grant_types_list
+            raise NotImplementedError, "#{self.class} must implement #grant_types_list"
+          end
+
+          # Get list of response types to request during registration
+          # @return [Array<String>] response types
+          def response_types_list
+            raise NotImplementedError, "#{self.class} must implement #response_types_list"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/grant_strategies/client_credentials.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      module GrantStrategies
+        # Client Credentials grant strategy
+        # Used for application authentication without user interaction
+        class ClientCredentials < Base
+          # Client credentials require client_secret
+          # @return [String] "client_secret_post"
+          def auth_method
+            "client_secret_post"
+          end
+
+          # Client credentials and refresh token grants
+          # @return [Array<String>] grant types
+          def grant_types_list
+            %w[client_credentials refresh_token]
+          end
+
+          # No response types for client credentials flow (no redirect)
+          # @return [Array<String>] response types (empty)
+          def response_types_list
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/http_response_handler.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      # Utility class for handling HTTP responses in OAuth flows
+      # Consolidates error handling and response parsing
+      class HttpResponseHandler
+        # Handle and parse a successful HTTP response
+        # @param response [HTTPX::Response, HTTPX::ErrorResponse] HTTP response
+        # @param context [String] description for error messages (e.g., "Token exchange")
+        # @param expected_status [Integer, Array<Integer>] expected status code(s)
+        # @return [Hash] parsed JSON response
+        # @raise [Errors::TransportError] if response is an error or unexpected status
+        def self.handle_response(response, context:, expected_status: 200)
+          expected_statuses = Array(expected_status)
+
+          # Handle HTTPX ErrorResponse (connection failures, timeouts, etc.)
+          if response.is_a?(HTTPX::ErrorResponse)
+            error_message = response.error&.message || "Request failed"
+            raise Errors::TransportError.new(
+              message: "#{context} failed: #{error_message}"
+            )
+          end
+
+          unless expected_statuses.include?(response.status)
+            raise Errors::TransportError.new(
+              message: "#{context} failed: HTTP #{response.status}",
+              code: response.status
+            )
+          end
+
+          JSON.parse(response.body.to_s)
+        end
+
+        # Extract redirect URI mismatch details from error response
+        # @param body [String] error response body
+        # @return [Hash, nil] mismatch details or nil
+        def self.extract_redirect_mismatch(body)
+          data = JSON.parse(body)
+          error = data["error"] || data[:error]
+          return nil unless error == "unauthorized_client"
+
+          description = data["error_description"] || data[:error_description]
+          return nil unless description.is_a?(String)
+
+          # Parse common OAuth error message format
+          # Matches: "You sent <url> and we expected <url>"
+          match = description.match(%r{You sent\s+(https?://[^\s,]+)[\s,]+and we expected\s+(https?://\S+?)\.?\s*$}i)
+          return nil unless match
+
+          {
+            sent: match[1],
+            expected: match[2],
+            description: description
+          }
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/memory_storage.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      # In-memory storage for OAuth data
+      # Stores tokens, client registrations, server metadata, and temporary session data
+      class MemoryStorage
+        def initialize
+          @tokens = {}
+          @client_infos = {}
+          @server_metadata = {}
+          @pkce_data = {}
+          @state_data = {}
+          @resource_metadata = {}
+        end
+
+        # Token storage
+        def get_token(server_url)
+          @tokens[server_url]
+        end
+
+        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]
+        end
+
+        def set_client_info(server_url, client_info)
+          @client_infos[server_url] = client_info
+        end
+
+        # Server metadata caching
+        def get_server_metadata(server_url)
+          @server_metadata[server_url]
+        end
+
+        def set_server_metadata(server_url, metadata)
+          @server_metadata[server_url] = metadata
+        end
+
+        # PKCE state management (temporary)
+        def get_pkce(server_url)
+          @pkce_data[server_url]
+        end
+
+        def set_pkce(server_url, pkce)
+          @pkce_data[server_url] = pkce
+        end
+
+        def delete_pkce(server_url)
+          @pkce_data.delete(server_url)
+        end
+
+        # State parameter management (temporary)
+        def get_state(server_url)
+          @state_data[server_url]
+        end
+
+        def set_state(server_url, state)
+          @state_data[server_url] = state
+        end
+
+        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
+end

data/lib/ruby_llm/mcp/auth/oauth_provider.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      # Core OAuth 2.1 provider implementing complete authorization flow
+      # Supports RFC 7636 (PKCE), RFC 7591 (Dynamic Registration),
+      # RFC 8414 (Server Metadata), RFC 8707 (Resource Indicators), RFC 9728 (Protected Resource Metadata)
+      #
+      # @note This class is not thread-safe. Each thread should use its own instance.
+      class OAuthProvider
+        attr_reader :server_url
+        attr_accessor :redirect_uri, :scope, :logger, :storage, :grant_type
+
+        # Normalize server URL for consistent comparison
+        # @param url [String] raw URL
+        # @return [String] normalized URL
+        def self.normalize_url(url)
+          uri = URI.parse(url)
+
+          uri.scheme = uri.scheme&.downcase
+          uri.host = uri.host&.downcase
+
+          if (uri.scheme == "http" && uri.port == 80) || (uri.scheme == "https" && uri.port == 443)
+            uri.port = nil
+          end
+
+          if uri.path.nil? || uri.path.empty? || uri.path == "/"
+            uri.path = ""
+          elsif uri.path.end_with?("/")
+            uri.path = uri.path.chomp("/")
+          end
+
+          uri.fragment = nil
+          uri.to_s
+        end
+
+        def initialize(server_url:, redirect_uri: "http://localhost:8080/callback", scope: nil, logger: nil, # rubocop:disable Metrics/ParameterLists
+                       storage: nil, grant_type: :authorization_code)
+          self.server_url = server_url
+          self.redirect_uri = redirect_uri
+          self.scope = scope
+          self.logger = logger || MCP.logger
+          self.storage = storage || MemoryStorage.new
+          self.grant_type = grant_type.to_sym
+          validate_redirect_uri!(redirect_uri)
+
+          # Initialize HTTP client
+          @http_client = create_http_client
+
+          # Initialize service objects
+          @discoverer = Discoverer.new(@http_client, self.storage, self.logger)
+          @client_registrar = ClientRegistrar.new(@http_client, self.storage, self.logger, MCP.config)
+          @token_manager = TokenManager.new(@http_client, self.logger)
+          @session_manager = SessionManager.new(self.storage)
+
+          # Initialize flow orchestrators
+          @auth_code_flow = Flows::AuthorizationCodeFlow.new(
+            discoverer: @discoverer,
+            client_registrar: @client_registrar,
+            session_manager: @session_manager,
+            token_manager: @token_manager,
+            storage: self.storage,
+            logger: self.logger
+          )
+          @client_creds_flow = Flows::ClientCredentialsFlow.new(
+            discoverer: @discoverer,
+            client_registrar: @client_registrar,
+            token_manager: @token_manager,
+            storage: self.storage,
+            logger: self.logger
+          )
+        end
+
+        # Get current access token, refreshing if needed
+        # @return [Token, nil] valid access token or nil
+        def access_token
+          logger.debug("OAuth access_token: Looking up token for server_url='#{server_url}'")
+          token = storage.get_token(server_url)
+          logger.debug("OAuth access_token: Storage returned token=#{token ? 'present' : 'nil'}")
+
+          if token
+            logger.debug("  Token expires_at: #{token.expires_at}")
+            logger.debug("  Token expired?: #{token.expired?}")
+            logger.debug("  Token expires_soon?: #{token.expires_soon?}")
+          else
+            logger.warn("✗ No token found in storage for server_url='#{server_url}'")
+            logger.warn("  Check that authentication completed and stored the token")
+            return nil
+          end
+
+          # Return token if still valid
+          return token unless token.expired? || token.expires_soon?
+
+          # Try to refresh if we have a refresh token
+          logger.debug("Token expired or expiring soon, attempting refresh...")
+          refresh_token(token) if token.refresh_token
+        end
+
+        # Authenticate and return current access token
+        # This is a convenience method for consistency with BrowserOAuthProvider
+        # For standard OAuth flow, external authorization is required before calling this
+        # @return [Token] current valid access token
+        # @raise [Errors::TransportError] if not authenticated or token unavailable
+        def authenticate
+          token = access_token
+          unless token
+            raise Errors::TransportError.new(
+              message: "Not authenticated. Please complete OAuth authorization flow first. " \
+                       "For standard OAuth, you must authorize externally and exchange the code."
+            )
+          end
+          token
+        end
+
+        # Start OAuth authorization flow (authorization code grant)
+        # @return [String] authorization URL for user to visit
+        def start_authorization_flow
+          @auth_code_flow.start(
+            server_url,
+            redirect_uri,
+            scope,
+            https_validator: method(:validate_https_endpoint)
+          )
+        end
+
+        # Perform client credentials flow (application authentication without user)
+        # @param scope [String] optional scope override
+        # @return [Token] access token
+        def client_credentials_flow(scope: nil)
+          @client_creds_flow.execute(server_url, redirect_uri, scope || self.scope)
+        end
+
+        # Complete OAuth authorization flow after callback
+        # @param code [String] authorization code from callback
+        # @param state [String] state parameter from callback
+        # @return [Token] access token
+        def complete_authorization_flow(code, state)
+          @auth_code_flow.complete(server_url, code, state)
+        end
+
+        # Apply authorization header to HTTP request
+        # @param request [HTTPX::Request] HTTP request object
+        def apply_authorization(request)
+          token = access_token
+          logger.debug("OAuth apply_authorization: token=#{token ? 'present' : 'nil'}")
+          return unless token
+
+          logger.debug("OAuth applying authorization header: #{token.to_header[0..20]}...")
+          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
+        # @return [HTTPX::Session] HTTP client
+        def create_http_client
+          headers = {
+            "Accept" => "application/json",
+            "User-Agent" => "RubyLLM-MCP/#{RubyLLM::MCP::VERSION}"
+          }
+          headers["MCP-Protocol-Version"] = RubyLLM::MCP.config.protocol_version
+
+          HTTPX.plugin(:follow_redirects).with(
+            timeout: { total: DEFAULT_OAUTH_TIMEOUT },
+            headers: headers
+          )
+        end
+
+        # Normalize and set server URL
+        # Ensures consistent URL format for storage keys
+        def server_url=(url)
+          @server_url = self.class.normalize_url(url)
+        end
+
+        # Validate redirect URI per OAuth 2.1 security requirements
+        # @param uri [String] redirect URI
+        # @raise [ArgumentError] if URI is invalid or not localhost/HTTPS
+        def validate_redirect_uri!(uri)
+          parsed = URI.parse(uri)
+          is_localhost = ["localhost", "127.0.0.1", "::1"].include?(parsed.host)
+          is_https = parsed.scheme == "https"
+
+          unless is_localhost || is_https
+            raise ArgumentError,
+                  "Redirect URI must be localhost or HTTPS per OAuth 2.1 security requirements: #{uri}"
+          end
+        rescue URI::InvalidURIError => e
+          raise ArgumentError, "Invalid redirect URI: #{uri} - #{e.message}"
+        end
+
+        # Validate HTTPS usage for OAuth endpoint (warning only)
+        # @param url [String] endpoint URL
+        # @param endpoint_name [String] descriptive name for logging
+        def validate_https_endpoint(url, endpoint_name)
+          uri = URI.parse(url)
+          is_localhost = ["localhost", "127.0.0.1", "::1"].include?(uri.host)
+
+          if uri.scheme != "https" && !is_localhost
+            logger.warn("WARNING: #{endpoint_name} is not using HTTPS: #{url}")
+            logger.warn("OAuth endpoints SHOULD use HTTPS in production environments")
+          end
+        end
+
+        # Refresh access token using refresh token
+        # @param token [Token] current token with refresh_token
+        # @return [Token, nil] new token or nil if refresh failed
+        def refresh_token(token)
+          return nil unless token.refresh_token
+
+          server_metadata = @discoverer.discover(server_url)
+          client_info = storage.get_client_info(server_url)
+          return nil unless server_metadata && client_info
+
+          new_token = @token_manager.refresh_token(server_metadata, client_info, token, server_url)
+          storage.set_token(server_url, new_token) if new_token
+          logger.debug("Token refreshed successfully") if new_token
+          new_token
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/security.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      # Security utilities for OAuth implementation
+      module Security
+        module_function
+
+        # Constant-time string comparison to prevent timing attacks
+        # @param a [String] first string
+        # @param b [String] second string
+        # @return [Boolean] true if strings are equal
+        def secure_compare(first, second)
+          # Handle nil values
+          return false if first.nil? || second.nil?
+
+          # Use Rails/ActiveSupport's secure_compare if available (more battle-tested)
+          if defined?(ActiveSupport::SecurityUtils) && ActiveSupport::SecurityUtils.respond_to?(:secure_compare)
+            return ActiveSupport::SecurityUtils.secure_compare(first, second)
+          end
+
+          # Fallback to our own implementation
+          constant_time_compare?(first, second)
+        end
+
+        # Constant-time comparison implementation
+        # @param a [String] first string
+        # @param b [String] second string
+        # @return [Boolean] true if strings are equal
+        def constant_time_compare?(first, second)
+          return false unless first.bytesize == second.bytesize
+
+          l = first.unpack("C*")
+          r = 0
+          i = -1
+
+          second.each_byte { |v| r |= v ^ l[i += 1] }
+          r.zero?
+        end
+      end
+    end
+  end
+end