auth-bundle-1 Phase 13: docs (rbac.md + threat model + migration guide + security.md update)

Closes the last Phase before the Bundle 1 Exit gate. Operators now have authoritative reference + threat model + migration guide covering every behavior change Bundles 0-12 introduced. # New docs * docs/operator/rbac.md (340 lines) — operator how-to: - Mental model (actors / roles / permissions / scopes) - 7 default roles seeded by migration 000029 + the 5 admin-only fine-grained perms seeded by 000030 - Permission catalogue table by namespace - Scope semantics (global beats specific) + the Bundle-2 deferral on scope_id FK enforcement - Granting / revoking access from GUI + CLI + HTTP API + MCP - The auditor pattern (audit-only, no resource read) - Day-0 bootstrap flow (CERTCTL_BOOTSTRAP_TOKEN → curl → HTTP 410 thereafter) - Demo-mode (CERTCTL_AUTH_TYPE=none) caveat for production * docs/operator/auth-threat-model.md (180 lines) — what the controls defend against: - 5 threat actors (external, wrong-role, compromised key, insider operator, compromised auditor) - Per-defense walk-through (API-key auth, RBAC, bootstrap, approval workflow + Phase 9 closure, audit trail, protocol-endpoint allowlist) - 9 explicit deferrals (OIDC, sessions, local accounts, JIT elevation, MFA, etc.) — Bundle 2 / future scope - Compliance mapping (SOC 2 CC6.1/CC6.3, HIPAA §164.312(b), NIST SSDF PO.5.2, FedRAMP AU-9, PCI-DSS §10) - 5 operator-runnable sanity checks (e.g., 'SELECT FROM audit_events WHERE actor=system-bypass' MUST return 0 in production) * docs/migration/api-keys-to-rbac.md (200 lines) — v2.0.x → v2.1.0 upgrade flow: - The SECURITY: AUDIT YOUR API KEYS callout - Migration list (000029-000033) + what each does - 4-mode scope-down flow (interactive / non-interactive JSON / --suggest / --suggest --apply) - What changes for code that called auth.IsAdmin - Helm-specific upgrade flow with example post-upgrade Job - Docker Compose upgrade flow + the 5 examples folders that ride demo mode unchanged - Verification queries + rollback flow # Updated docs * docs/operator/security.md — Last-reviewed bumped to 2026-05-09; existing Authentication-surface section extended to call out the Bundle 1 RBAC primitive, day-0 bootstrap path, and approval-bypass closure with cross-references to the new docs. * docs/reference/profiles.md — Last-reviewed header formatting fixed (added the > blockquote prefix used consistently across the docs tree). # docs/README.md navigation * Operator section gains 2 new rows (RBAC + auth-threat-model) and Approval-workflow row updated to mention Phase 9 closure. * Reference section gains the Profiles row. * Migration section gains the api-keys-to-rbac row with the AUDIT YOUR API KEYS callout in the link description. # CHANGELOG.md v2.1.0 section refreshed The Phase 7 commit landed the SECURITY: AUDIT YOUR API KEYS callout. This commit appends the missing Phase 9-12 highlights: - Approval-bypass closure (profile-edit gate + flip-flop loophole + ErrApproveBySameActor invariant) - GUI: Roles / API Keys / Auth Settings / Approvals queue - 12 new MCP RBAC tools - Coverage gates on internal/auth + internal/service/auth - Protocol-endpoint allowlist pinned at 3 layers Trailing cross-reference block now points at all 4 new docs. # Verifications * Every internal link in the 4 new/modified docs validated by shell sweep (find broken links → 0 hits). * Every new doc carries 'Last reviewed: 2026-05-09' header with the > blockquote prefix matching the docs-tree convention. * go vet ./... clean. * staticcheck across every Bundle-1-touched Go package clean. * gofmt -l clean repo-wide. * go test -short -count=1 green across internal/auth (incl. bootstrap), internal/api/handler, internal/api/router, internal/cli, internal/service (incl. auth), internal/domain/auth, internal/mcp, cmd/cli (cmd/server has 1 environmental failure on the sandbox virtiofs-tmp: TestPreflightSCEPRACertKey_KeyWorldReadable_Refuses depends on tmpfs file-mode semantics that virtiofs propagates differently — pre-existing, unrelated to Bundle 1). * Frontend: 19 Vitest tests across src/pages/auth/ + AuditPage all pass; tsc --noEmit clean.
2026-06-07 16:21:30 +00:00 · 2026-05-10 00:10:15 +00:00
parent 06cea1ce0f
commit e7a94b6080
7 changed files with 913 additions and 9 deletions
@@ -54,13 +54,48 @@ What else changed in v2.1.0:
 - **`/v1/auth/check` enrichment.** Response now includes the actor's
  standing roles and effective permissions, so the GUI gates
  affordances from a single fetch on app boot.
 - **Approval-bypass closure.** Edits to a profile that has (or
  would have) `RequiresApproval=true` now route through the
  `ApprovalService` two-person integrity gate (Phase 9). Migration
  000033 adds `approval_kind` + `payload` to
  `issuance_approval_requests` so cert-issuance and profile-edit
  approvals share the same workflow. Same-actor self-approve is
  rejected with `ErrApproveBySameActor` for both kinds. Closes the
  flip-flop loophole where an admin could disable approval, mutate,
  re-enable. Documented at
  [`docs/reference/profiles.md`](docs/reference/profiles.md).
 - **GUI: Roles / API Keys / Auth Settings / Approvals queue.**
  Four new pages under `/auth/*` consume `/v1/auth/me` for
  permission-aware rendering. The Approvals queue blocks
  self-approve at the client layer (Approve/Reject buttons hidden
  when requested_by == current actor_id) on top of the server-side
  enforcement. AuditPage gains a category filter (cert_lifecycle /
  auth / config) for the auditor view.
 - **MCP server gains 12 RBAC tools.** Operators driving certctl
  from Claude / VS Code / any MCP client get parity with the GUI
  + CLI. Each tool routes through the same HTTP handler; permission
  gates fire server-side.
 - **OpenAPI catalogues every new route.** Every Bundle 1 endpoint
  ships with an `operationId`; the parity test guards against drift.
 - **Coverage gates.** `internal/auth/` and `internal/service/auth/`
  now have ≥85% coverage floors in `.github/coverage-thresholds.yml`.
  The 12-path negative-test list from the Bundle 1 prompt is
  fully covered (path #12 deferred with in-tree TODO).
 - **Protocol-endpoint allowlist pinned at three layers.** The
  middleware bypass (`auth.IsProtocolEndpoint`), the router-level
  `AuthExemptRouterRoutes` constant, and a new
  `phase12_protocol_allowlist_test.go` AST scan all guard against
  accidentally wrapping ACME / SCEP / EST / OCSP / CRL routes in
  `rbacGate`.
 - **Bundle 2 (OIDC + sessions) starts after Bundle 1 lands on
  master.** Roadmap entry remains in `cowork/auth-bundle-2-prompt.md`.
 Migration ordering, idempotency, and downgrade are documented in
-`docs/migration/api-keys-to-rbac.md`.
+[`docs/migration/api-keys-to-rbac.md`](docs/migration/api-keys-to-rbac.md).
 The threat model + compliance mapping live at
 [`docs/operator/auth-threat-model.md`](docs/operator/auth-threat-model.md).
 Day-2 RBAC operations live at
 [`docs/operator/rbac.md`](docs/operator/rbac.md).
 ## v2.0.68 — Image registry path changed ⚠️
@@ -27,6 +27,7 @@ You're operating certctl in production or building integrations and need authori
 | Doc | What it covers |
 |---|---|
 | [Architecture](reference/architecture.md) | System design, data flow, security model, deployment topologies |
 | [Profiles](reference/profiles.md) | CertificateProfile policy object — issuer wiring, EKUs, RequiresApproval gate (Phase 9 closure) |
 | [API](reference/api.md) | OpenAPI 3.1 spec, integration patterns, client SDK generation |
 | [CLI](reference/cli.md) | certctl-cli command reference and CI/CD integration patterns |
 | [Configuration](reference/configuration.md) | `CERTCTL_*` environment variable reference (scheduler, rate limits, deploy verify, audit, agent) |
@@ -62,10 +63,12 @@ You're running certctl in production and need operational guidance.
 | Doc | What it covers |
 |---|---|
-| [Security posture](operator/security.md) | Auth, rate limits, encryption at rest, key rotation |
+| [Security posture](operator/security.md) | Auth, rate limits, encryption at rest, key rotation, RBAC primitive (Bundle 1), bootstrap |
 | [RBAC operator reference](operator/rbac.md) | Roles, permissions, scopes, scope-down + bootstrap flow (Bundle 1) |
 | [Auth threat model](operator/auth-threat-model.md) | API-key compromise, role-grant abuse, bootstrap-token leak, audit-mutation, compliance mapping (Bundle 1) |
 | [Control plane TLS](operator/tls.md) | Self-signed bootstrap, operator-supplied Secret, cert-manager Certificate CR |
 | [Database TLS](operator/database-tls.md) | PostgreSQL transport encryption |
-| [Approval workflow](operator/approval-workflow.md) | Two-person integrity gate for high-stakes issuance |
+| [Approval workflow](operator/approval-workflow.md) | Two-person integrity gate for high-stakes issuance + Phase 9 profile-edit closure |
 | [Helm deployment](operator/helm-deployment.md) | Kubernetes installation via the bundled chart |
 | [Performance baselines](operator/performance-baselines.md) | Operator-runnable benchmarks for regression spot checks |
 | [Legacy clients (TLS 1.2)](operator/legacy-clients-tls-1.2.md) | Reverse-proxy runbook for embedded EST/SCEP clients on TLS 1.2 |
@@ -90,6 +93,7 @@ You're moving from another cert-management tool to certctl, or running both in p
 | Caddy ACME (point Caddy at certctl) | [migration/acme-from-caddy.md](migration/acme-from-caddy.md) |
 | cert-manager ACME (point cert-manager at certctl) | [migration/acme-from-cert-manager.md](migration/acme-from-cert-manager.md) |
 | Traefik ACME (point Traefik at certctl) | [migration/acme-from-traefik.md](migration/acme-from-traefik.md) |
 | **API keys → RBAC (v2.0.x → v2.1.0)** | [migration/api-keys-to-rbac.md](migration/api-keys-to-rbac.md) — **AUDIT YOUR API KEYS** post-upgrade |
 ## Contributor
@@ -0,0 +1,296 @@
 # Migrating API keys to RBAC (v2.0.x → v2.1.0)
 > Last reviewed: 2026-05-09
 This is the upgrade guide for an existing certctl deployment moving
 from v2.0.x's "every API key is admin or not" model to v2.1.0's
 RBAC primitive. Everything keeps working through the upgrade — the
 Bundle 1 migration backfills every existing API key to the
 `r-admin` role on first boot, so the pre-existing automation that
 was using those keys does not change behavior. **However**, most
 keys do not need full admin power; this guide walks the operator
 through the post-upgrade scope-down flow.
 ## ⚠️ SECURITY: AUDIT YOUR API KEYS
 Bundle 1 maps **every** existing `CERTCTL_API_KEYS_NAMED` entry
 (and every legacy `CERTCTL_AUTH_SECRET`-synthesized key) to the
 `r-admin` role on the first boot after migration 000029 applies.
 This is the safe-for-back-compat default — your CI / agents / scripts
 keep working without changes — but if you don't downgrade keys, every
 key in your fleet has full admin permissions including bulk-revoke,
 CRL admin, and CA hierarchy management.
 **Run the scope-down flow before tagging the next release.** The
 release notes for v2.1.0 lead with this callout for a reason.
 ## Upgrade flow
 ### 1. Apply the migration
 The migration runner is idempotent. Re-applying is a no-op if the
 schema is already at the target version. The Bundle 1 migrations
 that ship with v2.1.0:
 | Migration | What it does |
 |---|---|
 | `000029_rbac.up.sql` | Creates `tenants`, `roles`, `permissions`, `role_permissions`, `actor_roles`. Seeds 7 default roles + 33-permission catalogue + the synthetic `actor-demo-anon` admin grant. Backfills every named API key into `actor_roles` with the `r-admin` role. |
 | `000030_rbac_admin_perms.up.sql` | Seeds 5 admin-only fine-grained permissions (`cert.bulk_revoke`, `crl.admin`, `scep.admin`, `est.admin`, `ca.hierarchy.manage`) into `r-admin` only. |
 | `000031_api_keys.up.sql` | Creates the `api_keys` table for runtime-minted keys (Bundle 1 Phase 6 bootstrap). |
 | `000032_audit_category.up.sql` | Adds `event_category` column to `audit_events` with the closed enum (`cert_lifecycle` / `auth` / `config`). |
 | `000033_approval_kinds.up.sql` | Adds `approval_kind` + `payload` to `issuance_approval_requests` for the Phase 9 approval-bypass closure. |
 The Bundle 1 server applies these on first boot. No operator
 action is required other than running the upgrade.
 ### 2. Verify the backfill landed
 ```bash
 # Inspect the seeded actor_roles rows. You should see one row per
 # entry in CERTCTL_API_KEYS_NAMED (Admin=true keys → r-admin,
 # Admin=false keys → r-viewer) plus the seeded actor-demo-anon
 # admin row.
 psql -d certctl -c "SELECT actor_id, role_id, granted_by, granted_at FROM actor_roles ORDER BY granted_at;"
 ```
 If the table is empty, the boot-loader hook in
 `cmd/server/auth_backfill.go::backfillNamedKeyActorRoles` did not
 run; re-check that `CERTCTL_AUTH_TYPE` is `api-key` (the boot
 hook is gated on `cfg.Auth.Type != none`).
 ### 3. List + scope-down keys
 The `certctl-cli` ships a four-mode scope-down command. Pick the
 mode that matches your fleet size + automation posture.
 #### Interactive walk
 ```bash
 certctl-cli auth keys scope-down
 ```
 Walks every actor (skips the synthetic `actor-demo-anon`) and
 prompts for a target role. Empty input keeps the existing role.
 Type one of `admin`, `operator`, `viewer`, `agent`, `mcp`, `cli`,
 `auditor` to replace.
 #### Non-interactive JSON config (Helm post-upgrade hook)
 ```bash
 cat > scope-down.json <<EOF
 {
  "ci-bot":         "operator",
  "agent-prod-1":   "agent",
  "agent-prod-2":   "agent",
  "monitoring-bot": "viewer",
  "compliance-bot": "auditor"
 }
 EOF
 certctl-cli auth keys scope-down --non-interactive ./scope-down.json
 ```
 Empty role values revoke every current grant WITHOUT granting a
 replacement; assign roles selectively with
 `certctl-cli auth keys assign`.
 #### Audit-driven suggestion
 ```bash
 # Preview suggestions based on the last 30 days of audit history
 certctl-cli auth keys scope-down --suggest
 # Apply the suggestions
 certctl-cli auth keys scope-down --suggest --apply
 ```
 The classifier (pure function in `internal/cli/auth_scope_down.go::SuggestRoleFromAuditEvents`)
 walks the actor's audit events and emits one of:
 | Suggestion | Trigger |
 |---|---|
 | `admin` | Any auth.role.* / auth.key.* / ca.hierarchy.* / *.bulk_revoke / *.admin action |
 | `mcp` | All observed actions are MCP-shaped (`mcp.*`) |
 | `viewer` | All observed actions are read-only (`*.read` or `*.list`) |
 | `agent` | All observed actions are agent-shaped (`agent.*`, `cert.read`, `cert.issue`) |
 | `operator` | Cert / profile / target lifecycle mutations without admin signals |
 The classifier is conservative — when in doubt, it prefers the
 narrower role. The operator confirms each suggestion before any
 mutation lands (unless `--apply` is set).
 ### 4. Mint a fresh admin via bootstrap (optional, for fresh deployments)
 If you're standing up a fresh deployment instead of upgrading an
 existing one, the bootstrap path mints the first admin key without
 needing the operator to know the env-var format:
 ```bash
 # Set the bootstrap token in the server environment.
 export CERTCTL_BOOTSTRAP_TOKEN=$(openssl rand -hex 32)
 # Boot the server. Logs include "bootstrap endpoint enabled".
 docker compose up -d
 # Mint the first admin key.
 curl -X POST $URL/api/v1/auth/bootstrap \
  -H 'Content-Type: application/json' \
  -d '{"token":"'$CERTCTL_BOOTSTRAP_TOKEN'","actor_name":"first-admin"}'
 ```
 The response carries the plaintext `key_value` once. Capture it
 and use it as the Bearer token for subsequent calls. Subsequent
 bootstrap calls return HTTP 410 Gone.
 See [`docs/operator/rbac.md`](../operator/rbac.md) for the full
 bootstrap flow + the threat model.
 ## What changes for code that called `IsAdmin`
 Pre-Bundle-1, the five admin handlers checked `auth.IsAdmin(ctx)`
 directly in the body. Bundle 1 Phase 3.5 moved those checks to
 the router via the `auth.RequirePermission` middleware (wrapped
 through the `rbacGate` helper in
 `internal/api/router/router.go`). The behavior contract is
 unchanged: `r-admin`-roled callers reach the handler, anyone else
 gets HTTP 403 BEFORE the body runs.
 If your code consumed `auth.IsAdmin` directly (it shouldn't —
 the helper is internal), the new convention is:
 1. Wrap the route in `rbacGate(reg.Checker, "<perm>", handler)`
   in `router.go`.
 2. Add the perm to `migrations/000030_rbac_admin_perms.up.sql`
   (or `migrations/000029_rbac.up.sql`'s catalogue).
 3. Grant the perm to the right default roles.
 The five admin-only fine-grained perms shipped in Phase 3.5 stay
 on `r-admin` only by default. Operators delegate by creating
 custom roles with the specific perm.
 ## Helm-specific upgrade
 The certctl Helm chart applies migrations on container start via
 the standard migrations runner. No chart changes are required;
 the `helm upgrade` command runs identically:
 ```bash
 helm upgrade certctl certctl/certctl \
  --version <new-version> \
  --reuse-values
 ```
 Post-upgrade, the boot loader runs the named-key actor-role
 backfill against the `CERTCTL_API_KEYS_NAMED` env-var-injected
 into the deployment. The "AUDIT YOUR API KEYS" callout applies —
 add a post-upgrade Job to your release pipeline that runs
 `certctl-cli auth keys scope-down --non-interactive` against a
 checked-in JSON config, so the role narrowing is deterministic
 across upgrade rollouts.
 Example post-upgrade Job:
 ```yaml
 apiVersion: batch/v1
 kind: Job
 metadata:
  name: certctl-scope-down
 spec:
  template:
    spec:
      containers:
      - name: scope-down
        image: ghcr.io/certctl-io/certctl-cli:<tag>
        command:
          - certctl-cli
          - auth
          - keys
          - scope-down
          - --non-interactive
          - /config/scope-down.json
        envFrom:
          - secretRef:
              name: certctl-cli-credentials
        volumeMounts:
          - name: scope-down-config
            mountPath: /config
      volumes:
        - name: scope-down-config
          configMap:
            name: certctl-scope-down-config
      restartPolicy: OnFailure
 ```
 The ConfigMap holds the `{actor_id: role_id}` map; the Secret
 holds the API key the Job uses to call `/v1/auth/keys/.../roles`.
 ## Docker Compose-specific upgrade
 For `deploy/docker-compose.yml` deployments:
 1. Pull the new images: `docker compose pull`
 2. Verify your `CERTCTL_AUTH_TYPE` value before restarting. If it
   was `none` (the demo path), the post-upgrade server will boot
   in demo mode again — the synthetic `actor-demo-anon` admin
   covers every request, no scope-down is meaningful. If you're
   moving from `none` to `api-key` mode, set
   `CERTCTL_API_KEYS_NAMED` first, then restart.
 3. `docker compose up -d` to apply.
 4. `docker compose logs certctl-server | grep -i 'loaded persisted api_keys'`
   to verify the boot loader ran. The first-boot log line includes
   the count of keys loaded into the runtime keystore.
 5. Run `certctl-cli auth keys scope-down` against the running
   server.
 The five examples in `examples/` (acme-nginx, private-ca-traefik,
 step-ca-haproxy, multi-issuer, acme-wildcard-dns01) all run in
 demo mode (`CERTCTL_AUTH_TYPE=none`) and are unaffected by the
 RBAC migration — the synthetic actor-demo-anon admin grant covers
 every request.
 ## Verifying the upgrade landed
 After the scope-down flow completes:
 1. `certctl-cli auth me` while authenticated as each named key
   confirms the right `effective_permissions` for that role.
 2. `psql -c "SELECT actor_id, array_agg(role_id ORDER BY role_id) FROM actor_roles GROUP BY actor_id;"`
   gives the full picture in one query.
 3. The audit trail
   (`GET /api/v1/audit?category=auth`)
   shows the `auth.role.assign` and `auth.role.revoke` rows for
   every change you made — confirm via the GUI's
   `/audit?category=auth` view.
 4. Read the updated [`docs/operator/rbac.md`](../operator/rbac.md)
   for day-2 RBAC management.
 ## Rollback
 If the upgrade goes wrong, the down migrations exist in lockstep:
 ```bash
 # Roll back via your migration runner (golang-migrate, Atlas, etc.).
 # Migrations 000029-000033 each have a .down.sql that reverses the
 # .up.sql. Down migrations are destructive on data added by the up
 # migration (api_keys rows, role grants on actors, profile-edit
 # approvals); take a backup first.
 ```
 After rollback, the v2.0.x binary works against the v2.0.x
 schema unchanged. The operator's API keys still authenticate (the
 in-memory hash table is rebuilt from `CERTCTL_API_KEYS_NAMED` on
 boot regardless of schema version).
 ## Cross-references
 - [`docs/operator/rbac.md`](../operator/rbac.md) — the operator
  how-to for the new RBAC primitive
 - [`docs/operator/auth-threat-model.md`](../operator/auth-threat-model.md) —
  what the new controls defend against
 - [`docs/reference/profiles.md`](../reference/profiles.md) — the
  Phase 9 approval-bypass closure
 - [`docs/operator/security.md`](../operator/security.md) — the
  full security posture
 - `cowork/auth-bundle-1-prompt.md` — the design + phase plan
 - `cowork/auth-bundles-index.md` — the per-phase status tracker
 - `CHANGELOG.md` — the v2.1.0 release notes lead with this guide
@@ -0,0 +1,244 @@
 # Authentication & authorization threat model
 > Last reviewed: 2026-05-09
 This document describes the attack surface around authentication and
 authorization in certctl after Bundle 1 (the RBAC primitive) lands.
 It complements [`rbac.md`](rbac.md) — that doc explains how to use
 the controls; this one explains what those controls defend against
 and which threats they explicitly do NOT close.
 For Bundle 2's OIDC + sessions extensions, this document will be
 updated. The Bundle 1 boundary is "API-key auth + RBAC primitive +
 day-0 bootstrap"; OIDC-federated humans, session cookies,
 revocation lists, WebAuthn, and break-glass local accounts are
 Bundle 2 scope.
 ## Threat actors
 1. **External attacker with no credential** — probing the public
   HTTP surface. The default trust boundary for everything except
   the protocol-level endpoints (ACME / SCEP / EST / OCSP / CRL,
   which authenticate via embedded credentials per their own RFCs).
 2. **Authenticated caller with the wrong role** — has a valid API
   key but the role doesn't grant the requested operation. The
   primary RBAC threat model.
 3. **Compromised API key** — attacker holds a valid Bearer token
   that an honest operator originally provisioned. The key may
   carry any role.
 4. **Insider operator** — legitimate access; potentially trying
   to escalate privilege or bypass the approval workflow.
 5. **Compromised audit reviewer (auditor role)** — read-only
   access to audit events but otherwise untrusted.
 ## Defenses Bundle 1 ships
 ### API-key authentication
 - API keys live in `CERTCTL_API_KEYS_NAMED` (env-var) or
  `api_keys` (DB row, written by Bundle 1 Phase 6 bootstrap and
  the future role-management API). Keys hash via SHA-256; the
  middleware compares hashes via `crypto/subtle.ConstantTimeCompare`
  to defeat timing attacks.
 - The auth middleware populates `ActorIDKey` / `ActorTypeKey` /
  `TenantIDKey` on every authenticated request context. Audit rows
  attribute every action to the named-key actor instead of the
  pre-Bundle-1 hardcoded `api-key-user` placeholder.
 - Demo mode (`CERTCTL_AUTH_TYPE=none`) injects the synthetic
  `actor-demo-anon` actor with admin grants. Production deploys
  MUST NOT use demo mode.
 ### Authorization (RBAC)
 - Every gated handler routes through `auth.RequirePermission` (or
  the router-level `rbacGate` wrap from Phase 3.5). The middleware
  resolves the actor's effective permissions via the
  `Authorizer.CheckPermission` service-layer call; on miss, the
  handler returns HTTP 403 BEFORE the body runs. This is the
  load-bearing gate.
 - The five admin-only fine-grained perms (`cert.bulk_revoke` /
  `crl.admin` / `scep.admin` / `est.admin` /
  `ca.hierarchy.manage`) are seeded into `r-admin` only. To
  delegate one, an operator creates a custom role with the
  specific perm and grants it to the right actor.
 - The auditor split: `r-auditor` holds only `audit.read` +
  `audit.export`. Pinned by the
  `internal/domain/auth/auditor_test.go` invariants. A regulator
  with the auditor key cannot read certificates, profiles,
  issuers, or any mutating surface.
 - The privilege-escalation guard: granting or revoking a role
  requires the caller to hold `auth.role.assign` (enforced in
  `internal/service/auth/actor_role_service.go`). A non-admin
  cannot self-grant admin.
 - The reserved-actor guard: mutations against `actor-demo-anon`
  return HTTP 409 from the service layer
  (`ErrAuthReservedActor`). The synthetic actor is operator-
  inaccessible.
 ### Day-0 bootstrap
 - `CERTCTL_BOOTSTRAP_TOKEN` is constant-time-compared by
  `EnvTokenStrategy.Validate`. The strategy is one-shot via
  `sync.Mutex`-guarded `consumed` bool; the second call returns
  `ErrDisabled` (HTTP 410), not `ErrInvalidToken` (HTTP 401), so
  a probing attacker cannot distinguish "wrong token, retry"
  from "already consumed".
 - The strategy also re-probes admin existence on every Validate.
  If an admin actor lands during the gap between Available and
  Validate, the second caller still gets HTTP 410.
 - The minted plaintext key is written to the response body once.
  It is NEVER logged. The token-leak hygiene test in
  `internal/api/handler/auth_bootstrap_test.go` redirects
  `slog.Default` to a buffer and grep-asserts that neither the
  bootstrap token nor the minted key appears in any log line,
  audit row, or HTTP header.
 - The minted key is hashed before persistence. Lost key →
  rotate via the regular RBAC API; the plaintext is not
  recoverable from the DB.
 ### Approval workflow + Phase 9 loophole closure
 - `CertificateProfile.RequiresApproval=true` gates two surfaces:
  (a) issuance + renewal of every cert pointing at the profile,
  (b) edits to the profile itself (Bundle 1 Phase 9). The Phase 9
  closure prevents the flip-flop bypass where an admin disables
  approval, mutates, re-enables.
 - Same-actor self-approve is rejected at the service layer with
  `ErrApproveBySameActor` for both `cert_issuance` and
  `profile_edit` kinds. Two-person integrity is the load-bearing
  invariant; pinned by tests in
  `internal/service/approval_test.go`.
 ### Audit trail
 - Every mutating operation flows through `AuditService.RecordEvent`
  or `RecordEventWithCategory`. Bundle 1 Phase 8 added the
  `event_category` column with a `CHECK` constraint enforcing
  the closed enum (`cert_lifecycle` / `auth` / `config`); the
  category surfaces the auth-mutation slice to the auditor view.
 - The WORM trigger from migration 000018
  (`audit_events_worm_trigger`) blocks `UPDATE` and `DELETE` at
  the database layer. Even an admin DB user cannot tamper with
  audit history without dropping the trigger.
 - Bundle-6's redactor (`internal/service/audit_redact.go`)
  scrubs credentials + PII from the `details` JSONB before
  persistence; an `_redacted_keys` field surfaces what the
  redactor took out for compliance review.
 ### Protocol-endpoint allowlist
 ACME / SCEP / EST / OCSP / CRL endpoints authenticate via
 embedded credentials defined by their own RFCs (JWS-signed,
 challenge passwords, mTLS, public-by-RFC). The auth middleware
 explicitly bypasses these via `IsProtocolEndpoint`. The Phase 12
 `internal/api/router/phase12_protocol_allowlist_test.go` pins
 the invariant at three layers (middleware bypass, allowlist
 constant, router-level no-rbacGate-wraps-protocol-paths).
 ## Threats Bundle 1 does NOT close
 These are NOT defended; some are deferred to Bundle 2, others
 are out-of-scope for the project entirely.
 1. **OIDC / SAML / WebAuthn federation** — Bundle 2.
 2. **Session management** — there is no session cookie, no
   server-side revocation list. Each Bearer token is the bearer
   credential. To revoke a key, delete the `actor_roles` rows or
   remove the env-var entry; there is no "log out everywhere"
   button. Bundle 2.
 3. **Local password accounts (break-glass)** — Bundle 2.
 4. **Time-bound role grants / JIT elevation** — the schema
   reserves `actor_roles.expires_at` but no UI/API to set it.
   Bundle 2 or v3.
 5. **MFA / hardware tokens for the operator console** —
   Bundle 2.
 6. **Rate limiting on the bootstrap endpoint** — the endpoint
   is one-shot by construction (consumed flag + admin-existence
   probe), so a brute-force attack on the token has at most the
   single attempt before the path closes. Per-IP rate limiting
   on the broader API is still in place via Bundle C's
   `middleware.NewRateLimiter`.
 7. **`scope_id` FK enforcement** — operators can grant a
   permission at scope `profile`/`p-bogus` without the bogus
   profile existing. The gate still works (no rows match at
   request time) but a strict 404 on grant would be cleaner. See
   `RoleRepository.AddPermission` `TODO(bundle-2)` comment in
   `internal/repository/postgres/auth.go`.
 8. **OIDC-first-admin bootstrap** — Bundle 1 ships only the
   env-var-token strategy. Bundle 2 adds the OIDC-group-claim
   strategy alongside (the `Strategy` interface in
   `internal/auth/bootstrap/` is already in place).
 9. **GUI E2E suite via Playwright** — the prompt asked for
   nine end-to-end flow tests. Bundle 1 ships 19 React Testing
   Library + Vitest tests covering the same surface; full
   Playwright land in Phase 12-extended work.
 ## Compliance mapping
 The control set in this document supports the following
 framework requirements. This is a mapping; it is not a claim of
 formal certification.
 - **SOC 2 CC6.1** (logical access controls) — RBAC primitive
  with role-based gating on every mutating endpoint.
 - **SOC 2 CC6.3** (privileged access management) — `r-admin`
  role separation + role-grant audit trail with two-person
  integrity on approval-tier profile edits.
 - **HIPAA §164.312(b)** (audit controls) — `event_category`
  column lets the auditor role review authentication / authorization
  changes specifically. WORM trigger keeps the audit table
  append-only at the database layer.
 - **NIST SSDF PO.5.2** (separation of duties) — two-person
  integrity for compliance-tier issuance via the
  `RequiresApproval` flow + Bundle 1 Phase 9's closure of the
  flip-flop bypass.
 - **FedRAMP AU-9** (audit information protection) — WORM
  enforcement + auditor-only read access (the auditor role
  cannot mutate, the WORM trigger blocks UPDATE/DELETE).
 - **PCI-DSS §10** (audit logging) — every mutating operation
  emits an audit row with actor + action + resource + timestamp +
  category. The audit table is append-only.
 ## Operator-facing checks
 Run these periodically to verify the controls are working.
 1. `certctl-cli auth keys list` — confirm no unexpected actor
   holds `r-admin`. Audit any new admin grants against the audit
   log.
 2. `SELECT actor, action, COUNT(*) FROM audit_events WHERE
   action LIKE 'approval_%' AND timestamp > NOW() - INTERVAL '7
   days' GROUP BY actor, action;` — confirm approvals are
   happening and not concentrated in a single approver.
 3. `SELECT COUNT(*) FROM audit_events WHERE actor =
   'system-bypass';` — MUST return 0 in production. A non-zero
   count means `CERTCTL_APPROVAL_BYPASS=true` was set; production
   deploys MUST leave it unset.
 4. `SELECT actor, COUNT(*) FROM audit_events WHERE action =
   'bootstrap.consume';` — MUST return at most one row per
   tenant. Multiple rows means the bootstrap endpoint was called
   more than once, which the strategy's one-shot guard should
   have prevented; investigate.
 5. `certctl-cli auth me` while authenticated as the auditor
   key — `effective_permissions` must contain `audit.read` +
   `audit.export` ONLY. Any other permission means a role grant
   widened the auditor's surface; revoke immediately.
 ## Cross-references
 - [`rbac.md`](rbac.md) — the operator how-to
 - [`security.md`](security.md) — the wider security posture
 - [`approval-workflow.md`](approval-workflow.md) — the two-person
  integrity gate
 - [`docs/migration/api-keys-to-rbac.md`](../migration/api-keys-to-rbac.md) —
  upgrade flow
 - `internal/auth/` — middleware + keystore + RequirePermission +
  bootstrap
 - `internal/service/auth/` — Authorizer + privilege-escalation
  guard + reserved-actor guard
 - `migrations/000029_rbac.up.sql` — schema + seed
 - `migrations/000030_rbac_admin_perms.up.sql` — five admin-only
  fine-grained perms
 - `migrations/000032_audit_category.up.sql` — auditor surface
 - `migrations/000033_approval_kinds.up.sql` — approval-bypass
  closure
@@ -0,0 +1,280 @@
 # RBAC operator reference
 > Last reviewed: 2026-05-09
 This is the operator-facing reference for the role-based access
 control primitive that ships with Bundle 1 (auth bundle 1) of certctl.
 Read this if you're running certctl in production and need to grant /
 revoke access to API keys, set up the auditor split, or onboard the
 first admin.
 For the threat model behind these controls, see
 [`auth-threat-model.md`](auth-threat-model.md). For the migration
 flow from a pre-Bundle-1 deployment, see
 [`docs/migration/api-keys-to-rbac.md`](../migration/api-keys-to-rbac.md).
 ## Mental model
 Every action against the certctl HTTP / CLI / MCP / GUI surface is
 performed by an **actor** (an API key, an agent's machine identity,
 the synthetic demo-anon actor when the server runs in
 `CERTCTL_AUTH_TYPE=none` mode). Each actor holds zero or more
 **roles**. Each role grants a set of **permissions** at a **scope**.
 A request to a gated endpoint succeeds when the actor's effective
 permission set (the union across all held roles) contains the
 permission the endpoint requires.
 The schema lives in `migrations/000029_rbac.up.sql` and ships with
 seven seeded default roles + a 33-permission canonical catalogue.
 The middleware that gates requests lives at
 `internal/auth/require_permission.go`. The service-layer authorizer
 that resolves "actor → permissions" lives at
 `internal/service/auth/authorizer.go`.
 ## Default roles (seeded by migration 000029)
 | Role | ID | Use case | Permission shape |
 |---|---|---|---|
 | Admin | `r-admin` | Operator with full control | Every permission in the canonical catalogue |
 | Operator | `r-operator` | Day-to-day cert lifecycle | `cert.*`, `profile.read`, `issuer.read`, `target.*`, `agent.read`, `audit.read` |
 | Viewer | `r-viewer` | Read-only console access | `*.read` for every resource type |
 | Agent | `r-agent` | Machine identity for `certctl-agent` | `cert.read` + `agent.heartbeat` + `agent.job.poll` + `agent.job.complete` + `agent.job.report` |
 | MCP | `r-mcp` | Operator-equivalent for the MCP server, minus destructive ops | Like Operator without `*.delete` |
 | CLI | `r-cli` | Day-to-day operator CLI | Like Operator + `auth.key.list` / `auth.key.create` / `auth.key.rotate` |
 | Auditor | `r-auditor` | Compliance reviewer | `audit.read` + `audit.export` ONLY |
 The auditor split is the load-bearing one: an auditor cannot read
 certificates, profiles, or issuers — only audit events. That makes the
 role legitimate to hand to a SOC 2 / FedRAMP / PCI auditor without
 giving them the keys to the kingdom. The
 `internal/domain/auth/auditor_test.go` invariants pin this set going
 forward.
 The five **admin-only fine-grained perms** seeded by migration
 000030 (Phase 3.5 conversion) gate the high-blast-radius endpoints:
 - `cert.bulk_revoke` — `POST /api/v1/certificates/bulk-revoke` and the EST sibling
 - `crl.admin` — `/api/v1/admin/crl/cache`
 - `scep.admin` — `/api/v1/admin/scep/intune/*`
 - `est.admin` — `/api/v1/admin/est/*`
 - `ca.hierarchy.manage` — `/api/v1/issuers/{id}/intermediates`, `/api/v1/intermediates/{id}`
 Only `r-admin` holds these by default. To delegate one, create a
 custom role with the specific perm and grant it to the right actor.
 ## Permission catalogue
 The catalogue is namespaced. Permission strings are stable across
 releases; new permissions add to the namespace, never reshape an
 existing one. Run
 `certctl-cli auth permissions list` (or `GET /api/v1/auth/permissions`)
 for the live catalogue.
 | Namespace | Examples | What the namespace gates |
 |---|---|---|
 | `cert.*` | `cert.read`, `cert.issue`, `cert.revoke`, `cert.delete`, `cert.bulk_revoke` | The certificate lifecycle surface (`/api/v1/certificates`) |
 | `profile.*` | `profile.read`, `profile.edit`, `profile.delete` | `CertificateProfile` CRUD |
 | `issuer.*` | `issuer.read`, `issuer.edit`, `issuer.delete` | Issuer connector config |
 | `target.*` | `target.read`, `target.edit`, `target.delete` | Deployment target config |
 | `agent.*` | `agent.read`, `agent.edit`, `agent.retire`, `agent.heartbeat`, `agent.job.*` | Agent fleet + agent self-service endpoints |
 | `audit.*` | `audit.read`, `audit.export` | The audit-events surface |
 | `auth.role.*` | `auth.role.list`, `auth.role.create`, `auth.role.edit`, `auth.role.delete`, `auth.role.assign` | RBAC management |
 | `auth.key.*` | `auth.key.list`, `auth.key.create`, `auth.key.rotate`, `auth.key.delete` | API key management |
 | `auth.bootstrap.*` | `auth.bootstrap.use` | Day-0 first-admin path |
 | `crl.admin`, `scep.admin`, `est.admin`, `ca.hierarchy.manage` | (single perms) | The five admin-only fine-grained perms (see above) |
 ## Scope semantics
 Permissions are granted at one of three scopes:
 - **`global`** — applies to every resource in the tenant. The
  default for the seeded role grants. A `cert.read` grant at global
  scope lets the actor read any certificate.
 - **`profile`** — applies only to the named `CertificateProfile`
  (matched by ID). `cert.issue` at scope `profile`/`p-corp-cdn` lets
  the actor issue against `p-corp-cdn` only.
 - **`issuer`** — applies only to the named issuer. Lets you grant
  `issuer.edit` on the production issuer to a senior operator
  without giving them edit on every issuer.
 Global beats specific: an actor with `cert.read` at global scope
 passes a `cert.read` check against any specific profile or issuer
 even if no scoped grant exists. The reverse is also true — a
 scoped grant doesn't satisfy a request against a different scope.
 The Authorizer's `CheckPermission` is the single point of truth.
 > **Note (Bundle 1 deferral):** the `scope_id` column is not
 > currently FK-constrained against the resource tables. An
 > operator can grant a permission at scope `profile`/`p-bogus`
 > without `p-bogus` existing; the gate still works (no rows match
 > at request time), but the API does not 404 the grant. Bundle 2
 > tracks the strict-FK closure. See
 > `internal/repository/postgres/auth.go::AddPermission`'s
 > `TODO(bundle-2)` comment.
 ## Granting + revoking access
 ### From the GUI
 `/auth/roles` lists every role; click into one to see its
 permissions and (if you hold `auth.role.edit`) add or remove a
 permission. `/auth/keys` lists every actor with role grants;
 click "Assign role" to grant, click the × on a role tag to revoke.
 The synthetic `actor-demo-anon` row is shown but flagged
 "system-managed" with the mutation buttons hidden — the server-side
 reserved-actor guard rejects mutations against it regardless.
 ### From the CLI
 ```bash
 # Identity probe — what can the current API key actually do?
 certctl-cli auth me
 # Roles
 certctl-cli auth roles list
 certctl-cli auth roles get r-admin
 # Permissions catalogue
 certctl-cli auth permissions list
 # Key → role assignment
 certctl-cli auth keys list
 certctl-cli auth keys assign alice --role r-operator
 certctl-cli auth keys revoke alice --role r-admin
 # Walk-every-key prompt for downgrade
 certctl-cli auth keys scope-down
 # Audit-driven role suggestion (last 30 days of audit events)
 certctl-cli auth keys scope-down --suggest
 certctl-cli auth keys scope-down --suggest --apply
 # JSON-driven scope-down for automation (Helm post-upgrade hook etc.)
 certctl-cli auth keys scope-down --non-interactive ./scope-down.json
 ```
 The mutating role-lifecycle commands (`certctl-cli auth roles
 create / update / delete` + `roles add-permission / remove-permission`)
 are tracked as Bundle 1 Phase 5.5 follow-up; today, manage custom
 roles via the HTTP API or GUI.
 ### From the HTTP API
 Every endpoint is documented in `api/openapi.yaml` under the `[Auth]`
 tag. Quick reference:
 | Endpoint | Permission |
 |---|---|
 | `GET /v1/auth/me` | (none — own data) |
 | `GET /v1/auth/roles` | `auth.role.list` |
 | `GET /v1/auth/roles/{id}` | `auth.role.list` |
 | `POST /v1/auth/roles` | `auth.role.create` |
 | `PUT /v1/auth/roles/{id}` | `auth.role.edit` |
 | `DELETE /v1/auth/roles/{id}` | `auth.role.delete` |
 | `GET /v1/auth/permissions` | `auth.role.list` |
 | `POST /v1/auth/roles/{id}/permissions` | `auth.role.edit` |
 | `DELETE /v1/auth/roles/{id}/permissions/{perm}` | `auth.role.edit` |
 | `GET /v1/auth/keys` | `auth.role.list` |
 | `POST /v1/auth/keys/{id}/roles` | `auth.role.assign` |
 | `DELETE /v1/auth/keys/{id}/roles/{role_id}` | `auth.role.assign` |
 | `GET /v1/auth/check` | (authenticated; surfaces effective perms) |
 | `GET /v1/auth/bootstrap` + `POST /v1/auth/bootstrap` | (auth-exempt; gated by env-var token) |
 ### From the MCP server
 Bundle 1 Phase 11 ships 12 RBAC tools:
 `certctl_auth_me`, `certctl_auth_list_roles`, `certctl_auth_get_role`,
 `certctl_auth_create_role`, `certctl_auth_update_role`,
 `certctl_auth_delete_role`, `certctl_auth_list_permissions`,
 `certctl_auth_add_permission_to_role`,
 `certctl_auth_remove_permission_from_role`,
 `certctl_auth_list_keys`, `certctl_auth_assign_role_to_key`,
 `certctl_auth_revoke_role_from_key`. Each routes through the same
 HTTP surface above; permission gates fire server-side.
 ## The auditor pattern
 Hand the auditor key to compliance reviewers. They get:
 - `GET /api/v1/audit?category=auth` — every auth/authz mutation
  in the system (role creates, role grants on actors, bootstrap
  consumption, etc.).
 - `GET /api/v1/audit?category=cert_lifecycle` — every cert event.
 - `GET /api/v1/audit?category=config` — every issuer / target /
  settings edit.
 - `GET /api/v1/audit/export` — bulk export.
 They do NOT get cert read, profile read, issuer read, or any
 mutating permission. The categorization is enforced by the database
 CHECK constraint (migration 000032); the WORM trigger from
 migration 000018 keeps the audit table append-only at the DB layer.
 To create an auditor key:
 1. `certctl-cli auth keys assign <key-id> --role r-auditor`
 2. (Optional) Revoke any other roles the key holds with
   `certctl-cli auth keys revoke <key-id> --role r-...`
 3. Confirm via `certctl-cli auth me` while authenticated as the
   auditor key — the response should show only `audit.read` and
   `audit.export` in `effective_permissions`.
 ## Day-0 bootstrap (first-admin path)
 Bundle 1 Phase 6 ships a one-shot bootstrap endpoint for fresh
 deployments where no admin actor exists yet.
 1. Set `CERTCTL_BOOTSTRAP_TOKEN=$(openssl rand -hex 32)` in the
   server environment.
 2. Boot the server. Logs include
   "bootstrap endpoint enabled — POST /api/v1/auth/bootstrap to
   mint the first admin key (one-shot)" when the path is callable.
 3. Run a single curl:
   ```bash
   curl -X POST $URL/api/v1/auth/bootstrap \
     -H 'Content-Type: application/json' \
     -d '{"token":"<the-token>","actor_name":"first-admin"}'
   ```
 4. Capture the `key_value` from the response. **It is shown ONCE.**
   The server never logs it.
 5. Use the new key to authenticate against the rest of the API.
   The bootstrap path is now closed: subsequent calls return HTTP
   410 Gone, even with the same valid token, because an admin
   actor exists.
 The token is constant-time-compared. The server logs a startup
 warning if `CERTCTL_BOOTSTRAP_TOKEN` is set AND admin actors
 already exist (config-drift signal). For OIDC-first-admin (the
 "first user who signs in via SSO becomes admin" pattern), wait for
 Bundle 2.
 ## Demo mode (`CERTCTL_AUTH_TYPE=none`)
 When auth is disabled, the server injects a synthetic actor
 `actor-demo-anon` into every request context. That actor holds
 `r-admin` at global scope (seeded by migration 000029), so every
 gated route resolves with a populated actor and admin grants. The
 synthetic actor is reserved: the API rejects any mutation that
 targets it (HTTP 409 with `ErrAuthReservedActor`).
 Production deployments MUST NOT use demo mode — there is no
 per-request actor identity for the audit trail, and every request
 flows as admin. Use it for the `docker compose up` demo + the five
 example folders only.
 ## Where to look next
 - [Threat model](auth-threat-model.md) — what attacks this primitive
  defends against and which it does not
 - [Migration guide](../migration/api-keys-to-rbac.md) — moving
  pre-Bundle-1 deployments onto RBAC
 - [Profiles](../reference/profiles.md) — the `RequiresApproval=true`
  flow that Bundle 1 Phase 9 closure protects from flip-flop
 - [Approval workflow](approval-workflow.md) — the Rank 7 Infisical
  deep-research deliverable that the Phase 9 closure piggybacks on
 - `internal/auth/` — the middleware + keystore + RequirePermission
 - `internal/service/auth/` — the service-layer Authorizer
 - `cowork/auth-bundle-1-prompt.md` — the design + phase plan
 - `cowork/auth-bundles-index.md` — the per-phase status tracker
@@ -1,6 +1,6 @@
 # certctl Security Posture & Operator Guidance
-> Last reviewed: 2026-05-05
+> Last reviewed: 2026-05-09
 This document collects the operator-facing security guidance that the source
 code's per-finding comment blocks reference. Each section names the audit
@@ -75,15 +75,60 @@ the accompanying tests for the format spec.
 Bundle B / M-002. Two layers decide auth-exempt status:
 1. **Router layer:** `internal/api/router/router.go::AuthExemptRouterRoutes`
-   — the 4 endpoints registered via direct `r.mux.Handle` without going
+   — the endpoints registered via direct `r.mux.Handle` without going
   through the middleware chain (`/health`, `/ready`, `/api/v1/auth/info`,
-   `/api/v1/version`).
+   `/api/v1/version`, plus `/api/v1/auth/bootstrap` GET + POST per
   Bundle 1 Phase 6).
 2. **Dispatch layer:** `internal/api/router/router.go::AuthExemptDispatchPrefixes`
   — URL-prefix routing in `cmd/server/main.go::buildFinalHandler` for
