Skip to content

feat: admin API and dashboard for organization encryption transitions - #9446

Open
bflad wants to merge 2 commits into
bflad/aim-1006-feat-oauth-credential-backfill-andfrom
bflad/aim-1007-feat-admin-api-and-dashboard-for-organization
Open

bflad wants to merge 2 commits into
bflad/aim-1006-feat-oauth-credential-backfill-andfrom
bflad/aim-1007-feat-admin-api-and-dashboard-for-organization

Conversation

@bflad

@bflad bflad commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

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.

Written for commit 2df9579. Summary will update on new commits.

View guided diff Turn on auto-fix


🚀 Preview Environment (PR #9446)

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

Component Status Details Updated (UTC)
✅ Database Ready Created and validated 2026-11-21 20:54:46.
✅ Images Available Container images ready 2026-11-21 20:55:51.

Gram Preview Bot

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

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 (gram admin):
- getOrganizationEncryption reports the key configuration and, for each use case that moves, the transition state, live counts of waiting, unreadable and unattributed values, the last backfill and verification, and why finalize would be refused.
- listOrganizationEncryptionTransitions lists organizations by state for one use case, counting organizations that were never enrolled as platform_key.
- enroll, rollback and run act on one organization. Run backfills and verifies in dual_write, and finishes clearing platform-key copies in org_kms.
- finalize requires a typed confirmation and the number of unreadable values the administrator acknowledged. It refuses when that number no longer matches. Once org_kms is recorded it starts the run that clears the platform-key copies; if that cannot start, the hourly run finishes it.
- Writes are keyed on the organization id alone, and every change is audited to the staff member, including the clear the run performs.
- The methods are unavailable unless organization encryption is configured. Runs also need Temporal.

Admin dashboard:
- An Encryption section on the organization page, with a card per use case and the enroll, run, roll back and finalize actions. The finalize dialog states what is destroyed, that rollback is no longer possible, and the unreadable count, which the administrator must acknowledge again if it changes. The page refreshes while a backfill or clear may be running.
- An Encryption transitions page lists organizations by state and enrolls a selected batch, or the next N in platform_key, one at a time at about one a second. Failures are reported without stopping the rest, and the batch can be stopped.

Shared helper changes:
- Finalize also refuses while the organization's key is suspended, and checks the acknowledged unreadable count under the state row lock.
- A clear that loses a race with another clear reports success instead of an error.
- The on-demand run's activity timeout fits a full clear (8 minutes).

Admin MCP: no tools added. Transitions are rare staff-only steps and finalize is destructive, so they stay deliberate dashboard actions.

Temporal actions/month: unchanged per namespace except 2 to 4 per on-demand run, including one per finalize. It doesn't scale with organizations.
@bflad bflad added the enhancement New feature or request label Nov 21, 2026
@changeset-bot

changeset-bot Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 2df9579

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
server Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@linear-code

linear-code Bot commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

AIM-1007

@bflad

bflad commented Nov 21, 2026

Copy link
Copy Markdown
Member Author

Demo: screenshots

Captured against a local stack with organization encryption enabled. The red rings mark the new UI.

Encryption transitions page, with its new admin sidebar entry:

Encryption transitions page listing organizations by state

Encryption section on an organization page, in dual write with finalize blocked and the blocker listed:

Organization Encryption section in dual write with finalize blocked

After finalize, once the background run cleared the platform-key copies:

Organization Encryption section after finalize showing Organization key and cleared copies

@bflad

bflad commented Nov 21, 2026

Copy link
Copy Markdown
Member Author

Demo: bulk enroll

What it shows:

  1. The Encryption transitions page with every organization in platform key.
  2. Batch size 3, Select next in platform key, then Enroll selected (3) and the confirmation listing the organizations.
  3. Enrolling 2 of 3 with Stop, then the three rows in DUAL WRITE and the success toast.
02-bulk-enroll-trimmed.webm

@bflad

bflad commented Nov 21, 2026

Copy link
Copy Markdown
Member Author

Demo: finalize

What it shows:

  1. An organization in dual write whose blockers are clear (soak and verification backdated in the local database).
  2. The finalize dialog: what is destroyed, that rollback is no longer possible, and the unreadable count. Finalize enables only after the acknowledgement and the typed phrase.
  3. The card moves to CLEARING with the "clearing platform-key copies" toast; the page then polls until it shows ORGANIZATION KEY (last screenshot above).
04-finalize-trimmed.webm

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cubic analysis

4 issues found across 79 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="client/admin/src/sdk/src/models/components/finalizeorganizationencryptionrequestbody.ts">

<violation number="1" location="client/admin/src/sdk/src/models/components/finalizeorganizationencryptionrequestbody.ts:42">
P2: This schema omits the API’s non-negative constraint, so callers can pass a negative acknowledgement count and receive a server-side 400 after the SDK accepts and sends it. Add a `z.gte(0)` check to keep outbound validation aligned with the contract.</violation>
</file>

<file name="server/internal/admin/organizationencryption.go">

<violation number="1" location="server/internal/admin/organizationencryption.go:184">
P1: According to linked Linear issue AIM-1007, `oauth-session-tokens` enrollment must be blocked until AIM-1004 is deployed in every OAuth-serving process. This path has no rollout/readiness check, so an unupdated process can keep relying on platform copies while finalization destroys them; add the gate before allowing the first enrollment.</violation>

<violation number="2" location="server/internal/admin/organizationencryption.go:224">
P2: According to linked Linear issue AIM-1007, every admin action, including “run the backfill now,” must be audited and attributed to the staff member. A dual-write run started here has no audit record because the actor is ignored by the backfill path; record an internal staff-attributed run event when starting the workflow.</violation>
</file>

<file name="client/admin/src/sdk/src/react-query/adminListOrganizationEncryptionTransitions.core.ts">

<violation number="1" location="client/admin/src/sdk/src/react-query/adminListOrganizationEncryptionTransitions.core.ts:52">
P3: The query key does not normalize the request defaults, so omitted pagination and explicit `{ limit: 50, offset: 0 }` create separate cache entries for the same API request. Normalize both values in the key.</violation>
</file>

Linked issue analysis

Linked issue: AIM-1007: feat: admin API and dashboard for organization encryption transitions

Status Acceptance criteria Notes
✅ Show configuration and transition progress for moving use cases The API reports configuration, transition state, live counts, and backfill and verification history for both OAuth use cases.
✅ Support enrollment, rollback, backfill, and finalize actions The API and organization page expose these actions, with finalize blockers reported and checked before the transition.
✅ Enroll organizations sequentially and continue after individual failures Bulk enrollment runs one organization at a time and reports failures without stopping the remaining enrollments.
✅ Finalize safely, acknowledge unreadable values, and resume clearing Finalize rechecks the acknowledged unreadable count under lock, records org_kms first, and supports resuming an incomplete clear.
✅ Provide organization and transition dashboards with deliberate confirmation The dashboard adds per-organization controls, state-based listings, and a dialog requiring count acknowledgement and the typed phrase.
✅ Audit transition actions to the staff member internally The PR says actions, including clearing, carry the staff actor and are recorded as internal audit events.
❌ Check OAuth token-writer rollout before enrollment The issue requires checking AIM-1004 on every OAuth-serving process before enrollment, but the PR description shows no such check.

This PR changes a database schema or migrates data. Ultrareviews find 2.4x more serious bugs than standard reviews. Comment @cubic-dev-ai ultrareview to run one.

View guided diff | Turn on auto-fix | Re-trigger cubic

return nil, err
}

