test(oidcgate): integration test with real middleware against mock IdP (#142)

- Add 'oidcgate' build entry (linux/darwin × amd64/arm64) to goreleaser.
- Add per-OS/arch tar.gz archives for the daemon binary.
- Add dockers + docker_manifests entries publishing
  ghcr.io/lukaszraczylo/oidcgate:vX.Y.Z (release tag), :vX.Y, :vX, :latest
  as multi-arch manifests (linux/amd64 + linux/arm64).
- Add cmd/oidcgate/Dockerfile (distroless static, nonroot user).
- Sign images with cosign keyless (docker_signs).
- Preserve existing source-only Traefik plugin archive via meta:true.
- Update README to advertise the published image.

.goreleaser.yaml

@@ -1,13 +1,41 @@
 version: 2
 
-# Traefik plugins are source-only - no binary builds
-# Traefik loads plugins via Yaegi interpreter at runtime
-builds:
-  - skip: true
+# Two release artefacts:
+#
+# 1. The Traefik plugin: source-only — Traefik loads it via the Yaegi
+#    interpreter from the source tarball published on GitHub releases.
+# 2. oidcgate: a standalone forward-auth daemon built from cmd/oidcgate.
+#    Shipped as both per-OS/arch binary archives AND a multi-arch Docker
+#    image at ghcr.io/lukaszraczylo/oidcgate, tagged to match the release.
+
+builds:
+  - id: oidcgate
+    main: ./cmd/oidcgate
+    binary: oidcgate
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+    goarch:
+      - amd64
+      - arm64
+    flags:
+      - -trimpath
+      - -buildvcs=false
+    ldflags:
+      - -s -w
+      - -X main.version={{.Version}}
+      - -X main.commit={{.ShortCommit}}
+      - -X main.date={{.Date}}
+    mod_timestamp: "{{ .CommitTimestamp }}"
 
-# Create source archive for GitHub releases
 archives:
-  - formats: [tar.gz]
+  # Source archive for the Traefik plugin path. meta:true → no binary
+  # builds attached; everything comes from `files:` below.
+  - id: source-plugin
+    meta: true
+    formats: [tar.gz]
     name_template: "{{ .ProjectName }}_v{{ .Version }}_source"
     files:
       - "*.go"
@@ -25,6 +53,93 @@ archives:
       - "!regression/**"
       - "!examples/**"
       - "!docs/**"
+      - "!cmd/**"
+
+  # Per-OS/arch binary archives for the oidcgate daemon.
+  - id: oidcgate
+    ids: [oidcgate]
+    formats: [tar.gz]
+    name_template: "oidcgate_v{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    files:
+      - LICENSE*
+      - README*
+      - src: docs/OIDCGATE.md
+        dst: docs/
+      - src: examples/oidcgate.yaml
+        dst: examples/
+
+# Build a Docker image per (linux, arch) combo. Tag suffixes are
+# combined into a single multi-arch manifest list below via
+# docker_manifests, so end users pull a single tag.
+dockers:
+  - id: oidcgate-amd64
+    ids: [oidcgate]
+    goos: linux
+    goarch: amd64
+    image_templates:
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-amd64"
+    use: buildx
+    dockerfile: cmd/oidcgate/Dockerfile
+    build_flag_templates:
+      - "--pull"
+      - "--platform=linux/amd64"
+      - "--label=org.opencontainers.image.title=oidcgate"
+      - "--label=org.opencontainers.image.description=Standalone OIDC forward-auth daemon for nginx/Caddy/Traefik/HAProxy/Envoy"
+      - "--label=org.opencontainers.image.version={{ .Version }}"
+      - "--label=org.opencontainers.image.revision={{ .FullCommit }}"
+      - "--label=org.opencontainers.image.created={{ .Date }}"
+      - "--label=org.opencontainers.image.source=https://github.com/lukaszraczylo/traefikoidc"
+      - "--label=org.opencontainers.image.url=https://github.com/lukaszraczylo/traefikoidc"
+      - "--label=org.opencontainers.image.documentation=https://github.com/lukaszraczylo/traefikoidc/blob/main/docs/OIDCGATE.md"
+      - "--label=org.opencontainers.image.licenses=MIT"
+
+  - id: oidcgate-arm64
+    ids: [oidcgate]
+    goos: linux
+    goarch: arm64
+    image_templates:
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-arm64"
+    use: buildx
+    dockerfile: cmd/oidcgate/Dockerfile
+    build_flag_templates:
+      - "--pull"
+      - "--platform=linux/arm64"
+      - "--label=org.opencontainers.image.title=oidcgate"
+      - "--label=org.opencontainers.image.description=Standalone OIDC forward-auth daemon for nginx/Caddy/Traefik/HAProxy/Envoy"
+      - "--label=org.opencontainers.image.version={{ .Version }}"
+      - "--label=org.opencontainers.image.revision={{ .FullCommit }}"
+      - "--label=org.opencontainers.image.created={{ .Date }}"
+      - "--label=org.opencontainers.image.source=https://github.com/lukaszraczylo/traefikoidc"
+      - "--label=org.opencontainers.image.url=https://github.com/lukaszraczylo/traefikoidc"
+      - "--label=org.opencontainers.image.documentation=https://github.com/lukaszraczylo/traefikoidc/blob/main/docs/OIDCGATE.md"
+      - "--label=org.opencontainers.image.licenses=MIT"
+
+# Multi-arch manifests — these are what users actually pull.
+# Tags match the release tag (vX.Y.Z) exactly, plus a few convenience tags.
+docker_manifests:
+  - name_template: "ghcr.io/lukaszraczylo/oidcgate:v{{ .Version }}"
+    image_templates:
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-amd64"
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-arm64"
+  - name_template: "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}"
+    image_templates:
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-amd64"
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-arm64"
+  - name_template: "ghcr.io/lukaszraczylo/oidcgate:v{{ .Major }}.{{ .Minor }}"
+    image_templates:
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-amd64"
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-arm64"
+    skip_push: auto
+  - name_template: "ghcr.io/lukaszraczylo/oidcgate:v{{ .Major }}"
+    image_templates:
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-amd64"
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-arm64"
+    skip_push: auto
+  - name_template: "ghcr.io/lukaszraczylo/oidcgate:latest"
+    image_templates:
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-amd64"
+      - "ghcr.io/lukaszraczylo/oidcgate:{{ .Version }}-arm64"
+    skip_push: auto
 
 checksum:
   name_template: "{{ .ProjectName }}_v{{ .Version }}_checksums.txt"
@@ -58,3 +173,13 @@ signs:
       - "--yes"
     artifacts: checksum
     output: true
+
+# Sign the Docker images and manifests with cosign keyless.
+docker_signs:
+  - cmd: cosign
+    artifacts: all
+    args:
+      - sign
+      - "${artifact}@${digest}"
+      - "--yes"
+    output: true

.traefik.yml

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

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)
@@ -63,6 +64,28 @@ cosign verify-blob \
   traefikoidc_v<version>_checksums.txt
 ```
 
+## Standalone binary (oidcgate)
+
+If you don't run Traefik, `oidcgate` exposes the same middleware as a
+forward-auth daemon for nginx, Caddy, Traefik ForwardAuth, HAProxy, and
+Envoy. See [`docs/OIDCGATE.md`](docs/OIDCGATE.md).
+
+```bash
+# From source
+go build -o oidcgate ./cmd/oidcgate
+./oidcgate --config examples/oidcgate.yaml
+
+# Or pull the released image (multi-arch: linux/amd64, linux/arm64)
+docker run --rm \
+  -v /path/to/config.yaml:/etc/oidcgate/config.yaml:ro \
+  -p 8080:8080 \
+  ghcr.io/lukaszraczylo/oidcgate:latest
+```
+
+Each tagged release publishes a Docker image at
+`ghcr.io/lukaszraczylo/oidcgate:vX.Y.Z` (matching the release tag), plus
+floating `:vX.Y`, `:vX`, and `:latest` aliases.
+
 ## Quickstart
 
 ```yaml
@@ -171,6 +194,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

auth_flow.go

