browserclaw 0.4.2 → 0.5.0

package/dist/index.d.cts

@@ -1,4 +1,7 @@
 import * as playwright_core from 'playwright-core';
+import { BrowserContext } from 'playwright-core';
+import * as node_dns from 'node:dns';
+import { lookup as lookup$1 } from 'node:dns';
 import { lookup } from 'node:dns/promises';
 
 interface FrameEvalResult {
@@ -414,6 +417,16 @@ interface HttpCredentials {
     /** Clear HTTP credentials */
     clear?: boolean;
 }
+/** @internal */
+interface ContextState {
+    traceActive: boolean;
+}
+/** Result of DNS pinning resolution — hostname locked to resolved addresses. */
+interface PinnedHostname {
+    hostname: string;
+    addresses: string[];
+    lookup: typeof node_dns.lookup;
+}
 
 /**
  * Represents a single browser page/tab with ref-based automation.
@@ -1164,6 +1177,23 @@ type BrowserNavigationRequestLike = {
 };
 /** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
 declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
+/**
+ * Create a pinned DNS lookup function that always resolves to the pre-resolved
+ * addresses for the given hostname. Falls back to real DNS for other hostnames.
+ */
+declare function createPinnedLookup(params: {
+    hostname: string;
+    addresses: string[];
+    fallback?: typeof lookup$1;
+}): typeof lookup$1;
+/**
+ * Resolve DNS for a hostname and validate resolved addresses against SSRF policy.
+ * Returns a PinnedHostname with pre-resolved addresses and a pinned lookup function.
+ */
+declare function resolvePinnedHostnameWithPolicy(hostname: string, params?: {
+    lookupFn?: LookupFn;
+    policy?: SsrfPolicy;
+}): Promise<PinnedHostname>;
 /**
  * Assert that a URL is allowed for browser navigation under the given SSRF policy.
  * Throws `InvalidBrowserNavigationUrlError` if the URL is blocked.
@@ -1172,13 +1202,22 @@ declare function assertBrowserNavigationAllowed(opts: {
     url: string;
     lookupFn?: LookupFn;
 } & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Sanitize an untrusted file name (e.g. from a download) to prevent path traversal.
+ */
+declare function sanitizeUntrustedFileName(fileName: string, fallbackName: string): string;
+/**
+ * Write a file atomically via a sibling temp path.
+ * The writeTemp callback should write the content to tempPath.
+ * After writeTemp completes, the temp file is renamed to the target path.
+ */
+declare function writeViaSiblingTempPath(params: {
+    rootDir: string;
+    targetPath: string;
+    writeTemp: (tempPath: string) => Promise<void>;
+}): 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;
@@ -1186,17 +1225,26 @@ declare function assertBrowserNavigationResultAllowed(opts: {
 } & 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).
+ * Returns true if the SSRF policy requires redirect chain inspection.
  */
 declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: SsrfPolicy): boolean;
 
-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 };
+declare function ensureContextState(context: BrowserContext): ContextState;
+/**
+ * Force-disconnect a Playwright browser connection for a given CDP target.
+ * Clears the connection cache, sends Runtime.terminateExecution via CDP
+ * session to kill stuck evals, and closes the browser.
+ */
+declare function forceDisconnectPlaywrightForTarget(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    reason?: string;
+}): Promise<void>;
+
+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 ContextState, 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 PinnedHostname, 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, createPinnedLookup, ensureContextState, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, requiresInspectableBrowserNavigationRedirects, resolvePinnedHostnameWithPolicy, sanitizeUntrustedFileName, withBrowserNavigationPolicy, writeViaSiblingTempPath };

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 import * as playwright_core from 'playwright-core';
+import { BrowserContext } from 'playwright-core';
+import * as node_dns from 'node:dns';
+import { lookup as lookup$1 } from 'node:dns';
 import { lookup } from 'node:dns/promises';
 
 interface FrameEvalResult {
@@ -414,6 +417,16 @@ interface HttpCredentials {
     /** Clear HTTP credentials */
     clear?: boolean;
 }
+/** @internal */
+interface ContextState {
+    traceActive: boolean;
+}
+/** Result of DNS pinning resolution — hostname locked to resolved addresses. */
+interface PinnedHostname {
+    hostname: string;
+    addresses: string[];
+    lookup: typeof node_dns.lookup;
+}
 
 /**
  * Represents a single browser page/tab with ref-based automation.
@@ -1164,6 +1177,23 @@ type BrowserNavigationRequestLike = {
 };
 /** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
 declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
+/**
+ * Create a pinned DNS lookup function that always resolves to the pre-resolved
+ * addresses for the given hostname. Falls back to real DNS for other hostnames.
+ */
+declare function createPinnedLookup(params: {
+    hostname: string;
+    addresses: string[];
+    fallback?: typeof lookup$1;
+}): typeof lookup$1;
+/**
+ * Resolve DNS for a hostname and validate resolved addresses against SSRF policy.
+ * Returns a PinnedHostname with pre-resolved addresses and a pinned lookup function.
+ */
+declare function resolvePinnedHostnameWithPolicy(hostname: string, params?: {
+    lookupFn?: LookupFn;
+    policy?: SsrfPolicy;
+}): Promise<PinnedHostname>;
 /**
  * Assert that a URL is allowed for browser navigation under the given SSRF policy.
  * Throws `InvalidBrowserNavigationUrlError` if the URL is blocked.
@@ -1172,13 +1202,22 @@ declare function assertBrowserNavigationAllowed(opts: {
     url: string;
     lookupFn?: LookupFn;
 } & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Sanitize an untrusted file name (e.g. from a download) to prevent path traversal.
+ */
+declare function sanitizeUntrustedFileName(fileName: string, fallbackName: string): string;
+/**
+ * Write a file atomically via a sibling temp path.
+ * The writeTemp callback should write the content to tempPath.
+ * After writeTemp completes, the temp file is renamed to the target path.
+ */
+declare function writeViaSiblingTempPath(params: {
+    rootDir: string;
+    targetPath: string;
+    writeTemp: (tempPath: string) => Promise<void>;
+}): 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;
@@ -1186,17 +1225,26 @@ declare function assertBrowserNavigationResultAllowed(opts: {
 } & 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).
+ * Returns true if the SSRF policy requires redirect chain inspection.
  */
 declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: SsrfPolicy): boolean;
 
-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 };
+declare function ensureContextState(context: BrowserContext): ContextState;
+/**
+ * Force-disconnect a Playwright browser connection for a given CDP target.
+ * Clears the connection cache, sends Runtime.terminateExecution via CDP
+ * session to kill stuck evals, and closes the browser.
+ */
+declare function forceDisconnectPlaywrightForTarget(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    reason?: string;
+}): Promise<void>;
+
+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 ContextState, 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 PinnedHostname, 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, createPinnedLookup, ensureContextState, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, requiresInspectableBrowserNavigationRedirects, resolvePinnedHostnameWithPolicy, sanitizeUntrustedFileName, withBrowserNavigationPolicy, writeViaSiblingTempPath };