if _, err := s.orgEncryption.Transitions.Enroll(ctx, organizationID, move.UseCase, encryptionActor(ctx)); err != nil {

@cubic-dev-ai cubic-dev-ai Bot Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: According to linked Linear issue AIM-1007, oauth-session-tokens enrollment must be blocked until AIM-1004 is deployed in every OAuth-serving process. This path has no rollout/readiness check, so an unupdated process can keep relying on platform copies while finalization destroys them; add the gate before allowing the first enrollment.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At server/internal/admin/organizationencryption.go, line 184:

<comment>According to linked Linear issue AIM-1007, `oauth-session-tokens` enrollment must be blocked until AIM-1004 is deployed in every OAuth-serving process. This path has no rollout/readiness check, so an unupdated process can keep relying on platform copies while finalization destroys them; add the gate before allowing the first enrollment.</comment>

<file context>
@@ -0,0 +1,500 @@
+		return nil, err
+	}
+
+	if _, err := s.orgEncryption.Transitions.Enroll(ctx, organizationID, move.UseCase, encryptionActor(ctx)); err != nil {
+		return nil, mapOrganizationEncryptionError(ctx, logger, err, "enroll")
+	}
</file context>
Fix with cubic

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Declining: AIM-1004 (sealing OAuth session tokens with organization keys) is already merged and deployed to every process that serves OAuth, so there is no rollout state left for a gate to check. A code gate would also have nothing reliable to read, since deployment state is not stored anywhere the admin process can see.

