ruby-mcp-client 0.8.1 → 0.9.0

data/lib/mcp_client/auth/browser_oauth.rb

@@ -0,0 +1,424 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'uri'
+require 'cgi'
+require_relative 'oauth_provider'
+
+module MCPClient
+  module Auth
+    # Browser-based OAuth authentication flow helper
+    # Provides a complete OAuth flow using browser authentication with a local callback server
+    class BrowserOAuth
+      # @!attribute [r] oauth_provider
+      #   @return [OAuthProvider] The OAuth provider instance
+      # @!attribute [r] callback_port
+      #   @return [Integer] Port for local callback server
+      # @!attribute [r] callback_path
+      #   @return [String] Path for OAuth callback
+      # @!attribute [r] logger
+      #   @return [Logger] Logger instance
+      attr_reader :oauth_provider, :callback_port, :callback_path, :logger
+
+      # Initialize browser OAuth helper
+      # @param oauth_provider [OAuthProvider] OAuth provider to use for authentication
+      # @param callback_port [Integer] Port for local callback server (default: 8080)
+      # @param callback_path [String] Path for OAuth callback (default: '/callback')
+      # @param logger [Logger, nil] Optional logger
+      def initialize(oauth_provider, callback_port: 8080, callback_path: '/callback', logger: nil)
+        @oauth_provider = oauth_provider
+        @callback_port = callback_port
+        @callback_path = callback_path
+        @logger = logger || Logger.new($stdout, level: Logger::WARN)
+
+        # Ensure OAuth provider's redirect_uri matches our callback server
+        expected_redirect_uri = "http://localhost:#{callback_port}#{callback_path}"
+        return unless 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
+      end
+
+      # Perform complete browser-based OAuth authentication flow
+      # This will:
+      # 1. Start a local HTTP server to handle the callback
+      # 2. Open the authorization URL in the user's browser
+      # 3. Wait for the user to authorize and receive the callback
+      # 4. Complete the OAuth flow and return the token
+      # @param timeout [Integer] Timeout in seconds to wait for callback (default: 300 = 5 minutes)
+      # @param auto_open_browser [Boolean] Automatically open browser (default: true)
+      # @return [Token] Access token after successful authentication
+      # @raise [Timeout::Error] if user doesn't complete auth within timeout
+      # @raise [MCPClient::Errors::ConnectionError] if OAuth flow fails
+      def authenticate(timeout: 300, auto_open_browser: true)
+        # Start authorization flow and get URL
+        auth_url = @oauth_provider.start_authorization_flow
+        @logger.debug("Authorization URL: #{auth_url}")
+
+        # Create a result container to share data between threads
+        result = { code: nil, state: nil, error: nil, completed: false }
+        mutex = Mutex.new
+        condition = ConditionVariable.new
+
+        # Start local callback server
+        server = start_callback_server(result, mutex, condition)
+
+        begin
+          # Open browser to authorization URL
+          if auto_open_browser
+            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...")
+
+          # Wait for callback with timeout
+          mutex.synchronize do
+            condition.wait(mutex, timeout) unless result[:completed]
+          end
+
+          # Check if we got a response
+          raise Timeout::Error, "OAuth authorization timed out after #{timeout} seconds" unless result[:completed]
+
+          # Check for errors
+          raise MCPClient::Errors::ConnectionError, "OAuth authorization failed: #{result[:error]}" if result[:error]
+
+          # 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
+
+      # Start the local callback server using TCPServer
+      # @param result [Hash] Hash to store callback results
+      # @param mutex [Mutex] Mutex for thread synchronization
+      # @param condition [ConditionVariable] Condition variable for thread signaling
+      # @return [CallbackServer] The running callback server
+      # @raise [MCPClient::Errors::ConnectionError] if port is already in use
+      # @private
+      def start_callback_server(result, mutex, condition)
+        begin
+          server = TCPServer.new('127.0.0.1', @callback_port)
+          @logger.debug("Started callback server on http://127.0.0.1:#{@callback_port}#{@callback_path}")
+        rescue Errno::EADDRINUSE
+          raise MCPClient::Errors::ConnectionError,
+                "Cannot start OAuth callback server: port #{@callback_port} is already in use. " \
+                'Please close the application using this port or choose a different callback_port.'
+        rescue StandardError => e
+          raise MCPClient::Errors::ConnectionError,
+                "Failed to start OAuth callback server on port #{@callback_port}: #{e.message}"
+        end
+
+        running = true
+
+        # Start server in background thread
+        thread = Thread.new do
+          while running
+            begin
+              # Use wait_readable with timeout to allow checking the 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 an object with shutdown method for compatibility
+        CallbackServer.new(server, thread, -> { running = false })
+      end
+
+      # Handle HTTP request from OAuth callback
+      # @param client [TCPSocket] The client socket
+      # @param result [Hash] Hash to store callback results
+      # @param mutex [Mutex] Mutex for thread synchronization
+      # @param condition [ConditionVariable] Condition variable for thread signaling
+      # @private
+      def handle_http_request(client, result, mutex, condition)
+        # Set read timeout to prevent hanging connections
+        client.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [5, 0].pack('l_2'))
+
+        # Read request line
+        request_line = client.gets
+        return unless request_line
+
+        parts = request_line.split
+        return unless parts.length >= 2
+
+        method, path = parts[0..1]
+        @logger.debug("Received #{method} request: #{path}")
+
+        # Read and discard headers until blank line (with limit to prevent memory exhaustion)
+        header_count = 0
+        loop do
+          break if header_count >= 100 # Limit header count
+
+          line = client.gets
+          break if line.nil? || line.strip.empty?
+
+          header_count += 1
+        end
+
+        # Parse path and query parameters
+        uri_path, query_string = path.split('?', 2)
+
+        # Only handle our callback path
+        unless uri_path == @callback_path
+          send_http_response(client, 404, 'text/plain', 'Not Found')
+          return
+        end
+
+        # Parse query parameters
+        params = parse_query_params(query_string || '')
+        @logger.debug("Callback params: #{params.keys.join(', ')}")
+
+        # Extract OAuth parameters
+        code = params['code']
+        state = params['state']
+        error = params['error']
+        error_description = params['error_description']
+
+        # Update result and signal waiting thread
+        mutex.synchronize do
+          if error
+            result[:error] = error_description || error
+          elsif code && state
+            result[:code] = code
+            result[:state] = state
+          else
+            result[:error] = 'Invalid callback: missing code or state parameter'
+          end
+          result[:completed] = true
+
+          condition.signal
+        end
+
+        # Send HTML response to browser
+        if result[:error]
+          send_http_response(client, 400, 'text/html', error_page(result[:error]))
+        else
+          send_http_response(client, 200, 'text/html', success_page)
+        end
+      ensure
+        client&.close
+      end
+
+      # Parse URL query parameters
+      # @param query_string [String] Query string from URL
+      # @return [Hash] Parsed parameters
+      # @private
+      def parse_query_params(query_string)
+        params = {}
+        query_string.split('&').each do |param|
+          next if param.empty?
+
+          key, value = param.split('=', 2)
+          params[CGI.unescape(key)] = CGI.unescape(value || '')
+        end
+        params
+      end
+
+      # Send HTTP response to client
+      # @param client [TCPSocket] The client socket
+      # @param status_code [Integer] HTTP status code
+      # @param content_type [String] Content type header value
+      # @param body [String] Response body
+      # @private
+      def send_http_response(client, status_code, content_type, body)
+        status_text = case status_code
+                      when 200 then 'OK'
+                      when 400 then 'Bad Request'
+                      when 404 then 'Not Found'
+                      else 'Unknown'
+                      end
+
+        response = "HTTP/1.1 #{status_code} #{status_text}\r\n"
+        response += "Content-Type: #{content_type}; charset=utf-8\r\n"
+        response += "Content-Length: #{body.bytesize}\r\n"
+        response += "Connection: close\r\n"
+        response += "\r\n"
+        response += body
+
+        client.print(response)
+      end
+
+      # Open URL in default browser
+      # @param url [String] URL to open
+      # @return [Boolean] true if browser opened successfully
+      def open_browser(url)
+        case RbConfig::CONFIG['host_os']
+        when /darwin/
+          system('open', url)
+        when /linux|bsd/
+          system('xdg-open', url)
+        when /mswin|mingw|cygwin/
+          system('start', url)
+        else
+          @logger.warn('Unknown operating system, cannot open browser automatically')
+          false
+        end
+      rescue StandardError => e
+        @logger.warn("Failed to open browser: #{e.message}")
+        false
+      end
+
+      private
+
+      # HTML page shown on successful authentication
+      # @return [String] HTML content
+      def success_page
+        <<~HTML
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <meta charset="UTF-8">
+            <title>Authentication Successful</title>
+            <style>
+              body {
+                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                display: flex;
+                justify-content: center;
+                align-items: center;
+                height: 100vh;
+                margin: 0;
+                background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+              }
+              .container {
+                background: white;
+                padding: 3rem;
+                border-radius: 1rem;
+                box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+                text-align: center;
+                max-width: 400px;
+              }
+              .icon {
+                font-size: 4rem;
+                margin-bottom: 1rem;
+              }
+              h1 {
+                color: #333;
+                margin: 0 0 1rem 0;
+                font-size: 1.5rem;
+              }
+              p {
+                color: #666;
+                margin: 0;
+                line-height: 1.5;
+              }
+            </style>
+          </head>
+          <body>
+            <div class="container">
+              <div class="icon">✅</div>
+              <h1>Authentication Successful!</h1>
+              <p>You have successfully authenticated. You can close this window and return to your application.</p>
+            </div>
+          </body>
+          </html>
+        HTML
+      end
+
+      # HTML page shown on authentication error
+      # @param error_message [String] Error message to display
+      # @return [String] HTML content
+      def error_page(error_message)
+        <<~HTML
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <meta charset="UTF-8">
+            <title>Authentication Failed</title>
+            <style>
+              body {
+                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                display: flex;
+                justify-content: center;
+                align-items: center;
+                height: 100vh;
+                margin: 0;
+                background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+              }
+              .container {
+                background: white;
+                padding: 3rem;
+                border-radius: 1rem;
+                box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+                text-align: center;
+                max-width: 400px;
+              }
+              .icon {
+                font-size: 4rem;
+                margin-bottom: 1rem;
+              }
+              h1 {
+                color: #333;
+                margin: 0 0 1rem 0;
+                font-size: 1.5rem;
+              }
+              p {
+                color: #666;
+                margin: 0;
+                line-height: 1.5;
+              }
+              .error {
+                background: #fee;
+                border: 1px solid #fcc;
+                border-radius: 0.5rem;
+                padding: 1rem;
+                margin-top: 1rem;
+                color: #c33;
+                font-family: monospace;
+                font-size: 0.875rem;
+              }
+            </style>
+          </head>
+          <body>
+            <div class="container">
+              <div class="icon">❌</div>
+              <h1>Authentication Failed</h1>
+              <p>An error occurred during authentication.</p>
+              <div class="error">#{CGI.escapeHTML(error_message)}</div>
+            </div>
+          </body>
+          </html>
+        HTML
+      end
+
+      # Wrapper class for TCPServer to provide shutdown interface
+      # @private
+      class CallbackServer
+        def initialize(tcp_server, thread, stop_callback)
+          @tcp_server = tcp_server
+          @thread = thread
+          @stop_callback = stop_callback
+        end
+
+        def shutdown
+          # Signal the thread to stop
+          @stop_callback&.call
+
+          # Close the server socket
+          @tcp_server&.close
+
+          # Wait for thread to finish (with timeout)
+          @thread&.join(2)
+        end
+      end
+    end
+  end
+end