@@ -69,7 +69,7 @@ func (t *TraefikOidc) prepareSessionForAuthentication(session *SessionData, csrf
 //   - session: The session data to prepare for authentication.
 //   - redirectURL: The pre-calculated callback URL (redirect_uri) for this middleware instance.
 func (t *TraefikOidc) defaultInitiateAuthentication(rw http.ResponseWriter, req *http.Request, session *SessionData, redirectURL string) {
-	t.logger.Debugf("Initiating new OIDC authentication flow for request: %s", req.URL.RequestURI())
+	t.logger.Debugf("Initiating new OIDC authentication flow for request: %s", t.originalRequestURI(req))
 
 	// Check and handle redirect limits
 	if err := t.validateRedirectCount(session, rw, req); err != nil {
@@ -98,7 +98,7 @@ func (t *TraefikOidc) defaultInitiateAuthentication(rw http.ResponseWriter, req
 	}
 
 	// Clear existing session data and set new authentication state
-	t.prepareSessionForAuthentication(session, csrfToken, nonce, codeVerifier, req.URL.RequestURI())
+	t.prepareSessionForAuthentication(session, csrfToken, nonce, codeVerifier, t.originalRequestURI(req))
 
 	session.MarkDirty()
 

bearer_auth.go

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

bearer_auth_test.go

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

cmd/oidcgate/Dockerfile

@@ -0,0 +1,28 @@
+# syntax=docker/dockerfile:1.7
+#
+# This Dockerfile is consumed by GoReleaser. The binary is built outside
+# the Docker context (by goreleaser's Go cross-compile) and placed in the
+# build context as ./oidcgate before `docker buildx build` runs.
+#
+# To build locally without goreleaser:
+#   go build -o oidcgate ./cmd/oidcgate
+#   docker build -f cmd/oidcgate/Dockerfile -t oidcgate:dev .
+FROM gcr.io/distroless/static-debian12:nonroot
+
+ARG TARGETOS
+ARG TARGETARCH
+
+LABEL org.opencontainers.image.title="oidcgate"
+LABEL org.opencontainers.image.description="Standalone OIDC forward-auth daemon for nginx/Caddy/Traefik/HAProxy/Envoy"
+LABEL org.opencontainers.image.source="https://github.com/lukaszraczylo/traefikoidc"
+LABEL org.opencontainers.image.documentation="https://github.com/lukaszraczylo/traefikoidc/blob/main/docs/OIDCGATE.md"
+LABEL org.opencontainers.image.licenses="MIT"
+
+COPY oidcgate /usr/local/bin/oidcgate
+
+EXPOSE 8080
+
+USER nonroot:nonroot
+
+ENTRYPOINT ["/usr/local/bin/oidcgate"]
+CMD ["--config", "/etc/oidcgate/config.yaml"]

cmd/oidcgate/config.go

@@ -0,0 +1,222 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"unicode"
+
+	"github.com/lukaszraczylo/traefikoidc"
+	"gopkg.in/yaml.v3"
+)
+
+// Config is the top-level oidcgate configuration. The OIDC subtree maps 1:1
+// onto traefikoidc.Config; the few extra fields configure the daemon itself.
+type Config struct {
+	Listen    string             `json:"listen"`
+	AuthPath  string             `json:"authPath"`
+	StartPath string             `json:"startPath"`
+	OIDC      traefikoidc.Config `json:"-"`
+}
+
+// envScalarFields lists Config field names (within OIDC and top-level)
+// that may be overridden via OIDCGATE_<UPPER_SNAKE_CASE> environment
+// variables. Only scalar strings/ints/bools are supported; nested structs
+// (Redis, SecurityHeaders, DynamicClientRegistration) stay YAML-only.
+var envScalarFields = []string{
+	"Listen", "AuthPath", "StartPath",
+	"ProviderURL", "ClientID", "ClientSecret", "Audience",
+	"CallbackURL", "LogoutURL", "PostLogoutRedirectURI",
+	"SessionEncryptionKey", "CookiePrefix", "CookieDomain",
+	"LogLevel", "RevocationURL", "OIDCEndSessionURL",
+	"UserIdentifierClaim", "GroupClaimName", "RoleClaimName",
+	"ClientAuthMethod", "ClientAssertionPrivateKey",
+	"ClientAssertionKeyPath", "ClientAssertionKeyID", "ClientAssertionAlg",
+	"CACertPath", "CACertPEM",
+}
+
+// Load reads YAML from path, applies env-var overrides, fills defaults,
+// and forces TrustForwardedURI=true so the library honors X-Forwarded-Uri.
+func Load(path string) (*Config, error) {
+	// Clean the operator-supplied path to satisfy gosec G304 (file inclusion
+	// via variable). filepath.Clean strips traversal sequences and normalises
+	// the path; this is canonical mitigation for config files supplied via a
+	// CLI flag — the operator runs the daemon, so the input is trusted, but
+	// gosec's static analysis still flags variable paths without the cleanup.
+	clean := filepath.Clean(path)
+	data, err := os.ReadFile(clean) // #nosec G304 -- operator-supplied config path, cleaned above
+	if err != nil {
+		return nil, fmt.Errorf("read config: %w", err)
+	}
+
+	// Pass 1: YAML → generic map.
+	var raw map[string]any
+	if err := yaml.Unmarshal(data, &raw); err != nil {
+		return nil, fmt.Errorf("yaml parse: %w", err)
+	}
+
+	// Split the top-level oidcgate-specific keys away from the OIDC subtree.
+	listen, _ := raw["listen"].(string)
+	authPath, _ := raw["authPath"].(string)
+	startPath, _ := raw["startPath"].(string)
+	delete(raw, "listen")
+	delete(raw, "authPath")
+	delete(raw, "startPath")
+
+	// Pass 2: remaining map → JSON → traefikoidc.Config (uses existing json tags).
+	jsonBytes, err := json.Marshal(raw)
+	if err != nil {
+		return nil, fmt.Errorf("yaml→json: %w", err)
+	}
+	var oidcCfg traefikoidc.Config
+	if err := json.Unmarshal(jsonBytes, &oidcCfg); err != nil {
+		return nil, fmt.Errorf("oidc config parse: %w", err)
+	}
+
+	cfg := &Config{
+		Listen:    listen,
+		AuthPath:  authPath,
+		StartPath: startPath,
+		OIDC:      oidcCfg,
+	}
+
+	applyEnvOverrides(cfg)
+	applyDefaults(cfg)
+
+	if cfg.Listen == "" {
+		return nil, fmt.Errorf("config: missing required 'listen' (or OIDCGATE_LISTEN env var)")
+	}
+
+	if !strings.HasPrefix(cfg.OIDC.CallbackURL, "/") {
+		return nil, fmt.Errorf("config: callbackURL must be a path starting with '/', got %q", cfg.OIDC.CallbackURL)
+	}
+	if !strings.HasPrefix(cfg.OIDC.LogoutURL, "/") {
+		return nil, fmt.Errorf("config: logoutURL must be a path starting with '/', got %q", cfg.OIDC.LogoutURL)
+	}
+
+	reserved := []string{
+		sentinelPath,
+		cfg.AuthPath,
+		cfg.StartPath,
+		cfg.OIDC.CallbackURL,
+		cfg.OIDC.LogoutURL,
+	}
+	for _, ex := range cfg.OIDC.ExcludedURLs {
+		for _, r := range reserved {
+			if r != "" && strings.HasPrefix(r, ex) {
+				return nil, fmt.Errorf("config: excludedURL %q would bypass reserved oidcgate path %q", ex, r)
+			}
+		}
+	}
+
+	// Force standalone semantics: trust X-Forwarded-Uri.
+	cfg.OIDC.TrustForwardedURI = true
+	return cfg, nil
+}
+
+// applyEnvOverrides walks the allow-listed scalar fields and replaces any
+// non-empty OIDCGATE_<UPPER_SNAKE_CASE> env var. Field name "ClientID"
+// becomes "OIDCGATE_CLIENT_ID"; "SessionEncryptionKey" becomes
+// "OIDCGATE_SESSION_ENCRYPTION_KEY".
+func applyEnvOverrides(cfg *Config) {
+	for _, field := range envScalarFields {
+		env := os.Getenv("OIDCGATE_" + camelToSnakeUpper(field))
+		if env == "" {
+			continue
+		}
+		setScalarField(cfg, field, env)
+	}
+}
+
+func setScalarField(cfg *Config, field, value string) {
+	switch field {
+	case "Listen":
+		cfg.Listen = value
+	case "AuthPath":
+		cfg.AuthPath = value
+	case "StartPath":
+		cfg.StartPath = value
+	case "ProviderURL":
+		cfg.OIDC.ProviderURL = value
+	case "ClientID":
+		cfg.OIDC.ClientID = value
+	case "ClientSecret":
+		cfg.OIDC.ClientSecret = value
+	case "Audience":
+		cfg.OIDC.Audience = value
+	case "CallbackURL":
+		cfg.OIDC.CallbackURL = value
+	case "LogoutURL":
+		cfg.OIDC.LogoutURL = value
+	case "PostLogoutRedirectURI":
+		cfg.OIDC.PostLogoutRedirectURI = value
+	case "SessionEncryptionKey":
+		cfg.OIDC.SessionEncryptionKey = value
+	case "CookiePrefix":
+		cfg.OIDC.CookiePrefix = value
+	case "CookieDomain":
+		cfg.OIDC.CookieDomain = value
+	case "LogLevel":
+		cfg.OIDC.LogLevel = value
+	case "RevocationURL":
+		cfg.OIDC.RevocationURL = value
+	case "OIDCEndSessionURL":
+		cfg.OIDC.OIDCEndSessionURL = value
+	case "UserIdentifierClaim":
+		cfg.OIDC.UserIdentifierClaim = value
+	case "GroupClaimName":
+		cfg.OIDC.GroupClaimName = value
+	case "RoleClaimName":
+		cfg.OIDC.RoleClaimName = value
+	case "ClientAuthMethod":
+		cfg.OIDC.ClientAuthMethod = value
+	case "ClientAssertionPrivateKey":
+		cfg.OIDC.ClientAssertionPrivateKey = value
+	case "ClientAssertionKeyPath":
+		cfg.OIDC.ClientAssertionKeyPath = value
+	case "ClientAssertionKeyID":
+		cfg.OIDC.ClientAssertionKeyID = value
+	case "ClientAssertionAlg":
+		cfg.OIDC.ClientAssertionAlg = value
+	case "CACertPath":
+		cfg.OIDC.CACertPath = value
+	case "CACertPEM":
+		cfg.OIDC.CACertPEM = value
+	}
+}
+
+func applyDefaults(cfg *Config) {
+	if cfg.AuthPath == "" {
+		cfg.AuthPath = "/oauth2/auth"
+	}
+	if cfg.StartPath == "" {
+		cfg.StartPath = "/oauth2/start"
+	}
+}
+
+// camelToSnakeUpper turns "ClientSecret" into "CLIENT_SECRET",
+// "SessionEncryptionKey" into "SESSION_ENCRYPTION_KEY", etc.
+// Multi-letter acronyms keep their grouping: "OIDCEndSessionURL" →
+// "OIDC_END_SESSION_URL", "CACertPEM" → "CA_CERT_PEM".
+func camelToSnakeUpper(s string) string {
+	runes := []rune(s)
+	var b strings.Builder
+	for i, r := range runes {
+		if i > 0 && isUpper(r) {
+			prev := runes[i-1]
+			next := rune(0)
+			if i+1 < len(runes) {
+				next = runes[i+1]
+			}
+			if !isUpper(prev) || (next != 0 && !isUpper(next)) {
+				b.WriteByte('_')
+			}
+		}
+		b.WriteRune(unicode.ToUpper(r))
+	}
+	return b.String()
+}
+
+func isUpper(r rune) bool { return r >= 'A' && r <= 'Z' }

cmd/oidcgate/config_test.go

@@ -0,0 +1,303 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// minimalYAML is a base config accepted by Load with no surprises.
+const minimalYAML = `
+listen: ":8080"
+providerURL: "https://idp.example"
+clientID: "abc"
+clientSecret: "secret"
+sessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+callbackURL: "/oauth2/callback"
+logoutURL: "/oauth2/logout"
+`
+
+func writeConfig(t *testing.T, content string) string {
+	t.Helper()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+func TestLoad_YAMLRoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	if err := os.WriteFile(path, []byte(`
+listen: ":9090"
+authPath: "/auth"
+startPath: "/start"
+providerURL: "https://idp.example"
+clientID: "abc"
+clientSecret: "secret"
+sessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+callbackURL: "/oauth2/callback"
+logoutURL: "/oauth2/logout"
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.Listen != ":9090" {
+		t.Errorf("listen: want :9090, got %q", cfg.Listen)
+	}
+	if cfg.AuthPath != "/auth" {
+		t.Errorf("authPath: want /auth, got %q", cfg.AuthPath)
+	}
+	if cfg.StartPath != "/start" {
+		t.Errorf("startPath: want /start, got %q", cfg.StartPath)
+	}
+	if cfg.OIDC.ClientID != "abc" {
+		t.Errorf("clientID: want abc, got %q", cfg.OIDC.ClientID)
+	}
+	if cfg.OIDC.ClientSecret != "secret" {
+		t.Errorf("clientSecret: want secret, got %q", cfg.OIDC.ClientSecret)
+	}
+	if !cfg.OIDC.TrustForwardedURI {
+		t.Errorf("TrustForwardedURI should be forced true by Load")
+	}
+}
+
+func TestLoad_EnvOverride(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	if err := os.WriteFile(path, []byte(`
+listen: ":8080"
+providerURL: "https://idp.example"
+clientID: "abc"
+clientSecret: "from-file"
+sessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+callbackURL: "/oauth2/callback"
+logoutURL: "/oauth2/logout"
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("OIDCGATE_CLIENT_SECRET", "from-env")
+	t.Setenv("OIDCGATE_LISTEN", ":9999")
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.OIDC.ClientSecret != "from-env" {
+		t.Errorf("env override (clientSecret): want from-env, got %q", cfg.OIDC.ClientSecret)
+	}
+	if cfg.Listen != ":9999" {
+		t.Errorf("env override (listen): want :9999, got %q", cfg.Listen)
+	}
+}
+
+func TestLoad_Defaults(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	if err := os.WriteFile(path, []byte(`
+listen: ":8080"
+providerURL: "https://idp.example"
+clientID: "abc"
+clientSecret: "secret"
+sessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+callbackURL: "/oauth2/callback"
+logoutURL: "/oauth2/logout"
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.AuthPath != "/oauth2/auth" {
+		t.Errorf("AuthPath default: want /oauth2/auth, got %q", cfg.AuthPath)
+	}
+	if cfg.StartPath != "/oauth2/start" {
+		t.Errorf("StartPath default: want /oauth2/start, got %q", cfg.StartPath)
+	}
+}
+
+func TestLoad_MissingFile(t *testing.T) {
+	if _, err := Load("/nonexistent/config.yaml"); err == nil {
+		t.Fatal("expected error for missing file")
+	}
+}
+
+func TestLoad_NestedStructRoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	if err := os.WriteFile(path, []byte(`
+listen: ":8080"
+providerURL: "https://idp.example"
+clientID: "abc"
+clientSecret: "secret"
+sessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+callbackURL: "/oauth2/callback"
+logoutURL: "/oauth2/logout"
+redis:
+  address: "redis:6379"
+  password: "redispw"
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.OIDC.Redis == nil {
+		t.Fatal("redis block should populate cfg.OIDC.Redis")
+	}
+	if cfg.OIDC.Redis.Address != "redis:6379" {
+		t.Errorf("redis address: want redis:6379, got %q", cfg.OIDC.Redis.Address)
+	}
+}
+
+// Fix 5: callbackURL / logoutURL must start with "/"
+func TestLoad_RejectsAbsoluteCallbackURL(t *testing.T) {
+	path := writeConfig(t, `
+listen: ":8080"
+providerURL: "https://idp.example"
+clientID: "abc"
+clientSecret: "secret"
+sessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+callbackURL: "https://app.example.com/oauth2/callback"
+logoutURL: "/oauth2/logout"
+`)
+	if _, err := Load(path); err == nil {
+		t.Fatal("callbackURL with absolute URL must be rejected")
+	}
+}
+
+func TestLoad_RejectsAbsoluteLogoutURL(t *testing.T) {
+	path := writeConfig(t, `
+listen: ":8080"
+providerURL: "https://idp.example"
+clientID: "abc"
+clientSecret: "secret"
+sessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+callbackURL: "/oauth2/callback"
+logoutURL: "https://app.example.com/oauth2/logout"
+`)
+	if _, err := Load(path); err == nil {
+		t.Fatal("logoutURL with absolute URL must be rejected")
+	}
+}
+
+// Fix 2: excludedURLs must not prefix reserved paths
+func TestLoad_RejectsExcludedURLPrefixingReservedPath(t *testing.T) {
+	path := writeConfig(t, `
+listen: ":8080"
+providerURL: "https://idp.example"
+clientID: "abc"
+clientSecret: "secret"
+sessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+callbackURL: "/oauth2/callback"
+logoutURL: "/oauth2/logout"
+excludedURLs: ["/"]
+`)
+	if _, err := Load(path); err == nil {
+		t.Fatal("excludedURLs: ['/'] must be rejected (bypasses all reserved paths)")
+	}
+}
+
+func TestLoad_AllowsNonOverlappingExcludedURL(t *testing.T) {
+	path := writeConfig(t, minimalYAML+`excludedURLs: ["/public"]
+`)
+	if _, err := Load(path); err != nil {
+		t.Fatalf("non-overlapping excludedURL must be accepted: %v", err)
+	}
+}
+
+// Fix 3: env override coverage — every envScalarFields entry must have a
+// matching case in setScalarField. isAllZeroForField detects drift.
+func TestEnvOverrideCoverage(t *testing.T) {
+	for _, field := range envScalarFields {
+		field := field
+		t.Run(field, func(t *testing.T) {
+			probe := "/safe/probe-" + field
+			if field == "SessionEncryptionKey" {
+				probe = "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"
+			}
+			if field == "LogLevel" {
+				probe = "debug"
+			}
+			if field == "ClientAuthMethod" {
+				probe = "client_secret_post"
+			}
+			if field == "ClientAssertionAlg" {
+				probe = "RS256"
+			}
+
+			var fresh Config
+			setScalarField(&fresh, field, probe)
+			if isAllZeroForField(&fresh, field, probe) {
+				t.Fatalf("envScalarFields includes %q but setScalarField has no matching case (drift)", field)
+			}
+		})
+	}
+}
+
+// isAllZeroForField returns true when setScalarField did NOT set the expected
+// field — i.e., the switch is missing a case for `field`.
+func isAllZeroForField(cfg *Config, field, probe string) bool {
+	switch field {
+	case "Listen":
+		return cfg.Listen != probe
+	case "AuthPath":
+		return cfg.AuthPath != probe
+	case "StartPath":
+		return cfg.StartPath != probe
+	case "ProviderURL":
+		return cfg.OIDC.ProviderURL != probe
+	case "ClientID":
+		return cfg.OIDC.ClientID != probe
+	case "ClientSecret":
+		return cfg.OIDC.ClientSecret != probe
+	case "Audience":
+		return cfg.OIDC.Audience != probe
+	case "CallbackURL":
+		return cfg.OIDC.CallbackURL != probe
+	case "LogoutURL":
+		return cfg.OIDC.LogoutURL != probe
+	case "PostLogoutRedirectURI":
+		return cfg.OIDC.PostLogoutRedirectURI != probe
+	case "SessionEncryptionKey":
+		return cfg.OIDC.SessionEncryptionKey != probe
+	case "CookiePrefix":
+		return cfg.OIDC.CookiePrefix != probe
+	case "CookieDomain":
+		return cfg.OIDC.CookieDomain != probe
+	case "LogLevel":
+		return cfg.OIDC.LogLevel != probe
+	case "RevocationURL":
+		return cfg.OIDC.RevocationURL != probe
+	case "OIDCEndSessionURL":
+		return cfg.OIDC.OIDCEndSessionURL != probe
+	case "UserIdentifierClaim":
+		return cfg.OIDC.UserIdentifierClaim != probe
+	case "GroupClaimName":
+		return cfg.OIDC.GroupClaimName != probe
+	case "RoleClaimName":
+		return cfg.OIDC.RoleClaimName != probe
+	case "ClientAuthMethod":
+		return cfg.OIDC.ClientAuthMethod != probe
+	case "ClientAssertionPrivateKey":
+		return cfg.OIDC.ClientAssertionPrivateKey != probe
+	case "ClientAssertionKeyPath":
+		return cfg.OIDC.ClientAssertionKeyPath != probe
+	case "ClientAssertionKeyID":
+		return cfg.OIDC.ClientAssertionKeyID != probe
+	case "ClientAssertionAlg":
+		return cfg.OIDC.ClientAssertionAlg != probe
+	case "CACertPath":
+		return cfg.OIDC.CACertPath != probe
+	case "CACertPEM":
+		return cfg.OIDC.CACertPEM != probe
+	}
+	return true // unknown field → drift
+}

cmd/oidcgate/endpoints.go

@@ -0,0 +1,69 @@
+package main
+
+import "net/http"
+
+// sentinelPath is the synthetic request path used when delegating /oauth2/auth
+// and /oauth2/start into the traefikoidc middleware. It must NOT collide with
+// callbackURL, logoutURL, /health*, or any plausible excludedURLs entry —
+// the underscores and double-prefixing make accidental matches near-impossible.
+const sentinelPath = "/__oidcgate_protected__"
+
+// newAuthHandler builds the /oauth2/auth (silent probe) handler.
+// Rewrites the request path to sentinelPath, wraps the ResponseWriter to
+// convert the middleware's 302→IdP into 401, and delegates.
+func newAuthHandler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
+		ic := newAuthInterceptor(rw)
+		defer ic.Finalize()
+		r2 := cloneAndRewrite(req, sentinelPath)
+		next.ServeHTTP(ic, r2)
+	})
+}
+
+// newStartHandler builds the /oauth2/start (visible sign-in) handler.
+// Rewrites the path to sentinelPath, forwards any ?rd= query as
+// X-Forwarded-Uri so the middleware (with TrustForwardedURI=true) captures
+// the right post-login redirect target, then delegates. The middleware's
+// natural 302→IdP flows through unchanged.
+func newStartHandler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
+		r2 := cloneAndRewrite(req, sentinelPath)
+		// Precedence: explicit ?rd= wins over an ambient upstream
+		// X-Forwarded-Uri so /oauth2/start?rd=/dashboard does not get
+		// silently overridden by the proxy's current-URL forwarding.
+		if rd := req.URL.Query().Get("rd"); rd != "" {
+			r2.Header.Set("X-Forwarded-Uri", rd)
+		}
+		next.ServeHTTP(rw, r2)
+	})
+}
+
+// newCallbackHandler builds the IdP callback endpoint.
+// Rewrites the request path to the configured callbackURL so the middleware's
+// path-match at the top of ServeHTTP triggers the callback flow.
+func newCallbackHandler(next http.Handler, callbackURL string) http.Handler {
+	return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
+		r2 := cloneAndRewrite(req, callbackURL)
+		next.ServeHTTP(rw, r2)
+	})
+}
+
+// newLogoutHandler builds the logout endpoint.
+// Rewrites the request path to the configured logoutURL so the middleware's
+// path-match at the top of ServeHTTP triggers the logout flow.
+func newLogoutHandler(next http.Handler, logoutURL string) http.Handler {
+	return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
+		r2 := cloneAndRewrite(req, logoutURL)
+		next.ServeHTTP(rw, r2)
+	})
+}
+
+// cloneAndRewrite returns a clone of req with URL.Path set to newPath.
+// req.Clone deep-copies URL via net/http's cloneURL, so mutating
+// r2.URL.Path does not affect the original req. RawQuery, Host,
+// Fragment, RawPath are preserved unchanged.
+func cloneAndRewrite(req *http.Request, newPath string) *http.Request {
+	r2 := req.Clone(req.Context())
+	r2.URL.Path = newPath
+	return r2
+}

cmd/oidcgate/endpoints_test.go

@@ -0,0 +1,167 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// stubMiddleware lets us test endpoint wiring without spinning up a full
+// traefikoidc instance. Each test injects the behavior it wants.
+type stubMiddleware struct {
+	calls []stubCall
+	fn    func(rw http.ResponseWriter, req *http.Request)
+}
+
+type stubCall struct {
+	path   string
+	header http.Header
+}
+
+func (s *stubMiddleware) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
+	s.calls = append(s.calls, stubCall{path: req.URL.Path, header: req.Header.Clone()})
+	if s.fn != nil {
+		s.fn(rw, req)
+	}
+}
+
+func TestAuth_RewritesToSentinel_AndConverts302To401(t *testing.T) {
+	stub := &stubMiddleware{
+		fn: func(rw http.ResponseWriter, req *http.Request) {
+			rw.Header().Set("Location", "https://idp.example/authorize?state=abc")
+			rw.Header().Add("Set-Cookie", "_oidc_state=abc; Path=/")
+			rw.WriteHeader(http.StatusFound)
+		},
+	}
+	h := newAuthHandler(stub)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth2/auth", nil)
+	req.Header.Set("X-Forwarded-Uri", "/protected/page")
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status: want 401, got %d", rec.Code)
+	}
+	if len(stub.calls) != 1 || stub.calls[0].path != sentinelPath {
+		t.Fatalf("middleware path: want %q, got %v", sentinelPath, stub.calls)
+	}
+	if rec.Header().Get("X-Auth-Redirect") == "" {
+		t.Error("X-Auth-Redirect should carry Location")
+	}
+	if got := stub.calls[0].header.Get("X-Forwarded-Uri"); got != "/protected/page" {
+		t.Errorf("X-Forwarded-Uri must pass through to middleware: want /protected/page, got %q", got)
+	}
+}
+
+func TestAuth_AuthenticatedReturnsHeadersAnd200(t *testing.T) {
+	stub := &stubMiddleware{
+		fn: func(rw http.ResponseWriter, req *http.Request) {
+			// Middleware would stamp X-Forwarded-User on req then call next.
+			req.Header.Set("X-Forwarded-User", "alice")
+			newSuccessHandler().ServeHTTP(rw, req)
+		},
+	}
+	h := newAuthHandler(stub)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth2/auth", nil)
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status: want 200, got %d", rec.Code)
+	}
+	if got := rec.Header().Get("X-Forwarded-User"); got != "alice" {
+		t.Errorf("X-Forwarded-User mirrored: want alice, got %q", got)
+	}
+}
+
+func TestStart_DelegatesWithSentinel_NoInterception(t *testing.T) {
+	stub := &stubMiddleware{
+		fn: func(rw http.ResponseWriter, req *http.Request) {
+			rw.Header().Set("Location", "https://idp.example/authorize")
+			rw.WriteHeader(http.StatusFound)
+		},
+	}
+	h := newStartHandler(stub)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth2/start?rd=/back", nil)
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusFound {
+		t.Fatalf("start: 302 must flow through, got %d", rec.Code)
+	}
+	if stub.calls[0].path != sentinelPath {
+		t.Fatalf("start path rewrite: want %q, got %q", sentinelPath, stub.calls[0].path)
+	}
+}
+
+func TestStart_ForwardsRdAsXForwardedURI(t *testing.T) {
+	stub := &stubMiddleware{
+		fn: func(rw http.ResponseWriter, req *http.Request) { rw.WriteHeader(http.StatusFound) },
+	}
+	h := newStartHandler(stub)
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth2/start?rd=/back/here", nil)
+	h.ServeHTTP(rec, req)
+	if got := stub.calls[0].header.Get("X-Forwarded-Uri"); got != "/back/here" {
+		t.Fatalf("?rd should become X-Forwarded-Uri: want /back/here, got %q", got)
+	}
+}
+
+func TestStart_RdQueryWinsOverUpstreamHeader(t *testing.T) {
+	stub := &stubMiddleware{
+		fn: func(rw http.ResponseWriter, req *http.Request) { rw.WriteHeader(http.StatusFound) },
+	}
+	h := newStartHandler(stub)
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth2/start?rd=/explicit", nil)
+	req.Header.Set("X-Forwarded-Uri", "/ambient")
+	h.ServeHTTP(rec, req)
+	if got := stub.calls[0].header.Get("X-Forwarded-Uri"); got != "/explicit" {
+		t.Fatalf("?rd= must win over upstream X-Forwarded-Uri: want /explicit, got %q", got)
+	}
+}
+
+func TestCallback_RewritesToConfiguredCallbackURL(t *testing.T) {
+	var seenPath, seenQuery string
+	stub := &stubMiddleware{
+		fn: func(rw http.ResponseWriter, req *http.Request) {
+			seenPath = req.URL.Path
+			seenQuery = req.URL.RawQuery
+			rw.WriteHeader(http.StatusOK)
+		},
+	}
+	h := newCallbackHandler(stub, "/oauth2/callback")
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth2/callback?code=abc&state=xyz", nil)
+	h.ServeHTTP(rec, req)
+
+	if seenPath != "/oauth2/callback" {
+		t.Fatalf("callback path: want /oauth2/callback, got %q", seenPath)
+	}
+	if seenQuery != "code=abc&state=xyz" {
+		t.Fatalf("callback query must survive rewrite: want code=abc&state=xyz, got %q", seenQuery)
+	}
+}
+
+func TestLogout_RewritesToConfiguredLogoutURL(t *testing.T) {
+	var seenPath string
+	stub := &stubMiddleware{
+		fn: func(rw http.ResponseWriter, req *http.Request) {
+			seenPath = req.URL.Path
+			rw.WriteHeader(http.StatusOK)
+		},
+	}
+	h := newLogoutHandler(stub, "/oauth2/logout")
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/logout", nil)
+	h.ServeHTTP(rec, req)
+
+	if seenPath != "/oauth2/logout" {
+		t.Fatalf("logout path: want /oauth2/logout, got %q", seenPath)
+	}
+}

cmd/oidcgate/health.go

@@ -0,0 +1,24 @@
+package main
+
+import "net/http"
+
+// readyReporter is satisfied by *traefikoidc.TraefikOidc via its Ready() method.
+type readyReporter interface {
+	Ready() bool
+}
+
+func newHealthzHandler() http.Handler {
+	return http.HandlerFunc(func(rw http.ResponseWriter, _ *http.Request) {
+		rw.WriteHeader(http.StatusOK)
+	})
+}
+
+func newReadyzHandler(r readyReporter) http.Handler {
+	return http.HandlerFunc(func(rw http.ResponseWriter, _ *http.Request) {
+		if r.Ready() {
+			rw.WriteHeader(http.StatusOK)
+			return
+		}
+		rw.WriteHeader(http.StatusServiceUnavailable)
+	})
+}

cmd/oidcgate/health_test.go

@@ -0,0 +1,38 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+type readyStub struct{ ready bool }
+
+func (r *readyStub) Ready() bool { return r.ready }
+
+func TestHealthz_Always200(t *testing.T) {
+	h := newHealthzHandler()
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("healthz: want 200, got %d", rec.Code)
+	}
+}
+
+func TestReadyz_503BeforeDiscovery(t *testing.T) {
+	h := newReadyzHandler(&readyStub{ready: false})
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/readyz", nil))
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("readyz pre-discovery: want 503, got %d", rec.Code)
+	}
+}
+
+func TestReadyz_200AfterDiscovery(t *testing.T) {
+	h := newReadyzHandler(&readyStub{ready: true})
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/readyz", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("readyz post-discovery: want 200, got %d", rec.Code)
+	}
+}

cmd/oidcgate/helpers_test.go

@@ -0,0 +1,15 @@
+package main
+
+import "github.com/lukaszraczylo/traefikoidc"
+
+type traefikoidcConfigStub struct {
+	callbackURL string
+	logoutURL   string
+}
+
+func (s traefikoidcConfigStub) AsOIDC() traefikoidc.Config {
+	return traefikoidc.Config{
+		CallbackURL: s.callbackURL,
+		LogoutURL:   s.logoutURL,
+	}
+}

cmd/oidcgate/integration_test.go

@@ -0,0 +1,195 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/lukaszraczylo/traefikoidc"
+)
+
+// fakeProviderHost is a synthetic hostname used in place of the httptest.Server's
+// 127.0.0.1 address. traefikoidc's URL validator blocks loopback IPs
+// unconditionally; a non-loopback hostname passes the check. The custom HTTP
+// client returned by mockHTTPClient rewires all dials for this host to the
+// actual test-server port, so the mock IdP still receives every request.
+const fakeProviderHost = "test-oidc-provider.local"
+
+// mockHTTPClient returns an *http.Client whose dialer transparently redirects
+// connections to fakeProviderHost to the real httptest.Server address.
+func mockHTTPClient(realAddr string) *http.Client {
+	dialer := &net.Dialer{Timeout: 5 * time.Second}
+	transport := &http.Transport{
+		DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
+			host, _, err := net.SplitHostPort(addr)
+			if err != nil {
+				return dialer.DialContext(ctx, network, addr)
+			}
+			if host == fakeProviderHost {
+				addr = realAddr
+			}
+			return dialer.DialContext(ctx, network, addr)
+		},
+	}
+	return &http.Client{Transport: transport}
+}
+
+// newMockIdP returns an httptest.Server that serves the minimal OIDC
+// discovery surface required by traefikoidc.NewWithContext to bootstrap
+// — discovery doc + an empty JWKS. All URLs in the discovery doc use
+// fakeProviderHost so they pass the middleware's URL security validator.
+func newMockIdP(t *testing.T) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	fakeBase := "http://" + fakeProviderHost
+	mux.HandleFunc("/.well-known/openid-configuration", func(rw http.ResponseWriter, _ *http.Request) {
+		discovery := map[string]any{
+			"issuer":                                fakeBase,
+			"authorization_endpoint":                fakeBase + "/authorize",
+			"token_endpoint":                        fakeBase + "/token",
+			"jwks_uri":                              fakeBase + "/jwks",
+			"response_types_supported":              []string{"code"},
+			"subject_types_supported":               []string{"public"},
+			"id_token_signing_alg_values_supported": []string{"RS256"},
+		}
+		rw.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(rw).Encode(discovery)
+	})
+	mux.HandleFunc("/jwks", func(rw http.ResponseWriter, _ *http.Request) {
+		rw.Header().Set("Content-Type", "application/json")
+		_, _ = rw.Write([]byte(`{"keys":[]}`))
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+// buildTestConfig produces a Config that points at the fake provider hostname
+// (which the custom HTTP client redirects to the real mock server) and uses
+// a known-good SessionEncryptionKey + safe path defaults.
+func buildTestConfig(srv *httptest.Server) *Config {
+	// realAddr is HOST:PORT of the httptest server (e.g. "127.0.0.1:56789").
+	realAddr := srv.Listener.Addr().String()
+	cfg := &Config{
+		Listen:    "127.0.0.1:0", // unused — we drive the mux directly via httptest
+		AuthPath:  "/oauth2/auth",
+		StartPath: "/oauth2/start",
+		OIDC: traefikoidc.Config{
+			ProviderURL:          "http://" + fakeProviderHost,
+			ClientID:             "test-client",
+			ClientSecret:         "test-secret",
+			SessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+			CallbackURL:          "/oauth2/callback",
+			LogoutURL:            "/oauth2/logout",
+			TrustForwardedURI:    true,
+			EnablePKCE:           true,
+			HTTPClient:           mockHTTPClient(realAddr),
+		},
+	}
+	return cfg
+}
+
+// buildIntegrationStack builds the same wiring main.go builds: real
+// middleware constructed against the mock IdP, success handler as next,
+// mux on top.
+func buildIntegrationStack(t *testing.T, idp *httptest.Server) (http.Handler, *traefikoidc.TraefikOidc) {
+	t.Helper()
+	cfg := buildTestConfig(idp)
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+	mw, err := traefikoidc.NewWithContext(ctx, &cfg.OIDC, newSuccessHandler(), "oidcgate-test")
+	if err != nil {
+		t.Fatalf("NewWithContext: %v", err)
+	}
+	mux := buildMux(cfg, mw, mw)
+	return mux, mw
+}
+
+func TestIntegration_UnauthenticatedAuthReturns401WithRedirect(t *testing.T) {
+	idp := newMockIdP(t)
+	mux, _ := buildIntegrationStack(t, idp)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth2/auth", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status: want 401, got %d (body=%q)", rec.Code, rec.Body.String())
+	}
+	loc := rec.Header().Get("X-Auth-Redirect")
+	if loc == "" {
+		t.Fatal("X-Auth-Redirect should carry the IdP authorize URL")
+	}
+	if !strings.HasPrefix(loc, "http://"+fakeProviderHost+"/authorize") {
+		t.Errorf("X-Auth-Redirect should point at the mock IdP authorize endpoint, got %q", loc)
+	}
+	if cookies := rec.Header().Values("Set-Cookie"); len(cookies) == 0 {
+		t.Error("expected at least one Set-Cookie (state/PKCE/nonce) on 401")
+	}
+}
+
+func TestIntegration_StartRedirectsToIdPWithStateAndPKCE(t *testing.T) {
+	idp := newMockIdP(t)
+	mux, _ := buildIntegrationStack(t, idp)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth2/start?rd=/dashboard", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusFound {
+		t.Fatalf("status: want 302, got %d", rec.Code)
+	}
+	loc := rec.Header().Get("Location")
+	if !strings.HasPrefix(loc, "http://"+fakeProviderHost+"/authorize") {
+		t.Fatalf("Location: want prefix http://%s/authorize, got %q", fakeProviderHost, loc)
+	}
+	if !strings.Contains(loc, "state=") {
+		t.Errorf("Location should include state= param, got %q", loc)
+	}
+	if !strings.Contains(loc, "code_challenge=") {
+		t.Errorf("Location should include code_challenge= param (PKCE), got %q", loc)
+	}
+}
+
+func TestIntegration_HealthzAlways200(t *testing.T) {
+	idp := newMockIdP(t)
+	mux, _ := buildIntegrationStack(t, idp)
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("healthz: want 200, got %d", rec.Code)
+	}
+}
+
+func TestIntegration_ReadyzBecomes200AfterDiscovery(t *testing.T) {
+	idp := newMockIdP(t)
+	mux, mw := buildIntegrationStack(t, idp)
+
+	// Hit /oauth2/auth once to trigger metadata discovery (the middleware
+	// performs discovery lazily on first request).
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/oauth2/auth", nil))
+
+	// Poll Ready() until true or timeout.
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		if mw.Ready() {
+			break
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	if !mw.Ready() {
+		t.Fatal("middleware should be Ready() within 3s after first request triggered discovery")
+	}
+
+	rec = httptest.NewRecorder()
+	mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/readyz", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("readyz post-discovery: want 200, got %d", rec.Code)
+	}
+}

