@openparachute/hub 0.6.3 → 0.6.4-rc.1

package/src/__tests__/hub-server.test.ts

@@ -15,6 +15,7 @@ import {
 } from "../hub-server.ts";
 import { setNotesRedirectDisabled } from "../hub-settings.ts";
 import { clearNotesRedirectLogState } from "../notes-redirect.ts";
+import { mintOperatorToken } from "../operator-token.ts";
 import { pidPath } from "../process-state.ts";
 import { type ServiceEntry, writeManifest } from "../services-manifest.ts";
 import { buildSessionCookie, createSession } from "../sessions.ts";
@@ -530,9 +531,13 @@ describe("hubFetch routing", () => {
     const h = makeHarness();
     try {
       writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
-      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
-        new Request("http://127.0.0.1:1939/.well-known/parachute.json"),
-      );
+      const res = await hubFetch(h.dir, {
+        manifestPath: h.manifestPath,
+        // No exposure recorded — isolate from the host's real expose-state.json
+        // so the request-origin fallback (not the #531 expose tier) is what
+        // this test exercises.
+        loadExposeHubOrigin: () => undefined,
+      })(new Request("http://127.0.0.1:1939/.well-known/parachute.json"));
       const body = (await res.json()) as { vaults: Array<{ url: string }> };
       expect(body.vaults[0]?.url).toBe("http://127.0.0.1:1939/vault/default");
     } finally {
@@ -3195,13 +3200,46 @@ describe("hubFetch /<svc>/* generic proxy dispatch (#182)", () => {
   });
 });
 
