@mindstone/mcp-server-browser-automation 0.2.0 → 0.2.1

package/README.md

@@ -9,7 +9,7 @@ Browser control you can watch: open pages, sign in, click around, fill forms, ta
 
 ## Status
 
-- **Version:** [0.2.0](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-browser-automation)
+- **Version:** [0.2.1](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-browser-automation)
 - **Auth:** None ([`server.json`](./server.json))
 - **Tools:** [21](./src/tools/) (navigation, observation, interaction, sessions, files)
 - **Surface:** browser-automation
@@ -117,7 +117,6 @@ No API keys or credentials are required. The server communicates with the browse
 |---|---|---|
 | `AGENT_BROWSER_SESSION_NAME` | No | Session name for browser persistence (default: `mcp`) |
 | `AGENT_BROWSER_SHOW_WINDOW` | No | Set to `false` to run without a visible browser window. Default is visible (`true`). |
-| `BROWSER_AUTOMATION_ALLOW_EVAL` | No | Set to `1` to register the `browser_evaluate` tool. Off by default. See [Security notes](#security-notes). |
 | `MCP_WORKSPACE_PATH` | No | Workspace directory that `browser_pdf` writes into and `browser_upload` reads from. Defaults to the system temp directory. See [Security notes](#security-notes). |
 
 ### MCP Host Configuration
@@ -133,7 +132,7 @@ No API keys or credentials are required. The server communicates with the browse
 }
 ```
 
-## Available Tools (20 by default; +1 when `BROWSER_AUTOMATION_ALLOW_EVAL=1`)
+## Available Tools (21)
 
 ### Navigation
 - **browser_navigate** — Navigate to a URL
@@ -157,7 +156,7 @@ No API keys or credentials are required. The server communicates with the browse
 - **browser_select** — Select an option from a dropdown
 - **browser_hover** — Hover over an element
 - **browser_upload** — Upload workspace files to a file input (regular files only, staged privately before upload)
-- **browser_evaluate** — Execute JavaScript in the page context (gated; see [Security notes](#security-notes))
+- **browser_evaluate** — Execute JavaScript in the page context (on by default; `destructiveHint: true` so hosts can require confirmation — see [Security notes](#security-notes))
 
 ### Session Management
 - **browser_tabs** — List open tabs or switch to a tab
@@ -177,15 +176,9 @@ The typical workflow uses accessibility snapshots for reliable element targeting
 
 Browser automation has a large attack surface: the agent-browser CLI controls a real headless browser that loads URLs you pass it, runs page-side JavaScript, and persists cookies and session state across runs. Read this section before deploying.
 
-### `browser_evaluate` is gated behind `BROWSER_AUTOMATION_ALLOW_EVAL`
+### `browser_evaluate` runs by default — host confirmation is the gate
 
-`browser_evaluate` lets the model execute arbitrary JavaScript inside the page context — the security equivalent of giving the model a shell on whatever site it has just navigated to. To prevent prompt-injected content from doing this silently, the tool is **only registered when the host explicitly opts in**:
-
-```bash
-BROWSER_AUTOMATION_ALLOW_EVAL=1 mcp-server-browser-automation
-```
-
-Without this env var, `browser_evaluate` is **not** in the tools list at all — the LLM cannot even see it. When enabled, the tool is marked so MCP hosts can require explicit user confirmation before each invocation.
+`browser_evaluate` lets the model execute arbitrary JavaScript inside the page context — the security equivalent of giving the model a shell on whatever site it has just navigated to. The tool is registered **unconditionally** (capability-first); the safeguard is the host's tool-approval layer. The tool is marked `destructiveHint: true`, so MCP hosts SHOULD require explicit user confirmation before each invocation. Do not configure a host to auto-approve this tool.
 
 ### URL scheme deny-list
 
@@ -207,7 +200,7 @@ To override the session name (for example, to keep separate profiles per project
 ### Recommended deployment posture
 
 - **Run the connector against a separate browser profile** — a dedicated `AGENT_BROWSER_SESSION_NAME` per MCP host. Do not reuse your daily browser profile: the connector reads and overwrites cookies in whichever profile it is pointed at, and a malicious page can ride the existing session of any site you are logged into.
-- **Leave `browser_evaluate` disabled** unless the host implements user confirmation for every call. The default (off) is the safe choice.
+- **Require host confirmation for `browser_evaluate`** — it runs by default; every call executes arbitrary JavaScript in the page context.
 - **Require host confirmation** for `browser_authenticate` and any flow that may navigate to authenticated sites — otherwise prompt injection in fetched content can drive the browser at sites the user is logged into.
 - **Returned page content is enveloped as untrusted** — accessibility snapshots, page text, titles, URLs, tab lists, and `browser_evaluate` outputs come from arbitrary websites and may contain prompt-injection attempts. The connector wraps them in `<untrusted-content source="…">` envelopes (with close-tag breakout escaping) so hosts and models treat them as data, not instructions. Keep that treatment on your side: don't strip the envelopes, and don't let page text alone trigger irreversible actions.
 
@@ -219,7 +212,7 @@ Both tools are marked `destructiveHint: true`, so hosts can require user confirm
 
 Additional hardening:
 
-- **Staged file hand-off.** Validated files are never re-opened by pathname. `browser_upload` sources are opened once, verified to be regular files (directories, devices, and FIFOs are refused), and copied into a fresh private staging directory that the CLI consumes; `browser_pdf` has the CLI write into a fresh private staging directory and then installs the PDF at the requested path with exclusive-create semantics. A file or symlink planted after validation cannot redirect the read or the write.
+- **Staged file hand-off.** Validated files are never re-opened by pathname. `browser_upload` sources are opened once, verified to be regular files (directories, devices, and FIFOs are refused), and copied into a fresh private staging directory that the CLI consumes. `browser_pdf` has the CLI write into a fresh private staging directory, then installs the PDF at the requested path: the destination directory's canonical identity is pinned before the CLI runs and re-verified before installing, so an intermediate directory swapped to a symlink mid-call is refused, and exclusive-create semantics refuse a file or symlink planted at the destination leaf instead of writing through it.
 - **No silent overwrite.** `browser_pdf` refuses an existing `file_path` with a `FILE_EXISTS` error unless the caller explicitly passes `overwrite: true`.
 - **Enveloped errors.** Error output from the `agent-browser` CLI can contain page-authored text; it is wrapped in `<untrusted-content>` envelopes (with close-tag breakout escaping) before reaching the model, and timeout errors do not echo the command's argument values.
 

package/dist/path-safety.d.ts

@@ -60,6 +60,14 @@ export declare function stageUploadSource(inputPath: string, stagingDir: string,
 export interface PdfStagingTarget {
     /** Validated final destination for the PDF. */
     destPath: string;
+    /**
+     * Canonical realpath of destPath's parent directory, pinned at validation
+     * time (the parent is created before the CLI runs). installStagedFile
+     * re-verifies it before writing, so an intermediate directory swapped to
+     * a symlink during the CLI call is refused instead of followed outside
+     * the workspace.
+     */
+    canonicalParentDir: string;
     /** Private staging path the CLI should write to. */
     stagingPath: string;
     /** Remove with discardStagingDir once installed (or on failure). */
@@ -79,12 +87,22 @@ export declare function createPdfStagingTarget(filePath: string, overwrite: bool
 /**
  * Install a staged PDF at its validated destination.
  *
- * The install never writes through a pre-existing filesystem entry:
- * exclusive-create (COPYFILE_EXCL) fails with EEXIST on anything already at
- * the destination — including a planted symlink. With `overwrite`, the old
- * entry is removed first and the same exclusive-create follows, so a swap
- * planted in between still surfaces as an EEXIST refusal instead of a write
- * through an attacker-chosen path.
+ * Two defences, one per path component class:
+ *   - Leaf: the install never writes through a pre-existing filesystem
+ *     entry. Exclusive-create (COPYFILE_EXCL) fails with EEXIST on anything
+ *     already at the destination — including a planted symlink. With
+ *     `overwrite`, the old entry is removed first and the same
+ *     exclusive-create follows, so a leaf swap planted in between surfaces
+ *     as an EEXIST refusal instead of a write through an attacker-chosen
+ *     path.
+ *   - Intermediate directories: exclusive-create guards only the final
+ *     component, so the parent's canonical identity (pinned at validation,
+ *     before the CLI ran) is re-verified immediately before installing. A
+ *     directory swapped to a symlink during the CLI call is refused rather
+ *     than followed outside the workspace — for the write and, with
+ *     `overwrite`, for the preceding delete. (A swap landing after this
+ *     re-check but before the copy is a sub-millisecond residual window, on
+ *     par with any local check-then-use race.)
  */
-export declare function installStagedFile(stagingPath: string, destPath: string, overwrite: boolean): void;
+export declare function installStagedFile(target: PdfStagingTarget, overwrite: boolean): void;
 //# sourceMappingURL=path-safety.d.ts.map

package/dist/path-safety.js

@@ -233,9 +233,20 @@ export function createPdfStagingTarget(filePath, overwrite) {
     if (!overwrite && fs.existsSync(resolved.path)) {
         throw new ConnectorError(`file_path already exists: ${filePath}`, 'FILE_EXISTS', 'Pass overwrite: true to replace the existing file, or choose a different file_path.');
     }
+    // Create the parent directory NOW, before the multi-second CLI call, and
+    // pin its canonical identity. resolved.path is canonical, so the realpath
+    // of the freshly prepared parent must equal it exactly; a mismatch means
+    // a component changed under us and the destination cannot be trusted.
+    const parentDir = path.dirname(resolved.path);
+    fs.mkdirSync(parentDir, { recursive: true });
+    const canonicalParentDir = fs.realpathSync(parentDir);
+    if (canonicalParentDir !== parentDir) {
+        throw new ConnectorError(`file_path parent directory changed while it was being prepared: ${filePath}`, 'PATH_OUTSIDE_WORKSPACE', 'Retry the call, or choose a different file_path inside the workspace directory.');
+    }
     const stagingDir = createStagingDir('browser-pdf-');
     return {
         destPath: resolved.path,
+        canonicalParentDir,
         stagingPath: path.join(stagingDir, sanitiseBasename(resolved.path, 'page.pdf')),
         stagingDir,
     };
@@ -243,14 +254,25 @@ export function createPdfStagingTarget(filePath, overwrite) {
 /**
  * Install a staged PDF at its validated destination.
  *
- * The install never writes through a pre-existing filesystem entry:
- * exclusive-create (COPYFILE_EXCL) fails with EEXIST on anything already at
- * the destination — including a planted symlink. With `overwrite`, the old
- * entry is removed first and the same exclusive-create follows, so a swap
- * planted in between still surfaces as an EEXIST refusal instead of a write
- * through an attacker-chosen path.
+ * Two defences, one per path component class:
+ *   - Leaf: the install never writes through a pre-existing filesystem
+ *     entry. Exclusive-create (COPYFILE_EXCL) fails with EEXIST on anything
+ *     already at the destination — including a planted symlink. With
+ *     `overwrite`, the old entry is removed first and the same
+ *     exclusive-create follows, so a leaf swap planted in between surfaces
+ *     as an EEXIST refusal instead of a write through an attacker-chosen
+ *     path.
+ *   - Intermediate directories: exclusive-create guards only the final
+ *     component, so the parent's canonical identity (pinned at validation,
+ *     before the CLI ran) is re-verified immediately before installing. A
+ *     directory swapped to a symlink during the CLI call is refused rather
+ *     than followed outside the workspace — for the write and, with
+ *     `overwrite`, for the preceding delete. (A swap landing after this
+ *     re-check but before the copy is a sub-millisecond residual window, on
+ *     par with any local check-then-use race.)
  */
-export function installStagedFile(stagingPath, destPath, overwrite) {
+export function installStagedFile(target, overwrite) {
+    const { stagingPath, destPath, canonicalParentDir } = target;
     let staged;
     try {
         staged = fs.lstatSync(stagingPath);
@@ -261,12 +283,21 @@ export function installStagedFile(stagingPath, destPath, overwrite) {
     if (!staged.isFile()) {
         throw new ConnectorError('The agent-browser CLI did not produce a regular output file.', 'CLI_ERROR', 'Retry the call, or check that a page is open in the browser session.');
     }
+    const parentDir = path.dirname(destPath);
+    let currentParentDir;
+    try {
+        currentParentDir = fs.realpathSync(parentDir);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new ConnectorError(`Destination directory cannot be resolved (${reason}): ${destPath}`, 'PATH_OUTSIDE_WORKSPACE', 'Retry the call, or choose a different file_path inside the workspace directory.');
+    }
+    if (currentParentDir !== canonicalParentDir) {
+        throw new ConnectorError(`Destination directory changed while the PDF was being generated: ${destPath}`, 'PATH_OUTSIDE_WORKSPACE', 'Retry the call, or choose a different file_path inside the workspace directory.');
+    }
     if (overwrite) {
         fs.rmSync(destPath, { force: true });
     }
-    // Parent directories were validated as inside the workspace by
-    // resolveWorkspaceWritePath; create any missing tail before installing.
-    fs.mkdirSync(path.dirname(destPath), { recursive: true });
     try {
         fs.copyFileSync(stagingPath, destPath, fs.constants.COPYFILE_EXCL);
     }

package/dist/tools/interaction.js

@@ -119,32 +119,27 @@ WORKFLOW: browser_snapshot → find input @ref → browser_fill`,
     }));
     // M3.12 — `browser_evaluate` lets the model run arbitrary JavaScript inside
     // the page context, which is the security equivalent of giving it a shell
-    // on whatever site it has just navigated to. To prevent prompt-injected
-    // content from doing this silently, the tool is registered ONLY when the
-    // host explicitly opts in via `BROWSER_AUTOMATION_ALLOW_EVAL=1`. Without
-    // that env var the tool is not in the tools list at all (the LLM cannot
-    // even see it). When enabled it carries `destructiveHint: true` so MCP
-    // hosts can require explicit user confirmation before each invocation.
-    if (process.env.BROWSER_AUTOMATION_ALLOW_EVAL === '1') {
-        server.registerTool('browser_evaluate', // eslint-disable-line @typescript-eslint/quotes
-        {
-            description: 'Execute JavaScript in the page context and return the result. ' +
-                'DESTRUCTIVE: this is equivalent to running arbitrary code with the privileges of the current page; ' +
-                'hosts SHOULD require user confirmation before each call. ' +
-                'Only registered when BROWSER_AUTOMATION_ALLOW_EVAL=1 is set.',
-            inputSchema: {
-                script: z.string().describe('JavaScript code to execute'),
-            },
-            annotations: {
-                readOnlyHint: false,
-                destructiveHint: true,
-                idempotentHint: false,
-                openWorldHint: true,
-            },
-        }, withErrorHandling(async (args) => {
-            const result = await execAgentBrowser(['eval', args.script]);
-            return JSON.stringify({ ok: true, result: wrapUntrusted(result.stdout.trim(), 'browser-automation:evaluate') });
-        }));
-    }
+    // on whatever site it has just navigated to. The tool is registered
+    // unconditionally (capability-first): it carries `destructiveHint: true`
+    // so the host's tool-approval layer can require explicit user confirmation
+    // before each invocation.
+    server.registerTool('browser_evaluate', // eslint-disable-line @typescript-eslint/quotes
+    {
+        description: 'Execute JavaScript in the page context and return the result. ' +
+            'DESTRUCTIVE: this is equivalent to running arbitrary code with the privileges of the current page; ' +
+            'hosts SHOULD require user confirmation before each call.',
+        inputSchema: {
+            script: z.string().describe('JavaScript code to execute'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        const result = await execAgentBrowser(['eval', args.script]);
+        return JSON.stringify({ ok: true, result: wrapUntrusted(result.stdout.trim(), 'browser-automation:evaluate') });
+    }));
 }
 //# sourceMappingURL=interaction.js.map

package/dist/tools/observation.js

@@ -115,14 +115,15 @@ The file is written inside the workspace directory (MCP_WORKSPACE_PATH, or the s
             openWorldHint: true,
         },
     }, withErrorHandling(async (args) => {
-        // The CLI writes into a private staging dir, and the PDF is installed
-        // at the validated destination with exclusive-create semantics, so a
-        // post-validation swap cannot redirect the write or clobber an
-        // existing file.
+        // The CLI writes into a private staging dir. Install then re-verifies
+        // the destination directory's canonical identity (pinned before the
+        // CLI ran) and writes with exclusive-create, so a post-validation swap
+        // of an intermediate directory or the leaf is refused rather than
+        // followed outside the workspace.
         const target = createPdfStagingTarget(args.file_path, args.overwrite);
         try {
             await execAgentBrowser(['pdf', target.stagingPath]);
-            installStagedFile(target.stagingPath, target.destPath, args.overwrite);
+            installStagedFile(target, args.overwrite);
             return JSON.stringify({ ok: true, file_path: target.destPath });
         }
         finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstone/mcp-server-browser-automation",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "mcpName": "io.github.mindstone/mcp-server-browser-automation",
   "description": "Browser automation MCP server — visible-by-default browser control via accessibility snapshots, navigation, form filling, screenshots, and tab management. Set AGENT_BROWSER_SHOW_WINDOW=false to run quietly.",
   "license": "FSL-1.1-MIT",