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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.1-rc.2",
+  "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

@@ -95,7 +95,10 @@ function fixtureLoadServicesManifest(): ServicesManifest {
 
 describe("authorizationServerMetadata", () => {
   test("emits RFC 8414 fields rooted at the issuer", async () => {
-    const res = authorizationServerMetadata({ issuer: ISSUER });
+    const res = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadServicesManifest: fixtureLoadServicesManifest,
+    });
     expect(res.status).toBe(200);
     const body = (await res.json()) as Record<string, unknown>;
     expect(body.issuer).toBe(ISSUER);
@@ -110,15 +113,21 @@ describe("authorizationServerMetadata", () => {
     const scopesSupported = body.scopes_supported as string[];
     expect(scopesSupported).toContain("vault:read");
     expect(scopesSupported).toContain("vault:admin");
-    expect(scopesSupported).toContain("scribe:transcribe");
+    expect(scopesSupported).toContain("scribe:transcribe"); // scribe is in the fixture manifest
     expect(scopesSupported).toContain("hub:admin");
+    // channel isn't in the fixture manifest → its scopes aren't advertised
+    // (hub#…: optional-module scopes only surface when the module is installed).
+    expect(scopesSupported).not.toContain("channel:send");
   });
 
   test("does NOT advertise non-requestable operator-only scopes", async () => {
     // #96: parachute:host:admin is operator-only. RFC 8414 §2 frames
     // scopes_supported as scopes a client *can* request — advertising what
     // we always reject would mislead clients.
-    const res = authorizationServerMetadata({ issuer: ISSUER });
+    const res = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadServicesManifest: fixtureLoadServicesManifest,
+    });
     const body = (await res.json()) as Record<string, unknown>;
     const scopesSupported = body.scopes_supported as string[];
     expect(scopesSupported).not.toContain("parachute:host:admin");
@@ -143,6 +152,7 @@ describe("authorizationServerMetadata", () => {
     const res = authorizationServerMetadata({
       issuer: ISSUER,
       loadDeclaredScopes: () => declared,
+      loadServicesManifest: fixtureLoadServicesManifest,
     });
     const body = (await res.json()) as Record<string, unknown>;
     const scopesSupported = body.scopes_supported as string[];
@@ -157,11 +167,84 @@ describe("authorizationServerMetadata", () => {
     // NON_REQUESTABLE filter still applies even when the scope is declared
     expect(scopesSupported).not.toContain("parachute:host:admin");
   });
+
+  test("advertises an optional module's scopes only when it's installed", async () => {
+    // FIRST_PARTY_SCOPES carries scribe:* + channel:send statically. On a
+    // vault-only hub they must NOT be advertised — a discovery client (e.g.
+    // claude.ai's connector UI) lists the catalog verbatim, so a friend
+    // connecting one vault was shown Scribe + Channel access the hub can't
+    // honor. Vault + hub are core and always advertised.
+    const declared = new Set<string>([
+      "vault:read",
+      "vault:write",
+      "vault:admin",
+      "scribe:transcribe",
+      "scribe:admin",
+      "channel:send",
+      "hub:admin",
+    ]);
+    const vaultOnly = {
+      services: [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/health",
+          version: "0.5.1",
+        },
+      ],
+    };
+    const res = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadDeclaredScopes: () => declared,
+      loadServicesManifest: () => vaultOnly as unknown as ServicesManifest,
+    });
+    const scopes = ((await res.json()) as Record<string, unknown>).scopes_supported as string[];
+    // core scopes survive
+    expect(scopes).toContain("vault:read");
+    expect(scopes).toContain("vault:admin");
+    expect(scopes).toContain("hub:admin");
+    // uninstalled optional-module scopes are dropped
+    expect(scopes).not.toContain("scribe:transcribe");
+    expect(scopes).not.toContain("scribe:admin");
+    expect(scopes).not.toContain("channel:send");
+
+    // ...but once scribe is installed, its scopes ARE advertised again.
+    const withScribe = {
+      services: [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/health",
+          version: "0.5.1",
+        },
+        {
+          name: "parachute-scribe",
+          port: 1943,
+          paths: ["/scribe"],
+          health: "/health",
+          version: "0.4.5",
+        },
+      ],
+    };
+    const res2 = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadDeclaredScopes: () => declared,
+      loadServicesManifest: () => withScribe as unknown as ServicesManifest,
+    });
+    const scopes2 = ((await res2.json()) as Record<string, unknown>).scopes_supported as string[];
+    expect(scopes2).toContain("scribe:transcribe");
+    expect(scopes2).not.toContain("channel:send"); // channel still not installed
+  });
 });
 
 describe("protectedResourceMetadata (RFC 9728, closes hub#393)", () => {
   test("emits the required RFC 9728 fields rooted at the issuer", async () => {
-    const res = protectedResourceMetadata({ issuer: ISSUER });
+    const res = protectedResourceMetadata({
+      issuer: ISSUER,
+      loadServicesManifest: fixtureLoadServicesManifest,
+    });
     expect(res.status).toBe(200);
     expect(res.headers.get("content-type")).toMatch(/application\/json/);
     const body = (await res.json()) as Record<string, unknown>;
@@ -185,6 +268,7 @@ describe("protectedResourceMetadata (RFC 9728, closes hub#393)", () => {
     const res = protectedResourceMetadata({
       issuer: ISSUER,
       loadDeclaredScopes: () => declared,
+      loadServicesManifest: fixtureLoadServicesManifest,
     });
     const body = (await res.json()) as Record<string, unknown>;
     const scopes = body.scopes_supported as string[];
@@ -3904,7 +3988,10 @@ describe("refresh-token rotation + /oauth/revoke (#73)", () => {
   });
 
   test("authorizationServerMetadata advertises revocation_endpoint", async () => {
-    const res = authorizationServerMetadata({ issuer: ISSUER });
+    const res = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadServicesManifest: fixtureLoadServicesManifest,
+    });
     const body = (await res.json()) as Record<string, unknown>;
     expect(body.revocation_endpoint).toBe(`${ISSUER}/oauth/revoke`);
   });
@@ -8455,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"],
@@ -8477,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");
@@ -8501,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,
@@ -8509,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();
     }
@@ -8524,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");
@@ -8545,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();
     }
@@ -8683,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",
@@ -8728,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)}` } },
           ),
@@ -8736,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(
@@ -8770,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(
@@ -8812,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

@@ -388,13 +388,53 @@ function oauthErrorRedirect(
  *
  * Closes hub#393.
  */
+
+/**
+ * Optional first-party modules whose scopes `FIRST_PARTY_SCOPES` carries
+ * statically (it's `Object.keys(SCOPE_EXPLANATIONS)`), paired with the
+ * services.json entry that means "installed." Vault + hub are core and always
+ * advertised; these are the modules a hub may not have.
+ */
+const OPTIONAL_MODULE_SCOPES: ReadonlyArray<readonly [prefix: string, service: string]> = [
+  ["scribe:", "parachute-scribe"],
+  ["channel:", "parachute-channel"],
+];
+
+/**
+ * The scope set to advertise in `scopes_supported` (RFC 8414 + RFC 9728): the
+ * requestable declared scopes, minus any OPTIONAL module's scopes when that
+ * module isn't installed.
+ *
+ * Why: `FIRST_PARTY_SCOPES` is static, so a vault-only hub still advertised
+ * `scribe:*` + `channel:send`. Discovery clients list the advertised catalog
+ * verbatim — claude.ai's connector UI showed a friend connecting ONE vault a
+ * request for Scribe + Channel access the hub can't even honor. So advertise an
+ * optional module's scopes only when its service is present in services.json.
+ * (Trims the ADVERTISEMENT only; issuance/validation still use the full
+ * `loadDeclaredScopes` set, and the per-vault PRM stays vault-narrowed.)
+ */
+function advertisedScopes(declared: ReadonlySet<string>, manifest: ServicesManifest): string[] {
+  const installed = new Set(manifest.services.map((s) => s.name));
+  return Array.from(declared)
+    .filter(isRequestableScope)
+    .filter((scope) => {
+      for (const [prefix, service] of OPTIONAL_MODULE_SCOPES) {
+        if (scope.startsWith(prefix) && !installed.has(service)) return false;
+      }
+      return true;
+    });
+}
+
 export function protectedResourceMetadata(deps: OAuthDeps): Response {
   const iss = deps.issuer;
   const declared = (deps.loadDeclaredScopes ?? loadDeclaredScopes)();
   return jsonResponse({
     resource: iss,
     authorization_servers: [iss],
-    scopes_supported: Array.from(declared).filter(isRequestableScope),
+    scopes_supported: advertisedScopes(
+      declared,
+      (deps.loadServicesManifest ?? readServicesManifest)(),
+    ),
     bearer_methods_supported: ["header"],
     resource_documentation: "https://parachute.computer",
     // Intentional omission: `resource_signing_alg_values_supported` +
@@ -435,7 +475,10 @@ export function authorizationServerMetadata(deps: OAuthDeps): Response {
     // — RFC 8414 §2 frames `scopes_supported` as "the OAuth 2.0 [...] scope
     // values that this authorization server supports" for clients to request.
     // Advertising what we always reject would mislead clients.
-    scopes_supported: Array.from(declared).filter(isRequestableScope),
+    scopes_supported: advertisedScopes(
+      declared,
+      (deps.loadServicesManifest ?? readServicesManifest)(),
+    ),
   });
 }
 
@@ -1150,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

@@ -45,6 +45,12 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
     label: "Full vault access plus configuration changes (rotate tokens, change settings).",
     level: "admin",
   },
+  // Optional-module scopes (scribe / channel). These are in FIRST_PARTY_SCOPES
+  // (= Object.keys(this map)) but the modules may not be installed — so they're
+  // GATED in `OPTIONAL_MODULE_SCOPES` (oauth-handlers.ts) and only advertised in
+  // `scopes_supported` when the service is in services.json. If you add scopes
+  // for another optional module here, add a matching gate there too, or a
+  // vault-only hub will over-advertise them (the bug behind hub#489).
   "scribe:transcribe": {
     label: "Send audio to Scribe for transcription.",
     level: "write",
@@ -146,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 [];
 }