@openparachute/hub 0.5.13 → 0.5.14-rc.10

package/src/oauth-handlers.ts

@@ -66,6 +66,7 @@ import {
 } from "./oauth-ui.ts";
 import { isSameOriginRequest } from "./origin-check.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
+import { narrowResourceVaultScopes, resolveResourceVault } from "./resource-binding.ts";
 import { isNonRequestableScope, isRequestableScope, scopeIsAdmin } from "./scope-explanations.ts";
 import { findUnknownScopes, loadDeclaredScopes } from "./scope-registry.ts";
 import {
@@ -83,7 +84,7 @@ import {
   findSession,
   parseSessionCookie,
 } from "./sessions.ts";
-import { getUserById, getUserByUsername, verifyPassword } from "./users.ts";
+import { getUserById, getUserByUsername, isFirstAdmin, verifyPassword } from "./users.ts";
 import { listVaultNames } from "./vault-names.ts";
 import { isVaultEntry, shortName, vaultInstanceNameFor } from "./well-known.ts";
 
@@ -114,30 +115,35 @@ function narrowVaultScopes(scopes: string[], pickedVault: string): string[] {
 
 /**
  * Derive the `vault_scope` claim value for a given hub user. Multi-user
- * Phase 1 (design
- * [`2026-05-20-multi-user-phase-1.md`](https://parachute.computer/design/2026-05-20-multi-user-phase-1/),
- * §oauth-claim-shape).
+ * Phase 2 PR 2 (design 2026-05-20-multi-user-phase-1.md §Phase 2 —
+ * many-to-many membership via the `user_vaults` table).
  *
  *   - `userId` resolves to no row → `[]`. Defensive: the caller already
  *     validated the user existed (auth-code redemption / refresh row's
- *     user_id), but a delete-between-mint-and-now race shouldn't 500. Empty
- *     is the safe sentinel — the scope-bearing `scope` claim is still the
- *     gate.
- *   - User exists with `assignedVault === null` → `[]`. Admin / unpinned
- *     posture; the consent picker is the source of truth.
- *   - User exists with `assignedVault === "name"` → `["name"]`. The Phase 1
- *     single-vault pin; PR 5's scope-guard at vault/notes/scribe consumes
- *     this to enforce that an assigned user can't request scope against any
- *     vault other than their assigned one.
+ *     user_id), but a delete-between-mint-and-now race shouldn't 500.
+ *     Empty is the safe sentinel — the scope-bearing `scope` claim is
+ *     still the gate.
+ *   - First admin → `[]`. Admin posture is unrestricted by design (see
+ *     `isFirstAdmin`). The consent picker is the source of truth and
+ *     the scope-guard reads an empty `vault_scope` claim as "no
+ *     narrowing" — first admin can request scope against any vault.
+ *   - Non-admin user → the list of vault names from `user_vaults`. The
+ *     scope-guard at vault/notes/scribe enforces that the user can
+ *     only request scope against vaults in their list (Phase 1 pinned
+ *     to a single vault; Phase 2 lifts that to N). A non-admin with
+ *     zero assignments returns `[]` — distinct semantics from the
+ *     admin's `[]` because the consent picker plus the picked-must-
+ *     match-assignment defense in `handleConsentSubmit` enforces that
+ *     non-admin tokens carry a non-empty `vault_scope`.
  *
  * Always returns an array (never undefined) so the JWT carries the claim
  * unconditionally — readers don't have to distinguish "absent" from "empty."
  */
 export function vaultScopeForUser(db: Database, userId: string): string[] {
+  if (isFirstAdmin(db, userId)) return [];
   const user = getUserById(db, userId);
   if (!user) return [];
-  if (user.assignedVault === null) return [];
-  return [user.assignedVault];
+  return [...user.assignedVaults];
 }
 
 export interface OAuthDeps {
@@ -455,6 +461,9 @@ function parseAuthorizeFormParams(url: URL): AuthorizeFormParams | { error: stri
     codeChallenge,
     codeChallengeMethod,
     state: url.searchParams.get("state"),
+    // RFC 8707 resource indicator (optional). When present and resolvable to
+    // a per-vault MCP resource, drives the narrow-consent + named-scope path.
+    resource: url.searchParams.get("resource"),
   };
 }
 
@@ -839,6 +848,41 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     );
   }
 
