chore(release): v1.0.36

* feat: add RFC 8707 resource indicator via resource config

`Config.Resource` is an alternative to `audience` for IdPs that implement
RFC 8707. `buildAuthURL` sends it as the `resource` parameter on the
authorization request, before `extraAuthParams` so an operator-configured
`resource` key there cannot override or duplicate it. `exchangeTokens`
repeats it on both the `authorization_code` and `refresh_token` grants
(RFC 8707 §2.2), so a refreshed token keeps the audience binding of the
original grant.

Only one resource is accepted. RFC 8707 permits a list, but no provider
that supports the parameter handles a list usefully: one rejects any
request naming more than one resource with HTTP 400 `invalid_target`;
node-oidc-provider accepts several and issues an opaque token bound to
none of them.

`Config.Validate()` requires an absolute URI of at most 256 characters
with no fragment, wildcard, or control characters. `http`/`https` values
go through `isValidSecureURL`, so HTTPS is required outside loopback;
other schemes (`urn:`) pass as-is.

When `resource` is set and `audience` is not, `audience` defaults to the
resource for access-token validation; `strictAudienceValidation` applies
the same way whichever of the two is set. That default is validation-only.
A new `TraefikOidc.explicitAudience` mirrors `Config.Audience` verbatim,
and `buildAuthURL` keys the non-standard `audience` request parameter (the
Auth0 custom-API pattern) on it rather than on `audience`, so a
resource-derived default is never sent as an unsolicited `audience`
parameter alongside `resource` — a combination that misbehaves against
providers such as Ory Hydra, which give `audience` a different meaning.
`audience_test.go` and `url_helpers_ultra_test.go` set `audience` on the
struct directly, bypassing `New()`, and now set `explicitAudience` too.

docs/CONFIGURATION.md carries only the reference-table row and a short
pointer; the new docs/RFC8707.md holds the request behaviour, the
single-resource rationale, the `resource`/`audience` relationship, and a
provider-support table from interop testing: node-oidc-provider supports
it; Zitadel accepts and silently ignores it (`oidc.AuthRequest` has no
`resource` field, confirmed against a live instance); Authentik returns
`invalid_target`; Keycloak has no support through 26.6; Ory Hydra/Fosite
uses its own `audience` parameter; Azure AD/Entra ID v2 is reported to
reject `resource` combined with v2-style `scope`; Auth0 and AWS Cognito
claims are unverified. README.md, docs/index.html, and .traefik.yml each
point at docs/RFC8707.md instead of repeating it, and the comments on
`Config.Resource`, in main.go, and in url_helpers.go defer to it as well.

rfc8707_resource_test.go covers the authorization-URL parameter (set,
unset, query-bearing value percent-encoded rather than merged,
`extraAuthParams` unable to override), both grants sending `resource` in
the form body, the `Config.Validate()` rules table, audience defaulting
through `New()`, and a regression pair: a resource-derived audience
default is not sent as `audience`, while an explicitly configured one
still is.

* fix: accept Resource in place of Audience for bearer-auth validation

`NewWithContext` rejected `EnableBearerAuth=true` whenever
`config.Audience` was empty, even though `t.audience` already falls back
to `config.Resource` in that case. The check now fails only when both
`Audience` and `Resource` are empty, and the error names both fields.
`TestStartupValidation_BearerAcceptsResourceInPlaceOfAudience` covers the
`Resource`-only configuration.

`docs/RFC8707.md` links the `audience` parameter note to
`docs/AUTH0_AUDIENCE_GUIDE.md` instead of restating it, and drops the
provider table's GitHub row and the interop-testing paragraph, which are
covered elsewhere.

.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

@@ -23,6 +23,19 @@ testData:
   providerURL: https://accounts.google.com
   clientID: 1234567890.apps.googleusercontent.com
   clientSecret: your-client-secret
+  # Alternative: RFC 7523 private_key_jwt client authentication (Entra ID,
+  # Okta, Auth0, Keycloak). Replaces clientSecret with a signed JWT assertion.
+  # See README "Client authentication via private key JWT".
+  # clientAuthMethod: private_key_jwt
+  # clientAssertionKeyID: my-key-2026
+  # clientAssertionAlg: RS256             # default; or PS256/384/512, ES256/384/512
+  # # File path option:
+  # clientAssertionKeyPath: /etc/traefik/oidc/client-key.pem
+  # # Or inline PEM (PKCS#8 / PKCS#1 / SEC1):
+  # clientAssertionPrivateKey: |
+  #   -----BEGIN PRIVATE KEY-----
+  #   MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDexampleexample
+  #   -----END PRIVATE KEY-----
   sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
   callbackURL: /oauth2/callback
 
@@ -47,14 +60,18 @@ testData:
   scopes:
     - roles
 
-  # Templated headers forwarded to backends.
-  # NOTE: use quadruple braces — the YAML parser collapses {{{{ → {{ so the
-  # Go template engine receives the correct expression.
+  # Templated headers forwarded to backends. Values are Go templates and must
+  # be written with plain double braces — the catalog analyzer feeds them to
+  # the plugin verbatim (issue #151; quadruple braces do NOT get collapsed).
+  # Only when your dynamic config file is rendered by Traefik's file-provider
+  # Go templating do the braces need escaping there, e.g.
+  #   value: "{{`{{.Claims.email}}`}}"
+  # (see README "Templated headers").
   headers:
     - name: X-User-Email
-      value: "{{{{.Claims.email}}}}"
+      value: "{{.Claims.email}}"
     - name: Authorization
-      value: "Bearer {{{{.AccessToken}}}}"
+      value: "Bearer {{.AccessToken}}"
 
   # Security headers (default profile is enabled out of the box)
   securityHeaders:
@@ -67,3 +84,31 @@ 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
+  # introspectionURL: https://idp.example.com/oauth/introspect  # manual override; set when discovery omits introspection_endpoint
+  # 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
+
+  # Optional: RFC 8707 resource indicator, alternative to `audience` for
+  # supporting IdPs. See docs/RFC8707.md for exact request behavior and
+  # provider support.
+  # resource: https://api.example.com
+

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)
@@ -41,7 +42,7 @@ experimental:
   plugins:
     traefikoidc:
       moduleName: github.com/lukaszraczylo/traefikoidc
-      version: v0.7.10
+      version: v1.0.29
 ```
 
 Then attach the middleware in your dynamic configuration (see
@@ -96,7 +97,7 @@ More example configs in [`examples/`](examples/).
 |-----------|-------------|
 | `providerURL` | Issuer URL (used for OIDC discovery). |
 | `clientID` | OAuth 2.0 client ID. |
-| `clientSecret` | OAuth 2.0 client secret. Supports `urn:k8s:secret:ns:name:key`. |
+| `clientSecret` | OAuth 2.0 client secret. Supports `urn:k8s:secret:ns:name:key`. Required when `clientAuthMethod` is unset, `client_secret_post`, or `client_secret_basic`; optional with `private_key_jwt`. |
 | `sessionEncryptionKey` | Cookie encryption key, **min 32 bytes**. |
 | `callbackURL` | Callback path, e.g. `/oauth2/callback`. |
 
@@ -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. |
@@ -119,12 +121,14 @@ Full reference in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 | `enablePKCE` | `false` | PKCE on the auth code flow. |
 | `cookieDomain` | auto | Set explicitly for multi-subdomain setups (`.example.com`). |
 | `cookiePrefix` | `_oidc_raczylo_` | Unique prefix per middleware instance to isolate sessions. |
+| `cookiePath` | `/` | Restrict cookies to a path prefix. Set to the middleware's path (e.g. `/app`) to prevent the browser from sending OIDC cookies to unprotected paths, avoiding 431 "Request Header Or Cookie Too Large" errors on mixed-use domains. |
 | `sessionMaxAge` | `86400` | Session lifetime in seconds. |
 | `refreshGracePeriodSeconds` | `60` | Proactively refresh tokens this many seconds before expiry. |
 | `maxRefreshTokenAgeSeconds` | `21600` | Heuristic max stored refresh-token lifetime (6h). Past this, the plugin treats the RT as expired without contacting the IdP — returns 401 to AJAX, full re-auth on navigations. Set `0` to disable. Tune to match your IdP's RT TTL. |
 | `rateLimit` | `100` | Requests/sec. Min `10`. |
 | `logLevel` | `info` | `debug`, `info`, `error`. |
-| `audience` | `clientID` | Custom access-token audience (Auth0 custom APIs). |
+| `audience` | `clientID`, or `resource` if set | Custom access-token audience (Auth0 custom APIs). |
+| `resource` | none | RFC 8707 resource indicator, alternative to `audience` for supporting IdPs (see [docs/RFC8707.md](docs/RFC8707.md)). |
 | `strictAudienceValidation` | `false` | Reject mismatched audiences. **Set `true` in production.** |
 | `allowOpaqueTokens` / `requireTokenIntrospection` | `false` | Accept opaque access tokens via RFC 7662. |
 | `disableReplayDetection` | `false` | Disable JTI cache. Use Redis instead for multi-replica. |
@@ -133,6 +137,11 @@ Full reference in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 | `stripAuthCookies` | `false` | Strip OIDC cookies from backend hop (mitigates HTTP 431). |
 | `caCertPath` / `caCertPEM` | none | Trust an internal CA for the provider's TLS. |
 | `insecureSkipVerify` | `false` | **Local dev only.** Disables TLS verification, logs a security warning. |
+| `clientAuthMethod` | `client_secret_post` | Client auth method. Set `private_key_jwt` for RFC 7523 JWT assertions (Entra ID, Okta, Auth0, Keycloak). See [Client authentication via private key JWT](#client-authentication-via-private-key-jwt). |
+| `clientAssertionPrivateKey` | none | Inline PEM private key for `private_key_jwt`. Mutually exclusive with `clientAssertionKeyPath`. |
+| `clientAssertionKeyPath` | none | File path to PEM private key for `private_key_jwt`. |
+| `clientAssertionKeyID` | none | JWS `kid` header. Required when `clientAuthMethod=private_key_jwt`; must match the public key registered with the IdP. |
+| `clientAssertionAlg` | `RS256` | JWS alg for `private_key_jwt`. Supported: `RS256/384/512`, `PS256/384/512`, `ES256/384/512`. |
 | `enableBackchannelLogout` / `backchannelLogoutURL` | `false` / none | OIDC Back-Channel Logout (server-to-server). |
 | `enableFrontchannelLogout` / `frontchannelLogoutURL` | `false` / none | OIDC Front-Channel Logout (iframe). |
 | `redis` | disabled | See [docs/REDIS.md](docs/REDIS.md). |
@@ -140,6 +149,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
@@ -159,6 +180,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
 
@@ -166,6 +189,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
@@ -213,6 +322,44 @@ caCertPEM: |
 Both can be combined. An unparseable bundle fails the plugin at startup.
 See [#125](https://github.com/lukaszraczylo/traefikoidc/issues/125).
 
+### Client authentication via private key JWT
+
+Use when your IdP enforces short-lived secrets or pushes secretless client auth
+— Microsoft Entra ID / Azure AD, Okta, Auth0, Keycloak. Instead of sending a
+static `clientSecret`, the plugin signs a short-lived JWT and submits it as
+`client_assertion` per [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523).
+
+Minimal config:
+
+```yaml
+clientAuthMethod: private_key_jwt
+clientAssertionKeyPath: /etc/traefik/oidc/client-key.pem
+clientAssertionKeyID: my-key-2026
+# clientAssertionAlg: RS256   # default; or PS256/384/512, ES256/384/512
+```
+
+Or inline:
+
+```yaml
+clientAuthMethod: private_key_jwt
+clientAssertionPrivateKey: |
+  -----BEGIN PRIVATE KEY-----
+  ...
+  -----END PRIVATE KEY-----
+clientAssertionKeyID: my-key-2026
+```
+
+Accepted PEM forms: PKCS#8 (`PRIVATE KEY`), PKCS#1 (`RSA PRIVATE KEY`), SEC1
+(`EC PRIVATE KEY`). The assertion uses `iss=sub=clientID`, `aud=tokenURL`, 60s
+lifetime, random hex `jti` per request. Sent on `/token` (auth-code + refresh)
+and `/revoke`. The `kid` must match the public key registered with the IdP.
+
+`clientSecret` becomes optional with `private_key_jwt`. Existing
+`client_secret_post` setups are unaffected. Keys are parsed once at startup —
+rotation requires a Traefik reload.
+
+See [issue #135](https://github.com/lukaszraczylo/traefikoidc/issues/135).
+
 ### Environment variable names containing `API`
 
 Traefik reserves `TRAEFIK_API_*`. User vars whose name contains `API` (e.g.
@@ -227,21 +374,50 @@ Forward identity to backends via Go templates over ID-token claims and tokens:
 ```yaml
 headers:
   - name: X-User-Email
-    value: "{{{{.Claims.email}}}}"
+    value: "{{.Claims.email}}"
   - name: Authorization
-    value: "Bearer {{{{.AccessToken}}}}"
+    value: "Bearer {{.AccessToken}}"
   - name: X-User-Roles
