@openparachute/hub 0.5.10-rc.6 → 0.5.10

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

@@ -6,6 +6,12 @@ import { join } from "node:path";
 import { getClient, registerClient } from "../clients.ts";
 import { CSRF_COOKIE_NAME } from "../csrf.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS,
+  getSetting,
+  openFirstClientAutoApproveWindow,
+  setSetting,
+} from "../hub-settings.ts";
 import { findTokenRowByJti, validateAccessToken } from "../jwt-sign.ts";
 import {
   authorizationServerMetadata,
@@ -227,6 +233,142 @@ describe("handleAuthorizeGet", () => {
       );
       const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
       expect(res.status).toBe(400);
+      const body = await res.text();
+      expect(body).toContain("Unknown application");
+      // Cross-origin redirect_uri → no recovery affordance. The page must
+      // not include the inline JS reset block; we can't safely interact
+      // with a third-party SPA's storage from this page.
+      expect(body).not.toContain("unknown-client-reset");
+      expect(body).not.toContain("lens:dcr:");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("unknown client_id with self-origin redirect_uri renders recovery affordance (hub#fresh-machine-connect)", async () => {
+    // The canonical fresh-machine-stale-localStorage repro: notes' SPA
+    // is mounted at the hub's own origin, holds a cached client_id from
+    // a previous hub.db, and lands on /oauth/authorize with the dangling
+    // id. Hub recognizes the redirect_uri as one of its bound origins and
+    // surfaces a one-click recovery: the inline JS clears the SPA's DCR
+    // localStorage cache (any `lens:dcr:*` key) and navigates to the
+    // redirect_uri's pathname for a fresh DCR pass.
+    const { db, cleanup } = await makeDb();
+    try {
+      const { challenge } = makePkce();
+      const selfRedirect = `${ISSUER}/notes/oauth/callback`;
+      const req = new Request(
+        authorizeUrl({
+          client_id: "stale-dangling-id",
+          redirect_uri: selfRedirect,
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        hubBoundOrigins: () => [ISSUER],
+      });
+      expect(res.status).toBe(400);
+      const body = await res.text();
+      expect(body).toContain("Unknown application");
+      expect(body).toContain("stale-dangling-id");
+      // Recovery affordance is present.
+      expect(body).toContain("unknown-client-reset");
+      // The reset target is the redirect_uri's pathname only (not the
+      // full URL — we never surface a cross-origin redirect even when
+      // redirect_uri claims to be ours).
+      expect(body).toContain('data-target="/notes/oauth/callback"');
+      // The inline JS clears the SPA's known DCR cache prefix.
+      expect(body).toContain("lens:dcr:");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("unknown client_id with redirect_uri on unbound origin falls back to static error", async () => {
+    // hubBoundOrigins lists only the canonical hub origin; a redirect_uri
+    // pointing somewhere else (third-party SPA, attacker probe) MUST NOT
+    // surface the recovery JS — that JS only makes sense for SPAs we
+    // ourselves host.
+    const { db, cleanup } = await makeDb();
+    try {
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: "stale-id",
+          redirect_uri: "https://attacker.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        hubBoundOrigins: () => [ISSUER],
+      });
+      expect(res.status).toBe(400);
+      const body = await res.text();
+      expect(body).toContain("Unknown application");
+      expect(body).not.toContain("unknown-client-reset");
+      expect(body).not.toContain("lens:dcr:");
+      expect(body).not.toContain("attacker.example");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("unknown client_id with malformed redirect_uri falls back to static error", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: "stale-id",
+          // Validated as non-empty by parseAuthorizeFormParams but not
+          // URL-parsed there; the unknown-client renderer must handle
+          // its own parsing safely.
+          redirect_uri: "not-a-valid-url",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        hubBoundOrigins: () => [ISSUER],
+      });
+      expect(res.status).toBe(400);
+      const body = await res.text();
+      expect(body).toContain("Unknown application");
+      expect(body).not.toContain("unknown-client-reset");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("unknown client_id falls back to static error when hubBoundOrigins is unset", async () => {
+    // Pre-#245 callers don't thread hubBoundOrigins; the gate falls back
+    // to `[issuer]` so a single-origin hub still surfaces the recovery
+    // affordance for its own redirect_uris. Verify that path.
+    const { db, cleanup } = await makeDb();
+    try {
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: "stale-id",
+          redirect_uri: `${ISSUER}/notes/oauth/callback`,
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+      );
+      // No hubBoundOrigins → falls back to [issuer], which still matches.
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(400);
+      const body = await res.text();
+      expect(body).toContain("unknown-client-reset");
     } finally {
       cleanup();
     }
@@ -880,6 +1022,58 @@ describe("handleAuthorizePost — consent submit", () => {
     }
   });
 
+  test("race-condition branch (client un-approved between GET and POST) — error points at web approval path, no CLI mention", async () => {
+    // Defensive branch in handleConsentSubmit: consent only renders for
+    // approved clients, but a row can flip back to pending between GET and
+    // POST (operator revoke / hand-crafted POST). Pre-rc.19 follow-up the
+    // error said "Run `parachute auth approve-client <id>` from a terminal";
+    // rc.19 retired every browser-visible CLI mention, so this branch now
+    // surfaces the same /admin/approve-client/<id> path the unauth GET-on-
+    // pending page advertises.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const { challenge } = makePkce();
+      const form = new URLSearchParams({
+        __action: "consent",
+        __csrf: TEST_CSRF,
+        approve: "yes",
+        client_id: reg.client.clientId,
+        redirect_uri: "https://app.example/cb",
+        response_type: "code",
+        scope: "vault:default:read",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        state: "race",
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, 86400)}`,
+        },
+      });
+      const res = await handleAuthorizePost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(403);
+      const html = await res.text();
+      expect(html).toContain("App not yet approved");
+      // Web path advertised, with the client_id rendered inline.
+      expect(html).toContain(`/admin/approve-client/${reg.client.clientId}`);
+      expect(html).toContain("Sign in as admin");
+      // CLI mention retired from every browser-visible surface in rc.19.
+      expect(html).not.toContain("parachute auth approve-client");
+      expect(html).not.toContain("from a terminal");
+    } finally {
+      cleanup();
+    }
+  });
+
   test("rejects parachute:host:admin in form scope (defense-in-depth, #96)", async () => {
     // GET-time gate already rejects, but a hand-crafted POST could carry
     // an operator-only scope. Consent submit must independently reject.
@@ -955,6 +1149,57 @@ describe("handleAuthorizePost — consent submit", () => {
       cleanup();
     }
   });
+
+  test("consent POST with unknown client_id + self-origin redirect_uri renders recovery affordance", async () => {
+    // Symmetry with the GET-path coverage of the same hub#277 recovery
+    // affordance. handleAuthorizePost's consent submit routes the
+    // `getClient = null` branch through the same `unknownClientResponse`
+    // helper as the GET path; pin it explicitly so a future refactor
+    // can't silently drop the recovery path here. Reaching this branch
+    // on the consent POST means the client_id was deleted between
+    // render and submit (vanishingly rare in practice — exercised here
+    // by registering nothing for the carried `client_id`).
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const { challenge } = makePkce();
+      const form = new URLSearchParams({
+        __action: "consent",
+        __csrf: TEST_CSRF,
+        approve: "yes",
+        client_id: "stale-dangling-id",
+        redirect_uri: `${ISSUER}/notes/oauth/callback`,
+        response_type: "code",
+        scope: "vault:read",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        state: "abc",
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, 86400)}`,
+        },
+      });
+      const res = await handleAuthorizePost(db, req, {
+        issuer: ISSUER,
+        hubBoundOrigins: () => [ISSUER],
+      });
+      expect(res.status).toBe(400);
+      const body = await res.text();
+      expect(body).toContain("Unknown application");
+      expect(body).toContain("stale-dangling-id");
+      // Recovery affordance — same shape as the GET-path tests above.
+      expect(body).toContain("unknown-client-reset");
+      expect(body).toContain('data-target="/notes/oauth/callback"');
+      expect(body).toContain("lens:dcr:");
+    } finally {
+      cleanup();
+    }
+  });
 });
 
 describe("handleToken — full OAuth dance", () => {
@@ -2230,7 +2475,9 @@ describe("DCR approval gate (#74)", () => {
       expect(res.status).toBe(403);
       const html = await res.text();
       expect(html).toContain("App not yet approved");
-      expect(html).toContain("approve-client");
+      // /admin/approve-client/<id> deep link is the canonical recovery now
+      // (the pre-rc.19 CLI message was retired in favor of the web path).
+      expect(html).toContain(`/admin/approve-client/${encodeURIComponent(reg.client.clientId)}`);
       // No vault hint → no vault row in approve-meta. Single-vault hubs +
       // pre-vault-popover clients leave the section omitted (#244).
       expect(html).not.toContain('approve-meta-label">vault');
@@ -3723,10 +3970,13 @@ describe("inline approve button on pending /oauth/authorize (#208)", () => {
     });
   }
 
-  test("session absent → page renders WITHOUT approve form (CLI-only fallback)", async () => {
-    // Regression: pre-#208 behavior preserved when no session cookie is
-    // present. The CLI-fallback message must still be visible so an operator
-    // who arrived from a fresh browser knows what to do.
+  test("session absent → page renders Sign-in CTA + shareable deep link (no CLI message)", async () => {
+    // Approval-UX rc.19: the unauthenticated viewer no longer sees a
+    // "Ask the operator to run `parachute auth approve-client <id>`"
+    // message. The web approval path (#277) is the canonical recovery
+    // now — render a primary Sign-in CTA wired to /login?next=/admin/...
+    // and a shareable deep link the operator can send to whoever runs
+    // the hub.
     const { db, cleanup } = await makeDb();
     try {
       const reg = registerClient(db, {
@@ -3739,9 +3989,23 @@ describe("inline approve button on pending /oauth/authorize (#208)", () => {
       expect(res.status).toBe(403);
       const html = await res.text();
       expect(html).toContain("App not yet approved");
-      // CLI-fallback message present — the only way to recover without a session.
-      expect(html).toContain("approve-client");
-      // No form element pointing at the approve endpoint.
+      // Primary CTA: Sign-in link wired to land the admin directly on
+      // the approval page after authenticating.
+      expect(html).toContain("Sign in as admin to approve");
+      const expectedLoginHref = `/login?next=${encodeURIComponent(
+        `/admin/approve-client/${encodeURIComponent(reg.client.clientId)}`,
+      )}`;
+      expect(html).toContain(`href="${expectedLoginHref}"`);
+      // Secondary CTA: shareable, fully-qualified deep link + Copy button.
+      expect(html).toContain(
+        `${ISSUER}/admin/approve-client/${encodeURIComponent(reg.client.clientId)}`,
+      );
+      expect(html).toContain('id="approve-share-copy"');
+      expect(html).toContain("navigator.clipboard");
+      // Retired CLI hint must not appear anywhere in the body.
+      expect(html).not.toContain("parachute auth approve-client");
+      expect(html).not.toContain("from a terminal");
+      // No form element pointing at the approve endpoint (un-authed branch).
       expect(html).not.toContain('action="/oauth/authorize/approve"');
     } finally {
       cleanup();
@@ -3783,8 +4047,12 @@ describe("inline approve button on pending /oauth/authorize (#208)", () => {
       expect(html).toContain("MyApp");
       expect(html).toContain(reg.client.clientId);
       expect(html).toContain("https://app.example/cb");
-      // CLI fallback still visible.
-      expect(html).toContain("approve-client");
+      // Authed branch shows only the one-click Approve form — the unauth
+      // Sign-in CTA and shareable-link block do NOT render here.
+      expect(html).not.toContain("Sign in as admin to approve");
+      expect(html).not.toContain("Or send this link to your hub admin");
+      // CLI hint also gone in this branch (approval-UX rc.19).
+      expect(html).not.toContain("parachute auth approve-client");
     } finally {
       cleanup();
     }
@@ -4216,3 +4484,784 @@ describe("inline approve button on pending /oauth/authorize (#208)", () => {
     }
   });
 });
+
+// DCR first-client auto-approve window (hub#268 Item 3). The wizard's
+// expose-step POST opens a 60-minute window where the very next
+// `/oauth/register` registration is auto-approved + the window cleared.
+// Single-use: client #2 within the same window falls through to the
+// standard pending-approval flow.
+describe("DCR first-client auto-approve window (hub#268 Item 3)", () => {
+  function registerRequest(): Request {
+    return new Request(`${ISSUER}/oauth/register`, {
+      method: "POST",
+      body: JSON.stringify({
+        redirect_uris: ["https://app.example/cb"],
+        client_name: "first-client",
+      }),
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  test("client registered within the open window → status approved + window cleared", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      const res = await handleRegister(db, registerRequest(), {
+        issuer: ISSUER,
+        now: () => t0,
+      });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("approved");
+      // Persisted, not just response-shaped.
+      const row = getClient(db, body.client_id as string);
+      expect(row?.status).toBe("approved");
+      // Window cleared on consume (single-use).
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("client registered AFTER the window has expired → status pending", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      const past = new Date(t0.getTime() + FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS + 1);
+      const res = await handleRegister(db, registerRequest(), {
+        issuer: ISSUER,
+        now: () => past,
+      });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("second client within window after first auto-approved → status pending (single-use)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      // Client #1: approved.
+      const res1 = await handleRegister(db, registerRequest(), {
+        issuer: ISSUER,
+        now: () => t0,
+      });
+      const body1 = (await res1.json()) as Record<string, unknown>;
+      expect(body1.status).toBe("approved");
+      // Client #2 within the (still-not-expired) window: pending.
+      const stillWithinWindow = new Date(t0.getTime() + 30 * 60 * 1000);
+      const res2 = await handleRegister(db, registerRequest(), {
+        issuer: ISSUER,
+        now: () => stillWithinWindow,
+      });
+      const body2 = (await res2.json()) as Record<string, unknown>;
+      expect(body2.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no window set → status pending (default public-DCR flow)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const res = await handleRegister(db, registerRequest(), { issuer: ISSUER });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+      // Settings row untouched.
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("operator-bearer auto-approve still takes precedence over the window (no double-consume)", async () => {
+    // Bearer-authenticated registration approves directly; the
+    // auto-approve window should NOT be consumed in that case — it's
+    // still available for the first un-authenticated client.
+    const { db, cleanup } = await makeDb();
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      // We can't easily mint an operator bearer in this test layer, so
+      // simulate by using the session-cookie path (issuer-trusted) which
+      // also auto-approves before falling through to the window check.
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const req = new Request(`${ISSUER}/oauth/register`, {
+        method: "POST",
+        body: JSON.stringify({ redirect_uris: ["https://app.example/cb"] }),
+        headers: {
+          "content-type": "application/json",
+          cookie: buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000)),
+          origin: ISSUER,
+        },
+      });
+      const res = await handleRegister(db, req, { issuer: ISSUER, now: () => t0 });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("approved");
+      // Window NOT consumed — still set, still open. The session-cookie
+      // path approved first, never reaching the window-consume code.
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeDefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("malformed timestamp in the setting → treated as no-window, status pending", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      setSetting(db, "pending_first_client_auto_approve_until", "not-a-real-iso-string");
+      const res = await handleRegister(db, registerRequest(), { issuer: ISSUER });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+// Multi-user Phase 1, PR 4 (design 2026-05-20-multi-user-phase-1.md, hub#252):
+// non-admin users (with `assigned_vault` non-null) see the consent picker
+// locked, and the OAuth issuer mints tokens carrying `vault_scope: [<assigned>]`.
+// Server-side defense refuses any mint whose picked vault disagrees.
+describe("handleAuthorizeGet — multi-user assigned vault picker lock (PR 4)", () => {
+  test("admin user (assigned_vault null) sees the free dropdown", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const admin = await createUser(db, "admin-aaron", "pw");
+      const session = createSession(db, { userId: admin.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:read",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      // Free dropdown for admin: radio inputs present, no "Assigned vault" lock.
+      expect(html).toContain('name="vault_pick" value="default"');
+      expect(html).not.toContain("Assigned vault");
+      expect(html).not.toContain("admin-managed");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("non-admin user (assigned_vault set) sees the locked picker with admin-managed note", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const admin = await createUser(db, "admin-aaron", "pw");
+      const bob = await createUser(db, "bob", "pw", {
+        allowMulti: true,
+        assignedVault: "default",
+      });
+      void admin;
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:read",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).toContain("vault-picker-locked");
+      expect(html).toContain("Assigned vault");
+      expect(html).toContain("admin-managed");
+      // Hidden input carries the assigned vault as the picker value.
+      expect(html).toContain('<input type="hidden" name="vault_pick" value="default"');
+      // No free-choice radio inputs.
+      expect(html).not.toContain('type="radio" name="vault_pick"');
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+// Approval-UX rc.19 (Issue 2 in Aaron's bundle): the consent screen now
+// renders the *resolved* scope shape — `vault:<name>:<verb>` — instead of
+// the raw OAuth request `vault:<verb>`. The raw form was confusing because
+// it implied vault-wide unrestricted access, when hub actually narrows to
+// a specific vault at token-mint via the picker (or the user's
+// assigned_vault for multi-user setups).
+describe("handleAuthorizeGet — resolved scope display (approval-UX rc.19)", () => {
+  test("non-admin user (assigned_vault set) sees vault:<assigned>:read on consent, not raw vault:read", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const bob = await createUser(db, "bob", "pw", { assignedVault: "default" });
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:read",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      // Resolved form rendered in the scope-row code block.
+      expect(html).toContain('<code class="scope-name">vault:default:read</code>');
+      // Raw unnamed form must NOT appear inside a scope row (it still
+      // appears in the hidden form-roundtrip inputs as `name="scope" value="vault:read"`).
+      expect(html).not.toContain('<code class="scope-name">vault:read</code>');
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("admin user with picker — single-vault hub pre-checks and consent shows that vault", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const admin = await createUser(db, "admin-aaron", "pw");
+      const session = createSession(db, { userId: admin.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:read",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      // The fixture services manifest has a single vault named "default" — the
+      // picker pre-checks it and the consent screen renders the resolved form.
+      expect(html).toContain('<code class="scope-name">vault:default:read</code>');
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("handleAuthorizePost — multi-user assigned vault defense (PR 4)", () => {
+  test("non-admin happy path: token carries vault_scope=[assigned] and narrowed scope", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const bob = await createUser(db, "bob", "pw", { assignedVault: "default" });
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { verifier, challenge } = makePkce();
+      const consentForm = new URLSearchParams({
+        __action: "consent",
+        __csrf: TEST_CSRF,
+        approve: "yes",
+        client_id: reg.client.clientId,
+        redirect_uri: "https://app.example/cb",
+        response_type: "code",
+        scope: "vault:read",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        vault_pick: "default",
+      });
+      const consentRes = await handleAuthorizePost(
+        db,
+        new Request(`${ISSUER}/oauth/authorize`, {
+          method: "POST",
+          body: consentForm,
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, 86400)}`,
+          },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      expect(consentRes.status).toBe(302);
+      const code = new URL(consentRes.headers.get("location") ?? "").searchParams.get("code");
+      const tokenRes = await handleToken(
+        db,
+        new Request(`${ISSUER}/oauth/token`, {
+          method: "POST",
+          body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code: code ?? "",
+            client_id: reg.client.clientId,
+            redirect_uri: "https://app.example/cb",
+            code_verifier: verifier,
+          }),
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      expect(tokenRes.status).toBe(200);
+      const body = (await tokenRes.json()) as { access_token: string; scope: string };
+      expect(body.scope).toBe("vault:default:read");
+      const { payload } = await validateAccessToken(db, body.access_token, ISSUER);
+      expect(payload.scope).toBe("vault:default:read");
+      expect(payload.vault_scope).toEqual(["default"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("admin user (assigned_vault null) mints with vault_scope=[]", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const admin = await createUser(db, "admin-aaron", "pw");
+      const session = createSession(db, { userId: admin.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { verifier, challenge } = makePkce();
+      const consentForm = new URLSearchParams({
+        __action: "consent",
+        __csrf: TEST_CSRF,
+        approve: "yes",
+        client_id: reg.client.clientId,
+        redirect_uri: "https://app.example/cb",
+        response_type: "code",
+        scope: "vault:read",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        vault_pick: "default",
+      });
+      const consentRes = await handleAuthorizePost(
+        db,
+        new Request(`${ISSUER}/oauth/authorize`, {
+          method: "POST",
+          body: consentForm,
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, 86400)}`,
+          },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      const code = new URL(consentRes.headers.get("location") ?? "").searchParams.get("code");
+      const tokenRes = await handleToken(
+        db,
+        new Request(`${ISSUER}/oauth/token`, {
+          method: "POST",
+          body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code: code ?? "",
+            client_id: reg.client.clientId,
+            redirect_uri: "https://app.example/cb",
+            code_verifier: verifier,
+          }),
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      const body = (await tokenRes.json()) as { access_token: string };
+      const { payload } = await validateAccessToken(db, body.access_token, ISSUER);
+      expect(payload.vault_scope).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("non-admin with disagreeing vault_pick → 400 vault_scope_mismatch", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const bob = await createUser(db, "bob", "pw", { assignedVault: "default" });
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { challenge } = makePkce();
+      // The fixture also has a vault "default"; build a manifest that has
+      // two valid vault names so the mismatch isn't conflated with
+      // "unknown vault."
+      const twoVaultManifest: ServicesManifest = {
+        services: [
+          {
+            name: "parachute-vault",
+            port: 1940,
+            paths: ["/vault/default", "/vault/other"],
+            health: "/health",
+            version: "0.3.0",
+          },
+        ],
+      };
+      const consentForm = new URLSearchParams({
+        __action: "consent",
+        __csrf: TEST_CSRF,
+        approve: "yes",
+        client_id: reg.client.clientId,
+        redirect_uri: "https://app.example/cb",
+        response_type: "code",
+        scope: "vault:read",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        vault_pick: "other",
+      });
+      const res = await handleAuthorizePost(
+        db,
+        new Request(`${ISSUER}/oauth/authorize`, {
+          method: "POST",
+          body: consentForm,
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, 86400)}`,
+          },
+        }),
+        { issuer: ISSUER, loadServicesManifest: () => twoVaultManifest },
+      );
+      expect(res.status).toBe(400);
+      const html = await res.text();
+      expect(html).toContain("vault_scope_mismatch");
+      // Echo back the picked-but-rejected vault (HTML-escaped), but DON'T
+      // leak the assigned one (post-N1 nit-fold). "your vault assignment"
+      // is the soft phrase replacing the prior `your assigned vault "..."`.
+      expect(html).toContain("&quot;other&quot;");
+      expect(html).toContain("your vault assignment");
+      expect(html).not.toContain("&quot;default&quot;");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("non-admin requesting named scope for the wrong vault → 400 vault_scope_mismatch", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const bob = await createUser(db, "bob", "pw", { assignedVault: "default" });
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { challenge } = makePkce();
+      const consentForm = new URLSearchParams({
+        __action: "consent",
+        __csrf: TEST_CSRF,
+        approve: "yes",
+        client_id: reg.client.clientId,
+        redirect_uri: "https://app.example/cb",
+        response_type: "code",
+        // Explicit named scope targeting a vault other than bob's assigned one.
+        scope: "vault:other:read",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+      });
+      const res = await handleAuthorizePost(
+        db,
+        new Request(`${ISSUER}/oauth/authorize`, {
+          method: "POST",
+          body: consentForm,
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, 86400)}`,
+          },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      expect(res.status).toBe(400);
+      const html = await res.text();
+      expect(html).toContain("vault_scope_mismatch");
+      expect(html).toContain("vault:other:read");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("non-admin requesting named scope for the assigned vault → happy path", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const bob = await createUser(db, "bob", "pw", { assignedVault: "default" });
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { verifier, challenge } = makePkce();
+      const consentForm = new URLSearchParams({
+        __action: "consent",
+        __csrf: TEST_CSRF,
+        approve: "yes",
+        client_id: reg.client.clientId,
+        redirect_uri: "https://app.example/cb",
+        response_type: "code",
+        // Named scope matching bob's assigned vault — should pass.
+        scope: "vault:default:read",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+      });
+      const consentRes = await handleAuthorizePost(
+        db,
+        new Request(`${ISSUER}/oauth/authorize`, {
+          method: "POST",
+          body: consentForm,
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, 86400)}`,
+          },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      expect(consentRes.status).toBe(302);
+      const code = new URL(consentRes.headers.get("location") ?? "").searchParams.get("code");
+      const tokenRes = await handleToken(
+        db,
+        new Request(`${ISSUER}/oauth/token`, {
+          method: "POST",
+          body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code: code ?? "",
+            client_id: reg.client.clientId,
+            redirect_uri: "https://app.example/cb",
+            code_verifier: verifier,
+          }),
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      const body = (await tokenRes.json()) as { access_token: string };
+      const { payload } = await validateAccessToken(db, body.access_token, ISSUER);
+      expect(payload.scope).toBe("vault:default:read");
+      expect(payload.vault_scope).toEqual(["default"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("refresh flow re-derives vault_scope from current assigned_vault", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const bob = await createUser(db, "bob", "pw", { assignedVault: "default" });
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { verifier, challenge } = makePkce();
+
+      // Step 1: complete the OAuth dance to obtain a refresh token.
+      const consentForm = new URLSearchParams({
+        __action: "consent",
+        __csrf: TEST_CSRF,
+        approve: "yes",
+        client_id: reg.client.clientId,
+        redirect_uri: "https://app.example/cb",
+        response_type: "code",
+        scope: "vault:read",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        vault_pick: "default",
+      });
+      const consentRes = await handleAuthorizePost(
+        db,
+        new Request(`${ISSUER}/oauth/authorize`, {
+          method: "POST",
+          body: consentForm,
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, 86400)}`,
+          },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      const code = new URL(consentRes.headers.get("location") ?? "").searchParams.get("code");
+      const tokenRes = await handleToken(
+        db,
+        new Request(`${ISSUER}/oauth/token`, {
+          method: "POST",
+          body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code: code ?? "",
+            client_id: reg.client.clientId,
+            redirect_uri: "https://app.example/cb",
+            code_verifier: verifier,
+          }),
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      const tokenBody = (await tokenRes.json()) as {
+        access_token: string;
+        refresh_token: string;
+      };
+      const firstValidated = await validateAccessToken(db, tokenBody.access_token, ISSUER);
+      expect(firstValidated.payload.vault_scope).toEqual(["default"]);
+
+      // Step 2: refresh the token; vault_scope should still be ["default"].
+      const refreshRes = await handleToken(
+        db,
+        new Request(`${ISSUER}/oauth/token`, {
+          method: "POST",
+          body: new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: tokenBody.refresh_token,
+            client_id: reg.client.clientId,
+          }),
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+        }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      const refreshBody = (await refreshRes.json()) as { access_token: string };
+      const refreshedValidated = await validateAccessToken(db, refreshBody.access_token, ISSUER);
+      expect(refreshedValidated.payload.vault_scope).toEqual(["default"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  // Reviewer nit N3 (PR #283): the previous test only verified that
+  // `vault_scope` SURVIVES refresh — it didn't prove the claim is re-derived
+  // mid-session if an admin changes the user's `assigned_vault`. This test
+  // pins the actual "re-derived at refresh time" invariant by mutating the
+  // assignment between mint and refresh, then asserting the new token
+  // carries the post-mutation value. The `scope` claim itself stays
+  // narrowed to the original vault (it was set at consent time and stored
+  // on the refresh-token row); only the informational `vault_scope` claim
+  // tracks the live row.
+  test("refresh flow picks up a mid-session assigned_vault change", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const bob = await createUser(db, "bob", "pw", { assignedVault: "vault-a" });
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { verifier, challenge } = makePkce();
+
+      // Manifest fixture: both vault-a (initial assignment) and vault-b
+      // (post-admin-update assignment) are registered. PR 4 doesn't ship
+      // a PATCH endpoint, so we use the same direct UPDATE the design
+      // anticipates an admin path would call.
+      const twoVaultManifest: ServicesManifest = {
+        services: [
+          {
+            name: "parachute-vault",
+            port: 1940,
+            paths: ["/vault/vault-a", "/vault/vault-b"],
+            health: "/health",
+            version: "0.3.0",
+          },
+        ],
+      };
+
+      // Step 1: initial OAuth dance + token mint. Asserts vault_scope=["vault-a"].
+      const consentForm = new URLSearchParams({
+        __action: "consent",
+        __csrf: TEST_CSRF,
+        approve: "yes",
+        client_id: reg.client.clientId,
+        redirect_uri: "https://app.example/cb",
+        response_type: "code",
+        scope: "vault:read",
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        vault_pick: "vault-a",
+      });
+      const consentRes = await handleAuthorizePost(
+        db,
+        new Request(`${ISSUER}/oauth/authorize`, {
+          method: "POST",
+          body: consentForm,
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, 86400)}`,
+          },
+        }),
+        { issuer: ISSUER, loadServicesManifest: () => twoVaultManifest },
+      );
+      const code = new URL(consentRes.headers.get("location") ?? "").searchParams.get("code");
+      const tokenRes = await handleToken(
+        db,
+        new Request(`${ISSUER}/oauth/token`, {
+          method: "POST",
+          body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code: code ?? "",
+            client_id: reg.client.clientId,
+            redirect_uri: "https://app.example/cb",
+            code_verifier: verifier,
+          }),
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+        }),
+        { issuer: ISSUER, loadServicesManifest: () => twoVaultManifest },
+      );
+      const tokenBody = (await tokenRes.json()) as {
+        access_token: string;
+        refresh_token: string;
+      };
+      const initial = await validateAccessToken(db, tokenBody.access_token, ISSUER);
+      expect(initial.payload.vault_scope).toEqual(["vault-a"]);
+      expect(initial.payload.scope).toBe("vault:vault-a:read");
+
+      // Step 2: admin updates bob's assigned_vault to vault-b. Direct UPDATE
+      // because Phase 1 has no PATCH endpoint; same effect a future admin
+      // path would have. The refresh path reads the live row at mint time
+      // (`vaultScopeForUser`), so the next refresh should pick up the new
+      // value.
+      db.prepare("UPDATE users SET assigned_vault = ? WHERE id = ?").run("vault-b", bob.id);
+
+      // Step 3: refresh the token. vault_scope should be ["vault-b"] (the
+      // new live value); the `scope` claim stays narrowed to the original
+      // vault (auth-code grant snapshotted it onto the refresh-token row).
+      const refreshRes = await handleToken(
+        db,
+        new Request(`${ISSUER}/oauth/token`, {
+          method: "POST",
+          body: new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: tokenBody.refresh_token,
+            client_id: reg.client.clientId,
+          }),
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+        }),
+        { issuer: ISSUER, loadServicesManifest: () => twoVaultManifest },
+      );
+      expect(refreshRes.status).toBe(200);
+      const refreshBody = (await refreshRes.json()) as { access_token: string };
+      const refreshed = await validateAccessToken(db, refreshBody.access_token, ISSUER);
+      expect(refreshed.payload.vault_scope).toEqual(["vault-b"]);
+      // The `scope` claim is still bound to the original consent — the
+      // refresh-token row carries `vault:vault-a:read` and the rotation
+      // preserves it. PR 5 will be the side that enforces "your access
+      // tokens for the old vault stop working when the assignment moves";
+      // PR 4 just emits the informational claim correctly.
+      expect(refreshed.payload.scope).toBe("vault:vault-a:read");
+    } finally {
+      cleanup();
+    }
+  });
+});