Skip to content

Commit f3ac824

Browse files
orangecolaclaudemykytanetipa
authored
docs(samples): add Agent Card signing sample (a2aproject#1198)
There was no runnable example for `a2a.utils.signing`, so this adds one covering both halves of Agent Card signing. `samples/agent_card_signing.py`: - **Server**: generates an ES256 key, signs the Agent Card with `create_agent_card_signer`, serves it via `create_agent_card_routes(card_modifier=...)`, and publishes the public key as a JWKS document at `/.well-known/jwks.json` — the URL the signature's `jku` points to. - **Client**: verifies the card with `create_signature_verifier` passed to `A2ACardResolver.get_agent_card(signature_verifier=...)`, resolving keys by `kid` from an allowlist of pinned JWKS URLs, with algorithms pinned to `ES256`. - **Modes**: `demo` (default, runs both in-process), `serve`, `verify --url`. The default `demo` mode verifies the genuine card and then shows the three rejections a verifier exists for: ``` 1. The card served by the agent verified card for agent: Signed Card Agent protected header: {'alg': 'ES256', 'jku': '.../.well-known/jwks.json', 'kid': 'sample-card-key-1', 'typ': 'JOSE'} 2. A card whose transport URL was rewritten in transit rejected as expected: No valid signature found 3. A card with its signature stripped off rejected as expected: AgentCard has no signatures to verify. 4. The genuine card, checked by a client that pins other keys rejected as expected: No valid signature found ``` Two non-obvious details are called out in comments, since they bite anyone copying the pattern: - The verifier is a **synchronous** callable, so fetching the JWKS inside it with a sync HTTP client blocks the event loop (it deadlocks against an in-process server and reports `No valid signature found`). The key provider does pure in-memory lookups over JWKS prefetched asynchronously. - `create_agent_card_signer` **mutates** the card it signs, so a per-request `card_modifier` would accumulate signatures. The helper deep-copies first and the card is signed once at startup. The key provider also raises `PyJWKError` rather than a plain exception, so the verifier treats one unusable signature as unverifiable and moves to the next instead of aborting a card that also carries a good signature. Also adds `tests/integration/test_agent_card_signing_smoke.py` (runs the demo on a free port, asserts one acceptance and three rejections) and a `samples/README.md` section. No library code changed — samples, tests and docs only. ## Testing - `uv run pytest tests/utils/test_signing.py tests/integration/test_agent_card_signing_smoke.py tests/client/test_card_resolver.py` → 55 passed - `uv run ruff format --check` and `uv run ruff check` → clean - `uv run ty check` → same 4 pre-existing diagnostics as `main` (samples are outside `[tool.ty.src]`) ## Checklist - [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. - [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) Fixes a2aproject#1197 🦕 --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: mykytanetipa <mykytanetipa@google.com>
1 parent a4c68f6 commit f3ac824

4 files changed

Lines changed: 616 additions & 0 deletions

File tree

‎.github/actions/spelling/allow.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ rmi
136136
RS256
137137
RUF
138138
Rundgren
139+
SECP
139140
SECP256R1
140141
SFIXED
141142
SLF

‎samples/README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This directory contains runnable examples demonstrating how to build and interac
88
|---|---|---|
99
| `hello_world_agent.py` | **Server** | A2A agent server |
1010
| `cli.py` | **Client** | Interactive terminal client |
11+
| `agent_card_signing.py` | **Server + Client** | Signing and verifying an Agent Card |
1112

1213
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.
1314
---
@@ -56,3 +57,30 @@ uv run python samples/cli.py --url http://192.168.1.10:41241 --transport GRPC
5657
Then type a message like `hello` and press Enter.
5758

5859
Type `/quit` or `/exit` to stop, or press `Ctrl+C`.
60+
61+
---
62+
63+
## `agent_card_signing.py` — Agent Card Signing
64+
65+
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.
66+
67+
Demonstrates:
68+
- 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=...)`
69+
- Publishing the matching public key as a JWKS document at `/.well-known/jwks.json`, referenced by the signature's `jku` header
70+
- 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`)
71+
- Pinning trust: the verifier accepts keys only from an allowlist of JWKS URLs and only signatures using an allowlisted algorithm
72+
73+
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.
74+
75+
**Run:**
76+
77+
```bash
78+
# Server and client together (default):
79+
uv run python samples/agent_card_signing.py
80+
81+
# Or run the two halves separately:
82+
uv run python samples/agent_card_signing.py serve
83+
uv run python samples/agent_card_signing.py verify --url http://127.0.0.1:41242
84+
```
85+
86+
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.

0 commit comments

Comments
 (0)