@openparachute/hub 0.6.1-rc.3 → 0.6.1-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.1-rc.3",
+  "version": "0.6.1-rc.4",
   "description": "parachute \u2014 the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/account-home-ui.test.ts

@@ -310,7 +310,9 @@ describe("renderAccountHome", () => {
     expect(html).not.toContain('data-testid="mint-verb-write"');
   });
 
-  test("mint affordance — never offers an admin verb", () => {
+  test("mint affordance — offers the admin verb when the user holds it", () => {
+    // 2026-05-30: assigned users hold read/write/admin on their vault, so the
+    // mint form offers admin (the live `vaultVerbsForUserVault` returns it).
     const html = renderAccountHome({
       username: "alice",
       assignedVaults: ["work"],
@@ -319,10 +321,10 @@ describe("renderAccountHome", () => {
       isFirstAdmin: false,
       csrfToken: CSRF,
       twoFactorEnabled: false,
-      mintableVerbs: { work: ["read", "write"] },
+      mintableVerbs: { work: ["read", "write", "admin"] },
     });
-    expect(html).not.toContain('value="admin"');
-    expect(html).not.toContain('data-testid="mint-verb-admin"');
+    expect(html).toContain('value="admin"');
+    expect(html).toContain('data-testid="mint-verb-admin"');
   });
 
   test("mint affordance — absent when no mintable verbs (admin / no-vault / unmapped role)", () => {

package/src/__tests__/account-vault-token.test.ts

@@ -10,7 +10,8 @@
  *   - UNassigned vault      → 403 (cannot mint for a vault not in the
  *                             user's `user_vaults` assignment — blocks
  *                             cross-vault).
- *   - `admin` verb          → rejected (not in the form vocabulary).
+ *   - `admin` verb          → minted for an ASSIGNED vault (2026-05-30:
+ *                             assigned users hold full vault authority).
  *   - Broader/garbage verb  → rejected.
  *   - First admin           → 403 (no `user_vaults` rows → unrestricted
  *                             admins use the SPA path, not this one).
@@ -245,17 +246,19 @@ describe("handleAccountVaultTokenPost — authorization gates (adversarial)", ()
     expect(res.status).toBe(403);
   });
 
-  test("admin verb is rejected — never mints vault:<name>:admin", async () => {
+  test("200 mints vault:<name>:admin when verb=admin (assigned users hold admin, 2026-05-30)", async () => {
     const { cookie, csrfToken } = await seedFriend(["work"]);
     const res = await handleAccountVaultTokenPost(
       mintReq("work", { cookie, csrfToken, verb: "admin" }),
       "work",
       deps(),
     );
-    expect(res.status).toBe(400);
+    expect(res.status).toBe(200);
     const html = await res.text();
-    expect(html).not.toContain('data-testid="minted-token-banner"');
-    expect(html).not.toContain("vault:work:admin");
+    const token = html.match(/data-testid="minted-token-value">([^<]+)</)?.[1] as string;
+    const validated = await validateAccessToken(harness.db, token, ISSUER);
+    const scopeClaim = (validated.payload as { scope?: string }).scope ?? "";
+    expect(scopeClaim.split(/\s+/)).toEqual(["vault:work:admin"]);
   });
 
   test("a garbage / broader verb is rejected", async () => {

package/src/__tests__/oauth-handlers.test.ts

@@ -8542,12 +8542,12 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
   // Test 9 — privesc: read/write assigned (non-owner) user requests
   // vault:work:admin + vault:work:write → admin DROPPED, token has write only,
   // recorded grant lacks admin.
-  test("[9] non-owner read/write user requests admin+write → admin DROPPED (write only), grant lacks admin", async () => {
+  test("[9] non-owner ASSIGNED to the vault requests admin+write → BOTH granted (assigned users hold admin)", async () => {
     const { db, cleanup } = await makeDb();
     try {
       await createUser(db, "owner", "pw"); // first user = owner; consumes the admin slot.
       const friend = await createUser(db, "friend", "pw", { allowMulti: true });
-      setUserVaults(db, friend.id, ["work"]); // role=write → verbs [read, write]
+      setUserVaults(db, friend.id, ["work"]); // role=write → verbs [read, write, admin]
       const session = createSession(db, { userId: friend.id });
       const reg = registerClient(db, {
         redirectUris: ["https://app.example/cb"],
@@ -8564,20 +8564,20 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
       expect(consentRes.status).toBe(302);
       const code = new URL(consentRes.headers.get("location") ?? "").searchParams.get("code");
       const { scope, aud } = await redeemToScopeAud(db, code ?? "", reg.client.clientId, verifier);
-      // admin dropped; write kept.
-      expect(scope.split(" ").sort()).toEqual(["vault:work:write"]);
+      // Assigned user holds admin on their own vault → BOTH kept (2026-05-30 policy).
+      expect(scope.split(" ").sort()).toEqual(["vault:work:admin", "vault:work:write"]);
       expect(aud).toBe("vault.work");
-      // Recorded grant lacks admin.
+      // Recorded grant includes admin.
       const grant = findGrant(db, friend.id, reg.client.clientId);
       expect(grant?.scopes).toContain("vault:work:write");
-      expect(grant?.scopes).not.toContain("vault:work:admin");
+      expect(grant?.scopes).toContain("vault:work:admin");
     } finally {
       cleanup();
     }
   });
 
   // Test 10 — non-owner admin-ONLY request → REFUSED (clear error), no token.
-  test("[10] non-owner admin-only request → REFUSED with invalid_scope, no token minted", async () => {
+  test("[10] non-owner assigned, admin-only request → GRANTED (holds admin on their vault)", async () => {
     const { db, cleanup } = await makeDb();
     try {
       await createUser(db, "owner", "pw");
@@ -8588,7 +8588,7 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
         redirectUris: ["https://app.example/cb"],
         status: "approved",
       });
-      const { challenge } = makePkce();
+      const { verifier, challenge } = makePkce();
       const consentRes = await submitConsent(
         db,
         session.id,
@@ -8596,14 +8596,17 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
         "vault:work:admin",
         challenge,
       );
-      // Capping leaves an EMPTY scope set → refuse (no zero-scope token).
+      // Assigned user holds admin on their vault → minted, not refused.
       expect(consentRes.status).toBe(302);
       const loc = new URL(consentRes.headers.get("location") ?? "");
       expect(loc.origin + loc.pathname).toBe("https://app.example/cb");
-      expect(loc.searchParams.get("error")).toBe("invalid_scope");
-      expect(loc.searchParams.get("code")).toBeNull();
-      // No grant recorded.
-      expect(findGrant(db, friend.id, reg.client.clientId)).toBeNull();
+      const code = loc.searchParams.get("code");
+      expect(code).toBeTruthy();
+      const { scope, aud } = await redeemToScopeAud(db, code ?? "", reg.client.clientId, verifier);
+      expect(scope.split(" ")).toEqual(["vault:work:admin"]);
+      expect(aud).toBe("vault.work");
+      const grant = findGrant(db, friend.id, reg.client.clientId);
+      expect(grant?.scopes).toContain("vault:work:admin");
     } finally {
       cleanup();
     }
@@ -8611,7 +8614,7 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
 
   // Test 11 — non-owner unnamed vault:admin + picks assigned vault → after
   // narrowing, admin dropped (cap runs post-narrow).
-  test("[11] non-owner unnamed vault:admin + picks assigned vault → admin dropped post-narrow", async () => {
+  test("[11] non-owner unnamed vault:admin + picks assigned vault → admin KEPT post-narrow", async () => {
     const { db, cleanup } = await makeDb();
     try {
       await createUser(db, "owner", "pw");
@@ -8632,16 +8635,16 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
         challenge,
         { vault_pick: "work" },
       );
-      // narrowVaultScopes → vault:work:admin + vault:work:write; cap drops
-      // admin (non-owner doesn't hold it), keeps write → mints write only.
+      // narrowVaultScopes → vault:work:admin + vault:work:write; cap KEEPS
+      // both (assigned user holds admin on their picked vault) → mints both.
       expect(consentRes.status).toBe(302);
       const code = new URL(consentRes.headers.get("location") ?? "").searchParams.get("code");
       expect(code).toBeTruthy();
       const { scope } = await redeemToScopeAud(db, code ?? "", reg.client.clientId, verifier);
-      expect(scope.split(" ").sort()).toEqual(["vault:work:write"]);
+      expect(scope.split(" ").sort()).toEqual(["vault:work:admin", "vault:work:write"]);
       const grant = findGrant(db, friend.id, reg.client.clientId);
       expect(grant?.scopes).toContain("vault:work:write");
-      expect(grant?.scopes).not.toContain("vault:work:admin");
+      expect(grant?.scopes).toContain("vault:work:admin");
     } finally {
       cleanup();
     }
@@ -8770,35 +8773,41 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
   // issueAuthCodeRedirect with an admin scope via ANY path (skip-consent /
   // same-hub / consent). Assert no grants row ever contains an un-held admin
   // verb across each path.
-  test("[15] bypass-proof: no mint path ever records an un-held admin verb for a non-owner", async () => {
+  test("[15] bypass-proof: no mint path grants admin on a vault the user is NOT assigned", async () => {
     const { db, cleanup } = await makeDb();
     try {
       await createUser(db, "owner", "pw");
       const friend = await createUser(db, "friend", "pw", { allowMulti: true });
-      setUserVaults(db, friend.id, ["work"]); // verbs [read, write] only
+      // Assigned to "work" only → holds work:read/write/admin, but NOT "other"
+      // (which exists in CAP_MANIFEST). "other" is the un-held boundary.
+      setUserVaults(db, friend.id, ["work"]);
       const session = createSession(db, { userId: friend.id });
 
-      // Path A — consent-submit with admin+write → admin dropped, recorded grant
-      // lacks admin.
+      // Path A — consent-submit admin on the UNASSIGNED "other" → the cap
+      // empties the set (friend doesn't hold it) → invalid_scope refusal, no
+      // grant. (Granting admin on the user's OWN assigned vault is exercised by
+      // [9]/[10]; here we isolate the un-held boundary.)
       const regConsent = registerClient(db, {
         redirectUris: ["https://app.example/cb"],
         status: "approved",
       });
       {
         const { challenge } = makePkce();
-        await submitConsent(
+        const res = await submitConsent(
           db,
           session.id,
           regConsent.client.clientId,
-          "vault:work:admin vault:work:write",
+          "vault:other:admin",
           challenge,
         );
-        const g = findGrant(db, friend.id, regConsent.client.clientId);
-        expect(g?.scopes ?? []).not.toContain("vault:work:admin");
+        // The consent-submit assignment gate rejects a request naming a vault
+        // the user isn't assigned (400) — refused before any mint, no grant.
+        expect(res.status).toBe(400);
+        expect(findGrant(db, friend.id, regConsent.client.clientId)).toBeNull();
       }
 
-      // Path B — same-hub client requesting admin → consent renders (admin gate
-      // blocks the silent path); no grant recorded with admin.
+      // Path B — same-hub client requesting admin on the UNASSIGNED "other" →
+      // consent renders (admin gate blocks the silent path); no grant with it.
       const regSameHub = registerClient(db, {
         redirectUris: ["https://app.example/cb"],
         status: "approved",
@@ -8815,7 +8824,7 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
               response_type: "code",
               code_challenge: challenge,
               code_challenge_method: "S256",
-              scope: "vault:work:admin",
+              scope: "vault:other:admin",
             }),
             { headers: { cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, TTL_S)}` } },
           ),
@@ -8823,22 +8832,23 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
         );
         expect(res.status).toBe(200); // consent, not silent-mint
         const g = findGrant(db, friend.id, regSameHub.client.clientId);
-        expect(g?.scopes ?? []).not.toContain("vault:work:admin");
+        expect(g?.scopes ?? []).not.toContain("vault:other:admin");
       }
 
-      // Path C — skip-consent: even if a grant row were somehow seeded with an
-      // admin verb, the cap at issueAuthCodeRedirect drops it before minting AND
-      // re-records the capped set. Seed a poisoned grant, drive skip-consent,
-      // and assert the minted token + the (re-recorded) grant carry no admin.
+      // Path C — skip-consent: a grant row seeded with an UNASSIGNED-vault admin
+      // verb. The cap at issueAuthCodeRedirect is the authority, not the grant
+      // row — request only the held write scope (skip-consent fires) and the
+      // minted token carries no other:admin (the un-held verb never rides along).
       const regSkip = registerClient(db, {
         redirectUris: ["https://app.example/cb"],
         status: "approved",
       });
-      recordGrant(db, friend.id, regSkip.client.clientId, ["vault:work:write", "vault:work:admin"]);
+      recordGrant(db, friend.id, regSkip.client.clientId, [
+        "vault:work:write",
+        "vault:other:admin",
+      ]);
       {
         const { verifier, challenge } = makePkce();
-        // Request only the held write scope so skip-consent fires (covered by
-        // the seeded grant) and routes through issueAuthCodeRedirect.
         const res = handleAuthorizeGet(
           db,
           new Request(
@@ -8857,37 +8867,36 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
         expect(res.status).toBe(302); // skip-consent silent mint of the held scope
         const code = new URL(res.headers.get("location") ?? "").searchParams.get("code");
         const { scope } = await redeemToScopeAud(db, code ?? "", regSkip.client.clientId, verifier);
-        expect(scope.split(" ")).not.toContain("vault:work:admin");
+        expect(scope.split(" ")).not.toContain("vault:other:admin");
       }
     } finally {
       cleanup();
     }
   });
 
-  // Reviewer fold (security-relevant): test 15 path C only requested `write`
-  // against the poisoned client, which proves the cap doesn't *re-record* an
-  // un-held verb. This case requests `vault:work:admin` DIRECTLY against a
-  // client whose grant row ALREADY lists `vault:work:admin` (poisoned). The
-  // skip-consent gate fires (the requested admin scope IS covered by the
-  // poisoned grant) and routes through issueAuthCodeRedirect — where the CAP,
-  // not the grant lookup, drops the admin verb. Admin-only request → caps to
-  // EMPTY → invalid_scope refusal, no code, no token. This pins that the
-  // cap-before-issueAuthCode invariant holds even when a stale admin grant
-  // would otherwise satisfy the coverage check.
-  test("[15b] non-owner requests admin DIRECTLY against a POISONED-grant client → cap refuses, no admin token", async () => {
+  // Reviewer fold (security-relevant): test 15 path C only requested the held
+  // `write` scope, proving the cap doesn't re-record an un-held verb. This case
+  // requests admin on the UNASSIGNED "other" vault DIRECTLY against a client
+  // whose grant row already lists `vault:other:admin` (poisoned). The
+  // skip-consent gate fires (the requested scope IS covered by the poisoned
+  // grant) and routes through issueAuthCodeRedirect — where the CAP, not the
+  // grant lookup, drops the un-held verb. Admin-only request → caps to EMPTY →
+  // invalid_scope refusal, no code, no token. Pins that the cap-before-
+  // issueAuthCode invariant holds even when a stale grant satisfies coverage.
+  test("[15b] non-owner requests admin on an UNASSIGNED vault against a POISONED-grant client → cap refuses", async () => {
     const { db, cleanup } = await makeDb();
     try {
       await createUser(db, "owner", "pw");
       const friend = await createUser(db, "friend", "pw", { allowMulti: true });
-      setUserVaults(db, friend.id, ["work"]); // verbs [read, write] only — never admin
+      setUserVaults(db, friend.id, ["work"]); // holds work:* (incl. admin) — NOT "other"
       const session = createSession(db, { userId: friend.id });
       const reg = registerClient(db, {
         redirectUris: ["https://app.example/cb"],
         status: "approved",
       });
-      // Poisoned grant: already lists vault:work:admin (so the skip-consent
-      // coverage check would pass for a direct admin request).
-      recordGrant(db, friend.id, reg.client.clientId, ["vault:work:write", "vault:work:admin"]);
+      // Poisoned grant: already lists vault:other:admin (so the skip-consent
+      // coverage check would pass for a direct other:admin request).
+      recordGrant(db, friend.id, reg.client.clientId, ["vault:work:write", "vault:other:admin"]);
 
       const { challenge } = makePkce();
       const res = handleAuthorizeGet(
@@ -8899,14 +8908,14 @@ describe("single OAuth consent + grantable vault admin + delegate-only cap (2026
             response_type: "code",
             code_challenge: challenge,
             code_challenge_method: "S256",
-            scope: "vault:work:admin",
+            scope: "vault:other:admin",
             state: "poisoned-direct",
           }),
           { headers: { cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, TTL_S)}` } },
         ),
         capDeps,
       );
-      // The cap leaves an EMPTY set (non-owner doesn't hold admin) → refuse.
+      // The cap leaves an EMPTY set (friend isn't assigned "other") → refuse.
       // 302 to redirect_uri with invalid_scope and NO code — no token minted.
       expect(res.status).toBe(302);
       const loc = new URL(res.headers.get("location") ?? "");

package/src/__tests__/users.test.ts

@@ -740,10 +740,13 @@ describe("getFirstAdminId / isFirstAdmin", () => {
 
 describe("vaultVerbsForRole / vaultVerbsForUserVault (friend token-mint cap)", () => {
   test("vaultVerbsForRole maps roles to verbs, fails closed on unknown", () => {
-    expect(vaultVerbsForRole("write")).toEqual(["read", "write"]);
+    // Assigned users (role=write, today's default) hold FULL vault authority
+    // incl. admin (2026-05-30 policy: any assigned user gets admin). A
+    // deliberate read-only assignment stays read-only. Unknown role strings
+    // (including the literal "admin") map to [] — only the recognised roles
+    // grant verbs; never silently default to write.
+    expect(vaultVerbsForRole("write")).toEqual(["read", "write", "admin"]);
     expect(vaultVerbsForRole("read")).toEqual(["read"]);
-    // Unknown / future roles grant NO mintable verb — never silently
-    // default to write. `admin` is explicitly NOT a mintable role here.
     expect(vaultVerbsForRole("admin")).toEqual([]);
     expect(vaultVerbsForRole("owner")).toEqual([]);
     expect(vaultVerbsForRole("")).toEqual([]);
@@ -757,8 +760,9 @@ describe("vaultVerbsForRole / vaultVerbsForUserVault (friend token-mint cap)", (
         allowMulti: true,
         assignedVaults: ["work"],
       });
-      // createUser/setUserVaults insert role='write' today → read+write.
-      expect(vaultVerbsForUserVault(db, friend.id, "work")).toEqual(["read", "write"]);
+      // createUser/setUserVaults insert role='write' today → read+write+admin
+      // (assigned users hold full vault authority, 2026-05-30 policy).
+      expect(vaultVerbsForUserVault(db, friend.id, "work")).toEqual(["read", "write", "admin"]);
     } finally {
       cleanup();
     }

package/src/account-home-ui.ts

@@ -384,7 +384,12 @@ function renderTokenMintBlock(
   const radios = verbs
     .map((verb, i) => {
       const checked = i === 0 ? " checked" : "";
-      const label = verb === "read" ? "Read-only" : "Read + write";
+      const label =
+        verb === "read"
+          ? "Read-only"
+          : verb === "admin"
+            ? "Full (read, write, rotate tokens + config)"
+            : "Read + write";
       return `
               <label class="mint-verb-option">
                 <input type="radio" name="verb" value="${verb}"${checked}

package/src/account-vault-token.ts

@@ -21,12 +21,10 @@
  *      `vaultVerbsForUserVault` (which returns `null` for an unassigned
  *      vault), NOT from the verb-blind `assignedVaults` array.
  *   3. **Scope cap.** The requested verb MUST be one the user's assignment
- *      role permits, and may only ever be `read` or `write` — NEVER `admin`,
- *      never a broader scope than the user holds. `vaultVerbsForUserVault`
- *      returns the role's verb set (today always `["read", "write"]` since
- *      every assignment is `role = 'write'`); a verb outside that set → 403.
- *      `admin` is not in the form's vocabulary at all and is rejected at the
- *      parse step as an invalid verb.
+ *      role permits. As of 2026-05-30 an assigned user holds the full set
+ *      `["read", "write", "admin"]` on their vault (`vaultVerbsForUserVault`),
+ *      so this surface mints admin tokens too — consistent with the OAuth
+ *      flow. A verb outside the held set, or for an unassigned vault, → 403.
  *
  * The first admin (unrestricted, empty `assignedVaults`) has no `user_vaults`
  * rows, so gate 2 returns `null` for every vault and the admin gets a 403
@@ -81,7 +79,7 @@ import { type VaultVerb, getUserById, isFirstAdmin, vaultVerbsForUserVault } fro
 /** Matches the manifest vault-name validator + `/admin/vault-admin-token`. */
 const VAULT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
 /** Verbs this surface will ever mint. `admin` is deliberately absent. */
-const ALLOWED_VERBS: readonly VaultVerb[] = ["read", "write"];
+const ALLOWED_VERBS: readonly VaultVerb[] = ["read", "write", "admin"];
 /** client_id stamped on the minted JWT + registry row. */
 const ACCOUNT_VAULT_TOKEN_CLIENT_ID = "parachute-account";
 
@@ -199,14 +197,15 @@ export async function handleAccountVaultTokenPost(
     return renderHome(400, { mintError: `"${vaultName}" is not a valid vault name.` });
   }
 
-  // Verb parse — must be exactly one of read/write. `admin` (or anything
-  // else) is not in this surface's vocabulary and is rejected here, well
-  // before authority is even consulted.
+  // Verb parse — must be one of read/write/admin (this surface's vocabulary).
+  // Anything else is rejected here, well before authority is even consulted;
+  // the per-vault authority cap (gate 3 below) then drops verbs the user
+  // doesn't actually hold.
   const verbRaw = form.get("verb");
   const verb = typeof verbRaw === "string" ? verbRaw : "";
   if (!ALLOWED_VERBS.includes(verb as VaultVerb)) {
     return renderHome(400, {
-      mintError: "Pick an access level (read or write).",
+      mintError: "Pick an access level (read, write, or admin).",
     });
   }
   const requestedVerb = verb as VaultVerb;
@@ -217,9 +216,11 @@ export async function handleAccountVaultTokenPost(
   //             (fail-closed for an unknown role): 403.
   //   - [...] → the verbs the assignment role permits. The requested verb
   //             must be in this set (gate 3): else 403.
-  // This is the cap to the user's actual authority — it blocks minting for
-  // an unassigned vault, a broader verb than the role grants, and (since the
-  // set never contains `admin`) any admin escalation.
+  // This is the cap to the user's actual authority — it blocks minting for an
+  // unassigned vault or a verb the role doesn't grant. Assigned users hold
+  // read/write/admin on their vault (2026-05-30), so admin mints for an
+  // assigned vault; the cap still refuses admin (and everything else) for a
+  // vault the user isn't assigned (`allowedForUser === null`).
   const allowedForUser = vaultVerbsForUserVault(deps.db, user.id, vaultName);
   if (allowedForUser === null) {
     return renderHome(403, {

package/src/oauth-handlers.ts

@@ -1193,12 +1193,14 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
  *   - The authority source of truth today is `isFirstAdmin` for owner-wide
  *     authority and `user_vaults.role` (via `vaultVerbsForRole`) for assigned
  *     users.
- *   - `vaultVerbsForRole` provably never returns `admin` for an assigned user
- *     (it maps write→[read,write], read→[read], unknown→[]), so this helper
- *     drops `vault:<name>:admin` for every non-owner BY CONSTRUCTION — without
- *     hardcoding "drop admin". It reads the held verb set and admits only
- *     held verbs, so it's forward-compatible: if a future role ever granted
- *     admin, the cap would admit it automatically.
+ *   - `vaultVerbsForRole` maps write→[read,write,admin] (2026-05-30: any
+ *     assigned user holds FULL vault authority, incl. admin), read→[read],
+ *     unknown→[]. This helper reads the held verb set and admits ONLY held
+ *     verbs — no hardcoded allow/deny of admin. So an assigned user gets
+ *     `vault:<their-vault>:admin`, while a user gets NOTHING for a vault they
+ *     aren't assigned (held=null → every verb dropped). The cap is the
+ *     forward-compatible single source: it admitted admin automatically the
+ *     moment the role mapping changed — no edit here was needed.
  *   - Applied inside `issueAuthCodeRedirect` (the single choke-point ALL mint
  *     paths funnel through: consent-submit, skip-consent, and same-hub
  *     auto-trust), the CAPPED set is what gets both recorded (`recordGrant`)

package/src/scope-explanations.ts

@@ -152,10 +152,13 @@ export const NON_REQUESTABLE_SCOPES: ReadonlySet<string> = new Set([
  * enforced at the shared mint choke-point (`capScopesToUserAuthority` applied
  * inside `issueAuthCodeRedirect` in `oauth-handlers.ts`): an OAuth flow caps
  * named vault verbs to those the consenting user actually holds on that vault.
- * `vaultVerbsForRole` never returns `admin` for an assigned (read/write) user,
- * so admin is dropped for everyone except the hub owner (isFirstAdmin) — who
- * holds admin everywhere by construction. An admin-only request from a
- * non-owner is refused outright (never minted as a zero-scope token).
+ * `vaultVerbsForRole` returns admin for an assigned user (2026-05-30: any
+ * assigned user holds full vault authority on their own vault), so a non-owner
+ * can delegate `vault:<their-vault>:admin` to their client. The cap still
+ * drops admin (and every verb) for a vault the user is NOT assigned to
+ * (held=null), and an admin-only request the cap empties is refused outright
+ * (never minted as a zero-scope token). The hub owner (isFirstAdmin) holds
+ * admin everywhere by construction.
  *
  * `vault:<name>:admin` also remains mintable by operator-proving local paths,
  * all of which require already-established authority:

package/src/users.ts

@@ -146,30 +146,37 @@ function readVaultsForUser(db: Database, userId: string): string[] {
 
 /**
  * The per-vault verbs a `user_vaults.role` grants. The schema's `role`
- * column is `TEXT NOT NULL DEFAULT 'write'` and is reserved forward-compat
- * for per-vault role granularity (see the v10 migration note in
- * `hub-db.ts`). Today every assignment is created with `role = 'write'`, so
- * the only live mapping is `write → {read, write}`. The function is the
- * single place the verb-cap lives so a future role taxonomy (`read`-only,
- * `admin`, etc.) lands here without the friend-mint path having to change.
+ * column is `TEXT NOT NULL DEFAULT 'write'`; today every assignment is created
+ * with `role = 'write'`. This is the single place the verb-cap lives, so the
+ * OAuth mint cap (`capScopesToUserAuthority`) and the `/account` mint UI both
+ * read authority from here.
+ *
+ * **Assigned users hold FULL vault authority (read + write + admin)** as of
+ * 2026-05-30 (Aaron's call: "any assigned user gets admin"). The point of the
+ * multi-user flow is that someone given a vault — owned or shared — can connect
+ * their own client (e.g. Claude MCP) to it and grant everything they'd want,
+ * including `vault:<name>:admin` (token creation + config). Owner-vs-shared is
+ * NOT distinguished today; a shared user gets admin too (explicit trade-off).
  *
  * Mapping:
- *   - `write` (today's only value)  → `["read", "write"]`
- *   - `read`                        → `["read"]`
+ *   - `write` (today's default)     → `["read", "write", "admin"]`
+ *   - `read` (forward-compat)       → `["read"]` — a *deliberate* read-only
+ *     assignment stays read-only even under the any-assigned-user-gets-admin
+ *     policy. Not created by any flow today.
  *   - anything else (unknown role)  → `[]` — fail closed. An unrecognised
  *     role grants no minting authority rather than silently defaulting to
  *     write. (Defense-in-depth: a hand-edited / future row with a role this
- *     code doesn't understand should not be treated as broad write.)
+ *     code doesn't understand should not be treated as broad.)
  *
- * `admin` is intentionally NOT mapped to a `vault:<name>:admin` mint here —
- * the friend-facing token mint is capped at read/write by design. A
- * future per-vault-admin friend grant would route through the
- * vault-admin-token path, not this one.
+ * Scope of the widening: this only affects `vault:<name>:<verb>` for vaults
+ * the user is assigned. Hub-level admin (`hub:admin`) + host operator scopes
+ * (`parachute:host:*`) are NOT vault scopes and remain ungrantable by
+ * non-admins — the cap's named-vault branch is the only thing this touches.
  */
-export type VaultVerb = "read" | "write";
+export type VaultVerb = "read" | "write" | "admin";
 
 export function vaultVerbsForRole(role: string): VaultVerb[] {
-  if (role === "write") return ["read", "write"];
+  if (role === "write") return ["read", "write", "admin"];
   if (role === "read") return ["read"];
   return [];
 }