-    value: "{{{{range $i, $e := .Claims.roles}}}}{{{{if $i}}}},{{{{end}}}}{{{{$e}}}}{{{{end}}}}"
+    value: "{{range $i, $e := .Claims.roles}}{{if $i}},{{end}}{{$e}}{{end}}"
 ```
 
-Available bindings: `.Claims.<field>`, `.AccessToken`, `.IdToken`,
-`.RefreshToken`. Names are case-sensitive (`.Claims`, not `.claims`).
+Available bindings: `.Claims.<field>`, `.AccessToken`, `.IdToken`
+(or `.IDToken`), `.RefreshToken`. Names are case-sensitive (`.Claims`, not
+`.claims`).
 
-> **Escape with quadruple braces.** If you see
-> `can't evaluate field AccessToken in type bool`, Traefik's YAML parser ate
-> your `{{ }}`. The fix that actually works is `{{{{ }}}}` — the YAML pass
-> turns it into `{{ }}` for the Go template engine. Other escaping tricks
-> (literal blocks, single quotes) do not work reliably.
+Header templates are validated at startup (a failing template stops the
+middleware from loading). Only a fixed set of claim fields may be emitted —
+standard OIDC claims plus common provider claims (`email`, `name`,
+`given_name`, `family_name`, `preferred_username`, `sub`, `groups`, `roles`,
+`realm_access`, `resource_access`, `oid`, `tid`, `upn`, `hd`, `picture`,
+`locale`, `email_verified`, and a few more; see `safeClaimsFields` in
+`template_validation.go`). To emit a claim not on that list, add it to
+`allowedClaims`:
+
+```yaml
+allowedClaims:
+  - employee_id
+headers:
+  - name: X-Employee-Id
+    value: "{{.Claims.employee_id}}"
+```
+
+Rendering the whole context (`{{.}}`, `{{$}}`), the whole claims map
+(`{{.Claims}}`), or any non-listed claim is rejected — this prevents a template
+from accidentally forwarding raw tokens or unlisted claims. `range`/`with` must
+target a specific listed claim (e.g. `{{range .Claims.groups}}`); `get`/`default`
+are the only functions allowed.
+
+> **File-provider users: escape the braces.** Traefik's file provider runs
+> every dynamic configuration file through Go templating before the plugin
+> sees it. Plain `{{.AccessToken}}` then fails with
+> `can't evaluate field AccessToken in type bool`. Wrap the expression in a
+> raw string so the file provider emits it literally:
+> ``value: "{{`{{.Claims.email}}`}}"``. All other providers (Kubernetes CRD,
+> Docker labels, Consul, ...) pass the value through untouched — use the plain
+> form there. Quadruple braces (`{{{{ }}}}`) do not work anywhere: the file
+> provider fails to parse them, and every other path hands them to the plugin
+> verbatim, where template validation rejects them (issues #149, #151).
 
 ## Default downstream headers
 
@@ -269,7 +445,7 @@ section — see [docs/CONFIGURATION.md](docs/CONFIGURATION.md#security-headers).
 | `No matching public key found` | JWKS endpoint down, or `kid` mismatch. |
 | `Access denied: Your email domain is not allowed` | User's domain not in `allowedUserDomains`. |
 | `Access denied: You do not have any of the allowed roles or groups` | Claims missing or not in `allowedRolesAndGroups`. |
-| `can't evaluate field AccessToken in type bool` | Template not escaped — use `{{{{ }}}}`. |
+| `can't evaluate field AccessToken in type bool` | File provider templated your header value — escape it: ``"{{`{{.AccessToken}}`}}"`` (see "Templated headers"). |
 | `tls: failed to verify certificate: x509: certificate signed by unknown authority` | Internal CA — set `caCertPath` / `caCertPEM`. |
 | `invalid handler type: <nil>` | Env var name contains `API` — rename it. |
 | `false positive replay detected` | Multi-replica without Redis — see [Multi-replica deployments](#multi-replica-deployments). |
@@ -281,6 +457,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

@@ -288,6 +288,10 @@ func TestAuth0Scenario1WithCustomAudience(t *testing.T) {
 
 	customAudience := "https://my-api.example.com"
 	ts.tOidc.audience = customAudience
+	// buildAuthURL sources the outbound `audience` param from
+	// explicitAudience, not audience (see url_helpers.go); an explicitly
+	// configured custom audience must set both to behave like production.
+	ts.tOidc.explicitAudience = customAudience
 
 	// Create ID token with aud = client_id (OIDC standard)
 	idToken, err := createTestJWT(ts.rsaPrivateKey, "RS256", "test-key-id", map[string]interface{}{
@@ -484,7 +488,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 +628,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,848 @@
+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", "[email protected]", "[email protected]", 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_BearerAcceptsResourceInPlaceOfAudience(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 = ""
+	cfg.Resource = "https://api.example.com"
+	mw, err := New(context.Background(), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}), cfg, "bearer-test")
+	if err != nil {
+		t.Fatalf("expected Resource to satisfy the bearer-auth audience requirement, got %v", err)
+	}
+	defer mw.(*TraefikOidc).Close()
+}
+
+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

@@ -18,6 +18,7 @@ type CacheManager struct {
 var (
 	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()

client_assertion.go

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

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
 // =============================================================================
@@ -826,11 +750,53 @@ func TestValidateTemplateSecure_CoverageBoost(t *testing.T) {
 			template:    "{{.Unknown}}",
 			shouldError: true,
 		},
+		// Issue #148: whitespace after {{ and before }} must be tolerated
+		{
+			name:        "get with leading space (issue #148)",
+			template:    "{{ get .Claims \"email\" }}",
+			shouldError: false,
+		},
+		{
+			name:        "get with multiple leading spaces",
+			template:    "{{  get .Claims \"email\"}}",
+			shouldError: false,
+		},
+		{
+			name:        "default with spaces",
+			template:    "{{ default \"unknown\" .Claims.email }}",
+			shouldError: false,
+		},
+		{
+			name:        "claims with spaces",
+			template:    "{{ .Claims.email }}",
+			shouldError: false,
+		},
+		{
+			name:        "access token with spaces",
+			template:    "{{ .AccessToken }}",
+			shouldError: false,
+		},
+		// Issue #148: space must NOT let dangerous patterns bypass detection
+		{
+			name:        "range with leading space stays blocked",
+			template:    "{{ range .Items }}{{.}}{{end}}",
+			shouldError: true,
+		},
+		{
+			name:        "call with leading space stays blocked",
+			template:    "{{ call .Func }}",
+			shouldError: true,
+		},
+		{
+			name:        "disallowed claim with spaces stays blocked",
+			template:    "{{ .Claims.password }}",
+			shouldError: true,
+		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			err := validateTemplateSecure(tt.template)
+			err := validateTemplateSecure(tt.template, nil)
 			if tt.shouldError && err == nil {
 				t.Errorf("Expected error for template: %s", tt.template)
 			}

docs/AUTH0_AUDIENCE_GUIDE.md

@@ -298,13 +298,20 @@ strictAudienceValidation: true
    ```
    Look for `introspection_endpoint`
 
-2. **Disable required introspection (less secure):**
+2. **Configure the endpoint manually:**
+   ```yaml
+   introspectionURL: https://YOUR_DOMAIN/oauth/introspect
+   ```
+   Set this when Auth0 omits `introspection_endpoint` from discovery. The
+   manual value takes precedence over the discovered value.
+
+3. **Disable required introspection (less secure):**
    ```yaml
    allowOpaqueTokens: true
    requireTokenIntrospection: false  # Falls back to ID token
    ```
 
-3. **Use JWT access tokens instead** (recommended)
+4. **Use JWT access tokens instead** (recommended)
 
 ---
 

docs/BEARER_AUTH.md

@@ -0,0 +1,250 @@
+# Bearer Token (M2M) Authentication
+
+Opt-in path that lets API clients present `Authorization: Bearer <jwt>` to
+authenticate without going through the cookie-based OIDC redirect flow.
+Designed for machine-to-machine (M2M) traffic — services calling other
+services with tokens minted by your OIDC provider.
+
+The bearer path lives next to the cookie path: both go through the same
+post-auth pipeline (`forwardAuthorized`) that injects identity headers,
+checks `allowedRolesAndGroups`, applies security headers, and forwards to
+the backend. The only thing that differs is how the principal is established
+for that single request.
+
+## Quick start
+
+```yaml
+enableBearerAuth: true
+audience: https://api.example.com  # REQUIRED when bearer is enabled
+clientID: my-api-client-id
+providerURL: https://issuer.example.com
+sessionEncryptionKey: <32+-byte secret>
+callbackURL: /oauth2/callback
+```
+
+That is the minimum. Everything else has a secure default.
+
+## Obtaining bearer tokens from your OIDC provider
+
+The middleware only **validates** bearer tokens — minting them is the IdP's job. For M2M traffic the canonical mint flow is OAuth 2.0 **`client_credentials`** (RFC 6749 §4.4); some providers require **JWT bearer assertion** (RFC 7523) instead.
+
+```
+┌────────────┐  POST /token                    ┌──────────┐
+│  client    │ ───────────────────────────────►│  IdP     │
+│  (service) │   grant_type=client_credentials │ /token   │
+│            │   client_id=…                   │          │
+│            │   client_secret=…  (or JWT)     │          │
+│            │   audience=https://api.…   ←── critical    │
+│            │   scope=api:read …                         │
+│            │ ◄───────────────────────────────│          │
+│            │     access_token (JWT)          │          │
+└────────────┘                                 └──────────┘
+         │
+         │  GET /protected
+         │  Authorization: Bearer <access_token>
+         ▼
+   Your service (behind Traefik + this plugin)
+```
+
+The IdP returns a JWT signed by the same JWKs the middleware already trusts (it discovers them from `providerURL`/.well-known). On the first protected request, the middleware verifies signature + issuer + **audience** + `exp` + identifier claim, then forwards downstream with `X-Forwarded-User` set.
+
+### Minimal worked example (Auth0-shape)
+
+```bash
+# 1. Mint a token
+curl -s -X POST https://issuer.example.com/oauth/token \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "grant_type":    "client_credentials",
+    "client_id":     "your-m2m-client-id",
+    "client_secret": "your-m2m-client-secret",
+    "audience":      "https://api.example.com",
+    "scope":         "api:read api:write"
+  }'
+# → {"access_token":"eyJhbGciOiJSUzI1NiIs…","token_type":"Bearer","expires_in":86400,…}
+
+# 2. Use it
+curl -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs…' https://api.example.com/protected
+```
+
+The `audience` field in the token request **must match** the `audience` you configured on the middleware. Mismatch → 401 with `Bearer error="invalid_token"`.
+
+### Per-provider quick reference
+
+| Provider | Grant | Token endpoint | Audience parameter | Notes |
+|---|---|---|---|---|
+| **Auth0** | `client_credentials` | `https://TENANT.auth0.com/oauth/token` | `audience=<your API identifier>` | Register an "API" + "Machine to Machine Application" authorised against that API. Without `audience` you get an opaque /userinfo token, which the bearer path rejects. See `docs/AUTH0_AUDIENCE_GUIDE.md`. |
+| **Okta** | `client_credentials` | `https://TENANT.okta.com/oauth2/default/v1/token` | Configured in the authorization server; default `aud` is the auth-server URL | Service app must enable the `client_credentials` flow and be granted the requested scopes. |
+| **Keycloak** | `client_credentials` | `https://kc/realms/REALM/protocol/openid-connect/token` | Configure an "Audience" mapper on a client scope, or use `client_id` as the audience | Client must have `serviceAccountsEnabled: true` plus role mappings. |
+| **Entra ID / Azure AD** | `client_credentials` (v2.0 endpoint) | `https://login.microsoftonline.com/TENANT/oauth2/v2.0/token` | Pass `scope=<App ID URI>/.default`; `aud` ends up being the API's App ID URI | Requires an App Registration + API permissions + admin consent. **Use the v2.0 endpoint** — v1 issues Microsoft-proprietary access tokens that are opaque to non-Microsoft clients. |
+| **AWS Cognito** | `client_credentials` | `https://YOUR_DOMAIN.auth.REGION.amazoncognito.com/oauth2/token` | Scopes from a "Resource Server" attached to your User Pool | App client must have `client_credentials` flow enabled. Use HTTP **Basic** auth header for `client_id:client_secret`. |
+| **GitLab** | `client_credentials` | `https://gitlab.com/oauth/token` | Audience matches the GitLab issuer | Rarely used for protecting external APIs; better suited for GitLab's own resources. |
+| **Google** | **JWT bearer (RFC 7523)** — *not* `client_credentials` | `https://oauth2.googleapis.com/token` | Signed assertion JWT carries `aud=https://oauth2.googleapis.com/token`; resulting access token is **opaque** unless you specifically request a Google-issued JWT for your API | Google service-account flow is not the best fit for this middleware (opaque tokens are rejected on the bearer path). Run Auth0 / Okta / Keycloak in front, or use ID-token-based flows on the cookie path. |
+
+### RFC 7523 (JWT bearer assertion) — secretless alternative
+
+When shared secrets are forbidden (FAPI, internal compliance), swap `client_secret` for a signed JWT assertion:
+
+```
+POST /token
+grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
+assertion=<JWT signed by the client's private key>
+```
+
+The assertion JWT carries `iss=<client_id>`, `sub=<client_id>`, `aud=<token endpoint>`, `exp`. The IdP verifies the signature against a public key you've pre-registered and returns an access token.
+
+This middleware already supports JWT assertions on the *middleware → IdP* hop via `clientAuthMethod: private_key_jwt` (see `docs/CONFIGURATION.md`). For the *client → IdP* hop, the same pattern applies — the client signs its own assertion.
+
+### Operational notes
+
+- **Token TTL is typically 1–24 hours.** Clients should refresh on `401`, not on a polling timer — saves the IdP.
+- **Cache and reuse tokens.** The middleware caches verified tokens too, so repeated presentations are cheap. Clients SHOULD reuse a token until ~80 % of `expires_in`.
+- **JWKS rotation is transparent.** The middleware auto-refreshes its JWKS cache when the IdP rotates keys. Clients don't need to do anything.
+- **Revocation is generally not per-token** with `client_credentials`. If you need real-time revocation, set `requireTokenIntrospection: true` on the middleware and the IdP is consulted on every cache miss.
+- **`scope` vs `audience`.** Scope says *what the client may do*; audience says *which service the token is for*. The middleware enforces audience; the backend service should enforce scope.
+- **Secret hygiene.** Store `client_secret` in a secrets manager (Vault, AWS Secrets Manager, Kubernetes `Secret`). For higher assurance, switch the client to `private_key_jwt` (no shared secret at all).
+
+### Quickest validation loop
+
+```bash
+# 1. Mint
+TOKEN=$(curl -s -X POST https://issuer.example.com/oauth/token \
+  -H 'Content-Type: application/json' \
+  -d '{"grant_type":"client_credentials","client_id":"…","client_secret":"…","audience":"https://api.example.com"}' \
+  | jq -r .access_token)
+
+# 2. Inspect claims to confirm aud/iss/exp match the middleware config
+echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq
+
+# 3. Hit the protected route
+curl -i -H "Authorization: Bearer $TOKEN" https://api.example.com/protected
+```
+
+`HTTP/1.1 200` with `X-Forwarded-User` on the backend confirms the loop works end-to-end. `401` with `WWW-Authenticate: Bearer error="invalid_token"` plus a middleware debug log explaining the rejection (audience mismatch, ID token presented, `iat` outside the 24h window, etc.) confirms the hardening is firing as designed.
+
+## Threat model and design rules
+
+Bearer authentication has materially different security properties from
+cookie sessions: no `HttpOnly`/`Secure`/`SameSite` shielding, the token is
+visible in headers and logs, and it's easier to exfiltrate. The bearer path
+treats every one of these as a first-class concern.
+
+| Property | Behaviour | Why |
+|---|---|---|
+| Default state | `enableBearerAuth=false` | Bearer is opt-in; existing deployments observe no change. |
+| Audience | **Mandatory.** Startup fails if `audience` is empty when bearer is enabled. | Eliminates the "token issued for service B accepted by service A" confusion attack. |
+| Token format | JWT only (3 segments, JOSE-encoded). Opaque tokens are not accepted on the bearer path. | Matches the validation pipeline; opaque tokens require introspection only and bypass JWT-specific defences. |
+| `alg` allowlist | Hard-pinned asymmetric: `RS256/384/512`, `PS256/384/512`, `ES256/384/512`. Checked **before** any JWKS fetch. | Denies `alg=none` and `alg=HS*` probes; prevents attacker noise from amplifying into JWKS round-trips. |
+| `kid` hardening | Max 256 bytes; charset `[A-Za-z0-9._\-=]`. Checked **before** JWKS fetch. | Prevents cache-key explosion / pathological-`kid` JWKS amplification. |
+| Token type | ID tokens are explicitly rejected (`nonce` claim, `typ: at+jwt`, `token_use=id`, scope/aud heuristics — reuses the existing `detectTokenType` helper). | ID tokens are not API credentials; treating them as such is classic token confusion. |
+| Multi-audience | When `aud` is an array of length > 1, the token must carry `azp == clientID`. | OIDC §2 hardening against tokens minted for one client being replayed by another. |
+| `iat` upper-age | Rejects tokens older than `maxTokenAgeSeconds` (default 24h). | Bounds clock-manipulation / forever-token abuse, even if `exp` is far in the future. |
+| Identifier claim | `bearerIdentifierClaim` (default `"sub"`). Resolved value drives `X-Forwarded-User`. | Decoupled from the cookie path's `UserIdentifierClaim` (default `email`) so the M2M flow can never accidentally trust an unverified email. |
+| Identifier sanitisation | Length cap (`maxIdentifierLength`, default 256). Rejects control chars, Unicode bidi-overrides (U+202A–U+202E, U+2066–U+2069), and the delimiters `, ; =`. | Defence in depth against downstream header injection / log injection / admin-UI spoofing. |
+| JTI replay marking | Bearer path skips the JTI **Set** (so the same token can be reused until `exp`) but the **Get** stays active. | Allows legitimate bearer reuse without false-positive replay detection; revoked tokens (added to the blacklist by `RevokeToken`) still fail immediately. |
+| Mixed bearer + cookie | **Cookie wins by default.** Flip to bearer-wins with `bearerOverridesCookie=true`. | Safer against browser/extension/proxy bearer injection scenarios. The cookie is the authoritative authenticator when present. |
+| `Authorization` strip | `stripAuthorizationHeader=true` by default. | Keeps the raw token out of downstream services and their logs. |
+| Excluded URLs | `Authorization` is stripped on excluded paths when `enableBearerAuth=true`. | Prevents bearer leakage into public health/metrics endpoint logs and prevents recon via excluded paths. |
+| Per-IP throttle | After `bearerFailureThreshold` consecutive 401s from one source IP within `bearerFailureWindowSeconds`, further bearer requests from that IP return `429 Too Many Requests` + `Retry-After` for `bearerFailurePenaltySeconds`. | Limits offline-guessing-style attacks and protects the shared rate-limiter / JWKS endpoint. |
+| Optional introspection | `requireTokenIntrospection=true` calls RFC 7662 introspection on every cache miss. Introspection result is cached briefly. Endpoint failure returns `503` (distinguishes infra outage from credential rejection). | Real-time revocation for high-assurance environments. Adds per-request IdP latency. |
+| Response shape | `401 Unauthorized` with generic body. `WWW-Authenticate: Bearer error="invalid_token"` per RFC 6750 §3 (toggleable via `bearerEmitWWWAuthenticate`). `403` for roles/groups denial. `429` for throttle. `503` for introspection-endpoint outage. | Auditable from spec to code; reason categories never leak into the response body. |
+| Logging | Failure reason + identifier hash (SHA-256 truncated to 8 hex chars) logged at debug. Raw tokens are never logged. | Audit trail without secrets-in-logs. |
+
+## Configuration reference
+
+| Field | Default | Description |
+|---|---|---|
+| `enableBearerAuth` | `false` | Master switch for the bearer path. |
+| `audience` | (unset) | **Required** when `enableBearerAuth=true`. Reuses the existing global `audience` field. |
+| `bearerIdentifierClaim` | `"sub"` | JWT claim used as the principal identifier. `"email"` is rejected at startup. |
+| `stripAuthorizationHeader` | `true` | Remove the `Authorization` header before forwarding to the backend. Disable only when a downstream needs to re-verify the bearer. |
+| `bearerEmitWWWAuthenticate` | `true` | Include `WWW-Authenticate: Bearer error="..."` on 401 responses (RFC 6750 §3). Disable to reduce recon signal. |
+| `bearerOverridesCookie` | `false` | Cookie wins when both are present (default). Set `true` for the AWS/GCP/Kubernetes bearer-wins convention. |
+| `maxTokenAgeSeconds` | `86400` | Upper bound on `iat` claim age (24h). Set `0` to disable the check (not recommended). |
+| `maxIdentifierLength` | `256` | Length cap for the post-sanitisation identifier. |
+| `bearerFailureThreshold` | `20` | Consecutive 401s from one IP that trip the throttle. |
+| `bearerFailureWindowSeconds` | `60` | Rolling window over which 401s are counted. |
+| `bearerFailurePenaltySeconds` | `60` | Duration of the 429 penalty box after the threshold trips. |
+| `requireTokenIntrospection` | `false` | Call RFC 7662 introspection on every cache miss. Adds per-request IdP latency. |
+
+## What the bearer path does NOT do
+
+- **Human-user / browser flows.** The bearer path is M2M-only in this
+  iteration. Browser SPAs that want to attach a bearer to fetch calls work
+  if your backend treats them as machine clients, but the spec defaults are
+  tuned for service-to-service traffic.
+- **Opaque access tokens.** Tokens must be JWTs. Introspection is a
+  revocation overlay on top of JWT verification, not a substitute for it.
+- **`email_verified` enforcement.** The bearer path rejects `email` as the
+  identifier claim at startup precisely because `email_verified` is not
+  enforced in this iteration. Adding human-user bearer support is a
+  follow-up that must include this check.
+- **mTLS / API keys.** Out of scope. The `principal` abstraction enables
+  adding these later as additional auth methods that produce a principal
+  for the shared `forwardAuthorized` pipeline.
+- **SSE / WebSocket bypass with bearer.** Bypass paths keep their existing
+  cookie-only behaviour; bearer headers are ignored on those endpoints.
+  Documented limitation; widen by removing the bypass if you need bearer on
+  streaming endpoints.
+
+## Operational guidance
+
+- **Always set `strictAudienceValidation: true` when bearer is enabled.**
+  Startup logs a recommendation if you don't.
+- **Set a tight `maxTokenAgeSeconds`** for environments where tokens are
+  expected to be minted frequently — the default 24h is conservative.
+- **Enable `requireTokenIntrospection`** if your IdP supports it and
+  revocation latency matters. Bearer-path introspection caches results for
+  a short window per token.
+- **Monitor 429s.** Sustained 429 traffic indicates either a buggy client
+  loop or an active credential-stuffing attempt. The throttle is your
+  primary signal for both.
+- **`stripAuthorizationHeader=false` extends the token's blast radius** to
+  every downstream service that sees the request. Treat those services'
+  logs as token stores.
+- **Bearer reuse is normal.** Don't enable per-token rate limiting; that's
+  what `bearerFailureThreshold` is for (per-IP, not per-token).
+- **Cookie-wins is the safer default.** Only flip `bearerOverridesCookie`
+  if you control all clients and have audited that none of them present a
+  cookie alongside a bearer they don't intend to authenticate with.
+
+## Failure response matrix
+
+| Trigger | Status | Body | `WWW-Authenticate` |
+|---|---|---|---|
+| Empty bearer after prefix | 401 | `Unauthorized` | `Bearer error="invalid_request"` |
+| Token over `MaxLength` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Not a 3-segment JWT | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Disallowed `alg` (e.g. none, HS*) | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Missing / oversized / bad-charset `kid` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Signature / issuer / audience / `exp` failure | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| `iat` older than `maxTokenAgeSeconds` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Multi-audience token without matching `azp` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Detected as ID token | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| JTI blacklisted (revoked) | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Introspection reports `active=false` | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Introspection endpoint failure | 503 | `Service Unavailable` | (none) |
+| Identifier claim missing / empty | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Identifier fails sanitisation | 401 | `Unauthorized` | `Bearer error="invalid_token"` |
+| Per-IP failure threshold tripped | 429 | `Too Many Requests` | (none); `Retry-After: <bearerFailurePenaltySeconds>` |
+| Roles / groups not allowed | 403 | `Access denied` | (none) |
+
+## Known follow-ups (deferred)
+
+These are documented as future work, not blockers:
+
+- **Human-user bearer with `email_verified` enforcement.** Requires
+  decoupling the email-claim guard from the startup rejection and adding a
+  per-request `email_verified=true` check.
+- **Introspection respects `client_assertion`.** The existing introspection
+  helper uses `client_secret_basic` only; operators on `private_key_jwt`
+  will see introspection silently use basic auth.
+- **Per-route bearer configuration.** Single middleware-wide setting in this
+  iteration.
+
+## References
+
+- [PR design spec](superpowers/specs/2026-05-18-bearer-token-auth-design.md) — full design rationale, alternatives considered, and per-section sign-off history.
+- [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750) — Bearer Token Usage.
+- [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662) — OAuth 2.0 Token Introspection.
+- [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068) — JWT Profile for OAuth 2.0 Access Tokens.

docs/CONFIGURATION.md

@@ -5,6 +5,7 @@ Complete reference for all Traefik OIDC middleware configuration options.
 ## Table of Contents
 
 - [Required Parameters](#required-parameters)
+- [Client Authentication](#client-authentication)
 - [Optional Parameters](#optional-parameters)
 - [Security Options](#security-options)
 - [Session Management](#session-management)
@@ -22,7 +23,7 @@ Complete reference for all Traefik OIDC middleware configuration options.
 |-----------|------|-------------|---------|
 | `providerURL` | string | Base URL of the OIDC provider | `https://accounts.google.com` |
 | `clientID` | string | OAuth 2.0 client identifier | `1234567890.apps.googleusercontent.com` |
-| `clientSecret` | string | OAuth 2.0 client secret | `your-client-secret` |
+| `clientSecret` | string | OAuth 2.0 client secret. Required when `clientAuthMethod` is unset, `client_secret_post`, or `client_secret_basic`. Optional when `clientAuthMethod: private_key_jwt`. | `your-client-secret` |
 | `sessionEncryptionKey` | string | Key for encrypting session data (min 32 bytes) | `your-32-byte-encryption-key-here` |
 | `callbackURL` | string | Path where provider redirects after authentication | `/oauth2/callback` |
 
@@ -45,6 +46,129 @@ spec:
 
 ---
 
+## Client Authentication
+
+The middleware supports three client authentication methods at the token and
+revocation endpoints. The default is `client_secret_post` (current behavior);
+`private_key_jwt` is opt-in and backwards compatible.
+
+| Method | Default | Description |
+|--------|---------|-------------|
+| `client_secret_post` | yes | `client_id` + `client_secret` in the request body. |
+| `client_secret_basic` | no | RFC 6749 §2.3.1 — `client_id` + `client_secret` in the `Authorization: Basic` header (form-urlencoded then base64); not in the body. |
+| `private_key_jwt` | no | RFC 7523 §2.2 — plugin signs a short-lived JWT with a private key and sends it as `client_assertion`. |
+
+Select via `clientAuthMethod`:
+
+```yaml
+clientAuthMethod: private_key_jwt
+```
+
+### client_secret_post
+
+Default. The plugin sends `client_id` and `client_secret` as form parameters
+in the token / revocation request body. No additional configuration required.
+
+### private_key_jwt
+
+Asymmetric client authentication per
+[RFC 7523 §2.2](https://www.rfc-editor.org/rfc/rfc7523). Use this when your
+IdP enforces short secret TTLs, when policy mandates secretless clients, or
+when you want to avoid distributing a shared secret to the proxy.
+
+For each token / revocation request the plugin builds a JWS with:
+
+- `iss` = `sub` = `clientID`
+- `aud` = token endpoint URL
+- `iat` = now, `exp` = now + 60s
+- `jti` = random hex per request
+- `kid` header = `clientAssertionKeyID`
+
+**Required fields:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `clientAuthMethod` | string | `client_secret_post` | Set to `private_key_jwt`. |
+| `clientAssertionPrivateKey` | string | none | Inline PEM private key. Mutually exclusive with `clientAssertionKeyPath`. PKCS#8, PKCS#1, and SEC1 formats accepted. |
+| `clientAssertionKeyPath` | string | none | Path to PEM private key on disk. Mutually exclusive with `clientAssertionPrivateKey`. |
+| `clientAssertionKeyID` | string | none | `kid` header inserted in the JWS. Must match the public key registered with the IdP. |
+| `clientAssertionAlg` | string | `RS256` | One of `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384`, `ES512`. |
+
+When `clientAuthMethod: private_key_jwt`, `clientSecret` is optional.
+
+**Example — inline PEM:**
+
+```yaml
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: oidc-auth
+spec:
+  plugin:
+    traefikoidc:
+      providerURL: https://idp.example.com
+      clientID: my-client-id
+      sessionEncryptionKey: your-32-byte-encryption-key-here
+      callbackURL: /oauth2/callback
+      clientAuthMethod: private_key_jwt
+      clientAssertionKeyID: key-2026-01
+      clientAssertionAlg: RS256
+      clientAssertionPrivateKey: |
+        -----BEGIN PRIVATE KEY-----
+        MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7VJTUt9Us8cKj
+        MZj4ev7QnMa1mYV3Kx1jRkH5YwXQ7N2J2j8K5pP6h0oZmXq1yQv4r8wZb3sH9D2k
+        ... (truncated) ...
+        -----END PRIVATE KEY-----
+```
+
+**Example — key on disk:**
+
+```yaml
+clientAuthMethod: private_key_jwt
+clientAssertionKeyPath: /etc/traefik/oidc/client-key.pem
+clientAssertionKeyID: key-2026-01
+clientAssertionAlg: RS256
+```
+
+**Generating an RS256 key with OpenSSL:**
+
+```bash
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 \
+  -out client-key.pem
+openssl rsa -in client-key.pem -pubout -out client-pub.pem
+```
+
+Register `client-pub.pem` (or its JWK form) with your IdP under the same
+`kid` you set in `clientAssertionKeyID`.
+
+**Notes:**
+
+- The private key is parsed once at plugin startup. Key rotation requires a
+  Traefik reload.
+- Assertion lifetime is fixed at 60 seconds.
+- A fresh random `jti` is generated per request.
+- The `aud` claim is the token endpoint URL (from discovery).
+- Tracking issue:
+  [#135](https://github.com/lukaszraczylo/traefikoidc/issues/135).
+
+### client_secret_basic
+
+Per [RFC 6749 §2.3.1][rfc6749-2-3-1], the plugin sends the client credentials
+in an `Authorization: Basic` header instead of the body. Both halves
+(`client_id`, `client_secret`) are form-urlencoded individually, joined with
+a colon, then base64-encoded. Use this when your IdP requires Basic auth at
+the token endpoint and rejects credentials in the body.
+
+```yaml
+clientAuthMethod: client_secret_basic
+clientID: your-client-id
+clientSecret: your-client-secret
+```
+
+[rfc6749-2-3-1]: https://www.rfc-editor.org/rfc/rfc6749#section-2.3.1
+
+---
+
 ## Optional Parameters
 
 | Parameter | Type | Default | Description |
@@ -54,11 +178,17 @@ spec:
 | `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 |
-| `revocationURL` | string | auto-discovered | Token revocation endpoint |
-| `oidcEndSessionURL` | string | auto-discovered | Provider's end session endpoint |
+| `excludedURLs` | []string | none | Paths that bypass authentication, matched at a path-segment or file-extension boundary |
+| `revocationURL` | string | auto-discovered | Token revocation endpoint. Takes precedence over the discovered value. |
+| `oidcEndSessionURL` | string | auto-discovered | Provider's end session endpoint. Takes precedence over the discovered value. |
+| `introspectionURL` | string | auto-discovered | RFC 7662 token introspection endpoint. Set this when your IdP omits `introspection_endpoint` from discovery. Takes precedence over the discovered value. |
 | `enablePKCE` | bool | `false` | Enable PKCE for authorization code flow |
 | `minimalHeaders` | bool | `false` | Reduce forwarded headers |
+| `clientAuthMethod` | string | `client_secret_post` | Client authentication method at token/revocation endpoints. One of `client_secret_post`, `client_secret_basic`, `private_key_jwt`. See [Client Authentication](#client-authentication). |
+| `clientAssertionPrivateKey` | string | none | Inline PEM private key for `private_key_jwt`. Mutually exclusive with `clientAssertionKeyPath`. PKCS#8 / PKCS#1 / SEC1. |
+| `clientAssertionKeyPath` | string | none | Path to PEM private key on disk for `private_key_jwt`. Mutually exclusive with `clientAssertionPrivateKey`. |
+| `clientAssertionKeyID` | string | none | `kid` header for `private_key_jwt` assertions. Required when `clientAuthMethod: private_key_jwt`. |
+| `clientAssertionAlg` | string | `RS256` | Signing algorithm for `private_key_jwt`. One of `RS256/384/512`, `PS256/384/512`, `ES256/384/512`. |
 
 ### TLS Termination at Load Balancer
 
@@ -105,7 +235,8 @@ SSE / WebSocket connection.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `audience` | string | `clientID` | Expected audience for access token validation |
+| `audience` | string | `clientID`, or `resource` if set | Expected audience for access token validation |
+| `resource` | string | none | RFC 8707 resource indicator, alternative to `audience` for supporting IdPs — see [docs/RFC8707.md](RFC8707.md) |
 | `strictAudienceValidation` | bool | `false` | Reject sessions with audience mismatch |
 | `allowOpaqueTokens` | bool | `false` | Enable opaque token support via RFC 7662 |
 | `requireTokenIntrospection` | bool | `false` | Require introspection for opaque tokens |
@@ -117,6 +248,16 @@ audience: "https://my-api.example.com"
 strictAudienceValidation: true
 ```
 
+#### RFC 8707 Resource Indicators
+
+```yaml
+resource: "https://api.example.com"
+```
+
+Alternative to `audience` for IdPs that implement [RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707).
+See [docs/RFC8707.md](RFC8707.md) for exactly what request is made, why only a single
+resource is supported, and current per-provider support.
+
 #### Opaque Token Support
 
 ```yaml
@@ -132,6 +273,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
@@ -282,22 +443,62 @@ minimalHeaders: true  # Only forwards X-Forwarded-User
 ```yaml
 headers:
   - name: "X-User-Email"
-    value: "{{{{.Claims.email}}}}"
+    value: "{{.Claims.email}}"
   - name: "X-User-ID"
-    value: "{{{{.Claims.sub}}}}"
+    value: "{{.Claims.sub}}"
   - name: "Authorization"
-    value: "Bearer {{{{.AccessToken}}}}"
+    value: "Bearer {{.AccessToken}}"
   - name: "X-User-Roles"
-    value: "{{{{range $i, $e := .Claims.roles}}}}{{{{if $i}}}},{{{{end}}}}{{{{$e}}}}{{{{end}}}}"
+    value: "{{range $i, $e := .Claims.roles}}{{if $i}},{{end}}{{$e}}{{end}}"
 ```
 
 **Template Variables:**
-- `{{.Claims.field}}` - ID token claims
+- `{{.Claims.field}}` - ID token claims (only whitelisted fields; see below)
 - `{{.AccessToken}}` - Raw access token
-- `{{.IdToken}}` - Raw ID token
+- `{{.IdToken}}` / `{{.IDToken}}` - Raw ID token (both spellings work)
 - `{{.RefreshToken}}` - Raw refresh token
 
-**Important:** Use double curly braces (`{{{{` and `}}}}`) to escape templates in YAML.
+**Important — file provider only:** Traefik's file provider runs every dynamic
+configuration file through Go templating before the plugin sees it, so plain
+`{{ }}` fails there with `can't evaluate field AccessToken in type bool`.
+Escape with a raw string: ``value: "{{`{{.Claims.email}}`}}"``. All other
+providers (Kubernetes CRD, Docker labels, Consul, ...) pass the value through
+untouched — use the plain form shown above. Do not use quadruple braces
+(`{{{{ }}}}`); no configuration path collapses them, and template validation
+rejects them (issues #149, #151).
+
+**Validation and the claims whitelist.** Header templates are parsed and
+validated when the middleware loads; an invalid or disallowed template stops the
+middleware from starting (the route then returns Traefik's
+`invalid handler type: <nil>`). To prevent a template from accidentally
+forwarding raw tokens or sensitive claims, only a fixed set of claim fields may
+be emitted — the standard OIDC claims plus common provider claims (`email`,
+`name`, `given_name`, `family_name`, `preferred_username`, `sub`, `groups`,
+`roles`, `internal_role`, `role`, `department`, `organization`, `realm_access`,
+`resource_access`, `oid`, `tid`, `upn`, `hd`, `picture`, `locale`, `zoneinfo`,
+`phone_number`, `email_verified`, `updated_at`; the authoritative list is
+`safeClaimsFields` in `template_validation.go`). Rejected: rendering the whole
+context (`{{.}}`, `{{$}}`) or the whole claims map (`{{.Claims}}`), any claim not
+on the list, functions other than `get`/`default`, and `range`/`with` that do not
+target a specific listed claim (e.g. `{{range .Claims}}` is rejected; `{{range
+.Claims.groups}}` is allowed).
+
+**`allowedClaims`** extends the whitelist for claims your provider issues that
+are not built in:
+
+```yaml
+allowedClaims:
+  - employee_id
+  - cost_center
+headers:
+  - name: "X-Employee-Id"
+    value: "{{.Claims.employee_id}}"
+```
+
+Listed names apply to both direct access (`{{.Claims.employee_id}}`) and
+`get` (`{{get .Claims "employee_id"}}`). Subfields of a whitelisted map-valued
+claim (e.g. `realm_access.roles`) are already accessible without listing them
+individually.
 
 ---
 

docs/RFC8707.md

@@ -0,0 +1,54 @@
+# RFC 8707 Resource Indicators
+
+`resource` ([Config.Resource](../settings.go)) is an alternative to `audience` for IdPs that
+implement [RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707). See
+[docs/CONFIGURATION.md](CONFIGURATION.md#audience-validation) for the config reference; this
+document covers exactly what request is made and which providers support it.
+
+## What the plugin sends
+
+- One `resource` parameter on the authorization request (`buildAuthURL`), added before
+  `extraAuthParams` so an operator-configured `resource` key there cannot override or
+  duplicate it.
+- The same `resource` parameter on both the `authorization_code` and `refresh_token` grants
+  (`exchangeTokens`), per RFC 8707 §2.2 — so a refreshed token keeps the same audience binding
+  as the original grant.
+
+Only a single resource is supported, not a list. RFC 8707 allows a server to accept multiple
+`resource` values and scope the issued token to a subset of them, but no provider found to
+support the parameter at all handles that usefully: one provider tested rejects a request
+naming more than one resource with HTTP 400 `invalid_target`; node-oidc-provider accepts
+multiple resources but issues an opaque access token bound to none of them. A single value
+avoids both failure modes.
+
+## Relationship to `audience`
+
+`resource` and `audience` both feed the same access-token audience check —
+`strictAudienceValidation` applies identically to either — but they produce different requests
+on the wire:
+
+- `audience`, when explicitly configured, is sent as a non-standard `audience` request
+  parameter (see [docs/AUTH0\_AUDIENCE\_GUIDE.md](AUTH0_AUDIENCE_GUIDE.md)).
+- `resource` is sent as the RFC 8707 `resource` parameter instead.
+- If `resource` is set and `audience` is not, the expected-audience check defaults to the
+  resource value, but this is validation-only: it does not cause an `audience` parameter to be
+  sent. Setting both is allowed — e.g. as a hedge against a provider that ignores `resource` —
+  in which case both parameters are sent.
+
+## Provider support
+
+Verified 2026-09-02 (Zitadel reverified separately against a live instance). RFC 8707 requires
+a server that does not support `resource` to *ignore* it, but not every implementation does —
+verify against your specific provider and version before relying on it.
+
+| Provider | Support | Notes |
+|---|---|---|
+| node-oidc-provider | Supported | Via its `resourceIndicators` feature. |
+| Zitadel | Ignored, not rejected | `oidc.AuthRequest` has no `resource` field; confirmed against a live instance — `/oauth/v2/authorize` returns the same `302` with or without `resource`, including a spec-invalid value. |
+| Authentik | Rejected | Returns `invalid_target` ("Resource indicators are not supported"). |
+| Keycloak | Not supported (through 26.6) | Its own guidance is an audience mapper plus `scope` instead ([keycloak/keycloak#41526](https://github.com/keycloak/keycloak/issues/41526)). |
+| Ory Hydra / Fosite | Not implemented | Uses its own non-standard `audience` request parameter instead. |
+| Azure AD / Entra ID v2.0 (MSAL) | Reported to reject | When combined with v2-style `scope`, rather than ignoring it ([writeup](https://www.groff.dev/blog/azure-entra-id-mcp-server-authentication-incompatibilities)). Do not enable against an Entra ID v2 tenant without confirming. The v1.0 endpoint has a separate, pre-RFC `resource` parameter with similar but not identical semantics. |
+| Auth0 | Not verified | Documents a Resource Parameter Compatibility Profile mapping `resource` → `audience` ([Auth0 docs](https://auth0.com/ai/docs/mcp/guides/resource-param-compatibility-profile)). |
+| AWS Cognito | Not verified | Announced Oct 2025 for user-pool authorization-code/implicit grants ([announcement](https://aws.amazon.com/about-aws/whats-new/2025/10/amazon-cognito-resource-indicators-protection-oauth-2-0-resources)). |
+| Okta, Google, GitLab | Unverified | No confirming documentation found either way. |

docs/index.html

@@ -642,7 +642,7 @@ spec:
                                     </tr>
                                     <tr class="border-b border-gray-100 dark:border-gray-800">
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientSecret</code></td>
-                                        <td class="py-2 px-3">OAuth 2.0 client secret</td>
+                                        <td class="py-2 px-3">OAuth 2.0 client secret. Only required when <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAuthMethod</code> is unset or <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret_post</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret_basic</code>.</td>
                                     </tr>
                                     <tr class="border-b border-gray-100 dark:border-gray-800">
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">sessionEncryptionKey</code></td>
@@ -735,9 +735,14 @@ spec:
                                     </tr>
                                     <tr class="border-b border-gray-100 dark:border-gray-800">
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">audience</code></td>
-                                        <td class="py-2 px-3">clientID</td>
+                                        <td class="py-2 px-3">clientID, or <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">resource</code> if set</td>
                                         <td class="py-2 px-3">Custom audience for access token validation</td>
                                     </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">resource</code></td>
+                                        <td class="py-2 px-3">none</td>
+                                        <td class="py-2 px-3">RFC 8707 resource indicator, alternative to <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">audience</code> for supporting IdPs — see docs/RFC8707.md.</td>
+                                    </tr>
                                     <tr class="border-b border-gray-100 dark:border-gray-800">
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">strictAudienceValidation</code></td>
                                         <td class="py-2 px-3">false</td>
@@ -753,15 +758,48 @@ spec:
                                         <td class="py-2 px-3">false</td>
                                         <td class="py-2 px-3">Require RFC 7662 introspection for opaque tokens</td>
                                     </tr>
-                                    <tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
                                         <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">disableReplayDetection</code></td>
                                         <td class="py-2 px-3">false</td>
                                         <td class="py-2 px-3">Disable JTI replay detection (for multi-replica without Redis)</td>
                                     </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAuthMethod</code></td>
+                                        <td class="py-2 px-3">client_secret_post</td>
+                                        <td class="py-2 px-3">Selects how the plugin authenticates to the token endpoint. One of <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret_post</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret_basic</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">private_key_jwt</code>.</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionPrivateKey</code></td>
+                                        <td class="py-2 px-3">none</td>
+                                        <td class="py-2 px-3">Inline PEM private key used to sign client assertions for <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">private_key_jwt</code>.</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionKeyPath</code></td>
+                                        <td class="py-2 px-3">none</td>
+                                        <td class="py-2 px-3">Path to a PEM private key file. Alternative to <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionPrivateKey</code>.</td>
+                                    </tr>
+                                    <tr class="border-b border-gray-100 dark:border-gray-800">
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionKeyID</code></td>
+                                        <td class="py-2 px-3">none</td>
+                                        <td class="py-2 px-3">JWS <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">kid</code> header value. Required when <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAuthMethod</code> is <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">private_key_jwt</code>.</td>
+                                    </tr>
+                                    <tr>
+                                        <td class="py-2 px-3"><code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">clientAssertionAlg</code></td>
+                                        <td class="py-2 px-3">RS256</td>
+                                        <td class="py-2 px-3">Signing algorithm for the client assertion. One of <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">RS256</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">RS384</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">RS512</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">PS256</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">PS384</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">PS512</code>, <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">ES256</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">ES384</code>/<code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">ES512</code>.</td>
+                                    </tr>
                                 </tbody>
                             </table>
                         </div>
                     </div>
+                    <div class="glass p-6 rounded-xl">
+                        <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-3">Private Key JWT (RFC 7523)</h3>
+                        <p class="text-gray-600 dark:text-gray-400 mb-3 text-sm">Use this when your IdP (Entra ID, Okta, Auth0, Keycloak) pressures short-lived secrets, or when policy mandates secretless service-to-service authentication. The plugin signs a 60-second assertion with the configured private key and sends it as <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_assertion</code> instead of <code class="bg-gray-200 dark:bg-gray-700 px-1 rounded">client_secret</code>. Public-key registration on the IdP replaces shared-secret rotation. See <a href="https://www.rfc-editor.org/rfc/rfc7523" target="_blank" rel="noopener" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 underline">RFC 7523</a> and <a href="https://github.com/lukaszraczylo/traefikoidc/issues/135" target="_blank" rel="noopener" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100 underline">issue #135</a>.</p>
+                        <pre class="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto text-sm"><code>clientAuthMethod: private_key_jwt
+clientAssertionKeyPath: /etc/traefik/oidc-client.pem
+clientAssertionKeyID: my-client-key-2026
+# clientSecret no longer required</code></pre>
+                    </div>
                     <div class="glass p-6 rounded-xl">
                         <h3 class="font-semibold text-gray-900 dark:text-gray-100 mb-3">Example: Google Workspace with Domain Restriction</h3>
 

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 {

examples/complete-traefik-config.yaml

@@ -51,7 +51,7 @@ experimental:
   plugins:
     traefikoidc:
       moduleName: github.com/lukaszraczylo/traefikoidc
-      version: v0.8.0
+      version: v1.0.29
 
 log:
   level: INFO
@@ -101,6 +101,16 @@ http:
           providerURL: "https://auth.example.com"
           callbackURL: "/oauth2/callback"
 
+          # ----------------------------------------------------------------
+          # Optional: switch to RFC 7523 private_key_jwt client auth
+          # (Entra ID, Okta, Auth0, Keycloak). Replaces clientSecret with a
+          # signed JWT assertion. See README for details and PEM formats.
+          # ----------------------------------------------------------------
+          # clientAuthMethod: "private_key_jwt"
+          # clientAssertionKeyPath: "/etc/traefik/oidc/client-key.pem"
+          # clientAssertionKeyID: "prod-key-2026"
+          # clientAssertionAlg: "RS256"   # or PS256/384/512, ES256/384/512
+
           # Session Configuration
           sessionEncryptionKey: "prod-encryption-key-64-chars-long-keep-it-secret-and-safe"
           sessionMaxAge: 28800  # 8 hours
@@ -253,7 +263,7 @@ services:
       - "--entrypoints.web.address=:80"
       - "--entrypoints.websecure.address=:443"
       - "--experimental.plugins.traefikoidc.modulename=github.com/lukaszraczylo/traefikoidc"
-      - "--experimental.plugins.traefikoidc.version=v0.8.0"
+      - "--experimental.plugins.traefikoidc.version=v1.0.29"
     ports:
       - "80:80"
       - "443:443"

examples/redis-config.yaml

@@ -6,7 +6,7 @@ experimental:
   plugins:
     traefikoidc:
       moduleName: github.com/lukaszraczylo/traefikoidc
-      version: v0.8.0
+      version: v1.0.29
 
 # Dynamic configuration (dynamic.yml or labels)
 http:

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

@@ -108,8 +108,11 @@ type TokenResponse struct {
 func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, codeOrToken string, redirectURL string, codeVerifier string) (*TokenResponse, error) {
 	data := url.Values{
 		"grant_type": {grantType},
-		"client_id":     {t.clientID},
-		"client_secret": {t.clientSecret},
+	}
+	// client_id is sent in the body for every method except client_secret_basic,
+	// where it is carried in the Authorization header per RFC 6749 §2.3.1.
+	if t.clientAuthMethod != "client_secret_basic" || t.clientAssertion != nil {
+		data.Set("client_id", t.clientID)
 	}
 
 	if grantType == "authorization_code" {
@@ -123,6 +126,13 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
 		data.Set("refresh_token", codeOrToken)
 	}
 
+	// RFC 8707 §2.2: repeat the same resource indicator sent on the
+	// authorization request so refreshed tokens keep the same audience
+	// binding as the original grant.
+	if t.resource != "" {
+		data.Set("resource", t.resource)
+	}
+
 	client := t.tokenHTTPClient
 	if client == nil {
 		// Use shared transport pool to prevent memory leaks
@@ -141,16 +151,33 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
 		}
 	}
 
-	// Read tokenURL with RLock
+	// Read tokenURL with RLock — needed as audience for private_key_jwt (RFC 7523 §3).
 	t.metadataMu.RLock()
 	tokenURL := t.tokenURL
 	t.metadataMu.RUnlock()
 
+	useBasicAuth := false
+	if t.clientAssertion != nil {
+		assertion, err := t.clientAssertion.Sign(tokenURL, t.clientID)
+		if err != nil {
+			return nil, fmt.Errorf("failed to sign client assertion: %w", err)
+		}
+		data.Set("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer")
+		data.Set("client_assertion", assertion)
+	} else if t.clientAuthMethod == "client_secret_basic" {
+		useBasicAuth = true
+	} else {
+		data.Set("client_secret", t.clientSecret)
+	}
+
 	req, err := http.NewRequestWithContext(ctx, "POST", tokenURL, strings.NewReader(data.Encode()))
 	if err != nil {
 		return nil, fmt.Errorf("failed to create token request: %w", err)
 	}
 	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	if useBasicAuth {
+		setOAuthBasicAuth(req, t.clientID, t.clientSecret)
+	}
 
 	resp, err := client.Do(req)
 	if err != nil {
@@ -372,10 +399,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
@@ -394,7 +430,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.
@@ -423,6 +459,19 @@ func BuildLogoutURL(endSessionURL, idToken, postLogoutRedirectURI string) (strin
 	return u.String(), nil
 }
 
+// setOAuthBasicAuth sets the Authorization header per RFC 6749 §2.3.1: the
+// client_id and client_secret are form-urlencoded individually, joined with a
+// colon, then base64-encoded. This differs from http.Request.SetBasicAuth,
+// which skips the form-urlencode step — that matters for credentials with
+// reserved characters (`:`, `@`, `+`, `%`, etc.) where the wire format would
+// otherwise diverge from what the spec mandates.
+func setOAuthBasicAuth(req *http.Request, clientID, clientSecret string) {
+	user := url.QueryEscape(clientID)
+	pass := url.QueryEscape(clientSecret)
+	auth := base64.StdEncoding.EncodeToString([]byte(user + ":" + pass))
+	req.Header.Set("Authorization", "Basic "+auth)
+}
+
 // deduplicateScopes removes duplicate scopes from a slice while preserving order.
 // This ensures that OAuth scope parameters don't contain duplicates which could
 // cause issues with some authorization servers.

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 {
+	// 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": "[email protected]",
+		"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": "[email protected]",
+		"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": "[email protected]",
+		"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")
+}

issue135_regression_test.go

@@ -0,0 +1,925 @@
+package traefikoidc
+
+// issue135_regression_test.go — regression tests for RFC 7523 private_key_jwt
+// client authentication (issue #135).
+//
+// These tests guard:
+//   - Correct JWT construction and cryptographic signature for all supported
+//     algorithms (RS*/PS*/ES*).
+//   - Proper validation of alg/key type combinations and empty-kid rejection.
+//   - JTI uniqueness across concurrent calls.
+//   - PEM variant tolerance (PKCS#8, PKCS#1, SEC1).
+//   - Config.Validate() behavior for all private_key_jwt configuration paths.
+//   - buildClientAssertionSignerFromConfig: inline PEM, file-backed PEM, default alg.
+//   - Wire-up in exchangeTokens: assertion fields sent, client_secret absent.
+//   - Wire-up in RevokeTokenWithProvider: assertion fields sent, audience = tokenURL.
+//   - Back-compat: client_secret_post path unchanged when clientAssertion == nil.
+
+import (
+	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"crypto/sha512"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/json"
+	"encoding/pem"
+	"math/big"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ── A. Signer unit tests ──────────────────────────────────────────────────────
+
+// TestIssue135_SignerRSAFamily verifies that NewClientAssertionSigner + Sign
+// produces a well-formed, cryptographically valid JWT for every RSA-family
+// algorithm (RS256/RS384/RS512/PS256/PS384/PS512).
+func TestIssue135_SignerRSAFamily(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	pemBytes := encodeRSAPKCS8(t, rsaKey)
+
+	cases := []struct {
+		alg      string
+		hashFn   func([]byte) []byte
+		isPS     bool
+		hash     crypto.Hash
+	}{
+		{"RS256", func(b []byte) []byte { h := sha256.Sum256(b); return h[:] }, false, crypto.SHA256},
+		{"RS384", func(b []byte) []byte { h := sha512.Sum384(b); return h[:] }, false, crypto.SHA384},
+		{"RS512", func(b []byte) []byte { h := sha512.Sum512(b); return h[:] }, false, crypto.SHA512},
+		{"PS256", func(b []byte) []byte { h := sha256.Sum256(b); return h[:] }, true, crypto.SHA256},
+		{"PS384", func(b []byte) []byte { h := sha512.Sum384(b); return h[:] }, true, crypto.SHA384},
+		{"PS512", func(b []byte) []byte { h := sha512.Sum512(b); return h[:] }, true, crypto.SHA512},
+	}
+
+	const (
+		audience = "https://example.com/token"
+		clientID = "client-abc"
+		kid      = "kid-1"
+	)
+
+	for _, tc := range cases {
+		t.Run(tc.alg, func(t *testing.T) {
+			signer, err := NewClientAssertionSigner(pemBytes, tc.alg, kid)
+			require.NoError(t, err)
+
+			jwtStr, err := signer.Sign(audience, clientID)
+			require.NoError(t, err)
+
+			parts := strings.Split(jwtStr, ".")
+			require.Len(t, parts, 3, "JWT must have three dot-separated parts")
+
+			// Decode and check header.
+			hdr := decodeJSONPart(t, parts[0])
+			assert.Equal(t, tc.alg, hdr["alg"])
+			assert.Equal(t, "JWT", hdr["typ"])
+			assert.Equal(t, kid, hdr["kid"])
+
+			// Decode and check claims.
+			clms := decodeJSONPart(t, parts[1])
+			assert.Equal(t, clientID, clms["iss"])
+			assert.Equal(t, clientID, clms["sub"])
+			assert.Equal(t, audience, clms["aud"])
+
+			iat, ok := clms["iat"].(float64)
+			require.True(t, ok, "iat must be numeric")
+			exp, ok := clms["exp"].(float64)
+			require.True(t, ok, "exp must be numeric")
+			assert.InDelta(t, 60, exp-iat, 2, "exp-iat must equal ~60s")
+
+			now := float64(time.Now().Unix())
+			assert.True(t, iat <= now+2 && iat >= now-5, "iat must be current time ±5s")
+
+			jti, ok := clms["jti"].(string)
+			require.True(t, ok, "jti must be a string")
+			assert.Len(t, jti, 32, "jti must be 32-char hex (16 bytes → hex)")
+
+			// Verify cryptographic signature.
+			sigInput := parts[0] + "." + parts[1]
+			digest := tc.hashFn([]byte(sigInput))
+			sigBytes, err := base64.RawURLEncoding.DecodeString(parts[2])
+			require.NoError(t, err)
+
+			pub := &rsaKey.PublicKey
+			if tc.isPS {
+				opts := &rsa.PSSOptions{SaltLength: rsa.PSSSaltLengthEqualsHash, Hash: tc.hash}
+				assert.NoError(t, rsa.VerifyPSS(pub, tc.hash, digest, sigBytes, opts),
+					"PSS signature verification failed for %s", tc.alg)
+			} else {
+				assert.NoError(t, rsa.VerifyPKCS1v15(pub, tc.hash, digest, sigBytes),
+					"PKCS1v15 signature verification failed for %s", tc.alg)
+			}
+		})
+	}
+}
+
+// TestIssue135_SignerECDSAFamily verifies correct JWT production for all
+// ECDSA algorithms (ES256/ES384/ES512) including that the signature is the
+// raw r||s encoding (not ASN.1 DER) and is verifiable with the matching key.
+func TestIssue135_SignerECDSAFamily(t *testing.T) {
+	cases := []struct {
+		alg    string
+		curve  elliptic.Curve
+		hashFn func([]byte) []byte
+		hash   crypto.Hash
+	}{
+		{"ES256", elliptic.P256(), func(b []byte) []byte { h := sha256.Sum256(b); return h[:] }, crypto.SHA256},
+		{"ES384", elliptic.P384(), func(b []byte) []byte { h := sha512.Sum384(b); return h[:] }, crypto.SHA384},
+		{"ES512", elliptic.P521(), func(b []byte) []byte { h := sha512.Sum512(b); return h[:] }, crypto.SHA512},
+	}
+
+	const (
+		audience = "https://idp.example.com/token"
+		clientID = "ec-client"
+		kid      = "ec-kid"
+	)
+
+	for _, tc := range cases {
+		t.Run(tc.alg, func(t *testing.T) {
+			ecKey, err := ecdsa.GenerateKey(tc.curve, rand.Reader)
+			require.NoError(t, err)
+
+			pemBytes := encodeECPKCS8(t, ecKey)
+
+			signer, err := NewClientAssertionSigner(pemBytes, tc.alg, kid)
+			require.NoError(t, err)
+
+			jwtStr, err := signer.Sign(audience, clientID)
+			require.NoError(t, err)
+
+			parts := strings.Split(jwtStr, ".")
+			require.Len(t, parts, 3)
+
+			sigBytes, err := base64.RawURLEncoding.DecodeString(parts[2])
+			require.NoError(t, err)
+
+			byteLen := (tc.curve.Params().BitSize + 7) / 8
+			assert.Len(t, sigBytes, 2*byteLen,
+				"ECDSA signature must be raw r||s (2×%d bytes for %s)", byteLen, tc.alg)
+
+			r := new(big.Int).SetBytes(sigBytes[:byteLen])
+			s := new(big.Int).SetBytes(sigBytes[byteLen:])
+
+			sigInput := parts[0] + "." + parts[1]
+			digest := tc.hashFn([]byte(sigInput))
+
+			ok := ecdsa.Verify(&ecKey.PublicKey, digest, r, s)
+			assert.True(t, ok, "ECDSA signature verification failed for %s", tc.alg)
+		})
+	}
+}
+
+// TestIssue135_SignerRejectsAlgKeyMismatch verifies that the signer constructor
+// rejects type mismatches between key type and algorithm, unknown algorithms,
+// and an empty kid.
+func TestIssue135_SignerRejectsAlgKeyMismatch(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	rsaPEM := encodeRSAPKCS8(t, rsaKey)
+
+	ecKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	require.NoError(t, err)
+	ecPEM := encodeECPKCS8(t, ecKey)
+
+	cases := []struct {
+		name     string
+		pemBytes []byte
+		alg      string
+		kid      string
+		wantErr  string
+	}{
+		{
+			name:    "RSA key with ES256",
+			pemBytes: rsaPEM,
+			alg:     "ES256",
+			kid:     "k1",
+			wantErr: "EC key",
+		},
+		{
+			name:    "EC key with RS256",
+			pemBytes: ecPEM,
+			alg:     "RS256",
+			kid:     "k1",
+			wantErr: "RSA key",
+		},
+		{
+			name:    "unknown alg HS256",
+			pemBytes: rsaPEM,
+			alg:     "HS256",
+			kid:     "k1",
+			wantErr: "unsupported",
+		},
+		{
+			name:    "empty kid",
+			pemBytes: rsaPEM,
+			alg:     "RS256",
+			kid:     "",
+			wantErr: "kid must not be empty",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := NewClientAssertionSigner(tc.pemBytes, tc.alg, tc.kid)
+			require.Error(t, err)
+			assert.Contains(t, strings.ToLower(err.Error()), strings.ToLower(tc.wantErr),
+				"error should mention %q", tc.wantErr)
+		})
+	}
+}
+
+// TestIssue135_SignerJTIUniqueness signs 50 assertions with the same signer
+// and asserts all jti values are distinct. Guards against broken entropy reuse.
+func TestIssue135_SignerJTIUniqueness(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	pemBytes := encodeRSAPKCS8(t, rsaKey)
+
+	signer, err := NewClientAssertionSigner(pemBytes, "RS256", "jti-kid")
+	require.NoError(t, err)
+
+	seen := make(map[string]bool, 50)
+	for i := range 50 {
+		jwtStr, err := signer.Sign("https://example.com/token", "client-x")
+		require.NoError(t, err)
+
+		parts := strings.Split(jwtStr, ".")
+		require.Len(t, parts, 3)
+		clms := decodeJSONPart(t, parts[1])
+		jti, ok := clms["jti"].(string)
+		require.True(t, ok)
+		assert.False(t, seen[jti], "jti %q was reused at iteration %d", jti, i)
+		seen[jti] = true
+	}
+}
+
+// TestIssue135_SignerPEMVariants confirms that all PEM block types understood
+// by NewClientAssertionSigner are parsed correctly: PKCS#8 ("PRIVATE KEY"),
+// PKCS#1 ("RSA PRIVATE KEY"), and SEC1 ("EC PRIVATE KEY").
+func TestIssue135_SignerPEMVariants(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	ecKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	require.NoError(t, err)
+
+	t.Run("RSA PKCS8", func(t *testing.T) {
+		pemBytes := encodeRSAPKCS8(t, rsaKey)
+		signer, err := NewClientAssertionSigner(pemBytes, "RS256", "k1")
+		require.NoError(t, err)
+		assertValidRSAJWT(t, rsaKey, signer, "RS256")
+	})
+
+	t.Run("RSA PKCS1", func(t *testing.T) {
+		der := x509.MarshalPKCS1PrivateKey(rsaKey)
+		pemBytes := pem.EncodeToMemory(&pem.Block{Type: "RSA PRIVATE KEY", Bytes: der})
+		signer, err := NewClientAssertionSigner(pemBytes, "RS256", "k1")
+		require.NoError(t, err)
+		assertValidRSAJWT(t, rsaKey, signer, "RS256")
+	})
+
+	t.Run("EC PKCS8", func(t *testing.T) {
+		pemBytes := encodeECPKCS8(t, ecKey)
+		signer, err := NewClientAssertionSigner(pemBytes, "ES256", "k1")
+		require.NoError(t, err)
+		jwtStr, err := signer.Sign("https://example.com/token", "cid")
+		require.NoError(t, err)
+		parts := strings.Split(jwtStr, ".")
+		require.Len(t, parts, 3)
+	})
+
+	t.Run("EC SEC1", func(t *testing.T) {
+		der, err := x509.MarshalECPrivateKey(ecKey)
+		require.NoError(t, err)
+		pemBytes := pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: der})
+		signer, err := NewClientAssertionSigner(pemBytes, "ES256", "k1")
+		require.NoError(t, err)
+		jwtStr, err := signer.Sign("https://example.com/token", "cid")
+		require.NoError(t, err)
+		parts := strings.Split(jwtStr, ".")
+		require.Len(t, parts, 3)
+	})
+}
+
+// ── B. Config validation ──────────────────────────────────────────────────────
+
+// TestIssue135_ConfigValidation table-drives Config.Validate() for every
+// client-authentication-related validation branch.
+func TestIssue135_ConfigValidation(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	validPEM := string(encodeRSAPKCS8(t, rsaKey))
+
+	// baseConfig returns the minimum valid config, modified per test case.
+	base := func() *Config {
+		return &Config{
+			ProviderURL:          "https://idp.example.com",
+			CallbackURL:          "/cb",
+			ClientID:             "cid",
+			ClientSecret:         "secret",
+			SessionEncryptionKey: "01234567890123456789012345678901", // 32 chars
+			RateLimit:            100,
+		}
+	}
+
+	cases := []struct {
+		name     string
+		mutate   func(*Config)
+		wantErr  string // empty = expect nil error
+	}{
+		{
+			name:    "default empty method + secret ok",
+			mutate:  func(c *Config) { /* nothing extra */ },
+			wantErr: "",
+		},
+		{
+			name: "explicit client_secret_post + secret ok",
+			mutate: func(c *Config) {
+				c.ClientAuthMethod = "client_secret_post"
+			},
+			wantErr: "",
+		},
+		{
+			name: "private_key_jwt inline key + kid ok",
+			mutate: func(c *Config) {
+				c.ClientAuthMethod = "private_key_jwt"
+				c.ClientSecret = ""
+				c.ClientAssertionPrivateKey = validPEM
+				c.ClientAssertionKeyID = "k1"
+			},
+			wantErr: "",
+		},
+		{
+			name: "private_key_jwt no key at all",
+			mutate: func(c *Config) {
+				c.ClientAuthMethod = "private_key_jwt"
+				c.ClientSecret = ""
+				c.ClientAssertionKeyID = "k1"
+			},
+			wantErr: "clientAssertionPrivateKey",
+		},
+		{
+			name: "private_key_jwt both inline and path",
+			mutate: func(c *Config) {
+				c.ClientAuthMethod = "private_key_jwt"
+				c.ClientSecret = ""
+				c.ClientAssertionPrivateKey = validPEM
+				c.ClientAssertionKeyPath = "/tmp/key.pem"
+				c.ClientAssertionKeyID = "k1"
+			},
+			wantErr: "only one of",
+		},
+		{
+			name: "private_key_jwt key but no kid",
+			mutate: func(c *Config) {
+				c.ClientAuthMethod = "private_key_jwt"
+				c.ClientSecret = ""
+				c.ClientAssertionPrivateKey = validPEM
+			},
+			wantErr: "clientAssertionKeyID",
+		},
+		{
+			name: "private_key_jwt unsupported alg HS256",
+			mutate: func(c *Config) {
+				c.ClientAuthMethod = "private_key_jwt"
+				c.ClientSecret = ""
+				c.ClientAssertionPrivateKey = validPEM
+				c.ClientAssertionKeyID = "k1"
+				c.ClientAssertionAlg = "HS256"
+			},
+			wantErr: "is not supported",
+		},
+		{
+			name: "unknown client auth method",
+			mutate: func(c *Config) {
+				c.ClientAuthMethod = "weird"
+			},
+			wantErr: "is not supported",
+		},
+		{
+			name: "client_secret_post with no secret",
+			mutate: func(c *Config) {
+				c.ClientAuthMethod = "client_secret_post"
+				c.ClientSecret = ""
+			},
+			wantErr: "clientSecret is required",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := base()
+			tc.mutate(cfg)
+			err := cfg.Validate()
+			if tc.wantErr == "" {
+				assert.NoError(t, err)
+			} else {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tc.wantErr,
+					"error must mention %q", tc.wantErr)
+			}
+		})
+	}
+}
+
+// TestIssue135_ConfigKeyPathLoadsFile verifies that buildClientAssertionSignerFromConfig
+// reads the PEM key from disk when ClientAssertionKeyPath is set.
+func TestIssue135_ConfigKeyPathLoadsFile(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	pemBytes := encodeRSAPKCS8(t, rsaKey)
+
+	dir := t.TempDir()
+	keyFile := dir + "/private.pem"
+	require.NoError(t, os.WriteFile(keyFile, pemBytes, 0o600))
+
+	cfg := &Config{
+		ClientAuthMethod:    "private_key_jwt",
+		ClientAssertionKeyPath: keyFile,
+		ClientAssertionKeyID:   "file-kid",
+		ClientAssertionAlg:     "RS256",
+	}
+
+	signer, err := buildClientAssertionSignerFromConfig(cfg)
+	require.NoError(t, err, "should load signer from key file")
+	require.NotNil(t, signer)
+
+	// Confirm signer produces a valid JWT.
+	jwtStr, err := signer.Sign("https://example.com/token", "client-from-file")
+	require.NoError(t, err)
+	parts := strings.Split(jwtStr, ".")
+	require.Len(t, parts, 3, "should produce a 3-part JWT")
+}
+
+// ── C. Wire-up — exchangeTokens ───────────────────────────────────────────────
+
+// TestIssue135_AuthCodeExchangeUsesAssertion confirms that exchangeTokens sends
+// client_assertion + client_assertion_type instead of client_secret when a
+// ClientAssertionSigner is configured, and that the assertion JWT is valid.
+func TestIssue135_AuthCodeExchangeUsesAssertion(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	pemBytes := encodeRSAPKCS8(t, rsaKey)
+
+	var capturedBody []byte
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body := make([]byte, r.ContentLength)
+		_, _ = r.Body.Read(body)
+		capturedBody = body
+		w.Header().Set("Content-Type", "application/json")
+		// Return a minimal token response so exchangeTokens doesn't error.
+		_ = json.NewEncoder(w).Encode(TokenResponse{
+			AccessToken:  "at",
+			IDToken:      "it",
+			RefreshToken: "rt",
+			TokenType:    "Bearer",
+			ExpiresIn:    3600,
+		})
+	}))
+	defer server.Close()
+
+	signer, err := NewClientAssertionSigner(pemBytes, "RS256", "wire-kid")
+	require.NoError(t, err)
+
+	oidc := &TraefikOidc{
+		clientID:        "wire-client",
+		tokenHTTPClient: server.Client(),
+		clientAssertion: signer,
+		logger:          GetSingletonNoOpLogger(),
+	}
+	oidc.tokenURL = server.URL
+
+	_, err = oidc.exchangeTokens(context.Background(), "authorization_code", "code-x", "https://app/cb", "")
+	require.NoError(t, err)
+
+	form, err := url.ParseQuery(string(capturedBody))
+	require.NoError(t, err)
+
+	assert.Equal(t, "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+		form.Get("client_assertion_type"), "client_assertion_type must be set")
+	assertionJWT := form.Get("client_assertion")
+	assert.NotEmpty(t, assertionJWT, "client_assertion must be present")
+	assert.Empty(t, form.Get("client_secret"), "client_secret must not be sent when using assertion")
+	assert.Equal(t, "wire-client", form.Get("client_id"))
+	assert.Equal(t, "code-x", form.Get("code"))
+	assert.Equal(t, "authorization_code", form.Get("grant_type"))
+
+	// Verify assertion JWT: header, claims, signature.
+	parts := strings.Split(assertionJWT, ".")
+	require.Len(t, parts, 3)
+
+	hdr := decodeJSONPart(t, parts[0])
+	assert.Equal(t, "RS256", hdr["alg"])
+
+	clms := decodeJSONPart(t, parts[1])
+	assert.Equal(t, "wire-client", clms["iss"])
+	assert.Equal(t, "wire-client", clms["sub"])
+	assert.Equal(t, server.URL, clms["aud"],
+		"audience must be the tokenURL (RFC 7523 §3)")
+
+	// Verify signature with RSA public key.
+	sigInput := parts[0] + "." + parts[1]
+	digest := sha256SumBytes([]byte(sigInput))
+	sigBytes, err := base64.RawURLEncoding.DecodeString(parts[2])
+	require.NoError(t, err)
+	assert.NoError(t, rsa.VerifyPKCS1v15(&rsaKey.PublicKey, crypto.SHA256, digest, sigBytes))
+}
+
+// TestIssue135_RefreshTokenUsesAssertion verifies that the refresh_token grant
+// type also sends client_assertion and the correct form fields.
+func TestIssue135_RefreshTokenUsesAssertion(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	pemBytes := encodeRSAPKCS8(t, rsaKey)
+
+	var capturedForm url.Values
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.NoError(t, r.ParseForm())
+		capturedForm = r.Form
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(TokenResponse{
+			AccessToken: "new-at",
+			TokenType:   "Bearer",
+			ExpiresIn:   3600,
+		})
+	}))
+	defer server.Close()
+
+	signer, err := NewClientAssertionSigner(pemBytes, "RS256", "rt-kid")
+	require.NoError(t, err)
+
+	oidc := &TraefikOidc{
+		clientID:        "rt-client",
+		tokenHTTPClient: server.Client(),
+		clientAssertion: signer,
+		logger:          GetSingletonNoOpLogger(),
+	}
+	oidc.tokenURL = server.URL
+
+	_, err = oidc.exchangeTokens(context.Background(), "refresh_token", "rt-y", "", "")
+	require.NoError(t, err)
+
+	assert.Equal(t, "refresh_token", capturedForm.Get("grant_type"))
+	assert.Equal(t, "rt-y", capturedForm.Get("refresh_token"))
+	assert.Equal(t, "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+		capturedForm.Get("client_assertion_type"))
+	assert.NotEmpty(t, capturedForm.Get("client_assertion"))
+	assert.Empty(t, capturedForm.Get("client_secret"))
+}
+
+// TestIssue135_BackcompatClientSecretPath confirms that exchangeTokens sends
+// client_secret and does NOT send client_assertion when clientAssertion is nil.
+func TestIssue135_BackcompatClientSecretPath(t *testing.T) {
+	var capturedForm url.Values
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.NoError(t, r.ParseForm())
+		capturedForm = r.Form
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(TokenResponse{
+			AccessToken: "at",
+			TokenType:   "Bearer",
+			ExpiresIn:   3600,
+		})
+	}))
+	defer server.Close()
+
+	oidc := &TraefikOidc{
+		clientID:        "legacy-client",
+		clientSecret:    "legacy-secret",
+		tokenHTTPClient: server.Client(),
+		clientAssertion: nil, // back-compat path
+		logger:          GetSingletonNoOpLogger(),
+	}
+	oidc.tokenURL = server.URL
+
+	_, err := oidc.exchangeTokens(context.Background(), "authorization_code", "code-bc", "https://app/cb", "")
+	require.NoError(t, err)
+
+	assert.Equal(t, "legacy-secret", capturedForm.Get("client_secret"),
+		"client_secret must be sent on the classic path")
+	assert.Empty(t, capturedForm.Get("client_assertion"),
+		"client_assertion must NOT be present on the classic path")
+	assert.Empty(t, capturedForm.Get("client_assertion_type"),
+		"client_assertion_type must NOT be present on the classic path")
+}
+
+// TestIssue135_ClientSecretBasicAuth verifies that when clientAuthMethod is
+// "client_secret_basic", exchangeTokens sends an HTTP Basic Authorization
+// header carrying url-encoded client_id:client_secret per RFC 6749 §2.3.1,
+// and that neither client_id nor client_secret appears in the form body.
+func TestIssue135_ClientSecretBasicAuth(t *testing.T) {
+	var capturedAuth string
+	var capturedForm url.Values
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		capturedAuth = r.Header.Get("Authorization")
+		require.NoError(t, r.ParseForm())
+		capturedForm = r.Form
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(TokenResponse{
+			AccessToken: "at-basic", TokenType: "Bearer", ExpiresIn: 3600,
+		})
+	}))
+	defer server.Close()
+
+	oidc := &TraefikOidc{
+		clientID:         "basic-client",
+		clientSecret:     "basic-secret",
+		clientAuthMethod: "client_secret_basic",
+		tokenHTTPClient:  server.Client(),
+		logger:           GetSingletonNoOpLogger(),
+	}
+	oidc.tokenURL = server.URL
+
+	_, err := oidc.exchangeTokens(context.Background(), "authorization_code", "code-bb", "https://app/cb", "")
+	require.NoError(t, err)
+
+	require.True(t, strings.HasPrefix(capturedAuth, "Basic "),
+		"Authorization header must start with 'Basic ', got %q", capturedAuth)
+	raw, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(capturedAuth, "Basic "))
+	require.NoError(t, err, "Authorization payload must be valid base64")
+	user, pass, ok := strings.Cut(string(raw), ":")
+	require.True(t, ok, "Authorization payload must contain a single ':' separator")
+	assert.Equal(t, "basic-client", user, "client_id should round-trip through QueryEscape")
+	assert.Equal(t, "basic-secret", pass, "client_secret should round-trip through QueryEscape")
+
+	assert.Empty(t, capturedForm.Get("client_id"),
+		"client_id must NOT be in the body when using client_secret_basic")
+	assert.Empty(t, capturedForm.Get("client_secret"),
+		"client_secret must NOT be in the body when using client_secret_basic")
+	assert.Empty(t, capturedForm.Get("client_assertion"),
+		"client_assertion must NOT be present on the basic-auth path")
+}
+
+// TestIssue135_ClientSecretBasicURLEncodesReservedChars verifies that
+// credentials containing reserved characters (`:`, `+`, `/`, etc.) are
+// form-urlencoded before base64 per RFC 6749 §2.3.1, so the receiving
+// authorization server can decode them deterministically.
+func TestIssue135_ClientSecretBasicURLEncodesReservedChars(t *testing.T) {
+	var capturedAuth string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		capturedAuth = r.Header.Get("Authorization")
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(TokenResponse{AccessToken: "at", TokenType: "Bearer", ExpiresIn: 3600})
+	}))
+	defer server.Close()
+
+	const (
+		clientID     = "weird:id+1"
+		clientSecret = "p@ss/word=&" //nolint:gosec // test fixture
+	)
+
+	oidc := &TraefikOidc{
+		clientID:         clientID,
+		clientSecret:     clientSecret,
+		clientAuthMethod: "client_secret_basic",
+		tokenHTTPClient:  server.Client(),
+		logger:           GetSingletonNoOpLogger(),
+	}
+	oidc.tokenURL = server.URL
+
+	_, err := oidc.exchangeTokens(context.Background(), "authorization_code", "c", "https://app/cb", "")
+	require.NoError(t, err)
+
+	raw, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(capturedAuth, "Basic "))
+	require.NoError(t, err)
+
+	wantUser := url.QueryEscape(clientID)
+	wantPass := url.QueryEscape(clientSecret)
+	assert.Equal(t, wantUser+":"+wantPass, string(raw),
+		"both halves must be form-urlencoded before the base64 step")
+}
+
+// TestIssue135_ClientSecretBasicRevocation verifies that the revocation path
+// honors client_secret_basic identically to the token path.
+func TestIssue135_ClientSecretBasicRevocation(t *testing.T) {
+	var capturedAuth string
+	var capturedForm url.Values
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		capturedAuth = r.Header.Get("Authorization")
+		require.NoError(t, r.ParseForm())
+		capturedForm = r.Form
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	oidc := &TraefikOidc{
+		clientID:         "rev-basic",
+		clientSecret:     "rev-secret",
+		clientAuthMethod: "client_secret_basic",
+		httpClient:       server.Client(),
+		logger:           GetSingletonNoOpLogger(),
+	}
+	oidc.tokenURL = "https://idp.example.com/token"
+	oidc.revocationURL = server.URL
+
+	require.NoError(t, oidc.RevokeTokenWithProvider("opaque-tok", "access_token"))
+
+	require.True(t, strings.HasPrefix(capturedAuth, "Basic "), "got %q", capturedAuth)
+	raw, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(capturedAuth, "Basic "))
+	require.NoError(t, err)
+	assert.Equal(t, "rev-basic:rev-secret", string(raw))
+
+	assert.Equal(t, "opaque-tok", capturedForm.Get("token"))
+	assert.Equal(t, "access_token", capturedForm.Get("token_type_hint"))
+	assert.Empty(t, capturedForm.Get("client_id"),
+		"client_id must NOT be in body on Basic-auth revocation")
+	assert.Empty(t, capturedForm.Get("client_secret"),
+		"client_secret must NOT be in body on Basic-auth revocation")
+}
+
+// ── D. Wire-up — RevokeTokenWithProvider ────────────────────────────────────
+
+// TestIssue135_RevocationUsesAssertion verifies that RevokeTokenWithProvider
+// sends client_assertion (not client_secret), and that the assertion's audience
+// is the tokenURL, not the revocationURL (per RFC 7523 §3).
+func TestIssue135_RevocationUsesAssertion(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	pemBytes := encodeRSAPKCS8(t, rsaKey)
+
+	const (
+		tokenEndpoint      = "https://idp.example.com/token"  // audience for assertion
+		clientIDVal        = "revoke-client"
+	)
+
+	var capturedForm url.Values
+	// Revocation endpoint — deliberate separate URL to confirm audience != revocationURL.
+	revokeServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.NoError(t, r.ParseForm())
+		capturedForm = r.Form
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer revokeServer.Close()
+
+	signer, err := NewClientAssertionSigner(pemBytes, "RS256", "rev-kid")
+	require.NoError(t, err)
+
+	oidc := &TraefikOidc{
+		clientID:        clientIDVal,
+		clientAssertion: signer,
+		httpClient:      revokeServer.Client(),
+		logger:          GetSingletonNoOpLogger(),
+	}
+	// tokenURL drives assertion audience; revocationURL is where the POST goes.
+	oidc.tokenURL = tokenEndpoint
+	oidc.revocationURL = revokeServer.URL
+
+	err = oidc.RevokeTokenWithProvider("some-token", "refresh_token")
+	require.NoError(t, err)
+
+	assert.Equal(t, "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+		capturedForm.Get("client_assertion_type"))
+	assertionJWT := capturedForm.Get("client_assertion")
+	assert.NotEmpty(t, assertionJWT)
+	assert.Empty(t, capturedForm.Get("client_secret"),
+		"client_secret must not appear in revocation request with assertion")
+
+	// Verify the assertion audience is tokenURL (not revocationURL).
+	parts := strings.Split(assertionJWT, ".")
+	require.Len(t, parts, 3)
+	clms := decodeJSONPart(t, parts[1])
+	assert.Equal(t, tokenEndpoint, clms["aud"],
+		"assertion audience must be tokenURL, not revocationURL")
+
+	// Sanity-check cryptographic validity.
+	sigInput := parts[0] + "." + parts[1]
+	digest := sha256SumBytes([]byte(sigInput))
+	sigBytes, err := base64.RawURLEncoding.DecodeString(parts[2])
+	require.NoError(t, err)
+	assert.NoError(t, rsa.VerifyPKCS1v15(&rsaKey.PublicKey, crypto.SHA256, digest, sigBytes))
+}
+
+// ── E. End-to-end via buildClientAssertionSignerFromConfig ───────────────────
+
+// TestIssue135_BuildSignerFromInlineConfig confirms that the full config→signer
+// pipeline works for an ES256 key specified inline in the Config struct.
+func TestIssue135_BuildSignerFromInlineConfig(t *testing.T) {
+	ecKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	require.NoError(t, err)
+	pemBytes := encodeECPKCS8(t, ecKey)
+
+	cfg := &Config{
+		ClientAuthMethod:          "private_key_jwt",
+		ClientAssertionPrivateKey: string(pemBytes),
+		ClientAssertionKeyID:      "inline-ec-kid",
+		ClientAssertionAlg:        "ES256",
+	}
+
+	signer, err := buildClientAssertionSignerFromConfig(cfg)
+	require.NoError(t, err)
+	require.NotNil(t, signer)
+
+	jwtStr, err := signer.Sign("https://example.com/token", "inline-client")
+	require.NoError(t, err)
+
+	parts := strings.Split(jwtStr, ".")
+	require.Len(t, parts, 3)
+
+	hdr := decodeJSONPart(t, parts[0])
+	assert.Equal(t, "ES256", hdr["alg"])
+	assert.Equal(t, "inline-ec-kid", hdr["kid"])
+
+	// Verify the EC signature.
+	byteLen := (elliptic.P256().Params().BitSize + 7) / 8
+	sigBytes, err := base64.RawURLEncoding.DecodeString(parts[2])
+	require.NoError(t, err)
+	require.Len(t, sigBytes, 2*byteLen)
+
+	r := new(big.Int).SetBytes(sigBytes[:byteLen])
+	s := new(big.Int).SetBytes(sigBytes[byteLen:])
+	sigInput := parts[0] + "." + parts[1]
+	digest := sha256SumBytes([]byte(sigInput))
+	assert.True(t, ecdsa.Verify(&ecKey.PublicKey, digest, r, s))
+}
+
+// TestIssue135_BuildSignerDefaultsToRS256 verifies that an empty
+// ClientAssertionAlg defaults to RS256.
+func TestIssue135_BuildSignerDefaultsToRS256(t *testing.T) {
+	rsaKey := genRSAKey(t, 2048)
+	pemBytes := encodeRSAPKCS8(t, rsaKey)
+
+	cfg := &Config{
+		ClientAssertionPrivateKey: string(pemBytes),
+		ClientAssertionKeyID:      "default-alg-kid",
+		ClientAssertionAlg:        "", // intentionally empty
+	}
+
+	signer, err := buildClientAssertionSignerFromConfig(cfg)
+	require.NoError(t, err)
+
+	jwtStr, err := signer.Sign("https://example.com/token", "default-client")
+	require.NoError(t, err)
+
+	parts := strings.Split(jwtStr, ".")
+	require.Len(t, parts, 3)
+
+	hdr := decodeJSONPart(t, parts[0])
+	assert.Equal(t, "RS256", hdr["alg"], "empty alg must default to RS256")
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+// genRSAKey generates an RSA key of the given bit size, failing the test on error.
+func genRSAKey(t *testing.T, bits int) *rsa.PrivateKey {
+	t.Helper()
+	k, err := rsa.GenerateKey(rand.Reader, bits)
+	require.NoError(t, err)
+	return k
+}
+
+// encodeRSAPKCS8 marshals an RSA key as PKCS#8 PEM ("PRIVATE KEY").
+func encodeRSAPKCS8(t *testing.T, key *rsa.PrivateKey) []byte {
+	t.Helper()
+	der, err := x509.MarshalPKCS8PrivateKey(key)
+	require.NoError(t, err)
+	return pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: der})
+}
+
+// encodeECPKCS8 marshals an EC key as PKCS#8 PEM ("PRIVATE KEY").
+func encodeECPKCS8(t *testing.T, key *ecdsa.PrivateKey) []byte {
+	t.Helper()
+	der, err := x509.MarshalPKCS8PrivateKey(key)
+	require.NoError(t, err)
+	return pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: der})
+}
+
+// decodeJSONPart base64url-decodes a JWT part and parses it as a JSON object.
+func decodeJSONPart(t *testing.T, b64url string) map[string]any {
+	t.Helper()
+	raw, err := base64.RawURLEncoding.DecodeString(b64url)
+	require.NoError(t, err, "base64url decode of JWT part failed")
+	var m map[string]any
+	require.NoError(t, json.Unmarshal(raw, &m), "JSON unmarshal of JWT part failed")
+	return m
+}
+
+// sha256SumBytes returns the SHA-256 digest of b as a byte slice.
+func sha256SumBytes(b []byte) []byte {
+	h := sha256.Sum256(b)
+	return h[:]
+}
+
+// assertValidRSAJWT signs a JWT with signer and verifies the RS256 signature
+// against the given RSA public key. Used by PEM variant tests.
+func assertValidRSAJWT(t *testing.T, key *rsa.PrivateKey, signer *ClientAssertionSigner, alg string) {
+	t.Helper()
+	jwtStr, err := signer.Sign("https://example.com/token", "pem-client")
+	require.NoError(t, err)
+
+	parts := strings.Split(jwtStr, ".")
+	require.Len(t, parts, 3)
+
+	hdr := decodeJSONPart(t, parts[0])
+	assert.Equal(t, alg, hdr["alg"])
+
+	sigBytes, err := base64.RawURLEncoding.DecodeString(parts[2])
+	require.NoError(t, err)
+
+	sigInput := parts[0] + "." + parts[1]
+	digest := sha256SumBytes([]byte(sigInput))
+	assert.NoError(t, rsa.VerifyPKCS1v15(&key.PublicKey, crypto.SHA256, digest, sigBytes))
+}
+

issue149_regression_test.go

@@ -0,0 +1,303 @@
+package traefikoidc
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+	"text/template"
+)
+
+// Issue #149: after NewWithContext started calling config.Validate() (commit
+// 546ceb9), `headers` configs that had worked in 0.8.25 began failing, so New()
+// returned a nil handler and Traefik logged the opaque router error
+// "invalid handler type: <nil>". Two independent header-validation checks were
+// too strict:
+//
+//  1. validateTemplateSecure rejected the documented multi-valued-claim join
+//     pattern "{{range .. := .Claims.groups}}..." as a dangerous {{range}}.
+//  2. Config.Validate required every header value to contain {{ }}, rejecting
+//     static/literal values (e.g. a shared proxy secret).
+//
+// These tests pin the fix while proving the security boundary still holds.
+
+// issue149BaseConfig returns a complete, valid config with no headers. Header
+// cases are layered on per-test. No network is performed by Config.Validate.
+func issue149BaseConfig() *Config {
+	return &Config{
+		ProviderURL:          "https://provider.example.com",
+		ClientID:             "frigate-client",
+		ClientSecret:         "frigate-client-secret",
+		CallbackURL:          "/oauth2/callback",
+		SessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789",
+		RateLimit:            100,
+		Scopes:               []string{"openid", "profile", "email", "groups"},
+	}
+}
+
+// TestIssue149_HeadersConfigValidates is the exact reproduction: the issue's
+// three headers (after Traefik file-provider un-escaping) must now validate.
+func TestIssue149_HeadersConfigValidates(t *testing.T) {
+	cfg := issue149BaseConfig()
+	cfg.Headers = []TemplatedHeader{
+		{Name: "X-Forwarded-Preferred-Username", Value: `{{.Claims.preferred_username}}`},
+		{Name: "X-Forwarded-Groups", Value: `{{range $i, $e := .Claims.groups}}{{if $i}},{{end}}{{$e}}{{end}}`},
+		{Name: "X-Proxy-Secret", Value: `super-secret-shared-value`},
+	}
+	if err := cfg.Validate(); err != nil {
+		t.Fatalf("issue #149 headers config must validate after the fix, got: %v", err)
+	}
+}
+
+// TestIssue149_TemplateSecurityBoundary asserts the relaxed validator accepts
+// the documented range/if join over claims while still blocking genuinely
+// dangerous templates and access to non-whitelisted claims.
+func TestIssue149_TemplateSecurityBoundary(t *testing.T) {
+	cases := []struct {
+		name       string
+		template   string
+		shouldFail bool
+	}{
+		// --- allowed: documented, safe patterns ---
+		{"direct claim", `{{.Claims.preferred_username}}`, false},
+		{"documented groups join", `{{range $i, $e := .Claims.groups}}{{if $i}},{{end}}{{$e}}{{end}}`, false},
+		{"documented roles join", `{{range $i, $e := .Claims.roles}}{{if $i}},{{end}}{{$e}}{{end}}`, false},
+		{"simple range over claims", `{{range .Claims.groups}}{{.}} {{end}}`, false},
+		{"default over claim", `{{default "none" .Claims.email}}`, false},
+		{"access token", `{{.AccessToken}}`, false},
+		{"with over claim field", `{{with .Claims.email}}{{.}}{{end}}`, false},
+		{"id token IdToken spelling", `{{.IdToken}}`, false}, // documented spelling (C6)
+		{"id token IDToken spelling", `{{.IDToken}}`, false}, // actual data key (C6)
+
+		// --- still blocked: with over the bare Claims map leaks arbitrary fields ---
+		{"with over bare claims map", `{{with .Claims}}{{.password}}{{end}}`, true},
+
+		// --- still blocked: dangerous control/functions ---
+		{"range over non-claims data", `{{range .Items}}{{.}}{{end}}`, true},
+		{"call function", `{{call .Func}}`, true},
+		{"define template", `{{define "x"}}{{.}}{{end}}`, true},
+		{"template inclusion", `{{template "other"}}`, true},
+		{"printf", `{{printf "%s" .}}`, true},
+
+		// --- still blocked: non-whitelisted claim access, incl. via range ---
+		{"non-whitelisted claim direct", `{{.Claims.password}}`, true},
+		{"non-whitelisted claim via range", `{{range $i, $e := .Claims.ssn}}{{$e}}{{end}}`, true},
+		{"no recognized variable", `{{.Unknown}}`, true},
+
+		// --- still blocked: whole-Claims-map dump via range (issue #149 review, C1).
+		// A decoy {{.Claims.sub}} must NOT launder a bare-map range past the gate.
+		{"whole claims map dump via range", `{{range .Claims}}{{.}} {{end}}{{.Claims.sub}}`, true},
+		{"claims keys dump via range assign", `{{range $k, $v := .Claims}}{{$k}} {{end}}{{.Claims.sub}}`, true},
+		// --- still blocked: newline-obfuscated actions — the AST parser resolves
+		// whitespace, so these are just {{range}}/{{index}} and are rejected.
+		{"newline-obfuscated range over map", "{{\nrange .Claims}}{{.}}{{end}}{{.Claims.sub}}", true},
+		{"newline-obfuscated index exfil", "{{\nindex .Claims \"password\"}}{{.Claims.sub}}", true},
+
+		// --- still blocked: whole-root / whole-Claims-map render (AST review). A
+		// whitelisted decoy {{.Claims.email}} must NOT launder a bare-map/root dump.
+		{"whole claims map render", `{{.Claims}}`, true},
+		{"whole root render dot", `{{.}}`, true},
+		{"whole root render dollar", `{{$}}`, true},
+		{"root claims via dollar", `{{$.Claims}}`, true},
+		{"decoy plus root dump", `{{.Claims.email}}{{.}}`, true},
+		{"decoy plus map dump", `{{.Claims.email}}{{.Claims}}`, true},
+		{"var-laundered map dump", `{{$x := .Claims}}{{$x}}{{.Claims.sub}}`, true},
+		{"index builtin blocked", `{{index .Claims "password"}}`, true},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateTemplateSecure(tc.template, nil)
+			if tc.shouldFail && err == nil {
+				t.Fatalf("expected %q to be rejected, but it passed", tc.template)
+			}
+			if !tc.shouldFail && err != nil {
+				t.Fatalf("expected %q to be allowed, but it was rejected: %v", tc.template, err)
+			}
+		})
+	}
+}
+
+// TestIssue149_GroupsTemplateRendersForwardableValue proves the end goal: the
+// documented groups join template parses, executes to a comma-separated string,
+// and passes the runtime header sanitizer — so the header is actually emitted,
+// not merely accepted by validation. Parse options mirror main.go:414.
+func TestIssue149_GroupsTemplateRendersForwardableValue(t *testing.T) {
+	const tmplStr = `{{range $i, $e := .Claims.groups}}{{if $i}},{{end}}{{$e}}{{end}}`
+
+	tmpl, err := template.New("X-Forwarded-Groups").Option("missingkey=zero").Parse(tmplStr)
+	if err != nil {
+		t.Fatalf("documented groups template must parse: %v", err)
+	}
+
+	data := map[string]any{
+		"Claims": map[string]any{
+			"groups": []any{"admin", "users", "viewers"},
+		},
+	}
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, data); err != nil {
+		t.Fatalf("groups template must execute: %v", err)
+	}
+	if got := buf.String(); got != "admin,users,viewers" {
+		t.Fatalf("groups render mismatch: got %q want %q", got, "admin,users,viewers")
+	}
+
+	// The comma-joined value must survive the runtime injection guard; commas
+	// are not control/bidi runes, so it forwards intact.
+	if reason := headerValueReason(buf.String(), headerTemplateMaxLen); reason != "" {
+		t.Fatalf("rendered groups header was dropped by sanitizer: %s", reason)
+	}
+}
+
+// TestIssue149_GetEnforcesClaimsWhitelist proves the runtime `get` helper cannot
+// exfiltrate a non-whitelisted claim, a raw token, or the whole data map — even
+// though validateTemplateSecure accepts {{get ...}} syntactically. This is the
+// defense-in-depth layer for C2/C3/C4 from the issue #149 security review.
+func TestIssue149_GetEnforcesClaimsWhitelist(t *testing.T) {
+	data := map[string]any{
+		"AccessToken":  "AT-SECRET",
+		"IDToken":      "IDT",
+		"IdToken":      "IDT",
+		"RefreshToken": "RT-SECRET",
+		"Claims": map[string]any{
+			"email":    "[email protected]",
+			"password": "PW-SECRET",
+			"ssn":      "123-45-6789",
+		},
+	}
+	fns := headerTemplateFuncMap(nil)
+	render := func(tmplStr string) string {
+		tmpl := template.Must(template.New("h").Funcs(fns).Option("missingkey=zero").Parse(tmplStr))
+		var b bytes.Buffer
+		if err := tmpl.Execute(&b, data); err != nil {
+			t.Fatalf("execute %q: %v", tmplStr, err)
+		}
+		return b.String()
+	}
+
+	// Every exfil attempt must render empty (or the default fallback), never a secret.
+	leaky := map[string]string{
+		"get non-whitelisted claim": `{{get .Claims "password"}}`,
+		"get ssn":                   `{{get .Claims "ssn"}}`,
+		"get raw token off root":    `{{get . "AccessToken"}}`,
+		"get whole claims map":      `{{get . "Claims"}}`,
+		"default wrapping get(ssn)": `{{default "none" (get .Claims "ssn")}}`,
+	}
+	for name, tmplStr := range leaky {
+		t.Run(name, func(t *testing.T) {
+			got := render(tmplStr)
+			for _, secret := range []string{"PW-SECRET", "AT-SECRET", "RT-SECRET", "123-45-6789"} {
+				if strings.Contains(got, secret) {
+					t.Fatalf("%q leaked %q (rendered %q)", tmplStr, secret, got)
+				}
+			}
+		})
+	}
+
+	// A whitelisted claim via get must still resolve.
+	if got := render(`{{get .Claims "email"}}`); got != "[email protected]" {
+		t.Fatalf(`get of whitelisted "email" must work, got %q`, got)
+	}
+}
+
+// TestIssue149_IdTokenBothSpellingsRender pins C6: both {{.IdToken}} (documented)
+// and {{.IDToken}} (runtime data key) resolve to the ID token, and both validate.
+func TestIssue149_IdTokenBothSpellingsRender(t *testing.T) {
+	data := map[string]any{"IDToken": "IDT-REAL", "IdToken": "IDT-REAL"}
+	for _, tmplStr := range []string{`{{.IdToken}}`, `{{.IDToken}}`} {
+		if err := validateTemplateSecure(tmplStr, nil); err != nil {
+			t.Fatalf("%q must validate: %v", tmplStr, err)
+		}
+		tmpl := template.Must(template.New("h").Option("missingkey=zero").Parse(tmplStr))
+		var b bytes.Buffer
+		if err := tmpl.Execute(&b, data); err != nil {
+			t.Fatalf("execute %q: %v", tmplStr, err)
+		}
+		if b.String() != "IDT-REAL" {
+			t.Fatalf("%q rendered %q, want IDT-REAL", tmplStr, b.String())
+		}
+	}
+}
+
+// TestIssue149_AllowedClaimsExtendsWhitelist pins the allowedClaims config
+// option: a custom claim is rejected by default but validates and renders once
+// listed, via both direct access and get.
+func TestIssue149_AllowedClaimsExtendsWhitelist(t *testing.T) {
+	const custom = "employee_id"
+
+	// Default (no allowedClaims): the custom claim is not forwardable.
+	base := issue149BaseConfig()
+	base.Headers = []TemplatedHeader{{Name: "X-Emp", Value: `{{.Claims.employee_id}}`}}
+	if err := base.Validate(); err == nil {
+		t.Fatalf("custom claim %q must be rejected without allowedClaims", custom)
+	}
+
+	// With allowedClaims: direct access and get both validate.
+	cfg := issue149BaseConfig()
+	cfg.AllowedClaims = []string{custom}
+	cfg.Headers = []TemplatedHeader{
+		{Name: "X-Emp", Value: `{{.Claims.employee_id}}`},
+		{Name: "X-Emp-Get", Value: `{{get .Claims "employee_id"}}`},
+	}
+	if err := cfg.Validate(); err != nil {
+		t.Fatalf("allowedClaims must permit %q, got: %v", custom, err)
+	}
+
+	// The whitelist (validation) and the runtime get share the same effective set.
+	whitelist := claimsWhitelist(cfg.AllowedClaims)
+	if err := validateTemplateSecure(`{{get .Claims "employee_id"}}`, whitelist); err != nil {
+		t.Fatalf("get on allowed custom claim must validate: %v", err)
+	}
+	fns := headerTemplateFuncMap(whitelist)
+	tmpl := template.Must(template.New("h").Funcs(fns).Option("missingkey=zero").Parse(`{{get .Claims "employee_id"}}`))
+	var b bytes.Buffer
+	if err := tmpl.Execute(&b, map[string]any{"Claims": map[string]any{"employee_id": "E-42"}}); err != nil {
+		t.Fatalf("render: %v", err)
+	}
+	if b.String() != "E-42" {
+		t.Fatalf("runtime get of allowed claim rendered %q, want E-42", b.String())
+	}
+
+	// A still-unlisted claim stays rejected even when another is allowed.
+	if err := validateTemplateSecure(`{{.Claims.ssn}}`, whitelist); err == nil {
+		t.Fatal("non-allowed claim ssn must still be rejected")
+	}
+}
+
+// TestIssue149_StaticAndDelimiterHandling covers the Config.Validate header loop
+// for literal values and malformed delimiters (validateTemplateSecure is not
+// invoked for pure literals).
+func TestIssue149_StaticAndDelimiterHandling(t *testing.T) {
+	cases := []struct {
+		name        string
+		value       string
+		shouldFail  bool
+		errContains string
+	}{
+		{"static literal secret", `super-secret-shared-value`, false, ""},
+		{"static with equals/base64", `AAAA1234==`, false, ""},
+		{"static with CRLF is rejected", "line1\r\nline2", true, "invalid characters"},
+		{"unbalanced open only", `{{.Claims.email`, true, "unbalanced template delimiters"},
+		{"unbalanced close only", `.Claims.email}}`, true, "unbalanced template delimiters"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := issue149BaseConfig()
+			cfg.Headers = []TemplatedHeader{{Name: "X-Test", Value: tc.value}}
+			err := cfg.Validate()
+			if tc.shouldFail {
+				if err == nil {
+					t.Fatalf("expected value %q to be rejected, but it passed", tc.value)
+				}
+				if tc.errContains != "" && !strings.Contains(err.Error(), tc.errContains) {
+					t.Fatalf("expected error to contain %q, got: %v", tc.errContains, err)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("expected value %q to be allowed, but it was rejected: %v", tc.value, err)
+			}
+		})
+	}
+}

