legate 0.1.0

data/lib/legate/auth/runner.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+require_relative 'coordinator'
+require_relative 'coordinators/oauth2_coordinator'
+require_relative 'coordinators/oidc_coordinator'
+require_relative 'coordinators/service_account_coordinator'
+require_relative 'token_store'
+require_relative 'token_manager'
+
+module Legate
+  module Auth
+    # Runner provides the execution environment for fiber-based authentication flows.
+    # It handles creating and managing authentication coordinators, running tasks within
+    # a fiber, and handling authentication requests/responses.
+    class Runner
+      # Initialize a new authentication runner
+      # @param session_service [Legate::SessionService::Base] The session service for persistence
+      # @param token_store [Legate::Auth::TokenStore, nil] Optional token store for caching tokens
+      # @param token_manager [Legate::Auth::TokenManager, nil] Optional token manager for lifecycle management
+      def initialize(session_service:, token_store: nil, token_manager: nil)
+        @session_service = session_service
+        @token_store = token_store || TokenStore.new(session_service)
+        @token_manager = token_manager || TokenManager.new(@token_store)
+        @active_coordinators = {}
+      end
+
+      # Run a task within a fiber with authentication handling
+      # @param task [Proc] The task to run
+      # @param context [Object] The context to run the task in (typically ToolContext)
+      # @yield [Hash, nil] Optional block to handle authentication requests
+      # @return [Object] The result of the task
+      # @raise [Legate::Auth::Error] If authentication fails
+      def run(task, context = nil, &auth_handler)
+        raise ArgumentError, 'Task must be a Proc or lambda' unless task.is_a?(Proc)
+
+        # Create a fiber for the task
+        task_fiber = Fiber.new do
+          # Make the auth_session method available in the context
+          if context && !context.respond_to?(:auth_session)
+            context.define_singleton_method(:auth_session) do |scheme, credential, **opts|
+              Fiber.yield({
+                            action: :authenticate,
+                            scheme: scheme,
+                            credential: credential,
+                            options: opts
+                          })
+            end
+          end
+
+          # Run the task
+          task.call
+        rescue StandardError => e
+          { error: e }
+        end
+
+        # Start the fiber
+        result = nil
+        loop do
+          # Resume the fiber and get the next result/yield
+          result = task_fiber.resume
+
+          # If the fiber has completed (not yielded), return the result
+          break unless task_fiber.alive?
+
+          # Handle authentication requests
+          if result.is_a?(Hash) && result[:action] == :authenticate
+            handle_authentication_request(result, task_fiber, &auth_handler)
+          else
+            # For other types of yields, just pass them to the handler if provided
+            response = auth_handler ? auth_handler.call(result) : nil
+            result = task_fiber.resume(response)
+          end
+        end
+
+        # If the result is an error hash, raise it
+        raise result[:error] if result.is_a?(Hash) && result[:error]
+
+        result
+      end
+
+      # Handle an authentication response from the client
+      # @param request_id [String] The request ID for the authentication flow
+      # @param response [Hash] The response from the client
+      # @return [Hash] The result of handling the response
+      def handle_auth_response(request_id, response)
+        coordinator = @active_coordinators[request_id]
+
+        unless coordinator
+          return {
+            status: :error,
+            error: "No active authentication flow found for request ID: #{request_id}"
+          }
+        end
+
+        begin
+          result = coordinator.resume(response)
+
+          if coordinator.complete?
+            if coordinator.success?
+              # Authentication completed successfully
+              @active_coordinators.delete(request_id)
+              {
+                status: :completed,
+                credential: result
+              }
+            else
+              # Authentication failed
+              @active_coordinators.delete(request_id)
+              {
+                status: :failed,
+                error: coordinator.error&.message || 'Authentication failed'
+              }
+            end
+          else
+            # Authentication is still in progress, return the next request
+            {
+              status: :pending,
+              request: result
+            }
+          end
+        rescue StandardError => e
+          @active_coordinators.delete(request_id)
+          {
+            status: :error,
+            error: "Error handling authentication response: #{e.message}"
+          }
+        end
+      end
+
+      # Cancel an active authentication flow
+      # @param request_id [String] The request ID for the authentication flow
+      # @param reason [String, nil] Optional reason for cancellation
+      # @return [Boolean] True if the flow was successfully cancelled
+      def cancel_auth_flow(request_id, reason = nil)
+        coordinator = @active_coordinators[request_id]
+
+        return false unless coordinator
+
+        result = coordinator.cancel(reason)
+        @active_coordinators.delete(request_id) if result
+        result
+      end
+
+      private
+
+      # Handle an authentication request yielded from a task fiber
+      # @param request [Hash] The authentication request
+      # @param task_fiber [Fiber] The task fiber
+      # @yield [Hash] Optional block to handle authentication requests
+      # @return [Legate::Auth::ExchangedCredential, nil] The result of authentication
+      def handle_authentication_request(request, task_fiber, &auth_handler)
+        scheme = request[:scheme]
+        credential = request[:credential]
+        options = request[:options] || {}
+
+        # Validate request
+        raise ArgumentError, "Invalid authentication scheme: #{scheme.class}" unless scheme.is_a?(Legate::Auth::Scheme)
+
+        raise ArgumentError, "Invalid credential: #{credential.class}" unless credential.is_a?(Legate::Auth::Credential)
+
+        # First, try to get an existing token from the token manager
+        token = @token_manager.get_token(scheme, credential)
+
+        # If we have a valid token, use it
+        return task_fiber.resume(token) if token && !token.expired?
+
+        # Create an appropriate coordinator based on the scheme type
+        coordinator = create_coordinator(scheme, credential, options)
+
+        # Start the authentication flow
+        auth_request = coordinator.start
+
+        # Store the coordinator for future responses
+        @active_coordinators[auth_request[:request_id]] = coordinator
+
+        # If a handler block is provided, use it
+        if auth_handler
+          # Pass the authentication request to the handler
+          response = auth_handler.call(auth_request)
+
+          # If the handler provided a response directly, process it
+          if response
+            result = handle_auth_response(auth_request[:request_id], response)
+
+            # Return the credential to the task fiber if authentication completed
+            return task_fiber.resume(result[:credential]) if result[:status] == :completed
+          end
+        end
+
+        # Otherwise, return authentication request to await client response
+        { request_id: auth_request[:request_id], status: :pending }
+      end
+
+      # Create an appropriate coordinator based on the scheme type
+      # @param scheme [Legate::Auth::Scheme] The authentication scheme
+      # @param credential [Legate::Auth::Credential] The credential
+      # @param options [Hash] Additional options for the coordinator
+      # @return [Legate::Auth::Coordinator] The appropriate coordinator
+      def create_coordinator(scheme, credential, options)
+        case scheme
+        when Legate::Auth::Schemes::OAuth2
+          Legate::Auth::Coordinators::OAuth2Coordinator.new(
+            scheme: scheme,
+            credential: credential,
+            session_service: @session_service,
+            token_store: @token_store,
+            timeout: options[:timeout],
+            redirect_uri: options[:redirect_uri]
+          )
+        when Legate::Auth::Schemes::OIDC
+          Legate::Auth::Coordinators::OIDCCoordinator.new(
+            scheme: scheme,
+            credential: credential,
+            session_service: @session_service,
+            token_store: @token_store,
+            timeout: options[:timeout],
+            redirect_uri: options[:redirect_uri]
+          )
+        when Legate::Auth::Schemes::ServiceAccount
+          Legate::Auth::Coordinators::ServiceAccountCoordinator.new(
+            scheme: scheme,
+            credential: credential,
+            session_service: @session_service,
+            token_store: @token_store,
+            timeout: options[:timeout]
+          )
+        # Add more coordinator types as needed for other schemes
+        else
+          raise NotImplementedError, "No coordinator available for scheme type: #{scheme.class}"
+        end
+      end
+
+      # Create a service account coordinator
+      # @param scheme [Legate::Auth::Schemes::ServiceAccount] The service account scheme
+      # @param credential [Legate::Auth::Credential] The credential with service account info
+      # @param options [Hash] Additional options for the coordinator
+      # @return [Legate::Auth::Coordinators::ServiceAccountCoordinator] The coordinator
+      def create_service_account_coordinator(scheme, credential, options = {})
+        raise ArgumentError, "Expected a ServiceAccount scheme, got #{scheme.class}" unless scheme.is_a?(Legate::Auth::Schemes::ServiceAccount)
+
+        raise ArgumentError, "Credential must have auth_type :service_account, got #{credential.auth_type}" unless credential.auth_type.to_sym == :service_account
+
+        Legate::Auth::Coordinators::ServiceAccountCoordinator.new(
+          scheme: scheme,
+          credential: credential,
+          session_service: @session_service,
+          token_store: @token_store,
+          timeout: options[:timeout]
+        )
+      end
+
+      # Authenticate using a service account
+      # @param scheme [Legate::Auth::Schemes::ServiceAccount] The service account scheme
+      # @param credential [Legate::Auth::Credential] The credential with service account info
+      # @param options [Hash] Additional options for the coordinator
+      # @return [Legate::Auth::ExchangedCredential] The authenticated credential
+      # @raise [Legate::Auth::Error] If authentication fails
+      def authenticate_with_service_account(scheme, credential, options = {})
+        # Create the coordinator
+        coordinator = create_service_account_coordinator(scheme, credential, options)
+
+        # Start the authentication flow
+        coordinator.start
+
+        # For service accounts, authentication is non-interactive, so the result should be available immediately
+        if coordinator.complete?
+          return coordinator.result if coordinator.success?
+
+          raise coordinator.error || Legate::Auth::Error.new('Service account authentication failed')
+
+        end
+
+        # This should never happen for service accounts
+        raise Legate::Auth::Error.new('Unexpected state: service account authentication requires interaction')
+      end
+    end
+  end
+end

