pi-weave 0.1.7 → 0.1.9

package/src/web/server/security.ts

@@ -0,0 +1,361 @@
+/**
+ * The four security layers of the loopback workspace server
+ * (weave-workspace §5.1).
+ *
+ * ## Why any of this, on 127.0.0.1
+ *
+ * The retired viewer bound loopback and stopped there —
+ * `git show cef1177:src/pi/viewer/server.ts` has **zero** matches for
+ * `token`, `Origin` or `Host`. Loopback is not an authorisation boundary:
+ *
+ *  - every process running as the user can reach the port, and can find it
+ *    by scanning a few thousand ports faster than a page loads;
+ *  - **any website the user visits** can reach it too, via DNS rebinding —
+ *    `evil.com` resolves to a real address for the page load, then re-answers
+ *    with `127.0.0.1` on a second lookup, and the browser now treats our
+ *    server as same-origin with the attacker's JavaScript.
+ *
+ * So four layers, each defeating something the others do not:
+ *
+ * | # | Layer | Defeats |
+ * | - | ----- | ------- |
+ * | 1 | bind `127.0.0.1`, port `0` | remote reachability; a guessable port |
+ * | 2 | {@link isAllowedHost} | DNS rebinding |
+ * | 3 | {@link timingSafeMatch} over a 256-bit token | local processes, blind CSRF |
+ * | 4 | {@link checkOrigin} | cross-origin writes from a page that got past 2 |
+ *
+ * Layer 2 is the one that carries the rebinding case, and the reason it
+ * works is worth stating: the rebinding attacker controls DNS, not the
+ * browser. The browser sends `Host: evil.com` because that is the name in
+ * the URL bar, and it cannot be talked out of it — `fetch` rejects an
+ * attempt to set `Host` as a forbidden header. An allowlist of
+ * `127.0.0.1:PORT` / `localhost:PORT` / `[::1]:PORT` therefore rejects every
+ * rebound request while costing a legitimate one a string compare.
+ *
+ * Layer 4 is deliberately asymmetric, because `Origin` is asymmetric:
+ * browsers omit it on same-origin GET *navigations*, so requiring it would
+ * break typing the URL into the address bar. Validate-if-present on GET,
+ * require on everything else — which is where state changes live.
+ *
+ * ## Everything here is a pure function of request facts
+ *
+ * {@link RequestFacts} is four strings, not an `IncomingMessage`, so the
+ * table tests in `tests/web/security.test.ts` enumerate the matrix directly
+ * instead of constructing sockets. {@link requestFacts} is the one adapter
+ * from Node's request object, and it is the only part of this module that
+ * knows HTTP exists.
+ */
+
+import { randomBytes, timingSafeEqual } from "node:crypto";
+
+// --- token -------------------------------------------------------------------
+
+/**
+ * Token entropy. 256 bits: not guessable by a local process in the lifetime
+ * of a pi session, and short enough in base64url (43 chars) to survive being
+ * pasted into a terminal.
+ */
+export const TOKEN_BYTES = 32;
+
+/** A fresh per-session token. */
+export function generateToken(): string {
+  return randomBytes(TOKEN_BYTES).toString("base64url");
+}
+
+/**
+ * Constant-time string comparison.
+ *
+ * `timingSafeEqual` **throws** on a length mismatch (`ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH`),
+ * which is the trap this wrapper exists to close: a caller that passes it
+ * two user-controlled strings has written a crash, not a comparison. The
+ * length pre-check is not a timing leak worth caring about — our token's
+ * length is a constant of the program, so an attacker learns nothing they
+ * could not read in this file.
+ *
+ * Byte length, not `String.length`: a multi-byte character would make the
+ * two disagree and re-introduce the throw.
+ */
+export function timingSafeMatch(a: string, b: string): boolean {
+  const left = Buffer.from(a, "utf8");
+  const right = Buffer.from(b, "utf8");
+  if (left.length !== right.length) return false;
+  // Zero-length buffers compare equal in `timingSafeEqual`, which would make
+  // "" a valid token against an "" secret. Callers never hold an empty
+  // token, but a truncated env var is one typo away, so refuse explicitly.
+  if (left.length === 0) return false;
+  return timingSafeEqual(left, right);
+}
+
+// --- host and origin ---------------------------------------------------------
+
+/**
+ * The `Host` values a legitimate request can carry. IPv6 loopback is
+ * included in bracketed form because that is what a browser sends for
+ * `http://[::1]:PORT/`.
+ */
+export function allowedHosts(port: number): ReadonlySet<string> {
+  return new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
+}
+
+/** The `Origin` values matching {@link allowedHosts}. Always `http:`. */
+export function allowedOrigins(port: number): ReadonlySet<string> {
+  return new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`]);
+}
+
+/**
+ * Layer 2. An absent `Host` is a deny: HTTP/1.1 requires it, and the only
+ * clients that omit it are hand-rolled ones probing the port.
+ */
+export function isAllowedHost(host: string | undefined, port: number): boolean {
+  if (host === undefined) return false;
+  return allowedHosts(port).has(host);
+}
+
+/**
+ * Layer 4. Returns `true` when the request may proceed.
+ *
+ *  - present and allowlisted → ok, any method;
+ *  - present and foreign → denied, any method (this is the cross-origin
+ *    write, and also a cross-origin read attempt worth refusing early);
+ *  - absent on `GET`/`HEAD` → ok, because browsers omit it on same-origin
+ *    navigations and we would otherwise reject the address bar;
+ *  - absent on anything else → denied. A state-changing request with no
+ *    provenance is exactly the shape of a form-post CSRF.
+ */
+export function checkOrigin(method: string, origin: string | undefined, port: number): boolean {
+  if (origin !== undefined) return allowedOrigins(port).has(origin);
+  const safe = method === "GET" || method === "HEAD";
+  return safe;
+}
+
+// --- cookies -----------------------------------------------------------------
+
+/**
+ * Default cookie name. The `__Host-` prefix is a browser-enforced
+ * commitment: the cookie must be `Secure`, must have `Path=/`, and must
+ * carry **no** `Domain` — which together mean no sibling origin and no
+ * subdomain can set or overwrite it. That closes cookie-injection, where an
+ * attacker plants their own token so that any request the user makes is
+ * attributed to a session the attacker also holds.
+ *
+ * `Secure` on `http://127.0.0.1` is legal because loopback is a
+ * [secure context](https://w3c.github.io/webappsec-secure-contexts/), and
+ * Chrome/Firefox/Safari all honour it there. §5.1 footnote 1 asks for a
+ * fallback anyway, which is {@link FALLBACK_COOKIE_NAME}: same value, no
+ * prefix, no `Secure`, and therefore none of the guarantees above. It exists
+ * so a browser that disagrees costs a config flag rather than a redesign.
+ */
+export const DEFAULT_COOKIE_NAME = "__Host-weave";
+
+/** Prefix-free fallback for a browser that rejects `Secure` on loopback. */
+export const FALLBACK_COOKIE_NAME = "weave_token";
+
+/** Query parameter carrying the token on the one-shot handoff URL. */
+export const TOKEN_QUERY_PARAM = "t";
+
+/**
+ * Parse a `Cookie` request header into a map.
+ *
+ * Lenient by design — this is header parsing on an attacker-reachable path,
+ * so anything malformed is skipped rather than thrown. A pair with no `=` is
+ * dropped; a value containing `=` keeps it (base64url does not produce one,
+ * but a fallback-named cookie set by something else might).
+ */
+export function parseCookies(header: string | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (header === undefined) return out;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    // `eq === 0` is a nameless pair ("=v"); `eq === -1` has no separator at
+    // all. Both are malformed, and `<= 0` covers them together — which also
+    // means a name can never be the empty string below.
+    if (eq <= 0) continue;
+    out[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+  }
+  return out;
+}
+
+/**
+ * The `Set-Cookie` value for the handoff.
+ *
+ * `HttpOnly` keeps the token out of `document.cookie`, so an XSS in the
+ * client (or in a note's rendered Markdown) cannot exfiltrate it.
+ * `SameSite=Strict` means the browser will not attach it to any
+ * cross-site-initiated request at all, which is a second, independent answer
+ * to the CSRF that {@link checkOrigin} covers.
+ *
+ * No `Max-Age`: a session cookie dies with the browser session, and the
+ * server dies with the pi session, so persisting it would only widen the
+ * window in which a stale token exists.
+ */
+export function buildSetCookie(name: string, token: string): string {
+  const attrs = [`${name}=${token}`, "HttpOnly", "SameSite=Strict", "Path=/"];
+  // `Secure` is mandatory for `__Host-`; the fallback name exists precisely
+  // to be usable without it.
+  if (name.startsWith("__Host-")) attrs.push("Secure");
+  return attrs.join("; ");
+}
+
+// --- the decision ------------------------------------------------------------
+
+/**
+ * Everything the policy needs from a request. Four strings, so the matrix is
+ * table-testable without a socket.
+ */
+export interface RequestFacts {
+  method: string;
+  /** Request target as sent, e.g. `/api/graph?x=1`. Never a full URL. */
+  url: string;
+  host: string | undefined;
+  origin: string | undefined;
+  /** Raw `Cookie` header. */
+  cookie: string | undefined;
+}
+
+/** Minimal structural view of a Node request — avoids importing `http` types. */
+export interface IncomingLike {
+  method?: string | undefined;
+  url?: string | undefined;
+  headers: Record<string, string | string[] | undefined>;
+}
+
+/**
+ * Read {@link RequestFacts} off a Node request.
+ *
+ * Node lower-cases header names and collapses duplicates for these four, but
+ * a duplicated `Host` still arrives as an array on some proxies; taking the
+ * first would let an attacker append an allowlisted value to a foreign one.
+ * An array is therefore treated as absent, which fails closed.
+ */
+export function requestFacts(req: IncomingLike): RequestFacts {
+  return {
+    method: req.method ?? "GET",
+    url: req.url ?? "/",
+    host: single(req.headers["host"]),
+    origin: single(req.headers["origin"]),
+    cookie: single(req.headers["cookie"]),
+  };
+}
+
+function single(value: string | string[] | undefined): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * What the server should do with a request.
+ *
+ *  - `allow`: proceed to routing.
+ *  - `handoff`: the URL carried a valid token; set the cookie and `302` to
+ *    {@link SecurityDecision.location}, dropping the token from the address
+ *    bar (and therefore from `Referer`, from shell history, and from
+ *    anything that later reads the tab's URL).
+ *  - `deny`: respond `403` with `reason`. The reason is for the server log
+ *    and the test table, never for the response body — telling a prober
+ *    which layer stopped them is free reconnaissance.
+ */
+export type SecurityDecision =
+  | { kind: "allow" }
+  | { kind: "handoff"; location: string; setCookie: string }
+  | { kind: "deny"; status: 403; reason: DenyReason };
+
+export type DenyReason = "host" | "origin" | "token";
+
+export interface SecurityOptions {
+  port: number;
+  /** Defaults to a fresh {@link generateToken}. */
+  token?: string;
+  /** Defaults to {@link DEFAULT_COOKIE_NAME}. */
+  cookieName?: string;
+}
+
+export interface SecurityPolicy {
+  readonly token: string;
+  readonly cookieName: string;
+  /** `http://127.0.0.1:PORT` — the canonical origin of this server. */
+  readonly origin: string;
+  /** The one-shot handoff URL to hand to a browser. */
+  readonly entryUrl: string;
+  authorize(facts: RequestFacts): SecurityDecision;
+}
+
+/**
+ * Bind the four layers to a port and a token.
+ *
+ * A factory rather than free functions with a port argument everywhere: the
+ * allowlists are derived from the port, and deriving them once at bind time
+ * makes it impossible to check a request against the wrong port — the class
+ * of bug where a server restarts on a new port and an allowlist captured
+ * earlier keeps accepting the old one.
+ */
+export function createSecurityPolicy(opts: SecurityOptions): SecurityPolicy {
+  const token = opts.token ?? generateToken();
+  const cookieName = opts.cookieName ?? DEFAULT_COOKIE_NAME;
+  const { port } = opts;
+  const origin = `http://127.0.0.1:${port}`;
+  const setCookie = buildSetCookie(cookieName, token);
+
+  return {
+    token,
+    cookieName,
+    origin,
+    entryUrl: `${origin}/?${TOKEN_QUERY_PARAM}=${token}`,
+
+    authorize(facts: RequestFacts): SecurityDecision {
+      // Order matters: cheapest and most decisive first, and never leak
+      // whether a token was *nearly* right to a caller who failed layer 2.
+      if (!isAllowedHost(facts.host, port)) return { kind: "deny", status: 403, reason: "host" };
+      if (!checkOrigin(facts.method, facts.origin, port)) {
+        return { kind: "deny", status: 403, reason: "origin" };
+      }
+
+      const cookies = parseCookies(facts.cookie);
+      const held = cookies[cookieName];
+      if (held !== undefined && timingSafeMatch(held, token)) return { kind: "allow" };
+
+      // No valid cookie. A GET may still be the one-shot handoff.
+      const query = queryToken(facts.url);
+      if (query !== null && facts.method === "GET" && timingSafeMatch(query, token)) {
+        return { kind: "handoff", location: stripTokenParam(facts.url), setCookie };
+      }
+      return { kind: "deny", status: 403, reason: "token" };
+    },
+  };
+}
+
+/**
+ * The `t` parameter of a request target, or `null`.
+ *
+ * Parsed against a fixed dummy base because `req.url` is a path, not an
+ * absolute URL, and `new URL` demands one. The base is never used for
+ * anything but parsing.
+ */
+function queryToken(url: string): string | null {
+  return parseTarget(url).searchParams.get(TOKEN_QUERY_PARAM);
+}
+
+/**
+ * The same target with `t` removed — the `302` location.
+ *
+ * Other parameters survive, so a deep link like `/?t=…&note=alpha` still
+ * lands on the note after the handoff.
+ */
+function stripTokenParam(url: string): string {
+  const parsed = parseTarget(url);
+  parsed.searchParams.delete(TOKEN_QUERY_PARAM);
+  const query = parsed.searchParams.toString();
+  return query.length > 0 ? `${parsed.pathname}?${query}` : parsed.pathname;
+}
+
+/** Dummy origin for parsing an origin-form request target. */
+const PARSE_BASE = "http://weave.invalid";
+
+function parseTarget(url: string): URL {
+  try {
+    return new URL(url, PARSE_BASE);
+  } catch {
+    // `new URL` is remarkably hard to break with an origin-form target, but
+    // the request line is attacker-controlled and a throw here would be a
+    // 500 on an unauthenticated path. Fail closed to a token-less root.
+    return new URL("/", PARSE_BASE);
+  }
+}

package/src/web/server/server.ts

@@ -0,0 +1,275 @@
+/**
+ * The loopback workspace server — bind, lifecycle, teardown
+ * (weave-workspace §5.1, §5.4).
+ *
+ * This module owns three things and delegates everything else:
+ *
+ *  1. **Binding.** `listen(0, "127.0.0.1")` — loopback only, ephemeral port.
+ *     Never a fixed port: a fixed port is a port another process can squat
+ *     before us, and a port a malicious page can guess without scanning.
+ *  2. **Composition.** It builds the {@link RouteDeps} — a
+ *     {@link WorkspaceCache}, a {@link SecurityPolicy}, and whichever hub and
+ *     watcher it was handed — and passes them to `handleRequest`.
+ *  3. **Lifecycle.** Idle shutdown 30 minutes after the last SSE client
+ *     disconnects, and a `close()` that actually releases the port.
+ *
+ * ## Why the hub and the watcher are constructor arguments
+ *
+ * `SseHub` and `Watcher` are declared in `routes.ts` (the consumer) and
+ * arrive here as optional options. That is not ceremony: it means the server
+ * can be booted with neither — which is exactly what the route tests do, so
+ * they exercise the real socket and the real security policy without a file
+ * watcher spinning up on a temp directory, and it means the SSE
+ * implementation can be written, replaced, or omitted with no edit to this
+ * file. With no hub, `/events` answers `503` and the server has no idle
+ * timer to run, because nothing can be idle.
+ *
+ * ## Idle shutdown, precisely
+ *
+ * The timer starts when the SSE client count reaches zero and is cancelled
+ * when a client attaches. A workspace with a tab open is never idle; a
+ * workspace whose last tab closed is reclaimed after
+ * {@link DEFAULT_IDLE_MS}. `setTimer` is injectable, so the test asserts the
+ * transition rather than waiting thirty minutes for it, and
+ * `timer.unref?.()` keeps a pending shutdown from holding the process open.
+ */
+
+import { randomBytes } from "node:crypto";
+import { createServer as createHttpServer, type Server } from "node:http";
+import { fileURLToPath } from "node:url";
+import { WorkspaceCache } from "../../core/cache/workspace";
+import { resolveVaultRoot } from "../../core/paths";
+import { handleRequest, type RouteDeps, type SseHub, type Watcher } from "./routes";
+import { createSecurityPolicy, type SecurityPolicy } from "./security";
+
+export type { SseHub, Watcher } from "./routes";
+
+/** §5.4: reclaim the port 30 minutes after the last SSE client disconnects. */
+export const DEFAULT_IDLE_MS = 30 * 60 * 1000;
+
+/**
+ * The committed bundle, resolved relative to this module rather than to
+ * `process.cwd()` — the server runs in whatever directory the user invoked
+ * pi from, which is never the package root.
+ */
+export function defaultBundlePath(): string {
+  return fileURLToPath(new URL("../client/dist/app.js", import.meta.url));
+}
+
+/** A `setTimeout` shaped seam, so the idle path is testable in microseconds. */
+export interface TimerHandle {
+  unref?(): unknown;
+}
+export type SetTimer = (fn: () => void, ms: number) => TimerHandle;
+export type ClearTimer = (handle: TimerHandle) => void;
+
+export interface StartWorkspaceServerOptions {
+  cwd: string;
+  /** Defaults to `resolveVaultRoot()`, which honours `PI_WEAVE_VAULT`. */
+  vaultRoot?: string;
+  /**
+   * Live-update hub. Absent → `/events` answers `503` and the idle timer
+   * never runs. Supplied by the caller that also constructs the watcher.
+   */
+  sse?: SseHub | undefined;
+  /** File watcher. Started during boot, closed during teardown. */
+  watcher?: Watcher | undefined;
+  /** Pre-built cache. Defaults to a fresh one over `cwd` + `vaultRoot`. */
+  cache?: WorkspaceCache | undefined;
+  /** Fixed token, for tests that need to know it before the boot resolves. */
+  token?: string | undefined;
+  /** Cookie name override — the §5.1 footnote-1 fallback. */
+  cookieName?: string | undefined;
+  /** Absolute path to the client bundle. Defaults to the committed one. */
+  bundlePath?: string | undefined;
+  /** Test seam for `POST /api/open`. */
+  openNote?: ((slug: string) => Promise<boolean>) | undefined;
+  /** Test seam for the note read; see {@link RouteDeps.readNote}. */
+  readNote?: RouteDeps["readNote"];
+  /**
+   * Self-write suppression (§6): tell the watcher to ignore a path it is
+   * about to see us change.
+   *
+   * A separate option rather than a method on {@link Watcher}, because
+   * `Watcher` here is the two-method lifecycle contract `routes.ts` declares
+   * — start and close — and widening it would force every future watcher
+   * (a poller, a remote FS) to implement suppression whether or not the
+   * concept applies to it. The caller that constructs the real watcher knows
+   * it has a `suppress`, and passes it.
+   *
+   * Defaults to {@link Watcher.suppress} when the injected watcher has one,
+   * so the common wiring is automatic and the option exists for a caller
+   * whose suppression lives somewhere else (or for a test that wants to
+   * observe it). Absent on both means writes happen unsuppressed, which is
+   * exactly right for a server booted with no watcher: there is nothing
+   * listening to feed a loop.
+   */
+  suppress?: ((absPath: string) => void) | undefined;
+  /** Idle shutdown delay. `0` disables it entirely. */
+  idleMs?: number | undefined;
+  setTimer?: SetTimer | undefined;
+  clearTimer?: ClearTimer | undefined;
+  /** Invoked when the idle timeout fires, after `close()`. */
+  onIdleShutdown?: (() => void) | undefined;
+}
+
+export interface WorkspaceServer {
+  /** Canonical base URL, e.g. `http://127.0.0.1:53217`. */
+  url: string;
+  /** The one-shot handoff URL: `url` plus `?t=TOKEN`. Give this to a browser. */
+  entryUrl: string;
+  port: number;
+  token: string;
+  security: SecurityPolicy;
+  cache: WorkspaceCache;
+  /** Random per-boot id, also embedded in the page bootstrap. */
+  session: string;
+  /**
+   * Called by the SSE hub whenever a client attaches or detaches, so the
+   * idle timer can be armed or cancelled. Exposed rather than inferred
+   * because only the hub knows when a socket actually died.
+   */
+  noteActivity(): void;
+  /** Release the port, the watcher and every stream. Idempotent. */
+  close(): Promise<void>;
+}
+
+export async function startWorkspaceServer(opts: StartWorkspaceServerOptions): Promise<WorkspaceServer> {
+  const vaultRoot = opts.vaultRoot ?? resolveVaultRoot();
+  const cache = opts.cache ?? new WorkspaceCache({ cwd: opts.cwd, vaultRoot });
+  const session = randomBytes(8).toString("hex");
+  const setTimer: SetTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer: ClearTimer = opts.clearTimer ?? ((h) => clearTimeout(h as NodeJS.Timeout));
+  const idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
+
+  // `deps` is assembled before `listen` because the request handler closes
+  // over it, but the security policy needs the bound port — so the policy
+  // slot is filled after binding and the handler reads it through the
+  // mutable holder rather than capturing a stale value.
+  // Explicit `suppress` first, else the watcher's own if it has one (§6).
+  // Bound as a closure rather than passed as a method reference, so a
+  // watcher implementing `suppress` as a class method keeps its `this`.
+  const watcherSuppress = opts.watcher?.suppress;
+  const suppress: ((absPath: string) => void) | null =
+    opts.suppress ?? (watcherSuppress === undefined ? null : (absPath: string) => watcherSuppress.call(opts.watcher, absPath));
+
+  let deps: RouteDeps | null = null;
+  const server: Server = createHttpServer((req, res) => {
+    // Unreachable in practice — `listen` resolves before any connection is
+    // accepted — but a request arriving with no deps would be a `500` with
+    // an incomprehensible stack, so answer honestly instead.
+    /* c8 ignore next 5 */
+    if (deps === null) {
+      res.writeHead(503, { "content-type": "text/plain; charset=utf-8" });
+      res.end("pi-weave: starting\n");
+      return;
+    }
+    void handleRequest(deps, req, res);
+  });
+
+  await listen(server);
+  const port = boundPort(server);
+  const security = createSecurityPolicy({
+    port,
+    ...(opts.token !== undefined ? { token: opts.token } : {}),
+    ...(opts.cookieName !== undefined ? { cookieName: opts.cookieName } : {}),
+  });
+
+  let closed = false;
+  let idleHandle: TimerHandle | null = null;
+
+  const cancelIdle = (): void => {
+    if (idleHandle !== null) {
+      clearTimer(idleHandle);
+      idleHandle = null;
+    }
+  };
+
+  const armIdle = (): void => {
+    // No hub means `/events` answers 503, so there is no such thing as a
+    // client here and nothing for a countdown to count. The server stays up
+    // until its owner closes it.
+    if (idleMs <= 0 || closed || opts.sse === undefined) return;
+    const handle = setTimer(() => {
+      idleHandle = null;
+      void close().then(() => opts.onIdleShutdown?.());
+    }, idleMs);
+    // A pending shutdown must not be the reason the process stays alive.
+    handle.unref?.();
+    idleHandle = handle;
+  };
+
+  const noteActivity = (): void => {
+    cancelIdle();
+    // Zero clients right now means the countdown starts now. A hub that
+    // reports a live client cancels it and says nothing more until that
+    // client leaves. With no hub at all, `armIdle` is already a no-op — the
+    // guard lives there rather than being repeated here.
+    if (opts.sse === undefined || opts.sse.clientCount() === 0) armIdle();
+  };
+
+  const close = async (): Promise<void> => {
+    if (closed) return;
+    closed = true;
+    cancelIdle();
+    opts.sse?.close();
+    await opts.watcher?.close();
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+      // Without this, an open SSE stream keeps the server's handle alive and
+      // `close()` never resolves — the exact reason a pi session used to
+      // hang on shutdown.
+      server.closeAllConnections();
+    });
+  };
+
+  deps = {
+    cwd: opts.cwd,
+    vaultRoot,
+    session,
+    cache,
+    security,
+    bundlePath: opts.bundlePath ?? defaultBundlePath(),
+    ...(opts.sse !== undefined ? { sse: opts.sse } : {}),
+    ...(opts.openNote !== undefined ? { openNote: opts.openNote } : {}),
+    ...(opts.readNote !== undefined ? { readNote: opts.readNote } : {}),
+    ...(suppress === null ? {} : { suppress }),
+    onActivity: noteActivity,
+  };
+
+  await opts.watcher?.start();
+
+  // A workspace nobody has connected to yet is already idle: if the browser
+  // never opens, the port should still be reclaimed.
+  if (opts.sse !== undefined) armIdle();
+
+  return {
+    url: security.origin,
+    entryUrl: security.entryUrl,
+    port,
+    token: security.token,
+    security,
+    cache,
+    session,
+    noteActivity,
+    close,
+  };
+}
+
+/** Bind to an ephemeral loopback port, rejecting on a bind error. */
+function listen(server: Server): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+}
+
+function boundPort(server: Server): number {
+  const address = server.address();
+  /* c8 ignore next -- `address()` is only a string for a unix socket, which we never bind. */
+  if (typeof address !== "object" || address === null) throw new Error("pi-weave: server did not bind a TCP port");
+  return address.port;
+}