fix: snapshot patterns for refresh-tracker and metadata URLs

Two related lock-free snapshot refactors addressing the remaining
post-v1.0.16 code-review findings.

1. refreshAttemptTracker: per-field atomic.Load/Store -> atomic.Value
   snapshot of *attemptState (refresh_coordinator.go).

   Previously each tracker held five independently-atomic fields. The
   cooldown-exit reset wrote cooldownEndNano = 0 first, then separately
   stored attempts = 1 and windowStartNano = now. A concurrent
   isInCooldown call could observe cooldownEndNano = 0 (reset just
   completed) with attempts still at MaxRefreshAttempts, immediately
   triggering a fresh cooldown — a benign double-trigger race that
   nonetheless meant the state machine had observable intermediate
   states.

   New design: state is a *attemptState (immutable) published via
   atomic.Value. All transitions (record/success/failure/window-reset/
   cooldown-enter/cooldown-exit) go through mutateState, which runs a
   CAS loop: load current snapshot -> construct fresh snapshot ->
   CompareAndSwap. Either the entire new state publishes or none of
   it does — no intermediate visibility, no cross-field race.

   Under Yaegi this collapses 3-5 per-field atomic dispatches into one
   atomic.Value.Load on the read path. Write paths pay an extra
   allocation for the new snapshot but avoid the cross-field hazard.

2. MetadataSnapshot: hot-path readers use atomic.Value instead of
   metadataMu.RLock (middleware.go, types.go, main.go, utilities.go).

   middleware.ServeHTTP previously took metadataMu.RLock on every
   non-bypass request to read the single field issuerURL. Under Yaegi
   each RLock acquisition costs 1-5ms of interpreter dispatch.
   updateMetadataEndpoints now also publishes an immutable
   *MetadataSnapshot via atomic.Value; the hot-path reader loads it
   in one op via t.metadataSnap(). Falls back to the legacy
   metadataMu.RLock pattern when the snapshot is unpublished (some
   test setups initialize the struct fields directly without going
   through updateMetadataEndpoints).

   Less-frequent callers (helpers, logout, token_introspection) still
   take metadataMu.RLock and are unchanged. The snapshot strictly
   subsets the metadataMu-protected fields, so those readers see
   identical data.

Note on atomic.Pointer[T]: this would have been the cleaner type but
yaegi v0.16.1's stdlib (used by traefik:v3.7.1) exposes only the
legacy unsafe.Pointer-based atomic primitives — no generic Pointer[T].
atomic.Value provides the same semantics via interface{} + type assert.

All tests pass with -race; golangci-lint clean.

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: lukaszraczylo
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: https://monzo.me/lukaszraczylo

.github/workflows/release.yml

@@ -11,7 +11,9 @@ on:
   workflow_dispatch:
 
 permissions:
+  id-token: write
   contents: write
+  packages: write
 
 jobs:
   release:

.gitignore

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

.golangci.yml

@@ -14,21 +14,22 @@ linters:
     - gosec
     - misspell
     - noctx
-    - nolintlint
     - prealloc
     - revive
     - rowserrcheck
     - sqlclosecheck
     - unconvert
     - unparam
-    - whitespace
   disable:
     - exhaustive
     - funlen
     - gocognit
+    - gocyclo           # Disabled: OAuth/OIDC flows are inherently complex
+    - goprintffuncname  # Disabled: naming convention is project-specific
     - lll
     - mnd
     - testpackage
+    - whitespace        # Disabled: style preference about newlines
     - wsl
   settings:
     dupl:
@@ -47,29 +48,13 @@ linters:
         - fmt.Fprintln
     goconst:
       min-len: 3
-      min-occurrences: 10  # Increased to reduce noise for standard OAuth2/OIDC strings
+      min-occurrences: 15  # Increased to reduce noise for standard OAuth2/OIDC strings and common patterns like "true"
       ignore-tests: true
     gocritic:
-      # Using default enabled checks in v2
-      enabled-checks:
-        - appendCombine
-        - boolExprSimplify
-        - builtinShadow
-        - commentedOutCode
-        - emptyFallthrough
-        - equalFold
-        - hexLiteral
-        - indexAlloc
-        - initClause
-        - methodExprCall
-        - nestingReduce
-        - rangeExprCopy
-        - rangeValCopy
-        - stringXbytes
-        - typeAssertChain
-        - typeUnparen
-        - unlabelStmt
-        - yodaStyleExpr
+      # Disable style-only checks that add noise
+      disabled-checks:
+        - ifElseChain      # Style preference, switch not always clearer
+        - elseif           # Style preference
     gocyclo:
       min-complexity: 30  # OAuth/OIDC flows are inherently complex; set higher for Yaegi compatibility
     gosec:
@@ -106,23 +91,23 @@ linters:
         - name: error-return
         - name: error-strings
         - name: error-naming
-        - name: exported
-        - name: if-return
+        # - name: exported  # Disabled: too noisy, not all exported functions need comments
+        # - name: if-return  # Disabled: style preference
         - name: increment-decrement
-        - name: var-naming
-        - name: var-declaration
-        - name: package-comments
+        # - name: var-naming  # Disabled: too strict for legacy code (IP vs Ip)
+        # - name: var-declaration  # Disabled: explicit zero values can be clearer
+        # - name: package-comments  # Disabled: handled by other tools
         - name: range
         - name: receiver-naming
         - name: time-naming
         - name: unexported-return
-        - name: indent-error-flow
+        # - name: indent-error-flow  # Disabled: style preference
         - name: errorf
-        - name: empty-block
+        # - name: empty-block  # Disabled: sometimes empty blocks are intentional
         - name: superfluous-else
-        - name: unused-parameter
+        # - name: unused-parameter  # Disabled: test callbacks and interface implementations often have required unused params
         - name: unreachable-code
-        - name: redefines-builtin-id
+        # - name: redefines-builtin-id  # Disabled: min/max helpers are common before Go 1.21
     unparam:
       check-exported: false
     staticcheck:
@@ -132,8 +117,15 @@ linters:
         - -QF1003  # Tagged switch - style preference, may affect Yaegi
         - -QF1007  # Merge conditional assignment - style preference
         - -QF1008  # Remove embedded field - may break Yaegi compatibility
+        - -QF1011  # Omit type from declaration - style preference
         - -QF1012  # Use fmt.Fprintf - style preference
+        - -SA9003  # Empty branch - sometimes intentional for future work
+        - -ST1000  # Package comment format - not required for all packages
         - -ST1003  # Package name format - allowed for test packages
+        - -ST1016  # Receiver name consistency - legacy code
+        - -ST1020  # Comment format for methods - style preference
+        - -ST1021  # Comment format for types - style preference
+        - -ST1023  # Omit type from declaration - style preference
   exclusions:
     generated: lax
     rules:
@@ -144,18 +136,43 @@ linters:
           - goconst
           - gocyclo
           - gosec
+          - govet
+          - ineffassign
           - noctx
           - prealloc
           - unparam
+          - revive
+          - gocritic
         path: _test\.go
       - linters:
           - dupl
           - gocyclo
+          - govet
+          - noctx
+          - prealloc
+          - unparam
+          - revive
+          - gocritic
         path: test.*\.go
       - linters:
           - gocritic
           - unused
+          - errcheck
+          - revive
         path: mocks.*\.go
+      - linters:
+          - errcheck
+          - revive
+          - gocritic
+          - govet
+          - unparam
+        path: internal/testutil/
+      - linters:
+          - govet
+          - unparam
+          - noctx
+          - prealloc
+        path: integration/
       - linters:
           - gosec
         text: 'G404:'

.goreleaser.yaml

@@ -47,3 +47,14 @@ release:
   name_template: "v{{ .Version }}"
   draft: false
   prerelease: auto
+
+signs:
+  - cmd: cosign
+    signature: "${artifact}.sigstore.json"
+    args:
+      - sign-blob
+      - "--bundle=${signature}"
+      - "${artifact}"
+      - "--yes"
+    artifacts: checksum
+    output: true

SECURITY_FIX.md

@@ -0,0 +1,49 @@
+# Security Fix: Integer Overflow Protection in Cache Serialization
+
+## Summary
+
+Fixed **High severity** integer overflow vulnerability identified by GitHub Advanced Security in PR #117.
+
+## Vulnerability
+
+**Locations**: `universal_cache.go` lines 789 and 811
+- `result := make([]byte, len(bytes)+1)` - Raw bytes path
+- `result := make([]byte, len(jsonData)+1)` - JSON encoding path
+
+**Risk**: Potential integer overflow when allocating memory for very large cache entries.
+
+## Fix Applied
+
+1. **Added size limit constant**:
+   ```go
+   maxCacheEntrySize = 64 * 1024 * 1024 // 64 MiB
+   ```
+
+2. **Size validation before allocation**:
+   - Validates entry size doesn't exceed limit
+   - Validates adding marker byte won't overflow
+   - Returns descriptive error messages
+
+3. **Comprehensive test coverage**:
+   - Oversized byte slices (>64 MiB)
+   - Exact max size edge case
+   - Safe sizes (normal operation)
+   - Large JSON data structures
+
+## Verification
+
+✅ All tests pass with race detection
+✅ No security issues (golangci-lint, gosec)
+✅ 76.3% test coverage maintained
+
+## Impact
+
+- No breaking changes
+- Negligible performance overhead
+- Prevents potential buffer overflows
+- Predictable memory usage
+
+---
+
+**Date**: January 8, 2026
+**Severity**: High → Resolved

audience_test.go

@@ -84,8 +84,8 @@ func TestAudienceValidation(t *testing.T) {
 	tests := []struct {
 		name          string
 		audience      string
-		expectError   bool
 		errorContains string
+		expectError   bool
 	}{
 		{
 			name:        "valid custom audience URL",
@@ -163,8 +163,8 @@ func TestConfigAudienceValidation(t *testing.T) {
 	tests := []struct {
 		name        string
 		audience    string
-		wantErr     bool
 		errContains string
+		wantErr     bool
 	}{
 		{
 			name:     "Empty audience is valid for backward compatibility",
@@ -732,11 +732,11 @@ func TestJWTAudienceVerification(t *testing.T) {
 	tokenCache := tc.addTokenCache(NewTokenCache())
 
 	tests := []struct {
+		tokenAudience   interface{}
 		name            string
 		configAudience  string
-		tokenAudience   interface{}
-		wantErr         bool
 		errContains     string
+		wantErr         bool
 		skipReplayCheck bool
 	}{
 		{
@@ -1491,7 +1491,7 @@ func TestAudienceEndToEndScenario(t *testing.T) {
 		if err := session.SetAuthenticated(true); err != nil {
 			t.Fatalf("Failed to set authenticated: %v", err)
 		}
-		session.SetEmail("user@company.com")
+		session.SetUserIdentifier("user@company.com")
 		session.SetIDToken(validJWT)
 		session.SetAccessToken(validJWT)
 

auth_flow.go

@@ -4,8 +4,7 @@ import (
 	"fmt"
 	"net/http"
 	"strings"
-
-	"github.com/google/uuid"
+	"time"
 )
 
 // validateRedirectCount checks if redirect limit is exceeded and handles the error
@@ -44,7 +43,7 @@ func (t *TraefikOidc) generatePKCEParameters() (string, string, error) {
 func (t *TraefikOidc) prepareSessionForAuthentication(session *SessionData, csrfToken, nonce, codeVerifier, incomingPath string) {
 	// Clear all existing session data
 	_ = session.SetAuthenticated(false) // Safe to ignore: clearing authentication state on new flow
-	session.SetEmail("")
+	session.SetUserIdentifier("")
 	session.SetAccessToken("")
 	session.SetRefreshToken("")
 	session.SetIDToken("")
@@ -77,7 +76,12 @@ func (t *TraefikOidc) defaultInitiateAuthentication(rw http.ResponseWriter, req
 		return
 	}
 
-	csrfToken := uuid.NewString()
+	csrfToken, err := newUUIDv4()
+	if err != nil {
+		t.logger.Errorf("Failed to generate CSRF token: %v", err)
+		http.Error(rw, "Failed to generate CSRF token", http.StatusInternalServerError)
+		return
+	}
 	nonce, err := generateNonce()
 	if err != nil {
 		t.logger.Errorf("Failed to generate nonce: %v", err)
@@ -246,7 +250,7 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 		t.sendErrorResponse(rw, req, "Failed to update session", http.StatusInternalServerError)
 		return
 	}
-	session.SetEmail(userIdentifier) // SetEmail stores the user identifier (email or other claim)
+	session.SetUserIdentifier(userIdentifier)
 	session.SetIDToken(tokenResponse.IDToken)
 	session.SetAccessToken(tokenResponse.AccessToken)
 	session.SetRefreshToken(tokenResponse.RefreshToken)
@@ -286,7 +290,7 @@ func (t *TraefikOidc) handleExpiredToken(rw http.ResponseWriter, req *http.Reque
 	session.SetIDToken("")
 	session.SetAccessToken("")
 	session.SetRefreshToken("")
-	session.SetEmail("")
+	session.SetUserIdentifier("")
 	// Clear CSRF tokens to prevent replay attacks
 	session.SetCSRF("")
 	session.SetNonce("")
@@ -334,9 +338,54 @@ func (t *TraefikOidc) isAjaxRequest(req *http.Request) bool {
 		strings.Contains(accept, "application/json")
 }
 
-// isRefreshTokenExpired checks if refresh token is likely expired (older than 6 hours)
-func (t *TraefikOidc) isRefreshTokenExpired(session *SessionData) bool {
-	// This is a heuristic check - actual implementation would depend on
-	// the specific provider and token metadata
-	return false // Placeholder implementation
+// isNonNavigationRequest reports whether the request is a browser
+// sub-resource (script, image, stylesheet, fetch, serviceWorker) rather than
+// a top-level HTML navigation. Non-navigation requests MUST NOT trigger an
+// OIDC redirect flow: several sub-resource loads happening in parallel would
+// each call defaultInitiateAuthentication, each overwriting the session's
+// CSRF/nonce, breaking the eventual callback (issue #129).
+//
+// Detection prefers Sec-Fetch-Mode, which all modern browsers send
+// (Chrome/Edge/Firefox/Safari). For older or non-browser clients we fall
+// back to Accept: if Accept is present and does not list text/html, treat
+// it as a sub-resource. An empty/missing Accept is assumed to be navigation
+// (safer to redirect than 401 on an ambiguous request).
+func (t *TraefikOidc) isNonNavigationRequest(req *http.Request) bool {
+	if mode := req.Header.Get("Sec-Fetch-Mode"); mode != "" {
+		return mode != "navigate"
+	}
+	accept := req.Header.Get("Accept")
+	if accept == "" || accept == "*/*" {
+		return false
+	}
+	return !strings.Contains(accept, "text/html")
+}
+
+// isRefreshTokenExpired checks whether the stored refresh token is likely
+// past its useful lifetime, using the cookie-side issued_at timestamp set by
+// SetRefreshToken. IdPs do not expose RT TTL on the wire, so this is a
+// conservative heuristic gated by t.maxRefreshTokenAge (default 6h, set via
+// MaxRefreshTokenAgeSeconds; 0 disables the check).
+//
+// The point of this check is to short-circuit the refresh path BEFORE the
+// thundering herd hits the IdP for a token the provider has almost certainly
+// revoked. Together with the RefreshCoordinator wireup, it keeps Grafana-
+// style polling clients from looping on invalid_grant after a long pause.
+func (t *TraefikOidc) isRefreshTokenExpired(session *SessionData) bool {
+	if t == nil || session == nil {
+		return false
+	}
+	if t.maxRefreshTokenAge <= 0 {
+		return false
+	}
+
+	issuedAt := session.GetRefreshTokenIssuedAt()
+	if issuedAt.IsZero() {
+		// No timestamp recorded (legacy session pre-dating the issued_at
+		// field). Don't force a re-auth - attempt refresh once and let the
+		// IdP be the source of truth.
+		return false
+	}
+
+	return time.Since(issuedAt) > t.maxRefreshTokenAge
 }

auth_flow_behaviour_test.go

@@ -192,7 +192,7 @@ func (s *AuthFlowBehaviourSuite) TestPrepareSessionForAuthentication() {
 
 	// Pre-populate session with old data
 	_ = session.SetAuthenticated(true)
-	session.SetEmail("old@example.com")
+	session.SetUserIdentifier("old@example.com")
 	session.SetAccessToken("old-access-token-with-many-characters")
 	session.SetRefreshToken("old-refresh-token-with-many-characters")
 	session.SetIDToken("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.signature")
@@ -207,7 +207,7 @@ func (s *AuthFlowBehaviourSuite) TestPrepareSessionForAuthentication() {
 
 	// Verify old data is cleared
 	s.False(session.GetAuthenticated())
-	s.Empty(session.GetEmail())
+	s.Empty(session.GetUserIdentifier())
 
 	// Verify new data is set
 	s.Equal(csrfToken, session.GetCSRF())
@@ -253,8 +253,8 @@ func (s *AuthFlowBehaviourSuite) TestPrepareSessionForAuthentication_WithPKCE()
 // TestIsAjaxRequest tests AJAX request detection
 func (s *AuthFlowBehaviourSuite) TestIsAjaxRequest() {
 	testCases := []struct {
-		name       string
 		headers    map[string]string
+		name       string
 		expectAjax bool
 	}{
 		{
@@ -305,6 +305,90 @@ func (s *AuthFlowBehaviourSuite) TestIsAjaxRequest() {
 	}
 }
 
+// TestIsNonNavigationRequest verifies browser sub-resource detection used to
+// suppress OIDC redirects on parallel static-asset loads (issue #129).
+func (s *AuthFlowBehaviourSuite) TestIsNonNavigationRequest() {
+	testCases := []struct {
+		headers             map[string]string
+		name                string
+		expectNonNavigation bool
+	}{
+		{
+			name:                "Sec-Fetch-Mode navigate",
+			headers:             map[string]string{"Sec-Fetch-Mode": "navigate"},
+			expectNonNavigation: false,
+		},
+		{
+			name:                "Sec-Fetch-Mode no-cors",
+			headers:             map[string]string{"Sec-Fetch-Mode": "no-cors"},
+			expectNonNavigation: true,
+		},
+		{
+			name:                "Sec-Fetch-Mode cors",
+			headers:             map[string]string{"Sec-Fetch-Mode": "cors"},
+			expectNonNavigation: true,
+		},
+		{
+			name:                "Sec-Fetch-Mode same-origin (fetch in page)",
+			headers:             map[string]string{"Sec-Fetch-Mode": "same-origin"},
+			expectNonNavigation: true,
+		},
+		{
+			name:                "Accept text/html (fallback)",
+			headers:             map[string]string{"Accept": "text/html,application/xhtml+xml"},
+			expectNonNavigation: false,
+		},
+		{
+			name:                "Accept image/png (fallback)",
+			headers:             map[string]string{"Accept": "image/png,image/*;q=0.8"},
+			expectNonNavigation: true,
+		},
+		{
+			name:                "Accept application/javascript (fallback)",
+			headers:             map[string]string{"Accept": "application/javascript"},
+			expectNonNavigation: true,
+		},
+		{
+			name:                "Accept */* treated as navigation",
+			headers:             map[string]string{"Accept": "*/*"},
+			expectNonNavigation: false,
+		},
+		{
+			name:                "No Accept header assumed navigation",
+			headers:             map[string]string{},
+			expectNonNavigation: false,
+		},
+		{
+			name: "Sec-Fetch-Mode beats Accept (navigate wins)",
+			headers: map[string]string{
+				"Sec-Fetch-Mode": "navigate",
+				"Accept":         "application/javascript",
+			},
+			expectNonNavigation: false,
+		},
+		{
+			name: "Sec-Fetch-Mode beats Accept (no-cors wins)",
+			headers: map[string]string{
+				"Sec-Fetch-Mode": "no-cors",
+				"Accept":         "text/html",
+			},
+			expectNonNavigation: true,
+		},
+	}
+
+	for _, tc := range testCases {
+		s.Run(tc.name, func() {
+			req := httptest.NewRequest(http.MethodGet, "/_static/asset.js", nil)
+			for key, value := range tc.headers {
+				req.Header.Set(key, value)
+			}
+
+			result := s.tOidc.isNonNavigationRequest(req)
+			s.Equal(tc.expectNonNavigation, result)
+		})
+	}
+}
+
 // TestHandleCallback_MissingState tests callback with missing state parameter
 func (s *AuthFlowBehaviourSuite) TestHandleCallback_MissingState() {
 	sessionManager, err := NewSessionManager(
@@ -627,7 +711,7 @@ func (s *AuthFlowBehaviourSuite) TestHandleExpiredToken() {
 	session, err := sessionManager.GetSession(req)
 	s.Require().NoError(err)
 	_ = session.SetAuthenticated(true)
-	session.SetEmail("test@example.com")
+	session.SetUserIdentifier("test@example.com")
 	session.SetIDToken("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.signature")
 	session.mainSession.Values["redirect_count"] = 3
 
@@ -636,7 +720,7 @@ func (s *AuthFlowBehaviourSuite) TestHandleExpiredToken() {
 
 	// Session should be cleared
 	s.False(session.GetAuthenticated())
-	s.Empty(session.GetEmail())
+	s.Empty(session.GetUserIdentifier())
 	s.Empty(session.GetIDToken())
 
 	// Redirect count should be reset to 0 and then incremented by defaultInitiateAuthentication

autocleanup.go

@@ -222,17 +222,16 @@ func (bt *BackgroundTask) run() {
 // TaskCircuitBreaker implements circuit breaker pattern for background task creation
 // It limits concurrent task execution and tracks failures to prevent system overload
 type TaskCircuitBreaker struct {
-	state            int32 // CircuitBreakerState
-	failureCount     int32
-	lastFailureTime  int64 // Unix timestamp
-	failureThreshold int32
-	timeout          time.Duration
 	logger           *Logger
-	// Concurrency limiting
-	concurrentTasks int32               // Current number of running tasks
-	maxConcurrent   int32               // Maximum concurrent tasks allowed
-	activeTasks     map[string]struct{} // Track active task names
-	tasksMu         sync.RWMutex        // Separate mutex for task tracking
+	activeTasks      map[string]struct{}
+	lastFailureTime  int64
+	timeout          time.Duration
+	tasksMu          sync.RWMutex
+	state            int32
+	failureCount     int32
+	failureThreshold int32
+	concurrentTasks  int32
+	maxConcurrent    int32
 }
 
 // NewTaskCircuitBreaker creates a new circuit breaker for background tasks
@@ -380,9 +379,9 @@ func (cb *TaskCircuitBreaker) OnTaskFailure(taskName string, err error) {
 // TaskRegistry maintains a registry of all active background tasks to prevent duplicates
 type TaskRegistry struct {
 	tasks  map[string]*BackgroundTask
-	mu     sync.RWMutex
 	cb     *TaskCircuitBreaker
 	logger *Logger
+	mu     sync.RWMutex
 }
 
 // GlobalTaskRegistry is the singleton instance for managing all background tasks
@@ -600,8 +599,9 @@ func GetGlobalTaskMemoryMonitor(logger *Logger) *TaskMemoryMonitor {
 	return globalTaskMemoryMonitor
 }
 
-// NewTaskMemoryMonitor creates a new memory monitor for task registry
-// Deprecated: Use GetGlobalTaskMemoryMonitor instead for singleton behavior
+// NewTaskMemoryMonitor creates a new memory monitor for task registry.
+//
+// Deprecated: Use GetGlobalTaskMemoryMonitor instead for singleton behavior.
 func NewTaskMemoryMonitor(logger *Logger, registry *TaskRegistry) *TaskMemoryMonitor {
 	return GetGlobalTaskMemoryMonitor(logger)
 }
@@ -713,7 +713,7 @@ func (mm *TaskMemoryMonitor) checkForMemoryIssues(stats TaskMemoryStats) {
 
 	// Check for goroutine leaks (arbitrary threshold)
 	if stats.Goroutines > 100 {
-		mm.logger.Infof("High goroutine count detected: %d", stats.Goroutines)
+		mm.logger.Debugf("High goroutine count detected: %d", stats.Goroutines)
 	}
 
 	// Check for heap growth without corresponding GC activity

azure_oidc_test.go

@@ -330,12 +330,12 @@ func TestValidateGoogleTokens(t *testing.T) {
 	ts.tOidc.refreshGracePeriod = 60 * time.Second
 
 	tests := []struct {
-		name            string
 		setupSession    func() *SessionData
+		name            string
+		description     string
 		expectedAuth    bool
 		expectedRefresh bool
 		expectedExpired bool
-		description     string
 	}{
 		{
 			name: "ValidGoogleTokens",
@@ -476,13 +476,13 @@ func TestIsUserAuthenticated(t *testing.T) {
 	ts.tOidc.refreshGracePeriod = 60 * time.Second
 
 	tests := []struct {
+		setupSession    func() *SessionData
 		name            string
 		providerType    string
-		setupSession    func() *SessionData
+		description     string
 		expectedAuth    bool
 		expectedRefresh bool
 		expectedExpired bool
-		description     string
 	}{
 		{
 			name:         "AzureProvider",
@@ -660,12 +660,12 @@ func TestValidateAzureTokensEdgeCases(t *testing.T) {
 	ts.tOidc.refreshGracePeriod = 60 * time.Second
 
 	tests := []struct {
-		name            string
 		setupSession    func() *SessionData
+		name            string
+		description     string
 		expectedAuth    bool
 		expectedRefresh bool
 		expectedExpired bool
-		description     string
 	}{
 		{
 			name: "UnauthenticatedWithRefreshToken",

background_tasks_ultra_test.go

@@ -29,8 +29,9 @@ func TestMemoryMonitorComprehensive(t *testing.T) {
 		pressure := monitor.GetMemoryPressure()
 		assert.Equal(t, MemoryPressureNone, pressure)
 
-		// Collect stats to populate lastStats
-		monitor.GetCurrentStats()
+		// Explicitly sample to populate lastStats; GetCurrentStats is now a
+		// cached read and no longer forces a runtime.ReadMemStats.
+		monitor.Refresh()
 
 		// Now should return a valid pressure level
 		pressure = monitor.GetMemoryPressure()
@@ -46,11 +47,13 @@ func TestMemoryMonitorComprehensive(t *testing.T) {
 		thresholds := DefaultMemoryAlertThresholds()
 		monitor := NewMemoryMonitor(newNoOpLogger(), thresholds)
 
-		// Start monitoring should not panic
+		// Start monitoring should not panic. Interval is clamped to the
+		// minimum (30s); we rely on Refresh() when we need a synchronous
+		// sample instead of waiting for a tick.
 		assert.NotPanics(t, func() {
 			ctx := context.Background()
-			monitor.StartMonitoring(ctx, 100*time.Millisecond)
-			time.Sleep(GetTestDuration(50 * time.Millisecond))
+			monitor.StartMonitoring(ctx, 0)
+			monitor.Refresh()
 		})
 
 		// Clean up
@@ -97,15 +100,15 @@ func TestMemoryMonitorComprehensive(t *testing.T) {
 
 	t.Run("String method returns pressure name", func(t *testing.T) {
 		pressures := []struct {
-			level MemoryPressureLevel
 			name  string
+			level MemoryPressureLevel
 		}{
-			{MemoryPressureNone, "None"},
-			{MemoryPressureLow, "Low"},
-			{MemoryPressureModerate, "Moderate"},
-			{MemoryPressureHigh, "High"},
-			{MemoryPressureCritical, "Critical"},
-			{MemoryPressureLevel(999), "Unknown"},
+			{level: MemoryPressureNone, name: "None"},
+			{level: MemoryPressureLow, name: "Low"},
+			{level: MemoryPressureModerate, name: "Moderate"},
+			{level: MemoryPressureHigh, name: "High"},
+			{level: MemoryPressureCritical, name: "Critical"},
+			{level: MemoryPressureLevel(999), name: "Unknown"},
 		}
 
 		for _, p := range pressures {
@@ -117,6 +120,9 @@ func TestMemoryMonitorComprehensive(t *testing.T) {
 		thresholds := DefaultMemoryAlertThresholds()
 		monitor := NewMemoryMonitor(newNoOpLogger(), thresholds)
 
+		// Refresh forces a synchronous sample; GetCurrentStats is a cached
+		// read, so we sample first to guarantee fresh data.
+		monitor.Refresh()
 		stats := monitor.GetCurrentStats()
 		assert.NotNil(t, stats)
 		assert.Greater(t, stats.HeapAllocBytes, uint64(0))
@@ -450,12 +456,12 @@ func TestMemoryMonitorIntegration(t *testing.T) {
 		monitor := NewMemoryMonitor(newNoOpLogger(), thresholds)
 		defer monitor.StopMonitoring()
 
-		// Start monitoring
+		// Start monitoring. The interval is clamped to the minimum (30s) so
+		// the ticker won't fire during the test; drive the sample manually via
+		// Refresh() instead.
 		ctx := context.Background()
-		monitor.StartMonitoring(ctx, 50*time.Millisecond)
-
-		// Wait for at least one check
-		time.Sleep(GetTestDuration(150 * time.Millisecond))
+		monitor.StartMonitoring(ctx, 0)
+		monitor.Refresh()
 
 		// Get pressure (should be a valid pressure level)
 		pressure := monitor.GetMemoryPressure()
@@ -488,6 +494,7 @@ func TestMemoryStatsCollection(t *testing.T) {
 		thresholds := DefaultMemoryAlertThresholds()
 		monitor := NewMemoryMonitor(newNoOpLogger(), thresholds)
 
+		monitor.Refresh()
 		stats := monitor.GetCurrentStats()
 
 		assert.NotNil(t, stats)
@@ -501,6 +508,7 @@ func TestMemoryStatsCollection(t *testing.T) {
 		thresholds := DefaultMemoryAlertThresholds()
 		monitor := NewMemoryMonitor(newNoOpLogger(), thresholds)
 
+		monitor.Refresh()
 		stats := monitor.GetCurrentStats()
 
 		// Should calculate and include pressure level
@@ -521,13 +529,14 @@ func TestMemoryStatsCollection(t *testing.T) {
 		// Allocate some memory
 		_ = make([]byte, 1024*1024) // 1MB
 
-		// Get stats before GC
-		beforeStats := monitor.GetCurrentStats()
+		// Get stats before GC (explicit Refresh so we have a fresh pre-GC
+		// snapshot to compare against, not the constructor baseline).
+		beforeStats := monitor.Refresh()
 
-		// Trigger GC
+		// Trigger GC (internally Refresh()es before and after)
 		monitor.TriggerGC()
 
-		// Get stats after GC
+		// Get stats after GC from cache (TriggerGC already refreshed it)
 		afterStats := monitor.GetCurrentStats()
 
 		// After GC should have different stats

bearer_auth.go

@@ -0,0 +1,592 @@
+// Package traefikoidc — bearer-token (M2M) authentication path.
+//
+// Disabled by default. When enabled via Config.EnableBearerAuth, requests
+// presenting "Authorization: Bearer <jwt>" are validated against the
+// configured OIDC provider (signature, issuer, audience, exp, replay-Get)
+// and the request is forwarded downstream without creating a cookie session.
+//
+// Design rules (kept here in code as the single source of truth):
+//   - Access tokens only. ID tokens are rejected via detectTokenType.
+//   - Audience is mandatory (enforced at startup in main.go).
+//   - alg + kid pinned BEFORE JWKS fetch to deny amplification probes.
+//   - 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.
+//   - 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,
+//     delimiter chars (, ; =) rejected.
+//   - On excluded URLs the Authorization header is stripped before forwarding.
+//
+// See docs/superpowers/specs/2026-05-18-bearer-token-auth-design.md and
+// docs/BEARER_AUTH.md for the full threat model.
+package traefikoidc
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+	"unicode"
+)
+
+const bearerPrefix = "Bearer "
+
+// bearerAlgAllowlist is the set of JWS algorithms accepted on the bearer
+// path. Asymmetric-only — HS* would allow public-key-as-HMAC-secret attacks
+// if any operator ever rotates a key into the symmetric branch by mistake;
+// "none" is obvious. Matches the allowlist enforced inside jwt.Verify but is
+// checked here BEFORE the JWKS fetch so attacker noise can't amplify.
+var bearerAlgAllowlist = map[string]struct{}{
+	"RS256": {}, "RS384": {}, "RS512": {},
+	"PS256": {}, "PS384": {}, "PS512": {},
+	"ES256": {}, "ES384": {}, "ES512": {},
+}
+
+// bearerKidMaxLen caps the JOSE kid header length to keep memory and cache-key
+// usage bounded against attacker-controlled values.
+const bearerKidMaxLen = 256
+
+// validKidChar is the allowlist for kid header characters. Letters, digits,
+// dot, underscore, hyphen, equals. Intentionally narrow; real-world kid
+// values are short URL-safe-base64-ish identifiers.
+func validKidChar(r rune) bool {
+	if r >= 'a' && r <= 'z' {
+		return true
+	}
+	if r >= 'A' && r <= 'Z' {
+		return true
+	}
+	if r >= '0' && r <= '9' {
+		return true
+	}
+	switch r {
+	case '.', '_', '-', '=':
+		return true
+	}
+	return false
+}
+
+// bearerError categorizes failure modes for the response builder. Categories
+// map 1:1 to the table in docs/superpowers/specs/2026-05-18-bearer-token-auth-design.md
+// §9 so behavior is auditable from spec to code.
+type bearerErrorKind int
+
+const (
+	bearerErrInvalidRequest bearerErrorKind = iota
+	bearerErrInvalidToken
+	bearerErrTokenInactive
+	bearerErrInvalidIdentifier
+	bearerErrForbidden
+	bearerErrThrottled
+	bearerErrIntrospectionUnavailable
+)
+
+type bearerError struct {
+	kind   bearerErrorKind
+	reason string
+}
+
+func (e *bearerError) Error() string { return e.reason }
+
+func newBearerError(kind bearerErrorKind, reason string) *bearerError {
+	return &bearerError{kind: kind, reason: reason}
+}
+
+// joseHeader is the minimal subset of the JWS protected header we inspect
+// BEFORE running the full verification pipeline. Lifted out so the alg+kid
+// pin can run without paying for parseJWT's full claim decode.
+type joseHeader struct {
+	Alg string `json:"alg"`
+	Kid string `json:"kid"`
+	Typ string `json:"typ"`
+}
+
+// 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
+// directly to a status code. The decoded header itself is not surfaced because
+// callers don't need it (verifyTokenWithOpts re-parses internally).
+func parseBearerJOSEHeader(token string) *bearerError {
+	dot := strings.IndexByte(token, '.')
+	if dot <= 0 {
+		return newBearerError(bearerErrInvalidToken, "malformed JWT: no header segment")
+	}
+	raw, err := base64.RawURLEncoding.DecodeString(token[:dot])
+	if err != nil {
+		// Some IdPs pad with '='; tolerate by retrying with StdEncoding.
+		raw, err = base64.URLEncoding.DecodeString(token[:dot])
+		if err != nil {
+			return newBearerError(bearerErrInvalidToken, "malformed JWT: header not base64url")
+		}
+	}
+	var hdr joseHeader
+	if err := json.Unmarshal(raw, &hdr); err != nil {
+		return newBearerError(bearerErrInvalidToken, "malformed JWT: header not JSON")
+	}
+	if _, ok := bearerAlgAllowlist[hdr.Alg]; !ok {
+		return newBearerError(bearerErrInvalidToken, fmt.Sprintf("disallowed alg %q on bearer path", hdr.Alg))
+	}
+	if hdr.Kid == "" {
+		return newBearerError(bearerErrInvalidToken, "missing kid header")
+	}
+	if len(hdr.Kid) > bearerKidMaxLen {
+		return newBearerError(bearerErrInvalidToken, "kid header exceeds max length")
+	}
+	for _, r := range hdr.Kid {
+		if !validKidChar(r) {
+			return newBearerError(bearerErrInvalidToken, "kid header contains disallowed characters")
+		}
+	}
+	return nil
+}
+
+// sanitizeBearerIdentifier validates and trims a principal identifier before
+// it is injected into request headers. Layered defense: net/http will reject
+// CRLF on the wire too, but rejecting early gives clearer error logs and
+// prevents bidi-override / delimiter chars that pass net/http's narrower
+// checks but confuse downstream parsers and admin UIs.
+func sanitizeBearerIdentifier(raw string, maxLen int) (string, *bearerError) {
+	identifier := strings.TrimSpace(raw)
+	if identifier == "" {
+		return "", newBearerError(bearerErrInvalidIdentifier, "identifier claim empty")
+	}
+	if maxLen > 0 && len(identifier) > maxLen {
+		return "", newBearerError(bearerErrInvalidIdentifier, "identifier exceeds max length")
+	}
+	for _, r := range identifier {
+		if unicode.IsControl(r) {
+			return "", newBearerError(bearerErrInvalidIdentifier, "identifier contains control character")
+		}
+		// Unicode bidi-override range (RTL spoofing of admin UI / SIEM).
+		if (r >= 0x202A && r <= 0x202E) || (r >= 0x2066 && r <= 0x2069) {
+			return "", newBearerError(bearerErrInvalidIdentifier, "identifier contains bidi-override character")
+		}
+		if r == ',' || r == ';' || r == '=' {
+			return "", newBearerError(bearerErrInvalidIdentifier, "identifier contains delimiter character")
+		}
+	}
+	return identifier, nil
+}
+
+// resolveBearerIdentifier picks the principal identifier from claims using
+// the configured BearerIdentifierClaim (default "sub"). Decoupled from
+// userIdentifierClaim (cookie path) to avoid the unverified-email spoofing
+// vector documented in the spec §13.
+func resolveBearerIdentifier(claims map[string]interface{}, claimName string) (string, *bearerError) {
+	if claimName == "" {
+		claimName = "sub"
+	}
+	raw, ok := claims[claimName]
+	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))
+	}
+	return str, nil
+}
+
+// enforceMultiAudienceAzp implements the spec hardening: when aud is a
+// multi-element array, require an azp claim equal to clientID. Single-string
+// aud is unaffected (existing verifyAudience handles it).
+func enforceMultiAudienceAzp(claims map[string]interface{}, clientID string) *bearerError {
+	audRaw, ok := claims["aud"]
+	if !ok {
+		return nil // verifyToken already rejects missing aud
+	}
+	arr, ok := audRaw.([]interface{})
+	if !ok {
+		return nil // single-string aud
+	}
+	if len(arr) <= 1 {
+		return nil
+	}
+	azpRaw, ok := claims["azp"]
+	if !ok {
+		return newBearerError(bearerErrInvalidToken, "multi-audience token missing azp")
+	}
+	azp, ok := azpRaw.(string)
+	if !ok || azp == "" {
+		return newBearerError(bearerErrInvalidToken, "multi-audience token has empty/non-string azp")
+	}
+	if azp != clientID {
+		return newBearerError(bearerErrInvalidToken, "multi-audience token azp does not match clientID")
+	}
+	return nil
+}
+
+// enforceIatAge implements the spec MaxTokenAgeSeconds bound on iat. Bounds
+// clock-manipulation / forever-token abuse without rejecting tokens with a
+// normal iat just because the issuer's clock skews a few seconds.
+func enforceIatAge(claims map[string]interface{}, maxAge time.Duration) *bearerError {
+	if maxAge <= 0 {
+		return nil
+	}
+	iatRaw, ok := claims["iat"].(float64)
+	if !ok {
+		// jwt.Verify already requires iat; this branch shouldn't be reached.
+		return newBearerError(bearerErrInvalidToken, "missing iat claim")
+	}
+	iat := time.Unix(int64(iatRaw), 0)
+	if time.Since(iat) > maxAge {
+		return newBearerError(bearerErrInvalidToken, "token iat outside age bound")
+	}
+	return nil
+}
+
+// hashIdentifierForLog returns a short SHA-256 prefix safe for info-level
+// logs. Full identifier is only emitted at debug. Satisfies the audit
+// requirement (trace which principal was rejected) without leaking PII.
+func hashIdentifierForLog(identifier string) string {
+	if identifier == "" {
+		return "(none)"
+	}
+	sum := sha256.Sum256([]byte(identifier))
+	return hex.EncodeToString(sum[:4]) // 8 hex chars
+}
+
+// --- Per-IP failure throttle ---
+
+// bearerFailureTracker records consecutive bearer-auth 401s per source IP and
+// parks repeat offenders in a 429 penalty box. Limits offline-guessing-style
+// attacks and protects the shared rate-limiter / JWKS endpoint from being
+// burned by a single source.
+type bearerFailureTracker struct {
+	mu      sync.Mutex
+	entries map[string]*bearerFailureEntry
+	// Configuration snapshot. Captured at construction so a hot reconfigure
+	// doesn't race with the per-request paths.
+	threshold int
+	window    time.Duration
+	penalty   time.Duration
+}
+
+type bearerFailureEntry struct {
+	firstFailureAt time.Time
+	penaltyUntil   time.Time
+	count          int
+}
+
+func newBearerFailureTracker(threshold int, window, penalty time.Duration) *bearerFailureTracker {
+	if threshold <= 0 {
+		threshold = 20
+	}
+	if window <= 0 {
+		window = 60 * time.Second
+	}
+	if penalty <= 0 {
+		penalty = 60 * time.Second
+	}
+	return &bearerFailureTracker{
+		entries:   make(map[string]*bearerFailureEntry),
+		threshold: threshold,
+		window:    window,
+		penalty:   penalty,
+	}
+}
+
+// blocked reports whether the source IP is currently in the penalty box.
+// Returns (true, retryAfter) when blocked; (false, 0) when allowed.
+func (b *bearerFailureTracker) blocked(ip string) (bool, time.Duration) {
+	if b == nil || ip == "" {
+		return false, 0
+	}
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	e, ok := b.entries[ip]
+	if !ok {
+		return false, 0
+	}
+	now := time.Now()
+	if !e.penaltyUntil.IsZero() && now.Before(e.penaltyUntil) {
+		return true, time.Until(e.penaltyUntil)
+	}
+	return false, 0
+}
+
+// recordFailure increments the failure counter for the given IP and trips
+// the penalty box once threshold-within-window is exceeded.
+func (b *bearerFailureTracker) recordFailure(ip string) {
+	if b == nil || ip == "" {
+		return
+	}
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	now := time.Now()
+	e, ok := b.entries[ip]
+	if !ok || now.Sub(e.firstFailureAt) > b.window {
+		e = &bearerFailureEntry{firstFailureAt: now}
+		b.entries[ip] = e
+	}
+	e.count++
+	if e.count >= b.threshold {
+		e.penaltyUntil = now.Add(b.penalty)
+	}
+}
+
+// recordSuccess clears the failure counter for the given IP after a
+// successful bearer auth.
+func (b *bearerFailureTracker) recordSuccess(ip string) {
+	if b == nil || ip == "" {
+		return
+	}
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	delete(b.entries, ip)
+}
+
+// clientIPForBearer returns the source IP used to key the failure tracker.
+// Trusts only the request's transport-level RemoteAddr; X-Forwarded-For is
+// intentionally ignored to avoid attacker-controlled key spoofing. Behind a
+// trusted reverse proxy where every request shares one IP, the throttle is
+// still useful (caps attacker churn through that proxy) — operators wanting
+// per-real-client throttling must terminate at this middleware.
+func clientIPForBearer(req *http.Request) string {
+	if req == nil {
+		return ""
+	}
+	host, _, err := net.SplitHostPort(req.RemoteAddr)
+	if err != nil {
+		return req.RemoteAddr
+	}
+	return host
+}
+
+// --- Bearer auth entrypoint ---
+
+// detectBearerToken returns (token, true) when the request carries a usable
+// Authorization: Bearer header. Case-insensitive on the scheme. Returns
+// ("", false) for any other shape.
+func detectBearerToken(req *http.Request) (string, bool) {
+	if req == nil {
+		return "", false
+	}
+	h := req.Header.Get("Authorization")
+	if len(h) < len(bearerPrefix) {
+		return "", false
+	}
+	if !strings.EqualFold(h[:len(bearerPrefix)], bearerPrefix) {
+		return "", false
+	}
+	token := strings.TrimSpace(h[len(bearerPrefix):])
+	if token == "" {
+		return "", false
+	}
+	return token, true
+}
+
+// hasSessionCookie reports whether the request carries any cookie matching
+// the session prefix. Used to implement the cookie-wins-by-default
+// precedence rule when both bearer and cookie are present.
+func (t *TraefikOidc) hasSessionCookie(req *http.Request) bool {
+	if t.sessionManager == nil {
+		return false
+	}
+	prefix := t.sessionManager.GetCookiePrefix()
+	if prefix == "" {
+		return false
+	}
+	for _, c := range req.Cookies() {
+		if strings.HasPrefix(c.Name, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+// writeBearerError writes the canonical 401/403/429/503 response per spec §9.
+// Body is always generic; reason is logged at debug only. The
+// WWW-Authenticate hint is gated by config (default on, RFC 6750 compliant).
+func (t *TraefikOidc) writeBearerError(rw http.ResponseWriter, req *http.Request, err *bearerError) {
+	var (
+		status     int
+		errCode    string
+		body       string
+		retryAfter time.Duration
+	)
+	switch err.kind {
+	case bearerErrInvalidRequest:
+		status = http.StatusUnauthorized
+		errCode = "invalid_request"
+		body = "Unauthorized"
+	case bearerErrInvalidToken, bearerErrTokenInactive, bearerErrInvalidIdentifier:
+		status = http.StatusUnauthorized
+		errCode = "invalid_token"
+		body = "Unauthorized"
+	case bearerErrForbidden:
+		status = http.StatusForbidden
+		body = "Access denied"
+	case bearerErrThrottled:
+		status = http.StatusTooManyRequests
+		body = "Too Many Requests"
+		retryAfter = t.bearerFailurePenalty
+	case bearerErrIntrospectionUnavailable:
+		status = http.StatusServiceUnavailable
+		body = "Service Unavailable"
+	default:
+		status = http.StatusUnauthorized
+		body = "Unauthorized"
+	}
+
+	if t.bearerEmitWWWAuthenticate && errCode != "" {
+		rw.Header().Set("WWW-Authenticate", fmt.Sprintf(`Bearer error=%q`, errCode))
+	}
+	if retryAfter > 0 {
+		rw.Header().Set("Retry-After", fmt.Sprintf("%d", int(retryAfter.Seconds())))
+	}
+	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
+
+	if t.logger != nil {
+		t.logger.Debugf("bearer auth rejected: status=%d category=%v reason=%q path=%s",
+			status, err.kind, err.reason, req.URL.Path)
+	}
+}
+
+// handleBearerRequest is the entry point invoked by ServeHTTP when the
+// EnableBearerAuth flag is set, the request carries an Authorization: Bearer
+// header, and the (configurable) cookie-precedence rule allows the bearer
+// path to run.
+func (t *TraefikOidc) handleBearerRequest(rw http.ResponseWriter, req *http.Request) {
+	ip := clientIPForBearer(req)
+
+	if blocked, retryAfter := t.bearerFailureTracker.blocked(ip); blocked {
+		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())))
+		}
+		t.writeBearerError(rw, req, throttled)
+		return
+	}
+
+	token, ok := detectBearerToken(req)
+	if !ok {
+		t.bearerFailureTracker.recordFailure(ip)
+		t.writeBearerError(rw, req, newBearerError(bearerErrInvalidRequest, "missing or empty bearer token"))
+		return
+	}
+	if len(token) > AccessTokenConfig.MaxLength {
+		t.bearerFailureTracker.recordFailure(ip)
+		t.writeBearerError(rw, req, newBearerError(bearerErrInvalidToken, "token exceeds max length"))
+		return
+	}
+	if strings.Count(token, ".") != 2 {
+		t.bearerFailureTracker.recordFailure(ip)
+		t.writeBearerError(rw, req, newBearerError(bearerErrInvalidToken, "token is not a 3-segment JWT"))
+		return
+	}
+
+	if bErr := parseBearerJOSEHeader(token); bErr != nil {
+		t.bearerFailureTracker.recordFailure(ip)
+		t.writeBearerError(rw, req, bErr)
+		return
+	}
+
+	p, bErr := t.buildPrincipalFromBearerToken(token)
+	if bErr != nil {
+		t.bearerFailureTracker.recordFailure(ip)
+		t.writeBearerError(rw, req, bErr)
+		return
+	}
+
+	t.bearerFailureTracker.recordSuccess(ip)
+	if t.logger != nil {
+		t.logger.Debugf("bearer auth success: identifier_hash=%s path=%s",
+			hashIdentifierForLog(p.Identifier), req.URL.Path)
+	}
+	t.forwardAuthorized(rw, req, p)
+}
+
+// buildPrincipalFromBearerToken runs the full bearer verification pipeline
+// 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 {
+		return nil, newBearerError(bearerErrInvalidToken, "token verification failed: "+err.Error())
+	}
+
+	parsed, err := parseJWT(token)
+	if err != nil {
+		return nil, newBearerError(bearerErrInvalidToken, "post-verify parseJWT failed: "+err.Error())
+	}
+	claims := parsed.Claims
+
+	// Token-type guard. Reuse the well-tested classifier which already
+	// checks nonce / typ=at+jwt / token_use / scope / aud-vs-clientID.
+	if t.detectTokenType(parsed, token) {
+		return nil, newBearerError(bearerErrInvalidToken, "ID tokens are not accepted on the bearer path")
+	}
+	// Belt-and-braces explicit rejection (cheap, catches edge cases not
+	// covered by detectTokenType's heuristic).
+	if nonce, ok := claims["nonce"].(string); ok && nonce != "" {
+		return nil, newBearerError(bearerErrInvalidToken, "nonce claim present (ID-token shape)")
+	}
+	if tu, ok := claims["token_use"].(string); ok && tu == "id" {
+		return nil, newBearerError(bearerErrInvalidToken, "token_use=id rejected")
+	}
+
+	if bErr := enforceMultiAudienceAzp(claims, t.clientID); bErr != nil {
+		return nil, bErr
+	}
+	if bErr := enforceIatAge(claims, t.maxTokenAge); bErr != nil {
+		return nil, bErr
+	}
+
+	if t.requireTokenIntrospection {
+		if bErr := t.introspectOnBearerPath(token); bErr != nil {
+			return nil, bErr
+		}
+	}
+
+	rawIdentifier, bErr := resolveBearerIdentifier(claims, t.bearerIdentifierClaim)
+	if bErr != nil {
+		return nil, bErr
+	}
+	identifier, bErr := sanitizeBearerIdentifier(rawIdentifier, t.maxIdentifierLength)
+	if bErr != nil {
+		return nil, bErr
+	}
+
+	subject, _ := claims["sub"].(string)
+	clientID, _ := claims["azp"].(string)
+	if clientID == "" {
+		clientID, _ = claims["client_id"].(string)
+	}
+
+	return &principal{
+		Source:      sourceBearer,
+		Identifier:  identifier,
+		Subject:     subject,
+		ClientID:    clientID,
+		Claims:      claims,
+		AccessToken: token,
+	}, 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
+// like credential failures.
+func (t *TraefikOidc) introspectOnBearerPath(token string) *bearerError {
+	resp, err := t.introspectToken(token)
+	if err != nil {
+		return newBearerError(bearerErrIntrospectionUnavailable, "introspection failed: "+err.Error())
+	}
+	if !resp.Active {
+		return newBearerError(bearerErrTokenInactive, "introspection reports token inactive")
+	}
+	return nil
+}

bearer_auth_test.go

@@ -0,0 +1,812 @@
+package traefikoidc
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"golang.org/x/time/rate"
+)
+
+// =============================================================================
+// Helper builders
+// =============================================================================
+
+// makeBearerJWT constructs a JWT with explicit header + claims for tests.
+// Signature is opaque (b64("signature")) — bearer tests don't exercise the
+// real cryptographic verifier; verification is bypassed via tokenCache pre-
+// seed so the bearer pipeline under test sees a "verified" token.
+func makeBearerJWT(t *testing.T, header, claims map[string]interface{}) string {
+	t.Helper()
+	hb, err := json.Marshal(header)
+	if err != nil {
+		t.Fatalf("marshal header: %v", err)
+	}
+	cb, err := json.Marshal(claims)
+	if err != nil {
+		t.Fatalf("marshal claims: %v", err)
+	}
+	return fmt.Sprintf("%s.%s.%s",
+		base64.RawURLEncoding.EncodeToString(hb),
+		base64.RawURLEncoding.EncodeToString(cb),
+		base64.RawURLEncoding.EncodeToString([]byte("signature")),
+	)
+}
+
+// defaultBearerHeader produces the standard RS256+kid header used in tests.
+func defaultBearerHeader() map[string]interface{} {
+	return map[string]interface{}{"alg": "RS256", "kid": "test-kid"}
+}
+
+// defaultBearerClaims produces a baseline access-token claim set. Tests
+// shallow-clone and override fields as needed.
+func defaultBearerClaims() map[string]interface{} {
+	return map[string]interface{}{
+		"iss":   "https://issuer.example.com",
+		"aud":   "https://api.example.com",
+		"sub":   "service-account-1",
+		"scope": "api:read api:write",
+		"exp":   float64(time.Now().Add(time.Hour).Unix()),
+		"iat":   float64(time.Now().Unix()),
+	}
+}
+
+// makeBearerOIDC constructs a TraefikOidc wired for bearer auth tests. The
+// real verifyTokenWithOpts pipeline is short-circuited via tokenCache pre-
+// seed: any token Set into t.tokenCache returns nil from VerifyToken,
+// letting tests exercise the post-verify bearer logic (classifier, identifier,
+// throttle, header forwarding) without standing up JWKs.
+func makeBearerOIDC(t *testing.T, next http.Handler) *TraefikOidc {
+	t.Helper()
+	sm := createTestSessionManager(t)
+	oidc := &TraefikOidc{
+		next:                      next,
+		logger:                    NewLogger("error"),
+		initComplete:              make(chan struct{}),
+		sessionManager:            sm,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
+		issuerURL:                 "https://issuer.example.com",
+		audience:                  "https://api.example.com",
+		clientID:                  "https://api.example.com",
+		tokenCache:                NewTokenCache(),
+		excludedURLs:              map[string]struct{}{"/favicon.ico": {}},
+		allowedRolesAndGroups:     map[string]struct{}{},
+		limiter:                   rate.NewLimiter(rate.Every(time.Second), 1000),
+		ctx:                       context.Background(),
+		enableBearerAuth:          true,
+		stripAuthorizationHeader:  true,
+		bearerEmitWWWAuthenticate: true,
+		bearerOverridesCookie:     false,
+		bearerIdentifierClaim:     "sub",
+		maxIdentifierLength:       256,
+		maxTokenAge:               24 * time.Hour,
+		bearerFailureThreshold:    20,
+		bearerFailureWindow:       60 * time.Second,
+		bearerFailurePenalty:      60 * time.Second,
+		bearerFailureTracker:      newBearerFailureTracker(20, 60*time.Second, 60*time.Second),
+	}
+	oidc.extractClaimsFunc = extractClaims
+	close(oidc.initComplete)
+	return oidc
+}
+
+// seedVerified pre-populates the tokenCache so verifyTokenWithOpts short-
+// circuits to nil for the given token. Mirrors the production fast-return
+// path at token_manager.go for previously-verified tokens.
+func seedVerified(t *testing.T, oidc *TraefikOidc, token string, claims map[string]interface{}) {
+	t.Helper()
+	if oidc.tokenCache == nil {
+		oidc.tokenCache = NewTokenCache()
+	}
+	oidc.tokenCache.Set(token, claims, time.Hour)
+}
+
+// =============================================================================
+// Unit tests — small helpers
+// =============================================================================
+
+func TestDetectBearerToken(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name   string
+		header string
+		want   string
+		ok     bool
+	}{
+		{"missing header", "", "", false},
+		{"basic auth", "Basic abc", "", false},
+		{"bearer with token", "Bearer abc.def.ghi", "abc.def.ghi", true},
+		{"lowercase bearer", "bearer abc.def.ghi", "abc.def.ghi", true},
+		{"mixed case", "BeArEr abc.def.ghi", "abc.def.ghi", true},
+		{"empty token after prefix", "Bearer    ", "", false},
+		{"bearer no space", "Bearerabc", "", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			req := httptest.NewRequest("GET", "/", nil)
+			if tc.header != "" {
+				req.Header.Set("Authorization", tc.header)
+			}
+			got, ok := detectBearerToken(req)
+			if ok != tc.ok || got != tc.want {
+				t.Fatalf("got=(%q, %v), want=(%q, %v)", got, ok, tc.want, tc.ok)
+			}
+		})
+	}
+}
+
+func TestParseBearerJOSEHeader(t *testing.T) {
+	t.Parallel()
+	mk := func(t *testing.T, h map[string]interface{}) string {
+		return makeBearerJWT(t, h, map[string]interface{}{"sub": "x"})
+	}
+	cases := []struct {
+		header  map[string]interface{}
+		name    string
+		wantErr bool
+	}{
+		{name: "valid RS256", header: map[string]interface{}{"alg": "RS256", "kid": "k1"}, wantErr: false},
+		{name: "valid ES512", header: map[string]interface{}{"alg": "ES512", "kid": "abc-_.="}, wantErr: false},
+		{name: "alg=none rejected", header: map[string]interface{}{"alg": "none", "kid": "k1"}, wantErr: true},
+		{name: "alg=HS256 rejected", header: map[string]interface{}{"alg": "HS256", "kid": "k1"}, wantErr: true},
+		{name: "missing kid", header: map[string]interface{}{"alg": "RS256"}, wantErr: true},
+		{name: "kid too long", header: map[string]interface{}{"alg": "RS256", "kid": strings.Repeat("a", bearerKidMaxLen+1)}, wantErr: true},
+		{name: "kid bad chars", header: map[string]interface{}{"alg": "RS256", "kid": "evil/../etc/passwd"}, wantErr: true},
+		{name: "kid with space", header: map[string]interface{}{"alg": "RS256", "kid": "key one"}, wantErr: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			token := mk(t, tc.header)
+			err := parseBearerJOSEHeader(token)
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("err=%v wantErr=%v", err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestSanitiseBearerIdentifier(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name    string
+		in      string
+		want    string
+		wantErr bool
+	}{
+		{"normal sub", "service-account-1", "service-account-1", false},
+		{"email-like", "alice@example.com", "alice@example.com", false},
+		{"trim whitespace", "  abc  ", "abc", false},
+		{"empty", "", "", true},
+		{"only whitespace", "   ", "", true},
+		{"control char (newline)", "alice\nbob", "", true},
+		{"control char (CR)", "alice\rbob", "", true},
+		{"control char (NUL)", "alice\x00bob", "", true},
+		{"bidi override", "alice\u202ebob", "", true},
+		{"bidi isolate", "alice\u2066bob", "", true},
+		{"comma delimiter", "alice,bob", "", true},
+		{"semicolon delimiter", "alice;bob", "", true},
+		{"equals delimiter", "alice=bob", "", true},
+		{"over length", strings.Repeat("a", 257), "", true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := sanitizeBearerIdentifier(tc.in, 256)
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("err=%v wantErr=%v", err, tc.wantErr)
+			}
+			if !tc.wantErr && got != tc.want {
+				t.Fatalf("got=%q want=%q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestResolveBearerIdentifier(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		claims  map[string]interface{}
+		name    string
+		claim   string
+		want    string
+		wantErr bool
+	}{
+		{name: "default sub", claims: map[string]interface{}{"sub": "abc"}, claim: "", want: "abc"},
+		{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},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := resolveBearerIdentifier(tc.claims, tc.claim)
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("err=%v wantErr=%v", err, tc.wantErr)
+			}
+			if !tc.wantErr && got != tc.want {
+				t.Fatalf("got=%q want=%q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestEnforceMultiAudienceAzp(t *testing.T) {
+	t.Parallel()
+	const cid = "https://api.example.com"
+	cases := []struct {
+		claims  map[string]interface{}
+		name    string
+		wantErr bool
+	}{
+		{name: "single string aud", claims: map[string]interface{}{"aud": "x"}, wantErr: false},
+		{name: "single element array", claims: map[string]interface{}{"aud": []interface{}{"x"}}, wantErr: false},
+		{name: "multi-aud with matching azp", claims: map[string]interface{}{"aud": []interface{}{"a", "b"}, "azp": cid}, wantErr: false},
+		{name: "multi-aud missing azp", claims: map[string]interface{}{"aud": []interface{}{"a", "b"}}, wantErr: true},
+		{name: "multi-aud empty azp", claims: map[string]interface{}{"aud": []interface{}{"a", "b"}, "azp": ""}, wantErr: true},
+		{name: "multi-aud wrong azp", claims: map[string]interface{}{"aud": []interface{}{"a", "b"}, "azp": "other"}, wantErr: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := enforceMultiAudienceAzp(tc.claims, cid)
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("err=%v wantErr=%v", err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestEnforceIatAge(t *testing.T) {
+	t.Parallel()
+	now := time.Now()
+	cases := []struct {
+		name    string
+		iat     float64
+		maxAge  time.Duration
+		wantErr bool
+	}{
+		{name: "fresh", iat: float64(now.Unix()), maxAge: time.Hour, wantErr: false},
+		{name: "23h59m old, max 24h", iat: float64(now.Add(-23*time.Hour - 59*time.Minute).Unix()), maxAge: 24 * time.Hour, wantErr: false},
+		{name: "25h old, max 24h", iat: float64(now.Add(-25 * time.Hour).Unix()), maxAge: 24 * time.Hour, wantErr: true},
+		{name: "1970 token", iat: float64(0), maxAge: 24 * time.Hour, wantErr: true},
+		{name: "maxAge disabled (0)", iat: float64(0), maxAge: 0, wantErr: false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := enforceIatAge(map[string]interface{}{"iat": tc.iat}, tc.maxAge)
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("err=%v wantErr=%v", err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestBearerFailureTracker(t *testing.T) {
+	t.Parallel()
+	tr := newBearerFailureTracker(3, 60*time.Second, 60*time.Second)
+	const ip = "10.0.0.1"
+	// Below threshold: not blocked.
+	for i := 0; i < 2; i++ {
+		tr.recordFailure(ip)
+		if b, _ := tr.blocked(ip); b {
+			t.Fatalf("blocked too early after %d failures", i+1)
+		}
+	}
+	// Threshold reached: blocked.
+	tr.recordFailure(ip)
+	if b, retry := tr.blocked(ip); !b || retry <= 0 {
+		t.Fatalf("expected blocked with positive retry, got=%v retry=%v", b, retry)
+	}
+	// Success clears the counter.
+	tr.recordSuccess(ip)
+	if b, _ := tr.blocked(ip); b {
+		t.Fatalf("expected unblocked after success")
+	}
+	// Other IPs are unaffected.
+	if b, _ := tr.blocked("10.0.0.2"); b {
+		t.Fatalf("unrelated IP should not be blocked")
+	}
+}
+
+// =============================================================================
+// Integration tests — full ServeHTTP via the bearer pipeline
+// =============================================================================
+
+func TestServeHTTP_Bearer_HappyPath(t *testing.T) {
+	t.Parallel()
+	var nextCalled atomic.Bool
+	var capturedHeaders http.Header
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		nextCalled.Store(true)
+		capturedHeaders = r.Header.Clone()
+		w.WriteHeader(http.StatusOK)
+	})
+	oidc := makeBearerOIDC(t, next)
+	claims := defaultBearerClaims()
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if !nextCalled.Load() {
+		t.Fatalf("expected next handler to run; got status=%d body=%q", rw.Code, rw.Body.String())
+	}
+	if rw.Code != http.StatusOK {
+		t.Fatalf("status=%d, want 200", rw.Code)
+	}
+	if got := capturedHeaders.Get("X-Forwarded-User"); got != "service-account-1" {
+		t.Fatalf("X-Forwarded-User=%q, want service-account-1", got)
+	}
+	if got := capturedHeaders.Get("Authorization"); got != "" {
+		t.Fatalf("Authorization should be stripped, got=%q", got)
+	}
+}
+
+func TestServeHTTP_Bearer_StripAuthDisabled(t *testing.T) {
+	t.Parallel()
+	var capturedAuth string
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		capturedAuth = r.Header.Get("Authorization")
+		w.WriteHeader(http.StatusOK)
+	})
+	oidc := makeBearerOIDC(t, next)
+	oidc.stripAuthorizationHeader = false
+	claims := defaultBearerClaims()
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if !strings.HasPrefix(capturedAuth, "Bearer ") {
+		t.Fatalf("expected Authorization to be forwarded, got=%q", capturedAuth)
+	}
+}
+
+func TestServeHTTP_Bearer_RejectIDToken(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run for ID token rejection")
+	})
+	oidc := makeBearerOIDC(t, next)
+	// ID-token shape: nonce claim present and no scope. detectTokenType
+	// returns true.
+	claims := map[string]interface{}{
+		"iss":   "https://issuer.example.com",
+		"aud":   "https://api.example.com",
+		"sub":   "user-1",
+		"nonce": "n-0S6_WzA2Mj",
+		"exp":   float64(time.Now().Add(time.Hour).Unix()),
+		"iat":   float64(time.Now().Unix()),
+	}
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if rw.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", rw.Code)
+	}
+	if wa := rw.Header().Get("WWW-Authenticate"); !strings.Contains(wa, `error="invalid_token"`) {
+		t.Fatalf("expected WWW-Authenticate invalid_token, got=%q", wa)
+	}
+}
+
+func TestServeHTTP_Bearer_AlgNoneRejected(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run for alg=none")
+	})
+	oidc := makeBearerOIDC(t, next)
+	header := map[string]interface{}{"alg": "none", "kid": "k1"}
+	claims := defaultBearerClaims()
+	token := makeBearerJWT(t, header, claims)
+	// Even if we pre-seeded the cache, the early alg pin runs FIRST.
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if rw.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", rw.Code)
+	}
+}
+
+func TestServeHTTP_Bearer_KidTooLongRejected(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run for oversized kid")
+	})
+	oidc := makeBearerOIDC(t, next)
+	header := map[string]interface{}{"alg": "RS256", "kid": strings.Repeat("a", bearerKidMaxLen+1)}
+	claims := defaultBearerClaims()
+	token := makeBearerJWT(t, header, claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if rw.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", rw.Code)
+	}
+}
+
+func TestServeHTTP_Bearer_MultiAudRequiresAzp(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run for multi-aud without azp")
+	})
+	oidc := makeBearerOIDC(t, next)
+	claims := defaultBearerClaims()
+	claims["aud"] = []interface{}{"https://api.example.com", "https://other.example.com"}
+	delete(claims, "azp")
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if rw.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", rw.Code)
+	}
+}
+
+func TestServeHTTP_Bearer_MultiAudWithAzpAccepted(t *testing.T) {
+	t.Parallel()
+	var nextCalled atomic.Bool
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		nextCalled.Store(true)
+		w.WriteHeader(http.StatusOK)
+	})
+	oidc := makeBearerOIDC(t, next)
+	claims := defaultBearerClaims()
+	claims["aud"] = []interface{}{"https://api.example.com", "https://other.example.com"}
+	claims["azp"] = oidc.clientID
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if rw.Code != http.StatusOK || !nextCalled.Load() {
+		t.Fatalf("expected 200 + next called; got status=%d called=%v", rw.Code, nextCalled.Load())
+	}
+}
+
+func TestServeHTTP_Bearer_IatTooOldRejected(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run for old iat")
+	})
+	oidc := makeBearerOIDC(t, next)
+	claims := defaultBearerClaims()
+	claims["iat"] = float64(time.Now().Add(-25 * time.Hour).Unix())
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if rw.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", rw.Code)
+	}
+}
+
+func TestServeHTTP_Bearer_IdentifierWithBidiRejected(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run for bidi identifier")
+	})
+	oidc := makeBearerOIDC(t, next)
+	claims := defaultBearerClaims()
+	claims["sub"] = "alice\u202ebob"
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if rw.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", rw.Code)
+	}
+}
+
+func TestServeHTTP_Bearer_ReplayRegression(t *testing.T) {
+	t.Parallel()
+	var successCount atomic.Int32
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		successCount.Add(1)
+		w.WriteHeader(http.StatusOK)
+	})
+	oidc := makeBearerOIDC(t, next)
+	claims := defaultBearerClaims()
+	claims["jti"] = "regression-jti"
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	for i := 0; i < 100; i++ {
+		req := httptest.NewRequest("GET", "/api/work", nil)
+		req.Header.Set("Authorization", "Bearer "+token)
+		rw := httptest.NewRecorder()
+		oidc.ServeHTTP(rw, req)
+		if rw.Code != http.StatusOK {
+			t.Fatalf("iteration %d: status=%d, want 200", i, rw.Code)
+		}
+	}
+	if successCount.Load() != 100 {
+		t.Fatalf("successCount=%d, want 100", successCount.Load())
+	}
+}
+
+func TestServeHTTP_Bearer_ThrottleTrips429(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run during throttle test")
+	})
+	oidc := makeBearerOIDC(t, next)
+	oidc.bearerFailureTracker = newBearerFailureTracker(3, 60*time.Second, 60*time.Second)
+
+	// Send malformed bearers from the same RemoteAddr until threshold trips.
+	send := func() *httptest.ResponseRecorder {
+		req := httptest.NewRequest("GET", "/api/work", nil)
+		req.RemoteAddr = "10.0.0.5:1234"
+		req.Header.Set("Authorization", "Bearer not-a-jwt")
+		rw := httptest.NewRecorder()
+		oidc.ServeHTTP(rw, req)
+		return rw
+	}
+	for i := 0; i < 3; i++ {
+		rw := send()
+		if rw.Code != http.StatusUnauthorized {
+			t.Fatalf("pre-throttle iteration %d: status=%d, want 401", i, rw.Code)
+		}
+	}
+	// 4th request: throttled.
+	rw := send()
+	if rw.Code != http.StatusTooManyRequests {
+		t.Fatalf("expected 429 after threshold, got %d", rw.Code)
+	}
+	if ra := rw.Header().Get("Retry-After"); ra == "" {
+		t.Fatalf("expected Retry-After header on 429")
+	}
+}
+
+func TestServeHTTP_Bearer_ExcludedURLStripsAuth(t *testing.T) {
+	t.Parallel()
+	var capturedAuth string
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		capturedAuth = r.Header.Get("Authorization")
+		w.WriteHeader(http.StatusOK)
+	})
+	oidc := makeBearerOIDC(t, next)
+	oidc.excludedURLs = map[string]struct{}{"/favicon.ico": {}}
+
+	req := httptest.NewRequest("GET", "/favicon.ico", nil)
+	req.Header.Set("Authorization", "Bearer abc.def.ghi")
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if rw.Code != http.StatusOK {
+		t.Fatalf("excluded path should pass; got %d", rw.Code)
+	}
+	if capturedAuth != "" {
+		t.Fatalf("Authorization must be stripped on excluded paths, got=%q", capturedAuth)
+	}
+}
+
+func TestServeHTTP_Bearer_RolesGate(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name       string
+		rolesClaim []interface{}
+		want       int
+	}{
+		{name: "matching role", rolesClaim: []interface{}{"admin"}, want: http.StatusOK},
+		{name: "no matching role", rolesClaim: []interface{}{"viewer"}, want: http.StatusForbidden},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusOK)
+			})
+			oidc := makeBearerOIDC(t, next)
+			oidc.allowedRolesAndGroups = map[string]struct{}{"admin": {}}
+			oidc.roleClaimName = "roles"
+			claims := defaultBearerClaims()
+			claims["roles"] = tc.rolesClaim
+			token := makeBearerJWT(t, defaultBearerHeader(), claims)
+			seedVerified(t, oidc, token, claims)
+
+			req := httptest.NewRequest("GET", "/api/work", nil)
+			req.Header.Set("Authorization", "Bearer "+token)
+			rw := httptest.NewRecorder()
+			oidc.ServeHTTP(rw, req)
+			if rw.Code != tc.want {
+				t.Fatalf("status=%d, want %d", rw.Code, tc.want)
+			}
+		})
+	}
+}
+
+func TestServeHTTP_Bearer_CookieWinsByDefault(t *testing.T) {
+	t.Parallel()
+	// Both cookie and bearer present: cookie path runs (which will redirect
+	// to /authorize since the cookie is empty/unauthenticated).
+	var nextCalled atomic.Bool
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		nextCalled.Store(true)
+		w.WriteHeader(http.StatusOK)
+	})
+	oidc := makeBearerOIDC(t, next)
+	claims := defaultBearerClaims()
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	prefix := oidc.sessionManager.GetCookiePrefix()
+	req.AddCookie(&http.Cookie{Name: prefix + "main", Value: "irrelevant"})
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	// Cookie path consumed the request; bearer was ignored. Since the
+	// cookie is empty, the cookie path will either 302 to /authorize or
+	// return 401 — in either case, next must NOT be called.
+	if nextCalled.Load() {
+		t.Fatalf("next must not be called when bearer is ignored due to cookie precedence")
+	}
+}
+
+func TestServeHTTP_Bearer_BearerOverridesCookie(t *testing.T) {
+	t.Parallel()
+	var nextCalled atomic.Bool
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		nextCalled.Store(true)
+		w.WriteHeader(http.StatusOK)
+	})
+	oidc := makeBearerOIDC(t, next)
+	oidc.bearerOverridesCookie = true
+	claims := defaultBearerClaims()
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	prefix := oidc.sessionManager.GetCookiePrefix()
+	req.AddCookie(&http.Cookie{Name: prefix + "main", Value: "irrelevant"})
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+
+	if !nextCalled.Load() || rw.Code != http.StatusOK {
+		t.Fatalf("expected bearer to win with override; status=%d called=%v", rw.Code, nextCalled.Load())
+	}
+}
+
+func TestServeHTTP_Bearer_OversizedToken(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run for oversized token")
+	})
+	oidc := makeBearerOIDC(t, next)
+	huge := strings.Repeat("a", AccessTokenConfig.MaxLength+1)
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+huge)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+	if rw.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", rw.Code)
+	}
+}
+
+func TestServeHTTP_Bearer_MalformedJWT(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("next must not run for malformed JWT")
+	})
+	oidc := makeBearerOIDC(t, next)
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer not.jwt") // 1 dot
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+	if rw.Code != http.StatusUnauthorized {
+		t.Fatalf("status=%d, want 401", rw.Code)
+	}
+}
+
+func TestServeHTTP_Bearer_FeatureOffPassesThrough(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Should not be reached: cookie path runs and (with no session)
+		// will redirect or 401. We assert no panic / next not called.
+		t.Fatalf("next must not run when bearer is off and no valid session exists")
+	})
+	oidc := makeBearerOIDC(t, next)
+	oidc.enableBearerAuth = false
+	claims := defaultBearerClaims()
+	token := makeBearerJWT(t, defaultBearerHeader(), claims)
+	seedVerified(t, oidc, token, claims)
+	req := httptest.NewRequest("GET", "/api/work", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rw := httptest.NewRecorder()
+	oidc.ServeHTTP(rw, req)
+	// Expect non-200: either 302 to /authorize or 401. The point is the
+	// bearer pipeline didn't run.
+	if rw.Code == http.StatusOK {
+		t.Fatalf("expected non-200 when bearer is off; got %d", rw.Code)
+	}
+}
+
+// =============================================================================
+// Startup validation tests
+// =============================================================================
+
+func TestStartupValidation_BearerRequiresAudience(t *testing.T) {
+	t.Parallel()
+	cfg := CreateConfig()
+	cfg.ProviderURL = "https://issuer.example.com"
+	cfg.ClientID = "id"
+	cfg.ClientSecret = "secret"
+	cfg.CallbackURL = "/oauth/callback"
+	cfg.SessionEncryptionKey = "0123456789abcdef0123456789abcdef0123456789abcdef"
+	cfg.EnableBearerAuth = true
+	cfg.Audience = ""
+	_, err := New(context.Background(), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}), cfg, "bearer-test")
+	if err == nil || !strings.Contains(err.Error(), "requires Audience") {
+		t.Fatalf("expected audience-required error, got %v", err)
+	}
+}
+
+func TestStartupValidation_BearerRejectsEmailIdentifier(t *testing.T) {
+	t.Parallel()
+	cfg := CreateConfig()
+	cfg.ProviderURL = "https://issuer.example.com"
+	cfg.ClientID = "id"
+	cfg.ClientSecret = "secret"
+	cfg.CallbackURL = "/oauth/callback"
+	cfg.SessionEncryptionKey = "0123456789abcdef0123456789abcdef0123456789abcdef"
+	cfg.EnableBearerAuth = true
+	cfg.Audience = "https://api.example.com"
+	cfg.BearerIdentifierClaim = "email"
+	_, err := New(context.Background(), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}), cfg, "bearer-test")
+	if err == nil || !strings.Contains(err.Error(), "bearerIdentifierClaim=\"email\"") {
+		t.Fatalf("expected email-identifier rejection, got %v", err)
+	}
+}
+
+// =============================================================================
+// Principal invariants
+// =============================================================================
+
+func TestBuildPrincipalFromSession_NoIdentifier(t *testing.T) {
+	t.Parallel()
+	oidc := &TraefikOidc{logger: NewLogger("error")}
+	if p := oidc.buildPrincipalFromSession(nil); p != nil {
+		t.Fatalf("nil session must produce nil principal")
+	}
+}

ca_cert_test.go

@@ -0,0 +1,137 @@
+package traefikoidc
+
+import (
+	"encoding/pem"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// testCertPEM returns a valid PEM-encoded certificate harvested from an
+// httptest.NewTLSServer. Using httptest keeps the test free of any
+// handwritten static cert that could expire.
+func testCertPEM(t *testing.T) string {
+	t.Helper()
+	srv := httptest.NewTLSServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+	t.Cleanup(srv.Close)
+
+	cert := srv.Certificate()
+	if cert == nil {
+		t.Fatal("httptest.NewTLSServer did not expose a certificate")
+	}
+	return string(pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: cert.Raw}))
+}
+
+func TestLoadCACertPool_Empty(t *testing.T) {
+	cfg := &Config{}
+	pool, err := cfg.loadCACertPool()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pool != nil {
+		t.Errorf("expected nil pool when no CA source configured, got %v", pool)
+	}
+}
+
+func TestLoadCACertPool_InlinePEM(t *testing.T) {
+	cfg := &Config{CACertPEM: testCertPEM(t)}
+	pool, err := cfg.loadCACertPool()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pool == nil {
+		t.Fatal("expected non-nil pool for valid CACertPEM")
+	}
+}
+
+func TestLoadCACertPool_InlinePEM_Garbage(t *testing.T) {
+	cfg := &Config{CACertPEM: "not a pem"}
+	pool, err := cfg.loadCACertPool()
+	if err == nil {
+		t.Fatal("expected error for garbage CACertPEM, got nil")
+	}
+	if pool != nil {
+		t.Errorf("expected nil pool on error, got %v", pool)
+	}
+	if !strings.Contains(err.Error(), "caCertPEM") {
+		t.Errorf("error should name the failing field, got: %v", err)
+	}
+}
+
+func TestLoadCACertPool_FilePath(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "ca.pem")
+	if err := os.WriteFile(path, []byte(testCertPEM(t)), 0o600); err != nil {
+		t.Fatalf("writing temp PEM: %v", err)
+	}
+
+	cfg := &Config{CACertPath: path}
+	pool, err := cfg.loadCACertPool()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pool == nil {
+		t.Fatal("expected non-nil pool for valid CACertPath")
+	}
+}
+
+func TestLoadCACertPool_FilePath_Missing(t *testing.T) {
+	cfg := &Config{CACertPath: "/does/not/exist/ca.pem"}
+	pool, err := cfg.loadCACertPool()
+	if err == nil {
+		t.Fatal("expected error for missing CACertPath, got nil")
+	}
+	if pool != nil {
+		t.Errorf("expected nil pool on error, got %v", pool)
+	}
+}
+
+func TestLoadCACertPool_Combined(t *testing.T) {
+	// Both inline and file sources populated — certificates from both should
+	// be accepted into the same pool.
+	dir := t.TempDir()
+	path := filepath.Join(dir, "ca.pem")
+	if err := os.WriteFile(path, []byte(testCertPEM(t)), 0o600); err != nil {
+		t.Fatalf("writing temp PEM: %v", err)
+	}
+
+	cfg := &Config{CACertPath: path, CACertPEM: testCertPEM(t)}
+	pool, err := cfg.loadCACertPool()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pool == nil {
+		t.Fatal("expected non-nil pool when both sources set")
+	}
+}
+
+func TestSharedTransportPool_ConfigKeyDistinguishesCAAndSkipVerify(t *testing.T) {
+	p := GetGlobalTransportPool()
+	cfgSystem := DefaultHTTPClientConfig()
+
+	cfgSkip := DefaultHTTPClientConfig()
+	cfgSkip.InsecureSkipVerify = true
+
+	cfgCustomCA := DefaultHTTPClientConfig()
+	pool, err := (&Config{CACertPEM: testCertPEM(t)}).loadCACertPool()
+	if err != nil {
+		t.Fatalf("loadCACertPool: %v", err)
+	}
+	cfgCustomCA.RootCAs = pool
+
+	keys := map[string]string{
+		"system":   p.configKey(cfgSystem),
+		"skip":     p.configKey(cfgSkip),
+		"customCA": p.configKey(cfgCustomCA),
+	}
+	seen := make(map[string]string, len(keys))
+	for name, key := range keys {
+		if dup, ok := seen[key]; ok {
+			t.Errorf("configKey collision: %s and %s share key %q", name, dup, key)
+		}
+		seen[key] = name
+	}
+}

cache_compat.go

@@ -155,9 +155,9 @@ type CacheStrategy interface {
 
 // CacheEntry for backward compatibility
 type CacheEntry struct {
-	Key       string
-	Value     interface{}
 	ExpiresAt time.Time
+	Value     interface{}
+	Key       string
 }
 
 // Cache is an alias for backward compatibility
@@ -175,10 +175,10 @@ func NewOptimizedCacheWithConfig(config OptimizedCacheConfig) *CacheInterfaceWra
 
 // ListNode for backward compatibility
 type ListNode struct {
-	Key   string
 	Value interface{}
 	Next  *ListNode
 	Prev  *ListNode
+	Key   string
 }
 
 // NewFixedMetadataCache creates a metadata cache with fixed configuration

cache_manager.go

@@ -20,8 +20,9 @@ var (
 	cacheManagerInitOnce       sync.Once
 )
 
-// GetGlobalCacheManager returns a singleton CacheManager instance
-// Deprecated: Use GetGlobalCacheManagerWithConfig instead
+// GetGlobalCacheManager returns a singleton CacheManager instance.
+//
+// Deprecated: Use GetGlobalCacheManagerWithConfig instead.
 func GetGlobalCacheManager(wg *sync.WaitGroup) *CacheManager {
 	return GetGlobalCacheManagerWithConfig(wg, nil)
 }
@@ -61,7 +62,7 @@ func GetGlobalCacheManagerWithConfig(wg *sync.WaitGroup, config *Config) *CacheM
 func (cm *CacheManager) GetSharedTokenBlacklist() CacheInterface {
 	cm.mu.RLock()
 	defer cm.mu.RUnlock()
-	return &CacheInterfaceWrapper{cache: cm.manager.GetBlacklistCache()}
+	return &CacheInterfaceWrapper{cache: cm.manager.GetBlacklistCache(), managed: true}
 }
 
 // GetSharedTokenCache returns the shared token cache
@@ -93,7 +94,7 @@ func (cm *CacheManager) GetSharedJWKCache() JWKCacheInterface {
 func (cm *CacheManager) GetSharedIntrospectionCache() CacheInterface {
 	cm.mu.RLock()
 	defer cm.mu.RUnlock()
-	return &CacheInterfaceWrapper{cache: cm.manager.GetIntrospectionCache()}
+	return &CacheInterfaceWrapper{cache: cm.manager.GetIntrospectionCache(), managed: true}
 }
 
 // GetSharedTokenTypeCache returns the shared token type cache
@@ -101,7 +102,23 @@ func (cm *CacheManager) GetSharedIntrospectionCache() CacheInterface {
 func (cm *CacheManager) GetSharedTokenTypeCache() CacheInterface {
 	cm.mu.RLock()
 	defer cm.mu.RUnlock()
-	return &CacheInterfaceWrapper{cache: cm.manager.GetTokenTypeCache()}
+	return &CacheInterfaceWrapper{cache: cm.manager.GetTokenTypeCache(), managed: true}
+}
+
+// GetSharedSessionInvalidationCache returns the shared session invalidation cache
+// for backchannel and front-channel logout (IdP-initiated logout)
+func (cm *CacheManager) GetSharedSessionInvalidationCache() CacheInterface {
+	cm.mu.RLock()
+	defer cm.mu.RUnlock()
+	return &CacheInterfaceWrapper{cache: cm.manager.GetSessionInvalidationCache(), managed: true}
+}
+
+// GetSharedRefreshResultCache returns the short-lived refresh-result cache used
+// by the refresh path to coalesce grants across Traefik replicas via Redis.
+func (cm *CacheManager) GetSharedRefreshResultCache() CacheInterface {
+	cm.mu.RLock()
+	defer cm.mu.RUnlock()
+	return &CacheInterfaceWrapper{cache: cm.manager.GetRefreshResultCache(), managed: true}
 }
 
 // Close gracefully shuts down all cache components
@@ -121,7 +138,8 @@ func CleanupGlobalCacheManager() error {
 
 // CacheInterfaceWrapper wraps UniversalCache to implement CacheInterface
 type CacheInterfaceWrapper struct {
-	cache *UniversalCache
+	cache   *UniversalCache
+	managed bool // If true, cache is managed globally and Close() is a no-op
 }
 
 // Set stores a value
@@ -149,9 +167,15 @@ func (c *CacheInterfaceWrapper) Cleanup() {
 	c.cache.Cleanup()
 }
 
-// Close shuts down the cache
+// Close shuts down the cache if it's not managed globally.
+// For managed caches (from UniversalCacheManager), this is a no-op to prevent log flooding
+// when multiple plugin instances are closed during Traefik configuration reloads.
 func (c *CacheInterfaceWrapper) Close() {
-	// Close the underlying cache to stop goroutines
+	if c.managed {
+		// Cache is managed globally by UniversalCacheManager, so we don't close it here.
+		return
+	}
+	// Standalone cache - close it properly to stop cleanup goroutines
 	if c.cache != nil {
 		_ = c.cache.Close() // Safe to ignore: closing cache is best-effort during shutdown
 	}

cache_test.go

@@ -19,16 +19,16 @@ import (
 
 // CacheTestCase represents a comprehensive test case for cache operations
 type CacheTestCase struct {
+	setup      func(*TestFramework)
+	execute    func(*TestFramework) error
+	validate   func(*testing.T, error, *TestFramework)
+	cleanup    func(*TestFramework)
 	name       string
-	cacheType  string                                  // "universal", "metadata", "bounded"
-	operation  string                                  // "get", "set", "evict", "cleanup"
-	setup      func(*TestFramework)                    // Pre-test setup
-	execute    func(*TestFramework) error              // Test execution
-	validate   func(*testing.T, error, *TestFramework) // Validation logic
-	cleanup    func(*TestFramework)                    // Post-test cleanup
-	timeout    time.Duration                           // Test timeout
-	parallel   bool                                    // Can run in parallel
-	skipReason string                                  // Optional reason to skip
+	cacheType  string
+	operation  string
+	skipReason string
+	timeout    time.Duration
+	parallel   bool
 }
 
 // createTestCacheConfig creates a standard test configuration
@@ -219,6 +219,159 @@ func TestCacheInterfaceWrapper_Close(t *testing.T) {
 	nilWrapper.Close()
 }
 
+// TestCacheInterfaceWrapper_ManagedClose_Regression tests that managed cache wrappers
+// don't close the underlying cache when Close() is called. This is a regression test
+// for issue #105 where multiple plugin instances closing shared caches caused log flooding.
+func TestCacheInterfaceWrapper_ManagedClose_Regression(t *testing.T) {
+	cm := getTestCacheManager(t)
+
+	// Get a managed cache wrapper
+	cache := cm.GetSharedTokenBlacklist()
+	wrapper, ok := cache.(*CacheInterfaceWrapper)
+	if !ok {
+		t.Fatal("Expected CacheInterfaceWrapper")
+	}
+
+	// Verify it's marked as managed
+	if !wrapper.managed {
+		t.Error("Expected shared cache wrapper to be marked as managed")
+	}
+
+	// Set some data before Close
+	cache.Set("test-key", "test-value", time.Hour)
+
+	// Close the wrapper (should be a no-op for managed caches)
+	wrapper.Close()
+
+	// Verify the cache is still operational after Close
+	value, found := cache.Get("test-key")
+	if !found {
+		t.Error("Expected cache to still work after Close() on managed wrapper")
+	}
+	if value != "test-value" {
+		t.Errorf("Expected 'test-value', got %v", value)
+	}
+
+	// Can still set new values
+	cache.Set("new-key", "new-value", time.Hour)
+	newValue, found := cache.Get("new-key")
+	if !found || newValue != "new-value" {
+		t.Error("Expected to be able to set new values after Close() on managed wrapper")
+	}
+}
+
+// TestCacheInterfaceWrapper_StandaloneClose tests that standalone cache wrappers
+// properly close the underlying cache when Close() is called.
+func TestCacheInterfaceWrapper_StandaloneClose(t *testing.T) {
+	// Create a standalone cache (not from the global cache manager)
+	standaloneCache := NewCache()
+
+	wrapper, ok := standaloneCache.(*CacheInterfaceWrapper)
+	if !ok {
+		t.Fatal("Expected CacheInterfaceWrapper")
+	}
+
+	// Verify it's NOT marked as managed
+	if wrapper.managed {
+		t.Error("Expected standalone cache wrapper to NOT be marked as managed")
+	}
+
+	// Set some data
+	standaloneCache.Set("test-key", "test-value", time.Hour)
+
+	// Get baseline goroutine count
+	baselineGoroutines := runtime.NumGoroutine()
+
+	// Close the wrapper (should actually close the underlying cache)
+	wrapper.Close()
+
+	// Give cleanup goroutine time to stop
+	time.Sleep(100 * time.Millisecond)
+
+	// Goroutine count should decrease (cleanup routine stopped)
+	finalGoroutines := runtime.NumGoroutine()
+	if finalGoroutines > baselineGoroutines {
+		// This is acceptable - other tests might have started goroutines
+		t.Logf("Goroutine count: baseline=%d, final=%d", baselineGoroutines, finalGoroutines)
+	}
+}
+
+// TestCacheInterfaceWrapper_MultipleInstancesClose_Regression tests that multiple
+// plugin instances can close their cache wrappers without affecting shared caches.
+// This is a regression test for issue #105.
+func TestCacheInterfaceWrapper_MultipleInstancesClose_Regression(t *testing.T) {
+	cm := getTestCacheManager(t)
+
+	// Simulate multiple plugin instances getting cache references
+	instances := make([]*CacheInterfaceWrapper, 5)
+	for i := 0; i < 5; i++ {
+		cache := cm.GetSharedTokenBlacklist()
+		wrapper, ok := cache.(*CacheInterfaceWrapper)
+		if !ok {
+			t.Fatal("Expected CacheInterfaceWrapper")
+		}
+		instances[i] = wrapper
+
+		// Each instance might set some data
+		cache.Set(fmt.Sprintf("instance-%d-key", i), fmt.Sprintf("value-%d", i), time.Hour)
+	}
+
+	// Close all instances (simulating plugin shutdown/reload)
+	for _, wrapper := range instances {
+		wrapper.Close()
+	}
+
+	// The shared cache should still work after all instances closed their wrappers
+	newCache := cm.GetSharedTokenBlacklist()
+
+	// Data set by earlier instances should still be accessible
+	for i := 0; i < 5; i++ {
+		key := fmt.Sprintf("instance-%d-key", i)
+		value, found := newCache.Get(key)
+		if !found {
+			t.Errorf("Expected data from instance %d to still be accessible", i)
+		}
+		expectedValue := fmt.Sprintf("value-%d", i)
+		if value != expectedValue {
+			t.Errorf("Expected '%s', got '%v'", expectedValue, value)
+		}
+	}
+
+	// Should be able to add new data
+	newCache.Set("after-close-key", "after-close-value", time.Hour)
+	value, found := newCache.Get("after-close-key")
+	if !found || value != "after-close-value" {
+		t.Error("Expected to be able to use cache after all wrapper Close() calls")
+	}
+}
+
+// TestAllSharedCachesMarkedAsManaged verifies all shared cache getters
+// return managed wrappers to prevent the log flooding issue.
+func TestAllSharedCachesMarkedAsManaged(t *testing.T) {
+	cm := getTestCacheManager(t)
+
+	tests := []struct {
+		name  string
+		cache CacheInterface
+	}{
+		{"TokenBlacklist", cm.GetSharedTokenBlacklist()},
+		{"IntrospectionCache", cm.GetSharedIntrospectionCache()},
+		{"TokenTypeCache", cm.GetSharedTokenTypeCache()},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			wrapper, ok := tt.cache.(*CacheInterfaceWrapper)
+			if !ok {
+				t.Fatalf("Expected CacheInterfaceWrapper for %s", tt.name)
+			}
+			if !wrapper.managed {
+				t.Errorf("%s cache wrapper should be marked as managed", tt.name)
+			}
+		})
+	}
+}
+
 func TestCacheInterfaceWrapper_GetStats(t *testing.T) {
 	cm := getTestCacheManager(t)
 	cache := cm.GetSharedTokenBlacklist()
@@ -698,10 +851,10 @@ func TestUnifiedCache_SetMaxSize(t *testing.T) {
 
 func TestNewCacheAdapter(t *testing.T) {
 	tests := []struct {
-		name        string
 		cache       interface{}
-		expectNil   bool
+		name        string
 		description string
+		expectNil   bool
 	}{
 		{
 			name:        "UniversalCache",

client_assertion.go

@@ -0,0 +1,295 @@
+package traefikoidc
+
+import (
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"crypto/sha512"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"encoding/pem"
+	"fmt"
+	"io"
+	"math/big"
+	"os"
+	"time"
+)
+
+// isSupportedClientAssertionAlg reports whether alg is a recognized JWS
+// algorithm for private_key_jwt (RFC 7523 §2.2).
+func isSupportedClientAssertionAlg(alg string) bool {
+	switch alg {
+	case "RS256", "RS384", "RS512",
+		"PS256", "PS384", "PS512",
+		"ES256", "ES384", "ES512":
+		return true
+	}
+	return false
+}
+
+// ClientAssertionSigner builds and signs client_assertion JWTs (RFC 7523 §2.2).
+type ClientAssertionSigner struct {
+	key crypto.PrivateKey
+	alg string
+	kid string
+	// rand is the entropy source for jti generation and PSS/ECDSA signing.
+	// Defaults to crypto/rand.Reader when nil.
+	rand io.Reader
+	// now returns the current time. Defaults to time.Now when nil.
+	now func() time.Time
+}
+
+// NewClientAssertionSigner parses pemBytes as a private key, validates that
+// alg is consistent with the key type, and returns a ready-to-use signer.
+// kid is placed verbatim in the JWS header.
+//
+// PEM block types understood:
+//   - "PRIVATE KEY"     → PKCS#8 (tried first for all types)
+//   - "RSA PRIVATE KEY" → PKCS#1
+//   - "EC PRIVATE KEY"  → SEC1
+func NewClientAssertionSigner(pemBytes []byte, alg, kid string) (*ClientAssertionSigner, error) {
+	if !isSupportedClientAssertionAlg(alg) {
+		return nil, fmt.Errorf("unsupported client assertion alg %q", alg)
+	}
+	if kid == "" {
+		return nil, fmt.Errorf("kid must not be empty")
+	}
+
+	block, _ := pem.Decode(pemBytes)
+	if block == nil {
+		return nil, fmt.Errorf("no PEM block found in private key material")
+	}
+
+	var key crypto.PrivateKey
+	var parseErr error
+
+	switch block.Type {
+	case "PRIVATE KEY":
+		key, parseErr = x509.ParsePKCS8PrivateKey(block.Bytes)
+	case "RSA PRIVATE KEY":
+		key, parseErr = x509.ParsePKCS1PrivateKey(block.Bytes)
+	case "EC PRIVATE KEY":
+		key, parseErr = x509.ParseECPrivateKey(block.Bytes)
+	default:
+		// Best-effort fallback for unknown block types.
+		key, parseErr = x509.ParsePKCS8PrivateKey(block.Bytes)
+	}
+	if parseErr != nil {
+		return nil, fmt.Errorf("failed to parse private key (block type %q): %w", block.Type, parseErr)
+	}
+
+	if err := validateAlgKeyMatch(alg, key); err != nil {
+		return nil, err
+	}
+
+	return &ClientAssertionSigner{key: key, alg: alg, kid: kid}, nil
+}
+
+// validateAlgKeyMatch returns an error when alg implies a key type that does
+// not match the actual key.
+func validateAlgKeyMatch(alg string, key crypto.PrivateKey) error {
+	switch alg[0] {
+	case 'R', 'P': // RS* or PS*
+		if _, ok := key.(*rsa.PrivateKey); !ok {
+			return fmt.Errorf("alg %q requires an RSA key, got %T", alg, key)
+		}
+	case 'E': // ES*
+		if _, ok := key.(*ecdsa.PrivateKey); !ok {
+			return fmt.Errorf("alg %q requires an EC key, got %T", alg, key)
+		}
+	}
+	return nil
+}
+
+// Sign constructs and returns a signed client_assertion JWT.
+// audience is typically the token endpoint URL (RFC 7523 §3).
+// clientID is used as both iss and sub per RFC 7523 §2.2.
+func (s *ClientAssertionSigner) Sign(audience, clientID string) (string, error) {
+	rander := s.rand
+	if rander == nil {
+		rander = rand.Reader
+	}
+	nowFn := s.now
+	if nowFn == nil {
+		nowFn = time.Now
+	}
+
+	now := nowFn()
+
+	// 16 random bytes as lowercase hex for jti uniqueness.
+	jtiBytes := make([]byte, 16)
+	if _, err := io.ReadFull(rander, jtiBytes); err != nil {
+		return "", fmt.Errorf("failed to generate jti: %w", err)
+	}
+	jti := hex.EncodeToString(jtiBytes)
+
+	header := map[string]string{
+		"alg": s.alg,
+		"typ": "JWT",
+		"kid": s.kid,
+	}
+	hdrJSON, err := json.Marshal(header)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal JWT header: %w", err)
+	}
+
+	claims := map[string]any{
+		"iss": clientID,
+		"sub": clientID,
+		"aud": audience,
+		"jti": jti,
+		"iat": now.Unix(),
+		"exp": now.Add(60 * time.Second).Unix(),
+	}
+	claimsJSON, err := json.Marshal(claims)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal JWT claims: %w", err)
+	}
+
+	hdrB64 := base64.RawURLEncoding.EncodeToString(hdrJSON)
+	claimsB64 := base64.RawURLEncoding.EncodeToString(claimsJSON)
+	signingInput := hdrB64 + "." + claimsB64
+
+	sig, err := s.sign(rander, []byte(signingInput))
+	if err != nil {
+		return "", err
+	}
+
+	return signingInput + "." + base64.RawURLEncoding.EncodeToString(sig), nil
+}
+
+// sign computes raw signature bytes for signingInput per s.alg.
+// validateAlgKeyMatch in NewClientAssertionSigner guarantees the key type
+// matches s.alg, but the comma-ok asserts here keep errcheck happy and
+// surface internal misuse loudly instead of via panic.
+func (s *ClientAssertionSigner) sign(rander io.Reader, input []byte) ([]byte, error) {
+	switch s.alg {
+	case "RS256", "RS384", "RS512", "PS256", "PS384", "PS512":
+		rsaKey, ok := s.key.(*rsa.PrivateKey)
+		if !ok {
+			return nil, fmt.Errorf("internal: alg %q requires *rsa.PrivateKey, got %T", s.alg, s.key)
+		}
+		hash := rsaHashForAlg(s.alg)
+		digest := hashSum(hash, input)
+		if s.alg[0] == 'R' {
+			return signRSAPKCS1v15(rander, rsaKey, hash, digest)
+		}
+		return signRSAPSS(rander, rsaKey, hash, digest)
+	case "ES256", "ES384", "ES512":
+		ecKey, ok := s.key.(*ecdsa.PrivateKey)
+		if !ok {
+			return nil, fmt.Errorf("internal: alg %q requires *ecdsa.PrivateKey, got %T", s.alg, s.key)
+		}
+		hash := ecHashForAlg(s.alg)
+		digest := hashSum(hash, input)
+		return signECDSA(rander, ecKey, digest)
+	}
+	return nil, fmt.Errorf("unhandled alg %q", s.alg)
+}
+
+func rsaHashForAlg(alg string) crypto.Hash {
+	switch alg {
+	case "RS256", "PS256":
+		return crypto.SHA256
+	case "RS384", "PS384":
+		return crypto.SHA384
+	case "RS512", "PS512":
+		return crypto.SHA512
+	}
+	return 0
+}
+
+func ecHashForAlg(alg string) crypto.Hash {
+	switch alg {
+	case "ES256":
+		return crypto.SHA256
+	case "ES384":
+		return crypto.SHA384
+	case "ES512":
+		return crypto.SHA512
+	}
+	return 0
+}
+
+func hashSum(h crypto.Hash, input []byte) []byte {
+	switch h {
+	case crypto.SHA256:
+		sum := sha256.Sum256(input)
+		return sum[:]
+	case crypto.SHA384:
+		sum := sha512.Sum384(input)
+		return sum[:]
+	case crypto.SHA512:
+		sum := sha512.Sum512(input)
+		return sum[:]
+	}
+	return nil
+}
+
+func signRSAPKCS1v15(rander io.Reader, key *rsa.PrivateKey, hash crypto.Hash, digest []byte) ([]byte, error) {
+	sig, err := rsa.SignPKCS1v15(rander, key, hash, digest)
+	if err != nil {
+		return nil, fmt.Errorf("RSA PKCS1v15 signing failed: %w", err)
+	}
+	return sig, nil
+}
+
+func signRSAPSS(rander io.Reader, key *rsa.PrivateKey, hash crypto.Hash, digest []byte) ([]byte, error) {
+	opts := &rsa.PSSOptions{SaltLength: rsa.PSSSaltLengthEqualsHash, Hash: hash}
+	sig, err := rsa.SignPSS(rander, key, hash, digest, opts)
+	if err != nil {
+		return nil, fmt.Errorf("RSA PSS signing failed: %w", err)
+	}
+	return sig, nil
+}
+
+// signECDSA produces the JWS raw r||s signature (RFC 7515 App. A.3).
+// Each scalar is zero-padded to (curve.BitSize+7)/8 bytes.
+func signECDSA(rander io.Reader, key *ecdsa.PrivateKey, digest []byte) ([]byte, error) {
+	r, ss, err := ecdsa.Sign(rander, key, digest)
+	if err != nil {
+		return nil, fmt.Errorf("ECDSA signing failed: %w", err)
+	}
+	byteLen := (key.Curve.Params().BitSize + 7) / 8
+	sig := make([]byte, 2*byteLen)
+	padBigInt(sig[0:byteLen], r)
+	padBigInt(sig[byteLen:], ss)
+	return sig, nil
+}
+
+// padBigInt writes n as a fixed-width big-endian integer into buf.
+func padBigInt(buf []byte, n *big.Int) {
+	b := n.Bytes()
+	copy(buf[len(buf)-len(b):], b)
+}
+
+// buildClientAssertionSignerFromConfig loads key material and constructs a
+// ClientAssertionSigner. Called from NewWithContext when
+// ClientAuthMethod == "private_key_jwt".
+func buildClientAssertionSignerFromConfig(config *Config) (*ClientAssertionSigner, error) {
+	var pemBytes []byte
+
+	if config.ClientAssertionPrivateKey != "" {
+		pemBytes = []byte(config.ClientAssertionPrivateKey)
+	} else {
+		data, err := os.ReadFile(config.ClientAssertionKeyPath)
+		if err != nil {
+			return nil, fmt.Errorf("read clientAssertionKeyPath %q: %w", config.ClientAssertionKeyPath, err)
+		}
+		pemBytes = data
+	}
+
+	alg := config.ClientAssertionAlg
+	if alg == "" {
+		alg = "RS256"
+	}
+
+	return NewClientAssertionSigner(pemBytes, alg, config.ClientAssertionKeyID)
+}
+
+
+

config_marshalling.go

@@ -7,7 +7,7 @@ import (
 // REDACTED is the placeholder value for sensitive information
 const REDACTED = "[REDACTED]"
 
-// MarshalJSON implements custom JSON marshalling to redact sensitive fields
+// 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
@@ -47,7 +47,7 @@ func (c Config) MarshalJSON() ([]byte, error) {
 	return json.Marshal(result)
 }
 
-// MarshalYAML implements custom YAML marshalling to redact sensitive fields
+// 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

csrf_session_test.go

@@ -31,7 +31,7 @@ func TestCSRFTokenSessionManagement(t *testing.T) {
 		session.SetCSRF(csrfToken)
 		session.SetNonce("test-nonce")
 		session.SetAuthenticated(true)
-		session.SetEmail("user@example.com")
+		session.SetUserIdentifier("user@example.com")
 		session.SetAccessToken("old-access-token")
 		session.SetRefreshToken("old-refresh-token")
 		session.SetIDToken("old-id-token")
@@ -61,7 +61,7 @@ func TestCSRFTokenSessionManagement(t *testing.T) {
 
 		// Now perform selective clearing (as done in the fix)
 		session2.SetAuthenticated(false)
-		session2.SetEmail("")
+		session2.SetUserIdentifier("")
 		session2.SetAccessToken("")
 		session2.SetRefreshToken("")
 		session2.SetIDToken("")
@@ -303,7 +303,7 @@ func TestRegressionLoginLoop(t *testing.T) {
 
 		// Set initial session data
 		session.SetAuthenticated(true)
-		session.SetEmail("old@example.com")
+		session.SetUserIdentifier("old@example.com")
 		session.SetAccessToken("old-token")
 		session.SetCSRF("existing-csrf")
 
@@ -325,7 +325,7 @@ func TestRegressionLoginLoop(t *testing.T) {
 		// OLD BEHAVIOR: session.Clear() would have been called here, losing CSRF
 		// NEW BEHAVIOR: Selective clearing
 		session2.SetAuthenticated(false)
-		session2.SetEmail("")
+		session2.SetUserIdentifier("")
 		session2.SetAccessToken("")
 		session2.SetRefreshToken("")
 		session2.SetIDToken("")

dcr_storage_compat.go

@@ -0,0 +1,290 @@
+// Package traefikoidc provides OIDC authentication middleware for Traefik
+package traefikoidc
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/lukaszraczylo/traefikoidc/internal/dcrstorage"
+)
+
+// DCRStorageBackend represents the type of storage backend for DCR credentials.
+// Alias for internal package type for backward compatibility.
+type DCRStorageBackend = dcrstorage.StorageBackend
+
+const (
+	// DCRStorageBackendFile uses file-based storage (default for backward compatibility)
+	DCRStorageBackendFile DCRStorageBackend = dcrstorage.StorageBackendFile
+
+	// DCRStorageBackendRedis uses Redis for distributed storage
+	DCRStorageBackendRedis DCRStorageBackend = dcrstorage.StorageBackendRedis
+
+	// DCRStorageBackendAuto automatically selects Redis if available, otherwise file
+	DCRStorageBackendAuto DCRStorageBackend = dcrstorage.StorageBackendAuto
+)
+
+// DCRCredentialsStore defines the interface for storing DCR credentials.
+// This abstraction allows different storage backends (file, Redis) to be used
+// for persisting OIDC Dynamic Client Registration credentials across nodes.
+type DCRCredentialsStore interface {
+	// Save stores the client registration response for a provider
+	// The providerURL is used as a key to support multi-tenant scenarios
+	Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error
+
+	// Load retrieves stored credentials for a provider
+	// Returns nil, nil if no credentials exist (not an error)
+	Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error)
+
+	// Delete removes stored credentials for a provider
+	Delete(ctx context.Context, providerURL string) error
+
+	// Exists checks if credentials exist for a provider
+	Exists(ctx context.Context, providerURL string) (bool, error)
+}
+
+// loggerAdapter adapts our Logger to the dcrstorage.Logger interface
+type loggerAdapter struct {
+	logger *Logger
+}
+
+func (l *loggerAdapter) Debug(msg string)                  { l.logger.Debug("%s", msg) }
+func (l *loggerAdapter) Debugf(format string, args ...any) { l.logger.Debugf(format, args...) }
+func (l *loggerAdapter) Info(msg string)                   { l.logger.Info("%s", msg) }
+func (l *loggerAdapter) Infof(format string, args ...any)  { l.logger.Infof(format, args...) }
+func (l *loggerAdapter) Error(msg string)                  { l.logger.Error("%s", msg) }
+func (l *loggerAdapter) Errorf(format string, args ...any) { l.logger.Errorf(format, args...) }
+
+// cacheAdapter adapts UniversalCache to dcrstorage.Cache interface
+type cacheAdapter struct {
+	cache *UniversalCache
+}
+
+func (c *cacheAdapter) Get(key string) (any, bool) {
+	return c.cache.Get(key)
+}
+
+func (c *cacheAdapter) Set(key string, value any, ttl time.Duration) error {
+	return c.cache.Set(key, value, ttl)
+}
+
+func (c *cacheAdapter) Delete(key string) {
+	c.cache.Delete(key)
+}
+
+// fileStoreWrapper wraps dcrstorage.FileStore to implement DCRCredentialsStore
+type fileStoreWrapper struct {
+	inner *dcrstorage.FileStore
+}
+
+func (w *fileStoreWrapper) Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error {
+	innerCreds := convertCredsToInternal(creds)
+	return w.inner.Save(ctx, providerURL, innerCreds)
+}
+
+func (w *fileStoreWrapper) Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error) {
+	innerCreds, err := w.inner.Load(ctx, providerURL)
+	if err != nil || innerCreds == nil {
+		return nil, err
+	}
+	return convertCredsFromInternal(innerCreds), nil
+}
+
+func (w *fileStoreWrapper) Delete(ctx context.Context, providerURL string) error {
+	return w.inner.Delete(ctx, providerURL)
+}
+
+func (w *fileStoreWrapper) Exists(ctx context.Context, providerURL string) (bool, error) {
+	return w.inner.Exists(ctx, providerURL)
+}
+
+// basePath returns the base path used for storing credentials (for backward compatibility in tests)
+func (w *fileStoreWrapper) basePath() string {
+	return w.inner.BasePath()
+}
+
+// getFilePath returns the file path for storing credentials for a specific provider (for backward compatibility in tests)
+func (w *fileStoreWrapper) getFilePath(providerURL string) string {
+	return w.inner.GetFilePath(providerURL)
+}
+
+// redisStoreWrapper wraps dcrstorage.RedisStore to implement DCRCredentialsStore
+type redisStoreWrapper struct {
+	inner *dcrstorage.RedisStore
+}
+
+func (w *redisStoreWrapper) Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error {
+	innerCreds := convertCredsToInternal(creds)
+	return w.inner.Save(ctx, providerURL, innerCreds)
+}
+
+func (w *redisStoreWrapper) Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error) {
+	innerCreds, err := w.inner.Load(ctx, providerURL)
+	if err != nil || innerCreds == nil {
+		return nil, err
+	}
+	return convertCredsFromInternal(innerCreds), nil
+}
+
+func (w *redisStoreWrapper) Delete(ctx context.Context, providerURL string) error {
+	return w.inner.Delete(ctx, providerURL)
+}
+
+func (w *redisStoreWrapper) Exists(ctx context.Context, providerURL string) (bool, error) {
+	return w.inner.Exists(ctx, providerURL)
+}
+
+// FileCredentialsStore implements DCRCredentialsStore using file-based storage.
+// This is the default storage backend for backward compatibility with existing deployments.
+type FileCredentialsStore = fileStoreWrapper
+
+// RedisCredentialsStore implements DCRCredentialsStore using Redis-backed cache.
+// This storage backend enables sharing DCR credentials across multiple Traefik instances.
+type RedisCredentialsStore = redisStoreWrapper
+
+// NewFileCredentialsStore creates a new file-based credentials store.
+// If basePath is empty, defaults to /tmp/oidc-client-credentials.json
+func NewFileCredentialsStore(basePath string, logger *Logger) *FileCredentialsStore {
+	var dcrLogger dcrstorage.Logger
+	if logger != nil {
+		dcrLogger = &loggerAdapter{logger: logger}
+	}
+	inner := dcrstorage.NewFileStore(basePath, dcrLogger)
+	return &fileStoreWrapper{inner: inner}
+}
+
+// NewRedisCredentialsStore creates a new Redis-backed credentials store.
+// The cache should be configured with a Redis backend for distributed storage.
+// If keyPrefix is empty, defaults to "dcr:creds:"
+func NewRedisCredentialsStore(cache *UniversalCache, keyPrefix string, logger *Logger) *RedisCredentialsStore {
+	var dcrLogger dcrstorage.Logger
+	if logger != nil {
+		dcrLogger = &loggerAdapter{logger: logger}
+	}
+	cacheAdapt := &cacheAdapter{cache: cache}
+	inner := dcrstorage.NewRedisStore(cacheAdapt, keyPrefix, dcrLogger)
+	return &redisStoreWrapper{inner: inner}
+}
+
+// Helper functions to convert between main package and internal package types
+func convertCredsToInternal(creds *ClientRegistrationResponse) *dcrstorage.ClientRegistrationResponse {
+	if creds == nil {
+		return nil
+	}
+	return &dcrstorage.ClientRegistrationResponse{
+		SubjectType:             creds.SubjectType,
+		LogoURI:                 creds.LogoURI,
+		RegistrationAccessToken: creds.RegistrationAccessToken,
+		RegistrationClientURI:   creds.RegistrationClientURI,
+		Scope:                   creds.Scope,
+		TokenEndpointAuthMethod: creds.TokenEndpointAuthMethod,
+		TOSURI:                  creds.TOSURI,
+		PolicyURI:               creds.PolicyURI,
+		ClientSecret:            creds.ClientSecret,
+		ApplicationType:         creds.ApplicationType,
+		ClientID:                creds.ClientID,
+		ClientName:              creds.ClientName,
+		JWKSURI:                 creds.JWKSURI,
+		ClientURI:               creds.ClientURI,
+		Contacts:                creds.Contacts,
+		GrantTypes:              creds.GrantTypes,
+		ResponseTypes:           creds.ResponseTypes,
+		RedirectURIs:            creds.RedirectURIs,
+		ClientSecretExpiresAt:   creds.ClientSecretExpiresAt,
+		ClientIDIssuedAt:        creds.ClientIDIssuedAt,
+	}
+}
+
+func convertCredsFromInternal(creds *dcrstorage.ClientRegistrationResponse) *ClientRegistrationResponse {
+	if creds == nil {
+		return nil
+	}
+	return &ClientRegistrationResponse{
+		SubjectType:             creds.SubjectType,
+		LogoURI:                 creds.LogoURI,
+		RegistrationAccessToken: creds.RegistrationAccessToken,
+		RegistrationClientURI:   creds.RegistrationClientURI,
+		Scope:                   creds.Scope,
+		TokenEndpointAuthMethod: creds.TokenEndpointAuthMethod,
+		TOSURI:                  creds.TOSURI,
+		PolicyURI:               creds.PolicyURI,
+		ClientSecret:            creds.ClientSecret,
+		ApplicationType:         creds.ApplicationType,
+		ClientID:                creds.ClientID,
+		ClientName:              creds.ClientName,
+		JWKSURI:                 creds.JWKSURI,
+		ClientURI:               creds.ClientURI,
+		Contacts:                creds.Contacts,
+		GrantTypes:              creds.GrantTypes,
+		ResponseTypes:           creds.ResponseTypes,
+		RedirectURIs:            creds.RedirectURIs,
+		ClientSecretExpiresAt:   creds.ClientSecretExpiresAt,
+		ClientIDIssuedAt:        creds.ClientIDIssuedAt,
+	}
+}
+
+// NewDCRCredentialsStore creates a DCRCredentialsStore based on configuration.
+// This factory function handles backend selection logic:
+//   - "file": Use file-based storage (default for backward compatibility)
+//   - "redis": Use Redis exclusively (fails if Redis unavailable)
+//   - "auto": Use Redis if available, fallback to file
+func NewDCRCredentialsStore(
+	config *DynamicClientRegistrationConfig,
+	cacheManager *CacheManager,
+	logger *Logger,
+) (DCRCredentialsStore, error) {
+	if config == nil {
+		return nil, fmt.Errorf("DCR config is nil")
+	}
+
+	if logger == nil {
+		logger = GetSingletonNoOpLogger()
+	}
+
+	backend := config.StorageBackend
+	if backend == "" {
+		backend = string(DCRStorageBackendAuto) // Default to auto selection
+	}
+
+	switch DCRStorageBackend(backend) {
+	case DCRStorageBackendFile:
+		logger.Info("Using file-based storage for DCR credentials")
+		return NewFileCredentialsStore(config.CredentialsFile, logger), nil
+
+	case DCRStorageBackendRedis:
+		cache := getDCRCache(cacheManager)
+		if cache == nil {
+			return nil, fmt.Errorf("redis storage requested but Redis/cache not configured")
+		}
+		logger.Info("Using Redis storage for DCR credentials")
+		return NewRedisCredentialsStore(cache, config.RedisKeyPrefix, logger), nil
+
+	case DCRStorageBackendAuto:
+		// Try Redis first, fallback to file
+		cache := getDCRCache(cacheManager)
+		if cache != nil && cache.backend != nil {
+			logger.Info("Auto-selected Redis storage for DCR credentials")
+			return NewRedisCredentialsStore(cache, config.RedisKeyPrefix, logger), nil
+		}
+		logger.Info("Redis not available, using file storage for DCR credentials")
+		return NewFileCredentialsStore(config.CredentialsFile, logger), nil
+
+	default:
+		return nil, fmt.Errorf("unknown DCR storage backend: %s", backend)
+	}
+}
+
+// getDCRCache safely retrieves the DCR credentials cache from the cache manager
+func getDCRCache(cacheManager *CacheManager) *UniversalCache {
+	if cacheManager == nil {
+		return nil
+	}
+	cacheManager.mu.RLock()
+	defer cacheManager.mu.RUnlock()
+
+	if cacheManager.manager == nil {
+		return nil
+	}
+
+	return cacheManager.manager.GetDCRCredentialsCache()
+}

dcr_storage_test.go

@@ -0,0 +1,663 @@
+// Package traefikoidc provides OIDC authentication middleware for Traefik
+package traefikoidc
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+)
+
+// TestFileCredentialsStore_SaveLoad tests the file-based credentials store
+func TestFileCredentialsStore_SaveLoad(t *testing.T) {
+	t.Parallel()
+
+	// Create a temp directory for test files
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	testCreds := &ClientRegistrationResponse{
+		ClientID:                "test-client-id",
+		ClientSecret:            "test-client-secret",
+		ClientSecretExpiresAt:   time.Now().Add(24 * time.Hour).Unix(),
+		RegistrationAccessToken: "test-access-token",
+		RegistrationClientURI:   "https://example.com/register/test-client-id",
+		RedirectURIs:            []string{"https://app.example.com/callback"},
+		GrantTypes:              []string{"authorization_code", "refresh_token"},
+		ResponseTypes:           []string{"code"},
+		TokenEndpointAuthMethod: "client_secret_basic",
+	}
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	t.Run("save and load credentials", func(t *testing.T) {
+		// Save credentials
+		err := store.Save(ctx, providerURL, testCreds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials: %v", err)
+		}
+
+		// Load credentials
+		loaded, err := store.Load(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to load credentials: %v", err)
+		}
+
+		if loaded == nil {
+			t.Fatal("Expected credentials but got nil")
+		}
+
+		// Verify fields
+		if loaded.ClientID != testCreds.ClientID {
+			t.Errorf("ClientID mismatch: got %s, want %s", loaded.ClientID, testCreds.ClientID)
+		}
+		if loaded.ClientSecret != testCreds.ClientSecret {
+			t.Errorf("ClientSecret mismatch: got %s, want %s", loaded.ClientSecret, testCreds.ClientSecret)
+		}
+		if loaded.RegistrationAccessToken != testCreds.RegistrationAccessToken {
+			t.Errorf("RegistrationAccessToken mismatch: got %s, want %s", loaded.RegistrationAccessToken, testCreds.RegistrationAccessToken)
+		}
+	})
+
+	t.Run("load non-existent credentials", func(t *testing.T) {
+		tempDir2 := t.TempDir()
+		store2 := NewFileCredentialsStore(filepath.Join(tempDir2, "nonexistent.json"), logger)
+
+		loaded, err := store2.Load(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Unexpected error for non-existent file: %v", err)
+		}
+		if loaded != nil {
+			t.Error("Expected nil for non-existent credentials")
+		}
+	})
+
+	t.Run("exists check", func(t *testing.T) {
+		exists, err := store.Exists(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if !exists {
+			t.Error("Expected credentials to exist")
+		}
+
+		exists, err = store.Exists(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if exists {
+			t.Error("Expected credentials to not exist")
+		}
+	})
+
+	t.Run("delete credentials", func(t *testing.T) {
+		err := store.Delete(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to delete credentials: %v", err)
+		}
+
+		exists, _ := store.Exists(ctx, providerURL)
+		if exists {
+			t.Error("Expected credentials to be deleted")
+		}
+	})
+
+	t.Run("delete non-existent credentials", func(t *testing.T) {
+		// Should not error
+		err := store.Delete(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Delete should not error for non-existent: %v", err)
+		}
+	})
+}
+
+// TestFileCredentialsStore_MultiProvider tests multi-provider support
+func TestFileCredentialsStore_MultiProvider(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	ctx := context.Background()
+
+	provider1 := "https://auth1.example.com"
+	provider2 := "https://auth2.example.com"
+
+	creds1 := &ClientRegistrationResponse{
+		ClientID:     "client-1",
+		ClientSecret: "secret-1",
+	}
+	creds2 := &ClientRegistrationResponse{
+		ClientID:     "client-2",
+		ClientSecret: "secret-2",
+	}
+
+	// Save credentials for both providers
+	if err := store.Save(ctx, provider1, creds1); err != nil {
+		t.Fatalf("Failed to save creds1: %v", err)
+	}
+	if err := store.Save(ctx, provider2, creds2); err != nil {
+		t.Fatalf("Failed to save creds2: %v", err)
+	}
+
+	// Load and verify each provider's credentials
+	loaded1, err := store.Load(ctx, provider1)
+	if err != nil {
+		t.Fatalf("Failed to load creds1: %v", err)
+	}
+	if loaded1.ClientID != "client-1" {
+		t.Errorf("Provider 1 ClientID mismatch: got %s", loaded1.ClientID)
+	}
+
+	loaded2, err := store.Load(ctx, provider2)
+	if err != nil {
+		t.Fatalf("Failed to load creds2: %v", err)
+	}
+	if loaded2.ClientID != "client-2" {
+		t.Errorf("Provider 2 ClientID mismatch: got %s", loaded2.ClientID)
+	}
+
+	// Delete one shouldn't affect the other
+	if err := store.Delete(ctx, provider1); err != nil {
+		t.Fatalf("Failed to delete creds1: %v", err)
+	}
+
+	exists, _ := store.Exists(ctx, provider2)
+	if !exists {
+		t.Error("Provider 2 credentials should still exist")
+	}
+}
+
+// TestFileCredentialsStore_ConcurrentAccess tests thread safety
+func TestFileCredentialsStore_ConcurrentAccess(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	creds := &ClientRegistrationResponse{
+		ClientID:     "test-client",
+		ClientSecret: "test-secret",
+	}
+
+	var wg sync.WaitGroup
+	concurrency := 10
+
+	// Concurrent saves
+	for i := 0; i < concurrency; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_ = store.Save(ctx, providerURL, creds)
+		}()
+	}
+	wg.Wait()
+
+	// Concurrent loads
+	for i := 0; i < concurrency; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = store.Load(ctx, providerURL)
+		}()
+	}
+	wg.Wait()
+
+	// Final verification
+	loaded, err := store.Load(ctx, providerURL)
+	if err != nil {
+		t.Fatalf("Failed to load after concurrent access: %v", err)
+	}
+	if loaded == nil || loaded.ClientID != "test-client" {
+		t.Error("Credentials corrupted after concurrent access")
+	}
+}
+
+// TestFileCredentialsStore_InvalidInput tests error handling
+func TestFileCredentialsStore_InvalidInput(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	ctx := context.Background()
+
+	t.Run("save nil credentials", func(t *testing.T) {
+		err := store.Save(ctx, "https://example.com", nil)
+		if err == nil {
+			t.Error("Expected error for nil credentials")
+		}
+	})
+
+	t.Run("empty provider URL uses default path", func(t *testing.T) {
+		creds := &ClientRegistrationResponse{ClientID: "test"}
+		err := store.Save(ctx, "", creds)
+		if err != nil {
+			t.Fatalf("Save with empty provider URL failed: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, "")
+		if err != nil {
+			t.Fatalf("Load with empty provider URL failed: %v", err)
+		}
+		if loaded == nil || loaded.ClientID != "test" {
+			t.Error("Failed to load credentials with empty provider URL")
+		}
+	})
+}
+
+// TestFileCredentialsStore_DefaultPath tests default path behavior
+func TestFileCredentialsStore_DefaultPath(t *testing.T) {
+	t.Parallel()
+
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore("", logger)
+
+	// Just verify we can create with empty path and it has a default
+	if store.basePath() == "" {
+		t.Error("Expected default base path")
+	}
+}
+
+// TestRedisCredentialsStore_WithMemoryCache tests Redis store with in-memory cache
+func TestRedisCredentialsStore_WithMemoryCache(t *testing.T) {
+	t.Parallel()
+
+	// Create an in-memory cache for testing
+	cache := NewUniversalCache(UniversalCacheConfig{
+		Type:       CacheTypeGeneral,
+		MaxSize:    100,
+		DefaultTTL: time.Hour,
+		Logger:     GetSingletonNoOpLogger(),
+	})
+	defer cache.Close()
+
+	logger := GetSingletonNoOpLogger()
+	store := NewRedisCredentialsStore(cache, "", logger)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	testCreds := &ClientRegistrationResponse{
+		ClientID:                "redis-test-client",
+		ClientSecret:            "redis-test-secret",
+		ClientSecretExpiresAt:   time.Now().Add(24 * time.Hour).Unix(),
+		RegistrationAccessToken: "redis-test-token",
+		RedirectURIs:            []string{"https://app.example.com/callback"},
+	}
+
+	t.Run("save and load credentials", func(t *testing.T) {
+		err := store.Save(ctx, providerURL, testCreds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to load credentials: %v", err)
+		}
+
+		if loaded == nil {
+			t.Fatal("Expected credentials but got nil")
+		}
+		if loaded.ClientID != testCreds.ClientID {
+			t.Errorf("ClientID mismatch: got %s, want %s", loaded.ClientID, testCreds.ClientID)
+		}
+		if loaded.ClientSecret != testCreds.ClientSecret {
+			t.Errorf("ClientSecret mismatch: got %s, want %s", loaded.ClientSecret, testCreds.ClientSecret)
+		}
+	})
+
+	t.Run("exists check", func(t *testing.T) {
+		exists, err := store.Exists(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if !exists {
+			t.Error("Expected credentials to exist")
+		}
+	})
+
+	t.Run("delete credentials", func(t *testing.T) {
+		err := store.Delete(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to delete credentials: %v", err)
+		}
+
+		exists, _ := store.Exists(ctx, providerURL)
+		if exists {
+			t.Error("Expected credentials to be deleted")
+		}
+	})
+
+	t.Run("load non-existent credentials", func(t *testing.T) {
+		loaded, err := store.Load(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Unexpected error for non-existent: %v", err)
+		}
+		if loaded != nil {
+			t.Error("Expected nil for non-existent credentials")
+		}
+	})
+}
+
+// TestRedisCredentialsStore_TTLFromExpiry tests TTL calculation
+func TestRedisCredentialsStore_TTLFromExpiry(t *testing.T) {
+	t.Parallel()
+
+	cache := NewUniversalCache(UniversalCacheConfig{
+		Type:       CacheTypeGeneral,
+		MaxSize:    100,
+		DefaultTTL: time.Hour,
+		Logger:     GetSingletonNoOpLogger(),
+	})
+	defer cache.Close()
+
+	logger := GetSingletonNoOpLogger()
+	store := NewRedisCredentialsStore(cache, "", logger)
+
+	ctx := context.Background()
+
+	t.Run("expired credentials should fail", func(t *testing.T) {
+		expiredCreds := &ClientRegistrationResponse{
+			ClientID:              "expired-client",
+			ClientSecret:          "expired-secret",
+			ClientSecretExpiresAt: time.Now().Add(-1 * time.Hour).Unix(), // Already expired
+		}
+
+		err := store.Save(ctx, "https://expired.example.com", expiredCreds)
+		if err == nil {
+			t.Error("Expected error for expired credentials")
+		}
+	})
+
+	t.Run("credentials without expiry use default TTL", func(t *testing.T) {
+		creds := &ClientRegistrationResponse{
+			ClientID:              "no-expiry-client",
+			ClientSecret:          "no-expiry-secret",
+			ClientSecretExpiresAt: 0, // No expiry
+		}
+
+		err := store.Save(ctx, "https://noexpiry.example.com", creds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials without expiry: %v", err)
+		}
+	})
+}
+
+// TestRedisCredentialsStore_InvalidInput tests error handling
+func TestRedisCredentialsStore_InvalidInput(t *testing.T) {
+	t.Parallel()
+
+	cache := NewUniversalCache(UniversalCacheConfig{
+		Type:       CacheTypeGeneral,
+		MaxSize:    100,
+		DefaultTTL: time.Hour,
+		Logger:     GetSingletonNoOpLogger(),
+	})
+	defer cache.Close()
+
+	logger := GetSingletonNoOpLogger()
+	store := NewRedisCredentialsStore(cache, "", logger)
+
+	ctx := context.Background()
+
+	t.Run("save nil credentials", func(t *testing.T) {
+		err := store.Save(ctx, "https://example.com", nil)
+		if err == nil {
+			t.Error("Expected error for nil credentials")
+		}
+	})
+}
+
+// TestDCRStorageFactory tests the factory function
+func TestDCRStorageFactory(t *testing.T) {
+	t.Parallel()
+
+	logger := GetSingletonNoOpLogger()
+
+	t.Run("nil config returns error", func(t *testing.T) {
+		_, err := NewDCRCredentialsStore(nil, nil, logger)
+		if err == nil {
+			t.Error("Expected error for nil config")
+		}
+	})
+
+	t.Run("file backend creates file store", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "file",
+			CredentialsFile:    "/tmp/test-creds.json",
+		}
+
+		store, err := NewDCRCredentialsStore(config, nil, logger)
+		if err != nil {
+			t.Fatalf("Failed to create file store: %v", err)
+		}
+		if store == nil {
+			t.Error("Expected store but got nil")
+		}
+
+		_, ok := store.(*FileCredentialsStore)
+		if !ok {
+			t.Error("Expected FileCredentialsStore")
+		}
+	})
+
+	t.Run("redis backend without cache manager returns error", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "redis",
+		}
+
+		_, err := NewDCRCredentialsStore(config, nil, logger)
+		if err == nil {
+			t.Error("Expected error for redis backend without cache manager")
+		}
+	})
+
+	t.Run("auto backend without redis falls back to file", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "auto",
+		}
+
+		store, err := NewDCRCredentialsStore(config, nil, logger)
+		if err != nil {
+			t.Fatalf("Failed to create auto store: %v", err)
+		}
+
+		_, ok := store.(*FileCredentialsStore)
+		if !ok {
+			t.Error("Expected FileCredentialsStore for auto without redis")
+		}
+	})
+
+	t.Run("unknown backend returns error", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "unknown",
+		}
+
+		_, err := NewDCRCredentialsStore(config, nil, logger)
+		if err == nil {
+			t.Error("Expected error for unknown backend")
+		}
+	})
+
+	t.Run("empty backend defaults to auto", func(t *testing.T) {
+		config := &DynamicClientRegistrationConfig{
+			Enabled:            true,
+			PersistCredentials: true,
+			StorageBackend:     "",
+		}
+
+		store, err := NewDCRCredentialsStore(config, nil, logger)
+		if err != nil {
+			t.Fatalf("Failed to create store with empty backend: %v", err)
+		}
+
+		// Should default to file (auto without redis)
+		_, ok := store.(*FileCredentialsStore)
+		if !ok {
+			t.Error("Expected FileCredentialsStore for empty backend")
+		}
+	})
+}
+
+// TestDynamicClientRegistrar_WithStore tests registrar with store
+func TestDynamicClientRegistrar_WithStore(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	config := &DynamicClientRegistrationConfig{
+		Enabled:            true,
+		PersistCredentials: true,
+	}
+
+	registrar := NewDynamicClientRegistrarWithStore(
+		nil, // httpClient
+		logger,
+		config,
+		"https://auth.example.com",
+		store,
+	)
+
+	if registrar == nil {
+		t.Fatal("Expected registrar but got nil")
+	}
+
+	if registrar.store == nil {
+		t.Error("Expected store to be set")
+	}
+
+	// Test SetStore
+	newStore := NewFileCredentialsStore(filepath.Join(tempDir, "new.json"), logger)
+	registrar.SetStore(newStore)
+
+	if registrar.store != newStore {
+		t.Error("SetStore did not update the store")
+	}
+}
+
+// TestDynamicClientRegistrar_CredentialsFromStore tests loading from store
+func TestDynamicClientRegistrar_CredentialsFromStore(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	providerURL := "https://auth.example.com"
+	ctx := context.Background()
+
+	// Pre-save credentials
+	testCreds := &ClientRegistrationResponse{
+		ClientID:              "pre-saved-client",
+		ClientSecret:          "pre-saved-secret",
+		ClientSecretExpiresAt: time.Now().Add(24 * time.Hour).Unix(),
+	}
+	if err := store.Save(ctx, providerURL, testCreds); err != nil {
+		t.Fatalf("Failed to pre-save credentials: %v", err)
+	}
+
+	config := &DynamicClientRegistrationConfig{
+		Enabled:            true,
+		PersistCredentials: true,
+	}
+
+	registrar := NewDynamicClientRegistrarWithStore(
+		nil,
+		logger,
+		config,
+		providerURL,
+		store,
+	)
+
+	// Test loading via the internal method
+	loaded, err := registrar.loadCredentialsFromStore(ctx)
+	if err != nil {
+		t.Fatalf("Failed to load from store: %v", err)
+	}
+	if loaded == nil {
+		t.Fatal("Expected credentials but got nil")
+	}
+	if loaded.ClientID != "pre-saved-client" {
+		t.Errorf("ClientID mismatch: got %s", loaded.ClientID)
+	}
+}
+
+// TestFileCredentialsStore_CorruptedFile tests handling of corrupted files
+func TestFileCredentialsStore_CorruptedFile(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(basePath, logger)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	// Write corrupted JSON
+	filePath := store.getFilePath(providerURL)
+	if err := os.WriteFile(filePath, []byte("{corrupted json"), 0600); err != nil {
+		t.Fatalf("Failed to write corrupted file: %v", err)
+	}
+
+	// Should return error for corrupted file
+	_, err := store.Load(ctx, providerURL)
+	if err == nil {
+		t.Error("Expected error for corrupted JSON")
+	}
+}
+
+// TestFileCredentialsStore_DirectoryCreation tests auto directory creation
+func TestFileCredentialsStore_DirectoryCreation(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	deepPath := filepath.Join(tempDir, "deep", "nested", "path", "credentials.json")
+	logger := GetSingletonNoOpLogger()
+	store := NewFileCredentialsStore(deepPath, logger)
+
+	ctx := context.Background()
+	creds := &ClientRegistrationResponse{ClientID: "test"}
+
+	err := store.Save(ctx, "https://example.com", creds)
+	if err != nil {
+		t.Fatalf("Failed to save with nested directory: %v", err)
+	}
+
+	loaded, err := store.Load(ctx, "https://example.com")
+	if err != nil {
+		t.Fatalf("Failed to load after nested directory creation: %v", err)
+	}
+	if loaded == nil || loaded.ClientID != "test" {
+		t.Error("Failed to load credentials from nested directory")
+	}
+}

docs/AUTH0_AUDIENCE_GUIDE.md

@@ -25,7 +25,10 @@ The **audience** (`aud`) claim in a JWT identifies the intended recipient of the
 
 ### Why Does This Matter?
 
-Proper audience validation prevents **token confusion attacks** where a token intended for one API is used to access another API.
+Audience validation rejects access tokens whose `aud` claim does not match the
+expected audience, blocking the trivial form of token confusion where a token
+issued for API A is presented to API B. (Defence in depth — pair with
+short-lived tokens, rotation, and per-API client credentials.)
 
 ---
 
@@ -137,8 +140,8 @@ http:
 **Recommended:** `true` for production
 
 **What it does:**
-- When `true`: Rejects sessions if access token audience doesn't match (prevents Scenario 2)
-- When `false`: Logs warnings but allows fallback to ID token (backward compatible)
+- When `true`: On audience mismatch, the middleware does **not** silently fall back to ID-token validation. It tries to refresh the access token first; if no refresh token is present (or refresh fails), the user is re-authenticated.
+- When `false`: Logs warnings and falls back to ID-token validation (backward compatible).
 
 **Example:**
 ```yaml
@@ -349,7 +352,7 @@ When opaque tokens are detected:
 
 **Cache behavior:**
 - Cache key: Token hash
-- TTL: 5 minutes or token expiry (whichever is shorter)
+- TTL: 5 minutes; if the token's `exp` is sooner, the cache entry expires at `exp` instead. Tokens without `exp` use the flat 5-minute TTL.
 - Reduces introspection requests for frequently used tokens
 
 ---

docs/BEARER_AUTH.md

@@ -0,0 +1,250 @@
+# Bearer Token (M2M) Authentication
+
+Opt-in path that lets API clients present `Authorization: Bearer <jwt>` to
+authenticate without going through the cookie-based OIDC redirect flow.
+Designed for machine-to-machine (M2M) traffic — services calling other
+services with tokens minted by your OIDC provider.
+
+The bearer path lives next to the cookie path: both go through the same
+post-auth pipeline (`forwardAuthorized`) that injects identity headers,
+checks `allowedRolesAndGroups`, applies security headers, and forwards to
+the backend. The only thing that differs is how the principal is established
+for that single request.
+
+## Quick start
+
+```yaml
+enableBearerAuth: true
+audience: https://api.example.com  # REQUIRED when bearer is enabled
+clientID: my-api-client-id
+providerURL: https://issuer.example.com
+sessionEncryptionKey: <32+-byte secret>
+callbackURL: /oauth2/callback
+```
+
+That is the minimum. Everything else has a secure default.
+
+## Obtaining bearer tokens from your OIDC provider
+
+The middleware only **validates** bearer tokens — minting them is the IdP's job. For M2M traffic the canonical mint flow is OAuth 2.0 **`client_credentials`** (RFC 6749 §4.4); some providers require **JWT bearer assertion** (RFC 7523) instead.
+
+```
+┌────────────┐  POST /token                    ┌──────────┐
+│  client    │ ───────────────────────────────►│  IdP     │
+│  (service) │   grant_type=client_credentials │ /token   │
+│            │   client_id=…                   │          │
+│            │   client_secret=…  (or JWT)     │          │
+│            │   audience=https://api.…   ←── critical    │
+│            │   scope=api:read …                         │
+│            │ ◄───────────────────────────────│          │
+│            │     access_token (JWT)          │          │
+└────────────┘                                 └──────────┘
+         │
+         │  GET /protected
+         │  Authorization: Bearer <access_token>
+         ▼
+   Your service (behind Traefik + this plugin)
+```
+
+The IdP returns a JWT signed by the same JWKs the middleware already trusts (it discovers them from `providerURL`/.well-known). On the first protected request, the middleware verifies signature + issuer + **audience** + `exp` + identifier claim, then forwards downstream with `X-Forwarded-User` set.
+
+### Minimal worked example (Auth0-shape)
+
+```bash
+# 1. Mint a token
+curl -s -X POST https://issuer.example.com/oauth/token \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "grant_type":    "client_credentials",
+    "client_id":     "your-m2m-client-id",
+    "client_secret": "your-m2m-client-secret",
+    "audience":      "https://api.example.com",
+    "scope":         "api:read api:write"
+  }'
+# → {"access_token":"eyJhbGciOiJSUzI1NiIs…","token_type":"Bearer","expires_in":86400,…}
+
+# 2. Use it
+curl -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs…' https://api.example.com/protected
+```
+
+The `audience` field in the token request **must match** the `audience` you configured on the middleware. Mismatch → 401 with `Bearer error="invalid_token"`.
+
+### Per-provider quick reference
+
+| Provider | Grant | Token endpoint | Audience parameter | Notes |
+|---|---|---|---|---|
+| **Auth0** | `client_credentials` | `https://TENANT.auth0.com/oauth/token` | `audience=<your API identifier>` | Register an "API" + "Machine to Machine Application" authorised against that API. Without `audience` you get an opaque /userinfo token, which the bearer path rejects. See `docs/AUTH0_AUDIENCE_GUIDE.md`. |
+| **Okta** | `client_credentials` | `https://TENANT.okta.com/oauth2/default/v1/token` | Configured in the authorization server; default `aud` is the auth-server URL | Service app must enable the `client_credentials` flow and be granted the requested scopes. |
+| **Keycloak** | `client_credentials` | `https://kc/realms/REALM/protocol/openid-connect/token` | Configure an "Audience" mapper on a client scope, or use `client_id` as the audience | Client must have `serviceAccountsEnabled: true` plus role mappings. |
+| **Entra ID / Azure AD** | `client_credentials` (v2.0 endpoint) | `https://login.microsoftonline.com/TENANT/oauth2/v2.0/token` | Pass `scope=<App ID URI>/.default`; `aud` ends up being the API's App ID URI | Requires an App Registration + API permissions + admin consent. **Use the v2.0 endpoint** — v1 issues Microsoft-proprietary access tokens that are opaque to non-Microsoft clients. |
+| **AWS Cognito** | `client_credentials` | `https://YOUR_DOMAIN.auth.REGION.amazoncognito.com/oauth2/token` | Scopes from a "Resource Server" attached to your User Pool | App client must have `client_credentials` flow enabled. Use HTTP **Basic** auth header for `client_id:client_secret`. |
+| **GitLab** | `client_credentials` | `https://gitlab.com/oauth/token` | Audience matches the GitLab issuer | Rarely used for protecting external APIs; better suited for GitLab's own resources. |
+| **Google** | **JWT bearer (RFC 7523)** — *not* `client_credentials` | `https://oauth2.googleapis.com/token` | Signed assertion JWT carries `aud=https://oauth2.googleapis.com/token`; resulting access token is **opaque** unless you specifically request a Google-issued JWT for your API | Google service-account flow is not the best fit for this middleware (opaque tokens are rejected on the bearer path). Run Auth0 / Okta / Keycloak in front, or use ID-token-based flows on the cookie path. |
+
+### RFC 7523 (JWT bearer assertion) — secretless alternative
+
+When shared secrets are forbidden (FAPI, internal compliance), swap `client_secret` for a signed JWT assertion:
+
+```
+POST /token
+grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
+assertion=<JWT signed by the client's private key>
+```
+
+The assertion JWT carries `iss=<client_id>`, `sub=<client_id>`, `aud=<token endpoint>`, `exp`. The IdP verifies the signature against a public key you've pre-registered and returns an access token.
+
+This middleware already supports JWT assertions on the *middleware → IdP* hop via `clientAuthMethod: private_key_jwt` (see `docs/CONFIGURATION.md`). For the *client → IdP* hop, the same pattern applies — the client signs its own assertion.
+
+### Operational notes
+
+- **Token TTL is typically 1–24 hours.** Clients should refresh on `401`, not on a polling timer — saves the IdP.
+- **Cache and reuse tokens.** The middleware caches verified tokens too, so repeated presentations are cheap. Clients SHOULD reuse a token until ~80 % of `expires_in`.
+- **JWKS rotation is transparent.** The middleware auto-refreshes its JWKS cache when the IdP rotates keys. Clients don't need to do anything.
+- **Revocation is generally not per-token** with `client_credentials`. If you need real-time revocation, set `requireTokenIntrospection: true` on the middleware and the IdP is consulted on every cache miss.
+- **`scope` vs `audience`.** Scope says *what the client may do*; audience says *which service the token is for*. The middleware enforces audience; the backend service should enforce scope.
+- **Secret hygiene.** Store `client_secret` in a secrets manager (Vault, AWS Secrets Manager, Kubernetes `Secret`). For higher assurance, switch the client to `private_key_jwt` (no shared secret at all).
+
+### Quickest validation loop
+
+```bash
+# 1. Mint
+TOKEN=$(curl -s -X POST https://issuer.example.com/oauth/token \
+  -H 'Content-Type: application/json' \
+  -d '{"grant_type":"client_credentials","client_id":"…","client_secret":"…","audience":"https://api.example.com"}' \
+  | jq -r .access_token)
+
+# 2. Inspect claims to confirm aud/iss/exp match the middleware config
+echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq
+
+# 3. Hit the protected route
+curl -i -H "Authorization: Bearer $TOKEN" https://api.example.com/protected
+```
+
+`HTTP/1.1 200` with `X-Forwarded-User` on the backend confirms the loop works end-to-end. `401` with `WWW-Authenticate: Bearer error="invalid_token"` plus a middleware debug log explaining the rejection (audience mismatch, ID token presented, `iat` outside the 24h window, etc.) confirms the hardening is firing as designed.
+
+## Threat model and design rules
+
+Bearer authentication has materially different security properties from
+cookie sessions: no `HttpOnly`/`Secure`/`SameSite` shielding, the token is
+visible in headers and logs, and it's easier to exfiltrate. The bearer path
+treats every one of these as a first-class concern.
+
+| Property | Behaviour | Why |
+|---|---|---|
+| 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. |
+| `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. |
+| Multi-audience | When `aud` is an array of length > 1, the token must carry `azp == clientID`. | OIDC §2 hardening against tokens minted for one client being replayed by another. |
+| `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. |
+| 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. |
+| 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. |
+
+## Configuration reference
+
+| Field | Default | Description |
+|---|---|---|
+| `enableBearerAuth` | `false` | Master switch for the bearer path. |
+| `audience` | (unset) | **Required** when `enableBearerAuth=true`. Reuses the existing global `audience` field. |
+| `bearerIdentifierClaim` | `"sub"` | JWT claim used as the principal identifier. `"email"` is rejected at startup. |
+| `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). |
+| `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. |
+
+## What the bearer path does NOT do
+
+- **Human-user / browser flows.** The bearer path is M2M-only in this
+  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.
+- **`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
+  follow-up that must include this check.
+- **mTLS / API keys.** Out of scope. The `principal` abstraction enables
+  adding these later as additional auth methods that produce a principal
+  for the shared `forwardAuthorized` pipeline.
+- **SSE / WebSocket bypass with bearer.** Bypass paths keep their existing
+  cookie-only behaviour; bearer headers are ignored on those endpoints.
+  Documented limitation; widen by removing the bypass if you need bearer on
+  streaming endpoints.
+
+## Operational guidance
+
+- **Always set `strictAudienceValidation: true` when bearer is enabled.**
+  Startup logs a recommendation if you don't.
+- **Set a tight `maxTokenAgeSeconds`** for environments where tokens are
+  expected to be minted frequently — the default 24h is conservative.
+- **Enable `requireTokenIntrospection`** if your IdP supports it and
+  revocation latency matters. Bearer-path introspection caches results for
+  a short window per token.
+- **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.
+- **`stripAuthorizationHeader=false` extends the token's blast radius** to
+  every downstream service that sees the request. Treat those services'
+  logs as token stores.
+- **Bearer reuse is normal.** Don't enable per-token rate limiting; that's
+  what `bearerFailureThreshold` is for (per-IP, not per-token).
+- **Cookie-wins is the safer default.** Only flip `bearerOverridesCookie`
+  if you control all clients and have audited that none of them present a
+  cookie alongside a bearer they don't intend to authenticate with.
+
+## Failure response matrix
+
+| Trigger | Status | Body | `WWW-Authenticate` |
+|---|---|---|---|
+| Empty bearer after prefix | 401 | `Unauthorized` | `Bearer error="invalid_request"` |
+| Token over `MaxLength` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Not a 3-segment JWT | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Disallowed `alg` (e.g. none, HS*) | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Missing / oversized / bad-charset `kid` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Signature / issuer / audience / `exp` failure | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| `iat` older than `maxTokenAgeSeconds` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| 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) |
+| 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>` |
+| Roles / groups not allowed | 403 | `Access denied` | (none) |
+
+## Known follow-ups (deferred)
+
+These are documented as future work, not blockers:
+
+- **Human-user bearer with `email_verified` enforcement.** Requires
+  decoupling the email-claim guard from the startup rejection and adding a
+  per-request `email_verified=true` check.
+- **Introspection respects `client_assertion`.** The existing introspection
+  helper uses `client_secret_basic` only; operators on `private_key_jwt`
+  will see introspection silently use basic auth.
+- **Per-route bearer configuration.** Single middleware-wide setting in this
+  iteration.
+
+## References
+
+- [PR design spec](superpowers/specs/2026-05-18-bearer-token-auth-design.md) — full design rationale, alternatives considered, and per-section sign-off history.
+- [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750) — Bearer Token Usage.
+- [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662) — OAuth 2.0 Token Introspection.
+- [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068) — JWT Profile for OAuth 2.0 Access Tokens.

docs/CONFIGURATION.md

@@ -5,6 +5,7 @@ Complete reference for all Traefik OIDC middleware configuration options.
 ## Table of Contents
 
 - [Required Parameters](#required-parameters)
+- [Client Authentication](#client-authentication)
 - [Optional Parameters](#optional-parameters)
 - [Security Options](#security-options)
 - [Session Management](#session-management)
@@ -22,7 +23,7 @@ Complete reference for all Traefik OIDC middleware configuration options.
 |-----------|------|-------------|---------|
 | `providerURL` | string | Base URL of the OIDC provider | `https://accounts.google.com` |
 | `clientID` | string | OAuth 2.0 client identifier | `1234567890.apps.googleusercontent.com` |
-| `clientSecret` | string | OAuth 2.0 client secret | `your-client-secret` |
+| `clientSecret` | string | OAuth 2.0 client secret. Required when `clientAuthMethod` is unset, `client_secret_post`, or `client_secret_basic`. Optional when `clientAuthMethod: private_key_jwt`. | `your-client-secret` |
 | `sessionEncryptionKey` | string | Key for encrypting session data (min 32 bytes) | `your-32-byte-encryption-key-here` |
 | `callbackURL` | string | Path where provider redirects after authentication | `/oauth2/callback` |
 
@@ -45,6 +46,129 @@ spec:
 
 ---
 
+## Client Authentication
+
+The middleware supports three client authentication methods at the token and
+revocation endpoints. The default is `client_secret_post` (current behavior);
+`private_key_jwt` is opt-in and backwards compatible.
+
+| Method | Default | Description |
+|--------|---------|-------------|
+| `client_secret_post` | yes | `client_id` + `client_secret` in the request body. |
+| `client_secret_basic` | no | RFC 6749 §2.3.1 — `client_id` + `client_secret` in the `Authorization: Basic` header (form-urlencoded then base64); not in the body. |
+| `private_key_jwt` | no | RFC 7523 §2.2 — plugin signs a short-lived JWT with a private key and sends it as `client_assertion`. |
+
+Select via `clientAuthMethod`:
+
+```yaml
+clientAuthMethod: private_key_jwt
+```
+
+### client_secret_post
+
+Default. The plugin sends `client_id` and `client_secret` as form parameters
+in the token / revocation request body. No additional configuration required.
+
+### private_key_jwt
+
+Asymmetric client authentication per
+[RFC 7523 §2.2](https://www.rfc-editor.org/rfc/rfc7523). Use this when your
+IdP enforces short secret TTLs, when policy mandates secretless clients, or
+when you want to avoid distributing a shared secret to the proxy.
+
+For each token / revocation request the plugin builds a JWS with:
+
+- `iss` = `sub` = `clientID`
+- `aud` = token endpoint URL
+- `iat` = now, `exp` = now + 60s
+- `jti` = random hex per request
+- `kid` header = `clientAssertionKeyID`
+
+**Required fields:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `clientAuthMethod` | string | `client_secret_post` | Set to `private_key_jwt`. |
+| `clientAssertionPrivateKey` | string | none | Inline PEM private key. Mutually exclusive with `clientAssertionKeyPath`. PKCS#8, PKCS#1, and SEC1 formats accepted. |
+| `clientAssertionKeyPath` | string | none | Path to PEM private key on disk. Mutually exclusive with `clientAssertionPrivateKey`. |
+| `clientAssertionKeyID` | string | none | `kid` header inserted in the JWS. Must match the public key registered with the IdP. |
+| `clientAssertionAlg` | string | `RS256` | One of `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384`, `ES512`. |
+
+When `clientAuthMethod: private_key_jwt`, `clientSecret` is optional.
+
+**Example — inline PEM:**
+
+```yaml
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: oidc-auth
+spec:
+  plugin:
+    traefikoidc:
+      providerURL: https://idp.example.com
+      clientID: my-client-id
+      sessionEncryptionKey: your-32-byte-encryption-key-here
+      callbackURL: /oauth2/callback
+      clientAuthMethod: private_key_jwt
+      clientAssertionKeyID: key-2026-01
+      clientAssertionAlg: RS256
+      clientAssertionPrivateKey: |
+        -----BEGIN PRIVATE KEY-----
+        MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7VJTUt9Us8cKj
+        MZj4ev7QnMa1mYV3Kx1jRkH5YwXQ7N2J2j8K5pP6h0oZmXq1yQv4r8wZb3sH9D2k
+        ... (truncated) ...
+        -----END PRIVATE KEY-----
+```
+
+**Example — key on disk:**
+
+```yaml
+clientAuthMethod: private_key_jwt
+clientAssertionKeyPath: /etc/traefik/oidc/client-key.pem
+clientAssertionKeyID: key-2026-01
+clientAssertionAlg: RS256
+```
+
+**Generating an RS256 key with OpenSSL:**
+
+```bash
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 \
+  -out client-key.pem
+openssl rsa -in client-key.pem -pubout -out client-pub.pem
+```
+
+Register `client-pub.pem` (or its JWK form) with your IdP under the same
+`kid` you set in `clientAssertionKeyID`.
+
+**Notes:**
+
+- The private key is parsed once at plugin startup. Key rotation requires a
+  Traefik reload.
+- Assertion lifetime is fixed at 60 seconds.
+- A fresh random `jti` is generated per request.
+- The `aud` claim is the token endpoint URL (from discovery).
+- Tracking issue:
+  [#135](https://github.com/lukaszraczylo/traefikoidc/issues/135).
+
+### client_secret_basic
+
+Per [RFC 6749 §2.3.1][rfc6749-2-3-1], the plugin sends the client credentials
+in an `Authorization: Basic` header instead of the body. Both halves
+(`client_id`, `client_secret`) are form-urlencoded individually, joined with
+a colon, then base64-encoded. Use this when your IdP requires Basic auth at
+the token endpoint and rejects credentials in the body.
+
+```yaml
+clientAuthMethod: client_secret_basic
+clientID: your-client-id
+clientSecret: your-client-secret
+```
+
+[rfc6749-2-3-1]: https://www.rfc-editor.org/rfc/rfc6749#section-2.3.1
+
+---
+
 ## Optional Parameters
 
 | Parameter | Type | Default | Description |
@@ -52,23 +176,55 @@ spec:
 | `logoutURL` | string | `callbackURL + "/logout"` | Path for logout requests |
 | `postLogoutRedirectURI` | string | `/` | Redirect URL after logout |
 | `logLevel` | string | `info` | Logging verbosity (`debug`, `info`, `error`) |
-| `forceHTTPS` | bool | `false` | Force HTTPS for redirect URIs |
+| `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 |
 | `revocationURL` | string | auto-discovered | Token revocation endpoint |
 | `oidcEndSessionURL` | string | auto-discovered | Provider's end session endpoint |
 | `enablePKCE` | bool | `false` | Enable PKCE for authorization code flow |
 | `minimalHeaders` | bool | `false` | Reduce forwarded headers |
+| `clientAuthMethod` | string | `client_secret_post` | Client authentication method at token/revocation endpoints. One of `client_secret_post`, `client_secret_basic`, `private_key_jwt`. See [Client Authentication](#client-authentication). |
+| `clientAssertionPrivateKey` | string | none | Inline PEM private key for `private_key_jwt`. Mutually exclusive with `clientAssertionKeyPath`. PKCS#8 / PKCS#1 / SEC1. |
+| `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`. |
 
 ### TLS Termination at Load Balancer
 
-If running Traefik behind a load balancer (AWS ALB, Google Cloud LB, Azure App Gateway) that terminates TLS:
+`forceHTTPS` defaults to `true`, so redirect URIs always use `https://`. This is
+the correct default behind any TLS-terminating load balancer (AWS ALB, Google
+Cloud LB, Azure App Gateway) — `X-Forwarded-Proto` cannot be trusted (ALB may
+overwrite it).
 
-```yaml
-forceHTTPS: true  # Required for correct redirect URIs
-```
+Set `forceHTTPS: false` only when you serve OIDC over plaintext HTTP (local
+dev). Otherwise leave it at default.
 
-Without this setting, redirect URIs will use `http://` instead of `https://`, causing OAuth callback failures.
+### Streaming Endpoints (SSE and WebSocket)
+
+The middleware automatically bypasses the OIDC redirect for two request kinds
+that browsers cannot follow a 302 on:
+
+| Bypass | Triggered by |
+|--------|--------------|
+| Server-Sent Events (SSE) | `Accept: text/event-stream` |
+| WebSocket upgrade | `Upgrade: websocket` + `Connection: upgrade` (RFC 6455) |
+
+These requests do **not** require any explicit configuration — they are
+handled implicitly. However, the bypass is **not** unauthenticated:
+
+- A valid, encrypted session cookie is required. Requests without one are
+  rejected (the connection cannot proceed to the backend).
+- The session cookie is sealed with `sessionEncryptionKey`, so the
+  `authenticated` flag cannot be forged.
+- Validation is cookie-only — no JWK fetch / signature verification — so
+  streaming endpoints keep working when the OIDC provider is briefly
+  unavailable.
+- The user identifier from the session is forwarded as `X-Forwarded-User`
+  (and `X-Auth-Request-User` unless `minimalHeaders: true`).
+
+For browser clients, the user must complete the normal OIDC flow on a
+regular HTTP page first; the resulting session cookie is then reused on the
+SSE / WebSocket connection.
 
 ---
 
@@ -105,6 +261,26 @@ strictAudienceValidation: true
 | `disableReplayDetection` | bool | `false` | Disable JTI-based replay attack detection |
 | `allowPrivateIPAddresses` | bool | `false` | Allow private IPs in provider URLs |
 
+### Bearer-token (M2M) authentication
+
+Opt-in path that accepts `Authorization: Bearer <jwt>` instead of the cookie
+session flow. M2M-only, default off, audience-mandatory. See
+[docs/BEARER_AUTH.md](BEARER_AUTH.md) for the threat model and operational
+guidance.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `enableBearerAuth` | bool | `false` | Master switch. Startup fails if true with empty `audience` or with `bearerIdentifierClaim=email`. |
+| `bearerIdentifierClaim` | string | `"sub"` | JWT claim used as the principal identifier. `"email"` is rejected at startup. |
+| `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. |
+| `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. |
+| `bearerFailurePenaltySeconds` | int | `60` | 429 + `Retry-After` duration after the threshold trips. |
+
 ---
 
 ## Session Management
@@ -113,6 +289,7 @@ strictAudienceValidation: true
 |-----------|------|---------|-------------|
 | `sessionMaxAge` | int | `86400` (24h) | Maximum session age in seconds |
 | `refreshGracePeriodSeconds` | int | `60` | Seconds before expiry to attempt refresh |
+| `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 |
 
@@ -384,10 +561,14 @@ scopes:
 
 ### Dynamic Client Registration (RFC 7591)
 
+Dynamic Client Registration allows the middleware to automatically register itself with the OIDC provider, eliminating the need to manually create client credentials.
+
+**Basic Configuration (Single Instance):**
+
 ```yaml
 dynamicClientRegistration:
   enabled: true
-  initialAccessToken: "your-token"  # Optional
+  initialAccessToken: "your-token"  # Optional, if provider requires it
   persistCredentials: true
   credentialsFile: "/tmp/oidc-credentials.json"
   clientMetadata:
@@ -400,6 +581,35 @@ dynamicClientRegistration:
       - "refresh_token"
 ```
 
+**Multi-Replica Deployment (Kubernetes):**
+
+For Kubernetes deployments with multiple replicas, use Redis storage to share credentials across all instances and prevent registration race conditions:
+
+```yaml
+dynamicClientRegistration:
+  enabled: true
+  persistCredentials: true
+  storageBackend: "redis"  # Share credentials via Redis
+  redisKeyPrefix: "myapp:dcr:"  # Optional custom prefix
+  clientMetadata:
+    redirect_uris:
+      - "https://your-app.com/oauth2/callback"
+    client_name: "My Application"
+
+redis:
+  enabled: true
+  address: "redis:6379"
+  cacheMode: "redis"
+```
+
+**Storage Backend Options:**
+
+| Backend | Description | Use Case |
+|---------|-------------|----------|
+| `file` | Store credentials in local file | Single instance deployments |
+| `redis` | Store credentials in Redis | Multi-replica Kubernetes deployments |
+| `auto` | Use Redis if available, fallback to file | Flexible deployments (default) |
+
 ### Multi-Replica Deployment
 
 Without Redis, disable replay detection:

docs/DCR.md

@@ -0,0 +1,95 @@
+# Dynamic Client Registration (RFC 7591)
+
+The middleware can register itself with an OIDC provider at startup instead of
+using a pre-provisioned `clientID` / `clientSecret`. Useful for multi-tenant
+deployments, self-service integrations, and ephemeral environments.
+
+## How it works
+
+1. Middleware reads `registration_endpoint` from `.well-known/openid-configuration`.
+2. If `clientID` is empty, it `POST`s `clientMetadata` to the registration endpoint.
+3. Returned `client_id` / `client_secret` are cached, optionally persisted.
+4. Subsequent requests use the registered credentials.
+
+For multi-replica deployments, set `storageBackend: redis` so all replicas
+share one client and avoid registration races.
+
+## Configuration
+
+```yaml
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: oidc-dcr
+  namespace: traefik
+spec:
+  plugin:
+    traefikoidc:
+      providerURL: https://your-oidc-provider.com
+      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
+      callbackURL: /oauth2/callback
+      dynamicClientRegistration:
+        enabled: true
+        persistCredentials: true
+        storageBackend: redis        # file | redis | auto
+        initialAccessToken: ""        # optional, for protected endpoints
+        registrationEndpoint: ""      # optional, override discovery
+        credentialsFile: /tmp/oidc-client-credentials.json
+        redisKeyPrefix: "dcr:creds:"
+        clientMetadata:
+          redirect_uris:
+            - https://app.example.com/oauth2/callback
+          client_name: My Application
+          application_type: web
+          grant_types: [authorization_code, refresh_token]
+          response_types: [code]
+          token_endpoint_auth_method: client_secret_basic
+          contacts: [admin@example.com]
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `enabled` | `false` | Enable DCR. |
+| `persistCredentials` | `false` | Save returned credentials for reuse across restarts. |
+| `storageBackend` | `auto` | `file`, `redis`, or `auto` (Redis if available, else file). |
+| `credentialsFile` | `/tmp/oidc-client-credentials.json` | Path for file-backed storage. Mode `0600`. |
+| `redisKeyPrefix` | (none — set explicitly) | Key prefix for Redis-backed storage. The code does not inject a default; if unset, keys have no prefix. `dcr:creds:` is a sensible convention. |
+| `registrationEndpoint` | discovered | Override the discovered endpoint. |
+| `initialAccessToken` | none | Bearer token for protected registration endpoints. |
+| `clientMetadata.redirect_uris` | required | Callback URIs for the OAuth flow. |
+| `clientMetadata.client_name` | none | Human-readable client name. |
+| `clientMetadata.application_type` | `web` | `web` or `native`. |
+| `clientMetadata.grant_types` | `[authorization_code, refresh_token]` | OAuth grant types. |
+| `clientMetadata.response_types` | `[code]` | OAuth response types. |
+| `clientMetadata.token_endpoint_auth_method` | `client_secret_basic` | `client_secret_basic`, `client_secret_post`, or `none`. |
+| `clientMetadata.scope` | none | Space-separated scopes. |
+| `clientMetadata.contacts` | none | Admin email addresses. |
+| `clientMetadata.logo_uri` | none | Logo URL for consent screens. |
+| `clientMetadata.client_uri` | none | Client homepage URL. |
+| `clientMetadata.policy_uri` | none | Privacy policy URL. |
+| `clientMetadata.tos_uri` | none | Terms of service URL. |
+
+## Provider support
+
+The middleware does not gate DCR by provider — if the provider exposes a
+`registration_endpoint` in its discovery document (or you set
+`registrationEndpoint` explicitly), DCR will attempt registration. The table
+below is informational guidance based on each provider's published support.
+
+| Provider | DCR | Notes |
+|----------|-----|-------|
+| Keycloak | Yes | Enable in realm settings. |
+| Auth0 | Yes | Requires Management API token. |
+| Okta | Yes | Enable Dynamic Client Registration in admin console. |
+| Azure AD | Limited | Use App Registration API instead. |
+| Google | No | Manual registration required. |
+| AWS Cognito | No | Manual registration required. |
+
+## Security notes
+
+- Registration endpoints must be HTTPS (loopback excepted for local dev).
+- Use `initialAccessToken` in production to gate registration.
+- File-backed credentials use `0600`; protect the mount path.
+- The plugin marks credentials invalid when within ~5 min of `client_secret_expires_at` but does **not** automatically re-register. If your provider sets a non-zero expiry, schedule manual rotation (delete the credentials file or Redis entry, restart) before that time.

docs/DEVELOPMENT.md

@@ -16,9 +16,8 @@ Guide for local development, testing, and contributing to the Traefik OIDC middl
 
 ## Prerequisites
 
-- **Go 1.23+** for plugin compilation
-- **Docker & Docker Compose** for local testing
-- **OIDC Provider** credentials (Google, Azure, etc.)
+- **Go 1.24+** (matches `go.mod`; CI runs Go 1.24.11)
+- **OIDC Provider** credentials (Google, Azure, etc.) for any end-to-end test against a real provider
 
 ### Required Development Tools
 
@@ -40,110 +39,32 @@ go install golang.org/x/vuln/cmd/govulncheck@latest
 
 ## Local Development Setup
 
-### Docker Compose Environment
-
-The repository includes a Docker Compose setup for testing the plugin locally.
-
-#### 1. Host Configuration
-
-Add to `/etc/hosts`:
+### Build and unit tests
 
 ```bash
-127.0.0.1 hello.localhost
-127.0.0.1 traefik.localhost
+go mod tidy
+go build ./...
+go test ./... -short          # fast loop, < 30 s
+go test -race -timeout=15m ./...
 ```
 
-#### 2. Plugin Configuration
+### Sample plugin configurations
 
-The plugin is loaded using Traefik's **local plugins mode**:
+Working middleware/Traefik configs live in [`examples/`](../examples/):
 
-- Plugin source: Parent directory (`../`)
-- Mount path: `/plugins-local/src/github.com/lukaszraczylo/traefikoidc`
-- Configuration: `experimental.localPlugins` in `traefik.yml`
+- `complete-traefik-config.yaml` — full middleware example
+- `redis-config.yaml` — Redis cache configuration
 
-#### 3. OIDC Provider Setup
+To run the plugin against a real Traefik instance, drop the project on disk
+and load it via `experimental.localPlugins` in your Traefik static config —
+see the [README install section](../README.md#install).
 
-Edit `docker/dynamic.yml` with your provider details:
+### Integration tests
 
-**Google:**
-```yaml
-http:
-  middlewares:
-    oidc-auth:
-      plugin:
-        traefikoidc:
-          providerURL: "https://accounts.google.com"
-          clientID: "your-client-id.apps.googleusercontent.com"
-          clientSecret: "your-google-client-secret"
-          sessionEncryptionKey: "your-32-character-encryption-key"
-          callbackURL: "/oauth2/callback"
-          logoutURL: "/oauth2/logout"
-          scopes:
-            - "openid"
-            - "email"
-            - "profile"
-```
-
-**Azure AD:**
-```yaml
-http:
-  middlewares:
-    oidc-auth:
-      plugin:
-        traefikoidc:
-          providerURL: "https://login.microsoftonline.com/your-tenant-id/v2.0"
-          clientID: "your-azure-client-id"
-          clientSecret: "your-azure-client-secret"
-          sessionEncryptionKey: "your-32-character-encryption-key"
-          callbackURL: "/oauth2/callback"
-          scopes:
-            - "openid"
-            - "email"
-            - "profile"
-```
-
-#### 4. Start Environment
+Integration tests live in `integration/`. Run them explicitly:
 
 ```bash
-cd docker
-docker-compose up -d
-```
-
-#### 5. Test Plugin
-
-- **Protected App**: http://hello.localhost (redirects to OIDC)
-- **Traefik Dashboard**: http://traefik.localhost:8080
-
-### Development Workflow
-
-1. **Edit plugin code** in the project root
-2. **Build and test** (optional syntax check):
-   ```bash
-   go mod tidy
-   go build .
-   go test ./...
-   ```
-3. **Restart Traefik** to reload plugin:
-   ```bash
-   docker-compose restart traefik
-   ```
-4. **Test changes** at http://hello.localhost
-
-### Debugging
-
-**View plugin logs:**
-```bash
-docker-compose logs -f traefik | grep traefikoidc
-```
-
-**Check plugin loading:**
-```bash
-docker-compose logs traefik | grep -i plugin
-```
-
-**Verify plugin directory:**
-```bash
-docker-compose exec traefik ls -la /plugins-local/src/github.com/lukaszraczylo/traefikoidc/
+go test ./integration/... -run Integration -v
 ```
 
 ---
@@ -299,7 +220,7 @@ The repository uses GitHub Actions for comprehensive validation with 20+ paralle
 
 #### Testing (9 suites)
 - Race Detector
-- Coverage (75% threshold)
+- Coverage (70% threshold, enforced in `pr.yaml`)
 - Memory Leaks
 - Integration Tests
 - Regression Tests
@@ -323,13 +244,13 @@ Tests run in parallel for:
 #### Performance & Build (3 checks)
 - Benchmarks
 - Multi-platform Build (linux/darwin x amd64/arm64)
-- Go Version Compatibility (Go 1.23 & 1.24)
+- Go Version Compatibility (currently Go 1.24.11 in CI)
 
 ### Quality Gates
 
 All PRs must pass:
 - All parallel checks
-- 75% test coverage minimum
+- 70% test coverage minimum
 - Zero security vulnerabilities
 - No race conditions
 - No memory leaks

docs/PROVIDERS.md

@@ -23,10 +23,10 @@ Configuration reference for each supported OIDC provider.
 | Provider | OIDC Support | Refresh Tokens | Auto-Detection | ID Tokens |
 |----------|-------------|----------------|----------------|-----------|
 | Google | Full | Yes | `accounts.google.com` | Yes |
-| Azure AD | Full | Yes | `login.microsoftonline.com` | Yes |
+| Azure AD | Full | Yes | `login.microsoftonline.com`, `sts.windows.net` | Yes |
 | Auth0 | Full | Yes | `*.auth0.com` | Yes |
-| Okta | Full | Yes | `*.okta.com` | Yes |
-| Keycloak | Full | Yes | `/auth/realms/` path | Yes |
+| Okta | Full | Yes | `*.okta.com`, `*.oktapreview.com`, `*.okta-emea.com` | Yes |
+| Keycloak | Full | Yes | host containing `keycloak`, or `/realms/` in path (matches both `/auth/realms/` legacy and `/realms/` modern) | Yes |
 | AWS Cognito | Full | Yes | `cognito-idp.*.amazonaws.com` | Yes |
 | GitLab | Full | Yes | `gitlab.com` | Yes |
 | GitHub | OAuth 2.0 Only | No | `github.com` | No |
@@ -353,6 +353,8 @@ allowPrivateIPAddresses: true  # Required for private IPs
    - Roles: User Client Role mapper with "Add to ID token" enabled
    - Groups: Group Membership mapper with "Add to ID token" enabled
 
+See [KEYCLOAK_SETUP_GUIDE.md](KEYCLOAK_SETUP_GUIDE.md) for detailed step-by-step setup instructions, mapper configuration, troubleshooting, and performance optimization.
+
 ---
 
 ## AWS Cognito

docs/REDIS.md

@@ -109,11 +109,11 @@ redis:
 | `writeTimeout` | int | `3` | Write timeout (seconds) |
 | `enableTLS` | bool | `false` | Enable TLS for connections |
 | `tlsSkipVerify` | bool | `false` | Skip TLS certificate verification |
-| `enableCircuitBreaker` | bool | `true` | Enable circuit breaker |
-| `circuitBreakerThreshold` | int | `5` | Failures before circuit opens |
-| `circuitBreakerTimeout` | int | `60` | Circuit reset timeout (seconds) |
-| `enableHealthCheck` | bool | `true` | Enable periodic health checks |
-| `healthCheckInterval` | int | `30` | Health check interval (seconds) |
+| `enableCircuitBreaker` | bool | `false` | Wrap the Redis backend with a circuit breaker. **Recommended `true` in production.** |
+| `circuitBreakerThreshold` | int | `5` | Consecutive failures before the circuit opens (only when `enableCircuitBreaker: true`). |
+| `circuitBreakerTimeout` | int | `60` | Seconds the circuit stays open before allowing a probe (only when `enableCircuitBreaker: true`). |
+| `enableHealthCheck` | bool | `false` | Wrap the Redis backend with periodic health checks. **Recommended `true` in production.** |
+| `healthCheckInterval` | int | `30` | Health check interval in seconds (only when `enableHealthCheck: true`). |
 | `hybridL1Size` | int | `500` | Max items in L1 cache (hybrid mode) |
 | `hybridL1MemoryMB` | int64 | `10` | Max memory for L1 cache in MB |
 
@@ -134,13 +134,21 @@ REDIS_READ_TIMEOUT=3
 REDIS_WRITE_TIMEOUT=3
 REDIS_ENABLE_TLS=false
 REDIS_TLS_SKIP_VERIFY=false
+REDIS_HYBRID_L1_SIZE=500
+REDIS_HYBRID_L1_MEMORY_MB=10
 ```
 
+> Resilience fields (`enableCircuitBreaker`, `enableHealthCheck`,
+> `circuitBreakerThreshold`, `circuitBreakerTimeout`, `healthCheckInterval`)
+> have no environment variable fallback — set them in plugin configuration.
+
+Invalid `cacheMode` values are rejected at plugin startup.
+
 ---
 
 ## Cache Modes
 
-### Memory Mode (Default without Redis)
+### Memory Mode (used when Redis is disabled)
 
 ```yaml
 redis:

docs/TESTING.md

@@ -6,8 +6,8 @@ Comprehensive testing infrastructure for traefikoidc.
 
 | Metric | Value |
 |--------|-------|
-| Test files | 99 |
-| Lines of test code | ~65,500 |
+| Test files | 110 |
+| Lines of test code | ~72,000 |
 | Code coverage | 71.0% |
 | Race conditions | None (all pass with `-race`) |
 

docs/index.html

@@ -90,6 +90,7 @@
                         <a href="#configuration" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 font-medium">Configuration</a>
                         <a href="#deployment" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 font-medium">Deployment</a>
                         <a href="#security" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 font-medium">Security</a>
+                        <a href="#logout" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 font-medium">Logout</a>
                     </div>
                     <div class="flex items-center space-x-4">
                         <button id="theme-toggle" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 p-2 min-w-[44px] min-h-[44px] flex items-center justify-center" aria-label="Toggle theme">
@@ -114,6 +115,7 @@
                     <a href="#configuration" class="block px-3 py-3 text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 hover:bg-gray-50 dark:hover:bg-gray-700 rounded font-medium">Configuration</a>
                     <a href="#deployment" class="block px-3 py-3 text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 hover:bg-gray-50 dark:hover:bg-gray-700 rounded font-medium">Deployment</a>
                     <a href="#security" class="block px-3 py-3 text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 hover:bg-gray-50 dark:hover:bg-gray-700 rounded font-medium">Security</a>
+                    <a href="#logout" class="block px-3 py-3 text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 hover:bg-gray-50 dark:hover:bg-gray-700 rounded font-medium">Logout</a>
                 </div>
             </div>
         </nav>
@@ -193,7 +195,7 @@
                             </div>
                             <div>
                                 <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-1">Dynamic Registration</h3>
-                                <p class="text-sm text-gray-600 dark:text-gray-400">RFC 7591 Dynamic Client Registration for automatic client setup without manual configuration</p>
+                                <p class="text-sm text-gray-600 dark:text-gray-400">RFC 7591 Dynamic Client Registration with Redis storage support for multi-replica deployments</p>
                             </div>
                         </div>
                     </div>
@@ -640,7 +642,7 @@ spec:
                                     </tr>
                                     <tr class="border-b border-gray-100 dark:border-gray-800">
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientSecret</code></td>
-                                        <td class="py-2 px-3">OAuth 2.0 client secret</td>
+                                        <td class="py-2 px-3">OAuth 2.0 client secret. Only required when <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAuthMethod</code> is unset or <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret_post</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret_basic</code>.</td>
                                     </tr>
                                     <tr class="border-b border-gray-100 dark:border-gray-800">
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">sessionEncryptionKey</code></td>
@@ -716,6 +718,11 @@ spec:
                                         <td class="py-2 px-3">86400</td>
                                         <td class="py-2 px-3">Maximum session age in seconds (24 hours default)</td>
                                     </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">maxRefreshTokenAgeSeconds</code></td>
+                                        <td class="py-2 px-3">21600</td>
+                                        <td class="py-2 px-3">Heuristic upper bound on stored refresh-token lifetime (6 hours default). Past this, the plugin treats the RT as expired without contacting the IdP. Set <code>0</code> to disable.</td>
+                                    </tr>
                                     <tr class="border-b border-gray-100 dark:border-gray-800">
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">cookiePrefix</code></td>
                                         <td class="py-2 px-3">_oidc_raczylo_</td>
@@ -746,15 +753,48 @@ spec:
                                         <td class="py-2 px-3">false</td>
                                         <td class="py-2 px-3">Require RFC 7662 introspection for opaque tokens</td>
                                     </tr>
-                                    <tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">disableReplayDetection</code></td>
                                         <td class="py-2 px-3">false</td>
                                         <td class="py-2 px-3">Disable JTI replay detection (for multi-replica without Redis)</td>
                                     </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAuthMethod</code></td>
+                                        <td class="py-2 px-3">client_secret_post</td>
+                                        <td class="py-2 px-3">Selects how the plugin authenticates to the token endpoint. One of <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret_post</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret_basic</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">private_key_jwt</code>.</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionPrivateKey</code></td>
+                                        <td class="py-2 px-3">none</td>
+                                        <td class="py-2 px-3">Inline PEM private key used to sign client assertions for <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">private_key_jwt</code>.</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionKeyPath</code></td>
+                                        <td class="py-2 px-3">none</td>
+                                        <td class="py-2 px-3">Path to a PEM private key file. Alternative to <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionPrivateKey</code>.</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionKeyID</code></td>
+                                        <td class="py-2 px-3">none</td>
+                                        <td class="py-2 px-3">JWS <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">kid</code> header value. Required when <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAuthMethod</code> is <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">private_key_jwt</code>.</td>
+                                    </tr>
+                                    <tr>
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionAlg</code></td>
+                                        <td class="py-2 px-3">RS256</td>
+                                        <td class="py-2 px-3">Signing algorithm for the client assertion. One of <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">RS256</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">RS384</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">RS512</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">PS256</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">PS384</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">PS512</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">ES256</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">ES384</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">ES512</code>.</td>
+                                    </tr>
                                 </tbody>
                             </table>
                         </div>
                     </div>
+                    <div class="glass p-6 rounded-xl">
+                        <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-3">Private Key JWT (RFC 7523)</h3>
+                        <p class="text-gray-600 dark:text-gray-400 mb-3 text-sm">Use this when your IdP (Entra ID, Okta, Auth0, Keycloak) pressures short-lived secrets, or when policy mandates secretless service-to-service authentication. The plugin signs a 60-second assertion with the configured private key and sends it as <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_assertion</code> instead of <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret</code>. Public-key registration on the IdP replaces shared-secret rotation. See <a href="https://www.rfc-editor.org/rfc/rfc7523" target="_blank" rel="noopener" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 underline">RFC 7523</a> and <a href="https://github.com/lukaszraczylo/traefikoidc/issues/135" target="_blank" rel="noopener" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 underline">issue #135</a>.</p>
+                        <pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto text-sm"><code>clientAuthMethod: private_key_jwt
+clientAssertionKeyPath: /etc/traefik/oidc-client.pem
+clientAssertionKeyID: my-client-key-2026
+# clientSecret no longer required</code></pre>
+                    </div>
                     <div class="glass p-6 rounded-xl">
                         <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-3">Example: Google Workspace with Domain Restriction</h3>
 
@@ -856,7 +896,54 @@ spec:
                                     <tr>
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">redis.enableTLS</code></td>
                                         <td class="py-2 px-3">false</td>
-                                        <td class="py-2 px-3">Enable TLS for Redis connections</td>
+                                        <td class="py-2 px-3">Enable TLS for Redis connections (e.g. AWS ElastiCache in-transit encryption)</td>
+                                    </tr>
+                                    <tr>
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">redis.tlsSkipVerify</code></td>
+                                        <td class="py-2 px-3">false</td>
+                                        <td class="py-2 px-3">Skip TLS server certificate verification (testing only; not recommended in production)</td>
+                                    </tr>
+                                </tbody>
+                            </table>
+                        </div>
+                    </div>
+                    <div class="glass p-6 rounded-xl">
+                        <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-4">Dynamic Client Registration (RFC 7591)</h3>
+                        <p class="text-gray-600 dark:text-gray-400 mb-3 text-sm">Automatically register your application with the OIDC provider. Supports Redis storage for multi-replica deployments:</p>
+                        <div class="overflow-x-auto mb-4">
+                            <table class="w-full text-sm">
+                                <thead>
+                                    <tr class="border-b border-gray-200 dark:border-gray-700">
+                                        <th class="text-left py-2 px-3 text-gray-900 dark:text-gray-100">Parameter</th>
+                                        <th class="text-left py-2 px-3 text-gray-900 dark:text-gray-100">Default</th>
+                                        <th class="text-left py-2 px-3 text-gray-900 dark:text-gray-100">Description</th>
+                                    </tr>
+                                </thead>
+                                <tbody class="text-gray-600 dark:text-gray-400">
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.enabled</code></td>
+                                        <td class="py-2 px-3">false</td>
+                                        <td class="py-2 px-3">Enable dynamic client registration</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.persistCredentials</code></td>
+                                        <td class="py-2 px-3">true</td>
+                                        <td class="py-2 px-3">Persist registered credentials across restarts</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.storageBackend</code></td>
+                                        <td class="py-2 px-3">auto</td>
+                                        <td class="py-2 px-3">Storage backend: <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">file</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">redis</code>, or <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">auto</code> (uses Redis if available)</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.redisKeyPrefix</code></td>
+                                        <td class="py-2 px-3">dcr:creds:</td>
+                                        <td class="py-2 px-3">Redis key prefix for DCR credentials</td>
+                                    </tr>
+                                    <tr>
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">dynamicClientRegistration.clientMetadata.redirect_uris</code></td>
+                                        <td class="py-2 px-3">-</td>
+                                        <td class="py-2 px-3">Redirect URIs for the registered client (required)</td>
                                     </tr>
                                 </tbody>
                             </table>
@@ -1177,6 +1264,71 @@ spec:
             </div>
         </section>
 
+        <!-- IdP-Initiated Logout Section -->
+        <section id="logout" class="py-12 sm:py-16 md:py-20 bg-white dark:bg-gray-900 theme-transition">
+            <div class="max-w-6xl mx-auto px-4 sm:px-6">
+                <div class="text-center mb-8 sm:mb-12">
+                    <h2 class="text-2xl sm:text-3xl md:text-4xl font-bold text-gray-900 dark:text-gray-100 mb-3 sm:mb-4">IdP-Initiated Logout</h2>
+                    <p class="text-base sm:text-lg text-gray-600 dark:text-gray-300 px-4">Support for OIDC Back-Channel and Front-Channel Logout specifications</p>
+                </div>
+                <div class="max-w-4xl mx-auto">
+                    <div class="grid md:grid-cols-2 gap-6 mb-8">
+                        <div class="glass p-6 rounded-xl">
+                            <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-4 flex items-center">
+                                <i class="fas fa-server mr-2 text-blue-500"></i>
+                                Back-Channel Logout
+                            </h3>
+                            <p class="text-gray-600 dark:text-gray-400 text-sm mb-4">
+                                Server-to-server logout notification. The IdP sends a signed JWT (logout_token) directly to your application when a user logs out.
+                            </p>
+                            <ul class="text-gray-600 dark:text-gray-400 space-y-2 text-sm">
+                                <li>&#8226; Signed JWT logout tokens</li>
+                                <li>&#8226; Session ID (sid) based invalidation</li>
+                                <li>&#8226; Subject (sub) based invalidation</li>
+                                <li>&#8226; Works behind firewalls</li>
+                            </ul>
+                        </div>
+                        <div class="glass p-6 rounded-xl">
+                            <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-4 flex items-center">
+                                <i class="fas fa-browser mr-2 text-purple-500"></i>
+                                Front-Channel Logout
+                            </h3>
+                            <p class="text-gray-600 dark:text-gray-400 text-sm mb-4">
+                                Browser-based logout via iframe. The IdP embeds an iframe pointing to your logout endpoint during user logout.
+                            </p>
+                            <ul class="text-gray-600 dark:text-gray-400 space-y-2 text-sm">
+                                <li>&#8226; Iframe-based session termination</li>
+                                <li>&#8226; Immediate cookie invalidation</li>
+                                <li>&#8226; Simple GET request handling</li>
+                                <li>&#8226; Issuer validation</li>
+                            </ul>
+                        </div>
+                    </div>
+                    <div class="glass p-6 rounded-xl">
+                        <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-4">Configuration Example</h3>
+                        <pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto text-sm"><code>http:
+  middlewares:
+    oidc-auth:
+      plugin:
+        traefikoidc:
+          # ... other OIDC configuration ...
+
+          # Back-Channel Logout (server-to-server)
+          enableBackchannelLogout: true
+          backchannelLogoutURL: "/backchannel-logout"
+
+          # Front-Channel Logout (browser-based)
+          enableFrontchannelLogout: true
+          frontchannelLogoutURL: "/frontchannel-logout"</code></pre>
+                        <p class="text-gray-600 dark:text-gray-400 text-sm mt-4">
+                            Configure your IdP with the full URLs (e.g., <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">https://your-app.example.com/backchannel-logout</code>). 
+                            When a user logs out from the IdP, all their sessions across your applications will be invalidated.
+                        </p>
+                    </div>
+                </div>
+            </div>
+        </section>
+
         <!-- Why Choose Section -->
         <section class="py-12 sm:py-16 md:py-20 bg-gray-50 dark:bg-gray-800 theme-transition">
             <div class="max-w-6xl mx-auto px-4 sm:px-6">

docs/superpowers/specs/2026-05-18-bearer-token-auth-design.md

@@ -0,0 +1,459 @@
+# Bearer Token Authentication — Design Spec
+
+- **Date**: 2026-05-18
+- **Status**: Design — pending implementation plan
+- **Supersedes**: PR #93 (broken implementation; recommended to close in favour of this design)
+
+## 1. Summary
+
+Add an opt-in path that lets API clients (machine-to-machine) authenticate by presenting a signed access token in the `Authorization: Bearer <token>` header, bypassing the cookie-based OIDC redirect flow. Identity, roles, and authorization checks remain consistent with the existing cookie path; the only thing that changes is how the principal is established for that single request.
+
+The feature is implemented by extracting a shared `forwardAuthorized` pipeline from the existing `processAuthorizedRequest`, introducing a `principal` value type, and adding a small bearer-specific entrypoint that builds a principal directly from a verified JWT — without synthesising a fake `SessionData`.
+
+## 2. Motivation
+
+PR #93 attempted this feature by building an in-memory `SessionData` from JWT claims and reusing `processAuthorizedRequest`. The approach has three latent defects:
+
+1. The synthetic session omits `mainSession.Values["user_identifier"]`. `processAuthorizedRequest` reads it via `GetUserIdentifier()`; when empty it bails to `defaultInitiateAuthentication` and issues an OIDC redirect. The feature is non-functional in practice despite the unit test passing.
+2. `verifyToken` accepts both ID tokens (audience match against `clientID`) and access tokens. ID tokens are not API credentials; treating them as such is a classic token-confusion vector.
+3. `verifyToken` adds JTI to the replay blacklist on first verify. Once the verified-token cache evicts, subsequent reuse of the same bearer token triggers a false-positive replay rejection.
+
+Rather than patch a synthetic-session approach that will keep generating bugs as `SessionData` evolves, this spec replaces it with a cleaner abstraction where session lifecycle and post-auth header injection live in separate units.
+
+## 3. Goals
+
+- Accept `Authorization: Bearer <jwt>` from M2M clients, validate the token, and forward the request downstream with identity headers populated.
+- Enforce the same `allowedRolesAndGroups` policy as the cookie path.
+- Default-off; safe defaults when enabled (audience required, ID tokens rejected, identifier sanitised).
+- No behavioural change to the cookie path. Existing tests must continue to pass without modification.
+
+## 4. Non-Goals
+
+- Human-user / browser flows. Bearer is M2M-only in this iteration.
+- Pure opaque access tokens on the bearer path. Tokens must be JWTs; introspection (RFC 7662) is supported *on top of* JWT verification for revocation state, not as a substitute for it.
+- mTLS, API keys, or any other auth method. The `principal` abstraction enables them later, but they are not delivered here.
+- Per-route bearer configuration. Single middleware-wide setting.
+
+## 5. Decided Requirements
+
+| Topic | Decision |
+|---|---|
+| Consumer type | Machine-to-machine (M2M) only |
+| Token format | JWT only (signature, issuer, audience, exp) |
+| Audience | Mandatory when feature enabled; startup fails if `Audience == ""` |
+| Token type | Access tokens only; ID tokens explicitly rejected |
+| Revocation | JWT-only verification by default; introspection (RFC 7662) opt-in via existing `RequireTokenIntrospection` |
+| Identity claim | New `BearerIdentifierClaim` config (string, default `"sub"`). Bearer path reads this claim exclusively; does NOT use `UserIdentifierClaim` (which defaults to `"email"` and drives the cookie path). Resolved value must be a non-empty string. `sub` is mandatory per `jwt.go:416` regardless, so even with a different `BearerIdentifierClaim` the token must still carry a valid `sub`. Decoupling avoids the M2M-vs-human-user identity-claim conflict and the email-spoofing footgun. |
+| Identifier sanitisation | Reject value containing any `unicode.IsControl` char, any Unicode bidi-override (U+202A–U+202E, U+2066–U+2069), leading/trailing whitespace, commas, semicolons, equals signs. Max length 256 bytes. |
+| Token classifier | **Reuse existing `detectTokenType(jwt, token)` at `token_manager.go:187-303`** which already handles `nonce`, `typ: at+jwt`, `token_use`, `scope`, and aud-vs-clientID priority. Bearer path rejects any token where `detectTokenType == true` (ID token). Do not invent a parallel classifier. |
+| Algorithm pinning | Hard-pin `alg ∈ {RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512}`, enforced **before** JWKS lookup on the bearer path. Prevents wasted JWKS fetches for `alg=none`/HS attacker probes. |
+| `kid` hardening | `kid` ≤ 256 bytes, charset `[A-Za-z0-9._\-=]`. Reject before JWKS lookup. |
+| Token age | Bearer path enforces `now - iat <= MaxTokenAgeSeconds` (default 86400 / 24h, configurable). Cookie path unchanged. |
+| Multi-audience policy | If `aud` is an array (length > 1), require `azp` claim to be present and equal to `clientID`. Single-string `aud` unaffected. |
+| Mixed bearer + cookie precedence | **Cookie wins by default** when both are presented (safer for browser scenarios). Operator opt-in: `BearerOverridesCookie=true` to flip. Either way, a warning is logged on the request. |
+| Bearer + excluded URL | `Authorization` header is **stripped** before forwarding when the request hits an excluded URL. Prevents bearer leaking into public endpoints' downstream logs and prevents recon via excluded paths. |
+| Per-source bearer 401 throttle | New sharded cache `failedBearerAttempts` keyed by client IP. After N (default 20) consecutive 401s from one IP within 1 minute, reject further bearer requests from that IP with 429 for 60s. Applied BEFORE `verifyToken` to deny JWKS amplification. |
+| `Authorization` header passthrough | New `StripAuthorizationHeader` config, default `true` |
+| Roles/groups gating | Same `allowedRolesAndGroups` rules as cookie path |
+| Default state | `EnableBearerAuth` = `false` |
+| JTI replay marking | Suppressed on bearer path; cookie path unchanged |
+| Failure response shape | 401 with generic body; `WWW-Authenticate: Bearer error="invalid_token"` per RFC 6750 |
+| Introspection endpoint outage | 503 (distinguishes infra outage from token rejection) |
+| Mixed bearer + cookie | Bearer wins; cookie ignored on that request |
+| SSE/WS bypass + bearer | Bypass paths keep cookie-only check; bearer header ignored on SSE/WS |
+
+## 6. Architecture
+
+```
+                ┌──────────────────┐
+   HTTP req ──► │   ServeHTTP      │  (existing entry; adds bearer detection)
+                └─────────┬────────┘
+              ┌───────────┴────────────┐
+              ▼                        ▼
+        cookie / session         bearer (Authorization: Bearer …)
+              │                        │
+              ▼                        ▼
+    ┌────────────────┐        ┌────────────────────┐
+    │ buildPrincipal │        │ buildPrincipal     │
+    │ FromSession()  │        │ FromBearerToken()  │
+    └────────┬───────┘        └─────────┬──────────┘
+             │     produces *principal  │
+             └──────────────┬───────────┘
+                            ▼
+              ┌────────────────────────────┐
+              │ forwardAuthorized(rw,req,p)│  (shared pipeline)
+              │  • roles/groups gate       │
+              │  • header injection        │
+              │  • header templates        │
+              │  • security headers        │
+              │  • cookie stripping        │
+              │  • next.ServeHTTP          │
+              └────────────────────────────┘
+```
+
+**Invariant**: `forwardAuthorized` never touches session storage. Session-specific concerns (Save, IsDirty, backchannel-logout invalidation) stay inside `processAuthorizedRequest` around the call to `forwardAuthorized`.
+
+**Feature gate**: when `EnableBearerAuth == false`, the bearer-detection check in `ServeHTTP` is a no-op. Existing deployments observe byte-identical behaviour.
+
+## 7. Components
+
+### 7.1 `principal` type (new file `principal.go`)
+
+```go
+type principalSource int
+
+const (
+    sourceSession principalSource = iota
+    sourceBearer
+)
+
+type principal struct {
+    Identifier   string                 // drives X-Forwarded-User
+    Email        string                 // optional, "" for M2M
+    Subject      string                 // sub claim
+    ClientID     string                 // azp / client_id, M2M caller
+    Claims       map[string]interface{} // raw claims for templates / groups
+    AccessToken  string                 // for X-Auth-Request-Token (gated by minimalHeaders)
+    IDToken      string                 // "" on bearer path
+    RefreshToken string                 // "" on bearer path
+    Source       principalSource
+}
+```
+
+Pure data. No methods that mutate it. No I/O. No manager pointer.
+
+### 7.2 `buildPrincipalFromSession(*SessionData) *principal` (new in `principal.go`)
+
+Read-only adapter over existing `SessionData` getters: `GetUserIdentifier`, `GetEmail`, `GetAccessToken`, `GetIDToken`, `GetRefreshToken`, cached claims via `GetIDTokenClaims`. Does not write back to the session. This is the only function that still knows about `SessionData`.
+
+### 7.3 `buildPrincipalFromBearerToken(token string) (*principal, error)` (new in `bearer_auth.go`)
+
+1. **Length / format guards**: `len(token) <= AccessTokenConfig.MaxLength`, exactly two dots, non-empty after trim.
+2. **Parse header for early alg/kid pinning** (without trusting payload): decode JOSE header; reject if `alg` ∉ asymmetric allowlist; reject if `kid` missing, > 256 bytes, or contains chars outside `[A-Za-z0-9._\-=]`. This happens **before** JWKS lookup so attacker noise doesn't amplify into JWKS fetches.
+3. **Per-IP 401 throttle check**: if this IP is in the `failedBearerAttempts` penalty box, return 429 immediately.
+4. `t.verifyToken(token, verifyOpts{skipReplayMarking: true})` — reuses signature, issuer, audience, expiration, JTI Get (replay detection). The `skipReplayMarking` flag gates ONLY the JTI Set at `token_manager.go:108-143`; the JTI Get at `token_manager.go:44-47, 80-89` remains active so revoked tokens (via `RevokeToken` adding to blacklist) are still rejected.
+5. **Re-parse claims** (`parseJWT(token)` is cheap and already done internally; reuse via a single decode if practical).
+6. **Token-type guard**: call existing `detectTokenType(jwt, token)` (`token_manager.go:187-303`). Reject when it returns `true` (ID token). Belt-and-braces: also reject if `claims["nonce"]` is a non-empty string or `claims["token_use"] == "id"`.
+7. **Multi-audience hardening**: if `claims["aud"]` is a `[]interface{}` with length > 1, require `claims["azp"]` to be a non-empty string equal to `t.clientID`; reject otherwise.
+8. **`iat` upper-age bound**: reject when `time.Now().Unix() - int64(claims["iat"].(float64)) > MaxTokenAgeSeconds` (default 86400).
+9. **Optional introspection**: if `requireTokenIntrospection` is set, call `introspectToken`; reject if `active == false` (401); surface 503 on transport failure. Bearer-path introspection cache TTL is capped at 60s (not 5min) to keep the "real-time revocation" promise close to true.
+10. **Identifier resolution**: read `t.bearerIdentifierClaim` (defaults to `"sub"`); do NOT use `t.userIdentifierClaim` (cookie path's setting, default `email`). The bearer path does NOT fall back to other claims because `jwt.Verify` already enforces non-empty `sub` (`jwt.go:416-419`). Empty/missing identifier → 401.
+11. **Identifier sanitisation**: trim, then reject if length > 256 OR contains any of: `unicode.IsControl`, bidi-override (U+202A–U+202E, U+2066–U+2069), `,`, `;`, `=`.
+12. Return `&principal{ Source: sourceBearer, … }`.
+
+On any failure path: increment the per-IP `failedBearerAttempts` counter; return the appropriate HTTP status (401 / 403 / 429 / 503) without revealing the failure reason in the response body. Reason is logged at debug only, with the identifier (if resolved) hashed via SHA-256 truncated to 8 hex chars.
+
+### 7.4 `forwardAuthorized(rw, req, *principal)` (new in `middleware.go`, extracted)
+
+The shared post-auth pipeline. Lifted verbatim from the existing `processAuthorizedRequest`:
+
+1. Roles/groups extraction via existing `extractGroupsAndRolesFromClaims`.
+2. `allowedRolesAndGroups` gate (existing logic).
+3. Inject `X-Forwarded-User`, `X-User-Groups`, `X-User-Roles`.
+4. Inject `X-Auth-Request-*` (gated by `minimalHeaders`).
+5. Header templates.
+6. Security headers.
+7. Cookie strip when `stripAuthCookies`.
+8. **New**: `Authorization` header strip when `stripAuthorizationHeader` AND `principal.Source == sourceBearer`.
+9. `t.next.ServeHTTP(rw, req)`.
+
+Does not call `Save`, does not check `IsDirty`. Session persistence stays with the cookie-path caller.
+
+### 7.5 `handleBearerRequest(rw, req)` (new in `bearer_auth.go`)
+
+```
+1. Detect "Authorization: Bearer <token>" (case-insensitive prefix).
+2. token = TrimSpace(authHeader[7:]); reject empty.
+3. p, err := buildPrincipalFromBearerToken(token).
+   On err → 401 with WWW-Authenticate, log reason at debug.
+4. forwardAuthorized(rw, req, p).
+```
+
+Target: ~40 lines.
+
+### 7.6 Refactor of `processAuthorizedRequest` (modify `middleware.go`)
+
+Splits along the principal boundary:
+- Session-specific part (backchannel-logout invalidation, `IsDirty` / `Save`) stays in `processAuthorizedRequest`.
+- Everything else moves to `forwardAuthorized`.
+- `processAuthorizedRequest` ends with `forwardAuthorized(rw, req, buildPrincipalFromSession(session))`.
+
+### 7.7 `verifyOpts` extension to `verifyToken` (modify `token_manager.go`)
+
+Add a parameter struct:
+```go
+type verifyOpts struct {
+    skipReplayMarking bool // suppress JTI Set (token_manager.go:108-143); blacklist Get stays active
+}
+```
+
+Both the type and field are unexported (internal-only knob). Signature change: `verifyToken(token string)` becomes `verifyToken(token string, opts verifyOpts)`. Existing callers pass `verifyOpts{}` (zero value = current behaviour). Bearer path passes `verifyOpts{skipReplayMarking: true}`.
+
+**Critical semantics — must be reflected in implementation and tests:**
+- `skipReplayMarking` only gates the **Set** at `token_manager.go:108-143` (the call adding the JTI to the blacklist and replay cache).
+- The blacklist **Get** at `token_manager.go:44-47, 80-89` stays unconditionally active on the bearer path. Tokens revoked via `RevokeToken` (which adds the JTI to the blacklist) MUST still be rejected on the bearer path.
+- Must NOT be implemented by mutating `t.disableReplayDetection` (struct field) — that would create a cross-request race that disables replay protection globally.
+
+A targeted regression test exercises: bearer token verified once → admin calls `RevokeToken` adding the JTI to the blacklist → same token replayed → 401.
+
+### 7.8 Config additions (modify `settings.go`)
+
+```go
+EnableBearerAuth              bool   `json:"enableBearerAuth,omitempty"`
+BearerIdentifierClaim         string `json:"bearerIdentifierClaim,omitempty"`
+StripAuthorizationHeader      bool   `json:"stripAuthorizationHeader,omitempty"`
+BearerEmitWWWAuthenticate     bool   `json:"bearerEmitWWWAuthenticate,omitempty"`
+BearerOverridesCookie         bool   `json:"bearerOverridesCookie,omitempty"`
+MaxTokenAgeSeconds            int64  `json:"maxTokenAgeSeconds,omitempty"`
+MaxIdentifierLength           int    `json:"maxIdentifierLength,omitempty"`
+BearerFailureThreshold        int    `json:"bearerFailureThreshold,omitempty"`
+BearerFailureWindowSeconds    int    `json:"bearerFailureWindowSeconds,omitempty"`
+BearerFailurePenaltySeconds   int    `json:"bearerFailurePenaltySeconds,omitempty"`
+```
+
+Defaults (applied in `CreateConfig` for the bearer-related fields; values >0 only honoured when `EnableBearerAuth=true`):
+- `EnableBearerAuth`: `false`.
+- `BearerIdentifierClaim`: `"sub"`.
+- `StripAuthorizationHeader`: `true`.
+- `BearerEmitWWWAuthenticate`: `true` (RFC 6750 hint enabled by default; flip to false if recon-exposure is a concern).
+- `BearerOverridesCookie`: `false` (cookie wins when both present; flip to `true` for the legacy/industry-default behaviour).
+- `MaxTokenAgeSeconds`: `86400` (24h upper bound on `iat`).
+- `MaxIdentifierLength`: `256`.
+- `BearerFailureThreshold`: `20` (consecutive 401s per IP before throttle).
+- `BearerFailureWindowSeconds`: `60`.
+- `BearerFailurePenaltySeconds`: `60` (429 reply for this long after threshold tripped).
+
+### 7.9 Startup validation (modify `main.go` `New()`)
+
+- `EnableBearerAuth && Audience == ""` → fatal error.
+- `EnableBearerAuth && !StrictAudienceValidation` → warning log (recommended hardening).
+- `EnableBearerAuth && BearerIdentifierClaim == "email"` → fatal error (the bearer path is M2M and an `email` identifier without `email_verified` enforcement is a spoofing vector; default `BearerIdentifierClaim=sub` avoids this; explicit override to `email` is rejected).
+- `EnableBearerAuth && MaxTokenAgeSeconds <= 0` → reset to default 86400 with info log.
+- `EnableBearerAuth && BearerFailureThreshold <= 0` → reset to default 20 with info log.
+
+## 8. Data Flow
+
+### 8.1 Bearer path
+
+```
+ServeHTTP entry (pre-init paths unchanged: logout, backchannel, frontchannel, excluded URLs, SSE/WS bypass)
+  │
+  ├─ enableBearerAuth == false?  → fall through to cookie path
+  │
+  └─ enableBearerAuth == true AND Authorization starts with "Bearer "
+       │
+       ▼
+  handleBearerRequest
+       │
+       ├─ format guards (empty, length, segment count)
+       │
+       ▼
+  verifyToken(token, verifyOpts{SkipReplayMarking: true})
+       │  signature, issuer, audience (strict), exp
+       │
+       ▼
+  classifyToken(claims) → reject ID tokens
+       │
+       ▼
+  if requireTokenIntrospection: introspectToken → active check
+       │
+       ▼
+  resolveIdentifier(claims) → sanitiseIdentifier
+       │
+       ▼
+  principal{Source: sourceBearer, …}
+       │
+       ▼
+  forwardAuthorized(rw, req, principal)
+       │
+       ├─ roles/groups gate (403 on deny)
+       ├─ header injection
+       ├─ header templates
+       ├─ security headers
+       ├─ strip OIDC cookies (existing)
+       ├─ strip Authorization header (new, when configured)
+       └─ next.ServeHTTP(rw, req)
+```
+
+### 8.2 Cookie path (refactored, semantically unchanged)
+
+```
+processAuthorizedRequest
+  1. Session validity / backchannel-logout invalidation (unchanged).
+  2. principal := buildPrincipalFromSession(session).
+  3. forwardAuthorized(rw, req, principal).
+  4. if session.IsDirty(): session.Save().
+```
+
+## 9. Error Handling
+
+| Trigger | Status | Body | WWW-Authenticate | Debug log reason |
+|---|---|---|---|---|
+| Empty bearer after prefix | 401 | `Unauthorized` | `Bearer error="invalid_request"` | empty bearer token |
+| Token over MaxLength | 401 | `Unauthorized` | `Bearer error="invalid_token"` | token exceeds max length |
+| Not a 3-segment JWT | 401 | `Unauthorized` | `Bearer error="invalid_token"` | malformed JWT |
+| Disallowed `alg` (e.g. none, HS*) | 401 | `Unauthorized` | `Bearer error="invalid_token"` | unsupported alg |
+| Missing/oversized/bad-charset `kid` | 401 | `Unauthorized` | `Bearer error="invalid_token"` | invalid kid |
+| Signature / issuer / aud / exp fail | 401 | `Unauthorized` | `Bearer error="invalid_token"` | reason from verifyToken (category only) |
+| `iat` older than MaxTokenAgeSeconds | 401 | `Unauthorized` | `Bearer error="invalid_token"` | token too old (iat outside age bound) |
+| Multi-aud without matching `azp` | 401 | `Unauthorized` | `Bearer error="invalid_token"` | multi-aud token without azp match |
+| Detected as ID token | 401 | `Unauthorized` | `Bearer error="invalid_token"` | ID tokens not accepted on bearer path |
+| JTI blacklisted (revoked) | 401 | `Unauthorized` | `Bearer error="invalid_token"` | token JTI in blacklist |
+| Introspection `active=false` | 401 | `Unauthorized` | `Bearer error="invalid_token"` | token inactive at IdP |
+| Introspection endpoint failure | 503 | `Service Unavailable` | (none) | introspection unavailable |
+| Identifier claim missing/empty | 401 | `Unauthorized` | `Bearer error="invalid_token"` | no identifier claim |
+| Identifier fails sanitisation | 401 | `Unauthorized` | `Bearer error="invalid_token"` | invalid identifier characters |
+| Per-IP failure threshold tripped | 429 | `Too Many Requests` | (none); `Retry-After: <BearerFailurePenaltySeconds>` | source IP in penalty box |
+| Roles/groups not allowed | 403 | `Access denied` | (none) | user not in allowedRolesAndGroups |
+
+Responses never include token contents, never include the raw failure reason, and never set `Location` headers (API clients cannot follow redirects).
+
+## 10. Edge Cases
+
+1. **Both bearer header and cookie session present.** Cookie wins by default (safer against browser/extension/proxy bearer injection). `BearerOverridesCookie=true` flips to bearer-wins. Either way: WARN log includes both source markers so operators can audit.
+2. **`Authorization: Basic …`.** Not bearer; cookie path runs as today.
+3. **`Authorization: Bearer ` (trailing space, no value).** Empty after trim → 401.
+4. **Mixed-case prefix (`bearer`, `BEARER`, `BeArEr`).** Case-insensitive prefix check; token value preserved verbatim.
+5. **Multiple `Authorization` headers.** Use only the first (Go `http.Header.Get` default). Documented.
+6. **Bearer during OIDC init wait.** Bearer requests also block on init: we need `issuerURL`, `audience`, JWKs ready. If init fails, bearer requests return 503 just like cookie requests.
+7. **SSE / WebSocket bypass with bearer.** Bypass paths keep cookie-only behaviour. Operators who want bearer on streaming endpoints must remove SSE/WS bypass. Documented.
+8. **Logout endpoint with bearer.** Logout runs before bearer detection. Treated as cookie-session logout; bearer token revocation requires IdP-side action.
+9. **Excluded URLs with bearer.** Bypass excluded URLs as today; bearer not validated on excluded paths. ADDITIONALLY: `Authorization: Bearer` is stripped from the request before forwarding so the token can't leak into the excluded endpoint's downstream logs / metrics scrapers / health checks.
+10. **Concurrent identical bearer requests.** Existing `tokenCache` is concurrency-safe; no new locking.
+11. **Client rotates token between requests.** Independent verification per token; independent cache entries.
+12. **Clock skew.** Use existing `jwt.Verify` leeway. (If absent, add ±30s as a separate change; out of scope here.)
+
+## 11. Testing Strategy
+
+### 11.1 Integration tests (new `bearer_auth_test.go`)
+
+Table-driven test against a real `httptest.Server` and the full `ServeHTTP` flow. Coverage matrix:
+
+- Valid access token + allowed roles → 200, `next` ran, `X-Forwarded-User` set.
+- Valid token without configured roles → 200.
+- Wrong audience, expired, tampered signature → 401, `next` did not run.
+- ID token presented → 401 (`ID tokens not accepted`).
+- Malformed JWT (2 segments) → 401.
+- Oversized token (> MaxLength) → 401.
+- Empty bearer → 401.
+- Missing identifier claim → 401.
+- Identifier containing `\r\n` → 401.
+- `allowedRolesAndGroups` mismatch → 403.
+- `allowedRolesAndGroups` match → 200.
+- `EnableBearerAuth=false` + bearer header → cookie path runs (302 to `/authorize`).
+- Bearer + valid cookie session → bearer wins, 200.
+- `StripAuthorizationHeader=true` → downstream sees no `Authorization`.
+- `StripAuthorizationHeader=false` → downstream sees `Authorization`.
+- Case variants (`bearer`, `BEARER`) → 200.
+- SSE bypass + bearer → cookie-only check applies (bearer ignored).
+- **Replay regression**: same token 1000 times in a row → all 200.
+- **Cache-evict regression**: same token, force-evict `tokenCache` between iterations (call `tokenCache.Delete` directly), replay → still 200 (verifies `skipReplayMarking` doesn't poison the blacklist).
+- **Revocation-while-bearer regression**: bearer token verified once → admin calls `RevokeToken` adding JTI to blacklist → same token presented → 401 (verifies blacklist Get stays active on bearer path even with `skipReplayMarking` set).
+- **Alg-pin: token signed with `alg=none`** → 401, no JWKS fetch happens (verify with a counting mock).
+- **`kid` injection: 50KB random kid** → 401 immediately, no JWKS fetch.
+- **Per-IP throttle**: 21 bad bearer requests from same IP within 1 minute → 22nd returns 429 + Retry-After.
+- **`iat` upper-age**: token with `iat = now - 25h` → 401 (older than 24h default).
+- **Multi-aud without azp**: aud = `["a", "b"]`, no azp → 401.
+- **Multi-aud with matching azp**: aud = `["api-aud", "other"]`, azp = clientID → 200.
+- **Identifier with bidi-override**: sub contains U+202E → 401.
+- **Identifier with comma**: sub = `"alice,bob"` → 401.
+- **Identifier over 256 bytes** → 401.
+- **`UserIdentifierClaim=email` at startup with EnableBearerAuth=true** → startup fails.
+- **Excluded URL + bearer**: bearer header presented on excluded URL → request forwarded, downstream sees no `Authorization` header (stripped).
+
+### 11.2 Unit tests (in `bearer_auth_test.go`)
+
+- `classifyToken`: ID-token detection, access-token detection by `scope`/`scp`/`token_use`, ambiguous → reject.
+- `resolveIdentifier`: precedence (`userIdentifierClaim` → `sub` → `client_id`/`azp`); missing → error; empty string → error.
+- `sanitizeIdentifier`: rejects all `unicode.IsControl`; accepts email/sub-style values.
+
+### 11.3 Introspection tests (`bearer_auth_introspection_test.go`)
+
+- Token valid + introspection `active=true` → 200.
+- Token valid + introspection `active=false` → 401.
+- Introspection endpoint 500 → 503.
+- Second request hits introspection cache (no second HTTP call).
+
+### 11.4 Startup validation tests (extend `settings_test.go` / `main_test.go`)
+
+- `EnableBearerAuth=true, Audience=""` → `New()` errors.
+- `EnableBearerAuth=true, StrictAudienceValidation=false` → succeeds with warning.
+- `EnableBearerAuth=false` → no validation; existing tests untouched.
+
+### 11.5 Cookie-path regression suite
+
+- All existing `TestServeHTTP_*` tests in `main_servehttp_test.go` pass unmodified.
+- Add: cookie session, `EnableBearerAuth=true`, no bearer header → identical behaviour to baseline.
+- Add: dirty session still triggers `Save()` after refactor.
+
+### 11.6 Principal invariants
+
+- `buildPrincipalFromSession`: `Source == sourceSession`; `IDToken` / `RefreshToken` populated when present in session.
+- `buildPrincipalFromBearerToken`: `Source == sourceBearer`; `IDToken == ""`, `RefreshToken == ""`.
+- `forwardAuthorized` produces identical headers for equivalent principals regardless of source.
+
+### 11.7 Coverage gate
+
+- New code in `bearer_auth.go` and `principal.go`: ≥ 90% line coverage.
+- `forwardAuthorized` coverage ≥ existing `processAuthorizedRequest` coverage baseline.
+
+### 11.8 Out of scope (follow-ups)
+
+- Load test of bearer vs cookie hot path.
+- Fuzzing the JWT parser.
+- Additional auth methods (mTLS, API keys) — design enables them, but they are separate work.
+
+## 12. Migration / Rollout
+
+Default-off. Existing deployments observe no behavioural change. Operators opt in by setting:
+
+```yaml
+enableBearerAuth: true
+audience: https://api.example.com   # required when bearer enabled
+# optional:
+stripAuthorizationHeader: true       # default
+requireTokenIntrospection: false     # default; set true for real-time revocation
+userIdentifierClaim: client_id       # optional override; defaults to sub fallback chain
+```
+
+Documentation: update `docs/CONFIGURATION.md` with a bearer-auth section, and add a new `docs/BEARER_AUTH.md` covering the security model, threat assumptions (token issuer is trusted; audience must be set; bearer means trust the issuer's revocation policy unless introspection enabled), and recommended configurations for common IdPs.
+
+## 13. Security Considerations
+
+| Concern | Mitigation |
+|---|---|
+| Token confusion (ID token used as bearer) | Reuse `detectTokenType` (`token_manager.go:187-303`) which checks `nonce`, `typ: at+jwt`, `token_use`, `scope`, aud-vs-clientID. Belt-and-braces: explicit `nonce` + `token_use == "id"` rejection on top. |
+| Audience confusion (token for service B accepted by A) | `Audience` mandatory at startup; verified via existing `VerifyJWTSignatureAndClaims`; multi-aud tokens require matching `azp == clientID`. |
+| Replay-via-blacklist false positive | `verifyOpts{skipReplayMarking: true}` on bearer path. Gates ONLY the Set; the Get stays so revoked tokens still fail. |
+| Revocation lag | Optional RFC 7662 introspection. Bearer-path introspection cache TTL capped at 60s. Set `RequireTokenIntrospection=true` for real-time revocation. |
+| `alg`-confusion / `alg=none` attacks | Hard-pin asymmetric allowlist at bearer entry, **before** JWKS fetch. Prevents wasted upstream calls and locks out HS/none probes. |
+| `kid` injection / JWKS amplification | `kid` length cap (256 bytes) + charset allowlist enforced at bearer entry. |
+| Bearer 401 brute-force / oracle | Per-IP `failedBearerAttempts` cache; configurable threshold + penalty box returning 429 + `Retry-After`. |
+| `iat` clock-manipulation / forever-tokens | `MaxTokenAgeSeconds` upper bound (default 24h); cookie path unchanged. |
+| Identifier-driven header injection | `sanitizeIdentifier`: length cap, control-char + bidi-override + `,;=` rejection. `net/http` rejects CRLF on the wire too (defence in depth). |
+| Token leakage downstream | `StripAuthorizationHeader=true` by default. Also: `Authorization` stripped on excluded-URL requests so bearer can't leak into health/metrics downstream logs. |
+| Token-in-logs | All log paths log reason categories, not raw tokens. Identifier hashed via SHA-256 truncated to 8 hex chars before any info/warn-level emission (full identifier only at debug). New `safeLogAuthEvent(category, hashedIdentifier, reasonCode)` helper makes this hard to misuse. |
+| `email` claim spoofing | Startup fails if `EnableBearerAuth && UserIdentifierClaim == "email"`. Future human-user bearer iteration must add `email_verified` enforcement. |
+| Bypass on SSE / WS endpoints | SSE/WS bypass keeps cookie-only behaviour; bearer ignored. Operators choose to widen if needed. |
+| Mixed bearer + cookie precedence | Cookie wins by default (safer for browser scenarios); `BearerOverridesCookie=true` flips. WARN log on both-present requests. |
+| Configuration drift (operator forgets audience) | Startup fails when `EnableBearerAuth=true && Audience==""`. |
+| Downstream blast radius when `StripAuthorizationHeader=false` | Documented: forwarded bearer extends token's blast radius to all downstream services. Logs at those services become token stores. Operators must treat downstream log policy accordingly. |
+| Introspection auth method (pre-existing gap, called out) | `token_introspection.go:80` uses `client_secret_basic` only; does not honour `private_key_jwt`. Out of scope for this PR but documented as a follow-up; operators using `ClientAuthMethod=private_key_jwt` + `RequireTokenIntrospection=true` should be aware introspection will use basic auth. |
+
+## 14. Open Questions
+
+None — all design decisions resolved during brainstorming + security review. Implementation may surface incidental questions (e.g. exact clock-skew leeway in `jwt.Verify`); those are out of scope for this spec and handled in the implementation plan.
+
+## 14a. Security Review Reference
+
+This design was reviewed by the `security-reviewer` subagent on 2026-05-18. Findings incorporated:
+
+- **Critical**: C1 (classifier reuses `detectTokenType`), C2 (sub fallback dropped — unreachable due to `jwt.go:416`), C3 (replay-marking gates only Set, not Get; revocation regression test added).
+- **High**: H1 (alg pinned at bearer entry), H2 (kid length + charset), H3 (cookie wins by default, configurable), H4 (per-IP 401 throttle), H5 (multi-aud requires azp).
+- **Medium**: M1 (identifier max-length + bidi reject + delimiter chars), M2 (introspection cache TTL capped at 60s on bearer path), M4 (log-hashing via SHA-256[:8]), M5 (StripAuth blast-radius documented), M6 (iat upper-age bound), M7 (Authorization stripped on excluded URLs).
+- **Low/Nit**: L2 (renamed to `BearerEmitWWWAuthenticate`), N3 (startup rejects `UserIdentifierClaim=email`).
+- **Documented as pre-existing gaps (follow-up PRs)**: M3 (introspection auth method doesn't honour `private_key_jwt`).
+
+## 15. Implementation Plan Reference
+
+To be produced by the `writing-plans` skill in a follow-up document at `docs/superpowers/plans/2026-05-18-bearer-token-auth-plan.md`. The plan decomposes this design into ordered, independently-testable PRs.

dynamic_client_registration.go

@@ -16,35 +16,26 @@ import (
 
 // ClientRegistrationResponse represents the response from a successful client registration (RFC 7591)
 type ClientRegistrationResponse struct {
-	// Required fields
-	ClientID string `json:"client_id"`
-
-	// Conditional - only for confidential clients
-	ClientSecret string `json:"client_secret,omitempty"`
-
-	// Optional - for managing registration
-	RegistrationAccessToken string `json:"registration_access_token,omitempty"`
-	RegistrationClientURI   string `json:"registration_client_uri,omitempty"`
-
-	// Expiration
-	ClientIDIssuedAt      int64 `json:"client_id_issued_at,omitempty"`
-	ClientSecretExpiresAt int64 `json:"client_secret_expires_at,omitempty"`
-
-	// Echo back of registered metadata
-	RedirectURIs            []string `json:"redirect_uris,omitempty"`
-	ResponseTypes           []string `json:"response_types,omitempty"`
-	GrantTypes              []string `json:"grant_types,omitempty"`
-	ApplicationType         string   `json:"application_type,omitempty"`
-	Contacts                []string `json:"contacts,omitempty"`
-	ClientName              string   `json:"client_name,omitempty"`
-	LogoURI                 string   `json:"logo_uri,omitempty"`
-	ClientURI               string   `json:"client_uri,omitempty"`
-	PolicyURI               string   `json:"policy_uri,omitempty"`
-	TOSURI                  string   `json:"tos_uri,omitempty"`
-	JWKSURI                 string   `json:"jwks_uri,omitempty"`
 	SubjectType             string   `json:"subject_type,omitempty"`
-	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
+	LogoURI                 string   `json:"logo_uri,omitempty"`
+	RegistrationAccessToken string   `json:"registration_access_token,omitempty"`
+	RegistrationClientURI   string   `json:"registration_client_uri,omitempty"`
 	Scope                   string   `json:"scope,omitempty"`
+	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
+	TOSURI                  string   `json:"tos_uri,omitempty"`
+	PolicyURI               string   `json:"policy_uri,omitempty"`
+	ClientSecret            string   `json:"client_secret,omitempty"`
+	ApplicationType         string   `json:"application_type,omitempty"`
+	ClientID                string   `json:"client_id"`
+	ClientName              string   `json:"client_name,omitempty"`
+	JWKSURI                 string   `json:"jwks_uri,omitempty"`
+	ClientURI               string   `json:"client_uri,omitempty"`
+	Contacts                []string `json:"contacts,omitempty"`
+	GrantTypes              []string `json:"grant_types,omitempty"`
+	ResponseTypes           []string `json:"response_types,omitempty"`
+	RedirectURIs            []string `json:"redirect_uris,omitempty"`
+	ClientSecretExpiresAt   int64    `json:"client_secret_expires_at,omitempty"`
+	ClientIDIssuedAt        int64    `json:"client_id_issued_at,omitempty"`
 }
 
 // ClientRegistrationError represents an error response from client registration (RFC 7591)
@@ -55,14 +46,13 @@ type ClientRegistrationError struct {
 
 // DynamicClientRegistrar handles OIDC Dynamic Client Registration (RFC 7591)
 type DynamicClientRegistrar struct {
-	httpClient  *http.Client
-	logger      *Logger
-	config      *DynamicClientRegistrationConfig
-	providerURL string
-
-	// Cached registration response
-	mu                   sync.RWMutex
+	httpClient           *http.Client
+	logger               *Logger
+	config               *DynamicClientRegistrationConfig
 	registrationResponse *ClientRegistrationResponse
+	store                DCRCredentialsStore // Storage backend for credentials
+	providerURL          string
+	mu                   sync.RWMutex
 }
 
 // NewDynamicClientRegistrar creates a new dynamic client registrar
@@ -84,8 +74,37 @@ func NewDynamicClientRegistrar(
 	}
 }
 
+// NewDynamicClientRegistrarWithStore creates a new dynamic client registrar with a specific storage backend
+func NewDynamicClientRegistrarWithStore(
+	httpClient *http.Client,
+	logger *Logger,
+	dcrConfig *DynamicClientRegistrationConfig,
+	providerURL string,
+	store DCRCredentialsStore,
+) *DynamicClientRegistrar {
+	if logger == nil {
+		logger = GetSingletonNoOpLogger()
+	}
+
+	return &DynamicClientRegistrar{
+		httpClient:  httpClient,
+		logger:      logger,
+		config:      dcrConfig,
+		providerURL: providerURL,
+		store:       store,
+	}
+}
+
+// SetStore sets the credentials store for the registrar
+// This allows setting the store after creation when the cache manager is available
+func (r *DynamicClientRegistrar) SetStore(store DCRCredentialsStore) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.store = store
+}
+
 // RegisterClient performs dynamic client registration with the OIDC provider
-// It first attempts to load existing credentials from a file if persistence is enabled,
+// It first attempts to load existing credentials from storage if persistence is enabled,
 // then registers a new client if no valid credentials exist.
 func (r *DynamicClientRegistrar) RegisterClient(ctx context.Context, registrationEndpoint string) (*ClientRegistrationResponse, error) {
 	if r.config == nil || !r.config.Enabled {
@@ -94,10 +113,13 @@ func (r *DynamicClientRegistrar) RegisterClient(ctx context.Context, registratio
 
 	// Try to load existing credentials if persistence is enabled
 	if r.config.PersistCredentials {
-		if resp, err := r.loadCredentials(); err == nil && resp != nil {
+		resp, err := r.loadCredentialsFromStore(ctx)
+		if err != nil {
+			r.logger.Debugf("Failed to load credentials from store: %v", err)
+		} else if resp != nil {
 			// Check if credentials are still valid (not expired)
 			if r.areCredentialsValid(resp) {
-				r.logger.Info("Loaded existing client credentials from file")
+				r.logger.Info("Loaded existing client credentials from storage")
 				r.mu.Lock()
 				r.registrationResponse = resp
 				r.mu.Unlock()
@@ -190,7 +212,7 @@ func (r *DynamicClientRegistrar) RegisterClient(ctx context.Context, registratio
 
 	// Persist credentials if enabled
 	if r.config.PersistCredentials {
-		if err := r.saveCredentials(&regResp); err != nil {
+		if err := r.saveCredentialsToStore(ctx, &regResp); err != nil {
 			r.logger.Errorf("Failed to persist client credentials: %v", err)
 			// Don't fail registration if persistence fails
 		}
@@ -326,7 +348,44 @@ func (r *DynamicClientRegistrar) credentialsFilePath() string {
 	return "/tmp/oidc-client-credentials.json"
 }
 
-// saveCredentials persists client credentials to a file
+// loadCredentialsFromStore loads client credentials from the configured storage backend
+// Falls back to legacy file-based loading if no store is configured
+func (r *DynamicClientRegistrar) loadCredentialsFromStore(ctx context.Context) (*ClientRegistrationResponse, error) {
+	// Use store if available
+	if r.store != nil {
+		return r.store.Load(ctx, r.providerURL)
+	}
+	// Fallback to legacy file-based loading
+	return r.loadCredentials()
+}
+
+// saveCredentialsToStore persists client credentials to the configured storage backend
+// Falls back to legacy file-based saving if no store is configured
+func (r *DynamicClientRegistrar) saveCredentialsToStore(ctx context.Context, resp *ClientRegistrationResponse) error {
+	// Use store if available
+	if r.store != nil {
+		return r.store.Save(ctx, r.providerURL, resp)
+	}
+	// Fallback to legacy file-based saving
+	return r.saveCredentials(resp)
+}
+
+// deleteCredentialsFromStore removes credentials from the configured storage backend
+// Falls back to legacy file-based deletion if no store is configured
+func (r *DynamicClientRegistrar) deleteCredentialsFromStore(ctx context.Context) error {
+	// Use store if available
+	if r.store != nil {
+		return r.store.Delete(ctx, r.providerURL)
+	}
+	// Fallback to legacy file-based deletion
+	filePath := r.credentialsFilePath()
+	if err := os.Remove(filePath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+// saveCredentials persists client credentials to a file (legacy method)
 func (r *DynamicClientRegistrar) saveCredentials(resp *ClientRegistrationResponse) error {
 	filePath := r.credentialsFilePath()
 
@@ -344,7 +403,7 @@ func (r *DynamicClientRegistrar) saveCredentials(resp *ClientRegistrationRespons
 	return nil
 }
 
-// loadCredentials loads client credentials from a file
+// loadCredentials loads client credentials from a file (legacy method)
 func (r *DynamicClientRegistrar) loadCredentials() (*ClientRegistrationResponse, error) {
 	filePath := r.credentialsFilePath()
 
@@ -431,7 +490,7 @@ func (r *DynamicClientRegistrar) UpdateClientRegistration(ctx context.Context) (
 
 	// Persist updated credentials if enabled
 	if r.config.PersistCredentials {
-		if err := r.saveCredentials(&regResp); err != nil {
+		if err := r.saveCredentialsToStore(ctx, &regResp); err != nil {
 			r.logger.Errorf("Failed to persist updated credentials: %v", err)
 		}
 	}
@@ -538,11 +597,10 @@ func (r *DynamicClientRegistrar) DeleteClientRegistration(ctx context.Context) e
 	r.registrationResponse = nil
 	r.mu.Unlock()
 
-	// Remove credentials file if persistence is enabled
+	// Remove credentials from storage if persistence is enabled
 	if r.config.PersistCredentials {
-		filePath := r.credentialsFilePath()
-		if err := os.Remove(filePath); err != nil && !os.IsNotExist(err) {
-			r.logger.Errorf("Failed to remove credentials file: %v", err)
+		if err := r.deleteCredentialsFromStore(ctx); err != nil {
+			r.logger.Errorf("Failed to remove credentials from storage: %v", err)
 		}
 	}
 

dynamic_client_registration_test.go

@@ -223,10 +223,10 @@ func TestRegisterClientWithInitialAccessToken(t *testing.T) {
 // TestRegisterClientError tests error handling during registration
 func TestRegisterClientError(t *testing.T) {
 	tests := []struct {
-		name           string
 		serverResponse func(w http.ResponseWriter, r *http.Request)
-		expectError    bool
+		name           string
 		errorContains  string
+		expectError    bool
 	}{
 		{
 			name: "invalid_redirect_uri error",
@@ -321,8 +321,8 @@ func TestRegisterClientError(t *testing.T) {
 // TestRegisterClientDisabled tests that registration fails when not enabled
 func TestRegisterClientDisabled(t *testing.T) {
 	tests := []struct {
-		name      string
 		dcrConfig *DynamicClientRegistrationConfig
+		name      string
 	}{
 		{
 			name:      "nil config",
@@ -521,8 +521,8 @@ func TestCredentialsValidation(t *testing.T) {
 	registrar := NewDynamicClientRegistrar(&http.Client{}, NewLogger("DEBUG"), dcrConfig, "https://example.com")
 
 	tests := []struct {
-		name     string
 		response *ClientRegistrationResponse
+		name     string
 		expected bool
 	}{
 		{
@@ -584,9 +584,9 @@ func TestCredentialsValidation(t *testing.T) {
 // TestBuildRegistrationRequest tests the request body construction
 func TestBuildRegistrationRequest(t *testing.T) {
 	tests := []struct {
-		name           string
 		metadata       *ClientRegistrationMetadata
 		expectedFields map[string]interface{}
+		name           string
 		expectError    bool
 	}{
 		{

enhanced_mocks_test.go

@@ -2,6 +2,8 @@ package traefikoidc
 
 import (
 	"context"
+	"crypto"
+	"fmt"
 	"net/http"
 	"sync"
 	"sync/atomic"
@@ -12,23 +14,19 @@ import (
 
 // EnhancedMockJWKCache is an improved state-based mock with call tracking
 type EnhancedMockJWKCache struct {
-	mu sync.RWMutex
-
-	// State (what to return)
-	JWKS *JWKSet
-	Err  error
-
-	// Call tracking
+	Err            error
+	JWKS           *JWKSet
 	GetJWKSCalls   []JWKSCall
+	mu             sync.RWMutex
+	getJWKSCallsMu sync.Mutex
 	CleanupCalls   int32
 	CloseCalls     int32
-	getJWKSCallsMu sync.Mutex
 }
 
 // JWKSCall records parameters from a GetJWKS call
 type JWKSCall struct {
-	URL       string
 	Timestamp time.Time
+	URL       string
 }
 
 func (m *EnhancedMockJWKCache) GetJWKS(ctx context.Context, jwksURL string, httpClient *http.Client) (*JWKSet, error) {
@@ -44,6 +42,31 @@ func (m *EnhancedMockJWKCache) GetJWKS(ctx context.Context, jwksURL string, http
 	return m.JWKS, m.Err
 }
 
+func (m *EnhancedMockJWKCache) GetPublicKey(ctx context.Context, jwksURL, kid string, httpClient *http.Client) (crypto.PublicKey, error) {
+	jwks, err := m.GetJWKS(ctx, jwksURL, httpClient)
+	if err != nil {
+		return nil, err
+	}
+	if jwks == nil {
+		return nil, fmt.Errorf("JWKS is nil")
+	}
+	for i := range jwks.Keys {
+		k := &jwks.Keys[i]
+		if k.Kid != kid {
+			continue
+		}
+		switch k.Kty {
+		case "RSA":
+			return k.ToRSAPublicKey()
+		case "EC":
+			return k.ToECDSAPublicKey()
+		default:
+			return nil, fmt.Errorf("unsupported key type: %s", k.Kty)
+		}
+	}
+	return nil, fmt.Errorf("no matching public key found for kid: %s", kid)
+}
+
 func (m *EnhancedMockJWKCache) Cleanup() {
 	atomic.AddInt32(&m.CleanupCalls, 1)
 	m.mu.Lock()
@@ -108,22 +131,18 @@ func (m *EnhancedMockJWKCache) Reset() {
 
 // EnhancedMockTokenVerifier is an improved state-based mock with call tracking
 type EnhancedMockTokenVerifier struct {
-	mu sync.RWMutex
-
-	// State (what to return) - can be a fixed error or a function
-	Err        error
-	VerifyFunc func(token string) error
-
-	// Call tracking
+	Err           error
+	VerifyFunc    func(token string) error
 	VerifyCalls   []TokenVerifyCall
+	mu            sync.RWMutex
 	verifyCallsMu sync.Mutex
 }
 
 // TokenVerifyCall records parameters from a VerifyToken call
 type TokenVerifyCall struct {
-	Token     string
 	Timestamp time.Time
 	Result    error
+	Token     string
 }
 
 func (m *EnhancedMockTokenVerifier) VerifyToken(token string) error {
@@ -207,49 +226,43 @@ func (m *EnhancedMockTokenVerifier) Reset() {
 
 // EnhancedMockTokenExchanger is an improved state-based mock with call tracking
 type EnhancedMockTokenExchanger struct {
-	mu sync.RWMutex
-
-	// State (what to return)
-	ExchangeResponse *TokenResponse
-	ExchangeErr      error
-	RefreshResponse  *TokenResponse
 	RefreshErr       error
 	RevokeErr        error
-
-	// Optional functions for dynamic behavior
+	ExchangeErr      error
 	ExchangeCodeFunc func(ctx context.Context, grantType, codeOrToken, redirectURL, codeVerifier string) (*TokenResponse, error)
+	RefreshResponse  *TokenResponse
+	ExchangeResponse *TokenResponse
 	RefreshTokenFunc func(refreshToken string) (*TokenResponse, error)
 	RevokeTokenFunc  func(token, tokenType string) error
-
-	// Call tracking
-	ExchangeCalls   []ExchangeCall
-	RefreshCalls    []RefreshCall
-	RevokeCalls     []RevokeCall
-	exchangeCallsMu sync.Mutex
-	refreshCallsMu  sync.Mutex
-	revokeCallsMu   sync.Mutex
+	ExchangeCalls    []ExchangeCall
+	RefreshCalls     []RefreshCall
+	RevokeCalls      []RevokeCall
+	mu               sync.RWMutex
+	exchangeCallsMu  sync.Mutex
+	refreshCallsMu   sync.Mutex
+	revokeCallsMu    sync.Mutex
 }
 
 // ExchangeCall records parameters from an ExchangeCodeForToken call
 type ExchangeCall struct {
+	Timestamp    time.Time
 	GrantType    string
 	CodeOrToken  string
 	RedirectURL  string
 	CodeVerifier string
-	Timestamp    time.Time
 }
 
 // RefreshCall records parameters from a GetNewTokenWithRefreshToken call
 type RefreshCall struct {
-	RefreshToken string
 	Timestamp    time.Time
+	RefreshToken string
 }
 
 // RevokeCall records parameters from a RevokeTokenWithProvider call
 type RevokeCall struct {
+	Timestamp time.Time
 	Token     string
 	TokenType string
-	Timestamp time.Time
 }
 
 func (m *EnhancedMockTokenExchanger) ExchangeCodeForToken(ctx context.Context, grantType, codeOrToken, redirectURL, codeVerifier string) (*TokenResponse, error) {
@@ -401,16 +414,12 @@ func (m *EnhancedMockTokenExchanger) Reset() {
 
 // EnhancedMockCacheInterface is an improved state-based mock for CacheInterface
 type EnhancedMockCacheInterface struct {
-	mu sync.RWMutex
-
-	// Internal storage
-	data    map[string]cacheEntry
-	maxSize int
-
-	// Call tracking
+	data        map[string]cacheEntry
 	GetCalls    []CacheGetCall
 	SetCalls    []CacheSetCall
 	DeleteCalls []string
+	maxSize     int
+	mu          sync.RWMutex
 	getCalls    sync.Mutex
 	setCalls    sync.Mutex
 	deleteCalls sync.Mutex
@@ -423,17 +432,17 @@ type cacheEntry struct {
 
 // CacheGetCall records parameters from a Get call
 type CacheGetCall struct {
+	Timestamp time.Time
 	Key       string
 	Found     bool
-	Timestamp time.Time
 }
 
 // CacheSetCall records parameters from a Set call
 type CacheSetCall struct {
-	Key       string
-	Value     any
-	TTL       time.Duration
 	Timestamp time.Time
+	Value     any
+	Key       string
+	TTL       time.Duration
 }
 
 // NewEnhancedMockCache creates a new enhanced cache mock

error_recovery.go

@@ -642,14 +642,10 @@ func (e *HTTPError) Error() string {
 // OIDCError represents OIDC-specific errors with context information.
 // It provides structured error reporting for authentication and authorization failures.
 type OIDCError struct {
-	// Code identifies the specific error type
-	Code string
-	// Message provides a human-readable description
-	Message string
-	// Context contains additional error context (e.g., provider, session details)
+	Cause   error
 	Context map[string]interface{}
-	// Cause is the underlying error that caused this error
-	Cause error
+	Code    string
+	Message string
 }
 
 // Error returns the string representation of the OIDC error.
@@ -669,14 +665,10 @@ func (e *OIDCError) Unwrap() error {
 // SessionError represents session-related errors with context.
 // Used for session management, validation, and storage errors.
 type SessionError struct {
-	// Operation describes what session operation failed
+	Cause     error
 	Operation string
-	// Message provides a human-readable description
-	Message string
-	// SessionID identifies the session (if available)
+	Message   string
 	SessionID string
-	// Cause is the underlying error that caused this error
-	Cause error
 }
 
 // Error returns the string representation of the session error.
@@ -696,14 +688,10 @@ func (e *SessionError) Unwrap() error {
 // TokenError represents token-related errors with validation context.
 // Used for JWT validation, token refresh, and token format errors.
 type TokenError struct {
-	// TokenType identifies the type of token (id_token, access_token, refresh_token)
+	Cause     error
 	TokenType string
-	// Reason describes why the token is invalid
-	Reason string
-	// Message provides a human-readable description
-	Message string
-	// Cause is the underlying error that caused this error
-	Cause error
+	Reason    string
+	Message   string
 }
 
 // Error returns the string representation of the token error.
@@ -765,24 +753,15 @@ func NewTokenError(tokenType, reason, message string, cause error) *TokenError {
 // It provides fallback mechanisms when primary services are unavailable and monitors
 // service health to automatically recover when services become available again.
 type GracefulDegradation struct {
-	// BaseRecoveryMechanism provides common functionality
 	*BaseRecoveryMechanism
-	// fallbacks stores service-specific fallback implementations
-	fallbacks map[string]func() (interface{}, error)
-	// healthChecks stores service health check functions
-	healthChecks map[string]func() bool
-	// degradedServices tracks which services are currently degraded
+	fallbacks        map[string]func() (interface{}, error)
+	healthChecks     map[string]func() bool
 	degradedServices map[string]time.Time
-	// config contains graceful degradation configuration
-	config GracefulDegradationConfig
-	// mutex protects shared state
-	mutex sync.RWMutex
-	// healthCheckTask manages background health checking
-	healthCheckTask *BackgroundTask
-	// stopChan signals shutdown
-	stopChan chan struct{}
-	// shutdownOnce ensures shutdown happens only once
-	shutdownOnce sync.Once
+	healthCheckTask  *BackgroundTask
+	stopChan         chan struct{}
+	config           GracefulDegradationConfig
+	mutex            sync.RWMutex
+	shutdownOnce     sync.Once
 }
 
 // GracefulDegradationConfig holds configuration for graceful degradation behavior.
@@ -975,7 +954,7 @@ func (gd *GracefulDegradation) GetDegradedServices() []string {
 	gd.mutex.RLock()
 	defer gd.mutex.RUnlock()
 
-	var degraded []string
+	degraded := make([]string, 0, len(gd.degradedServices))
 	for serviceName := range gd.degradedServices {
 		degraded = append(degraded, serviceName)
 	}

error_recovery_test.go

@@ -20,10 +20,10 @@ import (
 func TestCircuitBreakerStateTransitions(t *testing.T) {
 	tests := []struct {
 		name                string
-		failures            int
-		maxFailures         int
 		expectedStateBefore string
 		expectedStateAfter  string
+		failures            int
+		maxFailures         int
 	}{
 		{
 			name:                "stays closed below threshold",
@@ -543,8 +543,8 @@ func TestRetryExecutorNetworkErrors(t *testing.T) {
 	}, nil)
 
 	tests := []struct {
-		name        string
 		err         error
+		name        string
 		shouldRetry bool
 	}{
 		{
@@ -1647,8 +1647,8 @@ func TestGracefulDegradationFullScenario(t *testing.T) {
 
 func TestIsTraefikDefaultCertError(t *testing.T) {
 	tests := []struct {
-		name     string
 		err      error
+		name     string
 		expected bool
 	}{
 		{
@@ -1680,8 +1680,8 @@ func TestIsTraefikDefaultCertError(t *testing.T) {
 
 func TestIsEOFError(t *testing.T) {
 	tests := []struct {
-		name     string
 		err      error
+		name     string
 		expected bool
 	}{
 		{
@@ -1723,8 +1723,8 @@ func TestIsEOFError(t *testing.T) {
 
 func TestIsCertificateError(t *testing.T) {
 	tests := []struct {
-		name     string
 		err      error
+		name     string
 		expected bool
 	}{
 		{
@@ -1811,8 +1811,8 @@ func TestRetryExecutorStartupErrors(t *testing.T) {
 	_ = NewRetryExecutor(MetadataFetchRetryConfig(), nil)
 
 	tests := []struct {
-		name        string
 		err         error
+		name        string
 		shouldRetry bool
 	}{
 		{
@@ -1890,8 +1890,8 @@ func TestRetryExecutorIsRetryableErrorIntegration(t *testing.T) {
 	re := NewRetryExecutor(DefaultRetryConfig(), nil)
 
 	tests := []struct {
-		name        string
 		err         error
+		name        string
 		shouldRetry bool
 	}{
 		{
@@ -1977,9 +1977,9 @@ func circuitBreakerStateToString(state CircuitBreakerState) string {
 }
 
 type mockNetError struct {
+	msg       string
 	timeout   bool
 	temporary bool
-	msg       string
 }
 
 func (e *mockNetError) Error() string   { return e.msg }

examples/complete-traefik-config.yaml

@@ -101,6 +101,16 @@ http:
           providerURL: "https://auth.example.com"
           callbackURL: "/oauth2/callback"
 
+          # ----------------------------------------------------------------
+          # Optional: switch to RFC 7523 private_key_jwt client auth
+          # (Entra ID, Okta, Auth0, Keycloak). Replaces clientSecret with a
+          # signed JWT assertion. See README for details and PEM formats.
+          # ----------------------------------------------------------------
+          # clientAuthMethod: "private_key_jwt"
+          # clientAssertionKeyPath: "/etc/traefik/oidc/client-key.pem"
+          # clientAssertionKeyID: "prod-key-2026"
+          # clientAssertionAlg: "RS256"   # or PS256/384/512, ES256/384/512
+
           # Session Configuration
           sessionEncryptionKey: "prod-encryption-key-64-chars-long-keep-it-secret-and-safe"
           sessionMaxAge: 28800  # 8 hours

go.mod

@@ -4,7 +4,6 @@ go 1.24.0
 
 require (
 	github.com/alicebob/miniredis/v2 v2.35.0
-	github.com/google/uuid v1.6.0
 	github.com/gorilla/sessions v1.3.0
 	github.com/redis/go-redis/v9 v9.17.2
 	github.com/stretchr/testify v1.10.0

go.sum

@@ -12,8 +12,6 @@ github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/r
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
 github.com/google/gofuzz v1.2.0 h1:xRy4A+RhZaiKjJ1bPfwQ8sedCA+YS2YcCHW6ec7JMi0=
 github.com/google/gofuzz v1.2.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
-github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
-github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/securecookie v1.1.2 h1:YCIWL56dvtr73r6715mJs5ZvhtnY73hBvEF8kXD8ePA=
 github.com/gorilla/securecookie v1.1.2/go.mod h1:NfCASbcHqRSY+3a8tlWJwsQap2VX5pwzwo4h3eOamfo=
 github.com/gorilla/sessions v1.3.0 h1:XYlkq7KcpOB2ZhHBPv5WpjMIxrQosiZanfoy1HLZFzg=

goroutine_manager.go

@@ -10,16 +10,16 @@ import (
 type GoroutineManager struct {
 	ctx        context.Context
 	cancel     context.CancelFunc
-	wg         sync.WaitGroup
-	mu         sync.RWMutex
 	goroutines map[string]*managedGoroutine
 	logger     *Logger
+	wg         sync.WaitGroup
+	mu         sync.RWMutex
 }
 
 type managedGoroutine struct {
-	name      string
-	cancel    context.CancelFunc
 	startTime time.Time
+	cancel    context.CancelFunc
+	name      string
 	running   bool
 }
 
@@ -149,10 +149,10 @@ func (m *GoroutineManager) GetStatus() map[string]GoroutineStatus {
 
 // GoroutineStatus represents the status of a managed goroutine
 type GoroutineStatus struct {
-	Name      string
-	Running   bool
 	StartTime time.Time
+	Name      string
 	Runtime   time.Duration
+	Running   bool
 }
 
 // ErrShutdownTimeout is returned when shutdown times out

helpers.go

@@ -17,6 +17,21 @@ import (
 	"github.com/lukaszraczylo/traefikoidc/internal/utils"
 )
 
+// newUUIDv4 returns an RFC 4122 v4 UUID string (e.g.
+// "f47ac10b-58cc-4372-a567-0e02b2c3d479") backed by crypto/rand. Used for CSRF
+// tokens and other opaque random identifiers — replaces github.com/google/uuid
+// to keep the plugin stdlib-only on the production path.
+func newUUIDv4() (string, error) {
+	var b [16]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return "", fmt.Errorf("could not generate UUID: %w", err)
+	}
+	b[6] = (b[6] & 0x0f) | 0x40 // version 4
+	b[8] = (b[8] & 0x3f) | 0x80 // RFC 4122 variant
+	return fmt.Sprintf("%08x-%04x-%04x-%04x-%012x",
+		b[0:4], b[4:6], b[6:8], b[8:10], b[10:16]), nil
+}
+
 // generateNonce creates a cryptographically secure random nonce for OIDC flows.
 // The nonce is used to prevent replay attacks and associate client sessions with ID tokens.
 // Returns:
@@ -92,9 +107,12 @@ type TokenResponse struct {
 //   - An error if the token exchange fails (e.g., network error, provider error, invalid grant)
 func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, codeOrToken string, redirectURL string, codeVerifier string) (*TokenResponse, error) {
 	data := url.Values{
-		"grant_type":    {grantType},
-		"client_id":     {t.clientID},
-		"client_secret": {t.clientSecret},
+		"grant_type": {grantType},
+	}
+	// 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 grantType == "authorization_code" {
@@ -126,16 +144,33 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
 		}
 	}
 
-	// Read tokenURL with RLock
+	// Read tokenURL with RLock — needed as audience for private_key_jwt (RFC 7523 §3).
 	t.metadataMu.RLock()
 	tokenURL := t.tokenURL
 	t.metadataMu.RUnlock()
 
+	useBasicAuth := false
+	if t.clientAssertion != nil {
+		assertion, err := t.clientAssertion.Sign(tokenURL, t.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" {
+		useBasicAuth = true
+	} else {
+		data.Set("client_secret", t.clientSecret)
+	}
+
 	req, err := http.NewRequestWithContext(ctx, "POST", tokenURL, strings.NewReader(data.Encode()))
 	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)
+	}
 
 	resp, err := client.Do(req)
 	if err != nil {
@@ -336,6 +371,7 @@ func createStringMap(keys []string) map[string]struct{} {
 // and redirects to the provider's logout endpoint or configured post-logout URI.
 // It handles potential errors during session retrieval or clearing.
 func (t *TraefikOidc) handleLogout(rw http.ResponseWriter, req *http.Request) {
+	t.logger.Debug("Processing logout request")
 	session, err := t.sessionManager.GetSession(req)
 	if err != nil {
 		t.logger.Errorf("Error getting session: %v", err)
@@ -407,6 +443,19 @@ func BuildLogoutURL(endSessionURL, idToken, postLogoutRedirectURI string) (strin
 	return u.String(), nil
 }
 
+// setOAuthBasicAuth sets the Authorization header per RFC 6749 §2.3.1: the
+// client_id and client_secret are form-urlencoded individually, joined with a
+// colon, then base64-encoded. This differs from http.Request.SetBasicAuth,
+// which skips the form-urlencode step — that matters for credentials with
+// reserved characters (`:`, `@`, `+`, `%`, etc.) where the wire format would
+// otherwise diverge from what the spec mandates.
+func setOAuthBasicAuth(req *http.Request, clientID, clientSecret string) {
+	user := url.QueryEscape(clientID)
+	pass := url.QueryEscape(clientSecret)
+	auth := base64.StdEncoding.EncodeToString([]byte(user + ":" + pass))
+	req.Header.Set("Authorization", "Basic "+auth)
+}
+
 // deduplicateScopes removes duplicate scopes from a slice while preserving order.
 // This ensures that OAuth scope parameters don't contain duplicates which could
 // cause issues with some authorization servers.

helpers_test.go

@@ -0,0 +1,29 @@
+package traefikoidc
+
+import (
+	"regexp"
+	"testing"
+)
+
+// TestNewUUIDv4 verifies the in-house UUID v4 generator produces RFC 4122
+// compliant identifiers. Locks in the replacement for github.com/google/uuid
+// — a regression here would weaken the CSRF token used in the OIDC flow.
+func TestNewUUIDv4(t *testing.T) {
+	rfc4122v4 := regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)
+
+	const samples = 1000
+	seen := make(map[string]struct{}, samples)
+	for i := 0; i < samples; i++ {
+		got, err := newUUIDv4()
+		if err != nil {
+			t.Fatalf("newUUIDv4 failed: %v", err)
+		}
+		if !rfc4122v4.MatchString(got) {
+			t.Fatalf("UUID %q does not match RFC 4122 v4 format", got)
+		}
+		if _, dup := seen[got]; dup {
+			t.Fatalf("duplicate UUID emitted within %d samples: %q", samples, got)
+		}
+		seen[got] = struct{}{}
+	}
+}

http_client_factory.go

@@ -3,6 +3,7 @@ package traefikoidc
 import (
 	"context"
 	"crypto/tls"
+	"crypto/x509"
 	"fmt"
 	"net"
 	"net/http"
@@ -12,27 +13,26 @@ import (
 
 // HTTPClientConfig provides configuration for creating HTTP clients
 type HTTPClientConfig struct {
-	// Timeout for the entire request
-	Timeout time.Duration
-	// MaxRedirects allowed (0 means follow Go's default of 10)
-	MaxRedirects int
-	// UseCookieJar enables cookie jar for the client
-	UseCookieJar bool
-	// Connection settings
+	IdleConnTimeout       time.Duration
+	MaxIdleConns          int
+	ReadBufferSize        int
 	DialTimeout           time.Duration
 	KeepAlive             time.Duration
 	TLSHandshakeTimeout   time.Duration
 	ResponseHeaderTimeout time.Duration
 	ExpectContinueTimeout time.Duration
-	IdleConnTimeout       time.Duration
-	// Connection pool settings
-	MaxIdleConns        int
-	MaxIdleConnsPerHost int
-	MaxConnsPerHost     int
-	// Buffer settings
-	WriteBufferSize int
-	ReadBufferSize  int
-	// Feature flags
+	MaxRedirects          int
+	MaxIdleConnsPerHost   int
+	Timeout               time.Duration
+	MaxConnsPerHost       int
+	WriteBufferSize       int
+	// RootCAs is an optional certificate pool used for TLS verification.
+	// A nil pool means "use the system trust store" (default behavior).
+	RootCAs *x509.CertPool
+	// InsecureSkipVerify disables TLS certificate verification.
+	// ONLY set this for local development against self-signed certificates.
+	InsecureSkipVerify bool
+	UseCookieJar       bool
 	ForceHTTP2         bool
 	DisableKeepAlives  bool
 	DisableCompression bool
@@ -210,7 +210,8 @@ func (f *HTTPClientFactory) CreateHTTPClient(config HTTPClientConfig) *http.Clie
 				tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
 			},
 			PreferServerCipherSuites: true,
-			InsecureSkipVerify:       false, // Always verify certificates
+			RootCAs:                  config.RootCAs,
+			InsecureSkipVerify:       config.InsecureSkipVerify, //nolint:gosec // opt-in, loud warning emitted at plugin startup
 		},
 		ForceAttemptHTTP2:     config.ForceHTTP2,
 		TLSHandshakeTimeout:   config.TLSHandshakeTimeout,

http_client_factory_unit_test.go

@@ -110,9 +110,9 @@ func TestHTTPClientFactoryValidateHTTPClientConfig(t *testing.T) {
 
 	tests := []struct {
 		name      string
+		errorMsg  string
 		config    HTTPClientConfig
 		wantError bool
-		errorMsg  string
 	}{
 		{
 			name: "valid config",

http_client_pool.go

@@ -3,6 +3,7 @@ package traefikoidc
 import (
 	"context"
 	"crypto/tls"
+	"fmt"
 	"net"
 	"net/http"
 	"sync"
@@ -12,19 +13,19 @@ import (
 
 // SharedTransportPool manages a pool of shared HTTP transports to prevent connection exhaustion
 type SharedTransportPool struct {
-	mu          sync.RWMutex
-	transports  map[string]*sharedTransport
-	maxConns    int
 	ctx         context.Context
+	transports  map[string]*sharedTransport
 	cancel      context.CancelFunc
-	clientCount int32 // SECURITY FIX: Track total HTTP clients
-	maxClients  int32 // SECURITY FIX: Limit total clients to 5
+	maxConns    int
+	mu          sync.RWMutex
+	clientCount int32
+	maxClients  int32
 }
 
 type sharedTransport struct {
+	lastUsed  time.Time
 	transport *http.Transport
 	refCount  int
-	lastUsed  time.Time
 }
 
 var (
@@ -103,7 +104,8 @@ func (p *SharedTransportPool) GetOrCreateTransport(config HTTPClientConfig) *htt
 				tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
 			},
 			PreferServerCipherSuites: true,
-			InsecureSkipVerify:       false,
+			RootCAs:                  config.RootCAs,
+			InsecureSkipVerify:       config.InsecureSkipVerify, //nolint:gosec // opt-in, loud warning emitted at plugin startup
 		},
 		ForceAttemptHTTP2:     config.ForceHTTP2,
 		TLSHandshakeTimeout:   config.TLSHandshakeTimeout,
@@ -205,8 +207,21 @@ func (p *SharedTransportPool) performCleanup() {
 
 // configKey generates a unique key for a config
 func (p *SharedTransportPool) configKey(config HTTPClientConfig) string {
-	// Simple key based on main parameters
-	return string(rune(config.MaxConnsPerHost)) + string(rune(config.MaxIdleConnsPerHost))
+	// Pool transports by the parameters that change TLS or connection
+	// behavior. 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.
+	skip := "0"
+	if config.InsecureSkipVerify {
+		skip = "1"
+	}
+	return fmt.Sprintf("%d|%d|%p|%s",
+		config.MaxConnsPerHost,
+		config.MaxIdleConnsPerHost,
+		config.RootCAs,
+		skip,
+	)
 }
 
 // Cleanup closes all transports and stops the cleanup goroutine

input_validation.go

@@ -10,6 +10,14 @@ import (
 	"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
@@ -73,7 +81,7 @@ func DefaultInputValidationConfig() InputValidationConfig {
 }
 
 // NewInputValidator creates a new input validator with the specified configuration.
-// It compiles all necessary regex patterns and initializes security pattern lists.
+// It uses pre-compiled regex patterns and initializes security pattern lists.
 //
 // Parameters:
 //   - config: Validation configuration with size limits and mode settings.
@@ -81,29 +89,8 @@ func DefaultInputValidationConfig() InputValidationConfig {
 //
 // Returns:
 //   - A configured InputValidator instance.
-//   - An error if regex compilation fails.
+//   - An error (always nil, kept for API compatibility).
 func NewInputValidator(config InputValidationConfig, logger *Logger) (*InputValidator, error) {
-	// Compile regex patterns
-	emailRegex, err := regexp.Compile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
-	if err != nil {
-		return nil, fmt.Errorf("failed to compile email regex: %w", err)
-	}
-
-	urlRegex, err := regexp.Compile(`^https?://[a-zA-Z0-9.-]+(?:\.[a-zA-Z]{2,})?(?::[0-9]+)?(?:/[^\s]*)?$`)
-	if err != nil {
-		return nil, fmt.Errorf("failed to compile URL regex: %w", err)
-	}
-
-	tokenRegex, err := regexp.Compile(`^[A-Za-z0-9._-]+$`)
-	if err != nil {
-		return nil, fmt.Errorf("failed to compile token regex: %w", err)
-	}
-
-	usernameRegex, err := regexp.Compile(`^[a-zA-Z0-9._-]+$`)
-	if err != nil {
-		return nil, fmt.Errorf("failed to compile username regex: %w", err)
-	}
-
 	return &InputValidator{
 		maxTokenLength:          config.MaxTokenLength,
 		maxURLLength:            config.MaxURLLength,
@@ -112,10 +99,10 @@ func NewInputValidator(config InputValidationConfig, logger *Logger) (*InputVali
 		maxEmailLength:          config.MaxEmailLength,
 		maxUsernameLength:       config.MaxUsernameLength,
 		allowPrivateIPAddresses: config.AllowPrivateIPAddresses,
-		emailRegex:              emailRegex,
-		urlRegex:                urlRegex,
-		tokenRegex:              tokenRegex,
-		usernameRegex:           usernameRegex,
+		emailRegex:              emailRegexPattern,
+		urlRegex:                urlRegexPattern,
+		tokenRegex:              tokenRegexPattern,
+		usernameRegex:           usernameRegexPattern,
 		sqlInjectionPatterns: []string{
 			"'", "\"", ";", "--", "/*", "*/", "xp_", "sp_",
 			"union", "select", "insert", "update", "delete", "drop",

input_validation_test.go

@@ -14,7 +14,7 @@ func TestInputValidator(t *testing.T) {
 	}
 
 	t.Run("Valid token validation", func(t *testing.T) {
-		validToken := "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.EkN-DOsnsuRjRO6BxXemmJDm3HbxrbRzXglbN2S4sOkopdU4IsDxTI8jO19W_A4K8ZPJijNLis4EZsHeY559a4DFOd50_OqgHs3UjpMC6M6FNqI2J-I2NxrragtnDxGxdJUvDERDQVHzeNlVQiuqWDEeO_O-0KptafbfyuGqfQxH_6dp2_MeFpAc"
+		validToken := "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.EkN-DOsnsuRjRO6BxXemmJDm3HbxrbRzXglbN2S4sOkopdU4IsDxTI8jO19W_A4K8ZPJijNLis4EZsHeY559a4DFOd50_OqgHs3UjpMC6M6FNqI2J-I2NxrragtnDxGxdJUvDERDQVHzeNlVQiuqWDEeO_O-0KptafbfyuGqfQxH_6dp2_MeFpAc" // trufflehog:ignore
 
 		result := validator.ValidateToken(validToken)
 		if !result.IsValid {
@@ -428,12 +428,12 @@ func TestInputValidatorValidateToken(t *testing.T) {
 	tests := []struct {
 		name        string
 		token       string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidJWTToken",
-			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNTE2MjM5MDIyLCJpYXQiOjE1MTYyMzkwMjJ9.signature",
+			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNTE2MjM5MDIyLCJpYXQiOjE1MTYyMzkwMjJ9.signature", // trufflehog:ignore
 			expectValid: true,
 			description: "Valid JWT token should pass validation",
 		},
@@ -475,7 +475,7 @@ func TestInputValidatorValidateToken(t *testing.T) {
 		},
 		{
 			name:        "MaliciousJWTWithExtraData",
-			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.sig.malicious_extra",
+			token:       "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.sig.malicious_extra", // trufflehog:ignore
 			expectValid: false,
 			description: "JWT with extra malicious data should fail validation",
 		},
@@ -500,8 +500,8 @@ func TestInputValidatorValidateEmail(t *testing.T) {
 	tests := []struct {
 		name        string
 		email       string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidEmail",
@@ -578,8 +578,8 @@ func TestInputValidatorValidateURL(t *testing.T) {
 	tests := []struct {
 		name        string
 		url         string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidHTTPSURL",
@@ -669,8 +669,8 @@ func TestInputValidatorValidateClaim(t *testing.T) {
 		name        string
 		claimName   string
 		claimValue  string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidStringClaim",
@@ -750,8 +750,8 @@ func TestInputValidatorValidateHeader(t *testing.T) {
 		name        string
 		headerName  string
 		headerValue string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidHeader",
@@ -830,8 +830,8 @@ func TestInputValidatorValidateUsername(t *testing.T) {
 	tests := []struct {
 		name        string
 		username    string
-		expectValid bool
 		description string
+		expectValid bool
 	}{
 		{
 			name:        "ValidUsername",

integration/integration_consolidated_test.go

@@ -726,20 +726,20 @@ type MockConfig struct {
 }
 
 type MockSession struct {
-	id       string
-	userID   string
 	created  time.Time
 	lastUsed time.Time
 	data     map[string]interface{}
+	id       string
+	userID   string
 }
 
 type TestResult struct {
-	UserID    int
 	StartTime time.Time
 	EndTime   time.Time
+	Error     error
+	UserID    int
 	Duration  time.Duration
 	Success   bool
-	Error     error
 }
 
 // ============================================================================

internal/cache/backends/config.go

@@ -18,33 +18,25 @@ const (
 
 // Config provides common configuration for cache backends
 type Config struct {
-	// Type specifies the backend type
-	Type BackendType
-
-	// Memory backend settings
-	MaxSize         int
-	MaxMemoryBytes  int64
-	CleanupInterval time.Duration
-
-	// Redis backend settings
-	RedisAddr     string
-	RedisPassword string
-	RedisDB       int
-	RedisPrefix   string
-	PoolSize      int
-
-	// Hybrid backend settings
-	L1Config    *Config // Memory cache (L1)
-	L2Config    *Config // Redis cache (L2)
-	AsyncWrites bool    // Write to L2 asynchronously
-
-	// Resilience settings
+	L2Config             *Config
+	L1Config             *Config
+	RedisPrefix          string
+	Type                 BackendType
+	RedisAddr            string
+	RedisPassword        string
+	TLSServerName        string
+	PoolSize             int
+	RedisDB              int
+	CleanupInterval      time.Duration
+	MaxMemoryBytes       int64
+	MaxSize              int
+	HealthCheckInterval  time.Duration
+	AsyncWrites          bool
 	EnableCircuitBreaker bool
 	EnableHealthCheck    bool
-	HealthCheckInterval  time.Duration
-
-	// Metrics
-	EnableMetrics bool
+	EnableMetrics        bool
+	EnableTLS            bool
+	TLSSkipVerify        bool
 }
 
 // DefaultConfig returns a default configuration for in-memory caching

internal/cache/backends/hybrid.go

@@ -13,40 +13,41 @@ import (
 // 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 {
-	primary   CacheBackend // L1: Memory cache for fast access
-	secondary CacheBackend // L2: Redis cache for distributed access
-
-	// Configuration
-	syncWriteCacheTypes map[string]bool // Which cache types require synchronous writes
+	lastL2Error         atomic.Value
+	secondary           CacheBackend
+	primary             CacheBackend
+	logger              Logger
+	ctx                 context.Context
+	syncWriteCacheTypes map[string]bool
 	asyncWriteBuffer    chan *asyncWriteItem
-
-	// Metrics
-	l1Hits   atomic.Int64
-	l2Hits   atomic.Int64
-	misses   atomic.Int64
-	l1Writes atomic.Int64
-	l2Writes atomic.Int64
-	errors   atomic.Int64
-
-	// Fallback tracking
-	fallbackMode atomic.Bool  // True when operating in degraded mode (L1 only)
-	lastL2Error  atomic.Value // Stores last L2 error timestamp
-
-	// Lifecycle
-	ctx    context.Context
-	cancel context.CancelFunc
-	wg     sync.WaitGroup
-
-	// Logging
-	logger Logger
+	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
-	ctx   context.Context
 }
 
 // Logger interface for structured logging
@@ -82,9 +83,9 @@ func (l *defaultLogger) Errorf(format string, args ...interface{}) {
 type HybridConfig struct {
 	Primary             CacheBackend
 	Secondary           CacheBackend
-	SyncWriteCacheTypes map[string]bool // Cache types requiring synchronous L2 writes
-	AsyncBufferSize     int
 	Logger              Logger
+	SyncWriteCacheTypes map[string]bool
+	AsyncBufferSize     int
 }
 
 // NewHybridBackend creates a new hybrid cache backend with L1 (memory) and L2 (Redis) tiers
@@ -124,6 +125,7 @@ func NewHybridBackend(config *HybridConfig) (*HybridBackend, error) {
 		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,
@@ -133,6 +135,11 @@ func NewHybridBackend(config *HybridConfig) (*HybridBackend, error) {
 	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()
@@ -157,7 +164,7 @@ func (h *HybridBackend) Set(ctx context.Context, key string, value []byte, ttl t
 
 	// Check if we're in fallback mode
 	if h.fallbackMode.Load() {
-		h.logger.Debugf("Operating in fallback mode, skipping L2 write for key: %s", key)
+		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
 	}
 
@@ -169,13 +176,13 @@ func (h *HybridBackend) Set(ctx context.Context, key string, value []byte, ttl t
 		// 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", key, err)
+			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", key)
+		h.logger.Debugf("Synchronous write to L2 completed for critical key: %s", redactKey(key))
 	} else {
 		// Asynchronous write for non-critical cache types
 		select {
@@ -185,10 +192,10 @@ func (h *HybridBackend) Set(ctx context.Context, key string, value []byte, ttl t
 			ttl:   ttl,
 			ctx:   ctx,
 		}:
-			h.logger.Debugf("Queued async write to L2 for key: %s", key)
+			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", key)
+			h.logger.Warnf("Async write buffer full, dropping L2 write for key: %s", redactKey(key))
 			h.errors.Add(1)
 		}
 	}
@@ -202,7 +209,7 @@ func (h *HybridBackend) Get(ctx context.Context, key string) ([]byte, time.Durat
 	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", key, err)
+		h.logger.Debugf("L1 get error for key %s: %v", redactKey(key), err)
 	}
 
 	if exists {
@@ -220,7 +227,7 @@ func (h *HybridBackend) Get(ctx context.Context, key string) ([]byte, time.Durat
 	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", key, err)
+		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
@@ -233,18 +240,10 @@ func (h *HybridBackend) Get(ctx context.Context, key string) ([]byte, time.Durat
 
 	h.l2Hits.Add(1)
 
-	// Populate L1 cache with value from L2 (write-through on read)
-	// Use goroutine to avoid blocking the read path
-	go func() {
-		writeCtx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
-		defer cancel()
-
-		if err := h.primary.Set(writeCtx, key, value, ttl); err != nil {
-			h.logger.Debugf("Failed to populate L1 cache from L2 for key %s: %v", key, err)
-		} else {
-			h.logger.Debugf("Populated L1 cache from L2 for key: %s", key)
-		}
-	}()
+	// 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
 }
@@ -381,6 +380,7 @@ func (h *HybridBackend) Close() error {
 
 	// Close async write channel
 	close(h.asyncWriteBuffer)
+	close(h.l1BackfillBuffer)
 
 	// Wait for workers to finish with timeout
 	done := make(chan struct{})
@@ -450,13 +450,7 @@ func (h *HybridBackend) GetMany(ctx context.Context, keys []string) (map[string]
 			for key, value := range l2Results {
 				results[key] = value
 				h.l2Hits.Add(1)
-
-				// Asynchronously populate L1
-				go func(k string, v []byte) {
-					writeCtx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
-					defer cancel()
-					_ = h.primary.Set(writeCtx, k, v, 0) // Use default TTL
-				}(key, value)
+				h.queueL1Backfill(key, value, 0) // 0 = primary backend default TTL
 			}
 		}
 	} else {
@@ -465,13 +459,7 @@ func (h *HybridBackend) GetMany(ctx context.Context, keys []string) (map[string]
 			if value, ttl, exists, err := h.secondary.Get(ctx, key); err == nil && exists {
 				results[key] = value
 				h.l2Hits.Add(1)
-
-				// Asynchronously populate L1
-				go func(k string, v []byte, t time.Duration) {
-					writeCtx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
-					defer cancel()
-					_ = h.primary.Set(writeCtx, k, v, t)
-				}(key, value, ttl)
+				h.queueL1Backfill(key, value, ttl)
 			}
 		}
 	}
@@ -548,6 +536,55 @@ func (h *HybridBackend) SetMany(ctx context.Context, items map[string][]byte, tt
 	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()
@@ -582,11 +619,11 @@ func (h *HybridBackend) asyncWriteWorker() {
 			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", item.key, err)
+				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", item.key)
+				h.logger.Debugf("Async write to L2 completed for key: %s", redactKey(item.key))
 			}
 			cancel()
 		}

internal/cache/backends/hybrid_l1_backfill_test.go

@@ -0,0 +1,112 @@
+//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/hybrid_test.go

@@ -17,23 +17,23 @@ import (
 
 // mockBackend is a simple mock implementation of CacheBackend for testing
 type mockBackend struct {
+	pingError   error
 	data        map[string]mockEntry
+	stats       map[string]interface{}
 	mu          sync.RWMutex
+	getCalls    atomic.Int32
+	setCalls    atomic.Int32
+	deleteCalls atomic.Int32
 	failSet     bool
 	failGet     bool
 	failDelete  bool
 	failClear   bool
 	failPing    bool
-	pingError   error
-	stats       map[string]interface{}
-	getCalls    atomic.Int32
-	setCalls    atomic.Int32
-	deleteCalls atomic.Int32
 }
 
 type mockEntry struct {
-	value     []byte
 	expiresAt time.Time
+	value     []byte
 }
 
 // mockBatchBackend extends mockBackend with batch operations

internal/cache/backends/interface.go

@@ -41,53 +41,22 @@ type CacheBackend interface {
 
 // BackendStats represents statistics for a cache backend
 type BackendStats struct {
-	// Type is the backend type
-	Type BackendType
-
-	// Hits is the number of cache hits
-	Hits int64
-
-	// Misses is the number of cache misses
-	Misses int64
-
-	// Sets is the number of set operations
-	Sets int64
-
-	// Deletes is the number of delete operations
-	Deletes int64
-
-	// Errors is the number of errors
-	Errors int64
-
-	// Evictions is the number of evicted items
-	Evictions int64
-
-	// CurrentSize is the current number of items in cache
-	CurrentSize int64
-
-	// MaxSize is the maximum number of items (0 means unlimited)
-	MaxSize int64
-
-	// MemoryUsage is the approximate memory usage in bytes
-	MemoryUsage int64
-
-	// AverageGetLatency is the average latency for get operations
+	StartTime         time.Time
+	LastErrorTime     time.Time
+	Type              BackendType
+	LastError         string
+	Deletes           int64
+	Errors            int64
+	Evictions         int64
+	CurrentSize       int64
+	MaxSize           int64
+	MemoryUsage       int64
 	AverageGetLatency time.Duration
-
-	// AverageSetLatency is the average latency for set operations
 	AverageSetLatency time.Duration
-
-	// LastError is the last error encountered
-	LastError string
-
-	// LastErrorTime is when the last error occurred
-	LastErrorTime time.Time
-
-	// Uptime is how long the backend has been running
-	Uptime time.Duration
-
-	// StartTime is when the backend was started
-	StartTime time.Time
+	Sets              int64
+	Misses            int64
+	Uptime            time.Duration
+	Hits              int64
 }
 
 // BackendCapabilities describes the capabilities of a cache backend

internal/cache/backends/log_redact.go

@@ -0,0 +1,26 @@
+// 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

@@ -2,23 +2,30 @@
 package backends
 
 import (
-	"container/list"
 	"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 {
-	key         string
-	value       interface{}
 	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
-	element     *list.Element // for LRU tracking
 }
 
 // isExpired checks if the item is expired
@@ -29,17 +36,23 @@ func (item *memoryCacheItem) isExpired() bool {
 	return time.Now().After(item.expiresAt)
 }
 
-// MemoryCacheBackend implements the CacheBackend interface using in-memory storage
+// 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 {
-	mu            sync.RWMutex
-	items         map[string]*memoryCacheItem
-	lruList       *list.List
-	maxSize       int64
-	maxMemory     int64
-	currentSize   int64
-	currentMemory int64
+	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
 
-	// Statistics
+	// Global stats (aggregated from shards)
 	hits      atomic.Int64
 	misses    atomic.Int64
 	sets      atomic.Int64
@@ -53,40 +66,59 @@ type MemoryCacheBackend struct {
 	getCount     atomic.Int64
 	setCount     atomic.Int64
 
-	// Status
-	startTime     time.Time
-	lastError     string
-	lastErrorTime time.Time
-	cleanupTicker *time.Ticker
-	cleanupDone   chan bool
-	closed        atomic.Bool
-
-	// Configuration
-	cleanupInterval time.Duration
-	evictionPolicy  string // "lru", "lfu", "fifo"
+	// State
+	closed atomic.Bool
+	mu     sync.RWMutex // For global operations like stats and error tracking
 }
 
-// NewMemoryCacheBackend creates a new memory cache backend
+// NewMemoryCacheBackend creates a new sharded memory cache backend
 func NewMemoryCacheBackend(maxSize int64, maxMemory int64, cleanupInterval time.Duration) *MemoryCacheBackend {
 	if maxSize <= 0 {
-		maxSize = 10000 // Default to 10k items
+		maxSize = defaultMaxSize
 	}
 	if maxMemory <= 0 {
-		maxMemory = 100 * 1024 * 1024 // Default to 100MB
+		maxMemory = defaultMaxMemory
 	}
 	if cleanupInterval <= 0 {
-		cleanupInterval = 5 * time.Minute
+		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{
-		items:           make(map[string]*memoryCacheItem),
-		lruList:         list.New(),
+		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,
-		evictionPolicy:  "lru",
-		cleanupDone:     make(chan bool),
+		cleanupDone:     make(chan struct{}),
+	}
+
+	// Initialize shards
+	for i := uint32(0); i < shardCount; i++ {
+		m.shards[i] = newCacheShard(shardMaxSize, shardMaxMemory)
 	}
 
 	// Start cleanup goroutine
@@ -96,6 +128,12 @@ func NewMemoryCacheBackend(maxSize int64, maxMemory int64, cleanupInterval time.
 	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 {
@@ -108,20 +146,19 @@ func (m *MemoryCacheBackend) cleanupLoop() {
 	}
 }
 
-// cleanupExpired removes all expired items from the cache
+// cleanupExpired removes all expired items from all shards
 func (m *MemoryCacheBackend) cleanupExpired() {
-	m.mu.Lock()
-	defer m.mu.Unlock()
-
-	var keysToDelete []string
-	for key, item := range m.items {
-		if item.isExpired() {
-			keysToDelete = append(keysToDelete, key)
-		}
+	if m.closed.Load() {
+		return
 	}
 
-	for _, key := range keysToDelete {
-		m.deleteItemLocked(key)
+	totalRemoved := 0
+	for _, shard := range m.shards {
+		totalRemoved += shard.cleanup()
+	}
+
+	if totalRemoved > 0 {
+		m.evictions.Add(int64(totalRemoved))
 	}
 }
 
@@ -138,35 +175,23 @@ func (m *MemoryCacheBackend) Get(ctx context.Context, key string) (interface{},
 		m.getCount.Add(1)
 	}()
 
-	m.mu.RLock()
-	item, exists := m.items[key]
-	m.mu.RUnlock()
+	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
 	}
 
-	if item.isExpired() {
-		m.mu.Lock()
-		m.deleteItemLocked(key)
-		m.mu.Unlock()
-		m.misses.Add(1)
-		return nil, ErrCacheMiss
-	}
-
-	// Update access time and count
-	m.mu.Lock()
-	item.accessedAt = time.Now()
-	item.accessCount++
-	// Move to front of LRU list
-	if m.evictionPolicy == "lru" && item.element != nil {
-		m.lruList.MoveToFront(item.element)
-	}
-	m.mu.Unlock()
-
 	m.hits.Add(1)
-	return item.value, nil
+	return value, nil
 }
 
 // Set stores a value in the cache with optional TTL
@@ -182,113 +207,105 @@ func (m *MemoryCacheBackend) Set(ctx context.Context, key string, value interfac
 		m.setCount.Add(1)
 	}()
 
-	// Calculate item size (simplified estimation)
+	// Calculate item size
 	itemSize := int64(len(key)) + estimateValueSize(value)
 
-	m.mu.Lock()
-	defer m.mu.Unlock()
+	// Enforce global limits before adding new item
+	m.enforceGlobalLimits(itemSize)
 
-	// Check if we need to evict items
-	if m.currentSize >= m.maxSize || m.currentMemory+itemSize > m.maxMemory {
-		m.evictLocked()
-	}
-
-	// Check if key exists
-	if oldItem, exists := m.items[key]; exists {
-		m.currentMemory -= oldItem.size
-		if oldItem.element != nil {
-			m.lruList.Remove(oldItem.element)
-		}
-	} else {
-		m.currentSize++
-	}
-
-	now := time.Now()
 	var expiresAt time.Time
 	if ttl > 0 {
-		expiresAt = now.Add(ttl)
+		expiresAt = time.Now().Add(ttl)
 	}
 
-	item := &memoryCacheItem{
-		key:         key,
-		value:       value,
-		expiresAt:   expiresAt,
-		createdAt:   now,
-		accessedAt:  now,
-		accessCount: 0,
-		size:        itemSize,
-	}
+	shard := m.getShard(key)
+	shard.set(key, value, expiresAt, itemSize)
 
-	// Add to LRU list
-	if m.evictionPolicy == "lru" {
-		item.element = m.lruList.PushFront(item)
-	}
-
-	m.items[key] = item
-	m.currentMemory += 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
 	}
 
-	m.mu.Lock()
-	defer m.mu.Unlock()
-
-	if _, exists := m.items[key]; !exists {
-		return nil
+	shard := m.getShard(key)
+	if shard.delete(key) {
+		m.deletes.Add(1)
 	}
 
-	m.deleteItemLocked(key)
-	m.deletes.Add(1)
 	return nil
 }
 
-// deleteItemLocked deletes an item without acquiring the lock (must be called with lock held)
-func (m *MemoryCacheBackend) deleteItemLocked(key string) {
-	if item, exists := m.items[key]; exists {
-		m.currentMemory -= item.size
-		m.currentSize--
-		if item.element != nil {
-			m.lruList.Remove(item.element)
-		}
-		delete(m.items, key)
-	}
-}
-
-// evictLocked evicts items based on the eviction policy (must be called with lock held)
-func (m *MemoryCacheBackend) evictLocked() {
-	if m.evictionPolicy == "lru" && m.lruList.Len() > 0 {
-		// Evict least recently used item
-		element := m.lruList.Back()
-		if element != nil {
-			item := element.Value.(*memoryCacheItem)
-			m.deleteItemLocked(item.key)
-			m.evictions.Add(1)
-		}
-	}
-}
-
 // 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
 	}
 
-	m.mu.RLock()
-	item, exists := m.items[key]
-	m.mu.RUnlock()
-
-	if !exists {
-		return false, nil
-	}
-
-	return !item.isExpired(), nil
+	shard := m.getShard(key)
+	return shard.exists(key), nil
 }
 
 // Clear removes all items from the cache
@@ -297,13 +314,9 @@ func (m *MemoryCacheBackend) Clear(ctx context.Context) error {
 		return ErrBackendUnavailable
 	}
 
-	m.mu.Lock()
-	defer m.mu.Unlock()
-
-	m.items = make(map[string]*memoryCacheItem)
-	m.lruList = list.New()
-	m.currentSize = 0
-	m.currentMemory = 0
+	for _, shard := range m.shards {
+		shard.clear()
+	}
 
 	return nil
 }
@@ -314,29 +327,28 @@ func (m *MemoryCacheBackend) Keys(ctx context.Context, pattern string) ([]string
 		return nil, ErrBackendUnavailable
 	}
 
-	m.mu.RLock()
-	defer m.mu.RUnlock()
-
-	var keys []string
-	for key, item := range m.items {
-		if !item.isExpired() && matchPattern(pattern, key) {
-			keys = append(keys, key)
-		}
+	var allKeys []string
+	for _, shard := range m.shards {
+		keys := shard.keys(pattern)
+		allKeys = append(allKeys, keys...)
 	}
 
-	return keys, nil
+	return allKeys, nil
 }
 
-// Size returns the number of items in the cache
+// 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
 	}
 
-	m.mu.RLock()
-	defer m.mu.RUnlock()
+	var total int64
+	for _, shard := range m.shards {
+		size, _ := shard.stats()
+		total += size
+	}
 
-	return m.currentSize, nil
+	return total, nil
 }
 
 // TTL returns the remaining time-to-live for a key
@@ -345,24 +357,13 @@ func (m *MemoryCacheBackend) TTL(ctx context.Context, key string) (time.Duration
 		return 0, ErrBackendUnavailable
 	}
 
-	m.mu.RLock()
-	item, exists := m.items[key]
-	m.mu.RUnlock()
-
-	if !exists || item.isExpired() {
+	shard := m.getShard(key)
+	ttl, exists := shard.ttl(key)
+	if !exists {
 		return 0, ErrCacheMiss
 	}
 
-	if item.expiresAt.IsZero() {
-		return 0, nil // No expiration
-	}
-
-	remaining := time.Until(item.expiresAt)
-	if remaining < 0 {
-		return 0, nil
-	}
-
-	return remaining, nil
+	return ttl, nil
 }
 
 // Expire updates the TTL for an existing key
@@ -371,20 +372,11 @@ func (m *MemoryCacheBackend) Expire(ctx context.Context, key string, ttl time.Du
 		return ErrBackendUnavailable
 	}
 
-	m.mu.Lock()
-	defer m.mu.Unlock()
-
-	item, exists := m.items[key]
-	if !exists || item.isExpired() {
+	shard := m.getShard(key)
+	if !shard.expire(key, ttl) {
 		return ErrCacheMiss
 	}
 
-	if ttl > 0 {
-		item.expiresAt = time.Now().Add(ttl)
-	} else {
-		item.expiresAt = time.Time{} // Remove expiration
-	}
-
 	return nil
 }
 
@@ -394,6 +386,14 @@ func (m *MemoryCacheBackend) GetStats(ctx context.Context) (*BackendStats, error
 		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
@@ -417,9 +417,9 @@ func (m *MemoryCacheBackend) GetStats(ctx context.Context) (*BackendStats, error
 		Deletes:           m.deletes.Load(),
 		Errors:            m.errors.Load(),
 		Evictions:         m.evictions.Load(),
-		CurrentSize:       m.currentSize,
+		CurrentSize:       totalSize,
 		MaxSize:           m.maxSize,
-		MemoryUsage:       m.currentMemory,
+		MemoryUsage:       totalMemory,
 		AverageGetLatency: avgGetLatency,
 		AverageSetLatency: avgSetLatency,
 		LastError:         lastError,
@@ -446,10 +446,10 @@ func (m *MemoryCacheBackend) Close() error {
 	m.cleanupTicker.Stop()
 	close(m.cleanupDone)
 
-	m.mu.Lock()
-	m.items = nil
-	m.lruList = nil
-	m.mu.Unlock()
+	// Clear all shards
+	for _, shard := range m.shards {
+		shard.clear()
+	}
 
 	return nil
 }
@@ -482,12 +482,28 @@ func (m *MemoryCacheBackend) Capabilities() *BackendCapabilities {
 	}
 }
 
+// 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 {
-	// This is a simplified estimation
-	// In production, you might want to use a more accurate method
 	switch v := value.(type) {
 	case string:
 		return int64(len(v))
@@ -510,7 +526,10 @@ func matchPattern(pattern, key string) bool {
 	if pattern == "*" {
 		return true
 	}
-	// Simplified pattern matching - in production, use a proper glob library
-	return key == pattern || (len(pattern) > 0 && pattern[0] == '*' &&
-		len(key) >= len(pattern)-1 && key[len(key)-len(pattern)+1:] == pattern[1:])
+	// 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_shard.go

@@ -0,0 +1,294 @@
+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

@@ -0,0 +1,283 @@
+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_wrapper.go

@@ -45,21 +45,11 @@ func (m *MemoryBackend) Get(ctx context.Context, key string) ([]byte, time.Durat
 		return nil, 0, false, err
 	}
 
-	// Get the item directly to check TTL
-	m.MemoryCacheBackend.mu.RLock()
-	item, exists := m.MemoryCacheBackend.items[key]
-	m.MemoryCacheBackend.mu.RUnlock()
-
-	if !exists {
-		return nil, 0, false, nil
-	}
-
-	var ttl time.Duration
-	if !item.expiresAt.IsZero() {
-		ttl = time.Until(item.expiresAt)
-		if ttl < 0 {
-			ttl = 0
-		}
+	// 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
@@ -68,8 +58,7 @@ func (m *MemoryBackend) Get(ctx context.Context, key string) ([]byte, time.Durat
 		if bytes, ok := val.([]byte); ok {
 			valueBytes = bytes
 		} else {
-			// If it's not already []byte, we might need to handle other types
-			// For now, we'll just return an error
+			// If it's not already []byte, return an error
 			return nil, 0, false, ErrInvalidValue
 		}
 	}
@@ -123,19 +112,20 @@ func (m *MemoryBackend) GetStats() map[string]interface{} {
 	}
 
 	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,
+		"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(),
 	}
 }
 

internal/cache/backends/redis.go

@@ -49,6 +49,7 @@ func NewRedisBackend(config *Config) (*RedisBackend, error) {
 	poolConfig := &PoolConfig{
 		Address:           config.RedisAddr,
 		Password:          config.RedisPassword,
+		TLSServerName:     config.TLSServerName,
 		DB:                config.RedisDB,
 		MaxConnections:    config.PoolSize,
 		ConnectTimeout:    2 * time.Second,
@@ -57,6 +58,8 @@ func NewRedisBackend(config *Config) (*RedisBackend, error) {
 		EnableHealthCheck: true,
 		MaxRetries:        3,
 		RetryDelay:        100 * time.Millisecond,
+		EnableTLS:         config.EnableTLS,
+		TLSSkipVerify:     config.TLSSkipVerify,
 	}
 
 	pool, err := NewConnectionPool(poolConfig)
@@ -345,7 +348,7 @@ func (r *RedisBackend) prefixKey(key string) string {
 
 // executeWithRetry executes a Redis operation with exponential backoff retry logic.
 // It checks context cancellation at multiple points to ensure fast abort when the
-// caller's context is cancelled (e.g., due to request timeout).
+// caller's context is canceled (e.g., due to request timeout).
 func (r *RedisBackend) executeWithRetry(ctx context.Context, operation func(*RedisConn) error) error {
 	maxRetries := 3
 	baseDelay := 50 * time.Millisecond // Reduced from 100ms to fail faster
@@ -377,7 +380,7 @@ func (r *RedisBackend) executeWithRetry(ctx context.Context, operation func(*Red
 		err = operation(conn)
 		r.pool.Put(conn)
 
-		// Check context after operation - if cancelled, don't bother retrying
+		// Check context after operation - if canceled, don't bother retrying
 		if ctx.Err() != nil {
 			return ctx.Err()
 		}
@@ -431,39 +434,135 @@ func isRetryableError(err error) bool {
 	return false
 }
 
-// SetMany stores multiple values in Redis (batch operation)
+// SetMany stores multiple values in Redis using pipelining for efficiency
+// This reduces N round-trips to a single round-trip
 func (r *RedisBackend) SetMany(ctx context.Context, items map[string][]byte, ttl time.Duration) error {
 	if r.closed.Load() {
 		return ErrBackendClosed
 	}
 
-	// For simplicity, execute sequentially (can be optimized with pipelining later)
-	for key, value := range items {
-		if err := r.Set(ctx, key, value, ttl); err != nil {
-			return err
+	if len(items) == 0 {
+		return nil
+	}
+
+	// For single items, use regular Set
+	if len(items) == 1 {
+		for key, value := range items {
+			return r.Set(ctx, key, value, ttl)
 		}
 	}
 
+	conn, err := r.pool.Get(ctx)
+	if err != nil {
+		return err
+	}
+	defer r.pool.Put(conn)
+
+	pipeline := conn.NewPipeline()
+
+	// Queue all SET commands
+	ttlSeconds := int(ttl.Seconds())
+	ttlMillis := ttl.Milliseconds()
+
+	for key, value := range items {
+		prefixedKey := r.prefixKey(key)
+
+		if ttl > 0 {
+			if ttlMillis < 1000 {
+				// Use PSETEX for sub-second TTLs
+				pipeline.Queue("PSETEX", prefixedKey, fmt.Sprintf("%d", ttlMillis), string(value))
+			} else {
+				// Use SETEX for larger TTLs
+				pipeline.Queue("SETEX", prefixedKey, fmt.Sprintf("%d", ttlSeconds), string(value))
+			}
+		} else {
+			pipeline.Queue("SET", prefixedKey, string(value))
+		}
+	}
+
+	// Execute pipeline
+	responses, err := pipeline.Execute()
+	if err != nil {
+		return fmt.Errorf("pipeline SetMany failed: %w", err)
+	}
+
+	// Check responses for errors (each should be "OK")
+	for i, resp := range responses {
+		if resp == nil {
+			continue
+		}
+		if str, ok := resp.(string); ok && str == "OK" {
+			continue
+		}
+		return fmt.Errorf("SetMany: unexpected response at index %d: %v", i, resp)
+	}
+
 	return nil
 }
 
-// GetMany retrieves multiple values from Redis
+// GetMany retrieves multiple values from Redis using pipelining for efficiency
+// This reduces N round-trips to a single round-trip
 func (r *RedisBackend) GetMany(ctx context.Context, keys []string) (map[string][]byte, error) {
 	if r.closed.Load() {
 		return nil, ErrBackendClosed
 	}
 
-	result := make(map[string][]byte)
+	if len(keys) == 0 {
+		return make(map[string][]byte), nil
+	}
 
-	// For simplicity, execute sequentially
-	for _, key := range keys {
-		value, _, exists, err := r.Get(ctx, key)
+	// For single key, use regular Get
+	if len(keys) == 1 {
+		result := make(map[string][]byte)
+		value, _, exists, err := r.Get(ctx, keys[0])
 		if err != nil {
 			return nil, err
 		}
 		if exists {
-			result[key] = value
+			result[keys[0]] = value
 		}
+		return result, nil
+	}
+
+	conn, err := r.pool.Get(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer r.pool.Put(conn)
+
+	pipeline := conn.NewPipeline()
+
+	// Queue all GET commands
+	prefixedKeys := make([]string, len(keys))
+	for i, key := range keys {
+		prefixedKeys[i] = r.prefixKey(key)
+		pipeline.Queue("GET", prefixedKeys[i])
+	}
+
+	// Execute pipeline
+	responses, err := pipeline.Execute()
+	if err != nil {
+		return nil, fmt.Errorf("pipeline GetMany failed: %w", err)
+	}
+
+	// Process responses
+	result := make(map[string][]byte)
+	for i, resp := range responses {
+		if resp == nil {
+			// Key doesn't exist
+			r.misses.Add(1)
+			continue
+		}
+
+		value, err := RESPString(resp)
+		if err != nil {
+			// Invalid response, skip this key
+			r.misses.Add(1)
+			continue
+		}
+
+		r.hits.Add(1)
+		result[keys[i]] = []byte(value)
 	}
 
 	return result, nil

internal/cache/backends/redis_health.go

@@ -9,30 +9,24 @@ import (
 
 // HealthMonitor continuously monitors Redis connection health and triggers reconnections
 type HealthMonitor struct {
-	pool   *ConnectionPool
-	config *HealthMonitorConfig
-
-	// State
-	healthy       atomic.Bool
-	running       atomic.Bool
-	lastCheckTime atomic.Int64 // Unix timestamp
-
-	// Metrics
+	pool                *ConnectionPool
+	config              *HealthMonitorConfig
+	stopChan            chan struct{}
+	wg                  sync.WaitGroup
+	lastCheckTime       atomic.Int64
 	consecutiveFailures atomic.Int64
 	totalChecks         atomic.Int64
 	totalFailures       atomic.Int64
-
-	// Lifecycle
-	stopChan chan struct{}
-	wg       sync.WaitGroup
+	healthy             atomic.Bool
+	running             atomic.Bool
 }
 
 // HealthMonitorConfig configures the health monitor
 type HealthMonitorConfig struct {
-	CheckInterval      time.Duration // How often to check health
-	Timeout            time.Duration // Timeout for health check
-	UnhealthyThreshold int           // Consecutive failures before marking unhealthy
 	OnHealthChange     func(healthy bool)
+	CheckInterval      time.Duration
+	Timeout            time.Duration
+	UnhealthyThreshold int
 }
 
 // DefaultHealthMonitorConfig returns default health monitor configuration

internal/cache/backends/redis_pipeline_test.go

@@ -0,0 +1,461 @@
+package backends
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// setupTestRedis creates a miniredis instance for testing
+func setupTestRedis(t *testing.T) (*miniredis.Miniredis, *RedisBackend) {
+	t.Helper()
+
+	mr, err := miniredis.Run()
+	require.NoError(t, err)
+
+	t.Cleanup(func() {
+		mr.Close()
+	})
+
+	backend, err := NewRedisBackend(&Config{
+		RedisAddr:   mr.Addr(),
+		RedisPrefix: "test:",
+		PoolSize:    5,
+	})
+	require.NoError(t, err)
+
+	t.Cleanup(func() {
+		backend.Close()
+	})
+
+	return mr, backend
+}
+
+// TestPipeline_Basic tests basic pipeline functionality
+func TestPipeline_Basic(t *testing.T) {
+	t.Parallel()
+
+	mr, err := miniredis.Run()
+	require.NoError(t, err)
+	defer mr.Close()
+
+	config := &PoolConfig{
+		Address:        mr.Addr(),
+		MaxConnections: 5,
+		ConnectTimeout: 5 * time.Second,
+		ReadTimeout:    1 * time.Second,
+		WriteTimeout:   1 * time.Second,
+	}
+
+	pool, err := NewConnectionPool(config)
+	require.NoError(t, err)
+	defer pool.Close()
+
+	ctx := context.Background()
+
+	conn, err := pool.Get(ctx)
+	require.NoError(t, err)
+	defer pool.Put(conn)
+
+	t.Run("SingleCommand", func(t *testing.T) {
+		pipeline := conn.NewPipeline()
+		pipeline.Queue("SET", "single-key", "single-value")
+
+		responses, err := pipeline.Execute()
+		require.NoError(t, err)
+		require.Len(t, responses, 1)
+		assert.Equal(t, "OK", responses[0])
+	})
+
+	t.Run("MultipleCommands", func(t *testing.T) {
+		pipeline := conn.NewPipeline()
+		pipeline.Queue("SET", "key1", "value1")
+		pipeline.Queue("SET", "key2", "value2")
+		pipeline.Queue("SET", "key3", "value3")
+		pipeline.Queue("GET", "key1")
+		pipeline.Queue("GET", "key2")
+		pipeline.Queue("GET", "key3")
+
+		responses, err := pipeline.Execute()
+		require.NoError(t, err)
+		require.Len(t, responses, 6)
+
+		// First 3 are SET responses
+		assert.Equal(t, "OK", responses[0])
+		assert.Equal(t, "OK", responses[1])
+		assert.Equal(t, "OK", responses[2])
+
+		// Last 3 are GET responses
+		assert.Equal(t, "value1", responses[3])
+		assert.Equal(t, "value2", responses[4])
+		assert.Equal(t, "value3", responses[5])
+	})
+
+	t.Run("EmptyPipeline", func(t *testing.T) {
+		pipeline := conn.NewPipeline()
+
+		responses, err := pipeline.Execute()
+		require.NoError(t, err)
+		assert.Nil(t, responses)
+	})
+
+	t.Run("NilResponses", func(t *testing.T) {
+		pipeline := conn.NewPipeline()
+		pipeline.Queue("GET", "nonexistent-key")
+
+		responses, err := pipeline.Execute()
+		require.NoError(t, err)
+		require.Len(t, responses, 1)
+		assert.Nil(t, responses[0])
+	})
+}
+
+// TestPipeline_SetMany tests pipelined SetMany
+func TestPipeline_SetMany(t *testing.T) {
+	t.Parallel()
+
+	_, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	t.Run("SetManyItems", func(t *testing.T) {
+		items := make(map[string][]byte)
+		for i := 0; i < 10; i++ {
+			items[fmt.Sprintf("setmany-key-%d", i)] = []byte(fmt.Sprintf("value-%d", i))
+		}
+
+		err := backend.SetMany(ctx, items, time.Minute)
+		require.NoError(t, err)
+
+		// Verify all items were set
+		for key, expectedValue := range items {
+			value, _, exists, err := backend.Get(ctx, key)
+			require.NoError(t, err)
+			assert.True(t, exists, "Key %s should exist", key)
+			assert.Equal(t, expectedValue, value)
+		}
+	})
+
+	t.Run("SetManyEmpty", func(t *testing.T) {
+		err := backend.SetMany(ctx, map[string][]byte{}, time.Minute)
+		require.NoError(t, err)
+	})
+
+	t.Run("SetManySingleItem", func(t *testing.T) {
+		items := map[string][]byte{
+			"single-setmany": []byte("single-value"),
+		}
+
+		err := backend.SetMany(ctx, items, time.Minute)
+		require.NoError(t, err)
+
+		value, _, exists, err := backend.Get(ctx, "single-setmany")
+		require.NoError(t, err)
+		assert.True(t, exists)
+		assert.Equal(t, []byte("single-value"), value)
+	})
+
+	t.Run("SetManyNoTTL", func(t *testing.T) {
+		items := map[string][]byte{
+			"nottl-key1": []byte("value1"),
+			"nottl-key2": []byte("value2"),
+		}
+
+		err := backend.SetMany(ctx, items, 0)
+		require.NoError(t, err)
+
+		// Keys should exist
+		for key := range items {
+			exists, err := backend.Exists(ctx, key)
+			require.NoError(t, err)
+			assert.True(t, exists)
+		}
+	})
+}
+
+// TestPipeline_GetMany tests pipelined GetMany
+func TestPipeline_GetMany(t *testing.T) {
+	t.Parallel()
+
+	_, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	// Pre-populate cache
+	for i := 0; i < 10; i++ {
+		key := fmt.Sprintf("getmany-key-%d", i)
+		value := []byte(fmt.Sprintf("value-%d", i))
+		err := backend.Set(ctx, key, value, time.Minute)
+		require.NoError(t, err)
+	}
+
+	t.Run("GetManyExisting", func(t *testing.T) {
+		keys := make([]string, 10)
+		for i := 0; i < 10; i++ {
+			keys[i] = fmt.Sprintf("getmany-key-%d", i)
+		}
+
+		results, err := backend.GetMany(ctx, keys)
+		require.NoError(t, err)
+		assert.Len(t, results, 10)
+
+		for i, key := range keys {
+			assert.Equal(t, []byte(fmt.Sprintf("value-%d", i)), results[key])
+		}
+	})
+
+	t.Run("GetManyMixed", func(t *testing.T) {
+		keys := []string{
+			"getmany-key-0",     // exists
+			"nonexistent-key-1", // doesn't exist
+			"getmany-key-2",     // exists
+			"nonexistent-key-2", // doesn't exist
+		}
+
+		results, err := backend.GetMany(ctx, keys)
+		require.NoError(t, err)
+		assert.Len(t, results, 2) // Only existing keys
+
+		assert.Equal(t, []byte("value-0"), results["getmany-key-0"])
+		assert.Equal(t, []byte("value-2"), results["getmany-key-2"])
+		assert.NotContains(t, results, "nonexistent-key-1")
+		assert.NotContains(t, results, "nonexistent-key-2")
+	})
+
+	t.Run("GetManyEmpty", func(t *testing.T) {
+		results, err := backend.GetMany(ctx, []string{})
+		require.NoError(t, err)
+		assert.NotNil(t, results)
+		assert.Len(t, results, 0)
+	})
+
+	t.Run("GetManySingleKey", func(t *testing.T) {
+		results, err := backend.GetMany(ctx, []string{"getmany-key-5"})
+		require.NoError(t, err)
+		assert.Len(t, results, 1)
+		assert.Equal(t, []byte("value-5"), results["getmany-key-5"])
+	})
+
+	t.Run("GetManyAllNonexistent", func(t *testing.T) {
+		keys := []string{
+			"nonexistent-1",
+			"nonexistent-2",
+			"nonexistent-3",
+		}
+
+		results, err := backend.GetMany(ctx, keys)
+		require.NoError(t, err)
+		assert.Len(t, results, 0)
+	})
+}
+
+// TestPipeline_LargeBatch tests pipelining with large batches
+func TestPipeline_LargeBatch(t *testing.T) {
+	t.Parallel()
+
+	_, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	t.Run("SetMany100Items", func(t *testing.T) {
+		items := make(map[string][]byte)
+		for i := 0; i < 100; i++ {
+			items[fmt.Sprintf("large-batch-%d", i)] = []byte(fmt.Sprintf("value-%d", i))
+		}
+
+		err := backend.SetMany(ctx, items, time.Minute)
+		require.NoError(t, err)
+
+		// Verify random samples
+		for _, i := range []int{0, 25, 50, 75, 99} {
+			key := fmt.Sprintf("large-batch-%d", i)
+			value, _, exists, err := backend.Get(ctx, key)
+			require.NoError(t, err)
+			assert.True(t, exists)
+			assert.Equal(t, []byte(fmt.Sprintf("value-%d", i)), value)
+		}
+	})
+
+	t.Run("GetMany100Items", func(t *testing.T) {
+		keys := make([]string, 100)
+		for i := 0; i < 100; i++ {
+			keys[i] = fmt.Sprintf("large-batch-%d", i)
+		}
+
+		results, err := backend.GetMany(ctx, keys)
+		require.NoError(t, err)
+		assert.Len(t, results, 100)
+	})
+}
+
+// TestPipeline_Stats tests that stats are tracked correctly with pipelining
+func TestPipeline_Stats(t *testing.T) {
+	t.Parallel()
+
+	_, backend := setupTestRedis(t)
+	ctx := context.Background()
+
+	// Set some items
+	items := map[string][]byte{
+		"stats-key-1": []byte("value1"),
+		"stats-key-2": []byte("value2"),
+	}
+	err := backend.SetMany(ctx, items, time.Minute)
+	require.NoError(t, err)
+
+	// Get items (some exist, some don't)
+	keys := []string{
+		"stats-key-1",
+		"stats-key-2",
+		"stats-key-nonexistent",
+	}
+	results, err := backend.GetMany(ctx, keys)
+	require.NoError(t, err)
+	assert.Len(t, results, 2)
+
+	// Check stats
+	stats := backend.GetStats()
+	hits := stats["hits"].(int64)
+	misses := stats["misses"].(int64)
+
+	assert.Equal(t, int64(2), hits, "Should have 2 hits")
+	assert.Equal(t, int64(1), misses, "Should have 1 miss")
+}
+
+// BenchmarkPipeline_SetMany benchmarks SetMany with pipelining
+func BenchmarkPipeline_SetMany(b *testing.B) {
+	mr, err := miniredis.Run()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer mr.Close()
+
+	backend, err := NewRedisBackend(&Config{
+		RedisAddr:   mr.Addr(),
+		RedisPrefix: "bench:",
+		PoolSize:    10,
+	})
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Prepare items
+	items := make(map[string][]byte)
+	for i := 0; i < 100; i++ {
+		items[fmt.Sprintf("bench-key-%d", i)] = []byte(fmt.Sprintf("bench-value-%d", i))
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = backend.SetMany(ctx, items, time.Minute)
+	}
+}
+
+// BenchmarkPipeline_GetMany benchmarks GetMany with pipelining
+func BenchmarkPipeline_GetMany(b *testing.B) {
+	mr, err := miniredis.Run()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer mr.Close()
+
+	backend, err := NewRedisBackend(&Config{
+		RedisAddr:   mr.Addr(),
+		RedisPrefix: "bench:",
+		PoolSize:    10,
+	})
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Pre-populate cache
+	for i := 0; i < 100; i++ {
+		key := fmt.Sprintf("bench-key-%d", i)
+		value := []byte(fmt.Sprintf("bench-value-%d", i))
+		backend.Set(ctx, key, value, time.Hour)
+	}
+
+	// Prepare keys
+	keys := make([]string, 100)
+	for i := 0; i < 100; i++ {
+		keys[i] = fmt.Sprintf("bench-key-%d", i)
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = backend.GetMany(ctx, keys)
+	}
+}
+
+// BenchmarkPipeline_VsSequential benchmarks pipeline vs sequential operations
+func BenchmarkPipeline_VsSequential(b *testing.B) {
+	mr, err := miniredis.Run()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer mr.Close()
+
+	backend, err := NewRedisBackend(&Config{
+		RedisAddr:   mr.Addr(),
+		RedisPrefix: "bench:",
+		PoolSize:    10,
+	})
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer backend.Close()
+
+	ctx := context.Background()
+
+	// Prepare items
+	items := make(map[string][]byte)
+	keys := make([]string, 50)
+	for i := 0; i < 50; i++ {
+		key := fmt.Sprintf("compare-key-%d", i)
+		keys[i] = key
+		items[key] = []byte(fmt.Sprintf("compare-value-%d", i))
+	}
+
+	b.Run("Pipelined-Set", func(b *testing.B) {
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			_ = backend.SetMany(ctx, items, time.Minute)
+		}
+	})
+
+	b.Run("Sequential-Set", func(b *testing.B) {
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			for key, value := range items {
+				_ = backend.Set(ctx, key, value, time.Minute)
+			}
+		}
+	})
+
+	// Pre-populate for get benchmarks
+	_ = backend.SetMany(ctx, items, time.Hour)
+
+	b.Run("Pipelined-Get", func(b *testing.B) {
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			_, _ = backend.GetMany(ctx, keys)
+		}
+	})
+
+	b.Run("Sequential-Get", func(b *testing.B) {
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			for _, key := range keys {
+				_, _, _, _ = backend.Get(ctx, key)
+			}
+		}
+	})
+}

internal/cache/backends/redis_pool.go

@@ -2,6 +2,7 @@ package backends
 
 import (
 	"context"
+	"crypto/tls"
 	"errors"
 	"fmt"
 	"net"
@@ -31,6 +32,7 @@ type ConnectionPool struct {
 type PoolConfig struct {
 	Address           string
 	Password          string
+	TLSServerName     string // SNI server name; defaults to host(Address) when empty
 	DB                int
 	MaxConnections    int
 	ConnectTimeout    time.Duration
@@ -39,6 +41,8 @@ type PoolConfig struct {
 	EnableHealthCheck bool          // Enable connection health validation
 	MaxRetries        int           // Max retries for failed operations
 	RetryDelay        time.Duration // Initial delay between retries
+	EnableTLS         bool          // Wrap connection with TLS (e.g. AWS ElastiCache in-transit encryption)
+	TLSSkipVerify     bool          // Skip server certificate verification (escape hatch; not recommended)
 }
 
 // NewConnectionPool creates a new connection pool
@@ -96,7 +100,7 @@ func (p *ConnectionPool) Get(ctx context.Context) (*RedisConn, error) {
 			// 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) {
-				conn, err = p.createConnection()
+				conn, err = p.createConnection(ctx)
 				if err != nil {
 					// If this is the last attempt, return error
 					if attempt == maxAttempts-1 {
@@ -193,13 +197,31 @@ func (p *ConnectionPool) Stats() map[string]interface{} {
 }
 
 // createConnection creates a new Redis connection
-func (p *ConnectionPool) createConnection() (*RedisConn, error) {
+func (p *ConnectionPool) createConnection(ctx context.Context) (*RedisConn, error) {
 	// Connect with timeout
 	dialer := &net.Dialer{
 		Timeout: p.config.ConnectTimeout,
 	}
 
-	conn, err := dialer.Dial("tcp", p.config.Address)
+	var conn net.Conn
+	var err error
+	if p.config.EnableTLS {
+		serverName := p.config.TLSServerName
+		if serverName == "" {
+			if host, _, splitErr := net.SplitHostPort(p.config.Address); splitErr == nil {
+				serverName = host
+			}
+		}
+		tlsCfg := &tls.Config{
+			ServerName:         serverName,
+			InsecureSkipVerify: p.config.TLSSkipVerify, // #nosec G402 -- opt-in escape hatch via TLSSkipVerify config
+			MinVersion:         tls.VersionTLS12,
+		}
+		tlsDialer := &tls.Dialer{NetDialer: dialer, Config: tlsCfg}
+		conn, err = tlsDialer.DialContext(ctx, "tcp", p.config.Address)
+	} else {
+		conn, err = dialer.DialContext(ctx, "tcp", p.config.Address)
+	}
 	if err != nil {
 		return nil, fmt.Errorf("failed to connect to Redis: %w", err)
 	}
@@ -336,3 +358,120 @@ func (p *ConnectionPool) isConnectionHealthy(conn *RedisConn) bool {
 	_, err := conn.Do("PING")
 	return err == nil
 }
+
+// Pipeline represents a Redis pipeline for batch operations
+// It queues multiple commands and executes them in a single round-trip
+type Pipeline struct {
+	conn     *RedisConn
+	commands []pipelineCommand
+	mu       sync.Mutex
+}
+
+// pipelineCommand represents a single command in the pipeline
+type pipelineCommand struct {
+	command string
+	args    []string
+}
+
+// NewPipeline creates a new pipeline for the connection
+func (c *RedisConn) NewPipeline() *Pipeline {
+	return &Pipeline{
+		conn:     c,
+		commands: make([]pipelineCommand, 0, 16), // Pre-allocate for typical batch size
+	}
+}
+
+// Queue adds a command to the pipeline
+func (p *Pipeline) Queue(command string, args ...string) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	p.commands = append(p.commands, pipelineCommand{
+		command: command,
+		args:    args,
+	})
+}
+
+// Execute sends all queued commands and returns all responses
+// Returns a slice of responses in the same order as commands were queued
+func (p *Pipeline) Execute() ([]interface{}, error) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if len(p.commands) == 0 {
+		return nil, nil
+	}
+
+	if p.conn.closed.Load() {
+		return nil, ErrBackendClosed
+	}
+
+	p.conn.mu.Lock()
+	defer p.conn.mu.Unlock()
+
+	// Set write timeout for all commands
+	if p.conn.writeTimeout > 0 {
+		// Use longer timeout for batch operations
+		timeout := p.conn.writeTimeout * time.Duration(len(p.commands))
+		if timeout > 30*time.Second {
+			timeout = 30 * time.Second // Cap at 30 seconds
+		}
+		_ = p.conn.conn.SetWriteDeadline(time.Now().Add(timeout))
+	}
+
+	// Write all commands (pipelining - send all before reading any responses)
+	writer := NewRESPWriter(p.conn.conn)
+	for _, cmd := range p.commands {
+		cmdArgs := append([]string{cmd.command}, cmd.args...)
+		if err := writer.WriteCommand(cmdArgs...); err != nil {
+			writer.Release()
+			p.conn.closed.Store(true)
+			return nil, fmt.Errorf("pipeline write error: %w", err)
+		}
+	}
+	writer.Release()
+
+	// Set read timeout for all responses
+	if p.conn.readTimeout > 0 {
+		timeout := p.conn.readTimeout * time.Duration(len(p.commands))
+		if timeout > 30*time.Second {
+			timeout = 30 * time.Second
+		}
+		_ = p.conn.conn.SetReadDeadline(time.Now().Add(timeout))
+	}
+
+	// Read all responses
+	responses := make([]interface{}, len(p.commands))
+	reader := NewRESPReader(p.conn.conn)
+	defer reader.Release()
+
+	for i := range p.commands {
+		resp, err := reader.ReadResponse()
+		if err != nil {
+			// For nil responses, store nil instead of erroring
+			if errors.Is(err, ErrNilResponse) {
+				responses[i] = nil
+				continue
+			}
+			p.conn.closed.Store(true)
+			return responses[:i], fmt.Errorf("pipeline read error at command %d: %w", i, err)
+		}
+		responses[i] = resp
+	}
+
+	return responses, nil
+}
+
+// Clear resets the pipeline for reuse
+func (p *Pipeline) Clear() {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.commands = p.commands[:0]
+}
+
+// Len returns the number of queued commands
+func (p *Pipeline) Len() int {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return len(p.commands)
+}

internal/cache/backends/redis_pool_test.go

@@ -3,6 +3,7 @@ package backends
 import (
 	"context"
 	"errors"
+	"strings"
 	"sync"
 	"testing"
 	"time"
@@ -201,7 +202,7 @@ func TestConnectionPool_ContextCancellation(t *testing.T) {
 	conn, err := pool.Get(context.Background())
 	require.NoError(t, err)
 
-	// Try to get another with cancelled context
+	// Try to get another with canceled context
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel() // Cancel immediately
 
@@ -617,4 +618,33 @@ func TestRedisConn_TooManyArguments(t *testing.T) {
 			assert.NotContains(t, err.Error(), "too many arguments")
 		}
 	})
+
+}
+
+// TestRedisConn_RejectOversizedArgumentBytes is a regression test for CodeQL
+// alert #10 (go/allocation-size-overflow). A single argument larger than
+// maxTotalArgBytes (64 MiB) must be rejected by the per-argument overflow
+// guard in Do() before any allocation is attempted.
+func TestRedisConn_RejectOversizedArgumentBytes(t *testing.T) {
+	mr := NewMiniredisServer(t)
+
+	pool, err := NewConnectionPool(&PoolConfig{
+		Address:        mr.GetAddr(),
+		MaxConnections: 1,
+		ConnectTimeout: 5 * time.Second,
+		ReadTimeout:    3 * time.Second,
+		WriteTimeout:   3 * time.Second,
+	})
+	require.NoError(t, err)
+	defer pool.Close()
+
+	conn, err := pool.Get(context.Background())
+	require.NoError(t, err)
+	defer pool.Put(conn)
+
+	largeArg := strings.Repeat("x", (64<<20)+1)
+
+	_, err = conn.Do("SET", "k", largeArg)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "arguments too large")
 }

internal/cache/backends/redis_pool_tls_test.go

@@ -0,0 +1,230 @@
+package backends
+
+import (
+	"bufio"
+	"context"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"math/big"
+	"net"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// drainRESPRequest consumes a single RESP request (array or inline) from r and
+// returns true on success. Any read error returns false.
+func drainRESPRequest(r *bufio.Reader) bool {
+	header, err := r.ReadString('\n')
+	if err != nil {
+		return false
+	}
+	if !strings.HasPrefix(header, "*") {
+		return true // inline command (single line) — already consumed
+	}
+	n, err := strconv.Atoi(strings.TrimRight(strings.TrimPrefix(header, "*"), "\r\n"))
+	if err != nil || n <= 0 {
+		return false
+	}
+	for i := 0; i < n; i++ {
+		// Each bulk: "$len\r\n<bytes>\r\n"
+		if _, err := r.ReadString('\n'); err != nil {
+			return false
+		}
+		if _, err := r.ReadString('\n'); err != nil {
+			return false
+		}
+	}
+	return true
+}
+
+// startTLSPingServer spins up a TLS listener that speaks just enough RESP to
+// answer PING with +PONG. Returns the listener address and a self-signed cert.
+func startTLSPingServer(t *testing.T) (addr string, certPEM []byte, stop func()) {
+	t.Helper()
+
+	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	require.NoError(t, err)
+
+	template := &x509.Certificate{
+		SerialNumber: big.NewInt(1),
+		Subject:      pkix.Name{CommonName: "localhost"},
+		NotBefore:    time.Now().Add(-time.Hour),
+		NotAfter:     time.Now().Add(time.Hour),
+		KeyUsage:     x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
+		ExtKeyUsage:  []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+		DNSNames:     []string{"localhost"},
+		IPAddresses:  []net.IP{net.ParseIP("127.0.0.1")},
+	}
+	der, err := x509.CreateCertificate(rand.Reader, template, template, &priv.PublicKey, priv)
+	require.NoError(t, err)
+
+	tlsCert := tls.Certificate{
+		Certificate: [][]byte{der},
+		PrivateKey:  priv,
+	}
+
+	listener, err := tls.Listen("tcp", "127.0.0.1:0", &tls.Config{
+		Certificates: []tls.Certificate{tlsCert},
+		MinVersion:   tls.VersionTLS12,
+	})
+	require.NoError(t, err)
+
+	var wg sync.WaitGroup
+	stopCh := make(chan struct{})
+
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for {
+			select {
+			case <-stopCh:
+				return
+			default:
+			}
+			c, acceptErr := listener.Accept()
+			if acceptErr != nil {
+				return
+			}
+			wg.Add(1)
+			go func(conn net.Conn) {
+				defer wg.Done()
+				defer conn.Close()
+				reader := bufio.NewReader(conn)
+				for {
+					_ = conn.SetReadDeadline(time.Now().Add(2 * time.Second))
+					if !drainRESPRequest(reader) {
+						return
+					}
+					_, _ = conn.Write([]byte("+PONG\r\n"))
+				}
+			}(c)
+		}
+	}()
+
+	stop = func() {
+		close(stopCh)
+		_ = listener.Close()
+		wg.Wait()
+	}
+	return listener.Addr().String(), der, stop
+}
+
+// TestConnectionPool_TLSDial_SkipVerify verifies that EnableTLS=true with
+// TLSSkipVerify=true successfully negotiates TLS and exchanges a Redis command.
+// Regression test for issue #133 (enableTLS not propagated to client).
+func TestConnectionPool_TLSDial_SkipVerify(t *testing.T) {
+	addr, _, stop := startTLSPingServer(t)
+	defer stop()
+
+	pool, err := NewConnectionPool(&PoolConfig{
+		Address:        addr,
+		MaxConnections: 2,
+		ConnectTimeout: 2 * time.Second,
+		ReadTimeout:    1 * time.Second,
+		WriteTimeout:   1 * time.Second,
+		EnableTLS:      true,
+		TLSSkipVerify:  true,
+	})
+	require.NoError(t, err)
+	defer pool.Close()
+
+	conn, err := pool.Get(context.Background())
+	require.NoError(t, err)
+	require.NotNil(t, conn)
+	defer pool.Put(conn)
+
+	resp, err := conn.Do("PING")
+	require.NoError(t, err)
+	assert.Equal(t, "PONG", resp)
+}
+
+// TestConnectionPool_TLSDial_VerifyFails verifies that EnableTLS=true with
+// TLSSkipVerify=false rejects a self-signed server cert.
+func TestConnectionPool_TLSDial_VerifyFails(t *testing.T) {
+	addr, _, stop := startTLSPingServer(t)
+	defer stop()
+
+	pool, err := NewConnectionPool(&PoolConfig{
+		Address:        addr,
+		MaxConnections: 2,
+		ConnectTimeout: 2 * time.Second,
+		ReadTimeout:    1 * time.Second,
+		WriteTimeout:   1 * time.Second,
+		EnableTLS:      true,
+		TLSSkipVerify:  false,
+	})
+	require.NoError(t, err)
+	defer pool.Close()
+
+	_, err = pool.Get(context.Background())
+	require.Error(t, err)
+	assert.Contains(t, strings.ToLower(err.Error()), "tls")
+}
+
+// TestConnectionPool_TLSDial_PlainServerRejected verifies that EnableTLS=true
+// fails to handshake against a plain (non-TLS) listener.
+func TestConnectionPool_TLSDial_PlainServerRejected(t *testing.T) {
+	plain, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+	defer plain.Close()
+
+	go func() {
+		for {
+			c, acceptErr := plain.Accept()
+			if acceptErr != nil {
+				return
+			}
+			_ = c.Close()
+		}
+	}()
+
+	pool, err := NewConnectionPool(&PoolConfig{
+		Address:        plain.Addr().String(),
+		MaxConnections: 1,
+		ConnectTimeout: 1 * time.Second,
+		ReadTimeout:    1 * time.Second,
+		WriteTimeout:   1 * time.Second,
+		EnableTLS:      true,
+		TLSSkipVerify:  true,
+	})
+	require.NoError(t, err)
+	defer pool.Close()
+
+	_, err = pool.Get(context.Background())
+	require.Error(t, err)
+}
+
+// TestConnectionPool_PlainDial_StillWorks ensures non-TLS path is unaffected
+// when EnableTLS=false (default).
+func TestConnectionPool_PlainDial_StillWorks(t *testing.T) {
+	mr := NewMiniredisServer(t)
+
+	pool, err := NewConnectionPool(&PoolConfig{
+		Address:        mr.GetAddr(),
+		MaxConnections: 1,
+		ConnectTimeout: 2 * time.Second,
+		ReadTimeout:    1 * time.Second,
+		WriteTimeout:   1 * time.Second,
+		EnableTLS:      false,
+	})
+	require.NoError(t, err)
+	defer pool.Close()
+
+	conn, err := pool.Get(context.Background())
+	require.NoError(t, err)
+	defer pool.Put(conn)
+
+	resp, err := conn.Do("PING")
+	require.NoError(t, err)
+	assert.Equal(t, "PONG", resp)
+}

internal/cache/backends/resp.go

@@ -7,52 +7,34 @@ import (
 	"io"
 	"strconv"
 	"strings"
-	"sync"
 )
 
 // RESP (REdis Serialization Protocol) implementation
 // Pure Go implementation compatible with Yaegi interpreter (no unsafe package)
+//
+// NOTE: sync.Pool was intentionally removed for Yaegi compatibility.
+// Yaegi (Traefik's Go interpreter) has issues with sync.Pool and reflection
+// that cause "reflect: call of reflect.Value.Field on zero Value" panics.
+// See: https://github.com/lukaszraczylo/traefikoidc/issues/120
 
 var (
 	ErrInvalidRESP = errors.New("invalid RESP response")
 	ErrNilResponse = errors.New("nil response")
 )
 
-// Object pools for memory optimization - reduces allocations by 50-70%
-var (
-	readerPool = sync.Pool{
-		New: func() interface{} {
-			return &RESPReader{
-				r: bufio.NewReaderSize(nil, 4096),
-			}
-		},
-	}
-
-	writerPool = sync.Pool{
-		New: func() interface{} {
-			return &RESPWriter{
-				w: nil,
-			}
-		},
-	}
-)
-
 // RESPWriter writes RESP protocol messages
 type RESPWriter struct {
 	w io.Writer
 }
 
-// NewRESPWriter creates a new RESP writer from the pool (memory optimized)
+// NewRESPWriter creates a new RESP writer
 func NewRESPWriter(w io.Writer) *RESPWriter {
-	writer := writerPool.Get().(*RESPWriter)
-	writer.w = w
-	return writer
+	return &RESPWriter{w: w}
 }
 
-// Release returns the writer to the pool for reuse
+// Release is a no-op for API compatibility (pooling removed for Yaegi compatibility)
 func (w *RESPWriter) Release() {
-	w.w = nil
-	writerPool.Put(w)
+	// No-op: pooling removed for Yaegi compatibility
 }
 
 // WriteCommand writes a Redis command in RESP array format
@@ -78,17 +60,16 @@ type RESPReader struct {
 	r *bufio.Reader
 }
 
-// NewRESPReader creates a new RESP reader from the pool (memory optimized)
+// NewRESPReader creates a new RESP reader
 func NewRESPReader(r io.Reader) *RESPReader {
-	reader := readerPool.Get().(*RESPReader)
-	reader.r.Reset(r)
-	return reader
+	return &RESPReader{
+		r: bufio.NewReaderSize(r, 4096),
+	}
 }
 
-// Release returns the reader to the pool for reuse
+// Release is a no-op for API compatibility (pooling removed for Yaegi compatibility)
 func (r *RESPReader) Release() {
-	r.r.Reset(nil)
-	readerPool.Put(r)
+	// No-op: pooling removed for Yaegi compatibility
 }
 
 // ReadResponse reads a RESP response and returns the parsed value

internal/cache/backends/resp_test.go

@@ -15,8 +15,8 @@ import (
 func TestRESPWriter_WriteCommand(t *testing.T) {
 	tests := []struct {
 		name     string
-		args     []string
 		expected string
+		args     []string
 	}{
 		{
 			name:     "Simple command",
@@ -205,9 +205,9 @@ func TestRESPReader_ReadInteger(t *testing.T) {
 // TestRESPReader_ReadBulkString tests reading bulk strings
 func TestRESPReader_ReadBulkString(t *testing.T) {
 	tests := []struct {
+		expected interface{}
 		name     string
 		input    string
-		expected interface{}
 		wantErr  bool
 		isNil    bool
 	}{
@@ -440,10 +440,10 @@ func TestRESPHelpers(t *testing.T) {
 // TestRESPRoundTrip tests full round-trip encoding/decoding
 func TestRESPRoundTrip(t *testing.T) {
 	tests := []struct {
-		name     string
-		command  []string
-		response string
 		expected interface{}
+		name     string
+		response string
+		command  []string
 	}{
 		{
 			name:     "PING command",

internal/cache/backends/singleflight.go

@@ -0,0 +1,183 @@
+package backends
+
+import (
+	"context"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// SingleflightCache wraps a CacheBackend with singleflight deduplication
+// to prevent thundering herd problems when multiple concurrent requests
+// try to fetch the same uncached key.
+type SingleflightCache struct {
+	backend CacheBackend
+	mu      sync.Mutex
+	calls   map[string]*singleflightCall
+
+	// Metrics
+	deduplicatedCalls atomic.Int64
+	totalCalls        atomic.Int64
+}
+
+// singleflightCall represents an in-flight or completed fetch call
+type singleflightCall struct {
+	wg   sync.WaitGroup
+	val  []byte
+	ttl  time.Duration
+	err  error
+	done bool
+}
+
+// NewSingleflightCache creates a new singleflight-wrapped cache backend
+func NewSingleflightCache(backend CacheBackend) *SingleflightCache {
+	return &SingleflightCache{
+		backend: backend,
+		calls:   make(map[string]*singleflightCall),
+	}
+}
+
+// Fetcher is a function type that fetches data when cache misses
+type Fetcher func(ctx context.Context) (value []byte, ttl time.Duration, err error)
+
+// GetOrFetch retrieves a value from cache or calls the fetcher exactly once
+// per key when there's a cache miss. Concurrent calls for the same key will
+// wait for the first call to complete and share its result.
+func (s *SingleflightCache) GetOrFetch(ctx context.Context, key string, fetcher Fetcher) ([]byte, error) {
+	s.totalCalls.Add(1)
+
+	// Try cache first
+	value, _, exists, err := s.backend.Get(ctx, key)
+	if err != nil {
+		return nil, err
+	}
+	if exists {
+		return value, nil
+	}
+
+	// Cache miss - use singleflight
+	s.mu.Lock()
+
+	// Check if there's already an in-flight call for this key
+	if call, ok := s.calls[key]; ok {
+		s.mu.Unlock()
+		s.deduplicatedCalls.Add(1)
+
+		// Wait for the in-flight call to complete
+		call.wg.Wait()
+
+		// Check context cancellation
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+
+		return call.val, call.err
+	}
+
+	// Create new call
+	call := &singleflightCall{}
+	call.wg.Add(1)
+	s.calls[key] = call
+	s.mu.Unlock()
+
+	// Execute the fetcher
+	call.val, call.ttl, call.err = fetcher(ctx)
+	call.done = true
+
+	// If successful, store in cache
+	if call.err == nil && call.val != nil {
+		// Use a background context for cache storage to ensure it completes
+		// even if the original context is canceled
+		storeCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		_ = s.backend.Set(storeCtx, key, call.val, call.ttl)
+		cancel()
+	}
+
+	// Signal waiting goroutines
+	call.wg.Done()
+
+	// Clean up the call from the map after a short delay
+	// This allows late arrivals to still benefit from the result
+	go func() {
+		time.Sleep(100 * time.Millisecond)
+		s.mu.Lock()
+		if c, ok := s.calls[key]; ok && c == call {
+			delete(s.calls, key)
+		}
+		s.mu.Unlock()
+	}()
+
+	return call.val, call.err
+}
+
+// Get retrieves a value from the underlying cache backend
+func (s *SingleflightCache) Get(ctx context.Context, key string) ([]byte, time.Duration, bool, error) {
+	return s.backend.Get(ctx, key)
+}
+
+// Set stores a value in the underlying cache backend
+func (s *SingleflightCache) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error {
+	return s.backend.Set(ctx, key, value, ttl)
+}
+
+// Delete removes a key from the underlying cache backend
+func (s *SingleflightCache) Delete(ctx context.Context, key string) (bool, error) {
+	return s.backend.Delete(ctx, key)
+}
+
+// Exists checks if a key exists in the underlying cache backend
+func (s *SingleflightCache) Exists(ctx context.Context, key string) (bool, error) {
+	return s.backend.Exists(ctx, key)
+}
+
+// Clear removes all keys from the underlying cache backend
+func (s *SingleflightCache) Clear(ctx context.Context) error {
+	return s.backend.Clear(ctx)
+}
+
+// GetStats returns cache statistics including singleflight metrics
+func (s *SingleflightCache) GetStats() map[string]interface{} {
+	stats := s.backend.GetStats()
+
+	// Add singleflight-specific stats
+	totalCalls := s.totalCalls.Load()
+	deduped := s.deduplicatedCalls.Load()
+
+	stats["singleflight_total_calls"] = totalCalls
+	stats["singleflight_deduplicated"] = deduped
+	if totalCalls > 0 {
+		stats["singleflight_dedup_rate"] = float64(deduped) / float64(totalCalls)
+	} else {
+		stats["singleflight_dedup_rate"] = float64(0)
+	}
+
+	s.mu.Lock()
+	stats["singleflight_inflight"] = len(s.calls)
+	s.mu.Unlock()
+
+	return stats
+}
+
+// Close shuts down the cache backend
+func (s *SingleflightCache) Close() error {
+	return s.backend.Close()
+}
+
+// Ping checks if the backend is healthy
+func (s *SingleflightCache) Ping(ctx context.Context) error {
+	return s.backend.Ping(ctx)
+}
+
+// GetBackend returns the underlying cache backend
+func (s *SingleflightCache) GetBackend() CacheBackend {
+	return s.backend
+}
+
+// ResetStats resets the singleflight statistics
+func (s *SingleflightCache) ResetStats() {
+	s.totalCalls.Store(0)
+	s.deduplicatedCalls.Store(0)
+}
+
+// Ensure SingleflightCache implements CacheBackend
+var _ CacheBackend = (*SingleflightCache)(nil)

internal/cache/backends/singleflight_test.go

@@ -0,0 +1,510 @@
+package backends
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestSingleflightCache_BasicGetOrFetch tests basic GetOrFetch functionality
+func TestSingleflightCache_BasicGetOrFetch(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	t.Run("CacheHit", func(t *testing.T) {
+		key := "existing-key"
+		value := []byte("existing-value")
+
+		// Pre-populate cache
+		err := cache.Set(ctx, key, value, time.Minute)
+		require.NoError(t, err)
+
+		var fetchCalled bool
+		fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+			fetchCalled = true
+			return []byte("fetched-value"), time.Minute, nil
+		}
+
+		result, err := cache.GetOrFetch(ctx, key, fetcher)
+		require.NoError(t, err)
+		assert.Equal(t, value, result)
+		assert.False(t, fetchCalled, "Fetcher should not be called on cache hit")
+	})
+
+	t.Run("CacheMiss", func(t *testing.T) {
+		key := "missing-key"
+		expectedValue := []byte("fetched-value")
+
+		var fetchCalled bool
+		fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+			fetchCalled = true
+			return expectedValue, time.Minute, nil
+		}
+
+		result, err := cache.GetOrFetch(ctx, key, fetcher)
+		require.NoError(t, err)
+		assert.Equal(t, expectedValue, result)
+		assert.True(t, fetchCalled, "Fetcher should be called on cache miss")
+
+		// Verify value was stored in cache
+		cached, _, exists, err := cache.Get(ctx, key)
+		require.NoError(t, err)
+		assert.True(t, exists)
+		assert.Equal(t, expectedValue, cached)
+	})
+
+	t.Run("FetcherError", func(t *testing.T) {
+		key := "error-key"
+		expectedErr := errors.New("fetch failed")
+
+		fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+			return nil, 0, expectedErr
+		}
+
+		result, err := cache.GetOrFetch(ctx, key, fetcher)
+		assert.Error(t, err)
+		assert.Equal(t, expectedErr, err)
+		assert.Nil(t, result)
+
+		// Verify nothing was stored in cache
+		_, _, exists, err := cache.Get(ctx, key)
+		require.NoError(t, err)
+		assert.False(t, exists)
+	})
+}
+
+// TestSingleflightCache_Deduplication tests that concurrent calls are deduplicated
+func TestSingleflightCache_Deduplication(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	key := "dedup-key"
+	expectedValue := []byte("dedup-value")
+
+	var fetchCount atomic.Int32
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		fetchCount.Add(1)
+		// Simulate slow fetch
+		time.Sleep(100 * time.Millisecond)
+		return expectedValue, time.Minute, nil
+	}
+
+	// Launch multiple concurrent requests
+	concurrency := 10
+	var wg sync.WaitGroup
+	results := make([][]byte, concurrency)
+	errs := make([]error, concurrency)
+
+	for i := 0; i < concurrency; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			results[idx], errs[idx] = cache.GetOrFetch(ctx, key, fetcher)
+		}(i)
+	}
+
+	wg.Wait()
+
+	// Verify all requests got the same result
+	for i := 0; i < concurrency; i++ {
+		assert.NoError(t, errs[i])
+		assert.Equal(t, expectedValue, results[i])
+	}
+
+	// Verify fetcher was only called once
+	assert.Equal(t, int32(1), fetchCount.Load(), "Fetcher should only be called once")
+
+	// Verify deduplication stats
+	stats := cache.GetStats()
+	deduped := stats["singleflight_deduplicated"].(int64)
+	assert.Equal(t, int64(concurrency-1), deduped, "Should have deduplicated N-1 calls")
+}
+
+// TestSingleflightCache_DifferentKeys tests that different keys can fetch in parallel
+func TestSingleflightCache_DifferentKeys(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	var fetchCount atomic.Int32
+	fetchStarted := make(chan struct{}, 3)
+	fetchComplete := make(chan struct{})
+
+	fetcher := func(key string) Fetcher {
+		return func(ctx context.Context) ([]byte, time.Duration, error) {
+			fetchCount.Add(1)
+			fetchStarted <- struct{}{}
+			<-fetchComplete // Wait for signal
+			return []byte("value-" + key), time.Minute, nil
+		}
+	}
+
+	// Launch concurrent requests for different keys
+	var wg sync.WaitGroup
+	for i := 0; i < 3; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			key := fmt.Sprintf("key-%d", idx)
+			_, _ = cache.GetOrFetch(ctx, key, fetcher(key))
+		}(i)
+	}
+
+	// Wait for all fetches to start
+	for i := 0; i < 3; i++ {
+		<-fetchStarted
+	}
+
+	// All 3 fetches should be running in parallel
+	assert.Equal(t, int32(3), fetchCount.Load(), "All three fetches should run in parallel")
+
+	// Release all fetches
+	close(fetchComplete)
+	wg.Wait()
+}
+
+// TestSingleflightCache_ContextCancellation tests context cancellation
+func TestSingleflightCache_ContextCancellation(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	key := "cancel-key"
+	fetchStarted := make(chan struct{})
+
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		close(fetchStarted)
+		// Simulate slow fetch
+		time.Sleep(500 * time.Millisecond)
+		return []byte("value"), time.Minute, nil
+	}
+
+	// Start first request with long timeout
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		ctx := context.Background()
+		_, _ = cache.GetOrFetch(ctx, key, fetcher)
+	}()
+
+	// Wait for fetch to start
+	<-fetchStarted
+
+	// Start second request with short timeout
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+
+	_, err = cache.GetOrFetch(ctx, key, fetcher)
+	assert.Error(t, err)
+	assert.Equal(t, context.DeadlineExceeded, err)
+
+	wg.Wait()
+}
+
+// TestSingleflightCache_ErrorPropagation tests that errors are properly propagated
+func TestSingleflightCache_ErrorPropagation(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	key := "error-prop-key"
+	expectedErr := errors.New("intentional error")
+
+	var fetchCount atomic.Int32
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		fetchCount.Add(1)
+		time.Sleep(50 * time.Millisecond)
+		return nil, 0, expectedErr
+	}
+
+	// Launch multiple concurrent requests
+	concurrency := 5
+	var wg sync.WaitGroup
+	errs := make([]error, concurrency)
+
+	for i := 0; i < concurrency; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			_, errs[idx] = cache.GetOrFetch(ctx, key, fetcher)
+		}(i)
+	}
+
+	wg.Wait()
+
+	// Verify all requests got the same error
+	for i := 0; i < concurrency; i++ {
+		assert.Error(t, errs[i])
+		assert.Equal(t, expectedErr, errs[i])
+	}
+
+	// Verify fetcher was only called once
+	assert.Equal(t, int32(1), fetchCount.Load())
+}
+
+// TestSingleflightCache_PassthroughMethods tests that passthrough methods work
+func TestSingleflightCache_PassthroughMethods(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	t.Run("Set", func(t *testing.T) {
+		err := cache.Set(ctx, "set-key", []byte("set-value"), time.Minute)
+		require.NoError(t, err)
+
+		val, _, exists, err := cache.Get(ctx, "set-key")
+		require.NoError(t, err)
+		assert.True(t, exists)
+		assert.Equal(t, []byte("set-value"), val)
+	})
+
+	t.Run("Get", func(t *testing.T) {
+		err := cache.Set(ctx, "get-key", []byte("get-value"), time.Minute)
+		require.NoError(t, err)
+
+		val, ttl, exists, err := cache.Get(ctx, "get-key")
+		require.NoError(t, err)
+		assert.True(t, exists)
+		assert.Equal(t, []byte("get-value"), val)
+		assert.Greater(t, ttl, time.Duration(0))
+	})
+
+	t.Run("Delete", func(t *testing.T) {
+		err := cache.Set(ctx, "delete-key", []byte("delete-value"), time.Minute)
+		require.NoError(t, err)
+
+		deleted, err := cache.Delete(ctx, "delete-key")
+		require.NoError(t, err)
+		assert.True(t, deleted)
+
+		exists, err := cache.Exists(ctx, "delete-key")
+		require.NoError(t, err)
+		assert.False(t, exists)
+	})
+
+	t.Run("Exists", func(t *testing.T) {
+		exists, err := cache.Exists(ctx, "nonexistent")
+		require.NoError(t, err)
+		assert.False(t, exists)
+
+		err = cache.Set(ctx, "exists-key", []byte("value"), time.Minute)
+		require.NoError(t, err)
+
+		exists, err = cache.Exists(ctx, "exists-key")
+		require.NoError(t, err)
+		assert.True(t, exists)
+	})
+
+	t.Run("Clear", func(t *testing.T) {
+		err := cache.Set(ctx, "clear-key", []byte("value"), time.Minute)
+		require.NoError(t, err)
+
+		err = cache.Clear(ctx)
+		require.NoError(t, err)
+
+		exists, err := cache.Exists(ctx, "clear-key")
+		require.NoError(t, err)
+		assert.False(t, exists)
+	})
+
+	t.Run("Ping", func(t *testing.T) {
+		err := cache.Ping(ctx)
+		require.NoError(t, err)
+	})
+}
+
+// TestSingleflightCache_Stats tests statistics tracking
+func TestSingleflightCache_Stats(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	// Make some calls
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		time.Sleep(50 * time.Millisecond)
+		return []byte("value"), time.Minute, nil
+	}
+
+	var wg sync.WaitGroup
+	for i := 0; i < 5; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = cache.GetOrFetch(ctx, "stats-key", fetcher)
+		}()
+	}
+	wg.Wait()
+
+	stats := cache.GetStats()
+
+	// Check singleflight stats exist
+	assert.Contains(t, stats, "singleflight_total_calls")
+	assert.Contains(t, stats, "singleflight_deduplicated")
+	assert.Contains(t, stats, "singleflight_dedup_rate")
+	assert.Contains(t, stats, "singleflight_inflight")
+
+	// Verify values
+	assert.Equal(t, int64(5), stats["singleflight_total_calls"])
+	assert.Equal(t, int64(4), stats["singleflight_deduplicated"])
+
+	// Also check underlying backend stats are included
+	assert.Contains(t, stats, "hits")
+	assert.Contains(t, stats, "misses")
+}
+
+// TestSingleflightCache_ResetStats tests stats reset
+func TestSingleflightCache_ResetStats(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		return []byte("value"), time.Minute, nil
+	}
+
+	// Make some calls
+	_, _ = cache.GetOrFetch(ctx, "key1", fetcher)
+	_, _ = cache.GetOrFetch(ctx, "key2", fetcher)
+
+	stats := cache.GetStats()
+	assert.Greater(t, stats["singleflight_total_calls"].(int64), int64(0))
+
+	// Reset stats
+	cache.ResetStats()
+
+	stats = cache.GetStats()
+	assert.Equal(t, int64(0), stats["singleflight_total_calls"])
+	assert.Equal(t, int64(0), stats["singleflight_deduplicated"])
+}
+
+// TestSingleflightCache_GetBackend tests GetBackend method
+func TestSingleflightCache_GetBackend(t *testing.T) {
+	t.Parallel()
+
+	backend, err := NewMemoryBackend(DefaultConfig())
+	require.NoError(t, err)
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	assert.Equal(t, backend, cache.GetBackend())
+}
+
+// BenchmarkSingleflightCache_Sequential benchmarks sequential access
+func BenchmarkSingleflightCache_Sequential(b *testing.B) {
+	backend, _ := NewMemoryBackend(DefaultConfig())
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		return []byte("benchmark-value"), time.Minute, nil
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		key := fmt.Sprintf("key-%d", i%100)
+		_, _ = cache.GetOrFetch(ctx, key, fetcher)
+	}
+}
+
+// BenchmarkSingleflightCache_Concurrent benchmarks concurrent access
+func BenchmarkSingleflightCache_Concurrent(b *testing.B) {
+	backend, _ := NewMemoryBackend(DefaultConfig())
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		time.Sleep(time.Millisecond) // Simulate slow fetch
+		return []byte("benchmark-value"), time.Minute, nil
+	}
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		i := 0
+		for pb.Next() {
+			key := fmt.Sprintf("key-%d", i%10) // Only 10 unique keys to force deduplication
+			_, _ = cache.GetOrFetch(ctx, key, fetcher)
+			i++
+		}
+	})
+}
+
+// BenchmarkSingleflightCache_HighContention benchmarks high contention scenario
+func BenchmarkSingleflightCache_HighContention(b *testing.B) {
+	backend, _ := NewMemoryBackend(DefaultConfig())
+	defer backend.Close()
+
+	cache := NewSingleflightCache(backend)
+
+	ctx := context.Background()
+	fetcher := func(ctx context.Context) ([]byte, time.Duration, error) {
+		time.Sleep(10 * time.Millisecond) // Slow fetch to force queuing
+		return []byte("benchmark-value"), time.Minute, nil
+	}
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			// All goroutines hit the same key
+			_, _ = cache.GetOrFetch(ctx, "hot-key", fetcher)
+		}
+	})
+}

internal/cache/cache.go

@@ -33,21 +33,19 @@ type Logger interface {
 
 // Config provides configuration for the cache
 type Config struct {
+	Logger            Logger
+	JWKConfig         *JWKConfig
+	MetadataConfig    *MetadataConfig
+	TokenConfig       *TokenConfig
 	Type              Type
-	MaxSize           int
-	MaxMemoryBytes    int64
 	DefaultTTL        time.Duration
 	CleanupInterval   time.Duration
-	EnableCompression bool
+	MaxMemoryBytes    int64
+	MaxSize           int
 	EnableMetrics     bool
 	EnableAutoCleanup bool
 	EnableMemoryLimit bool
-	Logger            Logger
-
-	// Type-specific configurations
-	TokenConfig    *TokenConfig
-	MetadataConfig *MetadataConfig
-	JWKConfig      *JWKConfig
+	EnableCompression bool
 }
 
 // TokenConfig provides token-specific cache configuration
@@ -59,11 +57,11 @@ type TokenConfig struct {
 
 // MetadataConfig provides metadata-specific cache configuration
 type MetadataConfig struct {
+	SecurityCriticalFields         []string
 	GracePeriod                    time.Duration
 	ExtendedGracePeriod            time.Duration
 	MaxGracePeriod                 time.Duration
 	SecurityCriticalMaxGracePeriod time.Duration
-	SecurityCriticalFields         []string
 }
 
 // JWKConfig provides JWK-specific cache configuration
@@ -75,45 +73,35 @@ type JWKConfig struct {
 
 // Item represents a single cache entry
 type Item struct {
-	Key          string
-	Value        interface{}
-	Size         int64
 	ExpiresAt    time.Time
 	LastAccessed time.Time
-	AccessCount  int64
+	Value        interface{}
+	Metadata     map[string]interface{}
+	element      *list.Element
+	Key          string
 	CacheType    Type
-
-	// Type-specific metadata
-	Metadata map[string]interface{}
-
-	// LRU list element reference
-	element *list.Element
+	Size         int64
+	AccessCount  int64
 }
 
 // Cache provides a single, unified cache implementation
 type Cache struct {
-	mu      sync.RWMutex
-	items   map[string]*Item
-	lruList *list.List
-	config  Config
-	logger  Logger
-
-	// Memory management
+	config        Config
+	ctx           context.Context
+	logger        Logger
+	cancel        context.CancelFunc
+	lruList       *list.List
+	items         map[string]*Item
+	stopCleanup   chan bool
+	wg            sync.WaitGroup
 	currentSize   int64
 	currentMemory int64
-
-	// Metrics
-	hits      int64
-	misses    int64
-	evictions int64
-	sets      int64
-
-	// Lifecycle management
-	ctx         context.Context
-	cancel      context.CancelFunc
-	wg          sync.WaitGroup
-	stopCleanup chan bool
-	closed      int32
+	hits          int64
+	misses        int64
+	evictions     int64
+	sets          int64
+	mu            sync.RWMutex
+	closed        int32
 }
 
 // DefaultConfig returns a default cache configuration
@@ -202,7 +190,7 @@ func (c *Cache) Set(key string, value interface{}, ttl time.Duration) error {
 	c.currentSize++
 	atomic.AddInt64(&c.sets, 1)
 
-	c.logger.Debugf("Cache: Set key=%s, size=%d, ttl=%v", key, size, ttl)
+	c.logger.Debugf("Cache: Set key=%s, size=%d, ttl=%v", redactKey(key), size, ttl)
 	return nil
 }
 
@@ -358,7 +346,7 @@ func (c *Cache) evictLRU() {
 		item, _ := elem.Value.(*Item) // Safe to ignore: type assertion from known type
 		c.removeItem(item.Key, item)
 		atomic.AddInt64(&c.evictions, 1)
-		c.logger.Debugf("Cache: Evicted LRU item key=%s", item.Key)
+		c.logger.Debugf("Cache: Evicted LRU item key=%s", redactKey(item.Key))
 	}
 }
 

internal/cache/cache_test.go

@@ -1750,19 +1750,19 @@ func TestAdvancedEdgeCases(t *testing.T) {
 
 	// Test with various data types
 	testCases := []struct {
-		key   string
 		value interface{}
+		key   string
 	}{
-		{"string", "test string"},
-		{"int", 42},
-		{"float", 3.14159},
-		{"bool", true},
-		{"slice", []string{"a", "b", "c"}},
-		{"map", map[string]int{"one": 1, "two": 2}},
-		{"nil", nil},
-		{"empty-string", ""},
-		{"empty-slice", []string{}},
-		{"empty-map", map[string]interface{}{}},
+		{key: "string", value: "test string"},
+		{key: "int", value: 42},
+		{key: "float", value: 3.14159},
+		{key: "bool", value: true},
+		{key: "slice", value: []string{"a", "b", "c"}},
+		{key: "map", value: map[string]int{"one": 1, "two": 2}},
+		{key: "nil", value: nil},
+		{key: "empty-string", value: ""},
+		{key: "empty-slice", value: []string{}},
+		{key: "empty-map", value: map[string]interface{}{}},
 	}
 
 	for _, tc := range testCases {

internal/cache/log_redact.go

@@ -0,0 +1,22 @@
+// Package cache provides the in-memory cache implementation for the Traefik
+// OIDC plugin.
+package cache
+
+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 may include raw access / refresh / id
+// tokens (callers pass arbitrary strings) and CodeQL flags `key=%s`
+// formatters as a clear-text-logging sink for HTTP-header-sourced taint.
+// The hash preserves uniqueness in logs (same key → same hash) while keeping
+// the raw value out of disk-resident log streams.
+func redactKey(key string) string {
+	if key == "" {
+		return "(empty)"
+	}
+	sum := sha256.Sum256([]byte(key))
+	return hex.EncodeToString(sum[:4])
+}

internal/cache/manager.go

@@ -7,22 +7,17 @@ import (
 
 // Manager manages multiple cache instances with singleton pattern
 type Manager struct {
-	mu sync.RWMutex
-
-	// Core caches
+	logger        Logger
 	tokenCache    *Cache
 	metadataCache *Cache
 	jwkCache      *Cache
 	sessionCache  *Cache
 	generalCache  *Cache
-
-	// Typed wrappers
 	typedToken    *TokenCache
 	typedMetadata *MetadataCache
 	typedJWK      *JWKCache
 	typedSession  *SessionCache
-
-	logger Logger
+	mu            sync.RWMutex
 }
 
 var (
@@ -237,7 +232,7 @@ func (m *Manager) Close() error {
 
 	var firstErr error
 
-	if err := m.tokenCache.Close(); err != nil && firstErr == nil {
+	if err := m.tokenCache.Close(); err != nil {
 		firstErr = err
 	}
 	if err := m.metadataCache.Close(); err != nil && firstErr == nil {

internal/cache/resilience/circuit_breaker.go

@@ -48,23 +48,12 @@ func (s State) String() string {
 
 // CircuitBreakerConfig holds configuration for the circuit breaker
 type CircuitBreakerConfig struct {
-	// MaxFailures is the number of consecutive failures before opening the circuit
-	MaxFailures int
-
-	// FailureThreshold is the failure rate threshold (0.0 to 1.0)
-	FailureThreshold float64
-
-	// Timeout is how long the circuit stays open before trying half-open
-	Timeout time.Duration
-
-	// HalfOpenMaxRequests is the number of requests allowed in half-open state
+	OnStateChange       func(from, to State)
+	MaxFailures         int
+	FailureThreshold    float64
+	Timeout             time.Duration
 	HalfOpenMaxRequests int
-
-	// ResetTimeout is how long to wait before resetting counters in closed state
-	ResetTimeout time.Duration
-
-	// OnStateChange is called when the circuit breaker changes state
-	OnStateChange func(from, to State)
+	ResetTimeout        time.Duration
 }
 
 // DefaultCircuitBreakerConfig returns default configuration
@@ -80,28 +69,20 @@ func DefaultCircuitBreakerConfig() *CircuitBreakerConfig {
 
 // CircuitBreaker implements the circuit breaker pattern
 type CircuitBreaker struct {
-	config *CircuitBreakerConfig
-
-	// State management
-	state           atomic.Int32
-	lastStateChange time.Time
-	stateMu         sync.RWMutex
-
-	// Failure tracking
-	consecutiveFailures atomic.Int32
-	totalRequests       atomic.Int64
+	nextRetryTime       time.Time
+	lastStateChange     time.Time
+	lastSuccessTime     time.Time
+	lastFailureTime     time.Time
+	config              *CircuitBreakerConfig
 	totalFailures       atomic.Int64
+	totalRequests       atomic.Int64
+	stateTransitions    atomic.Int64
+	rejectedRequests    atomic.Int64
+	stateMu             sync.RWMutex
+	timeMu              sync.RWMutex
 	halfOpenRequests    atomic.Int32
-
-	// Timing
-	lastFailureTime time.Time
-	lastSuccessTime time.Time
-	nextRetryTime   time.Time
-	timeMu          sync.RWMutex
-
-	// Metrics
-	stateTransitions atomic.Int64
-	rejectedRequests atomic.Int64
+	consecutiveFailures atomic.Int32
+	state               atomic.Int32
 }
 
 // NewCircuitBreaker creates a new circuit breaker
@@ -313,17 +294,17 @@ func (cb *CircuitBreaker) Stats() CircuitBreakerStats {
 
 // CircuitBreakerStats holds statistics for the circuit breaker
 type CircuitBreakerStats struct {
-	State               State
-	ConsecutiveFailures int32
+	LastFailureTime     time.Time
+	LastSuccessTime     time.Time
+	LastStateChange     time.Time
+	NextRetryTime       time.Time
 	TotalRequests       int64
 	TotalFailures       int64
 	SuccessRate         float64
 	RejectedRequests    int64
 	StateTransitions    int64
-	LastFailureTime     time.Time
-	LastSuccessTime     time.Time
-	LastStateChange     time.Time
-	NextRetryTime       time.Time
+	State               State
+	ConsecutiveFailures int32
 }
 
 // IsHealthy returns true if the circuit breaker is in a healthy state

internal/cache/resilience/circuit_breaker_backend_test.go

@@ -28,8 +28,8 @@ type mockBackend struct {
 }
 
 type mockEntry struct {
-	value     []byte
 	expiresAt time.Time
+	value     []byte
 }
 
 func newMockBackend() *mockBackend {

internal/cache/resilience/health_check.go

@@ -41,26 +41,13 @@ func (h HealthStatus) String() string {
 
 // HealthCheckConfig holds configuration for the health checker
 type HealthCheckConfig struct {
-	// CheckInterval is how often to check health
-	CheckInterval time.Duration
-
-	// Timeout is the timeout for each health check
-	Timeout time.Duration
-
-	// HealthyThreshold is the number of consecutive successes to become healthy
-	HealthyThreshold int
-
-	// UnhealthyThreshold is the number of consecutive failures to become unhealthy
+	OnStatusChange     func(from, to HealthStatus)
+	CheckFunc          func(ctx context.Context) error
+	CheckInterval      time.Duration
+	Timeout            time.Duration
+	HealthyThreshold   int
 	UnhealthyThreshold int
-
-	// DegradedThreshold is the latency threshold in ms to mark as degraded
-	DegradedThreshold time.Duration
-
-	// OnStatusChange is called when health status changes
-	OnStatusChange func(from, to HealthStatus)
-
-	// CheckFunc is the function to check health
-	CheckFunc func(ctx context.Context) error
+	DegradedThreshold  time.Duration
 }
 
 // DefaultHealthCheckConfig returns default configuration
@@ -76,31 +63,23 @@ func DefaultHealthCheckConfig() *HealthCheckConfig {
 
 // HealthChecker monitors the health of a backend
 type HealthChecker struct {
-	config *HealthCheckConfig
-
-	// Status tracking
-	status               atomic.Int32
-	consecutiveSuccesses atomic.Int32
+	lastCheckTime        time.Time
+	lastSuccessTime      time.Time
+	lastFailureTime      time.Time
+	config               *HealthCheckConfig
+	stopChan             chan struct{}
+	ticker               *time.Ticker
+	wg                   sync.WaitGroup
+	statusChanges        atomic.Int64
+	totalChecks          atomic.Int64
+	totalSuccesses       atomic.Int64
+	totalFailures        atomic.Int64
+	averageLatency       atomic.Int64
+	timeMu               sync.RWMutex
 	consecutiveFailures  atomic.Int32
-
-	// Timing
-	lastCheckTime   time.Time
-	lastSuccessTime time.Time
-	lastFailureTime time.Time
-	averageLatency  atomic.Int64
-	timeMu          sync.RWMutex
-
-	// Metrics
-	totalChecks    atomic.Int64
-	totalSuccesses atomic.Int64
-	totalFailures  atomic.Int64
-	statusChanges  atomic.Int64
-
-	// Lifecycle
-	ticker   *time.Ticker
-	stopChan chan struct{}
-	stopped  atomic.Bool
-	wg       sync.WaitGroup
+	consecutiveSuccesses atomic.Int32
+	stopped              atomic.Bool
+	status               atomic.Int32
 }
 
 // NewHealthChecker creates a new health checker
@@ -342,19 +321,19 @@ func (hc *HealthChecker) Stats() HealthCheckerStats {
 
 // HealthCheckerStats holds statistics for the health checker
 type HealthCheckerStats struct {
-	Status               HealthStatus
-	ConsecutiveSuccesses int32
-	ConsecutiveFailures  int32
+	LastCheckTime        time.Time
+	LastFailureTime      time.Time
+	LastSuccessTime      time.Time
 	TotalChecks          int64
 	TotalSuccesses       int64
 	TotalFailures        int64
 	SuccessRate          float64
 	AverageLatency       time.Duration
 	StatusChanges        int64
-	LastCheckTime        time.Time
-	LastSuccessTime      time.Time
-	LastFailureTime      time.Time
 	HealthScore          float64
+	Status               HealthStatus
+	ConsecutiveFailures  int32
+	ConsecutiveSuccesses int32
 }
 
 // Reset resets the health checker statistics

internal/cache/resilience/health_check_backend.go

@@ -12,20 +12,16 @@ import (
 
 // HealthCheckBackend wraps a cache backend with health checking
 type HealthCheckBackend struct {
-	backend backends.CacheBackend
-	config  *HealthCheckConfig
-
-	// Health tracking
+	lastCheck        time.Time
+	backend          backends.CacheBackend
+	ctx              context.Context
+	config           *HealthCheckConfig
+	cancel           context.CancelFunc
+	wg               sync.WaitGroup
+	checkMutex       sync.RWMutex
 	status           atomic.Int32
 	consecutiveFails atomic.Int32
 	consecutiveOK    atomic.Int32
-	lastCheck        time.Time
-	checkMutex       sync.RWMutex
-
-	// Lifecycle
-	ctx    context.Context
-	cancel context.CancelFunc
-	wg     sync.WaitGroup
 }
 
 // NewHealthCheckBackend creates a new health check wrapped backend

internal/cache/typed_cache.go

@@ -292,12 +292,12 @@ type SessionCache struct {
 
 // SessionData represents session information
 type SessionData struct {
+	ExpiresAt    time.Time              `json:"expires_at"`
+	Claims       map[string]interface{} `json:"claims"`
 	ID           string                 `json:"id"`
 	UserID       string                 `json:"user_id"`
 	AccessToken  string                 `json:"access_token"`
 	RefreshToken string                 `json:"refresh_token"`
-	ExpiresAt    time.Time              `json:"expires_at"`
-	Claims       map[string]interface{} `json:"claims"`
 }
 
 // NewSessionCache creates a new session cache

internal/cleanup/cleanup_test.go

@@ -11,10 +11,10 @@ import (
 
 // Mock logger for testing
 type mockLogger struct {
-	mu       sync.Mutex
 	logs     []string
 	errLogs  []string
 	debugLog []string
+	mu       sync.Mutex
 }
 
 func (m *mockLogger) Logf(format string, args ...interface{}) {

internal/cleanup/manager.go

@@ -19,20 +19,20 @@ type Logger interface {
 
 // BackgroundTask represents a recurring background task
 type BackgroundTask struct {
-	name       string
-	interval   time.Duration
-	taskFunc   func()
+	lastRun    time.Time
+	logger     Logger
+	ctx        context.Context
 	ticker     *time.Ticker
 	stopChan   chan bool
-	isRunning  int32
-	logger     Logger
 	waitGroup  *sync.WaitGroup
-	lastRun    time.Time
+	taskFunc   func()
+	cancelFunc context.CancelFunc
+	name       string
 	runCount   int64
 	errorCount int64
+	interval   time.Duration
 	mu         sync.RWMutex
-	ctx        context.Context
-	cancelFunc context.CancelFunc
+	isRunning  int32
 }
 
 // NewBackgroundTask creates a new background task
@@ -183,11 +183,11 @@ func (bt *BackgroundTask) IsRunning() bool {
 
 // TaskRegistry manages all background tasks
 type TaskRegistry struct {
-	tasks          map[string]*BackgroundTask
-	mu             sync.RWMutex
 	logger         Logger
-	maxTasks       int
+	tasks          map[string]*BackgroundTask
 	circuitBreaker *TaskCircuitBreaker
+	maxTasks       int
+	mu             sync.RWMutex
 }
 
 // globalTaskRegistry is the singleton task registry

internal/cleanup/workers.go

@@ -11,14 +11,14 @@ import (
 
 // TaskCircuitBreaker prevents task creation failures from cascading
 type TaskCircuitBreaker struct {
+	lastFailureTime  time.Time
+	logger           Logger
+	taskFailures     map[string]int32
+	timeout          time.Duration
+	mu               sync.RWMutex
 	failureThreshold int32
 	failureCount     int32
-	lastFailureTime  time.Time
-	timeout          time.Duration
-	state            int32 // 0: closed, 1: open
-	logger           Logger
-	mu               sync.RWMutex
-	taskFailures     map[string]int32
+	state            int32
 }
 
 // CircuitBreakerState represents the state of the circuit breaker
@@ -140,14 +140,14 @@ func (cb *TaskCircuitBreaker) GetState() CircuitBreakerState {
 
 // TaskMemoryMonitor monitors memory usage and can trigger cleanup
 type TaskMemoryMonitor struct {
+	lastCheck       time.Time
 	logger          Logger
 	registry        *TaskRegistry
+	stopChan        chan bool
 	memoryThreshold uint64
 	checkInterval   time.Duration
-	isMonitoring    int32
-	stopChan        chan bool
-	lastCheck       time.Time
 	mu              sync.RWMutex
+	isMonitoring    int32
 }
 
 var (
@@ -310,13 +310,13 @@ func (tmm *TaskMemoryMonitor) GetStats() map[string]interface{} {
 
 // WorkerPool manages a pool of worker goroutines for task execution
 type WorkerPool struct {
-	workers   int
-	taskQueue chan func()
-	workerWg  sync.WaitGroup
-	isRunning int32
 	logger    Logger
+	taskQueue chan func()
 	stopChan  chan bool
 	metrics   WorkerPoolMetrics
+	workerWg  sync.WaitGroup
+	workers   int
+	isRunning int32
 }
 
 // WorkerPoolMetrics tracks worker pool performance
@@ -397,7 +397,7 @@ func (wp *WorkerPool) Submit(task func()) error {
 }
 
 // worker is the main worker routine
-func (wp *WorkerPool) worker(id int) {
+func (wp *WorkerPool) worker(_ int) {
 	defer wp.workerWg.Done()
 
 	for {

internal/dcrstorage/file.go

@@ -0,0 +1,155 @@
+package dcrstorage
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+)
+
+// FileStore implements Store using file-based storage.
+// This is the default storage backend for backward compatibility with existing deployments.
+// For distributed environments, consider using RedisStore instead.
+type FileStore struct {
+	basePath string
+	logger   Logger
+	mu       sync.RWMutex
+}
+
+// NewFileStore creates a new file-based credentials store.
+// If basePath is empty, defaults to /tmp/oidc-client-credentials.json
+func NewFileStore(basePath string, logger Logger) *FileStore {
+	if basePath == "" {
+		basePath = "/tmp/oidc-client-credentials.json"
+	}
+	if logger == nil {
+		logger = NoOpLogger()
+	}
+	return &FileStore{
+		basePath: basePath,
+		logger:   logger,
+	}
+}
+
+// BasePath returns the base path used for storing credentials
+func (s *FileStore) BasePath() string {
+	return s.basePath
+}
+
+// GetFilePath returns the file path for storing credentials for a specific provider.
+// For multi-tenant scenarios, each provider gets a separate file based on URL hash.
+func (s *FileStore) GetFilePath(providerURL string) string {
+	if providerURL == "" {
+		return s.basePath
+	}
+
+	// Hash provider URL for filename safety and uniqueness
+	hash := sha256.Sum256([]byte(providerURL))
+	hashStr := hex.EncodeToString(hash[:8]) // Use first 8 bytes for shorter filename
+
+	ext := filepath.Ext(s.basePath)
+	base := strings.TrimSuffix(s.basePath, ext)
+	if ext == "" {
+		ext = ".json"
+	}
+
+	return fmt.Sprintf("%s-%s%s", base, hashStr, ext)
+}
+
+// Save stores the client registration response to a file
+func (s *FileStore) Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error {
+	if creds == nil {
+		return fmt.Errorf("credentials cannot be nil")
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	filePath := s.GetFilePath(providerURL)
+
+	// Ensure parent directory exists
+	dir := filepath.Dir(filePath)
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return fmt.Errorf("failed to create credentials directory: %w", err)
+	}
+
+	data, err := json.MarshalIndent(creds, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to marshal credentials: %w", err)
+	}
+
+	// Write with restrictive permissions (owner read/write only)
+	if err := os.WriteFile(filePath, data, 0600); err != nil {
+		return fmt.Errorf("failed to write credentials file: %w", err)
+	}
+
+	s.logger.Debugf("Saved client credentials to %s", filePath)
+	return nil
+}
+
+// Load retrieves stored credentials from a file.
+// Returns nil, nil if no credentials file exists (not an error).
+func (s *FileStore) Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	filePath := s.GetFilePath(providerURL)
+
+	// #nosec G304 -- path is constructed from trusted config values via GetFilePath()
+	data, err := os.ReadFile(filePath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil // No credentials file exists - not an error
+		}
+		return nil, fmt.Errorf("failed to read credentials file: %w", err)
+	}
+
+	var creds ClientRegistrationResponse
+	if err := json.Unmarshal(data, &creds); err != nil {
+		return nil, fmt.Errorf("failed to parse credentials file: %w", err)
+	}
+
+	s.logger.Debugf("Loaded client credentials from %s", filePath)
+	return &creds, nil
+}
+
+// Delete removes the credentials file for a provider
+func (s *FileStore) Delete(ctx context.Context, providerURL string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	filePath := s.GetFilePath(providerURL)
+
+	if err := os.Remove(filePath); err != nil {
+		if os.IsNotExist(err) {
+			return nil // File doesn't exist, nothing to delete
+		}
+		return fmt.Errorf("failed to remove credentials file: %w", err)
+	}
+
+	s.logger.Debugf("Deleted client credentials from %s", filePath)
+	return nil
+}
+
+// Exists checks if credentials exist for a provider
+func (s *FileStore) Exists(ctx context.Context, providerURL string) (bool, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	filePath := s.GetFilePath(providerURL)
+
+	_, err := os.Stat(filePath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return false, nil
+		}
+		return false, fmt.Errorf("failed to check credentials file: %w", err)
+	}
+
+	return true, nil
+}

internal/dcrstorage/redis.go

@@ -0,0 +1,161 @@
+package dcrstorage
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"sync"
+	"time"
+)
+
+// Cache defines the interface for cache operations needed by RedisStore.
+// This allows the main package to provide a cache implementation without
+// creating circular dependencies.
+type Cache interface {
+	// Get retrieves a value from the cache
+	Get(key string) (any, bool)
+	// Set stores a value in the cache with a TTL
+	Set(key string, value any, ttl time.Duration) error
+	// Delete removes a value from the cache
+	Delete(key string)
+}
+
+// RedisStore implements Store using a Cache-backed storage.
+// This storage backend enables sharing DCR credentials across multiple Traefik instances
+// in distributed environments (e.g., Kubernetes with multiple ingress pods).
+type RedisStore struct {
+	cache     Cache
+	keyPrefix string
+	logger    Logger
+	mu        sync.RWMutex
+}
+
+// NewRedisStore creates a new cache-backed credentials store.
+// The cache should be configured with a Redis backend for distributed storage.
+// If keyPrefix is empty, defaults to "dcr:creds:"
+func NewRedisStore(cache Cache, keyPrefix string, logger Logger) *RedisStore {
+	if keyPrefix == "" {
+		keyPrefix = "dcr:creds:"
+	}
+	if logger == nil {
+		logger = NoOpLogger()
+	}
+	return &RedisStore{
+		cache:     cache,
+		keyPrefix: keyPrefix,
+		logger:    logger,
+	}
+}
+
+// makeKey creates a unique cache key for a provider URL.
+// Uses SHA256 hash of the provider URL for consistent key generation across nodes.
+func (s *RedisStore) makeKey(providerURL string) string {
+	if providerURL == "" {
+		return s.keyPrefix + "default"
+	}
+	hash := sha256.Sum256([]byte(providerURL))
+	return s.keyPrefix + hex.EncodeToString(hash[:])
+}
+
+// Save stores the client registration response in the cache.
+// TTL is calculated based on client_secret_expires_at if available.
+func (s *RedisStore) Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error {
+	if creds == nil {
+		return fmt.Errorf("credentials cannot be nil")
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	key := s.makeKey(providerURL)
+
+	// Calculate TTL based on client_secret_expires_at if available
+	ttl := 30 * 24 * time.Hour // Default: 30 days
+	if creds.ClientSecretExpiresAt > 0 {
+		expiresAt := time.Unix(creds.ClientSecretExpiresAt, 0)
+		ttl = time.Until(expiresAt)
+		if ttl < 0 {
+			return fmt.Errorf("credentials already expired")
+		}
+		// Add a small buffer to ensure we don't serve expired credentials
+		if ttl > time.Minute {
+			ttl -= time.Minute
+		}
+	}
+
+	// Serialize credentials to JSON for storage
+	data, err := json.Marshal(creds)
+	if err != nil {
+		return fmt.Errorf("failed to marshal credentials: %w", err)
+	}
+
+	// Store as string in cache (will be serialized by the cache backend)
+	if err := s.cache.Set(key, string(data), ttl); err != nil {
+		return fmt.Errorf("failed to store credentials in cache: %w", err)
+	}
+
+	s.logger.Debugf("Saved client credentials to cache with key %s (TTL: %v)", key, ttl)
+	return nil
+}
+
+// Load retrieves stored credentials from the cache.
+// Returns nil, nil if no credentials exist (not an error).
+func (s *RedisStore) Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	key := s.makeKey(providerURL)
+
+	value, exists := s.cache.Get(key)
+	if !exists {
+		return nil, nil // No credentials stored - not an error
+	}
+
+	// Handle different value types from cache
+	var jsonData string
+	switch v := value.(type) {
+	case string:
+		jsonData = v
+	case []byte:
+		jsonData = string(v)
+	default:
+		// Try to see if it's already the struct (from local cache)
+		if creds, ok := value.(*ClientRegistrationResponse); ok {
+			return creds, nil
+		}
+		return nil, fmt.Errorf("unexpected credentials type in cache: %T", value)
+	}
+
+	var creds ClientRegistrationResponse
+	if err := json.Unmarshal([]byte(jsonData), &creds); err != nil {
+		return nil, fmt.Errorf("failed to parse credentials from cache: %w", err)
+	}
+
+	s.logger.Debugf("Loaded client credentials from cache with key %s", key)
+	return &creds, nil
+}
+
+// Delete removes stored credentials from the cache
+func (s *RedisStore) Delete(ctx context.Context, providerURL string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	key := s.makeKey(providerURL)
+	s.cache.Delete(key)
+
+	s.logger.Debugf("Deleted client credentials from cache with key %s", key)
+	return nil
+}
+
+// Exists checks if credentials exist in the cache for a provider
+func (s *RedisStore) Exists(ctx context.Context, providerURL string) (bool, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	key := s.makeKey(providerURL)
+	_, exists := s.cache.Get(key)
+
+	return exists, nil
+}

internal/dcrstorage/storage.go

@@ -0,0 +1,90 @@
+// Package dcrstorage provides storage backends for OIDC Dynamic Client Registration credentials.
+// It supports both file-based and Redis-based storage for persisting client credentials
+// across application restarts and distributed deployments.
+package dcrstorage
+
+import (
+	"context"
+)
+
+// StorageBackend represents the type of storage backend for DCR credentials
+type StorageBackend string
+
+const (
+	// StorageBackendFile uses file-based storage (default for backward compatibility)
+	StorageBackendFile StorageBackend = "file"
+
+	// StorageBackendRedis uses Redis for distributed storage
+	StorageBackendRedis StorageBackend = "redis"
+
+	// StorageBackendAuto automatically selects Redis if available, otherwise file
+	StorageBackendAuto StorageBackend = "auto"
+)
+
+// Logger interface for DCR storage operations
+type Logger interface {
+	Debug(msg string)
+	Debugf(format string, args ...any)
+	Info(msg string)
+	Infof(format string, args ...any)
+	Error(msg string)
+	Errorf(format string, args ...any)
+}
+
+// ClientRegistrationResponse represents the response from a successful client registration (RFC 7591)
+type ClientRegistrationResponse struct {
+	SubjectType             string   `json:"subject_type,omitempty"`
+	LogoURI                 string   `json:"logo_uri,omitempty"`
+	RegistrationAccessToken string   `json:"registration_access_token,omitempty"`
+	RegistrationClientURI   string   `json:"registration_client_uri,omitempty"`
+	Scope                   string   `json:"scope,omitempty"`
+	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
+	TOSURI                  string   `json:"tos_uri,omitempty"`
+	PolicyURI               string   `json:"policy_uri,omitempty"`
+	ClientSecret            string   `json:"client_secret,omitempty"`
+	ApplicationType         string   `json:"application_type,omitempty"`
+	ClientID                string   `json:"client_id"`
+	ClientName              string   `json:"client_name,omitempty"`
+	JWKSURI                 string   `json:"jwks_uri,omitempty"`
+	ClientURI               string   `json:"client_uri,omitempty"`
+	Contacts                []string `json:"contacts,omitempty"`
+	GrantTypes              []string `json:"grant_types,omitempty"`
+	ResponseTypes           []string `json:"response_types,omitempty"`
+	RedirectURIs            []string `json:"redirect_uris,omitempty"`
+	ClientSecretExpiresAt   int64    `json:"client_secret_expires_at,omitempty"`
+	ClientIDIssuedAt        int64    `json:"client_id_issued_at,omitempty"`
+}
+
+// Store defines the interface for storing DCR credentials.
+// This abstraction allows different storage backends (file, Redis) to be used
+// for persisting OIDC Dynamic Client Registration credentials across nodes.
+type Store interface {
+	// Save stores the client registration response for a provider
+	// The providerURL is used as a key to support multi-tenant scenarios
+	Save(ctx context.Context, providerURL string, creds *ClientRegistrationResponse) error
+
+	// Load retrieves stored credentials for a provider
+	// Returns nil, nil if no credentials exist (not an error)
+	Load(ctx context.Context, providerURL string) (*ClientRegistrationResponse, error)
+
+	// Delete removes stored credentials for a provider
+	Delete(ctx context.Context, providerURL string) error
+
+	// Exists checks if credentials exist for a provider
+	Exists(ctx context.Context, providerURL string) (bool, error)
+}
+
+// noOpLogger is a no-op implementation of Logger for default use
+type noOpLogger struct{}
+
+func (n noOpLogger) Debug(msg string)                  {}
+func (n noOpLogger) Debugf(format string, args ...any) {}
+func (n noOpLogger) Info(msg string)                   {}
+func (n noOpLogger) Infof(format string, args ...any)  {}
+func (n noOpLogger) Error(msg string)                  {}
+func (n noOpLogger) Errorf(format string, args ...any) {}
+
+// NoOpLogger returns a no-op logger instance
+func NoOpLogger() Logger {
+	return noOpLogger{}
+}

internal/dcrstorage/storage_test.go

@@ -0,0 +1,464 @@
+package dcrstorage
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+)
+
+// mockCache implements Cache for testing
+type mockCache struct {
+	data map[string]cacheEntry
+	mu   sync.RWMutex
+}
+
+type cacheEntry struct {
+	value     any
+	expiresAt time.Time
+}
+
+func newMockCache() *mockCache {
+	return &mockCache{data: make(map[string]cacheEntry)}
+}
+
+func (m *mockCache) Get(key string) (any, bool) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	entry, ok := m.data[key]
+	if !ok {
+		return nil, false
+	}
+	if time.Now().After(entry.expiresAt) {
+		return nil, false
+	}
+	return entry.value, true
+}
+
+func (m *mockCache) Set(key string, value any, ttl time.Duration) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.data[key] = cacheEntry{
+		value:     value,
+		expiresAt: time.Now().Add(ttl),
+	}
+	return nil
+}
+
+func (m *mockCache) Delete(key string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.data, key)
+}
+
+func TestFileStore_SaveLoad(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+
+	store := NewFileStore(basePath, nil)
+
+	testCreds := &ClientRegistrationResponse{
+		ClientID:                "test-client-id",
+		ClientSecret:            "test-client-secret",
+		ClientSecretExpiresAt:   time.Now().Add(24 * time.Hour).Unix(),
+		RegistrationAccessToken: "test-access-token",
+		RegistrationClientURI:   "https://example.com/register/test-client-id",
+		RedirectURIs:            []string{"https://app.example.com/callback"},
+		GrantTypes:              []string{"authorization_code", "refresh_token"},
+		ResponseTypes:           []string{"code"},
+		TokenEndpointAuthMethod: "client_secret_basic",
+	}
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	t.Run("save and load credentials", func(t *testing.T) {
+		err := store.Save(ctx, providerURL, testCreds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to load credentials: %v", err)
+		}
+
+		if loaded == nil {
+			t.Fatal("Expected credentials but got nil")
+		}
+
+		if loaded.ClientID != testCreds.ClientID {
+			t.Errorf("ClientID mismatch: got %s, want %s", loaded.ClientID, testCreds.ClientID)
+		}
+		if loaded.ClientSecret != testCreds.ClientSecret {
+			t.Errorf("ClientSecret mismatch: got %s, want %s", loaded.ClientSecret, testCreds.ClientSecret)
+		}
+		if loaded.RegistrationAccessToken != testCreds.RegistrationAccessToken {
+			t.Errorf("RegistrationAccessToken mismatch: got %s, want %s", loaded.RegistrationAccessToken, testCreds.RegistrationAccessToken)
+		}
+	})
+
+	t.Run("load non-existent credentials", func(t *testing.T) {
+		tempDir2 := t.TempDir()
+		store2 := NewFileStore(filepath.Join(tempDir2, "nonexistent.json"), nil)
+
+		loaded, err := store2.Load(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Unexpected error for non-existent file: %v", err)
+		}
+		if loaded != nil {
+			t.Error("Expected nil for non-existent credentials")
+		}
+	})
+
+	t.Run("exists check", func(t *testing.T) {
+		exists, err := store.Exists(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if !exists {
+			t.Error("Expected credentials to exist")
+		}
+
+		exists, err = store.Exists(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if exists {
+			t.Error("Expected credentials to not exist")
+		}
+	})
+
+	t.Run("delete credentials", func(t *testing.T) {
+		err := store.Delete(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to delete credentials: %v", err)
+		}
+
+		exists, _ := store.Exists(ctx, providerURL)
+		if exists {
+			t.Error("Expected credentials to be deleted")
+		}
+	})
+
+	t.Run("delete non-existent credentials", func(t *testing.T) {
+		err := store.Delete(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Delete should not error for non-existent: %v", err)
+		}
+	})
+}
+
+func TestFileStore_MultiProvider(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	store := NewFileStore(basePath, nil)
+
+	ctx := context.Background()
+
+	provider1 := "https://auth1.example.com"
+	provider2 := "https://auth2.example.com"
+
+	creds1 := &ClientRegistrationResponse{
+		ClientID:     "client-1",
+		ClientSecret: "secret-1",
+	}
+	creds2 := &ClientRegistrationResponse{
+		ClientID:     "client-2",
+		ClientSecret: "secret-2",
+	}
+
+	if err := store.Save(ctx, provider1, creds1); err != nil {
+		t.Fatalf("Failed to save creds1: %v", err)
+	}
+	if err := store.Save(ctx, provider2, creds2); err != nil {
+		t.Fatalf("Failed to save creds2: %v", err)
+	}
+
+	loaded1, err := store.Load(ctx, provider1)
+	if err != nil {
+		t.Fatalf("Failed to load creds1: %v", err)
+	}
+	if loaded1.ClientID != "client-1" {
+		t.Errorf("Provider 1 ClientID mismatch: got %s", loaded1.ClientID)
+	}
+
+	loaded2, err := store.Load(ctx, provider2)
+	if err != nil {
+		t.Fatalf("Failed to load creds2: %v", err)
+	}
+	if loaded2.ClientID != "client-2" {
+		t.Errorf("Provider 2 ClientID mismatch: got %s", loaded2.ClientID)
+	}
+
+	if err := store.Delete(ctx, provider1); err != nil {
+		t.Fatalf("Failed to delete creds1: %v", err)
+	}
+
+	exists, _ := store.Exists(ctx, provider2)
+	if !exists {
+		t.Error("Provider 2 credentials should still exist")
+	}
+}
+
+func TestFileStore_ConcurrentAccess(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	store := NewFileStore(basePath, nil)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	creds := &ClientRegistrationResponse{
+		ClientID:     "test-client",
+		ClientSecret: "test-secret",
+	}
+
+	var wg sync.WaitGroup
+	concurrency := 10
+
+	for range concurrency {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_ = store.Save(ctx, providerURL, creds)
+		}()
+	}
+	wg.Wait()
+
+	for range concurrency {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = store.Load(ctx, providerURL)
+		}()
+	}
+	wg.Wait()
+
+	loaded, err := store.Load(ctx, providerURL)
+	if err != nil {
+		t.Fatalf("Failed to load after concurrent access: %v", err)
+	}
+	if loaded == nil || loaded.ClientID != "test-client" {
+		t.Error("Credentials corrupted after concurrent access")
+	}
+}
+
+func TestFileStore_InvalidInput(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	store := NewFileStore(basePath, nil)
+
+	ctx := context.Background()
+
+	t.Run("save nil credentials", func(t *testing.T) {
+		err := store.Save(ctx, "https://example.com", nil)
+		if err == nil {
+			t.Error("Expected error for nil credentials")
+		}
+	})
+
+	t.Run("empty provider URL uses default path", func(t *testing.T) {
+		creds := &ClientRegistrationResponse{ClientID: "test"}
+		err := store.Save(ctx, "", creds)
+		if err != nil {
+			t.Fatalf("Save with empty provider URL failed: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, "")
+		if err != nil {
+			t.Fatalf("Load with empty provider URL failed: %v", err)
+		}
+		if loaded == nil || loaded.ClientID != "test" {
+			t.Error("Failed to load credentials with empty provider URL")
+		}
+	})
+}
+
+func TestFileStore_DefaultPath(t *testing.T) {
+	t.Parallel()
+
+	store := NewFileStore("", nil)
+
+	if store.BasePath() == "" {
+		t.Error("Expected default base path")
+	}
+}
+
+func TestRedisStore_WithMockCache(t *testing.T) {
+	t.Parallel()
+
+	cache := newMockCache()
+	store := NewRedisStore(cache, "", nil)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	testCreds := &ClientRegistrationResponse{
+		ClientID:                "redis-test-client",
+		ClientSecret:            "redis-test-secret",
+		ClientSecretExpiresAt:   time.Now().Add(24 * time.Hour).Unix(),
+		RegistrationAccessToken: "redis-test-token",
+		RedirectURIs:            []string{"https://app.example.com/callback"},
+	}
+
+	t.Run("save and load credentials", func(t *testing.T) {
+		err := store.Save(ctx, providerURL, testCreds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials: %v", err)
+		}
+
+		loaded, err := store.Load(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to load credentials: %v", err)
+		}
+
+		if loaded == nil {
+			t.Fatal("Expected credentials but got nil")
+		}
+		if loaded.ClientID != testCreds.ClientID {
+			t.Errorf("ClientID mismatch: got %s, want %s", loaded.ClientID, testCreds.ClientID)
+		}
+		if loaded.ClientSecret != testCreds.ClientSecret {
+			t.Errorf("ClientSecret mismatch: got %s, want %s", loaded.ClientSecret, testCreds.ClientSecret)
+		}
+	})
+
+	t.Run("exists check", func(t *testing.T) {
+		exists, err := store.Exists(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Exists check failed: %v", err)
+		}
+		if !exists {
+			t.Error("Expected credentials to exist")
+		}
+	})
+
+	t.Run("delete credentials", func(t *testing.T) {
+		err := store.Delete(ctx, providerURL)
+		if err != nil {
+			t.Fatalf("Failed to delete credentials: %v", err)
+		}
+
+		exists, _ := store.Exists(ctx, providerURL)
+		if exists {
+			t.Error("Expected credentials to be deleted")
+		}
+	})
+
+	t.Run("load non-existent credentials", func(t *testing.T) {
+		loaded, err := store.Load(ctx, "https://nonexistent.example.com")
+		if err != nil {
+			t.Fatalf("Unexpected error for non-existent: %v", err)
+		}
+		if loaded != nil {
+			t.Error("Expected nil for non-existent credentials")
+		}
+	})
+}
+
+func TestRedisStore_TTLFromExpiry(t *testing.T) {
+	t.Parallel()
+
+	cache := newMockCache()
+	store := NewRedisStore(cache, "", nil)
+
+	ctx := context.Background()
+
+	t.Run("expired credentials should fail", func(t *testing.T) {
+		expiredCreds := &ClientRegistrationResponse{
+			ClientID:              "expired-client",
+			ClientSecret:          "expired-secret",
+			ClientSecretExpiresAt: time.Now().Add(-1 * time.Hour).Unix(),
+		}
+
+		err := store.Save(ctx, "https://expired.example.com", expiredCreds)
+		if err == nil {
+			t.Error("Expected error for expired credentials")
+		}
+	})
+
+	t.Run("credentials without expiry use default TTL", func(t *testing.T) {
+		creds := &ClientRegistrationResponse{
+			ClientID:              "no-expiry-client",
+			ClientSecret:          "no-expiry-secret",
+			ClientSecretExpiresAt: 0,
+		}
+
+		err := store.Save(ctx, "https://noexpiry.example.com", creds)
+		if err != nil {
+			t.Fatalf("Failed to save credentials without expiry: %v", err)
+		}
+	})
+}
+
+func TestRedisStore_InvalidInput(t *testing.T) {
+	t.Parallel()
+
+	cache := newMockCache()
+	store := NewRedisStore(cache, "", nil)
+
+	ctx := context.Background()
+
+	t.Run("save nil credentials", func(t *testing.T) {
+		err := store.Save(ctx, "https://example.com", nil)
+		if err == nil {
+			t.Error("Expected error for nil credentials")
+		}
+	})
+}
+
+func TestFileStore_CorruptedFile(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	basePath := filepath.Join(tempDir, "credentials.json")
+	store := NewFileStore(basePath, nil)
+
+	ctx := context.Background()
+	providerURL := "https://auth.example.com"
+
+	filePath := store.GetFilePath(providerURL)
+	if err := os.WriteFile(filePath, []byte("{corrupted json"), 0600); err != nil {
+		t.Fatalf("Failed to write corrupted file: %v", err)
+	}
+
+	_, err := store.Load(ctx, providerURL)
+	if err == nil {
+		t.Error("Expected error for corrupted JSON")
+	}
+}
+
+func TestFileStore_DirectoryCreation(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	deepPath := filepath.Join(tempDir, "deep", "nested", "path", "credentials.json")
+	store := NewFileStore(deepPath, nil)
+
+	ctx := context.Background()
+	creds := &ClientRegistrationResponse{ClientID: "test"}
+
+	err := store.Save(ctx, "https://example.com", creds)
+	if err != nil {
+		t.Fatalf("Failed to save with nested directory: %v", err)
+	}
+
+	loaded, err := store.Load(ctx, "https://example.com")
+	if err != nil {
+		t.Fatalf("Failed to load after nested directory creation: %v", err)
+	}
+	if loaded == nil || loaded.ClientID != "test" {
+		t.Error("Failed to load credentials from nested directory")
+	}
+}

internal/features/flags.go

@@ -12,9 +12,9 @@ import (
 type FeatureFlag struct {
 	name        string
 	description string
-	enabled     atomic.Bool
-	mu          sync.RWMutex
 	callbacks   []func(bool)
+	mu          sync.RWMutex
+	enabled     atomic.Bool
 }
 
 // FeatureManager manages all feature flags in the application
@@ -173,7 +173,7 @@ func (m *FeatureManager) LoadFromEnv() {
 	for name, flag := range flags {
 		envVar := "FEATURE_" + name
 		if value := os.Getenv(envVar); value != "" {
-			enabled := strings.ToLower(value) == "true" || value == "1"
+			enabled := strings.EqualFold(value, "true") || value == "1"
 			flag.enabled.Store(enabled)
 		}
 	}

internal/pool/transport.go

@@ -14,50 +14,41 @@ import (
 // and resource leaks. It provides centralized management of HTTP client transports with
 // proper lifecycle management and security controls.
 type TransportPool struct {
-	mu          sync.RWMutex
-	transports  map[string]*sharedTransport
-	maxConns    int
 	ctx         context.Context
+	transports  map[string]*sharedTransport
 	cancel      context.CancelFunc
-	clientCount int32 // Track total HTTP clients
-	maxClients  int32 // Limit total clients
+	maxConns    int
+	mu          sync.RWMutex
+	clientCount int32
+	maxClients  int32
 }
 
 // sharedTransport wraps an HTTP transport with reference counting
 type sharedTransport struct {
-	transport *http.Transport
-	refCount  int32
 	lastUsed  time.Time
+	transport *http.Transport
 	config    TransportConfig
+	refCount  int32
 }
 
 // TransportConfig defines configuration for HTTP transports
 type TransportConfig struct {
-	// Timeouts
-	DialTimeout           time.Duration
-	TLSHandshakeTimeout   time.Duration
+	MaxConnsPerHost       int
+	WriteBufferSize       int
 	ResponseHeaderTimeout time.Duration
 	ExpectContinueTimeout time.Duration
 	IdleConnTimeout       time.Duration
 	KeepAlive             time.Duration
-
-	// Connection limits
-	MaxIdleConns        int
-	MaxIdleConnsPerHost int
-	MaxConnsPerHost     int
-
-	// Features
-	ForceHTTP2         bool
-	DisableKeepAlives  bool
-	DisableCompression bool
-
-	// Buffer sizes
-	WriteBufferSize int
-	ReadBufferSize  int
-
-	// TLS
-	InsecureSkipVerify bool
-	MinTLSVersion      uint16
+	TLSHandshakeTimeout   time.Duration
+	MaxIdleConns          int
+	DialTimeout           time.Duration
+	MaxIdleConnsPerHost   int
+	ReadBufferSize        int
+	MinTLSVersion         uint16
+	ForceHTTP2            bool
+	DisableCompression    bool
+	InsecureSkipVerify    bool
+	DisableKeepAlives     bool
 }
 
 var (

internal/providers/aws_cognito.go

@@ -40,7 +40,7 @@ func (p *AWSCognitoProvider) BuildAuthParams(baseParams url.Values, scopes []str
 	// Remove offline_access scope as Cognito doesn't use it (case-insensitive)
 	var filteredScopes []string
 	for _, scope := range scopes {
-		if strings.ToLower(scope) != ScopeOfflineAccess {
+		if !strings.EqualFold(scope, ScopeOfflineAccess) {
 			filteredScopes = append(filteredScopes, scope)
 		}
 	}

internal/providers/azure_test.go

@@ -154,10 +154,10 @@ func TestAzureProvider_ValidateTokens(t *testing.T) {
 	provider := NewAzureProvider()
 
 	tests := []struct {
-		name           string
-		session        *mockSession
 		verifierError  error
+		session        *mockSession
 		cacheData      map[string]interface{}
+		name           string
 		expectedResult ValidationResult
 	}{
 		{
@@ -369,9 +369,9 @@ func TestAzureProvider_OfflineAccessHandling(t *testing.T) {
 
 	tests := []struct {
 		name          string
-		inputScopes   []string
-		expectedCount int // Expected number of offline_access scopes (should be 1)
 		description   string
+		inputScopes   []string
+		expectedCount int
 	}{
 		{
 			name:          "No offline_access - should add one",

internal/providers/base_test.go

@@ -8,10 +8,10 @@ import (
 
 // Mock implementations for testing
 type mockSession struct {
-	authenticated bool
 	idToken       string
 	accessToken   string
 	refreshToken  string
+	authenticated bool
 }
 
 func (s *mockSession) GetIDToken() string      { return s.idToken }
@@ -338,10 +338,10 @@ func TestBaseProvider_ValidateTokenExpiry(t *testing.T) {
 	gracePeriod := 5 * time.Minute
 
 	tests := []struct {
-		name           string
 		claims         map[string]interface{}
-		cacheFound     bool
+		name           string
 		expectedResult ValidationResult
+		cacheFound     bool
 	}{
 		{
 			name:       "Token not found in cache, has refresh token",
@@ -438,10 +438,10 @@ func TestBaseProvider_ValidateTokenExpiry_NoRefreshToken(t *testing.T) {
 	gracePeriod := 5 * time.Minute
 
 	tests := []struct {
-		name           string
 		claims         map[string]interface{}
-		cacheFound     bool
+		name           string
 		expectedResult ValidationResult
+		cacheFound     bool
 	}{
 		{
 			name:       "Token not found in cache, no refresh token",

internal/providers/factory_test.go

@@ -25,9 +25,9 @@ func TestProviderFactory_CreateProvider(t *testing.T) {
 	tests := []struct {
 		name         string
 		issuerURL    string
+		errMsg       string
 		expectedType ProviderType
 		wantErr      bool
-		errMsg       string
 	}{
 		{
 			name:         "Google provider",
@@ -158,10 +158,10 @@ func TestProviderFactory_CreateProviderByType(t *testing.T) {
 
 	tests := []struct {
 		name         string
+		errMsg       string
 		providerType ProviderType
 		expectedType ProviderType
 		wantErr      bool
-		errMsg       string
 	}{
 		{
 			name:         "Generic provider",

internal/providers/generic_test.go

@@ -136,9 +136,9 @@ func TestGenericProvider_ValidateTokens(t *testing.T) {
 	provider := NewGenericProvider()
 
 	tests := []struct {
-		name           string
-		session        *mockSession
 		verifierError  error
+		session        *mockSession
+		name           string
 		expectedResult ValidationResult
 	}{
 		{

internal/providers/google_test.go

@@ -172,8 +172,8 @@ func TestGoogleProvider_OfflineAccessFiltering(t *testing.T) {
 
 	tests := []struct {
 		name        string
-		inputScopes []string
 		description string
+		inputScopes []string
 	}{
 		{
 			name:        "Multiple offline_access occurrences",

internal/providers/registry.go

@@ -147,7 +147,8 @@ func (r *ProviderRegistry) detectProviderUnsafe(issuerURL string) OIDCProvider {
 				return p
 			}
 		case ProviderTypeKeycloak:
-			if strings.Contains(host, "keycloak") || strings.Contains(normalizedURL.Path, "/auth/realms/") {
+			// Match both Keycloak <17 (`/auth/realms/`) and 17+ (`/realms/`).
+			if strings.Contains(host, "keycloak") || strings.Contains(normalizedURL.Path, "/realms/") {
 				return p
 			}
 		case ProviderTypeAWSCognito:

internal/providers/registry_test.go

@@ -82,9 +82,9 @@ func TestProviderRegistry_GetProviderByType(t *testing.T) {
 	registry.RegisterProvider(googleProvider)
 
 	tests := []struct {
+		expected     OIDCProvider
 		name         string
 		providerType ProviderType
-		expected     OIDCProvider
 	}{
 		{
 			name:         "Get Generic provider",
@@ -180,9 +180,9 @@ func TestProviderRegistry_DetectProvider(t *testing.T) {
 	registry.RegisterProvider(gitlabProvider)
 
 	tests := []struct {
+		expected  OIDCProvider
 		name      string
 		issuerURL string
-		expected  OIDCProvider
 	}{
 		{
 			name:      "Google provider detection",
@@ -225,10 +225,15 @@ func TestProviderRegistry_DetectProvider(t *testing.T) {
 			expected:  oktaProvider,
 		},
 		{
-			name:      "Keycloak provider detection",
+			name:      "Keycloak provider detection (legacy /auth/realms/)",
 			issuerURL: "https://auth.example.com/auth/realms/master",
 			expected:  keycloakProvider,
 		},
+		{
+			name:      "Keycloak provider detection (modern /realms/, KC 17+)",
+			issuerURL: "https://auth.example.com/realms/master",
+			expected:  keycloakProvider,
+		},
 		{
 			name:      "AWS Cognito provider detection",
 			issuerURL: "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example",
@@ -640,9 +645,9 @@ func TestProviderRegistry_GitLabDetection_RealWorldURLs(t *testing.T) {
 	registry.RegisterProvider(githubProvider)
 
 	realWorldTests := []struct {
+		expected  OIDCProvider
 		name      string
 		issuerURL string
-		expected  OIDCProvider
 	}{
 		// Actual self-hosted GitLab examples from issue #61
 		{

internal/providers/validation_test.go

@@ -20,8 +20,8 @@ func TestValidateIssuerURL(t *testing.T) {
 	tests := []struct {
 		name      string
 		issuerURL string
-		wantErr   bool
 		errMsg    string
+		wantErr   bool
 	}{
 		{
 			name:      "valid https URL",
@@ -106,8 +106,8 @@ func TestValidateClientID(t *testing.T) {
 	tests := []struct {
 		name     string
 		clientID string
-		wantErr  bool
 		errMsg   string
+		wantErr  bool
 	}{
 		{
 			name:     "valid client ID",
@@ -173,9 +173,9 @@ func TestValidateClientID(t *testing.T) {
 func TestValidateScopes(t *testing.T) {
 	tests := []struct {
 		name    string
+		errMsg  string
 		scopes  []string
 		wantErr bool
-		errMsg  string
 	}{
 		{
 			name:    "valid scopes with openid",
@@ -248,8 +248,8 @@ func TestValidateRedirectURL(t *testing.T) {
 	tests := []struct {
 		name        string
 		redirectURL string
-		wantErr     bool
 		errMsg      string
+		wantErr     bool
 	}{
 		{
 			name:        "valid https redirect URL",
@@ -315,11 +315,11 @@ func TestValidateRedirectURL(t *testing.T) {
 // TestValidateProviderSpecificConfig tests provider-specific configuration validation
 func TestValidateProviderSpecificConfig(t *testing.T) {
 	tests := []struct {
-		name     string
 		provider OIDCProvider
 		config   map[string]interface{}
-		wantErr  bool
+		name     string
 		errMsg   string
+		wantErr  bool
 	}{
 		{
 			name:     "valid Google config",
@@ -458,8 +458,8 @@ func TestValidateGoogleConfig_EdgeCases(t *testing.T) {
 	googleProvider := NewGoogleProvider()
 
 	tests := []struct {
-		name    string
 		config  map[string]interface{}
+		name    string
 		wantErr bool
 	}{
 		{
@@ -502,10 +502,10 @@ func TestValidateAzureConfig_EdgeCases(t *testing.T) {
 	azureProvider := NewAzureProvider()
 
 	tests := []struct {
-		name    string
 		config  map[string]interface{}
-		wantErr bool
+		name    string
 		errMsg  string
+		wantErr bool
 	}{
 		{
 			name: "valid tenant ID format",

internal/providers/warnings.go

@@ -7,9 +7,9 @@ import (
 
 // ProviderWarning represents a warning about provider limitations or requirements.
 type ProviderWarning struct {
-	ProviderType ProviderType
-	Level        string // "info", "warning", "error"
+	Level        string
 	Message      string
+	ProviderType ProviderType
 }
 
 // GetProviderWarnings returns warnings about provider-specific limitations.
@@ -18,16 +18,17 @@ func GetProviderWarnings(providerType ProviderType) []ProviderWarning {
 
 	switch providerType {
 	case ProviderTypeGitHub:
-		warnings = append(warnings, ProviderWarning{
-			ProviderType: ProviderTypeGitHub,
-			Level:        "warning",
-			Message:      "GitHub uses OAuth 2.0, not OpenID Connect. ID tokens are not available. Use access tokens for API calls only.",
-		})
-		warnings = append(warnings, ProviderWarning{
-			ProviderType: ProviderTypeGitHub,
-			Level:        "info",
-			Message:      "GitHub OAuth apps do not support refresh tokens. Users will need to re-authenticate when tokens expire.",
-		})
+		warnings = append(warnings,
+			ProviderWarning{
+				ProviderType: ProviderTypeGitHub,
+				Level:        "warning",
+				Message:      "GitHub uses OAuth 2.0, not OpenID Connect. ID tokens are not available. Use access tokens for API calls only.",
+			},
+			ProviderWarning{
+				ProviderType: ProviderTypeGitHub,
+				Level:        "info",
+				Message:      "GitHub OAuth apps do not support refresh tokens. Users will need to re-authenticate when tokens expire.",
+			})
 
 	case ProviderTypeAuth0:
 		warnings = append(warnings, ProviderWarning{