harden(oidc): pre-login UA/IP binding (MED-16) — RFC 9700 §4.7.1

Audit 2026-05-10 MED-16 closure.

WHAT.

Binds the OIDC pre-login row to the (clientIP, userAgent) tuple of
the /auth/oidc/login request, and enforces a constant-time compare
against the /auth/oidc/callback request at consume time. Defeats
replay of a stolen pre-login cookie by a different browser /
source — the secondary defense layer recommended by RFC 9700 §4.7.1
when the primary layer (HMAC integrity + Path=/ + SameSite=Lax on
the cookie) is bypassed via CSRF / XSS / TLS-termination leak.

WHY.

Pre-fix, the pre-login cookie's HMAC verified only that 'some'
caller of /auth/oidc/login was talking to /auth/oidc/callback; it
did not verify that the SAME browser / source was on both sides.
An attacker who exfiltrated the cookie value via any vector could
replay the bytes through their own user-agent and ride the victim's
authorization. RFC 9700 §4.7.1 calls out the gap explicitly and
recommends binding state to a user-agent fingerprint + source IP.

HOW.

Migration:
  migrations/000044_prelogin_uaip.up.sql
    ALTER TABLE oidc_pre_login_sessions
      ADD COLUMN IF NOT EXISTS client_ip   TEXT,
      ADD COLUMN IF NOT EXISTS user_agent  TEXT;
  Both nullable for in-flight rolling-deploy compat — the consume-
  side check only enforces when both row AND request carry non-empty
  values for the leg in question.

Domain:
  internal/repository/oidc.go (PreLoginSession) — adds ClientIP +
    UserAgent fields.

Repository:
  internal/repository/postgres/oidc_prelogin.go — Create persists
    via sql.NullString (empty → NULL); LookupAndConsume reads back.
    Re-uses package-local nullableString from discovery.go.

Service:
  internal/auth/oidc/service.go
    - PreLoginStore.CreatePreLogin signature takes (clientIP,
      userAgent) as positions 5–6.
    - PreLoginStore.LookupAndConsume returns (clientIP, userAgent)
      as positions 5–6.
    - HandleAuthRequest signature gains (clientIP, userAgent),
      threaded to the store.
    - HandleCallback adds Step 1.5 — UA / IP constant-time compare
      between stored row and incoming request. Per-leg toggles via
      preLoginRequireUA / preLoginRequireIP service fields. Empty
      values on either side pass through (rolling-deploy + headless-
      proxy compat).
    - New sentinels ErrPreLoginUAMismatch, ErrPreLoginIPMismatch.
    - SetPreLoginBindingRequirements(requireUA, requireIP) helper
      for main.go config wiring.

Adapter:
  internal/auth/oidc/prelogin.go — PreLoginAdapter passes the new
    fields through to the repo row.

Handler:
  internal/api/handler/auth_session_oidc.go
    - OIDCAuthHandshaker.HandleAuthRequest signature updated.
    - LoginInitiate captures clientIPFromRequest + r.UserAgent()
      and passes to the service.
    - classifyOIDCFailure adds errors.Is dispatch for the two new
      sentinels → prelogin_ua_mismatch / prelogin_ip_mismatch
      audit categories.

Config:
  internal/config/config.go
    + AuthConfig.OIDCPreLoginRequireUA (default true)
      env CERTCTL_OIDC_PRELOGIN_REQUIRE_UA
    + AuthConfig.OIDCPreLoginRequireIP (default true)
      env CERTCTL_OIDC_PRELOGIN_REQUIRE_IP
  cmd/server/main.go calls oidcService.SetPreLoginBindingRequirements
    from cfg.Auth.OIDCPreLoginRequire{UA,IP}.

Tests (internal/auth/oidc/service_test.go):
  - TestService_HandleCallback_MED16_UAMismatchRejected
  - TestService_HandleCallback_MED16_IPMismatchRejected
  - TestService_HandleCallback_MED16_BothMatch_Succeeds
  - TestService_HandleCallback_MED16_LegacyRowEmptyValues  (rolling-
    deploy compat — empty stored values pass through)
  - TestService_HandleCallback_MED16_RequireUAFalse_AllowsMismatch
    (operator escape-hatch — UA mismatch silently allowed)

Mechanical fan-out:
  - stubPreLogin / stubPreLoginRepo signatures updated.
  - All existing call sites in service_test.go (~40), prelogin_test.go,
    bench_test.go, logging_test.go, provider_enabled_test.go,
    integration_keycloak_test.go, integration_okta_smoke_test.go,
    auth_session_oidc_test.go updated to pass empty strings for the
    new params — pre-existing tests do not exercise UA/IP binding
    semantics.

