@openparachute/hub 0.7.6 → 0.7.7-rc.13

package/src/hub-server.ts

@@ -24,15 +24,33 @@
  *   /admin/login, /admin/logout                → 301 → /login, /logout
  *
  *   # Notes-as-app migration Phase 2 (parachute-app design doc §16).
+ *   # `/surface/notes` = the legacy notes-ui mount (existing installs);
+ *   # `/surface/parachute` = the app's surface mount post-W2-12 rename.
  *   /notes, /notes/, /notes/*                  → 301 → /surface/notes[/...]
  *                                                (opt-out via
  *                                                 hub_settings.notes_redirect_disabled)
+ *   /surface/notes[/...]                       → 301 → /surface/parachute[/...]
+ *                                                CONDITIONAL (W2-12, dispatched just
+ *                                                before the generic services proxy):
+ *                                                only when uis{} mounts show
+ *                                                /surface/notes gone + /surface/parachute
+ *                                                present — inert on existing notes-ui
+ *                                                installs (surface-notes-alias.ts)
  *
  *   # Discovery + well-known.
- *   /, /hub.html                               → hub.html (the discovery page)
+ *   /                                          → root_mode-dependent: `redirect`
+ *                                                (default) 302s to root_redirect
+ *                                                (default /admin); `serve-app`
+ *                                                serves the installed app's dist
+ *                                                index.html AT `/` (no chrome).
+ *                                                Fresh-hub wizard funnel + pre-
+ *                                                admin 503 still preempt it.
+ *   /hub.html                                  → hub.html (the discovery page;
+ *                                                unaffected by root_mode)
  *   /.well-known/parachute.json                → built dynamically from services.json
  *   /.well-known/parachute-revocation.json     → revoked-jti list (hub#212 Phase 1)
  *   /.well-known/jwks.json                     → JWKS from hub.db
+ *   /.well-known/parachute-account             → account-door capabilities descriptor (public, H2)
  *   /.well-known/oauth-authorization-server    → RFC 8414 metadata (issuer, endpoints)
  *
  *   # OAuth issuer.
@@ -49,10 +67,15 @@
  *                                                 tokens/grants/user_vaults/invites/
  *                                                 connections sweep, CLI remove,
  *                                                 supervisor restart)
+ *   # /account/* — the Bearer-gated account-door REST facade (Phase 2, H2).
+ *   # account:self:admin OR parachute:host:admin (mutations); +:read (reads).
+ *   /account                      (GET)        → account bootstrap {id,email,door} (Bearer only)
+ *   /account/vaults               (GET/POST)   → list / create vault (create returns vault_token)
+ *   /account/vaults/<name>        (DELETE)     → teardown (wraps /vaults/<name> cascade)
+ *   /account/vaults/<name>/token  (POST)       → per-vault scoped token mint
+ *   /account/vaults/<name>/caps   (GET/PUT)    → read / set the storage cap
  *   /admin/host-admin-token       (GET)        → SPA bearer mint (cookie-gated)
  *   /admin/vault-admin-token/<n>  (GET)        → per-vault bearer mint (cookie-gated)
- *   /admin/agent-token            (GET)        → agent UI bearer mint (cookie-gated)
- *   /admin/channel-token          (GET)        → 301 → /admin/agent-token (legacy; channel→agent rename 2026-06-17)
  *   /admin/module-token/<short>   (GET)        → generic module config-UI bearer mint <short>:admin (cookie-gated)
  *   /api/connections/catalog      (GET)        → events/actions across installed modules (cookie-gated)
  *   /admin/connections            (POST/GET)   → connection provision/list (cookie-gated; POST CSRF-belted)
@@ -106,6 +129,13 @@
  *                                                 (hub#473; reached after a correct
  *                                                 password for a 2FA-enrolled user)
  *   /logout                       (POST)       → end admin session
+ *   /account/session               (GET)        → same-origin boot oracle {signed_in,
+ *                                                 csrf,...} (hub-parity P1); cookie-gated,
+ *                                                 NOT Bearer — mounted ABOVE the
+ *                                                 force-change-password gate below (a pure
+ *                                                 state oracle, so a pre-rotation user can
+ *                                                 still read it to drive the rotation
+ *                                                 ceremony itself)
  *   /account/change-password      (GET + POST) → user self-service change-password
  *                                                 (force-redirect target for users
  *                                                 with password_changed=false; also
@@ -114,8 +144,16 @@
  *                                                 + the per-vault proxy is hard-gated
  *                                                 per-request on password_changed===true
  *                                                 (forceChangePasswordGate); only this
- *                                                 route and /logout stay reachable
+ *                                                 route, /logout, and /account/session
+ *                                                 (P1, also above the gate) stay reachable
  *                                                 pre-rotation.
+ *   /account/token                (POST)       → cookie→account-bearer mint (App
+ *                                                 campaign Phase 2 H1): session cookie →
+ *                                                 short-lived JWT carrying the account
+ *                                                 superset {account:self:admin,
+ *                                                 parachute:host:admin, parachute:host:auth}
+ *                                                 aud="account"; first-admin-gated,
+ *                                                 CSRF + same-origin belt; stateless
  *   /account/2fa                  (GET + POST) → user self-service 2FA enroll/disenroll
  *                                                 (hub#473; QR + backup codes)
  *   /account/vault-token/<name>   (POST)       → friend mints a scoped
@@ -141,7 +179,13 @@
  *   # Generic services.json-driven proxy (non-vault modules: notes, scribe, agent).
  *   /<service-mount>/*                         → proxy via services.json longest-prefix
  *
- *   anything else                              → 404
+ *   # serve-app tail (only when root_mode = serve-app): an unclaimed GET is
+ *   # handed to the app's root-based dist — an existing bundle file (/assets/*,
+ *   # /icon.svg, /manifest.webmanifest, /sw.js) serves that file; an HTML deep
+ *   # link gets the SPA shell. Inert in redirect mode (the 404 below is
+ *   # byte-identical to before). See root-serve.ts.
+ *   anything else                              → 404 (or app asset / SPA shell
+ *                                                in serve-app mode)
  *
  * Invoked as:
  *   bun <this-file> --port <n> --well-known-dir <path> [--db <path>] [--issuer <url>]
@@ -163,7 +207,21 @@ 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 {
+  ACCOUNT_MUTATION_SCOPES,
+  type AccountApiDeps,
+  handleAccountCapabilities,
+  handleAccountCreateVault,
+  handleAccountGetVaultCaps,
+  handleAccountListVaults,
+  handleAccountMintVaultToken,
+  handleAccountRoot,
+  handleAccountSetVaultCaps,
+  requireAnyScope,
+} from "./account-api.ts";
+import { type AccountSessionDeps, handleAccountSession } from "./account-session.ts";
 import { handleAccountSetupGet, handleAccountSetupPost } from "./account-setup.ts";
+import { handleAccountToken } from "./account-token.ts";
 import { handleAccountVaultAdminTokenPost } from "./account-vault-admin-token.ts";
 import { handleAccountVaultTokenPost } from "./account-vault-token.ts";
 import {
@@ -171,7 +229,8 @@ import {
   handleAgentGrants,
   handleOAuthGrantCallback,
 } from "./admin-agent-grants.ts";
-import { handleAgentToken } from "./admin-agent-token.ts";
+
+import { adminAuthErrorResponse } from "./admin-auth.ts";
 import { handleApproveClient, handleDeleteClient, handleGetClient } from "./admin-clients.ts";
 import {
   type ConnectionsDeps,
@@ -252,7 +311,7 @@ import {
   startDbPathLivenessTimer,
 } from "./hub-db-liveness.ts";
 import { hubDbPath, openHubDb } from "./hub-db.ts";
-import { getHubOrigin, resolveRootRedirect } from "./hub-settings.ts";
+import { getHubOrigin, resolveRootMode, resolveRootRedirect } from "./hub-settings.ts";
 import { type RenderHubOpts, renderHub } from "./hub.ts";
 import { pemToJwk } from "./jwks.ts";
 import {
@@ -276,6 +335,7 @@ import { clearPid, writePid } from "./process-state.ts";
 import { toResponse as proxyErrorToResponse, renderProxyError } from "./proxy-error-ui.ts";
 import { classifyUpstream } from "./proxy-state.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
+import { makeAppDistResolver, serveAppAtRoot } from "./root-serve.ts";
 import {
   FIRST_PARTY_FALLBACKS,
   KNOWN_MODULES,
@@ -295,6 +355,7 @@ import {
 } from "./setup-wizard.ts";
 import { getAllPublicKeys } from "./signing-keys.ts";
 import type { Supervisor } from "./supervisor.ts";
+import { isSurfaceNotesPath, maybeRedirectSurfaceNotes } from "./surface-notes-alias.ts";
 import { handleTwoFactorGet, handleTwoFactorPost } from "./two-factor-handlers.ts";
 import { getUserById, userCount } from "./users.ts";
 import { sanitizePublicOrigin } from "./vault-hub-origin-env.ts";
@@ -1374,6 +1435,15 @@ export interface HubFetchDeps {
    * tracker between fetch fn and bridge handlers is impossible.
    */
   wsConnectionTracker?: WsConnectionTracker;
