auth-bundle-2 Phase 7 + Phase 7.5: OIDC first-admin bootstrap +

break-glass admin (Argon2id, lockout, default-OFF, surface-invisibility)

Phase 7 — OIDC first-admin bootstrap (Decision 3):

  - Optional AdminBootstrapHook closure on *oidc.Service. When wired,
    HandleCallback consults the hook AFTER group resolution + user
    upsert and BEFORE the empty-mapping fail-closed check. Hook
    receives (providerID, groups, userID); returns grantAdmin=true
    when the user matches CERTCTL_BOOTSTRAP_ADMIN_GROUPS AND no
    admin exists yet in the tenant.
  - cmd/server/main.go wires the hook as a closure that:
      * Filters by CERTCTL_BOOTSTRAP_OIDC_PROVIDER_ID (if configured).
      * Probes AdminExists via authActorRoleRepo (admin-already-exists
        silently returns false; bootstrap mode is one-shot per tenant).
      * Walks group intersection.
      * On match: grants r-admin via authActorRoleRepo.Grant + emits
        the bootstrap.oidc_first_admin audit row with
        event_category=auth + INFO log.
  - Coexists with the Bundle 1 env-var-token bootstrap. Both paths
    can be configured; first match wins (admin-existence probe
    short-circuits the second).
  - HandleCallback's empty-mapping fail-closed check moved AFTER the
    hook so a fresh deployment with zero group_role_mappings can
    still mint the first admin.
  - 5 tests in service_test.go: hook grants admin on match, hook
    returns false preserves empty-mapping fail-closed, admin-already-
    exists silently falls through to normal mapping, hook-error wraps
    + bubbles, idempotent when admin is already in the mapped role set.

Phase 7.5 — Break-glass admin (Decision 4, default-OFF):

Migration 000038 ships:

  - breakglass_credentials table — at-most-one-credential-per-actor
    (UNIQUE(actor_id)), Argon2id PHC-format password_hash, lockout
    state machine (failure_count, locked_until, last_failure_at).
    FK CASCADE on users(id) so deleting a user atomically removes
    their credential.
  - Two new permissions seeded into r-admin only:
      auth.breakglass.admin — set/rotate/unlock/remove credentials.
      auth.breakglass.login — actor uses break-glass to log in.
    CanonicalPermissions extended in lockstep.

internal/auth/breakglass/service.go (~580 LOC):

  - Service.Enabled() reflects CERTCTL_BREAKGLASS_ENABLED.
  - SetPassword: Argon2id with OWASP 2024 params (m=64MiB, t=3, p=4,
    salt=16 random bytes, output=32 bytes); per-password random salt;
    PHC-format hash output. Min 12 / max 256 byte input.
  - Authenticate: constant-time-compare via subtle.ConstantTimeCompare
    on every code path. Identical 401 + identical timing across the
    wrong-password / locked-account / non-existent-actor paths so an
    attacker cannot probe whether a given actor has break-glass
    configured. Non-existent-actor + locked-account paths run a
    verifyDummy() Argon2id pass for timing parity. Lockout state
    machine: failure_count++ on every wrong attempt; threshold (default
    5) trips locked_until = NOW() + duration (default 15m). Successful
    Authenticate resets the counter. Reset-window: failures aged out
    after CERTCTL_BREAKGLASS_LOCKOUT_RESET_INTERVAL (default 1h)
    auto-reset on next attempt.
  - Unlock + RemoveCredential: admin-only (auth.breakglass.admin
    gated at the router via rbacGate). Audit rows on every operation.
  - All public methods refuse to act when Enabled()==false (returns
    ErrDisabled; the handler maps to HTTP 404 — surface invisibility).

internal/repository/postgres/breakglass.go ships the 5-method
postgres impl with atomic single-statement IncrementFailure (so
concurrent racing wrong-password attempts can't observe an
intermediate state and slip past the threshold) and idempotent
ResetFailureCount.

