Repository navigation
fix(agent-card): serialize every card map deterministically - #566
chopmob-cloud wants to merge 1 commit into
Conversation
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
04e6c63 to
0556853
Compare
muscariello
left a comment
There was a problem hiding this comment.
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.
- Cards are not byte-stable yet. Only the requirement's schemes moved to a
BTreeMap.AgentCard.security_schemesis still aHashMap<String, SecurityScheme>, and so areAgentExtension.params, the OAuth flows'scopesand the signatureheader. On this head, 60 freshly built cards with sixsecuritySchemesserialize 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 forserialize_withcovers them) or narrow the description and keep #361 open with them listed. - 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
securitySchemesgives 1 distinct string). Building the card inside the loop catches both. - 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>
0556853 to
41a7a1d
Compare
|
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:
And after it, 1 for each. Sorting is done at the serialization boundary with one helper per shape (
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 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.
|
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:securitySchemesaloneparamsaloneheaderaloneThe 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_mapandserialize_optional_sorted_map), so the public fields stayHashMaps and no construction site changes:AgentCard.security_schemesAgentExtension.paramsAgentCardSignature.headerscopesmap of all five OAuth flowsAfter 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
StringListis 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
{})schemes[{}]and[{"schemes":{}}]) round-trip{"bearer": ["read"]}) still parsesThe 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
serdeattributes, or reverting theBTreeMap, 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.