browserclaw 0.2.8 → 0.3.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import * as playwright_core from 'playwright-core';
+import { lookup } from 'node:dns/promises';
 
 interface FrameEvalResult {
     frameUrl: string;
@@ -6,6 +7,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 +46,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;
     /**
@@ -176,7 +197,7 @@ interface ClickOptions {
     /** Mouse button to use */
     button?: 'left' | 'right' | 'middle';
     /** Modifier keys to hold during click */
-    modifiers?: ('Alt' | 'Control' | 'Meta' | 'Shift')[];
+    modifiers?: ('Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift')[];
     /** Timeout in milliseconds. Default: `8000` */
     timeoutMs?: number;
 }
@@ -390,9 +411,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;
     /**
@@ -663,6 +684,8 @@ declare class CrawlPage {
      */
     evaluate(fn: string, opts?: {
         ref?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
     }): Promise<unknown>;
     /**
      * Run JavaScript in ALL frames on the page (including cross-origin iframes).
@@ -987,7 +1010,7 @@ declare class CrawlPage {
  */
 declare class BrowserClaw {
     private readonly cdpUrl;
-    private readonly allowInternal;
+    private readonly ssrfPolicy;
     private chrome;
     private constructor();
     /**
@@ -1087,6 +1110,7 @@ declare class BrowserClaw {
     stop(): Promise<void>;
 }
 
+type LookupFn = typeof lookup;
 /**
  * Thrown when a navigation URL is blocked by SSRF policy.
  * Callers can catch this specifically to distinguish navigation blocks
@@ -1095,5 +1119,19 @@ declare class BrowserClaw {
 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;
+/**
+ * Assert that a URL is allowed for browser navigation under the given SSRF policy.
+ * Throws `InvalidBrowserNavigationUrlError` if the URL is blocked.
+ */
+declare function assertBrowserNavigationAllowed(opts: {
+    url: string;
+    lookupFn?: LookupFn;
+} & BrowserNavigationPolicyOptions): 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, InvalidBrowserNavigationUrlError, 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 };
+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 LookupFn, 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, assertBrowserNavigationAllowed, withBrowserNavigationPolicy };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as playwright_core from 'playwright-core';
+import { lookup } from 'node:dns/promises';
 
 interface FrameEvalResult {
     frameUrl: string;
@@ -6,6 +7,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 +46,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;
     /**
@@ -176,7 +197,7 @@ interface ClickOptions {
     /** Mouse button to use */
     button?: 'left' | 'right' | 'middle';
     /** Modifier keys to hold during click */
-    modifiers?: ('Alt' | 'Control' | 'Meta' | 'Shift')[];
+    modifiers?: ('Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift')[];
     /** Timeout in milliseconds. Default: `8000` */
     timeoutMs?: number;
 }
@@ -390,9 +411,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;
     /**
@@ -663,6 +684,8 @@ declare class CrawlPage {
      */
     evaluate(fn: string, opts?: {
         ref?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
     }): Promise<unknown>;
     /**
      * Run JavaScript in ALL frames on the page (including cross-origin iframes).
@@ -987,7 +1010,7 @@ declare class CrawlPage {
  */
 declare class BrowserClaw {
     private readonly cdpUrl;
-    private readonly allowInternal;
+    private readonly ssrfPolicy;
     private chrome;
     private constructor();
     /**
@@ -1087,6 +1110,7 @@ declare class BrowserClaw {
     stop(): Promise<void>;
 }
 
+type LookupFn = typeof lookup;
 /**
  * Thrown when a navigation URL is blocked by SSRF policy.
  * Callers can catch this specifically to distinguish navigation blocks
@@ -1095,5 +1119,19 @@ declare class BrowserClaw {
 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;
+/**
+ * Assert that a URL is allowed for browser navigation under the given SSRF policy.
+ * Throws `InvalidBrowserNavigationUrlError` if the URL is blocked.
+ */
+declare function assertBrowserNavigationAllowed(opts: {
+    url: string;
+    lookupFn?: LookupFn;
+} & BrowserNavigationPolicyOptions): 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, InvalidBrowserNavigationUrlError, 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 };
+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 LookupFn, 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, assertBrowserNavigationAllowed, withBrowserNavigationPolicy };

package/dist/index.js

@@ -1384,6 +1384,32 @@ var InvalidBrowserNavigationUrlError = class extends Error {
     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, opts.lookupFn)) {
+    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.");
@@ -1506,7 +1532,7 @@ function isInternalUrl(url) {
   }
   return false;
 }
-async function isInternalUrlResolved(url) {
+async function isInternalUrlResolved(url, lookupFn = lookup) {
   if (isInternalUrl(url)) return true;
   let parsed;
   try {
@@ -1515,7 +1541,7 @@ async function isInternalUrlResolved(url) {
     return true;
   }
   try {
-    const { address } = await lookup(parsed.hostname);
+    const { address } = await lookupFn(parsed.hostname);
     if (isInternalIP(address)) return true;
   } catch {
     return true;
@@ -1527,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 InvalidBrowserNavigationUrlError(`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) });
@@ -1552,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 InvalidBrowserNavigationUrlError(`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();
@@ -1673,6 +1699,7 @@ async function evaluateViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const timeout = opts.timeoutMs != null ? opts.timeoutMs : void 0;
   if (opts.ref) {
     const locator = refLocator(page, opts.ref);
     return await locator.evaluate(
@@ -1685,10 +1712,11 @@ async function evaluateViaPlaywright(opts) {
           throw new Error("Invalid evaluate function: " + (err instanceof Error ? err.message : String(err)));
         }
       },
-      fnText
+      fnText,
+      { timeout }
     );
   }
-  return await page.evaluate(
+  const evalPromise = page.evaluate(
     // eslint-disable-next-line no-eval
     (fnBody) => {
       try {
@@ -1700,6 +1728,13 @@ async function evaluateViaPlaywright(opts) {
     },
     fnText
   );
+  if (!opts.signal) return evalPromise;
+  return Promise.race([
+    evalPromise,
+    new Promise((_, reject) => {
+      opts.signal.addEventListener("abort", () => reject(new Error("Evaluate aborted")), { once: true });
+    })
+  ]);
 }
 
 // src/actions/download.ts
@@ -2061,12 +2096,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() {
@@ -2399,7 +2434,7 @@ var CrawlPage = class {
       targetId: this.targetId,
       url,
       timeoutMs: opts?.timeoutMs,
-      allowInternal: this.allowInternal
+      ssrfPolicy: this.ssrfPolicy
     });
   }
   /**
@@ -2478,7 +2513,9 @@ var CrawlPage = class {
       cdpUrl: this.cdpUrl,
       targetId: this.targetId,
       fn,
-      ref: opts?.ref
+      ref: opts?.ref,
+      timeoutMs: opts?.timeoutMs,
+      signal: opts?.signal
     });
   }
   /**
@@ -2929,12 +2966,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.
@@ -2962,7 +2999,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.
@@ -2983,7 +3021,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.
@@ -2998,8 +3037,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.
@@ -3012,7 +3051,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.
@@ -3047,7 +3086,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() {
@@ -3069,6 +3108,6 @@ var BrowserClaw = class _BrowserClaw {
   }
 };
 
-export { BrowserClaw, CrawlPage, InvalidBrowserNavigationUrlError };
+export { BrowserClaw, CrawlPage, InvalidBrowserNavigationUrlError, assertBrowserNavigationAllowed, withBrowserNavigationPolicy };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map