From 23cb3d4a634c0b04acff808ffde6aa7f0cd06a98 Mon Sep 17 00:00:00 2001
From: vthwang <vthwang.work@gmail.com>
Date: Mon, 3 Aug 2026 13:31:11 -0700
Subject: [PATCH] feat: add co-admins to the platform stack's VTA from the
 admin panel

Signed-off-by: vthwang <vthwang.work@gmail.com>
---
 CLAUDE.md                                     |  52 +++
 docs/platform-stack-admin-grant-design.md     | 427 ++++++++++++++++++
 internal/apidocs/openapi.yaml                 | 185 ++++++++
 .../handler/admin_platform_stack_admins.go    | 318 +++++++++++++
 .../handler/admin_platform_stack_grant.go     | 224 +++++++++
 .../admin_platform_stack_grant_test.go        | 107 +++++
 internal/k8s/fullstack_names.go               |   9 +
 internal/model/vta_admin_grant.go             |  52 +++
 internal/router/router.go                     |  15 +
 migrations/000027_vta_admin_grants.down.sql   |   3 +
 migrations/000027_vta_admin_grants.up.sql     |  61 +++
 11 files changed, 1453 insertions(+)
 create mode 100644 docs/platform-stack-admin-grant-design.md
 create mode 100644 internal/handler/admin_platform_stack_admins.go
 create mode 100644 internal/handler/admin_platform_stack_grant.go
 create mode 100644 internal/handler/admin_platform_stack_grant_test.go
 create mode 100644 internal/model/vta_admin_grant.go
 create mode 100644 migrations/000027_vta_admin_grants.down.sql
 create mode 100644 migrations/000027_vta_admin_grants.up.sql

diff --git a/CLAUDE.md b/CLAUDE.md
index 103ecd3..da010af 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -172,6 +172,8 @@ To create additional admins, an authenticated admin calls `POST /api/v1/admin/ad
 | `POST` | `/api/v1/admin/setup-sessions/:id/vtc/install-ack` | admin | Admin twin of the user route |
 | `POST` | `/api/v1/admin/platform-stack` | admin | Create the platform stack: domain row + 4 proxied DNS records + `full_stack` session, in one action. The only route that mints a `domains` row for our own zone |
 | `GET` | `/api/v1/admin/platform-stack` | admin | Its state, plus the `config_values` to copy into the environment once it's running |
+| `GET` | `/api/v1/admin/platform-stack/admins` | admin | What was added from here — a history of grants, not the VTA's admin list (nothing stores a copy of that). Free, stored state only. See "Co-admins on the platform stack" below |
+| `POST` | `/api/v1/admin/platform-stack/admins` | admin | Self-service: add a `did:key` as **unrestricted super admin** on that VTA — the same authority the stack's first admin got. **Stops the VTA for ~1 minute**, serialises against itself (409 while another is running). Requires `did`, `label` and `{"confirm": "<label>"}` |
 | `GET` | `/api/v1/admin/setup/domain-info` | admin | Admin-cookie twin of `GET /setup/domain-info` — the platform stack page names its hostnames before they exist |
 
 Every route an authenticated admin calls lives under `/api/v1/admin/...` — that
@@ -429,6 +431,56 @@ below).
   the `*.firstperson.dev` wildcard already covers the names.
 - `beta_access` doesn't apply (it's a user gate); cluster capacity does.
 
+### Co-admins on the platform stack
+
+`step_import_admin_did` writes the VTA's admin ACL once, mid-pipeline, with
+`vta import-did --role admin` and **no `--context`** — an empty context list,
+which is the definition of a super admin (`is_super_admin()` is the admin role
+plus an unrestricted act scope). Adding a second co-admin means emitting the
+same command again with a different DID, so there is no separate authority
+model to keep in sync.
+
+The point is self-service: a second admin pastes the DID their own `pnm setup`
+minted, instead of asking whoever holds the credential to run `pnm acl create`
+by hand. **Adding only** — removal is `pnm acl delete` against the live VTA,
+which costs no downtime and, more usefully, avoids having to answer "which entry
+is whose", a question this side cannot answer well (see rotation below).
+
+Three things about that are easy to get wrong:
+
+- **Reaching the ACL means stopping the VTA.** It is a fjall store on a RWO PVC
+  and the running VTA holds a lock on it, so a grant scales the Deployment to 0,
+  waits for the pod to release the lock, runs a Job against the volume, and
+  scales back. `reissueDidsEnroll` does the same dance against the dids daemon
+  and is the template. The mediator and dids daemons are separate Deployments
+  and stay up, so `vta_only` sessions are unaffected; what goes down is this
+  stack's own VTA and its VTC. Reading costs the same window, which is why
+  **nothing here stores a copy of the ACL** — `pnm acl list` answers that against
+  the running VTA for free, and any copy would be stale within minutes anyway.
+- **A grant row is an event, not a permission.** The DID a co-admin submits is
+  the temporary `did:key` from `pnm setup`, and PNM swaps it for a long-lived
+  one on first connect (`POST /acl/swap`, which preserves role, contexts **and
+  label**). `vta_admin_grants.did` therefore goes stale by design, and `label`
+  is the only human-readable field that survives the move — which is why the API
+  requires one: it is what somebody reads at a `pnm acl list` prompt. Nothing
+  here tracks where the entry moved to.
+- **One window at a time.** `runVtaAclJob` holds a process-wide `TryLock` for the
+  whole window, and the grant route additionally refuses when a live `pending`
+  row exists (the cross-replica half — the lock is in-process). Two concurrent
+  grants would scale the same VTA down twice and run two Jobs under one name,
+  each able to delete the other's.
+
+**Platform stack only, and `runVtaAclJob` enforces it** — it refuses any session
+whose `domain_type` is not `platform`, on top of the routes already resolving
+only that session. Everything under it is session-generic by construction (the
+table is keyed by `session_id`, the K8s names derive from `session.ID`), so
+without that check a per-session route wired to it later would silently hand out
+unrestricted super admin on a stack the farm merely operates. Widening the scope
+is gated on the approval flow of design §7.4 — the `pending` status and
+`requested_by` column exist for it — not on deleting that check.
+
+Design: `docs/platform-stack-admin-grant-design.md` (§7 is the section to read).
+
 ## Beta Access
 
 `users.beta_access` (bool, default `false`) gates access to features still in
diff --git a/docs/platform-stack-admin-grant-design.md b/docs/platform-stack-admin-grant-design.md
new file mode 100644
index 0000000..5ee389e
--- /dev/null
+++ b/docs/platform-stack-admin-grant-design.md
@@ -0,0 +1,427 @@
+# Platform Stack Admin Grant — Design
+
+Lets an admin add a second (third, …) **super admin** to the platform stack's
+VTA from the admin panel, with exactly the authority the stack's first admin
+DID got at provisioning time.
+
+**Self-service is the point.** A co-admin pastes the `did:key` their own
+`pnm setup` minted and the grant happens; nobody has to collect DIDs by hand and
+run `pnm acl create` for each one.
+
+**Adding only.** Removing an admin is `pnm acl delete <did>` against the running
+VTA — no downtime, and nothing here has to answer "which entry is whose", which
+§7.2 shows this side cannot answer well.
+
+Today that authority is minted once, in the middle of the pipeline, and never
+again: `fsStepImportAdminDid` runs `vta import-did --role admin` against the
+VTA's fjall store while the VTA is still down, and after `deploy_vta` there is
+no route to a second one. The only way to add a co-admin is for the existing
+admin to run `pnm acl create` from their own workstation — which works, but is
+invisible to the farm and unavailable to anyone who does not already hold the
+credential.
+
+> **§7 is the section to read first** — it is where this design can go wrong.
+
+Prerequisite reading: [`full-stack-setup-design.md`](full-stack-setup-design.md)
+§"Phase 2", and `CLAUDE.md` §"The platform stack".
+
+---
+
+## 1. Scope
+
+| In scope | Out of scope |
+| --- | --- |
+| The **platform stack** only — one session, owned by the `platform` system account | every other `full_stack`; every `vta_only` (§10.1) |
+| Granting `role=admin` with **no contexts** — unrestricted, identical to `pnm-bootstrap` | context-scoped grants, `initiator`/`application`/`reader`, expiry (§10.2) |
+| Adding an admin | **removing** one — that is `pnm acl delete` against the live VTA (§10.4) |
+| A record of **what was added from here** | any copy of the VTA's own admin list (§7.1) |
+| Accepting ~60–120s of VTA downtime per operation (§3) | zero-downtime grants (§10.3 records what that costs) |
+
+---
+
+## 2. What "the same permission as the first admin_did" means
+
+Precisely: `Role::Admin` with an **empty** context list.
+
+`fsStepImportAdminDid` (`internal/setup/orchestrator_fullstack.go:1071`) passes
+no `--context`:
+
+```go
+cmd := fmt.Sprintf("vta import-did --role admin --label pnm-bootstrap --did %s", shellQuote(adminDid))
+```
+
+`vta import-did` writes that empty list through unchanged
+(`vta-service/src/import_did.rs`, `.with_contexts(args.context.clone())`) and
+prints `Contexts: unrestricted`. Server-side that is the definition of a super
+admin (`vti-common/src/auth/extractor.rs:258`):
+
+```rust
+pub fn is_super_admin(&self) -> bool {
+    self.role == Role::Admin && self.act_scope().is_unrestricted()
+}
+```
+
+So this feature emits **the identical command** with a different `--did` and
+`--label`. There is no new authority model to design, and nothing to keep in
+sync with the pipeline: if the pipeline's grant ever changes shape, one grep for
+`import-did` finds both call sites.
+
+Note the contrast with `fsStepVtcAclGrant`, which is deliberately *narrow* —
+`--context <vtc> --admin-expires 1h`. The codebase already distinguishes a
+short-lived machine identity from a stack owner. This feature mints the latter,
+on purpose, because co-management is the stated goal.
+
+---
+
+## 3. Transport: offline, through the PVC
+
+The VTA's ACL lives in a fjall store on a `ReadWriteOnce` PVC
+(`internal/k8s/component_jobs.go:64`), and the running VTA holds a store-level
+lock on it. A Job cannot write that store while the Deployment is up — it fails
+with `store error: FjallError: Locked`, and on a different node it cannot even
+mount the volume.
+
+So every operation is: **scale to 0 → wait for the pod to actually terminate →
+Job → scale back to 1**.
+
+This is not a new pattern. `reissueDidsEnroll`
+(`internal/handler/setup_fullstack.go:526`) does exactly this against the dids
+daemon, including the `defer` that brings the Deployment back up whatever
+happens. That handler is the template; this one differs only in which Deployment
+it stops and which binary the Job runs.
+
+**Blast radius of the window.** The mediator and the dids daemon are separate
+Deployments and stay up, so no `vta_only` session loses its mediator or its DID
+host. What is down is the platform stack's own VTA, and the VTC that
+authenticates against it. For an operation performed a handful of times in the
+life of an environment, that is the right trade — §10.3 records what buying it
+back would cost.
+
+---
+
+## 4. Data model
+
+Migration `000027_vta_admin_grants`.
+
+```sql
+CREATE TABLE vta_admin_grants (
+    id          BIGSERIAL PRIMARY KEY,
+    session_id  BIGINT NOT NULL REFERENCES setup_sessions(id) ON DELETE CASCADE,
+    did         TEXT   NOT NULL,
+    label       TEXT   NOT NULL DEFAULT '',
+    status      TEXT   NOT NULL DEFAULT 'pending'
+                CHECK (status IN ('pending','granted','failed')),
+    error_msg   TEXT   NOT NULL DEFAULT '',
+    requested_by BIGINT NULL REFERENCES admins(id) ON DELETE SET NULL,
+    granted_at  TIMESTAMPTZ NULL,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- One live grant per DID per session. Partial, so a failed attempt stays as
+-- history and the same DID can be retried without deleting the first record.
+CREATE UNIQUE INDEX vta_admin_grants_live_unique
+    ON vta_admin_grants (session_id, did)
+    WHERE status IN ('pending','granted');
+```
+
+Named for the session, not for the platform stack, because the mechanism is
+session-generic and only the *route* is narrowed (§1). Generalising later is a
+route addition, not a migration.
+
+`ON DELETE CASCADE`: the grants describe a store that is deleted with the
+session. There is nothing to orphan.
+
+**No `role` or `contexts` column.** Every row is an unrestricted admin — that is
+the feature. Adding a column that only ever holds one value invites a second
+value without the authorization work §7.4 would need.
+
+---
+
+## 5. API surface
+
+All admin-cookie only, all under the existing `/api/v1/admin` group.
+
+| Method | Path | Notes |
+| --- | --- | --- |
+| `GET` | `/api/v1/admin/platform-stack/admins` | The grant rows — what was added from here. Never blocks, never causes downtime. |
+| `POST` | `/api/v1/admin/platform-stack/admins` | `{did, label, confirm}` → grants. Synchronous; 60–120s. 409 while another grant holds the window (§7.6). |
+
+`confirm` must equal the platform stack's label, mirroring the guard on
+`DELETE /admin/setup-sessions/:id` and enforced at the API, not the UI. It is
+the speed bump on an irreversible privilege grant that also takes production
+down for a minute — see §7.4 for why a speed bump and not a second approver.
+
+Validation on `did`: must start with `did:`, must be `did:key:` (the VTA's DI
+proof verifier is `did:key`-only, so anything else produces an ACL entry that
+can never authenticate), and must not already hold a live grant (409).
+
+Synchronous, following `reissueDidsEnroll`. The row is written `pending`
+**before** the k8s work starts, so a client that times out at an ingress proxy
+has not lost the operation — `GET` still shows it, and it lands `granted` or
+`failed` regardless of who is listening.
+
+---
+
+## 6. The operation
+
+One helper, `runVtaAclJob(ctx, session, cmd)`.
+
+```
+0. refuse unless domain_type = platform (§1); TryLock or 409 (§7.6)
+1. resolve ns, deployment name (k8s.FSVtaName), selector "app=fs-vta,session-id=<id>"
+2. ScaleComponentDeployment(vta, 0)
+3. defer: ScaleComponentDeployment(vta, 1) + WaitForComponentDeploymentReady
+          — unconditionally, exactly as reissueDidsEnroll does
+4. WaitForComponentPodsGone(selector, 2m)
+5. DeleteComponentJob(jobName)         — clear a previous TTL'd run
+6. CreateComponentJob(image: session.VtaImage, PVC: vta-data, cmd)
+7. WaitForJob → JobLogs
+8. parse, persist
+```
+
+The `cmd` does one thing — import, unless the DID is already there:
+
+**Grant** — `vta import-did` prompts `Overwrite?` through `dialoguer` when an
+entry already exists (`vta-service/src/import_did.rs`), and `interact()` on a
+pod's non-TTY stdin **errors**, failing the Job. So probe first, the way
+`fsStepVtcAclGrant` probes with `list-acl`:
+
+```sh
+if vta acl get <did> >/dev/null 2>&1; then
+  echo "VTAFARM_ALREADY_PRESENT"
+else
+  vta import-did --role admin --label <label> --did <did>
+fi
+```
+
+`VTAFARM_ALREADY_PRESENT` is not an error — it is the idempotent outcome, and
+the row still lands `granted`.
+
+A condition's exit status does not trigger `set -e`, so the probe stays a test
+rather than a failure. `set -e` itself is now defensive rather than load-bearing
+— the import is the last command, so its status is the script's — and it stays in
+front of whoever appends a line next, since a trailing command would otherwise
+mask a failed import and have the API report a grant that never happened.
+
+---
+
+## 7. Where this can go wrong
+
+### 7.1 No copy of the ACL is kept
+
+An earlier draft stored one — captured as a by-product of the grant Job, which
+could run `vta acl list` inside a window already being spent. It is gone, and the
+reason is worth recording because the idea looks free.
+
+It was never free:
+
+- **It could not be trusted to be current.** It only advanced when someone
+  granted, so it could be weeks old, and a co-admin's rotation invalidates it
+  minutes after the grant that captured it (§7.2). Every surface showing it had
+  to date it and explain why it was old.
+- **It carried the only unvalidated component.** Parsing `vta acl list` output
+  is the one part of this feature that cannot be checked without the real
+  binary, and it existed solely to feed that copy.
+- **Its one logical consumer went with revoke.** The last-admin guard was the
+  only thing that ever *decided* anything on it; after §10.4 it fed a display.
+
+What replaces it is `pnm acl list` against the running VTA: live, exact, no
+downtime, and already in the hands of everyone who can act on this. The API
+records what it did — grants — and points at `pnm` for what is true now.
+
+The cost, stated plainly: nothing in the product shows the admins this API did
+not add, which is the `pnm-bootstrap` entry from provisioning plus anything added
+out of band. That is a real gap, and the answer to it is a terminal.
+
+### 7.2 The submitted DID goes stale almost immediately
+
+The DID a co-admin sends is the **temporary** `did:key` that `pnm setup` minted
+and parked in their keyring. On their first authenticated command PNM rotates:
+`POST /acl/swap` atomically moves the entry — same role, same contexts — onto a
+fresh long-lived DID and deletes the temp (`vta-sdk/src/session.rs:1107`).
+
+So minutes after a successful grant, `vta_admin_grants.did` names a DID that is
+no longer in the ACL, while the co-admin holds full super admin under a DID this
+farm has never seen.
+
+This is not a bug to fix, it is the protocol working. What follows from it:
+
+- A grant row is **a record of an event**, not a statement of current access.
+  The UI must label it that way (`granted <date>`) and must not present it as
+  the admin list.
+- The **label is required** for exactly this reason. `POST /acl/swap` carries
+  role, contexts and label onto the new entry
+  (`vta-service/src/operations/acl.rs`, `with_label(old.label.clone())`), and of
+  those the label is the only human-readable one. Grant without it and the ACL
+  holds a did:key nobody can attribute to a person.
+- Nothing on this side follows the DID to where it moved. `pnm acl list` against
+  the running VTA is what answers "who can act on this now", and it is exact
+  where any stored copy would be a guess.
+- **This is why removal is not built here.** Deleting a granted DID after a
+  rotation would remove nothing; a removal that works must target a DID from the
+  the VTA's live ACL — which this side does not hold and deliberately does not
+  try to.
+
+  It is the strongest argument for keeping removal out of scope (§10.4).
+  Attributing a rotated entry to a person is not something this side can do:
+  `vta acl list` prints DID / role / label / contexts / created, so the only
+  handle is the **label** — which the swap does preserve
+  (`with_label(old.label.clone())`), and which is why the API requires one. An
+  operator at a `pnm` prompt reads that label with the whole ACL in front of them
+  and decides. A form cannot do better, and would take a maintenance window to do
+  worse.
+
+### 7.3 Nothing stops the last admin being removed
+
+The VTA has no last-admin protection — only "solo admins can assign the admin
+role" (`vti-common/src/acl/mod.rs:797`). Nothing refuses a delete that empties
+the ACL, and nothing stops a new super admin removing the one who granted them.
+
+Since removal is out of scope (§10.4), this is not a guard this feature can
+usefully supply — the deletes happen at a `pnm` prompt, where nothing this API
+does can intercept them. It is recorded because granting is what *creates* the
+exposure: every grant adds someone able to do it.
+
+Recovery, if it happens, is an offline `vta import-did` against the PVC — which
+is exactly the machinery this feature already runs. Lockout is survivable here
+because we hold the cluster.
+
+### 7.4 This makes a vtafarm admin cookie equivalent to VTA super admin
+
+Today those are separate trust domains. A vtafarm admin can provision and delete
+stacks; a VTA super admin can sign, read the vault, and mint keys. After this
+feature, any vtafarm admin session can grant itself the second.
+
+That is a real escalation and it should be a deliberate decision, not a side
+effect. It is accepted here because the platform stack is the farm's own stack,
+run by the same operators, on a cluster where those operators already have PVC
+access — the authority exists whether or not there is a button for it.
+
+Two things make it accountable rather than silent:
+
+- `requested_by` records which admin, and the row is permanent.
+- `confirm` (§5) means it cannot be a stray click or a CSRF-shaped accident.
+
+A second-approver flow (`pending` → approved by someone already holding a VTA
+credential) was considered and deferred: it is the right shape the moment this
+generalises to **customers'** stacks (§10.1), where the argument above does not
+hold. The `pending` status and `requested_by` column exist so that flow is an
+added transition, not a schema change.
+
+### 7.5 A failed scale-back leaves the stack down
+
+The `defer` runs unconditionally, but it can itself fail. `reissueDidsEnroll`
+logs and moves on. That is survivable for a dids daemon; for the platform
+stack's VTA it should be louder — the deferred restart failing must produce a
+distinct error in the response body, not only a log line, so the operator knows
+to check rather than assuming the failure was confined to the grant.
+
+---
+
+### 7.6 Self-service makes concurrency real
+
+While one operator held the credential and did this by hand, two overlapping
+windows could not happen. Self-service makes them ordinary — two admins click
+"add" within the same minute.
+
+That is destructive, not merely racy. Both scale the VTA to 0; both then
+`DeleteComponentJob` and `CreateComponentJob` under the **same** name (there is
+one per session), so each can delete the other's running Job; and the first
+`defer` to fire scales the VTA back up while the other is still writing to the
+fjall store it holds a lock on.
+
+Two guards, because one does not cover it:
+
+- `runVtaAclJob` takes a process-wide `TryLock` before anything is scaled.
+  `TryLock`, not `Lock`: a caller who queued would sit through one outage and
+  then start another, and a queue of these is a queue of outages. Refusing with
+  409 says the true thing — nothing is broken, come back in a minute.
+- The grant route additionally refuses while a live `pending` row exists for the
+  session. The lock is in-process and cannot see a second API replica; the row is
+  written before any Kubernetes work and can. Bounded by `aclJobStale` (15 min,
+  past the Job's own `ActiveDeadlineSeconds`) so a request that died mid-window
+  cannot wedge the route permanently.
+
+Both sit inside `runVtaAclJob` and the grant handler rather than in middleware,
+so nothing can reach the window by another path.
+
+## 8. Frontend
+
+`src/pages/admin/PlatformStackView.tsx`, one new section below the existing
+stack detail. Client methods in `src/lib/api.ts` alongside `getPlatformStack`.
+
+- **Add admin** — the primary action, and the reason the page exists. A
+  `did:key` field, a **required** label ("who is this?"), and a confirm input
+  taking the stack label. The copy has to state three things plainly: the grant
+  is **unrestricted super admin**, the VTA will be **down for about a minute**,
+  and the DID being pasted is expected to change once its holder connects.
+
+  Worth spelling out the flow it sits in, because a co-admin doing this for the
+  first time will otherwise stop halfway: run `pnm setup --name <slug>` locally,
+  paste the DID it prints here, wait for this to finish, then finish with
+  `pnm setup continue <slug> --vta-did <vta_did>`.
+
+  A 409 while another grant is running is not an error state — say "another
+  admin is updating the ACL, try again in a minute" and keep the form filled in.
+
+- **Added from here** — the `vta_admin_grants` rows, labelled as events (§7.2).
+  Empty on a new stack, and it says why: the first administrator was set during
+  provisioning and was never a row here.
+
+  This is the only list on the page, so it also carries the pointer to the real
+  one: `pnm acl list` for the VTA's actual administrators, `pnm acl delete <did>`
+  to remove one. Both belong next to the rows they qualify, not in a footnote.
+
+## 9. Phasing
+
+1. ~~Migration + model + `runVtaAclJob`, with `GET`.~~ **Done.**
+2. ~~`POST` (grant), with the concurrency guards of §7.6.~~ **Done.** Revoke was
+   cut — see §10.4.
+3. ~~Frontend section.~~ **Done** — `src/pages/admin/PlatformStackAdmins.tsx`,
+   rendered from `PlatformStackView` only once the stack is `running`.
+
+Complete. A fourth phase — capturing the ACL during `fsStepImportAdminDid` — was
+planned and dropped along with the stored copy it fed; §7.1 and §10.5 record why,
+because that reasoning is not recoverable from the code that is left.
+
+`runVtaAclJob` additionally refuses any session whose `domain_type` is not
+`platform`, so the scope in §1 holds even if a per-session route is wired to it
+by mistake. That check is not the reason the scope is narrow — §7.4 is — and
+removing it is not how the scope gets widened.
+
+## 10. Deliberately out of scope
+
+**10.1 Other sessions.** The mechanism is session-generic and the table is keyed
+by `session_id`, but the routes are platform-stack only. Customers' stacks need
+the second-approver flow of §7.4 first — the §7.4 argument for accepting the
+escalation is specifically about the farm's own stack.
+
+**10.2 Anything but unrestricted admin.** Context-scoped grants are useful and
+the VTA supports them, but they need a real authorization model in the UI
+(which contexts may this admin confer?) rather than a free-text field. Out of
+scope until there is a second stated use case.
+
+**10.3 Zero downtime.** Requires the farm to hold its own admin entry in the
+VTA's ACL and to call `POST /acl` over REST. Technically clear — the VTA accepts
+a DI-signed `auth/authenticate/0.1` Trust Task over plain REST, no DIDComm or
+mediator involved (`vta-service/src/routes/auth.rs::try_authenticate_trust_task`).
+The cost is a byte-exact `eddsa-jcs-2022` signer in Go (the VTI's own docs warn
+that a mistake here "yields a signature that verifies nowhere"), or an image
+carrying a `config-session`-built `pnm`, plus a farm-held super admin on every
+stack. Revisit when this generalises past one session.
+
+**10.4 Removing an admin.** `pnm acl delete <did>` against the running VTA does
+it with no downtime and no code here. Building it into the API would mean
+answering "which of these entries is the person I want to remove" — and after a
+rotation the only handle is a label somebody typed (§7.2). An operator at a `pnm`
+prompt has the full ACL in front of them and can decide; a form cannot. The
+schema keeps no `revoked` status, so this is an addition rather than a
+resurrection if it is ever wanted.
+
+**10.5 Keeping any copy of the VTA's ACL.** Dropped along with the snapshot it
+was built for — §7.1 has the reasoning. A corollary: the once-planned fourth
+phase, capturing the ACL during `fsStepImportAdminDid`, is dropped too. It would
+have put a parse of `vta acl list` in the provisioning critical path, where a
+changed output format or a renamed flag fails the Job, fails the step and fails
+the whole stack build — for a display nobody needs.
diff --git a/internal/apidocs/openapi.yaml b/internal/apidocs/openapi.yaml
index c08e5ee..8beb6aa 100644
--- a/internal/apidocs/openapi.yaml
+++ b/internal/apidocs/openapi.yaml
@@ -1956,6 +1956,191 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /api/v1/admin/platform-stack/admins:
+    get:
+      summary: Co-admins on the platform stack's VTA
+      description: |
+        **What was added from here** — a history of events, not the VTA's
+        current admin list. Nothing here keeps a copy of that list.
+
+        The two differ in both directions and it matters:
+
+        - A `granted` DID usually is **not** in the VTA's ACL any more. The DID
+          a co-admin submits is the temporary `did:key` `pnm setup` minted, and
+          PNM swaps it for a fresh long-lived one on first connect
+          (`POST /acl/swap` moves the entry, carrying role, contexts and label,
+          then deletes the temporary). So minutes after a successful grant this
+          DID names something the ACL no longer holds, while its holder has full
+          super admin under a DID this API has never seen. That is the protocol
+          working, not a failure.
+        - Admins added out of band — the `pnm-bootstrap` entry from
+          provisioning, or anything an operator added with `pnm acl create` —
+          never appear here at all.
+
+        For who can act on the VTA right now, run `pnm acl list` against it.
+
+        Free — serves stored state, never touches the cluster.
+      tags: [Admin]
+      security:
+        - CookieAuthAdmin: []
+      responses:
+        "200":
+          description: What was added from here
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id: { type: string }
+                  label: { type: string }
+                  grants:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        did: { type: string }
+                        label: { type: string }
+                        status:
+                          type: string
+                          enum: [pending, granted, failed]
+                        error_msg: { type: string }
+                        granted_at: { type: string, format: date-time, nullable: true }
+                        created_at: { type: string, format: date-time }
+        "404":
+          description: No platform stack exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          description: Missing or invalid token
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Insufficient role
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    post:
+      summary: Grant a co-admin on the platform stack's VTA
+      description: |
+        Adds `did` to the VTA's ACL as an **unrestricted super admin** — the
+        same authority the stack's first admin got at provisioning
+        (`vta import-did --role admin` with no `--context`). There is no role or
+        scope parameter: unrestricted is the whole feature. A holder can sign,
+        read the vault, mint keys, and **remove any other admin including the
+        one who granted them** — the VTA has no last-admin protection.
+
+        **This stops the VTA for roughly a minute** (see the refresh route).
+        Synchronous, so the request blocks for the whole window. The grant row
+        is written `pending` *before* the Kubernetes work starts, so a client
+        that times out at a proxy has not lost the operation — it still lands
+        `granted` or `failed`, and `GET .../admins` shows the outcome.
+
+        `did` must be a `did:key` — the form `pnm setup` mints, and the only one
+        the VTA's REST login can verify. The expected flow: the co-admin runs
+        `pnm setup --name <slug>`, sends the DID it prints, and after this
+        succeeds finishes with `pnm setup continue <slug> --vta-did <vta_did>`.
+
+        Expect that DID to **stop being their DID** on their first connect —
+        PNM rotates onto a fresh long-lived one and the ACL entry moves with it.
+        That is normal; see `GET .../admins`.
+
+        `already_present: true` means the DID was already in the ACL and nothing
+        changed. Not an error — reported so a UI can say so rather than imply it
+        just granted something.
+
+        **Serialised against itself.** Two grants at once would scale the same
+        VTA down twice and run two Jobs under one name, each able to delete the
+        other's. A second caller gets 409 while a window is open — nothing is
+        wrong, come back in a minute.
+
+        **Removing an admin is not here.** Use `pnm acl delete <did>` against the
+        running VTA: no downtime, and no need for this side to work out which ACL
+        entry belongs to whom once PNM has rotated keys.
+      tags: [Admin]
+      security:
+        - CookieAuthAdmin: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [did, label, confirm]
+              properties:
+                did:
+                  type: string
+                  description: The co-admin's `did:key`, from `pnm setup`.
+                  example: did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
+                label:
+                  type: string
+                  maxLength: 64
+                  description: |
+                    Who this key belongs to. **Required** — PNM rotates the DID
+                    away on first connect and the label is the only
+                    human-readable field that survives the move, so an entry
+                    granted without one cannot be attributed to anyone later.
+                confirm:
+                  type: string
+                  description: Must equal the platform stack's label.
+      responses:
+        "200":
+          description: Granted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  did: { type: string }
+                  status: { type: string, enum: [granted] }
+                  already_present: { type: boolean }
+                  warning:
+                    type: string
+                    description: Present only when the VTA failed to restart. The stack is down.
+        "400":
+          description: Bad `did`, oversized label, or missing/non-matching `confirm`
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "409":
+          description: |
+            Either this DID already has a pending or granted entry, or another
+            admin's grant is mid-window. Both are retryable; neither means
+            damage.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: No platform stack exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "502":
+          description: The Kubernetes work failed; the grant row is marked `failed`
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          description: Missing or invalid token
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Insufficient role
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
   /api/v1/admin/setup/images:
     get:
       summary: List available component images (admin)
diff --git a/internal/handler/admin_platform_stack_admins.go b/internal/handler/admin_platform_stack_admins.go
new file mode 100644
index 0000000..dc4b81a
--- /dev/null
+++ b/internal/handler/admin_platform_stack_admins.go
@@ -0,0 +1,318 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+	corev1 "k8s.io/api/core/v1"
+
+	"github.com/ic3software/vtafarm-api/internal/k8s"
+	"github.com/ic3software/vtafarm-api/internal/model"
+)
+
+// Co-admins on the platform stack's VTA.
+// Design: docs/platform-stack-admin-grant-design.md.
+//
+// The point of the feature is self-service: a second admin pastes the `did:key`
+// their own `pnm setup` minted, instead of asking whoever holds the stack's
+// credential to run `pnm acl create` for them.
+//
+// **Adding only.** Removing an admin is deliberately not here — an operator who
+// needs to do it runs `pnm acl delete` against the live VTA, which costs no
+// downtime and needs nothing from this side. What that buys is not just less
+// code: it removes the need to work out *which* ACL entry belongs to whom, a
+// question this side cannot answer well (see the note on rotation below).
+//
+// The VTA's admin ACL is a fjall store on a ReadWriteOnce PVC, and the running
+// VTA holds a store-level lock on it, so writing it means stopping the VTA,
+// running a Job against the volume, and starting it again (§3).
+// `reissueDidsEnroll` does the same dance against the dids daemon and is the
+// template this follows, down to the unconditional deferred restart.
+//
+// This tracks **what was added from here**, and nothing else. It does not keep a
+// copy of the VTA's admin list: reading that costs the same maintenance window
+// as writing it, any copy is stale the moment a co-admin rotates their key, and
+// `pnm acl list` answers the live question against the running VTA for free.
+
+// aclJobTimeouts. The window is dominated by waiting for the old pod's lock to
+// be released and by the new pod's readiness probe, not by the CLI itself.
+const (
+	aclPodsGoneTimeout = 2 * time.Minute
+	aclRestartTimeout  = 3 * time.Minute
+	aclReadyTimeout    = 2 * time.Minute
+
+	// aclJobStale bounds how long a `pending` row can block the next attempt.
+	// Matches ComponentJobSpec's default ActiveDeadlineSeconds (600s) plus the
+	// restart budget: past that, no Job of ours can still be running, so a row
+	// still sitting at `pending` belongs to a request that died without
+	// finishing — most likely a replica that was killed mid-window.
+	aclJobStale = 15 * time.Minute
+)
+
+// aclJobLock serialises the maintenance window against itself.
+//
+// Two concurrent grants would be genuinely destructive, not merely racy: both
+// scale the VTA to 0, both then `DeleteComponentJob` and `CreateComponentJob`
+// under the *same* name (there is one per session), so each can delete the
+// other's running Job — and the first `defer` to fire scales the VTA back up
+// while the other is still writing to the fjall store it holds a lock on.
+//
+// This never mattered while one operator held the stack's credential and did
+// this by hand. It matters the moment it is self-service, which is the whole
+// point of the feature.
+//
+// One lock rather than one per session because runVtaAclJob refuses any session
+// that is not the platform stack, so there is exactly one session it can ever
+// run for. If that scope ever widens, this has to become per-session — the
+// comment in runVtaAclJob's guard is the other half of that statement.
+var aclJobLock sync.Mutex
+
+// errAclJobBusy is a sentinel so the handler answers 409 (come back in a
+// minute) rather than 502 (something broke). Nothing is wrong when this fires.
+var errAclJobBusy = errors.New(
+	"another admin is updating the VTA's ACL right now — that takes about a minute; try again after it finishes")
+
+// platformSession loads the platform stack's session, writing the response and
+// returning nil when there isn't one. Same two-step lookup GetPlatformStack
+// does — the domain row outlives its session, so "no domain" and "domain but no
+// session" are different states and both mean there is no stack to administer.
+func (h *SetupHandler) platformSession(c *gin.Context) *model.SetupSession {
+	domain, err := h.platformDomain()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to read platform domain"})
+		return nil
+	}
+	if domain == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no platform stack exists"})
+		return nil
+	}
+
+	var session model.SetupSession
+	err = h.db.Where("domain_id = ?", domain.ID).First(&session).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no platform stack exists"})
+		return nil
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to read platform session"})
+		return nil
+	}
+	return &session
+}
+
+// ListPlatformStackAdmins — GET /api/v1/admin/platform-stack/admins.
+//
+// Serves stored state only: never stops the VTA, never blocks.
+//
+// This is a history of what was added from here, **not** the VTA's current
+// admin list — and the two genuinely differ. A granted DID stops being the
+// holder's DID on their first connect (PNM rotates and `POST /acl/swap` moves
+// the entry), and admins added out of band never appear here at all. For who
+// can act on the VTA right now, `pnm acl list`.
+func (h *SetupHandler) ListPlatformStackAdmins(c *gin.Context) {
+	session := h.platformSession(c)
+	if session == nil {
+		return
+	}
+
+	var grants []model.VtaAdminGrant
+	if err := h.db.Where("session_id = ?", session.ID).
+		Order("created_at DESC").Find(&grants).Error; err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to read grants"})
+		return
+	}
+	if grants == nil {
+		grants = []model.VtaAdminGrant{}
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"id":     session.VtaName,
+		"label":  session.VtaName,
+		"grants": grants,
+	})
+}
+
+// requireStackConfirm gates the one route that takes the VTA down, mirroring
+// the guard on DELETE /admin/setup-sessions/:id: the caller must name the stack.
+//
+// Enforced here rather than in the UI. Adding an admin is both an irreversible
+// privilege grant and a minute of downtime on the flagship stack — neither is
+// something a stray click should be able to cause.
+//
+// Takes the already-bound value rather than reading the body itself, because
+// gin's ShouldBindJSON consumes it: the grant route carries `did` and `label`
+// alongside `confirm` and has to bind all three in one pass. A missing or
+// malformed body leaves Confirm at "", which fails here exactly as a wrong
+// value does — both mean "not confirmed".
+func requireStackConfirm(c *gin.Context, session *model.SetupSession, confirm string) bool {
+	if confirm != session.VtaName {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": "this stops the platform stack's VTA for about a minute — " +
+				`send {"confirm": "` + session.VtaName + `"} to proceed`,
+		})
+		return false
+	}
+	return true
+}
+
+// aclRestartError marks a failure of the deferred scale-back-up, so callers can
+// tell "the grant failed" from "the grant may have worked but the VTA is still
+// down" — §7.5. reissueDidsEnroll only logs this; for the platform stack's own
+// VTA it has to reach the operator.
+type aclRestartError struct{ err error }
+
+func (e *aclRestartError) Error() string { return e.err.Error() }
+func (e *aclRestartError) Unwrap() error { return e.err }
+
+// runVtaAclJob stops the VTA, runs `cmd` against its PVC, and starts it again.
+//
+// Returns the Job's logs, a non-nil restart error if bringing the VTA back up
+// failed, and the operation error. The restart error is returned separately
+// from the operation error on purpose: the two are independent, and an
+// operation that succeeded while the restart failed is the case most in need of
+// being reported accurately.
+//
+// The Job runs with Env: fsNoColorEnv() like every other full_stack Job — some
+// of these binaries colorize output even when stdout is not a TTY, and the ANSI
+// escapes corrupt captured values (§6).
+func (h *SetupHandler) runVtaAclJob(
+	ctx context.Context, session *model.SetupSession, cmd string,
+) (logs string, restartErr error, err error) {
+	// The platform stack, and nothing else — design §1 and §10.1.
+	//
+	// The routes above already resolve only the platform session, so reaching
+	// this with anything else is a programming error rather than a request. It
+	// is checked here anyway because everything below is session-generic by
+	// construction (the table is keyed by session_id, the names are derived
+	// from session.ID), so the day someone wires a per-session route to it,
+	// nothing else would object — and what it would silently hand out is
+	// unrestricted super admin on a stack this farm merely operates.
+	//
+	// Widening this is gated on the approval flow of §7.4, not on deleting a
+	// line here.
+	if session.DomainType != model.DomainPlatform {
+		log.Printf("[platform-admins] refused ACL job for non-platform session %d (%s, domain_type=%s)",
+			session.ID, session.VtaName, session.DomainType)
+		return "", nil, fmt.Errorf(
+			"ACL grants are limited to the platform stack; session %q is domain_type=%s",
+			session.VtaName, session.DomainType)
+	}
+	if h.k8s == nil {
+		return "", nil, fmt.Errorf("k8s not configured")
+	}
+	if session.VtaImage == "" {
+		return "", nil, fmt.Errorf("stack has no VTA image recorded — it has not been provisioned")
+	}
+
+	// Held for the whole window, taken before anything is scaled. TryLock
+	// rather than Lock: a caller who waits would sit through the other window
+	// and then start their own, so the honest answer is to refuse now and let
+	// them retry once — a queue of these is a queue of outages.
+	if !aclJobLock.TryLock() {
+		return "", nil, errAclJobBusy
+	}
+	defer aclJobLock.Unlock()
+
+	ns := h.k8s.UserNamespace(fmt.Sprintf("%d", session.UserID))
+	vtaName := k8s.FSVtaName(session.ID)
+	selector := fmt.Sprintf("app=fs-vta,session-id=%d", session.ID)
+	jobName := k8s.FSJobVtaACL(session.ID)
+
+	if scaleErr := h.k8s.ScaleComponentDeployment(ctx, ns, vtaName, 0); scaleErr != nil {
+		return "", nil, fmt.Errorf("failed to stop the VTA: %w", scaleErr)
+	}
+
+	// Bring the VTA back however this returns. Its own context, because the
+	// request's may already be cancelled by the time we get here — a client
+	// hanging up must not be what leaves the stack down.
+	defer func() {
+		restartCtx, cancel := context.WithTimeout(context.Background(), aclRestartTimeout)
+		defer cancel()
+		if e := h.k8s.ScaleComponentDeployment(restartCtx, ns, vtaName, 1); e != nil {
+			log.Printf("[platform-admins] error: failed to restart VTA for session %d: %v", session.ID, e)
+			restartErr = &aclRestartError{e}
+			return
+		}
+		if e := h.k8s.WaitForComponentDeploymentReady(restartCtx, ns, vtaName, aclReadyTimeout); e != nil {
+			log.Printf("[platform-admins] warn: VTA not ready after ACL job for session %d: %v", session.ID, e)
+			restartErr = &aclRestartError{e}
+		}
+	}()
+
+	// Scaling to 0 only stops scheduling — the outgoing pod keeps the fjall
+	// lock until it actually terminates, so the Job cannot start before this.
+	if waitErr := h.k8s.WaitForComponentPodsGone(ctx, ns, selector, aclPodsGoneTimeout); waitErr != nil {
+		return "", nil, fmt.Errorf("failed waiting for the VTA to stop: %w", waitErr)
+	}
+
+	h.k8s.DeleteComponentJob(ctx, ns, jobName) // clear a previous (TTL'd) run
+
+	if createErr := h.k8s.CreateComponentJob(ctx, ns, k8s.ComponentJobSpec{
+		Name:           jobName,
+		Image:          session.VtaImage,
+		Command:        []string{"sh", "-c", cmd},
+		WorkingDir:     "/work/vta",
+		ServiceAccount: k8s.VtaServiceAccount,
+		PVCMounts:      []k8s.PVCMount{{Name: "vta-data", ClaimName: vtaName, MountPath: "/work/vta"}},
+		Env:            noColorEnv(),
+	}); createErr != nil {
+		return "", nil, fmt.Errorf("failed to create the ACL job: %w", createErr)
+	}
+
+	succeeded, failMsg, watchErr := h.k8s.WaitForJob(ctx, ns, jobName)
+	if watchErr != nil {
+		return "", nil, fmt.Errorf("job watch error: %w", watchErr)
+	}
+	if !succeeded {
+		return "", nil, fmt.Errorf("ACL job failed: %s", failMsg)
+	}
+
+	out, logErr := h.k8s.JobLogs(ctx, ns, jobName)
+	if logErr != nil {
+		return "", nil, fmt.Errorf("failed to read job logs: %w", logErr)
+	}
+	return out, nil, nil
+}
+
+// respondAclJobError writes the failure, folding in a failed restart when there
+// was one. Both are reported: an operator told only that the grant failed would
+// have no reason to check whether the VTA came back.
+func respondAclJobError(c *gin.Context, err, restartErr error) {
+	body := gin.H{"error": err.Error()}
+	if restartErr != nil {
+		body["error"] = err.Error() + " — " + restartWarning(restartErr)
+	}
+	// Busy is not a failure: nothing broke, nothing was scaled, and the caller
+	// should simply come back. 502 would send an operator looking for damage.
+	if errors.Is(err, errAclJobBusy) {
+		c.JSON(http.StatusConflict, body)
+		return
+	}
+	c.JSON(http.StatusBadGateway, body)
+}
+
+func restartWarning(restartErr error) string {
+	return "WARNING: the VTA did not come back up (" + restartErr.Error() +
+		"). The platform stack is down — check the deployment before retrying."
+}
+
+// noColorEnv mirrors internal/setup's fsNoColorEnv, which is unexported for the
+// same reason shellQuote is duplicated here — internal/setup and
+// internal/handler stay decoupled.
+//
+// Matters because the Job's output is read back: `already_present` is decided by
+// matching a marker in it, and some of these binaries colorize even when stdout
+// is a Job log rather than a TTY.
+func noColorEnv() []corev1.EnvVar {
+	return []corev1.EnvVar{
+		{Name: "NO_COLOR", Value: "1"},
+		{Name: "CLICOLOR", Value: "0"},
+	}
+}
diff --git a/internal/handler/admin_platform_stack_grant.go b/internal/handler/admin_platform_stack_grant.go
new file mode 100644
index 0000000..7e77f20
--- /dev/null
+++ b/internal/handler/admin_platform_stack_grant.go
@@ -0,0 +1,224 @@
+package handler
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/ic3software/vtafarm-api/internal/middleware"
+	"github.com/ic3software/vtafarm-api/internal/model"
+)
+
+// Granting a co-admin on the platform stack's VTA — phase 2 of
+// docs/platform-stack-admin-grant-design.md. Runs through runVtaAclJob in
+// admin_platform_stack_admins.go, so it takes the VTA down for the window.
+
+// didKeyRe is the shape `pnm setup` mints: did:key with a base58btc multibase.
+//
+// Narrow on purpose. The ACL itself would take any DID string, but the value
+// that belongs here is a PNM holder's key, and the VTA verifies a REST login's
+// Data-Integrity proof with a did:key-only resolver
+// (vti-common/src/auth/di_proof.rs). Admitting anything else mostly admits
+// typos, which cost a maintenance window to discover and another to undo.
+//
+// It also keeps the value trivially safe to interpolate: shellQuote is what
+// actually protects the Job command, but a DID matching this cannot contain a
+// quote to begin with.
+var didKeyRe = regexp.MustCompile(`^did:key:z[1-9A-HJ-NP-Za-km-z]{20,}$`)
+
+// alreadyPresentMarker is echoed by the grant Job when the DID already had an
+// entry. Not an error: `vta import-did` prompts "Overwrite?" through dialoguer
+// in that case, and interact() on a pod's non-TTY stdin *errors*, so the Job
+// probes with `vta acl get` first and skips the import. The outcome is the same
+// one the caller asked for, so the grant still lands `granted` (§6).
+const alreadyPresentMarker = "VTAFARM_ALREADY_PRESENT"
+
+// GrantPlatformStackAdmin — POST /api/v1/admin/platform-stack/admins.
+//
+// Adds `did` to the platform stack's VTA ACL as an **unrestricted admin** — the
+// same authority step_import_admin_did gave the stack's first admin (§2).
+//
+// Synchronous and slow (60–120s). The grant row is written `pending` before any
+// Kubernetes work starts, so a client that times out at a proxy has not lost
+// the operation: it still lands `granted` or `failed`, and GET shows it.
+func (h *SetupHandler) GrantPlatformStackAdmin(c *gin.Context) {
+	session := h.platformSession(c)
+	if session == nil {
+		return
+	}
+
+	var body struct {
+		Did     string `json:"did"`
+		Label   string `json:"label"`
+		Confirm string `json:"confirm"`
+	}
+	_ = c.ShouldBindJSON(&body)
+	if !requireStackConfirm(c, session, body.Confirm) {
+		return
+	}
+
+	did := strings.TrimSpace(body.Did)
+	if !didKeyRe.MatchString(did) {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": "did must be a did:key (the form `pnm setup` mints, and the only one the VTA's REST login can verify)",
+		})
+		return
+	}
+	// Required, not decorative. The DID in this request stops being the
+	// holder's DID on their first connect — `POST /acl/swap` moves the entry
+	// onto a freshly minted one — and of everything on that entry the label is
+	// the only human-readable field that survives the move
+	// (vta-service/src/operations/acl.rs `with_label(old.label.clone())`).
+	//
+	// Grant without one and the ACL ends up holding an unidentifiable did:key —
+	// and since removal happens at a `pnm acl list` prompt, that label is what
+	// the person deciding is reading. Cheaper to insist here.
+	label := strings.TrimSpace(body.Label)
+	if label == "" {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": "label is required — it is the only identifier that survives PNM's key rotation, " +
+				"and without it this entry cannot be attributed to anyone later",
+		})
+		return
+	}
+	if len(label) > 64 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "label must be 64 characters or fewer"})
+		return
+	}
+
+	// Not idempotent by design: a second grant of a live DID is a mistake worth
+	// surfacing, not a no-op worth hiding, because it costs a window either
+	// way. The partial unique index is the real gate; this is the readable
+	// error in front of it.
+	var existing model.VtaAdminGrant
+	err := h.db.Where("session_id = ? AND did = ? AND status IN ?",
+		session.ID, did, []string{model.GrantPending, model.GrantGranted}).First(&existing).Error
+	if err == nil {
+		c.JSON(http.StatusConflict, gin.H{
+			"error": fmt.Sprintf("this DID already has a %s grant on the platform stack", existing.Status),
+		})
+		return
+	}
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to check existing grants"})
+		return
+	}
+
+	// The cross-replica half of the mutual exclusion in runVtaAclJob. That lock
+	// is in-process, so it only serialises callers hitting the same API pod;
+	// this catches a second pod, because the `pending` row is written before any
+	// Kubernetes work starts and is therefore visible to everyone.
+	//
+	// Bounded by aclJobStale so a request that died mid-window cannot wedge the
+	// route permanently — past that deadline no Job of ours can still be alive.
+	var inFlight int64
+	if countErr := h.db.Model(&model.VtaAdminGrant{}).
+		Where("session_id = ? AND status = ? AND created_at > ?",
+			session.ID, model.GrantPending, time.Now().Add(-aclJobStale)).
+		Count(&inFlight).Error; countErr != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to check for an in-flight grant"})
+		return
+	}
+	if inFlight > 0 {
+		c.JSON(http.StatusConflict, gin.H{"error": errAclJobBusy.Error()})
+		return
+	}
+
+	grant := model.VtaAdminGrant{
+		SessionID:   session.ID,
+		Did:         did,
+		Label:       label,
+		Status:      model.GrantPending,
+		RequestedBy: callingAdminID(c),
+	}
+	if createErr := h.db.Create(&grant).Error; createErr != nil {
+		// Lost a race with a concurrent grant of the same DID — the partial
+		// unique index caught what the read above could not.
+		c.JSON(http.StatusConflict, gin.H{"error": "a grant for this DID was just created"})
+		return
+	}
+	log.Printf("[platform-admins] granting super admin on session %d to %s (requested by admin %v)",
+		session.ID, did, grant.RequestedBy)
+
+	logs, restartErr, runErr := h.runVtaAclJob(c.Request.Context(), session, grantCmd(did, label))
+	if runErr != nil {
+		h.markGrant(&grant, model.GrantFailed, runErr.Error())
+		respondAclJobError(c, runErr, restartErr)
+		return
+	}
+
+	h.markGrant(&grant, model.GrantGranted, "")
+
+	resp := gin.H{
+		"did":    did,
+		"status": grant.Status,
+		// The caller asked for this DID to hold super admin; it already did.
+		// Reported rather than swallowed so a UI can say "already an admin"
+		// instead of implying it just changed something.
+		"already_present": strings.Contains(logs, alreadyPresentMarker),
+	}
+	if restartErr != nil {
+		resp["warning"] = restartWarning(restartErr)
+	}
+	c.JSON(http.StatusOK, resp)
+}
+
+// grantCmd probes before importing, because `vta import-did` prompts on an
+// existing entry and a pod has no TTY to answer with (§6). A condition's exit
+// status does not trigger `set -e`, so the probe stays a test rather than a
+// failure.
+//
+// `set -e` is defensive rather than load-bearing now that the import is the last
+// thing to run: with a trailing command it would be the difference between
+// reporting a grant and reporting the truth, so it stays in front of the next
+// person who appends a line.
+func grantCmd(did, label string) string {
+	importCmd := "vta import-did --role admin --did " + shellQuote(did)
+	if label != "" {
+		importCmd += " --label " + shellQuote(label)
+	}
+	return "set -e\n" +
+		"if vta acl get " + shellQuote(did) + " >/dev/null 2>&1; then\n" +
+		"  echo " + alreadyPresentMarker + "\n" +
+		"else\n" +
+		"  " + importCmd + "\n" +
+		"fi\n"
+}
+
+// markGrant moves a grant row to its terminal state, keeping the in-memory copy
+// in step so the caller can report from it.
+func (h *SetupHandler) markGrant(grant *model.VtaAdminGrant, status, errMsg string) {
+	now := time.Now()
+	updates := map[string]any{"status": status, "error_msg": errMsg, "updated_at": now}
+	if status == model.GrantGranted {
+		updates["granted_at"] = now
+		grant.GrantedAt = &now
+	}
+	if err := h.db.Model(&model.VtaAdminGrant{}).Where("id = ?", grant.ID).Updates(updates).Error; err != nil {
+		log.Printf("[platform-admins] error: failed to mark grant %d as %s: %v", grant.ID, status, err)
+	}
+	grant.Status = status
+	grant.ErrorMsg = errMsg
+}
+
+// callingAdminID reads the admin's id from the request. On an admin-cookie
+// route the JWT's UserID claim is an admins.id — admins are their own table
+// (see handler/admin_enroll.go, which mints the token from admin.ID).
+func callingAdminID(c *gin.Context) *uint {
+	v, ok := c.Get(middleware.ContextUserID)
+	if !ok {
+		return nil
+	}
+	id, ok := v.(uint)
+	if !ok {
+		return nil
+	}
+	return &id
+}
diff --git a/internal/handler/admin_platform_stack_grant_test.go b/internal/handler/admin_platform_stack_grant_test.go
new file mode 100644
index 0000000..5056d46
--- /dev/null
+++ b/internal/handler/admin_platform_stack_grant_test.go
@@ -0,0 +1,107 @@
+package handler
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+)
+
+func TestDidKeyValidation(t *testing.T) {
+	cases := []struct {
+		did  string
+		want bool
+	}{
+		{"did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK", true},
+		{"", false},
+		{"did:key:", false},
+		{"did:web:example.com", false},
+		{"did:webvh:abc:dids.firstperson.dev:x-vta", false},
+		{"did:key:z6Mk", false},                            // too short to be a real multibase
+		{"did:key:6MkhaXgBZDvotDkL5257faiztiGiC2Q", false}, // no z prefix
+		// Base58btc excludes 0, O, I and l precisely so they cannot be confused.
+		{"did:key:z0OIlhaXgBZDvotDkL5257faiztiGiC2Q", false},
+		// The shape that matters for the Job command: nothing quotable gets in.
+		{"did:key:z6Mkhax'; rm -rf /", false},
+		{"did:key:z6Mkhax with spaces aaaaaaaaaaaaa", false},
+	}
+	for _, tc := range cases {
+		if got := didKeyRe.MatchString(tc.did); got != tc.want {
+			t.Errorf("didKeyRe.MatchString(%q) = %v, want %v", tc.did, got, tc.want)
+		}
+	}
+}
+
+// The Job does exactly one thing: import the DID, unless it is already there.
+// It deliberately does not read the ACL back — nothing on this side stores a
+// copy of it.
+func TestGrantCmdImportsAndNothingElse(t *testing.T) {
+	cmd := grantCmd("did:key:z6MkTest", "alice")
+	if !strings.HasPrefix(cmd, "set -e\n") {
+		t.Fatalf("grantCmd must start with `set -e`; got:\n%s", cmd)
+	}
+	// The probe exists because `vta import-did` prompts on an existing entry
+	// and dialoguer's interact() errors on a pod's non-TTY stdin.
+	if !strings.Contains(cmd, "vta acl get") {
+		t.Error("grantCmd must probe with `vta acl get` before importing")
+	}
+	if !strings.Contains(cmd, alreadyPresentMarker) {
+		t.Error("grantCmd must echo the already-present marker so the handler can report it")
+	}
+	if strings.Contains(cmd, "acl list") {
+		t.Error("grantCmd must not read the ACL back — no copy of it is kept")
+	}
+}
+
+// The label is what identifies the entry after PNM rotates the DID away, so it
+// has to reach the ACL. The handler rejects an empty one; grantCmd still omits
+// the flag rather than passing an empty string, for any caller that gets there
+// another way.
+func TestGrantCmdCarriesTheLabel(t *testing.T) {
+	withLabel := grantCmd("did:key:z6MkTest", "alice")
+	if !strings.Contains(withLabel, "--label 'alice'") {
+		t.Errorf("label not quoted into the command:\n%s", withLabel)
+	}
+	bare := grantCmd("did:key:z6MkTest", "")
+	if strings.Contains(bare, "--label") {
+		t.Errorf("empty label must omit the flag entirely, not pass '':\n%s", bare)
+	}
+}
+
+// Quoting matters more than usual here: unlike the DID, the label is free text
+// and didKeyRe does not constrain it.
+func TestGrantCmdQuotesAHostileLabel(t *testing.T) {
+	cmd := grantCmd("did:key:z6MkTest", `alice'; vta acl delete x --yes #`)
+	if !strings.Contains(cmd, `--label 'alice'\''; vta acl delete x --yes #'`) {
+		t.Errorf("label not shell-escaped:\n%s", cmd)
+	}
+}
+
+// Two admins clicking "add" at the same time is the case self-service creates
+// and the single-operator flow never had. Both windows would scale the same VTA
+// down, then delete and recreate the same Job name under each other.
+func TestAclJobLockRefusesRatherThanQueues(t *testing.T) {
+	if !aclJobLock.TryLock() {
+		t.Fatal("lock was already held at the start of the test")
+	}
+	defer aclJobLock.Unlock()
+
+	// A second caller must be turned away immediately. Waiting would mean
+	// sitting through one outage and then starting another.
+	if aclJobLock.TryLock() {
+		aclJobLock.Unlock()
+		t.Fatal("a second ACL job acquired the lock; concurrent windows would corrupt each other")
+	}
+}
+
+// Busy has to be distinguishable from broken: it maps to 409, not 502, so an
+// operator is told to retry rather than sent looking for damage.
+func TestBusyErrorIsIdentifiable(t *testing.T) {
+	wrapped := fmt.Errorf("grant failed: %w", errAclJobBusy)
+	if !errors.Is(wrapped, errAclJobBusy) {
+		t.Error("errAclJobBusy must survive wrapping so respondAclJobError can map it to 409")
+	}
+	if errors.Is(errors.New("k8s exploded"), errAclJobBusy) {
+		t.Error("an unrelated error must not be mistaken for busy")
+	}
+}
diff --git a/internal/k8s/fullstack_names.go b/internal/k8s/fullstack_names.go
index 9f64983..ef67105 100644
--- a/internal/k8s/fullstack_names.go
+++ b/internal/k8s/fullstack_names.go
@@ -61,6 +61,15 @@ func FSJobImportAdminDid(sessionID uint) string {
 	return fmt.Sprintf("fs-%d-import-admin-did", sessionID)
 }
 