-describe("layerOf — classify trust layer from proxy headers", () => {
-  // Hub binds 127.0.0.1:1939; only trusted forwarders (cloudflared,
-  // tailscaled-serve, tailscaled-funnel) reach the listener. Spoofing isn't
-  // a concern. layerOf inspects the headers each forwarder injects.
+describe("layerOf — classify trust layer from proxy headers + peer (item E / #526)", () => {
+  // Proxy headers (cloudflared, tailscale serve/funnel) take precedence. When
+  // absent, the PEER ADDRESS is the loopback discriminator — header-absence is
+  // no longer a loopback signal (#526). The peer-address is the 2nd arg.
+
+  test("no proxy headers + loopback peer (127.0.0.1) → loopback (on-box CLI)", () => {
+    expect(layerOf(req("/"), "127.0.0.1")).toBe("loopback");
+  });
 
-  test("no proxy headers → loopback (direct localhost call)", () => {
-    expect(layerOf(req("/"))).toBe("loopback");
+  test("no proxy headers + IPv6 loopback peer (::1) → loopback", () => {
+    expect(layerOf(req("/"), "::1")).toBe("loopback");
+  });
+
+  test("no proxy headers + IPv4-mapped IPv6 loopback (::ffff:127.0.0.1) → loopback", () => {
+    expect(layerOf(req("/"), "::ffff:127.0.0.1")).toBe("loopback");
+  });
+
+  // THE FIX: a header-absent NON-loopback peer (the 0.0.0.0-bind direct-network
+  // case) must NOT be classified loopback — it would bypass the
+  // publicExposure:loopback 404-cloak. Fail to public (least-trusted).
+  test("no proxy headers + non-loopback peer → public (NOT loopback) [#526]", () => {
+    expect(layerOf(req("/"), "203.0.113.7")).toBe("public");
+    expect(layerOf(req("/"), "10.0.0.5")).toBe("public");
+    expect(layerOf(req("/"), "fd00::1234")).toBe("public");
+  });
+
+  // Fail-closed: an unknown peer (no Server threaded — null/undefined) is NOT
+  // loopback. A direct unit call to the fetch fn with no server lands here.
+  test("no proxy headers + unknown peer (null/undefined) → public (fail closed)", () => {
+    expect(layerOf(req("/"), null)).toBe("public");
+    expect(layerOf(req("/"), undefined)).toBe("public");
+    expect(layerOf(req("/"))).toBe("public");
+  });
+
+  // Headers still win over peer address — a tailnet/public forwarder sets the
+  // header and the peer (the local tailscaled/cloudflared) is loopback, but the
+  // header is authoritative.
+  test("Tailscale-User-Login → tailnet even from a loopback peer", () => {
+    const r = req("/", { headers: { "Tailscale-User-Login": "alice@example.com" } });
+    expect(layerOf(r, "127.0.0.1")).toBe("tailnet");
   });
 
   test("Tailscale-User-Login → tailnet (authed via tailscale serve)", () => {
@@ -3266,6 +3304,11 @@ describe("hubFetch publicExposure layer-gate (proxyToService)", () => {
     return { port: server.port as number, stop: () => server.stop(true) };
   }
 
+  // Fake Bun Server handle exposing only `requestIP` (item E / #526) so the
+  // fetch fn can resolve the peer address. The on-box CLI caller connects from
+  // 127.0.0.1; a network peer on a 0.0.0.0 bind connects from its real IP.
+  const fakeServer = (address: string) => ({ requestIP: () => ({ address }) });
+
   test("publicExposure: loopback + tailnet header → 404 (gate hides the route)", async () => {
     const h = makeHarness();
     const upstream = startUpstream("loopback-only");
@@ -3326,7 +3369,7 @@ describe("hubFetch publicExposure layer-gate (proxyToService)", () => {
     }
   });
 
-  test("publicExposure: loopback + no headers → reaches upstream (loopback layer)", async () => {
+  test("publicExposure: loopback + no headers + loopback peer → reaches upstream (loopback layer)", async () => {
     const h = makeHarness();
     const upstream = startUpstream("loopback-only");
     try {
@@ -3346,7 +3389,8 @@ describe("hubFetch publicExposure layer-gate (proxyToService)", () => {
         h.manifestPath,
       );
       const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
-      const res = await fetcher(req("/loopback-only/health"));
+      // On-box CLI caller: 127.0.0.1 peer, no proxy headers → loopback layer.
+      const res = await fetcher(req("/loopback-only/health"), fakeServer("127.0.0.1"));
       expect(res.status).toBe(200);
       const body = (await res.json()) as { tag: string };
       expect(body.tag).toBe("loopback-only");
@@ -3356,6 +3400,37 @@ describe("hubFetch publicExposure layer-gate (proxyToService)", () => {
     }
   });
 
+  // Item E / #526 — the core fix. On a 0.0.0.0 bind a network peer reaches the
+  // listener with NO proxy headers; it must NOT be treated as loopback, so the
+  // loopback-exposure cloak still fires (404) rather than leaking the route.
+  test("publicExposure: loopback + no headers + NON-loopback peer → 404 (cloak fires) [#526]", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("loopback-only");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "loopback-only",
+              port: upstream.port,
+              paths: ["/loopback-only"],
+              health: "/loopback-only/health",
+              version: "0.1.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/loopback-only/health"), fakeServer("203.0.113.9"));
+      expect(res.status).toBe(404);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
   test("publicExposure: allowed + tailnet header → reaches upstream (no gate)", async () => {
     const h = makeHarness();
     const upstream = startUpstream("allowed");
@@ -3514,6 +3589,10 @@ describe("hubFetch publicExposure layer-gate (proxyToVault)", () => {
     return { port: server.port as number, stop: () => server.stop(true) };
   }
 
+  // Item E / #526 — fake Bun Server handle exposing `requestIP` for the peer-
+  // address discriminator (see the proxyToService block for the rationale).
+  const fakeServer = (address: string) => ({ requestIP: () => ({ address }) });
+
   test("vault publicExposure: loopback + tailnet header → 404", async () => {
     const h = makeHarness();
     const upstream = startVaultUpstream("vault-private");
@@ -3545,7 +3624,7 @@ describe("hubFetch publicExposure layer-gate (proxyToVault)", () => {
     }
   });
 
-  test("vault publicExposure: loopback + no headers → reaches vault backend", async () => {
+  test("vault publicExposure: loopback + no headers + loopback peer → reaches vault backend", async () => {
     const h = makeHarness();
     const upstream = startVaultUpstream("vault-private");
     try {
@@ -3565,7 +3644,7 @@ describe("hubFetch publicExposure layer-gate (proxyToVault)", () => {
         h.manifestPath,
       );
       const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
-      const res = await fetcher(req("/vault/private/health"));
+      const res = await fetcher(req("/vault/private/health"), fakeServer("127.0.0.1"));
       expect(res.status).toBe(200);
       const body = (await res.json()) as { tag: string };
       expect(body.tag).toBe("vault-private");
@@ -3575,6 +3654,36 @@ describe("hubFetch publicExposure layer-gate (proxyToVault)", () => {
     }
   });
 
+  // Item E / #526 — vault-path symmetry: a header-absent NON-loopback peer on a
+  // 0.0.0.0 bind must NOT reach a loopback-exposed vault (cloak fires).
+  test("vault publicExposure: loopback + no headers + NON-loopback peer → 404 [#526]", async () => {
+    const h = makeHarness();
+    const upstream = startVaultUpstream("vault-private");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-private",
+              port: upstream.port,
+              paths: ["/vault/private"],
+              health: "/vault/private/health",
+              version: "0.4.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/private/health"), fakeServer("198.51.100.4"));
+      expect(res.status).toBe(404);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
   test("vault publicExposure: allowed + tailnet header → reaches backend", async () => {
     const h = makeHarness();
     const upstream = startVaultUpstream("vault-public");
@@ -4185,6 +4294,9 @@ describe("POST /account/vault-token/<name> — friend scoped mint (routed end-to
     const friend = await createUser(db, "friend", "friend-password-123", {
       assignedVaults,
       allowMulti: true,
+      // Item F (#469): the friend mints a token only after rotating the temp
+      // password; an unrotated friend is force-redirected before any mint.
+      passwordChanged: true,
     });
     const session = createSession(db, { userId: friend.id });
     const csrf = generateCsrfToken();
@@ -4227,6 +4339,63 @@ describe("POST /account/vault-token/<name> — friend scoped mint (routed end-to
     }
   });
 
+  // Item F (#469) routed e2e — an assigned but unrotated friend is force-
+  // redirected to the change-password rail before any mint, through the real
+  // dispatch.
+  test("unrotated friend is force-change-gated, routed through hubFetch (item F / #469)", async () => {
+    // As of hub#469 the broad per-request gate (forceChangePasswordGate) is the
+    // choke point and intercepts BEFORE the per-route mint handler. A browser
+    // request (Accept: text/html) is 302'd to the change-password rail; an
+    // API-style POST without that header is 403 force_change_password. Both
+    // prove the unrotated friend can't parlay the temp password into a mint.
+    const h = makeHarness();
+    writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+    const db = openHubDb(hubDbPath(h.dir));
+    rotateSigningKey(db);
+    await createUser(db, "operator", "operator-password-123");
+    const friend = await createUser(db, "friend", "friend-password-123", {
+      assignedVaults: ["work"],
+      allowMulti: true,
+      passwordChanged: false, // not yet rotated
+    });
+    const session = createSession(db, { userId: friend.id });
+    const csrf = generateCsrfToken();
+    const cookie = `${buildSessionCookie(session.id, 3600, { secure: false })}; ${
+      buildCsrfCookie(csrf, { secure: false }).split(";")[0]
+    }`;
+    const fetcher = hubFetch(h.dir, {
+      getDb: () => db,
+      manifestPath: h.manifestPath,
+      issuer: "https://hub.test",
+    });
+    try {
+      // The mint is a POST (non-GET) → the gate rejects with 403
+      // force_change_password regardless of Accept, per the spec ("redirect
+      // browser GETs, reject non-GET / API-style requests with 403"). A 302 on
+      // a POST wouldn't usefully re-issue the mint anyway.
+      const apiRes = await fetcher(
+        req("/account/vault-token/work", {
+          method: "POST",
+          headers: { cookie, "content-type": "application/x-www-form-urlencoded" },
+          body: postBody(csrf, "read"),
+        }),
+      );
+      expect(apiRes.status).toBe(403);
+      expect(((await apiRes.json()) as { error: string }).error).toBe("force_change_password");
+
+      // The friend's browser GET of the account home IS bounced to the
+      // change-password rail — the surface they'd navigate to is gated.
+      const browserRes = await fetcher(
+        req("/account/", { headers: { cookie, accept: "text/html" } }),
+      );
+      expect(browserRes.status).toBe(302);
+      expect(browserRes.headers.get("location")).toBe("/account/change-password");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
   test("unassigned vault → 403, no token, routed through hubFetch", async () => {
     const h = makeHarness();
     writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
@@ -4269,6 +4438,73 @@ describe("POST /account/vault-token/<name> — friend scoped mint (routed end-to
   });
 });
 
+// Item D (#450) routed e2e — exercise the knownVaultNames threading from
+// services.json → hubFetch → handleApiMintToken (hub-server.ts dispatch),
+// which the unit-level handler tests can't cover. A `vault:<typo>:admin` mint
+// for an unregistered vault → 400 through the full stack; a known vault → 200.
+describe("POST /api/auth/mint-token — vault-existence threading (routed end-to-end, item D)", () => {
+  const ISSUER = "https://hub.test";
+
+  async function seedMint(
+    h: Harness,
+    vaultNames: string[],
+  ): Promise<{ db: ReturnType<typeof openHubDb>; bearer: string }> {
+    const db = openHubDb(hubDbPath(h.dir));
+    rotateSigningKey(db); // mint needs an active signing key
+    const owner = await createUser(db, "owner", "owner-password-123");
+    // The default operator scope-set carries parachute:host:admin, which mints
+    // vault:<name>:admin (canGrant rule 2).
+    const op = await mintOperatorToken(db, owner.id, { issuer: ISSUER });
+    writeManifest({ services: vaultNames.map((n) => vaultEntry(n)) }, h.manifestPath);
+    return { db, bearer: op.token };
+  }
+
+  function mintReq(scope: string, bearer: string): Request {
+    return req("/api/auth/mint-token", {
+      method: "POST",
+      headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json" },
+      body: JSON.stringify({ scope }),
+    });
+  }
+
+  test("vault:<typo>:admin for an unregistered vault → 400 (knownVaultNames from services.json)", async () => {
+    const h = makeHarness();
+    const { db, bearer } = await seedMint(h, ["work", "default"]);
+    try {
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        issuer: ISSUER,
+      })(mintReq("vault:typo:admin", bearer));
+      expect(res.status).toBe(400);
+      const body = (await res.json()) as { error: string; error_description: string };
+      expect(body.error).toBe("invalid_scope");
+      expect(body.error_description).toContain("typo");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("vault:<name>:admin for a REGISTERED vault → 200 (proves the gate isn't over-blocking)", async () => {
+    const h = makeHarness();
+    const { db, bearer } = await seedMint(h, ["work", "default"]);
+    try {
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        issuer: ISSUER,
+      })(mintReq("vault:work:admin", bearer));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { scope: string };
+      expect(body.scope).toBe("vault:work:admin");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+});
+
 describe("hubFetch routing — /api/hub/upgrade (D4 SPA hub-upgrade)", () => {
   test("POST /api/hub/upgrade dispatches to the handler (401 without bearer, NOT 404)", async () => {
     const h = makeHarness();
@@ -4332,3 +4568,382 @@ describe("hubFetch routing — /api/hub/upgrade (D4 SPA hub-upgrade)", () => {
     }
   });
 });
+
+// Per-request force-change-password enforcement (P0-1 / hub#469). The redirect
+// at /login was never enough: a signed-in user holding an admin-set temp
+// password (`password_changed=false`) could navigate DIRECTLY to /account/* or
+// a per-vault proxy URL and operate indefinitely on the un-rotated secret.
+// These tests pin the broad per-request gate: pre-rotation users are bounced
+// off every /account/* surface AND the per-vault proxy, EXCEPT the rotation/exit
+// path (/account/change-password + /logout); after rotation all surfaces open.
+describe("force-change-password per-request gate (#469)", () => {
+  // Seed a signed-in user with a chosen password_changed flag and return a
+  // ready-to-use session cookie. Mirrors the seedFriend helpers in the
+  // account-vault-{token,admin-token} suites.
+  async function seedUser(
+    h: Harness,
+    db: ReturnType<typeof openHubDb>,
+    opts: { passwordChanged: boolean; assignedVaults?: string[] },
+  ): Promise<{ cookie: string }> {
+    const { SESSION_TTL_MS } = await import("../sessions.ts");
+    const user = await createUser(db, "friend", "temp-pw", {
+      allowMulti: true,
+      passwordChanged: opts.passwordChanged,
+      assignedVaults: opts.assignedVaults ?? [],
+    });
+    const session = createSession(db, { userId: user.id });
+    const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+    return { cookie };
+  }
+
+  test("(a) pre-rotation browser GET /account/ is 302'd to change-password", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: false,
+          assignedVaults: ["work"],
+        });
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/account/", { headers: { cookie, accept: "text/html" } }),
+        );
+        expect(res.status).toBe(302);
+        expect(res.headers.get("location")).toBe("/account/change-password");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(a) pre-rotation API POST /account/vault-token/<name> is 403 force_change_password", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: false,
+          assignedVaults: ["work"],
+        });
+        // No Accept: text/html → treated as an API client → 403 JSON, not a 302.
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/account/vault-token/work", { method: "POST", headers: { cookie } }),
+        );
+        expect(res.status).toBe(403);
+        const body = (await res.json()) as { error: string };
+        expect(body.error).toBe("force_change_password");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(a) pre-rotation browser GET of a per-vault proxy URL is 302'd to change-password", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: false,
+          assignedVaults: ["work"],
+        });
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/vault/work/notes/abc", { headers: { cookie, accept: "text/html" } }),
+        );
+        // Gated BEFORE the proxy ever runs — so this is the gate's 302, not a
+        // proxy 404/502.
+        expect(res.status).toBe(302);
+        expect(res.headers.get("location")).toBe("/account/change-password");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(b) pre-rotation user CAN still reach /account/change-password (GET)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: false,
+          assignedVaults: ["work"],
+        });
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/account/change-password", { headers: { cookie, accept: "text/html" } }),
+        );
+        // Reaches the real handler (200 form render) — NOT bounced to itself.
+        expect(res.status).toBe(200);
+        const body = await res.text();
+        expect(body.toLowerCase()).toContain("password");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(b) pre-rotation user CAN still reach /logout (POST)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: false,
+          assignedVaults: ["work"],
+        });
+        // CSRF cookie + matching field so the logout POST passes its own gate;
+        // the point is the force-change gate does NOT intercept /logout.
+        const csrf = generateCsrfToken();
+        const form = new URLSearchParams();
+        form.set("__csrf", csrf);
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/logout", {
+            method: "POST",
+            headers: {
+              cookie: `${cookie}; ${buildCsrfCookie(csrf)}`,
+              "content-type": "application/x-www-form-urlencoded",
+            },
+            body: form.toString(),
+          }),
+        );
+        // Logout succeeds (302 to /) — it is NOT the force-change 302 to
+        // /account/change-password and NOT a 403.
+        expect(res.status).toBe(302);
+        expect(res.headers.get("location")).not.toBe("/account/change-password");
+        expect(res.status).not.toBe(403);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(c) after rotation, /account/ is reachable (not gated)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: true,
+          assignedVaults: ["work"],
+        });
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/account/", { headers: { cookie, accept: "text/html" } }),
+        );
+        // Account home renders — not bounced.
+        expect(res.status).toBe(200);
+        expect(res.headers.get("location")).not.toBe("/account/change-password");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(c) after rotation, a per-vault proxy URL is NOT gated (reaches the proxy)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: true,
+          assignedVaults: ["work"],
+        });
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/vault/work/notes/abc", { headers: { cookie, accept: "text/html" } }),
+        );
+        // No upstream listening → the proxy returns a 404/502, NOT the gate's
+        // 302→change-password / 403. The point is the gate let it through.
+        expect(res.headers.get("location")).not.toBe("/account/change-password");
+        const body = res.status === 403 ? ((await res.json()) as { error?: string }) : null;
+        expect(body?.error).not.toBe("force_change_password");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("an UNAUTHENTICATED per-vault proxy request is NOT gated (no hub session)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        // No cookie at all — the common Notes/MCP case carrying its own bearer.
+        // forceChangePasswordGate returns null (no session) → proxy handles it.
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/vault/work/notes/abc", { headers: { accept: "text/html" } }),
+        );
+        expect(res.headers.get("location")).not.toBe("/account/change-password");
+        expect(res.status).not.toBe(403);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(b) pre-rotation user CAN POST /account/change-password (the rotation action itself)", async () => {
+    // The exempt POST: a pre-rotation user submitting their new password must
+    // NOT be intercepted by the gate — it's the only way out of force-change.
+    // `/account/change-password` is dispatched ABOVE the gate, so it never
+    // reaches the choke point. We assert the POST reaches its own handler (it
+    // fails CSRF here → its OWN 400/403, NOT the gate's 302→change-password).
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: false,
+          assignedVaults: ["work"],
+        });
+        const csrf = generateCsrfToken();
+        const form = new URLSearchParams();
+        form.set("__csrf", csrf);
+        form.set("current_password", "temp-pw");
+        form.set("new_password", "rotated-password-123");
+        form.set("new_password_confirm", "rotated-password-123");
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/account/change-password", {
+            method: "POST",
+            headers: {
+              cookie: `${cookie}; ${buildCsrfCookie(csrf)}`,
+              "content-type": "application/x-www-form-urlencoded",
+              accept: "text/html",
+            },
+            body: form.toString(),
+          }),
+        );
+        // Reaches its own handler (303 back to /account/ on success, or its own
+        // form re-render). The point: it is NOT the gate's 302 to
+        // change-password and NOT the gate's 403 force_change_password.
+        expect(res.status).not.toBe(403);
+        if (res.status === 302 || res.status === 303) {
+          expect(res.headers.get("location")).not.toBe("/account/change-password");
+        }
+        // And the rotation actually took: the user's flag flipped to true.
+        const { getUserById } = await import("../users.ts");
+        const friend = getUserById(
+          db,
+          db.query<{ id: string }, []>("SELECT id FROM users WHERE username = 'friend'").get()
+            ?.id ?? "",
+        );
+        expect(friend?.passwordChanged).toBe(true);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(a) bare /account (no trailing slash) is gated on the FIRST hop for a pre-rotation user", async () => {
+    // The bare `/account` 301s to `/account/`; without an explicit match it
+    // would slip past `startsWith("/account/")` and only be gated on the second
+    // hop. The gate must intercept the first request.
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: false,
+          assignedVaults: ["work"],
+        });
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/account", { headers: { cookie, accept: "text/html" } }),
+        );
+        // Gated → 302 to change-password, NOT the 301 → /account/.
+        expect(res.status).toBe(302);
+        expect(res.headers.get("location")).toBe("/account/change-password");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(a) pre-rotation session at /oauth/authorize is 302'd to change-password (no auth code issued)", async () => {
+    // The important one: a signed-in pre-rotation user must not ride the
+    // consent flow to an auth code → /oauth/token exchange for a vault token
+    // WITHOUT rotating. The gate intercepts /oauth/authorize before any client
+    // validation or code issuance, so no `code=` redirect can be produced.
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: false,
+          assignedVaults: ["work"],
+        });
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req(
+            "/oauth/authorize?client_id=x&response_type=code&redirect_uri=https://app.example/cb&scope=vault:work:read",
+            { headers: { cookie, accept: "text/html" } },
+          ),
+        );
+        expect(res.status).toBe(302);
+        const location = res.headers.get("location") ?? "";
+        expect(location).toBe("/account/change-password");
+        // No auth code was issued — the redirect is to the rotation rail, not a
+        // client callback carrying a `code=`.
+        expect(location).not.toContain("code=");
+        expect(location).not.toContain("app.example");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(c) after rotation, /oauth/authorize is NOT gated (reaches the oauth handler)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: true,
+          assignedVaults: ["work"],
+        });
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req(
+            "/oauth/authorize?client_id=x&response_type=code&redirect_uri=https://app.example/cb&scope=vault:work:read",
+            { headers: { cookie, accept: "text/html" } },
+          ),
+        );
+        // Reaches the real authorize handler (login/consent/error) — NOT bounced
+        // to the change-password rail by the gate.
+        expect(res.headers.get("location")).not.toBe("/account/change-password");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+});