a2a-rails 0.1.0 → 0.2.0

data/app/controllers/a2a/rails/requests_controller.rb

@@ -4,6 +4,10 @@ module A2A
   module Rails
     class RequestsController < ApplicationController
       def create
+        response.set_header("Cache-Control", "no-store")
+        return unless validate_a2a_request_body
+        return unless authenticate_a2a_request
+
         status, headers, body = A2A::Rails.runtime.call(
           env: request.env,
           request_base_url: request.base_url
@@ -13,6 +17,55 @@ module A2A
         headers.each { |name, value| response.set_header(name, value) }
         self.response_body = body
       end
+
+      private
+
+      def validate_a2a_request_body
+        RequestGuard.enforce!(
+          env: request.env,
+          max_bytes: A2A::Rails.configuration.max_request_bytes
+        )
+        true
+      rescue RequestGuard::PayloadTooLarge
+        render json: { error: "Payload too large" }, status: 413
+        false
+      rescue RequestGuard::UnsupportedMediaType
+        # This is an HTTP boundary rejection before JSON-RPC parsing (and
+        # before authentication). Respond with no JSON body: a JSON string
+        # under "error" is not a valid JSON-RPC Error object and confuses
+        # protocol clients that parse an HTTP 415 response as JSON-RPC.
+        head :unsupported_media_type
+        false
+      rescue RequestGuard::InvalidBody
+        render json: { error: "Invalid request body" }, status: 400
+        false
+      rescue RequestGuard::InvalidConfiguration
+        A2A::Rails.configuration.logger&.error("[a2a-rails] invalid request size configuration")
+        render json: { error: "Request validation unavailable" }, status: 500
+        false
+      end
+
+      def authenticate_a2a_request
+        Authentication.authenticate!(
+          request: request,
+          configuration: A2A::Rails.configuration,
+          rails_environment: ::Rails.env
+        )
+        true
+      rescue Authentication::Unauthorized
+        response.set_header("WWW-Authenticate", A2A::Rails.configuration.authentication_challenge)
+        render json: { error: "Unauthorized" }, status: :unauthorized
+        false
+      rescue Authentication::Forbidden
+        render json: { error: "Forbidden" }, status: :forbidden
+        false
+      rescue StandardError => error
+        # The exception message may contain credentials supplied by host code.
+        # Log the class only; never echo verifier failures into the response.
+        A2A::Rails.configuration.logger&.error("[a2a-rails] authentication unavailable: #{error.class}")
+        render json: { error: "Authentication unavailable" }, status: :internal_server_error
+        false
+      end
     end
   end
 end

data/lib/a2a/rails/agent.rb

@@ -34,7 +34,21 @@ module A2A
           @a2a_router = value
         end
 
-        def skill(id, description:, tags:, handler:, name: nil, examples: nil, input_modes: nil, output_modes: nil)
+        def execution_mode(value = UNSET)
+          return @a2a_execution_mode if value.equal?(UNSET)
+
+          @a2a_execution_mode = value
+        end
+
+        # Task replies remain the default. A host may opt into direct Message
+        # replies or provide a callable to choose the mode per request.
+        def response_mode(value = UNSET)
+          return @a2a_response_mode || :task if value.equal?(UNSET)
+
+          @a2a_response_mode = value
+        end
+
+        def skill(id, description:, tags:, handler:, name: nil, examples: nil, input_modes: nil, output_modes: nil, execution_mode: nil)
           definition = Skill.new(
             id: id,
             name: name,
@@ -43,7 +57,8 @@ module A2A
             handler: handler,
             examples: examples,
             input_modes: input_modes,
-            output_modes: output_modes
+            output_modes: output_modes,
+            execution_mode: execution_mode
           )
           skill_definitions << definition
           definition
@@ -57,6 +72,8 @@ module A2A
           validate_metadata!
           validate_skills!
           validate_router!
+          validate_response_mode!
+          validate_execution_mode!
           self
         end
 
@@ -91,6 +108,20 @@ module A2A
           skill_definitions.each(&:validate!)
         end
 
+        def validate_response_mode!
+          mode = response_mode
+          return if %i[task message].include?(mode) || mode.respond_to?(:call)
+
+          raise ConfigurationError, "response_mode must be :task, :message, or a callable"
+        end
+
+        def validate_execution_mode!
+          mode = execution_mode
+          return if mode.nil? || Configuration::TASK_EXECUTION_MODES.include?(mode)
+
+          raise ConfigurationError, "execution_mode must be :sync or :async"
+        end
+
         def validate_router!
           if skill_definitions.length > 1 && @a2a_router.nil?
             raise ConfigurationError, "#{self} defines multiple skills but no Router is configured"

data/lib/a2a/rails/agent_card/builder.rb

@@ -9,10 +9,11 @@ module A2A
         DEFAULT_INPUT_MODES = ["text/plain"].freeze
         DEFAULT_OUTPUT_MODES = ["text/plain"].freeze
 
-        def initialize(agent:, public_base_url: nil, request_base_url: nil, validator: Validator.new)
+        def initialize(agent:, public_base_url: nil, request_base_url: nil, security: {}, validator: Validator.new)
           @agent = agent
           @public_base_url = public_base_url
           @request_base_url = request_base_url
+          @security = security
           @validator = validator
         end
 
@@ -40,6 +41,7 @@ module A2A
             "skills" => @agent.skills.map { |skill| skill_hash(skill) }
           }
 
