browserclaw 0.4.0 → 0.4.2

package/dist/index.d.cts

@@ -1136,6 +1136,12 @@ declare class BrowserClaw {
     stop(): Promise<void>;
 }
 
+/**
+ * Convert a WebSocket CDP URL to an HTTP base URL for `/json/*` endpoints.
+ */
+declare function normalizeCdpHttpBaseForJsonEndpoints(cdpUrl: string): string;
+declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<boolean>;
+declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<string | null>;
 declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number): Promise<boolean>;
 
 type LookupFn = typeof lookup;
@@ -1151,6 +1157,11 @@ declare class InvalidBrowserNavigationUrlError extends Error {
 type BrowserNavigationPolicyOptions = {
     ssrfPolicy?: SsrfPolicy;
 };
+/** Playwright-compatible request interface for redirect chain inspection. */
+type BrowserNavigationRequestLike = {
+    url(): string;
+    redirectedFrom(): BrowserNavigationRequestLike | null;
+};
 /** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
 declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
 /**
@@ -1161,5 +1172,31 @@ declare function assertBrowserNavigationAllowed(opts: {
     url: string;
     lookupFn?: LookupFn;
 } & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Best-effort post-navigation guard for the final page URL.
+ * Only validates http/https URLs and about:blank — swallows errors on
+ * unparseable URLs and non-network protocols (e.g. chrome-error://) to avoid
+ * false positives on browser-internal error pages.
+ *
+ * Call this after `page.goto()` to catch redirect-based SSRF bypasses.
+ */
+declare function assertBrowserNavigationResultAllowed(opts: {
+    url: string;
+    lookupFn?: LookupFn;
+} & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Walk the full redirect chain and validate each hop against the SSRF policy.
+ * Call this after `page.goto()` with `response?.request()` to catch intermediate
+ * redirects that resolve to private/internal addresses.
+ */
+declare function assertBrowserNavigationRedirectChainAllowed(opts: {
+    request?: BrowserNavigationRequestLike | null;
+    lookupFn?: LookupFn;
+} & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Returns true if the SSRF policy requires redirect chain inspection
+ * (i.e. strict mode where private network is blocked).
+ */
+declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: SsrfPolicy): boolean;
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, isChromeCdpReady, withBrowserNavigationPolicy };
+export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, getChromeWebSocketUrl, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, requiresInspectableBrowserNavigationRedirects, withBrowserNavigationPolicy };

package/dist/index.d.ts

@@ -1136,6 +1136,12 @@ declare class BrowserClaw {
     stop(): Promise<void>;
 }
 
+/**
+ * Convert a WebSocket CDP URL to an HTTP base URL for `/json/*` endpoints.
+ */
+declare function normalizeCdpHttpBaseForJsonEndpoints(cdpUrl: string): string;
+declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<boolean>;
+declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<string | null>;
 declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number): Promise<boolean>;
 
 type LookupFn = typeof lookup;
@@ -1151,6 +1157,11 @@ declare class InvalidBrowserNavigationUrlError extends Error {
 type BrowserNavigationPolicyOptions = {
     ssrfPolicy?: SsrfPolicy;
 };
+/** Playwright-compatible request interface for redirect chain inspection. */
+type BrowserNavigationRequestLike = {
+    url(): string;
+    redirectedFrom(): BrowserNavigationRequestLike | null;
+};
 /** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
 declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
 /**
@@ -1161,5 +1172,31 @@ declare function assertBrowserNavigationAllowed(opts: {
     url: string;
     lookupFn?: LookupFn;
 } & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Best-effort post-navigation guard for the final page URL.
+ * Only validates http/https URLs and about:blank — swallows errors on
+ * unparseable URLs and non-network protocols (e.g. chrome-error://) to avoid
+ * false positives on browser-internal error pages.
+ *
+ * Call this after `page.goto()` to catch redirect-based SSRF bypasses.
+ */
+declare function assertBrowserNavigationResultAllowed(opts: {
+    url: string;
+    lookupFn?: LookupFn;
+} & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Walk the full redirect chain and validate each hop against the SSRF policy.
+ * Call this after `page.goto()` with `response?.request()` to catch intermediate
+ * redirects that resolve to private/internal addresses.
+ */
+declare function assertBrowserNavigationRedirectChainAllowed(opts: {
+    request?: BrowserNavigationRequestLike | null;
+    lookupFn?: LookupFn;
+} & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Returns true if the SSRF policy requires redirect chain inspection
+ * (i.e. strict mode where private network is blocked).
+ */
+declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: SsrfPolicy): boolean;
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, isChromeCdpReady, withBrowserNavigationPolicy };
+export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, getChromeWebSocketUrl, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, requiresInspectableBrowserNavigationRedirects, withBrowserNavigationPolicy };

package/dist/index.js

@@ -340,39 +340,109 @@ 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, authToken) {
-  const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+function isWebSocketUrl(url) {
   try {
-    const headers = {};
-    if (authToken) headers["Authorization"] = `Bearer ${authToken}`;
-    const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal, headers });
-    if (!res.ok) return false;
-    const data = await res.json();
-    return data != null && typeof data === "object";
+    const parsed = new URL(url);
+    return parsed.protocol === "ws:" || parsed.protocol === "wss:";
   } catch {
     return false;
-  } finally {
-    clearTimeout(t);
   }
 }
-async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500, authToken) {
+function isLoopbackHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
+}
+function normalizeCdpWsUrl(wsUrl, cdpUrl) {
+  const ws = new URL(wsUrl);
+  const cdp = new URL(cdpUrl);
+  const isWildcardBind = ws.hostname === "0.0.0.0" || ws.hostname === "[::]";
+  if ((isLoopbackHost(ws.hostname) || isWildcardBind) && !isLoopbackHost(cdp.hostname)) {
+    ws.hostname = cdp.hostname;
+    const cdpPort = cdp.port || (cdp.protocol === "https:" ? "443" : "80");
+    ws.port = cdpPort;
+    ws.protocol = cdp.protocol === "https:" ? "wss:" : "ws:";
+  }
+  if (cdp.protocol === "https:" && ws.protocol === "ws:") ws.protocol = "wss:";
+  if (!ws.username && !ws.password && (cdp.username || cdp.password)) {
+    ws.username = cdp.username;
+    ws.password = cdp.password;
+  }
+  for (const [key, value] of cdp.searchParams.entries()) {
+    if (!ws.searchParams.has(key)) ws.searchParams.append(key, value);
+  }
+  return ws.toString();
+}
+function normalizeCdpHttpBaseForJsonEndpoints(cdpUrl) {
+  try {
+    const url = new URL(cdpUrl);
+    if (url.protocol === "ws:") url.protocol = "http:";
+    else if (url.protocol === "wss:") url.protocol = "https:";
+    url.pathname = url.pathname.replace(/\/devtools\/browser\/.*$/, "");
+    url.pathname = url.pathname.replace(/\/cdp$/, "");
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return cdpUrl.replace(/^ws:/, "http:").replace(/^wss:/, "https:").replace(/\/devtools\/browser\/.*$/, "").replace(/\/cdp$/, "").replace(/\/$/, "");
+  }
+}
+function appendCdpPath(cdpUrl, cdpPath) {
+  const url = new URL(cdpUrl);
+  url.pathname = `${url.pathname.replace(/\/$/, "")}${cdpPath.startsWith("/") ? cdpPath : `/${cdpPath}`}`;
+  return url.toString();
+}
+async function canOpenWebSocket(url, timeoutMs) {
+  return new Promise((resolve2) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        ws.close();
+      } catch {
+      }
+      resolve2(value);
+    };
+    const timer = setTimeout(() => finish(false), Math.max(50, timeoutMs + 25));
+    let ws;
+    try {
+      ws = new WebSocket(url);
+    } catch {
+      finish(false);
+      return;
+    }
+    ws.onopen = () => finish(true);
+    ws.onerror = () => finish(false);
+  });
+}
+async function fetchChromeVersion(cdpUrl, timeoutMs = 500, authToken) {
   const ctrl = new AbortController();
   const t = setTimeout(() => ctrl.abort(), timeoutMs);
   try {
+    const httpBase = isWebSocketUrl(cdpUrl) ? normalizeCdpHttpBaseForJsonEndpoints(cdpUrl) : cdpUrl;
     const headers = {};
     if (authToken) headers["Authorization"] = `Bearer ${authToken}`;
-    const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal, headers });
+    const res = await fetch(appendCdpPath(httpBase, "/json/version"), { signal: ctrl.signal, headers });
     if (!res.ok) return null;
     const data = await res.json();
     if (!data || typeof data !== "object") return null;
