browserclaw 0.2.7 → 0.2.9

package/dist/index.d.cts

@@ -6,6 +6,18 @@ interface FrameEvalResult {
     result: unknown;
 }
 
+/**
+ * Policy for controlling which URLs browser navigation is allowed to reach.
+ * By default all private/internal addresses are blocked to prevent SSRF attacks.
+ */
+interface SsrfPolicy {
+    /** Allow navigation to private/internal network addresses. Default: `false` */
+    allowPrivateNetwork?: boolean;
+    /** Hostnames explicitly allowed even if they resolve to private addresses */
+    allowedHostnames?: string[];
+    /** Alias for allowedHostnames */
+    hostnameAllowlist?: string[];
+}
 /** Supported browser types that can be detected and launched. */
 type ChromeKind = 'chrome' | 'brave' | 'edge' | 'chromium' | 'canary' | 'custom';
 /** A detected browser executable on the system. */
@@ -33,19 +45,27 @@ interface LaunchOptions {
     profileColor?: string;
     /** Additional Chrome command-line arguments (e.g. `['--start-maximized']`). */
     chromeArgs?: string[];
+    /**
+     * SSRF policy controlling which URLs navigation is allowed to reach.
+     * By default all private/internal addresses are blocked.
+     */
+    ssrfPolicy?: SsrfPolicy;
     /**
      * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
-     * Default: `false` — internal URLs are blocked to prevent SSRF attacks.
-     * Set to `true` if you need to access local development servers.
+     * @deprecated Use `ssrfPolicy: { allowPrivateNetwork: true }` instead.
      */
     allowInternal?: boolean;
 }
 /** Options for connecting to an existing browser instance. */
 interface ConnectOptions {
+    /**
+     * SSRF policy controlling which URLs navigation is allowed to reach.
+     * By default all private/internal addresses are blocked.
+     */
+    ssrfPolicy?: SsrfPolicy;
     /**
      * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
-     * Default: `false` — internal URLs are blocked to prevent SSRF attacks.
-     * Set to `true` if you need to access local development servers.
+     * @deprecated Use `ssrfPolicy: { allowPrivateNetwork: true }` instead.
      */
     allowInternal?: boolean;
     /**
@@ -390,9 +410,9 @@ interface HttpCredentials {
 declare class CrawlPage {
     private readonly cdpUrl;
     private readonly targetId;
-    private readonly allowInternal;
+    private readonly ssrfPolicy;
     /** @internal */
-    constructor(cdpUrl: string, targetId: string, allowInternal?: boolean);
+    constructor(cdpUrl: string, targetId: string, ssrfPolicy?: SsrfPolicy);
     /** The CDP target ID for this page. Use this to identify the page in multi-tab scenarios. */
     get id(): string;
     /**
@@ -987,7 +1007,7 @@ declare class CrawlPage {
  */
 declare class BrowserClaw {
     private readonly cdpUrl;
-    private readonly allowInternal;
+    private readonly ssrfPolicy;
     private chrome;
     private constructor();
     /**
@@ -1087,4 +1107,19 @@ declare class BrowserClaw {
     stop(): Promise<void>;
 }
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, type LaunchOptions, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions };
+/**
+ * Thrown when a navigation URL is blocked by SSRF policy.
+ * Callers can catch this specifically to distinguish navigation blocks
+ * from other errors.
+ */
+declare class InvalidBrowserNavigationUrlError extends Error {
+    constructor(message: string);
+}
+/** Options for browser navigation SSRF policy. */
+type BrowserNavigationPolicyOptions = {
+    ssrfPolicy?: SsrfPolicy;
+};
+/** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
+declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
+
+export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, withBrowserNavigationPolicy };

package/dist/index.d.ts

@@ -6,6 +6,18 @@ interface FrameEvalResult {
     result: unknown;
 }
 
+/**
+ * Policy for controlling which URLs browser navigation is allowed to reach.
+ * By default all private/internal addresses are blocked to prevent SSRF attacks.
+ */
+interface SsrfPolicy {
+    /** Allow navigation to private/internal network addresses. Default: `false` */
+    allowPrivateNetwork?: boolean;
+    /** Hostnames explicitly allowed even if they resolve to private addresses */
+    allowedHostnames?: string[];
+    /** Alias for allowedHostnames */
+    hostnameAllowlist?: string[];
+}
 /** Supported browser types that can be detected and launched. */
 type ChromeKind = 'chrome' | 'brave' | 'edge' | 'chromium' | 'canary' | 'custom';
 /** A detected browser executable on the system. */
@@ -33,19 +45,27 @@ interface LaunchOptions {
     profileColor?: string;
     /** Additional Chrome command-line arguments (e.g. `['--start-maximized']`). */
     chromeArgs?: string[];
+    /**
+     * SSRF policy controlling which URLs navigation is allowed to reach.
+     * By default all private/internal addresses are blocked.
+     */
+    ssrfPolicy?: SsrfPolicy;
     /**
      * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
-     * Default: `false` — internal URLs are blocked to prevent SSRF attacks.
-     * Set to `true` if you need to access local development servers.
+     * @deprecated Use `ssrfPolicy: { allowPrivateNetwork: true }` instead.
      */
     allowInternal?: boolean;
 }
 /** Options for connecting to an existing browser instance. */
 interface ConnectOptions {
+    /**
+     * SSRF policy controlling which URLs navigation is allowed to reach.
+     * By default all private/internal addresses are blocked.
+     */
+    ssrfPolicy?: SsrfPolicy;
     /**
      * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
-     * Default: `false` — internal URLs are blocked to prevent SSRF attacks.
-     * Set to `true` if you need to access local development servers.
+     * @deprecated Use `ssrfPolicy: { allowPrivateNetwork: true }` instead.
      */
     allowInternal?: boolean;
     /**
@@ -390,9 +410,9 @@ interface HttpCredentials {
 declare class CrawlPage {
     private readonly cdpUrl;
     private readonly targetId;
-    private readonly allowInternal;
+    private readonly ssrfPolicy;
     /** @internal */
-    constructor(cdpUrl: string, targetId: string, allowInternal?: boolean);
+    constructor(cdpUrl: string, targetId: string, ssrfPolicy?: SsrfPolicy);
     /** The CDP target ID for this page. Use this to identify the page in multi-tab scenarios. */
     get id(): string;
     /**
@@ -987,7 +1007,7 @@ declare class CrawlPage {
  */
 declare class BrowserClaw {
     private readonly cdpUrl;
-    private readonly allowInternal;
+    private readonly ssrfPolicy;
     private chrome;
     private constructor();
     /**
@@ -1087,4 +1107,19 @@ declare class BrowserClaw {
     stop(): Promise<void>;
 }
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, type LaunchOptions, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions };
+/**
+ * Thrown when a navigation URL is blocked by SSRF policy.
+ * Callers can catch this specifically to distinguish navigation blocks
+ * from other errors.
+ */
+declare class InvalidBrowserNavigationUrlError extends Error {
+    constructor(message: string);
+}
+/** Options for browser navigation SSRF policy. */
+type BrowserNavigationPolicyOptions = {
+    ssrfPolicy?: SsrfPolicy;
+};
+/** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
+declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
+
+export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, withBrowserNavigationPolicy };

package/dist/index.js

@@ -1378,6 +1378,38 @@ async function pressKeyViaPlaywright(opts) {
   ensurePageState(page);
   await page.keyboard.press(key, { delay: Math.max(0, Math.floor(opts.delayMs ?? 0)) });
 }
+var InvalidBrowserNavigationUrlError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidBrowserNavigationUrlError";
+  }
+};
+function withBrowserNavigationPolicy(ssrfPolicy) {
+  return { ssrfPolicy };
+}
+async function assertBrowserNavigationAllowed(opts) {
+  const policy = opts.ssrfPolicy;
+  if (policy?.allowPrivateNetwork) return;
+  const allowedHostnames = [
+    ...policy?.allowedHostnames ?? [],
+    ...policy?.hostnameAllowlist ?? []
+  ];
+  if (allowedHostnames.length) {
+    let parsed;
+    try {
+      parsed = new URL(opts.url);
+    } catch {
+      throw new InvalidBrowserNavigationUrlError(`Invalid URL: "${opts.url}"`);
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (allowedHostnames.some((h) => h.toLowerCase() === hostname)) return;
+  }
+  if (await isInternalUrlResolved(opts.url)) {
+    throw new InvalidBrowserNavigationUrlError(
+      `Navigation to internal/loopback address blocked: "${opts.url}". Use ssrfPolicy: { allowPrivateNetwork: true } if this is intentional.`
+    );
+  }
+}
 function assertSafeOutputPath(path2, allowedRoots) {
   if (!path2 || typeof path2 !== "string") {
     throw new Error("Output path is required.");
@@ -1521,9 +1553,8 @@ async function isInternalUrlResolved(url) {
 async function navigateViaPlaywright(opts) {
   const url = String(opts.url ?? "").trim();
   if (!url) throw new Error("url is required");
-  if (!opts.allowInternal && await isInternalUrlResolved(url)) {
-    throw new Error(`Navigation to internal/loopback address blocked: "${url}". Set allowInternal: true if this is intentional.`);
-  }
+  const policy = opts.allowInternal ? { ...opts.ssrfPolicy, allowPrivateNetwork: true } : opts.ssrfPolicy;
+  await assertBrowserNavigationAllowed({ url, ssrfPolicy: policy });
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   await page.goto(url, { timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4) });
@@ -1546,8 +1577,9 @@ async function listPagesViaPlaywright(opts) {
 }
 async function createPageViaPlaywright(opts) {
   const targetUrl = (opts.url ?? "").trim() || "about:blank";
-  if (targetUrl !== "about:blank" && !opts.allowInternal && await isInternalUrlResolved(targetUrl)) {
-    throw new Error(`Navigation to internal/loopback address blocked: "${targetUrl}". Set allowInternal: true if this is intentional.`);
+  if (targetUrl !== "about:blank") {
+    const policy = opts.allowInternal ? { ...opts.ssrfPolicy, allowPrivateNetwork: true } : opts.ssrfPolicy;
+    await assertBrowserNavigationAllowed({ url: targetUrl, ssrfPolicy: policy });
   }
   const { browser } = await connectBrowser(opts.cdpUrl);
   const context = browser.contexts()[0] ?? await browser.newContext();
@@ -2055,12 +2087,12 @@ async function storageClearViaPlaywright(opts) {
 var CrawlPage = class {
   cdpUrl;
   targetId;
-  allowInternal;
+  ssrfPolicy;
   /** @internal */
-  constructor(cdpUrl, targetId, allowInternal = false) {
+  constructor(cdpUrl, targetId, ssrfPolicy) {
     this.cdpUrl = cdpUrl;
     this.targetId = targetId;
-    this.allowInternal = allowInternal;
+    this.ssrfPolicy = ssrfPolicy;
   }
   /** The CDP target ID for this page. Use this to identify the page in multi-tab scenarios. */
   get id() {
@@ -2393,7 +2425,7 @@ var CrawlPage = class {
       targetId: this.targetId,
       url,
       timeoutMs: opts?.timeoutMs,
-      allowInternal: this.allowInternal
+      ssrfPolicy: this.ssrfPolicy
     });
   }
   /**
@@ -2923,12 +2955,12 @@ var CrawlPage = class {
 };
 var BrowserClaw = class _BrowserClaw {
   cdpUrl;
-  allowInternal;
+  ssrfPolicy;
   chrome;
-  constructor(cdpUrl, chrome, allowInternal = false) {
+  constructor(cdpUrl, chrome, ssrfPolicy) {
     this.cdpUrl = cdpUrl;
     this.chrome = chrome;
-    this.allowInternal = allowInternal;
+    this.ssrfPolicy = ssrfPolicy;
   }
   /**
    * Launch a new Chrome instance and connect to it.
@@ -2956,7 +2988,8 @@ var BrowserClaw = class _BrowserClaw {
   static async launch(opts = {}) {
     const chrome = await launchChrome(opts);
     const cdpUrl = `http://127.0.0.1:${chrome.cdpPort}`;
-    return new _BrowserClaw(cdpUrl, chrome, opts.allowInternal);
+    const ssrfPolicy = opts.allowInternal ? { ...opts.ssrfPolicy, allowPrivateNetwork: true } : opts.ssrfPolicy;
+    return new _BrowserClaw(cdpUrl, chrome, ssrfPolicy);
   }
   /**
    * Connect to an already-running Chrome instance via its CDP endpoint.
@@ -2977,7 +3010,8 @@ 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);
-    return new _BrowserClaw(cdpUrl, null, opts?.allowInternal);
+    const ssrfPolicy = opts?.allowInternal ? { ...opts.ssrfPolicy, allowPrivateNetwork: true } : opts?.ssrfPolicy;
+    return new _BrowserClaw(cdpUrl, null, ssrfPolicy);
   }
   /**
    * Open a URL in a new tab and return the page handle.
@@ -2992,8 +3026,8 @@ var BrowserClaw = class _BrowserClaw {
    * ```
    */
   async open(url) {
-    const tab = await createPageViaPlaywright({ cdpUrl: this.cdpUrl, url, allowInternal: this.allowInternal });
-    return new CrawlPage(this.cdpUrl, tab.targetId, this.allowInternal);
+    const tab = await createPageViaPlaywright({ cdpUrl: this.cdpUrl, url, ssrfPolicy: this.ssrfPolicy });
+    return new CrawlPage(this.cdpUrl, tab.targetId, this.ssrfPolicy);
   }
   /**
    * Get a CrawlPage handle for the currently active tab.
@@ -3006,7 +3040,7 @@ var BrowserClaw = class _BrowserClaw {
     if (!pages.length) throw new Error("No pages available. Use browser.open(url) to create a tab.");
     const tid = await pageTargetId(pages[0]).catch(() => null);
     if (!tid) throw new Error("Failed to get targetId for the current page.");
-    return new CrawlPage(this.cdpUrl, tid, this.allowInternal);
+    return new CrawlPage(this.cdpUrl, tid, this.ssrfPolicy);
   }
   /**
    * List all open tabs.
@@ -3041,7 +3075,7 @@ var BrowserClaw = class _BrowserClaw {
    * @returns CrawlPage for the specified tab
    */
   page(targetId) {
-    return new CrawlPage(this.cdpUrl, targetId, this.allowInternal);
+    return new CrawlPage(this.cdpUrl, targetId, this.ssrfPolicy);
   }
   /** The CDP endpoint URL for this browser connection. */
   get url() {
@@ -3063,6 +3097,6 @@ var BrowserClaw = class _BrowserClaw {
   }
 };
 
-export { BrowserClaw, CrawlPage };
+export { BrowserClaw, CrawlPage, InvalidBrowserNavigationUrlError, withBrowserNavigationPolicy };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map