+          card.merge!(@security) unless @security.empty?
           @validator.validate!(card)
         end
 

data/lib/a2a/rails/agent_card/security.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    module AgentCard
+      # A2A v1.0 Agent Card security metadata is declarative. The host Rails
+      # application MUST independently verify the advertised credentials.
+      #
+      # Step 16-5 supports a verified HTTP Bearer profile only. Do not
+      # advertise unimplemented API key, OAuth2, OIDC or mTLS profiles.
+      class Security
+        def initialize(configuration:, rails_environment: (defined?(::Rails) ? ::Rails.env : "development"))
+          @configuration = configuration
+          @rails_environment = rails_environment.to_s
+        end
+
+        def fields
+          schemes = @configuration.security_schemes
+          requirements = @configuration.security_requirements
+          authenticator = @configuration.authenticate_request
+
+          # Preserve the unauthenticated local Quick Start, but never
+          # advertise an authentication method that has no verifier.
+          if authenticator.nil? && schemes.nil? && requirements.nil?
+            # A public Agent Card with no security requirements would falsely
+            # imply that production's protected endpoint is open.
+            return {} if %w[development test].include?(@rails_environment)
+
+            raise ConfigurationError, "Agent Card cannot advertise unauthenticated production endpoint"
+          end
+
+          unless authenticator.respond_to?(:call)
+            raise ConfigurationError, "Agent Card security needs a configured request authenticator"
+          end
+
+          unless schemes.is_a?(Hash) && !schemes.empty? &&
+              requirements.is_a?(Array) && !requirements.empty?
+            raise ConfigurationError, "authenticated Agent Cards require security_schemes and security_requirements"
+          end
+
+          normalized_schemes = schemes.each_with_object({}) do |(name, definition), output|
+            unless nonempty_string?(name) && definition.is_a?(Hash) && definition.size == 1
+              raise ConfigurationError, "invalid Agent Card security scheme"
+            end
+
+            scheme_type, details = definition.first
+            case scheme_type
+            when "httpAuthSecurityScheme"
+              validate_http_auth!(details)
+            else
+              raise ConfigurationError, "unsupported Agent Card authentication scheme type"
+            end
+            output[name] = { scheme_type => details.dup }
+          end
+
+          validated_requirements = requirements.map do |requirement|
+            unless requirement.is_a?(Hash) && requirement.keys == ["schemes"] &&
+                requirement["schemes"].is_a?(Hash) && !requirement["schemes"].empty?
+              raise ConfigurationError, "invalid Agent Card security requirement"
+            end
+
+            entries = requirement["schemes"].each_with_object({}) do |(name, scope_list), output|
+              unless normalized_schemes.key?(name) &&
+                  scope_list.is_a?(Hash) && scope_list.keys == ["list"] &&
+                  scope_list["list"].is_a?(Array) &&
+                  scope_list["list"].all? { |scope| nonempty_string?(scope) }
+                raise ConfigurationError, "Agent Card requirement references unknown or invalid scheme"
+              end
+              unless scope_list["list"].empty?
+                raise ConfigurationError, "Bearer HTTP auth must not advertise OAuth scopes"
+              end
+              output[name] = { "list" => [] }
+            end
+            { "schemes" => entries }
+          end
+
+          {
+            "securitySchemes" => normalized_schemes,
+            "securityRequirements" => validated_requirements
+          }
+        end
+
+        private
+
+        def nonempty_string?(value)
+          value.is_a?(String) && !value.strip.empty? && value.bytesize <= 256 &&
+            !value.match?(/[[:cntrl:]]/)
+        end
+
+        def validate_http_auth!(details)
+          unless details.is_a?(Hash) &&
+              (details.keys - %w[scheme description bearerFormat]).empty? &&
+              nonempty_string?(details["scheme"]) &&
+              optional_text?(details, "description") &&
+              optional_text?(details, "bearerFormat")
+            raise ConfigurationError, "invalid HTTP authentication declaration"
+          end
+          # In v1.0 a Bearer challenge is the only HTTP Auth profile we
+          # currently verify together with Rails' authenticate_request hook.
+          unless details["scheme"].casecmp?("Bearer")
+            raise ConfigurationError, "only Bearer HTTP authentication is supported"
+          end
+          Authentication.validate_challenge!(@configuration.authentication_challenge)
+          unless @configuration.authentication_challenge.match?(/\ABearer(?:\s|\z)/i)
+            raise ConfigurationError, "Bearer Agent Card must use a Bearer WWW-Authenticate challenge"
+          end
+        end
+
+        def optional_text?(hash, field)
+          !hash.key?(field) || nonempty_string?(hash[field])
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/authentication.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    # Gate the A2A HTTP endpoint before the protocol adapter can parse or
+    # dispatch a request. Task ownership is a separate security boundary
+    # (Step 16-3); authenticating a caller alone does not isolate Tasks.
+    module Authentication
+      PRINCIPAL_ENV_KEY = "a2a.rails.principal_id"
+      MAX_PRINCIPAL_BYTES = 256
+
+      class Unauthorized < StandardError; end
+      class Forbidden < StandardError; end
+      class ConfigurationError < StandardError; end
+
+      module_function
+
+      def authenticate!(request:, configuration:, rails_environment:)
+        # Never accept a pre-existing Rack environment value as a verified
+        # principal: only the application's authenticator may populate it.
+        request.env.delete(PRINCIPAL_ENV_KEY)
+        validate_challenge!(configuration.authentication_challenge)
+
+        authenticator = configuration.authenticate_request
+        if authenticator.nil?
+          # Preserve the published local Rails Quick Start in dev/test.
+          # Every other Rails environment fails closed without an authenticator.
+          return nil if %w[development test].include?(rails_environment.to_s)
+
+          raise Unauthorized
+        end
+
+        unless authenticator.respond_to?(:call)
+          raise ConfigurationError, "authenticate_request must respond to #call"
+        end
+
+        # A host verifier is only available when its advertised security
+        # requirements are valid. Never silently publish an open Agent Card.
+        AgentCard::Security.new(
+          configuration: configuration,
+          rails_environment: rails_environment
+        ).fields
+
+        principal_id = authenticator.call(request)
+        raise Unauthorized if principal_id.nil? || principal_id == false
+
+        unless valid_principal_id?(principal_id)
+          raise ConfigurationError, "authenticator must return a non-secret principal ID String"
+        end
+
+        # Retain only a stable, non-secret identity for future authorization
+        # checks. Never copy Authorization credentials into the Rack env key.
+        request.env[PRINCIPAL_ENV_KEY] = principal_id.dup.freeze
+      end
+
+      def validate_challenge!(value)
+        if !value.is_a?(String) || value.empty? || value.bytesize > 512 ||
+            value.match?(/[\r\n]/)
+          raise ConfigurationError, "authentication_challenge must be a safe HTTP challenge String"
+        end
+      end
+
+      def valid_principal_id?(value)
+        value.is_a?(String) &&
+          !value.strip.empty? &&
+          value.bytesize <= MAX_PRINCIPAL_BYTES &&
+          !value.match?(/[[:cntrl:]]/)
+      end
+    end
+  end
+end

