@crewhaus/computer-use-driver 0.1.3 → 0.1.5

package/dist/backends/host.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Section 30 — host backend for `computer-use-driver`. Drives the
+ * dev's actual desktop via the OS-level computer-use surface (macOS
+ * Quartz / Linux X11+xdotool / Windows SendInput). Production
+ * deployments use this for cross-app workflows that no browser can
+ * reach (Maps, Notes, Photos, Finder, native System Settings).
+ *
+ * **Safety gate:** the constructor refuses to return a working driver
+ * unless `CREWHAUS_BROW_HOST_ENABLED=1` is set in the environment. The
+ * goal is fail-loud ergonomics: deployment errors that try to use the
+ * host backend without explicit opt-in should immediately surface
+ * rather than silently driving the dev's machine.
+ *
+ * The OS-level command dispatch is delegated to a caller-supplied
+ * `HostExecutor` so tests + the smoke harness can stub the surface.
+ * In production, codegen wires a thin wrapper that shells out to
+ * `xdotool` (Linux), `cliclick` (macOS), or PowerShell (Windows).
+ */
+import { type Driver, type Viewport } from "../index";
+export type HostExecutor = {
+    /** Click at absolute screen coordinates. Button: "left" | "right" | "middle". */
+    click(x: number, y: number, button: string): Promise<void>;
+    /** Type a string at the current focus. */
+    type(text: string): Promise<void>;
+    /** Press a single key (or modifier+key, e.g. "cmd+space"). */
+    key(combo: string): Promise<void>;
+    /** Scroll at absolute screen coordinates. */
+    scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
+    /** Capture a PNG screenshot of the entire screen, returning base64. */
+    screenshot(): Promise<{
+        pngBase64: string;
+        viewport: Viewport;
+    }>;
+    /** Disconnect / clean up any handles. */
+    close?(): Promise<void>;
+};
+export type HostBackendOptions = {
+    /** Required to pass; otherwise the constructor throws. */
+    readonly enabled: boolean;
+    /** Test injection (or production OS shim). */
+    readonly executor: HostExecutor;
+};
+export declare function createHostDriver(opts: HostBackendOptions): Driver;

package/dist/backends/host.js

@@ -0,0 +1,75 @@
+/**
+ * Section 30 — host backend for `computer-use-driver`. Drives the
+ * dev's actual desktop via the OS-level computer-use surface (macOS
+ * Quartz / Linux X11+xdotool / Windows SendInput). Production
+ * deployments use this for cross-app workflows that no browser can
+ * reach (Maps, Notes, Photos, Finder, native System Settings).
+ *
+ * **Safety gate:** the constructor refuses to return a working driver
+ * unless `CREWHAUS_BROW_HOST_ENABLED=1` is set in the environment. The
+ * goal is fail-loud ergonomics: deployment errors that try to use the
+ * host backend without explicit opt-in should immediately surface
+ * rather than silently driving the dev's machine.
+ *
+ * The OS-level command dispatch is delegated to a caller-supplied
+ * `HostExecutor` so tests + the smoke harness can stub the surface.
+ * In production, codegen wires a thin wrapper that shells out to
+ * `xdotool` (Linux), `cliclick` (macOS), or PowerShell (Windows).
+ */
+import { ComputerUseDriverError } from "../index";
+export function createHostDriver(opts) {
+    if (!opts.enabled) {
+        throw new ComputerUseDriverError("host backend disabled. Set CREWHAUS_BROW_HOST_ENABLED=1 to opt in (this drives the actual desktop — never enable in smoke tests).");
+    }
+    let connected = false;
+    return {
+        backend: "host",
+        async connect() {
+            connected = true;
+        },
+        async goto(_url) {
+            // The host backend doesn't navigate URLs — callers should open
+            // a browser app first via the OS shell. We surface this as a
+            // soft-fail since some workflows want goto to be a no-op.
+            throw new ComputerUseDriverError("host backend cannot navigate URLs directly — open a browser via OS shell first");
+        },
+        async screenshot() {
+            if (!connected)
+                throw new ComputerUseDriverError("host driver not connected");
+            const { pngBase64 } = await opts.executor.screenshot();
+            return Buffer.from(pngBase64, "base64");
+        },
+        async click(x, y, button = "left") {
+            if (!connected)
+                throw new ComputerUseDriverError("host driver not connected");
+            await opts.executor.click(x, y, button);
+        },
+        async type(text) {
+            if (!connected)
+                throw new ComputerUseDriverError("host driver not connected");
+            await opts.executor.type(text);
+        },
+        async key(combo) {
+            if (!connected)
+                throw new ComputerUseDriverError("host driver not connected");
+            await opts.executor.key(combo);
+        },
+        async scroll(dx, dy) {
+            if (!connected)
+                throw new ComputerUseDriverError("host driver not connected");
+            // Driver.scroll has no cursor coords; pass (0, 0) for the executor's
+            // anchor and let the host shim scroll at the focused window's origin.
+            await opts.executor.scroll(0, 0, dx, dy);
+        },
+        async getViewport() {
+            if (!connected)
+                throw new ComputerUseDriverError("host driver not connected");
+            const shot = await opts.executor.screenshot();
+            return shot.viewport;
+        },
+        async disconnect() {
+            connected = false;
+            await opts.executor.close?.();
+        },
+    };
+}