data/lib/legate/auth/scheme.rb

@@ -0,0 +1,125 @@
+# File: lib/legate/auth/scheme.rb
+# frozen_string_literal: true
+
+require 'uri'
+require_relative 'url_guard'
+
+module Legate
+  module Auth
+    # Base class for all authentication schemes.
+    # Schemes provide logic for applying authentication to requests,
+    # refreshing tokens, and other operations specific to their authentication type.
+    class Scheme
+      # Get the type of authentication scheme
+      # @return [Symbol] The scheme type identifier
+      def scheme_type
+        raise NotImplementedError, "#{self.class} must implement #scheme_type"
+      end
+
+      # Apply authentication to a request
+      # @param request [Hash] The request hash to modify
+      # @param credential [Legate::Auth::Credential, Legate::Auth::ExchangedCredential] The credential to use
+      # @return [Hash] The modified request with authentication applied
+      def apply_to_request(request, credential)
+        raise NotImplementedError, "#{self.class} must implement #apply_to_request"
+      end
+
+      # Check if this scheme supports token refresh
+      # @return [Boolean] True if this scheme supports token refresh
+      def supports_refresh?
+        false
+      end
+
+      # Refresh an authentication token
+      # @param token [Legate::Auth::ExchangedCredential] The token to refresh
+      # @param credential [Legate::Auth::Credential] The credential containing refresh parameters
+      # @return [Legate::Auth::ExchangedCredential] The refreshed token
+      # @raise [Legate::Auth::TokenRefreshError] If the token cannot be refreshed
+      def refresh_token(token, credential)
+        raise NotImplementedError, "#{self.class} does not support token refresh"
+      end
+
+      # Exchange a credential for a token
+      # @param credential [Legate::Auth::Credential] The credential to exchange
+      # @return [Legate::Auth::ExchangedCredential] The exchanged token
+      # @raise [Legate::Auth::TokenExchangeError] If the credential cannot be exchanged
+      def exchange_token(credential)
+        raise NotImplementedError, "#{self.class} does not support token exchange"
+      end
+
+      # Revoke a token
+      # @param token [Legate::Auth::ExchangedCredential] The token to revoke
+      # @param credential [Legate::Auth::Credential] The credential for revocation parameters
+      # @return [Boolean] True if the token was revoked successfully
+      # @raise [Legate::Auth::TokenRevokeError] If the token cannot be revoked
+      def revoke_token(token, credential)
+        raise NotImplementedError, "#{self.class} does not support token revocation"
+      end
+
+      # Validates the scheme configuration
+      # @raise [Legate::Auth::SchemeValidationError] If the scheme configuration is invalid
+      # @abstract
+      def validate!
+        raise NotImplementedError, 'Subclasses must implement validate!'
+      end
+
+      # Returns a hash representation of the scheme
+      # @return [Hash] A hash containing the scheme configuration
+      # @abstract
+      def to_h
+        { type: scheme_type }
+      end
+
+      # Returns a string representation of the scheme
+      # @return [String] A string representing the scheme
+      def to_s
+        "#{self.class.name}<#{scheme_type}>"
+      end
+
+      # Builds an authorization URI for interactive authentication flows
+      # @param config [Legate::Auth::Config] The authentication configuration
+      # @param redirect_uri [String, nil] The redirect URI for the authorization request
+      # @param state [String, nil] A state parameter for the authorization request
+      # @return [String, nil] The authorization URI, or nil if not applicable
+      # @abstract
+      def build_authorization_uri(_config, _redirect_uri = nil, _state = nil)
+        nil # No-op in base class, override in subclasses that support interactive flows
+      end
+
+      # Checks if a response indicates an authentication error
+      # @param response [Hash] The HTTP response to check
+      # @return [Boolean] True if the response indicates an authentication error
+      def authentication_error?(response)
+        return false unless response.is_a?(Hash)
+
+        # HTTP status codes for auth errors (401 Unauthorized, 403 Forbidden)
+        [401, 403].include?(response[:status])
+      end
+
+      private
+
+      # Validates that a value is safe to use in an HTTP header.
+      # Rejects values containing CR, LF, or null bytes to prevent header injection.
+      # @param value [String] The header value to validate
+      # @param label [String] A label for error messages (e.g., "Bearer token")
+      # @raise [Legate::Auth::Error] If the value contains unsafe characters
+      def validate_header_value!(value, label = 'credential')
+        return unless value.is_a?(String)
+
+        return unless value.match?(/[\r\n\0]/)
+
+        raise Legate::Auth::Error, "#{label} contains invalid characters (CR, LF, or null byte)"
+      end
+
+      # Validates that an auth URL does not point to private/restricted network
+      # addresses. Delegates to the canonical {Legate::Auth::UrlGuard} so schemes
+      # and the web credential-test routes share one SSRF policy.
+      # @param url [String] The URL to validate
+      # @param label [String] A label for error messages
+      # @raise [Legate::Auth::Error] If the URL resolves to a restricted address
+      def validate_auth_url!(url, label: 'Auth URL')
+        Legate::Auth::UrlGuard.validate!(url, label: label)
+      end
+    end
+  end
+end