data/lib/a2a/rails/configuration.rb

@@ -1,15 +1,42 @@
 # frozen_string_literal: true
 
+require "digest"
 require "uri"
 
 module A2A
   module Rails
     class Configuration
-      attr_accessor :agent, :public_base_url
+      TASK_STORE_METHODS = %i[save find transition cancel list].freeze
+      TASK_EXECUTION_MODES = %i[sync async].freeze
+      DEFAULT_TASK_RETENTION_SECONDS = 30 * 24 * 60 * 60
+      DEFAULT_TASK_PRUNE_BATCH_SIZE = 1_000
+      DEFAULT_MAX_TASKS_PER_OWNER = 10_000
+      DEFAULT_MAX_TASK_HISTORY_ENTRIES = 100
+      DEFAULT_MAX_TASK_ARTIFACTS = 50
+
+      attr_accessor :agent, :public_base_url, :authenticate_request, :authentication_challenge,
+        :max_request_bytes, :security_schemes, :security_requirements,
+        :task_store, :task_page_token_secret, :task_retention,
+        :task_prune_batch_size, :max_tasks_per_owner,
+        :max_task_history_entries, :max_task_artifacts,
+        :task_execution_mode
 
       def initialize
         @agent = nil
         @public_base_url = nil
+        @authenticate_request = nil
+        @authentication_challenge = 'Bearer realm="a2a"'
+        @security_schemes = nil
+        @security_requirements = nil
+        @max_request_bytes = RequestGuard::DEFAULT_MAX_BYTES
+        @task_store = :memory
+        @task_page_token_secret = nil
+        @task_retention = DEFAULT_TASK_RETENTION_SECONDS
+        @task_prune_batch_size = DEFAULT_TASK_PRUNE_BATCH_SIZE
+        @max_tasks_per_owner = DEFAULT_MAX_TASKS_PER_OWNER
+        @max_task_history_entries = DEFAULT_MAX_TASK_HISTORY_ENTRIES
+        @max_task_artifacts = DEFAULT_MAX_TASK_ARTIFACTS
+        @task_execution_mode = :sync
         @logger_set = false
       end
 
