@crewhaus/computer-use-driver 0.1.3 → 0.1.5

package/src/index.ts

@@ -1,347 +0,0 @@
-/**
- * Catalog R18 `computer-use-driver` — Section 25 BROW.
- *
- * Cross-platform driver for mouse/keyboard/screenshot operations. The
- * `Driver` interface exposes:
- *   - `screenshot()` → PNG `Uint8Array`
- *   - `click(x, y, button?)`
- *   - `type(text)`
- *   - `key(combo)`            // "Enter", "Tab", "Control+a"
- *   - `scroll(dx, dy)`
- *   - `getViewport()` → { width, height, devicePixelRatio }
- *   - `goto(url)`              // browser-only; `host` backend rejects
- *
- * v0 ships ONE concrete backend — `chromium` — driven by Playwright's
- * bundled headless chromium. The kickoff names this `docker-chromium`
- * because it's intended to run inside a Section-18 sandbox; in v0 we
- * lean on Playwright's own chromium-sandboxing (the chromium binary
- * runs as a sandboxed renderer process) and defer the explicit Docker
- * wrapping to a follow-up.
- *
- * The `host` backend (drives the developer's actual desktop) and
- * `remote` backend (CDP-style remote control) are interface stubs that
- * throw at `connect()` — see the kickoff explicitly forbidding the host
- * backend in the smoke ("never use `host` backend for the smoke since
- * it would drive the dev's actual desktop").
- */
-import { ComputerUseDriverError } from "./errors";
-import { type SsrfPinningProxy, startSsrfPinningProxy } from "./ssrf-proxy";
-
-export { ComputerUseDriverError };
-export {
-  type DnsLookupFn,
-  type SsrfPinningProxy,
-  type StartSsrfPinningProxyOptions,
-  startSsrfPinningProxy,
-} from "./ssrf-proxy";
-
-export type DriverBackend = "host" | "chromium" | "remote";
-export type MouseButton = "left" | "right" | "middle";
-
-export type Viewport = {
-  readonly width: number;
-  readonly height: number;
-  readonly devicePixelRatio: number;
-};
-
-export interface Driver {
-  readonly backend: DriverBackend;
-  /** Open / connect / launch chromium. Idempotent. */
-  connect(): Promise<void>;
-  /** Navigate the chromium tab. Throws on `host` backend. */
-  goto(url: string): Promise<void>;
-  /** Capture a PNG screenshot. */
-  screenshot(): Promise<Uint8Array>;
-  click(x: number, y: number, button?: MouseButton): Promise<void>;
-  type(text: string): Promise<void>;
-  key(combo: string): Promise<void>;
-  scroll(dx: number, dy: number): Promise<void>;
-  getViewport(): Promise<Viewport>;
-  /** Best-effort DOM snapshot. Used by tests + the post-action assertions. */
-  domText?(): Promise<string>;
-  disconnect(): Promise<void>;
-}
-
-export type CreateDriverOptions = {
-  readonly backend: DriverBackend;
-  /** Playwright launch overrides (e.g. headless: false). chromium-only. */
-  readonly playwrightOptions?: Record<string, unknown>;
-  /**
-   * SECURITY (audit follow-up R1) — route ALL chromium traffic through a
-   * local DNS-pinning forward proxy (see `ssrf-proxy.ts`). The proxy resolves
-   * each hostname once, validates the IP against the private/loopback/
-   * link-local/metadata floor, and dials that exact pinned IP, closing the
-   * DNS-rebinding TOCTOU the pre-goto guard in tool-navigate cannot close
-   * (the browser re-resolves at connect time, and sub-resource fetches never
-   * pass the guard at all). Default true. Set `false` ONLY when the browser
-   * must reach private/internal targets (e.g. testing an intranet app) AND
-   * the page content is trusted. Ignored when `playwrightOptions.proxy` is
-   * set — an operator-supplied proxy wins, and is then responsible for its
-   * own egress policy. chromium-only.
-   */
-  readonly ssrfProxy?: boolean;
-  /** Initial viewport — chromium-only. Default 1280x720@1. */
-  readonly viewport?: { width: number; height: number };
-  /** Test injection: a pre-built Driver instance the factory returns verbatim. */
-  readonly _injected?: Driver;
-  /**
-   * Test injection: replaces the chromium backend's dynamic
-   * `import("playwright")`. Lets the import-failure path be exercised without
-   * `mock.module` — a throwing module mock cannot be registered once
-   * playwright has been imported anywhere in the test process. chromium-only.
-   */
-  readonly _importPlaywright?: () => Promise<unknown>;
-};
-
-export function createDriver(opts: CreateDriverOptions): Driver {
-  if (opts._injected !== undefined) return opts._injected;
-  if (opts.backend === "chromium") return createChromiumDriver(opts);
-  if (opts.backend === "host") {
-    // Section 30 — host backend stays gated. Callers that have wired
-    // a real executor use `createHostDriver` directly.
-    return createHostDriverStub();
-  }
-  if (opts.backend === "remote") {
-    // Same pattern: callers with a puppeteer-core import use
-    // `createRemoteDriver` directly.
-    return createRemoteDriverStub();
-  }
-  throw new ComputerUseDriverError(`unknown backend: ${opts.backend}`);
-}
-
-// Section 30 — direct exports for callers that wire backends with an
-// executor or puppeteer-core import.
-export { createHostDriver, type HostBackendOptions, type HostExecutor } from "./backends/host";
-export {
-  createRemoteDriver,
-  type PuppeteerCoreLike,
-  type RemoteBackendOptions,
-} from "./backends/remote";
-
-// ---------------------------------------------------------------------------
-// Playwright-backed chromium driver.
-// ---------------------------------------------------------------------------
-
-function createChromiumDriver(opts: CreateDriverOptions): Driver {
-  let browser: unknown;
-  let context: unknown;
-  let page: unknown;
-  let connected = false;
-  let ssrfProxy: SsrfPinningProxy | undefined;
-
-  async function loadPlaywright(): Promise<{
-    chromium: { launch: (...args: unknown[]) => unknown };
-  }> {
-    try {
-      // Lazy import so non-browser users don't need Playwright in their tree.
-      // The import is dynamic via a string indirection so `tsc` doesn't fail
-      // when playwright (an optional peer dep) isn't installed in CI.
-      const playwrightModule = "playwright";
-      const mod =
-        opts._importPlaywright !== undefined
-          ? await opts._importPlaywright()
-          : await import(playwrightModule);
-      return mod as unknown as { chromium: { launch: (...args: unknown[]) => unknown } };
-    } catch (err) {
-      throw new ComputerUseDriverError(
-        "Playwright not installed. Run `bun add -D playwright` and `bunx playwright install chromium` to use the chromium backend.",
-        err,
-      );
-    }
-  }
-
-  return {
-    backend: "chromium",
-    async connect() {
-      if (connected) return;
-      const { chromium } = await loadPlaywright();
-      const userOpts = opts.playwrightOptions ?? {};
-      // SECURITY — DNS-pinning proxy on by default (see CreateDriverOptions.
-      // ssrfProxy). An operator-supplied playwrightOptions.proxy wins; the
-      // proxy starts only after the playwright import succeeds so the
-      // import-failure path can't leak a listening server.
-      const useSsrfProxy = opts.ssrfProxy !== false && userOpts["proxy"] === undefined;
-      if (useSsrfProxy) {
-        ssrfProxy = await startSsrfPinningProxy();
-      }
-      try {
-        // Playwright defaults: chromium runs in its own sandbox (its own
-        // sandboxed renderer process). Headless by default. The
-        // `<-loopback>` bypass rule removes Chromium's implicit proxy bypass
-        // for localhost targets, so loopback requests also route through the
-        // pinning proxy — and get blocked there.
-        const launchOpts: Record<string, unknown> = {
-          headless: true,
-          ...userOpts,
-          ...(ssrfProxy !== undefined
-            ? { proxy: { server: ssrfProxy.url, bypass: "<-loopback>" } }
-            : {}),
-        };
-        browser = await (chromium.launch as (o: unknown) => Promise<unknown>)(launchOpts);
-        const ctxOpts: Record<string, unknown> = {
-          viewport: opts.viewport ?? { width: 1280, height: 720 },
-        };
-        context = await (browser as { newContext: (o: unknown) => Promise<unknown> }).newContext(
-          ctxOpts,
-        );
-        page = await (context as { newPage: () => Promise<unknown> }).newPage();
-      } catch (err) {
-        // Launch/context failure must not leak the proxy server (or a
-        // half-launched browser).
-        try {
-          await (browser as { close?: () => Promise<void> } | undefined)?.close?.();
-        } catch {
-          // best-effort
-        }
-        browser = undefined;
-        await ssrfProxy?.close();
-        ssrfProxy = undefined;
-        throw err;
-      }
-      connected = true;
-    },
-
-    async goto(url) {
-      if (!connected)
-        throw new ComputerUseDriverError("driver not connected — call connect() first");
-      await (page as { goto: (u: string, o?: unknown) => Promise<unknown> }).goto(url, {
-        waitUntil: "domcontentloaded",
-      });
-    },
-
-    async screenshot() {
-      if (!connected) throw new ComputerUseDriverError("driver not connected");
-      const buf = (await (page as { screenshot: (o?: unknown) => Promise<unknown> }).screenshot({
-        type: "png",
-      })) as Uint8Array;
-      return buf;
-    },
-
-    async click(x, y, button = "left") {
-      if (!connected) throw new ComputerUseDriverError("driver not connected");
-      await (
-        page as { mouse: { click: (x: number, y: number, o?: unknown) => Promise<void> } }
-      ).mouse.click(x, y, { button });
-    },
-
-    async type(text) {
-      if (!connected) throw new ComputerUseDriverError("driver not connected");
-      await (page as { keyboard: { type: (t: string) => Promise<void> } }).keyboard.type(text);
-    },
-
-    async key(combo) {
-      if (!connected) throw new ComputerUseDriverError("driver not connected");
-      await (page as { keyboard: { press: (k: string) => Promise<void> } }).keyboard.press(combo);
-    },
-
-    async scroll(dx, dy) {
-      if (!connected) throw new ComputerUseDriverError("driver not connected");
-      await (page as { mouse: { wheel: (dx: number, dy: number) => Promise<void> } }).mouse.wheel(
-        dx,
-        dy,
-      );
-    },
-
-    async getViewport() {
-      if (!connected) throw new ComputerUseDriverError("driver not connected");
-      const vp = (
-        page as { viewportSize: () => { width: number; height: number } | null }
-      ).viewportSize();
-      const w = vp?.width ?? opts.viewport?.width ?? 1280;
-      const h = vp?.height ?? opts.viewport?.height ?? 720;
-      return { width: w, height: h, devicePixelRatio: 1 };
-    },
-
-    async domText() {
-      if (!connected) throw new ComputerUseDriverError("driver not connected");
-      return (page as { textContent: (sel: string) => Promise<string | null> })
-        .textContent("body")
-        .then((t) => t ?? "");
-    },
-
-    async disconnect() {
-      if (!connected) return;
-      try {
-        await (browser as { close: () => Promise<void> }).close();
-      } catch {
-        // best-effort
-      }
-      await ssrfProxy?.close();
-      ssrfProxy = undefined;
-      connected = false;
-      browser = undefined;
-      context = undefined;
-      page = undefined;
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Stubs for host + remote backends.
-// ---------------------------------------------------------------------------
-
-function createHostDriverStub(): Driver {
-  return {
-    backend: "host",
-    async connect() {
-      throw new ComputerUseDriverError(
-        "host backend is not implemented in v0. The kickoff explicitly forbids it for smokes (would drive the dev's actual desktop). Native macOS / Linux / Windows backends land in a follow-up gated on `CREWHAUS_BROW_HOST_SMOKE=1`.",
-      );
-    },
-    async goto() {
-      throw new ComputerUseDriverError("host backend not implemented");
-    },
-    async screenshot() {
-      throw new ComputerUseDriverError("host backend not implemented");
-    },
-    async click() {
-      throw new ComputerUseDriverError("host backend not implemented");
-    },
-    async type() {
-      throw new ComputerUseDriverError("host backend not implemented");
-    },
-    async key() {
-      throw new ComputerUseDriverError("host backend not implemented");
-    },
-    async scroll() {
-      throw new ComputerUseDriverError("host backend not implemented");
-    },
-    async getViewport() {
-      throw new ComputerUseDriverError("host backend not implemented");
-    },
-    async disconnect() {},
-  };
-}
-
-function createRemoteDriverStub(): Driver {
-  return {
-    backend: "remote",
-    async connect() {
-      throw new ComputerUseDriverError(
-        "remote backend (CDP / Browserless) is not implemented in v0",
-      );
-    },
-    async goto() {
-      throw new ComputerUseDriverError("remote backend not implemented");
-    },
-    async screenshot() {
-      throw new ComputerUseDriverError("remote backend not implemented");
-    },
-    async click() {
-      throw new ComputerUseDriverError("remote backend not implemented");
-    },
-    async type() {
-      throw new ComputerUseDriverError("remote backend not implemented");
-    },
-    async key() {
-      throw new ComputerUseDriverError("remote backend not implemented");
-    },
-    async scroll() {
-      throw new ComputerUseDriverError("remote backend not implemented");
-    },
-    async getViewport() {
-      throw new ComputerUseDriverError("remote backend not implemented");
-    },
-    async disconnect() {},
-  };
-}

package/src/ssrf-proxy.test.ts

@@ -1,259 +0,0 @@
-/**
- * SECURITY (audit follow-up R1) — DNS-pinning proxy contract tests.
- *
- * Clients are raw `node:net` sockets writing literal HTTP — the most faithful
- * stand-in for a browser talking to a forward proxy, and immune to any HTTP
- * client library rewriting the request target. DNS + the blocked-IP predicate
- * are injected so no test depends on real resolution or real public hosts:
- * the allow-path tests stub the predicate open and point a fake public name
- * at a local target server; the deny-path tests use the REAL predicate.
- */
-import { afterEach, describe, expect, test } from "bun:test";
-import * as http from "node:http";
-import * as net from "node:net";
-import {
-  type SsrfPinningProxy,
-  isPrivateIp,
-  normalizeIpv4,
-  startSsrfPinningProxy,
-} from "./ssrf-proxy";
-
-const cleanups: Array<() => Promise<void> | void> = [];
-afterEach(async () => {
-  while (cleanups.length > 0) {
-    await cleanups.pop()?.();
-  }
-});
-
-function track(proxy: SsrfPinningProxy): SsrfPinningProxy {
-  cleanups.push(() => proxy.close());
-  return proxy;
-}
-
-/** Write `request` to the proxy and return everything received until close. */
-function rawHttp(port: number, request: string): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const sock = net.connect({ host: "127.0.0.1", port }, () => {
-      sock.write(request);
-    });
-    let buf = "";
-    sock.on("data", (d) => {
-      buf += d.toString();
-    });
-    sock.on("close", () => resolve(buf));
-    sock.on("error", reject);
-  });
-}
-
-/** Local HTTP target that records the request line + Host header. */
-async function startTarget(): Promise<{
-  port: number;
-  seen: Array<{ url: string; host: string | undefined }>;
-}> {
-  const seen: Array<{ url: string; host: string | undefined }> = [];
-  const server = http.createServer((req, res) => {
-    seen.push({ url: req.url ?? "", host: req.headers.host });
-    res.writeHead(200, { "content-type": "text/plain" });
-    res.end("target-says-hello");
-  });
-  await new Promise<void>((r) => server.listen(0, "127.0.0.1", () => r()));
-  cleanups.push(
-    () =>
-      new Promise<void>((r) => {
-        server.closeAllConnections();
-        server.close(() => r());
-      }),
-  );
-  const addr = server.address();
-  if (addr === null || typeof addr === "string") throw new Error("no port");
-  return { port: addr.port, seen };
-}
-
-describe("IP validators (duplicated from tool-fetch — keep in sync)", () => {
-  test.each([
-    ["127.0.0.1", true],
-    ["10.1.2.3", true],
-    ["169.254.169.254", true],
-    ["192.168.0.1", true],
-    ["100.64.0.1", true],
-    ["::1", true],
-    ["fe80::1", true],
-    ["fd00::1", true],
-    ["::ffff:127.0.0.1", true],
-    ["::ffff:7f00:1", true],
-    ["8.8.8.8", false],
-    ["93.184.216.34", false],
-    ["2606:4700::1111", false],
-  ])("isPrivateIp(%p) === %p", (ip, want) => {
-    expect(isPrivateIp(ip)).toBe(want);
-  });
-
-  test.each([
-    ["0x7f000001", "127.0.0.1"],
-    ["2130706433", "127.0.0.1"],
-    ["0177.0.0.1", "127.0.0.1"],
-    ["127.1", "127.0.0.1"],
-    ["not-an-ip", null],
-  ])("normalizeIpv4(%p) === %p", (raw, want) => {
-    expect(normalizeIpv4(raw)).toBe(want);
-  });
-});
-
-describe("plain-HTTP forwarding (absolute-form)", () => {
-  test("forwards to the PINNED ip, preserving the Host header for vhosts", async () => {
-    const target = await startTarget();
-    let lookups = 0;
-    const proxy = track(
-      await startSsrfPinningProxy({
-        _lookup: async () => {
-          lookups += 1;
-          return { address: "127.0.0.1", family: 4 };
-        },
-        _isIpBlocked: () => false,
-      }),
-    );
-    const res = await rawHttp(
-      proxy.port,
-      `GET http://fake-public.example:${target.port}/x?q=1 HTTP/1.1\r\nHost: fake-public.example:${target.port}\r\nConnection: close\r\n\r\n`,
-    );
-    expect(res).toContain("200");
-    expect(res).toContain("target-says-hello");
-    // The socket went to the pinned 127.0.0.1; the Host header kept the name.
-    expect(target.seen).toEqual([{ url: "/x?q=1", host: `fake-public.example:${target.port}` }]);
-    // Pinning = exactly one resolution per connection. A second lookup would
-    // be the rebinding window this proxy exists to remove.
-    expect(lookups).toBe(1);
-  });
-
-  test("origin-form request targets are rejected (not an origin server)", async () => {
-    const proxy = track(await startSsrfPinningProxy());
-    const res = await rawHttp(
-      proxy.port,
-      "GET /just-a-path HTTP/1.1\r\nHost: whatever\r\nConnection: close\r\n\r\n",
-    );
-    expect(res).toContain("400");
-  });
-
-  test("blocks localhost names without resolving", async () => {
-    let lookups = 0;
-    const proxy = track(
-      await startSsrfPinningProxy({
-        _lookup: async () => {
-          lookups += 1;
-          return { address: "8.8.8.8", family: 4 };
-        },
-      }),
-    );
-    const res = await rawHttp(
-      proxy.port,
-      "GET http://localhost:9999/ HTTP/1.1\r\nHost: localhost:9999\r\nConnection: close\r\n\r\n",
-    );
-    expect(res).toContain("403");
-    expect(lookups).toBe(0);
-  });
-
-  test("blocks private IP literals, including obfuscated forms", async () => {
-    const proxy = track(await startSsrfPinningProxy());
-    for (const host of ["127.0.0.1", "0x7f000001", "169.254.169.254", "[::1]"]) {
-      const res = await rawHttp(
-        proxy.port,
-        `GET http://${host}/ HTTP/1.1\r\nHost: ${host}\r\nConnection: close\r\n\r\n`,
-      );
-      expect(res).toContain("403");
-    }
-  });
-
-  test("blocks a public name that RESOLVES to a private IP (rebinding shape)", async () => {
-    const proxy = track(
-      await startSsrfPinningProxy({
-        _lookup: async () => ({ address: "169.254.169.254", family: 4 }),
-      }),
-    );
-    const res = await rawHttp(
-      proxy.port,
-      "GET http://innocent-looking.example/ HTTP/1.1\r\nHost: innocent-looking.example\r\nConnection: close\r\n\r\n",
-    );
-    expect(res).toContain("403");
-    expect(res).toContain("private IP 169.254.169.254");
-  });
-});
-
-describe("CONNECT tunneling", () => {
-  test("tunnels to the PINNED ip and pipes both directions", async () => {
-    // TCP echo target.
-    const echo = net.createServer((s) => s.pipe(s));
-    await new Promise<void>((r) => echo.listen(0, "127.0.0.1", () => r()));
-    cleanups.push(() => new Promise<void>((r) => echo.close(() => r())));
-    const echoAddr = echo.address();
-    if (echoAddr === null || typeof echoAddr === "string") throw new Error("no port");
-
-    let lookups = 0;
-    const proxy = track(
-      await startSsrfPinningProxy({
-        _lookup: async () => {
-          lookups += 1;
-          return { address: "127.0.0.1", family: 4 };
-        },
-        _isIpBlocked: () => false,
-      }),
-    );
-
-    const result = await new Promise<string>((resolve, reject) => {
-      const sock = net.connect({ host: "127.0.0.1", port: proxy.port }, () => {
-        sock.write(
-          `CONNECT fake-tls.example:${echoAddr.port} HTTP/1.1\r\nHost: fake-tls.example:${echoAddr.port}\r\n\r\n`,
-        );
-      });
-      let buf = "";
-      let established = false;
-      sock.on("data", (d) => {
-        buf += d.toString();
-        if (!established && buf.includes("\r\n\r\n")) {
-          if (!buf.startsWith("HTTP/1.1 200")) {
-            reject(new Error(`tunnel refused: ${buf.split("\r\n")[0]}`));
-            return;
-          }
-          established = true;
-          buf = "";
-          sock.write("opaque-tls-bytes");
-        } else if (established && buf.includes("opaque-tls-bytes")) {
-          sock.end();
-          resolve(buf);
-        }
-      });
-      sock.on("error", reject);
-    });
-    expect(result).toBe("opaque-tls-bytes");
-    expect(lookups).toBe(1);
-  });
-
-  test("refuses CONNECT to private targets with 403", async () => {
-    const proxy = track(await startSsrfPinningProxy());
-    const res = await rawHttp(
-      proxy.port,
-      "CONNECT 127.0.0.1:443 HTTP/1.1\r\nHost: 127.0.0.1:443\r\n\r\n",
-    );
-    expect(res).toContain("403");
-  });
-
-  test("refuses malformed CONNECT targets", async () => {
-    const proxy = track(await startSsrfPinningProxy());
-    const res = await rawHttp(proxy.port, "CONNECT garbage HTTP/1.1\r\nHost: garbage\r\n\r\n");
-    expect(res).toContain("403");
-  });
-});
-
-describe("lifecycle", () => {
-  test("close() actually stops accepting connections", async () => {
-    const proxy = await startSsrfPinningProxy();
-    await proxy.close();
-    await expect(
-      new Promise((resolve, reject) => {
-        const sock = net.connect({ host: "127.0.0.1", port: proxy.port }, () =>
-          resolve("connected"),
-        );
-        sock.on("error", reject);
-      }),
-    ).rejects.toThrow();
-  });
-});