browserclaw 0.3.6 → 0.3.8

package/README.md

@@ -1,4 +1,4 @@
-<h2 align="center">🦞 BrowserClaw — Standalone OpenClaw browser module</h1>
+<h2 align="center">🦞 BrowserClaw — Standalone OpenClaw browser module</h2>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/browserclaw"><img src="https://img.shields.io/npm/v/browserclaw.svg" alt="npm version" /></a>
@@ -217,13 +217,13 @@ await page.press('Meta+Shift+p');
 
 // Fill multiple form fields at once
 await page.fill([
-  { ref: 'e2', type: 'text', value: 'Jane Doe' },
-  { ref: 'e4', type: 'text', value: 'jane@example.com' },
+  { ref: 'e2', value: 'Jane Doe' },
+  { ref: 'e4', value: 'jane@example.com' },
   { ref: 'e6', type: 'checkbox', value: true },
 ]);
 ```
 
-`fill()` field types: `'text'` calls Playwright `fill()` with the string value. `'checkbox'` and `'radio'` call `setChecked()` — truthy values are `true`, `1`, `'1'`, `'true'`. Empty ref or type throws.
+`fill()` field types: `'text'` (default) calls Playwright `fill()` with the string value. `'checkbox'` and `'radio'` call `setChecked()` — truthy values are `true`, `1`, `'1'`, `'true'`. Type can be omitted and defaults to `'text'`. Empty ref throws.
 
 #### Highlight
 

package/dist/index.cjs

@@ -7,6 +7,7 @@ var net = require('net');
 var child_process = require('child_process');
 var playwrightCore = require('playwright-core');
 var promises = require('dns/promises');
+var promises$1 = require('fs/promises');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -1198,6 +1199,222 @@ function formatAriaNodes(nodes, limit) {
   }
   return out;
 }
+var InvalidBrowserNavigationUrlError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidBrowserNavigationUrlError";
+  }
+};
+function withBrowserNavigationPolicy(ssrfPolicy) {
+  return { ssrfPolicy };
+}
+var NETWORK_NAVIGATION_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
+var SAFE_NON_NETWORK_URLS = /* @__PURE__ */ new Set(["about:blank"]);
+async function assertBrowserNavigationAllowed(opts) {
+  const rawUrl = String(opts.url ?? "").trim();
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new InvalidBrowserNavigationUrlError(`Invalid URL: "${rawUrl}"`);
+  }
+  if (!NETWORK_NAVIGATION_PROTOCOLS.has(parsed.protocol)) {
+    if (SAFE_NON_NETWORK_URLS.has(parsed.href)) return;
+    throw new InvalidBrowserNavigationUrlError(`Navigation blocked: unsupported protocol "${parsed.protocol}"`);
+  }
+  const policy = opts.ssrfPolicy;
+  if (policy?.dangerouslyAllowPrivateNetwork ?? policy?.allowPrivateNetwork ?? true) return;
+  const allowedHostnames = [
+    ...policy?.allowedHostnames ?? [],
+    ...policy?.hostnameAllowlist ?? []
+  ];
+  if (allowedHostnames.length) {
+    const hostname = parsed.hostname.toLowerCase();
+    if (allowedHostnames.some((h) => h.toLowerCase() === hostname)) return;
+  }
+  if (await isInternalUrlResolved(rawUrl, opts.lookupFn)) {
+    throw new InvalidBrowserNavigationUrlError(
+      `Navigation to internal/loopback address blocked: "${rawUrl}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
+    );
+  }
+}
+async 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);
+    let parentReal;
+    try {
+      parentReal = await promises$1.realpath(path.dirname(resolved));
+    } catch {
+      throw new Error(`Unsafe output path: parent directory is inaccessible for "${path2}".`);
+    }
+    try {
+      const targetStat = await promises$1.lstat(resolved);
+      if (targetStat.isSymbolicLink()) {
+        throw new Error(`Unsafe output path: "${path2}" is a symbolic link.`);
+      }
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+    const results = await Promise.all(
+      allowedRoots.map(async (root) => {
+        try {
+          const rootStat = await promises$1.lstat(path.resolve(root));
+          if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return false;
+          const rootReal = await promises$1.realpath(path.resolve(root));
+          return parentReal === rootReal || parentReal.startsWith(rootReal + path.sep);
+        } catch {
+          return false;
+        }
+      })
+    );
+    if (!results.some(Boolean)) {
+      throw new Error(`Unsafe output path: "${path2}" is outside allowed directories.`);
+    }
+  }
+}
+function expandIPv6(ip) {
+  let normalized = ip;
+  const v4Match = normalized.match(/^(.+:)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (v4Match) {
+    const octets = v4Match[2].split(".").map(Number);
+    if (octets.some((o) => o > 255)) return null;
+    const hexHi = (octets[0] << 8 | octets[1]).toString(16).padStart(4, "0");
+    const hexLo = (octets[2] << 8 | octets[3]).toString(16).padStart(4, "0");
+    normalized = v4Match[1] + hexHi + ":" + hexLo;
+  }
+  const halves = normalized.split("::");
+  if (halves.length > 2) return null;
+  if (halves.length === 2) {
+    const left = halves[0] !== "" ? halves[0].split(":") : [];
+    const right = halves[1] !== "" ? halves[1].split(":") : [];
+    const needed = 8 - left.length - right.length;
+    if (needed < 0) return null;
+    const groups2 = [...left, ...Array(needed).fill("0"), ...right];
+    if (groups2.length !== 8) return null;
+    return groups2.map((g) => g.padStart(4, "0")).join(":");
+  }
+  const groups = normalized.split(":");
+  if (groups.length !== 8) return null;
+  return groups.map((g) => g.padStart(4, "0")).join(":");
+}
+function hexToIPv4(hiHex, loHex) {
+  const hi = parseInt(hiHex, 16);
+  const lo = parseInt(loHex, 16);
+  return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
+}
+function extractEmbeddedIPv4(lower) {
+  if (lower.startsWith("::ffff:")) {
+    return lower.slice(7);
+  }
+  const expanded = expandIPv6(lower);
+  if (expanded === null) return "";
+  const groups = expanded.split(":");
+  if (groups.length !== 8) return "";
+  if (groups[0] === "0064" && groups[1] === "ff9b" && groups[2] === "0000" && groups[3] === "0000" && groups[4] === "0000" && groups[5] === "0000") {
+    return hexToIPv4(groups[6], groups[7]);
+  }
+  if (groups[0] === "0064" && groups[1] === "ff9b" && groups[2] === "0001") {
+    return hexToIPv4(groups[6], groups[7]);
+  }
+  if (groups[0] === "2002") {
+    return hexToIPv4(groups[1], groups[2]);
+  }
+  if (groups[0] === "2001" && groups[1] === "0000") {
+    const hiXored = (parseInt(groups[6], 16) ^ 65535).toString(16).padStart(4, "0");
+    const loXored = (parseInt(groups[7], 16) ^ 65535).toString(16).padStart(4, "0");
+    return hexToIPv4(hiXored, loXored);
+  }
+  return null;
+}
+function isStrictDecimalOctet(part) {
+  if (!/^[0-9]+$/.test(part)) return false;
+  const n = parseInt(part, 10);
+  if (n < 0 || n > 255) return false;
+  if (String(n) !== part) return false;
+  return true;
+}
+function isUnsupportedIPv4Literal(ip) {
+  if (/^[0-9]+$/.test(ip)) return true;
+  const parts = ip.split(".");
+  if (parts.length !== 4) return true;
+  if (!parts.every(isStrictDecimalOctet)) return true;
+  return false;
+}
+function isInternalIP(ip) {
+  if (!ip.includes(":") && isUnsupportedIPv4Literal(ip)) return true;
+  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("ff")) return true;
+  const embedded = extractEmbeddedIPv4(lower);
+  if (embedded !== null) {
+    if (embedded === "") return true;
+    return isInternalIP(embedded);
+  }
+  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 assertSafeUploadPaths(paths) {
+  for (const filePath of paths) {
+    let stat;
+    try {
+      stat = await promises$1.lstat(filePath);
+    } catch {
+      throw new Error(`Upload path does not exist or is inaccessible: "${filePath}".`);
+    }
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Upload path is a symbolic link: "${filePath}".`);
+    }
+    if (!stat.isFile()) {
+      throw new Error(`Upload path is not a regular file: "${filePath}".`);
+    }
+  }
+}
+async function isInternalUrlResolved(url, lookupFn = promises.lookup) {
+  if (isInternalUrl(url)) return true;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return true;
+  }
+  try {
+    const { address } = await lookupFn(parsed.hostname);
+    if (isInternalIP(address)) return true;
+  } catch {
+    return true;
+  }
+  return false;
+}
 
 // src/actions/interaction.ts
 async function clickViaPlaywright(opts) {
@@ -1280,11 +1497,10 @@ async function fillFormViaPlaywright(opts) {
   for (let i = 0; i < opts.fields.length; i++) {
     const field = opts.fields[i];
     const ref = field.ref.trim();
-    const type = field.type.trim();
+    const type = (typeof field.type === "string" ? field.type.trim() : "") || "text";
     const rawValue = field.value;
     const value = rawValue == null ? "" : String(rawValue);
     if (!ref) throw new Error(`fill(): field at index ${i} has empty ref`);
-    if (!type) throw new Error(`fill(): field "${ref}" has empty type`);
     const locator = refLocator(page, ref);
     if (type === "checkbox" || type === "radio") {
       const checked = rawValue === true || rawValue === 1 || rawValue === "1" || rawValue === "true";
@@ -1330,6 +1546,7 @@ async function setInputFilesViaPlaywright(opts) {
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
   const locator = opts.ref ? refLocator(page, opts.ref) : opts.element ? page.locator(opts.element).first() : null;
   if (!locator) throw new Error("Either ref or element is required for setInputFiles");
+  await assertSafeUploadPaths(opts.paths);
   try {
     await locator.setInputFiles(opts.paths);
   } catch (err) {
@@ -1373,7 +1590,9 @@ async function armFileUploadViaPlaywright(opts) {
     const handler = async (fc) => {
       clearTimeout(timer);
       try {
-        await fc.setFiles(opts.paths ?? []);
+        const paths = opts.paths ?? [];
+        if (paths.length > 0) await assertSafeUploadPaths(paths);
+        await fc.setFiles(paths);
         resolve2();
       } catch (err) {
         reject(err);
@@ -1391,183 +1610,6 @@ async function pressKeyViaPlaywright(opts) {
   ensurePageState(page);
   await page.keyboard.press(key, { delay: Math.max(0, Math.floor(opts.delayMs ?? 0)) });
 }
-var InvalidBrowserNavigationUrlError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidBrowserNavigationUrlError";
-  }
-};
-function withBrowserNavigationPolicy(ssrfPolicy) {
-  return { ssrfPolicy };
-}
-var NETWORK_NAVIGATION_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
-var SAFE_NON_NETWORK_URLS = /* @__PURE__ */ new Set(["about:blank"]);
-async function assertBrowserNavigationAllowed(opts) {
-  const rawUrl = String(opts.url ?? "").trim();
-  let parsed;
-  try {
-    parsed = new URL(rawUrl);
-  } catch {
-    throw new InvalidBrowserNavigationUrlError(`Invalid URL: "${rawUrl}"`);
-  }
-  if (!NETWORK_NAVIGATION_PROTOCOLS.has(parsed.protocol)) {
-    if (SAFE_NON_NETWORK_URLS.has(parsed.href)) return;
-    throw new InvalidBrowserNavigationUrlError(`Navigation blocked: unsupported protocol "${parsed.protocol}"`);
-  }
-  const policy = opts.ssrfPolicy;
-  if (policy?.dangerouslyAllowPrivateNetwork ?? policy?.allowPrivateNetwork ?? true) return;
-  const allowedHostnames = [
-    ...policy?.allowedHostnames ?? [],
-    ...policy?.hostnameAllowlist ?? []
-  ];
-  if (allowedHostnames.length) {
-    const hostname = parsed.hostname.toLowerCase();
-    if (allowedHostnames.some((h) => h.toLowerCase() === hostname)) return;
-  }
-  if (await isInternalUrlResolved(rawUrl, opts.lookupFn)) {
-    throw new InvalidBrowserNavigationUrlError(
-      `Navigation to internal/loopback address blocked: "${rawUrl}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
-    );
-  }
-}
-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 expandIPv6(ip) {
-  let normalized = ip;
-  const v4Match = normalized.match(/^(.+:)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
-  if (v4Match) {
-    const octets = v4Match[2].split(".").map(Number);
-    if (octets.some((o) => o > 255)) return null;
-    const hexHi = (octets[0] << 8 | octets[1]).toString(16).padStart(4, "0");
-    const hexLo = (octets[2] << 8 | octets[3]).toString(16).padStart(4, "0");
-    normalized = v4Match[1] + hexHi + ":" + hexLo;
-  }
-  const halves = normalized.split("::");
-  if (halves.length > 2) return null;
-  if (halves.length === 2) {
-    const left = halves[0] !== "" ? halves[0].split(":") : [];
-    const right = halves[1] !== "" ? halves[1].split(":") : [];
-    const needed = 8 - left.length - right.length;
-    if (needed < 0) return null;
-    const groups2 = [...left, ...Array(needed).fill("0"), ...right];
-    if (groups2.length !== 8) return null;
-    return groups2.map((g) => g.padStart(4, "0")).join(":");
-  }
-  const groups = normalized.split(":");
-  if (groups.length !== 8) return null;
-  return groups.map((g) => g.padStart(4, "0")).join(":");
-}
-function hexToIPv4(hiHex, loHex) {
-  const hi = parseInt(hiHex, 16);
-  const lo = parseInt(loHex, 16);
-  return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
-}
-function extractEmbeddedIPv4(lower) {
-  if (lower.startsWith("::ffff:")) {
-    return lower.slice(7);
-  }
-  const expanded = expandIPv6(lower);
-  if (expanded === null) return "";
-  const groups = expanded.split(":");
-  if (groups.length !== 8) return "";
-  if (groups[0] === "0064" && groups[1] === "ff9b" && groups[2] === "0000" && groups[3] === "0000" && groups[4] === "0000" && groups[5] === "0000") {
-    return hexToIPv4(groups[6], groups[7]);
-  }
-  if (groups[0] === "0064" && groups[1] === "ff9b" && groups[2] === "0001") {
-    return hexToIPv4(groups[6], groups[7]);
-  }
-  if (groups[0] === "2002") {
-    return hexToIPv4(groups[1], groups[2]);
-  }
-  if (groups[0] === "2001" && groups[1] === "0000") {
-    const hiXored = (parseInt(groups[6], 16) ^ 65535).toString(16).padStart(4, "0");
-    const loXored = (parseInt(groups[7], 16) ^ 65535).toString(16).padStart(4, "0");
-    return hexToIPv4(hiXored, loXored);
-  }
-  return null;
-}
-function isStrictDecimalOctet(part) {
-  if (!/^[0-9]+$/.test(part)) return false;
-  const n = parseInt(part, 10);
-  if (n < 0 || n > 255) return false;
-  if (String(n) !== part) return false;
-  return true;
-}
-function isUnsupportedIPv4Literal(ip) {
-  if (/^[0-9]+$/.test(ip)) return true;
-  const parts = ip.split(".");
-  if (parts.length !== 4) return true;
-  if (!parts.every(isStrictDecimalOctet)) return true;
-  return false;
-}
-function isInternalIP(ip) {
-  if (!ip.includes(":") && isUnsupportedIPv4Literal(ip)) return true;
-  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;
-  const embedded = extractEmbeddedIPv4(lower);
-  if (embedded !== null) {
-    if (embedded === "") return true;
-    return isInternalIP(embedded);
-  }
-  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, lookupFn = promises.lookup) {
-  if (isInternalUrl(url)) return true;
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return true;
-  }
-  try {
-    const { address } = await lookupFn(parsed.hostname);
-    if (isInternalIP(address)) return true;
-  } catch {
-    return true;
-  }
-  return false;
-}
 
 // src/actions/navigation.ts
 async function navigateViaPlaywright(opts) {
@@ -1759,7 +1801,7 @@ async function evaluateViaPlaywright(opts) {
 
 // src/actions/download.ts
 async function downloadViaPlaywright(opts) {
-  assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
+  await 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 });
@@ -1786,7 +1828,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 assertSafeOutputPath(savePath, opts.allowedOutputRoots);
   await download.saveAs(savePath);
   return {
     url: download.url(),
@@ -1970,7 +2012,7 @@ async function traceStartViaPlaywright(opts) {
   });
 }
 async function traceStopViaPlaywright(opts) {
-  assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
+  await assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const context = page.context();