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.

cmd/server/main.go

@@ -24,6 +24,7 @@ import (
 	"github.com/certctl-io/certctl/internal/api/router"
 	"github.com/certctl-io/certctl/internal/auth"
 	"github.com/certctl-io/certctl/internal/auth/bootstrap"
+	"github.com/certctl-io/certctl/internal/auth/breakglass"
 	oidcsvc "github.com/certctl-io/certctl/internal/auth/oidc"
 	oidcdomain "github.com/certctl-io/certctl/internal/auth/oidc/domain"
 	"github.com/certctl-io/certctl/internal/auth/session"
@@ -438,6 +439,102 @@ func main() {
 		},
 	)
 
+	// =========================================================================
+	// Auth Bundle 2 Phase 7 — OIDC first-admin bootstrap hook.
+	//
+	// Wired AFTER oidcService is constructed. The hook closure consults
+	// the configured CERTCTL_BOOTSTRAP_ADMIN_GROUPS + the AdminExists
+	// probe; on first match it grants r-admin via the ActorRoleRepository
+	// + emits a bootstrap.oidc_first_admin audit row. Subsequent
+	// admin-already-exists logins return grantAdmin=false silently.
+	// Disabled (no-op) when CERTCTL_BOOTSTRAP_ADMIN_GROUPS is empty.
+	if len(cfg.Auth.BootstrapAdminGroups) > 0 {
+		bootstrapGroups := make(map[string]struct{}, len(cfg.Auth.BootstrapAdminGroups))
+		for _, g := range cfg.Auth.BootstrapAdminGroups {
+			bootstrapGroups[strings.TrimSpace(g)] = struct{}{}
+		}
+		bootstrapProviderID := cfg.Auth.BootstrapOIDCProviderID
+		oidcService.SetAdminBootstrapHook(func(ctx context.Context, providerID string, groups []string, userID string) (bool, error) {
+			// Provider-specificity: when configured, only the named
+			// provider is eligible for bootstrap.
+			if bootstrapProviderID != "" && providerID != bootstrapProviderID {
+				return false, nil
+			}
+			// Admin-already-exists: bootstrap mode is disabled once
+			// any actor in the tenant holds r-admin.
+			adminExists, probeErr := authActorRoleRepo.AdminExists(ctx, authdomainAlias.DefaultTenantID)
+			if probeErr != nil {
+				return false, fmt.Errorf("admin existence probe: %w", probeErr)
+			}
+			if adminExists {
+				return false, nil
+			}
+			// Group intersection check.
+			matched := false
+			for _, g := range groups {
+				if _, ok := bootstrapGroups[g]; ok {
+					matched = true
+					break
+				}
+			}
+			if !matched {
+				return false, nil
+			}
+			// Match. Grant r-admin via the actor-role repo.
+			grant := &authdomainAlias.ActorRole{
+				ActorID:   userID,
+				ActorType: authdomainAlias.ActorTypeValue("User"),
+				RoleID:    authdomainAlias.RoleIDAdmin,
+				TenantID:  authdomainAlias.DefaultTenantID,
+				GrantedBy: "oidc-bootstrap",
+			}
+			if gerr := authActorRoleRepo.Grant(ctx, grant); gerr != nil {
+				return false, fmt.Errorf("grant r-admin: %w", gerr)
+			}
+			// Emit audit row with event_category=auth.
+			_ = auditService.RecordEventWithCategory(ctx, userID, domain.ActorTypeUser,
+				"bootstrap.oidc_first_admin", domain.EventCategoryAuth,
+				"users", userID,
+				map[string]interface{}{
+					"user_id":     userID,
+					"provider_id": providerID,
+					"trigger":     "oidc_group_match",
+				})
+			logger.Info("OIDC first-admin bootstrap fired — user granted r-admin",
+				"user_id", userID, "provider_id", providerID)
+			return true, nil
+		})
+		logger.Info("OIDC first-admin bootstrap enabled",
+			"groups", cfg.Auth.BootstrapAdminGroups,
+			"provider_id_filter", bootstrapProviderID)
+	}
+
+	// =========================================================================
+	// Auth Bundle 2 Phase 7.5 — break-glass admin service + handler.
+	// =========================================================================
+	breakglassRepo := postgres.NewBreakglassCredentialRepository(db)
+	breakglassService := breakglass.NewService(
+		breakglassRepo,
+		auditService,
+		breakglassSessionMinterAdapter{svc: sessionService},
+		breakglass.Config{
+			Enabled:              cfg.Auth.Breakglass.Enabled,
+			LockoutThreshold:     cfg.Auth.Breakglass.LockoutThreshold,
+			LockoutDuration:      cfg.Auth.Breakglass.LockoutDuration,
+			LockoutResetInterval: cfg.Auth.Breakglass.LockoutResetInterval,
+		},
+		authdomainAlias.DefaultTenantID,
+	)
+	breakglassHandler := handler.NewAuthBreakglassHandler(breakglassService, handler.SessionCookieAttrs{
+		SameSite: sameSiteMode,
+		Secure:   true,
+	})
+	if cfg.Auth.Breakglass.Enabled {
+		logger.Warn("CERTCTL_BREAKGLASS_ENABLED=true — break-glass admin path is ACTIVE; this bypasses SSO. Disable in steady-state.",
+			"lockout_threshold", cfg.Auth.Breakglass.LockoutThreshold,
+			"lockout_duration", cfg.Auth.Breakglass.LockoutDuration.String())
+	}
+
 	policyService := service.NewPolicyService(policyRepo, auditService)
 	policyService.SetCertRepo(certificateRepo) // D-008: CertificateLifetime arm needs CertificateVersion.NotBefore/NotAfter
 	// G-1: RenewalPolicyService — distinct from PolicyService (compliance rules).
@@ -1206,6 +1303,11 @@ func main() {
 		// surface. 13 endpoints across login flow + session management
 		// + OIDC provider CRUD + group-mapping CRUD.
 		AuthSessionOIDC: authSessionOIDCHandler,
+
+		// AuthBreakglass — Auth Bundle 2 Phase 7.5 break-glass admin
+		// HTTP surface. 4 endpoints (1 public login + 3 admin CRUD).
+		// All endpoints return 404 when CERTCTL_BREAKGLASS_ENABLED=false.
+		AuthBreakglass: breakglassHandler,
 		// Auth — RBAC primitive (Bundle 1 Phase 4). Wires the postgres
 		// auth repos + service-layer Authorizer / RoleService /
 		// ActorRoleService / PermissionService into the HTTP surface
@@ -2594,6 +2696,28 @@ var (
 	_ = oidcdomain.OIDCProvider{}
 )
 
+// =============================================================================
+// breakglassSessionMinterAdapter — bridge from *session.Service to
+// breakglass.SessionMinter.
+//
+// The break-glass service's SessionMinter port (Phase 7.5) returns
+// (cookie, csrf, err); the underlying *session.Service.Create returns
+// *CreateResult. This adapter unwraps the result. Lives in cmd/server
+// so the breakglass package doesn't have to know about session.Service.
+// =============================================================================
+
+type breakglassSessionMinterAdapter struct {
+	svc *session.Service
+}
+
+func (a breakglassSessionMinterAdapter) Create(ctx context.Context, actorID, actorType, ip, userAgent string) (string, string, error) {
+	res, err := a.svc.Create(ctx, actorID, actorType, ip, userAgent)
+	if err != nil {
+		return "", "", err
+	}
+	return res.CookieValue, res.CSRFToken, nil
+}
+
 // oidcProvidersListAdapter bridges the postgres OIDCProviderRepository
 // to handler.OIDCProvidersListResolver. The handler returns
 // []*OIDCProviderInfo (id + display_name + login_url) for the public-