internal/api/handler/auth_breakglass.go ships the 4-endpoint HTTP
surface:

  - POST /auth/breakglass/login (auth-exempt; 5/min rate-limited per
    source IP via the existing rate limiter; returns 404 when
    disabled). On success sets the post-login session cookie + CSRF
    cookie via SessionService.Create + 204. On any failure:
    uniform 401 + identical timing (the service has already audited
    the specific failure category).
  - POST /api/v1/auth/breakglass/credentials (auth.breakglass.admin)
  - POST /api/v1/auth/breakglass/credentials/{actor_id}/unlock
    (auth.breakglass.admin)
  - DELETE /api/v1/auth/breakglass/credentials/{actor_id}
    (auth.breakglass.admin)

Admin endpoints share the surface-invisibility property: when
CERTCTL_BREAKGLASS_ENABLED=false, every admin endpoint also returns
404 (not 403) so probing via the admin surface gets the same signal
as probing the login endpoint.

Tests (internal/auth/breakglass/service_test.go):

All 8 Phase 7.5 spec-mandated negative cases:

  1. Service.Enabled()==false → all ops return ErrDisabled.
  2. Wrong password → ErrInvalidCredentials, failure_count++,
     audit row with event_category=auth.
  3. Failure_count exceeds threshold → locked, subsequent attempts
     (including with the CORRECT password) return identical-shape
     401 while the lockout window holds.
  4. Lockout window expires → next attempt with correct password
     succeeds + resets the counter.
  5. Password < 12 bytes (or > 256 bytes) → ErrWeakPassword.
  6. Password leak hygiene — the service has zero slog calls; the
     audit-row map literal never includes the password plaintext.
  7. Argon2id hash never appears in logs OR API responses — pinned
     by `json:"-"` tag on BreakglassCredential.PasswordHash + a
     belt-and-braces json.Marshal probe asserting the hash bytes
     never appear in the marshaled output.
  8. Constant-time-compare verified via timing-statistical test —
     wrong-password vs no-credential paths take statistically
     indistinguishable time (within 5x ratio). The verifyDummy()
     hash compute on the no-credential + locked paths is what
     keeps timing parity; absent that, an attacker could side-
     channel "actor doesn't have a credential" via timing.

Plus coverage-lift batch covering: SetPassword first-time vs rotate,
no-caller-id rejection, no-target-id rejection, RNG failure surface,
Authenticate happy-path mints session, no-credential audit row,
session-mint-failure surface, FailureResetInterval recycle, Unlock
+ RemoveCredential happy paths, hash-format unit tests (round-trip,
mismatch, malformed/wrong-version/bad-base64 formats), nil-audit +
nil-session pass-through.

Coverage on internal/auth/breakglass/ at 91.5% per-statement (above
the Phase 7.5 spec ≥ 90% floor).

cmd/server/main.go wiring:

  - Constructs breakglassRepo + breakglassService + breakglassHandler
    after the OIDC service block.
  - breakglassSessionMinterAdapter shim bridges *session.Service.Create
    to the breakglass.SessionMinter port.
  - Logs WARN at boot when CERTCTL_BREAKGLASS_ENABLED=true (operator
    visibility for the deliberate SSO-bypass).

internal/config/config.go gains:

  - AuthConfig.BootstrapAdminGroups + BootstrapOIDCProviderID for
    Phase 7 (CERTCTL_BOOTSTRAP_ADMIN_GROUPS comma-list +
    CERTCTL_BOOTSTRAP_OIDC_PROVIDER_ID).
  - AuthConfig.Breakglass nested struct with 4 env vars
    (CERTCTL_BREAKGLASS_ENABLED + LOCKOUT_THRESHOLD + LOCKOUT_DURATION
    + LOCKOUT_RESET_INTERVAL).