+// FSJobVtaACL is the post-provisioning ACL Job — granting a co-admin, revoking
+// one, or just reading the ACL back
+// (docs/platform-stack-admin-grant-design.md §6). Not a pipeline step, and one
+// name for all three operations because they are mutually exclusive in time:
+// each runs with the VTA scaled to 0, so two can never be in flight together,
+// and reusing the name means the previous run's TTL'd Job is what
+// DeleteComponentJob clears before the next.
+func FSJobVtaACL(sessionID uint) string { return fmt.Sprintf("fs-%d-vta-acl", sessionID) }
+
 // full_stack-only Jobs (design §8). FSJobVtcInvite is the reissue
 // endpoint's `vtc admin invite` Job (POST /setup/:id/vtc/reissue-install),
 // not a pipeline step — mirrors how FSJobDidsInvite doubles for reissue.
diff --git a/internal/model/vta_admin_grant.go b/internal/model/vta_admin_grant.go
new file mode 100644
index 0000000..272b09f
--- /dev/null
+++ b/internal/model/vta_admin_grant.go
@@ -0,0 +1,52 @@
+package model
+
+import "time"
+
+// The lifecycle of one grant. Written pending before any Kubernetes work
+// starts, so a client that times out during the maintenance window has not
+// lost the operation — the row is the record, the HTTP response is not. A live
+// pending row is also how a second API replica knows to refuse a concurrent
+// grant, which the in-process lock cannot see across pods.
+//
+// There is deliberately no revoked state: removing an admin is `pnm acl delete`
+// against the live VTA, not something this side does.
+const (
+	GrantPending = "pending"
+	GrantGranted = "granted"
+	GrantFailed  = "failed"
+)
+
+// VtaAdminGrant is one attempt by this farm to put a DID in a stack's VTA ACL
+// as an unrestricted admin — the same authority `step_import_admin_did` gives
+// the stack's first admin (docs/platform-stack-admin-grant-design.md §2).
+//
+// There is no role or contexts field: every grant is unrestricted admin, which
+// is the whole feature. See the migration for why that is a deliberate absence
+// rather than a default.
+//
+// **A row is an event, not a permission.** The DID here is the temporary
+// did:key `pnm setup` minted, and PNM rotates off it on first connect, so this
+// value goes stale by design (§7.2). Nothing on this side tracks where the entry
+// moved to — `pnm acl list` against the running VTA is what answers who can act
+// on it now.
+type VtaAdminGrant struct {
+	ID        uint `json:"-"                      gorm:"primaryKey;autoIncrement"`
+	SessionID uint `json:"-"                      gorm:"column:session_id;not null;index"`
+
+	Did   string `json:"did"   gorm:"not null"`
+	Label string `json:"label" gorm:"not null;default:''"`
+
+	Status   string `json:"status"              gorm:"not null;default:pending"`
+	ErrorMsg string `json:"error_msg,omitempty" gorm:"not null;default:''"`
+
+	// RequestedBy is an admins.id (the admin cookie's JWT carries it as
+	// UserID — admins are their own table). Nullable so the record outlives
+	// the admin who asked for it.
+	RequestedBy *uint      `json:"-"                     gorm:"column:requested_by"`
+	GrantedAt   *time.Time `json:"granted_at,omitempty"`
+
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+func (VtaAdminGrant) TableName() string { return "vta_admin_grants" }
diff --git a/internal/router/router.go b/internal/router/router.go
index 0afa60b..32224a5 100644
--- a/internal/router/router.go
+++ b/internal/router/router.go
@@ -170,6 +170,21 @@ func Setup(
 		// a domains row for our own zone.
 		adminAuth.POST("/admin/platform-stack", sh.CreatePlatformStack)
 		adminAuth.GET("/admin/platform-stack", sh.GetPlatformStack)
+		// Co-admins on that stack's VTA — self-service, so a second admin can
+		// add the did:key their own `pnm setup` minted instead of asking
+		// whoever holds the credential to run `pnm acl create` for them.
+		//
+		// Adding only. Removal is `pnm acl delete` against the live VTA: no
+		// downtime, and it avoids having to work out which ACL entry belongs to
+		// whom, which this side cannot answer well once PNM has rotated keys.
+		//
+		// POST stops the VTA for about a minute and serialises against itself.
+		// Narrowed to the platform stack even though the mechanism is
+		// session-generic: granting unrestricted admin on a *customer's* stack
+		// needs an approval step this doesn't have. See
+		// docs/platform-stack-admin-grant-design.md §1 and §7.4.
+		adminAuth.GET("/admin/platform-stack/admins", sh.ListPlatformStackAdmins)
+		adminAuth.POST("/admin/platform-stack/admins", sh.GrantPlatformStackAdmin)
 		// Cluster capacity overview: CPU/memory/storage totals per node plus
 		// how many more sessions of each mode still fit.
 		dashH := handler.NewDashboardHandler(k8sClient)
diff --git a/migrations/000027_vta_admin_grants.down.sql b/migrations/000027_vta_admin_grants.down.sql
new file mode 100644
index 0000000..01d7ef2
--- /dev/null
+++ b/migrations/000027_vta_admin_grants.down.sql
@@ -0,0 +1,3 @@
+DROP INDEX IF EXISTS vta_admin_grants_session_idx;
+DROP INDEX IF EXISTS vta_admin_grants_live_unique;
+DROP TABLE IF EXISTS vta_admin_grants;
diff --git a/migrations/000027_vta_admin_grants.up.sql b/migrations/000027_vta_admin_grants.up.sql
new file mode 100644
index 0000000..9743671
--- /dev/null
+++ b/migrations/000027_vta_admin_grants.up.sql
@@ -0,0 +1,61 @@
+-- Adding co-admins to a stack's VTA after it is running. Design:
+-- docs/platform-stack-admin-grant-design.md.
+--
+-- Until now the VTA's admin ACL was written exactly once, mid-pipeline, by
+-- step_import_admin_did — and never again, so a second admin could only be added
+-- by whoever already held the stack's credential running `pnm acl create` by
+-- hand. This makes it self-service.
+--
+-- Adding only. Removal stays `pnm acl delete` against the live VTA: no downtime,
+-- and nothing on this side has to work out which ACL entry belongs to whom.
+--
+-- What is recorded is only what was added from here. There is deliberately no
+-- copy of the VTA's own admin list: reading it costs the same maintenance window
+-- as writing it, any copy goes stale the moment a co-admin rotates their key,
+-- and `pnm acl list` answers the live question against the running VTA for free.
+
+-- ── The grants we made ──────────────────────────────────────────────────────
+-- Keyed by session, not by "the platform stack", because the mechanism is
+-- session-generic and only the routes are narrowed to the platform stack
+-- (design §1). Generalising later is a route addition, not a migration.
+--
+-- Deliberately no role or contexts column. Every row is an unrestricted admin —
+-- that IS the feature (design §2): the same `vta import-did --role admin` with
+-- no --context that minted the stack's first admin. A column holding one value
+-- forever is an invitation to put a second value in it without doing the
+-- authorization work that would need.
+CREATE TABLE vta_admin_grants (
+    id           BIGSERIAL   PRIMARY KEY,
+    -- CASCADE: these describe a store that is deleted with the session. There
+    -- is nothing here that outlives it and nothing to orphan.
+    session_id   BIGINT      NOT NULL REFERENCES setup_sessions(id) ON DELETE CASCADE,
+    did          TEXT        NOT NULL,
+    label        TEXT        NOT NULL DEFAULT '',
+    -- pending is written BEFORE the Kubernetes work starts, so an HTTP client
+    -- that times out mid-operation has not lost it: the row is the record, not
+    -- the response body. It is also what a second API replica reads to refuse a
+    -- concurrent grant, which the in-process lock alone cannot cover.
+    --
+    -- There is no 'revoked': removing an admin is `pnm acl delete` against the
+    -- live VTA, not something this side does. See the design doc §1.
+    status       TEXT        NOT NULL DEFAULT 'pending'
+                 CHECK (status IN ('pending', 'granted', 'failed')),
+    error_msg    TEXT        NOT NULL DEFAULT '',
+    -- Which admin asked. SET NULL rather than CASCADE: who was granted access
+    -- is a fact about the VTA, and it must survive the departure of whoever
+    -- requested it. This is the accountability half of accepting that a
+    -- vtafarm admin cookie can now mint a VTA super admin (design §7.4).
+    requested_by BIGINT      NULL REFERENCES admins(id) ON DELETE SET NULL,
+    granted_at   TIMESTAMPTZ NULL,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- One live grant per DID per session. Partial rather than total so a `failed`
+-- attempt stays as history and the same DID can be tried again without
+-- deleting the record of the first try.
+CREATE UNIQUE INDEX vta_admin_grants_live_unique
+    ON vta_admin_grants (session_id, did)
+    WHERE status IN ('pending', 'granted');
+
+CREATE INDEX vta_admin_grants_session_idx ON vta_admin_grants (session_id);