a2a-rails 0.2.0 → 0.3.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 447c947dcb0231daa7d00a4c0de158ca737795fcae5f529d71a0ed8d87f9ee3f
-  data.tar.gz: bc9fa7e1884a169d45857a9febea788630d9917022e8919819357b4e57914d35
+  metadata.gz: 28e6e84db258492d965f909914a94906dc8de57c0e390eb36ce4749ababa4741
+  data.tar.gz: 421a68f93bb61827857f380fe7fed8a801a97acc2fbf9569297a782d9e6bb43b
 SHA512:
-  metadata.gz: 6209ff98b146525320999d3d44e086053e6d767e1a20328436ff34908af222c87912c2e1b78745ce3b646499f1eb33c4e245d4b883fcc169870a1233604e4c10
-  data.tar.gz: b0b74efa6e45bf7fe84ac63e1d5b2e68cc27386177f1fab728f0ea0582186adb55c7c3c379504b66b05997cc7600cb9e30056143df7311b8af2c591a8b73957d
+  metadata.gz: 849551ca60cf796328da07761d4c8fe5f7a5ebd5860028af88a1affd97775b491c1677ef963b96fb377504e6198e05260416a458f7e5821b137aeaa8e2eb62ff
+  data.tar.gz: 00b4174d36e073db0aa70a2bb3199c1edc59226b334197b506aaf29347f2168324e809a1290e9a5d8961e1e07e00a728e8ddc859099e4d140d364c9f17a6933e

data/CHANGELOG.md