Router wiring:

  - 4 new breakglass routes registered when reg.AuthBreakglass != nil;
    public login route via direct r.mux.Handle (auth-exempt), 3 admin
    routes via r.Register + rbacGate(auth.breakglass.admin).
  - POST /auth/breakglass/login pinned in AuthExemptRouterRoutes
    allowlist with Phase 7.5 justification.
  - SpecParityExceptions extended with 4 new entries documenting
    the Phase 7.5 deferral of full per-endpoint OpenAPI rows
    (handler doc-block at the top of auth_breakglass.go is the
    operator-facing reference).

Threat model (encoded in service.go + auth_breakglass.go doc-blocks
+ migration 000038 docstrings, to be promoted to docs/operator/auth-
threat-model.md in Phase 12):

  - Break-glass is a deliberate bypass of the SSO security boundary.
    An attacker who phishes the password OR finds it in a compromised
    password manager bypasses MFA, OIDC, and every group-claim gate.
  - Recommendation: keep CERTCTL_BREAKGLASS_ENABLED=false in steady-
    state. Enable only during SSO-broken incidents. Disable after
    recovery.
  - WebAuthn pairing (v3 per Decision 12) is the load-bearing second
    factor. Without it, break-glass is best treated as an emergency-
    only path.
  - Audit trail surfaces every break-glass action under
    event_category=auth; the auditor role can monitor for unexpected
    break-glass logins.

Verifications: gofmt clean, go vet clean across all touched packages,
go test -short -count=1 green across internal/auth/oidc (3.0s; new
Phase 7 hook tests integrated alongside the 21+ Phase 3 negatives),
internal/auth/breakglass (3.6s; 8 spec-mandated negatives + coverage
batch passing), internal/config + internal/domain/auth + internal/api/
router + internal/api/handler all green, no regressions in Bundle 1
packages.

internal/config/config.go

