browserclaw 0.3.4 → 0.3.6

package/dist/index.d.cts

@@ -9,10 +9,19 @@ interface FrameEvalResult {
 
 /**
  * Policy for controlling which URLs browser navigation is allowed to reach.
- * By default all private/internal addresses are blocked to prevent SSRF attacks.
+ * Defaults to trusted-network mode (private/internal addresses allowed).
+ * Set `dangerouslyAllowPrivateNetwork: false` to enforce strict public-only checks.
  */
 interface SsrfPolicy {
-    /** Allow navigation to private/internal network addresses. Default: `false` */
+    /**
+     * Allow navigation to private/internal network addresses.
+     * Default: `true` (trusted-network mode). Set to `false` for strict public-only enforcement.
+     */
+    dangerouslyAllowPrivateNetwork?: boolean;
+    /**
+     * Allow navigation to private/internal network addresses.
+     * @deprecated Use `dangerouslyAllowPrivateNetwork` instead.
+     */
     allowPrivateNetwork?: boolean;
     /** Hostnames explicitly allowed even if they resolve to private addresses */
     allowedHostnames?: string[];
@@ -48,12 +57,13 @@ interface LaunchOptions {
     chromeArgs?: string[];
     /**
      * SSRF policy controlling which URLs navigation is allowed to reach.
-     * By default all private/internal addresses are blocked.
+     * Defaults to trusted-network mode (private/internal addresses allowed).
+     * Set `dangerouslyAllowPrivateNetwork: false` to enforce strict public-only checks.
      */
     ssrfPolicy?: SsrfPolicy;
     /**
      * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
-     * @deprecated Use `ssrfPolicy: { allowPrivateNetwork: true }` instead.
+     * @deprecated Use `ssrfPolicy: { dangerouslyAllowPrivateNetwork: true }` instead.
      */
     allowInternal?: boolean;
 }
@@ -61,12 +71,13 @@ interface LaunchOptions {
 interface ConnectOptions {
     /**
      * SSRF policy controlling which URLs navigation is allowed to reach.
-     * By default all private/internal addresses are blocked.
+     * Defaults to trusted-network mode (private/internal addresses allowed).
+     * Set `dangerouslyAllowPrivateNetwork: false` to enforce strict public-only checks.
      */
     ssrfPolicy?: SsrfPolicy;
     /**
      * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
-     * @deprecated Use `ssrfPolicy: { allowPrivateNetwork: true }` instead.
+     * @deprecated Use `ssrfPolicy: { dangerouslyAllowPrivateNetwork: true }` instead.
      */
     allowInternal?: boolean;
     /**

package/dist/index.d.ts

@@ -9,10 +9,19 @@ interface FrameEvalResult {
 
 /**
  * Policy for controlling which URLs browser navigation is allowed to reach.
- * By default all private/internal addresses are blocked to prevent SSRF attacks.
+ * Defaults to trusted-network mode (private/internal addresses allowed).
+ * Set `dangerouslyAllowPrivateNetwork: false` to enforce strict public-only checks.
  */
 interface SsrfPolicy {
-    /** Allow navigation to private/internal network addresses. Default: `false` */
+    /**
+     * Allow navigation to private/internal network addresses.
+     * Default: `true` (trusted-network mode). Set to `false` for strict public-only enforcement.
+     */
+    dangerouslyAllowPrivateNetwork?: boolean;
+    /**
+     * Allow navigation to private/internal network addresses.
+     * @deprecated Use `dangerouslyAllowPrivateNetwork` instead.
+     */
     allowPrivateNetwork?: boolean;
     /** Hostnames explicitly allowed even if they resolve to private addresses */
     allowedHostnames?: string[];
@@ -48,12 +57,13 @@ interface LaunchOptions {
     chromeArgs?: string[];
     /**
      * SSRF policy controlling which URLs navigation is allowed to reach.
-     * By default all private/internal addresses are blocked.
+     * Defaults to trusted-network mode (private/internal addresses allowed).
+     * Set `dangerouslyAllowPrivateNetwork: false` to enforce strict public-only checks.
      */
     ssrfPolicy?: SsrfPolicy;
     /**
      * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
-     * @deprecated Use `ssrfPolicy: { allowPrivateNetwork: true }` instead.
+     * @deprecated Use `ssrfPolicy: { dangerouslyAllowPrivateNetwork: true }` instead.
      */
     allowInternal?: boolean;
 }
@@ -61,12 +71,13 @@ interface LaunchOptions {
 interface ConnectOptions {
     /**
      * SSRF policy controlling which URLs navigation is allowed to reach.
-     * By default all private/internal addresses are blocked.
+     * Defaults to trusted-network mode (private/internal addresses allowed).
+     * Set `dangerouslyAllowPrivateNetwork: false` to enforce strict public-only checks.
      */
     ssrfPolicy?: SsrfPolicy;
     /**
      * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
-     * @deprecated Use `ssrfPolicy: { allowPrivateNetwork: true }` instead.
+     * @deprecated Use `ssrfPolicy: { dangerouslyAllowPrivateNetwork: true }` instead.
      */
     allowInternal?: boolean;
     /**

package/dist/index.js

@@ -346,7 +346,9 @@ async function isChromeReachable(cdpUrl, timeoutMs = 500, authToken) {
     const headers = {};
     if (authToken) headers["Authorization"] = `Bearer ${authToken}`;
     const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal, headers });
-    return res.ok;
+    if (!res.ok) return false;
+    const data = await res.json();
+    return data != null && typeof data === "object";
   } catch {
     return false;
   } finally {
@@ -362,6 +364,7 @@ async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500, authToken) {
     const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal, headers });
     if (!res.ok) return null;
     const data = await res.json();
+    if (!data || typeof data !== "object") return null;
     return String(data?.webSocketDebuggerUrl ?? "").trim() || null;
   } catch {
     return null;
@@ -1403,7 +1406,7 @@ async function assertBrowserNavigationAllowed(opts) {
     throw new InvalidBrowserNavigationUrlError(`Navigation blocked: unsupported protocol "${parsed.protocol}"`);
   }
   const policy = opts.ssrfPolicy;
-  if (policy?.allowPrivateNetwork) return;
+  if (policy?.dangerouslyAllowPrivateNetwork ?? policy?.allowPrivateNetwork ?? true) return;
   const allowedHostnames = [
     ...policy?.allowedHostnames ?? [],
     ...policy?.hostnameAllowlist ?? []
@@ -1414,7 +1417,7 @@ async function assertBrowserNavigationAllowed(opts) {
   }
   if (await isInternalUrlResolved(rawUrl, opts.lookupFn)) {
     throw new InvalidBrowserNavigationUrlError(
-      `Navigation to internal/loopback address blocked: "${rawUrl}". Use ssrfPolicy: { allowPrivateNetwork: true } if this is intentional.`
+      `Navigation to internal/loopback address blocked: "${rawUrl}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
     );
   }
 }
@@ -1561,7 +1564,7 @@ async function isInternalUrlResolved(url, lookupFn = lookup) {
 async function navigateViaPlaywright(opts) {
   const url = String(opts.url ?? "").trim();
   if (!url) throw new Error("url is required");
-  const policy = opts.allowInternal ? { ...opts.ssrfPolicy, allowPrivateNetwork: true } : opts.ssrfPolicy;
+  const policy = opts.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
   await assertBrowserNavigationAllowed({ url, ssrfPolicy: policy });
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
@@ -1586,7 +1589,7 @@ async function listPagesViaPlaywright(opts) {
 async function createPageViaPlaywright(opts) {
   const targetUrl = (opts.url ?? "").trim() || "about:blank";
   if (targetUrl !== "about:blank") {
-    const policy = opts.allowInternal ? { ...opts.ssrfPolicy, allowPrivateNetwork: true } : opts.ssrfPolicy;
+    const policy = opts.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
     await assertBrowserNavigationAllowed({ url: targetUrl, ssrfPolicy: policy });
   }
   const { browser } = await connectBrowser(opts.cdpUrl);
@@ -3010,7 +3013,7 @@ var BrowserClaw = class _BrowserClaw {
   static async launch(opts = {}) {
     const chrome = await launchChrome(opts);
     const cdpUrl = `http://127.0.0.1:${chrome.cdpPort}`;
-    const ssrfPolicy = opts.allowInternal ? { ...opts.ssrfPolicy, allowPrivateNetwork: true } : opts.ssrfPolicy;
+    const ssrfPolicy = opts.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
     return new _BrowserClaw(cdpUrl, chrome, ssrfPolicy);
   }
   /**
@@ -3032,7 +3035,7 @@ var BrowserClaw = class _BrowserClaw {
       throw new Error(`Cannot connect to Chrome at ${cdpUrl}. Is Chrome running with --remote-debugging-port?`);
     }
     await connectBrowser(cdpUrl, opts?.authToken);
-    const ssrfPolicy = opts?.allowInternal ? { ...opts.ssrfPolicy, allowPrivateNetwork: true } : opts?.ssrfPolicy;
+    const ssrfPolicy = opts?.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts?.ssrfPolicy;
     return new _BrowserClaw(cdpUrl, null, ssrfPolicy);
   }
   /**