@@ -4,9 +4,53 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.2.0] - 2026-10-08 (stable candidate source; NOT published)
-
-> **Step 26-4 release preparation only.** Version `0.2.0` has been selected for an exact, source-built candidate. No `v0.2.0` Git tag, GitHub Release, or RubyGems push has been authorized. The published `0.2.0.rc2` pre-release is immutable and **does not include the subsequent fixes** below.
+## [0.3.0.rc1] - 2026-10-10 (pre-release candidate)
+
+> **Pre-release candidate, not a stable-production security certification.**
+> This candidate contains the previously unreleased outbound Client changes
+> made after published stable `0.2.0`. The candidate source/gemspec VERSION
+> is `0.3.0.rc1`. [Technical release gates](docs/release/step-29-5u-risk-based-oss-release-policy.md)
+> require exact artifact verification, no known unresolved Critical/High
+> vulnerabilities and an explicit owner GO for publication. An external
+> security review is encouraged but **not a mandatory release condition**.
+> Public A2A deployment security is tracked separately in [Issue #11](https://github.com/cuichangquan/a2a-rails/issues/11).
+
+### Added — outbound Client capabilities (v0.3.0.rc1)
+
+- Outbound Rails `A2A::Rails::Client` for strict HTTPS Agent Card
+  discovery and A2A v1.0 JSON-RPC `SendMessage`, `GetTask`, `ListTasks`,
+  `CancelTask`, with separate Card/RPC credential callbacks, immutable
+  plain-Ruby results, direct Message or Task output and Client-only Rails mode.
+- Explicit approved origin and public-IPv4 pinned socket policy, ordinary
+  hostname/SNI/CA verification, zero automatic transport retries, bounded
+  timeouts/request-response sizes and safe error categories. Host secrets,
+  tenant authorization and recovery are **not** implemented automatically.
+- Structural validation of Message, nested Task/Artifact and File/Data Parts.
+  Native official Python and Go SDK local HTTPS interoperability, plus
+  genuine Solid Queue/Sidekiq separately executing outbound Client workers
+  on Rails 8.0/8.1, all tracked with scoped test limitations.
+
+### Security and compatibility notes
+
+- Source-hardening tests cover DNS/SSRF, TLS/auth/log privacy, gzip and
+  malformed/chunked/truncated HTTP, JSON nesting, ambiguous remote
+  SendMessage/CancelTask timeout and nested response validation.
+- **Go SDK follow-up:** Step 29-5q verified authenticated Go ListTasks pagination with two scoped test users and isolated Task visibility; anonymous callers still receive `-31401`.
+- **Release evidence and limitations:** Exact-version source and Gem are
+  subject to mandatory build-once/SHA256, installed Ruby/Rails/PostgreSQL,
+  native Python/Go interoperability and security regression checks.
+  [Step 29-5u risk-based release policy](docs/release/step-29-5u-risk-based-oss-release-policy.md)
+  makes third-party security audit **optional** and does not assert a
+  certification. No known unresolved Critical/High code defect is acceptable
+  in release scope. Production host security review remains separate.
+- Publishing a Gem and approving open-public **production deployment**
+  are distinct; a host must provide credential issuer verification,
+  business authorization, rate/concurrency and operational limits.
+  No release approval is implied by any CI PASS.
+
+## [0.2.0] - 2026-10-08 (published stable release)
+
+> **Published in Step 27 after explicit approval.** [GitHub Release](https://github.com/cuichangquan/a2a-rails/releases/tag/v0.2.0) and [RubyGems 0.2.0](https://rubygems.org/gems/a2a-rails/versions/0.2.0) contain the exact verified artifact, with no rebuild. See the [publication record](docs/release/v0.2.0-publication-record.md) for its SHA256 and public-download verification. The immutable `0.2.0.rc2` pre-release **does not include the subsequent fixes** below.
 
 ### Added
 

data/README.md

@@ -1,19 +1,22 @@
 # a2a-rails
-<img src="docs/assets/a2a-rails-handwritten-note.png">
+<img src="docs/assets/a2a-rails-infographics.png">
 <br/>
-<img src="docs/assets/a2a-railsで広がるAI協働図鑑.png">
+<br/>
+<img src="docs/assets/a2a-rails-infographics-en.png">
 
 Rails-native integration for exposing Rails applications as A2A v1.0 agents.
 
-> **Release status (2026-10-08):** RubyGems has published **`0.1.0`** and the **`0.2.0.rc2` pre-release**. The current source is being verified as an **unpublished `0.2.0` stable candidate** (Step 26-4). In particular, the Rails/Zeitwerk and migration-generator fixes after rc2 are only in the newer source-built candidate. **No stable `0.2.0` tag, GitHub Release, or RubyGems publication has been authorized.**
+> **Release status (2026-10-08):** **`0.2.0` is published as a stable release** on [RubyGems](https://rubygems.org/gems/a2a-rails/versions/0.2.0) and [GitHub](https://github.com/cuichangquan/a2a-rails/releases/tag/v0.2.0). It includes the Rails/Zeitwerk and migration-generator fixes after rc2. The public Gem matches the verified artifact byte-for-byte; see the [publication record](docs/release/v0.2.0-publication-record.md).
 
 - RubyGems: https://rubygems.org/gems/a2a-rails
-- Published pre-release: https://github.com/cuichangquan/a2a-rails/releases/tag/v0.2.0-rc.2 (stable `0.2.0` not yet released)
+- Published stable release: https://github.com/cuichangquan/a2a-rails/releases/tag/v0.2.0
 - Previous stable release: https://github.com/cuichangquan/a2a-rails/releases/tag/v0.1.0
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
-- Release record: [docs/release/v0.1.0-record.md](docs/release/v0.1.0-record.md)
-- **Release readiness:** [current release/deployment checklist](docs/release/security-hardening-release-checklist.md) · [v0.1.0 → proposed v0.2 upgrade guide](docs/release/upgrading-v0.1.0-to-v0.2.md). The old rc1 record is historical evidence only.
-- **Roadmap / 次にやること:** [ROADMAP.md](ROADMAP.md) — [Step 26 / Issue #62](https://github.com/cuichangquan/a2a-rails/issues/62) tracks the `0.2.0` stable candidate and release gates; [production Issue #11](https://github.com/cuichangquan/a2a-rails/issues/11) remains open. See [stable-readiness record](docs/release/v0.2.0-stable-readiness.md).
+- Release record: [v0.2.0 publication record](docs/release/v0.2.0-publication-record.md)
+- **Security policy / 脆弱性報告:** [SECURITY.md](SECURITY.md) — confidential vulnerability reporting, current assurance boundaries and production responsibilities.
+- **v0.3.x prerelease policy:** [Risk-based release gates](docs/release/step-29-5u-risk-based-oss-release-policy.md) — independently commissioned external audit is **recommended but optional**, not a known vulnerability or RubyGems requirement. Technical security checks, no known unresolved Critical/High findings, exact Gem provenance and explicit maintainer release approval remain mandatory; [optional community review #113](https://github.com/cuichangquan/a2a-rails/issues/113). **No v0.3.x has been published.**
+- **Release readiness:** [current release/deployment checklist](docs/release/security-hardening-release-checklist.md) · [v0.1.0 → v0.2.0 upgrade guide](docs/release/upgrading-v0.1.0-to-v0.2.md). The old rc1 record is historical evidence only.
+- **Roadmap / 次にやること:** [ROADMAP.md](ROADMAP.md) — [Step 26 / Issue #62](https://github.com/cuichangquan/a2a-rails/issues/62) records the `0.2.0` stable release gates; [production Issue #11](https://github.com/cuichangquan/a2a-rails/issues/11) remains open. See [stable-readiness record](docs/release/v0.2.0-stable-readiness.md).
 - **Official A2A TCK results:** [Pinned JSON-RPC MUST report and reproduction](docs/testing/official-a2a-tck.md) — after Step 17-4: **63 passed / 1 failed / 171 skipped / 30 deselected** (pytest). The remaining `CORE-SEND-003` mismatch is tracked [upstream in #202](https://github.com/a2aproject/a2a-tck/issues/202). The TCK workflow is informational, **not** an A2A conformance certificate.
 
 - [A2Aの全体像（日本語・A4 1枚PDF）](docs/guides/a2a-protocol-overview-ja.pdf) — 登場人物・依頼の流れ・主要用語・MCPとの違いをまとめた学習資料。
@@ -23,10 +26,10 @@ Rails-native integration for exposing Rails applications as A2A v1.0 agents.
 
 **[a2a-rails-demo — independent Rails 8 Echo Agent](https://github.com/cuichangquan/a2a-rails-demo)**
 
-Run a complete standalone Rails Agent with the current unreleased `a2a-rails` source pinned by Git commit (the published RubyGems v0.1.0 does not contain direct-Message support). The separate Demo covers Agent Card discovery, JSON-RPC v1.0 SendMessage **Task and direct Message**, GetTask, ListTasks and error handling.
+Run a complete standalone Rails Agent using the **published RubyGems `a2a-rails = 0.2.0`** (not a Git source checkout). The separate Demo covers Agent Card discovery, JSON-RPC v1.0 SendMessage **Task and direct Message**, GetTask, ListTasks and error handling.
 
 - [Demo Quick Start, code and example curl requests](https://github.com/cuichangquan/a2a-rails-demo#quick-start).
-- [Demo GitHub Actions smoke](https://github.com/cuichangquan/a2a-rails-demo/actions/workflows/smoke.yml) — independent real HTTP tests **16/16 checks passed** ([PR #1](https://github.com/cuichangquan/a2a-rails-demo/pull/1)).
+- [Demo GitHub Actions smoke](https://github.com/cuichangquan/a2a-rails-demo/actions/workflows/smoke.yml) — independent Rails 8.1.0 / Ruby 3.4.10 HTTP smoke **16/16 checks passed** against published Gem `0.2.0` ([Step 28 Demo PR #2, merged](https://github.com/cuichangquan/a2a-rails-demo/pull/2), [passing PR CI](https://github.com/cuichangquan/a2a-rails-demo/actions/runs/37736426834)). The CI also confirms `A2A::Rails::VERSION == "0.2.0"`, RubyGems as the dependency source, and the demo's production-startup refusal.
 - **Local-only development/test** demo: no trusted verifier or durable Task store, **not** an internet-facing production template. See [production security](docs/guides/production-security.md).
 
 ## What is a2a-rails?
@@ -50,9 +53,9 @@ The Gem provides:
 - a Rails-native Agent / Skill DSL;
 - A2A Agent Card generation;
 - automatically mounted A2A HTTP endpoints;
-- synchronous Task execution by default, plus opt-in ActiveJob-backed async Task execution on unreleased `main`;
+- synchronous Task execution by default, plus opt-in ActiveJob-backed async Task execution in published `0.2.0`;
 - SDK-independent Handler inputs;
-- a process-local MemoryStore by default, plus an optional durable ActiveRecordStore on unreleased main;
+- a process-local MemoryStore by default, plus an optional durable ActiveRecordStore in `0.2.0`;
 - Rails generators for initial setup;
 - an internal Protocol Adapter boundary around the upstream SDK.
 
@@ -270,17 +273,17 @@ POST /a2a
 
 The Rails Engine is mounted automatically.
 
-### Security work on main (unreleased; not in published v0.1.0)
+### Security in v0.2.0 (not in v0.1.0)
 
-The unreleased `main` branch includes a host-provided `config.authenticate_request` callback for `POST /a2a`, plus per-principal Task ownership checks. Without an authenticator, production and other non-development/test environments fail closed; the local development/test Quick Start remains available. See [Authentication guide](docs/guides/authentication.md).
+Published `0.2.0` includes a host-provided `config.authenticate_request` callback for `POST /a2a`, plus per-principal Task ownership checks. Without an authenticator, production and other non-development/test environments fail closed; the local development/test Quick Start remains available. See [Authentication guide](docs/guides/authentication.md).
 
-> **Important:** These protections are **absent from RubyGems 0.1.0** but included in the published `0.2.0.rc2` pre-release; the stable candidate has additional fixes. Neither pre-release nor stable source automatically makes a deployed endpoint production-secure. Distributed rate limits, business authorization and the deployment review remain tracked in [Issue #11](https://github.com/cuichangquan/a2a-rails/issues/11).
+> **Important:** These protections are **absent from RubyGems 0.1.0** but included in the published `0.2.0.rc2` pre-release; stable `0.2.0` includes additional fixes. Neither pre-release nor stable source automatically makes a deployed endpoint production-secure. Distributed rate limits, business authorization and the deployment review remain tracked in [Issue #11](https://github.com/cuichangquan/a2a-rails/issues/11).
 
-### Step 16-4 request hardening (merged on main; unreleased)
+### Step 16-4 request hardening (included in v0.2.0)
 
-The unreleased main branch adds a bounded JSON-RPC body (`config.max_request_bytes`, default 1 MiB), Content-Type validation, stricter parameter checks, a pagination snapshot cap, and reduced exception logging. See [Request Hardening Guide](docs/guides/request-hardening.md).
+Published `0.2.0` includes a bounded JSON-RPC body (`config.max_request_bytes`, default 1 MiB), Content-Type validation, stricter parameter checks, a pagination snapshot cap, and reduced exception logging. See [Request Hardening Guide](docs/guides/request-hardening.md).
 
-Rate limiting, application-specific authorization and production deployment safeguards remain the host's responsibility or future work. Step 16-5 adds explicit A2A Agent Card Bearer authentication advertisement on unreleased `main`; it must match the host verifier. **These improvements are not included in the published v0.1.0 Gem; see the later rc2 pre-release and current stable candidate.**
+Rate limiting, application-specific authorization and production deployment safeguards remain the host's responsibility or future work. Step 16-5 adds explicit A2A Agent Card Bearer authentication advertisement in published `0.2.0`; it must match the host verifier. **These improvements are not included in the published v0.1.0 Gem; see the published stable `0.2.0` release.**
 
 ### Production deployment review (Step 16-6)
 
@@ -337,14 +340,14 @@ Hash / Array → Data Part
 nil          → no Artifact
 other object → ArtifactMappingError
 
-Unreleased Step 17-3 (not in RubyGems v0.1.0):
+Included since v0.2.0 (not in v0.1.0):
 A2A::Rails::FileArtifact.bytes(...) → File Part with base64 raw bytes
 A2A::Rails::FileArtifact.url(...)   → File Part with an HTTPS URL
 ```
 
-**File Artifact output is unreleased.** Rails Handlers can explicitly return a `FileArtifact.bytes(data:, filename:, media_type:)` or `FileArtifact.url(url:, filename:, media_type:)`. See the [File Artifact output guide](docs/guides/file-artifacts.md). Input file Parts, downloading remote URLs and production file authorization are not supplied by the Gem.
+**File Artifact output is included in v0.2.0.** Rails Handlers can explicitly return a `FileArtifact.bytes(data:, filename:, media_type:)` or `FileArtifact.url(url:, filename:, media_type:)`. See the [File Artifact output guide](docs/guides/file-artifacts.md). Input file Parts, downloading remote URLs and production file authorization are not supplied by the Gem.
 
-**Unreleased Step 17-4:** A2A v1.0 also permits a direct `Message` from `SendMessage`. The host Agent can opt into `response_mode :message` or select the mode using a callable; the default remains `:task`. Direct replies do **not** create Task records. See the [Direct Message response guide](docs/guides/direct-message-responses.md) for the contract and safety implications.
+**Included in v0.2.0 (Step 17-4):** A2A v1.0 also permits a direct `Message` from `SendMessage`. The host Agent can opt into `response_mode :message` or select the mode using a callable; the default remains `:task`. Direct replies do **not** create Task records. See the [Direct Message response guide](docs/guides/direct-message-responses.md) for the contract and safety implications.
 
 Supported Task operations:
 
@@ -357,9 +360,9 @@ Supported Task operations:
 
 The default `Task::MemoryStore` is thread-safe but process-local. Tasks and pagination cursors are not durable across process restarts and are not shared between processes.
 
-**Unreleased Step 21:** applications that need durable, multi-worker Task state can opt into `config.task_store = :active_record`. The ActiveRecordStore uses owner-scoped SQL access, row-locked transitions, signed keyset cursors, terminal retention, bounded pruning and maintenance limits. See [ActiveRecord Task Store](docs/guides/active-record-task-store.md). PostgreSQL 16 persistence/locking smoke is verified in CI.
+**Included in v0.2.0 (Step 21):** applications that need durable, multi-worker Task state can opt into `config.task_store = :active_record`. The ActiveRecordStore uses owner-scoped SQL access, row-locked transitions, signed keyset cursors, terminal retention, bounded pruning and maintenance limits. See [ActiveRecord Task Store](docs/guides/active-record-task-store.md). PostgreSQL 16 persistence/locking smoke is verified in CI.
 
-**Unreleased Step 22:** Task execution remains synchronous by default. Hosts can opt into ActiveJob-backed async execution globally, per Agent, or per Skill; precedence is **Skill > Agent > global**.
+**Included in v0.2.0 (Step 22):** Task execution remains synchronous by default. Hosts can opt into ActiveJob-backed async execution globally, per Agent, or per Skill; precedence is **Skill > Agent > global**.
 
 ```ruby
 A2A::Rails.configure do |config|
@@ -485,7 +488,7 @@ Artifact: Echo: Hello
 
 See [docs/release/v0.1.0-record.md](docs/release/v0.1.0-record.md) for the complete release evidence.
 
-## Cross-language A2A interoperability — unreleased main source
+## Cross-language A2A interoperability — source verification
 
 [Step 18 / PR #27](https://github.com/cuichangquan/a2a-rails/pull/27) verified the **official** Python `a2a-sdk==1.2.2` and Go `a2a-go/v2 v2.6.0` clients against a loopback-only Rails JSON-RPC A2A v1.0 Agent. Both discovered Agent Cards, decoded Task and direct Message responses, queried Tasks and checked terminal cancellation and version errors.
 

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

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require_relative "pinned_https_transport"
+
+module A2A
+  module Rails
+    class Client
+      # Internal A2A v1.0 JSON-RPC Agent Card discovery and RPC boundary.
+      #
+      # NOT a public Client facade: application authentication, DTO contracts,
+      # complete schema validation and multi-language HTTP integration follow
+      # in later Step 29 PRs. Default construction always uses the secure
+      # OutboundPolicy and PinnedHttpsTransport; injection is test-only.
+      class AgentCardResolver
+        class Error < A2A::Rails::Error
+          attr_reader :reason
+
+          def initialize(reason)
+            @reason = reason
+            super("Outbound A2A Agent Card rejected: #{reason}")
+          end
+        end
+
+        class InvalidCard < Error; end
+        class UnsupportedInterface < Error; end
+        class InvalidRPC < Error; end
+
+        class RemoteError < Error
+          attr_reader :code
+
+          def initialize(code)
+            @code = code
+            super(:remote_json_rpc_error)
+          end
+        end
+
+        Interface = Struct.new(:url, :tenant, keyword_init: true)
+        Discovery = Struct.new(:card, :interface, keyword_init: true)
+
+        JSONRPC_BINDING = "JSONRPC"
+        PROTOCOL_VERSION = "1.0"
+        METHODS = %w[SendMessage GetTask ListTasks CancelTask].freeze
+        MAX_INTERFACES = 64
+        MAX_SKILLS = 256
+
+        def initialize(agent_card_url:, allowed_origins: nil,
+                       card_authorization: nil, card_credential_origin: nil,
+                       authorization: nil, credential_origin: nil,
+                       policy: nil, transport: nil)
+          # Production callers must construct through the forthcoming public
+          # Client facade, which will not expose policy/transport overrides.
+          @policy = policy || OutboundPolicy.new(allowed_origins: allowed_origins)
+          @transport = transport || PinnedHttpsTransport.new(policy: @policy)
+          @agent_card_url = agent_card_url
+          @card_authorization = card_authorization
+          @card_credential_origin = card_credential_origin
+          @authorization = authorization
+          @credential_origin = credential_origin
+        end
+
+        # Re-fetch on each invocation; never share card/identity cache.
+        # The transport separately resolves and pins the card destination.
+        def discover
+          response = @transport.get_json(
+            url: @agent_card_url,
+            authorization: @card_authorization,
+            credential_origin: @card_credential_origin
+          )
+          card = response.json
+          validate_card!(card)
+          interface = choose_interface!(card.fetch("supportedInterfaces"))
+          Discovery.new(card: deep_freeze(card), interface: interface).freeze
+        end
+
+        # A thin INTERNAL wire operation, not the public SendMessage API.
+        # The supplied params use JSON/protocol camelCase, not Ruby DTO keys.
+        def rpc(method:, params:, id:)
+          unless METHODS.include?(method) && params.is_a?(Hash) &&
+              params.keys.all? { |key| key.is_a?(String) } &&
+              !params.key?("tenant") &&
+              (id.is_a?(String) && !id.empty? || id.is_a?(Integer))
+            raise InvalidRPC, :invalid_parameters
+          end
+
+          interface = discover.interface
+          request_params = params.dup
+          # A2A 1.0 puts the opaque tenant in the request's params, not the
+          # JSON-RPC envelope. The host is forbidden from overriding it.
+          request_params["tenant"] = interface.tenant unless interface.tenant.nil?
+          wire = {
+            "jsonrpc" => "2.0",
+            "id" => id,
+            "method" => method,
+            "params" => request_params
+          }
+          response = @transport.post_json(
+            url: interface.url, json: wire,
+            authorization: @authorization,
+            credential_origin: @credential_origin
+          )
+          envelope = response.json
+          unless envelope.is_a?(Hash) && envelope["jsonrpc"] == "2.0" &&
+              envelope["id"] == id &&
+              (envelope.key?("result") ^ envelope.key?("error"))
+            raise InvalidRPC, :invalid_envelope
+          end
+          if envelope.key?("error")
+            error = envelope["error"]
+            raise InvalidRPC, :invalid_envelope unless error.is_a?(Hash) && error["code"].is_a?(Integer)
+
+            # The remote error.message/data are untrusted, and may contain
+            # secrets. Never reflect them in exception messages or logs.
+            raise RemoteError, error.fetch("code")
+          end
+
+          raise InvalidRPC, :invalid_result unless envelope["result"].is_a?(Hash)
+
+          deep_freeze(envelope.fetch("result"))
+        end
+
+        private
+
+        def validate_card!(card)
+          unless card.is_a?(Hash) &&
+              %w[name description version].all? { |key| present_text?(card[key]) } &&
+              card["capabilities"].is_a?(Hash) &&
+              valid_mode_list?(card["defaultInputModes"]) &&
+              valid_mode_list?(card["defaultOutputModes"]) &&
+              card["skills"].is_a?(Array) && !card["skills"].empty? &&
+              card["skills"].size <= MAX_SKILLS &&
+              card["skills"].all? { |s| s.is_a?(Hash) && present_text?(s["id"]) } &&
+              card["supportedInterfaces"].is_a?(Array) &&
+              !card["supportedInterfaces"].empty? &&
+              card["supportedInterfaces"].size <= MAX_INTERFACES
+            raise InvalidCard, :invalid_card_shape
+          end
+
+          card.fetch("supportedInterfaces").each do |item|
+            unless item.is_a?(Hash) &&
+                present_text?(item["url"]) &&
+                present_text?(item["protocolBinding"]) &&
+                present_text?(item["protocolVersion"])
+              raise InvalidCard, :invalid_interface_shape
+            end
+          end
+        end
+
+        def choose_interface!(interfaces)
+          candidate = interfaces.find do |entry|
+            entry["protocolBinding"] == JSONRPC_BINDING &&
+              entry["protocolVersion"] == PROTOCOL_VERSION
+          end
+          raise UnsupportedInterface, :no_jsonrpc_v1_interface unless candidate
+
+          if candidate.key?("tenant") &&
+              (!candidate["tenant"].is_a?(String) || candidate["tenant"].bytesize > 512)
+            raise InvalidCard, :invalid_tenant
+          end
+
+          # Validate the UNTRUSTED card's selected endpoint independently of
+          # card origin; no guessed path, origin fallback or automatic retry.
+          target = @policy.resolve!(candidate.fetch("url"))
+          Interface.new(url: target.url, tenant: candidate["tenant"]&.dup&.freeze).freeze
+        end
+
+        def valid_mode_list?(value)
+          value.is_a?(Array) && !value.empty? &&
+            value.all? { |element| present_text?(element) }
+        end
+
+        def present_text?(value)
+          value.is_a?(String) && !value.strip.empty?
+        end
+
+        def deep_freeze(value)
+          case value
+          when Hash
+            value.each do |key, element|
+              deep_freeze(key)
+              deep_freeze(element)
+            end
+          when Array
+            value.each { |element| deep_freeze(element) }
+          end
+          value.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class Client
+      # Explicit A2A protocol keys only. Arbitrary JSON metadata/data and
+      # unknown extension fields are opaque and must NOT have keys rewritten.
+      module Codec
+        KEYS = {
+          "message_id" => "messageId",
+          "context_id" => "contextId",
+          "task_id" => "taskId",
+          "artifact_id" => "artifactId",
+          "media_type" => "mediaType",
+          "mime_type" => "mimeType",
+          "file_name" => "fileName",
+          "supported_interfaces" => "supportedInterfaces",
+          "protocol_binding" => "protocolBinding",
+          "protocol_version" => "protocolVersion",
+          "default_input_modes" => "defaultInputModes",
+          "default_output_modes" => "defaultOutputModes",
+          "input_modes" => "inputModes",
+          "output_modes" => "outputModes",
+          "accepted_output_modes" => "acceptedOutputModes",
+          "return_immediately" => "returnImmediately",
+          "history_length" => "historyLength",
+          "page_size" => "pageSize",
+          "page_token" => "pageToken",
+          "next_page_token" => "nextPageToken",
+          "total_size" => "totalSize",
+          "status_timestamp_after" => "statusTimestampAfter",
+          "include_artifacts" => "includeArtifacts",
+          "security_schemes" => "securitySchemes",
+          "security_requirements" => "securityRequirements",
+          "extended_agent_card" => "extendedAgentCard",
+          "push_notifications" => "pushNotifications"
+        }.freeze
+        REVERSE = KEYS.invert.freeze
+        OPAQUE = %w[data metadata extensions securitySchemes securityRequirements].freeze
+
+        module_function
+
+        def encode(value, opaque: false)
+          case value
+          when Hash
+            convert_hash(value, :encode, opaque: opaque)
+          when Array
+            value.map { |item| encode(item, opaque: opaque) }
+          else
+            value
+          end
+        end
+
+        def decode(value, opaque: false)
+          case value
+          when Hash
+            convert_hash(value, :decode, opaque: opaque)
+          when Array
+            value.map { |item| decode(item, opaque: opaque) }.freeze
+          when String
+            value.dup.freeze
+          else
+            value
+          end
+        end
+
+        def convert_hash(value, direction, opaque:)
+          result = {}
+          value.each do |raw_key, entry|
+            unless raw_key.is_a?(String) || raw_key.is_a?(Symbol)
+              raise InvalidInputError, :invalid_hash_key
+            end
+            key = raw_key.to_s
+            if direction == :encode
+              output = opaque ? key : KEYS.fetch(key, key)
+            else
+              output = !opaque && REVERSE.key?(key) ? REVERSE.fetch(key).to_sym :
+                (!opaque && KNOWN_KEYS.include?(key) ? key.to_sym : key)
+            end
+            raise InvalidInputError, :ambiguous_protocol_key if result.key?(output)
+            child_opaque = opaque || OPAQUE.include?(key) || OPAQUE.include?(output.to_s)
+            result[output] = if direction == :encode
+              encode(entry, opaque: child_opaque)
+            else
+              decode(entry, opaque: child_opaque)
+            end
+          end
+          direction == :decode ? result.freeze : result
+        end
+
+        KNOWN_KEYS = %w[
+          id name description version skills capabilities streaming
+          role parts text raw url data filename mimeType mediaType
+          status state timestamp artifacts history message task tasks extensions
+          tenant contextId messageId taskId artifactId
+          supportedInterfaces protocolBinding protocolVersion
+          defaultInputModes defaultOutputModes inputModes outputModes
+          acceptedOutputModes returnImmediately historyLength
+          pageSize pageToken nextPageToken totalSize
+          statusTimestampAfter includeArtifacts metadata
+          securitySchemes securityRequirements
+        ].freeze
+      end
+    end
+  end
+end