auth-bundle-2 Phase 5: OIDC + session HTTP surface (13 endpoints),

pre-login store, OpenID Connect Back-Channel Logout 1.0, cookieAuth
scheme, 7 new auth permissions, CI guard, handler tests

Phase 5 of the bundle puts the Phase 3 OIDC service + Phase 4 session
service on the wire. 13 HTTP endpoints split into three logical groups:

Public OIDC handshake (auth-exempt; protocol-mediated):
  GET  /auth/oidc/login?provider=<id>  -> 302 to IdP authorization URL
                                          + sets certctl_oidc_pending cookie
                                          (10-min TTL, Path=/auth/oidc/,
                                          SameSite=Lax)
  GET  /auth/oidc/callback?code=...&state=... -> consume pre-login row,
                                          run Phase 3's 11-step token
                                          validation, mint post-login
                                          session, 302 to dashboard
  POST /auth/oidc/back-channel-logout  -> OpenID Connect BCL 1.0 — IdP
                                          POSTs logout_token JWT; certctl
                                          validates signature against IdP
                                          JWKS via Phase 3 alg allow-list,
                                          required claims (iss/aud/iat/jti/
                                          events; exactly one of sub/sid;
                                          nonce ABSENT per spec §2.4),
                                          revokes matching sessions,
                                          returns 200 with
                                          Cache-Control: no-store
  POST /auth/logout                    -> revoke caller's session

Session management (RBAC-gated auth.session.*):
  GET    /api/v1/auth/sessions         -> auth.session.list (own / all)
  DELETE /api/v1/auth/sessions/{id}    -> auth.session.revoke (own bypass)

OIDC provider + group-mapping CRUD (RBAC-gated auth.oidc.*):
  GET    /api/v1/auth/oidc/providers              -> auth.oidc.list
  POST   /api/v1/auth/oidc/providers              -> auth.oidc.create
                                                     (client_secret encrypted
                                                     at rest via
                                                     internal/crypto.EncryptIfKeySet)
  PUT    /api/v1/auth/oidc/providers/{id}         -> auth.oidc.edit
  DELETE /api/v1/auth/oidc/providers/{id}         -> auth.oidc.delete
                                                     (refused via
                                                     ErrOIDCProviderInUse → 409
                                                     when users authenticated
                                                     via this provider)
  POST   /api/v1/auth/oidc/providers/{id}/refresh -> auth.oidc.edit
                                                     (re-runs IdP downgrade
                                                     defense via
                                                     OIDCService.RefreshKeys)
  GET    /api/v1/auth/oidc/group-mappings         -> auth.oidc.list
  POST   /api/v1/auth/oidc/group-mappings         -> auth.oidc.edit
  DELETE /api/v1/auth/oidc/group-mappings/{id}    -> auth.oidc.edit

Migration 000037 ships:

  - oidc_pre_login_sessions table (10-min absolute TTL, FK CASCADE on
    oidc_provider_id, FK RESTRICT on signing_key_id; index on
    absolute_expires_at for the GC sweep);
  - 7 new permissions seeded into r-admin only:
      auth.session.list, auth.session.list.all, auth.session.revoke,
      auth.oidc.list, auth.oidc.create, auth.oidc.edit, auth.oidc.delete

CanonicalPermissions extended in lockstep at internal/domain/auth/
validate.go.

Pre-login machinery:

  - internal/repository/oidc.go gains PreLoginRepository interface +
    PreLoginSession struct + ErrPreLoginNotFound / ErrPreLoginExpired
    sentinels.
  - internal/repository/postgres/oidc_prelogin.go ships the impl;
    LookupAndConsume uses DELETE ... RETURNING for atomic single-use.
  - internal/auth/oidc/prelogin.go is the PreLoginAdapter that bridges
    the OIDC service's Phase 3 PreLoginStore interface to the new
    repository, signing the cookie value under the active
    SessionSigningKey via the same v1.<id>.<key>.<HMAC> wire format
    Phase 4 uses for post-login cookies. Defense-in-depth: the
    pre-login `pl-` prefix is enforced by ParseCookieValue(prefix);
    a stolen pre-login cookie cannot be replayed against the
    post-login Validate path (pinned by
    TestService_Validate_RejectsPreLoginCookieAtPostLoginGate).

