@openparachute/hub 0.6.5-rc.8 → 0.7.1

package/src/vault-name.ts

@@ -10,7 +10,9 @@
  *
  *   * lowercase alphanumeric + hyphens or underscores
  *   * 2–32 chars
- *   * `list` is reserved
+ *   * `list` / `new` / `assets` / `admin` are reserved (see
+ *     `RESERVED_VAULT_NAMES` below — one consolidated set for every hub
+ *     edge, per the 2026-06-09 hub-module-boundary migration B2)
  *
  * If vault's validator changes (e.g. additional reserved name, length
  * relaxation), the two must move in lockstep — hub passing the typed
@@ -41,12 +43,30 @@ const VAULT_NAME_RE = VAULT_NAME_CHARSET_RE;
 const VAULT_NAME_MIN_LEN = 2;
 const VAULT_NAME_MAX_LEN = 32;
 
-const RESERVED_NAMES = new Set([
-  // Mirrors vault's reservation. Collides with the legacy `/vaults/list`
-  // discovery endpoint; the routes have moved under `/vault/<name>/` but
-  // vault's `cmdCreate` still rejects "list" and cross-repo consistency
-  // is cheap.
+/**
+ * THE reserved vault-name set — single source of truth for every hub edge
+ * that names a vault (B2h of the 2026-06-09 hub-module-boundary migration).
+ * Before the consolidation hub carried TWO drifted sets: this file held only
+ * `list` (gating the setup wizard + invite redemption via `validateVaultName`)
+ * while `admin-vaults.ts` held `{list, new, assets}` (gating POST /vaults
+ * only) — so a non-admin invite redeemer could squat names an admin couldn't.
+ *
+ *   - `list`   — mirrors vault's own `cmdCreate` reservation (legacy
+ *     `/vaults/list` discovery endpoint; cross-repo consistency is cheap).
+ *   - `new`    — collides with `/vault/new`, the SPA's create-vault route.
+ *   - `assets` — collides with `/vault/assets/*`, the SPA's static bundle.
+ *   - `admin`  — collides with `/vault/admin`, the daemon-level mount for
+ *     vault's own multi-vault admin surface (B-route). A vault named `admin`
+ *     would capture the mount.
+ *
+ * DELETE /vaults/<name> deliberately does NOT consult this set — a squatted
+ * reserved-name vault (created before the reservation) must be removable.
+ */
+export const RESERVED_VAULT_NAMES: ReadonlySet<string> = new Set([
   "list",
+  "new",
+  "assets",
+  "admin",
 ]);
 
 export type VaultNameValidation = { ok: true; name: string } | { ok: false; error: string };
@@ -73,7 +93,7 @@ export function validateVaultName(raw: string): VaultNameValidation {
       error: "vault names must be lowercase alphanumeric with hyphens or underscores.",
     };
   }
-  if (RESERVED_NAMES.has(name)) {
+  if (RESERVED_VAULT_NAMES.has(name)) {
     return { ok: false, error: `"${name}" is a reserved vault name.` };
   }
   return { ok: true, name };

package/src/well-known.ts

@@ -169,12 +169,17 @@ export interface BuildWellKnownOpts {
   /**
    * Optional resolver mapping a `ServiceEntry` to its `module.json:uiUrl`,
    * if any. Same shape as `managementUrlFor`. Returning `undefined` means
-   * "no user-facing UI" and discovery omits the Services tile. For vault
-   * entries, the declared `uiUrl` is the per-instance path (e.g. "/admin/")
-   * — `buildWellKnown` prefixes it with the per-instance mount path on
-   * emission, yielding one tile per vault instance pointing at
-   * `<origin>/vault/<name>/admin/`. See patterns#96
-   * `module-ui-declaration.md` §"Multi-instance services (vault)".
+   * "no user-facing UI" and discovery omits the Services tile.
+   *
+   * Resolution follows the B4 unified semantics (2026-06-09
+   * hub-module-boundary): http(s):// → verbatim; leading-`/` →
+   * ORIGIN-ABSOLUTE against the canonical origin (vault's daemon-level
+   * `/vault/admin/` emits as-is, once per row); RELATIVE (no leading slash,
+   * e.g. `"admin/"`) → the per-instance form, mount-joined per emitted path
+   * — for a multi-path vault entry that yields one tile per instance at
+   * `<origin>/vault/<name>/admin/`. The literal legacy `"/admin/"` on a
+   * vault entry rides the one-release compat shim (mount-join + deprecation
+   * log). See `buildWellKnown`'s uiUrl branch.
    */
   uiUrlFor?: (entry: ServiceEntry) => string | undefined;
   /**
@@ -227,6 +232,9 @@ function buildUisArray(uis: Record<string, UiSubUnit>, base: string): WellKnownU
   });
 }
 
+/** One-time deprecation log for the legacy vault `"/admin/"` uiUrl (B4 compat shim). */
+let warnedLegacyVaultUiUrl = false;
+
 export function buildWellKnown(opts: BuildWellKnownOpts): WellKnownDocument {
   const base = opts.canonicalOrigin.replace(/\/$/, "");
   const doc: WellKnownDocument = { vaults: [], services: [] };
@@ -257,43 +265,43 @@ export function buildWellKnown(opts: BuildWellKnownOpts): WellKnownDocument {
       // entry — no installDir round-trip needed since it's already
       // persisted server-side and reasonably stable across reboots.
       if (s.tagline !== undefined) entry.tagline = s.tagline;
-      // Resolve uiUrl. Three forms (per patterns#96
-      // `module-ui-declaration.md` §"Shape"):
+      // Resolve uiUrl. Unified URL-resolution semantics (B4 of the 2026-06-09
+      // hub-module-boundary migration — same doctrine as api-modules.ts
+      // `resolveModuleUrl` and the `resolveManagementUrl` pair):
       //   - Absolute http(s) URL → verbatim.
-      //   - Path on a non-vault entry → joined onto `base` directly.
-      //   - Path on a vault entry → joined onto `base` AFTER prefixing
-      //     with the per-instance mount path. Vault is the only
-      //     multi-instance service today; its declared `uiUrl: "/admin/"`
-      //     resolves to `<base>/vault/<name>/admin/` (one tile per
-      //     instance). The mount path is whichever `path` we're iterating
-      //     this loop turn (vault's `pathsToEmit` is its `paths[]`,
-      //     fanning one row per instance).
+      //   - Leading-`/` path → ORIGIN-ABSOLUTE: resolved against `base`
+      //     directly (`/scribe/admin` → `<base>/scribe/admin`; vault's
+      //     daemon-level `/vault/admin/` → `<base>/vault/admin/`, once,
+      //     NOT per instance).
+      //   - Relative path (no leading slash) → MOUNT-JOINED: the
+      //     per-instance form. Vault is the only multi-instance service
+      //     today; a declared `uiUrl: "admin/"` resolves to
+      //     `<base>/vault/<name>/admin/` (one tile per instance). The mount
+      //     is whichever `path` we're iterating this loop turn (vault's
+      //     `pathsToEmit` is its `paths[]`, fanning one row per instance).
       //
-      // Path concatenation: `path` is the canonical per-instance mount
-      // ("/vault/default", no trailing slash from services.json). `uiUrlRaw`
-      // starts with "/" per pattern rule. Direct concatenation yields the
-      // correct join ("/vault/default" + "/admin/" → "/vault/default/admin/").
+      // COMPAT SHIM (one release — remove once vault's new manifest reaches
+      // @latest): the literal legacy `"/admin"`/`"/admin/"` on a VAULT entry
+      // is the OLD per-instance relative declaration that deployed vaults
+      // still ship; it mount-joins (the pre-B4 behavior) with a deprecation
+      // log instead of resolving origin-absolute.
       const uiUrlRaw = opts.uiUrlFor?.(s);
       if (uiUrlRaw !== undefined) {
+        const mount = path.replace(/\/+$/, "");
         if (/^https?:\/\//i.test(uiUrlRaw)) {
           entry.uiUrl = uiUrlRaw;
-        } else if (isVault) {
-          // Defensive guard: vault uiUrl MUST start with "/" per the
-          // multi-instance pattern (see module-ui-declaration.md). A bare
-          // "admin/" (no leading slash) would concatenate into
-          // "/vault/defaultadmin/" — a silent malformed URL that 404s.
-          // Warn loudly instead of emitting garbage; the entry just
-          // omits its uiUrl rather than poisoning the well-known doc.
-          if (!uiUrlRaw.startsWith("/")) {
+        } else if (isVault && (uiUrlRaw === "/admin" || uiUrlRaw === "/admin/")) {
+          if (!warnedLegacyVaultUiUrl) {
+            warnedLegacyVaultUiUrl = true;
             console.warn(
-              `[well-known] vault entry "${s.name}" declares uiUrl=${JSON.stringify(uiUrlRaw)} without a leading slash; skipping uiUrl emission. Per module-ui-declaration.md, multi-instance uiUrl must be a path-form starting with "/".`,
+              `[well-known] vault entry "${s.name}" declares the legacy per-instance uiUrl ${JSON.stringify(uiUrlRaw)}; mount-joining for one release. New semantics: relative ("admin/") = per-instance mount-join, leading-"/" = origin-absolute. Upgrade the vault module to clear this.`,
             );
-          } else {
-            const mount = path.replace(/\/$/, "");
-            entry.uiUrl = new URL(`${mount}${uiUrlRaw}`, `${base}/`).toString();
           }
-        } else {
+          entry.uiUrl = new URL(`${mount}${uiUrlRaw}`, `${base}/`).toString();
+        } else if (uiUrlRaw.startsWith("/")) {
           entry.uiUrl = new URL(uiUrlRaw, `${base}/`).toString();
+        } else {
+          entry.uiUrl = new URL(`${mount}/${uiUrlRaw}`, `${base}/`).toString();
         }
       }
       // Hierarchical sub-units (hub#313 / parachute-app design doc §12). The

package/src/ws-bridge.ts

@@ -0,0 +1,256 @@
+/**
+ * Bun-native WebSocket upgrade bridge (H1, surface-runtime design §"Hub work
+ * items").
+ *
+ * The hub's HTTP proxy is fetch-based, and WebSocket upgrades don't traverse
+ * fetch — so until now the route table simply couldn't forward them (the
+ * hub-server docstring acknowledged it). This module is the transport half of
+ * the fix: when `hub-server.ts` accepts an upgrade for a service mount whose
+ * module DECLARES the capability (`websocket: true` on its services.json row
+ * or module.json — deny-by-default), it calls `server.upgrade(req, { data })`
+ * with a {@link WsBridgeData} payload, and these handlers pipe frames
+ * bidirectionally between the client socket and a Bun WebSocket client
+ * connected to the upstream daemon (same path, loopback).
+ *
+ * Scope discipline: this is TRANSPORT, not features —
+ *
+ *   - The upstream connect carries the substrate trust headers (H2:
+ *     X-Parachute-Layer / X-Parachute-Client-IP) plus the client's own
+ *     headers (cookie, authorization) so the module authenticates the
+ *     connection itself; the hub adds no WS-level auth of its own beyond the
+ *     route gates that ran BEFORE the upgrade (publicExposure cloak,
+ *     audience gate).
+ *   - Subprotocol negotiation (`Sec-WebSocket-Protocol`) is NOT forwarded in
+ *     v1 — none of the in-design consumers (y-websocket / Hocuspocus manual
+ *     pumping) require it; forwarding it correctly needs a negotiation
+ *     round-trip the first real consumer can motivate.
+ *   - Backpressure is a blunt cap, not flow control: when either side's
+ *     buffered amount exceeds {@link DEFAULT_MAX_BUFFERED_BYTES}, the bridge
+ *     closes BOTH sides (1011). A slow consumer should reconnect rather than
+ *     let the hub buffer unboundedly.
+ *   - Admission control is upstream of this module (hub#649): the gate in
+ *     `maybeUpgradeWebSocket` enforces per-client-IP + total connection caps
+ *     (defaults 32 / 512, env-overridable via PARACHUTE_WS_MAX_PER_IP /
+ *     PARACHUTE_WS_MAX_TOTAL — see `ws-connection-caps.ts`) BEFORE
+ *     `server.upgrade()`. The bridge's part of the contract is release: the
+ *     `close` handler below is the single funnel every accepted socket
+ *     passes through, so it invokes {@link WsBridgeData.releaseCap} first
+ *     thing — whatever the teardown reason — and the counters churn back to
+ *     zero with the sockets.
+ *
+ * Lifecycle: either side closing tears down the other (close code + reason
+ * propagated where the RFC 6455 rules allow), and an upstream connect failure
+ * closes the client with 1011. The bridge holds no per-connection state
+ * outside `ws.data`, so a dropped socket leaks nothing.
+ */
+
+import type { ServerWebSocket, WebSocketHandler } from "bun";
+
+/**
+ * Default cap on either side's buffered (un-flushed) bytes before the bridge
+ * gives up and closes both sockets. 8 MiB comfortably covers CRDT sync bursts
+ * (a full Yjs document state vector is typically KBs) while bounding what a
+ * slow or stalled consumer can pin in hub memory per connection.
+ */
+export const DEFAULT_MAX_BUFFERED_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Per-connection payload attached at `server.upgrade(req, { data })` time by
+ * the hub's dispatch (which already ran the route gates). Everything the
+ * bridge needs to dial the upstream — it never re-derives routing or trust.
+ */
+export interface WsBridgeData {
+  /** Absolute ws:// URL of the upstream daemon (same path + query, loopback). */
+  upstreamUrl: string;
+  /**
+   * Headers presented on the upstream connect: the client's own headers
+   * (minus hop-by-hop + WS handshake headers, which the Bun client re-mints)
+   * plus the H2 substrate trust stamps.
+   */
+  upstreamHeaders: Record<string, string>;
+  /**
+   * Releases this connection's slot in the connection-cap accounting
+   * (hub#649) — attached by the acquire site in `maybeUpgradeWebSocket`,
+   * invoked by the `close` handler. Self-disarming (safe to call more than
+   * once). Optional so handler-level unit tests that fake `ws.data` don't
+   * have to care about caps.
+   */
+  releaseCap?: () => void;
+  /** Internal bridge state — attached by `open()`, owned by this module. */
+  _bridge?: BridgeState;
+}
+
+interface BridgeState {
+  upstream: WebSocket;
+  /** Client frames received while the upstream is still CONNECTING. */
+  pending: (string | Uint8Array)[];
+  pendingBytes: number;
+  /** Set once either side initiated teardown — makes close idempotent. */
+  closed: boolean;
+}
+
+export interface WsBridgeOptions {
+  /** Override the buffered-bytes cap (tests use a tiny value). */
+  maxBufferedBytes?: number;
+  /** Test seam for the upstream WebSocket constructor. */
+  connectUpstream?: (url: string, headers: Record<string, string>) => WebSocket;
+  logger?: Pick<Console, "warn">;
+}
+
+/**
+ * RFC 6455: only codes 1000–4999 may be sent on the wire, and 1004/1005/1006/
+ * 1015 are reserved (never sent). A close event surfacing one of those (e.g.
+ * 1006 abnormal closure) is re-mapped to a no-code close, which the peer
+ * observes as 1005.
+ */
+function sendableCloseCode(code: number | undefined): number | undefined {
+  if (code === undefined) return undefined;
+  if (code < 1000 || code > 4999) return undefined;
+  if (code === 1004 || code === 1005 || code === 1006 || code === 1015) return undefined;
+  return code;
+}
+
+/** Close reasons are capped at 123 bytes on the wire (RFC 6455 §5.5.1). */
+function trimReason(reason: string | undefined): string {
+  if (!reason) return "";
+  // Trim by UTF-8 byte length, not string length.
+  let out = reason;
+  while (Buffer.byteLength(out, "utf8") > 123) out = out.slice(0, -1);
+  return out;
+}
+
+function closeQuietly(close: () => void): void {
+  try {
+    close();
+  } catch {
+    // Already closed / closing — teardown is best-effort by design.
+  }
+}
+
+/** Tear down both sides exactly once. */
+function closeBoth(
+  ws: ServerWebSocket<WsBridgeData>,
+  state: BridgeState,
+  code: number,
+  reason: string,
+): void {
+  if (state.closed) return;
+  state.closed = true;
+  closeQuietly(() => state.upstream.close(sendableCloseCode(code), trimReason(reason)));
+  closeQuietly(() => ws.close(sendableCloseCode(code), trimReason(reason)));
+}
+
+function frameBytes(frame: string | Uint8Array | ArrayBuffer): number {
+  if (typeof frame === "string") return Buffer.byteLength(frame, "utf8");
+  return frame instanceof ArrayBuffer ? frame.byteLength : frame.byteLength;
+}
+
+/**
+ * Build the Bun.serve `websocket` handler set implementing the bridge. One
+ * handler object serves every bridged connection; per-connection state lives
+ * on `ws.data`.
+ */
+export function createWsBridgeHandlers(opts: WsBridgeOptions = {}): WebSocketHandler<WsBridgeData> {
+  const cap = opts.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+  const logger = opts.logger ?? console;
+  const connect =
+    opts.connectUpstream ??
+    ((url: string, headers: Record<string, string>) =>
+      // Bun's WebSocket client accepts custom headers (a Bun extension over
+      // the WHATWG constructor) — this is what carries the H2 trust stamps +
+      // the client's cookies/authorization to the upstream daemon.
+      new WebSocket(url, { headers } as unknown as string[]));
+
+  return {
+    open(ws) {
+      let upstream: WebSocket;
+      try {
+        upstream = connect(ws.data.upstreamUrl, ws.data.upstreamHeaders);
+      } catch (err) {
+        logger.warn(
+          `[ws-bridge] upstream connect threw for ${ws.data.upstreamUrl}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        closeQuietly(() => ws.close(1011, "upstream connect failed"));
+        return;
+      }
+      upstream.binaryType = "arraybuffer";
+      const state: BridgeState = { upstream, pending: [], pendingBytes: 0, closed: false };
+      ws.data._bridge = state;
+
+      upstream.addEventListener("open", () => {
+        if (state.closed) {
+          closeQuietly(() => upstream.close(1000, ""));
+          return;
+        }
+        for (const frame of state.pending) upstream.send(frame);
+        state.pending = [];
+        state.pendingBytes = 0;
+      });
+
+      upstream.addEventListener("message", (ev: MessageEvent) => {
+        if (state.closed) return;
+        const data = ev.data as string | ArrayBuffer;
+        ws.send(typeof data === "string" ? data : new Uint8Array(data));
+        // Backpressure: the client isn't draining what the upstream sends.
+        if (ws.getBufferedAmount() > cap) {
+          closeBoth(ws, state, 1011, "bridge backpressure cap exceeded");
+        }
+      });
+
+      upstream.addEventListener("close", (ev: CloseEvent) => {
+        if (state.closed) return;
+        state.closed = true;
+        closeQuietly(() => ws.close(sendableCloseCode(ev.code), trimReason(ev.reason)));
+      });
+
+      upstream.addEventListener("error", () => {
+        // A connect refusal (upstream not listening) surfaces here before
+        // any close event. Tear down the client; the close listener above is
+        // a no-op afterwards thanks to the `closed` latch.
+        closeBoth(ws, state, 1011, "upstream error");
+      });
+    },
+
+    message(ws, message) {
+      const state = ws.data._bridge;
+      if (!state || state.closed) return;
+      const frame: string | Uint8Array =
+        typeof message === "string" ? message : new Uint8Array(message);
+      const { upstream } = state;
+      if (upstream.readyState === WebSocket.OPEN) {
+        upstream.send(frame);
+        // Backpressure: the upstream isn't draining what the client sends.
+        if (upstream.bufferedAmount > cap) {
+          closeBoth(ws, state, 1011, "bridge backpressure cap exceeded");
+        }
+      } else if (upstream.readyState === WebSocket.CONNECTING) {
+        state.pending.push(frame);
+        state.pendingBytes += frameBytes(frame);
+        if (state.pendingBytes > cap) {
+          closeBoth(ws, state, 1011, "bridge backpressure cap exceeded");
+        }
+      }
+      // CLOSING / CLOSED: drop the frame — teardown is already in flight.
+    },
+
+    close(ws, code, reason) {
+      // Connection-cap release FIRST (hub#649) — before the bridge-state
+      // early-returns, because this callback fires even for sockets whose
+      // upstream connect threw in open() (no `_bridge` attached) and is the
+      // one teardown funnel every accepted socket passes through. The
+      // closure latches, so re-entry is harmless.
+      ws.data.releaseCap?.();
+      // Client → upstream close propagation. Note: Bun's server-side close
+      // callback delivers the client's close CODE but an empty `reason`
+      // (verified on Bun 1.3.13), so only the code propagates upstream in
+      // this direction. Upstream → client propagation (the close listener in
+      // open()) carries both.
+      const state = ws.data._bridge;
+      if (!state || state.closed) return;
+      state.closed = true;
+      closeQuietly(() => state.upstream.close(sendableCloseCode(code), trimReason(reason)));
+    },
+  };
+}

package/src/ws-connection-caps.ts

@@ -0,0 +1,170 @@
+/**
+ * WebSocket connection caps for the upgrade bridge (hub#649) — the gate
+ * before any backed surface goes public-facing.
+ *
+ * The H1 bridge (`ws-bridge.ts`) holds one client socket + one upstream
+ * socket per connection, and the only per-connection bound before this
+ * module was the 8 MiB buffered-byte backpressure cap — a public client
+ * could hold upgrade slots open indefinitely at near-zero send rate and
+ * exhaust daemon memory at ~KB/connection. With the `surface` audience tier
+ * (H3, hub#651) anonymous WS is REACHABLE BY DESIGN on surface-audience
+ * mounts, so admission control can't lean on auth: the hub needs a blunt
+ * concurrent-connection bound of its own.
+ *
+ * Enforcement lives in `maybeUpgradeWebSocket` (hub-server.ts), which calls
+ * {@link WsConnectionTracker.tryAcquire} synchronously right before
+ * `server.upgrade()` — over-cap upgrades are refused with a clean HTTP 429
+ * (the upgrade never happens, so a normal Response is the correct refusal
+ * shape in Bun) BEFORE the proxy commits any socket or upstream-dial
+ * resources. The refusal body is generic: it never reveals counts, caps, or
+ * which cap tripped (the hub log carries the specifics for the operator).
+ *
+ * Release rides the bridge's socket lifecycle: the acquire site threads a
+ * self-disarming release closure into `ws.data` ({@link
+ * WsBridgeData.releaseCap}), and the bridge's Bun-level `close` handler —
+ * the single funnel every accepted socket passes through, whatever the
+ * teardown reason (client close, upstream close, backpressure, connect
+ * failure) — invokes it first thing. A failed `server.upgrade()` releases
+ * inline (no socket ⇒ no close callback). The closure latches, so a stray
+ * double-close can't corrupt the counters.
+ *
+ * Defaults (overridable via env, the hub's config precedent —
+ * `PARACHUTE_HUB_ORIGIN` et al.):
+ *
+ *   - {@link DEFAULT_WS_MAX_PER_IP} = 32 per client IP
+ *     (`PARACHUTE_WS_MAX_PER_IP`). An owner-operated box realistically
+ *     serves a handful of humans; a collab surface opens a socket or two
+ *     per tab, so 32 covers a small team behind one NAT egress IP with
+ *     headroom, while turning a single-source flood into a rotate-IPs
+ *     problem.
+ *   - {@link DEFAULT_WS_MAX_TOTAL} = 512 total (`PARACHUTE_WS_MAX_TOTAL`).
+ *     Bounds worst-case hub memory under a distributed flood (512 bridged
+ *     pairs ≈ low MBs idle) at a ceiling far above any realistic legitimate
+ *     concurrent load for a single-operator hub.
+ *
+ * Keying: callers derive the bucket key with `wsCapBucketKey`
+ * (hub-server.ts), which follows the hub's substrate trust model — forwarded
+ * IP headers are only believed when the peer is an on-box (loopback)
+ * forwarder; direct network peers key by their socket address no matter
+ * what headers they inject; an underivable IP lands in one shared bucket
+ * (fail closed, same posture as rate-limit.ts's UNKNOWN_IP_SENTINEL).
+ */
+
+/** Default cap on concurrent bridged WS connections per client-IP bucket. */
+export const DEFAULT_WS_MAX_PER_IP = 32;
+/** Default cap on concurrent bridged WS connections across all clients. */
+export const DEFAULT_WS_MAX_TOTAL = 512;
+
+/** Env var overriding {@link DEFAULT_WS_MAX_PER_IP}. */
+export const WS_MAX_PER_IP_ENV = "PARACHUTE_WS_MAX_PER_IP";
+/** Env var overriding {@link DEFAULT_WS_MAX_TOTAL}. */
+export const WS_MAX_TOTAL_ENV = "PARACHUTE_WS_MAX_TOTAL";
+
+export interface WsCaps {
+  maxPerIp: number;
+  maxTotal: number;
+}
+
+/**
+ * Parse the cap overrides from an env bag. Only positive integers are
+ * honored; absent / malformed / non-positive values fall back to the
+ * defaults (an operator typo must not silently disable the gate — fail to
+ * the safe defaults, never to "unlimited").
+ */
+export function wsCapsFromEnv(env: NodeJS.ProcessEnv = process.env): WsCaps {
+  return {
+    maxPerIp: parseCap(env[WS_MAX_PER_IP_ENV], DEFAULT_WS_MAX_PER_IP),
+    maxTotal: parseCap(env[WS_MAX_TOTAL_ENV], DEFAULT_WS_MAX_TOTAL),
+  };
+}
+
+function parseCap(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback;
+  const n = Number.parseInt(raw.trim(), 10);
+  if (!Number.isSafeInteger(n) || n <= 0 || String(n) !== raw.trim()) return fallback;
+  return n;
+}
+
+/** The verdict of {@link WsConnectionTracker.tryAcquire}. */
+export type WsAcquireResult =
+  | { ok: true; release: () => void }
+  | { ok: false; reason: "per_ip_cap" | "total_cap" };
+
+/**
+ * Concurrent-connection accounting: a per-key map + a global counter.
+ *
+ * Acquire and release are synchronous and O(1); `tryAcquire` is called in
+ * the same synchronous block as `server.upgrade()` (no await between check
+ * and commit), so the counters can't race the admission decision.
+ *
+ * The returned `release` closure is latched — calling it twice decrements
+ * once. That makes leaks structurally hard: the caller doesn't need to know
+ * which teardown paths can double-fire; any number of invocations after the
+ * first are no-ops, and a key's bucket entry is deleted at zero so an
+ * attacker cycling keys can't grow the map without also holding sockets.
+ */
+export class WsConnectionTracker {
+  private readonly perKey = new Map<string, number>();
+  private total = 0;
+
+  constructor(
+    private readonly maxPerKey: number = DEFAULT_WS_MAX_PER_IP,
+    private readonly maxTotal: number = DEFAULT_WS_MAX_TOTAL,
+  ) {}
+
+  /**
+   * Admit-or-refuse a would-be connection for `key`. On admission the slot
+   * is counted immediately and the caller MUST either hand the returned
+   * `release` to the socket's close path or invoke it inline when the
+   * upgrade fails to complete.
+   */
+  tryAcquire(key: string): WsAcquireResult {
+    if (this.total >= this.maxTotal) return { ok: false, reason: "total_cap" };
+    const current = this.perKey.get(key) ?? 0;
+    if (current >= this.maxPerKey) return { ok: false, reason: "per_ip_cap" };
+    this.perKey.set(key, current + 1);
+    this.total += 1;
+
+    let released = false;
+    return {
+      ok: true,
+      release: () => {
+        if (released) return;
+        released = true;
+        const n = this.perKey.get(key) ?? 0;
+        if (n <= 1) this.perKey.delete(key);
+        else this.perKey.set(key, n - 1);
+        if (this.total > 0) this.total -= 1;
+      },
+    };
+  }
+
+  /** Current global connection count (observability + tests). */
+  get totalCount(): number {
+    return this.total;
+  }
+
+  /** Current count for one key (observability + tests). 0 when absent. */
+  countFor(key: string): number {
+    return this.perKey.get(key) ?? 0;
+  }
+
+  /** Number of distinct keys currently holding connections (leak probe). */
+  get keyCount(): number {
+    return this.perKey.size;
+  }
+}
+
+/**
+ * The production tracker — one per hub process, shared by every upgrade.
+ * Caps come from the env at module load (the hub reads its config once at
+ * boot; changing the env requires a restart, same as every other
+ * `PARACHUTE_*` knob). Tests construct their own trackers and inject them
+ * via `HubFetchDeps.wsConnectionTracker` so they never consume (or depend
+ * on) the shared process-level counters.
+ */
+const bootCaps = wsCapsFromEnv();
+export const defaultWsConnectionTracker = new WsConnectionTracker(
+  bootCaps.maxPerIp,
+  bootCaps.maxTotal,
+);