auth-bundle-1 Phase 6-7-8: bootstrap path + scope-down CLI + auditor-role split

# Phase 6 — day-0 admin bootstrap

* internal/auth/bootstrap/ (new package): Strategy interface +
  EnvTokenStrategy with constant-time compare, one-shot consumption
  via sync.Mutex, optional admin-existence probe. Bundle 2's OIDC-
  first-admin will plug in alongside as an alternate Strategy.
* BootstrapService.ValidateAndMint: validates the operator's
  CERTCTL_BOOTSTRAP_TOKEN, mints a 32-byte (64-hex-char) random API
  key value, persists the SHA-256 hash to api_keys, grants r-admin
  via actor_roles, AddHashed's the runtime keystore so the just-
  minted key authenticates the next request without restart, and
  records bootstrap.consume to the audit trail with category=auth.
* internal/auth/keystore.go (new): KeyStore interface +
  StaticKeyStore (immutable env-var-only path) + MutableKeyStore
  (env-var keys + DB-loaded api_keys + runtime AddHashed). The auth
  middleware now consumes a KeyStore so the bootstrap path can
  extend the lookup table at runtime.
* migrations/000031_api_keys.up/down.sql: api_keys table with
  (id, name UNIQUE, key_hash UNIQUE, tenant_id, admin, created_by,
  created_at, expires_at, last_used_at). Idempotent.
* /v1/auth/bootstrap GET (probe) + POST (mint) — auth-exempt. Both
  routes documented in api/openapi.yaml + AuthExemptRouterRoutes
  allowlist updated. The token never leaves internal/auth/bootstrap;
  the minted plaintext key flows only into the HTTP response body.
* Startup warning emitted when CERTCTL_BOOTSTRAP_TOKEN is set AND
  admin actors already exist (config drift signal).
* Tests: 4 strategy invariants (empty token born disabled, wrong
  token=ErrInvalidToken without consumption, one-shot consumption,
  admin-exists closes path), 5 service tests (happy path + actor-
  name validation + propagation of strategy errors + nil-deps
  guard + 32-byte entropy budget), 8 HTTP-handler tests (status
  201/410/401/400 mapping + token-leak hygiene scan of slog +
  audit details + Location header). Token-leak test redirects
  slog.Default to a buffer for the test scope.

# Phase 7 — API-key migration + scope-down CLI

* GET /v1/auth/keys handler + service method ListKeys backed by
  ActorRoleRepository.ListDistinctActors. Returns one row per
  (actor_id, actor_type) pair with the slice of role IDs they hold.
  Permission: auth.role.list.
* internal/cli/auth_scope_down.go: AuthListKeys, AuthScopeDown
  (interactive), AuthScopeDownNonInteractive (JSON config),
  AuthScopeDownSuggest (--suggest with optional --apply). The
  synthetic actor-demo-anon is filtered out of every interactive /
  bulk path; non-interactive flow logs and skips it explicitly.
* SuggestRoleFromAuditEvents (pure function): walks 30 days of
  audit events per actor and returns the narrowest matching role
  (admin / mcp / viewer / agent / operator) plus a one-line reason.
  Classification: any admin-shaped action wins; otherwise all-MCP
  → mcp; all-read-only → viewer; all-agent-shaped → agent;
  otherwise operator. Test table pins all six classifications.
* CLI subcommand tree extended: 'auth keys list' + 'auth keys
  scope-down [--non-interactive <cfg>] [--suggest [--apply]]'.
* CHANGELOG.md leads v2.1.0 with the SECURITY: AUDIT YOUR API KEYS
  call-out + four flow examples.

# Phase 8 — auditor role + event_category column

* migrations/000032_audit_category.up/down.sql: ALTER TABLE
  audit_events ADD COLUMN event_category TEXT NOT NULL DEFAULT
  'cert_lifecycle' + CHECK constraint (cert_lifecycle/auth/config)
  + (event_category) and (event_category, timestamp DESC) indexes
  for the auditor-filter query path. WORM trigger from migration
  000018 continues to enforce append-only at the DB layer (DDL is
  not blocked).
