ruby_llm-mcp 0.7.1 → 0.8.0

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

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      # Service for managing OAuth token operations
+      # Handles token exchange, refresh, and client credentials flows
+      class TokenManager
+        attr_reader :http_client, :logger
+
+        def initialize(http_client, logger)
+          @http_client = http_client
+          @logger = logger
+        end
+
+        # Exchange authorization code for access token
+        # @param server_metadata [ServerMetadata] server metadata
+        # @param client_info [ClientInfo] client info
+        # @param code [String] authorization code
+        # @param pkce [PKCE] PKCE parameters
+        # @param server_url [String] MCP server URL
+        # @return [Token] access token
+        def exchange_authorization_code(server_metadata, client_info, code, pkce, server_url)
+          logger.debug("Exchanging authorization code for access token")
+
+          registered_redirect_uri = client_info.metadata.redirect_uris.first
+          params = build_auth_code_params(client_info, code, pkce, registered_redirect_uri, server_url)
+
+          response = post_token_exchange(server_metadata, params)
+          response = retry_if_redirect_mismatch(response, server_metadata, params, registered_redirect_uri)
+
+          validate_token_response!(response, "Token exchange")
+          parse_token_response(response)
+        end
+
+        # Exchange client credentials for access token
+        # @param server_metadata [ServerMetadata] server metadata
+        # @param client_info [ClientInfo] client info with secret
+        # @param scope [String, nil] requested scope
+        # @param server_url [String] MCP server URL
+        # @return [Token] access token
+        def exchange_client_credentials(server_metadata, client_info, scope, server_url)
+          logger.debug("Exchanging client credentials for access token")
+
+          params = {
+            grant_type: "client_credentials",
+            client_id: client_info.client_id,
+            client_secret: client_info.client_secret,
+            scope: scope,
+            resource: server_url
+          }.compact
+
+          response = post_token_exchange(server_metadata, params)
+          validate_token_response!(response, "Token exchange")
+          parse_token_response(response)
+        end
+
+        # Refresh access token using refresh token
+        # @param server_metadata [ServerMetadata] server metadata
+        # @param client_info [ClientInfo] client info
+        # @param token [Token] current token with refresh_token
+        # @param server_url [String] MCP server URL
+        # @return [Token, nil] new token or nil if refresh failed
+        def refresh_token(server_metadata, client_info, token, server_url)
+          return nil unless token.refresh_token
+
+          logger.debug("Refreshing access token")
+
+          params = build_refresh_params(client_info, token, server_url)
+          response = post_token_refresh(server_metadata, params)
+
+          # Return nil on error responses
+          return nil if response.is_a?(HTTPX::ErrorResponse)
+          return nil unless response.status == 200
+
+          parse_refresh_response(response, token)
+        rescue JSON::ParserError => e
+          logger.warn("Invalid token refresh response: #{e.message}")
+          nil
+        rescue HTTPX::Error => e
+          logger.warn("Network error during token refresh: #{e.message}")
+          nil
+        end
+
+        private
+
+        # Build parameters for authorization code exchange
+        # @param client_info [ClientInfo] client info
+        # @param code [String] authorization code
+        # @param pkce [PKCE] PKCE parameters
+        # @param redirect_uri [String] redirect URI
+        # @param server_url [String] MCP server URL
+        # @return [Hash] token exchange parameters
+        def build_auth_code_params(client_info, code, pkce, redirect_uri, server_url)
+          params = {
+            grant_type: "authorization_code",
+            code: code,
+            redirect_uri: redirect_uri,
+            client_id: client_info.client_id,
+            code_verifier: pkce.code_verifier,
+            resource: server_url
+          }
+
+          add_client_secret_if_needed(params, client_info)
+          params
+        end
+
+        # Build parameters for token refresh
+        # @param client_info [ClientInfo] client info
+        # @param token [Token] current token
+        # @param server_url [String] MCP server URL
+        # @return [Hash] refresh parameters
+        def build_refresh_params(client_info, token, server_url)
+          params = {
+            grant_type: "refresh_token",
+            refresh_token: token.refresh_token,
+            client_id: client_info.client_id,
+            resource: server_url
+          }
+
+          add_client_secret_if_needed(params, client_info)
+          params
+        end
+
+        # Add client secret to params if needed
+        # @param params [Hash] token request parameters
+        # @param client_info [ClientInfo] client info
+        def add_client_secret_if_needed(params, client_info)
+          return unless client_info.client_secret
+          return unless client_info.metadata.token_endpoint_auth_method == "client_secret_post"
+
+          params[:client_secret] = client_info.client_secret
+        end
+
+        # Post token exchange request
+        # @param server_metadata [ServerMetadata] server metadata
+        # @param params [Hash] form parameters
+        # @return [HTTPX::Response] HTTP response
+        def post_token_exchange(server_metadata, params)
+          http_client.post(
+            server_metadata.token_endpoint,
+            headers: { "Content-Type" => "application/x-www-form-urlencoded" },
+            form: params
+          )
+        end
+
+        # Post token refresh request
+        # @param server_metadata [ServerMetadata] server metadata
+        # @param params [Hash] form parameters
+        # @return [HTTPX::Response] HTTP response
+        def post_token_refresh(server_metadata, params)
+          response = http_client.post(
+            server_metadata.token_endpoint,
+            headers: { "Content-Type" => "application/x-www-form-urlencoded" },
+            form: params
+          )
+
+          if response.is_a?(HTTPX::ErrorResponse)
+            logger.warn("Token refresh failed: #{response.error&.message || 'Request failed'}")
+          elsif response.status != 200
+            logger.warn("Token refresh failed: HTTP #{response.status}")
+          end
+          response
+        end
+
+        # Retry token exchange if redirect URI mismatch detected
+        # @param response [HTTPX::Response] initial response
+        # @param server_metadata [ServerMetadata] server metadata
+        # @param params [Hash] exchange parameters
+        # @param registered_redirect_uri [String] registered redirect URI
+        # @return [HTTPX::Response] response (possibly retried)
+        def retry_if_redirect_mismatch(response, server_metadata, params, registered_redirect_uri)
+          # Don't retry on error responses
+          return response if response.is_a?(HTTPX::ErrorResponse)
+          return response if response.status == 200
+
+          redirect_hint = HttpResponseHandler.extract_redirect_mismatch(response.body.to_s)
+          return response unless redirect_hint
+          return response if redirect_hint[:expected] == registered_redirect_uri
+
+          logger.warn("Redirect URI mismatch, retrying with: #{redirect_hint[:expected]}")
+          params[:redirect_uri] = redirect_hint[:expected]
+          post_token_exchange(server_metadata, params)
+        end
+
+        # Validate token response
+        # @param response [HTTPX::Response, HTTPX::ErrorResponse] HTTP response
+        # @param context [String] context for error messages
+        # @raise [Errors::TransportError] if response is invalid
+        def validate_token_response!(response, context)
+          # Handle HTTPX ErrorResponse
+          if response.is_a?(HTTPX::ErrorResponse)
+            error_message = response.error&.message || "Request failed"
+            raise Errors::TransportError.new(message: "#{context} failed: #{error_message}")
+          end
+
+          return if response.status == 200
+
+          raise Errors::TransportError.new(
+            message: "#{context} failed: HTTP #{response.status}",
+            code: response.status
+          )
+        end
+
+        # Parse token response
+        # @param response [HTTPX::Response] HTTP response
+        # @return [Token] parsed token
+        def parse_token_response(response)
+          data = JSON.parse(response.body.to_s)
+          Token.new(
+            access_token: data["access_token"],
+            token_type: data["token_type"] || "Bearer",
+            expires_in: data["expires_in"],
+            scope: data["scope"],
+            refresh_token: data["refresh_token"]
+          )
+        end
+
+        # Parse refresh response, preserving old refresh token if not provided
+        # @param response [HTTPX::Response] HTTP response
+        # @param old_token [Token] previous token
+        # @return [Token] new token
+        def parse_refresh_response(response, old_token)
+          data = JSON.parse(response.body.to_s)
+          Token.new(
+            access_token: data["access_token"],
+            token_type: data["token_type"] || "Bearer",
+            expires_in: data["expires_in"],
+            scope: data["scope"],
+            refresh_token: data["refresh_token"] || old_token.refresh_token
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module RubyLLM
+  module MCP
+    module Auth
+      # Utility class for building OAuth URLs
+      # Handles discovery URLs, authorization URLs, and URL normalization
+      class UrlBuilder
+        # Build discovery URL for OAuth server metadata
+        # @param server_url [String] MCP server URL
+        # @param discovery_type [Symbol] :authorization_server or :protected_resource
+        # @return [String] discovery URL
+        def self.build_discovery_url(server_url, discovery_type = :authorization_server)
+          uri = URI.parse(server_url)
+
+          # Extract ONLY origin (scheme + host + port)
+          origin = "#{uri.scheme}://#{uri.host}"
+          origin += ":#{uri.port}" if uri.port && !default_port?(uri)
+
+          # Two discovery endpoints supported
+          endpoint = if discovery_type == :authorization_server
+                       "oauth-authorization-server"
+                     else
+                       "oauth-protected-resource"
+                     end
+
+          "#{origin}/.well-known/#{endpoint}"
+        end
+
+        # Build OAuth authorization URL
+        # @param authorization_endpoint [String] auth server endpoint
+        # @param client_id [String] client ID
+        # @param redirect_uri [String] redirect URI
+        # @param scope [String, nil] requested scope
+        # @param state [String] CSRF state
+        # @param pkce [PKCE] PKCE parameters
+        # @param resource [String] resource indicator (RFC 8707)
+        # @return [String] authorization URL
+        def self.build_authorization_url(authorization_endpoint, client_id, redirect_uri, scope, state, pkce, resource) # rubocop:disable Metrics/ParameterLists
+          params = {
+            response_type: "code",
+            client_id: client_id,
+            redirect_uri: redirect_uri,
+            scope: scope,
+            state: state, # CSRF protection
+            code_challenge: pkce.code_challenge,
+            code_challenge_method: pkce.code_challenge_method, # S256
+            resource: resource # RFC 8707 - Resource Indicators
+          }.compact
+
+          uri = URI.parse(authorization_endpoint)
+          uri.query = URI.encode_www_form(params)
+          uri.to_s
+        end
+
+        # Get authorization base URL from server URL
+        # @param server_url [String] MCP server URL
+        # @return [String] authorization base URL (scheme + host + port)
+        def self.get_authorization_base_url(server_url)
+          uri = URI.parse(server_url)
+          origin = "#{uri.scheme}://#{uri.host}"
+          origin += ":#{uri.port}" if uri.port && !default_port?(uri)
+          origin
+        end
+
+        # Check if port is default for scheme
+        # @param uri [URI] parsed URI
+        # @return [Boolean] true if default port
+        def self.default_port?(uri)
+          (uri.scheme == "http" && uri.port == 80) ||
+            (uri.scheme == "https" && uri.port == 443)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest/sha2"
+require "securerandom"
+require "time"
+
+module RubyLLM
+  module MCP
+    module Auth
+      # OAuth configuration constants
+      # Token refresh buffer time in seconds (5 minutes)
+      TOKEN_REFRESH_BUFFER = 300
+
+      # Default OAuth timeout in seconds (30 seconds)
+      DEFAULT_OAUTH_TIMEOUT = 30
+
+      # CSRF state parameter size in bytes (32 bytes)
+      CSRF_STATE_SIZE = 32
+
+      # PKCE code verifier size in bytes (32 bytes)
+      PKCE_VERIFIER_SIZE = 32
+
+      # Represents an OAuth 2.1 access token with expiration tracking
+      class Token
+        attr_reader :access_token, :token_type, :expires_in, :scope, :refresh_token, :expires_at
+
+        def initialize(access_token:, token_type: "Bearer", expires_in: nil, scope: nil, refresh_token: nil)
+          @access_token = access_token
+          @token_type = token_type
+          @expires_in = expires_in
+          @scope = scope
+          @refresh_token = refresh_token
+          @expires_at = expires_in ? Time.now + expires_in : nil
+        end
+
+        # Check if token has expired
+        # @return [Boolean] true if token is expired
+        def expired?
+          return false unless @expires_at
+
+          Time.now >= @expires_at
+        end
+
+        # Check if token expires soon (within configured buffer)
+        # This enables proactive token refresh
+        # @return [Boolean] true if token expires within the buffer period
+        def expires_soon?
+          return false unless @expires_at
+
+          Time.now >= (@expires_at - TOKEN_REFRESH_BUFFER)
+        end
+
+        # Format token for Authorization header
+        # @return [String] formatted as "Bearer {access_token}"
+        def to_header
+          "#{@token_type} #{@access_token}"
+        end
+
+        # Serialize token to hash
+        # @return [Hash] token data
+        def to_h
+          {
+            access_token: @access_token,
+            token_type: @token_type,
+            expires_in: @expires_in,
+            scope: @scope,
+            refresh_token: @refresh_token,
+            expires_at: @expires_at&.iso8601
+          }
+        end
+
+        # Deserialize token from hash
+        # @param data [Hash] token data
+        # @return [Token] new token instance
+        def self.from_h(data)
+          token = new(
+            access_token: data[:access_token] || data["access_token"],
+            token_type: data[:token_type] || data["token_type"] || "Bearer",
+            expires_in: data[:expires_in] || data["expires_in"],
+            scope: data[:scope] || data["scope"],
+            refresh_token: data[:refresh_token] || data["refresh_token"]
+          )
+
+          # Restore expires_at if present
+          expires_at_str = data[:expires_at] || data["expires_at"]
+          if expires_at_str
+            token.instance_variable_set(:@expires_at, Time.parse(expires_at_str))
+          end
+
+          token
+        end
+      end
+
+      # Client metadata for dynamic client registration (RFC 7591)
+      # Supports all optional parameters from the specification
+      class ClientMetadata
+        attr_reader :redirect_uris, :token_endpoint_auth_method, :grant_types, :response_types, :scope,
+                    :client_name, :client_uri, :logo_uri, :contacts, :tos_uri, :policy_uri,
+                    :jwks_uri, :jwks, :software_id, :software_version
+
+        def initialize( # rubocop:disable Metrics/ParameterLists
+          redirect_uris:,
+          token_endpoint_auth_method: "none",
+          grant_types: %w[authorization_code refresh_token],
+          response_types: ["code"],
+          scope: nil,
+          client_name: nil,
+          client_uri: nil,
+          logo_uri: nil,
+          contacts: nil,
+          tos_uri: nil,
+          policy_uri: nil,
+          jwks_uri: nil,
+          jwks: nil,
+          software_id: nil,
+          software_version: nil
+        )
+          @redirect_uris = redirect_uris
+          @token_endpoint_auth_method = token_endpoint_auth_method
+          @grant_types = grant_types
+          @response_types = response_types
+          @scope = scope
+          @client_name = client_name
+          @client_uri = client_uri
+          @logo_uri = logo_uri
+          @contacts = contacts
+          @tos_uri = tos_uri
+          @policy_uri = policy_uri
+          @jwks_uri = jwks_uri
+          @jwks = jwks
+          @software_id = software_id
+          @software_version = software_version
+        end
+
+        # Convert to hash for registration request
+        # @return [Hash] client metadata
+        def to_h
+          {
+            redirect_uris: @redirect_uris,
+            token_endpoint_auth_method: @token_endpoint_auth_method,
+            grant_types: @grant_types,
+            response_types: @response_types,
+            scope: @scope,
+            client_name: @client_name,
+            client_uri: @client_uri,
+            logo_uri: @logo_uri,
+            contacts: @contacts,
+            tos_uri: @tos_uri,
+            policy_uri: @policy_uri,
+            jwks_uri: @jwks_uri,
+            jwks: @jwks,
+            software_id: @software_id,
+            software_version: @software_version
+          }.compact
+        end
+      end
+
+      # Registered client information from authorization server
+      class ClientInfo
+        attr_reader :client_id, :client_secret, :client_id_issued_at, :client_secret_expires_at, :metadata
+
+        def initialize(client_id:, client_secret: nil, client_id_issued_at: nil, client_secret_expires_at: nil,
+                       metadata: nil)
+          @client_id = client_id
+          @client_secret = client_secret
+          @client_id_issued_at = client_id_issued_at
+          @client_secret_expires_at = client_secret_expires_at
+          @metadata = metadata
+        end
+
+        # Check if client secret has expired
+        # @return [Boolean] true if client secret is expired
+        def client_secret_expired?
+          return false unless @client_secret_expires_at
+
+          Time.now.to_i >= @client_secret_expires_at
+        end
+
+        # Serialize to hash
+        # @return [Hash] client info
+        def to_h
+          {
+            client_id: @client_id,
+            client_secret: @client_secret,
+            client_id_issued_at: @client_id_issued_at,
+            client_secret_expires_at: @client_secret_expires_at,
+            metadata: @metadata&.to_h
+          }
+        end
+
+        # Deserialize from hash
+        # @param data [Hash] client info data
+        # @return [ClientInfo] new instance
+        def self.from_h(data)
+          metadata_data = data[:metadata] || data["metadata"]
+          metadata = if metadata_data
+                       ClientMetadata.new(**metadata_data.transform_keys(&:to_sym))
+                     end
+
+          new(
+            client_id: data[:client_id] || data["client_id"],
+            client_secret: data[:client_secret] || data["client_secret"],
+            client_id_issued_at: data[:client_id_issued_at] || data["client_id_issued_at"],
+            client_secret_expires_at: data[:client_secret_expires_at] || data["client_secret_expires_at"],
+            metadata: metadata
+          )
+        end
+      end
+
+      # OAuth Authorization Server Metadata (RFC 8414)
+      class ServerMetadata
+        attr_reader :issuer, :authorization_endpoint, :token_endpoint, :registration_endpoint,
+                    :scopes_supported, :response_types_supported, :grant_types_supported
+
+        def initialize(issuer:, authorization_endpoint:, token_endpoint:, options: {})
+          @issuer = issuer
+          @authorization_endpoint = authorization_endpoint
+          @token_endpoint = token_endpoint
+          @registration_endpoint = options[:registration_endpoint] || options["registration_endpoint"]
+          @scopes_supported = options[:scopes_supported] || options["scopes_supported"]
+          @response_types_supported = options[:response_types_supported] || options["response_types_supported"]
+          @grant_types_supported = options[:grant_types_supported] || options["grant_types_supported"]
+        end
+
+        # Check if dynamic client registration is supported
+        # @return [Boolean] true if registration endpoint exists
+        def supports_registration?
+          !@registration_endpoint.nil?
+        end
+
+        # Serialize to hash
+        # @return [Hash] server metadata
+        def to_h
+          {
+            issuer: @issuer,
+            authorization_endpoint: @authorization_endpoint,
+            token_endpoint: @token_endpoint,
+            registration_endpoint: @registration_endpoint,
+            scopes_supported: @scopes_supported,
+            response_types_supported: @response_types_supported,
+            grant_types_supported: @grant_types_supported
+          }.compact
+        end
+
+        # Deserialize from hash
+        # @param data [Hash] server metadata
+        # @return [ServerMetadata] new instance
+        def self.from_h(data)
+          new(
+            issuer: data[:issuer] || data["issuer"],
+            authorization_endpoint: data[:authorization_endpoint] || data["authorization_endpoint"],
+            token_endpoint: data[:token_endpoint] || data["token_endpoint"],
+            registration_endpoint: data[:registration_endpoint] || data["registration_endpoint"],
+            scopes_supported: data[:scopes_supported] || data["scopes_supported"],
+            response_types_supported: data[:response_types_supported] || data["response_types_supported"],
+            grant_types_supported: data[:grant_types_supported] || data["grant_types_supported"]
+          )
+        end
+      end
+
+      # OAuth Protected Resource Metadata (RFC 9728)
+      # Used for authorization server delegation
+      class ResourceMetadata
+        attr_reader :resource, :authorization_servers
+
+        def initialize(resource:, authorization_servers:)
+          @resource = resource
+          @authorization_servers = authorization_servers
+        end
+
+        # Serialize to hash
+        # @return [Hash] resource metadata
+        def to_h
+          {
+            resource: @resource,
+            authorization_servers: @authorization_servers
+          }
+        end
+
+        # Deserialize from hash
+        # @param data [Hash] resource metadata
+        # @return [ResourceMetadata] new instance
+        def self.from_h(data)
+          new(
+            resource: data[:resource] || data["resource"],
+            authorization_servers: data[:authorization_servers] || data["authorization_servers"]
+          )
+        end
+      end
+
+      # Proof Key for Code Exchange (PKCE) implementation (RFC 7636)
+      # Required for OAuth 2.1 security
+      class PKCE
+        attr_reader :code_verifier, :code_challenge, :code_challenge_method
+
+        def initialize
+          @code_verifier = generate_code_verifier
+          @code_challenge = generate_code_challenge(@code_verifier)
+          @code_challenge_method = "S256" # SHA256 - only secure method for OAuth 2.1
+        end
+
+        # Serialize to hash
+        # @return [Hash] PKCE parameters
+        def to_h
+          {
+            code_verifier: @code_verifier,
+            code_challenge: @code_challenge,
+            code_challenge_method: @code_challenge_method
+          }
+        end
+
+        # Deserialize from hash
+        # @param data [Hash] PKCE data
+        # @return [PKCE] new instance
+        def self.from_h(data)
+          pkce = allocate
+          pkce.instance_variable_set(:@code_verifier, data[:code_verifier] || data["code_verifier"])
+          pkce.instance_variable_set(:@code_challenge, data[:code_challenge] || data["code_challenge"])
+          pkce.instance_variable_set(:@code_challenge_method,
+                                     data[:code_challenge_method] || data["code_challenge_method"] || "S256")
+          pkce
+        end
+
+        private
+
+        # Generate cryptographically secure code verifier
+        # @return [String] base64url-encoded random bytes
+        def generate_code_verifier
+          Base64.urlsafe_encode64(SecureRandom.random_bytes(PKCE_VERIFIER_SIZE), padding: false)
+        end
+
+        # Generate code challenge from verifier using SHA256
+        # @param verifier [String] code verifier
+        # @return [String] base64url-encoded SHA256 hash
+        def generate_code_challenge(verifier)
+          digest = Digest::SHA256.digest(verifier)
+          Base64.urlsafe_encode64(digest, padding: false)
+        end
+      end
+
+      # Factory method to create OAuth providers
+      # @param server_url [String] OAuth server URL
+      # @param type [Symbol] OAuth provider type (:standard or :browser)
+      # @param options [Hash] additional options passed to provider
+      # @return [OAuthProvider, BrowserOAuthProvider] OAuth provider instance
+      def self.create_oauth(server_url, type: :standard, **options)
+        case type
+        when :browser
+          BrowserOAuthProvider.new(server_url: server_url, **options)
+        when :standard
+          OAuthProvider.new(server_url: server_url, **options)
+        else
+          raise ArgumentError, "Unknown OAuth type: #{type}. Must be :standard or :browser"
+        end
+      end
+    end
+  end
+end