docs(samples): add Agent Card signing sample

.github/actions/spelling/allow.txt

@@ -1,4 +1,4 @@
 a2a
 A2A
 A2AFastAPI
 AAgent
@@ -28,7 +28,7 @@
 AUser
 autouse
 backticks
 base64url
 buf
 bufbuild
 cla
@@ -46,7 +46,7 @@
 drivername
 DSNs
 dunders
 ES256
 euo
 EUR
 evt
@@ -62,8 +62,8 @@
 gowebpki
 GVsb
 hazmat
 HS256
 HS384
 ietf
 importlib
 initdb
@@ -106,10 +106,10 @@
 Oneof
 OpenAPI
 openapiv
 openapiv2
 opensource
 otherurl
 pb2
 podman
 Podman
 poolclass
@@ -132,9 +132,10 @@
 respx
 resub
 rmi
 RS256
 RUF
 Rundgren
+SECP
 SECP256R1
 SFIXED
 SLF

samples/README.md

@@ -8,6 +8,7 @@ This directory contains runnable examples demonstrating how to build and interac
 |---|---|---|
 | `hello_world_agent.py` | **Server** | A2A agent server |
 | `cli.py` | **Client** | Interactive terminal client |
+| `agent_card_signing.py` | **Server + Client** | Signing and verifying an Agent Card |
 
 The samples are designed to work together out of the box: the agent listens on `http://127.0.0.1:41241`, which is the default URL used by the client.
 ---
@@ -56,3 +57,30 @@ uv run python samples/cli.py --url http://192.168.1.10:41241 --transport GRPC
 Then type a message like `hello` and press Enter.
 
 Type `/quit` or `/exit` to stop, or press `Ctrl+C`.
+
+---
+
+## `agent_card_signing.py` — Agent Card Signing
+
+An Agent Card is fetched before any trust has been established with the agent, so everything in it — transport URLs, security schemes, skills — is attacker-controlled until it is verified. This sample signs a card on the server and verifies it on the client.
+
+Demonstrates:
+- Signing the Agent Card with an ES256 key via `create_agent_card_signer`, wired into the card endpoint through `create_agent_card_routes(card_modifier=...)`
+- Publishing the matching public key as a JWKS document at `/.well-known/jwks.json`, referenced by the signature's `jku` header
+- Verifying the card with `create_signature_verifier`, passed to `A2ACardResolver.get_agent_card(signature_verifier=...)` (the same argument is accepted by `ClientFactory.create_from_url`)
+- Pinning trust: the verifier accepts keys only from an allowlist of JWKS URLs and only signatures using an allowlisted algorithm
+
+The default `demo` mode starts the server, verifies its card, and then shows the three failures a verifier exists to catch: a card whose transport URL was rewritten in transit, a card with its signature stripped, and a genuine card whose `jku` the client does not trust.
+
+**Run:**
+
+```bash
+# Server and client together (default):
+uv run python samples/agent_card_signing.py
+
+# Or run the two halves separately:
+uv run python samples/agent_card_signing.py serve
+uv run python samples/agent_card_signing.py verify --url http://127.0.0.1:41242
+```
+
+Requires the `signing`, `encryption` and `fastapi` extras (`pip install 'a2a-sdk[signing,encryption,fastapi]'`); they are already present when working from a `uv sync` of this repo.