feat: Add client secret expiry tracking and automatic renew for DCR

[Sanskarzz]

Summary

Implements client secret expiry tracking and automatic renewal for Dynamic Client Registration (DCR)

Fixes: #3631

ToolHive already stored the client_id and client_secret from DCR responses, but discarded the registration_access_token, registration_client_uri, and client_secret_expires_at fields. Without these, there was no way to detect or renew an expired client secret, causing silent authentication failures for long-running workloads on providers like Keycloak that issue expiring secrets.

This PR implements the full RFC 7591 / RFC 7592 secret lifecycle in three phases:

1. Store all DCR response metadata through the persistence pipeline
2. Detect expiry proactively (24 h buffer) and on session restore
3. Renew the secret via RFC 7592 §2.2 before it becomes a problem

Note
All the phases are added in the same PR.

---

Changes

pkg/auth/remote/persisting_token_source.go

Extended ClientCredentialsPersister function type signature:

// Before
type ClientCredentialsPersister func(clientID, clientSecret string) error

// After
type ClientCredentialsPersister func(
    clientID string,
    clientSecret string,
    secretExpiry time.Time,           // zero = never expires (RFC 7591 §3.2.1)
    registrationAccessToken string,   // for RFC 7592 management operations
    registrationClientURI string,     // endpoint for RFC 7592 updates
    tokenEndpointAuthMethod string,   // "client_secret_post" or "client_secret_basic" (RFC 7591 §2)
) error

pkg/auth/remote/config.go

• Added CachedRegClientURI field to store registration_client_uri as plain text
• Added CachedTokenEndpointAuthMethod field to store the authentication method used during DCR
• Updated ClearCachedClientCredentials() to also clear the new fields

pkg/auth/discovery/discovery.go

• Added DCR renewal metadata fields to OAuthFlowConfig (used as the threading vehicle from handleDynamicRegistration through to the result)
• Extended OAuthFlowResult with SecretExpiry, RegistrationAccessToken, RegistrationClientURI, and TokenEndpointAuthMethod
• Updated handleDynamicRegistration() to capture all four from DynamicClientRegistrationResponse:
  • ClientSecretExpiresAt > 0 → time.Unix(...) (zero if the field is 0, meaning never expires)
  • RegistrationAccessToken and RegistrationClientURI copied as-is
  • TokenEndpointAuthMethod captured from response (defaults to client_secret_post in request)
• Updated newOAuthFlow() to populate the new fields in OAuthFlowResult

pkg/auth/remote/handler.go

• Updated wrapWithPersistence() to pass all 6 arguments to clientCredentialsPersister
• Added "time" import
• resolveClientCredentials() now proactively calls renewClientSecret() when the secret is expiring within 24 h; renewal failures are soft-logged and execution continues
• tryRestoreFromCachedTokens() now checks expiry before attempting token refresh:
  • Within 24 h buffer + renewal fails → warning, continue with existing secret
  • Past expiry + renewal fails → hard error, forces a fresh OAuth flow

pkg/runner/runner.go

Updated SetClientCredentialsPersister callback to match the new 6-argument signature and persist:

• CachedSecretExpiry — stored directly in config
• registrationAccessToken — stored securely in the secret manager, reference saved to CachedRegTokenRef
• registrationClientURI — stored as plain text in CachedRegClientURI
• tokenEndpointAuthMethod — stored directly in config as CachedTokenEndpointAuthMethod

pkg/auth/remote/secret_renewal.go (new file)

Implements RFC 7592 §2.2 client secret renewal:

• isSecretExpiredOrExpiringSoon() — returns true when the secret is within secretExpiryBuffer (24 h) of expiry or already past it; false for zero expiry (never expires)
• renewClientSecret(ctx) — sends an authenticated HTTP PUT to registration_client_uri per RFC 7592 §2.2:
  • Retrieves registrationAccessToken from the secret manager
  • Validates registration_client_uri (must be HTTPS or localhost)
  • Sends current client metadata as the request body (required by RFC 7592)
  • Parses the response (RFC 7592 §2.1), extracts new client_secret, client_secret_expires_at, and optionally a rotated registration_access_token
  • Persists everything via clientCredentialsPersister
• validateRegistrationClientURI(uri) — validates the URI is HTTPS (or localhost for development)

pkg/auth/remote/secret_renewal_test.go (new file)

16 new tests covering:

Test	Coverage
TestIsSecretExpiredOrExpiringSoon (5 cases)	Zero, far-future, within-buffer, past-expiry, at-boundary
TestValidateRegistrationClientURI (6 cases)	Empty, HTTPS, HTTP non-localhost rejected, localhost/127.0.0.1 allowed, invalid URL
TestRenewClientSecret_MissingConfig (3 cases)	No URI, no token ref, no secret provider
TestRenewClientSecret_Success	Happy path with mock RFC 7592 server; token rotation
TestRenewClientSecret_ServerError	HTTP 401 from server
TestRenewClientSecret_NoPersister	Server OK but no persister configured
TestRenewClientSecret_ZeroExpiryInResponse	client_secret_expires_at: 0 → time.Time{} (never expires)

---

Breaking Changes

