@openparachute/hub 0.6.3 → 0.6.4-rc.1

package/src/hub-server.ts

@@ -78,7 +78,13 @@
  *   /account/change-password      (GET + POST) → user self-service change-password
  *                                                 (force-redirect target for users
  *                                                 with password_changed=false; also
- *                                                 reachable directly to rotate)
+ *                                                 reachable directly to rotate). With
+ *                                                 hub#469, EVERY other /account/* route
+ *                                                 + the per-vault proxy is hard-gated
+ *                                                 per-request on password_changed===true
+ *                                                 (forceChangePasswordGate); only this
+ *                                                 route and /logout stay reachable
+ *                                                 pre-rotation.
  *   /account/2fa                  (GET + POST) → user self-service 2FA enroll/disenroll
  *                                                 (hub#473; QR + backup codes)
  *   /account/vault-token/<name>   (POST)       → friend mints a scoped
@@ -121,6 +127,8 @@ import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import pkg from "../package.json" with { type: "json" };
+import { handleAccountSetupGet, handleAccountSetupPost } from "./account-setup.ts";
+import { handleAccountVaultAdminTokenPost } from "./account-vault-admin-token.ts";
 import { handleAccountVaultTokenPost } from "./account-vault-token.ts";
 import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
 import { handleListGrants, handleRevokeGrant } from "./admin-grants.ts";
@@ -140,6 +148,7 @@ import {
 } from "./api-account.ts";
 import { handleHubUpgrade, handleHubUpgradeStatus } from "./api-hub-upgrade.ts";
 import { handleApiHub } from "./api-hub.ts";
+import { handleCreateInvite, handleListInvites, handleRevokeInvite } from "./api-invites.ts";
 import { handleApiMe } from "./api-me.ts";
 import { handleApiMintToken } from "./api-mint-token.ts";
 import { handleApiModulesConfig, parseModulesConfigPath } from "./api-modules-config.ts";
@@ -220,6 +229,7 @@ import { getAllPublicKeys } from "./signing-keys.ts";
 import type { Supervisor } from "./supervisor.ts";
 import { handleTwoFactorGet, handleTwoFactorPost } from "./two-factor-handlers.ts";
 import { getUserById, userCount } from "./users.ts";
+import { sanitizePublicOrigin } from "./vault-hub-origin-env.ts";
 import {
   WELL_KNOWN_DIR,
   buildWellKnown,
@@ -428,19 +438,31 @@ export type RequestLayer = "loopback" | "tailnet" | "public";
  *   - `CF-Ray` and `CF-Connecting-IP` are set by Cloudflare's edge for
  *     anything proxied through a cloudflared tunnel.
  *
- * Spoofing isn't a concern: hub binds `127.0.0.1:1939`, so external requests
- * can't reach the listener except via these trusted forwarders. Tailscale
- * specifically strips the same headers from incoming requests before
- * re-injecting them, so even a malicious tailnet peer can't impersonate a
- * different user. We could mirror that strip-on-arrival defense, but it's
- * belt-and-braces given the bind shape.
+ * Spoofing isn't a concern for the proxy-injected layers: the trusted
+ * forwarders (tailscale serve/funnel, cloudflared) set these headers and a
+ * peer can't forge them past the forwarder. Tailscale specifically strips the
+ * same headers from incoming requests before re-injecting them, so even a
+ * malicious tailnet peer can't impersonate a different user.
  *
- * Default to "loopback" when no proxy headers are present — that's the
- * direct-localhost case. Funnel without `Tailscale-Funnel-Request` would
- * also fall here, but Tailscale always sets the header on funneled
- * requests, so this branch only fires for true loopback callers.
+ * Header-absence is NOT a loopback signal (item E / hub#526). The old default
+ * returned "loopback" — the most-trusted layer — for any request with no proxy
+ * headers, on the premise (true only on a loopback bind) that "external
+ * requests can't reach the listener." Containers / Render legitimately bind
+ * `0.0.0.0`, where a network peer can reach the listener directly with no proxy
+ * headers and would be misclassified `loopback`, bypassing the
+ * `publicExposure:"loopback"` 404-cloak on `proxyToService` / `proxyToVault`.
+ *
+ * Fix: derive loopback from the actual PEER ADDRESS (`peerAddr`, resolved by
+ * the caller from `server.requestIP(req)` — `requestIP` lives on the Bun
+ * Server, not the Request; see rate-limit.ts:282-285). A header-absent request
+ * is `loopback` ONLY when its peer is `127.0.0.1` / `::1` (the on-box CLI
+ * caller, which must stay loopback). A header-absent NON-loopback peer is the
+ * untrusted direct-network case and is classified `public` (least-trusted) so
+ * the cloak fires. When `peerAddr` is unknown (null/undefined — no Server
+ * threaded, e.g. a unit test calling `layerOf(req)` directly), we fail CLOSED
+ * to `public` rather than open to `loopback`.
  */
-export function layerOf(req: Request): RequestLayer {
+export function layerOf(req: Request, peerAddr?: string | null): RequestLayer {
   const h = req.headers;
   if (h.get("cf-ray") !== null || h.get("cf-connecting-ip") !== null) return "public";
   // Match the structured-header value (`?1`) rather than mere presence:
@@ -451,7 +473,22 @@ export function layerOf(req: Request): RequestLayer {
   // value to compare against, hence the presence-check above.
   if (h.get("tailscale-funnel-request") === "?1") return "public";
   if (h.get("tailscale-user-login") !== null) return "tailnet";
-  return "loopback";
+  // No proxy headers — classify by peer address, failing closed when unknown.
+  return isLoopbackPeer(peerAddr) ? "loopback" : "public";
+}
+
+/**
+ * True when `peerAddr` (a `server.requestIP(req)?.address`) is a loopback
+ * address. Handles the IPv4-mapped IPv6 form (`::ffff:127.0.0.1`) Bun can emit
+ * on a dual-stack listener. A null/undefined/unparseable address is NOT
+ * loopback — `layerOf` fails closed to `public` in that case.
+ */
+function isLoopbackPeer(peerAddr: string | null | undefined): boolean {
+  if (!peerAddr) return false;
+  const addr = peerAddr.trim().toLowerCase();
+  return (
+    addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1" || addr.startsWith("127.")
+  );
 }
 
 /**
@@ -586,6 +623,7 @@ async function proxyToVault(
   req: Request,
   manifestPath: string,
   supervisor: Supervisor | undefined,
+  peerAddr: string | null,
 ): Promise<Response | undefined> {
   // Lenient — see hub#406. One bad services.json row no longer takes
   // down vault routing the way it used to take down /admin/setup and
@@ -596,8 +634,13 @@ async function proxyToVault(
   if (!match) return undefined;
   // Layer-gate on `publicExposure: "loopback"` — hide the entry from non-
   // loopback callers as if it doesn't exist. "allowed" / "auth-required"
-  // pass through; the service does its own auth.
-  if (effectivePublicExposure(match.entry) === "loopback" && layerOf(req) !== "loopback") {
+  // pass through; the service does its own auth. `peerAddr` (item E / #526)
+  // is the loopback discriminator: a header-absent NON-loopback peer is NOT
+  // loopback, so the cloak fires on a 0.0.0.0 bind.
+  if (
+    effectivePublicExposure(match.entry) === "loopback" &&
+    layerOf(req, peerAddr) !== "loopback"
+  ) {
     return new Response("not found", { status: 404 });
   }
   // Symmetry with proxyToService (#196): honor `stripPrefix` with FIRST_-
@@ -671,6 +714,7 @@ async function proxyToService(
   req: Request,
   manifestPath: string,
   supervisor: Supervisor | undefined,
+  peerAddr: string | null,
 ): Promise<Response | undefined> {
   // Lenient read on the hot-path — a single malformed services.json
   // entry (e.g. a module installed at a buggy version that wrote
@@ -692,8 +736,11 @@ async function proxyToService(
   // tailnet/public caller, a loopback-only service must be indistinguishable
   // from "not installed" — 404, not 403, so we don't leak the existence of
   // the route. "allowed" / "auth-required" pass through; the service does
-  // its own auth.
-  if (effectivePublicExposure(match.entry) === "loopback" && layerOf(req) !== "loopback") {
+  // its own auth. `peerAddr` (item E / #526) is the loopback discriminator.
+  if (
+    effectivePublicExposure(match.entry) === "loopback" &&
+    layerOf(req, peerAddr) !== "loopback"
+  ) {
     return new Response("not found", { status: 404 });
   }
   // Consult FIRST_PARTY_FALLBACKS as a fallback for `stripPrefix` (#196).
@@ -788,12 +835,20 @@ export interface HubFetchDeps {
    */
   loopbackPort?: number;
   /**
-   * Test seam for reading `expose-state.json`. Production reads the operator's
-   * `~/.parachute/expose-state.json` via `readExposeState`; tests inject a
-   * fake to drive tailnet/funnel origins into the bound set without standing
-   * up real exposes. Returns `undefined` when no state file is present
-   * (pre-`parachute expose` state — fine, the issuer + loopback still cover
-   * legitimate access).
+   * Test seam for reading `expose-state.json`'s `hubOrigin`. Production reads
+   * the operator's `~/.parachute/expose-state.json` via `readExposeState`;
+   * tests inject a fake to drive tailnet/funnel origins into the bound set
+   * without standing up real exposes. Returns `undefined` when no state file
+   * is present (pre-`parachute expose` state — fine, the issuer + loopback
+   * still cover legitimate access).
+   *
+   * This single seam now feeds BOTH (a) the same-origin bound set via
+   * `buildHubBoundOrigins`, and (b) the issuer resolution via `resolveIssuer`
+   * (#531): on the reboot-persistent owner-operated path the launchd /
+   * systemd unit carries no `PARACHUTE_HUB_ORIGIN`, so the hub boots with no
+   * `configuredIssuer` and falls back to this exposed origin rather than
+   * stamping `iss` from the per-request (loopback) origin — which exposed
+   * resource servers (vault) reject until they restart.
    */
   loadExposeHubOrigin?: () => string | undefined;
   /**
@@ -1038,6 +1093,13 @@ async function serveSpa(spaDistDir: string, pathname: string, mount: SpaMount):
  * regular dispatch continues.
  */
 function shouldGateForSetup(pathname: string): boolean {
+  // Invite redemption (`/account/setup/<token>`) is an un-authed onboarding
+  // surface like the wizard — it must pass through the pre-admin lockout so a
+  // recipient can claim an invite. (In practice invites can only be issued
+  // after an admin exists, so the no-admin lockout rarely coincides; the
+  // explicit pass-through keeps the surface's posture clear + matches the
+  // wizard's `/admin/setup/*` exemption.)
+  if (pathname === "/account/setup" || pathname.startsWith("/account/setup/")) return false;
   if (pathname === "/login" || pathname === "/logout") return true;
   // The wizard itself + its POST endpoints are the *only* way to exit
   // the pre-admin lockout from a browser — they must pass through. Any
@@ -1068,38 +1130,95 @@ function dbNotConfigured(): Response {
   );
 }
 
+/**
+ * Read the exposed public origin off `expose-state.json` for the issuer
+ * fallback, guarded to a non-loopback http(s) origin and malformed-safe.
+ * Returns undefined when no exposure is recorded, the file is corrupt, or
+ * the recorded origin is loopback / not an http(s) URL (a loopback value
+ * here would re-pin the degraded request-origin mode — expose-state should
+ * never carry one, but we defend anyway). This is the seam the launchd /
+ * systemd reboot path leans on: those units carry no `PARACHUTE_HUB_ORIGIN`,
+ * so without it the hub boots issuer-less and stamps `iss` from the
+ * per-request origin, which exposed resource servers (vault) reject.
+ *
+ * The `readExpose()` call is itself wrapped in try/catch so ANY reader —
+ * the default OR an injected one — that throws yields undefined rather than
+ * propagating into the request path. The default reader self-wraps too, but
+ * the seam must not depend on that: a future caller passing a non-swallowing
+ * reader still can't 500 the hub. Origin sanitization is delegated to the
+ * shared `sanitizePublicOrigin` helper (strips trailing slashes, validates
+ * http(s), rejects loopback), kept identical with resolveStartupIssuer (#531).
+ */
+export function exposeIssuerOrigin(
+  readExpose: () => string | undefined = defaultExposeHubOriginRead,
+): string | undefined {
+  let raw: string | undefined;
+  try {
+    raw = readExpose();
+  } catch {
+    return undefined;
+  }
+  return sanitizePublicOrigin(raw);
+}
+
+function defaultExposeHubOriginRead(): string | undefined {
+  try {
+    return readExposeState()?.hubOrigin;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Resolve the OAuth issuer URL for this request. Precedence, highest
- * first (hub#298):
+ * first (hub#298, expose tier added #531):
  *
  *   1. `hub_settings.hub_origin` — operator-set canonical URL from the
  *      admin SPA. Wins when present.
  *   2. `configuredIssuer` — `--issuer` flag or `PARACHUTE_HUB_ORIGIN`
  *      env var captured at hub start. The deploy-time setting.
- *   3. `new URL(req.url).origin` — the request's own origin. Local dev
+ *   3. `expose-state.json`'s `hubOrigin` — the canonical public origin a
+ *      live tailscale/cloudflare exposure recorded. Load-bearing for the
+ *      reboot-persistent owner-operated path: the launchd plist / systemd
+ *      unit carries no `PARACHUTE_HUB_ORIGIN`, so a hub booted off it has
+ *      no `configuredIssuer` and would otherwise stamp `iss` from the
+ *      per-request origin — which exposed resource servers (vault) reject
+ *      with `unexpected "iss" claim value` until they restart. Reading the
+ *      exposed origin off disk closes that. Guarded non-loopback http(s)
+ *      (see `exposeIssuerOrigin`).
+ *   4. `new URL(req.url).origin` — the request's own origin. Local dev
  *      + Render-assigned subdomains land here when nothing's been
  *      configured.
  *
  * Per-request (not cached at hub start) so a PUT to
  * `/api/settings/hub-origin` takes effect on the next request without a
- * restart. The hub_settings read is a single small SQLite query — cheap
- * relative to JWT signing on the same request path.
+ * restart. Both the hub_settings read and the expose-state read are cheap
+ * (a small SQLite query / a small JSON parse) relative to JWT signing on
+ * the same request path — and the expose read is per-request so an operator
+ * who runs `parachute expose` while the hub is up gets the new origin on the
+ * next request without a restart.
  *
  * `db` is optional because the wellknown / discovery surfaces are
  * reachable on a hub with no DB configured (the dbNotConfigured 503
  * gate sits behind these in the dispatcher). In that case we skip the
- * settings layer and fall through to env/request precedence.
+ * settings layer and fall through to env/expose/request precedence.
+ *
+ * `readExpose` is injectable so tests exercise the expose tier without
+ * touching the real `~/.parachute`.
  */
 export function resolveIssuer(
   req: Request,
   db: Database | undefined,
   configuredIssuer: string | undefined,
+  readExpose: () => string | undefined = defaultExposeHubOriginRead,
 ): string {
   if (db !== undefined) {
     const stored = getHubOrigin(db);
     if (stored) return stored;
   }
   if (configuredIssuer) return configuredIssuer;
+  const exposed = exposeIssuerOrigin(readExpose);
+  if (exposed) return exposed;
   // Reverse-proxy aware: Render / Tailscale Funnel / cloudflared terminate
   // TLS at the edge and forward plain HTTP to hub. Without X-Forwarded-Proto
   // honoring, `req.url.origin` is `http://...` and hub publishes mixed-content
@@ -1128,23 +1247,96 @@ export function resolveIssuer(
 /**
  * Where did the resolved issuer come from? Drives the source-label
  * surfaced in the admin SPA so operators can tell which precedence
- * layer they're on without inspecting the DB or env.
+ * layer they're on without inspecting the DB or env. Mirrors the
+ * precedence in `resolveIssuer` exactly — settings > env > expose >
+ * request — so the attribution can't drift from the resolved value.
  */
-export type IssuerSource = "settings" | "env" | "request";
+export type IssuerSource = "settings" | "env" | "expose" | "request";
 
 export function resolveIssuerSource(
   db: Database | undefined,
   configuredIssuer: string | undefined,
+  readExpose: () => string | undefined = defaultExposeHubOriginRead,
 ): IssuerSource {
   if (db !== undefined && getHubOrigin(db)) return "settings";
   if (configuredIssuer) return "env";
+  if (exposeIssuerOrigin(readExpose)) return "expose";
   return "request";
 }
 
+/**
+ * Minimal structural type for the Bun `Server` handle the fetch callback
+ * receives as its 2nd argument. We only need `requestIP` (item E / #526) to
+ * resolve the peer address for `layerOf`. Typed structurally (rather than
+ * importing Bun's full `Server`) so tests can pass a tiny fake and so the
+ * signature stays robust to Bun type-shape churn. Optional in the callback
+ * because a direct unit call to the returned fetch fn may omit it — in which
+ * case `peerAddr` is null and `layerOf` fails closed to `public`.
+ */
+interface PeerIpResolver {
+  requestIP(req: Request): { address: string } | null;
+}
+
+/**
+ * Per-request force-change-password gate (P0-1 / hub#469).
+ *
+ * Before #469, `password_changed === false` only triggered a redirect at the
+ * `/login` step. A signed-in user handed an admin-set temp password could then
+ * navigate DIRECTLY to `/account/`, `/account/vault-token/<name>`, a vault-admin
+ * deep-link, or any per-vault proxy URL and operate INDEFINITELY on the
+ * un-rotated secret. Invites = temp-credential handoff at scale, so that gap
+ * scales with every invited user. This makes the gate per-request.
+ *
+ * Returns a 302/403 Response when the request must be bounced; `null` when the
+ * request may proceed (no session, password already rotated, or — for callers
+ * that pre-check — an exempt path). Resolution is a single session→user lookup,
+ * mirroring the per-route gates in `account-vault-{token,admin-token}.ts` so we
+ * don't add a second DB read on those paths (they keep their own gate; this is
+ * the broad net for everything else under `/account/*` + the vault proxy).
+ *
+ * EXEMPT (NOT gated — the rotation/exit path; callers must route these BEFORE
+ * invoking this gate): `/account/change-password` (GET+POST) and `/logout`.
+ * Everything else under `/account/*`, the per-vault `/vault/<name>/*` proxy,
+ * and the session-backed `/oauth/authorize` consent path is gated. The decision
+ * is deliberate: a pre-rotation user can ONLY rotate or sign out — no vault
+ * reads, no token mints, no account home, and no OAuth authorize → auth code →
+ * `/oauth/token` exchange for a vault-scoped access token.
+ *
+ * Browser GETs (Accept: text/html) get a 302 to `/account/change-password`;
+ * non-GET and API-style requests get a 403 with the same JSON error shape the
+ * per-route mints use, so a scripted client gets a clear machine-readable
+ * refusal rather than an HTML redirect it can't follow.
+ */
+export function forceChangePasswordGate(db: Database, req: Request): Response | null {
+  const session = findActiveSession(db, req);
+  if (!session) return null; // unauthenticated → downstream handler decides (401/login)
+  const user = getUserById(db, session.userId);
+  if (!user || user.passwordChanged) return null; // rotated (or vanished) → proceed
+
+  const wantsHtml = req.method === "GET" && (req.headers.get("accept") ?? "").includes("text/html");
+  if (wantsHtml) {
+    return new Response(null, {
+      status: 302,
+      headers: { location: "/account/change-password", "cache-control": "no-store" },
+    });
+  }
+  return new Response(
+    JSON.stringify({
+      error: "force_change_password",
+      error_description:
+        "You must change your temporary password before using this surface. Visit /account/change-password.",
+    }),
+    {
+      status: 403,
+      headers: { "content-type": "application/json", "cache-control": "no-store" },
+    },
+  );
+}
+
 export function hubFetch(
   wellKnownDir: string,
   deps?: HubFetchDeps,
-): (req: Request) => Response | Promise<Response> {
+): (req: Request, server?: PeerIpResolver) => Response | Promise<Response> {
   const hubHtmlPath = join(wellKnownDir, "hub.html");
   const getDb = deps?.getDb;
   const configuredIssuer = deps?.issuer;
@@ -1164,7 +1356,7 @@ export function hubFetch(
     });
 
   const oauthDeps = (req: Request) => {
-    const issuer = resolveIssuer(req, getDb?.(), configuredIssuer);
+    const issuer = resolveIssuer(req, getDb?.(), configuredIssuer, loadExposeHubOrigin);
     return {
       issuer,
       // Per-request resolution (closes #245): expose-state.json can change
@@ -1191,10 +1383,18 @@ export function hubFetch(
     };
   };
 
-  return async (req) => {
+  return async (req, server) => {
     const url = new URL(req.url);
     const pathname = url.pathname;
 
+    // Resolve the peer address ONCE per request (item E / #526). Bun's
+    // `requestIP` lives on the Server handle, not the Request. It's the
+    // loopback discriminator for `layerOf` on the loopback-exposure cloak —
+    // a header-absent non-loopback peer must NOT be treated as loopback.
+    // `server` is absent when a unit test calls this fn directly; `peerAddr`
+    // is then null and `layerOf` fails closed to `public`.
+    const peerAddr = server?.requestIP(req)?.address ?? null;
+
     // 301 back-compat for the pre-hub#231 admin-SPA mounts:
     //
     //   `/vault`            → `/admin/vaults`
@@ -1525,7 +1725,12 @@ export function hubFetch(
         // `/.well-known/parachute.json` while their JWTs carry the
         // canonical URL, and discovery clients would split-brain on
         // which one to trust.
-        const canonicalOrigin = resolveIssuer(req, getDb?.(), configuredIssuer);
+        const canonicalOrigin = resolveIssuer(
+          req,
+          getDb?.(),
+          configuredIssuer,
+          loadExposeHubOrigin,
+        );
         const readManifestFn = deps?.readModuleManifest ?? defaultReadModuleManifest;
         const [managementUrlByName, serviceUiMeta] = await Promise.all([
           loadManagementUrls(manifest.services, readManifestFn),
@@ -1651,6 +1856,17 @@ export function hubFetch(
     // See `src/cors.ts` for the wildcard-origin rationale.
     if (pathname === "/oauth/authorize") {
       if (!getDb) return applyCorsHeaders(req, dbNotConfigured());
+      // Per-request force-change-password gate (P0-1 / hub#469). CHOKE POINT 3:
+      // a signed-in pre-rotation user must NOT be able to ride the consent flow
+      // to an auth code → `/oauth/token` exchange → vault-scoped access token
+      // without rotating the temp password. Gating `/oauth/authorize` (the
+      // session-backed consent path) is sufficient — no code is issued without
+      // it, so `/oauth/token` (back-channel code exchange, no session cookie)
+      // is intentionally NOT gated (gating it would break the legitimate
+      // exchange). An UNAUTHENTICATED authorize request returns null from the
+      // gate and falls through to render the login form, unchanged.
+      const oauthGate = forceChangePasswordGate(getDb(), req);
+      if (oauthGate) return applyCorsHeaders(req, oauthGate);
       if (req.method === "GET") {
         // handleAuthorizeGet is sync (returns Response, not Promise<Response>).
         // handleAuthorizePost is async — keep the await on POST only.
@@ -1826,8 +2042,8 @@ export function hubFetch(
       return handleApiSettingsHubOrigin(req, {
         db,
         issuer: oauthDeps(req).issuer,
-        resolvedIssuer: resolveIssuer(req, db, configuredIssuer),
-        resolvedSource: resolveIssuerSource(db, configuredIssuer),
+        resolvedIssuer: resolveIssuer(req, db, configuredIssuer, loadExposeHubOrigin),
+        resolvedSource: resolveIssuerSource(db, configuredIssuer, loadExposeHubOrigin),
       });
     }
 
@@ -1933,9 +2149,20 @@ export function hubFetch(
 
     if (pathname === "/api/auth/mint-token") {
       if (!getDb) return dbNotConfigured();
+      // Derive the set of registered vault names so the handler can reject a
+      // `vault:<typo>:admin` mint (item D / hub#450) — same source + shape the
+      // session-cookie `/admin/vault-admin-token/<name>` path uses. Lenient
+      // read so a malformed manifest doesn't 500 the mint endpoint.
+      const mintManifest = readManifestLenient(manifestPath);
+      const mintKnownVaultNames = new Set<string>();
+      for (const s of mintManifest.services) {
+        if (!isVaultEntry(s)) continue;
+        for (const path of s.paths) mintKnownVaultNames.add(vaultInstanceNameFor(s.name, path));
+      }
       return handleApiMintToken(req, {
         db: getDb(),
         issuer: oauthDeps(req).issuer,
+        knownVaultNames: mintKnownVaultNames,
       });
     }
 
@@ -2083,6 +2310,29 @@ export function hubFetch(
       });
     }
 
+    // One-time invite links (design §7). host:admin-gated, same gate flavor
+    // as /api/users. POST creates (returns the single-emit token + URL), GET
+    // lists (status-annotated), DELETE /:id revokes by sha256 hash.
+    if (pathname === "/api/invites") {
+      if (!getDb) return dbNotConfigured();
+      const invitesDeps = { db: getDb(), issuer: oauthDeps(req).issuer, manifestPath };
+      if (req.method === "GET") return handleListInvites(req, invitesDeps);
+      if (req.method === "POST") return handleCreateInvite(req, invitesDeps);
+      return new Response("method not allowed", { status: 405 });
+    }
+    if (pathname.startsWith("/api/invites/")) {
+      if (!getDb) return dbNotConfigured();
+      const id = decodeURIComponent(pathname.slice("/api/invites/".length));
+      if (!id || id.includes("/")) {
+        return new Response("not found", { status: 404 });
+      }
+      return handleRevokeInvite(req, id, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+        manifestPath,
+      });
+    }
+
     // Canonical login/logout. The handlers themselves are unchanged from
     // when they lived at /admin/login + /admin/logout; the rename surfaced
     // via #231-followup so the URL reflects the surface's actual scope
@@ -2113,6 +2363,27 @@ export function hubFetch(
       return handleAdminLogoutPost(getDb(), req);
     }
 
+    // Invite redemption — `/account/setup/<token>` (design §7). Un-authed
+    // onboarding surface (the invitee has no session yet); routed BEFORE the
+    // per-request force-change choke point and the `/account/` matches below.
+    // GET renders the claim form; POST redeems → creates account + own vault,
+    // mints a session, 302 → /account/. The handler validates the invite
+    // (sha256 lookup, expiry/used/revoked), CSRF, and rate-limits on the
+    // /login IP bucket. The invite alone is the authorization — no host:admin.
+    if (pathname.startsWith("/account/setup/")) {
+      if (!getDb) return dbNotConfigured();
+      const rawToken = decodeURIComponent(pathname.slice("/account/setup/".length));
+      if (!rawToken || rawToken.includes("/")) {
+        return new Response("not found", { status: 404 });
+      }
+      const db = getDb();
+      const hubOrigin = resolveIssuer(req, db, configuredIssuer, loadExposeHubOrigin);
+      const setupDeps = { db, hubOrigin, manifestPath };
+      if (req.method === "GET") return handleAccountSetupGet(req, rawToken, setupDeps);
+      if (req.method === "POST") return handleAccountSetupPost(req, rawToken, setupDeps);
+      return new Response("method not allowed", { status: 405 });
+    }
+
     // Multi-user Phase 1 PR 3 — user self-service change-password surface
     // (hub#252, design §sign-in flow change). Both GET (render form) and
     // POST (apply change) require a session cookie. The handler itself
@@ -2134,6 +2405,28 @@ export function hubFetch(
       return new Response("method not allowed", { status: 405 });
     }
 
+    // Per-request force-change-password gate (P0-1 / hub#469). CHOKE POINT 1:
+    // every `/account/*` route BELOW this line is gated. `/logout` and
+    // `/account/change-password` (the rotation/exit path) ran above and already
+    // returned, so they're never reached here — they stay reachable
+    // pre-rotation by construction. A signed-in user with
+    // `password_changed === false` is bounced (302 → change-password for
+    // browsers, 403 JSON for API clients) before any account surface
+    // (2fa, vault-token, vault-admin-token, account home) resolves. DRY: one
+    // gate for the whole `/account/*` family rather than per-route. The
+    // per-route mints in `account-vault-{token,admin-token}.ts` keep their own
+    // gate as defence-in-depth (they're also reachable in tests directly).
+    //
+    // The bare `/account` (no trailing slash) is matched explicitly too —
+    // otherwise it would slip past `startsWith("/account/")` to its 301 →
+    // `/account/` below, and a pre-rotation user wouldn't be gated until the
+    // second hop. Exact-match `/account` (not `startsWith("/account")`) so
+    // unrelated paths like `/accounts-something` aren't caught.
+    if (getDb && (pathname === "/account" || pathname.startsWith("/account/"))) {
+      const gate = forceChangePasswordGate(getDb(), req);
+      if (gate) return gate;
+    }
+
     // /account/2fa — user self-service TOTP 2FA enroll / disenroll (hub#473).
     // Both GET (render state) and POST (start/confirm/disable) require an
     // active session; the handler does the session check + 302 to /login when
@@ -2146,6 +2439,50 @@ export function hubFetch(
       return new Response("method not allowed", { status: 405 });
     }
 
+    // /account/vault-admin-token/<name> — friend-facing vault ADMIN deep-link.
+    // POST-only, session-gated, assignment-capped to the `admin` verb: an
+    // assigned non-admin user mints a `vault:<name>:admin` bootstrap token and
+    // 303-redirects into the vault's own admin SPA (`#token=<jwt>`), where they
+    // can rotate vault tokens AND configure Git backup / mirror. The non-admin
+    // sibling of `/admin/vault-admin-token/<name>` (which is first-admin-gated
+    // and returns JSON for the hub SPA). The handler enforces session →
+    // assignment-grants-admin → CSRF → force-change-password (item F / #469)
+    // before minting. Must precede `/account/vault-token/` (it isn't a prefix
+    // of it, but keep the more-specific admin path first for clarity) and the
+    // `/account/` match below. See `account-vault-admin-token.ts`.
+    if (pathname.startsWith("/account/vault-admin-token/")) {
+      if (!getDb) return dbNotConfigured();
+      if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+      const vaultName = decodeURIComponent(pathname.slice("/account/vault-admin-token/".length));
+      const db = getDb();
+      const hubOrigin = resolveIssuer(req, db, configuredIssuer, loadExposeHubOrigin);
+      // Resolve the vault's declared `managementUrl` at request time (same
+      // source the well-known doc reads — `installDir/.parachute/module.json`)
+      // so the deep-link lands on the vault admin SPA's real entry point. Quiet
+      // on a malformed/absent manifest: the handler defaults to `/admin/`
+      // (vault's canonical value), the same target the admin sibling uses.
+      const readManifestFn = deps?.readModuleManifest ?? defaultReadModuleManifest;
+      const manifest = readManifestLenient(manifestPath);
+      let managementUrl: string | undefined;
+      for (const s of manifest.services) {
+        if (!isVaultEntry(s) || !s.installDir) continue;
+        const instanceNames = new Set(s.paths.map((p) => vaultInstanceNameFor(s.name, p)));
+        if (!instanceNames.has(vaultName)) continue;
+        try {
+          const m = await readManifestFn(s.installDir);
+          if (m?.managementUrl) managementUrl = m.managementUrl;
+        } catch {
+          // Leave undefined → handler defaults to /admin/.
+        }
+        break;
+      }
+      return handleAccountVaultAdminTokenPost(req, vaultName, {
+        db,
+        hubOrigin,
+        ...(managementUrl !== undefined ? { managementUrl } : {}),
+      });
+    }
+
     // /account/vault-token/<name> — friend-facing scoped vault token mint.
     // POST-only, session-gated, assignment-capped: a non-admin friend mints a
     // `vault:<name>:read|write` bearer for a vault they're ASSIGNED to, for
@@ -2159,7 +2496,7 @@ export function hubFetch(
       if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
       const vaultName = decodeURIComponent(pathname.slice("/account/vault-token/".length));
       const db = getDb();
-      const hubOrigin = resolveIssuer(req, db, configuredIssuer);
+      const hubOrigin = resolveIssuer(req, db, configuredIssuer, loadExposeHubOrigin);
       return handleAccountVaultTokenPost(req, vaultName, { db, hubOrigin });
     }
 
@@ -2177,8 +2514,17 @@ export function hubFetch(
       }
       if (!getDb) return dbNotConfigured();
       const db = getDb();
-      const hubOrigin = resolveIssuer(req, db, configuredIssuer);
-      return handleAccountHomeGet(req, { db, hubOrigin });
+      const hubOrigin = resolveIssuer(req, db, configuredIssuer, loadExposeHubOrigin);
+      // Resolve each assigned vault's loopback port from services.json so the
+      // home can fetch per-vault usage. Read at request time (same dynamism as
+      // proxyToVault) — a vault created seconds ago surfaces a stat without a
+      // restart. Returns null for an unknown name → that tile skips the stat.
+      const resolveVaultPort = (vaultName: string): number | null => {
+        const services = readManifestLenient(manifestPath).services;
+        const match = findVaultUpstream(services, `/vault/${vaultName}`);
+        return match ? match.port : null;
+      };
+      return handleAccountHomeGet(req, { db, hubOrigin, resolveVaultPort });
     }
 
     // Legacy `/admin/config` (server-rendered module-config portal, #46)
@@ -2202,7 +2548,19 @@ export function hubFetch(
     // here anymore (the SPA moved to /admin), so we can't accidentally
     // mask a backend 404 with HTML.
     if (pathname.startsWith("/vault/")) {
-      const proxied = await proxyToVault(req, manifestPath, deps?.supervisor);
+      // Per-request force-change-password gate (P0-1 / hub#469). CHOKE POINT 2:
+      // a pre-rotation signed-in user can't reach a per-vault user surface
+      // (Notes PWA, MCP, vault API) on the un-rotated temp password — they're
+      // bounced to change-password (browser) / 403 (API). Same posture as the
+      // `/account/*` gate above. An UNAUTHENTICATED proxy request (no hub
+      // session — the common Notes/MCP case carrying its own bearer) passes the
+      // gate untouched (`forceChangePasswordGate` returns null with no session)
+      // and is handled by the vault's own auth downstream.
+      if (getDb) {
+        const gate = forceChangePasswordGate(getDb(), req);
+        if (gate) return gate;
+      }
+      const proxied = await proxyToVault(req, manifestPath, deps?.supervisor, peerAddr);
       if (proxied) return decorateWithChrome(proxied, req, pathname, getDb);
       return new Response("not found", { status: 404 });
     }
@@ -2229,7 +2587,7 @@ export function hubFetch(
     // here only after every hub-owned prefix above has had its turn — so
     // `/`, `/admin/*`, `/oauth/*`, `/.well-known/*`, `/hub/*`, `/vault/*`,
     // `/api/*` are excluded by ordering, not by an explicit denylist (#182).
-    const proxied = await proxyToService(req, manifestPath, deps?.supervisor);
+    const proxied = await proxyToService(req, manifestPath, deps?.supervisor, peerAddr);
     if (proxied) return decorateWithChrome(proxied, req, pathname, getDb);
 
     // Branded fall-through 404 (closes hub#392) — the operator who mistyped