Agent Card signature verification (spec §8.4) is missing from the Java SDK

Open
#1,299 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
java

Research direction

Start by reading the Java SDK’s AgentCardSignature record and A2ACardResolver, then compare the Python signing interoperability vectors and canonicalization vectors named in the issue. Before implementation, agree on the verification scope, shared module location, and resolver integration; the issue also flags unresolved canonicalization details in spec issue #2122. Done means Java verifies the agreed interoperable cases and rejects the specified invalid signatures.

Written by the indexing model from the issue text.

Description

The A2A spec defines JWS signatures over the Agent Card in §8.4, and the other SDKs implement them:

  • a2a-python — src/a2a/utils/signing.py plus _jcs.py for RFC 8785 canonicalization
  • a2a-js — src/signature.ts
  • a2a-go — a2acrypto/

In a2a-java there is nothing behind it. AgentCardSignature in spec is a data record that carries protected, signature and header, and A2ACardResolver fetches a card and deserializes it with no verification step and no hook to add one. So a Java client cannot tell a signed card from an unsigned one, and the signatures field it parses is decoration.

That matters most where the card is fetched over a channel the client does not fully control, or served by a registry rather than the agent itself — which is the case §8.4 exists for.

What I would like to agree on before writing anything

  1. Scope of a first slice. Verification only — verify(AgentCard, PublicKey) / a JWKSet-backed resolver — with signing left for later, or both at once?
  2. Where it lives. A new spec-adjacent module, or http-client next to A2ACardResolver? It needs to be usable from the gRPC and REST transports too, which argues for somewhere neutral.
  3. How it plugs into A2ACardResolver. Opt-in strategy object, default no-op? I would rather not change the default behaviour of a card fetch in a patch release.
  4. Dependencies. ES256 is reachable through the JDK's own JCA (SHA256withECDSAinP1363Format), and RFC 8785 canonicalization is a few hundred lines, so this can land with no new dependency. The alternative is nimbus-jose-jwt. I lean to no new dependency; say the word if you would rather have the library.

On interop testing. a2a-python publishes language-neutral vectors — tests/utils/signing_interop_vectors.json (MUST-ACCEPT and MUST-REJECT cases with expected canonical bytes and a published test key) and jcs_vectors.json. Those make the whole thing verifiable offline with no network and no credentials, and they pin us to the same canonical bytes the other SDKs produce.

One caveat worth stating up front: spec issue #2122 notes that §8.4.1 canonicalization is under-determined and that two SDKs disagree on parts of it. I would scope the first slice to the vectors that do not depend on that ambiguity, and leave the disputed cases until the spec settles, rather than encoding one SDK's reading into Java.

Happy to take this on if the direction is right — I would rather agree on 1–3 first than send a PR that guesses.

Dominant language
Java
Stars
514
Forks
200
Avg merge
1d 2h
Merged PRs (30d)
53

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from a2aproject/a2a-java

All issues in a2aproject/a2a-java

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.