@openparachute/hub 0.7.0 → 0.7.2-rc.1

package/src/hub-server.ts

@@ -51,16 +51,27 @@
  *                                                 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/agent-token            (GET)        → agent UI bearer mint (cookie-gated)
+ *   /admin/channel-token          (GET)        → 301 → /admin/agent-token (legacy; channel→agent rename 2026-06-17)
  *   /admin/module-token/<short>   (GET)        → generic module config-UI bearer mint <short>:admin (cookie-gated)
  *   /api/connections/catalog      (GET)        → events/actions across installed modules (cookie-gated)
  *   /admin/connections            (POST/GET)   → connection provision/list (cookie-gated; POST CSRF-belted)
  *   /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)
+ *   /admin/grants                 (PUT/GET)    → agent-connector grant upsert/list (4b-1; host-admin Bearer)
+ *   /admin/grants/<id>/material   (GET)        → injectable secret for an APPROVED grant (4b-1; host-admin Bearer)
+ *   /admin/grants/<id>/approve    (POST)       → operator approves a grant — mint (vault) / store (service) / static-bearer-or-start-OAuth (mcp, 4b-2) (cookie-gated; CSRF-belted)
+ *   /admin/grants/<id>/revoke     (POST)       → operator revokes a grant — drop the stored secret + best-effort issuer revoke (mcp, 4b-2) (cookie-gated; CSRF-belted)
+ *   /oauth/agent-grant/callback   (GET)        → OAuth-client redirect target for an mcp grant consent (4b-2; single-use state, no Bearer, NOT same-origin-belted — cross-site redirect in)
  *
  *   # "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/admin-lock               (GET)        → screen-lock status (cookie-gated; first-admin)
+ *   /api/admin-lock/{set,change,remove,unlock,lock,heartbeat} (POST) → manage the optional admin idle PIN lock (cookie-gated; CSRF)
  *   /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)
  *   /api/hub/upgrade/status       (GET)        → poll the on-disk hub-upgrade status (host:admin)
@@ -150,7 +161,12 @@ 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 {
+  type AgentGrantsDeps,
+  handleAgentGrants,
+  handleOAuthGrantCallback,
+} from "./admin-agent-grants.ts";
+import { handleAgentToken } from "./admin-agent-token.ts";
 import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
 import {
   type ConnectionsDeps,
@@ -173,6 +189,7 @@ import {
   handleAccountChangePasswordPost,
   handleAccountHomeGet,
 } from "./api-account.ts";
+import { handleAdminLock } from "./api-admin-lock.ts";
 import { handleHubUpgrade, handleHubUpgradeStatus } from "./api-hub-upgrade.ts";
 import { handleApiHub } from "./api-hub.ts";
 import { handleCreateInvite, handleListInvites, handleRevokeInvite } from "./api-invites.ts";
@@ -204,7 +221,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 +292,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;
@@ -448,7 +472,7 @@ function hasVaultInstalled(manifestPath: string): boolean {
  * 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
+ * user-facing prefix, e.g. `/agent`), which the engine joins with a sink
  * action's `endpoint` to build the hub-proxied webhook.
  */
 async function collectInstalledModules(
@@ -478,6 +502,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 +605,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 +755,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 +773,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 +819,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 +934,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);
 }
 
 /**
@@ -770,7 +943,7 @@ async function proxyToVault(
  * 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
+ * self-registered `parachute-vault` row — same shape as the agentEntry
  * 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`,
@@ -805,7 +978,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);
 }
 
 /**
@@ -896,7 +1069,8 @@ async function proxyToService(
   }
   // 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)
+  // only in hub's vendored fallback; post-#310 scribe (and post-D3 agent,
+  // renamed from channel 2026-06-17)
   // 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
@@ -911,19 +1085,19 @@ 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 — 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).
+ * agent (renamed from channel 2026-06-17) 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 —
+ * agent services.json rows). Defaults to `false` — keep the prefix —
  * matching the pre-#196 dispatch behavior for unknown / third-party
  * services.
  *
@@ -989,6 +1163,17 @@ export interface HubFetchDeps {
    * at a tmpdir; production defaults to `<CONFIG_DIR>/connections.json`.
    */
   connectionsStorePath?: string;
+  /**
+   * Path to `agent-grants.json` (the agent-connector grant store, 4b-1). Tests
+   * point this at a tmpdir; production defaults to `<CONFIG_DIR>/agent-grants.json`.
+   */
+  agentGrantsStorePath?: string;
+  /**
+   * Path to `agent-oauth-flows.json` (the in-flight agent-grant OAuth consents,
+   * 4b-2). Tests point this at a tmpdir; production defaults to
+   * `<CONFIG_DIR>/agent-oauth-flows.json`.
+   */
+  agentOAuthFlowsStorePath?: string;
   /**
    * Directory containing the built SPA bundle (`index.html` + `assets/`). When
    * absent, the hub auto-resolves to `<repo>/web/ui/dist/` — handy for the
@@ -1038,6 +1223,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 +1639,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 +1993,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);
@@ -1717,6 +2169,27 @@ export function hubFetch(
         }
       }
 
+      // `/channel/*` 301-redirects to `/agent/*` — back-compat for the
+      // 2026-06-17 channel→agent module rename. Operator bookmarks, an
+      // un-upgraded chat/config UI's deep links, and any externally-shared
+      // `/channel/mcp/<name>` URL keep resolving for one release cycle while
+      // the module's canonical mount moves to `/agent`. Method-agnostic, same
+      // shape as the `/notes/*` redirect above (the agent's read-write surface
+      // is its own daemon API, not the hub mount, so a re-issued GET is fine).
+      // Matches `/channel` exactly and any `/channel/...` subpath, but NOT a
+      // longer-prefix module like a hypothetical `/channelthing` — the guard is
+      // exact-or-slash-delimited. Query string is preserved. (The generic
+      // services-proxy fallthrough below would otherwise 404 a `/channel/*`
+      // request once the module self-registers under `/agent`.)
+      if (pathname === "/channel" || pathname.startsWith("/channel/")) {
+        const dest = new URL(req.url);
+        dest.pathname = `/agent${pathname.slice("/channel".length)}`;
+        return new Response("", {
+          status: 301,
+          headers: { location: dest.pathname + dest.search },
+        });
+      }
+
       // CORS preflight for the public OAuth + discovery surface. Browsers
       // issue OPTIONS before any non-simple cross-origin request — third-party
       // SPAs hitting `/oauth/register` (RFC 7591 DCR), `/oauth/token`,
@@ -1888,6 +2361,41 @@ export function hubFetch(
         }
       }
 
+      // Fresh-hub `/login` funnel (hub#644). `/login` is a browser-facing,
+      // server-rendered HTML surface (the sign-in form) — but on a no-admin
+      // box there is no account to sign in as, so the JSON-503 gate below
+      // would render as raw `{"error":"setup_required",...}` text in the
+      // visitor's tab. This is exactly the path a visitor takes when they
+      // load an open module surface (e.g. /vault/admin/) and click its
+      // "Sign in" banner, which links to `/login?next=<surface>`. Funnel the
+      // GET to the wizard instead, mirroring the `/` + `/hub.html` redirect
+      // above (same shape, same justification: never emit a JSON body on an
+      // HTML surface). 302 (not 301) so it disappears the moment setup
+      // completes and the real sign-in form takes over.
+      //
+      // Scoped to `userCount === 0` (the true no-admin state), NOT the
+      // broader `needsWizard`: once an admin exists, that operator must be
+      // able to reach the sign-in form even if no vault is installed yet
+      // (env-seed deploys). Only GET is funneled — a POST to `/login`
+      // pre-admin has no account to authenticate and falls through to the
+      // JSON-503 gate, the right shape for a stray non-browser caller.
+      //
+      // The `?next=<surface>` param is intentionally dropped: there's no
+      // account yet to return the visitor to, and the open surface they came
+      // from likely can't function until setup completes. They land on the
+      // wizard, not back on that surface.
+      //
+      // `cache-control: no-store` (the `/` + `/hub.html` funnel above omits
+      // it) — this 302 reflects transient pre-setup state that flips the
+      // moment an admin is created, so it must never be cached by a CDN or
+      // bfcache and serve a stale "go finish setup" to a now-set-up hub.
+      if (getDb && pathname === "/login" && req.method === "GET" && userCount(getDb()) === 0) {
+        return new Response(null, {
+          status: 302,
+          headers: { location: "/admin/setup", "cache-control": "no-store" },
+        });
+      }
+
       // Pre-admin lockout. When the hub has booted with no admin row (the
       // fresh-container case before PARACHUTE_INITIAL_ADMIN_* is set or
       // /admin/setup is walked), every operator-facing surface that requires
@@ -2207,6 +2715,38 @@ export function hubFetch(
         return applyCorsHeaders(req, await handleRevoke(getDb(), req, oauthDeps(req)));
       }
 
+      // Agent-connector OAuth-client callback (Phase 4b-2). The operator's
+      // browser is redirected here by a REMOTE issuer after consenting to a
+      // `kind:mcp` grant. Standalone server-rendered route — NOT under /admin/*,
+      // so the SPA catch-all never swallows it. GET, no Bearer: the single-use
+      // `state` it carries is the CSRF defense (this is a cross-site redirect IN
+      // from the remote issuer, so the same-origin belt does NOT apply). The
+      // handler looks up the pending flow by `state`, exchanges the code at the
+      // remote token endpoint, stores the grant material, and renders a tiny
+      // HTML "connected" / error page (never a token).
+      if (pathname === "/oauth/agent-grant/callback") {
+        if (!getDb) return dbNotConfigured();
+        if (req.method !== "GET") {
+          return new Response("method not allowed", { status: 405 });
+        }
+        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 agentGrantsDeps: AgentGrantsDeps = {
+          db: getDb(),
+          hubOrigin: oauthDeps(req).issuer,
+          storePath: deps?.agentGrantsStorePath ?? join(CONFIG_DIR, "agent-grants.json"),
+          flowsStorePath:
+            deps?.agentOAuthFlowsStorePath ?? join(CONFIG_DIR, "agent-oauth-flows.json"),
+          resolveVaultOrigin,
+        };
+        return handleOAuthGrantCallback(req, agentGrantsDeps);
+      }
+
       if (pathname === "/vaults") {
         if (!getDb) return dbNotConfigured();
         return handleCreateVault(req, {
@@ -2223,10 +2763,10 @@ export function hubFetch(
         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
+        // Agent'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 agentEntry = findServiceByShort(services, "agent");
+        const agentOrigin = agentEntry ? `http://127.0.0.1:${agentEntry.port}` : null;
         const resolveVaultOrigin = (vaultName: string): string | null => {
           const match = findVaultUpstream(
             readManifestLenient(manifestPath).services,
@@ -2240,8 +2780,9 @@ export function hubFetch(
           issuer: oauthDeps(req).issuer,
           manifestPath,
           connectionsStorePath: deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
-          channelOrigin,
+          agentOrigin,
           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).
@@ -2268,9 +2809,19 @@ export function hubFetch(
         });
       }
 
+      // Back-compat: the agent module's admin-token mint moved from
+      // `/admin/channel-token` to `/admin/agent-token` in the 2026-06-17
+      // channel→agent rename. 301-redirect the old path so operator bookmarks
+      // + any un-upgraded UI fallback keep working for one release cycle.
       if (pathname === "/admin/channel-token") {
+        const dest = new URL(req.url);
+        dest.pathname = "/admin/agent-token";
+        return Response.redirect(dest.toString(), 301);
+      }
+
+      if (pathname === "/admin/agent-token") {
         if (!getDb) return dbNotConfigured();
-        return handleChannelToken(req, {
+        return handleAgentToken(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
         });
@@ -2280,7 +2831,7 @@ export function hubFetch(
       // 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
+      // /admin/agent-token + /admin/vault-admin-token. Gated on
       // self-registration (services.json row + readable module.json) with the
       // bootstrap registries as a fallback (boundary C5) — a genuinely
       // third-party module mints here with zero hub code changes. Vault is
@@ -2300,8 +2851,9 @@ export function hubFetch(
 
       // Note: the legacy `/admin/channels` bespoke vault-channel orchestration
       // endpoint (pre-Connections, hub#624 era) was retired in boundary D1 —
-      // superseded by the general engine below. Channel's own admin page
-      // drives `/admin/connections` + `/admin/channel-token`.
+      // superseded by the general engine below. The agent module's own admin
+      // page (renamed from channel 2026-06-17) drives `/admin/connections` +
+      // `/admin/agent-token`.
 
       // Connections — the GENERAL module event→action engine (2026-06-09
       // modular-UI architecture, P5). `/api/connections/catalog` (GET) returns
@@ -2310,7 +2862,7 @@ export function hubFetch(
       // `/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.
+      // nothing is agent-hardcoded.
       if (
         pathname === "/api/connections/catalog" ||
         pathname === "/admin/connections" ||
@@ -2318,13 +2870,14 @@ export function hubFetch(
       ) {
         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
+        // Agent's services.json row carries its MANIFEST name
+        // (`parachute-agent`), not the bare short `agent` — 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;
+        // `s.name === "agent"` never matched, leaving agentOrigin null →
+        // "agent not installed".) A legacy un-upgraded `parachute-channel` row
+        // still resolves here via the LEGACY_MANIFEST_ALIASES fallback.
+        const agentEntry = findServiceByShort(services, "agent");
+        const agentOrigin = agentEntry ? `http://127.0.0.1:${agentEntry.port}` : null;
         const resolveVaultOrigin = (vaultName: string): string | null => {
           const match = findVaultUpstream(
             readManifestLenient(manifestPath).services,
@@ -2339,15 +2892,16 @@ export function hubFetch(
           hubOrigin: oauthDeps(req).issuer,
           modules,
           resolveVaultOrigin,
-          channelOrigin,
+          resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
+          agentOrigin,
           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
+        // carry a matching Origin. The seam's canonical consumer — the agent
+        // module'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.
@@ -2359,6 +2913,43 @@ export function hubFetch(
         return handleConnections(req, subPath, connectionsDeps);
       }
 
+      // Agent-connector GRANTS — the approval-gated resource-grant subsystem
+      // (Phase 4b-1, agent-connectors design 2026-06-17). Generalizes the
+      // Connections engine from "event→action triggers" to "approval-gated
+      // resource grants": an agent declares connections it WANTS beyond its
+      // def-vault; the agent module registers each as a pending grant (PUT,
+      // host-admin Bearer); the operator approves per-connection (POST
+      // /approve, first-admin cookie); the hub mints (vault) / stores (service)
+      // the secret; the agent module fetches it at spawn (GET /material,
+      // host-admin Bearer). Two auth classes split by route inside the handler.
+      if (pathname === "/admin/grants" || pathname.startsWith("/admin/grants/")) {
+        if (!getDb) return dbNotConfigured();
+        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 agentGrantsDeps: AgentGrantsDeps = {
+          db: getDb(),
+          hubOrigin: oauthDeps(req).issuer,
+          storePath: deps?.agentGrantsStorePath ?? join(CONFIG_DIR, "agent-grants.json"),
+          flowsStorePath:
+            deps?.agentOAuthFlowsStorePath ?? join(CONFIG_DIR, "agent-oauth-flows.json"),
+          resolveVaultOrigin,
+        };
+        // CSRF belt (same posture as /admin/connections, hub#632): a no-op for
+        // the host-admin-Bearer PUT/GET (Bearer → not a browser CSRF), and the
+        // real gate on the cookie-authed POST /approve + /revoke.
+        {
+          const rejected = assertSameOriginForCookieMutation(req, oauthDeps(req).hubBoundOrigins());
+          if (rejected) return rejected;
+        }
+        const subPath = pathname.slice("/admin/grants".length);
+        return handleAgentGrants(req, subPath, agentGrantsDeps);
+      }
+
       if (pathname.startsWith("/admin/vault-admin-token/")) {
         if (!getDb) return dbNotConfigured();
         const vaultName = decodeURIComponent(pathname.slice("/admin/vault-admin-token/".length));
@@ -2385,6 +2976,25 @@ export function hubFetch(
         return handleApiMe(req, { db: getDb() });
       }
 
+      // Admin screen-lock management (optional idle PIN lock for the admin
+      // UI). Session-cookie-gated to the first admin; these manage the lock
+      // itself so they are NOT behind the lock gate. The lock GATE lives in
+      // the four `/admin/*-token` mint handlers (admin-lock.ts:requireUnlocked)
+      // — it does NOT touch `/oauth/*`, so the OAuth issuer is unaffected.
+      if (pathname === "/api/admin-lock" || pathname.startsWith("/api/admin-lock/")) {
+        if (!getDb) return dbNotConfigured();
+        // CSRF belt (same posture as /admin/connections): these are
+        // cookie-authed JSON mutations. The handler ALSO checks a double-
+        // submit `__csrf` token; the Origin belt is defense-in-depth on the
+        // POST paths (GET status is read-shaped and skips it).
+        {
+          const rejected = assertSameOriginForCookieMutation(req, oauthDeps(req).hubBoundOrigins());
+          if (rejected) return rejected;
+        }
+        const subpath = pathname.slice("/api/admin-lock".length);
+        return handleAdminLock(req, subpath, { db: getDb() });
+      }
+
       // SPA-driven hub self-upgrade (design 2026-06-01 §5.3 / D4). Dedicated
       // endpoint — the hub is NOT a supervised module (no /api/modules/hub/*),
       // so it gets its own route. Checked BEFORE the `/api/hub` exact match
@@ -2506,7 +3116,7 @@ export function hubFetch(
       // the 2026-06-09 modular-UI architecture P3. Config is module-owned +
       // hub-framed now: the Modules page "Configure" action opens the module's
       // OWN config UI (`configUiUrl`), which mints its admin Bearer from the
-      // cookie-gated `/admin/module-token/<short>` (or `/admin/channel-token`).
+      // cookie-gated `/admin/module-token/<short>` (or `/admin/agent-token`).
 
       // Per-module action endpoints: /api/modules/:short/{install,restart,upgrade,uninstall}.
       if (pathname.startsWith("/api/modules/")) {
@@ -3018,8 +3628,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 +3703,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 +3719,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 +3740,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 +3820,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