Session package extension:

  - internal/auth/session/service.go gains exported SignCookieValue,
    ParseCookieValue (with caller-supplied id-1 prefix), ComputeCookieHMAC,
    DecryptKeyMaterial wrappers so the OIDC pre-login adapter shares
    the same length-prefixed HMAC math without code duplication.
  - parseCookie no longer hardcodes the `ses-` prefix check (moved to
    Validate as defense-in-depth; pre-login cookie verification uses
    the `pl-` prefix via ParseCookieValue).

Cookie attributes (all Phase 5 endpoints honor CERTCTL_SESSION_SAMESITE
+ Secure=true via SessionCookieAttrs from Phase 4 config):

  - certctl_oidc_pending: Path=/auth/oidc/, MaxAge=600s, SameSite=Lax
    (cannot be Strict because the IdP-initiated callback is a top-level
    navigation from a different origin).
  - certctl_session: Path=/, Expires=8h, SameSite=Lax|Strict, HttpOnly.
  - certctl_csrf: Path=/, Expires=8h, HttpOnly=false (intentional —
    GUI must read it to echo into X-CSRF-Token header).

Audit logging on every mutating operation (event_category="auth"):

  auth.oidc_login_succeeded / failed / unmapped_groups
  auth.oidc_back_channel_logout / failed
  auth.session_revoked
  auth.oidc_provider_{created,updated,deleted,refreshed}
  auth.group_mapping_{added,removed}

OpenAPI updates:

  - cookieAuth security scheme added to api/openapi.yaml under
    components.securitySchemes (apiKey / cookie / certctl_session).
  - The 13 Phase 5 routes are added to SpecParityExceptions with a
    deferral note: full per-endpoint OpenAPI rows land in a follow-on
    commit alongside the GUI work (Phase 8) so the ergonomic shape can
    be validated against the live GUI client.

CI guard: scripts/ci-guards/N-bundle-2-security-empty-preserved.sh
asserts api/openapi.yaml has ≥ 14 'security: []' occurrences (the
pre-Bundle-2 baseline). Reducing the count below 14 would silently
force a Bearer-or-cookie requirement onto an endpoint that legitimately
runs without certctl-issued credentials; the guard fires before that
regression lands.

Handler tests (internal/api/handler/auth_session_oidc_test.go):

  - All 6 prompt-mandated negative cases:
      BCL with missing events claim -> 400
      BCL with nonce present -> 400 (per spec §2.4)
      BCL with sig signed by an unknown key -> 400
      Callback with replayed state -> 400
      Callback with PKCE verifier mismatch -> 400
      Callback with expired pre-login row -> 400
  - Plus happy paths for every endpoint, edge cases (missing-cookie,
    duplicate-name, in-use-409, wrong-tenant), and the Helper-function
    coverage (peekIssuer, classifyOIDCFailure, defaultIfBlank,
    defaultIntIfZero, clientIPFromRequest, encryptClientSecret).