-    return String(data?.webSocketDebuggerUrl ?? "").trim() || null;
+    return data;
   } catch {
     return null;
   } finally {
     clearTimeout(t);
   }
 }
+async function isChromeReachable(cdpUrl, timeoutMs = 500, authToken) {
+  if (isWebSocketUrl(cdpUrl)) return await canOpenWebSocket(cdpUrl, timeoutMs);
+  const version = await fetchChromeVersion(cdpUrl, timeoutMs, authToken);
+  return Boolean(version);
+}
+async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500, authToken) {
+  if (isWebSocketUrl(cdpUrl)) return cdpUrl;
+  const version = await fetchChromeVersion(cdpUrl, timeoutMs, authToken);
+  const wsUrl = String(version?.webSocketDebuggerUrl ?? "").trim();
+  if (!wsUrl) return null;
+  return normalizeCdpWsUrl(wsUrl, cdpUrl);
+}
 async function isChromeCdpReady(cdpUrl, timeoutMs = 500, handshakeTimeoutMs = 800) {
   const wsUrl = await getChromeWebSocketUrl(cdpUrl, timeoutMs);
   if (!wsUrl) return false;
@@ -770,7 +840,7 @@ async function findPageByTargetId(browser, targetId, cdpUrl) {
   }
   if (cdpUrl) {
     try {
-      const listUrl = `${cdpUrl.replace(/\/+$/, "").replace(/^ws:/, "http:").replace(/\/cdp$/, "")}/json/list`;
+      const listUrl = `${normalizeCdpHttpBaseForJsonEndpoints(cdpUrl)}/json/list`;
       const headers = {};
       if (cached?.authToken) headers["Authorization"] = `Bearer ${cached.authToken}`;
       const response = await fetch(listUrl, { headers });
@@ -1258,6 +1328,20 @@ function withBrowserNavigationPolicy(ssrfPolicy) {
 }
 var NETWORK_NAVIGATION_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
 var SAFE_NON_NETWORK_URLS = /* @__PURE__ */ new Set(["about:blank"]);
+var PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
+function isAllowedNonNetworkNavigationUrl(parsed) {
+  return SAFE_NON_NETWORK_URLS.has(parsed.href);
+}
+function isPrivateNetworkAllowedByPolicy(policy) {
+  return policy?.dangerouslyAllowPrivateNetwork === true || policy?.allowPrivateNetwork === true;
+}
+function hasProxyEnvConfigured(env = process.env) {
+  for (const key of PROXY_ENV_KEYS) {
+    const value = env[key];
+    if (typeof value === "string" && value.trim().length > 0) return true;
+  }
+  return false;
+}
 async function assertBrowserNavigationAllowed(opts) {
   const rawUrl = String(opts.url ?? "").trim();
   let parsed;
@@ -1267,9 +1351,14 @@ async function assertBrowserNavigationAllowed(opts) {
     throw new InvalidBrowserNavigationUrlError(`Invalid URL: "${rawUrl}"`);
   }
   if (!NETWORK_NAVIGATION_PROTOCOLS.has(parsed.protocol)) {
-    if (SAFE_NON_NETWORK_URLS.has(parsed.href)) return;
+    if (isAllowedNonNetworkNavigationUrl(parsed)) return;
     throw new InvalidBrowserNavigationUrlError(`Navigation blocked: unsupported protocol "${parsed.protocol}"`);
   }
+  if (hasProxyEnvConfigured() && !isPrivateNetworkAllowedByPolicy(opts.ssrfPolicy)) {
+    throw new InvalidBrowserNavigationUrlError(
+      "Navigation blocked: strict browser SSRF policy cannot be enforced while env proxy variables are set"
+    );
+  }
   const policy = opts.ssrfPolicy;
   if (policy?.dangerouslyAllowPrivateNetwork ?? policy?.allowPrivateNetwork ?? true) return;
   const allowedHostnames = [
@@ -1474,10 +1563,24 @@ async function assertBrowserNavigationResultAllowed(opts) {
   } catch {
     return;
   }
-  if (NETWORK_NAVIGATION_PROTOCOLS.has(parsed.protocol) || SAFE_NON_NETWORK_URLS.has(parsed.href)) {
+  if (NETWORK_NAVIGATION_PROTOCOLS.has(parsed.protocol) || isAllowedNonNetworkNavigationUrl(parsed)) {
     await assertBrowserNavigationAllowed(opts);
   }
 }
+async function assertBrowserNavigationRedirectChainAllowed(opts) {
+  const chain = [];
+  let current = opts.request ?? null;
+  while (current) {
+    chain.push(current.url());
+    current = current.redirectedFrom();
+  }
+  for (const url of [...chain].reverse()) {
+    await assertBrowserNavigationAllowed({ url, lookupFn: opts.lookupFn, ssrfPolicy: opts.ssrfPolicy });
+  }
+}
+function requiresInspectableBrowserNavigationRedirects(ssrfPolicy) {
+  return !isPrivateNetworkAllowedByPolicy(ssrfPolicy);
+}
 
 // src/actions/interaction.ts
 async function clickViaPlaywright(opts) {
@@ -1682,7 +1785,8 @@ async function navigateViaPlaywright(opts) {
   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) });
+  const response = await page.goto(url, { timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4) });
+  await assertBrowserNavigationRedirectChainAllowed({ request: response?.request(), ...withBrowserNavigationPolicy(policy) });
   const finalUrl = page.url();
   await assertBrowserNavigationResultAllowed({ url: finalUrl, ssrfPolicy: policy });
   return { url: finalUrl };
@@ -1713,7 +1817,9 @@ async function createPageViaPlaywright(opts) {
   const page = await context.newPage();
   ensurePageState(page);
   if (targetUrl !== "about:blank") {
-    await page.goto(targetUrl, { timeout: normalizeTimeoutMs(void 0, 2e4) });
+    const navigationPolicy = withBrowserNavigationPolicy(policy);
+    const response = await page.goto(targetUrl, { timeout: normalizeTimeoutMs(void 0, 2e4) });
+    await assertBrowserNavigationRedirectChainAllowed({ request: response?.request(), ...navigationPolicy });
     await assertBrowserNavigationResultAllowed({ url: page.url(), ssrfPolicy: policy });
   }
   const tid = await pageTargetId(page).catch(() => null);
@@ -3239,6 +3345,6 @@ var BrowserClaw = class _BrowserClaw {
   }
 };
 
-export { BrowserClaw, CrawlPage, InvalidBrowserNavigationUrlError, assertBrowserNavigationAllowed, isChromeCdpReady, withBrowserNavigationPolicy };
+export { BrowserClaw, CrawlPage, InvalidBrowserNavigationUrlError, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, getChromeWebSocketUrl, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, requiresInspectableBrowserNavigationRedirects, withBrowserNavigationPolicy };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map