cmd/oidcgate/interceptor.go

@@ -0,0 +1,83 @@
+package main
+
+import "net/http"
+
+// authInterceptor wraps a ResponseWriter for the /oauth2/auth endpoint.
+// The traefikoidc middleware emits an HTTP 302 to the IdP authorize URL
+// when a request is unauthenticated, but nginx auth_request and similar
+// silent-probe contracts cannot follow redirects. authInterceptor buffers
+// the header/body and, at Finalize() time:
+//
+//   - if status was a redirect class (302, 303, 307, 308), rewrites it
+//     to 401, moves the original Location header to X-Auth-Redirect
+//     (advisory), strips Location, preserves Set-Cookie headers (state,
+//     PKCE, nonce — the browser will carry them into the next request),
+//     and writes an empty body.
+//   - otherwise: passes through verbatim.
+type authInterceptor struct {
+	inner       http.ResponseWriter
+	headers     http.Header
+	status      int
+	body        []byte
+	wroteHeader bool
+	finalized   bool
+}
+
+func newAuthInterceptor(inner http.ResponseWriter) *authInterceptor {
+	return &authInterceptor{
+		inner:   inner,
+		headers: http.Header{},
+		status:  http.StatusOK,
+	}
+}
+
+func (w *authInterceptor) Header() http.Header { return w.headers }
+
+func (w *authInterceptor) WriteHeader(status int) {
+	if w.wroteHeader {
+		return
+	}
+	w.status = status
+	w.wroteHeader = true
+}
+
+func (w *authInterceptor) Write(b []byte) (int, error) { //nolint:unparam // signature mandated by http.ResponseWriter
+	if !w.wroteHeader {
+		w.WriteHeader(http.StatusOK)
+	}
+	w.body = append(w.body, b...)
+	return len(b), nil
+}
+
+// Finalize flushes the buffered response, applying the 302/303 → 401 rewrite.
+// Must be called exactly once after the wrapped handler returns.
+func (w *authInterceptor) Finalize() {
+	if w.finalized {
+		return
+	}
+	w.finalized = true
+	switch w.status {
+	case http.StatusFound, http.StatusSeeOther, http.StatusTemporaryRedirect, http.StatusPermanentRedirect:
+		// Move Location → X-Auth-Redirect, strip Location, force 401, drop body.
+		if loc := w.headers.Get("Location"); loc != "" {
+			w.headers.Set("X-Auth-Redirect", loc)
+			w.headers.Del("Location")
+		}
+		copyHeaders(w.inner.Header(), w.headers)
+		w.inner.WriteHeader(http.StatusUnauthorized)
+		return
+	}
+	copyHeaders(w.inner.Header(), w.headers)
+	w.inner.WriteHeader(w.status)
+	if len(w.body) > 0 {
+		_, _ = w.inner.Write(w.body)
+	}
+}
+
+func copyHeaders(dst, src http.Header) {
+	for k, vs := range src {
+		for _, v := range vs {
+			dst.Add(k, v)
+		}
+	}
+}

cmd/oidcgate/interceptor_test.go

@@ -0,0 +1,108 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestInterceptor_302BecomesNot401(t *testing.T) {
+	rec := httptest.NewRecorder()
+	w := newAuthInterceptor(rec)
+
+	w.Header().Set("Location", "https://idp.example/authorize?state=abc")
+	w.Header().Add("Set-Cookie", "_oidc_state=abc; Path=/; HttpOnly")
+	w.Header().Add("Set-Cookie", "_oidc_pkce=xyz; Path=/; HttpOnly")
+	w.WriteHeader(http.StatusFound)
+	_, _ = w.Write([]byte("ignored body"))
+
+	w.Finalize()
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status: want 401, got %d", rec.Code)
+	}
+	if got := rec.Header().Get("X-Auth-Redirect"); got != "https://idp.example/authorize?state=abc" {
+		t.Errorf("X-Auth-Redirect: want preserved Location, got %q", got)
+	}
+	if got := rec.Header().Get("Location"); got != "" {
+		t.Errorf("Location must be stripped on 401, got %q", got)
+	}
+	cookies := rec.Header().Values("Set-Cookie")
+	if len(cookies) != 2 {
+		t.Fatalf("Set-Cookie count: want 2, got %d (%v)", len(cookies), cookies)
+	}
+	if body := strings.TrimSpace(rec.Body.String()); body != "" {
+		t.Errorf("body must be empty on 401, got %q", body)
+	}
+}
+
+func TestInterceptor_NonRedirectPassthrough(t *testing.T) {
+	rec := httptest.NewRecorder()
+	w := newAuthInterceptor(rec)
+
+	w.Header().Set("X-Forwarded-User", "alice")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte("ok"))
+
+	w.Finalize()
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status: want 200, got %d", rec.Code)
+	}
+	if got := rec.Header().Get("X-Forwarded-User"); got != "alice" {
+		t.Errorf("X-Forwarded-User: want preserved, got %q", got)
+	}
+	if !strings.Contains(rec.Body.String(), "ok") {
+		t.Errorf("body: want 'ok' preserved, got %q", rec.Body.String())
+	}
+}
+
+func TestInterceptor_303SeeOtherAlsoIntercepted(t *testing.T) {
+	rec := httptest.NewRecorder()
+	w := newAuthInterceptor(rec)
+	w.Header().Set("Location", "/elsewhere")
+	w.WriteHeader(http.StatusSeeOther)
+	w.Finalize()
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("303 should be intercepted to 401, got %d", rec.Code)
+	}
+}
+
+func TestInterceptor_307TemporaryRedirectIntercepted(t *testing.T) {
+	rec := httptest.NewRecorder()
+	w := newAuthInterceptor(rec)
+	w.Header().Set("Location", "/elsewhere")
+	w.WriteHeader(http.StatusTemporaryRedirect)
+	w.Finalize()
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("307 should be intercepted to 401, got %d", rec.Code)
+	}
+}
+
+func TestInterceptor_308PermanentRedirectIntercepted(t *testing.T) {
+	rec := httptest.NewRecorder()
+	w := newAuthInterceptor(rec)
+	w.Header().Set("Location", "/elsewhere")
+	w.WriteHeader(http.StatusPermanentRedirect)
+	w.Finalize()
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("308 should be intercepted to 401, got %d", rec.Code)
+	}
+}
+
+func TestInterceptor_DoubleFinalizeIsNoop(t *testing.T) {
+	rec := httptest.NewRecorder()
+	w := newAuthInterceptor(rec)
+	w.Header().Set("X-Forwarded-User", "alice")
+	w.WriteHeader(http.StatusOK)
+	w.Finalize()
+	// Second call must not panic, must not change anything observable.
+	w.Finalize()
+	if rec.Code != http.StatusOK {
+		t.Fatalf("double Finalize must not change status, got %d", rec.Code)
+	}
+	if got := rec.Header().Get("X-Forwarded-User"); got != "alice" {
+		t.Errorf("double Finalize must not duplicate headers, got %q", got)
+	}
+}

cmd/oidcgate/main.go

@@ -0,0 +1,54 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/lukaszraczylo/traefikoidc"
+)
+
+func main() {
+	configPath := flag.String("config", "/etc/oidcgate/config.yaml", "Path to YAML config file")
+	flag.Parse()
+
+	cfg, err := Load(*configPath)
+	if err != nil {
+		log.Fatalf("oidcgate: load config: %v", err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	success := newSuccessHandler()
+	middleware, err := traefikoidc.NewWithContext(ctx, &cfg.OIDC, success, "oidcgate")
+	if err != nil {
+		cancel()
+		log.Fatalf("oidcgate: build middleware: %v", err)
+	}
+
+	mux := buildMux(cfg, middleware, middleware)
+	srv := buildServer(cfg, mux)
+
+	go func() {
+		sigs := make(chan os.Signal, 1)
+		signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+		<-sigs
+		log.Println("oidcgate: shutdown signal received")
+		if err := shutdown(srv); err != nil {
+			log.Printf("oidcgate: shutdown error: %v", err)
+		}
+	}()
+
+	log.Printf("oidcgate: listening on %s", cfg.Listen)
+	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+		cancel()
+		log.Fatalf("oidcgate: serve: %v", err)
+	}
+	log.Println("oidcgate: stopped")
+}

cmd/oidcgate/server.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"context"
+	"net/http"
+	"time"
+)
+
+// buildMux wires all six routes onto a single ServeMux:
+//
+//	/healthz, /readyz, AuthPath, StartPath, OIDC.CallbackURL, OIDC.LogoutURL.
+//
+// The same `middleware` instance is delegated to by all four OIDC routes;
+// the synthetic success handler is wired into the middleware at construction
+// time (in main.go) so it doesn't appear here.
+func buildMux(cfg *Config, middleware http.Handler, ready readyReporter) *http.ServeMux {
+	mux := http.NewServeMux()
+	mux.Handle("/healthz", newHealthzHandler())
+	mux.Handle("/readyz", newReadyzHandler(ready))
+	mux.Handle(cfg.AuthPath, newAuthHandler(middleware))
+	mux.Handle(cfg.StartPath, newStartHandler(middleware))
+	mux.Handle(cfg.OIDC.CallbackURL, newCallbackHandler(middleware, cfg.OIDC.CallbackURL))
+	mux.Handle(cfg.OIDC.LogoutURL, newLogoutHandler(middleware, cfg.OIDC.LogoutURL))
+	return mux
+}
+
+// buildServer wraps the mux in an http.Server with sensible timeouts.
+func buildServer(cfg *Config, mux http.Handler) *http.Server { //nolint:unused // consumed by main.go in Task 9
+	return &http.Server{
+		Addr:              cfg.Listen,
+		Handler:           mux,
+		ReadHeaderTimeout: 10 * time.Second,
+		WriteTimeout:      30 * time.Second,
+		IdleTimeout:       120 * time.Second,
+	}
+}
+
+// shutdown gracefully stops the server with a 15s deadline.
+func shutdown(srv *http.Server) error { //nolint:unused // consumed by main.go in Task 9
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	return srv.Shutdown(ctx)
+}

cmd/oidcgate/server_test.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestMux_RoutesAllEndpoints(t *testing.T) {
+	stub := &stubMiddleware{
+		fn: func(rw http.ResponseWriter, _ *http.Request) { rw.WriteHeader(http.StatusOK) },
+	}
+	mux := buildMux(&Config{
+		Listen:    ":0",
+		AuthPath:  "/oauth2/auth",
+		StartPath: "/oauth2/start",
+		OIDC: traefikoidcConfigStub{
+			callbackURL: "/oauth2/callback",
+			logoutURL:   "/oauth2/logout",
+		}.AsOIDC(),
+	}, stub, &readyStub{ready: true})
+
+	cases := []struct {
+		path   string
+		method string
+		want   int
+	}{
+		{"/healthz", http.MethodGet, http.StatusOK},
+		{"/readyz", http.MethodGet, http.StatusOK},
+		{"/oauth2/auth", http.MethodGet, http.StatusOK},
+		{"/oauth2/start", http.MethodGet, http.StatusOK},
+		{"/oauth2/callback", http.MethodGet, http.StatusOK},
+		{"/oauth2/logout", http.MethodPost, http.StatusOK},
+	}
+	for _, c := range cases {
+		rec := httptest.NewRecorder()
+		mux.ServeHTTP(rec, httptest.NewRequest(c.method, c.path, nil))
+		if rec.Code != c.want {
+			t.Errorf("%s %s: want %d, got %d", c.method, c.path, c.want, rec.Code)
+		}
+	}
+}

cmd/oidcgate/success.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"net/http"
+	"strings"
+)
+
+// mirrorAllowedHeaders is the set of NON-X-prefixed request headers that the
+// success handler copies onto the response. The traefikoidc middleware sets
+// "Authorization: Bearer ..." via the templated-header feature when operators
+// configure it, and proxies need that to flow upstream.
+var mirrorAllowedHeaders = map[string]struct{}{
+	"Authorization": {},
+}
+
+// successHandler is the http.Handler installed as the middleware's `next`.
+// When the middleware reaches this handler the request is authenticated; we
+// mirror the X-* (and a small allow-list of non-X-*) headers the middleware
+// stamped onto req.Header back onto the response so upstream proxies can
+// capture them via auth_request_set / authResponseHeaders / copy_headers,
+// then write 200 with an empty body.
+func newSuccessHandler() http.Handler {
+	return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
+		for name, values := range req.Header {
+			if !shouldMirror(name) {
+				continue
+			}
+			for _, v := range values {
+				rw.Header().Add(name, v)
+			}
+		}
+		rw.WriteHeader(http.StatusOK)
+	})
+}
+
+func shouldMirror(name string) bool {
+	if strings.HasPrefix(name, "X-") {
+		return true
+	}
+	canonical := http.CanonicalHeaderKey(name)
+	_, ok := mirrorAllowedHeaders[canonical]
+	return ok
+}

