ruby-mcp-client 0.7.0 → 0.7.1

data/lib/mcp_client/auth.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'json'
+require 'base64'
+require 'digest'
+require 'securerandom'
+require 'time'
+
+module MCPClient
+  # OAuth 2.1 implementation for MCP client authentication
+  module Auth
+    # OAuth token model representing access/refresh tokens
+    class Token
+      attr_reader :access_token, :token_type, :expires_in, :scope, :refresh_token, :expires_at
+
+      # @param access_token [String] The access token
+      # @param token_type [String] Token type (default: "Bearer")
+      # @param expires_in [Integer, nil] Token lifetime in seconds
+      # @param scope [String, nil] Token scope
+      # @param refresh_token [String, nil] Refresh token for renewal
+      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 the token is expired
+      # @return [Boolean] true if token is expired
+      def expired?
+        return false unless @expires_at
+
+        Time.now >= @expires_at
+      end
+
+      # Check if the token is close to expiring (within 5 minutes)
+      # @return [Boolean] true if token expires soon
+      def expires_soon?
+        return false unless @expires_at
+
+        Time.now >= (@expires_at - 300) # 5 minutes buffer
+      end
+
+      # Convert token to authorization header value
+      # @return [String] Authorization header value
+      def to_header
+        "#{@token_type} #{@access_token}"
+      end
+
+      # Convert to hash for serialization
+      # @return [Hash] Hash representation
+      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
+
+      # Create 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']
+        )
+
+        # Set expires_at if provided
+        if (expires_at_str = data[:expires_at] || data['expires_at'])
+          token.instance_variable_set(:@expires_at, Time.parse(expires_at_str))
+        end
+
+        token
+      end
+    end
+
+    # OAuth client metadata for registration and authorization
+    class ClientMetadata
+      attr_reader :redirect_uris, :token_endpoint_auth_method, :grant_types, :response_types, :scope
+
+      # @param redirect_uris [Array<String>] List of valid redirect URIs
+      # @param token_endpoint_auth_method [String] Authentication method for token endpoint
+      # @param grant_types [Array<String>] Supported grant types
+      # @param response_types [Array<String>] Supported response types
+      # @param scope [String, nil] Requested scope
+      def initialize(redirect_uris:, token_endpoint_auth_method: 'none',
+                     grant_types: %w[authorization_code refresh_token],
+                     response_types: ['code'], scope: nil)
+        @redirect_uris = redirect_uris
+        @token_endpoint_auth_method = token_endpoint_auth_method
+        @grant_types = grant_types
+        @response_types = response_types
+        @scope = scope
+      end
+
+      # Convert to hash for HTTP requests
+      # @return [Hash] Hash representation
+      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
+        }.compact
+      end
+    end
+
+    # Registered OAuth client information
+    class ClientInfo
+      attr_reader :client_id, :client_secret, :client_id_issued_at, :client_secret_expires_at, :metadata
+
+      # @param client_id [String] OAuth client ID
+      # @param client_secret [String, nil] OAuth client secret (for confidential clients)
+      # @param client_id_issued_at [Integer, nil] Unix timestamp when client ID was issued
+      # @param client_secret_expires_at [Integer, nil] Unix timestamp when client secret expires
+      # @param metadata [ClientMetadata] Client metadata
+      def initialize(client_id:, metadata:, client_secret: nil, client_id_issued_at: nil,
+                     client_secret_expires_at: 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 is 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
+
+      # Convert to hash for serialization
+      # @return [Hash] Hash representation
+      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
+        }.compact
+      end
+
+      # Create client info from hash
+      # @param data [Hash] Client info data
+      # @return [ClientInfo] New client info instance
+      def self.from_h(data)
+        metadata_data = data[:metadata] || data['metadata'] || {}
+        metadata = build_metadata_from_hash(metadata_data)
+
+        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
+
+      # Build ClientMetadata from hash data
+      # @param metadata_data [Hash] Metadata hash
+      # @return [ClientMetadata] Client metadata instance
+      def self.build_metadata_from_hash(metadata_data)
+        ClientMetadata.new(
+          redirect_uris: metadata_data[:redirect_uris] || metadata_data['redirect_uris'] || [],
+          token_endpoint_auth_method: extract_auth_method(metadata_data),
+          grant_types: metadata_data[:grant_types] || metadata_data['grant_types'] ||
+                       %w[authorization_code refresh_token],
+          response_types: metadata_data[:response_types] || metadata_data['response_types'] || ['code'],
+          scope: metadata_data[:scope] || metadata_data['scope']
+        )
+      end
+
+      # Extract token endpoint auth method from metadata
+      # @param metadata_data [Hash] Metadata hash
+      # @return [String] Authentication method
+      def self.extract_auth_method(metadata_data)
+        metadata_data[:token_endpoint_auth_method] ||
+          metadata_data['token_endpoint_auth_method'] || 'none'
+      end
+    end
+
+    # OAuth authorization server metadata
+    class ServerMetadata
+      attr_reader :issuer, :authorization_endpoint, :token_endpoint, :registration_endpoint,
+                  :scopes_supported, :response_types_supported, :grant_types_supported
+
+      # @param issuer [String] Issuer identifier URL
+      # @param authorization_endpoint [String] Authorization endpoint URL
+      # @param token_endpoint [String] Token endpoint URL
+      # @param registration_endpoint [String, nil] Client registration endpoint URL
+      # @param scopes_supported [Array<String>, nil] Supported OAuth scopes
+      # @param response_types_supported [Array<String>, nil] Supported response types
+      # @param grant_types_supported [Array<String>, nil] Supported grant types
+      def initialize(issuer:, authorization_endpoint:, token_endpoint:, registration_endpoint: nil,
+                     scopes_supported: nil, response_types_supported: nil, grant_types_supported: nil)
+        @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
+      end
+
+      # Check if dynamic client registration is supported
+      # @return [Boolean] true if registration endpoint is available
+      def supports_registration?
+        !@registration_endpoint.nil?
+      end
+
+      # Convert to hash
+      # @return [Hash] Hash representation
+      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
+
+      # Create server metadata from hash
+      # @param data [Hash] Server metadata
+      # @return [ServerMetadata] New server metadata 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
+
+    # Protected resource metadata for authorization server discovery
+    class ResourceMetadata
+      attr_reader :resource, :authorization_servers
+
+      # @param resource [String] Resource server identifier
+      # @param authorization_servers [Array<String>] List of authorization server URLs
+      def initialize(resource:, authorization_servers:)
+        @resource = resource
+        @authorization_servers = authorization_servers
+      end
+
+      # Convert to hash
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          resource: @resource,
+          authorization_servers: @authorization_servers
+        }
+      end
+
+      # Create resource metadata from hash
+      # @param data [Hash] Resource metadata
+      # @return [ResourceMetadata] New resource metadata instance
+      def self.from_h(data)
+        new(
+          resource: data[:resource] || data['resource'],
+          authorization_servers: data[:authorization_servers] || data['authorization_servers']
+        )
+      end
+    end
+
+    # PKCE (Proof Key for Code Exchange) helper
+    class PKCE
+      attr_reader :code_verifier, :code_challenge, :code_challenge_method
+
+      # Generate PKCE parameters
+      def initialize
+        @code_verifier = generate_code_verifier
+        @code_challenge = generate_code_challenge(@code_verifier)
+        @code_challenge_method = 'S256'
+      end
+
+      private
+
+      # Generate a cryptographically random code verifier
+      # @return [String] Base64url-encoded code verifier
+      def generate_code_verifier
+        # Generate 32 random bytes (256 bits) and base64url encode
+        Base64.urlsafe_encode64(SecureRandom.random_bytes(32), 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
+  end
+end

data/lib/mcp_client/http_transport_base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'json_rpc_common'
+require_relative 'auth/oauth_provider'
 
 module MCPClient
   # Base module for HTTP-based JSON-RPC transports
@@ -172,18 +173,17 @@ module MCPClient
 
       begin
         response = conn.post(@endpoint) do |req|
-          # Apply all headers including custom ones
-          @headers.each { |k, v| req.headers[k] = v }
+          apply_request_headers(req, request)
           req.body = request.to_json
         end
 
         handle_http_error_response(response) unless response.success?
+        handle_successful_response(response, request)
 
         log_response(response)
         response
       rescue Faraday::UnauthorizedError, Faraday::ForbiddenError => e
-        error_status = e.response ? e.response[:status] : 'unknown'
-        raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{error_status}"
+        handle_auth_error(e)
       rescue Faraday::ConnectionFailed => e
         raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
       rescue Faraday::Error => e
@@ -191,6 +191,43 @@ module MCPClient
       end
     end
 
+    # Apply headers to the HTTP request (can be overridden by subclasses)
+    # @param req [Faraday::Request] HTTP request
+    # @param _request [Hash] JSON-RPC request
+    def apply_request_headers(req, _request)
+      # Apply all headers including custom ones
+      @headers.each { |k, v| req.headers[k] = v }
+
+      # Apply OAuth authorization if available
+      @logger.debug("OAuth provider present: #{@oauth_provider ? 'yes' : 'no'}")
+      @oauth_provider&.apply_authorization(req)
+    end
+
+    # Handle successful HTTP response (can be overridden by subclasses)
+    # @param response [Faraday::Response] HTTP response
+    # @param _request [Hash] JSON-RPC request
+    def handle_successful_response(response, _request)
+      # Default: no additional handling
+    end
+
+    # Handle authentication errors
+    # @param error [Faraday::UnauthorizedError, Faraday::ForbiddenError] Auth error
+    # @raise [MCPClient::Errors::ConnectionError] Connection error
+    def handle_auth_error(error)
+      # Handle OAuth authorization challenges
+      if error.response && @oauth_provider
+        resource_metadata = @oauth_provider.handle_unauthorized_response(error.response)
+        if resource_metadata
+          @logger.debug('Received OAuth challenge, discovered resource metadata')
+          # Re-raise the error to trigger OAuth flow in calling code
+          raise MCPClient::Errors::ConnectionError, "OAuth authorization required: HTTP #{error.response[:status]}"
+        end
+      end
+
+      error_status = error.response ? error.response[:status] : 'unknown'
+      raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{error_status}"
+    end
+
     # Handle HTTP error responses
     # @param response [Faraday::Response] the error response
     # @raise [MCPClient::Errors::ConnectionError] for auth errors

data/lib/mcp_client/oauth_client.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative 'auth/oauth_provider'
+require_relative 'server_http'
+require_relative 'server_streamable_http'
+
+module MCPClient
+  # Utility class for creating OAuth-enabled MCP clients
+  class OAuthClient
+    # Create an OAuth-enabled HTTP server
+    # @param server_url [String] The MCP server URL
+    # @param options [Hash] Configuration options
+    # @option options [String] :redirect_uri OAuth redirect URI (default: 'http://localhost:8080/callback')
+    # @option options [String, nil] :scope OAuth scope
+    # @option options [String] :endpoint JSON-RPC endpoint path (default: '/rpc')
+    # @option options [Hash] :headers Additional headers to include in requests
+    # @option options [Integer] :read_timeout Read timeout in seconds (default: 30)
+    # @option options [Integer] :retries Retry attempts on transient errors (default: 3)
+    # @option options [Numeric] :retry_backoff Base delay for exponential backoff (default: 1)
+    # @option options [String, nil] :name Optional name for this server
+    # @option options [Logger, nil] :logger Optional logger
+    # @option options [Object, nil] :storage Storage backend for OAuth tokens and client info
+    # @return [ServerHTTP] OAuth-enabled HTTP server
+    def self.create_http_server(server_url:, **options)
+      opts = default_server_options.merge(options)
+
+      oauth_provider = Auth::OAuthProvider.new(
+        server_url: server_url,
+        redirect_uri: opts[:redirect_uri],
+        scope: opts[:scope],
+        logger: opts[:logger],
+        storage: opts[:storage]
+      )
+
+      ServerHTTP.new(
+        base_url: server_url,
+        endpoint: opts[:endpoint],
+        headers: opts[:headers],
+        read_timeout: opts[:read_timeout],
+        retries: opts[:retries],
+        retry_backoff: opts[:retry_backoff],
+        name: opts[:name],
+        logger: opts[:logger],
+        oauth_provider: oauth_provider
+      )
+    end
+
+    # Create an OAuth-enabled Streamable HTTP server
+    # @param server_url [String] The MCP server URL
+    # @param options [Hash] Configuration options (same as create_http_server)
+    # @return [ServerStreamableHTTP] OAuth-enabled Streamable HTTP server
+    def self.create_streamable_http_server(server_url:, **options)
+      opts = default_server_options.merge(options)
+
+      oauth_provider = Auth::OAuthProvider.new(
+        server_url: server_url,
+        redirect_uri: opts[:redirect_uri],
+        scope: opts[:scope],
+        logger: opts[:logger],
+        storage: opts[:storage]
+      )
+
+      ServerStreamableHTTP.new(
+        base_url: server_url,
+        endpoint: opts[:endpoint],
+        headers: opts[:headers],
+        read_timeout: opts[:read_timeout],
+        retries: opts[:retries],
+        retry_backoff: opts[:retry_backoff],
+        name: opts[:name],
+        logger: opts[:logger],
+        oauth_provider: oauth_provider
+      )
+    end
+
+    # Perform OAuth authorization flow for a server
+    # This is a helper method that can be used to manually perform the OAuth flow
+    # @param server [ServerHTTP, ServerStreamableHTTP] The OAuth-enabled server
+    # @return [String] Authorization URL to redirect user to
+    # @raise [ArgumentError] if server doesn't have OAuth provider
+    def self.start_oauth_flow(server)
+      oauth_provider = server.instance_variable_get(:@oauth_provider)
+      raise ArgumentError, 'Server does not have OAuth provider configured' unless oauth_provider
+
+      oauth_provider.start_authorization_flow
+    end
+
+    # Complete OAuth authorization flow with authorization code
+    # @param server [ServerHTTP, ServerStreamableHTTP] The OAuth-enabled server
+    # @param code [String] Authorization code from callback
+    # @param state [String] State parameter from callback
+    # @return [Auth::Token] Access token
+    # @raise [ArgumentError] if server doesn't have OAuth provider
+    def self.complete_oauth_flow(server, code, state)
+      oauth_provider = server.instance_variable_get(:@oauth_provider)
+      raise ArgumentError, 'Server does not have OAuth provider configured' unless oauth_provider
+
+      oauth_provider.complete_authorization_flow(code, state)
+    end
+
+    # Check if server has a valid OAuth access token
+    # @param server [ServerHTTP, ServerStreamableHTTP] The OAuth-enabled server
+    # @return [Boolean] true if server has valid access token
+    def self.valid_token?(server)
+      oauth_provider = server.instance_variable_get(:@oauth_provider)
+      return false unless oauth_provider
+
+      token = oauth_provider.access_token
+      !!(token && !token.expired?)
+    end
+
+    private_class_method def self.default_server_options
+      {
+        redirect_uri: 'http://localhost:8080/callback',
+        scope: nil,
+        endpoint: '/rpc',
+        headers: {},
+        read_timeout: 30,
+        retries: 3,
+        retry_backoff: 1,
+        name: nil,
+        logger: nil,
+        storage: nil
+      }
+    end
+  end
+end