+  // RFC 8707 resource binding. When the client named a per-vault MCP
+  // resource (`<origin>/vault/<name>/mcp` or its PRM URL), narrow the
+  // requested vault verbs to the named `vault:<name>:<verb>` form BEFORE any
+  // downstream processing. Two effects:
+  //
+  //   1. The consent screen shows ONLY that vault's scopes (the picker locks
+  //      to <name>) instead of the whole-hub catalog — a friend connecting to
+  //      one vault no longer sees `hub:admin`, `scribe:admin`, or every other
+  //      vault's verbs.
+  //   2. The minted token carries the named scope, so `inferAudience` stamps
+  //      `aud=vault.<name>` and a current-line vault accepts it (an unnamed
+  //      `vault:read` token is rejected by `findBroadVaultScopes`).
+  //
+  // Narrowing happens before the non-requestable gate (below) on purpose: if
+  // a resource-bound client somehow asked for `vault:admin`, narrowing makes
+  // it `vault:<name>:admin`, which IS non-requestable — so the gate correctly
+  // blocks it. Read/write narrow to the requestable named form. Non-vault
+  // scopes and already-named scopes for other vaults pass through unchanged.
+  //
+  // No resource, or a resource that isn't one of our per-vault MCP resources
+  // (off-origin, malformed, non-vault path) → `boundVault` is null and the
+  // flow is byte-for-byte the pre-#461 behavior (manual picker, etc.).
+  const boundVault = resolveResourceVault(parsed.resource, resolveBoundOrigins(deps));
+  if (boundVault) {
+    const narrowed = narrowResourceVaultScopes(
+      parsed.scope.split(" ").filter((s) => s.length > 0),
+      boundVault,
+    );
+    // Rewrite `parsed.scope` so the narrowed named scopes flow through every
+    // downstream consumer: the login-redirect query round-trip, the consent
+    // props + hidden inputs, the skip-consent grant lookup, and the
+    // auth-code mint.
+    parsed.scope = narrowed.join(" ");
+  }
+
   // Operator-only scope gate (#96). Reject any request that names a scope
   // we'll never mint via this flow — `parachute:host:admin` and friends.
   // Per RFC 6749 §4.1.2.1, errors that aren't redirect-uri-related are
@@ -862,12 +906,20 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     return htmlResponse(renderLogin({ params: parsed, csrfToken: csrf.token }), 200, extra);
   }
 
-  // Multi-user Phase 1: non-admin users (with `assigned_vault !== null`) see
-  // the picker locked to their assigned vault — they can't pick a different
-  // one. Admin users (assigned_vault === null) see the full dropdown.
-  // Defensive null-coalesce: the session points at a deleted user shouldn't
-  // 500; treat as admin posture (the broader scope-validation gate will
-  // catch any actual privilege issue).
+  // Multi-user Phase 2 PR 2: non-admin users see the picker narrowed to
+  // their assigned vault list — they can't pick a vault they don't own.
+  // First admin (admin posture) sees the full dropdown of every vault on
+  // the hub.
+  //
+  // Two shapes for non-admin users emerge:
+  //   - exactly one assigned vault → picker renders locked to that name
+  //     (same shape as Phase 1; smallest diff for the common case).
+  //   - two or more assigned vaults → picker renders a free dropdown
+  //     filtered to those names — user picks one per consent.
+  //
+  // Defensive null-coalesce: the session points at a deleted user
+  // shouldn't 500; treat as admin posture (the broader scope-validation
+  // gate will catch any actual privilege issue).
   //
   // Resolved here (before the fast-paths) because the stale-assignment
   // predicate below — which gates both skip-consent (#75) and same-hub
@@ -876,24 +928,28 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
   // closing the silent-mint-on-stale-vault gap; the read is one JSON parse
   // off-disk per /authorize.
   const user = getUserById(db, session.userId);
-  const lockedVault = user?.assignedVault ?? null;
+  const userIsAdmin = isFirstAdmin(db, session.userId);
+  // Non-admin user's assigned vaults; admin posture (or no row) → empty.
+  const assignedVaults: string[] = userIsAdmin ? [] : (user?.assignedVaults ?? []);
   const manifest = (deps.loadServicesManifest ?? readServicesManifest)();
   const vaultNames = listVaultNames(manifest);
 
-  // Stale-assignment predicate (hub#284 reviewer fold). The user has an
-  // `assigned_vault` pinned on their row but the named vault is no longer
-  // in services.json. Both fast-paths below (#75 skip-consent, hub#312
-  // same-hub auto-trust) would otherwise silently mint a token for a vault
-  // that doesn't exist — the user thinks consent succeeded but the
-  // downstream API calls fail with no actionable signal. Fall through to
-  // the consent render in either case so the banner UX (and the disabled
-  // Approve when the requested scope depends on a vault) surfaces the
-  // condition + admin-remediation path. Admin users (`lockedVault === null`)
-  // are never stale.
-  const hasStaleAssignment = lockedVault !== null && !vaultNames.includes(lockedVault);
+  // Stale-assignment predicate (hub#284, generalized in Phase 2 PR 2 from
+  // single-vault to N-vault). For a non-admin user, "stale" means at
+  // least one of their assigned vaults no longer exists in services.json
+  // AND no vault in their list still exists — i.e. they have *zero*
+  // valid vaults to consent against. The banner surfaces this state with
+  // an admin-remediation hint instead of silently minting a token
+  // against a missing vault. If at least one of their vaults still
+  // exists, the consent flow proceeds normally — the missing ones drop
+  // out of the picker without ceremony.
+  //
+  // Admin users are never stale (they aren't pinned to any vault list).
+  const remainingValidVaults = assignedVaults.filter((v) => vaultNames.includes(v));
+  const hasStaleAssignment = assignedVaults.length > 0 && remainingValidVaults.length === 0;
 
   // Skip-consent gate (#75). If the user has previously granted every
