a2a-ruby 1.0.0

data/lib/a2a/client/auth/interceptor.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require_relative "oauth2"
+require_relative "jwt"
+require_relative "api_key"
+
+##
+# Authentication interceptor for automatic token handling
+#
+# Provides a unified interface for applying different authentication
+# strategies to HTTP requests, with automatic token refresh and
+# error handling.
+#
+module A2A
+  module Client
+    module Auth
+      class Interceptor
+        attr_reader :strategy, :auto_retry
+
+        ##
+        # Initialize authentication interceptor
+        #
+        # @param strategy [Object] Authentication strategy (OAuth2, JWT, ApiKey, etc.)
+        # @param auto_retry [Boolean] Whether to automatically retry on auth failures
+        def initialize(strategy, auto_retry: true)
+          @strategy = strategy
+          @auto_retry = auto_retry
+          @retry_mutex = Mutex.new
+        end
+
+        ##
+        # Middleware call method for Faraday
+        #
+        # @param request [Object] The request object
+        # @param context [Hash] Request context
+        # @param next_middleware [Proc] Next middleware in chain
+        # @return [Object] Response from next middleware
+        def call(request, context, next_middleware)
+          # Apply authentication to the request
+          apply_authentication(request)
+
+          # Execute the request
+          begin
+            response = next_middleware.call(request, context)
+
+            # Check for authentication errors and retry if configured
+            if authentication_error?(response) && @auto_retry
+              handle_auth_error_retry(request, context, next_middleware)
+            else
+              response
+            end
+          rescue A2A::Errors::AuthenticationError, A2A::Errors::AuthorizationFailed => e
+            raise e unless @auto_retry
+
+            handle_auth_error_retry(request, context, next_middleware)
+          end
+        end
+
+        ##
+        # Apply authentication to a request
+        #
+        # @param request [Object] The request to authenticate
+        def apply_authentication(request)
+          case @strategy
+          when OAuth2, JWT, ApiKey
+            @strategy.apply_to_request(request)
+          when Hash
+            # Handle configuration-based authentication
+            apply_config_authentication(request, @strategy)
+          else
+            raise ArgumentError, "Unsupported authentication strategy: #{@strategy.class}"
+          end
+        end
+
+        ##
+        # Create interceptor from configuration
+        #
+        # @param config [Hash] Authentication configuration
+        # @return [Interceptor] Configured interceptor
+        def self.from_config(config)
+          strategy = case config["type"] || config[:type]
+                     when "oauth2"
+                       OAuth2.new(
+                         client_id: config["client_id"] || config[:client_id],
+                         client_secret: config["client_secret"] || config[:client_secret],
+                         token_url: config["token_url"] || config[:token_url],
+                         scope: config["scope"] || config[:scope]
+                       )
+                     when "jwt"
+                       JWT.new(
+                         token: config["token"] || config[:token],
+                         secret: config["secret"] || config[:secret],
+                         algorithm: config["algorithm"] || config[:algorithm] || "HS256",
+                         payload: config["payload"] || config[:payload],
+                         headers: config["headers"] || config[:headers],
+                         expires_in: config["expires_in"] || config[:expires_in]
+                       )
+                     when "api_key"
+                       ApiKey.new(
+                         key: config["key"] || config[:key],
+                         name: config["name"] || config[:name] || "X-API-Key",
+                         location: config["location"] || config[:location] || "header"
+                       )
+                     else
+                       raise ArgumentError, "Unknown authentication type: #{config['type'] || config[:type]}"
+                     end
+
+          new(strategy, auto_retry: config["auto_retry"] || config[:auto_retry] || true)
+        end
+
+        ##
+        # Create interceptor from security scheme
+        #
+        # @param scheme [Hash] Security scheme definition
+        # @param credentials [Hash] Authentication credentials
+        # @return [Interceptor] Configured interceptor
+        def self.from_security_scheme(scheme, credentials)
+          strategy = case scheme["type"]
+                     when "oauth2"
+                       OAuth2.new(
+                         client_id: credentials["client_id"],
+                         client_secret: credentials["client_secret"],
+                         token_url: scheme["tokenUrl"],
+                         scope: credentials["scope"]
+                       )
+                     when "http"
+                       case scheme["scheme"]
+                       when "bearer"
+                         JWT.new(token: credentials["token"])
+                       when "basic"
+                         # Basic auth would be handled differently
+                         raise ArgumentError, "Basic auth not yet implemented"
+                       else
+                         raise ArgumentError, "Unsupported HTTP scheme: #{scheme['scheme']}"
+                       end
+                     when "apiKey"
+                       ApiKey.from_security_scheme(scheme, credentials["key"])
+                     else
+                       raise ArgumentError, "Unsupported security scheme type: #{scheme['type']}"
+                     end
+
+          new(strategy)
+        end
+
+        ##
+        # Check if the strategy supports token refresh
+        #
+        # @return [Boolean] True if strategy supports refresh
+        def supports_refresh?
+          @strategy.respond_to?(:refresh_token!) || @strategy.respond_to?(:regenerate_token!)
+        end
+
+        ##
+        # Refresh authentication credentials
+        #
+        # @return [Boolean] True if refresh was successful
+        def refresh!
+          return false unless supports_refresh?
+
+          begin
+            if @strategy.respond_to?(:refresh_token!)
+              @strategy.refresh_token!
+            elsif @strategy.respond_to?(:regenerate_token!)
+              @strategy.regenerate_token!
+            end
+            true
+          rescue StandardError
+            false
+          end
+        end
+
+        ##
+        # Get current authentication status
+        #
+        # @return [Hash] Status information
+        def status
+          {
+            strategy: @strategy.class.name,
+            valid: strategy_valid?,
+            supports_refresh: supports_refresh?,
+            expires_at: strategy_expires_at
+          }
+        end
+
+        private
+
+        ##
+        # Apply configuration-based authentication
+        #
+        # @param request [Object] The request to authenticate
+        # @param config [Hash] Authentication configuration
+        def apply_config_authentication(request, config)
+          case config["type"] || config[:type]
+          when "bearer"
+            request.headers["Authorization"] = "Bearer #{config['token'] || config[:token]}"
+          when "basic"
+            require "base64"
+            username = config["username"] || config[:username]
+            password = config["password"] || config[:password]
+            credentials = Base64.strict_encode64("#{username}:#{password}")
+            request.headers["Authorization"] = "Basic #{credentials}"
+          when "api_key"
+            name = config["name"] || config[:name] || "X-API-Key"
+            key = config["key"] || config[:key]
+            location = config["location"] || config[:location] || "header"
+
+            case location
+            when "header"
+              request.headers[name] = key
+            when "query"
+              request.params[name] = key
+            end
+          end
+        end
+
+        ##
+        # Check if response indicates authentication error
+        #
+        # @param response [Object] The response to check
+        # @return [Boolean] True if authentication error
+        def authentication_error?(response)
+          # This would depend on the response format
+          # For HTTP responses, check status codes
+          return [401, 403].include?(response.status) if response.respond_to?(:status)
+
+          # For JSON-RPC responses, check error codes
+          if response.respond_to?(:[]) && response["error"]
+            error_code = response["error"]["code"]
+            return [A2A::Protocol::JsonRpc::AUTHENTICATION_REQUIRED, A2A::Protocol::JsonRpc::AUTHORIZATION_FAILED].include?(error_code)
+          end
+
+          false
+        end
+
+        ##
+        # Handle authentication error with retry
+        #
+        # @param request [Object] The original request
+        # @param context [Hash] Request context
+        # @param next_middleware [Proc] Next middleware in chain
+        # @return [Object] Response from retry attempt
+        def handle_auth_error_retry(request, context, next_middleware)
+          @retry_mutex.synchronize do
+            # Try to refresh credentials
+            if refresh!
+              # Reapply authentication and retry
+              apply_authentication(request)
+              return next_middleware.call(request, context)
+            end
+          end
+
+          # If refresh failed, raise the original error
+          raise A2A::Errors::AuthenticationError, "Authentication failed and refresh unsuccessful"
+        end
+
+        ##
+        # Check if the current strategy is valid
+        #
+        # @return [Boolean] True if strategy is valid
+        def strategy_valid?
+          case @strategy
+          when OAuth2
+            @strategy.token_valid?
+          when JWT
+            !@strategy.token_expired?
+          when ApiKey
+            @strategy.valid?
+          else
+            true # Assume valid for unknown strategies
+          end
+        end
+
+        ##
+        # Get strategy expiration time
+        #
+        # @return [Time, nil] Expiration time if available
+        def strategy_expires_at
+          case @strategy
+          when OAuth2
+            @strategy.expires_at
+          when JWT
+            @strategy.expires_at
+          end
+        end
+      end
+    end
+  end
+end