cmd/oidcgate/success_test.go

@@ -0,0 +1,70 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestSuccessHandler_Writes200(t *testing.T) {
+	h := newSuccessHandler()
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status: want 200, got %d", rec.Code)
+	}
+}
+
+func TestSuccessHandler_MirrorsForwardedHeaders(t *testing.T) {
+	h := newSuccessHandler()
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	req.Header.Set("X-Forwarded-User", "alice@example.com")
+	req.Header.Set("X-Forwarded-Email", "alice@example.com")
+	req.Header.Set("X-Custom-Templated", "value")
+	req.Header.Set("Authorization", "Bearer token-from-template")
+	req.Header.Set("Cookie", "session=should-NOT-mirror")
+
+	h.ServeHTTP(rec, req)
+
+	if got := rec.Header().Get("X-Forwarded-User"); got != "alice@example.com" {
+		t.Errorf("X-Forwarded-User: want mirrored, got %q", got)
+	}
+	if got := rec.Header().Get("X-Forwarded-Email"); got != "alice@example.com" {
+		t.Errorf("X-Forwarded-Email: want mirrored, got %q", got)
+	}
+	if got := rec.Header().Get("X-Custom-Templated"); got != "value" {
+		t.Errorf("X-Custom-Templated: want mirrored (X- prefix), got %q", got)
+	}
+	if got := rec.Header().Get("Authorization"); got != "Bearer token-from-template" {
+		t.Errorf("Authorization: want mirrored (templated bearer), got %q", got)
+	}
+	if got := rec.Header().Get("Cookie"); got != "" {
+		t.Errorf("Cookie must NOT be mirrored, got %q", got)
+	}
+}
+
+func TestSuccessHandler_EmptyBody(t *testing.T) {
+	h := newSuccessHandler()
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	h.ServeHTTP(rec, req)
+	if body := strings.TrimSpace(rec.Body.String()); body != "" {
+		t.Fatalf("body: want empty, got %q", body)
+	}
+}
+
+func TestSuccessHandler_MultiValueHeader(t *testing.T) {
+	h := newSuccessHandler()
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	req.Header.Add("X-Role", "admin")
+	req.Header.Add("X-Role", "editor")
+	h.ServeHTTP(rec, req)
+	got := rec.Header()["X-Role"]
+	if len(got) != 2 || got[0] != "admin" || got[1] != "editor" {
+		t.Errorf("X-Role multi-value: want [admin editor], got %v", got)
+	}
+}

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