* domain.AuditEvent gains EventCategory string (omitempty);
  domain.EventCategoryCertLifecycle / Auth / Config constants.
* AuditService.RecordEventWithCategory sibling of RecordEvent;
  legacy callers stay on RecordEvent (defaults to cert_lifecycle).
  Auth callers (RoleService, ActorRoleService, BootstrapService)
  switched to RecordEventWithCategory(..., 'auth', ...).
* GET /v1/audit?category=<cat>: handler accepts the optional query
  param, validates against the enum (400 on invalid value),
  dispatches through ListAuditEventsByCategory. OpenAPI updated
  with the new query param + AuditEvent.event_category schema.
* Postgres AuditRepository.Create now writes event_category;
  AuditRepository.List filters on it; AuditFilter.EventCategory
  gates the WHERE clause.
* Tests: 5 audit-category-filter HTTP tests (dispatch routing,
  back-compat fallback, 400 for invalid values, all 3 enum values
  accepted, page+category combine, JSON output surfaces the
  field). 3 auditor-role invariants (auditor holds exactly
  audit.read+audit.export, no mutating perms, disjoint from
  viewer except audit.read).

# Cross-phase wiring

* HandlerRegistry.Bootstrap field added; cmd/server/main.go wires
  the bootstrap service ahead of RegisterHandlers (extracted
  assembleNamedAPIKeys helper into auth_backfill.go, moved the
  keystore + bootstrap construction up alongside the auth repos).
* AuthCheckResolver / AuthActorRoleService extended with ListKeys
  to satisfy the Phase 7 surface; existing fakes updated.
* fakeAudit + mockAuditService stubs in tests gain
  RecordEventWithCategory + ListAuditEventsByCategory; existing
  tests untouched.

# Verifications

* gofmt -l: clean across every modified file.
* go vet ./...: clean.
* staticcheck across internal/auth + handler + router + cli +
  service + repository + cmd + domain: clean.
* go test -short -count=1: green across every Bundle-1-touched
  package — internal/auth (incl. bootstrap), internal/api/handler,
  internal/api/router, internal/cli, internal/service/auth,
  internal/service, internal/domain/auth, internal/repository/postgres,
  cmd/server, cmd/cli, plus internal/scheduler, internal/api/middleware,
  cmd/agent, internal/mcp.

internal/domain/audit.go

@@ -15,8 +15,36 @@ type AuditEvent struct {
 	ResourceID   string          `json:"resource_id"`
 	Details      json.RawMessage `json:"details"`
 	Timestamp    time.Time       `json:"timestamp"`
+
+	// EventCategory (Bundle 1 Phase 8) classifies the event into one
+	// of "cert_lifecycle", "auth", or "config" so the auditor role
+	// can filter to authentication / authorization events without
+	// also seeing every cert.issue. The persistence layer treats an
+	// empty value as "cert_lifecycle" (the migration default + the
+	// DB CHECK constraint).
+	EventCategory string `json:"event_category,omitempty"`
 }
 
+// Audit event-category constants. Bundle 1 Phase 8 ships exactly
+// three; future bundles extend the enum (and the migration's CHECK
+// constraint) without reshaping the column.
+const (
+	// EventCategoryCertLifecycle is the default for cert.* /
+	// agent.* / deployment.* / verification.* events.
+	EventCategoryCertLifecycle = "cert_lifecycle"
+
+	// EventCategoryAuth covers every auth.role.* / auth.key.* /
+	// auth.bootstrap.* event plus the bootstrap.consume action
+	// recorded by Phase 6. Auditors filter to this category to
+	// review who minted / granted / revoked roles.
+	EventCategoryAuth = "auth"
+
+	// EventCategoryConfig covers issuer / target / settings
+	// mutations. Distinct from cert_lifecycle so a regulator can
+	// review configuration changes separately from cert ops.
+	EventCategoryConfig = "config"
+)
+
 // ActorType represents the entity performing an action.
 type ActorType string
 

internal/domain/auth/apikey.go

