@crewhaus/tool-navigate 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -23,8 +23,24 @@ export declare function _setDnsLookup(fn: DnsLookupFn | undefined): void;
  * 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 declare function assertSafeNavigationTarget(rawUrl: string, opts?: {
+    readonly allowPrivateTargets?: boolean;
+}): Promise<void>;
 export type CreateNavigateToolOptions = {
     readonly driver: Driver;
+    /**
+     * SECURITY — spec `driver.allowPrivateTargets: true`. Waives ONLY the
+     * private/loopback/mDNS host checks, for a harness whose whole job is a
+     * private target the operator controls: an intranet app under test, or a
+     * locally-served fixture page. The scheme allowlist is never waived, so an
+     * opted-in spec still cannot reach `file:`/`data:`/`chrome:`.
+     *
+     * Default false, and a per-spec compile-time decision — there is
+     * deliberately no env var or global switch, so it cannot be turned on by an
+     * ambient misconfiguration, and a reviewer sees it in the spec diff. The
+     * chromium backend drops its DNS-pinning proxy under the same flag, so the
+     * two layers agree instead of one silently 403ing what the other allowed.
+     */
+    readonly allowPrivateTargets?: boolean;
 };
 export declare function createNavigateTool(opts: CreateNavigateToolOptions): RegisteredTool;

package/dist/index.js

@@ -174,7 +174,7 @@ function isPrivateIp(addr) {
  * 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) {
+export async function assertSafeNavigationTarget(rawUrl, opts = {}) {
     let url;
     try {
         url = new URL(rawUrl);
@@ -185,6 +185,8 @@ export async function assertSafeNavigationTarget(rawUrl) {
     if (!ALLOWED_SCHEMES.has(url.protocol)) {
         throw new NavigateError(`navigation to ${rawUrl} blocked: only http/https is allowed (got "${url.protocol}")`);
     }
+    if (opts.allowPrivateTargets === true)
+        return;
     const hostname = url.hostname.toLowerCase();
     if (hostname === "localhost" || hostname.endsWith(".localhost")) {
         throw new NavigateError(`navigation to ${rawUrl} blocked: loopback host`);
@@ -224,7 +226,9 @@ export function createNavigateTool(opts) {
         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);
+            await assertSafeNavigationTarget(input.url, {
+                allowPrivateTargets: opts.allowPrivateTargets === true,
+            });
             try {
                 await opts.driver.goto(input.url);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-navigate",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Navigate tool — drives driver.goto(url) for the BROW agent (Section 25 BROW)",
   "main": "dist/index.js",
@@ -15,10 +15,10 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/computer-use-driver": "0.4.0",
-    "@crewhaus/errors": "0.4.0",
-    "@crewhaus/tool-builder": "0.4.0",
-    "@crewhaus/tool-catalog": "0.4.0",
+    "@crewhaus/computer-use-driver": "0.5.0",
+    "@crewhaus/errors": "0.5.0",
+    "@crewhaus/tool-builder": "0.5.0",
+    "@crewhaus/tool-catalog": "0.5.0",
     "zod": "^3.23.8"
   },
   "license": "Apache-2.0",