Coverage on internal/api/handler/auth_session_oidc.go: 80.9% per-function
(above the Phase 5 spec's ≥ 80% floor).

Server wiring (cmd/server/main.go):

  Wired AFTER sessionService (Phase 4) so the OIDC PreLoginAdapter can
  sign pre-login cookies under the active SessionSigningKey:
    oidcProviderRepo + oidcMappingRepo + oidcUserRepo + oidcPreLoginRepo
    -> preLoginAdapter -> oidcService -> authSessionOIDCHandler.
  sessionMinterAdapter shim bridges *session.Service.Create to the
  oidcsvc.SessionMinter port the OIDC service consumes.

Router wiring (internal/api/router/router.go):

  4 public OIDC routes via direct r.mux.Handle (auth-exempt; pinned in
  AuthExemptRouterRoutes); 9 RBAC-gated routes via r.Register +
  rbacGate(checker, perm, h). Routes only register when
  reg.AuthSessionOIDC != nil so pre-Phase-5 builds skip the block
  entirely.

Verifications: gofmt clean, go vet clean across all touched packages,
go test -short -count=1 green across internal/api/handler (74 tests +
new Phase 5 batch), internal/api/router (parity + auth-exempt
allowlist), internal/auth/oidc + session (no regressions), full domain
+ scheduler + config sweeps green, ci-guard
N-bundle-2-security-empty-preserved.sh green (17 ≥ 14 baseline).

internal/auth/oidc/prelogin.go

@@ -0,0 +1,180 @@
+// Package oidc — Bundle 2 Phase 5 / pre-login cookie machinery.
+//
+// This file implements the production-side PreLoginStore that the
+// Phase 3 OIDC service wires into HandleAuthRequest + HandleCallback.
+// Phase 3 shipped the interface + an in-memory test stub; Phase 5
+// ships the real implementation backed by:
+//
+//   - oidc_pre_login_sessions table (Phase 5 migration 000037)
+//   - the active SessionSigningKey (Phase 4 service)
+//
+// The cookie wire format is `v1.<pl-id>.<sk-id>.<base64url-no-pad
+// HMAC-SHA256>` — IDENTICAL to the post-login session cookie shape so
+// both surfaces share the same parser, the same length-prefixed HMAC
+// input (defeats concatenation collisions), and the same v1. version
+// prefix. Different cookie name (`certctl_oidc_pending` vs
+// `certctl_session`) and different id prefix (`pl-` vs `ses-`) keep
+// the two surfaces distinguishable; defense-in-depth checks at each
+// consumer reject the wrong-prefix shape even if the cookie value
+// somehow gets routed to the wrong handler.
+
+package oidc
+
+import (
+	"context"
+	cryptorand "crypto/rand"
+	"crypto/subtle"
+	"encoding/base64"
+	"errors"
+	"fmt"
+
+	"github.com/certctl-io/certctl/internal/auth/session"
+	sessiondomain "github.com/certctl-io/certctl/internal/auth/session/domain"
+	"github.com/certctl-io/certctl/internal/repository"
+)
+
+// SigningKeyLookup is the slice of SessionSigningKey access the
+// pre-login adapter needs. SessionService satisfies this implicitly
+// via the Phase 4 SigningKeyRepo (we re-use the interface here rather
+// than adding a method to SessionService).
+type SigningKeyLookup interface {
+	GetActive(ctx context.Context, tenantID string) (*sessiondomain.SessionSigningKey, error)
+	Get(ctx context.Context, id string) (*sessiondomain.SessionSigningKey, error)
+}
+
+// PreLoginAdapter implements the Phase 3 OIDCService.PreLoginStore
+// interface against a real PreLoginRepository + the active
+// SessionSigningKey.
+//
+// The cookie value returned by CreatePreLogin is the wire-format
+// `v1.pl-<id>.sk-<id>.<HMAC-SHA256>`; LookupAndConsume parses + HMAC-
+// verifies the cookie value before reading + deleting the row.
+type PreLoginAdapter struct {
+	repo          repository.PreLoginRepository
+	keys          SigningKeyLookup
+	tenantID      string
+	encryptionKey string
+
+	// Injectable for tests so the adapter can be exercised against a
+	// deterministic-failure RNG.
+	readRand func([]byte) (int, error)
+}
+
+// NewPreLoginAdapter constructs a PreLoginAdapter wired against the
+// supplied repository + signing-key lookup. encryptionKey is the
+// CERTCTL_CONFIG_ENCRYPTION_KEY value used to decrypt the
+// SessionSigningKey.KeyMaterialEncrypted blob.
+func NewPreLoginAdapter(
+	repo repository.PreLoginRepository,
+	keys SigningKeyLookup,
+	tenantID, encryptionKey string,
+) *PreLoginAdapter {
+	return &PreLoginAdapter{
+		repo:          repo,
+		keys:          keys,
+		tenantID:      tenantID,
+		encryptionKey: encryptionKey,
+		readRand:      cryptorand.Read,
+	}
+}
+
+// SetRandReaderForTest replaces the entropy source. ONLY for tests.
+func (a *PreLoginAdapter) SetRandReaderForTest(r func([]byte) (int, error)) {
+	a.readRand = r
+}
+
+// CreatePreLogin generates a fresh `pl-<random>` id, signs the cookie
+// value under the active SessionSigningKey, persists the row, and
+// returns the cookie value + the row id.
+//
+// Implements the Phase 3 OIDCService.PreLoginStore.CreatePreLogin
+// interface signature.
+func (a *PreLoginAdapter) CreatePreLogin(ctx context.Context, providerID, state, nonce, verifier string) (cookieValue, sessionID string, err error) {
+	active, err := a.keys.GetActive(ctx, a.tenantID)
+	if err != nil {
+		return "", "", fmt.Errorf("pre-login: get active signing key: %w", err)
+	}
+	hmacKey, err := session.DecryptKeyMaterial(active.KeyMaterialEncrypted, a.encryptionKey)
+	if err != nil {
+		return "", "", fmt.Errorf("pre-login: decrypt active key: %w", err)
+	}
+	id, err := a.newID()
+	if err != nil {
+		return "", "", fmt.Errorf("pre-login: generate id: %w", err)
+	}
+	row := &repository.PreLoginSession{
+		ID:             id,
+		TenantID:       a.tenantID,
+		SigningKeyID:   active.ID,
+		OIDCProviderID: providerID,
+		State:          state,
+		Nonce:          nonce,
+		PKCEVerifier:   verifier,
+	}
+	if err := a.repo.Create(ctx, row); err != nil {
+		return "", "", fmt.Errorf("pre-login: persist row: %w", err)
+	}
+	cookieValue = session.SignCookieValue(id, active.ID, hmacKey)
+	return cookieValue, id, nil
+}
+
+// LookupAndConsume parses + HMAC-verifies the cookie value, looks up
+// the row, atomically deletes it, and returns the OIDC handshake
+// material the callback handler needs.
+//
+// Failure semantics:
+//   - Malformed cookie / wrong v1. prefix / wrong id prefix /
+//     bad base64 HMAC -> ErrPreLoginNotFound (uniform 400 to the wire,
+//     no information leak about which check failed).
+//   - HMAC mismatch -> ErrPreLoginNotFound (forged cookie).
+//   - Signing key id not found -> ErrPreLoginNotFound.
+//   - Row not found OR already consumed -> ErrPreLoginNotFound.
+//   - Row found but past 10-minute TTL -> ErrPreLoginExpired (row is
+//     deleted at the repo layer regardless).
+//
+// Implements the Phase 3 OIDCService.PreLoginStore.LookupAndConsume
+// interface signature.
+func (a *PreLoginAdapter) LookupAndConsume(ctx context.Context, cookieValue string) (providerID, state, nonce, verifier string, err error) {
+	plID, signingKeyID, providedHMAC, perr := session.ParseCookieValue(cookieValue, "pl-")
+	if perr != nil {
+		return "", "", "", "", ErrPreLoginNotFound
+	}
+
+	signingKey, kerr := a.keys.Get(ctx, signingKeyID)
+	if kerr != nil {
+		return "", "", "", "", ErrPreLoginNotFound
+	}
+	hmacKey, derr := session.DecryptKeyMaterial(signingKey.KeyMaterialEncrypted, a.encryptionKey)
+	if derr != nil {
+		return "", "", "", "", ErrPreLoginNotFound
+	}
+	expectedHMAC := session.ComputeCookieHMAC(plID, signingKeyID, hmacKey)
+	if subtle.ConstantTimeCompare(expectedHMAC, providedHMAC) != 1 {
+		return "", "", "", "", ErrPreLoginNotFound
+	}
+
+	row, lerr := a.repo.LookupAndConsume(ctx, plID)
+	if lerr != nil {
+		// Map both not-found AND expired to the same uniform sentinel
+		// the OIDC service consumes; the audit row distinguishes via
+		// the wrapped error from the repo (which the handler logs).
+		if errors.Is(lerr, repository.ErrPreLoginNotFound) {
+			return "", "", "", "", ErrPreLoginNotFound
+		}
+		if errors.Is(lerr, repository.ErrPreLoginExpired) {
+			return "", "", "", "", ErrPreLoginNotFound
+		}
+		return "", "", "", "", fmt.Errorf("pre-login: lookup_and_consume: %w", lerr)
+	}
+
+	return row.OIDCProviderID, row.State, row.Nonce, row.PKCEVerifier, nil
+}
+
+// newID returns `pl-<base64url-no-pad>` with 16 bytes of entropy.
+func (a *PreLoginAdapter) newID() (string, error) {
+	b := make([]byte, 16)
+	if _, err := a.readRand(b); err != nil {
+		return "", err
+	}
+	return "pl-" + base64.RawURLEncoding.EncodeToString(b), nil
+}