browserclaw 0.2.2 → 0.2.4

package/dist/index.d.cts

@@ -33,6 +33,27 @@ interface LaunchOptions {
     profileColor?: string;
     /** Additional Chrome command-line arguments (e.g. `['--start-maximized']`). */
     chromeArgs?: string[];
+    /**
+     * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
+     * Default: `false` — internal URLs are blocked to prevent SSRF attacks.
+     * Set to `true` if you need to access local development servers.
+     */
+    allowInternal?: boolean;
+}
+/** Options for connecting to an existing browser instance. */
+interface ConnectOptions {
+    /**
+     * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
+     * Default: `false` — internal URLs are blocked to prevent SSRF attacks.
+     * Set to `true` if you need to access local development servers.
+     */
+    allowInternal?: boolean;
+    /**
+     * Bearer token for authenticating with the CDP endpoint.
+     * Required when connecting to a browser instance that has auth enabled
+     * (e.g. OpenClaw browser control with gateway.auth.token).
+     */
+    authToken?: string;
 }
 /**
  * Describes a single interactive element found during a snapshot.
@@ -48,6 +69,19 @@ interface RoleRefInfo {
 }
 /** Map of ref IDs (e.g. `'e1'`, `'e2'`) to their element information. */
 type RoleRefs = Record<string, RoleRefInfo>;
