feat: add --allow-file-access flag for file:// URL support (#375)

* feat: add --allow-file-access flag for file:// URL support

Adds the ability to open and interact with local files using file:// URLs.
This enables use cases like viewing local PDFs, testing local HTML files,
and allowing JavaScript to access other local files via XHR.

The flag adds Chromium's --allow-file-access-from-files and --allow-file-access
launch arguments. Only supported in Chromium browsers.

Fixes #345

* fix: add cli_allow_file_access tracking to prevent spurious warning

When --allow-file-access is set via AGENT_BROWSER_ALLOW_FILE_ACCESS env var
(not CLI), don't warn about the flag being ignored when daemon is already running.

src/browser.ts

@@ -1082,18 +1082,35 @@ export class BrowserManager {
       throw new Error('Extensions are only supported in Chromium');
     }
 
+    // allowFileAccess is only supported in Chromium
+    if (options.allowFileAccess && browserType !== 'chromium') {
+      throw new Error('allowFileAccess is only supported in Chromium');
+    }
+
     const launcher =
       browserType === 'firefox' ? firefox : browserType === 'webkit' ? webkit : chromium;
     const viewport = options.viewport ?? { width: 1280, height: 720 };
 
+    // Build base args array with file access flags if enabled
+    // --allow-file-access-from-files: allows file:// URLs to read other file:// URLs via XHR/fetch
+    // --allow-file-access: allows the browser to access local files in general
+    const fileAccessArgs = options.allowFileAccess
+      ? ['--allow-file-access-from-files', '--allow-file-access']
+      : [];
+    const baseArgs = options.args
+      ? [...fileAccessArgs, ...options.args]
+      : fileAccessArgs.length > 0
+        ? fileAccessArgs
+        : undefined;
+
     let context: BrowserContext;
     if (hasExtensions) {
       // Extensions require persistent context in a temp directory
       const extPaths = options.extensions!.join(',');
       const session = process.env.AGENT_BROWSER_SESSION || 'default';
-      // Combine extension args with custom args
+      // Combine extension args with custom args and file access args
       const extArgs = [`--disable-extensions-except=${extPaths}`, `--load-extension=${extPaths}`];
-      const allArgs = options.args ? [...extArgs, ...options.args] : extArgs;
+      const allArgs = baseArgs ? [...extArgs, ...baseArgs] : extArgs;
       context = await launcher.launchPersistentContext(
         path.join(os.tmpdir(), `agent-browser-ext-${session}`),
         {
@@ -1115,7 +1132,7 @@ export class BrowserManager {
       context = await launcher.launchPersistentContext(profilePath, {
         headless: options.headless ?? true,
         executablePath: options.executablePath,
-        args: options.args,
+        args: baseArgs,
         viewport,
         extraHTTPHeaders: options.headers,
         userAgent: options.userAgent,
@@ -1128,7 +1145,7 @@ export class BrowserManager {
       this.browser = await launcher.launch({
         headless: options.headless ?? true,
         executablePath: options.executablePath,
-        args: options.args,
+        args: baseArgs,
       });
       this.cdpEndpoint = null;
       context = await this.browser.newContext({

src/daemon.ts

@@ -311,6 +311,7 @@ export async function startDaemon(options?: {
                 : undefined;
 
               const ignoreHTTPSErrors = process.env.AGENT_BROWSER_IGNORE_HTTPS_ERRORS === '1';
+              const allowFileAccess = process.env.AGENT_BROWSER_ALLOW_FILE_ACCESS === '1';
               await manager.launch({
                 id: 'auto',
                 action: 'launch' as const,
@@ -323,6 +324,7 @@ export async function startDaemon(options?: {
                 userAgent: process.env.AGENT_BROWSER_USER_AGENT,
                 proxy,
                 ignoreHTTPSErrors: ignoreHTTPSErrors,
+                allowFileAccess: allowFileAccess,
               });
             }
           }

src/types.ts

@@ -29,6 +29,7 @@ export interface LaunchCommand extends BaseCommand {
   userAgent?: string;
   provider?: string;
   ignoreHTTPSErrors?: boolean;
+  allowFileAccess?: boolean; // Enable file:// URL access and cross-origin file requests
 }
 
 export interface NavigateCommand extends BaseCommand {