VERIFY.

- go vet ./internal/auth/oidc/... ./internal/api/handler/...
  ./internal/config/...                                       PASS
- go test -short -count=1 -run MED16 ./internal/auth/oidc/... PASS (5/5)
- go test -short -count=1 ./internal/auth/oidc/...            PASS (4.6s)
- go test -short -count=1 ./internal/api/handler/...          PASS (4.3s)
- go test -short -count=1 ./internal/config/...               PASS

Refs: cowork/auth-bundles-audit-2026-05-10.md MED-16
      cowork/auth-bundles-fixes-2026-05-10/HANDOFF.md item 6
      RFC 9700 §4.7.1 — OAuth 2.0 Security Best Current Practice

internal/api/handler/auth_session_oidc.go

@@ -55,7 +55,10 @@ import (
 // OIDCAuthHandshaker is the slice of *oidc.Service the OIDC HTTP path
 // consumes. Phase 3's *oidc.Service satisfies this directly.
 type OIDCAuthHandshaker interface {
-	HandleAuthRequest(ctx context.Context, providerID string) (authURL, cookieValue, preLoginID string, err error)
+	// Audit 2026-05-10 MED-16 — clientIP + userAgent persist into the
+	// pre-login row so HandleCallback can reject mismatches at consume
+	// time (RFC 9700 §4.7.1 binding).
+	HandleAuthRequest(ctx context.Context, providerID, clientIP, userAgent string) (authURL, cookieValue, preLoginID string, err error)
 	// Audit 2026-05-10 MED-17 — callbackIss carries the value of the
 	// RFC 9207 `iss` query parameter on /auth/oidc/callback (empty
 	// string when the IdP doesn't send it). The service enforces the
@@ -233,7 +236,14 @@ func (h *AuthSessionOIDCHandler) LoginInitiate(w http.ResponseWriter, r *http.Re
 		Error(w, http.StatusBadRequest, "missing required query parameter `provider`")
 		return
 	}
-	authURL, cookieValue, _, err := h.oidcSvc.HandleAuthRequest(r.Context(), providerID)
+	// Audit 2026-05-10 MED-16 — capture clientIP + UA at /auth/oidc/login
+	// so HandleCallback can reject a stolen pre-login cookie replayed
+	// from a different browser/source. clientIPFromRequest already
+	// honours the LOW-5 trusted-proxy gating; r.UserAgent() reads the
+	// header verbatim.
+	loginIP := clientIPFromRequest(r)
+	loginUA := r.UserAgent()
+	authURL, cookieValue, _, err := h.oidcSvc.HandleAuthRequest(r.Context(), providerID, loginIP, loginUA)
 	if err != nil {
 		// Provider not found is the most common case; map to 404.
 		if errors.Is(err, repository.ErrOIDCProviderNotFound) {
@@ -1178,6 +1188,9 @@ func classifyOIDCFailure(err error) string {
 		return "ok"
 	}
 	// Audit 2026-05-10 MED-17 — typed dispatch for the iss family.
+	// Audit 2026-05-10 MED-16 — typed dispatch for the UA/IP binding
+	// family (no substring guarantees because UA strings are operator
+	// data and could match anything).
 	switch {
 	case errors.Is(err, oidcsvc.ErrIssParamMissing):
 		return "iss_param_missing"
@@ -1185,6 +1198,10 @@ func classifyOIDCFailure(err error) string {
 		return "iss_param_mismatch"
 	case errors.Is(err, oidcsvc.ErrIssuerMismatch):
 		return "id_token_iss_mismatch"
+	case errors.Is(err, oidcsvc.ErrPreLoginUAMismatch):
+		return "prelogin_ua_mismatch"
+	case errors.Is(err, oidcsvc.ErrPreLoginIPMismatch):
+		return "prelogin_ip_mismatch"
 	}
 	msg := strings.ToLower(err.Error())
 	switch {

internal/api/handler/auth_session_oidc_test.go

@@ -43,7 +43,7 @@ type stubOIDCSvc struct {
 	refreshErr  error
 }
 
-func (s *stubOIDCSvc) HandleAuthRequest(_ context.Context, _ string) (string, string, string, error) {
+func (s *stubOIDCSvc) HandleAuthRequest(_ context.Context, _, _, _ string) (string, string, string, error) {
 	return s.authURL, s.cookie, s.preLoginID, s.authReqErr
 }
 func (s *stubOIDCSvc) HandleCallback(_ context.Context, _, _, _, _, _, _ string) (*oidcsvc.CallbackResult, error) {