ruby_llm-mcp 0.7.1 → 0.8.0

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

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require_relative "browser/http_server"
+require_relative "browser/callback_handler"
+require_relative "browser/pages"
+require_relative "browser/opener"
+require_relative "browser/callback_server"
+
+module RubyLLM
+  module MCP
+    module Auth
+      # Browser-based OAuth authentication provider
+      # Provides complete OAuth 2.1 flow with automatic browser opening and local callback server
+      # Compatible API with OAuthProvider for seamless interchange
+      class BrowserOAuthProvider
+        attr_reader :oauth_provider, :callback_port, :callback_path, :logger
+        attr_accessor :server_url, :redirect_uri, :scope, :storage
+
+        # Expose custom pages for testing/inspection
+        def custom_success_page
+          @pages.instance_variable_get(:@custom_success_page)
+        end
+
+        def custom_error_page
+          @pages.instance_variable_get(:@custom_error_page)
+        end
+
+        # @param server_url [String] OAuth server URL (alternative to oauth_provider)
+        # @param oauth_provider [OAuthProvider] OAuth provider instance (alternative to server_url)
+        # @param callback_port [Integer] port for local callback server
+        # @param callback_path [String] path for callback URL
+        # @param logger [Logger] logger instance
+        # @param storage [Object] token storage instance
+        # @param redirect_uri [String] OAuth redirect URI
+        # @param scope [String] OAuth scopes
+        def initialize(server_url: nil, oauth_provider: nil, callback_port: 8080, callback_path: "/callback", # rubocop:disable Metrics/ParameterLists
+                       logger: nil, storage: nil, redirect_uri: nil, scope: nil)
+          @logger = logger || MCP.logger
+          @callback_port = callback_port
+          @callback_path = callback_path
+
+          # Set redirect_uri before creating oauth_provider
+          redirect_uri ||= "http://localhost:#{callback_port}#{callback_path}"
+
+          # Either accept an existing oauth_provider or create one
+          if oauth_provider
+            @oauth_provider = oauth_provider
+            # Sync attributes from the provided oauth_provider
+            @server_url = oauth_provider.server_url
+            @redirect_uri = oauth_provider.redirect_uri
+            @scope = oauth_provider.scope
+            @storage = oauth_provider.storage
+          elsif server_url
+            @server_url = server_url
+            @redirect_uri = redirect_uri
+            @scope = scope
+            @storage = storage || MemoryStorage.new
+            # Create a new oauth_provider
+            @oauth_provider = OAuthProvider.new(
+              server_url: server_url,
+              redirect_uri: redirect_uri,
+              scope: scope,
+              logger: @logger,
+              storage: @storage
+            )
+          else
+            raise ArgumentError, "Either server_url or oauth_provider must be provided"
+          end
+
+          # Ensure OAuth provider redirect_uri matches our callback server
+          validate_and_sync_redirect_uri!
+
+          # Initialize browser helpers
+          @http_server = Browser::HttpServer.new(port: @callback_port, logger: @logger)
+          @callback_handler = Browser::CallbackHandler.new(callback_path: @callback_path, logger: @logger)
+          @pages = Browser::Pages.new(
+            custom_success_page: MCP.config.oauth.browser_success_page,
+            custom_error_page: MCP.config.oauth.browser_error_page
+          )
+          @opener = Browser::Opener.new(logger: @logger)
+        end
+
+        # Perform complete OAuth authentication flow with browser
+        # Compatible with OAuthProvider's authentication pattern
+        # @param timeout [Integer] seconds to wait for authorization
+        # @param auto_open_browser [Boolean] automatically open browser
+        # @return [Token] access token
+        def authenticate(timeout: 300, auto_open_browser: true)
+          # 1. Start authorization flow and get URL
+          auth_url = @oauth_provider.start_authorization_flow
+          @logger.debug("Authorization URL: #{auth_url}")
+
+          # 2. Create result container for thread coordination
+          result = { code: nil, state: nil, error: nil, completed: false }
+          mutex = Mutex.new
+          condition = ConditionVariable.new
+
+          # 3. Start local callback server
+          server = start_callback_server(result, mutex, condition)
+
+          begin
+            # 4. Open browser to authorization URL
+            if auto_open_browser
+              @opener.open_browser(auth_url)
+              @logger.info("\nOpening browser for authorization...")
+              @logger.info("If browser doesn't open automatically, visit this URL:")
+            else
+              @logger.info("\nPlease visit this URL to authorize:")
+            end
+            @logger.info(auth_url)
+            @logger.info("\nWaiting for authorization...")
+
+            # 5. Wait for callback with timeout
+            mutex.synchronize do
+              condition.wait(mutex, timeout) unless result[:completed]
+            end
+
+            unless result[:completed]
+              raise Errors::TimeoutError.new(message: "OAuth authorization timed out after #{timeout} seconds")
+            end
+
+            if result[:error]
+              raise Errors::TransportError.new(message: "OAuth authorization failed: #{result[:error]}")
+            end
+
+            # 6. Complete OAuth flow
+            @logger.debug("Completing OAuth authorization flow")
+            token = @oauth_provider.complete_authorization_flow(result[:code], result[:state])
+
+            @logger.info("\nAuthentication successful!")
+            token
+          ensure
+            # Always shutdown the server
+            server&.shutdown
+          end
+        end
+
+        # Get current access token (for compatibility with OAuthProvider)
+        # @return [Token, nil] valid access token or nil
+        def access_token
+          @oauth_provider.access_token
+        end
+
+        # Apply authorization header to HTTP request (for compatibility with OAuthProvider)
+        # @param request [HTTPX::Request] HTTP request object
+        def apply_authorization(request)
+          @oauth_provider.apply_authorization(request)
+        end
+
+        # Start authorization flow (for compatibility with OAuthProvider)
+        # @return [String] authorization URL
+        def start_authorization_flow
+          @oauth_provider.start_authorization_flow
+        end
+
+        # Complete authorization flow (for compatibility with OAuthProvider)
+        # @param code [String] authorization code
+        # @param state [String] state parameter
+        # @return [Token] access token
+        def complete_authorization_flow(code, state)
+          @oauth_provider.complete_authorization_flow(code, state)
+        end
+
+        private
+
+        # Validate and synchronize redirect_uri between this provider and oauth_provider
+        def validate_and_sync_redirect_uri!
+          expected_redirect_uri = "http://localhost:#{@callback_port}#{@callback_path}"
+
+          if @oauth_provider.redirect_uri != expected_redirect_uri
+            @logger.warn("OAuth provider redirect_uri (#{@oauth_provider.redirect_uri}) " \
+                         "doesn't match callback server (#{expected_redirect_uri}). " \
+                         "Updating redirect_uri.")
+            @oauth_provider.redirect_uri = expected_redirect_uri
+            @redirect_uri = expected_redirect_uri
+          end
+        end
+
+        # Start local HTTP callback server
+        # @param result [Hash] result container for callback data
+        # @param mutex [Mutex] synchronization mutex
+        # @param condition [ConditionVariable] wait condition
+        # @return [Browser::CallbackServer] server wrapper
+        def start_callback_server(result, mutex, condition)
+          server = @http_server.start_server
+          @logger.debug("Started callback server on http://127.0.0.1:#{@callback_port}#{@callback_path}")
+
+          running = true
+
+          # Start server in background thread
+          thread = Thread.new do
+            while running
+              begin
+                # Use wait_readable with timeout to allow checking running flag
+                next unless server.wait_readable(0.5)
+
+                client = server.accept
+                handle_http_request(client, result, mutex, condition)
+              rescue IOError, Errno::EBADF
+                # Server was closed, exit loop
+                break
+              rescue StandardError => e
+                @logger.error("Error handling callback request: #{e.message}")
+              end
+            end
+          end
+
+          # Return wrapper with shutdown method
+          Browser::CallbackServer.new(server, thread, -> { running = false })
+        end
+
+        # Handle incoming HTTP request on callback server
+        # @param client [TCPSocket] client socket
+        # @param result [Hash] result container
+        # @param mutex [Mutex] synchronization mutex
+        # @param condition [ConditionVariable] wait condition
+        def handle_http_request(client, result, mutex, condition)
+          @http_server.configure_client_socket(client)
+
+          request_line = @http_server.read_request_line(client)
+          return unless request_line
+
+          method_name, path = @http_server.extract_request_parts(request_line)
+          return unless method_name && path
+
+          @logger.debug("Received #{method_name} request: #{path}")
+          @http_server.read_http_headers(client)
+
+          # Validate callback path
+          unless @callback_handler.valid_callback_path?(path)
+            @http_server.send_http_response(client, 404, "text/plain", "Not Found")
+            return
+          end
+
+          # Parse and extract OAuth parameters
+          params = @callback_handler.parse_callback_params(path, @http_server)
+          oauth_params = @callback_handler.extract_oauth_params(params)
+
+          # Update result with OAuth parameters
+          @callback_handler.update_result_with_oauth_params(oauth_params, result, mutex, condition)
+
+          # Send response
+          if result[:error]
+            @http_server.send_http_response(client, 400, "text/html", @pages.error_page(result[:error]))
+          else
+            @http_server.send_http_response(client, 200, "text/html", @pages.success_page)
+          end
+        ensure
+          client&.close
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      # Service for registering OAuth clients
+      # Implements RFC 7591 (Dynamic Client Registration)
+      class ClientRegistrar
+        attr_reader :http_client, :storage, :logger, :config
+
+        def initialize(http_client, storage, logger, config)
+          @http_client = http_client
+          @storage = storage
+          @logger = logger
+          @config = config
+        end
+
+        # Get cached client info or register new client
+        # @param server_url [String] MCP server URL
+        # @param server_metadata [ServerMetadata] server metadata
+        # @param grant_type [Symbol] :authorization_code or :client_credentials
+        # @param redirect_uri [String] redirect URI for authorization code flow
+        # @param scope [String, nil] requested scope
+        # @return [ClientInfo] client information
+        def get_or_register(server_url, server_metadata, grant_type, redirect_uri, scope)
+          # Check cache first
+          client_info = storage.get_client_info(server_url)
+          return client_info if client_info && !client_info.client_secret_expired?
+
+          # Register new client if no cached info or secret expired
+          if server_metadata.supports_registration?
+            register(server_url, server_metadata, grant_type, redirect_uri, scope)
+          else
+            raise Errors::TransportError.new(
+              message: "OAuth server does not support dynamic client registration"
+            )
+          end
+        end
+
+        # Register OAuth client dynamically (RFC 7591)
+        # @param server_url [String] MCP server URL
+        # @param server_metadata [ServerMetadata] server metadata
+        # @param grant_type [Symbol] :authorization_code or :client_credentials
+        # @param redirect_uri [String] redirect URI for authorization code flow
+        # @param scope [String, nil] requested scope
+        # @return [ClientInfo] registered client info
+        def register(server_url, server_metadata, grant_type, redirect_uri, scope)
+          logger.debug("Registering OAuth client at: #{server_metadata.registration_endpoint}")
+
+          metadata = build_client_metadata(grant_type, redirect_uri, scope)
+          response = post_registration(server_metadata, metadata)
+          data = HttpResponseHandler.handle_response(response, context: "Client registration",
+                                                               expected_status: [200, 201])
+
+          registered_metadata = parse_registered_metadata(data, redirect_uri)
+          warn_redirect_uri_mismatch(registered_metadata, redirect_uri)
+
+          client_info = create_client_info(data, registered_metadata)
+          storage.set_client_info(server_url, client_info)
+          logger.debug("Client registered successfully: #{client_info.client_id}")
+          client_info
+        end
+
+        private
+
+        # Build client metadata for registration request
+        # @param grant_type [Symbol] :authorization_code or :client_credentials
+        # @param redirect_uri [String] redirect URI
+        # @param scope [String, nil] requested scope
+        # @return [ClientMetadata] client metadata
+        def build_client_metadata(grant_type, redirect_uri, scope)
+          strategy = grant_strategy_for(grant_type)
+
+          metadata = {
+            redirect_uris: [redirect_uri],
+            token_endpoint_auth_method: strategy.auth_method,
+            grant_types: strategy.grant_types_list,
+            response_types: strategy.response_types_list,
+            scope: scope,
+            client_name: config.oauth.client_name,
+            client_uri: config.oauth.client_uri,
+            logo_uri: config.oauth.logo_uri,
+            contacts: config.oauth.contacts,
+            tos_uri: config.oauth.tos_uri,
+            policy_uri: config.oauth.policy_uri,
+            jwks_uri: config.oauth.jwks_uri,
+            jwks: config.oauth.jwks,
+            software_id: config.oauth.software_id,
+            software_version: config.oauth.software_version
+          }.compact
+
+          ClientMetadata.new(**metadata)
+        end
+
+        # Get grant strategy for grant type
+        # @param grant_type [Symbol] :authorization_code or :client_credentials
+        # @return [GrantStrategies::Base] grant strategy
+        def grant_strategy_for(grant_type)
+          case grant_type
+          when :client_credentials
+            GrantStrategies::ClientCredentials.new
+          else
+            GrantStrategies::AuthorizationCode.new
+          end
+        end
+
+        # Post client registration request
+        # @param server_metadata [ServerMetadata] server metadata
+        # @param metadata [ClientMetadata] client metadata
+        # @return [HTTPX::Response] HTTP response
+        def post_registration(server_metadata, metadata)
+          http_client.post(
+            server_metadata.registration_endpoint,
+            headers: { "Content-Type" => "application/json" },
+            json: metadata.to_h
+          )
+        end
+
+        # Parse registered client metadata from response
+        # @param data [Hash] registration response data
+        # @param redirect_uri [String] requested redirect URI
+        # @return [ClientMetadata] registered metadata
+        def parse_registered_metadata(data, redirect_uri)
+          ClientMetadata.new(
+            redirect_uris: data["redirect_uris"] || [redirect_uri],
+            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"],
+            client_name: data["client_name"],
+            client_uri: data["client_uri"],
+            logo_uri: data["logo_uri"],
+            contacts: data["contacts"],
+            tos_uri: data["tos_uri"],
+            policy_uri: data["policy_uri"],
+            jwks_uri: data["jwks_uri"],
+            jwks: data["jwks"],
+            software_id: data["software_id"],
+            software_version: data["software_version"]
+          )
+        end
+
+        # Warn if server changed redirect URI
+        # @param registered_metadata [ClientMetadata] registered metadata
+        # @param redirect_uri [String] requested redirect URI
+        def warn_redirect_uri_mismatch(registered_metadata, redirect_uri)
+          return if registered_metadata.redirect_uris.first == redirect_uri
+
+          logger.warn("OAuth server changed redirect_uri:")
+          logger.warn("  Requested:  #{redirect_uri}")
+          logger.warn("  Registered: #{registered_metadata.redirect_uris.first}")
+        end
+
+        # Create client info from registration response
+        # @param data [Hash] registration response data
+        # @param registered_metadata [ClientMetadata] registered metadata
+        # @return [ClientInfo] client info
+        def create_client_info(data, registered_metadata)
+          ClientInfo.new(
+            client_id: data["client_id"],
+            client_secret: data["client_secret"],
+            client_id_issued_at: data["client_id_issued_at"],
+            client_secret_expires_at: data["client_secret_expires_at"],
+            metadata: registered_metadata
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      # Service for discovering OAuth authorization servers
+      # Implements RFC 8414 (Server Metadata) and RFC 9728 (Protected Resource Metadata)
+      class Discoverer
+        attr_reader :http_client, :storage, :logger
+
+        def initialize(http_client, storage, logger)
+          @http_client = http_client
+          @storage = storage
+          @logger = logger
+        end
+
+        # Discover OAuth authorization server
+        # Tries two patterns: server as own auth server, or delegated auth server
+        # @param server_url [String] MCP server URL
+        # @return [ServerMetadata, nil] server metadata or nil
+        def discover(server_url)
+          logger.debug("Discovering OAuth authorization server for #{server_url}")
+
+          # Check cache first
+          cached = storage.get_server_metadata(server_url)
+          return cached if cached
+
+          server_metadata = try_authorization_server_discovery(server_url) ||
+                            try_protected_resource_discovery(server_url) ||
+                            create_default_metadata(server_url)
+
+          # Cache and return
+          storage.set_server_metadata(server_url, server_metadata) if server_metadata
+          server_metadata
+        end
+
+        private
+
+        # Try oauth-authorization-server discovery (server is own auth server)
+        # @param server_url [String] MCP server URL
+        # @return [ServerMetadata, nil] server metadata or nil
+        def try_authorization_server_discovery(server_url)
+          discovery_url = UrlBuilder.build_discovery_url(server_url, :authorization_server)
+          logger.debug("Trying discovery URL: #{discovery_url}")
+          fetch_server_metadata(discovery_url)
+        rescue StandardError => e
+          logger.debug("oauth-authorization-server discovery failed: #{e.message}")
+          nil
+        end
+
+        # Try oauth-protected-resource discovery (delegation pattern)
+        # @param server_url [String] MCP server URL
+        # @return [ServerMetadata, nil] server metadata or nil
+        def try_protected_resource_discovery(server_url)
+          discovery_url = UrlBuilder.build_discovery_url(server_url, :protected_resource)
+          logger.debug("Trying protected resource discovery: #{discovery_url}")
+          resource_metadata = fetch_resource_metadata(discovery_url)
+          auth_server_url = resource_metadata.authorization_servers.first
+
+          if auth_server_url
+            logger.debug("Found delegated auth server: #{auth_server_url}")
+            fetch_server_metadata("#{auth_server_url}/.well-known/oauth-authorization-server")
+          end
+        rescue StandardError => e
+          logger.debug("oauth-protected-resource discovery failed: #{e.message}")
+          nil
+        end
+
+        # Create default server metadata when discovery fails
+        # @param server_url [String] MCP server URL
+        # @return [ServerMetadata] server metadata with default endpoints
+        def create_default_metadata(server_url)
+          base_url = UrlBuilder.get_authorization_base_url(server_url)
+          logger.warn("OAuth discovery failed, falling back to default endpoints")
+          logger.info("Using default OAuth endpoints for #{base_url}")
+
+          ServerMetadata.new(
+            issuer: base_url,
+            authorization_endpoint: "#{base_url}/authorize",
+            token_endpoint: "#{base_url}/token",
+            options: { registration_endpoint: "#{base_url}/register" }
+          )
+        end
+
+        # Fetch OAuth server metadata
+        # @param url [String] discovery URL
+        # @return [ServerMetadata] server metadata
+        def fetch_server_metadata(url)
+          logger.debug("Fetching server metadata from #{url}")
+          response = http_client.get(url)
+
+          data = HttpResponseHandler.handle_response(response, context: "Server metadata fetch")
+
+          ServerMetadata.new(
+            issuer: data["issuer"],
+            authorization_endpoint: data["authorization_endpoint"],
+            token_endpoint: data["token_endpoint"],
+            options: {
+              registration_endpoint: data["registration_endpoint"],
+              scopes_supported: data["scopes_supported"],
+              response_types_supported: data["response_types_supported"],
+              grant_types_supported: data["grant_types_supported"]
+            }
+          )
+        end
+
+        # Fetch OAuth protected resource metadata
+        # @param url [String] discovery URL
+        # @return [ResourceMetadata] resource metadata
+        def fetch_resource_metadata(url)
+          logger.debug("Fetching resource metadata from #{url}")
+          response = http_client.get(url)
+
+          data = HttpResponseHandler.handle_response(response, context: "Resource metadata fetch")
+
+          ResourceMetadata.new(
+            resource: data["resource"],
+            authorization_servers: data["authorization_servers"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      module Flows
+        # Orchestrates OAuth 2.1 Authorization Code flow with PKCE
+        # Coordinates session management, discovery, registration, and token exchange
+        class AuthorizationCodeFlow
+          attr_reader :discoverer, :client_registrar, :session_manager, :token_manager, :storage, :logger
+
+          def initialize(discoverer:, client_registrar:, session_manager:, token_manager:, storage:, logger:) # rubocop:disable Metrics/ParameterLists
+            @discoverer = discoverer
+            @client_registrar = client_registrar
+            @session_manager = session_manager
+            @token_manager = token_manager
+            @storage = storage
+            @logger = logger
+          end
+
+          # Start OAuth authorization flow
+          # @param server_url [String] MCP server URL
+          # @param redirect_uri [String] redirect URI for callback
+          # @param scope [String, nil] requested scope
+          # @param https_validator [Proc] callback to validate HTTPS usage
+          # @return [String] authorization URL for user to visit
+          def start(server_url, redirect_uri, scope, https_validator: nil)
+            logger.debug("Starting OAuth authorization flow for #{server_url}")
+
+            # 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)
+            client_info = client_registrar.get_or_register(
+              server_url,
+              server_metadata,
+              :authorization_code,
+              redirect_uri,
+              scope
+            )
+
+            # 3. Create session with PKCE and CSRF state
+            session = session_manager.create_session(server_url)
+
+            # 4. Validate HTTPS usage (optional warning)
+            https_validator&.call(server_metadata.authorization_endpoint, "Authorization endpoint")
+
+            # 5. Build and return authorization URL
+            auth_url = UrlBuilder.build_authorization_url(
+              server_metadata.authorization_endpoint,
+              client_info.client_id,
+              client_info.metadata.redirect_uris.first,
+              scope,
+              session[:state],
+              session[:pkce],
+              server_url
+            )
+
+            logger.debug("Authorization URL: #{auth_url}")
+            auth_url
+          end
+
+          # Complete OAuth authorization flow after callback
+          # @param server_url [String] MCP server URL
+          # @param code [String] authorization code from callback
+          # @param state [String] state parameter from callback
+          # @return [Token] access token
+          def complete(server_url, code, state)
+            logger.debug("Completing OAuth authorization flow")
+
+            # 1. Validate state and retrieve session data
+            session_data = session_manager.validate_and_retrieve_session(server_url, state)
+
+            pkce = session_data[:pkce]
+            client_info = session_data[:client_info]
+            server_metadata = discoverer.discover(server_url)
+
+            unless pkce && client_info
+              raise Errors::TransportError.new(message: "Missing PKCE or client info")
+            end
+
+            # 2. Exchange authorization code for tokens
+            token = token_manager.exchange_authorization_code(
+              server_metadata,
+              client_info,
+              code,
+              pkce,
+              server_url
+            )
+
+            # 3. Store token
+            storage.set_token(server_url, token)
+
+            # 4. Clean up temporary session data
+            session_manager.cleanup_session(server_url)
+
+            logger.info("OAuth authorization completed successfully")
+            token
+          end
+        end
+      end
+    end
+  end
+end