docs: correct stale and inaccurate documentation across the repo

[osanderson]

Summary

A full review of every Markdown doc and the package doc comments against current main. Each claim was checked against the code:

• an identifier scan over all .md files and Go comments;
• GETTING_STARTED's snippets compiled and run as a real program;
• behavioral claims read against the implementation.

Behavioral errors (most important)

• server/doc.go: said every access token is DPoP-only and "mTLS binding [is] not supported". mTLS sender-constraining (RFC 8705 §3) is supported and certified.
• server/doc.go: said refresh tokens rotate on every use. They deliberately don't (FAPI 2.0 SP §5.3.2.1 forbids rotation except in extraordinary circumstances).
• server/doc.go: said production checks for store and key capabilities "will be added". They exist; the text now lists them.
• GETTING_STARTED.md: the server.New example failed as written ("client certificate trust is required"). It now includes ClientCertificateTrust and is gofmt'd.
• GETTING_STARTED.md: pointed at the removed selfIssuerKeySource instead of keys.NewLocalIssuerKeys.

ARCHITECTURE.md

• Named things that don't exist or were never built as described:

  • root Scope/Issuer/SenderConstraint types;
  • client.AuthorizationRequest / server.ValidatedAuthorizationRequest;
  • DPoPKeyHandle and a DPoP key reference in the session store;
  • server.SelectSigningKey;
  • SubjectProvider;
  • AuthorizationPolicy.Evaluate;
  • an Exposure tag on errors;
  • configurable fail-closed or outbox audit;
  • replay.Store and a client:jarm namespace;
  • stores living in client/server;
  • a contract suite covering rollback and cross-connection consistency.

  Each passage now describes the real API.

• Linked a nonexistent "Hardening rules for every role's public API" section, as did client/doc.go and resource/doc.go. These now point to "Design rules".

• The conformance history opened by saying CIBA is "deliberately not part of this automated certification loop". It now opens with current results (2026-09-27 run) and notes that the per-profile counts below are first-run figures.

Other docs

• README: adds attestation-based client authentication (in the ClientAuthMethod enum and the feature list) and the client-side OAuthOnly option.
• SECURITY: said there are no tagged releases; it now describes the supported versions.
• conformance/README:
  • CIBA section framed as unit-test-only; now describes the four AS legs plus the RP leg;
  • ciba-mtls is now 35 modules;
  • client-credentials counts were stale (now 16/12/10/6, mapped per leg);
  • dropped a parenthetical pointing at ARCHITECTURE detail that doesn't exist.
• Leg count: "twenty-one" appeared in conformance.yml (comments and step name) and server/scripts/README.md; run-all.sh runs 22.
• UPGRADING v0.38.0: adds invalid_scope at PAR/CIBA (fix(server): return invalid_scope for a scope the client isn't allowed #403), and the character-checked server error text plus malformed-callback-code rejection (feat(client): expose the server's OAuth error response on client.Error #402).
• CONTRIBUTING / AGENTS: a breaking PR adds its UPGRADING.md section. AGENTS no longer says "this session settled on".
• Package docs:
  • client/doc.go: CIBA methods, ParseSessionHandle binding, ServerResponse;
  • resource/doc.go: mTLS x5t#S256 binding;
  • keys/doc.go: custody declaration, JWKS/local issuer key sources, KeySourceAssurance;
  • storage/doc.go: Session/Nonce/Backchannel stores exist, real namespaces;
  • server/assurance.go: dropped a "HSM-backed keys will be added" note that contradicts the custody design.

Deliberately left alone

The long per-profile conformance READMEs keep their dated "result of a live run" counts as history. Their aud, federation and expected-failure content was checked and is current.

Testing

• go build ./... and go vet pass.
• Tests pass for server, client, resource, keys and storage.
• The re-run identifier scan leaves only two intentional references: the fapi.New counterexample and a suite Java class name.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GMAyPYDPGpfnwow3JLeooZ

[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