@@ -0,0 +1,24 @@
+package auth
+
+import "time"
+
+// APIKey is the runtime-minted operator API key (Bundle 1 Phase 6).
+// Stored in the `api_keys` table with the SHA-256 hash of the key
+// value; the plaintext is returned to the operator on creation and
+// never persisted. Name is the canonical actor identity that joins
+// against actor_roles.actor_id. The Admin flag is a denormalized hint
+// replicated from the actor's standing role grant so the auth
+// middleware can populate the legacy AdminKey context without joining
+// actor_roles on every request; the actor_roles row remains the
+// source of truth for authorization.
+type APIKey struct {
+	ID         string     `json:"id"` // prefix `ak-`
+	Name       string     `json:"name"`
+	KeyHash    string     `json:"-"` // never serialized
+	TenantID   string     `json:"tenant_id"`
+	Admin      bool       `json:"admin"`
+	CreatedBy  string     `json:"created_by"`
+	CreatedAt  time.Time  `json:"created_at"`
+	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
+	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
+}

internal/domain/auth/auditor_test.go

@@ -0,0 +1,83 @@
+package auth
+
+import "testing"
+
+// =============================================================================
+// Bundle 1 Phase 8 — auditor role invariants. Pin the seeded permission
+// set so a future refactor that accidentally widens it gets caught.
+// =============================================================================
+
+// TestAuditorRoleHoldsExactlyAuditReadAndExport pins the load-bearing
+// invariant that the auditor role has read-only audit access AND
+// nothing else. Any drift here breaks the SOC 2 / FedRAMP separation
+// the prompt requires.
+func TestAuditorRoleHoldsExactlyAuditReadAndExport(t *testing.T) {
+	got, ok := DefaultRoles[RoleIDAuditor]
+	if !ok {
+		t.Fatalf("auditor role missing from DefaultRoles")
+	}
+	want := map[string]bool{
+		"audit.read":   true,
+		"audit.export": true,
+	}
+	if len(got) != len(want) {
+		t.Errorf("auditor permission count = %d, want %d (auditor role widened?)", len(got), len(want))
+	}
+	for _, p := range got {
+		if !want[p] {
+			t.Errorf("auditor holds %q but should not — auditor must be read-only", p)
+		}
+	}
+	for w := range want {
+		found := false
+		for _, p := range got {
+			if p == w {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("auditor role missing %q", w)
+		}
+	}
+}
+
+// TestAuditorRoleDoesNotHoldMutatingOrReadingNonAuditPerms pins that
+// the auditor role grants ZERO mutating perms (cert.*, profile.*,
+// issuer.*, target.*, agent.*) AND zero non-audit read perms. The
+// auditor is "audit-only", not "read-only across everything".
+func TestAuditorRoleDoesNotHoldMutatingOrReadingNonAuditPerms(t *testing.T) {
+	got := DefaultRoles[RoleIDAuditor]
+	for _, p := range got {
+		switch p {
+		case "audit.read", "audit.export":
+			// allowed
+		default:
+			t.Errorf("auditor holds non-audit permission %q — should be audit-only", p)
+		}
+	}
+}
+
+// TestAuditorRoleSeparateFromViewer pins that auditor and viewer
+// permission sets are disjoint EXCEPT for nothing — viewer gets
+// resource-read perms (cert/profile/issuer/target/agent) which auditor
+// must NOT inherit. Closes the "auditor sees customer cert data" leg.
+func TestAuditorRoleSeparateFromViewer(t *testing.T) {
+	auditorSet := map[string]bool{}
+	for _, p := range DefaultRoles[RoleIDAuditor] {
+		auditorSet[p] = true
+	}
+	viewerSet := map[string]bool{}
+	for _, p := range DefaultRoles[RoleIDViewer] {
+		viewerSet[p] = true
+	}
+	for v := range viewerSet {
+		if v == "audit.read" {
+			// shared by design (viewer can read audit)
+			continue
+		}
+		if auditorSet[v] {
+			t.Errorf("auditor inherits viewer permission %q — must be disjoint except audit.read", v)
+		}
+	}
+}