feat: Implement Agent Card Signing and Verification per Spec (#581)

This PR introduces digital signatures for Agent Cards to ensure
authenticity and integrity, adhering to the A2A specification for [Agent
Card Signing (Section
8.4).](https://a2a-protocol.org/latest/specification/#84-agent-card-signing)

## Changes:
- Implement `Canonicalization` Logic (`src/a2a/utils/signing.py`)
- Add `Signing` and `Verification` Utilities
(`src/a2a/utils/signing.py`):
- `create_agent_card_signer` which generates an `agent_card_signer` for
signing `AgentCards`
- `create_signature_verifier` which generates a `signature_verifier` for
verification of `AgentCard` signatures
- Enable signature verification support for `json-rpc`, `rest` and
`gRPC` transports
- Add Protobuf Conversion for Signatures
(`src/a2a/utils/proto_utils.py`) ensuring `AgentCardSignature` can be
serialized and deserialized for gRPC transport
- Add related tests:
   - integration tests for fetching signed cards from the Server
   - unit tests for signing util
   - unit tests for protobuf conversions 



- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- Important Prefixes for
[release-please](https://github.com/googleapis/release-please):
- `fix:` which represents bug fixes, and correlates to a
[SemVer](https://semver.org/) patch.
- `feat:` represents a new feature, and correlates to a SemVer minor.
- `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking
change (indicated by the `!`) and will result in a SemVer major.
- [x] Ensure the tests and linter pass (Run `bash scripts/format.sh`
from the repository root to format)
- [x] Appropriate docs were updated (if necessary)

Release-As: 0.3.21

Author: sokoliva

.github/actions/spelling/allow.txt

@@ -47,9 +47,14 @@ initdb
 inmemory
 INR
 isready
+jku
 JPY
 JSONRPCt
+jwk
+jwks
 JWS
+jws
+kid
 kwarg
 langgraph
 lifecycles

pyproject.toml

@@ -35,6 +35,7 @@ grpc = ["grpcio>=1.60", "grpcio-tools>=1.60", "grpcio_reflection>=1.7.0"]
 telemetry = ["opentelemetry-api>=1.33.0", "opentelemetry-sdk>=1.33.0"]
 postgresql = ["sqlalchemy[asyncio,postgresql-asyncpg]>=2.0.0"]
 mysql = ["sqlalchemy[asyncio,aiomysql]>=2.0.0"]
+signing = ["PyJWT>=2.0.0"]
 sqlite = ["sqlalchemy[asyncio,aiosqlite]>=2.0.0"]
 
 sql = ["a2a-sdk[postgresql,mysql,sqlite]"]
@@ -45,6 +46,7 @@ all = [
   "a2a-sdk[encryption]",
   "a2a-sdk[grpc]",
   "a2a-sdk[telemetry]",
+  "a2a-sdk[signing]",
 ]
 
 [project.urls]
@@ -86,6 +88,7 @@ style = "pep440"
 dev = [
   "datamodel-code-generator>=0.30.0",
   "mypy>=1.15.0",
+  "PyJWT>=2.0.0",
   "pytest>=8.3.5",
   "pytest-asyncio>=0.26.0",
   "pytest-cov>=6.1.1",

src/a2a/client/base_client.py

@@ -1,4 +1,4 @@
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Callable
 from typing import Any
 
 from a2a.client.client import (
@@ -261,6 +261,7 @@ async def get_card(
         *,
         context: ClientCallContext | None = None,
         extensions: list[str] | None = None,
+        signature_verifier: Callable[[AgentCard], None] | None = None,
     ) -> AgentCard:
         """Retrieves the agent's card.
 
@@ -270,12 +271,15 @@ async def get_card(
         Args:
             context: The client call context.
             extensions: List of extensions to be activated.
+            signature_verifier: A callable used to verify the agent card's signatures.
 
         Returns:
             The `AgentCard` for the agent.
         """
         card = await self._transport.get_card(
-            context=context, extensions=extensions
+            context=context,
+            extensions=extensions,
+            signature_verifier=signature_verifier,
         )
         self._card = card
         return card

src/a2a/client/client.py

@@ -185,6 +185,7 @@ async def get_card(
         *,
         context: ClientCallContext | None = None,
         extensions: list[str] | None = None,
+        signature_verifier: Callable[[AgentCard], None] | None = None,
     ) -> AgentCard:
         """Retrieves the agent's card."""
 

src/a2a/client/transports/base.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Callable
 
 from a2a.client.middleware import ClientCallContext
 from a2a.types import (
@@ -103,6 +103,7 @@ async def get_card(
         *,
         context: ClientCallContext | None = None,
         extensions: list[str] | None = None,
+        signature_verifier: Callable[[AgentCard], None] | None = None,
     ) -> AgentCard:
         """Retrieves the AgentCard."""
 

src/a2a/client/transports/grpc.py

@@ -1,6 +1,6 @@
 import logging
 
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Callable
 
 
 try:
@@ -223,6 +223,7 @@ async def get_card(
         *,
         context: ClientCallContext | None = None,
         extensions: list[str] | None = None,
+        signature_verifier: Callable[[AgentCard], None] | None = None,
     ) -> AgentCard:
         """Retrieves the agent's card."""
         card = self.agent_card
@@ -236,6 +237,9 @@ async def get_card(
             metadata=self._get_grpc_metadata(extensions),
         )
         card = proto_utils.FromProto.agent_card(card_pb)
+        if signature_verifier is not None:
+            signature_verifier(card)
+
         self.agent_card = card
         self._needs_extended_card = False
         return card

src/a2a/client/transports/jsonrpc.py

@@ -1,7 +1,7 @@
 import json
 import logging
 
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Callable
 from typing import Any
 from uuid import uuid4
 
@@ -379,16 +379,20 @@ async def get_card(
         *,
         context: ClientCallContext | None = None,
         extensions: list[str] | None = None,
+        signature_verifier: Callable[[AgentCard], None] | None = None,
     ) -> AgentCard:
         """Retrieves the agent's card."""
         modified_kwargs = update_extension_header(
             self._get_http_args(context),
             extensions if extensions is not None else self.extensions,
         )
         card = self.agent_card
+
         if not card:
             resolver = A2ACardResolver(self.httpx_client, self.url)
             card = await resolver.get_agent_card(http_kwargs=modified_kwargs)
+            if signature_verifier is not None:
+                signature_verifier(card)
             self._needs_extended_card = (
                 card.supports_authenticated_extended_card
             )
@@ -413,9 +417,13 @@ async def get_card(
         )
         if isinstance(response.root, JSONRPCErrorResponse):
             raise A2AClientJSONRPCError(response.root)
-        self.agent_card = response.root.result
+        card = response.root.result
+        if signature_verifier is not None:
+            signature_verifier(card)
+
+        self.agent_card = card
         self._needs_extended_card = False
-        return self.agent_card
+        return card
 
     async def close(self) -> None:
         """Closes the httpx client."""

src/a2a/client/transports/rest.py

@@ -1,7 +1,7 @@
 import json
 import logging
 
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Callable
 from typing import Any
 
 import httpx
@@ -371,16 +371,20 @@ async def get_card(
         *,
         context: ClientCallContext | None = None,
         extensions: list[str] | None = None,
+        signature_verifier: Callable[[AgentCard], None] | None = None,
     ) -> AgentCard:
         """Retrieves the agent's card."""
         modified_kwargs = update_extension_header(
             self._get_http_args(context),
             extensions if extensions is not None else self.extensions,
         )
         card = self.agent_card
+
         if not card:
             resolver = A2ACardResolver(self.httpx_client, self.url)
             card = await resolver.get_agent_card(http_kwargs=modified_kwargs)
+            if signature_verifier is not None:
+                signature_verifier(card)
             self._needs_extended_card = (
                 card.supports_authenticated_extended_card
             )
@@ -398,6 +402,9 @@ async def get_card(
             '/v1/card', {}, modified_kwargs
         )
         card = AgentCard.model_validate(response_data)
+        if signature_verifier is not None:
+            signature_verifier(card)
+
         self.agent_card = card
         self._needs_extended_card = False
         return card

src/a2a/utils/helpers.py

@@ -2,13 +2,15 @@
 
 import functools
 import inspect
+import json
 import logging
 
 from collections.abc import Callable
 from typing import Any
 from uuid import uuid4
 
 from a2a.types import (
+    AgentCard,
     Artifact,
     MessageSendParams,
     Part,
@@ -340,3 +342,29 @@ def are_modalities_compatible(
         return True
 
     return any(x in server_output_modes for x in client_output_modes)
+
+
+def _clean_empty(d: Any) -> Any:
+    """Recursively remove empty strings, lists and dicts from a dictionary."""
+    if isinstance(d, dict):
+        cleaned_dict: dict[Any, Any] = {
+            k: _clean_empty(v) for k, v in d.items()
+        }
+        return {k: v for k, v in cleaned_dict.items() if v}
+    if isinstance(d, list):
+        cleaned_list: list[Any] = [_clean_empty(v) for v in d]
+        return [v for v in cleaned_list if v]
+    return d if d not in ['', [], {}] else None
+
+
+def canonicalize_agent_card(agent_card: AgentCard) -> str:
+    """Canonicalizes the Agent Card JSON according to RFC 8785 (JCS)."""
+    card_dict = agent_card.model_dump(
+        exclude={'signatures'},
+        exclude_defaults=True,
+        exclude_none=True,
+        by_alias=True,
+    )
+    # Recursively remove empty values
+    cleaned_dict = _clean_empty(card_dict)
+    return json.dumps(cleaned_dict, separators=(',', ':'), sort_keys=True)

src/a2a/utils/proto_utils.py

@@ -397,6 +397,21 @@ def agent_card(
             ]
             if card.additional_interfaces
             else None,
+            signatures=[cls.agent_card_signature(x) for x in card.signatures]
+            if card.signatures
+            else None,
+        )
+
+    @classmethod
+    def agent_card_signature(
+        cls, signature: types.AgentCardSignature
+    ) -> a2a_pb2.AgentCardSignature:
+        return a2a_pb2.AgentCardSignature(
+            protected=signature.protected,
+            signature=signature.signature,
+            header=dict_to_struct(signature.header)
+            if signature.header is not None
+            else None,
         )
 
     @classmethod
@@ -865,6 +880,19 @@ def agent_card(
             ]
             if card.additional_interfaces
             else None,
+            signatures=[cls.agent_card_signature(x) for x in card.signatures]
+            if card.signatures
+            else None,
+        )
+
+    @classmethod
+    def agent_card_signature(
+        cls, signature: a2a_pb2.AgentCardSignature
+    ) -> types.AgentCardSignature:
+        return types.AgentCardSignature(
+            protected=signature.protected,
+            signature=signature.signature,
+            header=json_format.MessageToDict(signature.header),
         )
 
     @classmethod