-  // requested scope to this client, mint the auth code immediately. Two
+  // requested scope to this client, mint the auth code immediately. Three
   // important constraints:
   //   - Unnamed vault verbs (`vault:read`) need the picker even if a prior
   //     grant exists, because the operator's vault choice isn't recorded
@@ -905,10 +961,25 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
   //   - Stale-assignment (above) also forces the consent render so the
   //     banner explains the broken state rather than silently minting a
   //     token against the missing vault.
+  //   - The user is admin OR has at least one assigned vault (hub#429
+  //     reviewer fold, follow-up). A zero-vault non-admin whose prior
+  //     grants survived a `setUserVaults(_, [])` admin action would
+  //     otherwise silently re-mint a token against the now-revoked
+  //     vault assignment — the grants table has no FK cascade from
+  //     `user_vaults`, so deleting assignments doesn't revoke grants.
+  //     Same privesc shape as the same-hub auto-trust gate below;
+  //     identical guard (`userHasVaultPosture`). Force fall-through to
+  //     the consent render where the zero-vault gate in
+  //     `handleConsentSubmit` also refuses (defense in depth). This
+  //     also transitively defends the trust-by-client_name auto-
+  //     promote path (~line 554) which recursively re-enters
+  //     `handleAuthorizeGet` after promoting the pending client.
   const hasUnnamedVault = unnamedVaultVerbs(requestedScopes).length > 0;