issue151_regression_test.go

@@ -0,0 +1,114 @@
+package traefikoidc
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"os"
+	"testing"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Issue #151: the Traefik Plugin Catalog analyzer (piceus) failed v1.0.28 with
+// "failed to run the plugin with Yaegi: invalid handler type: <nil>". Two
+// independent defects combined to produce that opaque report:
+//
+//  1. The analyzer feeds .traefik.yml testData to New() RAW — paerser and
+//     mapstructure perform no brace collapsing, so the quadruple-brace header
+//     values ("{{{{.Claims.email}}}}") reached Config.Validate() verbatim and
+//     failed template parsing (`unexpected "{" in command`). The quadruple-brace
+//     convention (commit 2d1b04c) was based on a false premise; YAML does not
+//     collapse braces.
+//
+//  2. New() tail-called `return NewWithContext(...)`, converting the returned
+//     (*TraefikOidc, error) to (http.Handler, error) in the return statement.
+//     Under yaegi v0.16.1 (the interpreter piceus and Traefik embed) that
+//     conversion zeroes BOTH results when the error path is taken, so piceus
+//     saw (nil, nil), skipped its error branch, and reported the handler-type
+//     message instead of the real validation error. Compiled Go had the sibling
+//     defect: the typed-nil *TraefikOidc made New() return a NON-nil
+//     http.Handler alongside a non-nil error.
+//
+// These tests pin both fixes natively (no interpreter needed):
+// TestIssue151_ManifestTestDataPassesAnalyzer pins (1) and
+// TestIssue151_NewReturnsUntypedNilHandlerOnInvalidConfig pins (2).
+
+// manifestTestData reads .traefik.yml and returns testData exactly as the
+// analyzer sees it: parsed by a YAML parser, no template preprocessing.
+func manifestTestData(t *testing.T) map[string]any {
+	t.Helper()
+
+	raw, err := os.ReadFile(".traefik.yml")
+	if err != nil {
+		t.Fatalf("read .traefik.yml: %v", err)
+	}
+
+	var manifest struct {
+		TestData map[string]any `yaml:"testData"`
+	}
+	if err := yaml.Unmarshal(raw, &manifest); err != nil {
+		t.Fatalf("parse .traefik.yml: %v", err)
+	}
+	if len(manifest.TestData) == 0 {
+		t.Fatal(".traefik.yml has no testData — the analyzer rejects manifests without it")
+	}
+	return manifest.TestData
+}
+
+// TestIssue151_ManifestTestDataPassesAnalyzer decodes the manifest's testData
+// into a Config the same way piceus does (defaults from CreateConfig, then the
+// raw testData values on top; JSON round-trip stands in for mapstructure) and
+// requires the full analyzer contract: Validate() passes and New() yields a
+// working handler with no error.
+func TestIssue151_ManifestTestDataPassesAnalyzer(t *testing.T) {
+	testData := manifestTestData(t)
+
+	cfg := CreateConfig()
+	buf, err := json.Marshal(testData)
+	if err != nil {
+		t.Fatalf("marshal testData: %v", err)
+	}
+	if err := json.Unmarshal(buf, cfg); err != nil {
+		t.Fatalf("decode testData into Config: %v", err)
+	}
+
+	if err := cfg.Validate(); err != nil {
+		t.Fatalf("manifest testData must pass Validate() — the catalog analyzer feeds it to New() raw (issue #151): %v", err)
+	}
+
+	next := http.HandlerFunc(func(http.ResponseWriter, *http.Request) {})
+	h, err := New(context.Background(), next, cfg, "issue151-analyzer")
+	if err != nil {
+		t.Fatalf("New() with manifest testData must succeed (issue #151): %v", err)
+	}
+	if h == nil {
+		t.Fatal("New() with manifest testData returned a nil handler")
+	}
+	if closer, ok := h.(interface{ Close() error }); ok {
+		_ = closer.Close()
+	}
+}
+
+// TestIssue151_NewReturnsUntypedNilHandlerOnInvalidConfig requires New() to
+// return an UNTYPED nil handler when construction fails. The previous
+// `return NewWithContext(...)` tail call wrapped a typed-nil *TraefikOidc into
+// the http.Handler interface (h != nil despite err != nil), and under yaegi the
+// same statement zeroed the error as well, which is what turned every
+// validation failure into Traefik's opaque "invalid handler type: <nil>".
+func TestIssue151_NewReturnsUntypedNilHandlerOnInvalidConfig(t *testing.T) {
+	cfg := issue149BaseConfig()
+	cfg.Headers = []TemplatedHeader{
+		// Invalid template — the analyzer-side shape that triggered #151.
+		{Name: "X-User-Email", Value: `{{{{.Claims.email}}}}`},
+	}
+
+	next := http.HandlerFunc(func(http.ResponseWriter, *http.Request) {})
+	h, err := New(context.Background(), next, cfg, "issue151-nil")
+	if err == nil {
+		t.Fatal("New() must reject an invalid header template")
+	}
+	if h != nil {
+		t.Fatalf("New() must return an untyped nil handler on error, got %T (typed nil leaks through the http.Handler interface and breaks the analyzer's error reporting)", h)
+	}
+}