@@ -28,9 +55,16 @@ module A2A
       def validate!
         validate_agent_name!
         normalized_public_base_url
+        validate_task_execution_mode!(@task_execution_mode, "config.task_execution_mode")
         self
       end
 
+      def resolve_task_execution_mode(agent:, skill:)
+        mode = skill.execution_mode || agent.execution_mode || @task_execution_mode
+        validate_task_execution_mode!(mode, "task execution mode")
+        mode
+      end
+
       def resolve_agent
         validate_agent_name!
 
@@ -52,8 +86,68 @@ module A2A
         normalize_base_url(value.to_s)
       end
 
+      def resolve_task_store
+        case @task_store
+        when nil, :memory
+          Task::MemoryStore.new
+        when :active_record
+          resolve_active_record_store
+        else
+          validate_task_store!(@task_store)
+        end
+      end
+
       private
 
+      def validate_task_execution_mode!(mode, label)
+        return if TASK_EXECUTION_MODES.include?(mode)
+
+        raise ConfigurationError, "#{label} must be :sync or :async"
+      end
+
+      def resolve_active_record_store
+        require_relative "task/active_record_store"
+
+        Task::ActiveRecordStore.new(
+          cursor_secret: task_cursor_secret,
+          retention: @task_retention,
+          prune_batch_size: @task_prune_batch_size,
+          max_tasks_per_owner: @max_tasks_per_owner,
+          max_history_entries: @max_task_history_entries,
+          max_artifacts: @max_task_artifacts
+        )
+      rescue LoadError => error
+        raise ConfigurationError,
+          "config.task_store = :active_record requires ActiveRecord in the host application (#{error.path})"
+      end
+
+      def task_cursor_secret
+        configured = @task_page_token_secret
+        if configured
+          unless configured.is_a?(String) && configured.bytesize >= 32
+            raise ConfigurationError, "config.task_page_token_secret must be at least 32 bytes"
+          end
+          return configured
+        end
+
+        if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+          secret = ::Rails.application.secret_key_base.to_s
+          return Digest::SHA256.digest("a2a-rails/task-page-token/#{secret}") unless secret.empty?
+        end
+
+        raise ConfigurationError,
+          "ActiveRecord Task Store needs Rails.application.secret_key_base or config.task_page_token_secret"
+      end
+
+      def validate_task_store!(store)
+        missing = TASK_STORE_METHODS.reject { |method_name| store.respond_to?(method_name) }
+        unless missing.empty?
+          raise ConfigurationError, "config.task_store is missing methods: #{missing.join(", ")}"
+        end
+
+        store
+      end
+
       def validate_agent_name!
         unless @agent.is_a?(String) && !@agent.strip.empty?
           raise ConfigurationError, "config.agent must be a non-empty class-name String"