data/lib/a2a/client/auth/jwt.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "jwt"
+require "json"
+
+##
+# JWT Bearer Token authentication strategy
+#
+# Supports both static JWT tokens and dynamic JWT generation
+# for authentication with A2A agents.
+#
+module A2A
+  module Client
+    module Auth
+      class JWT
+        attr_reader :token, :algorithm, :secret, :payload, :headers
+
+        ##
+        # Initialize JWT authentication
+        #
+        # @param token [String, nil] Pre-generated JWT token
+        # @param secret [String, nil] Secret key for JWT signing (required for dynamic tokens)
+        # @param algorithm [String] JWT signing algorithm (default: 'HS256')
+        # @param payload [Hash, nil] JWT payload for dynamic token generation
+        # @param headers [Hash, nil] Additional JWT headers
+        # @param expires_in [Integer, nil] Token expiration time in seconds
+        def initialize(token: nil, secret: nil, algorithm: "HS256", payload: nil,
+                       headers: nil, expires_in: nil)
+          @token = token
+          @secret = secret
+          @algorithm = algorithm
+          @payload = payload || {}
+          @headers = headers || {}
+          @expires_in = expires_in
+          @generated_token = nil
+          @token_expires_at = nil
+          @token_mutex = Mutex.new
+
+          validate_configuration!
+        end
+
+        ##
+        # Get a valid JWT token
+        #
+        # @return [String] The JWT token
+        def jwt_token
+          if @token
+            # Static token
+            @token
+          else
+            # Dynamic token generation
+            @token_mutex.synchronize do
+              generate_token if token_expired?
+              @generated_token
+            end
+          end
+        end
+
+        ##
+        # Get authorization header value
+        #
+        # @return [String] The authorization header value
+        def authorization_header
+          "Bearer #{jwt_token}"
+        end
+
+        ##
+        # Apply authentication to a Faraday request
+        #
+        # @param request [Faraday::Request] The request to authenticate
+        def apply_to_request(request)
+          request.headers["Authorization"] = authorization_header
+        end
+
+        ##
+        # Validate the JWT token
+        #
+        # @param token [String, nil] Token to validate (uses current token if nil)
+        # @param verify_signature [Boolean] Whether to verify the signature
+        # @return [Hash] Decoded JWT payload
+        def validate_token(token = nil, verify_signature: true)
+          token_to_validate = token || jwt_token
+
+          if verify_signature && @secret
+            ::JWT.decode(token_to_validate, @secret, true, { algorithm: @algorithm })
+          else
+            ::JWT.decode(token_to_validate, nil, false)
+          end
+        rescue ::JWT::DecodeError => e
+          raise A2A::Errors::AuthenticationError, "JWT validation failed: #{e.message}"
+        end
+
+        ##
+        # Check if the token is expired
+        #
+        # @param token [String, nil] Token to check (uses current token if nil)
+        # @return [Boolean] True if token is expired
+        def token_expired?(token = nil)
+          return false unless @expires_in || token
+
+          if @generated_token && @token_expires_at
+            # Check generated token expiration
+            Time.now >= (@token_expires_at - 30) # 30 second buffer
+          elsif token || @token
+            # Check token payload expiration
+            begin
+              payload = validate_token(token, verify_signature: false).first
+              exp = payload["exp"]
+              return false unless exp
+
+              Time.now.to_i >= (exp - 30) # 30 second buffer
+            rescue A2A::Errors::AuthenticationError
+              true # Consider invalid tokens as expired
+            end
+          else
+            false
+          end
+        end
+
+        ##
+        # Force regenerate the token (for dynamic tokens)
+        #
+        # @return [String] The new JWT token
+        def regenerate_token!
+          return @token if @token # Can't regenerate static tokens
+
+          @token_mutex.synchronize do
+            generate_token
+          end
+        end
+
+        ##
+        # Get token expiration time
+        #
+        # @return [Time, nil] Token expiration time
+        def expires_at
+          if @token_expires_at
+            @token_expires_at
+          elsif @token
+            begin
+              payload = validate_token(@token, verify_signature: false).first
+              exp = payload["exp"]
+              Time.zone.at(exp) if exp
+            rescue A2A::Errors::AuthenticationError
+              nil
+            end
+          end
+        end
+
+        private
+
+        ##
+        # Validate the authentication configuration
+        def validate_configuration!
+          raise ArgumentError, "Either token or secret must be provided" if @token.nil? && @secret.nil?
+
+          raise ArgumentError, "Payload is required for dynamic token generation" if @token.nil? && @payload.empty?
+
+          return if %w[HS256 HS384 HS512 RS256 RS384 RS512 ES256 ES384 ES512].include?(@algorithm)
+
+          raise ArgumentError, "Unsupported JWT algorithm: #{@algorithm}"
+        end
+
+        ##
+        # Generate a new JWT token
+        #
+        # @return [String] The generated JWT token
+        def generate_token
+          raise ArgumentError, "Cannot generate token without secret" unless @secret
+
+          # Build payload with expiration
+          token_payload = @payload.dup
+
+          if @expires_in
+            now = Time.now.to_i
+            token_payload["iat"] = now
+            token_payload["exp"] = now + @expires_in
+            @token_expires_at = Time.now + @expires_in
+          end
+
+          # Generate token
+          @generated_token = ::JWT.encode(token_payload, @secret, @algorithm, @headers)
+        rescue ::JWT::EncodeError => e
+          raise A2A::Errors::AuthenticationError, "JWT generation failed: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/client/auth/oauth2.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "base64"
+
+##
+# OAuth 2.0 Client Credentials Flow authentication strategy
+#
+# Implements OAuth 2.0 client credentials flow for machine-to-machine
+# authentication with A2A agents.
+#
+module A2A
+  module Client
+    module Auth
+      class OAuth2
+        attr_reader :client_id, :client_secret, :token_url, :scope, :access_token, :expires_at
+
+        ##
+        # Initialize OAuth2 authentication
+        #
+        # @param client_id [String] OAuth2 client ID
+        # @param client_secret [String] OAuth2 client secret
+        # @param token_url [String] OAuth2 token endpoint URL
+        # @param scope [String, nil] Optional scope for the token
+        def initialize(client_id:, client_secret:, token_url:, scope: nil)
+          @client_id = client_id
+          @client_secret = client_secret
+          @token_url = token_url
+          @scope = scope
+          @access_token = nil
+          @expires_at = nil
+          @token_mutex = Mutex.new
+        end
+
+        ##
+        # Get a valid access token, refreshing if necessary
+        #
+        # @return [String] The access token
+        def token
+          @token_mutex.synchronize do
+            refresh_token if token_expired?
+            @access_token
+          end
+        end
+
+        ##
+        # Get authorization header value
+        #
+        # @return [String] The authorization header value
+        def authorization_header
+          "Bearer #{token}"
+        end
+
+        ##
+        # Apply authentication to a Faraday request
+        #
+        # @param request [Faraday::Request] The request to authenticate
+        def apply_to_request(request)
+          request.headers["Authorization"] = authorization_header
+        end
+
+        ##
+        # Check if the current token is valid
+        #
+        # @return [Boolean] True if token is valid and not expired
+        def token_valid?
+          @access_token && !token_expired?
+        end
+
+        ##
+        # Force refresh the access token
+        #
+        # @return [String] The new access token
+        def refresh_token!
+          @token_mutex.synchronize do
+            refresh_token
+          end
+        end
+
+        ##
+        # Clear the current token (force re-authentication)
+        def clear_token!
+          @token_mutex.synchronize do
+            @access_token = nil
+            @expires_at = nil
+          end
+        end
+
+        private
+
+        ##
+        # Check if the token is expired
+        #
+        # @return [Boolean] True if token is expired or will expire soon
+        def token_expired?
+          return true unless @expires_at
+
+          # Consider token expired if it expires within 30 seconds
+          Time.now >= (@expires_at - 30)
+        end
+
+        ##
+        # Refresh the access token using client credentials flow
+        def refresh_token
+          connection = Faraday.new do |conn|
+            conn.request :url_encoded
+            conn.response :json
+            conn.adapter Faraday.default_adapter
+          end
+
+          # Prepare request parameters
+          params = {
+            grant_type: "client_credentials",
+            client_id: @client_id,
+            client_secret: @client_secret
+          }
+          params[:scope] = @scope if @scope
+
+          # Make token request
+          response = connection.post(@token_url, params)
+
+          unless response.success?
+            raise A2A::Errors::AuthenticationError, "OAuth2 token request failed: #{response.status} - #{response.body}"
+          end
+
+          token_data = response.body
+
+          unless token_data["access_token"]
+            raise A2A::Errors::AuthenticationError, "OAuth2 response missing access_token: #{token_data}"
+          end
+
+          @access_token = token_data["access_token"]
+
+          # Calculate expiration time
+          expires_in = token_data["expires_in"]&.to_i || 3600 # Default to 1 hour
+          @expires_at = Time.now + expires_in
+
+          @access_token
+        rescue Faraday::Error => e
+          raise A2A::Errors::AuthenticationError, "OAuth2 token request failed: #{e.message}"
+        end
+      end
+    end
+  end
+end