browserclaw 0.2.8 → 0.3.0

package/dist/index.cjs

@@ -1393,6 +1393,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.");
@@ -1515,7 +1541,7 @@ function isInternalUrl(url) {
   }
   return false;
 }
-async function isInternalUrlResolved(url) {
+async function isInternalUrlResolved(url, lookupFn = promises.lookup) {
   if (isInternalUrl(url)) return true;
   let parsed;
   try {
@@ -1524,7 +1550,7 @@ async function isInternalUrlResolved(url) {
     return true;
   }
   try {
-    const { address } = await promises.lookup(parsed.hostname);
+    const { address } = await lookupFn(parsed.hostname);
     if (isInternalIP(address)) return true;
   } catch {
     return true;
@@ -1536,9 +1562,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) });
@@ -1561,8 +1586,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();
@@ -1682,6 +1708,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(
@@ -1694,10 +1721,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 {
@@ -1709,6 +1737,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
@@ -2070,12 +2105,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() {
@@ -2408,7 +2443,7 @@ var CrawlPage = class {
       targetId: this.targetId,
       url,
       timeoutMs: opts?.timeoutMs,
-      allowInternal: this.allowInternal
+      ssrfPolicy: this.ssrfPolicy
     });
   }
   /**
@@ -2487,7 +2522,9 @@ var CrawlPage = class {
       cdpUrl: this.cdpUrl,
       targetId: this.targetId,
       fn,
-      ref: opts?.ref
+      ref: opts?.ref,
+      timeoutMs: opts?.timeoutMs,
+      signal: opts?.signal
     });
   }
   /**
@@ -2938,12 +2975,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.
@@ -2971,7 +3008,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.
@@ -2992,7 +3030,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.
@@ -3007,8 +3046,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.
@@ -3021,7 +3060,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.
@@ -3056,7 +3095,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() {
@@ -3081,5 +3120,7 @@ var BrowserClaw = class _BrowserClaw {
 exports.BrowserClaw = BrowserClaw;
 exports.CrawlPage = CrawlPage;
 exports.InvalidBrowserNavigationUrlError = InvalidBrowserNavigationUrlError;
+exports.assertBrowserNavigationAllowed = assertBrowserNavigationAllowed;
+exports.withBrowserNavigationPolicy = withBrowserNavigationPolicy;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map