data/lib/mcp_client/auth/oauth_provider.rb

@@ -179,15 +179,18 @@ module MCPClient
       # Build OAuth discovery URL from server URL
       # Uses only the origin (scheme + host + port) for discovery
       # @param server_url [String] Full MCP server URL
+      # @param discovery_type [Symbol] Type of discovery endpoint (:authorization_server or :protected_resource)
       # @return [String] Discovery URL
-      def build_discovery_url(server_url)
+      def build_discovery_url(server_url, discovery_type = :authorization_server)
         uri = URI.parse(server_url)
 
         # Build origin URL (scheme + host + port)
         origin = "#{uri.scheme}://#{uri.host}"
         origin += ":#{uri.port}" if uri.port && !default_port?(uri)
 
-        "#{origin}/.well-known/oauth-protected-resource"
+        # Select discovery endpoint based on type
+        endpoint = discovery_type == :authorization_server ? 'oauth-authorization-server' : 'oauth-protected-resource'
+        "#{origin}/.well-known/#{endpoint}"
       end
 
       # Check if URI uses default port for its scheme
@@ -199,6 +202,9 @@ module MCPClient
       end
 
       # Discover authorization server metadata
+      # Tries multiple discovery patterns:
+      # 1. oauth-authorization-server (MCP spec pattern - server is its own auth server)
+      # 2. oauth-protected-resource (delegation pattern - points to external auth server)
       # @return [ServerMetadata] Authorization server metadata
       # @raise [MCPClient::Errors::ConnectionError] if discovery fails
       def discover_authorization_server