@@ -1596,6 +1596,33 @@ type AuthConfig struct {
 	// legacy `api-key` auth type ignore this struct entirely.
 	Session SessionConfig
 
+	// Breakglass holds the Auth Bundle 2 Phase 7.5 break-glass admin
+	// tunables. Default-OFF; the entire surface is invisible (404
+	// instead of 403) when CERTCTL_BREAKGLASS_ENABLED is not true.
+	// Threat model: enabling break-glass is a deliberate bypass of
+	// the SSO security boundary; operators turn it on during SSO
+	// incidents and turn it off after recovery.
+	Breakglass BreakglassConfig
+
+	// BootstrapAdminGroups is the comma-separated list of IdP group
+	// names that grant the FIRST OIDC-authenticated user the r-admin
+	// role. Auth Bundle 2 Phase 7 / Decision 3. Empty (default)
+	// disables the OIDC-first-admin bootstrap path; the env-var-token
+	// path (BootstrapToken below) remains the fallback for fresh
+	// deployments without OIDC. When both are configured, OIDC wins
+	// on group match.
+	// Setting: CERTCTL_BOOTSTRAP_ADMIN_GROUPS environment variable.
+	BootstrapAdminGroups []string
+
+	// BootstrapOIDCProviderID restricts the OIDC-first-admin bootstrap
+	// path to a specific provider id (matches the seeded provider
+	// name in oidc_providers.id). Empty (default) accepts a match
+	// from any configured provider. Useful when an operator
+	// configures multiple IdPs and wants only the corporate IdP to
+	// be eligible for bootstrap.
+	// Setting: CERTCTL_BOOTSTRAP_OIDC_PROVIDER_ID environment variable.
+	BootstrapOIDCProviderID string
+
 	// BootstrapToken is the one-shot pre-shared secret that gates the
 	// Bundle 1 Phase 6 bootstrap endpoint (POST /v1/auth/bootstrap). When
 	// set at server startup AND no admin-roled actors exist, the
@@ -1666,6 +1693,38 @@ type SessionConfig struct {
 	BindUserAgent bool
 }
 
+// BreakglassConfig contains the Auth Bundle 2 Phase 7.5 break-glass
+// admin tunables. Decision 4: operator-toggleable local-password
+// admin for the SSO-broken case. Default-OFF; the entire surface is
+// invisible (404 NOT 403) when Enabled=false.
+//
+// Threat model (load-bearing): enabling break-glass is a deliberate
+// bypass of the SSO security boundary. An attacker who phishes the
+// password OR finds it in a compromised password manager bypasses
+// MFA, OIDC, and every group-claim gate. Recommendation: keep
+// CERTCTL_BREAKGLASS_ENABLED=false in steady-state. Enable only
+// during SSO-broken incidents. Disable after recovery. WebAuthn
+// pairing (v3 per Decision 12) is the load-bearing second factor.
+type BreakglassConfig struct {
+	// Enabled gates the entire service surface. Default false.
+	// Wire: CERTCTL_BREAKGLASS_ENABLED.
+	Enabled bool
+
+	// LockoutThreshold is the failure count that trips the lockout.
+	// Default 5. Wire: CERTCTL_BREAKGLASS_LOCKOUT_THRESHOLD.
+	LockoutThreshold int
+
+	// LockoutDuration is how long the account stays locked after the
+	// threshold trips. Default 15m.
+	// Wire: CERTCTL_BREAKGLASS_LOCKOUT_DURATION.
+	LockoutDuration time.Duration
+
+	// LockoutResetInterval is the idle time after last_failure_at
+	// before the failure counter resets to 0 on next attempt.
+	// Default 1h. Wire: CERTCTL_BREAKGLASS_LOCKOUT_RESET_INTERVAL.
+	LockoutResetInterval time.Duration
+}
+
 // RateLimitConfig contains rate limiting configuration.
 //
 // Bundle B / Audit M-025 (OWASP ASVS L2 §11.2.1): pre-bundle the rate
@@ -1789,6 +1848,12 @@ func Load() (*Config, error) {
 			// /v1/auth/bootstrap endpoint that mints the first admin
 			// key. Empty = bootstrap endpoint disabled (default).
 			BootstrapToken: getEnv("CERTCTL_BOOTSTRAP_TOKEN", ""),
+			// Bundle 2 Phase 7: OIDC-first-admin bootstrap. When the
+			// configured group list is non-empty, the first OIDC
+			// login that carries any of those groups is auto-granted
+			// r-admin. Coexists with BootstrapToken.
+			BootstrapAdminGroups:    getEnvList("CERTCTL_BOOTSTRAP_ADMIN_GROUPS", nil),
+			BootstrapOIDCProviderID: getEnv("CERTCTL_BOOTSTRAP_OIDC_PROVIDER_ID", ""),
 			// Bundle 2 Phase 4: session-service tunables. Defaults match
 			// the prompt; high-security deployments tighten via the env
 			// vars documented on SessionConfig fields.
@@ -1801,6 +1866,16 @@ func Load() (*Config, error) {
 				BindIP:              getEnvBool("CERTCTL_SESSION_BIND_IP", false),
 				BindUserAgent:       getEnvBool("CERTCTL_SESSION_BIND_USER_AGENT", false),
 			},
+			// Bundle 2 Phase 7.5: break-glass admin tunables. Default-
+			// OFF; the entire surface is invisible (404 NOT 403) when
+			// Enabled=false. Threat model + recommendation in the
+			// BreakglassConfig docstring.
+			Breakglass: BreakglassConfig{
+				Enabled:              getEnvBool("CERTCTL_BREAKGLASS_ENABLED", false),
+				LockoutThreshold:     getEnvInt("CERTCTL_BREAKGLASS_LOCKOUT_THRESHOLD", 5),
+				LockoutDuration:      getEnvDuration("CERTCTL_BREAKGLASS_LOCKOUT_DURATION", 15*time.Minute),
+				LockoutResetInterval: getEnvDuration("CERTCTL_BREAKGLASS_LOCKOUT_RESET_INTERVAL", 1*time.Hour),
+			},
 		},
 		RateLimit: RateLimitConfig{
 			Enabled:          getEnvBool("CERTCTL_RATE_LIMIT_ENABLED", true),