auth-bundle-2 Phase 6: session middleware + CSRF token plumbing +

chained-auth combinator + AuthInfo OIDC providers extension + 2 CI
guards (Bundle-1-compat + Bundle-1-to-2-upgrade)

Phase 6 wires the Phase 4 session service + Phase 5 OIDC handlers into
the request path. Three middlewares + one combinator land in
internal/auth/session/middleware.go:

  1. SessionMiddleware reads `certctl_session` cookie, validates via
     SessionService.Validate, populates the legacy UserKey/AdminKey
     + Phase 3 RBAC context keys (ActorIDKey/ActorTypeKey/TenantIDKey)
     so downstream RequirePermission + audit-attribution see a
     consistent caller. Best-effort UpdateLastSeen keeps the idle-
     expiry sliding window fresh. CRITICALLY: never 401s on validate
     failure — defers to the next middleware so the chained-auth
     combinator can fall back to Bearer.

  2. CSRFMiddleware gates state-changing methods (POST/PUT/DELETE/
     PATCH) for session-authenticated requests. API-key actors are
     EXEMPT (no session row in context => CSRF doesn't apply; they're
     not browser-driven). Constant-time-compares SHA-256(X-CSRF-Token
     header) against the session row's stored hash via
     SessionService.ValidateCSRF. Mismatch returns 403.

  3. ChainAuthSessionThenBearer is the load-bearing chained-auth
     combinator: tries the session cookie first; on miss/invalid,
     falls back to the API-key Bearer middleware; if neither
     authenticates, 401. The composition uses bearerSkipIfAuthenticated
     so a request with both a valid session AND a valid Bearer uses
     the session (cookie wins per the Bundle 2 contract).

Middleware chain order in cmd/server/main.go (per Phase 6 spec):

  RequestID → Logging → Recovery → CORS → RateLimit → AUTH (chained:
  session → Bearer) → CSRF (state-changing only; API-key exempt) →
  Audit → Handler

The chained authMiddleware replaces the bare Bundle-1 bearerMiddleware
at the chain entry point; csrfMiddleware lands immediately after so
session-authenticated requests pass through CSRF before audit. Both
new middlewares are pass-throughs when sessionService is nil
(pre-Phase-4 builds).

AuthInfo extension (Category E): GET /api/v1/auth/info now returns the
list of configured OIDC providers (id + display_name + login_url
where login_url = `/auth/oidc/login?provider=<id>`) so the GUI Login
page renders the correct "Sign in with X" buttons. Endpoint stays
auth-exempt; the providers list is public configuration. Wired via
HealthHandler.OIDCProvidersResolver + a new OIDCProvidersListResolver
projection interface; the cmd/server adapter
oidcProvidersListAdapter projects the postgres OIDCProviderRepository
into the public-safe shape. Resolver lookups are best-effort: failures
fall back to the minimal payload rather than 500-ing the GUI's auth
probe. Nil resolver preserves the pre-Phase-6 minimal shape so test
fixtures + no-db deploys keep compiling.

Bypass list preserved (Category E): the existing public-route
allowlist in router.AuthExemptRouterRoutes is preserved by virtue of
those routes registering via direct r.mux.Handle (they bypass the
entire chain). The protocol-endpoint allowlist (ACME/SCEP/EST/OCSP/
CRL) bypasses via cmd/server/main.go::buildFinalHandler URL-prefix
dispatch — those routes never reach the auth middleware at all. Both
preservations are pinned by the Bundle-1 compat CI guard below.

Tests (internal/auth/session/middleware_test.go):

All 7 Phase 6 spec-mandated middleware-chain tests pass:

  1. Session cookie + correct CSRF → 200.
  2. Session cookie + wrong CSRF → 403.
  3. Bearer-only (no session) + no CSRF → 200 (API-key actors are
     CSRF-exempt by design).
  4. No cookie + no Bearer → 401.
  5. Expired cookie + valid Bearer → fall back to Bearer succeeds.
  6. Tampered cookie → 401 (no Bearer to fall back to).
  7. Bypass-list awareness — state-changing method, no auth, no
     session row → uniform 401 (NOT a CSRF 403; the CSRF check is
     gated on session-row presence and never fires for unauth
     requests).

Plus coverage-lift tests covering nil-service pass-through, safe-
methods bypass, SessionFromContext nil + populated, isStateChangingMethod
matrix, clientIPFromRequest variants (RemoteAddr / XFF first-hop /
XFF single / no-port), nil-bearer chain branches.