issue152_regression_test.go

@@ -0,0 +1,568 @@
+package traefikoidc
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+// issue152_regression_test.go — regression tests for issue #152.
+//
+// Three provider endpoints — token revocation, OIDC end-session (logout), and
+// RFC 7662 token introspection — were documented Config fields
+// (RevocationURL, OIDCEndSessionURL) or a brand-new one (IntrospectionURL)
+// that operators can set when their IdP omits an endpoint from discovery, or
+// to pin a non-standard one. RevocationURL and OIDCEndSessionURL were dead:
+// Config.Validate() checked them but nothing ever copied them onto the live
+// TraefikOidc fields consumers read, so setting them silently did nothing.
+// IntrospectionURL did not exist at all.
+//
+// The fix adds three unexported write-once fields on TraefikOidc
+// (configRevocationURL, configEndSessionURL, configIntrospectionURL),
+// populated from Config at construction (main.go NewWithContext). The same
+// three values also cold-start-seed the live fields (revocationURL,
+// endSessionURL, introspectionURL) so a discovery failure does not lose an
+// operator override. Inside updateMetadataEndpoints, after the SSRF sanitize
+// pass, the introspection same-host pin, and the issuer pin — but before the
+// metadataMu.Lock() that publishes the live fields — each non-empty config*
+// field overwrites the corresponding metadata.* value, so a manual override
+// wins over discovery on every refresh, not just at construction. An empty
+// override leaves the discovered value alone. Manual overrides deliberately
+// skip validateDiscoveredEndpoint and the introspection same-host pin: they
+// sit at the same trust tier as providerURL itself, already gated by
+// isValidSecureURL at config-validation time.
+//
+// These tests pin: default (no overrides) behavior is unchanged, overrides
+// win over both absent and present discovered values, a cross-host
+// introspection override survives the same-host pin that a discovered
+// cross-host endpoint does not, overrides survive repeated metadata
+// refreshes, NewWithContext wires the three config* fields and cold-start
+// seeds correctly (including when discovery fails outright), the override
+// is honored end-to-end by introspectToken and RevokeTokenWithProvider, the
+// logout URL builder emits the override, and Config.Validate / New enforce
+// the same "invalid configuration" + untyped-nil-handler contract (#151)
+// for a bad IntrospectionURL that the sibling fields already had.
+
+// issue152BaseConfig returns a complete, valid Config, following the
+// minimal-valid-config pattern used elsewhere in this package (e.g.
+// issue154BaseConfig in issue154_regression_test.go).
+func issue152BaseConfig() *Config {
+	return &Config{
+		ProviderURL:          "https://provider.example.com",
+		ClientID:             "test-client",
+		ClientSecret:         "test-secret",
+		CallbackURL:          "/callback",
+		SessionEncryptionKey: "this-is-a-valid-session-key-32b!",
+		RateLimit:            100,
+	}
+}
+
+// issue152Endpoints reads the three metadataMu-guarded live endpoint fields
+// under lock, so callers stay race-clean regardless of whether a background
+// discovery goroutine may still touch them.
+func issue152Endpoints(oidc *TraefikOidc) (revocation, endSession, introspection string) {
+	oidc.metadataMu.RLock()
+	defer oidc.metadataMu.RUnlock()
+	return oidc.revocationURL, oidc.endSessionURL, oidc.introspectionURL
+}
+
+// TestIssue152DefaultPreservation proves the fix is additive: with no
+// operator overrides, updateMetadataEndpoints behaves exactly as before —
+// discovered values become the live fields and the published snapshot.
+func TestIssue152DefaultPreservation(t *testing.T) {
+	t.Run("discovered values populate live fields and snapshot", func(t *testing.T) {
+		oidc := &TraefikOidc{
+			providerURL: "https://provider.example.com",
+			logger:      NewLogger("error"),
+			clientID:    "test-client",
+		}
+		metadata := &ProviderMetadata{
+			Issuer:           "https://provider.example.com",
+			AuthURL:          "https://provider.example.com/authorize",
+			TokenURL:         "https://provider.example.com/token",
+			JWKSURL:          "https://provider.example.com/jwks",
+			RevokeURL:        "https://provider.example.com/revoke",
+			EndSessionURL:    "https://provider.example.com/endsession",
+			IntrospectionURL: "https://provider.example.com/introspect",
+			RegistrationURL:  "https://provider.example.com/register",
+		}
+
+		oidc.updateMetadataEndpoints(metadata)
+
+		revocation, endSession, introspection := issue152Endpoints(oidc)
+		if revocation != metadata.RevokeURL {
+			t.Fatalf("revocationURL = %q, want discovered %q", revocation, metadata.RevokeURL)
+		}
+		if endSession != metadata.EndSessionURL {
+			t.Fatalf("endSessionURL = %q, want discovered %q", endSession, metadata.EndSessionURL)
+		}
+		if introspection != metadata.IntrospectionURL {
+			t.Fatalf("introspectionURL = %q, want discovered %q", introspection, metadata.IntrospectionURL)
+		}
+
+		snap := oidc.metadataSnap()
+		if snap == nil {
+			t.Fatal("metadataSnap() returned nil after updateMetadataEndpoints")
+		}
+		if snap.RevocationURL != metadata.RevokeURL || snap.EndSessionURL != metadata.EndSessionURL || snap.IntrospectionURL != metadata.IntrospectionURL {
+			t.Fatalf("metadataSnapshot = %+v, want it to match discovered metadata %+v", snap, metadata)
+		}
+	})
+
+	t.Run("discovery omits introspection and no override leaves it empty", func(t *testing.T) {
+		oidc := &TraefikOidc{
+			providerURL: "https://provider.example.com",
+			logger:      NewLogger("error"),
+			clientID:    "test-client",
+		}
+		metadata := &ProviderMetadata{
+			Issuer:   "https://provider.example.com",
+			AuthURL:  "https://provider.example.com/authorize",
+			TokenURL: "https://provider.example.com/token",
+			JWKSURL:  "https://provider.example.com/jwks",
+			// IntrospectionURL intentionally omitted.
+		}
+
+		oidc.updateMetadataEndpoints(metadata)
+
+		_, _, introspection := issue152Endpoints(oidc)
+		if introspection != "" {
+			t.Fatalf("introspectionURL = %q, want empty when discovery omits it and no override is set", introspection)
+		}
+	})
+}
+
+// TestIssue152OverridesWin proves a non-empty config* override always wins
+// over discovery, whether discovery is silent on the endpoint (a) or
+// actively supplies a different value (b), and that a cross-host
+// introspection override survives the same-host pin that a discovered
+// cross-host introspection endpoint does not (c).
+func TestIssue152OverridesWin(t *testing.T) {
+	overrideRevocation := "https://override.example.com/revoke"
+	overrideEndSession := "https://override.example.com/endsession"
+	overrideIntrospection := "https://override.example.com/introspect"
+
+	newOverriddenOidc := func() *TraefikOidc {
+		return &TraefikOidc{
+			providerURL:            "https://provider.example.com",
+			logger:                 NewLogger("error"),
+			clientID:               "test-client",
+			configRevocationURL:    overrideRevocation,
+			configEndSessionURL:    overrideEndSession,
+			configIntrospectionURL: overrideIntrospection,
+		}
+	}
+
+	t.Run("discovery omits endpoints, overrides fill them in", func(t *testing.T) {
+		oidc := newOverriddenOidc()
+		metadata := &ProviderMetadata{
+			Issuer:   "https://provider.example.com",
+			AuthURL:  "https://provider.example.com/authorize",
+			TokenURL: "https://provider.example.com/token",
+			JWKSURL:  "https://provider.example.com/jwks",
+		}
+
+		oidc.updateMetadataEndpoints(metadata)
+
+		revocation, endSession, introspection := issue152Endpoints(oidc)
+		if revocation != overrideRevocation || endSession != overrideEndSession || introspection != overrideIntrospection {
+			t.Fatalf("got (%q, %q, %q), want overrides (%q, %q, %q)",
+				revocation, endSession, introspection, overrideRevocation, overrideEndSession, overrideIntrospection)
+		}
+		snap := oidc.metadataSnap()
+		if snap == nil || snap.RevocationURL != overrideRevocation || snap.EndSessionURL != overrideEndSession || snap.IntrospectionURL != overrideIntrospection {
+			t.Fatalf("metadataSnapshot = %+v, want overrides", snap)
+		}
+	})
+
+	t.Run("discovery supplies different values, overrides win anyway", func(t *testing.T) {
+		oidc := newOverriddenOidc()
+		metadata := &ProviderMetadata{
+			Issuer:           "https://provider.example.com",
+			AuthURL:          "https://provider.example.com/authorize",
+			TokenURL:         "https://provider.example.com/token",
+			JWKSURL:          "https://provider.example.com/jwks",
+			RevokeURL:        "https://provider.example.com/discovered-revoke",
+			EndSessionURL:    "https://provider.example.com/discovered-endsession",
+			IntrospectionURL: "https://provider.example.com/discovered-introspect",
+		}
+
+		oidc.updateMetadataEndpoints(metadata)
+
+		revocation, endSession, introspection := issue152Endpoints(oidc)
+		if revocation != overrideRevocation || endSession != overrideEndSession || introspection != overrideIntrospection {
+			t.Fatalf("got (%q, %q, %q), want overrides (%q, %q, %q) to beat discovered values",
+				revocation, endSession, introspection, overrideRevocation, overrideEndSession, overrideIntrospection)
+		}
+	})
+
+	t.Run("cross-host introspection: discovered is zeroed, override survives", func(t *testing.T) {
+		// No override: a discovered introspection endpoint on a different host
+		// than providerURL must be zeroed by the same-host pin.
+		oidc := &TraefikOidc{
+			providerURL: "https://provider.example.com",
+			logger:      NewLogger("error"),
+			clientID:    "test-client",
+		}
+		metadata := &ProviderMetadata{
+			Issuer:           "https://provider.example.com",
+			AuthURL:          "https://provider.example.com/authorize",
+			TokenURL:         "https://provider.example.com/token",
+			JWKSURL:          "https://provider.example.com/jwks",
+			IntrospectionURL: "https://attacker.example.com/introspect",
+		}
+		oidc.updateMetadataEndpoints(metadata)
+		if _, _, introspection := issue152Endpoints(oidc); introspection != "" {
+			t.Fatalf("introspectionURL = %q, want empty: discovered cross-host introspection must be zeroed by the same-host pin", introspection)
+		}
+
+		// Same cross-host discovered value, but now with a cross-host override:
+		// the override must survive because it skips the same-host pin.
+		oidcWithOverride := &TraefikOidc{
+			providerURL:            "https://provider.example.com",
+			logger:                 NewLogger("error"),
+			clientID:               "test-client",
+			configIntrospectionURL: overrideIntrospection,
+		}
+		oidcWithOverride.updateMetadataEndpoints(metadata)
+		if _, _, introspection := issue152Endpoints(oidcWithOverride); introspection != overrideIntrospection {
+			t.Fatalf("introspectionURL = %q, want override %q to survive despite being cross-host", introspection, overrideIntrospection)
+		}
+	})
+}
+
+// TestIssue152RefreshSurvival proves overrides are re-applied inside
+// updateMetadataEndpoints itself, so they survive every metadata refresh —
+// not just the first call after construction.
+func TestIssue152RefreshSurvival(t *testing.T) {
+	overrideRevocation := "https://override.example.com/revoke"
+	overrideEndSession := "https://override.example.com/endsession"
+	overrideIntrospection := "https://override.example.com/introspect"
+
+	oidc := &TraefikOidc{
+		providerURL:            "https://provider.example.com",
+		logger:                 NewLogger("error"),
+		clientID:               "test-client",
+		configRevocationURL:    overrideRevocation,
+		configEndSessionURL:    overrideEndSession,
+		configIntrospectionURL: overrideIntrospection,
+	}
+
+	firstRefresh := &ProviderMetadata{
+		Issuer:           "https://provider.example.com",
+		AuthURL:          "https://provider.example.com/authorize",
+		TokenURL:         "https://provider.example.com/token",
+		JWKSURL:          "https://provider.example.com/jwks",
+		RevokeURL:        "https://provider.example.com/refresh1-revoke",
+		EndSessionURL:    "https://provider.example.com/refresh1-endsession",
+		IntrospectionURL: "https://provider.example.com/refresh1-introspect",
+	}
+	oidc.updateMetadataEndpoints(firstRefresh)
+	if revocation, endSession, introspection := issue152Endpoints(oidc); revocation != overrideRevocation || endSession != overrideEndSession || introspection != overrideIntrospection {
+		t.Fatalf("after 1st refresh: got (%q, %q, %q), want overrides to hold", revocation, endSession, introspection)
+	}
+
+	secondRefresh := &ProviderMetadata{
+		Issuer:           "https://provider.example.com",
+		AuthURL:          "https://provider.example.com/authorize",
+		TokenURL:         "https://provider.example.com/token",
+		JWKSURL:          "https://provider.example.com/jwks",
+		RevokeURL:        "https://provider.example.com/refresh2-revoke",
+		EndSessionURL:    "https://provider.example.com/refresh2-endsession",
+		IntrospectionURL: "https://provider.example.com/refresh2-introspect",
+	}
+	oidc.updateMetadataEndpoints(secondRefresh)
+	if revocation, endSession, introspection := issue152Endpoints(oidc); revocation != overrideRevocation || endSession != overrideEndSession || introspection != overrideIntrospection {
+		t.Fatalf("after 2nd refresh: got (%q, %q, %q), want overrides to still hold", revocation, endSession, introspection)
+	}
+}
+
+// TestIssue152NewWithContextWiring proves NewWithContext wires
+// Config.RevocationURL / OIDCEndSessionURL / IntrospectionURL onto the three
+// unexported config* fields and cold-start-seeds the live fields from them
+// (main.go, the configRevocationURL/configEndSessionURL/configIntrospectionURL
+// and revocationURL/endSessionURL/introspectionURL initializers), both when
+// discovery succeeds with different values (override must still win) and
+// when discovery fails outright (the cold-start seed must not be lost).
+func TestIssue152NewWithContextWiring(t *testing.T) {
+	overrideRevocation := "https://override.example.com/revoke"
+	overrideEndSession := "https://override.example.com/endsession"
+	overrideIntrospection := "https://override.example.com/introspect"
+
+	t.Run("discovery succeeds with different values, overrides still win", func(t *testing.T) {
+		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:           srv.URL,
+					AuthURL:          srv.URL + "/auth",
+					TokenURL:         srv.URL + "/token",
+					JWKSURL:          srv.URL + "/jwks",
+					RevokeURL:        srv.URL + "/discovered-revoke",
+					EndSessionURL:    srv.URL + "/discovered-endsession",
+					IntrospectionURL: srv.URL + "/discovered-introspect",
+				})
+				return
+			}
+			w.WriteHeader(http.StatusNotFound)
+		}))
+		defer srv.Close()
+
+		cfg := issue152BaseConfig()
+		cfg.ProviderURL = srv.URL
+		cfg.RevocationURL = overrideRevocation
+		cfg.OIDCEndSessionURL = overrideEndSession
+		cfg.IntrospectionURL = overrideIntrospection
+
+		oidc, err := NewWithContext(context.Background(), cfg, nil, "issue152-wiring-success")
+		if err != nil {
+			t.Fatalf("NewWithContext must accept a valid config with overrides, got: %v", err)
+		}
+		defer func() { _ = oidc.Close() }()
+
+		<-oidc.initComplete // wait for the discovery goroutine so field reads below are race-safe.
+
+		revocation, endSession, introspection := issue152Endpoints(oidc)
+		if revocation != overrideRevocation || endSession != overrideEndSession || introspection != overrideIntrospection {
+			t.Fatalf("got (%q, %q, %q), want overrides (%q, %q, %q) to win over successful discovery",
+				revocation, endSession, introspection, overrideRevocation, overrideEndSession, overrideIntrospection)
+		}
+	})
+
+	t.Run("discovery fails outright, cold-start seed holds", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusInternalServerError)
+		}))
+		defer srv.Close()
+
+		cfg := issue152BaseConfig()
+		cfg.ProviderURL = srv.URL
+		cfg.RevocationURL = overrideRevocation
+		cfg.OIDCEndSessionURL = overrideEndSession
+		cfg.IntrospectionURL = overrideIntrospection
+
+		oidc, err := NewWithContext(context.Background(), cfg, nil, "issue152-wiring-coldstart")
+		if err != nil {
+			t.Fatalf("NewWithContext must accept a valid config even though discovery will fail, got: %v", err)
+		}
+		defer func() { _ = oidc.Close() }()
+
+		<-oidc.initComplete // discovery has failed and returned by now.
+
+		revocation, endSession, introspection := issue152Endpoints(oidc)
+		if revocation != overrideRevocation || endSession != overrideEndSession || introspection != overrideIntrospection {
+			t.Fatalf("got (%q, %q, %q), want the constructor's cold-start seed (%q, %q, %q) to survive a failed discovery",
+				revocation, endSession, introspection, overrideRevocation, overrideEndSession, overrideIntrospection)
+		}
+	})
+}
+
+// TestIssue152EndToEndIntrospection proves the override is honored one layer
+// up from the field: with a discovery document that omits
+// introspection_endpoint entirely, introspectToken (token_introspection.go)
+// must still reach the manually-configured endpoint and return its result.
+func TestIssue152EndToEndIntrospection(t *testing.T) {
+	var hits int32
+	var gotToken string
+	introspectionSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&hits, 1)
+		if err := r.ParseForm(); err == nil {
+			gotToken = r.PostFormValue("token")
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"active": true})
+	}))
+	defer introspectionSrv.Close()
+
+	oidc := &TraefikOidc{
+		providerURL:            "https://provider.example.com",
+		logger:                 NewLogger("error"),
+		clientID:               "test-client",
+		clientSecret:           "test-secret",
+		httpClient:             http.DefaultClient,
+		configIntrospectionURL: introspectionSrv.URL,
+	}
+	metadata := &ProviderMetadata{
+		Issuer:   "https://provider.example.com",
+		AuthURL:  "https://provider.example.com/authorize",
+		TokenURL: "https://provider.example.com/token",
+		JWKSURL:  "https://provider.example.com/jwks",
+		// IntrospectionURL intentionally omitted: the override is the only
+		// source of the endpoint.
+	}
+	oidc.updateMetadataEndpoints(metadata)
+
+	if _, _, introspection := issue152Endpoints(oidc); introspection != introspectionSrv.URL {
+		t.Fatalf("introspectionURL = %q, want override %q wired before calling introspectToken", introspection, introspectionSrv.URL)
+	}
+
+	resp, err := oidc.introspectToken("opaque-test-token")
+	if err != nil {
+		t.Fatalf("introspectToken must succeed against the manual override endpoint, got: %v", err)
+	}
+	if !resp.Active {
+		t.Fatal("introspectToken response Active = false, want true")
+	}
+	if got := atomic.LoadInt32(&hits); got != 1 {
+		t.Fatalf("introspection endpoint hit count = %d, want 1", got)
+	}
+	if gotToken != "opaque-test-token" {
+		t.Fatalf("introspection request token = %q, want %q", gotToken, "opaque-test-token")
+	}
+}
+
+// TestIssue152SiblingRevocationAndLogout proves the two dead siblings this
+// issue repaired are wired end-to-end: RevokeTokenWithProvider
+// (token_manager.go) posts to a configRevocationURL override, and the
+// end-session URL BuildLogoutURL (helpers.go) builds from is the
+// configEndSessionURL override. The full handleLogout HTTP handler needs a
+// live SessionManager and an authenticated cookie to reach BuildLogoutURL,
+// which is disproportionate for this fix; instead this asserts the live
+// field wiring plus a direct BuildLogoutURL call with that wired value,
+// which is the same function handleLogout calls.
+func TestIssue152SiblingRevocationAndLogout(t *testing.T) {
+	t.Run("RevokeTokenWithProvider posts to the override", func(t *testing.T) {
+		var hits int32
+		var gotToken string
+		revocationSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			atomic.AddInt32(&hits, 1)
+			if err := r.ParseForm(); err == nil {
+				gotToken = r.PostFormValue("token")
+			}
+			w.WriteHeader(http.StatusOK)
+		}))
+		defer revocationSrv.Close()
+
+		oidc := &TraefikOidc{
+			providerURL:         "https://provider.example.com",
+			logger:              NewLogger("error"),
+			clientID:            "test-client",
+			clientSecret:        "test-secret",
+			httpClient:          http.DefaultClient,
+			configRevocationURL: revocationSrv.URL,
+		}
+		metadata := &ProviderMetadata{
+			Issuer:   "https://provider.example.com",
+			AuthURL:  "https://provider.example.com/authorize",
+			TokenURL: "https://provider.example.com/token",
+			JWKSURL:  "https://provider.example.com/jwks",
+			// RevokeURL intentionally omitted.
+		}
+		oidc.updateMetadataEndpoints(metadata)
+
+		if err := oidc.RevokeTokenWithProvider("opaque-test-token", "access_token"); err != nil {
+			t.Fatalf("RevokeTokenWithProvider must succeed against the manual override endpoint, got: %v", err)
+		}
+		if got := atomic.LoadInt32(&hits); got != 1 {
+			t.Fatalf("revocation endpoint hit count = %d, want 1", got)
+		}
+		if gotToken != "opaque-test-token" {
+			t.Fatalf("revocation request token = %q, want %q", gotToken, "opaque-test-token")
+		}
+	})
+
+	t.Run("logout URL builder emits the override", func(t *testing.T) {
+		overrideEndSession := "https://override.example.com/endsession"
+		oidc := &TraefikOidc{
+			providerURL:         "https://provider.example.com",
+			logger:              NewLogger("error"),
+			clientID:            "test-client",
+			configEndSessionURL: overrideEndSession,
+		}
+		metadata := &ProviderMetadata{
+			Issuer:   "https://provider.example.com",
+			AuthURL:  "https://provider.example.com/authorize",
+			TokenURL: "https://provider.example.com/token",
+			JWKSURL:  "https://provider.example.com/jwks",
+			// EndSessionURL intentionally omitted.
+		}
+		oidc.updateMetadataEndpoints(metadata)
+
+		_, endSession, _ := issue152Endpoints(oidc)
+		if endSession != overrideEndSession {
+			t.Fatalf("endSessionURL = %q, want override %q wired before building the logout URL", endSession, overrideEndSession)
+		}
+
+		logoutURL, err := BuildLogoutURL(endSession, "idtok123", "https://myapp.example.com/")
+		if err != nil {
+			t.Fatalf("BuildLogoutURL must succeed with the wired override, got: %v", err)
+		}
+		if !strings.HasPrefix(logoutURL, overrideEndSession+"?") {
+			t.Fatalf("logoutURL = %q, want prefix %q", logoutURL, overrideEndSession+"?")
+		}
+		if !strings.Contains(logoutURL, "id_token_hint=idtok123") {
+			t.Fatalf("logoutURL = %q, want it to contain the id_token_hint", logoutURL)
+		}
+	})
+}
+
+// TestIssue152ConfigValidation pins Config.Validate's IntrospectionURL check:
+// empty is fine (feature is opt-in), a valid HTTPS URL is fine, plaintext
+// HTTP is fine only for a loopback host (isValidSecureURL's RFC 8252-style
+// allowance, mirrored from the ProviderURL/RevocationURL/OIDCEndSessionURL
+// checks), and anything else — plaintext HTTP to a remote host, or a
+// malformed URL — is rejected with the introspectionURL-specific message.
+func TestIssue152ConfigValidation(t *testing.T) {
+	cases := []struct {
+		name        string
+		value       string
+		wantErr     bool
+		errContains string
+	}{
+		{"valid HTTPS URL", "https://idp.example.com/introspect", false, ""},
+		{"empty is valid (opt-in feature)", "", false, ""},
+		{"plaintext HTTP allowed for loopback", "http://localhost:8080/introspect", false, ""},
+		{"plaintext HTTP rejected for remote host", "http://evil.example.com/x", true, "introspectionURL must be a valid HTTPS URL"},
+		{"malformed URL rejected", "://garbage", true, "introspectionURL must be a valid HTTPS URL"},
+		{"URL with no host rejected", "https:///nohost", true, "introspectionURL must be a valid HTTPS URL"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := issue152BaseConfig()
+			cfg.IntrospectionURL = tc.value
+
+			err := cfg.Validate()
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("Validate() with IntrospectionURL=%q must fail", tc.value)
+				}
+				if !strings.Contains(err.Error(), tc.errContains) {
+					t.Fatalf("Validate() error = %q, want substring %q", err.Error(), tc.errContains)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("Validate() with IntrospectionURL=%q must succeed, got: %v", tc.value, err)
+			}
+		})
+	}
+}
+
+// TestIssue152InvalidIntrospectionURLNewContract proves an invalid
+// IntrospectionURL is rejected by New() through the same fail-closed,
+// untyped-nil-handler contract issue #151 established for every other
+// Config.Validate failure: a concrete "invalid configuration" error, and h
+// itself must be an untyped nil (not a typed-nil *TraefikOidc boxed into a
+// non-nil http.Handler interface value).
+func TestIssue152InvalidIntrospectionURLNewContract(t *testing.T) {
+	cfg := issue152BaseConfig()
+	cfg.IntrospectionURL = "http://evil.example.com/x" // plaintext HTTP to a remote host: rejected.
+
+	next := http.HandlerFunc(func(http.ResponseWriter, *http.Request) {})
+	h, err := New(context.Background(), next, cfg, "issue152-invalid-introspection")
+	if err == nil {
+		t.Fatal("New() must reject an invalid IntrospectionURL")
+	}
+	if !strings.Contains(err.Error(), "invalid configuration") {
+		t.Fatalf("New() error = %q, want it to contain %q", err.Error(), "invalid configuration")
+	}
+	if h != nil {
+		t.Fatalf("New() must return an untyped nil handler on error, got %T", h)
+	}
+}

