@openparachute/hub 0.6.5-rc.8 → 0.7.1

package/src/hub-server.ts

@@ -15,7 +15,8 @@
  *
  *   # Pre-rename 301 back-compat (hub#231 — first so they preempt any
  *   # remaining handlers under /vault or /hub).
- *   /vault, /vault/, /vault/new                → 301 → /admin/vaults[/new]
+ *   /vault, /vault/, /vault/new                → 301 → /vault/admin/ (B5:
+ *                                                vault's daemon-level admin)
  *   /hub/vaults*                               → 301 → /admin/vaults*
  *   /hub/permissions                           → 301 → /admin/permissions
  *   /hub/tokens                                → 301 → /admin/tokens
@@ -43,8 +44,25 @@
  *
  *   # Admin API + bearer-mint surfaces (must precede /admin/* SPA mount).
  *   /vaults                       (POST)       → create vault
+ *   /vaults/<name>                (DELETE)     → destroy vault + identity cascade
+ *                                                 (B1: confirm body, host:admin,
+ *                                                 tokens/grants/user_vaults/invites/
+ *                                                 connections sweep, CLI remove,
+ *                                                 supervisor restart)
  *   /admin/host-admin-token       (GET)        → SPA bearer mint (cookie-gated)
  *   /admin/vault-admin-token/<n>  (GET)        → per-vault bearer mint (cookie-gated)
+ *   /admin/channel-token          (GET)        → channel UI bearer mint (cookie-gated)
+ *   /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)
+ *   /admin/connections/<id>       (DELETE)     → connection teardown (cookie-gated; CSRF-belted)
+ *   /admin/connections/<id>/renew (POST)       → credential renewal (H4; Bearer = the credential itself, proof of possession)
+ *   /admin/connections/<id>/claim (POST)       → claim/reconcile a directly-delivered credential → pending record (surface#113; Bearer = the credential itself)
+ *   /admin/connections/<id>/approve (POST)     → operator approval of a pending claim (cookie-gated; CSRF-belted)
+ *
+ *   # "CSRF-belted" = strict same-origin Origin check on cookie-authed
+ *   # mutations (hub#632, boundary C1) — origin-check.ts
+ *   # `assertSameOriginForCookieMutation` carries the canonical enumeration.
  *   /api/me                       (GET)        → who-am-I (session+CSRF or hasSession:false)
  *   /api/hub                      (GET)        → hub version + uptime + install-source (host:admin)
  *   /api/hub/upgrade              (POST)       → SPA-driven hub self-upgrade → 202 + detached helper (host:admin, §5.3/D4)
@@ -94,6 +112,11 @@
  *   /admin/config*                             → 301 → /admin/vaults (legacy
  *                                                portal retired post-SPA-rework)
  *
+ *   # Vault MODULE daemon-level admin surface (B-route, 2026-06-09
+ *   # hub-module-boundary). Runs BEFORE the per-vault proxy; "admin" is a
+ *   # reserved vault name so no instance can claim the mount.
+ *   /vault/admin, /vault/admin/*               → proxy to the vault module's daemon
+ *
  *   # Per-vault content proxy (user-facing vault data: Notes PWA, MCP, etc.).
  *   /vault/<name>/*                            → proxy to the vault backend
  *
@@ -130,7 +153,13 @@ 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 { handleChannelToken } from "./admin-channel-token.ts";
 import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
+import {
+  type ConnectionsDeps,
+  handleConnections,
+  handleConnectionsCatalog,
+} from "./admin-connections.ts";
 import { handleListGrants, handleRevokeGrant } from "./admin-grants.ts";
 import {
   handleAdminLoginGet,
@@ -139,8 +168,9 @@ import {
   handleAdminLogoutPost,
 } from "./admin-handlers.ts";
 import { handleHostAdminToken } from "./admin-host-admin-token.ts";
+import { handleModuleToken } from "./admin-module-token.ts";
 import { handleVaultAdminToken } from "./admin-vault-admin-token.ts";
-import { handleCreateVault } from "./admin-vaults.ts";
+import { handleCreateVault, handleDeleteVault } from "./admin-vaults.ts";
 import {
   handleAccountChangePasswordGet,
   handleAccountChangePasswordPost,
@@ -151,7 +181,6 @@ 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";
 import {
   getDefaultOperationsRegistry,
   handleInstall,
@@ -178,7 +207,12 @@ import {
   handleResetUserPassword,
   handleUpdateUserVaults,
 } from "./api-users.ts";
-import { buildChromeForRequest, injectChromeIntoResponse } from "./chrome-strip.ts";
+import { gateUiAudience, resolveUiMount } from "./audience-gate.ts";
+import {
+  CHROME_OPT_OUT_PREFIXES,
+  buildChromeForRequest,
+  injectChromeIntoResponse,
+} from "./chrome-strip.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "./config.ts";
 import { applyCorsHeaders, corsPreflightResponse, isCorsAllowedRoute } from "./cors.ts";
 import { ensureCsrfToken } from "./csrf.ts";
@@ -211,7 +245,7 @@ import {
   protectedResourceMetadata,
 } from "./oauth-handlers.ts";
 import { renderNotFoundPage } from "./oauth-ui.ts";
-import { buildHubBoundOrigins } from "./origin-check.ts";
+import { assertSameOriginForCookieMutation, buildHubBoundOrigins } from "./origin-check.ts";
 import { clearPid, writePid } from "./process-state.ts";
 import { toResponse as proxyErrorToResponse, renderProxyError } from "./proxy-error-ui.ts";
 import { classifyUpstream } from "./proxy-state.ts";
@@ -220,6 +254,7 @@ import {
   FIRST_PARTY_FALLBACKS,
   KNOWN_MODULES,
   effectivePublicExposure,
+  findServiceByShort,
   shortNameForManifest,
 } from "./service-spec.ts";
 import { type ServiceEntry, readManifest, readManifestLenient } from "./services-manifest.ts";
@@ -243,6 +278,8 @@ import {
   isVaultEntry,
   vaultInstanceNameFor,
 } from "./well-known.ts";
+import { type WsBridgeData, createWsBridgeHandlers } from "./ws-bridge.ts";
+import { type WsConnectionTracker, defaultWsConnectionTracker } from "./ws-connection-caps.ts";
 
 interface Args {
   port: number;
@@ -412,6 +449,62 @@ function hasVaultInstalled(manifestPath: string): boolean {
   }
 }
 
+/**
+ * Snapshot of every installed module's `.parachute/module.json` + its
+ * user-facing mount path, for the Connections engine (2026-06-09 modular-UI
+ * architecture, P5). Read at request time so a freshly-installed module's
+ * declared events/actions surface without a hub restart. A malformed manifest
+ * on one module is skipped (logged), never 500s the whole catalog — same
+ * posture as `/api/modules`.
+ *
+ * `mount` is the first non-`.parachute` services.json path (the proxied
+ * user-facing prefix, e.g. `/channel`), which the engine joins with a sink
+ * action's `endpoint` to build the hub-proxied webhook.
+ */
+async function collectInstalledModules(
+  manifestPath: string,
+  readManifestFn: (installDir: string) => Promise<ModuleManifest | null>,
+): Promise<import("./admin-connections.ts").InstalledModuleInfo[]> {
+  // Lenient — see hub#406.
+  const services = readManifestLenient(manifestPath).services;
+  const out: import("./admin-connections.ts").InstalledModuleInfo[] = [];
+  await Promise.all(
+    services.map(async (entry) => {
+      if (!entry.installDir) return;
+      const short = shortNameForManifest(entry.name) ?? entry.name;
+      const userPath = (entry.paths ?? []).find(
+        (p) => p !== "/.parachute" && !p.startsWith("/.parachute/"),
+      );
+      try {
+        const manifest = await readManifestFn(entry.installDir);
+        if (!manifest) return;
+        out.push({ short, manifest, mount: userPath ?? null });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`connections: skipping module ${short}: ${msg}`);
+      }
+    }),
+  );
+  return out;
+}
+
+/**
+ * Resolve a module's loopback origin by SHORT name from services.json — the
+ * H4 credential-delivery seam (the Connections engine POSTs minted
+ * credentials + removal payloads direct to the daemon, not through the hub
+ * proxy). Short derivation mirrors `collectInstalledModules`:
+ * `shortNameForManifest(name) ?? name`, so third-party modules (whose row
+ * name IS their short) resolve too. Read per-request — a module installed
+ * seconds ago is deliverable without a hub restart.
+ */
+function makeResolveModuleOrigin(manifestPath: string): (short: string) => string | null {
+  return (short) => {
+    const services = readManifestLenient(manifestPath).services;
+    const entry = services.find((s) => (shortNameForManifest(s.name) ?? s.name) === short);
+    return entry ? `http://127.0.0.1:${entry.port}` : null;
+  };
+}
+
 /**
  * The trust layer a request arrived through. Hub binds `127.0.0.1:1939`, so
  * every request reaches it via one of three trusted forwarders (or directly
@@ -498,6 +591,125 @@ function isLoopbackPeer(peerAddr: string | null | undefined): boolean {
   );
 }
 
+/**
+ * The two substrate trust headers the hub stamps on every forwarded request
+ * (H2, surface-runtime-primitives design §10):
+ *
+ *   X-Parachute-Layer     — the `layerOf` classification ("loopback" |
+ *                           "tailnet" | "public"), fail-closed to "public"
+ *                           when the peer address is unknown.
+ *   X-Parachute-Client-IP — the resolved client IP (CF-Connecting-IP →
+ *                           X-Forwarded-For first hop → peer address; same
+ *                           precedence as rate-limit.ts `clientIpFromRequest`,
+ *                           with the peer address as the direct-caller floor).
+ *
+ * Backends (surface-host's `ctx.layer` / `ctx.clientIp`, any module reading
+ * trust signals) consume THESE, never raw forwarder headers — the hub is the
+ * only component that can see the actual peer socket, so it's the only place
+ * the classification can be made fail-closed.
+ */
+export const PARACHUTE_LAYER_HEADER = "x-parachute-layer";
+export const PARACHUTE_CLIENT_IP_HEADER = "x-parachute-client-ip";
+
+/**
+ * Resolve the client IP for the X-Parachute-Client-IP stamp. Precedence:
+ *
+ *   1. `CF-Connecting-IP` — cloudflared stamps the actual client IP on every
+ *      forwarded request (authoritative on cloudflare-fronted hubs).
+ *   2. `X-Forwarded-For` first hop — tailscale serve/funnel and generic
+ *      reverse proxies set it; the leftmost entry is the original client.
+ *   3. The peer address itself — the direct caller (loopback CLI, or a
+ *      direct network peer on a 0.0.0.0 bind).
+ *
+ * Returns null when nothing resolves (no forwarder headers AND no peer
+ * address — e.g. a unit test calling the fetch fn without a Server). The
+ * caller omits the header in that case; backends treat absence as null.
+ *
+ * Known limitation (same as the rate-limiter's keying): a DIRECT caller can
+ * spoof the forwarded-IP headers and misattribute its own address. It cannot
+ * spoof the LAYER (layerOf classifies direct non-loopback peers as "public"
+ * regardless of injected headers), so the trust signal stays sound — only
+ * the attribution string is best-effort for direct callers.
+ */
+export function resolveClientIp(req: Request, peerAddr: string | null): string | null {
+  const cf = req.headers.get("cf-connecting-ip")?.trim();
+  if (cf) return cf;
+  const xff = req.headers.get("x-forwarded-for");
+  if (xff) {
+    const first = xff.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  const peer = peerAddr?.trim();
+  return peer ? peer : null;
+}
+
+/**
+ * Strip any inbound occurrences of the substrate trust headers, then stamp
+ * the hub's own classification. The strip is load-bearing: a public client
+ * sending `X-Parachute-Layer: loopback` (or a forged client IP) must never
+ * ride that injection past the proxy into a module that keys trust off it.
+ * Mutates `headers` in place (the proxy's outgoing header bag).
+ */
+export function stampSubstrateTrustHeaders(
+  headers: Headers,
+  req: Request,
+  peerAddr: string | null,
+): void {
+  headers.delete(PARACHUTE_LAYER_HEADER);
+  headers.delete(PARACHUTE_CLIENT_IP_HEADER);
+  headers.set(PARACHUTE_LAYER_HEADER, layerOf(req, peerAddr));
+  const clientIp = resolveClientIp(req, peerAddr);
+  if (clientIp) headers.set(PARACHUTE_CLIENT_IP_HEADER, clientIp);
+}
+
+/**
+ * Shared bucket for connections whose client IP cannot be derived at all
+ * (no forwarder headers AND no peer address). Fail-closed: they all contend
+ * for one per-IP allotment rather than each minting a fresh bucket — the
+ * same posture as rate-limit.ts's UNKNOWN_IP_SENTINEL.
+ */
+export const WS_CAP_SHARED_BUCKET = "unknown";
+
+/**
+ * Derive the connection-cap bucket key for a WS upgrade (hub#649).
+ *
+ * STRICTER than {@link resolveClientIp} on purpose. The H2 attribution stamp
+ * tolerates a direct caller misattributing itself (documented limitation —
+ * the LAYER stays truthful, only the attribution string is best-effort). A
+ * cap key cannot afford that tolerance: if a direct peer's forged
+ * X-Forwarded-For were believed, rotating the header would mint a fresh
+ * bucket per connection and the per-IP cap would never trip. So forwarded
+ * IP headers are believed ONLY when the peer is loopback — the hub's actual
+ * forwarder topology (cloudflared, tailscale serve/funnel) runs on-box and
+ * dials 127.0.0.1; nothing else legitimately presents those headers from
+ * loopback, and a remote attacker can't BE loopback.
+ *
+ *   - loopback peer:  CF-Connecting-IP → X-Forwarded-For first hop → the
+ *     loopback address itself (direct local callers share one bucket —
+ *     owner-operated, and the cap is configurable).
+ *   - non-loopback peer: the peer address, regardless of injected headers
+ *     (spoofed XFF on an untrusted layer lands in the spoofer's own bucket).
+ *   - no peer derivable: {@link WS_CAP_SHARED_BUCKET} (fail closed).
+ *
+ * Known limitation, container deploys (Render / Fly): the platform edge
+ * dials from a private non-loopback address, so all public clients share
+ * the edge peer's bucket there — the per-IP cap degrades to a coarse shared
+ * cap and the global cap is the operative bound. Raise
+ * PARACHUTE_WS_MAX_PER_IP on such deploys; a trusted-proxy allowlist can
+ * refine this when a cloud WS surface actually ships.
+ */
+export function wsCapBucketKey(req: Request, peerAddr: string | null): string {
+  const peer = peerAddr?.trim() || null;
+  if (peer && isLoopbackPeer(peer)) {
+    const cf = req.headers.get("cf-connecting-ip")?.trim();
+    if (cf) return cf;
+    const xff = req.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+    if (xff) return xff;
+    return peer;
+  }
+  return peer ?? WS_CAP_SHARED_BUCKET;
+}
+
 /**
  * Forward a request to a loopback service on `127.0.0.1:<port>`. By default
  * the incoming pathname + query are preserved verbatim; pass `targetPath` to
@@ -529,10 +741,17 @@ function isLoopbackPeer(peerAddr: string | null | undefined): boolean {
  * `short` is the canonical short (`vault`/`scribe`/`notes`) — used as
  * the supervisor map key + pidfile directory key for classification.
  *
- * Hop-by-hop notes: WebSocket upgrades and HTTP/2 trailers don't traverse
- * fetch-based proxies cleanly. No on-box service uses either today; if one
- * eventually needs them, switch to a Node http.IncomingMessage / http.request
- * pair.
+ * `peerAddr` is the resolved peer address (`server.requestIP`), threaded so
+ * the substrate trust headers (below) classify the layer the same way the
+ * `publicExposure` cloak does — fail-closed to `public` when unknown.
+ *
+ * Hop-by-hop notes: HTTP/2 trailers don't traverse fetch-based proxies
+ * cleanly; no on-box service uses them today. WebSocket upgrades CANNOT
+ * traverse this fetch-based path either — they're handled BEFORE dispatch by
+ * the Bun-native upgrade bridge (H1: `maybeUpgradeWebSocket` +
+ * `src/ws-bridge.ts`) for modules that declare the capability; an upgrade
+ * request reaching this function belongs to a non-declaring mount and the
+ * upstream sees a plain GET.
  */
 async function proxyRequest(
   req: Request,
@@ -540,6 +759,7 @@ async function proxyRequest(
   serviceLabel: string,
   short: string,
   supervisor: Supervisor | undefined,
+  peerAddr: string | null,
   targetPath?: string,
 ): Promise<Response> {
   const url = new URL(req.url);
@@ -585,6 +805,11 @@ async function proxyRequest(
   if (!headers.has("x-forwarded-proto")) {
     headers.set("x-forwarded-proto", isHttpsRequest(req) ? "https" : "http");
   }
+  // Substrate trust headers (H2, surface-runtime design §10): stamped on
+  // EVERY forwarded request so module backends read trust signals from the
+  // substrate instead of re-deriving them from raw forwarder headers (the
+  // "header-absence = local trust" anti-pattern the design rejects).
+  stampSubstrateTrustHeaders(headers, req, peerAddr);
 
   const init: RequestInit & { duplex?: "half" } = {
     method: req.method,
@@ -695,7 +920,51 @@ async function proxyToVault(
   // vault instances share the same supervisor key under hub's current
   // single-vault-per-hub model; if multi-vault-per-hub ever ships, the
   // classifier will need a per-instance key.
-  return proxyRequest(req, match.port, "vault", "vault", supervisor, targetPath);
+  return proxyRequest(req, match.port, "vault", "vault", supervisor, peerAddr, targetPath);
+}
+
+/**
+ * Reverse-proxy `/vault/admin` + `/vault/admin/*` to the vault MODULE's
+ * daemon — the daemon-level multi-vault admin surface (B-route, 2026-06-09
+ * hub-module-boundary migration), NOT a per-instance path.
+ *
+ * Resolution is via `findServiceByShort(services, "vault")` (the canonical
+ * self-registered `parachute-vault` row — same shape as the channelEntry
+ * lookup in the Connections deps), deliberately NOT `findVaultUpstream`:
+ * vault must NOT self-register `/vault/admin` in `paths[]`, because every
+ * consumer that derives instance names from paths (`vaultInstanceNameFor`,
+ * the well-known vaults[] fan-out, `findExistingVault`, the mint
+ * allowlists, the users vault-picker) would fabricate a phantom vault named
+ * "admin". The mount is hub-owned and gated on the B2h `admin` name
+ * reservation, so no real instance can ever claim it.
+ *
+ * Applies the SAME `publicExposure: "loopback"` 404-cloak as `proxyToVault`
+ * (the per-vault proxy's only layer-gate; "allowed"/"auth-required" pass
+ * through and the daemon self-gates). Vault's row declares no `stripPrefix`
+ * — the FULL path forwards, so the daemon's own `/vault/admin` routing
+ * branch (vault wave, B3) serves it.
+ *
+ * Returns `undefined` when no vault module is installed (caller 404s).
+ * NOTE: legacy per-instance rows named `parachute-vault-<name>` don't
+ * resolve through `findServiceByShort` (it only knows the canonical
+ * manifest name) — on such an install this surface 404s until vault's boot
+ * selfRegister rewrites the canonical row, which is the documented
+ * old-install degradation, not a routing hole.
+ */
+async function proxyToVaultAdmin(
+  req: Request,
+  manifestPath: string,
+  supervisor: Supervisor | undefined,
+  peerAddr: string | null,
+): Promise<Response | undefined> {
+  // Lenient — see hub#406 (same posture as proxyToVault).
+  const services = readManifestLenient(manifestPath).services;
+  const entry = findServiceByShort(services, "vault");
+  if (!entry) return undefined;
+  if (effectivePublicExposure(entry) === "loopback" && layerOf(req, peerAddr) !== "loopback") {
+    return new Response("not found", { status: 404 });
+  }
+  return proxyRequest(req, entry.port, "vault", "vault", supervisor, peerAddr);
 }
 
 /**
@@ -784,15 +1053,15 @@ async function proxyToService(
   ) {
     return new Response("not found", { status: 404 });
   }
-  // Consult FIRST_PARTY_FALLBACKS as a fallback for `stripPrefix` (#196).
-  // Pre-hub#310, scribe's `stripPrefix: true` lived only in hub's vendored
-  // fallback; post-#310 scribe self-registers with `stripPrefix: true` on
-  // its row, so the entry-based path is authoritative for scribe. The
-  // fallback consultation now matters only for notes / channel
-  // (FIRST_PARTY_FALLBACKS shorts that haven't yet self-registered with
-  // the canonical declaration). Explicit-on-entry still wins; absent →
-  // fallback → false (preserving the keep-prefix default for unknown
-  // services).
+  // Consult FIRST_PARTY_FALLBACKS / KNOWN_MODULES as a fallback for
+  // `stripPrefix` (#196). Pre-hub#310, scribe's `stripPrefix: true` lived
+  // only in hub's vendored fallback; post-#310 scribe (and post-D3 channel)
+  // self-register with `stripPrefix: true` on their rows, so the entry-based
+  // path is authoritative. The registry consultation now matters only for
+  // notes (the remaining FALLBACK short) and legacy rows written before the
+  // module emitted the field (KNOWN_MODULES canonicalStripPrefix).
+  // Explicit-on-entry still wins; absent → fallback → false (preserving the
+  // keep-prefix default for unknown services).
   const stripPrefix = stripPrefixFor(match.entry);
   const targetPath = stripPrefix ? url.pathname.slice(match.mount.length) || "/" : undefined;
   // Resolve canonical short for classification — falls back to the
@@ -801,20 +1070,21 @@ async function proxyToService(
   // will land in "persistent" by default which is the safer choice for
   // unknown lifecycle).
   const short = shortNameForManifest(match.entry.name) ?? match.entry.name;
-  return proxyRequest(req, match.port, match.entry.name, short, supervisor, targetPath);
+  return proxyRequest(req, match.port, match.entry.name, short, supervisor, peerAddr, targetPath);
 }
 
 /**
  * Resolve effective `stripPrefix` for a service entry. Explicit on-entry
  * wins; otherwise consult `FIRST_PARTY_FALLBACKS` keyed by short name (for
- * notes / channel — vault/scribe/runner retired their FALLBACK entries in
- * hub#310 and self-register with the canonical `stripPrefix` declaration on
- * their services.json row). `KNOWN_MODULES[short]?.canonicalStripPrefix`
- * is the next fallback — covers the edge case where a self-registering
- * module wrote its row before the `stripPrefix` field was being emitted
- * (e.g. pre-scribe#50 services.json rows). Defaults to `false` — keep the
- * prefix — matching the pre-#196 dispatch behavior for unknown / third-
- * party services.
+ * notes — vault/scribe/runner retired their FALLBACK entries in hub#310,
+ * channel in boundary D3; all self-register with the canonical `stripPrefix`
+ * declaration on their services.json row).
+ * `KNOWN_MODULES[short]?.canonicalStripPrefix` is the next fallback — covers
+ * the edge case where a self-registering module wrote its row before the
+ * `stripPrefix` field was being emitted (e.g. pre-scribe#50 or pre-D3
+ * channel services.json rows). Defaults to `false` — keep the prefix —
+ * matching the pre-#196 dispatch behavior for unknown / third-party
+ * services.
  *
  * For a self-registering KNOWN_MODULES short whose row is missing entirely
  * (uninstalled, never booted), the request never reaches this code path —
@@ -873,6 +1143,11 @@ export interface HubFetchDeps {
    * the doc reflect `parachute vault create` etc. without re-running expose.
    */
   manifestPath?: string;
+  /**
+   * Path to `connections.json` (the Connections store, P5). Tests point this
+   * at a tmpdir; production defaults to `<CONFIG_DIR>/connections.json`.
+   */
+  connectionsStorePath?: string;
   /**
    * Directory containing the built SPA bundle (`index.html` + `assets/`). When
    * absent, the hub auto-resolves to `<repo>/web/ui/dist/` — handy for the
@@ -922,6 +1197,15 @@ export interface HubFetchDeps {
    * CLI commands directly.
    */
   supervisor?: Supervisor;
+  /**
+   * WebSocket connection-cap accounting (hub#649). Production uses the
+   * process-wide {@link defaultWsConnectionTracker} (caps from env at boot);
+   * tests inject their own tracker so they neither consume nor depend on the
+   * shared counters. Release pairing is structural — the acquire site stashes
+   * the release closure on the upgraded socket's `data`, so a mismatched
+   * tracker between fetch fn and bridge handlers is impossible.
+   */
+  wsConnectionTracker?: WsConnectionTracker;
 }
 
 /**
@@ -1024,8 +1308,9 @@ function defaultSpaDistDir(): string {
  * The admin SPA serves at a single mount: `/admin/*` (since hub#231).
  *
  * Routes:
- *   - `/admin/vaults`       → vault list (the SPA's home)
- *   - `/admin/vaults/new`   → vault create form
+ *   - `/admin/`             → Home (the admin-shell overview)
+ *   - `/admin/vaults`       → legacy vault list; feature-detects a new-manifest
+ *                             vault and forwards to `/vault/admin/` (B5)
  *   - `/admin/permissions`  → OAuth consent grant management
  *   - `/admin/tokens`       → token registry: mint / list / revoke
  *
@@ -1328,15 +1613,230 @@ export function resolveIssuerSource(
 
 /**
  * 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
+ * receives as its 2nd argument. We need `requestIP` (item E / #526) to
+ * resolve the peer address for `layerOf`, and `upgrade` (H1) to hand a
+ * gated WebSocket upgrade to the bridge. 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`.
+ * case `peerAddr` is null and `layerOf` fails closed to `public`, and a
+ * WebSocket upgrade is refused (503 — no server to upgrade on).
  */
 interface PeerIpResolver {
   requestIP(req: Request): { address: string } | null;
+  /**
+   * Bun `Server.upgrade` — present on the real server, optional on fakes.
+   * Typed with the bridge's data payload (Bun's own signature takes
+   * `data: unknown`; method bivariance keeps the real Server assignable).
+   */
+  upgrade?(req: Request, options: { data: WsBridgeData }): boolean;
+}
+
+/**
+ * True when the request is a WebSocket upgrade. The `Upgrade` header is the
+ * discriminator (RFC 6455 §4.1 requires it; Bun's `server.upgrade` re-checks
+ * the full handshake — key, version, Connection token — so this only needs
+ * to be a cheap router predicate, not a validator).
+ */
+export function isWebSocketUpgrade(req: Request): boolean {
+  return (req.headers.get("upgrade") ?? "").toLowerCase() === "websocket";
+}
+
+/**
+ * Hop-by-hop + WS-handshake headers never forwarded on the upstream connect:
+ * the Bun WebSocket client re-mints its own handshake (key/version/
+ * extensions), and forwarding the originals would corrupt it.
+ */
+const WS_HOP_BY_HOP_HEADERS = [
+  "host",
+  "connection",
+  "upgrade",
+  "keep-alive",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "sec-websocket-key",
+  "sec-websocket-version",
+  "sec-websocket-extensions",
+  "sec-websocket-accept",
+  // Subprotocol negotiation is NOT forwarded in v1 (see ws-bridge.ts header).
+  "sec-websocket-protocol",
+] as const;
+
+/** The verdict of {@link maybeUpgradeWebSocket}. */
+type WsUpgradeVerdict =
+  | { kind: "upgraded" }
+  | { kind: "response"; response: Response }
+  | { kind: "pass" };
+
+/**
+ * H1 — the WebSocket upgrade bridge's routing + gating half (the frame
+ * piping lives in `src/ws-bridge.ts`).
+ *
+ * For an `Upgrade: websocket` request:
+ *
+ *   1. Resolve the service mount (generic longest-prefix, then vault mounts —
+ *      same resolution as the HTTP proxies). No mount → `pass` (normal
+ *      dispatch 404s / handles it).
+ *   2. Gate BEFORE upgrading — same posture as the HTTP path:
+ *      `publicExposure: "loopback"` cloak (404, indistinguishable from
+ *      not-installed) and the per-UI audience gate (H3).
+ *   3. Capability check, DENY BY DEFAULT: the module must declare
+ *      `websocket: true` on its services.json row OR its
+ *      `.parachute/module.json`. No declaration → 426 (the route exists but
+ *      doesn't speak WebSocket; the fetch-based proxy can't forward upgrades
+ *      and the daemon never sees the request).
+ *   4. Connection caps (hub#649): per-client-IP + total concurrent caps,
+ *      checked-and-acquired in the same synchronous block as the upgrade
+ *      (no await between check and commit). Over-cap → generic 429 (no
+ *      count leakage; the hub log carries which cap + bucket), refused
+ *      BEFORE `server.upgrade()` commits a socket or the bridge dials the
+ *      upstream. Keying + trust model: {@link wsCapBucketKey}; defaults +
+ *      env overrides: `ws-connection-caps.ts`. Release rides the bridge's
+ *      close handler via `data.releaseCap`.
+ *   5. `server.upgrade(req, { data })` with the upstream URL + headers
+ *      (client headers minus hop-by-hop/handshake, plus the H2 substrate
+ *      trust stamps). The ws-bridge handlers take over from there.
+ */
+async function maybeUpgradeWebSocket(
+  req: Request,
+  server: PeerIpResolver | undefined,
+  deps: {
+    manifestPath: string;
+    peerAddr: string | null;
+    readModuleManifestFn: (installDir: string) => Promise<ModuleManifest | null>;
+    /** H3 — gate the upgrade on the mount's audience BEFORE upgrading. */
+    gateAudience?: (pathname: string) => Promise<Response | null>;
+    /** hub#649 — per-IP + total connection-cap accounting. */
+    wsConnectionTracker: WsConnectionTracker;
+  },
+): Promise<WsUpgradeVerdict> {
+  const services = readManifestLenient(deps.manifestPath).services;
+  const url = new URL(req.url);
+  const match =
+    findServiceUpstream(services, url.pathname) ?? findVaultUpstream(services, url.pathname);
+  if (!match) return { kind: "pass" };
+
+  // Layer cloak first — a loopback-only module must look not-installed from
+  // tailnet/public, for upgrades exactly as for HTTP.
+  if (
+    effectivePublicExposure(match.entry) === "loopback" &&
+    layerOf(req, deps.peerAddr) !== "loopback"
+  ) {
+    return { kind: "response", response: new Response("not found", { status: 404 }) };
+  }
+
+  // Audience gate (H3) — runs BEFORE the upgrade so an unauthorized client
+  // never gets a socket. Threaded from dispatch (needs db + issuer).
+  if (deps.gateAudience) {
+    const gated = await deps.gateAudience(url.pathname);
+    if (gated) return { kind: "response", response: gated };
+  }
+
+  // Capability — deny by default. services.json row wins; module.json is the
+  // canonical declaration source for modules that haven't re-registered yet.
+  let declared = match.entry.websocket === true;
+  if (!declared && match.entry.installDir) {
+    try {
+      const manifest = await deps.readModuleManifestFn(match.entry.installDir);
+      declared = manifest?.websocket === true;
+    } catch {
+      declared = false; // malformed manifest → deny (fail closed)
+    }
+  }
+  if (!declared) {
+    return {
+      kind: "response",
+      response: new Response(
+        JSON.stringify({
+          error: "websocket_not_supported",
+          error_description: `module "${match.entry.name}" does not declare WebSocket support`,
+        }),
+        { status: 426, headers: { "content-type": "application/json", upgrade: "websocket" } },
+      ),
+    };
+  }
+
+  if (!server?.upgrade) {
+    return {
+      kind: "response",
+      response: new Response(
+        JSON.stringify({
+          error: "service_unavailable",
+          error_description: "websocket upgrade unavailable on this server",
+        }),
+        { status: 503, headers: { "content-type": "application/json" } },
+      ),
+    };
+  }
+
+  // Upstream URL — same path semantics as the HTTP proxy (stripPrefix honored).
+  const stripPrefix = stripPrefixFor(match.entry);
+  const targetPath = stripPrefix ? url.pathname.slice(match.mount.length) || "/" : url.pathname;
+  const upstreamUrl = `ws://127.0.0.1:${match.port}${targetPath}${url.search}`;
+
+  // Upstream headers: the client's own (cookie / authorization ride through
+  // so the daemon authenticates the connection) minus hop-by-hop + handshake
+  // headers, plus the H2 substrate trust stamps.
+  const headers = new Headers(req.headers);
+  for (const h of WS_HOP_BY_HOP_HEADERS) headers.delete(h);
+  stampSubstrateTrustHeaders(headers, req, deps.peerAddr);
+  const upstreamHeaders: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    upstreamHeaders[key] = value;
+  });
+
+  // Connection caps (hub#649) — the LAST gate, synchronous with the upgrade
+  // itself (everything between here and `server.upgrade` must stay
+  // await-free so the check can't race the commit). Last on purpose: the
+  // earlier refusals keep their precise statuses (the 404 cloak stays
+  // indistinguishable from not-installed even under cap pressure), and the
+  // counters only ever hold slots for connections that would actually
+  // bridge.
+  const capKey = wsCapBucketKey(req, deps.peerAddr);
+  const acquired = deps.wsConnectionTracker.tryAcquire(capKey);
+  if (!acquired.ok) {
+    // Operator-facing pressure signal: which cap, which bucket, how full.
+    // None of this reaches the client — the 429 body is deliberately
+    // generic (no counts, no cap identity).
+    console.warn(
+      `[ws-caps] refused upgrade for ${url.pathname}: ${
+        acquired.reason === "per_ip_cap" ? `per-IP cap (ip=${capKey})` : `total cap (ip=${capKey})`
+      }; total=${deps.wsConnectionTracker.totalCount} ip_count=${deps.wsConnectionTracker.countFor(
+        capKey,
+      )}`,
+    );
+    return {
+      kind: "response",
+      response: new Response(
+        JSON.stringify({
+          error: "too_many_connections",
+          error_description: "WebSocket connection limit reached; try again later",
+        }),
+        { status: 429, headers: { "content-type": "application/json" } },
+      ),
+    };
+  }
+
+  const upgraded = server.upgrade(req, {
+    data: { upstreamUrl, upstreamHeaders, releaseCap: acquired.release },
+  });
+  if (upgraded) return { kind: "upgraded" };
+  // No socket was created, so the bridge's close handler will never fire —
+  // release the slot inline (the closure latches, so this can't double-count
+  // against a later close).
+  acquired.release();
+  return {
+    kind: "response",
+    response: new Response(
+      JSON.stringify({
+        error: "upgrade_failed",
+        error_description: "WebSocket handshake was malformed or could not be completed",
+      }),
+      { status: 400, headers: { "content-type": "application/json" } },
+    ),
+  };
 }
 
 /**
@@ -1467,6 +1967,49 @@ export function hubFetch(
     // error detail"). A transient SQLITE_BUSY is classified non-fatal and just
     // surfaces a 503 the next request clears — it never kills the hub.
     try {
+      // H1 — WebSocket upgrade bridge. Runs before normal dispatch: an
+      // `Upgrade: websocket` request targeting a declared service mount is
+      // gated (publicExposure cloak + audience gate) and, if it passes,
+      // upgraded into the Bun-native bridge (src/ws-bridge.ts) instead of
+      // the fetch-based proxy (which cannot forward upgrades). Upgrade
+      // requests that match no service mount fall through to normal dispatch
+      // unchanged — no hub-owned route speaks WebSocket.
+      if (isWebSocketUpgrade(req)) {
+        const verdict = await maybeUpgradeWebSocket(req, server, {
+          manifestPath,
+          peerAddr,
+          readModuleManifestFn: deps?.readModuleManifest ?? defaultReadModuleManifest,
+          wsConnectionTracker: deps?.wsConnectionTracker ?? defaultWsConnectionTracker,
+          // H3 — the audience gate runs BEFORE the upgrade, same posture as
+          // the HTTP dispatch below: a WS endpoint under a hub-users surface
+          // never hands a socket to an anonymous caller, while `surface`
+          // audiences pass through (the backed surface authenticates the
+          // socket itself — e.g. the docs editor's collab WS rides this).
+          // (The publicExposure cloak already ran inside
+          // maybeUpgradeWebSocket before this hook.)
+          gateAudience: async (wsPathname) => {
+            const wsUiMatch = resolveUiMount(
+              readManifestLenient(manifestPath).services,
+              wsPathname,
+            );
+            if (!wsUiMatch) return null;
+            return gateUiAudience(req, wsUiMatch.audience, wsUiMatch.ui, {
+              db: getDb?.(),
+              knownIssuers: () => oauthDeps(req).hubBoundOrigins(),
+            });
+          },
+        });
+        if (verdict.kind === "upgraded") {
+          // Bun's contract after a successful `server.upgrade()` is to
+          // return undefined from fetch — the socket now belongs to the
+          // websocket handlers. The public signature stays Response-typed
+          // for the many direct (non-WS) call sites; this cast is the one
+          // deliberate exception, observed only by Bun's runtime.
+          return undefined as unknown as Response;
+        }
+        if (verdict.kind === "response") return verdict.response;
+        // kind === "pass" — fall through to normal dispatch.
+      }
       return await dispatch();
     } catch (err) {
       const klass = classifyDbError(err);
@@ -1497,11 +2040,17 @@ export function hubFetch(
     async function dispatch(): Promise<Response> {
       // 301 back-compat for the pre-hub#231 admin-SPA mounts:
       //
-      //   `/vault`            → `/admin/vaults`
-      //   `/vault/new`        → `/admin/vaults/new`
+      //   `/vault`, `/vault/new` → `/vault/admin/` (vault's own daemon-level
+      //                        admin surface — B5, 2026-06-09 hub-module-
+      //                        boundary migration. These pointed at
+      //                        `/admin/vaults[/new]` until B5; with the
+      //                        list+create UX module-owned, pointing DIRECTLY
+      //                        at the target avoids a redirect → SPA-load →
+      //                        client-side-forward chain)
       //   `/hub/vaults*`      → `/admin/vaults*` (this redirect predates #231;
-      //                        it now retargets at the new admin mount instead
-      //                        of the interim `/vault` mount)
+      //                        /admin/vaults survives as the feature-detected
+      //                        legacy list, so the target stays valid on both
+      //                        old-vault and new-vault boxes)
       //   `/hub/permissions`  → `/admin/permissions`
       //   `/hub/tokens`       → `/admin/tokens`
       //   `/hub` (bare)       → `/admin/vaults`
@@ -1513,12 +2062,13 @@ export function hubFetch(
       // POST endpoint to protect.
       //
       // `/vault/<name>/*` is INTENTIONALLY excluded — that's the per-vault
-      // content proxy (Notes PWA, etc.), not the admin SPA. Stays where it is.
+      // content proxy (Notes PWA, etc.), not the admin SPA. The exact-match
+      // condition here also never touches `/vault/admin*` — the daemon-level
+      // mount dispatched further down.
       if (pathname === "/vault" || pathname === "/vault/" || pathname === "/vault/new") {
-        const sub = pathname === "/vault/new" ? "/new" : "";
         return new Response("", {
           status: 301,
-          headers: { location: `/admin/vaults${sub}${url.search}` },
+          headers: { location: `/vault/admin/${url.search}` },
         });
       }
       if (pathname === "/hub/vaults" || pathname.startsWith("/hub/vaults/")) {
@@ -1795,7 +2345,35 @@ export function hubFetch(
         );
       }
 
-      if (pathname === "/" || pathname === "/hub.html") {
+      // Bare `/` → `/admin` (admin-shell IA, R1). The home page and the admin
+      // SPA used to be two disconnected surfaces; `/` now funnels straight into
+      // the single coherent admin shell, whose Home/Overview carries the
+      // discovery content (hub-native sections, modules, user surfaces) that
+      // used to live here.
+      //
+      // Ordering matters: this sits AFTER the fresh-hub wizard funnel above
+      // (so a brand-new operator still lands on `/admin/setup`, not a 404 inside
+      // the shell) and AFTER the pre-admin lockout (so an admin-less hub still
+      // 503s API callers correctly). 302 (not 301) — `/` is reclaimed for
+      // future use, but a permanent redirect would get cached and we may want
+      // `/` back later.
+      //
+      // The signed-out path is preserved: a signed-out visitor lands on
+      // `/admin`, where the SPA's AuthIndicator shows a "Sign in" link that
+      // round-trips through `/login?next=/admin/...` and back. We don't pin the
+      // redirect on session state — the shell handles both auth states itself.
+      //
+      // `/hub.html` is INTENTIONALLY excluded: it still renders the discovery
+      // page (used by the static `parachute expose --set-path=/` disk file and
+      // any bookmark to the explicit `.html`). Only the bare `/` redirects.
+      if (pathname === "/") {
+        return new Response(null, {
+          status: 302,
+          headers: { location: "/admin" },
+        });
+      }
+
+      if (pathname === "/hub.html") {
         // When a DB is configured, render the discovery page dynamically so
         // the header carries a "Signed in as <name>" affordance for the
         // active session. Without a DB, fall back to the static disk file
@@ -2063,6 +2641,47 @@ export function hubFetch(
         });
       }
 
+      // DELETE /vaults/<name> — destroy a vault with the full identity
+      // cascade (B1, 2026-06-09 hub-module-boundary: lifecycle symmetry).
+      // Bearer parachute:host:admin + {"confirm": "<name>"} body. See
+      // admin-vaults.handleDeleteVault for the enumerated cascade.
+      if (pathname.startsWith("/vaults/")) {
+        if (!getDb) return dbNotConfigured();
+        const name = decodeURIComponent(pathname.slice("/vaults/".length));
+        const services = readManifestLenient(manifestPath).services;
+        // Channel's row carries its MANIFEST name — resolve via
+        // findServiceByShort (see the /admin/connections note below).
+        const channelEntry = findServiceByShort(services, "channel");
+        const channelOrigin = channelEntry ? `http://127.0.0.1:${channelEntry.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,
+          manifestPath,
+          connectionsStorePath: deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
+          channelOrigin,
+          resolveVaultOrigin,
+          resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
+          // Daemon eviction — the same in-process supervisor the lifecycle
+          // verbs drive (module-ops API); restarting vault evicts the open
+          // store handle + re-runs selfRegister (services.json path rebuild).
+          ...(supervisor
+            ? {
+                restartVaultModule: async () => {
+                  await supervisor.restart("vault");
+                },
+              }
+            : {}),
+        });
+      }
+
       // Note: the old `/hub/*` SPA mount has been retired. Known prefixes
       // (`/hub`, `/hub/vaults*`, `/hub/permissions`, `/hub/tokens`) are
       // 301-redirected at the top of dispatch. Any other `/hub/*` path falls
@@ -2076,6 +2695,98 @@ export function hubFetch(
         });
       }
 
+      if (pathname === "/admin/channel-token") {
+        if (!getDb) return dbNotConfigured();
+        return handleChannelToken(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/channel-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
+      // 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/")) {
+        if (!getDb) return dbNotConfigured();
+        const short = decodeURIComponent(pathname.slice("/admin/module-token/".length));
+        return handleModuleToken(req, short, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          // Lenient + per-request — a module that self-registered since hub
+          // boot is mintable without a restart (see hub#406 for lenient).
+          readServices: () => readManifestLenient(manifestPath).services,
+          ...(deps?.readModuleManifest ? { readModuleManifest: deps.readModuleManifest } : {}),
+        });
+      }
+
+      // 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. Channel's own admin page
+      // drives `/admin/connections` + `/admin/channel-token`.
+
+      // Connections — the GENERAL module event→action engine (2026-06-09
+      // modular-UI architecture, P5). `/api/connections/catalog` (GET) returns
+      // the available events/actions read from each installed module's
+      // `module.json`; `/admin/connections` (GET/POST) lists + provisions;
+      // `/admin/connections/:id` (DELETE) tears down. Cookie-gated to the
+      // first-admin operator. The provisioning engine derives the vault
+      // trigger's webhook + scope from the SINK action's declaration —
+      // nothing is channel-hardcoded.
+      if (
+        pathname === "/api/connections/catalog" ||
+        pathname === "/admin/connections" ||
+        pathname.startsWith("/admin/connections/")
+      ) {
+        if (!getDb) return dbNotConfigured();
+        const services = readManifestLenient(manifestPath).services;
+        // Channel's services.json row carries its MANIFEST name
+        // (`parachute-channel`), not the bare short `channel` — resolve via
+        // findServiceByShort so the lookup matches the on-disk row. (A bare
+        // `s.name === "channel"` never matched, leaving channelOrigin null →
+        // "channel not installed".)
+        const channelEntry = findServiceByShort(services, "channel");
+        const channelOrigin = channelEntry ? `http://127.0.0.1:${channelEntry.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 readManifestFn = deps?.readModuleManifest ?? defaultReadModuleManifest;
+        const modules = await collectInstalledModules(manifestPath, readManifestFn);
+        const connectionsDeps: ConnectionsDeps = {
+          db: getDb(),
+          hubOrigin: oauthDeps(req).issuer,
+          modules,
+          resolveVaultOrigin,
+          resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
+          channelOrigin,
+          storePath: deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
+        };
+        if (pathname === "/api/connections/catalog") {
+          return handleConnectionsCatalog(req, connectionsDeps);
+        }
+        // CSRF belt (hub#632, boundary C1): cookie-authed POST/DELETE must
+        // carry a matching Origin. The seam's canonical consumer — channel's
+        // admin page POSTing link-vault with `credentials: "include"` — is a
+        // same-origin fetch() and passes; see origin-check.ts
+        // `assertSameOriginForCookieMutation` for the belted-endpoint
+        // enumeration.
+        {
+          const rejected = assertSameOriginForCookieMutation(req, oauthDeps(req).hubBoundOrigins());
+          if (rejected) return rejected;
+        }
+        const subPath = pathname.slice("/admin/connections".length);
+        return handleConnections(req, subPath, connectionsDeps);
+      }
+
       if (pathname.startsWith("/admin/vault-admin-token/")) {
         if (!getDb) return dbNotConfigured();
         const vaultName = decodeURIComponent(pathname.slice("/admin/vault-admin-token/".length));
@@ -2218,28 +2929,12 @@ export function hubFetch(
         });
       }
 
-      // Per-module config surface (hub#260) — schema + values GET, values PUT.
-      // Sits ahead of the install/restart/upgrade/uninstall switch below so
-      // `/api/modules/<short>/config[/schema]` doesn't fall into the default-
-      // branch 404 (`parseModulesPath` only matches the action-suffix shape,
-      // not the `config` / `config/schema` shape).
-      //
-      // Diverges from the action endpoints in two ways: doesn't require a
-      // supervisor (we just proxy to the running module's HTTP surface, not
-      // spawn a child), and mints a `<short>:admin` token at proxy time so
-      // the upstream auth gate is satisfied without forcing the SPA bearer
-      // to carry per-module scopes.
-      {
-        const configMatch = parseModulesConfigPath(pathname);
-        if (configMatch) {
-          if (!getDb) return dbNotConfigured();
-          return handleApiModulesConfig(req, configMatch, {
-            db: getDb(),
-            issuer: oauthDeps(req).issuer,
-            manifestPath: deps?.manifestPath ?? SERVICES_MANIFEST_PATH,
-          });
-        }
-      }
+      // NOTE: the hub-hosted generic per-module config proxy
+      // (`/api/modules/<short>/config[/schema]`) + its SPA form were RETIRED in
+      // 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/channel-token`).
 
       // Per-module action endpoints: /api/modules/:short/{install,restart,upgrade,uninstall}.
       if (pathname.startsWith("/api/modules/")) {
@@ -2669,8 +3364,10 @@ export function hubFetch(
       }
 
       // Legacy `/admin/config` (server-rendered module-config portal, #46)
-      // retired post-SPA-rework. 301 → the SPA home so any bookmark or stale
-      // post-login redirect lands somewhere useful. The route stays here in
+      // retired post-SPA-rework. 301 → /admin/vaults so any bookmark or stale
+      // post-login redirect lands somewhere useful (post-B5 that's the
+      // feature-detected vaults surface — legacy list on an old-vault box,
+      // forward to /vault/admin/ on a new one). The route stays here in
       // dispatch order (above the /admin/* SPA catch-all) so the redirect
       // wins over a SPA shell render.
       if (pathname === "/admin/config" || pathname.startsWith("/admin/config/")) {
@@ -2680,10 +3377,31 @@ export function hubFetch(
         });
       }
 
+      // /vault/admin + /vault/admin/* — the vault MODULE's daemon-level
+      // admin surface (B-route, 2026-06-09 hub-module-boundary). MUST run
+      // BEFORE the per-vault proxy dispatch below: this is a module-level
+      // mount, not an instance path. "admin" is a reserved vault name (B2h)
+      // so no instance can claim it, and `findVaultUpstream` never sees it —
+      // no consumer fabricates a phantom vault named "admin". Exact-segment
+      // match only: a vault instance named e.g. "adminx" still routes
+      // per-instance through the branch below.
+      if (pathname === "/vault/admin" || pathname.startsWith("/vault/admin/")) {
+        // Same per-request force-change-password gate as the per-vault proxy
+        // (P0-1 / hub#469) — a pre-rotation signed-in user can't reach the
+        // multi-vault admin surface on an un-rotated temp password either.
+        if (getDb) {
+          const gate = forceChangePasswordGate(getDb(), req);
+          if (gate) return gate;
+        }
+        const proxied = await proxyToVaultAdmin(req, manifestPath, deps?.supervisor, peerAddr);
+        if (proxied) return decorateWithChrome(proxied, req, pathname, getDb);
+        return new Response("not found", { status: 404 });
+      }
+
       // /vault/<name>/* — per-vault content proxy. Stays as user-facing
       // surface (the Notes PWA loads through here, etc.). The bare `/vault`
       // and `/vault/new` paths were SPA routes pre-#231; they 301-redirect at
-      // the top of dispatch now. Multi-segment requests like
+      // the top of dispatch now (to `/vault/admin/` since B5). Multi-segment requests like
       // `/vault/<unknown>/health` are vault-API shapes targeting a
       // non-existent vault and 404 directly — there's no SPA-shell fallback
       // here anymore (the SPA moved to /admin), so we can't accidentally
@@ -2713,9 +3431,9 @@ export function hubFetch(
       // SPA's own router renders the page and handles 404 client-side for
       // unknown sub-paths.
       if (pathname === "/admin" || pathname === "/admin/") {
-        // Unprefixed /admin → SPA shell pointed at the vault list (its home).
-        // The SPA's basename is /admin, so the router will land on / and
-        // render VaultsList.
+        // Unprefixed /admin → SPA shell at its index route. The SPA's
+        // basename is /admin, so the router lands on / and renders Home
+        // (the admin-shell overview).
         if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
         return serveSpa(spaDistDir, pathname, "/admin");
       }
@@ -2728,8 +3446,54 @@ 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).
+      //
+      // 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
+      // enforced BEFORE forwarding: 'public' passes, 'surface' passes (the
+      // backed surface authenticates every request itself), 'hub-users'
+      // requires a session or a scope-satisfying Bearer, 'operator' requires
+      // the first admin. Module API paths outside any uis entry are NOT
+      // gated here — modules keep their own auth. Ordering nuance: when the
+      // row's publicExposure cloak would fire (loopback-only, non-loopback
+      // layer), the gate is SKIPPED so the 404 cloak stays indistinguishable
+      // from not-installed (a 401 here would leak the route's existence) —
+      // 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);
+      if (uiMatch) {
+        const cloaked =
+          effectivePublicExposure(uiMatch.entry) === "loopback" &&
+          layerOf(req, peerAddr) !== "loopback";
+        if (!cloaked) {
+          const denied = await gateUiAudience(req, uiMatch.audience, uiMatch.ui, {
+            db: getDb?.(),
+            knownIssuers: () => oauthDeps(req).hubBoundOrigins(),
+          });
+          if (denied) return denied;
+        }
+      }
       const proxied = await proxyToService(req, manifestPath, deps?.supervisor, peerAddr);
-      if (proxied) return decorateWithChrome(proxied, req, pathname, getDb);
+      if (proxied) {
+        // H5 — chrome-strip rides the gate: where the audience resolved
+        // `public`, the identity chrome is disabled for that mount (public
+        // readers aren't hub users). `surface` follows the same precedent —
+        // a backed surface's visitors are mostly capability-link invitees,
+        // NOT hub users, so the "Signed in as…" chrome would be wrong for
+        // them (and the surface owns its whole page anyway). Reuses the
+        // per-path opt-out mechanism the /surface/notes/ precedent
+        // established, generalized to the declared audience.
+        return decorateWithChrome(
+          proxied,
+          req,
+          pathname,
+          getDb,
+          uiMatch !== undefined && (uiMatch.audience === "public" || uiMatch.audience === "surface")
+            ? [uiMatch.mount]
+            : undefined,
+        );
+      }
 
       // 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
@@ -2757,6 +3521,14 @@ export function hubFetch(
  * wrapper threads in the session-aware chrome HTML and a `set-cookie`
  * append when a fresh CSRF cookie was minted.
  *
+ * `extraOptOutPrefixes` (H5) generalizes the static opt-out list: the
+ * dispatch passes the matched UI mount when the audience gate resolved
+ * `public` or `surface` — public readers (and a backed surface's
+ * capability-link invitees) aren't hub users, so the identity chrome
+ * ("Signed in as…", Sign in link) must not ride their pages. Same
+ * mechanism as the hardcoded `/surface/notes/` precedent, now driven by
+ * the sub-unit's declared audience instead of a hub-side path list.
+ *
  * When `getDb` isn't wired (hubFetch instantiated without state — tests,
  * cold-start hub minus DB), we still inject — the signed-out variant.
  */
@@ -2765,6 +3537,7 @@ async function decorateWithChrome(
   req: Request,
   pathname: string,
   getDb: HubFetchDeps["getDb"],
+  extraOptOutPrefixes?: readonly string[],
 ): Promise<Response> {
   // Build chrome HTML lazily — `buildChromeForRequest` already opens the DB
   // for the session lookup; calling it on a response that won't be rewritten
@@ -2785,6 +3558,9 @@ async function decorateWithChrome(
   const out = await injectChromeIntoResponse(res, {
     chromeHtml,
     pathname,
+    ...(extraOptOutPrefixes !== undefined && extraOptOutPrefixes.length > 0
+      ? { optOutPrefixes: [...CHROME_OPT_OUT_PREFIXES, ...extraOptOutPrefixes] }
+      : {}),
   });
   // Append set-cookie if a CSRF was minted AND the chrome was actually
   // injected (we know that by checking out !== res — pass-through preserves
@@ -2862,6 +3638,9 @@ if (import.meta.main) {
       issuer,
       loopbackPort: port,
     }),
+    // H1 — the WebSocket upgrade bridge's frame-piping handlers. Connections
+    // land here only after `maybeUpgradeWebSocket` gated + upgraded them.
+    websocket: createWsBridgeHandlers(),
   });
   // Register PID + port from the running hub itself so any startup path
   // (spawn-via-`ensureHubRunning` or a direct `bun src/hub-server.ts` from