@@ -207,18 +213,40 @@ module MCPClient
           return cached
         end
 
-        # Build discovery URL using the origin (scheme + host + port) only
-        discovery_url = build_discovery_url(server_url)
+        server_metadata = nil
 
-        # Fetch resource metadata to find authorization server
-        resource_metadata = fetch_resource_metadata(discovery_url)
+        # 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
 
-        # Get first authorization server
-        auth_server_url = resource_metadata.authorization_servers.first
-        raise MCPClient::Errors::ConnectionError, 'No authorization servers found' unless auth_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
 
-        # Fetch authorization server metadata
-        server_metadata = fetch_server_metadata("#{auth_server_url}/.well-known/oauth-authorization-server")
+        unless server_metadata
+          raise MCPClient::Errors::ConnectionError,
+                'OAuth discovery failed: no valid endpoints found'
+        end
 
         # Cache the metadata
         storage.set_server_metadata(server_url, server_metadata)
@@ -279,10 +307,12 @@ module MCPClient
       def get_or_register_client(server_metadata)
         # Try to get existing client info from storage
         if (client_info = storage.get_client_info(server_url)) && !client_info.client_secret_expired?
+          logger.debug("Using cached OAuth client for #{server_url}")
           return client_info
         end
 
         # Register new client if server supports it
