docs(examples): add the federated-union OpenID Federation demo

[osanderson]

Summary

A runnable showcase in the style of OID4VCgo's passport-vdc. Three fictional countries (Northland, Southport, Eastmark) each run their own identity federation, then join the Meridian Union, an OpenID Federation 1.0 trust anchor above them. A service in one country signs in a citizen of another, with no registration on either side beforehand.

cd examples/federated-union && go run ./cmd/federated-union
# https://console.localhost:8443/

Everything runs in one process: 15 entities, each at its own *.localhost host, on one TLS listener. Browsers resolve *.localhost to loopback natively, so there's no hosts-file setup.

What it shows

1. Cross-border sign-in with no onboarding: the bank resolves EastID's Trust Chain (EastID → Eastmark authority → Union); EastID registers the bank automatically (§12.1).

2. Layered policy: the Union's metadata policy narrows each service's grant types, and Southport adds its own requirement. The console compares declared and resolved metadata.

3. Recognized assurance: identity providers carry level-of-assurance Trust Marks from accreditation offices listed in the Union's trust_mark_issuers. Services verify them with RequireFederationAccreditation.

4. Data minimization: the bank requests claims (BeginAuthorizationRequest.Claims), and the citizen unticks what they won't share (ApprovedIdentityClaims).

5. Console scenes:

   • forged mark: refused, because the issuer isn't accredited;
   • suspended country: cross-border sign-ins fail while domestic ones keep working;
   • compromised authority: the impostor is contained by the Union's naming constraints.

   A live log of federation traffic sits alongside.

How

• Public API only. The three library gaps it exposed were fixed first: feat(federation): name the federation types in the public API #414 (public federation types), feat(federation): publish Trust Marks in an Entity Configuration #415 (Trust Marks in Entity Configurations) and feat(client): request identity claims with the OIDC claims parameter #417 (the client claims parameter).
• Its own Go module, built against this checkout via replace, like passport-vdc.
• Consent CSRF guidance followed: the identity providers keep the interaction handle in an HttpOnly, SameSite cookie (docs: require binding the interaction handle to the browser; fix refresh-token binding claim #409). The services bind callbacks with ParseSessionHandle (fix(client)!: bind authorization callbacks to the user agent that began the flow #397).

Repo wiring

• A new CI job, examples: vet, go test -race, and golangci-lint on the demo module.
• release-please-config.json: exclude-paths: ["examples"].
• sonar-project.properties: examples/** excluded from the coverage metric only; all other rules still apply.
• The README links to the demo.

Testing

• union/e2e_test.go boots the whole federation on a free port and drives each scenario through the actual pages, with a cookie-jar browser client:
  • a cross-border sign-in where the unshared address never reaches the bank;
  • a domestic sign-in;
  • a forged mark refused with 403;
  • suspension cutting off cross-border sign-ins only;
  • the impostor rejected through the Union but resolvable through Eastmark alone;
  • console pages rendering the policy narrowing.
• go test -race and golangci-lint are clean on the demo module.
• The binary was run live and its console and service pages were checked.

Developer-experience notes found while building it (follow-ups, not in this PR)

• When automatic registration fails, the identity provider can only answer invalid_client: unknown client, and the embedder gets no reason either. The cause here, a missing token_endpoint_auth_signing_alg, took reading the source to find. A registration-failure hook would help.
• federation.OpenIDRelyingPartyMetadata doesn't mention that private_key_jwt needs TokenEndpointAuthSigningAlg for a FAPIgo identity provider.

🤖 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
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud