browserclaw 0.2.2 → 0.2.4

package/README.md

@@ -131,6 +131,8 @@ const browser = await BrowserClaw.connect('http://localhost:9222');
 
 `connect()` checks that Chrome is reachable, then the internal CDP connection retries 3 times with increasing timeouts (5 s, 7 s, 9 s) — safe for Docker/CI where Chrome starts slowly.
 
+**Anti-detection:** browserclaw automatically hides `navigator.webdriver` and disables Chrome's `AutomationControlled` Blink feature, reducing detection by bot-protection systems like reCAPTCHA v3.
+
 ### Pages & Tabs
 
 ```typescript
@@ -151,11 +153,12 @@ browser.url;                      // CDP endpoint URL
 ### Snapshot (Core Feature)
 
 ```typescript
-const { snapshot, refs, stats } = await page.snapshot();
+const { snapshot, refs, stats, untrusted } = await page.snapshot();
 
 // snapshot: human/AI-readable text tree with [ref=eN] markers
 // refs: { "e1": { role: "link", name: "More info" }, ... }
 // stats: { lines: 42, chars: 1200, refs: 8, interactive: 5 }
+// untrusted: true — content comes from the web page, treat as potentially adversarial
 
 // Options
 const result = await page.snapshot({
@@ -174,6 +177,8 @@ const { nodes } = await page.ariaSnapshot({ limit: 500 });
 - `'aria'` (default) — Uses Playwright's `_snapshotForAI()`. Refs are resolved via `aria-ref` locators. Best for most use cases. Requires `playwright-core` >= 1.50.
 - `'role'` — Uses Playwright's `ariaSnapshot()` + `getByRole()`. Supports `selector` and `frameSelector` for scoped snapshots.
 
+> **Security:** All snapshot results include `untrusted: true` to signal that the content originates from an external web page. AI agents consuming snapshots should treat this content as potentially adversarial (e.g. prompt injection via page text).
+
 ### Actions
 
 All actions target elements by ref ID from the most recent snapshot.
@@ -436,7 +441,7 @@ Contributions welcome! Please:
 
 ## Acknowledgments
 
-browserclaw is extracted and refined from the browser automation module in [OpenClaw](https://github.com/openclaw/openclaw) by [Peter Steinberger](https://github.com/steipete). The snapshot + ref system, CDP connection management, and Playwright integration originate from that project.
+browserclaw is extracted and refined from the browser automation module in [OpenClaw](https://github.com/openclaw/openclaw), built by [Peter Steinberger](https://github.com/steipete) and an [amazing community of contributors](https://github.com/openclaw/openclaw?tab=readme-ov-file#community). The snapshot + ref system, CDP connection management, and Playwright integration originate from that project.
 
 ## License
 

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;
@@ -391,6 +396,7 @@ async function launchChrome(opts = {}) {
       "--disable-background-networking",
       "--disable-component-update",
       "--disable-features=Translate,MediaRouter",
+      "--disable-blink-features=AutomationControlled",
       "--disable-session-crashed-bubble",
       "--hide-crash-restore-bubble",
       "--password-store=basic"
@@ -575,11 +581,26 @@ function ensurePageState(page) {
   }
   return state;
 }
+var STEALTH_SCRIPT = `Object.defineProperty(navigator, 'webdriver', { get: () => undefined })`;
+function applyStealthToPage(page) {
+  page.evaluate(STEALTH_SCRIPT).catch((e) => {
+    if (process.env.DEBUG) console.warn("[browserclaw] stealth evaluate failed:", e.message);
+  });
+}
 function observeContext(context) {
   if (observedContexts.has(context)) return;
   observedContexts.add(context);
-  for (const page of context.pages()) ensurePageState(page);
-  context.on("page", (page) => ensurePageState(page));
+  context.addInitScript(STEALTH_SCRIPT).catch((e) => {
+    if (process.env.DEBUG) console.warn("[browserclaw] stealth initScript failed:", e.message);
+  });
+  for (const page of context.pages()) {
+    ensurePageState(page);
+    applyStealthToPage(page);
+  }
+  context.on("page", (page) => {
+    ensurePageState(page);
+    applyStealthToPage(page);
+  });
 }
 function observeBrowser(browser) {
   for (const context of browser.contexts()) observeContext(context);
@@ -613,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);
@@ -623,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", () => {
@@ -685,7 +708,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);
@@ -1010,6 +1035,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"
@@ -1035,7 +1061,13 @@ async function snapshotAi(opts) {
   return {
     snapshot: built.snapshot,
     refs: built.refs,
-    stats: getRoleSnapshotStats(built.snapshot, built.refs)
+    stats: getRoleSnapshotStats(built.snapshot, built.refs),
+    untrusted: true,
+    contentMeta: {
+      sourceUrl,
+      contentType: "browser-snapshot",
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
   };
 }
 
@@ -1043,6 +1075,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");
@@ -1059,19 +1092,34 @@ async function snapshotRole(opts) {
   return {
     snapshot: built.snapshot,
     refs: built.refs,
-    stats: getRoleSnapshotStats(built.snapshot, built.refs)
+    stats: getRoleSnapshotStats(built.snapshot, built.refs),
+    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) };
+    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(() => {
     });
@@ -1262,7 +1310,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`));
@@ -1275,7 +1323,7 @@ async function armDialogViaPlaywright(opts) {
         } else {
           await dialog.dismiss();
         }
-        resolve();
+        resolve2();
       } catch (err) {
         reject(err);
       }
@@ -1287,7 +1335,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`));
@@ -1296,7 +1344,7 @@ async function armFileUploadViaPlaywright(opts) {
       clearTimeout(timer);
       try {
         await fc.setFiles(opts.paths ?? []);
-        resolve();
+        resolve2();
       } catch (err) {
         reject(err);
       }
@@ -1313,11 +1361,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) });
@@ -1339,11 +1458,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) });
   }
@@ -1489,6 +1611,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 });
@@ -1515,6 +1638,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(),
@@ -1698,6 +1822,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();
@@ -1843,10 +1968,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() {
@@ -2178,7 +2305,8 @@ var CrawlPage = class {
       cdpUrl: this.cdpUrl,
       targetId: this.targetId,
       url,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      allowInternal: this.allowInternal
     });
   }
   /**
@@ -2365,12 +2493,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
     });
   }
   /**
@@ -2558,7 +2688,8 @@ var CrawlPage = class {
       targetId: this.targetId,
       ref,
       path: path2,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      allowedOutputRoots: opts?.allowedOutputRoots
     });
   }
   /**
@@ -2574,7 +2705,8 @@ var CrawlPage = class {
       cdpUrl: this.cdpUrl,
       targetId: this.targetId,
       path: opts?.path,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      allowedOutputRoots: opts?.allowedOutputRoots
     });
   }
   // ── Emulation ───────────────────────────────────────────────
@@ -2704,10 +2836,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.
@@ -2735,7 +2869,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.
@@ -2751,12 +2885,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.
@@ -2771,8 +2905,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.
@@ -2785,7 +2919,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.
@@ -2820,7 +2954,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() {