+        logger.debug('No cached client found, registering new OAuth client...')
         if server_metadata.supports_registration?
           register_client(server_metadata)
         else
@@ -317,12 +347,33 @@ module MCPClient
         end
 
         data = JSON.parse(response.body)
+        logger.debug("OAuth client registered successfully: #{data['client_id']}")
+
+        # Parse registered metadata from server response (may differ from our request)
+        registered_metadata = 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']
+        )
+
+        # Warn if server changed redirect_uri
+        requested_uri = redirect_uri
+        registered_uri = registered_metadata.redirect_uris.first
+        if registered_uri != requested_uri
+          logger.warn('OAuth server changed redirect_uri:')
+          logger.warn("  Requested:  #{requested_uri}")
+          logger.warn("  Registered: #{registered_uri}")
+          logger.warn("Using server's registered redirect_uri for token exchange.")
+        end
+
         client_info = 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: metadata
+          metadata: registered_metadata
         )
 
         # Store client info
@@ -342,10 +393,13 @@ module MCPClient
       # @param state [String] State parameter
       # @return [String] Authorization URL
       def build_authorization_url(server_metadata, client_info, pkce, state)
+        # Use the redirect_uri that was actually registered
+        registered_redirect_uri = client_info.metadata.redirect_uris.first
+
         params = {
           response_type: 'code',
           client_id: client_info.client_id,
-          redirect_uri: redirect_uri,
+          redirect_uri: registered_redirect_uri,
           scope: scope,
           state: state,
           code_challenge: pkce.code_challenge,
@@ -366,21 +420,51 @@ module MCPClient
       # @return [Token] Access token
       # @raise [MCPClient::Errors::ConnectionError] if token exchange fails
       def exchange_authorization_code(server_metadata, client_info, code, pkce)
-        logger.debug("Exchanging authorization code for token at: #{server_metadata.token_endpoint}")
+        logger.debug('Exchanging authorization code for access token')
+
+        # Use the redirect_uri that was actually registered, not our requested one
+        registered_redirect_uri = client_info.metadata.redirect_uris.first
 
         params = {
           grant_type: 'authorization_code',
           code: code,
-          redirect_uri: redirect_uri,
+          redirect_uri: registered_redirect_uri,
           client_id: client_info.client_id,
           code_verifier: pkce.code_verifier,
           resource: server_url
         }
 
-        response = @http_client.post(server_metadata.token_endpoint) do |req|
-          req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
-          req.headers['Accept'] = 'application/json'
-          req.body = URI.encode_www_form(params)
+        # Add client_secret if required by token_endpoint_auth_method
+        if client_info.client_secret && client_info.metadata.token_endpoint_auth_method == 'client_secret_post'
+          params[:client_secret] = client_info.client_secret
+        end
+
+        request_body = URI.encode_www_form(params)
+
+        send_token_request = lambda do |body|
+          @http_client.post(server_metadata.token_endpoint) do |req|
+            req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+            req.headers['Accept'] = 'application/json'
+            req.body = body
+          end
+        end
+
+        response = send_token_request.call(request_body)
+
+        unless response.success?
+          redirect_hint = extract_redirect_mismatch(response.body)
+
+          if redirect_hint && redirect_hint[:expected] && redirect_hint[:expected] != registered_redirect_uri
+            expected_uri = redirect_hint[:expected]
+            logger.warn(
+              "Token exchange failed: redirect_uri mismatch. Retrying with server's expected value: #{expected_uri}"
+            )
+
+            params[:redirect_uri] = redirect_hint[:expected]
+            retry_body = URI.encode_www_form(params)
+
+            response = send_token_request.call(retry_body)
+          end
         end
 
         unless response.success?
@@ -421,6 +505,11 @@ module MCPClient
           resource: server_url
         }
 