issue154_regression_test.go

@@ -0,0 +1,326 @@
+package traefikoidc
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// issue154_regression_test.go — regression tests for issue #154.
+//
+// A providerURL pointing at a localhost identity provider (local
+// development, sidecar OIDC providers) caused an infinite redirect loop.
+// validateHost unconditionally rejected loopback/localhost hosts, so
+// buildURLWithParams returned "" for the discovered authorization endpoint,
+// buildAuthURL returned "", and Traefik kept redirecting to an empty
+// Location header forever.
+//
+// The fix adds an unexported `allowLoopbackHosts bool` field to TraefikOidc,
+// derived at construction time from `isLoopbackProviderURL(config.ProviderURL)`
+// (settings.go). validateHost now gates loopback IPs and localhost/127.x/::1
+// literals on `!t.allowLoopbackHosts`, while link-local, multicast, and the
+// cloud-metadata hostnames stay unconditionally blocked (SSRF surface must
+// not widen). updateMetadataEndpoints recomputes the same derivation from
+// t.providerURL directly (not the struct field), so it stays correct for
+// TraefikOidc values test code builds as struct literals.
+//
+// These tests pin: the opt-in behaves correctly, the default (flag unset)
+// still blocks loopback exactly as before the fix, the SSRF-relevant hosts
+// stay blocked even with the opt-in active, allowPrivateIPAddresses remains
+// an independent gate, the derivation helper is correct in isolation, the
+// end-to-end buildAuthURL behavior for both flag states, that NewWithContext
+// derives the field correctly from config.ProviderURL, and that the
+// discovery layer (updateMetadataEndpoints) and the URL-validation layer
+// (validateHost/buildAuthURL) agree on a loopback provider.
+
+// issue154LoopbackHosts are host strings that represent localhost/loopback
+// under every literal form validateHost must recognize: bare hostname,
+// hostname:port, case variation, IPv4 loopback with and without port, an
+// IPv6 loopback literal with port, and a non-canonical loopback IP
+// (127.0.0.0/8 is entirely loopback, not just 127.0.0.1).
+var issue154LoopbackHosts = []string{
+	"localhost",
+	"localhost:8080",
+	"LOCALHOST",
+	"127.0.0.1",
+	"127.0.0.1:8080",
+	"[::1]:8080",
+	"127.0.0.2:9000",
+}
+
+// TestIssue154ValidateHostLoopbackAllowed pins the opt-in: once a middleware
+// instance has allowLoopbackHosts=true (as New/NewWithContext derive it from
+// a loopback providerURL), every loopback host form validates cleanly.
+func TestIssue154ValidateHostLoopbackAllowed(t *testing.T) {
+	middleware := createMinimalMiddleware()
+	middleware.allowLoopbackHosts = true
+
+	for _, host := range issue154LoopbackHosts {
+		t.Run(host, func(t *testing.T) {
+			if err := middleware.validateHost(host); err != nil {
+				t.Fatalf("validateHost(%q) with allowLoopbackHosts=true must succeed, got: %v", host, err)
+			}
+		})
+	}
+}
+
+// TestIssue154ValidateHostLoopbackDefaultBlocked pins the default-preserving
+// half of the fix: a middleware instance built without explicitly setting
+// allowLoopbackHosts (its zero value, matching every TraefikOidc a
+// non-loopback New()/NewWithContext call produces) must still reject every
+// loopback host form, exactly as before the fix. This is asserted as
+// "error present", not against exact error text: "[::1]:8080" alone
+// (without a bracket-less counterpart) does not hit the pre-existing
+// net.SplitHostPort quirk where a bare "[::1]" without a port fails with
+// "invalid host format" instead of the loopback-specific message — but
+// pinning only non-nil keeps this test robust to either error path.
+func TestIssue154ValidateHostLoopbackDefaultBlocked(t *testing.T) {
+	middleware := createMinimalMiddleware() // allowLoopbackHosts left at zero value (false)
+
+	for _, host := range issue154LoopbackHosts {
+		t.Run(host, func(t *testing.T) {
+			if err := middleware.validateHost(host); err == nil {
+				t.Fatalf("validateHost(%q) with default allowLoopbackHosts must still be rejected", host)
+			}
+		})
+	}
+}
+
+// TestIssue154SecurityEnvelopeWithLoopbackAllowed is the highest-value test
+// in this file: it proves that opting into loopback hosts does not widen the
+// SSRF surface. Cloud metadata addresses, link-local, multicast, and
+// unspecified addresses must stay blocked even with allowLoopbackHosts=true.
+func TestIssue154SecurityEnvelopeWithLoopbackAllowed(t *testing.T) {
+	middleware := createMinimalMiddleware()
+	middleware.allowLoopbackHosts = true
+
+	cases := []struct {
+		name       string
+		host       string
+		wantSubstr string
+	}{
+		{"AWS/GCP metadata IP", "169.254.169.254", "loopback/link-local"},
+		{"AWS/GCP metadata IP with port", "169.254.169.254:80", "loopback/link-local"},
+		{"GCP metadata hostname", "metadata.google.internal", "dangerous hostname"},
+		{"GCP metadata hostname with port", "metadata.google.internal:80", "dangerous hostname"},
+		{"IPv6 link-local", "[fe80::1]:80", "loopback/link-local"},
+		{"IPv4 link-local multicast", "224.0.0.1", "loopback/link-local"},
+		{"unspecified IPv4", "0.0.0.0", "unspecified or multicast"},
+		{"unspecified IPv6 with port", "[::]:80", "unspecified or multicast"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := middleware.validateHost(tc.host)
+			if err == nil {
+				t.Fatalf("validateHost(%q) must still be rejected with allowLoopbackHosts=true", tc.host)
+			}
+			if !strings.Contains(err.Error(), tc.wantSubstr) {
+				t.Fatalf("validateHost(%q) error = %q, want substring %q", tc.host, err.Error(), tc.wantSubstr)
+			}
+		})
+	}
+}
+
+// TestIssue154PrivateIPIndependence proves allowLoopbackHosts and
+// allowPrivateIPAddresses are independent gates: opting a middleware into
+// loopback hosts must not also open up RFC 1918 private ranges.
+func TestIssue154PrivateIPIndependence(t *testing.T) {
+	middleware := createMinimalMiddleware()
+	middleware.allowLoopbackHosts = true
+	middleware.allowPrivateIPAddresses = false
+
+	privateHosts := []string{"10.0.0.5", "192.168.1.10", "172.16.0.1"}
+	for _, host := range privateHosts {
+		t.Run(host, func(t *testing.T) {
+			err := middleware.validateHost(host)
+			if err == nil {
+				t.Fatalf("validateHost(%q) must be rejected when allowPrivateIPAddresses=false", host)
+			}
+			if !strings.Contains(err.Error(), "private/internal") {
+				t.Fatalf("validateHost(%q) error = %q, want substring %q", host, err.Error(), "private/internal")
+			}
+		})
+	}
+}
+
+// TestIssue154IsLoopbackProviderURL exercises the construction-time
+// derivation helper in isolation, including malformed input that must not
+// panic.
+func TestIssue154IsLoopbackProviderURL(t *testing.T) {
+	cases := []struct {
+		name        string
+		providerURL string
+		want        bool
+	}{
+		{"http localhost with port", "http://localhost:8080", true},
+		{"http loopback IPv4 with port", "http://127.0.0.1:9000", true},
+		{"http loopback IPv6 with port", "http://[::1]:9000", true},
+		{"https localhost uppercase", "https://LOCALHOST:9000", true},
+		{"https real remote provider", "https://accounts.google.com", false},
+		{"https another remote provider", "https://idp.example.com", false},
+		{"empty string", "", false},
+		{"malformed URL must not panic", "://garbage", false},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := isLoopbackProviderURL(tc.providerURL)
+			if got != tc.want {
+				t.Fatalf("isLoopbackProviderURL(%q) = %v, want %v", tc.providerURL, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestIssue154BuildAuthURLLoopbackProvider is the issue scenario reproduced
+// at the unit level: a loopback authURL must produce a real redirect URL
+// when allowLoopbackHosts is set, and the pre-fix behavior (empty string,
+// the infinite-redirect-loop trigger) must be pinned as the default when it
+// is not.
+func TestIssue154BuildAuthURLLoopbackProvider(t *testing.T) {
+	t.Run("allowLoopbackHosts=true builds a real auth URL", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		middleware.allowLoopbackHosts = true
+		middleware.authURL = "http://localhost:8080/oauth/authorize"
+		middleware.issuerURL = "http://localhost:8080"
+
+		got := middleware.buildAuthURL("http://localhost:5555/callback", "state123", "nonce456", "")
+
+		if got == "" {
+			t.Fatal("buildAuthURL returned empty string for a loopback provider with allowLoopbackHosts=true")
+		}
+		if !strings.HasPrefix(got, "http://localhost:8080/oauth/authorize?") {
+			t.Fatalf("buildAuthURL = %q, want prefix %q", got, "http://localhost:8080/oauth/authorize?")
+		}
+		for _, want := range []string{"client_id=", "state=state123", "nonce=nonce456"} {
+			if !strings.Contains(got, want) {
+				t.Fatalf("buildAuthURL = %q, want it to contain %q", got, want)
+			}
+		}
+	})
+
+	t.Run("default allowLoopbackHosts=false pins pre-fix empty-string behavior", func(t *testing.T) {
+		middleware := createMinimalMiddleware() // allowLoopbackHosts left at zero value (false)
+		middleware.authURL = "http://localhost:8080/oauth/authorize"
+		middleware.issuerURL = "http://localhost:8080"
+
+		got := middleware.buildAuthURL("http://localhost:5555/callback", "state123", "nonce456", "")
+
+		if got != "" {
+			t.Fatalf("buildAuthURL = %q, want empty string when a loopback provider is not opted in", got)
+		}
+	})
+}
+
+// issue154BaseConfig returns a complete, valid Config with the given
+// providerURL, following the minimal-valid-config pattern used elsewhere in
+// this package (e.g. TestRank2And6_InvalidConfigFailsClosed in
+// security_audit_fixes_test.go).
+func issue154BaseConfig(providerURL string) *Config {
+	return &Config{
+		ProviderURL:          providerURL,
+		ClientID:             "test-client",
+		ClientSecret:         "test-secret",
+		CallbackURL:          "/callback",
+		SessionEncryptionKey: "this-is-a-valid-session-key-32b!",
+		RateLimit:            100,
+	}
+}
+
+// TestIssue154NewWithContextDerivation proves NewWithContext derives
+// allowLoopbackHosts from config.ProviderURL at construction time (main.go,
+// the `allowLoopbackHosts: isLoopbackProviderURL(config.ProviderURL)` field
+// initializer). The field is set synchronously before the metadata-discovery
+// goroutine starts, so this needs no live discovery endpoint: the ports used
+// below (a loopback port nothing listens on, and an RFC 2606 .invalid host)
+// only need to fail fast once the background goroutine attempts discovery —
+// Close() cancels that goroutine's context regardless of outcome.
+func TestIssue154NewWithContextDerivation(t *testing.T) {
+	t.Run("loopback providerURL derives allowLoopbackHosts=true", func(t *testing.T) {
+		// A real httptest server (loopback by construction) so the
+		// background discovery goroutine NewWithContext starts completes
+		// quickly and Close() below does not have to wait out its 10s
+		// goroutine-shutdown timeout for an unreachable host. Mirrors
+		// TestInitializeMetadata's server setup in main_initialization_test.go.
+		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:   srv.URL,
+					AuthURL:  srv.URL + "/auth",
+					TokenURL: srv.URL + "/token",
+					JWKSURL:  srv.URL + "/jwks",
+				})
+				return
+			}
+			w.WriteHeader(http.StatusNotFound)
+		}))
+		defer srv.Close()
+
+		cfg := issue154BaseConfig(srv.URL)
+		oidc, err := NewWithContext(context.Background(), cfg, nil, "issue154-loopback")
+		if err != nil {
+			t.Fatalf("NewWithContext must accept a valid loopback config, got: %v", err)
+		}
+		defer func() { _ = oidc.Close() }()
+
+		if !oidc.allowLoopbackHosts {
+			t.Fatal("expected allowLoopbackHosts=true for a loopback providerURL")
+		}
+	})
+
+	t.Run("non-loopback providerURL derives allowLoopbackHosts=false", func(t *testing.T) {
+		cfg := issue154BaseConfig("https://provider.invalid")
+		oidc, err := NewWithContext(context.Background(), cfg, nil, "issue154-remote")
+		if err != nil {
+			t.Fatalf("NewWithContext must accept a valid remote config, got: %v", err)
+		}
+		defer func() { _ = oidc.Close() }()
+
+		if oidc.allowLoopbackHosts {
+			t.Fatal("expected allowLoopbackHosts=false for a non-loopback providerURL")
+		}
+	})
+}
+
+// TestIssue154DiscoveryAndURLValidationAgree catches layer drift between the
+// discovery-endpoint sanitizer (updateMetadataEndpoints, which recomputes
+// isLoopbackProviderURL(t.providerURL) itself per its doc comment, since
+// test helpers build &TraefikOidc{} literals without going through
+// NewWithContext) and the outbound URL validator (validateHost, gated on the
+// allowLoopbackHosts field). Both layers must agree that a loopback provider
+// is usable end-to-end: discovery must accept the loopback authURL, and
+// buildAuthURL must build a real URL once allowLoopbackHosts is set to
+// mirror what NewWithContext would have derived.
+func TestIssue154DiscoveryAndURLValidationAgree(t *testing.T) {
+	oidc := &TraefikOidc{
+		providerURL: "http://localhost:8080",
+		logger:      NewLogger("debug"),
+		clientID:    "test-client",
+	}
+
+	metadata := &ProviderMetadata{
+		Issuer:   "http://localhost:8080",
+		AuthURL:  "http://localhost:8080/oauth/authorize",
+		TokenURL: "http://localhost:8080/oauth/token",
+		JWKSURL:  "http://localhost:8080/jwks",
+	}
+	oidc.updateMetadataEndpoints(metadata)
+
+	if oidc.authURL == "" {
+		t.Fatal("updateMetadataEndpoints rejected a loopback authURL for a loopback providerURL (discovery layer drift)")
+	}
+
+	// The URL-validation layer must independently agree once
+	// allowLoopbackHosts mirrors what NewWithContext would have derived from
+	// this same loopback providerURL.
+	oidc.allowLoopbackHosts = true
+	if got := oidc.buildAuthURL("http://localhost:5555/callback", "state", "nonce", ""); got == "" {
+		t.Fatal("buildAuthURL returned empty for the discovered loopback authURL with allowLoopbackHosts=true (validation layer drift)")
+	}
+}

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
+	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,
 		},
 	}
 
