a2a-rails 0.2.0 → 0.3.0

data/lib/a2a/rails/client/outbound_policy.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "resolv"
+require "timeout"
+require "uri"
+require_relative "../errors"
+
+module A2A
+  module Rails
+    class Client
+      # Preflight checks for a *configured* outbound Agent Card or RPC URL.
+      #
+      # IMPORTANT: Resolve! alone does not prevent DNS rebinding. The future
+      # transport MUST connect to one of Target#addresses while preserving
+      # the validated Host/SNI, and repeat the decision for each connection.
+      # Do not expose this as a production-ready HTTP Client.
+      class OutboundPolicy
+        class RejectedTarget < A2A::Rails::Error
+          attr_reader :reason
+
+          def initialize(reason)
+            @reason = reason
+            super("Outbound A2A target rejected: #{reason}")
+          end
+        end
+
+        Target = Struct.new(:url, :origin, :host, :port, :addresses, keyword_init: true)
+
+        # IPv4-pinned policy. Dual-stack DNS is accepted only if EVERY IPv6
+        # answer is a recognized public global-unicast candidate and at least
+        # one safe IPv4 address is present. IPv6 sockets remain unsupported.
+        BLOCKED_IPV4 = %w[
+          0.0.0.0/8
+          10.0.0.0/8
+          100.64.0.0/10
+          127.0.0.0/8
+          169.254.0.0/16
+          172.16.0.0/12
+          192.0.0.0/24
+          192.0.2.0/24
+          192.88.99.0/24
+          192.168.0.0/16
+          198.18.0.0/15
+          198.51.100.0/24
+          203.0.113.0/24
+          224.0.0.0/4
+          240.0.0.0/4
+        ].map { |cidr| IPAddr.new(cidr) }.freeze
+
+        # Only recognize IPv6 global-unicast candidates for DNS validation;
+        # outbound sockets remain IPv4-only. Exclude special-use allocations
+        # conservatively, including IPv4-embedding transition mechanisms.
+        GLOBAL_UNICAST_IPV6 = IPAddr.new("2000::/3")
+        BLOCKED_IPV6 = %w[
+          2001::/23
+          2001:db8::/32
+          2002::/16
+          3fff::/20
+        ].map { |cidr| IPAddr.new(cidr) }.freeze
+
+        HOST_LABEL = /\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/
+
+        # Resolver injection is for unit testing only; normal callers use
+        # Resolv. The Client facade will not expose this override by default.
+        def initialize(allowed_origins:, resolver: Resolv.method(:getaddresses))
+          unless allowed_origins.is_a?(Array) && !allowed_origins.empty? && allowed_origins.all? { |value| value.is_a?(String) }
+            raise RejectedTarget, :invalid_allowlist
+          end
+          unless resolver.respond_to?(:call)
+            raise RejectedTarget, :invalid_resolver
+          end
+
+          @allowed_origins = allowed_origins.map { |value| checked_origin(value) }.uniq.freeze
+          @resolver = resolver
+        end
+
+        # Check configured URL syntax and exact origin without resolving DNS.
+        # The actual HTTP transport MUST call resolve! again at connect time.
+        def validate_url!(value)
+          uri = checked_uri(value)
+          raise RejectedTarget, :unapproved_origin unless @allowed_origins.include?(canonical_origin(uri))
+
+          uri
+        end
+
+        # Called for BOTH the configured Agent Card URL and each card-provided
+        # supportedInterfaces[].url. The result is NOT permission to connect
+        # by hostname: use Target#addresses as the connect-time allowlist.
+        def resolve!(value)
+          uri = checked_uri(value)
+          origin = canonical_origin(uri)
+          raise RejectedTarget, :unapproved_origin unless @allowed_origins.include?(origin)
+
+          addresses = begin
+            @resolver.call(uri.host)
+          rescue Timeout::Error
+            # The transport's total deadline must not be converted into a DNS failure.
+            raise
+          rescue StandardError
+            raise RejectedTarget.new(:dns_failure), cause: nil
+          end
+          unless addresses.is_a?(Array) && !addresses.empty?
+            raise RejectedTarget, :dns_failure
+          end
+
+          # Fail closed if ANY DNS answer is unsafe, even when another answer
+          # is public. Public IPv6 answers are checked, but NEVER selected as
+          # a socket destination; the transport pins an approved IPv4 only.
+          addresses = addresses.each_with_object([]) do |address, ipv4_addresses|
+            # IPAddr accepts CIDR strings and normalizes them to network addresses.
+            # DNS answers must instead be individual host IP literals.
+            unless address.is_a?(String) && !address.include?("/")
+              raise RejectedTarget, :invalid_dns_address
+            end
+            parsed = IPAddr.new(address)
+            if parsed.ipv4?
+              raise RejectedTarget, :blocked_ip if BLOCKED_IPV4.any? { |range| range.include?(parsed) }
+              ipv4_addresses << parsed.to_s.freeze
+            elsif !GLOBAL_UNICAST_IPV6.include?(parsed) ||
+                  BLOCKED_IPV6.any? { |range| range.include?(parsed) }
+              raise RejectedTarget, :blocked_ip
+            end
+          rescue IPAddr::InvalidAddressError, ArgumentError
+            raise RejectedTarget.new(:invalid_dns_address), cause: nil
+          end.uniq.freeze
+          raise RejectedTarget, :unsupported_ip_family if addresses.empty?
+
+          Target.new(
+            url: uri.to_s.freeze,
+            origin: origin.freeze,
+            host: uri.host.freeze,
+            port: uri.port,
+            addresses: addresses
+          ).freeze
+        end
+
+        private
+
+        def checked_origin(value)
+          uri = checked_uri(value)
+          raise RejectedTarget, :invalid_allowlist unless uri.path.empty? || uri.path == "/"
+
+          canonical_origin(uri)
+        end
+
+        def checked_uri(value)
+          raise RejectedTarget, :invalid_url unless value.is_a?(String) && !value.empty? && value == value.strip
+          uri = URI.parse(value)
+
+          unless uri.is_a?(URI::HTTPS) && uri.host && !uri.host.empty? &&
+              uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil?
+            raise RejectedTarget, :invalid_url
+          end
+
+          host = uri.host.downcase
+          labels = host.split(".", -1)
+          unless host.ascii_only? && host.bytesize <= 253 && labels.size >= 2 &&
+              labels.all? { |part| HOST_LABEL.match?(part) } &&
+              labels.last.match?(/[a-z]/)
+            raise RejectedTarget, :invalid_host
+          end
+
+          # DNS names only, never direct IPv4/IPv6 or unusual numeric forms.
+          begin
+            IPAddr.new(host)
+            raise RejectedTarget, :ip_literal
+          rescue IPAddr::InvalidAddressError
+            # Expected for DNS names.
+          end
+
+          # Fail closed on encoded slashes, backslashes, controls or ambiguous
+          # dot segments pending a more general URL canonicalization layer.
+          path = uri.path
+          if path.match?(/[%\\\\[:cntrl:]]/) || path.split("/").include?("..") || path.split("/").include?(".")
+            raise RejectedTarget, :invalid_path
+          end
+
+          unless uri.port.between?(1, 65_535)
+            raise RejectedTarget, :invalid_port
+          end
+
+          uri.host = host
+          uri
+        rescue URI::InvalidURIError, URI::InvalidComponentError
+          raise RejectedTarget.new(:invalid_url), cause: nil
+        end
+
+        def canonical_origin(uri)
+          base = "https://#{uri.host.downcase}"
+          uri.port == 443 ? base : "#{base}:#{uri.port}"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/client/pinned_https_transport.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "timeout"
+require "uri"
+require_relative "outbound_policy"
+
+module A2A
+  module Rails
+    class Client
+      # Internal synchronous HTTPS transport used by the unreleased Client facade.
+      #
+      # DNS is checked immediately before each request; the selected IP is
+      # pinned on Net::HTTP BEFORE the socket is opened. TLS peer and hostname
+      # validation continue to use the original approved DNS hostname.
+      class PinnedHttpsTransport
+        class Error < A2A::Rails::Error
+          attr_reader :reason
+
+          def initialize(reason)
+            @reason = reason
+            super("Outbound A2A HTTP request failed: #{reason}")
+          end
+        end
+
+        class RedirectBlocked < Error; end
+        class ResponseTooLarge < Error; end
+        class InvalidResponse < Error; end
+        class DeadlineExceeded < Error; end
+
+        class HTTPError < Error
+          attr_reader :status
+
+          def initialize(status)
+            @status = status
+            super(:http_error)
+          end
+        end
+
+        Response = Struct.new(:status, :json, keyword_init: true)
+
+        DEFAULT_OPEN_TIMEOUT = 3
+        DEFAULT_READ_TIMEOUT = 10
+        DEFAULT_TOTAL_TIMEOUT = 15
+        DEFAULT_MAX_BYTES = 1_048_576
+        DEFAULT_MAX_DEPTH = 48
+        MAX_CREDENTIAL_BYTES = 4096
+
+        def initialize(policy:, open_timeout: DEFAULT_OPEN_TIMEOUT,
+                       read_timeout: DEFAULT_READ_TIMEOUT,
+                       total_timeout: DEFAULT_TOTAL_TIMEOUT,
+                       max_request_bytes: DEFAULT_MAX_BYTES,
+                       max_response_bytes: DEFAULT_MAX_BYTES,
+                       max_json_nesting: DEFAULT_MAX_DEPTH,
+                       ca_file: nil)
+          unless policy.respond_to?(:resolve!)
+            raise Error, :invalid_policy
+          end
+
+          @policy = policy
+          @open_timeout = positive_number!(open_timeout)
+          @read_timeout = positive_number!(read_timeout)
+          @total_timeout = positive_number!(total_timeout)
+          @max_request_bytes = positive_integer!(max_request_bytes)
+          @max_response_bytes = positive_integer!(max_response_bytes)
+          @max_json_nesting = positive_integer!(max_json_nesting)
+          @ca_file = ca_file
+        end
+
+        # Agent Card requests are public by default. Protected Cards require
+        # their OWN callback and explicitly bound credential origin.
+        def get_json(url:, authorization: nil, credential_origin: nil)
+          perform(:get, url: url, authorization: authorization, credential_origin: credential_origin)
+        end
+
+        # A2A v1.0 JSON-RPC payload; preserves both Task and direct Message
+        # response shapes without interpreting the protocol at this layer.
+        def post_json(url:, json:, authorization: nil, credential_origin: nil)
+          encoded = JSON.generate(json, max_nesting: @max_json_nesting, allow_nan: false)
+          raise Error, :request_too_large if encoded.bytesize > @max_request_bytes
+
+          perform(:post, url: url, body: encoded,
+                  authorization: authorization, credential_origin: credential_origin)
+        rescue JSON::GeneratorError, JSON::NestingError, TypeError
+          raise Error.new(:invalid_request_json), cause: nil
+        end
+
+        private
+
+        def perform(method, url:, body: nil, authorization: nil, credential_origin: nil)
+          # Fail closed on syntax/origin/DNS before evaluating any credential.
+          # OutboundPolicy also rejects mixed public/private DNS results.
+          # DNS and credential callbacks count toward the same total deadline
+          # as socket connection, request upload and response consumption.
+          Timeout.timeout(@total_timeout) do
+            target = @policy.resolve!(url)
+            uri = URI.parse(target.url)
+            raise Error, :invalid_target unless uri.is_a?(URI::HTTPS) &&
+              target.host == uri.host && target.port == uri.port &&
+              target.addresses.is_a?(Array) && !target.addresses.empty?
+
+            header = credential_for(target, authorization, credential_origin)
+            ip = target.addresses.first
+
+            # The third argument nil is essential: ignore HTTP(S)_PROXY and
+            # env proxy configuration, which could bypass the approved IP.
+            http = Net::HTTP.new(target.host, target.port, nil)
+            raise Error, :proxy_not_disabled if http.proxy?
+
+            http.ipaddr = ip
+            http.use_ssl = true
+            http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+            http.verify_hostname = true
+            http.ca_file = @ca_file unless @ca_file.nil?
+            http.open_timeout = [@open_timeout, @total_timeout].min
+            http.read_timeout = [@read_timeout, @total_timeout].min
+            http.write_timeout = [@read_timeout, @total_timeout].min
+            http.max_retries = 0 # Especially important for SendMessage.
+            http.keep_alive_timeout = 0
+
+            request_class = method == :get ? Net::HTTP::Get : Net::HTTP::Post
+            request = request_class.new(uri.request_uri)
+            request["Accept"] = "application/json"
+            request["Accept-Encoding"] = "identity"
+            request["A2A-Version"] = "1.0" if method == :post
+            request["Content-Type"] = "application/json" if method == :post
+            request["Authorization"] = header unless header.nil?
+            request.body = body if method == :post
+
+            payload = nil
+            status = nil
+            http.start do |connection|
+              # Guard against a future Net::HTTP implementation that might
+              # silently connect anywhere other than the pinned address.
+              raise Error, :socket_address_mismatch unless connection.ipaddr == ip
+
+              connection.request(request) do |response|
+                status = response.code.to_i
+                raise RedirectBlocked, :redirect_rejected if status.between?(300, 399)
+                raise HTTPError, status unless status.between?(200, 299)
+
+                content_type = response["Content-Type"].to_s.downcase.split(";", 2).first.strip
+                unless ["application/json", "application/a2a+json"].include?(content_type)
+                  raise InvalidResponse, :invalid_content_type
+                end
+                unless response["Content-Encoding"].to_s.strip.downcase.match?(/\A(?:|identity)\z/)
+                  raise InvalidResponse, :unsupported_content_encoding
+                end
+
+                content_length = response["Content-Length"]
+                if content_length
+                  raise InvalidResponse, :invalid_content_length unless content_length.match?(/\A[0-9]+\z/)
+                  raise ResponseTooLarge, :response_too_large if content_length.to_i > @max_response_bytes
+                end
+
+                payload = +""
+                response.read_body do |chunk|
+                  raise ResponseTooLarge, :response_too_large if payload.bytesize + chunk.bytesize > @max_response_bytes
+                  payload << chunk
+                end
+
+                # Net::HTTP can return successfully on a prematurely closed
+                # Content-Length body. A valid JSON prefix must not make that
+                # truncated HTTP response look like a complete A2A reply.
+                if content_length && payload.bytesize != content_length.to_i
+                  raise InvalidResponse, :invalid_content_length
+                end
+              end
+            end
+
+            parsed = JSON.parse(payload, max_nesting: @max_json_nesting)
+            Response.new(status: status, json: parsed).freeze
+          end
+        rescue Timeout::Error, Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
+          raise DeadlineExceeded.new(:timeout), cause: nil
+        rescue JSON::ParserError, JSON::NestingError
+          raise InvalidResponse.new(:invalid_json), cause: nil
+        rescue OpenSSL::SSL::SSLError, IOError, SystemCallError, SocketError, EOFError,
+               Net::HTTPBadResponse, Net::ProtocolError
+          # Never surface remote bodies, headers, URLs, IPs or credentials,
+          # including nested exception causes captured by error reporters.
+          raise Error.new(:connection_failed), cause: nil
+        end
+
+        def credential_for(target, callback, origin)
+          if callback.nil?
+            raise Error, :unexpected_credential_origin unless origin.nil?
+            return nil
+          end
+          unless callback.respond_to?(:call) && origin.is_a?(String) && origin == target.origin
+            raise Error, :credential_origin_mismatch
+          end
+
+          value = begin
+            callback.call
+          rescue Timeout::Error
+            # Preserve the outer total-deadline classification.
+            raise
+          rescue StandardError
+            # Host token-provider exceptions may embed credentials. Never
+            # surface them as the transport's public-facing error/cause.
+            raise Error.new(:credential_failure), cause: nil
+          end
+          unless value.is_a?(String) && !value.empty? && value.bytesize <= MAX_CREDENTIAL_BYTES &&
+              !value.match?(/[\r\n\x00-\x1f\x7f]/)
+            raise Error, :invalid_credential
+          end
+          value
+        end
+
+        def positive_number!(value)
+          return value if value.is_a?(Numeric) && value.finite? && value.positive?
+
+          raise Error, :invalid_timeout
+        end
+
+        def positive_integer!(value)
+          return value if value.is_a?(Integer) && value.positive?
+
+          raise Error, :invalid_limit
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/client/public_types.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class Client
+      # Public client-only exceptions. Never include response bodies, URLs,
+      # request metadata or credential strings in exception messages.
+      class Error < A2A::Rails::Error
+        attr_reader :reason, :operation
+
+        def initialize(reason, operation: nil)
+          @reason = reason
+          @operation = operation
+          super("Outbound A2A #{operation || 'Client'}: #{reason}")
+        end
+      end
+
+      class ConfigurationError < Error; end
+      class InvalidInputError < Error; end
+      class DiscoveryError < Error; end
+      class UnsupportedInterfaceError < DiscoveryError; end
+      class TransportError < Error; end
+
+      class TimeoutError < TransportError
+        attr_reader :may_have_executed
+
+        def initialize(operation:, may_have_executed:)
+          @may_have_executed = may_have_executed
+          super(:timeout, operation: operation)
+        end
+      end
+
+      class AuthenticationError < Error
+        attr_reader :status
+
+        def initialize(status, operation:)
+          @status = status
+          super(:authentication_rejected, operation: operation)
+        end
+      end
+
+      class RemoteError < Error
+        attr_reader :code
+
+        def initialize(code, operation:)
+          @code = code
+          super(:remote_protocol_error, operation: operation)
+        end
+      end
+
+      class InvalidResponseError < Error; end
+
+      # Immutable plain-Ruby results, deliberately independent of the SDK.
+      SendResult = Struct.new(:kind, :task, :message, keyword_init: true)
+      ListResult = Struct.new(:tasks, :next_page_token, :page_size, :total_size, keyword_init: true)
+    end
+  end
+end