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

build(release): publish multi-arch oidcgate Docker image per release tag
- 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.
2026-06-06 22:49:43 +00:00 · 2026-05-23 03:12:17 +01:00 · 2026-05-19 17:14:29 +01:00 · 2026-05-19 16:59:15 +01:00 · 2026-05-19 16:41:57 +01:00 · 2026-05-19 16:41:34 +01:00
32 changed files with 4197 additions and 9 deletions
@@ -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
@@ -64,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
@@ -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()

@@ -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"]
@@ -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' }
@@ -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
+}
@@ -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
+}
@@ -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)
+	}
+}
@@ -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)
+	})
+}
@@ -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)
+	}
+}
@@ -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,
+	}
+}
@@ -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)
+	}
+}
@@ -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)
+		}
+	}
+}
@@ -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)
+	}
+}
@@ -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")
+}
@@ -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)
+}
@@ -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)
+		}
+	}
+}
@@ -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
+}
@@ -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)
+	}
+}
@@ -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)

 ---

@@ -664,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.
@@ -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.
@@ -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.
@@ -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]
@@ -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 == ""
+}
@@ -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)
+	}
+}
+
@@ -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,
@@ -603,7 +603,7 @@ func (t *TraefikOidc) forwardAuthorized(rw http.ResponseWriter, req *http.Reques

 	// 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-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)
@@ -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 != ""
+}
@@ -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")
+	}
+}
@@ -126,6 +126,13 @@ type Config struct {
 	// 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.
@@ -149,6 +149,7 @@ type TraefikOidc struct {
 	enablePKCE                 bool
 	forceHTTPS                 bool
 	suppressDiagnosticLogs     bool
+	trustForwardedURI          bool

 	// Bearer-auth runtime state (populated only when EnableBearerAuth=true).
 	bearerIdentifierClaim     string
Author	SHA1	Message	Date
lukaszraczylo	4fa579ccf4	test(oidcgate): integration test with real middleware against mock IdP (#142 )	2026-05-23 03:12:17 +01:00
lukaszraczylo	2af05701dc	build(release): publish multi-arch oidcgate Docker image per release tag - 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.	2026-05-19 17:14:29 +01:00
lukaszraczylo	03a755cb53	docs(oidcgate): expand user guide and cross-link - Add HAProxy and Envoy ext_authz_http wiring snippets. - Add full OIDCGATE_* env-var inventory (26 fields). - Add Security Posture section (X-Forwarded-Uri sanitisation, excludedURLs guardrail, callbackURL/logoutURL validation). - Add Bearer-token (M2M) auth composition section with link to BEARER_AUTH.md. - Add Operational Guidance section (healthz/readyz ACL, Redis for multi-replica, no built-in metrics, graceful shutdown deadline). - Add Debugging section (sentinel path, silent open-redirect rejections, /readyz warm-up). - Cross-link from docs/CONFIGURATION.md.	2026-05-19 16:59:15 +01:00
lukaszraczylo	dc0e7e0238	fix(oidcgate): gosec G304 — clean config path + native #nosec directive The //nolint:gosec directive only suppresses golangci-lint; the standalone gosec GitHub Action uses its own '#nosec G304 -- reason' syntax. Use both filepath.Clean as canonical mitigation and the native directive.	2026-05-19 16:41:57 +01:00
lukaszraczylo	b2e79d8798	Merge remote-tracking branch 'origin/main' into conflict-resolve # Conflicts: # docs/superpowers/specs/2026-05-18-bearer-token-auth-design.md # middleware.go # settings.go # types.go	2026-05-19 16:41:34 +01:00
lukaszraczylo	52ef32ece7	fix(oidcgate): security hardening — sanitize XFU, guardrails, validations	2026-05-19 15:17:04 +01:00
lukaszraczylo	3bf7c60ef4	chore: gofmt	2026-05-19 15:00:42 +01:00
lukaszraczylo	775ca7afc3	docs(oidcgate): user-facing setup guide and nginx/Caddy/Traefik wiring	2026-05-19 14:25:38 +01:00
lukaszraczylo	a1273e6883	feat(oidcgate): main entrypoint with graceful shutdown	2026-05-19 14:22:46 +01:00
lukaszraczylo	0bc0079a58	refactor(oidcgate): WriteTimeout for slowloris guard, nolint reason	2026-05-19 14:18:28 +01:00
lukaszraczylo	20294f1339	feat(oidcgate): mux wiring and http.Server with graceful shutdown	2026-05-19 14:13:13 +01:00
lukaszraczylo	43938ed8a8	feat(oidcgate): healthz and readyz endpoints	2026-05-19 14:08:53 +01:00
lukaszraczylo	46679c82eb	refactor(oidcgate): simplify cloneAndRewrite, flip ?rd precedence, assert XFU passthrough	2026-05-19 14:07:44 +01:00
lukaszraczylo	a46be72be5	feat(oidcgate): auth/start/callback/logout endpoint handlers	2026-05-19 13:59:20 +01:00
lukaszraczylo	91966c1bec	refactor(oidcgate): idempotent Finalize; document and test 307/308 intercept	2026-05-19 13:57:15 +01:00
lukaszraczylo	c465fc888b	feat(oidcgate): response-writer interceptor converts 302->401 for /oauth2/auth	2026-05-19 13:50:03 +01:00
lukaszraczylo	047fea3c75	refactor(oidcgate): drop unreachable lowercase prefix; add multi-value mirror test	2026-05-19 13:48:13 +01:00
lukaszraczylo	0c092a5a22	feat(oidcgate): synthetic success handler mirrors X-* headers to response	2026-05-19 13:41:51 +01:00
lukaszraczylo	8f458b4f6e	fix(oidcgate): quality fixes — rune-safe snake-upper, drop dead import, listen validation, nested-struct test	2026-05-19 13:40:24 +01:00
lukaszraczylo	17c28fd574	feat(oidcgate): YAML config loader with env-var overrides	2026-05-19 13:30:28 +01:00
lukaszraczylo	21cc2ed747	refactor(lib): match codebase metadataMu lock pattern in Ready()	2026-05-19 13:25:13 +01:00
lukaszraczylo	ded90e5dc1	feat(lib): add (*TraefikOidc).Ready() metadata-discovery readiness accessor	2026-05-19 13:19:20 +01:00
lukaszraczylo	46777d0510	fix(lib): also route X-Auth-Request-Redirect through originalRequestURI helper	2026-05-19 13:14:16 +01:00
lukaszraczylo	f990365cb8	feat(lib): add TrustForwardedURI to honor X-Forwarded-Uri for post-login redirect target	2026-05-19 13:07:35 +01:00
lukaszraczylo	85eb9ecd16	docs: add oidcgate implementation plan	2026-05-19 13:00:56 +01:00
lukaszraczylo	3495e70cbb	docs: add oidcgate Tier 1 forward-auth daemon design	2026-05-19 12:51:41 +01:00
lukaszraczylo	fcb21a36e6	docs: harden bearer-auth spec with security review findings	2026-05-18 16:24:52 +01:00
lukaszraczylo	a6c38c0747	docs: bearer-token auth design spec	2026-05-18 15:35:12 +01:00