-   `/.well-known/pki/*`, `/.well-known/est/*`, and `/scep[/...]*`.
+   `/.well-known/pki/*`, `/.well-known/est/*`, `/.well-known/est-mtls`,
   and `/scep[/...]*` (incl. `/scep-mtls`).
 Both lists have AST-walking regression tests (`auth_exempt_test.go`) that
-fail CI if a new bypass lands without an updating the documented constant.
+fail CI if a new bypass lands without updating the documented constant.
 ### RBAC primitive (Bundle 1)
 Bundle 1 ships role-based authorization on top of API-key
 authentication. Every gated handler routes through the
 `auth.RequirePermission` middleware (or its router-level wrap
 `rbacGate`); the middleware resolves the actor's effective
 permissions via the service-layer `Authorizer.CheckPermission`
 and returns HTTP 403 BEFORE the handler body runs on miss. The
 seven default roles (`admin` / `operator` / `viewer` / `agent` /
 `mcp` / `cli` / `auditor`), 33-permission canonical catalogue,
 and the auditor split (`r-auditor` holds only `audit.read` +
 `audit.export`) are seeded by migration 000029.
 For the operator how-to, see [`rbac.md`](rbac.md). For the
 threat model + compliance mapping, see
 [`auth-threat-model.md`](auth-threat-model.md). For the upgrade
 flow from a pre-Bundle-1 deployment, see
 [`docs/migration/api-keys-to-rbac.md`](../migration/api-keys-to-rbac.md).
 ### Day-0 admin bootstrap (Bundle 1 Phase 6)
 Fresh deployments where no admin actor exists yet can mint the
 first admin via `POST /api/v1/auth/bootstrap` — set
 `CERTCTL_BOOTSTRAP_TOKEN`, POST a single curl with the token, and
 the server returns the plaintext key value once. The token is
 constant-time-compared; the strategy is one-shot via mutex; the
 admin-existence probe re-closes the path once an admin lands.
 The token is NEVER logged. The minted plaintext key flows only
 into the HTTP response body. See
 [`rbac.md`](rbac.md#day-0-bootstrap-first-admin-path) for the
 full flow.
 ### Approval-bypass closure (Bundle 1 Phase 9)
 `CertificateProfile.RequiresApproval=true` profiles route both
 issuance/renewal AND profile edits through the
 `ApprovalService` two-person integrity gate (Phase 9 closes the
 flip-flop loophole where an admin could disable approval, mutate,
 re-enable). Same-actor self-approve is rejected at the service
 layer with `ErrApproveBySameActor`. See
 [`docs/reference/profiles.md`](../reference/profiles.md) for the
 full gate semantics.
 ## Per-user rate limiting
@@ -1,6 +1,6 @@
 # Certificate profiles
-Last reviewed: 2026-05-09
+> Last reviewed: 2026-05-09
 A `CertificateProfile` is the policy object that groups every cert with
 the same shape: which issuer mints it, which key algorithm + size are