fix(federation): share the registration cache fairly between superiors

[osanderson]

Summary

The automatic-registration cache now limits how much of it any one federation member can occupy:

• per immediate superior: at most 512 entries;
• per branch of a Trust Anchor: at most 2048;
• overall: 4096, unchanged.

An intermediate that mints many Relying Parties can now only ever displace its own entries.

Merge after the v0.52.0 release PR (#616). This is a non-breaking fix intended for v0.52.1.

Why

From the v0.52.0 pre-release review. Since #610 the cache was capped at 4096, and once full it cached nothing new rather than evict a still-valid entry. That stopped an attacker pushing busy clients out. But an intermediate that minted and refreshed 4096 Relying Parties once per cache lifetime could keep the cache full indefinitely, so every other federation client paid a full Trust Chain resolution on every request.

Design

Each cached registration records where it sits in its resolved Trust Chain (ResolvedEntity.Chain):

• its immediate superior: Chain[1], the entity that issued its Subordinate Statement and the only one able to mint Relying Parties beside it;
• its branch: Chain[len-2], the Trust Anchor's own subordinate the chain runs through. This also covers the intermediates an attacker-controlled intermediate mints beneath itself, each of which would otherwise be a new "superior" with its own quota.

Policy on insert:

Situation	Outcome
Superior at its quota (512)	Evict that superior's own oldest entry, then cache.
Branch at its cap (2048)	Drop expired entries; if still at the cap, don't cache.
Whole cache full (4096)	Drop expired entries; if still full, don't cache.
Directly under a Trust Anchor (no branch)	Counted only against the overall 4096. Such a Relying Party can't mint siblings, and the Trust Anchor is trusted.

A still-valid entry is never evicted for another superior's registration.

Cost:

• lookups stay O(1), and so does an eviction (a per-superior list in insertion order);
• the expired-entry sweep runs only when a limit is reached, as before;
• an entry found expired on lookup is still removed, releasing its counts.

The cache moves into its own unexported type (federation/registration_cache.go). AutomaticRegistrationConfig.MaxCacheAge's doc and the federation guide describe the policy.

Verification

• New tests:
  • the attack: one intermediate minting 3× its quota keeps exactly its newest 512, and Relying Parties under other superiors stay and get cached;
  • nested sub-intermediates filling a branch;
  • a full cache never evicting a valid entry;
  • Trust-Anchor leaves having no per-superior quota;
  • refresh moving an entry to the back without double-counting;
  • expiry on lookup releasing counts;
  • chainPosition;
  • an end-to-end check that a real resolution records the chain position (via a test-only accessor in export_test.go).
• Existing cache tests pass, ported to the new type.
• Mutation checks: 8 mutants, all caught:
  • no own-superior eviction;
  • no branch cap;
  • evicting instead of skipping when full;
  • expired entries kept on lookup;
  • branch counts not released;
  • a quota applied to Trust-Anchor leaves;
  • register dropping the chain position;
  • the wrong branch computed.
• Wider checks, all clean:
  • go vet, and go test on Go 1.27 and 1.26.9;
  • go test -race ./federation/...;
  • golangci-lint (0 issues), and the GOOS=linux GOARCH=arm vet;
  • every example module's vet and -race tests, including federated-union.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud