@crewhaus/tool-navigate 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import type { Driver } from "@crewhaus/computer-use-driver";
+import { CrewhausError } from "@crewhaus/errors";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+export declare class NavigateError extends CrewhausError {
+    readonly name = "NavigateError";
+    constructor(message: string, cause?: unknown);
+}
+export type DnsLookupFn = (hostname: string) => Promise<{
+    readonly address: string;
+    readonly family: number;
+}>;
+/** Test hook: override DNS resolution. Pass `undefined` to restore the default. */
+export declare function _setDnsLookup(fn: DnsLookupFn | undefined): void;
+/**
+ * Reject anything that isn't a public http/https target before the browser
+ * sees it. This guard blocks the direct vectors — non-http(s) schemes, IP
+ * literals, loopback/mDNS names, and names that resolve to a private range
+ * at check time. The rebinding TOCTOU this check alone cannot close (the
+ * browser re-resolves DNS at connect time, and sub-resource fetches never
+ * pass through here) is closed at the connection layer by the chromium
+ * backend's DNS-pinning proxy — see `ssrf-proxy.ts` in computer-use-driver,
+ * on by default. The remote (CDP/Browserless) backend launches its browser
+ * elsewhere, so for that backend this pre-goto guard is still the only
+ * navigate-side control; pin egress at the remote browser's host.
+ */
+export declare function assertSafeNavigationTarget(rawUrl: string): Promise<void>;
+export type CreateNavigateToolOptions = {
+    readonly driver: Driver;
+};
+export declare function createNavigateTool(opts: CreateNavigateToolOptions): RegisteredTool;

package/dist/index.js

@@ -0,0 +1,237 @@
+/**
+ * Catalog R4 `tool-navigate` — Section 25 BROW.
+ *
+ * `Navigate(url)` tool. Drives `driver.goto(url)` so the browser agent
+ * can bootstrap to a starting page. Returns a short text confirmation
+ * the model can read back; surfaces playwright errors verbatim (e.g.
+ * unreachable host, navigation timeout) so the model can recover or
+ * report the failure.
+ *
+ * Flag profile: `destructive: false` (default-allowed). Navigation is
+ * the agent's only bootstrap path — gating it behind an `alwaysAllow`
+ * rule would silently break every spec that doesn't define one. The
+ * §3 permission-engine still applies the user's explicit `alwaysDeny`
+ * rules; Click/Type/Key/Scroll stay destructive-by-default in
+ * `tool-mouse-keyboard`.
+ *
+ * Scope is `"external"` because the URL request crosses a network
+ * boundary. Before handing the URL to the browser we run an SSRF guard
+ * (`assertSafeNavigationTarget`): the model picks this URL and the model
+ * is prompt-injectable, so an attacker who controls any untrusted input
+ * (a channel message, fetched page, MCP result) could otherwise steer it
+ * to `file:///etc/passwd`, `http://169.254.169.254/…` (cloud metadata) or
+ * a loopback admin port and read the result back via `Screenshot`. Output
+ * classification is off — the response is a deterministic short string,
+ * not model-generated content.
+ */
+import { lookup as nodeDnsLookup } from "node:dns/promises";
+import { CrewhausError } from "@crewhaus/errors";
+import { buildTool } from "@crewhaus/tool-builder";
+import { z } from "zod";
+export class NavigateError extends CrewhausError {
+    name = "NavigateError";
+    constructor(message, cause) {
+        super("tool", message, cause);
+    }
+}
+const navigateSchema = z
+    .object({
+    /** Absolute URL to navigate to (http/https). */
+    url: z.string().url(),
+})
+    .strict();
+/** Only real web schemes — blocks file:, gopher:, chrome:, data:, about:, etc. */
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+let dnsLookupFn = nodeDnsLookup;
+/** Test hook: override DNS resolution. Pass `undefined` to restore the default. */
+export function _setDnsLookup(fn) {
+    dnsLookupFn = fn ?? nodeDnsLookup;
+}
+/**
+ * SSRF defenses below mirror `@crewhaus/tool-fetch` (`isPrivateIp` /
+ * `normalizeIpv4`). They are duplicated rather than imported to avoid
+ * coupling the browser bundle to tool-fetch's module-level config state —
+ * keep the copies in sync. The IPv4-mapped IPv6 handling (`::ffff:…`, both
+ * dotted and hex-compressed) is load-bearing: `new URL` normalizes
+ * `http://[::ffff:127.0.0.1]/` to `[::ffff:7f00:1]`, which would otherwise
+ * slip past a naive loopback check.
+ */
+function normalizeIpv4(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return null;
+    const parseComponent = (s) => {
+        if (s === "")
+            return null;
+        let value;
+        if (/^0[xX][0-9a-fA-F]+$/.test(s)) {
+            value = Number.parseInt(s.slice(2), 16);
+        }
+        else if (/^0[0-7]+$/.test(s)) {
+            value = Number.parseInt(s, 8);
+        }
+        else if (/^[0-9]+$/.test(s)) {
+            value = Number.parseInt(s, 10);
+        }
+        else {
+            return null;
+        }
+        return Number.isNaN(value) ? null : value;
+    };
+    const segments = trimmed.split(".");
+    if (segments.length > 4)
+        return null;
+    const components = [];
+    for (const seg of segments) {
+        const value = parseComponent(seg);
+        if (value === null || value < 0)
+            return null;
+        components.push(value);
+    }
+    const n = components.length;
+    const octets = [0, 0, 0, 0];
+    for (let i = 0; i < n - 1; i++) {
+        const c = components[i];
+        if (c > 255)
+            return null;
+        octets[i] = c;
+    }
+    const last = components[n - 1];
+    const maxLast = 2 ** (8 * (4 - (n - 1)));
+    if (last >= maxLast)
+        return null;
+    let rest = last;
+    for (let i = 3; i >= n - 1; i--) {
+        octets[i] = rest & 0xff;
+        rest = Math.floor(rest / 256);
+    }
+    return octets.join(".");
+}
+function isPrivateIp(addr) {
+    const ip = addr.replace(/^\[/, "").replace(/\]$/, "");
+    const lowerIp = ip.toLowerCase();
+    // IPv6 unspecified / loopback / link-local / unique-local
+    if (lowerIp === "::" || lowerIp === "::1")
+        return true;
+    if (lowerIp.startsWith("fe80:"))
+        return true;
+    if (lowerIp.startsWith("fc") || lowerIp.startsWith("fd"))
+        return true;
+    // IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1 / ::ffff:7f00:1) — classify by
+    // the embedded IPv4 address so a mapped literal can't smuggle past.
+    const mapped = lowerIp.match(/^::ffff:(.+)$/);
+    if (mapped) {
+        const tail = mapped[1];
+        if (tail.includes(".")) {
+            return isPrivateIp(tail);
+        }
+        const hexGroups = tail.split(":");
+        if (hexGroups.length === 2 && hexGroups.every((g) => /^[0-9a-f]{1,4}$/.test(g))) {
+            const hi = Number.parseInt(hexGroups[0], 16);
+            const lo = Number.parseInt(hexGroups[1], 16);
+            return isPrivateIp([(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff].join("."));
+        }
+        return false;
+    }
+    // IPv4 — normalise octal/hex/integer literals to dotted-decimal first.
+    const normalized = normalizeIpv4(ip);
+    if (normalized === null)
+        return false;
+    const parts = normalized.split(".").map((p) => Number.parseInt(p, 10));
+    if (parts.length !== 4 || parts.some((nn) => Number.isNaN(nn) || nn < 0 || nn > 255)) {
+        return false;
+    }
+    const [a, b] = parts;
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 10)
+        return true; // 10.0.0.0/8 RFC1918
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local + AWS metadata
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12 RFC1918
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16 RFC1918
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT (RFC6598)
+    if (a === 192 && b === 0 && parts[2] === 0)
+        return true; // 192.0.0.0/24 (RFC6890)
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // 198.18.0.0/15 (RFC2544)
+    if (a === 0)
+        return true; // 0.0.0.0/8
+    return false;
+}
+/**
+ * Reject anything that isn't a public http/https target before the browser
+ * sees it. This guard blocks the direct vectors — non-http(s) schemes, IP
+ * literals, loopback/mDNS names, and names that resolve to a private range
+ * at check time. The rebinding TOCTOU this check alone cannot close (the
+ * browser re-resolves DNS at connect time, and sub-resource fetches never
+ * pass through here) is closed at the connection layer by the chromium
+ * backend's DNS-pinning proxy — see `ssrf-proxy.ts` in computer-use-driver,
+ * on by default. The remote (CDP/Browserless) backend launches its browser
+ * elsewhere, so for that backend this pre-goto guard is still the only
+ * navigate-side control; pin egress at the remote browser's host.
+ */
+export async function assertSafeNavigationTarget(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new NavigateError(`navigation to ${rawUrl} blocked: not a valid absolute URL`);
+    }
+    if (!ALLOWED_SCHEMES.has(url.protocol)) {
+        throw new NavigateError(`navigation to ${rawUrl} blocked: only http/https is allowed (got "${url.protocol}")`);
+    }
+    const hostname = url.hostname.toLowerCase();
+    if (hostname === "localhost" || hostname.endsWith(".localhost")) {
+        throw new NavigateError(`navigation to ${rawUrl} blocked: loopback host`);
+    }
+    if (hostname.endsWith(".local")) {
+        throw new NavigateError(`navigation to ${rawUrl} blocked: mDNS host "${hostname}"`);
+    }
+    const unbracketed = hostname.replace(/^\[/, "").replace(/\]$/, "");
+    if (isPrivateIp(unbracketed)) {
+        throw new NavigateError(`navigation to ${rawUrl} blocked: private/loopback IP`);
+    }
+    // IP literals are their own target — nothing to resolve/rebind.
+    const isIpLiteral = normalizeIpv4(unbracketed) !== null || unbracketed.includes(":");
+    if (isIpLiteral)
+        return;
+    let resolved;
+    try {
+        resolved = await dnsLookupFn(unbracketed);
+    }
+    catch (err) {
+        throw new NavigateError(`navigation to ${rawUrl} blocked: cannot resolve host: ${err.message}`);
+    }
+    if (isPrivateIp(resolved.address)) {
+        throw new NavigateError(`navigation to ${rawUrl} blocked: host resolves to private IP ${resolved.address}`);
+    }
+}
+export function createNavigateTool(opts) {
+    return buildTool({
+        name: "Navigate",
+        description: "Navigate the browser to a URL. Call this first to load a starting page (e.g. a search engine, documentation site, or known landing page) before using Screenshot/FindElement/Click/Type. Returns a short confirmation; pair with Screenshot to see what loaded.",
+        inputSchema: navigateSchema,
+        readOnly: false,
+        destructive: false,
+        concurrencySafe: false,
+        classifyOutput: false,
+        scope: "external",
+        execute: async (input) => {
+            // SSRF guard runs BEFORE the browser touches the URL. Throws
+            // NavigateError directly so the block reason surfaces unwrapped.
+            await assertSafeNavigationTarget(input.url);
+            try {
+                await opts.driver.goto(input.url);
+            }
+            catch (err) {
+                throw new NavigateError(`navigation to ${input.url} failed: ${err.message}`, err);
+            }
+            return [{ type: "text", text: `navigated to ${input.url}` }];
+        },
+    });
+}