+        # Add client_secret if required by token_endpoint_auth_method
+        if client_info.client_secret && client_info.metadata.token_endpoint_auth_method == 'client_secret_post'
+          params[:client_secret] = client_info.client_secret
+        end
+
         response = @http_client.post(server_metadata.token_endpoint) do |req|
           req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
           req.headers['Accept'] = 'application/json'
@@ -451,6 +540,29 @@ module MCPClient
         nil
       end
 
+      # Extract redirect_uri mismatch details from an OAuth error response
+      # @param body [String] Raw HTTP response body
+      # @return [Hash, nil] Hash with :sent and :expected URIs if mismatch detected
+      def 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)
+
+        match = description.match(%r{You sent\s+(https?://\S+)[,.]?\s+and we expected\s+(https?://\S+)}i)
+        return nil unless match
+
+        {
+          sent: match[1],
+          expected: match[2],
+          description: description
+        }
+      rescue JSON::ParserError
+        nil
+      end
+
       # Simple in-memory storage for OAuth data
       class MemoryStorage
         def initialize

data/lib/mcp_client/auth.rb

@@ -47,7 +47,7 @@ module MCPClient
       # Convert token to authorization header value
       # @return [String] Authorization header value
       def to_header
-        "#{@token_type} #{@access_token}"
+        "#{@token_type.capitalize} #{@access_token}"
       end
 
       # Convert to hash for serialization