data/lib/a2a/rails/dispatcher.rb

@@ -3,8 +3,9 @@
 module A2A
   module Rails
     class Dispatcher
-      def initialize(agent:)
+      def initialize(agent:, configuration: Configuration.new)
         @agent = agent
+        @configuration = configuration
       end
 
       def validate!
@@ -12,14 +13,41 @@ module A2A
         self
       end
 
-      def call(message:, context:)
+      # Evaluated before creating a Task, so a direct Message leaves no
+      # temporary or orphaned Task in the backing store.
+      def response_mode(message:)
+        validate!
+        setting = @agent.response_mode
+        mode = setting.respond_to?(:call) ? setting.call(message: message) : setting
+        return mode if %i[task message].include?(mode)
+
+        raise ConfigurationError, "response_mode must resolve to :task or :message"
+      end
+
+      def plan(message:, context:)
         validate!
         skill = select_skill(message: message, context: context)
+
+        ExecutionPlan.new(
+          agent_class_name: @agent.name,
+          skill_id: skill.id,
+          execution_mode: @configuration.resolve_task_execution_mode(agent: @agent, skill: skill)
+        )
+      end
+
+      def execute(plan:, message:, context:)
+        validate!
+        skill = declared_skill(plan.skill_id)
         handler_context = context.merge(skill_id: skill.id)
 
         skill.handler.call(message: message, context: handler_context)
       end
 
+      def call(message:, context:)
+        execution_plan = plan(message: message, context: context)
+        execute(plan: execution_plan, message: message, context: context)
+      end
+
       private
 
       def select_skill(message:, context:)
@@ -33,8 +61,12 @@ module A2A
         )
         selected_id = normalize_selected_id(selected)
 
-        declared.find { |skill| skill.id == selected_id } ||
-          raise(UnknownSkillError, "Router selected unknown skill: #{selected.inspect}")
+        declared_skill(selected_id, selected)
+      end
+
+      def declared_skill(skill_id, original = skill_id)
+        @agent.skills.find { |skill| skill.id == skill_id } ||
+          raise(UnknownSkillError, "Router selected unknown skill: #{original.inspect}")
       end
 
       def normalize_selected_id(value)

data/lib/a2a/rails/engine.rb

@@ -14,6 +14,15 @@ module A2A
     class Engine < ::Rails::Engine
       isolate_namespace A2A::Rails
 
+      # The Gem's app/controllers/a2a/... files define A2A, not A2a.
+      # Override only the exact Zeitwerk basename, rather than mutating the
+      # host's global ActiveSupport inflections (used by migrations).
+      initializer "a2a-rails.zeitwerk_inflection" do
+        ::Rails.autoloaders.each do |loader|
+          loader.inflector.inflect("a2a" => "A2A")
+        end
+      end
+
       initializer "a2a-rails.mount_engine" do |app|
         app.routes.append do
           mount A2A::Rails::Engine => "/"

data/lib/a2a/rails/errors.rb

@@ -38,5 +38,8 @@ module A2A
 
     class InvalidTaskQueryError < TaskError; end
     class InvalidTaskStateError < TaskError; end
+    class TaskStoreUnavailableError < TaskError; end
+    class TaskStoreCapacityError < TaskError; end
+    class TaskStorePayloadLimitError < TaskError; end
   end
 end

