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/repository/breakglass.go

@@ -0,0 +1,62 @@
+package repository
+
+import (
+	"context"
+	"errors"
+
+	bgdomain "github.com/certctl-io/certctl/internal/auth/breakglass/domain"
+)
+
+// Sentinel errors for the BreakglassCredentialRepository. Postgres
+// implementation translates SQLSTATE codes into these so handler /
+// service code can branch via errors.Is.
+var (
+	// ErrBreakglassNotFound: GetByActor / Get found no row. The
+	// service-layer Authenticate path treats this as "wrong password"
+	// at the wire (uniform 401, identical timing) so the existence of
+	// a break-glass credential for a given actor cannot be probed.
+	ErrBreakglassNotFound = errors.New("breakglass: credential not found")
+
+	// ErrBreakglassDuplicate: Create tripped the (actor_id) UNIQUE
+	// constraint. SetPassword should use Upsert semantics; if a caller
+	// invokes Create on an actor that already has a row, this surfaces
+	// as a 409.
+	ErrBreakglassDuplicate = errors.New("breakglass: credential already exists for actor")
+)
+
+// BreakglassCredentialRepository wraps the breakglass_credentials
+// table. Auth Bundle 2 Phase 7.5 — see internal/auth/breakglass/service.go
+// for the consumer.
+type BreakglassCredentialRepository interface {
+	// Create persists a new credential row. Caller MUST have called
+	// c.Validate() and computed the Argon2id PHC-format password hash.
+	// Returns ErrBreakglassDuplicate when (actor_id) UNIQUE fires.
+	Create(ctx context.Context, c *bgdomain.BreakglassCredential) error
+
+	// GetByActor returns the credential for the named actor. Returns
+	// ErrBreakglassNotFound on miss.
+	GetByActor(ctx context.Context, actorID, tenantID string) (*bgdomain.BreakglassCredential, error)
+
+	// UpdatePasswordHash rotates the password hash + bumps
+	// last_password_change_at. Resets failure_count + clears
+	// locked_until (a fresh password starts unlocked).
+	UpdatePasswordHash(ctx context.Context, actorID, tenantID, newHash string) error
+
+	// IncrementFailure increments failure_count + sets last_failure_at;
+	// when the new count crosses the threshold, sets locked_until.
+	// Returns the updated row so the service can see the post-update
+	// failure_count + locked_until without a re-read. Atomic single-
+	// statement UPDATE so concurrent failed attempts can't race past
+	// the threshold.
+	IncrementFailure(ctx context.Context, actorID, tenantID string, threshold int, lockoutDurationSec int) (*bgdomain.BreakglassCredential, error)
+
+	// ResetFailureCount clears failure_count + locked_until. Used on
+	// successful Authenticate AND on admin-initiated Unlock.
+	ResetFailureCount(ctx context.Context, actorID, tenantID string) error
+
+	// Delete removes a credential row. Returns ErrBreakglassNotFound
+	// on miss. Active sessions for the actor are NOT auto-revoked
+	// (separate concern; the operator can call SessionService.RevokeAll
+	// in lockstep).
+	Delete(ctx context.Context, actorID, tenantID string) error
+}

internal/repository/postgres/breakglass.go

