legate 0.1.0

data/lib/legate/auth/coordinators/oidc_coordinator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../coordinator'
+require_relative '../schemes/openid_connect'
+require_relative 'oauth2_coordinator'
+
+module Legate
+  module Auth
+    module Coordinators
+      # OIDCCoordinator handles the interactive OpenID Connect authentication flow using fibers.
+      # It extends the OAuth2Coordinator with OIDC-specific functionality.
+      class OIDCCoordinator < OAuth2Coordinator
+        # Initialize a new OIDC coordinator
+        # @param scheme [Legate::Auth::Schemes::OpenIDConnect] The OIDC scheme
+        # @param credential [Legate::Auth::Credential] The credential with client information
+        # @param session_service [Legate::SessionService::Base] The session service
+        # @param token_store [Legate::Auth::TokenStore, nil] Optional token store
+        # @param timeout [Integer, nil] Optional timeout in seconds
+        # @param redirect_uri [String, nil] Optional redirect URI
+        def initialize(scheme:, credential:, session_service:, token_store: nil, timeout: DEFAULT_TIMEOUT, redirect_uri: nil)
+          super
+
+          raise ArgumentError, "Expected an OIDC scheme, got #{scheme.class}" unless scheme.is_a?(Legate::Auth::Schemes::OIDC)
+
+          return if credential.auth_type == :oidc
+          # Allow OAuth2 credentials as they are compatible
+          return if credential.auth_type == :oauth2
+
+          raise ArgumentError, "Credential must have auth_type :oidc or :oauth2, got #{credential.auth_type}"
+        end
+
+        protected
+
+        # Implement the OIDC authentication flow, extending the OAuth2 flow
+        # @return [Legate::Auth::ExchangedCredential] The authenticated credential
+        # @raise [Legate::Auth::Error] If authentication fails
+        def authenticate
+          # Call the parent (OAuth2) authentication flow first
+          oauth2_result = super
+
+          # For OIDC, we may want to request the userinfo endpoint
+          # if the ID token doesn't have all needed claims
+          if @scheme.should_fetch_userinfo? && oauth2_result
+            fetch_userinfo(oauth2_result)
+          else
+            oauth2_result
+          end
+        end
+
+        private
+
+        # Fetch additional user information using the userinfo endpoint
+        # @param token [Legate::Auth::ExchangedCredential] The token with access_token
+        # @return [Legate::Auth::ExchangedCredential] The token with added userinfo
+        # @raise [Legate::Auth::Error] If userinfo fetch fails
+        def fetch_userinfo(token)
+          # Fetch userinfo using the access token
+          userinfo = @scheme.fetch_userinfo(token)
+
+          # Add the userinfo to the token metadata
+          token.with(
+            metadata: (token.metadata || {}).merge(userinfo: userinfo)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/legate/auth/coordinators/service_account_coordinator.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative '../coordinator'
+require_relative '../schemes/service_account'
+require_relative '../config'
+
+module Legate
+  module Auth
+    module Coordinators
+      # ServiceAccountCoordinator handles non-interactive service account authentication
+      # with automatic token exchange and refresh. Unlike OAuth2 coordinators, service
+      # account authentication does not require user interaction.
+      class ServiceAccountCoordinator < Coordinator
+        # Authentication steps for Service Accounts
+        module Steps
+          TOKEN_EXCHANGE = :token_exchange
+          TOKEN_REFRESH = :token_refresh
+        end
+
+        # Initialize a new Service Account coordinator
+        # @param scheme [Legate::Auth::Schemes::ServiceAccount] The Service Account scheme
+        # @param credential [Legate::Auth::Credential] The credential with service account information
+        # @param session_service [Legate::SessionService::Base] The session service
+        # @param token_store [Legate::Auth::TokenStore, nil] Optional token store
+        # @param timeout [Integer, nil] Optional timeout in seconds
+        def initialize(scheme:, credential:, session_service:, token_store: nil, timeout: DEFAULT_TIMEOUT)
+          super(scheme: scheme, credential: credential, session_service: session_service, token_store: token_store, timeout: timeout)
+
+          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
+
+          @current_step = Steps::TOKEN_EXCHANGE
+        end
+
+        protected
+
+        # Implement the Service Account authentication flow
+        # @return [Legate::Auth::ExchangedCredential] The authenticated credential
+        # @raise [Legate::Auth::Error] If authentication fails
+        def authenticate
+          # Service account authentication is non-interactive, so we just exchange tokens
+          @current_step = Steps::TOKEN_EXCHANGE
+          exchanged_token = exchange_token
+
+          # Store the token if we have a token store
+          store_token(exchanged_token) if @token_store
+
+          exchanged_token
+        end
+
+        # Refresh an existing token
+        # @param token [Legate::Auth::ExchangedCredential] The token to refresh
+        # @return [Legate::Auth::ExchangedCredential] The refreshed token
+        # @raise [Legate::Auth::TokenRefreshError] If token refresh fails
+        def refresh(token)
+          @current_step = Steps::TOKEN_REFRESH
+
+          # For service accounts, we get a new token rather than refreshing the existing one
+          refreshed_token = @scheme.refresh_token(token, @credential)
+
+          # Store the refreshed token if we have a token store
+          store_token(refreshed_token) if @token_store
+
+          refreshed_token
+        end
+
+        private
+
+        # Exchange for a token
+        # @return [Legate::Auth::ExchangedCredential] The exchanged token
+        # @raise [Legate::Auth::TokenExchangeError] If token exchange fails
+        def exchange_token
+          # Create a config for token exchange, if needed by the scheme
+          auth_config = Legate::Auth::Config.new(
+            scheme: @scheme,
+            credential: @credential,
+            options: { request_id: @request_id }
+          )
+
+          # Exchange for tokens using the scheme
+          # Some service account implementations might need the config, others might not
+          if @scheme.method(:exchange_token).arity == 2
+            @scheme.exchange_token(auth_config, @credential)
+          else
+            @scheme.exchange_token(@credential)
+          end
+        end
+
+        # Store a token in the token store
+        # @param token [Legate::Auth::ExchangedCredential] The token to store
+        def store_token(token)
+          return unless @token_store && token
+
+          # Generate a key for the token
+          key = generate_token_key
+
+          # Store the token with the generated key
+          @token_store.store(key, token)
+        end
+
+        # Generate a key for storing the token
+        # @return [String] The generated key
+        def generate_token_key
+          # Create a base key using the scheme type, client email, and scopes
+          base_key = "#{@scheme.scheme_type}"
+
+          # Add client email if available
+          base_key += ":#{@credential[:client_email]}" if @credential[:client_email]
+
+          # Add scopes if available
+          base_key += ":#{@scheme.scopes.join(',')}" if @scheme.scopes && !@scheme.scopes.empty?
+
+          # Add audience if available and scopes aren't set
+          base_key += ":#{@scheme.audience}" if @scheme.audience && (@scheme.scopes.nil? || @scheme.scopes.empty?)
+
+          base_key
+        end
+      end
+    end
+  end
+end

data/lib/legate/auth/credential.rb

@@ -0,0 +1,157 @@
+# File: lib/legate/auth/credential.rb
+# frozen_string_literal: true
+
+module Legate
+  module Auth
+    # Represents authentication credentials required by different schemes.
+    # Handles different types of credentials such as API keys, OAuth2 client credentials,
+    # service account keys, and more.
+    #
+    # @example API Key credential
+    #   credential = Legate::Auth::Credential.new(
+    #     auth_type: :api_key,
+    #     api_key: 'my-api-key'
+    #   )
+    #
+    # @example OAuth2 credential with environment variable
+    #   credential = Legate::Auth::Credential.new(
+    #     auth_type: :oauth2,
+    #     client_id: 'my-client-id',
+    #     client_secret: 'ENV:MY_CLIENT_SECRET'
+    #   )
+    class Credential
+      # Valid credential types
+      VALID_TYPES = %i[api_key oauth2 oidc service_account google_service_account http_bearer basic].freeze
+
+      # Prefix for environment variable references
+      ENV_PREFIX = 'ENV:'
+
+      # @return [Symbol] The type of authentication
+      attr_reader :auth_type
+
+      # Initialize a new credential
+      # @param auth_type [Symbol] The type of authentication (:api_key, :oauth2, :oidc, :service_account, :http_bearer)
+      # @param kwargs [Hash] Additional attributes for the specific auth type
+      # @raise [Legate::Auth::CredentialError] If the credential is invalid
+      def initialize(auth_type:, **kwargs)
+        @auth_type = auth_type.to_sym
+        @attributes = kwargs
+
+        validate_auth_type!
+        validate_required_attributes!
+      end
+
+      # Get an attribute value
+      # @param name [Symbol, String] The attribute name
+      # @param resolve_env [Boolean] Whether to resolve environment variables
+      # @return [Object, nil] The attribute value, or nil if not present
+      # @raise [Legate::Auth::EnvironmentVariableNotFoundError] If an environment variable is not found
+      def [](name, resolve_env: true)
+        attr_name = name.to_sym
+        value = @attributes[attr_name]
+
+        if resolve_env && value.is_a?(String) && value.start_with?(ENV_PREFIX)
+          resolve_environment_variable(value)
+        else
+          value
+        end
+      end
+
+      # Set an attribute value
+      # @param name [Symbol, String] The attribute name
+      # @param value [Object] The attribute value
+      def []=(name, value)
+        @attributes[name.to_sym] = value
+      end
+
+      # Convert to a hash
+      # @param resolve_env [Boolean] Whether to resolve environment variables
+      # @return [Hash] A hash representation of the credential
+      def to_h(resolve_env: false)
+        result = { auth_type: @auth_type }
+
+        @attributes.each do |key, value|
+          result[key] = if resolve_env && value.is_a?(String) && value.start_with?(ENV_PREFIX)
+                          resolve_environment_variable(value)
+                        else
+                          value
+                        end
+        end
+
+        result
+      end
+
+      # Check if the credential has an attribute
+      # @param name [Symbol, String] The attribute name
+      # @return [Boolean] True if the attribute exists
+      def has_attribute?(name)
+        @attributes.key?(name.to_sym)
+      end
+
+      private
+
+      # Validate the authentication type
+      # @raise [Legate::Auth::CredentialError] If the authentication type is invalid
+      def validate_auth_type!
+        return if VALID_TYPES.include?(@auth_type)
+
+        raise Legate::Auth::CredentialError,
+              "Invalid auth_type: #{@auth_type}. Must be one of: #{VALID_TYPES.join(', ')}"
+      end
+
+      # Validate required attributes based on the authentication type
+      # @raise [Legate::Auth::CredentialError] If required attributes are missing
+      def validate_required_attributes!
+        required_attrs = required_attributes_for_type
+        missing_attrs = required_attrs.reject { |attr| @attributes.key?(attr) }
+
+        return if missing_attrs.empty?
+
+        raise Legate::Auth::CredentialError,
+              "Missing required attributes for #{@auth_type}: #{missing_attrs.join(', ')}"
+      end
+
+      # Required attributes based on the authentication type
+      # @return [Array<Symbol>] The required attributes
+      def required_attributes_for_type
+        case @auth_type
+        when :api_key
+          [:api_key]
+        when :oauth2
+          [:client_id]
+        when :oidc
+          [:client_id]
+        when :service_account
+          # Allow either service_account_key or service_account_key_file
+          return [] if @attributes.key?(:service_account_key) || @attributes.key?(:service_account_key_file)
+
+          [:service_account_key]
+        when :google_service_account
+          # Allow either service_account_key or service_account_key_file
+          return [] if @attributes.key?(:service_account_key) || @attributes.key?(:service_account_key_file)
+
+          [:service_account_key]
+        when :http_bearer
+          [:bearer_token]
+        when :basic
+          %i[username password]
+        else
+          []
+        end
+      end
+
+      # Resolve an environment variable reference
+      # @param value [String] The environment variable reference (e.g., "ENV:VARIABLE_NAME")
+      # @return [String] The resolved value
+      # @raise [Legate::Auth::EnvironmentVariableNotFoundError] If the environment variable is not found
+      def resolve_environment_variable(value)
+        env_name = value[ENV_PREFIX.length..-1]
+        env_value = ENV[env_name]
+
+        raise Legate::Auth::EnvironmentVariableNotFoundError, env_name if env_value.nil? || env_value.empty?
+
+        env_value
+      end
+    end
+  end
+end

data/lib/legate/auth/encryption.rb

@@ -0,0 +1,108 @@
+# File: lib/legate/auth/encryption.rb
+# frozen_string_literal: true
+
+module Legate
+  module Auth
+    # Provides encryption and decryption utilities for sensitive authentication data.
+    # Uses the rbnacl gem for authenticated encryption.
+    module Encryption
+      # Environment variable name for the encryption key
+      ENV_KEY_NAME = 'LEGATE_AUTH_ENCRYPTION_KEY'
+
+      # Header added to encrypted data for identification
+      ENCRYPTION_HEADER = 'LGTAUTH'
+
+      class << self
+        # Encrypts sensitive data
+        # @param data [String] The data to encrypt
+        # @param key [String, nil] The encryption key (defaults to the key from environment)
+        # @return [String] The encrypted data in Base64 format with header
+        # @raise [LoadError] If the rbnacl gem is not available
+        # @raise [ArgumentError] If the encryption key is not available
+        def encrypt(data, key = nil)
+          require_rbnacl
+          encryption_key = key || get_encryption_key
+
+          require 'base64'
+          box = create_box(encryption_key)
+          encrypted = box.encrypt(data.to_s)
+          "#{ENCRYPTION_HEADER}#{Base64.strict_encode64(encrypted)}"
+        end
+
+        # Decrypts sensitive data
+        # @param encrypted_data [String] The encrypted data to decrypt
+        # @param key [String, nil] The encryption key (defaults to the key from environment)
+        # @return [String] The decrypted data
+        # @raise [LoadError] If the rbnacl gem is not available
+        # @raise [ArgumentError] If the data is not in the expected format or the key is invalid
+        def decrypt(encrypted_data, key = nil)
+          require_rbnacl
+          encryption_key = key || get_encryption_key
+
+          # Check format and remove header
+          raise ArgumentError, 'Invalid encrypted data format' unless encrypted_data.to_s.start_with?(ENCRYPTION_HEADER)
+
+          encoded = encrypted_data.to_s[ENCRYPTION_HEADER.length..-1]
+          require 'base64'
+          encrypted = Base64.strict_decode64(encoded)
+
+          box = create_box(encryption_key)
+          box.decrypt(encrypted)
+        rescue RbNaCl::CryptoError => e
+          raise ArgumentError, "Decryption failed: #{e.message}"
+        rescue ArgumentError => e
+          raise ArgumentError, "Invalid Base64 encoding: #{e.message}"
+        end
+
+        # Generates a new random encryption key
+        # @return [String] A new encryption key in Base64 format
+        # @raise [LoadError] If the rbnacl gem is not available
+        def generate_key
+          require_rbnacl
+          require 'base64'
+          raw_key = RbNaCl::Random.random_bytes(RbNaCl::SecretBox.key_bytes)
+          Base64.strict_encode64(raw_key)
+        end
+
+        # Checks if the encrypted data is in the expected format
+        # @param data [String] The data to check
+        # @return [Boolean] True if the data appears to be encrypted
+        def encrypted?(data)
+          data.to_s.start_with?(ENCRYPTION_HEADER)
+        end
+
+        private
+
+        # Gets the encryption key from the environment or configuration
+        # @return [String] The encryption key in raw binary format
+        # @raise [ArgumentError] If the encryption key is not available
+        def get_encryption_key
+          env_key = ENV[ENV_KEY_NAME]
+          raise ArgumentError, "Encryption key not found. Set #{ENV_KEY_NAME} environment variable." unless env_key
+
+          require 'base64'
+          begin
+            Base64.strict_decode64(env_key)
+          rescue ArgumentError
+            raise ArgumentError, 'Invalid encryption key format. Must be Base64-encoded.'
+          end
+        end
+
+        # Creates a SimpleBox from the encryption key
+        # @param key [String] The encryption key in raw binary format
+        # @return [RbNaCl::SimpleBox] A box for encryption/decryption
+        def create_box(key)
+          RbNaCl::SimpleBox.from_secret_key(key)
+        end
+
+        # Ensures that the rbnacl gem is available
+        # @raise [LoadError] If the rbnacl gem is not available
+        def require_rbnacl
+          require 'rbnacl'
+        rescue LoadError
+          raise LoadError, "rbnacl gem is required for encryption. Add it to your Gemfile: gem 'rbnacl'"
+        end
+      end
+    end
+  end
+end

data/lib/legate/auth/error.rb

@@ -0,0 +1,94 @@
+# File: lib/legate/auth/error.rb
+# frozen_string_literal: true
+
+module Legate
+  module Auth
+    # Base class for all authentication-related errors
+    class Error < Legate::Error
+      # @param message [String] The error message
+      # @param cause [Exception, nil] The underlying exception that caused this error
+      def initialize(message = nil, cause = nil)
+        message = "Authentication error#{": #{message}" if message}"
+        super(message)
+        set_backtrace(cause.backtrace) if cause && cause.backtrace
+      end
+    end
+
+    # Raised when authentication configuration is invalid
+    class ConfigurationError < Error
+      def initialize(message = nil, cause = nil)
+        super(message || 'Invalid authentication configuration', cause)
+      end
+    end
+
+    # Raised when a token exchange operation fails
+    class TokenExchangeError < Error
+      # @param message [String] The error message
+      # @param provider_error [String, nil] Error information from the provider
+      # @param cause [Exception, nil] The underlying exception that caused this error
+      def initialize(message = nil, provider_error = nil, cause = nil)
+        error_message = message || 'Token exchange failed'
+        error_message = "#{error_message}: #{provider_error}" if provider_error
+        super(error_message, cause)
+      end
+    end
+
+    # Raised when a token refresh operation fails
+    class TokenRefreshError < Error
+      # @param message [String] The error message
+      # @param provider_error [String, nil] Error information from the provider
+      # @param cause [Exception, nil] The underlying exception that caused this error
+      def initialize(message = nil, provider_error = nil, cause = nil)
+        error_message = message || 'Token refresh failed'
+        error_message = "#{error_message}: #{provider_error}" if provider_error
+        super(error_message, cause)
+      end
+    end
+
+    # Raised when a token revocation operation fails
+    class TokenRevocationError < Error
+      # @param message [String] The error message
+      # @param provider_error [String, nil] Error information from the provider
+      # @param cause [Exception, nil] The underlying exception that caused this error
+      def initialize(message = nil, provider_error = nil, cause = nil)
+        error_message = message || 'Token revocation failed'
+        error_message = "#{error_message}: #{provider_error}" if provider_error
+        super(error_message, cause)
+      end
+    end
+
+    # Raised when an authentication provider returns an error
+    class ProviderError < Error
+      # @param message [String] The error message
+      # @param provider_error [String, nil] Error information from the provider
+      # @param cause [Exception, nil] The underlying exception that caused this error
+      def initialize(message = nil, provider_error = nil, cause = nil)
+        error_message = message || 'Authentication provider error'
+        error_message = "#{error_message}: #{provider_error}" if provider_error
+        super(error_message, cause)
+      end
+    end
+
+    # Raised when credentials are missing or invalid
+    class CredentialError < Error
+      def initialize(message = nil, cause = nil)
+        super(message || 'Invalid or missing credentials', cause)
+      end
+    end
+
+    # Raised when an environment variable used for credentials is not found
+    class EnvironmentVariableNotFoundError < CredentialError
+      # @param var_name [String] The name of the environment variable
+      def initialize(var_name, cause = nil)
+        super("Environment variable not found: #{var_name}", cause)
+      end
+    end
+
+    # Raised when a scheme validation fails
+    class SchemeValidationError < ConfigurationError
+      def initialize(message = nil, cause = nil)
+        super(message || 'Invalid authentication scheme configuration', cause)
+      end
+    end
+  end
+end