@openparachute/hub 0.7.0 → 0.7.1

package/src/hub-server.ts

@@ -56,6 +56,9 @@
  *   /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
@@ -204,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";
@@ -270,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;
@@ -478,6 +488,23 @@ async function collectInstalledModules(
   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
@@ -564,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
@@ -595,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,
@@ -606,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);
@@ -651,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,
@@ -761,7 +920,7 @@ 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);
 }
 
 /**
@@ -805,7 +964,7 @@ async function proxyToVaultAdmin(
   if (effectivePublicExposure(entry) === "loopback" && layerOf(req, peerAddr) !== "loopback") {
     return new Response("not found", { status: 404 });
   }
-  return proxyRequest(req, entry.port, "vault", "vault", supervisor);
+  return proxyRequest(req, entry.port, "vault", "vault", supervisor, peerAddr);
 }
 
 /**
@@ -911,7 +1070,7 @@ 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);
 }
 
 /**
@@ -1038,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;
 }
 
 /**
@@ -1445,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" } },
+    ),
+  };
 }
 
 /**
@@ -1584,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);
@@ -2242,6 +2668,7 @@ export function hubFetch(
           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).
@@ -2339,6 +2766,7 @@ export function hubFetch(
           hubOrigin: oauthDeps(req).issuer,
           modules,
           resolveVaultOrigin,
+          resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
           channelOrigin,
           storePath: deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
         };
@@ -3018,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
@@ -3047,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.
  */
@@ -3055,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
@@ -3075,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
@@ -3152,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