FinalizeOrganizationEncryptionRequestBody
> = z.pipe(
z.object({
acknowledgedUnreadableValues: z.int(),

@cubic-dev-ai cubic-dev-ai Bot Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This schema omits the API’s non-negative constraint, so callers can pass a negative acknowledgement count and receive a server-side 400 after the SDK accepts and sends it. Add a z.gte(0) check to keep outbound validation aligned with the contract.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At client/admin/src/sdk/src/models/components/finalizeorganizationencryptionrequestbody.ts, line 42:

<comment>This schema omits the API’s non-negative constraint, so callers can pass a negative acknowledgement count and receive a server-side 400 after the SDK accepts and sends it. Add a `z.gte(0)` check to keep outbound validation aligned with the contract.</comment>

<file context>
@@ -0,0 +1,65 @@
+    FinalizeOrganizationEncryptionRequestBody
+  > = z.pipe(
+    z.object({
+      acknowledgedUnreadableValues: z.int(),
+      confirmation: z.string(),
+      organizationId: z.string(),
</file context>
Suggested change
acknowledgedUnreadableValues: z.int(),
acknowledgedUnreadableValues: z.int().check(z.gte(0)),
Fix with cubic

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Declining: this file is generated by the Speakeasy SDK generator from the OpenAPI document and cannot be edited by hand. The minimum is declared in the design (Minimum(0) on acknowledged_unreadable_values), Goa validates it on the server, and the dashboard only ever sends the non-negative count it read from the API.

return nil, oops.E(oops.CodeConflict, nil, "the platform-key copies are already cleared; there is nothing left to run").LogInfo(ctx, logger)
}

if err := s.orgEncryption.Runs.StartOrganizationEncryptionRun(ctx, organizationID, move.UseCase, encryptionActor(ctx)); err != nil {

@cubic-dev-ai cubic-dev-ai Bot Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: According to linked Linear issue AIM-1007, every admin action, including “run the backfill now,” must be audited and attributed to the staff member. A dual-write run started here has no audit record because the actor is ignored by the backfill path; record an internal staff-attributed run event when starting the workflow.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At server/internal/admin/organizationencryption.go, line 224:

<comment>According to linked Linear issue AIM-1007, every admin action, including “run the backfill now,” must be audited and attributed to the staff member. A dual-write run started here has no audit record because the actor is ignored by the backfill path; record an internal staff-attributed run event when starting the workflow.</comment>

<file context>
@@ -0,0 +1,500 @@
+		return nil, oops.E(oops.CodeConflict, nil, "the platform-key copies are already cleared; there is nothing left to run").LogInfo(ctx, logger)
+	}
+
+	if err := s.orgEncryption.Runs.StartOrganizationEncryptionRun(ctx, organizationID, move.UseCase, encryptionActor(ctx)); err != nil {
+		return nil, oops.E(oops.CodeUnexpected, err, "error starting the organization encryption run").LogError(ctx, logger)
+	}
</file context>
Fix with cubic

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Declining by design: "Run backfill now" changes no transition state, so it records no audit event. The work it can lead to that does change state is already attributed to the staff member: the clear it finishes in org_kms carries the requesting actor through the workflow params into ClearPlatformCopies, which records organization_encryption_transition:clear_platform_copies with that actor. Enroll, rollback and finalize are each audited to the staff member as well.

Comment thread client/admin/src/lib/adminNav.ts Resolved
Comment on lines +52 to +53
limit: request?.limit,
offset: request?.offset,

@cubic-dev-ai cubic-dev-ai Bot Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The query key does not normalize the request defaults, so omitted pagination and explicit { limit: 50, offset: 0 } create separate cache entries for the same API request. Normalize both values in the key.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At client/admin/src/sdk/src/react-query/adminListOrganizationEncryptionTransitions.core.ts, line 52:

<comment>The query key does not normalize the request defaults, so omitted pagination and explicit `{ limit: 50, offset: 0 }` create separate cache entries for the same API request. Normalize both values in the key.</comment>

<file context>
@@ -0,0 +1,92 @@
+    queryKey: queryKeyAdminListOrganizationEncryptionTransitions({
+      useCase: request?.useCase,
+      state: request?.state,
+      limit: request?.limit,
+      offset: request?.offset,
+    }),
</file context>
Suggested change
limit: request?.limit,
offset: request?.offset,
limit: request?.limit ?? 50,
offset: request?.offset ?? 0,
Fix with cubic

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Declining: this file is generated by the Speakeasy SDK generator and cannot be edited by hand. The dashboard always passes explicit limit and offset values for list queries, and invalidates by the shared key prefix after changes, so the two forms never coexist in practice.

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

- gram admin builds organization encryption whether or not the application encryption key is set, so the transition methods no longer depend on it. Only the remote session service still needs both.
- Finalize requires the acknowledged unreadable count instead of treating it as optional.
- The configuration response declares its mode and state enums.
- Bulk enroll uses the use case the URL names, and "select next" pages past disabled organizations until it has enough.
- The finalize dialog's own button follows blockers that appear while it is open, and the dialog scrolls on short screens.
- The command palette finds the encryption pages by rollback, roll back and finalize.
- Tests prove enrollment runs one organization at a time, that the organization-key copy still opens after clearing, and the exact finalize blocker messages.
@bflad
bflad marked this pull request as ready for review November 21, 2026 20:50
@bflad
bflad requested a review from a team as a code owner November 21, 2026 20:50
@github-actions github-actions Bot added the preview Spawn a preview environment label Nov 21, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request preview Spawn a preview environment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant