browserclaw 0.2.3 → 0.2.4

package/dist/index.js

@@ -1,9 +1,10 @@
 import os from 'os';
-import path from 'path';
+import path, { normalize, resolve, sep } from 'path';
 import fs from 'fs';
 import net from 'net';
 import { spawn, execFileSync } from 'child_process';
 import { devices, chromium } from 'playwright-core';
+import { lookup } from 'dns/promises';
 
 // src/chrome-launcher.ts
 var CHROMIUM_BUNDLE_IDS = /* @__PURE__ */ new Set([
@@ -263,12 +264,12 @@ function resolveBrowserExecutable(opts) {
   return null;
 }
 async function ensurePortAvailable(port) {
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     const tester = net.createServer().once("error", (err) => {
       if (err.code === "EADDRINUSE") reject(new Error(`Port ${port} is already in use`));
       else reject(err);
     }).once("listening", () => {
-      tester.close(() => resolve());
+      tester.close(() => resolve2());
     }).listen(port);
   });
 }
@@ -338,11 +339,13 @@ function resolveUserDataDir(profileName) {
   const configDir = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
   return path.join(configDir, "browserclaw", "profiles", profileName, "user-data");
 }
-async function isChromeReachable(cdpUrl, timeoutMs = 500) {
+async function isChromeReachable(cdpUrl, timeoutMs = 500, authToken) {
   const ctrl = new AbortController();
   const t = setTimeout(() => ctrl.abort(), timeoutMs);
   try {
-    const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal });
+    const headers = {};
+    if (authToken) headers["Authorization"] = `Bearer ${authToken}`;
+    const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal, headers });
     return res.ok;
   } catch {
     return false;
@@ -350,11 +353,13 @@ async function isChromeReachable(cdpUrl, timeoutMs = 500) {
     clearTimeout(t);
   }
 }
-async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500) {
+async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500, authToken) {
   const ctrl = new AbortController();
   const t = setTimeout(() => ctrl.abort(), timeoutMs);
   try {
-    const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal });
+    const headers = {};
+    if (authToken) headers["Authorization"] = `Bearer ${authToken}`;
+    const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal, headers });
     if (!res.ok) return null;
     const data = await res.json();
     return String(data?.webSocketDebuggerUrl ?? "").trim() || null;
@@ -620,7 +625,7 @@ function restoreRoleRefsForTarget(opts) {
   state.roleRefsFrameSelector = entry.frameSelector;
   state.roleRefsMode = entry.mode;
 }
-async function connectBrowser(cdpUrl) {
+async function connectBrowser(cdpUrl, authToken) {
   const normalized = normalizeCdpUrl(cdpUrl);
   if (cached?.cdpUrl === normalized) return cached;
   const existing = connectingByUrl.get(normalized);
@@ -630,9 +635,11 @@ async function connectBrowser(cdpUrl) {
     for (let attempt = 0; attempt < 3; attempt++) {
       try {
         const timeout = 5e3 + attempt * 2e3;
-        const endpoint = await getChromeWebSocketUrl(normalized, timeout).catch(() => null) ?? normalized;
-        const browser = await chromium.connectOverCDP(endpoint, { timeout });
-        const connected = { browser, cdpUrl: normalized };
+        const endpoint = await getChromeWebSocketUrl(normalized, timeout, authToken).catch(() => null) ?? normalized;
+        const headers = {};
+        if (authToken) headers["Authorization"] = `Bearer ${authToken}`;
+        const browser = await chromium.connectOverCDP(endpoint, { timeout, headers });
+        const connected = { browser, cdpUrl: normalized, authToken };
         cached = connected;
         observeBrowser(browser);
         browser.on("disconnected", () => {
@@ -692,7 +699,9 @@ async function findPageByTargetId(browser, targetId, cdpUrl) {
   if (cdpUrl) {
     try {
       const listUrl = `${cdpUrl.replace(/\/+$/, "").replace(/^ws:/, "http:").replace(/\/cdp$/, "")}/json/list`;
-      const response = await fetch(listUrl);
+      const headers = {};
+      if (cached?.authToken) headers["Authorization"] = `Bearer ${cached.authToken}`;
+      const response = await fetch(listUrl, { headers });
       if (response.ok) {
         const targets = await response.json();
         const target = targets.find((t) => t.id === targetId);
@@ -1017,6 +1026,7 @@ async function snapshotAi(opts) {
   if (!maybe._snapshotForAI) {
     throw new Error("Playwright _snapshotForAI is not available. Upgrade playwright-core to >= 1.50.");
   }
+  const sourceUrl = page.url();
   const result = await maybe._snapshotForAI({
     timeout: normalizeTimeoutMs(opts.timeoutMs, 5e3, 6e4),
     track: "response"
@@ -1043,7 +1053,12 @@ async function snapshotAi(opts) {
     snapshot: built.snapshot,
     refs: built.refs,
     stats: getRoleSnapshotStats(built.snapshot, built.refs),
-    untrusted: true
+    untrusted: true,
+    contentMeta: {
+      sourceUrl,
+      contentType: "browser-snapshot",
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
   };
 }
 
@@ -1051,6 +1066,7 @@ async function snapshotAi(opts) {
 async function snapshotRole(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
+  const sourceUrl = page.url();
   const frameSelector = opts.frameSelector?.trim() || "";
   const selector = opts.selector?.trim() || "";
   const locator = frameSelector ? selector ? page.frameLocator(frameSelector).locator(selector) : page.frameLocator(frameSelector).locator(":root") : selector ? page.locator(selector) : page.locator(":root");
@@ -1068,19 +1084,33 @@ async function snapshotRole(opts) {
     snapshot: built.snapshot,
     refs: built.refs,
     stats: getRoleSnapshotStats(built.snapshot, built.refs),
-    untrusted: true
+    untrusted: true,
+    contentMeta: {
+      sourceUrl,
+      contentType: "browser-snapshot",
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
   };
 }
 async function snapshotAria(opts) {
   const limit = Math.max(1, Math.min(2e3, Math.floor(opts.limit ?? 500)));
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
+  const sourceUrl = page.url();
   const session = await page.context().newCDPSession(page);
   try {
     await session.send("Accessibility.enable").catch(() => {
     });
     const res = await session.send("Accessibility.getFullAXTree");
-    return { nodes: formatAriaNodes(Array.isArray(res?.nodes) ? res.nodes : [], limit), untrusted: true };
+    return {
+      nodes: formatAriaNodes(Array.isArray(res?.nodes) ? res.nodes : [], limit),
+      untrusted: true,
+      contentMeta: {
+        sourceUrl,
+        contentType: "browser-aria-tree",
+        capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
   } finally {
     await session.detach().catch(() => {
     });
@@ -1271,7 +1301,7 @@ async function armDialogViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const timer = setTimeout(() => {
       page.removeListener("dialog", handler);
       reject(new Error(`No dialog appeared within ${timeout}ms`));
@@ -1284,7 +1314,7 @@ async function armDialogViaPlaywright(opts) {
         } else {
           await dialog.dismiss();
         }
-        resolve();
+        resolve2();
       } catch (err) {
         reject(err);
       }
@@ -1296,7 +1326,7 @@ async function armFileUploadViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const timer = setTimeout(() => {
       page.removeListener("filechooser", handler);
       reject(new Error(`No file chooser appeared within ${timeout}ms`));
@@ -1305,7 +1335,7 @@ async function armFileUploadViaPlaywright(opts) {
       clearTimeout(timer);
       try {
         await fc.setFiles(opts.paths ?? []);
-        resolve();
+        resolve2();
       } catch (err) {
         reject(err);
       }
@@ -1322,11 +1352,82 @@ async function pressKeyViaPlaywright(opts) {
   ensurePageState(page);
   await page.keyboard.press(key, { delay: Math.max(0, Math.floor(opts.delayMs ?? 0)) });
 }
+function assertSafeOutputPath(path2, allowedRoots) {
+  if (!path2 || typeof path2 !== "string") {
+    throw new Error("Output path is required.");
+  }
+  const normalized = normalize(path2);
+  if (normalized.includes("..")) {
+    throw new Error(`Unsafe output path: directory traversal detected in "${path2}".`);
+  }
+  if (allowedRoots?.length) {
+    const resolved = resolve(normalized);
+    const withinRoot = allowedRoots.some((root) => {
+      const normalizedRoot = resolve(root);
+      return resolved === normalizedRoot || resolved.startsWith(normalizedRoot + sep);
+    });
+    if (!withinRoot) {
+      throw new Error(`Unsafe output path: "${path2}" is outside allowed directories.`);
+    }
+  }
+}
+function isInternalIP(ip) {
+  if (/^127\./.test(ip)) return true;
+  if (/^10\./.test(ip)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(ip)) return true;
+  if (/^192\.168\./.test(ip)) return true;
+  if (/^169\.254\./.test(ip)) return true;
+  if (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(ip)) return true;
+  if (ip === "0.0.0.0") return true;
+  const lower = ip.toLowerCase();
+  if (lower === "::1") return true;
+  if (lower.startsWith("fe80:")) return true;
+  if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
+  if (lower.startsWith("::ffff:")) {
+    const v4 = lower.replace(/^::ffff:/, "");
+    return isInternalIP(v4);
+  }
+  return false;
+}
+function isInternalUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return true;
+  }
+  const hostname = parsed.hostname.toLowerCase();
+  if (hostname === "localhost") return true;
+  if (isInternalIP(hostname)) return true;
+  if (hostname.endsWith(".local") || hostname.endsWith(".internal") || hostname.endsWith(".localhost")) {
+    return true;
+  }
+  return false;
+}
+async function isInternalUrlResolved(url) {
+  if (isInternalUrl(url)) return true;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return true;
+  }
+  try {
+    const { address } = await lookup(parsed.hostname);
+    if (isInternalIP(address)) return true;
+  } catch {
+    return true;
+  }
+  return false;
+}
 
 // src/actions/navigation.ts
 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 page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   await page.goto(url, { timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4) });
@@ -1348,11 +1449,14 @@ async function listPagesViaPlaywright(opts) {
   return results;
 }
 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.`);
+  }
   const { browser } = await connectBrowser(opts.cdpUrl);
   const context = browser.contexts()[0] ?? await browser.newContext();
   const page = await context.newPage();
   ensurePageState(page);
-  const targetUrl = (opts.url ?? "").trim() || "about:blank";
   if (targetUrl !== "about:blank") {
     await page.goto(targetUrl, { timeout: normalizeTimeoutMs(void 0, 2e4) });
   }
@@ -1498,6 +1602,7 @@ async function evaluateViaPlaywright(opts) {
 
 // src/actions/download.ts
 async function downloadViaPlaywright(opts) {
+  assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
@@ -1524,6 +1629,7 @@ async function waitForDownloadViaPlaywright(opts) {
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
   const download = await page.waitForEvent("download", { timeout });
   const savePath = opts.path ?? download.suggestedFilename();
+  assertSafeOutputPath(savePath, opts.allowedOutputRoots);
   await download.saveAs(savePath);
   return {
     url: download.url(),
@@ -1707,6 +1813,7 @@ async function traceStartViaPlaywright(opts) {
   });
 }
 async function traceStopViaPlaywright(opts) {
+  assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const context = page.context();
@@ -1852,10 +1959,12 @@ async function storageClearViaPlaywright(opts) {
 var CrawlPage = class {
   cdpUrl;
   targetId;
+  allowInternal;
   /** @internal */
-  constructor(cdpUrl, targetId) {
+  constructor(cdpUrl, targetId, allowInternal = false) {
     this.cdpUrl = cdpUrl;
     this.targetId = targetId;
+    this.allowInternal = allowInternal;
   }
   /** The CDP target ID for this page. Use this to identify the page in multi-tab scenarios. */
   get id() {
@@ -2187,7 +2296,8 @@ var CrawlPage = class {
       cdpUrl: this.cdpUrl,
       targetId: this.targetId,
       url,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      allowInternal: this.allowInternal
     });
   }
   /**
@@ -2374,12 +2484,14 @@ var CrawlPage = class {
    * Stop recording a trace and save it to a file.
    *
    * @param path - File path to save the trace (e.g. `'trace.zip'`)
+   * @param opts - Options (allowedOutputRoots: constrain output to specific directories)
    */
-  async traceStop(path2) {
+  async traceStop(path2, opts) {
     return traceStopViaPlaywright({
       cdpUrl: this.cdpUrl,
       targetId: this.targetId,
-      path: path2
+      path: path2,
+      allowedOutputRoots: opts?.allowedOutputRoots
     });
   }
   /**
@@ -2567,7 +2679,8 @@ var CrawlPage = class {
       targetId: this.targetId,
       ref,
       path: path2,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      allowedOutputRoots: opts?.allowedOutputRoots
     });
   }
   /**
@@ -2583,7 +2696,8 @@ var CrawlPage = class {
       cdpUrl: this.cdpUrl,
       targetId: this.targetId,
       path: opts?.path,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      allowedOutputRoots: opts?.allowedOutputRoots
     });
   }
   // ── Emulation ───────────────────────────────────────────────
@@ -2713,10 +2827,12 @@ var CrawlPage = class {
 };
 var BrowserClaw = class _BrowserClaw {
   cdpUrl;
+  allowInternal;
   chrome;
-  constructor(cdpUrl, chrome) {
+  constructor(cdpUrl, chrome, allowInternal = false) {
     this.cdpUrl = cdpUrl;
     this.chrome = chrome;
+    this.allowInternal = allowInternal;
   }
   /**
    * Launch a new Chrome instance and connect to it.
@@ -2744,7 +2860,7 @@ 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);
+    return new _BrowserClaw(cdpUrl, chrome, opts.allowInternal);
   }
   /**
    * Connect to an already-running Chrome instance via its CDP endpoint.
@@ -2760,12 +2876,12 @@ var BrowserClaw = class _BrowserClaw {
    * const browser = await BrowserClaw.connect('http://localhost:9222');
    * ```
    */
-  static async connect(cdpUrl) {
-    if (!await isChromeReachable(cdpUrl, 3e3)) {
+  static async connect(cdpUrl, opts) {
+    if (!await isChromeReachable(cdpUrl, 3e3, opts?.authToken)) {
       throw new Error(`Cannot connect to Chrome at ${cdpUrl}. Is Chrome running with --remote-debugging-port?`);
     }
-    await connectBrowser(cdpUrl);
-    return new _BrowserClaw(cdpUrl, null);
+    await connectBrowser(cdpUrl, opts?.authToken);
+    return new _BrowserClaw(cdpUrl, null, opts?.allowInternal);
   }
   /**
    * Open a URL in a new tab and return the page handle.
@@ -2780,8 +2896,8 @@ var BrowserClaw = class _BrowserClaw {
    * ```
    */
   async open(url) {
-    const tab = await createPageViaPlaywright({ cdpUrl: this.cdpUrl, url });
-    return new CrawlPage(this.cdpUrl, tab.targetId);
+    const tab = await createPageViaPlaywright({ cdpUrl: this.cdpUrl, url, allowInternal: this.allowInternal });
+    return new CrawlPage(this.cdpUrl, tab.targetId, this.allowInternal);
   }
   /**
    * Get a CrawlPage handle for the currently active tab.
@@ -2794,7 +2910,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);
+    return new CrawlPage(this.cdpUrl, tid, this.allowInternal);
   }
   /**
    * List all open tabs.
@@ -2829,7 +2945,7 @@ var BrowserClaw = class _BrowserClaw {
    * @returns CrawlPage for the specified tab
    */
   page(targetId) {
-    return new CrawlPage(this.cdpUrl, targetId);
+    return new CrawlPage(this.cdpUrl, targetId, this.allowInternal);
   }
   /** The CDP endpoint URL for this browser connection. */
   get url() {