chore(release): v1.0.26

* fix(security): encrypt session cookies + fail closed on invalid config

Batch 1 of security audit remediation (ranks 1, 2, 6).

- session.go: derive independent HMAC + AES-256 keys via stdlib HKDF-SHA256
  and build the gorilla cookie store with both, so session cookies are now
  encrypted, not merely signed. The single-key store previously left OIDC
  access/refresh/ID tokens recoverable from raw cookie bytes. Cookie format
  changes, so existing sessions are invalidated on deploy (one-time re-login).
- main.go: call config.Validate() at construction and error out on failure,
  instead of silently substituting a public hardcoded encryption key for
  empty/short keys (which allowed session forgery). The yaegi analyzer
  passes via .traefik.yml testData.
- settings.go: isValidSecureURL permits plaintext HTTP for loopback hosts
  only (RFC 8252); remote providers must still use HTTPS.
- tests: complete configs that did not satisfy Validate(); add regression
  tests in security_audit_fixes_test.go.

Configs below documented minimums (rateLimit < 10, key < 32 chars) are now
rejected at startup (fail closed).

* fix(security): validate discovered OIDC endpoints + pin introspection host

Batch 2 of security audit remediation (ranks 3, 4).

- url_helpers.go: add validateDiscoveredEndpoint, an SSRF screen for endpoints
  taken from the provider discovery document (jwks_uri, token, authorization,
  revocation, end_session, introspection, registration). Blocks link-local
  (cloud metadata 169.254.169.254), multicast, unspecified and private
  addresses (unless allowPrivateIPAddresses); blocks loopback unless the
  configured providerURL is itself loopback (dev/test). Cross-domain JWKS
  hosts (e.g. Google) stay allowed. Add sameHost helper.
- main.go: updateMetadataEndpoints screens every discovered endpoint and
  blanks any that fail (fail closed downstream). The introspection endpoint
  carries the client secret via HTTP Basic, so it is additionally pinned to
  the providerURL host to stop a poisoned discovery document exfiltrating the
  secret to an attacker-controlled host.
- tests: regression tests for the SSRF guard and the host pin.

* fix(security): close open redirects + anchor excluded-URL matching

Batch 3 of security audit remediation (ranks 5, 14, 15).

- auth_flow.go: run the stored incoming path through normalizeLogoutPath
  before using it as the post-login redirect, so //evil.com and /\evil.com
  payloads become host-relative (open-redirect, rank 5).
- url_helpers.go: excluded-URL matching is anchored at a natural boundary
  (exact, sub-path "/", or file extension "."), so excluding "/public" no
  longer also bypasses auth on "/publicsecret"; "/favicon" still matches
  "/favicon.ico" (rank 14).
- internal/utils: X-Forwarded-Host is sanitized (first value only; reject
  CRLF/whitespace/multi-value) before building redirect URLs (rank 15).
- helpers.go: the logout redirect used when there is no provider end-session
  endpoint is host-relative, never an absolute URL derived from the
  client-controllable request host (logout open-redirect, rank 15).
- tests: update two logout cases that asserted the old absolute redirect;
  add regression tests.

* fix(security): reject unverified Azure tokens; fix transport TLS reuse

Batch 4 of security audit remediation (ranks 7, 11).

- token_validation_rs.go: an Azure nonce-bearing access token that cannot be
  cryptographically verified no longer returns "authenticated" when there is
  no ID token to corroborate it; it refreshes (if possible) or forces
  re-authentication instead of failing open (rank 7).
- http_client_pool.go: the at-limit transport-reuse path now takes the write
  lock before mutating refCount (fixes a data race) and only reuses a
  transport whose TLS settings (CA pool + InsecureSkipVerify) match the
  caller's, never one with a different trust store; if none matches it returns
  nil so the caller falls back to a verifying default transport (rank 11).
- tests: add a transport-pool TLS-isolation regression test.

* fix(security): stop logging templated header values (token leak)

Batch 5 of security audit remediation (rank 16).

middleware.go: templated downstream headers commonly carry the access token
(e.g. "Authorization: Bearer {{.AccessToken}}"). The debug log line printed
the full header value, leaking credentials into logs. Log the header name and
byte length instead.

* fix(security): cache-key collision, cache-config divergence, fleet cleanup

Batch 6 of security audit remediation (ranks 9, 10, 12).

- token_manager.go: detectTokenType keys its cache on a SHA-256 hash of the
  full token instead of the first 32 chars (which are only the base64url JWT
  header). Distinct tokens sharing alg+kid no longer collide and get
  mis-classified (rank 10).
- cache_manager.go: the process-global cache manager is initialized once and
  shared across plugin instances; it now logs a loud warning when a later
  instance requests a different explicit Redis backend that is silently
  ignored, surfacing the cross-instance state-isolation hazard (rank 9).
- singleton_resources.go / main.go / utilities.go: track a process-global live
  instance count; the shared singleton-token-cleanup task is stopped only when
  the LAST instance shuts down, so one instance's Close() (e.g. a config reload)
  no longer kills cleanup for surviving instances (rank 12).
- tests: update TestDetectTokenTypeCaching for the new key; add regression tests.

* fix(security): bound introspection cache + cookie lifetime to config

Batch 7 of security audit remediation (ranks 8, 13).

- token_introspection.go: when requireTokenIntrospection is enabled, cap the
  positive introspection-result cache at 30s (instead of 5m) so a token
  revoked at the provider stops passing within ~30s, matching the operator's
  near-real-time revocation expectation (rank 8).
- session.go: bind the cookie store's MaxAge to the configured sessionMaxAge,
  so the cookie codec's cryptographic timestamp validity is no longer fixed at
  gorilla's 30-day default; a stolen cookie is valid only for the configured
  session lifetime (rank 13).
- tests: add a cookie-lifetime regression test.

* fix(security): low-severity hardening (cache, DoS caps, PKCE, throttle)

Batch 8 of security audit remediation — low severity
(ranks 24, 25, 27, 29, 31, 36, 37, 41, 45, 46, 49).

- universal_cache.go: updateLocalCache updates an existing key in place instead
  of orphaning its LRU element and double-counting currentSize/currentMemory
  (rank 36 — the only production-reachable bug in this batch).
- jwk.go / metadata_cache.go / token_introspection.go: bound response bodies
  with io.LimitReader (1 MiB) to prevent memory exhaustion from a hostile or
  buggy provider (ranks 24, 25).
- jwk.go: skip JWKs not usable for signature verification (use != sig, or
  key_ops without "verify") when building the key set (rank 49).
- auth_flow.go: fail closed at the callback when PKCE is enabled but the code
  verifier is missing, instead of silently dropping it (rank 27).
- utilities.go / main.go: match allowedUserDomains case-insensitively (rank 31).
- bearer_auth.go: a single success no longer wipes an active per-IP penalty;
  the counter resets only when no penalty is in effect (rank 29).
- main.go: handle (not discard) the NewSessionManager error (rank 37).
- error_recovery.go: take a write lock in isServiceDegraded (it deletes from a
  map); compare retryable-error substrings case-insensitively (ranks 45, 46).
- singleton_resources.go: bind the generic-cache cleanup goroutine to the
  resource-manager shutdown channel so it cannot outlive its owner (rank 41).
- tests: update the bearer throttle test to the corrected penalty semantics.

* fix(security): header sanitization, issuer pinning, fail-closed paths

Batch 9 of security audit remediation (ranks 18, 19, 20, 21, 22, 30, 33, 34).

- middleware.go / bearer_auth.go: sanitize claim-derived values on the cookie
  auth path before injecting them into downstream headers. Drop group/role and
  identifier values containing control chars, bidi-override runes, or the
  , ; = delimiters (a comma would inject phantom entries into X-User-Groups);
  reject control/bidi/over-length in rendered templated header output (but
  permit , ; = in free-form values such as a bearer token). The bearer path
  already sanitized; the cookie path did not (ranks 33, 34).
- main.go / metadata_cache.go: pin the discovered issuer to the configured
  provider host (sameHost) and refuse/never-cache a mismatch, so a poisoned
  discovery document cannot redefine the JWT trust anchor (ranks 21, 22).
- token_introspection.go: when a distinct API audience is configured, fail
  closed on a missing or mismatched introspection audience; aud parsed as
  string-or-array per RFC 7662 (rank 19).
- logout.go: front-channel logout requires a matching issuer; an empty iss is
  rejected (blocks unauthenticated forced-logout via a known sid) (rank 30).
- token_validation_rs.go: an opaque access token with no ID token and no
  successful introspection fails closed (re-auth) instead of authenticating
  (ranks 18, 20).
- tests: realistic same-host provider mocks; regression tests for the header
  sanitization distinction and the fail-closed paths.

* chore(security): remove unwired dead code with latent footguns

Batch 10 of security audit remediation — delete confirmed-dead, unwired
subsystems (ranks 26, 35, 50). None had a production caller (grep-verified);
removal eliminates the latent footguns and ~2.1k lines of dead code.

- token_validator.go (deleted): an unused *TokenValidator whose validateJWT set
  Valid=true with NO signature verification — a severe footgun if ever wired
  (rank 50). The wired RS-aware validators are unaffected.
- security_monitoring.go (deleted): an unused *SecurityMonitor / ExtractClientIP
  that trusted spoofable X-Forwarded-For / X-Real-IP. The live bearer throttle
  uses clientIPForBearer (RemoteAddr-only), unchanged (rank 35).
- dynamic_client_registration.go: removed the RFC 7592 management methods
  (Update/Read/DeleteClientRegistration) that dereferenced an attacker-
  influenced RegistrationClientURI with the registration token attached and no
  HTTPS/SSRF gate, and had no callers. The wired RFC 7591 RegisterClient and
  credential-store helpers are kept (rank 26).
- tests: removed the tests covering the deleted code.

* chore: add Makefile with yaegi load validation

No Makefile existed. The new `yaegi-validate` target interprets the plugin
under the yaegi interpreter the same way Traefik loads it, catching yaegi-only
incompatibilities (unsupported stdlib symbols, reflection edge cases) that the
native `go build` / `go test` toolchain does not. Importing the plugin forces
yaegi to interpret every file plus its vendored deps; CreateConfig + New
exercise the instantiation path.

- cmd/yaegicheck/main.go: the load driver, marked //go:build ignore so it is
  excluded from `go build ./...` (avoids VCS-stamping a main binary, which
  fails in git-worktree layouts) yet is run explicitly by yaegi.
- Makefile: build / fmt / vet / lint / test / vendor / yaegi-validate / check
  targets; `make check` runs vet + tests + yaegi-validate.

Verified: `make yaegi-validate` passes on this branch — the HKDF cookie
encryption, net-based endpoint validation, and claim sanitizers all interpret
and instantiate cleanly under yaegi.

* ci: bump workflow Go toolchain to 1.25; pin yaegi-validate to v0.16.1

Traefik v3.7.1 (the deployed version) is built with `go 1.25.0`, so the PR and
release workflows now use Go 1.25.x to match the toolchain Traefik uses.

Important distinction: the CI Go version is the build TOOLCHAIN. The plugin's
actual interpreter-compatibility ceiling is the yaegi version Traefik bundles
(v0.16.1, which declares go 1.21 and ships a ~Go 1.22 stdlib symbol surface),
NOT the CI Go version. That ceiling is enforced by `make yaegi-validate` plus
the go.mod language directive — e.g. it is why HKDF is hand-rolled with
hmac+sha256 rather than Go 1.24's crypto/hkdf, which yaegi v0.16.1 lacks.

Also pin Makefile YAEGI_VERSION to v0.16.1 (what Traefik v3.7.1 vendors) so
yaegi-validate exercises the real deployed interpreter instead of @latest,
which could pass on a newer yaegi that supports symbols the deployed one does
not.

* docs: align README/CONFIGURATION with branch behavior changes

- excludedURLs: documented as segment/extension-boundary matching (was
  "prefix-matched") — "/public" no longer also matches "/publicsecret" (rank 14).
- Front-channel logout now requires a matching `iss`; requests without one are
  rejected with 400 (rank 30).
- Add an "Upgrading from an earlier release" note: session cookies are now
  AES-256 encrypted with lifetime tracking sessionMaxAge (one-time re-login on
  upgrade), and invalid configuration (rateLimit < 10, key < 32 bytes, missing
  callbackURL, non-HTTPS remote providerURL) now fails closed at startup.

* fix: remove staticcheck-flagged unused functions; wire staticcheck into make check

CI Static Analysis (standalone staticcheck) failed with U1000 "unused":
- dynamic_client_registration.go: deleteCredentialsFromStore — its only caller
  was the RFC 7592 DeleteClientRegistration removed in the dead-code batch.
- token_test.go: createTestJWTSimple — its only callers were the TokenValidator
  tests removed in the same batch.
Both confirmed to have zero remaining callers and removed. build / vet /
go test ./... / staticcheck ./... all green.

The pre-commit hook runs golangci-lint, but CI runs standalone staticcheck
(which flags U1000). Add a `staticcheck` Makefile target and include it in
`make check` so this class of finding is caught locally before push.

* fix(test): stabilize flaky TestWorkerPool_TaskPanic

tasksFailed is incremented in the worker's deferred recover(), which runs after the panicking task's own defer wg.Done(). wg.Wait() could therefore return before the failure was recorded, so reading the counter immediately raced and flaked on slow CI runners. Poll until the failure lands (2s budget) instead. Verified 200x plain + 50x under -race/GOMAXPROCS=1.

.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/pr.yaml

@@ -18,6 +18,6 @@ jobs:
   pr-checks:
     uses: lukaszraczylo/shared-actions/.github/workflows/go-pr.yaml@main
     with:
-      go-version: "1.24.11"
+      go-version: "1.25.x"
       coverage-threshold: 70
     secrets: inherit

.github/workflows/release.yml

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

.traefik.yml

@@ -80,3 +80,25 @@ testData:
   #   address: redis:6379
   #   password: urn:k8s:secret:redis:password
   #   cacheMode: hybrid
+
+  # Optional: bearer-token authentication for M2M (machine-to-machine) API
+  # clients. Default off. When enabled, requests presenting
+  # "Authorization: Bearer <jwt>" are validated against the configured OIDC
+  # provider (signature/issuer/audience/exp) and forwarded without creating
+  # a cookie session. The bearer path REJECTS ID tokens, requires a non-
+  # default audience, and never trusts the `email` claim as the identifier.
+  # See docs/BEARER_AUTH.md for the full threat model.
+  #
+  # enableBearerAuth: true                # opt-in
+  # audience: https://api.example.com     # REQUIRED when bearer is enabled
+  # bearerIdentifierClaim: sub            # default; used as X-Forwarded-User. `email` is rejected.
+  # stripAuthorizationHeader: true        # default; drops the raw token before forwarding
+  # bearerEmitWWWAuthenticate: true       # default; RFC 6750 hint on 401s
+  # bearerOverridesCookie: false          # default; cookie wins when both are present
+  # requireTokenIntrospection: false      # opt-in; calls RFC 7662 introspection per request
+  # maxTokenAgeSeconds: 86400             # 24h cap on iat (rejects clock-skew/forever tokens)
+  # maxIdentifierLength: 256              # cap on the sanitised principal identifier
+  # bearerFailureThreshold: 20            # consecutive 401s/IP that trip the throttle
+  # bearerFailureWindowSeconds: 60        # rolling window over which 401s are counted
+  # bearerFailurePenaltySeconds: 60       # 429 + Retry-After duration after threshold trips
+

Makefile

@@ -0,0 +1,61 @@
+# traefikoidc — Makefile
+# Run `make help` for available targets.
+
+GO            ?= go
+GOPATH        := $(shell $(GO) env GOPATH)
+# Pin to the yaegi version bundled by the deployed Traefik so yaegi-validate
+# tests the real interpreter, not a newer one that may support more. Traefik
+# v3.7.1 vendors yaegi v0.16.1 (Go ~1.22 stdlib surface). Bump when Traefik is.
+YAEGI_VERSION ?= v0.16.1
+TEST_TIMEOUT  ?= 480s
+
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show this help
+	@grep -hE '^[a-zA-Z0-9_-]+:.*## ' $(MAKEFILE_LIST) | awk 'BEGIN{FS=":.*## "}{printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: build
+build: ## Compile all packages (native toolchain)
+	$(GO) build ./...
+
+.PHONY: fmt
+fmt: ## Format sources with gofmt
+	gofmt -w $$(git ls-files '*.go' | grep -v '^vendor/')
+
+.PHONY: vet
+vet: ## Run go vet
+	$(GO) vet ./...
+
+.PHONY: lint
+lint: ## Run golangci-lint if available
+	@command -v golangci-lint >/dev/null 2>&1 && golangci-lint run ./... || echo "golangci-lint not installed; skipping"
+
+.PHONY: staticcheck
+staticcheck: ## Run staticcheck (matches the CI "Static Analysis" job; catches U1000 unused, etc.)
+	@command -v staticcheck >/dev/null 2>&1 || { echo ">> installing staticcheck"; $(GO) install honnef.co/go/tools/cmd/staticcheck@latest; }
+	@GOFLAGS=-buildvcs=false $$(command -v staticcheck || echo "$(GOPATH)/bin/staticcheck") ./...
+
+.PHONY: test
+test: ## Run the test suite
+	$(GO) test ./... -count=1 -timeout $(TEST_TIMEOUT)
+
+.PHONY: vendor
+vendor: ## Refresh and vendor dependencies
+	$(GO) mod tidy && $(GO) mod vendor
+
+# yaegi-validate interprets the plugin under the yaegi interpreter the same way
+# Traefik loads it. Native `go build`/`go test` use the standard compiler and do
+# NOT catch yaegi-only incompatibilities (unsupported stdlib symbols, reflection
+# edge cases). This target does. Importing the package forces yaegi to interpret
+# every file in it plus its vendored deps; CreateConfig + New exercise the
+# instantiation path. Pin YAEGI_VERSION to match Traefik's bundled yaegi if you
+# need exact parity.
+.PHONY: yaegi-validate
+yaegi-validate: ## Verify the plugin loads under Traefik's yaegi interpreter
+	@command -v yaegi >/dev/null 2>&1 || { echo ">> installing yaegi@$(YAEGI_VERSION)"; $(GO) install github.com/traefik/yaegi/cmd/yaegi@$(YAEGI_VERSION); }
+	@echo ">> interpreting plugin under yaegi (as Traefik does)"
+	@DO_NOT_TRACK=1 GOFLAGS=-mod=vendor $$(command -v yaegi || echo "$(GOPATH)/bin/yaegi") run ./cmd/yaegicheck/main.go
+
+.PHONY: check
+check: vet staticcheck test yaegi-validate ## vet + staticcheck + tests + yaegi load validation

README.md

@@ -9,6 +9,7 @@ manages sessions, and forwards user identity to downstream services.
 - [Configuration reference](docs/CONFIGURATION.md) — every parameter
 - [Provider guide](docs/PROVIDERS.md) — Google, Azure, Auth0, Okta, Keycloak, Cognito, GitLab, GitHub, generic
 - [Auth0 audience guide](docs/AUTH0_AUDIENCE_GUIDE.md) — custom APIs, opaque tokens, token confusion
+- [Bearer-token (M2M) auth](docs/BEARER_AUTH.md) — opt-in `Authorization: Bearer` path, threat model
 - [Redis cache](docs/REDIS.md) — multi-replica deployments
 - [Dynamic Client Registration](docs/DCR.md) — RFC 7591
 - [Development](docs/DEVELOPMENT.md) · [Testing](docs/TESTING.md)
@@ -110,7 +111,8 @@ Full reference in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 | `logoutURL` | `callbackURL + "/logout"` | RP-initiated logout path. |
 | `postLogoutRedirectURI` | `/` | Where to send users after logout. |
 | `scopes` | appended to `openid profile email` | Extra OAuth scopes. Set `overrideScopes: true` to replace defaults. |
-| `excludedURLs` | none | Prefix-matched paths that bypass auth. |
+| `extraAuthParams` | none | Map of extra query parameters appended to the authorization request (e.g. `screen_hint: signup`, `login_hint`, `ui_locales`, `prompt`). Plugin-managed params (`client_id`, `state`, `nonce`, `redirect_uri`, `code_challenge`, `scope`, `response_type`, …) cannot be overridden. |
+| `excludedURLs` | none | Paths that bypass auth, matched at a path-segment or file-extension boundary (e.g. `/public` matches `/public`, `/public/sub` and `/public.json`, but **not** `/publicsecret`). |
 | `allowedUserDomains` | none | Restrict to email domains. |
 | `allowedUsers` | none | Restrict to specific addresses (or claim values when `userIdentifierClaim != email`). |
 | `allowedRolesAndGroups` | none | Require any of these roles/groups from ID-token claims. |
@@ -145,6 +147,18 @@ Full reference in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 
 ## Production gotchas
 
+### Upgrading from an earlier release
+
+- **Sessions are re-issued once.** Session cookies are now AES-256 encrypted
+  (previously signed only) and their cryptographic lifetime tracks
+  `sessionMaxAge` (previously a fixed 30 days). Existing cookies become invalid
+  on upgrade, so users re-authenticate one time.
+- **Invalid configuration now fails closed at startup** instead of being
+  silently accepted: a `sessionEncryptionKey` shorter than 32 bytes, a
+  `rateLimit` below 10, a missing `callbackURL`, or a non-HTTPS remote
+  `providerURL` are rejected. Plaintext HTTP is permitted only for loopback
+  hosts (local development).
+
 ### TLS termination at a load balancer
 
 `forceHTTPS` defaults to `true`, so redirect URIs always use `https://`. This is
@@ -164,6 +178,8 @@ detected" when the same token hits different replicas. Two options:
 
 For IdP-initiated logout (back/front-channel) in multi-replica setups, Redis is
 **required** so a logout on one instance invalidates sessions on the others.
+Front-channel logout requests must include a matching `iss` query parameter;
+requests that omit it are rejected with `400`.
 
 ### Multiple middleware instances on the same host
 
@@ -171,6 +187,92 @@ Each instance must use a unique `cookiePrefix` **and** `sessionEncryptionKey`,
 otherwise a session minted by one instance can grant access through another.
 See [issue #87](https://github.com/lukaszraczylo/traefikoidc/issues/87).
 
+### Bearer-token (M2M) authentication
+
+Opt-in path for API clients that present `Authorization: Bearer <jwt>` instead
+of logging in via the browser flow. Default off. When enabled, the middleware
+validates the bearer JWT against the configured OIDC provider (signature,
+issuer, audience, expiry) and forwards the request downstream with the
+principal headers — no cookie session is created.
+
+```yaml
+enableBearerAuth: true
+audience: https://api.example.com   # REQUIRED when bearer is enabled
+# optional, defaults shown:
+bearerIdentifierClaim: sub          # claim used as X-Forwarded-User
+stripAuthorizationHeader: true      # drop the raw token before forwarding
+bearerEmitWWWAuthenticate: true     # RFC 6750 hint on 401s
+bearerOverridesCookie: false        # cookie wins when both are present (safer)
+maxTokenAgeSeconds: 86400           # 24h cap on iat
+bearerFailureThreshold: 20          # consecutive 401s/IP before 429 throttle
+```
+
+Hardening built in by default:
+
+- **Audience required.** Startup fails if `enableBearerAuth=true` and
+  `audience` is unset. Eliminates the "token issued for service B accepted
+  by A" confusion vector.
+- **ID tokens explicitly rejected.** Bearer is access-token-only. ID tokens
+  (detected via `nonce`, `typ: at+jwt`, `token_use`, `scope`, or audience
+  shape) return `401`.
+- **`alg` and `kid` pinned at the entrypoint.** Asymmetric-only allowlist
+  (`RS256/384/512`, `PS256/384/512`, `ES256/384/512`); `kid` length and
+  charset capped — both checked **before** any JWKS fetch so attacker noise
+  can't amplify into upstream calls.
+- **Identifier sanitised.** Default identifier source is `sub`; `email` is
+  rejected unless explicitly opted in (which the middleware still refuses to
+  avoid the unverified-email spoofing footgun). Control characters, bidi-
+  override codepoints, and the delimiters `, ; =` are all rejected before
+  the value reaches `X-Forwarded-User`.
+- **Multi-audience tokens require `azp`.** When `aud` is an array of more
+  than one element, the token must carry `azp == clientID`.
+- **`iat` upper-age bound.** Tokens older than `maxTokenAgeSeconds` are
+  rejected even if `exp` is far in the future.
+- **Per-IP 401 throttle.** After `bearerFailureThreshold` consecutive 401s
+  from one source IP, further bearer requests from that IP are rejected
+  with `429 Too Many Requests` + `Retry-After`.
+- **Cookie-wins by default.** When both a session cookie and an
+  `Authorization: Bearer` header arrive on the same request, the cookie path
+  runs (safer against browser/extension/proxy bearer injection). Set
+  `bearerOverridesCookie: true` for the AWS/GCP/Kubernetes convention.
+- **Replay protection preserved.** The bearer path skips the JTI **Set**
+  (so the same token can be reused) but the **Get** stays active —
+  `RevokeToken` still terminates a bearer token immediately.
+- **Excluded URLs strip Authorization.** When `enableBearerAuth=true`,
+  excluded paths (e.g. `/health`, `/metrics`) get the `Authorization` header
+  removed before forwarding so the token can't leak into public endpoint
+  logs.
+- **Optional real-time revocation.** Set `requireTokenIntrospection: true`
+  to call RFC 7662 introspection on every cache miss; revoked tokens fail
+  immediately. Introspection endpoint failures return `503` (distinguishes
+  infra outage from credential rejection).
+
+**Obtaining bearer tokens** — minting is the IdP's job, not the
+middleware's. The canonical M2M flow is OAuth 2.0 `client_credentials`
+(RFC 6749 §4.4); Google requires JWT bearer assertion (RFC 7523) instead.
+Minimal Auth0-shape request:
+
+```bash
+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"
+  }'
+```
+
+The `audience` you request from the IdP **must match** the `audience` you
+configured on the middleware. Per-provider endpoints, parameter names, and
+gotchas (Entra v2 endpoint, Cognito Resource Servers, Keycloak audience
+mappers, Google's opaque-token quirk) are documented in
+[docs/BEARER_AUTH.md](docs/BEARER_AUTH.md#obtaining-bearer-tokens-from-your-oidc-provider).
+
+Full threat model, configuration matrix, and follow-up gaps in
+[docs/BEARER_AUTH.md](docs/BEARER_AUTH.md).
+
 ### SSE and WebSocket endpoints
 
 Browser clients cannot follow an OIDC `302` redirect on an SSE stream or a
@@ -324,6 +426,19 @@ namespaced claims, Cognito regions, GitLab self-hosted) live in
 
 Set `logLevel: debug` to surface detail.
 
+## Telemetry
+
+On first plugin instantiation this middleware sends a single anonymous
+adoption ping — project name, version, timestamp; no identifiers, no
+request data, no token contents. Fire-and-forget with a 2-second timeout;
+cannot block plugin load or panic.
+
+Local source: [`telemetry.go`](./telemetry.go). Disclosure mirrors
+**[oss-telemetry — Disabling telemetry](https://github.com/lukaszraczylo/oss-telemetry#disabling-telemetry)**.
+
+Quick opt-out: set any of `DO_NOT_TRACK=1`, `OSS_TELEMETRY_DISABLED=1`,
+or `TRAEFIKOIDC_DISABLE_TELEMETRY=1`.
+
 ## License
 
 See [LICENSE](LICENSE).

audience_test.go

@@ -484,7 +484,8 @@ func TestAuth0Scenario3OpaqueAccessToken(t *testing.T) {
 	session.SetAccessToken(opaqueAccessToken)
 	session.SetIDToken(idToken)
 
-	authenticated, needsRefresh, expired := ts.tOidc.validateStandardTokens(session)
+	rs := (&requestState{}).captureSession(session)
+	authenticated, needsRefresh, expired := ts.tOidc.validateStandardTokensRS(rs)
 	if !authenticated || needsRefresh || expired {
 		t.Errorf("Session with opaque access token and valid ID token should be authenticated. Got: auth=%v, refresh=%v, expired=%v",
 			authenticated, needsRefresh, expired)
@@ -623,7 +624,8 @@ func TestAuth0Scenario2StrictMode(t *testing.T) {
 	session.SetRefreshToken("test-refresh-token") // Add refresh token so it can attempt refresh
 
 	// In strict mode, this should FAIL (no fallback to ID token)
-	authenticated, needsRefresh, expired := ts.tOidc.validateStandardTokens(session)
+	rs := (&requestState{}).captureSession(session)
+	authenticated, needsRefresh, expired := ts.tOidc.validateStandardTokensRS(rs)
 	if authenticated {
 		t.Errorf("Strict mode: Session with wrong access token audience should be rejected, but got authenticated=true")
 	}

auth_flow.go

@@ -182,6 +182,11 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 	}
 
 	codeVerifier := session.GetCodeVerifier()
+	if t.enablePKCE && codeVerifier == "" {
+		t.logger.Error("PKCE is enabled but code verifier is missing from session during callback")
+		t.sendErrorResponse(rw, req, "Authentication failed: PKCE verifier missing", http.StatusBadRequest)
+		return
+	}
 
 	tokenResponse, err := t.tokenExchanger.ExchangeCodeForToken(req.Context(), "authorization_code", code, redirectURL, codeVerifier)
 	if err != nil {
@@ -263,7 +268,10 @@ func (t *TraefikOidc) handleCallback(rw http.ResponseWriter, req *http.Request,
 
 	redirectPath := "/"
 	if incomingPath := session.GetIncomingPath(); incomingPath != "" && incomingPath != t.redirURLPath {
-		redirectPath = incomingPath
+		// Neutralize open-redirect payloads (e.g. //evil.com, /\evil.com) stored
+		// from the original request target before using it as the post-login
+		// redirect target. normalizeLogoutPath forces a host-relative path.
+		redirectPath = normalizeLogoutPath(incomingPath)
 	}
 	session.SetIncomingPath("")
 
@@ -305,28 +313,6 @@ func (t *TraefikOidc) handleExpiredToken(rw http.ResponseWriter, req *http.Reque
 	t.defaultInitiateAuthentication(rw, req, session, redirectURL)
 }
 
-// isUserAuthenticated determines the authentication status and refresh requirements.
-// It delegates to provider-specific validation methods that handle different token types
-// and expiration behaviors.
-// Parameters:
-//   - session: The session data containing authentication tokens.
-//
-// Returns:
-//   - authenticated (bool): True if the user has valid tokens.
-//   - needsRefresh (bool): True if tokens are valid but nearing expiration.
-//   - expired (bool): True if the session is unauthenticated, the token is missing,
-//     or the token verification failed for reasons other than nearing/actual expiration.
-func (t *TraefikOidc) isUserAuthenticated(session *SessionData) (bool, bool, bool) {
-	if t.isAzureProvider() {
-		return t.validateAzureTokens(session)
-	} else if t.isGoogleProvider() {
-		return t.validateGoogleTokens(session)
-	}
-	// Auth0 and other providers can now use standard validation
-	// which handles opaque tokens generically
-	return t.validateStandardTokens(session)
-}
-
 // isAjaxRequest determines if this is an AJAX request that should receive 401 instead of redirect
 func (t *TraefikOidc) isAjaxRequest(req *http.Request) bool {
 	xhr := req.Header.Get("X-Requested-With")

azure_oidc_test.go

@@ -262,7 +262,8 @@ func TestAzureOIDCRegression(t *testing.T) {
 		defer func() { tOidc.tokenVerifier = originalTokenVerifier }()
 
 		// Test that CSRF is preserved during Azure validation failures
-		authenticated, needsRefresh, expired := tOidc.validateAzureTokens(session)
+		rs := (&requestState{}).captureSession(session)
+		authenticated, needsRefresh, expired := tOidc.validateAzureTokensRS(rs)
 
 		// Should not be authenticated due to validation failure
 		if authenticated {
@@ -453,7 +454,8 @@ func TestValidateGoogleTokens(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			session := tt.setupSession()
 
-			auth, refresh, expired := ts.tOidc.validateGoogleTokens(session)
+			rs := (&requestState{}).captureSession(session)
+			auth, refresh, expired := ts.tOidc.validateGoogleTokensRS(rs)
 
 			if auth != tt.expectedAuth {
 				t.Errorf("Expected authenticated=%v, got %v. %s", tt.expectedAuth, auth, tt.description)
@@ -637,7 +639,8 @@ func TestIsUserAuthenticated(t *testing.T) {
 			defer func() { ts.tOidc.issuerURL = originalIssuer }()
 
 			session := tt.setupSession()
-			auth, refresh, expired := ts.tOidc.isUserAuthenticated(session)
+			rs := (&requestState{}).captureSession(session)
+			auth, refresh, expired := ts.tOidc.isUserAuthenticatedRS(rs)
 
 			if auth != tt.expectedAuth {
 				t.Errorf("Expected authenticated=%v, got %v. %s", tt.expectedAuth, auth, tt.description)
@@ -762,7 +765,8 @@ func TestValidateAzureTokensEdgeCases(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			session := tt.setupSession()
 
-			auth, refresh, expired := ts.tOidc.validateAzureTokens(session)
+			rs := (&requestState{}).captureSession(session)
+			auth, refresh, expired := ts.tOidc.validateAzureTokensRS(rs)
 
 			if auth != tt.expectedAuth {
 				t.Errorf("Expected authenticated=%v, got %v. %s", tt.expectedAuth, auth, tt.description)

bearer_auth.go

@@ -0,0 +1,683 @@
+// 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
+}
+
+// headerClaimRuneReason reports why a rune is unsafe to inject into a request
+// header value, or "" if the rune is acceptable. Shared core of the bearer-path
+// identifier sanitizer and the cookie-path header claim sanitizer: rejects
+// control chars (CRLF/header injection), Unicode bidi-override runes (RTL
+// spoofing of admin UI / SIEM), and the delimiters , ; = (a comma in a group
+// name would inject extra entries into a comma-joined header).
+func headerClaimRuneReason(r rune) string {
+	if reason := headerInjectionRuneReason(r); reason != "" {
+		return reason
+	}
+	// The , ; = delimiters are only unsafe for values placed into delimited or
+	// list contexts (a comma-joined header, or an identifier downstreams may
+	// split). They are valid in arbitrary single header values, so this stricter
+	// check is used for the cookie-path identifier and the group/role list, NOT
+	// for free-form templated header output (see headerValueReason).
+	if r == ',' || r == ';' || r == '=' {
+		return "delimiter character"
+	}
+	return ""
+}
+
+// headerInjectionRuneReason reports why a rune is unsafe in ANY HTTP header
+// value, or "" if acceptable. Rejects control characters (CR/LF header
+// injection) and Unicode bidi-override runes (RTL spoofing of admin UIs/SIEMs).
+// Unlike headerClaimRuneReason it does NOT reject , ; = which are legitimate in
+// free-form header values (e.g. an opaque "Authorization: Bearer <token>").
+func headerInjectionRuneReason(r rune) string {
+	if unicode.IsControl(r) {
+		return "control character"
+	}
+	if (r >= 0x202A && r <= 0x202E) || (r >= 0x2066 && r <= 0x2069) {
+		return "bidi-override character"
+	}
+	return ""
+}
+
+// headerValueReason reports why value is unsafe to forward as a free-form HTTP
+// header value, or "" if acceptable. It rejects values over maxLen (maxLen<=0
+// disables the check) and values containing control or bidi-override runes, but
+// permits , ; = (valid in header values). Empty is allowed. The reason string
+// never includes the value, so it is safe to log.
+func headerValueReason(value string, maxLen int) string {
+	if maxLen > 0 && len(value) > maxLen {
+		return "exceeds max length"
+	}
+	for _, r := range value {
+		if reason := headerInjectionRuneReason(r); reason != "" {
+			return reason
+		}
+	}
+	return ""
+}
+
+// headerClaimValueReason reports why value is unsafe to inject into a
+// downstream request header, or "" if it is acceptable. It rejects empty
+// values, values exceeding maxLen (maxLen<=0 disables the length check), and
+// values containing any rune rejected by headerClaimRuneReason. The reason
+// string is safe to log (it never includes the value itself).
+func headerClaimValueReason(value string, maxLen int) string {
+	if value == "" {
+		return "empty value"
+	}
+	if maxLen > 0 && len(value) > maxLen {
+		return "exceeds max length"
+	}
+	for _, r := range value {
+		if reason := headerClaimRuneReason(r); reason != "" {
+			return reason
+		}
+	}
+	return ""
+}
+
+// sanitizeHeaderClaimValue validates a claim-derived value before it is
+// injected into a downstream request header. It trims surrounding whitespace
+// and fails closed (ok=false) on empty values, values exceeding maxLen
+// (maxLen<=0 disables the length check), or values containing any rune rejected
+// by headerClaimRuneReason. Used by the cookie/session path, which — unlike the
+// bearer path — does not otherwise sanitize the principal identifier or the
+// group/role strings joined into X-User-Groups / X-User-Roles.
+func sanitizeHeaderClaimValue(raw string, maxLen int) (string, bool) {
+	value := strings.TrimSpace(raw)
+	if headerClaimValueReason(value, maxLen) != "" {
+		return "", false
+	}
+	return value, true
+}
+
+// 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 reason := headerClaimRuneReason(r); reason != "" {
+			return "", newBearerError(bearerErrInvalidIdentifier, "identifier contains "+reason)
+		}
+	}
+	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()
+	e, ok := b.entries[ip]
+	if !ok {
+		return
+	}
+	// Preserve an active penalty so a single success cannot wipe an in-effect
+	// lockout; only reset the counter when no penalty is active or it has expired.
+	now := time.Now()
+	if e.penaltyUntil.IsZero() || now.After(e.penaltyUntil) {
+		e.count = 0
+		e.firstFailureAt = now
+	}
+}
+
+// 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,830 @@
+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)
+	}
+	// A success while a penalty is active must NOT wipe the in-effect lockout
+	// (otherwise a single success could clear an attacker's penalty).
+	tr.recordSuccess(ip)
+	if b, _ := tr.blocked(ip); !b {
+		t.Fatalf("expected still blocked after success while penalty active")
+	}
+	// Other IPs are unaffected.
+	if b, _ := tr.blocked("10.0.0.2"); b {
+		t.Fatalf("unrelated IP should not be blocked")
+	}
+
+	// With an expired penalty, a success resets the counter so a subsequent
+	// sub-threshold failure does not immediately re-block.
+	tr2 := newBearerFailureTracker(3, 60*time.Second, 1*time.Millisecond)
+	const ip2 = "10.0.0.3"
+	for i := 0; i < 3; i++ {
+		tr2.recordFailure(ip2)
+	}
+	time.Sleep(5 * time.Millisecond) // let the short penalty expire
+	if b, _ := tr2.blocked(ip2); b {
+		t.Fatalf("expected unblocked after penalty expiry")
+	}
+	tr2.recordSuccess(ip2) // resets count since penalty has passed
+	tr2.recordFailure(ip2) // single failure, well below threshold
+	if b, _ := tr2.blocked(ip2); b {
+		t.Fatalf("expected unblocked: counter should have reset after success")
+	}
+}
+
+// =============================================================================
+// 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")
+	}
+}

cache_manager.go

@@ -16,8 +16,9 @@ type CacheManager struct {
 }
 
 var (
-	globalCacheManagerInstance *CacheManager
-	cacheManagerInitOnce       sync.Once
+	globalCacheManagerInstance    *CacheManager
+	cacheManagerInitOnce          sync.Once
+	cacheManagerActiveFingerprint string
 )
 
 // GetGlobalCacheManager returns a singleton CacheManager instance.
@@ -29,7 +30,9 @@ func GetGlobalCacheManager(wg *sync.WaitGroup) *CacheManager {
 
 // GetGlobalCacheManagerWithConfig returns a singleton CacheManager instance with optional Redis configuration
 func GetGlobalCacheManagerWithConfig(wg *sync.WaitGroup, config *Config) *CacheManager {
+	fp := redisFingerprint(config)
 	cacheManagerInitOnce.Do(func() {
+		cacheManagerActiveFingerprint = fp
 		var redisConfig *RedisConfig
 		var logger *Logger
 
@@ -55,9 +58,27 @@ func GetGlobalCacheManagerWithConfig(wg *sync.WaitGroup, config *Config) *CacheM
 			manager: GetUniversalCacheManagerWithConfig(logger, redisConfig),
 		}
 	})
+	// Warn loudly if a later instance asks for a DIFFERENT explicit Redis
+	// backend than the one that won initialization: the cache manager is a
+	// process-global singleton shared across plugin instances (yaegi), so this
+	// instance's divergent configuration is silently ignored, which would
+	// otherwise collapse cache/state isolation between routes (rank 9).
+	if fp != "" && cacheManagerActiveFingerprint != "" && fp != cacheManagerActiveFingerprint {
+		NewLogger(config.LogLevel).Errorf("cache manager already initialized with Redis backend %q; this instance's Redis backend %q is IGNORED (process-global singleton). Use a single consistent cache configuration across all routes.", cacheManagerActiveFingerprint, fp)
+	}
 	return globalCacheManagerInstance
 }
 
+// redisFingerprint returns a stable identifier for an explicitly-enabled Redis
+// backend (address + key prefix), or "" when Redis is not explicitly enabled.
+// Used to detect divergent cache configurations across plugin instances.
+func redisFingerprint(config *Config) string {
+	if config == nil || config.Redis == nil || !config.Redis.Enabled {
+		return ""
+	}
+	return config.Redis.Address + "|" + config.Redis.KeyPrefix
+}
+
 // GetSharedTokenBlacklist returns the shared token blacklist cache
 func (cm *CacheManager) GetSharedTokenBlacklist() CacheInterface {
 	cm.mu.RLock()

cmd/yaegicheck/main.go

@@ -0,0 +1,46 @@
+//go:build ignore
+
+// Command yaegicheck verifies that the traefikoidc plugin can be imported and
+// instantiated by the yaegi interpreter — the same way Traefik loads a plugin.
+//
+// It is run by `make yaegi-validate`. Importing the plugin package forces yaegi
+// to interpret every source file in the package (and its vendored
+// dependencies), so any construct yaegi cannot handle (unsupported stdlib
+// symbol, reflection edge case, etc.) surfaces here rather than at Traefik load
+// time. CreateConfig + New additionally exercise the instantiation path
+// (session manager, cookie codec, caches, key derivation) under the interpreter.
+package main
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+
+	oidc "github.com/lukaszraczylo/traefikoidc"
+)
+
+func main() {
+	cfg := oidc.CreateConfig()
+	cfg.ProviderURL = "https://accounts.google.com"
+	cfg.ClientID = "yaegi-check-client"
+	cfg.ClientSecret = "yaegi-check-secret"
+	cfg.CallbackURL = "/oauth2/callback"
+	cfg.SessionEncryptionKey = "0123456789abcdef0123456789abcdef"
+	cfg.RateLimit = 100
+
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {})
+	h, err := oidc.New(context.Background(), next, cfg, "yaegi-check")
+	if err != nil {
+		fmt.Println("FAIL: New returned an error under yaegi:", err)
+		os.Exit(1)
+	}
+	if h == nil {
+		fmt.Println("FAIL: New returned a nil handler under yaegi")
+		os.Exit(1)
+	}
+	if closer, ok := h.(interface{ Close() error }); ok {
+		_ = closer.Close()
+	}
+	fmt.Println("OK: traefikoidc imported + CreateConfig + New succeeded under yaegi")
+}

coverage_boost_final_test.go

@@ -278,82 +278,6 @@ func TestHTTPClientProfiler_Methods_CoverageBoost(t *testing.T) {
 	}
 }
 
-// =============================================================================
-// SECURITY MONITORING TESTS
-// =============================================================================
-
-func TestSecurityMonitor_StopCleanupRoutine_CoverageBoost(t *testing.T) {
-	logger := NewLogger("info")
-	config := SecurityMonitorConfig{
-		MaxFailuresPerIP:       5,
-		FailureWindowMinutes:   15,
-		BlockDurationMinutes:   30,
-		RapidFailureThreshold:  3,
-		CleanupIntervalMinutes: 60,
-		RetentionHours:         24,
-		EnablePatternDetection: true,
-		EnableDetailedLogging:  false,
-		LogSuspiciousOnly:      false,
-	}
-
-	sm := NewSecurityMonitor(config, logger)
-	if sm == nil {
-		t.Fatal("Expected non-nil SecurityMonitor")
-	}
-
-	// Start cleanup routine first (lowercase method)
-	sm.startCleanupRoutine()
-
-	// Give it a moment to start
-	time.Sleep(50 * time.Millisecond)
-
-	// Stop cleanup routine (public method)
-	sm.StopCleanupRoutine()
-
-	// Stop again should be safe
-	sm.StopCleanupRoutine()
-}
-
-func TestSecurityMonitor_MultipleHandlers_CoverageBoost(t *testing.T) {
-	logger := NewLogger("info")
-	config := SecurityMonitorConfig{
-		MaxFailuresPerIP:       5,
-		FailureWindowMinutes:   15,
-		BlockDurationMinutes:   30,
-		RapidFailureThreshold:  3,
-		CleanupIntervalMinutes: 60,
-		RetentionHours:         24,
-	}
-
-	sm := NewSecurityMonitor(config, logger)
-
-	// Create handler
-	handler := &LoggingSecurityEventHandler{logger: logger}
-
-	// Register handler using AddEventHandler
-	sm.AddEventHandler(handler)
-
-	// Record a failure to trigger events
-	sm.RecordAuthenticationFailure("192.168.1.100", "test-agent", "/test", "test_failure", nil)
-}
-
-func TestLoggingSecurityEventHandler_HandleSecurityEvent_AllSeverities_CoverageBoost(t *testing.T) {
-	logger := NewLogger("debug")
-	handler := &LoggingSecurityEventHandler{logger: logger}
-
-	// Severity is a string in this implementation
-	events := []SecurityEvent{
-		{Type: "test", Severity: "low", Message: "low severity"},
-		{Type: "test", Severity: "medium", Message: "medium severity"},
-		{Type: "test", Severity: "high", Message: "high severity"},
-		{Type: "test", Severity: "critical", Message: "critical severity"},
-	}
-
-	for _, event := range events {
-		handler.HandleSecurityEvent(event)
-	}
-}
-
 // =============================================================================
 // SESSION MANAGER TESTS
 // =============================================================================

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

@@ -178,7 +178,7 @@ clientSecret: your-client-secret
 | `logLevel` | string | `info` | Logging verbosity (`debug`, `info`, `error`) |
 | `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 |
+| `excludedURLs` | []string | none | Paths that bypass authentication, matched at a path-segment or file-extension boundary |
 | `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 |
@@ -261,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

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

@@ -370,21 +370,6 @@ func (r *DynamicClientRegistrar) saveCredentialsToStore(ctx context.Context, res
 	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()
@@ -423,187 +408,3 @@ func (r *DynamicClientRegistrar) loadCredentials() (*ClientRegistrationResponse,
 
 	return &resp, nil
 }
-
-// UpdateClientRegistration updates an existing client registration using RFC 7592
-// This requires the registration_client_uri and registration_access_token from the original registration
-func (r *DynamicClientRegistrar) UpdateClientRegistration(ctx context.Context) (*ClientRegistrationResponse, error) {
-	r.mu.RLock()
-	cachedResp := r.registrationResponse
-	r.mu.RUnlock()
-
-	if cachedResp == nil {
-		return nil, fmt.Errorf("no existing registration to update")
-	}
-
-	if cachedResp.RegistrationClientURI == "" || cachedResp.RegistrationAccessToken == "" {
-		return nil, fmt.Errorf("registration management not supported: missing registration_client_uri or registration_access_token")
-	}
-
-	// Build update request
-	reqBody, err := r.buildRegistrationRequest()
-	if err != nil {
-		return nil, fmt.Errorf("failed to build update request: %w", err)
-	}
-
-	// Create HTTP request
-	req, err := http.NewRequestWithContext(ctx, http.MethodPut, cachedResp.RegistrationClientURI, bytes.NewReader(reqBody))
-	if err != nil {
-		return nil, fmt.Errorf("failed to create update request: %w", err)
-	}
-
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("Accept", "application/json")
-	req.Header.Set("Authorization", "Bearer "+cachedResp.RegistrationAccessToken)
-
-	// Execute request
-	resp, err := r.httpClient.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("update request failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	// Read response body
-	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
-	if err != nil {
-		return nil, fmt.Errorf("failed to read update response: %w", err)
-	}
-
-	// Handle error responses
-	if resp.StatusCode != http.StatusOK {
-		var regError ClientRegistrationError
-		if jsonErr := json.Unmarshal(body, &regError); jsonErr == nil && regError.Error != "" {
-			return nil, fmt.Errorf("update failed: %s - %s", regError.Error, regError.ErrorDescription)
-		}
-		return nil, fmt.Errorf("update failed with status %d: %s", resp.StatusCode, string(body))
-	}
-
-	// Parse successful response
-	var regResp ClientRegistrationResponse
-	if err := json.Unmarshal(body, &regResp); err != nil {
-		return nil, fmt.Errorf("failed to parse update response: %w", err)
-	}
-
-	// Update cache
-	r.mu.Lock()
-	r.registrationResponse = &regResp
-	r.mu.Unlock()
-
-	// Persist updated credentials if enabled
-	if r.config.PersistCredentials {
-		if err := r.saveCredentialsToStore(ctx, &regResp); err != nil {
-			r.logger.Errorf("Failed to persist updated credentials: %v", err)
-		}
-	}
-
-	r.logger.Infof("Successfully updated client registration for client ID: %s", regResp.ClientID)
-	return &regResp, nil
-}
-
-// ReadClientRegistration reads the current client registration using RFC 7592
-func (r *DynamicClientRegistrar) ReadClientRegistration(ctx context.Context) (*ClientRegistrationResponse, error) {
-	r.mu.RLock()
-	cachedResp := r.registrationResponse
-	r.mu.RUnlock()
-
-	if cachedResp == nil {
-		return nil, fmt.Errorf("no existing registration to read")
-	}
-
-	if cachedResp.RegistrationClientURI == "" || cachedResp.RegistrationAccessToken == "" {
-		return nil, fmt.Errorf("registration management not supported: missing registration_client_uri or registration_access_token")
-	}
-
-	// Create HTTP request
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, cachedResp.RegistrationClientURI, nil)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create read request: %w", err)
-	}
-
-	req.Header.Set("Accept", "application/json")
-	req.Header.Set("Authorization", "Bearer "+cachedResp.RegistrationAccessToken)
-
-	// Execute request
-	resp, err := r.httpClient.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("read request failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	// Read response body
-	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
-	if err != nil {
-		return nil, fmt.Errorf("failed to read response: %w", err)
-	}
-
-	// Handle error responses
-	if resp.StatusCode != http.StatusOK {
-		var regError ClientRegistrationError
-		if jsonErr := json.Unmarshal(body, &regError); jsonErr == nil && regError.Error != "" {
-			return nil, fmt.Errorf("read failed: %s - %s", regError.Error, regError.ErrorDescription)
-		}
-		return nil, fmt.Errorf("read failed with status %d: %s", resp.StatusCode, string(body))
-	}
-
-	// Parse successful response
-	var regResp ClientRegistrationResponse
-	if err := json.Unmarshal(body, &regResp); err != nil {
-		return nil, fmt.Errorf("failed to parse read response: %w", err)
-	}
-
-	return &regResp, nil
-}
-
-// DeleteClientRegistration deletes the client registration using RFC 7592
-func (r *DynamicClientRegistrar) DeleteClientRegistration(ctx context.Context) error {
-	r.mu.RLock()
-	cachedResp := r.registrationResponse
-	r.mu.RUnlock()
-
-	if cachedResp == nil {
-		return fmt.Errorf("no existing registration to delete")
-	}
-
-	if cachedResp.RegistrationClientURI == "" || cachedResp.RegistrationAccessToken == "" {
-		return fmt.Errorf("registration management not supported: missing registration_client_uri or registration_access_token")
-	}
-
-	// Create HTTP request
-	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, cachedResp.RegistrationClientURI, nil)
-	if err != nil {
-		return fmt.Errorf("failed to create delete request: %w", err)
-	}
-
-	req.Header.Set("Authorization", "Bearer "+cachedResp.RegistrationAccessToken)
-
-	// Execute request
-	resp, err := r.httpClient.Do(req)
-	if err != nil {
-		return fmt.Errorf("delete request failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	// Handle error responses (204 No Content is success)
-	if resp.StatusCode != http.StatusNoContent && resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
-		var regError ClientRegistrationError
-		if jsonErr := json.Unmarshal(body, &regError); jsonErr == nil && regError.Error != "" {
-			return fmt.Errorf("delete failed: %s - %s", regError.Error, regError.ErrorDescription)
-		}
-		return fmt.Errorf("delete failed with status %d: %s", resp.StatusCode, string(body))
-	}
-
-	// Clear cache
-	r.mu.Lock()
-	r.registrationResponse = nil
-	r.mu.Unlock()
-
-	// Remove credentials from storage if persistence is enabled
-	if r.config.PersistCredentials {
-		if err := r.deleteCredentialsFromStore(ctx); err != nil {
-			r.logger.Errorf("Failed to remove credentials from storage: %v", err)
-		}
-	}
-
-	r.logger.Info("Successfully deleted client registration")
-	return nil
-}

dynamic_client_registration_test.go

@@ -735,258 +735,6 @@ func TestDCRConfigDefaults(t *testing.T) {
 	}
 }
 
-// TestUpdateClientRegistration tests the RFC 7592 client update functionality
-func TestUpdateClientRegistration(t *testing.T) {
-	updateCalled := false
-
-	server := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Method == http.MethodPut {
-			updateCalled = true
-
-			// Verify authorization header
-			if r.Header.Get("Authorization") == "" {
-				t.Error("Missing Authorization header for update")
-			}
-
-			resp := ClientRegistrationResponse{
-				ClientID:                "updated-client-id",
-				ClientSecret:            "updated-client-secret",
-				RegistrationAccessToken: "new-access-token",
-				RegistrationClientURI:   r.URL.String(),
-			}
-			w.Header().Set("Content-Type", "application/json")
-			w.WriteHeader(http.StatusOK)
-			json.NewEncoder(w).Encode(resp)
-		}
-	}))
-	defer server.Close()
-
-	dcrConfig := &DynamicClientRegistrationConfig{
-		Enabled: true,
-		ClientMetadata: &ClientRegistrationMetadata{
-			RedirectURIs: []string{"https://example.com/callback"},
-		},
-	}
-
-	registrar := NewDynamicClientRegistrar(
-		server.Client(),
-		NewLogger("DEBUG"),
-		dcrConfig,
-		server.URL,
-	)
-
-	// Set up cached response with management credentials
-	registrar.mu.Lock()
-	registrar.registrationResponse = &ClientRegistrationResponse{
-		ClientID:                "original-client-id",
-		ClientSecret:            "original-client-secret",
-		RegistrationAccessToken: "access-token",
-		RegistrationClientURI:   server.URL + "/register/client123",
-	}
-	registrar.mu.Unlock()
-
-	// Perform update
-	ctx := context.Background()
-	resp, err := registrar.UpdateClientRegistration(ctx)
-
-	if err != nil {
-		t.Fatalf("Update failed: %v", err)
-	}
-
-	if !updateCalled {
-		t.Error("Update endpoint was not called")
-	}
-
-	if resp.ClientID != "updated-client-id" {
-		t.Errorf("Updated ClientID mismatch: got %s", resp.ClientID)
-	}
-}
-
-// TestDeleteClientRegistration tests the RFC 7592 client deletion functionality
-func TestDeleteClientRegistration(t *testing.T) {
-	deleteCalled := false
-
-	server := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Method == http.MethodDelete {
-			deleteCalled = true
-			w.WriteHeader(http.StatusNoContent)
-		}
-	}))
-	defer server.Close()
-
-	tempDir := t.TempDir()
-	credentialsFile := filepath.Join(tempDir, "credentials.json")
-
-	// Create a credentials file to test deletion
-	os.WriteFile(credentialsFile, []byte(`{"client_id":"test"}`), 0600)
-
-	dcrConfig := &DynamicClientRegistrationConfig{
-		Enabled:            true,
-		PersistCredentials: true,
-		CredentialsFile:    credentialsFile,
-	}
-
-	registrar := NewDynamicClientRegistrar(
-		server.Client(),
-		NewLogger("DEBUG"),
-		dcrConfig,
-		server.URL,
-	)
-
-	// Set up cached response with management credentials
-	registrar.mu.Lock()
-	registrar.registrationResponse = &ClientRegistrationResponse{
-		ClientID:                "test-client-id",
-		RegistrationAccessToken: "access-token",
-		RegistrationClientURI:   server.URL + "/register/client123",
-	}
-	registrar.mu.Unlock()
-
-	// Perform delete
-	ctx := context.Background()
-	err := registrar.DeleteClientRegistration(ctx)
-
-	if err != nil {
-		t.Fatalf("Delete failed: %v", err)
-	}
-
-	if !deleteCalled {
-		t.Error("Delete endpoint was not called")
-	}
-
-	// Verify cache is cleared
-	if registrar.GetCachedResponse() != nil {
-		t.Error("Cached response should be cleared after deletion")
-	}
-
-	// Verify credentials file is deleted
-	if _, err := os.Stat(credentialsFile); !os.IsNotExist(err) {
-		t.Error("Credentials file should be deleted")
-	}
-}
-
-// TestReadClientRegistration tests the RFC 7592 client read functionality
-func TestReadClientRegistration(t *testing.T) {
-	server := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Method == http.MethodGet {
-			resp := ClientRegistrationResponse{
-				ClientID:        "read-client-id",
-				ClientSecret:    "read-client-secret",
-				RedirectURIs:    []string{"https://example.com/callback"},
-				ResponseTypes:   []string{"code"},
-				GrantTypes:      []string{"authorization_code"},
-				ApplicationType: "web",
-			}
-			w.Header().Set("Content-Type", "application/json")
-			w.WriteHeader(http.StatusOK)
-			json.NewEncoder(w).Encode(resp)
-		}
-	}))
-	defer server.Close()
-
-	dcrConfig := &DynamicClientRegistrationConfig{Enabled: true}
-
-	registrar := NewDynamicClientRegistrar(
-		server.Client(),
-		NewLogger("DEBUG"),
-		dcrConfig,
-		server.URL,
-	)
-
-	// Set up cached response with management credentials
-	registrar.mu.Lock()
-	registrar.registrationResponse = &ClientRegistrationResponse{
-		ClientID:                "original-client-id",
-		RegistrationAccessToken: "access-token",
-		RegistrationClientURI:   server.URL + "/register/client123",
-	}
-	registrar.mu.Unlock()
-
-	// Read registration
-	ctx := context.Background()
-	resp, err := registrar.ReadClientRegistration(ctx)
-
-	if err != nil {
-		t.Fatalf("Read failed: %v", err)
-	}
-
-	if resp.ClientID != "read-client-id" {
-		t.Errorf("Read ClientID mismatch: got %s", resp.ClientID)
-	}
-}
-
-// TestOperationsWithoutCachedResponse tests error handling when no cached response exists
-func TestOperationsWithoutCachedResponse(t *testing.T) {
-	dcrConfig := &DynamicClientRegistrationConfig{Enabled: true}
-
-	registrar := NewDynamicClientRegistrar(
-		&http.Client{},
-		NewLogger("DEBUG"),
-		dcrConfig,
-		"https://example.com",
-	)
-
-	ctx := context.Background()
-
-	// Test Update without cached response
-	_, err := registrar.UpdateClientRegistration(ctx)
-	if err == nil || !stringContains(err.Error(), "no existing registration") {
-		t.Errorf("Update should fail without cached response: %v", err)
-	}
-
-	// Test Read without cached response
-	_, err = registrar.ReadClientRegistration(ctx)
-	if err == nil || !stringContains(err.Error(), "no existing registration") {
-		t.Errorf("Read should fail without cached response: %v", err)
-	}
-
-	// Test Delete without cached response
-	err = registrar.DeleteClientRegistration(ctx)
-	if err == nil || !stringContains(err.Error(), "no existing registration") {
-		t.Errorf("Delete should fail without cached response: %v", err)
-	}
-}
-
-// TestOperationsWithoutManagementCredentials tests error handling without management URIs
-func TestOperationsWithoutManagementCredentials(t *testing.T) {
-	dcrConfig := &DynamicClientRegistrationConfig{Enabled: true}
-
-	registrar := NewDynamicClientRegistrar(
-		&http.Client{},
-		NewLogger("DEBUG"),
-		dcrConfig,
-		"https://example.com",
-	)
-
-	// Set up cached response WITHOUT management credentials
-	registrar.mu.Lock()
-	registrar.registrationResponse = &ClientRegistrationResponse{
-		ClientID: "test-client-id",
-		// Missing RegistrationAccessToken and RegistrationClientURI
-	}
-	registrar.mu.Unlock()
-
-	ctx := context.Background()
-
-	// Test Update without management credentials
-	_, err := registrar.UpdateClientRegistration(ctx)
-	if err == nil || !stringContains(err.Error(), "registration management not supported") {
-		t.Errorf("Update should fail without management credentials: %v", err)
-	}
-
-	// Test Read without management credentials
-	_, err = registrar.ReadClientRegistration(ctx)
-	if err == nil || !stringContains(err.Error(), "registration management not supported") {
-		t.Errorf("Read should fail without management credentials: %v", err)
-	}
-
-	// Test Delete without management credentials
-	err = registrar.DeleteClientRegistration(ctx)
-	if err == nil || !stringContains(err.Error(), "registration management not supported") {
-		t.Errorf("Delete should fail without management credentials: %v", err)
-	}
-}
-
 // stringContains is a helper function to check if a string contains a substring
 func stringContains(s, substr string) bool {
 	return len(s) >= len(substr) && (s == substr || len(s) > 0 && stringContainsHelper(s, substr))

error_recovery.go

@@ -539,10 +539,10 @@ func (re *RetryExecutor) isRetryableError(err error) bool {
 		return true
 	}
 
-	errStr := err.Error()
+	errStr := strings.ToLower(err.Error())
 
 	for _, retryableErr := range re.config.RetryableErrors {
-		if contains(errStr, retryableErr) {
+		if contains(errStr, strings.ToLower(retryableErr)) {
 			return true
 		}
 	}
@@ -551,7 +551,7 @@ func (re *RetryExecutor) isRetryableError(err error) bool {
 		if netErr.Timeout() {
 			return true
 		}
-		errStr := netErr.Error()
+		errStr := strings.ToLower(netErr.Error())
 		temporaryPatterns := []string{
 			"connection refused",
 			"connection reset",
@@ -859,8 +859,9 @@ func (gd *GracefulDegradation) ExecuteWithFallback(serviceName string, primary f
 
 // isServiceDegraded checks if a service is currently degraded
 func (gd *GracefulDegradation) isServiceDegraded(serviceName string) bool {
-	gd.mutex.RLock()
-	defer gd.mutex.RUnlock()
+	// Uses a write lock because the recovery-timeout branch deletes from the map.
+	gd.mutex.Lock()
+	defer gd.mutex.Unlock()
 
 	degradedTime, exists := gd.degradedServices[serviceName]
 	if !exists {

go.mod

@@ -5,6 +5,7 @@ go 1.24.0
 require (
 	github.com/alicebob/miniredis/v2 v2.35.0
 	github.com/gorilla/sessions v1.3.0
+	github.com/lukaszraczylo/oss-telemetry v0.2.3
 	github.com/redis/go-redis/v9 v9.17.2
 	github.com/stretchr/testify v1.10.0
 	golang.org/x/time v0.14.0

go.sum

@@ -16,6 +16,8 @@ github.com/gorilla/securecookie v1.1.2 h1:YCIWL56dvtr73r6715mJs5ZvhtnY73hBvEF8kX
 github.com/gorilla/securecookie v1.1.2/go.mod h1:NfCASbcHqRSY+3a8tlWJwsQap2VX5pwzwo4h3eOamfo=
 github.com/gorilla/sessions v1.3.0 h1:XYlkq7KcpOB2ZhHBPv5WpjMIxrQosiZanfoy1HLZFzg=
 github.com/gorilla/sessions v1.3.0/go.mod h1:ePLdVu+jbEgHH+KWw8I1z2wqd0BAdAQh/8LRvBeoNcQ=
+github.com/lukaszraczylo/oss-telemetry v0.2.3 h1:xoDtBqeZGmXj7IteiE1M5WMuzeoqag58qEleI0Cf2Ms=
+github.com/lukaszraczylo/oss-telemetry v0.2.3/go.mod h1:+Cn78qZo8rc3T9eZt0v3oICYRdd75wORtSidc8lNjDQ=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/redis/go-redis/v9 v9.17.2 h1:P2EGsA4qVIM3Pp+aPocCJ7DguDHhqrXNhVcEp4ViluI=

helpers.go

@@ -392,10 +392,19 @@ func (t *TraefikOidc) handleLogout(rw http.ResponseWriter, req *http.Request) {
 	baseURL := fmt.Sprintf("%s://%s", scheme, host)
 
 	postLogoutRedirectURI := t.postLogoutRedirectURI
+	// localRedirect is used when there is no provider end-session endpoint and
+	// the plugin redirects the browser itself. It must never be an absolute URL
+	// derived from the request host (X-Forwarded-Host is client-controllable and
+	// would be an open redirect); use a host-relative path, or the operator's
+	// own configured absolute URL, instead.
+	localRedirect := "/"
 	if postLogoutRedirectURI == "" {
 		postLogoutRedirectURI = fmt.Sprintf("%s/", baseURL)
 	} else if !strings.HasPrefix(postLogoutRedirectURI, "http") {
+		localRedirect = normalizeLogoutPath(postLogoutRedirectURI)
 		postLogoutRedirectURI = fmt.Sprintf("%s%s", baseURL, postLogoutRedirectURI)
+	} else {
+		localRedirect = postLogoutRedirectURI
 	}
 
 	// Read endSessionURL with RLock
@@ -414,7 +423,7 @@ func (t *TraefikOidc) handleLogout(rw http.ResponseWriter, req *http.Request) {
 		return
 	}
 
-	http.Redirect(rw, req, postLogoutRedirectURI, http.StatusFound)
+	http.Redirect(rw, req, localRedirect, http.StatusFound)
 }
 
 // BuildLogoutURL constructs a logout URL for the OIDC provider's end session endpoint.

http_client_pool.go

@@ -26,6 +26,10 @@ type sharedTransport struct {
 	lastUsed  time.Time
 	transport *http.Transport
 	refCount  int
+	// tlsKey identifies the TLS trust settings (CA pool + InsecureSkipVerify)
+	// this transport was built with, so the at-limit fallback only reuses a
+	// transport whose TLS configuration matches the caller's.
+	tlsKey string
 }
 
 var (
@@ -53,19 +57,26 @@ func GetGlobalTransportPool() *SharedTransportPool {
 
 // GetOrCreateTransport gets or creates a shared transport with the given config
 func (p *SharedTransportPool) GetOrCreateTransport(config HTTPClientConfig) *http.Transport {
-	// SECURITY FIX: Check client limit before creating new transport
+	// SECURITY FIX: Check client limit before creating new transport.
 	if atomic.LoadInt32(&p.clientCount) >= p.maxClients {
-		// Return existing transport if limit reached
-		p.mu.RLock()
-		defer p.mu.RUnlock()
+		// At the client limit: only reuse a transport that was built for the
+		// SAME config (same TLS trust store). refCount is mutated under the
+		// write lock to avoid a data race, and a transport created for a
+		// different configuration is never handed back — doing so could apply
+		// the wrong (possibly verification-disabled) TLS settings to a request.
+		want := tlsConfigKey(config)
+		p.mu.Lock()
+		defer p.mu.Unlock()
 		for _, shared := range p.transports {
-			if shared != nil && shared.transport != nil {
+			if shared != nil && shared.transport != nil && shared.tlsKey == want {
 				shared.refCount++
 				shared.lastUsed = time.Now()
 				return shared.transport
 			}
 		}
-		// If no transport available, return nil (caller should handle)
+		// No TLS-compatible transport available; return nil so the caller falls
+		// back to a default, certificate-verifying transport rather than one
+		// with a different (possibly verification-disabled) trust store.
 		return nil
 	}
 
@@ -125,6 +136,7 @@ func (p *SharedTransportPool) GetOrCreateTransport(config HTTPClientConfig) *htt
 		transport: transport,
 		refCount:  1,
 		lastUsed:  time.Now(),
+		tlsKey:    tlsConfigKey(config),
 	}
 
 	return transport
@@ -224,6 +236,18 @@ func (p *SharedTransportPool) configKey(config HTTPClientConfig) string {
 	)
 }
 
+// tlsConfigKey identifies only the TLS trust settings of a config — the CA pool
+// and the InsecureSkipVerify flag. Two configs with the same tlsConfigKey are
+// safe to serve from the same transport even if other (non-TLS) parameters such
+// as connection limits differ; configs with different TLS settings are not.
+func tlsConfigKey(config HTTPClientConfig) string {
+	skip := "0"
+	if config.InsecureSkipVerify {
+		skip = "1"
+	}
+	return fmt.Sprintf("%p|%s", config.RootCAs, skip)
+}
+
 // Cleanup closes all transports and stops the cleanup goroutine
 func (p *SharedTransportPool) Cleanup() {
 	p.mu.Lock()

internal/cache/backends/hybrid.go

@@ -164,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
 	}
 
@@ -176,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 {
@@ -192,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)
 		}
 	}
@@ -209,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 {
@@ -227,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
@@ -544,7 +544,7 @@ func (h *HybridBackend) queueL1Backfill(key string, value []byte, ttl time.Durat
 	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", key)
+		h.logger.Debugf("L1 backfill buffer full, dropping for key: %s", redactKey(key))
 	}
 }
 
@@ -576,9 +576,9 @@ func (h *HybridBackend) l1BackfillWorker() {
 			}
 			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", item.key, err)
+				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", item.key)
+				h.logger.Debugf("Populated L1 cache from L2 for key: %s", redactKey(item.key))
 			}
 			cancel()
 		}
@@ -619,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/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/cache.go

@@ -190,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
 }
 
@@ -346,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/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/cleanup/cleanup_test.go

@@ -842,10 +842,18 @@ func TestWorkerPool_TaskPanic(t *testing.T) {
 		t.Error("Timeout waiting for tasks")
 	}
 
-	// Pool should still be functional
-	metrics := pool.GetMetrics()
-	if metrics["tasksFailed"].(int64) < 1 {
-		t.Error("Expected at least one failed task")
+	// tasksFailed is incremented in the worker's deferred recover(), which runs
+	// AFTER the panicking task's own `defer wg.Done()`. wg.Wait() above can
+	// therefore return before the failure is recorded — reading the counter
+	// immediately is a race that flakes on slow/contended CI runners. Poll until
+	// the failure lands (or time out).
+	deadline := time.Now().Add(2 * time.Second)
+	for pool.GetMetrics()["tasksFailed"].(int64) < 1 {
+		if time.Now().After(deadline) {
+			t.Error("Expected at least one failed task")
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
 	}
 }
 

internal/utils/utils.go

@@ -155,12 +155,34 @@ func DetermineScheme(req *http.Request, forceHTTPS bool) string {
 // It checks X-Forwarded-Host header first (for proxy scenarios),
 // then falls back to req.Host.
 func DetermineHost(req *http.Request) string {
-	if host := req.Header.Get("X-Forwarded-Host"); host != "" {
+	if host := sanitizeForwardedHost(req.Header.Get("X-Forwarded-Host")); host != "" {
 		return host
 	}
 	return req.Host
 }
 
+// sanitizeForwardedHost returns a single, well-formed host from a (possibly
+// comma-separated) X-Forwarded-Host header, or "" if none is usable. It takes
+// only the first value and rejects whitespace and control characters, so a
+// crafted header cannot inject CRLF, smuggle a second host, or otherwise poison
+// the redirect URLs built from the result.
+func sanitizeForwardedHost(v string) string {
+	if v == "" {
+		return ""
+	}
+	if i := strings.IndexByte(v, ','); i >= 0 {
+		v = v[:i]
+	}
+	v = strings.TrimSpace(v)
+	if v == "" {
+		return ""
+	}
+	if strings.IndexFunc(v, func(r rune) bool { return r < 0x20 || r == 0x7f || r == ' ' }) >= 0 {
+		return ""
+	}
+	return v
+}
+
 // BuildFullURL constructs a URL from scheme, host, and path components.
 // It handles absolute URLs (returning them as-is) and ensures paths have leading slashes.
 func BuildFullURL(scheme, host, path string) string {

issue134_followup_graph_test.go

@@ -0,0 +1,453 @@
+package traefikoidc
+
+import (
+	"bytes"
+	"crypto"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"math/big"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gorilla/sessions"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/time/rate"
+)
+
+// signGraphStyleAccessToken builds a JWT in Microsoft's Graph proprietary
+// nonce-header form: bytes that get signed contain the SHA256 hash of the
+// nonce, while the wire token ships the original nonce. A standard JWS
+// verifier always rejects these with `crypto/rsa: verification error`, which
+// is why Microsoft documents Graph access tokens as opaque to client apps:
+//
+//	https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens
+//	"you can't validate tokens for Microsoft Graph according to these rules
+//	 due to their proprietary format"
+func signGraphStyleAccessToken(t *testing.T, key *rsa.PrivateKey, kid, originalNonce string, claims map[string]any) string {
+	t.Helper()
+
+	wireHeader := map[string]any{
+		"alg":   "RS256",
+		"kid":   kid,
+		"typ":   "JWT",
+		"nonce": originalNonce,
+	}
+	wireHeaderJSON, err := json.Marshal(wireHeader)
+	require.NoError(t, err)
+
+	hashed := sha256.Sum256([]byte(originalNonce))
+	signedHeader := map[string]any{
+		"alg":   "RS256",
+		"kid":   kid,
+		"typ":   "JWT",
+		"nonce": fmt.Sprintf("%x", hashed),
+	}
+	signedHeaderJSON, err := json.Marshal(signedHeader)
+	require.NoError(t, err)
+
+	claimsJSON, err := json.Marshal(claims)
+	require.NoError(t, err)
+
+	wireHeaderB64 := base64.RawURLEncoding.EncodeToString(wireHeaderJSON)
+	signedHeaderB64 := base64.RawURLEncoding.EncodeToString(signedHeaderJSON)
+	claimsB64 := base64.RawURLEncoding.EncodeToString(claimsJSON)
+
+	signedInput := signedHeaderB64 + "." + claimsB64
+	hSign := sha256.Sum256([]byte(signedInput))
+	sig, err := rsa.SignPKCS1v15(rand.Reader, key, crypto.SHA256, hSign[:])
+	require.NoError(t, err)
+
+	return wireHeaderB64 + "." + claimsB64 + "." + base64.RawURLEncoding.EncodeToString(sig)
+}
+
+// newAzureFollowupOIDC produces a TraefikOidc instance wired for an Azure
+// AD tenant with a captured error log buffer. Used by the issue #134 followup
+// tests to assert log behavior during validateAzureTokens flows.
+func newAzureFollowupOIDC(t *testing.T, jwks *JWKSet) (*TraefikOidc, *bytes.Buffer) {
+	t.Helper()
+	tc := newTestCleanup(t)
+
+	errBuf := &bytes.Buffer{}
+	logger := &Logger{
+		logError: log.New(errBuf, "", 0),
+		logInfo:  log.New(io.Discard, "", 0),
+		logDebug: log.New(io.Discard, "", 0),
+	}
+
+	tokenCache := tc.addTokenCache(NewTokenCache())
+	tokenBlacklist := tc.addCache(NewCache())
+
+	oidc := &TraefikOidc{
+		issuerURL:         "https://login.microsoftonline.com/tenant-id/v2.0",
+		clientID:          "test-client-id",
+		audience:          "test-client-id",
+		jwksURL:           "https://login.microsoftonline.com/tenant-id/discovery/v2.0/keys",
+		limiter:           rate.NewLimiter(rate.Every(time.Second), 100),
+		logger:            logger,
+		httpClient:        &http.Client{Timeout: 10 * time.Second},
+		jwkCache:          &MockJWKCache{JWKS: jwks},
+		tokenCache:        tokenCache,
+		tokenBlacklist:    tokenBlacklist,
+		extractClaimsFunc: extractClaims,
+	}
+	oidc.tokenVerifier = oidc
+	oidc.jwtVerifier = oidc
+	require.True(t, oidc.isAzureProvider(), "fixture must be detected as Azure provider")
+	return oidc, errBuf
+}
+
+// authedSessionWithTokens returns a SessionData populated with the supplied
+// access and ID tokens, marked authenticated and recently created. The
+// SessionManager carries a real ChunkManager so that GetAccessToken /
+// GetIDToken / GetRefreshToken behave like the production code path.
+func authedSessionWithTokens(t *testing.T, accessToken, idToken string) *SessionData {
+	t.Helper()
+
+	chunkLogger := NewLogger("error")
+	chunkManager := NewChunkManager(chunkLogger)
+	t.Cleanup(chunkManager.Shutdown)
+
+	sd := CreateMockSessionData()
+	sd.manager = &SessionManager{
+		sessionMaxAge: 24 * time.Hour,
+		chunkManager:  chunkManager,
+		logger:        chunkLogger,
+	}
+
+	sd.mainSession = sessions.NewSession(nil, "main")
+	sd.mainSession.Values["authenticated"] = true
+	sd.mainSession.Values["created_at"] = time.Now().Unix()
+
+	sd.accessSession = sessions.NewSession(nil, "access")
+	sd.accessSession.Values["token"] = accessToken
+	sd.accessSession.Values["compressed"] = false
+
+	sd.idTokenSession = sessions.NewSession(nil, "id")
+	sd.idTokenSession.Values["token"] = idToken
+	sd.idTokenSession.Values["compressed"] = false
+
+	sd.refreshSession = sessions.NewSession(nil, "refresh")
+	sd.refreshSession.Values["token"] = ""
+	sd.refreshSession.Values["compressed"] = false
+
+	return sd
+}
+
+// TestIssue134_Followup_GraphAccessTokenReproducesUsersError sanity-checks
+// that our crafted Graph-style token reproduces the exact rsa error string
+// quoted on the issue thread (dada-engineer 2026-05-08, friek 2026-05-11).
+//
+// Sanity test: must always pass, regardless of the issue #134 followup fix.
+// It exists so a future contributor does not accidentally weaken the
+// reproducer and assume the followup fix is no longer needed.
+func TestIssue134_Followup_GraphAccessTokenReproducesUsersError(t *testing.T) {
+	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+
+	const kid = "azure-followup-kid"
+	graphToken := signGraphStyleAccessToken(t, rsaKey, kid, "wire-only-nonce", map[string]any{
+		"iss": "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud": "00000003-0000-0000-c000-000000000000",
+		"exp": time.Now().Add(time.Hour).Unix(),
+		"iat": time.Now().Unix(),
+		"sub": "user-azure-id",
+		"scp": "User.Read",
+	})
+
+	parsedJWT, err := parseJWT(graphToken)
+	require.NoError(t, err)
+	pubKey := &rsaKey.PublicKey
+	alg, _ := parsedJWT.Header["alg"].(string)
+	verifyErr := verifySignatureWithKey(graphToken, pubKey, alg)
+	require.Error(t, verifyErr)
+	assert.Contains(t, verifyErr.Error(), "crypto/rsa: verification error",
+		"reproducer must emit the exact error string reported on issue #134")
+}
+
+// TestIssue134_Followup_ValidateAzureTokensSkipsGraphAccessToken is the
+// failing-then-passing test for the followup fix.
+//
+// Symptom (before fix): validateAzureTokens calls verifyToken on every
+// JWT-shaped access token. For Microsoft Graph access tokens (the default
+// when no custom resource is registered), verification always fails with
+// `crypto/rsa: verification error`, generating two error log lines per
+// request:
+//
+//	UNKNOWN token verification failed: signature verification failed:
+//	  crypto/rsa: verification error
+//	DIAGNOSTIC: Signature verification failed for kid=<kid>, alg=RS256:
+//	  crypto/rsa: verification error
+//
+// Microsoft's own documentation tells client apps not to validate Graph
+// access tokens. The fix matches that guidance: when an Azure access token
+// carries Microsoft's proprietary `nonce` JWT header, treat it as opaque
+// (skip JWT verification, fall through to ID token validation).
+func TestIssue134_Followup_ValidateAzureTokensSkipsGraphAccessToken(t *testing.T) {
+	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+
+	const kid = "azure-followup-kid"
+	jwk := JWK{
+		Kty: "RSA",
+		Use: "sig",
+		Alg: "RS256",
+		Kid: kid,
+		N:   base64.RawURLEncoding.EncodeToString(rsaKey.N.Bytes()),
+		E:   base64.RawURLEncoding.EncodeToString(big.NewInt(int64(rsaKey.E)).Bytes()),
+	}
+	jwks := &JWKSet{Keys: []JWK{jwk}}
+
+	now := time.Now()
+	exp := now.Add(time.Hour).Unix()
+
+	graphAccessToken := signGraphStyleAccessToken(t, rsaKey, kid, "wire-only-nonce-azure-graph", map[string]any{
+		"iss":   "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud":   "00000003-0000-0000-c000-000000000000",
+		"exp":   exp,
+		"iat":   now.Unix(),
+		"sub":   "user-azure-id",
+		"appid": "test-client-id",
+		"scp":   "User.Read",
+	})
+
+	idToken, err := createTestJWT(rsaKey, "RS256", kid, map[string]any{
+		"iss":   "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud":   "test-client-id",
+		"exp":   exp,
+		"iat":   now.Add(-2 * time.Minute).Unix(),
+		"nbf":   now.Add(-2 * time.Minute).Unix(),
+		"sub":   "user-azure-id",
+		"email": "user@example.com",
+		"nonce": "id-token-oidc-nonce",
+		"jti":   "id-token-jti-followup",
+	})
+	require.NoError(t, err)
+
+	oidc, errBuf := newAzureFollowupOIDC(t, jwks)
+	session := authedSessionWithTokens(t, graphAccessToken, idToken)
+
+	rs := (&requestState{}).captureSession(session)
+	authenticated, needsRefresh, expired := oidc.validateAzureTokensRS(rs)
+
+	output := errBuf.String()
+	assert.NotContains(t, output, "crypto/rsa: verification error",
+		"validateAzureTokens must not log rsa verification error for Graph-style access tokens; got: %q", output)
+	assert.NotContains(t, output, "DIAGNOSTIC: Signature verification failed",
+		"DIAGNOSTIC line must not fire for Graph-style access tokens; got: %q", output)
+	assert.NotContains(t, output, "UNKNOWN token verification failed",
+		"UNKNOWN classification log must not fire for Graph-style access tokens; got: %q", output)
+
+	assert.True(t, authenticated, "session must remain authenticated via the ID token fallback")
+	assert.False(t, needsRefresh, "valid ID token must not signal a refresh need")
+	assert.False(t, expired, "valid ID token must not be reported as expired")
+}
+
+// TestIssue134_Followup_IsUnverifiableAzureAccessToken_Detection covers the
+// classifier added by the followup fix. Pure-function unit test for the
+// Microsoft proprietary marker we rely on (nonce in JWT header).
+func TestIssue134_Followup_IsUnverifiableAzureAccessToken_Detection(t *testing.T) {
+	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+
+	const kid = "azure-detection-kid"
+	standardToken, err := createTestJWT(rsaKey, "RS256", kid, map[string]any{
+		"iss": "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud": "test-client-id",
+		"exp": time.Now().Add(time.Hour).Unix(),
+		"iat": time.Now().Unix(),
+		"sub": "user-azure-id",
+	})
+	require.NoError(t, err)
+
+	graphToken := signGraphStyleAccessToken(t, rsaKey, kid, "wire-only-nonce", map[string]any{
+		"iss": "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud": "00000003-0000-0000-c000-000000000000",
+		"exp": time.Now().Add(time.Hour).Unix(),
+		"iat": time.Now().Unix(),
+		"sub": "user-azure-id",
+		"scp": "User.Read",
+	})
+
+	oidc, _ := newAzureFollowupOIDC(t, &JWKSet{})
+
+	cases := []struct {
+		name           string
+		token          string
+		wantUnverified bool
+	}{
+		{name: "standard JWT without nonce header", token: standardToken, wantUnverified: false},
+		{name: "Microsoft proprietary token (nonce in header)", token: graphToken, wantUnverified: true},
+		{name: "garbage token treated as unverifiable", token: "not-a-jwt-at-all", wantUnverified: true},
+		{name: "empty token treated as unverifiable", token: "", wantUnverified: true},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := oidc.isUnverifiableAzureAccessToken(tc.token)
+			assert.Equal(t, tc.wantUnverified, got)
+		})
+	}
+}
+
+// TestIssue134_Followup_StandardAzureAccessTokenStillVerifies guards against
+// regression in the happy path: an access token issued for our own clientID
+// (custom Azure-registered API) — no proprietary nonce header, signed normally
+// — must still flow through the standard verification path and authenticate.
+func TestIssue134_Followup_StandardAzureAccessTokenStillVerifies(t *testing.T) {
+	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+
+	const kid = "azure-standard-kid"
+	jwk := JWK{
+		Kty: "RSA", Use: "sig", Alg: "RS256", Kid: kid,
+		N: base64.RawURLEncoding.EncodeToString(rsaKey.N.Bytes()),
+		E: base64.RawURLEncoding.EncodeToString(big.NewInt(int64(rsaKey.E)).Bytes()),
+	}
+	jwks := &JWKSet{Keys: []JWK{jwk}}
+
+	now := time.Now()
+	exp := now.Add(time.Hour).Unix()
+
+	// Custom-resource access token: aud points to the app, no nonce header.
+	accessToken, err := createTestJWT(rsaKey, "RS256", kid, map[string]any{
+		"iss": "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud": "test-client-id",
+		"exp": exp,
+		"iat": now.Add(-2 * time.Minute).Unix(),
+		"nbf": now.Add(-2 * time.Minute).Unix(),
+		"sub": "user-azure-id",
+		"scp": "api.read",
+		"jti": "standard-access-jti",
+	})
+	require.NoError(t, err)
+
+	idToken, err := createTestJWT(rsaKey, "RS256", kid, map[string]any{
+		"iss":   "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud":   "test-client-id",
+		"exp":   exp,
+		"iat":   now.Add(-2 * time.Minute).Unix(),
+		"nbf":   now.Add(-2 * time.Minute).Unix(),
+		"sub":   "user-azure-id",
+		"email": "user@example.com",
+		"nonce": "id-token-oidc-nonce",
+		"jti":   "standard-id-jti",
+	})
+	require.NoError(t, err)
+
+	oidc, errBuf := newAzureFollowupOIDC(t, jwks)
+	session := authedSessionWithTokens(t, accessToken, idToken)
+
+	rs := (&requestState{}).captureSession(session)
+	authenticated, needsRefresh, expired := oidc.validateAzureTokensRS(rs)
+
+	assert.True(t, authenticated, "standard Azure access token must verify and authenticate")
+	assert.False(t, needsRefresh)
+	assert.False(t, expired)
+	assert.NotContains(t, errBuf.String(), "crypto/rsa: verification error",
+		"standard Azure token must not produce signature errors")
+}
+
+// TestIssue134_Followup_GraphAccessTokenWithoutIDToken covers the edge where
+// the session has only a Graph access token (no ID token). The classifier must
+// preserve the existing "treat as opaque" semantics for backward compatibility:
+// authenticated=true even when there is no ID token to verify.
+func TestIssue134_Followup_GraphAccessTokenWithoutIDToken(t *testing.T) {
+	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+
+	const kid = "azure-no-idt-kid"
+	jwk := JWK{
+		Kty: "RSA", Use: "sig", Alg: "RS256", Kid: kid,
+		N: base64.RawURLEncoding.EncodeToString(rsaKey.N.Bytes()),
+		E: base64.RawURLEncoding.EncodeToString(big.NewInt(int64(rsaKey.E)).Bytes()),
+	}
+	jwks := &JWKSet{Keys: []JWK{jwk}}
+
+	graphAccessToken := signGraphStyleAccessToken(t, rsaKey, kid, "wire-only-nonce-no-idt", map[string]any{
+		"iss": "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud": "00000003-0000-0000-c000-000000000000",
+		"exp": time.Now().Add(time.Hour).Unix(),
+		"iat": time.Now().Unix(),
+		"sub": "user-azure-id",
+		"scp": "User.Read",
+	})
+
+	oidc, errBuf := newAzureFollowupOIDC(t, jwks)
+	session := authedSessionWithTokens(t, graphAccessToken, "")
+
+	rs := (&requestState{}).captureSession(session)
+	authenticated, needsRefresh, expired := oidc.validateAzureTokensRS(rs)
+
+	assert.True(t, authenticated, "Graph token without ID token must remain authenticated (matches existing opaque-token semantics)")
+	assert.False(t, needsRefresh)
+	assert.False(t, expired)
+	assert.NotContains(t, errBuf.String(), "crypto/rsa: verification error")
+}
+
+// TestIssue134_Followup_ConfusedDeputyAttackDoesNotBypassVerification proves
+// the classifier is not a security regression. An attacker who forges a JWT
+// with a `nonce` JWT header (Microsoft's proprietary marker) but a payload
+// claiming `aud=our-clientID` should NOT gain authenticated status simply by
+// triggering the "treat as opaque" branch.
+//
+// This is the confused-deputy guardrail Microsoft warns about
+// (https://cwe.mitre.org/data/definitions/441.html): we treat the access token
+// as opaque, which means we DO NOT authorize from it — authorization comes
+// only from a separately verifiable ID token.  An attacker without a valid ID
+// token must not be authenticated.
+func TestIssue134_Followup_ConfusedDeputyAttackDoesNotBypassVerification(t *testing.T) {
+	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+	attackerKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+
+	const kid = "azure-attack-kid"
+	jwk := JWK{
+		Kty: "RSA", Use: "sig", Alg: "RS256", Kid: kid,
+		N: base64.RawURLEncoding.EncodeToString(rsaKey.N.Bytes()),
+		E: base64.RawURLEncoding.EncodeToString(big.NewInt(int64(rsaKey.E)).Bytes()),
+	}
+	jwks := &JWKSet{Keys: []JWK{jwk}}
+
+	// Forged: attacker uses their OWN key, sets aud = our clientID, plants a
+	// `nonce` header to trip the opaque-detection path.
+	forgedAccessToken := signGraphStyleAccessToken(t, attackerKey, kid, "attacker-nonce", map[string]any{
+		"iss": "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud": "test-client-id",
+		"exp": time.Now().Add(time.Hour).Unix(),
+		"iat": time.Now().Unix(),
+		"sub": "attacker",
+		"scp": "admin",
+	})
+
+	// Forged ID token signed with the attacker's key — must fail verification
+	// against the tenant JWKS.
+	forgedIDToken, err := createTestJWT(attackerKey, "RS256", kid, map[string]any{
+		"iss":   "https://login.microsoftonline.com/tenant-id/v2.0",
+		"aud":   "test-client-id",
+		"exp":   time.Now().Add(time.Hour).Unix(),
+		"iat":   time.Now().Add(-2 * time.Minute).Unix(),
+		"nbf":   time.Now().Add(-2 * time.Minute).Unix(),
+		"sub":   "attacker",
+		"email": "attacker@evil.example",
+		"nonce": "id-token-oidc-nonce",
+		"jti":   "attacker-id-jti",
+	})
+	require.NoError(t, err)
+
+	oidc, _ := newAzureFollowupOIDC(t, jwks)
+	session := authedSessionWithTokens(t, forgedAccessToken, forgedIDToken)
+
+	rs := (&requestState{}).captureSession(session)
+	authenticated, _, _ := oidc.validateAzureTokensRS(rs)
+	assert.False(t, authenticated,
+		"attacker's forged tokens must not authenticate even when the access token has a nonce header — ID token verification rejects the wrong-key signature")
+}

issue67_regression_test.go

@@ -478,11 +478,10 @@ func TestRefreshCoordinatorIntegration(t *testing.T) {
 
 	// Test 3: Rate limiting
 	t.Run("RateLimiting", func(t *testing.T) {
-		// Reset circuit breaker to closed state for this test
-		coordinator.circuitBreaker.mutex.Lock()
+		// Reset circuit breaker to closed state for this test. All fields are
+		// atomic so we don't need any mutex.
 		atomic.StoreInt32(&coordinator.circuitBreaker.state, 0) // closed
 		atomic.StoreInt32(&coordinator.circuitBreaker.failures, 0)
-		coordinator.circuitBreaker.mutex.Unlock()
 
 		// Temporarily increase circuit breaker threshold to not interfere
 		oldMaxFailures := coordinator.circuitBreaker.config.MaxFailures
@@ -525,9 +524,11 @@ func TestRefreshCoordinatorIntegration(t *testing.T) {
 		time.Sleep(config.CleanupInterval * 3)
 
 		// Old sessions should be cleaned up
-		coordinator.attemptsMutex.RLock()
-		count := len(coordinator.sessionRefreshAttempts)
-		coordinator.attemptsMutex.RUnlock()
+		count := 0
+		coordinator.sessionRefreshAttempts.Range(func(_, _ interface{}) bool {
+			count++
+			return true
+		})
 
 		// Should have fewer sessions after cleanup
 		if count > 10 {

jwk.go

@@ -53,10 +53,26 @@ type JWKSet struct {
 	Keys []JWK `json:"keys"`
 }
 
-// JWKCache provides thread-safe caching of JWKS using UniversalCache
+// JWKCache provides thread-safe caching of JWKS using UniversalCache.
+//
+// inflightFetches deduplicates concurrent fetches for the same JWKS URL.
+// It replaces a global sync.RWMutex that was previously held for the entire
+// HTTP round-trip in GetJWKS: on a cold cache (cold pod, JWK rotation, brief
+// network blip) every concurrent request piled up on that single Lock(), and
+// under Yaegi each Lock acquisition costs 10-50ms of interpreter-dispatch
+// overhead. The singleflight pattern keeps the cold-cache cost O(1) HTTP
+// fetch regardless of how many requests are waiting.
 type JWKCache struct {
-	cache *UniversalCache
-	mutex sync.RWMutex
+	cache           *UniversalCache
+	inflightFetches sync.Map // map[jwksURL string]*jwksFetch
+}
+
+// jwksFetch represents an in-flight JWKS fetch. Done is closed when the fetch
+// completes; jwks and err carry the result (one of them is set, never both).
+type jwksFetch struct {
+	done chan struct{}
+	jwks *JWKSet
+	err  error
 }
 
 // JWKCacheInterface defines the contract for JWK caching implementations.
@@ -83,36 +99,58 @@ func NewJWKCache() *JWKCache {
 // request refetches from the upstream. JWK rotation is rare and a per-replica
 // HTTP fetch on cold cache is cheap, so cross-replica coherence buys nothing.
 func (c *JWKCache) GetJWKS(ctx context.Context, jwksURL string, httpClient *http.Client) (*JWKSet, error) {
-	// Check cache first
+	// Fast path: cache hit.
 	if cachedValue, found := c.cache.GetLocal(jwksURL); found {
 		if jwks, ok := cachedValue.(*JWKSet); ok {
 			return jwks, nil
 		}
 	}
 
-	c.mutex.Lock()
-	defer c.mutex.Unlock()
+	// Singleflight: dedupe concurrent fetches per URL key. The first arrival
+	// performs the HTTP fetch; any later arrival for the same URL waits on
+	// its done channel and shares the result. No global lock is held during
+	// the fetch.
+	candidate := &jwksFetch{done: make(chan struct{})}
+	if existing, loaded := c.inflightFetches.LoadOrStore(jwksURL, candidate); loaded {
+		f, _ := existing.(*jwksFetch)
+		select {
+		case <-f.done:
+			return f.jwks, f.err
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		}
+	}
 
-	// Double-check after acquiring lock
+	// We're the leader. Make absolutely sure the result fields and the
+	// in-flight map entry are cleaned up before any waiter unblocks.
+	defer func() {
+		c.inflightFetches.Delete(jwksURL)
+		close(candidate.done)
+	}()
+
+	// Re-check the cache in case a concurrent fetch completed between our
+	// initial miss and our LoadOrStore win.
 	if cachedValue, found := c.cache.GetLocal(jwksURL); found {
 		if jwks, ok := cachedValue.(*JWKSet); ok {
+			candidate.jwks = jwks
 			return jwks, nil
 		}
 	}
 
-	// Fetch from URL
 	jwks, err := fetchJWKS(ctx, jwksURL, httpClient)
 	if err != nil {
+		candidate.err = err
 		return nil, err
 	}
-
 	if len(jwks.Keys) == 0 {
-		return nil, fmt.Errorf("JWKS response contains no keys")
+		candidate.err = fmt.Errorf("JWKS response contains no keys")
+		return nil, candidate.err
 	}
 
-	// Cache for 1 hour
+	// Cache for 1 hour.
 	_ = c.cache.SetLocal(jwksURL, jwks, 1*time.Hour) // Safe to ignore: cache failures are non-critical
 
+	candidate.jwks = jwks
 	return jwks, nil
 }
 
@@ -162,6 +200,22 @@ func buildParsedJWKS(jwks *JWKSet) *parsedJWKS {
 		if k.Kid == "" {
 			continue
 		}
+		// Skip keys that are not intended for signature verification.
+		if k.Use != "" && k.Use != "sig" {
+			continue
+		}
+		if len(k.KeyOps) > 0 {
+			hasVerify := false
+			for _, op := range k.KeyOps {
+				if op == "verify" {
+					hasVerify = true
+					break
+				}
+			}
+			if !hasVerify {
+				continue
+			}
+		}
 		var pub crypto.PublicKey
 		var err error
 		switch k.Kty {
@@ -204,11 +258,11 @@ func fetchJWKS(ctx context.Context, jwksURL string, httpClient *http.Client) (*J
 	defer func() { _ = resp.Body.Close() }() // Safe to ignore: closing body on defer
 
 	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(resp.Body) // Safe to ignore: reading error body for diagnostics
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 10*1024)) // Safe to ignore: reading error body for diagnostics
 		return nil, fmt.Errorf("JWKS fetch failed with status %d: %s", resp.StatusCode, body)
 	}
 
-	body, err := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
 	if err != nil {
 		return nil, fmt.Errorf("error reading JWKS response: %w", err)
 	}

logout.go

@@ -134,8 +134,11 @@ func (t *TraefikOidc) handleFrontchannelLogout(rw http.ResponseWriter, req *http
 	expectedIssuer := t.issuerURL
 	t.metadataMu.RUnlock()
 
-	if iss != "" && iss != expectedIssuer {
-		t.logger.Errorf("Front-channel logout: issuer mismatch: got %s, expected %s", iss, expectedIssuer)
+	// Require a matching issuer. An empty iss must be rejected too: accepting a
+	// missing issuer would let an unauthenticated attacker force-logout any
+	// session whose sid is known by simply omitting iss.
+	if iss == "" || iss != expectedIssuer {
+		t.logger.Errorf("Front-channel logout: issuer validation failed: got %q, expected %q", iss, expectedIssuer)
 		http.Error(rw, "Invalid issuer", http.StatusBadRequest)
 		return
 	}

logout_test.go

@@ -125,10 +125,14 @@ func TestFrontchannelLogoutBasic(t *testing.T) {
 			expectedStatus: http.StatusOK,
 		},
 		{
-			name:           "Valid front-channel logout without issuer",
+			// Front-channel logout MUST carry a matching issuer. A request
+			// omitting iss is rejected so an unauthenticated attacker cannot
+			// force-logout a session whose sid is known by simply leaving iss
+			// out (audit rank 30).
+			name:           "Missing issuer is rejected",
 			method:         http.MethodGet,
 			queryParams:    map[string]string{"sid": "session456"},
-			expectedStatus: http.StatusOK,
+			expectedStatus: http.StatusBadRequest,
 		},
 	}
 
@@ -407,17 +411,17 @@ func TestMiddlewareBackchannelLogoutRouting(t *testing.T) {
 	})
 
 	oidc := &TraefikOidc{
-		next:                     nextHandler,
-		logger:                   NewLogger("debug"),
-		enableBackchannelLogout:  true,
-		backchannelLogoutPath:    "/backchannel-logout",
-		sessionInvalidationCache: mockCache,
-		clientID:                 "test-client",
-		issuerURL:                "https://provider.example.com",
-		initComplete:             make(chan struct{}),
-		firstRequestReceived:     true,
-		metadataRefreshStarted:   true,
-		logoutURLPath:            "/logout",
+		next:                         nextHandler,
+		logger:                       NewLogger("debug"),
+		enableBackchannelLogout:      true,
+		backchannelLogoutPath:        "/backchannel-logout",
+		sessionInvalidationCache:     mockCache,
+		clientID:                     "test-client",
+		issuerURL:                    "https://provider.example.com",
+		initComplete:                 make(chan struct{}),
+		firstRequestStarted:          1,
+		metadataRefreshStartedAtomic: 1,
+		logoutURLPath:                "/logout",
 	}
 	close(oidc.initComplete)
 
@@ -449,22 +453,23 @@ func TestMiddlewareFrontchannelLogoutRouting(t *testing.T) {
 	})
 
 	oidc := &TraefikOidc{
-		next:                     nextHandler,
-		logger:                   NewLogger("debug"),
-		enableFrontchannelLogout: true,
-		frontchannelLogoutPath:   "/frontchannel-logout",
-		sessionInvalidationCache: mockCache,
-		clientID:                 "test-client",
-		issuerURL:                "https://provider.example.com",
-		initComplete:             make(chan struct{}),
-		firstRequestReceived:     true,
-		metadataRefreshStarted:   true,
-		logoutURLPath:            "/logout",
+		next:                         nextHandler,
+		logger:                       NewLogger("debug"),
+		enableFrontchannelLogout:     true,
+		frontchannelLogoutPath:       "/frontchannel-logout",
+		sessionInvalidationCache:     mockCache,
+		clientID:                     "test-client",
+		issuerURL:                    "https://provider.example.com",
+		initComplete:                 make(chan struct{}),
+		firstRequestStarted:          1,
+		metadataRefreshStartedAtomic: 1,
+		logoutURLPath:                "/logout",
 	}
 	close(oidc.initComplete)
 
-	// Request to front-channel logout path with valid sid should succeed
-	req := httptest.NewRequest(http.MethodGet, "/frontchannel-logout?sid=test-session", nil)
+	// Request to front-channel logout path with valid sid + matching issuer
+	// should succeed. The issuer is now required (audit rank 30), so supply it.
+	req := httptest.NewRequest(http.MethodGet, "/frontchannel-logout?sid=test-session&iss=https://provider.example.com", nil)
 	rw := httptest.NewRecorder()
 
 	oidc.ServeHTTP(rw, req)
@@ -1432,7 +1437,9 @@ func TestFrontchannelLogoutCacheControl(t *testing.T) {
 		issuerURL:                "https://provider.example.com",
 	}
 
-	req := httptest.NewRequest(http.MethodGet, "/frontchannel-logout?sid=session123", nil)
+	// Issuer is now required (audit rank 30); supply a matching one so the
+	// successful-logout cache headers can be asserted.
+	req := httptest.NewRequest(http.MethodGet, "/frontchannel-logout?sid=session123&iss=https://provider.example.com", nil)
 	rw := httptest.NewRecorder()
 
 	oidc.handleFrontchannelLogout(rw, req)

main.go

@@ -9,6 +9,7 @@ import (
 	"encoding/hex"
 	"fmt"
 	"net/http"
+	"net/url"
 	"os"
 	"runtime"
 	"strings"
@@ -16,6 +17,7 @@ import (
 	"text/template"
 	"time"
 
+	telemetry "github.com/lukaszraczylo/oss-telemetry"
 	"golang.org/x/time/rate"
 )
 
@@ -23,6 +25,11 @@ const (
 	ConstSessionTimeout = 86400
 )
 
+// telemetryStartupOnce keeps the anonymous "plugin loaded" ping to one per
+// process. Traefik calls New once per route that uses the plugin; oss-telemetry
+// does not deduplicate client-side (the server does), so the gate stays here.
+var telemetryStartupOnce sync.Once
+
 // isTestMode detects if the code is running in a test environment.
 func isTestMode() bool {
 	if os.Getenv("SUPPRESS_DIAGNOSTIC_LOGS") == "1" {
@@ -89,6 +96,13 @@ var defaultExcludedURLs = map[string]struct{}{
 //   - The configured TraefikOidc handler ready to process requests.
 //   - An error if essential configuration is missing or invalid (e.g., short encryption key).
 func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error) {
+	telemetryStartupOnce.Do(func() {
+		// Only stamped release builds phone home; dev/local/test builds keep the
+		// devPluginVersion sentinel (see version.go) and stay silent.
+		if traefikoidcPluginVersion != devPluginVersion {
+			telemetry.Send("traefikoidc", traefikoidcPluginVersion)
+		}
+	})
 	return NewWithContext(ctx, config, next, name)
 }
 
@@ -99,18 +113,18 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		config = CreateConfig()
 	}
 
-	if config.SessionEncryptionKey == "" {
-		config.SessionEncryptionKey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
-	}
-
 	logger := NewLogger(config.LogLevel)
-	if len(config.SessionEncryptionKey) < minEncryptionKeyLength {
-		if runtime.Compiler == "yaegi" {
-			config.SessionEncryptionKey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
-			logger.Infof("Session encryption key is too short; using default key for analyzer")
-		} else {
-			return nil, fmt.Errorf("encryption key must be at least %d bytes long", minEncryptionKeyLength)
-		}
+
+	// Fail closed on invalid configuration. Validate() enforces the security
+	// constraints (required fields, HTTPS-only URLs, key length, excludedURLs
+	// safety, rate-limit floor, audience format, ...) that were previously
+	// unenforced because this constructor never called it. Crucially it rejects
+	// an empty or too-short SessionEncryptionKey instead of silently
+	// substituting a public hardcoded key, which would let an attacker forge
+	// any session. Traefik's yaegi plugin analyzer supplies a valid key via
+	// .traefik.yml testData, so it passes; only misconfigured deployments fail.
+	if err := config.Validate(); err != nil {
+		return nil, fmt.Errorf("invalid configuration: %w", err)
 	}
 	// Setup HTTP client
 	caPool, err := config.loadCACertPool()
@@ -201,6 +215,7 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		}(),
 		forceHTTPS:                config.ForceHTTPS,
 		enablePKCE:                config.EnablePKCE,
+		extraAuthParams:           config.ExtraAuthParams,
 		overrideScopes:            config.OverrideScopes,
 		strictAudienceValidation:  config.StrictAudienceValidation,
 		allowOpaqueTokens:         config.AllowOpaqueTokens,
@@ -221,7 +236,7 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		httpClient:            httpClient,
 		tokenHTTPClient:       tokenHTTPClient,
 		excludedURLs:          createStringMap(config.ExcludedURLs),
-		allowedUserDomains:    createStringMap(config.AllowedUserDomains),
+		allowedUserDomains:    createCaseInsensitiveStringMap(config.AllowedUserDomains),
 		allowedUsers:          createCaseInsensitiveStringMap(config.AllowedUsers),
 		allowedRolesAndGroups: createStringMap(config.AllowedRolesAndGroups),
 		initComplete:          make(chan struct{}),
@@ -239,23 +254,63 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 			}
 			return 0
 		}(),
-		tokenCleanupStopChan:     make(chan struct{}),
-		metadataRefreshStopChan:  make(chan struct{}),
-		ctx:                      pluginCtx,
-		cancelFunc:               cancelFunc,
-		suppressDiagnosticLogs:   isTestMode(),
-		securityHeadersApplier:   config.GetSecurityHeadersApplier(),
-		scopeFilter:              NewScopeFilter(logger), // NEW - for discovery-based scope filtering
-		dcrConfig:                config.DynamicClientRegistration,
-		allowPrivateIPAddresses:  config.AllowPrivateIPAddresses,
-		minimalHeaders:           config.MinimalHeaders,
-		stripAuthCookies:         config.StripAuthCookies,
-		enableBackchannelLogout:  config.EnableBackchannelLogout,
-		enableFrontchannelLogout: config.EnableFrontchannelLogout,
-		backchannelLogoutPath:    normalizeLogoutPath(config.BackchannelLogoutURL),
-		frontchannelLogoutPath:   normalizeLogoutPath(config.FrontchannelLogoutURL),
-		sessionInvalidationCache: cacheManager.GetSharedSessionInvalidationCache(),
-		refreshResultCache:       cacheManager.GetSharedRefreshResultCache(),
+		tokenCleanupStopChan:      make(chan struct{}),
+		metadataRefreshStopChan:   make(chan struct{}),
+		ctx:                       pluginCtx,
+		cancelFunc:                cancelFunc,
+		suppressDiagnosticLogs:    isTestMode(),
+		securityHeadersApplier:    config.GetSecurityHeadersApplier(),
+		scopeFilter:               NewScopeFilter(logger), // NEW - for discovery-based scope filtering
+		dcrConfig:                 config.DynamicClientRegistration,
+		allowPrivateIPAddresses:   config.AllowPrivateIPAddresses,
+		minimalHeaders:            config.MinimalHeaders,
+		stripAuthCookies:          config.StripAuthCookies,
+		enableBackchannelLogout:   config.EnableBackchannelLogout,
+		enableFrontchannelLogout:  config.EnableFrontchannelLogout,
+		backchannelLogoutPath:     normalizeLogoutPath(config.BackchannelLogoutURL),
+		frontchannelLogoutPath:    normalizeLogoutPath(config.FrontchannelLogoutURL),
+		sessionInvalidationCache:  cacheManager.GetSharedSessionInvalidationCache(),
+		refreshResultCache:        cacheManager.GetSharedRefreshResultCache(),
+		enableBearerAuth:          config.EnableBearerAuth,
+		stripAuthorizationHeader:  config.StripAuthorizationHeader,
+		bearerEmitWWWAuthenticate: config.BearerEmitWWWAuthenticate,
+		bearerOverridesCookie:     config.BearerOverridesCookie,
+		bearerIdentifierClaim: func() string {
+			if config.BearerIdentifierClaim != "" {
+				return config.BearerIdentifierClaim
+			}
+			return "sub"
+		}(),
+		maxIdentifierLength: func() int {
+			if config.MaxIdentifierLength > 0 {
+				return config.MaxIdentifierLength
+			}
+			return 256
+		}(),
+		maxTokenAge: func() time.Duration {
+			if config.MaxTokenAgeSeconds > 0 {
+				return time.Duration(config.MaxTokenAgeSeconds) * time.Second
+			}
+			return 24 * time.Hour
+		}(),
+		bearerFailureThreshold: func() int {
+			if config.BearerFailureThreshold > 0 {
+				return config.BearerFailureThreshold
+			}
+			return 20
+		}(),
+		bearerFailureWindow: func() time.Duration {
+			if config.BearerFailureWindowSeconds > 0 {
+				return time.Duration(config.BearerFailureWindowSeconds) * time.Second
+			}
+			return 60 * time.Second
+		}(),
+		bearerFailurePenalty: func() time.Duration {
+			if config.BearerFailurePenaltySeconds > 0 {
+				return time.Duration(config.BearerFailurePenaltySeconds) * time.Second
+			}
+			return 60 * time.Second
+		}(),
 	}
 
 	// Log audience configuration
@@ -265,9 +320,39 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		t.logger.Debugf("No custom audience specified, using clientID as audience: %s", t.clientID)
 	}
 
+	// Bearer-auth startup validation. The bearer path is M2M-only and demands
+	// a non-default audience so tokens issued for a different resource cannot
+	// be replayed against this service. The BearerIdentifierClaim guard blocks
+	// the `email` claim explicitly — without email_verified enforcement (out of
+	// scope for M2M), trusting email is a spoofing vector for federated IdPs.
+	// See spec §7.9 / §13.
+	if config.EnableBearerAuth {
+		if config.Audience == "" {
+			cancelFunc()
+			return nil, fmt.Errorf("EnableBearerAuth=true requires Audience to be set explicitly (cannot default to clientID — that path accepts ID tokens)")
+		}
+		if t.bearerIdentifierClaim == "email" {
+			cancelFunc()
+			return nil, fmt.Errorf("enableBearerAuth=true with bearerIdentifierClaim=%q is rejected: email-based identity without email_verified enforcement is a spoofing vector for federated IdPs (use \"sub\" or a custom claim; cookie-path userIdentifierClaim is unaffected)", t.bearerIdentifierClaim)
+		}
+		if !config.StrictAudienceValidation {
+			t.logger.Infof("EnableBearerAuth=true with StrictAudienceValidation=false: recommend enabling strict audience validation for hardening")
+		}
+		t.bearerFailureTracker = newBearerFailureTracker(
+			t.bearerFailureThreshold, t.bearerFailureWindow, t.bearerFailurePenalty,
+		)
+		t.logger.Infof("Bearer-token auth enabled: audience=%q identifierClaim=%q stripAuthz=%t bearerOverridesCookie=%t maxTokenAge=%s",
+			config.Audience, t.bearerIdentifierClaim, t.stripAuthorizationHeader, t.bearerOverridesCookie, t.maxTokenAge)
+	}
+
 	// Convert sessionMaxAge from seconds to duration (0 will use default 24 hours)
 	sessionMaxAge := time.Duration(config.SessionMaxAge) * time.Second
-	t.sessionManager, _ = NewSessionManager(config.SessionEncryptionKey, config.ForceHTTPS, config.CookieDomain, config.CookiePrefix, sessionMaxAge, t.logger) // Safe to ignore: session manager creation with fallback to defaults
+	sessionManager, err := NewSessionManager(config.SessionEncryptionKey, config.ForceHTTPS, config.CookieDomain, config.CookiePrefix, sessionMaxAge, t.logger)
+	if err != nil {
+		cancelFunc()
+		return nil, fmt.Errorf("failed to create session manager: %w", err)
+	}
+	t.sessionManager = sessionManager
 	t.errorRecoveryManager = NewErrorRecoveryManager(t.logger)
 
 	// Initialize token resilience manager with default configuration
@@ -358,6 +443,7 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 
 	// Add reference for this instance
 	rm.AddReference(name)
+	registerLiveInstance()
 
 	// Initialize metadata in a goroutine with proper tracking
 	if t.goroutineWG != nil {
@@ -435,13 +521,58 @@ func (t *TraefikOidc) initializeMetadata(providerURL string) {
 // Parameters:
 //   - metadata: A pointer to the ProviderMetadata struct containing the discovered endpoints.
 func (t *TraefikOidc) updateMetadataEndpoints(metadata *ProviderMetadata) {
+	// SSRF defense (audit ranks 3 & 4): a discovery document is attacker-
+	// influenced when the provider or its TLS is compromised. Reject any
+	// discovered endpoint pointed at a blocked address before the plugin issues
+	// outbound requests to it, so it can never be used to reach the cloud
+	// metadata service or an internal host.
+	allowLoopback := false
+	if pu, err := url.Parse(t.providerURL); err == nil {
+		allowLoopback = isLoopbackHost(pu.Hostname())
+	}
+	sanitize := func(name, raw string) string {
+		if err := t.validateDiscoveredEndpoint(raw, allowLoopback); err != nil {
+			t.logger.Errorf("Ignoring discovered %s endpoint %q: %v", name, raw, err)
+			return ""
+		}
+		return raw
+	}
+	metadata.JWKSURL = sanitize("jwks_uri", metadata.JWKSURL)
+	metadata.AuthURL = sanitize("authorization", metadata.AuthURL)
+	metadata.TokenURL = sanitize("token", metadata.TokenURL)
+	metadata.RevokeURL = sanitize("revocation", metadata.RevokeURL)
+	metadata.EndSessionURL = sanitize("end_session", metadata.EndSessionURL)
+	metadata.RegistrationURL = sanitize("registration", metadata.RegistrationURL)
+	metadata.IntrospectionURL = sanitize("introspection", metadata.IntrospectionURL)
+	// The introspection request authenticates with the client secret via HTTP
+	// Basic, so the endpoint must live on the same host as the operator-
+	// configured provider; otherwise a poisoned discovery document could
+	// exfiltrate the client secret to an attacker-controlled host.
+	if metadata.IntrospectionURL != "" && t.providerURL != "" && !sameHost(metadata.IntrospectionURL, t.providerURL) {
+		t.logger.Errorf("Ignoring introspection endpoint %q: host does not match configured providerURL", metadata.IntrospectionURL)
+		metadata.IntrospectionURL = ""
+	}
+
+	// Pin the discovered issuer to the operator-configured provider host. The
+	// issuer is the trust anchor for JWT issuer validation, so a poisoned
+	// discovery document advertising an attacker-chosen issuer must never be
+	// stored. Real providers (Google, Azure, Keycloak, Okta, Auth0) keep the
+	// issuer on the same host as the configured providerURL. On mismatch, leave
+	// issuerURL empty/unchanged so downstream issuer validation fails closed
+	// rather than trusting the attacker-chosen value.
+	discoveredIssuer := metadata.Issuer
+	if discoveredIssuer != "" && t.providerURL != "" && !sameHost(discoveredIssuer, t.providerURL) {
+		t.logger.Errorf("Ignoring discovered issuer %q: host does not match configured providerURL", discoveredIssuer)
+		discoveredIssuer = ""
+	}
+
 	t.metadataMu.Lock()
 
 	t.jwksURL = metadata.JWKSURL
 	t.scopesSupported = metadata.ScopesSupported // Store supported scopes from discovery
 	t.authURL = metadata.AuthURL
 	t.tokenURL = metadata.TokenURL
-	t.issuerURL = metadata.Issuer
+	t.issuerURL = discoveredIssuer
 	t.revocationURL = metadata.RevokeURL
 	t.endSessionURL = metadata.EndSessionURL
 	t.introspectionURL = metadata.IntrospectionURL // OAuth 2.0 Token Introspection endpoint (RFC 7662)
@@ -451,6 +582,19 @@ func (t *TraefikOidc) updateMetadataEndpoints(metadata *ProviderMetadata) {
 	introspectionURL := t.introspectionURL
 	registrationURL := t.registrationURL
 
+	// Publish the read-mostly URL bundle atomically. Hot-path readers Load
+	// this directly instead of acquiring metadataMu.RLock per request.
+	t.metadataSnapshot.Store(&MetadataSnapshot{
+		IssuerURL:        discoveredIssuer,
+		JWKSURL:          metadata.JWKSURL,
+		TokenURL:         metadata.TokenURL,
+		AuthURL:          metadata.AuthURL,
+		RevocationURL:    metadata.RevokeURL,
+		EndSessionURL:    metadata.EndSessionURL,
+		IntrospectionURL: metadata.IntrospectionURL,
+		RegistrationURL:  metadata.RegistrationURL,
+	})
+
 	t.metadataMu.Unlock()
 
 	// Log introspection endpoint availability for opaque token support

main_goroutine_leak_test.go

@@ -194,6 +194,7 @@ func TestGoroutineLeakPrevention_MultipleInstances(t *testing.T) {
 		config.SessionEncryptionKey = "test-encryption-key-32-bytes-long"
 		config.ClientID = "test-client-id"
 		config.ClientSecret = "test-client-secret"
+		config.CallbackURL = "/callback"
 
 		handler, err := New(ctx, nil, config, "test")
 		if err != nil {
@@ -322,6 +323,7 @@ func TestGoroutineLeakPrevention_BackgroundTaskCleanup(t *testing.T) {
 	config.SessionEncryptionKey = "test-encryption-key-32-bytes-long"
 	config.ClientID = "test-client-id"
 	config.ClientSecret = "test-client-secret"
+	config.CallbackURL = "/callback"
 
 	handler, err := New(ctx, nil, config, "test")
 	if err != nil {

main_initialization_test.go

@@ -8,6 +8,7 @@ import (
 	"net/http/httptest"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 )
@@ -25,38 +26,47 @@ func TestInitializeMetadata(t *testing.T) {
 			name:        "successful metadata initialization",
 			providerURL: "",
 			setupMock: func() *httptest.Server {
-				return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				// Issuer must share the host with providerURL (the httptest
+				// server), otherwise the discovery doc is rejected as poisoned
+				// (audit ranks 21/22). Real providers keep issuer + endpoints on
+				// the same host, so derive them all from the server URL.
+				var srv *httptest.Server
+				srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 					if strings.HasSuffix(r.URL.Path, "/.well-known/openid-configuration") {
 						w.Header().Set("Content-Type", "application/json")
 						json.NewEncoder(w).Encode(ProviderMetadata{
-							Issuer:        "https://provider.example.com",
-							AuthURL:       "https://provider.example.com/auth",
-							TokenURL:      "https://provider.example.com/token",
-							JWKSURL:       "https://provider.example.com/jwks",
-							RevokeURL:     "https://provider.example.com/revoke",
-							EndSessionURL: "https://provider.example.com/logout",
+							Issuer:        srv.URL,
+							AuthURL:       srv.URL + "/auth",
+							TokenURL:      srv.URL + "/token",
+							JWKSURL:       srv.URL + "/jwks",
+							RevokeURL:     srv.URL + "/revoke",
+							EndSessionURL: srv.URL + "/logout",
 						})
 					} else {
 						w.WriteHeader(http.StatusNotFound)
 					}
 				}))
+				return srv
 			},
 			validateFunc: func(t *testing.T, oidc *TraefikOidc) {
-				if oidc.authURL != "https://provider.example.com/auth" {
+				if oidc.authURL == "" || !strings.HasSuffix(oidc.authURL, "/auth") {
 					t.Errorf("expected authURL to be set, got %s", oidc.authURL)
 				}
-				if oidc.tokenURL != "https://provider.example.com/token" {
+				if oidc.tokenURL == "" || !strings.HasSuffix(oidc.tokenURL, "/token") {
 					t.Errorf("expected tokenURL to be set, got %s", oidc.tokenURL)
 				}
-				if oidc.jwksURL != "https://provider.example.com/jwks" {
+				if oidc.jwksURL == "" || !strings.HasSuffix(oidc.jwksURL, "/jwks") {
 					t.Errorf("expected jwksURL to be set, got %s", oidc.jwksURL)
 				}
-				if oidc.revocationURL != "https://provider.example.com/revoke" {
+				if oidc.revocationURL == "" || !strings.HasSuffix(oidc.revocationURL, "/revoke") {
 					t.Errorf("expected revocationURL to be set, got %s", oidc.revocationURL)
 				}
-				if oidc.endSessionURL != "https://provider.example.com/logout" {
+				if oidc.endSessionURL == "" || !strings.HasSuffix(oidc.endSessionURL, "/logout") {
 					t.Errorf("expected endSessionURL to be set, got %s", oidc.endSessionURL)
 				}
+				if oidc.issuerURL == "" {
+					t.Errorf("expected issuerURL to be pinned to provider host, got empty")
+				}
 			},
 			wantPanic: false,
 		},
@@ -115,24 +125,27 @@ func TestInitializeMetadata(t *testing.T) {
 			name:        "partial metadata response",
 			providerURL: "",
 			setupMock: func() *httptest.Server {
-				return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				// Issuer host must match providerURL (audit ranks 21/22).
+				var srv *httptest.Server
+				srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 					if strings.HasSuffix(r.URL.Path, "/.well-known/openid-configuration") {
 						w.Header().Set("Content-Type", "application/json")
 						// Only return some fields
 						json.NewEncoder(w).Encode(map[string]string{
-							"issuer":                 "https://partial.example.com",
-							"authorization_endpoint": "https://partial.example.com/auth",
-							"token_endpoint":         "https://partial.example.com/token",
+							"issuer":                 srv.URL,
+							"authorization_endpoint": srv.URL + "/auth",
+							"token_endpoint":         srv.URL + "/token",
 							// Missing jwks_uri, revocation_endpoint, end_session_endpoint
 						})
 					}
 				}))
+				return srv
 			},
 			validateFunc: func(t *testing.T, oidc *TraefikOidc) {
-				if oidc.authURL != "https://partial.example.com/auth" {
+				if oidc.authURL == "" || !strings.HasSuffix(oidc.authURL, "/auth") {
 					t.Errorf("expected authURL to be set, got %s", oidc.authURL)
 				}
-				if oidc.tokenURL != "https://partial.example.com/token" {
+				if oidc.tokenURL == "" || !strings.HasSuffix(oidc.tokenURL, "/token") {
 					t.Errorf("expected tokenURL to be set, got %s", oidc.tokenURL)
 				}
 				// JWKS URL and others may be empty
@@ -197,20 +210,22 @@ func TestInitializeMetadata_Concurrency(t *testing.T) {
 	requestCount := 0
 	var mu sync.Mutex
 
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		mu.Lock()
 		requestCount++
 		mu.Unlock()
 
 		if strings.HasSuffix(r.URL.Path, "/.well-known/openid-configuration") {
 			w.Header().Set("Content-Type", "application/json")
+			// Issuer host must match providerURL (audit ranks 21/22).
 			json.NewEncoder(w).Encode(ProviderMetadata{
-				Issuer:        "https://concurrent.example.com",
-				AuthURL:       "https://concurrent.example.com/auth",
-				TokenURL:      "https://concurrent.example.com/token",
-				JWKSURL:       "https://concurrent.example.com/jwks",
-				RevokeURL:     "https://concurrent.example.com/revoke",
-				EndSessionURL: "https://concurrent.example.com/logout",
+				Issuer:        server.URL,
+				AuthURL:       server.URL + "/auth",
+				TokenURL:      server.URL + "/token",
+				JWKSURL:       server.URL + "/jwks",
+				RevokeURL:     server.URL + "/revoke",
+				EndSessionURL: server.URL + "/logout",
 			})
 		}
 	}))
@@ -249,7 +264,7 @@ func TestInitializeMetadata_Concurrency(t *testing.T) {
 			oidc.initializeMetadata(server.URL)
 
 			// Verify initialization
-			if oidc.tokenURL != "https://concurrent.example.com/token" {
+			if oidc.tokenURL == "" || !strings.HasSuffix(oidc.tokenURL, "/token") {
 				t.Errorf("expected tokenURL to be set")
 			}
 		}()
@@ -341,17 +356,19 @@ func TestProviderDetection(t *testing.T) {
 // TestInitializationWaiting tests waiting for initialization to complete
 func TestInitializationWaiting(t *testing.T) {
 	t.Run("wait for initialization completion", func(t *testing.T) {
-		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var server *httptest.Server
+		server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			// Delay response to simulate slow initialization
 			time.Sleep(100 * time.Millisecond)
 
 			if strings.HasSuffix(r.URL.Path, "/.well-known/openid-configuration") {
 				w.Header().Set("Content-Type", "application/json")
+				// Issuer host must match providerURL (audit ranks 21/22).
 				json.NewEncoder(w).Encode(ProviderMetadata{
-					Issuer:   "https://slow.example.com",
-					AuthURL:  "https://slow.example.com/auth",
-					TokenURL: "https://slow.example.com/token",
-					JWKSURL:  "https://slow.example.com/jwks",
+					Issuer:   server.URL,
+					AuthURL:  server.URL + "/auth",
+					TokenURL: server.URL + "/token",
+					JWKSURL:  server.URL + "/jwks",
 				})
 			}
 		}))
@@ -388,7 +405,7 @@ func TestInitializationWaiting(t *testing.T) {
 		select {
 		case <-oidc.initComplete:
 			// Success
-			if oidc.tokenURL != "https://slow.example.com/token" {
+			if oidc.tokenURL == "" || !strings.HasSuffix(oidc.tokenURL, "/token") {
 				t.Error("expected tokenURL to be set after initialization")
 			}
 		case <-time.After(2 * time.Second):
@@ -397,17 +414,19 @@ func TestInitializationWaiting(t *testing.T) {
 	})
 
 	t.Run("multiple waiters for initialization", func(t *testing.T) {
-		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var server *httptest.Server
+		server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			// Delay to ensure multiple waiters
 			time.Sleep(50 * time.Millisecond)
 
 			if strings.HasSuffix(r.URL.Path, "/.well-known/openid-configuration") {
 				w.Header().Set("Content-Type", "application/json")
+				// Issuer host must match providerURL (audit ranks 21/22).
 				json.NewEncoder(w).Encode(ProviderMetadata{
-					Issuer:   "https://multi.example.com",
-					AuthURL:  "https://multi.example.com/auth",
-					TokenURL: "https://multi.example.com/token",
-					JWKSURL:  "https://multi.example.com/jwks",
+					Issuer:   server.URL,
+					AuthURL:  server.URL + "/auth",
+					TokenURL: server.URL + "/token",
+					JWKSURL:  server.URL + "/jwks",
 				})
 			}
 		}))
@@ -452,7 +471,7 @@ func TestInitializationWaiting(t *testing.T) {
 				select {
 				case <-oidc.initComplete:
 					// All waiters should see the same initialized state
-					if oidc.tokenURL != "https://multi.example.com/token" {
+					if oidc.tokenURL == "" || !strings.HasSuffix(oidc.tokenURL, "/token") {
 						t.Errorf("waiter %d: expected tokenURL to be set", id)
 					}
 				case <-time.After(2 * time.Second):
@@ -484,9 +503,8 @@ func TestFirstRequestHandling(t *testing.T) {
 		defer server.Close()
 
 		oidc := &TraefikOidc{
-			providerURL:          server.URL,
-			firstRequestReceived: false,
-			firstRequestMutex:    sync.Mutex{},
+			providerURL:         server.URL,
+			firstRequestStarted: 0,
 			httpClient: &http.Client{
 				Timeout: 5 * time.Second,
 			},
@@ -508,19 +526,13 @@ func TestFirstRequestHandling(t *testing.T) {
 			},
 		}
 
-		// Simulate first request processing
-		oidc.firstRequestMutex.Lock()
-		if !oidc.firstRequestReceived {
-			oidc.firstRequestReceived = true
-			oidc.firstRequestMutex.Unlock()
-
+		// Simulate first request processing — single-firing via CAS.
+		if atomic.CompareAndSwapInt32(&oidc.firstRequestStarted, 0, 1) {
 			// This would normally be called asynchronously
 			go func() {
 				oidc.initializeMetadata(server.URL)
 				// initComplete is closed internally by initializeMetadata
 			}()
-		} else {
-			oidc.firstRequestMutex.Unlock()
 		}
 
 		// Wait for initialization
@@ -556,9 +568,8 @@ func TestFirstRequestHandling(t *testing.T) {
 		defer server.Close()
 
 		oidc := &TraefikOidc{
-			providerURL:          server.URL,
-			firstRequestReceived: false,
-			firstRequestMutex:    sync.Mutex{},
+			providerURL:         server.URL,
+			firstRequestStarted: 0,
 			httpClient: &http.Client{
 				Timeout: 5 * time.Second,
 			},
@@ -580,31 +591,22 @@ func TestFirstRequestHandling(t *testing.T) {
 			},
 		}
 
-		// Simulate multiple concurrent "first" requests
+		// Simulate multiple concurrent "first" requests — only one CAS winner
+		// fires the bootstrap path.
 		const numRequests = 10
 		var wg sync.WaitGroup
 		wg.Add(numRequests)
 
-		initStarted := 0
-		var initMu sync.Mutex
+		var initStarted int32
 
 		for i := 0; i < numRequests; i++ {
 			go func() {
 				defer wg.Done()
 
-				oidc.firstRequestMutex.Lock()
-				if !oidc.firstRequestReceived {
-					oidc.firstRequestReceived = true
-					oidc.firstRequestMutex.Unlock()
-
-					initMu.Lock()
-					initStarted++
-					initMu.Unlock()
-
+				if atomic.CompareAndSwapInt32(&oidc.firstRequestStarted, 0, 1) {
+					atomic.AddInt32(&initStarted, 1)
 					// Only one should actually start initialization
 					oidc.initializeMetadata(server.URL)
-				} else {
-					oidc.firstRequestMutex.Unlock()
 				}
 			}()
 		}
@@ -612,8 +614,8 @@ func TestFirstRequestHandling(t *testing.T) {
 		wg.Wait()
 
 		// Verify only one initialization was started
-		if initStarted != 1 {
-			t.Errorf("expected exactly 1 initialization, got %d", initStarted)
+		if atomic.LoadInt32(&initStarted) != 1 {
+			t.Errorf("expected exactly 1 initialization, got %d", atomic.LoadInt32(&initStarted))
 		}
 
 		// The metadata endpoint might be called once or not at all depending on timing

main_servehttp_test.go

@@ -61,8 +61,8 @@ func TestServeHTTP_ExcludedURLs(t *testing.T) {
 				logger:                 NewLogger("debug"),
 				initComplete:           make(chan struct{}),
 				sessionManager:         createTestSessionManager(t),
-				firstRequestReceived:   true,
-				metadataRefreshStarted: true,
+				firstRequestStarted: 1,
+				metadataRefreshStartedAtomic: 1,
 				issuerURL:              "https://provider.example.com", // Required for initialization check
 			}
 			close(oidc.initComplete)
@@ -92,8 +92,8 @@ func TestServeHTTP_EventStream(t *testing.T) {
 			logger:                 NewLogger("debug"),
 			initComplete:           make(chan struct{}),
 			sessionManager:         sessionManager,
-			firstRequestReceived:   true,
-			metadataRefreshStarted: true,
+			firstRequestStarted: 1,
+			metadataRefreshStartedAtomic: 1,
 			issuerURL:              "https://provider.example.com",
 		}
 		close(oidc.initComplete)
@@ -175,8 +175,8 @@ func TestServeHTTP_WebSocketUpgrade(t *testing.T) {
 			logger:                 NewLogger("debug"),
 			initComplete:           make(chan struct{}),
 			sessionManager:         sessionManager,
-			firstRequestReceived:   true,
-			metadataRefreshStarted: true,
+			firstRequestStarted: 1,
+			metadataRefreshStartedAtomic: 1,
 			issuerURL:              "https://provider.example.com",
 		}
 		close(oidc.initComplete)
@@ -272,8 +272,8 @@ func TestServeHTTP_InitializationTimeout(t *testing.T) {
 			logger:                 NewLogger("debug"),
 			initComplete:           make(chan struct{}), // Never close this to simulate timeout
 			sessionManager:         createTestSessionManager(t),
-			firstRequestReceived:   true,
-			metadataRefreshStarted: true,
+			firstRequestStarted: 1,
+			metadataRefreshStartedAtomic: 1,
 		}
 
 		req := httptest.NewRequest("GET", "/protected", nil)
@@ -307,8 +307,8 @@ func TestServeHTTP_InitializationTimeout(t *testing.T) {
 			logger:                 NewLogger("debug"),
 			initComplete:           make(chan struct{}),
 			sessionManager:         createTestSessionManager(t),
-			firstRequestReceived:   true,
-			metadataRefreshStarted: true,
+			firstRequestStarted: 1,
+			metadataRefreshStartedAtomic: 1,
 			issuerURL:              "https://provider.example.com",
 			redirURLPath:           "/callback",
 			logoutURLPath:          "/logout",
@@ -337,8 +337,8 @@ func TestServeHTTP_CallbackAndLogout(t *testing.T) {
 			logger:                 NewLogger("debug"),
 			initComplete:           make(chan struct{}),
 			sessionManager:         createTestSessionManager(t),
-			firstRequestReceived:   true,
-			metadataRefreshStarted: true,
+			firstRequestStarted: 1,
+			metadataRefreshStartedAtomic: 1,
 			issuerURL:              "https://provider.example.com",
 			redirURLPath:           "/callback",
 			logoutURLPath:          "/logout",
@@ -367,8 +367,8 @@ func TestServeHTTP_CallbackAndLogout(t *testing.T) {
 			logger:                 NewLogger("debug"),
 			initComplete:           make(chan struct{}),
 			sessionManager:         createTestSessionManager(t),
-			firstRequestReceived:   true,
-			metadataRefreshStarted: true,
+			firstRequestStarted: 1,
+			metadataRefreshStartedAtomic: 1,
 			issuerURL:              "https://provider.example.com",
 			redirURLPath:           "/callback",
 			logoutURLPath:          "/logout",
@@ -740,8 +740,8 @@ func TestMinimalHeaders(t *testing.T) {
 				logger:                 NewLogger("debug"),
 				initComplete:           make(chan struct{}),
 				sessionManager:         sessionManager,
-				firstRequestReceived:   true,
-				metadataRefreshStarted: true,
+				firstRequestStarted: 1,
+				metadataRefreshStartedAtomic: 1,
 				issuerURL:              "https://provider.example.com",
 				minimalHeaders:         tt.minimalHeaders,
 				extractClaimsFunc: func(token string) (map[string]interface{}, error) {
@@ -817,8 +817,8 @@ func TestMinimalHeaders_TokenHeaderNotSet(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}),
 		sessionManager:         sessionManager,
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 		issuerURL:              "https://provider.example.com",
 		minimalHeaders:         true, // Enable minimal headers
 		extractClaimsFunc: func(token string) (map[string]interface{}, error) {
@@ -903,8 +903,8 @@ func TestStripAuthCookies(t *testing.T) {
 				logger:                 NewLogger("debug"),
 				initComplete:           make(chan struct{}),
 				sessionManager:         sessionManager,
-				firstRequestReceived:   true,
-				metadataRefreshStarted: true,
+				firstRequestStarted: 1,
+				metadataRefreshStartedAtomic: 1,
 				issuerURL:              "https://provider.example.com",
 				stripAuthCookies:       tt.stripAuthCookies,
 				extractClaimsFunc: func(token string) (map[string]interface{}, error) {
@@ -987,8 +987,8 @@ func TestStripAuthCookies_NoCookies(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}),
 		sessionManager:         sessionManager,
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 		issuerURL:              "https://provider.example.com",
 		stripAuthCookies:       true,
 		extractClaimsFunc: func(token string) (map[string]interface{}, error) {
@@ -1034,8 +1034,8 @@ func TestStripAuthCookies_OnlyOIDCCookies(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}),
 		sessionManager:         sessionManager,
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 		issuerURL:              "https://provider.example.com",
 		stripAuthCookies:       true,
 		extractClaimsFunc: func(token string) (map[string]interface{}, error) {
@@ -1085,8 +1085,8 @@ func TestStripAuthCookies_OnlyAppCookies(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}),
 		sessionManager:         sessionManager,
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 		issuerURL:              "https://provider.example.com",
 		stripAuthCookies:       true,
 		extractClaimsFunc: func(token string) (map[string]interface{}, error) {
@@ -1148,8 +1148,8 @@ func TestStripAuthCookies_CustomPrefix(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}),
 		sessionManager:         sm,
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 		issuerURL:              "https://provider.example.com",
 		stripAuthCookies:       true,
 		extractClaimsFunc: func(token string) (map[string]interface{}, error) {

main_test.go

@@ -16,6 +16,7 @@ import (
 	"net/url"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -1874,14 +1875,14 @@ func TestHandleLogout(t *testing.T) {
 			},
 			endSessionURL:  "",
 			expectedStatus: http.StatusFound,
-			expectedURL:    "http://example.com/",
+			expectedURL:    "/",
 			host:           "test-host",
 		},
 		{
 			name:           "Logout with empty session",
 			setupSession:   func(session *SessionData) {},
 			expectedStatus: http.StatusFound,
-			expectedURL:    "http://example.com/",
+			expectedURL:    "/",
 			host:           "test-host",
 		},
 		{
@@ -2348,19 +2349,22 @@ func TestMultipleMiddlewareInstances(t *testing.T) {
 		t.Skip("Skipping test in short mode")
 	}
 
-	// Create mock provider metadata server
-	mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	// Create mock provider metadata server. Issuer + endpoints must share the
+	// host with ProviderURL (the httptest server), otherwise the discovery doc
+	// is rejected as poisoned (audit ranks 21/22). Derive them from the server.
+	var mockServer *httptest.Server
+	mockServer = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/.well-known/openid-configuration" {
 			w.WriteHeader(http.StatusNotFound)
 			return
 		}
 		metadata := ProviderMetadata{
-			Issuer:        "https://test-issuer.com",
-			AuthURL:       "https://test-issuer.com/auth",
-			TokenURL:      "https://test-issuer.com/token",
-			JWKSURL:       "https://test-issuer.com/jwks",
-			RevokeURL:     "https://test-issuer.com/revoke",
-			EndSessionURL: "https://test-issuer.com/end-session",
+			Issuer:        mockServer.URL,
+			AuthURL:       mockServer.URL + "/auth",
+			TokenURL:      mockServer.URL + "/token",
+			JWKSURL:       mockServer.URL + "/jwks",
+			RevokeURL:     mockServer.URL + "/revoke",
+			EndSessionURL: mockServer.URL + "/end-session",
 		}
 		json.NewEncoder(w).Encode(metadata)
 	}))
@@ -2373,6 +2377,7 @@ func TestMultipleMiddlewareInstances(t *testing.T) {
 		ClientSecret:         "test-secret",
 		CallbackURL:          "/callback",
 		SessionEncryptionKey: "test-encryption-key-thats-long-enough",
+		RateLimit:            100,
 	}
 
 	// Create multiple middleware instances
@@ -2413,18 +2418,20 @@ func TestMultipleMiddlewareInstances(t *testing.T) {
 			t.Fatalf("Middleware instance %d failed to initialize", i)
 		}
 
-		// Verify each instance has its own unique configuration
-		if m.issuerURL != "https://test-issuer.com" {
-			t.Errorf("Instance %d: Expected issuer URL %s, got %s", i, "https://test-issuer.com", m.issuerURL)
+		// Verify each instance has its own unique configuration. Issuer is now
+		// pinned to the provider host (audit ranks 21/22), so it equals the
+		// mock server URL rather than a fixed literal.
+		if m.issuerURL != mockServer.URL {
+			t.Errorf("Instance %d: Expected issuer URL %s, got %s", i, mockServer.URL, m.issuerURL)
 		}
-		if m.authURL != "https://test-issuer.com/auth" {
-			t.Errorf("Instance %d: Expected auth URL %s, got %s", i, "https://test-issuer.com/auth", m.authURL)
+		if m.authURL != mockServer.URL+"/auth" {
+			t.Errorf("Instance %d: Expected auth URL %s, got %s", i, mockServer.URL+"/auth", m.authURL)
 		}
-		if m.tokenURL != "https://test-issuer.com/token" {
-			t.Errorf("Instance %d: Expected token URL %s, got %s", i, "https://test-issuer.com/token", m.tokenURL)
+		if m.tokenURL != mockServer.URL+"/token" {
+			t.Errorf("Instance %d: Expected token URL %s, got %s", i, mockServer.URL+"/token", m.tokenURL)
 		}
-		if m.jwksURL != "https://test-issuer.com/jwks" {
-			t.Errorf("Instance %d: Expected JWKS URL %s, got %s", i, "https://test-issuer.com/jwks", m.jwksURL)
+		if m.jwksURL != mockServer.URL+"/jwks" {
+			t.Errorf("Instance %d: Expected JWKS URL %s, got %s", i, mockServer.URL+"/jwks", m.jwksURL)
 		}
 		if m.redirURLPath != routes[i]+"/callback" {
 			t.Errorf("Instance %d: Expected callback URL %s, got %s", i, routes[i]+"/callback", m.redirURLPath)
@@ -2438,15 +2445,16 @@ func TestMultipleMiddlewareInstances(t *testing.T) {
 
 		m.ServeHTTP(rr, req)
 
-		// Should redirect to auth URL since not authenticated
+		// Should redirect (302) to the auth flow since not authenticated. The
+		// absolute auth URL is not asserted here: with issuer pinning (audit
+		// ranks 21/22) the discovery host equals the httptest server host,
+		// which is loopback, so buildAuthURL's SSRF guard legitimately refuses
+		// to emit a loopback authorization URL in this test environment. The
+		// per-instance auth/token/jwks/issuer URLs were already verified above;
+		// here we only confirm each instance independently triggers a redirect.
 		if rr.Code != http.StatusFound {
 			t.Errorf("Instance %d: Expected redirect status %d, got %d", i, http.StatusFound, rr.Code)
 		}
-
-		location := rr.Header().Get("Location")
-		if !strings.Contains(location, "https://test-issuer.com/auth") {
-			t.Errorf("Instance %d: Expected redirect to auth URL, got %s", i, location)
-		}
 	}
 }
 
@@ -2459,33 +2467,43 @@ func TestMultiRealmMetadataRefreshIsolation(t *testing.T) {
 	}
 
 	// Create two mock provider metadata servers simulating different Keycloak realms
-	realm1Server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	// Issuer + endpoints must share the host with each realm's ProviderURL
+	// (the httptest server), otherwise the discovery doc is rejected as
+	// poisoned (audit ranks 21/22). Keep the distinguishing /realms/realmN
+	// path so the per-realm isolation assertions below still hold, but base
+	// the host on the server URL — which is exactly what a same-host Keycloak
+	// deployment looks like.
+	var realm1Server *httptest.Server
+	realm1Server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/.well-known/openid-configuration" {
 			w.WriteHeader(http.StatusNotFound)
 			return
 		}
+		base := realm1Server.URL + "/realms/realm1"
 		metadata := ProviderMetadata{
-			Issuer:        "https://keycloak.example.com/realms/realm1",
-			AuthURL:       "https://keycloak.example.com/realms/realm1/protocol/openid-connect/auth",
-			TokenURL:      "https://keycloak.example.com/realms/realm1/protocol/openid-connect/token",
-			JWKSURL:       "https://keycloak.example.com/realms/realm1/protocol/openid-connect/certs",
-			EndSessionURL: "https://keycloak.example.com/realms/realm1/protocol/openid-connect/logout",
+			Issuer:        base,
+			AuthURL:       base + "/protocol/openid-connect/auth",
+			TokenURL:      base + "/protocol/openid-connect/token",
+			JWKSURL:       base + "/protocol/openid-connect/certs",
+			EndSessionURL: base + "/protocol/openid-connect/logout",
 		}
 		json.NewEncoder(w).Encode(metadata)
 	}))
 	defer realm1Server.Close()
 
-	realm2Server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	var realm2Server *httptest.Server
+	realm2Server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/.well-known/openid-configuration" {
 			w.WriteHeader(http.StatusNotFound)
 			return
 		}
+		base := realm2Server.URL + "/realms/realm2"
 		metadata := ProviderMetadata{
-			Issuer:        "https://keycloak.example.com/realms/realm2",
-			AuthURL:       "https://keycloak.example.com/realms/realm2/protocol/openid-connect/auth",
-			TokenURL:      "https://keycloak.example.com/realms/realm2/protocol/openid-connect/token",
-			JWKSURL:       "https://keycloak.example.com/realms/realm2/protocol/openid-connect/certs",
-			EndSessionURL: "https://keycloak.example.com/realms/realm2/protocol/openid-connect/logout",
+			Issuer:        base,
+			AuthURL:       base + "/protocol/openid-connect/auth",
+			TokenURL:      base + "/protocol/openid-connect/token",
+			JWKSURL:       base + "/protocol/openid-connect/certs",
+			EndSessionURL: base + "/protocol/openid-connect/logout",
 		}
 		json.NewEncoder(w).Encode(metadata)
 	}))
@@ -2499,6 +2517,7 @@ func TestMultiRealmMetadataRefreshIsolation(t *testing.T) {
 		CallbackURL:          "/realm1/callback",
 		SessionEncryptionKey: "test-encryption-key-thats-long-enough",
 		CookiePrefix:         "_oidc_realm1_",
+		RateLimit:            100,
 	}
 
 	// Config for realm2
@@ -2509,6 +2528,7 @@ func TestMultiRealmMetadataRefreshIsolation(t *testing.T) {
 		CallbackURL:          "/realm2/callback",
 		SessionEncryptionKey: "test-encryption-key-thats-long-enough",
 		CookiePrefix:         "_oidc_realm2_",
+		RateLimit:            100,
 	}
 
 	// Create middleware instances for both realms
@@ -2607,8 +2627,11 @@ func TestMetadataRecoveryOnProviderFailure(t *testing.T) {
 	providerAvailable := false
 	var mu sync.Mutex
 
-	// Create mock provider that initially fails, then becomes available
-	mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	// Create mock provider that initially fails, then becomes available.
+	// Issuer + endpoints must share the host with ProviderURL (audit ranks
+	// 21/22), so derive them from the server URL.
+	var mockServer *httptest.Server
+	mockServer = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		mu.Lock()
 		available := providerAvailable
 		mu.Unlock()
@@ -2620,11 +2643,11 @@ func TestMetadataRecoveryOnProviderFailure(t *testing.T) {
 
 		if r.URL.Path == "/.well-known/openid-configuration" {
 			metadata := ProviderMetadata{
-				Issuer:        "https://test-issuer.com",
-				AuthURL:       "https://test-issuer.com/auth",
-				TokenURL:      "https://test-issuer.com/token",
-				JWKSURL:       "https://test-issuer.com/jwks",
-				EndSessionURL: "https://test-issuer.com/logout",
+				Issuer:        mockServer.URL,
+				AuthURL:       mockServer.URL + "/auth",
+				TokenURL:      mockServer.URL + "/token",
+				JWKSURL:       mockServer.URL + "/jwks",
+				EndSessionURL: mockServer.URL + "/logout",
 			}
 			json.NewEncoder(w).Encode(metadata)
 			return
@@ -2639,6 +2662,7 @@ func TestMetadataRecoveryOnProviderFailure(t *testing.T) {
 		ClientSecret:         "test-secret",
 		CallbackURL:          "/callback",
 		SessionEncryptionKey: "test-encryption-key-thats-long-enough",
+		RateLimit:            100,
 	}
 
 	// Create middleware while provider is unavailable
@@ -2685,10 +2709,9 @@ func TestMetadataRecoveryOnProviderFailure(t *testing.T) {
 	providerAvailable = true
 	mu.Unlock()
 
-	// Reset the retry timer to allow immediate retry
-	m.metadataRetryMutex.Lock()
-	m.lastMetadataRetryTime = time.Time{} // Reset to zero time
-	m.metadataRetryMutex.Unlock()
+	// Reset the retry timer to allow immediate retry. The field is atomic
+	// now, so no lock is needed.
+	atomic.StoreInt64(&m.lastMetadataRetryNano, 0)
 
 	// Second request should trigger recovery attempt
 	req2 := httptest.NewRequest("GET", "/protected", nil)
@@ -4552,6 +4575,7 @@ func TestNewWithScopeAppending(t *testing.T) {
 				CallbackURL:          "/callback",
 				SessionEncryptionKey: "test-encryption-key-thats-long-enough",
 				Scopes:               tc.configScopes,
+				RateLimit:            100,
 			}
 
 			// Create middleware instance

memory_leak_test.go

@@ -1652,6 +1652,7 @@ func TestGoroutineLeaks(t *testing.T) {
 				config.SessionEncryptionKey = "test-encryption-key-32-bytes-long"
 				config.ClientID = "test-client"
 				config.ClientSecret = "test-secret"
+				config.CallbackURL = "/callback"
 
 				handler, err := New(context.Background(), nil, config, "test")
 				require.NoError(t, err)

metadata_cache.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	"net/http"
 	"strings"
 	"sync"
@@ -141,10 +142,19 @@ func (mc *MetadataCache) GetProviderMetadata(ctx context.Context, providerURL st
 	}
 
 	var metadata ProviderMetadata
-	if err := json.NewDecoder(resp.Body).Decode(&metadata); err != nil {
+	if err := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&metadata); err != nil {
 		return nil, fmt.Errorf("failed to decode metadata: %w", err)
 	}
 
+	// Pin the advertised issuer to the configured provider host. The issuer is
+	// the trust anchor for JWT issuer validation; rejecting a mismatch here
+	// ensures a poisoned discovery document advertising an attacker-chosen
+	// issuer is never cached or returned. Real providers (Google, Azure,
+	// Keycloak, Okta, Auth0) keep the issuer on the same host as providerURL.
+	if metadata.Issuer != "" && !sameHost(metadata.Issuer, providerURL) {
+		return nil, fmt.Errorf("discovery issuer %q host does not match provider %q", metadata.Issuer, providerURL)
+	}
+
 	// Cache for 1 hour by default
 	if err := mc.Set(providerURL, &metadata, 1*time.Hour); err != nil {
 		mc.logger.Errorf("Failed to cache metadata: %v", err)

middleware.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"net/http"
 	"strings"
+	"sync/atomic"
 	"time"
 
 	"github.com/lukaszraczylo/traefikoidc/internal/utils"
@@ -145,19 +146,20 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 	}
 
 	if !strings.HasPrefix(req.URL.Path, "/health") {
-		t.firstRequestMutex.Lock()
-		if !t.firstRequestReceived {
-			t.firstRequestReceived = true
+		// Lock-free one-shot bootstrap. The previous firstRequestMutex.Lock()
+		// fired on EVERY non-health request forever (even after the boolean
+		// flipped true), which under Yaegi added a per-request serialization
+		// point. CAS gives single-firing semantics with zero steady-state cost.
+		if atomic.CompareAndSwapInt32(&t.firstRequestStarted, 0, 1) {
 			t.logger.Debug("Starting background tasks on first request")
 			t.startTokenCleanup()
 
-			if !t.metadataRefreshStarted && t.providerURL != "" {
-				t.metadataRefreshStarted = true
+			if t.providerURL != "" &&
+				atomic.CompareAndSwapInt32(&t.metadataRefreshStartedAtomic, 0, 1) {
 				// Metadata refresh is handled by singleton resource manager
 				t.startMetadataRefresh(t.providerURL)
 			}
 		}
-		t.firstRequestMutex.Unlock()
 	}
 
 	// Evaluate auth-bypass once, before waiting for initialization. Excluded
@@ -168,6 +170,14 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 	// unauthenticated traffic would silently expose the backend.
 	if bypass, reason := t.shouldBypassAuth(req); bypass {
 		t.logger.Debugf("Bypassing OIDC for %s (%s)", req.URL.Path, reason)
+		// When bearer auth is enabled, strip the Authorization header on
+		// bypassed paths so a bearer token can't leak into health/metrics/
+		// public endpoint logs via downstream services that don't expect it.
+		// Excluded URLs are explicitly public; bearer is an artifact of the
+		// API auth flow that doesn't belong on them.
+		if t.enableBearerAuth {
+			req.Header.Del("Authorization")
+		}
 		switch reason {
 		case bypassReasonExcluded:
 			// Operator-declared excluded URLs forward unconditionally.
@@ -199,20 +209,31 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 
 	select {
 	case <-t.initComplete:
-		// Read issuerURL with RLock
-		t.metadataMu.RLock()
-		issuerURL := t.issuerURL
-		t.metadataMu.RUnlock()
+		// Read issuerURL via atomic snapshot when available — replaces the
+		// metadataMu.RLock that previously fired on every non-bypass request.
+		// Under Yaegi each RLock acquisition costs 1-5ms of interpreter
+		// dispatch; the snapshot is a single atomic.Value.Load. Falls back
+		// to the legacy field+RLock for paths that haven't published a
+		// snapshot yet (notably some test setups that initialize the struct
+		// fields directly).
+		var issuerURL string
+		if snap := t.metadataSnap(); snap != nil {
+			issuerURL = snap.IssuerURL
+		} else {
+			t.metadataMu.RLock()
+			issuerURL = t.issuerURL
+			t.metadataMu.RUnlock()
+		}
 
 		if issuerURL == "" {
-			// Provider metadata initialization failed - try to recover
-			// Retry every 30 seconds to allow automatic recovery when provider comes back online
-			t.metadataRetryMutex.Lock()
-			shouldRetry := time.Since(t.lastMetadataRetryTime) >= 30*time.Second
-			if shouldRetry {
-				t.lastMetadataRetryTime = time.Now()
-			}
-			t.metadataRetryMutex.Unlock()
+			// Provider metadata initialization failed - try to recover.
+			// Retry every 30 seconds to allow automatic recovery. Lock-free
+			// throttle via CAS on lastMetadataRetryNano: one goroutine wins
+			// the window, others see shouldRetry=false.
+			nowNano := time.Now().UnixNano()
+			last := atomic.LoadInt64(&t.lastMetadataRetryNano)
+			shouldRetry := time.Duration(nowNano-last) >= 30*time.Second &&
+				atomic.CompareAndSwapInt64(&t.lastMetadataRetryNano, last, nowNano)
 
 			if shouldRetry && t.providerURL != "" {
 				t.logger.Info("Attempting to recover OIDC provider metadata...")
@@ -236,6 +257,24 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 	// Bypass checks already ran before the init wait; no need to repeat them.
 	t.sessionManager.CleanupOldCookies(rw, req)
 
+	// Bearer-token auth (opt-in). Runs after init (we need issuer+JWKs+aud
+	// available) and after bypass (excluded URLs always win). Cookie-vs-
+	// bearer precedence is configurable; the safe default is cookie-wins.
+	// See bearer_auth.go for the full pipeline.
+	if t.enableBearerAuth {
+		if _, hasBearer := detectBearerToken(req); hasBearer {
+			cookiePresent := t.hasSessionCookie(req)
+			if !cookiePresent || t.bearerOverridesCookie {
+				if cookiePresent {
+					t.logger.Infof("Both Authorization: Bearer and session cookie present on %s; bearer-wins per BearerOverridesCookie=true", req.URL.Path)
+				}
+				t.handleBearerRequest(rw, req)
+				return
+			}
+			t.logger.Infof("Both Authorization: Bearer and session cookie present on %s; cookie-wins (default); bearer ignored", req.URL.Path)
+		}
+	}
+
 	session, err := t.sessionManager.GetSession(req)
 	if err != nil {
 		t.logger.Errorf("Error getting session: %v. Initiating authentication.", err)
@@ -272,6 +311,19 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 	host := utils.DetermineHost(req)
 	redirectURL := buildFullURL(scheme, host, t.redirURLPath)
 
+	// Capture per-request state: one RLock on sd.sessionMutex covers all the
+	// getter values the handler chain needs (instead of 5-7 separate
+	// session.GetX() calls each acquiring their own RLock under Yaegi).
+	// metadataSnap is also stored once so downstream handlers don't repeat
+	// the atomic.Value.Load.
+	rs := (&requestState{
+		scheme:      scheme,
+		host:        host,
+		redirectURL: redirectURL,
+		next:        t.next,
+		metadata:    t.metadataSnap(),
+	}).captureSession(session)
+
 	// Check if the current request is the OIDC callback
 	t.logger.Debugf("Checking callback URL match: request_path=%q, configured_callback=%q", req.URL.Path, t.redirURLPath)
 	if req.URL.Path == t.redirURLPath {
@@ -281,7 +333,10 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 	}
 	t.logger.Debugf("Callback URL did not match (request_path=%q != configured=%q), continuing auth flow", req.URL.Path, t.redirURLPath)
 
-	authenticated, needsRefresh, expired := t.isUserAuthenticated(session)
+	// Token validation reads session via the captured snapshot — saves ~21
+	// sd.sessionMutex.RLock acquisitions (Yaegi-dispatched, ~1-5ms each)
+	// across the validation path.
+	authenticated, needsRefresh, expired := t.isUserAuthenticatedRS(rs)
 
 	if expired {
 		t.logger.Debug("Session token is definitively expired or invalid, initiating re-auth")
@@ -289,7 +344,7 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 		return
 	}
 
-	userIdentifier := session.GetUserIdentifier()
+	userIdentifier := rs.userIdentifier
 	// User authorization check
 	if authenticated && userIdentifier != "" {
 		if !t.isAllowedUser(userIdentifier) {
@@ -306,11 +361,11 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 		// methods (validateAzureTokens/validateStandardTokens) before reaching this point.
 		// Redundant validation here was causing issues with Azure AD tokens that have
 		// JWT format but unverifiable signatures. See issue #89.
-		t.processAuthorizedRequest(rw, req, session, redirectURL)
+		t.processAuthorizedRequestRS(rw, req, rs)
 		return
 	}
 
-	refreshTokenPresent := session.GetRefreshToken() != ""
+	refreshTokenPresent := rs.refreshToken != ""
 
 	// Decide whether to answer with 401 instead of a redirect. AJAX requests
 	// cannot follow a 302 into an IdP, and sub-resource loads (script/image/
@@ -401,15 +456,112 @@ func (t *TraefikOidc) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 	t.defaultInitiateAuthentication(rw, req, session, redirectURL)
 }
 
-// processAuthorizedRequest processes requests for authenticated users.
-// It extracts claims, validates roles/groups if configured, sets authentication headers,
-// processes header templates, and forwards the request to the next handler.
-// Domain checks should be performed before calling this method.
+// processAuthorizedRequest processes requests for authenticated cookie/session
+// users. It performs session-specific checks (identifier presence, backchannel-
+// logout invalidation, claims extraction with potential re-auth), persists
+// dirty session state, then delegates the post-auth pipeline (roles/groups,
+// header injection, security headers, cookie strip, forward) to
+// forwardAuthorized.
+//
+// The bearer-token path uses the same forwardAuthorized helper but takes a
+// different route to it (see bearer_auth.go). Keeping forwardAuthorized
+// session-agnostic is what lets the two auth methods share one pipeline.
+//
 // Parameters:
 //   - rw: The HTTP response writer.
 //   - req: The HTTP request to process.
 //   - session: The user's session data containing tokens and claims.
 //   - redirectURL: The callback URL for re-authentication if needed.
+//
+// processAuthorizedRequestRS is the requestState-aware variant of
+// processAuthorizedRequest. It reads SessionData fields from the captured
+// snapshot in rs instead of calling session.GetX() (each of which acquires
+// sd.sessionMutex.RLock — under Yaegi every RLock pays ~1-5ms of interpreter
+// dispatch). Only session-mutating operations (Save, ResetRedirectCount,
+// Clear, IsDirty) still go through the session pointer because those write
+// state and have no snapshot.
+func (t *TraefikOidc) processAuthorizedRequestRS(rw http.ResponseWriter, req *http.Request, rs *requestState) {
+	session := rs.session
+	redirectURL := rs.redirectURL
+	userIdentifier := rs.userIdentifier
+	if userIdentifier == "" {
+		t.logger.Info("No user identifier found in session during final processing, initiating re-auth")
+		session.ResetRedirectCount()
+		t.defaultInitiateAuthentication(rw, req, session, redirectURL)
+		return
+	}
+
+	// Check if session has been invalidated via backchannel or front-channel logout
+	idToken := rs.idToken
+	if t.enableBackchannelLogout || t.enableFrontchannelLogout {
+		if idToken != "" {
+			sid, sub, createdAt := t.extractSessionInfo(idToken)
+			if t.isSessionInvalidated(sid, sub, createdAt) {
+				t.logger.Infof("Session for user %s has been invalidated via IdP-initiated logout", userIdentifier)
+				if err := session.Clear(req, rw); err != nil {
+					t.logger.Errorf("Error clearing invalidated session: %v", err)
+				}
+				session.ResetRedirectCount()
+				t.defaultInitiateAuthentication(rw, req, session, redirectURL)
+				return
+			}
+		}
+	}
+
+	// Resolve ID-token claims at most once per request. SessionData caches
+	// the parsed claims keyed on the raw ID token.
+	var (
+		idClaims    map[string]interface{}
+		idClaimsErr error
+	)
+	if idToken != "" {
+		idClaims, idClaimsErr = session.GetIDTokenClaims(t.extractClaimsFunc)
+	}
+
+	var (
+		groupClaims    map[string]interface{}
+		groupClaimsErr error
+	)
+	if idToken != "" {
+		groupClaims, groupClaimsErr = idClaims, idClaimsErr
+	} else if rs.accessToken != "" {
+		groupClaims, groupClaimsErr = t.extractClaimsFunc(rs.accessToken)
+	} else if len(t.allowedRolesAndGroups) > 0 {
+		t.logger.Error("No token available but roles/groups checks are required")
+		session.ResetRedirectCount()
+		t.defaultInitiateAuthentication(rw, req, session, redirectURL)
+		return
+	}
+
+	if groupClaimsErr != nil && len(t.allowedRolesAndGroups) > 0 {
+		t.logger.Errorf("Failed to extract claims for roles/groups check: %v", groupClaimsErr)
+		session.ResetRedirectCount()
+		t.defaultInitiateAuthentication(rw, req, session, redirectURL)
+		return
+	}
+
+	// Persist any dirty session state BEFORE forwardAuthorized writes the
+	// response.
+	if session.IsDirty() {
+		if err := session.Save(req, rw); err != nil {
+			t.logger.Errorf("Failed to save session after processing headers: %v", err)
+		}
+	} else {
+		t.logger.Debug("Session not dirty, skipping save in processAuthorizedRequest")
+	}
+
+	p := &principal{
+		Source:       sourceSession,
+		Identifier:   userIdentifier,
+		AccessToken:  rs.accessToken,
+		IDToken:      idToken,
+		RefreshToken: rs.refreshToken,
+		Claims:       groupClaims,
+	}
+
+	t.forwardAuthorized(rw, req, p)
+}
+
 func (t *TraefikOidc) processAuthorizedRequest(rw http.ResponseWriter, req *http.Request, session *SessionData, redirectURL string) {
 	userIdentifier := session.GetUserIdentifier()
 	if userIdentifier == "" {
@@ -442,8 +594,7 @@ func (t *TraefikOidc) processAuthorizedRequest(rw http.ResponseWriter, req *http
 	// the parsed claims keyed on the raw ID token, so concurrent dashboard
 	// panel requests on the same session don't repeatedly base64-decode and
 	// JSON-unmarshal the same JWT (a real cost under the yaegi interpreter
-	// that hosts Traefik plugins). idClaims is reused below by the
-	// header-templates branch.
+	// that hosts Traefik plugins).
 	idToken := session.GetIDToken()
 	var (
 		idClaims    map[string]interface{}
@@ -472,23 +623,126 @@ func (t *TraefikOidc) processAuthorizedRequest(rw http.ResponseWriter, req *http
 		return
 	}
 
-	var groups, roles []string
+	if groupClaimsErr != nil && len(t.allowedRolesAndGroups) > 0 {
+		// Claims couldn't be extracted but roles checks are required:
+		// re-authenticate rather than 403 (session may be salvageable on
+		// re-issue). Bearer path uses 401 for the equivalent failure.
+		t.logger.Errorf("Failed to extract claims for roles/groups check: %v", groupClaimsErr)
+		session.ResetRedirectCount()
+		t.defaultInitiateAuthentication(rw, req, session, redirectURL)
+		return
+	}
 
-	if groupClaimsErr == nil && groupClaims != nil {
-		var err error
-		groups, roles, err = t.extractGroupsAndRolesFromClaims(groupClaims)
-		if err != nil && len(t.allowedRolesAndGroups) > 0 {
-			t.logger.Errorf("Failed to extract groups and roles: %v", err)
-			session.ResetRedirectCount()
-			t.defaultInitiateAuthentication(rw, req, session, redirectURL)
+	// Persist any dirty session state BEFORE forwardAuthorized writes the
+	// response. Once next.ServeHTTP fires, Set-Cookie can no longer reach
+	// the client. The forwardAuthorized pipeline does not mutate session
+	// state, so saving here is safe.
+	if session.IsDirty() {
+		if err := session.Save(req, rw); err != nil {
+			t.logger.Errorf("Failed to save session after processing headers: %v", err)
+		}
+	} else {
+		t.logger.Debug("Session not dirty, skipping save in processAuthorizedRequest")
+	}
+
+	// Build the source-agnostic principal. ID-token claims drive header
+	// templates and roles when present; otherwise fall back to access-token
+	// claims (matches prior behavior for opaque-ID-token providers).
+	p := &principal{
+		Source:       sourceSession,
+		Identifier:   userIdentifier,
+		AccessToken:  session.GetAccessToken(),
+		IDToken:      idToken,
+		RefreshToken: session.GetRefreshToken(),
+		Claims:       groupClaims,
+	}
+
+	t.forwardAuthorized(rw, req, p)
+}
+
+// forwardAuthorized completes the post-authentication pipeline shared by the
+// cookie/session path and the bearer-token path. It performs:
+//
+//  1. Roles/groups extraction from p.Claims (idempotent; existing
+//     extractGroupsAndRolesFromClaims helper).
+//  2. allowedRolesAndGroups gate — writes a 403 and returns if denied.
+//  3. Identity-header injection (X-Forwarded-User, X-User-Groups, X-User-Roles,
+//     plus X-Auth-Request-* when !minimalHeaders).
+//  4. Operator-defined header templates.
+//  5. Security headers (delegated to t.securityHeadersApplier or fallback).
+//  6. OIDC session-cookie strip (stripAuthCookies).
+//  7. Authorization header strip on bearer source when stripAuthorizationHeader.
+//  8. next.ServeHTTP.
+//
+// Session persistence is the CALLER's responsibility — it must happen before
+// this function so Set-Cookie reaches the response.
+// headerTemplateMaxLen bounds the length of a rendered operator-defined header
+// template before it is forwarded downstream. Generous enough for an
+// "Authorization: Bearer <jwt>" value but small enough to reject obviously
+// abusive output. Matches the input-validation default header cap (8KB).
+const headerTemplateMaxLen = 8192
+
+// headerClaimMaxLen returns the maximum accepted length for a claim-derived
+// header value (principal identifier, group, role). Reuses the operator-
+// configured identifier cap (default 256) so a single setting governs both
+// auth paths; falls back to 256 when unset.
+func (t *TraefikOidc) headerClaimMaxLen() int {
+	if t.maxIdentifierLength > 0 {
+		return t.maxIdentifierLength
+	}
+	return 256
+}
+
+// sanitizeHeaderClaimList drops any group/role value that fails claim
+// sanitization (control chars, bidi-override runes, the , ; = delimiters, or an
+// over-long value) and returns the surviving values. Failing closed on a bad
+// entry prevents header injection and stops an embedded comma from injecting
+// extra entries into the comma-joined header. headerName is used only for
+// debug logging — the value is never logged.
+func (t *TraefikOidc) sanitizeHeaderClaimList(values []string, headerName string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+	safe := make([]string, 0, len(values))
+	for _, v := range values {
+		if clean, ok := sanitizeHeaderClaimValue(v, t.headerClaimMaxLen()); ok {
+			safe = append(safe, clean)
+		} else {
+			t.logger.Debugf("Dropping %s entry: value failed claim sanitization", headerName)
+		}
+	}
+	return safe
+}
+
+func (t *TraefikOidc) forwardAuthorized(rw http.ResponseWriter, req *http.Request, p *principal) {
+	var (
+		groups, roles []string
+		extractErr    error
+	)
+	if p.Claims != nil {
+		groups, roles, extractErr = t.extractGroupsAndRolesFromClaims(p.Claims)
+		if extractErr != nil && len(t.allowedRolesAndGroups) > 0 {
+			// Bearer path: 403 (caller already verified the token; principal
+			// claims are present but malformed for roles purposes).
+			// Cookie path can't reach here because processAuthorizedRequest
+			// catches groupClaimsErr earlier.
+			t.logger.Errorf("Failed to extract groups and roles: %v", extractErr)
+			t.sendErrorResponse(rw, req, "Access denied", http.StatusForbidden)
 			return
 		}
-		if err == nil {
-			if len(groups) > 0 {
-				req.Header.Set("X-User-Groups", strings.Join(groups, ","))
+		if extractErr == nil {
+			// Sanitize each group/role before it is joined into a comma-
+			// delimited header. The cookie/session path does not otherwise
+			// sanitize claim-derived values (the bearer path sanitizes its
+			// identifier at construction), so a control char would enable
+			// header injection and an embedded comma would inject extra
+			// entries into the comma-joined header. Fail closed: drop any
+			// value that does not pass.
+			if safeGroups := t.sanitizeHeaderClaimList(groups, "X-User-Groups"); len(safeGroups) > 0 {
+				req.Header.Set("X-User-Groups", strings.Join(safeGroups, ","))
 			}
-			if len(roles) > 0 {
-				req.Header.Set("X-User-Roles", strings.Join(roles, ","))
+			if safeRoles := t.sanitizeHeaderClaimList(roles, "X-User-Roles"); len(safeRoles) > 0 {
+				req.Header.Set("X-User-Roles", strings.Join(safeRoles, ","))
 			}
 		}
 	}
@@ -502,62 +756,73 @@ func (t *TraefikOidc) processAuthorizedRequest(rw http.ResponseWriter, req *http
 			}
 		}
 		if !allowed {
-			t.logger.Infof("User %s does not have any allowed roles or groups", userIdentifier)
+			t.logger.Infof("User %s does not have any allowed roles or groups", p.Identifier)
 			errorMsg := fmt.Sprintf("Access denied: You do not have any of the allowed roles or groups. To log out, visit: %s", t.logoutURLPath)
 			t.sendErrorResponse(rw, req, errorMsg, http.StatusForbidden)
 			return
 		}
 	}
 
-	req.Header.Set("X-Forwarded-User", userIdentifier)
+	// Sanitize the principal identifier before injecting it into headers. The
+	// bearer path already sanitizes its identifier at construction; the
+	// cookie/session path does not, so a claim carrying control chars, bidi-
+	// override runes, or , ; = could inject or spoof header content. Fail
+	// closed: drop the identifier header(s) rather than forward a tainted value.
+	safeIdentifier, identifierOK := sanitizeHeaderClaimValue(p.Identifier, t.headerClaimMaxLen())
+	if identifierOK {
+		req.Header.Set("X-Forwarded-User", safeIdentifier)
+	} else {
+		t.logger.Debugf("Dropping X-Forwarded-User header: identifier failed claim sanitization")
+	}
 
 	// When minimalHeaders is enabled, skip extra headers to prevent 431 errors
 	if !t.minimalHeaders {
 		req.Header.Set("X-Auth-Request-Redirect", req.URL.RequestURI())
-		req.Header.Set("X-Auth-Request-User", userIdentifier)
-		if idToken != "" {
-			req.Header.Set("X-Auth-Request-Token", idToken)
+		if identifierOK {
+			req.Header.Set("X-Auth-Request-User", safeIdentifier)
+		} else {
+			t.logger.Debugf("Dropping X-Auth-Request-User header: identifier failed claim sanitization")
+		}
+		if p.IDToken != "" {
+			req.Header.Set("X-Auth-Request-Token", p.IDToken)
 		}
 	}
 
 	if len(t.headerTemplates) > 0 {
-		if idClaimsErr != nil {
-			t.logger.Errorf("Failed to extract claims from ID Token for template headers: %v", idClaimsErr)
-		} else {
-			// idClaims may be nil when no ID token is present; templates
-			// referencing .Claims.* will simply produce empty values, which
-			// matches the prior behavior.
-			templateData := map[string]interface{}{
-				"AccessToken":  session.GetAccessToken(),
-				"IDToken":      idToken,
-				"RefreshToken": session.GetRefreshToken(),
-				"Claims":       idClaims,
-			}
-
-			for headerName, tmpl := range t.headerTemplates {
-				var buf bytes.Buffer
-				if err := tmpl.Execute(&buf, templateData); err != nil {
-					t.logger.Errorf("Failed to execute template for header %s: %v", headerName, err)
-					continue
-				}
-				headerValue := buf.String()
-				req.Header.Set(headerName, headerValue)
-				t.logger.Debugf("Set templated header %s = %s", headerName, headerValue)
-			}
-			// NOTE: templates only mutate request headers (not session state),
-			// so we deliberately do NOT MarkDirty / Save here. Previously every
-			// authenticated request with header templates re-encrypted and
-			// rewrote all session cookies, which was a measurable CPU and
-			// Set-Cookie tax on dashboards that poll many panels per second.
+		// p.Claims may be nil (e.g. session without an ID token). Templates
+		// referencing .Claims.* will simply produce empty values — matches
+		// the prior behavior. Bearer-source principals always carry access-
+		// token claims (post-verifyToken).
+		templateData := map[string]interface{}{
+			"AccessToken":  p.AccessToken,
+			"IDToken":      p.IDToken,
+			"RefreshToken": p.RefreshToken,
+			"Claims":       p.Claims,
 		}
-	}
 
-	if session.IsDirty() {
-		if err := session.Save(req, rw); err != nil {
-			t.logger.Errorf("Failed to save session after processing headers: %v", err)
+		for headerName, tmpl := range t.headerTemplates {
+			var buf bytes.Buffer
+			if err := tmpl.Execute(&buf, templateData); err != nil {
+				t.logger.Errorf("Failed to execute template for header %s: %v", headerName, err)
+				continue
+			}
+			headerValue := buf.String()
+			// Sanitize the rendered output: template inputs are claim-derived
+			// and attacker-influenceable, so reject control chars (header
+			// injection), bidi-override runes, the , ; = delimiters, and an
+			// over-long value. Fail closed by dropping the header rather than
+			// forwarding a tainted value. Do not log the value (it commonly
+			// carries the access token); log only name + reason.
+			if reason := headerValueReason(headerValue, headerTemplateMaxLen); reason != "" {
+				t.logger.Debugf("Dropping templated header %s: value failed sanitization (%s)", headerName, reason)
+				continue
+			}
+			req.Header.Set(headerName, headerValue)
+			// Do not log the value: templated headers commonly carry the access
+			// token (e.g. "Authorization: Bearer {{.AccessToken}}"), and logging
+			// it — even at debug — leaks credentials into logs.
+			t.logger.Debugf("Set templated header %s (%d bytes)", headerName, len(headerValue))
 		}
-	} else {
-		t.logger.Debug("Session not dirty, skipping save in processAuthorizedRequest")
 	}
 
 	// Apply security headers if configured
@@ -573,7 +838,7 @@ func (t *TraefikOidc) processAuthorizedRequest(rw http.ResponseWriter, req *http
 
 	// Strip OIDC session cookies before forwarding to the backend to prevent
 	// HTTP 431 "Request Header Fields Too Large" errors (GitHub issue #122).
-	if t.stripAuthCookies {
+	if t.stripAuthCookies && t.sessionManager != nil {
 		prefix := t.sessionManager.GetCookiePrefix()
 		filtered := make([]*http.Cookie, 0, len(req.Cookies()))
 		for _, c := range req.Cookies() {
@@ -587,7 +852,14 @@ func (t *TraefikOidc) processAuthorizedRequest(rw http.ResponseWriter, req *http
 		}
 	}
 
-	t.logger.Debugf("Request authorized for user %s, forwarding to next handler", userIdentifier)
+	// Bearer source: strip the Authorization header to keep the raw token
+	// out of downstream service logs. Off-by-config for operators who chain
+	// services that each re-verify the bearer.
+	if p.Source == sourceBearer && t.stripAuthorizationHeader {
+		req.Header.Del("Authorization")
+	}
+
+	t.logger.Debugf("Request authorized for user %s (source=%d), forwarding to next handler", p.Identifier, p.Source)
 
 	t.next.ServeHTTP(rw, req)
 }

middleware_edge_cases_test.go

@@ -13,8 +13,8 @@ func TestMiddlewareContextCancellation(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}), // Never close to simulate waiting
 		sessionManager:         createTestSessionManager(t),
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 	}
 
 	// Create request with canceled context
@@ -39,8 +39,8 @@ func TestMiddlewareSessionErrorRecovery(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}),
 		sessionManager:         createTestSessionManager(t),
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 		issuerURL:              "https://provider.example.com",
 		redirURLPath:           "/callback",
 		logoutURLPath:          "/logout",
@@ -73,8 +73,8 @@ func TestMiddlewareAJAXRequestHandling(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}),
 		sessionManager:         createTestSessionManager(t),
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 		issuerURL:              "https://provider.example.com",
 		redirURLPath:           "/callback",
 		logoutURLPath:          "/logout",
@@ -102,8 +102,8 @@ func TestLogoutWorksWithoutOIDCInitialization(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}), // Never close to simulate provider unavailable
 		sessionManager:         createTestSessionManager(t),
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 		logoutURLPath:          "/logout",
 		postLogoutRedirectURI:  "/",
 		forceHTTPS:             false,
@@ -142,8 +142,8 @@ func TestMiddlewareDomainRestrictions(t *testing.T) {
 			logger:         NewLogger("debug"),
 			initComplete:   make(chan struct{}),
 			sessionManager: sessionManager,
-			firstRequestReceived:   true,
-			metadataRefreshStarted: true,
+			firstRequestStarted: 1,
+			metadataRefreshStartedAtomic: 1,
 			issuerURL:      "https://provider.example.com",
 			redirURLPath:   "/callback",
 			logoutURLPath:  "/logout",
@@ -187,8 +187,8 @@ func TestMiddlewareDomainRestrictions(t *testing.T) {
 			logger:                 NewLogger("debug"),
 			initComplete:           make(chan struct{}),
 			sessionManager:         sessionManager,
-			firstRequestReceived:   true,
-			metadataRefreshStarted: true,
+			firstRequestStarted: 1,
+			metadataRefreshStartedAtomic: 1,
 			issuerURL:              "https://provider.example.com",
 			redirURLPath:           "/callback",
 			logoutURLPath:          "/logout",
@@ -236,8 +236,8 @@ func TestMiddlewareOpaqueTokenHandling(t *testing.T) {
 		logger:                 NewLogger("debug"),
 		initComplete:           make(chan struct{}),
 		sessionManager:         sessionManager,
-		firstRequestReceived:   true,
-		metadataRefreshStarted: true,
+		firstRequestStarted: 1,
+		metadataRefreshStartedAtomic: 1,
 		issuerURL:              "https://provider.example.com",
 		redirURLPath:           "/callback",
 		logoutURLPath:          "/logout",

principal.go

@@ -0,0 +1,58 @@
+// Package traefikoidc — principal abstraction for the shared post-auth
+// pipeline. A principal carries the resolved identity + tokens + claims
+// produced by EITHER the cookie session path or the bearer-token path, so
+// downstream header injection / roles checks / forwarding can be implemented
+// once and reused.
+package traefikoidc
+
+// principalSource indicates which auth path produced a principal. Used by
+// forwardAuthorized to decide source-specific behavior (e.g. only strip the
+// Authorization header for bearer-source principals).
+type principalSource int
+
+const (
+	sourceSession principalSource = iota
+	sourceBearer
+)
+
+// principal is the immutable post-auth value passed to forwardAuthorized.
+// No methods mutate it; no manager pointer; no I/O. Pure data.
+type principal struct {
+	Claims       map[string]interface{}
+	Identifier   string
+	Subject      string
+	ClientID     string
+	AccessToken  string
+	IDToken      string
+	RefreshToken string
+	Source       principalSource
+}
+
+// buildPrincipalFromSession adapts an authenticated SessionData into a
+// principal value WITHOUT writing back to the session. This is the only
+// function that still knows about SessionData; the rest of the pipeline is
+// session-agnostic. Returns nil when the session has no usable identity.
+func (t *TraefikOidc) buildPrincipalFromSession(session *SessionData) *principal {
+	if session == nil {
+		return nil
+	}
+	identifier := session.GetUserIdentifier()
+	if identifier == "" {
+		return nil
+	}
+
+	var claims map[string]interface{}
+	if idToken := session.GetIDToken(); idToken != "" && t.extractClaimsFunc != nil {
+		// Best-effort: cached on the session, never blocking.
+		claims, _ = session.GetIDTokenClaims(t.extractClaimsFunc) // Safe to ignore: claims-error path handled by header-template branch
+	}
+
+	return &principal{
+		Source:       sourceSession,
+		Identifier:   identifier,
+		AccessToken:  session.GetAccessToken(),
+		IDToken:      session.GetIDToken(),
+		RefreshToken: session.GetRefreshToken(),
+		Claims:       claims,
+	}
+}

refresh_coordinator.go

@@ -15,18 +15,28 @@ import (
 // It implements request coalescing, rate limiting, and circuit breaking
 // specifically for token refresh operations.
 type RefreshCoordinator struct {
-	inFlightRefreshes      map[string]*refreshOperation
-	cleanupTimers          map[string]*time.Timer
-	sessionRefreshAttempts map[string]*refreshAttemptTracker
+	// inFlightRefreshes maps tokenHash -> *refreshOperation. sync.Map is used
+	// instead of a plain map + RWMutex so concurrent refreshes do not
+	// serialize on a single global lock. Under Yaegi the previous
+	// refreshMutex.Lock() was held for tens of milliseconds per request due
+	// to interpreter overhead on the work inside the critical section,
+	// causing dozens of goroutines to stack up on it and pin one CPU core.
+	inFlightRefreshes sync.Map
+	// sessionRefreshAttempts maps sessionID -> *refreshAttemptTracker.
+	// sync.Map + atomic tracker fields means isInCooldown/recordRefreshAttempt/
+	// recordRefreshSuccess/recordRefreshFailure are lock-free. Previously
+	// these used attemptsMutex sync.RWMutex; under Yaegi every Lock() acquisition
+	// adds 10-50ms of dispatch overhead, and they were called twice per leader
+	// request (once for recordRefreshAttempt, once for isInCooldown). That
+	// serializing pattern caused the v1.0.15 death spiral after v1.0.14
+	// removed the refreshMutex (same architectural shape, different mutex).
+	sessionRefreshAttempts sync.Map
 	circuitBreaker         *RefreshCircuitBreaker
 	metrics                *RefreshMetrics
 	logger                 *Logger
 	stopChan               chan struct{}
 	config                 RefreshCoordinatorConfig
 	wg                     sync.WaitGroup
-	attemptsMutex          sync.RWMutex
-	refreshMutex           sync.RWMutex
-	cleanupTimerMu         sync.Mutex
 }
 
 // RefreshCoordinatorConfig configures the refresh coordinator behavior
@@ -84,14 +94,46 @@ type refreshResult struct {
 	fromCache     bool
 }
 
-// refreshAttemptTracker tracks refresh attempts for a session
-type refreshAttemptTracker struct {
-	lastAttemptTime     time.Time
-	windowStartTime     time.Time
-	cooldownEndTime     time.Time
+// attemptState is the immutable snapshot of a session's refresh-attempt
+// state. Lives behind refreshAttemptTracker.state (atomic.Value). Every
+// transition (record, success, failure, window-reset, cooldown-enter,
+// cooldown-exit) constructs a fresh attemptState and publishes it via
+// CompareAndSwap so the entire field set is updated together.
+//
+// Per-field atomic.Load/Store (the previous v1.0.15 design) had a benign
+// but observable hazard: the cooldown-exit reset wrote cooldownEndNano = 0
+// first, then separately stored attempts = 1 and windowStartNano = now.
+// A concurrent isInCooldown call could see cooldownEndNano = 0 (reset
+// just completed) with attempts still at MaxRefreshAttempts, triggering
+// a fresh cooldown immediately. The snapshot approach eliminates the
+// intermediate state entirely.
+type attemptState struct {
+	lastAttemptNano     int64 // UnixNano of last attempt
+	windowStartNano     int64 // UnixNano of attempt-window start
+	cooldownEndNano     int64 // UnixNano; 0 = not in cooldown
 	attempts            int32
 	consecutiveFailures int32
-	inCooldown          bool
+}
+
+// refreshAttemptTracker tracks refresh attempts for a session via a single
+// atomic.Value holding a *attemptState pointer. Readers do exactly one Load.
+// Writers do Load → construct new → CompareAndSwap (retry on conflict).
+// Under Yaegi this collapses 3-4 per-field atomic dispatches into one Load,
+// and eliminates the cross-field race in the window-reset path.
+type refreshAttemptTracker struct {
+	state atomic.Value // *attemptState
+}
+
+// stateOf returns the current attemptState, or a zero-value snapshot if none
+// has been published yet. The empty snapshot represents "no attempts recorded".
+func (t *refreshAttemptTracker) stateOf() *attemptState {
+	if v := t.state.Load(); v != nil {
+		s, _ := v.(*attemptState)
+		if s != nil {
+			return s
+		}
+	}
+	return &attemptState{}
 }
 
 // RefreshMetrics tracks coordinator performance metrics
@@ -106,14 +148,18 @@ type RefreshMetrics struct {
 	currentInFlightRefreshes int32
 }
 
-// RefreshCircuitBreaker implements a circuit breaker specifically for refresh operations
+// RefreshCircuitBreaker implements a circuit breaker specifically for refresh
+// operations. All mutable fields are atomic so AllowRequest/RecordSuccess/
+// RecordFailure run without any mutex. The previous sync.RWMutex.RLock() was
+// taken on every CoordinateRefresh — under Yaegi this added 10-50ms of
+// interpreter dispatch per call, which compounded with attemptsMutex to keep
+// the pod's single CPU core saturated.
 type RefreshCircuitBreaker struct {
-	lastFailureTime time.Time
-	lastSuccessTime time.Time
+	lastFailureNano int64 // atomic, UnixNano of most recent failure
+	lastSuccessNano int64 // atomic, UnixNano of most recent success
 	config          RefreshCircuitBreakerConfig
-	mutex           sync.RWMutex
-	state           int32
-	failures        int32
+	state           int32 // atomic: 0=closed, 1=open, 2=half-open
+	failures        int32 // atomic
 }
 
 // RefreshCircuitBreakerConfig configures the refresh circuit breaker
@@ -130,13 +176,12 @@ func NewRefreshCoordinator(config RefreshCoordinatorConfig, logger *Logger) *Ref
 	}
 
 	rc := &RefreshCoordinator{
-		inFlightRefreshes:      make(map[string]*refreshOperation),
-		sessionRefreshAttempts: make(map[string]*refreshAttemptTracker),
-		config:                 config,
-		metrics:                &RefreshMetrics{},
-		logger:                 logger,
-		stopChan:               make(chan struct{}),
-		cleanupTimers:          make(map[string]*time.Timer),
+		// inFlightRefreshes and sessionRefreshAttempts are both sync.Map;
+		// their zero values are ready to use.
+		config:        config,
+		metrics:  &RefreshMetrics{},
+		logger:   logger,
+		stopChan: make(chan struct{}),
 		circuitBreaker: &RefreshCircuitBreaker{
 			config: RefreshCircuitBreakerConfig{
 				MaxFailures:      3,
@@ -227,13 +272,28 @@ func (rc *RefreshCoordinator) getOrCreateOperation(
 	tokenHash string,
 	refreshToken string,
 ) (*refreshOperation, bool, error) {
-	rc.refreshMutex.Lock()
-	defer rc.refreshMutex.Unlock()
+	// Speculatively construct the operation we WOULD register if we win the
+	// race. Allocating here keeps the LoadOrStore call below atomic and
+	// avoids any global lock — under Yaegi the previous map+RWMutex design
+	// held the write lock long enough (tens of ms per call) that concurrent
+	// refreshes on the same coordinator serialized into a queue that grew
+	// without bound. See struct comment on inFlightRefreshes.
+	candidate := &refreshOperation{
+		refreshToken: refreshToken,
+		done:         make(chan struct{}),
+		startTime:    time.Now(),
+		waiterCount:  1,
+	}
 
-	// Check for existing operation while holding the lock
-	if existingOp, exists := rc.inFlightRefreshes[tokenHash]; exists {
+	if existing, loaded := rc.inFlightRefreshes.LoadOrStore(tokenHash, candidate); loaded {
+		existingOp, ok := existing.(*refreshOperation)
+		if !ok {
+			// Defensive: anything stored here is always *refreshOperation, but
+			// keep the typed assert so a programming error elsewhere doesn't
+			// surface as a confusing panic in an interpreter frame.
+			return nil, false, fmt.Errorf("inFlightRefreshes corrupt: unexpected type %T", existing)
+		}
 		if existingOp.refreshToken == refreshToken {
-			// Join existing operation
 			atomic.AddInt32(&existingOp.waiterCount, 1)
 			return existingOp, false, nil
 		}
@@ -241,41 +301,71 @@ func (rc *RefreshCoordinator) getOrCreateOperation(
 		return nil, false, fmt.Errorf("refresh token mismatch")
 	}
 
-	// No existing operation - check if we can create a new one
-	// All checks happen while holding the lock to prevent races
+	// We won the race and registered `candidate`. Apply gates now. If any
+	// gate fails we must remove our entry from the map and signal failure
+	// to any joiners that snuck in between LoadOrStore and now.
+	if err := rc.applyLeaderGates(sessionID); err != nil {
+		rc.failCandidate(tokenHash, candidate, err)
+		return nil, false, err
+	}
 
-	// Check and record refresh attempt for rate limiting
-	rc.recordRefreshAttempt(sessionID)
+	// Reserve concurrent slot via ticket-and-return: increment optimistically,
+	// decrement if we overshot the limit. The previous CAS-loop allowed a
+	// transient overshoot of up to N-1 leaders when several goroutines all
+	// observed `current < max` in the same scheduling slice before any one
+	// of them succeeded their CAS — visible to readers as
+	// currentInFlightRefreshes > MaxConcurrentRefreshes for a brief window.
+	// The ticket pattern is strictly bounded: the counter momentarily reads
+	// max+k for k concurrent attempts past the limit, but only the k that
+	// produced max+1..max+k decrement back, and only k=1 ever observes max+1
+	// as committed.
+	newCount := atomic.AddInt32(&rc.metrics.currentInFlightRefreshes, 1)
+	if int(newCount) > rc.config.MaxConcurrentRefreshes {
+		atomic.AddInt32(&rc.metrics.currentInFlightRefreshes, -1)
+		err := fmt.Errorf("maximum concurrent refresh operations reached")
+		rc.failCandidate(tokenHash, candidate, err)
+		return nil, false, err
+	}
+
+	return candidate, true, nil
+}
+
+// applyLeaderGates runs the rate-limit, cooldown, and memory-pressure checks
+// that previously ran under the global refreshMutex. Only the leader (the
+// goroutine that just registered the operation) runs them; joiners share the
+// leader's outcome via operation.done.
+func (rc *RefreshCoordinator) applyLeaderGates(sessionID string) error {
+	// Cooldown check FIRST, BEFORE incrementing the attempt counter.
+	// Previously this function recorded the attempt and then read the
+	// cooldown state. Under burst load (many concurrent leaders with
+	// different token hashes but same session) every goroutine could
+	// increment past MaxRefreshAttempts before any one of them observed
+	// the threshold, so the cooldown gate fired too late — the same
+	// thundering-herd shape that drove v1.0.14 into the ground.
 	if rc.isInCooldown(sessionID) {
 		atomic.AddInt64(&rc.metrics.cooldownsTriggered, 1)
-		return nil, false, fmt.Errorf("refresh attempts exceeded for session, in cooldown period")
+		return fmt.Errorf("refresh attempts exceeded for session, in cooldown period")
 	}
-
-	// Check memory pressure
 	if rc.config.EnableMemoryPressureDetection && rc.isUnderMemoryPressure() {
 		atomic.AddInt64(&rc.metrics.memoryPressureEvents, 1)
-		return nil, false, fmt.Errorf("system under memory pressure, refresh denied")
+		return fmt.Errorf("system under memory pressure, refresh denied")
 	}
+	// Only count attempts that actually progress past the gates.
+	rc.recordRefreshAttempt(sessionID)
+	return nil
+}
 
-	// Check and reserve concurrent refresh slot atomically
-	current := atomic.LoadInt32(&rc.metrics.currentInFlightRefreshes)
-	if int(current) >= rc.config.MaxConcurrentRefreshes {
-		return nil, false, fmt.Errorf("maximum concurrent refresh operations reached")
-	}
-
-	// Reserve the slot - we're still holding the lock so this is safe
-	atomic.AddInt32(&rc.metrics.currentInFlightRefreshes, 1)
-
-	// Create and register new operation
-	operation := &refreshOperation{
-		refreshToken: refreshToken,
-		done:         make(chan struct{}),
-		startTime:    time.Now(),
-		waiterCount:  1,
-	}
-	rc.inFlightRefreshes[tokenHash] = operation
-
-	return operation, true, nil
+// failCandidate removes the leader's just-registered operation from the
+// in-flight map and signals the error to any joiners by recording the result
+// and closing the done channel. This keeps the (nil, false, err) return path
+// equivalent to the pre-sync.Map version: callers see the error directly,
+// joiners see it via operation.done.
+func (rc *RefreshCoordinator) failCandidate(tokenHash string, op *refreshOperation, err error) {
+	rc.inFlightRefreshes.Delete(tokenHash)
+	op.mutex.Lock()
+	op.result = &refreshResult{err: err}
+	op.mutex.Unlock()
+	close(op.done)
 }
 
 // executeRefreshAsync performs the actual refresh operation asynchronously
@@ -338,130 +428,196 @@ func (rc *RefreshCoordinator) executeRefreshAsync(
 	}
 }
 
-// scheduleDelayedCleanup schedules a cleanup using a timer instead of spawning a goroutine
-// This prevents goroutine explosion under high load (500+ req/sec)
+// scheduleDelayedCleanup schedules a cleanup using a timer instead of spawning
+// a goroutine — time.AfterFunc uses the runtime's timer heap and never spawns
+// a per-timer goroutine until the callback actually fires.
+//
+// The previous implementation tracked every pending timer in a map guarded by
+// cleanupTimerMu so a duplicate scheduling could cancel the prior timer. That
+// "shouldn't happen" path was the only consumer of the map, but the mutex
+// fired on every successful refresh completion — yet another per-request
+// Yaegi-dispatched lock acquisition. performCleanup is already idempotent
+// (LoadAndDelete on the sync.Map), so a duplicate scheduling at worst fires
+// performCleanup twice; the second call is a no-op. Dropping the map removes
+// the whole class of contention on this code path.
 func (rc *RefreshCoordinator) scheduleDelayedCleanup(tokenHash string) {
 	delay := rc.config.DeduplicationCleanupDelay
 	if delay <= 0 {
-		// Immediate cleanup
 		rc.performCleanup(tokenHash)
 		return
 	}
-
-	// Use time.AfterFunc which is more efficient than spawning a goroutine with Sleep
-	// time.AfterFunc uses the runtime's timer heap which is much more efficient
-	rc.cleanupTimerMu.Lock()
-	// Cancel any existing timer for this hash (shouldn't happen, but just in case)
-	if existingTimer, exists := rc.cleanupTimers[tokenHash]; exists {
-		existingTimer.Stop()
-	}
-	rc.cleanupTimers[tokenHash] = time.AfterFunc(delay, func() {
-		rc.performCleanup(tokenHash)
-		// Remove timer from map
-		rc.cleanupTimerMu.Lock()
-		delete(rc.cleanupTimers, tokenHash)
-		rc.cleanupTimerMu.Unlock()
-	})
-	rc.cleanupTimerMu.Unlock()
+	time.AfterFunc(delay, func() { rc.performCleanup(tokenHash) })
 }
 
 // performCleanup removes the operation from the in-flight map.
 // Idempotent: only decrements the in-flight counter if an entry was actually
-// removed. This guards against any future path accidentally calling cleanup
-// twice for the same tokenHash (which would corrupt the refresh budget).
+// removed. LoadAndDelete is atomic so any concurrent failCandidate or repeat
+// cleanup call will see exactly one removal — the budget cannot be corrupted
+// by double-decrement.
 func (rc *RefreshCoordinator) performCleanup(tokenHash string) {
-	rc.refreshMutex.Lock()
-	_, existed := rc.inFlightRefreshes[tokenHash]
-	if existed {
-		delete(rc.inFlightRefreshes, tokenHash)
-	}
-	rc.refreshMutex.Unlock()
-	if existed {
+	if _, existed := rc.inFlightRefreshes.LoadAndDelete(tokenHash); existed {
 		atomic.AddInt32(&rc.metrics.currentInFlightRefreshes, -1)
 	}
 }
 
-// isInCooldown checks if a session is in cooldown after recording an attempt
-func (rc *RefreshCoordinator) isInCooldown(sessionID string) bool {
-	rc.attemptsMutex.Lock()
-	defer rc.attemptsMutex.Unlock()
+// getOrCreateTracker fetches the tracker for sessionID or atomically creates a
+// fresh one. The sync.Map.LoadOrStore semantics make this lock-free even under
+// concurrent first-touch races: at most one tracker per sessionID survives.
+//
+// trackerFromMapValue centralizes the type assertion so the lint-mandated
+// two-value form lives in one place; the stored type is always
+// *refreshAttemptTracker by construction.
+func trackerFromMapValue(v interface{}) *refreshAttemptTracker {
+	t, _ := v.(*refreshAttemptTracker)
+	return t
+}
 
-	tracker, exists := rc.sessionRefreshAttempts[sessionID]
-	if !exists {
+func (rc *RefreshCoordinator) getOrCreateTracker(sessionID string) *refreshAttemptTracker {
+	if v, ok := rc.sessionRefreshAttempts.Load(sessionID); ok {
+		return trackerFromMapValue(v)
+	}
+	fresh := &refreshAttemptTracker{}
+	fresh.state.Store(&attemptState{windowStartNano: time.Now().UnixNano()})
+	actual, _ := rc.sessionRefreshAttempts.LoadOrStore(sessionID, fresh)
+	return trackerFromMapValue(actual)
+}
+
+// mutateState performs a CompareAndSwap loop that applies mutate to the
+// current snapshot. mutate must be PURE: it receives an immutable view of
+// the current state and returns a fresh *attemptState. If mutate returns nil
+// the update is skipped (used by isInCooldown for "no change needed" paths).
+//
+// Retries on CAS conflict are bounded by the number of concurrent writers —
+// in practice 1-3. Under Yaegi each retry pays the dispatch cost of one Load
+// + one CompareAndSwap; still cheaper than the previous per-field atomic
+// sequence and immune to the cross-field race the v1.0.15 design had.
+func (t *refreshAttemptTracker) mutateState(mutate func(cur *attemptState) *attemptState) *attemptState {
+	for {
+		cur := t.stateOf()
+		next := mutate(cur)
+		if next == nil {
+			return cur
+		}
+		if t.state.CompareAndSwap(cur, next) {
+			return next
+		}
+	}
+}
+
+// isInCooldown checks if a session is in cooldown. Snapshot-based: every
+// transition publishes a fresh *attemptState atomically so readers never see
+// a partially-updated state. The previous per-field atomic design had a
+// benign race in the cooldown-exit path (cooldownEndNano reset before
+// attempts reset) that could double-trigger cooldown.
+func (rc *RefreshCoordinator) isInCooldown(sessionID string) bool {
+	v, ok := rc.sessionRefreshAttempts.Load(sessionID)
+	if !ok {
 		return false // No tracker means first attempt, not in cooldown
 	}
-
+	tracker := trackerFromMapValue(v)
 	now := time.Now()
+	nowNano := now.UnixNano()
+	maxAttempts := rc.config.MaxRefreshAttempts
+	window := rc.config.RefreshAttemptWindow
+	cooldownPeriod := rc.config.RefreshCooldownPeriod
 
-	// Check if already in cooldown
-	if tracker.inCooldown {
-		if now.After(tracker.cooldownEndTime) {
-			// Cooldown expired, reset tracker
-			tracker.inCooldown = false
-			tracker.attempts = 1 // Already recorded one attempt
-			tracker.consecutiveFailures = 0
-			tracker.windowStartTime = now
-			return false
+	cur := tracker.stateOf()
+
+	// Already in cooldown?
+	if cur.cooldownEndNano != 0 {
+		if nowNano <= cur.cooldownEndNano {
+			return true // still in cooldown
 		}
-		return true // Still in cooldown
-	}
-
-	// Check if window expired
-	if now.Sub(tracker.windowStartTime) > rc.config.RefreshAttemptWindow {
-		// Reset window
-		tracker.attempts = 1 // Already recorded one attempt
-		tracker.windowStartTime = now
+		// Cooldown expired: atomically publish a fresh state with the window
+		// restarted from one attempt. Whichever goroutine wins the CAS sets
+		// the new snapshot; losers see it via the next stateOf load.
+		tracker.mutateState(func(s *attemptState) *attemptState {
+			if s.cooldownEndNano == 0 || nowNano <= s.cooldownEndNano {
+				return nil // someone else already reset, or back in cooldown
+			}
+			return &attemptState{
+				windowStartNano: nowNano,
+				attempts:        1,
+			}
+		})
 		return false
 	}
 
-	// Check if just exceeded attempt limit
-	if int(tracker.attempts) >= rc.config.MaxRefreshAttempts {
-		// Enter cooldown now
-		tracker.inCooldown = true
-		tracker.cooldownEndTime = now.Add(rc.config.RefreshCooldownPeriod)
-		rc.logger.Infof("Session %s entering refresh cooldown after %d attempts",
-			sessionID, tracker.attempts)
+	// Window expired?
+	if time.Duration(nowNano-cur.windowStartNano) > window {
+		tracker.mutateState(func(s *attemptState) *attemptState {
+			if time.Duration(nowNano-s.windowStartNano) <= window {
+				return nil
+			}
+			next := *s
+			next.windowStartNano = nowNano
+			next.attempts = 1
+			return &next
+		})
+		return false
+	}
+
+	// Just exceeded attempt limit?
+	if int(cur.attempts) >= maxAttempts {
+		end := now.Add(cooldownPeriod).UnixNano()
+		published := tracker.mutateState(func(s *attemptState) *attemptState {
+			if s.cooldownEndNano != 0 {
+				return nil
+			}
+			next := *s
+			next.cooldownEndNano = end
+			return &next
+		})
+		if published.cooldownEndNano == end {
+			rc.logger.Infof("Session %s entering refresh cooldown after %d attempts",
+				sessionID, published.attempts)
+		}
 		return true
 	}
 
 	return false
 }
 
-// recordRefreshAttempt records a refresh attempt for rate limiting
+// recordRefreshAttempt records a refresh attempt for rate limiting. Lock-free
+// snapshot mutation; attempts and lastAttemptNano are advanced atomically.
 func (rc *RefreshCoordinator) recordRefreshAttempt(sessionID string) {
-	rc.attemptsMutex.Lock()
-	defer rc.attemptsMutex.Unlock()
-
-	tracker, exists := rc.sessionRefreshAttempts[sessionID]
-	if !exists {
-		tracker = &refreshAttemptTracker{
-			windowStartTime: time.Now(),
-		}
-		rc.sessionRefreshAttempts[sessionID] = tracker
-	}
-
-	atomic.AddInt32(&tracker.attempts, 1)
-	tracker.lastAttemptTime = time.Now()
+	tracker := rc.getOrCreateTracker(sessionID)
+	nowNano := time.Now().UnixNano()
+	tracker.mutateState(func(s *attemptState) *attemptState {
+		next := *s
+		next.attempts++
+		next.lastAttemptNano = nowNano
+		return &next
+	})
 }
 
-// recordRefreshSuccess records a successful refresh
+// recordRefreshSuccess records a successful refresh: zero consecutiveFailures.
 func (rc *RefreshCoordinator) recordRefreshSuccess(sessionID string) {
-	rc.attemptsMutex.Lock()
-	defer rc.attemptsMutex.Unlock()
-
-	if tracker, exists := rc.sessionRefreshAttempts[sessionID]; exists {
-		tracker.consecutiveFailures = 0
+	v, ok := rc.sessionRefreshAttempts.Load(sessionID)
+	if !ok {
+		return
 	}
+	trackerFromMapValue(v).mutateState(func(s *attemptState) *attemptState {
+		if s.consecutiveFailures == 0 {
+			return nil
+		}
+		next := *s
+		next.consecutiveFailures = 0
+		return &next
+	})
 }
 
-// recordRefreshFailure records a failed refresh
+// recordRefreshFailure records a failed refresh: increments consecutiveFailures.
 func (rc *RefreshCoordinator) recordRefreshFailure(sessionID string) {
-	rc.attemptsMutex.Lock()
-	defer rc.attemptsMutex.Unlock()
-
-	if tracker, exists := rc.sessionRefreshAttempts[sessionID]; exists {
-		atomic.AddInt32(&tracker.consecutiveFailures, 1)
+	v, ok := rc.sessionRefreshAttempts.Load(sessionID)
+	if !ok {
+		return
 	}
+	trackerFromMapValue(v).mutateState(func(s *attemptState) *attemptState {
+		next := *s
+		next.consecutiveFailures++
+		return &next
+	})
 }
 
 // hashRefreshToken creates a hash of the refresh token for deduplication
@@ -512,20 +668,22 @@ func (rc *RefreshCoordinator) cleanupRoutine() {
 	}
 }
 
-// cleanupStaleEntries removes outdated tracking entries
+// cleanupStaleEntries removes outdated tracking entries. Lock-free iteration
+// via sync.Map.Range; safe to race with concurrent reads/writes.
 func (rc *RefreshCoordinator) cleanupStaleEntries() {
-	now := time.Now()
-
-	rc.attemptsMutex.Lock()
-	defer rc.attemptsMutex.Unlock()
-
-	// Clean up old session trackers
-	for sessionID, tracker := range rc.sessionRefreshAttempts {
-		// Remove trackers that haven't been used recently
-		if now.Sub(tracker.lastAttemptTime) > 2*rc.config.RefreshAttemptWindow {
-			delete(rc.sessionRefreshAttempts, sessionID)
+	cutoff := time.Now().Add(-2 * rc.config.RefreshAttemptWindow).UnixNano()
+	rc.sessionRefreshAttempts.Range(func(key, value interface{}) bool {
+		tracker := trackerFromMapValue(value)
+		if tracker == nil {
+			return true
 		}
-	}
+		if tracker.stateOf().lastAttemptNano < cutoff {
+			// Compare-and-delete to avoid evicting a tracker that was just
+			// re-used by a concurrent caller. We compare by pointer identity.
+			rc.sessionRefreshAttempts.CompareAndDelete(key, value)
+		}
+		return true
+	})
 }
 
 // GetMetrics returns current coordinator metrics
@@ -543,78 +701,60 @@ func (rc *RefreshCoordinator) GetMetrics() map[string]interface{} {
 	}
 }
 
-// Shutdown gracefully shuts down the coordinator
+// Shutdown gracefully shuts down the coordinator. Pending delayed-cleanup
+// timers are NOT canceled explicitly: time.AfterFunc callbacks are tiny
+// (one map LoadAndDelete) and harmless after Shutdown — sync.Map operations
+// remain safe on an unused coordinator until GC.
 func (rc *RefreshCoordinator) Shutdown() {
 	close(rc.stopChan)
-
-	// Cancel all pending cleanup timers
-	rc.cleanupTimerMu.Lock()
-	for _, timer := range rc.cleanupTimers {
-		timer.Stop()
-	}
-	rc.cleanupTimers = make(map[string]*time.Timer)
-	rc.cleanupTimerMu.Unlock()
-
 	rc.wg.Wait()
 }
 
-// AllowRequest checks if the circuit breaker allows a request
+// AllowRequest reports whether the circuit breaker allows a request. Lock-free.
 func (cb *RefreshCircuitBreaker) AllowRequest() bool {
-	cb.mutex.RLock()
-	defer cb.mutex.RUnlock()
-
-	state := atomic.LoadInt32(&cb.state)
-
-	switch state {
-	case 0: // Closed
+	switch atomic.LoadInt32(&cb.state) {
+	case 0: // closed
 		return true
-	case 1: // Open
-		if time.Since(cb.lastFailureTime) > cb.config.OpenDuration {
-			// Try to transition to half-open
+	case 1: // open
+		lastFail := atomic.LoadInt64(&cb.lastFailureNano)
+		if time.Duration(time.Now().UnixNano()-lastFail) > cb.config.OpenDuration {
+			// Transition to half-open; first CAS winner gets the probe.
 			if atomic.CompareAndSwapInt32(&cb.state, 1, 2) {
 				return true
 			}
 		}
 		return false
-	case 2: // Half-open
+	case 2: // half-open
 		return true
 	default:
 		return false
 	}
 }
 
-// RecordSuccess records a successful operation
+// RecordSuccess records a successful operation. Lock-free.
 func (cb *RefreshCircuitBreaker) RecordSuccess() {
-	cb.mutex.Lock()
-	defer cb.mutex.Unlock()
-
-	state := atomic.LoadInt32(&cb.state)
-	if state == 2 { // Half-open
-		// Close the circuit
+	switch atomic.LoadInt32(&cb.state) {
+	case 2: // half-open -> close
 		atomic.StoreInt32(&cb.state, 0)
 		atomic.StoreInt32(&cb.failures, 0)
-	} else if state == 0 { // Closed
-		// Reset failure count on success
+	case 0: // closed
 		atomic.StoreInt32(&cb.failures, 0)
 	}
-	cb.lastSuccessTime = time.Now()
+	atomic.StoreInt64(&cb.lastSuccessNano, time.Now().UnixNano())
 }
 
-// RecordFailure records a failed operation
+// RecordFailure records a failed operation. Lock-free.
 func (cb *RefreshCircuitBreaker) RecordFailure() {
-	cb.mutex.Lock()
-	defer cb.mutex.Unlock()
-
 	failures := atomic.AddInt32(&cb.failures, 1)
-	cb.lastFailureTime = time.Now()
+	atomic.StoreInt64(&cb.lastFailureNano, time.Now().UnixNano())
 
-	state := atomic.LoadInt32(&cb.state)
-
-	if state == 0 && int(failures) >= cb.config.MaxFailures {
-		// Open the circuit
-		atomic.StoreInt32(&cb.state, 1)
-	} else if state == 2 {
-		// Half-open failed, return to open
+	switch atomic.LoadInt32(&cb.state) {
+	case 0:
+		if int(failures) >= cb.config.MaxFailures {
+			atomic.StoreInt32(&cb.state, 1)
+		}
+	case 2:
+		// Half-open probe failed -> back to open.
 		atomic.StoreInt32(&cb.state, 1)
 	}
 }

refresh_coordinator_test.go

@@ -165,9 +165,14 @@ func TestRefreshRateLimiting(t *testing.T) {
 		time.Sleep(150 * time.Millisecond)
 	}
 
-	// Verify that cooldown was triggered after max attempts
-	// With the new logic, the Nth attempt triggers cooldown, so we get N-1 successful attempts
-	expectedSuccessfulAttempts := config.MaxRefreshAttempts - 1
+	// Verify that cooldown was triggered after max attempts.
+	// With applyLeaderGates checking cooldown BEFORE recording the attempt
+	// (the v1.0.16 reorder fixing the thundering-herd off-by-one), N attempts
+	// run to completion and the (N+1)th is denied. Previously the Nth was
+	// denied as it tried to record, which under burst load let multiple
+	// concurrent leaders increment past the limit before any one of them
+	// observed the gate.
+	expectedSuccessfulAttempts := config.MaxRefreshAttempts
 	if attempts != expectedSuccessfulAttempts {
 		t.Errorf("Expected %d successful attempts before cooldown, got %d", expectedSuccessfulAttempts, attempts)
 	}
@@ -365,10 +370,12 @@ func TestMemoryLeakPrevention(t *testing.T) {
 		}
 	}
 
-	// Verify cleanup is working
-	coordinator.attemptsMutex.RLock()
-	sessionCount := len(coordinator.sessionRefreshAttempts)
-	coordinator.attemptsMutex.RUnlock()
+	// Verify cleanup is working. sync.Map has no Len(); count via Range.
+	sessionCount := 0
+	coordinator.sessionRefreshAttempts.Range(func(_, _ interface{}) bool {
+		sessionCount++
+		return true
+	})
 
 	// Should have cleaned up old sessions (only recent ones remain)
 	if sessionCount > numWorkers*2 {
@@ -650,24 +657,23 @@ func TestCleanupRoutine(t *testing.T) {
 		coordinator.recordRefreshAttempt(fmt.Sprintf("session_%d", i))
 	}
 
-	// Verify sessions exist
-	coordinator.attemptsMutex.RLock()
-	initialCount := len(coordinator.sessionRefreshAttempts)
-	coordinator.attemptsMutex.RUnlock()
+	countSessions := func() int {
+		n := 0
+		coordinator.sessionRefreshAttempts.Range(func(_, _ interface{}) bool {
+			n++
+			return true
+		})
+		return n
+	}
 
-	if initialCount != 5 {
+	if initialCount := countSessions(); initialCount != 5 {
 		t.Errorf("Expected 5 sessions, got %d", initialCount)
 	}
 
 	// Wait for cleanup to run (2x window + cleanup interval)
 	time.Sleep(2*config.RefreshAttemptWindow + 2*config.CleanupInterval)
 
-	// Verify sessions were cleaned up
-	coordinator.attemptsMutex.RLock()
-	finalCount := len(coordinator.sessionRefreshAttempts)
-	coordinator.attemptsMutex.RUnlock()
-
-	if finalCount != 0 {
+	if finalCount := countSessions(); finalCount != 0 {
 		t.Errorf("Expected 0 sessions after cleanup, got %d", finalCount)
 	}
 }
@@ -720,11 +726,9 @@ func TestNoGoroutineExplosionWithTimers(t *testing.T) {
 	currentGoroutines := runtime.NumGoroutine()
 	t.Logf("Goroutines after %d refresh operations: %d", numRefreshes, currentGoroutines)
 
-	// Check timer count
-	coordinator.cleanupTimerMu.Lock()
-	timerCount := len(coordinator.cleanupTimers)
-	coordinator.cleanupTimerMu.Unlock()
-	t.Logf("Active cleanup timers: %d", timerCount)
+	// (Coordinator no longer tracks pending timers; time.AfterFunc closures
+	// fire performCleanup directly. This test now only checks the goroutine
+	// budget, which was always the real invariant.)
 
 	// With timer-based cleanup, goroutine increase should be minimal
 	// Timers don't create goroutines - they use the runtime timer heap
@@ -740,19 +744,9 @@ func TestNoGoroutineExplosionWithTimers(t *testing.T) {
 			initialGoroutines, currentGoroutines, goroutineIncrease)
 	}
 
-	// Wait for timers to fire and cleanup
+	// Wait for timers to fire and cleanup.
 	time.Sleep(config.DeduplicationCleanupDelay + 50*time.Millisecond)
 
-	// Verify timers were cleaned up
-	coordinator.cleanupTimerMu.Lock()
-	remainingTimers := len(coordinator.cleanupTimers)
-	coordinator.cleanupTimerMu.Unlock()
-
-	// Most timers should have fired and been removed
-	if remainingTimers > 10 {
-		t.Errorf("Too many cleanup timers remaining: %d", remainingTimers)
-	}
-
 	// Verify goroutines returned to near initial
 	runtime.GC()
 	time.Sleep(50 * time.Millisecond)

requeststate.go

@@ -0,0 +1,71 @@
+// Package traefikoidc provides OIDC authentication middleware for Traefik.
+// requestState bundles read-mostly fields for a single ServeHTTP call.
+package traefikoidc
+
+import "net/http"
+
+// requestState is a per-request context object allocated at the top of
+// ServeHTTP and threaded through to downstream handlers. It caches values
+// that would otherwise require a Yaegi-dispatched lock acquisition each time
+// they're read:
+//
+//   - The metadata snapshot (atomic.Value.Load once, not per-handler).
+//   - SessionData getter results (one RLock on sd.sessionMutex covers all
+//     fields, instead of 5-7 separate RLock/RUnlock pairs scattered through
+//     the handler chain).
+//
+// The struct is alloc'd at request entry, populated under at most one RLock
+// of sd.sessionMutex, and discarded at request exit. It is NOT shared across
+// requests and never written from another goroutine, so no synchronization
+// on its fields is required.
+//
+// Cross-request global caches (tokenCache, JWKCache, sessionEntries,
+// sessionInvalidationCache) remain — they're orthogonal. requestState's job
+// is to eliminate redundant per-handler reads of values that don't change
+// within a single request.
+type requestState struct {
+	// Globals snapshotted once.
+	metadata *MetadataSnapshot
+
+	// SessionData fields snapshotted under one RLock. The pointer to the
+	// SessionData is retained so handlers that genuinely need to mutate
+	// (Save, Clear, etc.) still have access.
+	session *SessionData
+
+	authenticated     bool
+	accessToken       string
+	idToken           string
+	refreshToken      string
+	userIdentifier    string
+	createdAtUnixSec  int64
+
+	// Output: scheme/host/redirect path determined at top of ServeHTTP.
+	scheme      string
+	host        string
+	redirectURL string
+
+	// Carry the next handler so forwardAuthorized doesn't need to close over t.
+	next http.Handler
+}
+
+// captureSession populates requestState's SessionData-derived fields under a
+// single RLock of sd.sessionMutex. Returns the populated rs for chaining.
+//
+// Replaces a sequence of SessionData.GetX() calls each of which acquires
+// sd.sessionMutex.RLock(). Under Yaegi each RLock costs ~1-5ms of
+// interpreter dispatch; batching saves the rest.
+func (rs *requestState) captureSession(sd *SessionData) *requestState {
+	if sd == nil {
+		return rs
+	}
+	rs.session = sd
+	sd.sessionMutex.RLock()
+	rs.authenticated = sd.getAuthenticatedUnsafe()
+	rs.accessToken = sd.getAccessTokenUnsafe()
+	rs.idToken = sd.getIDTokenUnsafe()
+	rs.refreshToken = sd.getRefreshTokenUnsafe()
+	rs.userIdentifier = sd.getUserIdentifierUnsafe()
+	rs.createdAtUnixSec = sd.getCreatedAtUnsafe()
+	sd.sessionMutex.RUnlock()
+	return rs
+}

security_audit_fixes_test.go

@@ -0,0 +1,404 @@
+package traefikoidc
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/gorilla/sessions"
+	"github.com/lukaszraczylo/traefikoidc/internal/utils"
+)
+
+// TestRank1_SessionCookieIsEncrypted verifies that the session cookie payload is
+// AES-encrypted, not merely HMAC-signed. Regression test for the audit finding
+// "session cookies signed but NOT encrypted": a single key left the stored OIDC
+// tokens recoverable in plaintext from the raw cookie bytes.
+func TestRank1_SessionCookieIsEncrypted(t *testing.T) {
+	const secret = "a-sufficiently-long-session-encryption-key"
+	authKey, encKey := deriveCookieKeys(secret)
+	if len(authKey) != 64 || len(encKey) != 32 {
+		t.Fatalf("expected 64-byte auth key and 32-byte enc key, got %d/%d", len(authKey), len(encKey))
+	}
+	if string(authKey) == string(encKey) {
+		t.Fatal("authentication and encryption keys must be independent")
+	}
+
+	const marker = "SUPER-SECRET-ACCESS-TOKEN-marker-value"
+
+	// Encode a session through the same two-key store the production code now
+	// builds (see NewSessionManager).
+	store := sessions.NewCookieStore(authKey, encKey)
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	rec := httptest.NewRecorder()
+	sess, err := store.New(req, "session")
+	if err != nil {
+		t.Fatalf("store.New failed: %v", err)
+	}
+	sess.Values["tok"] = marker
+	if err := sess.Save(req, rec); err != nil {
+		t.Fatalf("session save failed: %v", err)
+	}
+
+	var cookie *http.Cookie
+	for _, c := range rec.Result().Cookies() {
+		if c.Name == "session" {
+			cookie = c
+		}
+	}
+	if cookie == nil {
+		t.Fatal("no session cookie was set")
+	}
+
+	// The secret token must never appear in plaintext in the cookie value.
+	if strings.Contains(cookie.Value, marker) {
+		t.Error("marker token found in plaintext inside the session cookie value")
+	}
+
+	// A store holding only the authentication key (the previous behavior)
+	// must NOT be able to read the encrypted cookie — proving the payload is
+	// genuinely encrypted, not just signed.
+	signedOnly := sessions.NewCookieStore(authKey)
+	req2 := httptest.NewRequest(http.MethodGet, "/", nil)
+	req2.AddCookie(cookie)
+	if _, derr := signedOnly.Get(req2, "session"); derr == nil {
+		t.Error("encrypted cookie should not be decodable without the encryption key")
+	}
+
+	// The full two-key store round-trips correctly.
+	req3 := httptest.NewRequest(http.MethodGet, "/", nil)
+	req3.AddCookie(cookie)
+	rt, derr := store.Get(req3, "session")
+	if derr != nil {
+		t.Fatalf("round-trip decode failed: %v", derr)
+	}
+	if got, _ := rt.Values["tok"].(string); got != marker {
+		t.Errorf("round-trip mismatch: got %q want %q", got, marker)
+	}
+}
+
+// TestRank2And6_InvalidConfigFailsClosed verifies that NewWithContext now calls
+// Config.Validate() and fails closed on an empty or too-short session
+// encryption key instead of silently substituting a public hardcoded key, and
+// rejects other missing required fields. Regression test for "hardcoded default
+// encryption key" + "Config.Validate() never called in production path".
+func TestRank2And6_InvalidConfigFailsClosed(t *testing.T) {
+	base := func() *Config {
+		return &Config{
+			ProviderURL:          "https://accounts.google.com",
+			ClientID:             "test-client",
+			ClientSecret:         "test-secret",
+			CallbackURL:          "/callback",
+			SessionEncryptionKey: "this-is-a-valid-session-key-32b!",
+			RateLimit:            100,
+		}
+	}
+
+	// Sanity: a fully valid config still constructs.
+	p, err := NewWithContext(context.Background(), base(), nil, "valid")
+	if err != nil {
+		t.Fatalf("valid config should construct, got: %v", err)
+	}
+	if p != nil {
+		p.Close()
+	}
+
+	cases := []struct {
+		name   string
+		mutate func(*Config)
+	}{
+		{"empty key", func(c *Config) { c.SessionEncryptionKey = "" }},
+		{"short key", func(c *Config) { c.SessionEncryptionKey = "tooshort" }},
+		{"missing providerURL", func(c *Config) { c.ProviderURL = "" }},
+		{"missing callbackURL", func(c *Config) { c.CallbackURL = "" }},
+		{"plaintext remote providerURL", func(c *Config) { c.ProviderURL = "http://accounts.google.com" }},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c := base()
+			tc.mutate(c)
+			plugin, err := NewWithContext(context.Background(), c, nil, tc.name)
+			if err == nil {
+				if plugin != nil {
+					plugin.Close()
+				}
+				t.Errorf("expected NewWithContext to reject config (%s), but it succeeded", tc.name)
+			}
+		})
+	}
+}
+
+// TestRank3_DiscoveredEndpointSSRFGuard verifies that endpoints from the
+// provider discovery document are screened against SSRF targets before use.
+func TestRank3_DiscoveredEndpointSSRFGuard(t *testing.T) {
+	tr := &TraefikOidc{}
+
+	blocked := []string{
+		"http://169.254.169.254/latest/meta-data/", // cloud metadata (link-local)
+		"http://[fe80::1]/jwks",                    // IPv6 link-local
+		"http://10.0.0.5/jwks",                     // private
+		"http://192.168.1.10/jwks",                 // private
+		"http://127.0.0.1/jwks",                    // loopback (allowLoopback=false)
+		"ftp://example.com/jwks",                   // disallowed scheme
+	}
+	for _, u := range blocked {
+		if err := tr.validateDiscoveredEndpoint(u, false); err == nil {
+			t.Errorf("expected discovered endpoint %q to be rejected", u)
+		}
+	}
+
+	allowed := []string{
+		"https://accounts.google.com/o/oauth2/v3/certs",
+		"https://www.googleapis.com/oauth2/v3/certs", // cross-domain JWKS must stay allowed
+		"", // empty optional endpoint
+	}
+	for _, u := range allowed {
+		if err := tr.validateDiscoveredEndpoint(u, false); err != nil {
+			t.Errorf("expected discovered endpoint %q to be allowed, got %v", u, err)
+		}
+	}
+
+	// Loopback is allowed only when the provider itself is loopback (dev/test).
+	if err := tr.validateDiscoveredEndpoint("http://127.0.0.1:8080/jwks", true); err != nil {
+		t.Errorf("loopback endpoint should be allowed when allowLoopback=true: %v", err)
+	}
+	// Private addresses are allowed when explicitly opted in.
+	trPriv := &TraefikOidc{allowPrivateIPAddresses: true}
+	if err := trPriv.validateDiscoveredEndpoint("http://10.0.0.5/jwks", false); err != nil {
+		t.Errorf("private endpoint should be allowed when allowPrivateIPAddresses=true: %v", err)
+	}
+}
+
+// TestRank4_IntrospectionHostPin verifies the host-equality check used to pin
+// the credential-bearing introspection endpoint to the configured provider.
+func TestRank4_IntrospectionHostPin(t *testing.T) {
+	if !sameHost("https://kc.example.com/realms/x", "https://kc.example.com/realms/x/protocol/openid-connect/token/introspect") {
+		t.Error("introspection on the same host as the provider should be accepted")
+	}
+	if sameHost("https://kc.example.com", "https://evil.example.net/introspect") {
+		t.Error("introspection on a different host must be rejected")
+	}
+	if sameHost("", "https://kc.example.com") || sameHost("https://kc.example.com", "") {
+		t.Error("empty URL must not be treated as a host match")
+	}
+}
+
+// TestRank5_OpenRedirectNeutralized verifies the helper the callback now applies
+// to the stored incoming path forces a host-relative redirect target.
+func TestRank5_OpenRedirectNeutralized(t *testing.T) {
+	cases := map[string]string{
+		"//evil.com/x": "/evil.com/x",
+		`/\evil.com`:   "/evil.com",
+		"/legit/path":  "/legit/path",
+	}
+	for in, want := range cases {
+		got := normalizeLogoutPath(in)
+		if got != want {
+			t.Errorf("normalizeLogoutPath(%q) = %q, want %q", in, got, want)
+		}
+		if strings.HasPrefix(got, "//") || strings.HasPrefix(got, `/\`) {
+			t.Errorf("normalizeLogoutPath(%q) = %q is still protocol-relative", in, got)
+		}
+	}
+}
+
+// TestRank14_ExcludedURLSegmentBoundary verifies excluded-URL matching is
+// anchored at path-segment boundaries and cannot be widened into a bypass.
+func TestRank14_ExcludedURLSegmentBoundary(t *testing.T) {
+	if !pathExcluded("/public", "/public") {
+		t.Error("exact match should be excluded")
+	}
+	if !pathExcluded("/public/page", "/public") {
+		t.Error("sub-path should be excluded")
+	}
+	if pathExcluded("/publicsecret", "/public") {
+		t.Error("/publicsecret must NOT be excluded by /public")
+	}
+	if pathExcluded("/public-admin", "/public") {
+		t.Error("/public-admin must NOT be excluded by /public")
+	}
+	if !pathExcluded("/health", "/health/") {
+		t.Error("trailing-slash config should still match the exact path")
+	}
+	if pathExcluded("/anything", "/") {
+		t.Error("root exclusion must not match arbitrary paths")
+	}
+	if !pathExcluded("/", "/") {
+		t.Error("root exclusion should match the root path")
+	}
+}
+
+// TestRank15_ForwardedHostSanitized verifies a crafted X-Forwarded-Host cannot
+// inject CRLF, smuggle a second host, or otherwise poison the derived host.
+func TestRank15_ForwardedHostSanitized(t *testing.T) {
+	mk := func(xfh string) *http.Request {
+		r := httptest.NewRequest(http.MethodGet, "http://real.example.com/x", nil)
+		r.Host = "real.example.com"
+		if xfh != "" {
+			r.Header.Set("X-Forwarded-Host", xfh)
+		}
+		return r
+	}
+	if got := utils.DetermineHost(mk("ext.example.com")); got != "ext.example.com" {
+		t.Errorf("clean X-Forwarded-Host should be honored, got %q", got)
+	}
+	if got := utils.DetermineHost(mk("a.example.com, evil.com")); got != "a.example.com" {
+		t.Errorf("multi-value X-Forwarded-Host should use first host only, got %q", got)
+	}
+	for _, bad := range []string{"evil.com\r\nSet-Cookie: x=1", "evil.com /x", "   "} {
+		if got := utils.DetermineHost(mk(bad)); got != "real.example.com" {
+			t.Errorf("malformed X-Forwarded-Host %q should fall back to req.Host, got %q", bad, got)
+		}
+	}
+}
+
+// TestRank11_TransportPoolTLSIsolationAtLimit verifies that, once the client
+// limit is reached, the transport pool reuses an existing transport only when
+// its TLS settings match the caller's, and never hands back a transport built
+// with different TLS trust settings.
+func TestRank11_TransportPoolTLSIsolationAtLimit(t *testing.T) {
+	pool := &SharedTransportPool{
+		transports: make(map[string]*sharedTransport),
+		maxConns:   20,
+		maxClients: 5,
+	}
+
+	strict := DefaultHTTPClientConfig() // InsecureSkipVerify = false
+	t1 := pool.GetOrCreateTransport(strict)
+	if t1 == nil {
+		t.Fatal("expected a transport for the strict config")
+	}
+
+	// Saturate the client limit so subsequent calls hit the fallback path.
+	atomic.StoreInt32(&pool.clientCount, pool.maxClients)
+
+	// Same TLS settings, different (non-TLS) connection limit: safe to reuse.
+	sameTLS := DefaultHTTPClientConfig()
+	sameTLS.MaxConnsPerHost = 99
+	if got := pool.GetOrCreateTransport(sameTLS); got != t1 {
+		t.Error("at the limit a TLS-compatible config should reuse the existing transport")
+	}
+
+	// Different TLS settings (InsecureSkipVerify): must NOT reuse the strict
+	// transport — returning nil lets the caller fall back to a verifying default.
+	insecure := DefaultHTTPClientConfig()
+	insecure.InsecureSkipVerify = true
+	if got := pool.GetOrCreateTransport(insecure); got == t1 {
+		t.Error("at the limit a config with different TLS settings must not reuse the strict transport")
+	}
+}
+
+// TestRank9_RedisFingerprint verifies divergent explicit Redis backends produce
+// distinct fingerprints (used to warn about ignored cache config), while an
+// absent or disabled Redis yields the empty (no-warning) fingerprint.
+func TestRank9_RedisFingerprint(t *testing.T) {
+	if redisFingerprint(nil) != "" {
+		t.Error("nil config should yield an empty fingerprint")
+	}
+	if redisFingerprint(&Config{}) != "" {
+		t.Error("config without Redis should yield an empty fingerprint")
+	}
+	if redisFingerprint(&Config{Redis: &RedisConfig{Enabled: false, Address: "a:6379"}}) != "" {
+		t.Error("disabled Redis should yield an empty fingerprint")
+	}
+	a := redisFingerprint(&Config{Redis: &RedisConfig{Enabled: true, Address: "a:6379", KeyPrefix: "p"}})
+	b := redisFingerprint(&Config{Redis: &RedisConfig{Enabled: true, Address: "b:6379", KeyPrefix: "p"}})
+	if a == "" || a == b {
+		t.Errorf("distinct enabled backends must produce distinct non-empty fingerprints (%q vs %q)", a, b)
+	}
+}
+
+// TestRank10_TokenTypeCacheKeyNoCollision verifies that two different tokens
+// sharing the same 32-character JWT header prefix are classified independently.
+// The previous 32-char cache key would have collided and mis-classified them.
+func TestRank10_TokenTypeCacheKeyNoCollision(t *testing.T) {
+	tr := &TraefikOidc{
+		tokenTypeCache:         NewCache(),
+		suppressDiagnosticLogs: true,
+		clientID:               "client",
+	}
+	// A header prefix longer than 32 chars, shared by both tokens.
+	prefix := "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ"
+	idJWT := &JWT{Header: map[string]interface{}{}, Claims: map[string]interface{}{"nonce": "n"}}
+	accessJWT := &JWT{Header: map[string]interface{}{"typ": "at+jwt"}, Claims: map[string]interface{}{}}
+
+	if !tr.detectTokenType(idJWT, prefix+".id.sig") {
+		t.Error("token with a nonce claim should be detected as an ID token")
+	}
+	if tr.detectTokenType(accessJWT, prefix+".access.sig") {
+		t.Error("access token (typ=at+jwt) must not be mis-classified as ID despite the shared 32-char prefix")
+	}
+}
+
+// TestRank12_LiveInstanceCounter verifies the process-global instance counter
+// that gates teardown of shared singleton tasks.
+func TestRank12_LiveInstanceCounter(t *testing.T) {
+	start := atomic.LoadInt32(&liveInstanceCount)
+	registerLiveInstance()
+	registerLiveInstance()
+	if got := atomic.LoadInt32(&liveInstanceCount); got != start+2 {
+		t.Fatalf("expected %d live instances, got %d", start+2, got)
+	}
+	if rem := unregisterLiveInstance(); rem != start+1 {
+		t.Errorf("expected %d remaining, got %d", start+1, rem)
+	}
+	if rem := unregisterLiveInstance(); rem != start {
+		t.Errorf("expected %d remaining, got %d", start, rem)
+	}
+}
+
+// TestRank13_CookieMaxAgeMatchesSessionLifetime verifies the cookie store's
+// MaxAge (which bounds both the cookie Max-Age and the codec's cryptographic
+// timestamp validity) is bound to the configured session lifetime rather than
+// gorilla's 30-day default.
+func TestRank13_CookieMaxAgeMatchesSessionLifetime(t *testing.T) {
+	maxAge := 2 * time.Hour
+	sm, err := NewSessionManager(strings.Repeat("k", 40), false, "", "", maxAge, NewLogger("error"))
+	if err != nil {
+		t.Fatalf("NewSessionManager failed: %v", err)
+	}
+	defer sm.cancel()
+
+	cs, ok := sm.store.(*sessions.CookieStore)
+	if !ok {
+		t.Fatal("session store is not a *sessions.CookieStore")
+	}
+	if got := cs.Options.MaxAge; got != int(maxAge.Seconds()) {
+		t.Errorf("cookie store MaxAge = %d, want %d (bound to sessionMaxAge)", got, int(maxAge.Seconds()))
+	}
+}
+
+// TestRank33And34_HeaderSanitizationDistinction verifies the two header sinks
+// use the right strictness: free-form templated header VALUES (rank 34) permit
+// , ; = (e.g. an opaque "Bearer <token>" or an LDAP-DN claim) but reject CR/LF,
+// bidi, and over-length; claim values joined into delimited/identifier headers
+// (rank 33) additionally reject , ; =.
+func TestRank33And34_HeaderSanitizationDistinction(t *testing.T) {
+	// Rank 34 — free-form header value.
+	if headerValueReason("Bearer abc=def==", 8192) != "" {
+		t.Error("'=' must be allowed in a free-form header value (opaque bearer token)")
+	}
+	if headerValueReason("cn=user,ou=eng;dc=x", 8192) != "" {
+		t.Error("',;=' must be allowed in a free-form header value (e.g. an LDAP DN claim)")
+	}
+	if headerValueReason("evil"+string(rune(13))+string(rune(10))+"Injected: 1", 8192) == "" {
+		t.Error("CR/LF must be rejected in a header value (injection)")
+	}
+	if headerValueReason("toolong", 3) == "" {
+		t.Error("over-length value must be rejected")
+	}
+
+	// Rank 33 — claim value bound for a delimited/identifier header.
+	if _, ok := sanitizeHeaderClaimValue("admins,superadmins", 256); ok {
+		t.Error("a comma must be rejected in a value joined into a comma-delimited header")
+	}
+	if _, ok := sanitizeHeaderClaimValue("normal-user@example.com", 256); !ok {
+		t.Error("a clean identifier must pass claim sanitization")
+	}
+	if _, ok := sanitizeHeaderClaimValue("evil"+string(rune(13))+string(rune(10))+"X: 1", 256); ok {
+		t.Error("CR/LF must be rejected in a claim value")
+	}
+}

security_monitoring.go

@@ -1,590 +0,0 @@
-package traefikoidc
-
-import (
-	"fmt"
-	"net"
-	"net/http"
-	"strings"
-	"sync"
-	"time"
-)
-
-// SecurityEventType categorizes different types of security events
-// that can occur during OIDC authentication and authorization flows.
-type SecurityEventType string
-
-// Security event types for monitoring and alerting
-const (
-	// AuthFailure indicates a failed authentication attempt
-	AuthFailure SecurityEventType = "authentication_failure"
-	// TokenValidFailure indicates JWT token validation failed
-	TokenValidFailure SecurityEventType = "token_validation_failure"
-	// RateLimitHit indicates rate limiting was triggered
-	RateLimitHit SecurityEventType = "rate_limit_hit"
-	// SuspiciousActivity indicates potentially malicious behavior
-	SuspiciousActivity SecurityEventType = "suspicious_activity"
-)
-
-// DefaultSeverity returns the default severity level for each security event type.
-// Severity levels are: low, medium, high.
-func (t SecurityEventType) DefaultSeverity() string {
-	switch t {
-	case AuthFailure:
-		return "medium"
-	case TokenValidFailure:
-		return "medium"
-	case RateLimitHit:
-		return "low"
-	case SuspiciousActivity:
-		return "high"
-	default:
-		return "medium"
-	}
-}
-
-// IPFailureType returns a string identifier for categorizing failures
-// by IP address for rate limiting and blocking decisions.
-func (t SecurityEventType) IPFailureType() string {
-	switch t {
-	case AuthFailure:
-		return "auth_failure"
-	case TokenValidFailure:
-		return "token_failure"
-	case SuspiciousActivity:
-		return "suspicious"
-	default:
-		return "general"
-	}
-}
-
-// SecurityEvent represents a security-related event with comprehensive context.
-// Contains timing information, IP address, user agent, request details,
-// and custom event-specific data for security analysis and alerting.
-type SecurityEvent struct {
-	// Timestamp when the event occurred
-	Timestamp time.Time `json:"timestamp"`
-	// Details contains event-specific additional information
-	Details map[string]interface{} `json:"details,omitempty"`
-	// Type categorizes the event (auth_failure, token_failure, etc.)
-	Type string `json:"type"`
-	// Severity indicates event importance (low, medium, high)
-	Severity string `json:"severity"`
-	// ClientIP is the source IP address of the request
-	ClientIP string `json:"client_ip"`
-	// UserAgent is the User-Agent header from the request
-	UserAgent string `json:"user_agent"`
-	// RequestPath is the requested URL path
-	RequestPath string `json:"request_path"`
-	// Message provides human-readable description of the event
-	Message string `json:"message"`
-}
-
-// SecurityMonitor provides comprehensive security monitoring for the OIDC middleware.
-// It tracks failures by IP address, detects suspicious patterns, enforces
-// rate limits, and can trigger custom security event handlers.
-type SecurityMonitor struct {
-	ipFailures      map[string]*IPFailureTracker
-	patternDetector *SuspiciousPatternDetector
-	logger          *Logger
-	cleanupTask     *BackgroundTask
-	eventHandlers   []SecurityEventHandler
-	config          SecurityMonitorConfig
-	ipMutex         sync.RWMutex
-}
-
-// IPFailureTracker maintains failure statistics and blocking state for an IP address.
-// Used for implementing progressive penalties and automatic IP blocking based on
-// failure patterns, with support for different failure types for
-// rate limiting and IP blocking decisions.
-type IPFailureTracker struct {
-	// LastFailure timestamp of the most recent failure
-	LastFailure time.Time
-	// FirstFailure timestamp of the first failure in current window
-	FirstFailure time.Time
-	// BlockedUntil indicates when the IP block expires
-	BlockedUntil time.Time
-	// FailureTypes tracks counts by failure type
-	FailureTypes map[string]int64
-	// FailureCount total number of failures
-	FailureCount int64
-	// mutex protects concurrent access to tracker data
-	mutex sync.RWMutex
-	// IsBlocked indicates if this IP is currently blocked
-	IsBlocked bool
-}
-
-// SuspiciousPatternDetector identifies attack patterns that may indicate coordinated threats.
-// Analyzes events across multiple time windows to detect rapid failures, distributed attacks,
-// and persistent attack patterns that individual IP monitoring might miss.
-type SuspiciousPatternDetector struct {
-	// recentEvents stores recent security events for analysis
-	recentEvents []SecurityEvent
-	// shortWindow defines time frame for rapid failure detection
-	shortWindow time.Duration
-	// mediumWindow defines time frame for distributed attack detection
-	mediumWindow time.Duration
-	// longWindow defines time frame for persistent attack detection
-	longWindow time.Duration
-	// rapidFailureThreshold triggers rapid failure alerts
-	rapidFailureThreshold int
-	// distributedAttackThreshold triggers distributed attack alerts
-	distributedAttackThreshold int
-	// persistentAttackThreshold triggers persistent attack alerts
-	persistentAttackThreshold int
-	// eventsMutex protects concurrent access to events
-	eventsMutex sync.RWMutex
-}
-
-// SecurityEventHandler defines the interface for processing security events.
-// Implementations can log events, send alerts, update external systems,
-// or trigger automated response actions.
-type SecurityEventHandler interface {
-	// HandleSecurityEvent processes a security event
-	HandleSecurityEvent(event SecurityEvent)
-}
-
-// SecurityMonitorConfig contains configuration parameters for the security monitor.
-// Controls thresholds, time windows, and behavior for security monitoring.
-type SecurityMonitorConfig struct {
-	// MaxFailuresPerIP sets the failure threshold before blocking
-	MaxFailuresPerIP int `json:"max_failures_per_ip"`
-	// FailureWindowMinutes defines the time window for counting failures
-	FailureWindowMinutes int `json:"failure_window_minutes"`
-	// BlockDurationMinutes sets how long to block an IP
-	BlockDurationMinutes int `json:"block_duration_minutes"`
-	// RapidFailureThreshold triggers rapid failure detection
-	RapidFailureThreshold int `json:"rapid_failure_threshold"`
-	// CleanupIntervalMinutes sets cleanup frequency for old data
-	CleanupIntervalMinutes int  `json:"cleanup_interval_minutes"`
-	RetentionHours         int  `json:"retention_hours"`
-	EnablePatternDetection bool `json:"enable_pattern_detection"`
-	EnableDetailedLogging  bool `json:"enable_detailed_logging"`
-	LogSuspiciousOnly      bool `json:"log_suspicious_only"`
-}
-
-// DefaultSecurityMonitorConfig returns a default configuration
-func DefaultSecurityMonitorConfig() SecurityMonitorConfig {
-	return SecurityMonitorConfig{
-		MaxFailuresPerIP:       10,
-		FailureWindowMinutes:   15,
-		BlockDurationMinutes:   60,
-		EnablePatternDetection: true,
-		RapidFailureThreshold:  5,
-		EnableDetailedLogging:  true,
-		LogSuspiciousOnly:      false,
-		CleanupIntervalMinutes: 30,
-		RetentionHours:         24,
-	}
-}
-
-// NewSecurityMonitor creates a new security monitor instance
-func NewSecurityMonitor(config SecurityMonitorConfig, logger *Logger) *SecurityMonitor {
-	sm := &SecurityMonitor{
-		ipFailures:      make(map[string]*IPFailureTracker),
-		eventHandlers:   make([]SecurityEventHandler, 0),
-		config:          config,
-		logger:          logger,
-		patternDetector: NewSuspiciousPatternDetector(),
-	}
-
-	sm.startCleanupRoutine()
-
-	return sm
-}
-
-// NewSuspiciousPatternDetector creates a new pattern detector
-func NewSuspiciousPatternDetector() *SuspiciousPatternDetector {
-	return &SuspiciousPatternDetector{
-		shortWindow:                1 * time.Minute,
-		mediumWindow:               5 * time.Minute,
-		longWindow:                 15 * time.Minute,
-		rapidFailureThreshold:      5,
-		distributedAttackThreshold: 20,
-		persistentAttackThreshold:  50,
-		recentEvents:               make([]SecurityEvent, 0),
-	}
-}
-
-// RecordSecurityEvent is a generic method to record any type of security event
-func (sm *SecurityMonitor) RecordSecurityEvent(
-	eventType SecurityEventType,
-	clientIP, userAgent, requestPath string,
-	message string,
-	details map[string]interface{},
-	trackIPFailure bool) {
-
-	event := SecurityEvent{
-		Type:        string(eventType),
-		Severity:    eventType.DefaultSeverity(),
-		Timestamp:   time.Now(),
-		ClientIP:    clientIP,
-		UserAgent:   userAgent,
-		RequestPath: requestPath,
-		Message:     message,
-		Details:     details,
-	}
-
-	if trackIPFailure {
-		sm.recordIPFailure(clientIP, eventType.IPFailureType())
-	}
-
-	sm.processSecurityEvent(event)
-}
-
-// RecordAuthenticationFailure records an authentication failure event
-func (sm *SecurityMonitor) RecordAuthenticationFailure(clientIP, userAgent, requestPath, reason string, details map[string]interface{}) {
-	if details == nil {
-		details = make(map[string]interface{})
-	}
-	details["reason"] = reason
-
-	sm.RecordSecurityEvent(
-		AuthFailure,
-		clientIP,
-		userAgent,
-		requestPath,
-		fmt.Sprintf("Authentication failed: %s", reason),
-		details,
-		true,
-	)
-}
-
-// RecordTokenValidationFailure records a token validation failure
-func (sm *SecurityMonitor) RecordTokenValidationFailure(clientIP, userAgent, requestPath, reason string, tokenPrefix string) {
-	details := map[string]interface{}{
-		"reason": reason,
-	}
-	if tokenPrefix != "" {
-		details["token_prefix"] = tokenPrefix
-	}
-
-	sm.RecordSecurityEvent(
-		TokenValidFailure,
-		clientIP,
-		userAgent,
-		requestPath,
-		fmt.Sprintf("Token validation failed: %s", reason),
-		details,
-		true,
-	)
-}
-
-// RecordRateLimitHit records when rate limiting is triggered
-func (sm *SecurityMonitor) RecordRateLimitHit(clientIP, userAgent, requestPath string) {
-	details := map[string]interface{}{
-		"limit_type": "token_verification",
-	}
-
-	sm.RecordSecurityEvent(
-		RateLimitHit,
-		clientIP,
-		userAgent,
-		requestPath,
-		"Rate limit exceeded",
-		details,
-		true,
-	)
-}
-
-// RecordSuspiciousActivity records suspicious activity that doesn't fit other categories
-func (sm *SecurityMonitor) RecordSuspiciousActivity(clientIP, userAgent, requestPath, activityType, description string, details map[string]interface{}) {
-	if details == nil {
-		details = make(map[string]interface{})
-	}
-	details["activity_type"] = activityType
-
-	sm.RecordSecurityEvent(
-		SuspiciousActivity,
-		clientIP,
-		userAgent,
-		requestPath,
-		fmt.Sprintf("Suspicious activity detected: %s - %s", activityType, description),
-		details,
-		true,
-	)
-}
-
-// recordIPFailure tracks failures for a specific IP address
-func (sm *SecurityMonitor) recordIPFailure(clientIP, failureType string) {
-	sm.ipMutex.Lock()
-	defer sm.ipMutex.Unlock()
-
-	tracker, exists := sm.ipFailures[clientIP]
-	if !exists {
-		tracker = &IPFailureTracker{
-			FailureTypes: make(map[string]int64),
-			FirstFailure: time.Now(),
-		}
-		sm.ipFailures[clientIP] = tracker
-	}
-
-	tracker.mutex.Lock()
-	defer tracker.mutex.Unlock()
-
-	tracker.FailureCount++
-	tracker.LastFailure = time.Now()
-	tracker.FailureTypes[failureType]++
-
-	windowStart := time.Now().Add(-time.Duration(sm.config.FailureWindowMinutes) * time.Minute)
-	if tracker.FirstFailure.After(windowStart) && tracker.FailureCount >= int64(sm.config.MaxFailuresPerIP) {
-		if !tracker.IsBlocked {
-			tracker.IsBlocked = true
-			tracker.BlockedUntil = time.Now().Add(time.Duration(sm.config.BlockDurationMinutes) * time.Minute)
-
-			sm.logger.Errorf("IP %s blocked due to %d failures (types: %v)", clientIP, tracker.FailureCount, tracker.FailureTypes)
-
-			blockEvent := SecurityEvent{
-				Type:      "ip_blocked",
-				Severity:  "high",
-				Timestamp: time.Now(),
-				ClientIP:  clientIP,
-				Message:   fmt.Sprintf("IP blocked due to %d failures in %d minutes", tracker.FailureCount, sm.config.FailureWindowMinutes),
-				Details: map[string]interface{}{
-					"failure_count": tracker.FailureCount,
-					"failure_types": tracker.FailureTypes,
-					"blocked_until": tracker.BlockedUntil,
-				},
-			}
-			sm.processSecurityEvent(blockEvent)
-		}
-	}
-}
-
-// IsIPBlocked checks if an IP address is currently blocked
-func (sm *SecurityMonitor) IsIPBlocked(clientIP string) bool {
-	sm.ipMutex.RLock()
-	defer sm.ipMutex.RUnlock()
-
-	tracker, exists := sm.ipFailures[clientIP]
-	if !exists {
-		return false
-	}
-
-	tracker.mutex.RLock()
-	defer tracker.mutex.RUnlock()
-
-	if tracker.IsBlocked && time.Now().Before(tracker.BlockedUntil) {
-		return true
-	}
-
-	if tracker.IsBlocked && time.Now().After(tracker.BlockedUntil) {
-		tracker.IsBlocked = false
-		sm.logger.Infof("IP %s automatically unblocked", clientIP)
-	}
-
-	return false
-}
-
-// processSecurityEvent processes a security event through all handlers and pattern detection
-func (sm *SecurityMonitor) processSecurityEvent(event SecurityEvent) {
-	if sm.config.EnablePatternDetection {
-		sm.patternDetector.AddEvent(event)
-
-		if patterns := sm.patternDetector.DetectSuspiciousPatterns(); len(patterns) > 0 {
-			if len(patterns) == 1 {
-				sm.logger.Errorf("Suspicious pattern detected: %s", patterns[0])
-			} else {
-				sm.logger.Errorf("Multiple suspicious patterns detected: %v", patterns)
-			}
-
-			for _, pattern := range patterns {
-				patternEvent := SecurityEvent{
-					Type:      "suspicious_pattern",
-					Severity:  "high",
-					Timestamp: time.Now(),
-					Message:   fmt.Sprintf("Suspicious pattern detected: %s", pattern),
-					Details: map[string]interface{}{
-						"pattern_type":  pattern,
-						"trigger_event": event,
-					},
-				}
-				sm.handleSecurityEvent(patternEvent)
-			}
-		}
-	}
-
-	sm.handleSecurityEvent(event)
-}
-
-// handleSecurityEvent sends the event to all registered handlers
-func (sm *SecurityMonitor) handleSecurityEvent(event SecurityEvent) {
-	if sm.config.EnableDetailedLogging && (!sm.config.LogSuspiciousOnly || event.Severity == "high") {
-		sm.logger.Infof("Security Event [%s/%s]: %s (IP: %s, Path: %s)",
-			event.Type, event.Severity, event.Message, event.ClientIP, event.RequestPath)
-	}
-
-	for _, handler := range sm.eventHandlers {
-		go handler.HandleSecurityEvent(event)
-	}
-}
-
-// AddEventHandler adds a security event handler
-func (sm *SecurityMonitor) AddEventHandler(handler SecurityEventHandler) {
-	sm.eventHandlers = append(sm.eventHandlers, handler)
-}
-
-// This is kept for API compatibility but doesn't collect actual metrics
-func (sm *SecurityMonitor) GetSecurityMetrics() map[string]interface{} {
-	return map[string]interface{}{
-		"tracked_ips": 0,
-	}
-}
-
-// AddEvent adds an event to the pattern detector
-func (spd *SuspiciousPatternDetector) AddEvent(event SecurityEvent) {
-	spd.eventsMutex.Lock()
-	defer spd.eventsMutex.Unlock()
-
-	spd.recentEvents = append(spd.recentEvents, event)
-
-	cutoff := time.Now().Add(-spd.longWindow)
-	var filteredEvents []SecurityEvent
-	for _, e := range spd.recentEvents {
-		if e.Timestamp.After(cutoff) {
-			filteredEvents = append(filteredEvents, e)
-		}
-	}
-	spd.recentEvents = filteredEvents
-}
-
-// DetectSuspiciousPatterns analyzes recent events for suspicious patterns
-func (spd *SuspiciousPatternDetector) DetectSuspiciousPatterns() []string {
-	spd.eventsMutex.RLock()
-	defer spd.eventsMutex.RUnlock()
-
-	var patterns []string
-	now := time.Now()
-
-	ipCounts := make(map[string]int)
-	shortWindowStart := now.Add(-spd.shortWindow)
-
-	for _, event := range spd.recentEvents {
-		if event.Timestamp.After(shortWindowStart) &&
-			(event.Type == "authentication_failure" || event.Type == "token_validation_failure") {
-			ipCounts[event.ClientIP]++
-		}
-	}
-
-	for ip, count := range ipCounts {
-		if count >= spd.rapidFailureThreshold {
-			patterns = append(patterns, fmt.Sprintf("rapid_failures_from_ip_%s", ip))
-		}
-	}
-
-	mediumWindowStart := now.Add(-spd.mediumWindow)
-	uniqueFailingIPs := make(map[string]bool)
-
-	for _, event := range spd.recentEvents {
-		if event.Timestamp.After(mediumWindowStart) &&
-			(event.Type == "authentication_failure" || event.Type == "token_validation_failure") {
-			uniqueFailingIPs[event.ClientIP] = true
-		}
-	}
-
-	if len(uniqueFailingIPs) >= spd.distributedAttackThreshold {
-		patterns = append(patterns, "distributed_attack_pattern")
-	}
-
-	longWindowStart := now.Add(-spd.longWindow)
-	persistentFailures := 0
-
-	for _, event := range spd.recentEvents {
-		if event.Timestamp.After(longWindowStart) &&
-			(event.Type == "authentication_failure" || event.Type == "token_validation_failure") {
-			persistentFailures++
-		}
-	}
-
-	if persistentFailures >= spd.persistentAttackThreshold {
-		patterns = append(patterns, "persistent_attack_pattern")
-	}
-
-	return patterns
-}
-
-// startCleanupRoutine starts the background cleanup routine
-func (sm *SecurityMonitor) startCleanupRoutine() {
-	sm.cleanupTask = NewBackgroundTask(
-		"security-monitor-cleanup",
-		time.Duration(sm.config.CleanupIntervalMinutes)*time.Minute,
-		sm.cleanup,
-		sm.logger)
-	sm.cleanupTask.Start()
-}
-
-// StopCleanupRoutine stops the background cleanup routine
-func (sm *SecurityMonitor) StopCleanupRoutine() {
-	if sm.cleanupTask != nil {
-		sm.cleanupTask.Stop()
-		sm.cleanupTask = nil
-	}
-}
-
-// cleanup removes old tracking data
-func (sm *SecurityMonitor) cleanup() {
-	sm.ipMutex.Lock()
-	defer sm.ipMutex.Unlock()
-
-	cutoff := time.Now().Add(-time.Duration(sm.config.RetentionHours) * time.Hour)
-
-	for ip, tracker := range sm.ipFailures {
-		tracker.mutex.RLock()
-		shouldRemove := tracker.LastFailure.Before(cutoff) && !tracker.IsBlocked
-		tracker.mutex.RUnlock()
-
-		if shouldRemove {
-			delete(sm.ipFailures, ip)
-		}
-	}
-
-	sm.logger.Debugf("Security monitor cleanup completed, tracking %d IPs", len(sm.ipFailures))
-}
-
-// ExtractClientIP extracts the client IP from the request, considering proxy headers
-func ExtractClientIP(r *http.Request) string {
-	if xri := r.Header.Get("X-Real-IP"); xri != "" {
-		if net.ParseIP(xri) != nil {
-			return xri
-		}
-	}
-
-	if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
-		ips := strings.Split(xff, ",")
-		if len(ips) > 0 {
-			ip := strings.TrimSpace(ips[0])
-			if net.ParseIP(ip) != nil {
-				return ip
-			}
-		}
-	}
-
-	host, _, err := net.SplitHostPort(r.RemoteAddr)
-	if err != nil {
-		return r.RemoteAddr
-	}
-	return host
-}
-
-// LoggingSecurityEventHandler logs security events to the standard logger
-type LoggingSecurityEventHandler struct {
-	logger *Logger
-}
-
-// NewLoggingSecurityEventHandler creates a new logging event handler
-func NewLoggingSecurityEventHandler(logger *Logger) *LoggingSecurityEventHandler {
-	return &LoggingSecurityEventHandler{logger: logger}
-}
-
-// HandleSecurityEvent implements SecurityEventHandler
-func (h *LoggingSecurityEventHandler) HandleSecurityEvent(event SecurityEvent) {
-	switch event.Severity {
-	case "high":
-		h.logger.Errorf("SECURITY [%s]: %s (IP: %s)", event.Type, event.Message, event.ClientIP)
-	case "medium":
-		h.logger.Errorf("SECURITY [%s]: %s (IP: %s)", event.Type, event.Message, event.ClientIP)
-	case "low":
-		h.logger.Infof("SECURITY [%s]: %s (IP: %s)", event.Type, event.Message, event.ClientIP)
-	default:
-		h.logger.Debugf("SECURITY [%s]: %s (IP: %s)", event.Type, event.Message, event.ClientIP)
-	}
-}

security_monitoring_test.go

@@ -1,285 +0,0 @@
-package traefikoidc
-
-import (
-	"net/http/httptest"
-	"strconv"
-	"testing"
-	"time"
-)
-
-func TestSecurityMonitor(t *testing.T) {
-	config := DefaultSecurityMonitorConfig()
-	config.MaxFailuresPerIP = 3
-	config.BlockDurationMinutes = 1 // 1 minute for testing
-	config.CleanupIntervalMinutes = 1
-
-	logger := NewLogger("debug")
-	monitor := NewSecurityMonitor(config, logger)
-	defer func() {
-		// Allow cleanup goroutine to finish
-		time.Sleep(150 * time.Millisecond)
-	}()
-
-	t.Run("Record authentication failure", func(t *testing.T) {
-		monitor.RecordAuthenticationFailure("192.168.1.1", "test-agent", "/login", "invalid credentials", nil)
-
-		// Should not be blocked after first failure
-		if monitor.IsIPBlocked("192.168.1.1") {
-			t.Error("IP should not be blocked after first failure")
-		}
-	})
-
-	t.Run("IP blocked after max failures", func(t *testing.T) {
-		// Record multiple failures
-		for i := 0; i < config.MaxFailuresPerIP; i++ {
-			monitor.RecordAuthenticationFailure("192.168.1.2", "test-agent", "/login", "invalid credentials", nil)
-		}
-
-		// Should be blocked now
-		if !monitor.IsIPBlocked("192.168.1.2") {
-			t.Error("IP should be blocked after max failures")
-		}
-	})
-
-	t.Run("Token validation failure", func(t *testing.T) {
-		// Just verify the method doesn't panic
-		monitor.RecordTokenValidationFailure("192.168.1.3", "test-agent", "/api", "invalid token", "abc123")
-	})
-
-	t.Run("Rate limit hit", func(t *testing.T) {
-		// Just verify the method doesn't panic
-		monitor.RecordRateLimitHit("192.168.1.4", "test-agent", "/api")
-	})
-
-	t.Run("Suspicious activity", func(t *testing.T) {
-		details := map[string]interface{}{"pattern": "unusual"}
-		// Just verify the method doesn't panic
-		monitor.RecordSuspiciousActivity("192.168.1.5", "test-agent", "/admin", "unusual pattern", "high frequency requests", details)
-	})
-}
-
-func TestSuspiciousPatternDetector(t *testing.T) {
-	detector := NewSuspiciousPatternDetector()
-
-	t.Run("Add events and detect patterns", func(t *testing.T) {
-		// Add multiple events from same IP
-		for i := 0; i < 10; i++ {
-			event := SecurityEvent{
-				Type:      "authentication_failure",
-				ClientIP:  "192.168.1.100",
-				Timestamp: time.Now(),
-			}
-			detector.AddEvent(event)
-		}
-
-		patterns := detector.DetectSuspiciousPatterns()
-
-		found := false
-		for _, p := range patterns {
-			if p == "rapid_failures_from_ip_192.168.1.100" {
-				found = true
-				break
-			}
-		}
-		if !found {
-			t.Error("Expected to detect rapid failure pattern")
-		}
-	})
-
-	t.Run("Detect distributed attack pattern", func(t *testing.T) {
-		// Add failures from many different IPs
-		for i := 0; i < 25; i++ {
-			event := SecurityEvent{
-				Type:      "authentication_failure",
-				ClientIP:  "192.168.1." + strconv.Itoa(100+i),
-				Timestamp: time.Now(),
-			}
-			detector.AddEvent(event)
-		}
-
-		patterns := detector.DetectSuspiciousPatterns()
-
-		found := false
-		for _, p := range patterns {
-			if p == "distributed_attack_pattern" {
-				found = true
-				break
-			}
-		}
-		if !found {
-			t.Error("Expected to detect distributed attack pattern")
-		}
-	})
-}
-
-func TestExtractClientIP(t *testing.T) {
-	tests := []struct {
-		name       string
-		remoteAddr string
-		headers    map[string]string
-		expectedIP string
-	}{
-		{
-			name:       "Direct connection",
-			remoteAddr: "192.168.1.1:12345",
-			expectedIP: "192.168.1.1",
-		},
-		{
-			name:       "X-Forwarded-For header",
-			remoteAddr: "10.0.0.1:12345",
-			headers:    map[string]string{"X-Forwarded-For": "203.0.113.1, 10.0.0.1"},
-			expectedIP: "203.0.113.1",
-		},
-		{
-			name:       "X-Real-IP header",
-			remoteAddr: "10.0.0.1:12345",
-			headers:    map[string]string{"X-Real-IP": "203.0.113.2"},
-			expectedIP: "203.0.113.2",
-		},
-		{
-			name:       "Multiple headers - X-Real-IP takes precedence",
-			remoteAddr: "10.0.0.1:12345",
-			headers: map[string]string{
-				"X-Forwarded-For": "203.0.113.1",
-				"X-Real-IP":       "203.0.113.2",
-			},
-			expectedIP: "203.0.113.2",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			req := httptest.NewRequest("GET", "/", nil)
-			req.RemoteAddr = tt.remoteAddr
-
-			for key, value := range tt.headers {
-				req.Header.Set(key, value)
-			}
-
-			ip := ExtractClientIP(req)
-			if ip != tt.expectedIP {
-				t.Errorf("Expected IP %s, got %s", tt.expectedIP, ip)
-			}
-		})
-	}
-}
-
-func TestSecurityEventHandlers(t *testing.T) {
-	t.Run("Logging security event handler", func(t *testing.T) {
-		logger := NewLogger("debug")
-		handler := NewLoggingSecurityEventHandler(logger)
-
-		event := SecurityEvent{
-			Type:      "authentication_failure",
-			ClientIP:  "192.168.1.1",
-			Timestamp: time.Now(),
-			Message:   "Test failure",
-			Severity:  "medium",
-		}
-
-		// Should not panic
-		handler.HandleSecurityEvent(event)
-	})
-
-	// Metrics security event handler test removed as part of metrics cleanup
-}
-
-func TestSecurityMonitorEventHandlers(t *testing.T) {
-	config := DefaultSecurityMonitorConfig()
-	logger := NewLogger("debug")
-	monitor := NewSecurityMonitor(config, logger)
-
-	// Add event handler with proper synchronization
-	handlerCalled := make(chan bool, 1)
-	handler := &testSecurityEventHandler{
-		callback: func(event SecurityEvent) {
-			select {
-			case handlerCalled <- true:
-			default:
-				// Channel already has a value, don't block
-			}
-		},
-	}
-	monitor.AddEventHandler(handler)
-
-	monitor.RecordAuthenticationFailure("192.168.1.1", "test-agent", "/login", "test failure", nil)
-
-	// Wait for event handler to be called with timeout
-	select {
-	case <-handlerCalled:
-		// Success - handler was called
-	case <-time.After(100 * time.Millisecond):
-		t.Error("Expected event handler to be called within timeout")
-	}
-}
-
-// Test helper for security event handler
-type testSecurityEventHandler struct {
-	callback func(SecurityEvent)
-}
-
-func (h *testSecurityEventHandler) HandleSecurityEvent(event SecurityEvent) {
-	h.callback(event)
-}
-
-func TestDefaultSecurityMonitorConfig(t *testing.T) {
-	config := DefaultSecurityMonitorConfig()
-
-	if config.MaxFailuresPerIP <= 0 {
-		t.Error("Expected positive MaxFailuresPerIP")
-	}
-	if config.BlockDurationMinutes <= 0 {
-		t.Error("Expected positive BlockDurationMinutes")
-	}
-	if config.CleanupIntervalMinutes <= 0 {
-		t.Error("Expected positive CleanupIntervalMinutes")
-	}
-	if config.FailureWindowMinutes <= 0 {
-		t.Error("Expected positive FailureWindowMinutes")
-	}
-}
-
-func TestSecurityMonitorCleanup(t *testing.T) {
-	config := DefaultSecurityMonitorConfig()
-	config.CleanupIntervalMinutes = 1
-	config.BlockDurationMinutes = 1
-	config.RetentionHours = 1
-
-	logger := NewLogger("debug")
-	monitor := NewSecurityMonitor(config, logger)
-
-	// Block an IP
-	for i := 0; i < config.MaxFailuresPerIP; i++ {
-		monitor.RecordAuthenticationFailure("192.168.1.99", "test-agent", "/login", "test", nil)
-	}
-
-	// Verify it's blocked
-	if !monitor.IsIPBlocked("192.168.1.99") {
-		t.Error("IP should be blocked")
-	}
-
-	// Wait a bit and check if it gets unblocked automatically
-	time.Sleep(100 * time.Millisecond)
-
-	// The IP should still be blocked since we haven't waited long enough
-	if !monitor.IsIPBlocked("192.168.1.99") {
-		t.Error("IP should still be blocked")
-	}
-}
-
-func TestSecurityEventTypes(t *testing.T) {
-	config := DefaultSecurityMonitorConfig()
-	logger := NewLogger("debug")
-	monitor := NewSecurityMonitor(config, logger)
-
-	// Test different event types - just verify they don't panic
-	monitor.RecordAuthenticationFailure("192.168.1.200", "test-agent", "/login", "invalid password", nil)
-	monitor.RecordTokenValidationFailure("192.168.1.200", "test-agent", "/api", "expired token", "abc123")
-	monitor.RecordRateLimitHit("192.168.1.200", "test-agent", "/api")
-
-	details := map[string]interface{}{"pattern": "test"}
-	monitor.RecordSuspiciousActivity("192.168.1.200", "test-agent", "/admin", "unusual pattern", "multiple failed logins", details)
-
-	// Just verify GetSecurityMetrics doesn't panic
-	_ = monitor.GetSecurityMetrics()
-}

session.go

@@ -4,7 +4,9 @@ import (
 	"bytes"
 	"compress/gzip"
 	"context"
+	"crypto/hmac"
 	"crypto/rand"
+	"crypto/sha256"
 	"crypto/subtle"
 	"encoding/base64"
 	"encoding/hex"
@@ -31,6 +33,45 @@ func constantTimeStringCompare(a, b string) bool {
 	return subtle.ConstantTimeCompare([]byte(a), []byte(b)) == 1
 }
 
+// deriveCookieKeys derives an independent 64-byte HMAC authentication key and a
+// 32-byte AES-256 encryption key from the operator-provided session encryption
+// key using HKDF-SHA256 (RFC 5869).
+//
+// gorilla/securecookie only ENCRYPTS the cookie payload when a block
+// (encryption) key is supplied; constructing the store with a single key leaves
+// sessions signed-but-plaintext, so the OIDC access/refresh/ID tokens stored in
+// the cookie are recoverable by anyone who can read the raw cookie bytes. Two
+// independent keys are derived here so the cookie is both encrypted and
+// authenticated. HKDF is implemented with stdlib hmac+sha256 so it runs under
+// Traefik's yaegi interpreter, which may not export crypto/hkdf.
+func deriveCookieKeys(secret string) (authKey, encKey []byte) {
+	okm := hkdfSHA256([]byte(secret), nil, []byte("traefikoidc session cookie keys v1"), 96)
+	return okm[:64], okm[64:96]
+}
+
+// hkdfSHA256 performs HKDF-Extract followed by HKDF-Expand (RFC 5869) using
+// HMAC-SHA256 and returns length bytes of output keying material.
+func hkdfSHA256(ikm, salt, info []byte, length int) []byte {
+	if len(salt) == 0 {
+		salt = make([]byte, sha256.Size)
+	}
+	// Extract: PRK = HMAC-SHA256(salt, IKM)
+	ext := hmac.New(sha256.New, salt)
+	ext.Write(ikm)
+	prk := ext.Sum(nil)
+	// Expand: T(i) = HMAC-SHA256(PRK, T(i-1) | info | i)
+	var out, t []byte
+	for i := byte(1); len(out) < length; i++ {
+		exp := hmac.New(sha256.New, prk)
+		exp.Write(t)
+		exp.Write(info)
+		exp.Write([]byte{i})
+		t = exp.Sum(nil)
+		out = append(out, t...)
+	}
+	return out[:length]
+}
+
 // min returns the minimum of two integers.
 // This is a utility function used throughout the session management code.
 // Parameters:
@@ -118,12 +159,12 @@ var knownSessionKeys = map[string]bool{
 	"id_token":        true,
 	"user_identifier": true,
 	"authenticated":   true,
-	"csrf":           true,
-	"nonce":          true,
-	"code_verifier":  true,
-	"incoming_path":  true,
-	"created_at":     true,
-	"redirect_count": true,
+	"csrf":            true,
+	"nonce":           true,
+	"code_verifier":   true,
+	"incoming_path":   true,
+	"created_at":      true,
+	"redirect_count":  true,
 }
 
 // compressCombinedPayload compresses the combined session payload using gzip.
@@ -423,8 +464,13 @@ func NewSessionManager(encryptionKey string, forceHTTPS bool, cookieDomain strin
 
 	ctx, cancel := context.WithCancel(context.Background())
 
+	// Derive independent authentication + encryption keys so the session cookie
+	// is AES-256 encrypted and HMAC authenticated, not merely signed. See
+	// deriveCookieKeys: a single key would leave the stored tokens in plaintext.
+	authKey, encKey := deriveCookieKeys(encryptionKey)
+
 	sm := &SessionManager{
-		store:         sessions.NewCookieStore([]byte(encryptionKey)),
+		store:         sessions.NewCookieStore(authKey, encKey),
 		forceHTTPS:    forceHTTPS,
 		cookieDomain:  cookieDomain,
 		cookiePrefix:  cookiePrefix,
@@ -435,6 +481,14 @@ func NewSessionManager(encryptionKey string, forceHTTPS bool, cookieDomain strin
 		cancel:        cancel,
 	}
 
+	// Bind the cookie codec's timestamp validity (and the cookie Max-Age) to the
+	// configured session lifetime instead of gorilla's 30-day default, so a
+	// stolen cookie is not cryptographically valid for up to 30 days regardless
+	// of the (possibly much shorter) configured sessionMaxAge (rank 13).
+	if cs, ok := sm.store.(*sessions.CookieStore); ok {
+		cs.MaxAge(int(sessionMaxAge.Seconds()))
+	}
+
 	// Initialize global memory monitoring (singleton)
 	sm.memoryMonitor = GetGlobalTaskMemoryMonitor(logger)
 
@@ -1566,7 +1620,7 @@ func (sd *SessionData) Clear(r *http.Request, w http.ResponseWriter) error {
 
 	sd.sessionMutex.Lock()
 	sd.clearAllSessionData(r, true)
-	
+
 	// Release the lock before calling Save to prevent deadlock
 	sd.sessionMutex.Unlock()
 

settings.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"net"
 	"net/http"
 	"net/url"
 	"os"
@@ -54,6 +55,7 @@ type Config struct {
 	AllowedUserDomains        []string                         `json:"allowedUserDomains"`
 	AllowedUsers              []string                         `json:"allowedUsers"`
 	Headers                   []TemplatedHeader                `json:"headers"`
+	ExtraAuthParams           map[string]string                `json:"extraAuthParams,omitempty"`
 	RefreshGracePeriodSeconds int                              `json:"refreshGracePeriodSeconds"`
 	// MaxRefreshTokenAgeSeconds is a heuristic upper bound on the lifetime of
 	// a stored refresh token. Once the token has been in the session longer
@@ -63,23 +65,23 @@ type Config struct {
 	// IdPs do not expose RT TTL on the wire, so this is intentionally a
 	// conservative heuristic; tune to match your provider configuration.
 	// Default 21600 (6h). Set to 0 to disable the check.
-	MaxRefreshTokenAgeSeconds int                              `json:"maxRefreshTokenAgeSeconds"`
-	SessionMaxAge             int                              `json:"sessionMaxAge"`
-	RateLimit                 int                              `json:"rateLimit"`
-	OverrideScopes            bool                             `json:"overrideScopes"`
-	DisableReplayDetection    bool                             `json:"disableReplayDetection,omitempty"`
-	RequireTokenIntrospection bool                             `json:"requireTokenIntrospection,omitempty"`
-	AllowOpaqueTokens         bool                             `json:"allowOpaqueTokens,omitempty"`
-	StrictAudienceValidation  bool                             `json:"strictAudienceValidation,omitempty"`
-	EnablePKCE                bool                             `json:"enablePKCE"`
-	ForceHTTPS                bool                             `json:"forceHTTPS"`
-	AllowPrivateIPAddresses   bool                             `json:"allowPrivateIPAddresses,omitempty"`
-	MinimalHeaders            bool                             `json:"minimalHeaders,omitempty"`
-	StripAuthCookies          bool                             `json:"stripAuthCookies,omitempty"`
-	EnableBackchannelLogout   bool                             `json:"enableBackchannelLogout,omitempty"`
-	EnableFrontchannelLogout  bool                             `json:"enableFrontchannelLogout,omitempty"`
-	BackchannelLogoutURL      string                           `json:"backchannelLogoutURL,omitempty"`
-	FrontchannelLogoutURL     string                           `json:"frontchannelLogoutURL,omitempty"`
+	MaxRefreshTokenAgeSeconds int    `json:"maxRefreshTokenAgeSeconds"`
+	SessionMaxAge             int    `json:"sessionMaxAge"`
+	RateLimit                 int    `json:"rateLimit"`
+	OverrideScopes            bool   `json:"overrideScopes"`
+	DisableReplayDetection    bool   `json:"disableReplayDetection,omitempty"`
+	RequireTokenIntrospection bool   `json:"requireTokenIntrospection,omitempty"`
+	AllowOpaqueTokens         bool   `json:"allowOpaqueTokens,omitempty"`
+	StrictAudienceValidation  bool   `json:"strictAudienceValidation,omitempty"`
+	EnablePKCE                bool   `json:"enablePKCE"`
+	ForceHTTPS                bool   `json:"forceHTTPS"`
+	AllowPrivateIPAddresses   bool   `json:"allowPrivateIPAddresses,omitempty"`
+	MinimalHeaders            bool   `json:"minimalHeaders,omitempty"`
+	StripAuthCookies          bool   `json:"stripAuthCookies,omitempty"`
+	EnableBackchannelLogout   bool   `json:"enableBackchannelLogout,omitempty"`
+	EnableFrontchannelLogout  bool   `json:"enableFrontchannelLogout,omitempty"`
+	BackchannelLogoutURL      string `json:"backchannelLogoutURL,omitempty"`
+	FrontchannelLogoutURL     string `json:"frontchannelLogoutURL,omitempty"`
 	// CACertPath is an optional filesystem path to a PEM-encoded CA bundle used
 	// to verify the OIDC provider's TLS certificate. Use this when the provider
 	// is signed by an internal/private CA that is not in the system trust store.
@@ -125,6 +127,52 @@ type Config struct {
 	// ClientAssertionAlg is the JWS signing algorithm. Defaults to RS256.
 	// Supported: RS256/384/512, PS256/384/512, ES256/384/512.
 	ClientAssertionAlg string `json:"clientAssertionAlg,omitempty"`
+
+	// --- Bearer-token auth (opt-in M2M path) ---
+
+	// EnableBearerAuth turns on the Authorization: Bearer <jwt> auth path.
+	// Default false. When true, Audience MUST be set or startup fails. The
+	// bearer path is M2M-only: it accepts validated access-token JWTs, rejects
+	// ID tokens, and forwards principal headers downstream without creating a
+	// cookie session. See docs/BEARER_AUTH.md for the threat model.
+	EnableBearerAuth bool `json:"enableBearerAuth,omitempty"`
+	// BearerIdentifierClaim names the JWT claim used as the principal identifier
+	// on the bearer-token auth path. Default "sub". Decoupled from
+	// UserIdentifierClaim (which defaults to "email" and drives the cookie path)
+	// so M2M bearer flow never accidentally relies on an unverified email.
+	BearerIdentifierClaim string `json:"bearerIdentifierClaim,omitempty"`
+	// StripAuthorizationHeader removes the Authorization header from the
+	// forwarded request after successful bearer auth, so downstream services
+	// never see the raw token. Default true. Disable only when a downstream
+	// explicitly needs to re-validate the bearer.
+	StripAuthorizationHeader bool `json:"stripAuthorizationHeader,omitempty"`
+	// BearerEmitWWWAuthenticate controls whether 401 responses on the bearer
+	// path include a WWW-Authenticate: Bearer error="invalid_token" hint per
+	// RFC 6750 §3. Default true. Disable to reduce reconnaissance signal.
+	BearerEmitWWWAuthenticate bool `json:"bearerEmitWWWAuthenticate,omitempty"`
+	// BearerOverridesCookie controls precedence when both Authorization:
+	// Bearer and a session cookie are present. Default false: cookie wins
+	// (safer against browser/extension/proxy bearer injection). Set true for
+	// the bearer-wins convention used by AWS/GCP/Kubernetes API gateways.
+	BearerOverridesCookie bool `json:"bearerOverridesCookie,omitempty"`
+	// MaxTokenAgeSeconds caps how old (iat-based) a bearer token may be.
+	// Default 86400 (24h). Bounds clock-manipulation tokens with implausibly
+	// distant iat values.
+	MaxTokenAgeSeconds int64 `json:"maxTokenAgeSeconds,omitempty"`
+	// MaxIdentifierLength bounds the post-sanitisation length of the bearer
+	// principal identifier (the value injected as X-Forwarded-User). Default
+	// 256.
+	MaxIdentifierLength int `json:"maxIdentifierLength,omitempty"`
+	// BearerFailureThreshold is the number of consecutive 401s from one
+	// source IP within BearerFailureWindowSeconds that trips the throttle.
+	// Default 20.
+	BearerFailureThreshold int `json:"bearerFailureThreshold,omitempty"`
+	// BearerFailureWindowSeconds is the rolling window (seconds) over which
+	// 401s are counted for throttling. Default 60.
+	BearerFailureWindowSeconds int `json:"bearerFailureWindowSeconds,omitempty"`
+	// BearerFailurePenaltySeconds is how long an IP is parked in the 429
+	// penalty box after BearerFailureThreshold is exceeded. Default 60.
+	BearerFailurePenaltySeconds int `json:"bearerFailurePenaltySeconds,omitempty"`
 }
 
 // loadCACertPool assembles an x509.CertPool from CACertPath and CACertPEM.
@@ -291,6 +339,19 @@ func CreateConfig() *Config {
 		MaxRefreshTokenAgeSeconds: 21600, // 6h - conservative heuristic, see field doc
 		SecurityHeaders:           createDefaultSecurityConfig(),
 		Redis:                     nil, // Redis is disabled by default, configure via Traefik or env vars
+
+		// Bearer-auth defaults. EnableBearerAuth=false leaves the feature
+		// dormant; the rest are values that apply only when bearer is enabled.
+		EnableBearerAuth:            false,
+		BearerIdentifierClaim:       "sub",
+		StripAuthorizationHeader:    true,
+		BearerEmitWWWAuthenticate:   true,
+		BearerOverridesCookie:       false,
+		MaxTokenAgeSeconds:          86400,
+		MaxIdentifierLength:         256,
+		BearerFailureThreshold:      20,
+		BearerFailureWindowSeconds:  60,
+		BearerFailurePenaltySeconds: 60,
 	}
 
 	return c
@@ -702,7 +763,32 @@ func validateTemplateSecure(templateStr string) error {
 // Returns true if the URL is valid and secure (HTTPS), false otherwise.
 func isValidSecureURL(s string) bool {
 	u, err := url.Parse(s)
-	return err == nil && u.Scheme == "https" && u.Host != ""
+	if err != nil || u.Host == "" {
+		return false
+	}
+	if u.Scheme == "https" {
+		return true
+	}
+	// Permit plaintext HTTP only for loopback hosts (local development,
+	// in-cluster sidecar providers, tests). Loopback traffic never leaves the
+	// host, so it is not exposed to network MITM; remote providers must use
+	// HTTPS. Mirrors the RFC 8252 loopback allowance.
+	if u.Scheme == "http" && isLoopbackHost(u.Hostname()) {
+		return true
+	}
+	return false
+}
+
+// isLoopbackHost reports whether host is "localhost" or a loopback IP literal
+// (127.0.0.0/8 or ::1).
+func isLoopbackHost(host string) bool {
+	if strings.EqualFold(host, "localhost") {
+		return true
+	}
+	if ip := net.ParseIP(host); ip != nil {
+		return ip.IsLoopback()
+	}
+	return false
 }
 
 // isValidLogLevel checks if the provided log level string is one of the supported values ("debug", "info", "error").

singleton_resources.go

@@ -106,8 +106,9 @@ func (rm *ResourceManager) GetCache(key string) interface{} {
 	case "jwk-cache":
 		cache = cacheManager.GetSharedJWKCache()
 	default:
-		// Generic cache implementation
-		cache = NewGenericCache(1*time.Hour, rm.logger)
+		// Generic cache implementation; bind cleanup goroutine to the manager's
+		// shutdown channel so it exits when the ResourceManager shuts down.
+		cache = newGenericCacheWithOwner(1*time.Hour, rm.logger, rm.shutdownChan)
 	}
 
 	rm.caches[key] = cache
@@ -263,6 +264,19 @@ func (rm *ResourceManager) cleanupInstance(instanceID string) {
 	// This is a hook for future instance-specific cleanup needs
 }
 
+// liveInstanceCount tracks the number of fully-constructed TraefikOidc plugin
+// instances alive in this process. Process-global singleton tasks (such as the
+// shared token-cleanup) must only be stopped when the LAST instance shuts down,
+// otherwise one instance's teardown would disable them for all survivors.
+var liveInstanceCount int32
+
+// registerLiveInstance records a newly constructed plugin instance.
+func registerLiveInstance() { atomic.AddInt32(&liveInstanceCount, 1) }
+
+// unregisterLiveInstance records a plugin instance shutting down and returns the
+// number of instances still alive afterwards.
+func unregisterLiveInstance() int32 { return atomic.AddInt32(&liveInstanceCount, -1) }
+
 // Shutdown gracefully shuts down all managed resources
 func (rm *ResourceManager) Shutdown(ctx context.Context) error {
 	var err error
@@ -501,20 +515,31 @@ func (p *GoroutinePool) Shutdown(ctx context.Context) error {
 
 // GenericCache provides a simple cache implementation for testing
 type GenericCache struct {
-	data     map[string]interface{}
-	logger   *Logger
-	stopChan chan struct{}
-	ttl      time.Duration
-	mu       sync.RWMutex
+	data map[string]interface{}
+	// ownerStopChan, when non-nil, signals the cleanup goroutine to exit when
+	// the owning ResourceManager shuts down, so the goroutine cannot outlive it.
+	ownerStopChan <-chan struct{}
+	logger        *Logger
+	stopChan      chan struct{}
+	ttl           time.Duration
+	mu            sync.RWMutex
 }
 
 // NewGenericCache creates a new generic cache
 func NewGenericCache(ttl time.Duration, logger *Logger) *GenericCache {
+	return newGenericCacheWithOwner(ttl, logger, nil)
+}
+
+// newGenericCacheWithOwner creates a generic cache whose cleanup goroutine also
+// exits when ownerStopChan is closed (typically the ResourceManager shutdown
+// channel), guaranteeing the goroutine is stoppable on shutdown.
+func newGenericCacheWithOwner(ttl time.Duration, logger *Logger, ownerStopChan <-chan struct{}) *GenericCache {
 	cache := &GenericCache{
-		data:     make(map[string]interface{}),
-		ttl:      ttl,
-		logger:   logger,
-		stopChan: make(chan struct{}),
+		data:          make(map[string]interface{}),
+		ttl:           ttl,
+		logger:        logger,
+		stopChan:      make(chan struct{}),
+		ownerStopChan: ownerStopChan,
 	}
 
 	// Start cleanup routine
@@ -570,6 +595,11 @@ func (gc *GenericCache) cleanupRoutine() {
 			gc.mu.Unlock()
 		case <-gc.stopChan:
 			return
+		case <-gc.ownerStopChan:
+			// Owning ResourceManager is shutting down; exit so the goroutine
+			// does not outlive its owner. A nil channel blocks forever, so this
+			// case is inert when no owner is set.
+			return
 		}
 	}
 }

singleton_resources_test.go

@@ -296,9 +296,12 @@ func TestContextAwareGoroutineManagement(t *testing.T) {
 
 		// Create a TraefikOidc instance with context
 		config := &Config{
-			ProviderURL:  mockServer.URL,
-			ClientID:     "test-client",
-			ClientSecret: "test-secret",
+			ProviderURL:          mockServer.URL,
+			ClientID:             "test-client",
+			ClientSecret:         "test-secret",
+			CallbackURL:          "/callback",
+			SessionEncryptionKey: "test-encryption-key-32-bytes-long",
+			RateLimit:            100,
 		}
 
 		plugin, err := NewWithContext(ctx, config, nil, "test")
@@ -350,9 +353,9 @@ func TestContextAwareGoroutineManagement(t *testing.T) {
 		initialGoroutines := runtime.NumGoroutine()
 
 		configs := []Config{
-			{ProviderURL: mockServer1.URL, ClientID: "client1", ClientSecret: "secret1"},
-			{ProviderURL: mockServer2.URL, ClientID: "client2", ClientSecret: "secret2"},
-			{ProviderURL: mockServer3.URL, ClientID: "client3", ClientSecret: "secret3"},
+			{ProviderURL: mockServer1.URL, ClientID: "client1", ClientSecret: "secret1", CallbackURL: "/callback", SessionEncryptionKey: "test-encryption-key-32-bytes-long", RateLimit: 100},
+			{ProviderURL: mockServer2.URL, ClientID: "client2", ClientSecret: "secret2", CallbackURL: "/callback", SessionEncryptionKey: "test-encryption-key-32-bytes-long", RateLimit: 100},
+			{ProviderURL: mockServer3.URL, ClientID: "client3", ClientSecret: "secret3", CallbackURL: "/callback", SessionEncryptionKey: "test-encryption-key-32-bytes-long", RateLimit: 100},
 		}
 
 		var plugins []*TraefikOidc
@@ -432,9 +435,12 @@ func TestContextAwareGoroutineManagement(t *testing.T) {
 		for i := 0; i < 3; i++ {
 			ctx := context.Background()
 			config := &Config{
-				ProviderURL:  mockServers[i].URL,
-				ClientID:     fmt.Sprintf("client%d", i),
-				ClientSecret: fmt.Sprintf("secret%d", i),
+				ProviderURL:          mockServers[i].URL,
+				ClientID:             fmt.Sprintf("client%d", i),
+				ClientSecret:         fmt.Sprintf("secret%d", i),
+				CallbackURL:          "/callback",
+				SessionEncryptionKey: "test-encryption-key-32-bytes-long",
+				RateLimit:            100,
 			}
 
 			plugin, err := NewWithContext(ctx, config, nil, fmt.Sprintf("test-%d", i))
@@ -595,9 +601,12 @@ func TestBackwardCompatibility(t *testing.T) {
 	t.Run("LegacyNewFunction", func(t *testing.T) {
 		// Test that the original New function still works
 		config := &Config{
-			ProviderURL:  "https://example.com",
-			ClientID:     "test-client",
-			ClientSecret: "test-secret",
+			ProviderURL:          "https://example.com",
+			ClientID:             "test-client",
+			ClientSecret:         "test-secret",
+			CallbackURL:          "/callback",
+			SessionEncryptionKey: "test-encryption-key-32-bytes-long",
+			RateLimit:            100,
 		}
 
 		handler, err := New(context.Background(), nil, config, "test")
@@ -617,9 +626,12 @@ func TestBackwardCompatibility(t *testing.T) {
 
 	t.Run("ExistingAPICompatibility", func(t *testing.T) {
 		config := &Config{
-			ProviderURL:  "https://example.com",
-			ClientID:     "test-client",
-			ClientSecret: "test-secret",
+			ProviderURL:          "https://example.com",
+			ClientID:             "test-client",
+			ClientSecret:         "test-secret",
+			CallbackURL:          "/callback",
+			SessionEncryptionKey: "test-encryption-key-32-bytes-long",
+			RateLimit:            100,
 		}
 
 		handler, _ := New(context.Background(), nil, config, "test")

token_introspection.go

@@ -21,13 +21,16 @@ type IntrospectionResponse struct {
 	Username  string `json:"username,omitempty"`
 	TokenType string `json:"token_type,omitempty"`
 	Sub       string `json:"sub,omitempty"`
-	Aud       string `json:"aud,omitempty"`
-	Iss       string `json:"iss,omitempty"`
-	Jti       string `json:"jti,omitempty"`
-	Exp       int64  `json:"exp,omitempty"`
-	Iat       int64  `json:"iat,omitempty"`
-	Nbf       int64  `json:"nbf,omitempty"`
-	Active    bool   `json:"active"`
+	// Aud holds the introspection audience. Per RFC 7662 it may be a single
+	// string or an array of strings, so it is decoded as interface{} and
+	// matched with verifyAudience (which handles both shapes).
+	Aud    interface{} `json:"aud,omitempty"`
+	Iss    string      `json:"iss,omitempty"`
+	Jti    string      `json:"jti,omitempty"`
+	Exp    int64       `json:"exp,omitempty"`
+	Iat    int64       `json:"iat,omitempty"`
+	Nbf    int64       `json:"nbf,omitempty"`
+	Active bool        `json:"active"`
 }
 
 // introspectToken performs OAuth 2.0 Token Introspection (RFC 7662) for an opaque token.
@@ -120,7 +123,7 @@ func (t *TraefikOidc) introspectToken(token string) (*IntrospectionResponse, err
 
 	// Parse response per RFC 7662 Section 2.2
 	var introspectionResp IntrospectionResponse
-	if err := json.NewDecoder(resp.Body).Decode(&introspectionResp); err != nil {
+	if err := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&introspectionResp); err != nil {
 		return nil, fmt.Errorf("failed to decode introspection response: %w", err)
 	}
 
@@ -128,6 +131,12 @@ func (t *TraefikOidc) introspectToken(token string) (*IntrospectionResponse, err
 	if t.introspectionCache != nil {
 		// Cache for a short duration or until token expiry (whichever is shorter)
 		cacheDuration := 5 * time.Minute
+		// When introspection is REQUIRED, operators expect near-real-time
+		// revocation; cap the positive-result cache so a token revoked at the
+		// provider cannot keep passing for the full 5 minutes (rank 8).
+		if t.requireTokenIntrospection && cacheDuration > 30*time.Second {
+			cacheDuration = 30 * time.Second
+		}
 		if introspectionResp.Exp > 0 {
 			expTime := time.Unix(introspectionResp.Exp, 0)
 			untilExp := time.Until(expTime)
@@ -197,12 +206,18 @@ func (t *TraefikOidc) validateOpaqueToken(token string) error {
 		}
 	}
 
-	// Validate audience if configured
-	// Note: For opaque tokens, audience validation via introspection may be limited
-	// depending on what the introspection endpoint returns
-	if t.audience != "" && t.audience != t.clientID && resp.Aud != "" {
-		if resp.Aud != t.audience {
-			return fmt.Errorf("invalid audience: expected %s, got %s", t.audience, resp.Aud)
+	// Validate audience if configured. When a distinct API audience is
+	// configured (audience != clientID), the introspection response MUST carry
+	// a matching audience. Fail closed on a missing or mismatched aud: a token
+	// whose audience cannot be confirmed must not be accepted, otherwise a
+	// token minted for a different audience would pass. aud may be a single
+	// string or an array of strings (RFC 7662); verifyAudience handles both.
+	if t.audience != "" && t.audience != t.clientID {
+		if resp.Aud == nil {
+			return fmt.Errorf("invalid audience: expected %s, introspection response has no audience", t.audience)
+		}
+		if err := verifyAudience(resp.Aud, t.audience); err != nil {
+			return fmt.Errorf("invalid audience: expected %s: %w", t.audience, err)
 		}
 	}
 

token_manager.go

@@ -5,8 +5,8 @@ package traefikoidc
 
 import (
 	"context"
-	"encoding/base64"
-	"encoding/json"
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
 	"io"
 	"net/http"
@@ -29,6 +29,29 @@ import (
 //
 //nolint:gocognit,gocyclo // Complex token verification logic requires multiple security checks
 func (t *TraefikOidc) VerifyToken(token string) error {
+	return t.verifyTokenWithOpts(token, verifyOpts{})
+}
+
+// verifyOpts are internal-only knobs for verifyTokenWithOpts. Kept unexported
+// because they expose subtle replay-protection semantics that are dangerous
+// to misuse.
+type verifyOpts struct {
+	// skipReplayMarking suppresses the JTI -> blacklist Set near the bottom
+	// of verifyTokenWithOpts. The Get at the top remains active, so revoked
+	// tokens (added to the blacklist by RevokeToken) are still rejected.
+	// Used exclusively by the bearer-auth path, where bearer tokens are
+	// designed to be reused until exp.
+	skipReplayMarking bool
+}
+
+// verifyTokenWithOpts runs the full token verification pipeline used by both
+// the cookie path and the bearer path. The cookie path uses the zero-value
+// opts; the bearer path sets skipReplayMarking=true. See the security spec
+// (docs/superpowers/specs/2026-05-18-bearer-token-auth-design.md §7.7) for
+// the exact contract: skipReplayMarking gates ONLY the JTI Set, never the Get.
+//
+//nolint:gocognit,gocyclo // Complex token verification logic requires multiple security checks
+func (t *TraefikOidc) verifyTokenWithOpts(token string, opts verifyOpts) error {
 	if token == "" {
 		return fmt.Errorf("invalid JWT format: token is empty")
 	}
@@ -76,7 +99,9 @@ func (t *TraefikOidc) VerifyToken(token string) error {
 	}
 
 	// Only check JTI blacklist for tokens that aren't already in the cache
-	// This is for FIRST-TIME validation to detect replay attacks
+	// This is for FIRST-TIME validation to detect replay attacks. The
+	// blacklist Get is ALWAYS active on the bearer path too — only the
+	// Set below is gated by opts.skipReplayMarking.
 	if jti, ok := parsedJWT.Claims["jti"].(string); ok && jti != "" {
 		// Skip JTI blacklist check if replay detection is disabled
 		if !t.disableReplayDetection {
@@ -105,8 +130,12 @@ func (t *TraefikOidc) VerifyToken(token string) error {
 
 	t.cacheVerifiedToken(token, jwt.Claims)
 
-	if jti, ok := jwt.Claims["jti"].(string); ok && jti != "" && !t.disableReplayDetection {
-		// Only add to blacklist if replay detection is enabled
+	// Replay marking: add JTI to blacklist so subsequent presentations of
+	// the SAME token can short-circuit via cache. Bearer path suppresses
+	// this Set (opts.skipReplayMarking=true) because bearer tokens are
+	// designed for reuse until exp; the cache-evict-then-replay scenario
+	// would otherwise trigger false replay detection.
+	if jti, ok := jwt.Claims["jti"].(string); ok && jti != "" && !t.disableReplayDetection && !opts.skipReplayMarking {
 		expiry := time.Now().Add(defaultBlacklistDuration)
 		if expClaim, expOk := jwt.Claims["exp"].(float64); expOk {
 			expTime := time.Unix(int64(expClaim), 0)
@@ -185,11 +214,13 @@ func (t *TraefikOidc) cacheVerifiedToken(token string, claims map[string]interfa
 //
 //nolint:gocognit,gocyclo // Complex token type detection with multiple provider-specific checks
 func (t *TraefikOidc) detectTokenType(jwt *JWT, token string) bool {
-	// Use first 32 chars of token as cache key (sufficient for uniqueness)
-	cacheKey := token
-	if len(token) > 32 {
-		cacheKey = token[:32]
-	}
+	// Key on a hash of the FULL token. The first 32 characters of a JWT are
+	// only the base64url-encoded header, which is identical for every token
+	// sharing the same alg+kid, so distinct tokens (e.g. an ID token and an
+	// access token from the same issuer) would otherwise collide on the cache
+	// key and be mis-classified.
+	sum := sha256.Sum256([]byte(token))
+	cacheKey := hex.EncodeToString(sum[:])
 
 	// Check cache first
 	if t.tokenTypeCache != nil {
@@ -341,7 +372,17 @@ func (t *TraefikOidc) VerifyJWTSignatureAndClaims(jwt *JWT, token string) error
 
 	if err := verifySignatureWithKey(token, pubKey, alg); err != nil {
 		if !t.suppressDiagnosticLogs {
-			t.safeLogErrorf("DIAGNOSTIC: Signature verification failed for kid=%s, alg=%s: %v", kid, alg, err)
+			// Microsoft Graph access tokens carry a `nonce` JWT header and are
+			// signed in a proprietary form Microsoft documents as unverifiable
+			// by client applications. They reach this path only when the
+			// per-provider classifier (validateAzureTokens) didn't catch them,
+			// so log at debug to keep the error stream actionable while still
+			// surfacing the cause for diagnostics.
+			if _, isMSProprietary := jwt.Header["nonce"]; isMSProprietary {
+				t.safeLogDebugf("DIAGNOSTIC: Signature verification failed for kid=%s, alg=%s (Microsoft proprietary nonce header — token is opaque to clients): %v", kid, alg, err)
+			} else {
+				t.safeLogErrorf("DIAGNOSTIC: Signature verification failed for kid=%s, alg=%s: %v", kid, alg, err)
+			}
 		}
 		return fmt.Errorf("signature verification failed: %w", err)
 	}
@@ -785,6 +826,27 @@ func (t *TraefikOidc) isGoogleProvider() bool {
 	return strings.Contains(issuerURL, "google") || strings.Contains(issuerURL, "accounts.google.com")
 }
 
+// isUnverifiableAzureAccessToken reports whether a JWT-shaped access token
+// matches the Microsoft proprietary format that client applications must not
+// validate. Microsoft injects a `nonce` value into the JWT header, signs over
+// the SHA256 hash of that nonce, and ships the original nonce on the wire,
+// guaranteeing that any standard JWS verifier rejects the signature. This is
+// the documented mechanism that keeps access tokens opaque to non-resource
+// holders (Microsoft Graph, Azure Management API).
+//
+// https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens
+//
+// Returns true on parse failure as well — a token we cannot parse should not
+// be passed through the verification path that emits ERROR logs.
+func (t *TraefikOidc) isUnverifiableAzureAccessToken(token string) bool {
+	parsed, err := parseJWT(token)
+	if err != nil {
+		return true
+	}
+	_, hasProprietaryNonce := parsed.Header["nonce"]
+	return hasProprietaryNonce
+}
+
 // isAzureProvider detects if the configured OIDC provider is Azure AD.
 // It checks the issuer URL for Microsoft Azure AD domains.
 // Returns:
@@ -800,413 +862,6 @@ func (t *TraefikOidc) isAzureProvider() bool {
 		strings.Contains(issuerURL, "login.windows.net")
 }
 
-// validateAzureTokens validates tokens with Azure AD-specific logic.
-// Azure tokens may be opaque access tokens that cannot be verified as JWTs,
-// so this method handles both JWT and opaque token scenarios.
-// Parameters:
-//   - session: The session data containing tokens to validate.
-//
-// Returns:
-//   - authenticated: Whether the user has valid authentication.
-//   - needsRefresh: Whether tokens need to be refreshed.
-//   - expired: Whether tokens have expired and cannot be refreshed.
-//
-//nolint:gocognit // Azure-specific validation requires multiple token type checks
-func (t *TraefikOidc) validateAzureTokens(session *SessionData) (bool, bool, bool) {
-	if !session.GetAuthenticated() {
-		t.logger.Debug("Azure user is not authenticated according to session flag")
-		if session.GetRefreshToken() != "" {
-			t.logger.Debug("Azure session not authenticated, but refresh token exists. Signaling need for refresh.")
-			return false, true, false
-		}
-		return false, true, false
-	}
-
-	accessToken := session.GetAccessToken()
-	idToken := session.GetIDToken()
-
-	if accessToken != "" {
-		if strings.Count(accessToken, ".") == 2 {
-			if err := t.verifyToken(accessToken); err != nil {
-				if idToken != "" {
-					if err := t.verifyToken(idToken); err != nil {
-						t.logger.Debugf("Azure: Both access and ID token validation failed: %v", err)
-						if session.GetRefreshToken() != "" {
-							return false, true, false
-						}
-						return false, false, true
-					}
-					return t.validateTokenExpiry(session, idToken)
-				}
-				if session.GetRefreshToken() != "" {
-					return false, true, false
-				}
-				return false, false, true
-			}
-			return t.validateTokenExpiry(session, accessToken)
-		}
-		t.logger.Debug("Azure access token appears opaque, treating as valid")
-		if idToken != "" {
-			return t.validateTokenExpiry(session, idToken)
-		}
-		return true, false, false
-	}
-
-	if idToken != "" {
-		if err := t.verifyToken(idToken); err != nil {
-			if strings.Contains(err.Error(), "token has expired") {
-				if session.GetRefreshToken() != "" {
-					return false, true, false
-				}
-				return false, false, true
-			}
-			if session.GetRefreshToken() != "" {
-				return false, true, false
-			}
-			return false, false, true
-		}
-		return t.validateTokenExpiry(session, idToken)
-	}
-
-	if session.GetRefreshToken() != "" {
-		return false, true, false
-	}
-	return false, false, true
-}
-
-// validateGoogleTokens handles Google-specific token validation logic.
-// Currently delegates to standard token validation but provides a hook
-// for Google-specific validation requirements in the future.
-// Parameters:
-//   - session: The session data containing tokens to validate.
-//
-// Returns:
-//   - authenticated: Whether the user has valid authentication.
-//   - needsRefresh: Whether tokens need to be refreshed.
-//   - expired: Whether tokens have expired and cannot be refreshed.
-func (t *TraefikOidc) validateGoogleTokens(session *SessionData) (bool, bool, bool) {
-	return t.validateStandardTokens(session)
-}
-
-// validateStandardTokens handles standard OIDC token validation logic.
-// This is the default validation method for generic OIDC providers.
-// It verifies ID tokens and handles access tokens appropriately.
-// Parameters:
-//   - session: The session data containing tokens to validate.
-//
-// Returns:
-//   - authenticated: Whether the user has valid authentication.
-//   - needsRefresh: Whether tokens need to be refreshed.
-//   - expired: Whether tokens have expired and cannot be refreshed.
-//
-//nolint:gocognit,gocyclo // Complex validation logic handles multiple token scenarios and edge cases
-func (t *TraefikOidc) validateStandardTokens(session *SessionData) (bool, bool, bool) {
-	authenticated := session.GetAuthenticated()
-	// Removed debug output
-	if !authenticated {
-		t.logger.Debug("User is not authenticated according to session flag")
-		if session.GetRefreshToken() != "" {
-			t.logger.Debug("Session not authenticated, but refresh token exists. Signaling need for refresh.")
-			return false, true, false
-		}
-		return false, false, false
-	}
-
-	accessToken := session.GetAccessToken()
-	// Removed debug output
-	if accessToken == "" {
-		t.logger.Debug("Authenticated flag set, but no access token found in session")
-		if session.GetRefreshToken() != "" {
-			// Check if we have an ID token to determine if we're beyond grace period
-			// When access token is missing, check ID token expiry to determine if refresh is viable
-			idToken := session.GetIDToken()
-			t.logger.Debugf("Checking ID token for grace period: ID token present: %v", idToken != "")
-			if idToken != "" {
-				// Try to parse the ID token to check its expiry
-				parts := strings.Split(idToken, ".")
-				if len(parts) == 3 {
-					// Decode the claims part
-					claimsData, err := base64.RawURLEncoding.DecodeString(parts[1])
-					if err == nil {
-						var claims map[string]interface{}
-						if err := json.Unmarshal(claimsData, &claims); err == nil {
-							if expClaim, ok := claims["exp"].(float64); ok {
-								expTime := time.Unix(int64(expClaim), 0)
-								if time.Now().After(expTime) {
-									expiredDuration := time.Since(expTime)
-									if expiredDuration > t.refreshGracePeriod {
-										t.logger.Debugf("ID token expired beyond grace period (%v > %v), must re-authenticate",
-											expiredDuration, t.refreshGracePeriod)
-										return false, false, true // expired, cannot refresh
-									}
-									t.logger.Debugf("ID token expired %v ago, within grace period %v, allowing refresh",
-										expiredDuration, t.refreshGracePeriod)
-								}
-							}
-						}
-					}
-				}
-			}
-			t.logger.Debug("Access token missing, but refresh token exists. Signaling need for refresh.")
-			return false, true, false
-		}
-		return false, false, true
-	}
-
-	// Check if access token is opaque (doesn't have JWT structure)
-	dotCount := strings.Count(accessToken, ".")
-	isOpaqueToken := dotCount != 2
-
-	// For opaque access tokens, use introspection if available (RFC 7662 - Option C: Scenario 3)
-	if isOpaqueToken {
-		t.logger.Debugf("Access token appears to be opaque (dots: %d)", dotCount)
-
-		// Try introspection first if opaque tokens are allowed
-		if t.allowOpaqueTokens {
-			if err := t.validateOpaqueToken(accessToken); err != nil {
-				errMsg := err.Error()
-				t.logger.Infof("⚠️  Opaque access token validation via introspection failed: %v", err)
-
-				// Check if the token was explicitly marked as inactive/revoked/expired by the provider
-				// In these cases, we should NOT fall back to ID token - the provider has explicitly
-				// told us this token is no longer valid. We must refresh or re-authenticate.
-				isTokenInvalid := strings.Contains(errMsg, "token is not active") ||
-					strings.Contains(errMsg, "revoked") ||
-					strings.Contains(errMsg, "token has expired")
-
-				if isTokenInvalid {
-					t.logger.Infof("⚠️  Token explicitly marked as invalid by provider, cannot fall back to ID token")
-					if session.GetRefreshToken() != "" {
-						t.logger.Debug("Refresh token available, attempting refresh")
-						return false, true, false
-					}
-					t.logger.Debug("No refresh token available, must re-authenticate")
-					return false, false, true
-				}
-
-				// If introspection required, reject the session
-				if t.requireTokenIntrospection {
-					t.logger.Errorf("❌ SECURITY: Opaque token rejected (introspection required but failed)")
-					if session.GetRefreshToken() != "" {
-						return false, true, false
-					}
-					return false, false, true
-				}
-
-				// Only fall back to ID token validation for transient errors (network issues, etc.)
-				// where the introspection endpoint couldn't be reached
-				t.logger.Infof("⚠️  Falling back to ID token validation for opaque access token (transient error)")
-			} else {
-				// Introspection successful
-				t.logger.Debugf("✓ Opaque access token validated via introspection")
-				// Still need to check ID token for session expiry
-				idToken := session.GetIDToken()
-				if idToken != "" {
-					return t.validateTokenExpiry(session, idToken)
-				}
-				return true, false, false
-			}
-		} else {
-			// Opaque tokens not allowed - log warning and reject or fall back
-			t.logger.Infof("⚠️  Opaque access token detected but allowOpaqueTokens=false")
-		}
-
-		// Fall back to ID token validation
-		idToken := session.GetIDToken()
-		if idToken == "" {
-			t.logger.Debug("Opaque access token present but no ID token found")
-			if session.GetRefreshToken() != "" {
-				t.logger.Debug("ID token missing but refresh token exists. Signaling need for refresh.")
-				return false, true, false
-			}
-			// Accept session with opaque access token even without ID token
-			// The OAuth provider validated it when issued
-			t.logger.Debug("Accepting session with opaque access token")
-			return true, false, false
-		}
-
-		// Validate ID token if present
-		if err := t.verifyToken(idToken); err != nil {
-			if strings.Contains(err.Error(), "token has expired") {
-				t.logger.Debugf("ID token expired with opaque access token, needs refresh")
-				if session.GetRefreshToken() != "" {
-					return false, true, false
-				}
-				return false, false, true
-			}
-
-			t.logger.Errorf("ID token verification failed with opaque access token: %v", err)
-			if session.GetRefreshToken() != "" {
-				return false, true, false
-			}
-			return false, false, true
-		}
-
-		// Use ID token for expiry validation
-		return t.validateTokenExpiry(session, idToken)
-	}
-
-	// JWT access token present - validate it explicitly to detect Scenario 2
-	// (Option C: Scenario 2 detection and strict mode)
-	accessTokenValid := false
-	accessTokenError := ""
-
-	if err := t.verifyToken(accessToken); err != nil {
-		// Access token validation failed
-		accessTokenError = err.Error()
-
-		// Check if it's an audience validation failure (Scenario 2)
-		if strings.Contains(accessTokenError, "invalid audience") || strings.Contains(accessTokenError, "audience") {
-			// SCENARIO 2 DETECTED: Access token has wrong audience
-			t.logger.Infof("⚠️  SCENARIO 2 DETECTED: Access token validation failed due to audience mismatch: %v", err)
-
-			if t.strictAudienceValidation {
-				// Strict mode: Reject the session (don't fall back to ID token)
-				t.logger.Errorf("❌ SECURITY: Session rejected due to access token audience mismatch (strictAudienceValidation=true)")
-				t.logger.Errorf("❌ This prevents potential cross-API token confusion attacks (Auth0 Scenario 2)")
-				if session.GetRefreshToken() != "" {
-					return false, true, false // try refresh
-				}
-				return false, false, true // must re-authenticate
-			}
-			// Backward compatibility mode: Log loud warning but allow fallback to ID token
-			t.logger.Infof("⚠️⚠️⚠️  SECURITY WARNING: Falling back to ID token validation despite access token audience mismatch!")
-			t.logger.Infof("⚠️  This could allow tokens intended for different APIs to grant access")
-			t.logger.Infof("⚠️  Set strictAudienceValidation=true to enforce proper audience validation")
-			t.logger.Infof("⚠️  See: https://github.com/lukaszraczylo/traefikoidc/issues/74")
-		} else if !strings.Contains(accessTokenError, "token has expired") {
-			// Other validation errors (not expiration, not audience)
-			t.logger.Debugf("Access token validation failed (non-expiration, non-audience): %v", err)
-		}
-	} else {
-		// Access token is valid
-		accessTokenValid = true
-	}
-
-	idToken := session.GetIDToken()
-	if idToken == "" {
-		if accessTokenValid {
-			// Access token is valid, no ID token needed
-			t.logger.Debug("Access token valid, no ID token present")
-			return t.validateTokenExpiry(session, accessToken)
-		}
-
-		t.logger.Debug("Authenticated flag set with access token, but no ID token found in session")
-		if session.GetRefreshToken() != "" {
-			t.logger.Debug("ID token missing but refresh token exists. Signaling conditional refresh to obtain ID token.")
-			return true, true, false
-		}
-		return true, false, false
-	}
-
-	// Validate ID token
-	if err := t.verifyToken(idToken); err != nil {
-		if strings.Contains(err.Error(), "token has expired") {
-			t.logger.Debugf("ID token signature/claims valid but token expired, needs refresh")
-			if session.GetRefreshToken() != "" {
-				return false, true, false
-			}
-			return false, false, true
-		}
-
-		t.logger.Errorf("ID token verification failed (non-expiration): %v", err)
-		if session.GetRefreshToken() != "" {
-			t.logger.Debug("ID token verification failed, but refresh token exists. Signaling need for refresh.")
-			return false, true, false
-		}
-		return false, false, true
-	}
-
-	// If access token was valid, use it for expiry; otherwise use ID token
-	if accessTokenValid {
-		return t.validateTokenExpiry(session, accessToken)
-	}
-
-	return t.validateTokenExpiry(session, idToken)
-}
-
-// validateTokenExpiry checks if a token is nearing expiration and needs refresh.
-// It uses the configured grace period to determine when proactive refresh should occur.
-// Parameters:
-//   - session: The session data for refresh token availability.
-//   - token: The token to check expiry for.
-//
-// Returns:
-//   - authenticated: Whether the token is currently valid.
-//   - needsRefresh: Whether the token is nearing expiration and should be refreshed.
-//   - expired: Whether the token is invalid or verification failed.
-func (t *TraefikOidc) validateTokenExpiry(session *SessionData, token string) (bool, bool, bool) {
-	cachedClaims, found := t.tokenCache.Get(token)
-	if !found {
-		t.logger.Debug("Claims not found in cache after successful token verification")
-		if session.GetRefreshToken() != "" {
-			t.logger.Debug("Claims missing post-verification, attempting refresh to recover.")
-			return false, true, false
-		}
-		return false, false, true
-	}
-
-	expClaim, ok := cachedClaims["exp"].(float64)
-	if !ok {
-		t.logger.Error("Failed to get expiration time ('exp' claim) from verified token")
-		if session.GetRefreshToken() != "" {
-			t.logger.Debug("Token missing 'exp' claim, but refresh token exists. Signaling need for refresh.")
-			return false, true, false
-		}
-		return false, false, true
-	}
-
-	expTime := int64(expClaim)
-	expTimeObj := time.Unix(expTime, 0)
-	nowObj := time.Now()
-
-	// Check if token has already expired
-	if expTimeObj.Before(nowObj) {
-		// Token has expired
-		expiredDuration := nowObj.Sub(expTimeObj)
-
-		t.logger.Debugf("Token expired %v ago, grace period is %v",
-			expiredDuration, t.refreshGracePeriod)
-
-		// If we have a refresh token, always attempt to use it regardless of grace period
-		// The refresh token has its own expiry and the provider will reject it if invalid
-		if session.GetRefreshToken() != "" {
-			t.logger.Debugf("Token expired, attempting refresh with available refresh token")
-			return false, true, false // needs refresh
-		}
-
-		// No refresh token available - must re-authenticate
-		t.logger.Debugf("Token expired and no refresh token available, must re-authenticate")
-		return false, false, true // expired, cannot refresh
-	}
-
-	// Token not yet expired - check if nearing expiration
-	refreshThreshold := nowObj.Add(t.refreshGracePeriod)
-
-	t.logger.Debugf("Token expires at %v, now is %v, refresh threshold is %v",
-		expTimeObj.Format(time.RFC3339),
-		nowObj.Format(time.RFC3339),
-		refreshThreshold.Format(time.RFC3339))
-
-	if expTimeObj.Before(refreshThreshold) {
-		remainingSeconds := int64(time.Until(expTimeObj).Seconds())
-		t.logger.Debugf("Token nearing expiration (expires in %d seconds, grace period %s), scheduling proactive refresh",
-			remainingSeconds, t.refreshGracePeriod)
-
-		if session.GetRefreshToken() != "" {
-			return true, true, false
-		}
-
-		t.logger.Debugf("Token nearing expiration but no refresh token available, cannot proactively refresh.")
-		return true, false, false
-	}
-
-	t.logger.Debugf("Token is valid and not nearing expiration (expires in %d seconds, outside %s grace period)",
-		int64(time.Until(expTimeObj).Seconds()), t.refreshGracePeriod)
-
-	return true, false, false
-}
-
 // startTokenCleanup starts background cleanup goroutines for cache maintenance.
 // It runs periodic cleanup of token cache, JWK cache, and session chunks.
 // Includes panic recovery to ensure stability.

token_test.go

@@ -3,7 +3,9 @@ package traefikoidc
 import (
 	"bytes"
 	"compress/gzip"
+	"crypto/sha256"
 	"encoding/base64"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -885,10 +887,9 @@ func TestDetectTokenTypeCaching(t *testing.T) {
 		},
 	}
 	token := "test-token-for-caching-with-enough-characters-for-key"
-	cacheKey := token
-	if len(token) > 32 {
-		cacheKey = token[:32]
-	}
+	// The cache key is a SHA-256 hash of the full token (collision-resistant).
+	sum := sha256.Sum256([]byte(token))
+	cacheKey := hex.EncodeToString(sum[:])
 
 	result := tr.detectTokenType(jwt, token)
 	if !result {
@@ -911,521 +912,6 @@ func TestDetectTokenTypeCaching(t *testing.T) {
 	}
 }
 
-// =============================================================================
-// TOKEN VALIDATOR TESTS
-// =============================================================================
-
-func TestNewTokenValidator(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	if validator == nil {
-		t.Fatal("Expected non-nil token validator")
-	}
-
-	if validator.logger == nil {
-		t.Error("Expected logger to be initialized")
-	}
-}
-
-func TestNewTokenValidatorWithLogger(t *testing.T) {
-	logger := GetSingletonNoOpLogger()
-	validator := NewTokenValidator(logger)
-
-	if validator == nil {
-		t.Fatal("Expected non-nil token validator")
-	}
-
-	if validator.logger != logger {
-		t.Error("Expected provided logger to be used")
-	}
-}
-
-func TestValidateTokenEmpty(t *testing.T) {
-	validator := NewTokenValidator(nil)
-	result := validator.ValidateToken("", false)
-
-	if result.Valid {
-		t.Error("Expected invalid result for empty token")
-	}
-
-	if result.Error == nil {
-		t.Error("Expected error for empty token")
-	}
-
-	if !strings.Contains(result.Error.Error(), "empty") {
-		t.Errorf("Expected 'empty' in error, got: %v", result.Error)
-	}
-}
-
-func TestValidateTokenRequireJWT(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	result := validator.ValidateToken("opaque_token_value_here", true)
-
-	if result.Valid {
-		t.Error("Expected invalid result for opaque token when JWT required")
-	}
-
-	if result.Error == nil {
-		t.Error("Expected error when JWT required but opaque token provided")
-	}
-}
-
-func TestValidateJWTValidFormat(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	claims := map[string]interface{}{
-		"sub": "user123",
-		"exp": time.Now().Add(1 * time.Hour).Unix(),
-		"iat": time.Now().Unix(),
-	}
-
-	token := createTestJWTSimple(claims)
-	result := validator.ValidateToken(token, false)
-
-	if !result.Valid {
-		t.Errorf("Expected valid result, got error: %v", result.Error)
-	}
-
-	if result.TokenType != "JWT" {
-		t.Errorf("Expected TokenType 'JWT', got %s", result.TokenType)
-	}
-
-	if result.Claims == nil {
-		t.Error("Expected claims to be parsed")
-	}
-
-	if result.Expiry == nil {
-		t.Error("Expected expiry to be extracted")
-	}
-
-	if result.IssuedAt == nil {
-		t.Error("Expected issued at to be extracted")
-	}
-}
-
-func TestValidateJWTExpiredToken(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	claims := map[string]interface{}{
-		"sub": "user123",
-		"exp": time.Now().Add(-1 * time.Hour).Unix(),
-		"iat": time.Now().Add(-2 * time.Hour).Unix(),
-	}
-
-	token := createTestJWTSimple(claims)
-	result := validator.ValidateToken(token, false)
-
-	if result.Valid {
-		t.Error("Expected invalid result for expired token")
-	}
-
-	if result.Error == nil {
-		t.Error("Expected error for expired token")
-	}
-
-	if !strings.Contains(result.Error.Error(), "expired") {
-		t.Errorf("Expected 'expired' in error, got: %v", result.Error)
-	}
-}
-
-func TestValidateJWTFutureIssuedAt(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	claims := map[string]interface{}{
-		"sub": "user123",
-		"exp": time.Now().Add(2 * time.Hour).Unix(),
-		"iat": time.Now().Add(10 * time.Minute).Unix(),
-	}
-
-	token := createTestJWTSimple(claims)
-	result := validator.ValidateToken(token, false)
-
-	if result.Valid {
-		t.Error("Expected invalid result for future iat")
-	}
-
-	if result.Error == nil {
-		t.Error("Expected error for future iat")
-	}
-
-	if !strings.Contains(result.Error.Error(), "future") {
-		t.Errorf("Expected 'future' in error, got: %v", result.Error)
-	}
-}
-
-func TestValidateJWTNotBeforeClaim(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	claims := map[string]interface{}{
-		"sub": "user123",
-		"exp": time.Now().Add(2 * time.Hour).Unix(),
-		"iat": time.Now().Unix(),
-		"nbf": time.Now().Add(1 * time.Hour).Unix(),
-	}
-
-	token := createTestJWTSimple(claims)
-	result := validator.ValidateToken(token, false)
-
-	if result.Valid {
-		t.Error("Expected invalid result for nbf in future")
-	}
-
-	if result.Error == nil {
-		t.Error("Expected error for nbf in future")
-	}
-
-	if !strings.Contains(result.Error.Error(), "not yet valid") {
-		t.Errorf("Expected 'not yet valid' in error, got: %v", result.Error)
-	}
-}
-
-func TestValidateJWTInvalidFormat(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	tests := []struct {
-		name  string
-		token string
-	}{
-		{"single part", "eyJhbGciOiJIUzI1NiJ9"},
-		{"two parts", "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0In0"},
-		{"four parts", "part1.part2.part3.part4"},
-		{"empty part", "eyJhbGciOiJIUzI1NiJ9..signature"},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.ValidateToken(tt.token, true)
-
-			if result.Valid {
-				t.Error("Expected invalid result for malformed JWT")
-			}
-
-			if result.Error == nil {
-				t.Error("Expected error for malformed JWT")
-			}
-		})
-	}
-}
-
-func TestValidateOpaqueTokenValid(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	token := "sk_live_abcdef123456GHIJKL789"
-	result := validator.ValidateToken(token, false)
-
-	if !result.Valid {
-		t.Errorf("Expected valid result, got error: %v", result.Error)
-	}
-
-	if result.TokenType != "Opaque" {
-		t.Errorf("Expected TokenType 'Opaque', got %s", result.TokenType)
-	}
-}
-
-func TestValidateOpaqueTokenTooShort(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	token := "short"
-	result := validator.ValidateToken(token, false)
-
-	if result.Valid {
-		t.Error("Expected invalid result for short token")
-	}
-
-	if result.Error == nil {
-		t.Error("Expected error for short token")
-	}
-
-	if !strings.Contains(result.Error.Error(), "too short") {
-		t.Errorf("Expected 'too short' in error, got: %v", result.Error)
-	}
-}
-
-func TestValidateOpaqueTokenWithSpaces(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	token := "this token has spaces in it"
-	result := validator.ValidateToken(token, false)
-
-	if result.Valid {
-		t.Error("Expected invalid result for token with spaces")
-	}
-
-	if result.Error == nil {
-		t.Error("Expected error for token with spaces")
-	}
-
-	if !strings.Contains(result.Error.Error(), "spaces") {
-		t.Errorf("Expected 'spaces' in error, got: %v", result.Error)
-	}
-}
-
-func TestValidateOpaqueTokenControlCharacters(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	token := "token_with\x00control_char"
-	result := validator.ValidateToken(token, false)
-
-	if result.Valid {
-		t.Error("Expected invalid result for token with control characters")
-	}
-
-	if result.Error == nil {
-		t.Error("Expected error for token with control characters")
-	}
-
-	if !strings.Contains(result.Error.Error(), "control character") {
-		t.Errorf("Expected 'control character' in error, got: %v", result.Error)
-	}
-}
-
-func TestValidateOpaqueTokenInsufficientEntropy(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	token := "aaaaaabbbbbbccccccdddd"
-	result := validator.ValidateToken(token, false)
-
-	if result.Valid {
-		t.Error("Expected invalid result for low entropy token")
-	}
-
-	if result.Error == nil {
-		t.Error("Expected error for low entropy token")
-	}
-
-	if !strings.Contains(result.Error.Error(), "entropy") {
-		t.Errorf("Expected 'entropy' in error, got: %v", result.Error)
-	}
-}
-
-func TestIsValidBase64URL(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	tests := []struct {
-		name     string
-		input    string
-		expected bool
-	}{
-		{"valid uppercase", "ABCDEFGHIJKLMNOPQRSTUVWXYZ", true},
-		{"valid lowercase", "abcdefghijklmnopqrstuvwxyz", true},
-		{"valid numbers", "0123456789", true},
-		{"valid dash", "abc-def", true},
-		{"valid underscore", "abc_def", true},
-		{"valid equals", "abc=", true},
-		{"invalid at sign", "abc@def", false},
-		{"invalid space", "abc def", false},
-		{"invalid plus", "abc+def", false},
-		{"invalid slash", "abc/def", false},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.isValidBase64URL(tt.input)
-			if result != tt.expected {
-				t.Errorf("Expected %v for %s, got %v", tt.expected, tt.input, result)
-			}
-		})
-	}
-}
-
-func TestExtractTime(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	tests := []struct {
-		claim    interface{}
-		name     string
-		expected bool
-	}{
-		{name: "float64", claim: float64(1609459200), expected: true},
-		{name: "int64", claim: int64(1609459200), expected: true},
-		{name: "int", claim: int(1609459200), expected: true},
-		{name: "string", claim: "not a timestamp", expected: false},
-		{name: "nil", claim: nil, expected: false},
-		{name: "map", claim: map[string]interface{}{}, expected: false},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.extractTime(tt.claim)
-
-			if tt.expected && result == nil {
-				t.Error("Expected non-nil time")
-			}
-
-			if !tt.expected && result != nil {
-				t.Error("Expected nil time")
-			}
-		})
-	}
-}
-
-func TestValidateTokenSize(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	tests := []struct {
-		name        string
-		token       string
-		maxSize     int
-		expectError bool
-	}{
-		{"within limit", "short_token", 20, false},
-		{"at limit", "exactly_twenty_c", 16, false},
-		{"exceeds limit", "this_token_is_too_long", 10, true},
-		{"empty token", "", 10, false},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			err := validator.ValidateTokenSize(tt.token, tt.maxSize)
-
-			if tt.expectError && err == nil {
-				t.Error("Expected error for oversized token")
-			}
-
-			if !tt.expectError && err != nil {
-				t.Errorf("Expected no error, got: %v", err)
-			}
-
-			if err != nil && !strings.Contains(err.Error(), "exceeds") {
-				t.Errorf("Expected 'exceeds' in error, got: %v", err)
-			}
-		})
-	}
-}
-
-func TestExtractClaims(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	claims := map[string]interface{}{
-		"sub":   "user123",
-		"email": "user@example.com",
-		"exp":   float64(1609459200),
-	}
-
-	token := createTestJWTSimple(claims)
-	extracted, err := validator.ExtractClaims(token)
-
-	if err != nil {
-		t.Fatalf("Expected no error, got: %v", err)
-	}
-
-	if extracted == nil {
-		t.Fatal("Expected non-nil claims")
-	}
-
-	if extracted["sub"] != "user123" {
-		t.Errorf("Expected sub 'user123', got %v", extracted["sub"])
-	}
-
-	if extracted["email"] != "user@example.com" {
-		t.Errorf("Expected email 'user@example.com', got %v", extracted["email"])
-	}
-}
-
-func TestExtractClaimsInvalidFormat(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	tests := []struct {
-		name  string
-		token string
-	}{
-		{"single part", "onlyonepart"},
-		{"two parts", "two.parts"},
-		{"four parts", "one.two.three.four"},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			_, err := validator.ExtractClaims(tt.token)
-
-			if err == nil {
-				t.Error("Expected error for invalid format")
-			}
-
-			if !strings.Contains(err.Error(), "invalid JWT format") {
-				t.Errorf("Expected 'invalid JWT format' in error, got: %v", err)
-			}
-		})
-	}
-}
-
-func TestCompareTokensEqual(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	token1 := "secret_token_12345"
-	token2 := "secret_token_12345"
-
-	if !validator.CompareTokens(token1, token2) {
-		t.Error("Expected tokens to be equal")
-	}
-}
-
-func TestCompareTokensDifferent(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	token1 := "secret_token_12345"
-	token2 := "secret_token_54321"
-
-	if validator.CompareTokens(token1, token2) {
-		t.Error("Expected tokens to be different")
-	}
-}
-
-func TestCompareTokensDifferentLength(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	token1 := "short"
-	token2 := "much_longer_token"
-
-	if validator.CompareTokens(token1, token2) {
-		t.Error("Expected tokens to be different (different lengths)")
-	}
-}
-
-func TestCompareTokensEmpty(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	token1 := ""
-	token2 := ""
-
-	if !validator.CompareTokens(token1, token2) {
-		t.Error("Expected empty tokens to be equal")
-	}
-}
-
-func TestValidateTokenMaliciousPayloads(t *testing.T) {
-	validator := NewTokenValidator(nil)
-
-	tests := []struct {
-		name  string
-		token string
-	}{
-		{"sql injection attempt", "'; DROP TABLE users; --"},
-		{"xss attempt", "<script>alert('xss')</script>"},
-		{"path traversal", "../../../etc/passwd"},
-		{"null bytes", "token\x00with\x00nulls"},
-		{"unicode exploit", "token\u0000\u0001\u0002"},
-		{"extremely long", strings.Repeat("a", 100000)},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := validator.ValidateToken(tt.token, false)
-
-			if result.Valid {
-				if result.Claims != nil {
-					t.Logf("Token considered valid: %s", tt.name)
-				}
-			} else {
-				if result.Error == nil {
-					t.Error("Expected error for malicious payload")
-				}
-			}
-		})
-	}
-}
-
 // =============================================================================
 // CONSOLIDATED TOKEN TESTS
 // =============================================================================
@@ -2098,19 +1584,3 @@ func createTokenOfSize(baseToken string, targetSize int) string {
 
 	return baseToken
 }
-
-func createTestJWTSimple(claims map[string]interface{}) string {
-	header := map[string]interface{}{
-		"alg": "HS256",
-		"typ": "JWT",
-	}
-
-	headerJSON, _ := json.Marshal(header)
-	claimsJSON, _ := json.Marshal(claims)
-
-	headerB64 := base64.RawURLEncoding.EncodeToString(headerJSON)
-	claimsB64 := base64.RawURLEncoding.EncodeToString(claimsJSON)
-	signature := base64.RawURLEncoding.EncodeToString([]byte("fake_signature"))
-
-	return headerB64 + "." + claimsB64 + "." + signature
-}

token_validation_rs.go

@@ -0,0 +1,299 @@
+// Package traefikoidc provides OIDC authentication middleware for Traefik.
+// This file contains requestState-aware variants of the token validation
+// functions. They read session field values from the captured snapshot in
+// *requestState instead of calling session.GetX(), eliminating ~21 RLock
+// acquisitions on sd.sessionMutex per request through the validation path
+// (validateStandardTokens reads 17, validateAzureTokens reads 10,
+// validateTokenExpiry reads 4 — and many are the SAME field). Under Yaegi
+// each RLock costs ~1-5ms of interpreter dispatch.
+//
+// The non-RS variants are retained for paths that don't have a captured
+// snapshot (tests that drive the validators directly, the Azure/Google path
+// when reached without rs threading, etc).
+package traefikoidc
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"strings"
+	"time"
+)
+
+// isUserAuthenticatedRS is the requestState-aware variant of
+// isUserAuthenticated. Dispatches to the right per-provider validator based
+// on the configured provider, all of which read from rs instead of session.
+func (t *TraefikOidc) isUserAuthenticatedRS(rs *requestState) (bool, bool, bool) {
+	if t.isAzureProvider() {
+		return t.validateAzureTokensRS(rs)
+	} else if t.isGoogleProvider() {
+		return t.validateGoogleTokensRS(rs)
+	}
+	return t.validateStandardTokensRS(rs)
+}
+
+// validateGoogleTokensRS handles Google-specific token validation. Currently
+// delegates to standard token validation; retained as a hook for any future
+// Google-specific behavior (matches the v1.0.20 layout of the non-RS variant).
+func (t *TraefikOidc) validateGoogleTokensRS(rs *requestState) (bool, bool, bool) {
+	return t.validateStandardTokensRS(rs)
+}
+
+// validateTokenExpiryRS is the requestState-aware variant of validateTokenExpiry.
+// Reads rs.refreshToken instead of session.GetRefreshToken() (4 RLocks avoided).
+func (t *TraefikOidc) validateTokenExpiryRS(rs *requestState, token string) (bool, bool, bool) {
+	cachedClaims, found := t.tokenCache.Get(token)
+	if !found {
+		t.logger.Debug("Claims not found in cache after successful token verification")
+		if rs.refreshToken != "" {
+			return false, true, false
+		}
+		return false, false, true
+	}
+
+	expClaim, ok := cachedClaims["exp"].(float64)
+	if !ok {
+		t.logger.Error("Failed to get expiration time ('exp' claim) from verified token")
+		if rs.refreshToken != "" {
+			return false, true, false
+		}
+		return false, false, true
+	}
+
+	expTimeObj := time.Unix(int64(expClaim), 0)
+	nowObj := time.Now()
+
+	if expTimeObj.Before(nowObj) {
+		if rs.refreshToken != "" {
+			return false, true, false
+		}
+		return false, false, true
+	}
+
+	refreshThreshold := nowObj.Add(t.refreshGracePeriod)
+	if expTimeObj.Before(refreshThreshold) {
+		if rs.refreshToken != "" {
+			return true, true, false
+		}
+		return true, false, false
+	}
+
+	return true, false, false
+}
+
+// validateStandardTokensRS is the requestState-aware variant of
+// validateStandardTokens. Replaces all session.GetX() calls (17 of them in
+// the non-RS variant, dominated by GetRefreshToken called 11 times) with
+// rs field reads. Same control flow.
+//
+//nolint:gocognit,gocyclo // Mirrors validateStandardTokens complexity by design.
+func (t *TraefikOidc) validateStandardTokensRS(rs *requestState) (bool, bool, bool) {
+	if !rs.authenticated {
+		if rs.refreshToken != "" {
+			return false, true, false
+		}
+		return false, false, false
+	}
+
+	if rs.accessToken == "" {
+		if rs.refreshToken != "" {
+			// ID-token grace-period check (only when accessToken is absent).
+			if rs.idToken != "" {
+				parts := strings.Split(rs.idToken, ".")
+				if len(parts) == 3 {
+					if claimsData, err := base64.RawURLEncoding.DecodeString(parts[1]); err == nil {
+						var claims map[string]interface{}
+						if err := json.Unmarshal(claimsData, &claims); err == nil {
+							if expClaim, ok := claims["exp"].(float64); ok {
+								expTime := time.Unix(int64(expClaim), 0)
+								if time.Now().After(expTime) {
+									expiredDuration := time.Since(expTime)
+									if expiredDuration > t.refreshGracePeriod {
+										return false, false, true
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+			return false, true, false
+		}
+		return false, false, true
+	}
+
+	dotCount := strings.Count(rs.accessToken, ".")
+	isOpaqueToken := dotCount != 2
+
+	if isOpaqueToken {
+		if t.allowOpaqueTokens {
+			if err := t.validateOpaqueToken(rs.accessToken); err != nil {
+				errMsg := err.Error()
+				isTokenInvalid := strings.Contains(errMsg, "token is not active") ||
+					strings.Contains(errMsg, "revoked") ||
+					strings.Contains(errMsg, "token has expired")
+				if isTokenInvalid {
+					if rs.refreshToken != "" {
+						return false, true, false
+					}
+					return false, false, true
+				}
+				if t.requireTokenIntrospection {
+					if rs.refreshToken != "" {
+						return false, true, false
+					}
+					return false, false, true
+				}
+				// Transient introspection error: fall through to ID-token validation.
+			} else {
+				// Introspection succeeded.
+				if rs.idToken != "" {
+					return t.validateTokenExpiryRS(rs, rs.idToken)
+				}
+				// No ID token to corroborate an access token we cannot verify
+				// (Azure nonce-bearing Graph access tokens carry a proprietary,
+				// client-unverifiable signature). Do NOT authenticate on an
+				// unverified token: refresh if a refresh token is available,
+				// otherwise force re-authentication.
+				if rs.refreshToken != "" {
+					return false, true, false
+				}
+				return false, false, true
+			}
+		}
+
+		// Fall back to ID-token validation when opaque + no successful introspection.
+		if rs.idToken == "" {
+			if rs.refreshToken != "" {
+				return false, true, false
+			}
+			// Opaque access token, no ID token to corroborate it, and
+			// introspection was unavailable/disabled/errored (e.g.
+			// circuit-breaker open). There is nothing left to verify the token
+			// against, so fail closed and force re-authentication rather than
+			// trusting an unverified opaque token.
+			return false, false, true
+		}
+		if err := t.verifyToken(rs.idToken); err != nil {
+			if strings.Contains(err.Error(), "token has expired") {
+				if rs.refreshToken != "" {
+					return false, true, false
+				}
+				return false, false, true
+			}
+			if rs.refreshToken != "" {
+				return false, true, false
+			}
+			return false, false, true
+		}
+		return t.validateTokenExpiryRS(rs, rs.idToken)
+	}
+
+	// JWT access token present.
+	accessTokenValid := false
+	if err := t.verifyToken(rs.accessToken); err != nil {
+		errMsg := err.Error()
+		if strings.Contains(errMsg, "invalid audience") || strings.Contains(errMsg, "audience") {
+			if t.strictAudienceValidation {
+				if rs.refreshToken != "" {
+					return false, true, false
+				}
+				return false, false, true
+			}
+			// Fall through to ID-token validation.
+		}
+	} else {
+		accessTokenValid = true
+	}
+
+	if rs.idToken == "" {
+		if accessTokenValid {
+			return t.validateTokenExpiryRS(rs, rs.accessToken)
+		}
+		if rs.refreshToken != "" {
+			return true, true, false
+		}
+		return true, false, false
+	}
+
+	if err := t.verifyToken(rs.idToken); err != nil {
+		if strings.Contains(err.Error(), "token has expired") {
+			if rs.refreshToken != "" {
+				return false, true, false
+			}
+			return false, false, true
+		}
+		if rs.refreshToken != "" {
+			return false, true, false
+		}
+		return false, false, true
+	}
+
+	if accessTokenValid {
+		return t.validateTokenExpiryRS(rs, rs.accessToken)
+	}
+	return t.validateTokenExpiryRS(rs, rs.idToken)
+}
+
+// validateAzureTokensRS is the requestState-aware variant of validateAzureTokens.
+// Eliminates 10 session.GetX() RLocks per Azure-path request.
+func (t *TraefikOidc) validateAzureTokensRS(rs *requestState) (bool, bool, bool) {
+	if !rs.authenticated {
+		if rs.refreshToken != "" {
+			return false, true, false
+		}
+		return false, true, false
+	}
+
+	if rs.accessToken != "" {
+		if strings.Count(rs.accessToken, ".") == 2 {
+			if t.isUnverifiableAzureAccessToken(rs.accessToken) {
+				if rs.idToken != "" {
+					if err := t.verifyToken(rs.idToken); err != nil {
+						if rs.refreshToken != "" {
+							return false, true, false
+						}
+						return false, false, true
+					}
+					return t.validateTokenExpiryRS(rs, rs.idToken)
+				}
+				return true, false, false
+			}
+			if err := t.verifyToken(rs.accessToken); err != nil {
+				if rs.idToken != "" {
+					if err := t.verifyToken(rs.idToken); err != nil {
+						if rs.refreshToken != "" {
+							return false, true, false
+						}
+						return false, false, true
+					}
+					return t.validateTokenExpiryRS(rs, rs.idToken)
+				}
+				if rs.refreshToken != "" {
+					return false, true, false
+				}
+				return false, false, true
+			}
+			return t.validateTokenExpiryRS(rs, rs.accessToken)
+		}
+		// Opaque access token.
+		if rs.idToken != "" {
+			return t.validateTokenExpiryRS(rs, rs.idToken)
+		}
+		return true, false, false
+	}
+
+	if rs.idToken != "" {
+		if err := t.verifyToken(rs.idToken); err != nil {
+			if rs.refreshToken != "" {
+				return false, true, false
+			}
+			return false, false, true
+		}
+		return t.validateTokenExpiryRS(rs, rs.idToken)
+	}
+
+	if rs.refreshToken != "" {
+		return false, true, false
+	}
+	return false, false, true
+}

token_validator.go

@@ -1,263 +0,0 @@
-package traefikoidc
-
-import (
-	"bytes"
-	"encoding/base64"
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/lukaszraczylo/traefikoidc/internal/pool"
-)
-
-// TokenValidator provides unified token validation functionality
-type TokenValidator struct {
-	logger *Logger
-}
-
-// NewTokenValidator creates a new token validator
-func NewTokenValidator(logger *Logger) *TokenValidator {
-	if logger == nil {
-		logger = GetSingletonNoOpLogger()
-	}
-	return &TokenValidator{
-		logger: logger,
-	}
-}
-
-// TokenValidationResult contains the result of token validation
-type TokenValidationResult struct {
-	Error     error
-	Claims    map[string]interface{}
-	Expiry    *time.Time
-	IssuedAt  *time.Time
-	TokenType string
-	Valid     bool
-}
-
-// ValidateToken performs comprehensive token validation
-func (v *TokenValidator) ValidateToken(token string, requireJWT bool) TokenValidationResult {
-	result := TokenValidationResult{}
-
-	// Basic validation
-	if token == "" {
-		result.Error = fmt.Errorf("token is empty")
-		return result
-	}
-
-	// Check if it's a JWT or opaque token
-	dotCount := strings.Count(token, ".")
-	isJWT := dotCount == 2
-
-	if requireJWT && !isJWT {
-		result.Error = fmt.Errorf("token is not a valid JWT (found %d dots, expected 2)", dotCount)
-		return result
-	}
-
-	if isJWT {
-		return v.validateJWT(token)
-	} else {
-		return v.validateOpaqueToken(token)
-	}
-}
-
-// validateJWT validates a JWT token
-func (v *TokenValidator) validateJWT(token string) TokenValidationResult {
-	result := TokenValidationResult{
-		TokenType: "JWT",
-	}
-
-	parts := strings.Split(token, ".")
-	if len(parts) != 3 {
-		result.Error = fmt.Errorf("invalid JWT format: expected 3 parts, got %d", len(parts))
-		return result
-	}
-
-	// Validate each part
-	for i, part := range parts {
-		if part == "" {
-			result.Error = fmt.Errorf("JWT part %d is empty", i)
-			return result
-		}
-
-		// Check for valid base64url characters
-		if !v.isValidBase64URL(part) {
-			result.Error = fmt.Errorf("JWT part %d contains invalid base64url characters", i)
-			return result
-		}
-	}
-
-	// Decode and parse claims
-	payload, err := base64.RawURLEncoding.DecodeString(parts[1])
-	if err != nil {
-		result.Error = fmt.Errorf("failed to decode JWT payload: %w", err)
-		return result
-	}
-
-	var claims map[string]interface{}
-	pm := pool.Get()
-	decoder := pm.GetJSONDecoder(bytes.NewReader(payload))
-	defer pm.PutJSONDecoder(decoder)
-	if err := decoder.Decode(&claims); err != nil {
-		result.Error = fmt.Errorf("failed to parse JWT claims: %w", err)
-		return result
-	}
-
-	result.Claims = claims
-
-	// Extract standard claims
-	if exp, ok := claims["exp"]; ok {
-		expTime := v.extractTime(exp)
-		if expTime != nil {
-			result.Expiry = expTime
-			// Check if expired
-			if time.Now().After(*expTime) {
-				result.Error = fmt.Errorf("token is expired (expired at %v)", expTime.Format(time.RFC3339))
-				return result
-			}
-		}
-	}
-
-	if iat, ok := claims["iat"]; ok {
-		iatTime := v.extractTime(iat)
-		if iatTime != nil {
-			result.IssuedAt = iatTime
-			// Check if issued in future
-			if iatTime.After(time.Now().Add(5 * time.Minute)) {
-				result.Error = fmt.Errorf("token issued in future (iat: %v)", iatTime.Format(time.RFC3339))
-				return result
-			}
-		}
-	}
-
-	// Check nbf (not before)
-	if nbf, ok := claims["nbf"]; ok {
-		nbfTime := v.extractTime(nbf)
-		if nbfTime != nil && time.Now().Before(*nbfTime) {
-			result.Error = fmt.Errorf("token not yet valid (nbf: %v)", nbfTime.Format(time.RFC3339))
-			return result
-		}
-	}
-
-	result.Valid = true
-	return result
-}
-
-// validateOpaqueToken validates an opaque token
-func (v *TokenValidator) validateOpaqueToken(token string) TokenValidationResult {
-	result := TokenValidationResult{
-		TokenType: "Opaque",
-	}
-
-	// Check minimum length
-	if len(token) < 20 {
-		result.Error = fmt.Errorf("opaque token too short (length: %d)", len(token))
-		return result
-	}
-
-	// Check for spaces
-	if strings.Contains(token, " ") {
-		result.Error = fmt.Errorf("opaque token contains spaces")
-		return result
-	}
-
-	// Check for control characters
-	for i, char := range token {
-		if char < 32 || char == 127 {
-			result.Error = fmt.Errorf("opaque token contains control character at position %d", i)
-			return result
-		}
-	}
-
-	// Check entropy
-	if len(token) >= 20 {
-		uniqueChars := make(map[rune]bool)
-		for _, char := range token {
-			uniqueChars[char] = true
-		}
-		if len(uniqueChars) < 8 {
-			result.Error = fmt.Errorf("opaque token has insufficient entropy (unique chars: %d)", len(uniqueChars))
-			return result
-		}
-	}
-
-	result.Valid = true
-	return result
-}
-
-// isValidBase64URL checks if a string contains only valid base64url characters
-func (v *TokenValidator) isValidBase64URL(s string) bool {
-	for _, char := range s {
-		if !((char >= 'A' && char <= 'Z') ||
-			(char >= 'a' && char <= 'z') ||
-			(char >= '0' && char <= '9') ||
-			char == '-' || char == '_' || char == '=') {
-			return false
-		}
-	}
-	return true
-}
-
-// extractTime extracts a time.Time from various claim formats
-func (v *TokenValidator) extractTime(claim interface{}) *time.Time {
-	var timestamp int64
-
-	switch val := claim.(type) {
-	case float64:
-		timestamp = int64(val)
-	case int64:
-		timestamp = val
-	case int:
-		timestamp = int64(val)
-	default:
-		return nil
-	}
-
-	t := time.Unix(timestamp, 0)
-	return &t
-}
-
-// ValidateTokenSize checks if token size is within acceptable limits
-func (v *TokenValidator) ValidateTokenSize(token string, maxSize int) error {
-	if len(token) > maxSize {
-		return fmt.Errorf("token exceeds maximum size (size: %d, max: %d)", len(token), maxSize)
-	}
-	return nil
-}
-
-// ExtractClaims extracts claims from a JWT without full validation
-func (v *TokenValidator) ExtractClaims(token string) (map[string]interface{}, error) {
-	parts := strings.Split(token, ".")
-	if len(parts) != 3 {
-		return nil, fmt.Errorf("invalid JWT format")
-	}
-
-	payload, err := base64.RawURLEncoding.DecodeString(parts[1])
-	if err != nil {
-		return nil, fmt.Errorf("failed to decode payload: %w", err)
-	}
-
-	var claims map[string]interface{}
-	pm := pool.Get()
-	decoder := pm.GetJSONDecoder(bytes.NewReader(payload))
-	defer pm.PutJSONDecoder(decoder)
-	if err := decoder.Decode(&claims); err != nil {
-		return nil, fmt.Errorf("failed to parse claims: %w", err)
-	}
-
-	return claims, nil
-}
-
-// CompareTokens safely compares two tokens for equality
-func (v *TokenValidator) CompareTokens(token1, token2 string) bool {
-	if len(token1) != len(token2) {
-		return false
-	}
-
-	// Use constant-time comparison to prevent timing attacks
-	var result byte
-	for i := 0; i < len(token1); i++ {
-		result |= token1[i] ^ token2[i]
-	}
-	return result == 0
-}

types.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"net/http"
 	"sync"
+	"sync/atomic"
 	"text/template"
 	"time"
 
@@ -64,8 +65,46 @@ type ProviderMetadata struct {
 // It integrates with various OIDC providers, manages sessions, caches tokens, and handles
 // the complete authentication flow. It's designed to work seamlessly with Traefik's
 // plugin system and provides flexible configuration options.
+// MetadataSnapshot is an immutable bundle of provider-metadata URLs that the
+// plugin needs on the hot request path. Published atomically via
+// TraefikOidc.metadataSnapshot; readers do exactly one atomic.Value.Load to
+// access all fields. Replaces 3 per-request metadataMu.RLock acquisitions
+// in middleware.ServeHTTP + token_manager paths, each of which paid
+// 1-5ms of Yaegi-dispatch overhead.
+//
+// The fields are a strict subset of the metadataMu-guarded TraefikOidc
+// fields; the legacy fields are still written under metadataMu for
+// less-frequent code paths that have not been migrated.
+type MetadataSnapshot struct {
+	IssuerURL        string
+	JWKSURL          string
+	TokenURL         string
+	AuthURL          string
+	RevocationURL    string
+	EndSessionURL    string
+	IntrospectionURL string
+	RegistrationURL  string
+}
+
 type TraefikOidc struct {
-	lastMetadataRetryTime      time.Time
+	// metadataSnapshot atomically publishes the read-mostly URL bundle.
+	// Hot-path readers (middleware.ServeHTTP, token verification) load it
+	// directly; less-frequent paths still acquire metadataMu.RLock and
+	// read the individual fields below.
+	metadataSnapshot           atomic.Value
+	// lastMetadataRetryNano is the UnixNano timestamp of the last metadata
+	// recovery attempt. Stored atomically so the hot ServeHTTP path can
+	// throttle retries without acquiring metadataRetryMutex on every request.
+	lastMetadataRetryNano      int64
+	// firstRequestStarted is 0 until the very first non-health request fires
+	// the background-task bootstrap; then it flips to 1 via CAS. Replaces the
+	// firstRequestMutex + firstRequestReceived combo which previously took
+	// a write lock on every non-health request forever.
+	firstRequestStarted        int32
+	// metadataRefreshStartedAtomic is the CAS-only variant of the old
+	// metadataRefreshStarted bool. Both flags live under the same atomic so
+	// concurrent first-request goroutines race exactly once.
+	metadataRefreshStartedAtomic int32
 	jwkCache                   JWKCacheInterface
 	jwtVerifier                JWTVerifier
 	ctx                        context.Context
@@ -126,21 +165,18 @@ type TraefikOidc struct {
 	frontchannelLogoutPath     string
 	scopesSupported            []string
 	scopes                     []string
+	extraAuthParams            map[string]string
 	refreshGracePeriod         time.Duration
 	maxRefreshTokenAge         time.Duration
 	metadataMu                 sync.RWMutex
 	shutdownOnce               sync.Once
-	metadataRetryMutex         sync.Mutex
-	firstRequestMutex          sync.Mutex
 	sessionInvalidationCache   CacheInterface
 	refreshResultCache         CacheInterface
 	minimalHeaders             bool
 	stripAuthCookies           bool
 	enableBackchannelLogout    bool
 	enableFrontchannelLogout   bool
-	firstRequestReceived       bool
 	requireTokenIntrospection  bool
-	metadataRefreshStarted     bool
 	allowPrivateIPAddresses    bool
 	disableReplayDetection     bool
 	allowOpaqueTokens          bool
@@ -149,4 +185,17 @@ type TraefikOidc struct {
 	enablePKCE                 bool
 	forceHTTPS                 bool
 	suppressDiagnosticLogs     bool
+
+	// Bearer-auth runtime state (populated only when EnableBearerAuth=true).
+	bearerIdentifierClaim     string
+	bearerFailureTracker      *bearerFailureTracker
+	maxTokenAge               time.Duration
+	maxIdentifierLength       int
+	bearerFailureThreshold    int
+	bearerFailureWindow       time.Duration
+	bearerFailurePenalty      time.Duration
+	enableBearerAuth          bool
+	stripAuthorizationHeader  bool
+	bearerEmitWWWAuthenticate bool
+	bearerOverridesCookie     bool
 }

universal_cache.go

@@ -396,8 +396,16 @@ func (c *UniversalCache) getLocal(key string) (interface{}, bool) {
 			return value, true
 		}
 		c.mu.RUnlock()
-		// Expired — fall through to the write-locked slow path below to
-		// remove the entry under exclusive access.
+		// Expired — return miss immediately. The periodic cleanup goroutine
+		// will evict the stale entry. NEVER fall through to the write-locked
+		// slow path for Token/JWK/Session caches: under Yaegi the write Lock
+		// at line 403 costs 10-100ms per acquisition, and Go's RWMutex
+		// writer-priority semantics block ALL new RLock callers while a Lock
+		// is pending. A single expired-token event turns every concurrent
+		// request from read-parallel into write-serialized — the exact
+		// convoy that produced the 737-goroutine pileup at 0x400275a608.
+		atomic.AddInt64(&c.misses, 1)
+		return nil, false
 	}
 
 	c.mu.Lock()
@@ -595,15 +603,28 @@ func (c *UniversalCache) removeItem(key string, item *CacheItem) {
 
 // evictOldest evicts the oldest item from the cache (must be called with lock held)
 func (c *UniversalCache) evictOldest() {
-	if elem := c.lruList.Back(); elem != nil {
-		key, _ := elem.Value.(string) // Safe to ignore: cache internal type assertion
-		if item, exists := c.items[key]; exists {
-			c.removeItem(key, item)
-			atomic.AddInt64(&c.evictions, 1)
-			if c.logger.IsDebug() {
-				c.logger.Debugf("UniversalCache[%s]: Evicted key=%s", c.config.Type, key)
-			}
+	elem := c.lruList.Back()
+	if elem == nil {
+		return
+	}
+	key, _ := elem.Value.(string) // Safe to ignore: cache internal type assertion
+	if item, exists := c.items[key]; exists && item.element == elem {
+		c.removeItem(key, item)
+		atomic.AddInt64(&c.evictions, 1)
+		if c.logger.IsDebug() {
+			c.logger.Debugf("UniversalCache[%s]: Evicted key=%s", c.config.Type, key)
 		}
+		return
+	}
+	// Defensive forward-progress guard: the back node is dangling — its key is
+	// absent from c.items, or c.items[key] points at a newer node (a stale
+	// duplicate). Drop the node directly so an eviction loop
+	// (`for ... && c.lruList.Len() > 0`) is guaranteed to terminate and can
+	// never spin holding c.mu.Lock(). With the updateLocalCache replace-in-place
+	// fix this branch should be unreachable, but it makes the spin impossible.
+	c.lruList.Remove(elem)
+	if c.currentSize > 0 {
+		c.currentSize--
 	}
 }
 
@@ -936,6 +957,30 @@ func (c *UniversalCache) updateLocalCache(key string, value interface{}, ttl tim
 	}
 
 	now := time.Now()
+	// Replace an existing entry in place: update the item and move its single
+	// list node to the front. Without this, a repeat populate of the same key
+	// (the per-request Get->backend-hit path) would PushFront a duplicate node
+	// and overwrite c.items[key], orphaning the previous node. Orphans inflate
+	// currentMemory/currentSize and, once eviction deletes the key, leave a
+	// Back() node whose key is absent from c.items — so evictOldest() spins
+	// while holding c.mu.Lock(): the 100%-CPU write-lock convoy seen in pprof.
+	// setLocal dedups the same way; evictOldest also guards any dangling node.
+	if existing, exists := c.items[key]; exists {
+		c.currentMemory -= existing.Size
+		c.lruList.Remove(existing.element)
+
+		existing.Value = value
+		existing.Size = size
+		existing.ExpiresAt = now.Add(ttl)
+		existing.LastAccessed = now
+		existing.AccessCount++
+
+		existing.element = c.lruList.PushFront(key)
+		c.currentMemory += size
+
+		return nil
+	}
+
 	item := &CacheItem{
 		Key:          key,
 		Value:        value,

universal_cache_orphan_test.go

@@ -0,0 +1,84 @@
+package traefikoidc
+
+import (
+	"testing"
+	"time"
+)
+
+// newOrphanTestCache builds a Token-type cache with background cleanup disabled
+// so the test fully controls lruList/items state.
+func newOrphanTestCache(maxMem int64) *UniversalCache {
+	return NewUniversalCache(UniversalCacheConfig{
+		Type:              CacheTypeToken,
+		DefaultTTL:        time.Hour,
+		MaxSize:           1_000_000, // large: keep the size-branch out of the way
+		MaxMemoryBytes:    maxMem,
+		EnableMemoryLimit: maxMem > 0,
+		SkipAutoCleanup:   true,
+		EnableAutoCleanup: false,
+	})
+}
+
+// TestUpdateLocalCache_NoOrphanElements is the direct red test: repeatedly
+// populating the SAME key via updateLocalCache (the per-request Get->backend-hit
+// path) must NOT leave dangling lruList elements. Today updateLocalCache blindly
+// PushFronts + overwrites c.items[key] without removing the prior element, so the
+// list grows one orphan per call while items stays at 1 entry.
+func TestUpdateLocalCache_NoOrphanElements(t *testing.T) {
+	c := newOrphanTestCache(0) // memory limit off: isolate the orphan, no eviction
+	const key = "same-key"
+
+	for range 5 {
+		if err := c.updateLocalCache(key, "v", time.Hour); err != nil {
+			t.Fatalf("updateLocalCache: %v", err)
+		}
+	}
+
+	c.mu.RLock()
+	listLen := c.lruList.Len()
+	itemCount := len(c.items)
+	c.mu.RUnlock()
+
+	if itemCount != 1 {
+		t.Fatalf("items: got %d want 1", itemCount)
+	}
+	if listLen != 1 {
+		t.Fatalf("ORPHAN BUG: lruList.Len()=%d but items=%d (one list element per key expected)", listLen, itemCount)
+	}
+}
+
+// TestUpdateLocalCache_EvictionTerminates is the convoy reproducer: once orphans
+// for a key exist and the memory-eviction loop runs, evictOldest() deletes the
+// key from items on the first eviction, after which every remaining orphan at
+// Back() has a key absent from items -> evictOldest() no-ops while lruList.Len()>0
+// stays true -> infinite loop while holding c.mu.Lock(). That is the 100%-CPU
+// holder + write-lock convoy observed in pprof.
+func TestUpdateLocalCache_EvictionTerminates(t *testing.T) {
+	c := newOrphanTestCache(0) // start with memory limit OFF to accumulate orphans
+	const key = "same-key"
+
+	// Build 3 same-key list elements (3 orphans, items={key}).
+	for range 3 {
+		if err := c.updateLocalCache(key, "v", time.Hour); err != nil {
+			t.Fatalf("seed updateLocalCache: %v", err)
+		}
+	}
+
+	// Arm the trap: tiny memory limit so the next call enters the eviction loop.
+	c.mu.Lock()
+	c.config.MaxMemoryBytes = 1
+	c.mu.Unlock()
+
+	done := make(chan struct{})
+	go func() {
+		_ = c.updateLocalCache(key, "v", time.Hour) // triggers the eviction loop
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// fix present: loop made forward progress and returned
+	case <-time.After(2 * time.Second):
+		t.Fatal("INFINITE LOOP: eviction loop did not terminate within 2s (orphan whose key was deleted is never removed from lruList)")
+	}
+}

url_helpers.go

@@ -19,7 +19,7 @@ import (
 //   - true if the URL should be excluded from authentication, false otherwise.
 func (t *TraefikOidc) determineExcludedURL(currentRequest string) bool {
 	for excludedURL := range t.excludedURLs {
-		if strings.HasPrefix(currentRequest, excludedURL) {
+		if pathExcluded(currentRequest, excludedURL) {
 			t.logger.Debugf("URL is excluded - got %s / excluded hit: %s", currentRequest, excludedURL)
 			return true
 		}
@@ -27,6 +27,31 @@ func (t *TraefikOidc) determineExcludedURL(currentRequest string) bool {
 	return false
 }
 
+// pathExcluded reports whether requestPath is covered by an excluded prefix at a
+// natural boundary: an exact match, a sub-path ("/public" → "/public/x"), or a
+// file extension ("/favicon" → "/favicon.ico"). It deliberately does NOT match
+// an unrelated sibling such as "/publicsecret", so a configured exclusion can no
+// longer be widened into an authentication bypass on a different resource.
+func pathExcluded(requestPath, excluded string) bool {
+	excluded = strings.TrimRight(excluded, "/")
+	if excluded == "" {
+		// A "/" (root) exclusion only matches the root path, not everything.
+		return requestPath == "" || requestPath == "/"
+	}
+	if requestPath == excluded {
+		return true
+	}
+	if !strings.HasPrefix(requestPath, excluded) {
+		return false
+	}
+	switch requestPath[len(excluded)] {
+	case '/', '.':
+		return true
+	default:
+		return false
+	}
+}
+
 // buildAuthURL constructs the OIDC provider authorization URL.
 // It builds the URL with all necessary parameters including client_id, scopes,
 // PKCE parameters, and provider-specific parameters for Google and Azure.
@@ -146,6 +171,21 @@ func (t *TraefikOidc) buildAuthURL(redirectURL, state, nonce, codeChallenge stri
 		t.logger.Debugf("TraefikOidc.buildAuthURL: Final scope string being sent to OIDC provider: %s", finalScopeString)
 	}
 
+	// Apply operator-configured extra authorization parameters (e.g.
+	// screen_hint, login_hint, ui_locales, prompt). These are added last but
+	// can never override parameters the plugin itself manages (client_id,
+	// state, nonce, redirect_uri, code_challenge, scope, response_type, ...):
+	// a key already present in params is left untouched, so this cannot
+	// weaken security-critical parameters.
+	for key, value := range t.extraAuthParams {
+		if params.Get(key) == "" {
+			params.Set(key, value)
+			t.logger.Debugf("TraefikOidc.buildAuthURL: Added extra auth param %s", key)
+		} else {
+			t.logger.Debugf("TraefikOidc.buildAuthURL: Skipped extra auth param %s (already set by plugin)", key)
+		}
+	}
+
 	// Read authURL with RLock
 	t.metadataMu.RLock()
 	authURL := t.authURL
@@ -273,6 +313,63 @@ func (t *TraefikOidc) validateParsedURL(u *url.URL) error {
 	return nil
 }
 
+// validateDiscoveredEndpoint validates an endpoint URL obtained from the
+// provider's OIDC/OAuth2 discovery document before the plugin issues any
+// outbound request to it. A discovery document is attacker-influenced if the
+// provider is malicious or its TLS is broken, so an unvalidated endpoint is an
+// SSRF vector (e.g. jwks_uri or introspection_endpoint pointed at the cloud
+// metadata service 169.254.169.254 or an internal host).
+//
+// Empty endpoints are allowed (they are optional). Link-local (which covers the
+// 169.254.0.0/16 metadata range), multicast and unspecified addresses are
+// always rejected. Private addresses are rejected unless allowPrivateIPAddresses
+// is set. Loopback is rejected unless allowLoopback is true — which the caller
+// sets only when the operator-configured providerURL is itself loopback (local
+// development, in-cluster sidecars, tests), so production deployments pointed at
+// a real provider still block loopback SSRF.
+func (t *TraefikOidc) validateDiscoveredEndpoint(urlStr string, allowLoopback bool) error {
+	if urlStr == "" {
+		return nil
+	}
+	u, err := url.Parse(urlStr)
+	if err != nil {
+		return fmt.Errorf("invalid URL format: %w", err)
+	}
+	if u.Scheme != "https" && u.Scheme != "http" {
+		return fmt.Errorf("disallowed URL scheme: %q", u.Scheme)
+	}
+	if u.Host == "" {
+		return fmt.Errorf("missing host in URL")
+	}
+	if ip := net.ParseIP(u.Hostname()); ip != nil {
+		switch {
+		case ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() || ip.IsMulticast() || ip.IsUnspecified():
+			return fmt.Errorf("endpoint host is a blocked address: %s", ip)
+		case ip.IsLoopback() && !allowLoopback:
+			return fmt.Errorf("endpoint host is a loopback address: %s", ip)
+		case ip.IsPrivate() && !t.allowPrivateIPAddresses:
+			return fmt.Errorf("endpoint host is a private address: %s", ip)
+		}
+	}
+	if strings.Contains(u.Path, "..") {
+		return fmt.Errorf("path traversal detected in URL path")
+	}
+	return nil
+}
+
+// sameHost reports whether two URLs share the same host:port (case-insensitive).
+// Used to pin the credential-bearing introspection endpoint to the operator-
+// configured provider so a poisoned discovery document cannot redirect the
+// client secret to an attacker-controlled host.
+func sameHost(a, b string) bool {
+	ua, erra := url.Parse(a)
+	ub, errb := url.Parse(b)
+	if erra != nil || errb != nil || ua.Host == "" || ub.Host == "" {
+		return false
+	}
+	return strings.EqualFold(ua.Host, ub.Host)
+}
+
 // validateHost validates a hostname or IP address for security.
 // It prevents access to localhost, private networks, and known metadata endpoints.
 // When allowPrivateIPAddresses is enabled, private IP checks are skipped.

url_helpers_ultra_test.go

@@ -554,3 +554,54 @@ func TestForceHTTPSIntegration(t *testing.T) {
 			"should use https from X-Forwarded-Proto when forceHTTPS is false")
 	})
 }
+
+// TestBuildAuthURLExtraAuthParams verifies operator-configured extra
+// authorization parameters are appended to the authorization URL, and that
+// they can never override parameters the plugin itself manages.
+func TestBuildAuthURLExtraAuthParams(t *testing.T) {
+	t.Run("extra params are added (e.g. screen_hint=signup)", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		middleware.extraAuthParams = map[string]string{
+			"screen_hint": "signup",
+			"ui_locales":  "en",
+		}
+
+		authURL := middleware.buildAuthURL(
+			"https://app.com/callback", "state123", "nonce456", "",
+		)
+
+		assert.Contains(t, authURL, "screen_hint=signup")
+		assert.Contains(t, authURL, "ui_locales=en")
+	})
+
+	t.Run("nil/empty extraAuthParams is a no-op", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		// extraAuthParams left nil
+		authURL := middleware.buildAuthURL(
+			"https://app.com/callback", "state123", "nonce456", "",
+		)
+
+		assert.Contains(t, authURL, "client_id=test-client")
+		assert.NotContains(t, authURL, "screen_hint")
+	})
+
+	t.Run("extra params CANNOT override plugin-managed params", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		middleware.extraAuthParams = map[string]string{
+			"client_id":     "ATTACKER",
+			"state":         "ATTACKER",
+			"redirect_uri":  "https://evil.example.com",
+			"response_type": "token",
+		}
+
+		authURL := middleware.buildAuthURL(
+			"https://app.com/callback", "state123", "nonce456", "",
+		)
+
+		// Plugin-managed values must win; injected values must be absent.
+		assert.Contains(t, authURL, "client_id=test-client")
+		assert.NotContains(t, authURL, "ATTACKER")
+		assert.NotContains(t, authURL, "evil.example.com")
+		assert.Contains(t, authURL, "response_type=code")
+	})
+}

utilities.go

@@ -14,6 +14,19 @@ import (
 	"time"
 )
 
+// metadataSnap returns the most recently published *MetadataSnapshot, or nil
+// if metadata has not yet been resolved. Single atomic.Value.Load — the hot
+// ServeHTTP path uses this instead of acquiring metadataMu.RLock, which under
+// Yaegi pays 1-5ms of interpreter-dispatch overhead per acquisition.
+func (t *TraefikOidc) metadataSnap() *MetadataSnapshot {
+	v := t.metadataSnapshot.Load()
+	if v == nil {
+		return nil
+	}
+	s, _ := v.(*MetadataSnapshot)
+	return s
+}
+
 // safeLogDebug provides nil-safe logging for debug messages
 func (t *TraefikOidc) safeLogDebug(msg string) {
 	if t.logger != nil {
@@ -122,7 +135,7 @@ func (t *TraefikOidc) isAllowedDomain(email string) bool {
 			return false
 		}
 
-		domain := parts[1]
+		domain := strings.ToLower(parts[1])
 		_, domainAllowed := t.allowedUserDomains[domain]
 
 		if domainAllowed {
@@ -223,8 +236,13 @@ func (t *TraefikOidc) Close() error {
 		// Get resource manager for cleanup
 		rm := GetResourceManager()
 
-		// Stop singleton tasks related to this instance
-		_ = rm.StopBackgroundTask("singleton-token-cleanup") // Safe to ignore: best effort cleanup
+		// singleton-token-cleanup is a process-global task shared by every plugin
+		// instance. Only stop it when the LAST instance is shutting down;
+		// otherwise one instance's teardown (e.g. a single config reload) would
+		// kill chunked-session/token cleanup for all surviving instances (rank 12).
+		if unregisterLiveInstance() <= 0 {
+			_ = rm.StopBackgroundTask("singleton-token-cleanup") // best effort, last instance only
+		}
 		// Stop metadata refresh task using same hash-based name as startMetadataRefresh
 		if t.providerURL != "" {
 			hash := sha256.Sum256([]byte(t.providerURL))

vendor/github.com/lukaszraczylo/oss-telemetry/.gitignore

@@ -0,0 +1 @@
+.docs

vendor/github.com/lukaszraczylo/oss-telemetry/.golangci.yml

@@ -0,0 +1,36 @@
+version: "2"
+
+run:
+  timeout: 2m
+
+linters:
+  default: none
+  enable:
+    - bodyclose
+    - errcheck
+    - errorlint
+    - gocritic
+    - gocyclo
+    - govet
+    - ineffassign
+    - misspell
+    - prealloc
+    - revive
+    - staticcheck
+    - unconvert
+    - unused
+  settings:
+    gocyclo:
+      min-complexity: 12
+    revive:
+      rules:
+        - name: var-naming
+        - name: indent-error-flow
+        - name: superfluous-else
+        - name: unused-parameter
+        - name: redefines-builtin-id
+
+formatters:
+  enable:
+    - gofmt
+    - goimports

vendor/github.com/lukaszraczylo/oss-telemetry/.semver.yaml

@@ -0,0 +1,42 @@
+# Configuration for lukaszraczylo/semver-generator.
+# Reference: https://github.com/lukaszraczylo/semver-generator
+#
+# Word matching is fuzzy + case-insensitive. The keywords below mirror the
+# Conventional Commits prefixes used in this repo's git history. Same pattern
+# as github.com/lukaszraczylo/go-telegram/.semver.yaml.
+
+version: 1
+
+# Respect existing v* tags as the version baseline. semver-generator finds
+# the highest existing tag and bumps from there. With no tags yet, the first
+# release computes from the empty base.
+force:
+  existing: true
+
+# Skip merge commits and machine-generated traffic that would otherwise
+# spuriously bump the version.
+blacklist:
+  - "Merge branch"
+  - "Merge pull request"
+  - "Merge remote-tracking branch"
+  - "go mod tidy"
+
+wording:
+  patch:
+    - "fix"
+    - "chore"
+    - "docs"
+    - "test"
+    - "style"
+    - "refactor"
+    - "build"
+    - "ci"
+    - "perf"
+  minor:
+    - "feat"
+  major:
+    # Match only the canonical Conventional Commits trailer. The bare word
+    # "breaking" is too greedy under semver-generator's fuzzy match — it
+    # triggers on substrings inside a commit body and wrongly produces a
+    # major bump.
+    - "BREAKING CHANGE"

vendor/github.com/lukaszraczylo/oss-telemetry/README.md

@@ -0,0 +1,122 @@
+# oss-telemetry
+
+A tiny Go client that fires one anonymous "this binary started" ping at a
+central ingest endpoint. Designed to be embedded in your own open-source
+projects so you can see approximate adoption and version spread without
+collecting anything that could identify a user.
+
+This is the **client library only**. The ingest endpoint, server-side
+deduplication, rate limiting, and metrics are out of scope here.
+
+## What it sends
+
+A single HTTP `POST` per call to `Send`:
+
+```json
+{
+  "project": "my-tool",
+  "version": "1.2.3",
+  "ts": 1747782200
+}
+```
+
+No identifiers, no IP, no machine info, no user data. The server dedupes
+incoming requests; the client just fires and forgets.
+
+## Failproof by design
+
+- Never blocks the caller — work runs in a goroutine.
+- Never panics — the goroutine recovers internally.
+- Never returns errors — bad input and network failures are silently dropped.
+- Never retries, never persists state, never reads back.
+- 2-second hard timeout on every request.
+- Zero third-party dependencies (Go stdlib only).
+
+The endpoint is hardcoded and not overridable from consuming code, by design.
+
+## Install
+
+```bash
+go get github.com/lukaszraczylo/oss-telemetry
+```
+
+Requires Go 1.22+.
+
+## Usage
+
+```go
+package main
+
+import (
+    "time"
+
+    telemetry "github.com/lukaszraczylo/oss-telemetry"
+)
+
+const version = "1.2.3"
+
+func main() {
+    telemetry.Send("my-tool", version)
+
+    // ... your program runs ...
+
+    // Only needed for short-lived CLIs that may exit before the goroutine
+    // finishes its POST. Long-running services do not need this.
+    telemetry.Wait(2 * time.Second)
+}
+```
+
+Call `Send` once at boot. Calling it more often just sends more pings; the
+server deduplicates.
+
+## Disabling telemetry
+
+If you ship a binary that imports this library, link your users to this
+section (`https://github.com/lukaszraczylo/oss-telemetry#disabling-telemetry`)
+so they can find the opt-out paths.
+
+Any one of these turns it off:
+
+| Mechanism                                | How                                                              |
+| ---------------------------------------- | ---------------------------------------------------------------- |
+| Universal opt-out                        | `DO_NOT_TRACK=1`                                                 |
+| Library-wide opt-out                     | `OSS_TELEMETRY_DISABLED=1`                                       |
+| Project-specific opt-out                 | `<UPPER_PROJECT>_DISABLE_TELEMETRY=1`                            |
+| Programmatic (e.g. behind a `--no-telemetry` flag) | `telemetry.Disable()` before the first `Send`          |
+
+Project-specific env var derivation: uppercase the project name and replace
+`-` with `_`. For `my-tool` the variable is `MY_TOOL_DISABLE_TELEMETRY`.
+
+Truthy values: `1`, `true`, `yes`, `on` (case-insensitive). Anything else is
+treated as "not set".
+
+## Validation rules (silently dropped if violated)
+
+- `project`: matches `^[a-z0-9-]+$`, length 1–64.
+- `version`: matches `^[A-Za-z0-9.+_-]+$`, length 1–32.
+
+Bad input is a no-op — the library never logs, never errors, never crashes.
+
+## API
+
+```go
+// Fire a single ping in the background. Returns immediately.
+func Send(project, version string)
+
+// Suppress all subsequent Send calls in this process. Idempotent.
+func Disable()
+
+// Block until in-flight pings complete or timeout elapses, whichever first.
+// Useful for short-lived CLI processes.
+func Wait(timeout time.Duration)
+```
+
+## Testing
+
+```bash
+go test -race ./...
+```
+
+## License
+
+Pick one before publishing. None bundled.

vendor/github.com/lukaszraczylo/oss-telemetry/telemetry.go

@@ -0,0 +1,367 @@
+// Package telemetry sends anonymous usage pings for open-source Go projects.
+//
+// Wire format (POST application/json):
+//
+//	{"project":"<name>","version":"<ver>","ts":<unix-seconds>}
+//
+// Design contract (failproof):
+//   - never blocks the caller (work happens in a goroutine)
+//   - never panics (background goroutine recovers internally)
+//   - never returns errors (silently no-ops on bad input or network failure)
+//   - never retries, never deduplicates, never persists state — the client
+//     fires a single ping and forgets; the server is responsible for
+//     deduplication, abuse protection, and aggregation
+//
+// Typical usage at program startup:
+//
+//	telemetry.Send("my-tool", "1.2.3")
+//
+// For short-lived CLI processes that may exit before the goroutine finishes:
+//
+//	telemetry.Send("my-tool", "1.2.3")
+//	defer telemetry.Wait(2 * time.Second)
+//
+// Disablement (any one of these suppresses pings):
+//   - environment variable DO_NOT_TRACK=1
+//   - environment variable OSS_TELEMETRY_DISABLED=1
+//   - environment variable <UPPER_PROJECT>_DISABLE_TELEMETRY=1
+//     (project name uppercased, dashes replaced with underscores)
+//   - calling telemetry.Disable() at runtime
+package telemetry
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"os"
+	"runtime/debug"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+const (
+	defaultEndpoint = "https://oss.raczylo.com/v1/ping"
+	httpTimeout     = 2 * time.Second
+	maxProjectLen   = 64
+	maxVersionLen   = 32
+)
+
+// Yaegi note: this package is consumed by the traefikoidc Traefik plugin, which
+// Traefik interprets with Yaegi (it vendors and interprets dependency source).
+// It therefore avoids generic stdlib types (atomic.Pointer[T], atomic.Bool) and
+// range-over-int (Go 1.22), which some Traefik/Yaegi runtimes cannot interpret.
+// Endpoint mutation uses a mutex-guarded string; the disabled flag uses the
+// function-based sync/atomic int32 API (atomic.LoadInt32/StoreInt32).
+var (
+	// endpointURL holds the ingest URL. Production code never mutates it; the
+	// setter exists only so the test suite can retarget it at httptest servers
+	// while goroutines started by Send are still in flight.
+	endpointMu  sync.RWMutex
+	endpointURL = defaultEndpoint
+
+	disabled int32 // 0 = enabled, 1 = disabled; accessed via sync/atomic only
+	inflight sync.WaitGroup
+
+	client = &http.Client{Timeout: httpTimeout}
+)
+
+func currentEndpoint() string {
+	endpointMu.RLock()
+	defer endpointMu.RUnlock()
+	return endpointURL
+}
+
+func setEndpointURL(u string) {
+	endpointMu.Lock()
+	endpointURL = u
+	endpointMu.Unlock()
+}
+
+// Send fires a single anonymous telemetry ping in the background and returns
+// immediately. It never blocks, never panics, and never reports errors.
+// Invalid inputs, disabled state, and network failures are silently dropped.
+//
+// Version strings are validated against a SemVer-ish shape that mirrors the
+// receiver. An optional leading "v" or "V" is accepted and stripped before
+// transmission so that callers can pass either "v1.2.3" or "1.2.3"; the
+// wire form is always the unprefixed canonical version.
+//
+// Call once at program startup. Calling repeatedly will send repeated pings;
+// the server is responsible for deduplication.
+func Send(project, version string) {
+	if atomic.LoadInt32(&disabled) != 0 {
+		return
+	}
+	if isDisabledByEnv(project) {
+		return
+	}
+	if !validProject(project) || !validVersion(version) {
+		return
+	}
+	canonical := normalizeVersion(version)
+
+	inflight.Add(1)
+	go func() {
+		defer inflight.Done()
+		defer func() { _ = recover() }()
+		dispatch(project, canonical)
+	}()
+}
+
+// SendForModule is the recommended call form for Go libraries: it resolves
+// the version automatically from Go's build info for the given module path
+// so consumers do not need to maintain a hand-bumped version constant in
+// source. Behaviour and contract are otherwise identical to [Send].
+//
+// Resolution order:
+//
+//  1. debug.ReadBuildInfo Deps entry for modulePath (authoritative when the
+//     library is consumed via go.mod);
+//  2. debug.ReadBuildInfo Main when the library is itself the main module
+//     (e.g. running its own tests or examples);
+//  3. fallback parameter, used only when build info is unavailable or
+//     unhelpful (replace directives, detached `go run`, ldflag override).
+//
+// Any leading "v" reported by build info is stripped to match the canonical
+// wire form. Empty / "(devel)" build versions are skipped in favour of the
+// next resolution source. Typical usage:
+//
+//	telemetry.SendForModule("my-tool", "github.com/me/my-tool", "0.0.0-dev")
+func SendForModule(project, modulePath, fallback string) {
+	Send(project, ResolveModuleVersion(modulePath, fallback))
+}
+
+// ResolveModuleVersion implements the version resolution used by
+// SendForModule. Exposed for callers that need to format the resolved
+// version (e.g. logging) without firing a ping.
+func ResolveModuleVersion(modulePath, fallback string) string {
+	if info, ok := debug.ReadBuildInfo(); ok {
+		for _, d := range info.Deps {
+			if d != nil && d.Path == modulePath && isUsableBuildVersion(d.Version) {
+				return strings.TrimPrefix(d.Version, "v")
+			}
+		}
+		if info.Main.Path == modulePath && isUsableBuildVersion(info.Main.Version) {
+			return strings.TrimPrefix(info.Main.Version, "v")
+		}
+	}
+	return fallback
+}
+
+func isUsableBuildVersion(v string) bool {
+	return v != "" && v != "(devel)"
+}
+
+// Disable suppresses all subsequent Send calls in this process.
+// Idempotent and safe to call from any goroutine.
+func Disable() {
+	atomic.StoreInt32(&disabled, 1)
+}
+
+// Wait blocks until all in-flight pings have completed, or until timeout
+// elapses — whichever comes first. Useful for short-lived CLI processes
+// that may otherwise exit before the background goroutine finishes its POST.
+//
+// A non-positive timeout returns immediately.
+func Wait(timeout time.Duration) {
+	if timeout <= 0 {
+		return
+	}
+	done := make(chan struct{})
+	go func() {
+		inflight.Wait()
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-time.After(timeout):
+	}
+}
+
+func dispatch(project, version string) {
+	body := buildPayload(project, version, time.Now().Unix())
+
+	ctx, cancel := context.WithTimeout(context.Background(), httpTimeout)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, currentEndpoint(), bytes.NewReader(body))
+	if err != nil {
+		return
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return
+	}
+	_ = resp.Body.Close()
+}
+
+// buildPayload writes the JSON body without encoding/json. The validators
+// restrict project and version to characters that never require JSON
+// escaping, so direct concatenation is safe.
+func buildPayload(project, version string, ts int64) []byte {
+	// Wrapper text plus 20 chars for a signed int64.
+	const overhead = len(`{"project":"","version":"","ts":}`) + 20
+	buf := make([]byte, 0, len(project)+len(version)+overhead)
+	buf = append(buf, `{"project":"`...)
+	buf = append(buf, project...)
+	buf = append(buf, `","version":"`...)
+	buf = append(buf, version...)
+	buf = append(buf, `","ts":`...)
+	buf = strconv.AppendInt(buf, ts, 10)
+	buf = append(buf, '}')
+	return buf
+}
+
+func validProject(p string) bool {
+	n := len(p)
+	if n == 0 || n > maxProjectLen {
+		return false
+	}
+	for i := 0; i < n; i++ {
+		c := p[i]
+		switch {
+		case c >= 'a' && c <= 'z',
+			c >= '0' && c <= '9',
+			c == '-':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
+// validVersion accepts SemVer-ish version strings with an optional leading
+// "v"/"V" prefix. Acceptable shape (after stripping the leading v):
+//
+//	MAJOR[.MINOR[.PATCH]] ("-"prerelease)? ("+"build)?
+//
+// where MAJOR/MINOR/PATCH are ASCII digit sequences and the prerelease/build
+// payloads are non-empty runs of [0-9A-Za-z.-]. This intentionally mirrors
+// the receiver's version regex so junk like "dev" or "git-2026-05-22" never
+// leaves the client (where it would only be rejected with HTTP 400 anyway).
+func validVersion(v string) bool {
+	n := len(v)
+	if n == 0 || n > maxVersionLen {
+		return false
+	}
+	if v[0] == 'v' || v[0] == 'V' {
+		v = v[1:]
+	}
+	if len(v) == 0 {
+		return false
+	}
+	return checkSemverShape(v)
+}
+
+// normalizeVersion strips an optional leading "v"/"V" so the on-the-wire
+// version matches the form stored server-side by the version refresher cron
+// (which also strips the leading v from release tags). Callers may pass
+// either "v1.2.3" or "1.2.3" — only the unprefixed form is transmitted.
+func normalizeVersion(v string) string {
+	if len(v) > 0 && (v[0] == 'v' || v[0] == 'V') {
+		return v[1:]
+	}
+	return v
+}
+
+func checkSemverShape(s string) bool {
+	i := 0
+	if !readDigitRun(s, &i) {
+		return false
+	}
+	for groups := 0; groups < 2 && i < len(s) && s[i] == '.'; groups++ {
+		i++
+		if !readDigitRun(s, &i) {
+			return false
+		}
+	}
+	if i < len(s) && s[i] == '-' {
+		i++
+		if !readIdentRun(s, &i, '+') {
+			return false
+		}
+	}
+	if i < len(s) && s[i] == '+' {
+		i++
+		if !readIdentRun(s, &i, 0) {
+			return false
+		}
+	}
+	return i == len(s)
+}
+
+func readDigitRun(s string, i *int) bool {
+	start := *i
+	for *i < len(s) && s[*i] >= '0' && s[*i] <= '9' {
+		*i++
+	}
+	return *i > start
+}
+
+// readIdentRun consumes [0-9A-Za-z.-] until end-of-string or until `stop`
+// is hit (stop=0 disables the early-stop check). Returns false if no
+// characters were consumed (i.e. empty payload).
+func readIdentRun(s string, i *int, stop byte) bool {
+	start := *i
+	for *i < len(s) {
+		c := s[*i]
+		if stop != 0 && c == stop {
+			break
+		}
+		valid := (c >= '0' && c <= '9') ||
+			(c >= 'A' && c <= 'Z') ||
+			(c >= 'a' && c <= 'z') ||
+			c == '.' || c == '-'
+		if !valid {
+			return false
+		}
+		*i++
+	}
+	return *i > start
+}
+
+func isDisabledByEnv(project string) bool {
+	if truthy(os.Getenv("DO_NOT_TRACK")) {
+		return true
+	}
+	if truthy(os.Getenv("OSS_TELEMETRY_DISABLED")) {
+		return true
+	}
+	if project == "" {
+		return false
+	}
+	key := projectEnvKey(project)
+	return truthy(os.Getenv(key))
+}
+
+// projectEnvKey returns "<UPPER_PROJECT>_DISABLE_TELEMETRY" using a single
+// allocation rather than chained strings.ToUpper(strings.ReplaceAll(...)).
+func projectEnvKey(project string) string {
+	const suffix = "_DISABLE_TELEMETRY"
+	buf := make([]byte, 0, len(project)+len(suffix))
+	for i := 0; i < len(project); i++ {
+		c := project[i]
+		switch {
+		case c == '-':
+			c = '_'
+		case c >= 'a' && c <= 'z':
+			c -= 'a' - 'A'
+		}
+		buf = append(buf, c)
+	}
+	buf = append(buf, suffix...)
+	return string(buf)
+}
+
+func truthy(s string) bool {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "1", "true", "yes", "on":
+		return true
+	}
+	return false
+}

vendor/modules.txt

@@ -24,6 +24,9 @@ github.com/gorilla/securecookie
 # github.com/gorilla/sessions v1.3.0
 ## explicit; go 1.20
 github.com/gorilla/sessions
+# github.com/lukaszraczylo/oss-telemetry v0.2.3
+## explicit; go 1.22
+github.com/lukaszraczylo/oss-telemetry
 # github.com/pmezard/go-difflib v1.0.0
 ## explicit
 github.com/pmezard/go-difflib/difflib

version.go

@@ -0,0 +1,17 @@
+package traefikoidc
+
+// devPluginVersion is the placeholder carried by source-tree / local / test
+// builds. Telemetry is suppressed while the plugin still reports this sentinel,
+// so only stamped release builds emit a "plugin loaded" ping.
+const devPluginVersion = "0.0.0-dev"
+
+// traefikoidcPluginVersion is the released version of this plugin. It is stamped
+// at release time by ./workflow-prepare.sh (invoked by the shared go-release
+// workflow before GoReleaser builds and tags), which rewrites the string below
+// to the computed semver.
+//
+// Traefik runs this plugin under Yaegi, where the version cannot be resolved
+// from build info at runtime (debug.ReadBuildInfo sees Traefik's build graph,
+// not the interpreted plugin). This build-stamped constant is therefore the
+// single source of truth for the version reported by anonymous usage telemetry.
+const traefikoidcPluginVersion = "1.0.26"

workflow-prepare.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# workflow-prepare.sh — stamp the release version into version.go at build time.
+#
+# The shared go-release workflow (lukaszraczylo/shared-actions go-release.yaml)
+# runs this script, if present, from the repository root BEFORE GoReleaser
+# builds and tags. Traefik runs this plugin under Yaegi, where the version
+# cannot be resolved from build info at runtime, so the released semver must be
+# baked into source here.
+#
+# Version source — first non-empty wins:
+#   $VERSION  $VERSION_TAG  $SEMVER  $NEW_VERSION  $RELEASE_VERSION
+# A leading "v"/"V" is stripped.
+#
+# NOTE: go-release.yaml @main does not yet pass the computed version into this
+# step's environment. Add it to the "Run workflow prepare script" step, e.g.:
+#   env:
+#     VERSION: ${{ needs.version.outputs.version }}   # bare, no leading v
+#
+# The shared workflow runs this script in its test, version AND release jobs,
+# but only the release job has a computed version. So a missing version is a
+# no-op (leave the dev sentinel) — NOT a hard failure, otherwise the test/version
+# jobs would break. A malformed version that IS provided is a hard error. Wire
+# the env only on the release job's prepare step (see header note above).
+set -euo pipefail
+
+FILE="version.go"
+CONST="traefikoidcPluginVersion"
+
+VER="${VERSION:-${VERSION_TAG:-${SEMVER:-${NEW_VERSION:-${RELEASE_VERSION:-}}}}}"
+VER="${VER#v}"
+VER="${VER#V}"
+
+if [ -z "$VER" ]; then
+  if [ "${GITHUB_ACTIONS:-}" = "true" ]; then
+    echo "workflow-prepare: WARNING no version provided; leaving ${FILE} at the dev placeholder. If this is the release build, set 'env: VERSION: \${{ needs.version.outputs.version }}' on the release job's prepare step — otherwise the release ships 0.0.0-dev and emits no telemetry." >&2
+  else
+    echo "workflow-prepare: no version provided; leaving dev placeholder in ${FILE} (local build)"
+  fi
+  exit 0
+fi
+
+# Accept MAJOR[.MINOR[.PATCH]] with optional -prerelease / +build (semver-ish,
+# matching the oss-telemetry receiver's validator).
+if ! printf '%s' "$VER" | grep -Eq '^[0-9]+(\.[0-9]+){0,2}(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$'; then
+  echo "workflow-prepare: ERROR version '${VER}' is not semver-shaped" >&2
+  exit 1
+fi
+
+if [ ! -f "$FILE" ]; then
+  echo "workflow-prepare: ERROR ${FILE} not found (run from repository root)" >&2
+  exit 1
+fi
+
+# Rewrite only the value of ${CONST}, anchored on the constant name so the
+# sibling devPluginVersion sentinel is left untouched.
+tmp="$(mktemp)"
+sed -E "s/(${CONST}[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1${VER}\2/" "$FILE" > "$tmp"
+mv "$tmp" "$FILE"
+
+if ! grep -Eq "${CONST}[[:space:]]*=[[:space:]]*\"${VER}\"" "$FILE"; then
+  echo "workflow-prepare: ERROR failed to stamp version into ${FILE}" >&2
+  exit 1
+fi
+
+command -v gofmt >/dev/null 2>&1 && gofmt -w "$FILE"
+echo "workflow-prepare: stamped ${CONST} = \"${VER}\" in ${FILE}"