Add replay protection to private_key_jwt client assertions

[thiva-k]

Purpose

private_key_jwt client assertions had no replay protection: jti was never tracked,
unlike DPoP proofs and ID-JAG assertions which both use the shared oauth2/jti deny-list.
A captured, still-valid client_assertion could be replayed to mint tokens as that client
without its private key. Affects all endpoints behind ClientAuthMiddleware. (CWE-294.)

Approach

Wire the existing jti deny-list into the private_key_jwt path, mirroring DPoP/ID-JAG:
after verification, record the assertion's jti (now required) and reject replays. The
entry is bounded by the assertion's exp plus clock-skew leeway. Threaded the shared
jtiStore and leeway through ClientAuthMiddleware into all five consuming endpoints.

Summary by CodeRabbit

• Security Enhancements
  • Added replay protection for OAuth client assertions.
  • Assertions now require valid, one-time-use identifiers and expiration claims.
  • Reused, incomplete, or invalid assertions are rejected.
  • Consistent replay protection and configurable JWT clock tolerance are applied across OAuth authentication flows.

[coderabbitai]

📝 Walkthrough

Walkthrough

OAuth client assertion validation now uses shared JTI storage and JWT leeway. OAuth initialization passes these values through PAR, CIBA, token, introspection, and revocation route setup.

Changes

OAuth JTI replay protection

Layer / File(s)	Summary
Client assertion replay validation backend/internal/oauth/oauth2/clientauth/clientauth.go, backend/internal/oauth/oauth2/clientauth/clientauth_test.go	Assertions require jti and exp claims. The validation records each JTI until expiration plus leeway and rejects replayed assertions.
Client authentication middleware wiring backend/internal/oauth/oauth2/clientauth/middleware.go, backend/internal/oauth/oauth2/clientauth/middleware_test.go	The middleware accepts and forwards the JTI store and leeway. Existing middleware tests use the expanded signature.
OAuth route initialization backend/internal/oauth/init.go, backend/internal/oauth/oauth2/{ciba,introspect,par,revocation,token}/init*.go	OAuth initialization creates a shared JTI store and passes it with configured JWT leeway to route registration and client authentication middleware.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• thunder-id/thunderid#4172: Introduces the runtime-backed JTI store wired by this change.
• thunder-id/thunderid#3803: Wires JTI replay enforcement through OAuth client authentication and token validation.
• thunder-id/thunderid#4220: Modifies the OAuth client-authentication flow used by this change.

Suggested reviewers: thamindudilshan, senthalan, anushasunkada

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: replay protection for private_key_jwt client assertions.
Description check	✅ Passed	The description clearly covers the purpose and approach, but it omits the template’s related items, checklist, and security checks.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

backend/internal/oauth/oauth2/clientauth/clientauth_test.go (1)

1516-1521: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert the JTI retention deadline.

These expectations accept any expiry value. Assert time.Unix(9999999999+testLeeway, 0) in one RecordJTI expectation. Otherwise, removing leeway from recordAssertionJTI keeps the replay tests passing.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@backend/internal/oauth/oauth2/clientauth/clientauth_test.go` around lines
1516 - 1521, Update the two RecordJTI expectations in the replay test to assert
the retention deadline explicitly: use time.Unix(9999999999+testLeeway, 0) for
the expiry argument in one expectation instead of mock.Anything, while
preserving the existing return values and call ordering.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/internal/oauth/oauth2/clientauth/clientauth.go`:
- Around line 312-335: Update the relevant OAuth client-authentication guide
under docs/content/guides/ and the request semantics in docs/content/apis.mdx to
document private_key_jwt requirements: jti is mandatory, each assertion is
single-use across client-authenticated OAuth endpoints, replay attempts fail,
and replay retention lasts until exp plus the configured JWT leeway. Ensure the
documentation matches recordAssertionJTI behavior.

---

Nitpick comments:
In `@backend/internal/oauth/oauth2/clientauth/clientauth_test.go`:
- Around line 1516-1521: Update the two RecordJTI expectations in the replay
test to assert the retention deadline explicitly: use
time.Unix(9999999999+testLeeway, 0) for the expiry argument in one expectation
instead of mock.Anything, while preserving the existing return values and call
ordering.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 64180c34-8fa4-4c98-850e-88d468d7508e

📥 Commits

Reviewing files that changed from the base of the PR and between 98caa2d and d242ac3.

📒 Files selected for processing (12)

• backend/internal/oauth/init.go
• backend/internal/oauth/oauth2/ciba/init.go
• backend/internal/oauth/oauth2/clientauth/clientauth.go
• backend/internal/oauth/oauth2/clientauth/clientauth_test.go
• backend/internal/oauth/oauth2/clientauth/middleware.go
• backend/internal/oauth/oauth2/clientauth/middleware_test.go
• backend/internal/oauth/oauth2/introspect/init.go
• backend/internal/oauth/oauth2/introspect/init_test.go
• backend/internal/oauth/oauth2/par/init.go
• backend/internal/oauth/oauth2/revocation/init.go
• backend/internal/oauth/oauth2/revocation/init_test.go
• backend/internal/oauth/oauth2/token/init.go

[codecov]

Codecov Report

❌ Patch coverage is 92.30769% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...end/internal/oauth/oauth2/clientauth/clientauth.go	80.95%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[ThaminduDilshan]

LGTM