feat: admin API and dashboard for organization encryption transitions

BF
8h ago
+47759-26753

https://linear.app/speakeasy/issue/AIM-1007/feat-admin-api-and-dashboard-for-organization-encryption-transitions

Stacked on #9311 (AIM-1006, the background backfill and verification). Review and merge that first; this PR then retargets main.

Summary

Staff can now see where each organization stands in moving its OAuth client secrets and session tokens from the platform key to its own key, and drive that move from the admin dashboard.

Admin API (server/design/admin/organizationencryption.go, server/internal/admin/organizationencryption.go)

  • getOrganizationEncryption: the key configuration and, for each use case that moves (oauth-client-secrets, oauth-session-tokens), the transition state, live counts of waiting, unreadable and unattributed values, the last backfill and verification, and the reasons finalize would be refused. tailscale-gateway-state is left out because it never had platform-key copies.
  • listOrganizationEncryptionTransitions: organizations by state for one use case, with counts per state. Organizations that were never enrolled count as platform_key.
  • enrollOrganizationEncryption, rollbackOrganizationEncryption, runOrganizationEncryption: run starts an on-demand Temporal run that backfills and verifies in dual_write, or finishes clearing the platform-key copies in org_kms.
  • finalizeOrganizationEncryption: requires the typed phrase destroy platform-key copies and the number of unreadable values the admin acknowledged. Transitions.Finalize compares that number under the state row lock and refuses if it changed. After org_kms is recorded, the handler starts the clearing run; if it cannot start, the hourly run finishes the clear and the response says so.
  • Writes are keyed on the organization id alone. Every change is audited (internal only) to the staff member, including the clear the run performs, because the actor is carried through the workflow params.
  • gram admin wires this only when organization encryption is configured; otherwise the methods return 503. Without Temporal, only run is unavailable.

Admin dashboard (client/admin)

  • An Encryption section on the organization page with a card per use case and the enroll, run backfill / resume clearing, roll back and finalize actions. Finalize stays disabled while blockers exist and lists them. The page polls while a backfill or clear may be running.
  • The finalize dialog states what is destroyed, that rollback is no longer possible, and the unreadable count. The admin must tick an acknowledgement of that count (which lapses if the count changes) and type the phrase.
  • An Encryption transitions page lists organizations by state and use case, with "select next N in platform key" and a bulk enroll that runs in the browser one organization at a time at about one a second. Failures are listed without stopping the rest, and the batch can be stopped.

Shared helper (server/internal/orgencryption, server/internal/background)

  • FinalizeRequest.ExpectedUnreadable, and finalize refuses while the organization's key is suspended.
  • ClearPlatformCopies reports success when another clear (such as the hourly resume) finished first, instead of a wrapped no rows error.
  • Migrator.RunOnDemand backs the on-demand workflow, whose activity timeout now fits a full clear (8 minutes).
  • Exported CountStores and FinalizeBlockers for the admin view. FinalizeBlockers is advisory; finalize checks again under the lock.

Motivation

Moving an organization to its own key ends with an irreversible step: finalize destroys the platform-key copies. Staff need to see each organization's progress, enroll organizations in controlled batches (each enroll can mint a KMS key), and finalize deliberately once the backfill and verification are clean. The ordering, fencing and audit events already live in the shared helper (AIM-1001), so this PR calls it rather than reimplementing them, and keeps finalize synchronous so the acknowledged count is checked at the moment of the change. Clearing runs as a Temporal run so it survives admin restarts, and bulk enroll runs from the dashboard so a long batch never depends on one HTTP request.

Admin MCP parity: no tools added. Transitions are rare, staff-only platform steps, and finalize is destructive, so they stay deliberate dashboard actions behind a typed confirmation. The decision is recorded in the design file.

Temporal actions/month ≈ 2 to 4 per on-demand run (including one per finalize) on top of AIM-1006's ~1,440 per namespace, scales with fixed (staff actions only, not organizations).

Gutternote review steps

Setup: preview deployments run gram admin without organization encryption, so in a preview both pages report that organization encryption is not available on this server. The demo below shows the flows against a local stack with it enabled.

  1. Admin sidebar → Encryption transitions (/encryption-transitions). Expect the use case and state filters, counts per state, Batch size, Select next in platform key and Enroll selected (N) above a table of organizations.
  2. Set Batch size to 2, click Select next in platform key, then Enroll selected (2) and confirm. The button shows Enrolling 1 of 2, then the rows show DUAL WRITE.
  3. Open an organization → sidebar Encryption (/organizations/<org>/encryption). Expect a Key card and a card per use case with its state badge, counts, last backfill and verification. In dual write, Finalize is disabled and the blockers are listed.
  4. On an organization whose blockers are clear, click Finalize. The dialog lists what is destroyed and the unreadable count; the Finalize button enables only after ticking the acknowledgement and typing destroy platform-key copies. After finalize, the badge shows CLEARING and then ORGANIZATION KEY with the copies cleared.

Also check: the 503 message when organization encryption is not configured, and the command palette entries for Encryption (organization) and Encryption transitions.


Summary by cubic

Staff can now see where each organization stands in moving its OAuth client secrets and session tokens from the platform key to its own key, and drive the move from the admin dashboard.

Admin API

  • Adds endpoints to view an organization's encryption configuration and transition state, list organizations by transition state, and enroll, roll back, run backfills, and finalize.
  • gram admin builds organization encryption independently of the application encryption key; methods return 503 unless organization encryption is configured, and run additionally requires Temporal.
  • finalize requires the typed phrase destroy platform-key copies and an acknowledged unreadable count, re-checked under the state row lock; it refuses while the organization's key is suspended.
  • After finalize records org_kms, it starts a run that clears the platform-key copies; if that run cannot start, the hourly background run finishes the clear.
  • Writes are keyed on organization ID, and every change (including clears) is audited to the staff member.
  • No admin MCP tools: transitions are rare, staff-only steps and finalize is destructive, so they stay deliberate dashboard actions.

Admin dashboard

  • Adds an Encryption section to the organization page with enroll, run, roll back, and finalize actions, polled while backfill or clearing may be running.
  • Adds an Encryption transitions page listing organizations by state, with batch enrollment that runs one organization at a time and reports failures without stopping; "select next" skips disabled organizations.
  • The finalize dialog states what is destroyed and the unreadable count, requires the typed phrase plus an acknowledgement that lapses if the count changes, and disables its button as new blockers appear.

🚀 Preview Environment (PR #9446)

Preview URL: https://pr-9446.dev.getgram.ai

ComponentStatusDetailsUpdated (UTC)
✅ DatabaseReadyCreated and validated2026-11-21 20:54:46.
✅ ImagesAvailableContainer images ready2026-11-21 20:55:51.

Gram Preview Bot