@@ -14,6 +14,7 @@ Complete reference for all Traefik OIDC middleware configuration options.
 - [Security Headers](#security-headers)
 - [Scope Configuration](#scope-configuration)
 - [Advanced Options](#advanced-options)
+- [Standalone binary (oidcgate)](#standalone-binary-oidcgate)
 
 ---
 
@@ -261,6 +262,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
@@ -644,3 +665,19 @@ sessionEncryptionKey: ${OIDC_SECRET_API}
 # Good
 sessionEncryptionKey: ${OIDC_SECRET_SVC}
 ```
+
+---
+
+## Standalone binary (oidcgate)
+
+If you don't run Traefik, the same configuration shape documented above
+works for the [`oidcgate`](OIDCGATE.md) standalone forward-auth daemon
+under `cmd/oidcgate`. Three extra top-level keys (`listen`, `authPath`,
+`startPath`) configure the daemon itself; everything else maps 1:1 onto
+the `traefikoidc.Config` fields documented in this reference.
+
+See [`docs/OIDCGATE.md`](OIDCGATE.md) for the full daemon guide including
+nginx, Caddy, Traefik ForwardAuth, HAProxy and Envoy wiring snippets,
+the `OIDCGATE_*` environment-variable inventory, the security posture
+(X-Forwarded-Uri sanitisation, excludedURLs guardrail), and how to layer
+M2M [bearer-token auth](BEARER_AUTH.md) on the same daemon.

docs/OIDCGATE.md

@@ -0,0 +1,362 @@
+# oidcgate — standalone OIDC forward-auth daemon
+
+`oidcgate` is a single binary that exposes the same OIDC middleware that
+powers the Traefik plugin as a forward-auth daemon for nginx, Caddy,
+Traefik ForwardAuth, HAProxy, and Envoy `ext_authz_http`.
+
+## Table of contents
+
+- [Build](#build)
+- [Run](#run)
+- [Configuration](#configuration)
+  - [YAML file](#yaml-file)
+  - [Environment-variable overrides](#environment-variable-overrides)
+- [Endpoints](#endpoints)
+- [Reverse-proxy snippets](#reverse-proxy-snippets)
+  - [nginx (`auth_request`)](#nginx-auth_request)
+  - [Caddy (`forward_auth`)](#caddy-forward_auth)
+  - [Traefik (`ForwardAuth`)](#traefik-forwardauth)
+  - [HAProxy](#haproxy)
+  - [Envoy (`ext_authz_http`)](#envoy-ext_authz_http)
+- [Security posture](#security-posture)
+- [Bearer-token (M2M) auth on the same daemon](#bearer-token-m2m-auth-on-the-same-daemon)
+- [Operational guidance](#operational-guidance)
+- [Debugging](#debugging)
+
+## Build
+
+```bash
+go build -o oidcgate ./cmd/oidcgate
+```
+
+## Run
+
+```bash
+./oidcgate --config /etc/oidcgate/config.yaml
+```
+
+The daemon parses `--config`, loads YAML, applies any `OIDCGATE_*` env-var
+overrides, validates the result, and binds to `listen`. On SIGINT/SIGTERM it
+calls `http.Server.Shutdown` with a 15s deadline, draining in-flight requests.
+
+## Configuration
+
+### YAML file
+
+The OIDC subtree of the config maps 1:1 onto the [`traefikoidc.Config`](CONFIGURATION.md)
+struct — every field documented under "Configuration Reference" works here
+verbatim. Three extra top-level keys configure the daemon itself:
+
+| Key | Default | Purpose |
+|---|---|---|
+| `listen` | _required_ | TCP address (e.g. `:8080`, `127.0.0.1:8080`). |
+| `authPath` | `/oauth2/auth` | Silent-probe endpoint (used by nginx `auth_request`). |
+| `startPath` | `/oauth2/start` | Visible sign-in endpoint. |
+
+Minimal example (see [`examples/oidcgate.yaml`](../examples/oidcgate.yaml)):
+
+```yaml
+listen: ":8080"
+providerURL: "https://accounts.google.com"
+clientID: "your-client-id"
+clientSecret: "your-client-secret"
+sessionEncryptionKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+callbackURL: "/oauth2/callback"
+logoutURL: "/oauth2/logout"
+```
+
+Nested structs (`redis:`, `securityHeaders:`, `dynamicClientRegistration:`)
+round-trip cleanly through YAML — same shape as in `.traefik.yml`.
+
+### Environment-variable overrides
+
+Any of the following scalar fields can be overridden at runtime by an
+`OIDCGATE_<UPPER_SNAKE_CASE>` environment variable. The env var wins over
+the YAML value when set and non-empty. Intended for secret injection
+(K8s `valueFrom.secretKeyRef`, systemd `EnvironmentFile=`, etc.).
+
+| YAML key | Env var |
+|---|---|
+| `listen` | `OIDCGATE_LISTEN` |
+| `authPath` | `OIDCGATE_AUTH_PATH` |
+| `startPath` | `OIDCGATE_START_PATH` |
+| `providerURL` | `OIDCGATE_PROVIDER_URL` |
+| `clientID` | `OIDCGATE_CLIENT_ID` |
+| `clientSecret` | `OIDCGATE_CLIENT_SECRET` |
+| `audience` | `OIDCGATE_AUDIENCE` |
+| `callbackURL` | `OIDCGATE_CALLBACK_URL` |
+| `logoutURL` | `OIDCGATE_LOGOUT_URL` |
+| `postLogoutRedirectURI` | `OIDCGATE_POST_LOGOUT_REDIRECT_URI` |
+| `sessionEncryptionKey` | `OIDCGATE_SESSION_ENCRYPTION_KEY` |
+| `cookiePrefix` | `OIDCGATE_COOKIE_PREFIX` |
+| `cookieDomain` | `OIDCGATE_COOKIE_DOMAIN` |
+| `logLevel` | `OIDCGATE_LOG_LEVEL` |
+| `revocationURL` | `OIDCGATE_REVOCATION_URL` |
+| `oidcEndSessionURL` | `OIDCGATE_OIDC_END_SESSION_URL` |
+| `userIdentifierClaim` | `OIDCGATE_USER_IDENTIFIER_CLAIM` |
+| `groupClaimName` | `OIDCGATE_GROUP_CLAIM_NAME` |
+| `roleClaimName` | `OIDCGATE_ROLE_CLAIM_NAME` |
+| `clientAuthMethod` | `OIDCGATE_CLIENT_AUTH_METHOD` |
+| `clientAssertionPrivateKey` | `OIDCGATE_CLIENT_ASSERTION_PRIVATE_KEY` |
+| `clientAssertionKeyPath` | `OIDCGATE_CLIENT_ASSERTION_KEY_PATH` |
+| `clientAssertionKeyID` | `OIDCGATE_CLIENT_ASSERTION_KEY_ID` |
+| `clientAssertionAlg` | `OIDCGATE_CLIENT_ASSERTION_ALG` |
+| `caCertPath` | `OIDCGATE_CA_CERT_PATH` |
+| `caCertPEM` | `OIDCGATE_CA_CERT_PEM` |
+
+Nested-struct fields (Redis, security headers, DCR) are YAML-only — set
+them in the config file, not via env.
+
+## Endpoints
+
+| Path | Method | Purpose |
+|---|---|---|
+| `/oauth2/auth` | GET | Silent probe — `200` if authenticated, `401` if not. Never returns `302`; the middleware's redirect-to-IdP is rewritten in-flight to `401` with the original `Location` carried as `X-Auth-Redirect`. |
+| `/oauth2/start` | GET | Visible sign-in — `302` to the IdP authorize URL. Accepts `?rd=<safe-path>` (or honours `X-Forwarded-Uri`) for the post-login redirect target. |
+| `/oauth2/callback` | GET | IdP `code`+`state` exchange. Path is configurable via `callbackURL`. |
+| `/oauth2/logout` | GET/POST | Terminates the session. Path is configurable via `logoutURL`. Honours `oidcEndSessionURL` for RP-initiated logout. |
+| `/healthz` | GET | Liveness — `200` while the process is alive. |
+| `/readyz` | GET | Readiness — `200` once the OIDC discovery document has been fetched, otherwise `503`. |
+
+## Reverse-proxy snippets
+
+### nginx (`auth_request`)
+
+```nginx
+location = /oauth2/auth {
+    internal;
+    proxy_pass              http://oidcgate:8080;
+    proxy_pass_request_body off;
+    proxy_set_header        Content-Length "";
+    proxy_set_header        X-Forwarded-Uri $request_uri;
+    proxy_set_header        X-Forwarded-Host $host;
+    proxy_set_header        X-Forwarded-Proto $scheme;
+}
+location @oidc_signin {
+    return 302 /oauth2/start?rd=$scheme://$host$request_uri;
+}
+location /oauth2/ {
+    proxy_pass       http://oidcgate:8080;
+    proxy_set_header X-Forwarded-Host  $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+location / {
+    auth_request           /oauth2/auth;
+    error_page             401 = @oidc_signin;
+    auth_request_set       $user  $upstream_http_x_forwarded_user;
+    auth_request_set       $email $upstream_http_x_forwarded_email;
+    proxy_set_header       X-Forwarded-User  $user;
+    proxy_set_header       X-Forwarded-Email $email;
+    proxy_pass             http://backend;
+}
+```
+
+### Caddy (`forward_auth`)
+
+```caddyfile
+example.com {
+    forward_auth oidcgate:8080 {
+        uri /oauth2/auth
+        copy_headers X-Forwarded-User X-Forwarded-Email
+        @denied status 401
+        handle_response @denied {
+            redir /oauth2/start?rd={http.request.uri} 302
+        }
+    }
+    handle /oauth2/* {
+        reverse_proxy oidcgate:8080
+    }
+    reverse_proxy backend:3000
+}
+```
+
+### Traefik (`ForwardAuth`)
+
+```yaml
+http:
+  middlewares:
+    oidcgate:
+      forwardAuth:
+        address: "http://oidcgate:8080/oauth2/auth"
+        authResponseHeaders:
+          - X-Forwarded-User
+          - X-Forwarded-Email
+```
+
+Traefik can follow the `X-Auth-Redirect` value via a chained `redirectScheme`
+middleware, or you can configure the upstream router to redirect `401` →
+`/oauth2/start` directly.
+
+### HAProxy
+
+```haproxy
+frontend fe_https
+    bind *:443 ssl crt /etc/haproxy/certs/site.pem
+    http-request set-var(req.orig_uri) path
+    http-request send-spoe-group oidc auth-check  # or use lua/SPOE; simplest is the lua snippet below
+
+    # The simpler pattern: dispatch /oauth2/* to oidcgate, everything else
+    # goes through a Lua filter that issues a sub-request to /oauth2/auth.
+    acl is_oidc_endpoint path_beg /oauth2/
+    use_backend be_oidcgate if is_oidc_endpoint
+    default_backend be_app
+
+backend be_oidcgate
+    server oidcgate1 oidcgate:8080
+
+backend be_app
+    server app1 backend:3000
+```
+
+HAProxy does not have a first-class `auth_request` equivalent in pure
+config — the canonical patterns are SPOE (Stream Processing Offload Engine),
+a Lua filter that issues `/oauth2/auth` and reads the response, or a
+sidecar that does the dance. Reach for SPOE for high-throughput
+production; Lua is simpler for low-volume.
+
+### Envoy (`ext_authz_http`)
+
+```yaml
+http_filters:
+  - name: envoy.filters.http.ext_authz
+    typed_config:
+      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
+      transport_api_version: V3
+      http_service:
+        server_uri:
+          uri: http://oidcgate:8080
+          cluster: oidcgate
+          timeout: 2s
+        path_prefix: /oauth2/auth
+        authorization_request:
+          allowed_headers:
+            patterns:
+              - exact: cookie
+              - exact: authorization
+              - prefix: x-forwarded-
+        authorization_response:
+          allowed_upstream_headers:
+            patterns:
+              - exact: x-forwarded-user
+              - exact: x-forwarded-email
+          allowed_client_headers:
+            patterns:
+              - exact: x-auth-redirect
+              - exact: set-cookie
+```
+
+On `401`, the `X-Auth-Redirect` header is surfaced to the downstream client
+via `allowed_client_headers`. A small Envoy `router` filter or
+`local_reply_config` rule can convert that into a browser-facing `302`
+redirect to `/oauth2/start`.
+
+## Security posture
+
+- **`X-Forwarded-Uri` is sanitised.** The daemon forces
+  `TrustForwardedURI=true` so the middleware honours `X-Forwarded-Uri` for
+  the post-login redirect target. To prevent open redirects (CWE-601),
+  the value is rejected unless it is a safe same-origin path: must start
+  with `/`, must NOT start with `//` (protocol-relative), and must have
+  no scheme or host after parsing. Absolute URLs or anything that could
+  redirect off-origin falls through to `req.URL.RequestURI()`.
+
+- **`excludedURLs` cannot bypass the daemon's own paths.** At config
+  load, the loader rejects any `excludedURLs` entry that is a prefix of
+  `authPath`, `startPath`, `callbackURL`, `logoutURL`, or the internal
+  sentinel path. A misconfiguration like `excludedURLs: ["/"]` (common
+  "allow all then add auth selectively" mistake) is rejected at startup
+  with a descriptive error.
+
+- **`callbackURL` and `logoutURL` must be paths.** Absolute URLs are
+  rejected at config load — both because `http.ServeMux.Handle` panics
+  on non-`/` patterns and because the middleware's path-match would
+  silently fail.
+
+- **`listen` is required.** Empty or missing `listen` is rejected at
+  startup rather than failing later at `net.Listen`.
+
+- **Secrets via env vars.** `clientSecret` and `sessionEncryptionKey`
+  can be supplied via env vars instead of YAML so they don't end up on
+  disk if you use a secret manager.
+
+## Bearer-token (M2M) auth on the same daemon
+
+oidcgate uses the full `traefikoidc.Config` shape, so the bearer-token
+M2M auth path documented in [`BEARER_AUTH.md`](BEARER_AUTH.md) works
+out of the box. Add to your YAML:
+
+```yaml
+enableBearerAuth: true
+audience: "https://api.example.com"
+bearerIdentifierClaim: "sub"
+# stripAuthorizationHeader: true   # default
+# bearerOverridesCookie: false     # default — cookie wins on collision
+```
+
+With this set, the daemon accepts both:
+- Browser users hitting `/oauth2/auth` → cookie session flow.
+- API clients calling the protected backend with `Authorization: Bearer <jwt>`
+  → bearer validation, principal headers, no session.
+
+The bearer path doesn't go through `/oauth2/auth` separately — it's
+applied by the middleware on every request the daemon sees, before the
+cookie session check. See [BEARER_AUTH.md](BEARER_AUTH.md) for the full
+threat model, identifier sanitisation rules, and failure-response
+matrix.
+
+## Operational guidance
+
+- **Run behind a fronting proxy on a private network.** The daemon does
+  not terminate TLS. Put it on a localhost socket or a private subnet
+  reachable only from your nginx/Caddy/Traefik/HAProxy/Envoy.
+- **`/healthz` and `/readyz` are unauthenticated** — correct for
+  Kubernetes liveness/readiness probes, but **do not expose them past a
+  load balancer**. Restrict via an ACL: nginx `allow 10.0.0.0/8; deny
+  all;`, Caddy `@health remote_ip 10.0.0.0/8`, k8s NetworkPolicy, or
+  your CNI of choice.
+- **Multi-replica deployments** need a shared session store. Enable the
+  `redis:` block in the config (see [`docs/REDIS.md`](REDIS.md)) so
+  sessions survive a hop between replicas.
+- **No built-in Prometheus metrics yet.** If you need request-level
+  visibility, take it from your fronting proxy's access logs — both
+  nginx and Envoy can tag `auth_request` / `ext_authz` outcomes.
+- **Logs are minimal by default.** Set `logLevel: debug` while
+  bringing up a new deployment; raise to `info` (default) or higher
+  once stable. Debug logs include path-match decisions and metadata
+  refresh outcomes.
+- **Graceful shutdown is 15s.** SIGINT or SIGTERM triggers
+  `http.Server.Shutdown(ctx)` with a 15-second deadline; in-flight
+  requests are allowed to complete. If your orchestrator's grace
+  period is shorter, requests can be cut mid-flight.
+
+## Debugging
+
+- **Requests appear as `/__oidcgate_protected__` in middleware debug
+  logs.** This is the internal sentinel path used when `/oauth2/auth`
+  and `/oauth2/start` delegate into the traefikoidc middleware. The
+  upstream client never sees it; it only shows up in the middleware's
+  own `Debugf` output when `logLevel: debug` is set.
+
+- **`/oauth2/auth` returns `401` with `X-Auth-Redirect` header on
+  unauthenticated requests.** This is the deliberate translation of the
+  middleware's `302` to make nginx `auth_request` work. The browser is
+  redirected via the fronting proxy's `error_page 401 = @oidc_signin;`
+  pattern, not by following the daemon's response directly.
+
+- **`/readyz` stays `503` after startup.** The middleware fetches the
+  OIDC discovery document lazily on first request, so `/readyz` returns
+  `503` until at least one request has triggered metadata discovery.
+  Hit `/oauth2/auth` once after startup to warm it up — many K8s
+  setups achieve the same effect because the liveness probe already
+  goes through the proxy chain.
+
+- **Cookie/session diagnostics.** With `logLevel: debug` the middleware
+  logs which session manager was selected (in-memory vs Redis), whether
+  cookies decrypted successfully, and the JWT validation outcome.
+
+- **Open-redirect rejections are silent.** When the daemon ignores an
+  unsafe `X-Forwarded-Uri` value, it falls back to `req.URL.RequestURI()`
+  without logging. This is intentional (no recon signal) — if a user
+  reports "I keep landing on the wrong page after login", inspect
+  whether the upstream proxy is forwarding a non-canonical
+  `X-Forwarded-Uri` value.

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.

docs/superpowers/specs/2026-05-19-oidcgate-design.md

@@ -0,0 +1,173 @@
+# oidcgate — Standalone OIDC Forward-Auth Daemon (Tier 1)
+
+**Date:** 2026-05-19
+**Status:** Design approved, pending implementation plan
+**Scope:** Tier 1 only — forward-auth daemon. No reverse-proxy mode, no TLS termination, no metrics, no multi-tenancy.
+
+## Goal
+
+Provide a standalone Go binary that exposes the existing `traefikoidc` OIDC middleware as a forward-auth daemon callable from nginx (`auth_request`), Caddy (`forward_auth`), Traefik (`ForwardAuth`), HAProxy, and Envoy (`ext_authz_http`). The library's public surface is **additive only**: no existing exported function signature changes; one optional `Config` field (`TrustForwardedURI`) and one new read-only accessor on `*TraefikOidc` are added. Existing Traefik plugin users see no behavior change unless they opt in to the new field.
+
+## Non-Goals
+
+- Reverse-proxy mode (Tier 2 — separate effort if requested).
+- TLS termination inside the daemon.
+- Built-in Prometheus metrics.
+- Multi-tenant routing (one binary serves one OIDC client config).
+- oauth2-proxy CLI/flag compatibility.
+- Docker image or goreleaser publishing as part of Tier 1.
+
+## Architecture
+
+### File layout
+
+```
+github.com/lukaszraczylo/traefikoidc          (library, unchanged)
+├── main.go                                    (existing New/NewWithContext)
+├── middleware.go                              (existing ServeHTTP + ~10 LoC patch)
+└── cmd/
+    └── oidcgate/
+        ├── main.go                            (entrypoint, flags, signal handling)
+        ├── config.go                          (YAML loader + env-var override walker)
+        ├── server.go                          (http.ServeMux wiring, listen loop)
+        ├── endpoints.go                       (auth/start/callback/logout handlers)
+        ├── success.go                         (synthetic success handler used as `next`)
+        ├── interceptor.go                     (302→401 response-writer for /oauth2/auth)
+        ├── health.go                          (/healthz, /readyz)
+        ├── config_test.go
+        ├── endpoints_test.go
+        └── interceptor_test.go
+```
+
+### Process model
+
+Single binary, single `*TraefikOidc` instance built at boot from YAML config, served on one listener port. Health endpoints on the same listener. Graceful shutdown on `SIGINT`/`SIGTERM` via `srv.Shutdown(ctx)` with a 15s deadline, after which context cancellation propagates into the existing goroutine manager.
+
+## Endpoint Contract
+
+All four endpoints share the listener. Paths are configurable; defaults shown.
+
+| Endpoint | Default path | Method | Contract |
+|---|---|---|---|
+| **Auth probe** | `/oauth2/auth` | GET | Silent. `200 OK` + injected headers on success. `401` on failure (never `302`). Consumed by nginx `auth_request`, Traefik ForwardAuth, Caddy `forward_auth`, Envoy ext_authz_http. |
+| **Sign-in** | `/oauth2/start` | GET | Always `302` to IdP `authorize` URL with `state`+`nonce`+PKCE. Reads target URL from `?rd=` query or `X-Forwarded-Uri` header. Hit by the browser after a `401` from `/oauth2/auth`. |
+| **Callback** | `config.callbackURL` | GET | IdP `code`+`state` exchange. Existing `auth_flow.go` logic runs unchanged. On success → `302` to original URL. |
+| **Logout** | `config.logoutURL` | GET/POST | Existing `logout.go` handler. Terminates session. Honors `oidcEndSessionURL` if configured. |
+
+### Wiring (how each endpoint delegates)
+
+All four handlers feed `(*TraefikOidc).ServeHTTP` after rewriting `req.URL.Path`:
+
+- `/oauth2/callback` → rewrite to `config.callbackURL`, delegate. Middleware path-match at `middleware.go` triggers callback flow.
+- `/oauth2/logout` → rewrite to `config.logoutURL`, delegate. Middleware logout path-match at the top of `ServeHTTP` triggers.
+- `/oauth2/start` → rewrite `req.URL.Path` to the sentinel `/__oidcgate_protected__`, delegate. Middleware sees an unauthenticated GET on a protected path, emits the `302` to IdP. The redirect flows through naturally.
+- `/oauth2/auth` → rewrite `req.URL.Path` to `/__oidcgate_protected__`, wrap `ResponseWriter` with an interceptor (see below), delegate.
+
+The sentinel path `/__oidcgate_protected__` is chosen because it cannot collide with `callbackURL` / `logoutURL` / `/health*` path matches inside `ServeHTTP` and is not a likely user-configured `excludedURLs` entry. It is internal-only: clients never see it.
+
+### Synthetic `next` handler
+
+The middleware calls `t.next.ServeHTTP(rw, req)` at four sites (`middleware.go:174,185,187,592`) when the request is authenticated and should be forwarded. The daemon supplies a `next` that:
+
+1. Writes `200 OK`.
+2. Mirrors any `X-Forwarded-*` and templated headers that the middleware set on `req.Header` (e.g. `X-Forwarded-User` at `middleware.go:101,512`) onto the **response** headers, so proxies can capture them via `auth_request_set` / `authResponseHeaders`.
+3. Writes empty body.
+
+### 302 → 401 interceptor (`/oauth2/auth` only)
+
+nginx `auth_request` cannot follow `302`s. For the silent endpoint, the daemon wraps the `ResponseWriter` such that:
+
+- If the middleware writes status `302` (the IdP-redirect branch), the interceptor rewrites it to `401`.
+- `Location` header from the swallowed `302` is preserved as `X-Auth-Redirect` on the `401` response (advisory; some proxies may surface it).
+- `Set-Cookie` headers (state, PKCE, nonce) are preserved verbatim so the browser carries them into the subsequent `/oauth2/start` request.
+- For any non-`302` status, the interceptor is a passthrough.
+
+`/oauth2/start` does **not** wrap; the middleware's natural `302` flows through to the browser.
+
+## Configuration
+
+### Source
+
+- **File:** `--config /etc/oidcgate/config.yaml` (path overridable via flag).
+- **Format:** YAML, unmarshalled into the existing `traefikoidc.Config` struct (`settings.go:39`) via `yaml.v3` (already a dependency in `go.mod`).
+- **Migration from Traefik:** copy the `plugin.traefikoidc:` subtree out of `.traefik.yml` and add the daemon-specific top-level keys below.
+- **Env-var overrides** (secrets in particular): after YAML unmarshal, walk the config struct. Any scalar string/int/bool field with a non-empty `OIDCGATE_<UPPER_SNAKE_CASE_FIELD>` env-var replaces the YAML value. Nested structs (`Redis`, `SecurityHeaders`, `DynamicClientRegistration`) stay YAML-only.
+
+### Top-level oidcgate-specific keys
+
+```yaml
+listen: ":8080"            # required, listener address
+authPath: "/oauth2/auth"   # optional, default shown
+startPath: "/oauth2/start" # optional, default shown
+# all other keys = existing traefikoidc.Config fields
+```
+
+### Validation
+
+The existing validation inside `traefikoidc.NewWithContext` (`main.go:97`) runs unchanged. On any returned error, the daemon logs the error and exits non-zero.
+
+## Library-Side Patches
+
+Two additive changes, both default-off / read-only:
+
+1. **`settings.go` + `middleware.go` (~10 LoC):** add `Config.TrustForwardedURI bool` (default `false`). When `true`, the post-login-redirect target captured during the "unauthenticated GET → 302 to IdP" branch is sourced from `req.Header.Get("X-Forwarded-Uri")` if non-empty, instead of from `req.URL`. The daemon sets `TrustForwardedURI = true` at config build time. Default-off preserves current Traefik plugin behavior exactly.
+
+2. **`main.go` (~5 LoC):** add `func (t *TraefikOidc) Ready() bool` returning `true` once at least one successful OIDC metadata discovery fetch has populated the metadata cache. Read-only; no behavior change for existing consumers.
+
+## Lifecycle
+
+```
+parse flags
+  → load YAML
+  → apply env-var overrides
+  → build synthetic success handler
+  → call traefikoidc.New(ctx, success, cfg, "oidcgate")  (validation happens here)
+  → build mux (auth, start, callback, logout, healthz, readyz)
+  → http.Server.ListenAndServe on cfg.listen
+  → wait for SIGINT/SIGTERM
+  → srv.Shutdown(15s ctx)
+  → ctx cancel propagates to goroutine manager
+  → exit 0
+```
+
+`/readyz` returns `200` only once `traefikoidc.New` has returned without error **and** the first OIDC metadata discovery fetch has succeeded. Implementation: add a read-only accessor `func (t *TraefikOidc) Ready() bool` that returns `true` once the metadata cache has at least one successful discovery fetch. The daemon's `/readyz` handler calls this and returns `200` / `503` accordingly.
+
+`/healthz` returns `200` as long as the process is alive.
+
+## Testing
+
+- `config_test.go` — YAML round-trip; env-var override precedence; validation pass-through.
+- `endpoints_test.go` — `httptest.NewServer`-based scenarios:
+  - `/oauth2/auth` with no session → `401`.
+  - `/oauth2/auth` with valid session → `200` + `X-Forwarded-User` mirrored on response.
+  - `/oauth2/start` → `302` with valid IdP `authorize` URL incl. `state` and PKCE.
+  - `/oauth2/callback` → completes exchange, sets session, redirects to original URL.
+  - `/oauth2/logout` → clears session cookie.
+- `interceptor_test.go` — middleware-emitted `302` becomes `401`; `Location` → `X-Auth-Redirect`; `Set-Cookie` preserved.
+- Reuse existing mock IdP from `enhanced_mocks_test.go`. No new mock infra.
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Interceptor swallows a legitimate `302` from the middleware that isn't the IdP redirect. | Inspect: only intercept when `Location` matches `t.providerURL`'s authorize endpoint or when it points off-host. Test coverage in `interceptor_test.go`. |
+| Library-side patch breaks current Traefik users. | New `TrustForwardedURI` defaults to `false`; existing path untouched when unset. |
+| Env-var walker overreaches into nested structs. | Restrict to top-level scalar fields; document explicitly; nested structs stay YAML-only. |
+| Path-rewrite trick hits a middleware path-comparison we didn't anticipate. | All four `t.next.ServeHTTP` sites verified at `middleware.go:174,185,187,592`. Endpoint tests exercise each path. |
+
+## Out of Scope (Tier 2 candidates)
+
+- Reverse-proxy mode (`httputil.ReverseProxy` as the configured `next`).
+- TLS termination (`tls.Config`, ACME).
+- Prometheus metrics endpoint.
+- Multi-tenant routing.
+- oauth2-proxy flag/env compatibility.
+- Goreleaser binaries, Docker image, systemd unit.
+
+## Acceptance Criteria
+
+1. `go build ./cmd/oidcgate` produces a working binary.
+2. Existing test suite (`go test ./...`) still passes — zero regressions in the library.
+3. New endpoint tests pass for all four endpoints against the mock IdP.
+4. `oidcgate --config example.yaml` boots, serves `/healthz`, performs end-to-end OIDC flow against a real IdP (manual smoke test against e.g. a local Keycloak).
+5. README section documents nginx, Caddy, and Traefik wiring examples.

examples/oidcgate.yaml

@@ -0,0 +1,15 @@
+# Minimal oidcgate config. See docs/OIDCGATE.md for full reference.
+listen: ":8080"
+authPath: "/oauth2/auth"
+startPath: "/oauth2/start"
+
+providerURL: "https://accounts.google.com"
+clientID: "REPLACE_ME.apps.googleusercontent.com"
+clientSecret: "REPLACE_ME"            # OR set OIDCGATE_CLIENT_SECRET
+sessionEncryptionKey: "REPLACE_WITH_64_HEX_BYTES" # OR OIDCGATE_SESSION_ENCRYPTION_KEY
+callbackURL: "/oauth2/callback"
+logoutURL: "/oauth2/logout"
+postLogoutRedirectURI: "/"
+
+# allowedUserDomains: [company.com]
+# excludedURLs: [/health, /metrics]

forwarded_uri.go

@@ -0,0 +1,37 @@
+package traefikoidc
+
+import (
+	"net/http"
+	"net/url"
+	"strings"
+)
+
+// originalRequestURI returns the request URI that should be used as the
+// post-login redirect target. When TrustForwardedURI is enabled and the
+// X-Forwarded-Uri header carries a safe same-origin path, that header
+// wins. Otherwise (or if the header is missing/unsafe), falls back to
+// req.URL.RequestURI() — the path the request reached the proxy with.
+//
+// "Safe" means: starts with "/", does NOT start with "//" (protocol-relative
+// URLs can change host), and has no scheme or host after parsing. This
+// prevents an attacker-controllable header from triggering an open redirect
+// via http.Redirect later in the auth flow.
+func (t *TraefikOidc) originalRequestURI(req *http.Request) string {
+	if t.trustForwardedURI {
+		if v := req.Header.Get("X-Forwarded-Uri"); v != "" && isSafeRedirectTarget(v) {
+			return v
+		}
+	}
+	return req.URL.RequestURI()
+}
+
+func isSafeRedirectTarget(v string) bool {
+	if !strings.HasPrefix(v, "/") || strings.HasPrefix(v, "//") {
+		return false
+	}
+	u, err := url.Parse(v)
+	if err != nil {
+		return false
+	}
+	return u.Host == "" && u.Scheme == ""
+}

forwarded_uri_test.go

@@ -0,0 +1,69 @@
+package traefikoidc
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestOriginalRequestURI_DefaultOff(t *testing.T) {
+	tr := &TraefikOidc{trustForwardedURI: false}
+	req := httptest.NewRequest(http.MethodGet, "/protected?x=1", nil)
+	req.Header.Set("X-Forwarded-Uri", "/spoofed")
+	if got := tr.originalRequestURI(req); got != "/protected?x=1" {
+		t.Fatalf("default-off: want /protected?x=1, got %q", got)
+	}
+}
+
+func TestOriginalRequestURI_TrustEnabled(t *testing.T) {
+	tr := &TraefikOidc{trustForwardedURI: true}
+	req := httptest.NewRequest(http.MethodGet, "/protected?x=1", nil)
+	req.Header.Set("X-Forwarded-Uri", "/real?y=2")
+	if got := tr.originalRequestURI(req); got != "/real?y=2" {
+		t.Fatalf("trust-on with header: want /real?y=2, got %q", got)
+	}
+}
+
+func TestOriginalRequestURI_TrustEnabledNoHeader(t *testing.T) {
+	tr := &TraefikOidc{trustForwardedURI: true}
+	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+	if got := tr.originalRequestURI(req); got != "/protected" {
+		t.Fatalf("trust-on no header: want /protected, got %q", got)
+	}
+}
+func TestOriginalRequestURI_RejectsAbsoluteURL(t *testing.T) {
+	tr := &TraefikOidc{trustForwardedURI: true}
+	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+	req.Header.Set("X-Forwarded-Uri", "https://evil.example/phish")
+	if got := tr.originalRequestURI(req); got != "/protected" {
+		t.Fatalf("absolute URL must be rejected, want /protected fallback, got %q", got)
+	}
+}
+
+func TestOriginalRequestURI_RejectsProtocolRelative(t *testing.T) {
+	tr := &TraefikOidc{trustForwardedURI: true}
+	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+	req.Header.Set("X-Forwarded-Uri", "//evil.example/phish")
+	if got := tr.originalRequestURI(req); got != "/protected" {
+		t.Fatalf("protocol-relative URL must be rejected, want /protected fallback, got %q", got)
+	}
+}
+
+func TestOriginalRequestURI_AcceptsSafePathWithQuery(t *testing.T) {
+	tr := &TraefikOidc{trustForwardedURI: true}
+	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+	req.Header.Set("X-Forwarded-Uri", "/safe?x=1&y=2")
+	if got := tr.originalRequestURI(req); got != "/safe?x=1&y=2" {
+		t.Fatalf("safe path with query must be accepted, got %q", got)
+	}
+}
+
+func TestOriginalRequestURI_RejectsBareHostnameNoSlash(t *testing.T) {
+	tr := &TraefikOidc{trustForwardedURI: true}
+	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+	req.Header.Set("X-Forwarded-Uri", "evil.example/phish")
+	if got := tr.originalRequestURI(req); got != "/protected" {
+		t.Fatalf("non-/ prefix must be rejected, got %q", got)
+	}
+}
+

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

main.go

@@ -201,6 +201,7 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		}(),
 		forceHTTPS:                config.ForceHTTPS,
 		enablePKCE:                config.EnablePKCE,
+		trustForwardedURI:         config.TrustForwardedURI,
 		overrideScopes:            config.OverrideScopes,
 		strictAudienceValidation:  config.StrictAudienceValidation,
 		allowOpaqueTokens:         config.AllowOpaqueTokens,
@@ -239,23 +240,63 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 			}
 			return 0
 		}(),
-		tokenCleanupStopChan:     make(chan struct{}),
-		metadataRefreshStopChan:  make(chan struct{}),
-		ctx:                      pluginCtx,
-		cancelFunc:               cancelFunc,
-		suppressDiagnosticLogs:   isTestMode(),
-		securityHeadersApplier:   config.GetSecurityHeadersApplier(),
-		scopeFilter:              NewScopeFilter(logger), // NEW - for discovery-based scope filtering
-		dcrConfig:                config.DynamicClientRegistration,
-		allowPrivateIPAddresses:  config.AllowPrivateIPAddresses,
-		minimalHeaders:           config.MinimalHeaders,
-		stripAuthCookies:         config.StripAuthCookies,
-		enableBackchannelLogout:  config.EnableBackchannelLogout,
-		enableFrontchannelLogout: config.EnableFrontchannelLogout,
-		backchannelLogoutPath:    normalizeLogoutPath(config.BackchannelLogoutURL),
-		frontchannelLogoutPath:   normalizeLogoutPath(config.FrontchannelLogoutURL),
-		sessionInvalidationCache: cacheManager.GetSharedSessionInvalidationCache(),
-		refreshResultCache:       cacheManager.GetSharedRefreshResultCache(),
+		tokenCleanupStopChan:      make(chan struct{}),
+		metadataRefreshStopChan:   make(chan struct{}),
+		ctx:                       pluginCtx,
+		cancelFunc:                cancelFunc,
+		suppressDiagnosticLogs:    isTestMode(),
+		securityHeadersApplier:    config.GetSecurityHeadersApplier(),
+		scopeFilter:               NewScopeFilter(logger), // NEW - for discovery-based scope filtering
+		dcrConfig:                 config.DynamicClientRegistration,
+		allowPrivateIPAddresses:   config.AllowPrivateIPAddresses,
+		minimalHeaders:            config.MinimalHeaders,
+		stripAuthCookies:          config.StripAuthCookies,
+		enableBackchannelLogout:   config.EnableBackchannelLogout,
+		enableFrontchannelLogout:  config.EnableFrontchannelLogout,
+		backchannelLogoutPath:     normalizeLogoutPath(config.BackchannelLogoutURL),
+		frontchannelLogoutPath:    normalizeLogoutPath(config.FrontchannelLogoutURL),
+		sessionInvalidationCache:  cacheManager.GetSharedSessionInvalidationCache(),
+		refreshResultCache:        cacheManager.GetSharedRefreshResultCache(),
+		enableBearerAuth:          config.EnableBearerAuth,
+		stripAuthorizationHeader:  config.StripAuthorizationHeader,
+		bearerEmitWWWAuthenticate: config.BearerEmitWWWAuthenticate,
+		bearerOverridesCookie:     config.BearerOverridesCookie,
+		bearerIdentifierClaim: func() string {
+			if config.BearerIdentifierClaim != "" {
+				return config.BearerIdentifierClaim
+			}
+			return "sub"
+		}(),
+		maxIdentifierLength: func() int {
+			if config.MaxIdentifierLength > 0 {
+				return config.MaxIdentifierLength
+			}
+			return 256
+		}(),
+		maxTokenAge: func() time.Duration {
+			if config.MaxTokenAgeSeconds > 0 {
+				return time.Duration(config.MaxTokenAgeSeconds) * time.Second
+			}
+			return 24 * time.Hour
+		}(),
+		bearerFailureThreshold: func() int {
+			if config.BearerFailureThreshold > 0 {
+				return config.BearerFailureThreshold
+			}
+			return 20
+		}(),
+		bearerFailureWindow: func() time.Duration {
+			if config.BearerFailureWindowSeconds > 0 {
+				return time.Duration(config.BearerFailureWindowSeconds) * time.Second
+			}
+			return 60 * time.Second
+		}(),
+		bearerFailurePenalty: func() time.Duration {
+			if config.BearerFailurePenaltySeconds > 0 {
+				return time.Duration(config.BearerFailurePenaltySeconds) * time.Second
+			}
+			return 60 * time.Second
+		}(),
 	}
 
 	// Log audience configuration
@@ -265,6 +306,31 @@ func NewWithContext(ctx context.Context, config *Config, next http.Handler, name
 		t.logger.Debugf("No custom audience specified, using clientID as audience: %s", t.clientID)
 	}
 
+	// Bearer-auth startup validation. The bearer path is M2M-only and demands
+	// a non-default audience so tokens issued for a different resource cannot
+	// be replayed against this service. The BearerIdentifierClaim guard blocks
+	// the `email` claim explicitly — without email_verified enforcement (out of
+	// scope for M2M), trusting email is a spoofing vector for federated IdPs.
+	// See spec §7.9 / §13.
+	if config.EnableBearerAuth {
+		if config.Audience == "" {
+			cancelFunc()
+			return nil, fmt.Errorf("EnableBearerAuth=true requires Audience to be set explicitly (cannot default to clientID — that path accepts ID tokens)")
+		}
+		if t.bearerIdentifierClaim == "email" {
+			cancelFunc()
+			return nil, fmt.Errorf("enableBearerAuth=true with bearerIdentifierClaim=%q is rejected: email-based identity without email_verified enforcement is a spoofing vector for federated IdPs (use \"sub\" or a custom claim; cookie-path userIdentifierClaim is unaffected)", t.bearerIdentifierClaim)
+		}
+		if !config.StrictAudienceValidation {
+			t.logger.Infof("EnableBearerAuth=true with StrictAudienceValidation=false: recommend enabling strict audience validation for hardening")
+		}
+		t.bearerFailureTracker = newBearerFailureTracker(
+			t.bearerFailureThreshold, t.bearerFailureWindow, t.bearerFailurePenalty,
+		)
+		t.logger.Infof("Bearer-token auth enabled: audience=%q identifierClaim=%q stripAuthz=%t bearerOverridesCookie=%t maxTokenAge=%s",
+			config.Audience, t.bearerIdentifierClaim, t.stripAuthorizationHeader, t.bearerOverridesCookie, t.maxTokenAge)
+	}
+
 	// Convert sessionMaxAge from seconds to duration (0 will use default 24 hours)
 	sessionMaxAge := time.Duration(config.SessionMaxAge) * time.Second
 	t.sessionManager, _ = NewSessionManager(config.SessionEncryptionKey, config.ForceHTTPS, config.CookieDomain, config.CookiePrefix, sessionMaxAge, t.logger) // Safe to ignore: session manager creation with fallback to defaults

middleware.go

@@ -168,6 +168,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.
@@ -236,6 +244,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)
@@ -401,10 +427,17 @@ 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.
@@ -442,8 +475,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,18 +504,76 @@ func (t *TraefikOidc) processAuthorizedRequest(rw http.ResponseWriter, req *http
 		return
 	}
 
-	var groups, roles []string
+	if groupClaimsErr != nil && len(t.allowedRolesAndGroups) > 0 {
+		// Claims couldn't be extracted but roles checks are required:
+		// re-authenticate rather than 403 (session may be salvageable on
+		// re-issue). Bearer path uses 401 for the equivalent failure.
+		t.logger.Errorf("Failed to extract claims for roles/groups check: %v", groupClaimsErr)
+		session.ResetRedirectCount()
+		t.defaultInitiateAuthentication(rw, req, session, redirectURL)
+		return
+	}
 
-	if groupClaimsErr == nil && groupClaims != nil {
-		var err error
-		groups, roles, err = t.extractGroupsAndRolesFromClaims(groupClaims)
-		if err != nil && len(t.allowedRolesAndGroups) > 0 {
-			t.logger.Errorf("Failed to extract groups and roles: %v", err)
-			session.ResetRedirectCount()
-			t.defaultInitiateAuthentication(rw, req, session, redirectURL)
+	// Persist any dirty session state BEFORE forwardAuthorized writes the
+	// response. Once next.ServeHTTP fires, Set-Cookie can no longer reach
+	// the client. The forwardAuthorized pipeline does not mutate session
+	// state, so saving here is safe.
+	if session.IsDirty() {
+		if err := session.Save(req, rw); err != nil {
+			t.logger.Errorf("Failed to save session after processing headers: %v", err)
+		}
+	} else {
+		t.logger.Debug("Session not dirty, skipping save in processAuthorizedRequest")
+	}
+
+	// Build the source-agnostic principal. ID-token claims drive header
+	// templates and roles when present; otherwise fall back to access-token
+	// claims (matches prior behavior for opaque-ID-token providers).
+	p := &principal{
+		Source:       sourceSession,
+		Identifier:   userIdentifier,
+		AccessToken:  session.GetAccessToken(),
+		IDToken:      idToken,
+		RefreshToken: session.GetRefreshToken(),
+		Claims:       groupClaims,
+	}
+
+	t.forwardAuthorized(rw, req, p)
+}
+
+// forwardAuthorized completes the post-authentication pipeline shared by the
+// cookie/session path and the bearer-token path. It performs:
+//
+//  1. Roles/groups extraction from p.Claims (idempotent; existing
+//     extractGroupsAndRolesFromClaims helper).
+//  2. allowedRolesAndGroups gate — writes a 403 and returns if denied.
+//  3. Identity-header injection (X-Forwarded-User, X-User-Groups, X-User-Roles,
+//     plus X-Auth-Request-* when !minimalHeaders).
+//  4. Operator-defined header templates.
+//  5. Security headers (delegated to t.securityHeadersApplier or fallback).
+//  6. OIDC session-cookie strip (stripAuthCookies).
+//  7. Authorization header strip on bearer source when stripAuthorizationHeader.
+//  8. next.ServeHTTP.
+//
+// Session persistence is the CALLER's responsibility — it must happen before
+// this function so Set-Cookie reaches the response.
+func (t *TraefikOidc) forwardAuthorized(rw http.ResponseWriter, req *http.Request, p *principal) {
+	var (
+		groups, roles []string
+		extractErr    error
+	)
+	if p.Claims != nil {
+		groups, roles, extractErr = t.extractGroupsAndRolesFromClaims(p.Claims)
+		if extractErr != nil && len(t.allowedRolesAndGroups) > 0 {
+			// Bearer path: 403 (caller already verified the token; principal
+			// claims are present but malformed for roles purposes).
+			// Cookie path can't reach here because processAuthorizedRequest
+			// catches groupClaimsErr earlier.
+			t.logger.Errorf("Failed to extract groups and roles: %v", extractErr)
+			t.sendErrorResponse(rw, req, "Access denied", http.StatusForbidden)
 			return
 		}
-		if err == nil {
+		if extractErr == nil {
 			if len(groups) > 0 {
 				req.Header.Set("X-User-Groups", strings.Join(groups, ","))
 			}
@@ -502,62 +592,46 @@ 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)
+	req.Header.Set("X-Forwarded-User", p.Identifier)
 
 	// 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)
+		req.Header.Set("X-Auth-Request-Redirect", t.originalRequestURI(req))
+		req.Header.Set("X-Auth-Request-User", p.Identifier)
+		if p.IDToken != "" {
+			req.Header.Set("X-Auth-Request-Token", p.IDToken)
 		}
 	}
 
 	if len(t.headerTemplates) > 0 {
-		if idClaimsErr != nil {
-			t.logger.Errorf("Failed to extract claims from ID Token for template headers: %v", idClaimsErr)
-		} else {
-			// idClaims may be nil when no ID token is present; templates
-			// referencing .Claims.* will simply produce empty values, which
-			// matches the prior behavior.
-			templateData := map[string]interface{}{
-				"AccessToken":  session.GetAccessToken(),
-				"IDToken":      idToken,
-				"RefreshToken": session.GetRefreshToken(),
-				"Claims":       idClaims,
-			}
-
-			for headerName, tmpl := range t.headerTemplates {
-				var buf bytes.Buffer
-				if err := tmpl.Execute(&buf, templateData); err != nil {
-					t.logger.Errorf("Failed to execute template for header %s: %v", headerName, err)
-					continue
-				}
-				headerValue := buf.String()
-				req.Header.Set(headerName, headerValue)
-				t.logger.Debugf("Set templated header %s = %s", headerName, headerValue)
-			}
-			// NOTE: templates only mutate request headers (not session state),
-			// so we deliberately do NOT MarkDirty / Save here. Previously every
-			// authenticated request with header templates re-encrypted and
-			// rewrote all session cookies, which was a measurable CPU and
-			// Set-Cookie tax on dashboards that poll many panels per second.
+		// p.Claims may be nil (e.g. session without an ID token). Templates
+		// referencing .Claims.* will simply produce empty values — matches
+		// the prior behavior. Bearer-source principals always carry access-
+		// token claims (post-verifyToken).
+		templateData := map[string]interface{}{
+			"AccessToken":  p.AccessToken,
+			"IDToken":      p.IDToken,
+			"RefreshToken": p.RefreshToken,
+			"Claims":       p.Claims,
 		}
-	}
 
-	if session.IsDirty() {
-		if err := session.Save(req, rw); err != nil {
-			t.logger.Errorf("Failed to save session after processing headers: %v", err)
+		for headerName, tmpl := range t.headerTemplates {
+			var buf bytes.Buffer
+			if err := tmpl.Execute(&buf, templateData); err != nil {
+				t.logger.Errorf("Failed to execute template for header %s: %v", headerName, err)
+				continue
+			}
+			headerValue := buf.String()
+			req.Header.Set(headerName, headerValue)
+			t.logger.Debugf("Set templated header %s = %s", headerName, headerValue)
 		}
-	} else {
-		t.logger.Debug("Session not dirty, skipping save in processAuthorizedRequest")
 	}
 
 	// Apply security headers if configured
@@ -573,7 +647,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 +661,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)
 }

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

ready.go

@@ -0,0 +1,12 @@
+package traefikoidc
+
+// Ready reports whether the middleware has completed at least one successful
+// OIDC provider metadata discovery. Used by external supervisors (e.g. the
+// oidcgate /readyz endpoint) to gate traffic until the IdP discovery doc
+// has been fetched and the authorization endpoint is known.
+func (t *TraefikOidc) Ready() bool {
+	t.metadataMu.RLock()
+	u := t.authURL
+	t.metadataMu.RUnlock()
+	return u != ""
+}

ready_test.go

@@ -0,0 +1,20 @@
+package traefikoidc
+
+import "testing"
+
+func TestReady_FalseBeforeMetadata(t *testing.T) {
+	tr := &TraefikOidc{}
+	if tr.Ready() {
+		t.Fatal("Ready() should be false before metadata discovery")
+	}
+}
+
+func TestReady_TrueAfterAuthURLSet(t *testing.T) {
+	tr := &TraefikOidc{}
+	tr.metadataMu.Lock()
+	tr.authURL = "https://idp.example/authorize"
+	tr.metadataMu.Unlock()
+	if !tr.Ready() {
+		t.Fatal("Ready() should be true once authURL is populated")
+	}
+}

settings.go

@@ -63,23 +63,23 @@ type Config struct {
 	// IdPs do not expose RT TTL on the wire, so this is intentionally a
 	// conservative heuristic; tune to match your provider configuration.
 	// Default 21600 (6h). Set to 0 to disable the check.
-	MaxRefreshTokenAgeSeconds int                              `json:"maxRefreshTokenAgeSeconds"`
-	SessionMaxAge             int                              `json:"sessionMaxAge"`
-	RateLimit                 int                              `json:"rateLimit"`
-	OverrideScopes            bool                             `json:"overrideScopes"`
-	DisableReplayDetection    bool                             `json:"disableReplayDetection,omitempty"`
-	RequireTokenIntrospection bool                             `json:"requireTokenIntrospection,omitempty"`
-	AllowOpaqueTokens         bool                             `json:"allowOpaqueTokens,omitempty"`
-	StrictAudienceValidation  bool                             `json:"strictAudienceValidation,omitempty"`
-	EnablePKCE                bool                             `json:"enablePKCE"`
-	ForceHTTPS                bool                             `json:"forceHTTPS"`
-	AllowPrivateIPAddresses   bool                             `json:"allowPrivateIPAddresses,omitempty"`
-	MinimalHeaders            bool                             `json:"minimalHeaders,omitempty"`
-	StripAuthCookies          bool                             `json:"stripAuthCookies,omitempty"`
-	EnableBackchannelLogout   bool                             `json:"enableBackchannelLogout,omitempty"`
-	EnableFrontchannelLogout  bool                             `json:"enableFrontchannelLogout,omitempty"`
-	BackchannelLogoutURL      string                           `json:"backchannelLogoutURL,omitempty"`
-	FrontchannelLogoutURL     string                           `json:"frontchannelLogoutURL,omitempty"`
+	MaxRefreshTokenAgeSeconds int    `json:"maxRefreshTokenAgeSeconds"`
+	SessionMaxAge             int    `json:"sessionMaxAge"`
+	RateLimit                 int    `json:"rateLimit"`
+	OverrideScopes            bool   `json:"overrideScopes"`
+	DisableReplayDetection    bool   `json:"disableReplayDetection,omitempty"`
+	RequireTokenIntrospection bool   `json:"requireTokenIntrospection,omitempty"`
+	AllowOpaqueTokens         bool   `json:"allowOpaqueTokens,omitempty"`
+	StrictAudienceValidation  bool   `json:"strictAudienceValidation,omitempty"`
+	EnablePKCE                bool   `json:"enablePKCE"`
+	ForceHTTPS                bool   `json:"forceHTTPS"`
+	AllowPrivateIPAddresses   bool   `json:"allowPrivateIPAddresses,omitempty"`
+	MinimalHeaders            bool   `json:"minimalHeaders,omitempty"`
+	StripAuthCookies          bool   `json:"stripAuthCookies,omitempty"`
+	EnableBackchannelLogout   bool   `json:"enableBackchannelLogout,omitempty"`
+	EnableFrontchannelLogout  bool   `json:"enableFrontchannelLogout,omitempty"`
+	BackchannelLogoutURL      string `json:"backchannelLogoutURL,omitempty"`
+	FrontchannelLogoutURL     string `json:"frontchannelLogoutURL,omitempty"`
 	// CACertPath is an optional filesystem path to a PEM-encoded CA bundle used
 	// to verify the OIDC provider's TLS certificate. Use this when the provider
 	// is signed by an internal/private CA that is not in the system trust store.
@@ -125,6 +125,59 @@ type Config struct {
 	// ClientAssertionAlg is the JWS signing algorithm. Defaults to RS256.
 	// Supported: RS256/384/512, PS256/384/512, ES256/384/512.
 	ClientAssertionAlg string `json:"clientAssertionAlg,omitempty"`
+
+	// TrustForwardedURI, when true, makes the middleware prefer the
+	// X-Forwarded-Uri request header (set by an upstream reverse proxy)
+	// over req.URL when capturing the "where was the user going" target
+	// stored for post-login redirect. Used by the oidcgate standalone
+	// daemon. Default false preserves the Traefik plugin behavior exactly.
+	TrustForwardedURI bool `json:"trustForwardedURI,omitempty"`
+
+	// --- Bearer-token auth (opt-in M2M path) ---
+
+	// EnableBearerAuth turns on the Authorization: Bearer <jwt> auth path.
+	// Default false. When true, Audience MUST be set or startup fails. The
+	// bearer path is M2M-only: it accepts validated access-token JWTs, rejects
+	// ID tokens, and forwards principal headers downstream without creating a
+	// cookie session. See docs/BEARER_AUTH.md for the threat model.
+	EnableBearerAuth bool `json:"enableBearerAuth,omitempty"`
+	// BearerIdentifierClaim names the JWT claim used as the principal identifier
+	// on the bearer-token auth path. Default "sub". Decoupled from
+	// UserIdentifierClaim (which defaults to "email" and drives the cookie path)
+	// so M2M bearer flow never accidentally relies on an unverified email.
+	BearerIdentifierClaim string `json:"bearerIdentifierClaim,omitempty"`
+	// StripAuthorizationHeader removes the Authorization header from the
+	// forwarded request after successful bearer auth, so downstream services
+	// never see the raw token. Default true. Disable only when a downstream
+	// explicitly needs to re-validate the bearer.
+	StripAuthorizationHeader bool `json:"stripAuthorizationHeader,omitempty"`
+	// BearerEmitWWWAuthenticate controls whether 401 responses on the bearer
+	// path include a WWW-Authenticate: Bearer error="invalid_token" hint per
+	// RFC 6750 §3. Default true. Disable to reduce reconnaissance signal.
+	BearerEmitWWWAuthenticate bool `json:"bearerEmitWWWAuthenticate,omitempty"`
+	// BearerOverridesCookie controls precedence when both Authorization:
+	// Bearer and a session cookie are present. Default false: cookie wins
+	// (safer against browser/extension/proxy bearer injection). Set true for
+	// the bearer-wins convention used by AWS/GCP/Kubernetes API gateways.
+	BearerOverridesCookie bool `json:"bearerOverridesCookie,omitempty"`
+	// MaxTokenAgeSeconds caps how old (iat-based) a bearer token may be.
+	// Default 86400 (24h). Bounds clock-manipulation tokens with implausibly
+	// distant iat values.
+	MaxTokenAgeSeconds int64 `json:"maxTokenAgeSeconds,omitempty"`
+	// MaxIdentifierLength bounds the post-sanitisation length of the bearer
+	// principal identifier (the value injected as X-Forwarded-User). Default
+	// 256.
+	MaxIdentifierLength int `json:"maxIdentifierLength,omitempty"`
+	// BearerFailureThreshold is the number of consecutive 401s from one
+	// source IP within BearerFailureWindowSeconds that trips the throttle.
+	// Default 20.
+	BearerFailureThreshold int `json:"bearerFailureThreshold,omitempty"`
+	// BearerFailureWindowSeconds is the rolling window (seconds) over which
+	// 401s are counted for throttling. Default 60.
+	BearerFailureWindowSeconds int `json:"bearerFailureWindowSeconds,omitempty"`
+	// BearerFailurePenaltySeconds is how long an IP is parked in the 429
+	// penalty box after BearerFailureThreshold is exceeded. Default 60.
+	BearerFailurePenaltySeconds int `json:"bearerFailurePenaltySeconds,omitempty"`
 }
 
 // loadCACertPool assembles an x509.CertPool from CACertPath and CACertPEM.
@@ -291,6 +344,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

token_manager.go

@@ -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)

types.go

@@ -149,4 +149,18 @@ type TraefikOidc struct {
 	enablePKCE                 bool
 	forceHTTPS                 bool
 	suppressDiagnosticLogs     bool
+	trustForwardedURI          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
 }