package/dist/backends/remote.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Section 30 — remote backend for `computer-use-driver`. Connects to a
+ * remote chromium instance over Chrome DevTools Protocol (browserless.io,
+ * BrowserBase, self-hosted DevTools). Same `Driver` surface as the
+ * Playwright-backed `chromium` backend; the difference is the connection
+ * layer.
+ *
+ * Production deployments install `puppeteer-core` and pass it as
+ * `_puppeteer`. Without it, the constructor returns a driver whose
+ * `connect()` throws a clear diagnostic — matching the SQS / Vapi
+ * pattern of "abstraction always builds; deployment-time SDK presence
+ * gates the operation".
+ */
+import { type Driver, type Viewport } from "../index";
+export type RemoteBackendOptions = {
+    /** Browserless / BrowserBase WebSocket endpoint. */
+    readonly url: string;
+    /** Optional viewport override; defaults to 1280×800. */
+    readonly viewport?: Viewport;
+    /**
+     * Test / production injection: `puppeteer-core` `import` namespace.
+     * When undefined, the driver throws at `connect()` with a hint to
+     * install puppeteer-core.
+     */
+    readonly _puppeteer?: PuppeteerCoreLike;
+};
+export type PuppeteerCoreLike = {
+    connect(opts: {
+        browserWSEndpoint: string;
+    }): Promise<{
+        newPage(): Promise<{
+            goto(url: string): Promise<void>;
+            screenshot(opts?: {
+                encoding?: "base64";
+            }): Promise<string | Buffer>;
+            mouse: {
+                click(x: number, y: number, opts?: {
+                    button?: string;
+                }): Promise<void>;
+            };
+            keyboard: {
+                type(text: string): Promise<void>;
+                press(key: string): Promise<void>;
+            };
+            evaluate<T>(fn: () => T): Promise<T>;
+            close(): Promise<void>;
+        }>;
+        close(): Promise<void>;
+    }>;
+};
+export declare function createRemoteDriver(opts: RemoteBackendOptions): Driver;

package/dist/backends/remote.js

