browserclaw 0.2.3 → 0.2.5

package/dist/index.cjs

@@ -6,6 +6,7 @@ var fs = require('fs');
 var net = require('net');
 var child_process = require('child_process');
 var playwrightCore = require('playwright-core');
+var promises = require('dns/promises');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -272,12 +273,12 @@ function resolveBrowserExecutable(opts) {
   return null;
 }
 async function ensurePortAvailable(port) {
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     const tester = net__default.default.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);
   });
 }
@@ -347,11 +348,13 @@ function resolveUserDataDir(profileName) {
   const configDir = process.env.XDG_CONFIG_HOME ?? path__default.default.join(os__default.default.homedir(), ".config");
   return path__default.default.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;
@@ -359,11 +362,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;
@@ -629,7 +634,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);
@@ -639,9 +644,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 playwrightCore.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 playwrightCore.chromium.connectOverCDP(endpoint, { timeout, headers });
+        const connected = { browser, cdpUrl: normalized, authToken };
         cached = connected;
         observeBrowser(browser);
         browser.on("disconnected", () => {
@@ -694,14 +701,26 @@ async function pageTargetId(page) {
 }
 async function findPageByTargetId(browser, targetId, cdpUrl) {
   const pages = await getAllPages(browser);
+  let resolvedViaCdp = false;
   for (const page of pages) {
-    const tid = await pageTargetId(page).catch(() => null);
+    let tid = null;
+    try {
+      tid = await pageTargetId(page);
+      resolvedViaCdp = true;
+    } catch {
+      tid = null;
+    }
     if (tid && tid === targetId) return page;
   }
+  if (!resolvedViaCdp && pages.length === 1) {
+    return pages[0];
+  }
   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);
@@ -826,6 +845,27 @@ function getIndentLevel(line) {
   const match = line.match(/^(\s*)/);
   return match ? Math.floor(match[1].length / 2) : 0;
 }
+function matchInteractiveSnapshotLine(line, options) {
+  const depth = getIndentLevel(line);
+  if (options.maxDepth !== void 0 && depth > options.maxDepth) {
+    return null;
+  }
+  const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+  if (!match) {
+    return null;
+  }
+  const [, , roleRaw, name, suffix] = match;
+  if (roleRaw.startsWith("/")) {
+    return null;
+  }
+  const role = roleRaw.toLowerCase();
+  return {
+    roleRaw,
+    role,
+    ...name ? { name } : {},
+    suffix
+  };
+}
 function createRoleNameTracker() {
   const counts = /* @__PURE__ */ new Map();
   const refsByKey = /* @__PURE__ */ new Map();
@@ -899,14 +939,11 @@ function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
   if (options.interactive) {
     const result2 = [];
     for (const line of lines) {
-      const depth = getIndentLevel(line);
-      if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
-      const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
-      if (!match) continue;
-      const [, prefix, roleRaw, name, suffix] = match;
-      if (roleRaw.startsWith("/")) continue;
-      const role = roleRaw.toLowerCase();
+      const parsed = matchInteractiveSnapshotLine(line, options);
+      if (!parsed) continue;
+      const { roleRaw, role, name, suffix } = parsed;
       if (!INTERACTIVE_ROLES.has(role)) continue;
+      const prefix = line.match(/^(\s*-\s*)/)?.[1] ?? "";
       const ref = nextRef();
       const nth = tracker.getNextIndex(role, name);
       tracker.trackRef(role, name, ref);
@@ -969,16 +1006,13 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
   if (options.interactive) {
     const out2 = [];
     for (const line of lines) {
-      const depth = getIndentLevel(line);
-      if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
-      const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
-      if (!match) continue;
-      const [, prefix, roleRaw, name, suffix] = match;
-      if (roleRaw.startsWith("/")) continue;
-      const role = roleRaw.toLowerCase();
+      const parsed = matchInteractiveSnapshotLine(line, options);
+      if (!parsed) continue;
+      const { roleRaw, role, name, suffix } = parsed;
       if (!INTERACTIVE_ROLES.has(role)) continue;
       const ref = parseAiSnapshotRef(suffix);
       if (!ref) continue;
+      const prefix = line.match(/^(\s*-\s*)/)?.[1] ?? "";
       refs[ref] = { role, ...name ? { name } : {} };
       out2.push(`${prefix}${roleRaw}${name ? ` "${name}"` : ""}${suffix}`);
     }
@@ -1026,6 +1060,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"
@@ -1052,7 +1087,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()
+    }
   };
 }
 
@@ -1060,6 +1100,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");
@@ -1077,19 +1118,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(() => {
     });
@@ -1280,7 +1335,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`));
@@ -1293,7 +1348,7 @@ async function armDialogViaPlaywright(opts) {
         } else {
           await dialog.dismiss();
         }
-        resolve();
+        resolve2();
       } catch (err) {
         reject(err);
       }
@@ -1305,7 +1360,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`));
@@ -1314,7 +1369,7 @@ async function armFileUploadViaPlaywright(opts) {
       clearTimeout(timer);
       try {
         await fc.setFiles(opts.paths ?? []);
-        resolve();
+        resolve2();
       } catch (err) {
         reject(err);
       }
@@ -1331,11 +1386,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 = path.normalize(path2);
+  if (normalized.includes("..")) {
+    throw new Error(`Unsafe output path: directory traversal detected in "${path2}".`);
+  }
+  if (allowedRoots?.length) {
+    const resolved = path.resolve(normalized);
+    const withinRoot = allowedRoots.some((root) => {
+      const normalizedRoot = path.resolve(root);
+      return resolved === normalizedRoot || resolved.startsWith(normalizedRoot + path.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 promises.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) });
@@ -1357,11 +1483,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) });
   }
@@ -1507,6 +1636,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 });
@@ -1533,6 +1663,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(),
@@ -1716,6 +1847,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();
@@ -1861,10 +1993,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() {
@@ -2196,7 +2330,8 @@ var CrawlPage = class {
       cdpUrl: this.cdpUrl,
       targetId: this.targetId,
       url,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      allowInternal: this.allowInternal
     });
   }
   /**
@@ -2383,12 +2518,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
     });
   }
   /**
@@ -2576,7 +2713,8 @@ var CrawlPage = class {
       targetId: this.targetId,
       ref,
       path: path2,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      allowedOutputRoots: opts?.allowedOutputRoots
     });
   }
   /**
@@ -2592,7 +2730,8 @@ var CrawlPage = class {
       cdpUrl: this.cdpUrl,
       targetId: this.targetId,
       path: opts?.path,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      allowedOutputRoots: opts?.allowedOutputRoots
     });
   }
   // ── Emulation ───────────────────────────────────────────────
@@ -2722,10 +2861,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.
@@ -2753,7 +2894,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.
@@ -2769,12 +2910,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.
@@ -2789,8 +2930,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.
@@ -2803,7 +2944,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.
@@ -2838,7 +2979,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() {