+/**
+ * Metadata about the source of untrusted external content.
+ * Used by consumers (e.g. OpenClaw) to wrap browser outputs with
+ * structured external-content markers for prompt-injection mitigation.
+ */
+interface UntrustedContentMeta {
+    /** The source URL of the content at the time of capture */
+    sourceUrl?: string;
+    /** Content type identifier (e.g. `'browser-snapshot'`, `'browser-aria-tree'`) */
+    contentType: string;
+    /** ISO 8601 timestamp of when the content was captured */
+    capturedAt: string;
+}
 /** Result of taking a page snapshot. */
 interface SnapshotResult {
     /** AI-readable text representation of the page with numbered refs */
@@ -56,6 +90,14 @@ interface SnapshotResult {
     refs: RoleRefs;
     /** Statistics about the snapshot */
     stats?: SnapshotStats;
+    /**
+     * Indicates this content originates from an untrusted external source (the web page).
+     * AI agents should treat snapshot content as potentially adversarial
+     * (e.g. prompt injection via page text). Always `true` for browser snapshots.
+     */
+    untrusted?: true;
+    /** Structured metadata about the untrusted content source */
+    contentMeta?: UntrustedContentMeta;
 }
 /** Statistics about a snapshot's content. */
 interface SnapshotStats {
@@ -110,6 +152,13 @@ interface AriaNode {
 interface AriaSnapshotResult {
     /** Flat list of accessibility tree nodes */
     nodes: AriaNode[];
+    /**
+     * Indicates this content originates from an untrusted external source (the web page).
+     * AI agents should treat snapshot content as potentially adversarial. Always `true`.
+     */
+    untrusted?: true;
+    /** Structured metadata about the untrusted content source */
+    contentMeta?: UntrustedContentMeta;
 }
 /** A form field to fill as part of a batch `fill()` operation. */
 interface FormField {
@@ -341,8 +390,9 @@ interface HttpCredentials {
 declare class CrawlPage {
     private readonly cdpUrl;
     private readonly targetId;
+    private readonly allowInternal;
     /** @internal */
-    constructor(cdpUrl: string, targetId: string);
+    constructor(cdpUrl: string, targetId: string, allowInternal?: boolean);
     /** The CDP target ID for this page. Use this to identify the page in multi-tab scenarios. */
     get id(): string;
     /**
@@ -699,8 +749,11 @@ declare class CrawlPage {
      * 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)
      */
-    traceStop(path: string): Promise<void>;
+    traceStop(path: string, opts?: {
+        allowedOutputRoots?: string[];
+    }): Promise<void>;
     /**
      * Wait for a network response matching a URL pattern and return its body.
      *
@@ -824,6 +877,7 @@ declare class CrawlPage {
      */
     download(ref: string, path: string, opts?: {
         timeoutMs?: number;
+        allowedOutputRoots?: string[];
     }): Promise<DownloadResult>;
     /**
      * Wait for the next download event (without clicking).
@@ -836,6 +890,7 @@ declare class CrawlPage {
     waitForDownload(opts?: {
         path?: string;
         timeoutMs?: number;
+        allowedOutputRoots?: string[];
     }): Promise<DownloadResult>;
     /**
      * Set the browser to offline or online mode.
@@ -932,6 +987,7 @@ declare class CrawlPage {
  */
 declare class BrowserClaw {
     private readonly cdpUrl;
+    private readonly allowInternal;
     private chrome;
     private constructor();
     /**
@@ -972,7 +1028,7 @@ declare class BrowserClaw {
      * const browser = await BrowserClaw.connect('http://localhost:9222');
      * ```
      */
-    static connect(cdpUrl: string): Promise<BrowserClaw>;
+    static connect(cdpUrl: string, opts?: ConnectOptions): Promise<BrowserClaw>;
     /**
      * Open a URL in a new tab and return the page handle.
      *
@@ -1031,4 +1087,4 @@ declare class BrowserClaw {
     stop(): Promise<void>;
 }
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, type LaunchOptions, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type StorageKind, type TraceStartOptions, type TypeOptions, type WaitOptions };
+export { type AriaNode, type AriaSnapshotResult, BrowserClaw, 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, type LaunchOptions, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions };

package/dist/index.d.ts

@@ -33,6 +33,27 @@ interface LaunchOptions {
     profileColor?: string;
     /** Additional Chrome command-line arguments (e.g. `['--start-maximized']`). */
     chromeArgs?: string[];
+    /**
+     * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
+     * Default: `false` — internal URLs are blocked to prevent SSRF attacks.
+     * Set to `true` if you need to access local development servers.
+     */
+    allowInternal?: boolean;
+}
+/** Options for connecting to an existing browser instance. */
+interface ConnectOptions {
+    /**
+     * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
+     * Default: `false` — internal URLs are blocked to prevent SSRF attacks.
+     * Set to `true` if you need to access local development servers.
+     */
+    allowInternal?: boolean;
+    /**
+     * Bearer token for authenticating with the CDP endpoint.
+     * Required when connecting to a browser instance that has auth enabled
+     * (e.g. OpenClaw browser control with gateway.auth.token).
+     */
+    authToken?: string;
 }
 /**
  * Describes a single interactive element found during a snapshot.
@@ -48,6 +69,19 @@ interface RoleRefInfo {
 }
 /** Map of ref IDs (e.g. `'e1'`, `'e2'`) to their element information. */
 type RoleRefs = Record<string, RoleRefInfo>;
+/**
+ * Metadata about the source of untrusted external content.
+ * Used by consumers (e.g. OpenClaw) to wrap browser outputs with
+ * structured external-content markers for prompt-injection mitigation.
+ */
+interface UntrustedContentMeta {
+    /** The source URL of the content at the time of capture */
+    sourceUrl?: string;
+    /** Content type identifier (e.g. `'browser-snapshot'`, `'browser-aria-tree'`) */
+    contentType: string;
+    /** ISO 8601 timestamp of when the content was captured */
+    capturedAt: string;
+}
 /** Result of taking a page snapshot. */
 interface SnapshotResult {
     /** AI-readable text representation of the page with numbered refs */
@@ -56,6 +90,14 @@ interface SnapshotResult {
     refs: RoleRefs;
     /** Statistics about the snapshot */
     stats?: SnapshotStats;
+    /**
+     * Indicates this content originates from an untrusted external source (the web page).
+     * AI agents should treat snapshot content as potentially adversarial
+     * (e.g. prompt injection via page text). Always `true` for browser snapshots.
+     */
+    untrusted?: true;
+    /** Structured metadata about the untrusted content source */
+    contentMeta?: UntrustedContentMeta;
 }
 /** Statistics about a snapshot's content. */
 interface SnapshotStats {
@@ -110,6 +152,13 @@ interface AriaNode {
 interface AriaSnapshotResult {
     /** Flat list of accessibility tree nodes */
     nodes: AriaNode[];
+    /**
+     * Indicates this content originates from an untrusted external source (the web page).
+     * AI agents should treat snapshot content as potentially adversarial. Always `true`.
+     */
+    untrusted?: true;
+    /** Structured metadata about the untrusted content source */
+    contentMeta?: UntrustedContentMeta;
 }
 /** A form field to fill as part of a batch `fill()` operation. */
 interface FormField {
@@ -341,8 +390,9 @@ interface HttpCredentials {
 declare class CrawlPage {
     private readonly cdpUrl;
     private readonly targetId;
+    private readonly allowInternal;
     /** @internal */
-    constructor(cdpUrl: string, targetId: string);
+    constructor(cdpUrl: string, targetId: string, allowInternal?: boolean);
     /** The CDP target ID for this page. Use this to identify the page in multi-tab scenarios. */
     get id(): string;
     /**
@@ -699,8 +749,11 @@ declare class CrawlPage {
      * 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)
      */
-    traceStop(path: string): Promise<void>;
+    traceStop(path: string, opts?: {
+        allowedOutputRoots?: string[];
+    }): Promise<void>;
     /**
      * Wait for a network response matching a URL pattern and return its body.
      *
@@ -824,6 +877,7 @@ declare class CrawlPage {
      */
     download(ref: string, path: string, opts?: {
         timeoutMs?: number;
+        allowedOutputRoots?: string[];
     }): Promise<DownloadResult>;
     /**
      * Wait for the next download event (without clicking).
@@ -836,6 +890,7 @@ declare class CrawlPage {
     waitForDownload(opts?: {
         path?: string;
         timeoutMs?: number;
+        allowedOutputRoots?: string[];
     }): Promise<DownloadResult>;
     /**
      * Set the browser to offline or online mode.
@@ -932,6 +987,7 @@ declare class CrawlPage {
  */
 declare class BrowserClaw {
     private readonly cdpUrl;
+    private readonly allowInternal;
     private chrome;
     private constructor();
     /**
@@ -972,7 +1028,7 @@ declare class BrowserClaw {
      * const browser = await BrowserClaw.connect('http://localhost:9222');
      * ```
      */
-    static connect(cdpUrl: string): Promise<BrowserClaw>;
+    static connect(cdpUrl: string, opts?: ConnectOptions): Promise<BrowserClaw>;
     /**
      * Open a URL in a new tab and return the page handle.
      *
@@ -1031,4 +1087,4 @@ declare class BrowserClaw {
     stop(): Promise<void>;
 }
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConsoleMessage, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, type LaunchOptions, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type StorageKind, type TraceStartOptions, type TypeOptions, type WaitOptions };
+export { type AriaNode, type AriaSnapshotResult, BrowserClaw, 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, type LaunchOptions, type NetworkRequest, type PageError, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions };