harnery 0.31.6 → 0.32.0

package/src/lib/browser/session-control.ts

@@ -0,0 +1,892 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { once } from "node:events";
+import {
+  chmodSync,
+  existsSync,
+  linkSync,
+  lstatSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { createConnection, createServer, type Server, type Socket } from "node:net";
+import { dirname, resolve } from "node:path";
+import type {
+  BrowserSessionInspection,
+  BrowserSessionLocator,
+  BrowserSessionScreenshot,
+  BrowserSessionStatus,
+  BrowserSessionTab,
+} from "./client.ts";
+
+export const BROWSER_SESSION_PROTOCOL_VERSION = 1 as const;
+export const BROWSER_SESSION_MAX_FRAME_BYTES = 1024 * 1024;
+export const BROWSER_SESSION_MAX_FILL_BYTES = 64 * 1024;
+export const BROWSER_SESSION_MAX_INSPECTION_TEXT_BYTES = 256 * 1024;
+
+const DEFAULT_ACTION_TIMEOUT_MS = 30_000;
+const SHORT_ACTION_TIMEOUT_MS = 5_000;
+const UNIX_SOCKET_MAX_BYTES = 100;
+const ARIA_ROLES = new Set([
+  "alert",
+  "alertdialog",
+  "application",
+  "article",
+  "banner",
+  "blockquote",
+  "button",
+  "caption",
+  "cell",
+  "checkbox",
+  "code",
+  "columnheader",
+  "combobox",
+  "complementary",
+  "contentinfo",
+  "definition",
+  "deletion",
+  "dialog",
+  "directory",
+  "document",
+  "emphasis",
+  "feed",
+  "figure",
+  "form",
+  "generic",
+  "grid",
+  "gridcell",
+  "group",
+  "heading",
+  "img",
+  "insertion",
+  "link",
+  "list",
+  "listbox",
+  "listitem",
+  "log",
+  "main",
+  "marquee",
+  "math",
+  "meter",
+  "menu",
+  "menubar",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "navigation",
+  "none",
+  "note",
+  "option",
+  "paragraph",
+  "presentation",
+  "progressbar",
+  "radio",
+  "radiogroup",
+  "region",
+  "row",
+  "rowgroup",
+  "rowheader",
+  "scrollbar",
+  "search",
+  "searchbox",
+  "separator",
+  "slider",
+  "spinbutton",
+  "status",
+  "strong",
+  "subscript",
+  "superscript",
+  "switch",
+  "tab",
+  "table",
+  "tablist",
+  "tabpanel",
+  "term",
+  "textbox",
+  "time",
+  "timer",
+  "toolbar",
+  "tooltip",
+  "tree",
+  "treegrid",
+  "treeitem",
+]);
+
+export interface BrowserSessionDescriptor {
+  version: typeof BROWSER_SESSION_PROTOCOL_VERSION;
+  pid: number;
+  created_at: string;
+  transport: { kind: "unix"; address: string } | { kind: "pipe"; address: string };
+  token: string;
+}
+
+export type BrowserSessionRequest =
+  | BaseRequest<"status", Record<string, never>>
+  | BaseRequest<"inspect", { locator?: BrowserSessionLocator }>
+  | BaseRequest<"screenshot", { out: string }>
+  | BaseRequest<"tabs", Record<string, never>>
+  | BaseRequest<"select_tab", { index: number }>
+  | BaseRequest<"open_tab", { url: string }>
+  | BaseRequest<"close_tab", { index: number }>
+  | BaseRequest<"goto", { url: string }>
+  | BaseRequest<"reload", Record<string, never>>
+  | BaseRequest<"click", { locator: BrowserSessionLocator }>
+  | BaseRequest<"fill", { locator: BrowserSessionLocator; value: string }>
+  | BaseRequest<"press", { key: string }>
+  | BaseRequest<"wait", { locator: BrowserSessionLocator }>
+  | BaseRequest<"close", Record<string, never>>;
+
+interface BaseRequest<Action extends string, Args> {
+  version: typeof BROWSER_SESSION_PROTOCOL_VERSION;
+  id: string;
+  token: string;
+  action: Action;
+  args: Args;
+}
+
+export type BrowserSessionResult =
+  | BrowserSessionStatus
+  | BrowserSessionInspection
+  | BrowserSessionScreenshot
+  | BrowserSessionTab[]
+  | BrowserSessionTab
+  | { closing: true }
+  | { revision: number };
+
+export type BrowserSessionResponse =
+  | {
+      version: typeof BROWSER_SESSION_PROTOCOL_VERSION;
+      id: string;
+      ok: true;
+      result: BrowserSessionResult;
+    }
+  | {
+      version: typeof BROWSER_SESSION_PROTOCOL_VERSION;
+      id: string;
+      ok: false;
+      error: { code: string; message: string };
+    };
+
+export interface BrowserSessionTarget {
+  sessionStatus(): Promise<BrowserSessionStatus>;
+  sessionInspect(locator?: BrowserSessionLocator): Promise<BrowserSessionInspection>;
+  sessionScreenshot(out: string): Promise<BrowserSessionScreenshot>;
+  sessionTabs(): Promise<BrowserSessionTab[]>;
+  sessionSelectTab(index: number): Promise<BrowserSessionTab>;
+  sessionOpenTab(url: string): Promise<BrowserSessionTab>;
+  sessionCloseTab(index: number): Promise<BrowserSessionTab>;
+  sessionGoto(url: string): Promise<BrowserSessionTab>;
+  sessionReload(): Promise<BrowserSessionTab>;
+  sessionClick(locator: BrowserSessionLocator): Promise<{ revision: number }>;
+  sessionFill(locator: BrowserSessionLocator, value: string): Promise<{ revision: number }>;
+  sessionPress(key: string): Promise<{ revision: number }>;
+  sessionWait(locator: BrowserSessionLocator): Promise<{ revision: number }>;
+}
+
+export class BrowserSessionError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "BrowserSessionError";
+  }
+}
+
+export interface BrowserSessionServer {
+  descriptorPath: string;
+  closeRequested: Promise<void>;
+  stopAccepting(): Promise<void>;
+  cleanup(): Promise<void>;
+}
+
+interface StartOptions {
+  platform?: NodeJS.Platform;
+  actionTimeoutMs?: number;
+  shortActionTimeoutMs?: number;
+}
+
+interface Deferred {
+  promise: Promise<void>;
+  resolve(): void;
+}
+
+function deferred(): Deferred {
+  let resolvePromise!: () => void;
+  const promise = new Promise<void>((resolve) => {
+    resolvePromise = resolve;
+  });
+  return { promise, resolve: resolvePromise };
+}
+
+export function browserSessionTransport(
+  controlFile: string,
+  platform: NodeJS.Platform = process.platform,
+): BrowserSessionDescriptor["transport"] {
+  if (platform === "win32") {
+    return {
+      kind: "pipe",
+      address: `\\\\.\\pipe\\harnery-browser-${randomUUID()}`,
+    };
+  }
+  const address = `${controlFile}.${randomBytes(8).toString("hex")}.sock`;
+  if (Buffer.byteLength(address) > UNIX_SOCKET_MAX_BYTES) {
+    throw new BrowserSessionError(
+      "socket_path_too_long",
+      `Control file path is too long for a Unix socket; keep it under ${UNIX_SOCKET_MAX_BYTES - 23} bytes.`,
+    );
+  }
+  return { kind: "unix", address };
+}
+
+export async function startBrowserSessionServer(
+  controlFileInput: string,
+  target: BrowserSessionTarget,
+  options: StartOptions = {},
+): Promise<BrowserSessionServer> {
+  const controlFile = resolve(controlFileInput);
+  const platform = options.platform ?? process.platform;
+  assertPrivateParent(controlFile, platform);
+  if (existsSync(controlFile)) {
+    throw new BrowserSessionError(
+      "descriptor_exists",
+      `Control descriptor already exists at ${controlFile}. Inspect or remove the stale file first.`,
+    );
+  }
+
+  const transport = browserSessionTransport(controlFile, platform);
+  if (transport.kind === "unix" && existsSync(transport.address)) {
+    throw new BrowserSessionError(
+      "transport_exists",
+      "Control transport already exists. Remove the stale endpoint first.",
+    );
+  }
+
+  const token = randomBytes(32).toString("base64url");
+  const descriptor: BrowserSessionDescriptor = {
+    version: BROWSER_SESSION_PROTOCOL_VERSION,
+    pid: process.pid,
+    created_at: new Date().toISOString(),
+    transport,
+    token,
+  };
+  const closeSignal = deferred();
+  const sockets = new Set<Socket>();
+  const actionSockets = new Set<Socket>();
+  let accepting = true;
+  let cleaned = false;
+  let published = false;
+  let actionTail: Promise<void> = Promise.resolve();
+
+  const server = createServer({ allowHalfOpen: true }, (socket) => {
+    sockets.add(socket);
+    socket.once("close", () => {
+      sockets.delete(socket);
+      actionSockets.delete(socket);
+    });
+    readRequestFrame(socket)
+      .then(async (raw) => {
+        const parsed = parseBrowserSessionRequest(raw);
+        if (!tokenMatches(token, parsed.token)) {
+          return errorResponse(parsed.id, "auth_failed", "Session authentication failed.");
+        }
+        if (!accepting) {
+          return errorResponse(parsed.id, "session_closing", "Browser session is closing.");
+        }
+        actionSockets.add(socket);
+
+        let actionPromise!: Promise<BrowserSessionResult>;
+        actionPromise = actionTail.then(() => dispatchAction(parsed, target, closeSignal));
+        actionTail = actionPromise.then(
+          () => undefined,
+          () => undefined,
+        );
+        const timeoutMs = isShortAction(parsed.action)
+          ? (options.shortActionTimeoutMs ?? SHORT_ACTION_TIMEOUT_MS)
+          : (options.actionTimeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
+        try {
+          const result = await responseWithTimeout(actionPromise, timeoutMs);
+          return successResponse(parsed.id, result);
+        } catch (error) {
+          return safeActionError(parsed.id, error);
+        }
+      })
+      .catch((error) => {
+        const safe =
+          error instanceof BrowserSessionError
+            ? errorResponse("unknown", error.code, error.message)
+            : errorResponse("unknown", "invalid_request", "Invalid browser-session request.");
+        return safe;
+      })
+      .then((response) => {
+        if (!socket.destroyed) socket.end(`${JSON.stringify(response)}\n`);
+        actionSockets.delete(socket);
+      })
+      .catch(() => socket.destroy());
+  });
+
+  try {
+    server.listen(transport.address);
+    await once(server, "listening");
+    if (transport.kind === "unix") chmodSync(transport.address, 0o600);
+    publishDescriptor(controlFile, descriptor);
+    published = true;
+  } catch (error) {
+    await closeServer(server);
+    if (transport.kind === "unix") unlinkIfExists(transport.address);
+    throw error;
+  }
+
+  async function stopAccepting(): Promise<void> {
+    if (!accepting) return;
+    accepting = false;
+    const serverClosed = closeServer(server);
+    for (const socket of sockets) {
+      if (!actionSockets.has(socket)) socket.destroy();
+    }
+    const settled = await settlesWithin(
+      actionTail,
+      options.actionTimeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS,
+    );
+    if (!settled) {
+      for (const socket of sockets) socket.destroy();
+    }
+    await serverClosed;
+  }
+
+  async function cleanup(): Promise<void> {
+    if (cleaned) return;
+    cleaned = true;
+    await stopAccepting();
+    for (const socket of sockets) socket.destroy();
+    if (published) unlinkIfExists(controlFile);
+    if (transport.kind === "unix") unlinkIfExists(transport.address);
+  }
+
+  return {
+    descriptorPath: controlFile,
+    closeRequested: closeSignal.promise,
+    stopAccepting,
+    cleanup,
+  };
+}
+
+export function readBrowserSessionDescriptor(
+  controlFileInput: string,
+  platform: NodeJS.Platform = process.platform,
+): BrowserSessionDescriptor {
+  const controlFile = resolve(controlFileInput);
+  assertPrivateParent(controlFile, platform);
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(controlFile);
+  } catch {
+    throw new BrowserSessionError(
+      "descriptor_missing",
+      "Browser session descriptor was not found.",
+    );
+  }
+  if (!stat.isFile()) {
+    throw new BrowserSessionError(
+      "descriptor_invalid",
+      "Browser session descriptor is not a file.",
+    );
+  }
+  if (platform !== "win32") {
+    const uid = process.getuid?.();
+    if (uid !== undefined && stat.uid !== uid) {
+      throw new BrowserSessionError(
+        "descriptor_owner",
+        "Browser session descriptor is not owned by the current user.",
+      );
+    }
+    if ((stat.mode & 0o777) !== 0o600) {
+      throw new BrowserSessionError(
+        "descriptor_mode",
+        "Browser session descriptor must have mode 0600.",
+      );
+    }
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(controlFile, "utf8"));
+  } catch {
+    throw new BrowserSessionError("descriptor_invalid", "Browser session descriptor is invalid.");
+  }
+  return validateDescriptor(parsed);
+}
+
+export async function sendBrowserSessionRequest(
+  controlFile: string,
+  action: BrowserSessionRequest["action"],
+  args: Record<string, unknown>,
+): Promise<BrowserSessionResult> {
+  const descriptor = readBrowserSessionDescriptor(controlFile);
+  const request = parseBrowserSessionRequest({
+    version: BROWSER_SESSION_PROTOCOL_VERSION,
+    id: randomUUID(),
+    token: descriptor.token,
+    action,
+    args,
+  });
+  const response = await sendRequestToDescriptor(descriptor, request);
+  if (!response.ok) throw new BrowserSessionError(response.error.code, response.error.message);
+  return response.result;
+}
+
+export async function sendRequestToDescriptor(
+  descriptor: BrowserSessionDescriptor,
+  request: BrowserSessionRequest,
+): Promise<BrowserSessionResponse> {
+  const socket = createConnection(descriptor.transport.address);
+  try {
+    await once(socket, "connect");
+    socket.write(`${JSON.stringify(request)}\n`);
+    const raw = await readResponseFrame(socket);
+    return parseBrowserSessionResponse(raw, request.id);
+  } catch (error) {
+    socket.destroy();
+    if (error instanceof BrowserSessionError) throw error;
+    throw new BrowserSessionError("transport_failed", "Could not connect to the browser session.");
+  }
+}
+
+export function parseBrowserSessionRequest(value: unknown): BrowserSessionRequest {
+  if (!isRecord(value) || !hasOnlyKeys(value, ["version", "id", "token", "action", "args"])) {
+    throw new BrowserSessionError("invalid_request", "Invalid browser-session request.");
+  }
+  if (value.version !== BROWSER_SESSION_PROTOCOL_VERSION) {
+    throw new BrowserSessionError("unsupported_version", "Unsupported browser-session protocol.");
+  }
+  const id = requiredString(value.id, "id", 128);
+  const token = requiredString(value.token, "token", 128);
+  const action = requiredString(value.action, "action", 32);
+  if (!isRecord(value.args)) {
+    throw new BrowserSessionError("invalid_request", "Request args must be an object.");
+  }
+
+  const base = { version: BROWSER_SESSION_PROTOCOL_VERSION, id, token };
+  switch (action) {
+    case "status":
+    case "tabs":
+    case "reload":
+    case "close":
+      requireKeys(value.args, []);
+      return { ...base, action, args: {} };
+    case "inspect": {
+      requireKeys(value.args, ["locator"], true);
+      return {
+        ...base,
+        action,
+        args: value.args.locator === undefined ? {} : { locator: parseLocator(value.args.locator) },
+      };
+    }
+    case "screenshot":
+      requireKeys(value.args, ["out"]);
+      return { ...base, action, args: { out: requiredString(value.args.out, "out", 4096) } };
+    case "select_tab":
+    case "close_tab":
+      requireKeys(value.args, ["index"]);
+      return { ...base, action, args: { index: requiredIndex(value.args.index) } };
+    case "open_tab":
+    case "goto":
+      requireKeys(value.args, ["url"]);
+      return { ...base, action, args: { url: requiredString(value.args.url, "url", 8192) } };
+    case "click":
+    case "wait":
+      requireKeys(value.args, ["locator"]);
+      return { ...base, action, args: { locator: parseLocator(value.args.locator) } };
+    case "fill": {
+      requireKeys(value.args, ["locator", "value"]);
+      const fillValue = requiredString(value.args.value, "value", BROWSER_SESSION_MAX_FILL_BYTES);
+      if (Buffer.byteLength(fillValue) > BROWSER_SESSION_MAX_FILL_BYTES) {
+        throw new BrowserSessionError("fill_too_large", "Fill input exceeds the 64 KiB limit.");
+      }
+      return {
+        ...base,
+        action,
+        args: { locator: parseLocator(value.args.locator), value: fillValue },
+      };
+    }
+    case "press":
+      requireKeys(value.args, ["key"]);
+      return { ...base, action, args: { key: requiredString(value.args.key, "key", 128) } };
+    default:
+      throw new BrowserSessionError("unknown_action", "Unknown browser-session action.");
+  }
+}
+
+function parseLocator(value: unknown): BrowserSessionLocator {
+  if (!isRecord(value)) {
+    throw new BrowserSessionError("invalid_locator", "A locator object is required.");
+  }
+  const kind = requiredString(value.kind, "locator kind", 16);
+  const partial = value.partial === undefined ? false : requiredBoolean(value.partial);
+  if (kind === "selector") {
+    requireKeys(value, ["kind", "value", "partial"] as const, true);
+    return { kind, value: requiredString(value.value, "selector", 4096), partial };
+  }
+  if (kind === "role") {
+    requireKeys(value, ["kind", "value", "name", "partial"] as const, true);
+    const role = requiredString(value.value, "role", 64);
+    if (!ARIA_ROLES.has(role)) {
+      throw new BrowserSessionError("invalid_locator", "Unsupported accessible role.");
+    }
+    return {
+      kind,
+      value: role,
+      ...(value.name === undefined ? {} : { name: requiredString(value.name, "name", 4096) }),
+      partial,
+    };
+  }
+  if (kind === "label" || kind === "text") {
+    requireKeys(value, ["kind", "value", "partial"] as const, true);
+    return { kind, value: requiredString(value.value, kind, 4096), partial };
+  }
+  throw new BrowserSessionError("invalid_locator", "Unsupported locator kind.");
+}
+
+async function dispatchAction(
+  request: BrowserSessionRequest,
+  target: BrowserSessionTarget,
+  closeSignal: Deferred,
+): Promise<BrowserSessionResult> {
+  switch (request.action) {
+    case "status":
+      return target.sessionStatus();
+    case "inspect":
+      return target.sessionInspect(request.args.locator);
+    case "screenshot":
+      return target.sessionScreenshot(request.args.out);
+    case "tabs":
+      return target.sessionTabs();
+    case "select_tab":
+      return target.sessionSelectTab(request.args.index);
+    case "open_tab":
+      return target.sessionOpenTab(request.args.url);
+    case "close_tab":
+      return target.sessionCloseTab(request.args.index);
+    case "goto":
+      return target.sessionGoto(request.args.url);
+    case "reload":
+      return target.sessionReload();
+    case "click":
+      return target.sessionClick(request.args.locator);
+    case "fill":
+      return target.sessionFill(request.args.locator, request.args.value);
+    case "press":
+      return target.sessionPress(request.args.key);
+    case "wait":
+      return target.sessionWait(request.args.locator);
+    case "close":
+      closeSignal.resolve();
+      return { closing: true };
+  }
+}
+
+function publishDescriptor(path: string, descriptor: BrowserSessionDescriptor): void {
+  const temporary = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(descriptor)}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    chmodSync(temporary, 0o600);
+    linkSync(temporary, path);
+  } catch (error) {
+    if (existsSync(path)) {
+      throw new BrowserSessionError(
+        "descriptor_exists",
+        `Control descriptor already exists at ${path}. Inspect or remove the stale file first.`,
+      );
+    }
+    throw error;
+  } finally {
+    unlinkIfExists(temporary);
+  }
+}
+
+function assertPrivateParent(path: string, platform: NodeJS.Platform): void {
+  const parent = dirname(path);
+  let stat: ReturnType<typeof lstatSync>;
+  try {
+    stat = lstatSync(parent);
+  } catch {
+    throw new BrowserSessionError(
+      "parent_missing",
+      "Control descriptor parent directory must already exist.",
+    );
+  }
+  if (!stat.isDirectory()) {
+    throw new BrowserSessionError(
+      "parent_invalid",
+      "Control descriptor parent is not a directory.",
+    );
+  }
+  if (platform === "win32") return;
+  const uid = process.getuid?.();
+  if (uid !== undefined && stat.uid !== uid) {
+    throw new BrowserSessionError(
+      "parent_owner",
+      "Control descriptor directory is not owned by the current user.",
+    );
+  }
+  if ((stat.mode & 0o077) !== 0) {
+    throw new BrowserSessionError(
+      "parent_mode",
+      "Control descriptor directory must not be accessible by group or other users.",
+    );
+  }
+}
+
+async function readRequestFrame(socket: Socket): Promise<unknown> {
+  const text = await readFrame(socket, BROWSER_SESSION_MAX_FRAME_BYTES, "request");
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new BrowserSessionError("malformed_json", "Request frame is not valid JSON.");
+  }
+}
+
+async function readResponseFrame(socket: Socket): Promise<unknown> {
+  const text = await readFrame(socket, BROWSER_SESSION_MAX_FRAME_BYTES, "response");
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new BrowserSessionError("invalid_response", "Browser session returned invalid JSON.");
+  }
+}
+
+async function readFrame(
+  socket: Socket,
+  limit: number,
+  kind: "request" | "response",
+): Promise<string> {
+  return await new Promise<string>((resolveFrame, reject) => {
+    let buffer = Buffer.alloc(0);
+    let settled = false;
+    const fail = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+    socket.on("data", (chunk: Buffer) => {
+      if (settled) return;
+      buffer = Buffer.concat([buffer, chunk]);
+      if (buffer.length > limit) {
+        fail(
+          new BrowserSessionError("frame_too_large", `${capitalize(kind)} frame exceeds 1 MiB.`),
+        );
+        return;
+      }
+      const newline = buffer.indexOf(0x0a);
+      if (newline < 0) return;
+      const trailing = buffer
+        .subarray(newline + 1)
+        .toString("utf8")
+        .trim();
+      if (trailing.length > 0) {
+        fail(
+          new BrowserSessionError("multiple_frames", "Only one frame is allowed per connection."),
+        );
+        return;
+      }
+      settled = true;
+      resolveFrame(buffer.subarray(0, newline).toString("utf8"));
+    });
+    socket.once("end", () => {
+      if (!settled) {
+        fail(
+          new BrowserSessionError(
+            "unterminated_frame",
+            `${capitalize(kind)} frame is unterminated.`,
+          ),
+        );
+      }
+    });
+    socket.once("error", (error) => fail(error));
+  });
+}
+
+function parseBrowserSessionResponse(value: unknown, requestId: string): BrowserSessionResponse {
+  if (
+    !isRecord(value) ||
+    value.version !== BROWSER_SESSION_PROTOCOL_VERSION ||
+    value.id !== requestId
+  ) {
+    throw new BrowserSessionError(
+      "invalid_response",
+      "Browser session returned an invalid response.",
+    );
+  }
+  if (value.ok === true && "result" in value) {
+    return value as BrowserSessionResponse;
+  }
+  if (
+    value.ok === false &&
+    isRecord(value.error) &&
+    typeof value.error.code === "string" &&
+    typeof value.error.message === "string"
+  ) {
+    return value as BrowserSessionResponse;
+  }
+  throw new BrowserSessionError(
+    "invalid_response",
+    "Browser session returned an invalid response.",
+  );
+}
+
+function validateDescriptor(value: unknown): BrowserSessionDescriptor {
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, ["version", "pid", "created_at", "transport", "token"])
+  ) {
+    throw new BrowserSessionError("descriptor_invalid", "Browser session descriptor is invalid.");
+  }
+  if (
+    value.version !== BROWSER_SESSION_PROTOCOL_VERSION ||
+    !Number.isSafeInteger(value.pid) ||
+    (value.pid as number) <= 0 ||
+    typeof value.created_at !== "string" ||
+    Number.isNaN(Date.parse(value.created_at)) ||
+    typeof value.token !== "string" ||
+    value.token.length < 40 ||
+    !isRecord(value.transport) ||
+    !hasOnlyKeys(value.transport, ["kind", "address"]) ||
+    (value.transport.kind !== "unix" && value.transport.kind !== "pipe") ||
+    typeof value.transport.address !== "string" ||
+    value.transport.address.length === 0
+  ) {
+    throw new BrowserSessionError("descriptor_invalid", "Browser session descriptor is invalid.");
+  }
+  return value as unknown as BrowserSessionDescriptor;
+}
+
+function tokenMatches(expected: string, actual: string): boolean {
+  const expectedHash = createHash("sha256").update(expected).digest();
+  const actualHash = createHash("sha256").update(actual).digest();
+  return timingSafeEqual(expectedHash, actualHash);
+}
+
+function successResponse(id: string, result: BrowserSessionResult): BrowserSessionResponse {
+  return { version: BROWSER_SESSION_PROTOCOL_VERSION, id, ok: true, result };
+}
+
+function errorResponse(id: string, code: string, message: string): BrowserSessionResponse {
+  return { version: BROWSER_SESSION_PROTOCOL_VERSION, id, ok: false, error: { code, message } };
+}
+
+function safeActionError(id: string, error: unknown): BrowserSessionResponse {
+  if (error instanceof BrowserSessionError) return errorResponse(id, error.code, error.message);
+  if (
+    isRecord(error) &&
+    error.name === "BrowserSessionActionError" &&
+    typeof error.code === "string" &&
+    typeof error.message === "string"
+  ) {
+    return errorResponse(id, error.code, error.message);
+  }
+  return errorResponse(id, "action_failed", "Browser action failed.");
+}
+
+function responseWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  return new Promise<T>((resolvePromise, reject) => {
+    const timer = setTimeout(
+      () => reject(new BrowserSessionError("action_timeout", "Browser action timed out.")),
+      timeoutMs,
+    );
+    timer.unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolvePromise(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+async function settlesWithin(promise: Promise<void>, timeoutMs: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise.then(() => true),
+      new Promise<boolean>((resolveTimeout) => {
+        timer = setTimeout(() => resolveTimeout(false), timeoutMs);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function isShortAction(action: BrowserSessionRequest["action"]): boolean {
+  return action === "status" || action === "tabs" || action === "close";
+}
+
+async function closeServer(server: Server): Promise<void> {
+  if (!server.listening) return;
+  await new Promise<void>((resolveClose) => server.close(() => resolveClose()));
+}
+
+function unlinkIfExists(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+function requiredString(value: unknown, field: string, maxLength: number): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+    throw new BrowserSessionError("invalid_request", `Invalid ${field}.`);
+  }
+  return value;
+}
+
+function requiredIndex(value: unknown): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new BrowserSessionError("invalid_request", "Tab index must be a non-negative integer.");
+  }
+  return value as number;
+}
+
+function requiredBoolean(value: unknown): boolean {
+  if (typeof value !== "boolean") {
+    throw new BrowserSessionError("invalid_request", "Locator partial flag must be boolean.");
+  }
+  return value;
+}
+
+function requireKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+  optional = false,
+): void {
+  if (!hasOnlyKeys(value, keys)) {
+    throw new BrowserSessionError("invalid_request", "Request args contain unsupported fields.");
+  }
+  if (!optional && keys.some((key) => !(key in value))) {
+    throw new BrowserSessionError("invalid_request", "Request args are incomplete.");
+  }
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const allowed = new Set(keys);
+  return Object.keys(value).every((key) => allowed.has(key));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function capitalize(value: string): string {
+  return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+}