+  const userHasVaultPosture = userIsAdmin || assignedVaults.length > 0;
   if (
     !hasStaleAssignment &&
     !hasUnnamedVault &&
+    userHasVaultPosture &&
     isCoveredByGrant(db, session.userId, client.clientId, requestedScopes)
   ) {
     console.log(
@@ -931,16 +1002,31 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
   //      still want explicit consent as a sanity gate.
   //   3. No unnamed vault verbs are requested — those need the picker to
   //      narrow `vault:<verb>` → `vault:<name>:<verb>` before mint.
-  //   4. The user's assigned_vault is not stale (hub#284 reviewer fold) —
-  //      otherwise the same-hub gate would silently mint a token for a
-  //      removed vault before the consent-render path's stale detection
-  //      ever runs.
+  //   4. The user's assigned_vaults list is not stale (hub#284 reviewer
+  //      fold) — otherwise the same-hub gate would silently mint a token
+  //      for a removed vault before the consent-render path's stale
+  //      detection ever runs.
+  //   5. The user is admin OR has at least one assigned vault (Phase 2
+  //      PR 2 reviewer fold). A zero-vault non-admin has
+  //      `hasStaleAssignment=false` (length===0 short-circuits the stale
+  //      predicate above) and would otherwise sail through the auto-
+  //      trust gate. The resulting `vault_scope: []` claim is the admin
+  //      "unrestricted" sentinel — minting it for a non-admin grants
+  //      hub-wide vault access. Force fall-through to the consent
+  //      render where the zero-vault gate in `handleConsentSubmit` also
+  //      refuses (defense in depth).
   //
   // The grant is also recorded so subsequent flows with the same scopes
   // hit the standard skip-consent gate above. Logged so an operator
   // auditing "who did this" can trace it back to a same-hub DCR.
   const hasAdminScope = requestedScopes.some(scopeIsAdmin);
-  if (client.sameHub && !hasAdminScope && !hasUnnamedVault && !hasStaleAssignment) {
+  if (
+    client.sameHub &&
+    !hasAdminScope &&
+    !hasUnnamedVault &&
+    !hasStaleAssignment &&
+    userHasVaultPosture
+  ) {
     console.log(
       `[oauth] auto-approved same-hub client client_id=${client.clientId} user_id=${session.userId} scopes=${requestedScopes.join(" ")} (hub#312)`,
     );
@@ -952,7 +1038,9 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
   }
 
   return htmlResponse(
-    renderConsent(consentProps(client, parsed, vaultNames, csrf.token, lockedVault)),
+    renderConsent(
+      consentProps(client, parsed, vaultNames, csrf.token, assignedVaults, userIsAdmin),
+    ),
     200,
     extra,
   );
@@ -1072,6 +1160,21 @@ async function handleConsentSubmit(
   csrfToken: string,
 ): Promise<Response> {
   const params = paramsFromForm(form);
+  // RFC 8707 resource binding — defense-in-depth (mirror of the GET handler).
+  // The consent form's hidden inputs already carry the narrowed named scopes
+  // (the GET handler rewrote `parsed.scope` before rendering), but a hand-
+  // crafted POST could re-supply an unnamed `vault:read` alongside the
+  // `resource` field. Re-narrow here so the minted token is always named +
+  // correctly-audienced regardless of what the form body claims. Same
+  // semantics as the GET path: only when `resource` resolves to one of our
+  // per-vault MCP resources; no-op otherwise (manual-pick path unchanged).
+  const boundVault = resolveResourceVault(params.resource, resolveBoundOrigins(deps));
+  if (boundVault) {
+    params.scope = narrowResourceVaultScopes(
+      params.scope.split(" ").filter((s) => s.length > 0),
+      boundVault,
+    ).join(" ");
+  }
   const approve = String(form.get("approve") ?? "") === "yes";
   const sessionId = parseSessionCookie(req.headers.get("cookie"));
   const session = sessionId ? findSession(db, sessionId) : null;
@@ -1140,18 +1243,51 @@ async function handleConsentSubmit(
       params.state,
     );
   }
-  // Multi-user Phase 1 (design 2026-05-20-multi-user-phase-1.md): non-admin
-  // users (`assigned_vault !== null`) are pinned to a single vault. The
-  // consent screen renders the picker locked to that vault and any named
-  // scopes (`vault:<name>:<verb>`) requested by the client must match. The
-  // server-side defense here refuses any mint where the user's submission
-  // disagrees — Aaron pinned this as "server-side defense refuses mints
-  // whose picked vault disagrees with assigned_vault" rather than silent
-  // overwrite, so a hand-crafted POST or a misbehaving SPA can't bypass the
-  // lock. Admin users (`assigned_vault === null`) keep the existing picker-
-  // as-source-of-truth behavior.
+  // Multi-user Phase 2 PR 2: non-admin users are pinned to a list of one
+  // or more vaults via `user_vaults`. The consent screen renders the
+  // picker narrowed to that list and any named scopes (`vault:<name>:
+  // <verb>`) requested by the client must target a vault in the list.
+  // The server-side defense here refuses any mint where the user's
+  // submission disagrees, so a hand-crafted POST or a misbehaving SPA
+  // can't bypass the narrowing. First admin (admin posture) keeps the
+  // existing picker-as-source-of-truth behavior (empty `assignedVaults`).
+  const userIsAdmin = isFirstAdmin(db, session.userId);
   const sessionUser = getUserById(db, session.userId);
-  const assignedVault = sessionUser?.assignedVault ?? null;
+  const assignedVaults: string[] = userIsAdmin ? [] : (sessionUser?.assignedVaults ?? []);
+  const isPinned = assignedVaults.length > 0;
+  // By design: the resource-bound re-narrow above does NOT check the bound
+  // vault exists in services.json for the admin path — admin (isPinned=false)
+  // can already consent to any vault via the manual picker, so the asymmetry
+  // (named-scope mint against a possibly-missing vault) is deliberate, not an
+  // oversight. Non-admins still hit the assignment + stale-vault defenses below.
+
+  // Zero-vault non-admin gate (Phase 2 PR 2 reviewer fold). A non-admin
+  // user with no `user_vaults` rows is a known-but-not-yet-assigned
+  // posture — they can sign in to /account/, change their password, and
+  // see the home page, but they have no vaults to authorize against.
+  // Block any vault-scoped consent at the submit boundary so an OAuth
+  // client can't trick them into minting a token: an empty `vault_scope`
+  // claim is the admin "unrestricted" sentinel (see `vaultScopeForUser`),
+  // and we must keep that sentinel reserved for true admins. Non-vault
+  // scopes (`scribe:transcribe`, etc.) still consent normally — only
+  // `vault:...` scopes are gated here. The defense pairs with the GET-
+  // path same-hub-auto-trust gate below (which falls through to the
+  // consent render that would otherwise show the picker).
+  if (!userIsAdmin && assignedVaults.length === 0) {
+    const submittedScopes = params.scope.split(" ").filter((s) => s.length > 0);
+    const hasVaultScope = submittedScopes.some((s) => {
+      if (s === "vault:read" || s === "vault:write" || s === "vault:admin") return true;
+      const parts = s.split(":");
+      return parts.length === 3 && parts[0] === "vault" && parts[2] && VAULT_VERBS.has(parts[2]);
+    });
+    if (hasVaultScope) {
+      return htmlError(
+        "No vaults assigned",
+        "vault_scope_mismatch: you have no assigned vaults on this hub yet, so you can't authorize an app for vault access. Ask the hub admin to assign you at least one vault via /admin/users, then try again.",
+        400,
+      );
+    }
+  }
 
   // Vault picker (Q1 of the vault-config-and-scopes design): an unnamed
   // `vault:<verb>` scope is ambiguous about which vault it grants access to.
@@ -1171,24 +1307,17 @@ async function handleConsentSubmit(
     const manifest = (deps.loadServicesManifest ?? readServicesManifest)();
     const validNames = listVaultNames(manifest);
     if (!validNames.includes(pickedVault)) {
-      // Stale-assignment branch (hub#284). Surfaced during hub#283
-      // reviewer pass — the pre-rc.11 path 400'd with the generic
-      // "Unknown vault" copy when a user whose assigned_vault was
-      // removed by the admin landed back on consent and submitted the
-      // stale name. The locked picker rendered the missing name, the
-      // form posted it, the user saw "vault X is not registered" and
-      // had no path forward. The new copy names the actual condition
-      // (assignment removed) and points at the admin remediation
-      // surface (/admin/users) instead of leaving the user wondering
-      // whether hub itself is broken.
+      // Stale-assignment branch (hub#284, generalized Phase 2 PR 2). The
+      // user is consenting via an assignment that points at a vault no
+      // longer in services.json. The new copy names the actual condition
+      // (assignment removed) and points at the admin remediation surface.
       //
-      // The check fires only when the user's `assigned_vault` claim
-      // matches the picked vault — narrows the special-case to the
-      // "user is consenting via their locked assignment that's now
-      // stale" shape rather than swallowing every Unknown-vault. A
-      // hand-crafted POST naming a never-existed vault still hits the
-      // generic branch.
-      if (assignedVault !== null && pickedVault === assignedVault) {
+      // The check fires when the picked vault is in the user's assigned
+      // list — narrows the special-case to the "user is consenting via
+      // a now-stale assignment" shape rather than swallowing every
+      // Unknown-vault. A hand-crafted POST naming a never-existed vault
+      // still hits the generic branch.
+      if (isPinned && assignedVaults.includes(pickedVault)) {
         return htmlError(
           "Assigned vault was removed",
           `Your assigned vault "${pickedVault}" is no longer registered on this hub. Ask the hub admin to reassign you to an existing vault via /admin/users, then try again.`,
@@ -1201,16 +1330,16 @@ async function handleConsentSubmit(
         400,
       );
     }
-    // Server-side defense: non-admin user submitted a vault that disagrees
-    // with their `assigned_vault`. The picker rendered as locked, so a UI-
-    // path user couldn't reach this — but a hand-crafted form bypassing the
-    // locked input lands here. Refuse the mint instead of silently
-    // overwriting; the explicit error tells the operator the assignment is
-    // load-bearing.
-    if (assignedVault !== null && pickedVault !== assignedVault) {
+    // Server-side defense: non-admin user submitted a vault that's not in
+    // their assigned list. The picker rendered as narrowed, so a UI-path
+    // user couldn't reach this — but a hand-crafted form bypassing the
+    // narrowed input lands here. Refuse the mint instead of silently
+    // overwriting; the explicit error tells the operator the assignment
+    // is load-bearing.
+    if (isPinned && !assignedVaults.includes(pickedVault)) {
       return htmlError(
         "Vault assignment mismatch",
-        `vault_scope_mismatch: the picked vault "${pickedVault}" does not match your vault assignment. Ask the hub admin to update your assignment, or pick the vault shown on the consent screen.`,
+        `vault_scope_mismatch: the picked vault "${pickedVault}" is not in your vault assignment. Ask the hub admin to update your assignment, or pick a vault shown on the consent screen.`,
         400,
       );
     }
@@ -1218,12 +1347,12 @@ async function handleConsentSubmit(
   }
 
   // Server-side defense for named-vault scopes (`vault:<name>:<verb>`) too.
-  // A non-admin user can't request scope against any vault other than their
-  // assigned one — same invariant as the picker check above, applied to
-  // scopes that arrived already-named (e.g. a client that knows the user's
-  // vault and asked for `vault:bob:read` directly). Admins (assigned_vault
-  // null) skip this check.
-  if (assignedVault !== null) {
+  // A non-admin user can't request scope against any vault outside their
+  // assignment list — same invariant as the picker check above, applied
+  // to scopes that arrived already-named (e.g. a client that knows the
+  // user's vault and asked for `vault:bob:read` directly). Admin posture
+  // (`isPinned === false`) skips this check.
+  if (isPinned) {
     const mismatched: string[] = [];
     for (const s of scopes) {
       const parts = s.split(":");
@@ -1233,7 +1362,7 @@ async function handleConsentSubmit(
         parts[1] &&
         parts[2] &&
         VAULT_VERBS.has(parts[2]) &&
-        parts[1] !== assignedVault
+        !assignedVaults.includes(parts[1])
       ) {
         mismatched.push(s);
       }
@@ -1241,29 +1370,29 @@ async function handleConsentSubmit(
     if (mismatched.length > 0) {
       return htmlError(
         "Vault assignment mismatch",
-        `vault_scope_mismatch: requested scopes ${mismatched.join(", ")} target a vault other than your vault assignment.`,
+        `vault_scope_mismatch: requested scopes ${mismatched.join(", ")} target a vault outside your assignment.`,
         400,
       );
     }
 
-    // Stale-assignment defense (hub#284) for named-vault scopes. A scope
-    // shaped `vault:<assigned>:<verb>` passes the mismatch check above but
-    // points at a vault that no longer exists in services.json. Minting a
-    // token here would silently issue scope against a vault the resource
-    // server can't find — the user thinks consent succeeded but the
-    // subsequent API calls fail with no actionable signal. Refuse the mint
-    // and surface the same admin-remediation hint the GET path's banner
-    // uses, so the picker-bypass POST and the natural form-render arrive at
-    // the same recovery story.
+    // Stale-assignment defense (hub#284, generalized Phase 2 PR 2). A
+    // named scope shaped `vault:<assigned>:<verb>` passes the mismatch
+    // check above but points at a vault that no longer exists in
+    // services.json. Minting a token here would silently issue scope
+    // against a vault the resource server can't find — the user thinks
+    // consent succeeded but the subsequent API calls fail with no
+    // actionable signal. Refuse the mint and surface the same admin-
+    // remediation hint the GET path's banner uses.
     const namedStaleScopes: string[] = [];
     for (const s of scopes) {
       const parts = s.split(":");
       if (
         parts.length === 3 &&
         parts[0] === "vault" &&
-        parts[1] === assignedVault &&
+        parts[1] !== undefined &&
         parts[2] &&
-        VAULT_VERBS.has(parts[2])
+        VAULT_VERBS.has(parts[2]) &&
+        assignedVaults.includes(parts[1])
       ) {
         namedStaleScopes.push(s);
       }
@@ -1273,10 +1402,19 @@ async function handleConsentSubmit(
       // the no-vault-scope hot path off-disk for the common admin flows.
       const manifest = (deps.loadServicesManifest ?? readServicesManifest)();
       const validNames = listVaultNames(manifest);
-      if (!validNames.includes(assignedVault)) {
+      // Collect the stale vault names embedded in the named scopes.
+      const staleNames = new Set<string>();
+      for (const s of namedStaleScopes) {
+        const parts = s.split(":");
+        if (parts[1] !== undefined && !validNames.includes(parts[1])) {
+          staleNames.add(parts[1]);
+        }
+      }
+      if (staleNames.size > 0) {
+        const exemplar = [...staleNames][0];
         return htmlError(
           "Assigned vault was removed",
-          `Your assigned vault "${assignedVault}" is no longer registered on this hub. Ask the hub admin to reassign you to an existing vault via /admin/users, then try again.`,
+          `Your assigned vault "${exemplar}" is no longer registered on this hub. Ask the hub admin to reassign you to an existing vault via /admin/users, then try again.`,
           400,
         );
       }
@@ -1421,10 +1559,7 @@ export async function handleApproveClientPost(
       );
     }
     target.searchParams.set("error", "access_denied");
-    target.searchParams.set(
-      "error_description",
-      "The user denied the authorization request.",
-    );
+    target.searchParams.set("error_description", "The user denied the authorization request.");
     if (denyState !== undefined) target.searchParams.set("state", denyState);
     return redirectResponse(target.toString());
   }
@@ -1478,6 +1613,7 @@ function paramsFromForm(form: Awaited<ReturnType<Request["formData"]>>): Authori
     codeChallenge: String(form.get("code_challenge") ?? ""),
     codeChallengeMethod: String(form.get("code_challenge_method") ?? "S256"),
     state: (form.get("state") as string | null) ?? null,
+    resource: (form.get("resource") as string | null) ?? null,
   };
 }
 
@@ -1491,6 +1627,10 @@ function authorizeParamsToQuery(p: AuthorizeFormParams): Record<string, string>
     code_challenge_method: p.codeChallengeMethod,
   };
   if (p.state) q.state = p.state;
+  // Round-trip the RFC 8707 resource indicator through the login redirect so
+  // the resource-bound narrowing survives a sign-in (it re-enters GET
+  // /oauth/authorize with the original params).
+  if (p.resource) q.resource = p.resource;
   return q;
 }
 
@@ -1660,11 +1800,17 @@ async function handleTokenAuthorizationCode(
     audience,
     clientId: redeemed.clientId,
     issuer: deps.issuer,
-    // vault_scope claim — Phase 1 per-user vault pin. Non-empty list for
-    // non-admin users with `assigned_vault` set; empty for admin / unpinned.
-    // The narrowing in `handleConsentSubmit` already rewrote `vault:<verb>` →
-    // `vault:<assigned_vault>:<verb>` for non-admin users, so the auth code's
-    // scopes are pre-aligned; this claim is the explicit "owned vault"
+    // vault_scope claim — Phase 2 per-user vault pin (Phase 1 had a single
+    // `assigned_vault` column; Phase 2 PR 2 generalized to `assigned_vaults`
+    // via `user_vaults`). Non-empty list for non-admin users with at least
+    // one assigned vault; empty for first-admin (unrestricted sentinel).
+    // Zero-vault non-admin is also empty by `vaultScopeForUser`, but the
+    // OAuth flow refuses to mint a vault-scoped token for them upstream
+    // (see the zero-vault gate in `handleConsentSubmit` + the same-hub
+    // auto-trust posture check), so we never reach here with that user
+    // posture. The narrowing in `handleConsentSubmit` already rewrote
+    // `vault:<verb>` → `vault:<assigned>:<verb>`, so the auth code's
+    // scopes are pre-aligned; this claim is the explicit "owned vaults"
     // signal PR 5 consumes downstream.
     vaultScope: vaultScopeForUser(db, redeemed.userId),
     now: deps.now,
@@ -1781,12 +1927,12 @@ async function handleTokenRefresh(
     clientId: row.clientId,
     issuer: deps.issuer,
     // vault_scope claim — re-derived from the user's *current*
-    // `assigned_vault` at refresh time (not snapshotted onto the refresh-
-    // token row). An admin who changes a user's `assigned_vault` between
+    // `assigned_vaults` at refresh time (not snapshotted onto the refresh-
+    // token row). An admin who changes a user's vault assignments between
     // mint and refresh sees the new value on the next refresh; existing
     // access tokens carry their original claim until their 15-minute TTL
     // elapses. Same posture as the design's "OAuth issuer reads
-    // `assigned_vault` at mint time, not at session-creation time" pin.
+    // `assigned_vaults` at mint time, not at session-creation time" pin.
     vaultScope: vaultScopeForUser(db, refreshUserId),
     now: deps.now,
   });
@@ -2156,95 +2302,117 @@ function consentProps(
   params: AuthorizeFormParams,
   vaultNames: string[],
   csrfToken: string,
-  lockedVault: string | null,
+  assignedVaults: readonly string[],
+  userIsAdmin: boolean,
 ) {
   const scopes = params.scope.split(" ").filter((s) => s.length > 0);
   const unnamedVerbs = unnamedVaultVerbs(scopes);
-  // Multi-user Phase 1, stale-assignment branch (hub#284). The user has an
-  // `assigned_vault` pinned on their row but the named vault is no longer
-  // in services.json — admin removed / renamed it without reassigning the
-  // user. Pre-hub#284 this fell through to the locked picker, posted the
-  // stale name, and `handleConsentSubmit` rejected it with a generic
-  // "Unknown vault" 400. The user couldn't tell what happened or how to
-  // recover.
+  // Multi-user Phase 2 PR 2 stale-assignment branch (hub#284 generalized
+  // from one vault to N). A non-admin user whose entire vault list has
+  // been removed from services.json — admin removed / renamed the vaults
+  // without reassigning. The banner surfaces this state with an admin-
+  // remediation hint instead of silently minting against a missing vault.
   //
-  // Detect it here and surface the banner on the consent screen explaining
-  // the state and pointing at admin remediation. The banner is informational
-  // for non-vault-scoped flows (the user can still consent to e.g.
-  // `scribe:transcribe` without a working vault assignment), but the picker
-  // section + Approve button are gated when the requested scope actually
-  // depends on a vault — see the `vaultPicker` + `approveDisabled` logic
-  // below.
+  // The user-facing surface is "your assigned vault(s) were removed" —
+  // the banner names the first stale vault as the canonical example. The
+  // exact list is unimportant for the recovery path (operator goes to
+  // /admin/users either way), and pluralizing the banner copy doesn't
+  // change the action.
   //
-  // Security posture: we deliberately do NOT relax the picked-must-match-
-  // assigned check or let the user pick any other vault. Doing so would
-  // let assignment-binding be circumvented by getting an admin to remove
-  // the assigned vault. Stale-assignment is an admin-remediated state.
+  // Security posture: we deliberately do NOT relax the picked-must-be-in-
+  // assigned-list check. Stale-assignment is admin-remediated.
+  const remainingValidAssigned = assignedVaults.filter((v) => vaultNames.includes(v));
+  const hasStaleAssignment = assignedVaults.length > 0 && remainingValidAssigned.length === 0;
   const staleAssignedVault =
-    lockedVault !== null && !vaultNames.includes(lockedVault) ? lockedVault : undefined;
-  // A named scope like `vault:<old>:read` requested by the client where
-  // <old> is the user's stale assigned_vault. The server-side named-scope
-  // defense (`handleConsentSubmit`) allows this through because the scope
-  // matches `assignedVault`, but the token it mints would point at a vault
-  // that doesn't exist. Gate Approve on this case too so the user doesn't
-  // burn a consent into a token that fails at the resource server.
+    hasStaleAssignment && assignedVaults[0] !== undefined ? assignedVaults[0] : undefined;
+  // A named scope like `vault:<old>:<verb>` requested by the client where
+  // <old> is one of the user's stale vaults. The server-side named-scope
+  // defense allows this through because the scope matches an assigned
+  // vault, but the token it mints would point at a vault that no longer
+  // exists. Gate Approve on this case too so the user doesn't burn a
+  // consent into a token that fails at the resource server.
   const hasNamedStaleVaultScope =
-    staleAssignedVault !== undefined &&
+    hasStaleAssignment &&
     scopes.some((s) => {
       const parts = s.split(":");
-      return (
-        parts.length === 3 &&
-        parts[0] === "vault" &&
-        parts[1] === staleAssignedVault &&
-        parts[2] !== undefined &&
-        VAULT_VERBS.has(parts[2])
-      );
+      if (
+        parts.length !== 3 ||
+        parts[0] !== "vault" ||
+        parts[1] === undefined ||
+        parts[2] === undefined ||
+        !VAULT_VERBS.has(parts[2])
+      ) {
+        return false;
+      }
+      // Named for one of the user's vaults — and given hasStaleAssignment,
+      // none of the user's vaults exist on this hub, so this scope points
+      // at a stale name.
+      return assignedVaults.includes(parts[1]);
     });
 
-  // Multi-user Phase 1 (design 2026-05-20-multi-user-phase-1.md, decision-pin
-  // "consent picker for non-admin users"): non-admin users (assigned_vault
-  // non-null) see the picker locked to their `assigned_vault` rather than a
-  // free dropdown. Phase 2 will hide other vaults entirely; Phase 1 ships
-  // lock-the-picker (the smallest diff that satisfies "user can't pick a
-  // vault they don't own"). Server-side defense in `handleConsentSubmit`
-  // refuses mints whose POST disagrees regardless of how the picker is
-  // rendered.
+  // Multi-user Phase 2 PR 2: non-admin users see the picker narrowed to
+  // their assigned vault list. Four shapes emerge:
   //
-  // Stale-assignment shape (hub#284): when the user's assigned_vault no
-  // longer exists, the picker renders as no-vaults-available rather than
-  // locking onto a missing name — the banner above the scope list explains
-  // why and the disabled Approve prevents a form submit that would fail
-  // server-side anyway.
+  //   - Single assigned vault (still valid) → render locked to that name
+  //     (same shape as Phase 1).
+  //   - Two-or-more assigned vaults → render a dropdown filtered to the
+  //     user's list. Same control as the admin dropdown but narrowed.
+  //   - Stale-assigned (all vaults gone) → render no-vaults-available so
+  //     the form gracefully rejects an Approve click instead of silently
+  //     submitting a missing name.
+  //   - First admin (admin posture, empty `assignedVaults`) → full hub-
+  //     wide dropdown of every vault on the hub.
+  //   - Zero-vault non-admin (Phase 2 PR 2 reviewer fold) → no-vaults-
+  //     available so the form gracefully rejects an Approve click. The
+  //     prior shape rendered the full hub-wide list for non-admins with
+  //     zero assignments, which let them pick a vault they had no
+  //     business consenting to. The consent-submit gate refuses any
+  //     vault-scoped POST from a zero-vault non-admin (defense in depth);
+  //     this branch keeps the picker UI honest.
   let vaultPicker: VaultPickerProps | undefined;
   if (unnamedVerbs.length > 0) {
-    if (staleAssignedVault !== undefined) {
+    if (hasStaleAssignment) {
       vaultPicker = { unnamedVerbs, availableVaults: [] };
-    } else if (lockedVault !== null) {
-      vaultPicker = { unnamedVerbs, availableVaults: vaultNames, lockedVault };
-    } else {
+    } else if (remainingValidAssigned.length === 1) {
+      const only = remainingValidAssigned[0];
+      if (only !== undefined) {
+        vaultPicker = { unnamedVerbs, availableVaults: [only], lockedVault: only };
+      }
+    } else if (remainingValidAssigned.length > 1) {
+      vaultPicker = { unnamedVerbs, availableVaults: remainingValidAssigned };
+    } else if (userIsAdmin) {
+      // Admin posture (no assignments) → full hub-wide list.
       vaultPicker = { unnamedVerbs, availableVaults: vaultNames };
+    } else {
+      // Zero-vault non-admin → no-vaults-available picker with the
+      // "ask your admin to assign you" copy. The Approve button renders
+      // disabled (same shape as the empty-services-json case) so the
+      // form can't post a hand-picked name. The consent-submit gate
+      // refuses any vault-scoped POST from this user too (defense in
+      // depth — see `handleConsentSubmit`).
+      vaultPicker = { unnamedVerbs, availableVaults: [], emptyReason: "no-assignments" };
     }
   }
   // Named-scope display: substitute unnamed `vault:<verb>` rows with the
   // resolved form the operator will actually consent to.
-  //   - Non-admin (lockedVault set, NOT stale) → render `vault:<lockedVault>:<verb>`.
-  //   - Stale-assigned (hub#284) → null; the scope row carries the
-  //     `<TBD>` placeholder. The banner explains why a name isn't bound.
-  //   - Admin with exactly one vault available → render that vault's name;
-  //     the picker pre-checks it and a default-Approve mints scope against
-  //     it, so the displayed scope matches the next state of the form.
-  //   - Admin with multiple vaults / no vaults → null sentinel; render with
-  //     a `<TBD>` placeholder + a hint pointing at the picker. Once the
-  //     operator clicks a radio the JS-free form still posts the chosen
-  //     name; the displayed scope only changes after the next page render.
+  //   - Non-admin with exactly one valid assigned vault → render that name.
+  //   - Stale-assigned → null; the row carries the `<TBD>` placeholder.
+  //     The banner explains why a name isn't bound.
+  //   - Non-admin with multiple assigned vaults → null sentinel (the user
+  //     hasn't picked yet).
+  //   - Admin with exactly one vault available → render that name.
+  //   - Admin with multiple / no vaults → null sentinel.
   let displayVault: string | null = null;
-  if (staleAssignedVault === undefined && lockedVault !== null) {
-    displayVault = lockedVault;
+  if (!hasStaleAssignment && remainingValidAssigned.length === 1) {
+    const only = remainingValidAssigned[0];
+    if (only !== undefined) displayVault = only;
   } else if (
-    staleAssignedVault === undefined &&
+    !hasStaleAssignment &&
+    assignedVaults.length === 0 &&
     unnamedVerbs.length > 0 &&
     vaultNames.length === 1
   ) {
+    // Admin with a single vault on the hub: pre-check pattern from Phase 1.
     const only = vaultNames[0];
     if (only) displayVault = only;
   }
@@ -2271,4 +2439,5 @@ interface VaultPickerProps {
   unnamedVerbs: string[];
   availableVaults: string[];
   lockedVault?: string;
+  emptyReason?: "no-assignments" | "no-vaults-on-hub";
 }