ruby_llm-mcp 0.7.1 → 1.0.0

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

@@ -0,0 +1,427 @@
+# frozen_string_literal: true
+
+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
+        # Serializes logger calls so test doubles and non-thread-safe loggers remain safe
+        # when callback and main threads log at the same time.
+        class SynchronizedLogger
+          def initialize(logger)
+            @logger = logger
+            @mutex = Mutex.new
+          end
+
+          def debug(...)
+            synchronized_log(:debug, ...)
+          end
+
+          def info(...)
+            synchronized_log(:info, ...)
+          end
+
+          def warn(...)
+            synchronized_log(:warn, ...)
+          end
+
+          def error(...)
+            synchronized_log(:error, ...)
+          end
+
+          private
+
+          def synchronized_log(level, ...)
+            @mutex.synchronize do
+              return unless @logger.respond_to?(level)
+
+              @logger.public_send(level, ...)
+            end
+          end
+        end
+
+        # Callback worker thread logs are intentionally isolated from the caller logger.
+        # JRuby + rspec-mocks logger doubles are not safe to share across threads.
+        class NullLogger
+          def debug(*) = nil
+          def info(*) = nil
+          def warn(*) = nil
+          def error(*) = nil
+        end
+
+        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
+          @synchronized_logger = SynchronizedLogger.new(@logger)
+          @callback_logger = NullLogger.new
+          @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: @synchronized_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: @callback_logger)
+          @callback_handler = Browser::CallbackHandler.new(callback_path: @callback_path, logger: @callback_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: @synchronized_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
+          @synchronized_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
+            announce_authorization_flow(auth_url, auto_open_browser)
+
+            # Allow callback worker to begin processing only after setup logging/browser open
+            # to reduce cross-thread test-double races under JRuby.
+            server.start
+
+            # 5. Wait for callback with timeout
+            mutex.synchronize do
+              condition.wait(mutex, timeout) unless result[:completed]
+            end
+
+            snapshot = mutex.synchronize { result.dup }
+
+            unless snapshot[:completed]
+              raise Errors::TimeoutError.new(message: "OAuth authorization timed out after #{timeout} seconds")
+            end
+
+            if snapshot[:error]
+              raise Errors::TransportError.new(message: "OAuth authorization failed: #{snapshot[:error]}")
+            end
+
+            # Stop callback server before token exchange to avoid cross-thread races
+            # (observed under JRuby when background callback logging overlaps main-thread mocks).
+            server&.shutdown
+            server = nil
+
+            # 6. Complete OAuth flow
+            @synchronized_logger.debug("Completing OAuth authorization flow")
+            token = @oauth_provider.complete_authorization_flow(snapshot[:code], snapshot[:state])
+
+            @synchronized_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
+
+        # Handle authentication challenge with browser-based auth
+        # @param www_authenticate [String, nil] WWW-Authenticate header value
+        # @param resource_metadata [String, nil] Resource metadata URL from response/challenge
+        # @param resource_metadata_url [String, nil] Legacy alias for resource_metadata
+        # @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: nil, resource_metadata_url: nil,
+                                            requested_scope: nil)
+          @synchronized_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: resource_metadata,
+              resource_metadata_url: resource_metadata_url,
+              requested_scope: requested_scope
+            )
+          rescue Errors::AuthenticationRequiredError
+            # Standard provider couldn't handle it - need interactive auth
+            @synchronized_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
+        def validate_and_sync_redirect_uri!
+          expected_redirect_uri = "http://localhost:#{@callback_port}#{@callback_path}"
+
+          if @oauth_provider.redirect_uri != expected_redirect_uri
+            @synchronized_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
+          @synchronized_logger.debug("Started callback server on http://127.0.0.1:#{@callback_port}#{@callback_path}")
+
+          control = build_callback_thread_control
+          thread = build_callback_worker_thread(server, result, mutex, condition, control)
+          stop_proc = -> { stop_callback_worker(control) }
+          start_proc = -> { start_callback_worker(control) }
+
+          # Return wrapper with shutdown method
+          Browser::CallbackServer.new(server, thread, stop_proc, start_proc)
+        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)
+          callback_result = nil
+
+          @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
+
+          @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)
+          callback_result = build_callback_result(oauth_params)
+
+          # Send response
+          if callback_result[:error]
+            @http_server.send_http_response(client, 400, "text/html", @pages.error_page(callback_result[:error]))
+          else
+            @http_server.send_http_response(client, 200, "text/html", @pages.success_page)
+          end
+        ensure
+          apply_callback_result(callback_result, result, mutex, condition) if callback_result
+          close_callback_client(client)
+        end
+
+        # Wake the waiting authentication flow with a deterministic error when callback
+        # processing fails in the worker thread.
+        def mark_callback_failure(result, mutex, condition, error)
+          mutex.synchronize do
+            return if result[:completed]
+
+            result[:error] = "OAuth callback processing failed: #{error.message}"
+            result[:completed] = true
+            condition.signal
+          end
+
+          @synchronized_logger.warn("OAuth callback worker failed: #{error.class}: #{error.message}")
+        end
+
+        def build_callback_result(oauth_params)
+          if oauth_params[:error]
+            { code: nil, state: nil, error: oauth_params[:error_description] || oauth_params[:error] }
+          elsif oauth_params[:code] && oauth_params[:state]
+            { code: oauth_params[:code], state: oauth_params[:state], error: nil }
+          else
+            { code: nil, state: nil, error: "Invalid callback: missing code or state parameter" }
+          end
+        end
+
+        def apply_callback_result(callback_result, result, mutex, condition)
+          mutex.synchronize do
+            return if result[:completed]
+
+            result[:code] = callback_result[:code]
+            result[:state] = callback_result[:state]
+            result[:error] = callback_result[:error]
+            result[:completed] = true
+            condition.signal
+          end
+        end
+
+        def close_callback_client(client)
+          client&.close
+        rescue IOError, SystemCallError => e
+          @synchronized_logger.debug("Error closing OAuth callback client socket: #{e.class}: #{e.message}")
+        end
+
+        def announce_authorization_flow(auth_url, auto_open_browser)
+          if auto_open_browser
+            @opener.open_browser(auth_url)
+            @synchronized_logger.info("\nOpening browser for authorization...")
+            @synchronized_logger.info("If browser doesn't open automatically, visit this URL:")
+          else
+            @synchronized_logger.info("\nPlease visit this URL to authorize:")
+          end
+          @synchronized_logger.info(auth_url)
+          @synchronized_logger.info("\nWaiting for authorization...")
+        end
+
+        def build_callback_thread_control
+          {
+            mutex: Mutex.new,
+            condition: ConditionVariable.new,
+            running: true,
+            accepting: false
+          }
+        end
+
+        def build_callback_worker_thread(server, result, result_mutex, condition, control)
+          Thread.new do
+            wait_for_callback_worker_start(control)
+
+            while callback_worker_running?(control)
+              begin
+                # Use wait_readable with timeout to allow checking stop signal
+                next unless server.wait_readable(0.5)
+
+                client = server.accept
+                handle_http_request(client, result, result_mutex, condition)
+                break if result_mutex.synchronize { result[:completed] }
+              rescue IOError, Errno::EBADF
+                # Server was closed, exit loop
+                break
+              rescue StandardError => e
+                mark_callback_failure(result, result_mutex, condition, e)
+                break
+              end
+            end
+          end
+        end
+
+        def wait_for_callback_worker_start(control)
+          control[:mutex].synchronize do
+            control[:condition].wait(control[:mutex]) until control[:accepting] || !control[:running]
+          end
+        end
+
+        def callback_worker_running?(control)
+          control[:mutex].synchronize { control[:running] }
+        end
+
+        def start_callback_worker(control)
+          control[:mutex].synchronize do
+            control[:accepting] = true
+            control[:condition].signal
+          end
+        end
+
+        def stop_callback_worker(control)
+          control[:mutex].synchronize do
+            control[:running] = false
+            control[:accepting] = true
+            control[:condition].broadcast
+          end
+        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