Warning

ClientCredentialsPersister function type signature changed.

Any code outside this repository that implements or calls ClientCredentialsPersister must be updated to use the new 6-parameter signature. Within this repository, the only call site is pkg/runner/runner.go, which is updated in this PR.

---

Backward Compatibility

Scenario	Behaviour
Provider does not issue expiring secrets (client_secret_expires_at = 0)	CachedSecretExpiry is time.Time{}. isSecretExpiredOrExpiringSoon() returns false. No renewal is attempted.
Provider does not support RFC 7592 (no registration_access_token / URI)	renewClientSecret() returns an immediate error. Caller logs a warning and continues with the existing secret.
Provider does issue expiring secrets and supports RFC 7592	Secret renewed automatically within 24 h of expiry.
Renewal fails but secret is still within its validity window	Soft warning logged, existing secret used.
Renewal fails and secret is past its expiry	Hard error returned; caller performs a fresh OAuth flow.

---

RFC References

• RFC 7591 3.2.1 — client_secret_expires_at, registration_access_token, registration_client_uri in registration response
• RFC 7592 2.2 — Client Update Request (PUT with Bearer token)
• RFC 7592 2.1 — Client Information Response (response format for read/update)

---

Test Results

ok  github.com/stacklok/toolhive/pkg/auth               PASS
ok  github.com/stacklok/toolhive/pkg/auth/awssts        PASS
ok  github.com/stacklok/toolhive/pkg/auth/discovery     PASS
ok  github.com/stacklok/toolhive/pkg/auth/oauth         PASS
ok  github.com/stacklok/toolhive/pkg/auth/remote        PASS  (16 new tests)
ok  github.com/stacklok/toolhive/pkg/auth/secrets       PASS
ok  github.com/stacklok/toolhive/pkg/auth/tokenexchange PASS
ok  github.com/stacklok/toolhive/pkg/auth/upstreamswap  PASS
ok  github.com/stacklok/toolhive/pkg/auth/upstreamtoken PASS

Type of change

• Bug fix
• [*] New feature
• Refactoring (no behavior change)
• Dependency update
• Documentation
• Other (describe):

Test plan

I have done E2E testing with Keycloak.

sanskar@sanskar-HP-Laptop-15s-du1xxx:~/opensource/stacklok/toolhive$ ./bin/thv logs keycloak-e2e-detached --proxy | grep -E "renew|RFC 7592|expired"
{"time":"2026-03-22T03:19:13+05:30","level":"DEBUG","msg":"DCR response includes registration access token for RFC 7592 operations"}
{"time":"2026-03-22T03:20:32+05:30","level":"DEBUG","msg":"Stored DCR registration access token for RFC 7592 operations"}
{"time":"2026-03-22T03:24:40+05:30","level":"DEBUG","msg":"DCR response includes registration access token for RFC 7592 operations"}
sanskar@sanskar-HP-Laptop-15s-du1xxx:~/opensource/stacklok/toolhive$ 

{"time":"2026-03-22T03:46:24+05:30","level":"INFO","msg":"Cached client secret is expiring or expired; attempting renewal before token restore","expiry":"2024-01-01T00:00:00Z"}
{"time":"2026-03-22T03:46:24+05:30","level":"DEBUG","msg":"Attempting RFC 7592 client secret renewal","registration_client_uri":"http://localhost:8080/realms/mcp-test/clients-registrations/openid-connect/8327e637-eef9-4f2e-93fb-768e5ed6b4a1"}
{"time":"2026-03-22T03:46:24+05:30","level":"INFO","msg":"Successfully renewed client secret via RFC 7592","client_id":"8327e637-eef9-4f2e-93fb-768e5ed6b4a1","new_expiry_zero":true,"reg_token_rotated":true}

- [*] Unit tests (`task test`)
- [*] E2E tests (`task test-e2e`)
- [*] Linting (`task lint-fix`)
- [*] Manual testing (describe below) Pending

[codecov]

Codecov Report

❌ Patch coverage is 51.16279% with 105 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.66%. Comparing base (0108b11) to head (0e0a520).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/runner/runner.go	0.00%	62 Missing ⚠️
pkg/auth/remote/secret_renewal.go	86.13%	7 Missing and 7 partials ⚠️
pkg/auth/discovery/discovery.go	0.00%	12 Missing ⚠️
pkg/auth/remote/handler.go	64.28%	8 Missing and 2 partials ⚠️
pkg/auth/remote/persisting_token_source.go	0.00%	3 Missing ⚠️
pkg/state/runconfig.go	33.33%	2 Missing ⚠️
pkg/workloads/types/types.go	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4194      +/-   ##
==========================================
- Coverage   68.77%   68.66%   -0.11%     
==========================================
  Files         473      474       +1     
  Lines       47919    48115     +196     
==========================================
+ Hits        32955    33040      +85     
- Misses      12299    12342      +43     
- Partials     2665     2733      +68     

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

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.

PR size has been reduced below the XL threshold. Thank you for splitting this up!

[github-actions]

✅ PR size has been reduced below the XL threshold. The size review has been dismissed and this PR can now proceed with normal review. Thank you for splitting this up!

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.