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

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.1](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-browser-automation)
+- **Version:** [0.2.2](./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
@@ -212,8 +212,8 @@ 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, 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`.
+- **Staged file hand-off.** Validated files are never re-opened by pathname. `browser_upload` sources are opened once (`O_NOFOLLOW` + `O_NONBLOCK`, so a post-validation leaf-symlink swap fails and a planted FIFO cannot wedge the open), verified to be regular files (directories, devices, and FIFOs are refused), bound to a fresh confined resolution by device+inode (an intermediate-directory swap after validation redirects the resolution and is refused with `UPLOAD_SOURCE_CHANGED`), 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`. Even then, a destination that is a directory is refused (`DESTINATION_IS_DIRECTORY`) — the overwrite delete is a bare unlink and never recurses.
 - **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.
 
 ## Licence

package/dist/path-safety.d.ts

@@ -1,3 +1,4 @@
+import * as fs from 'node:fs';
 export type ResolveResult = {
     ok: true;
     path: string;
@@ -49,14 +50,24 @@ export declare function discardStagingDir(stagingDir: string): void;
  * the CLI should consume.
  *
  * The source is validated inside the workspace root, then opened EXACTLY
- * ONCE and fstat-verified through that fd to be a regular file —
- * directories, FIFOs, sockets, and devices pass realpathSync but must not
- * become upload payloads. The content is streamed through the same fd into
- * a private staging slot carrying over only the requested basename, so the
+ * ONCE with O_NOFOLLOW — a leaf swapped for a symlink between validation
+ * and open fails with ELOOP instead of being followed outside the
+ * workspace — and O_NONBLOCK, so a planted FIFO cannot wedge the connector
+ * by blocking the open until a writer appears. The fd is fstat-verified to
+ * be a regular file (directories, FIFOs, sockets, and devices pass
+ * realpathSync but must not become upload payloads), then bound to a fresh
+ * confined resolution of the path by dev+inode — an intermediate directory
+ * (or, on platforms without O_NOFOLLOW, the leaf itself) swapped for a
+ * symlink after validation redirects the resolution to a different inode
+ * and is refused. The content is streamed through the same fd into a
+ * private staging slot carrying over only the requested basename, so the
  * CLI never re-opens the validated pathname and a post-validation swap of
  * the original cannot redirect the upload.
+ *
+ * `openFile` is injectable for adversarial tests only; production callers
+ * use the default `fs.openSync`.
  */
-export declare function stageUploadSource(inputPath: string, stagingDir: string, index: number): string;
+export declare function stageUploadSource(inputPath: string, stagingDir: string, index: number, openFile?: typeof fs.openSync): string;
 export interface PdfStagingTarget {
     /** Validated final destination for the PDF. */
     destPath: string;

package/dist/path-safety.js

@@ -170,19 +170,37 @@ function sanitiseBasename(p, fallback) {
     const base = path.basename(p);
     return base === '' || base === '.' || base === '..' ? fallback : base;
 }
+/**
+ * A post-validation swap raced the upload source. Distinct from
+ * PATH_OUTSIDE_WORKSPACE: the path WAS inside the workspace at validation
+ * time, so retrying can succeed.
+ */
+function uploadSourceChangedError(inputPath) {
+    return new ConnectorError(`file_path changed while it was being validated: ${inputPath}`, 'UPLOAD_SOURCE_CHANGED', 'Retry the call, or pass a path to a regular file inside the workspace directory.');
+}
 /**
  * Stage one `browser_upload` source into `stagingDir` and return the path
  * the CLI should consume.
  *
  * The source is validated inside the workspace root, then opened EXACTLY
- * ONCE and fstat-verified through that fd to be a regular file —
- * directories, FIFOs, sockets, and devices pass realpathSync but must not
- * become upload payloads. The content is streamed through the same fd into
- * a private staging slot carrying over only the requested basename, so the
+ * ONCE with O_NOFOLLOW — a leaf swapped for a symlink between validation
+ * and open fails with ELOOP instead of being followed outside the
+ * workspace — and O_NONBLOCK, so a planted FIFO cannot wedge the connector
+ * by blocking the open until a writer appears. The fd is fstat-verified to
+ * be a regular file (directories, FIFOs, sockets, and devices pass
+ * realpathSync but must not become upload payloads), then bound to a fresh
+ * confined resolution of the path by dev+inode — an intermediate directory
+ * (or, on platforms without O_NOFOLLOW, the leaf itself) swapped for a
+ * symlink after validation redirects the resolution to a different inode
+ * and is refused. The content is streamed through the same fd into a
+ * private staging slot carrying over only the requested basename, so the
  * CLI never re-opens the validated pathname and a post-validation swap of
  * the original cannot redirect the upload.
+ *
+ * `openFile` is injectable for adversarial tests only; production callers
+ * use the default `fs.openSync`.
  */
-export function stageUploadSource(inputPath, stagingDir, index) {
+export function stageUploadSource(inputPath, stagingDir, index, openFile = fs.openSync) {
     const resolved = resolveWorkspaceReadPath(inputPath);
     if (!resolved.ok) {
         throw new ConnectorError(resolved.error, 'PATH_OUTSIDE_WORKSPACE', 'Pass file paths inside the workspace directory (MCP_WORKSPACE_PATH, or the system temp directory when unset).');
@@ -190,12 +208,58 @@ export function stageUploadSource(inputPath, stagingDir, index) {
     const slot = path.join(stagingDir, String(index));
     fs.mkdirSync(slot, { mode: STAGING_DIR_MODE });
     const stagingPath = path.join(slot, sanitiseBasename(resolved.path, `upload-${index}`));
-    const inFd = fs.openSync(resolved.path, 'r');
+    // O_NOFOLLOW: resolved.path is canonical (no symlinks at validation
+    // time), so a symlink at the leaf here can only be a post-validation
+    // swap — refuse instead of following it outside the workspace.
+    // O_NONBLOCK: opening a FIFO O_RDONLY would otherwise block until a
+    // writer appears, letting a planted pipe wedge the connector; for
+    // regular files O_NONBLOCK is a no-op. (Either flag is undefined on
+    // platforms without it, where the composition degrades to a plain
+    // O_RDONLY — the dev+inode re-resolution below still refuses a swap
+    // there.)
+    let inFd;
+    try {
+        inFd = openFile(resolved.path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            throw new ConnectorError(`File not found: ${inputPath}`, 'PATH_OUTSIDE_WORKSPACE', 'Pass file paths inside the workspace directory (MCP_WORKSPACE_PATH, or the system temp directory when unset).');
+        }
+        if (code === 'ELOOP' || code === 'EMLINK' || code === 'EFTYPE' ||
+            code === 'EISDIR' || code === 'EPERM' || code === 'EACCES') {
+            // ELOOP/EMLINK/EFTYPE: the validated leaf was swapped for a symlink
+            // before we could open it (the O_NOFOLLOW errno varies by platform).
+            // EISDIR/EPERM/EACCES: swapped for a directory or an unreadable
+            // object. Either way, refuse rather than read.
+            throw uploadSourceChangedError(inputPath);
+        }
+        throw err;
+    }
     try {
         const stat = fs.fstatSync(inFd);
         if (!stat.isFile()) {
             throw new ConnectorError(`file_path is not a regular file: ${inputPath}`, 'NOT_A_REGULAR_FILE', 'Pass a path to a regular file inside the workspace directory.');
         }
+        // An intermediate directory swapped for a symlink after validation
+        // could have redirected the open itself (O_NOFOLLOW constrains only
+        // the final component), so bind the descriptor to a fresh confined
+        // resolution: the path must still resolve inside the workspace to the
+        // SAME dev+inode we opened. Bytes are read through the fd below, so a
+        // swap landing after this check cannot change the uploaded content.
+        const recheck = resolveWorkspaceReadPath(inputPath);
+        let fresh;
+        if (recheck.ok) {
+            try {
+                fresh = fs.statSync(recheck.path);
+            }
+            catch {
+                fresh = undefined; // resolution failed — refuse below
+            }
+        }
+        if (!fresh || fresh.dev !== stat.dev || fresh.ino !== stat.ino) {
+            throw uploadSourceChangedError(inputPath);
+        }
         const outFd = fs.openSync(stagingPath, 'wx', STAGING_FILE_MODE);
         try {
             const chunk = Buffer.allocUnsafe(COPY_CHUNK_BYTES);
@@ -296,7 +360,26 @@ export function installStagedFile(target, overwrite) {
         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 });
+        // unlinkSync, not rmSync: only a regular file or symlink may ever be
+        // removed here. unlink refuses directories atomically in the kernel
+        // (no lstat pre-check to race, as rmSync's ERR_FS_EISDIR path has) and
+        // can never recurse — deleting a directory tree as a PDF-overwrite
+        // side effect would be far worse than refusing.
+        try {
+            fs.unlinkSync(destPath);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'EISDIR' || code === 'EPERM') {
+                // EISDIR on Linux, EPERM on macOS: the destination is a directory.
+                throw new ConnectorError(`Destination is a directory, not a file: ${destPath}`, 'DESTINATION_IS_DIRECTORY', 'Choose a file_path that does not collide with an existing directory.');
+            }
+            if (code !== 'ENOENT') {
+                throw err;
+            }
+            // ENOENT: nothing to overwrite — the exclusive-create below installs
+            // the staged file.
+        }
     }
     try {
         fs.copyFileSync(stagingPath, destPath, fs.constants.COPYFILE_EXCL);

package/dist/tools/observation.js

@@ -105,7 +105,7 @@ Use this for reading and summarising page content — it returns clean text, unl
 The file is written inside the workspace directory (MCP_WORKSPACE_PATH, or the system temp directory when unset) — file_path must resolve inside that workspace. Existing files are refused unless overwrite is set to true.`,
         inputSchema: {
             file_path: z.string().min(1).describe('Target file path for the PDF. Relative paths resolve inside the workspace directory; absolute paths must be inside it (e.g., "reports/page.pdf").'),
-            overwrite: z.boolean().optional().default(false).describe('Replace an existing file at file_path. Default: false — existing files are refused.'),
+            overwrite: z.boolean().optional().default(false).describe('Replace an existing file at file_path. Default: false — existing files are refused. A directory at file_path is refused even with overwrite: true.'),
         },
         annotations: {
             readOnlyHint: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstone/mcp-server-browser-automation",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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",