docs: cover v0.42.0's features and add an examples overview

[osanderson]

Summary

These fixes come from a docs review of main (a941962) against the last docs sweep (#468). The mechanical checks were already clean:

• Every library identifier referenced in docs and comments exists. The scanner is rewritten to read the Go AST, so it now also covers members of var (...) blocks.
• All 11 GETTING_STARTED Go blocks compile and vet (re-checked after these edits).
• Every relative link and anchor resolves.
• UPGRADING.md covers all three v0.42.0 breaking changes, accurately.

The problems were in content.

Integrators copying these examples would get them wrong:

• GETTING_STARTED login step:
  • Problem: it passed time.Now() to NewAuthenticationContext, and never mentioned Interaction.ACRValues/MaxAge. An app that reuses an SSO session and copies this silently defeats v0.42.0's max_age check.
  • Fix: it now passes the time the user actually authenticated, says when to re-authenticate, and shows GrantedAuthorization.GrantID.
• GETTING_STARTED resource-server step:
  • Problem: it built VerifyRequest without PeerCertificate, so every mTLS-bound access token would be refused.
  • Fix: it now passes resource.PeerCertificateFromHTTP(r), with a paragraph on TLS-terminating proxies.

Completeness:

• GETTING_STARTED:
  • RevokeGrant in the revocation guidance, on both the AS and the RS side;
  • a "serving a grant this package doesn't" paragraph: TokenEndpointRequest.Parameters, AuthenticateAttestedClient, VerifyTokenRequestBinding and Config.AdditionalGrantTypes;
  • the CIBA and client credentials methods in the HTTP-surface list.
• README feature list: refresh tokens and whole-grant revocation; OIDC claims with per-claim consent, acr_values and enforced max_age; embedder-served grants.
• server/doc.go: the method list gains RevokeGrant and BuildAuthorizationErrorRedirect, plus the embedder-grant pair and why it fits the "no generic primitives" rule. There are new bullets for max_age, and for CIBA in RevokeGrant.
• client/doc.go: a garbled sentence is fixed; RefreshTokens is noted as populating, and keeping, the ID token; ClientAttestationHeaders is added to the list of deliberate exceptions.
• ARCHITECTURE: the layout gains serverresource/, internal/grantrevocation/, cmd/ and examples/, and rules 3 and 7 gain the new flows.
• UPGRADING max_age section: the clock-skew leeway, the 100-year cap, and "pass the real authentication time".
• keys/keys/ephemeral package docs: corrected.

Examples overview (new examples/README.md):

• a table of the six demos: the story and the port;
• a capability matrix of 16 rows, mapping each feature to its spec and the demos that show it. I checked every cell against the demo's code.
• what every demo shares: the console tour, the attack lab, protocol traces, public API only (CI-enforced), and end-to-end tests;
• how to run one, and one port table.

The root README links to it. Each demo README's partial "runs alongside the other demos" port list now points at that table.

No code changes beyond doc comments.

🤖 Generated with Claude Code

[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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!