Skip to content

fix(agent-card): serialize every card map deterministically - #566

Open
chopmob-cloud wants to merge 1 commit into
a2aproject:mainfrom
chopmob-cloud:fix/361-deterministic-security-requirements
Open

chopmob-cloud wants to merge 1 commit into
a2aproject:mainfrom
chopmob-cloud:fix/361-deterministic-security-requirements

Conversation

@chopmob-cloud

@chopmob-cloud chopmob-cloud commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Addresses #361 (follow-up to #359/#334): items 1 to 3 of its scope.

1. Deterministic key order, for every map in the card

A card's maps are HashMaps, so a card rebuilt from the same values serialized to different bytes each time. Measured on this branch before the change, 60 rebuilds of one card gave:

Map Distinct strings over 60 rebuilds
securitySchemes alone 60
extension params alone 22
signature header alone 2
the whole card 60

The requirement's own schemes were fixed by the first revision of this branch (56 distinct before, 1 after). The four maps around them were not, which is why #361's acceptance line, "a card serializes identically on every run", was not met.

All of them now sort their keys at the serialization boundary, with one helper per shape (serialize_sorted_map and serialize_optional_sorted_map), so the public fields stay HashMaps and no construction site changes:

  • AgentCard.security_schemes
  • AgentExtension.params
  • AgentCardSignature.header
  • the scopes map of all five OAuth flows

After the change, every row above is 1.

A card is then reproducible for diffs and for a content-hash ETag, one of the forms section 8.6.1 allows. Signatures are unaffected: section 8.4.1 canonicalises with JCS, which orders keys itself.

2. Empty scope list

An empty StringList is omitted, so an empty scope set serializes as {} rather than {"list": []}, matching canonical ProtoJSON as written by a2a-pb and the Python SDK. A proto reader treats them the same; this pins the form.

3. Regression tests

  • one exact expected string for a card carrying six schemes, four extension params, three OAuth scopes and a two-entry signature header, rebuilt inside the loop for 60 runs
  • the exact expected string for a six-scheme requirement, which checks sorted order and framing together
  • the empty-list form ({})
  • a scheme literally named schemes
  • empty requirements in both shapes ([{}] and [{"schemes":{}}]) round-trip
  • legacy flat input ({"bearer": ["read"]}) still parses

The determinism test builds the card inside the loop, so it sees maps the serializer rebuilds. Each of the five edits is load-bearing: removing any one of the four serde attributes, or reverting the BTreeMap, fails it. Each was checked separately.

Not done

Item 4, checking a card from a2a-lf against the Python SDK 1.x parser, is an external cross-check and is not included here.

Verification

cargo test -p a2a-lf (101 passed), cargo fmt --all --check, cargo clippy -p a2a-lf --all-targets, and the full workspace test, run on a clean Linux host.

@chopmob-cloud
chopmob-cloud requested a review from a team as a code owner November 19, 2026 19:35
@codecov

codecov Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.85714% with 2 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
a2a/src/agent_card.rs 98.85% 2 Missing ⚠️

📢 Thoughts on this report? Let us know!

@chopmob-cloud
chopmob-cloud force-pushed the fix/361-deterministic-security-requirements branch from 04e6c63 to 0556853 Compare November 19, 2026 20:50

@muscariello muscariello left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The change is correct and CI is green. Writing {} for an empty scope list matches what a2a-go already emits (securityScopeList.MarshalJSON) and what ProtoJSON produces, and it is the form spec §8.4.1 needs before signing (default values omitted). I reverted each of the two edits and the matching test fails, as the description says.

  1. Cards are not byte-stable yet. Only the requirement's schemes moved to a BTreeMap. AgentCard.security_schemes is still a HashMap<String, SecurityScheme>, and so are AgentExtension.params, the OAuth flows' scopes and the signature header. On this head, 60 freshly built cards with six securitySchemes serialize to 55–59 distinct strings, and the order differs between processes; the requirements are stable (1 of 60). So "byte-stable for diffs, caching and signing" holds for requirements only, and the acceptance line of #361 ("a card serializes identically on every run") is not met. Either sort those maps the same way (one helper for serialize_with covers them) or narrow the description and keep #361 open with them listed.
  2. The determinism test cannot see them. It serializes one card 60 times, and that is stable for any map the serializer does not rebuild (the same card with securitySchemes gives 1 distinct string). Building the card inside the loop catches both.
  3. Signing. Item 1 does not affect signatures, since JCS sorts keys; item 2 does. The spec reference is the better justification in the comment and commit.

Nit: the order assertion finds each name by substring position; comparing with the exact expected string is simpler.

…ct#361)

A card's maps are HashMaps, so a card rebuilt from the same values serialized
to different bytes each time: 60 rebuilds of one card gave 60 distinct strings.
Measured the same way, securitySchemes alone accounted for 60, extension params
for 22 and the signature header for 2. A six-scheme requirement gave 56 distinct
strings, as a2aproject#361 reports, until this branch sorted its schemes.

Sort keys at the serialization boundary with one helper per shape, so the public
fields stay HashMaps and no construction site changes. Covers a requirement's
schemes, AgentCard.security_schemes, AgentExtension.params,
AgentCardSignature.header and the scopes map of all five OAuth flows.

A card is then reproducible for diffs and for a content hash, one of the ETag
forms section 8.6.1 allows. Signatures are unaffected: section 8.4.1
canonicalises with JCS, which already orders keys.

An empty scope list serializes as {} rather than {"list": []}, the ProtoJSON
form a2a-pb and the Python SDK emit; a proto reader treats them the same.

The determinism test builds a card carrying every one of these maps inside the
loop and compares 60 runs against one exact string. Removing any one of the four
serde attributes, or reverting the BTreeMap, fails it; each was checked
separately.

Signed-off-by: AlgoVoi <chopmob@gmail.com>
@chopmob-cloud
chopmob-cloud force-pushed the fix/361-deterministic-security-requirements branch from 0556853 to 41a7a1d Compare November 20, 2026 21:07
@chopmob-cloud

chopmob-cloud commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author

All three points hold, and the first one is fixed on this head rather than narrowed. Rebuilding a card with six schemes, four extension params, three OAuth scopes and a two-entry signature header gave this before the change:

  • securitySchemes alone: 60 distinct strings out of 60 rebuilds
  • extension params alone: 22
  • signature header alone: 2
  • the whole card: 60

And after it, 1 for each. Sorting is done at the serialization boundary with one helper per shape (serialize_sorted_map and its optional form), so the public fields stay HashMaps and no construction site changes:

  • a requirement's schemes, already a BTreeMap in the serializer
  • AgentCard.security_schemes
  • AgentExtension.params
  • AgentCardSignature.header
  • the scopes map of all five OAuth flows

On the second point, you were right about why the old test could not see them: it serialized one card 60 times, which is stable for any map the serializer does not rebuild. The test now builds the card inside the loop, with every one of those maps populated, and compares 60 runs against one exact string. Removing any single one of the four serde attributes makes it fail, and so does reverting the BTreeMap; I checked each of the five separately rather than assuming.

On the third, the comment and commit now cite section 8.6.1 (a content hash is one of the ETag forms the section allows) and say explicitly that signatures are unaffected because section 8.4.1 canonicalises with JCS, which orders keys itself. The nit is taken as well: the requirement test compares the exact expected string instead of looking for substring positions.

cargo test -p a2a-lf, cargo fmt --all --check, cargo clippy -p a2a-lf --all-targets and the full workspace test are clean on this head.

@chopmob-cloud chopmob-cloud changed the title fix(agent-card): serialize security requirements deterministically fix(agent-card): serialize every card map deterministically Nov 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants