Security & correctness hardening: auth flow, cache, recovery, DCR, docs (#155)

* Audit review (rounds 1-31): fix confirmed issues, remove dead code, harden tests

Security/correctness fixes:
- fail-open token validation preserved with lenient-audience; access token that
  fails verification and has no ID token to corroborate now fails closed
- token_manager blacklist-expiry: fix impossible tautology (x>24h && x<24h)
- constant-time OAuth state compare; clear state/nonce/code_verifier on
  callback token-exchange failure to prevent replay of half-failed flows
- StopAllTasks gated on last-instance close
- background-task panic recovery; remove task-registry counter leak
- circuit breaker half-open: release probe slot; CB + per-session outcome
  recorded once per refresh operation, not once per waiter
- Redis connection pool: handle nil receive when pool closed concurrently
- FileStore: atomic temp-write + rename
- errors_recovery health-check data race -> atomic

Test-isolation / hardening:
- reset helpers for Once-pinned global cache manager and transport pool
- coverage: utils 70->93% (redirect URL security contract); fuzz targets for
  bearer parsers; concurrent ServeHTTP race tests for the shared request path

Dead-code removal (verified orphaned, build+suite green): internal/providers
(30 files, 0 importers), internal/compat, internal/features, input_validation.

Verified: govulncheck, go mod tidy, yaegi-validate, cross-compile (darwin+
linux), golangci-lint (new-from-rev clean), 3x full race+shuffle green.

* Lint: fix real int-truncation bug; document intentional gosec findings

- TransportPool configKey: write conn-count ints verbatim (strconv) instead of
  byte() truncation — a config value >=256 previously truncated and made two
  distinct configs collide on one key, silently sharing a transport with the
  wrong settings (real fix, gosec G115).
- Document design-intentional gosec findings with //nolint:gosec + rationale:
  G117 (clients_secret intentionally marshaled into stored creds JSON),
  G704 (tokenURL is the trusted discovery endpoint), G124 (delete/test cookie,
  Secure set conditionally), G118 (long-lived background refresh) and pool
  utils short-ID rune, testutil mock server redirects.

Result: full-tree golangci-lint now reports 0 issues (was ~12). Build, vet,
and the full test suite remain green.

* Fix singleton ResourceManager data race (unlocked read vs test reset)

GetResourceManager returned the process-global via an unprotected read
(singleton_resources.go:50), while resetResourceManagerForTesting and
ResetResourceManager write it under resourceManagerMutex. A live background
task (graceful-degradation health check started by one test) reading the
singleton while a shuffled test resets it was a data race (found via
-race -shuffle: Write at singleton_resources_test.go:941/942 vs Read at
autocleanup.go:554 / error_recovery.go:910).

Fix: hold resourceManagerMutex around the read, matching the sibling
GetGlobalTaskRegistry (autocleanup.go:414). Added a deterministic
concurrent regression test (GetResourceManager vs reset under -race).

Verified: 4x full -race -count=1 -shuffle=on ./... all exit 0, 0 races,
0 fails; source-order suite green; lint clean.

* Fix 6 issues surfaced by adversarial agent team (round 35)

Concurrency/lifecycle (P1, highest-value):
- singleton_resources.go: RegisterBackgroundTask now REPLACES a stopped
  task instead of reusing it. BackgroundTask.Start is sync.Once-guarded,
  so a task stopped on instance close and re-registered (Traefik
  close+recreate for the same provider) was permanently dead: IsTaskRunning
  returned false (started && !stopped) so callers retried a start that
  was a no-op. Metadata refresh, token cleanup, and health checks now
  resume across a recreate cycle.
- error_recovery.go: the shared graceful-degradation health task was
  bound to the FIRST instance's performHealthChecks (later instances'
  checks never ran) and any instance's Close stopped it for all. Added a
  global live-instance registry; the shared task runs every instance's
  checks and is stopped only when the last instance closes (mirrors the
  singleton-token-cleanup gate).

Storage/cache:
- hybrid.go recordL2Error: Store(now) then immediately compared
  time.Since(t)<1s against its own write => ALWAYS fired, so a single
  transient L2 error flipped the whole cache into fallback (full L2
  bypass -> upstream stampede). Now enters fallback only on a PRIOR
  error within the window (true "multiple errors"). Updated two tests
  that had encoded the old single-error-fallback bug.
- redis_pool.go: ConnectionPool.Put checked closed but sent on
  p.connections without holding p.mu; Close closed it under p.mu.
  Window => 'send on closed channel' panic at shutdown. Put now holds
  p.mu (the lock only Close used).

HTTP/transport:
- jwk.go fetchJWKS: added an explicit >1 MiB guard (was silent partial
  read, could yield a truncated keyset and spurious missing-kid).
- http_client_pool.go configKey: now includes every transport-behavior
  field it actually consumes (compression, HTTP2, keep-alives, timeouts,
  buffer sizes, dial) so behaviorally different configs no longer share
  one transport built with the first config's settings.

Each fix has a regression test. Verified: full source-order suite green,
golangci-lint 0 issues, 3x full -race -count=1 -shuffle=on ./... all exit 0.

* Fix round-36 issues: DCR validation, auth-method default, shared metadata task, replay false-positive

Four verified fixes from the round-36 agent team (each confirmed against source
before acting):

- settings.go: Config.Validate now skips the client-credential block when
  Dynamic Client Registration is enabled and no clientID is pre-provisioned
  (RFC 7591 provides credentials at registration). Previously the
  unconditional 'clientID is required' made DCR unreachable via New.
- dynamic_client_registration.go: default registered token_endpoint_auth_method
  to client_secret_post to match the plugin's runtime default; an enforcing
  IdP would otherwise reject the plugin's token exchange.
- utilities.go: gate the shared per-provider singleton-metadata-refresh task
  stop on lastInstance (matching singleton-token-cleanup) so one instance's
  tear down no longer kills 2h metadata refresh for a surviving sibling.
- token_manager.go: stop self-recording the JTI into the per-instance
  tokenBlacklist on every verify. On the cookie path the same valid token is
  re-presented per request; an LRU eviction of the raw-token cache (MaxSize
  1000 / 5 MiB) then turned a legitimate cache miss into a false 'token
  replay detected'. Replay tracking stays in the shared shardedReplayCache.

Regression tests: new review_r36_regression_test.go (4 tests); updated
dynamic_client_registration_test.go and security_edge_cases_test.go which had
encoded the old defaults.

Verified: full source-order suite, full -race -count=1 -shuffle=on ./...
(all packages), and golangci-lint run ./... (0 issues).

* Fix dead CircuitBreaker.ResetTimeout config (round 39)

error_recovery.go: ResetTimeout was copied into the CircuitBreaker but never
consulted by the state machine (used only for a metric), so the documented
"how long to wait before fully closing the circuit" (reset_timeout, default
30s) had no effect: Open->HalfOpen used Timeout (60s), and a single
half-open success closed the circuit immediately, losing the intended
open -> half-open -> (reset cooldown) -> closed hysteresis and letting a
stray success immediately reopen (bounce).

Now the circuit remains half-open after entering it until resetTimeout has
elapsed; only then can a successful request fully close it. Half-open
requests are still allowed as probes. Default behavior is more
conservative (up to Timeout+ResetTimeout before full close).

Tests: updated TestCircuitBreakerHalfOpenTransition to the corrected
semantics; added TestCircuitBreakerResetTimeoutEnforced (fails on the old
dead-field code, where resetTimeout was ignored).

Verified: full source-order suite, full -race -count=1 -shuffle=on ./...
(all packages), golangci-lint run ./... (0 issues).

* Apply configured conn limits in pooled transport (round 41)

http_client_pool.go SharedTransportPool.GetOrCreateTransport built the shared
http.Transport with hardcoded MaxConnsPerHost=5, MaxIdleConnsPerHost=2,
MaxIdleConns=10, IdleConnTimeout=30s while HTTPClientConfig's versions of
those fields drove configKey (cache identity) and were validated and tuned
per preset (Default: 20/10/50/30s; OIDCProvider: 50/25/100/90s). The
config was thus valid, keyed, and validated but silently ignored in the
transport used by main.go (CreatePooledHTTPClient) - dead config that left
OIDC-provider connection tuning without effect. The sibling factory path
(http_client_factory.go) already applied these values.

Now the pooled transport derives MaxConnsPerHost, MaxIdleConnsPerHost,
MaxIdleConns, and IdleConnTimeout from the config, consistent with the
factory path and with configKey.

Test: added TestSharedTransportPoolAppliesConfigLimits, which fails on the
old hardcoded code (fixed values) and passes now.

Verified: full source-order suite, full -race -count=1 -shuffle=on ./...
(all packages), golangci-lint run ./... (0 issues).

* Harden redirect-count accessors against pooled-session data race (round 44)

* Fix bearer Authorization template strip order + nonce constant-time compare (round 45)

* Sanitize claim-derived identifier on auth-bypass headers (round 48)

* R51: guarantee openid scope in buildAuthURL when filter drops it

* R53: enforce 2048-bit minimum RSA key size on verify

* R54: refresh JWKS on unknown-kid to pick up key rotation

* R55: blacklist session tokens on user logout

* R56: honor RateLimit config as sustained req rate

* R57: FIFO eviction; keep fresh replay JTIs in cache

* R58: idempotent RefreshCoordinator Shutdown; no close-close

* R59: honor backend TTL on cache repopulation

* R60: accept single-string groups/roles; fix mem over-evict

* R61: detect truncated chunked token via stored total

* R62: drain queued tasks on goroutine pool shutdown

* R63: Shutdown waits for in-flight refresh goroutines

* R64: cap metadata cache grace by configured limits

* R65: validate ES client-assertion key curve matches alg

* R66: check expiry on lenient-audience token path

* R67: apply allowedRolesAndGroups gate to SSE/WS bypass

* R68: cache expiry TOCTOU, logout open-redirect, session max-age

* R69: fix double pool-return on session-timeout path

* R70: pooled-client cookie jar, refresh Save-failure cleanup

* R71: SSE/WS allowlist, session max-age, sec headers

* R72: validate combined cookie chunk metadata

* R73: logout jti replay, expired ajax, no-value

* R74: recv handler panics, cache TTL race fix

* R75: azure unauth copy-paste, dcr guard, cookie domain

* R76: dcr singleflight, L1 no-resurrect, TLS loopback

* R77: bearer allowedUsers gate, session inUse CAS

* R78: hybrid Clear flush, reauth reacquire, pool CAS

* R79: invalidation ttl tracks maxage, empty tpl hdr

* R80: req secret for introspection, pool conn on panic

* R81: reject empty access token on callback+refresh

* R82: req discovery endpoints, single-use code retry

* R83: DCR require client_secret for confidential auth, validate redirect_uri scheme; reject callback query/fragment

* R86: atomic SetIfAbsent for replay cache; close double-accept and singleton-read race

* R87: validate backchannel logout token exp; live-refresh JWKS for logout kid-miss

* R88: make StopAllTasks cover ResourceManager singleton tasks

TaskRegistry.CreateSingletonTask delegates to ResourceManager.RegisterBackgroundTask
and stores the task in the ResourceManager's registry, not TaskRegistry.tasks.
TaskRegistry.StopAllTasks previously iterated its own (always-empty) registry,
silently leaking every process-global singleton task's ticker goroutine past the
last Close (memory-monitor, replay-cache-cleanup) — tasks kept running real
periodic work with no instance to serve.

Add ResourceManager.StopAllTasks (stops all rm-owned tasks) and have
TaskRegistry.StopAllTasks stop both its own RegisterTask-direct tasks and the
ResourceManager-owned singletons.

Regression TestR88StopAllTasksStopsResourceManagerOwnedTasks (review_r88_test.go):
fails on old code (task still running after StopAllTasks), passes on new.

* R89: normalize excluded-url paths; apply defaults to pooled HTTP clients

Two verified defects from R89 scout round:

1. Excluded-URL dot-segment traversal widening (P1, auth bypass).
   shouldBypassAuth passes req.URL.Path raw (middleware.go:54); Go's server
   leaves '..' in URL.Path (url.ParseRequestURI does not normalize), so an
   exclusion for /public also matched /public/../admin, letting a real
   sibling (/admin) reach the backend unauthenticated. pathExcluded now
   path.Clean()s the request path ('.' -> '' to preserve root semantics)
   before boundary matching. Regression TestR89ExcludedPathDotTraversal
   fails on old (all 4 traversal cases wrongly excluded), passes on new.

2. Pooled HTTP client had no zero-value defaults (P2, unbounded stall).
   CreateHTTPClient applies defaults; CreatePooledHTTPClient and
   GetOrCreateTransport did not, so a partial config yielded Timeout=0 and
   ResponseHeaderTimeout=0 (a hanging upstream stalls forever). Extracted
   applyHTTPClientDefaults (single source of truth) and applied it in all
   three construction paths; pool cache key now reflects normalized values.
   Regression TestR89PooledClientAppliesDefaults fails on old, passes on new.

R89 clean/declined: session max-age IS absolute-and-enforced-every-request
(verified, review_r68 already locks it); AllowedUserDomains fail-closed (P2
'*' not a wildcard, P3 TrimSpace — declined as config-scoped).

* R92: validate all time claims on lenient-audience access tokens

On the lenient-audience path (validateStandardTokensRS), jwt.Verify
short-circuits at the aud check before reaching exp/iat/nbf validation,
leaving every time claim unvalidated. accessTokenUnexpired previously
re-patched only 'exp' (the R66 fix), so a token with a not-yet-reached
'nbf' but a valid exp was trusted for authorization before it was valid.

accessTokenUnexpired now re-applies the full main-path time validation:
verifyExpiration, verifyIssuedAt (iat required), and verifyNotBefore when
present — all clock-skew-aware. Regression TestR92LenientPathRejectsFutureNbf
(plus valid control) fails on old code (future-nbf token accepted), passes on
new.

R92 clean/declined: bearer auth (aud enforced, full claims — clean);
refresh rotation (correctly bound to session; no local reuse detection =
design); logout cookie completeness (all chunk names cleared, no revive;
two P3 non-security notes declined).

* fix(auth): harden OIDC flow, token validation, session, and bearer handling

- replay entry covers exp + clock-skew window; callback GET-only (RFC 6749)
- callback rate-limit returns 429 + Retry-After; panic-recovery sets no-store
- cross-chunk integrity for chunked tokens; bounded chunked-token read scan
- HTTPError classification so 5xx/429 token-endpoint responses retry
- redaction of token/code/state in logs; per-source external auth gate

* fix(cache): harden cache backends, resilience, recovery, and transports

- RESP -ERR no longer closes healthy conn / aborts batch; global cap replacement-aware
- global health-check pass serialized (latent data race); MemoryMonitor via ResourceManager
- token-exchange retry, open-circuit rejections counted as failures
- TLS-posture matching transport reuse (no silent InsecureSkipVerify handoff)

* fix(config,dcr): env fallbacks, DCR self-heal, per-source auth gate

- implement documented OIDC_* env fallbacks; hold metadataMu for clientAssertion write
- re-register client when client_secret expires; require secret for confidential
- add opt-in per-source external auth rate limiting (PerSourceLoginRateLimit)

* docs: complete config reference and config examples

- CONFIGURATION.md: add 11 previously-omitted optional parameters
- README: document 6 implemented-but-undocumented options
- fix example config (raw .env block made invalid YAML)

* build: pin toolchain to go1.26.6 (resolves 5 reachable stdlib CVEs)

- net/http, asn1, idna GO-2026 CVEs cleared; govulncheck now 0 findings

* fix(jwk): use time.Since for elapsed-time computation (S1012)

* test: add R-round regression and security suite

- fail-on-old regression tests for every shipped fix (R-rounds)
- fuzz targets (parseJWT, bearer), concurrency-stress, shuffle-flake guards
- coverage-closing contract tests (health-check backend, TLS-posture reuse)
- r154 ID-token fixture built from parts to avoid false-positive secret scan

* test: mark synthetic PKCE verifier with trufflehog:ignore

Quiet the Lob detector's false positive on the fake test-only code_verifier,
matching the repo's existing // trufflehog:ignore convention in token_test.go.
Local trufflehog filesystem scan is now 0 verified / 0 unverified.

* fix(circuit-breaker): stop open-circuit rejections from re-arming the open timer (FIX-01)

ExecuteWithContext called the promoted BaseRecoveryMechanism.RecordFailure()
on every request rejected while the circuit is open. RecordFailure sets
lastFailureTime, the same field allowRequest read as the Open->HalfOpen
timer, so each rejection re-armed the timer. Under steady traffic shorter
than Timeout the breaker never left Open (the default-on token breaker,
token_resilience.go:31-36, is affected in production).

CircuitBreaker now tracks its own openedAt timestamp, set only on a
genuine Closed->Open or HalfOpen->Open transition in recordFailure.
allowRequest and IsAvailable gate on openedAt instead of lastFailureTime.
An open-circuit rejection still increments total_failures directly via
atomic.AddInt64, preserving the R180 metrics contract, but no longer
touches lastFailureTime or the open timer.

Adds TestCircuitBreakerOpenRejectionsDoNotExtendOpenWindow, which opens
the breaker (MaxFailures 1, Timeout 50ms) and sends a probe every 10ms;
it fails at head because no probe is ever admitted within 500ms.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(circuit-breaker): ignore terminal client errors in the breaker state machine (FIX-09)

After FIX-01, an ordinary fn() error still trips recordFailure(), which
reopens a half-open circuit unconditionally and holds it half-open for a
full ResetTimeout (15s/30s in production). A per-user HTTPError such as
invalid_grant from a replayed code is not a downstream-health signal, so
under a 1% user-error rate roughly 78% of half-open cycles reopened for
another ResetTimeout, extending real outages.

recordFailure() is now skipped for a terminal client error (HTTPError
4xx other than 429); the promoted RecordFailure() metrics counter still
runs, since the operation did return an error to its caller. 429 and
non-HTTPError failures (network errors, 5xx) are unaffected and still
trip the state machine.

Adds three regression tests: a half-open probe returning HTTPError 400
must stay half-open and later close on success (fails at head: reopens);
HTTPError 429 and a net.OpError must still reopen half-open (already
passing, pinned as a guard against over-broadening the exemption).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(retry): stop single-use retry from matching HTTP response bodies (FIX-14)

ExecuteSingleUseWithContext substring-matched singleUseRetryableErrors
against the raw err.Error() text. helpers.go returns a *HTTPError whose
Message carries up to 10 KiB of the token-endpoint response body once a
response is received, so an IdP 500 that happened to mention "connection
refused" in its own body was retried up to MaxAttempts times even though
the request had definitely reached the server. Re-sending a consumed
authorization code or a rotated refresh token surfaces invalid_grant or
triggers refresh-token-family revocation on rotating IdPs.

Adds isNeverSentError: an *HTTPError (a response was received) is never
retried, and the fragment match now applies only to a genuine *net.OpError
(a dial/connect failure), the concrete type net/http.Client.Do returns
before any request reaches the wire.

Adds TestExecuteSingleUseWithContextNeverRetriesAfterHTTPResponse, which
fails at head (fn called 3 times instead of 1) and passes after the fix,
plus a guard that a real dial error is still retried.

Updates the existing TestRetryExecutor_SingleUse_RetriesPreSendError
(review_r82_test.go) to simulate the dial failure as a *net.OpError
instead of a bare string, matching what client.Do actually returns; the
bare-string form no longer satisfies the tightened, type-based match.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(circuit-breaker): address review for FIX-09

isTerminalClientError used errors.As(err, &httpErr) against an
interpreted *HTTPError target. Under yaegi v0.16.1 (Makefile:9) this
panics with "errors: *target must be interface or implement error",
regardless of the error's own concrete type. CircuitBreaker calls
this on every fn() error, on the default-on token-exchange/refresh
path, so every failed exchange or refresh panicked the goroutine
instead of returning its error, and the panic on the refresh path
(refresh_coordinator.go, an unrecovered goroutine) crashed the
process. Switch to a plain type assertion: the production error
reaches the breaker unwrapped, so no Unwrap chain walk is needed.

Extend cmd/yaegicheck/main.go to drive CircuitBreaker.ExecuteWithContext
under the real interpreter: a plain error (the first call shape that
panicked), a half-open 400 (must stay half-open), a closed-state 400
(must stay closed), and a 429 (must still reopen half-open). make
yaegi-validate now fails on the pre-fix code and passes after.

Also add a Closed-state regression test pinning the existing scope
choice (the terminal-client-error exemption applies to Closed as well
as HalfOpen, not only HalfOpen): a 400 leaves the breaker Closed, and a
following genuine 5xx still opens it. This is coverage-only -- the
Closed-state behavior itself already matched this before the change,
confirmed by running the new test against the pre-fix code (PASS).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(retry): address review for FIX-14

isNeverSentError used errors.As(err, &httpErr) against an interpreted
*HTTPError target. Under yaegi v0.16.1 (Makefile:9) this panics with
"errors: *target must be interface or implement error", regardless of
the error's own concrete type. ExecuteSingleUseWithContext calls this
on every fn() error, on the default-on authorization-code-exchange and
refresh path, so every failed exchange or refresh panicked instead of
returning its error. Switch to a plain type assertion: the production
error reaches here unwrapped, so no Unwrap chain walk is needed. The
errors.As(err, &opErr) match against *net.OpError is untouched -- a
compiled stdlib type, yaegi-safe.

Also narrow the *net.OpError match to Op "dial" or "proxyconnect".
isNeverSentError previously matched singleUseRetryableErrors against
ANY *net.OpError, including "read"/"write", which happen after the
connection is already established and the single-use request may
already have reached the IdP. Only a failed connect proves the request
never went out. Correct the doc comment, which claimed a *net.OpError
is always pre-wire -- it is not.

Extend cmd/yaegicheck/main.go to drive
RetryExecutor.ExecuteSingleUseWithContext under the real interpreter: a
*HTTPError whose Message happens to contain a retryable-looking
fragment (must be called once, never retried) and a real client.Do
dial failure against a closed local port (must be retried to
MaxAttempts). make yaegi-validate now fails on the pre-fix code and
passes after.

Add a regression pinning the Op-scoping fix: a *net.OpError{Op: "read"}
carrying syscall.EHOSTUNREACH is not retried by
ExecuteSingleUseWithContext (fn called once). Confirmed this fails
against the pre-fix code (fn called 3 times) before applying the fix.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(recovery): stop gdInstances leak from TokenResilienceManager (FIX-18)

Register GracefulDegradation in gdInstances synchronously in
NewGracefulDegradation, before the health-check goroutine starts. A
Close() that ran immediately after construction could otherwise race
the async registration and delete nothing, then the later registration
would add an already-closed instance permanently.

Add Close to ErrorRecoveryManager and TokenResilienceManager.
NewTokenResilienceManager builds its own ErrorRecoveryManager (and
therefore its own GracefulDegradation), separate from the plugin
instance own errorRecoveryManager. Production Close() only ever closed
the first one, so the second leaked in gdInstances forever and the
shared health-check task last-instance stop gate never fired.

TraefikOidc.Close now calls Close on both managers.

Regression test TestFix18_ClosingBothManagersEmptiesGDInstances fails
to build at head (Close undefined on both managers) and passes after
the fix.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(tasks): keep pending singleton task instead of orphaning it (FIX-19)

RegisterBackgroundTask replaced any existing task with
started==0 && stopped==0, including one that is merely pending its
first Start() call. CreateSingletonTask (and the two other call sites
sharing its Register-then-Start pattern) does not hold tasksMu across
that sequence, so a second concurrent caller lands in that window and
replaces a task the first caller is about to start. The first caller
then starts an object no longer reachable from the registry, and
StopAllTasks/Shutdown never reach it again.

Add a startRefused flag to BackgroundTask, set on Starts refused by
the circuit breaker or the concurrency limiter (the two early-return
paths that leave started==0 and stopped==0 permanently).
RegisterBackgroundTask now replaces an existing task only when it is
stopped or its one Start attempt was refused, keeping a task that is
simply not started yet.

review_r122_test.go pinned the old "started==0 && stopped==0 always
means replace" behavior with a fixture that force-sets those fields
directly, without ever exercising a real Start() rejection. Update the
fixture to also set startRefused=1, the precise signal that case now
carries, preserving the R122 invariant (a circuit-breaker-rejected
task is still always replaced) alongside the new one.

Regression test TestFix19_RegisterBackgroundTaskKeepsPendingTaskNoOrphan
fails at head (orphan task keeps ticking after StopAllTasks: 13 -> 25)
and passes after the fix.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(lifecycle): re-check last-instance under shared mutex before stop (FIX-35)

Close() decided whether it was the last live instance once, early
in its shutdown sequence (unregisterLiveInstance return value), then
reused that boolean much later to gate three separate singleton
stops (singleton-token-cleanup, singleton-metadata-refresh-*, and
the general StopAllTasks). Session and cache teardown run in
between, taking real time, during which a concurrently-created new
instance (an overlapping Traefik reload) can register and adopt the
same singletons. The stale decision then stops them anyway, leaving
the surviving instance with no memory monitor, token cleanup, or
metadata refresh until the next reload.

Add liveInstanceMu, taken by registerLiveInstance,
unregisterLiveInstance and a new isLastInstanceNow. Close() now calls
isLastInstanceNow() fresh, immediately before each of the three
singleton stops, instead of reusing one early decision.

main.go now calls registerLiveInstance before New adopts the
memory-monitor singleton (previously called after), so a concurrent
Close elsewhere always sees a new instance counted before it can
decide to stop the singletons that instance depends on.

Regression test
TestFix35_ConcurrentNewKeepsSingletonAliveAcrossOldClose fails to
build at head (isLastInstanceNow undefined) and passes after the fix.
A throwaway scratch probe (not committed) confirmed the runtime bug
independently: reproducing the old stale-decision pattern inline
wrongly stops memory-monitor even after a new instance registered and
adopted it.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(refresh): reject CoordinateRefresh after Shutdown, correct stale ctx comments (FIX-36)

CoordinateRefresh called wg.Add(1) unconditionally, with no check
on rc.stopChan, so a request arriving during or after Shutdown still
registered and ran a new refresh operation. go doc sync.WaitGroup.Add
requires that Adds with a positive delta happening when the counter
is zero happen before a Wait; an Add racing the last Done during an
in-progress Wait can panic with WaitGroup misuse.

Add lifecycleMu (RWMutex). CoordinateRefresh now takes RLock around
its stopChan check and its wg.Add(1) call; Shutdown takes Lock()
before closing stopChan. Lock() cannot succeed while any
CoordinateRefresh call holds RLock, so every Add that will ever
happen has completed before Shutdown reaches wg.Wait().
CoordinateRefresh called after Shutdown now returns an error instead
of running.

The comment on the isNew branch claimed in-flight refreshes "are
aborted promptly via rc.ctx when stopChan closes" - rc.ctx does not
exist. An initial version of this fix added it, deriving
executeRefreshAsync timeout context from it and canceling it in
Shutdown, so Shutdown would return before a genuinely in-flight
refresh finished. That directly regressed two existing, deliberately
written tests - TestRefreshCoordinator_ShutdownWaitsForInFlight
(review_r154) and TestRefreshCoordinatorShutdownWaitsForInflight
(review_r63) - which pin that Shutdown must wait for an in-flight
refresh to finish naturally, not abandon it (avoiding a leaked
refresh goroutine). This fix keeps that contract: Shutdown still
waits via wg.Wait(), bounded only by each operation own
RefreshTimeout, and the stale comments are corrected to describe
that behavior accurately instead of a rc.ctx mechanism that does not
exist.

Regression test TestFix36_CoordinateRefreshRejectedAfterShutdown
fails at head (CoordinateRefresh after Shutdown wrongly succeeds
and runs refreshFunc) and passes after the fix. The R63/R154 tests
were re-run and confirmed still green.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(refresh): replace timing-margin sleeps with deterministic waits (FIX-22)

Four tests raced the 100ms DeduplicationCleanupDelay cleanup timer
with a 150ms fixed sleep, a 50ms margin. A late timer let the next
call join the previous operation instead of starting a new one,
under-counting circuit-breaker/rate-limit attempts on loaded CI
runners. A fifth test (internal/cache/backends) raced singleflights
own 100ms delayed-cleanup goroutine the same way.

Set DeduplicationCleanupDelay=0 on the four RefreshCoordinator tests
(TestRefreshCoordinatorIntegration CircuitBreaker and RateLimiting
subtests, TestCircuitBreakerProtection,
TestRefreshCoordinator_SuccessOnlyAfterCombinedOperations), matching
the pattern already used elsewhere in refresh_coordinator_test.go.
Delay=0 alone is not fully deterministic: close(operation.done) and
the synchronous cleanup call are two separate statements in the same
deferred closure, so a waiter woken by the channel close can run
concurrently with, and observe the map entry before, that same
goroutines next statement. Confirmed this manually: an
intermediate delay-only version (no polling) failed 1 run out of 20
under -race -shuffle=on with the exact under-counting symptom the
finding describes.

Add waitForRefreshDrain, which polls
RefreshCoordinator.inFlightRefreshes for the tokens removal instead
of sleeping a fixed margin, and use it in all four loops. For
internal/cache/backends/review_r141_test.go, poll
SingleflightCache.calls under its own mutex the same way, per the
todo acceptance criterion.

All four tests plus the r141 test now pass go test -race -count=20
-shuffle=on with no fixed sleep at the previously-flaky sites, and
keep their existing assertions.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(refresh): assert bounded Shutdown and goroutine exit (FIX-23)

TestRefreshCoordinatorShutdownStopsCleanup called Shutdown() with no
assertion, so it passed on base regardless of whether Shutdown
actually stopped the cleanup goroutine. Only the sibling
TestRefreshCoordinatorShutdownIdempotent caught anything (a panic on
double-close).

Assert Shutdown returns within a 2s deadline, then independently
observe the cleanup goroutine exit via rc.wg (the same WaitGroup
Shutdown wg.Wait() depends on, bracketing exactly cleanupRoutine).

Mutation check performed and reverted: temporarily removing the
"case <-rc.stopChan: return" branch from cleanupRoutine makes the
test fail with "Shutdown did not return within the deadline" (the
goroutine loops on the ticker forever, wg.Done() never fires).
refresh_coordinator.go is unmodified in this commit (git diff
--stat shows only review_r58_shutdown_test.go); the mutation was
applied and reverted locally to prove the pin is live before this
commit.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(recovery): address review for FIX-18

Fix the close-before-goroutine race the review reopened: delete the
duplicate async registration in startHealthCheckRoutine (only
NewGracefulDegradation registers now), and make the goroutine check
gd.stopChan under gd.mutex before creating or adopting the shared
health-check task, so a closed instance can never (re)start it.

Close() now stops the shared task by name via
GetResourceManager().StopBackgroundTask instead of reading this
instance own gd.healthCheckTask field. With two or more instances,
that field can still be nil on the last-closing instance even though
a sibling already started the shared task, which would have skipped
the stop and leaked the task.

Close every remaining GracefulDegradation NewWithContext can leak: add
a deferred cleanup that closes t.errorRecoveryManager and
t.tokenResilienceManager on any error return after they are
constructed.

Add TestFix18_CloseImmediatelyAfterNewDoesNotReRegister (pins the
exact race; fails deterministically pre-fix, green across
-count=300 -cpu=1,4,16 post-fix), TestFix18_TraefikOidcCloseEmptiesGDInstances
(drives the real TraefikOidc.Close instead of calling the managers
Close directly), and TestFix18_NewWithContextClosesManagersOnEarlyError
(pins the NewWithContext error-path leak). Make the existing
TestFix18_ClosingBothManagersEmptiesGDInstances wait for each
instance async health-check goroutine to settle before closing, via
the new gd.healthRoutineSettled helper, so it exercises the
task-already-assigned path deterministically instead of sometimes
racing the goroutine.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(lifecycle): address review for FIX-35

Close the check-then-stop window the review reopened: isLastInstanceNow
released liveInstanceMu as soon as it returned, before the actual
singleton stop ran (StopBackgroundTask / StopAllTasks, which can block
up to 5s per task). A concurrent New() could register and adopt the
very singleton in that gap, and the stop would kill it anyway.

Add stopIfLastInstance, which holds liveInstanceMu across both the
check and the stop callback, and use it at all three gated stops in
Close() (singleton-token-cleanup, singleton-metadata-refresh-*,
StopAllTasks) in place of the bare isLastInstanceNow() check.

Add TestFix35_StopIfLastInstanceHoldsLockAcrossCheckAndStop, which
proves the lock is genuinely held for the stop full duration (a
concurrent registerLiveInstance cannot complete while a slow stop
callback is still running). Rewrite
TestFix35_ConcurrentNewKeepsSingletonAliveAcrossOldClose to drive the
real (*TraefikOidc).Close via a new closeTestHook (nil in production,
invoked once in Close right after unregisterLiveInstance) instead of
re-implementing Close stop decision inline — the previous version
stayed green even with the production fix fully reverted, since it
never called Close at all.

Both new tests fail to build pre-fix (stopIfLastInstance and
closeTestHook are new symbols); green post-fix across
-count=50 -cpu=1,4,16.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(session): expire chunk cookies before writing replacement chunks (FIX-05)

SetRefreshToken and SetIDToken re-Get and fill the new chunk sessions
before calling the expire helper for the old ones. gorilla Registry.Get
returns the same cached *sessions.Session per cookie name for a request,
so the expire pass re-Gets the objects this call just wrote and wipes
their Values, silently dropping the replacement token.

Reorder both methods to match SetAccessToken: validate chunk count,
sizes and reassembly first (pure computation, no store.Get), then
expire the old chunks, then Get and fill the new ones. A session whose
refresh or ID token was loaded from existing chunk cookies and gets
replaced with another token that also needs chunking no longer loses
the new token.

Adds fix05_session_chunk_replace_test.go, adapted from
.claude/review-2026-09-10/repro/zz_g1_chunkwipe_test.go and
zz_g1_chunkwipe_id_test.go with helpers and test names renamed to
describe the behavior pinned.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(session): gate deferred pool-return on ownership generation (FIX-10)

ServeHTTP defers session.returnToPoolSafely() right after GetSession.
The invalidated-session paths deeper in the same request (backchannel/
frontchannel logout detection) can session.Clear() that exact object
and re-acquire a fresh one before ServeHTTP returns. The deferred call
stays bound to the original pointer regardless, so if a concurrent
request pops the same pooled object before this deferred call fires,
its CompareAndSwap(true, false) still succeeds against the new owner
and Reset()s a session another request is actively using (ABA on the
pool-return CAS).

Add a generation counter to SessionData, bumped once by GetSession and
newSession on every handout. ownerGeneration() reads the current
value; returnToPoolIfOwner(gen) only acts if the generation still
matches what the caller captured at acquire time, so a stale deferred
call from a previous ownership epoch is a deliberate no-op instead of
releasing a live session. ServeHTTP now captures the generation right
after GetSession and defers returnToPoolIfOwner instead of the plain
call.

This is the generation-counter alternative the finding names, chosen
over nil-ing the deferred pointer: the Clear+reacquire happens inside
processAuthorizedRequestRS/processAuthorizedRequest, separate
functions from the ServeHTTP-scope defer, so nil-ing a local variable
there cannot reach the already-bound deferred call.

Adds fix10_session_pool_aba_test.go, adapted from
.claude/review-2026-09-10/repro/zz_g1_aba_test.go with the helper
names and test renamed, and rewritten to drive the ABA sequence
deterministically (the pool handing back the same object after Clear
is unspecified sync.Pool timing, not part of the fixed contract, and
did not reproduce on every run).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(middleware): require real preflight headers for the OPTIONS auth bypass (FIX-02)

shouldBypassAuth bypassed OIDC auth for any request whose method is
OPTIONS. A genuine CORS preflight always carries both an Origin header
and an Access-Control-Request-Method header; gating on the method
alone let an unauthenticated OPTIONS on any protected path reach the
backend with no session check. Reproduced against http.FileServer:
200 with the protected file body, no cookie, no Origin.

Require both headers before treating an OPTIONS request as a
preflight bypass. A genuine preflight still bypasses unconditionally;
every other OPTIONS request now goes through the normal auth
pipeline.

Adds fix02_options_bypass_test.go covering shouldBypassAuth directly
(bare OPTIONS, Origin-only, and a genuine preflight) plus an
end-to-end ServeHTTP reproduction of the leak and its fix. Updates the
existing TestShouldBypassAuth_PassesOptions in review_r124_test.go
(touched_outside) to send a genuine preflight instead of a bare
OPTIONS, since it asserted the vulnerable bypass-on-method-alone
behavior.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(middleware): drop oversized ID token header instead of truncating (FIX-34)

forwardAuthorized truncated an ID token longer than headerTemplateMaxLen
(8192 bytes) and still set X-Auth-Request-Token to the truncated value.
A truncated JWT is structurally invalid: a downstream that verifies the
signature rejects it (fine), but one that only base64-decodes claims
without verifying reads a corrupted value.

Drop the header instead of truncating, matching the fail-closed
pattern already used for X-Forwarded-User / X-Auth-Request-User in the
same function when identifier sanitization fails.

Adds fix34_idtoken_header_test.go (oversized token drops the header;
in-budget token still forwards unmodified). Updates
review_r155_regression_test.go (touched_outside): its existing test
asserted the header was truncated to exactly headerTemplateMaxLen
bytes, which is the behavior this fix replaces; renamed to
TestR155_XAuthRequestToken_DroppedWhenOverHeaderBudget and rewritten
to assert the header is absent.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(middleware): hand next.ServeHTTP the real writer, not the tracking wrapper (FIX-06)

ServeHTTP wraps rw in *trackingWriter (rw = tw) for panic-commit
tracking and then forwards that SAME wrapped writer to every
t.next.ServeHTTP call: excluded, SSE, WebSocket, options bypass, the
default case, and forwardAuthorized (the authenticated path). Traefik
runs the plugin interpreted under yaegi v0.16.1, whose stdlib interop
layer composes a boundary wrapper only for ResponseWriter+Hijacker
crossing into compiled code, never for Flusher or the Unwrap pattern
http.ResponseController relies on. So Traefik's compiled ReverseProxy
calling http.NewResponseController(rw).Flush() for SSE gets "feature
not supported" in production, even though trackingWriter declares
Flush/Unwrap and native tests (which never cross an interpreter
boundary) pass.

Reproduced with a throwaway yaegi run probe (not committed; yaegi
v0.16.1, GOPATH/bin/yaegi) mirroring trackingWriter exactly:
  wrapped:   ResponseController.Flush err=feature not supported, recorderFlushed=false
  unwrapped: ResponseController.Flush err=<nil>,                 recorderFlushed=true
matching the finding's own reproduction.

Add downstreamWriter(rw), used at every t.next.ServeHTTP call site: it
unwraps *trackingWriter to the real writer ServeHTTP received, and
marks the trackingWriter's new calledNext field so the deferred
recover (which may run in a different function than the call site, via
forwardAuthorized) knows control passed downstream.

Handing next the real writer means wroteHeader can no longer observe
writes next makes directly (it bypasses tw entirely). The deferred
panic recovery is updated to skip its fallback 500 once calledNext is
true: guessing in that state risks appending "Internal Server Error"
to a response next already committed, which TestR155_ServeHTTP_
PanicAfterCommitKeepsBodyIntact exists to prevent and is the more
severe failure mode. A panic in the middleware's own pre-forward code
is unaffected and still gets a clean 500
(TestR179_PanicRecoverySetsNoStore). Updates review_r74_test.go
(touched_outside): its existing assertion that a downstream (next)
panic forces a 500 is no longer achievable without that same
corruption risk; rewritten to assert the recovered-but-unwritten
default (200) Go's http.Server already gives any handler that returns
without writing.

Adds fix06_downstream_writer_test.go: asserts next receives the
unwrapped writer on the SSE, WebSocket and authenticated
(forwardAuthorized) paths.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(middleware): make FIX-06 actually load and behave correctly under yaegi (FIX-06)

trackingWriter now declares Header() explicitly instead of relying on
the embedded http.ResponseWriter promotion. yaegi v0.16.1 does not
count a promoted method when it statically checks whether
*trackingWriter satisfies http.ResponseWriter, so the plugin refused
to load under yaegi at all ("missing Header method"), invisible to
every native test. Verified with a temp GOPATH symlinked to this
worktree (the shared GOPATH symlink resolves to the main checkout, not
this branch) via `yaegi run ./cmd/yaegicheck/main.go`: FAIL before
this change, OK after.

ServeHTTP's panic-recovery defer now sends a header-only 500
(Cache-Control: no-store) whenever nothing was written through the
tracking wrapper, even after control has passed to next
(tw.calledNext). WriteHeader is idempotent, so this is a no-op if next
already committed its own response; only the fallback body Write is
still gated on !calledNext, since only a body Write can corrupt an
already-committed response. Previously the whole 500 was skipped once
calledNext was true, so a downstream panic before any write produced
an empty 200 instead of a 500, telling the client a failed request
succeeded. review_r74_test.go is restored to asserting 500 (its
925d627 baseline), with comments updated for the new behavior.

Adds cmd/yaegiflushcheck, a nested Go module (its own go.mod, so it
never enters the root module's build/vendor graph) that drives the
real plugin under yaegi with a COMPILED next handler calling
http.NewResponseController(w).Flush(), reproducing the finding
end-to-end rather than only at import time. Confirmed it fails
("feature not supported") when downstreamWriter is reverted to not
unwrap the tracking writer, and passes ("err=<nil>") against the fix.
fix06_downstream_writer_test.go's dangling reference to a
never-committed fix06_yaegi_probe.go now points at this file.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(middleware): discard the response body on a forged CORS preflight (FIX-02)

The FIX-02 header check (Origin + Access-Control-Request-Method) rules
out an accidental bare OPTIONS request but not a deliberate attacker:
any non-browser client can set both headers itself, and
bypassReasonOptions still forwarded that unauthenticated request to
next with no session check. Reproduced against http.FileServer: a
forged preflight with no cookie still returned the protected file's
body.

This exceeds what the FIX-02 todo originally asked for, so flagging
for maintainer sign-off (see the fixes report's concerns) even though
it is implemented here: severity is major with a concrete exploit, and
leaving it undone seemed worse than the scope overrun.

ServeHTTP's bypassReasonOptions case now hands next an
optionsPreflightWriter instead of the raw writer. It forwards
Header()/WriteHeader() (deleting any Content-Length next sets, since
no body follows) but discards every Write(). A browser never reads a
preflight response body, so a genuine CORS preflight keeps working
unchanged (TestServeHTTP_GenuinePreflightReachesBackend still passes);
a forged one can no longer read protected content through this path.
Declares Header/Write/WriteHeader explicitly rather than relying on
the embedded http.ResponseWriter's promotion, for the same yaegi
reason as trackingWriter (FIX-06): confirmed the plugin still loads
clean under yaegi (cmd/yaegicheck) with this change.

Adds TestServeHTTP_ForgedPreflightDoesNotLeakBody, which reproduces
the finding's own repro (http.FileServer, forged Origin +
Access-Control-Request-Method, no cookie) and asserts the body never
reaches the caller.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(bearer): gate opaque-token introspection and bind it to the client (FIX-03)

buildPrincipalFromOpaqueIntrospection accepted any introspected
active=true token from the IdP, with none of the JWT-path gates: it never
checked allowOpaqueTokens, never bound the response to this client when
audience==clientID (the common default), and never consulted
isSessionInvalidated or bearerIdentifierClaim/sanitizeBearerIdentifier/
maxTokenAge. A token issued to an unrelated client at the same IdP could
authenticate as any user, and IdP-initiated logout did not revoke an opaque
bearer token.

Gate the opaque branch behind the existing allowOpaqueTokens flag (no new
config knob). When audience==clientID, require resp.ClientID==clientID or
an aud containing clientID. Apply the identifier claim, sanitization,
maxTokenAge (resp.Iat) and isSessionInvalidated (by sub; RFC 7662 carries
no sid) the same way the JWT bearer path does. Update review_r159 and
review_r166 fixtures to set allowOpaqueTokens and a matching client_id, and
document the gated contract in docs/BEARER_AUTH.md.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(introspection): stop treating introspection 4xx as token-revoked (FIX-13)

R156 (8640451) mapped any 400-499 status from the introspection endpoint
to a definite "token invalid" verdict, on the session path
(token_validation_rs.go) and both bearer-path introspection call sites
(bearer_auth.go). RFC 7662 s2.2 defines only a 200 response with
active=false as inactive; s2.3 defines a 401 as the plugin own client
credentials being rejected, not a statement about the token. A rotated
client_secret or an IdP 429 therefore turned every valid token into a 401,
fed the bearer per-IP penalty box, and forced a refresh storm on the
session path.

Remove the 4xx-as-invalid special case at all three sites so those errors
fall into the existing generic handling: bearerErrIntrospectionUnavailable
(503) on the bearer path, and the existing requireTokenIntrospection-gated
fail-closed / transient-fallthrough on the session path. Only a 200
response with active=false still rejects the token. Update the R156
fixture that pinned the old (now superseded) 401-forces-refresh contract,
and document the corrected 401/503 split in docs/BEARER_AUTH.md.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(bearer): fail closed on logout invalidation when iat is absent (FIX-24)

buildPrincipalFromBearerToken derived the backchannel-logout invalidation
createdAt from iat, falling back to time.Now() when absent. 8640451 made
iat OPTIONAL in jwt.Verify (R126), so an access token without iat now
reaches this check. The time.Now() fallback made such a token always look
newer than any logout event, so IdP-initiated logout never revoked it,
reintroducing the R98 defect the cookie path already avoids by falling
back to the zero time instead.

Fall back to the zero time (fail closed) instead of time.Now(), matching
sessionCreatedAtForInvalidation on the cookie path. Also correct the stale
comment on enforceIatAge, which claimed jwt.Verify still hard-requires iat.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(bearer): stop sweeping in-progress failure counters (FIX-28)

recordFailure map-growth sweep deleted every entry whose penaltyUntil was
before the cutoff. An entry that has not tripped the penalty box yet has a
zero penaltyUntil, which is always before any cutoff, so once the map
passed defaultBearerEntrySweepThreshold every accumulating counter was
discarded regardless of how recently it started. An attacker who floods
many distinct source IPs (or one interleaving its own failures with
sweeps) could keep any one source below the threshold forever.

Delete an entry only when it is BOTH untripped-or-expired AND outside the
counting window: penaltyUntil.Before(cutoff) AND firstFailureAt is older
than the window. A fresh, still-accumulating counter now survives a sweep;
only entries that have genuinely gone stale are reclaimed. Update the R214
memory-bound test: a fresh flood within the window is now expected to grow
past the threshold (that is the fix, not a regression), while entries that
age past the window still get swept, which the rewritten test verifies in
a second phase.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(jwt): share the time-claims contract between Verify and the lenient path (FIX-27)

accessTokenUnexpired (the lenient-audience-path re-check that runs after
jwt.Verify short-circuits at the aud check) still hard-required iat, even
though 8640451 made iat OPTIONAL in jwt.Verify itself per RFC 7519 4.1.6
(R126). The two paths had drifted onto different contracts for the same
claim: an iat-less lenient-audience access token was always forced to
refresh or re-authenticate, while the identical token with a matching
audience passed through jwt.Verify fine.

Maintainer confirmed the iat-optional contract (R126) stands. Extract the
exp/iat/nbf validation shared by both paths into one verifyTimeClaims
helper in jwt.go and use it from both jwt.Verify and accessTokenUnexpired,
so the two cannot independently drift on which time claims are mandatory
again. Both R92 fixtures (which carry iat) keep passing.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(bearer): amortize the failure-tracker map-growth sweep (FIX-28)

recordFailure swept the whole entries map on every call once the map
crossed defaultBearerEntrySweepThreshold, even when the sweep found
nothing stale to delete. A flood of distinct source IPs (attacker-
controlled) turned this into O(n) work under b.mu on every call, O(n^2)
to fill the map, while blocked() waits on the same mutex on every
bearer request.

Add nextSweepAt, which doubles after each sweep (bounded below by
defaultBearerEntrySweepThreshold), so the scan runs only when the map
has genuinely grown, amortizing its frequency to logarithmic in the
flood size instead of linear. Add sweepPasses to count scans for
tests.

Rewrite TestBearerFailureTrackerSweepBoundsMemory phase 2 to record
failures until the next amortized sweep actually fires, then assert
the aged keys are gone, rather than asserting a fixed total-size
bound that the amortized gate no longer holds to on every call. Add
TestBearerFailureTrackerSweepAmortized: 30,000 fresh distinct sources
must trigger at most 6 sweep passes (HEAD triggers on ~29,000 calls).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(bearer): close 3 opaque-introspection gaps: sid logout, iat bound, identifier claims (FIX-03)

buildPrincipalFromOpaqueIntrospection had three gaps against the JWT
bearer path it mirrors:

- isSessionInvalidated was always called with an empty sid, so a
  sid-only (front-channel) logout never revoked an opaque token, even
  when the IdP introspection response itself carried a sid. Add Sid
  to IntrospectionResponse and pass resp.Sid through.
- maxTokenAge was applied only when resp.Iat > 0, silently skipping
  the bound on a response with no iat, unlike enforceIatAge on the
  JWT path (which fails closed on a missing iat once maxAge is set,
  and New() always sets it > 0). Route the opaque-path check through
  enforceIatAge itself so the two paths cannot drift again.
- The identifier claims map was built from sub/username only, so any
  other bearerIdentifierClaim value (client_id, scope, iss, jti, aud)
  always 401d with "missing claim", even when the introspection
  response carried it.

Add regression tests for all three (sid-only logout, missing iat with
maxTokenAge set, bearerIdentifierClaim=client_id). Add iat to the
R159/R166 introspection fixtures, which otherwise now fail the
enforced age bound under makeBearerOIDC's 24h maxTokenAge default.
Document the opaque iat requirement and the sid-only logout scope in
docs/BEARER_AUTH.md.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(introspection): stop classifying session-path introspection errors by IdP body text (FIX-13)

validateOpaqueToken wraps introspectTokens *HTTPError for a non-200
introspection response, and HTTPError.Message embeds up to 10 KiB of
the IdPs own response body. validateStandardTokensRS substring-matched
that message for "token is not active", "revoked" or "token has
expired" before reaching the transient/fail-closed branch, so a
401/403/429 whose body happened to contain one of those words (e.g.
the IdPs OWN client-secret-revoked error, RFC 7662 s2.3) still forced
a refresh, even though only a 200 response with active=false may
reject the token.

Detect an *HTTPError via errors.As before the substring match and
route it straight to the requireTokenIntrospection/transient handling.
Only validateOpaqueTokens own generated messages (active=false,
expired, nbf — never an *HTTPError) still reach the substring
classification. Add a regression test: a 401 with "revoked" in the
body, requireTokenIntrospection=false, must not force a refresh.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(bearer): correct maxTokenAge opt-in comments (FIX-24)

The enforceIatAge and TestBearerLogoutInvalidation_NoIatFallsClosedNotOpen
comments called maxTokenAge>0 an "operator opt-in": false. New()s
config-default closure (main.go:357-362) always sets maxTokenAge > 0 —
0/unset becomes 24h — so enforceIatAge rejects every iat-less bearer
JWT in production, opt-in or not. Only a test that constructs
*TraefikOidc directly (bypassing New()) can set maxTokenAge=0.

Reword both comments to state this, and note that the zero-time
createdAt fallback for the logout-invalidation check is mostly
defense in depth given that in production: it is what protects an
iat-less token only when maxTokenAge is explicitly 0 or the object
bypasses New(), since enforceIatAge otherwise rejects the token first.

No behavior change. Separately, docs/BEARER_AUTH.md:164 and
docs/CONFIGURATION.md:288 state "0 disables the check", which
contradicts main.go:357-362 (0 becomes 24h, it is never actually
disabled) -- flagged to the lead as a pre-existing doc/code mismatch
outside this packages scope, not fixed here.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): stop deleting applied-but-slow backend writes on Set failure (FIX-04)

RedisBackend.executeWithRetry checked ctx.Err() before err==nil, so a SET
that completed after the caller gave up waiting reported as failed even
though Redis applied it. UniversalCache.Set then issued a Delete on any
backend Set error, erasing the value that write just landed.

Reorder executeWithRetry to return nil immediately on a successful
operation, before consulting ctx.Err(). Skip the Delete in
UniversalCache.Set when the error is a context deadline/timeout (the
write may have applied), and unconditionally for MonotonicMarkers caches
(blacklist, session invalidation), whose entries are revocation markers
and are never stale regardless of the failure reason.

Adds MonotonicMarkers to UniversalCacheConfig, set for the blacklist and
session-invalidation cache configs in universal_cache_singleton.go.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): add blacklist to getLocal RLock fast path (FIX-15)

The blacklist cache moved to CacheTypeBlacklist but the getLocal fast
path only gained CacheTypeIntrospection, so every blacklist lookup fell
to the exclusive c.mu.Lock(). tokenBlacklist.Get runs on the verify path
for every authenticated request, so this re-created the RLock-convoy
pattern (a single expired entry serializing every concurrent JWT verify
under yaegi) the fast path exists to prevent.

Add CacheTypeBlacklist to the fast-path case list.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): read legacy token: namespace on blacklist miss (FIX-16)

The R128 rename moved the blacklist cache backend namespace from
CacheTypeToken (token:<key>) to CacheTypeBlacklist (blacklist:<key>) with
no migration. Revocation markers written before the upgrade (TTL up to
24h) were ignored after it, and mixed-version replicas in a rolling
deploy did not share revocations, since old and new instances read and
write different namespaces.

On a blacklist miss, also read the legacy token:<key> backend entry.
Treat it as blacklisted only when the stored value deserializes to
boolean true, so a CacheTypeToken claims-map entry for the same raw
token is never misread as a revocation marker. Writes stay on the new
blacklist: namespace only.

Upgrade note: operators upgrading through this release keep denying
tokens revoked by a pre-upgrade instance for the lifetime of the
revocation marker (up to 24h). The legacy-namespace read is a one-release
compatibility shim; a future release can drop checkLegacyBlacklistMarker
and legacyBlacklistPrefix in universal_cache.go once all replicas have
rolled forward past the R128 rename.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): use PTTL and a no-expiry sentinel for Get TTL (FIX-31)

RedisBackend.Get read TTL (second precision), which maps both "no
expiry" (-1) and "under one second left" to a reported ttl of 0.
UniversalCache.Get treated any ttl<=0 as DefaultTTL, so a key on the
verge of expiring in Redis got re-cached locally for the cache's full
DefaultTTL, up to 25h for the session-invalidation cache, well past the
real expiry of the entry.

Switch Get to PTTL (millisecond precision) and return the distinct
NoExpiryTTL sentinel for a key with no associated expiry. Update
UniversalCache.Get to federate DefaultTTL only for that sentinel, and to
skip repopulating the local copy for any other non-positive ttl instead
of defaulting to DefaultTTL.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): address review for FIX-04

Replace the anonymous-interface errors.As in isTimeoutOrDeadlineError
with the compiled net.Error pattern already used in error_recovery.go.
Under yaegi v0.16.1, errors.As against `var x interface{ Timeout() bool
}` panics with "errors: *target must be interface or implement error"
when the plugin package is interpreted the way Traefik loads it (GOPATH
self-import, not `go test`). Every non-context Set error on a
non-monotonic cache panicked UniversalCache.Set in Redis mode. Verified
this session: repointing the ~/.go/src GOPATH symlink to this worktree
(make yaegi-validate otherwise silently validates the main checkout,
see the yaegi-validate-gopath-symlink memory note) reproduces the exact
panic on the old code and confirms it is gone on the new code, both via
a standalone repro script and via a new cmd/yaegicheck guard
(checkUniversalCacheSetDoesNotPanicOnBackendError) that make
yaegi-validate now runs on every call.

Add the backend-stale local-write guard the FIX-04 todo asked for.
Skipping the post-failure Delete (timeout error, or a MonotonicMarkers
cache) leaves the backend holding whatever was there before the failed
Set. Get() previously trusted that backend value unconditionally,
reopening R162 for a deadline-erroring Set that never applied, and
silently masking a newer session-invalidation logout with an older
Redis timestamp when the newer Set's write failed. UniversalCache now
tracks a per-key backend-stale mark (staleBackend, cleared by the next
successful backend Set and by item removal/eviction/Clear); Get()
prefers the live local value over the backend value for a marked key
instead of overwriting it via updateLocalCache. Corrects the
MonotonicMarkers doc comment, which claimed session-invalidation
entries are "never stale" - they are Unix timestamps compared by
value, so an older one really can be stale next to a newer one.

Add SkipAutoCleanup/Close to the FIX-04 and FIX-16 test caches that
were leaking a cleanup goroutine and ticker per test run.

Tests: TestFIX04_TimeoutSetFailureServesFreshLocalNotStale,
TestFIX04_SessionInvalidationNewerLogoutDeadlineServesFreshLocal,
TestFIX04_SessionInvalidationNewerLogoutErrorReplyServesFreshLocal
(new); existing TestFIX04_*, TestFIX16_*, TestR162_* re-run clean.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): address review for FIX-31

Correct the NoExpiryTTL godoc: it said the sentinel covers "Redis PTTL
-2/-1", contradicting the very next sentence, but Get only maps PTTL
-1 to NoExpiryTTL. PTTL -2 (and 0) map to a reported ttl of 0, same as
an about-to-expire key.

Tighten TestFIX31_GetWithRealTTLReportsPositiveDuration with a lower
bound near the set TTL. The prior assertions (ttl>0, ttl<=10s) do not
pin the millisecond-precision PTTL contract: reproduced this session
by mutating Get back to `conn.Do("TTL", ...)` while still reading the
reply as milliseconds — both FIX-31 backend tests still passed, and a
10s key reported "10ms" as its TTL. The new `ttl>9s` bound fails on
that same mutation ("10ms" is not greater than "9s") and passes on the
real PTTL-based code.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): address review for FIX-16

Reword the legacy-blacklist-namespace comment in Get(). It claimed
mixed-version replicas "share revocations" during a rolling deploy,
but the shim is one-directional: an upgraded replica still honors a
revocation a pre-upgrade replica wrote under the legacy "token:"
namespace (checkLegacyBlacklistMarker on a "blacklist:" miss), but a
pre-upgrade replica has no knowledge of "blacklist:" and never sees a
revocation an upgraded replica writes. Writes stay on the new
namespace only, unchanged.

Comment-only change; TestFIX16_* re-run clean.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache/redis): drain array after nested -ERR reply (FIX-37)

readArray returned early on the first nested "-ERR" element, leaving
declared-but-unread elements on the connection. Do treats
ErrCommandReply as non-fatal and returns the connection to the pool, so
the leftover bytes could be read as the reply to the next command on
that connection (response desync).

readArray now keeps reading past a nested command-error reply, storing
it as the element value, and only aborts on a genuine IO or protocol
error.

Regression test proves a nested -ERR no longer aborts the array read
and that a subsequent reply on the same stream is not corrupted by
leftover bytes.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache/redis): surface pipeline command errors in GetMany (FIX-38)

Pipeline.Execute stores a Redis command-error reply (e.g. LOADING,
WRONGTYPE) as an error value in the responses slice instead of failing
the batch. GetMany ran that value through RESPString, which always
failed on an error value, and counted the failure as a cache miss with
no log. A command error therefore looked identical to "key not found".

GetMany now recognizes an error-valued response, keeps it out of the
miss count, and returns it wrapped with the offending key. Other keys
in the same batch still populate the result map.

Regression test proves a WRONGTYPE reply for one key is surfaced as an
error, not silently dropped, while a good key in the same batch still
comes back.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* chore(cache): remove unreachable internal/cache dead code (FIX-43)

Grep confirms no non-test code imports traefikoidc/internal/cache, and
NewMemoryBackend/NewHybridBackend have no production caller anywhere
(only tests of the twins themselves). The production cache path is
UniversalCache over the root-level backends package; R64/R68/R74/R76/
R78 fixes to these twins had no production effect, and R64 duplicates
logic that already exists in universal_cache.go (unchanged).

Removed:
- internal/cache (parent package): cache.go, manager.go, typed_cache.go,
  compat.go, log_redact.go, and their tests.
- internal/cache/backends: memory.go, memory_shard.go, memory_wrapper.go,
  hybrid.go, and their tests. FIX-20 (hybrid.go asyncWg race) is
  superseded by this removal and is not fixed.

Tests that exercised the deleted MemoryCacheBackend/cacheShard/
MemoryBackend/HybridBackend internals directly are removed with them
(review_r76/78/99/124/125/139_f2/177_regression_test.go under
backends, race_regression_test.go). Tests that used NewMemoryBackend
only as a convenient CacheBackend substrate for still-alive production
code (singleflight.go, review_r141/r212 stress tests, and the root
package JWKCache tests via NewMemoryBackendForTest) now build that
substrate from a miniredis-backed RedisBackend instead. Assertions are
unchanged.

The redis.go retry classifier depended on a small case-insensitive
contains/toLower helper that had been living in hybrid.go; moved to a
new stringutil.go so the redis backend keeps working standalone.

go list ./... no longer lists internal/cache (only backends and
resilience remain); build, vet and the full race test suite are green.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache/backends): delete now-unused redactKey (FIX-43)

redactKey had callers only in the deleted hybrid.go. staticcheck U1000
and a full golangci-lint run both flagged it as unused after the FIX-43
deletion. Delete it and move the package doc comment it carried onto
interface.go, replacing that file's stale singular-typo comment.

staticcheck ./... and golangci-lint run ./... (no --new-from-rev) both
report 0 issues in internal/cache/backends after this change.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache/backends): treat nested nil array elements as values (FIX-37)

readArray aborted on a nested "$-1" or "*-1" element by returning
ErrNilResponse, leaving trailing array elements unread on the wire.
Do() treats ErrNilResponse as a healthy-connection signal and keeps
the connection pooled, so the next command desyncs onto the leftover
bytes. This is the same desync the nested "-ERR" fix already handles.

Store nil for a nested ErrNilResponse and keep draining the array,
mirroring how Pipeline.Execute already treats ErrNilResponse as a
non-fatal per-command value. Top-level "$-1"/"*-1" still return
ErrNilResponse unchanged.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(cache/backends): assert misses counter on GetMany command error (FIX-38)

The regression test only checked the returned error and the good key
result, not the misses counter, so the todo acceptance criterion
"does not increment misses" went unenforced.

Snapshot GetStats() before and after GetMany and assert misses is
unchanged and hits goes up by exactly one. Verified the test catches
the regression by temporarily reintroducing r.misses.Add(1) in the
resp.(error) branch: the test fails with "expected: 0 actual: 1" on
the misses assertion. Reverted the mutation; redis.go has no diff.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(test): close miniredis in NewMemoryBackendForTest (FIX-43)

NewMemoryBackendForTest started a miniredis server as a local variable
and never closed it. Callers only deferred backend.Close(), which
closes the RedisBackend pool, not the miniredis listener, so each
call leaked a listener and its goroutines for the rest of the test
binary.

NewMemoryBackendForTest now takes *testing.T and registers the
miniredis server against t.Cleanup(mr.Close), matching the pattern
already used by NewMiniredisServer and setupTestRedis in
internal/cache/backends. Updated both call sites (review_r124_test.go,
review_r130_test.go) to pass t.

New regression test in memory_backend_for_test_leak_test.go dials the
miniredis address after the owning subtest ends and asserts the
connection is refused. It fails against the pre-fix helper (dial
succeeds, listener still up) and passes after the fix.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(cache): fix comments referencing deleted FIX-43 files (FIX-43)

Several comments still pointed at code the FIX-43 dead-code deletion
removed: sharded_cache.go and review_r129_test.go cited
internal/cache/backends/memory_shard.go, and review_r34_regression_test.go
cited a nonexistent hybrid TestRecordL2Error. interface_test.go claimed
the RedisBackend contract subtest actually runs, but setupRedisBackend
also t.Skips, so TestCacheBackendContract currently exercises neither
subtest.

Reword each comment to drop the stale references and, for
interface_test.go, state plainly that both subtests are pending
t.Skip stubs.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(jwk): bound repeat JWKS fetches after a failed refresh (FIX-30)

doLiveRefresh recorded the force-refresh cooldown only after a
successful fetch (R100), so every unknown-kid bearer request and every
backchannel-logout token hit the JWKS endpoint again during an IdP
outage, with no throttling at all.

Record a short 5s failure cooldown (jwksFailureCooldown) by backdating
the existing lastForceRefresh/lastSignatureRefresh timestamps, so a
failure blocks repeat upstream calls briefly without waiting the full
30s success cooldown before retrying once the IdP recovers.

forceJWKSRefresh previously delegated its within-cooldown branch to
GetJWKS, which itself falls back to a live fetch on a cache miss. That
silently defeated the new failure cooldown (nothing is cached after a
failure), so the branch now reads the local cache directly instead.

Update TestForceJWKSRefresh_FailedFetchDoesNotSetCooldown (review_r100_test.go)
to pin the corrected bound: a failure records a short cooldown that
clears well before the 30s success cooldown, not zero cooldown at all -
the previous assertion (no cooldown recorded) is the exact behavior
this fix corrects.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(logout): rebuild post_logout_redirect_uri from the trusted redirect origin (FIX-07)

handleLogout sent every postLogoutRedirectURI value that does not start
with "http" (including the documented default of "/") to a branch that
set postLogoutRedirectURI = "". BuildLogoutURL then omitted the
parameter entirely, so RP-initiated logout left users stranded on the
IdP logout page under the default config plus an end_session_endpoint.

Capture the origin of redirect_url before session.Clear wipes it. That
value was persisted at authentication-initiate time (R136) and already
accepted by the IdP as this deployment redirect_uri, so its scheme and
host are safe to reuse for post_logout_redirect_uri - unlike the
request Host / X-Forwarded-Host, which the browser controls.

When no trusted origin is available (pre-R136 session, or logout
without a completed login), the parameter is still omitted, matching
the existing safe fallback. An operator-configured absolute URL keeps
taking priority over the derived origin.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(logout): log provider revocation failures and bound the calls (FIX-33)

handleLogout makes two synchronous provider revocation round trips
(access token, refresh token) and discarded both errors with "_ =",
so a failing revocation endpoint left no trace, and each call used
context.Background() with no deadline of its own, so a slow or
unreachable provider could hold the logout redirect open with no
bound of its own.

RevokeTokenWithProvider now derives its request context from a
3-second timeout (revocationRequestTimeout) instead of
context.Background(), and returns a sentinel
ErrRevocationEndpointNotConfigured for the expected "no revocation
endpoint" case. handleLogout logs any other error at error level and
still redirects the browser.

Document the logout revocation and post_logout_redirect_uri behavior
in docs/CONFIGURATION.md.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(auth-flow): stop logging CSRF/nonce on login initiation (FIX-29)

defaultInitiateAuthentication logged "Session saved before redirect.
CSRF: %s, Nonce: %s" and the full provider authorize URL (which also
carries state and nonce as query values) at Debug, despite the R153
commit claiming redaction of state in logs.

Drop the CSRF/nonce values from the first log line. The authorize-URL
log now goes through a new redactAuthorizeURLForLog, which calls the
existing redactCallbackURL (state) and additionally strips nonce and
code_challenge - redactCallbackURL alone was written for the callback
URL and does not know about those two authorize-URL-only values.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(auth-flow): drop Retry-After on the rate-limited callback 429 (FIX-32)

handleCallback sent Retry-After on the 429 for ErrRateLimitExceeded, but
clearOneTimeAuthState has already cleared csrf/nonce/code_verifier and
the authorization code has already been redeemed at the IdP by the
time that response is sent. A client that honors Retry-After and
retries the exact callback URL cannot succeed - it hits "CSRF token
missing in session" instead. Drop the header; the 429 status stays.

Update TestR179_CallbackRateLimitReturns429 (review_r179_regression_test.go)
to assert the corrected contract (no Retry-After) instead of the header
it previously required - the header it pinned is exactly what this fix
removes.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(replay): remove the dead JTI replay write path, make backchannel jti check atomic (FIX-17)

verifyTokenWithOpts wrote every verified JTI into the shared
shardedReplayCache, and its comment (R36) claimed this is "the store
jwt.Verify consults for genuine replay detection". Both were wrong:
jwt.Verify replay branch, the only reader of that cache, only runs
when called with skipReplayCheck=false, and the sole non-test
production caller (VerifyJWTSignatureAndClaims) always passes true.
The write was pure overhead - an exclusive replayCacheMu.Lock (via
initReplayCache) on every cache-miss verification, for a cache nothing
in production reads.

Remove the write-only block and correct the comment. jwt.Verify keeps
its replay branch intact rather than being removed too: ~15 existing
tests across several files call Verify directly with the replay check
enabled and assert on it, and rewriting that test surface is out of
this change scope - see the concern in the final report. A comment
in jwt.go now states the branch does not run on any production path.

Make the backchannel-logout jti replay check (OIDC Back-Channel Logout
1.0 section 2.5) atomic: it was a plain Get followed by a separate Set,
so two logout tokens sharing a jti could both observe "not yet
processed" and both proceed. The check now lives in
checkAndMarkLogoutJTIProcessed, serialized by a package-level mutex.

Correct four existing tests whose assertions pinned the removed
write-only behavior (review_r36_regression_test.go,
security_edge_cases_test.go TestJWTReplayAttack, main_test.go
TestAuthenticationFlowReplayDetection): each now asserts the cache is
NOT written by the production path, and where the test also wanted to
show jwt.Verify replay branch still works when called directly, it
now makes two direct Verify calls instead of relying on the removed
cross-path write.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(replay): correct four more tests pinning the removed FIX-17 write path

TestConcurrentTokenValidation, TestJTIBlacklistBehavior,
TestSessionBasedTokenRevalidation and TestEdgeCasesWithDifferentTokenTypes
(main_test.go) asserted that VerifyToken writes the JTI into the
shared shardedReplayCache, and in two cases relied on that write
happening so a single direct jwt.Verify call would then detect a
replay. FIX-17 removed that write-only path.

Each test now asserts the cache is not written by VerifyToken, and
the two direct-replay-detection cases make two direct Verify calls
(first succeeds and records the JTI itself, second is rejected)
instead of relying on the removed cross-path write.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(jwt): remove the dead replay branch from Verify (FIX-17)

Address verifier review of FIX-17.

Major: the todo's chosen option was to remove the dead jwt.Verify replay
branch, but only its write-only shardedReplayCache.Set call had been
removed; the branch itself and its comment claiming it was "live code"
stayed. Removes the replay-check block and its skipReplayCheck parameter
from JWT.Verify outright, plus the now-unused shardedReplayCache/
replayCache globals and their init/cleanup/stats helpers (jwt.go), and
the startReplayCacheCleanup call that started their background sweep
(main.go). Migrates every non-test and test call site of Verify to the
new two-argument signature, and rewrites or removes the tests whose sole
subject was the removed branch or cache (main_test.go,
security_edge_cases_test.go, review_r179_regression_test.go,
review_r156_regression_test.go, review_r119_test.go, review_r142_test.go
[deleted], review_r126_test.go, review_r36_regression_test.go,
review_r131_test.go, review_r66_lenient_expiry_test.go, audience_test.go,
coverage_boost_final_test.go). New regression coverage:
TestJWTVerify_PerformsNoReplayDetection and
TestVerifyTokenWithOpts_ProductionPathUnaffectedByReplayRemoval
(review_fix17_replay_test.go) pin that Verify performs no jti tracking at
all, and that the production verify path is unaffected.

Minor: verifyOpts.skipReplayMarking is written (bearer_auth.go) but
nothing in verifyTokenWithOpts reads it — the JTI blacklist Set it used
to gate was already removed by an earlier FIX-17 pass without updating
the comments describing it. Rewrites the comments on the field, on
verifyTokenWithOpts, on the blacklist Get, and in bearer_auth.go's
package doc to stop describing a Set that no longer exists. The field
itself is left in place and flagged as dead code needing maintainer
approval to delete, per the dead-code hygiene rule. Also fixes the
repeated "VerifyJWTSignatureAndClaims, via VerifyJWTSignatureAndClaims"
phrase in the R36 correction comment.

Minor: the backchannel-logout jti check (logout.go) uses a process-wide
mutex around Get-then-Set, not an atomic SetIfAbsent, so it is atomic
only within one process, not across Traefik replicas sharing a
Redis-backed sessionInvalidationCache. A real fix needs an atomic
primitive on the cache backend (e.g. Redis SET NX); backends.CacheBackend
has none, and adding one touches many files across internal/cache/
backends owned by unrelated work (FIX-20), which is out of this fix's
scope. Rewrites the backchannelLogoutJTIMu and
checkAndMarkLogoutJTIProcessed comments to state the single-process-only
guarantee explicitly, rather than implying full atomicity.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(logout): correct revocation timing and redirect-uri claims (FIX-33)

Address verifier review of FIX-33.

The Logout Behavior section overstated and misstated logout timing and
redirect behavior. Item 2 said the 3-second revocation timeout means a
slow provider cannot delay the redirect, but the two revocation calls
(access and refresh token) run one after the other, so together they can
delay it by up to about 6 seconds. Items 3-4 gave 'a logout request with
no completed login' as the example of a missing redirect origin, but
that case has no ID token and never reaches the oidcEndSessionURL branch
at all; the real missing-origin case is a session created before R136
started recording the redirect origin. The section also omitted that an
absolute postLogoutRedirectURI is sent unchanged. Rewrites items 2-4 to
state the actual timing and the three real conditions for the
end-session redirect, its redirect_uri handling, and when the parameter
is omitted. Removes the semicolon and the em dash per
simplified-technical-english.md.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(logout): make the FIX-07 redirect-origin regression table-driven (FIX-07)

Address verifier review of FIX-07.

The regression test set postLogoutRedirectURI to "", which helpers.go
sends through a separate case postLogoutRedirectURI == "" branch, not
the default: branch production actually runs (main.go turns an unset
config into the documented default '/', which goes through default:).
The old test's comment called "" the documented default, which it is
not. Deleting the trustedOrigin rebuild in default: would have kept the
old test green.

Makes the test table-driven with three cases: the production default
'/', a relative '/bye', and the pre-existing '' case, all wanting
https://app.example.com/ or https://app.example.com/bye. Verified with a
scratch mutation of the default: branch (trustedOrigin rebuild removed,
reverted before this commit): the old single-case '' test still passed,
the new '/' and '/bye' subtests failed as expected. Corrects the comment
that called '' the documented default.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(pool): remove racy nil pre-check, move test reset helper (FIX-39)

GetTransportPool read globalTransportPool outside transportPoolOnce,
racing the write inside Once.Do when two goroutines called it for the
first time concurrently. Run the whole body inside Once.Do instead, so
every caller only observes the pointer after Once establishes
happens-before.

Move resetGlobalTransportPoolForTest into a new export_test.go file so
the test-only helper no longer compiles into the plugin package that
imports internal/pool. Update TestCreateHTTPClient_Fallback to exhaust
the real singleton in place (mutate its fields) instead of swapping in
a hand-built *TransportPool, since Once.Do now always builds its own
pool after a reset and would overwrite a manually assigned one.

Regression test TestGetTransportPool_ConcurrentFirstCall pins the race:
it fails under -race at head (WARNING: DATA RACE between the write in
GetTransportPool.func1 and the read at the removed pre-check) and
passes after the fix.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(config): add perSourceLoginRateLimit, clientAssertionKeyPath to configToMap (FIX-40)

configToMap is the single field/redaction list MarshalJSON and
MarshalYAML share (R150), meant to stop the marshalled config from
silently dropping fields. It still dropped two json-tagged Config
fields: perSourceLoginRateLimit (added in the same changeset) and
clientAssertionKeyPath. Neither is a secret, so this reintroduced the
exact drift R150 set out to eliminate.

Add both fields to configToMap. clientAssertionKeyPath is a filesystem
path, not the key content, so it needs no redaction (the content field
clientAssertionPrivateKey is already REDACTED).

TestConfigToMap_IncludesAllJSONFields reflects over every json-tagged
Config field and asserts it is a configToMap key. It fails at head
with exactly the two missing fields and passes after the fix.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(makefile): run make test under -race (FIX-21)

Several regression pins (R44 TestSessionDataRedirectCountConcurrency,
R111 TestSessionAccessors_ConcurrentAccess, R77
TestSessionPool_ReturnToPool_ExactlyOnce) only fail when the old bug
they pin is reintroduced AND the race detector is on. make test ran
plain go test with no -race, so a regression in any of them would ship
silently. docs/TESTING.md already says to always run with -race.

Add -race to the Makefile test target.

Verified this session: reverting the R77 CAS in returnToPoolSafely
(and the inUse field back to plain bool, matching the pre-R77 shape)
back to a temporary local build, `go test -run
TestSessionPool_ReturnToPool_ExactlyOnce` passes without -race and
fails with -race:

    WARNING: DATA RACE
    Read at ... session.go:1784 (returnToPoolSafely)
    Previous write at ... session.go:1947 (Reset, called from the
    second concurrent returnToPoolSafely)
    --- FAIL: TestSessionPool_ReturnToPool_ExactlyOnce
        testing.go:1865: race detected during execution of test

The revert was local-only and is not part of this commit. Also
confirmed the shared CI workflow (go-pr.yaml@main in
lukaszraczylo/shared-actions, used by .github/workflows/pr.yaml) already
runs `go test -race -coverprofile=... -covermode=atomic ./...`, so CI
was not the gap.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(session): pin R104 no-reject-on-decompressed via the real read path (FIX-08)

TestValidateChunkingEfficiency_NoRejectOnDecompressed called
cm.validateChunkingEfficiency(big, config) as a bare statement and
asserted nothing. Go lets a statement call drop a return value, so the
test compiled and passed both before and after the R104 fix -
validateChunkingEfficiency changed from returning an error to
returning nothing in the same changeset, and a bare call compiles
either way. The test pinned nothing.

Rewrite it to drive the actual read path: build a JWT-shaped fixture
whose decompressed length exceeds MaxChunks*MaxChunkSize, gzip+base64
it the way a stored compressed cookie is shaped, and call
ChunkManager.GetToken(compressed=true, ...) - the same entrypoint
session.go uses. Assert the token reassembles unchanged with no error.

Verified this session with a temporary, uncommitted local revert of
validateChunkingEfficiency and its validateToken call site to the
pre-R104 base f728f61 shape (hard error on expectedChunks >
MaxChunks): the rewritten test fails there -

    review_r104_test.go:350: GetToken rejected a large
    legitimately-compressed token: access token would require 51
    chunks (max: 50)
    --- FAIL: TestValidateChunkingEfficiency_NoRejectOnDecompressed

and passes again once session_chunk_manager.go is restored to head.
The revert was local-only and is not part of this commit.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(ratelimit): key PerSourceLoginRateLimit on RemoteAddr, not XFF (FIX-11)

sourceIP() preferred the first X-Forwarded-For value, and
isInternalSource then trusted that attacker-controlled value as the
basis for internal classification. An external attacker sending
X-Forwarded-For: 127.0.0.1 (or any RFC 1918 address) was classified
internal and never throttled, making PerSourceLoginRateLimit a no-op
against exactly the attacker it exists to stop. Rotating arbitrary XFF
values also let an attacker dodge the per-source counter and grow the
entries map, or spoof a victim IP to exhaust that IPs budget.

clientIPForBearer (bearer_auth.go) already deliberately ignores XFF
for the same reason - a second mechanism doing the opposite of the
solved one.

Derive sourceIP from RemoteAddr only. No new config: the feature is
opt-in (default 0/off) and this restores the trust boundary it should
have shipped with.

Two existing tests relied on the old XFF-as-source behavior to
simulate distinct/internal sources and are updated to use RemoteAddr
instead, matching the corrected contract: TestR185_InternalSourceNeverThrottled
(review_r185_regression_test.go) and
TestR185_PerSourceLimiterSweepEvictsIdle (review_r213_test.go).

New regression tests (per_source_ratelimit_test.go):
TestPerSourceRateLimit_XFFSpoofDoesNotBypassThrottle drives the full
ServeHTTP callback path with an external RemoteAddr and a spoofed
X-Forwarded-For: 127.0.0.1, and TestSourceIP_IgnoresXForwardedFor pins
sourceIP() directly. Both fail at head:

    per_source_ratelimit_test.go:56: external source spoofing
    X-Forwarded-For: 127.0.0.1 was never throttled
    per_source_ratelimit_test.go:70: sourceIP = "127.0.0.1", want
    RemoteAddr-derived "203.0.113.7"

and pass after the fix.

docs/CONFIGURATION.md and README.md perSourceLoginRateLimit rows now
state the RemoteAddr-only keying.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(http): stop sharing a cookie jar across the pooled token client (FIX-12)

R70 made CreatePooledHTTPClient honor config.UseCookieJar.
TokenHTTPClientConfig and OIDCProviderHTTPClientConfig both set
UseCookieJar: true, and main.go builds one pooled tokenHTTPClient per
plugin instance from TokenHTTPClientConfig, shared by every users
token/refresh exchange. An IdP Set-Cookie on user As exchange response
was stored in that one jar and replayed on user Bs next token request
to the same host - cross-user state confusion at the IdP, with no
config change on upgrade.

Set UseCookieJar to false (the DefaultHTTPClientConfig default) in
both config constructors. Token/refresh calls are stateless
back-channel requests; the nil-client fallback in exchangeTokens
(helpers.go) already builds its own fresh jar per call, which stays
correct and is untouched. CreatePooledHTTPClients own UseCookieJar
honoring (http_client_pool.go) is unchanged and still covers any
future caller that legitimately needs a jar.

TestPooledTokenClient_DoesNotShareCookieJarAcrossRequests
(http_client_jar_test.go) drives CreatePooledHTTPClient(TokenHTTPClientConfig())
against a test IdP that sets a cookie on request 1 and asserts request
2 does not carry it. It fails at head:

    http_client_jar_test.go:31: request 2 carried leaked cookie
    idp_sess=alice from an earlier request

and passes after the fix. Two existing assertions that expected the
old (leaky) behavior are updated to match the corrected contract:
TestOIDCProviderHTTPClientConfigUnit and TestCreateTokenClientUnit
(http_client_factory_unit_test.go).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test: add newTestOIDC builder, move stubIntrospectionCache, migrate logout round files (FIX-41)

136 added root test files (71 hand-building TraefikOidc literals, 112
in total) make any change to TraefikOidc required fields a many-file
patch. Round files also depend on each others locally declared
helpers: review_r149_test.go used stubIntrospectionCache, declared in
review_r126_test.go, so deleting or renaming either file would break
the other silently at compile time.

Add newTestOIDC(t, opts...) in a new shared newtestoidc_test.go: a
builder with the common ServeHTTP-ready defaults (next handler, error
logger, closed initComplete, a real session manager, both startup
barriers past init, a plausible issuer/callback/client), customized
per test via functional options that set unexported fields directly
(same-package test file).

Move stubIntrospectionCache from review_r126_test.go into the same
shared file. review_r143_test.go and review_r149_test.go, which also
use it, need no change - Go resolves package-level identifiers by
package, not file, so moving it to a shared file removes the
round-to-round coupling without touching either caller.

Migrate the logout round files onto the builder (5 tests):
review_r55_logout_blacklist_test.go, review_r73_test.go, and
review_r87_test.go.

Verified this session that migration did not defang any of these
pins: for 3 of the 5, a temporary uncommitted local revert of the
exact behavior each test regresses made the migrated test fail, then
was restored. All 5 migrated tests, and the full root package (go
test -race), pass at head with the reverts removed.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(http): correct stale cookie-jar comment on CreatePooledHTTPClient (FIX-12)

Reword the comment above the UseCookieJar branch. It described the
jar-less pooled token/OIDC clients as a bug to fix, contradicting the
FIX-12 comments already in http_client_factory.go and inviting a
reintroduction of the cross-user jar R70 introduced. State instead
that TokenHTTPClientConfig and OIDCProviderHTTPClientConfig
deliberately leave UseCookieJar false because a pooled client is
shared across users.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(ratelimit): document the shared-proxy-IP tradeoff for perSourceLoginRateLimit

perSourceLoginRateLimit keys solely on RemoteAddr (per_source_ratelimit.go).
Behind a load balancer or CDN that is the proxy address, not the real
client: a private proxy address is exempt from throttling entirely, and
a public proxy address puts every client into one shared bucket. State
this in both docs rows, matching the tradeoff already documented in
clientIPForBearer (bearer_auth.go).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test: eliminate remaining cross-round test-helper references (FIX-41)

The prior FIX-41 pass moved only stubIntrospectionCache; 14 references
into 10 other helpers survived, 3 of them into the migrated logout
round files (review_r172_regression_test.go used newR87LogoutHarness
and r87BaseClaims from review_r87_test.go; review_r103_test.go used
mustTemplate from review_r73_test.go). Deleting or renaming any of
those round files would still have broken an unrelated file.

Move every cross-referenced helper into a shared _test.go file, by
topic: jwt_test_helpers_test.go (writeJWKS, signRSAJWTForTest,
makeJWTForTest), cache_test_helpers_test.go (NewMemoryBackendForTest,
mapCache, serializingCache), config_test_helpers_test.go
(r134ValidConfig), plugin_test_helpers_test.go (newR154TestPlugin),
logout_test_helpers_test.go (r87LogoutHarness, newR87LogoutHarness,
r87BaseClaims), and mustTemplate into the existing newtestoidc_test.go.
A go/ast analyzer built for this fix (File.Unresolved checked against
top-level decls of every other review_rNN*_test.go file) now reports 0
cross-round references, down from 20.

Also migrate TestBackchannelLogout_RejectsReplayedJTI
(review_r73_test.go) onto the newTestOIDC builder, the one migration
the prior pass missed among the three logout round files. Verified the
migrated test still catches the regression: with the jti-replay check
in logout.go temporarily disabled (reverted before this commit), it
fails with "review_r73_test.go:109: replayed logout token should be
rejected (400), got 200".

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(client-assertion): pin and document the RSA<2048 private_key_jwt rejection (FIX-42)

validateAlgKeyMatch already rejects an RS*/PS* private_key_jwt signing
key under 2048 bits (RFC 7518 3.3), added by 8640451 with no commit
mention and no CHANGELOG entry. Keep the rejection as-is.

Wrap the error with a new ErrRSAKeyTooSmall sentinel so callers can
match it with errors.Is instead of parsing the message, add a pin
test that generates a 1024-bit and a 2048-bit key and asserts the
reject/accept boundary, and document the minimum in
docs/CONFIGURATION.md and CHANGELOG.md.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(main): name and document dropped http endpoints under https providers (FIX-26)

validateDiscoveredEndpoint already refuses a discovered http:// endpoint
under an https providerURL (R146). Keep that pin; do not add an
opt-out flag.

Wrap the rejection in a named ErrDiscoveredEndpointSchemeDowngrade
sentinel and have updateMetadataEndpoints sanitize log an extra
SECURITY-tagged line, naming the endpoint, the dropped URL, and the
absence of an override, whenever the dropped endpoint is token,
jwks_uri, or authorization — the three a login cannot function
without. The generic per-endpoint log line stays unchanged.

Add a regression test pinning the new log line and a negative test
confirming accepted https endpoints stay silent. Document the
behaviour in docs/CONFIGURATION.md, README.md, and CHANGELOG.md.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(changelog): record the R96/R102/R105/R126 auth relaxations (FIX-25)

security_edge_cases_test.go:459 (+bearer_auth_test.go:225, custom_claims_test.go:158,
main_test.go:2325) pin four claim-validation relaxations that shipped
in 8640451 with no commit-body or CHANGELOG mention: optional iat
(R126), a stringified numeric bearer sub (R102), a malformed
groups/roles claim treated as empty (R96), and stringified numeric
items inside a groups/roles array (R105).

Each relaxation is intentional, matches a production change, and
already has a passing regression test (re-run this session to
confirm: TestMissingClaims/Missing_IssuedAt_is_optional,
TestResolveBearerIdentifier, TestCustomClaimNames_MalformedRoleClaim,
TestCustomClaimNames_MalformedGroupClaim,
TestCustomClaimNames_NonStringInRoleArray,
TestCustomClaimNames_NonStringInGroupArray). Keep all four as-is; no
code change. Record each in CHANGELOG.md so a reviewer of the
squashed commit can see the intent.

Also record the blacklist Redis namespace move (token: -> blacklist:,
FIX-16, implemented elsewhere) and its one-release legacy read, since
CHANGELOG.md is otherwise silent on it too.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(main): restrict SECURITY scheme-downgrade log to no-override endpoints (FIX-26)

sanitize logged the SECURITY line for every dropped endpoint, not only
jwks_uri, authorization and token as docs/CHANGELOG/README say. Revocation,
end_session and introspection have a config override (revocationURL,
oidcEndSessionURL, introspectionURL) that replaces the endpoint right after
sanitize runs, so the "no override; requests will fail" wording was false
for those three.

Add discoveredEndpointHasNoOverride and named constants for the three
endpoints with no config source, and gate the SECURITY line on both the
scheme-downgrade error and endpoint name. Add negative tests pinning that
end_session/revocation/introspection/registration keep only the generic
line, and that a config override still replaces a dropped endpoint. Add one
sentence to docs/CONFIGURATION.md naming which endpoints have an override.
Correct the fix26 test file header comment: the pre-existing ERROR line
already named the scheme-downgrade reason; the new SECURITY line only adds
a distinct tag and the no-override statement.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(changelog): scope the iat relaxation, drop the unbuilt FIX-16 bullet (FIX-25)

The iat bullet overstated the R126 relaxation: it is optional in
jwt.Verify only. Bearer-token auth still rejects a token with no iat
(enforceIatAge, "missing iat claim"), because maxTokenAgeSeconds always
applies and 0 falls back to a 24h default. The lenient-audience
accessTokenUnexpired path also still requires iat on this branch. State
that scope explicitly instead of implying the check is gone everywhere.

Reword the heading to match bullet 4: a numeric groups/roles array item
was silently dropped before R105, not rejected, so "previously-rejected"
alone mis-described it.

Remove the Blacklist Redis-namespace-move bullet: it describes
universal_cache.go changes from commit 4eb876b on fix/d1-universal-cache,
which this branch does not contain. Re-add it when that branch merges.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(yaegi): replace errors.As on interpreted *HTTPError in RetryExecutor

errors.As(err, &target) panics under yaegi v0.16.1 whenever the target
pointed-to type is interpreted. *HTTPError is declared in this plugin, so
RetryExecutor.isRetryableError panicked on the default-on token-exchange/
refresh retry path regardless of the concrete error type reaching it.

Add asHTTPError, a manual errors.Unwrap walk plus type assertions (both
yaegi-safe), and use it in place of both errors.As calls in
isRetryableError. Native classification stays unchanged: the walk mirrors
errors.As exactly for the fmt.Errorf(%w) chains callers actually wrap.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(yaegi): replace errors.As on interpreted HTTPError/OIDCError in internal/recovery

Same yaegi v0.16.1 hazard as error_recovery.go's RetryExecutor: this
package's own *HTTPError and *OIDCError types are interpreted whenever
the traefikoidc plugin loads under yaegi (it imports internal/recovery
transitively through internal/utils/logger_wrapper.go), so
RetryExecutor.isRetryableError's two errors.As calls here panic too.

Add asHTTPError and asOIDCError, the same manual errors.Unwrap-walk
pattern used in the top-level package, and use them in place of
errors.As. Native classification is unchanged (TestR175 stays green).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(yaegi): drop errors.As from introspection error classification

token_validation_rs.go classified validateOpaqueToken's error with
errors.As(err, &httpErr): *HTTPError is interpreted under yaegi v0.16.1,
so this panicked on every opaque-token session-path classification.

A plain type assertion is yaegi-safe but only if the value arrives
unwrapped, and an interpreted *HTTPError wrapped with fmt.Errorf(%w)
cannot be recovered by a manual errors.Unwrap walk under yaegi either
(verified this session against the pinned interpreter). So instead of
adding an unwrap-walk helper here, fix the producer:
validateOpaqueToken (token_introspection.go) now returns
introspectToken's *HTTPError unwrapped instead of wrapping it with
"token introspection failed: %w", matching the existing yaegi-safe
pattern (isTerminalClientError, isNeverSentError). The call site
switches to a plain err.(*HTTPError) assertion.

Adds native regression coverage for the unwrapped return and for the
5xx classification case (401/429 were already covered).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(yaegi): add NEW-01 regression checks to yaegicheck

Extend cmd/yaegicheck/main.go, the program make yaegi-validate runs
under the interpreter, with checks that drive every site fixed by
NEW-01: RetryExecutor.ExecuteWithContext (top-level package) with an
HTTPError 500 (retried), an HTTPError 400 (not retried), and a plain
error (no panic); the same pair for internal/recovery's RetryExecutor,
plus its OIDCError retryable/terminal classification; and a full
plugin instance driving RFC 7662 introspection end to end through the
bearer path for a 4xx and a 5xx response.

Confirmed these checks panic (errors.As at error_recovery.go:723) when
run against the pre-fix commit, and pass on the fixed worktree.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* refactor: remove symbols left unused by the review fixes

staticcheck (U1000) flagged defaultBlacklistDuration in cache_manager.go and isLastInstanceNow in singleton_resources.go. The FIX-35 lifecycle change routes every last-instance stop through stopIfLastInstance, and the blacklist TTL no longer reads the constant. Comments that named the removed function now describe the check they compare against.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(yaegi): fold the SSE flush check into yaegicheck

Add checkSSEFlushReachesNext to cmd/yaegicheck. It sends an SSE request through the excluded-URL bypass under yaegi and asserts that http.NewResponseController(w).Flush() succeeds on the writer next receives (FIX-06). Remove cmd/yaegiflushcheck, a nested module with its own go.mod (go 1.27.1) and a yaegi dependency that ran the same check. make yaegi-validate now covers it.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(changelog): record the blacklist namespace move, correct the iat scope

Add the FIX-16 entry: the blacklist cache writes under the blacklist: Redis prefix, and for one release it reads a legacy token: entry only when the stored value is boolean true. Correct the iat bullet: accessTokenUnexpired now calls verifyTimeClaims, so the lenient-audience path treats iat as optional, the same as jwt.Verify (FIX-27).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(middleware): pin FIX-02 default-deny for genuine OPTIONS preflight

Regression test for the maintainer decision on FIX-02: the released
behavior required auth for every OPTIONS request by default. Confirms
red on base code -- shouldBypassAuth currently bypasses any genuine
CORS preflight (Origin + Access-Control-Request-Method) unconditionally,
so this test currently fails with the backend reached (status=204).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* feat(settings): add AllowUnauthenticatedPreflight config option

New Config.AllowUnauthenticatedPreflight bool (json tag
allowUnauthenticatedPreflight, default false), wired through to
TraefikOidc.allowUnauthenticatedPreflight (types.go, main.go) and into
configToMap (config_marshalling.go) so it round-trips through
MarshalJSON/MarshalYAML like every other Config field. Naming and
omitempty match the sibling AllowPrivateIPAddresses option. No
behavior change yet -- middleware.go still needs to read the field
(next commit).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(middleware): gate OPTIONS bypass behind AllowUnauthenticatedPreflight

Maintainer decision for FIX-02: restore the released behavior where
every OPTIONS request needs authentication by default. shouldBypassAuth
now only treats a genuine CORS preflight (Origin +
Access-Control-Request-Method) as an auth bypass when
t.allowUnauthenticatedPreflight is true; with the flag at its default
(false), OPTIONS goes through the normal auth pipeline like any other
method. The optionsPreflightWriter body-discard hardening (forged
preflights cannot read a protected body even when the flag is on)
still applies unchanged inside the bypassReasonOptions case, since
shouldBypassAuth only returns that reason when the flag permits it.

Updates the FIX-02 tests that assumed the bypass was unconditionally
on (fix02_options_bypass_test.go, review_r124_test.go
TestShouldBypassAuth_PassesOptions) to set
allowUnauthenticatedPreflight: true, so they keep exercising the
Origin+Access-Control-Request-Method gate rather than being short-
circuited by the new flag gate. Adds
fix02b_allow_unauthenticated_preflight_test.go pinning the maintainer
decision directly: default config requires auth for a genuine
preflight (red on prior commit); with the flag on, a genuine preflight
still bypasses with its body discarded; with the flag on, a bare
OPTIONS still requires auth.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs: document allowUnauthenticatedPreflight option

Adds the new Config.AllowUnauthenticatedPreflight option to the
docs/CONFIGURATION.md security-options table and the README.md option
table, next to its sibling allowPrivateIPAddresses. .traefik.yml is not
touched: it lists only complex opt-in feature blocks (bearer-auth,
Redis) as commented examples, not the plain security-relaxing bools
like allowPrivateIPAddresses -- allowUnauthenticatedPreflight follows
that same precedent.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* style(test): fix wrong test name in FIX-02 cross-reference comment

TestShouldBypassAuth_PassesOptions referenced a
TestShouldBypassAuth_DefaultDoesNotBypassOptions that does not exist;
point it at the real default-off regression test,
TestServeHTTP_DefaultConfigGenuinePreflightRequiresAuth in
fix02b_allow_unauthenticated_preflight_test.go.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(refresh): cancel refresh context on Shutdown so it returns promptly (FIX-36)

Derive each refresh operation's timeout context in executeRefreshAsync from
a coordinator-owned context (rc.ctx) instead of context.WithTimeout(
context.Background(), RefreshTimeout). Shutdown now cancels rc.ctx before
wg.Wait(), so it no longer blocks for up to RefreshTimeout (or the
refreshFunc's own natural completion) per in-flight refresh. A waiter
blocked in CoordinateRefresh on an aborted operation gets an error, not a
hang. RefreshTimeout still caps a refresh that is not aborted by Shutdown.

The refreshFunc call itself runs in an untracked inner goroutine
(executeRefreshAsync) that cannot be aborted given its
func() (*TokenResponse, error) signature; it keeps running past Shutdown
until it returns naturally (in production, until its own HTTP client
timeout). This is documented in code comments on Shutdown and
executeRefreshAsync.

Corrects three comments that described the old contract: the goroutine-
launch comment in CoordinateRefresh, the timeout-context comment in
executeRefreshAsync, and the Shutdown comment — all previously said
Shutdown deliberately does not cancel and must wait for a genuine in-flight
refresh to finish, which is now false.

Rewrites TestRefreshCoordinatorShutdownWaitsForInflight (review_r63) and
TestRefreshCoordinator_ShutdownWaitsForInFlight (review_r154), which pinned
the old "Shutdown blocks until the refresh finishes" contract this commit
intentionally reverses; they now assert the prompt-return contract instead.

Adds TestFix36_ShutdownReturnsPromptlyDuringInFlightRefresh: starts a
refresh whose refreshFunc blocks 3s, calls Shutdown, and asserts Shutdown
returns in under 1s and the waiter gets an error. Fails on pre-fix code at
refresh_coordinator_test.go:871 ("Shutdown did not return within 1s while a
refresh was in flight"); green under go test -race.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(refresh): pin wg-tracking of the aborted refresh goroutine (FIX-36 review)

TestRefreshCoordinator_ShutdownWaitsForInFlight (review_r154) and
TestRefreshCoordinatorShutdownReleasesWaiterOnInflight (review_r63) only
checked that Shutdown returns promptly and the waiter gets an error. Both
checks also pass when the executeRefreshAsync goroutine is not tracked by
rc.wg, so an untracked-goroutine regression would go unnoticed, and the
R154 test comment claimed wg coverage the test did not assert.

Add an assertion on rc.circuitBreaker.failures right after Shutdown
returns: executeRefreshAsync calls RecordFailure() before it returns, and
the goroutine that calls it is (correctly) covered by wg.Wait(), so the
count must already be 1 by the time Shutdown, and therefore wg.Wait,
returns.

Verified with a local mutation (not committed): replacing
`defer rc.wg.Done()` inside the spawned goroutine with an immediate
`rc.wg.Done()` before `go func(){...}()` made the new assertion fail
20/20 runs for the R154 test and 12/20 for the R63 test under
-race -count=20; both pass 20/20 on the real (tracked) code.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(refresh): skip refreshFunc when rc.ctx is already canceled

executeRefreshAsync spawns an inner goroutine that calls refreshFunc
unconditionally, even when rc.ctx (and therefore refreshCtx) is already
canceled before the goroutine starts. The outer select then always takes
the refreshCtx.Done() branch and discards whatever refreshFunc returned,
but refreshFunc is the IdP refresh-token grant: calling it anyway still
spends a request against a (possibly rotating, one-time-use) refresh
token whose result nobody reads.

Check rc.ctx.Err() as the first statement in the inner goroutine and
return without calling refreshFunc when it is already canceled.

Adds TestFix36_ExecuteRefreshAsyncSkipsRefreshFuncWhenAlreadyCanceled:
cancels rc.ctx directly (isolating this from the stopChan-reject path),
then asserts refreshFunc is never called and the waiter gets an error.
Fails on pre-fix code at refresh_coordinator_test.go:926 ("refreshFunc
must not be called when rc.ctx is already canceled before the refresh
starts"); green under go test -race -count=20.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(refresh): correct stale nolint comment on the tracked refresh goroutine

The nolint reason still said the refresh "intentionally uses a background
context", describing the pre-FIX-36 behaviour. Since FIX-36,
executeRefreshAsync derives its timeout context from rc.ctx (canceled by
Shutdown), capped by RefreshTimeout, not context.Background().

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* feat(cache/redis): add atomic SetNX check-and-set to RedisBackend (FIX-17)

RedisBackend gets SetNX(ctx, key, value, ttl) (bool, error): one Redis
SET key value NX PX <ttl-ms> command instead of a separate GET then
SET, so two callers racing the same key can never both observe
"absent". Backs the UniversalCache.SetIfAbsent primitive the next
commit adds, which the backchannel-logout jti replay check
(logout.go) needs to be atomic across Traefik replicas, not just
within one process (FIX-17, R36 correction).

A nil bulk-string reply (NX condition failed, key already exists) is
reported as (false, nil), not an error: it is a valid protocol
outcome, not a backend failure, so executeWithRetry must not retry it
or surface it as err.

Regression test (miniredis-backed): a second SetNX on an already-set
key does not overwrite the first value or its TTL, and exactly one of
20 concurrent SetNX calls on the same key wins under -race.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* feat(cache): add UniversalCache.SetIfAbsent atomic check-and-set (FIX-17)

SetIfAbsent(key, value, ttl) (bool, error) stores value only if key is
not already present, replacing the TOCTOU-prone separate Get then Set
with one atomic operation (FIX-17, R36 correction).

With no distributed backend, the presence check and the insert happen
inside a single c.mu critical section (setLocalLocked, extracted from
setLocal so SetIfAbsent does not have to re-enter the lock setLocal
already holds). With a backend that implements the optional
backendSetNXer interface (RedisBackend.SetNX, previous commit),
that call alone decides the outcome, so the check is atomic across
every replica sharing that backend too. CacheBackend itself is not
widened to require SetNX: every other implementer and test double
would need a method only this caller needs, so SetIfAbsent reaches it
through a type assertion instead. A successful backend claim is then
mirrored into the local cache as a best-effort read-through.

Exposed to callers as AtomicSetIfAbsentCache (types.go), an optional
capability a CacheInterface value can satisfy, for the same reason:
CacheInterface itself is not widened, since most of its many test
doubles across the suite have no need for the atomic primitive.
CacheInterfaceWrapper (the concrete type sessionInvalidationCache
actually is at runtime) implements it by delegating to
UniversalCache.SetIfAbsent.

Regression tests: SetIfAbsent single-threaded claim/no-overwrite
semantics; exactly one of 20 concurrent same-key calls wins, both with
no backend and with a real Redis backend (miniredis); and
CacheInterfaceWrapper satisfies AtomicSetIfAbsentCache. All green
under -race.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(logout): make backchannel-logout jti check atomic via SetIfAbsent (FIX-17)

checkAndMarkLogoutJTIProcessed now type-asserts sessionInvalidationCache
to AtomicSetIfAbsentCache and, when it is available, uses SetIfAbsent
as the sole check: no separate Get then Set, and no
backchannelLogoutJTIMu. CacheInterfaceWrapper (what
sessionInvalidationCache actually is at runtime) satisfies the
interface, so this is the path production traffic takes, and it is
atomic across Traefik replicas sharing a Redis-backed cache, not just
within one process (FIX-17, R36 correction: the prior commit on this
line only made the check-and-set atomic process-locally).

backchannelLogoutJTIMu is kept as a fallback for a CacheInterface
implementation that does not provide the atomic primitive, guarding
only that case now. A SetIfAbsent backend error falls through to the
same fallback rather than rejecting an otherwise-valid logout token
outright on a transient cache failure.

Regression test: 20 concurrent backchannel-logout submissions of the
same valid logout token, through the production validateLogoutToken
path, must yield exactly one acceptance AND must reach it through
SetIfAbsent alone (asserted via call counts on an instrumented cache
double) rather than the legacy Get/Set fallback, so the test would
catch a regression to the old path even where the outcome happens to
still be correct under backchannelLogoutJTIMu. Green under
-race -count=5.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache/resilience): forward SetNX through circuit-breaker and health-check wrappers

Round-2 verifier finding (major): UniversalCache.SetIfAbsent reaches a
Redis backend through the optional backendSetNXer type assertion, but
neither CircuitBreakerBackend nor HealthCheckBackend implemented SetNX,
so wrapping Redis with either (docs/REDIS.md and the example configs
recommend both true in production) made the assertion fail and every
call silently fall back to the process-local-only path. Two replicas
sharing the same wrapped Redis backend both claimed the backchannel-
logout jti and Redis never saw the key.

Add SetNX passthrough to both wrappers: forward to the wrapped backend
when it implements SetNX (through the same circuit-breaker/health
accounting as every other operation), and report the new
backends.ErrSetNXUnsupported sentinel otherwise.

Pin with three regression tests driving two UniversalCache instances
(simulated replicas) over one miniredis-backed RedisBackend wrapped by
NewCircuitBreakerBackend, NewHealthCheckBackend, and the production
wiring order HealthCheck(CircuitBreaker(raw)). All three fail on
b433f42 (second replica also claims; redis keys=[]) and pass here.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): reject SetIfAbsent when backend lacks SetNX, no silent local

Round-2 verifier finding (major, completes the previous commit):
UniversalCache.SetIfAbsent fell back to the local-only path for ANY
backend that failed the backendSetNXer type assertion, not only the
CircuitBreakerBackend/HealthCheckBackend case the previous commit
fixes at the source. Belt-and-suspenders: a distributed backend
attached to the cache now must expose SetNX (directly or through a
wrapper) or SetIfAbsent errors loudly with the new
errSetIfAbsentUnsupported sentinel, instead of quietly giving each
replica a process-local-only guarantee it never asked for.
checkAndMarkLogoutJTIProcessed already falls through to its
backchannelLogoutJTIMu-guarded Get+Set on any SetIfAbsent error, so no
logout.go behavior change is needed there beyond correcting its doc
comments to describe the corrected contract.

Pin with a fake backend that deliberately has no SetNX: two
UniversalCache instances (simulated replicas) sharing it must both
get the same sentinel error and neither may silently claim locally.
Fails on HEAD before this commit (no error returned); passes here.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(cache): pin SetIfAbsent cross-replica atomicity with two instances

Round-2 verifier finding (minor): the existing Redis-backed SetIfAbsent
test drives 20 concurrent calls through a SINGLE UniversalCache
instance, so its own c.mu already serializes them to exactly one
winner even when the c.backend.(backendSetNXer) branch is mutated
dead — the test cannot tell "one process, one mutex" from "many
replicas, one Redis". Add a test using two separate UniversalCache
instances (simulated replicas) sharing one miniredis-backed
RedisBackend: the second instance must be rejected AND the key must
be present in the shared miniredis, which two independent local maps
cannot produce.

Verified this test (and the pre-existing one) both fail under the
verifiers mutation (backendSetNXer branch forced dead) once the
previous two commits are in place: SetIfAbsent now errors instead of
silently using the local-only path, so the mutation surfaces as
"unexpected error" rather than a quiet pass.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache/redis): make SetNX retry-safe when a reply is lost

Round-2 verifier finding (minor): SetNX ran SET key value NX PX inside
executeWithRetry, which blindly retries the whole operation on a
"connection"/"timeout"/"EOF" error by re-issuing the closure. That is
fine for Set (SETEX/PSETEX overwrite unconditionally, so a retry after
a lost reply just repeats the same write) but wrong for SET NX: if the
first SET NX reached Redis and applied, and only the reply was lost,
the retried SET NX sees the caller own write and reports
(false, nil) — "already claimed" — for what was actually a
first-ever claim. checkAndMarkLogoutJTIProcessed then rejected a
legitimate logout token (and every IdP redelivery) as a replay.

Add RedisConn.doTracked, reporting whether the command was already
written when it failed; Do becomes a thin wrapper over it. Give SetNX
its own retry loop: retry a failed connection acquisition (nothing
sent yet, safe), but once doTracked reports the command reached the
wire, stop and return the new backends.ErrSetNXAmbiguous sentinel
instead of guessing. checkAndMarkLogoutJTIProcessed accepts that
specific error outright rather than falling through to the
Get+Set fallback, which would see the same ambiguous write and
misreport the token as a replay.

Pin with a TCP proxy that forwards a SET NX to a real miniredis
instance but swallows its reply: RedisBackend.SetNX must report
(false, ErrSetNXAmbiguous), and the key must actually exist in
miniredis (proving the old (false, nil) was a false negative on a
first-ever claim). Also pin checkAndMarkLogoutJTIProcessed accepting
an ambiguous SetIfAbsent result without consulting Get. Both fail on
the pre-fix code (redis.go:161 gets claimed=false err=nil;
logout_test.go:89 gets a spurious replay error) and pass here.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(changelog): record the allowUnauthenticatedPreflight option (FIX-02)

OPTIONS requests need authentication by default again. The new allowUnauthenticatedPreflight option lets a genuine CORS preflight bypass authentication, with its response body discarded.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(yaegi): pin SetIfAbsent claim semantics under yaegi (FIX-17)

Add checkSetIfAbsentUnderYaegi to cmd/yaegicheck. It claims one key twice through UniversalCache.SetIfAbsent in local-only mode and through a backend that implements SetNX, and expects exactly one winner each time. A backend without SetNX must return an error instead of a local claim. This covers the optional-interface assertion in SetIfAbsent under the interpreter.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache/redis): check sent before ctx.Err() in SetNX

RedisBackend.SetNX checked ctx.Err() before the sent check, so a lost
SET NX reply under the real 500ms SetIfAbsent context almost always
surfaced as context.DeadlineExceeded instead of ErrSetNXAmbiguous.
checkAndMarkLogoutJTIProcessed only special-cases the ambiguous
sentinel, so it fell through to the Get+Set fallback and rejected a
first-ever, never-before-seen logout token as a replay.

Move the sent check ahead of ctx.Err() so ErrSetNXAmbiguous is
reported whenever the command reached the wire, regardless of ctx
state, and keep it returned unwrapped for == comparison under yaegi.

Add a regression test that drives UniversalCache.SetIfAbsent and
checkAndMarkLogoutJTIProcessed through miniredis behind a proxy that
drops the SET NX reply, using a deterministic pre-call delay to avoid
racing the real 500ms timing window.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(main): cover AllowUnauthenticatedPreflight constructor wiring

FIX-02: main.go NewWithContext wires
Config.AllowUnauthenticatedPreflight into
TraefikOidc.allowUnauthenticatedPreflight, but every existing
middleware test builds *TraefikOidc as a struct literal and sets the
field directly, so deleting that wiring line failed no test.

Add a pair of tests that build the plugin through NewWithContext: one
with the flag enabled, asserting a genuine CORS preflight reaches next
and the response body is discarded; one with the default config,
asserting the same request is redirected into the login flow instead.
Confirmed with a mutation (temporarily removing the wiring line) that
the enabled case fails while the default case still passes, then
restored the line.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(refresh): drop unused nolint:gosec on tracked refresh goroutine

FIX-36: nolintlint (allow-unused: false) reports the //nolint:gosec
directive on the tracked refresh goroutine call as unused — gosec
never flagged this line, so the suppression served no purpose.

Remove the directive suffix and keep the explanatory comment, which
still documents why the goroutine detaches from the request ctx.

nolintlint is not in .golangci.yml enable list in this worktree, so
plain golangci-lint run ./... does not surface this finding either
before or after the change; verified with --enable nolintlint instead
that the report is gone and gosec genuinely does not fire on this
line. The plain run ./... command shows the same 6 pre-existing,
unrelated findings before and after (2x gosec G117 in
internal/dcrstorage, 2x gosec G710 in internal/testutil/servers,
1x gosec G124 in internal/testutil/suite.go, 1x unparam in
token_manager.go) — left untouched, out of scope.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* refactor(token): remove the dead verifyOpts parameter

FIX-17 removed the only reader of verifyOpts.skipReplayMarking, so golangci-lint (unparam) reported the opts parameter of verifyTokenWithOpts as unused. Remove the verifyOpts type, its dead field, its only write in buildPrincipalFromBearerToken and the parameter, and update the comments that described it. Behaviour does not change. The function keeps its name to avoid churn in the many comments that refer to it.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(helpers): move round-file-declared cross-file JWT/GD test helpers into shared files

makeTestJWT (review_r92_test.go) was consumed by
access_token_unexpired_iat_optional_test.go and resetGdInstancesForTest
(review_r34_regression_test.go) was consumed by fix18_gd_lifecycle_test.go,
reintroducing the hidden cross-round-file dependency FIX-41 removed:
deleting or folding either round file would silently break its consumer.

Move makeTestJWT into jwt_test_helpers_test.go (alongside the other shared
JWT builders) and resetGdInstancesForTest into a new
gd_test_helpers_test.go, unchanged in behaviour.

Add TestRoundFilesDependOnlyOnSharedHelpers, a static AST-based regression
pin that parses every _test.go file and fails if any non-Test helper
declared in a review_rNN*_test.go round file is referenced from another
file, catching this class of fragility again.

Closes the remaining partial from FIX-41.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(middleware): drop Content-Length on implicit-200 preflight writes

optionsPreflightWriter only stripped a stale Content-Length inside its
own WriteHeader. A next handler that sets Content-Length and calls
Write with no explicit WriteHeader (the implicit-200 idiom) left the
real header in place while the body stayed discarded, so the client
saw a non-zero Content-Length with an empty body and treated the
preflight response as truncated.

Write now commits an implicit 200 through WriteHeader before
discarding the bytes, so Content-Length is stripped either way.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(middleware): repanic ErrAbortHandler, drop guessed post-next 500

ServeHTTP recovered http.ErrAbortHandler like any other panic and
returned normally, so net/http finished the response as if it were
complete: a reverse-proxied body truncated mid-copy (httputil panics
with this sentinel) reached the client as a clean 200 instead of an
aborted connection. Re-panic it first, before any logging or write,
so the outer net/http recovery aborts the connection the same way it
would with no plugin in front of it.

Separately: once t.next.ServeHTTP has been called it holds the real
ResponseWriter (FIX-06), not the tracking wrapper, so wroteHeader can
no longer prove nothing was sent. The old code still guessed and sent
WriteHeader(500) unconditionally, which is a superfluous call net/http
logs whenever next already committed a response. The recovery now
logs and returns without writing once next has been reached, instead
of guessing. Documented trade-off: a panic in next before it writes
anything no longer gets an explicit 500 from this middleware.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(main): gate the SECURITY log on whether an override is set

discoveredEndpointHasNoOverride was static: it always answered false
for revocation, end_session and introspection, regardless of whether
the operator had actually configured revocationURL/oidcEndSessionURL/
introspectionURL. With no override set, a scheme-downgrade drop of one
of these three is exactly as terminal as a drop of jwks_uri,
authorization or token, yet it never logged the SECURITY line, and the
comment plus docs/CONFIGURATION.md claimed nothing fails for them.

discoveredEndpointHasNoOverride now checks the matching config field
and fires the SECURITY line whenever it is empty. registration is
unaffected: its override is read independently of this discovery
step. Corrects docs/CONFIGURATION.md to match.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(yaegicheck): fail NEW-01 introspection checks on recovered panic

checkNew01IntrospectionBearerStatus only failed when rw.Code == 0,
which httptest.NewRecorder never leaves (it starts at 200), so a
reintroduced errors.As panic on the bearer path -- recovered by
ServeHTTP as a 500 -- still printed PASS. Require the exact expected
status (503, bearerErrIntrospectionUnavailable) instead.

The bearer path also shares introspectToken with the SESSION path
(token_validation_rs.go, the NEW-01 fix site) but never reaches it, so
no check exercised the classification commit d7686c3 actually fixed.
Adds checkNew01OpaqueSessionIntrospectionClassification: builds an
authenticated cookie session holding an opaque access token via a
second SessionManager sharing cfgs encryption key and cookie
parameters (the plugins own session manager is an unexported field,
unreachable from this package, but the cookie codec key is a pure
function of those inputs), then drives it through ServeHTTP against a
5xx introspection response and requires the expected 302
re-authentication redirect.

Verified both checks fail under yaegi v0.16.1 with a temporarily
reintroduced errors.As at their respective sites (bearer_auth.go
buildPrincipalFromOpaqueIntrospection, token_validation_rs.go
validateStandardTokensRS), then reverted.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* ci(pr): run cmd/yaegicheck under yaegi v0.16.1 on every PR

The 15 yaegi-only regression checks in cmd/yaegicheck (errors.As on an
interpreted target, SSE Flush across the interpreter boundary, ...)
only ran locally via `make yaegi-validate`. The shared go-pr.yaml
workflow has no yaegi step, so a PR reintroducing an errors.As on an
interpreted type -- the exact shape of the NEW-01 production break --
passed CI.

Adds a sibling yaegi-validate job: checkout, setup-go, install yaegi
pinned to v0.16.1 (the version Traefik v3.7.1 vendors, matching
Makefile YAEGI_VERSION), symlink the checkout into GOPATH so yaegi
resolves the plugins own import path, then run cmd/yaegicheck.
contents:read only and a 10-minute timeout; no non-actions/* action is
used, so nothing needs SHA pinning. The existing pr-checks job is
unchanged.

Validated: python3 -c "import yaml" parses the file, and the shell
steps ran end to end against a fresh private GOPATH (go install +
symlink + yaegi run, exit 0).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(middleware): repanic instead of swallowing a post-next panic

Once t.next has been called, the deferred recover silently returned
after logging, answering every post-next panic with a false clean
response: an empty 200 for a pre-write panic, and a truncated-but-
"complete" 200 for a mid-body panic. That is the same defect class
the ErrAbortHandler branch above it already exists to prevent.

Re-panic the original value instead, once calledNext is true. This
writes no second WriteHeader and wraps nothing, so it reaches
net/http's own top-level recovery (or, in production, Traefik's
compiled recovery middleware), which can tell whether a response was
already committed and react correctly from outside this plugin.

Update the three regression tests that pinned the old return-normally
behavior (TestServeHTTP_RecoversHandlerPanic,
TestServeHTTP_PanicAfterNextCommitted_NoSuperfluousWriteHeader,
TestR155_ServeHTTP_PanicAfterCommitKeepsBodyIntact) to recover around
ServeHTTP and assert the original panic value comes back out, with the
writer holding only next's own writes.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(middleware): fix stale trackingWriter doc comment on calledNext

The comment said the panic handler still sends a header-only 500 once
calledNext is true. That stopped being true with the repanic fix: the
recover now re-panics the original value and writes nothing.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(yaegi): pin ErrAbortHandler abort behavior through a compiled next

r == http.ErrAbortHandler only matches a panic raised by compiled
code under yaegi v0.16.1 -- exactly the real production shape, since
only this plugin runs interpreted and every next handler downstream
of it is compiled. Add a yaegicheck that drives that shape for real: a
front-facing server running the interpreted plugin, next a compiled
httputil.ReverseProxy, upstream writes a partial chunk, flushes, then
Hijacks and closes the raw connection. The client must see a non-nil
read error, never a clean 200 with a truncated body.

Amend the comment on the ErrAbortHandler branch: the re-panicked
value is not identical to the sentinel once it crosses back out of
the interpreter, so net/http and Traefik log a panic line even though
the connection still aborts correctly.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(yaegicheck): require an actual introspection hit for NEW-01 session check

checkNew01OpaqueSessionIntrospectionClassification passed on a bare
302 alone. An unauthenticated request with no session cookie at all
also redirects with 302, without ever calling
introspectToken/validateOpaqueToken (the d7686c3 fix site), so a
future regression there could leave the check green.

Count requests that reach the introspection endpoint with an atomic
counter and require at least one, alongside the existing 302 check.

Verified: with the cookie deliberately withheld (simulating the
second SessionManager cookie no longer decoding), the check now FAILS
with "expected at least one request to reach the introspection
endpoint ... got 0" instead of silently printing PASS.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(main): cover revocation and introspection in the override-replace test

TestUpdateMetadataEndpoints_ConfigOverrideReplacesDroppedEndpoint only
pinned end_session. A regression that stopped applying
configRevocationURL or configIntrospectionURL specifically left every
test green.

Verified: with discoveredEndpointHasNoOverride hardcoded to always
report no override for revocation/introspection (ignoring the
configured override), the prior test suite still passed. The new
table-driven version, run against the same mutation, fails for both
revocation and introspection; reverted, all three subtests pass.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(config): correct registration override wording for scheme-downgrade drops

The prior wording implied an override always covers registration. It
does not: RegisterClient falls back to the discovered
registrationURL whenever dynamicClientRegistration.registrationEndpoint
is unset (main.go), so an unset override plus a scheme-downgrade drop
breaks Dynamic Client Registration with only the generic ERROR line --
the same unset-override case this fix already made loud for
revocation, end_session and introspection.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(session): make pool-return ownership check and release atomic

returnToPoolIfOwner checked sd.generation.Load() != gen and then called
returnToPoolSafely, whose inUse.CompareAndSwap(true, false) is a second,
independent atomic. GetSession/newSession hand an object out with
inUse.Store(true) before generation.Add(1), so a stale deferred return
from a previous owner could land its generation check in that window,
then have its CAS succeed against a concurrently re-acquired object,
releasing (and Reset()ing) a session another request still owns.

Replace inUse+generation as the ownership gate with a single atomic
word, sessionOwner: 0 means free, any nonzero value is the current
owner's generation. A handout claims it with Store(newGeneration); a
release claims it back with one CompareAndSwap(gen, 0). generation
itself never resets and is never reused, so once a release zeroes
sessionOwner, no later stale CompareAndSwap naming an older generation
can ever match again, regardless of timing against a new owner's own
writes.

inUse stays as a best-effort, observational field for callers that only
need a snapshot (token_manager.go's refreshToken abort check); it is no
longer part of the ownership decision. ReturnToPool now delegates to
returnToPoolSafely so both unconditional-release call sites share one
gate instead of racing two independent CAS mechanisms.

Adds a stress regression test that races the real returnToPoolIfOwner
against a goroutine performing the exact writes GetSession/newSession
make on a handout of a freshly-freed object. A cruder version of the
same race (matching the old two-field design, where a release never
touched generation) reproduced the bug in 362/400000 iterations against
the unfixed code; the fixed code shows 0 hits deterministically across
repeated -race runs.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(session): pin ServeHTTP's generation-gated pool-return wiring

The only existing regression for FIX-10 (fix10_session_pool_aba_test.go)
calls returnToPoolIfOwner directly and never drives ServeHTTP, where the
actual fix lives (middleware.go:700-701:
'defer session.returnToPoolIfOwner(sessionGen)' instead of a plain
'defer session.returnToPoolSafely()'). Reverting those two lines
compiles and leaves the whole root suite green (re-review finding at
session.go:1825).

Add a test that drives a real ServeHTTP call through the
Clear-and-reacquire branch (processAuthorizedRequestRS's backchannel/
front-channel-logout invalidation check). A small test-only hook,
sessionClearReleaseHook (nil outside tests, called at the end of
Clear()'s existing pool-return defer), lets the test pause the
invalidated request's goroutine the instant its session is freed and
deterministically steal that exact object with a direct GetSession
call, mark it as a different user's live session, then let the
invalidated request run to completion including its outer ServeHTTP
defer.

Verified the test fails (5/5 runs) against a temporary, uncommitted
revert of middleware.go:700-701 to 'defer session.returnToPoolSafely()'
(inUse=false: the stale call released the concurrent owner's session),
and passes (including under -race) against the unmodified wiring.
middleware.go itself is untouched by this commit.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(session): make the ServeHTTP pool-owner wiring test deterministic

The initial version of TestServeHTTP_InvalidatedSessionReacquireDoesNotStealConcurrentSession
was flaky in two independent ways, both found by stress-running it:

1. Stealing the freed session object via a second, real GetSession call
   (even from the same goroutine, immediately after the Put, with
   GOMAXPROCS(1) and GC disabled) missed the just-freed object in roughly
   a quarter of runs -- sync.Pool's exact reuse behavior here is an
   unspecified implementation detail. Fixed by having the hook swap the
   SessionManager's pool for a fresh, empty one the instant it captures
   the freed pointer, so request A's own reacquire can only allocate a
   new object, never collide with the stolen one.

2. The test asserted on the stolen object's user identifier
   (SetUserIdentifier/GetUserIdentifier), which lives in the gorilla
   session's Values map. gorilla/sessions caches a decoded session on the
   *http.Request's context keyed by cookie name; request A's own reacquire
   reads the SAME request, so it aliases the SAME underlying mainSession
   the stolen SessionData points to, even once it is a distinct SessionData
   struct. Request A's own re-auth bookkeeping then legitimately (and
   correctly) mutates that shared map, which looked like corruption but
   had nothing to do with the pool-ownership bug being tested. Fixed by
   asserting only on the SessionData struct's own ownership fields
   (inUse/sessionOwner via ownerGeneration), which ns's aliased
   mainSession cannot touch.

Verified: 80/80 passes against the correct wiring and 20/20 failures
against a temporary, uncommitted revert of middleware.go:700-701 to
'defer session.returnToPoolSafely()', both under -race. middleware.go
itself remains untouched.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(session): simulate the real handout sequence in the FIX-10 ABA test

The stale-return simulation wrote inUse and generation but left
sessionOwner at 0. returnToPoolIfOwner gates on sessionOwner, so the
stale return CAS mismatched because the object looked already-free
(owner 0), not because a real new owner held it. The cleanup call at
the end of the test was therefore a no-op: it never released the
object back to the pool.

Set sessionOwner to the freshly bumped generation before inUse, the
same order GetSession/newSession use on every real handout
(session.go:1076-1078, 1108-1110). Verified against the current
session.go: before this change the cleanup left inUse true and
activeSessions unchanged; after it, inUse goes false and
activeSessions decrements by one, as a real release does.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(session): skip the pool-owner race test below GOMAXPROCS 2, fix rate claim

TestSessionPoolReturnIfOwner_ConcurrentHandoutRace only catches the
regression statistically: it needs two OS threads to interleave a
stale returnToPoolIfOwner with a concurrent handout. At GOMAXPROCS=1
it passes with 0 hits even against the unfixed two-field gate, so a
single-CPU runner would report green for the wrong reason. Skip the
test below GOMAXPROCS 2 instead.

The comment also claimed a rate "consistent with" a different,
unrelated experiment (about 3 hits per 1.2M), which does not hold up:
reverting returnToPoolIfOwner/returnToPoolSafely to the pre-fix
two-field gate and running this exact test gives 76-89 hits per
400000 on this 16-core machine, roughly 100x that figure. Replace the
claim with the rate actually measured for this test against that
mutation, plus the 0-hits-at-GOMAXPROCS=1 control that motivates the
skip.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(bearer): check local revocation blacklist and nbf on opaque path

buildPrincipalFromOpaqueIntrospection never read t.tokenBlacklist, so a
captured opaque bearer token kept authenticating after logout for as
long as the introspection endpoint still reported it active (RevokeToken
blacklists locally; provider-side revocation is best-effort and silent
by default). Reject the raw token and, when the introspection response
carries one, its jti (gated on disableReplayDetection), the same way
verifyTokenWithOpts gates the JWT path. Also enforce nbf, which
validateOpaqueToken already applies on the session path and the JWT
path applies through verifyTimeClaims, but the opaque bearer path
skipped.

Regression tests: RevokeToken-blacklisted raw token, blacklisted jti
echoed in the introspection response, and a future nbf all now 401;
each failed on the base code before this fix.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(bearer): correct maxTokenAgeSeconds:0 opt-out claim

main.go maps every maxTokenAgeSeconds <= 0 (unset or an operator setting
0) to a 24h default; there is no config value that disables the iat-age
check. The FIX-24 comment and BEARER_AUTH.md both said 0 could disable
it and be used as an opt-out for an iat-less opaque introspection
response. State plainly that 0 means the 24h default and that a
response without iat is rejected once the bound is in effect, which it
always is.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(bearer): rewrite stale JTI replay marking claim

FIX-17 removed the last writer of the JTI replay cache: no request path
Sets a JTI any more, so the header comment and BEARER_AUTH.md row that
described a Set/Get split ("skips the Set but the Get stays active")
were stale. Revocation does not depend on that cache: RevokeToken
blacklists the raw token and a JWTs jti, and both the JWT and (as of
the previous commit) the opaque-introspection bearer path check that
blacklist before accepting a token.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* chore(cache): remove dead ShardedCache

FIX-17 removed jwt.gos replay cache, ShardedCaches last production
caller. Nothing outside its own tests referenced NewShardedCache or
ShardedCache after that (verified with grep across the package and a
clean go build). Delete sharded_cache.go and the test functions that
existed only to exercise it:

- review_r57_shard_eviction_test.go, review_r86_test.go: deleted whole
  files, entirely ShardedCache-specific.
- cache_test.go, cache_bench_test.go, review_r129_test.go,
  review_r153_regression_test.go: deleted only the ShardedCache-specific
  functions/benchmarks, keeping unrelated tests in the same file.
  BenchmarkShardedVsGlobalMutex is dropped whole since its purpose was
  comparing against ShardedCache.

Approved dead-code removal per review decision; go build and the full
test suite are clean after the removal.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(bearer): scope JTI replay claim to access tokens

bearer_auth.go header and BEARER_AUTH.md JTI-replay row said no path
writes a JTI to a replay cache at all. Backchannel logout still writes
logout-token JTIs via checkAndMarkLogoutJTIProcessed (made atomic by
FIX-17, not removed). Limit the claim to access-token JTIs and name the
one JTI replay check left.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(bearer): correct stale JTI Set/Get replay claim in README

README said the bearer path skips the JTI Set but keeps the Get active,
contradicting the rewritten BEARER_AUTH.md and bearer_auth.go, both of
which say no access-token JTI Set exists on this path at all. Replace
with a bullet matching the corrected wording: revocation goes through
the raw-token (and JWT jti) blacklist, not a JTI-replay Get.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(config): correct maxTokenAgeSeconds opt-out claim

CONFIGURATION.md said maxTokenAgeSeconds:0 disables the age check.
main.go maps any value <= 0 to a 24h default; no value disables the
check. BEARER_AUTH.md already carries the corrected wording; this was
the sibling copy the earlier fix missed.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(bearer): correct nbf clock-skew-tolerance claim in comment

Comment on the opaque-introspection nbf check said it was the same
check the JWT path applies through verifyTimeClaims. It is not: the JWT
path's verifyNotBefore allows 10s of ClockSkewTolerancePast, this check
allows none. It does match validateOpaqueToken's strict comparison and
this function's own strict exp check. Comment only, no behaviour
change.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(bearer): assert opaque-token rejects return 401 not 503

TestBearerOpaqueIntrospection_RevokedTokenRejected,
_BlacklistedJtiRejected and _NbfFutureRejected only checked bErr != nil.
A mutant that swaps those three gates to
newBearerError(bearerErrIntrospectionUnavailable, ...) (mapped to 503,
and skipped by the per-IP failure tracker) still passed bErr == nil.
Add a kind == bearerErrTokenInactive check to each so the tests pin the
401 status, not just any error.

Verified against the described mutant before reverting it: all three
tests failed with 'got kind 6' (bearerErrIntrospectionUnavailable);
reverting the mutant restores a clean pass.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(bearer): pin disableReplayDetection skips jti blacklist check

The jti-blacklist gate at bearer_auth.go:928 guards itself with
!t.disableReplayDetection, but no test exercised that guard. Add
TestBearerOpaqueIntrospection_BlacklistedJtiIgnoredWhenReplayDetectionDisabled:
a blacklisted jti on an otherwise-valid introspection response must be
accepted when disableReplayDetection is true.

Verified against a mutant removing the guard before reverting it: the
new test failed with 'token replay detected (jti blacklisted)'
(bearer_opaque_binding_test.go:337); reverting the mutant restores a
clean pass across all TestBearerOpaqueIntrospection_* tests.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache/redis): treat a Redis command-error reply as definitive in SetNX

RedisBackend.SetNX reported ErrSetNXAmbiguous for any post-write read
failure, including a RESP -ERROR reply (READONLY, OOM, MISCONF). That
reply proves Redis rejected the command, unlike a genuinely lost reply
after a timeout/EOF/reset. Reporting it as ambiguous let
checkAndMarkLogoutJTIProcessed accept a logout jti-claim outright
instead of falling to its local Get+Set fallback, so a captured
backchannel-logout token could be replayed forever while Redis
rejects writes (e.g. a demoted read-only replica).

Check errors.Is(doErr, ErrCommandReply) before the sent-based
ambiguity check and return it as a plain error. Add a proxy-backed
regression test in internal/cache/backends pinning SetNX itself, and
an end-to-end test wiring a real RedisBackend behind a proxy that
always answers SET-family commands with -READONLY, confirming
checkAndMarkLogoutJTIProcessed now rejects the second delivery of the
same jti.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): let a newer backend value win over a stale-marked local one

FIX-04s backend-stale mark let Get serve the local value over EVERY
later backend value for a marked key, assuming the backend entry
could only be older (a same-replica write that may have landed after
a timeout). That is false across replicas: another replica can write
a genuinely newer value to the same key while this one is still
marked stale, e.g. a later cross-replica backchannel logout. The
session-invalidation cache (MonotonicMarkers, 25h local TTL) could
then ignore a newer logout from another replica for up to 25h.

Add backendValueIsNewer: when both the local and backend values
decode to a comparable timestamp, Get now serves whichever is not
older, so a genuinely newer backend value wins. Values it cannot
compare (e.g. the blacklist caches bool markers) keep the original
FIX-04 behavior of always preferring local. This also keeps the
original protection intact: an applied-but-timed-out Set is still not
clobbered by an older backend value, because local is newer in that
case too.

Add two-replica regression tests (a shared fake backend, no real
Redis needed) for both the plain and MonotonicMarkers cases.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* perf(cache): bound the legacy blacklist-namespace lookup cost

checkLegacyBlacklistMarker ran an extra Redis round trip (PING+GET,
plus PTTL when the key existed) on every single blacklist Get miss,
which is nearly every blacklist check, since most tokens are never
revoked. It also fully JSON-decoded whatever it found there, even a
CacheTypeToken claims map cached under the same raw token, just to
learn the value was not the boolean marker.

Compare the raw legacy value against the exact bytes serialize(true)
produces before decoding anything, and remember a miss (or a
non-bool legacy hit) locally per key for legacyBlacklistMissCacheTTL
(30s), so a repeated check for the same key skips the legacy round
trip until the window elapses. A genuine legacy marker already in
Redis is still honored once the window is up. Prune expired entries
opportunistically from cleanup(), which already runs on a timer for
every cache including the blacklist one.

Add miniredis CommandCount-based regression tests: the fix reduces a
repeated miss from 4 Redis commands to 2, and separate tests pin that
a real legacy marker is still found and a cached claims map is still
never misread as one.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* chore(cache): remove dead memory/hybrid backend config

FIX-43 deleted MemoryBackend and HybridBackend, but config.go still
declared BackendTypeMemory, BackendTypeHybrid, TypeMemory, TypeHybrid,
DefaultConfig (Type: memory) and DefaultHybridConfig — config for
backends with no implementation left. Confirmed no production caller
of backends.DefaultConfig or backends.DefaultHybridConfig outside
their own now-deleted tests (servers.DefaultConfig in
internal/testutil/servers is an unrelated function).

Remove both functions and the memory/hybrid constants; keep
BackendTypeRedis/TypeRedis, the only backend now implemented. Delete
config_test.go, which exercised only DefaultHybridConfig.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(cache): run the backend contract suite against a real RedisBackend

TestCacheBackendContract was a no-op: setupMemoryBackend and
setupRedisBackend were both t.Skip stubs, so no CacheBackend
implementation ever ran the 13 shared contract tests. MemoryBackend
no longer exists (FIX-43), so drop that subtest and wire
setupRedisBackend to a real miniredis-backed RedisBackend, matching
the pattern redis_test.go and singleflight_test.go already use.

miniredis only expires a key when its own simulated clock is moved
forward (FastForward) - it never expires anything on real elapsed
time, so testTTLExpirations time.Sleep never actually exercised
expiry against it. Thread an advanceClock func through
runContractTests/testTTLExpiration and pass mr.FastForward for it, so
that subtest genuinely proves expiry rather than passing by coincidence.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): bound the backend-stale mark in time for values FIX-04 cannot compare

markBackendStale/backendStaleLocalValue let Get serve the local value over
every later backend value, for as long as the local entry stayed live,
whenever backendValueIsNewer cannot decode the value into a comparable
number (a string, a map, a struct). The DCR client-credentials cache
(a JSON string, TTL up to 100*365 days) hit this on every replica whose
write timed out: a stale credential could pin over a value a different
replica legitimately wrote, for the entry's whole TTL.

staleBackend now records when each key was marked (map[string]time.Time),
and backendStaleLocalValue treats a mark older than the new
backendStaleMarkTTL (5s, well above the 500ms Set timeout) as expired,
deleting it so the current backend value is trusted again. The numeric
newer-wins comparison for MonotonicMarkers caches is unchanged.

Two regression tests pin both directions for a non-numeric (string) value
across two replicas sharing one backend: within the bound an older
backend write does not clobber the surviving local value, and after the
bound a newer value written by another replica is served.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): gate the backend-stale numeric comparison on MonotonicMarkers

backendValueIsNewer's "larger number wins" comparison ran for every
cache, not only MonotonicMarkers ones. For a non-monotonic numeric cache
a larger number is not necessarily a newer write, so an older, larger
backend value could clobber a fresh, smaller local write that survived a
timed-out Set — the exact clobber FIX-04 exists to prevent.

Get now gates the comparison behind c.config.MonotonicMarkers. Every
other cache recovers from a stale mark via the time bound added in the
previous commit instead of by numeric order.

Rebuilt TestR4_BackendStale_CrossReplicaNewerValue_PrefersNewerBackend on
the time bound instead of numeric order, since its cache never set
MonotonicMarkers, and added a regression test pinning the direction it
used to get backwards (an old, larger backend value must not clobber a
fresh, smaller local write on a non-monotonic cache).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* perf(cache): cap legacyBlacklistMissUntil at the cache's MaxSize

legacyBlacklistMissUntil had no size cap of its own. Its keys came from
the raw bearer token, looked up before signature verification, so a
caller who can send unique tokens fully controlled how many distinct
entries piled up. Pruning ran only from cleanup()'s 5-minute tick, so
each unique key stayed in memory for up to ~5.5 minutes regardless of
volume — unbounded memory a caller could grow at will.

recordLegacyBlacklistMiss now caps the map at c.config.MaxSize (already
>0 for every cache), pruning expired entries inline when the cap is hit
before deciding whether to record. If it is still full afterward, the
miss is simply not recorded — the only cost is one extra legacy lookup
next time, exactly what every check paid before this bound existed. The
map is also keyed by a sha256 digest of the lookup key instead of the raw
string, so an entry's size no longer grows with token length.

Regression test drives a small-MaxSize blacklist cache through 4x its
cap in unique misses and asserts the map never exceeds the cap, and that
a genuine legacy marker is still honored while the map sits at capacity.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): honour the pre-#117 legacy blacklist marker encoding

checkLegacyBlacklistMarker's byte compare recognized only the current
serialize() encoding (0x01 type-marker byte + json.Marshal(true)). Code
before #117 (commit 775de2a; every tag up to and including v0.8.17) wrote
plain json.Marshal(true) with no type-marker byte at all - 4 bytes,
'true'. deserialize's legacy no-marker fallback still accepts that
shape, and the OLD checkLegacyBlacklistMarker (which deserialized instead
of comparing bytes) honored it, so a Redis-mode upgrade straight from
v0.8.17 or earlier could silently drop revocations written up to the
blacklist's TTL before the upgrade.

Also accept legacyBlacklistTrueMarker with its type-marker byte stripped.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(lifecycle): fix order-dependent baseline and global-state leaks in FIX-35/18/19 tests

TestFix35_ConcurrentNewKeepsSingletonAliveAcrossOldClose registered a live
instance without capturing a liveInstanceCount baseline first. A live
instance left registered by an earlier test in the same run already makes
the pre-FIX-35 stale "was last" decision false on its own, so the test
cannot tell a reverted production fix from a working one under -shuffle.
Save/reset/restore the counter via a new resetLiveInstanceCountForTest
return value and t.Cleanup instead. Reproduced with a temporary leaked
instance ahead of the test plus a manual revert of the FIX-35 decision in
Close(): the test passed either way before this change, now fails as
expected. TestFix35_StopIfLastInstanceHoldsLockAcrossCheckAndStop is
updated to the same save/restore pattern.

TestFix18_CloseImmediatelyAfterNewDoesNotReRegister called the shared
resetGdInstancesForTest helper, which wipes the process-global gdInstances
registry with no restore, discarding any GracefulDegradation instances
other tests left registered. Add snapshotAndClearGdInstancesForTest, which
saves the prior set and restores it via t.Cleanup.

TestFix19_RegisterBackgroundTaskKeepsPendingTaskNoOrphan called
rm.StopAllTasks() on the process-global ResourceManager, which stops every
registered singleton task (memory-monitor, singleton-token-cleanup, etc.),
not just the one this test created. Replace it with
StopBackgroundTask(name) so the test only touches its own task.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(recovery): treat HTTP 408 as transient in isTerminalClientError

isTerminalClientError excluded only 429 from the terminal-4xx breaker
exemption, so a burst of token-endpoint 408 Request Timeout responses
never opened the refresh circuit breaker. token_validation_rs.go (FIX-13),
bearer_auth.go, and internal/recovery already classify 408 as a transient
service-health signal, not a per-request rejection. Exclude 408 alongside
429.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* refactor(recovery): move healthRoutineSettled out of production code

GracefulDegradation.healthRoutineSettled was added to error_recovery.go
(production) but its only caller is fix18_gd_lifecycle_test.go, and its
own doc comment says "Tests use this". FIX-39 established the pattern of
keeping test-only helpers out of the production binary
(internal/pool/export_test.go). Move the method into
fix18_gd_lifecycle_test.go next to its sole caller,
waitForHealthRoutineSettled.

No behavior change: verified via go build (production code compiles with
the method removed) and the FIX-18 test suite, unchanged.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(refresh): remove fixed-sleep dedup race in TestRefreshRateLimiting

TestRefreshRateLimiting used the default 100ms DeduplicationCleanupDelay
and a 150ms sleep to outrun it before starting the next iteration -- the
same fixed-sleep-vs-cleanup-timer race FIX-22 removed from its siblings
(TestCircuitBreakerProtection, issue67, review_refresh_cb), but not from
this test.

Reproduced deterministically by temporarily setting
DeduplicationCleanupDelay above the 150ms sleep: the next CoordinateRefresh
call then joins the still-registered previous operation instead of
starting fresh, so attempts is miscounted (5 instead of 3) and cooldown
never triggers. Fix: DeduplicationCleanupDelay=0 plus waitForRefreshDrain
polling the in-flight map, matching the sibling tests.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(refresh): bound Shutdown's abandonment of in-flight refreshes to a drain cap

FIX-36 made Shutdown cancel rc.ctx immediately, aborting every in-flight
refresh unconditionally -- including one whose refreshFunc call had
already reached the IdP and would complete on its own. Discarding that
result loses the token response, and for a rotating IdP (Zitadel,
Authentik), consumes a one-time-use refresh token that gets thrown away,
forcing the next refresh into invalid_grant and a re-login.

DECIDED: Shutdown now waits for in-flight refreshes to drain naturally, up
to a new shutdownRefreshDrainTimeout (5s) constant. A refresh that
completes within the cap delivers its result to its waiters as normal;
Shutdown only cancels rc.ctx (abandoning whatever is still running) once
the cap elapses, so Shutdown itself never blocks longer than the cap.
CoordinateRefresh's stopChan check (still gated by lifecycleMu, still
ahead of wg.Add) is unchanged: a call arriving after Shutdown starts is
still rejected immediately, without waiting for the drain cap.

Reproduced with a probe mirroring the finding's evidence (refreshFunc
completes 300ms after Shutdown starts): the waiter got "refresh
coordinator is shutting down: context canceled" instead of its tokens on
unfixed code. Added as
TestFix36_ShutdownDeliversResultForRefreshCompletingWithinDrainCap
(fails on base at refresh_coordinator_test.go:905) and
TestFix36_ShutdownReturnsNearCapWhenRefreshExceedsIt (fails on base:
Shutdown returned after 4.666us instead of waiting out the cap), plus a
rejected-during-drain coverage test. Rewrote
TestFix36_ShutdownReturnsPromptlyDuringInFlightRefresh into these two,
since its "always cancel immediately" assertions directly contradicted
the new contract, and its refreshFunc's fixed 3s time.Sleep left a
goroutine running past the test -- both replacements block on a channel
released via t.Cleanup instead.

Updated review_r63's TestRefreshCoordinatorShutdownReleasesWaiterOnInflight
and review_r154's TestRefreshCoordinator_ShutdownWaitsForInFlight to the
same drain-cap contract: their refreshFunc never completes on its own, so
they now assert Shutdown gives up near the cap (not immediately) and the
waiter still gets an error, while keeping their original wg-tracking
assertion (circuit-breaker failure recorded before Shutdown returns).

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(refresh): gate the pre-start refresh on stopChan, not only rc.ctx

Shutdown closes stopChan synchronously but only cancels rc.ctx after
shutdownRefreshDrainTimeout (or once every in-flight refresh drains).
executeRefreshAsyncs inner goroutine checked only rc.ctx.Err() before
calling refreshFunc, so an operation whose wg.Add ran just before
Shutdown started, but whose goroutine reached that check afterward,
still spent the IdP grant for nothing during the whole drain window.

Add a stopChan gate ahead of the rc.ctx check so a refresh not yet
started is skipped and its waiter gets the shutdown error immediately.
Also make Shutdown cancel rc.ctx unconditionally before it returns (not
only on the drain-cap path), so a clean Shutdown with nothing in flight
still leaves rc.ctx canceled instead of dead. Update the stale FIX-36
comments describing the old cancel-immediately contract.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(refresh): wait on stopChan instead of fixed sleeps in two Fix36 tests

TestFix36_CoordinateRefreshRejectedAfterShutdownStillImmediate slept
20ms hoping Shutdown had closed stopChan by then; a late-scheduled
Shutdown would let the second CoordinateRefresh get wrongly accepted.
TestFix36_ShutdownDeliversResultForRefreshCompletingWithinDrainCap
slept 50ms before releasing the refresh; if Shutdown had not started
yet, the refresh would finish before Shutdown ran, passing even on the
reverted cancel-immediately code (a false negative).

Both now block on <-rc.stopChan (with a 2s failure timeout) so the
release/second-call always happens strictly after Shutdown has begun.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(lifecycle): remove duplicated doc paragraph in FIX-35 test

be3ac67 duplicated the TestFix35_ConcurrentNewKeepsSingletonAliveAcrossOldClose
doc paragraph word for word. Delete the copy and keep the baseline
paragraph that follows it.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(lifecycle): restore process-global singleton state in fix18/fix35 tests

TestFix18_TraefikOidcCloseEmptiesGDInstances made its synthetic
instance the last live one, so Close() ran stopIfLastInstance and
stopped singleton-token-cleanup and (via StopAllTasks) every other
process-global singleton, including memory-monitor, with nothing to
restart them. TestFix35_ConcurrentNewKeepsSingletonAliveAcrossOldClose
unconditionally reset the global memory monitor on entry and on
cleanup, discarding whatever state an earlier test in the same binary
left running.

Fix18: register a sentinel live instance so this test is never the
last one, leaving Close()s last-instance stop path unreached.
Fix35: capture whether memory-monitor was running before this tests
own reset, and restart it in a cleanup (registered first, so it runs
last) when it was.

Verified with a throwaway probe (started both singletons, ran both
tests via t.Run, asserted running-state after): failed at HEAD with
singleton-token-cleanup=false/memory-monitor=false after fix18 and
memory-monitor still false after fix35; passes with this change.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(lifecycle): surface StopBackgroundTask errors in FIX-19 test

_ = rm.StopBackgroundTask(name) discarded the "task not registered"
error StopBackgroundTask returns on a failed lookup, which would let
the test fail later with a misleading "orphan escaped registry"
message instead of pointing at the real cause. Fail the test directly
with the actual error, and fix the stale StopAllTasks wording in the
neighboring failure message to name the call this test actually makes.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* docs(changelog): record the round-4 re-review fixes

Record the behaviour changes users can notice: opaque bearer tokens with all three bearer flags, the first post-upgrade logout for older sessions, the 5-second refresh drain on shutdown, and panics after forwarding that now abort the connection. Add a Fixed section for the six round-4 fixes and note that the legacy blacklist check runs at most once per key in each 30 seconds.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(cache): keep the backend-stale mark for MonotonicMarkers caches

The round-4 time bound on the backend-stale mark also expired it for MonotonicMarkers caches. When a replica could not write a newer session-invalidation marker to Redis, it fell back to the older backend marker after 5 seconds and stopped enforcing the newer logout, which is the case FIX-04 exists for. Exempt MonotonicMarkers caches from the bound. Get still lets a newer marker from another replica win through the newer-wins compare. The regression test fails before this change (Get returns 1000) and passes after it.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* chore(git): ignore the .claude directory

Local Claude Code state (todos, review artifacts, agent worktrees) lives under .claude/ and must not be committed. Replace the narrower .claude/*.out rule with the whole directory.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(make): fail make lint on golangci-lint findings

The lint recipe "golangci-lint run ./... || echo ..." turned every lint failure into exit 0, so make lint always reported success. Use an explicit if/else: run golangci-lint when it is installed and return its exit status, otherwise print the skip message. TestMakeLintPropagatesGolangciLintResult runs the target with a fake golangci-lint and fails on the old recipe.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix: avoid narrowing int conversions flagged by gosec G115

reserveConnectionSlot and the half-open gate narrowed an int limit to int32, so a configured value above MaxInt32 wrapped negative and refused every connection or probe. Compare in int64 instead. BuildSessionName used rune(0+index) for any index below 10, so a negative index produced a non-digit; limit the fast path to 0..9. Regression tests fail on the old code.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* chore(gosec): annotate intentional findings with #nosec

GitHub code scanning runs standalone gosec, which ignores golangci //nolint:gosec directives and honors only #nosec. Replace the directive with a #nosec Gxxx comment and a reason at the nine intentional sites: persisted DCR client_secret (G117), operator-enabled insecureSkipVerify (G402), the conditional-Secure deletion cookie and a test request cookie (G124), and the test mock IdP redirects (G710). golangci-lint also honors #nosec, so it stays at 0 issues.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* ci: build with Go 1.26

staticcheck@latest (v0.8.1) and govulncheck@latest (v1.8.0) now require Go 1.26. The shared workflow runs them with GOTOOLCHAIN=local on the pinned 1.25.x, so the Static Analysis and Security Scan jobs failed to install them. Pin 1.26.x in pr.yaml (both jobs) and release.yml, matching toolchain go1.26.6 in go.mod.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(recovery): stop health routine restarting task after last Close

GracefulDegradation.Close closed stopChan without gd.mutex. A health
routine that passed its stopChan check could then reach the task registry
after the last Close stopped the shared task. RegisterBackgroundTask
replaces a stopped task, so the routine started a task that no live
instance can stop. This made TestSharedHealthTaskSurvivesOtherInstanceClose
flaky when an earlier test left the shared task running.

Close now closes stopChan under gd.mutex, so an in-flight routine finishes
before the instance unregisters. The lock is released before the task
stop, because BackgroundTask.Stop waits for a pass that takes gd.mutex.

TestSharedHealthTaskNotRestartedAfterLastClose parks the routine after its
check and fails on the old code in 20 of 20 runs.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(recovery): keep shared health pass out of health-check subtests

TestGracefulDegradationHealthChecks calls performHealthChecks directly.
The shared health-check task also runs the same registered checks in the
background, so the race detector reported a write to healthCheckCalled.
The background pass could also clear the degraded state before the first
assertion. The subtests failed 18 of 1000 runs alone under -race.

The two subtests now hold globalHealthCheckMu, so no background pass runs
during their assertions. The unlock is deferred after Close, so it runs
first and Close never waits on a blocked pass.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(tls): drop the deprecated PreferServerCipherSuites field

crypto/tls ignores Config.PreferServerCipherSuites since Go 1.18, and staticcheck v0.8.1 (SA1019), which CI now installs, fails the Static Analysis job on it. Remove the field at its three sites and the stale #nosec comment beside one of them. Behaviour does not change.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test(cleanup): wait for the processed-task metric in TestWorkerPool_GetMetrics

executeTask increments tasksProcessed in a deferred call that runs after the task returns, so the task wg.Done() can fire first, and wg.Wait() returned while the metric still read 1. CI failed on this once. Poll the counter with a 2 second deadline before asserting. With a 20ms delay injected before the increment, the old test fails in 3 of 3 runs and the new test passes.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(recovery): serialize GracefulDegradation creation with the last-instance stop

GracefulDegradation.Close removed the instance from gdInstances, decided it
was the last one, and released the lock before stopping the shared
health-check task. A GracefulDegradation created in that gap registered at
once, and its health routine adopted the still-running task. The stop then
killed the task that the new, live instance relies on, and nothing
restarted it.

Add gdLifecycleMu. NewGracefulDegradation registers under it, and Close holds
it across the last-instance check and the stop. A new instance now either
counts toward the check or registers after the stop, and its routine then
replaces the stopped task. The health-check pass never takes this lock, so
the stop can still wait for an in-progress pass.

TestSharedHealthTaskSurvivesCreateDuringLastClose pauses Close between the
check and the stop through a nil-by-default test seam
(beforeSharedTaskStop). With the seam on the old Close logic, it fails in 10
of 10 runs. With this change, it passes in 20 of 20 runs under -race.

Production impact today is limited: no production code registers a health
check, and degraded state expires through RecoveryTimeout, not the task.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* fix(session): delete stale cookies at the configured cookiePath

Session cookies are written at the configured cookiePath
(EnhanceSessionSecurity), but CleanupOldCookies wrote its deletion cookies
at a hardcoded "/". A browser deletes a cookie only when name, domain and
path all match, so the cleanup removed nothing when cookiePath was set.

Add SessionManager.effectiveCookiePath (the configured cookiePath, or "/")
and use it for cookie writes, for the deletion cookies, and in
getSessionOptions, so the three sites cannot drift. The cleanup deletes
only at the configured path. Cookies written at "/" before an operator set
cookiePath stay until they expire.

TestCleanupOldCookies_UsesConfiguredCookiePath fails on the old code
(deletion Path "/", want "/app") and passes after the fix.

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

* test: close leaked graceful-degradation managers and guard against leaks

Eleven root tests created an ErrorRecoveryManager or TokenResilienceManager,
or built a manager with a GracefulDegradation, and never closed it. Each one
left an instance registered and the shared health-check task running for
every later test in the process. That made lifecycle tests that assume a
clean start flaky (TestSharedHealthTaskSurvivesOtherInstanceClose).

The leakers were found by running each of the 1156 root tests alone, followed
by a check of gdInstances and the task state. Each leaker now registers
t.Cleanup(<manager>.Close).

TestMain now fails the package when tests leave a GracefulDegradation
unclosed or the shared task running, after a 2-second settle window for
plugin instances that close asynchronously. On a leaking test it reports
"tests leaked 1 unclosed GracefulDegradation instance(s)".

Claude-Session: https://claude.ai/code/session_01KwtV5ecajCrftcf8TkfPad

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>

.github/workflows/pr.yaml

@@ -18,6 +18,43 @@ jobs:
   pr-checks:
     uses: lukaszraczylo/shared-actions/.github/workflows/go-pr.yaml@main
     with:
-      go-version: "1.25.x"
+      go-version: "1.26.x"
       coverage-threshold: 70
     secrets: inherit
+
+  yaegi-validate:
+    name: Yaegi interpreter compatibility
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Go
+        uses: actions/setup-go@v7
+        with:
+          go-version: "1.26.x"
+
+      # Pinned to the yaegi version Traefik v3.7.1 vendors (Makefile
+      # YAEGI_VERSION), so this tests the real interpreter a release runs
+      # under, not a newer one that may tolerate more.
+      - name: Install yaegi
+        run: go install github.com/traefik/yaegi/cmd/[email protected]
+
+      # yaegi resolves the plugin's own import path
+      # (github.com/lukaszraczylo/traefikoidc) through GOPATH/src, same as
+      # `make yaegi-validate` does locally.
+      - name: Symlink checkout into GOPATH
+        run: |
+          mkdir -p "$(go env GOPATH)/src/github.com/lukaszraczylo"
+          ln -sfn "$GITHUB_WORKSPACE" "$(go env GOPATH)/src/github.com/lukaszraczylo/traefikoidc"
+
+      # Runs cmd/yaegicheck under the real interpreter: imports the plugin
+      # package, exercises CreateConfig + New, and drives every yaegi-only
+      # regression check (errors.As-on-an-interpreted-target panics,
+      # SSE Flush across the interpreter boundary, etc.) that native
+      # `go build`/`go test` cannot see.
+      - name: Run yaegi regression checks
+        run: DO_NOT_TRACK=1 GOFLAGS=-mod=vendor yaegi run ./cmd/yaegicheck/main.go

.github/workflows/release.yml

@@ -19,5 +19,5 @@ jobs:
   release:
     uses: lukaszraczylo/shared-actions/.github/workflows/go-release.yaml@main
     with:
-      go-version: "1.25.x"
+      go-version: "1.26.x"
     secrets: inherit

.gitignore

@@ -1,4 +1,4 @@
 docker/
-.claude/*.out
+.claude/
 *.test
 .leann/

CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+
+- **`allowUnauthenticatedPreflight` (default `false`).** Every `OPTIONS`
+  request needs authentication by default, as in the last release. Set the
+  option to `true` to let a genuine CORS preflight reach the backend
+  without a session. Only an `OPTIONS` request that carries both `Origin`
+  and `Access-Control-Request-Method` bypasses authentication, and the
+  plugin discards the backend's response body for it, because a browser
+  never reads a preflight body (`settings.go`, `middleware.go`, FIX-02).
+  See the option table in [CONFIGURATION.md](docs/CONFIGURATION.md).
+
+### Changed
+
+- **Opaque bearer tokens when all three bearer flags are set.** A deployment
+  that sets `enableBearerAuth`, `requireTokenIntrospection` and
+  `allowOpaqueTokens` now accepts opaque bearer tokens after RFC 7662
+  introspection. The last release rejected every non-JWT bearer token. The
+  plugin binds an accepted opaque token to the client through `client_id` or
+  `aud`. It also applies the identifier, token-age, logout, revocation and
+  `nbf` checks (`bearer_auth.go`).
+
+- **Sessions created before this upgrade can omit `post_logout_redirect_uri`
+  on their first logout.** The plugin now builds that parameter only from the
+  redirect-URI origin recorded at login, never from the logout request's
+  host. Older sessions have no recorded origin, so those users stay on the
+  IdP's logout page once (`helpers.go`).
+
+- **Shutdown waits up to 5 seconds for a token refresh in progress.** On
+  shutdown, for example a Traefik reload, the refresh coordinator lets a
+  refresh that already reached the IdP deliver its tokens, then returns
+  (`shutdownRefreshDrainTimeout`, `refresh_coordinator.go`). A refresh that
+  has not started does not start after shutdown.
+
+- **A panic after the request reaches the backend now aborts the
+  connection.** The plugin re-panics it, for example the reverse proxy's
+  `http.ErrAbortHandler` when an upstream drops the connection mid-body. Go's
+  HTTP server then aborts the connection. Before, the plugin recovered the
+  panic, so a truncated response could reach the client as a complete 200. A
+  panic before the request reaches the backend still returns 500
+  (`middleware.go`).
+
+- **private_key_jwt now rejects RSA signing keys under 2048 bits.**
+  `validateAlgKeyMatch` stops `New()` with an error when a configured
+  `private_key_jwt` RS\*/PS\* key is smaller than 2048 bits (RFC 7518 §3.3).
+  A smaller key signs locally, but a conformant IdP rejects it at token
+  exchange with `invalid_client`, so the plugin now fails at construction
+  instead of at every runtime exchange. There is no override: deployments
+  using an RSA key under 2048 bits must generate a 2048-bit-or-larger key
+  before upgrading. The rejection returns a matchable `ErrRSAKeyTooSmall`
+  sentinel (`client_assertion.go`).
+
+- **A discovered `http://` endpoint is now dropped when `providerURL` is
+  `https://`.** `validateDiscoveredEndpoint` refuses to accept an
+  authorization, token, jwks_uri, revocation, end_session, introspection, or
+  registration endpoint served over plaintext HTTP when the operator
+  configured an HTTPS provider (R146): using it as-is would send a client
+  secret or token over an unauthenticated channel. There is no configuration
+  flag to disable this check. A dropped endpoint logs an `ERROR` line; a
+  dropped `token`, `jwks_uri`, or `authorization` endpoint — the three
+  every login needs — additionally logs a `SECURITY:`-prefixed line naming
+  the endpoint, the dropped URL, and the fact that there is no override, so
+  the failure is diagnosable instead of surfacing only as a broken login.
+  See [Discovered Endpoint
+  Validation](docs/CONFIGURATION.md#discovered-endpoint-validation)
+  (`url_helpers.go`, `main.go`).
+
+- **Blacklist entries in Redis use the `blacklist:` key prefix.** The
+  blacklist cache now has its own cache type (`CacheTypeBlacklist`), so its
+  Redis keys move from the shared `token:` prefix to `blacklist:` (R128).
+  A cached token entry and a revocation marker for the same raw token can
+  no longer overwrite each other. For one release, a blacklist miss also
+  reads the legacy `token:<key>` entry and treats it as revoked only when
+  the stored value is boolean `true` (`checkLegacyBlacklistMarker` in
+  `universal_cache.go`, FIX-16). The fallback works in one direction only:
+  during a rolling deploy, a replica that runs the previous version does
+  not see revocations that an upgraded replica writes under `blacklist:`.
+  A blacklist miss checks the legacy `token:` entry at most once per key in
+  each 30 seconds, so the fallback adds little Redis traffic.
+
+- **Claim validation accepts four previously-rejected or silently-dropped
+  claim shapes.** Each change below is intentional, matches a production
+  change, and is pinned by an existing regression test.
+  - `iat` (issued-at) is optional in `jwt.Verify`, per RFC 7519 §4.1.6. A
+    token that omits it is validated on `iss`/`aud`/`exp`/`nbf` alone,
+    instead of being rejected (`jwt.go`, R126). The lenient-audience
+    access-token path (`accessTokenUnexpired` in `token_validation_rs.go`)
+    applies the same rule, because both paths call `verifyTimeClaims`
+    (`jwt.go`, FIX-27). Bearer-token auth still rejects a token with no
+    `iat`: it returns `"missing iat claim"` (`enforceIatAge` in
+    `bearer_auth.go`), because `maxTokenAgeSeconds` always applies — `0`
+    falls back to a 24h default (`main.go`).
+  - A numeric `sub` (bearer-auth identifier) claim is stringified instead of
+    rejected, so an IdP that emits a numeric subject still authenticates
+    (`bearer_auth.go` `resolveBearerIdentifier`, R102).
+  - A `groups`/`roles` claim that is neither a string nor an array (for
+    example a bare number or `null`) is treated as an empty list instead of
+    failing claim extraction outright, so a malformed claim on one side does
+    not suppress a valid claim on the other (`token_manager.go`
+    `extractGroupsAndRolesFromClaims`, R96).
+  - A numeric element inside a `groups`/`roles` array is stringified into
+    the list instead of being silently dropped, so a numeric group ID
+    survives extraction and can match an `allowedRolesAndGroups` entry
+    (`token_manager.go` `stringListFromClaim`, `utilities.go`
+    `claimScalarString`, R105).
+
+### Fixed
+
+- The opaque bearer path rejects a token that `RevokeToken` added to the
+  blacklist, for example at logout. It also rejects an opaque token whose
+  `nbf` is in the future (`bearer_auth.go`).
+- The backchannel-logout replay check treats a Redis error reply such as
+  `READONLY`, `OOM` or `MISCONF` as a failure, not as an unknown outcome. A
+  replayed logout token is now rejected while Redis refuses writes
+  (`internal/cache/backends/redis.go`).
+- After a failed cache write, a replica no longer ignores a newer value that
+  another replica wrote, such as a later logout. The preference for the local
+  value expires after 5 seconds (`backendStaleMarkTTL`, `universal_cache.go`).
+- The token circuit breaker treats HTTP 408 from the token endpoint as a
+  transient failure, the same as 429 (`error_recovery.go`).
+- With `allowUnauthenticatedPreflight` enabled, a preflight response no longer
+  carries a stale `Content-Length` when the backend writes a body without
+  calling `WriteHeader` (`middleware.go`).
+- A dropped `http://` revocation, end-session or introspection endpoint logs
+  the `SECURITY:` line when its override (`revocationURL`, `oidcEndSessionURL`
+  or `introspectionURL`) is not configured (`main.go`).

Makefile

@@ -29,7 +29,7 @@ vet: ## Run go vet
 
 .PHONY: lint
 lint: ## Run golangci-lint if available
-	@command -v golangci-lint >/dev/null 2>&1 && golangci-lint run ./... || echo "golangci-lint not installed; skipping"
+	@if command -v golangci-lint >/dev/null 2>&1; then golangci-lint run ./...; else echo "golangci-lint not installed; skipping"; fi
 
 .PHONY: staticcheck
 staticcheck: ## Run staticcheck (matches the CI "Static Analysis" job; catches U1000 unused, etc.)
@@ -37,8 +37,8 @@ staticcheck: ## Run staticcheck (matches the CI "Static Analysis" job; catches U
 	@GOFLAGS=-buildvcs=false $$(command -v staticcheck || echo "$(GOPATH)/bin/staticcheck") ./...
 
 .PHONY: test
-test: ## Run the test suite
-	$(GO) test ./... -count=1 -timeout $(TEST_TIMEOUT)
+test: ## Run the test suite (race detector on: several regression pins, e.g. R44/R77/R111, only fail under -race)
+	$(GO) test -race ./... -count=1 -timeout $(TEST_TIMEOUT)
 
 .PHONY: vendor
 vendor: ## Refresh and vendor dependencies

README.md

@@ -126,13 +126,19 @@ Full reference in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 | `refreshGracePeriodSeconds` | `60` | Proactively refresh tokens this many seconds before expiry. |
 | `maxRefreshTokenAgeSeconds` | `21600` | Heuristic max stored refresh-token lifetime (6h). Past this, the plugin treats the RT as expired without contacting the IdP — returns 401 to AJAX, full re-auth on navigations. Set `0` to disable. Tune to match your IdP's RT TTL. |
 | `rateLimit` | `100` | Requests/sec. Min `10`. |
+| `perSourceLoginRateLimit` | `0` (off) | Throttle OIDC auth events (authorization-code callback + login initiation) per external client source, auth events per minute. Keys and classifies the source by RemoteAddr only, never `X-Forwarded-For`, so a client cannot spoof it. Internal/loopback sources (proxies, in-cluster) are never throttled. `0` disables. RemoteAddr is the TCP peer. Behind a load balancer or CDN, the limiter keys on the proxy address: a private address is never throttled, and a public address puts every client in one shared bucket. |
 | `logLevel` | `info` | `debug`, `info`, `error`. |
 | `audience` | `clientID`, or `resource` if set | Custom access-token audience (Auth0 custom APIs). |
 | `resource` | none | RFC 8707 resource indicator, alternative to `audience` for supporting IdPs (see [docs/RFC8707.md](docs/RFC8707.md)). |
 | `strictAudienceValidation` | `false` | Reject mismatched audiences. **Set `true` in production.** |
 | `allowOpaqueTokens` / `requireTokenIntrospection` | `false` | Accept opaque access tokens via RFC 7662. |
+| `revocationURL` / `oidcEndSessionURL` / `introspectionURL` | `""` | Override the discovered revocation / end-session / introspection endpoints; take precedence when discovery omits them. |
+| `maxIdentifierLength` | `256` | Bound the post-sanitisation length of the bearer identity header (`X-Forwarded-User`). |
+| `bearerFailureWindowSeconds` | `60` | Rolling window (s) over which per-IP bearer 401s are counted toward the throttle. |
+| `bearerFailurePenaltySeconds` | `60` | Seconds an IP is kept in the 429 penalty box after the bearer failure threshold. |
 | `disableReplayDetection` | `false` | Disable JTI cache. Use Redis instead for multi-replica. |
 | `allowPrivateIPAddresses` | `false` | Permit private-IP `providerURL` (internal Keycloak, etc.). |
+| `allowUnauthenticatedPreflight` | `false` | Bypass auth for a genuine CORS preflight (`OPTIONS` + `Origin` + `Access-Control-Request-Method`); the response body is still discarded. Default requires auth for every `OPTIONS` request, preflight or not. |
 | `minimalHeaders` | `false` | Reduce forwarded headers (mitigates HTTP 431). |
 | `stripAuthCookies` | `false` | Strip OIDC cookies from backend hop (mitigates HTTP 431). |
 | `caCertPath` / `caCertPEM` | none | Trust an internal CA for the provider's TLS. |
@@ -160,6 +166,18 @@ Full reference in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
   `rateLimit` below 10, a missing `callbackURL`, or a non-HTTPS remote
   `providerURL` are rejected. Plaintext HTTP is permitted only for loopback
   hosts (local development).
+- **A `private_key_jwt` RSA key under 2048 bits now fails startup** instead
+  of signing locally and failing `invalid_client` at every token exchange
+  (RFC 7518 §3.3). Generate a 2048-bit-or-larger key before upgrading. No
+  override exists.
+- **A discovered `http://` endpoint under an `https://` `providerURL` is now
+  dropped**, not used as-is: the plugin refuses to send a client secret or
+  token over plaintext HTTP even when the IdP's own discovery document
+  advertises it that way. A dropped `token`, `jwks_uri`, or `authorization`
+  endpoint breaks login; a `SECURITY:`-tagged log line names the endpoint.
+  See [Discovered Endpoint
+  Validation](docs/CONFIGURATION.md#discovered-endpoint-validation). No
+  override exists.
 
 ### TLS termination at a load balancer
 
@@ -237,9 +255,10 @@ Hardening built in by default:
   `Authorization: Bearer` header arrive on the same request, the cookie path
   runs (safer against browser/extension/proxy bearer injection). Set
   `bearerOverridesCookie: true` for the AWS/GCP/Kubernetes convention.
-- **Replay protection preserved.** The bearer path skips the JTI **Set**
-  (so the same token can be reused) but the **Get** stays active —
-  `RevokeToken` still terminates a bearer token immediately.
+- **Revocation enforced.** No access-token JTI is recorded for replay;
+  `RevokeToken` (called from logout) blacklists the raw token (and a JWT's
+  `jti`), and both the JWT and the opaque bearer path reject a blacklisted
+  token.
 - **Excluded URLs strip Authorization.** When `enableBearerAuth=true`,
   excluded paths (e.g. `/health`, `/metrics`) get the `Authorization` header
   removed before forwarding so the token can't leak into public endpoint

access_token_unexpired_iat_optional_test.go

@@ -0,0 +1,49 @@
+package traefikoidc
+
+import (
+	"testing"
+	"time"
+)
+
+// FIX-27 regression test.
+//
+// accessTokenUnexpired (the lenient-audience-path time-claims re-check)
+// returned false whenever iat was absent, even though 8640451 made iat
+// OPTIONAL in jwt.Verify itself (R126: "Hard-requiring it here also
+// rejected otherwise-valid access ... tokens whose provider omits iat").
+// The two paths had drifted onto different contracts for the same claim.
+// A lenient (wrong-audience) access token without iat, in a session with
+// no ID token to corroborate it, was always forced to refresh or
+// re-authenticate, while the identical token with a matching audience
+// authenticated fine via the main jwt.Verify path.
+//
+// Fail-on-old: a syntactically valid, unexpired token with no iat is
+// rejected by accessTokenUnexpired (returns false).
+func TestAccessTokenUnexpired_IatOptional(t *testing.T) {
+	tm := &TraefikOidc{}
+	now := time.Now()
+
+	noIat := makeTestJWT(t, map[string]interface{}{
+		"exp": float64(now.Add(time.Hour).Unix()),
+		// intentionally no "iat", matching jwt.Verify's R126 contract
+	})
+	if !tm.accessTokenUnexpired(noIat) {
+		t.Error("a token with a valid exp and no iat must be accepted, matching jwt.Verify's iat-optional contract (R126/FIX-27)")
+	}
+}
+
+// TestAccessTokenUnexpired_IatStillBoundedWhenPresent is the positive
+// control: an iat far in the future (used-before-issued) must still be
+// rejected when iat IS present — the fix makes iat optional, not ignored.
+func TestAccessTokenUnexpired_IatStillBoundedWhenPresent(t *testing.T) {
+	tm := &TraefikOidc{}
+	now := time.Now()
+
+	futureIat := makeTestJWT(t, map[string]interface{}{
+		"exp": float64(now.Add(time.Hour).Unix()),
+		"iat": float64(now.Add(time.Hour).Unix()), // far in the future
+	})
+	if tm.accessTokenUnexpired(futureIat) {
+		t.Error("a present iat far in the future (used-before-issued) must still be rejected")
+	}
+}

audience_test.go

@@ -326,16 +326,12 @@ func TestAuth0Scenario1WithCustomAudience(t *testing.T) {
 	}
 
 	// Verify ID token validates against client_id
-	cleanupReplayCache()
-	initReplayCache()
 	err = ts.tOidc.VerifyToken(idToken)
 	if err != nil {
 		t.Errorf("ID token validation failed (should validate against client_id): %v", err)
 	}
 
 	// Verify access token validates against custom audience
-	cleanupReplayCache()
-	initReplayCache()
 	err = ts.tOidc.VerifyToken(accessToken)
 	if err != nil {
 		t.Errorf("Access token validation failed (should validate against custom audience): %v", err)
@@ -399,8 +395,6 @@ func TestAuth0Scenario2DefaultAudience(t *testing.T) {
 	}
 
 	// Verify ID token validates
-	cleanupReplayCache()
-	initReplayCache()
 	err = ts.tOidc.VerifyToken(idToken)
 	if err != nil {
 		t.Errorf("ID token validation failed: %v", err)
@@ -408,8 +402,6 @@ func TestAuth0Scenario2DefaultAudience(t *testing.T) {
 
 	// Access token won't have client_id in aud, so it will fail validation
 	// This is expected for scenario 2 - the session validation relies on ID token
-	cleanupReplayCache()
-	initReplayCache()
 	err = ts.tOidc.VerifyToken(accessToken)
 	if err == nil {
 		t.Logf("Access token validation passed (unexpected but OK if client_id is in aud array)")
@@ -460,8 +452,6 @@ func TestAuth0Scenario3OpaqueAccessToken(t *testing.T) {
 	opaqueAccessToken := "opaque_access_token_random_string_12345"
 
 	// Verify ID token validates
-	cleanupReplayCache()
-	initReplayCache()
 	err = ts.tOidc.VerifyToken(idToken)
 	if err != nil {
 		t.Errorf("ID token validation failed: %v", err)
@@ -524,8 +514,6 @@ func TestAuth0AudienceArrayValidation(t *testing.T) {
 	}
 
 	// Should validate successfully - custom audience is in the array
-	cleanupReplayCache()
-	initReplayCache()
 	err = ts.tOidc.VerifyToken(accessToken)
 	if err != nil {
 		t.Errorf("Access token with audience array should validate when custom audience is present: %v", err)
@@ -558,8 +546,6 @@ func TestAuth0MismatchedAudience(t *testing.T) {
 	}
 
 	// Should fail validation - audience doesn't match
-	cleanupReplayCache()
-	initReplayCache()
 	err = ts.tOidc.VerifyToken(accessToken)
 	if err == nil {
 		t.Error("Access token with wrong audience should fail validation")
@@ -669,8 +655,6 @@ func TestIDTokenAlwaysValidatesAgainstClientID(t *testing.T) {
 	}
 
 	// Should validate successfully - ID tokens are checked against client_id
-	cleanupReplayCache()
-	initReplayCache()
 	err = ts.tOidc.VerifyToken(idToken)
 	if err != nil {
 		t.Errorf("ID token should validate against client_id even when custom audience is configured: %v", err)
@@ -692,8 +676,6 @@ func TestIDTokenAlwaysValidatesAgainstClientID(t *testing.T) {
 	}
 
 	// Should fail - ID tokens must have client_id as audience
-	cleanupReplayCache()
-	initReplayCache()
 	err = ts.tOidc.VerifyToken(wrongIDToken)
 	if err == nil {
 		t.Error("ID token with custom audience (not client_id) should fail validation")

auth_flow.go

@@ -1,12 +1,37 @@
 package traefikoidc
 
 import (
+	"errors"
 	"fmt"
 	"net/http"
+	"net/url"
 	"strings"
 	"time"
 )
 
+// redactAuthorizeURLForLog removes the remaining security-sensitive query
+// values from the provider authorize URL before it is logged. It builds on
+// redactCallbackURL (url_helpers.go, R153), which strips "code" and
+// "state" but was written for the callback URL and does not know about
+// the nonce or PKCE code_challenge the authorize URL also carries — so
+// logging redactCallbackURL(authURL) alone would still leak the nonce
+// (FIX-29 correction of the R153 claim).
+func redactAuthorizeURLForLog(rawURL string) string {
+	redacted := redactCallbackURL(rawURL)
+	u, err := url.Parse(redacted)
+	if err != nil {
+		return redacted
+	}
+	q := u.Query()
+	for _, k := range []string{"nonce", "code_challenge"} {
+		if q.Get(k) != "" {
+			q.Set(k, "[REDACTED]")
+		}
+	}
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
 // validateRedirectCount checks if redirect limit is exceeded and handles the error
 func (t *TraefikOidc) validateRedirectCount(session *SessionData, rw http.ResponseWriter, req *http.Request) error {
 	const maxRedirects = 5
@@ -14,6 +39,16 @@ func (t *TraefikOidc) validateRedirectCount(session *SessionData, rw http.Respon
 	if redirectCount >= maxRedirects {
 		t.logger.Errorf("Maximum redirect limit (%d) exceeded, possible redirect loop detected", maxRedirects)
 		session.ResetRedirectCount()
+		// Persist the reset so the NEXT request starts at 0 and can
+		// attempt auth again. Without Save, the reset only touched the
+		// in-memory session value (dirty flag set but never flushed): the
+		// cookie still carried the old count, so every subsequent
+		// request re-observed redirect_count==max and the user was
+		// hard-locked on 508 for the whole session with no recovery
+		// (R123).
+		if err := session.Save(req, rw); err != nil {
+			t.logger.Errorf("Failed to save session after redirect reset: %v", err)
+		}
 		t.sendErrorResponse(rw, req, "Authentication failed: Too many redirects", http.StatusLoopDetected)
 		return fmt.Errorf("redirect limit exceeded")
 	}
@@ -68,9 +103,34 @@ func (t *TraefikOidc) prepareSessionForAuthentication(session *SessionData, csrf
 //   - req: The HTTP request initiating authentication.
 //   - session: The session data to prepare for authentication.
 //   - redirectURL: The pre-calculated callback URL (redirect_uri) for this middleware instance.
+//
+// rateLimitPerSourceAuth applies the (optional) per-external-source auth
+// throttle at an OIDC gate. Returns true if the request was already
+// answered with 429 and the caller must return. No-op when the limiter is
+// disabled (PerSourceLoginRateLimit <= 0) or the source is internal.
+func (t *TraefikOidc) rateLimitPerSourceAuth(rw http.ResponseWriter, req *http.Request) bool {
+	if t.perSourceLimiter == nil {
+		return false
+	}
+	if t.perSourceLimiter.allow(req) {
+		return false
+	}
+	rw.Header().Set("Retry-After", "1")
+	t.sendErrorResponse(rw, req, "Too many authentication attempts, please try again shortly", http.StatusTooManyRequests)
+	return true
+}
+
 func (t *TraefikOidc) defaultInitiateAuthentication(rw http.ResponseWriter, req *http.Request, session *SessionData, redirectURL string) {
 	t.logger.Debugf("Initiating new OIDC authentication flow for request: %s", req.URL.RequestURI())
 
+	// Per-external-source throttle on login initiation: a single host
+	// flooding the route with auth starts shouldn't be able to spin up an
+	// unbounded number of IdP round-trips or wear the shared token-origin
+	// bucket down for everyone (R185).
+	if t.rateLimitPerSourceAuth(rw, req) {
+		return
+	}
+
 	// Check and handle redirect limits
 	if err := t.validateRedirectCount(session, rw, req); err != nil {
 		return
@@ -97,9 +157,42 @@ func (t *TraefikOidc) defaultInitiateAuthentication(rw http.ResponseWriter, req
 		return
 	}
 
+	// Build the provider authorize URL BEFORE mutating the session. A URL-
+	// build failure must not clear a valid existing session, and must not
+	// emit an empty-Location redirect (browsers reload the current page,
+	// re-entering this flow and bumping the redirect count until the hard
+	// 508). Fail closed with an explicit status instead (R142).
+	authURL := t.buildAuthURL(redirectURL, csrfToken, nonce, codeChallenge)
+	if authURL == "" {
+		t.logger.Errorf("Failed to build provider authorize URL; aborting login flow")
+		http.Error(rw, "Failed to build provider authorize URL", http.StatusInternalServerError)
+		return
+	}
+
+	// When dynamic client registration is enabled but has not yet produced a
+	// client_id (registration pending or failed), forging an authorize URL
+	// with client_id="" would send the user to the provider on a broken
+	// flow. Fail with a clear status instead of redirecting. This guard
+	// must run BEFORE prepareSessionForAuthentication re-seeds the session:
+	// re-seeding (and the save that follows) would otherwise mutate and
+	// persist the session even though we are about to answer 503 with no
+	// redirect — discarding any existing session state for no reason (R163).
+	// Snapshot clientID under metadataMu: DCR rewrites it at runtime (R137).
+	clientID, _, _, _, _ := t.clientCredentials()
+	if t.dcrConfig != nil && t.dcrConfig.Enabled && clientID == "" {
+		t.logger.Errorf("OIDC dynamic client registration has not produced a client_id; refusing to redirect to provider")
+		http.Error(rw, "Identity provider registration pending", http.StatusServiceUnavailable)
+		return
+	}
+
 	// Clear existing session data and set new authentication state
 	t.prepareSessionForAuthentication(session, csrfToken, nonce, codeVerifier, req.URL.RequestURI())
 
+	// Persist the redirect_uri so the callback reuses the exact value sent
+	// to the IdP, instead of rebuilding it from the (client-affectable)
+	// callback request's X-Forwarded-Host (R136).
+	session.SetRedirectURL(redirectURL)
+
 	session.MarkDirty()
 
 	if err := session.Save(req, rw); err != nil {
@@ -108,12 +201,17 @@ func (t *TraefikOidc) defaultInitiateAuthentication(rw http.ResponseWriter, req
 		return
 	}
 
-	t.logger.Debugf("Session saved before redirect. CSRF: %s, Nonce: %s",
-		csrfToken, nonce)
+	// CSRF/state and nonce are single-use security credentials; do not log
+	// them in the clear (FIX-29 correction of the R153 redaction claim).
+	t.logger.Debug("Session saved before redirect")
 
-	authURL := t.buildAuthURL(redirectURL, csrfToken, nonce, codeChallenge)
-	t.logger.Debugf("Redirecting user to OIDC provider: %s", authURL)
+	t.logger.Debugf("Redirecting user to OIDC provider: %s", redactAuthorizeURLForLog(authURL))
 
+	// 302s into the IdP must not be heuristically cacheable (RFC 7234):
+	// a stale, cached redirect could replay the pre-re-authentication URL.
+	// Every other auth response sets no-store; these redirects were missed
+	// (R147).
+	rw.Header().Set("Cache-Control", "no-store")
 	http.Redirect(rw, req, authURL, http.StatusFound)
 }
 
@@ -124,7 +222,31 @@ func (t *TraefikOidc) defaultInitiateAuthentication(rw http.ResponseWriter, req
 //   - rw: The HTTP response writer.
 //   - req: The callback request containing authorization code and state.
 //   - redirectURL: The fully qualified callback URL (used in the token exchange request).
+//
+// clearOneTimeAuthState clears the one-time CSRF/nonce/PKCE-verifier after a
+// callback that consumed the authorization code but then failed, and persists
+// the cleared state. Without it the failed session stays in a pending-auth
+// state and a retried callback would re-exchange a fresh code before failing
+// again. Mirrors the cleanup on the exchange-failure / empty-access-token
+// paths (R134).
+func (t *TraefikOidc) clearOneTimeAuthState(session *SessionData, req *http.Request, rw http.ResponseWriter) {
+	session.SetCSRF("")
+	session.SetNonce("")
+	session.SetCodeVerifier("")
+	if saveErr := session.Save(req, rw); saveErr != nil {
+		t.logger.Errorf("Failed to save session after callback failure: %v", saveErr)
+	}
+}
+
 func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request, redirectURL string) {
+	// Per-external-source throttle on the authorization-code callback: this
+	// is where the one-time code exchange (server round-trip + token
+	// cache write) happens, so a single source can't brute-force
+	// repeated code exchanges or drown the shared limiter (R185).
+	if t.rateLimitPerSourceAuth(rw, req) {
+		return
+	}
+
 	session, err := t.sessionManager.GetSession(req)
 	if err != nil {
 		t.logger.Errorf("Session error during callback: %v", err)
@@ -133,15 +255,28 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 	}
 	defer session.returnToPoolSafely()
 
-	t.logger.Debugf("Handling callback, URL: %s", req.URL.String())
+	t.logger.Debugf("Handling callback, URL: %s", redactCallbackURL(req.URL.String()))
 
 	if req.URL.Query().Get("error") != "" {
 		errorDescription := req.URL.Query().Get("error_description")
 		if errorDescription == "" {
 			errorDescription = req.URL.Query().Get("error")
 		}
-		t.logger.Errorf("Authentication error from provider during callback: %s - %s", req.URL.Query().Get("error"), errorDescription)
-		t.sendErrorResponse(rw, req, fmt.Sprintf("Authentication error from provider: %s", errorDescription), http.StatusBadRequest)
+		// error / error_description are attacker-controlled query params.
+		// Sanitize before logging and before echoing back to the client:
+		// an embedded newline would inject a forged line into (especially
+		// structured) logs, and unbounded length would bloat the log and
+		// the error response (R145).
+		sanitizeErr := func(s string) string {
+			s = strings.NewReplacer("\n", " ", "\r", " ").Replace(s)
+			const maxErrLen = 512
+			if len(s) > maxErrLen {
+				s = s[:maxErrLen]
+			}
+			return s
+		}
+		t.logger.Errorf("Authentication error from provider during callback: %s - %s", sanitizeErr(req.URL.Query().Get("error")), sanitizeErr(errorDescription))
+		t.sendErrorResponse(rw, req, fmt.Sprintf("Authentication error from provider: %s", sanitizeErr(errorDescription)), http.StatusBadRequest)
 		return
 	}
 
@@ -155,7 +290,7 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 	csrfToken := session.GetCSRF()
 	if csrfToken == "" {
 		t.logger.Errorf("CSRF token missing in session during callback. Authenticated: %v, Request URL: %s",
-			session.GetAuthenticated(), req.URL.String())
+			session.GetAuthenticated(), redactCallbackURL(req.URL.String()))
 
 		cookie, err := req.Cookie("_oidc_raczylo_m")
 		if err != nil {
@@ -168,7 +303,7 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 		return
 	}
 
-	if state != csrfToken {
+	if !constantTimeStringCompare(state, csrfToken) {
 		t.logger.Error("State parameter does not match CSRF token in session during callback")
 		t.sendErrorResponse(rw, req, "Invalid state parameter (CSRF mismatch)", http.StatusBadRequest)
 		return
@@ -188,15 +323,49 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 		return
 	}
 
+	// Use the redirect_uri persisted at initiate time (must match what was
+	// sent to the IdP's authorize endpoint). Fall back to the rebuilt one
+	// only for pre-existing sessions that predate R136 (R136).
+	if stored := session.GetRedirectURL(); stored != "" {
+		redirectURL = stored
+	}
+
 	tokenResponse, err := t.tokenExchanger.ExchangeCodeForToken(req.Context(), "authorization_code", code, redirectURL, codeVerifier)
 	if err != nil {
 		t.logger.Errorf("Failed to exchange code for token during callback: %v", err)
+		// Invalidate the one-time auth state and persist it so a
+		// partially-failed flow cannot be continued: the authorization code
+		// may still be unconsumed at the provider, so a replayed callback
+		// must re-authenticate rather than revalidate a stale
+		// state/nonce/code_verifier. Mirrors the cleanup on success.
+		t.clearOneTimeAuthState(session, req, rw)
 		t.sendErrorResponse(rw, req, "Authentication failed: Could not exchange code for token", http.StatusInternalServerError)
 		return
 	}
 
+	if tokenResponse.AccessToken == "" {
+		t.logger.Errorf("Token endpoint returned no access token during callback")
+		t.clearOneTimeAuthState(session, req, rw)
+		t.sendErrorResponse(rw, req, "Authentication failed: Token endpoint returned no access token", http.StatusInternalServerError)
+		return
+	}
+
 	if err = t.verifyToken(tokenResponse.IDToken); err != nil {
 		t.logger.Errorf("Failed to verify id_token during callback: %v", err)
+		t.clearOneTimeAuthState(session, req, rw)
+		if errors.Is(err, ErrRateLimitExceeded) {
+			// Rate-limit exhaustion must be a 429, not a generic 500: a
+			// single source's burst currently degrades every user's
+			// callback to "server error" (R179). No Retry-After: by this
+			// point clearOneTimeAuthState has already destroyed the
+			// csrf/nonce/code_verifier and the authorization code has
+			// already been redeemed at the IdP, so a client that honors
+			// Retry-After and retries this exact callback URL is
+			// guaranteed to hit "CSRF token missing in session" instead
+			// of a successful retry (FIX-32). The user must restart login.
+			t.sendErrorResponse(rw, req, "Authentication failed: Too many requests, please retry", http.StatusTooManyRequests)
+			return
+		}
 		t.sendErrorResponse(rw, req, "Authentication failed: Could not verify ID token", http.StatusInternalServerError)
 		return
 	}
@@ -204,6 +373,7 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 	claims, err := t.extractClaimsFunc(tokenResponse.IDToken)
 	if err != nil {
 		t.logger.Errorf("Failed to extract claims during callback: %v", err)
+		t.clearOneTimeAuthState(session, req, rw)
 		t.sendErrorResponse(rw, req, "Authentication failed: Could not extract claims from token", http.StatusInternalServerError)
 		return
 	}
@@ -211,41 +381,57 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 	nonceClaim, ok := claims["nonce"].(string)
 	if !ok || nonceClaim == "" {
 		t.logger.Error("Nonce claim missing in id_token during callback")
-		t.sendErrorResponse(rw, req, "Authentication failed: Nonce missing in token", http.StatusInternalServerError)
+		t.clearOneTimeAuthState(session, req, rw)
+		t.sendErrorResponse(rw, req, "Authentication failed: Nonce missing in token", http.StatusBadRequest)
 		return
 	}
 
 	sessionNonce := session.GetNonce()
 	if sessionNonce == "" {
 		t.logger.Error("Nonce not found in session during callback")
-		t.sendErrorResponse(rw, req, "Authentication failed: Nonce missing in session", http.StatusInternalServerError)
+		t.clearOneTimeAuthState(session, req, rw)
+		t.sendErrorResponse(rw, req, "Authentication failed: Nonce missing in session", http.StatusBadRequest)
 		return
 	}
 
-	if nonceClaim != sessionNonce {
+	if !constantTimeStringCompare(nonceClaim, sessionNonce) {
 		t.logger.Error("Nonce claim does not match session nonce during callback")
-		t.sendErrorResponse(rw, req, "Authentication failed: Nonce mismatch", http.StatusInternalServerError)
+		t.clearOneTimeAuthState(session, req, rw)
+		t.sendErrorResponse(rw, req, "Authentication failed: Nonce mismatch", http.StatusBadRequest)
 		return
 	}
 
 	// Extract user identifier from the configured claim (defaults to "email" for backward compatibility)
-	userIdentifier, _ := claims[t.userIdentifierClaim].(string)
+	userIdentifier, _ := claimScalarString(claims[t.userIdentifierClaim])
 	if userIdentifier == "" {
 		// Try "sub" as fallback since it's required by OIDC spec
 		if t.userIdentifierClaim != "sub" {
-			userIdentifier, _ = claims["sub"].(string)
+			userIdentifier, _ = claimScalarString(claims["sub"])
 		}
 		if userIdentifier == "" {
 			t.logger.Errorf("User identifier claim '%s' missing or empty in token during callback", t.userIdentifierClaim)
+			t.clearOneTimeAuthState(session, req, rw)
 			t.sendErrorResponse(rw, req, "Authentication failed: User identifier missing in token", http.StatusInternalServerError)
 			return
 		}
 		t.logger.Debugf("Configured claim '%s' not found, using 'sub' claim as fallback", t.userIdentifierClaim)
 	}
 
+	// Validate user authorization. When the identity is an email, require the
+	// IdP not to have explicitly flagged it as unverified — an unverified
+	// address must not satisfy an email/domain allowlist (see
+	// emailIdentityPermitted).
+	if !emailIdentityPermitted(userIdentifier, claims) {
+		t.logger.Errorf("User email not verified during callback, rejecting email-based authorization: %s", userIdentifier)
+		t.clearOneTimeAuthState(session, req, rw)
+		t.sendErrorResponse(rw, req, "Authentication failed: Email not verified", http.StatusForbidden)
+		return
+	}
+
 	// Validate user authorization
 	if !t.isAllowedUser(userIdentifier) {
 		t.logger.Errorf("User not authorized during callback: %s", userIdentifier)
+		t.clearOneTimeAuthState(session, req, rw)
 		t.sendErrorResponse(rw, req, "Authentication failed: User not authorized", http.StatusForbidden)
 		return
 	}
@@ -282,6 +468,8 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 	}
 
 	t.logger.Debugf("Callback successful, redirecting to %s", redirectPath)
+	// no-store so the post-auth redirect isn't cached and replayed (R147).
+	rw.Header().Set("Cache-Control", "no-store")
 	http.Redirect(rw, req, redirectPath, http.StatusFound)
 }
 

auth_flow_behaviour_test.go

@@ -957,8 +957,10 @@ func (s *AuthFlowBehaviourSuite) TestHandleCallback_NonceMismatch() {
 	// Call handleCallback
 	s.tOidc.handleCallback(rw2, req2, "https://example.com/callback")
 
-	// Should return internal server error due to nonce mismatch
-	s.Equal(http.StatusInternalServerError, rw2.Code)
+	// R161: nonce mismatch is a client-side authorization-request
+	// integrity failure (same class as state/CSRF mismatch), so it returns
+	// 400, not 500.
+	s.Equal(http.StatusBadRequest, rw2.Code)
 }
 
 // TestHandleCallback_UserNotAuthorized tests callback when user is not authorized

autocleanup.go

@@ -28,6 +28,12 @@ type BackgroundTask struct {
 	stopped    int32 // 1 = stopped, 0 = not stopped
 	started    int32 // 1 = started, 0 = not started
 	doneClosed int32 // 1 = doneChan closed, 0 = not closed
+	// startRefused is set when Start's circuit-breaker or concurrency-limit
+	// early-return fires (FIX-19). started stays 0 and stopped stays 0 in
+	// that case, which is indistinguishable from "registered but Start has
+	// not been called yet" — RegisterBackgroundTask needs the distinction to
+	// know this task's slot is actually free to reuse.
+	startRefused int32 // 1 = a Start call was refused, 0 = never refused
 }
 
 // NewBackgroundTask creates a new background task with the specified configuration.
@@ -46,6 +52,12 @@ func NewBackgroundTask(name string, interval time.Duration, taskFunc func(), log
 	if len(wg) > 0 {
 		externalWG = wg[0]
 	}
+	// run() uses time.NewTicker(interval), which panics for d <= 0 inside
+	// the started goroutine (autocleanup.go:186), crashing the whole
+	// process on a misconfigured interval. Normalize here (R149).
+	if interval <= 0 {
+		interval = time.Minute
+	}
 	return &BackgroundTask{
 		name:       name,
 		interval:   interval,
@@ -81,6 +93,7 @@ func (bt *BackgroundTask) Start() {
 			if bt.logger != nil {
 				bt.logger.Debugf("Cannot start task %s: %v (circuit breaker protection working as expected)", bt.name, err)
 			}
+			atomic.StoreInt32(&bt.startRefused, 1)
 			// Close doneChan since the task won't run
 			if atomic.CompareAndSwapInt32(&bt.doneClosed, 0, 1) {
 				close(bt.doneChan)
@@ -88,8 +101,21 @@ func (bt *BackgroundTask) Start() {
 			return
 		}
 
-		// Reserve the task slot immediately when starting
-		registry.cb.OnTaskStart(bt.name)
+		// Reserve the task slot immediately when starting. OnTaskStart
+		// is the authoritative concurrency gate (R165): it returns false
+		// if maxConcurrent is already reached, in which case this task
+		// must not launch run() (its slot was not taken).
+		if !registry.cb.OnTaskStart(bt.name) {
+			if bt.logger != nil {
+				bt.logger.Debugf("Cannot start task %s: concurrency limit reached, slot not acquired", bt.name)
+			}
+			atomic.StoreInt32(&bt.startRefused, 1)
+			// Close doneChan since the task won't run
+			if atomic.CompareAndSwapInt32(&bt.doneClosed, 0, 1) {
+				close(bt.doneChan)
+			}
+			return
+		}
 
 		atomic.StoreInt32(&bt.started, 1)
 		bt.internalWG.Add(1)
@@ -114,6 +140,14 @@ func (bt *BackgroundTask) Stop() {
 			if atomic.CompareAndSwapInt32(&bt.doneClosed, 0, 1) {
 				close(bt.doneChan)
 			}
+			// Also close stopChan (R117): a concurrent Start may be in-flight
+			// and about to launch run(). Signaling stopChan lets it exit at
+			// the next stop check instead of leaking the goroutine and its
+			// circuit-breaker slot (taken by OnTaskStart but never released).
+			func() {
+				defer func() { _ = recover() }() // safe if already closed
+				close(bt.stopChan)
+			}()
 			return
 		}
 
@@ -134,18 +168,37 @@ func (bt *BackgroundTask) Stop() {
 		// This avoids the race condition with WaitGroup
 		select {
 		case <-bt.doneChan:
-			// Normal completion
+			// Normal completion: the goroutine has returned, so it is safe
+			// to wait on the WaitGroup.
+			bt.internalWG.Wait()
 		case <-time.After(5 * time.Second):
+			// The task goroutine is still running (its taskFunc is blocked or
+			// long-lived). Do NOT wait on the WaitGroup here — that would
+			// block Stop() (and shutdown) for as long as the task runs.
+			// Return now; the goroutine is reaped when it completes.
 			if bt.logger != nil {
 				bt.logger.Errorf("Timeout waiting for background task %s to stop", bt.name)
 			}
 		}
-
-		// Wait for the internal WaitGroup synchronously after doneChan signals
-		bt.internalWG.Wait()
 	})
 }
 
+// safeRunTask executes the task function, recovering from any panic so that a
+// single panicking run does not permanently kill the background goroutine and its
+// periodic loop. Under yaegi (where this plugin runs) unexpected panics are more
+// likely, and a silently-dead background task (metadata refresh, autocleanup,
+// memory monitor) would otherwise stop forever with no log or restart.
+func (bt *BackgroundTask) safeRunTask() {
+	defer func() {
+		if r := recover(); r != nil {
+			if bt.logger != nil {
+				bt.logger.Errorf("Background task %s panicked (recovered): %v", bt.name, r)
+			}
+		}
+	}()
+	bt.taskFunc()
+}
+
 // run is the main loop for the background task.
 // It executes the task function immediately, then periodically
 // until the stop signal is received.
@@ -187,7 +240,7 @@ func (bt *BackgroundTask) run() {
 		}
 		return
 	default:
-		bt.taskFunc()
+		bt.safeRunTask()
 	}
 
 	for {
@@ -206,7 +259,7 @@ func (bt *BackgroundTask) run() {
 				}
 				return
 			default:
-				bt.taskFunc()
+				bt.safeRunTask()
 			}
 		case <-bt.stopChan:
 			if bt.logger != nil {
@@ -329,9 +382,30 @@ func (cb *TaskCircuitBreaker) CanCreateTask(taskName string) error {
 	}
 }
 
-// OnTaskStart records a task starting execution
-func (cb *TaskCircuitBreaker) OnTaskStart(taskName string) {
-	atomic.AddInt32(&cb.concurrentTasks, 1)
+// OnTaskStart records a task starting execution. It atomically reserves a
+// concurrency slot and returns whether one was available. The reservation
+// is fundamental (R165): CanCreateTask's limit check is only advisory —
+// it is also called by RegisterTask without starting the task — so a
+// check-then-act TOCTOU meant two concurrently starting tasks could both
+// read current < limit and then both start, letting live tasks exceed
+// maxConcurrent and defeating the DoS backstop. OnTaskStart is the
+// single commit point, so it enforces maxConcurrent here via a CAS loop:
+// only maxConcurrent tasks can hold slots at once. BackgroundTask.Start
+// aborts (without launching run) when this returns false.
+func (cb *TaskCircuitBreaker) OnTaskStart(taskName string) bool {
+	max := atomic.LoadInt32(&cb.maxConcurrent)
+	for {
+		current := atomic.LoadInt32(&cb.concurrentTasks)
+		if current >= max {
+			if cb.logger != nil {
+				cb.logger.Debug("Concurrent task limit reached, refusing slot for: %s", taskName)
+			}
+			return false
+		}
+		if atomic.CompareAndSwapInt32(&cb.concurrentTasks, current, current+1) {
+			break
+		}
+	}
 	cb.tasksMu.Lock()
 	cb.activeTasks[taskName] = struct{}{}
 	cb.tasksMu.Unlock()
@@ -342,6 +416,7 @@ func (cb *TaskCircuitBreaker) OnTaskStart(taskName string) {
 		cb.logger.Debug("Task started, concurrent count: %d, task: %s",
 			atomic.LoadInt32(&cb.concurrentTasks), taskName)
 	}
+	return true
 }
 
 // OnTaskComplete records a task completing execution
@@ -463,10 +538,13 @@ func (tr *TaskRegistry) RegisterTask(name string, task *BackgroundTask) error {
 	tr.mu.Lock()
 	defer tr.mu.Unlock()
 
-	// Task execution tracking is now handled in the run() method
-
 	tr.tasks[name] = task
-	tr.cb.OnTaskSuccess(name)
+	// Execution tracking (the circuit-breaker concurrent count) is handled by
+	// Start()/run(): Start() reserves a slot via OnTaskStart and run() releases
+	// it via OnTaskComplete. Do NOT also OnTaskSuccess here — that would
+	// double-count every registered task (+1 on register, +1 on Start, -1 on
+	// stop), leaking one slot per task and eventually blocking all background
+	// task creation at the concurrency limit.
 
 	if tr.logger != nil {
 		tr.logger.Debug("Registered background task: %s", name)
@@ -499,9 +577,18 @@ func (tr *TaskRegistry) GetTask(name string) (*BackgroundTask, bool) {
 	return task, exists
 }
 
-// StopAllTasks stops all registered background tasks
+// StopAllTasks stops all registered background tasks.
+//
+// Tasks can live in two places: those registered directly via
+// TaskRegistry.RegisterTask (stored in tr.tasks) and process-global
+// singletons created via TaskRegistry.CreateSingletonTask, which delegate to
+// GetResourceManager().RegisterBackgroundTask and store the task in the
+// ResourceManager's registry (see CreateSingletonTask below) — NOT in
+// tr.tasks. Stop both so neither a direct task nor a singleton task leaks its
+// ticker goroutine past the last Close.
 func (tr *TaskRegistry) StopAllTasks() {
-	// First, copy the tasks map to avoid deadlock with GetTaskCount()
+	// First, stop tasks registered directly in this registry.
+	// Copy the tasks map to avoid deadlock with GetTaskCount().
 	tr.mu.Lock()
 	tasksCopy := make(map[string]*BackgroundTask, len(tr.tasks))
 	for name, task := range tr.tasks {
@@ -511,13 +598,15 @@ func (tr *TaskRegistry) StopAllTasks() {
 	tr.tasks = make(map[string]*BackgroundTask)
 	tr.mu.Unlock()
 
-	// Now stop all tasks without holding the lock
-	for name, task := range tasksCopy {
+	for _, task := range tasksCopy {
 		task.Stop()
-		if tr.logger != nil {
-			tr.logger.Debug("Stopped background task during shutdown: %s", name)
-		}
 	}
+
+	// Then stop process-global singleton tasks, which live in the
+	// ResourceManager's registry, not in tr.tasks (otherwise the singleton
+	// task teardown would be a silent no-op and leak every singleton task's
+	// ticker goroutine past the last Close).
+	GetResourceManager().StopAllTasks()
 }
 
 // GetTaskCount returns the number of active tasks
@@ -721,9 +810,14 @@ func (mm *TaskMemoryMonitor) checkForMemoryIssues(stats TaskMemoryStats) {
 	historyLen := len(mm.statsHistory)
 	if historyLen >= 2 {
 		prev := mm.statsHistory[historyLen-2]
-		heapGrowth := float64(stats.HeapAlloc) / float64(prev.HeapAlloc)
-		if heapGrowth > 2.0 && stats.NumGC == prev.NumGC {
-			mm.logger.Infof("Potential memory leak: heap grew %.2fx without GC", heapGrowth)
+		// Guard against div-by-zero (prev.HeapAlloc == 0) which would make
+		// heapGrowth == +Inf and fire a spurious "memory leak" alert for a
+		// first-ever measurement (R103).
+		if prev.HeapAlloc > 0 {
+			heapGrowth := float64(stats.HeapAlloc) / float64(prev.HeapAlloc)
+			if heapGrowth > 2.0 && stats.NumGC == prev.NumGC {
+				mm.logger.Infof("Potential memory leak: heap grew %.2fx without GC", heapGrowth)
+			}
 		}
 	}
 	mm.mu.RUnlock()

azure_oidc_test.go

@@ -265,14 +265,14 @@ func TestAzureOIDCRegression(t *testing.T) {
 		rs := (&requestState{}).captureSession(session)
 		authenticated, needsRefresh, expired := tOidc.validateAzureTokensRS(rs)
 
-		// Should not be authenticated due to validation failure
+		// Should not be authenticated due to validation failure, and with no
+		// refresh token and no tokens to probe, should not claim an expiry
+		// state (matches the standard path: unauthenticated, no refresh).
 		if authenticated {
 			t.Error("Should not be authenticated when token validation fails")
 		}
-
-		// Should be marked as expired since no tokens work
-		if !expired && !needsRefresh {
-			t.Error("Should be marked as needing refresh or expired when validation fails")
+		if needsRefresh || expired {
+			t.Error("With no refresh token and no tokens to probe, should be (false,false,false)")
 		}
 
 		// Verify CSRF token is still preserved in session
@@ -691,7 +691,7 @@ func TestValidateAzureTokensEdgeCases(t *testing.T) {
 				return session
 			},
 			expectedAuth:    false,
-			expectedRefresh: true,
+			expectedRefresh: false,
 			expectedExpired: false,
 			description:     "Unauthenticated Azure session without refresh token",
 		},
@@ -725,10 +725,10 @@ func TestValidateAzureTokensEdgeCases(t *testing.T) {
 				session.SetAccessToken("opaque_access_token_longer_than_minimum") // Not JWT format but long enough
 				return session
 			},
-			expectedAuth:    true,
+			expectedAuth:    false,
 			expectedRefresh: false,
-			expectedExpired: false,
-			description:     "Azure session with opaque access token",
+			expectedExpired: true,
+			description:     "Azure session with opaque access token but NO ID token fails closed (no unverified auth, R99)",
 		},
 		{
 			name: "AuthenticatedWithBothTokensInvalid",

bearer_auth.go

@@ -12,8 +12,13 @@
 //   - iat upper-age cap bounds clock-skew / forever-token abuse.
 //   - Multi-audience tokens require matching azp.
 //   - Per-IP 401 throttle returns 429 + Retry-After after a threshold.
-//   - JTI Set is suppressed (skipReplayMarking) but JTI Get stays — revoked
-//     tokens (RevokeToken adds to blacklist) are still rejected.
+//   - No path writes an access-token JTI to a replay cache (FIX-17 removed
+//     that writer; the only JTI replay tracking left is for backchannel
+//     logout tokens, logout.go checkAndMarkLogoutJTIProcessed). RevokeToken
+//     (called from logout) still blacklists the raw token and, for a JWT,
+//     its jti; both the JWT and opaque-introspection bearer paths check
+//     that blacklist before accepting a token, so revocation stays
+//     effective without replay-detection overhead.
 //   - Identifier is read from BearerIdentifierClaim (default "sub"), never
 //     from UserIdentifierClaim, to avoid the unverified-email spoofing path.
 //   - Identifier is sanitized: length cap, control chars, bidi-override,
@@ -93,6 +98,10 @@ const (
 type bearerError struct {
 	kind   bearerErrorKind
 	reason string
+	// retryAfter carries the actual remaining penalty when known (e.g. the
+	// per-IP penalty box), so writeBearerError emits the true value instead
+	// of the full configured penalty.
+	retryAfter time.Duration
 }
 
 func (e *bearerError) Error() string { return e.reason }
@@ -110,6 +119,32 @@ type joseHeader struct {
 	Typ string `json:"typ"`
 }
 
+// joseHeaderWellFormed reports whether token is structurally a JWT: exactly
+// two dot-separated segments whose header decodes as a JSON JOSE header.
+// It intentionally applies NO alg/kid policy (unlike parseBearerJOSEHeader)
+// so the JWT-vs-opaque routing gate classifies purely on structure: a
+// structurally-valid JWT with a disallowed alg stays on the JWT path
+// (where local policy rejects it), while an opaque token whose two dots
+// are coincidental falls through to opaque introspection (R166).
+func joseHeaderWellFormed(token string) bool {
+	dot := strings.IndexByte(token, '.')
+	if dot <= 0 {
+		return false
+	}
+	if strings.Count(token[dot+1:], ".") != 1 {
+		return false
+	}
+	raw, err := base64.RawURLEncoding.DecodeString(token[:dot])
+	if err != nil {
+		raw, err = base64.URLEncoding.DecodeString(token[:dot])
+		if err != nil {
+			return false
+		}
+	}
+	var hdr joseHeader
+	return json.Unmarshal(raw, &hdr) == nil
+}
+
 // parseBearerJOSEHeader decodes the first JWT segment for early alg/kid pinning.
 // Does not touch the payload or signature — those are the verifier's job.
 // Returns nil on success; *bearerError on rejection so the handler can map
@@ -153,19 +188,22 @@ func parseBearerJOSEHeader(token string) *bearerError {
 // header value, or "" if the rune is acceptable. Shared core of the bearer-path
 // identifier sanitizer and the cookie-path header claim sanitizer: rejects
 // control chars (CRLF/header injection), Unicode bidi-override runes (RTL
-// spoofing of admin UI / SIEM), and the delimiters , ; = (a comma in a group
-// name would inject extra entries into a comma-joined header).
+// spoofing of admin UI / SIEM), and the delimiters , ; = plus the bracketing
+// characters " { } — each of these in a group name / identifier would break a
+// downstream comma-joined list or a naive CSV/JSON-style parser consuming the
+// header (a comma would inject extra entries into a comma-joined header).
 func headerClaimRuneReason(r rune) string {
 	if reason := headerInjectionRuneReason(r); reason != "" {
 		return reason
 	}
-	// The , ; = delimiters are only unsafe for values placed into delimited or
-	// list contexts (a comma-joined header, or an identifier downstreams may
-	// split). They are valid in arbitrary single header values, so this stricter
-	// check is used for the cookie-path identifier and the group/role list, NOT
-	// for free-form templated header output (see headerValueReason).
-	if r == ',' || r == ';' || r == '=' {
-		return "delimiter character"
+	// The , ; = delimiters and the " { } bracketing chars are only unsafe for
+	// values placed into delimited or list contexts (a comma-joined header, or
+	// an identifier downstreams may split). They are valid in arbitrary single
+	// header values, so this stricter check is used for the cookie-path
+	// identifier and the group/role list, NOT for free-form templated header
+	// output (see headerValueReason).
+	if r == ',' || r == ';' || r == '=' || r == '"' || r == '{' || r == '}' {
+		return "delimiter or bracketing character"
 	}
 	return ""
 }
@@ -270,11 +308,12 @@ func resolveBearerIdentifier(claims map[string]interface{}, claimName string) (s
 	if !ok {
 		return "", newBearerError(bearerErrInvalidIdentifier, fmt.Sprintf("missing claim %q", claimName))
 	}
-	str, ok := raw.(string)
-	if !ok {
-		return "", newBearerError(bearerErrInvalidIdentifier, fmt.Sprintf("claim %q not a string", claimName))
+	// Accept scalar numbers (e.g. a numeric sub) by stringifying them,
+	// so a numeric identifier claim doesn't 401 a valid principal.
+	if s, isScalar := claimScalarString(raw); isScalar {
+		return s, nil
 	}
-	return str, nil
+	return "", newBearerError(bearerErrInvalidIdentifier, fmt.Sprintf("claim %q is not a scalar string or number", claimName))
 }
 
 // enforceMultiAudienceAzp implements the spec hardening: when aud is a
@@ -315,7 +354,14 @@ func enforceIatAge(claims map[string]interface{}, maxAge time.Duration) *bearerE
 	}
 	iatRaw, ok := claims["iat"].(float64)
 	if !ok {
-		// jwt.Verify already requires iat; this branch shouldn't be reached.
+		// iat is OPTIONAL per RFC 7519 §4.1.6, and jwt.Verify validates it
+		// only when present (R126) — this branch IS reachable. maxAge is NOT
+		// an operator opt-in: New() (main.go's config-default closure) always
+		// sets maxTokenAge > 0 — 0/unset becomes 24h — so this branch rejects
+		// every iat-less bearer JWT in production, not just when an operator
+		// has explicitly configured maxTokenAgeSeconds. A token with no iat
+		// has nothing to bound its age against, so fail closed rather than
+		// silently skip the check.
 		return newBearerError(bearerErrInvalidToken, "missing iat claim")
 	}
 	iat := time.Unix(int64(iatRaw), 0)
@@ -350,6 +396,20 @@ type bearerFailureTracker struct {
 	threshold int
 	window    time.Duration
 	penalty   time.Duration
+	// nextSweepAt is the map size recordFailure next scans the map at. A
+	// static per-call gate (len > defaultBearerEntrySweepThreshold) made
+	// EVERY recordFailure call re-scan the entire map once a flood of
+	// distinct source IPs crossed the threshold, turning attacker-controlled
+	// traffic into O(n^2) work under b.mu while blocked() (called on every
+	// bearer request) waits on the same lock (FIX-28). nextSweepAt doubles
+	// after each sweep (bounded below by defaultBearerEntrySweepThreshold),
+	// amortizing the scan so its frequency grows logarithmically with the
+	// flood size instead of linearly.
+	nextSweepAt int
+	// sweepPasses counts how many times recordFailure has run the full-map
+	// staleness scan. Exposed for tests to confirm the amortization actually
+	// bounds scan frequency.
+	sweepPasses int
 }
 
 type bearerFailureEntry struct {
@@ -358,6 +418,10 @@ type bearerFailureEntry struct {
 	count          int
 }
 
+// defaultBearerEntrySweepThreshold is the map size above which recordFailure
+// sweeps stale entries, bounding memory under a flood of distinct source IPs.
+const defaultBearerEntrySweepThreshold = 1024
+
 func newBearerFailureTracker(threshold int, window, penalty time.Duration) *bearerFailureTracker {
 	if threshold <= 0 {
 		threshold = 20
@@ -369,10 +433,11 @@ func newBearerFailureTracker(threshold int, window, penalty time.Duration) *bear
 		penalty = 60 * time.Second
 	}
 	return &bearerFailureTracker{
-		entries:   make(map[string]*bearerFailureEntry),
-		threshold: threshold,
-		window:    window,
-		penalty:   penalty,
+		entries:     make(map[string]*bearerFailureEntry),
+		threshold:   threshold,
+		window:      window,
+		penalty:     penalty,
+		nextSweepAt: defaultBearerEntrySweepThreshold,
 	}
 }
 
@@ -404,6 +469,43 @@ func (b *bearerFailureTracker) recordFailure(ip string) {
 	b.mu.Lock()
 	defer b.mu.Unlock()
 	now := time.Now()
+	// Bound per-IP map growth (R117): entries for source IPs that fail once
+	// and never return were never removed. Sweep stale entries (no active
+	// penalty box, too old to matter) once the map grows past a nominal
+	// size, keeping steady-state memory bounded.
+	//
+	// An entry that has not tripped the penalty box yet has a ZERO
+	// penaltyUntil, which is always Before(cutoff) — so checking only
+	// e.penaltyUntil.Before(cutoff) discarded every in-progress (not yet
+	// tripped) counter on every sweep, regardless of how recently it
+	// started. Once the map passed the threshold, a source whose failures
+	// interleaved with sweeps could never accumulate enough to trip (FIX-28).
+	// Only remove an entry once it is BOTH untripped-or-expired AND outside
+	// the counting window, so a fresh, still-accumulating counter survives.
+	//
+	// The sweep itself is gated on b.nextSweepAt, not the static threshold:
+	// a flood of distinct, still-fresh source IPs (attacker-controlled) that
+	// crosses defaultBearerEntrySweepThreshold and stays above it made every
+	// subsequent recordFailure call re-scan the whole map for nothing (the
+	// predicate above finds nothing to delete while entries stay fresh),
+	// which is O(n) work under b.mu on every call — O(n^2) to fill the map —
+	// while blocked() waits on the same mutex on every bearer request
+	// (FIX-28). nextSweepAt doubles after each sweep so the scan frequency
+	// grows logarithmically with the flood size instead of on every call.
+	if len(b.entries) > b.nextSweepAt {
+		cutoff := now.Add(-(b.window + b.penalty))
+		for k, e := range b.entries {
+			if e.penaltyUntil.Before(cutoff) && now.Sub(e.firstFailureAt) > b.window {
+				delete(b.entries, k)
+			}
+		}
+		b.sweepPasses++
+		next := 2 * len(b.entries)
+		if next < defaultBearerEntrySweepThreshold {
+			next = defaultBearerEntrySweepThreshold
+		}
+		b.nextSweepAt = next
+	}
 	e, ok := b.entries[ip]
 	if !ok || now.Sub(e.firstFailureAt) > b.window {
 		e = &bearerFailureEntry{firstFailureAt: now}
@@ -520,7 +622,10 @@ func (t *TraefikOidc) writeBearerError(rw http.ResponseWriter, req *http.Request
 	case bearerErrThrottled:
 		status = http.StatusTooManyRequests
 		body = "Too Many Requests"
-		retryAfter = t.bearerFailurePenalty
+		retryAfter = err.retryAfter
+		if retryAfter <= 0 {
+			retryAfter = t.bearerFailurePenalty
+		}
 	case bearerErrIntrospectionUnavailable:
 		status = http.StatusServiceUnavailable
 		body = "Service Unavailable"
@@ -535,6 +640,10 @@ func (t *TraefikOidc) writeBearerError(rw http.ResponseWriter, req *http.Request
 	if retryAfter > 0 {
 		rw.Header().Set("Retry-After", fmt.Sprintf("%d", int(retryAfter.Seconds())))
 	}
+	// Auth-rejection responses must never be cached (R101 contract): a
+	// cached 429/401 could be replayed to a client well after the
+	// penalty box expired or the session recovered.
+	rw.Header().Set("Cache-Control", "no-store")
 	rw.Header().Set("Content-Type", "text/plain; charset=utf-8")
 	rw.WriteHeader(status)
 	_, _ = rw.Write([]byte(body)) // Safe to ignore: best-effort error body write
@@ -553,12 +662,11 @@ func (t *TraefikOidc) handleBearerRequest(rw http.ResponseWriter, req *http.Requ
 	ip := clientIPForBearer(req)
 
 	if blocked, retryAfter := t.bearerFailureTracker.blocked(ip); blocked {
+		// Carry the actual remaining penalty (diverges from the configured
+		// default on clock-skew, partial-window expiry) so writeBearerError
+		// emits the true Retry-After rather than the full penalty.
 		throttled := newBearerError(bearerErrThrottled, "ip in penalty box")
-		// Preserve the actual retry-after even if it diverged from the
-		// configured default (clock-skew, partial-window expiry).
-		if retryAfter > 0 {
-			rw.Header().Set("Retry-After", fmt.Sprintf("%d", int(retryAfter.Seconds())))
-		}
+		throttled.retryAfter = retryAfter
 		t.writeBearerError(rw, req, throttled)
 		return
 	}
@@ -574,12 +682,51 @@ func (t *TraefikOidc) handleBearerRequest(rw http.ResponseWriter, req *http.Requ
 		t.writeBearerError(rw, req, newBearerError(bearerErrInvalidToken, "token exceeds max length"))
 		return
 	}
-	if strings.Count(token, ".") != 2 {
+	// Determine whether this is genuinely a JWT. RFC 7662 token
+	// introspection covers opaque access tokens; when the operator
+	// requires live introspection (requireTokenIntrospection, whose
+	// documented purpose is exactly opaque-token support via
+	// client_secret_basic), introspect the opaque token on the bearer
+	// path instead of rejecting it — the session path already does
+	// (validateOpaqueToken). Previously the JWT-shape gate ran before
+	// the introspection branch, so every opaque token got a 401 even
+	// with introspection on (R159).
+	//
+	// A token is only treated as a JWT when it has exactly two dots AND
+	// its header actually parses as a JOSE header. Dot count alone is
+	// insufficient: an opaque token that coincidentally contains exactly
+	// two dots used to be routed onto the JWT path and rejected even
+	// under requireTokenIntrospection (header parse would fail) — it must
+	// instead be introspected like any other opaque token (R166).
+	isJWT := joseHeaderWellFormed(token)
+	if !isJWT {
+		if t.requireTokenIntrospection {
+			p, bErr := t.buildPrincipalFromOpaqueIntrospection(token)
+			if bErr != nil {
+				if bErr.kind != bearerErrIntrospectionUnavailable {
+					t.bearerFailureTracker.recordFailure(ip)
+				}
+				t.writeBearerError(rw, req, bErr)
+				return
+			}
+			t.bearerFailureTracker.recordSuccess(ip)
+			if t.logger != nil {
+				t.logger.Debugf("bearer auth success (introspected opaque): identifier_hash=%s path=%s",
+					hashIdentifierForLog(p.Identifier), req.URL.Path)
+			}
+			t.forwardAuthorized(rw, req, p)
+			return
+		}
 		t.bearerFailureTracker.recordFailure(ip)
-		t.writeBearerError(rw, req, newBearerError(bearerErrInvalidToken, "token is not a 3-segment JWT"))
+		t.writeBearerError(rw, req, newBearerError(bearerErrInvalidToken, "token is not a valid JWT"))
 		return
 	}
 
+	// Structurally a JWT: enforce the alg/kid policy EARLY (before the
+	// cached fast-path in buildPrincipalFromBearerToken can short-circuit
+	// on a prior positive verdict). Without this pin an alg=none or
+	// oversized-kid token that had been cached as verified would sail
+	// through without re-checking.
 	if bErr := parseBearerJOSEHeader(token); bErr != nil {
 		t.bearerFailureTracker.recordFailure(ip)
 		t.writeBearerError(rw, req, bErr)
@@ -588,7 +735,13 @@ func (t *TraefikOidc) handleBearerRequest(rw http.ResponseWriter, req *http.Requ
 
 	p, bErr := t.buildPrincipalFromBearerToken(token)
 	if bErr != nil {
-		t.bearerFailureTracker.recordFailure(ip)
+		// Count only authentication failures (401/403) toward the per-IP
+		// throttle. An introspection outage (503) is infrastructure, not a
+		// client failure; recording it would trip a 429 penalty that a
+		// single success can't clear even after the endpoint recovers.
+		if bErr.kind != bearerErrIntrospectionUnavailable {
+			t.bearerFailureTracker.recordFailure(ip)
+		}
 		t.writeBearerError(rw, req, bErr)
 		return
 	}
@@ -605,7 +758,7 @@ func (t *TraefikOidc) handleBearerRequest(rw http.ResponseWriter, req *http.Requ
 // described in spec §7.3 and returns a principal ready for forwardAuthorized.
 // Returns a typed *bearerError on failure so the caller can map to status.
 func (t *TraefikOidc) buildPrincipalFromBearerToken(token string) (*principal, *bearerError) {
-	if err := t.verifyTokenWithOpts(token, verifyOpts{skipReplayMarking: true}); err != nil {
+	if err := t.verifyTokenWithOpts(token); err != nil {
 		return nil, newBearerError(bearerErrInvalidToken, "token verification failed: "+err.Error())
 	}
 
@@ -629,7 +782,9 @@ func (t *TraefikOidc) buildPrincipalFromBearerToken(token string) (*principal, *
 		return nil, newBearerError(bearerErrInvalidToken, "token_use=id rejected")
 	}
 
-	if bErr := enforceMultiAudienceAzp(claims, t.clientID); bErr != nil {
+	// Snapshot clientID under metadataMu: DCR rewrites it at runtime (R137).
+	clientID, _, _, _, _ := t.clientCredentials()
+	if bErr := enforceMultiAudienceAzp(claims, clientID); bErr != nil {
 		return nil, bErr
 	}
 	if bErr := enforceIatAge(claims, t.maxTokenAge); bErr != nil {
@@ -642,6 +797,40 @@ func (t *TraefikOidc) buildPrincipalFromBearerToken(token string) (*principal, *
 		}
 	}
 
+	// Honor IdP-initiated (backchannel/front-channel) logout. The cookie
+	// path re-checks sessionInvalidationCache on every request; the bearer
+	// path previously did not, so a still-cryptographically-valid access
+	// token for a logged-out subject kept returning 200 (and, with
+	// requireTokenIntrospection, a cached positive verdict extended the
+	// stale window). Reject here, mirroring the cookie path: use the
+	// token's iat as its creation time so a token issued before the
+	// logout is invalidated, while a legitimately freshly-issued token
+	// (iat after logout) still passes (R146). iat is OPTIONAL per RFC 7519
+	// §4.1.6 and jwt.Verify no longer requires it (R126), so an iat-less
+	// token DOES reach here now. Falling back to time.Now() made such a
+	// token always look newer than any logout, so IdP-initiated logout
+	// never revoked it — reintroducing the R98 defect the cookie path's
+	// own fallback (sessionCreatedAtForInvalidation) avoids by using the
+	// zero time instead: fail closed rather than open (FIX-24). In
+	// production this branch is mostly defense in depth: enforceIatAge
+	// above already rejects an iat-less token before reaching here whenever
+	// maxTokenAge > 0. New() always sets it so: config.MaxTokenAgeSeconds
+	// <= 0 (unset, or an operator explicitly configuring 0) maps to a 24h
+	// default (main.go:359-364), it is never mapped to "disabled" — there
+	// is no config value that makes maxTokenAge 0. This fallback protects
+	// an iat-less token's logout check only in the case New()'s mapping
+	// doesn't reach: a test that constructs TraefikOidc with maxTokenAge=0
+	// directly, bypassing New().
+	subjectForInvalidation, _ := claims["sub"].(string)
+	sidForInvalidation, _ := claims["sid"].(string)
+	var createdAt time.Time
+	if iat, ok := claims["iat"].(float64); ok {
+		createdAt = time.Unix(int64(iat), 0)
+	}
+	if t.isSessionInvalidated(sidForInvalidation, subjectForInvalidation, createdAt) {
+		return nil, newBearerError(bearerErrInvalidToken, "session has been invalidated (logout)")
+	}
+
 	rawIdentifier, bErr := resolveBearerIdentifier(claims, t.bearerIdentifierClaim)
 	if bErr != nil {
 		return nil, bErr
@@ -652,7 +841,7 @@ func (t *TraefikOidc) buildPrincipalFromBearerToken(token string) (*principal, *
 	}
 
 	subject, _ := claims["sub"].(string)
-	clientID, _ := claims["azp"].(string)
+	clientID, _ = claims["azp"].(string)
 	if clientID == "" {
 		clientID, _ = claims["client_id"].(string)
 	}
@@ -667,6 +856,178 @@ func (t *TraefikOidc) buildPrincipalFromBearerToken(token string) (*principal, *
 	}, nil
 }
 
+// buildPrincipalFromOpaqueIntrospection authenticates a bearer access
+// token that has no JWT shape by live RFC 7662 introspection, and builds
+// a principal whose identifier is the introspected subject. It mirrors
+// introspectOnBearerPath's classification (active, token_type, expiry,
+// audience) and binds the compliant subject. Only used on the bearer
+// path when requireTokenIntrospection is enabled (R159).
+//
+// Unlike a JWT bearer token — whose signature, aud and azp are already
+// bound to this client by jwt.Verify/enforceMultiAudienceAzp before this
+// function's counterpart ever runs — an opaque token has no local
+// verification at all; introspection is the only gate. So this function
+// re-applies every JWT-path gate the introspection branch used to skip
+// (R159 gap): allowOpaqueTokens, client binding, bearerIdentifierClaim +
+// sanitizeBearerIdentifier, maxTokenAge, isSessionInvalidated, the local
+// tokenBlacklist (raw token and jti) and nbf.
+func (t *TraefikOidc) buildPrincipalFromOpaqueIntrospection(token string) (*principal, *bearerError) {
+	if !t.allowOpaqueTokens {
+		return nil, newBearerError(bearerErrInvalidToken, "opaque tokens are not enabled (set allowOpaqueTokens to true)")
+	}
+
+	// Same local-revocation gate the JWT path applies first
+	// (verifyTokenWithOpts, token_manager.go:71-75): handleLogout calls
+	// RevokeToken on the session's access token specifically so a token
+	// captured before logout cannot be reused (helpers.go). Without this
+	// check here, a captured opaque bearer token kept authenticating as the
+	// revoked subject for as long as the IdP still reported it active —
+	// provider-side revocation is best-effort (RevokeTokenWithProvider logs
+	// and continues on failure) and is not configured for most deployments.
+	if t.tokenBlacklist != nil {
+		if b, exists := t.tokenBlacklist.Get(token); exists && b != nil {
+			return nil, newBearerError(bearerErrTokenInactive, "token has been revoked")
+		}
+	}
+
+	resp, err := t.introspectToken(token)
+	if err != nil {
+		// Any introspection transport/HTTP error — including a 4xx, which
+		// per RFC 7662 s2.3 means OUR OWN client credentials were rejected,
+		// not that the presented token is bad — is an availability problem,
+		// not a verdict on the token. Only a 200 response with active=false
+		// is (FIX-13, supersedes R156's blanket 4xx-as-invalid mapping).
+		return nil, newBearerError(bearerErrIntrospectionUnavailable, "introspection failed: "+err.Error())
+	}
+	if !resp.Active {
+		return nil, newBearerError(bearerErrTokenInactive, "introspection reports token inactive")
+	}
+	// Mirror introspectOnBearerPath (R149): reject a definite non-access
+	// token_type (e.g. refresh_token); accept "access_token" and "Bearer".
+	if resp.TokenType != "" && resp.TokenType != "access_token" && resp.TokenType != "Bearer" {
+		return nil, newBearerError(bearerErrTokenInactive, "introspection token_type is not a bearer access token")
+	}
+	if resp.Exp > 0 && time.Now().After(time.Unix(resp.Exp, 0)) {
+		return nil, newBearerError(bearerErrTokenInactive, "introspection reports token expired")
+	}
+	// Mirrors the session path's strict nbf comparison in
+	// validateOpaqueToken (token_introspection.go:258-263): no clock-skew
+	// tolerance. This is NOT the same check the JWT path applies — its
+	// verifyNotBefore (jwt.go:281, via verifyTimeConstraint) allows
+	// ClockSkewTolerancePast (jwt.go:23, 10s) before failing. RFC 7662
+	// s2.2 defines nbf with the same semantics as RFC 7519's nbf claim.
+	if resp.Nbf > 0 && time.Now().Before(time.Unix(resp.Nbf, 0)) {
+		return nil, newBearerError(bearerErrTokenInactive, "introspection reports token not yet valid (nbf)")
+	}
+	// Same jti-blacklist gate the JWT path applies on a cached-token hit
+	// (token_manager.go:90-96): RevokeToken blacklists a JWT's jti too, and
+	// an IdP may echo that same jti in an opaque token's introspection
+	// response (e.g. a rotated token sharing the revoked JTI). Gated on
+	// disableReplayDetection like the JWT path, so an operator who has
+	// disabled replay/JTI tracking is not surprised by this new check.
+	if resp.Jti != "" && !t.disableReplayDetection && t.tokenBlacklist != nil {
+		if b, exists := t.tokenBlacklist.Get(resp.Jti); exists && b != nil {
+			return nil, newBearerError(bearerErrTokenInactive, "token replay detected (jti blacklisted)")
+		}
+	}
+	clientID, _, _, audience, _ := t.clientCredentials()
+	if audience != "" && audience != clientID {
+		// A distinct API audience is configured: the introspection response
+		// MUST carry a matching audience.
+		if resp.Aud == nil || verifyAudience(resp.Aud, audience) != nil {
+			return nil, newBearerError(bearerErrTokenInactive, "introspection audience mismatch")
+		}
+	} else {
+		// audience == clientID (the common single-app default): RFC 7662
+		// s2.2 leaves client scoping to the authorization server's own
+		// policy, so without an explicit check here an opaque token issued
+		// to a completely different client at the same IdP would still
+		// report active=true and pass. Bind it to this client via either
+		// client_id or aud (client_id is RFC-optional).
+		clientBound := resp.ClientID == clientID ||
+			(resp.Aud != nil && verifyAudience(resp.Aud, clientID) == nil)
+		if !clientBound {
+			return nil, newBearerError(bearerErrTokenInactive, "introspection client_id/audience does not match this client")
+		}
+	}
+
+	// maxTokenAge bound on iat, via the SAME enforceIatAge the JWT path
+	// uses (not a hand-rolled duplicate): RFC 7662 iat is optional, but
+	// New() always sets maxTokenAge > 0 (0/unset becomes 24h,
+	// main.go's config-default closure), so a response with no iat gives
+	// nothing to bound the token's age against and must fail closed —
+	// exactly like enforceIatAge already does for a JWT with no iat
+	// (R126/FIX-27 made iat optional on the JWT path too, and that path
+	// fails closed rather than silently skipping the bound).
+	iatClaims := map[string]interface{}{}
+	if resp.Iat > 0 {
+		iatClaims["iat"] = float64(resp.Iat)
+	}
+	if bErr := enforceIatAge(iatClaims, t.maxTokenAge); bErr != nil {
+		return nil, bErr
+	}
+
+	// Honor IdP-initiated (backchannel/front-channel) logout, mirroring the
+	// JWT bearer path (R146). RFC 7662 does not define sid, but some
+	// providers return it anyway (FIX-03): when the response carries one,
+	// check it exactly like the JWT path does, so a sid-only (front-channel)
+	// logout — front-channel logout always records by sid only, and so does
+	// a backchannel logout token that carries only sid — can revoke an
+	// opaque token too, not just a backchannel logout recorded by sub. iat
+	// absent -> zero time (fail closed, same as the JWT path's FIX-24
+	// contract), so a token whose age cannot be bounded is treated as
+	// pre-dating any logout rather than as freshly issued.
+	var createdAt time.Time
+	if resp.Iat > 0 {
+		createdAt = time.Unix(resp.Iat, 0)
+	}
+	if t.isSessionInvalidated(resp.Sid, resp.Sub, createdAt) {
+		return nil, newBearerError(bearerErrInvalidToken, "session has been invalidated (logout)")
+	}
+
+	// Populate every non-empty IntrospectionResponse member the RFC 7662
+	// response can carry, not just sub/username, so bearerIdentifierClaim
+	// can resolve the identifier from any of them (FIX-03) — mirroring how
+	// the JWT bearer path resolves against the full decoded claim set.
+	claims := map[string]interface{}{}
+	if resp.Sub != "" {
+		claims["sub"] = resp.Sub
+	}
+	if resp.Username != "" {
+		claims["username"] = resp.Username
+	}
+	if resp.ClientID != "" {
+		claims["client_id"] = resp.ClientID
+	}
+	if resp.Scope != "" {
+		claims["scope"] = resp.Scope
+	}
+	if resp.Iss != "" {
+		claims["iss"] = resp.Iss
+	}
+	if resp.Jti != "" {
+		claims["jti"] = resp.Jti
+	}
+	if resp.Aud != nil {
+		claims["aud"] = resp.Aud
+	}
+	rawIdentifier, bErr := resolveBearerIdentifier(claims, t.bearerIdentifierClaim)
+	if bErr != nil {
+		return nil, bErr
+	}
+	identifier, bErr := sanitizeBearerIdentifier(rawIdentifier, t.maxIdentifierLength)
+	if bErr != nil {
+		return nil, bErr
+	}
+	return &principal{
+		Claims:      claims,
+		Identifier:  identifier,
+		Subject:     resp.Sub,
+		AccessToken: token,
+		Source:      sourceBearer,
+	}, nil
+}
+
 // introspectOnBearerPath calls the existing RFC 7662 introspector when the
 // operator demands real-time revocation. Distinguishes "token revoked" (401)
 // from "endpoint unavailable" (503) so transient infra failures don't look
@@ -674,10 +1035,57 @@ func (t *TraefikOidc) buildPrincipalFromBearerToken(token string) (*principal, *
 func (t *TraefikOidc) introspectOnBearerPath(token string) *bearerError {
 	resp, err := t.introspectToken(token)
 	if err != nil {
+		// Any introspection transport/HTTP error is an availability
+		// problem, never a verdict on the token: RFC 7662 s2.3 defines a
+		// 401/403 from the introspection endpoint as OUR OWN client
+		// credentials being rejected (e.g. a rotated client_secret), and
+		// 408/429 as the endpoint throttling or timing out. Only a 200
+		// response with active=false is a definite "not active" (s2.2).
+		// (FIX-13, supersedes R156's blanket 4xx-as-invalid mapping — a
+		// misconfigured or throttled endpoint must not turn every valid
+		// token into a 401.)
 		return newBearerError(bearerErrIntrospectionUnavailable, "introspection failed: "+err.Error())
 	}
 	if !resp.Active {
 		return newBearerError(bearerErrTokenInactive, "introspection reports token inactive")
 	}
+	// Mirror the session path (validateOpaqueToken): an opaque-or-any
+	// token whose RFC 7662 token_type classifies it as a refresh token
+	// must not be honored as a bearer access token (R149). Only reject on
+	// a definite non-access match; compliant providers may omit it. RFC
+	// 7662's token_type is the RFC 6749 token type, whose value for an
+	// access token is "Bearer" (RFC 6750) — accept both spellings
+	// providers use (R156).
+	if resp.TokenType != "" && resp.TokenType != "access_token" && resp.TokenType != "Bearer" {
+		return newBearerError(bearerErrTokenInactive, "introspection token_type is not a bearer access token")
+	}
+	// Mirror the session path (validateOpaqueToken): an active but
+	// already-expired result must not pass. The positive-only cache is
+	// capped by time-until-exp when Exp is present, but a provider
+	// returning active=1 past exp would otherwise let the token pass on
+	// the bearer path while the identical token is rejected on the
+	// session path.
+	if resp.Exp > 0 {
+		expTime := time.Unix(resp.Exp, 0)
+		if time.Now().After(expTime) {
+			return newBearerError(bearerErrTokenInactive, "introspection reports token expired")
+		}
+	}
+	// Mirror the session path (validateOpaqueToken): when a distinct API
+	// audience is configured (audience != clientID), the introspection
+	// response MUST carry a matching audience. Fail closed on a missing or
+	// mismatched aud, otherwise a token minted for a different audience
+	// would pass the bearer path while the identical token is rejected on
+	// the session path. aud may be a single string or an array (RFC 7662).
+	// (R143)
+	clientID, _, _, audience, _ := t.clientCredentials()
+	if audience != "" && audience != clientID {
+		if resp.Aud == nil {
+			return newBearerError(bearerErrTokenInactive, "introspection reports no audience")
+		}
+		if err := verifyAudience(resp.Aud, audience); err != nil {
+			return newBearerError(bearerErrTokenInactive, "introspection audience mismatch")
+		}
+	}
 	return nil
 }

bearer_auth_fuzz_test.go

@@ -0,0 +1,46 @@
+package traefikoidc
+
+import "testing"
+
+// FuzzParseBearerJOSEHeader verifies the attacker-controlled JWT header parser
+// never panics on arbitrary input (no slice OOB, no unbounded alloc, no
+// JSON-engine surprise) regardless of token contents.
+func FuzzParseBearerJOSEHeader(f *testing.F) {
+	seeds := []string{
+		"",
+		"...",
+		"abc.def.ghi",
+		"eyJhbGciOiJSUzI1NiIsImtpZCI6ImtpZDEifQ.sig.sig", // alg=RS256 kid=kid1
+		"::",
+		"snapshot=",
+		"a,b.zzz",
+	}
+	for _, s := range seeds {
+		f.Add(s)
+	}
+	f.Fuzz(func(t *testing.T, token string) {
+		parseBearerJOSEHeader(token) // must not panic
+	})
+}
+
+// FuzzSanitizeBearerIdentifier verifies the identifier sanitizer never panics on
+// arbitrary strings and always returns either a clean value or a *bearerError.
+func FuzzSanitizeBearerIdentifier(f *testing.F) {
+	seeds := []string{
+		"",
+		"alice",
+		"user,group=admin",
+		"a\u202eb\u202c",
+		"\t \n",
+		"verylongidentifier-padding-padding-padding-padding",
+	}
+	for _, s := range seeds {
+		f.Add(s)
+	}
+	f.Fuzz(func(t *testing.T, raw string) {
+		id, berr := sanitizeBearerIdentifier(raw, 256)
+		if berr == nil && id == "" {
+			t.Fatalf("sanitize ok but empty identifier for %q", raw)
+		}
+	})
+}

bearer_auth_test.go

@@ -222,7 +222,8 @@ func TestResolveBearerIdentifier(t *testing.T) {
 		{name: "explicit sub", claims: map[string]interface{}{"sub": "abc"}, claim: "sub", want: "abc"},
 		{name: "custom client_id claim", claims: map[string]interface{}{"client_id": "svc"}, claim: "client_id", want: "svc"},
 		{name: "missing claim", claims: map[string]interface{}{"other": "x"}, claim: "sub", wantErr: true},
-		{name: "non-string claim", claims: map[string]interface{}{"sub": 123}, claim: "sub", wantErr: true},
+		{name: "numeric claim", claims: map[string]interface{}{"sub": 123}, claim: "sub", want: "123"}, // R102: scalar numbers stringified, not rejected
+		{name: "object claim", claims: map[string]interface{}{"sub": map[string]interface{}{"a": 1}}, claim: "sub", wantErr: true},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
@@ -615,6 +616,43 @@ func TestServeHTTP_Bearer_ThrottleTrips429(t *testing.T) {
 	}
 }
 
+func TestServeHTTP_Bearer_Introspection503_NotThrottleFailure(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run: introspection 503 should reject request")
+	})
+	oidc := makeBearerOIDC(t, next)
+	oidc.requireTokenIntrospection = true
+	// Unreachable introspection endpoint -> every request returns 503.
+	oidc.introspectionURL = "http://127.0.0.1:1/"
+	oidc.httpClient = &http.Client{Timeout: 500 * time.Millisecond}
+	oidc.bearerFailureTracker = newBearerFailureTracker(3, 60*time.Second, 60*time.Second)
+
+	claims := defaultBearerClaims()
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	send := func() *httptest.ResponseRecorder {
+		req := httptest.NewRequest("GET", "/api/work", nil)
+		req.RemoteAddr = "10.0.0.7:1234"
+		req.Header.Set("Authorization", "Bearer "+token)
+		rw := httptest.NewRecorder()
+		oidc.ServeHTTP(rw, req)
+		return rw
+	}
+
+	// Four requests during an introspection outage. Each is a 503 and the
+	// per-IP failure count must stay at 0 so the threshold (3) never trips.
+	// On OLD code each 503 was counted as a throttle failure, so the 4th
+	// request would come back 429 (penalty box) instead of 503.
+	for i := 0; i < 4; i++ {
+		rw := send()
+		if rw.Code != http.StatusServiceUnavailable {
+			t.Fatalf("iteration %d: status=%d, want %d", i, rw.Code, http.StatusServiceUnavailable)
+		}
+	}
+}
+
 func TestServeHTTP_Bearer_ExcludedURLStripsAuth(t *testing.T) {
 	t.Parallel()
 	var capturedAuth string

bearer_failure_tracker_sweep_test.go

@@ -0,0 +1,72 @@
+package traefikoidc
+
+import (
+	"fmt"
+	"testing"
+	"time"
+)
+
+// FIX-28 regression tests.
+//
+// R117's map-growth sweep in recordFailure deleted every entry whose
+// penaltyUntil was before the cutoff. An entry that has not tripped the
+// penalty box yet has a ZERO penaltyUntil, which is always before any
+// cutoff — so once the map passed defaultBearerEntrySweepThreshold, every
+// accumulating (not-yet-tripped) counter was discarded regardless of how
+// recently it started, no matter how recent firstFailureAt was. A source
+// whose failures interleave with sweeps could never reach the threshold.
+
+// TestBearerFailureTracker_SweepDoesNotDiscardFreshCounters guards the
+// exact scenario from the finding: threshold 3, 2 failures for a target
+// IP, then 1025 other IPs failing once each (crossing the sweep
+// threshold), then a 3rd failure for the target IP. The target's count
+// must survive the sweep and trip the penalty box.
+// Fail-on-old: the sweep discards the target's in-progress counter, so the
+// 3rd failure restarts it at count=1 and blocked() reports false.
+func TestBearerFailureTracker_SweepDoesNotDiscardFreshCounters(t *testing.T) {
+	b := newBearerFailureTracker(3, 60*time.Second, 60*time.Second)
+
+	b.recordFailure("target-ip")
+	b.recordFailure("target-ip")
+
+	// Push the map past defaultBearerEntrySweepThreshold with distinct,
+	// equally-fresh IPs so recordFailure's sweep branch runs.
+	for i := 0; i < defaultBearerEntrySweepThreshold+1; i++ {
+		b.recordFailure(fmt.Sprintf("other-ip-%d", i))
+	}
+
+	b.recordFailure("target-ip")
+
+	blocked, _ := b.blocked("target-ip")
+	if !blocked {
+		t.Fatal("a source whose failures are recent (within the window) must not lose its count to the map-growth sweep, and must trip the penalty box on its 3rd failure")
+	}
+}
+
+// TestBearerFailureTracker_SweepRemovesTrulyStaleEntries is the positive
+// control: an entry that is BOTH untripped AND outside the window (a
+// source that failed once, long ago, and never returned) must still be
+// swept once the map grows past the threshold — otherwise the fix would
+// defeat the sweep's original memory-bound purpose entirely.
+func TestBearerFailureTracker_SweepRemovesTrulyStaleEntries(t *testing.T) {
+	b := newBearerFailureTracker(20, 60*time.Second, 60*time.Second)
+
+	b.mu.Lock()
+	b.entries["stale-ip"] = &bearerFailureEntry{
+		firstFailureAt: time.Now().Add(-time.Hour), // well outside the 60s window
+		count:          1,
+		// penaltyUntil left zero: never tripped.
+	}
+	b.mu.Unlock()
+
+	for i := 0; i < defaultBearerEntrySweepThreshold+1; i++ {
+		b.recordFailure(fmt.Sprintf("filler-ip-%d", i))
+	}
+
+	b.mu.Lock()
+	_, stillPresent := b.entries["stale-ip"]
+	b.mu.Unlock()
+	if stillPresent {
+		t.Fatal("an untripped entry whose firstFailureAt is outside the window must still be swept once the map grows past the threshold")
+	}
+}

bearer_logout_iat_fallback_test.go

@@ -0,0 +1,100 @@
+package traefikoidc
+
+import (
+	"testing"
+	"time"
+)
+
+// FIX-24 regression test.
+//
+// buildPrincipalFromBearerToken derived the IdP-logout-invalidation
+// "createdAt" from the token's iat claim, falling back to time.Now() when
+// iat was absent. Since 8640451 made iat OPTIONAL in jwt.Verify (R126), an
+// access token without iat now reaches this check. time.Now() makes such a
+// token always look newer than any logout event (isSessionInvalidated only
+// matches when invalidationTime >= createdAt), so IdP-initiated
+// (backchannel) logout never revokes it — reintroducing the R98 defect the
+// cookie path already fixed by falling back to zero time instead.
+//
+// Fail-on-old: a bearer token without iat, for a sid invalidated by
+// backchannel logout, still authenticates (200) after the logout.
+func TestBearerLogoutInvalidation_NoIatFallsClosedNotOpen(t *testing.T) {
+	cache := NewCache()
+	defer cache.Close()
+
+	oidc := makeBearerOIDC(t, nil)
+	oidc.sessionInvalidationCache = cache
+	// Disable the unrelated maxTokenAge/enforceIatAge bound (a DIFFERENT
+	// check that also rejects a missing iat, and that New() always turns on
+	// in production — 0/unset becomes 24h, main.go:357-362 — this override
+	// only exists because this test constructs *TraefikOidc directly,
+	// bypassing New()) so this test isolates the isSessionInvalidated
+	// createdAt fallback under test. That fallback is what actually matters
+	// once maxTokenAge is 0: with maxTokenAge > 0 (the production default),
+	// enforceIatAge rejects an iat-less token before this logout check is
+	// even reached.
+	oidc.maxTokenAge = 0
+
+	claims := defaultBearerClaims()
+	delete(claims, "iat") // provider omits iat (now legal per R126)
+	claims["sub"] = "user-1"
+	claims["sid"] = "session-1"
+
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	// Backchannel logout invalidates the session a full hour before this
+	// request (set directly rather than via invalidateSession's real-clock
+	// Unix() call, so the comparison is deterministic regardless of
+	// test-execution timing rather than depending on two time.Now() calls
+	// landing in the same second). The buggy time.Now() fallback for
+	// createdAt makes the token look newer than this invalidation
+	// (invalidationTime.Before(createdAt) == true -> NOT invalidated); the
+	// fix's zero-time fallback is never after any invalidation timestamp.
+	invalidatedAt := time.Now().Add(-time.Hour).Unix()
+	cache.Set(oidc.buildSessionInvalidationKey("sid", "session-1"), invalidatedAt, time.Hour)
+
+	_, bErr := oidc.buildPrincipalFromBearerToken(token)
+	if bErr == nil {
+		t.Fatal("a bearer token without iat, whose sid was invalidated by backchannel logout, must be rejected (fail closed), not authenticated as if issued after the logout")
+	}
+}
+
+// TestBearerLogoutInvalidation_WithIatStillHonored is the positive control:
+// a token WITH iat issued before the logout must still be invalidated (the
+// existing R146 behavior), and one issued after must still pass.
+func TestBearerLogoutInvalidation_WithIatStillHonored(t *testing.T) {
+	cache := NewCache()
+	defer cache.Close()
+
+	oidc := makeBearerOIDC(t, nil)
+	oidc.sessionInvalidationCache = cache
+
+	if err := oidc.invalidateSession("session-2", ""); err != nil {
+		t.Fatalf("invalidateSession: %v", err)
+	}
+
+	// Issued well before the logout above.
+	staleClaims := defaultBearerClaims()
+	staleClaims["sub"] = "user-2"
+	staleClaims["sid"] = "session-2"
+	staleClaims["iat"] = float64(time.Now().Add(-time.Hour).Unix())
+	staleToken := makeBearerJWT(t, defaultBearerHeader(), staleClaims)
+	seedVerified(t, oidc, staleToken, staleClaims)
+
+	if _, bErr := oidc.buildPrincipalFromBearerToken(staleToken); bErr == nil {
+		t.Fatal("a token issued before the logout must still be invalidated")
+	}
+
+	// Freshly issued after the logout, for an unrelated sid.
+	freshClaims := defaultBearerClaims()
+	freshClaims["sub"] = "user-3"
+	freshClaims["sid"] = "session-3"
+	freshClaims["iat"] = float64(time.Now().Unix())
+	freshToken := makeBearerJWT(t, defaultBearerHeader(), freshClaims)
+	seedVerified(t, oidc, freshToken, freshClaims)
+
+	if _, bErr := oidc.buildPrincipalFromBearerToken(freshToken); bErr != nil {
+		t.Fatalf("a freshly issued token for an uninvalidated sid must pass, got: %v", bErr)
+	}
+}

bearer_opaque_binding_test.go

@@ -0,0 +1,390 @@
+package traefikoidc
+
+import (
+	"testing"
+	"time"
+)
+
+// FIX-03 regression tests.
+//
+// R159 sent every opaque (non-JWT) bearer token to
+// buildPrincipalFromOpaqueIntrospection whenever requireTokenIntrospection
+// was enabled, with none of the JWT-path gates: allowOpaqueTokens was never
+// checked, the introspected client_id/audience was never bound to this
+// client when the operator left audience==clientID (the common default),
+// and IdP-initiated logout (isSessionInvalidated) was never consulted. Any
+// introspected active=true token from the same IdP therefore authenticated,
+// including one issued to a completely different client.
+
+// TestBearerOpaqueIntrospection_RequiresAllowOpaqueTokens guards the
+// allowOpaqueTokens gate: with it left at its default (false), an opaque
+// bearer token must be rejected even when requireTokenIntrospection is on
+// and the introspection endpoint reports the token active.
+func TestBearerOpaqueIntrospection_RequiresAllowOpaqueTokens(t *testing.T) {
+	active := &IntrospectionResponse{Active: true, Sub: "user-1", ClientID: "my-client"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: active},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         false, // default
+		clientID:                  "my-client",
+	}
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr == nil {
+		t.Fatal("opaque bearer token must be rejected when allowOpaqueTokens is false, even with requireTokenIntrospection on")
+	}
+}
+
+// TestBearerOpaqueIntrospection_RejectsForeignClient guards the client
+// binding: when audience==clientID (no distinct API audience configured),
+// an introspected token whose client_id names another client, and whose
+// aud does not contain this client either, must be rejected.
+func TestBearerOpaqueIntrospection_RejectsForeignClient(t *testing.T) {
+	foreign := &IntrospectionResponse{Active: true, Sub: "user-1", ClientID: "other-client"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: foreign},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+	}
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr == nil {
+		t.Fatal("an introspected token issued to a different client_id must be rejected")
+	}
+}
+
+// TestBearerOpaqueIntrospection_AcceptsOwnClientViaClientID is the positive
+// control: client_id matching this client must still authenticate.
+func TestBearerOpaqueIntrospection_AcceptsOwnClientViaClientID(t *testing.T) {
+	own := &IntrospectionResponse{Active: true, Sub: "user-1", ClientID: "my-client"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: own},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+	}
+	p, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr != nil {
+		t.Fatalf("a token issued to this client_id must be accepted, got: %v", bErr)
+	}
+	if p.Identifier != "user-1" {
+		t.Fatalf("expected identifier %q, got %q", "user-1", p.Identifier)
+	}
+}
+
+// TestBearerOpaqueIntrospection_AcceptsOwnClientViaAud is the positive
+// control for providers that omit client_id from the introspection
+// response but carry it in aud instead (RFC 7662 leaves client_id
+// optional).
+func TestBearerOpaqueIntrospection_AcceptsOwnClientViaAud(t *testing.T) {
+	own := &IntrospectionResponse{Active: true, Sub: "user-1", Aud: "my-client"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: own},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+	}
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr != nil {
+		t.Fatalf("a token whose aud contains this client_id must be accepted, got: %v", bErr)
+	}
+}
+
+// TestBearerOpaqueIntrospection_InvalidatedSessionRejected guards the
+// IdP-initiated-logout check: a subject invalidated via backchannel logout
+// must be rejected even though the introspected token itself reports
+// active=true. The introspection response carries no sid (RFC 7662 does
+// not define one), so this checks invalidation by sub, mirroring the JWT
+// bearer path's isSessionInvalidated(sid, sub, createdAt) call with an
+// empty sid.
+func TestBearerOpaqueIntrospection_InvalidatedSessionRejected(t *testing.T) {
+	cache := NewCache()
+	defer cache.Close()
+
+	own := &IntrospectionResponse{Active: true, Sub: "user-1", ClientID: "my-client"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: own},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		sessionInvalidationCache:  cache,
+	}
+	if err := tObj.invalidateSession("", "user-1"); err != nil {
+		t.Fatalf("invalidateSession: %v", err)
+	}
+
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr == nil {
+		t.Fatal("an introspected token for a subject invalidated by backchannel logout must be rejected")
+	}
+}
+
+// TestBearerOpaqueIntrospection_NotYetInvalidatedAccepted is the positive
+// control: a subject with no invalidation entry must still authenticate.
+func TestBearerOpaqueIntrospection_NotYetInvalidatedAccepted(t *testing.T) {
+	cache := NewCache()
+	defer cache.Close()
+
+	own := &IntrospectionResponse{Active: true, Sub: "user-1", ClientID: "my-client"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: own},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		sessionInvalidationCache:  cache,
+	}
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr != nil {
+		t.Fatalf("a subject with no invalidation entry must authenticate, got: %v", bErr)
+	}
+}
+
+// TestBearerOpaqueIntrospection_UsesBearerIdentifierClaim guards that the
+// identifier is resolved through bearerIdentifierClaim + sanitizeBearerIdentifier
+// like the JWT bearer path, instead of always preferring sub.
+func TestBearerOpaqueIntrospection_UsesBearerIdentifierClaim(t *testing.T) {
+	own := &IntrospectionResponse{Active: true, Sub: "user-1", Username: "svc-account", ClientID: "my-client"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: own},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		bearerIdentifierClaim:     "username",
+	}
+	p, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr != nil {
+		t.Fatalf("unexpected error: %v", bErr)
+	}
+	if p.Identifier != "svc-account" {
+		t.Fatalf("expected identifier from configured claim %q, got %q", "username", p.Identifier)
+	}
+}
+
+// TestBearerOpaqueIntrospection_MaxTokenAgeEnforced guards that maxTokenAge
+// bounds the introspected token's iat like enforceIatAge does for the JWT
+// path, when the AS returns one.
+func TestBearerOpaqueIntrospection_MaxTokenAgeEnforced(t *testing.T) {
+	stale := &IntrospectionResponse{
+		Active:   true,
+		Sub:      "user-1",
+		ClientID: "my-client",
+		Iat:      time.Now().Add(-2 * time.Hour).Unix(),
+	}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: stale},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		maxTokenAge:               time.Hour,
+	}
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr == nil {
+		t.Fatal("an introspected token whose iat is older than maxTokenAge must be rejected")
+	}
+}
+
+// TestBearerOpaqueIntrospection_MissingIatRejectedWithMaxTokenAge guards
+// that an opaque token whose introspection response carries no iat is
+// bound by maxTokenAge exactly like enforceIatAge binds the JWT path: when
+// maxTokenAge > 0 (New() always sets it so — 0/unset becomes 24h,
+// main.go's config-default closure), a missing iat gives nothing to bound
+// the token's age against, so it must fail closed rather than bypass the
+// age check entirely.
+func TestBearerOpaqueIntrospection_MissingIatRejectedWithMaxTokenAge(t *testing.T) {
+	noIat := &IntrospectionResponse{Active: true, Sub: "user-1", ClientID: "my-client"} // Iat left zero
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: noIat},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		maxTokenAge:               24 * time.Hour,
+	}
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr == nil {
+		t.Fatal("an introspected opaque token with no iat must be rejected when maxTokenAge is set, matching enforceIatAge's fail-closed contract on the JWT path")
+	}
+}
+
+// TestBearerOpaqueIntrospection_SidOnlyLogoutRejected guards front-channel
+// (sid-only) logout reaching an opaque bearer token. isSessionInvalidated
+// used to be called with a hardcoded empty sid, so a logout recorded only
+// by sid (front-channel logout always records this way; so does a
+// back-channel logout token carrying only sid) never revoked an opaque
+// token even when the introspection response itself carried a sid.
+func TestBearerOpaqueIntrospection_SidOnlyLogoutRejected(t *testing.T) {
+	cache := NewCache()
+	defer cache.Close()
+
+	withSid := &IntrospectionResponse{Active: true, Sub: "user-1", ClientID: "my-client", Sid: "session-1"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: withSid},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		sessionInvalidationCache:  cache,
+	}
+	if err := tObj.invalidateSession("session-1", ""); err != nil {
+		t.Fatalf("invalidateSession: %v", err)
+	}
+
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr == nil {
+		t.Fatal("an introspected token whose sid was invalidated by a sid-only (front-channel) logout must be rejected, when the introspection response carries that sid")
+	}
+}
+
+// TestBearerOpaqueIntrospection_RevokedTokenRejected guards the local
+// revocation blacklist: the JWT bearer path rejects a raw token that
+// RevokeToken blacklisted (verifyTokenWithOpts, token_manager.go:71-75), and
+// handleLogout calls RevokeToken on the session's access token specifically
+// so "a token captured before logout ... cannot be reused" (helpers.go).
+// buildPrincipalFromOpaqueIntrospection never consulted t.tokenBlacklist, so
+// a captured opaque bearer token kept authenticating as the victim after
+// logout for as long as the IdP still reported it active.
+func TestBearerOpaqueIntrospection_RevokedTokenRejected(t *testing.T) {
+	blacklist := NewCache()
+	defer blacklist.Close()
+
+	active := &IntrospectionResponse{Active: true, Sub: "victim", ClientID: "my-client"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: active},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		tokenBlacklist:            blacklist,
+		tokenCache:                NewTokenCache(),
+	}
+	defer tObj.tokenCache.Close()
+
+	const token = "opaque-victim-token"
+	tObj.RevokeToken(token)
+
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection(token)
+	if bErr == nil {
+		t.Fatal("an opaque bearer token blacklisted by RevokeToken (logout) must be rejected, even though introspection still reports it active")
+	}
+	if bErr.kind != bearerErrTokenInactive {
+		t.Fatalf("want bearerErrTokenInactive (401), got kind %v", bErr.kind)
+	}
+}
+
+// TestBearerOpaqueIntrospection_BlacklistedJtiRejected guards the jti side
+// of the same gate: when the introspection response carries a jti and that
+// jti is blacklisted (e.g. the IdP echoes the same jti it minted for a JWT
+// RevokeToken already blacklisted by jti), the opaque path must reject it
+// too, unless disableReplayDetection is set — mirroring the JWT path's
+// tokenCache-hit jti check (token_manager.go:90-96).
+func TestBearerOpaqueIntrospection_BlacklistedJtiRejected(t *testing.T) {
+	blacklist := NewCache()
+	defer blacklist.Close()
+	blacklist.Set("revoked-jti-1", true, time.Hour)
+
+	withJti := &IntrospectionResponse{Active: true, Sub: "victim", ClientID: "my-client", Jti: "revoked-jti-1"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: withJti},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		tokenBlacklist:            blacklist,
+	}
+
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr == nil {
+		t.Fatal("an opaque bearer token whose introspection jti is blacklisted must be rejected")
+	}
+	if bErr.kind != bearerErrTokenInactive {
+		t.Fatalf("want bearerErrTokenInactive (401), got kind %v", bErr.kind)
+	}
+}
+
+// TestBearerOpaqueIntrospection_BlacklistedJtiIgnoredWhenReplayDetectionDisabled
+// guards the disableReplayDetection escape hatch on the jti-blacklist gate
+// (bearer_auth.go:928): an operator who has turned off replay/JTI tracking
+// must not be surprised by this gate rejecting an otherwise-valid token
+// whose jti happens to collide with a blacklisted one. The raw token itself
+// is NOT blacklisted here — only its jti is — so this isolates the jti
+// branch from the raw-token blacklist check covered by
+// _RevokedTokenRejected above.
+func TestBearerOpaqueIntrospection_BlacklistedJtiIgnoredWhenReplayDetectionDisabled(t *testing.T) {
+	blacklist := NewCache()
+	defer blacklist.Close()
+	blacklist.Set("revoked-jti-1", true, time.Hour)
+
+	withJti := &IntrospectionResponse{Active: true, Sub: "user-1", ClientID: "my-client", Jti: "revoked-jti-1"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: withJti},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		tokenBlacklist:            blacklist,
+		disableReplayDetection:    true,
+	}
+
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr != nil {
+		t.Fatalf("a blacklisted jti must be ignored when disableReplayDetection is true, got: %v", bErr)
+	}
+}
+
+// TestBearerOpaqueIntrospection_NbfFutureRejected guards the not-before
+// check the JWT path applies through verifyTimeClaims and the session path
+// applies through validateOpaqueToken (token_introspection.go:258-263): an
+// introspection response reporting a future nbf must be rejected on the
+// bearer path too.
+func TestBearerOpaqueIntrospection_NbfFutureRejected(t *testing.T) {
+	notYetValid := &IntrospectionResponse{
+		Active:   true,
+		Sub:      "user-1",
+		ClientID: "my-client",
+		Nbf:      time.Now().Add(time.Hour).Unix(),
+	}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: notYetValid},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+	}
+	_, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr == nil {
+		t.Fatal("an introspected token with nbf in the future must be rejected")
+	}
+	if bErr.kind != bearerErrTokenInactive {
+		t.Fatalf("want bearerErrTokenInactive (401), got kind %v", bErr.kind)
+	}
+}
+
+// TestBearerOpaqueIntrospection_UsesClientIDClaim guards that
+// bearerIdentifierClaim can resolve against any IntrospectionResponse
+// member, not just sub/username — client_id, scope, iss, jti and aud must
+// all be available too.
+func TestBearerOpaqueIntrospection_UsesClientIDClaim(t *testing.T) {
+	own := &IntrospectionResponse{Active: true, Sub: "user-1", ClientID: "my-client"}
+	tObj := &TraefikOidc{
+		logger:                    newNoOpLogger(),
+		introspectionCache:        &stubIntrospectionCache{v: own},
+		requireTokenIntrospection: true,
+		allowOpaqueTokens:         true,
+		clientID:                  "my-client",
+		bearerIdentifierClaim:     "client_id",
+	}
+	p, bErr := tObj.buildPrincipalFromOpaqueIntrospection("opaque-token")
+	if bErr != nil {
+		t.Fatalf("unexpected error: %v", bErr)
+	}
+	if p.Identifier != "my-client" {
+		t.Fatalf("expected identifier from configured claim %q, got %q", "client_id", p.Identifier)
+	}
+}

cache_bench_test.go

@@ -2,7 +2,6 @@ package traefikoidc
 
 import (
 	"fmt"
-	"sync"
 	"testing"
 	"time"
 )
@@ -161,81 +160,3 @@ func BenchmarkLRUStrategy_EstimateSize(b *testing.B) {
 		strategy.EstimateSize(item)
 	}
 }
-
-// =============================================================================
-// SHARDED CACHE BENCHMARKS
-// =============================================================================
-
-func BenchmarkShardedCache(b *testing.B) {
-	b.Run("Set", func(b *testing.B) {
-		cache := NewShardedCache(64, 100000)
-		b.ResetTimer()
-		for i := 0; i < b.N; i++ {
-			cache.Set(fmt.Sprintf("key-%d", i), i, 5*time.Minute)
-		}
-	})
-
-	b.Run("Get", func(b *testing.B) {
-		cache := NewShardedCache(64, 100000)
-		for i := 0; i < 10000; i++ {
-			cache.Set(fmt.Sprintf("key-%d", i), i, 5*time.Minute)
-		}
-		b.ResetTimer()
-		for i := 0; i < b.N; i++ {
-			cache.Get(fmt.Sprintf("key-%d", i%10000))
-		}
-	})
-
-	b.Run("ParallelSetGet", func(b *testing.B) {
-		cache := NewShardedCache(64, 100000)
-		b.RunParallel(func(pb *testing.PB) {
-			i := 0
-			for pb.Next() {
-				key := fmt.Sprintf("key-%d", i)
-				cache.Set(key, i, 5*time.Minute)
-				cache.Get(key)
-				i++
-			}
-		})
-	})
-}
-
-// BenchmarkShardedVsGlobalMutex compares sharded cache with global mutex approach
-func BenchmarkShardedVsGlobalMutex(b *testing.B) {
-	b.Run("ShardedCache64", func(b *testing.B) {
-		cache := NewShardedCache(64, 100000)
-		b.RunParallel(func(pb *testing.PB) {
-			i := 0
-			for pb.Next() {
-				key := fmt.Sprintf("jti-%d", i%10000)
-				if !cache.Exists(key) {
-					cache.Set(key, true, 5*time.Minute)
-				}
-				i++
-			}
-		})
-	})
-
-	b.Run("GlobalMutexCache", func(b *testing.B) {
-		var mu sync.RWMutex
-		data := make(map[string]bool)
-
-		b.RunParallel(func(pb *testing.PB) {
-			i := 0
-			for pb.Next() {
-				key := fmt.Sprintf("jti-%d", i%10000)
-
-				mu.RLock()
-				_, exists := data[key]
-				mu.RUnlock()
-
-				if !exists {
-					mu.Lock()
-					data[key] = true
-					mu.Unlock()
-				}
-				i++
-			}
-		})
-	})
-}

cache_manager.go

@@ -5,10 +5,6 @@ import (
 	"time"
 )
 
-const (
-	defaultBlacklistDuration = 24 * time.Hour
-)
-
 // CacheManager manages all caching components using the universal cache
 type CacheManager struct {
 	manager *UniversalCacheManager
@@ -107,7 +103,7 @@ func (cm *CacheManager) GetSharedMetadataCache() *MetadataCache {
 func (cm *CacheManager) GetSharedJWKCache() JWKCacheInterface {
 	cm.mu.RLock()
 	defer cm.mu.RUnlock()
-	return &JWKCache{cache: cm.manager.GetJWKCache()}
+	return &JWKCache{cache: cm.manager.GetJWKCache(), lastForceRefresh: make(map[string]time.Time)}
 }
 
 // GetSharedIntrospectionCache returns the shared token introspection cache
@@ -173,6 +169,13 @@ func (c *CacheInterfaceWrapper) Get(key string) (interface{}, bool) {
 	return c.cache.Get(key)
 }
 
+// SetIfAbsent atomically stores a value only if the key is not already
+// present. See UniversalCache.SetIfAbsent and AtomicSetIfAbsentCache
+// (FIX-17).
+func (c *CacheInterfaceWrapper) SetIfAbsent(key string, value interface{}, ttl time.Duration) (bool, error) {
+	return c.cache.SetIfAbsent(key, value, ttl)
+}
+
 // Delete removes a key
 func (c *CacheInterfaceWrapper) Delete(key string) {
 	c.cache.Delete(key)

cache_test.go

@@ -178,6 +178,11 @@ func TestCacheInterfaceWrapper_Clear(t *testing.T) {
 	cm := getTestCacheManager(t)
 	cache := cm.GetSharedTokenBlacklist()
 
+	// The shared token blacklist is process-global across tests; under shuffled
+	// execution a prior test may have left items behind. Clear first so the
+	// size assertions are stable regardless of test order.
+	cache.Clear()
+
 	cache.Set("key1", "value1", time.Hour)
 	cache.Set("key2", "value2", time.Hour)
 
@@ -465,314 +470,6 @@ func TestConcurrentCacheAccess(t *testing.T) {
 	wg.Wait()
 }
 
-// =============================================================================
-// SHARDED CACHE TESTS
-// =============================================================================
-
-func TestShardedCacheBasicOperations(t *testing.T) {
-	t.Run("SetAndGet", func(t *testing.T) {
-		cache := NewShardedCache(16, 1000)
-
-		cache.Set("key1", "value1", 5*time.Minute)
-		cache.Set("key2", 42, 5*time.Minute)
-		cache.Set("key3", true, 5*time.Minute)
-
-		val1, ok := cache.Get("key1")
-		if !ok || val1 != "value1" {
-			t.Errorf("Expected 'value1', got %v, ok=%v", val1, ok)
-		}
-
-		val2, ok := cache.Get("key2")
-		if !ok || val2 != 42 {
-			t.Errorf("Expected 42, got %v, ok=%v", val2, ok)
-		}
-
-		val3, ok := cache.Get("key3")
-		if !ok || val3 != true {
-			t.Errorf("Expected true, got %v, ok=%v", val3, ok)
-		}
-	})
-
-	t.Run("GetNonExistent", func(t *testing.T) {
-		cache := NewShardedCache(16, 1000)
-
-		val, ok := cache.Get("nonexistent")
-		if ok || val != nil {
-			t.Errorf("Expected nil/false for nonexistent key, got %v/%v", val, ok)
-		}
-	})
-
-	t.Run("Delete", func(t *testing.T) {
-		cache := NewShardedCache(16, 1000)
-
-		cache.Set("key1", "value1", 5*time.Minute)
-		cache.Delete("key1")
-
-		val, ok := cache.Get("key1")
-		if ok || val != nil {
-			t.Errorf("Expected nil/false after delete, got %v/%v", val, ok)
-		}
-	})
-
-	t.Run("Exists", func(t *testing.T) {
-		cache := NewShardedCache(16, 1000)
-
-		cache.Set("key1", "value1", 5*time.Minute)
-
-		if !cache.Exists("key1") {
-			t.Error("Expected Exists to return true for existing key")
-		}
-
-		if cache.Exists("nonexistent") {
-			t.Error("Expected Exists to return false for nonexistent key")
-		}
-	})
-
-	t.Run("Size", func(t *testing.T) {
-		cache := NewShardedCache(16, 1000)
-
-		if cache.Size() != 0 {
-			t.Errorf("Expected size 0, got %d", cache.Size())
-		}
-
-		for i := 0; i < 100; i++ {
-			cache.Set(fmt.Sprintf("key%d", i), i, 5*time.Minute)
-		}
-
-		if cache.Size() != 100 {
-			t.Errorf("Expected size 100, got %d", cache.Size())
-		}
-	})
-
-	t.Run("Clear", func(t *testing.T) {
-		cache := NewShardedCache(16, 1000)
-
-		for i := 0; i < 100; i++ {
-			cache.Set(fmt.Sprintf("key%d", i), i, 5*time.Minute)
-		}
-
-		cache.Clear()
-
-		if cache.Size() != 0 {
-			t.Errorf("Expected size 0 after clear, got %d", cache.Size())
-		}
-	})
-}
-
-func TestShardedCacheExpiration(t *testing.T) {
-	t.Run("ItemExpires", func(t *testing.T) {
-		cache := NewShardedCache(16, 1000)
-
-		cache.Set("key1", "value1", 50*time.Millisecond)
-
-		if !cache.Exists("key1") {
-			t.Error("Item should exist immediately after set")
-		}
-
-		time.Sleep(100 * time.Millisecond)
-
-		if cache.Exists("key1") {
-			t.Error("Item should have expired")
-		}
-	})
-
-	t.Run("CleanupRemovesExpired", func(t *testing.T) {
-		cache := NewShardedCache(16, 1000)
-
-		for i := 0; i < 50; i++ {
-			cache.Set(fmt.Sprintf("expired%d", i), i, 10*time.Millisecond)
-		}
-
-		for i := 0; i < 50; i++ {
-			cache.Set(fmt.Sprintf("valid%d", i), i, 5*time.Minute)
-		}
-
-		time.Sleep(50 * time.Millisecond)
-
-		cache.Cleanup()
-
-		for i := 0; i < 50; i++ {
-			if cache.Exists(fmt.Sprintf("expired%d", i)) {
-				t.Errorf("Expired item %d should not exist after cleanup", i)
-			}
-		}
-
-		for i := 0; i < 50; i++ {
-			if !cache.Exists(fmt.Sprintf("valid%d", i)) {
-				t.Errorf("Valid item %d should still exist after cleanup", i)
-			}
-		}
-	})
-
-	t.Run("ZeroTTLNeverExpires", func(t *testing.T) {
-		cache := NewShardedCache(16, 1000)
-
-		cache.Set("permanent", "value", 0)
-
-		time.Sleep(10 * time.Millisecond)
-
-		if !cache.Exists("permanent") {
-			t.Error("Item with 0 TTL should never expire")
-		}
-	})
-}
-
-func TestShardedCacheConcurrency(t *testing.T) {
-	t.Run("ConcurrentSetGet", func(t *testing.T) {
-		cache := NewShardedCache(64, 10000)
-		const numGoroutines = 100
-		const numOperations = 1000
-
-		var wg sync.WaitGroup
-		var errors int32
-
-		for i := 0; i < numGoroutines; i++ {
-			wg.Add(1)
-			go func(id int) {
-				defer wg.Done()
-				for j := 0; j < numOperations; j++ {
-					key := fmt.Sprintf("key-%d-%d", id, j)
-					cache.Set(key, j, 5*time.Minute)
-				}
-			}(i)
-		}
-
-		for i := 0; i < numGoroutines; i++ {
-			wg.Add(1)
-			go func(id int) {
-				defer wg.Done()
-				for j := 0; j < numOperations; j++ {
-					key := fmt.Sprintf("key-%d-%d", id, j)
-					cache.Get(key)
-				}
-			}(i)
-		}
-
-		wg.Wait()
-
-		if atomic.LoadInt32(&errors) > 0 {
-			t.Errorf("Encountered %d errors during concurrent access", errors)
-		}
-	})
-
-	t.Run("ConcurrentMixedOperations", func(t *testing.T) {
-		cache := NewShardedCache(64, 10000)
-		const numGoroutines = 50
-		const numOperations = 500
-
-		var wg sync.WaitGroup
-
-		for i := 0; i < numGoroutines; i++ {
-			wg.Add(1)
-			go func(id int) {
-				defer wg.Done()
-				for j := 0; j < numOperations; j++ {
-					key := fmt.Sprintf("key-%d", j%100)
-					switch j % 4 {
-					case 0:
-						cache.Set(key, j, 5*time.Minute)
-					case 1:
-						cache.Get(key)
-					case 2:
-						cache.Exists(key)
-					case 3:
-						cache.Delete(key)
-					}
-				}
-			}(i)
-		}
-
-		wg.Wait()
-	})
-
-	t.Run("NoConcurrentPanics", func(t *testing.T) {
-		cache := NewShardedCache(32, 5000)
-		const numGoroutines = 100
-
-		var wg sync.WaitGroup
-
-		for i := 0; i < numGoroutines; i++ {
-			wg.Add(1)
-			go func(id int) {
-				defer wg.Done()
-				defer func() {
-					if r := recover(); r != nil {
-						t.Errorf("Panic in goroutine %d: %v", id, r)
-					}
-				}()
-
-				for j := 0; j < 100; j++ {
-					cache.Set(fmt.Sprintf("k%d", j), j, time.Millisecond)
-					cache.Get(fmt.Sprintf("k%d", j))
-					cache.Cleanup()
-				}
-			}(i)
-		}
-
-		wg.Wait()
-	})
-}
-
-func TestShardedCacheEviction(t *testing.T) {
-	t.Run("EvictsWhenFull", func(t *testing.T) {
-		cache := NewShardedCache(4, 100)
-
-		for i := 0; i < 600; i++ {
-			cache.Set(fmt.Sprintf("key%d", i), i, 5*time.Minute)
-		}
-
-		size := cache.Size()
-		if size >= 600 {
-			t.Errorf("Expected eviction to reduce size below 600, got %d", size)
-		}
-		t.Logf("Cache size after adding 600 items: %d", size)
-	})
-
-	t.Run("EvictsExpiredFirst", func(t *testing.T) {
-		cache := NewShardedCache(4, 100)
-
-		for i := 0; i < 50; i++ {
-			cache.Set(fmt.Sprintf("expired%d", i), i, 1*time.Millisecond)
-		}
-
-		time.Sleep(10 * time.Millisecond)
-
-		for i := 0; i < 100; i++ {
-			cache.Set(fmt.Sprintf("valid%d", i), i, 5*time.Minute)
-		}
-
-		validCount := 0
-		for i := 0; i < 100; i++ {
-			if cache.Exists(fmt.Sprintf("valid%d", i)) {
-				validCount++
-			}
-		}
-
-		if validCount < 80 {
-			t.Errorf("Expected at least 80 valid items, got %d", validCount)
-		}
-	})
-}
-
-func TestShardedCacheShardDistribution(t *testing.T) {
-	t.Run("EvenDistribution", func(t *testing.T) {
-		cache := NewShardedCache(16, 16000)
-
-		for i := 0; i < 10000; i++ {
-			cache.Set(fmt.Sprintf("key-%d", i), i, 5*time.Minute)
-		}
-
-		stats := cache.ShardStats()
-
-		average := 10000 / 16
-		for i, count := range stats {
-			if count > average*3 || count < average/3 {
-				t.Errorf("Shard %d has uneven distribution: %d items (expected ~%d)", i, count, average)
-			}
-		}
-	})
-}
-
 // =============================================================================
 // CACHE COMPATIBILITY TESTS
 // =============================================================================

cache_test_helpers_test.go

@@ -0,0 +1,93 @@
+package traefikoidc
+
+// Shared CacheInterface / cache-backend test doubles for round-regression
+// tests.
+//
+// Moved here for FIX-41: NewMemoryBackendForTest, mapCache/newMapCache and
+// serializingCache were each declared inside a single round file (review_r124,
+// review_r146, review_r159) but consumed by other round files, so deleting or
+// renaming the declaring file silently broke the consumer. Every
+// review_rNN*_test.go file must depend only on shared helpers like this one,
+// never on another round file.
+
+import (
+	"encoding/json"
+	"github.com/alicebob/miniredis/v2"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/lukaszraczylo/traefikoidc/internal/cache/backends"
+)
+
+// NewMemoryBackendForTest returns a cache backend backed by an in-process
+// miniredis instance, for white-box tests that need a real CacheBackend
+// without depending on a live Redis server. internal/cache's in-memory
+// backend was removed as unreachable dead code (FIX-43); RedisBackend
+// against miniredis is the project's standard lightweight substitute.
+//
+// The miniredis server is registered against t.Cleanup so it (and its
+// listener goroutine) is closed when t ends. Callers still defer
+// backend.Close() to close the RedisBackend connection pool.
+func NewMemoryBackendForTest(t *testing.T) (backends.CacheBackend, error) {
+	t.Helper()
+	mr, err := miniredis.Run()
+	if err != nil {
+		return nil, err
+	}
+	t.Cleanup(mr.Close)
+	return backends.NewRedisBackend(backends.DefaultRedisConfig(mr.Addr()))
+}
+
+// mapCache is a minimal thread-safe CacheInterface for seeding caches in
+// bearer-invalidation tests.
+type mapCache struct {
+	mu sync.Mutex
+	m  map[string]any
+}
+
+func newMapCache() *mapCache { return &mapCache{m: map[string]any{}} }
+func (c *mapCache) Set(key string, value any, ttl time.Duration) {
+	c.mu.Lock()
+	c.m[key] = value
+	c.mu.Unlock()
+}
+func (c *mapCache) Get(key string) (any, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	v, ok := c.m[key]
+	return v, ok
+}
+func (c *mapCache) Delete(key string)        { c.mu.Lock(); delete(c.m, key); c.mu.Unlock() }
+func (c *mapCache) SetMaxSize(size int)      {}
+func (c *mapCache) Size() int                { return 0 }
+func (c *mapCache) Clear()                   {}
+func (c *mapCache) Cleanup()                 {}
+func (c *mapCache) Close()                   {}
+func (c *mapCache) GetStats() map[string]any { return nil }
+
+// serializingCache simulates a UniversalCache backed by a serializing
+// store (e.g. Redis): Set JSON-round-trips the value, so Get returns a
+// generic map, never the original concrete type. This is exactly what
+// production sees on the distributed path.
+type serializingCache struct {
+	m map[string]interface{}
+}
+
+func (c *serializingCache) Set(key string, value any, ttl time.Duration) {
+	b, _ := json.Marshal(value)
+	var v interface{}
+	_ = json.Unmarshal(b, &v)
+	c.m[key] = v
+}
+func (c *serializingCache) Get(key string) (any, bool) {
+	v, ok := c.m[key]
+	return v, ok
+}
+func (c *serializingCache) Delete(key string)        { delete(c.m, key) }
+func (c *serializingCache) SetMaxSize(int)           {}
+func (c *serializingCache) Size() int                { return len(c.m) }
+func (c *serializingCache) Clear()                   { c.m = map[string]interface{}{} }
+func (c *serializingCache) Cleanup()                 {}
+func (c *serializingCache) Close()                   {}
+func (c *serializingCache) GetStats() map[string]any { return nil }

client_assertion.go

@@ -3,6 +3,7 @@ package traefikoidc
 import (
 	"crypto"
 	"crypto/ecdsa"
+	"crypto/elliptic"
 	"crypto/rand"
 	"crypto/rsa"
 	"crypto/sha256"
@@ -12,6 +13,7 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"encoding/pem"
+	"errors"
 	"fmt"
 	"io"
 	"math/big"
@@ -19,6 +21,13 @@ import (
 	"time"
 )
 
+// ErrRSAKeyTooSmall is returned (wrapped) by validateAlgKeyMatch when a
+// private_key_jwt RS*/PS* signing key is smaller than the RFC 7518 §3.3
+// minimum of 2048 bits. A named sentinel lets callers detect this specific
+// rejection with errors.Is instead of matching the formatted message text
+// (FIX-42; see CHANGELOG.md).
+var ErrRSAKeyTooSmall = errors.New("RSA key too small for RS*/PS* signing (RFC 7518 §3.3 requires >= 2048 bits)")
+
 // isSupportedClientAssertionAlg reports whether alg is a recognized JWS
 // algorithm for private_key_jwt (RFC 7523 §2.2).
 func isSupportedClientAssertionAlg(alg string) bool {
@@ -94,13 +103,43 @@ func NewClientAssertionSigner(pemBytes []byte, alg, kid string) (*ClientAssertio
 func validateAlgKeyMatch(alg string, key crypto.PrivateKey) error {
 	switch alg[0] {
 	case 'R', 'P': // RS* or PS*
-		if _, ok := key.(*rsa.PrivateKey); !ok {
+		rsaKey, ok := key.(*rsa.PrivateKey)
+		if !ok {
 			return fmt.Errorf("alg %q requires an RSA key, got %T", alg, key)
 		}
+		// RFC 7518 §3.3: RS*/PS* MUST use a key of 2048 bits or larger.
+		// A smaller key signs locally but conformant IdPs (Entra, Okta,
+		// Keycloak) reject it, so every exchange/refresh/revocation fails
+		// invalid_client at runtime — better to fail at construction
+		// (R135).
+		if rsaKey.N.BitLen() < 2048 {
+			return fmt.Errorf("alg %q requires an RSA key of at least 2048 bits, got %d: %w", alg, rsaKey.N.BitLen(), ErrRSAKeyTooSmall)
+		}
 	case 'E': // ES*
-		if _, ok := key.(*ecdsa.PrivateKey); !ok {
+		ecKey, ok := key.(*ecdsa.PrivateKey)
+		if !ok {
 			return fmt.Errorf("alg %q requires an EC key, got %T", alg, key)
 		}
+		// ES* maps 1:1 to a NIST curve (ES256→P-256, ES384→P-384,
+		// ES512→P-521). A key on the wrong curve would otherwise pass this
+		// check yet always produce a signature the IdP rejects.
+		if want := ecdsaAlgorithmCurve(alg); want != nil && ecKey.Curve != want {
+			return fmt.Errorf("alg %q requires a key on curve %s, got %s", alg, want.Params().Name, ecKey.Curve.Params().Name)
+		}
+	}
+	return nil
+}
+
+// ecdsaAlgorithmCurve returns the NIST curve required by an ES* algorithm, or
+// nil for any non-ES algorithm.
+func ecdsaAlgorithmCurve(alg string) elliptic.Curve {
+	switch alg {
+	case "ES256":
+		return elliptic.P256()
+	case "ES384":
+		return elliptic.P384()
+	case "ES512":
+		return elliptic.P521()
 	}
 	return nil
 }
@@ -120,6 +159,14 @@ func (s *ClientAssertionSigner) Sign(audience, clientID string) (string, error)
 
 	now := nowFn()
 
+	// RFC 7523 §3: aud must be the token (or introspection/revocation)
+	// endpoint URL. An empty audience yields a client_assertion with
+	// "aud":"" that the IdP will reject, so fail fast with a clear
+	// error rather than minting a useless token (R150).
+	if audience == "" {
+		return "", fmt.Errorf("client assertion audience must not be empty")
+	}
+
 	// 16 random bytes as lowercase hex for jti uniqueness.
 	jtiBytes := make([]byte, 16)
 	if _, err := io.ReadFull(rander, jtiBytes); err != nil {
@@ -290,6 +337,3 @@ func buildClientAssertionSignerFromConfig(config *Config) (*ClientAssertionSigne
 
 	return NewClientAssertionSigner(pemBytes, alg, config.ClientAssertionKeyID)
 }
-
-
-

cmd/yaegicheck/main.go

@@ -9,17 +9,84 @@
 // symbol, reflection edge case, etc.) surfaces here rather than at Traefik load
 // time. CreateConfig + New additionally exercise the instantiation path
 // (session manager, cookie codec, caches, key derivation) under the interpreter.
+//
+// Beyond the load/instantiate path, this also drives CircuitBreaker and
+// RetryExecutor directly (FIX-09, FIX-14). yaegi v0.16.1 panics on
+// errors.As(err, &target) whenever target's pointed-to type is itself
+// interpreted ("errors: *target must be interface or implement error"), a
+// case native `go test`/`go build` cannot see because there the target type
+// is compiled, not interpreted. CircuitBreaker.ExecuteWithContext and
+// RetryExecutor.ExecuteSingleUseWithContext both ran such a check on every
+// fn() error, on the default-on token-exchange/refresh path, so this must
+// run under the real interpreter to catch it.
 package main
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io"
+	"net"
 	"net/http"
+	"net/http/httptest"
+	"net/http/httputil"
+	"net/url"
 	"os"
+	"sync"
+	"sync/atomic"
+	"time"
 
 	oidc "github.com/lukaszraczylo/traefikoidc"
+	recovery "github.com/lukaszraczylo/traefikoidc/internal/recovery"
+	servers "github.com/lukaszraczylo/traefikoidc/internal/testutil/servers"
 )
 
+// failingSetBackend is a minimal CacheBackend whose Set always fails with a
+// plain (non-timeout) error. It guards FIX-04: UniversalCache.Set must not
+// panic when isTimeoutOrDeadlineError inspects a non-timeout backend Set
+// error under the yaegi interpreter.
+type failingSetBackend struct{}
+
+func (failingSetBackend) Set(_ context.Context, _ string, _ []byte, _ time.Duration) error {
+	return errors.New("x")
+}
+func (failingSetBackend) Get(_ context.Context, _ string) ([]byte, time.Duration, bool, error) {
+	return nil, 0, false, nil
+}
+func (failingSetBackend) Delete(_ context.Context, _ string) (bool, error) { return false, nil }
+func (failingSetBackend) Exists(_ context.Context, _ string) (bool, error) { return false, nil }
+func (failingSetBackend) Clear(_ context.Context) error                    { return nil }
+func (failingSetBackend) GetStats() map[string]interface{}                 { return nil }
+func (failingSetBackend) Close() error                                     { return nil }
+func (failingSetBackend) Ping(_ context.Context) error                     { return nil }
+
+// checkUniversalCacheSetDoesNotPanicOnBackendError guards FIX-04: in Redis
+// mode, UniversalCache.Set must degrade to the local write on any
+// non-timeout backend Set error instead of panicking. errors.As against an
+// anonymous interface target panics under yaegi v0.16.1, so a native `go
+// test` run cannot see this; only the interpreter can.
+func checkUniversalCacheSetDoesNotPanicOnBackendError() {
+	defer func() {
+		if r := recover(); r != nil {
+			fmt.Println("FAIL: UniversalCache.Set panicked on a non-timeout backend Set error:", r)
+			os.Exit(1)
+		}
+	}()
+
+	cache := oidc.NewUniversalCacheWithBackend(oidc.UniversalCacheConfig{
+		Logger:     oidc.NewLogger("error"),
+		Type:       oidc.CacheTypeToken,
+		DefaultTTL: time.Minute,
+	}, failingSetBackend{})
+	defer cache.Close()
+
+	if err := cache.Set("yaegi-check-key", "v", time.Minute); err != nil {
+		fmt.Println("FAIL: UniversalCache.Set returned an unexpected error:", err)
+		os.Exit(1)
+	}
+	fmt.Println("OK: UniversalCache.Set did not panic on a non-timeout backend Set error under yaegi")
+}
+
 func main() {
 	cfg := oidc.CreateConfig()
 	cfg.ProviderURL = "https://accounts.google.com"
@@ -43,4 +110,791 @@ func main() {
 		_ = closer.Close()
 	}
 	fmt.Println("OK: traefikoidc imported + CreateConfig + New succeeded under yaegi")
+
+	checkUniversalCacheSetDoesNotPanicOnBackendError()
+
+	runCheck("fix09-plain-error", checkFix09PlainError)
+	runCheck("fix09-halfopen-400-stays-halfopen", checkFix09HalfOpenTerminalStaysHalfOpen)
+	runCheck("fix09-closed-400-stays-closed", checkFix09ClosedTerminalStaysClosed)
+	runCheck("fix09-429-reopens", checkFix09RateLimitReopens)
+	runCheck("fix14-httperror-once", checkFix14HTTPErrorNeverRetried)
+	runCheck("fix14-real-dial-retried", checkFix14RealDialRetried)
+
+	// NEW-01: errors.As(err, &target) panics under yaegi v0.16.1 whenever
+	// target's pointed-to type is interpreted (*HTTPError, *OIDCError are
+	// both declared in this plugin / internal/recovery, so always are),
+	// regardless of err's own concrete type. These checks drive every
+	// reachable errors.As-replacement site directly under the interpreter.
+	runCheck("new01-retryexecutor-500-retried", checkNew01RetryExecutorHTTPError500Retried)
+	runCheck("new01-retryexecutor-400-not-retried", checkNew01RetryExecutorHTTPError400NotRetried)
+	runCheck("new01-retryexecutor-plain-error-no-panic", checkNew01RetryExecutorPlainErrorNoPanic)
+	runCheck("new01-internal-recovery-httperror-classification", checkNew01InternalRecoveryHTTPErrorClassification)
+	runCheck("new01-internal-recovery-oidcerror-classification", checkNew01InternalRecoveryOIDCErrorClassification)
+	runCheck("new01-introspection-bearer-4xx-no-panic", checkNew01IntrospectionBearer4xxNoPanic)
+	runCheck("new01-introspection-bearer-5xx-no-panic", checkNew01IntrospectionBearer5xxNoPanic)
+	runCheck("new01-opaque-session-introspection-classification", checkNew01OpaqueSessionIntrospectionClassification)
+
+	runCheck("fix06-sse-flush-reaches-next", checkSSEFlushReachesNext)
+	runCheck("middleware-erraborthandler-aborts-under-yaegi", checkErrAbortHandlerAbortsUnderYaegi)
+	runCheck("fix17-setifabsent-claims-once", checkSetIfAbsentUnderYaegi)
+	fmt.Println("OK: all yaegi regression checks passed")
+}
+
+// runCheck runs one named regression check and exits the process on
+// failure, matching this command's existing OK/FAIL reporting style. detail
+// is appended to the PASS line verbatim (e.g. " calls=3"), or empty.
+func runCheck(name string, fn func() (string, error)) {
+	detail, err := fn()
+	if err != nil {
+		fmt.Printf("FAIL %s: %v\n", name, err)
+		os.Exit(1)
+	}
+	fmt.Printf("PASS %s%s\n", name, detail)
+}
+
+// circuitStateName renders a CircuitBreakerState for FAIL messages.
+func circuitStateName(s oidc.CircuitBreakerState) string {
+	switch s {
+	case oidc.CircuitBreakerClosed:
+		return "closed"
+	case oidc.CircuitBreakerOpen:
+		return "open"
+	case oidc.CircuitBreakerHalfOpen:
+		return "half-open"
+	default:
+		return "unknown"
+	}
+}
+
+// checkFix09PlainError drives CircuitBreaker.ExecuteWithContext with a
+// plain (non-HTTPError) error, the call shape that panicked first under the
+// pre-fix isTerminalClientError: errors.As against an interpreted *HTTPError
+// target panics under yaegi regardless of the error's own concrete type,
+// because the check runs on every fn() error.
+func checkFix09PlainError() (string, error) {
+	cb := oidc.NewCircuitBreaker(oidc.CircuitBreakerConfig{
+		MaxFailures:  1,
+		Timeout:      50 * time.Millisecond,
+		ResetTimeout: 50 * time.Millisecond,
+	}, oidc.NewLogger("error"))
+
+	err := cb.ExecuteWithContext(context.Background(), func() error {
+		return errors.New("boom")
+	})
+	if err == nil {
+		return "", fmt.Errorf("expected the plain error to be returned")
+	}
+	if cb.GetState() != oidc.CircuitBreakerOpen {
+		return "", fmt.Errorf("expected a plain error to trip the breaker open, got %s", circuitStateName(cb.GetState()))
+	}
+	return "", nil
+}
+
+// newHalfOpenBreaker builds a breaker, trips it with one real (non client)
+// failure, and waits past Timeout so the next ExecuteWithContext call
+// performs the Open -> HalfOpen probe transition itself.
+func newHalfOpenBreaker() *oidc.CircuitBreaker {
+	cb := oidc.NewCircuitBreaker(oidc.CircuitBreakerConfig{
+		MaxFailures:  1,
+		Timeout:      100 * time.Millisecond,
+		ResetTimeout: 50 * time.Millisecond,
+	}, oidc.NewLogger("error"))
+
+	_ = cb.ExecuteWithContext(context.Background(), func() error {
+		return &oidc.HTTPError{StatusCode: 500, Message: "downstream unavailable"}
+	})
+	time.Sleep(150 * time.Millisecond)
+	return cb
+}
+
+// checkFix09HalfOpenTerminalStaysHalfOpen pins FIX-09: a terminal client 4xx
+// (e.g. invalid_grant) must not reopen a half-open circuit.
+func checkFix09HalfOpenTerminalStaysHalfOpen() (string, error) {
+	cb := newHalfOpenBreaker()
+
+	err := cb.ExecuteWithContext(context.Background(), func() error {
+		return &oidc.HTTPError{StatusCode: 400, Message: "invalid_grant"}
+	})
+	if err == nil {
+		return "", fmt.Errorf("expected the probe's own error to be returned")
+	}
+	if cb.GetState() != oidc.CircuitBreakerHalfOpen {
+		return "", fmt.Errorf("a terminal client 4xx must not reopen a half-open circuit, got %s", circuitStateName(cb.GetState()))
+	}
+	return "", nil
+}
+
+// checkFix09ClosedTerminalStaysClosed pins that the same exemption applies
+// in the Closed state: a terminal client 4xx must not trip the breaker.
+func checkFix09ClosedTerminalStaysClosed() (string, error) {
+	cb := oidc.NewCircuitBreaker(oidc.CircuitBreakerConfig{
+		MaxFailures:  1,
+		Timeout:      50 * time.Millisecond,
+		ResetTimeout: 50 * time.Millisecond,
+	}, oidc.NewLogger("error"))
+
+	err := cb.ExecuteWithContext(context.Background(), func() error {
+		return &oidc.HTTPError{StatusCode: 400, Message: "invalid_grant"}
+	})
+	if err == nil {
+		return "", fmt.Errorf("expected the probe's own error to be returned")
+	}
+	if cb.GetState() != oidc.CircuitBreakerClosed {
+		return "", fmt.Errorf("a terminal client 4xx must not trip a closed circuit, got %s", circuitStateName(cb.GetState()))
+	}
+	return "", nil
+}
+
+// checkFix09RateLimitReopens guards against over-broadening FIX-09: a 429
+// (the service itself signaling overload) must still reopen a half-open
+// circuit.
+func checkFix09RateLimitReopens() (string, error) {
+	cb := newHalfOpenBreaker()
+
+	err := cb.ExecuteWithContext(context.Background(), func() error {
+		return &oidc.HTTPError{StatusCode: 429, Message: "rate limited"}
+	})
+	if err == nil {
+		return "", fmt.Errorf("expected the probe's own error to be returned")
+	}
+	if cb.GetState() != oidc.CircuitBreakerOpen {
+		return "", fmt.Errorf("a 429 must still reopen a half-open circuit, got %s", circuitStateName(cb.GetState()))
+	}
+	return "", nil
+}
+
+// checkFix14HTTPErrorNeverRetried pins FIX-14: a *HTTPError proves a
+// response was received, so ExecuteSingleUseWithContext must never retry
+// it even when its Message (up to 10 KiB of a real IdP response body, see
+// helpers.go) happens to contain a singleUseRetryableErrors fragment such
+// as "connection refused".
+func checkFix14HTTPErrorNeverRetried() (string, error) {
+	re := oidc.NewRetryExecutor(oidc.RetryConfig{
+		MaxAttempts:   3,
+		InitialDelay:  1 * time.Millisecond,
+		MaxDelay:      1 * time.Millisecond,
+		BackoffFactor: 1,
+	}, oidc.NewLogger("error"))
+
+	calls := 0
+	err := re.ExecuteSingleUseWithContext(context.Background(), func() error {
+		calls++
+		return &oidc.HTTPError{
+			StatusCode: 500,
+			Message:    "token endpoint returned status 500: {\"error\":\"server_error\",\"detail\":\"upstream: connection refused\"}",
+		}
+	})
+	if err == nil {
+		return "", fmt.Errorf("expected the HTTPError to be returned")
+	}
+	if calls != 1 {
+		return "", fmt.Errorf("fn called %d times, want 1", calls)
+	}
+	return fmt.Sprintf(" calls=%d", calls), nil
+}
+
+// checkFix14RealDialRetried guards against over-broadening FIX-14: a real
+// client.Do dial failure (net/http wraps it as *net.OpError, reached via
+// errors.As unwrapping any %w chain) proves the request never reached the
+// server and must still be retried.
+func checkFix14RealDialRetried() (string, error) {
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return "", fmt.Errorf("setup: %w", err)
+	}
+	addr := ln.Addr().String()
+	ln.Close()
+
+	re := oidc.NewRetryExecutor(oidc.RetryConfig{
+		MaxAttempts:   3,
+		InitialDelay:  1 * time.Millisecond,
+		MaxDelay:      1 * time.Millisecond,
+		BackoffFactor: 1,
+	}, oidc.NewLogger("error"))
+
+	client := &http.Client{Timeout: 3 * time.Second}
+	calls := 0
+	execErr := re.ExecuteSingleUseWithContext(context.Background(), func() error {
+		calls++
+		resp, derr := client.Get("http://" + addr + "/")
+		if derr != nil {
+			return fmt.Errorf("token endpoint request failed: %w", derr)
+		}
+		resp.Body.Close()
+		return nil
+	})
+	if execErr == nil {
+		return "", fmt.Errorf("expected the dial failure to be returned after exhausting retries")
+	}
+	if calls != 3 {
+		return "", fmt.Errorf("fn called %d times, want 3", calls)
+	}
+	return fmt.Sprintf(" calls=%d", calls), nil
+}
+
+// checkNew01RetryExecutorHTTPError500Retried pins NEW-01: RetryExecutor's
+// isRetryableError classifies an *HTTPError via asHTTPError, a plain type
+// assertion plus an errors.Unwrap walk, NOT errors.As -- errors.As(err,
+// &target) panics under yaegi v0.16.1 whenever target's pointed-to type is
+// interpreted, and *HTTPError is declared in this plugin so it always is,
+// regardless of err's own concrete type (error_recovery.go, isRetryableError
+// ~line 764/821). A 500 is a transient server error and must be retried to
+// MaxAttempts.
+func checkNew01RetryExecutorHTTPError500Retried() (string, error) {
+	re := oidc.NewRetryExecutor(oidc.RetryConfig{
+		MaxAttempts:   3,
+		InitialDelay:  1 * time.Millisecond,
+		MaxDelay:      1 * time.Millisecond,
+		BackoffFactor: 1,
+	}, oidc.NewLogger("error"))
+
+	calls := 0
+	err := re.ExecuteWithContext(context.Background(), func() error {
+		calls++
+		return &oidc.HTTPError{StatusCode: 500, Message: "downstream unavailable"}
+	})
+	if err == nil {
+		return "", fmt.Errorf("expected the HTTPError to be returned after exhausting retries")
+	}
+	if calls != 3 {
+		return "", fmt.Errorf("fn called %d times, want 3 (a 500 must be retried)", calls)
+	}
+	return fmt.Sprintf(" calls=%d", calls), nil
+}
+
+// checkNew01RetryExecutorHTTPError400NotRetried is checkNew01RetryExecutorHTTPError500Retried's
+// counterpart: a terminal 4xx (other than 429) must NOT be retried.
+func checkNew01RetryExecutorHTTPError400NotRetried() (string, error) {
+	re := oidc.NewRetryExecutor(oidc.RetryConfig{
+		MaxAttempts:   3,
+		InitialDelay:  1 * time.Millisecond,
+		MaxDelay:      1 * time.Millisecond,
+		BackoffFactor: 1,
+	}, oidc.NewLogger("error"))
+
+	calls := 0
+	err := re.ExecuteWithContext(context.Background(), func() error {
+		calls++
+		return &oidc.HTTPError{StatusCode: 400, Message: "invalid_grant"}
+	})
+	if err == nil {
+		return "", fmt.Errorf("expected the HTTPError to be returned")
+	}
+	if calls != 1 {
+		return "", fmt.Errorf("fn called %d times, want 1 (a terminal 400 must not be retried)", calls)
+	}
+	return fmt.Sprintf(" calls=%d", calls), nil
+}
+
+// checkNew01RetryExecutorPlainErrorNoPanic pins that a plain (non-HTTPError)
+// error reaching isRetryableError's asHTTPError check never panics under
+// yaegi -- the exact call shape that panicked pre-fix regardless of err's
+// own concrete type (see asHTTPError's doc comment, error_recovery.go).
+func checkNew01RetryExecutorPlainErrorNoPanic() (string, error) {
+	re := oidc.NewRetryExecutor(oidc.RetryConfig{
+		MaxAttempts:   3,
+		InitialDelay:  1 * time.Millisecond,
+		MaxDelay:      1 * time.Millisecond,
+		BackoffFactor: 1,
+	}, oidc.NewLogger("error"))
+
+	calls := 0
+	err := re.ExecuteWithContext(context.Background(), func() error {
+		calls++
+		return errors.New("boom")
+	})
+	if err == nil {
+		return "", fmt.Errorf("expected the plain error to be returned")
+	}
+	if calls != 1 {
+		return "", fmt.Errorf("fn called %d times, want 1 (an unrecognized plain error must not be retried)", calls)
+	}
+	return fmt.Sprintf(" calls=%d", calls), nil
+}
+
+// checkNew01InternalRecoveryHTTPErrorClassification covers
+// internal/recovery/metrics.go's RetryExecutor.isRetryableError, which has
+// its OWN *HTTPError type (interpreted, same yaegi hazard as the top-level
+// package's) and is reachable under yaegi because the traefikoidc plugin
+// imports internal/recovery transitively (internal/utils/logger_wrapper.go),
+// forcing yaegi to interpret it when the plugin loads.
+func checkNew01InternalRecoveryHTTPErrorClassification() (string, error) {
+	retryCfg := recovery.RetryConfig{
+		MaxAttempts:          3,
+		InitialDelay:         1 * time.Millisecond,
+		MaxDelay:             1 * time.Millisecond,
+		Multiplier:           1,
+		RetryableStatusCodes: []int{500, 503},
+	}
+
+	calls500 := 0
+	err := recovery.NewRetryExecutor(retryCfg, nil).ExecuteWithContext(context.Background(), func() error {
+		calls500++
+		return &recovery.HTTPError{StatusCode: 500, Message: "downstream unavailable"}
+	})
+	if err == nil {
+		return "", fmt.Errorf("500: expected the HTTPError to be returned after exhausting retries")
+	}
+	if calls500 != 3 {
+		return "", fmt.Errorf("500: fn called %d times, want 3", calls500)
+	}
+
+	calls400 := 0
+	err = recovery.NewRetryExecutor(retryCfg, nil).ExecuteWithContext(context.Background(), func() error {
+		calls400++
+		return &recovery.HTTPError{StatusCode: 400, Message: "bad request"}
+	})
+	if err == nil {
+		return "", fmt.Errorf("400: expected the HTTPError to be returned")
+	}
+	if calls400 != 1 {
+		return "", fmt.Errorf("400: fn called %d times, want 1", calls400)
+	}
+
+	return fmt.Sprintf(" calls500=%d calls400=%d", calls500, calls400), nil
+}
+
+// checkNew01InternalRecoveryOIDCErrorClassification is
+// checkNew01InternalRecoveryHTTPErrorClassification's counterpart for
+// internal/recovery's *OIDCError (also interpreted, also reached via
+// errors.As pre-fix).
+func checkNew01InternalRecoveryOIDCErrorClassification() (string, error) {
+	retryCfg := recovery.RetryConfig{
+		MaxAttempts:  3,
+		InitialDelay: 1 * time.Millisecond,
+		MaxDelay:     1 * time.Millisecond,
+		Multiplier:   1,
+	}
+
+	callsRetryable := 0
+	err := recovery.NewRetryExecutor(retryCfg, nil).ExecuteWithContext(context.Background(), func() error {
+		callsRetryable++
+		return &recovery.OIDCError{Code: "temporarily_unavailable", Description: "busy"}
+	})
+	if err == nil {
+		return "", fmt.Errorf("retryable: expected the OIDCError to be returned after exhausting retries")
+	}
+	if callsRetryable != 3 {
+		return "", fmt.Errorf("retryable: fn called %d times, want 3", callsRetryable)
+	}
+
+	callsTerminal := 0
+	err = recovery.NewRetryExecutor(retryCfg, nil).ExecuteWithContext(context.Background(), func() error {
+		callsTerminal++
+		return &recovery.OIDCError{Code: "invalid_grant", Description: "nope"}
+	})
+	if err == nil {
+		return "", fmt.Errorf("terminal: expected the OIDCError to be returned")
+	}
+	if callsTerminal != 1 {
+		return "", fmt.Errorf("terminal: fn called %d times, want 1", callsTerminal)
+	}
+
+	return fmt.Sprintf(" callsRetryable=%d callsTerminal=%d", callsRetryable, callsTerminal), nil
+}
+
+// checkNew01IntrospectionBearerStatus builds a full plugin instance with
+// bearer auth + mandatory introspection enabled, points IntrospectionURL at
+// a controllable server returning wantStatus, and drives one bearer request
+// carrying an opaque (non-JWT) token through introspectToken end-to-end
+// under yaegi. introspectToken is the shared producer for BOTH the bearer
+// path (bearer_auth.go) and the session path (token_validation_rs.go, the
+// NEW-01 fix site); this proves the round trip -- discovery, introspection
+// POST, error classification, response write -- never panics under the real
+// interpreter for a 4xx or a 5xx introspection response.
+func checkNew01IntrospectionBearerStatus(wantStatus int) (string, error) {
+	discovery := servers.NewOIDCServer(nil)
+	defer discovery.Close()
+
+	introspect := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(wantStatus)
+	}))
+	defer introspect.Close()
+
+	cfg := oidc.CreateConfig()
+	cfg.ProviderURL = discovery.URL
+	cfg.ClientID = "yaegi-check-bearer-client"
+	cfg.ClientSecret = "yaegi-check-bearer-secret"
+	cfg.CallbackURL = "/oauth2/callback"
+	cfg.SessionEncryptionKey = "0123456789abcdef0123456789abcdef"
+	cfg.RateLimit = 100
+	cfg.EnableBearerAuth = true
+	cfg.Audience = cfg.ClientID
+	cfg.RequireTokenIntrospection = true
+	cfg.AllowOpaqueTokens = true
+	cfg.IntrospectionURL = introspect.URL
+
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {})
+	h, err := oidc.New(context.Background(), next, cfg, fmt.Sprintf("yaegi-check-bearer-%d", wantStatus))
+	if err != nil {
+		return "", fmt.Errorf("New: %w", err)
+	}
+	if closer, ok := h.(interface{ Close() error }); ok {
+		defer closer.Close()
+	}
+
+	req := httptest.NewRequest("GET", "/protected", nil)
+	req.Header.Set("Authorization", "Bearer opaque-test-token-without-dots")
+	rw := httptest.NewRecorder()
+	h.ServeHTTP(rw, req)
+
+	// Every introspectToken error on the bearer path -- 4xx or 5xx alike --
+	// maps to bearerErrIntrospectionUnavailable, a 503 (bearer_auth.go). A
+	// recovered errors.As panic answers a DIFFERENT status: ServeHTTP's own
+	// deferred recover turns any panic into 500 (middleware.go), and
+	// httptest.NewRecorder starts at Code 200, so neither of those values
+	// can be mistaken for the real 503. rw.Code == 0 (the previous check
+	// here) can never happen -- the Recorder never leaves that zero value --
+	// so it accepted a recovered panic silently. Require the exact expected
+	// value instead.
+	if rw.Code != http.StatusServiceUnavailable {
+		return "", fmt.Errorf("expected response_status=%d (bearerErrIntrospectionUnavailable) for introspection_status=%d, got %d", http.StatusServiceUnavailable, wantStatus, rw.Code)
+	}
+	return fmt.Sprintf(" introspection_status=%d response_status=%d", wantStatus, rw.Code), nil
+}
+
+func checkNew01IntrospectionBearer4xxNoPanic() (string, error) {
+	return checkNew01IntrospectionBearerStatus(http.StatusTooManyRequests)
+}
+
+func checkNew01IntrospectionBearer5xxNoPanic() (string, error) {
+	return checkNew01IntrospectionBearerStatus(http.StatusInternalServerError)
+}
+
+// checkNew01OpaqueSessionIntrospectionClassification drives the SESSION
+// path fixed by commit d7686c3, which checkNew01IntrospectionBearerStatus
+// above does not reach: an authenticated cookie session holding an opaque
+// access token, validated via isUserAuthenticatedRS ->
+// validateStandardTokensRS -> validateOpaqueToken, when introspection
+// answers a 5xx. Before d7686c3, validateStandardTokensRS classified
+// validateOpaqueToken's error with errors.As(err, &httpErr) against
+// *HTTPError -- interpreted under yaegi v0.16.1, so this panicked on every
+// opaque-token session-path classification regardless of introspection
+// status. The bearer path shares introspectToken but never reaches this
+// call site, so a yaegicheck suite that only drove the bearer path could
+// not have caught this.
+//
+// A cookie session is built directly (New's session manager is an
+// unexported field, unreachable from this package) with a second
+// SessionManager sharing the exact cfg fields oidc.New passes into its own
+// NewSessionManager call (SessionEncryptionKey, ForceHTTPS, CookieDomain,
+// CookiePrefix, SessionMaxAge). The cookie codec key is a deterministic
+// function of those inputs alone (deriveCookieKeys, no per-instance
+// randomness), so a cookie minted here decodes identically in the plugin's
+// own session manager.
+func checkNew01OpaqueSessionIntrospectionClassification() (string, error) {
+	discovery := servers.NewOIDCServer(nil)
+	defer discovery.Close()
+
+	// introspectionRequests counts requests that actually reach the
+	// introspection endpoint. A 302 alone does not prove ServeHTTP got as
+	// far as introspectToken/validateOpaqueToken (commit d7686c3's fix
+	// site) -- an unauthenticated request with no session at all also ends
+	// in a 302, to the same provider, without ever calling introspection.
+	// If the cookie rebuilt through the second SessionManager below ever
+	// stops decoding, this check would otherwise still print PASS while
+	// exercising nothing.
+	var introspectionRequests int32
+	introspect := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&introspectionRequests, 1)
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer introspect.Close()
+
+	cfg := oidc.CreateConfig()
+	cfg.ProviderURL = discovery.URL
+	cfg.ClientID = "yaegi-check-session-client"
+	cfg.ClientSecret = "yaegi-check-session-secret"
+	cfg.CallbackURL = "/oauth2/callback"
+	cfg.SessionEncryptionKey = "0123456789abcdef0123456789abcdef"
+	cfg.RateLimit = 100
+	cfg.AllowOpaqueTokens = true
+	cfg.RequireTokenIntrospection = true
+	cfg.IntrospectionURL = introspect.URL
+
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {})
+	h, err := oidc.New(context.Background(), next, cfg, "yaegi-check-session")
+	if err != nil {
+		return "", fmt.Errorf("New: %w", err)
+	}
+	if closer, ok := h.(interface{ Close() error }); ok {
+		defer closer.Close()
+	}
+
+	sm, err := oidc.NewSessionManager(cfg.SessionEncryptionKey, cfg.ForceHTTPS, cfg.CookieDomain, cfg.CookiePrefix, time.Duration(cfg.SessionMaxAge)*time.Second, oidc.NewLogger("error"))
+	if err != nil {
+		return "", fmt.Errorf("NewSessionManager: %w", err)
+	}
+	defer sm.Shutdown()
+
+	setupReq := httptest.NewRequest("GET", "/protected", nil)
+	session, err := sm.GetSession(setupReq)
+	if err != nil {
+		return "", fmt.Errorf("GetSession: %w", err)
+	}
+	if err := session.SetAuthenticated(true); err != nil {
+		return "", fmt.Errorf("SetAuthenticated: %w", err)
+	}
+	// No dots: isOpaqueToken (validateStandardTokensRS) reads it as opaque,
+	// routing it into validateOpaqueToken/introspectToken instead of JWT
+	// parsing. No refresh token is set, so a classification of "not
+	// verifiable, requireTokenIntrospection fails closed" resolves
+	// deterministically to expired (not needsRefresh) below.
+	session.SetAccessToken("opaque-session-token-without-dots")
+	rec := httptest.NewRecorder()
+	if err := session.Save(setupReq, rec); err != nil {
+		return "", fmt.Errorf("session.Save: %w", err)
+	}
+	session.ReturnToPool()
+
+	req := httptest.NewRequest("GET", "/protected", nil)
+	for _, c := range rec.Result().Cookies() {
+		req.AddCookie(c)
+	}
+	rw := httptest.NewRecorder()
+	h.ServeHTTP(rw, req)
+
+	// requireTokenIntrospection=true with no refresh token classifies a
+	// 5xx-introspection opaque access token as expired (not "token
+	// invalid", which is reserved for a definitive active=false/expired/
+	// revoked introspection body -- RFC 7662 s2.2/s2.3): ServeHTTP responds
+	// with handleExpiredToken -> defaultInitiateAuthentication, a 302 to
+	// the provider. A reintroduced errors.As panic is instead recovered by
+	// ServeHTTP's own deferred recover as a 500, before t.next is ever
+	// reached -- a status this check must reject just as firmly as the 200
+	// (rw.Code's unwritten zero value can never appear here either) a
+	// silently-swallowed panic could otherwise produce.
+	if rw.Code != http.StatusFound {
+		return "", fmt.Errorf("expected response_status=%d (re-authentication redirect) for a 5xx introspection response on the session path, got %d", http.StatusFound, rw.Code)
+	}
+	// A 302 alone is not proof this check reached the session-path
+	// classification: an unauthenticated request with no cookie at all
+	// also redirects with 302, without ever calling introspectToken. Only
+	// a non-zero introspection hit count proves the request got as far as
+	// validateOpaqueToken.
+	if got := atomic.LoadInt32(&introspectionRequests); got < 1 {
+		return "", fmt.Errorf("expected at least one request to reach the introspection endpoint (proving the check reached validateOpaqueToken/introspectToken), got %d -- a %d response alone does not prove this, since an unauthenticated request with no session also redirects with %d", got, rw.Code, http.StatusFound)
+	}
+	return fmt.Sprintf(" response_status=%d", rw.Code), nil
+}
+
+// checkSSEFlushReachesNext pins FIX-06: the writer ServeHTTP hands to next
+// must support http.NewResponseController(w).Flush() under yaegi. Before
+// the fix, next received the interpreted *trackingWriter, which exposes no
+// Flusher across the interpreter boundary, so SSE responses were buffered
+// in Traefik. The excluded-URL bypass reaches next without a session.
+func checkSSEFlushReachesNext() (string, error) {
+	cfg := oidc.CreateConfig()
+	cfg.ProviderURL = "https://accounts.google.com"
+	cfg.ClientID = "yaegi-check-client"
+	cfg.ClientSecret = "yaegi-check-secret"
+	cfg.CallbackURL = "/oauth2/callback"
+	cfg.SessionEncryptionKey = "0123456789abcdef0123456789abcdef"
+	cfg.ExcludedURLs = []string{"/public"}
+
+	var flushErr error
+	reached := false
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		reached = true
+		w.Header().Set("Content-Type", "text/event-stream")
+		_, _ = w.Write([]byte("data: 1\n\n"))
+		flushErr = http.NewResponseController(w).Flush()
+	})
+	h, err := oidc.New(context.Background(), next, cfg, "yaegi-sse")
+	if err != nil {
+		return "", fmt.Errorf("New: %v", err)
+	}
+	if closer, ok := h.(interface{ Close() error }); ok {
+		defer func() { _ = closer.Close() }()
+	}
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/public/stream", nil)
+	req.Header.Set("Accept", "text/event-stream")
+	h.ServeHTTP(rec, req)
+	if !reached {
+		return "", fmt.Errorf("next was not reached (status %d)", rec.Code)
+	}
+	if flushErr != nil {
+		return "", fmt.Errorf("Flush on the writer handed to next failed: %v", flushErr)
+	}
+	if !rec.Flushed {
+		return "", fmt.Errorf("the underlying writer was not flushed")
+	}
+	return "", nil
+}
+
+// checkErrAbortHandlerAbortsUnderYaegi guards the re-review finding on
+// ServeHTTP's ErrAbortHandler branch (middleware.go): under yaegi v0.16.1,
+// `r == http.ErrAbortHandler` only ever matches a panic raised by COMPILED
+// code -- which is exactly the real production shape, since only this
+// plugin runs interpreted; every `next` handler downstream of it
+// (Traefik's own router, a compiled httputil.ReverseProxy) is compiled.
+// This drives that shape end-to-end under the interpreter: a live
+// front-facing server running the interpreted plugin, whose next is a
+// compiled httputil.ReverseProxy pointed at an upstream that writes a
+// partial chunk, flushes it to the client, then Hijacks and closes the raw
+// connection mid-stream -- the same way copyResponse
+// (net/http/httputil/reverseproxy.go) panics with http.ErrAbortHandler
+// when the upstream body read fails after headers were already sent. The
+// client must observe the aborted connection (a non-nil read error on the
+// truncated body), never a clean 200. Do not assign rp.ErrorLog: yaegi
+// v0.16.1 rejects the *log.Logger field assignment.
+func checkErrAbortHandlerAbortsUnderYaegi() (string, error) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		_, _ = w.Write([]byte("partial-chunk"))
+		if f, ok := w.(http.Flusher); ok {
+			f.Flush()
+		}
+		hj, ok := w.(http.Hijacker)
+		if !ok {
+			return
+		}
+		conn, _, hjErr := hj.Hijack()
+		if hjErr != nil {
+			return
+		}
+		_ = conn.Close()
+	}))
+	defer upstream.Close()
+
+	upstreamURL, err := url.Parse(upstream.URL)
+	if err != nil {
+		return "", fmt.Errorf("parse upstream URL: %w", err)
+	}
+	rp := httputil.NewSingleHostReverseProxy(upstreamURL)
+
+	cfg := oidc.CreateConfig()
+	cfg.ProviderURL = "https://accounts.google.com"
+	cfg.ClientID = "yaegi-check-abort-client"
+	cfg.ClientSecret = "yaegi-check-abort-secret"
+	cfg.CallbackURL = "/oauth2/callback"
+	cfg.SessionEncryptionKey = "0123456789abcdef0123456789abcdef"
+	cfg.ExcludedURLs = []string{"/public"}
+
+	h, err := oidc.New(context.Background(), rp, cfg, "yaegi-check-abort")
+	if err != nil {
+		return "", fmt.Errorf("New: %w", err)
+	}
+	if closer, ok := h.(interface{ Close() error }); ok {
+		defer func() { _ = closer.Close() }()
+	}
+
+	front := httptest.NewServer(h)
+	defer front.Close()
+
+	resp, err := http.Get(front.URL + "/public")
+	if err != nil {
+		return "", fmt.Errorf("client GET: %w", err)
+	}
+	defer resp.Body.Close()
+
+	_, readErr := io.ReadAll(resp.Body)
+	if readErr == nil {
+		return "", fmt.Errorf("expected the client read to fail after the upstream aborted mid-body, got a clean read (status %d)", resp.StatusCode)
+	}
+	return fmt.Sprintf(" client_read_err=%v", readErr), nil
+}
+
+// memNXBackend is a minimal in-process CacheBackend that also implements
+// SetNX, standing in for a Redis backend. It guards FIX-17: the
+// optional-interface assertion in UniversalCache.SetIfAbsent must work
+// under yaegi, and a second claim of the same key must lose.
+type memNXBackend struct {
+	mu   sync.Mutex
+	data map[string][]byte
+}
+
+func (b *memNXBackend) Set(_ context.Context, k string, v []byte, _ time.Duration) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.data[k] = v
+	return nil
+}
+
+func (b *memNXBackend) Get(_ context.Context, k string) ([]byte, time.Duration, bool, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	v, ok := b.data[k]
+	return v, 0, ok, nil
+}
+
+func (b *memNXBackend) Delete(_ context.Context, k string) (bool, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	_, ok := b.data[k]
+	delete(b.data, k)
+	return ok, nil
+}
+
+func (b *memNXBackend) Exists(_ context.Context, k string) (bool, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	_, ok := b.data[k]
+	return ok, nil
+}
+
+func (b *memNXBackend) Clear(_ context.Context) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.data = map[string][]byte{}
+	return nil
+}
+
+func (b *memNXBackend) GetStats() map[string]interface{} { return nil }
+func (b *memNXBackend) Close() error                     { return nil }
+func (b *memNXBackend) Ping(_ context.Context) error     { return nil }
+
+func (b *memNXBackend) SetNX(_ context.Context, k string, v []byte, _ time.Duration) (bool, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	if _, ok := b.data[k]; ok {
+		return false, nil
+	}
+	b.data[k] = v
+	return true, nil
+}
+
+// claimTwice calls SetIfAbsent twice on the same key and returns both
+// results. The first call must claim the key and the second must lose.
+func claimTwice(c *oidc.UniversalCache) (bool, bool, error) {
+	first, err := c.SetIfAbsent("yaegi-jti", true, time.Minute)
+	if err != nil {
+		return false, false, err
+	}
+	second, err := c.SetIfAbsent("yaegi-jti", true, time.Minute)
+	return first, second, err
+}
+
+// checkSetIfAbsentUnderYaegi pins FIX-17: UniversalCache.SetIfAbsent must
+// claim a key exactly once in local-only mode and through a backend that
+// implements SetNX, and must refuse a backend without SetNX instead of
+// claiming locally.
+func checkSetIfAbsentUnderYaegi() (string, error) {
+	cfg := oidc.UniversalCacheConfig{
+		Logger:          oidc.NewLogger("error"),
+		Type:            oidc.CacheTypeToken,
+		DefaultTTL:      time.Minute,
+		SkipAutoCleanup: true,
+	}
+
+	local := oidc.NewUniversalCache(cfg)
+	defer local.Close()
+	if first, second, err := claimTwice(local); err != nil || !first || second {
+		return "", fmt.Errorf("local-only: first=%v second=%v err=%v, want true false nil", first, second, err)
+	}
+
+	nx := oidc.NewUniversalCacheWithBackend(cfg, &memNXBackend{data: map[string][]byte{}})
+	defer nx.Close()
+	if first, second, err := claimTwice(nx); err != nil || !first || second {
+		return "", fmt.Errorf("SetNX backend: first=%v second=%v err=%v, want true false nil", first, second, err)
+	}
+
+	noNX := oidc.NewUniversalCacheWithBackend(cfg, failingSetBackend{})
+	defer noNX.Close()
+	claimed, err := noNX.SetIfAbsent("yaegi-jti", true, time.Minute)
+	if err == nil || claimed {
+		return "", fmt.Errorf("backend without SetNX: claimed=%v err=%v, want false and an error", claimed, err)
+	}
+	return "", nil
 }

concurrent_servehttp_test.go

@@ -0,0 +1,95 @@
+package traefikoidc
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+)
+
+// TestConcurrentServeHTTP_SharedInstance drives the full request path
+// (bootstraps, auth-bypass evaluation, session lookup, redirect) across many
+// goroutines against ONE shared plugin instance. Traefik runs the middleware
+// concurrently for every request on a router, so this is the production
+// concurrency shape. Holds under -race only if the request path touches
+// shared mutable state via atomics/locks, never plain field writes.
+func TestConcurrentServeHTTP_SharedInstance(t *testing.T) {
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+
+	oidc := &TraefikOidc{
+		next:                         next,
+		logger:                       NewLogger("debug"),
+		initComplete:                 make(chan struct{}),
+		sessionManager:               createTestSessionManager(t),
+		issuerURL:                    "https://provider.example.com",
+		redirURLPath:                 "/callback",
+		logoutURLPath:                "/logout",
+		clientID:                     "test-client",
+		audience:                     "test-client",
+		authURL:                      "https://provider.example.com/auth",
+		firstRequestStarted:          0, // let exactly one goroutine win the bootstrap CAS
+		metadataRefreshStartedAtomic: 0,
+	}
+	close(oidc.initComplete)
+
+	const goroutines = 40
+	const perGoroutine = 5
+
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+	for g := 0; g < goroutines; g++ {
+		go func() {
+			defer wg.Done()
+			for i := 0; i < perGoroutine; i++ {
+				req := httptest.NewRequest("GET", fmt.Sprintf("/api/g%d/", g), nil)
+				w := httptest.NewRecorder()
+				oidc.ServeHTTP(w, req)
+				// Unauthenticated request must bounce to the IdP (3xx), not
+				// forward to the backend (200) or error.
+				if w.Code < 300 || w.Code >= 400 {
+					t.Errorf("expected auth redirect (3xx), got %d", w.Code)
+				}
+			}
+		}()
+	}
+	wg.Wait()
+}
+
+// TestConcurrentServeHTTP_ExcludedBypass drives the auth-bypass path
+// concurrently (shouldBypassAuth read-path) on a shared instance.
+func TestConcurrentServeHTTP_ExcludedBypass(t *testing.T) {
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+
+	oidc := &TraefikOidc{
+		next:                         next,
+		logger:                       NewLogger("debug"),
+		initComplete:                 make(chan struct{}),
+		sessionManager:               createTestSessionManager(t),
+		firstRequestStarted:          1,
+		metadataRefreshStartedAtomic: 1,
+		authURL:                      "https://provider.example.com/auth",
+	}
+	close(oidc.initComplete)
+
+	const goroutines = 40
+	const perGoroutine = 5
+
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+	for g := 0; g < goroutines; g++ {
+		go func() {
+			defer wg.Done()
+			for i := 0; i < perGoroutine; i++ {
+				req := httptest.NewRequest("GET", "/", nil)
+				w := httptest.NewRecorder()
+				oidc.ServeHTTP(w, req)
+			}
+		}()
+	}
+	wg.Wait()
+}

config_marshalling.go

@@ -7,10 +7,32 @@ import (
 // REDACTED is the placeholder value for sensitive information
 const REDACTED = "[REDACTED]"
 
-// MarshalJSON implements custom JSON marshaling to redact sensitive fields
-// Rewritten without type aliases for yaegi compatibility
-func (c Config) MarshalJSON() ([]byte, error) {
-	// Build a map manually to avoid type alias issues with yaegi
+// marshalDCR builds the JSON/YAML-safe representation of the dynamic
+// client registration config, redacting the initial access token.
+func marshalDCR(d *DynamicClientRegistrationConfig) map[string]interface{} {
+	if d == nil {
+		return nil
+	}
+	m := make(map[string]interface{})
+	m["enabled"] = d.Enabled
+	m["persistCredentials"] = d.PersistCredentials
+	m["storageBackend"] = d.StorageBackend
+	m["initialAccessToken"] = REDACTED
+	m["registrationEndpoint"] = d.RegistrationEndpoint
+	m["credentialsFile"] = d.CredentialsFile
+	m["redisKeyPrefix"] = d.RedisKeyPrefix
+	return m
+}
+
+// configToMap builds the JSON/YAML-safe map representation of Config. Both
+// MarshalJSON and MarshalYAML share it so the (hand-maintained for yaegi
+// compatibility) field/redaction list cannot drift between the two
+// encoders — previously the list silently dropped entire config areas
+// (dynamicClientRegistration, securityHeaders, audience, overrideScopes,
+// enablePKCE, allowOpaqueTokens, requireTokenIntrospection,
+// strictAudienceValidation, extraAuthParams, client assertion settings)
+// and never redacted their embedded secrets (R150).
+func (c Config) configToMap() map[string]interface{} {
 	result := make(map[string]interface{})
 
 	// Copy public fields
@@ -28,11 +50,65 @@ func (c Config) MarshalJSON() ([]byte, error) {
 	result["allowedUsers"] = c.AllowedUsers
 	result["allowedRolesAndGroups"] = c.AllowedRolesAndGroups
 
-	// Redact sensitive fields
+	// Fields that the legacy hand-written list dropped (R150): important
+	// non-secret config that must survive any JSON/YAML round-trip.
+	result["audience"] = c.Audience
+	result["resource"] = c.Resource
+	result["cookiePrefix"] = c.CookiePrefix
+	result["cookieDomain"] = c.CookieDomain
+	result["userIdentifierClaim"] = c.UserIdentifierClaim
+	result["groupClaimName"] = c.GroupClaimName
+	result["roleClaimName"] = c.RoleClaimName
+	result["oidcEndSessionURL"] = c.OIDCEndSessionURL
+	result["revocationURL"] = c.RevocationURL
+	result["introspectionURL"] = c.IntrospectionURL
+	result["headers"] = c.Headers
+	result["allowedClaims"] = c.AllowedClaims
+	result["extraAuthParams"] = c.ExtraAuthParams
+	result["refreshGracePeriodSeconds"] = c.RefreshGracePeriodSeconds
+	result["maxRefreshTokenAgeSeconds"] = c.MaxRefreshTokenAgeSeconds
+	result["sessionMaxAge"] = c.SessionMaxAge
+	result["overrideScopes"] = c.OverrideScopes
+	result["disableReplayDetection"] = c.DisableReplayDetection
+	result["requireTokenIntrospection"] = c.RequireTokenIntrospection
+	result["allowOpaqueTokens"] = c.AllowOpaqueTokens
+	result["strictAudienceValidation"] = c.StrictAudienceValidation
+	result["enablePKCE"] = c.EnablePKCE
+	result["allowPrivateIPAddresses"] = c.AllowPrivateIPAddresses
+	result["allowUnauthenticatedPreflight"] = c.AllowUnauthenticatedPreflight
+	result["minimalHeaders"] = c.MinimalHeaders
+	result["stripAuthCookies"] = c.StripAuthCookies
+	result["cookiePath"] = c.CookiePath
+	result["enableBackchannelLogout"] = c.EnableBackchannelLogout
+	result["enableFrontchannelLogout"] = c.EnableFrontchannelLogout
+	result["backchannelLogoutURL"] = c.BackchannelLogoutURL
+	result["frontchannelLogoutURL"] = c.FrontchannelLogoutURL
+	result["caCertPath"] = c.CACertPath
+	result["caCertPEM"] = c.CACertPEM
+	result["insecureSkipVerify"] = c.InsecureSkipVerify
+	result["clientAuthMethod"] = c.ClientAuthMethod
+	result["clientAssertionKeyID"] = c.ClientAssertionKeyID
+	result["clientAssertionAlg"] = c.ClientAssertionAlg
+	result["clientAssertionKeyPath"] = c.ClientAssertionKeyPath
+	result["perSourceLoginRateLimit"] = c.PerSourceLoginRateLimit
+	result["enableBearerAuth"] = c.EnableBearerAuth
+	result["bearerIdentifierClaim"] = c.BearerIdentifierClaim
+	result["stripAuthorizationHeader"] = c.StripAuthorizationHeader
+	result["bearerEmitWWWAuthenticate"] = c.BearerEmitWWWAuthenticate
+	result["bearerOverridesCookie"] = c.BearerOverridesCookie
+	result["maxTokenAgeSeconds"] = c.MaxTokenAgeSeconds
+	result["maxIdentifierLength"] = c.MaxIdentifierLength
+	result["bearerFailureThreshold"] = c.BearerFailureThreshold
+	result["bearerFailureWindowSeconds"] = c.BearerFailureWindowSeconds
+	result["bearerFailurePenaltySeconds"] = c.BearerFailurePenaltySeconds
+
+	// Redact sensitive fields (existing secrets plus the previously-leaked
+	// client assertion private key, R150).
 	result["clientSecret"] = REDACTED
 	result["sessionEncryptionKey"] = REDACTED
+	result["clientAssertionPrivateKey"] = REDACTED
 
-	// Handle Redis config
+	// Handle Redis config (redacts password)
 	if c.Redis != nil {
 		redisMap := make(map[string]interface{})
 		redisMap["enabled"] = c.Redis.Enabled
@@ -44,47 +120,29 @@ func (c Config) MarshalJSON() ([]byte, error) {
 		result["redis"] = redisMap
 	}
 
-	return json.Marshal(result)
+	// Handle dynamic client registration (redacts the initial access token)
+	if c.DynamicClientRegistration != nil {
+		result["dynamicClientRegistration"] = marshalDCR(c.DynamicClientRegistration)
+	}
+
+	// Handle security headers
+	if c.SecurityHeaders != nil {
+		result["securityHeaders"] = c.SecurityHeaders
+	}
+
+	return result
+}
+
+// MarshalJSON implements custom JSON marshaling to redact sensitive fields
+// Rewritten without type aliases for yaegi compatibility
+func (c Config) MarshalJSON() ([]byte, error) {
+	return json.Marshal(c.configToMap())
 }
 
 // MarshalYAML implements custom YAML marshaling to redact sensitive fields
 // Rewritten without type aliases for yaegi compatibility
 func (c Config) MarshalYAML() (interface{}, error) {
-	// Build a map manually to avoid type alias issues with yaegi
-	result := make(map[string]interface{})
-
-	// Copy public fields
-	result["providerURL"] = c.ProviderURL
-	result["clientID"] = c.ClientID
-	result["callbackURL"] = c.CallbackURL
-	result["logoutURL"] = c.LogoutURL
-	result["postLogoutRedirectURI"] = c.PostLogoutRedirectURI
-	result["scopes"] = c.Scopes
-	result["forceHTTPS"] = c.ForceHTTPS
-	result["logLevel"] = c.LogLevel
-	result["rateLimit"] = c.RateLimit
-	result["excludedURLs"] = c.ExcludedURLs
-	result["allowedUserDomains"] = c.AllowedUserDomains
-	result["allowedUsers"] = c.AllowedUsers
-	result["allowedRolesAndGroups"] = c.AllowedRolesAndGroups
-
-	// Redact sensitive fields
-	result["clientSecret"] = REDACTED
-	result["sessionEncryptionKey"] = REDACTED
-
-	// Handle Redis config
-	if c.Redis != nil {
-		redisMap := make(map[string]interface{})
-		redisMap["enabled"] = c.Redis.Enabled
-		redisMap["address"] = c.Redis.Address
-		redisMap["password"] = REDACTED
-		redisMap["db"] = c.Redis.DB
-		redisMap["poolSize"] = c.Redis.PoolSize
-		redisMap["cacheMode"] = c.Redis.CacheMode
-		result["redis"] = redisMap
-	}
-
-	return result, nil
+	return c.configToMap(), nil
 }
 
 // MarshalJSON for RedisConfig to redact sensitive fields

config_marshalling_test.go

@@ -0,0 +1,44 @@
+package traefikoidc
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// TestConfigToMap_IncludesAllJSONFields pins FIX-40: configToMap is the
+// single field/redaction list shared by MarshalJSON and MarshalYAML (R150),
+// so every json-tagged Config field must appear as a configToMap key or the
+// marshaled/logged config silently drops it again. Fields tagged
+// `json:"-"` are intentionally excluded from marshaling and are skipped.
+func TestConfigToMap_IncludesAllJSONFields(t *testing.T) {
+	// Non-nil pointer fields so their conditional branches in configToMap
+	// run and populate a map key, matching how a real, non-empty Config is
+	// built.
+	cfg := Config{
+		Redis:                     &RedisConfig{},
+		DynamicClientRegistration: &DynamicClientRegistrationConfig{},
+		SecurityHeaders:           &SecurityHeadersConfig{},
+	}
+	result := cfg.configToMap()
+
+	typ := reflect.TypeOf(Config{})
+	var missing []string
+	for i := 0; i < typ.NumField(); i++ {
+		tag := typ.Field(i).Tag.Get("json")
+		if tag == "" || tag == "-" {
+			continue
+		}
+		name := strings.Split(tag, ",")[0]
+		if name == "" {
+			continue
+		}
+		if _, ok := result[name]; !ok {
+			missing = append(missing, name)
+		}
+	}
+
+	if len(missing) > 0 {
+		t.Fatalf("configToMap is missing json-tagged Config fields: %v", missing)
+	}
+}

config_test_helpers_test.go

@@ -0,0 +1,21 @@
+package traefikoidc
+
+// Shared Config-fixture helpers for round-regression tests.
+//
+// Moved here for FIX-41: r134ValidConfig was declared inside review_r134_test.go
+// but consumed by review_r135_test.go, so deleting or renaming the declaring
+// file silently broke the consumer. Every review_rNN*_test.go file must
+// depend only on shared helpers like this one, never on another round file.
+
+// r134ValidConfig returns a minimal Config that passes Validate(), for tests
+// that mutate one field and assert the resulting accept/reject outcome.
+func r134ValidConfig() *Config {
+	return &Config{
+		ProviderURL:          "https://provider.example.com",
+		CallbackURL:          "/callback",
+		ClientID:             "test-client",
+		ClientSecret:         "test-secret",
+		SessionEncryptionKey: "0123456789abcdef0123456789abcdef",
+		RateLimit:            CreateConfig().RateLimit,
+	}
+}

cookie_cleanup_path_test.go

@@ -0,0 +1,55 @@
+package traefikoidc
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestCleanupOldCookies_UsesConfiguredCookiePath pins the fix for cookie
+// cleanup under cookiePath. Session cookies are written at the configured
+// cookiePath (EnhanceSessionSecurity), but CleanupOldCookies wrote its
+// deletion cookies at a hardcoded "/". A browser deletes a cookie only when
+// name, domain and path all match, so the cleanup removed nothing when
+// cookiePath was set.
+func TestCleanupOldCookies_UsesConfiguredCookiePath(t *testing.T) {
+	cases := []struct {
+		name       string
+		cookiePath string
+		wantPath   string
+	}{
+		{name: "configured path", cookiePath: "/app", wantPath: "/app"},
+		{name: "default path", cookiePath: "", wantPath: "/"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			sm, err := NewSessionManager(
+				"test-encryption-key-32-bytes-long!!",
+				false, "app.example.com", "testpref", 0,
+				newNoOpLogger(),
+			)
+			if err != nil {
+				t.Fatalf("session manager: %v", err)
+			}
+			defer sm.Shutdown()
+			sm.cookiePath = tc.cookiePath
+
+			req := httptest.NewRequest(http.MethodGet, "/app/page", nil)
+			req.Host = "app.example.com"
+			req.AddCookie(&http.Cookie{Name: "testpref_sess", Value: "x"})
+			rw := httptest.NewRecorder()
+
+			sm.CleanupOldCookies(rw, req)
+
+			deleted := rw.Result().Cookies()
+			if len(deleted) == 0 {
+				t.Fatal("expected deletion cookies for the other domains")
+			}
+			for _, c := range deleted {
+				if c.Path != tc.wantPath {
+					t.Errorf("deletion cookie %s for domain %s has Path %q, want %q", c.Name, c.Domain, c.Path, tc.wantPath)
+				}
+			}
+		})
+	}
+}

coverage_boost_final_test.go

@@ -41,24 +41,6 @@ func TestLRUStrategy_OnRemove_CoverageBoost(t *testing.T) {
 	strategy.OnRemove("")
 }
 
-// =============================================================================
-// JWT REPLAY CACHE TESTS
-// =============================================================================
-
-func TestGetReplayCacheStats_CoverageBoost(t *testing.T) {
-	// Test the function - it should return valid stats
-	size, maxSize := getReplayCacheStats()
-
-	if maxSize != 10000 {
-		t.Errorf("Expected maxSize to be 10000, got %d", maxSize)
-	}
-
-	// Size should be >= 0
-	if size < 0 {
-		t.Errorf("Expected size to be >= 0, got %d", size)
-	}
-}
-
 // =============================================================================
 // PROFILING MANAGER TESTS
 // =============================================================================

custom_claims_test.go

@@ -151,9 +151,11 @@ func TestCustomClaimNames_MalformedRoleClaim(t *testing.T) {
 	// Configure custom claim names
 	ts.tOidc.roleClaimName = "custom_roles"
 
-	// Create token with malformed role claim (not an array)
+	// Create token with malformed role claim (non-string, non-array scalar).
+	// A single-string role claim is now accepted as a 1-element list, so
+	// "malformed" here means a scalar that is neither.
 	claims := map[string]interface{}{
-		"custom_roles": "this-should-be-an-array",
+		"custom_roles": 12345,
 	}
 
 	token, err := createTestJWT(ts.rsaPrivateKey, "RS256", "test-key-id", claims)
@@ -161,15 +163,12 @@ func TestCustomClaimNames_MalformedRoleClaim(t *testing.T) {
 		t.Fatalf("Failed to create test token: %v", err)
 	}
 
-	_, _, err = ts.tOidc.extractGroupsAndRoles(token)
-	if err == nil {
-		t.Error("Expected error for malformed role claim, got nil")
+	groups, roles, err := ts.tOidc.extractGroupsAndRoles(token)
+	if err != nil {
+		t.Fatalf("Expected no error for malformed role claim, got %v", err)
 	}
-
-	// Check error message contains the custom claim name
-	expectedError := "custom_roles claim is not an array"
-	if err.Error() != expectedError {
-		t.Errorf("Expected error '%s', got '%s'", expectedError, err.Error())
+	if len(groups) != 0 || len(roles) != 0 {
+		t.Errorf("Expected empty groups and roles for a malformed (numeric) role claim, got groups=%v roles=%v", groups, roles)
 	}
 }
 
@@ -191,15 +190,12 @@ func TestCustomClaimNames_MalformedGroupClaim(t *testing.T) {
 		t.Fatalf("Failed to create test token: %v", err)
 	}
 
-	_, _, err = ts.tOidc.extractGroupsAndRoles(token)
-	if err == nil {
-		t.Error("Expected error for malformed group claim, got nil")
+	groups, roles, err := ts.tOidc.extractGroupsAndRoles(token)
+	if err != nil {
+		t.Fatalf("Expected no error for malformed group claim, got %v", err)
 	}
-
-	// Check error message contains the custom claim name
-	expectedError := "custom_groups claim is not an array"
-	if err.Error() != expectedError {
-		t.Errorf("Expected error '%s', got '%s'", expectedError, err.Error())
+	if len(groups) != 0 || len(roles) != 0 {
+		t.Errorf("Expected empty groups and roles for a malformed (numeric) group claim, got groups=%v roles=%v", groups, roles)
 	}
 }
 
@@ -328,9 +324,10 @@ func TestCustomClaimNames_NonStringInRoleArray(t *testing.T) {
 		t.Errorf("Unexpected error: %v", err)
 	}
 
-	// Should only extract string elements
-	if !stringSliceEqual(roles, []string{"role1", "role2"}) {
-		t.Errorf("Expected roles [role1 role2], got %v", roles)
+	// String elements kept, numeric scalars stringified (R105, matching R102
+	// numeric-tolerance), only non-scalars (here: bool) dropped.
+	if !stringSliceEqual(roles, []string{"role1", "12345", "role2"}) {
+		t.Errorf("Expected roles [role1 12345 role2], got %v", roles)
 	}
 }
 
@@ -357,8 +354,9 @@ func TestCustomClaimNames_NonStringInGroupArray(t *testing.T) {
 		t.Errorf("Unexpected error: %v", err)
 	}
 
-	// Should only extract string elements
-	if !stringSliceEqual(groups, []string{"group1", "group2"}) {
-		t.Errorf("Expected groups [group1 group2], got %v", groups)
+	// String elements kept, numeric scalars stringified (R105); only
+	// non-scalars (here: nil) dropped.
+	if !stringSliceEqual(groups, []string{"group1", "group2", "3.14"}) {
+		t.Errorf("Expected groups [group1 group2 3.14], got %v", groups)
 	}
 }

docs/BEARER_AUTH.md

@@ -133,7 +133,10 @@ treats every one of these as a first-class concern.
 |---|---|---|
 | Default state | `enableBearerAuth=false` | Bearer is opt-in; existing deployments observe no change. |
 | Audience | **Mandatory.** Startup fails if `audience` is empty when bearer is enabled. | Eliminates the "token issued for service B accepted by service A" confusion attack. |
-| Token format | JWT only (3 segments, JOSE-encoded). Opaque tokens are not accepted on the bearer path. | Matches the validation pipeline; opaque tokens require introspection only and bypass JWT-specific defences. |
+| Token format | JWT by default. An opaque (non-JWT) token is accepted only when both `requireTokenIntrospection=true` and `allowOpaqueTokens=true`. | JWTs carry their own signature, audience and issuer; an opaque token has no local verification, so introspection must be turned on explicitly for both purposes before one is trusted. |
+| Opaque token client binding | When `audience` equals `clientID` (the common single-app case), the introspection response must carry a matching `client_id`, or an `aud` that contains `clientID`. | RFC 7662 §2.2 leaves client scoping to the authorization server's own policy. Without this check, any active token from the same IdP — including one issued to a different client — would authenticate. |
+| Opaque token `iat` requirement | The introspection response for an opaque token must carry `iat`. A response with no `iat` is always rejected: `maxTokenAgeSeconds` has no "disabled" value — `0` or unset maps to a 24h default (see the config-reference row below) — so the age bound is always in effect. | Mirrors `enforceIatAge` on the JWT path: with an age bound configured, a token with nothing to bound its age against must fail closed, not skip the check. |
+| Opaque token logout scope | A `sid`-only (front-channel) logout revokes an opaque bearer token only when the introspection response itself carries a `sid`. RFC 7662 does not define `sid`; when the IdP's response omits it, only a `sub`-based (backchannel) logout reaches the opaque token. | The middleware can only match invalidation against fields the introspection response actually returns. |
 | `alg` allowlist | Hard-pinned asymmetric: `RS256/384/512`, `PS256/384/512`, `ES256/384/512`. Checked **before** any JWKS fetch. | Denies `alg=none` and `alg=HS*` probes; prevents attacker noise from amplifying into JWKS round-trips. |
 | `kid` hardening | Max 256 bytes; charset `[A-Za-z0-9._\-=]`. Checked **before** JWKS fetch. | Prevents cache-key explosion / pathological-`kid` JWKS amplification. |
 | Token type | ID tokens are explicitly rejected (`nonce` claim, `typ: at+jwt`, `token_use=id`, scope/aud heuristics — reuses the existing `detectTokenType` helper). | ID tokens are not API credentials; treating them as such is classic token confusion. |
@@ -141,12 +144,12 @@ treats every one of these as a first-class concern.
 | `iat` upper-age | Rejects tokens older than `maxTokenAgeSeconds` (default 24h). | Bounds clock-manipulation / forever-token abuse, even if `exp` is far in the future. |
 | Identifier claim | `bearerIdentifierClaim` (default `"sub"`). Resolved value drives `X-Forwarded-User`. | Decoupled from the cookie path's `UserIdentifierClaim` (default `email`) so the M2M flow can never accidentally trust an unverified email. |
 | Identifier sanitisation | Length cap (`maxIdentifierLength`, default 256). Rejects control chars, Unicode bidi-overrides (U+202A–U+202E, U+2066–U+2069), and the delimiters `, ; =`. | Defence in depth against downstream header injection / log injection / admin-UI spoofing. |
-| JTI replay marking | Bearer path skips the JTI **Set** (so the same token can be reused until `exp`) but the **Get** stays active. | Allows legitimate bearer reuse without false-positive replay detection; revoked tokens (added to the blacklist by `RevokeToken`) still fail immediately. |
+| JTI replay marking | No request path writes an access-token JTI to a replay cache (the only JTI replay check left is for backchannel logout tokens). Revocation still works without it: `RevokeToken` (called from logout) blacklists the raw token and, for a JWT, its `jti`; both the JWT and the opaque bearer path check that blacklist — raw token always, plus `jti` when the introspection response carries one — before accepting the token. | Revocation without replay-detection overhead: a legitimately reused, non-revoked bearer token is never falsely flagged as a replay. |
 | Mixed bearer + cookie | **Cookie wins by default.** Flip to bearer-wins with `bearerOverridesCookie=true`. | Safer against browser/extension/proxy bearer injection scenarios. The cookie is the authoritative authenticator when present. |
 | `Authorization` strip | `stripAuthorizationHeader=true` by default. | Keeps the raw token out of downstream services and their logs. |
 | Excluded URLs | `Authorization` is stripped on excluded paths when `enableBearerAuth=true`. | Prevents bearer leakage into public health/metrics endpoint logs and prevents recon via excluded paths. |
 | Per-IP throttle | After `bearerFailureThreshold` consecutive 401s from one source IP within `bearerFailureWindowSeconds`, further bearer requests from that IP return `429 Too Many Requests` + `Retry-After` for `bearerFailurePenaltySeconds`. | Limits offline-guessing-style attacks and protects the shared rate-limiter / JWKS endpoint. |
-| Optional introspection | `requireTokenIntrospection=true` calls RFC 7662 introspection on every cache miss. Introspection result is cached briefly. Endpoint failure returns `503` (distinguishes infra outage from credential rejection). | Real-time revocation for high-assurance environments. Adds per-request IdP latency. |
+| Optional introspection | `requireTokenIntrospection=true` calls RFC 7662 introspection on every cache miss. Introspection result is cached briefly. Only an HTTP 200 response with `active=false` returns `401`; any other endpoint failure (network error, or any other status including 401/403/408/429) returns `503`. | RFC 7662 §2.3 defines a 401/403 from the introspection endpoint as the resource's own client credentials being rejected, not a statement about the presented token, so it must never be read as "token revoked". |
 | Response shape | `401 Unauthorized` with generic body. `WWW-Authenticate: Bearer error="invalid_token"` per RFC 6750 §3 (toggleable via `bearerEmitWWWAuthenticate`). `403` for roles/groups denial. `429` for throttle. `503` for introspection-endpoint outage. | Auditable from spec to code; reason categories never leak into the response body. |
 | Logging | Failure reason + identifier hash (SHA-256 truncated to 8 hex chars) logged at debug. Raw tokens are never logged. | Audit trail without secrets-in-logs. |
 
@@ -160,12 +163,13 @@ treats every one of these as a first-class concern.
 | `stripAuthorizationHeader` | `true` | Remove the `Authorization` header before forwarding to the backend. Disable only when a downstream needs to re-verify the bearer. |
 | `bearerEmitWWWAuthenticate` | `true` | Include `WWW-Authenticate: Bearer error="..."` on 401 responses (RFC 6750 §3). Disable to reduce recon signal. |
 | `bearerOverridesCookie` | `false` | Cookie wins when both are present (default). Set `true` for the AWS/GCP/Kubernetes bearer-wins convention. |
-| `maxTokenAgeSeconds` | `86400` | Upper bound on `iat` claim age (24h). Set `0` to disable the check (not recommended). |
+| `maxTokenAgeSeconds` | `86400` | Upper bound on `iat` claim age. `0` and unset both map to the 24h default — there is no value that disables the check. A JWT or opaque-introspection response with no `iat` is rejected once this bound is in effect, which it always is. |
 | `maxIdentifierLength` | `256` | Length cap for the post-sanitisation identifier. |
 | `bearerFailureThreshold` | `20` | Consecutive 401s from one IP that trip the throttle. |
 | `bearerFailureWindowSeconds` | `60` | Rolling window over which 401s are counted. |
 | `bearerFailurePenaltySeconds` | `60` | Duration of the 429 penalty box after the threshold trips. |
 | `requireTokenIntrospection` | `false` | Call RFC 7662 introspection on every cache miss. Adds per-request IdP latency. |
+| `allowOpaqueTokens` | `false` | Accept an opaque (non-JWT) bearer token, introspected via `requireTokenIntrospection`. Both flags are required together; this flag alone has no effect on the bearer path. |
 
 ## What the bearer path does NOT do
 
@@ -173,8 +177,11 @@ treats every one of these as a first-class concern.
   iteration. Browser SPAs that want to attach a bearer to fetch calls work
   if your backend treats them as machine clients, but the spec defaults are
   tuned for service-to-service traffic.
-- **Opaque access tokens.** Tokens must be JWTs. Introspection is a
-  revocation overlay on top of JWT verification, not a substitute for it.
+- **Opaque access tokens by default.** Tokens must be JWTs unless both
+  `requireTokenIntrospection=true` and `allowOpaqueTokens=true` are set. For a
+  JWT, introspection stays a revocation overlay on top of local verification,
+  not a substitute for it; an opaque token has no local verification, so
+  introspection is its only check.
 - **`email_verified` enforcement.** The bearer path rejects `email` as the
   identifier claim at startup precisely because `email_verified` is not
   enforced in this iteration. Adding human-user bearer support is a
@@ -196,6 +203,11 @@ treats every one of these as a first-class concern.
 - **Enable `requireTokenIntrospection`** if your IdP supports it and
   revocation latency matters. Bearer-path introspection caches results for
   a short window per token.
+- **Also set `allowOpaqueTokens=true`** if your clients present opaque
+  (non-JWT) access tokens. `requireTokenIntrospection` alone does not admit
+  an opaque token; both flags are required together. Confirm your IdP's
+  introspection response carries `client_id` or `aud` so the client-binding
+  check above can pass.
 - **Monitor 429s.** Sustained 429 traffic indicates either a buggy client
   loop or an active credential-stuffing attempt. The throttle is your
   primary signal for both.
@@ -222,8 +234,8 @@ treats every one of these as a first-class concern.
 | Multi-audience token without matching `azp` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
 | Detected as ID token | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
 | JTI blacklisted (revoked) | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
-| Introspection reports `active=false` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
-| Introspection endpoint failure | 503 | `Service Unavailable` | (none) |
+| Introspection returns HTTP 200 with `active=false` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Introspection endpoint HTTP failure (network error, or any non-200 status including 401/403/408/429) | 503 | `Service Unavailable` | (none) |
 | Identifier claim missing / empty | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
 | Identifier fails sanitisation | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
 | Per-IP failure threshold tripped | 429 | `Too Many Requests` | (none); `Retry-After: <bearerFailurePenaltySeconds>` |

docs/CONFIGURATION.md

@@ -96,6 +96,11 @@ For each token / revocation request the plugin builds a JWS with:
 
 When `clientAuthMethod: private_key_jwt`, `clientSecret` is optional.
 
+With `clientAssertionAlg` set to `RS256`, `RS384`, `RS512`, `PS256`, `PS384`,
+or `PS512`, the RSA key must be 2048 bits or larger (RFC 7518 §3.3). The
+plugin rejects a smaller key at startup instead of at every token exchange.
+There is no override for this check.
+
 **Example — inline PEM:**
 
 ```yaml
@@ -179,7 +184,7 @@ clientSecret: your-client-secret
 | `forceHTTPS` | bool | `true` | Force HTTPS for redirect URIs (set `false` only for plaintext HTTP local dev) |
 | `rateLimit` | int | `100` | Maximum requests per second |
 | `excludedURLs` | []string | none | Paths that bypass authentication, matched at a path-segment or file-extension boundary |
-| `revocationURL` | string | auto-discovered | Token revocation endpoint. Takes precedence over the discovered value. |
+| `revocationURL` | string | auto-discovered | Token revocation endpoint. Takes precedence over the discovered value. See [Logout Behavior](#logout-behavior) for what happens at logout when this is set. |
 | `oidcEndSessionURL` | string | auto-discovered | Provider's end session endpoint. Takes precedence over the discovered value. |
 | `introspectionURL` | string | auto-discovered | RFC 7662 token introspection endpoint. Set this when your IdP omits `introspection_endpoint` from discovery. Takes precedence over the discovered value. |
 | `enablePKCE` | bool | `false` | Enable PKCE for authorization code flow |
@@ -189,6 +194,41 @@ clientSecret: your-client-secret
 | `clientAssertionKeyPath` | string | none | Path to PEM private key on disk for `private_key_jwt`. Mutually exclusive with `clientAssertionPrivateKey`. |
 | `clientAssertionKeyID` | string | none | `kid` header for `private_key_jwt` assertions. Required when `clientAuthMethod: private_key_jwt`. |
 | `clientAssertionAlg` | string | `RS256` | Signing algorithm for `private_key_jwt`. One of `RS256/384/512`, `PS256/384/512`, `ES256/384/512`. |
+| `extraAuthParams` | map | none | Extra query parameters appended to the authorization request (e.g. re-selective prompt). |
+| `perSourceLoginRateLimit` | int | `0` (off) | Throttle OIDC auth events (callback + login initiation) per external client source, in auth events per minute. Keys and classifies the source by RemoteAddr only, never `X-Forwarded-For`, so a client cannot spoof it. Internal/loopback sources are never throttled. RemoteAddr is the TCP peer. Behind a load balancer or CDN, the limiter keys on the proxy address: a private address is never throttled, and a public address puts every client in one shared bucket. |
+| `stripAuthCookies` | bool | `false` | Strip OIDC session cookies from the hop to the backend (mitigates HTTP 431). |
+| `enableBackchannelLogout` | bool | `false` | Enable OIDC back-channel logout (IdP-initiated, server-to-server). |
+| `backchannelLogoutURL` | string | derived | Back-channel logout endpoint path. |
+| `enableFrontchannelLogout` | bool | `false` | Enable OIDC front-channel logout (browser iframe logout). |
+| `frontchannelLogoutURL` | string | derived | Front-channel logout endpoint path. |
+| `caCertPath` / `caCertPEM` | string | none | Custom CA bundle for OIDC TLS verification (filesystem path, or inline PEM). Mutually exclusive with `insecureSkipVerify`. |
+| `insecureSkipVerify` | bool | `false` | Disable TLS verification for the OIDC client (load balancer / mTLS edge). Emits a loud warning at startup. |
+
+### Logout Behavior
+
+A request to `logoutURL` clears the session, redirects the browser, and
+also revokes the session's tokens.
+
+1. The plugin blacklists the access, ID, and refresh tokens locally, so this
+   instance rejects them immediately.
+2. If `revocationURL` is set or discovered, the plugin also revokes the
+   access token and the refresh token at the provider (RFC 7009). Each
+   revocation call times out after 3 seconds. The two calls run one after
+   the other, so together they can delay the logout redirect by up to about
+   6 seconds. A revocation failure logs at error level and does not stop
+   the redirect. Deployments with no revocation endpoint log nothing for
+   this step.
+3. The plugin redirects to `oidcEndSessionURL` (RP-initiated logout) only
+   when `oidcEndSessionURL` is set or discovered and the session still
+   holds an ID token. Otherwise it redirects to `postLogoutRedirectURI`.
+4. When the plugin uses `oidcEndSessionURL`, it also sends
+   `post_logout_redirect_uri`. An absolute `postLogoutRedirectURI` value is
+   sent unchanged. A relative value, or the default `/`, is joined to the
+   origin of the redirect URI recorded at login. The plugin does not use
+   the logout request's `Host` header for this, because a client can spoof
+   it. The plugin omits the parameter only for a session created before
+   that origin was recorded. The provider then decides where to send the
+   user.
 
 ### TLS Termination at Load Balancer
 
@@ -272,6 +312,56 @@ strictAudienceValidation: true
 |-----------|------|---------|-------------|
 | `disableReplayDetection` | bool | `false` | Disable JTI-based replay attack detection |
 | `allowPrivateIPAddresses` | bool | `false` | Allow private IPs in provider URLs |
+| `allowUnauthenticatedPreflight` | bool | `false` | Bypass auth for a genuine CORS preflight (`OPTIONS` with `Origin` + `Access-Control-Request-Method`); response body is still discarded. Default requires auth for every `OPTIONS` request. |
+
+### Discovered Endpoint Validation
+
+When `providerURL` is `https://`, the plugin drops any endpoint the
+`.well-known/openid-configuration` document advertises as plain `http://`
+(authorization, token, jwks_uri, revocation, end_session, introspection,
+registration). A dropped credential-bearing endpoint would otherwise send
+the client secret or a token over an unauthenticated channel. There is no
+configuration flag to disable this check.
+
+A dropped endpoint logs an `ERROR`-level line naming it, and a dropped
+`token`, `jwks_uri`, or `authorization` endpoint — the three logins cannot
+function without — additionally logs a `SECURITY:`-prefixed line, because a
+blank endpoint otherwise fails every login with no other signal:
+
+```
+SECURITY: dropped the discovered token endpoint "http://idp.example.com/token": it is plaintext http while providerURL "https://idp.example.com" is https, and this check has no override; requests needing the token endpoint will fail until the provider serves it over https
+```
+
+The `revocationURL`, `oidcEndSessionURL` and `introspectionURL` config
+fields can supply those three endpoints directly, and when you set one of
+them, a plaintext-`http://` drop of the matching discovered endpoint does
+not break anything — the override replaces the endpoint right after
+sanitize runs and the `SECURITY:` line does not fire for it.
+
+Leave the override unset, though, and a drop is exactly as terminal as it is
+for `token`, `jwks_uri` and `authorization`: RP-initiated logout falls back
+to a local-only redirect (the IdP session stays alive), provider-side
+revocation is skipped, or `requireTokenIntrospection` breaks — all with no
+signal beyond the generic `ERROR` line. So `revocation`, `end_session` and
+`introspection` log the same `SECURITY:` line too, whenever the matching
+override is not set. `registration` never logs the `SECURITY:` line, under
+any configuration — it is not covered by this check. Dynamic Client
+Registration reads its own, separate override
+(`dynamicClientRegistration.registrationEndpoint`), independently of this
+discovery step, but only when you set it: leave it unset and a
+plaintext-`http://` drop of the discovered registration endpoint makes
+Dynamic Client Registration fail with only the generic `ERROR` line above —
+no `SECURITY:`-tagged signal, unlike `revocation`, `end_session` and
+`introspection`.
+
+`token`, `jwks_uri` and `authorization` log the `SECURITY:` line
+unconditionally — these three have no config field that can supply them at
+all, so a drop always breaks login regardless of any other setting.
+
+If your IdP's discovery document ever advertises an `http://` endpoint under
+an `https://` `providerURL`, fix the discovery document (for example, a
+TLS-terminating proxy in front of the IdP that does not forward
+`X-Forwarded-Proto`) rather than relying on the plugin to relax the check.
 
 ### Bearer-token (M2M) authentication
 
@@ -287,7 +377,7 @@ guidance.
 | `stripAuthorizationHeader` | bool | `true` | Strip `Authorization` from forwarded requests after successful bearer auth. |
 | `bearerEmitWWWAuthenticate` | bool | `true` | Emit RFC 6750 `WWW-Authenticate: Bearer error="..."` hints on 401. |
 | `bearerOverridesCookie` | bool | `false` | Cookie wins when both bearer and cookie are present (default). Set true for bearer-wins. |
-| `maxTokenAgeSeconds` | int64 | `86400` | Upper bound on `iat` claim age (24h). 0 disables the check. |
+| `maxTokenAgeSeconds` | int64 | `86400` | Upper bound on `iat` claim age (24h). `0` and unset both map to the 24h default; no value disables the check, and a bearer token or opaque-introspection response without `iat` is rejected. |
 | `maxIdentifierLength` | int | `256` | Length cap on the sanitised principal identifier. |
 | `bearerFailureThreshold` | int | `20` | Consecutive 401s from one source IP that trip the throttle. |
 | `bearerFailureWindowSeconds` | int | `60` | Rolling window for counting 401s. |
@@ -304,6 +394,7 @@ guidance.
 | `maxRefreshTokenAgeSeconds` | int | `21600` | Heuristic max age (in seconds) of a stored refresh token. Once exceeded, requests treat the RT as expired up front (returns 401 to AJAX, triggers full re-auth on navigations) instead of grant-spamming the IdP with `invalid_grant` retries. IdPs do not advertise RT TTL on the wire, so this is intentionally a conservative heuristic — tune to match your provider. Set `0` to disable. Default `21600` (6h). |
 | `cookieDomain` | string | auto-detected | Domain for session cookies |
 | `cookiePrefix` | string | `_oidc_raczylo_` | Prefix for cookie names |
+| `cookiePath` | string | `/` | Path prefix for session cookies. Set it to the middleware's path (for example `/app`) so the browser does not send OIDC cookies to unprotected paths (avoids HTTP 431). |
 
 ### Multi-Subdomain Setup
 

dynamic_client_registration.go

@@ -7,7 +7,9 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"net"
 	"net/http"
+	"net/url"
 	"os"
 	"strings"
 	"sync"
@@ -52,6 +54,7 @@ type DynamicClientRegistrar struct {
 	registrationResponse *ClientRegistrationResponse
 	store                DCRCredentialsStore // Storage backend for credentials
 	providerURL          string
+	scopes               []string // Runtime auth/scopes from the operator config (merged)
 	mu                   sync.RWMutex
 }
 
@@ -103,6 +106,19 @@ func (r *DynamicClientRegistrar) SetStore(store DCRCredentialsStore) {
 	r.store = store
 }
 
+// EffectiveTokenEndpointAuthMethod returns the token-endpoint auth method that
+// was (or will be) advertised to the IdP during registration:
+// ClientMetadata.TokenEndpointAuthMethod if set, else client_secret_post
+// (RFC 7591 confidential-client default). The IdP provisions the client
+// according to this method, so the runtime must authenticate to the token
+// endpoint with the SAME method or every exchange fails (R157).
+func (r *DynamicClientRegistrar) EffectiveTokenEndpointAuthMethod() string {
+	if r.config != nil && r.config.ClientMetadata != nil && r.config.ClientMetadata.TokenEndpointAuthMethod != "" {
+		return r.config.ClientMetadata.TokenEndpointAuthMethod
+	}
+	return "client_secret_post"
+}
+
 // RegisterClient performs dynamic client registration with the OIDC provider
 // It first attempts to load existing credentials from storage if persistence is enabled,
 // then registers a new client if no valid credentials exist.
@@ -141,8 +157,10 @@ func (r *DynamicClientRegistrar) RegisterClient(ctx context.Context, registratio
 
 	// Validate the endpoint URL
 	if !strings.HasPrefix(endpoint, "https://") {
-		// Allow http only for localhost/development
-		if !strings.HasPrefix(endpoint, "http://localhost") && !strings.HasPrefix(endpoint, "http://127.0.0.1") {
+		// Allow http only for loopback/development endpoints. Use a
+		// host-boundary check (not a prefix) so e.g.
+		// http://localhost.evil.com isn't treated as localhost.
+		if !isLoopbackRegistrationEndpoint(endpoint) {
 			return nil, fmt.Errorf("registration endpoint must use HTTPS for security")
 		}
 		r.logger.Infof("Warning: using insecure HTTP for registration endpoint (development only): %s", endpoint)
@@ -203,6 +221,19 @@ func (r *DynamicClientRegistrar) RegisterClient(ctx context.Context, registratio
 		return nil, fmt.Errorf("registration response missing client_id")
 	}
 
+	// The plugin's runtime client-auth default is client_secret_post
+	// (settings.go Config.Validate); RFC 7591 registers a confidential
+	// client. For a secret-based auth method the response must carry a
+	// client_secret, otherwise every token exchange fails. Adopting a
+	// secret-less client would silently break all auth.
+	authMethod := "client_secret_post"
+	if r.config != nil && r.config.ClientMetadata != nil && r.config.ClientMetadata.TokenEndpointAuthMethod != "" {
+		authMethod = r.config.ClientMetadata.TokenEndpointAuthMethod
+	}
+	if (authMethod == "client_secret_post" || authMethod == "client_secret_basic") && regResp.ClientSecret == "" {
+		return nil, fmt.Errorf("registration response missing client_secret for auth method %q", authMethod)
+	}
+
 	r.logger.Infof("Successfully registered client with ID: %s", regResp.ClientID)
 
 	// Cache the response
@@ -233,11 +264,41 @@ func (r *DynamicClientRegistrar) buildRegistrationRequest() ([]byte, error) {
 
 	// Required: redirect_uris
 	if len(metadata.RedirectURIs) > 0 {
+		// Reject malformed or wrong-scheme entries before they reach the IdP:
+		// RFC 7591 expects absolute http/https redirect URIs, and an invalid
+		// one sent to the IdP would corrupt the registered callback.
+		for _, uri := range metadata.RedirectURIs {
+			parsed, perr := url.ParseRequestURI(uri)
+			if perr != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" {
+				return nil, fmt.Errorf("redirect_uri %q must be an absolute http(s) URL", uri)
+			}
+		}
 		reqData["redirect_uris"] = metadata.RedirectURIs
 	} else {
 		return nil, fmt.Errorf("redirect_uris is required for client registration")
 	}
 
+	// Validate the optional URI metadata fields with the same absolute
+	// http(s) rule as redirect_uris. A relative or non-http(s) value
+	// (e.g. a malformed jwks_uri on a private_key_jwt client) would be
+	// forwarded to the IdP and make the registered client unverifiable at
+	// runtime (R141).
+	for _, field := range []struct{ val, name string }{
+		{metadata.LogoURI, "logo_uri"},
+		{metadata.ClientURI, "client_uri"},
+		{metadata.PolicyURI, "policy_uri"},
+		{metadata.TOSURI, "tos_uri"},
+		{metadata.JWKSURI, "jwks_uri"},
+	} {
+		if field.val == "" {
+			continue
+		}
+		parsed, perr := url.ParseRequestURI(field.val)
+		if perr != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" {
+			return nil, fmt.Errorf("%s %q must be an absolute http(s) URL", field.name, field.val)
+		}
+	}
+
 	// Optional fields - only include if set
 	if len(metadata.ResponseTypes) > 0 {
 		reqData["response_types"] = metadata.ResponseTypes
@@ -292,8 +353,10 @@ func (r *DynamicClientRegistrar) buildRegistrationRequest() ([]byte, error) {
 	if metadata.TokenEndpointAuthMethod != "" {
 		reqData["token_endpoint_auth_method"] = metadata.TokenEndpointAuthMethod
 	} else {
-		// Default to client_secret_basic for confidential clients
-		reqData["token_endpoint_auth_method"] = "client_secret_basic"
+		// Default must match the plugin's runtime client-auth default
+		// (client_secret_post, settings.go Config.Validate) so an IdP that
+		// enforces the registered method does not reject the token exchange.
+		reqData["token_endpoint_auth_method"] = "client_secret_post"
 	}
 
 	if metadata.DefaultMaxAge > 0 {
@@ -310,6 +373,13 @@ func (r *DynamicClientRegistrar) buildRegistrationRequest() ([]byte, error) {
 
 	if metadata.Scope != "" {
 		reqData["scope"] = metadata.Scope
+	} else if len(r.scopes) > 0 {
+		// Register with the union of runtime auth scopes when the operator
+		// gave no explicit registration scope. IdPs that only grant
+		// registered/advertised scopes (Keycloak offline_access, Auth0)
+		// otherwise register a client whose later token/refresh grant is
+		// rejected with invalid_scope, breaking refresh (R124).
+		reqData["scope"] = strings.Join(deduplicateScopes(r.scopes), " ")
 	}
 
 	return json.Marshal(reqData)
@@ -328,6 +398,19 @@ func (r *DynamicClientRegistrar) areCredentialsValid(resp *ClientRegistrationRes
 		return false
 	}
 
+	// For a secret-based auth method the response must carry a client_secret,
+	// mirroring the fresh-registration check (RegisterClient). A stored
+	// record with a client_id but empty secret would otherwise be accepted
+	// and installed as t.clientSecret="", breaking every token exchange
+	// (R124).
+	authMethod := "client_secret_post"
+	if r.config != nil && r.config.ClientMetadata != nil && r.config.ClientMetadata.TokenEndpointAuthMethod != "" {
+		authMethod = r.config.ClientMetadata.TokenEndpointAuthMethod
+	}
+	if (authMethod == "client_secret_post" || authMethod == "client_secret_basic") && resp.ClientSecret == "" {
+		return false
+	}
+
 	// Check if secret has expired
 	if resp.ClientSecretExpiresAt > 0 {
 		expiresAt := time.Unix(resp.ClientSecretExpiresAt, 0)
@@ -374,7 +457,7 @@ func (r *DynamicClientRegistrar) saveCredentialsToStore(ctx context.Context, res
 func (r *DynamicClientRegistrar) saveCredentials(resp *ClientRegistrationResponse) error {
 	filePath := r.credentialsFilePath()
 
-	data, err := json.MarshalIndent(resp, "", "  ")
+	data, err := json.MarshalIndent(resp, "", "  ") // #nosec G117 -- the registration response, including client_secret, is the credential this function persists
 	if err != nil {
 		return fmt.Errorf("failed to marshal credentials: %w", err)
 	}
@@ -408,3 +491,21 @@ func (r *DynamicClientRegistrar) loadCredentials() (*ClientRegistrationResponse,
 
 	return &resp, nil
 }
+
+// isLoopbackRegistrationEndpoint reports whether the (plaintext) registration
+// endpoint targets a loopback host, matching the hostname boundary (not a
+// string prefix) so http://localhost.evil.com is not treated as localhost.
+func isLoopbackRegistrationEndpoint(endpoint string) bool {
+	u, err := url.Parse(endpoint)
+	if err != nil || !u.IsAbs() {
+		return false
+	}
+	host := u.Hostname()
+	if host == "localhost" {
+		return true
+	}
+	if ip := net.ParseIP(host); ip != nil && ip.IsLoopback() {
+		return true
+	}
+	return false
+}

dynamic_client_registration_test.go

@@ -541,6 +541,7 @@ func TestCredentialsValidation(t *testing.T) {
 			name: "valid non-expiring credentials",
 			response: &ClientRegistrationResponse{
 				ClientID:              "test-client-id",
+				ClientSecret:          "test-client-secret",
 				ClientSecretExpiresAt: 0, // Never expires
 			},
 			expected: true,
@@ -549,6 +550,7 @@ func TestCredentialsValidation(t *testing.T) {
 			name: "valid future-expiring credentials",
 			response: &ClientRegistrationResponse{
 				ClientID:              "test-client-id",
+				ClientSecret:          "test-client-secret",
 				ClientSecretExpiresAt: time.Now().Add(1 * time.Hour).Unix(),
 			},
 			expected: true,
@@ -598,7 +600,7 @@ func TestBuildRegistrationRequest(t *testing.T) {
 				"redirect_uris":              []interface{}{"https://example.com/callback"},
 				"response_types":             []interface{}{"code"},
 				"grant_types":                []interface{}{"authorization_code", "refresh_token"},
-				"token_endpoint_auth_method": "client_secret_basic",
+				"token_endpoint_auth_method": "client_secret_post",
 			},
 			expectError: false,
 		},

enhanced_mocks_test.go

@@ -67,6 +67,10 @@ func (m *EnhancedMockJWKCache) GetPublicKey(ctx context.Context, jwksURL, kid st
 	return nil, fmt.Errorf("no matching public key found for kid: %s", kid)
 }
 
+func (m *EnhancedMockJWKCache) getPublicKeyFresh(ctx context.Context, jwksURL, kid string, httpClient *http.Client) (crypto.PublicKey, error) {
+	return m.GetPublicKey(ctx, jwksURL, kid, httpClient)
+}
+
 func (m *EnhancedMockJWKCache) Cleanup() {
 	atomic.AddInt32(&m.CleanupCalls, 1)
 	m.mu.Lock()

error_recovery.go

@@ -191,12 +191,23 @@ type CircuitBreaker struct {
 	maxFailures int
 	// timeout is how long to wait before allowing requests in half-open state
 	timeout time.Duration
-	// resetTimeout is how long to wait before transitioning from open to half-open
+	// resetTimeout is how long to stay in half-open (after the open timeout)
+	// before a successful response fully closes the circuit
 	resetTimeout time.Duration
 	// state tracks the current circuit breaker state
 	state CircuitBreakerState
 	// failures counts consecutive failures
 	failures int64
+	// halfOpenSince is when the circuit entered half-open; used to enforce
+	// resetTimeout before a success can fully close it
+	halfOpenSince time.Time
+	// openedAt is when the circuit last transitioned into the Open state
+	// (Closed->Open or HalfOpen->Open, set in recordFailure). allowRequest
+	// and IsAvailable gate the Open->HalfOpen transition on openedAt instead
+	// of the promoted lastFailureTime, so a request rejected while already
+	// open cannot re-arm the open timer and keep the circuit open forever
+	// under steady traffic (FIX-01).
+	openedAt time.Time
 }
 
 // CircuitBreakerConfig holds configuration parameters for circuit breakers.
@@ -239,12 +250,32 @@ func (cb *CircuitBreaker) ExecuteWithContext(ctx context.Context, fn func() erro
 	cb.RecordRequest()
 
 	if !cb.allowRequest() {
+		// A request rejected while the circuit is open is an admission
+		// outcome, not a never-started request: count it in total_failures
+		// so GetBaseMetrics' success_rate (successes/total_requests)
+		// reflects actual admission (R180). This intentionally bypasses the
+		// promoted BaseRecoveryMechanism.RecordFailure(), which also sets
+		// lastFailureTime -- allowRequest's Open->HalfOpen timer used to
+		// read that same field, so every rejection re-armed it and the
+		// circuit never left Open under steady traffic (FIX-01). The open
+		// timer now runs off cb.openedAt instead, set only on a genuine
+		// Closed->Open or HalfOpen->Open transition in recordFailure.
+		atomic.AddInt64(&cb.totalFailures, 1)
 		return fmt.Errorf("circuit breaker is open")
 	}
 
 	err := fn()
 	if err != nil {
-		cb.recordFailure()
+		// A terminal client error (HTTPError 4xx other than 429) reflects a
+		// per-user problem such as invalid_grant, not a downstream-service
+		// failure. It must not trip the state machine: in particular it
+		// must not reopen a half-open circuit, or the 15s/30s half-open
+		// hold (resetTimeout) extends an outage on any single per-user
+		// error (FIX-09). It is still recorded in the base metrics below,
+		// since it is a real error returned to the caller.
+		if !isTerminalClientError(err) {
+			cb.recordFailure()
+		}
 		cb.RecordFailure()
 		return err
 	}
@@ -254,6 +285,37 @@ func (cb *CircuitBreaker) ExecuteWithContext(ctx context.Context, fn func() erro
 	return nil
 }
 
+// isTerminalClientError reports whether err is an HTTPError whose status
+// code is a client error (4xx) other than 429 Too Many Requests or 408
+// Request Timeout. Such errors indicate the request itself was rejected by
+// the far end (for example a replayed authorization code), not that the far
+// end is unhealthy, so the circuit breaker's failure-counting state machine
+// ignores them (FIX-09). 429 and 408 are excluded because they are the
+// service itself signaling it is overloaded or slow, a genuine health
+// signal, not a per-request rejection — the same classification FIX-13
+// applies in token_validation_rs.go and bearer_auth.go, and that
+// internal/recovery/base.go and metrics.go apply via their retryable-status
+// checks.
+//
+// This uses a plain type assertion, not errors.As. Under yaegi v0.16.1 (the
+// interpreter Traefik uses to load this plugin, pinned in Makefile:9),
+// errors.As(err, &target) panics with "errors: *target must be interface
+// or implement error" whenever target's pointed-to type (*HTTPError here)
+// is itself interpreted, regardless of err's own concrete type. This
+// function runs on every fn() error in ExecuteWithContext, on the
+// default-on token-exchange/refresh path, so that panic reaches production
+// (FIX-09). The production error also reaches the breaker unwrapped
+// (helpers.go returns *HTTPError directly), so a type assertion is
+// sufficient and needs no Unwrap chain walk.
+func isTerminalClientError(err error) bool {
+	httpErr, ok := err.(*HTTPError)
+	if !ok {
+		return false
+	}
+	return httpErr.StatusCode >= 400 && httpErr.StatusCode < 500 &&
+		httpErr.StatusCode != 429 && httpErr.StatusCode != 408
+}
+
 // Execute executes a function through the circuit breaker without context.
 // This is provided for backward compatibility with existing code.
 func (cb *CircuitBreaker) Execute(fn func() error) error {
@@ -273,8 +335,9 @@ func (cb *CircuitBreaker) allowRequest() bool {
 		return true
 
 	case CircuitBreakerOpen:
-		if now.Sub(cb.lastFailureTime) > cb.timeout {
+		if now.Sub(cb.openedAt) > cb.timeout {
 			cb.state = CircuitBreakerHalfOpen
+			cb.halfOpenSince = now
 			cb.logger.Infof("Circuit breaker transitioning to half-open state")
 			return true
 		}
@@ -300,11 +363,13 @@ func (cb *CircuitBreaker) recordFailure() {
 	case CircuitBreakerClosed:
 		if cb.failures >= int64(cb.maxFailures) {
 			cb.state = CircuitBreakerOpen
+			cb.openedAt = time.Now()
 			cb.LogError("Circuit breaker opened after %d failures", cb.failures)
 		}
 
 	case CircuitBreakerHalfOpen:
 		cb.state = CircuitBreakerOpen
+		cb.openedAt = time.Now()
 		cb.LogError("Circuit breaker returned to open state after failure in half-open")
 	}
 }
@@ -317,6 +382,15 @@ func (cb *CircuitBreaker) recordSuccess() {
 
 	switch cb.state {
 	case CircuitBreakerHalfOpen:
+		// Honor resetTimeout: do not fully close until the circuit has been
+		// in half-open for at least resetTimeout. This provides the
+		// documented open -> half-open -> (reset cooldown) -> closed
+		// hysteresis instead of closing on the very first half-open
+		// success, which would let a stray success immediately reopen
+		// (bounce). While in half-open requests are still allowed as probes.
+		if time.Since(cb.halfOpenSince) < cb.resetTimeout {
+			return
+		}
 		cb.failures = 0
 		cb.state = CircuitBreakerClosed
 		cb.LogInfo("Circuit breaker closed after successful request in half-open state")
@@ -348,7 +422,24 @@ func (cb *CircuitBreaker) Reset() {
 // IsAvailable returns whether the circuit breaker is currently allowing requests.
 // This provides a quick way to check if the service is available.
 func (cb *CircuitBreaker) IsAvailable() bool {
-	return cb.allowRequest()
+	cb.mutex.Lock()
+	defer cb.mutex.Unlock()
+
+	switch cb.state {
+	case CircuitBreakerClosed:
+		return true
+	case CircuitBreakerHalfOpen:
+		return true
+	case CircuitBreakerOpen:
+		// Read-only availability probe: report that a request would be
+		// admitted only after the open timeout has elapsed, but do NOT
+		// transition to half-open — IsAvailable must not take a permit or
+		// mutate circuit state. Real traffic admission is gated by
+		// allowRequest (triggerRequest) which performs the transition.
+		return time.Since(cb.openedAt) > cb.timeout
+	default:
+		return false
+	}
 }
 
 // GetMetrics returns comprehensive metrics about the circuit breaker.
@@ -507,12 +598,157 @@ func (re *RetryExecutor) ExecuteWithContext(ctx context.Context, fn func() error
 }
 
 // Execute runs the given function with retry logic (for backward compatibility)
-// Execute executes a function with retry logic (backward compatibility).
+// Execute runs a function with retry logic (backward compatibility).
 // This method provides the same functionality as ExecuteWithContext.
 func (re *RetryExecutor) Execute(ctx context.Context, fn func() error) error {
 	return re.ExecuteWithContext(ctx, fn)
 }
 
+// singleUseRetryableErrors are error fragments that prove the request was NEVER
+// sent to the server (dial/connect failures). Retrying those is safe.
+var singleUseRetryableErrors = []string{
+	"connection refused",
+	"network unreachable",
+	"no route to host",
+	"temporary failure",
+}
+
+// isNeverSentError reports whether err proves a single-use request was never
+// sent to the server, so retrying it cannot re-present already-consumed
+// input (an authorization code or a rotated refresh token).
+//
+// A *HTTPError means a response WAS received: the request definitely
+// reached the endpoint, regardless of what its body says. Before this
+// check, ExecuteSingleUseWithContext substring-matched singleUseRetryableErrors
+// against the raw error text, and helpers.go's token-endpoint HTTPError
+// carries up to 10 KiB of the response body in its Message -- an IdP 500
+// whose body happened to mention "connection refused" was retried, re-
+// sending a consumed code or a rotated refresh token (FIX-14).
+//
+// A *net.OpError is NOT proof by itself: Go's net package uses that same
+// type for a "dial" failure before any request reaches the wire, but also
+// for a "read" or "write" failure AFTER the connection is already
+// established, when the request may already have reached the IdP. Only Op
+// "dial" (a failed connect) or "proxyconnect" (net/http's failed CONNECT to
+// an HTTP proxy) prove the request never went out, so the fragment match is
+// scoped to those two.
+func isNeverSentError(err error) bool {
+	// Plain type assertion, not errors.As: under yaegi v0.16.1 (the
+	// interpreter Traefik uses to load this plugin, pinned in Makefile:9),
+	// errors.As(err, &target) panics with "errors: *target must be
+	// interface or implement error" whenever target's pointed-to type
+	// (*HTTPError here) is itself interpreted, regardless of err's own
+	// concrete type. ExecuteSingleUseWithContext calls this on every fn()
+	// error, on the default-on authorization-code-exchange/refresh path,
+	// so that panic reaches production (FIX-14). The production error
+	// reaches here unwrapped (helpers.go returns *HTTPError directly), so
+	// a type assertion is sufficient and needs no Unwrap chain walk.
+	if _, ok := err.(*HTTPError); ok {
+		return false
+	}
+
+	// errors.As against the compiled *net.OpError type is yaegi-safe: the
+	// panic above is specific to an interpreted target type, and
+	// *net.OpError is a native stdlib type.
+	var opErr *net.OpError
+	if errors.As(err, &opErr) && (opErr.Op == "dial" || opErr.Op == "proxyconnect") {
+		return isSubstringMatch(opErr.Error(), singleUseRetryableErrors)
+	}
+
+	return false
+}
+
+// ExecuteSingleUseWithContext retries only on errors that prove the request was
+// never sent (connect/dial failures). It intentionally does NOT retry on
+// "timeout": for a single-use operation such as the authorization-code
+// exchange, a timeout may mean the provider already consumed the one-time code,
+// so re-sending it would surface invalid_grant permanently even though the
+// first attempt succeeded.
+func (re *RetryExecutor) ExecuteSingleUseWithContext(ctx context.Context, fn func() error) error {
+	re.RecordRequest()
+	var lastErr error
+
+	for attempt := 1; attempt <= re.config.MaxAttempts; attempt++ {
+		err := fn()
+		if err == nil {
+			if attempt > 1 {
+				re.LogInfo("Operation succeeded after %d attempts", attempt)
+			}
+			re.RecordSuccess()
+			return nil
+		}
+
+		lastErr = err
+
+		if !isNeverSentError(err) {
+			re.RecordFailure()
+			return err
+		}
+
+		if attempt == re.config.MaxAttempts {
+			re.RecordFailure()
+			break
+		}
+
+		delay := re.calculateDelay(attempt)
+		if attempt == 1 || attempt%3 == 0 {
+			re.LogDebug("Retrying single-use operation after %v (attempt %d/%d): %v",
+				delay, attempt, re.config.MaxAttempts, err)
+		}
+
+		select {
+		case <-ctx.Done():
+			re.RecordFailure()
+			return ctx.Err()
+		case <-time.After(delay):
+		}
+	}
+
+	finalErr := fmt.Errorf("operation failed after %d attempts: %w", re.config.MaxAttempts, lastErr)
+	return finalErr
+}
+
+// isSubstringMatch reports whether s contains any of the given fragments.
+func isSubstringMatch(s string, fragments []string) bool {
+	lower := strings.ToLower(s)
+	for _, frag := range fragments {
+		if strings.Contains(lower, frag) {
+			return true
+		}
+	}
+	return false
+}
+
+// asHTTPError reports whether err is, or (via a chain of Unwrap() error
+// methods) wraps, an *HTTPError. It exists because errors.As cannot be used
+// here: under yaegi v0.16.1 (the interpreter Traefik uses to load this
+// plugin, pinned in Makefile:9), errors.As(err, &target) panics with
+// "errors: *target must be interface or implement error" whenever target's
+// pointed-to type is itself interpreted, and *HTTPError is declared in this
+// plugin so it is always interpreted at runtime — regardless of err's own
+// concrete type (see isTerminalClientError above for the same hazard on a
+// path that does not need the Unwrap walk).
+//
+// This manually reimplements errors.As's single-chain Unwrap() walk using
+// only type assertions and errors.Unwrap, both yaegi-safe, so native
+// classification is byte-for-byte identical to errors.As (see
+// TestIsRetryableError_WrappedTransient). The one place native and yaegi
+// genuinely diverge: an interpreted *HTTPError wrapped with
+// fmt.Errorf("...%w", e) is found by this walk in native Go but NOT under
+// yaegi (an interpreter quirk with wrapped interpreted-type targets,
+// verified this session) — so every producer feeding isRetryableError must
+// keep returning an *HTTPError unwrapped (exchangeTokens already does; see
+// helpers.go).
+func asHTTPError(err error) (*HTTPError, bool) {
+	for err != nil {
+		if httpErr, ok := err.(*HTTPError); ok {
+			return httpErr, true
+		}
+		err = errors.Unwrap(err)
+	}
+	return nil, false
+}
+
 // isRetryableError checks if an error should trigger a retry
 // isRetryableError determines if an error should trigger a retry attempt.
 // Checks error message against configured retryable error patterns.
@@ -523,6 +759,17 @@ func (re *RetryExecutor) isRetryableError(err error) bool {
 		return false
 	}
 
+	// A terminal HTTP error (a real status that is neither 5xx nor 429)
+	// must be classified by its status BEFORE any message-substring scan.
+	// Otherwise a 4xx whose provider message merely contains a
+	// retryable-looking word — e.g. "certificate"/"tls" (isCertificateError),
+	// "EOF" (isEOFError), or a generic "timeout" — would be reclassified
+	// retryable and retried to MaxAttempts on a permanent error, repeating
+	// the failing request (R123, R157).
+	if statusHTTP, ok := asHTTPError(err); ok && statusHTTP.StatusCode != 0 && statusHTTP.StatusCode < 500 && statusHTTP.StatusCode != 429 {
+		return false
+	}
+
 	// Check for Traefik default certificate error (startup race condition)
 	// See: https://github.com/lukaszraczylo/traefikoidc/issues/90
 	if isTraefikDefaultCertError(err) {
@@ -547,7 +794,8 @@ func (re *RetryExecutor) isRetryableError(err error) bool {
 		}
 	}
 
-	if netErr, ok := err.(net.Error); ok {
+	var netErr net.Error
+	if errors.As(err, &netErr) {
 		if netErr.Timeout() {
 			return true
 		}
@@ -568,8 +816,19 @@ func (re *RetryExecutor) isRetryableError(err error) bool {
 		}
 	}
 
-	if httpErr, ok := err.(*HTTPError); ok {
-		return httpErr.StatusCode >= 500 || httpErr.StatusCode == 429
+	// asHTTPError (not errors.As) so retry classification survives error
+	// wrapping: a transient or 5xx/429 error returned as fmt.Errorf("...:
+	// %w", err) from an upstream layer must still be retried. Direct type
+	// assertions on the top-level error silently misclassified wrapped
+	// transient errors as permanent, giving up before any retry (R111).
+	// errors.As itself cannot be used under yaegi -- see asHTTPError's doc
+	// comment.
+	if httpErr, ok := asHTTPError(err); ok {
+		status := httpErr.StatusCode
+		// A 0 StatusCode means the producer used HTTPError purely as a
+		// message carrier (no real HTTP status). Treat it as unknown
+		// (non-retryable) rather than spuriously matching 5xx (R118).
+		return status != 0 && (status >= 500 || status == 429)
 	}
 
 	return false
@@ -762,6 +1021,10 @@ type GracefulDegradation struct {
 	config           GracefulDegradationConfig
 	mutex            sync.RWMutex
 	shutdownOnce     sync.Once
+	// beforeSharedTaskStop is a test seam, nil in production. Close calls it
+	// after deciding this is the last live instance and before stopping the
+	// shared health-check task.
+	beforeSharedTaskStop func()
 }
 
 // GracefulDegradationConfig holds configuration for graceful degradation behavior.
@@ -788,6 +1051,53 @@ func DefaultGracefulDegradationConfig() GracefulDegradationConfig {
 // NewGracefulDegradation creates a new graceful degradation manager
 // NewGracefulDegradation creates a new graceful degradation mechanism.
 // Initializes fallback and health check maps and starts background health monitoring.
+// gdInstances tracks live GracefulDegradation instances so the single shared
+// health-check task can run every instance's health checks (not just the first)
+// and so the task is only stopped when the last instance closes.
+var gdInstances = struct {
+	sync.RWMutex
+	set map[*GracefulDegradation]struct{}
+}{set: make(map[*GracefulDegradation]struct{})}
+
+// globalHealthCheckMu serializes the global pass. globalPerformHealthChecks
+// runs from more than one goroutine — the shared singleton task's run loop
+// AND the once-guarded StartBackgroundTask path both drive it — so without
+// this, any health check registered via the public RegisterHealthCheck
+// API would be invoked concurrently (a latent production race, and the
+// source of an intermittent full-suite race in tests). Serializing the
+// whole pass keeps registered health checks single-threaded (R189).
+var globalHealthCheckMu sync.Mutex
+
+// gdLifecycleMu serializes GracefulDegradation registration with the
+// last-instance check and shared-task stop in Close. Without it, an instance
+// created after Close decided it was the last one, but before the stop, adopted
+// the still-running task, and the stop then killed the task that the new live
+// instance relies on. With it, a new instance either counts toward the
+// last-instance check or registers after the stop, and its routine replaces
+// the stopped task. The health-check pass never takes this lock, so Close can
+// hold it while BackgroundTask.Stop waits for an in-progress pass.
+var gdLifecycleMu sync.Mutex
+
+// globalPerformHealthChecks runs the health check pass for every live
+// GracefulDegradation instance. The shared singleton task calls this, so a
+// health check registered on ANY instance is exercised, and closing one
+// instance does not stall recovery for the others.
+func globalPerformHealthChecks() {
+	globalHealthCheckMu.Lock()
+	defer globalHealthCheckMu.Unlock()
+
+	gdInstances.RLock()
+	instances := make([]*GracefulDegradation, 0, len(gdInstances.set))
+	for gd := range gdInstances.set {
+		instances = append(instances, gd)
+	}
+	gdInstances.RUnlock()
+
+	for _, gd := range instances {
+		gd.performHealthChecks()
+	}
+}
+
 func NewGracefulDegradation(config GracefulDegradationConfig, logger *Logger) *GracefulDegradation {
 	gd := &GracefulDegradation{
 		BaseRecoveryMechanism: NewBaseRecoveryMechanism("graceful-degradation", logger),
@@ -798,6 +1108,22 @@ func NewGracefulDegradation(config GracefulDegradationConfig, logger *Logger) *G
 	}
 
 	gd.stopChan = make(chan struct{})
+
+	// Register synchronously, before the health-check goroutine starts
+	// (FIX-18). Registration used to happen only inside startHealthCheckRoutine,
+	// which runs in its own goroutine, so a Close() called immediately after
+	// NewGracefulDegradation returned could race ahead of it: Close's
+	// gdInstances.delete would find nothing to remove, and the goroutine's
+	// later add would then register an already-closed gd permanently.
+	// startHealthCheckRoutine no longer touches gdInstances at all — this is
+	// now the ONLY place a GracefulDegradation is added to the set, so there
+	// is no second, racing registration left to worry about.
+	gdLifecycleMu.Lock()
+	gdInstances.Lock()
+	gdInstances.set[gd] = struct{}{}
+	gdInstances.Unlock()
+	gdLifecycleMu.Unlock()
+
 	go gd.startHealthCheckRoutine()
 
 	return gd
@@ -902,25 +1228,54 @@ func (gd *GracefulDegradation) executeFallback(serviceName string) (interface{},
 	return fallback()
 }
 
-// startHealthCheckRoutine starts the background health check routine
+// startHealthCheckRoutine starts the background health check routine.
+//
+// FIX-18: this runs in its own goroutine, started by NewGracefulDegradation
+// right after it registers gd in gdInstances. A Close() called immediately
+// after NewGracefulDegradation returns can race ahead of this goroutine
+// getting scheduled at all. Take gd.mutex up front and re-check gd.stopChan
+// before doing anything else: if Close() already closed it, this goroutine
+// must not create (or adopt) the shared health-check task for an
+// already-closed instance — that would leak the process-global task
+// forever, since nothing would ever be left registered to stop it.
 func (gd *GracefulDegradation) startHealthCheckRoutine() {
-	// Use singleton task registry to prevent multiple instances
+	gd.mutex.Lock()
+
+	select {
+	case <-gd.stopChan:
+		// Close() already ran before this goroutine got scheduled. Do not
+		// register or start the shared task on behalf of a closed instance.
+		gd.mutex.Unlock()
+		return
+	default:
+	}
+
+	// Use the singleton task registry so multiple GracefulDegradation
+	// instances share one health-check goroutine. The task function is the
+	// global pass over every live instance, not this instance's own health
+	// checks — otherwise only the first instance's checks would run.
+	//
+	// gd.mutex stays held through CreateSingletonTask and the healthCheckTask
+	// assignment below: CreateSingletonTask only touches the global task
+	// registry (a different lock), never gd.mutex, so this cannot deadlock,
+	// and it keeps the stopChan check and the assignment atomic with respect
+	// to a concurrent Close().
 	registry := GetGlobalTaskRegistry()
 
 	task, err := registry.CreateSingletonTask(
 		"graceful-degradation-health-check",
 		gd.config.HealthCheckInterval,
-		gd.performHealthChecks,
+		globalPerformHealthChecks,
 		gd.BaseRecoveryMechanism.logger,
 		nil, // No specific wait group
 	)
 
 	if err != nil {
+		gd.mutex.Unlock()
 		gd.BaseRecoveryMechanism.logger.Errorf("Failed to create health check task: %v", err)
 		return
 	}
 
-	gd.mutex.Lock()
 	gd.healthCheckTask = task
 	gd.mutex.Unlock()
 
@@ -972,25 +1327,58 @@ func (gd *GracefulDegradation) Reset() {
 	gd.LogInfo("Graceful degradation state has been reset")
 }
 
-// Close shuts down the graceful degradation system and cleans up resources
+// Close shuts down the graceful degradation system and cleans up resources.
 func (gd *GracefulDegradation) Close() {
 	gd.shutdownOnce.Do(func() {
-		// Signal shutdown
+		// Signal shutdown under gd.mutex. startHealthCheckRoutine checks
+		// stopChan and creates or adopts the shared task under the same
+		// lock, so an in-flight routine finishes before this instance
+		// unregisters below. Without the lock, a routine that passed its
+		// check could reach the task registry after the last Close stopped
+		// the task, and RegisterBackgroundTask would start a fresh task
+		// that no live instance can stop. Release the lock before the stop:
+		// BackgroundTask.Stop waits for a health-check pass that takes gd.mutex.
+		gd.mutex.Lock()
 		select {
 		case <-gd.stopChan:
 			// Already closed
 		default:
 			close(gd.stopChan)
 		}
-
-		// Stop health check task
-		gd.mutex.Lock()
-		task := gd.healthCheckTask
 		gd.mutex.Unlock()
 
-		if task != nil {
-			task.Stop()
-			// Don't set to nil to avoid race conditions
+		// Stop the shared health-check task only when this was the last live
+		// instance. The task is process-global and shared by every
+		// GracefulDegradation instance; stopping it on any one instance's
+		// close would kill health checks / recovery for all surviving
+		// instances (mirror of the singleton-token-cleanup lastInstance gate).
+		// Hold gdLifecycleMu across the last-instance check and the stop, so a
+		// concurrent NewGracefulDegradation cannot register in between and
+		// adopt a task that is about to stop.
+		gdLifecycleMu.Lock()
+		defer gdLifecycleMu.Unlock()
+
+		gdInstances.Lock()
+		delete(gdInstances.set, gd)
+		lastInstance := len(gdInstances.set) == 0
+		gdInstances.Unlock()
+
+		if lastInstance {
+			if gd.beforeSharedTaskStop != nil {
+				gd.beforeSharedTaskStop()
+			}
+			// Stop by name through the resource manager rather than reading
+			// this instance's own gd.healthCheckTask field: with two or more
+			// GracefulDegradation instances, the shared task can already be
+			// running — created by a SIBLING instance's startHealthCheckRoutine
+			// goroutine — while THIS instance's own goroutine has not yet run
+			// and populated its local healthCheckTask field. Reading that
+			// still-nil local field here would skip the stop and leak the
+			// task forever even though this genuinely is the last instance.
+			// StopBackgroundTask looks up the registry's current entry
+			// directly, so it is correct regardless of which instance's
+			// goroutine happened to create the task (FIX-18).
+			_ = GetResourceManager().StopBackgroundTask("graceful-degradation-health-check")
 		}
 
 		gd.logger.Debug("GracefulDegradation shut down successfully")
@@ -1050,6 +1438,21 @@ func NewErrorRecoveryManager(logger *Logger) *ErrorRecoveryManager {
 	}
 }
 
+// Close shuts down the resources owned by this ErrorRecoveryManager,
+// currently its GracefulDegradation instance (which unregisters from
+// gdInstances and, if this was the last live instance, stops the shared
+// health-check task). Safe to call multiple times; safe on a nil receiver.
+// FIX-18: every caller that constructs an ErrorRecoveryManager must call
+// Close, or its GracefulDegradation leaks in gdInstances forever.
+func (erm *ErrorRecoveryManager) Close() {
+	if erm == nil {
+		return
+	}
+	if erm.gracefulDegradation != nil {
+		erm.gracefulDegradation.Close()
+	}
+}
+
 // GetCircuitBreaker gets or creates a circuit breaker for a service
 // GetCircuitBreaker returns the circuit breaker for a specific service.
 // Creates a new circuit breaker if one doesn't exist for the service.
@@ -1072,8 +1475,14 @@ func (erm *ErrorRecoveryManager) GetCircuitBreaker(serviceName string) *CircuitB
 func (erm *ErrorRecoveryManager) ExecuteWithRecovery(ctx context.Context, serviceName string, fn func() error) error {
 	cb := erm.GetCircuitBreaker(serviceName)
 
-	return erm.retryExecutor.Execute(ctx, func() error {
-		return cb.Execute(fn)
+	// Retry INNER, circuit OUTER (matching TokenResilienceManager and the
+	// documented R106 compositing rule). Wrapping cb around the whole retry
+	// run means one logical call counts as a single circuit failure even
+	// when it was retried internally; the previous nesting (cb inside the
+	// retry loop) recorded each retry attempt as a separate failure and
+	// could open the circuit after only one flaky-but-retryable call (R144).
+	return cb.ExecuteWithContext(ctx, func() error {
+		return erm.retryExecutor.Execute(ctx, fn)
 	})
 }
 

error_recovery_408_transient_test.go

@@ -0,0 +1,47 @@
+package traefikoidc
+
+import (
+	"context"
+	"testing"
+)
+
+// TestIsTerminalClientError408IsTransient pins that HTTP 408 Request Timeout
+// is treated as a transient, service-health signal by isTerminalClientError,
+// not as a terminal per-request client error. A token endpoint (or a proxy
+// in front of it) returns 408 when the upstream is slow, which is the same
+// reasoning FIX-13 already applies in token_validation_rs.go's classifier
+// and bearer_auth.go, and that internal/recovery/base.go and metrics.go
+// apply via their RetryableStatusCodes/isRetryable checks. isTerminalClientError
+// must classify 408 the same way, or a burst of token-endpoint 408s never
+// opens the refresh circuit breaker.
+//
+// Fail-on-old: isTerminalClientError excluded only 429, so it reported 408
+// as terminal.
+func TestIsTerminalClientError408IsTransient(t *testing.T) {
+	err := &HTTPError{StatusCode: 408, Message: "request timeout"}
+	if isTerminalClientError(err) {
+		t.Fatal("408 Request Timeout must be treated as transient (like 429), not a terminal client error")
+	}
+}
+
+// TestCircuitBreakerHalfOpenRequestTimeoutReopens pins the same contract at
+// the circuit-breaker level: a 408 probe result must still reopen a
+// half-open breaker, exactly like the existing 429 case
+// (TestCircuitBreakerHalfOpenRateLimitReopens in error_recovery_fix09_test.go).
+//
+// Fail-on-old: with 408 misclassified as terminal, recordFailure's HalfOpen
+// exemption for terminal client errors (FIX-09) swallowed it and the breaker
+// stayed HalfOpen instead of reopening.
+func TestCircuitBreakerHalfOpenRequestTimeoutReopens(t *testing.T) {
+	cb := newFix09HalfOpenBreaker(t)
+
+	err := cb.ExecuteWithContext(context.Background(), func() error {
+		return &HTTPError{StatusCode: 408, Message: "request timeout"}
+	})
+	if err == nil {
+		t.Fatal("expected the probe's own error to be returned to the caller")
+	}
+	if cb.GetState() != CircuitBreakerOpen {
+		t.Fatalf("a 408 must still reopen a half-open circuit like 429, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+}

error_recovery_fix01_test.go

@@ -0,0 +1,87 @@
+package traefikoidc
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+// TestCircuitBreakerOpenRejectionsDoNotExtendOpenWindow is a regression test
+// for FIX-01.
+//
+// Before the fix, ExecuteWithContext called the promoted
+// BaseRecoveryMechanism.RecordFailure() on every request rejected while the
+// circuit is open. RecordFailure sets lastFailureTime, the same field
+// allowRequest reads as the Open -> HalfOpen timer. Every rejection then
+// re-armed the timer, so under steady traffic shorter than Timeout the
+// breaker never left Open (see error_recovery.go:253,288 pre-fix).
+//
+// Fail-on-old: with a request every 10ms and Timeout 50ms, no request is
+// ever admitted within the 500ms budget, because each rejection pushes the
+// open window forward by another Timeout.
+func TestCircuitBreakerOpenRejectionsDoNotExtendOpenWindow(t *testing.T) {
+	cb := NewCircuitBreaker(CircuitBreakerConfig{
+		MaxFailures:  1,
+		Timeout:      50 * time.Millisecond,
+		ResetTimeout: 30 * time.Second,
+	}, NewLogger("error"))
+
+	// Trip the breaker open with a single real failure.
+	if err := cb.ExecuteWithContext(context.Background(), func() error {
+		return errors.New("boom")
+	}); err == nil {
+		t.Fatal("expected the tripping call to return its own error")
+	}
+	if cb.GetState() != CircuitBreakerOpen {
+		t.Fatalf("expected circuit to be open after the tripping failure, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+
+	deadline := time.Now().Add(500 * time.Millisecond)
+	admitted := false
+	for time.Now().Before(deadline) {
+		callErr := cb.ExecuteWithContext(context.Background(), func() error {
+			return nil
+		})
+		if callErr == nil {
+			admitted = true
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	if !admitted {
+		t.Fatal("expected a probe to be admitted once Timeout elapsed with no real failure in between; open-circuit rejections must not re-arm the open timer")
+	}
+}
+
+// TestCircuitBreakerOpenRejectionStillCountedInMetrics pins the R180 intent
+// alongside FIX-01: an open-circuit rejection is still an admission outcome
+// and must still increment total_failures, even though it may no longer
+// touch the open timer.
+func TestCircuitBreakerOpenRejectionStillCountedInMetrics(t *testing.T) {
+	cb := NewCircuitBreaker(CircuitBreakerConfig{
+		MaxFailures:  1,
+		Timeout:      time.Hour,
+		ResetTimeout: time.Hour,
+	}, NewLogger("error"))
+
+	if err := cb.ExecuteWithContext(context.Background(), func() error {
+		return errors.New("boom")
+	}); err == nil {
+		t.Fatal("expected the tripping call to return its own error")
+	}
+
+	if err := cb.ExecuteWithContext(context.Background(), func() error {
+		t.Fatal("fn must not be called while the circuit is open")
+		return nil
+	}); err == nil {
+		t.Fatal("expected the rejected call to return an error")
+	}
+
+	metrics := cb.GetBaseMetrics()
+	totalFailures := metrics["total_failures"].(int64)
+	if totalFailures != 2 {
+		t.Errorf("total_failures = %d, want 2 (1 real failure + 1 open rejection)", totalFailures)
+	}
+}

error_recovery_fix09_test.go

@@ -0,0 +1,131 @@
+package traefikoidc
+
+import (
+	"context"
+	"errors"
+	"net"
+	"testing"
+	"time"
+)
+
+// newFix09HalfOpenBreaker builds a breaker, trips it with one real (non
+// client) failure, and waits past Timeout so the next ExecuteWithContext
+// call performs the Open -> HalfOpen probe transition itself.
+func newFix09HalfOpenBreaker(t *testing.T) *CircuitBreaker {
+	t.Helper()
+	cb := NewCircuitBreaker(CircuitBreakerConfig{
+		MaxFailures:  1,
+		Timeout:      100 * time.Millisecond,
+		ResetTimeout: 50 * time.Millisecond,
+	}, NewLogger("error"))
+
+	if err := cb.ExecuteWithContext(context.Background(), func() error {
+		return &HTTPError{StatusCode: 500, Message: "downstream unavailable"}
+	}); err == nil {
+		t.Fatal("expected the tripping call to return its own error")
+	}
+	if cb.GetState() != CircuitBreakerOpen {
+		t.Fatalf("setup: expected circuit open after the tripping failure, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+
+	time.Sleep(150 * time.Millisecond) // past Timeout: next call probes half-open
+	return cb
+}
+
+// TestCircuitBreakerHalfOpenTerminalClientErrorStaysHalfOpen is a regression
+// test for FIX-09. A terminal client error (HTTPError 4xx other than 429,
+// e.g. invalid_grant from a replayed code) reflects a per-user problem, not
+// a downstream-service failure, so it must not reopen a half-open breaker.
+//
+// Fail-on-old: recordFailure's HalfOpen case reopened unconditionally on
+// any fn() error, so the circuit is Open (not HalfOpen) right after this
+// probe.
+func TestCircuitBreakerHalfOpenTerminalClientErrorStaysHalfOpen(t *testing.T) {
+	cb := newFix09HalfOpenBreaker(t)
+
+	err := cb.ExecuteWithContext(context.Background(), func() error {
+		return &HTTPError{StatusCode: 400, Message: "invalid_grant"}
+	})
+	if err == nil {
+		t.Fatal("expected the probe's own error to be returned to the caller")
+	}
+	if cb.GetState() != CircuitBreakerHalfOpen {
+		t.Fatalf("a terminal client 4xx must not reopen a half-open circuit, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+
+	// Past resetTimeout relative to the half-open entry: a subsequent
+	// success must still be able to fully close the circuit.
+	time.Sleep(60 * time.Millisecond)
+
+	if err := cb.ExecuteWithContext(context.Background(), func() error { return nil }); err != nil {
+		t.Fatalf("expected the closing probe to succeed, got %v", err)
+	}
+	if cb.GetState() != CircuitBreakerClosed {
+		t.Fatalf("expected circuit to close after a half-open success following the ignored client error, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+}
+
+// TestCircuitBreakerHalfOpenRateLimitReopens pins that HTTP 429 (the
+// service itself signaling it is overloaded) still reopens a half-open
+// circuit, unlike an ordinary terminal client 4xx.
+func TestCircuitBreakerHalfOpenRateLimitReopens(t *testing.T) {
+	cb := newFix09HalfOpenBreaker(t)
+
+	err := cb.ExecuteWithContext(context.Background(), func() error {
+		return &HTTPError{StatusCode: 429, Message: "rate limited"}
+	})
+	if err == nil {
+		t.Fatal("expected the probe's own error to be returned to the caller")
+	}
+	if cb.GetState() != CircuitBreakerOpen {
+		t.Fatalf("a 429 must still reopen a half-open circuit, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+}
+
+// TestCircuitBreakerHalfOpenNetworkErrorReopens pins that a genuine network
+// error still reopens a half-open circuit.
+func TestCircuitBreakerHalfOpenNetworkErrorReopens(t *testing.T) {
+	cb := newFix09HalfOpenBreaker(t)
+
+	err := cb.ExecuteWithContext(context.Background(), func() error {
+		return &net.OpError{Op: "dial", Err: errors.New("connection refused")}
+	})
+	if err == nil {
+		t.Fatal("expected the probe's own error to be returned to the caller")
+	}
+	if cb.GetState() != CircuitBreakerOpen {
+		t.Fatalf("a network error must still reopen a half-open circuit, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+}
+
+// TestCircuitBreakerClosedTerminalClientErrorStaysClosed pins FIX-09's
+// scope choice: the terminal-client-error exemption applies to the Closed
+// state too, not only half-open, so a per-user invalid_grant never trips
+// the breaker at all. A following genuine 5xx still opens it normally.
+func TestCircuitBreakerClosedTerminalClientErrorStaysClosed(t *testing.T) {
+	cb := NewCircuitBreaker(CircuitBreakerConfig{
+		MaxFailures:  1,
+		Timeout:      100 * time.Millisecond,
+		ResetTimeout: 50 * time.Millisecond,
+	}, NewLogger("error"))
+
+	err := cb.ExecuteWithContext(context.Background(), func() error {
+		return &HTTPError{StatusCode: 400, Message: "invalid_grant"}
+	})
+	if err == nil {
+		t.Fatal("expected the probe's own error to be returned to the caller")
+	}
+	if cb.GetState() != CircuitBreakerClosed {
+		t.Fatalf("a terminal client 4xx must not trip a closed circuit, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+
+	err = cb.ExecuteWithContext(context.Background(), func() error {
+		return &HTTPError{StatusCode: 500, Message: "downstream unavailable"}
+	})
+	if err == nil {
+		t.Fatal("expected the tripping call to return its own error")
+	}
+	if cb.GetState() != CircuitBreakerOpen {
+		t.Fatalf("a genuine 5xx must still open a closed circuit, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+}

error_recovery_fix14_test.go

@@ -0,0 +1,104 @@
+package traefikoidc
+
+import (
+	"context"
+	"errors"
+	"net"
+	"syscall"
+	"testing"
+)
+
+// TestExecuteSingleUseWithContextNeverRetriesAfterHTTPResponse is a
+// regression test for FIX-14.
+//
+// helpers.go's token-endpoint exchange returns a *HTTPError whose Message
+// carries up to 10 KiB of the raw response body once a non-200 status is
+// received (helpers.go:192-195). Before the fix, ExecuteSingleUseWithContext
+// matched singleUseRetryableErrors as a plain substring of err.Error(), so
+// an IdP 500 whose body happens to mention "connection refused" (e.g. the
+// IdP's own downstream error) was retried up to MaxAttempts times even
+// though the request had definitely already reached the server. For a
+// single-use operation (authorization-code exchange, refresh) re-sending
+// consumed input causes invalid_grant or refresh-token-family revocation.
+//
+// Fail-on-old: fn is called 3 times (MaxAttempts) instead of once.
+func TestExecuteSingleUseWithContextNeverRetriesAfterHTTPResponse(t *testing.T) {
+	re := NewRetryExecutor(RetryConfig{
+		MaxAttempts:   3,
+		InitialDelay:  1,
+		MaxDelay:      1,
+		BackoffFactor: 1,
+	}, NewLogger("error"))
+
+	calls := 0
+	err := re.ExecuteSingleUseWithContext(context.Background(), func() error {
+		calls++
+		return &HTTPError{
+			StatusCode: 500,
+			Message:    "token endpoint returned status 500: {\"error\":\"server_error\",\"detail\":\"upstream: connection refused\"}",
+		}
+	})
+
+	if err == nil {
+		t.Fatal("expected the HTTPError to be returned")
+	}
+	if calls != 1 {
+		t.Fatalf("fn called %d times, want 1: an HTTP response proves the request was already sent and must never be retried for a single-use operation", calls)
+	}
+}
+
+// TestExecuteSingleUseWithContextStillRetriesRealDialError guards against
+// over-broadening the FIX-14 fix: a genuine dial/connect failure -- proof
+// the request never reached the server -- must still be retried.
+func TestExecuteSingleUseWithContextStillRetriesRealDialError(t *testing.T) {
+	re := NewRetryExecutor(RetryConfig{
+		MaxAttempts:   3,
+		InitialDelay:  1,
+		MaxDelay:      1,
+		BackoffFactor: 1,
+	}, NewLogger("error"))
+
+	calls := 0
+	err := re.ExecuteSingleUseWithContext(context.Background(), func() error {
+		calls++
+		if calls == 1 {
+			return &net.OpError{Op: "dial", Net: "tcp", Err: errors.New("connection refused")}
+		}
+		return nil
+	})
+
+	if err != nil {
+		t.Fatalf("expected the retried call to succeed, got: %v", err)
+	}
+	if calls != 2 {
+		t.Fatalf("fn called %d times, want 2: a real dial error must still be retried", calls)
+	}
+}
+
+// TestExecuteSingleUseWithContextNeverRetriesPostSendOpError pins FIX-14's
+// minor finding: isNeverSentError must match a *net.OpError only for Op
+// "dial" or "proxyconnect" (proof the request never reached the far end).
+// A "read"/"write" OpError happens after the connection is already
+// established, when the single-use request may already have reached the
+// IdP, and must not be retried.
+func TestExecuteSingleUseWithContextNeverRetriesPostSendOpError(t *testing.T) {
+	re := NewRetryExecutor(RetryConfig{
+		MaxAttempts:   3,
+		InitialDelay:  1,
+		MaxDelay:      1,
+		BackoffFactor: 1,
+	}, NewLogger("error"))
+
+	calls := 0
+	err := re.ExecuteSingleUseWithContext(context.Background(), func() error {
+		calls++
+		return &net.OpError{Op: "read", Net: "tcp", Err: syscall.EHOSTUNREACH}
+	})
+
+	if err == nil {
+		t.Fatal("expected the OpError to be returned")
+	}
+	if calls != 1 {
+		t.Fatalf("fn called %d times, want 1: a post-send (read/write) OpError must not be retried for a single-use operation", calls)
+	}
+}

error_recovery_test.go

@@ -89,18 +89,50 @@ func TestCircuitBreakerHalfOpenTransition(t *testing.T) {
 
 	time.Sleep(150 * time.Millisecond)
 
-	allowed := false
-	_ = cb.Execute(func() error {
-		allowed = true
-		return nil
-	})
-
-	if !allowed {
-		t.Error("Request should be allowed in half-open state")
+	// First request after the open timeout probes half-open. A single success
+	// does NOT immediately close: the circuit stays half-open until
+	// resetTimeout has elapsed (reset-cooldown hysteresis).
+	if err := cb.Execute(func() error { return nil }); err != nil {
+		t.Errorf("Request should be allowed in half-open state, got: %v", err)
+	}
+	if cb.GetState() != CircuitBreakerHalfOpen {
+		t.Errorf("Circuit should stay half-open during reset cooldown, got %v", circuitBreakerStateToString(cb.GetState()))
 	}
 
+	// After resetTimeout elapses, a successful request fully closes it.
+	time.Sleep(60 * time.Millisecond)
+	if err := cb.Execute(func() error { return nil }); err != nil {
+		t.Errorf("Request should be allowed, got: %v", err)
+	}
 	if cb.GetState() != CircuitBreakerClosed {
-		t.Errorf("Circuit should be closed after successful half-open request, got %v", cb.GetState())
+		t.Errorf("Circuit should be closed after successful request following reset cooldown, got %v", circuitBreakerStateToString(cb.GetState()))
+	}
+}
+
+// TestCircuitBreakerResetTimeoutEnforced is a regression test for the dead
+// resetTimeout config field: it must be consulted before a half-open success
+// can fully close the circuit. This failed on the old code where resetTimeout
+// was set but never read, so a single half-open success closed the circuit
+// immediately regardless of the configured reset cooldown.
+func TestCircuitBreakerResetTimeoutEnforced(t *testing.T) {
+	cb := NewCircuitBreaker(CircuitBreakerConfig{
+		MaxFailures:  1,
+		Timeout:      50 * time.Millisecond,
+		ResetTimeout: time.Minute,
+	}, nil)
+
+	_ = cb.Execute(func() error { return errors.New("fail") })
+	if cb.GetState() != CircuitBreakerOpen {
+		t.Fatal("circuit should be open after failure")
+	}
+
+	time.Sleep(70 * time.Millisecond) // past the open timeout -> half-open
+
+	if err := cb.Execute(func() error { return nil }); err != nil {
+		t.Fatalf("request should be allowed in half-open state, got: %v", err)
+	}
+	if cb.GetState() != CircuitBreakerHalfOpen {
+		t.Fatalf("circuit must remain half-open until resetTimeout elapses, got %v", circuitBreakerStateToString(cb.GetState()))
 	}
 }
 
@@ -243,7 +275,13 @@ func TestCircuitBreakerIsAvailable(t *testing.T) {
 	time.Sleep(150 * time.Millisecond)
 
 	if !cb.IsAvailable() {
-		t.Error("Circuit should be available in half-open state")
+		t.Error("Circuit should report availability once the open timeout has elapsed")
+	}
+	// R94: IsAvailable is a read-only probe and must not mutate circuit
+	// state. Merely checking availability must NOT transition the circuit
+	// to half-open (that is the job of real request admission).
+	if got := cb.GetState(); got != CircuitBreakerOpen {
+		t.Errorf("IsAvailable must not change circuit state; expected Open, got %v", got)
 	}
 }
 
@@ -1097,6 +1135,7 @@ func TestBaseRecoveryMechanism_LogMethods(t *testing.T) {
 
 func TestErrorRecoveryManagerCreation(t *testing.T) {
 	erm := NewErrorRecoveryManager(nil)
+	t.Cleanup(erm.Close)
 
 	if erm == nil {
 		t.Fatal("Expected non-nil error recovery manager")
@@ -1113,6 +1152,7 @@ func TestErrorRecoveryManagerCreation(t *testing.T) {
 
 func TestErrorRecoveryManagerGetCircuitBreaker(t *testing.T) {
 	erm := NewErrorRecoveryManager(nil)
+	t.Cleanup(erm.Close)
 
 	cb1 := erm.GetCircuitBreaker("service1")
 	cb2 := erm.GetCircuitBreaker("service1")
@@ -1133,6 +1173,7 @@ func TestErrorRecoveryManagerGetCircuitBreaker(t *testing.T) {
 
 func TestErrorRecoveryManagerExecuteWithRecovery(t *testing.T) {
 	erm := NewErrorRecoveryManager(nil)
+	t.Cleanup(erm.Close)
 
 	success := false
 	err := erm.ExecuteWithRecovery(context.Background(), "test-service", func() error {
@@ -1151,6 +1192,7 @@ func TestErrorRecoveryManagerExecuteWithRecovery(t *testing.T) {
 
 func TestErrorRecoveryManagerMetrics(t *testing.T) {
 	erm := NewErrorRecoveryManager(nil)
+	t.Cleanup(erm.Close)
 
 	_ = erm.GetCircuitBreaker("service1")
 	_ = erm.GetCircuitBreaker("service2")
@@ -1170,6 +1212,7 @@ func TestErrorRecoveryManagerMetrics(t *testing.T) {
 func TestErrorRecoveryManagerIntegration(t *testing.T) {
 	logger := GetSingletonNoOpLogger()
 	erm := NewErrorRecoveryManager(logger)
+	t.Cleanup(erm.Close)
 
 	t.Run("circuit breaker and retry integration", func(t *testing.T) {
 		cb := NewCircuitBreaker(CircuitBreakerConfig{
@@ -1271,9 +1314,12 @@ func TestGracefulDegradationRegisterHealthCheck(t *testing.T) {
 	defer gd.Close()
 
 	t.Run("register health check", func(t *testing.T) {
-		healthy := true
+		var healthy atomic.Bool
+		healthy.Store(true)
+		// The health check runs on a background goroutine (performHealthChecks at
+		// the configured interval); a plain captured bool would be a data race.
 		healthCheck := func() bool {
-			return healthy
+			return healthy.Load()
 		}
 
 		gd.RegisterHealthCheck("service1", healthCheck)
@@ -1281,7 +1327,7 @@ func TestGracefulDegradationRegisterHealthCheck(t *testing.T) {
 		gd.markServiceDegraded("service1")
 		assert.True(t, gd.isServiceDegraded("service1"))
 
-		healthy = true
+		healthy.Store(true)
 		time.Sleep(100 * time.Millisecond)
 	})
 }
@@ -1507,6 +1553,13 @@ func TestGracefulDegradationHealthChecks(t *testing.T) {
 		config := DefaultGracefulDegradationConfig()
 		gd := NewGracefulDegradation(config, logger)
 		defer gd.Close()
+		// The shared health-check task runs this gd's checks in the background
+		// (globalPerformHealthChecks). Hold its pass lock so that pass cannot
+		// run the check concurrently with the direct call below or change the
+		// degraded state between the assertions. The deferred Unlock runs
+		// before the deferred Close, so Close never waits on a blocked pass.
+		globalHealthCheckMu.Lock()
+		defer globalHealthCheckMu.Unlock()
 
 		healthCheckCalled := false
 		gd.RegisterHealthCheck("test-service", func() bool {
@@ -1529,6 +1582,9 @@ func TestGracefulDegradationHealthChecks(t *testing.T) {
 		config := DefaultGracefulDegradationConfig()
 		gd := NewGracefulDegradation(config, logger)
 		defer gd.Close()
+		// Keep the shared background pass out of this subtest (see above).
+		globalHealthCheckMu.Lock()
+		defer globalHealthCheckMu.Unlock()
 
 		gd.RegisterHealthCheck("failing-service", func() bool {
 			return false
@@ -1609,9 +1665,12 @@ func TestGracefulDegradationFullScenario(t *testing.T) {
 		return "fallback data", nil
 	})
 
-	serviceHealthy := false
+	var serviceHealthy atomic.Bool
+	serviceHealthy.Store(false)
+	// Health checks run on a background goroutine (performHealthChecks at the
+	// configured interval); a plain captured bool is a data race.
 	gd.RegisterHealthCheck("critical-service", func() bool {
-		return serviceHealthy
+		return serviceHealthy.Load()
 	})
 
 	result1, err1 := gd.ExecuteWithFallback("critical-service", func() (interface{}, error) {
@@ -1634,7 +1693,7 @@ func TestGracefulDegradationFullScenario(t *testing.T) {
 	assert.NoError(t, err3)
 	assert.Equal(t, "fallback data", result3)
 
-	serviceHealthy = true
+	serviceHealthy.Store(true)
 	time.Sleep(250 * time.Millisecond)
 
 	metrics := gd.GetMetrics()

examples/complete-traefik-config.yaml

@@ -445,22 +445,22 @@ spec:
 # you can set these. NOTE: Plugin configuration takes precedence!
 
 # Docker Compose env file (.env)
----
+# ----- (below is an example .env file, NOT YAML — shown for reference) -----
 # OIDC Configuration
-OIDC_CLIENT_ID=your-client-id
-OIDC_CLIENT_SECRET=your-client-secret
-OIDC_PROVIDER_URL=https://auth.example.com
+# OIDC_CLIENT_ID=your-client-id
+# OIDC_CLIENT_SECRET=your-client-secret
+# OIDC_PROVIDER_URL=https://auth.example.com
 
 # Redis Configuration (fallback)
-REDIS_ENABLED=true
-REDIS_ADDRESS=redis:6379
-REDIS_PASSWORD=yourredispassword
-REDIS_DB=0
-REDIS_KEY_PREFIX=traefikoidc:
-REDIS_CACHE_MODE=hybrid
-REDIS_POOL_SIZE=20
-REDIS_ENABLE_CIRCUIT_BREAKER=true
-REDIS_ENABLE_HEALTH_CHECK=true
+# REDIS_ENABLED=true
+# REDIS_ADDRESS=redis:6379
+# REDIS_PASSWORD=yourredispassword
+# REDIS_DB=0
+# REDIS_KEY_PREFIX=traefikoidc:
+# REDIS_CACHE_MODE=hybrid
+# REDIS_POOL_SIZE=20
+# REDIS_ENABLE_CIRCUIT_BREAKER=true
+# REDIS_ENABLE_HEALTH_CHECK=true
 
 
 # ============================================================================

fix02_options_bypass_test.go

@@ -0,0 +1,226 @@
+package traefikoidc
+
+// Regression tests for FIX-02 (review-2026-09-10 finding at
+// middleware.go:105): shouldBypassAuth bypassed OIDC auth for ANY request
+// whose method is OPTIONS, not only genuine CORS preflights. A real
+// preflight always carries both an Origin header and an
+// Access-Control-Request-Method header; the R124 fix checked only the
+// method, so an unauthenticated `OPTIONS <protected-path>` with neither
+// header reached the backend unauthenticated (reproduced against
+// http.FileServer: 200 with the protected file's body).
+//
+// TestServeHTTP_ForgedPreflightDoesNotLeakBody hardens the residual gap a
+// follow-up review found in that fix: the Origin +
+// Access-Control-Request-Method check only rules out an accidental bare
+// OPTIONS request, not a deliberate attacker, since any non-browser client
+// can set both headers itself. bypassReasonOptions still forwarded to next
+// with no session check, so a forged preflight against http.FileServer
+// still returned the protected file's body.
+//
+// A later maintainer decision (the AllowUnauthenticatedPreflight config
+// option, settings.go) restored the released default: every OPTIONS request
+// -- genuine preflight or not -- needs auth unless the operator opts in.
+// Every test below that exercises the bypass path (positive or negative)
+// sets allowUnauthenticatedPreflight: true so it keeps testing the
+// Origin+Access-Control-Request-Method gate itself rather than the flag
+// gate placed in front of it. The default-off case is pinned separately by
+// TestServeHTTP_DefaultConfigGenuinePreflightRequiresAuth in
+// fix02b_allow_unauthenticated_preflight_test.go.
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestShouldBypassAuth_BareOptionsDoesNotBypass pins the negative case: a
+// bare OPTIONS request carrying neither Origin nor
+// Access-Control-Request-Method is not a CORS preflight and must go
+// through the normal auth pipeline like any other method.
+func TestShouldBypassAuth_BareOptionsDoesNotBypass(t *testing.T) {
+	tObj := &TraefikOidc{logger: GetSingletonNoOpLogger(), allowUnauthenticatedPreflight: true}
+	req := httptest.NewRequest(http.MethodOptions, "/api/resource", nil)
+
+	if bypass, reason := tObj.shouldBypassAuth(req); bypass {
+		t.Fatalf("bare OPTIONS (no Origin, no Access-Control-Request-Method) must not bypass auth, got bypass reason %q", reason)
+	}
+}
+
+// TestShouldBypassAuth_OptionsWithOnlyOriginDoesNotBypass pins a partial
+// case: Origin alone (e.g. a plain cross-origin GET, not a preflight) must
+// not bypass either -- both headers are required.
+func TestShouldBypassAuth_OptionsWithOnlyOriginDoesNotBypass(t *testing.T) {
+	tObj := &TraefikOidc{logger: GetSingletonNoOpLogger(), allowUnauthenticatedPreflight: true}
+	req := httptest.NewRequest(http.MethodOptions, "/api/resource", nil)
+	req.Header.Set("Origin", "https://app.example.com")
+
+	if bypass, reason := tObj.shouldBypassAuth(req); bypass {
+		t.Fatalf("OPTIONS with only Origin set must not bypass auth, got bypass reason %q", reason)
+	}
+}
+
+// TestShouldBypassAuth_GenuinePreflightBypasses pins the positive case: a
+// real CORS preflight (Origin + Access-Control-Request-Method) must still
+// bypass auth, so a browser's actual preflight keeps working.
+func TestShouldBypassAuth_GenuinePreflightBypasses(t *testing.T) {
+	tObj := &TraefikOidc{logger: GetSingletonNoOpLogger(), allowUnauthenticatedPreflight: true}
+	req := httptest.NewRequest(http.MethodOptions, "/api/resource", nil)
+	req.Header.Set("Origin", "https://app.example.com")
+	req.Header.Set("Access-Control-Request-Method", "GET")
+
+	bypass, reason := tObj.shouldBypassAuth(req)
+	if !bypass {
+		t.Fatal("a genuine CORS preflight (Origin + Access-Control-Request-Method) must bypass auth")
+	}
+	if reason != bypassReasonOptions {
+		t.Fatalf("preflight bypass reason = %q, want %q", reason, bypassReasonOptions)
+	}
+}
+
+// TestServeHTTP_UnauthenticatedBareOptionsDoesNotReachBackend is the
+// end-to-end reproduction from the finding: an unauthenticated OPTIONS
+// request against a protected path, with no session cookie and no CORS
+// headers, must not reach the next handler. Mirrors the reviewer's
+// http.FileServer repro that returned the protected file's body.
+func TestServeHTTP_UnauthenticatedBareOptionsDoesNotReachBackend(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	nextCalled := false
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		nextCalled = true
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("TOP-SECRET-PAYROLL"))
+	})
+
+	initComplete := make(chan struct{})
+	close(initComplete)
+
+	tObj := &TraefikOidc{
+		logger:                        GetSingletonNoOpLogger(),
+		name:                          "test",
+		next:                          next,
+		sessionManager:                sm,
+		redirURLPath:                  "/callback",
+		authURL:                       "https://idp.example.com/authorize",
+		issuerURL:                     "https://idp.example.com",
+		clientID:                      "test-client-id",
+		scopes:                        []string{"openid"},
+		initComplete:                  initComplete,
+		allowUnauthenticatedPreflight: true,
+	}
+
+	req := httptest.NewRequest(http.MethodOptions, "https://app.example.com/secret.txt", nil)
+	rw := httptest.NewRecorder()
+
+	tObj.ServeHTTP(rw, req)
+
+	if nextCalled {
+		t.Fatalf("unauthenticated bare OPTIONS must not reach the backend, but next handler ran (status=%d body=%q)", rw.Code, rw.Body.String())
+	}
+	if rw.Code == http.StatusOK && strings.Contains(rw.Body.String(), "TOP-SECRET-PAYROLL") {
+		t.Fatalf("protected content leaked through an unauthenticated OPTIONS request: status=%d body=%q", rw.Code, rw.Body.String())
+	}
+}
+
+// TestServeHTTP_GenuinePreflightReachesBackend confirms the fix does not
+// regress the R124 behavior it builds on: a real CORS preflight for the
+// same protected path must still reach the backend unconditionally.
+func TestServeHTTP_GenuinePreflightReachesBackend(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	nextCalled := false
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		nextCalled = true
+		w.Header().Set("Access-Control-Allow-Origin", "https://app.example.com")
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	initComplete := make(chan struct{})
+	close(initComplete)
+
+	tObj := &TraefikOidc{
+		logger:                        GetSingletonNoOpLogger(),
+		name:                          "test",
+		next:                          next,
+		sessionManager:                sm,
+		redirURLPath:                  "/callback",
+		authURL:                       "https://idp.example.com/authorize",
+		issuerURL:                     "https://idp.example.com",
+		clientID:                      "test-client-id",
+		scopes:                        []string{"openid"},
+		initComplete:                  initComplete,
+		allowUnauthenticatedPreflight: true,
+	}
+
+	req := httptest.NewRequest(http.MethodOptions, "https://app.example.com/secret.txt", nil)
+	req.Header.Set("Origin", "https://app.example.com")
+	req.Header.Set("Access-Control-Request-Method", "GET")
+	rw := httptest.NewRecorder()
+
+	tObj.ServeHTTP(rw, req)
+
+	if !nextCalled {
+		t.Fatalf("a genuine CORS preflight must still reach the backend, got status=%d body=%q", rw.Code, rw.Body.String())
+	}
+}
+
+// TestServeHTTP_ForgedPreflightDoesNotLeakBody reproduces the finding's own
+// exploit: a non-browser client sends an OPTIONS request carrying BOTH
+// Origin and Access-Control-Request-Method (indistinguishable from a real
+// preflight to shouldBypassAuth) against a protected path, with no session
+// cookie. It must not receive the backend's response body, even though the
+// request still forwards unauthenticated so a real browser preflight keeps
+// getting its CORS headers answered.
+func TestServeHTTP_ForgedPreflightDoesNotLeakBody(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "secret.txt"), []byte("TOP-SECRET-PAYROLL"), 0o600); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+	next := http.FileServer(http.Dir(dir))
+
+	initComplete := make(chan struct{})
+	close(initComplete)
+
+	tObj := &TraefikOidc{
+		logger:                        GetSingletonNoOpLogger(),
+		name:                          "test",
+		next:                          next,
+		sessionManager:                sm,
+		redirURLPath:                  "/callback",
+		authURL:                       "https://idp.example.com/authorize",
+		issuerURL:                     "https://idp.example.com",
+		clientID:                      "test-client-id",
+		scopes:                        []string{"openid"},
+		initComplete:                  initComplete,
+		allowUnauthenticatedPreflight: true,
+	}
+
+	req := httptest.NewRequest(http.MethodOptions, "https://app.example.com/secret.txt", nil)
+	req.Header.Set("Origin", "https://attacker.example")
+	req.Header.Set("Access-Control-Request-Method", "GET")
+	rw := httptest.NewRecorder()
+
+	tObj.ServeHTTP(rw, req)
+
+	if strings.Contains(rw.Body.String(), "TOP-SECRET-PAYROLL") {
+		t.Fatalf("forged preflight leaked protected content: status=%d body=%q", rw.Code, rw.Body.String())
+	}
+}

fix02b_allow_unauthenticated_preflight_test.go

@@ -0,0 +1,167 @@
+package traefikoidc
+
+// Regression tests for the FIX-02 maintainer decision: the released
+// behavior required authentication for every OPTIONS request by default.
+// FIX-02 (fix02_options_bypass_test.go) narrowed an accidental
+// unconditional OPTIONS bypass down to genuine CORS preflights (Origin +
+// Access-Control-Request-Method), but that still left every preflight
+// unauthenticated by default -- a behavior change from the release. This
+// file pins the maintainer decision to restore released behavior: the
+// preflight bypass now only applies when the operator opts in via
+// AllowUnauthenticatedPreflight (default false). With the flag off, OPTIONS
+// goes through the normal auth pipeline like any other method.
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestServeHTTP_DefaultConfigGenuinePreflightRequiresAuth pins the default
+// (AllowUnauthenticatedPreflight=false) behavior: even a genuine CORS
+// preflight (Origin + Access-Control-Request-Method) must NOT reach the
+// backend without a session -- it goes through the normal auth pipeline
+// (redirect or 401) exactly like any other unauthenticated request. This is
+// the released behavior FIX-02 must restore by default.
+func TestServeHTTP_DefaultConfigGenuinePreflightRequiresAuth(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	nextCalled := false
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		nextCalled = true
+		w.Header().Set("Access-Control-Allow-Origin", "https://app.example.com")
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	initComplete := make(chan struct{})
+	close(initComplete)
+
+	tObj := &TraefikOidc{
+		logger:         GetSingletonNoOpLogger(),
+		name:           "test",
+		next:           next,
+		sessionManager: sm,
+		redirURLPath:   "/callback",
+		authURL:        "https://idp.example.com/authorize",
+		issuerURL:      "https://idp.example.com",
+		clientID:       "test-client-id",
+		scopes:         []string{"openid"},
+		initComplete:   initComplete,
+		// AllowUnauthenticatedPreflight left at its zero value (false):
+		// default config must not bypass auth for OPTIONS.
+	}
+
+	req := httptest.NewRequest(http.MethodOptions, "https://app.example.com/secret.txt", nil)
+	req.Header.Set("Origin", "https://app.example.com")
+	req.Header.Set("Access-Control-Request-Method", "GET")
+	rw := httptest.NewRecorder()
+
+	tObj.ServeHTTP(rw, req)
+
+	if nextCalled {
+		t.Fatalf("default config (allowUnauthenticatedPreflight=false) must send a genuine OPTIONS preflight through the normal auth pipeline, but the backend was called unconditionally: status=%d body=%q", rw.Code, rw.Body.String())
+	}
+	if rw.Code == http.StatusNoContent {
+		t.Fatalf("default config must not answer the preflight bypass response (204 from next); got status=%d", rw.Code)
+	}
+}
+
+// TestServeHTTP_AllowUnauthenticatedPreflight_GenuinePreflightBypassesBodyDiscarded
+// pins the opt-in behavior: with AllowUnauthenticatedPreflight=true, a
+// genuine CORS preflight still bypasses auth (so real browser preflights
+// keep working) and the optionsPreflightWriter still discards the body
+// (FIX-02's forged-preflight hardening keeps applying when the flag is on).
+func TestServeHTTP_AllowUnauthenticatedPreflight_GenuinePreflightBypassesBodyDiscarded(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "secret.txt"), []byte("TOP-SECRET-PAYROLL"), 0o600); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+	next := http.FileServer(http.Dir(dir))
+
+	initComplete := make(chan struct{})
+	close(initComplete)
+
+	tObj := &TraefikOidc{
+		logger:                        GetSingletonNoOpLogger(),
+		name:                          "test",
+		next:                          next,
+		sessionManager:                sm,
+		redirURLPath:                  "/callback",
+		authURL:                       "https://idp.example.com/authorize",
+		issuerURL:                     "https://idp.example.com",
+		clientID:                      "test-client-id",
+		scopes:                        []string{"openid"},
+		initComplete:                  initComplete,
+		allowUnauthenticatedPreflight: true,
+	}
+
+	req := httptest.NewRequest(http.MethodOptions, "https://app.example.com/secret.txt", nil)
+	req.Header.Set("Origin", "https://app.example.com")
+	req.Header.Set("Access-Control-Request-Method", "GET")
+	rw := httptest.NewRecorder()
+
+	tObj.ServeHTTP(rw, req)
+
+	if strings.Contains(rw.Body.String(), "TOP-SECRET-PAYROLL") {
+		t.Fatalf("allowUnauthenticatedPreflight=true must still discard the preflight response body: status=%d body=%q", rw.Code, rw.Body.String())
+	}
+}
+
+// TestServeHTTP_AllowUnauthenticatedPreflight_BareOptionsStillRequiresAuth
+// pins that the flag only widens the genuine-preflight gate -- a bare
+// OPTIONS request (no Origin, no Access-Control-Request-Method) still needs
+// auth even with AllowUnauthenticatedPreflight=true.
+func TestServeHTTP_AllowUnauthenticatedPreflight_BareOptionsStillRequiresAuth(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	nextCalled := false
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		nextCalled = true
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("TOP-SECRET-PAYROLL"))
+	})
+
+	initComplete := make(chan struct{})
+	close(initComplete)
+
+	tObj := &TraefikOidc{
+		logger:                        GetSingletonNoOpLogger(),
+		name:                          "test",
+		next:                          next,
+		sessionManager:                sm,
+		redirURLPath:                  "/callback",
+		authURL:                       "https://idp.example.com/authorize",
+		issuerURL:                     "https://idp.example.com",
+		clientID:                      "test-client-id",
+		scopes:                        []string{"openid"},
+		initComplete:                  initComplete,
+		allowUnauthenticatedPreflight: true,
+	}
+
+	req := httptest.NewRequest(http.MethodOptions, "https://app.example.com/secret.txt", nil)
+	rw := httptest.NewRecorder()
+
+	tObj.ServeHTTP(rw, req)
+
+	if nextCalled {
+		t.Fatalf("allowUnauthenticatedPreflight=true must not bypass auth for a bare OPTIONS request (no Origin/Access-Control-Request-Method), but the backend was called: status=%d body=%q", rw.Code, rw.Body.String())
+	}
+}

fix05_session_chunk_replace_test.go

@@ -0,0 +1,183 @@
+package traefikoidc
+
+// Regression tests for FIX-05 (review-2026-09-10 finding at session.go:2409,
+// session.go:3099): SetRefreshToken/SetIDToken re-Get the gorilla-registry-
+// cached chunk *sessions.Session objects for the NEW token, fill them, and
+// only THEN call the expire helper for the OLD chunks. Because gorilla's
+// Registry.Get returns the SAME cached object per cookie name for a given
+// request, the "expire old" pass re-Gets those identical objects and wipes
+// session.Values on every non-new one -- erasing the NEW chunk data this
+// call just wrote. A session loaded from existing (legacy) chunk cookies
+// whose replacement token also needs chunking loses the new token entirely.
+//
+// Adapted from the throwaway repro at
+// .claude/review-2026-09-10/repro/zz_g1_chunkwipe_test.go and
+// zz_g1_chunkwipe_id_test.go (TestG1ChunkWipeRefresh / TestG1ChunkWipeAccessControl
+// / TestG1ChunkWipeIDToken), renamed to describe the behavior they pin.
+
+import (
+	"crypto/rand"
+	"encoding/base64"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+// randChunkTestToken returns a random URL-safe token of n raw bytes, large
+// enough (with maxCookieSize=1400) to force the chunked storage path.
+func randChunkTestToken(t *testing.T, n int) string {
+	t.Helper()
+	b := make([]byte, n)
+	if _, err := rand.Read(b); err != nil {
+		t.Fatal(err)
+	}
+	return base64.RawURLEncoding.EncodeToString(b)
+}
+
+// randChunkTestJWT returns a structurally valid (3-dot-separated) JWT whose
+// payload is padded past maxCookieSize, so SetIDToken takes the chunked path.
+func randChunkTestJWT(t *testing.T) string {
+	t.Helper()
+	enc := base64.RawURLEncoding.EncodeToString
+	header := enc([]byte(`{"alg":"RS256","typ":"JWT","kid":"k"}`))
+	now := time.Now().Unix()
+	payload := enc([]byte(fmt.Sprintf(
+		`{"iss":"https://idp","sub":"u","aud":"c","iat":%d,"exp":%d,"pad":"%s"}`,
+		now, now+3600, randChunkTestToken(t, 3000),
+	)))
+	return header + "." + payload + "." + randChunkTestToken(t, 256)
+}
+
+// mergeSetCookiesIntoJar copies a response's Set-Cookie headers into jar,
+// dropping any cookie the response expired (MaxAge < 0), so the next request
+// carries forward only what a real browser would still hold.
+func mergeSetCookiesIntoJar(jar map[string]*http.Cookie, rr *httptest.ResponseRecorder) {
+	for _, c := range rr.Result().Cookies() {
+		if c.MaxAge < 0 {
+			delete(jar, c.Name)
+			continue
+		}
+		jar[c.Name] = c
+	}
+}
+
+// newRequestWithJarCookies builds a request carrying every cookie currently
+// held in jar, simulating a browser replaying its cookie jar on the next
+// request to the same session.
+func newRequestWithJarCookies(jar map[string]*http.Cookie) *http.Request {
+	r := httptest.NewRequest(http.MethodGet, "https://app.example.com/", nil)
+	for _, c := range jar {
+		r.AddCookie(&http.Cookie{Name: c.Name, Value: c.Value})
+	}
+	return r
+}
+
+// runChunkedTokenReplaceRegression drives three requests against one
+// SessionManager: request 1 stores a large (chunked) token A and saves it,
+// request 2 loads the cookies A produced and replaces the token with a
+// different large (chunked) token B, request 3 loads the cookies B produced
+// and must read back B, not A and not empty.
+func runChunkedTokenReplaceRegression(
+	t *testing.T,
+	set func(*SessionData, string),
+	get func(*SessionData) string,
+	tokA, tokB string,
+) {
+	t.Helper()
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	jar := map[string]*http.Cookie{}
+
+	r1 := newRequestWithJarCookies(jar)
+	s1, err := sm.GetSession(r1)
+	if err != nil {
+		t.Fatalf("GetSession (request 1): %v", err)
+	}
+	set(s1, tokA)
+	rr1 := httptest.NewRecorder()
+	if err := s1.Save(r1, rr1); err != nil {
+		t.Fatalf("Save (request 1): %v", err)
+	}
+	s1.returnToPoolSafely()
+	mergeSetCookiesIntoJar(jar, rr1)
+
+	r2 := newRequestWithJarCookies(jar)
+	s2, err := sm.GetSession(r2)
+	if err != nil {
+		t.Fatalf("GetSession (request 2): %v", err)
+	}
+	if got := get(s2); got != tokA {
+		t.Fatalf("request 2 must load token A written by request 1 before replacing it: got len=%d, want tokA", len(got))
+	}
+	set(s2, tokB)
+	if got := get(s2); got != tokB {
+		t.Fatalf("in-memory read immediately after replacing the chunked token must return the NEW token: got len=%d (isA=%v), want tokB", len(got), got == tokA)
+	}
+	rr2 := httptest.NewRecorder()
+	if err := s2.Save(r2, rr2); err != nil {
+		t.Fatalf("Save (request 2): %v", err)
+	}
+	s2.returnToPoolSafely()
+	mergeSetCookiesIntoJar(jar, rr2)
+
+	r3 := newRequestWithJarCookies(jar)
+	s3, err := sm.GetSession(r3)
+	if err != nil {
+		t.Fatalf("GetSession (request 3): %v", err)
+	}
+	defer s3.returnToPoolSafely()
+	got := get(s3)
+	if got != tokB {
+		t.Fatalf("after replacing a chunked token loaded from cookies: got len=%d (isTokA=%v), want tokB (the user would be silently signed out)", len(got), got == tokA)
+	}
+}
+
+// TestSessionData_SetRefreshToken_ReplacesChunkedTokenLoadedFromCookies pins
+// FIX-05 (session.go:2409): replacing a chunked refresh token that was
+// loaded from existing chunk cookies must not wipe the newly written chunks.
+func TestSessionData_SetRefreshToken_ReplacesChunkedTokenLoadedFromCookies(t *testing.T) {
+	tokA := randChunkTestToken(t, 4500)
+	tokB := randChunkTestToken(t, 4500)
+	runChunkedTokenReplaceRegression(
+		t,
+		func(s *SessionData, v string) { s.SetRefreshToken(v) },
+		func(s *SessionData) string { return s.GetRefreshToken() },
+		tokA, tokB,
+	)
+}
+
+// TestSessionData_SetIDToken_ReplacesChunkedTokenLoadedFromCookies pins
+// FIX-05 (session.go:3099): the same bug in SetIDToken, using structurally
+// valid JWTs since SetIDToken rejects non-JWT-shaped input.
+func TestSessionData_SetIDToken_ReplacesChunkedTokenLoadedFromCookies(t *testing.T) {
+	tokA := randChunkTestJWT(t)
+	tokB := randChunkTestJWT(t)
+	runChunkedTokenReplaceRegression(
+		t,
+		func(s *SessionData, v string) { s.SetIDToken(v) },
+		func(s *SessionData) string { return s.GetIDToken() },
+		tokA, tokB,
+	)
+}
+
+// TestSessionData_SetAccessToken_ReplacesChunkedTokenLoadedFromCookies is the
+// control: SetAccessToken already uses the expire-then-fill order (it was
+// unaffected by the R154 regression) and must stay green both before and
+// after FIX-05, proving the fix does not depend on a shared helper bug.
+func TestSessionData_SetAccessToken_ReplacesChunkedTokenLoadedFromCookies(t *testing.T) {
+	tokA := randChunkTestToken(t, 4500)
+	tokB := randChunkTestToken(t, 4500)
+	runChunkedTokenReplaceRegression(
+		t,
+		func(s *SessionData, v string) { s.SetAccessToken(v) },
+		func(s *SessionData) string { return s.GetAccessToken() },
+		tokA, tokB,
+	)
+}

fix06_downstream_writer_test.go

@@ -0,0 +1,163 @@
+package traefikoidc
+
+// Regression tests for FIX-06 (review-2026-09-10 finding at
+// middleware.go:309, high severity): ServeHTTP wraps the response writer
+// in *trackingWriter for panic-commit tracking (rw = tw) and then hands
+// that SAME wrapped writer to every t.next.ServeHTTP call, including the
+// SSE/WebSocket bypass and the authenticated forwarding path. Traefik runs
+// this plugin interpreted under yaegi v0.16.1, and yaegi's stdlib
+// interop layer composes a boundary wrapper only for ResponseWriter+
+// Hijacker crossing into compiled code -- not for Flusher or Unwrap. So
+// Traefik's compiled ReverseProxy calling
+// http.NewResponseController(rw).Flush() on the interpreted trackingWriter
+// gets "feature not supported" in production, even though trackingWriter
+// declares Flush/Unwrap and native tests (which never cross an
+// interpreter boundary) pass. See checkSSEFlushReachesNext in cmd/yaegicheck/main.go (run by
+// `make yaegi-validate`) for the interop reproduction.
+//
+// The fix hands t.next.ServeHTTP the ORIGINAL writer ServeHTTP received
+// (trackingWriter.Unwrap()), never the wrapper, on every forwarding path.
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+// nextWriterSpy is a minimal next handler that records whether the
+// http.ResponseWriter it was handed is (or, transitively, still wraps) a
+// *trackingWriter, so a test can assert the downstream writer is the real
+// one Traefik would give a compiled ReverseProxy -- not the interpreted
+// wrapper.
+func nextWriterSpy(called *bool, sawTrackingWriter *bool) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		*called = true
+		if _, ok := w.(*trackingWriter); ok {
+			*sawTrackingWriter = true
+		}
+		w.WriteHeader(http.StatusOK)
+	})
+}
+
+// authenticatedRequestWithCookie builds a request carrying a saved,
+// authenticated session cookie for user, so the SSE/WebSocket bypass's
+// cookie-only auth check (applyBypassUserHeaders) admits it.
+func authenticatedRequestWithCookie(t *testing.T, sm *SessionManager, user string) *http.Request {
+	t.Helper()
+	setupReq := httptest.NewRequest(http.MethodGet, "https://app.example.com/stream", nil)
+	session, err := sm.GetSession(setupReq)
+	if err != nil {
+		t.Fatalf("GetSession: %v", err)
+	}
+	session.SetAuthenticated(true)
+	session.SetUserIdentifier(user)
+	rr := httptest.NewRecorder()
+	if err := session.Save(setupReq, rr); err != nil {
+		t.Fatalf("Save: %v", err)
+	}
+	session.returnToPoolSafely()
+
+	req := httptest.NewRequest(http.MethodGet, "https://app.example.com/stream", nil)
+	for _, c := range rr.Result().Cookies() {
+		req.AddCookie(c)
+	}
+	return req
+}
+
+// TestServeHTTP_SSEBypass_NextReceivesUnwrappedWriter pins FIX-06 on the
+// SSE bypass path.
+func TestServeHTTP_SSEBypass_NextReceivesUnwrappedWriter(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	var called, sawTrackingWriter bool
+	initComplete := make(chan struct{})
+	close(initComplete)
+	tObj := &TraefikOidc{
+		logger:         GetSingletonNoOpLogger(),
+		name:           "test",
+		next:           nextWriterSpy(&called, &sawTrackingWriter),
+		sessionManager: sm,
+		initComplete:   initComplete,
+	}
+
+	req := authenticatedRequestWithCookie(t, sm, "[email protected]")
+	req.Header.Set("Accept", "text/event-stream")
+	rw := httptest.NewRecorder()
+
+	tObj.ServeHTTP(rw, req)
+
+	if !called {
+		t.Fatalf("next handler was not invoked (status=%d body=%q); the authenticated SSE bypass must forward", rw.Code, rw.Body.String())
+	}
+	if sawTrackingWriter {
+		t.Fatal("next handler received the interpreted trackingWriter on the SSE bypass path, not the original ResponseWriter")
+	}
+}
+
+// TestServeHTTP_WebSocketBypass_NextReceivesUnwrappedWriter pins FIX-06 on
+// the WebSocket upgrade bypass path.
+func TestServeHTTP_WebSocketBypass_NextReceivesUnwrappedWriter(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	var called, sawTrackingWriter bool
+	initComplete := make(chan struct{})
+	close(initComplete)
+	tObj := &TraefikOidc{
+		logger:         GetSingletonNoOpLogger(),
+		name:           "test",
+		next:           nextWriterSpy(&called, &sawTrackingWriter),
+		sessionManager: sm,
+		initComplete:   initComplete,
+	}
+
+	req := authenticatedRequestWithCookie(t, sm, "[email protected]")
+	req.Header.Set("Upgrade", "websocket")
+	req.Header.Set("Connection", "Upgrade")
+	rw := httptest.NewRecorder()
+
+	tObj.ServeHTTP(rw, req)
+
+	if !called {
+		t.Fatalf("next handler was not invoked (status=%d body=%q); the authenticated WebSocket bypass must forward", rw.Code, rw.Body.String())
+	}
+	if sawTrackingWriter {
+		t.Fatal("next handler received the interpreted trackingWriter on the WebSocket bypass path, not the original ResponseWriter")
+	}
+}
+
+// TestForwardAuthorized_NextReceivesUnwrappedWriter pins FIX-06 on the
+// authenticated forwarding path (forwardAuthorized is ServeHTTP's and
+// bearer_auth.go's shared tail call to t.next.ServeHTTP). ServeHTTP always
+// calls forwardAuthorized with rw already wrapped in *trackingWriter (see
+// middleware.go:309); reproduce that shape directly here.
+func TestForwardAuthorized_NextReceivesUnwrappedWriter(t *testing.T) {
+	var called, sawTrackingWriter bool
+	oidc := &TraefikOidc{
+		logger: GetSingletonNoOpLogger(),
+		next:   nextWriterSpy(&called, &sawTrackingWriter),
+	}
+
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	rec := httptest.NewRecorder()
+	tw := &trackingWriter{ResponseWriter: rec}
+	p := &principal{Identifier: "[email protected]"}
+
+	oidc.forwardAuthorized(tw, req, p)
+
+	if !called {
+		t.Fatal("next handler was not invoked")
+	}
+	if sawTrackingWriter {
+		t.Fatal("next handler received the interpreted trackingWriter on the authenticated path, not the original ResponseWriter")
+	}
+}

fix10_session_pool_aba_test.go

@@ -0,0 +1,124 @@
+package traefikoidc
+
+// Regression test for FIX-10 (review-2026-09-10 finding at session.go:1784,
+// middleware.go:566/789/883): a request-scoped deferred pool-return has no
+// way to tell a stale holder from the current owner (ABA on the pool-return
+// CAS). ServeHTTP acquires a session and defers its return; deep in the call
+// chain, session.Clear() returns the SAME object to the pool and the
+// handler re-acquires it under a fresh GetSession/newSession call. If a
+// concurrent request pops that pooled object before the ORIGINAL deferred
+// return fires, the stale return's CompareAndSwap(true, false) still
+// succeeds against the new owner, incorrectly releasing (and Reset()ting) a
+// session another request is actively using.
+//
+// Adapted from the throwaway repro at
+// .claude/review-2026-09-10/repro/zz_g1_aba_test.go (TestG1StaleDeferABA),
+// renamed to describe the behavior it pins and rewritten against the
+// generation-gated return the fix introduces (ownerGeneration /
+// returnToPoolIfOwner) instead of the raw returnToPoolSafely the bug lived
+// in -- a caller must adopt the new API for the fix to apply, so the test
+// exercises the same call the fixed middleware.go ServeHTTP now makes.
+//
+// The ABA reuse step (does the pool hand the SAME object back to a second
+// GetSession after Clear) is itself an unspecified sync.Pool implementation
+// detail, not part of the contract this fix establishes. Rather than depend
+// on that timing (flaky: it did not reproduce on every run), this test
+// drives the two field mutations GetSession/newSession make on every real
+// handout -- inUse.Store(true) then generation.Add(1) -- directly on the
+// SAME object Clear() just returned, deterministically recreating "a new
+// owner acquired this exact object" regardless of pool internals.
+
+import (
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestSessionPoolReturn_StaleGenerationDoesNotReleaseNewOwner reproduces the
+// ABA sequence: request A acquires session O and captures its ownership
+// generation (mirrors ServeHTTP's defer registration at middleware.go:566).
+// O is cleared and returned to the pool (mirrors session.Clear at
+// middleware.go:774/868); a new owner then claims the SAME object the way
+// GetSession/newSession do (mirrors the re-acquire at
+// middleware.go:781/875) and starts using it. A's stale deferred return
+// then fires (mirrors ServeHTTP's defer running at function exit) and must
+// be a no-op against the new owner's live ownership.
+func TestSessionPoolReturn_StaleGenerationDoesNotReleaseNewOwner(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	r1 := httptest.NewRequest("GET", "https://app.example.com/", nil)
+	o, err := sm.GetSession(r1)
+	if err != nil {
+		t.Fatalf("GetSession (request A): %v", err)
+	}
+	// ServeHTTP captures the generation right after acquiring, then defers
+	// a generation-gated return instead of an unconditional one.
+	staleGen := o.ownerGeneration()
+
+	if err := o.Clear(r1, httptest.NewRecorder()); err != nil {
+		t.Fatalf("Clear: %v", err)
+	}
+	if o.inUse.Load() {
+		t.Fatalf("Clear must return the object to the pool (inUse still true)")
+	}
+
+	// A new owner claims the exact same object: this is the sequence
+	// GetSession/newSession run on every real handout -- generation,
+	// sessionOwner, then inUse (session.go:1076-1078, 1108-1110) --
+	// reproduced directly so the test does not depend on sync.Pool's
+	// unspecified reuse timing. sessionOwner must be set to the new
+	// generation, not left at 0: a stale returnToPoolIfOwner call gates on
+	// sessionOwner, so leaving it 0 would make the object look already-free
+	// rather than owned by someone else, which is what this test needs to
+	// tell apart.
+	o.sessionOwner.Store(o.generation.Add(1))
+	o.inUse.Store(true)
+	o.SetUserIdentifier("bob")
+
+	if staleGen == o.ownerGeneration() {
+		t.Fatalf("test setup bug: new owner's generation (%d) must differ from the captured stale generation (%d)", o.ownerGeneration(), staleGen)
+	}
+
+	// A's stale deferred return fires at ServeHTTP exit, after the new
+	// owner has already claimed and started using the same object.
+	o.returnToPoolIfOwner(staleGen)
+
+	if !o.inUse.Load() {
+		t.Fatalf("stale deferred return (captured generation %d) released a session owned by another holder (current generation %d)", staleGen, o.ownerGeneration())
+	}
+	if o.GetUserIdentifier() != "bob" {
+		t.Fatalf("stale deferred return corrupted the new owner's session data: got user %q, want \"bob\"", o.GetUserIdentifier())
+	}
+
+	o.returnToPoolSafely()
+}
+
+// TestSessionPoolReturn_CurrentGenerationStillReturns is the control: a
+// non-stale generation-gated return (the common case -- no Clear+reacquire
+// happened) must still return the object to the pool, so the fix does not
+// leak sessions on the ordinary path.
+func TestSessionPoolReturn_CurrentGenerationStillReturns(t *testing.T) {
+	sm, err := NewSessionManager(strings.Repeat("k", 32), false, "", "", time.Hour, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager: %v", err)
+	}
+	defer sm.Shutdown()
+
+	r := httptest.NewRequest("GET", "https://app.example.com/", nil)
+	s, err := sm.GetSession(r)
+	if err != nil {
+		t.Fatalf("GetSession: %v", err)
+	}
+	gen := s.ownerGeneration()
+
+	s.returnToPoolIfOwner(gen)
+
+	if s.inUse.Load() {
+		t.Fatalf("returnToPoolIfOwner with the current generation must return the object to the pool (inUse still true)")
+	}
+}

fix18_gd_lifecycle_test.go

@@ -0,0 +1,255 @@
+package traefikoidc
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// FIX-18: main.go wires up TWO GracefulDegradation instances per plugin
+// instance — one directly via NewErrorRecoveryManager (t.errorRecoveryManager)
+// and one nested inside NewTokenResilienceManager's own ErrorRecoveryManager
+// (t.tokenResilienceManager). Production Close() only ever closed the first
+// one (t.errorRecoveryManager.gracefulDegradation.Close()), so the second gd
+// leaked forever in the package-level gdInstances registry and the shared
+// "graceful-degradation-health-check" task's last-instance stop gate
+// (len(gdInstances.set)==0) never fired.
+//
+// gdInstancesLen (below) reads the size of the package-level gdInstances set.
+// The test asserts on the DELTA around creating and closing both managers, so
+// it stays correct regardless of what other tests in this package leave
+// registered.
+func TestFix18_ClosingBothManagersEmptiesGDInstances(t *testing.T) {
+	logger := GetSingletonNoOpLogger()
+
+	before := gdInstancesLen()
+
+	erm := NewErrorRecoveryManager(logger)
+	trm := NewTokenResilienceManager(DefaultTokenResilienceConfig(), logger)
+
+	afterNew := gdInstancesLen()
+	if afterNew != before+2 {
+		t.Fatalf("precondition: wiring one plugin instance must create exactly 2 GracefulDegradation instances (one direct, one nested in TokenResilienceManager); got delta %d", afterNew-before)
+	}
+
+	// Let each instance's async health-check goroutine (started by
+	// NewGracefulDegradation) settle — either it assigns the shared task, or
+	// it observes an already-closed instance and bails — before closing.
+	// This makes the Close() calls below exercise the real "task already
+	// assigned, stop it by name" path deterministically on every run instead
+	// of sometimes racing the goroutine (FIX-18 review, item 4).
+	waitForHealthRoutineSettled(t, erm.gracefulDegradation)
+	waitForHealthRoutineSettled(t, trm.errorRecoveryManager.gracefulDegradation)
+
+	// Close every gd this wiring created. Before FIX-18, only erm's gd had a
+	// Close path reachable from TraefikOidc.Close (via
+	// t.errorRecoveryManager.gracefulDegradation.Close()); trm's own gd had
+	// no Close method to call at all.
+	erm.Close()
+	trm.Close()
+
+	afterClose := gdInstancesLen()
+	if afterClose != before {
+		t.Fatalf("gdInstances leaked %d entries after closing every gd this wiring created (afterClose delta=%d, want 0) — TokenResilienceManager's own GracefulDegradation was never closed", afterClose-before, afterClose-before)
+	}
+
+	// Only assert the shared health-check task itself stopped when this test
+	// is known to be the sole registrant (before==0): the task is a
+	// process-global singleton shared by every GracefulDegradation created
+	// anywhere in the suite, so this assertion would be flaky under a
+	// nonzero baseline left by another test.
+	if before == 0 && GetResourceManager().IsTaskRunning("graceful-degradation-health-check") {
+		t.Fatal("graceful-degradation-health-check task must stop once gdInstances is empty (last-instance stop gate)")
+	}
+}
+
+// TestFix18_TraefikOidcCloseEmptiesGDInstances pins the FIX-18 major-finding
+// gap left by the test above: calling erm.Close()/trm.Close() directly stays
+// green even if the real (*TraefikOidc).Close() is reverted to skip one of
+// them (utilities.go's t.errorRecoveryManager.Close() /
+// t.tokenResilienceManager.Close() calls). This test wires both managers on
+// a TraefikOidc exactly as NewWithContext does (main.go's
+// t.errorRecoveryManager = NewErrorRecoveryManager(...) followed by
+// t.tokenResilienceManager = NewTokenResilienceManager(...)) and drives the
+// real Close(), so it only passes when Close() actually reaches both.
+func TestFix18_TraefikOidcCloseEmptiesGDInstances(t *testing.T) {
+	logger := GetSingletonNoOpLogger()
+	before := gdInstancesLen()
+
+	oidc := &TraefikOidc{logger: logger}
+	oidc.errorRecoveryManager = NewErrorRecoveryManager(logger)
+	oidc.tokenResilienceManager = NewTokenResilienceManager(DefaultTokenResilienceConfig(), logger)
+
+	afterNew := gdInstancesLen()
+	if afterNew != before+2 {
+		t.Fatalf("precondition: wiring one plugin instance must create exactly 2 GracefulDegradation instances; got delta %d", afterNew-before)
+	}
+
+	waitForHealthRoutineSettled(t, oidc.errorRecoveryManager.gracefulDegradation)
+	waitForHealthRoutineSettled(t, oidc.tokenResilienceManager.errorRecoveryManager.gracefulDegradation)
+
+	// Keep a sentinel instance alive across Close() so this test's Close()
+	// call is never the last live instance: this test only asserts on
+	// gdInstances, but Close()'s "am I last" decision (stopIfLastInstance)
+	// also stops process-global singleton tasks — singleton-token-cleanup
+	// and, via GetGlobalTaskRegistry().StopAllTasks(), every other
+	// registered singleton (e.g. memory-monitor) — that this test does not
+	// own and must not stop out from under the rest of the suite.
+	registerLiveInstance()
+	t.Cleanup(func() { unregisterLiveInstance() })
+
+	// Balance Close()'s own unregisterLiveInstance() call: New() always
+	// registers before it returns an instance for Close() to eventually
+	// unregister, and this test's synthetic instance must too, or it skews
+	// the process-global liveInstanceCount permanently negative for every
+	// other test that runs afterward in the same binary (FIX-35 territory,
+	// but liveInstanceCount is shared package state regardless of which
+	// finding a given test targets).
+	registerLiveInstance()
+
+	if err := oidc.Close(); err != nil {
+		t.Fatalf("Close returned an error: %v", err)
+	}
+
+	after := gdInstancesLen()
+	if after != before {
+		t.Fatalf("gdInstances leaked %d entries after TraefikOidc.Close (delta=%d, want 0) — Close must close both t.errorRecoveryManager and t.tokenResilienceManager", after-before, after-before)
+	}
+}
+
+// TestFix18_CloseImmediatelyAfterNewDoesNotReRegister pins the exact race the
+// FIX-18 review's scratch probe found: NewGracefulDegradation followed
+// immediately by Close(), before the async health-check goroutine has had a
+// chance to run. The old startHealthCheckRoutine re-added gd to gdInstances
+// from inside that goroutine (after Close had already deleted it), permanently
+// re-registering an already-closed instance and restarting the shared
+// health-check task for it with nothing left able to ever stop it again.
+func TestFix18_CloseImmediatelyAfterNewDoesNotReRegister(t *testing.T) {
+	t.Cleanup(snapshotAndClearGdInstancesForTest())
+
+	cfg := DefaultGracefulDegradationConfig()
+	gd := NewGracefulDegradation(cfg, GetSingletonNoOpLogger())
+	gd.Close()
+
+	// Give the async health-check goroutine every opportunity to run and,
+	// under the bug, re-register the closed instance.
+	deadline := time.Now().Add(200 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		gdInstances.RLock()
+		n := len(gdInstances.set)
+		gdInstances.RUnlock()
+		if n != 0 {
+			t.Fatalf("closed instance was re-registered: gdInstances has %d entries, want 0", n)
+		}
+		time.Sleep(time.Millisecond)
+	}
+}
+
+// TestFix18_NewWithContextClosesManagersOnEarlyError pins the FIX-18 minor
+// finding: NewWithContext creates t.errorRecoveryManager and
+// t.tokenResilienceManager, then returns an error from a later validation
+// step (here, an invalid private_key_jwt key) without ever closing either
+// one — leaking their GracefulDegradation instances in gdInstances forever.
+func TestFix18_NewWithContextClosesManagersOnEarlyError(t *testing.T) {
+	before := gdInstancesLen()
+
+	cfg := &Config{
+		ProviderURL:               "https://accounts.google.com",
+		ClientID:                  "test-client",
+		ClientSecret:              "test-secret",
+		CallbackURL:               "/callback",
+		SessionEncryptionKey:      "this-is-a-valid-session-key-32b!",
+		RateLimit:                 100,
+		ClientAuthMethod:          "private_key_jwt",
+		ClientAssertionKeyID:      "test-kid",
+		ClientAssertionPrivateKey: "-----BEGIN PRIVATE KEY-----\nnot-valid-base64-content!!!\n-----END PRIVATE KEY-----\n",
+	}
+
+	plugin, err := NewWithContext(context.Background(), cfg, nil, "fix18-bad-key")
+	if err == nil {
+		if plugin != nil {
+			plugin.Close()
+		}
+		t.Fatal("expected NewWithContext to fail on an invalid private_key_jwt key")
+	}
+	if plugin != nil {
+		t.Fatal("NewWithContext must return a nil instance on error")
+	}
+
+	after := gdInstancesLen()
+	if after != before {
+		t.Fatalf("NewWithContext's error path leaked %d GracefulDegradation instance(s) in gdInstances (before=%d after=%d) — the errorRecoveryManager and tokenResilienceManager created just before the failure were never closed", after-before, before, after)
+	}
+}
+
+// healthRoutineSettled reports whether startHealthCheckRoutine has finished
+// making its one-time decision for this instance: either it assigned a
+// health-check task, or it observed stopChan already closed and returned
+// without assigning one (in which case it never will, since it runs at most
+// once). Tests use this to wait for the async goroutine NewGracefulDegradation
+// starts to settle before asserting on shared state, instead of depending on
+// goroutine-scheduling timing.
+//
+// Test-only: moved out of error_recovery.go (production code) because its
+// only caller is waitForHealthRoutineSettled below, following the pattern
+// FIX-39 established for resetGlobalTransportPoolForTest
+// (internal/pool/export_test.go) — a test-only helper has no business being
+// compiled into the production binary.
+func (gd *GracefulDegradation) healthRoutineSettled() bool {
+	gd.mutex.RLock()
+	defer gd.mutex.RUnlock()
+
+	if gd.healthCheckTask != nil {
+		return true
+	}
+
+	select {
+	case <-gd.stopChan:
+		return true
+	default:
+		return false
+	}
+}
+
+// waitForHealthRoutineSettled polls until gd's async startHealthCheckRoutine
+// goroutine has settled (see GracefulDegradation.healthRoutineSettled).
+func waitForHealthRoutineSettled(t *testing.T, gd *GracefulDegradation) {
+	t.Helper()
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if gd.healthRoutineSettled() {
+			return
+		}
+		time.Sleep(2 * time.Millisecond)
+	}
+	t.Fatal("health-check goroutine did not settle (task assigned or instance already closed) in time")
+}
+
+// gdInstancesLen reads the current size of the package-level gdInstances set
+// under its own lock.
+func gdInstancesLen() int {
+	gdInstances.RLock()
+	defer gdInstances.RUnlock()
+	return len(gdInstances.set)
+}
+
+// snapshotAndClearGdInstancesForTest captures the current contents of the
+// package-level gdInstances registry and replaces it with a fresh empty set,
+// mirroring resetGdInstancesForTest (review_r34_regression_test.go). Unlike
+// that helper, it returns a restore func the caller registers with
+// t.Cleanup: a bare reset with no restore permanently discards whatever
+// GracefulDegradation instances other tests in the same binary had
+// registered before this test ran, instead of only clearing for the
+// duration of this test.
+func snapshotAndClearGdInstancesForTest() func() {
+	gdInstances.Lock()
+	saved := gdInstances.set
+	gdInstances.set = make(map[*GracefulDegradation]struct{})
+	gdInstances.Unlock()
+
+	return func() {
+		gdInstances.Lock()
+		gdInstances.set = saved
+		gdInstances.Unlock()
+	}
+}

fix19_singleton_task_orphan_test.go

@@ -0,0 +1,114 @@
+package traefikoidc
+
+import (
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// FIX-19: RegisterBackgroundTask replaced a registered-but-not-yet-started
+// task (started==0, stopped==0) unconditionally. CreateSingletonTask runs
+// Register -> IsTaskRunning -> StartBackgroundTask without holding tasksMu
+// across the three calls (autocleanup.go:612-632), so a second concurrent
+// caller can land in RegisterBackgroundTask in the window before the first
+// caller's own Start() call runs.
+//
+// This test reproduces that exact interleaving deterministically, without
+// real goroutines, by issuing the calls in the documented race order:
+//
+//  1. Caller A registers the task (T1).
+//  2. Caller A reads its handle from the registry (mirrors
+//     CreateSingletonTask's internal StartBackgroundTask lookup) but has not
+//     called Start() on it yet.
+//  3. Caller B registers the SAME name before A calls Start() — at head this
+//     replaces the map entry with a fresh task (T2).
+//  4. Caller A calls Start() on the handle it read in step 2.
+//  5. Caller B starts whatever is now registered under the name.
+//
+// At head this starts two independent tickers (T1 wrapping count1, T2
+// wrapping count2). Only the object actually stored in the registry (T2) is
+// reachable from StopAllTasks, so T1 becomes an orphan that keeps running
+// forever past Close/StopAllTasks. After the fix, step 3's register call
+// keeps the existing (still-pending) T1 instead of replacing it, so there is
+// only ever one task, and count2 (which would wrap a second, orphaned task)
+// never starts at all.
+func TestFix19_RegisterBackgroundTaskKeepsPendingTaskNoOrphan(t *testing.T) {
+	rm := GetResourceManager()
+	name := "fix19-" + t.Name()
+
+	var count1, count2 int32
+
+	// Step 1: caller A registers T1.
+	if err := rm.RegisterBackgroundTask(name, 5*time.Millisecond, func() {
+		atomic.AddInt32(&count1, 1)
+	}); err != nil {
+		t.Fatalf("first RegisterBackgroundTask: %v", err)
+	}
+
+	// Step 2: caller A reads its handle, but has not started it yet.
+	rm.tasksMu.RLock()
+	aTask := rm.tasks[name]
+	rm.tasksMu.RUnlock()
+	if aTask == nil {
+		t.Fatal("task not present in registry after first RegisterBackgroundTask")
+	}
+
+	// Step 3: caller B registers the same name before A calls Start().
+	if err := rm.RegisterBackgroundTask(name, 5*time.Millisecond, func() {
+		atomic.AddInt32(&count2, 1)
+	}); err != nil {
+		t.Fatalf("second RegisterBackgroundTask: %v", err)
+	}
+
+	// Step 4: caller A starts the handle it read in step 2.
+	aTask.Start()
+
+	// Step 5: caller B starts whatever is now registered under the name.
+	if err := rm.StartBackgroundTask(name); err != nil {
+		t.Fatalf("StartBackgroundTask: %v", err)
+	}
+
+	// Let both tickers (or, after the fix, the single ticker) tick a few
+	// times before stopping.
+	time.Sleep(60 * time.Millisecond)
+
+	// Stop only the named task this test created, not rm.StopAllTasks(): the
+	// ResourceManager is a process-global singleton, and StopAllTasks stops
+	// every task registered on it, including unrelated singletons (e.g.
+	// memory-monitor, singleton-token-cleanup) that other tests in the same
+	// binary may have started and still expect running.
+	if err := rm.StopBackgroundTask(name); err != nil {
+		t.Fatalf("StopBackgroundTask(%q): %v", name, err)
+	}
+
+	// Snapshot count1 right after the stop, then again after another window
+	// long enough for several more ticks. A well-stopped task's counter must
+	// not move between the two snapshots.
+	afterStop1 := atomic.LoadInt32(&count1)
+	time.Sleep(60 * time.Millisecond)
+	final1 := atomic.LoadInt32(&count1)
+
+	if final1 != afterStop1 {
+		t.Fatalf("task wrapping count1 kept running after StopBackgroundTask (orphan escaped registry): %d -> %d", afterStop1, final1)
+	}
+	if afterStop1 == 0 {
+		t.Fatal("precondition: task wrapping count1 never ran at all")
+	}
+
+	// count2 must never have run: after the fix, the second
+	// RegisterBackgroundTask call keeps the existing pending task instead of
+	// constructing and starting a second one.
+	if got := atomic.LoadInt32(&count2); got != 0 {
+		t.Fatalf("second RegisterBackgroundTask call must not create and start a second task while the first is still pending; count2=%d", got)
+	}
+
+	// Cleanup: make sure the task this test created cannot keep running past
+	// the test even if an assertion above already failed it.
+	aTask.Stop()
+	rm.tasksMu.RLock()
+	bTask := rm.tasks[name]
+	rm.tasksMu.RUnlock()
+	if bTask != nil {
+		bTask.Stop()
+	}
+}

fix26_scheme_downgrade_test.go

@@ -0,0 +1,294 @@
+package traefikoidc
+
+import (
+	"bytes"
+	"io"
+	"log"
+	"strings"
+	"testing"
+)
+
+// fix26CapturingLogger builds a *Logger whose Errorf output lands in buf
+// while Info/Debug are discarded, so a test can assert on exactly what
+// reaches the error stream without touching the process-wide os.Stderr.
+func fix26CapturingLogger(buf *bytes.Buffer) *Logger {
+	return &Logger{
+		logError: log.New(buf, "", 0),
+		logInfo:  log.New(io.Discard, "", 0),
+		logDebug: log.New(io.Discard, "", 0),
+	}
+}
+
+// TestUpdateMetadataEndpoints_HTTPTokenEndpointUnderHTTPSProviderFailsLoudly
+// pins FIX-26. validateDiscoveredEndpoint already drops (R146) a discovered
+// http endpoint when providerURL is https, and the pre-existing "Ignoring
+// discovered ..." ERROR line already names the endpoint, the URL, and the
+// scheme-downgrade reason (it wraps ErrDiscoveredEndpointSchemeDowngrade).
+// What was missing was a way to tell that rejection apart, at a glance, from
+// every other validation rejection (SSRF block, malformed URL, path
+// traversal, ...) for the three endpoints login cannot function without. The
+// fix adds one additional, distinctly-tagged SECURITY line — naming the
+// endpoint and stating there is no config override — for exactly those
+// three (jwks_uri, authorization, token); the other four discovered
+// endpoints (revocation, end_session, introspection, registration) keep
+// only the generic line, since three of them (revocationURL,
+// oidcEndSessionURL, introspectionURL) have an operator override that
+// replaces them right after sanitize runs.
+func TestUpdateMetadataEndpoints_HTTPTokenEndpointUnderHTTPSProviderFailsLoudly(t *testing.T) {
+	var buf bytes.Buffer
+	tObj := &TraefikOidc{
+		logger:      fix26CapturingLogger(&buf),
+		providerURL: "https://provider.example.com",
+	}
+
+	tObj.updateMetadataEndpoints(&ProviderMetadata{
+		TokenURL: "http://provider.example.com/token",
+	})
+
+	if tObj.tokenURL != "" {
+		t.Fatalf("an http token endpoint under an https provider must still be dropped, got %q", tObj.tokenURL)
+	}
+
+	logged := buf.String()
+	if !strings.Contains(logged, "SECURITY:") {
+		t.Fatalf("dropping an endpoint for the https-pin reason must log a SECURITY-tagged line, got:\n%s", logged)
+	}
+	if !strings.Contains(logged, "token") {
+		t.Fatalf("the SECURITY line must name the dropped endpoint (token), got:\n%s", logged)
+	}
+	if !strings.Contains(logged, "http://provider.example.com/token") {
+		t.Fatalf("the SECURITY line must name the dropped URL, got:\n%s", logged)
+	}
+	if !strings.Contains(logged, "no override") {
+		t.Fatalf("the SECURITY line must state that this check has no override, got:\n%s", logged)
+	}
+}
+
+// TestUpdateMetadataEndpoints_AllHTTPSCriticalEndpointsNoSecurityLog is the
+// negative case: well-formed https endpoints (jwks_uri, authorization,
+// token) must not trip the new SECURITY line.
+func TestUpdateMetadataEndpoints_AllHTTPSCriticalEndpointsNoSecurityLog(t *testing.T) {
+	var buf bytes.Buffer
+	tObj := &TraefikOidc{
+		logger:      fix26CapturingLogger(&buf),
+		providerURL: "https://provider.example.com",
+	}
+
+	tObj.updateMetadataEndpoints(&ProviderMetadata{
+		JWKSURL:  "https://provider.example.com/jwks",
+		AuthURL:  "https://provider.example.com/auth",
+		TokenURL: "https://provider.example.com/token",
+	})
+
+	if tObj.tokenURL != "https://provider.example.com/token" {
+		t.Fatalf("an https token endpoint must be accepted, got %q", tObj.tokenURL)
+	}
+	if strings.Contains(buf.String(), "SECURITY:") {
+		t.Fatalf("accepted https endpoints must not log a SECURITY line, got:\n%s", buf.String())
+	}
+}
+
+// TestUpdateMetadataEndpoints_HTTPJWKSAndAuthEndpointsFailLoudly extends the
+// pin to the other two endpoints login cannot function without: jwks_uri
+// (signature verification) and authorization (the redirect target). Each
+// must independently trigger its own named SECURITY line.
+func TestUpdateMetadataEndpoints_HTTPJWKSAndAuthEndpointsFailLoudly(t *testing.T) {
+	for _, tc := range []struct {
+		field    string
+		endpoint string
+	}{
+		{field: "jwks_uri", endpoint: "http://provider.example.com/jwks"},
+		{field: "authorization", endpoint: "http://provider.example.com/auth"},
+	} {
+		t.Run(tc.field, func(t *testing.T) {
+			var buf bytes.Buffer
+			tObj := &TraefikOidc{
+				logger:      fix26CapturingLogger(&buf),
+				providerURL: "https://provider.example.com",
+			}
+			md := &ProviderMetadata{}
+			switch tc.field {
+			case "jwks_uri":
+				md.JWKSURL = tc.endpoint
+			case "authorization":
+				md.AuthURL = tc.endpoint
+			}
+			tObj.updateMetadataEndpoints(md)
+
+			logged := buf.String()
+			if !strings.Contains(logged, "SECURITY:") {
+				t.Fatalf("%s: dropping the endpoint must log a SECURITY-tagged line, got:\n%s", tc.field, logged)
+			}
+			if !strings.Contains(logged, tc.field) {
+				t.Fatalf("%s: the SECURITY line must name the endpoint, got:\n%s", tc.field, logged)
+			}
+		})
+	}
+}
+
+// TestUpdateMetadataEndpoints_RegistrationNeverLogsSecurityLine pins that
+// the registration endpoint never trips the SECURITY-tagged line. It is the
+// one discovered endpoint of the four (end_session, revocation,
+// introspection, registration) with no config*URL field checked inside
+// updateMetadataEndpoints at all: RegisterClient reads dcrConfig.
+// RegistrationEndpoint directly (main.go, outside this function) whenever
+// it is set, so a dropped discovered value here is orthogonal to whether
+// that separate override exists.
+func TestUpdateMetadataEndpoints_RegistrationNeverLogsSecurityLine(t *testing.T) {
+	var buf bytes.Buffer
+	tObj := &TraefikOidc{
+		logger:      fix26CapturingLogger(&buf),
+		providerURL: "https://provider.example.com",
+	}
+
+	tObj.updateMetadataEndpoints(&ProviderMetadata{
+		RegistrationURL: "http://provider.example.com/register",
+	})
+
+	logged := buf.String()
+	if !strings.Contains(logged, "Ignoring discovered registration") {
+		t.Fatalf("registration must still be dropped with the generic line, got:\n%s", logged)
+	}
+	if strings.Contains(logged, "SECURITY:") {
+		t.Fatalf("registration must never log a SECURITY line, got:\n%s", logged)
+	}
+}
+
+// TestUpdateMetadataEndpoints_NonCriticalEndpointsWithoutOverrideLogSecurityLine
+// pins the re-review fix at main.go:658 (low severity): a scheme-downgrade
+// drop of end_session, revocation or introspection is exactly as terminal
+// as a drop of jwks_uri/authorization/token WHEN the operator has not set
+// the matching override (oidcEndSessionURL / revocationURL /
+// introspectionURL) -- logout falls back to a local-only redirect, provider
+// revocation is skipped, or requireTokenIntrospection breaks, all silently
+// except for the generic "Ignoring discovered" line. The old
+// discoveredEndpointHasNoOverride was static and always answered false for
+// these three regardless of whether an override was actually configured, so
+// the SECURITY line never fired for them even with no override at all. It
+// must now fire exactly when the corresponding override is empty.
+func TestUpdateMetadataEndpoints_NonCriticalEndpointsWithoutOverrideLogSecurityLine(t *testing.T) {
+	for _, tc := range []struct {
+		field    string
+		endpoint string
+	}{
+		{field: "end_session", endpoint: "http://provider.example.com/logout"},
+		{field: "revocation", endpoint: "http://provider.example.com/revoke"},
+		{field: "introspection", endpoint: "http://provider.example.com/introspect"},
+	} {
+		t.Run(tc.field, func(t *testing.T) {
+			var buf bytes.Buffer
+			// Deliberately no configEndSessionURL/configRevocationURL/
+			// configIntrospectionURL set: the operator configured no
+			// override for any of these three.
+			tObj := &TraefikOidc{
+				logger:      fix26CapturingLogger(&buf),
+				providerURL: "https://provider.example.com",
+			}
+			md := &ProviderMetadata{}
+			switch tc.field {
+			case "end_session":
+				md.EndSessionURL = tc.endpoint
+			case "revocation":
+				md.RevokeURL = tc.endpoint
+			case "introspection":
+				md.IntrospectionURL = tc.endpoint
+			}
+			tObj.updateMetadataEndpoints(md)
+
+			logged := buf.String()
+			if !strings.Contains(logged, "Ignoring discovered "+tc.field) {
+				t.Fatalf("%s: the endpoint must still be dropped with the generic line, got:\n%s", tc.field, logged)
+			}
+			if !strings.Contains(logged, "SECURITY:") {
+				t.Fatalf("%s: dropping it with no configured override must log a SECURITY-tagged line, got:\n%s", tc.field, logged)
+			}
+			if !strings.Contains(logged, "no override") {
+				t.Fatalf("%s: the SECURITY line must state that this check has no override, got:\n%s", tc.field, logged)
+			}
+		})
+	}
+}
+
+// TestUpdateMetadataEndpoints_ConfigOverrideReplacesDroppedEndpoint pins the
+// second half of the same finding, table-driven over all three endpoints
+// that carry an override: setting the operator override for an endpoint
+// discovery drops for the scheme-downgrade reason means the endpoint does
+// not stay empty — the override runs right after sanitize and replaces it,
+// so a "requests needing this endpoint will fail" style claim would be
+// false for these three. Only end_session was pinned before; a regression
+// that stopped applying configRevocationURL or configIntrospectionURL
+// specifically would have left every test green (re-review finding at
+// fix26_scheme_downgrade_test.go:218).
+func TestUpdateMetadataEndpoints_ConfigOverrideReplacesDroppedEndpoint(t *testing.T) {
+	for _, tc := range []struct {
+		field        string
+		droppedURL   string
+		overrideURL  string
+		buildMD      func(dropped string) *ProviderMetadata
+		buildTObj    func(logger *Logger, override string) *TraefikOidc
+		resultingURL func(tObj *TraefikOidc) string
+	}{
+		{
+			field:       "end_session",
+			droppedURL:  "http://provider.example.com/logout",
+			overrideURL: "https://provider.example.com/logout-override",
+			buildMD: func(dropped string) *ProviderMetadata {
+				return &ProviderMetadata{EndSessionURL: dropped}
+			},
+			buildTObj: func(logger *Logger, override string) *TraefikOidc {
+				return &TraefikOidc{
+					logger:              logger,
+					providerURL:         "https://provider.example.com",
+					configEndSessionURL: override,
+				}
+			},
+			resultingURL: func(tObj *TraefikOidc) string { return tObj.endSessionURL },
+		},
+		{
+			field:       "revocation",
+			droppedURL:  "http://provider.example.com/revoke",
+			overrideURL: "https://provider.example.com/revoke-override",
+			buildMD: func(dropped string) *ProviderMetadata {
+				return &ProviderMetadata{RevokeURL: dropped}
+			},
+			buildTObj: func(logger *Logger, override string) *TraefikOidc {
+				return &TraefikOidc{
+					logger:              logger,
+					providerURL:         "https://provider.example.com",
+					configRevocationURL: override,
+				}
+			},
+			resultingURL: func(tObj *TraefikOidc) string { return tObj.revocationURL },
+		},
+		{
+			field:       "introspection",
+			droppedURL:  "http://provider.example.com/introspect",
+			overrideURL: "https://provider.example.com/introspect-override",
+			buildMD: func(dropped string) *ProviderMetadata {
+				return &ProviderMetadata{IntrospectionURL: dropped}
+			},
+			buildTObj: func(logger *Logger, override string) *TraefikOidc {
+				return &TraefikOidc{
+					logger:                 logger,
+					providerURL:            "https://provider.example.com",
+					configIntrospectionURL: override,
+				}
+			},
+			resultingURL: func(tObj *TraefikOidc) string { return tObj.introspectionURL },
+		},
+	} {
+		t.Run(tc.field, func(t *testing.T) {
+			var buf bytes.Buffer
+			tObj := tc.buildTObj(fix26CapturingLogger(&buf), tc.overrideURL)
+
+			tObj.updateMetadataEndpoints(tc.buildMD(tc.droppedURL))
+
+			if got := tc.resultingURL(tObj); got != tc.overrideURL {
+				t.Fatalf("%s: the configured override must replace the dropped discovered endpoint, got %q, want %q", tc.field, got, tc.overrideURL)
+			}
+			if strings.Contains(buf.String(), "SECURITY:") {
+				t.Fatalf("%s: has a config override, so no SECURITY line applies, got:\n%s", tc.field, buf.String())
+			}
+		})
+	}
+}

fix34_idtoken_header_test.go

@@ -0,0 +1,67 @@
+package traefikoidc
+
+// Regression test for FIX-34 (review-2026-09-10 finding at
+// middleware.go:1169, low severity): forwardAuthorized truncated an
+// oversized ID token to headerTemplateMaxLen (8192) bytes and still
+// forwarded it in X-Auth-Request-Token. A truncated JWT is structurally
+// invalid; a downstream that verifies the signature rejects it (fail
+// closed, fine), but one that merely base64-decodes claims without
+// verifying reads a corrupted, silently-wrong value. The header must be
+// dropped instead, matching the fail-closed pattern already used elsewhere
+// in forwardAuthorized (X-Forwarded-User / X-Auth-Request-User on a failed
+// sanitization).
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// TestForwardAuthorized_OversizedIDTokenDropsHeaderInsteadOfTruncating pins
+// FIX-34: an ID token longer than headerTemplateMaxLen must not appear in
+// X-Auth-Request-Token at all, truncated or otherwise.
+func TestForwardAuthorized_OversizedIDTokenDropsHeaderInsteadOfTruncating(t *testing.T) {
+	oidc := &TraefikOidc{
+		next:   http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}),
+		logger: NewLogger("error"),
+		// minimalHeaders defaults false: the X-Auth-Request-* block (where
+		// X-Auth-Request-Token is set) only runs when it is false.
+	}
+
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	rw := httptest.NewRecorder()
+	oversizedIDToken := strings.Repeat("a", headerTemplateMaxLen+1)
+	p := &principal{
+		Identifier: "user",
+		IDToken:    oversizedIDToken,
+	}
+	oidc.forwardAuthorized(rw, req, p)
+
+	if got := req.Header.Get("X-Auth-Request-Token"); got != "" {
+		t.Fatalf("X-Auth-Request-Token must be dropped (not truncated) for an oversized ID token; got %d bytes, want header absent", len(got))
+	}
+}
+
+// TestForwardAuthorized_IDTokenWithinLimitStillForwarded is the control: an
+// ID token at or under the header budget must still be forwarded
+// unmodified, so the fix does not regress the common case.
+func TestForwardAuthorized_IDTokenWithinLimitStillForwarded(t *testing.T) {
+	oidc := &TraefikOidc{
+		next:   http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}),
+		logger: NewLogger("error"),
+	}
+
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	rw := httptest.NewRecorder()
+	idToken := "header.payload.signature"
+	p := &principal{
+		Identifier: "user",
+		IDToken:    idToken,
+	}
+	oidc.forwardAuthorized(rw, req, p)
+
+	if got := req.Header.Get("X-Auth-Request-Token"); got != idToken {
+		t.Fatalf("X-Auth-Request-Token = %q, want the unmodified ID token %q", got, idToken)
+	}
+}

fix35_lifecycle_race_test.go

@@ -0,0 +1,179 @@
+package traefikoidc
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// FIX-35: Close() decided "am I the last live instance" once, early in its
+// shutdown sequence (unregisterLiveInstance()'s return value), then reused
+// that stale boolean much later to decide whether to stop process-global
+// singleton tasks (memory-monitor, singleton-token-cleanup,
+// singleton-metadata-refresh-*). Session/cache teardown happens in between,
+// taking real time. A concurrently-created new instance (an overlapping
+// Traefik reload) can register and adopt those same singletons in that
+// window; the old instance's stale decision then stops them anyway, and the
+// new instance runs with no memory monitor, token cleanup, or health checks
+// until the next reload.
+//
+// TestFix35_ConcurrentNewKeepsSingletonAliveAcrossOldClose drives the REAL
+// (*TraefikOidc).Close() through this exact window via closeTestHook, rather
+// than re-implementing Close's stop decision inline: a test that never calls
+// Close itself stays green even if the production fix (utilities.go's fresh,
+// lock-guarded re-check; main.go's registerLiveInstance-before-adoption
+// ordering) is reverted, which is a much weaker regression pin.
+//
+// It establishes its own liveInstanceCount baseline (save, zero, restore via
+// t.Cleanup) instead of assuming the package-global counter is already 0.
+// Without that, a live instance left registered by an earlier test in the
+// same run (any order under -shuffle) makes the pre-FIX-35 stale "was last"
+// decision already false on its own, so this test cannot tell a reverted fix
+// from a working one — it passes either way.
+func TestFix35_ConcurrentNewKeepsSingletonAliveAcrossOldClose(t *testing.T) {
+	// Save whether memory-monitor was already running before ResetGlobalMemoryMonitor
+	// below stops it, and restore that state afterward (registered first, so
+	// it runs LAST among this function's cleanups, after ResetGlobalMemoryMonitor
+	// has already torn the singleton down) — otherwise this test permanently
+	// destroys memory-monitor for every other test that runs afterward in the
+	// same binary, regardless of what state it found the process in.
+	wasMemoryMonitorRunning := GetResourceManager().IsTaskRunning("memory-monitor")
+	t.Cleanup(func() {
+		if wasMemoryMonitorRunning {
+			GetGlobalMemoryMonitor().StartMonitoring(context.Background(), time.Second)
+		}
+	})
+
+	ResetGlobalMemoryMonitor()
+	t.Cleanup(ResetGlobalMemoryMonitor)
+	t.Cleanup(func() { closeTestHook = nil })
+
+	baseline := resetLiveInstanceCountForTest()
+	t.Cleanup(func() { restoreLiveInstanceCountForTest(baseline) })
+
+	// --- Old instance: already live, has adopted the memory-monitor singleton
+	// (mirrors main.go's registerLiveInstance() followed by
+	// memoryMonitor.StartMonitoring()).
+	registerLiveInstance()
+	mm := GetGlobalMemoryMonitor()
+	oldCtx, oldCancel := context.WithCancel(context.Background())
+	defer oldCancel()
+	mm.StartMonitoring(oldCtx, time.Second)
+	if !GetResourceManager().IsTaskRunning("memory-monitor") {
+		t.Fatal("precondition: memory-monitor must be running after StartMonitoring")
+	}
+
+	// --- Simulate the concurrent New(): a new instance registers and adopts
+	// the memory-monitor singleton in the window between the old instance's
+	// unregisterLiveInstance() and its gated singleton stops. closeTestHook
+	// fires from inside the real Close(), at exactly that point.
+	newCtx, newCancel := context.WithCancel(context.Background())
+	defer newCancel()
+	closeTestHook = func() {
+		registerLiveInstance()
+		mm.StartMonitoring(newCtx, time.Second) // adopts: already running, so this is a no-op start.
+	}
+	// Undo the hook's registerLiveInstance for the new instance and actually
+	// stop the task so it does not outlive this test. Runs via t.Cleanup
+	// (LIFO, before the baseline restore above) so it still executes even if
+	// an assertion below fails the test early.
+	t.Cleanup(func() {
+		unregisterLiveInstance()
+		_ = GetResourceManager().StopBackgroundTask("memory-monitor")
+	})
+
+	// --- Drive the real Close() on an instance built the same way New()
+	// builds one for this purpose: registered live, nothing else set (every
+	// other field Close touches is nil-guarded).
+	oldInstance := &TraefikOidc{logger: GetSingletonNoOpLogger()}
+	if err := oldInstance.Close(); err != nil {
+		t.Fatalf("Close returned an error: %v", err)
+	}
+
+	if !GetResourceManager().IsTaskRunning("memory-monitor") {
+		t.Fatal("memory-monitor must keep running: a new instance registered and adopted it before Close's last-instance decision")
+	}
+}
+
+// TestFix35_StopIfLastInstanceHoldsLockAcrossCheckAndStop pins the FIX-35
+// review's major finding: a separate fresh-read check only wraps the counter
+// read. Used as `if check() { stop() }`, liveInstanceMu is
+// released as soon as the check returns, before stop() (which can block for
+// real time — BackgroundTask.Stop waits up to 5s per task) ever runs. A
+// concurrent registerLiveInstance() can land in that gap and have its
+// just-adopted singleton killed by a stop decision made before it
+// registered.
+//
+// stopIfLastInstance closes that window by holding liveInstanceMu across
+// both the check and the stop call. This test proves the lock is genuinely
+// held for the stop's full duration: while a slow stop callback is running,
+// a concurrent registerLiveInstance() must not be able to complete.
+func TestFix35_StopIfLastInstanceHoldsLockAcrossCheckAndStop(t *testing.T) {
+	baseline := resetLiveInstanceCountForTest()
+	t.Cleanup(func() { restoreLiveInstanceCountForTest(baseline) })
+
+	stopStarted := make(chan struct{})
+	releaseStop := make(chan struct{})
+	stopDone := make(chan struct{})
+
+	go func() {
+		stopIfLastInstance(func() {
+			close(stopStarted)
+			<-releaseStop // hold the "stop" open, simulating BackgroundTask.Stop's wait.
+		})
+		close(stopDone)
+	}()
+
+	select {
+	case <-stopStarted:
+	case <-time.After(2 * time.Second):
+		t.Fatal("stopIfLastInstance never invoked its stop callback at baseline (count 0)")
+	}
+
+	registerDone := make(chan struct{})
+	go func() {
+		registerLiveInstance()
+		close(registerDone)
+	}()
+
+	select {
+	case <-registerDone:
+		t.Fatal("registerLiveInstance completed while the stop callback was still running — liveInstanceMu was not held across the stop, reopening the check-then-stop window")
+	case <-time.After(100 * time.Millisecond):
+		// Expected: still blocked on liveInstanceMu.
+	}
+
+	close(releaseStop)
+
+	select {
+	case <-registerDone:
+	case <-time.After(2 * time.Second):
+		t.Fatal("registerLiveInstance did not complete after the stop callback released liveInstanceMu")
+	}
+	<-stopDone
+
+	unregisterLiveInstance() // balance the registerLiveInstance above
+}
+
+// resetLiveInstanceCountForTest establishes a clean baseline (0) for the
+// package-level liveInstanceCount so a test's last-instance decisions are not
+// skewed by instances registered-and-never-unregistered by earlier tests in
+// the same process. Test-only; mirrors resetGdInstancesForTest. Returns the
+// value liveInstanceCount held before the reset so the caller can restore it
+// via t.Cleanup (restoreLiveInstanceCountForTest) instead of permanently
+// clobbering a nonzero baseline left by another test in the same run.
+func resetLiveInstanceCountForTest() int32 {
+	liveInstanceMu.Lock()
+	defer liveInstanceMu.Unlock()
+	previous := liveInstanceCount
+	liveInstanceCount = 0
+	return previous
+}
+
+// restoreLiveInstanceCountForTest sets the package-level liveInstanceCount
+// back to a value captured by resetLiveInstanceCountForTest. Test-only.
+func restoreLiveInstanceCountForTest(previous int32) {
+	liveInstanceMu.Lock()
+	defer liveInstanceMu.Unlock()
+	liveInstanceCount = previous
+}

fix42_rsa_key_min_bits_test.go

@@ -0,0 +1,48 @@
+package traefikoidc
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"errors"
+	"strings"
+	"testing"
+)
+
+// TestValidateAlgKeyMatch_RejectsRSAKeyUnder2048Bits pins FIX-42: the
+// RFC 7518 §3.3 minimum key-size rejection that 8640451 added to
+// validateAlgKeyMatch (client_assertion.go:107) for private_key_jwt RS*/PS*
+// signing keys, undocumented in that commit. FIX-25's sibling decision keeps
+// the rejection as-is and records it in CHANGELOG.md; this test pins the
+// contract with a named, matchable sentinel error so the rejection survives
+// refactors and callers can detect it with errors.Is instead of matching a
+// log string.
+func TestValidateAlgKeyMatch_RejectsRSAKeyUnder2048Bits(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 1024)
+	if err != nil {
+		t.Fatalf("failed to generate 1024-bit test RSA key: %v", err)
+	}
+
+	err = validateAlgKeyMatch("RS256", key)
+	if err == nil {
+		t.Fatal("a 1024-bit RSA key must be rejected for RS256, got nil error")
+	}
+	if !errors.Is(err, ErrRSAKeyTooSmall) {
+		t.Fatalf("error must wrap ErrRSAKeyTooSmall so callers can match it with errors.Is, got: %v", err)
+	}
+	const wantSubstring = "requires an RSA key of at least 2048 bits"
+	if !strings.Contains(err.Error(), wantSubstring) {
+		t.Fatalf("error message must state the requirement (%q), got: %v", wantSubstring, err)
+	}
+}
+
+// TestValidateAlgKeyMatch_Accepts2048BitRSAKey is the boundary/positive
+// case: a key at exactly the 2048-bit floor must be accepted.
+func TestValidateAlgKeyMatch_Accepts2048BitRSAKey(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("failed to generate 2048-bit test RSA key: %v", err)
+	}
+	if err := validateAlgKeyMatch("RS256", key); err != nil {
+		t.Fatalf("a 2048-bit RSA key must be accepted for RS256, got: %v", err)
+	}
+}

gd_concurrent_create_during_last_close_test.go

@@ -0,0 +1,83 @@
+package traefikoidc
+
+import (
+	"testing"
+	"time"
+)
+
+// TestSharedHealthTaskSurvivesCreateDuringLastClose pins the create-versus-
+// last-close race on the shared graceful-degradation health-check task.
+//
+// Close() decides it is the last live instance and then stops the shared task.
+// A GracefulDegradation created between that decision and the stop used to
+// register at once, and its health routine adopted the still-running task.
+// The stop then killed the task that the new, live instance relies on, and
+// nothing restarted it.
+//
+// The test pauses the last instance's Close() between the decision and the
+// stop (beforeSharedTaskStop), creates a new instance, and then lets the stop
+// run. The new instance is live, so the shared task must be running at the end.
+func TestSharedHealthTaskSurvivesCreateDuringLastClose(t *testing.T) {
+	t.Cleanup(snapshotAndClearGdInstancesForTest())
+
+	cfg := DefaultGracefulDegradationConfig()
+	cfg.HealthCheckInterval = time.Hour
+	logger := GetSingletonNoOpLogger()
+
+	gdA := NewGracefulDegradation(cfg, logger)
+	waitForHealthRoutineSettled(t, gdA)
+	if !GetResourceManager().IsTaskRunning(gdHealthTaskName) {
+		t.Fatal("precondition: shared health-check task must run while gdA is live")
+	}
+
+	parked := make(chan struct{})
+	release := make(chan struct{})
+	gdA.beforeSharedTaskStop = func() {
+		close(parked)
+		<-release
+	}
+
+	closed := make(chan struct{})
+	go func() {
+		gdA.Close()
+		close(closed)
+	}()
+	select {
+	case <-parked:
+	case <-time.After(5 * time.Second):
+		t.Fatal("gdA.Close did not reach the shared-task stop")
+	}
+
+	created := make(chan *GracefulDegradation, 1)
+	go func() { created <- NewGracefulDegradation(cfg, logger) }()
+
+	// Without serialization, gdB registers at once and its routine adopts the
+	// still-running task before gdA stops it. With serialization, gdB waits
+	// behind gdA's stop; the bound only limits how long the test waits then.
+	var gdB *GracefulDegradation
+	select {
+	case gdB = <-created:
+		waitForHealthRoutineSettled(t, gdB)
+	case <-time.After(200 * time.Millisecond):
+	}
+
+	close(release)
+	select {
+	case <-closed:
+	case <-time.After(10 * time.Second):
+		t.Fatal("gdA.Close did not return")
+	}
+	if gdB == nil {
+		select {
+		case gdB = <-created:
+		case <-time.After(10 * time.Second):
+			t.Fatal("NewGracefulDegradation did not return after gdA.Close")
+		}
+	}
+	defer gdB.Close()
+	waitForHealthRoutineSettled(t, gdB)
+
+	if !GetResourceManager().IsTaskRunning(gdHealthTaskName) {
+		t.Fatal("shared health-check task is stopped although gdB is still live")
+	}
+}

gd_health_task_close_race_test.go

@@ -0,0 +1,132 @@
+package traefikoidc
+
+import (
+	"runtime"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+const gdHealthTaskName = "graceful-degradation-health-check"
+
+// TestSharedHealthTaskNotRestartedAfterLastClose pins the stop-versus-start
+// race behind the flaky TestSharedHealthTaskSurvivesOtherInstanceClose.
+//
+// startHealthCheckRoutine checks gd.stopChan under gd.mutex and then creates
+// or adopts the shared health-check task. Close() used to close stopChan
+// without gd.mutex, so a routine that had already passed its check could
+// reach the task registry AFTER the last Close() stopped the task.
+// RegisterBackgroundTask replaces a stopped task with a fresh one, so the
+// routine restarted the shared task with no live instance left to stop it.
+//
+// The test parks gd2's routine right after its stopChan check by holding the
+// task-registry mutex (Close never takes it), closes both instances, and then
+// releases the routine. The shared task must stay stopped.
+func TestSharedHealthTaskNotRestartedAfterLastClose(t *testing.T) {
+	t.Cleanup(snapshotAndClearGdInstancesForTest())
+
+	cfg := DefaultGracefulDegradationConfig()
+	cfg.HealthCheckInterval = time.Hour
+	logger := GetSingletonNoOpLogger()
+
+	gd1 := NewGracefulDegradation(cfg, logger)
+	defer gd1.Close()
+	waitForHealthRoutineSettled(t, gd1)
+	if !GetResourceManager().IsTaskRunning(gdHealthTaskName) {
+		t.Fatal("precondition: shared health-check task must run while gd1 is live")
+	}
+
+	globalTaskRegistryMutex.Lock()
+	registryLocked := true
+	releaseRegistry := func() {
+		if registryLocked {
+			registryLocked = false
+			globalTaskRegistryMutex.Unlock()
+		}
+	}
+	defer releaseRegistry()
+
+	gd2 := NewGracefulDegradation(cfg, logger)
+	defer gd2.Close()
+	waitForGoroutineParkedIn(t, "(*GracefulDegradation).startHealthCheckRoutine", "traefikoidc.GetGlobalTaskRegistry")
+
+	gd1.Close()
+
+	closed := make(chan struct{})
+	go func() {
+		gd2.Close()
+		close(closed)
+	}()
+
+	// Release the parked routine once the last Close() has stopped the task.
+	// A Close() that waits for the in-flight routine keeps the task running,
+	// so the bound only limits how long this test waits in that case.
+	deadline := time.Now().Add(200 * time.Millisecond)
+	for time.Now().Before(deadline) && GetResourceManager().IsTaskRunning(gdHealthTaskName) {
+		time.Sleep(time.Millisecond)
+	}
+	releaseRegistry()
+
+	select {
+	case <-closed:
+	case <-time.After(10 * time.Second):
+		t.Fatal("gd2.Close did not return")
+	}
+
+	// gd2's routine holds gd2.mutex until it has created or adopted a task,
+	// so taking the lock waits for the routine to finish.
+	gd2.mutex.RLock()
+	routineTask := gd2.healthCheckTask
+	gd2.mutex.RUnlock()
+
+	if routineTask != nil && atomic.LoadInt32(&routineTask.stopped) == 0 {
+		routineTask.Stop()
+		t.Error("gd2's health routine holds a running task after the last GracefulDegradation closed")
+	}
+	if GetResourceManager().IsTaskRunning(gdHealthTaskName) {
+		_ = GetResourceManager().StopBackgroundTask(gdHealthTaskName)
+		t.Error("shared health-check task was restarted after the last GracefulDegradation closed")
+	}
+}
+
+// waitForGoroutineParkedIn polls all goroutine stacks until one stack contains
+// every given frame substring.
+func waitForGoroutineParkedIn(t *testing.T, frames ...string) {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		if goroutineStackContains(frames...) {
+			return
+		}
+		time.Sleep(time.Millisecond)
+	}
+	t.Fatalf("no goroutine parked in %v", frames)
+}
+
+func goroutineStackContains(frames ...string) bool {
+	buf := make([]byte, 1<<20)
+	for {
+		n := runtime.Stack(buf, true)
+		if n < len(buf) {
+			buf = buf[:n]
+			break
+		}
+		buf = make([]byte, 2*len(buf))
+	}
+	for _, stack := range strings.Split(string(buf), "\n\n") {
+		if stackHasAllFrames(stack, frames) {
+			return true
+		}
+	}
+	return false
+}
+
+func stackHasAllFrames(stack string, frames []string) bool {
+	for _, f := range frames {
+		if !strings.Contains(stack, f) {
+			return false
+		}
+	}
+	return true
+}

gd_test_helpers_test.go

@@ -0,0 +1,20 @@
+package traefikoidc
+
+// Shared GracefulDegradation-instance-registry test helper for
+// round-regression and FIX-round tests.
+//
+// Moved here for the R4 re-review (closing the rest of FIX-41): resetGdInstancesForTest
+// was declared inside review_r34_regression_test.go but consumed by
+// fix18_gd_lifecycle_test.go, a FIX-round test file — the dependency was not
+// even confined to other round files. Every review_rNN*_test.go and
+// fixNN*_test.go file must depend only on shared helpers like this one,
+// never on another round file's private declarations.
+
+// resetGdInstancesForTest establishes a clean baseline for the process-global
+// gdInstances registry so a test's "last instance" and iteration assertions
+// are not skewed by instances created by earlier tests in the same process.
+func resetGdInstancesForTest() {
+	gdInstances.Lock()
+	gdInstances.set = make(map[*GracefulDegradation]struct{})
+	gdInstances.Unlock()
+}

go.mod

@@ -2,6 +2,11 @@ module github.com/lukaszraczylo/traefikoidc
 
 go 1.24.0
 
+// Pin the toolchain to a stdlib version without the go1.26.5 CVEs
+// (GO-2026-6089 net/http ReadHeaderTimeout, GO-2026-5972 asn1 recursion,
+// GO-2026-5026 idna) reported by govulncheck (R219). Auto-downloaded.
+toolchain go1.26.6
+
 require (
 	github.com/alicebob/miniredis/v2 v2.35.0
 	github.com/gorilla/sessions v1.3.0

goroutine_manager.go

@@ -63,6 +63,14 @@ func (m *GoroutineManager) StartGoroutine(name string, fn func(context.Context))
 			m.wg.Done()
 			m.mu.Lock()
 			managedGoroutine.running = false
+			// Prune the map entry once this goroutine has finished so that
+			// finished goroutines don't accumulate unboundedly (R157). Only
+			// delete when the current entry still IS the finishing
+			// goroutine: a concurrent Start with the same name may have
+			// already replaced it with a live one.
+			if cur, ok := m.goroutines[goroutineName]; ok && cur == managedGoroutine {
+				delete(m.goroutines, goroutineName)
+			}
 			m.mu.Unlock()
 
 			// Recover from panics

goroutine_manager_test.go

@@ -45,6 +45,7 @@ func TestStartGoroutine(t *testing.T) {
 
 	gm.StartGoroutine("test-goroutine", func(ctx context.Context) {
 		executed.Store(true)
+		<-ctx.Done() // keep alive so it is tracked while running
 	})
 
 	// Give goroutine time to execute
@@ -54,6 +55,7 @@ func TestStartGoroutine(t *testing.T) {
 		t.Error("Expected goroutine to execute")
 	}
 
+	// A live goroutine is tracked (R157: finished goroutines are pruned).
 	status := gm.GetStatus()
 	if len(status) != 1 {
 		t.Errorf("Expected 1 goroutine in status, got %d", len(status))
@@ -370,8 +372,9 @@ func TestGetStatus(t *testing.T) {
 
 	status := gm.GetStatus()
 
-	if len(status) != 2 {
-		t.Errorf("Expected 2 goroutines in status, got %d", len(status))
+	// R157: finished goroutines are pruned, so only the live one remains.
+	if len(status) != 1 {
+		t.Errorf("Expected 1 live goroutine in status, got %d", len(status))
 	}
 
 	if runningStatus, exists := status["running"]; exists {
@@ -394,12 +397,8 @@ func TestGetStatus(t *testing.T) {
 		t.Error("Expected 'running' goroutine in status")
 	}
 
-	if quickStatus, exists := status["quick"]; exists {
-		if quickStatus.Running {
-			t.Error("Expected 'quick' goroutine to be marked as not running")
-		}
-	} else {
-		t.Error("Expected 'quick' goroutine in status")
+	if _, exists := status["quick"]; exists {
+		t.Error("Expected finished 'quick' goroutine to be pruned from status")
 	}
 }
 
@@ -435,7 +434,7 @@ func TestConcurrentStartGoroutine(t *testing.T) {
 			name := "concurrent-" + string(rune('0'+id%10)) + string(rune('0'+id/10))
 			gm.StartGoroutine(name, func(ctx context.Context) {
 				counter.Add(1)
-				time.Sleep(50 * time.Millisecond)
+				<-ctx.Done() // stay alive so it is still tracked (R157 prunes finished ones)
 				counter.Add(-1)
 			})
 		}(i)

helpers.go

@@ -6,6 +6,7 @@ import (
 	"crypto/sha256"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -13,8 +14,6 @@ import (
 	"net/url"
 	"strings"
 	"time"
-
-	"github.com/lukaszraczylo/traefikoidc/internal/utils"
 )
 
 // newUUIDv4 returns an RFC 4122 v4 UUID string (e.g.
@@ -109,10 +108,13 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
 	data := url.Values{
 		"grant_type": {grantType},
 	}
+	// Snapshot client credentials under metadataMu: DCR rewrites clientID/
+	// clientSecret/audience at runtime (R137).
+	clientID, clientSecret, clientAuthMethod, _, clientAssertion := t.clientCredentials()
 	// client_id is sent in the body for every method except client_secret_basic,
 	// where it is carried in the Authorization header per RFC 6749 §2.3.1.
-	if t.clientAuthMethod != "client_secret_basic" || t.clientAssertion != nil {
-		data.Set("client_id", t.clientID)
+	if clientAuthMethod != "client_secret_basic" || clientAssertion != nil {
+		data.Set("client_id", clientID)
 	}
 
 	if grantType == "authorization_code" {
@@ -157,29 +159,29 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
 	t.metadataMu.RUnlock()
 
 	useBasicAuth := false
-	if t.clientAssertion != nil {
-		assertion, err := t.clientAssertion.Sign(tokenURL, t.clientID)
+	if clientAssertion != nil {
+		assertion, err := clientAssertion.Sign(tokenURL, clientID)
 		if err != nil {
 			return nil, fmt.Errorf("failed to sign client assertion: %w", err)
 		}
 		data.Set("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer")
 		data.Set("client_assertion", assertion)
-	} else if t.clientAuthMethod == "client_secret_basic" {
+	} else if clientAuthMethod == "client_secret_basic" {
 		useBasicAuth = true
 	} else {
-		data.Set("client_secret", t.clientSecret)
+		data.Set("client_secret", clientSecret)
 	}
 
-	req, err := http.NewRequestWithContext(ctx, "POST", tokenURL, strings.NewReader(data.Encode()))
+	req, err := http.NewRequestWithContext(ctx, "POST", tokenURL, strings.NewReader(data.Encode())) //nolint:gosec // tokenURL is the operator-trusted discovery endpoint (metadataMu)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create token request: %w", err)
 	}
 	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
 	if useBasicAuth {
-		setOAuthBasicAuth(req, t.clientID, t.clientSecret)
+		setOAuthBasicAuth(req, clientID, clientSecret)
 	}
 
-	resp, err := client.Do(req)
+	resp, err := client.Do(req) //nolint:gosec // req above targets the trusted tokenURL
 	if err != nil {
 		return nil, fmt.Errorf("failed to exchange tokens: %w", err)
 	}
@@ -191,14 +193,33 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
 	if resp.StatusCode != http.StatusOK {
 		limitReader := io.LimitReader(resp.Body, 1024*10)
 		bodyBytes, _ := io.ReadAll(limitReader) // Safe to ignore: reading error body for diagnostics
-		return nil, fmt.Errorf("token endpoint returned status %d: %s", resp.StatusCode, string(bodyBytes))
+		// Return a *HTTPError so the retry executor's isRetryableError can
+		// classify transient 5xx/429 responses and actually retry (R118).
+		// A plain error here made the 5xx/429 retry branch dead in
+		// production — every token-endpoint status was treated as permanent.
+		return nil, &HTTPError{
+			StatusCode: resp.StatusCode,
+			Message:    fmt.Sprintf("token endpoint returned status %d: %s", resp.StatusCode, string(bodyBytes)),
+		}
 	}
 
 	var tokenResponse TokenResponse
-	if err := json.NewDecoder(resp.Body).Decode(&tokenResponse); err != nil {
+	// Cap the decoded body so a corrupted or malicious oversized 200-body cannot
+	// drive an unbounded read/allocation. Token responses are small (a few KB).
+	if err := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&tokenResponse); err != nil {
 		return nil, fmt.Errorf("failed to decode token response: %w", err)
 	}
 
+	// RFC 6749 §5.1: a token response MUST include an access_token. A 200
+	// that omitted it is a protocol violation, not a success — treat it as an
+	// error here so no caller authenticates with a blank token (R158).
+	// Previously this seam returned success with an empty access_token and
+	// each caller had to re-check "AccessToken == \"\"", which several
+	// paths missed.
+	if tokenResponse.AccessToken == "" {
+		return nil, fmt.Errorf("token endpoint returned 200 without an access_token (RFC 6749 §5.1)")
+	}
+
 	return &tokenResponse, nil
 }
 
@@ -211,6 +232,17 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
 // Returns:
 //   - *TokenResponse: New token set from the authorization server
 //   - An error if the refresh operation fails
+//
+// redactToken returns a short, stable hash of a token credential suitable for
+// debug logging without leaking the credential itself (R138).
+func redactToken(token string) string {
+	if token == "" {
+		return "(empty)"
+	}
+	sum := sha256.Sum256([]byte(token))
+	return fmt.Sprintf("%x", sum[:4])
+}
+
 func (t *TraefikOidc) getNewTokenWithRefreshToken(refreshToken string) (*TokenResponse, error) {
 	ctx := context.Background()
 
@@ -225,7 +257,8 @@ func (t *TraefikOidc) getNewTokenWithRefreshToken(refreshToken string) (*TokenRe
 		return nil, fmt.Errorf("failed to refresh token: %w", err)
 	}
 
-	t.logger.Debugf("Token response: %+v", tokenResponse)
+	t.logger.Debugf("Refresh token response: token_type=%s expires_in=%d access_token=%s",
+		tokenResponse.TokenType, tokenResponse.ExpiresIn, redactToken(tokenResponse.AccessToken))
 	return tokenResponse, nil
 }
 
@@ -387,6 +420,14 @@ func (t *TraefikOidc) handleLogout(rw http.ResponseWriter, req *http.Request) {
 	}
 
 	idToken := session.GetIDToken()
+	accessToken := session.GetAccessToken()
+	refreshToken := session.GetRefreshToken()
+	// Capture the trusted origin BEFORE Clear wipes the session. redirect_url
+	// was persisted at authentication-initiate time (R136) and is therefore
+	// the exact scheme+host the IdP already accepted as this deployment's
+	// redirect_uri — unlike the current request's Host/X-Forwarded-Host,
+	// the browser cannot spoof it on this logout request (FIX-07).
+	trustedOrigin := trustedOriginFromRedirectURL(session.GetRedirectURL())
 
 	if err := session.Clear(req, rw); err != nil {
 		t.logger.Errorf("Error clearing session: %v", err)
@@ -394,9 +435,37 @@ func (t *TraefikOidc) handleLogout(rw http.ResponseWriter, req *http.Request) {
 		return
 	}
 
-	host := utils.DetermineHost(req)
-	scheme := utils.DetermineScheme(req, t.forceHTTPS)
-	baseURL := fmt.Sprintf("%s://%s", scheme, host)
+	// Blacklist the session's tokens so a token captured before logout (e.g. a
+	// bearer mode access token) cannot be reused until its natural expiry.
+	// RevokeToken is a no-op-safe local blacklist (guards nil) and skips
+	// empty values.
+	for _, tok := range []string{accessToken, idToken, refreshToken} {
+		if tok != "" {
+			t.RevokeToken(tok)
+		}
+	}
+
+	// Best-effort provider-side revocation (single logout): the local
+	// blacklist only stops reuse in-process, but a token captured before
+	// logout (e.g. a bearer-mode access token or the refresh token) stays
+	// valid at the IdP and a captured refresh token could keep minting new
+	// tokens. Revoke both access and refresh tokens at the provider when a
+	// revocation endpoint is available. Each call is bounded by
+	// revocationRequestTimeout so a slow or unreachable provider cannot
+	// hold the logout redirect open indefinitely (FIX-33). A genuine
+	// failure is logged at error level; the expected "no revocation
+	// endpoint configured" case (most deployments) stays silent so it
+	// doesn't log on every logout.
+	if accessToken != "" {
+		if err := t.RevokeTokenWithProvider(accessToken, "access_token"); err != nil && !errors.Is(err, ErrRevocationEndpointNotConfigured) {
+			t.logger.Errorf("Provider-side revocation failed for access_token: %v", err)
+		}
+	}
+	if refreshToken != "" {
+		if err := t.RevokeTokenWithProvider(refreshToken, "refresh_token"); err != nil && !errors.Is(err, ErrRevocationEndpointNotConfigured) {
+			t.logger.Errorf("Provider-side revocation failed for refresh_token: %v", err)
+		}
+	}
 
 	postLogoutRedirectURI := t.postLogoutRedirectURI
 	// localRedirect is used when there is no provider end-session endpoint and
@@ -404,14 +473,36 @@ func (t *TraefikOidc) handleLogout(rw http.ResponseWriter, req *http.Request) {
 	// derived from the request host (X-Forwarded-Host is client-controllable and
 	// would be an open redirect); use a host-relative path, or the operator's
 	// own configured absolute URL, instead.
+	//
+	// The post_logout_redirect_uri we hand to the IdP has the same constraint:
+	// deriving it from baseURL (scheme://client-controlled host) lets an
+	// attacker's X-Forwarded-Host steer the browser to an arbitrary origin
+	// after logout (open redirect through the IdP). So we build it from
+	// trustedOrigin (the redirect_uri origin the IdP already accepted at
+	// login, R136) instead; when no trusted origin was recorded (pre-R136
+	// session, or logout without a completed login), BuildLogoutURL omits
+	// the parameter entirely rather than guessing (FIX-07 corrects R68,
+	// which dropped the parameter unconditionally for every non-absolute
+	// config value, including the documented default of '/').
 	localRedirect := "/"
-	if postLogoutRedirectURI == "" {
-		postLogoutRedirectURI = fmt.Sprintf("%s/", baseURL)
-	} else if !strings.HasPrefix(postLogoutRedirectURI, "http") {
-		localRedirect = normalizeLogoutPath(postLogoutRedirectURI)
-		postLogoutRedirectURI = fmt.Sprintf("%s%s", baseURL, postLogoutRedirectURI)
-	} else {
+	switch {
+	case strings.HasPrefix(postLogoutRedirectURI, "http"):
+		// Operator configured an explicit absolute URL: already a trusted
+		// origin on its own, independent of trustedOrigin.
 		localRedirect = postLogoutRedirectURI
+	case postLogoutRedirectURI == "":
+		postLogoutRedirectURI = "" // no trusted origin below leaves it empty
+		if trustedOrigin != "" {
+			postLogoutRedirectURI = trustedOrigin + "/"
+		}
+	default:
+		// Relative operator-configured path: trusted for the plugin's own
+		// redirect, rebuilt against the trusted origin for the IdP.
+		localRedirect = normalizeLogoutPath(postLogoutRedirectURI)
+		postLogoutRedirectURI = ""
+		if trustedOrigin != "" {
+			postLogoutRedirectURI = trustedOrigin + localRedirect
+		}
 	}
 
 	// Read endSessionURL with RLock
@@ -426,13 +517,36 @@ func (t *TraefikOidc) handleLogout(rw http.ResponseWriter, req *http.Request) {
 			http.Error(rw, "Logout error", http.StatusInternalServerError)
 			return
 		}
+		// Logout redirects must never be cached: a heuristic-caching proxy
+		// replaying the 302 would re-trigger logout for an already
+		// logged-out session (R147 cache-directive contract).
+		rw.Header().Set("Cache-Control", "no-store")
 		http.Redirect(rw, req, logoutURL, http.StatusFound)
 		return
 	}
 
+	rw.Header().Set("Cache-Control", "no-store")
 	http.Redirect(rw, req, localRedirect, http.StatusFound)
 }
 
+// trustedOriginFromRedirectURL extracts "scheme://host" from the redirect_uri
+// persisted at authentication-initiate time (R136), for reuse as the trusted
+// origin when building post_logout_redirect_uri (FIX-07). That redirect_uri
+// was already accepted by the IdP as this deployment's own callback, so its
+// origin is safe to reuse — unlike the current request's Host/
+// X-Forwarded-Host, which the browser controls. Returns "" when redirectURL
+// is empty or is not an absolute http(s) URL.
+func trustedOriginFromRedirectURL(redirectURL string) string {
+	if redirectURL == "" {
+		return ""
+	}
+	u, err := url.Parse(redirectURL)
+	if err != nil || u.Host == "" || (u.Scheme != "http" && u.Scheme != "https") {
+		return ""
+	}
+	return u.Scheme + "://" + u.Host
+}
+
 // BuildLogoutURL constructs a logout URL for the OIDC provider's end session endpoint.
 // It includes the ID token hint and post-logout redirect URI according to OIDC specifications.
 // Parameters:

http_client_factory.go

@@ -61,16 +61,23 @@ func DefaultHTTPClientConfig() HTTPClientConfig {
 	}
 }
 
-// TokenHTTPClientConfig returns configuration optimized for token operations
+// TokenHTTPClientConfig returns configuration optimized for token operations.
 func TokenHTTPClientConfig() HTTPClientConfig {
 	config := DefaultHTTPClientConfig()
 	config.Timeout = 10 * time.Second // Shorter timeout for token operations
 	config.MaxRedirects = 50          // Token endpoints may redirect more
-	config.UseCookieJar = true        // Enable cookie jar for token operations
+	// UseCookieJar stays false (DefaultHTTPClientConfig's default). This
+	// config builds the single per-plugin-instance pooled token client
+	// (main.go, CreateTokenHTTPClient), shared by every user's token and
+	// refresh exchange. A jar on a shared client stores whatever
+	// Set-Cookie the IdP returns for one user's exchange and replays it on
+	// the next user's request to the same host - cross-user state
+	// confusion at the IdP (FIX-12; R70 had turned this on). Token/refresh
+	// calls are stateless back-channel requests and need no jar.
 	return config
 }
 
-// OIDCProviderHTTPClientConfig returns configuration optimized for OIDC provider calls
+// OIDCProviderHTTPClientConfig returns configuration optimized for OIDC provider calls.
 func OIDCProviderHTTPClientConfig() HTTPClientConfig {
 	config := DefaultHTTPClientConfig()
 	config.Timeout = 15 * time.Second         // Slightly longer for OIDC operations
@@ -78,7 +85,10 @@ func OIDCProviderHTTPClientConfig() HTTPClientConfig {
 	config.MaxIdleConnsPerHost = 25           // More connections per OIDC provider
 	config.MaxConnsPerHost = 50               // Allow more concurrent requests to OIDC provider
 	config.IdleConnTimeout = 90 * time.Second // Keep connections alive longer for reuse
-	config.UseCookieJar = true                // Enable cookie jar for session management
+	// UseCookieJar stays false, for the same cross-user reason as
+	// TokenHTTPClientConfig above (FIX-12): any client built from this
+	// config through the shared transport pool is one instance shared by
+	// every user, so a jar would leak cookies between them.
 	return config
 }
 
@@ -138,10 +148,13 @@ func (f *HTTPClientFactory) ValidateHTTPClientConfig(config *HTTPClientConfig) e
 	return nil
 }
 
-// CreateHTTPClient creates an HTTP client with the given configuration
-// Validates configuration parameters before creating the client
-func (f *HTTPClientFactory) CreateHTTPClient(config HTTPClientConfig) *http.Client {
-	// Set defaults for zero values before validation
+// applyHTTPClientDefaults fills zero-valued fields in cfg with the standard
+// conservative defaults so that a partially-populated config never yields an
+// unbounded HTTP client (zero overall Timeout or ResponseHeaderTimeout would make
+// a stalled upstream hang forever). All construction paths MUST converge on this
+// helper so behavior is identical: CreateHTTPClient and the shared transport
+// pool (CreatePooledHTTPClient / GetOrCreateTransport).
+func applyHTTPClientDefaults(config *HTTPClientConfig) {
 	if config.Timeout == 0 {
 		config.Timeout = 30 * time.Second
 	}
@@ -178,6 +191,13 @@ func (f *HTTPClientFactory) CreateHTTPClient(config HTTPClientConfig) *http.Clie
 	if config.ReadBufferSize == 0 {
 		config.ReadBufferSize = 4096
 	}
+}
+
+// CreateHTTPClient creates an HTTP client with the given configuration
+// Validates configuration parameters before creating the client
+func (f *HTTPClientFactory) CreateHTTPClient(config HTTPClientConfig) *http.Client {
+	// Set defaults for zero values before validation
+	applyHTTPClientDefaults(&config)
 
 	// Validate configuration - only fail on critical errors
 	if err := f.ValidateHTTPClientConfig(&config); err != nil {
@@ -209,9 +229,8 @@ func (f *HTTPClientFactory) CreateHTTPClient(config HTTPClientConfig) *http.Clie
 				tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
 				tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
 			},
-			PreferServerCipherSuites: true,
-			RootCAs:                  config.RootCAs,
-			InsecureSkipVerify:       config.InsecureSkipVerify, //nolint:gosec // opt-in, loud warning emitted at plugin startup
+			RootCAs:            config.RootCAs,
+			InsecureSkipVerify: config.InsecureSkipVerify, // #nosec G402 -- operator opt-in (insecureSkipVerify, default false); New logs a SECURITY WARNING
 		},
 		ForceAttemptHTTP2:     config.ForceHTTP2,
 		TLSHandshakeTimeout:   config.TLSHandshakeTimeout,

http_client_factory_unit_test.go

@@ -18,7 +18,10 @@ func TestOIDCProviderHTTPClientConfigUnit(t *testing.T) {
 	assert.Equal(t, 25, config.MaxIdleConnsPerHost, "OIDC provider should have 25 max idle conns per host")
 	assert.Equal(t, 50, config.MaxConnsPerHost, "OIDC provider should have 50 max conns per host")
 	assert.Equal(t, 90*time.Second, config.IdleConnTimeout, "OIDC provider should have 90s idle conn timeout")
-	assert.True(t, config.UseCookieJar, "OIDC provider should have cookie jar enabled")
+	// UseCookieJar must stay false (FIX-12): this config feeds the shared
+	// pooled client, and a jar there would leak one user's IdP cookies to
+	// every other user of the same pooled instance.
+	assert.False(t, config.UseCookieJar, "OIDC provider pooled client must not have a shared cookie jar")
 }
 
 // TestCreateDefaultClientUnit tests CreateDefaultClient function
@@ -38,7 +41,9 @@ func TestCreateTokenClientUnit(t *testing.T) {
 
 	require.NotNil(t, client)
 	assert.NotNil(t, client.Transport, "client should have transport")
-	assert.NotNil(t, client.Jar, "token client should have cookie jar")
+	// No jar (FIX-12): TokenHTTPClientConfig's UseCookieJar stays false so
+	// a client built from it never carries cross-request cookie state.
+	assert.Nil(t, client.Jar, "token client must not have a cookie jar")
 	assert.Equal(t, 10*time.Second, client.Timeout, "token client should have 10s timeout")
 }
 

http_client_jar_test.go

@@ -0,0 +1,58 @@
+package traefikoidc
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestPooledTokenClient_DoesNotShareCookieJarAcrossRequests regresses
+// FIX-12: R70 gave CreatePooledHTTPClient's client a cookie jar whenever
+// UseCookieJar is set, and TokenHTTPClientConfig (used to build the single
+// per-plugin-instance tokenHTTPClient, main.go) set UseCookieJar: true. That
+// one client, and its one jar, is shared by every user's token/refresh
+// exchange. An IdP Set-Cookie on user A's exchange was stored in the shared
+// jar and replayed on user B's next token request to the same host -
+// cross-user state confusion at the IdP. Token/refresh calls are stateless
+// back-channel requests and must never carry a cross-request jar.
+func TestPooledTokenClient_DoesNotShareCookieJarAcrossRequests(t *testing.T) {
+	var requests int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requests++
+		if requests == 1 {
+			// Simulate the IdP setting a session/affinity cookie on user A's
+			// token exchange response.
+			http.SetCookie(w, &http.Cookie{Name: "idp_sess", Value: "alice"})
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		// User B's request: must not carry the cookie set on user A's call.
+		if c, err := r.Cookie("idp_sess"); err == nil {
+			t.Errorf("request %d carried leaked cookie idp_sess=%s from an earlier request", requests, c.Value)
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	client := CreatePooledHTTPClient(TokenHTTPClientConfig())
+
+	// Request 1 (user A): receives and would store the IdP's Set-Cookie if
+	// the client has a jar.
+	resp1, err := client.Get(srv.URL)
+	if err != nil {
+		t.Fatalf("request 1: %v", err)
+	}
+	resp1.Body.Close()
+
+	// Request 2 (user B, same pooled client, same host): must be a clean
+	// request with no cookie carried over from request 1.
+	resp2, err := client.Get(srv.URL)
+	if err != nil {
+		t.Fatalf("request 2: %v", err)
+	}
+	resp2.Body.Close()
+
+	if requests != 2 {
+		t.Fatalf("want 2 requests reaching the server, got %d", requests)
+	}
+}

http_client_pool.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"net"
 	"net/http"
+	"net/http/cookiejar"
 	"sync"
 	"sync/atomic"
 	"time"
@@ -57,6 +58,12 @@ func GetGlobalTransportPool() *SharedTransportPool {
 
 // GetOrCreateTransport gets or creates a shared transport with the given config
 func (p *SharedTransportPool) GetOrCreateTransport(config HTTPClientConfig) *http.Transport {
+	// Apply the same zero-value defaults as CreateHTTPClient so a partially
+	// populated config never yields an unbounded client/transport, and so the
+	// pool cache key reflects normalized values (configKey). Bounded here,
+	// before the client-count gate, so both the gate and the key see
+	// normalized timeouts.
+	applyHTTPClientDefaults(&config)
 	// SECURITY FIX: Check client limit before creating new transport.
 	if atomic.LoadInt32(&p.clientCount) >= p.maxClients {
 		// At the client limit: only reuse a transport that was built for the
@@ -74,10 +81,21 @@ func (p *SharedTransportPool) GetOrCreateTransport(config HTTPClientConfig) *htt
 				return shared.transport
 			}
 		}
-		// No TLS-compatible transport available; return nil so the caller falls
-		// back to a default, certificate-verifying transport rather than one
-		// with a different (possibly verification-disabled) trust store.
-		return nil
+		// No TLS-compatible transport available. Returning nil would make the
+		// caller fall back to http.DefaultTransport, silently dropping the
+		// configured RootCAs / InsecureSkipVerify — custom-CA TLS would
+		// break and self-signed skip-verify would be lost (R95). Build and
+		// return the correctly-configured transport instead; honoring TLS
+		// settings takes precedence over the soft client cap.
+		t := newSharedTransport(config)
+		p.transports[p.configKey(config)] = &sharedTransport{
+			transport: t,
+			refCount:  1,
+			lastUsed:  time.Now(),
+			tlsKey:    want,
+		}
+		atomic.AddInt32(&p.clientCount, 1)
+		return t
 	}
 
 	p.mu.Lock()
@@ -94,8 +112,26 @@ func (p *SharedTransportPool) GetOrCreateTransport(config HTTPClientConfig) *htt
 	// Increment client count
 	atomic.AddInt32(&p.clientCount, 1)
 
-	// Create new transport with conservative limits
-	transport := &http.Transport{
+	transport := newSharedTransport(config)
+
+	p.transports[key] = &sharedTransport{
+		transport: transport,
+		refCount:  1,
+		lastUsed:  time.Now(),
+		tlsKey:    tlsConfigKey(config),
+	}
+
+	return transport
+}
+
+// newSharedTransport builds a properly-configured *http.Transport from the
+// given config, enforcing TLS 1.2+ and secure cipher suites. Shared by the
+// normal acquisition path and the at-cap fallback so the TLS settings are
+// NEVER silently dropped (the at-cap fallback previously returned nil,
+// making the caller fall back to http.DefaultTransport and lose the
+// configured RootCAs / InsecureSkipVerify — R95).
+func newSharedTransport(config HTTPClientConfig) *http.Transport {
+	return &http.Transport{
 		Proxy: http.ProxyFromEnvironment,
 		DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
 			dialer := &net.Dialer{
@@ -114,32 +150,22 @@ func (p *SharedTransportPool) GetOrCreateTransport(config HTTPClientConfig) *htt
 				tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
 				tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
 			},
-			PreferServerCipherSuites: true,
-			RootCAs:                  config.RootCAs,
-			InsecureSkipVerify:       config.InsecureSkipVerify, //nolint:gosec // opt-in, loud warning emitted at plugin startup
+			RootCAs:            config.RootCAs,
+			InsecureSkipVerify: config.InsecureSkipVerify, // #nosec G402 -- operator opt-in (insecureSkipVerify, default false); New logs a SECURITY WARNING
 		},
 		ForceAttemptHTTP2:     config.ForceHTTP2,
 		TLSHandshakeTimeout:   config.TLSHandshakeTimeout,
 		ExpectContinueTimeout: config.ExpectContinueTimeout,
-		MaxIdleConns:          10,               // SECURITY FIX: Further reduced
-		MaxIdleConnsPerHost:   2,                // SECURITY FIX: Limited connections
-		IdleConnTimeout:       30 * time.Second, // Reduced from 5 minutes
+		MaxIdleConns:          config.MaxIdleConns,
+		MaxIdleConnsPerHost:   config.MaxIdleConnsPerHost,
+		IdleConnTimeout:       config.IdleConnTimeout,
 		DisableKeepAlives:     config.DisableKeepAlives,
-		MaxConnsPerHost:       5, // SECURITY FIX: Strict limit
+		MaxConnsPerHost:       config.MaxConnsPerHost,
 		ResponseHeaderTimeout: config.ResponseHeaderTimeout,
 		DisableCompression:    config.DisableCompression,
 		WriteBufferSize:       config.WriteBufferSize,
 		ReadBufferSize:        config.ReadBufferSize,
 	}
-
-	p.transports[key] = &sharedTransport{
-		transport: transport,
-		refCount:  1,
-		lastUsed:  time.Now(),
-		tlsKey:    tlsConfigKey(config),
-	}
-
-	return transport
 }
 
 // ReleaseTransport decrements the reference count for a transport
@@ -219,20 +245,35 @@ func (p *SharedTransportPool) performCleanup() {
 
 // configKey generates a unique key for a config
 func (p *SharedTransportPool) configKey(config HTTPClientConfig) string {
-	// Pool transports by the parameters that change TLS or connection
-	// behavior. RootCAs and InsecureSkipVerify MUST be part of the key:
+	// Pool transports by every parameter the built *http.Transport actually
+	// consumes. RootCAs and InsecureSkipVerify MUST be part of the key:
 	// otherwise a middleware configured with a custom CA would share a
 	// transport with one using the system store, silently bypassing its
-	// CA configuration.
+	// CA configuration. The remaining fields affect connection behavior
+	// (HTTP version, compression, keep-alives, timeouts, buffer sizes,
+	// dial settings); omitting them would hand a caller a transport built
+	// with different settings than it requested (e.g. wrong compression).
 	skip := "0"
 	if config.InsecureSkipVerify {
 		skip = "1"
 	}
-	return fmt.Sprintf("%d|%d|%p|%s",
+	return fmt.Sprintf("%d|%d|%p|%s|%d|%d|%d|%v|%v|%v|%d|%d|%d|%d|%d|%d",
 		config.MaxConnsPerHost,
 		config.MaxIdleConnsPerHost,
 		config.RootCAs,
 		skip,
+		config.DialTimeout,
+		config.KeepAlive,
+		config.TLSHandshakeTimeout,
+		config.ForceHTTP2,
+		config.DisableKeepAlives,
+		config.DisableCompression,
+		config.ResponseHeaderTimeout,
+		config.ExpectContinueTimeout,
+		config.WriteBufferSize,
+		config.ReadBufferSize,
+		config.IdleConnTimeout,
+		config.MaxIdleConns,
 	)
 }
 
@@ -248,24 +289,38 @@ func tlsConfigKey(config HTTPClientConfig) string {
 	return fmt.Sprintf("%p|%s", config.RootCAs, skip)
 }
 
-// Cleanup closes all transports and stops the cleanup goroutine
+// Cleanup closes all transports, resets the pool, and restarts the cleanup
+// goroutine so the (singleton) pool remains fully usable afterwards. Prior
+// to R125, Cleanup canceled the cleanup goroutine but never restarted it
+// and left clientCount unreset: a reused singleton then had a permanently
+// dead cleaner (idle conns never pruned) and a stale count (the soft
+// maxClients cap keyed off it was wrong after reuse).
 func (p *SharedTransportPool) Cleanup() {
 	p.mu.Lock()
-	defer p.mu.Unlock()
-
-	// Stop the cleanup goroutine
-	if p.cancel != nil {
-		p.cancel()
-	}
-
 	for _, shared := range p.transports {
-		shared.transport.CloseIdleConnections()
+		if shared != nil && shared.transport != nil {
+			shared.transport.CloseIdleConnections()
+		}
 	}
 	p.transports = make(map[string]*sharedTransport)
+	atomic.StoreInt32(&p.clientCount, 0)
+	oldCancel := p.cancel
+	ctx, cancel := context.WithCancel(context.Background())
+	p.ctx = ctx
+	p.cancel = cancel
+	p.mu.Unlock()
+
+	if oldCancel != nil {
+		oldCancel()
+	}
+	go p.cleanupIdleTransports(ctx)
 }
 
 // CreatePooledHTTPClient creates an HTTP client using the shared transport pool
 func CreatePooledHTTPClient(config HTTPClientConfig) *http.Client {
+	// Apply the same zero-value defaults as CreateHTTPClient so a partially
+	// populated config still gets a bounded overall request Timeout.
+	applyHTTPClientDefaults(&config)
 	pool := GetGlobalTransportPool()
 	transport := pool.GetOrCreateTransport(config)
 
@@ -274,6 +329,18 @@ func CreatePooledHTTPClient(config HTTPClientConfig) *http.Client {
 		Transport: transport,
 	}
 
+	// Attach a jar only for callers that opt in via UseCookieJar, matching
+	// CreateHTTPClient (http_client_factory.go). TokenHTTPClientConfig and
+	// OIDCProviderHTTPClientConfig deliberately leave UseCookieJar false:
+	// a client built through this pool from either config is one instance
+	// shared across every user, so a jar would leak one user's cookies
+	// (e.g. Set-Cookie on a token/refresh response) into another user's
+	// requests to the same host (FIX-12).
+	if config.UseCookieJar {
+		jar, _ := cookiejar.New(nil) // Safe to ignore: nil options rarely fail
+		client.Jar = jar
+	}
+
 	// Configure redirect policy
 	maxRedirects := config.MaxRedirects
 	if maxRedirects == 0 {

http_client_pool_test.go

@@ -63,9 +63,17 @@ func TestSharedTransportPoolGetOrCreateTransport(t *testing.T) {
 		}
 
 		config := DefaultHTTPClientConfig()
+		config.InsecureSkipVerify = true //nolint:gosec // distinct TLS config to miss the tlsKey cache
 		transport := pool.GetOrCreateTransport(config)
 
-		assert.Nil(t, transport, "should return nil when at client limit")
+		// R95: at the client limit with no TLS-compatible transport, we must
+		// still return a correctly-configured transport (never nil, which
+		// previously fell back to http.DefaultTransport and dropped TLS
+		// settings).
+		require.NotNil(t, transport, "at-cap transport must not be nil")
+		if transport.TLSClientConfig == nil || !transport.TLSClientConfig.InsecureSkipVerify {
+			t.Fatal("at-cap transport must preserve the requested TLS settings")
+		}
 	})
 
 	t.Run("client limit with existing transport", func(t *testing.T) {
@@ -256,7 +264,7 @@ func TestSharedTransportPoolCleanup(t *testing.T) {
 		assert.Len(t, pool.transports, 0, "all transports should be removed")
 	})
 
-	t.Run("cleanup cancels context", func(t *testing.T) {
+	t.Run("cleanup cancels the old context and stays reusable", func(t *testing.T) {
 		ctx, cancel := context.WithCancel(context.Background())
 		pool := &SharedTransportPool{
 			transports:  make(map[string]*sharedTransport),
@@ -270,10 +278,16 @@ func TestSharedTransportPoolCleanup(t *testing.T) {
 		pool.Cleanup()
 
 		select {
-		case <-pool.ctx.Done():
-			// Context was canceled
+		case <-ctx.Done():
+			// The previous cleanup context was canceled (goroutine stopped).
 		case <-time.After(100 * time.Millisecond):
-			t.Error("context should be canceled")
+			t.Error("the previous cleanup context should be canceled")
+		}
+
+		// R125: Cleanup must leave the pool fully reusable — a fresh
+		// context is installed and new transports can still be acquired.
+		if tr := pool.GetOrCreateTransport(DefaultHTTPClientConfig()); tr == nil {
+			t.Error("pool must remain usable after Cleanup")
 		}
 	})
 
@@ -689,3 +703,58 @@ func TestSharedTransportPoolEdgeCases(t *testing.T) {
 		assert.Equal(t, int32(0), finalCount, "client count should decrement on cleanup")
 	})
 }
+
+// TestSharedTransportPoolAppliesConfigLimits is a regression test: the pooled
+// transport must apply the configured connection limits (MaxConnsPerHost,
+// MaxIdleConnsPerHost, MaxIdleConns, IdleConnTimeout) rather than hardcoded
+// constants. Previously GetOrCreateTransport built the transport with fixed
+// values (5/2/10/30s) while configKey still incorporated these config fields,
+// so the config was valid, keyed, and validated but silently ignored
+// (dead config) — e.g. OIDCProviderHTTPClientConfig's tuning had no effect.
+func TestSharedTransportPoolAppliesConfigLimits(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	pool := &SharedTransportPool{
+		transports:  make(map[string]*sharedTransport),
+		maxConns:    20,
+		clientCount: 0,
+		maxClients:  5,
+		ctx:         ctx,
+		cancel:      cancel,
+	}
+
+	config := DefaultHTTPClientConfig()
+	config.MaxConnsPerHost = 37
+	config.MaxIdleConnsPerHost = 13
+	config.MaxIdleConns = 41
+	config.IdleConnTimeout = 7 * time.Second
+
+	transport := pool.GetOrCreateTransport(config)
+	require.NotNil(t, transport)
+
+	assert.Equal(t, 37, transport.MaxConnsPerHost, "MaxConnsPerHost must come from config")
+	assert.Equal(t, 13, transport.MaxIdleConnsPerHost, "MaxIdleConnsPerHost must come from config")
+	assert.Equal(t, 41, transport.MaxIdleConns, "MaxIdleConns must come from config")
+	assert.Equal(t, 7*time.Second, transport.IdleConnTimeout, "IdleConnTimeout must come from config")
+}
+
+// TestCreatePooledHTTPClient_CookieJarOption regresses a config no-effect:
+// CreatePooledHTTPClient ignored config.UseCookieJar, so pooled token/OIDC
+// clients dropped the cookie jar that the non-pooled CreateHTTPClient
+// honors (queue cookies from auth-server token/refresh responses were
+// never stored or re-sent).
+func TestCreatePooledHTTPClient_CookieJarOption(t *testing.T) {
+	t.Run("enabled", func(t *testing.T) {
+		client := CreatePooledHTTPClient(HTTPClientConfig{UseCookieJar: true})
+		if client.Jar == nil {
+			t.Fatal("expected a cookie jar when UseCookieJar is true")
+		}
+	})
+	t.Run("disabled", func(t *testing.T) {
+		client := CreatePooledHTTPClient(HTTPClientConfig{UseCookieJar: false})
+		if client.Jar != nil {
+			t.Fatal("expected no cookie jar when UseCookieJar is false")
+		}
+	})
+}

input_validation.go

@@ -1,727 +0,0 @@
-package traefikoidc
-
-import (
-	"fmt"
-	"net/url"
-	"regexp"
-	"strconv"
-	"strings"
-	"unicode"
-	"unicode/utf8"
-)
-
-// Pre-compiled regex patterns for validation (const patterns should use MustCompile)
-var (
-	emailRegexPattern    = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
-	urlRegexPattern      = regexp.MustCompile(`^https?://[a-zA-Z0-9.-]+(?:\.[a-zA-Z]{2,})?(?::[0-9]+)?(?:/[^\s]*)?$`)
-	tokenRegexPattern    = regexp.MustCompile(`^[A-Za-z0-9._-]+$`)
-	usernameRegexPattern = regexp.MustCompile(`^[a-zA-Z0-9._-]+$`)
-)
-
-// InputValidator provides comprehensive input validation and sanitization
-// to protect against common security vulnerabilities including SQL injection,
-// XSS, path traversal, and other injection attacks. It validates and sanitizes
-// various input types used in OIDC authentication flows.
-type InputValidator struct {
-	usernameRegex           *regexp.Regexp
-	tokenRegex              *regexp.Regexp
-	logger                  *Logger
-	urlRegex                *regexp.Regexp
-	emailRegex              *regexp.Regexp
-	sqlInjectionPatterns    []string
-	pathTraversalPatterns   []string
-	xssPatterns             []string
-	maxUsernameLength       int
-	maxURLLength            int
-	maxTokenLength          int
-	maxEmailLength          int
-	maxClaimLength          int
-	maxHeaderLength         int
-	allowPrivateIPAddresses bool // Allow private IP addresses in URL validation
-}
-
-// ValidationResult encapsulates the outcome of input validation.
-// It includes the sanitized value, detected security risks, validation
-// errors and warnings, and an overall validity status.
-type ValidationResult struct {
-	SanitizedValue string   `json:"sanitized_value,omitempty"`
-	SecurityRisk   string   `json:"security_risk,omitempty"`
-	Errors         []string `json:"errors,omitempty"`
-	Warnings       []string `json:"warnings,omitempty"`
-	IsValid        bool     `json:"is_valid"`
-}
-
-// InputValidationConfig defines the configuration parameters for input validation.
-// It specifies maximum lengths for various input types and controls whether
-// strict validation mode is enabled.
-type InputValidationConfig struct {
-	MaxTokenLength          int  `json:"max_token_length"`
-	MaxURLLength            int  `json:"max_url_length"`
-	MaxHeaderLength         int  `json:"max_header_length"`
-	MaxClaimLength          int  `json:"max_claim_length"`
-	MaxEmailLength          int  `json:"max_email_length"`
-	MaxUsernameLength       int  `json:"max_username_length"`
-	StrictMode              bool `json:"strict_mode"`
-	AllowPrivateIPAddresses bool `json:"allow_private_ip_addresses"` // Allow private IP addresses in URL validation
-}
-
-// DefaultInputValidationConfig returns a secure default configuration
-// for input validation with reasonable limits based on industry standards
-// and security best practices.
-func DefaultInputValidationConfig() InputValidationConfig {
-	return InputValidationConfig{
-		MaxTokenLength:    50000, // 50KB for tokens
-		MaxURLLength:      2048,  // Standard URL length limit
-		MaxHeaderLength:   8192,  // 8KB for headers
-		MaxClaimLength:    1024,  // 1KB for individual claims
-		MaxEmailLength:    254,   // RFC 5321 limit
-		MaxUsernameLength: 64,    // Reasonable username limit
-		StrictMode:        true,  // Enable strict validation by default
-	}
-}
-
-// NewInputValidator creates a new input validator with the specified configuration.
-// It uses pre-compiled regex patterns and initializes security pattern lists.
-//
-// Parameters:
-//   - config: Validation configuration with size limits and mode settings.
-//   - logger: Logger instance for recording validation events.
-//
-// Returns:
-//   - A configured InputValidator instance.
-//   - An error (always nil, kept for API compatibility).
-func NewInputValidator(config InputValidationConfig, logger *Logger) (*InputValidator, error) {
-	return &InputValidator{
-		maxTokenLength:          config.MaxTokenLength,
-		maxURLLength:            config.MaxURLLength,
-		maxHeaderLength:         config.MaxHeaderLength,
-		maxClaimLength:          config.MaxClaimLength,
-		maxEmailLength:          config.MaxEmailLength,
-		maxUsernameLength:       config.MaxUsernameLength,
-		allowPrivateIPAddresses: config.AllowPrivateIPAddresses,
-		emailRegex:              emailRegexPattern,
-		urlRegex:                urlRegexPattern,
-		tokenRegex:              tokenRegexPattern,
-		usernameRegex:           usernameRegexPattern,
-		sqlInjectionPatterns: []string{
-			"'", "\"", ";", "--", "/*", "*/", "xp_", "sp_",
-			"union", "select", "insert", "update", "delete", "drop",
-			"create", "alter", "exec", "execute", "script",
-		},
-		xssPatterns: []string{
-			"<script", "</script>", "javascript:", "vbscript:",
-			"onload=", "onerror=", "onclick=", "onmouseover=",
-			"<iframe", "<object", "<embed", "<link", "<meta",
-		},
-		pathTraversalPatterns: []string{
-			"../", "..\\", "%2e%2e%2f", "%2e%2e%5c",
-			"..%2f", "..%5c", "%252e%252e%252f",
-		},
-		logger: logger,
-	}, nil
-}
-
-// ValidateToken validates JWT tokens and similar token strings
-func (iv *InputValidator) ValidateToken(token string) ValidationResult {
-	result := ValidationResult{IsValid: true, Errors: []string{}, Warnings: []string{}}
-
-	// Check for empty token
-	if token == "" {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "token cannot be empty")
-		return result
-	}
-
-	// Check length limits
-	if len(token) > iv.maxTokenLength {
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("token length %d exceeds maximum %d", len(token), iv.maxTokenLength))
-		return result
-	}
-
-	// Check for minimum reasonable length
-	if len(token) < 10 {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "token is too short to be valid")
-		return result
-	}
-
-	// Check for valid JWT structure (3 parts separated by dots)
-	parts := strings.Split(token, ".")
-	if len(parts) != 3 {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "token does not have valid JWT structure (expected 3 parts)")
-		return result
-	}
-
-	// Validate each part is base64url encoded
-	for i, part := range parts {
-		if !iv.isValidBase64URL(part) {
-			result.IsValid = false
-			result.Errors = append(result.Errors, fmt.Sprintf("token part %d is not valid base64url", i+1))
-			return result
-		}
-	}
-
-	// Check for suspicious patterns
-	if risk := iv.detectSecurityRisk(token); risk != "" {
-		result.SecurityRisk = risk
-		result.Warnings = append(result.Warnings, fmt.Sprintf("potential security risk detected: %s", risk))
-	}
-
-	// Check for null bytes and control characters
-	if iv.containsNullBytes(token) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "token contains null bytes")
-		return result
-	}
-
-	if iv.containsControlCharacters(token) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "token contains control characters")
-		return result
-	}
-
-	// Validate UTF-8 encoding
-	if !utf8.ValidString(token) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "token contains invalid UTF-8 sequences")
-		return result
-	}
-
-	result.SanitizedValue = token
-	return result
-}
-
-// ValidateEmail validates email addresses
-func (iv *InputValidator) ValidateEmail(email string) ValidationResult {
-	result := ValidationResult{IsValid: true, Errors: []string{}, Warnings: []string{}}
-
-	// Check for empty email
-	if email == "" {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "email cannot be empty")
-		return result
-	}
-
-	// Check length limits
-	if len(email) > iv.maxEmailLength {
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("email length %d exceeds maximum %d", len(email), iv.maxEmailLength))
-		return result
-	}
-
-	// Sanitize email (trim whitespace, convert to lowercase)
-	sanitized := strings.TrimSpace(strings.ToLower(email))
-
-	// Check regex pattern
-	if !iv.emailRegex.MatchString(sanitized) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "email format is invalid")
-		return result
-	}
-
-	// Check for suspicious patterns
-	if risk := iv.detectSecurityRisk(sanitized); risk != "" {
-		result.SecurityRisk = risk
-		result.Warnings = append(result.Warnings, fmt.Sprintf("potential security risk detected: %s", risk))
-	}
-
-	// Additional email-specific validations
-	parts := strings.Split(sanitized, "@")
-	if len(parts) != 2 {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "email must contain exactly one @ symbol")
-		return result
-	}
-
-	localPart, domain := parts[0], parts[1]
-
-	// Validate local part
-	if len(localPart) == 0 || len(localPart) > 64 {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "email local part length is invalid")
-		return result
-	}
-
-	// Validate domain
-	if len(domain) == 0 || len(domain) > 253 {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "email domain length is invalid")
-		return result
-	}
-
-	// Check for consecutive dots
-	if strings.Contains(sanitized, "..") {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "email contains consecutive dots")
-		return result
-	}
-
-	result.SanitizedValue = sanitized
-	return result
-}
-
-// ValidateURL validates URLs
-func (iv *InputValidator) ValidateURL(urlStr string) ValidationResult {
-	result := ValidationResult{IsValid: true, Errors: []string{}, Warnings: []string{}}
-
-	// Check for empty URL
-	if urlStr == "" {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "URL cannot be empty")
-		return result
-	}
-
-	// Check length limits
-	if len(urlStr) > iv.maxURLLength {
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("URL length %d exceeds maximum %d", len(urlStr), iv.maxURLLength))
-		return result
-	}
-
-	// Sanitize URL (trim whitespace)
-	sanitized := strings.TrimSpace(urlStr)
-
-	// Parse URL
-	parsedURL, err := url.Parse(sanitized)
-	if err != nil {
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("URL parsing failed: %v", err))
-		return result
-	}
-
-	// Check scheme
-	if parsedURL.Scheme != "https" && parsedURL.Scheme != "http" {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "URL scheme must be http or https")
-		return result
-	}
-
-	// Prefer HTTPS
-	if parsedURL.Scheme == "http" {
-		result.Warnings = append(result.Warnings, "HTTP URLs are less secure than HTTPS")
-	}
-
-	// Check host
-	if parsedURL.Host == "" {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "URL must have a valid host")
-		return result
-	}
-
-	// Check for localhost or private IPs for security
-	// Allow localhost for HTTPS (development/testing) but warn about it
-	hostname := strings.ToLower(parsedURL.Hostname())
-	if hostname == "localhost" || hostname == "127.0.0.1" || hostname == "::1" {
-		if parsedURL.Scheme == "https" {
-			// Allow HTTPS localhost for development but warn
-			result.Warnings = append(result.Warnings, "localhost URLs should only be used for development/testing")
-		} else {
-			// Reject non-HTTPS localhost for security
-			result.IsValid = false
-			result.Errors = append(result.Errors, "non-HTTPS localhost URLs are not allowed for security")
-			return result
-		}
-	}
-
-	// Check for private IP ranges (RFC 1918) - skip if allowPrivateIPAddresses is enabled
-	if !iv.allowPrivateIPAddresses {
-		if strings.HasPrefix(hostname, "10.") ||
-			strings.HasPrefix(hostname, "192.168.") ||
-			strings.HasPrefix(hostname, "172.") {
-			// For 172.x check if it's in the 172.16.0.0/12 range
-			if strings.HasPrefix(hostname, "172.") {
-				parts := strings.Split(hostname, ".")
-				if len(parts) >= 2 {
-					if second, err := strconv.Atoi(parts[1]); err == nil && second >= 16 && second <= 31 {
-						result.IsValid = false
-						result.Errors = append(result.Errors, "private IP URLs are not allowed for security")
-						return result
-					}
-				}
-			} else {
-				result.IsValid = false
-				result.Errors = append(result.Errors, "private IP URLs are not allowed for security")
-				return result
-			}
-		}
-	}
-
-	// Check for suspicious patterns
-	if risk := iv.detectSecurityRisk(sanitized); risk != "" {
-		result.SecurityRisk = risk
-		result.Warnings = append(result.Warnings, fmt.Sprintf("potential security risk detected: %s", risk))
-	}
-
-	// Check for path traversal attempts
-	if iv.containsPathTraversal(sanitized) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "URL contains path traversal patterns")
-		return result
-	}
-
-	result.SanitizedValue = sanitized
-	return result
-}
-
-// ValidateUsername validates usernames
-func (iv *InputValidator) ValidateUsername(username string) ValidationResult {
-	result := ValidationResult{IsValid: true, Errors: []string{}, Warnings: []string{}}
-
-	// Check for empty username
-	if username == "" {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "username cannot be empty")
-		return result
-	}
-
-	// Check length limits
-	if len(username) > iv.maxUsernameLength {
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("username length %d exceeds maximum %d", len(username), iv.maxUsernameLength))
-		return result
-	}
-
-	// Check minimum length
-	if len(username) < 2 {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "username must be at least 2 characters long")
-		return result
-	}
-
-	// Sanitize username (trim whitespace)
-	sanitized := strings.TrimSpace(username)
-
-	// Check regex pattern
-	if !iv.usernameRegex.MatchString(sanitized) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "username contains invalid characters (only letters, numbers, dots, underscores, and hyphens allowed)")
-		return result
-	}
-
-	// Check for suspicious patterns
-	if risk := iv.detectSecurityRisk(sanitized); risk != "" {
-		result.SecurityRisk = risk
-		result.Warnings = append(result.Warnings, fmt.Sprintf("potential security risk detected: %s", risk))
-	}
-
-	result.SanitizedValue = sanitized
-	return result
-}
-
-// ValidateClaim validates individual JWT claims
-func (iv *InputValidator) ValidateClaim(claimName, claimValue string) ValidationResult {
-	result := ValidationResult{IsValid: true, Errors: []string{}, Warnings: []string{}}
-
-	// Check claim name
-	if claimName == "" {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "claim name cannot be empty")
-		return result
-	}
-
-	// Check claim value length
-	if len(claimValue) > iv.maxClaimLength {
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("claim value length %d exceeds maximum %d", len(claimValue), iv.maxClaimLength))
-		return result
-	}
-
-	// Check for null bytes and control characters
-	if iv.containsNullBytes(claimValue) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "claim value contains null bytes")
-		return result
-	}
-
-	if iv.containsControlCharacters(claimValue) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "claim value contains control characters")
-		return result
-	}
-
-	// Validate UTF-8 encoding
-	if !utf8.ValidString(claimValue) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "claim value contains invalid UTF-8 sequences")
-		return result
-	}
-
-	// Check for suspicious patterns
-	if risk := iv.detectSecurityRisk(claimValue); risk != "" {
-		result.SecurityRisk = risk
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("potential security risk detected: %s", risk))
-		return result
-	}
-
-	// Check for excessive unicode (emojis and special characters)
-	unicodeCount := 0
-	runeCount := 0
-	for _, r := range claimValue {
-		runeCount++
-		if r > 127 { // Non-ASCII character
-			unicodeCount++
-		}
-	}
-	// If more than 50% of the characters are unicode, consider it suspicious
-	if runeCount > 0 && unicodeCount > runeCount/2 {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "claim value contains excessive unicode characters")
-		return result
-	}
-
-	// Specific validations based on claim name
-	switch claimName {
-	case "email":
-		emailResult := iv.ValidateEmail(claimValue)
-		if !emailResult.IsValid {
-			result.IsValid = false
-			result.Errors = append(result.Errors, emailResult.Errors...)
-		}
-		result.Warnings = append(result.Warnings, emailResult.Warnings...)
-		result.SanitizedValue = emailResult.SanitizedValue
-
-	case "iss", "aud":
-		urlResult := iv.ValidateURL(claimValue)
-		if !urlResult.IsValid {
-			// For issuer/audience, we're more lenient - just warn
-			result.Warnings = append(result.Warnings, fmt.Sprintf("%s claim is not a valid URL: %v", claimName, urlResult.Errors))
-		}
-		result.SanitizedValue = claimValue
-
-	case "preferred_username", "username":
-		usernameResult := iv.ValidateUsername(claimValue)
-		if !usernameResult.IsValid {
-			result.IsValid = false
-			result.Errors = append(result.Errors, usernameResult.Errors...)
-		}
-		result.Warnings = append(result.Warnings, usernameResult.Warnings...)
-		result.SanitizedValue = usernameResult.SanitizedValue
-
-	default:
-		// Generic string validation
-		result.SanitizedValue = strings.TrimSpace(claimValue)
-	}
-
-	return result
-}
-
-// ValidateHeader validates HTTP header values
-func (iv *InputValidator) ValidateHeader(headerName, headerValue string) ValidationResult {
-	result := ValidationResult{IsValid: true, Errors: []string{}, Warnings: []string{}}
-
-	// Check header name
-	if headerName == "" {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "header name cannot be empty")
-		return result
-	}
-
-	// Check for control characters in header name (including CRLF)
-	if iv.containsControlCharacters(headerName) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "header name contains control characters")
-		return result
-	}
-
-	// Check for CRLF injection in header name
-	if strings.Contains(headerName, "\r") || strings.Contains(headerName, "\n") {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "header name contains CRLF characters (potential header injection)")
-		return result
-	}
-
-	// Check header value length
-	if len(headerValue) > iv.maxHeaderLength {
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("header value length %d exceeds maximum %d", len(headerValue), iv.maxHeaderLength))
-		return result
-	}
-
-	// Check for null bytes and control characters (except allowed ones)
-	if iv.containsNullBytes(headerValue) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "header value contains null bytes")
-		return result
-	}
-
-	// Check for CRLF injection
-	if strings.Contains(headerValue, "\r") || strings.Contains(headerValue, "\n") {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "header value contains CRLF characters (potential header injection)")
-		return result
-	}
-
-	// Check for control characters in header value
-	if iv.containsControlCharacters(headerValue) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "header value contains control characters")
-		return result
-	}
-
-	// Validate UTF-8 encoding
-	if !utf8.ValidString(headerValue) {
-		result.IsValid = false
-		result.Errors = append(result.Errors, "header value contains invalid UTF-8 sequences")
-		return result
-	}
-
-	// Check for suspicious patterns
-	if risk := iv.detectSecurityRisk(headerValue); risk != "" {
-		result.SecurityRisk = risk
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("potential security risk detected: %s", risk))
-		return result
-	}
-
-	result.SanitizedValue = strings.TrimSpace(headerValue)
-	return result
-}
-
-// isValidBase64URL checks if a string is valid base64url encoding
-func (iv *InputValidator) isValidBase64URL(s string) bool {
-	// Base64url uses A-Z, a-z, 0-9, -, _ and no padding
-	for _, r := range s {
-		if !((r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') ||
-			(r >= '0' && r <= '9') || r == '-' || r == '_') {
-			return false
-		}
-	}
-	return true
-}
-
-// containsNullBytes checks if a string contains null bytes
-func (iv *InputValidator) containsNullBytes(s string) bool {
-	return strings.Contains(s, "\x00")
-}
-
-// containsControlCharacters checks if a string contains control characters
-func (iv *InputValidator) containsControlCharacters(s string) bool {
-	for _, r := range s {
-		if unicode.IsControl(r) && r != '\t' && r != '\n' && r != '\r' {
-			return true
-		}
-	}
-	return false
-}
-
-// containsPathTraversal checks for path traversal patterns
-func (iv *InputValidator) containsPathTraversal(s string) bool {
-	lowerS := strings.ToLower(s)
-	for _, pattern := range iv.pathTraversalPatterns {
-		if strings.Contains(lowerS, pattern) {
-			return true
-		}
-	}
-	return false
-}
-
-// detectSecurityRisk detects potential security risks in input
-func (iv *InputValidator) detectSecurityRisk(input string) string {
-	lowerInput := strings.ToLower(input)
-
-	// Check for SQL injection patterns
-	for _, pattern := range iv.sqlInjectionPatterns {
-		if strings.Contains(lowerInput, pattern) {
-			return "sql_injection"
-		}
-	}
-
-	// Check for XSS patterns
-	for _, pattern := range iv.xssPatterns {
-		if strings.Contains(lowerInput, pattern) {
-			return "xss"
-		}
-	}
-
-	// Check for path traversal
-	if iv.containsPathTraversal(input) {
-		return "path_traversal"
-	}
-
-	// Check for excessive length (potential DoS)
-	if len(input) > 10000 {
-		return "excessive_length"
-	}
-
-	// Check for suspicious character patterns
-	if iv.containsNullBytes(input) {
-		return "null_bytes"
-	}
-
-	// Check for binary data patterns
-	nonPrintableCount := 0
-	for _, r := range input {
-		if !unicode.IsPrint(r) && !unicode.IsSpace(r) {
-			nonPrintableCount++
-		}
-	}
-	if nonPrintableCount > len(input)/10 { // More than 10% non-printable
-		return "binary_data"
-	}
-
-	return ""
-}
-
-// SanitizeInput provides general input sanitization
-func (iv *InputValidator) SanitizeInput(input string, maxLength int) string {
-	// Trim whitespace
-	sanitized := strings.TrimSpace(input)
-
-	// Truncate if too long
-	if len(sanitized) > maxLength {
-		sanitized = sanitized[:maxLength]
-	}
-
-	// Remove null bytes
-	sanitized = strings.ReplaceAll(sanitized, "\x00", "")
-
-	// Remove other control characters except tab, newline, carriage return
-	var result strings.Builder
-	for _, r := range sanitized {
-		if !unicode.IsControl(r) || r == '\t' || r == '\n' || r == '\r' {
-			result.WriteRune(r)
-		}
-	}
-
-	return result.String()
-}
-
-// ValidateBoundaryValues validates numeric boundary values
-func (iv *InputValidator) ValidateBoundaryValues(value interface{}, min, max int64) ValidationResult {
-	result := ValidationResult{IsValid: true, Errors: []string{}, Warnings: []string{}}
-
-	var numValue int64
-
-	switch v := value.(type) {
-	case int:
-		numValue = int64(v)
-	case int32:
-		numValue = int64(v)
-	case int64:
-		numValue = v
-	case float64:
-		numValue = int64(v)
-		if float64(numValue) != v {
-			result.Warnings = append(result.Warnings, "floating point value truncated to integer")
-		}
-	default:
-		result.IsValid = false
-		result.Errors = append(result.Errors, "value is not a numeric type")
-		return result
-	}
-
-	if numValue < min {
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("value %d is below minimum %d", numValue, min))
-	}
-
-	if numValue > max {
-		result.IsValid = false
-		result.Errors = append(result.Errors, fmt.Sprintf("value %d exceeds maximum %d", numValue, max))
-	}
-
-	return result
-}

input_validation_test.go

@@ -1,895 +0,0 @@
-package traefikoidc
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestInputValidator(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	logger := NewLogger("debug")
-	validator, err := NewInputValidator(config, logger)
-	if err != nil {
-		t.Fatalf("Failed to create validator: %v", err)
-	}
-
-	t.Run("Valid token validation", func(t *testing.T) {
-		validToken := "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.EkN-DOsnsuRjRO6BxXemmJDm3HbxrbRzXglbN2S4sOkopdU4IsDxTI8jO19W_A4K8ZPJijNLis4EZsHeY559a4DFOd50_OqgHs3UjpMC6M6FNqI2J-I2NxrragtnDxGxdJUvDERDQVHzeNlVQiuqWDEeO_O-0KptafbfyuGqfQxH_6dp2_MeFpAc" // trufflehog:ignore
-
-		result := validator.ValidateToken(validToken)
-		if !result.IsValid {
-			t.Errorf("Expected valid token to pass validation, got errors: %v", result.Errors)
-		}
-	})
-
-	t.Run("Invalid token validation", func(t *testing.T) {
-		invalidTokens := []string{
-			"",              // Empty token
-			"invalid.token", // Invalid format
-			"a.b",           // Too few parts
-			"a.b.c.d",       // Too many parts
-		}
-
-		for _, token := range invalidTokens {
-			result := validator.ValidateToken(token)
-			if result.IsValid {
-				t.Errorf("Expected invalid token '%s' to fail validation", token)
-			}
-		}
-	})
-
-	t.Run("Valid email validation", func(t *testing.T) {
-		validEmails := []string{
-			"[email protected]",
-			"[email protected]",
-			"[email protected]",
-		}
-
-		for _, email := range validEmails {
-			result := validator.ValidateEmail(email)
-			if !result.IsValid {
-				t.Errorf("Expected valid email '%s' to pass validation, got errors: %v", email, result.Errors)
-			}
-		}
-	})
-
-	t.Run("Invalid email validation", func(t *testing.T) {
-		invalidEmails := []string{
-			"",                        // Empty
-			"invalid",                 // No @ symbol
-			"@domain.com",             // No local part
-			"user@",                   // No domain
-			"user@domain",             // No TLD
-			"[email protected]", // Double dots
-		}
-
-		for _, email := range invalidEmails {
-			result := validator.ValidateEmail(email)
-			if result.IsValid {
-				t.Errorf("Expected invalid email '%s' to fail validation", email)
-			}
-		}
-	})
-
-	t.Run("Valid URL validation", func(t *testing.T) {
-		validURLs := []string{
-			"https://example.com",
-			"https://sub.domain.com/path",
-			"https://localhost:8080/callback",
-		}
-
-		for _, url := range validURLs {
-			result := validator.ValidateURL(url)
-			if !result.IsValid {
-				t.Errorf("Expected valid URL '%s' to pass validation, got errors: %v", url, result.Errors)
-			}
-		}
-	})
-
-	t.Run("Invalid URL validation", func(t *testing.T) {
-		invalidURLs := []string{
-			"",                  // Empty
-			"not-a-url",         // Invalid format
-			"ftp://example.com", // Wrong scheme
-			"https://",          // No host
-		}
-
-		for _, url := range invalidURLs {
-			result := validator.ValidateURL(url)
-			if result.IsValid {
-				t.Errorf("Expected invalid URL '%s' to fail validation", url)
-			}
-		}
-	})
-
-	t.Run("Valid username validation", func(t *testing.T) {
-		validUsernames := []string{
-			"user123",
-			"test_user",
-			"user-name",
-		}
-
-		for _, username := range validUsernames {
-			result := validator.ValidateUsername(username)
-			if !result.IsValid {
-				t.Errorf("Expected valid username '%s' to pass validation, got errors: %v", username, result.Errors)
-			}
-		}
-	})
-
-	t.Run("Invalid username validation", func(t *testing.T) {
-		invalidUsernames := []string{
-			"",                       // Empty
-			"a",                      // Too short
-			strings.Repeat("a", 100), // Too long
-			"user name",              // Spaces
-		}
-
-		for _, username := range invalidUsernames {
-			result := validator.ValidateUsername(username)
-			if result.IsValid {
-				t.Errorf("Expected invalid username '%s' to fail validation", username)
-			}
-		}
-	})
-
-	t.Run("Valid claim validation", func(t *testing.T) {
-		validClaims := map[string]string{
-			"sub":   "user123",
-			"email": "[email protected]",
-			"name":  "John Doe",
-		}
-
-		for key, value := range validClaims {
-			result := validator.ValidateClaim(key, value)
-			if !result.IsValid {
-				t.Errorf("Expected valid claim '%s'='%s' to pass validation, got errors: %v", key, value, result.Errors)
-			}
-		}
-	})
-
-	t.Run("Invalid claim validation", func(t *testing.T) {
-		invalidClaims := map[string]string{
-			"":         "value",                    // Empty key
-			"long_key": strings.Repeat("a", 10000), // Too long value
-		}
-
-		for key, value := range invalidClaims {
-			result := validator.ValidateClaim(key, value)
-			if result.IsValid {
-				t.Errorf("Expected invalid claim '%s'='%s' to fail validation", key, value)
-			}
-		}
-	})
-
-	t.Run("Valid header validation", func(t *testing.T) {
-		validHeaders := map[string]string{
-			"Authorization": "Bearer token123",
-			"Content-Type":  "application/json",
-			"X-Custom":      "custom-value",
-		}
-
-		for key, value := range validHeaders {
-			result := validator.ValidateHeader(key, value)
-			if !result.IsValid {
-				t.Errorf("Expected valid header '%s'='%s' to pass validation, got errors: %v", key, value, result.Errors)
-			}
-		}
-	})
-
-	t.Run("Invalid header validation", func(t *testing.T) {
-		invalidHeaders := map[string]string{
-			"":             "value",     // Empty key
-			"Invalid\nKey": "value",     // Control characters in key
-			"key":          "value\r\n", // Control characters in value
-		}
-
-		for key, value := range invalidHeaders {
-			result := validator.ValidateHeader(key, value)
-			if result.IsValid {
-				t.Errorf("Expected invalid header '%s'='%s' to fail validation", key, value)
-			}
-		}
-	})
-}
-
-func TestSanitizeInput(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	logger := NewLogger("debug")
-	validator, err := NewInputValidator(config, logger)
-	if err != nil {
-		t.Fatalf("Failed to create validator: %v", err)
-	}
-
-	tests := []struct {
-		name     string
-		input    string
-		expected string
-		maxLen   int
-	}{
-		{
-			name:     "Normal text",
-			input:    "Hello World",
-			maxLen:   100,
-			expected: "Hello World",
-		},
-		{
-			name:     "Control characters",
-			input:    "text\x00with\x01control\x02chars",
-			maxLen:   100,
-			expected: "textwithcontrolchars",
-		},
-		{
-			name:     "Truncation",
-			input:    "very long text",
-			maxLen:   5,
-			expected: "very ",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.SanitizeInput(tt.input, tt.maxLen)
-			if result != tt.expected {
-				t.Errorf("Expected sanitized input '%s', got '%s'", tt.expected, result)
-			}
-		})
-	}
-}
-
-func TestValidateBoundaryValues(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	logger := NewLogger("debug")
-	validator, err := NewInputValidator(config, logger)
-	if err != nil {
-		t.Fatalf("Failed to create validator: %v", err)
-	}
-
-	t.Run("Valid boundary values", func(t *testing.T) {
-		validValues := []interface{}{
-			int(50),
-			int64(100),
-			float64(75.5),
-		}
-
-		for _, value := range validValues {
-			result := validator.ValidateBoundaryValues(value, 1, 1000)
-			if !result.IsValid {
-				t.Errorf("Expected valid boundary value %v to pass validation, got errors: %v", value, result.Errors)
-			}
-		}
-	})
-
-	t.Run("Invalid boundary values", func(t *testing.T) {
-		invalidValues := []interface{}{
-			int(-1),
-			int64(2000),
-			"not a number",
-		}
-
-		for _, value := range invalidValues {
-			result := validator.ValidateBoundaryValues(value, 1, 1000)
-			if result.IsValid {
-				t.Errorf("Expected invalid boundary value %v to fail validation", value)
-			}
-		}
-	})
-}
-
-func TestDefaultInputValidationConfig(t *testing.T) {
-	config := DefaultInputValidationConfig()
-
-	if config.MaxTokenLength <= 0 {
-		t.Error("Expected positive MaxTokenLength")
-	}
-	if config.MaxEmailLength <= 0 {
-		t.Error("Expected positive MaxEmailLength")
-	}
-	if config.MaxUsernameLength <= 0 {
-		t.Error("Expected positive MaxUsernameLength")
-	}
-	if config.MaxClaimLength <= 0 {
-		t.Error("Expected positive MaxClaimLength")
-	}
-	if config.MaxHeaderLength <= 0 {
-		t.Error("Expected positive MaxHeaderLength")
-	}
-	if !config.StrictMode {
-		t.Error("Expected StrictMode to be true by default")
-	}
-}
-
-func TestInputValidationHelpers(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	logger := NewLogger("debug")
-	validator, err := NewInputValidator(config, logger)
-	if err != nil {
-		t.Fatalf("Failed to create validator: %v", err)
-	}
-
-	t.Run("isValidBase64URL", func(t *testing.T) {
-		validBase64URL := "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9"
-		if !validator.isValidBase64URL(validBase64URL) {
-			t.Error("Expected valid base64url to be recognized")
-		}
-
-		invalidBase64URL := "invalid+base64/with+padding="
-		if validator.isValidBase64URL(invalidBase64URL) {
-			t.Error("Expected invalid base64url to be rejected")
-		}
-	})
-
-	t.Run("containsNullBytes", func(t *testing.T) {
-		withNull := "text\x00with\x00null"
-		if !validator.containsNullBytes(withNull) {
-			t.Error("Expected string with null bytes to be detected")
-		}
-
-		withoutNull := "normal text"
-		if validator.containsNullBytes(withoutNull) {
-			t.Error("Expected string without null bytes to pass")
-		}
-	})
-
-	t.Run("containsControlCharacters", func(t *testing.T) {
-		withControl := "text\x01with\x02control"
-		if !validator.containsControlCharacters(withControl) {
-			t.Error("Expected string with control characters to be detected")
-		}
-
-		withoutControl := "normal text"
-		if validator.containsControlCharacters(withoutControl) {
-			t.Error("Expected string without control characters to pass")
-		}
-	})
-
-	t.Run("containsPathTraversal", func(t *testing.T) {
-		withTraversal := "../../../etc/passwd"
-		if !validator.containsPathTraversal(withTraversal) {
-			t.Error("Expected path traversal to be detected")
-		}
-
-		normalPath := "/normal/path"
-		if validator.containsPathTraversal(normalPath) {
-			t.Error("Expected normal path to pass")
-		}
-	})
-
-	t.Run("detectSecurityRisk", func(t *testing.T) {
-		riskyInputs := []string{
-			"<script>alert('xss')</script>",
-			"'; DROP TABLE users; --",
-			"javascript:alert('xss')",
-		}
-
-		for _, input := range riskyInputs {
-			if validator.detectSecurityRisk(input) == "" {
-				t.Errorf("Expected security risk to be detected in: %s", input)
-			}
-		}
-
-		safeInput := "normal safe text"
-		if validator.detectSecurityRisk(safeInput) != "" {
-			t.Error("Expected safe input to pass security check")
-		}
-	})
-}
-
-func TestInputValidationEdgeCases(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	logger := NewLogger("debug")
-	validator, err := NewInputValidator(config, logger)
-	if err != nil {
-		t.Fatalf("Failed to create validator: %v", err)
-	}
-
-	t.Run("Empty inputs", func(t *testing.T) {
-		// Most validations should reject empty inputs
-		if result := validator.ValidateToken(""); result.IsValid {
-			t.Error("Expected empty token to be rejected")
-		}
-		if result := validator.ValidateEmail(""); result.IsValid {
-			t.Error("Expected empty email to be rejected")
-		}
-		if result := validator.ValidateURL(""); result.IsValid {
-			t.Error("Expected empty URL to be rejected")
-		}
-		if result := validator.ValidateUsername(""); result.IsValid {
-			t.Error("Expected empty username to be rejected")
-		}
-	})
-
-	t.Run("Very long inputs", func(t *testing.T) {
-		longString := strings.Repeat("a", 10000)
-
-		if result := validator.ValidateEmail(longString + "@domain.com"); result.IsValid {
-			t.Error("Expected very long email to be rejected")
-		}
-		if result := validator.ValidateUsername(longString); result.IsValid {
-			t.Error("Expected very long username to be rejected")
-		}
-	})
-
-	t.Run("Unicode handling", func(t *testing.T) {
-		unicodeEmail := "用户@example.com"
-		// Should handle unicode gracefully
-		validator.ValidateEmail(unicodeEmail) // Don't fail on unicode
-
-		unicodeUsername := "用户名"
-		validator.ValidateUsername(unicodeUsername) // Don't fail on unicode
-	})
-}
-
-// TestInputValidatorValidateToken tests comprehensive token validation
-func TestInputValidatorValidateToken(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	validator, _ := NewInputValidator(config, newNoOpLogger())
-
-	tests := []struct {
-		name        string
-		token       string
-		description string
-		expectValid bool
-	}{
-		{
-			name:        "ValidJWTToken",
-			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNTE2MjM5MDIyLCJpYXQiOjE1MTYyMzkwMjJ9.signature", // trufflehog:ignore
-			expectValid: true,
-			description: "Valid JWT token should pass validation",
-		},
-		{
-			name:        "InvalidOpaqueToken",
-			token:       "opaque_access_token_that_is_long_enough_to_pass",
-			expectValid: false,
-			description: "Opaque token (non-JWT) should fail validation",
-		},
-		{
-			name:        "EmptyToken",
-			token:       "",
-			expectValid: false,
-			description: "Empty token should fail validation",
-		},
-		{
-			name:        "TokenWithNullBytes",
-			token:       "token_with_null\x00byte",
-			expectValid: false,
-			description: "Token with null bytes should fail validation",
-		},
-		{
-			name:        "TokenTooLong",
-			token:       strings.Repeat("a", config.MaxTokenLength+1),
-			expectValid: false,
-			description: "Token exceeding max length should fail validation",
-		},
-		{
-			name:        "TokenWithControlCharacters",
-			token:       "token_with_control\x01character",
-			expectValid: false,
-			description: "Token with control characters should fail validation",
-		},
-		{
-			name:        "TokenWithHighUnicode",
-			token:       "token_with_unicode_\uffff",
-			expectValid: false,
-			description: "Token with high unicode characters should fail validation",
-		},
-		{
-			name:        "MaliciousJWTWithExtraData",
-			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.sig.malicious_extra", // trufflehog:ignore
-			expectValid: false,
-			description: "JWT with extra malicious data should fail validation",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.ValidateToken(tt.token)
-
-			if result.IsValid != tt.expectValid {
-				t.Errorf("Expected valid=%v, got %v. %s", tt.expectValid, result.IsValid, tt.description)
-			}
-		})
-	}
-}
-
-// TestInputValidatorValidateEmail tests email validation edge cases
-func TestInputValidatorValidateEmail(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	validator, _ := NewInputValidator(config, newNoOpLogger())
-
-	tests := []struct {
-		name        string
-		email       string
-		description string
-		expectValid bool
-	}{
-		{
-			name:        "ValidEmail",
-			email:       "[email protected]",
-			expectValid: true,
-			description: "Valid email should pass validation",
-		},
-		{
-			name:        "ValidEmailWithSubdomain",
-			email:       "[email protected]",
-			expectValid: true,
-			description: "Valid email with subdomain should pass validation",
-		},
-		{
-			name:        "EmptyEmail",
-			email:       "",
-			expectValid: false,
-			description: "Empty email should fail validation",
-		},
-		{
-			name:        "EmailWithoutAtSign",
-			email:       "userexample.com",
-			expectValid: false,
-			description: "Email without @ sign should fail validation",
-		},
-		{
-			name:        "EmailWithNullBytes",
-			email:       "user@example\x00.com",
-			expectValid: false,
-			description: "Email with null bytes should fail validation",
-		},
-		{
-			name:        "EmailTooLong",
-			email:       strings.Repeat("a", config.MaxEmailLength-10) + "@example.com",
-			expectValid: false,
-			description: "Email exceeding max length should fail validation",
-		},
-		{
-			name:        "EmailWithControlCharacters",
-			email:       "user\[email protected]",
-			expectValid: false,
-			description: "Email with control characters should fail validation",
-		},
-		{
-			name:        "MaliciousEmailWithScriptTag",
-			email:       "user<script>@example.com",
-			expectValid: false,
-			description: "Email with script tag should fail validation",
-		},
-		{
-			name:        "EmailWithUnicodeCharacters",
-			email:       "üser@éxample.com",
-			expectValid: false,
-			description: "Email with unicode should fail basic validation",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.ValidateEmail(tt.email)
-
-			if result.IsValid != tt.expectValid {
-				t.Errorf("Expected valid=%v, got %v. %s", tt.expectValid, result.IsValid, tt.description)
-			}
-		})
-	}
-}
-
-// TestInputValidatorValidateURL tests URL validation with security focus
-func TestInputValidatorValidateURL(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	validator, _ := NewInputValidator(config, newNoOpLogger())
-
-	tests := []struct {
-		name        string
-		url         string
-		description string
-		expectValid bool
-	}{
-		{
-			name:        "ValidHTTPSURL",
-			url:         "https://example.com/path",
-			expectValid: true,
-			description: "Valid HTTPS URL should pass validation",
-		},
-		{
-			name:        "ValidHTTPURL",
-			url:         "http://example.com/path",
-			expectValid: true,
-			description: "Valid HTTP URL should pass validation",
-		},
-		{
-			name:        "EmptyURL",
-			url:         "",
-			expectValid: false,
-			description: "Empty URL should fail validation",
-		},
-		{
-			name:        "InvalidScheme",
-			url:         "ftp://example.com",
-			expectValid: false,
-			description: "URL with invalid scheme should fail validation",
-		},
-		{
-			name:        "URLWithNullBytes",
-			url:         "https://example\x00.com",
-			expectValid: false,
-			description: "URL with null bytes should fail validation",
-		},
-		{
-			name:        "URLTooLong",
-			url:         "https://" + strings.Repeat("a", config.MaxURLLength) + ".com",
-			expectValid: false,
-			description: "URL exceeding max length should fail validation",
-		},
-		{
-			name:        "MalformedURL",
-			url:         "https://",
-			expectValid: false,
-			description: "Malformed URL should fail validation",
-		},
-		{
-			name:        "HTTPSLocalhostURL",
-			url:         "https://localhost:8080/path",
-			expectValid: true,
-			description: "HTTPS localhost URL should be allowed for development",
-		},
-		{
-			name:        "HTTPLocalhostURL",
-			url:         "http://localhost:8080/path",
-			expectValid: false,
-			description: "HTTP localhost URL should fail validation for security",
-		},
-		{
-			name:        "PrivateIPURL",
-			url:         "https://192.168.1.1/path",
-			expectValid: false,
-			description: "Private IP URL should fail validation for security",
-		},
-		{
-			name:        "JavaScriptURL",
-			url:         "javascript:alert(1)",
-			expectValid: false,
-			description: "JavaScript URL should fail validation",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.ValidateURL(tt.url)
-
-			if result.IsValid != tt.expectValid {
-				t.Errorf("Expected valid=%v, got %v. %s", tt.expectValid, result.IsValid, tt.description)
-			}
-		})
-	}
-}
-
-// TestInputValidatorValidateClaim tests claim validation with security focus
-func TestInputValidatorValidateClaim(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	validator, _ := NewInputValidator(config, newNoOpLogger())
-
-	tests := []struct {
-		name        string
-		claimName   string
-		claimValue  string
-		description string
-		expectValid bool
-	}{
-		{
-			name:        "ValidStringClaim",
-			claimName:   "email",
-			claimValue:  "[email protected]",
-			expectValid: true,
-			description: "Valid string claim should pass validation",
-		},
-		{
-			name:        "ValidNumberClaim",
-			claimName:   "exp",
-			claimValue:  "1516239022",
-			expectValid: true,
-			description: "Valid number claim should pass validation",
-		},
-		{
-			name:        "EmptyClaimName",
-			claimName:   "",
-			claimValue:  "value",
-			expectValid: false,
-			description: "Empty claim name should fail validation",
-		},
-		{
-			name:        "ClaimWithNullBytes",
-			claimName:   "test",
-			claimValue:  "value\x00with_null",
-			expectValid: false,
-			description: "Claim with null bytes should fail validation",
-		},
-		{
-			name:        "ClaimValueTooLong",
-			claimName:   "test",
-			claimValue:  strings.Repeat("a", config.MaxClaimLength+1),
-			expectValid: false,
-			description: "Claim value exceeding max length should fail validation",
-		},
-		{
-			name:        "ClaimWithControlCharacters",
-			claimName:   "test",
-			claimValue:  "value\x01with_control",
-			expectValid: false,
-			description: "Claim with control characters should fail validation",
-		},
-		{
-			name:        "MaliciousClaimWithHTML",
-			claimName:   "test",
-			claimValue:  "<script>alert('xss')</script>",
-			expectValid: false,
-			description: "Claim with HTML/script should fail validation",
-		},
-		{
-			name:        "ClaimWithExcessiveUnicode",
-			claimName:   "test",
-			claimValue:  strings.Repeat("🚀", 100), // Many unicode chars
-			expectValid: false,
-			description: "Claim with excessive unicode should fail validation",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.ValidateClaim(tt.claimName, tt.claimValue)
-
-			if result.IsValid != tt.expectValid {
-				t.Errorf("Expected valid=%v, got %v. %s", tt.expectValid, result.IsValid, tt.description)
-			}
-		})
-	}
-}
-
-// TestInputValidatorValidateHeader tests HTTP header validation
-func TestInputValidatorValidateHeader(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	validator, _ := NewInputValidator(config, newNoOpLogger())
-
-	tests := []struct {
-		name        string
-		headerName  string
-		headerValue string
-		description string
-		expectValid bool
-	}{
-		{
-			name:        "ValidHeader",
-			headerName:  "Authorization",
-			headerValue: "Bearer token123",
-			expectValid: true,
-			description: "Valid header should pass validation",
-		},
-		{
-			name:        "ValidContentType",
-			headerName:  "Content-Type",
-			headerValue: "application/json",
-			expectValid: true,
-			description: "Valid content type header should pass validation",
-		},
-		{
-			name:        "EmptyHeaderName",
-			headerName:  "",
-			headerValue: "value",
-			expectValid: false,
-			description: "Empty header name should fail validation",
-		},
-		{
-			name:        "HeaderWithNullBytes",
-			headerName:  "test",
-			headerValue: "value\x00with_null",
-			expectValid: false,
-			description: "Header with null bytes should fail validation",
-		},
-		{
-			name:        "HeaderValueTooLong",
-			headerName:  "test",
-			headerValue: strings.Repeat("a", config.MaxHeaderLength+1),
-			expectValid: false,
-			description: "Header value exceeding max length should fail validation",
-		},
-		{
-			name:        "HeaderWithCRLF",
-			headerName:  "test",
-			headerValue: "value\r\nMalicious: header",
-			expectValid: false,
-			description: "Header with CRLF should fail validation to prevent injection",
-		},
-		{
-			name:        "HeaderWithControlCharacters",
-			headerName:  "test",
-			headerValue: "value\x01with_control",
-			expectValid: false,
-			description: "Header with control characters should fail validation",
-		},
-		{
-			name:        "MaliciousHeaderWithHTML",
-			headerName:  "test",
-			headerValue: "<script>alert('xss')</script>",
-			expectValid: false,
-			description: "Header with HTML/script should fail validation",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.ValidateHeader(tt.headerName, tt.headerValue)
-
-			if result.IsValid != tt.expectValid {
-				t.Errorf("Expected valid=%v, got %v. %s", tt.expectValid, result.IsValid, tt.description)
-			}
-		})
-	}
-}
-
-// TestInputValidatorValidateUsername tests username validation
-func TestInputValidatorValidateUsername(t *testing.T) {
-	config := DefaultInputValidationConfig()
-	validator, _ := NewInputValidator(config, newNoOpLogger())
-
-	tests := []struct {
-		name        string
-		username    string
-		description string
-		expectValid bool
-	}{
-		{
-			name:        "ValidUsername",
-			username:    "john_doe",
-			expectValid: true,
-			description: "Valid username should pass validation",
-		},
-		{
-			name:        "ValidUsernameWithNumbers",
-			username:    "user123",
-			expectValid: true,
-			description: "Valid username with numbers should pass validation",
-		},
-		{
-			name:        "EmptyUsername",
-			username:    "",
-			expectValid: false,
-			description: "Empty username should fail validation",
-		},
-		{
-			name:        "UsernameWithNullBytes",
-			username:    "user\x00name",
-			expectValid: false,
-			description: "Username with null bytes should fail validation",
-		},
-		{
-			name:        "UsernameTooLong",
-			username:    strings.Repeat("a", config.MaxUsernameLength+1),
-			expectValid: false,
-			description: "Username exceeding max length should fail validation",
-		},
-		{
-			name:        "UsernameWithSpecialChars",
-			username:    "user@name",
-			expectValid: false,
-			description: "Username with special characters should fail validation",
-		},
-		{
-			name:        "UsernameWithSpaces",
-			username:    "user name",
-			expectValid: false,
-			description: "Username with spaces should fail validation",
-		},
-		{
-			name:        "UsernameWithControlCharacters",
-			username:    "user\x01name",
-			expectValid: false,
-			description: "Username with control characters should fail validation",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.ValidateUsername(tt.username)
-
-			if result.IsValid != tt.expectValid {
-				t.Errorf("Expected valid=%v, got %v. %s", tt.expectValid, result.IsValid, tt.description)
-			}
-		})
-	}
-}

internal/cache/backends/config.go

@@ -6,14 +6,10 @@ import "time"
 type BackendType string
 
 const (
-	BackendTypeMemory BackendType = "memory"
-	BackendTypeRedis  BackendType = "redis"
-	BackendTypeHybrid BackendType = "hybrid"
+	BackendTypeRedis BackendType = "redis"
 
-	// Aliases for backward compatibility
-	TypeMemory BackendType = "memory"
-	TypeRedis  BackendType = "redis"
-	TypeHybrid BackendType = "hybrid"
+	// TypeRedis is an alias for backward compatibility
+	TypeRedis BackendType = "redis"
 )
 
 // Config provides common configuration for cache backends
@@ -39,17 +35,6 @@ type Config struct {
 	TLSSkipVerify        bool
 }
 
-// DefaultConfig returns a default configuration for in-memory caching
-func DefaultConfig() *Config {
-	return &Config{
-		Type:            BackendTypeMemory,
-		MaxSize:         1000,
-		MaxMemoryBytes:  50 * 1024 * 1024, // 50MB
-		CleanupInterval: 5 * time.Minute,
-		EnableMetrics:   true,
-	}
-}
-
 // DefaultRedisConfig returns a default configuration for Redis caching
 func DefaultRedisConfig(addr string) *Config {
 	return &Config{
@@ -64,19 +49,3 @@ func DefaultRedisConfig(addr string) *Config {
 		EnableMetrics:        true,
 	}
 }
-
-// DefaultHybridConfig returns a default configuration for hybrid caching
-func DefaultHybridConfig(redisAddr string) *Config {
-	return &Config{
-		Type: BackendTypeHybrid,
-		L1Config: &Config{
-			Type:            BackendTypeMemory,
-			MaxSize:         500,
-			MaxMemoryBytes:  10 * 1024 * 1024, // 10MB for L1
-			CleanupInterval: 1 * time.Minute,
-		},
-		L2Config:      DefaultRedisConfig(redisAddr),
-		AsyncWrites:   true,
-		EnableMetrics: true,
-	}
-}

internal/cache/backends/config_test.go

@@ -1,59 +0,0 @@
-//go:build !yaegi
-
-package backends
-
-import (
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// TestDefaultHybridConfig verifies the default hybrid configuration
-func TestDefaultHybridConfig(t *testing.T) {
-	redisAddr := "localhost:6379"
-
-	config := DefaultHybridConfig(redisAddr)
-
-	require.NotNil(t, config)
-
-	// Verify top-level config
-	assert.Equal(t, BackendTypeHybrid, config.Type)
-	assert.True(t, config.AsyncWrites)
-	assert.True(t, config.EnableMetrics)
-
-	// Verify L1 (memory) config
-	require.NotNil(t, config.L1Config)
-	assert.Equal(t, BackendTypeMemory, config.L1Config.Type)
-	assert.Equal(t, 500, config.L1Config.MaxSize)
-	assert.Equal(t, int64(10*1024*1024), config.L1Config.MaxMemoryBytes) // 10MB
-	assert.Equal(t, 1*time.Minute, config.L1Config.CleanupInterval)
-
-	// Verify L2 (Redis) config exists
-	require.NotNil(t, config.L2Config)
-	assert.Equal(t, BackendTypeRedis, config.L2Config.Type)
-}
-
-func TestDefaultHybridConfig_DifferentRedisAddr(t *testing.T) {
-	tests := []struct {
-		name      string
-		redisAddr string
-	}{
-		{"localhost", "localhost:6379"},
-		{"remote host", "redis.example.com:6379"},
-		{"IP address", "192.168.1.100:6379"},
-		{"custom port", "localhost:6380"},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			config := DefaultHybridConfig(tt.redisAddr)
-
-			require.NotNil(t, config)
-			assert.Equal(t, BackendTypeHybrid, config.Type)
-			assert.NotNil(t, config.L1Config)
-			assert.NotNil(t, config.L2Config)
-		})
-	}
-}

internal/cache/backends/errors.go

@@ -35,4 +35,21 @@ var (
 
 	// ErrDeserializationFailed is returned when deserialization fails
 	ErrDeserializationFailed = errors.New("deserialization failed")
+
+	// ErrSetNXUnsupported is returned by a CacheBackend wrapper's SetNX when
+	// the backend it wraps does not itself implement SetNX (FIX-17 round-2).
+	// Compared with == only: no errors.As, no fmt.Errorf %w — an interpreted
+	// value wrapped with %w loses its type under yaegi v0.16.1, and
+	// errors.As with an interpreted target type panics there.
+	ErrSetNXUnsupported = errors.New("cache backend does not support atomic SetNX")
+
+	// ErrSetNXAmbiguous is returned by RedisBackend.SetNX when the SET NX
+	// command was already written to the connection but its reply could not
+	// be read (timeout, EOF, connection reset): Redis may or may not have
+	// applied it. Unlike Set's idempotent SETEX/PSETEX, retrying SET NX
+	// blindly here would see the caller's own possible write and misreport
+	// a first-ever claim as already-claimed, so SetNX surfaces the
+	// ambiguity instead of guessing (FIX-17 round-2). Compared with == only,
+	// for the same yaegi reason as ErrSetNXUnsupported.
+	ErrSetNXAmbiguous = errors.New("SET NX outcome unknown: reply lost after the command was sent")
 )

internal/cache/backends/hybrid.go

@@ -1,732 +0,0 @@
-// Package backend provides cache backend implementations for the Traefik OIDC plugin.
-package backends
-
-import (
-	"context"
-	"fmt"
-	"log"
-	"sync"
-	"sync/atomic"
-	"time"
-)
-
-// HybridBackend implements a two-tier cache with L1 (memory) and L2 (Redis) backends
-// It provides automatic failover, async writes for non-critical data, and optimized read paths
-type HybridBackend struct {
-	lastL2Error         atomic.Value
-	secondary           CacheBackend
-	primary             CacheBackend
-	logger              Logger
-	ctx                 context.Context
-	syncWriteCacheTypes map[string]bool
-	asyncWriteBuffer    chan *asyncWriteItem
-	l1BackfillBuffer    chan *l1BackfillItem
-	cancel              context.CancelFunc
-	wg                  sync.WaitGroup
-	l1Hits              atomic.Int64
-	errors              atomic.Int64
-	l2Writes            atomic.Int64
-	l1Writes            atomic.Int64
-	misses              atomic.Int64
-	l2Hits              atomic.Int64
-	l1BackfillDrops     atomic.Int64
-	fallbackMode        atomic.Bool
-}
-
-// asyncWriteItem represents an async write operation
-type asyncWriteItem struct {
-	ctx   context.Context
-	key   string
-	value []byte
-	ttl   time.Duration
-}
-
-// l1BackfillItem represents a deferred write of an L2-resolved value back into
-// L1. Backfills run on a single bounded worker so a burst of L2 hits cannot
-// detonate the goroutine count (issue: ~1000% CPU under sustained polling).
-type l1BackfillItem struct {
-	key   string
-	value []byte
-	ttl   time.Duration
-}
-
-// Logger interface for structured logging
-type Logger interface {
-	Debugf(format string, args ...interface{})
-	Infof(format string, args ...interface{})
-	Warnf(format string, args ...interface{})
-	Errorf(format string, args ...interface{})
-}
-
-// defaultLogger provides a basic logger implementation
-type defaultLogger struct {
-	*log.Logger
-}
-
-func (l *defaultLogger) Debugf(format string, args ...interface{}) {
-	l.Printf("[DEBUG] "+format, args...)
-}
-
-func (l *defaultLogger) Infof(format string, args ...interface{}) {
-	l.Printf("[INFO] "+format, args...)
-}
-
-func (l *defaultLogger) Warnf(format string, args ...interface{}) {
-	l.Printf("[WARN] "+format, args...)
-}
-
-func (l *defaultLogger) Errorf(format string, args ...interface{}) {
-	l.Printf("[ERROR] "+format, args...)
-}
-
-// HybridConfig provides configuration for the hybrid backend
-type HybridConfig struct {
-	Primary             CacheBackend
-	Secondary           CacheBackend
-	Logger              Logger
-	SyncWriteCacheTypes map[string]bool
-	AsyncBufferSize     int
-}
-
-// NewHybridBackend creates a new hybrid cache backend with L1 (memory) and L2 (Redis) tiers
-func NewHybridBackend(config *HybridConfig) (*HybridBackend, error) {
-	if config == nil {
-		return nil, fmt.Errorf("config is required")
-	}
-
-	if config.Primary == nil {
-		return nil, fmt.Errorf("primary (L1) backend is required")
-	}
-
-	if config.Secondary == nil {
-		return nil, fmt.Errorf("secondary (L2) backend is required")
-	}
-
-	if config.Logger == nil {
-		config.Logger = &defaultLogger{Logger: log.New(log.Writer(), "[HybridCache] ", log.LstdFlags)}
-	}
-
-	if config.AsyncBufferSize <= 0 {
-		config.AsyncBufferSize = 1000
-	}
-
-	// Default critical cache types that require synchronous writes
-	if config.SyncWriteCacheTypes == nil {
-		config.SyncWriteCacheTypes = map[string]bool{
-			"blacklist": true, // Token blacklist must be immediately consistent
-			"token":     true, // Token validation is critical
-		}
-	}
-
-	ctx, cancel := context.WithCancel(context.Background())
-
-	h := &HybridBackend{
-		primary:             config.Primary,
-		secondary:           config.Secondary,
-		syncWriteCacheTypes: config.SyncWriteCacheTypes,
-		asyncWriteBuffer:    make(chan *asyncWriteItem, config.AsyncBufferSize),
-		l1BackfillBuffer:    make(chan *l1BackfillItem, config.AsyncBufferSize),
-		ctx:                 ctx,
-		cancel:              cancel,
-		logger:              config.Logger,
-	}
-
-	// Start async write worker
-	h.wg.Add(1)
-	go h.asyncWriteWorker()
-
-	// Start L1 backfill worker (single goroutine) to bound goroutine growth on
-	// L2 hits regardless of request rate.
-	h.wg.Add(1)
-	go h.l1BackfillWorker()
-
-	// Start health monitoring
-	h.wg.Add(1)
-	go h.healthMonitor()
-
-	h.logger.Infof("HybridBackend initialized with L1 (memory) and L2 (Redis) tiers")
-	h.logger.Infof("Sync write cache types: %v", config.SyncWriteCacheTypes)
-	h.logger.Infof("Async write buffer size: %d", config.AsyncBufferSize)
-
-	return h, nil
-}
-
-// Set stores a value in both L1 and L2 caches
-func (h *HybridBackend) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error {
-	// Always write to L1 first (synchronous)
-	if err := h.primary.Set(ctx, key, value, ttl); err != nil {
-		h.errors.Add(1)
-		h.logger.Warnf("Failed to write to L1 cache: %v", err)
-		// Continue to try L2 even if L1 fails
-	} else {
-		h.l1Writes.Add(1)
-	}
-
-	// Check if we're in fallback mode
-	if h.fallbackMode.Load() {
-		h.logger.Debugf("Operating in fallback mode, skipping L2 write for key: %s", redactKey(key))
-		return nil // Don't fail the operation if L2 is down
-	}
-
-	// Determine if this should be a sync or async write based on cache type
-	cacheType := h.extractCacheType(key)
-	requiresSync := h.syncWriteCacheTypes[cacheType]
-
-	if requiresSync {
-		// Synchronous write for critical cache types
-		if err := h.secondary.Set(ctx, key, value, ttl); err != nil {
-			h.errors.Add(1)
-			h.logger.Warnf("Failed to write to L2 cache (sync) for key %s: %v", redactKey(key), err)
-			h.recordL2Error()
-			// Don't fail the operation - L1 write succeeded
-			return nil
-		}
-		h.l2Writes.Add(1)
-		h.logger.Debugf("Synchronous write to L2 completed for critical key: %s", redactKey(key))
-	} else {
-		// Asynchronous write for non-critical cache types
-		select {
-		case h.asyncWriteBuffer <- &asyncWriteItem{
-			key:   key,
-			value: value,
-			ttl:   ttl,
-			ctx:   ctx,
-		}:
-			h.logger.Debugf("Queued async write to L2 for key: %s", redactKey(key))
-		default:
-			// Buffer is full, log and continue
-			h.logger.Warnf("Async write buffer full, dropping L2 write for key: %s", redactKey(key))
-			h.errors.Add(1)
-		}
-	}
-
-	return nil
-}
-
-// Get retrieves a value from cache, checking L1 first, then L2
-func (h *HybridBackend) Get(ctx context.Context, key string) ([]byte, time.Duration, bool, error) {
-	// Try L1 first
-	value, ttl, exists, err := h.primary.Get(ctx, key)
-	if err != nil {
-		h.errors.Add(1)
-		h.logger.Debugf("L1 get error for key %s: %v", redactKey(key), err)
-	}
-
-	if exists {
-		h.l1Hits.Add(1)
-		return value, ttl, true, nil
-	}
-
-	// Check if we're in fallback mode
-	if h.fallbackMode.Load() {
-		h.misses.Add(1)
-		return nil, 0, false, nil
-	}
-
-	// Try L2
-	value, ttl, exists, err = h.secondary.Get(ctx, key)
-	if err != nil {
-		h.errors.Add(1)
-		h.logger.Debugf("L2 get error for key %s: %v", redactKey(key), err)
-		h.recordL2Error()
-		h.misses.Add(1)
-		return nil, 0, false, nil // Don't propagate L2 errors
-	}
-
-	if !exists {
-		h.misses.Add(1)
-		return nil, 0, false, nil
-	}
-
-	h.l2Hits.Add(1)
-
-	// Populate L1 cache with value from L2 (write-through on read).
-	// Hand off to the bounded backfill worker instead of spawning a goroutine
-	// per read - under burst that would mint thousands of goroutines.
-	h.queueL1Backfill(key, value, ttl)
-
-	return value, ttl, true, nil
-}
-
-// Delete removes a key from both L1 and L2 caches
-func (h *HybridBackend) Delete(ctx context.Context, key string) (bool, error) {
-	var deleted bool
-
-	// Delete from L1
-	if d, err := h.primary.Delete(ctx, key); err != nil {
-		h.logger.Debugf("Failed to delete from L1 cache: %v", err)
-	} else if d {
-		deleted = true
-	}
-
-	// Delete from L2 if not in fallback mode
-	if !h.fallbackMode.Load() {
-		if d, err := h.secondary.Delete(ctx, key); err != nil {
-			h.logger.Debugf("Failed to delete from L2 cache: %v", err)
-			h.recordL2Error()
-		} else if d {
-			deleted = true
-		}
-	}
-
-	return deleted, nil
-}
-
-// Exists checks if a key exists in either cache
-func (h *HybridBackend) Exists(ctx context.Context, key string) (bool, error) {
-	// Check L1 first
-	if exists, err := h.primary.Exists(ctx, key); err == nil && exists {
-		return true, nil
-	}
-
-	// Check L2 if not in fallback mode
-	if !h.fallbackMode.Load() {
-		if exists, err := h.secondary.Exists(ctx, key); err == nil && exists {
-			return true, nil
-		}
-	}
-
-	return false, nil
-}
-
-// Clear removes all keys from both caches
-func (h *HybridBackend) Clear(ctx context.Context) error {
-	var lastErr error
-
-	// Clear L1
-	if err := h.primary.Clear(ctx); err != nil {
-		h.logger.Errorf("Failed to clear L1 cache: %v", err)
-		lastErr = err
-	}
-
-	// Clear L2 if not in fallback mode
-	if !h.fallbackMode.Load() {
-		if err := h.secondary.Clear(ctx); err != nil {
-			h.logger.Errorf("Failed to clear L2 cache: %v", err)
-			h.recordL2Error()
-			lastErr = err
-		}
-	}
-
-	return lastErr
-}
-
-// GetStats returns statistics for the hybrid cache
-func (h *HybridBackend) GetStats() map[string]interface{} {
-	l1Hits := h.l1Hits.Load()
-	l2Hits := h.l2Hits.Load()
-	misses := h.misses.Load()
-	total := l1Hits + l2Hits + misses
-
-	stats := map[string]interface{}{
-		"type":          TypeHybrid,
-		"l1_hits":       l1Hits,
-		"l2_hits":       l2Hits,
-		"misses":        misses,
-		"total":         total,
-		"l1_writes":     h.l1Writes.Load(),
-		"l2_writes":     h.l2Writes.Load(),
-		"errors":        h.errors.Load(),
-		"fallback_mode": h.fallbackMode.Load(),
-	}
-
-	if total > 0 {
-		stats["l1_hit_rate"] = float64(l1Hits) / float64(total)
-		stats["l2_hit_rate"] = float64(l2Hits) / float64(total)
-		stats["overall_hit_rate"] = float64(l1Hits+l2Hits) / float64(total)
-	}
-
-	// Add sub-backend stats
-	stats["l1_stats"] = h.primary.GetStats()
-	stats["l2_stats"] = h.secondary.GetStats()
-
-	// Add last L2 error time if available
-	if lastErr := h.lastL2Error.Load(); lastErr != nil {
-		if t, ok := lastErr.(time.Time); ok {
-			stats["last_l2_error"] = t.Format(time.RFC3339)
-			stats["seconds_since_l2_error"] = time.Since(t).Seconds()
-		}
-	}
-
-	return stats
-}
-
-// Ping checks if both backends are healthy
-func (h *HybridBackend) Ping(ctx context.Context) error {
-	// Check L1
-	if err := h.primary.Ping(ctx); err != nil {
-		return fmt.Errorf("L1 ping failed: %w", err)
-	}
-
-	// Check L2 (but don't fail if it's down)
-	if err := h.secondary.Ping(ctx); err != nil {
-		h.logger.Warnf("L2 ping failed: %v", err)
-		h.recordL2Error()
-		// Don't return error - we can operate with L1 only
-	} else {
-		// L2 is healthy, clear fallback mode if it was set
-		if h.fallbackMode.CompareAndSwap(true, false) {
-			h.logger.Infof("L2 backend recovered, exiting fallback mode")
-		}
-	}
-
-	return nil
-}
-
-// Close shuts down the hybrid backend
-func (h *HybridBackend) Close() error {
-	// Cancel context to stop workers
-	h.cancel()
-
-	// Close async write channel
-	close(h.asyncWriteBuffer)
-	close(h.l1BackfillBuffer)
-
-	// Wait for workers to finish with timeout
-	done := make(chan struct{})
-	go func() {
-		h.wg.Wait()
-		close(done)
-	}()
-
-	select {
-	case <-done:
-		// Workers finished
-	case <-time.After(5 * time.Second):
-		h.logger.Warnf("Timeout waiting for workers to finish")
-	}
-
-	var lastErr error
-
-	// Close backends
-	if err := h.primary.Close(); err != nil {
-		h.logger.Errorf("Failed to close L1 backend: %v", err)
-		lastErr = err
-	}
-
-	if err := h.secondary.Close(); err != nil {
-		h.logger.Errorf("Failed to close L2 backend: %v", err)
-		lastErr = err
-	}
-
-	h.logger.Infof("HybridBackend closed")
-
-	return lastErr
-}
-
-// GetMany retrieves multiple values efficiently
-func (h *HybridBackend) GetMany(ctx context.Context, keys []string) (map[string][]byte, error) {
-	if len(keys) == 0 {
-		return make(map[string][]byte), nil
-	}
-
-	results := make(map[string][]byte, len(keys))
-	missingKeys := make([]string, 0)
-
-	// Try L1 first for all keys
-	for _, key := range keys {
-		if value, _, exists, _ := h.primary.Get(ctx, key); exists {
-			results[key] = value
-			h.l1Hits.Add(1)
-		} else {
-			missingKeys = append(missingKeys, key)
-		}
-	}
-
-	// If all found in L1 or in fallback mode, return
-	if len(missingKeys) == 0 || h.fallbackMode.Load() {
-		return results, nil
-	}
-
-	// Try L2 for missing keys using batch operation if available
-	if batcher, ok := h.secondary.(interface {
-		GetMany(context.Context, []string) (map[string][]byte, error)
-	}); ok {
-		l2Results, err := batcher.GetMany(ctx, missingKeys)
-		if err != nil {
-			h.logger.Debugf("L2 batch get error: %v", err)
-			h.recordL2Error()
-		} else {
-			for key, value := range l2Results {
-				results[key] = value
-				h.l2Hits.Add(1)
-				h.queueL1Backfill(key, value, 0) // 0 = primary backend default TTL
-			}
-		}
-	} else {
-		// Fallback to individual gets
-		for _, key := range missingKeys {
-			if value, ttl, exists, err := h.secondary.Get(ctx, key); err == nil && exists {
-				results[key] = value
-				h.l2Hits.Add(1)
-				h.queueL1Backfill(key, value, ttl)
-			}
-		}
-	}
-
-	// Count misses for keys not found anywhere
-	for _, key := range keys {
-		if _, found := results[key]; !found {
-			h.misses.Add(1)
-		}
-	}
-
-	return results, nil
-}
-
-// SetMany stores multiple key-value pairs efficiently
-func (h *HybridBackend) SetMany(ctx context.Context, items map[string][]byte, ttl time.Duration) error {
-	if len(items) == 0 {
-		return nil
-	}
-
-	// Write to L1 first
-	for key, value := range items {
-		if err := h.primary.Set(ctx, key, value, ttl); err != nil {
-			h.logger.Debugf("Failed to write to L1 in batch: %v", err)
-		} else {
-			h.l1Writes.Add(1)
-		}
-	}
-
-	// Skip L2 if in fallback mode
-	if h.fallbackMode.Load() {
-		return nil
-	}
-
-	// Check if L2 supports batch operations
-	if batcher, ok := h.secondary.(interface {
-		SetMany(context.Context, map[string][]byte, time.Duration) error
-	}); ok {
-		if err := batcher.SetMany(ctx, items, ttl); err != nil {
-			h.logger.Warnf("Failed to batch write to L2: %v", err)
-			h.recordL2Error()
-		} else {
-			h.l2Writes.Add(int64(len(items)))
-		}
-	} else {
-		// Fallback to individual sets
-		for key, value := range items {
-			cacheType := h.extractCacheType(key)
-			if h.syncWriteCacheTypes[cacheType] {
-				// Sync write for critical types
-				if err := h.secondary.Set(ctx, key, value, ttl); err != nil {
-					h.logger.Debugf("Failed to write to L2: %v", err)
-					h.recordL2Error()
-				} else {
-					h.l2Writes.Add(1)
-				}
-			} else {
-				// Async write for non-critical types
-				select {
-				case h.asyncWriteBuffer <- &asyncWriteItem{
-					key:   key,
-					value: value,
-					ttl:   ttl,
-					ctx:   ctx,
-				}:
-					// Queued
-				default:
-					h.logger.Warnf("Async buffer full for batch write")
-				}
-			}
-		}
-	}
-
-	return nil
-}
-
-// queueL1Backfill enqueues an L2-resolved value for write-through into L1.
-// Drops on full buffer to keep the read path constant-time; the next L2 hit
-// for the same key simply re-queues it.
-func (h *HybridBackend) queueL1Backfill(key string, value []byte, ttl time.Duration) {
-	select {
-	case h.l1BackfillBuffer <- &l1BackfillItem{key: key, value: value, ttl: ttl}:
-	default:
-		h.l1BackfillDrops.Add(1)
-		h.logger.Debugf("L1 backfill buffer full, dropping for key: %s", redactKey(key))
-	}
-}
-
-// l1BackfillWorker drains the backfill queue serially. Single worker is
-// intentional - L1 writes are local and cheap, and serializing them keeps
-// goroutine count bounded under any read rate.
-func (h *HybridBackend) l1BackfillWorker() {
-	defer h.wg.Done()
-
-	for {
-		select {
-		case <-h.ctx.Done():
-			// Drain remaining items best-effort then exit.
-			for len(h.l1BackfillBuffer) > 0 {
-				select {
-				case item := <-h.l1BackfillBuffer:
-					writeCtx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
-					_ = h.primary.Set(writeCtx, item.key, item.value, item.ttl)
-					cancel()
-				default:
-					return
-				}
-			}
-			return
-
-		case item, ok := <-h.l1BackfillBuffer:
-			if !ok {
-				return
-			}
-			writeCtx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
-			if err := h.primary.Set(writeCtx, item.key, item.value, item.ttl); err != nil {
-				h.logger.Debugf("Failed to populate L1 cache from L2 for key %s: %v", redactKey(item.key), err)
-			} else {
-				h.logger.Debugf("Populated L1 cache from L2 for key: %s", redactKey(item.key))
-			}
-			cancel()
-		}
-	}
-}
-
-// asyncWriteWorker processes asynchronous writes to L2
-func (h *HybridBackend) asyncWriteWorker() {
-	defer h.wg.Done()
-
-	for {
-		select {
-		case <-h.ctx.Done():
-			// Drain remaining items with best effort
-			for len(h.asyncWriteBuffer) > 0 {
-				select {
-				case item := <-h.asyncWriteBuffer:
-					ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
-					_ = h.secondary.Set(ctx, item.key, item.value, item.ttl)
-					cancel()
-				default:
-					return
-				}
-			}
-			return
-
-		case item, ok := <-h.asyncWriteBuffer:
-			if !ok {
-				return
-			}
-
-			// Skip if in fallback mode
-			if h.fallbackMode.Load() {
-				continue
-			}
-
-			// Perform the write with a timeout
-			writeCtx, cancel := context.WithTimeout(item.ctx, 500*time.Millisecond)
-			if err := h.secondary.Set(writeCtx, item.key, item.value, item.ttl); err != nil {
-				h.errors.Add(1)
-				h.logger.Debugf("Async write to L2 failed for key %s: %v", redactKey(item.key), err)
-				h.recordL2Error()
-			} else {
-				h.l2Writes.Add(1)
-				h.logger.Debugf("Async write to L2 completed for key: %s", redactKey(item.key))
-			}
-			cancel()
-		}
-	}
-}
-
-// healthMonitor periodically checks L2 health and manages fallback mode
-func (h *HybridBackend) healthMonitor() {
-	defer h.wg.Done()
-
-	ticker := time.NewTicker(30 * time.Second)
-	defer ticker.Stop()
-
-	for {
-		select {
-		case <-h.ctx.Done():
-			return
-
-		case <-ticker.C:
-			ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-
-			if err := h.secondary.Ping(ctx); err != nil {
-				if !h.fallbackMode.Load() {
-					h.fallbackMode.Store(true)
-					h.logger.Warnf("L2 backend unhealthy, entering fallback mode: %v", err)
-				}
-			} else {
-				if h.fallbackMode.CompareAndSwap(true, false) {
-					h.logger.Infof("L2 backend healthy, exiting fallback mode")
-				}
-			}
-
-			cancel()
-		}
-	}
-}
-
-// recordL2Error records the timestamp of an L2 error
-func (h *HybridBackend) recordL2Error() {
-	h.lastL2Error.Store(time.Now())
-
-	// Check if we should enter fallback mode based on recent errors
-	if !h.fallbackMode.Load() {
-		// Simple heuristic: if we've had an error in the last second, consider L2 unhealthy
-		if lastErr := h.lastL2Error.Load(); lastErr != nil {
-			if t, ok := lastErr.(time.Time); ok && time.Since(t) < time.Second {
-				h.fallbackMode.Store(true)
-				h.logger.Warnf("Multiple L2 errors detected, entering fallback mode")
-			}
-		}
-	}
-}
-
-// extractCacheType attempts to determine the cache type from the key
-func (h *HybridBackend) extractCacheType(key string) string {
-	// Simple heuristic based on key prefixes
-	// This should match the actual cache type strategy in the main application
-
-	if len(key) > 10 {
-		prefix := key[:10]
-		switch {
-		case contains(prefix, "blacklist"):
-			return "blacklist"
-		case contains(prefix, "token"):
-			return "token"
-		case contains(prefix, "metadata"):
-			return "metadata"
-		case contains(prefix, "jwk"):
-			return "jwk"
-		case contains(prefix, "session"):
-			return "session"
-		case contains(prefix, "introspect"):
-			return "introspection"
-		}
-	}
-
-	return "general"
-}
-
-// contains checks if a string contains a substring (case-insensitive)
-func contains(s, substr string) bool {
-	if len(substr) > len(s) {
-		return false
-	}
-	for i := 0; i <= len(s)-len(substr); i++ {
-		match := true
-		for j := 0; j < len(substr); j++ {
-			if toLower(s[i+j]) != toLower(substr[j]) {
-				match = false
-				break
-			}
-		}
-		if match {
-			return true
-		}
-	}
-	return false
-}
-
-// toLower converts a byte to lowercase
-func toLower(b byte) byte {
-	if b >= 'A' && b <= 'Z' {
-		return b + 32
-	}
-	return b
-}

internal/cache/backends/hybrid_l1_backfill_test.go

@@ -1,112 +0,0 @@
-//go:build !yaegi
-
-package backends
-
-import (
-	"context"
-	"fmt"
-	"runtime"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// TestHybridBackend_L1BackfillBounded verifies that a burst of L2 hits does
-// not detonate the goroutine count. Pre-fix the code spawned one goroutine
-// per Get() L2 hit; post-fix all backfills funnel through a single worker.
-func TestHybridBackend_L1BackfillBounded(t *testing.T) {
-	primary := newMockBackend()
-	secondary := newMockBackend()
-
-	hybrid, err := NewHybridBackend(&HybridConfig{
-		Primary:         primary,
-		Secondary:       secondary,
-		AsyncBufferSize: 256,
-	})
-	require.NoError(t, err)
-	defer hybrid.Close()
-
-	ctx := context.Background()
-	const burst = 1000
-
-	// Pre-populate L2 with `burst` distinct keys so each Get triggers a
-	// fresh L1 backfill enqueue.
-	for i := 0; i < burst; i++ {
-		require.NoError(t, secondary.Set(ctx, fmt.Sprintf("k:%d", i), []byte("v"), time.Minute))
-	}
-
-	baseline := runtime.NumGoroutine()
-
-	// Issue the burst as fast as possible; the backfill worker MUST be the
-	// only goroutine doing L1 writes. Allow brief slack for the test runtime
-	// scheduling but anything north of +20 means goroutine leakage.
-	peak := baseline
-	for i := 0; i < burst; i++ {
-		_, _, exists, err := hybrid.Get(ctx, fmt.Sprintf("k:%d", i))
-		require.NoError(t, err)
-		require.True(t, exists)
-		if g := runtime.NumGoroutine(); g > peak {
-			peak = g
-		}
-	}
-
-	delta := peak - baseline
-	if delta > 20 {
-		t.Fatalf("goroutine count grew by %d during burst (baseline=%d peak=%d); backfill worker not bounding goroutines",
-			delta, baseline, peak)
-	}
-
-	// L1 must eventually catch up via the worker. Worker drains serially so
-	// give it a generous window proportional to the burst size.
-	deadline := time.Now().Add(2 * time.Second)
-	for time.Now().Before(deadline) {
-		var populated int
-		for i := 0; i < burst; i++ {
-			if _, _, ok, _ := primary.Get(ctx, fmt.Sprintf("k:%d", i)); ok {
-				populated++
-			}
-		}
-		// Be lenient: drops are acceptable under buffer pressure, just want
-		// most of the keys to make it.
-		if populated >= burst-int(hybrid.l1BackfillDrops.Load()) {
-			return
-		}
-		time.Sleep(20 * time.Millisecond)
-	}
-	t.Fatalf("L1 not backfilled within deadline: l2Hits=%d l1Writes=%d drops=%d",
-		hybrid.l2Hits.Load(), hybrid.l1Writes.Load(), hybrid.l1BackfillDrops.Load())
-}
-
-// TestHybridBackend_L1BackfillFullDrops verifies the drop semantics when the
-// buffer is saturated. Drops must be counted, never block, never spawn a
-// goroutine.
-func TestHybridBackend_L1BackfillFullDrops(t *testing.T) {
-	primary := newMockBackend()
-	secondary := newMockBackend()
-
-	// Tiny buffer + slow primary writes via failSet so the worker stays
-	// blocked enough to overflow the buffer.
-	hybrid, err := NewHybridBackend(&HybridConfig{
-		Primary:         primary,
-		Secondary:       secondary,
-		AsyncBufferSize: 4,
-	})
-	require.NoError(t, err)
-	defer hybrid.Close()
-
-	// Stop the worker from draining: cancel the underlying context so the
-	// worker bails out, leaving us with a cold buffer and the queue method
-	// itself responsible for drop accounting.
-	hybrid.cancel()
-	// Wait for worker to exit so it can't drain.
-	time.Sleep(50 * time.Millisecond)
-
-	for i := 0; i < 50; i++ {
-		hybrid.queueL1Backfill(fmt.Sprintf("k:%d", i), []byte("v"), time.Minute)
-	}
-
-	assert.Greater(t, hybrid.l1BackfillDrops.Load(), int64(0),
-		"expected some drops when buffer is saturated and worker is stopped")
-}

internal/cache/backends/interface.go

@@ -1,4 +1,4 @@
-// Package backend provides cache backend implementations for the Traefik OIDC plugin.
+// Package backends provides cache backend implementations for the Traefik OIDC plugin.
 package backends
 
 import (
@@ -7,7 +7,7 @@ import (
 )
 
 // CacheBackend defines the interface for all cache backend implementations
-// Implementations include: MemoryBackend, RedisBackend, and HybridBackend
+// Implementations include: RedisBackend
 type CacheBackend interface {
 	// Set stores a value in the cache with the specified TTL
 	// Returns an error if the operation fails

internal/cache/backends/interface_test.go

@@ -11,28 +11,24 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-// TestCacheBackendContract defines a set of tests that all CacheBackend implementations must pass
-// This ensures that Memory, Redis, and Hybrid backends all behave consistently
+// TestCacheBackendContract defines a set of tests that all CacheBackend
+// implementations must pass. RedisBackend is the only implementation left
+// (FIX-43 deleted MemoryBackend and HybridBackend); it runs against a real
+// miniredis-backed instance via setupRedisBackend (R4 cache review — this
+// suite used to be a no-op: both subtests were t.Skip stubs).
 func TestCacheBackendContract(t *testing.T) {
-	// Test suite will be run against each backend type
-	t.Run("MemoryBackend", func(t *testing.T) {
-		backend := setupMemoryBackend(t)
-		runContractTests(t, backend)
-	})
-
 	t.Run("RedisBackend", func(t *testing.T) {
-		backend := setupRedisBackend(t)
-		runContractTests(t, backend)
-	})
-
-	t.Run("HybridBackend", func(t *testing.T) {
-		backend := setupHybridBackend(t)
-		runContractTests(t, backend)
+		backend, advanceClock := setupRedisBackend(t)
+		runContractTests(t, backend, advanceClock)
 	})
 }
 
-// runContractTests executes all contract tests against a backend
-func runContractTests(t *testing.T, backend CacheBackend) {
+// runContractTests executes all contract tests against a backend.
+// advanceClock advances TTL expiration by d: miniredis (see setupRedisBackend)
+// only expires keys when its simulated clock is explicitly moved forward, so
+// testTTLExpiration cannot rely on a real time.Sleep the way every other
+// contract test can.
+func runContractTests(t *testing.T, backend CacheBackend, advanceClock func(d time.Duration)) {
 	t.Helper()
 
 	ctx := context.Background()
@@ -62,7 +58,7 @@ func runContractTests(t *testing.T, backend CacheBackend) {
 	})
 
 	t.Run("TTLExpiration", func(t *testing.T) {
-		testTTLExpiration(t, ctx, backend)
+		testTTLExpiration(t, ctx, backend, advanceClock)
 	})
 
 	t.Run("Clear", func(t *testing.T) {
@@ -213,7 +209,7 @@ func testExists(t *testing.T, ctx context.Context, backend CacheBackend) {
 }
 
 // testTTLExpiration verifies TTL expiration behavior
-func testTTLExpiration(t *testing.T, ctx context.Context, backend CacheBackend) {
+func testTTLExpiration(t *testing.T, ctx context.Context, backend CacheBackend, advanceClock func(d time.Duration)) {
 	t.Helper()
 
 	key := "ttl-key"
@@ -229,8 +225,8 @@ func testTTLExpiration(t *testing.T, ctx context.Context, backend CacheBackend)
 	require.NoError(t, err)
 	assert.True(t, exists, "Key should exist immediately after Set")
 
-	// Wait for expiration
-	time.Sleep(200 * time.Millisecond)
+	// Advance past expiration.
+	advanceClock(200 * time.Millisecond)
 
 	// Verify expired
 	exists, err = backend.Exists(ctx, key)
@@ -378,44 +374,17 @@ func testSpecialCharactersInKeys(t *testing.T, ctx context.Context, backend Cach
 	}
 }
 
-// Helper functions to setup different backend types
-// These will be implemented in respective test files
-
-func setupMemoryBackend(t *testing.T) CacheBackend {
+// setupRedisBackend wires the contract suite to a real RedisBackend backed
+// by miniredis (R4 cache review), matching the pattern redis_test.go and
+// singleflight_test.go already use. The returned func advances miniredis's
+// own simulated clock (see MiniredisServer.FastForward): miniredis only
+// expires a key when that clock is explicitly moved forward, so it never
+// expires anything on real elapsed time alone.
+func setupRedisBackend(t *testing.T) (CacheBackend, func(d time.Duration)) {
 	t.Helper()
-	// This will be implemented in memory_test.go
-	// For now, return nil to allow compilation
-	t.Skip("MemoryBackend implementation pending")
-	return nil
-}
-
-func setupRedisBackend(t *testing.T) CacheBackend {
-	t.Helper()
-	// This will be implemented in redis_test.go
-	// For now, return nil to allow compilation
-	t.Skip("RedisBackend implementation pending")
-	return nil
-}
-
-func setupHybridBackend(t *testing.T) CacheBackend {
-	t.Helper()
-
-	primary := newMockBackend()
-	secondary := newMockBackend()
-
-	config := &HybridConfig{
-		Primary:         primary,
-		Secondary:       secondary,
-		AsyncBufferSize: 100,
-		Logger:          NewTestLogger(t),
-	}
-
-	hybrid, err := NewHybridBackend(config)
-	require.NoError(t, err)
-
-	t.Cleanup(func() {
-		hybrid.Close()
-	})
-
-	return hybrid
+	mr := NewMiniredisServer(t)
+	backend, err := NewRedisBackend(DefaultRedisConfig(mr.GetAddr()))
+	require.NoError(t, err, "failed to create RedisBackend")
+	t.Cleanup(func() { _ = backend.Close() })
+	return backend, mr.FastForward
 }

internal/cache/backends/log_redact.go

@@ -1,26 +0,0 @@
-// Package backends provides cache backend implementations for the Traefik OIDC plugin.
-package backends
-
-import (
-	"crypto/sha256"
-	"encoding/hex"
-)
-
-// redactKey returns a short, deterministic hash prefix of a cache key for use
-// in debug/info log lines. Cache keys in this plugin can include raw access /
-// refresh / id tokens (any caller may pass an arbitrary string), and CodeQL
-// flags `key=%s` formatters as a clear-text-logging sink for HTTP-header-
-// sourced taint. The hash preserves cache-key uniqueness in logs (same key →
-// same hash, useful for correlating a problematic key across log lines) while
-// keeping the raw value out of disk-resident log streams.
-//
-// 8 hex chars (32 bits) is enough to disambiguate at human-debugging scale
-// without making the hash itself a useful lookup primitive for an attacker
-// who only has the log stream.
-func redactKey(key string) string {
-	if key == "" {
-		return "(empty)"
-	}
-	sum := sha256.Sum256([]byte(key))
-	return hex.EncodeToString(sum[:4])
-}

internal/cache/backends/memory.go

@@ -1,535 +0,0 @@
-// Package backend provides cache backend implementations for the Traefik OIDC plugin.
-package backends
-
-import (
-	"context"
-	"sync"
-	"sync/atomic"
-	"time"
-)
-
-// Default configuration values
-const (
-	defaultShardCount      = 256
-	defaultMaxSize         = int64(10000)
-	defaultMaxMemory       = int64(100 * 1024 * 1024) // 100MB
-	defaultCleanupInterval = 5 * time.Minute
-)
-
-// memoryCacheItem represents an item in the memory cache
-type memoryCacheItem struct {
-	expiresAt   time.Time
-	createdAt   time.Time
-	accessedAt  time.Time
-	value       interface{}
-	element     interface{} // *list.Element, using interface{} to avoid import cycle
-	key         string
-	accessCount int64
-	size        int64
-}
-
-// isExpired checks if the item is expired
-func (item *memoryCacheItem) isExpired() bool {
-	if item.expiresAt.IsZero() {
-		return false
-	}
-	return time.Now().After(item.expiresAt)
-}
-
-// MemoryCacheBackend implements the CacheBackend interface using sharded in-memory storage
-// The sharded design reduces lock contention by partitioning keys across multiple shards,
-// each with its own lock.
-type MemoryCacheBackend struct {
-	shards          []*cacheShard
-	startTime       time.Time
-	lastErrorTime   time.Time
-	cleanupDone     chan struct{}
-	cleanupTicker   *time.Ticker
-	lastError       string
-	shardCount      uint32
-	shardMask       uint32
-	maxSize         int64
-	maxMemory       int64
-	cleanupInterval time.Duration
-
-	// Global stats (aggregated from shards)
-	hits      atomic.Int64
-	misses    atomic.Int64
-	sets      atomic.Int64
-	deletes   atomic.Int64
-	evictions atomic.Int64
-	errors    atomic.Int64
-
-	// Latency tracking
-	totalGetTime atomic.Int64
-	totalSetTime atomic.Int64
-	getCount     atomic.Int64
-	setCount     atomic.Int64
-
-	// State
-	closed atomic.Bool
-	mu     sync.RWMutex // For global operations like stats and error tracking
-}
-
-// NewMemoryCacheBackend creates a new sharded memory cache backend
-func NewMemoryCacheBackend(maxSize int64, maxMemory int64, cleanupInterval time.Duration) *MemoryCacheBackend {
-	if maxSize <= 0 {
-		maxSize = defaultMaxSize
-	}
-	if maxMemory <= 0 {
-		maxMemory = defaultMaxMemory
-	}
-	if cleanupInterval <= 0 {
-		cleanupInterval = defaultCleanupInterval
-	}
-
-	shardCount := uint32(defaultShardCount)
-
-	// For very small caches, reduce shard count to maintain sensible per-shard limits
-	// Ensure each shard can hold at least 2 items for proper LRU behavior
-	for shardCount > 1 && maxSize/int64(shardCount) < 2 {
-		shardCount /= 2
-	}
-	if shardCount < 1 {
-		shardCount = 1
-	}
-
-	// Per-shard limits are soft hints; global limits are enforced
-	// Give shards 2x the average to allow for uneven distribution
-	shardMaxSize := (maxSize * 2) / int64(shardCount)
-	if shardMaxSize < 4 {
-		shardMaxSize = 4
-	}
-	shardMaxMemory := (maxMemory * 2) / int64(shardCount)
-	if shardMaxMemory < 4096 {
-		shardMaxMemory = 4096 // Minimum 4KB per shard
-	}
-
-	m := &MemoryCacheBackend{
-		shards:          make([]*cacheShard, shardCount),
-		shardCount:      shardCount,
-		shardMask:       shardCount - 1, // For fast modulo with power-of-2
-		maxSize:         maxSize,
-		maxMemory:       maxMemory,
-		startTime:       time.Now(),
-		cleanupInterval: cleanupInterval,
-		cleanupDone:     make(chan struct{}),
-	}
-
-	// Initialize shards
-	for i := uint32(0); i < shardCount; i++ {
-		m.shards[i] = newCacheShard(shardMaxSize, shardMaxMemory)
-	}
-
-	// Start cleanup goroutine
-	m.cleanupTicker = time.NewTicker(cleanupInterval)
-	go m.cleanupLoop()
-
-	return m
-}
-
-// getShard returns the shard for a given key
-func (m *MemoryCacheBackend) getShard(key string) *cacheShard {
-	hash := fnv32(key)
-	return m.shards[hash&m.shardMask]
-}
-
-// cleanupLoop runs periodic cleanup of expired items
-func (m *MemoryCacheBackend) cleanupLoop() {
-	for {
-		select {
-		case <-m.cleanupTicker.C:
-			m.cleanupExpired()
-		case <-m.cleanupDone:
-			return
-		}
-	}
-}
-
-// cleanupExpired removes all expired items from all shards
-func (m *MemoryCacheBackend) cleanupExpired() {
-	if m.closed.Load() {
-		return
-	}
-
-	totalRemoved := 0
-	for _, shard := range m.shards {
-		totalRemoved += shard.cleanup()
-	}
-
-	if totalRemoved > 0 {
-		m.evictions.Add(int64(totalRemoved))
-	}
-}
-
-// Get retrieves a value from the cache
-func (m *MemoryCacheBackend) Get(ctx context.Context, key string) (interface{}, error) {
-	if m.closed.Load() {
-		return nil, ErrBackendUnavailable
-	}
-
-	start := time.Now()
-	defer func() {
-		duration := time.Since(start).Nanoseconds()
-		m.totalGetTime.Add(duration)
-		m.getCount.Add(1)
-	}()
-
-	shard := m.getShard(key)
-	value, exists, expired := shard.get(key)
-
-	if expired {
-		// Clean up expired item
-		shard.delete(key)
-		m.misses.Add(1)
-		return nil, ErrCacheMiss
-	}
-
-	if !exists {
-		m.misses.Add(1)
-		return nil, ErrCacheMiss
-	}
-
-	m.hits.Add(1)
-	return value, nil
-}
-
-// Set stores a value in the cache with optional TTL
-func (m *MemoryCacheBackend) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error {
-	if m.closed.Load() {
-		return ErrBackendUnavailable
-	}
-
-	start := time.Now()
-	defer func() {
-		duration := time.Since(start).Nanoseconds()
-		m.totalSetTime.Add(duration)
-		m.setCount.Add(1)
-	}()
-
-	// Calculate item size
-	itemSize := int64(len(key)) + estimateValueSize(value)
-
-	// Enforce global limits before adding new item
-	m.enforceGlobalLimits(itemSize)
-
-	var expiresAt time.Time
-	if ttl > 0 {
-		expiresAt = time.Now().Add(ttl)
-	}
-
-	shard := m.getShard(key)
-	shard.set(key, value, expiresAt, itemSize)
-
-	m.sets.Add(1)
-	return nil
-}
-
-// enforceGlobalLimits ensures global size and memory limits are respected
-// by evicting from shards when necessary
-func (m *MemoryCacheBackend) enforceGlobalLimits(newItemSize int64) {
-	// Check and enforce size limit
-	for {
-		totalSize, totalMemory := m.getGlobalStats()
-
-		needsSizeEviction := m.maxSize > 0 && totalSize >= m.maxSize
-		needsMemoryEviction := m.maxMemory > 0 && totalMemory+newItemSize > m.maxMemory
-
-		if !needsSizeEviction && !needsMemoryEviction {
-			break
-		}
-
-		// Find the shard with the most items and evict from it
-		evicted := m.evictFromLargestShard()
-		if !evicted {
-			break // No more items to evict
-		}
-		m.evictions.Add(1)
-	}
-}
-
-// getGlobalStats returns the total size and memory usage across all shards
-func (m *MemoryCacheBackend) getGlobalStats() (totalSize, totalMemory int64) {
-	for _, shard := range m.shards {
-		size, memory := shard.stats()
-		totalSize += size
-		totalMemory += memory
-	}
-	return
-}
-
-// evictFromLargestShard evicts the globally oldest item across all shards
-// This provides true LRU behavior even with sharding
-func (m *MemoryCacheBackend) evictFromLargestShard() bool {
-	var oldestShard *cacheShard
-	var oldestTime time.Time
-
-	for _, shard := range m.shards {
-		accessTime := shard.getOldestAccessTime()
-		// Skip empty shards
-		if accessTime.IsZero() {
-			continue
-		}
-		// Find the shard with the oldest (earliest) access time
-		if oldestShard == nil || accessTime.Before(oldestTime) {
-			oldestTime = accessTime
-			oldestShard = shard
-		}
-	}
-
-	if oldestShard == nil {
-		return false
-	}
-
-	return oldestShard.evictOne()
-}
-
-// Delete removes a key from the cache
-func (m *MemoryCacheBackend) Delete(ctx context.Context, key string) error {
-	if m.closed.Load() {
-		return ErrBackendUnavailable
-	}
-
-	shard := m.getShard(key)
-	if shard.delete(key) {
-		m.deletes.Add(1)
-	}
-
-	return nil
-}
-
-// Exists checks if a key exists in the cache
-func (m *MemoryCacheBackend) Exists(ctx context.Context, key string) (bool, error) {
-	if m.closed.Load() {
-		return false, ErrBackendUnavailable
-	}
-
-	shard := m.getShard(key)
-	return shard.exists(key), nil
-}
-
-// Clear removes all items from the cache
-func (m *MemoryCacheBackend) Clear(ctx context.Context) error {
-	if m.closed.Load() {
-		return ErrBackendUnavailable
-	}
-
-	for _, shard := range m.shards {
-		shard.clear()
-	}
-
-	return nil
-}
-
-// Keys returns all keys matching the pattern (use "*" for all keys)
-func (m *MemoryCacheBackend) Keys(ctx context.Context, pattern string) ([]string, error) {
-	if m.closed.Load() {
-		return nil, ErrBackendUnavailable
-	}
-
-	var allKeys []string
-	for _, shard := range m.shards {
-		keys := shard.keys(pattern)
-		allKeys = append(allKeys, keys...)
-	}
-
-	return allKeys, nil
-}
-
-// Size returns the total number of items in the cache
-func (m *MemoryCacheBackend) Size(ctx context.Context) (int64, error) {
-	if m.closed.Load() {
-		return 0, ErrBackendUnavailable
-	}
-
-	var total int64
-	for _, shard := range m.shards {
-		size, _ := shard.stats()
-		total += size
-	}
-
-	return total, nil
-}
-
-// TTL returns the remaining time-to-live for a key
-func (m *MemoryCacheBackend) TTL(ctx context.Context, key string) (time.Duration, error) {
-	if m.closed.Load() {
-		return 0, ErrBackendUnavailable
-	}
-
-	shard := m.getShard(key)
-	ttl, exists := shard.ttl(key)
-	if !exists {
-		return 0, ErrCacheMiss
-	}
-
-	return ttl, nil
-}
-
-// Expire updates the TTL for an existing key
-func (m *MemoryCacheBackend) Expire(ctx context.Context, key string, ttl time.Duration) error {
-	if m.closed.Load() {
-		return ErrBackendUnavailable
-	}
-
-	shard := m.getShard(key)
-	if !shard.expire(key, ttl) {
-		return ErrCacheMiss
-	}
-
-	return nil
-}
-
-// GetStats returns statistics about the cache backend
-func (m *MemoryCacheBackend) GetStats(ctx context.Context) (*BackendStats, error) {
-	if m.closed.Load() {
-		return nil, ErrBackendUnavailable
-	}
-
-	// Aggregate stats from all shards
-	var totalSize, totalMemory int64
-	for _, shard := range m.shards {
-		size, memory := shard.stats()
-		totalSize += size
-		totalMemory += memory
-	}
-
-	m.mu.RLock()
-	lastError := m.lastError
-	lastErrorTime := m.lastErrorTime
-	m.mu.RUnlock()
-
-	avgGetLatency := time.Duration(0)
-	if getCount := m.getCount.Load(); getCount > 0 {
-		avgGetLatency = time.Duration(m.totalGetTime.Load() / getCount)
-	}
-
-	avgSetLatency := time.Duration(0)
-	if setCount := m.setCount.Load(); setCount > 0 {
-		avgSetLatency = time.Duration(m.totalSetTime.Load() / setCount)
-	}
-
-	return &BackendStats{
-		Type:              TypeMemory,
-		Hits:              m.hits.Load(),
-		Misses:            m.misses.Load(),
-		Sets:              m.sets.Load(),
-		Deletes:           m.deletes.Load(),
-		Errors:            m.errors.Load(),
-		Evictions:         m.evictions.Load(),
-		CurrentSize:       totalSize,
-		MaxSize:           m.maxSize,
-		MemoryUsage:       totalMemory,
-		AverageGetLatency: avgGetLatency,
-		AverageSetLatency: avgSetLatency,
-		LastError:         lastError,
-		LastErrorTime:     lastErrorTime,
-		Uptime:            time.Since(m.startTime),
-		StartTime:         m.startTime,
-	}, nil
-}
-
-// Ping checks if the backend is healthy
-func (m *MemoryCacheBackend) Ping(ctx context.Context) error {
-	if m.closed.Load() {
-		return ErrBackendUnavailable
-	}
-	return nil
-}
-
-// Close closes the backend and releases resources
-func (m *MemoryCacheBackend) Close() error {
-	if m.closed.Swap(true) {
-		return nil // Already closed
-	}
-
-	m.cleanupTicker.Stop()
-	close(m.cleanupDone)
-
-	// Clear all shards
-	for _, shard := range m.shards {
-		shard.clear()
-	}
-
-	return nil
-}
-
-// IsHealthy returns true if the backend is healthy
-func (m *MemoryCacheBackend) IsHealthy() bool {
-	return !m.closed.Load()
-}
-
-// Type returns the backend type
-func (m *MemoryCacheBackend) Type() BackendType {
-	return TypeMemory
-}
-
-// Capabilities returns the backend capabilities
-func (m *MemoryCacheBackend) Capabilities() *BackendCapabilities {
-	return &BackendCapabilities{
-		Distributed:         false,
-		Persistent:          false,
-		Eviction:            true,
-		TTL:                 true,
-		MaxKeySize:          1024,     // 1KB
-		MaxValueSize:        10485760, // 10MB
-		MaxKeys:             m.maxSize,
-		SupportsExpire:      true,
-		SupportsMultiGet:    true,
-		SupportsTransaction: false,
-		SupportsCompression: false,
-		RequiresSerialize:   false,
-	}
-}
-
-// GetShardCount returns the number of shards (for testing/monitoring)
-func (m *MemoryCacheBackend) GetShardCount() uint32 {
-	return m.shardCount
-}
-
-// GetShardStats returns per-shard statistics (for monitoring)
-func (m *MemoryCacheBackend) GetShardStats() []map[string]int64 {
-	stats := make([]map[string]int64, m.shardCount)
-	for i, shard := range m.shards {
-		size, memory := shard.stats()
-		stats[i] = map[string]int64{
-			"size":   size,
-			"memory": memory,
-		}
-	}
-	return stats
-}
-
-// Helper functions
-
-// estimateValueSize estimates the size of a value in bytes
-func estimateValueSize(value interface{}) int64 {
-	switch v := value.(type) {
-	case string:
-		return int64(len(v))
-	case []byte:
-		return int64(len(v))
-	case int, int32, int64, uint, uint32, uint64:
-		return 8
-	case float32, float64:
-		return 8
-	case bool:
-		return 1
-	default:
-		// For complex types, use a default estimate
-		return 256
-	}
-}
-
-// matchPattern checks if a key matches a pattern (simplified glob matching)
-func matchPattern(pattern, key string) bool {
-	if pattern == "*" {
-		return true
-	}
-	// Simplified pattern matching
-	if len(pattern) > 0 && pattern[0] == '*' {
-		suffix := pattern[1:]
-		return len(key) >= len(suffix) && key[len(key)-len(suffix):] == suffix
-	}
-	return key == pattern
-}

internal/cache/backends/memory_bench_test.go

@@ -1,182 +0,0 @@
-package backends
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	"github.com/alicebob/miniredis/v2"
-)
-
-// setupBenchmarkRedis creates a miniredis instance for benchmarking
-func setupBenchmarkRedis(b *testing.B) string {
-	b.Helper()
-	mr, err := miniredis.Run()
-	if err != nil {
-		b.Fatal(err)
-	}
-	b.Cleanup(func() {
-		mr.Close()
-	})
-	return mr.Addr()
-}
-
-// BenchmarkRedisOperations_WithPooling benchmarks memory allocations with object pooling
-func BenchmarkRedisOperations_WithPooling(b *testing.B) {
-	addr := setupBenchmarkRedis(b)
-
-	config := &PoolConfig{
-		Address:        addr,
-		MaxConnections: 10,
-		ConnectTimeout: 5 * time.Second,
-	}
-
-	pool, err := NewConnectionPool(config)
-	if err != nil {
-		b.Fatal(err)
-	}
-	defer pool.Close()
-
-	ctx := context.Background()
-
-	b.ReportAllocs()
-	b.ResetTimer()
-
-	for i := 0; i < b.N; i++ {
-		conn, err := pool.Get(ctx)
-		if err != nil {
-			b.Fatal(err)
-		}
-
-		// Perform various operations
-		_, _ = conn.Do("SET", "bench-key", "bench-value")
-		_, _ = conn.Do("GET", "bench-key")
-		_, _ = conn.Do("EXISTS", "bench-key")
-		_, _ = conn.Do("DEL", "bench-key")
-
-		pool.Put(conn)
-	}
-}
-
-// BenchmarkRedisBackend_SetGet benchmarks the full backend with pooling
-func BenchmarkRedisBackend_SetGet(b *testing.B) {
-	addr := setupBenchmarkRedis(b)
-
-	backend, err := NewRedisBackend(&Config{
-		RedisAddr: addr,
-		PoolSize:  10,
-	})
-	if err != nil {
-		b.Fatal(err)
-	}
-	defer backend.Close()
-
-	ctx := context.Background()
-	testData := []byte("benchmark test data with some content")
-
-	b.ReportAllocs()
-	b.ResetTimer()
-
-	for i := 0; i < b.N; i++ {
-		// Set operation
-		err := backend.Set(ctx, "bench-key", testData, 0)
-		if err != nil {
-			b.Fatal(err)
-		}
-
-		// Get operation
-		_, _, _, err = backend.Get(ctx, "bench-key")
-		if err != nil {
-			b.Fatal(err)
-		}
-	}
-}
-
-// BenchmarkRedisBackend_ConcurrentAccess benchmarks concurrent operations with pooling
-func BenchmarkRedisBackend_ConcurrentAccess(b *testing.B) {
-	addr := setupBenchmarkRedis(b)
-
-	backend, err := NewRedisBackend(&Config{
-		RedisAddr: addr,
-		PoolSize:  10,
-	})
-	if err != nil {
-		b.Fatal(err)
-	}
-	defer backend.Close()
-
-	ctx := context.Background()
-	testData := []byte("concurrent benchmark data")
-
-	b.ReportAllocs()
-	b.ResetTimer()
-
-	b.RunParallel(func(pb *testing.PB) {
-		for pb.Next() {
-			_ = backend.Set(ctx, "concurrent-key", testData, 0)
-			_, _, _, _ = backend.Get(ctx, "concurrent-key")
-		}
-	})
-}
-
-// BenchmarkRESPProtocol_WriteRead benchmarks RESP protocol encoding/decoding
-func BenchmarkRESPProtocol_WriteRead(b *testing.B) {
-	addr := setupBenchmarkRedis(b)
-
-	config := &PoolConfig{
-		Address:        addr,
-		MaxConnections: 10,
-		ConnectTimeout: 5 * time.Second,
-	}
-
-	pool, err := NewConnectionPool(config)
-	if err != nil {
-		b.Fatal(err)
-	}
-	defer pool.Close()
-
-	ctx := context.Background()
-	conn, err := pool.Get(ctx)
-	if err != nil {
-		b.Fatal(err)
-	}
-	defer pool.Put(conn)
-
-	b.ReportAllocs()
-	b.ResetTimer()
-
-	for i := 0; i < b.N; i++ {
-		// This tests the pooling of RESPReader/RESPWriter
-		_, _ = conn.Do("PING")
-	}
-}
-
-// BenchmarkConnectionPool_GetPut benchmarks connection pool operations
-func BenchmarkConnectionPool_GetPut(b *testing.B) {
-	addr := setupBenchmarkRedis(b)
-
-	config := &PoolConfig{
-		Address:        addr,
-		MaxConnections: 10,
-		ConnectTimeout: 5 * time.Second,
-	}
-
-	pool, err := NewConnectionPool(config)
-	if err != nil {
-		b.Fatal(err)
-	}
-	defer pool.Close()
-
-	ctx := context.Background()
-
-	b.ReportAllocs()
-	b.ResetTimer()
-
-	for i := 0; i < b.N; i++ {
-		conn, err := pool.Get(ctx)
-		if err != nil {
-			b.Fatal(err)
-		}
-		pool.Put(conn)
-	}
-}

internal/cache/backends/memory_shard.go

@@ -1,294 +0,0 @@
-package backends
-
-import (
-	"container/list"
-	"sync"
-	"time"
-)
-
-// cacheShard represents a single shard of the sharded cache
-// Each shard has its own lock for reduced contention
-type cacheShard struct {
-	items      map[string]*memoryCacheItem
-	lruList    *list.List
-	mu         sync.RWMutex
-	maxSize    int64
-	maxMemory  int64
-	size       int64
-	memoryUsed int64
-}
-
-// newCacheShard creates a new cache shard
-func newCacheShard(maxSize, maxMemory int64) *cacheShard {
-	return &cacheShard{
-		items:     make(map[string]*memoryCacheItem),
-		lruList:   list.New(),
-		maxSize:   maxSize,
-		maxMemory: maxMemory,
-	}
-}
-
-// get retrieves a value from this shard
-// Returns: value, exists, expired
-func (s *cacheShard) get(key string) (interface{}, bool, bool) {
-	s.mu.RLock()
-	item, exists := s.items[key]
-	s.mu.RUnlock()
-
-	if !exists {
-		return nil, false, false
-	}
-
-	if item.isExpired() {
-		return nil, true, true // exists but expired
-	}
-
-	// Update access time and LRU position under write lock
-	s.mu.Lock()
-	// Re-check item exists (could have been deleted)
-	item, exists = s.items[key]
-	if exists && !item.isExpired() {
-		item.accessedAt = time.Now()
-		item.accessCount++
-		if elem, ok := item.element.(*list.Element); ok && elem != nil {
-			s.lruList.MoveToFront(elem)
-		}
-	}
-	s.mu.Unlock()
-
-	if !exists || item.isExpired() {
-		return nil, false, false
-	}
-
-	return item.value, true, false
-}
-
-// set stores a value in this shard
-func (s *cacheShard) set(key string, value interface{}, expiresAt time.Time, size int64) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-
-	// Check if we need to evict items
-	if s.maxSize > 0 && s.size >= s.maxSize {
-		s.evictLRULocked()
-	}
-	if s.maxMemory > 0 && s.memoryUsed+size > s.maxMemory {
-		s.evictLRULocked()
-	}
-
-	// Remove old item if exists
-	if oldItem, exists := s.items[key]; exists {
-		s.memoryUsed -= oldItem.size
-		if elem, ok := oldItem.element.(*list.Element); ok && elem != nil {
-			s.lruList.Remove(elem)
-		}
-		s.size--
-	}
-
-	now := time.Now()
-	item := &memoryCacheItem{
-		key:         key,
-		value:       value,
-		expiresAt:   expiresAt,
-		createdAt:   now,
-		accessedAt:  now,
-		accessCount: 0,
-		size:        size,
-	}
-
-	item.element = s.lruList.PushFront(item)
-	s.items[key] = item
-	s.size++
-	s.memoryUsed += size
-}
-
-// delete removes a key from this shard
-// Returns true if the key was deleted
-func (s *cacheShard) delete(key string) bool {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-
-	item, exists := s.items[key]
-	if !exists {
-		return false
-	}
-
-	s.deleteItemLocked(item)
-	return true
-}
-
-// exists checks if a key exists (and is not expired)
-func (s *cacheShard) exists(key string) bool {
-	s.mu.RLock()
-	item, exists := s.items[key]
-	s.mu.RUnlock()
-
-	if !exists {
-		return false
-	}
-
-	return !item.isExpired()
-}
-
-// ttl returns the remaining TTL for a key
-func (s *cacheShard) ttl(key string) (time.Duration, bool) {
-	s.mu.RLock()
-	item, exists := s.items[key]
-	s.mu.RUnlock()
-
-	if !exists || item.isExpired() {
-		return 0, false
-	}
-
-	if item.expiresAt.IsZero() {
-		return 0, true // No expiration
-	}
-
-	remaining := time.Until(item.expiresAt)
-	if remaining < 0 {
-		return 0, false
-	}
-
-	return remaining, true
-}
-
-// expire updates the TTL for an existing key
-func (s *cacheShard) expire(key string, ttl time.Duration) bool {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-
-	item, exists := s.items[key]
-	if !exists || item.isExpired() {
-		return false
-	}
-
-	if ttl > 0 {
-		item.expiresAt = time.Now().Add(ttl)
-	} else {
-		item.expiresAt = time.Time{} // Remove expiration
-	}
-
-	return true
-}
-
-// keys returns all non-expired keys matching the pattern
-func (s *cacheShard) keys(pattern string) []string {
-	s.mu.RLock()
-	defer s.mu.RUnlock()
-
-	var keys []string
-	for key, item := range s.items {
-		if !item.isExpired() && matchPattern(pattern, key) {
-			keys = append(keys, key)
-		}
-	}
-	return keys
-}
-
-// clear removes all items from this shard
-func (s *cacheShard) clear() {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-
-	s.items = make(map[string]*memoryCacheItem)
-	s.lruList.Init()
-	s.size = 0
-	s.memoryUsed = 0
-}
-
-// cleanup removes expired items
-// Returns the number of items removed
-func (s *cacheShard) cleanup() int {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-
-	var toRemove []*memoryCacheItem
-	for _, item := range s.items {
-		if item.isExpired() {
-			toRemove = append(toRemove, item)
-		}
-	}
-
-	for _, item := range toRemove {
-		s.deleteItemLocked(item)
-	}
-
-	return len(toRemove)
-}
-
-// stats returns statistics for this shard
-func (s *cacheShard) stats() (size, memory int64) {
-	s.mu.RLock()
-	defer s.mu.RUnlock()
-	return s.size, s.memoryUsed
-}
-
-// deleteItemLocked removes an item (must be called with lock held)
-func (s *cacheShard) deleteItemLocked(item *memoryCacheItem) {
-	if elem, ok := item.element.(*list.Element); ok && elem != nil {
-		s.lruList.Remove(elem)
-	}
-	delete(s.items, item.key)
-	s.size--
-	s.memoryUsed -= item.size
-}
-
-// evictLRULocked evicts the least recently used item (must be called with lock held)
-func (s *cacheShard) evictLRULocked() bool {
-	if s.lruList.Len() == 0 {
-		return false
-	}
-
-	element := s.lruList.Back()
-	if element != nil {
-		item, ok := element.Value.(*memoryCacheItem)
-		if ok {
-			s.deleteItemLocked(item)
-			return true
-		}
-	}
-	return false
-}
-
-// evictOne evicts one item from this shard (for global limit enforcement)
-func (s *cacheShard) evictOne() bool {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	return s.evictLRULocked()
-}
-
-// getOldestAccessTime returns the access time of the LRU item (oldest) in this shard
-// Returns zero time if shard is empty
-func (s *cacheShard) getOldestAccessTime() time.Time {
-	s.mu.RLock()
-	defer s.mu.RUnlock()
-
-	if s.lruList.Len() == 0 {
-		return time.Time{}
-	}
-
-	element := s.lruList.Back()
-	if element != nil {
-		item, ok := element.Value.(*memoryCacheItem)
-		if ok {
-			return item.accessedAt
-		}
-	}
-	return time.Time{}
-}
-
-// fnv32 computes FNV-1a hash of a string
-// This is a fast, well-distributed hash function
-func fnv32(key string) uint32 {
-	const (
-		offset32 = uint32(2166136261)
-		prime32  = uint32(16777619)
-	)
-
-	hash := offset32
-	for i := 0; i < len(key); i++ {
-		hash ^= uint32(key[i])
-		hash *= prime32
-	}
-	return hash
-}

internal/cache/backends/memory_shard_test.go

@@ -1,283 +0,0 @@
-package backends
-
-import (
-	"context"
-	"fmt"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// TestShardedCache_ShardDistribution tests that keys are distributed across shards
-func TestShardedCache_ShardDistribution(t *testing.T) {
-	t.Parallel()
-
-	// Create a cache with large enough size to have multiple shards
-	config := DefaultConfig()
-	config.MaxSize = 10000
-	config.MaxMemoryBytes = 100 * 1024 * 1024 // 100MB
-
-	backend, err := NewMemoryBackend(config)
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	// Add many items to see distribution
-	numItems := 1000
-	for i := 0; i < numItems; i++ {
-		key := fmt.Sprintf("dist-key-%d", i)
-		value := []byte(fmt.Sprintf("dist-value-%d", i))
-		err := backend.Set(ctx, key, value, time.Minute)
-		require.NoError(t, err)
-	}
-
-	// Check that items are distributed across multiple shards
-	shardStats := backend.MemoryCacheBackend.GetShardStats()
-	nonEmptyShards := 0
-	for _, stat := range shardStats {
-		if stat["size"] > 0 {
-			nonEmptyShards++
-		}
-	}
-
-	// With good hash distribution, we should have items in multiple shards
-	assert.Greater(t, nonEmptyShards, 1, "Items should be distributed across multiple shards")
-}
-
-// TestShardedCache_ShardCount tests that shard count adapts to cache size
-func TestShardedCache_ShardCount(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		maxSize         int
-		expectLowShards bool
-	}{
-		{5, true},      // Very small cache should have fewer shards
-		{100, true},    // Small cache should have fewer shards
-		{10000, false}, // Large cache should have default shards
-	}
-
-	for _, tt := range tests {
-		t.Run(fmt.Sprintf("MaxSize_%d", tt.maxSize), func(t *testing.T) {
-			config := DefaultConfig()
-			config.MaxSize = tt.maxSize
-
-			backend, err := NewMemoryBackend(config)
-			require.NoError(t, err)
-			defer backend.Close()
-
-			shardCount := backend.MemoryCacheBackend.GetShardCount()
-
-			if tt.expectLowShards {
-				assert.Less(t, shardCount, uint32(256), "Small cache should have fewer shards")
-			} else {
-				assert.Equal(t, uint32(256), shardCount, "Large cache should have default shard count")
-			}
-		})
-	}
-}
-
-// TestShardedCache_ConcurrentSameKey tests concurrent access to the same key
-func TestShardedCache_ConcurrentSameKey(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-	key := "concurrent-same-key"
-	initialValue := []byte("initial-value")
-
-	err = backend.Set(ctx, key, initialValue, time.Minute)
-	require.NoError(t, err)
-
-	var wg sync.WaitGroup
-	goroutines := 50
-	iterations := 100
-
-	for i := 0; i < goroutines; i++ {
-		wg.Add(1)
-		go func(id int) {
-			defer wg.Done()
-			for j := 0; j < iterations; j++ {
-				// Mix of reads and writes
-				if j%3 == 0 {
-					newValue := []byte(fmt.Sprintf("value-%d-%d", id, j))
-					err := backend.Set(ctx, key, newValue, time.Minute)
-					assert.NoError(t, err)
-				} else {
-					_, _, _, err := backend.Get(ctx, key)
-					assert.NoError(t, err)
-				}
-			}
-		}(i)
-	}
-
-	wg.Wait()
-
-	// Key should still exist
-	exists, err := backend.Exists(ctx, key)
-	require.NoError(t, err)
-	assert.True(t, exists)
-}
-
-// TestShardedCache_GlobalLRUEviction tests that global LRU is maintained
-func TestShardedCache_GlobalLRUEviction(t *testing.T) {
-	t.Parallel()
-
-	// Create a small cache to force eviction
-	config := DefaultConfig()
-	config.MaxSize = 10
-
-	backend, err := NewMemoryBackend(config)
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	// Add items
-	for i := 0; i < 10; i++ {
-		key := fmt.Sprintf("global-lru-%d", i)
-		value := []byte(fmt.Sprintf("value-%d", i))
-		err := backend.Set(ctx, key, value, time.Minute)
-		require.NoError(t, err)
-		// Small delay to ensure different access times
-		time.Sleep(time.Millisecond)
-	}
-
-	// Access some items to make them recently used
-	for i := 5; i < 10; i++ {
-		key := fmt.Sprintf("global-lru-%d", i)
-		_, _, _, err := backend.Get(ctx, key)
-		require.NoError(t, err)
-	}
-
-	// Add more items to trigger eviction
-	for i := 10; i < 15; i++ {
-		key := fmt.Sprintf("global-lru-%d", i)
-		value := []byte(fmt.Sprintf("value-%d", i))
-		err := backend.Set(ctx, key, value, time.Minute)
-		require.NoError(t, err)
-	}
-
-	// Recently accessed items (5-9) should still exist
-	for i := 5; i < 10; i++ {
-		key := fmt.Sprintf("global-lru-%d", i)
-		exists, err := backend.Exists(ctx, key)
-		require.NoError(t, err)
-		assert.True(t, exists, "Recently accessed item %d should exist", i)
-	}
-
-	// Check eviction stats
-	stats := backend.GetStats()
-	evictions := stats["evictions"].(int64)
-	assert.Greater(t, evictions, int64(0), "Should have evictions")
-}
-
-// TestShardedCache_StatsAggregation tests that stats are aggregated correctly
-func TestShardedCache_StatsAggregation(t *testing.T) {
-	t.Parallel()
-
-	config := DefaultConfig()
-	config.MaxSize = 10000
-
-	backend, err := NewMemoryBackend(config)
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	// Add items to multiple shards
-	numItems := 100
-	for i := 0; i < numItems; i++ {
-		key := fmt.Sprintf("stats-key-%d", i)
-		value := []byte(fmt.Sprintf("stats-value-%d", i))
-		err := backend.Set(ctx, key, value, time.Minute)
-		require.NoError(t, err)
-	}
-
-	// Read some items
-	for i := 0; i < numItems/2; i++ {
-		key := fmt.Sprintf("stats-key-%d", i)
-		backend.Get(ctx, key)
-	}
-
-	// Read non-existent items
-	for i := 0; i < 10; i++ {
-		backend.Get(ctx, fmt.Sprintf("nonexistent-%d", i))
-	}
-
-	stats := backend.GetStats()
-
-	// Verify stats
-	assert.Equal(t, int64(numItems), stats["sets"].(int64), "Sets should match")
-	assert.Equal(t, int64(numItems/2), stats["hits"].(int64), "Hits should match")
-	assert.Equal(t, int64(10), stats["misses"].(int64), "Misses should match")
-	assert.Equal(t, int64(numItems), stats["size"].(int64), "Size should match")
-
-	// Verify hit rate
-	hitRate := stats["hit_rate"].(float64)
-	expectedHitRate := float64(numItems/2) / float64(numItems/2+10)
-	assert.InDelta(t, expectedHitRate, hitRate, 0.01, "Hit rate should match")
-}
-
-// BenchmarkShardedCache_Parallel benchmarks parallel access
-func BenchmarkShardedCache_Parallel(b *testing.B) {
-	config := DefaultConfig()
-	config.MaxSize = 100000
-	config.MaxMemoryBytes = 100 * 1024 * 1024
-
-	backend, _ := NewMemoryBackend(config)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	// Pre-populate cache
-	for i := 0; i < 10000; i++ {
-		key := fmt.Sprintf("bench-key-%d", i)
-		value := []byte(fmt.Sprintf("bench-value-%d", i))
-		backend.Set(ctx, key, value, time.Hour)
-	}
-
-	b.ResetTimer()
-	b.RunParallel(func(pb *testing.PB) {
-		i := 0
-		for pb.Next() {
-			key := fmt.Sprintf("bench-key-%d", i%10000)
-			backend.Get(ctx, key)
-			i++
-		}
-	})
-}
-
-// BenchmarkShardedCache_MixedOps benchmarks mixed operations
-func BenchmarkShardedCache_MixedOps(b *testing.B) {
-	config := DefaultConfig()
-	config.MaxSize = 100000
-	config.MaxMemoryBytes = 100 * 1024 * 1024
-
-	backend, _ := NewMemoryBackend(config)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	b.ResetTimer()
-	b.RunParallel(func(pb *testing.PB) {
-		i := 0
-		for pb.Next() {
-			key := fmt.Sprintf("mixed-key-%d", i%1000)
-			if i%3 == 0 {
-				value := []byte(fmt.Sprintf("mixed-value-%d", i))
-				backend.Set(ctx, key, value, time.Hour)
-			} else {
-				backend.Get(ctx, key)
-			}
-			i++
-		}
-	})
-}

internal/cache/backends/memory_test.go

@@ -1,783 +0,0 @@
-package backends
-
-import (
-	"context"
-	"fmt"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// TestMemoryBackend_BasicOperations tests basic CRUD operations
-func TestMemoryBackend_BasicOperations(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	t.Run("SetAndGet", func(t *testing.T) {
-		key := "test-key"
-		value := []byte("test-value")
-		ttl := 1 * time.Minute
-
-		err := backend.Set(ctx, key, value, ttl)
-		require.NoError(t, err)
-
-		retrieved, remainingTTL, exists, err := backend.Get(ctx, key)
-		require.NoError(t, err)
-		assert.True(t, exists)
-		assert.Equal(t, value, retrieved)
-		assert.Greater(t, remainingTTL, 50*time.Second)
-		assert.LessOrEqual(t, remainingTTL, ttl)
-	})
-
-	t.Run("GetNonExistent", func(t *testing.T) {
-		_, _, exists, err := backend.Get(ctx, "non-existent")
-		require.NoError(t, err)
-		assert.False(t, exists)
-	})
-
-	t.Run("Delete", func(t *testing.T) {
-		key := "delete-key"
-		value := []byte("delete-value")
-
-		err := backend.Set(ctx, key, value, 1*time.Minute)
-		require.NoError(t, err)
-
-		deleted, err := backend.Delete(ctx, key)
-		require.NoError(t, err)
-		assert.True(t, deleted)
-
-		exists, err := backend.Exists(ctx, key)
-		require.NoError(t, err)
-		assert.False(t, exists)
-	})
-
-	t.Run("DeleteNonExistent", func(t *testing.T) {
-		deleted, err := backend.Delete(ctx, "non-existent-delete")
-		require.NoError(t, err)
-		assert.False(t, deleted)
-	})
-
-	t.Run("Exists", func(t *testing.T) {
-		key := "exists-key"
-		value := []byte("exists-value")
-
-		exists, err := backend.Exists(ctx, key)
-		require.NoError(t, err)
-		assert.False(t, exists)
-
-		err = backend.Set(ctx, key, value, 1*time.Minute)
-		require.NoError(t, err)
-
-		exists, err = backend.Exists(ctx, key)
-		require.NoError(t, err)
-		assert.True(t, exists)
-	})
-
-	t.Run("Clear", func(t *testing.T) {
-		// Add multiple items
-		for i := 0; i < 10; i++ {
-			key := fmt.Sprintf("clear-key-%d", i)
-			value := []byte(fmt.Sprintf("clear-value-%d", i))
-			err := backend.Set(ctx, key, value, 1*time.Minute)
-			require.NoError(t, err)
-		}
-
-		err := backend.Clear(ctx)
-		require.NoError(t, err)
-
-		stats := backend.GetStats()
-		size := stats["size"].(int64)
-		assert.Equal(t, int64(0), size)
-	})
-}
-
-// TestMemoryBackend_TTLExpiration tests TTL and expiration
-func TestMemoryBackend_TTLExpiration(t *testing.T) {
-	t.Parallel()
-
-	config := DefaultConfig()
-	config.CleanupInterval = 50 * time.Millisecond
-	backend, err := NewMemoryBackend(config)
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	t.Run("ShortTTL", func(t *testing.T) {
-		key := "short-ttl-key"
-		value := []byte("short-ttl-value")
-		shortTTL := 100 * time.Millisecond
-
-		err := backend.Set(ctx, key, value, shortTTL)
-		require.NoError(t, err)
-
-		// Verify exists immediately
-		exists, err := backend.Exists(ctx, key)
-		require.NoError(t, err)
-		assert.True(t, exists)
-
-		// Wait for expiration
-		time.Sleep(150 * time.Millisecond)
-
-		// Should be expired
-		_, _, exists, err = backend.Get(ctx, key)
-		require.NoError(t, err)
-		assert.False(t, exists)
-	})
-
-	t.Run("TTLDecrement", func(t *testing.T) {
-		key := "ttl-decrement-key"
-		value := []byte("ttl-decrement-value")
-		ttl := 2 * time.Second
-
-		err := backend.Set(ctx, key, value, ttl)
-		require.NoError(t, err)
-
-		// Check TTL immediately
-		_, ttl1, exists, err := backend.Get(ctx, key)
-		require.NoError(t, err)
-		assert.True(t, exists)
-
-		// Wait a bit
-		time.Sleep(500 * time.Millisecond)
-
-		// Check TTL again - should be less
-		_, ttl2, exists, err := backend.Get(ctx, key)
-		require.NoError(t, err)
-		assert.True(t, exists)
-		assert.Less(t, ttl2, ttl1, "TTL should decrease over time")
-	})
-
-	t.Run("CleanupExpiredItems", func(t *testing.T) {
-		// Set multiple items with short TTL
-		for i := 0; i < 5; i++ {
-			key := fmt.Sprintf("cleanup-key-%d", i)
-			value := []byte(fmt.Sprintf("cleanup-value-%d", i))
-			err := backend.Set(ctx, key, value, 50*time.Millisecond)
-			require.NoError(t, err)
-		}
-
-		// Wait for cleanup to run
-		time.Sleep(200 * time.Millisecond)
-
-		// All items should be cleaned up
-		for i := 0; i < 5; i++ {
-			key := fmt.Sprintf("cleanup-key-%d", i)
-			exists, err := backend.Exists(ctx, key)
-			require.NoError(t, err)
-			assert.False(t, exists, "Expired items should be cleaned up")
-		}
-	})
-}
-
-// TestMemoryBackend_LRUEviction tests LRU eviction
-func TestMemoryBackend_LRUEviction(t *testing.T) {
-	t.Parallel()
-
-	config := DefaultConfig()
-	config.MaxSize = 5
-	backend, err := NewMemoryBackend(config)
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	// Fill cache to max size
-	for i := 0; i < 5; i++ {
-		key := fmt.Sprintf("lru-key-%d", i)
-		value := []byte(fmt.Sprintf("lru-value-%d", i))
-		err := backend.Set(ctx, key, value, 1*time.Minute)
-		require.NoError(t, err)
-	}
-
-	// Access first item to make it most recently used
-	_, _, exists, err := backend.Get(ctx, "lru-key-0")
-	require.NoError(t, err)
-	assert.True(t, exists)
-
-	// Add a new item - should evict lru-key-1 (least recently used)
-	err = backend.Set(ctx, "lru-key-new", []byte("new-value"), 1*time.Minute)
-	require.NoError(t, err)
-
-	// lru-key-0 should still exist (was accessed recently)
-	exists, err = backend.Exists(ctx, "lru-key-0")
-	require.NoError(t, err)
-	assert.True(t, exists, "Recently accessed item should not be evicted")
-
-	// lru-key-1 should be evicted
-	exists, err = backend.Exists(ctx, "lru-key-1")
-	require.NoError(t, err)
-	assert.False(t, exists, "Least recently used item should be evicted")
-
-	// Check eviction count
-	stats := backend.GetStats()
-	evictions := stats["evictions"].(int64)
-	assert.Greater(t, evictions, int64(0), "Should have evictions")
-}
-
-// TestMemoryBackend_MemoryLimit tests memory-based eviction
-func TestMemoryBackend_MemoryLimit(t *testing.T) {
-	t.Parallel()
-
-	config := DefaultConfig()
-	config.MaxSize = 100
-	config.MaxMemoryBytes = 1024 // 1KB limit
-	backend, err := NewMemoryBackend(config)
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	// Add items until memory limit is reached
-	largeValue := make([]byte, 512) // 512 bytes each
-	for i := 0; i < 5; i++ {
-		key := fmt.Sprintf("mem-key-%d", i)
-		err := backend.Set(ctx, key, largeValue, 1*time.Minute)
-		require.NoError(t, err)
-	}
-
-	stats := backend.GetStats()
-	memory := stats["memory"].(int64)
-	assert.LessOrEqual(t, memory, config.MaxMemoryBytes, "Memory should not exceed limit")
-
-	evictions := stats["evictions"].(int64)
-	assert.Greater(t, evictions, int64(0), "Should have memory-based evictions")
-}
-
-// TestMemoryBackend_ConcurrentAccess tests thread safety
-func TestMemoryBackend_ConcurrentAccess(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-	var wg sync.WaitGroup
-	goroutines := 20
-	iterations := 50
-
-	// Concurrent writes
-	for i := 0; i < goroutines; i++ {
-		wg.Add(1)
-		go func(id int) {
-			defer wg.Done()
-			for j := 0; j < iterations; j++ {
-				key := fmt.Sprintf("concurrent-key-%d-%d", id, j)
-				value := []byte(fmt.Sprintf("concurrent-value-%d-%d", id, j))
-
-				err := backend.Set(ctx, key, value, 1*time.Minute)
-				assert.NoError(t, err)
-
-				// Read back
-				retrieved, _, exists, err := backend.Get(ctx, key)
-				assert.NoError(t, err)
-				if exists {
-					assert.Equal(t, value, retrieved)
-				}
-
-				// Random deletes
-				if j%5 == 0 {
-					backend.Delete(ctx, key)
-				}
-			}
-		}(i)
-	}
-
-	wg.Wait()
-
-	// Verify stats are consistent
-	stats := backend.GetStats()
-	hits := stats["hits"].(int64)
-	misses := stats["misses"].(int64)
-	assert.Greater(t, hits+misses, int64(0), "Should have cache operations")
-}
-
-// TestMemoryBackend_UpdateExisting tests updating existing keys
-func TestMemoryBackend_UpdateExisting(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	key := "update-key"
-	value1 := []byte("original-value")
-	value2 := []byte("updated-value")
-
-	// Set original
-	err = backend.Set(ctx, key, value1, 1*time.Minute)
-	require.NoError(t, err)
-
-	// Update
-	err = backend.Set(ctx, key, value2, 2*time.Minute)
-	require.NoError(t, err)
-
-	// Verify updated
-	retrieved, ttl, exists, err := backend.Get(ctx, key)
-	require.NoError(t, err)
-	assert.True(t, exists)
-	assert.Equal(t, value2, retrieved)
-	assert.Greater(t, ttl, 1*time.Minute, "TTL should be updated")
-
-	// Size should not increase (same key)
-	stats := backend.GetStats()
-	size := stats["size"].(int64)
-	assert.Equal(t, int64(1), size, "Size should be 1 for one key")
-}
-
-// TestMemoryBackend_Stats tests statistics tracking
-func TestMemoryBackend_Stats(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	// Initial stats
-	stats := backend.GetStats()
-	assert.Equal(t, int64(0), stats["hits"].(int64))
-	assert.Equal(t, int64(0), stats["misses"].(int64))
-
-	// Add items and track hits/misses
-	backend.Set(ctx, "key1", []byte("value1"), 1*time.Minute)
-	backend.Set(ctx, "key2", []byte("value2"), 1*time.Minute)
-
-	// Hit
-	backend.Get(ctx, "key1")
-	// Miss
-	backend.Get(ctx, "non-existent")
-
-	stats = backend.GetStats()
-	assert.Equal(t, int64(1), stats["hits"].(int64))
-	assert.Equal(t, int64(1), stats["misses"].(int64))
-
-	hitRate := stats["hit_rate"].(float64)
-	assert.InDelta(t, 0.5, hitRate, 0.01)
-}
-
-// TestMemoryBackend_EmptyValues tests handling of empty values
-func TestMemoryBackend_EmptyValues(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	key := "empty-key"
-	emptyValue := []byte{}
-
-	err = backend.Set(ctx, key, emptyValue, 1*time.Minute)
-	require.NoError(t, err)
-
-	retrieved, _, exists, err := backend.Get(ctx, key)
-	require.NoError(t, err)
-	assert.True(t, exists)
-	assert.Equal(t, 0, len(retrieved))
-}
-
-// TestMemoryBackend_LargeValues tests handling of large values
-func TestMemoryBackend_LargeValues(t *testing.T) {
-	t.Parallel()
-
-	config := DefaultConfig()
-	config.MaxMemoryBytes = 10 * 1024 * 1024 // 10MB
-	backend, err := NewMemoryBackend(config)
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	key := "large-key"
-	largeValue := make([]byte, 1024*1024) // 1MB
-
-	err = backend.Set(ctx, key, largeValue, 1*time.Minute)
-	require.NoError(t, err)
-
-	retrieved, _, exists, err := backend.Get(ctx, key)
-	require.NoError(t, err)
-	assert.True(t, exists)
-	assert.Equal(t, len(largeValue), len(retrieved))
-}
-
-// TestMemoryBackend_Close tests proper cleanup on close
-func TestMemoryBackend_Close(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-
-	ctx := context.Background()
-
-	// Add some items
-	for i := 0; i < 10; i++ {
-		key := fmt.Sprintf("close-key-%d", i)
-		value := []byte(fmt.Sprintf("close-value-%d", i))
-		backend.Set(ctx, key, value, 1*time.Minute)
-	}
-
-	// Close
-	err = backend.Close()
-	require.NoError(t, err)
-
-	// Operations after close should fail
-	err = backend.Set(ctx, "after-close", []byte("value"), 1*time.Minute)
-	assert.Error(t, err)
-	assert.Equal(t, ErrBackendClosed, err)
-
-	_, _, _, err = backend.Get(ctx, "close-key-0")
-	assert.Error(t, err)
-	assert.Equal(t, ErrBackendClosed, err)
-
-	// Closing again should be safe
-	err = backend.Close()
-	assert.NoError(t, err)
-}
-
-// TestMemoryBackend_Ping tests ping operation
-func TestMemoryBackend_Ping(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	err = backend.Ping(ctx)
-	assert.NoError(t, err)
-
-	// Close and ping should fail
-	backend.Close()
-	err = backend.Ping(ctx)
-	assert.Error(t, err)
-}
-
-// TestMemoryBackend_ValueIsolation tests that returned values are isolated
-func TestMemoryBackend_ValueIsolation(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	key := "isolation-key"
-	originalValue := []byte("original-value")
-
-	err = backend.Set(ctx, key, originalValue, 1*time.Minute)
-	require.NoError(t, err)
-
-	// Get value and modify it
-	retrieved, _, exists, err := backend.Get(ctx, key)
-	require.NoError(t, err)
-	assert.True(t, exists)
-
-	// Modify retrieved value
-	if len(retrieved) > 0 {
-		retrieved[0] = 'X'
-	}
-
-	// Get again - should be unchanged
-	retrieved2, _, exists, err := backend.Get(ctx, key)
-	require.NoError(t, err)
-	assert.True(t, exists)
-	assert.Equal(t, originalValue, retrieved2, "Original value should not be modified")
-}
-
-// TestMemoryBackend_Keys tests the Keys method with pattern matching
-func TestMemoryBackend_Keys(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	// Add test data
-	testKeys := []string{"user:1", "user:2", "session:abc", "session:def", "token:xyz"}
-	for _, key := range testKeys {
-		err := backend.Set(ctx, key, []byte("value"), 1*time.Minute)
-		require.NoError(t, err)
-	}
-
-	t.Run("AllKeys", func(t *testing.T) {
-		keys, err := backend.Keys(ctx, "*")
-		require.NoError(t, err)
-		assert.Len(t, keys, 5)
-	})
-
-	t.Run("SpecificPattern", func(t *testing.T) {
-		// Simple exact match
-		keys, err := backend.Keys(ctx, "user:1")
-		require.NoError(t, err)
-		assert.Len(t, keys, 1)
-		assert.Contains(t, keys, "user:1")
-	})
-
-	t.Run("ExcludesExpired", func(t *testing.T) {
-		// Add an expired key
-		expiredKey := "expired:key"
-		err := backend.Set(ctx, expiredKey, []byte("value"), 1*time.Millisecond)
-		require.NoError(t, err)
-
-		// Wait for expiration
-		time.Sleep(10 * time.Millisecond)
-
-		keys, err := backend.Keys(ctx, "*")
-		require.NoError(t, err)
-		assert.NotContains(t, keys, expiredKey, "Expired keys should not be returned")
-	})
-
-	t.Run("AfterClose", func(t *testing.T) {
-		closedBackend, _ := NewMemoryBackend(DefaultConfig())
-		closedBackend.Close()
-
-		_, err := closedBackend.Keys(ctx, "*")
-		assert.Error(t, err)
-		assert.Equal(t, ErrBackendUnavailable, err)
-	})
-}
-
-// TestMemoryBackend_Size tests the Size method
-func TestMemoryBackend_Size(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	// Initially empty
-	size, err := backend.Size(ctx)
-	require.NoError(t, err)
-	assert.Equal(t, int64(0), size)
-
-	// Add items
-	for i := 0; i < 5; i++ {
-		key := fmt.Sprintf("key-%d", i)
-		err := backend.Set(ctx, key, []byte("value"), 1*time.Minute)
-		require.NoError(t, err)
-	}
-
-	size, err = backend.Size(ctx)
-	require.NoError(t, err)
-	assert.Equal(t, int64(5), size)
-
-	// Delete one
-	backend.Delete(ctx, "key-0")
-
-	size, err = backend.Size(ctx)
-	require.NoError(t, err)
-	assert.Equal(t, int64(4), size)
-
-	// After close
-	backend.Close()
-	_, err = backend.Size(ctx)
-	assert.Error(t, err)
-	assert.Equal(t, ErrBackendUnavailable, err)
-}
-
-// TestMemoryBackend_TTL tests the TTL method
-func TestMemoryBackend_TTL(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	t.Run("ExistingKey", func(t *testing.T) {
-		key := "ttl-key"
-		ttl := 1 * time.Minute
-
-		err := backend.Set(ctx, key, []byte("value"), ttl)
-		require.NoError(t, err)
-
-		remaining, err := backend.TTL(ctx, key)
-		require.NoError(t, err)
-		assert.Greater(t, remaining, 50*time.Second)
-		assert.LessOrEqual(t, remaining, ttl)
-	})
-
-	t.Run("NonExistentKey", func(t *testing.T) {
-		_, err := backend.TTL(ctx, "non-existent")
-		assert.Error(t, err)
-		assert.Equal(t, ErrCacheMiss, err)
-	})
-
-	t.Run("NoExpiration", func(t *testing.T) {
-		key := "no-expiry"
-		// TTL of 0 typically means no expiration
-		err := backend.Set(ctx, key, []byte("value"), 0)
-		require.NoError(t, err)
-
-		remaining, err := backend.TTL(ctx, key)
-		require.NoError(t, err)
-		// No expiration returns 0
-		assert.Equal(t, time.Duration(0), remaining)
-	})
-
-	t.Run("AfterClose", func(t *testing.T) {
-		closedBackend, _ := NewMemoryBackend(DefaultConfig())
-		closedBackend.Close()
-
-		_, err := closedBackend.TTL(ctx, "key")
-		assert.Error(t, err)
-		assert.Equal(t, ErrBackendUnavailable, err)
-	})
-}
-
-// TestMemoryBackend_Expire tests the Expire method
-func TestMemoryBackend_Expire(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	ctx := context.Background()
-
-	t.Run("UpdateTTL", func(t *testing.T) {
-		key := "expire-key"
-		err := backend.Set(ctx, key, []byte("value"), 1*time.Minute)
-		require.NoError(t, err)
-
-		// Update to shorter TTL
-		err = backend.Expire(ctx, key, 5*time.Second)
-		require.NoError(t, err)
-
-		// Check new TTL
-		remaining, err := backend.TTL(ctx, key)
-		require.NoError(t, err)
-		assert.LessOrEqual(t, remaining, 5*time.Second)
-	})
-
-	t.Run("NonExistentKey", func(t *testing.T) {
-		err := backend.Expire(ctx, "non-existent", 1*time.Minute)
-		assert.Error(t, err)
-		assert.Equal(t, ErrCacheMiss, err)
-	})
-
-	t.Run("RemoveExpiration", func(t *testing.T) {
-		key := "no-expire-key"
-		err := backend.Set(ctx, key, []byte("value"), 1*time.Minute)
-		require.NoError(t, err)
-
-		// Set TTL to 0 to remove expiration
-		err = backend.Expire(ctx, key, 0)
-		require.NoError(t, err)
-
-		// TTL should now be 0
-		remaining, err := backend.TTL(ctx, key)
-		require.NoError(t, err)
-		assert.Equal(t, time.Duration(0), remaining)
-	})
-
-	t.Run("AfterClose", func(t *testing.T) {
-		closedBackend, _ := NewMemoryBackend(DefaultConfig())
-		closedBackend.Close()
-
-		err := closedBackend.Expire(ctx, "key", 1*time.Minute)
-		assert.Error(t, err)
-		assert.Equal(t, ErrBackendUnavailable, err)
-	})
-}
-
-// TestMemoryBackend_IsHealthy tests the IsHealthy method
-func TestMemoryBackend_IsHealthy(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-
-	// Should be healthy when open
-	assert.True(t, backend.IsHealthy())
-
-	// Should be unhealthy after close
-	backend.Close()
-	assert.False(t, backend.IsHealthy())
-}
-
-// TestMemoryBackend_Type tests the Type method
-func TestMemoryBackend_Type(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	backendType := backend.Type()
-	assert.Equal(t, TypeMemory, backendType)
-}
-
-// TestMemoryBackend_Capabilities tests the Capabilities method
-func TestMemoryBackend_Capabilities(t *testing.T) {
-	t.Parallel()
-
-	backend, err := NewMemoryBackend(DefaultConfig())
-	require.NoError(t, err)
-	defer backend.Close()
-
-	caps := backend.Capabilities()
-	require.NotNil(t, caps)
-
-	// Memory backend should not be distributed or persistent
-	assert.False(t, caps.Distributed)
-	assert.False(t, caps.Persistent)
-
-	// Should support eviction and TTL
-	assert.True(t, caps.Eviction)
-	assert.True(t, caps.TTL)
-	assert.True(t, caps.SupportsExpire)
-	assert.True(t, caps.SupportsMultiGet)
-
-	// Check limits
-	assert.Greater(t, caps.MaxKeySize, int64(0))
-	assert.Greater(t, caps.MaxValueSize, int64(0))
-}
-
-// TestMatchPattern tests the matchPattern helper function
-func TestMatchPattern(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		pattern string
-		key     string
-		matches bool
-	}{
-		{"*", "any-key", true},
-		{"*", "another", true},
-		{"user:1", "user:1", true},
-		{"user:1", "user:2", false},
-		{"*:suffix", "prefix:suffix", true},
-		{"*suffix", "prefix-suffix", true},
-		{"*abc", "xyzabc", true},
-		{"*abc", "xyz", false},
-	}
-
-	for _, tt := range tests {
-		t.Run(fmt.Sprintf("%s-%s", tt.pattern, tt.key), func(t *testing.T) {
-			result := matchPattern(tt.pattern, tt.key)
-			assert.Equal(t, tt.matches, result)
-		})
-	}
-}

internal/cache/backends/memory_wrapper.go

@@ -1,143 +0,0 @@
-package backends
-
-import (
-	"context"
-	"time"
-)
-
-// MemoryBackend wraps MemoryCacheBackend to implement the CacheBackend interface
-type MemoryBackend struct {
-	*MemoryCacheBackend
-}
-
-// NewMemoryBackend creates a new memory backend from a config
-func NewMemoryBackend(config *Config) (*MemoryBackend, error) {
-	maxSize := int64(config.MaxSize)
-	if maxSize <= 0 {
-		maxSize = 1000
-	}
-
-	cacheBackend := NewMemoryCacheBackend(maxSize, config.MaxMemoryBytes, config.CleanupInterval)
-	return &MemoryBackend{
-		MemoryCacheBackend: cacheBackend,
-	}, nil
-}
-
-// Set stores a value in the cache with the specified TTL
-func (m *MemoryBackend) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error {
-	err := m.MemoryCacheBackend.Set(ctx, key, value, ttl)
-	if err == ErrBackendUnavailable {
-		return ErrBackendClosed
-	}
-	return err
-}
-
-// Get retrieves a value from the cache
-func (m *MemoryBackend) Get(ctx context.Context, key string) ([]byte, time.Duration, bool, error) {
-	val, err := m.MemoryCacheBackend.Get(ctx, key)
-	if err != nil {
-		if err == ErrCacheMiss {
-			return nil, 0, false, nil
-		}
-		if err == ErrBackendUnavailable {
-			return nil, 0, false, ErrBackendClosed
-		}
-		return nil, 0, false, err
-	}
-
-	// Get TTL using the TTL method
-	ttl, ttlErr := m.MemoryCacheBackend.TTL(ctx, key)
-	if ttlErr != nil {
-		// If we can't get TTL, still return the value with 0 TTL
-		ttl = 0
-	}
-
-	// Convert interface{} to []byte
-	var valueBytes []byte
-	if val != nil {
-		if bytes, ok := val.([]byte); ok {
-			valueBytes = bytes
-		} else {
-			// If it's not already []byte, return an error
-			return nil, 0, false, ErrInvalidValue
-		}
-	}
-
-	return valueBytes, ttl, true, nil
-}
-
-// Delete removes a key from the cache
-func (m *MemoryBackend) Delete(ctx context.Context, key string) (bool, error) {
-	// Check if key exists first
-	exists, err := m.MemoryCacheBackend.Exists(ctx, key)
-	if err != nil {
-		return false, err
-	}
-
-	if !exists {
-		return false, nil
-	}
-
-	err = m.MemoryCacheBackend.Delete(ctx, key)
-	if err != nil {
-		return false, err
-	}
-	return true, nil
-}
-
-// Exists checks if a key exists in the cache
-func (m *MemoryBackend) Exists(ctx context.Context, key string) (bool, error) {
-	return m.MemoryCacheBackend.Exists(ctx, key)
-}
-
-// Clear removes all keys from the cache
-func (m *MemoryBackend) Clear(ctx context.Context) error {
-	return m.MemoryCacheBackend.Clear(ctx)
-}
-
-// GetStats returns cache statistics
-func (m *MemoryBackend) GetStats() map[string]interface{} {
-	stats, err := m.MemoryCacheBackend.GetStats(context.Background())
-	if err != nil {
-		return map[string]interface{}{
-			"error": err.Error(),
-		}
-	}
-
-	// Convert BackendStats to map
-	hitRate := float64(0)
-	total := stats.Hits + stats.Misses
-	if total > 0 {
-		hitRate = float64(stats.Hits) / float64(total)
-	}
-
-	return map[string]interface{}{
-		"type":        stats.Type,
-		"hits":        stats.Hits,
-		"misses":      stats.Misses,
-		"sets":        stats.Sets,
-		"deletes":     stats.Deletes,
-		"errors":      stats.Errors,
-		"evictions":   stats.Evictions,
-		"size":        stats.CurrentSize,
-		"max_size":    stats.MaxSize,
-		"memory":      stats.MemoryUsage,
-		"hit_rate":    hitRate,
-		"uptime":      stats.Uptime,
-		"start_time":  stats.StartTime,
-		"shard_count": m.MemoryCacheBackend.GetShardCount(),
-	}
-}
-
-// Close shuts down the cache backend and releases resources
-func (m *MemoryBackend) Close() error {
-	return m.MemoryCacheBackend.Close()
-}
-
-// Ping checks if the backend is healthy and responsive
-func (m *MemoryBackend) Ping(ctx context.Context) error {
-	return m.MemoryCacheBackend.Ping(ctx)
-}
-
-// Ensure MemoryBackend implements CacheBackend
-var _ CacheBackend = (*MemoryBackend)(nil)

internal/cache/backends/redis.go

@@ -17,6 +17,15 @@ var (
 	ErrPoolExhausted = errors.New("connection pool exhausted")
 )
 
+// NoExpiryTTL is the sentinel RedisBackend.Get reports for a key that has
+// no associated expiry (Redis PTTL -1). It is distinct from a returned
+// ttl of 0, which means the key has under a millisecond left (or vanished
+// between GET and PTTL): the caller must not treat those two cases the
+// same way — folding "no expiry" into 0 made a caller that repopulates a
+// local copy on ttl<=0 re-cache a dying entry for its full DefaultTTL
+// (FIX-31).
+const NoExpiryTTL time.Duration = -1
+
 // RedisBackend implements a Redis-based cache backend using pure Go
 type RedisBackend struct {
 	config        *Config
@@ -95,7 +104,15 @@ func (r *RedisBackend) Set(ctx context.Context, key string, value []byte, ttl ti
 		return ErrBackendClosed
 	}
 
+	// A NEGATIVE TTL means "already expired" (the stack's convention for a
+	// value whose validity has passed). Previously ttl<=0 fell through to a
+	// bare SET with no expiry, silently making the entry permanent. Zero here
+	// is the documented "no expiry" contract (see SetManyNoTTL), so only
+	// strictly-negative TTLs are skipped.
 	prefixedKey := r.prefixKey(key)
+	if ttl < 0 {
+		return nil
+	}
 
 	// Execute with retry logic
 	return r.executeWithRetry(ctx, func(conn *RedisConn) error {
@@ -120,6 +137,157 @@ func (r *RedisBackend) Set(ctx context.Context, key string, value []byte, ttl ti
 	})
 }
 
+// SetNX stores a value in Redis only if the key does not already exist,
+// atomically, using Redis SET key value NX PX <ttl-ms> — one server-side
+// command rather than a Get followed by a Set, so two callers racing the
+// same key (e.g. two Traefik replicas racing the same backchannel-logout
+// jti) can never both observe "absent". Backs UniversalCache.SetIfAbsent's
+// distributed case (FIX-17): CacheBackend has no such primitive, and
+// widening it would force every implementer to add an operation only this
+// one caller needs, so UniversalCache reaches this through an optional
+// interface type assertion instead.
+//
+// Returns (true, nil) when this call claimed the key, (false, nil) when the
+// key already existed (someone else claimed it first — not an error),
+// (false, ErrSetNXAmbiguous) when the command reached the wire but its
+// reply could not be read at all (timeout, EOF, connection reset) — Redis
+// may or may not have applied it — and (false, err) on any other genuine
+// backend failure, INCLUDING a definitive RESP '-' command-error reply
+// (-READONLY, -OOM, -MISCONF, ...): that proves Redis read and rejected the
+// command, so it is never ambiguous (R4 cache review).
+//
+// SetNX runs its own retry loop rather than executeWithRetry (FIX-17
+// round-2): Set's SETEX/PSETEX are idempotent, so retrying one after a lost
+// reply just repeats the same unconditional write. SET NX is not — retrying
+// it after a lost reply would see this call's OWN possible write and
+// misreport a first-ever claim as already-claimed. So SetNX retries a
+// failed connection acquisition (nothing was sent yet, safe to retry) but
+// never re-sends SET NX once doTracked reports the command was written.
+func (r *RedisBackend) SetNX(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error) {
+	if r.closed.Load() {
+		return false, ErrBackendClosed
+	}
+
+	// Mirrors Set's TTL convention: negative means "already expired", so
+	// there is nothing to claim.
+	prefixedKey := r.prefixKey(key)
+	if ttl < 0 {
+		return false, nil
+	}
+
+	var args []string
+	if ttl > 0 {
+		ttlMillis := ttl.Milliseconds()
+		if ttlMillis < 1 {
+			ttlMillis = 1
+		}
+		args = []string{prefixedKey, string(value), "NX", "PX", fmt.Sprintf("%d", ttlMillis)}
+	} else {
+		args = []string{prefixedKey, string(value), "NX"}
+	}
+
+	maxRetries := 3
+	baseDelay := 50 * time.Millisecond
+
+	for attempt := 0; attempt < maxRetries; attempt++ {
+		if ctx.Err() != nil {
+			return false, ctx.Err()
+		}
+
+		conn, err := r.pool.Get(ctx)
+		if err != nil {
+			if attempt == maxRetries-1 {
+				return false, fmt.Errorf("failed to get connection after %d attempts: %w", maxRetries, err)
+			}
+			delay := baseDelay * time.Duration(1<<uint(attempt))
+			select {
+			case <-ctx.Done():
+				return false, ctx.Err()
+			case <-time.After(delay):
+				continue
+			}
+		}
+
+		var (
+			resp  interface{}
+			sent  bool
+			doErr error
+		)
+		func() {
+			defer func() { r.pool.Put(conn) }()
+			resp, sent, doErr = conn.doTracked("SET", args...)
+		}()
+
+		if doErr == nil {
+			if _, strErr := RESPString(resp); strErr != nil {
+				return false, strErr
+			}
+			return true, nil
+		}
+
+		if errors.Is(doErr, ErrNilResponse) {
+			// NX condition failed: the key already existed before this
+			// call. A valid protocol outcome, not an error — the
+			// connection is healthy and nothing here should be retried.
+			return false, nil
+		}
+
+		if errors.Is(doErr, ErrCommandReply) {
+			// A RESP '-' reply (e.g. -READONLY, -OOM, -MISCONF) proves
+			// Redis read the command and refused it — unlike a lost reply,
+			// this is a DEFINITIVE outcome: the SET NX was never applied.
+			// Reporting it as ErrSetNXAmbiguous would make
+			// checkAndMarkLogoutJTIProcessed accept the caller's claim
+			// outright (the ambiguous branch exists precisely to avoid a
+			// false replay report for a write that may have landed), which
+			// here would let a captured logout token replay forever while
+			// Redis rejects writes. Surface it as a plain error instead, so
+			// the caller falls through to its own local fallback.
+			return false, doErr
+		}
+
+		if sent {
+			// The command reached the wire before reading its reply
+			// failed (timeout, EOF, connection reset): Redis may have
+			// applied it. This is checked BEFORE ctx.Err() (FIX-17
+			// round-3): UniversalCache.setIfAbsentBackend gives SetNX a
+			// 500ms context, and the pool's read deadline on this same
+			// write is also 500ms, started strictly after the ctx
+			// deadline began ticking — so when a reply is lost, ctx has
+			// almost always already expired by the time this line runs.
+			// Checking ctx.Err() first therefore reported
+			// context.DeadlineExceeded for what is actually an ambiguous
+			// outcome, and checkAndMarkLogoutJTIProcessed does not
+			// special-case a plain deadline error: it fell through to the
+			// mutex-guarded Get+Set fallback, whose Get saw this call's
+			// own possible write and misreported a first-ever logout
+			// token as a replay. Retrying here (instead of returning) would
+			// see this call's own possible write and misreport a
+			// first-ever claim as already-claimed, same reasoning as
+			// above — surface the ambiguity instead of guessing.
+			return false, ErrSetNXAmbiguous
+		}
+
+		if ctx.Err() != nil {
+			return false, ctx.Err()
+		}
+
+		if attempt == maxRetries-1 || !isRetryableError(doErr) {
+			return false, doErr
+		}
+
+		delay := baseDelay * time.Duration(1<<uint(attempt))
+		select {
+		case <-ctx.Done():
+			return false, ctx.Err()
+		case <-time.After(delay):
+			continue
+		}
+	}
+
+	return false, fmt.Errorf("operation failed after %d attempts", maxRetries)
+}
+
 // Get retrieves a value from Redis
 func (r *RedisBackend) Get(ctx context.Context, key string) ([]byte, time.Duration, bool, error) {
 	if r.closed.Load() {
@@ -149,10 +317,14 @@ func (r *RedisBackend) Get(ctx context.Context, key string) ([]byte, time.Durati
 			return err
 		}
 
-		// Get TTL
-		ttlResp, err := conn.Do("TTL", prefixedKey)
+		// Get TTL with millisecond precision (PTTL, not TTL). TTL's second
+		// precision maps both "no expiry" (-1) and "under one second left"
+		// to a reported ttl of 0 once truncated to whole seconds, so a
+		// caller cannot tell them apart (FIX-31). PTTL keeps "no expiry"
+		// distinct via NoExpiryTTL.
+		ttlResp, err := conn.Do("PTTL", prefixedKey)
 		if err != nil {
-			// If TTL fails, still return the value
+			// If PTTL fails, still return the value; report no TTL info.
 			r.hits.Add(1)
 			resultValue = []byte(value)
 			resultTTL = 0
@@ -160,10 +332,18 @@ func (r *RedisBackend) Get(ctx context.Context, key string) ([]byte, time.Durati
 			return nil
 		}
 
-		ttlSeconds, _ := RESPInt(ttlResp)
+		ttlMillis, _ := RESPInt(ttlResp)
 		var ttl time.Duration
-		if ttlSeconds > 0 {
-			ttl = time.Duration(ttlSeconds) * time.Second
+		switch {
+		case ttlMillis == -1:
+			// Key exists with no associated expiry.
+			ttl = NoExpiryTTL
+		case ttlMillis > 0:
+			ttl = time.Duration(ttlMillis) * time.Millisecond
+		default:
+			// -2 (key vanished between GET and PTTL) or 0 (under 1ms
+			// left): report "expire now", not "no expiry".
+			ttl = 0
 		}
 
 		r.hits.Add(1)
@@ -376,20 +556,30 @@ func (r *RedisBackend) executeWithRetry(ctx context.Context, operation func(*Red
 			}
 		}
 
-		// Execute the operation
-		err = operation(conn)
-		r.pool.Put(conn)
+		// Execute the operation, guaranteeing the borrowed connection is
+		// returned to the pool even if the operation panics (previously a
+		// panic here leaked the connection and desynced the pool counters;
+		// other pool call sites use defer for this).
+		func() {
+			defer func() { r.pool.Put(conn) }()
+			err = operation(conn)
+		}()
+
+		// Check err == nil BEFORE ctx.Err(): the operation already completed
+		// against the connection (op returned), so a nil error means Redis
+		// applied it. Reporting ctx.Err() first would tell the caller (e.g.
+		// UniversalCache.Set) that a write failed when it actually landed,
+		// which previously triggered a Delete that erased the just-applied
+		// value (FIX-04).
+		if err == nil {
+			return nil
+		}
 
 		// Check context after operation - if canceled, don't bother retrying
 		if ctx.Err() != nil {
 			return ctx.Err()
 		}
 
-		// If successful, return
-		if err == nil {
-			return nil
-		}
-
 		// If error is not retryable or last attempt, fail
 		if attempt == maxRetries-1 || !isRetryableError(err) {
 			return err
@@ -445,6 +635,13 @@ func (r *RedisBackend) SetMany(ctx context.Context, items map[string][]byte, ttl
 		return nil
 	}
 
+	if ttl < 0 {
+		// Already-expired TTL: nothing to persist (see Set's guard). Avoids
+		// creating permanent entries for past-dated values via the multi path.
+		// Zero retains the "no expiry" contract (see SetManyNoTTL).
+		return nil
+	}
+
 	// For single items, use regular Set
 	if len(items) == 1 {
 		for key, value := range items {
@@ -547,6 +744,7 @@ func (r *RedisBackend) GetMany(ctx context.Context, keys []string) (map[string][
 
 	// Process responses
 	result := make(map[string][]byte)
+	var firstErr error
 	for i, resp := range responses {
 		if resp == nil {
 			// Key doesn't exist
@@ -554,6 +752,17 @@ func (r *RedisBackend) GetMany(ctx context.Context, keys []string) (map[string][
 			continue
 		}
 
+		// A Redis command-error reply (e.g. LOADING, WRONGTYPE) is stored
+		// as an error value by Pipeline.Execute. It means the key lookup
+		// failed, not that the key is missing, so it must not be counted
+		// as a miss.
+		if respErr, ok := resp.(error); ok {
+			if firstErr == nil {
+				firstErr = fmt.Errorf("GetMany: command error for key %q: %w", keys[i], respErr)
+			}
+			continue
+		}
+
 		value, err := RESPString(resp)
 		if err != nil {
 			// Invalid response, skip this key
@@ -565,5 +774,9 @@ func (r *RedisBackend) GetMany(ctx context.Context, keys []string) (map[string][
 		result[keys[i]] = []byte(value)
 	}
 
+	if firstErr != nil {
+		return result, firstErr
+	}
+
 	return result, nil
 }

internal/cache/backends/redis_getmany_command_error_test.go

@@ -0,0 +1,46 @@
+package backends
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestRedisBackend_GetMany_CommandErrorReplyIsNotAMiss is a regression test
+// for the review finding that RedisBackend.GetMany silently counted a Redis
+// command-error reply (for example WRONGTYPE) as a cache miss instead of
+// surfacing it as an error. Pipeline.Execute stores such a reply as an
+// error value in the responses slice; GetMany must recognize that value and
+// report it, not swallow it as "key not found". Per the todo acceptance
+// criteria, this must also not increment the misses counter.
+func TestRedisBackend_GetMany_CommandErrorReplyIsNotAMiss(t *testing.T) {
+	t.Parallel()
+
+	mr, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	require.NoError(t, backend.Set(ctx, "good-key", []byte("good-value"), time.Minute))
+
+	// Create a key holding a list, so a GET against it returns a RESP
+	// command-error reply (WRONGTYPE), not a nil/missing response.
+	_, err := mr.Lpush("test:bad-key", "listval")
+	require.NoError(t, err)
+
+	missesBefore := backend.GetStats()["misses"].(int64)
+	hitsBefore := backend.GetStats()["hits"].(int64)
+
+	results, err := backend.GetMany(ctx, []string{"good-key", "bad-key"})
+
+	require.Error(t, err, "GetMany must surface the WRONGTYPE command-error reply instead of masking it as a miss")
+	assert.Contains(t, err.Error(), "bad-key")
+	assert.Equal(t, []byte("good-value"), results["good-key"], "a command error on one key must not drop a good key's result")
+	assert.NotContains(t, results, "bad-key")
+
+	missesAfter := backend.GetStats()["misses"].(int64)
+	hitsAfter := backend.GetStats()["hits"].(int64)
+	assert.Equal(t, missesBefore, missesAfter, "a command-error reply must not increment the misses counter")
+	assert.Equal(t, hitsBefore+1, hitsAfter, "the good key must still count as exactly one hit")
+}

internal/cache/backends/redis_pool.go

@@ -67,6 +67,24 @@ func NewConnectionPool(config *PoolConfig) (*ConnectionPool, error) {
 	return pool, nil
 }
 
+// reserveConnectionSlot atomically reserves capacity for one new connection,
+// returning false when the pool is already at MaxConnections. The
+// reservation is released via totalConns.Add(-1) if the dial fails.
+func (p *ConnectionPool) reserveConnectionSlot() bool {
+	// Compare in int64: narrowing MaxConnections to int32 could wrap a
+	// large configured value to a negative limit and refuse every connection.
+	maxConns := int64(p.config.MaxConnections)
+	for {
+		cur := p.totalConns.Load()
+		if int64(cur) >= maxConns {
+			return false
+		}
+		if p.totalConns.CompareAndSwap(cur, cur+1) {
+			return true
+		}
+	}
+}
+
 // Get retrieves a connection from the pool or creates a new one
 func (p *ConnectionPool) Get(ctx context.Context) (*RedisConn, error) {
 	if p.closed.Load() {
@@ -83,6 +101,11 @@ func (p *ConnectionPool) Get(ctx context.Context) (*RedisConn, error) {
 
 		select {
 		case conn = <-p.connections:
+			if conn == nil {
+				// Pool channel was closed concurrently (Close) - receiving from a
+				// closed channel yields the zero value.
+				return nil, ErrBackendClosed
+			}
 			// Reuse existing connection - validate if health check enabled
 			if p.config.EnableHealthCheck && !p.isConnectionHealthy(conn) {
 				// Connection is stale, close it and try again
@@ -97,11 +120,15 @@ func (p *ConnectionPool) Get(ctx context.Context) (*RedisConn, error) {
 			return nil, ctx.Err()
 
 		default:
-			// No available connection, create new one if under limit
-			// #nosec G115 -- MaxConnections is a small config value that fits in int32
-			if p.totalConns.Load() < int32(p.config.MaxConnections) {
+			// No available connection, create new one if under limit.
+			// Reserve capacity atomically before dialing: checking
+			// totalConns then dialing is not atomic, so concurrent Gets
+			// could each pass the check and spike the live socket count
+			// far above MaxConnections (FD / Redis maxclients exhaustion).
+			if p.reserveConnectionSlot() {
 				conn, err = p.createConnection(ctx)
 				if err != nil {
+					p.totalConns.Add(-1) // release the reserved slot
 					// If this is the last attempt, return error
 					if attempt == maxAttempts-1 {
 						return nil, err
@@ -111,13 +138,17 @@ func (p *ConnectionPool) Get(ctx context.Context) (*RedisConn, error) {
 					continue
 				}
 				p.activeConns.Add(1)
-				p.totalConns.Add(1)
 				return conn, nil
 			}
 
 			// Pool exhausted, wait for a connection with timeout
 			select {
 			case conn = <-p.connections:
+				if conn == nil {
+					// Pool channel was closed concurrently (Close) - receiving from a
+					// closed channel yields the zero value.
+					return nil, ErrBackendClosed
+				}
 				// Validate connection if health check enabled
 				if p.config.EnableHealthCheck && !p.isConnectionHealthy(conn) {
 					_ = conn.Close()
@@ -148,6 +179,13 @@ func (p *ConnectionPool) Put(conn *RedisConn) {
 	p.puts.Add(1)
 	p.activeConns.Add(-1)
 
+	// Hold p.mu so this is mutually exclusive with Close (which closes
+	// p.connections under the same lock). Without it, a Put that passed
+	// the closed check could send on p.connections just after Close
+	// closed it, panicking "send on closed channel" at shutdown.
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
 	if p.closed.Load() || conn.closed.Load() {
 		_ = conn.Close()
 		p.totalConns.Add(-1)
@@ -260,10 +298,23 @@ type RedisConn struct {
 	mu           sync.Mutex
 }
 
-// Do executes a Redis command and returns the response
+// Do executes a Redis command and returns the response.
 func (c *RedisConn) Do(command string, args ...string) (interface{}, error) {
+	resp, _, err := c.doTracked(command, args...)
+	return resp, err
+}
+
+// doTracked is Do's implementation. It additionally reports whether the
+// command was already written to the connection when it failed: SetNX uses
+// this to tell "definitely not applied" (the write itself failed) from
+// "outcome unknown, may have applied" (the write succeeded but reading the
+// reply failed). SET NX is not safe to retry blindly the way Set's
+// idempotent SETEX/PSETEX is — a retried SET NX after a lost reply sees its
+// own possible write and reports "already claimed" for what may have been a
+// first-ever claim (FIX-17 round-2).
+func (c *RedisConn) doTracked(command string, args ...string) (interface{}, bool, error) {
 	if c.closed.Load() {
-		return nil, ErrBackendClosed
+		return nil, false, ErrBackendClosed
 	}
 
 	c.mu.Lock()
@@ -273,7 +324,7 @@ func (c *RedisConn) Do(command string, args ...string) (interface{}, error) {
 	// maxSafeArgs is set to (1<<20)-1 = 1,048,575 which is more than any reasonable Redis command
 	const maxSafeArgs = (1 << 20) - 1
 	if len(args) > maxSafeArgs {
-		return nil, errors.New("too many arguments: exceeds maximum safe count")
+		return nil, false, errors.New("too many arguments: exceeds maximum safe count")
 	}
 
 	// Build command arguments
@@ -283,11 +334,11 @@ func (c *RedisConn) Do(command string, args ...string) (interface{}, error) {
 	for _, s := range args {
 		// Protect against possible overflow
 		if len(s) > maxTotalArgBytes-totalBytes {
-			return nil, errors.New("arguments too large (would overflow maximum allowed total size)")
+			return nil, false, errors.New("arguments too large (would overflow maximum allowed total size)")
 		}
 		totalBytes += len(s)
 		if totalBytes > maxTotalArgBytes {
-			return nil, errors.New("total argument size exceeds maximum allowed")
+			return nil, false, errors.New("total argument size exceeds maximum allowed")
 		}
 	}
 	// Build command slice: prepend command to args
@@ -305,7 +356,7 @@ func (c *RedisConn) Do(command string, args ...string) (interface{}, error) {
 	writer.Release() // Return to pool immediately after use
 	if err != nil {
 		c.closed.Store(true)
-		return nil, err
+		return nil, false, err
 	}
 
 	// Set read timeout
@@ -318,13 +369,17 @@ func (c *RedisConn) Do(command string, args ...string) (interface{}, error) {
 	resp, err := reader.ReadResponse()
 	reader.Release() // Return to pool immediately after use
 	if err != nil {
-		if !errors.Is(err, ErrNilResponse) {
+		// A nil response or a Redis command error reply leaves the
+		// connection healthy — only an IO/parse error closes it.
+		if !errors.Is(err, ErrNilResponse) && !errors.Is(err, ErrCommandReply) {
 			c.closed.Store(true)
 		}
-		return nil, err
+		// The write above already succeeded, so the command reached the
+		// wire even though its reply did not come back.
+		return nil, true, err
 	}
 
-	return resp, nil
+	return resp, true, nil
 }
 
 // Close closes the connection
@@ -453,6 +508,14 @@ func (p *Pipeline) Execute() ([]interface{}, error) {
 				responses[i] = nil
 				continue
 			}
+			if errors.Is(err, ErrCommandReply) {
+				// A Redis command error reply: the connection is healthy
+				// and the remaining replies are still readable. Store the
+				// error value so per-command validation upstream can
+				// report it without aborting the batch.
+				responses[i] = err
+				continue
+			}
 			p.conn.closed.Store(true)
 			return responses[:i], fmt.Errorf("pipeline read error at command %d: %w", i, err)
 		}

internal/cache/backends/redis_pool_max_conns_test.go

@@ -0,0 +1,37 @@
+package backends
+
+import (
+	"math"
+	"strconv"
+	"testing"
+)
+
+// TestReserveConnectionSlotLargeMaxConnections pins the gosec G115 fix: the
+// limit was narrowed with int32(MaxConnections), so a value above MaxInt32
+// wrapped to a negative limit and every connection was refused.
+func TestReserveConnectionSlotLargeMaxConnections(t *testing.T) {
+	if strconv.IntSize < 64 {
+		t.Skip("int cannot exceed MaxInt32 on this platform")
+	}
+	p := &ConnectionPool{config: &PoolConfig{MaxConnections: math.MaxInt32 + 1}}
+	if !p.reserveConnectionSlot() {
+		t.Fatal("reserveConnectionSlot refused a connection although MaxConnections is far above the current count")
+	}
+	if got := p.totalConns.Load(); got != 1 {
+		t.Fatalf("totalConns = %d, want 1", got)
+	}
+}
+
+// TestReserveConnectionSlotRespectsLimit checks that the int64 comparison
+// still enforces a normal limit.
+func TestReserveConnectionSlotRespectsLimit(t *testing.T) {
+	p := &ConnectionPool{config: &PoolConfig{MaxConnections: 2}}
+	for i := 0; i < 2; i++ {
+		if !p.reserveConnectionSlot() {
+			t.Fatalf("reservation %d refused below the limit", i+1)
+		}
+	}
+	if p.reserveConnectionSlot() {
+		t.Fatal("reservation above MaxConnections was accepted")
+	}
+}

internal/cache/backends/redis_pool_test.go

@@ -367,7 +367,47 @@ func TestConnectionPool_Close(t *testing.T) {
 	require.NoError(t, err)
 }
 
-// TestConnectionPool_Timeouts tests various timeout scenarios
+// TestConnectionPool_GetDuringClose_NoNilRegression ensures a Get racing with
+// Close never yields a nil *RedisConn with a nil error (which previously
+// happened when the receive from the closed p.connections channel returned
+// the zero value), and never panics by calling Close on a nil receiver.
+func TestConnectionPool_GetDuringClose_NoNilRegression(t *testing.T) {
+	mr := NewMiniredisServer(t)
+
+	config := &PoolConfig{
+		Address:        mr.GetAddr(),
+		MaxConnections: 1,
+		ConnectTimeout: 1 * time.Second,
+	}
+
+	pool, err := NewConnectionPool(config)
+	require.NoError(t, err)
+
+	// Fill the pool so a concurrent Get blocks waiting for a connection.
+	held, err := pool.Get(context.Background())
+	require.NoError(t, err)
+	defer pool.Put(held)
+
+	type result struct {
+		conn *RedisConn
+		err  error
+	}
+	resCh := make(chan result, 1)
+	go func() {
+		c, e := pool.Get(context.Background())
+		resCh <- result{c, e}
+	}()
+
+	// Give the goroutine time to reach the blocking receive on p.connections,
+	// then close the pool. Closing the channel unblocks the receive with the
+	// zero value; Get must surface ErrBackendClosed rather than (nil, nil).
+	time.Sleep(50 * time.Millisecond)
+	require.NoError(t, pool.Close())
+
+	res := <-resCh
+	require.Error(t, res.err, "Get after Close must return an error, not (nil, nil)")
+	assert.True(t, errors.Is(res.err, ErrBackendClosed), "want ErrBackendClosed, got %v", res.err)
+}
 func TestConnectionPool_Timeouts(t *testing.T) {
 	mr := NewMiniredisServer(t)
 
@@ -648,3 +688,47 @@ func TestRedisConn_RejectOversizedArgumentBytes(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "arguments too large")
 }
+
+// TestConnectionPool_PutDuringClose_NoPanic hammers Put/Get concurrently with
+// Close. Before the fix, Put checked closed then sent on p.connections
+// without holding p.mu; if Close closed the channel in between, the send
+// panicked ("send on closed channel") at shutdown. Run under -race.
+func TestConnectionPool_PutDuringClose_NoPanic(t *testing.T) {
+	mr := NewMiniredisServer(t)
+
+	config := &PoolConfig{
+		Address:        mr.GetAddr(),
+		MaxConnections: 5,
+		ConnectTimeout: 5 * time.Second,
+		ReadTimeout:    3 * time.Second,
+		WriteTimeout:   3 * time.Second,
+	}
+
+	pool, err := NewConnectionPool(config)
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	stop := make(chan struct{})
+	var wg sync.WaitGroup
+	for g := 0; g < 8; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for {
+				select {
+				case <-stop:
+					return
+				default:
+				}
+				if conn, err := pool.Get(ctx); err == nil {
+					pool.Put(conn) // may race Close
+				}
+			}
+		}()
+	}
+
+	time.Sleep(5 * time.Millisecond)
+	_ = pool.Close()
+	close(stop)
+	wg.Wait()
+}

internal/cache/backends/resp.go

@@ -20,6 +20,11 @@ import (
 var (
 	ErrInvalidRESP = errors.New("invalid RESP response")
 	ErrNilResponse = errors.New("nil response")
+	// ErrCommandReply marks a RESP '-' (Redis command error) reply, e.g.
+	// WRONGTYPE or OOM. It is a valid protocol response — the connection
+	// is healthy and any remaining pipelined replies are still readable —
+	// as opposed to an IO/parse error which means the connection is dead.
+	ErrCommandReply = errors.New("redis command error reply")
 )
 
 // RESPWriter writes RESP protocol messages
@@ -110,7 +115,9 @@ func (r *RESPReader) readError() error {
 	if err != nil {
 		return err
 	}
-	return errors.New(line)
+	// Wrap so callers can distinguish a Redis command error reply (healthy
+	// connection) from an IO/parse error (dead connection).
+	return fmt.Errorf("%w: %s", ErrCommandReply, line)
 }
 
 // readInteger reads an integer (:1000\r\n)
@@ -170,11 +177,26 @@ func (r *RESPReader) readArray() (interface{}, error) {
 		return nil, ErrNilResponse
 	}
 
-	// Read each element
+	// Read each element. A nested "-ERR" reply and a nested nil value
+	// ("$-1" or "*-1") are both valid protocol values, not connection-level
+	// failures: store the element (the error, or nil) and keep reading so
+	// every element is drained off the wire. Leaving unread elements on the
+	// connection would let the next command's reader pick up this array's
+	// leftover bytes as its own reply (response desync) once Do returns the
+	// connection to the pool. Any other error (IO or protocol) still aborts
+	// the array, since the connection is no longer trustworthy.
 	result := make([]interface{}, length)
 	for i := 0; i < length; i++ {
 		elem, err := r.ReadResponse()
 		if err != nil {
+			if errors.Is(err, ErrCommandReply) {
+				result[i] = err
+				continue
+			}
+			if errors.Is(err, ErrNilResponse) {
+				result[i] = nil
+				continue
+			}
 			return nil, err
 		}
 		result[i] = elem

internal/cache/backends/resp_nested_error_test.go

@@ -0,0 +1,140 @@
+package backends
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestRESPReader_ReadArray_NestedCommandErrorDrainsAllElements is a
+// regression test for the review finding that a nested "-ERR" reply inside
+// an array left the trailing array elements unread on the connection. A
+// nested command-error reply is a valid protocol value (the connection
+// stays healthy, see ErrCommandReply), so readArray must keep reading past
+// it instead of aborting the whole array read. Failing to drain the
+// trailing elements leaves them on the stream, where the next command's
+// reader would pick them up as its own reply (response desync).
+func TestRESPReader_ReadArray_NestedCommandErrorDrainsAllElements(t *testing.T) {
+	// *3: bulk "foo", a nested command-error reply, bulk "bar" - followed
+	// immediately by an independent "+PONG" reply on the same stream, as
+	// the next command's response would be.
+	input := "*3\r\n$3\r\nfoo\r\n-ERR boom\r\n$3\r\nbar\r\n+PONG\r\n"
+	reader := NewRESPReader(strings.NewReader(input))
+
+	result, err := reader.ReadResponse()
+	require.NoError(t, err, "a nested command-error reply must not fail the whole array read")
+
+	arr, ok := result.([]interface{})
+	require.True(t, ok, "expected an array result, got %T", result)
+	require.Len(t, arr, 3, "all three array elements must be present, including the one after the nested error")
+
+	assert.Equal(t, "foo", arr[0])
+
+	elemErr, ok := arr[1].(error)
+	require.True(t, ok, "the nested error element must be stored as an error value, got %T", arr[1])
+	assert.True(t, errors.Is(elemErr, ErrCommandReply), "want ErrCommandReply, got %v", elemErr)
+
+	assert.Equal(t, "bar", arr[2], "the element after the nested error must still be read off the wire")
+
+	// The reader must be positioned exactly at the start of the next reply,
+	// not partway through leftover array bytes.
+	next, err := reader.ReadResponse()
+	require.NoError(t, err, "the connection must not be desynced by the nested error")
+	assert.Equal(t, "PONG", next, "next command's reply must not be corrupted by unread array elements")
+}
+
+// TestRESPReader_ReadArray_NestedIOErrorStillAborts ensures a genuine
+// IO/parse error nested inside an array (as opposed to a valid "-ERR"
+// command-error reply) still aborts the array read, since the connection is
+// no longer trustworthy in that case.
+func TestRESPReader_ReadArray_NestedIOErrorStillAborts(t *testing.T) {
+	// Second element is a truncated bulk string (declares 5 bytes, supplies
+	// none) - a protocol/IO error, not a command-error reply.
+	input := "*2\r\n$3\r\nfoo\r\n$5\r\n"
+	reader := NewRESPReader(strings.NewReader(input))
+
+	_, err := reader.ReadResponse()
+	require.Error(t, err)
+	assert.False(t, errors.Is(err, ErrCommandReply), "a truncated bulk string is an IO error, not a command-error reply")
+}
+
+// TestRESPReader_ReadArray_NestedNilBulkStringDrainsAllElements is a
+// regression test for the same desync as the nested command-error case,
+// triggered by a nested "$-1" (nil bulk string) element instead of a
+// "-ERR" reply. readBulkString returns ErrNilResponse for "$-1", which is
+// not an IO or protocol error and does not make the connection
+// untrustworthy (see RedisConn.Do, which keeps the connection pooled on
+// ErrNilResponse). readArray must store nil for that element and keep
+// reading the rest of the array.
+func TestRESPReader_ReadArray_NestedNilBulkStringDrainsAllElements(t *testing.T) {
+	// *3: bulk "foo", a nested nil bulk string, bulk "bar" - followed
+	// immediately by an independent "+PONG" reply on the same stream, as
+	// the next command's response would be.
+	input := "*3\r\n$3\r\nfoo\r\n$-1\r\n$3\r\nbar\r\n+PONG\r\n"
+	reader := NewRESPReader(strings.NewReader(input))
+
+	result, err := reader.ReadResponse()
+	require.NoError(t, err, "a nested nil bulk string must not fail the whole array read")
+
+	arr, ok := result.([]interface{})
+	require.True(t, ok, "expected an array result, got %T", result)
+	require.Len(t, arr, 3, "all three array elements must be present, including the one after the nested nil")
+
+	assert.Equal(t, "foo", arr[0])
+	assert.Nil(t, arr[1], "the nested nil bulk string must be stored as a nil element")
+	assert.Equal(t, "bar", arr[2], "the element after the nested nil must still be read off the wire")
+
+	// The reader must be positioned exactly at the start of the next reply,
+	// not partway through leftover array bytes.
+	next, err := reader.ReadResponse()
+	require.NoError(t, err, "the connection must not be desynced by the nested nil bulk string")
+	assert.Equal(t, "PONG", next, "next command's reply must not be corrupted by unread array elements")
+}
+
+// TestRESPReader_ReadArray_NestedNilArrayDrainsAllElements is the same
+// regression as above for a nested "*-1" (nil array) element.
+func TestRESPReader_ReadArray_NestedNilArrayDrainsAllElements(t *testing.T) {
+	// *3: bulk "foo", a nested nil array, bulk "bar" - followed immediately
+	// by an independent "+PONG" reply on the same stream, as the next
+	// command's response would be.
+	input := "*3\r\n$3\r\nfoo\r\n*-1\r\n$3\r\nbar\r\n+PONG\r\n"
+	reader := NewRESPReader(strings.NewReader(input))
+
+	result, err := reader.ReadResponse()
+	require.NoError(t, err, "a nested nil array must not fail the whole array read")
+
+	arr, ok := result.([]interface{})
+	require.True(t, ok, "expected an array result, got %T", result)
+	require.Len(t, arr, 3, "all three array elements must be present, including the one after the nested nil")
+
+	assert.Equal(t, "foo", arr[0])
+	assert.Nil(t, arr[1], "the nested nil array must be stored as a nil element")
+	assert.Equal(t, "bar", arr[2], "the element after the nested nil must still be read off the wire")
+
+	// The reader must be positioned exactly at the start of the next reply,
+	// not partway through leftover array bytes.
+	next, err := reader.ReadResponse()
+	require.NoError(t, err, "the connection must not be desynced by the nested nil array")
+	assert.Equal(t, "PONG", next, "next command's reply must not be corrupted by unread array elements")
+}
+
+// TestRESPReader_ReadArray_TopLevelNilBulkStringStillErrors ensures the
+// top-level "$-1" contract is unchanged: only a nested nil is absorbed as
+// an element, a top-level nil bulk string still returns ErrNilResponse.
+func TestRESPReader_ReadArray_TopLevelNilBulkStringStillErrors(t *testing.T) {
+	reader := NewRESPReader(strings.NewReader("$-1\r\n"))
+	_, err := reader.ReadResponse()
+	assert.True(t, errors.Is(err, ErrNilResponse), "want ErrNilResponse, got %v", err)
+}
+
+// TestRESPReader_ReadArray_TopLevelNilArrayStillErrors ensures the
+// top-level "*-1" contract is unchanged: only a nested nil is absorbed as
+// an element, a top-level nil array still returns ErrNilResponse.
+func TestRESPReader_ReadArray_TopLevelNilArrayStillErrors(t *testing.T) {
+	reader := NewRESPReader(strings.NewReader("*-1\r\n"))
+	_, err := reader.ReadResponse()
+	assert.True(t, errors.Is(err, ErrNilResponse), "want ErrNilResponse, got %v", err)
+}

internal/cache/backends/resp_test.go

@@ -142,7 +142,12 @@ func TestRESPReader_ReadError(t *testing.T) {
 			_, err := reader.ReadResponse()
 
 			require.Error(t, err)
-			assert.Equal(t, tt.expectedError, err.Error())
+			// R177: a '-' reply is now wrapped with ErrCommandReply so
+			// callers can tell a Redis command error (healthy connection)
+			// apart from an IO/parse error. The command's message text is
+			// preserved verbatim inside the wrapped error.
+			assert.True(t, errors.Is(err, ErrCommandReply), "want ErrCommandReply, got %v", err)
+			assert.Contains(t, err.Error(), tt.expectedError)
 		})
 	}
 }

internal/cache/backends/review_fix17_setnx_test.go

@@ -0,0 +1,84 @@
+package backends
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestFIX17_RedisBackendSetNX_ClaimsOnlyWhenAbsent pins RedisBackend.SetNX's
+// contract: it stores the value and reports true only when the key does not
+// already exist, using Redis SET key value NX PX <ttl-ms> as one atomic
+// server-side operation, and never overwrites an existing key.
+func TestFIX17_RedisBackendSetNX_ClaimsOnlyWhenAbsent(t *testing.T) {
+	t.Parallel()
+
+	mr := NewMiniredisServer(t)
+	config := DefaultRedisConfig(mr.GetAddr())
+	backend, err := NewRedisBackend(config)
+	require.NoError(t, err)
+	defer backend.Close()
+
+	ctx := context.Background()
+	key := "fix17-setnx-key"
+
+	set, err := backend.SetNX(ctx, key, []byte("first"), time.Minute)
+	require.NoError(t, err)
+	assert.True(t, set, "first SetNX on an absent key must claim it")
+
+	set, err = backend.SetNX(ctx, key, []byte("second"), time.Minute)
+	require.NoError(t, err)
+	assert.False(t, set, "second SetNX on an already-claimed key must not claim it")
+
+	value, ttl, exists, err := backend.Get(ctx, key)
+	require.NoError(t, err)
+	require.True(t, exists)
+	assert.Equal(t, "first", string(value), "the losing SetNX must not overwrite the winner's value")
+	assert.Greater(t, ttl, 50*time.Second, "the winning SetNX must have attached the requested TTL")
+}
+
+// TestFIX17_RedisBackendSetNX_ConcurrentSameKeyExactlyOneWinner drives many
+// goroutines through SetNX on the SAME key against a single miniredis
+// instance shared by every caller (simulating every Traefik replica sharing
+// one Redis-backed session-invalidation cache). Exactly one must win: this
+// is the primitive UniversalCache.SetIfAbsent relies on to close the
+// cross-replica gap the FIX-17 R36 fix left open (backchannelLogoutJTIMu is
+// process-local and cannot coordinate across replicas; Redis SET NX can).
+func TestFIX17_RedisBackendSetNX_ConcurrentSameKeyExactlyOneWinner(t *testing.T) {
+	t.Parallel()
+
+	mr := NewMiniredisServer(t)
+	config := DefaultRedisConfig(mr.GetAddr())
+	backend, err := NewRedisBackend(config)
+	require.NoError(t, err)
+	defer backend.Close()
+
+	ctx := context.Background()
+	key := "fix17-setnx-concurrent-key"
+
+	const n = 20
+	var wg sync.WaitGroup
+	results := make([]bool, n)
+	errs := make([]error, n)
+	wg.Add(n)
+	for i := 0; i < n; i++ {
+		go func(i int) {
+			defer wg.Done()
+			results[i], errs[i] = backend.SetNX(ctx, key, []byte("claimant"), time.Minute)
+		}(i)
+	}
+	wg.Wait()
+
+	wins := 0
+	for i := 0; i < n; i++ {
+		require.NoError(t, errs[i])
+		if results[i] {
+			wins++
+		}
+	}
+	assert.Equal(t, 1, wins, "exactly one of %d concurrent SetNX calls on the same key must win", n)
+}

internal/cache/backends/review_fix31_pttl_test.go

@@ -0,0 +1,73 @@
+package backends
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestFIX31_GetNoExpiryReturnsDistinctSentinel guards RedisBackend.Get
+// against the R59 follow-up: the old code read TTL (second precision),
+// which maps both "no expiry" (-1) and "under one second left" to a
+// reported ttl of 0. UniversalCache.Get then treated any ttl<=0 as
+// DefaultTTL, so a key on the verge of expiring in Redis got re-cached
+// locally for the cache's full DefaultTTL (up to 25h for the
+// session-invalidation cache).
+//
+// Get must now use PTTL (millisecond precision) and report NoExpiryTTL,
+// not 0, for a key with no associated expiry, so the caller can still
+// distinguish "no expiry" from "expiring now".
+// Fail-on-old: a key stored with no TTL reports ttl == 0, indistinguishable
+// from an about-to-expire key.
+func TestFIX31_GetNoExpiryReturnsDistinctSentinel(t *testing.T) {
+	t.Parallel()
+
+	mr := NewMiniredisServer(t)
+	config := DefaultRedisConfig(mr.GetAddr())
+	backend, err := NewRedisBackend(config)
+	require.NoError(t, err)
+	defer backend.Close()
+
+	ctx := context.Background()
+	key := "fix31-no-expiry-key"
+
+	// ttl=0 to Set takes the bare-SET path (no expiry attached).
+	require.NoError(t, backend.Set(ctx, key, []byte("v"), 0))
+
+	_, ttl, exists, err := backend.Get(ctx, key)
+	require.NoError(t, err)
+	require.True(t, exists)
+	assert.Equal(t, NoExpiryTTL, ttl, "a key with no Redis expiry must report the distinct NoExpiryTTL sentinel, not 0")
+}
+
+// TestFIX31_GetWithRealTTLReportsPositiveDuration pins that a key with a
+// real remaining TTL still reports a normal positive duration (not the
+// sentinel, not zero) after switching from TTL to PTTL.
+func TestFIX31_GetWithRealTTLReportsPositiveDuration(t *testing.T) {
+	t.Parallel()
+
+	mr := NewMiniredisServer(t)
+	config := DefaultRedisConfig(mr.GetAddr())
+	backend, err := NewRedisBackend(config)
+	require.NoError(t, err)
+	defer backend.Close()
+
+	ctx := context.Background()
+	key := "fix31-real-ttl-key"
+
+	require.NoError(t, backend.Set(ctx, key, []byte("v"), 10*time.Second))
+
+	_, ttl, exists, err := backend.Get(ctx, key)
+	require.NoError(t, err)
+	require.True(t, exists)
+	assert.NotEqual(t, NoExpiryTTL, ttl)
+	// A lower bound near the full 10s pins the millisecond-precision PTTL
+	// contract: if Get is ever reverted to second-precision TTL while still
+	// being read as milliseconds, a ~10s key reports ~10ms and this bound
+	// catches it (a bare ttl>0 check would not).
+	assert.Greater(t, ttl, 9*time.Second)
+	assert.LessOrEqual(t, ttl, 10*time.Second)
+}

internal/cache/backends/review_r110_test.go

@@ -0,0 +1,54 @@
+package backends
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestConnectionPool_CapHeldUnderBurst regresses the connection-pool cap
+// being non-atomic: ConnectionPool.Get checked `totalConns < MaxConnections`
+// and THEN dialed a new socket, so concurrent Gets could each pass the check
+// and spike the live connection count far above MaxConnections (FD / Redis
+// maxclients exhaustion under burst load). The cap must now be held
+// atomically so at most MaxConnections sockets are ever created at once.
+func TestConnectionPool_CapHeldUnderBurst(t *testing.T) {
+	mr := NewMiniredisServer(t)
+
+	maxConns := 3
+	pool, err := NewConnectionPool(&PoolConfig{
+		Address:        mr.GetAddr(),
+		MaxConnections: maxConns,
+		ConnectTimeout: 80 * time.Millisecond,
+		ReadTimeout:    50 * time.Millisecond,
+		WriteTimeout:   50 * time.Millisecond,
+	})
+	require.NoError(t, err)
+	defer pool.Close()
+
+	ctx := context.Background()
+	const workers = 50
+
+	var wg sync.WaitGroup
+	for i := 0; i < workers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			conn, _ := pool.Get(ctx)
+			if conn != nil {
+				// Hold the connection (simulate an in-flight request) so the
+				// pool stays under pressure and the count is stable.
+				_ = conn
+			}
+		}()
+	}
+	wg.Wait()
+
+	stats := pool.Stats()
+	total := stats["total_connections"].(int32)
+	require.LessOrEqual(t, total, int32(maxConns),
+		"burst Gets must not create more than MaxConnections sockets (got %d)", total)
+}

internal/cache/backends/review_r115_test.go

@@ -0,0 +1,36 @@
+package backends
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestRedisBackend_SetNegativeTTL_NotPersistent guards the R115 negative-TTL
+// fix. The cache stack's convention is that a non-positive TTL means "already
+// expired". Previously RedisBackend.Set/SetMany fell through to a bare SET
+// when ttl<=0, writing an entry with NO expiry — i.e. an expired-dated value
+// became permanent. Now expired TTLs write nothing.
+func TestRedisBackend_SetNegativeTTL_NotPersistent(t *testing.T) {
+	_, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	// Single Set with an expired TTL must not create an entry.
+	require.NoError(t, backend.Set(ctx, "neg", []byte("v"), -time.Second))
+	_, _, exists, err := backend.Get(ctx, "neg")
+	require.NoError(t, err)
+	require.False(t, exists, "negative-TTL Set must not create a persistent entry")
+
+	// SetMany with multiple items and an expired TTL must not create entries.
+	require.NoError(t, backend.SetMany(ctx, map[string][]byte{
+		"a": []byte("1"),
+		"b": []byte("2"),
+	}, -time.Second))
+	for _, k := range []string{"a", "b"} {
+		_, _, exists, err := backend.Get(ctx, k)
+		require.NoError(t, err)
+		require.False(t, exists, "negative-TTL SetMany must not create a persistent entry for %q", k)
+	}
+}

internal/cache/backends/review_r141_test.go

@@ -0,0 +1,99 @@
+package backends
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+)
+
+// TestSingleflightCache_PanickingFetcherDoesNotDeadlock verifies that a
+// fetcher which panics (routines in this codebase treat panics as a normal
+// failure mode) does not wedge the singleflight entry: the leading caller
+// yields an error and waiting callers are released instead of blocking on
+// call.wg forever (R141).
+func TestSingleflightCache_PanickingFetcherDoesNotDeadlock(t *testing.T) {
+	mr := NewMiniredisServer(t)
+	backend, err := NewRedisBackend(DefaultRedisConfig(mr.GetAddr()))
+	requireNoErrorFatal(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+	ctx := context.Background()
+	key := "panic-key"
+
+	panicFetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		panic("boom")
+	}
+
+	var wg sync.WaitGroup
+	var doneA, doneB = make(chan struct{}), make(chan struct{})
+
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		defer func() { _ = recover() }() // tolerate old code's out-of-band panic
+		_, _ = cache.GetOrFetch(ctx, key, panicFetcher)
+		close(doneA)
+	}()
+
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_, _ = cache.GetOrFetch(ctx, key, panicFetcher)
+		close(doneB)
+	}()
+
+	select {
+	case <-doneB:
+	case <-time.After(3 * time.Second):
+		t.Fatal("concurrent waiter hung on a panicking singleflight fetcher")
+	}
+	select {
+	case <-doneA:
+	case <-time.After(3 * time.Second):
+		t.Fatal("leading caller hung on its own panicking fetcher")
+	}
+	wg.Wait()
+
+	// After the entry is cleaned up, a well-behaved fetcher for the same
+	// key must execute normally (proves the entry was not permanently
+	// wedged by the panic).
+	ran := false
+	good := func(ctx context.Context) ([]byte, time.Duration, error) {
+		ran = true
+		return []byte("ok"), time.Minute, nil
+	}
+	// Poll until the deferred cleanup goroutine (singleflight.go's
+	// time.Sleep(100ms) + delete) has released the key, instead of sleeping
+	// a fixed margin over that 100ms delay (FIX-22): a late-firing cleanup
+	// timer under load let the next GetOrFetch join the finished call and
+	// receive its stale panic error back, making the fixed-sleep version
+	// flaky on loaded CI runners.
+	deadline := time.Now().Add(2 * time.Second)
+	for {
+		cache.mu.Lock()
+		_, stillPresent := cache.calls[key]
+		cache.mu.Unlock()
+		if !stillPresent {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("singleflight entry for key was never released after the panicking fetcher completed")
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	if _, err := cache.GetOrFetch(ctx, key, good); err != nil {
+		t.Fatalf("well-behaved fetcher after panic returned error: %v", err)
+	}
+	if !ran {
+		t.Fatal("well-behaved fetcher after panic did not execute")
+	}
+}
+
+func requireNoErrorFatal(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}

internal/cache/backends/review_r177_redis_test.go

@@ -0,0 +1,79 @@
+package backends
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestR177_RedisCommandErrorDoesNotCloseConn regresses the RESP command-error
+// conflation: a Redis '-' (command error) reply, e.g. WRONGTYPE or OOM, is
+// a valid protocol response — it does not mean the connection is dead.
+// Previously Do and Pipeline treated it as an IO error, marking the healthy
+// pooled connection closed (and for pipelines aborting the whole batch),
+// discarding a perfectly reusable connection.
+func TestR177_RedisCommandErrorDoesNotCloseConn(t *testing.T) {
+	mr := NewMiniredisServer(t)
+	config := &PoolConfig{
+		Address:        mr.GetAddr(),
+		MaxConnections: 5,
+		ConnectTimeout: 5 * time.Second,
+		ReadTimeout:    3 * time.Second,
+		WriteTimeout:   3 * time.Second,
+	}
+	ctx := context.Background()
+
+	pool, err := NewConnectionPool(config)
+	require.NoError(t, err)
+	defer pool.Close()
+
+	conn, err := pool.Get(ctx)
+	require.NoError(t, err)
+	defer pool.Put(conn)
+
+	t.Run("single command error leaves conn healthy", func(t *testing.T) {
+		mr.SetError("ERR artificial") // every command returns '-ERR artificial'
+
+		_, err := conn.Do("GET", "k")
+		require.Error(t, err)
+		require.True(t, errors.Is(err, ErrCommandReply),
+			"expected a Redis command-reply error, got %v", err)
+
+		mr.SetError("") // clear; the connection must still be reusable
+
+		// On the buggy path Do marked the conn closed above, so this
+		// PING fails with "connection closed"; on the fixed path the
+		// conn is untouched and PING succeeds.
+		resp, err := conn.Do("PING")
+		require.NoError(t, err)
+		require.Equal(t, "PONG", resp)
+	})
+
+	t.Run("pipeline command error reads full batch and keeps conn", func(t *testing.T) {
+		mr.SetError("ERR artificial")
+
+		p := conn.NewPipeline()
+		p.Queue("SET", "k1", "v1")
+		p.Queue("SET", "k2", "v2")
+
+		// On the buggy path Execute returned after the first error (1
+		// response) and closed the conn; on the fixed path all replies
+		// are read (healthy conn), the batch is not aborted.
+		responses, err := p.Execute()
+		require.NoError(t, err, "batch must complete with per-command errors")
+		require.Len(t, responses, 2)
+		for i, r := range responses {
+			er, ok := r.(error)
+			require.True(t, ok, "response %d should carry an error value", i)
+			require.True(t, errors.Is(er, ErrCommandReply), "response %d should be a command-reply error", i)
+		}
+
+		mr.SetError("")
+		resp, err := conn.Do("PING")
+		require.NoError(t, err)
+		require.Equal(t, "PONG", resp)
+	})
+}

internal/cache/backends/review_r208_stress_test.go

@@ -0,0 +1,47 @@
+package backends
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+)
+
+// TestRedisBackendStressCloseConcurrent hammers a miniredis-backed
+// RedisBackend (pooled connections) from many goroutines while Close runs,
+// the pooled-conn use-after-close race class (R208).
+func TestRedisBackendStressCloseConcurrent(t *testing.T) {
+	mr := NewMiniredisServer(t)
+	backend, err := NewRedisBackend(DefaultRedisConfig(mr.GetAddr()))
+	if err != nil {
+		t.Fatalf("NewRedisBackend: %v", err)
+	}
+
+	var wg sync.WaitGroup
+	stop := make(chan struct{})
+	for g := 0; g < 8; g++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for i := 0; ; i++ {
+				select {
+				case <-stop:
+					return
+				default:
+				}
+				key := fmt.Sprintf("redis:k:%d:%d", id, i%256)
+				if i%2 == 0 {
+					_ = backend.Set(context.Background(), key, []byte("v"), time.Minute)
+				} else {
+					_, _, _, _ = backend.Get(context.Background(), key)
+				}
+			}
+		}(g)
+	}
+
+	time.Sleep(20 * time.Millisecond)
+	_ = backend.Close()
+	close(stop)
+	wg.Wait()
+}

internal/cache/backends/review_r212_stress_test.go

@@ -0,0 +1,86 @@
+package backends
+
+import (
+	"context"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// TestSingleflightStressDedup hammers GetOrFetch with many concurrent
+// waiters on the SAME key behind a slow fetcher: exactly one fetch must
+// run and all waiters must share its result, with no race on
+// call.val/call.err read after wg.Wait() (R212). Run under -race.
+func TestSingleflightStressDedup(t *testing.T) {
+	mr := NewMiniredisServer(t)
+	backend, _ := NewRedisBackend(DefaultRedisConfig(mr.GetAddr()))
+	sf := NewSingleflightCache(backend)
+
+	var fetches atomic.Int64
+	slow := func(context.Context) ([]byte, time.Duration, error) {
+		fetches.Add(1)
+		time.Sleep(5 * time.Millisecond)
+		return []byte("result"), time.Minute, nil
+	}
+
+	var wg sync.WaitGroup
+	for g := 0; g < 16; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; i < 20; i++ {
+				v, err := sf.GetOrFetch(context.Background(), "k", slow)
+				if err != nil {
+					t.Errorf("GetOrFetch: %v", err)
+					return
+				}
+				if string(v) != "result" {
+					t.Errorf("unexpected value %q", v)
+					return
+				}
+			}
+		}()
+	}
+	wg.Wait()
+
+	if fetches.Load() < 1 || fetches.Load() > 20 {
+		t.Fatalf("expected dedup across concurrent waiters; fetcher ran %d times", fetches.Load())
+	}
+}
+
+// A panicking fetcher must not leave waiters blocked forever: they must all
+// receive the recovered error (R212).
+func TestSingleflightStressPanicUnblocks(t *testing.T) {
+	mr := NewMiniredisServer(t)
+	backend, _ := NewRedisBackend(DefaultRedisConfig(mr.GetAddr()))
+	sf := NewSingleflightCache(backend)
+
+	panicFetcher := func(context.Context) ([]byte, time.Duration, error) {
+		panic("boom")
+	}
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		var wg sync.WaitGroup
+		for g := 0; g < 8; g++ {
+			wg.Add(1)
+			go func() {
+				defer wg.Done()
+				_, err := sf.GetOrFetch(context.Background(), "pk", panicFetcher)
+				if err == nil {
+					t.Error("expected error from panicking fetcher")
+				}
+			}()
+		}
+		wg.Wait()
+	}()
+
+	select {
+	case <-done:
+		// all waiters unblocked with the recovered error
+	case <-time.After(5 * time.Second):
+		t.Fatal("waiters stayed blocked after panicking fetcher (singleflight wedged)")
+	}
+}

internal/cache/backends/review_r2_fix17_setnx_reply_dropped_test.go

@@ -0,0 +1,171 @@
+package backends
+
+// Round-2 verifier regression (minor): RedisBackend.SetNX ran the Redis
+// SET key value NX PX command inside the shared executeWithRetry helper,
+// which blindly retries on a "connection"/"timeout"/"EOF" error by
+// re-issuing the whole operation closure. That is safe for Set (SETEX/
+// PSETEX overwrite unconditionally, so a retry after a lost reply is a
+// no-op repeat), but not for SET NX: if the first SET NX reached Redis and
+// applied, but its reply was lost before SetNX could read it, a retried
+// SET NX sees the caller's OWN write and reports (false, nil) —
+// "already claimed" — for what was actually a first-ever claim.
+//
+// dropReplyProxy below sits between the client and a real miniredis
+// instance, forwarding every request but swallowing the reply to exactly
+// one triggering command, reproducing that lost-reply window
+// deterministically.
+
+import (
+	"bytes"
+	"context"
+	"net"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// dropReplyProxy relays a single TCP connection to target, forwarding every
+// byte in both directions except: the first server->client chunk that
+// follows the FIRST client->server chunk containing trigger is swallowed
+// instead of forwarded, simulating a reply lost after Redis already
+// processed the command. Only the first occurrence of trigger arms a drop —
+// a caller's retry re-sending the same command (which necessarily contains
+// the same trigger substring) must relay normally, or the test could never
+// distinguish "retried and got a real answer" from "every attempt starved".
+type dropReplyProxy struct {
+	ln      net.Listener
+	target  string
+	trigger []byte
+
+	mu        sync.Mutex
+	triggered bool
+	dropNext  bool
+}
+
+func newDropReplyProxy(t *testing.T, target string, trigger []byte) *dropReplyProxy {
+	t.Helper()
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	p := &dropReplyProxy{ln: ln, target: target, trigger: trigger}
+	go p.acceptLoop()
+	t.Cleanup(func() { _ = ln.Close() })
+	return p
+}
+
+func (p *dropReplyProxy) Addr() string { return p.ln.Addr().String() }
+
+func (p *dropReplyProxy) acceptLoop() {
+	for {
+		client, err := p.ln.Accept()
+		if err != nil {
+			return
+		}
+		go p.handleConn(client)
+	}
+}
+
+func (p *dropReplyProxy) handleConn(client net.Conn) {
+	server, err := net.Dial("tcp", p.target)
+	if err != nil {
+		_ = client.Close()
+		return
+	}
+
+	var wg sync.WaitGroup
+	wg.Add(2)
+
+	go func() {
+		defer wg.Done()
+		buf := make([]byte, 4096)
+		for {
+			n, rerr := client.Read(buf)
+			if n > 0 {
+				chunk := buf[:n]
+				p.mu.Lock()
+				if !p.triggered && bytes.Contains(chunk, p.trigger) {
+					p.triggered = true
+					p.dropNext = true
+				}
+				p.mu.Unlock()
+				if _, werr := server.Write(chunk); werr != nil {
+					break
+				}
+			}
+			if rerr != nil {
+				break
+			}
+		}
+		_ = server.Close()
+	}()
+
+	go func() {
+		defer wg.Done()
+		buf := make([]byte, 4096)
+		for {
+			n, rerr := server.Read(buf)
+			if n > 0 {
+				p.mu.Lock()
+				drop := p.dropNext
+				p.dropNext = false
+				p.mu.Unlock()
+
+				if !drop {
+					if _, werr := client.Write(buf[:n]); werr != nil {
+						break
+					}
+				}
+				// drop == true: swallow this chunk, simulating a lost reply.
+			}
+			if rerr != nil {
+				break
+			}
+		}
+		_ = client.Close()
+	}()
+
+	wg.Wait()
+}
+
+// TestFIX17R2_RedisBackendSetNX_ReplyDropped_ReportsAmbiguousNotFalseClaim
+// pins that a SET NX whose reply is lost after the command reached Redis
+// must not be reported as (false, nil) — that reads as "someone else
+// already claimed it" when in fact THIS call may have (and, per the proxy,
+// did) claim it. It must instead report the request outcome as unknown
+// (ErrSetNXAmbiguous), and the key must actually exist in Redis (proving
+// the write really landed, so treating it as "not claimed" would have been
+// a false negative on a first-ever claim).
+func TestFIX17R2_RedisBackendSetNX_ReplyDropped_ReportsAmbiguousNotFalseClaim(t *testing.T) {
+	mr, err := miniredis.Run()
+	require.NoError(t, err)
+	t.Cleanup(mr.Close)
+
+	proxy := newDropReplyProxy(t, mr.Addr(), []byte("NX"))
+
+	config := DefaultRedisConfig(proxy.Addr())
+	config.PoolSize = 1
+	backend, err := NewRedisBackend(config)
+	require.NoError(t, err)
+	defer func() { _ = backend.Close() }()
+
+	ctx := context.Background()
+	key := "first-claim"
+
+	claimed, setNXErr := backend.SetNX(ctx, key, []byte("v1"), time.Minute)
+
+	assert.False(t, claimed, "an ambiguous SetNX outcome must not report claimed=true")
+	require.Error(t, setNXErr, "a lost SET NX reply must surface as an error, not (false, nil) — nil reads as \"someone else already claimed it\"")
+	assert.Same(t, ErrSetNXAmbiguous, setNXErr, "a lost SET NX reply must surface as the ambiguous sentinel specifically")
+
+	// Confirm directly against miniredis (bypassing the proxy) that the
+	// write actually landed — this is what makes (false, nil) wrong: it
+	// would have told the caller "not claimed" about a key Redis already
+	// holds.
+	val, verr := mr.Get(config.RedisPrefix + key)
+	require.NoError(t, verr)
+	assert.Equal(t, "v1", val, "the SET NX must have actually applied in Redis despite the dropped reply")
+}