feat(auth): define generation-fenced identity key snapshot

[seonghobae]

Objective

Advance issue #314 with a path-disjoint identity-key snapshot primitive for provider-neutral OIDC/JWT adapters. A verifier can now bind a server-owned verifier profile to one immutable key-set generation and bounded cache lifetime so an unknown key, stale generation, pre-fetch use, or expired snapshot fails closed before any future adapter treats key material as current authority.

Exact test-first evidence

Protected main is exact 55d7ae8647208e301f282350f076eeddaba61d11 at the latest direct refetch.

• RED test-only head 5f7099cad795a74e102dcb9366b5968b875a84bd: CI run 31457845369, Maven test job 93675234940, checked out that exact SHA and failed in testCompile because IdentityKeySnapshot did not exist. Security Scan and SAST succeeded; the Maven and fuzz failures are the intended RED boundary.
• GREEN head 959de4116c8d0587c038d6b1c8363c55dc4b6d0c: exact-head CI 31457958493, Security Scan 31457958510, SAST Semgrep 31457958534, and fuzz 31457958535 all completed successfully. No formal reviews or unresolved inline review threads exist at the latest direct refetch.

Implemented invariant

IdentityKeySnapshot is an immutable provider-neutral authority value. It defensively copies exact trusted key identifiers, requires a positive generation fence, models fetchedAt as inclusive and expiresAt as exclusive, rejects malformed authority inputs, and authorizes a key only when the caller's expected generation matches and the snapshot is current. It deliberately does not parse JWTs, choose algorithms, fetch discovery/JWK material, or carry JWK bodies; cryptographic verification remains a separate adapter responsibility.

Scope

New provider-neutral key-snapshot domain primitive plus focused tests only. This does not parse JWTs, verify signatures, fetch discovery/JWK documents, store JWK bodies, choose algorithms, map issuer/audience/roles, modify controllers, or replace the current signed-HMAC adapter. It is path-disjoint from #343's verifier port, #364's issuer trust policy, #365's role mapping, #374's token time window, and credential/HMAC work. Issue #314 remains open for signed-token verification, bounded discovery/JWK transport and refresh concurrency, algorithm/audience enforcement, rotation/recovery, migration, and integrated production acceptance.

Merge gate

Ready for ordinary independent review. Merge only if this unchanged exact head continues to satisfy all live required checks, zero valid unresolved findings, current protected-base expectations, and the qualifying independent non-author formal approval required by repository policy. Automated checks/comments/model output are evidence, not approval.

[coderabbitai]

Warning

Review limit reached

@seonghobae, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 49 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 606672fd-a130-4e3a-bf06-ed1b0f1706a3

📥 Commits

Reviewing files that changed from the base of the PR and between 55d7ae8 and 959de41.

📒 Files selected for processing (2)

• src/main/java/com/clearfolio/viewer/auth/IdentityKeySnapshot.java
• src/test/java/com/clearfolio/viewer/auth/IdentityKeySnapshotTest.java

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}