package/package.json

@@ -1,21 +1,24 @@
 {
   "name": "@crewhaus/tool-navigate",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Navigate tool — drives driver.goto(url) for the BROW agent (Section 25 BROW)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/computer-use-driver": "0.1.4",
-    "@crewhaus/errors": "0.1.4",
-    "@crewhaus/tool-builder": "0.1.4",
-    "@crewhaus/tool-catalog": "0.1.4",
+    "@crewhaus/computer-use-driver": "0.1.6",
+    "@crewhaus/errors": "0.1.6",
+    "@crewhaus/tool-builder": "0.1.6",
+    "@crewhaus/tool-catalog": "0.1.6",
     "zod": "^3.23.8"
   },
   "license": "Apache-2.0",
@@ -36,5 +39,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,156 +0,0 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import type { Driver } from "@crewhaus/computer-use-driver";
-import { NavigateError, _setDnsLookup, createNavigateTool } from "./index.js";
-
-type GotoRecord = { calls: string[] };
-
-function stubDriver(record: GotoRecord, opts: { gotoErr?: Error } = {}): Driver {
-  return {
-    backend: "chromium",
-    async connect() {},
-    async goto(url: string) {
-      record.calls.push(url);
-      if (opts.gotoErr) throw opts.gotoErr;
-    },
-    async screenshot() {
-      return new Uint8Array(0);
-    },
-    async click() {},
-    async type() {},
-    async key() {},
-    async scroll() {},
-    async getViewport() {
-      return { width: 800, height: 600, devicePixelRatio: 1 };
-    },
-    async disconnect() {},
-  };
-}
-
-describe("createNavigateTool", () => {
-  // A public IP literal skips DNS resolution, keeping these tests hermetic
-  // while still passing the SSRF guard (it's a public, non-loopback address).
-  const PUBLIC_URL = "https://93.184.216.34/";
-
-  test("happy path: forwards url to driver.goto and returns a text confirmation", async () => {
-    const record: GotoRecord = { calls: [] };
-    const tool = createNavigateTool({ driver: stubDriver(record) });
-
-    const result = await tool.execute({ url: PUBLIC_URL }, {});
-    expect(record.calls).toEqual([PUBLIC_URL]);
-    expect(Array.isArray(result)).toBe(true);
-    if (!Array.isArray(result)) throw new Error("expected ToolResultContent array");
-    expect(result).toHaveLength(1);
-    const block = result[0];
-    if (block?.type !== "text") throw new Error("expected text block");
-    expect(block.text).toBe(`navigated to ${PUBLIC_URL}`);
-  });
-
-  test("schema rejects non-URL strings (and missing url)", () => {
-    const record: GotoRecord = { calls: [] };
-    const tool = createNavigateTool({ driver: stubDriver(record) });
-    expect(() => tool.inputSchema.parse({ url: "not-a-url" })).toThrow();
-    expect(() => tool.inputSchema.parse({})).toThrow();
-  });
-
-  test("driver.goto failure surfaces as NavigateError with the URL in the message", async () => {
-    const record: GotoRecord = { calls: [] };
-    const tool = createNavigateTool({
-      driver: stubDriver(record, { gotoErr: new Error("net::ERR_CONNECTION_REFUSED") }),
-    });
-    try {
-      // Public IP literal passes the SSRF guard and reaches driver.goto.
-      await tool.execute({ url: PUBLIC_URL }, {});
-      throw new Error("expected NavigateError to be thrown");
-    } catch (err) {
-      expect(err).toBeInstanceOf(NavigateError);
-      expect((err as Error).message).toContain(PUBLIC_URL);
-      expect((err as Error).message).toContain("net::ERR_CONNECTION_REFUSED");
-    }
-  });
-
-  test("flag profile: default-allowed, external scope, classifier off", () => {
-    const record: GotoRecord = { calls: [] };
-    const tool = createNavigateTool({ driver: stubDriver(record) });
-    // destructive: false → permission-engine allows in default mode.
-    // Navigation is the agent's bootstrap; gating it behind alwaysAllow
-    // would silently break every browser spec without explicit rules.
-    expect(tool.destructive).toBe(false);
-    expect(tool.readOnly).toBe(false);
-    expect(tool.classifyOutput).toBe(false);
-    expect(tool.scope).toBe("external");
-    expect(tool.name).toBe("Navigate");
-  });
-});
-
-// SECURITY: the model picks the navigation URL and is prompt-injectable, so
-// an attacker who controls any untrusted input could steer it to file://,
-// cloud metadata, or a loopback/private host and read the result back via
-// Screenshot. The guard must run before driver.goto.
-describe("Navigate SSRF guard", () => {
-  afterEach(() => _setDnsLookup(undefined));
-
-  const expectBlocked = async (url: string) => {
-    const record: GotoRecord = { calls: [] };
-    const tool = createNavigateTool({ driver: stubDriver(record) });
-    let threw: unknown;
-    try {
-      await tool.execute({ url }, {});
-    } catch (err) {
-      threw = err;
-    }
-    expect(threw).toBeInstanceOf(NavigateError);
-    // The browser must never have been touched.
-    expect(record.calls).toEqual([]);
-  };
-
-  test.each([
-    ["file scheme", "file:///etc/passwd"],
-    ["gopher scheme", "gopher://127.0.0.1:6379/"],
-    ["data scheme", "data:text/html,<h1>x</h1>"],
-    ["loopback IPv4", "http://127.0.0.1/"],
-    ["loopback name", "http://localhost:8080/admin"],
-    ["AWS/GCP metadata", "http://169.254.169.254/latest/meta-data/iam/security-credentials/"],
-    ["RFC1918 10.x", "http://10.0.0.5/"],
-    ["RFC1918 192.168", "http://192.168.1.1/"],
-    ["RFC1918 172.16", "http://172.16.0.1/"],
-    ["CGNAT 100.64", "http://100.64.0.1/"],
-    ["0.0.0.0", "http://0.0.0.0/"],
-    ["IPv6 loopback", "http://[::1]/"],
-    ["IPv4-mapped IPv6 loopback", "http://[::ffff:127.0.0.1]/"],
-    ["IPv4-mapped IPv6 metadata", "http://[::ffff:169.254.169.254]/"],
-    ["octal-encoded loopback", "http://0177.0.0.1/"],
-    ["integer-encoded loopback", "http://2130706433/"],
-    ["mDNS .local", "http://printer.local/"],
-  ])("blocks %s", async (_label, url) => {
-    await expectBlocked(url);
-  });
-
-  test("blocks a public hostname that resolves to a private IP (DNS rebinding at check time)", async () => {
-    _setDnsLookup(async () => ({ address: "127.0.0.1", family: 4 }));
-    const record: GotoRecord = { calls: [] };
-    const tool = createNavigateTool({ driver: stubDriver(record) });
-    await expect(
-      tool.execute({ url: "http://totally-innocent.example/" }, {}),
-    ).rejects.toBeInstanceOf(NavigateError);
-    expect(record.calls).toEqual([]);
-  });
-
-  test("allows a public hostname that resolves to a public IP", async () => {
-    _setDnsLookup(async () => ({ address: "93.184.216.34", family: 4 }));
-    const record: GotoRecord = { calls: [] };
-    const tool = createNavigateTool({ driver: stubDriver(record) });
-    await tool.execute({ url: "http://example.com/" }, {});
-    expect(record.calls).toEqual(["http://example.com/"]);
-  });
-
-  test("allows a public IP literal without any DNS lookup", async () => {
-    // If DNS were consulted for an IP literal this would throw.
-    _setDnsLookup(async () => {
-      throw new Error("DNS must not be called for an IP literal");
-    });
-    const record: GotoRecord = { calls: [] };
-    const tool = createNavigateTool({ driver: stubDriver(record) });
-    await tool.execute({ url: "https://93.184.216.34/" }, {});
-    expect(record.calls).toEqual(["https://93.184.216.34/"]);
-  });
-});

