Repository navigation
Commit f3ac824
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
- samples
- tests/integration
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
136 | 136 | | |
137 | 137 | | |
138 | 138 | | |
| 139 | + | |
139 | 140 | | |
140 | 141 | | |
141 | 142 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| 11 | + | |
11 | 12 | | |
12 | 13 | | |
13 | 14 | | |
| |||
56 | 57 | | |
57 | 58 | | |
58 | 59 | | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
0 commit comments