@@ -415,8 +419,8 @@ func TestMiddlewareBackchannelLogoutRouting(t *testing.T) {
 		clientID:                     "test-client",
 		issuerURL:                    "https://provider.example.com",
 		initComplete:                 make(chan struct{}),
-		firstRequestReceived:     true,
-		metadataRefreshStarted:   true,
+		firstRequestStarted:          1,
+		metadataRefreshStartedAtomic: 1,
 		logoutURLPath:                "/logout",
 	}
 	close(oidc.initComplete)
@@ -457,14 +461,15 @@ func TestMiddlewareFrontchannelLogoutRouting(t *testing.T) {
 		clientID:                     "test-client",
 		issuerURL:                    "https://provider.example.com",
 		initComplete:                 make(chan struct{}),
-		firstRequestReceived:     true,
-		metadataRefreshStarted:   true,
+		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

@@ -16,6 +16,7 @@ import (
 	"text/template"
 	"time"
 
+	telemetry "github.com/lukaszraczylo/oss-telemetry"
 	"golang.org/x/time/rate"
 )
 
@@ -23,6 +24,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" {
@@ -76,6 +82,39 @@ var defaultExcludedURLs = map[string]struct{}{
 	"/favicon": {},
 }
 
+// headerTemplateFuncMap returns the function map available to custom header
+// value templates, gated by the effective claims whitelist (built-in +
+// config.AllowedClaims). It exposes exactly two helpers:
+//   - default: substitute a fallback when a value is nil/empty.
+//   - get: safe map access RESTRICTED to whitelisted claim keys, so it cannot be
+//     used to read a non-whitelisted claim, a raw token, or the whole data map
+//     (issue #149 review). This is the sole runtime enforcement of the claims
+//     whitelist for `get`; static validation cannot reliably parse its arguments.
+func headerTemplateFuncMap(allowedClaims map[string]bool) template.FuncMap {
+	if allowedClaims == nil {
+		allowedClaims = safeClaimsFields
+	}
+	return template.FuncMap{
+		"default": func(defaultVal interface{}, val interface{}) interface{} {
+			if val == nil || val == "" {
+				return defaultVal
+			}
+			return val
+		},
+		"get": func(m interface{}, key string) interface{} {
+			if !allowedClaims[key] {
+				return ""
+			}
+			if mapVal, ok := m.(map[string]interface{}); ok {
+				if val, exists := mapVal[key]; exists {
+					return val
+				}
+			}
+			return ""
+		},
+	}
+}
+
 // New creates a new TraefikOidc middleware instance.
 // It initializes all components including caches, HTTP clients, session management,
 // templates, and starts background processes for metadata discovery.
@@ -89,7 +128,27 @@ 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) {
-	return NewWithContext(ctx, config, next, name)
+	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)
+		}
+	})
+	// Deliberately NOT `return NewWithContext(...)` (issue #151): that tail call
+	// converts (*TraefikOidc, error) to (http.Handler, error) in the return
+	// statement. Compiled, a failed construction then returns a typed-nil
+	// *TraefikOidc wrapped in a NON-nil http.Handler; under yaegi v0.16.1 (the
+	// interpreter Traefik and the plugin-catalog analyzer embed) the same
+	// statement zeroes BOTH results on the error path, so callers saw
+	// (nil, nil) and reported the opaque "invalid handler type: <nil>" instead
+	// of the real error. The explicit split returns an untyped nil handler and
+	// keeps the error intact in both worlds.
+	t, err := NewWithContext(ctx, config, next, name)
+	if err != nil {
+		return nil, err
+	}
+	return t, nil
 }
 
 // NewWithContext creates a new TraefikOidc middleware instance with proper context handling.
@@ -99,18 +158,23 @@ 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 {
+		// Surface the concrete reason. When New() returns a nil handler, Traefik
+		// only logs the opaque router-level "invalid handler type: <nil>" and
+		// swallows this error, leaving operators no way to see WHY the plugin
+		// failed to build (issue #149). Log it explicitly at construction.
+		logger.Errorf("traefikoidc: invalid configuration, middleware not built: %v", err)
+		return nil, fmt.Errorf("invalid configuration: %w", err)
 	}
 	// Setup HTTP client
 	caPool, err := config.loadCACertPool()
@@ -169,12 +233,22 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		introspectionCache: cacheManager.GetSharedIntrospectionCache(), // Cache for introspection results
 		clientID:           config.ClientID,
 		clientSecret:       config.ClientSecret,
+		clientAuthMethod: func() string {
+			if config.ClientAuthMethod != "" {
+				return config.ClientAuthMethod
+			}
+			return "client_secret_post"
+		}(),
 		audience: func() string {
 			if config.Audience != "" {
 				return config.Audience
 			}
+			if config.Resource != "" {
+				return config.Resource
+			}
 			return config.ClientID
 		}(),
+		explicitAudience: config.Audience,
 		roleClaimName: func() string {
 			if config.RoleClaimName != "" {
 				return config.RoleClaimName
@@ -195,11 +269,28 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		}(),
 		forceHTTPS:                config.ForceHTTPS,
 		enablePKCE:                config.EnablePKCE,
+		extraAuthParams:           config.ExtraAuthParams,
+		resource:                  config.Resource,
 		overrideScopes:            config.OverrideScopes,
 		strictAudienceValidation:  config.StrictAudienceValidation,
 		allowOpaqueTokens:         config.AllowOpaqueTokens,
 		requireTokenIntrospection: config.RequireTokenIntrospection,
 		disableReplayDetection:    config.DisableReplayDetection,
+		// Operator-configured endpoint overrides (issue #152). Applied inside
+		// updateMetadataEndpoints so the override survives every metadata
+		// refresh, not just construction.
+		configRevocationURL:    config.RevocationURL,
+		configEndSessionURL:    config.OIDCEndSessionURL,
+		configIntrospectionURL: config.IntrospectionURL,
+		// Cold-start seed: discovery failure must not lose operator-configured
+		// endpoints; updateMetadataEndpoints re-applies these on every refresh.
+		// Seeding introspectionURL here does not populate metadataSnapshot
+		// (only updateMetadataEndpoints does); all three consumers
+		// (token_introspection.go, token_manager.go, helpers.go) read these
+		// metadataMu-guarded fields directly, not the snapshot.
+		revocationURL:    config.RevocationURL,
+		endSessionURL:    config.OIDCEndSessionURL,
+		introspectionURL: config.IntrospectionURL,
 		scopes: func() []string {
 			userProvidedScopes := deduplicateScopes(config.Scopes)
 
@@ -215,7 +306,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{}),
@@ -242,6 +333,7 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		scopeFilter:               NewScopeFilter(logger), // NEW - for discovery-based scope filtering
 		dcrConfig:                 config.DynamicClientRegistration,
 		allowPrivateIPAddresses:   config.AllowPrivateIPAddresses,
+		allowLoopbackHosts:        isLoopbackProviderURL(config.ProviderURL),
 		minimalHeaders:            config.MinimalHeaders,
 		stripAuthCookies:          config.StripAuthCookies,
 		enableBackchannelLogout:   config.EnableBackchannelLogout,
@@ -250,6 +342,46 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		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
@@ -259,9 +391,48 @@ 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)
 	}
 
+	// Log RFC 8707 resource indicator configuration
+	if t.resource != "" {
+		t.logger.Infof("RFC 8707 resource indicator configured: %s (effective audience: %s)", t.resource, t.audience)
+	}
+
+	// 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 == "" && config.Resource == "" {
+			cancelFunc()
+			return nil, fmt.Errorf("EnableBearerAuth=true requires Audience or Resource 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
+	if config.CookiePath != "" {
+		t.sessionManager.cookiePath = config.CookiePath
+		t.logger.Debugf("Using configured cookie path: %s", config.CookiePath)
+	}
 	t.errorRecoveryManager = NewErrorRecoveryManager(t.logger)
 
 	// Initialize token resilience manager with default configuration
@@ -273,6 +444,15 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 	// rotates refresh tokens (Zitadel/Authentik default).
 	t.refreshCoordinator = NewRefreshCoordinator(DefaultRefreshCoordinatorConfig(), t.logger)
 
+	if config.ClientAuthMethod == "private_key_jwt" {
+		signer, err := buildClientAssertionSignerFromConfig(config)
+		if err != nil {
+			cancelFunc()
+			return nil, fmt.Errorf("failed to build client assertion signer: %w", err)
+		}
+		t.clientAssertion = signer
+	}
+
 	t.extractClaimsFunc = extractClaims
 	t.initiateAuthenticationFunc = func(rw http.ResponseWriter, req *http.Request, session *SessionData, redirectURL string) {
 		t.defaultInitiateAuthentication(rw, req, session, redirectURL)
@@ -288,22 +468,7 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 
 	t.headerTemplates = make(map[string]*template.Template)
 
-	funcMap := template.FuncMap{
-		"default": func(defaultVal interface{}, val interface{}) interface{} {
-			if val == nil || val == "" {
-				return defaultVal
-			}
-			return val
-		},
-		"get": func(m interface{}, key string) interface{} {
-			if mapVal, ok := m.(map[string]interface{}); ok {
-				if val, exists := mapVal[key]; exists {
-					return val
-				}
-			}
-			return ""
-		},
-	}
+	funcMap := headerTemplateFuncMap(claimsWhitelist(config.AllowedClaims))
 
 	for _, header := range config.Headers {
 		tmpl := template.New(header.Name).Funcs(funcMap).Option("missingkey=zero")
@@ -343,6 +508,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 {
@@ -420,13 +586,73 @@ 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.
+	// Recomputed from t.providerURL (not the allowLoopbackHosts field) so this
+	// stays correct for TraefikOidc values built outside New() (test helpers
+	// construct &TraefikOidc{providerURL: ...} directly, leaving
+	// allowLoopbackHosts at its zero value).
+	allowLoopback := isLoopbackProviderURL(t.providerURL)
+	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 = ""
+	}
+	// Operator-configured endpoint overrides take precedence over discovered
+	// values. They deliberately skip validateDiscoveredEndpoint and the
+	// sameHost pin: those defend against a poisoned discovery document, while
+	// operator config sits at the same trust tier as providerURL itself and is
+	// already gated by isValidSecureURL at config time.
+	if t.configRevocationURL != "" {
+		metadata.RevokeURL = t.configRevocationURL
+	}
+	if t.configEndSessionURL != "" {
+		metadata.EndSessionURL = t.configEndSessionURL
+	}
+	if t.configIntrospectionURL != "" {
+		metadata.IntrospectionURL = t.configIntrospectionURL
+	}
+
 	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)
@@ -436,6 +662,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):
@@ -485,8 +504,7 @@ func TestFirstRequestHandling(t *testing.T) {
 
 		oidc := &TraefikOidc{
 			providerURL:         server.URL,
-			firstRequestReceived: false,
-			firstRequestMutex:    sync.Mutex{},
+			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
@@ -557,8 +569,7 @@ func TestFirstRequestHandling(t *testing.T) {
 
 		oidc := &TraefikOidc{
 			providerURL:         server.URL,
-			firstRequestReceived: false,
-			firstRequestMutex:    sync.Mutex{},
+			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
+		// 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
+			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 && 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)
+	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 err == nil {
-			if len(groups) > 0 {
-				req.Header.Set("X-User-Groups", strings.Join(groups, ","))
+
+	// 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)
 		}
-			if len(roles) > 0 {
-				req.Header.Set("X-User-Roles", strings.Join(roles, ","))
+	} 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 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 safeRoles := t.sanitizeHeaderClaimList(roles, "X-User-Roles"); len(safeRoles) > 0 {
+				req.Header.Set("X-User-Roles", strings.Join(safeRoles, ","))
 			}
 		}
 	}
@@ -502,36 +756,49 @@ 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.
+		// 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":  session.GetAccessToken(),
-				"IDToken":      idToken,
-				"RefreshToken": session.GetRefreshToken(),
-				"Claims":       idClaims,
+			"AccessToken":  p.AccessToken,
+			"IDToken":      p.IDToken,
+			"IdToken":      p.IDToken, // documented spelling (README/CONFIGURATION); alias so {{.IdToken}} renders (issue #149 review)
+			"RefreshToken": p.RefreshToken,
+			"Claims":       p.Claims,
 		}
 
 		for headerName, tmpl := range t.headerTemplates {
@@ -541,23 +808,22 @@ func (t *TraefikOidc) processAuthorizedRequest(rw http.ResponseWriter, req *http
 				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)
-				t.logger.Debugf("Set templated header %s = %s", 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))
 		}
-			// 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.
-		}
-	}
-
-	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")
 	}
 
 	// Apply security headers if configured
@@ -573,7 +839,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 +853,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),
+		// inFlightRefreshes and sessionRefreshAttempts are both sync.Map;
+		// their zero values are ready to use.
 		config:        config,
 		metrics:  &RefreshMetrics{},
 		logger:   logger,
 		stopChan: make(chan struct{}),
-		cleanupTimers:          make(map[string]*time.Timer),
 		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
-		}
-		return true // Still in cooldown
-	}
+	cur := tracker.stateOf()
 