Coverage on internal/auth/session/middleware.go: 100% per-function
across the 9 entry points (SessionValidator interfaces +
NewSessionMiddleware + NewCSRFMiddleware + ChainAuthSessionThenBearer +
bearerSkipIfAuthenticated + SessionFromContext + isStateChangingMethod
+ clientIPFromRequest + lastIndexByte). Package coverage 94.9%.

Two new CI guards:

  scripts/ci-guards/bundle-1-compat-regression.sh — Bundle-1-only
  compat invariants. Static-source checks that protect the Bundle-1
  path since spinning up docker-compose + running the integration
  test suite is sandbox-infeasible:
    1. SessionMiddleware MUST defer-to-next on missing/invalid cookie.
    2. CSRFMiddleware MUST be pass-through on missing session row.
    3. cmd/server/main.go MUST wire ChainAuthSessionThenBearer.
    4. The 4 public OIDC routes MUST be in AuthExemptRouterRoutes.
    5. AuthInfo MUST guard on OIDCProvidersResolver != nil.

  scripts/ci-guards/bundle-1-to-2-upgrade-regression.sh — Bundle-1 →
  Bundle-2 upgrade invariants:
    1. Migrations 000034..000037 use CREATE TABLE IF NOT EXISTS.
    2. Migrations are wrapped in BEGIN; ... COMMIT;.
    3. NO DROP TABLE / ALTER ... DROP COLUMN against any of the 19
       protected Bundle-1 tables (api_keys, audit_events, certificates,
       certificate_versions, profiles, issuers, targets, agents, jobs,
       owners, teams, agent_groups, notifications, roles, permissions,
       role_permissions, actor_roles, tenants, approvals,
       intermediate_cas, issuance_approval_requests).
    4. 000037 INSERTs use ON CONFLICT DO NOTHING (idempotent re-apply).
    5. ChainAuthSessionThenBearer is wired (Bundle-1 Bearer keys
       continue to authenticate post-upgrade).
    6. Bootstrap handler is registered (fresh-deployment bootstrap
       still works).

Both guards are sandbox-feasible static analysis. When the operator
gets a Linux VM with docker-in-docker, promote both to real `docker
compose up` integration tests against a v2.1.0 baseline DB dump.

Verifications: gofmt clean, go vet ./internal/auth/... ./internal/api/...
./cmd/server/... clean, go test -short -count=1 -race green across
internal/auth/session (94.9% coverage), internal/api/handler,
internal/api/router, no regressions in Bundle 1 packages, both new
ci-guards green.

internal/api/handler/health.go

@@ -77,6 +77,35 @@ type HealthHandler struct {
 	// the legacy {status, user, admin} payload (preserves test fixtures
 	// and the no-db deploy path).
 	Resolver AuthCheckResolver
+
+	// OIDCProvidersResolver (Bundle 2 Phase 6 / Category E) — optional.
+	// When set, AuthInfo additionally returns the list of configured
+	// OIDC providers (id, display_name, login_url) so the GUI Login
+	// page can render the correct buttons. Wired in cmd/server/main.go
+	// from the postgres OIDCProviderRepository. The endpoint stays
+	// auth-exempt; the providers list is public configuration (provider
+	// name + IdP URL — same info present in the IdP's discovery doc).
+	// Nil resolver preserves the pre-Phase-6 minimal payload shape so
+	// existing test fixtures + no-db deploys keep compiling.
+	OIDCProvidersResolver OIDCProvidersListResolver
+}
+
+// OIDCProvidersListResolver is the slice of repository.OIDCProviderRepository
+// the AuthInfo handler consumes for the Phase 6 GUI-facing providers
+// list. Defining the projection here keeps the handler decoupled from
+// the wider repo surface.
+type OIDCProvidersListResolver interface {
+	List(ctx context.Context, tenantID string) ([]*OIDCProviderInfo, error)
+}
+
+// OIDCProviderInfo is the minimal public-safe payload returned by
+// AuthInfo for each configured OIDC provider. The login_url is the
+// `/auth/oidc/login?provider=<id>` redirect target the GUI navigates
+// to when the user clicks the corresponding "Sign in with X" button.
+type OIDCProviderInfo struct {
+	ID          string `json:"id"`
+	DisplayName string `json:"display_name"`
+	LoginURL    string `json:"login_url"`
 }
 
 // NewHealthHandler creates a new HealthHandler.