@@ -0,0 +1,85 @@
+/**
+ * Section 30 — remote backend for `computer-use-driver`. Connects to a
+ * remote chromium instance over Chrome DevTools Protocol (browserless.io,
+ * BrowserBase, self-hosted DevTools). Same `Driver` surface as the
+ * Playwright-backed `chromium` backend; the difference is the connection
+ * layer.
+ *
+ * Production deployments install `puppeteer-core` and pass it as
+ * `_puppeteer`. Without it, the constructor returns a driver whose
+ * `connect()` throws a clear diagnostic — matching the SQS / Vapi
+ * pattern of "abstraction always builds; deployment-time SDK presence
+ * gates the operation".
+ */
+import { ComputerUseDriverError } from "../index";
+export function createRemoteDriver(opts) {
+    if (!opts.url)
+        throw new ComputerUseDriverError("remote backend requires url");
+    let browser;
+    let page;
+    let connected = false;
+    function ensure() {
+        if (!page)
+            throw new ComputerUseDriverError("remote driver not connected");
+        return page;
+    }
+    return {
+        backend: "remote",
+        async connect() {
+            const pup = opts._puppeteer;
+            if (!pup) {
+                throw new ComputerUseDriverError("remote backend requires `puppeteer-core` to be installed and passed as `_puppeteer`. e.g. `import * as pc from 'puppeteer-core'; createDriver({ backend: 'remote', url, _puppeteer: pc })`.");
+            }
+            browser = await pup.connect({ browserWSEndpoint: opts.url });
+            page = await browser.newPage();
+            connected = true;
+        },
+        async goto(url) {
+            await ensure().goto(url);
+        },
+        async screenshot() {
+            const buffer = await ensure().screenshot({ encoding: "base64" });
+            const pngBase64 = typeof buffer === "string" ? buffer : buffer.toString("base64");
+            return Buffer.from(pngBase64, "base64");
+        },
+        async click(x, y, button = "left") {
+            await ensure().mouse.click(x, y, { button });
+        },
+        async type(text) {
+            await ensure().keyboard.type(text);
+        },
+        async key(combo) {
+            await ensure().keyboard.press(combo);
+        },
+        async scroll(dx, dy) {
+            // Puppeteer doesn't expose mouse.wheel directly; dispatch from the
+            // page context where `window` is defined. The eval-with-args shape
+            // isn't on the local PuppeteerCoreLike type; cast to puppeteer's
+            // actual surface to call it.
+            const pageWithArgs = ensure();
+            await pageWithArgs.evaluate((d) => {
+                globalThis.scrollBy(d.dx, d.dy);
+            }, { dx, dy });
+        },
+        async getViewport() {
+            const v = opts.viewport;
+            if (v !== undefined)
+                return v;
+            return { width: 1280, height: 800, devicePixelRatio: 1 };
+        },
+        async disconnect() {
+            try {
+                if (page)
+                    await page.close();
+                if (browser)
+                    await browser.close();
+            }
+            catch {
+                /* best-effort */
+            }
+            connected = false;
+            page = undefined;
+            browser = undefined;
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+import { CrewhausError } from "@crewhaus/errors";
+export declare class ComputerUseDriverError extends CrewhausError {
+    readonly name = "ComputerUseDriverError";
+    constructor(message: string, cause?: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,7 @@
+import { CrewhausError } from "@crewhaus/errors";
+export class ComputerUseDriverError extends CrewhausError {
+    name = "ComputerUseDriverError";
+    constructor(message, cause) {
+        super("tool", message, cause);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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";
+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 declare function createDriver(opts: CreateDriverOptions): Driver;
+export { createHostDriver, type HostBackendOptions, type HostExecutor } from "./backends/host";
+export { createRemoteDriver, type PuppeteerCoreLike, type RemoteBackendOptions, } from "./backends/remote";

package/dist/index.js

@@ -0,0 +1,257 @@
+/**
+ * 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 { startSsrfPinningProxy } from "./ssrf-proxy";
+export { ComputerUseDriverError };
+export { startSsrfPinningProxy, } from "./ssrf-proxy";
+export function createDriver(opts) {
+    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 } from "./backends/host";
+export { createRemoteDriver, } from "./backends/remote";
+// ---------------------------------------------------------------------------
+// Playwright-backed chromium driver.
+// ---------------------------------------------------------------------------
+function createChromiumDriver(opts) {
+    let browser;
+    let context;
+    let page;
+    let connected = false;
+    let ssrfProxy;
+    async function loadPlaywright() {
+        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;
+        }
+        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 = {
+                    headless: true,
+                    ...userOpts,
+                    ...(ssrfProxy !== undefined
+                        ? { proxy: { server: ssrfProxy.url, bypass: "<-loopback>" } }
+                        : {}),
+                };
+                browser = await chromium.launch(launchOpts);
+                const ctxOpts = {
+                    viewport: opts.viewport ?? { width: 1280, height: 720 },
+                };
+                context = await browser.newContext(ctxOpts);
+                page = await context.newPage();
+            }
+            catch (err) {
+                // Launch/context failure must not leak the proxy server (or a
+                // half-launched browser).
+                try {
+                    await browser?.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.goto(url, {
+                waitUntil: "domcontentloaded",
+            });
+        },
+        async screenshot() {
+            if (!connected)
+                throw new ComputerUseDriverError("driver not connected");
+            const buf = (await page.screenshot({
+                type: "png",
+            }));
+            return buf;
+        },
+        async click(x, y, button = "left") {
+            if (!connected)
+                throw new ComputerUseDriverError("driver not connected");
+            await page.mouse.click(x, y, { button });
+        },
+        async type(text) {
+            if (!connected)
+                throw new ComputerUseDriverError("driver not connected");
+            await page.keyboard.type(text);
+        },
+        async key(combo) {
+            if (!connected)
+                throw new ComputerUseDriverError("driver not connected");
+            await page.keyboard.press(combo);
+        },
+        async scroll(dx, dy) {
+            if (!connected)
+                throw new ComputerUseDriverError("driver not connected");
+            await page.mouse.wheel(dx, dy);
+        },
+        async getViewport() {
+            if (!connected)
+                throw new ComputerUseDriverError("driver not connected");
+            const vp = page.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
+                .textContent("body")
+                .then((t) => t ?? "");
+        },
+        async disconnect() {
+            if (!connected)
+                return;
+            try {
+                await browser.close();
+            }
+            catch {
+                // best-effort
+            }
+            await ssrfProxy?.close();
+            ssrfProxy = undefined;
+            connected = false;
+            browser = undefined;
+            context = undefined;
+            page = undefined;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Stubs for host + remote backends.
+// ---------------------------------------------------------------------------
+function createHostDriverStub() {
+    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() {
+    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/dist/ssrf-proxy.d.ts

@@ -0,0 +1,26 @@
+export type DnsLookupFn = (host: string) => Promise<{
+    readonly address: string;
+    readonly family: number;
+}>;
+export type SsrfPinningProxy = {
+    /** Proxy URL for the browser's launch options, e.g. `http://127.0.0.1:49321`. */
+    readonly url: string;
+    readonly port: number;
+    close(): Promise<void>;
+};
+export type StartSsrfPinningProxyOptions = {
+    /** Test seam: replaces the DNS resolver. */
+    readonly _lookup?: DnsLookupFn;
+    /** Test seam: replaces the blocked-IP predicate. */
+    readonly _isIpBlocked?: (ip: string) => boolean;
+};
+/**
+ * Normalise an IPv4 literal to canonical dotted-decimal. Browsers and many
+ * HTTP stacks accept octal (`0177.0.0.1`), hex (`0x7f.0.0.1` / `0x7f000001`),
+ * and 32-bit integer (`2130706433`) forms — all of which resolve to the same
+ * address as `127.0.0.1`. Canonicalising first means `isPrivateIp` classifies
+ * them. Returns dotted-decimal, or `null` if `raw` is not an IPv4 literal.
+ */
+export declare function normalizeIpv4(raw: string): string | null;
+export declare function isPrivateIp(addr: string): boolean;
+export declare function startSsrfPinningProxy(opts?: StartSsrfPinningProxyOptions): Promise<SsrfPinningProxy>;