+  /**
+   * Resolve the installed app's `dist/` directory for `root_mode = serve-app`.
+   * Returns the dist dir, or `null` when the app isn't installed (→ serve-app
+   * falls back to the redirect). Production defaults to a memoizing resolver
+   * over the real `@openparachute/parachute-app` package (`makeAppDistResolver`);
+   * tests inject a fixture dir or a `() => null` to drive the not-installed
+   * fallback without a real global install.
+   */
+  resolveAppDist?: () => string | null;
 }
 
 /**
@@ -2073,6 +2143,13 @@ export function hubFetch(
   const manifestPath = deps?.manifestPath ?? SERVICES_MANIFEST_PATH;
   const gitRoot = deps?.gitRoot ?? join(CONFIG_DIR, "hub", "git");
   const spaDistDir = deps?.spaDistDir ?? defaultSpaDistDir();
+  // `root_mode = serve-app` resolver (memoizing over the real app package by
+  // default; tests inject their own). Instantiated once per hubFetch so the
+  // success-memoization spans the serve process's lifetime.
+  const resolveAppDist = deps?.resolveAppDist ?? makeAppDistResolver();
+  // One-shot log guard: when serve-app is set but the app can't be resolved we
+  // fall back to the redirect and say so ONCE, not on every `/` hit.
+  let warnedAppServeFallback = false;
   const loopbackPort = deps?.loopbackPort;
   const loadExposeHubOrigin =
     deps?.loadExposeHubOrigin ??
@@ -2312,27 +2389,6 @@ export function hubFetch(
         }
       }
 
-      // `/channel/*` 301-redirects to `/agent/*` — back-compat for the
-      // 2026-06-17 channel→agent module rename. Operator bookmarks, an
-      // un-upgraded chat/config UI's deep links, and any externally-shared
-      // `/channel/mcp/<name>` URL keep resolving for one release cycle while
-      // the module's canonical mount moves to `/agent`. Method-agnostic, same
-      // shape as the `/notes/*` redirect above (the agent's read-write surface
-      // is its own daemon API, not the hub mount, so a re-issued GET is fine).
-      // Matches `/channel` exactly and any `/channel/...` subpath, but NOT a
-      // longer-prefix module like a hypothetical `/channelthing` — the guard is
-      // exact-or-slash-delimited. Query string is preserved. (The generic
-      // services-proxy fallthrough below would otherwise 404 a `/channel/*`
-      // request once the module self-registers under `/agent`.)
-      if (pathname === "/channel" || pathname.startsWith("/channel/")) {
-        const dest = new URL(req.url);
-        dest.pathname = `/agent${pathname.slice("/channel".length)}`;
-        return new Response("", {
-          status: 301,
-          headers: { location: dest.pathname + dest.search },
-        });
-      }
-
       // CORS preflight for the public OAuth + discovery surface. Browsers
       // issue OPTIONS before any non-simple cross-origin request — third-party
       // SPAs hitting `/oauth/register` (RFC 7591 DCR), `/oauth/token`,
@@ -2611,6 +2667,24 @@ export function hubFetch(
       // page (used by the static `parachute expose --set-path=/` disk file and
       // any bookmark to the explicit `.html`). Only the bare `/` redirects.
       if (pathname === "/") {
+        // `root_mode = serve-app`: serve the installed app's shell AT the origin
+        // root (no redirect hop), the self-hosted mirror of the hosted door.
+        // GET only — a non-GET `/` keeps its 302 below. Runs AFTER the fresh-hub
+        // wizard funnel + pre-admin 503 above (a not-yet-set-up hub still lands
+        // on setup, never a half-working app shell). Falls back to the redirect
+        // when the app isn't installed (dist unresolvable), with a one-time log.
+        if (req.method === "GET" && resolveRootMode(getDb ? getDb() : null) === "serve-app") {
+          const dist = resolveAppDist();
+          if (dist) {
+            const served = serveAppAtRoot(dist, req, "/");
+            if (served) return served;
+          } else if (!warnedAppServeFallback) {
+            warnedAppServeFallback = true;
+            console.warn(
+              "[hub] root_mode=serve-app but the Parachute app is not installed (its dist could not be resolved) — falling back to the root redirect. Install it with `parachute install app`.",
+            );
+          }
+        }
         return new Response(null, {
           status: 302,
           headers: { location: resolveRootRedirect(getDb ? getDb() : null) },
@@ -2812,6 +2886,30 @@ export function hubFetch(
         return new Response(res.body, { status: res.status, headers: merged });
       }
 
+      // GET /.well-known/parachute-account — the account-door capabilities
+      // descriptor (Phase 2, H2). Public, no auth, wildcard CORS (the app pulls
+      // it cross-origin to render honestly per door: billing:false + plans:[] on
+      // self-host means no upgrade UI). See account-api.handleAccountCapabilities.
+      if (pathname === "/.well-known/parachute-account") {
+        const corsHeaders = {
+          "access-control-allow-origin": "*",
+          "access-control-allow-methods": "GET, OPTIONS",
+        };
+        if (req.method === "OPTIONS") {
+          return new Response(null, { status: 204, headers: corsHeaders });
+        }
+        if (!getDb) {
+          return new Response('{"error":"account descriptor unavailable: db not configured"}', {
+            status: 503,
+            headers: { "content-type": "application/json", ...corsHeaders },
+          });
+        }
+        const res = handleAccountCapabilities(req, { db: getDb(), issuer: oauthDeps(req).issuer });
+        const merged = new Headers(res.headers);
+        for (const [k, v] of Object.entries(corsHeaders)) merged.set(k, v);
+        return new Response(res.body, { status: res.status, headers: merged });
+      }
+
       // OAuth surface — every handler return is wrapped in `applyCorsHeaders`
       // so third-party SPAs can fetch these endpoints cross-origin (the entire
       // point of OAuth DCR: arbitrary SPAs register → authorize → exchange
@@ -3001,31 +3099,13 @@ export function hubFetch(
         });
       }
 
-      // Back-compat: the agent module's admin-token mint moved from
-      // `/admin/channel-token` to `/admin/agent-token` in the 2026-06-17
-      // channel→agent rename. 301-redirect the old path so operator bookmarks
-      // + any un-upgraded UI fallback keep working for one release cycle.
-      if (pathname === "/admin/channel-token") {
-        const dest = new URL(req.url);
-        dest.pathname = "/admin/agent-token";
-        return Response.redirect(dest.toString(), 301);
-      }
-
-      if (pathname === "/admin/agent-token") {
-        if (!getDb) return dbNotConfigured();
-        return handleAgentToken(req, {
-          db: getDb(),
-          issuer: oauthDeps(req).issuer,
-        });
-      }
-
       // Generic per-module config-UI bearer mint (2026-06-09 modular-UI
       // architecture, P3). `<short>:admin` for any single-audience module —
       // the admin scope each module-owned config UI needs to call its own
-      // endpoints. Cookie-gated to the first-admin operator, exactly like
-      // /admin/agent-token + /admin/vault-admin-token. Gated on
-      // self-registration (services.json row + readable module.json) with the
-      // bootstrap registries as a fallback (boundary C5) — a genuinely
+      // endpoints. Cookie-gated to the first-admin operator, matching the
+      // host/vault admin-token endpoints. Gated on self-registration
+      // (services.json row + readable module.json) with the bootstrap
+      // registries as a fallback (boundary C5) — a genuinely
       // third-party module mints here with zero hub code changes. Vault is
       // per-instance and routed to /admin/vault-admin-token/<name> instead.
       if (pathname.startsWith("/admin/module-token/")) {
@@ -3043,9 +3123,7 @@ export function hubFetch(
 
       // Note: the legacy `/admin/channels` bespoke vault-channel orchestration
       // endpoint (pre-Connections, hub#624 era) was retired in boundary D1 —
-      // superseded by the general engine below. The agent module's own admin
-      // page (renamed from channel 2026-06-17) drives `/admin/connections` +
-      // `/admin/agent-token`.
+      // superseded by the general engine below.
 
       // Connections — the GENERAL module event→action engine (2026-06-09
       // modular-UI architecture, P5). `/api/connections/catalog` (GET) returns
@@ -3348,7 +3426,7 @@ export function hubFetch(
       // the 2026-06-09 modular-UI architecture P3. Config is module-owned +
       // hub-framed now: the Modules page "Configure" action opens the module's
       // OWN config UI (`configUiUrl`), which mints its admin Bearer from the
-      // cookie-gated `/admin/module-token/<short>` (or `/admin/agent-token`).
+      // cookie-gated `/admin/module-token/<short>`.
 
       // Per-module action endpoints: /api/modules/:short/{install,restart,upgrade,uninstall}.
       if (pathname.startsWith("/api/modules/")) {
@@ -3699,6 +3777,20 @@ export function hubFetch(
         return new Response("method not allowed", { status: 405 });
       }
 
+      // /account/session — the same-origin boot oracle (hub-parity P1). A
+      // PURE STATE ORACLE, not a mutating surface, so it is mounted ABOVE the
+      // force-change-password gate immediately below: a pre-rotation user
+      // must still be able to read `{signed_in, csrf}` to drive the rotation
+      // ceremony itself, rather than get walled off before it can even ask.
+      // `/account/token` (below the gate) stays gated — a pre-rotation user
+      // hits its 403 `force_change_password` there instead. See
+      // `account-session.ts`.
+      if (pathname === "/account/session") {
+        if (!getDb) return dbNotConfigured();
+        const sessionDeps: AccountSessionDeps = { db: getDb() };
+        return handleAccountSession(req, sessionDeps);
+      }
+
       // 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
@@ -3721,6 +3813,27 @@ export function hubFetch(
         if (gate) return gate;
       }
 
+      // /account/token — cookie→account-bearer mint (Parachute App campaign,
+      // Phase 2 H1). POST-only. Exchanges the `parachute_hub_session` cookie for
+      // a short-lived JWT carrying the account superset
+      // {account:self:admin, parachute:host:admin, parachute:host:auth} with
+      // aud="account" — the same-origin app's bootstrap into holding the account
+      // credential (it never touches /oauth/authorize, so never hits consent).
+      // First-admin-gated (account ≡ box), CSRF double-submit + the same-origin
+      // Origin belt below. Stateless (no tokens row); revocation = logout.
+      if (pathname === "/account/token") {
+        if (!getDb) return dbNotConfigured();
+        // Origin belt (hub#632 posture): a cookie-authed POST mint gets the
+        // strict same-origin check as defense-in-depth over the body's CSRF
+        // token. A Bearer-authed caller (none expected here) would bypass the
+        // belt but still fail the cookie-only session gate inside the handler.
+        {
+          const rejected = assertSameOriginForCookieMutation(req, oauthDeps(req).hubBoundOrigins());
+          if (rejected) return rejected;
+        }
+        return handleAccountToken(req, { db: getDb(), issuer: oauthDeps(req).issuer });
+      }
+
       // /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
@@ -3777,6 +3890,115 @@ export function hubFetch(
         });
       }
 
+      // ====================================================================
+      // /account/* — the Bearer-gated account-door REST facade (Phase 2, H2).
+      // The normalized account API both doors mount (the hosted cloud door
+      // mounts the twin). Bearer-authed, machine-to-machine — no session
+      // cookie — so these precede the session-cookie `/account/vault-token/`
+      // + `/account/` HTML routes below. Mutations accept account:self:admin
+      // OR parachute:host:admin; reads also accept account:self:read. See
+      // `account-api.ts`.
+      // ====================================================================
+      if (pathname === "/account/vaults") {
+        if (!getDb) return dbNotConfigured();
+        const accountDeps: AccountApiDeps = {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        };
+        if (req.method === "GET") return handleAccountListVaults(req, accountDeps);
+        if (req.method === "POST") return handleAccountCreateVault(req, accountDeps);
+        return new Response("method not allowed", { status: 405 });
+      }
+      if (pathname.startsWith("/account/vaults/")) {
+        if (!getDb) return dbNotConfigured();
+        const rest = pathname.slice("/account/vaults/".length);
+        const accountDeps: AccountApiDeps = {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        };
+        // POST /account/vaults/<name>/token — per-vault scoped token mint.
+        if (rest.endsWith("/token")) {
+          const name = decodeURIComponent(rest.slice(0, -"/token".length));
+          return handleAccountMintVaultToken(req, name, accountDeps);
+        }
+        // GET/PUT /account/vaults/<name>/caps — read / set the storage cap.
+        if (rest.endsWith("/caps")) {
+          const name = decodeURIComponent(rest.slice(0, -"/caps".length));
+          if (req.method === "GET") return handleAccountGetVaultCaps(req, name, accountDeps);
+          if (req.method === "PUT") return handleAccountSetVaultCaps(req, name, accountDeps);
+          return new Response("method not allowed", { status: 405 });
+        }
+        // DELETE /account/vaults/<name> — teardown via the full identity
+        // cascade. Gate with the account-scope set here (accept account:self:admin
+        // OR parachute:host:admin), then delegate to `handleDeleteVault`, which
+        // re-gates parachute:host:admin — the superset account token carries it,
+        // so this is belt-and-suspenders, not a second authorization.
+        if (req.method === "DELETE") {
+          const name = decodeURIComponent(rest);
+          if (!name || name.includes("/")) return new Response("not found", { status: 404 });
+          try {
+            await requireAnyScope(
+              getDb(),
+              req,
+              ACCOUNT_MUTATION_SCOPES,
+              oauthDeps(req).hubBoundOrigins(),
+            );
+          } catch (err) {
+            return adminAuthErrorResponse(err);
+          }
+          const services = readManifestLenient(manifestPath).services;
+          const agentEntry = findServiceByShort(services, "agent");
+          const agentOrigin = agentEntry ? `http://127.0.0.1:${agentEntry.port}` : null;
+          const resolveVaultOrigin = (vaultName: string): string | null => {
+            const match = findVaultUpstream(
+              readManifestLenient(manifestPath).services,
+              `/vault/${vaultName}`,
+            );
+            return match ? `http://127.0.0.1:${match.port}` : null;
+          };
+          const supervisor = deps?.supervisor;
+          return handleDeleteVault(req, name, {
+            db: getDb(),
+            issuer: oauthDeps(req).issuer,
+            knownIssuers: oauthDeps(req).hubBoundOrigins(),
+            manifestPath,
+            connectionsStorePath:
+              deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
+            agentOrigin,
+            resolveVaultOrigin,
+            resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
+            ...(supervisor
+              ? {
+                  restartVaultModule: async () => {
+                    await supervisor.restart("vault");
+                  },
+                }
+              : {}),
+          });
+        }
+        return new Response("method not allowed", { status: 405 });
+      }
+      // GET /account (Bearer) — account bootstrap {id,email,door} (the
+      // door-contract's AccountBootstrap). Only intercepts when an
+      // Authorization header is present, so the cookie-authed HTML account
+      // home at `/account`/`/account/` below stays unaffected.
+      if (
+        (pathname === "/account" || pathname === "/account/") &&
+        req.headers.get("authorization")
+      ) {
+        if (!getDb) return dbNotConfigured();
+        return handleAccountRoot(req, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        });
+      }
+
       // /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
@@ -3967,6 +4189,28 @@ export function hubFetch(
       // `/`, `/admin/*`, `/oauth/*`, `/.well-known/*`, `/hub/*`, `/vault/*`,
       // `/api/*` are excluded by ordering, not by an explicit denylist (#182).
       //
+      // W2-12 — conditional `/surface/notes/*` → `/surface/parachute/*`
+      // alias, the "never 404 an old bookmark after an in-place upgrade"
+      // safety net for the app's notes→parachute surface-identity rename.
+      // Fires ONLY when the manifest's `uis{}` sub-units show the legacy
+      // `/surface/notes` mount gone AND a `/surface/parachute` mount
+      // present (see surface-notes-alias.ts for the full condition +
+      // inert-today proof). On every existing notes-ui install the
+      // condition fails and dispatch falls through to the generic proxy
+      // below unchanged. Reads the same lenient manifest source
+      // `resolveUiMount` consumes — hoisted to one read shared by both.
+      const manifestServices = readManifestLenient(manifestPath).services;
+      if (isSurfaceNotesPath(pathname)) {
+        const aliasTarget = maybeRedirectSurfaceNotes(pathname, url.search, manifestServices);
+        if (aliasTarget !== undefined) {
+          logNotesRedirect(pathname, aliasTarget);
+          return new Response("", {
+            status: 301,
+            headers: { location: aliasTarget },
+          });
+        }
+      }
+
       // H3 — per-UI audience gate. When the path falls under a declared UI
       // sub-unit (a `uis{}` entry on the matched service row — surface-hosted
       // UI mounts like /surface/<name>/*), the sub-unit's audience is
@@ -3981,7 +4225,7 @@ export function hubFetch(
       // which also means a 'surface'/'public' mount on a loopback-only row
       // stays unreachable from tailnet/funnel: exposure is orthogonal to
       // audience.
-      const uiMatch = resolveUiMount(readManifestLenient(manifestPath).services, pathname);
+      const uiMatch = resolveUiMount(manifestServices, pathname);
       if (uiMatch) {
         const cloaked =
           effectivePublicExposure(uiMatch.entry) === "loopback" &&
@@ -4015,6 +4259,25 @@ export function hubFetch(
         );
       }
 
+      // serve-app tail (`root_mode = serve-app`). This is exactly the "would
+      // have been the branded 404" point: every hub-owned prefix above (/,
+      // /admin, /oauth, /.well-known, /vault, /git, /api, service mounts) has
+      // already had its turn, so anything here is genuinely unclaimed. Hand an
+      // unclaimed GET to the app's root-based dist — an existing bundle file
+      // (/assets/*, /icon.svg, /manifest.webmanifest, /sw.js) serves that file;
+      // an HTML deep link the app routes client-side gets the SPA shell.
+      // `serveAppAtRoot` returns null (→ branded 404 below) for a non-GET, a
+      // non-HTML unclaimed request, or a reserved /api|/oauth|/.well-known
+      // prefix. NO chrome injection — the app owns its whole page. In redirect
+      // mode this branch is inert and the tail stays byte-identical to before.
+      if (req.method === "GET" && resolveRootMode(getDb ? getDb() : null) === "serve-app") {
+        const dist = resolveAppDist();
+        if (dist) {
+          const served = serveAppAtRoot(dist, req, pathname);
+          if (served) return served;
+        }
+      }
+
       // Branded fall-through 404 (closes hub#392) — the operator who mistyped
       // a URL sees a clear "not found" page with a path back home, not the
       // browser's default empty-body chrome. Only HTML clients get the