@bugmole/cli 0.4.0

package/src/storage/local-artifact-server.test.ts

@@ -0,0 +1,314 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import WebSocket from "ws";
+import { startLocalArtifactServer } from "./local-artifact-server.js";
+import { LocalObjectStore } from "./object-store.js";
+
+test("local artifact bridge serves only authorized project objects", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-artifacts-"));
+  const store = new LocalObjectStore(directory);
+  await store.put("projects/demo/runs/run-1/results.json", '{"ok":true}', "application/json");
+  await store.put("projects/other/runs/run-2/results.json", '{"secret":true}', "application/json");
+  const bridge = await startLocalArtifactServer({
+    directory,
+    projectId: "demo",
+    port: 0,
+    dashboardOrigin: "https://app.bugmole.com",
+  });
+
+  try {
+    const artifactUrl = `${bridge.origin}/artifact?key=${encodeURIComponent("projects/demo/runs/run-1/results.json")}`;
+    const response = await fetch(artifactUrl, {
+      headers: {
+        Authorization: `Bearer ${bridge.token}`,
+        Origin: "https://app.bugmole.com",
+      },
+    });
+    assert.equal(response.status, 200);
+    assert.equal(response.headers.get("content-type"), "application/json");
+    assert.equal(await response.text(), '{"ok":true}');
+
+    const otherProject = await fetch(
+      `${bridge.origin}/artifact?key=${encodeURIComponent("projects/other/runs/run-2/results.json")}`,
+      { headers: { Authorization: `Bearer ${bridge.token}` } },
+    );
+    assert.equal(otherProject.status, 403);
+
+    const traversal = await fetch(
+      `${bridge.origin}/artifact?key=${encodeURIComponent("projects/demo/../other/runs/run-2/results.json")}`,
+      { headers: { Authorization: `Bearer ${bridge.token}` } },
+    );
+    assert.equal(traversal.status, 400);
+  } finally {
+    await bridge.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("local artifact bridge rejects missing credentials and origins", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-artifacts-"));
+  const bridge = await startLocalArtifactServer({
+    directory,
+    projectId: "demo",
+    port: 0,
+    dashboardOrigin: "https://app.bugmole.com",
+  });
+  try {
+    const missingToken = await fetch(`${bridge.origin}/artifacts`);
+    assert.equal(missingToken.status, 401);
+    const wrongOrigin = await fetch(`${bridge.origin}/health`, {
+      headers: { Origin: "https://evil.example" },
+    });
+    assert.equal(wrongOrigin.status, 403);
+  } finally {
+    await bridge.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("local artifact bridges auto-separate projects when the default port is occupied", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-artifacts-"));
+  const first = await startLocalArtifactServer({ directory, projectId: "first" });
+  const second = await startLocalArtifactServer({ directory, projectId: "second" });
+  try {
+    assert.notEqual(first.origin, second.origin);
+    const firstHealth = await fetch(`${first.origin}/health`);
+    const secondHealth = await fetch(`${second.origin}/health`);
+    assert.equal((await firstHealth.json() as { projectId: string }).projectId, "first");
+    assert.equal((await secondHealth.json() as { projectId: string }).projectId, "second");
+  } finally {
+    await second.close();
+    await first.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("local artifact capability expires", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-artifacts-"));
+  const bridge = await startLocalArtifactServer({
+    directory,
+    projectId: "demo",
+    port: 0,
+    tokenTtlMs: 1,
+  });
+  try {
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    const response = await fetch(`${bridge.origin}/artifacts`, {
+      headers: { Authorization: `Bearer ${bridge.token}` },
+    });
+    assert.equal(response.status, 401);
+  } finally {
+    await bridge.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("local presence renews an expired capability for the live bridge", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-artifacts-"));
+  const bridge = await startLocalArtifactServer({
+    directory,
+    projectId: "demo",
+    port: 0,
+    tokenTtlMs: 100,
+  });
+  try {
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    const presenceResponse = await fetch(`${bridge.origin}/presence`);
+    assert.equal(presenceResponse.status, 200);
+    const presence = await presenceResponse.json() as { artifactToken?: string };
+    assert.ok(presence.artifactToken);
+    assert.notEqual(presence.artifactToken, bridge.token);
+    const response = await fetch(`${bridge.origin}/artifacts`, {
+      headers: { Authorization: `Bearer ${presence.artifactToken}` },
+    });
+    assert.equal(response.status, 200);
+  } finally {
+    await bridge.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("local presence is idempotent while the capability is valid", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-artifacts-"));
+  const bridge = await startLocalArtifactServer({
+    directory,
+    projectId: "demo",
+    aegisEmail: "owner@example.com",
+    port: 0,
+  });
+  try {
+    const first = await fetch(`${bridge.origin}/presence`, {
+      headers: { Origin: "https://app.bugmole.com" },
+    });
+    assert.equal(first.status, 200);
+    const presence = await first.json() as {
+      sessionId?: string;
+      deviceId?: string;
+      email?: string;
+      artifactToken?: string;
+    };
+    assert.ok(presence.sessionId);
+    assert.equal(presence.deviceId, "demo");
+    assert.equal(presence.email, "owner@example.com");
+    assert.equal(presence.artifactToken, bridge.token);
+
+    const second = await fetch(`${bridge.origin}/presence`);
+    assert.equal(second.status, 200);
+    const repeated = await second.json() as { sessionId?: string; artifactToken?: string };
+    assert.equal(repeated.sessionId, presence.sessionId);
+    assert.equal(repeated.artifactToken, presence.artifactToken);
+  } finally {
+    await bridge.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("local artifact bridge writes only project-scoped flow objects", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-artifacts-"));
+  const bridge = await startLocalArtifactServer({ directory, projectId: "demo", port: 0 });
+  try {
+    const allowed = await fetch(`${bridge.origin}/artifact?key=projects%2Fdemo%2Fjourneys%2Fgraph.json`, {
+      method: "PUT",
+      headers: { Authorization: `Bearer ${bridge.token}`, "content-type": "application/json" },
+      body: '{"version":2}',
+    });
+    assert.equal(allowed.status, 200);
+    const denied = await fetch(`${bridge.origin}/artifact?key=projects%2Fother%2Fjourneys%2Fgraph.json`, {
+      method: "PUT",
+      headers: { Authorization: `Bearer ${bridge.token}` },
+      body: "{}",
+    });
+    assert.equal(denied.status, 403);
+  } finally {
+    await bridge.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("local artifact bridge emits project-scoped progress and audit changes over WebSocket", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-artifacts-"));
+  const store = new LocalObjectStore(directory);
+  const bridge = await startLocalArtifactServer({
+    directory,
+    projectId: "demo",
+    port: 0,
+    dashboardOrigin: "https://app.bugmole.com",
+  });
+  const socket = new WebSocket(
+    `${bridge.origin.replace(/^http/, "ws")}/artifact-events?project=demo&token=${encodeURIComponent(bridge.token)}`,
+    { headers: { Origin: "https://app.bugmole.com" } },
+  );
+  try {
+    await new Promise<void>((resolve, reject) => {
+      socket.once("open", () => resolve());
+      socket.once("error", reject);
+    });
+    const messages = new Promise<Array<Record<string, string>>>((resolve, reject) => {
+      const received: Array<Record<string, string>> = [];
+      const timer = setTimeout(() => reject(new Error("Timed out waiting for artifact changes")), 1000);
+      socket.on("message", (data) => {
+        received.push(JSON.parse(data.toString()) as Record<string, string>);
+        if (received.length === 5) {
+          clearTimeout(timer);
+          resolve(received);
+        }
+      });
+    });
+    await store.put("projects/demo/ui-audits/audit-1.json", '{"auditId":"audit-1"}', "application/json");
+    await store.put(
+      "projects/demo/ui-parity-audits/parity-1.json",
+      '{"auditId":"parity-1","issues":[]}',
+      "application/json",
+    );
+    await store.put("projects/demo/progress/progress-1.json", '{"status":"working"}', "application/json");
+    // A live exploration run writes journeys/graph.json incrementally; the
+    // dashboard's step graph relies on seeing each write, not just the
+    // final one, so it can grow node-by-node instead of appearing all at
+    // once.
+    await store.put("projects/demo/journeys/graph.json", '{"version":2,"journeys":[]}', "application/json");
+    // A resolved exploration blocker; the Blockers panel's "gates N steps"
+    // count relies on seeing this the same way it sees UI/parity audits.
+    await store.put(
+      "projects/demo/blocker-resolutions/abc123.json",
+      '{"fingerprint":"abc123","category":"supabase_schema_missing","reason":"setup","nodeId":"home"}',
+      "application/json",
+    );
+    const received = await messages;
+    assert.deepEqual(
+      received.map((message) => message.type).sort(),
+      ["audit-change", "audit-change", "audit-change", "journey-change", "progress-change"],
+    );
+    for (const message of received) {
+      assert.equal(message.projectId, "demo");
+    }
+    await new Promise<void>((resolve) => {
+      socket.once("close", () => resolve());
+      socket.close();
+    });
+    const reconnected = new WebSocket(
+      `${bridge.origin.replace(/^http/, "ws")}/artifact-events?project=demo&token=${encodeURIComponent(bridge.token)}`,
+      { headers: { Origin: "https://app.bugmole.com" } },
+    );
+    await new Promise<void>((resolve, reject) => {
+      reconnected.once("open", () => resolve());
+      reconnected.once("error", reject);
+    });
+    const reconnectMessage = new Promise<Record<string, string>>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("Timed out waiting after reconnect")), 1000);
+      reconnected.once("message", (data) => {
+        clearTimeout(timer);
+        resolve(JSON.parse(data.toString()) as Record<string, string>);
+      });
+    });
+    await store.put("projects/demo/progress/progress-2.json", '{"status":"completed"}', "application/json");
+    assert.equal((await reconnectMessage).type, "progress-change");
+    reconnected.terminate();
+  } finally {
+    socket.terminate();
+    await bridge.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("serve bridge announces running and clean shutdown lifecycle", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-artifacts-"));
+  const bridge = await startLocalArtifactServer({
+    directory,
+    projectId: "demo",
+    port: 0,
+    service: "serve",
+  });
+  const socket = new WebSocket(
+    `${bridge.origin.replace(/^http/, "ws")}/artifact-events?project=demo&token=${encodeURIComponent(bridge.token)}`,
+  );
+  try {
+    const lifecycle = new Promise<Record<string, string>>((resolve, reject) => {
+      socket.once("error", reject);
+      socket.once("message", (data) => resolve(JSON.parse(data.toString()) as Record<string, string>));
+    });
+    await new Promise<void>((resolve, reject) => {
+      socket.once("open", () => resolve());
+      socket.once("error", reject);
+    });
+    assert.deepEqual(await lifecycle, { type: "serve-lifecycle", projectId: "demo", state: "running" });
+
+    const stopping = new Promise<Record<string, string>>((resolve, reject) => {
+      socket.once("error", reject);
+      socket.once("message", (data) => resolve(JSON.parse(data.toString()) as Record<string, string>));
+    });
+    const closePromise = bridge.close("shutdown");
+    assert.deepEqual(await stopping, {
+      type: "serve-lifecycle",
+      projectId: "demo",
+      state: "stopping",
+      reason: "shutdown",
+    });
+    await closePromise;
+  } finally {
+    socket.terminate();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});

package/src/storage/local-artifact-server.ts

@@ -0,0 +1,357 @@
+import http from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { watch } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { WebSocketServer, type WebSocket } from "ws";
+import { createObjectStore, type ObjectStoreConfig } from "./create-object-store.js";
+import { normalizeKey, type ObjectStore } from "./object-store.js";
+
+export type LocalArtifactServerOptions = {
+  directory: string;
+  projectId: string;
+  aegisEmail?: string;
+  port?: number;
+  dashboardOrigin?: string;
+  tokenTtlMs?: number;
+  service?: "serve" | "artifacts";
+};
+
+export type LocalArtifactServer = {
+  origin: string;
+  token: string;
+  expiresAt: string;
+  close(reason?: "shutdown"): Promise<void>;
+};
+
+function tokenMatches(request: http.IncomingMessage, expected: string, expiresAt: number): boolean {
+  if (Date.now() >= expiresAt) return false;
+  const value = request.headers.authorization?.replace(/^Bearer\s+/i, "");
+  return tokenValueMatches(value, expected);
+}
+
+function tokenValueMatches(
+  value: string | null | undefined,
+  expected: string,
+  expiresAt?: number,
+): boolean {
+  if (expiresAt !== undefined && Date.now() >= expiresAt) return false;
+  if (!value) return false;
+  const actual = Buffer.from(value);
+  const wanted = Buffer.from(expected);
+  return actual.length === wanted.length && timingSafeEqual(actual, wanted);
+}
+
+function writeJson(response: http.ServerResponse, status: number, body: unknown): void {
+  response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify(body));
+}
+
+function contentType(key: string): string {
+  if (key.endsWith(".json")) return "application/json";
+  if (key.endsWith(".html")) return "text/html; charset=utf-8";
+  if (key.endsWith(".md")) return "text/markdown; charset=utf-8";
+  if (key.endsWith(".txt") || key.endsWith(".log")) return "text/plain; charset=utf-8";
+  if (key.endsWith(".png")) return "image/png";
+  if (key.endsWith(".jpg") || key.endsWith(".jpeg")) return "image/jpeg";
+  if (key.endsWith(".webp")) return "image/webp";
+  if (key.endsWith(".trace") || key.endsWith(".zip")) return "application/octet-stream";
+  return "application/octet-stream";
+}
+
+export async function startLocalArtifactServer(
+  options: LocalArtifactServerOptions,
+): Promise<LocalArtifactServer> {
+  const store = createObjectStore({
+    provider: "local",
+    localDirectory: options.directory,
+  } satisfies ObjectStoreConfig);
+  let token = randomBytes(32).toString("base64url");
+  let presenceSessionId = randomBytes(24).toString("base64url");
+  let tokenExpiresAt = Date.now() + (options.tokenTtlMs ?? 30 * 60 * 1000);
+  const allowedOrigin = options.dashboardOrigin ?? "https://app.bugmole.com";
+  const projectPrefix = `projects/${encodeURIComponent(options.projectId)}/`;
+  const auditPrefix = `${projectPrefix}ui-audits/`;
+  const parityAuditPrefix = `${projectPrefix}ui-parity-audits/`;
+  const blockerResolutionsPrefix = `${projectPrefix}blocker-resolutions/`;
+  const progressPrefix = `${projectPrefix}progress/`;
+  const journeysPrefix = `${projectPrefix}journeys/`;
+  const projectDirectory = path.join(options.directory, projectPrefix);
+  const clients = new Set<WebSocket>();
+  const webSocketServer = new WebSocketServer({ noServer: true });
+  const lastEmittedSignatures = new Map<string, string>();
+  const pendingNotifications = new Map<string, NodeJS.Timeout>();
+  const service = options.service ?? "artifacts";
+  await fs.mkdir(projectDirectory, { recursive: true });
+  const artifactWatcher = watch(projectDirectory, { recursive: true }, (_eventType, filename) => {
+    if (!filename) return;
+    const relativeName = filename.toString().replaceAll("\\", "/");
+    const key = normalizeKey(`${projectPrefix}${relativeName}`);
+    const type = key.startsWith(auditPrefix) || key.startsWith(parityAuditPrefix) || key.startsWith(blockerResolutionsPrefix)
+      ? "audit-change"
+      : key.startsWith(journeysPrefix)
+        // A live exploration run writes journeys/graph.json incrementally
+        // (one node/edge at a time); broadcasting each write is what lets
+        // the dashboard's step graph grow node-by-node instead of only
+        // appearing once exploration finishes.
+        ? "journey-change"
+      : key.startsWith(progressPrefix)
+        ? "progress-change"
+        : null;
+    if (!type || !key.endsWith(".json")) return;
+    const previousTimer = pendingNotifications.get(key);
+    if (previousTimer) clearTimeout(previousTimer);
+    pendingNotifications.set(
+      key,
+      setTimeout(() => {
+        pendingNotifications.delete(key);
+        const filePath = path.join(options.directory, key);
+        void fs.stat(filePath, { bigint: true }).then(
+          (stat) => {
+            const signature = `${stat.size}:${stat.mtimeNs}`;
+            if (lastEmittedSignatures.get(key) === signature) return;
+            lastEmittedSignatures.set(key, signature);
+            for (const client of clients) {
+              if (client.readyState === client.OPEN) {
+                client.send(JSON.stringify({ type, projectId: options.projectId, key }));
+              }
+            }
+          },
+          () => {
+            if (lastEmittedSignatures.get(key) === "missing") return;
+            lastEmittedSignatures.set(key, "missing");
+            for (const client of clients) {
+              if (client.readyState === client.OPEN) {
+                client.send(JSON.stringify({ type, projectId: options.projectId, key }));
+              }
+            }
+          }
+        );
+      }, 25),
+    );
+  });
+  let expirationTimer: NodeJS.Timeout;
+  const scheduleExpiration = () => {
+    clearTimeout(expirationTimer);
+    expirationTimer = setTimeout(() => {
+      for (const client of clients) client.terminate();
+    }, Math.max(0, tokenExpiresAt - Date.now()));
+  };
+  scheduleExpiration();
+  const server = http.createServer(async (request, response) => {
+    const origin = request.headers.origin;
+    if (origin && origin !== allowedOrigin) {
+      writeJson(response, 403, { error: "Origin is not allowed" });
+      return;
+    }
+    if (origin) {
+      // Echo the configured origin, not the request's. The guard above
+      // already rejects anything that isn't exactly allowedOrigin, so the
+      // two are equal here — but reflecting a request header into a CORS
+      // response is the shape of a real vulnerability, and writing the
+      // literal keeps it obvious to a reader (and a scanner) that no
+      // caller-controlled value reaches this header.
+      response.setHeader("Access-Control-Allow-Origin", allowedOrigin);
+      response.setHeader("Vary", "Origin");
+      response.setHeader("Access-Control-Allow-Methods", "GET, PUT, OPTIONS");
+      response.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
+      response.setHeader("Access-Control-Allow-Private-Network", "true");
+    }
+    if (request.method === "OPTIONS") {
+      response.writeHead(204);
+      response.end();
+      return;
+    }
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+    if (request.method !== "GET" && request.method !== "PUT") {
+      writeJson(response, 405, { error: "Method not allowed" });
+      return;
+    }
+    if (url.pathname === "/health") {
+      writeJson(response, 200, { ok: true, provider: "local", projectId: options.projectId, service });
+      return;
+    }
+    if (url.pathname === "/presence") {
+      // Presence is both discovery and renewal. Keep it idempotent while the
+      // current capability is valid so login-page polling cannot invalidate a
+      // token already handed to the dashboard.
+      if (Date.now() >= tokenExpiresAt) {
+        token = randomBytes(32).toString("base64url");
+        presenceSessionId = randomBytes(24).toString("base64url");
+        tokenExpiresAt = Date.now() + (options.tokenTtlMs ?? 30 * 60 * 1000);
+        scheduleExpiration();
+      }
+      writeJson(response, 200, {
+        sessionId: presenceSessionId,
+        projectId: options.projectId,
+        deviceId: options.projectId,
+        email: options.aegisEmail,
+        artifactOrigin: `http://127.0.0.1:${(server.address() as { port: number }).port}`,
+        artifactToken: token,
+        expiresAt: new Date(tokenExpiresAt).toISOString(),
+      });
+      return;
+    }
+    if (!tokenMatches(request, token, tokenExpiresAt)) {
+      writeJson(response, 401, { error: "Artifact bridge authorization required" });
+      return;
+    }
+    if (url.pathname === "/artifacts" && request.method === "GET") {
+      const prefix = url.searchParams.get("prefix") ?? projectPrefix;
+      if (!prefix.startsWith(projectPrefix)) {
+        writeJson(response, 403, { error: "Project scope is not allowed" });
+        return;
+      }
+      const objects = await store.list(normalizeKey(prefix));
+      writeJson(response, 200, { objects });
+      return;
+    }
+    if (url.pathname === "/artifact" && request.method === "PUT") {
+      const rawKey = url.searchParams.get("key");
+      if (!rawKey) {
+        writeJson(response, 422, { error: "key is required" });
+        return;
+      }
+      let key: string;
+      try {
+        key = normalizeKey(rawKey);
+      } catch {
+        writeJson(response, 400, { error: "Invalid storage key" });
+        return;
+      }
+      if (!key.startsWith(projectPrefix)) {
+        writeJson(response, 403, { error: "Project scope is not allowed" });
+        return;
+      }
+      const chunks: Buffer[] = [];
+      for await (const chunk of request) chunks.push(Buffer.from(chunk));
+      const payload = Buffer.concat(chunks);
+      const maxBytes = Number(process.env.BUGMOLE_MAX_ARTIFACT_BYTES || 100_000_000);
+      if (payload.length > maxBytes) {
+        writeJson(response, 413, { error: "Artifact is too large" });
+        return;
+      }
+      await store.put(key, payload, request.headers["content-type"] ?? "application/octet-stream");
+      writeJson(response, 200, { saved: true, key });
+      return;
+    }
+    if (url.pathname === "/artifact" && request.method === "GET") {
+      const rawKey = url.searchParams.get("key");
+      if (!rawKey) {
+        writeJson(response, 422, { error: "key is required" });
+        return;
+      }
+      let key: string;
+      try {
+        key = normalizeKey(rawKey);
+      } catch {
+        writeJson(response, 400, { error: "Invalid storage key" });
+        return;
+      }
+      if (!key.startsWith(projectPrefix)) {
+        writeJson(response, 403, { error: "Project scope is not allowed" });
+        return;
+      }
+      try {
+        const body = await store.get(key);
+        response.writeHead(200, {
+          "Cache-Control": "no-store",
+          "Content-Type": contentType(key),
+          "X-Content-Type-Options": "nosniff",
+        });
+        response.end(Buffer.from(body));
+      } catch {
+        writeJson(response, 404, { error: "Artifact not found" });
+      }
+      return;
+    }
+    writeJson(response, 404, { error: "Not found" });
+  });
+  server.on("upgrade", (request, socket, head) => {
+    const origin = request.headers.origin;
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+    const tokenValue = url.searchParams.get("token");
+    const projectId = url.searchParams.get("project");
+    if (
+      origin &&
+      origin !== allowedOrigin ||
+      url.pathname !== "/artifact-events" ||
+      projectId !== options.projectId ||
+      Date.now() >= tokenExpiresAt ||
+      !tokenValueMatches(tokenValue, token)
+    ) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    webSocketServer.handleUpgrade(request, socket, head, (client) => {
+      webSocketServer.emit("connection", client, request);
+    });
+  });
+  webSocketServer.on("connection", (client) => {
+    clients.add(client);
+    if (service === "serve" && client.readyState === client.OPEN) {
+      client.send(JSON.stringify({ type: "serve-lifecycle", projectId: options.projectId, state: "running" }));
+    }
+    client.on("close", () => clients.delete(client));
+    client.on("error", () => clients.delete(client));
+  });
+
+  const requestedPort = options.port;
+  const listen = (port: number): Promise<void> =>
+    new Promise<void>((resolve, reject) => {
+      const errorHandler = (error: NodeJS.ErrnoException) => {
+        server.removeListener("error", errorHandler);
+        reject(error);
+      };
+      server.once("error", errorHandler);
+      server.listen(port, "127.0.0.1", () => {
+        server.removeListener("error", errorHandler);
+        resolve();
+      });
+    });
+  try {
+    // Keep the historical 3190 default for the first bridge, but let a
+    // second project use an ephemeral loopback port instead of failing or
+    // accidentally sharing another project's capability.
+    await listen(requestedPort ?? 3190);
+  } catch (error) {
+    if (requestedPort !== undefined || (error as NodeJS.ErrnoException).code !== "EADDRINUSE") {
+      throw error;
+    }
+    await listen(0);
+  }
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Local artifact bridge did not bind");
+  return {
+    origin: `http://127.0.0.1:${address.port}`,
+    token,
+    expiresAt: new Date(tokenExpiresAt).toISOString(),
+    close: async (reason) => {
+      clearTimeout(expirationTimer);
+      artifactWatcher.close();
+      for (const timer of pendingNotifications.values()) clearTimeout(timer);
+      pendingNotifications.clear();
+      if (service === "serve" && reason === "shutdown") {
+        for (const client of clients) {
+          if (client.readyState === client.OPEN) {
+            client.send(JSON.stringify({
+              type: "serve-lifecycle",
+              projectId: options.projectId,
+              state: "stopping",
+              reason: "shutdown",
+            }));
+          }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }
+      for (const client of clients) client.terminate();
+      await new Promise<void>((resolve, reject) => {
+        webSocketServer.close((error) => (error ? reject(error) : resolve()));
+      });
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+      });
+    },
+  };
+}