data/lib/a2a/rails/execution_plan.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class ExecutionPlan
+      attr_reader :agent_class_name, :skill_id, :execution_mode
+
+      def initialize(agent_class_name:, skill_id:, execution_mode:)
+        @agent_class_name = normalize_agent_class_name(agent_class_name)
+        @skill_id = normalize_skill_id(skill_id)
+        @execution_mode = normalize_execution_mode(execution_mode)
+        freeze
+      end
+
+      def async?
+        @execution_mode == :async
+      end
+
+      private
+
+      def normalize_agent_class_name(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        value.to_s.dup.freeze
+      end
+
+      def normalize_skill_id(value)
+        value.to_sym
+      rescue NoMethodError
+        raise ConfigurationError, "ExecutionPlan skill_id must be convertible to a Symbol"
+      end
+
+      def normalize_execution_mode(value)
+        return value if Configuration::TASK_EXECUTION_MODES.include?(value)
+
+        raise ConfigurationError, "ExecutionPlan execution_mode must be :sync or :async"
+      end
+    end
+  end
+end

data/lib/a2a/rails/file_artifact.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "base64"
+require "uri"
+
+module A2A
+  module Rails
+    # Explicit Handler result for a single A2A v1.0 file Artifact.
+    #
+    #   FileArtifact.bytes(data: File.binread(path), filename: "report.pdf", media_type: "application/pdf")
+    #   FileArtifact.url(url: "https://files.example.com/report.pdf", filename: "report.pdf", media_type: "application/pdf")
+    #
+    # URLs are only *described* on the wire. The Gem never downloads them,
+    # authorizes recipients, generates signed URLs or hosts files.
+    class FileArtifact
+      MAX_INLINE_BYTES = 1_048_576
+      MAX_URL_BYTES = 2_048
+      MAX_FILENAME_BYTES = 255
+      MIME_TYPE = /\A[a-zA-Z0-9!#$&^_.+-]+\/[a-zA-Z0-9!#$&^_.+-]+\z/
+
+      def self.bytes(data:, filename:, media_type:)
+        unless data.is_a?(String) && data.bytesize <= MAX_INLINE_BYTES
+          raise ArtifactMappingError, "inline file data must be a String of at most 1 MiB"
+        end
+
+        new(content_kind: :raw, content: Base64.strict_encode64(data.b),
+          filename: filename, media_type: media_type)
+      end
+
+      def self.url(url:, filename:, media_type:)
+        unless url.is_a?(String) && !url.empty? && url.bytesize <= MAX_URL_BYTES &&
+            !url.match?(/[[:cntrl:]]/)
+          raise ArtifactMappingError, "file URL must be an absolute HTTPS URL (at most 2048 bytes)"
+        end
+
+        parsed = URI.parse(url)
+        unless parsed.is_a?(URI::HTTPS) && !parsed.host.to_s.empty? &&
+            parsed.userinfo.nil? && parsed.fragment.nil?
+          raise ArtifactMappingError, "file URL must use HTTPS without credentials or a fragment"
+        end
+
+        new(content_kind: :url, content: url.dup,
+          filename: filename, media_type: media_type)
+      rescue URI::InvalidURIError
+        raise ArtifactMappingError, "invalid file URL"
+      end
+
+      def to_part
+        {
+          @content_kind => @content,
+          filename: @filename,
+          media_type: @media_type
+        }
+      end
+
+      private
+
+      def initialize(content_kind:, content:, filename:, media_type:)
+        unless filename.is_a?(String) && !filename.empty? &&
+            filename.bytesize <= MAX_FILENAME_BYTES &&
+            !filename.include?("/") && !filename.include?("\\") &&
+            !filename.match?(/[[:cntrl:]]/) && !%w[. ..].include?(filename)
+          raise ArtifactMappingError, "filename must be a safe basename (at most 255 bytes)"
+        end
+        unless media_type.is_a?(String) && MIME_TYPE.match?(media_type)
+          raise ArtifactMappingError, "media_type must be a valid MIME type such as application/pdf"
+        end
+
+        @content_kind = content_kind
+        @content = content.freeze
+        @filename = filename.dup.freeze
+        @media_type = media_type.dup.freeze
+        freeze
+      end
+    end
+  end
+end