PR B: Document and tighten the exception system; narrow JSON payload accesses

[turegjorup]

Summary

Second of three follow-ups (A → B → C) on the path to level: max PHPStan. Combines three closely-related concerns into one PR after review feedback on PR #42 surfaced naming + documentation gaps:

1. JSON-payload narrowing in getJwtVerificationKeys and getIdToken — replaces dynamic $jwks['keys'][n]['kid'] / $payload['id_token'] reads with explicit is_array / is_string guards that throw a typed exception at the actual error boundary.
2. Documentation on every concrete exception class. Audit confirms each of the 15 concretes covers a distinct failure category.
3. Rename KeyException → JwksException for symmetry with MetadataException.

Stacked on PR #42 — based on fix/replace-string-casts-with-guards. When #42 merges, this PR rebases onto develop cleanly. The MetadataException introduced by #42 is referenced from this PR's cross-type docblocks.

1. JSON-payload narrowing

Site	New throw
$jwks['keys'] not an array	JwksException('JWKS payload missing array "keys" property (RFC 7517 §5)')
$key not an object	JwksException('JWK entry is not a JSON object')
$key['kty'] not a string	JwksException('JWK entry missing string "kty" for key id: $kid')
RSA $key['e'] / $key['n'] not strings	JwksException('JWK RSA entry missing string "e"/"n" for key id: $kid')
Token endpoint response missing string id_token	CodeException('Token endpoint response missing string "id_token"')

All new throws are existing types implementing OpenIdConnectExceptionInterface — consumers catching the marker are unaffected.

Adds a createProviderWithCustomJwks(string) test helper used by four new JWKS validation tests plus one inline getIdToken test. 100% coverage maintained (161/161 lines, up from 151).

2. Documentation

Every concrete in src/Exception/ now carries a class-level PHPDoc describing:

• What failure category it represents.
• When the library throws it (specific trigger sites).
• The rationale for its SPL parent type.
• The boundary against related concrete types where confusion is plausible.

The audit shows each of the 15 concretes covers a distinct failure category — no two would be handled identically by a reasonable consumer (per ADR 001's granularity rule).

The overall count (15) is higher than ADR 001's "three to five per package" target. Consolidation candidates are flagged via the cross-references but not collapsed in this PR (any rename or removal is a deferred MAJOR break).

3. Rename KeyException → JwksException

The type fires for both document-level errors (keys array missing in the JWKS top level) and entry-level errors (missing kid / kty / e / n on a JWK inside). Naming it after the JWKS document type rather than the individual key is more accurate, and mirrors MetadataException (named after the OIDC discovery document).

Casing: JwksException (PSR-1/12 PascalCase) — matches Symfony's JwkSet convention. Avoids the eye-poke of all-caps acronyms in catch blocks.

Consumers catching OpenIdConnectExceptionInterface are unaffected. Consumers catching the concrete need to swap the class name.

Test plan

• task test:coverage — 100% on OpenIdConfigurationProvider (24/24 methods, 161/161 lines).
• task analyze:php at level: 8 — no errors.
• task analyze:php at level: max — 7 errors removed (26 → 19). Remaining 19 covered by PR C.
• task lint:php — clean.
• task lint:markdown — clean.
• CI matrix on PR.

Follow-up: PR C

Will narrow validateIdToken's claim accesses and the test-side Mockery / fixture-helper return types. After PR C, level: max is achievable in a single-line config bump.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (39ac2f8) to head (6dae797).

Additional details and impacted files

@@                           Coverage Diff                            @@
##             fix/replace-string-casts-with-guards       #44   +/-   ##
========================================================================
  Coverage                                  100.00%   100.00%           
- Complexity                                     64        72    +8     
========================================================================
  Files                                           1         1           
  Lines                                         175       185   +10     
========================================================================
+ Hits                                          175       185   +10     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.