@@ -165,11 +194,24 @@ func (h HealthHandler) Ready(w http.ResponseWriter, r *http.Request) {
 // AuthInfo responds with the server's authentication configuration.
 // This lets the GUI know whether to show a login screen.
 // GET /api/v1/auth/info (served without auth middleware)
+//
+// Bundle 2 Phase 6 / Category E: when h.OIDCProvidersResolver is wired,
+// the response is extended with the list of configured OIDC providers
+// (id, display_name, login_url) so the GUI's Login page can render the
+// correct "Sign in with X" buttons. The endpoint stays auth-exempt;
+// the providers list is public configuration. Resolver lookups are
+// best-effort: failures fall back to the minimal payload rather than
+// 500-ing the GUI's auth probe.
 func (h HealthHandler) AuthInfo(w http.ResponseWriter, r *http.Request) {
 	response := map[string]interface{}{
 		"auth_type": h.AuthType,
 		"required":  h.AuthType != "none",
 	}
+	if h.OIDCProvidersResolver != nil {
+		if provs, err := h.OIDCProvidersResolver.List(r.Context(), authdomain.DefaultTenantID); err == nil {
+			response["oidc_providers"] = provs
+		}
+	}
 	JSON(w, http.StatusOK, response)
 }
 

internal/auth/session/middleware.go

@@ -0,0 +1,313 @@
+// Package session — Auth Bundle 2 Phase 6 / session + CSRF middleware.
+//
+// This file ships the HTTP middleware that wires the post-login session
+// machinery into the request path. Three middlewares + one combinator:
+//
+//  1. SessionMiddleware — reads `certctl_session` cookie, validates
+//     via SessionService.Validate, populates the actor/role context
+//     keys (same keys as the API-key path) so downstream handlers
+//     and RBAC gates see a consistent caller.
+//
+//  2. CSRFMiddleware — for state-changing methods (POST/PUT/DELETE/
+//     PATCH), checks `X-CSRF-Token` header against the session row's
+//     stored hash. API-key actors are EXEMPT (they're not browser-
+//     driven; CSRF doesn't apply). Returns 403 on mismatch.
+//
+//  3. ChainAuthSessionThenBearer — the load-bearing chained-auth
+//     combinator: tries the session cookie first; on miss/invalid,
+//     falls back to the Bearer-token middleware; if neither
+//     authenticates, returns 401. Wired in cmd/server/main.go in the
+//     documented chain position (#6 — Auth, between RateLimit and CSRF).
+//
+// Bypass list (Category E): the existing public-route allowlist in
+// internal/api/router/router.go::AuthExemptRouterRoutes (/health,
+// /ready, /api/v1/auth/info, /api/v1/version, /api/v1/auth/bootstrap,
+// /auth/oidc/login + callback + back-channel-logout, /auth/logout) is
+// preserved by virtue of those routes registering via direct
+// r.mux.Handle (they bypass the entire middleware chain). The
+// protocol-endpoint allowlist (ACME / SCEP / EST / OCSP / CRL) bypasses
+// via the cmd/server/main.go::buildFinalHandler URL-prefix dispatch —
+// those routes never reach the auth middleware at all.
+package session
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/certctl-io/certctl/internal/auth"
+	sessiondomain "github.com/certctl-io/certctl/internal/auth/session/domain"
+)
+
+// =============================================================================
+// SessionMiddleware.
+// =============================================================================
+
+// SessionValidator is the slice of *Service the SessionMiddleware
+// consumes. Defining the projection here keeps the middleware
+// decoupled from the wider service surface (and lets tests stub
+// validation without spinning up a full SessionService).
+type SessionValidator interface {
+	Validate(ctx context.Context, in ValidateInput) (*sessiondomain.Session, error)
+	UpdateLastSeen(ctx context.Context, sessionID string) error
+}
+
+// NewSessionMiddleware returns the Phase 6 session-cookie middleware.
+//
+// Behavior on each request:
+//
+//  1. Read `certctl_session` cookie. Missing -> defer to next middleware
+//     (the chained-auth combinator falls back to Bearer).
+//  2. Validate via SessionService.Validate. On failure, defer to next
+//     middleware (likewise falls back to Bearer).
+//  3. On success, populate the legacy UserKey / AdminKey + the Phase 3
+//     RBAC context keys (ActorIDKey / ActorTypeKey / TenantIDKey) so
+//     downstream RequirePermission + audit-attribution code see a
+//     consistent actor regardless of how they authenticated.
+//  4. Best-effort UpdateLastSeen so the idle-expiry sliding window
+//     stays fresh (errors swallowed; the session is already validated).
+//  5. Defer to the next handler.
+//
+// The middleware does NOT 401 on session-validate failure; instead it
+// passes through, letting the chained-auth combinator try Bearer. The
+// combinator 401s when neither authenticates.
+func NewSessionMiddleware(svc SessionValidator) func(http.Handler) http.Handler {
+	if svc == nil {
+		// No session service wired (pre-Phase-5 deployments) — pass-through.
+		return func(next http.Handler) http.Handler { return next }
+	}
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			cookie, err := r.Cookie(sessiondomain.PostLoginCookieName)
+			if err != nil || cookie.Value == "" {
+				next.ServeHTTP(w, r)
+				return
+			}
+			sess, verr := svc.Validate(r.Context(), ValidateInput{
+				CookieValue: cookie.Value,
+				ClientIP:    clientIPFromRequest(r),
+				UserAgent:   r.UserAgent(),
+			})
+			if verr != nil {
+				// Cookie present but invalid (expired / tampered /
+				// retired-key / IP-bind / UA-bind / revoked). Defer to
+				// the next middleware so a valid Bearer can still
+				// authenticate. The auth combinator 401s if neither
+				// works.
+				next.ServeHTTP(w, r)
+				return
+			}
+
+			// Best-effort sliding-window update. The session is already
+			// validated; an UpdateLastSeen error doesn't change the
+			// auth outcome (the row stays valid until idle / absolute
+			// expiry; this just keeps the idle window fresh).
+			_ = svc.UpdateLastSeen(r.Context(), sess.ID)
+
+			ctx := r.Context()
+			ctx = context.WithValue(ctx, auth.UserKey{}, sess.ActorID)
+			ctx = context.WithValue(ctx, auth.AdminKey{}, false) // RBAC takes over from the legacy admin-flag heuristic
+			ctx = context.WithValue(ctx, auth.ActorIDKey{}, sess.ActorID)
+			ctx = context.WithValue(ctx, auth.ActorTypeKey{}, sess.ActorType)
+			ctx = context.WithValue(ctx, auth.TenantIDKey{}, sess.TenantID)
+			// Stash the session row itself so the CSRF middleware can
+			// look up the stored CSRF hash without re-validating.
+			ctx = context.WithValue(ctx, sessionContextKey{}, sess)
+			next.ServeHTTP(w, r.WithContext(ctx))
+		})
+	}
+}
+
+// =============================================================================
+// CSRFMiddleware.
+// =============================================================================
+
+// CSRFValidator is the slice of *Service the CSRFMiddleware uses.
+type CSRFValidator interface {
+	ValidateCSRF(headerValue string, sess *sessiondomain.Session) error
+}
+
+// NewCSRFMiddleware returns the Phase 6 CSRF middleware.
+//
+// Behavior:
+//
+//   - Safe methods (GET / HEAD / OPTIONS / TRACE) pass through unchecked.
+//   - Requests authenticated via Bearer (API-key actors) pass through
+//     unchecked: CSRF is a browser-driven attack vector that doesn't
+//     apply to programmatic API clients. The middleware detects API-key
+//     actors via the absence of a session row in context (the
+//     SessionMiddleware populates it; the API-key middleware doesn't).
+//   - Requests authenticated via session cookie + state-changing method
+//     are gated by SessionService.ValidateCSRF (constant-time-compare
+//     of SHA-256(X-CSRF-Token header) against the session row's
+//     stored hash). Mismatch returns 403.
+func NewCSRFMiddleware(svc CSRFValidator) func(http.Handler) http.Handler {
+	if svc == nil {
+		return func(next http.Handler) http.Handler { return next }
+	}
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if !isStateChangingMethod(r.Method) {
+				next.ServeHTTP(w, r)
+				return
+			}
+			// Find the session row populated by SessionMiddleware.
+			// Absence => either (a) caller authenticated via Bearer
+			// (API-key path; CSRF exempt by design), or (b) caller is
+			// unauthenticated (the auth combinator already 401'd
+			// before we got here, so this branch is unreachable in
+			// production; defensive code keeps the test surface tidy).
+			sess, ok := r.Context().Value(sessionContextKey{}).(*sessiondomain.Session)
+			if !ok || sess == nil {
+				next.ServeHTTP(w, r)
+				return
+			}
+			header := r.Header.Get("X-CSRF-Token")
+			if err := svc.ValidateCSRF(header, sess); err != nil {
+				w.Header().Set("Content-Type", "application/json; charset=utf-8")
+				http.Error(w, `{"error":"CSRF token missing or invalid"}`, http.StatusForbidden)
+				return
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+// =============================================================================
+// ChainAuthSessionThenBearer — the load-bearing combinator.
+// =============================================================================
+
+// ChainAuthSessionThenBearer composes the session middleware with the
+// API-key middleware so a single chain entry tries both paths.
+//
+// The composition order is critical:
+//
+//  1. SessionMiddleware runs first. On a valid session cookie it
+//     populates the actor context keys + sets the session-row stash
+//     and calls next.
+//  2. The Bearer-only inner middleware runs second. If the session
+//     middleware already populated ActorIDKey, the Bearer middleware
+//     is a pass-through (the request is already authenticated). If
+//     ActorIDKey is empty, it runs the standard Bearer-token check
+//     and either populates the context (200) or 401s.
+//
+// This means a request with BOTH a valid session AND a valid Bearer
+// uses the session (cookie wins; the Bundle 2 contract). A request
+// with only one works regardless of which one. A request with neither
+// 401s.
+//
+// The bearer parameter is the existing API-key middleware
+// (auth.NewAuthWithKeyStore or similar); when nil the chain degrades
+// to session-only.
+func ChainAuthSessionThenBearer(
+	sessionMW func(http.Handler) http.Handler,
+	bearerMW func(http.Handler) http.Handler,
+) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		// Build the inner: a Bearer middleware that short-circuits when
+		// SessionMiddleware already populated ActorIDKey.
+		inner := bearerSkipIfAuthenticated(bearerMW)(next)
+		// Then wrap with SessionMiddleware so it runs first.
+		return sessionMW(inner)
+	}
+}
+
+// bearerSkipIfAuthenticated wraps the Bearer-token middleware with a
+// short-circuit: if ActorIDKey is already populated (the session
+// middleware authenticated the request), pass through to next without
+// running the Bearer check. Otherwise run Bearer.
+func bearerSkipIfAuthenticated(bearerMW func(http.Handler) http.Handler) func(http.Handler) http.Handler {
+	if bearerMW == nil {
+		// No Bearer auth wired (test deployments / session-only). Just
+		// require ActorIDKey from the session middleware; 401 if missing.
+		return func(next http.Handler) http.Handler {
+			return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if actorID, _ := r.Context().Value(auth.ActorIDKey{}).(string); actorID != "" {
+					next.ServeHTTP(w, r)
+					return
+				}
+				w.Header().Set("Content-Type", "application/json; charset=utf-8")
+				http.Error(w, `{"error":"Authentication required"}`, http.StatusUnauthorized)
+			})
+		}
+	}
+	return func(next http.Handler) http.Handler {
+		bearerInner := bearerMW(next)
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if actorID, _ := r.Context().Value(auth.ActorIDKey{}).(string); actorID != "" {
+				// Session middleware already authenticated. Skip Bearer.
+				next.ServeHTTP(w, r)
+				return
+			}
+			// Defer to Bearer.
+			bearerInner.ServeHTTP(w, r)
+		})
+	}
+}
+
+// =============================================================================
+// Helpers.
+// =============================================================================
+
+// sessionContextKey is the context key under which SessionMiddleware
+// stashes the validated *sessiondomain.Session so CSRFMiddleware can
+// reach it without re-validating the cookie.
+type sessionContextKey struct{}
+
+// SessionFromContext returns the validated session row populated by
+// SessionMiddleware. Returns nil when the request was authenticated via
+// Bearer (no session) OR is unauthenticated.
+func SessionFromContext(ctx context.Context) *sessiondomain.Session {
+	if v, ok := ctx.Value(sessionContextKey{}).(*sessiondomain.Session); ok {
+		return v
+	}
+	return nil
+}
+
+func isStateChangingMethod(method string) bool {
+	switch method {
+	case http.MethodPost, http.MethodPut, http.MethodDelete, http.MethodPatch:
+		return true
+	}
+	return false
+}
+
+// clientIPFromRequest pulls the request's client IP — X-Forwarded-For
+// first hop wins when present; otherwise RemoteAddr (host:port) with
+// the port stripped. Mirrors the helper in
+// internal/api/handler/auth_session_oidc.go for the same reason: the
+// handler + middleware both need to derive the canonical client IP
+// from the same request shape, and duplicating the 6-line helper is
+// preferable to introducing an internal/util package for it.
+func clientIPFromRequest(r *http.Request) string {
+	if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
+		for i := 0; i < len(xff); i++ {
+			if xff[i] == ',' {
+				return trimSpace(xff[:i])
+			}
+		}
+		return trimSpace(xff)
+	}
+	if i := lastIndexByte(r.RemoteAddr, ':'); i > 0 {
+		return r.RemoteAddr[:i]
+	}
+	return r.RemoteAddr
+}
+
+func trimSpace(s string) string {
+	for len(s) > 0 && (s[0] == ' ' || s[0] == '\t') {
+		s = s[1:]
+	}
+	for len(s) > 0 && (s[len(s)-1] == ' ' || s[len(s)-1] == '\t') {
+		s = s[:len(s)-1]
+	}
+	return s
+}
+
+func lastIndexByte(s string, c byte) int {
+	for i := len(s) - 1; i >= 0; i-- {
+		if s[i] == c {
+			return i
+		}
+	}
+	return -1
+}

internal/auth/session/middleware_test.go

@@ -0,0 +1,365 @@
+package session
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/certctl-io/certctl/internal/auth"
+	sessiondomain "github.com/certctl-io/certctl/internal/auth/session/domain"
+)
+
+// =============================================================================
+// In-memory stubs.
+// =============================================================================
+
+type stubSessionValidator struct {
+	sess          *sessiondomain.Session
+	validateErr   error
+	updateLastErr error
+	validateCalls int
+	updateCalls   int
+}
+
+func (s *stubSessionValidator) Validate(_ context.Context, _ ValidateInput) (*sessiondomain.Session, error) {
+	s.validateCalls++
+	return s.sess, s.validateErr
+}
+func (s *stubSessionValidator) UpdateLastSeen(_ context.Context, _ string) error {
+	s.updateCalls++
+	return s.updateLastErr
+}
+func (s *stubSessionValidator) ValidateCSRF(headerValue string, sess *sessiondomain.Session) error {
+	if sess == nil {
+		return ErrCSRFMismatch
+	}
+	if headerValue == "" {
+		return ErrCSRFMissing
+	}
+	if hashCSRFToken(headerValue) != sess.CSRFTokenHash {
+		return ErrCSRFMismatch
+	}
+	return nil
+}
+
+// =============================================================================
+// Helpers.
+// =============================================================================
+
+// mockBearer returns a Bearer middleware stub that authenticates any
+// "Authorization: Bearer XYZ" header by setting the actor context.
+// Mimics auth.NewAuthWithKeyStore's success-path behavior for tests
+// without spinning up a real KeyStore.
+func mockBearer(_ *testing.T) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			authHeader := r.Header.Get("Authorization")
+			if authHeader != "Bearer test-key" {
+				w.Header().Set("Content-Type", "application/json; charset=utf-8")
+				http.Error(w, `{"error":"Invalid API key"}`, http.StatusUnauthorized)
+				return
+			}
+			ctx := r.Context()
+			ctx = context.WithValue(ctx, auth.UserKey{}, "api-key-actor")
+			ctx = context.WithValue(ctx, auth.ActorIDKey{}, "api-key-actor")
+			ctx = context.WithValue(ctx, auth.ActorTypeKey{}, "APIKey")
+			ctx = context.WithValue(ctx, auth.TenantIDKey{}, "t-default")
+			next.ServeHTTP(w, r.WithContext(ctx))
+		})
+	}
+}
+
+// markAuthenticated returns a tiny handler that 200s + writes the
+// actor id from context so tests can inspect which auth path won.
+func markAuthenticated() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		actorID, _ := r.Context().Value(auth.ActorIDKey{}).(string)
+		fmt.Fprintf(w, `{"actor_id":%q}`, actorID)
+	})
+}
+
+func newSession(t *testing.T, csrfPlaintext string) *sessiondomain.Session {
+	t.Helper()
+	now := time.Now().UTC()
+	return &sessiondomain.Session{
+		ID:                "ses-test",
+		ActorID:           "u-alice",
+		ActorType:         "User",
+		SigningKeyID:      "sk-test",
+		CSRFTokenHash:     hashCSRFToken(csrfPlaintext),
+		IdleExpiresAt:     now.Add(time.Hour),
+		AbsoluteExpiresAt: now.Add(8 * time.Hour),
+		CreatedAt:         now,
+		LastSeenAt:        now,
+		TenantID:          "t-default",
+	}
+}
+
+// =============================================================================
+// 7 Phase 6 spec-mandated middleware-chain tests.
+// =============================================================================
+
+// #1: Session cookie + correct CSRF -> succeeds.
+func TestPhase6_SessionPlusCorrectCSRF_Succeeds(t *testing.T) {
+	csrf := "the-csrf-token-plaintext"
+	stub := &stubSessionValidator{sess: newSession(t, csrf)}
+	chain := buildPhase6Chain(stub, stub)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/whatever", nil)
+	req.AddCookie(&http.Cookie{Name: sessiondomain.PostLoginCookieName, Value: "v1.ses-test.sk-test.mac"})
+	req.Header.Set("X-CSRF-Token", csrf)
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("status = %d; want 200; body=%q", w.Code, w.Body.String())
+	}
+	if !strContains(w.Body.String(), "u-alice") {
+		t.Errorf("body missing actor id; got %q", w.Body.String())
+	}
+}
+
+// #2: Session cookie + WRONG CSRF -> 403.
+func TestPhase6_SessionPlusWrongCSRF_403(t *testing.T) {
+	stub := &stubSessionValidator{sess: newSession(t, "real-csrf")}
+	chain := buildPhase6Chain(stub, stub)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/whatever", nil)
+	req.AddCookie(&http.Cookie{Name: sessiondomain.PostLoginCookieName, Value: "v1.ses-test.sk-test.mac"})
+	req.Header.Set("X-CSRF-Token", "wrong-csrf")
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, req)
+
+	if w.Code != http.StatusForbidden {
+		t.Errorf("status = %d; want 403", w.Code)
+	}
+}
+
+// #3: Bearer-only (no session) + no CSRF -> succeeds (API-key actors are CSRF-exempt).
+func TestPhase6_BearerOnly_NoCSRF_Succeeds(t *testing.T) {
+	stub := &stubSessionValidator{validateErr: errors.New("no cookie")}
+	chain := buildPhase6Chain(stub, stub)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/whatever", nil)
+	req.Header.Set("Authorization", "Bearer test-key")
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("status = %d; want 200; body=%q", w.Code, w.Body.String())
+	}
+	if !strContains(w.Body.String(), "api-key-actor") {
+		t.Errorf("body missing api-key actor id; got %q", w.Body.String())
+	}
+}
+
+// #4: No cookie + no Bearer -> 401.
+func TestPhase6_NeitherCookieNorBearer_401(t *testing.T) {
+	stub := &stubSessionValidator{}
+	chain := buildPhase6Chain(stub, stub)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/whatever", nil)
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d; want 401; body=%q", w.Code, w.Body.String())
+	}
+}
+
+// #5: Expired cookie + valid Bearer -> falls back to Bearer, succeeds.
+func TestPhase6_ExpiredCookieValidBearer_FallsBackToBearer(t *testing.T) {
+	stub := &stubSessionValidator{validateErr: ErrSessionExpiredAbsolute}
+	chain := buildPhase6Chain(stub, stub)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/whatever", nil)
+	req.AddCookie(&http.Cookie{Name: sessiondomain.PostLoginCookieName, Value: "v1.ses-expired.sk-x.mac"})
+	req.Header.Set("Authorization", "Bearer test-key")
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("status = %d; want 200; body=%q", w.Code, w.Body.String())
+	}
+	if !strContains(w.Body.String(), "api-key-actor") {
+		t.Errorf("expected Bearer fallback to win; body=%q", w.Body.String())
+	}
+}
+
+// #6: Tampered cookie -> 401 (no Bearer to fall back to).
+func TestPhase6_TamperedCookie_401(t *testing.T) {
+	stub := &stubSessionValidator{validateErr: ErrSessionInvalidCookie}
+	chain := buildPhase6Chain(stub, stub)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/whatever", nil)
+	req.AddCookie(&http.Cookie{Name: sessiondomain.PostLoginCookieName, Value: "v1.ses-x.sk-x.tampered"})
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d; want 401", w.Code)
+	}
+}
+
+// #7: Bypass-list awareness — the protocol-endpoint allowlist is
+// enforced by the dispatch layer (cmd/server/main.go::buildFinalHandler)
+// and the public-route allowlist by direct r.mux.Handle in router.go;
+// neither reaches the auth chain. Pin the contract by asserting that
+// the chained-auth combinator's behavior on a request with no auth +
+// a state-changing method is uniformly 401, NOT a CSRF 403 — i.e., the
+// CSRF check is gated on session-row presence and never fires for
+// unauthenticated requests.
+func TestPhase6_StateChangingMethod_Unauthenticated_Returns401NotCSRF403(t *testing.T) {
+	stub := &stubSessionValidator{}
+	chain := buildPhase6Chain(stub, stub)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/whatever", nil)
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d; want 401 (not 403); body=%q", w.Code, w.Body.String())
+	}
+}
+
+// =============================================================================
+// Coverage-lift tests.
+// =============================================================================
+
+func TestSessionMiddleware_NilService_PassThrough(t *testing.T) {
+	mw := NewSessionMiddleware(nil)
+	handler := mw(markAuthenticated())
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Errorf("nil service should pass through; got %d", w.Code)
+	}
+}
+
+func TestCSRFMiddleware_NilService_PassThrough(t *testing.T) {
+	mw := NewCSRFMiddleware(nil)
+	handler := mw(markAuthenticated())
+	req := httptest.NewRequest(http.MethodPost, "/x", nil)
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Errorf("nil service should pass through; got %d", w.Code)
+	}
+}
+
+func TestCSRFMiddleware_SafeMethodsBypass(t *testing.T) {
+	stub := &stubSessionValidator{sess: newSession(t, "csrf")}
+	mw := NewCSRFMiddleware(stub)
+	handler := mw(markAuthenticated())
+	for _, method := range []string{http.MethodGet, http.MethodHead, http.MethodOptions, http.MethodTrace} {
+		req := httptest.NewRequest(method, "/x", nil)
+		w := httptest.NewRecorder()
+		handler.ServeHTTP(w, req)
+		if w.Code != http.StatusOK {
+			t.Errorf("safe method %s blocked by CSRF middleware; status=%d", method, w.Code)
+		}
+	}
+}
+
+func TestSessionFromContext_NilMissing(t *testing.T) {
+	if s := SessionFromContext(context.Background()); s != nil {
+		t.Errorf("expected nil; got %v", s)
+	}
+}
+
+func TestSessionFromContext_PopulatedReturnsSession(t *testing.T) {
+	sess := newSession(t, "csrf")
+	ctx := context.WithValue(context.Background(), sessionContextKey{}, sess)
+	if s := SessionFromContext(ctx); s != sess {
+		t.Errorf("expected returned session pointer to match; got %v", s)
+	}
+}
+
+func TestIsStateChangingMethod(t *testing.T) {
+	for _, tc := range []struct {
+		method string
+		want   bool
+	}{
+		{http.MethodGet, false},
+		{http.MethodHead, false},
+		{http.MethodOptions, false},
+		{http.MethodTrace, false},
+		{http.MethodPost, true},
+		{http.MethodPut, true},
+		{http.MethodDelete, true},
+		{http.MethodPatch, true},
+	} {
+		if got := isStateChangingMethod(tc.method); got != tc.want {
+			t.Errorf("isStateChangingMethod(%s) = %v; want %v", tc.method, got, tc.want)
+		}
+	}
+}
+
+func TestClientIPFromRequest_Variants(t *testing.T) {
+	r := httptest.NewRequest(http.MethodGet, "/", nil)
+	r.RemoteAddr = "1.2.3.4:5555"
+	if ip := clientIPFromRequest(r); ip != "1.2.3.4" {
+		t.Errorf("RemoteAddr: got %q; want 1.2.3.4", ip)
+	}
+	r.Header.Set("X-Forwarded-For", "10.0.0.1, 10.0.0.2")
+	if ip := clientIPFromRequest(r); ip != "10.0.0.1" {
+		t.Errorf("XFF first hop: got %q; want 10.0.0.1", ip)
+	}
+	r.Header.Set("X-Forwarded-For", "10.0.0.99")
+	if ip := clientIPFromRequest(r); ip != "10.0.0.99" {
+		t.Errorf("XFF single: got %q; want 10.0.0.99", ip)
+	}
+	r2 := httptest.NewRequest(http.MethodGet, "/", nil)
+	r2.RemoteAddr = "no-port"
+	if ip := clientIPFromRequest(r2); ip != "no-port" {
+		t.Errorf("no-port RemoteAddr: got %q; want no-port", ip)
+	}
+}
+
+func TestChainAuthSessionThenBearer_NilBearer_Session401Path(t *testing.T) {
+	stub := &stubSessionValidator{validateErr: ErrSessionInvalidCookie}
+	chain := ChainAuthSessionThenBearer(NewSessionMiddleware(stub), nil)(markAuthenticated())
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	req.AddCookie(&http.Cookie{Name: sessiondomain.PostLoginCookieName, Value: "v1.ses.sk.bad"})
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d; want 401", w.Code)
+	}
+}
+
+func TestChainAuthSessionThenBearer_NilBearer_SessionAuthSucceeds(t *testing.T) {
+	stub := &stubSessionValidator{sess: newSession(t, "csrf")}
+	chain := ChainAuthSessionThenBearer(NewSessionMiddleware(stub), nil)(markAuthenticated())
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	req.AddCookie(&http.Cookie{Name: sessiondomain.PostLoginCookieName, Value: "v1.ses.sk.mac"})
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Errorf("status = %d; want 200", w.Code)
+	}
+}
+
+// =============================================================================
+// Helpers.
+// =============================================================================
+
+func buildPhase6Chain(svcSession SessionValidator, svcCSRF CSRFValidator) http.Handler {
+	auth := ChainAuthSessionThenBearer(NewSessionMiddleware(svcSession), mockBearer(nil))
+	csrf := NewCSRFMiddleware(svcCSRF)
+	return auth(csrf(markAuthenticated()))
+}
+
+func strContains(s, sub string) bool {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}