data/lib/legate/auth/schemes/api_key.rb

@@ -0,0 +1,212 @@
+# File: lib/legate/auth/schemes/api_key.rb
+# frozen_string_literal: true
+
+require_relative '../scheme'
+require_relative '../error'
+require_relative '../exchanged_credential'
+
+module Legate
+  module Auth
+    module Schemes
+      # API Key authentication scheme.
+      # This scheme applies an API key to requests via a header, query parameter, or cookie.
+      class ApiKey < Scheme
+        # Default header name for API key authentication
+        DEFAULT_HEADER_NAME = 'X-API-Key'
+
+        # Get the type of authentication scheme
+        # @return [Symbol] The scheme type identifier
+        def scheme_type
+          :api_key
+        end
+
+        # Apply authentication to a request
+        # @param request [Hash] The request hash to modify
+        # @param credential [Legate::Auth::Credential, Legate::Auth::ExchangedCredential] The credential to use
+        # @return [Hash] The modified request with authentication applied
+        # @raise [Legate::Auth::Error] If the API key cannot be applied
+        def apply_to_request(request, credential)
+          # Create a deep copy of the request to avoid modifying the original
+          request_copy = Marshal.load(Marshal.dump(request))
+
+          # Handle the case where we get a stack object from Excon
+          if request_copy.is_a?(Hash)
+            if request_copy[:stack]
+              # Extract the data from stack (Excon middleware format)
+              %i[scheme method path host port query].each do |key|
+                request_copy[key] = request_copy[:stack][key] if request_copy[:stack][key] && !request_copy[key]
+              end
+            end
+
+            # Ensure headers hash exists
+            request_copy[:headers] ||= {}
+          end
+
+          # Extract the API key from the credential
+          api_key = extract_api_key(credential)
+          raise Legate::Auth::Error, 'API key not found in credential' unless api_key
+
+          # Get parameters for applying the API key
+          location = credential[:location] || 'header'
+          name = credential[:name] || DEFAULT_HEADER_NAME
+
+          # Apply the API key based on location
+          case location.to_s.downcase
+          when 'header'
+            apply_to_header(request_copy, name, api_key)
+          when 'query', 'querystring'
+            apply_to_query(request_copy, name, api_key)
+          when 'cookie'
+            apply_to_cookie(request_copy, name, api_key)
+          else
+            raise Legate::Auth::Error, "Unsupported API key location: #{location}"
+          end
+        end
+
+        # Exchange a credential for a token
+        # @param credential [Legate::Auth::Credential] The credential to exchange
+        # @return [Legate::Auth::ExchangedCredential] The exchanged token
+        def exchange_token(credential)
+          # For API keys, we simply create a "token" that wraps the API key
+          # This is useful for token management consistency
+          api_key = extract_api_key(credential)
+          raise Legate::Auth::TokenExchangeError, 'API key not found in credential' unless api_key
+
+          # Create a simple exchanged credential that never expires
+          Legate::Auth::ExchangedCredential.new(
+            auth_type: :api_key,
+            api_key: api_key,
+            location: credential[:location] || 'header',
+            name: credential[:name] || DEFAULT_HEADER_NAME
+          )
+        end
+
+        # Get hash representation of the scheme
+        # @return [Hash] Scheme configuration as a hash
+        def to_h
+          {
+            type: scheme_type
+          }
+        end
+
+        private
+
+        # Extract the API key from a credential
+        # @param credential [Legate::Auth::Credential, Legate::Auth::ExchangedCredential] The credential
+        # @return [String, nil] The API key or nil if not found
+        def extract_api_key(credential)
+          # First try api_key
+          return credential[:api_key] if credential[:api_key]
+
+          # Next try key
+          return credential[:key] if credential[:key]
+
+          # Finally try token
+          credential[:token]
+        end
+
+        # Apply the API key to a request header
+        # @param request [Hash] The request to modify
+        # @param name [String] The header name
+        # @param api_key [String] The API key
+        # @return [Hash] The modified request
+        def apply_to_header(request, name, api_key)
+          validate_header_value!(api_key, 'API key')
+          validate_header_value!(name, 'Header name')
+          request[:headers] ||= {}
+          request[:headers][name] = api_key
+          request
+        end
+
+        # Apply the API key to a request query parameter
+        # @param request [Hash] The request to modify
+        # @param name [String] The parameter name
+        # @param api_key [String] The API key
+        # @return [Hash] The modified request
+        def apply_to_query(request, name, api_key)
+          # Initialize headers if not present
+          request[:headers] ||= {}
+
+          # The proper way to handle query parameters depends on the format
+          # expected by the HTTP client library
+
+          # Handle simple URL case
+          if request[:url]
+            # Properly append the query parameter
+            separator = request[:url].include?('?') ? '&' : '?'
+            request[:url] = "#{request[:url]}#{separator}#{name}=#{api_key}"
+          end
+
+          # Handle query param hash (used by Excon and other libraries)
+          if request[:query].is_a?(Hash)
+            # Simply add the param to the hash
+            request[:query][name] = api_key
+          elsif request[:query].is_a?(String)
+            # Append to existing query string
+            separator = request[:query].empty? ? '' : '&'
+            request[:query] = "#{request[:query]}#{separator}#{name}=#{api_key}"
+          elsif request[:query].nil?
+            # Create a new query hash
+            request[:query] = { name => api_key }
+          end
+
+          # Also update the URL with query parameters for debugging
+          if !request[:url] && (request[:scheme] || request[:host] || request[:path])
+            # Build the URL from components for reference
+            scheme = request[:scheme] || 'https'
+            host = request[:host] || 'example.com'
+            path = request[:path] || '/'
+            port = request[:port]
+
+            # Construct URL from components
+            port_part = port ? ":#{port}" : ''
+            url = "#{scheme}://#{host}#{port_part}#{path}"
+
+            # Add query string if present
+            if request[:query]
+              query_str = if request[:query].is_a?(Hash)
+                            params = []
+                            request[:query].each do |k, v|
+                              params << "#{k}=#{v}"
+                            end
+                            params.join('&')
+                          else
+                            request[:query].to_s
+                          end
+
+              url += "?#{query_str}" unless query_str.empty?
+            end
+
+            request[:url] = url
+          end
+
+          request
+        end
+
+        # Apply the API key to a request cookie
+        # @param request [Hash] The request to modify
+        # @param name [String] The cookie name
+        # @param api_key [String] The API key
+        # @return [Hash] The modified request
+        def apply_to_cookie(request, name, api_key)
+          validate_header_value!(api_key, 'API key (cookie)')
+          validate_header_value!(name, 'Cookie name')
+          # Initialize headers if not present
+          request[:headers] ||= {}
+
+          # Construct the cookie
+          cookie_value = "#{name}=#{api_key}"
+
+          # Append to existing cookie or set new one
+          request[:headers]['Cookie'] = if request[:headers]['Cookie'] && !request[:headers]['Cookie'].empty?
+                                          "#{request[:headers]['Cookie']}; #{cookie_value}"
+                                        else
+                                          cookie_value
+                                        end
+
+          request
+        end
+      end
+    end
+  end
+end