feat: opt-in M2M bearer-token authentication (supersedes #93) (#140)

* docs: bearer-token auth design spec

* docs: harden bearer-auth spec with security review findings

* feat(bearer): opt-in M2M bearer-token authentication

Adds an opt-in Authorization: Bearer <jwt> path for machine-to-machine
clients. Replaces and supersedes the broken approach in PR #93
(synthetic-session that omitted user_identifier and skipped ID-token
rejection / replay-protection-semantics / kid-pinning / etc.).

Design

  Two auth entrypoints feed one shared post-auth pipeline:

    cookie path  ─┐
                  ├── forwardAuthorized(rw, req, *principal)
    bearer path  ─┘    (roles/groups, header injection, security
                        headers, cookie strip, forward)

  buildPrincipalFromSession and buildPrincipalFromBearerToken produce
  the same `principal` value type. forwardAuthorized is session-agnostic
  and runs the existing post-auth work; processAuthorizedRequest now
  wraps it with the session-specific concerns (backchannel-logout,
  dirty/Save). The cookie path's behaviour is byte-identical to before
  this PR; the existing test suite passes unmodified.

Security hardening baked into the bearer path

  - Audience MANDATORY. Startup fails when EnableBearerAuth=true and
    Audience is empty.
  - BearerIdentifierClaim defaults to "sub"; "email" is rejected at
    startup to avoid the unverified-email spoofing footgun. Cookie
    path's UserIdentifierClaim is unaffected and still defaults to
    "email".
  - ID tokens explicitly rejected via the existing detectTokenType
    helper (nonce, typ=at+jwt, token_use, scope, aud-vs-clientID
    heuristics); belt-and-braces nonce/token_use=id rejection on top.
  - alg pinned to asymmetric allowlist (RS/PS/ES 256/384/512) BEFORE
    JWKS fetch, blocking alg=none and alg=HS* probes from amplifying
    into upstream calls.
  - kid length capped at 256 bytes and charset-restricted before JWKS
    fetch, blocking pathological-kid JWKS amplification.
  - Multi-audience tokens require azp == clientID.
  - iat upper-age bound (MaxTokenAgeSeconds, default 24h) bounds clock-
    manipulation and forever-token abuse.
  - Identifier sanitization: length cap, control-char + bidi-override
    + delimiter (, ; =) rejection.
  - Per-IP failure throttle: configurable threshold/window/penalty;
    returns 429 + Retry-After. Limits offline-guessing-style attacks
    and protects the shared rate-limiter / JWKS endpoint.
  - JTI replay marking suppressed via new internal verifyOpts
    {skipReplayMarking} so the same bearer can be reused until exp;
    the blacklist Get stays active so RevokeToken still terminates a
    bearer token immediately. The existing exported VerifyToken
    interface is unchanged so all mocks continue to work.
  - Cookie wins by default when both bearer and cookie are present
    (safer against browser/extension/proxy bearer injection).
    Operator can flip via BearerOverridesCookie.
  - Authorization header stripped on forward by default; also stripped
    on excluded URLs so the token can't leak into health/metrics
    downstream logs.
  - Optional RFC 7662 introspection via existing
    requireTokenIntrospection. Introspection-endpoint failure returns
    503 (distinguishes infra from token rejection).
  - 401s use RFC 6750 WWW-Authenticate hints (toggleable). Failure
    reason is logged at debug; raw tokens are never logged.

Implementation

  - principal.go: pure-data principal type and buildPrincipalFromSession.
  - bearer_auth.go: alg/kid pin, classifier, identifier sanitization,
    multi-aud azp gate, iat age check, per-IP failure tracker,
    handleBearerRequest, buildPrincipalFromBearerToken.
  - token_manager.go: VerifyToken now wraps a new verifyTokenWithOpts
    that accepts internal-only verifyOpts. Existing callers, the
    TokenVerifier interface, and all mocks unchanged.
  - middleware.go: extracted forwardAuthorized from
    processAuthorizedRequest; wired bearer detection after init wait
    + after bypass; excluded-URL Authorization strip when bearer
    enabled.
  - settings.go: ten new config fields with defaults applied in
    CreateConfig.
  - main.go: startup validation for audience + identifier-claim
    guard; bearer failure tracker init.

Tests

  - bearer_auth_test.go: table-driven helper tests for every new
    component (parseBearerJOSEHeader, sanitizeBearerIdentifier,
    resolveBearerIdentifier, enforceMultiAudienceAzp, enforceIatAge,
    bearerFailureTracker, detectBearerToken). Integration tests
    through ServeHTTP covering happy path, ID-token rejection,
    alg=none rejection, oversized kid, multi-aud with/without azp,
    iat-too-old, bidi identifier, replay (100x reuse), 429 throttle
    trip, excluded-URL strip, roles gate, cookie-wins precedence,
    BearerOverridesCookie, oversized token, malformed JWT,
    feature-off pass-through. Startup validation for audience-
    required and email-identifier-rejected.
  - All existing tests pass unmodified (cookie-path regression).
  - go vet clean. golangci-lint clean (0 issues). Race detector
    clean on bearer tests.

Documentation

  - README.md: bearer auth section with security highlights and
    config snippet; doc link in the index.
  - .traefik.yml: commented config block exposing every bearer knob.
  - docs/CONFIGURATION.md: new subsection with full parameter table.
  - docs/BEARER_AUTH.md: threat model, hardening matrix, failure
    response table, operational guidance, known follow-ups.
  - docs/superpowers/specs/2026-05-18-bearer-token-auth-design.md:
    design spec + security-review hardening history.

* fix(cache): redact raw cache keys in debug logs (CodeQL go/clear-text-logging)

CodeQL flagged 9 high-severity alerts (go/clear-text-logging) where the
in-memory cache and the hybrid L1+L2 backend printed `key=%s` at debug.
Cache callers (token cache, blacklist, introspection cache) pass raw
access / refresh / id tokens as cache keys, so any debug-enabled
deployment would write them to log streams.

Pre-existing issue. CodeQL started flagging it on this PR because the
new bearer-auth path adds a data-flow source (req.Header.Get("Authorization"))
that reaches the existing logging sinks via the same cache. The cookie
path had the same risk but wasn't tracked as taint by CodeQL.

Fix: hash the key (SHA-256[:8] hex) before printing. Same approach the
bearer-auth logger uses for principal identifiers (spec §13). Doesn't
change cache semantics — same key still produces the same hash, so
debug correlation across log lines is preserved without exposing the
raw value.

Touches both affected packages:
  - internal/cache/cache.go (2 sites: Set + LRU eviction)
  - internal/cache/backends/hybrid.go (12 sites: L1/L2 read/write/fallback)

New helper `redactKey` colocated with each package (unexported,
package-local) keeps the change blast radius narrow. Tests green; lint
clean.

* docs(bearer): how to obtain bearer tokens from the OIDC provider

Adds a section walking operators through the OAuth 2.0 client_credentials
flow (RFC 6749 §4.4) and the JWT bearer assertion alternative (RFC 7523),
with a worked Auth0-shape curl example, a per-provider quick reference
(Auth0, Okta, Keycloak, Entra v2, Cognito, GitLab, Google), operational
notes (token TTL, caching, JWKS rotation, revocation, scope vs audience,
secret hygiene), and a three-line validation loop.

Most common operator confusion: "I enabled the feature but tokens get
401'd" — almost always missing or wrong audience. The new section makes
the audience-matching requirement loud, with per-provider parameter
names so people don't have to dig through IdP docs.

Locations:
  - docs/BEARER_AUTH.md  — full section under "Quick start"
  - README.md            — short snippet + deep link

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