-	// Check if window expired
-	if now.Sub(tracker.windowStartTime) > rc.config.RefreshAttemptWindow {
-		// Reset window
-		tracker.attempts = 1 // Already recorded one attempt
-		tracker.windowStartTime = now
+	// Already in cooldown?
+	if cur.cooldownEndNano != 0 {
+		if nowNano <= cur.cooldownEndNano {
+			return true // still in cooldown
+		}
+		// 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)
+	// 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, tracker.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
+	switch atomic.LoadInt32(&cb.state) {
+	case 0:
+		if int(failures) >= cb.config.MaxFailures {
 			atomic.StoreInt32(&cb.state, 1)
-	} else if state == 2 {
-		// Half-open failed, return to open
+		}
+	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)

regression/regression_test.go

@@ -18,6 +18,50 @@ func TestIssueRegressions(t *testing.T) {
 	t.Run("Issue60_Missing_Claim_Fields", testIssue60MissingClaimFields)
 	t.Run("Issue60_Safe_Template_Functions", testIssue60SafeTemplateFunctions)
 	t.Run("Issue60_Double_Processing_Concern", testIssue60DoubleProcessing)
+	t.Run("Issue148_Template_Whitespace_Tolerance", testIssue148TemplateWhitespace)
+}
+
+// testIssue148TemplateWhitespace tests that header template validation tolerates
+// whitespace inside Go template delimiters (e.g. "{{ get" with a leading space),
+// which Go's text/template treats identically to "{{get". v1.0.26 rejected the
+// spaced form, causing "invalid handler type: <nil>" at startup. See issue #148.
+func testIssue148TemplateWhitespace(t *testing.T) {
+	baseConfig := func() *traefikoidc.Config {
+		c := traefikoidc.CreateConfig()
+		c.ProviderURL = "https://example.com"
+		c.ClientID = "test-client"
+		c.ClientSecret = "test-secret"
+		c.CallbackURL = "/callback"
+		c.SessionEncryptionKey = "test-encryption-key-32-characters"
+		return c
+	}
+
+	// Spaced delimiters must validate identically to the compact form.
+	validSpaced := []traefikoidc.TemplatedHeader{
+		{Name: "X-Get-Spaced", Value: "{{ get .Claims \"email\" }}"},
+		{Name: "X-Get-MultiSpace", Value: "{{  get .Claims \"email\"}}"},
+		{Name: "X-Default-Spaced", Value: "{{ default \"unknown\" .Claims.department }}"},
+		{Name: "X-Claims-Spaced", Value: "{{ .Claims.email }}"},
+		{Name: "X-AccessToken-Spaced", Value: "{{ .AccessToken }}"},
+	}
+	for _, header := range validSpaced {
+		config := baseConfig()
+		config.Headers = []traefikoidc.TemplatedHeader{header}
+		assert.NoError(t, config.Validate(),
+			"Spaced template should validate: %s", header.Value)
+	}
+
+	// A leading space must NOT smuggle a dangerous pattern past validation.
+	dangerousSpaced := []traefikoidc.TemplatedHeader{
+		{Name: "X-Bad-Range", Value: "{{ range .Items }}{{.}}{{end}}"},
+		{Name: "X-Bad-Call", Value: "{{ call .Func }}"},
+	}
+	for _, header := range dangerousSpaced {
+		config := baseConfig()
+		config.Headers = []traefikoidc.TemplatedHeader{header}
+		assert.Error(t, config.Validate(),
+			"Spaced dangerous template must still be rejected: %s", header.Value)
+	}
 }
 
 // testIssue53CSRFRegression tests the specific issue reported in GitHub issue #53
@@ -325,7 +369,10 @@ func testIssue60SafeTemplateFunctions(t *testing.T) {
 		config.Headers = []traefikoidc.TemplatedHeader{header}
 		err := config.Validate()
 		require.Error(t, err, "Dangerous template should be rejected: %s", header.Value)
-		assert.Contains(t, err.Error(), "dangerous", "Error should mention dangerous pattern")
+		// The template validator (template_validation.go) rejects these; Config.Validate
+		// wraps the reason with this stable prefix. Assert the behavior (rejected by
+		// the security validator) rather than a specific message word.
+		assert.Contains(t, err.Error(), "failed security validation", "should be rejected by the template security validator")
 	}
 
 	// Test all safe patterns from the documentation

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

rfc8707_resource_test.go

@@ -0,0 +1,342 @@
+package traefikoidc
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestBuildAuthURLResourceParameter verifies the RFC 8707 `resource`
+// parameter is appended to the authorization URL, and that it does not
+// interact with the unrelated audience/extraAuthParams handling.
+func TestBuildAuthURLResourceParameter(t *testing.T) {
+	t.Run("resource is added", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		middleware.resource = "https://api.example.com"
+
+		authURL := middleware.buildAuthURL(
+			"https://app.com/callback", "state123", "nonce456", "",
+		)
+
+		parsed, err := url.Parse(authURL)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"https://api.example.com"}, parsed.Query()["resource"])
+	})
+
+	t.Run("empty resource is a no-op", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		// resource left unset
+
+		authURL := middleware.buildAuthURL(
+			"https://app.com/callback", "state123", "nonce456", "",
+		)
+
+		assert.NotContains(t, authURL, "resource=")
+	})
+
+	t.Run("a resource carrying a query component is percent-encoded, not merged", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		middleware.resource = "https://api.example.com/v1?tenant=acme"
+
+		authURL := middleware.buildAuthURL(
+			"https://app.com/callback", "state123", "nonce456", "",
+		)
+
+		parsed, err := url.Parse(authURL)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"https://api.example.com/v1?tenant=acme"}, parsed.Query()["resource"])
+	})
+
+	t.Run("extraAuthParams cannot override or duplicate the resource parameter", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		middleware.resource = "https://api.example.com"
+		middleware.extraAuthParams = map[string]string{
+			"resource": "https://attacker.example",
+		}
+
+		authURL := middleware.buildAuthURL(
+			"https://app.com/callback", "state123", "nonce456", "",
+		)
+
+		parsed, err := url.Parse(authURL)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"https://api.example.com"}, parsed.Query()["resource"])
+		assert.NotContains(t, authURL, "attacker.example")
+	})
+
+	// Regression: a Resource-only config derives a validation-time audience
+	// default (see TestAudienceDefaultsFromSingleResource), but that default
+	// must never be sent as the non-standard `audience` request parameter —
+	// manual interop testing found this made every resource-configured
+	// authorization request carry both `resource=` and `audience=`, which
+	// providers that give `audience` its own meaning (e.g. Ory Hydra) would
+	// misinterpret.
+	t.Run("a resource-derived audience default is not sent as the audience parameter", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		middleware.resource = "https://api.example.com"
+		middleware.audience = "https://api.example.com" // as main.go's default would set it
+		middleware.explicitAudience = ""                // Config.Audience was left unset
+
+		authURL := middleware.buildAuthURL(
+			"https://app.com/callback", "state123", "nonce456", "",
+		)
+
+		assert.NotContains(t, authURL, "audience=")
+	})
+
+	t.Run("an explicitly configured audience is still sent alongside resource", func(t *testing.T) {
+		middleware := createMinimalMiddleware()
+		middleware.resource = "https://api.example.com"
+		middleware.audience = "https://explicit.example.com"
+		middleware.explicitAudience = "https://explicit.example.com"
+
+		authURL := middleware.buildAuthURL(
+			"https://app.com/callback", "state123", "nonce456", "",
+		)
+
+		parsed, err := url.Parse(authURL)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"https://explicit.example.com"}, parsed.Query()["audience"])
+		assert.Equal(t, []string{"https://api.example.com"}, parsed.Query()["resource"])
+	})
+}
+
+// newExchangeTestMiddleware builds a minimal TraefikOidc wired to server for
+// exchangeTokens tests.
+func newExchangeTestMiddleware(server *httptest.Server, resource string) *TraefikOidc {
+	return &TraefikOidc{
+		tokenURL:     server.URL + "/token",
+		clientID:     "test_client",
+		clientSecret: "test_secret",
+		audience:     "test_client",
+		resource:     resource,
+		tokenHTTPClient: &http.Client{
+			Timeout: 10 * time.Second,
+		},
+		logger:       NewLogger("debug"),
+		initComplete: make(chan struct{}),
+	}
+}
+
+func newResourceEchoTokenServer(t *testing.T) (*httptest.Server, *url.Values) {
+	var captured url.Values
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		require.NoError(t, err)
+		values, err := url.ParseQuery(string(body))
+		require.NoError(t, err)
+		captured = values
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(TokenResponse{
+			AccessToken:  "test_access_token",
+			IDToken:      "test_id_token",
+			RefreshToken: "test_refresh_token",
+			TokenType:    "Bearer",
+			ExpiresIn:    3600,
+		})
+	}))
+	return server, &captured
+}
+
+// TestExchangeTokensResourceParameter verifies RFC 8707 §2.2: the same
+// resource indicator configured for the authorization request is also sent
+// on both the authorization_code and refresh_token grants.
+func TestExchangeTokensResourceParameter(t *testing.T) {
+	t.Run("authorization_code grant sends the resource parameter", func(t *testing.T) {
+		server, captured := newResourceEchoTokenServer(t)
+		defer server.Close()
+
+		middleware := newExchangeTestMiddleware(server, "https://api.example.com")
+
+		_, err := middleware.exchangeTokens(context.Background(), "authorization_code", "auth-code", "https://app.com/callback", "")
+		require.NoError(t, err)
+
+		assert.Equal(t, []string{"https://api.example.com"}, (*captured)["resource"])
+	})
+
+	t.Run("refresh_token grant sends the resource parameter", func(t *testing.T) {
+		server, captured := newResourceEchoTokenServer(t)
+		defer server.Close()
+
+		middleware := newExchangeTestMiddleware(server, "https://api.example.com")
+
+		_, err := middleware.exchangeTokens(context.Background(), "refresh_token", "refresh-token-value", "", "")
+		require.NoError(t, err)
+
+		assert.Equal(t, []string{"https://api.example.com"}, (*captured)["resource"])
+	})
+
+	t.Run("no resource configured sends no resource parameter", func(t *testing.T) {
+		server, captured := newResourceEchoTokenServer(t)
+		defer server.Close()
+
+		middleware := newExchangeTestMiddleware(server, "")
+
+		_, err := middleware.exchangeTokens(context.Background(), "authorization_code", "auth-code", "https://app.com/callback", "")
+		require.NoError(t, err)
+
+		assert.NotContains(t, *captured, "resource")
+	})
+}
+
+// TestConfigValidateResources exercises Config.Validate()'s RFC 8707
+// resource-indicator rules.
+func TestConfigValidateResources(t *testing.T) {
+	baseConfig := func() *Config {
+		return &Config{
+			ProviderURL:          "https://provider.example.com",
+			ClientID:             "test-client",
+			ClientSecret:         "test-secret",
+			CallbackURL:          "/callback",
+			SessionEncryptionKey: "this-is-a-valid-session-key-32b!",
+			RateLimit:            100,
+		}
+	}
+
+	tests := []struct {
+		name     string
+		resource string
+		audience string
+		wantErr  string // substring; empty means no error expected
+	}{
+		{
+			name:     "unset resource, no audience needed",
+			resource: "",
+		},
+		{
+			name:     "valid https resource, no audience needed",
+			resource: "https://api.example.com",
+		},
+		{
+			name:     "valid urn resource",
+			resource: "urn:example:api",
+		},
+		{
+			name:     "resource with unrelated explicit audience is allowed",
+			resource: "https://api.example.com",
+			audience: "https://explicit.example.com",
+		},
+		{
+			name:     "fragment rejected",
+			resource: "https://api.example.com/v1#fragment",
+			wantErr:  "must not contain a fragment",
+		},
+		{
+			name:     "relative URI rejected",
+			resource: "/api/v1",
+			wantErr:  "must be an absolute URI",
+		},
+		{
+			name:     "non-loopback http rejected",
+			resource: "http://api.example.com",
+			wantErr:  "must be a valid HTTPS URL",
+		},
+		{
+			name:     "loopback http accepted",
+			resource: "http://127.0.0.1:8080/api",
+		},
+		{
+			name:     "wildcard rejected",
+			resource: "https://*.example.com",
+			wantErr:  "must not contain wildcards",
+		},
+		{
+			name:     "control character rejected",
+			resource: "https://api.example.com/\n",
+			wantErr:  "contains invalid characters",
+		},
+		{
+			name:     "too long rejected",
+			resource: "https://api.example.com/" + stringOfLength(250),
+			wantErr:  "must not exceed 256 characters",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := baseConfig()
+			cfg.Resource = tt.resource
+			cfg.Audience = tt.audience
+
+			err := cfg.Validate()
+			if tt.wantErr == "" {
+				assert.NoError(t, err)
+				return
+			}
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), tt.wantErr)
+		})
+	}
+}
+
+func stringOfLength(n int) string {
+	b := make([]byte, n)
+	for i := range b {
+		b[i] = 'a'
+	}
+	return string(b)
+}
+
+// TestAudienceDefaultsFromSingleResource verifies main.go's audience
+// derivation: a configured resource becomes the effective validation
+// audience when Audience is unset, matching what the IdP will put in the
+// access token's `aud` claim.
+func TestAudienceDefaultsFromSingleResource(t *testing.T) {
+	baseConfig := func() *Config {
+		return &Config{
+			ProviderURL:          "https://provider.example.com",
+			ClientID:             "test-client",
+			ClientSecret:         "test-secret",
+			CallbackURL:          "/callback",
+			SessionEncryptionKey: "this-is-a-valid-session-key-32b!",
+			RateLimit:            100,
+		}
+	}
+
+	t.Run("resource, no audience: audience defaults to the resource", func(t *testing.T) {
+		cfg := baseConfig()
+		cfg.Resource = "https://api.example.com"
+
+		mw, err := New(context.Background(), http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}), cfg, "test")
+		require.NoError(t, err)
+		t.Cleanup(func() { _ = mw.(*TraefikOidc).Close() })
+
+		assert.Equal(t, "https://api.example.com", mw.(*TraefikOidc).audience)
+		assert.Equal(t, "https://api.example.com", mw.(*TraefikOidc).resource)
+		// The default must be validation-only: Config.Audience was never set,
+		// so nothing should be sent as the outbound `audience` parameter.
+		assert.Empty(t, mw.(*TraefikOidc).explicitAudience)
+	})
+
+	t.Run("explicit audience wins over resource", func(t *testing.T) {
+		cfg := baseConfig()
+		cfg.Resource = "https://api.example.com"
+		cfg.Audience = "https://explicit.example.com"
+
+		mw, err := New(context.Background(), http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}), cfg, "test")
+		require.NoError(t, err)
+		t.Cleanup(func() { _ = mw.(*TraefikOidc).Close() })
+
+		assert.Equal(t, "https://explicit.example.com", mw.(*TraefikOidc).audience)
+		assert.Equal(t, "https://explicit.example.com", mw.(*TraefikOidc).explicitAudience)
+	})
+
+	t.Run("no resource: audience defaults to clientID as before", func(t *testing.T) {
+		cfg := baseConfig()
+
+		mw, err := New(context.Background(), http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}), cfg, "test")
+		require.NoError(t, err)
+		t.Cleanup(func() { _ = mw.(*TraefikOidc).Close() })
+
+		assert.Equal(t, "test-client", mw.(*TraefikOidc).audience)
+	})
+}

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("[email protected]", 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:
@@ -382,6 +423,7 @@ type SessionManager struct {
 	cancel         context.CancelFunc
 	cookieDomain   string
 	cookiePrefix   string
+	cookiePath     string
 	sessionMaxAge  time.Duration
 	activeSessions int64
 	poolHits       int64
@@ -423,8 +465,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 +482,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)
 
@@ -851,7 +906,12 @@ func (sm *SessionManager) EnhanceSessionSecurity(options *sessions.Options, r *h
 	}
 
 	options.HttpOnly = true
-	options.Path = "/" // Ensure cookies are available on all paths for OAuth flow
+	// Use configured cookie path (default "/" for backward compatibility)
+	cookiePath := sm.cookiePath
+	if cookiePath == "" {
+		cookiePath = "/"
+	}
+	options.Path = cookiePath
 
 	if sm.cookieDomain != "" {
 		options.Domain = sm.cookieDomain

settings.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"net"
 	"net/http"
 	"net/url"
 	"os"
@@ -48,12 +49,33 @@ type Config struct {
 	RoleClaimName             string                           `json:"roleClaimName,omitempty"`
 	CookieDomain              string                           `json:"cookieDomain"`
 	OIDCEndSessionURL         string                           `json:"oidcEndSessionURL"`
+	// IntrospectionURL overrides the RFC 7662 token introspection endpoint.
+	// Set it when the IdP omits introspection_endpoint from discovery. It
+	// takes precedence over the discovered value.
+	IntrospectionURL      string            `json:"introspectionURL"`
 	Scopes                []string          `json:"scopes"`
 	AllowedRolesAndGroups []string          `json:"allowedRolesAndGroups"`
 	ExcludedURLs          []string          `json:"excludedURLs"`
 	AllowedUserDomains    []string          `json:"allowedUserDomains"`
 	AllowedUsers          []string          `json:"allowedUsers"`
 	Headers               []TemplatedHeader `json:"headers"`
+	// AllowedClaims extends the built-in claims whitelist that header value
+	// templates may emit. Add the exact claim name (e.g. "employee_id") to allow
+	// {{.Claims.employee_id}} / {{get .Claims "employee_id"}}. Applies to both
+	// template validation and the runtime get helper. Built-in claims (email,
+	// groups, roles, realm_access, ...) need not be listed.
+	AllowedClaims   []string          `json:"allowedClaims,omitempty"`
+	ExtraAuthParams map[string]string `json:"extraAuthParams,omitempty"`
+	// Resource declares an RFC 8707 resource indicator: an alternative to
+	// Audience for IdPs that support it. strictAudienceValidation applies
+	// the same way regardless of which of the two is set; only the request
+	// made to the IdP differs. Only a single resource is supported. See
+	// docs/RFC8707.md for exact request behavior, why multiple resources
+	// aren't, and current provider support. When Resource is set and
+	// Audience is unset, Audience defaults to Resource for access-token
+	// validation; this does not affect what is sent on the wire — see
+	// TraefikOidc.explicitAudience.
+	Resource                  string `json:"resource,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
@@ -76,6 +98,13 @@ type Config struct {
 	AllowPrivateIPAddresses   bool `json:"allowPrivateIPAddresses,omitempty"`
 	MinimalHeaders            bool `json:"minimalHeaders,omitempty"`
 	StripAuthCookies          bool `json:"stripAuthCookies,omitempty"`
+	// CookiePath restricts session cookies to a specific path prefix instead of "/".
+	// When traefikoidc protects some but not all paths on a domain, set this to the
+	// middleware's path prefix (e.g. "/app-protegido") so the browser does not send
+	// the OIDC session cookies to unprotected paths — preventing "Request Header
+	// Or Cookie Too Large" (431) errors on those paths.
+	// Default "/" (all paths, current behaviour).
+	CookiePath               string `json:"cookiePath,omitempty"`
 	EnableBackchannelLogout  bool   `json:"enableBackchannelLogout,omitempty"`
 	EnableFrontchannelLogout bool   `json:"enableFrontchannelLogout,omitempty"`
 	BackchannelLogoutURL     string `json:"backchannelLogoutURL,omitempty"`
@@ -93,6 +122,84 @@ type Config struct {
 	// providers. Enabling this in production is a security hole — prefer
 	// CACertPath/CACertPEM. Emits a loud warning at startup.
 	InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"`
+
+	// ClientAuthMethod selects the OAuth 2.0 client authentication method used
+	// at the token / revocation / introspection endpoints. Supported values:
+	//
+	//   - "client_secret_post" (default, current behavior): clientSecret is
+	//     sent in the request body alongside client_id.
+	//   - "private_key_jwt" (RFC 7523 §2.2): the plugin signs a short-lived JWT
+	//     assertion with a configured private key and sends it as
+	//     client_assertion. Use this when your IdP enforces short-lived secrets
+	//     or mandates secretless client auth (Entra ID, Okta, Auth0, Keycloak).
+	//
+	// When set to "private_key_jwt", clientSecret may be left empty and one of
+	// clientAssertionPrivateKey / clientAssertionKeyPath must be configured.
+	ClientAuthMethod string `json:"clientAuthMethod,omitempty"`
+
+	// ClientAssertionPrivateKey is an inline PEM-encoded private key used to
+	// sign client_assertion JWTs. Mutually exclusive with
+	// ClientAssertionKeyPath. Supports PKCS#8, PKCS#1 (RSA), and SEC1 (EC).
+	ClientAssertionPrivateKey string `json:"clientAssertionPrivateKey,omitempty"`
+
+	// ClientAssertionKeyPath is a filesystem path to a PEM-encoded private key,
+	// equivalent to ClientAssertionPrivateKey but loaded from disk.
+	ClientAssertionKeyPath string `json:"clientAssertionKeyPath,omitempty"`
+
+	// ClientAssertionKeyID is the JWK key id (kid) advertised in the JWS
+	// header. Required when using private_key_jwt so the IdP can locate the
+	// matching public key registered for the client.
+	ClientAssertionKeyID string `json:"clientAssertionKeyID,omitempty"`
+
+	// 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.
@@ -259,6 +366,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
@@ -323,8 +443,30 @@ func (c *Config) Validate() error {
 	if c.ClientID == "" {
 		return fmt.Errorf("clientID is required")
 	}
+	authMethod := c.ClientAuthMethod
+	if authMethod == "" {
+		authMethod = "client_secret_post"
+	}
+	switch authMethod {
+	case "client_secret_post", "client_secret_basic":
 		if c.ClientSecret == "" {
-		return fmt.Errorf("clientSecret is required")
+			return fmt.Errorf("clientSecret is required when clientAuthMethod is %q", authMethod)
+		}
+	case "private_key_jwt":
+		if c.ClientAssertionPrivateKey == "" && c.ClientAssertionKeyPath == "" {
+			return fmt.Errorf("clientAssertionPrivateKey or clientAssertionKeyPath is required when clientAuthMethod is private_key_jwt")
+		}
+		if c.ClientAssertionPrivateKey != "" && c.ClientAssertionKeyPath != "" {
+			return fmt.Errorf("only one of clientAssertionPrivateKey or clientAssertionKeyPath may be set")
+		}
+		if c.ClientAssertionKeyID == "" {
+			return fmt.Errorf("clientAssertionKeyID is required when clientAuthMethod is private_key_jwt")
+		}
+		if c.ClientAssertionAlg != "" && !isSupportedClientAssertionAlg(c.ClientAssertionAlg) {
+			return fmt.Errorf("clientAssertionAlg %q is not supported (use RS256/384/512, PS256/384/512, or ES256/384/512)", c.ClientAssertionAlg)
+		}
+	default:
+		return fmt.Errorf("clientAuthMethod %q is not supported", authMethod)
 	}
 
 	// Validate session encryption key
@@ -362,6 +504,10 @@ func (c *Config) Validate() error {
 	if c.OIDCEndSessionURL != "" && !isValidSecureURL(c.OIDCEndSessionURL) {
 		return fmt.Errorf("oidcEndSessionURL must be a valid HTTPS URL")
 	}
+	// Validate introspection URL if set
+	if c.IntrospectionURL != "" && !isValidSecureURL(c.IntrospectionURL) {
+		return fmt.Errorf("introspectionURL must be a valid HTTPS URL")
+	}
 
 	// Validate post-logout redirect URI if set
 	if c.PostLogoutRedirectURI != "" && c.PostLogoutRedirectURI != "/" {
@@ -408,6 +554,38 @@ func (c *Config) Validate() error {
 		}
 	}
 
+	// Validate the RFC 8707 resource indicator if specified
+	if c.Resource != "" {
+		resource := c.Resource
+		if len(resource) > 256 {
+			return fmt.Errorf("resource %q must not exceed 256 characters", resource)
+		}
+		if strings.Contains(resource, "*") {
+			return fmt.Errorf("resource %q must not contain wildcards", resource)
+		}
+		if strings.ContainsAny(resource, "\n\r\t\x00") {
+			return fmt.Errorf("resource %q contains invalid characters", resource)
+		}
+
+		// RFC 8707 §2: the resource parameter MUST NOT include a fragment.
+		if strings.Contains(resource, "#") {
+			return fmt.Errorf("resource %q must not contain a fragment", resource)
+		}
+
+		u, err := url.Parse(resource)
+		if err != nil || !u.IsAbs() {
+			return fmt.Errorf("resource %q must be an absolute URI", resource)
+		}
+
+		// Enforce HTTPS (loopback HTTP permitted) for http/https resources;
+		// other absolute schemes (e.g. urn:) are accepted as-is.
+		if u.Scheme == "http" || u.Scheme == "https" {
+			if !isValidSecureURL(resource) {
+				return fmt.Errorf("resource %q must be a valid HTTPS URL", resource)
+			}
+		}
+	}
+
 	// Validate Redis configuration if provided
 	if c.Redis != nil && c.Redis.Enabled {
 		if err := c.Redis.Validate(); err != nil {
@@ -415,7 +593,9 @@ func (c *Config) Validate() error {
 		}
 	}
 
-	// Validate headers configuration for template security
+	// Validate headers configuration for template security. Header templates may
+	// emit the built-in claims plus any operator-configured AllowedClaims.
+	allowedClaims := claimsWhitelist(c.AllowedClaims)
 	for _, header := range c.Headers {
 		if header.Name == "" {
 			return fmt.Errorf("header name cannot be empty")
@@ -423,8 +603,20 @@ func (c *Config) Validate() error {
 		if header.Value == "" {
 			return fmt.Errorf("header value template cannot be empty")
 		}
-		if !strings.Contains(header.Value, "{{") || !strings.Contains(header.Value, "}}") {
-			return fmt.Errorf("header value '%s' does not appear to be a valid template (missing {{ }})", header.Value)
+		hasOpen := strings.Contains(header.Value, "{{")
+		hasClose := strings.Contains(header.Value, "}}")
+		if hasOpen != hasClose {
+			return fmt.Errorf("header value '%s' has unbalanced template delimiters (need both {{ and }})", header.Value)
+		}
+		if !hasOpen {
+			// Static/literal header value with no template actions (e.g. a shared
+			// proxy secret or a constant marker). Allowed as-is — it worked before
+			// the constructor started calling Validate() (issue #149). Reject only
+			// header-injection characters; the rendered value is emitted verbatim.
+			if strings.ContainsAny(header.Value, "\r\n\x00") {
+				return fmt.Errorf("header value for '%s' contains invalid characters (CR/LF/NUL)", header.Name)
+			}
+			continue
 		}
 
 		// Provide more helpful guidance for common template errors BEFORE security validation
@@ -442,7 +634,7 @@ func (c *Config) Validate() error {
 		}
 
 		// Validate template syntax and security
-		if err := validateTemplateSecure(header.Value); err != nil {
+		if err := validateTemplateSecure(header.Value, allowedClaims); err != nil {
 			return fmt.Errorf("header template '%s' failed security validation: %w", header.Value, err)
 		}
 	}
@@ -450,115 +642,12 @@ func (c *Config) Validate() error {
 	return nil
 }
 
-// validateTemplateSecure validates template expressions for security vulnerabilities.
-// It checks for dangerous template patterns that could lead to code execution or data leaks
-// while allowing safe custom functions for field access and default values.
-func validateTemplateSecure(templateStr string) error {
-	// Allow our specific safe custom functions
-	// These are added specifically to handle missing fields safely (issue #60)
-	safeCustomFunctions := []string{
-		"{{get ",     // Safe map access function
-		"{{default ", // Safe default value function
-	}
-
-	// Check if template uses safe custom functions
-	usesSafeFunctions := false
-	for _, safeFn := range safeCustomFunctions {
-		if strings.Contains(templateStr, safeFn) {
-			usesSafeFunctions = true
-			// These functions are explicitly allowed for safe field access
-		}
-	}
-
-	// Check for dangerous template functions and patterns
-	// Skip certain checks if using our safe functions
-	dangerousPatterns := []string{
-		"{{call",     // Function calls (except our safe ones)
-		"{{range",    // Range over arbitrary data
-		"{{define",   // Template definitions
-		"{{template", // Template inclusions
-		"{{block",    // Block definitions
-		"{{/*",       // Comments that could hide malicious code
-		"{{-",        // Trim whitespace (could be used to obfuscate)
-		"-}}",        // Trim whitespace (could be used to obfuscate)
-		"{{printf",   // Printf functions
-		"{{print",    // Print functions (but not our safe ones)
-		"{{println",  // Println functions
-		"{{html",     // HTML functions
-		"{{js",       // JavaScript functions
-		"{{urlquery", // URL query functions
-		"{{index",    // Index access to arbitrary data
-		"{{slice",    // Slice operations
-		"{{len",      // Length operations on arbitrary data
-		"{{eq",       // Comparison operations
-		"{{ne",       // Comparison operations
-		"{{lt",       // Comparison operations
-		"{{le",       // Comparison operations
-		"{{gt",       // Comparison operations
-		"{{ge",       // Comparison operations
-		"{{and",      // Logical operations
-		"{{or",       // Logical operations
-		"{{not",      // Logical operations
-	}
-
-	// Allow 'with' for safe conditional access
-	if !strings.Contains(templateStr, "{{with .Claims") {
-		dangerousPatterns = append(dangerousPatterns, "{{with")
-	}
-
-	templateLower := strings.ToLower(templateStr)
-	for _, pattern := range dangerousPatterns {
-		// Skip check if it's one of our safe functions
-		if usesSafeFunctions && (pattern == "{{call" || pattern == "{{print") {
-			// Allow these if we're using safe functions
-			continue
-		}
-
-		// Special handling for comparison operators to avoid false positives with "get" and "default"
-		if pattern == "{{ge" && (strings.Contains(templateStr, "{{get ") || strings.Contains(templateStr, "{{default ")) {
-			// Skip {{ge check if we're using the safe {{get or {{default functions
-			continue
-		}
-
-		// Skip {{de checks if using {{default
-		if pattern == "{{define" && strings.Contains(templateStr, "{{default ") {
-			continue
-		}
-
-		if strings.Contains(templateLower, strings.ToLower(pattern)) {
-			return fmt.Errorf("dangerous template pattern detected: %s", pattern)
-		}
-	}
-
-	// Validate template variables against whitelist
-	allowedPatterns := []string{
-		"{{.AccessToken}}",
-		"{{.IdToken}}",
-		"{{.RefreshToken}}",
-		"{{.Claims.",
-		"{{get ",     // Safe custom function
-		"{{default ", // Safe custom function
-		"{{with ",    // Safe conditional (when used with Claims)
-	}
-
-	// Check if template contains only allowed patterns
-	hasAllowedPattern := false
-	for _, pattern := range allowedPatterns {
-		if strings.Contains(templateStr, pattern) {
-			hasAllowedPattern = true
-			break
-		}
-	}
-
-	if !hasAllowedPattern {
-		return fmt.Errorf("template must use only allowed variables: AccessToken, IdToken, RefreshToken, Claims.*, or safe functions (get, default, with)")
-	}
-
-	// Validate claims access patterns
-	if strings.Contains(templateStr, "{{.Claims.") {
-		// Simple validation - ensure claims access is to known safe fields
-		// This list includes standard OIDC claims and common provider-specific claims
-		safeClaimsFields := map[string]bool{
+// safeClaimsFields is the single source of truth for which claim fields a header
+// template may emit. It gates both static validation (validateTemplateSecure)
+// and the runtime `get` function (main.go funcMap), so a claim can never be
+// forwarded via `get`/`index` that a direct {{.Claims.x}} reference would reject.
+// Includes standard OIDC claims and common provider-specific claims.
+var safeClaimsFields = map[string]bool{
 	// Standard OIDC claims
 	"email":              true,
 	"name":               true,
@@ -591,50 +680,13 @@ func validateTemplateSecure(templateStr string) error {
 	"phone_number":   true, // Contact info
 	"email_verified": true, // Email verification status
 	"updated_at":     true, // Last update time
-		}
-
-		// Extract field names from Claims access
-		start := strings.Index(templateStr, "{{.Claims.")
-		for start != -1 {
-			end := strings.Index(templateStr[start:], "}}")
-			if end == -1 {
-				return fmt.Errorf("malformed Claims template syntax")
-			}
-
-			// Extract the content between "{{.Claims." and "}}"
-			// start+10 skips "{{.Claims." and start+end is the position of "}}"
-			claimsContent := templateStr[start+10 : start+end]
-
-			// Get the field name (first part before any dots)
-			fieldName := strings.Split(claimsContent, ".")[0]
-
-			if !safeClaimsFields[fieldName] {
-				return fmt.Errorf("access to Claims.%s is not allowed for security reasons", fieldName)
-			}
-
-			// Search for next occurrence
-			nextStart := strings.Index(templateStr[start+end+2:], "{{.Claims.")
-			if nextStart != -1 {
-				start = start + end + 2 + nextStart
-			} else {
-				start = -1
-			}
-		}
-	}
-
-	// Prevent code injection through template syntax
-	if strings.Contains(templateStr, "{{") && strings.Contains(templateStr, "}}") {
-		// Count opening and closing braces
-		openCount := strings.Count(templateStr, "{{")
-		closeCount := strings.Count(templateStr, "}}")
-		if openCount != closeCount {
-			return fmt.Errorf("unbalanced template braces")
-		}
-	}
-
-	return nil
 }
 
+// validateTemplateSecure validates template expressions for security vulnerabilities.
+// It checks for dangerous template patterns that could lead to code execution or data leaks
+// while allowing safe custom functions for field access and default values.
+// validateTemplateSecure lives in template_validation.go (AST-based validation).
+
 // isValidSecureURL checks if a given string represents a valid, absolute HTTPS URL.
 // It uses url.Parse and checks for a nil error, an "https" scheme, and a non-empty host.
 //
@@ -648,7 +700,44 @@ 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
+}
+
+// isLoopbackProviderURL reports whether providerURL's host is loopback
+// (localhost or a loopback IP literal). Used at construction time to derive
+// allowLoopbackHosts, so local-development providers are not blocked by
+// validateHost's outbound URL checks.
+func isLoopbackProviderURL(providerURL string) bool {
+	pu, err := url.Parse(providerURL)
+	if err != nil {
+		return false
+	}
+	return isLoopbackHost(pu.Hostname())
 }
 
 // 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
@@ -502,6 +516,9 @@ func (p *GoroutinePool) Shutdown(ctx context.Context) error {
 // GenericCache provides a simple cache implementation for testing
 type GenericCache struct {
 	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
@@ -510,11 +527,19 @@ type GenericCache struct {
 
 // 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{}),
+		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

@@ -299,6 +299,9 @@ func TestContextAwareGoroutineManagement(t *testing.T) {
 			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
@@ -435,6 +438,9 @@ func TestContextAwareGoroutineManagement(t *testing.T) {
 				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))
@@ -598,6 +604,9 @@ func TestBackwardCompatibility(t *testing.T) {
 			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")
@@ -620,6 +629,9 @@ func TestBackwardCompatibility(t *testing.T) {
 			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")

template_validation.go

@@ -0,0 +1,362 @@
+package traefikoidc
+
+import (
+	"fmt"
+	"strings"
+	"text/template/parse"
+)
+
+// allowedRootTokenFields are the non-Claims values a header template may render
+// directly from the root data context. Both ID-token spellings are accepted
+// (templateData carries IDToken and IdToken).
+var allowedRootTokenFields = map[string]bool{
+	"AccessToken":  true,
+	"IdToken":      true,
+	"IDToken":      true,
+	"RefreshToken": true,
+}
+
+// validateTemplateParseFuncs is the function set the parser is told about. Only
+// get/default exist; every other identifier used as a command (printf, call,
+// index, js, ...) then fails to parse and is rejected — no blocklist needed.
+var validateTemplateParseFuncs = map[string]any{
+	"get":     struct{}{},
+	"default": struct{}{},
+}
+
+// claimsWhitelist returns the effective set of claim field names a header
+// template may emit: the built-in safeClaimsFields plus any operator-configured
+// extras (config.AllowedClaims). Blank/whitespace extras are ignored. The result
+// gates BOTH static validation and the runtime get helper so the two never drift.
+func claimsWhitelist(extra []string) map[string]bool {
+	m := make(map[string]bool, len(safeClaimsFields)+len(extra))
+	for k := range safeClaimsFields {
+		m[k] = true
+	}
+	for _, c := range extra {
+		if c = strings.TrimSpace(c); c != "" {
+			m[c] = true
+		}
+	}
+	return m
+}
+
+// templateValidator walks a parsed header template against a specific claims
+// whitelist (built-in + operator-configured). Holding the set on the walker
+// keeps it out of every method signature.
+type templateValidator struct {
+	allowed map[string]bool
+}
+
+// validateTemplateSecure parses a header value template and walks its AST,
+// permitting ONLY: literal text; the whitelisted root token fields; whitelisted
+// .Claims.<field> access; range/with over a whitelisted .Claims.<field>; the
+// safe get/default helpers; and {{if}} control flow. Everything else — bare
+// {{.}}/{{$}} (whole-root dump), bare {{.Claims}} (whole-map dump), non-
+// whitelisted claims, unknown functions, define/template/block — is rejected.
+//
+// allowed is the effective claim whitelist (see claimsWhitelist); a nil set
+// falls back to the built-in safeClaimsFields.
+//
+// Parsing (not substring matching) is what makes this sound: the parser resolves
+// whitespace, comments and the meaning of "." per scope, so obfuscation and the
+// "whitelisted decoy + bare-map render" bypass class cannot slip through.
+func validateTemplateSecure(templateStr string, allowed map[string]bool) error {
+	if allowed == nil {
+		allowed = safeClaimsFields
+	}
+	trees, err := parse.Parse("headerTemplate", templateStr, "{{", "}}", validateTemplateParseFuncs)
+	if err != nil {
+		return fmt.Errorf("invalid template: %w", err)
+	}
+	// {{define}}/{{block}} produce additional named trees; a header value template
+	// must be a single anonymous template, so reject anything that defines more.
+	if len(trees) != 1 {
+		return fmt.Errorf("template definitions ({{define}}/{{block}}) are not allowed")
+	}
+	tree, ok := trees["headerTemplate"]
+	if !ok || tree.Root == nil {
+		return fmt.Errorf("invalid template: empty parse tree")
+	}
+	v := &templateValidator{allowed: allowed}
+	// dotIsRoot=true: "." is the whole data context at the top level. Inside a
+	// range/with over a claims field it rebinds to that (already-whitelisted)
+	// element, so relative access there is safe.
+	return v.walkNode(tree.Root, true)
+}
+
+// walkNode validates a node and its children. dotIsRoot reports whether "."
+// currently refers to the root data context (true) or to a whitelisted claim
+// element rebound by an enclosing range/with (false).
+func (v *templateValidator) walkNode(n parse.Node, dotIsRoot bool) error {
+	switch node := n.(type) {
+	case nil:
+		return nil
+	case *parse.ListNode:
+		if node == nil {
+			return nil
+		}
+		for _, child := range node.Nodes {
+			if err := v.walkNode(child, dotIsRoot); err != nil {
+				return err
+			}
+		}
+		return nil
+	case *parse.TextNode:
+		return nil
+	case *parse.ActionNode:
+		return v.validatePipe(node.Pipe, dotIsRoot)
+	case *parse.IfNode:
+		return v.walkBranch(node.Pipe, node.List, node.ElseList, dotIsRoot, dotIsRoot)
+	case *parse.WithNode:
+		// with rebinds "." to the target inside its body; the target must be a
+		// whitelisted claim, so the body runs with dotIsRoot=false.
+		if err := v.validateClaimSelector(node.Pipe, dotIsRoot, "with"); err != nil {
+			return err
+		}
+		return v.walkBranch(nil, node.List, node.ElseList, false, dotIsRoot)
+	case *parse.RangeNode:
+		// range iterates the target and rebinds "." to each element; the target
+		// must be a whitelisted claim collection, so the body is dotIsRoot=false.
+		if err := v.validateClaimSelector(node.Pipe, dotIsRoot, "range"); err != nil {
+			return err
+		}
+		return v.walkBranch(nil, node.List, node.ElseList, false, dotIsRoot)
+	case *parse.TemplateNode:
+		return fmt.Errorf("template inclusion is not allowed")
+	default:
+		return fmt.Errorf("unsupported template construct: %s", n.String())
+	}
+}
+
+// walkBranch validates an if/with/range: an optional condition pipe (evaluated
+// in the outer scope), the body (bodyDotIsRoot), and the else branch (outer
+// scope). For with/range the condition pipe is validated by the caller and
+// condPipe is nil here.
+func (v *templateValidator) walkBranch(condPipe *parse.PipeNode, body, elseList *parse.ListNode, bodyDotIsRoot, outerDotIsRoot bool) error {
+	if condPipe != nil {
+		if err := v.validatePipe(condPipe, outerDotIsRoot); err != nil {
+			return err
+		}
+	}
+	if err := v.walkNode(body, bodyDotIsRoot); err != nil {
+		return err
+	}
+	if elseList != nil {
+		if err := v.walkNode(elseList, outerDotIsRoot); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// validatePipe validates every command in a pipeline, including the right-hand
+// side of any variable declaration ($x := ...). Declared vars therefore always
+// hold already-validated values, so later references to them are safe.
+func (v *templateValidator) validatePipe(pipe *parse.PipeNode, dotIsRoot bool) error {
+	if pipe == nil {
+		return nil
+	}
+	for _, cmd := range pipe.Cmds {
+		if err := v.validateCommand(cmd, dotIsRoot); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// validateCommand validates a single command (one stage of a pipeline). The
+// first argument may be the get/default function; the rest, and every argument
+// of a non-function command, must be a safe value expression.
+func (v *templateValidator) validateCommand(cmd *parse.CommandNode, dotIsRoot bool) error {
+	if cmd == nil || len(cmd.Args) == 0 {
+		return nil
+	}
+	if id, ok := cmd.Args[0].(*parse.IdentifierNode); ok {
+		return v.validateFunctionCall(id.Ident, cmd.Args[1:], dotIsRoot)
+	}
+	for _, arg := range cmd.Args {
+		if err := v.validateValue(arg, dotIsRoot); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// validateFunctionCall allows only get/default. get's map argument must be a
+// claims reference (never the root) and default's arguments are validated as
+// values; the runtime get additionally enforces the key whitelist.
+func (v *templateValidator) validateFunctionCall(name string, args []parse.Node, dotIsRoot bool) error {
+	switch name {
+	case "default":
+		for _, arg := range args {
+			if err := v.validateValue(arg, dotIsRoot); err != nil {
+				return err
+			}
+		}
+		return nil
+	case "get":
+		if len(args) < 1 {
+			return fmt.Errorf("get requires a map argument")
+		}
+		// The map argument must reference .Claims, never the root map (which
+		// would expose tokens / the whole Claims map). Remaining args (the key,
+		// possibly a pipeline) are validated as values.
+		if err := v.validateClaimsReference(args[0], dotIsRoot); err != nil {
+			return fmt.Errorf("get is only allowed on .Claims: %w", err)
+		}
+		// A literal key must be whitelisted (matches direct .Claims.<field>
+		// strictness); a dynamic key is enforced by the runtime get.
+		if len(args) >= 2 {
+			if key, ok := args[1].(*parse.StringNode); ok && !v.allowed[key.Text] {
+				return fmt.Errorf("access to Claims.%s is not allowed for security reasons", key.Text)
+			}
+		}
+		for _, arg := range args[1:] {
+			if err := v.validateValue(arg, dotIsRoot); err != nil {
+				return err
+			}
+		}
+		return nil
+	default:
+		return fmt.Errorf("function %q is not allowed in header templates", name)
+	}
+}
+
+// validateValue validates an expression that may be rendered or passed as an
+// argument. It rejects anything resolving to the whole root or the whole Claims
+// map, and any non-whitelisted claim.
+func (v *templateValidator) validateValue(node parse.Node, dotIsRoot bool) error {
+	switch val := node.(type) {
+	case *parse.StringNode, *parse.NumberNode, *parse.BoolNode, *parse.NilNode:
+		return nil
+	case *parse.DotNode:
+		// "." is the whole root at the top level (dumps tokens + all claims); it
+		// is a single already-whitelisted claim element inside a range/with body.
+		if dotIsRoot {
+			return fmt.Errorf("rendering the whole data context ({{.}}) is not allowed")
+		}
+		return nil
+	case *parse.FieldNode:
+		return v.validateFieldAccess(val.Ident, dotIsRoot)
+	case *parse.VariableNode:
+		return v.validateVariableAccess(val.Ident)
+	case *parse.PipeNode:
+		return v.validatePipe(val, dotIsRoot)
+	case *parse.ChainNode:
+		// (base).Field.Field — the field chain only narrows access, so validating
+		// the base value is sufficient.
+		return v.validateValue(val.Node, dotIsRoot)
+	default:
+		return fmt.Errorf("unsupported template expression: %s", node.String())
+	}
+}
+
+// validateFieldAccess validates a dot-relative field access ".A.B.C" given
+// whether "." is the root. In an element scope (dotIsRoot=false) the element is
+// already a whitelisted claim, so any sub-field access is safe.
+func (v *templateValidator) validateFieldAccess(idents []string, dotIsRoot bool) error {
+	if !dotIsRoot {
+		return nil
+	}
+	if len(idents) == 0 {
+		return fmt.Errorf("rendering the whole data context is not allowed")
+	}
+	root := idents[0]
+	if allowedRootTokenFields[root] {
+		return nil
+	}
+	if root == "Claims" {
+		if len(idents) < 2 {
+			return fmt.Errorf("rendering the whole Claims map ({{.Claims}}) is not allowed")
+		}
+		if !v.allowed[idents[1]] {
+			return fmt.Errorf("access to Claims.%s is not allowed for security reasons", idents[1])
+		}
+		// By design, only the top-level claim is whitelisted; deeper subfields
+		// (idents[2:]) of a map-valued whitelisted claim such as realm_access /
+		// resource_access are forwarded as-is. Whitelisting a map claim means
+		// opting into its nested contents, and the documented Keycloak pattern
+		// {{with .Claims.realm_access}}{{.roles}}{{end}} relies on it; nested
+		// provider keys can't be enumerated to whitelist individually.
+		return nil
+	}
+	return fmt.Errorf("access to .%s is not allowed in header templates", root)
+}
+
+// validateVariableAccess validates a $-variable reference. The bare root ("$"
+// and "$.x") is treated as a root field access; a named range/with/declaration
+// variable holds an already-validated value, so it and its sub-fields are safe.
+func (v *templateValidator) validateVariableAccess(idents []string) error {
+	if len(idents) == 0 {
+		return nil
+	}
+	if idents[0] == "$" {
+		// "$" is the root: "$" alone dumps everything; "$.Claims.email" is a
+		// root-absolute field access validated like ".Claims.email".
+		if len(idents) == 1 {
+			return fmt.Errorf("rendering the whole data context ({{$}}) is not allowed")
+		}
+		return v.validateFieldAccess(idents[1:], true)
+	}
+	// Named variable ($e, $i, $x): holds a validated element/index/value.
+	return nil
+}
+
+// validateClaimsReference requires a node to reference .Claims (or $.Claims),
+// never the root map — used for get's map argument, whose key is separately
+// enforced against the whitelist at render time.
+func (v *templateValidator) validateClaimsReference(node parse.Node, dotIsRoot bool) error {
+	switch ref := node.(type) {
+	case *parse.FieldNode:
+		if dotIsRoot && len(ref.Ident) >= 1 && ref.Ident[0] == "Claims" {
+			if len(ref.Ident) >= 2 && !v.allowed[ref.Ident[1]] {
+				return fmt.Errorf("access to Claims.%s is not allowed for security reasons", ref.Ident[1])
+			}
+			return nil
+		}
+	case *parse.VariableNode:
+		if len(ref.Ident) >= 2 && ref.Ident[0] == "$" && ref.Ident[1] == "Claims" {
+			if len(ref.Ident) >= 3 && !v.allowed[ref.Ident[2]] {
+				return fmt.Errorf("access to Claims.%s is not allowed for security reasons", ref.Ident[2])
+			}
+			return nil
+		}
+	}
+	return fmt.Errorf("expected a .Claims reference")
+}
+
+// validateClaimSelector validates the target of a range/with: it must iterate a
+// specific whitelisted claim field (.Claims.<field> or $.Claims.<field>), never
+// the bare Claims map or any non-claims value.
+func (v *templateValidator) validateClaimSelector(pipe *parse.PipeNode, dotIsRoot bool, kind string) error {
+	if pipe == nil || len(pipe.Cmds) == 0 {
+		return fmt.Errorf("%s requires a .Claims.<field> target", kind)
+	}
+	cmd := pipe.Cmds[len(pipe.Cmds)-1]
+	if len(cmd.Args) == 0 {
+		return fmt.Errorf("%s requires a .Claims.<field> target", kind)
+	}
+	target := cmd.Args[0]
+	if err := v.validateClaimField(target, dotIsRoot); err != nil {
+		return fmt.Errorf("%s is only allowed over a whitelisted claims field, e.g. {{range $i, $e := .Claims.groups}} or {{with .Claims.email}}: %w", kind, err)
+	}
+	return nil
+}
+
+// validateClaimField requires a node to be a specific whitelisted claim field
+// (.Claims.<whitelisted> or $.Claims.<whitelisted>) — stricter than
+// validateClaimsReference, which also permits the bare .Claims map for get.
+func (v *templateValidator) validateClaimField(node parse.Node, dotIsRoot bool) error {
+	switch field := node.(type) {
+	case *parse.FieldNode:
+		if dotIsRoot && len(field.Ident) >= 2 && field.Ident[0] == "Claims" && v.allowed[field.Ident[1]] {
+			return nil
+		}
+	case *parse.VariableNode:
+		if len(field.Ident) >= 3 && field.Ident[0] == "$" && field.Ident[1] == "Claims" && v.allowed[field.Ident[2]] {
+			return nil
+		}
+	}
+	return fmt.Errorf("not a whitelisted .Claims.<field>")
+}

token_introspection.go

@@ -21,7 +21,10 @@ type IntrospectionResponse struct {
 	Username  string `json:"username,omitempty"`
 	TokenType string `json:"token_type,omitempty"`
 	Sub       string `json:"sub,omitempty"`
-	Aud       string `json:"aud,omitempty"`
+	// 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"`
@@ -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,8 +372,18 @@ func (t *TraefikOidc) VerifyJWTSignatureAndClaims(jwt *JWT, token string) error
 
 	if err := verifySignatureWithKey(token, pubKey, alg); err != nil {
 		if !t.suppressDiagnosticLogs {
+			// 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)
 	}
 
@@ -660,11 +701,33 @@ func (t *TraefikOidc) RevokeTokenWithProvider(token, tokenType string) error {
 	}
 	t.logger.Debugf("Attempting to revoke token (type: %s) with provider at %s", tokenType, revocationURL)
 
+	// Read tokenURL with RLock — used as audience for private_key_jwt (RFC 7523 §3).
+	t.metadataMu.RLock()
+	tokenURL := t.tokenURL
+	t.metadataMu.RUnlock()
+
 	data := url.Values{
 		"token":           {token},
 		"token_type_hint": {tokenType},
-		"client_id":       {t.clientID},
-		"client_secret":   {t.clientSecret},
+	}
+	// client_id is sent in the body for every method except client_secret_basic,
+	// where it is carried in the Authorization header per RFC 6749 §2.3.1.
+	if t.clientAuthMethod != "client_secret_basic" || t.clientAssertion != nil {
+		data.Set("client_id", t.clientID)
+	}
+
+	useBasicAuth := false
+	if t.clientAssertion != nil {
+		assertion, err := t.clientAssertion.Sign(tokenURL, t.clientID)
+		if err != nil {
+			return fmt.Errorf("failed to sign client assertion: %w", err)
+		}
+		data.Set("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer")
+		data.Set("client_assertion", assertion)
+	} else if t.clientAuthMethod == "client_secret_basic" {
+		useBasicAuth = true
+	} else {
+		data.Set("client_secret", t.clientSecret)
 	}
 
 	req, err := http.NewRequestWithContext(context.Background(), "POST", revocationURL, strings.NewReader(data.Encode()))
@@ -674,6 +737,9 @@ func (t *TraefikOidc) RevokeTokenWithProvider(token, tokenType string) error {
 
 	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
 	req.Header.Set("Accept", "application/json")
+	if useBasicAuth {
+		setOAuthBasicAuth(req, t.clientID, t.clientSecret)
+	}
 
 	// Send the request with circuit breaker protection if available
 	var resp *http.Response
@@ -760,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:
@@ -775,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": "[email protected]",
-		"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"] != "[email protected]" {
-		t.Errorf("Expected email '[email protected]', 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
@@ -119,27 +158,54 @@ type TraefikOidc struct {
 	audience                     string
 	clientID                     string
 	clientSecret                 string
+	clientAuthMethod             string
+	clientAssertion              *ClientAssertionSigner
 	registrationURL              string
+	// configRevocationURL, configEndSessionURL, and configIntrospectionURL
+	// hold operator-configured endpoint overrides (Config.RevocationURL,
+	// Config.OIDCEndSessionURL, Config.IntrospectionURL). They are set once at
+	// construction and never mutated afterwards, so they are read lock-free,
+	// the same contract as providerURL, which updateMetadataEndpoints already
+	// reads unlocked. A manual override always wins over discovery; an empty
+	// string means use the discovered value.
+	configRevocationURL    string
+	configEndSessionURL    string
+	configIntrospectionURL string
 	backchannelLogoutPath  string
 	frontchannelLogoutPath string
 	scopesSupported        []string
 	scopes                 []string
+	extraAuthParams        map[string]string
+	// resource holds the RFC 8707 resource indicator from Config.Resource
+	// (Config.Validate() already guarantees it is either empty or a
+	// non-empty absolute URI). Sent as the `resource` param on the
+	// authorization request and on both the authorization_code and
+	// refresh_token grants.
+	resource string
+	// explicitAudience mirrors Config.Audience verbatim, with no
+	// resource- or clientID-based defaulting applied. audience (below) does
+	// carry that defaulting, for token-validation purposes; explicitAudience
+	// exists so buildAuthURL can decide whether to send the non-standard
+	// `audience` request parameter without that default leaking onto the
+	// wire.
+	explicitAudience          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
+	// allowLoopbackHosts permits loopback/localhost hosts in outbound URL
+	// validation (validateHost). Derived at construction time from a loopback
+	// providerURL (local development), never operator-set directly. Mirrors
+	// the allowLoopback derivation in updateMetadataEndpoints.
+	allowLoopbackHosts       bool
 	disableReplayDetection   bool
 	allowOpaqueTokens        bool
 	strictAudienceValidation bool
@@ -147,4 +213,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 {
+	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 {
+	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.
@@ -46,13 +71,21 @@ func (t *TraefikOidc) buildAuthURL(redirectURL, state, nonce, codeChallenge stri
 	params.Set("state", state)
 	params.Set("nonce", nonce)
 
-	// Add audience parameter for custom API audiences (e.g., Auth0 APIs)
-	// This allows access tokens to have the correct audience claim
-	// Only add if audience is configured and different from client_id
-	// ID tokens will always have aud=client_id per OIDC spec
-	if t.audience != "" && t.audience != t.clientID {
-		params.Set("audience", t.audience)
-		t.logger.Debugf("Adding audience parameter to authorize URL: %s", t.audience)
+	// Non-standard `audience` param for custom API audiences (e.g. Auth0).
+	// Keyed on explicitAudience, not audience — see TraefikOidc.explicitAudience.
+	// Only add if configured and different from client_id; ID tokens always
+	// have aud=client_id per OIDC spec.
+	if t.explicitAudience != "" && t.explicitAudience != t.clientID {
+		params.Set("audience", t.explicitAudience)
+		t.logger.Debugf("Adding audience parameter to authorize URL: %s", t.explicitAudience)
+	}
+
+	// RFC 8707 resource indicator — see Config.Resource. Runs before
+	// extraAuthParams so an operator-configured "resource" key there cannot
+	// override or duplicate it.
+	if t.resource != "" {
+		params.Set("resource", t.resource)
+		t.logger.Debugf("Adding resource parameter to authorize URL: %s", t.resource)
 	}
 
 	if t.enablePKCE && codeChallenge != "" {
@@ -146,6 +179,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 +321,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.
@@ -293,8 +398,15 @@ func (t *TraefikOidc) validateHost(host string) error {
 
 	ip := net.ParseIP(hostname)
 	if ip != nil {
-		// Always block loopback, link-local, and multicast addresses
-		if ip.IsLoopback() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() {
+		// Loopback addresses are blocked by default, but allowed when the
+		// plugin was constructed with a loopback providerURL (local
+		// development) — see allowLoopbackHosts.
+		if ip.IsLoopback() && !t.allowLoopbackHosts {
+			return fmt.Errorf("access to loopback/link-local IP addresses is not allowed: %s", ip.String())
+		}
+
+		// Link-local and multicast addresses are always blocked.
+		if ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() {
 			return fmt.Errorf("access to loopback/link-local IP addresses is not allowed: %s", ip.String())
 		}
 
@@ -308,16 +420,22 @@ func (t *TraefikOidc) validateHost(host string) error {
 		}
 	}
 
-	dangerousHosts := map[string]bool{
-		"localhost":                true,
-		"127.0.0.1":                true,
-		"::1":                      true,
+	// Always blocked regardless of allowLoopbackHosts: these have no IP-branch
+	// backstop (net.ParseIP returns nil for hostnames), so bypassing them
+	// would open an SSRF path to the cloud metadata service.
+	alwaysDangerousHosts := map[string]bool{
 		"0.0.0.0":                  true,
 		"169.254.169.254":          true,
 		"metadata.google.internal": true,
 	}
 
-	if dangerousHosts[strings.ToLower(hostname)] {
+	if alwaysDangerousHosts[strings.ToLower(hostname)] {
+		return fmt.Errorf("access to dangerous hostname is not allowed: %s", hostname)
+	}
+
+	// localhost/loopback literals are blocked unless allowLoopbackHosts
+	// permits them (see allowLoopbackHosts doc comment on TraefikOidc).
+	if !t.allowLoopbackHosts && isLoopbackHost(hostname) {
 		return fmt.Errorf("access to dangerous hostname is not allowed: %s", hostname)
 	}
 

url_helpers_ultra_test.go

@@ -407,7 +407,12 @@ func TestValidateURLEdgeCasesComprehensive(t *testing.T) {
 func TestBuildAuthURLAudienceParameter(t *testing.T) {
 	t.Run("audience added when different from client_id", func(t *testing.T) {
 		middleware := createMinimalMiddleware()
+		// buildAuthURL sources the outbound `audience` param from
+		// explicitAudience (an explicitly configured Config.Audience), not
+		// from audience (the effective validation audience, which can also
+		// carry a Resource-derived default that must never reach the wire).
 		middleware.audience = "https://api.example.com"
+		middleware.explicitAudience = "https://api.example.com"
 
 		authURL := middleware.buildAuthURL(
 			"https://app.com/callback",
@@ -422,6 +427,7 @@ func TestBuildAuthURLAudienceParameter(t *testing.T) {
 	t.Run("audience not added when empty", func(t *testing.T) {
 		middleware := createMinimalMiddleware()
 		middleware.audience = ""
+		middleware.explicitAudience = ""
 
 		authURL := middleware.buildAuthURL(
 			"https://app.com/callback",
@@ -436,6 +442,7 @@ func TestBuildAuthURLAudienceParameter(t *testing.T) {
 	t.Run("audience not added when equal to client_id", func(t *testing.T) {
 		middleware := createMinimalMiddleware()
 		middleware.audience = middleware.clientID
+		middleware.explicitAudience = middleware.clientID
 
 		authURL := middleware.buildAuthURL(
 			"https://app.com/callback",
@@ -554,3 +561,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))
@@ -273,19 +291,19 @@ func (t *TraefikOidc) Close() error {
 		}
 
 		if t.httpClient != nil {
-			if transport, ok := t.httpClient.Transport.(*http.Transport); ok {
+			if transport, ok := t.httpClient.Transport.(*http.Transport); ok && transport != nil {
 				transport.CloseIdleConnections()
 				t.safeLogDebug("HTTP client idle connections closed")
 			}
 		}
 
 		if t.tokenHTTPClient != nil {
-			if transport, ok := t.tokenHTTPClient.Transport.(*http.Transport); ok {
+			if transport, ok := t.tokenHTTPClient.Transport.(*http.Transport); ok && transport != nil {
 				transport.CloseIdleConnections()
 				t.safeLogDebug("Token HTTP client idle connections closed")
 			}
-			if t.tokenHTTPClient.Transport != t.httpClient.Transport {
-				if transport, ok := t.tokenHTTPClient.Transport.(*http.Transport); ok {
+			if t.httpClient == nil || t.tokenHTTPClient.Transport != t.httpClient.Transport {
+				if transport, ok := t.tokenHTTPClient.Transport.(*http.Transport); ok && transport != nil {
 					transport.CloseIdleConnections()
 					t.safeLogDebug("Token HTTP client transport closed (separate from main)")
 				}

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.36"

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