@@ -0,0 +1,166 @@
+package postgres
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+
+	"github.com/lib/pq"
+
+	bgdomain "github.com/certctl-io/certctl/internal/auth/breakglass/domain"
+	"github.com/certctl-io/certctl/internal/repository"
+)
+
+// BreakglassCredentialRepository is the postgres implementation of
+// repository.BreakglassCredentialRepository. Auth Bundle 2 Phase 7.5.
+type BreakglassCredentialRepository struct {
+	db *sql.DB
+}
+
+// NewBreakglassCredentialRepository constructs a
+// BreakglassCredentialRepository.
+func NewBreakglassCredentialRepository(db *sql.DB) *BreakglassCredentialRepository {
+	return &BreakglassCredentialRepository{db: db}
+}
+
+const breakglassColumns = `id, tenant_id, actor_id, password_hash,
+		created_at, last_password_change_at, failure_count, locked_until,
+		last_failure_at`
+
+func scanBreakglass(row interface{ Scan(...interface{}) error }) (*bgdomain.BreakglassCredential, error) {
+	var c bgdomain.BreakglassCredential
+	var lockedUntil, lastFailureAt sql.NullTime
+	if err := row.Scan(
+		&c.ID, &c.TenantID, &c.ActorID, &c.PasswordHash,
+		&c.CreatedAt, &c.LastPasswordChangeAt, &c.FailureCount,
+		&lockedUntil, &lastFailureAt,
+	); err != nil {
+		return nil, err
+	}
+	if lockedUntil.Valid {
+		c.LockedUntil = &lockedUntil.Time
+	}
+	if lastFailureAt.Valid {
+		c.LastFailureAt = &lastFailureAt.Time
+	}
+	return &c, nil
+}
+
+// Create persists a new credential row.
+func (r *BreakglassCredentialRepository) Create(ctx context.Context, c *bgdomain.BreakglassCredential) error {
+	_, err := r.db.ExecContext(ctx, `
+		INSERT INTO breakglass_credentials (
+			id, tenant_id, actor_id, password_hash
+		) VALUES ($1,$2,$3,$4)`,
+		c.ID, c.TenantID, c.ActorID, c.PasswordHash)
+	if err != nil {
+		var pqErr *pq.Error
+		if errors.As(err, &pqErr) && pqErr.Code == "23505" {
+			return repository.ErrBreakglassDuplicate
+		}
+		return fmt.Errorf("breakglass create: %w", err)
+	}
+	return nil
+}
+
+// GetByActor returns the credential for the named actor.
+func (r *BreakglassCredentialRepository) GetByActor(ctx context.Context, actorID, tenantID string) (*bgdomain.BreakglassCredential, error) {
+	row := r.db.QueryRowContext(ctx,
+		`SELECT `+breakglassColumns+` FROM breakglass_credentials WHERE actor_id = $1 AND tenant_id = $2`,
+		actorID, tenantID)
+	c, err := scanBreakglass(row)
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, repository.ErrBreakglassNotFound
+		}
+		return nil, fmt.Errorf("breakglass get_by_actor: %w", err)
+	}
+	return c, nil
+}
+
+// UpdatePasswordHash rotates the password hash. Idempotent reset of
+// failure_count + locked_until (a fresh password starts unlocked).
+func (r *BreakglassCredentialRepository) UpdatePasswordHash(ctx context.Context, actorID, tenantID, newHash string) error {
+	res, err := r.db.ExecContext(ctx, `
+		UPDATE breakglass_credentials
+		SET password_hash = $3,
+		    last_password_change_at = NOW(),
+		    failure_count = 0,
+		    locked_until = NULL,
+		    last_failure_at = NULL
+		WHERE actor_id = $1 AND tenant_id = $2`,
+		actorID, tenantID, newHash)
+	if err != nil {
+		return fmt.Errorf("breakglass update_password_hash: %w", err)
+	}
+	n, _ := res.RowsAffected()
+	if n == 0 {
+		return repository.ErrBreakglassNotFound
+	}
+	return nil
+}
+
+// IncrementFailure atomically bumps failure_count + sets last_failure_at;
+// when the new count >= threshold, sets locked_until = NOW() + duration.
+// The whole transition is one UPDATE so concurrent racing wrong-password
+// attempts can't observe an intermediate state.
+//
+// Returns the post-update row so the service can decide whether to
+// surface ErrBreakglassLocked without a re-read.
+func (r *BreakglassCredentialRepository) IncrementFailure(ctx context.Context, actorID, tenantID string, threshold int, lockoutDurationSec int) (*bgdomain.BreakglassCredential, error) {
+	row := r.db.QueryRowContext(ctx, `
+		UPDATE breakglass_credentials
+		SET failure_count = failure_count + 1,
+		    last_failure_at = NOW(),
+		    locked_until = CASE
+		        WHEN failure_count + 1 >= $3 THEN NOW() + ($4 || ' seconds')::interval
+		        ELSE locked_until
+		    END
+		WHERE actor_id = $1 AND tenant_id = $2
+		RETURNING `+breakglassColumns,
+		actorID, tenantID, threshold, lockoutDurationSec)
+	c, err := scanBreakglass(row)
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, repository.ErrBreakglassNotFound
+		}
+		return nil, fmt.Errorf("breakglass increment_failure: %w", err)
+	}
+	return c, nil
+}
+
+// ResetFailureCount clears failure_count + locked_until. Used on
+// successful Authenticate AND on admin-initiated Unlock. Idempotent.
+func (r *BreakglassCredentialRepository) ResetFailureCount(ctx context.Context, actorID, tenantID string) error {
+	res, err := r.db.ExecContext(ctx, `
+		UPDATE breakglass_credentials
+		SET failure_count = 0,
+		    locked_until = NULL,
+		    last_failure_at = NULL
+		WHERE actor_id = $1 AND tenant_id = $2`,
+		actorID, tenantID)
+	if err != nil {
+		return fmt.Errorf("breakglass reset_failure_count: %w", err)
+	}
+	n, _ := res.RowsAffected()
+	if n == 0 {
+		return repository.ErrBreakglassNotFound
+	}
+	return nil
+}
+
+// Delete removes a credential row.
+func (r *BreakglassCredentialRepository) Delete(ctx context.Context, actorID, tenantID string) error {
+	res, err := r.db.ExecContext(ctx,
+		`DELETE FROM breakglass_credentials WHERE actor_id = $1 AND tenant_id = $2`,
+		actorID, tenantID)
+	if err != nil {
+		return fmt.Errorf("breakglass delete: %w", err)
+	}
+	n, _ := res.RowsAffected()
+	if n == 0 {
+		return repository.ErrBreakglassNotFound
+	}
+	return nil
+}