package/src/index.ts

@@ -1,248 +0,0 @@
-/**
- * Catalog R4 `tool-navigate` — Section 25 BROW.
- *
- * `Navigate(url)` tool. Drives `driver.goto(url)` so the browser agent
- * can bootstrap to a starting page. Returns a short text confirmation
- * the model can read back; surfaces playwright errors verbatim (e.g.
- * unreachable host, navigation timeout) so the model can recover or
- * report the failure.
- *
- * Flag profile: `destructive: false` (default-allowed). Navigation is
- * the agent's only bootstrap path — gating it behind an `alwaysAllow`
- * rule would silently break every spec that doesn't define one. The
- * §3 permission-engine still applies the user's explicit `alwaysDeny`
- * rules; Click/Type/Key/Scroll stay destructive-by-default in
- * `tool-mouse-keyboard`.
- *
- * Scope is `"external"` because the URL request crosses a network
- * boundary. Before handing the URL to the browser we run an SSRF guard
- * (`assertSafeNavigationTarget`): the model picks this URL and the model
- * is prompt-injectable, so an attacker who controls any untrusted input
- * (a channel message, fetched page, MCP result) could otherwise steer it
- * to `file:///etc/passwd`, `http://169.254.169.254/…` (cloud metadata) or
- * a loopback admin port and read the result back via `Screenshot`. Output
- * classification is off — the response is a deterministic short string,
- * not model-generated content.
- */
-import { lookup as nodeDnsLookup } from "node:dns/promises";
-import type { Driver } from "@crewhaus/computer-use-driver";
-import { CrewhausError } from "@crewhaus/errors";
-import { buildTool } from "@crewhaus/tool-builder";
-import type { RegisteredTool, ToolResultContent } from "@crewhaus/tool-catalog";
-import { z } from "zod";
-
-export class NavigateError extends CrewhausError {
-  override readonly name = "NavigateError";
-  constructor(message: string, cause?: unknown) {
-    super("tool", message, cause);
-  }
-}
-
-const navigateSchema = z
-  .object({
-    /** Absolute URL to navigate to (http/https). */
-    url: z.string().url(),
-  })
-  .strict();
-
-/** Only real web schemes — blocks file:, gopher:, chrome:, data:, about:, etc. */
-const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
-
-export type DnsLookupFn = (
-  hostname: string,
-) => Promise<{ readonly address: string; readonly family: number }>;
-
-let dnsLookupFn: DnsLookupFn = nodeDnsLookup;
-
-/** Test hook: override DNS resolution. Pass `undefined` to restore the default. */
-export function _setDnsLookup(fn: DnsLookupFn | undefined): void {
-  dnsLookupFn = fn ?? nodeDnsLookup;
-}
-
-/**
- * SSRF defenses below mirror `@crewhaus/tool-fetch` (`isPrivateIp` /
- * `normalizeIpv4`). They are duplicated rather than imported to avoid
- * coupling the browser bundle to tool-fetch's module-level config state —
- * keep the copies in sync. The IPv4-mapped IPv6 handling (`::ffff:…`, both
- * dotted and hex-compressed) is load-bearing: `new URL` normalizes
- * `http://[::ffff:127.0.0.1]/` to `[::ffff:7f00:1]`, which would otherwise
- * slip past a naive loopback check.
- */
-function normalizeIpv4(raw: string): string | null {
-  const trimmed = raw.trim();
-  if (trimmed === "") return null;
-
-  const parseComponent = (s: string): number | null => {
-    if (s === "") return null;
-    let value: number;
-    if (/^0[xX][0-9a-fA-F]+$/.test(s)) {
-      value = Number.parseInt(s.slice(2), 16);
-    } else if (/^0[0-7]+$/.test(s)) {
-      value = Number.parseInt(s, 8);
-    } else if (/^[0-9]+$/.test(s)) {
-      value = Number.parseInt(s, 10);
-    } else {
-      return null;
-    }
-    return Number.isNaN(value) ? null : value;
-  };
-
-  const segments = trimmed.split(".");
-  if (segments.length > 4) return null;
-
-  const components: number[] = [];
-  for (const seg of segments) {
-    const value = parseComponent(seg);
-    if (value === null || value < 0) return null;
-    components.push(value);
-  }
-
-  const n = components.length;
-  const octets = [0, 0, 0, 0];
-  for (let i = 0; i < n - 1; i++) {
-    const c = components[i] as number;
-    if (c > 255) return null;
-    octets[i] = c;
-  }
-  const last = components[n - 1] as number;
-  const maxLast = 2 ** (8 * (4 - (n - 1)));
-  if (last >= maxLast) return null;
-  let rest = last;
-  for (let i = 3; i >= n - 1; i--) {
-    octets[i] = rest & 0xff;
-    rest = Math.floor(rest / 256);
-  }
-  return octets.join(".");
-}
-
-function isPrivateIp(addr: string): boolean {
-  const ip = addr.replace(/^\[/, "").replace(/\]$/, "");
-  const lowerIp = ip.toLowerCase();
-
-  // IPv6 unspecified / loopback / link-local / unique-local
-  if (lowerIp === "::" || lowerIp === "::1") return true;
-  if (lowerIp.startsWith("fe80:")) return true;
-  if (lowerIp.startsWith("fc") || lowerIp.startsWith("fd")) return true;
-
-  // IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1 / ::ffff:7f00:1) — classify by
-  // the embedded IPv4 address so a mapped literal can't smuggle past.
-  const mapped = lowerIp.match(/^::ffff:(.+)$/);
-  if (mapped) {
-    const tail = mapped[1] as string;
-    if (tail.includes(".")) {
-      return isPrivateIp(tail);
-    }
-    const hexGroups = tail.split(":");
-    if (hexGroups.length === 2 && hexGroups.every((g) => /^[0-9a-f]{1,4}$/.test(g))) {
-      const hi = Number.parseInt(hexGroups[0] as string, 16);
-      const lo = Number.parseInt(hexGroups[1] as string, 16);
-      return isPrivateIp([(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff].join("."));
-    }
-    return false;
-  }
-
-  // IPv4 — normalise octal/hex/integer literals to dotted-decimal first.
-  const normalized = normalizeIpv4(ip);
-  if (normalized === null) return false;
-  const parts = normalized.split(".").map((p) => Number.parseInt(p, 10));
-  if (parts.length !== 4 || parts.some((nn) => Number.isNaN(nn) || nn < 0 || nn > 255)) {
-    return false;
-  }
-  const [a, b] = parts as [number, number, number, number];
-
-  if (a === 127) return true; // 127.0.0.0/8 loopback
-  if (a === 10) return true; // 10.0.0.0/8 RFC1918
-  if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local + AWS metadata
-  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12 RFC1918
-  if (a === 192 && b === 168) return true; // 192.168.0.0/16 RFC1918
-  if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 CGNAT (RFC6598)
-  if (a === 192 && b === 0 && parts[2] === 0) return true; // 192.0.0.0/24 (RFC6890)
-  if (a === 198 && (b === 18 || b === 19)) return true; // 198.18.0.0/15 (RFC2544)
-  if (a === 0) return true; // 0.0.0.0/8
-  return false;
-}
-
-/**
- * Reject anything that isn't a public http/https target before the browser
- * sees it. This guard blocks the direct vectors — non-http(s) schemes, IP
- * literals, loopback/mDNS names, and names that resolve to a private range
- * at check time. The rebinding TOCTOU this check alone cannot close (the
- * browser re-resolves DNS at connect time, and sub-resource fetches never
- * pass through here) is closed at the connection layer by the chromium
- * backend's DNS-pinning proxy — see `ssrf-proxy.ts` in computer-use-driver,
- * on by default. The remote (CDP/Browserless) backend launches its browser
- * elsewhere, so for that backend this pre-goto guard is still the only
- * navigate-side control; pin egress at the remote browser's host.
- */
-export async function assertSafeNavigationTarget(rawUrl: string): Promise<void> {
-  let url: URL;
-  try {
-    url = new URL(rawUrl);
-  } catch {
-    throw new NavigateError(`navigation to ${rawUrl} blocked: not a valid absolute URL`);
-  }
-  if (!ALLOWED_SCHEMES.has(url.protocol)) {
-    throw new NavigateError(
-      `navigation to ${rawUrl} blocked: only http/https is allowed (got "${url.protocol}")`,
-    );
-  }
-  const hostname = url.hostname.toLowerCase();
-  if (hostname === "localhost" || hostname.endsWith(".localhost")) {
-    throw new NavigateError(`navigation to ${rawUrl} blocked: loopback host`);
-  }
-  if (hostname.endsWith(".local")) {
-    throw new NavigateError(`navigation to ${rawUrl} blocked: mDNS host "${hostname}"`);
-  }
-  const unbracketed = hostname.replace(/^\[/, "").replace(/\]$/, "");
-  if (isPrivateIp(unbracketed)) {
-    throw new NavigateError(`navigation to ${rawUrl} blocked: private/loopback IP`);
-  }
-  // IP literals are their own target — nothing to resolve/rebind.
-  const isIpLiteral = normalizeIpv4(unbracketed) !== null || unbracketed.includes(":");
-  if (isIpLiteral) return;
-  let resolved: { readonly address: string };
-  try {
-    resolved = await dnsLookupFn(unbracketed);
-  } catch (err) {
-    throw new NavigateError(
-      `navigation to ${rawUrl} blocked: cannot resolve host: ${(err as Error).message}`,
-    );
-  }
-  if (isPrivateIp(resolved.address)) {
-    throw new NavigateError(
-      `navigation to ${rawUrl} blocked: host resolves to private IP ${resolved.address}`,
-    );
-  }
-}
-
-export type CreateNavigateToolOptions = {
-  readonly driver: Driver;
-};
-
-export function createNavigateTool(opts: CreateNavigateToolOptions): RegisteredTool {
-  return buildTool({
-    name: "Navigate",
-    description:
-      "Navigate the browser to a URL. Call this first to load a starting page (e.g. a search engine, documentation site, or known landing page) before using Screenshot/FindElement/Click/Type. Returns a short confirmation; pair with Screenshot to see what loaded.",
-    inputSchema: navigateSchema,
-    readOnly: false,
-    destructive: false,
-    concurrencySafe: false,
-    classifyOutput: false,
-    scope: "external",
-    execute: async (input): Promise<ToolResultContent> => {
-      // SSRF guard runs BEFORE the browser touches the URL. Throws
-      // NavigateError directly so the block reason surfaces unwrapped.
-      await assertSafeNavigationTarget(input.url);
-      try {
-        await opts.driver.goto(input.url);
-      } catch (err) {
-        throw new NavigateError(
-          `navigation to ${input.url} failed: ${(err as Error).message}`,
-          err,
-        );
-      }
-      return [{ type: "text", text: `navigated to ${input.url}` }];
-    },
-  });
-}