Skip to content

Commit 8a3fe59

Browse files
cliffhallclaude
andcommitted
fix(filesystem): refuse to start on an unresolvable --read-only-dir
A read-only directory is now resolved with the same realpath write validation uses, and must be an existing directory when the server starts. A missing directory, a dangling symlink or a name the disk spells differently is refused at startup instead of being recorded under a spelling write validation would never produce, which left it writable. Replaces the nearest-ancestor resolution from the last round. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent f3222de commit 8a3fe59

5 files changed

Lines changed: 73 additions & 60 deletions

File tree

‎.changeset/filesystem-5348-read-only-dirs.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
"@modelcontextprotocol/server-filesystem": minor
33
---
44

5-
Add `--read-only-dir <path>`, repeatable, to make one allowed directory read-only while the others stay writable. Every write tool stays listed but refuses a target inside a read-only directory (`move_file` on either end, including moving a directory that contains one, and `copy_file` on its destination), checked on the resolved path so a symlink cannot route around it; a 2025-era client's Roots never lift the marking. `list_allowed_directories` names the read-only directories.
5+
Add `--read-only-dir <path>`, repeatable, to make one allowed directory read-only while the others stay writable. Every write tool stays listed but refuses a target inside a read-only directory (`move_file` on either end, including moving a directory that contains one, and `copy_file` on its destination), checked on the resolved path so a symlink cannot route around it; a 2025-era client's Roots never lift the marking. Each read-only directory must exist when the server starts, or it refuses to start. `list_allowed_directories` names the read-only directories.

‎src/filesystem/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ mcp-server-filesystem --read-only-dir /path/to/reference /path/to/workspace
5454

5555
- A read-only directory is an allowed directory too, so it need not also be listed on its own.
5656
- Every write tool (`write_file`, `append_file`, `edit_file`, `create_directory`, `move_file` and `copy_file`) stays listed, since the other directories are writable, but refuses a target inside a read-only directory with an error such as `Access denied - read-only directory: /path/to/reference/notes.md is in /path/to/reference, which the server was started with --read-only-dir`. `move_file` is refused when either its source or its destination is inside one or contains one, so a protected directory cannot be carried away by moving its parent; `copy_file` may copy out of one, never into it. `edit_file` is refused there even with `dryRun`.
57-
- The check runs on a path's resolved location, so a symlink in a writable directory cannot route a write into a read-only one. A read-only directory that does not exist yet is still protected: it is resolved through its nearest existing ancestor, so it covers the path a write would create.
57+
- The check runs on a path's resolved location, so a symlink in a writable directory cannot route a write into a read-only one. A read-only directory must therefore exist when the server starts: one that cannot be resolved (missing, not a directory, or a dangling symlink) stops the server from starting, rather than leaving a path it could not pin down writable.
5858
- A path inside any read-only directory is refused, so a directory nested inside a read-only one is read-only too, even if it is also given as a writable directory.
5959
- The marking is fixed at startup and holds on both protocol eras. A 2025-era client's Roots can replace the allowed directories (see Method 2), but Roots say nothing about writing, so they never lift it: a write into a read-only directory is refused whichever directories are in force, with or without `--confine-roots`.
6060
- `list_allowed_directories` lists the read-only directories after the allowed ones, and the server logs them to stderr at startup.

‎src/filesystem/__tests__/read-only-dirs.test.ts‎

Lines changed: 46 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -354,35 +354,44 @@ describe("resolveReadOnlyDirectories", () => {
354354
).toEqual([protectedDir]);
355355
});
356356

357-
it("keeps a directory that does not exist yet", async () => {
357+
it("refuses a directory that does not exist", async () => {
358358
const missing = path.join(writable, "later");
359-
expect(await resolveReadOnlyDirectories([missing])).toEqual([missing]);
359+
await expect(resolveReadOnlyDirectories([missing])).rejects.toThrow(
360+
`--read-only-dir ${missing} is not an existing directory`,
361+
);
360362
});
361363

362-
it("resolves a missing directory through a symlinked ancestor", async () => {
363-
const alias = path.join(protectedDir, "alias");
364-
await fs.symlink(writable, alias);
365-
expect(
366-
await resolveReadOnlyDirectories([path.join(alias, "later", "deep")]),
367-
).toEqual([
368-
path.join(alias, "later", "deep"),
369-
path.join(writable, "later", "deep"),
370-
]);
364+
it("refuses a dangling symlink", async () => {
365+
const alias = path.join(writable, "alias");
366+
await fs.symlink(path.join(writable, "vault"), alias);
367+
await expect(resolveReadOnlyDirectories([alias])).rejects.toThrow(
368+
`--read-only-dir ${alias} is not an existing directory`,
369+
);
371370
});
372371

373-
it("protects a directory created later under a symlinked ancestor", async () => {
374-
const alias = path.join(protectedDir, "alias");
375-
await fs.symlink(writable, alias);
376-
const marked = await resolveReadOnlyDirectories([
377-
path.join(alias, "later"),
378-
]);
379-
const client = await connect("legacy", [writable], marked);
380-
const created = await call(client, "create_directory", {
381-
path: path.join(writable, "later"),
382-
});
383-
expect(created.isError).toBe(true);
384-
expect(textOf(created)).toContain("Access denied - read-only directory");
385-
await expect(fs.access(path.join(writable, "later"))).rejects.toThrow();
372+
it("refuses a file", async () => {
373+
const file = path.join(writable, "scratch.txt");
374+
await expect(resolveReadOnlyDirectories([file])).rejects.toThrow(
375+
"not a directory",
376+
);
377+
});
378+
379+
it("refuses a name the disk does not hold, such as another Unicode normalization", async () => {
380+
// On a file system that keeps both forms apart, the NFD spelling of an
381+
// NFC-named directory is a different, missing name; where they are one
382+
// name, it resolves to the directory itself. Either way the marking is
383+
// never recorded under a spelling write validation would not produce.
384+
const nfc = path.join(writable, "caf\u00e9");
385+
await fs.mkdir(nfc);
386+
const nfd = path.join(writable, "cafe\u0301");
387+
const resolved = await resolveReadOnlyDirectories([nfd]).catch(
388+
(error: Error) => error,
389+
);
390+
if (resolved instanceof Error) {
391+
expect(resolved.message).toContain("is not an existing directory");
392+
} else {
393+
expect(resolved).toContain(await fs.realpath(nfd));
394+
}
386395
});
387396
});
388397

@@ -465,6 +474,19 @@ describe("main() with --read-only-dir", () => {
465474
expect(await keepContent()).toBe("original\n");
466475
});
467476

477+
it("refuses to start when a read-only directory cannot be resolved", async () => {
478+
const missing = path.join(writable, "missing");
479+
await expect(
480+
main(
481+
["--read-only-dir", missing, writable],
482+
new PassThrough(),
483+
new PassThrough(),
484+
),
485+
).rejects.toThrow(
486+
`--read-only-dir ${missing} is not an existing directory`,
487+
);
488+
});
489+
468490
it("does not print usage when only --read-only-dir names a directory", async () => {
469491
const handle = await main(
470492
["--read-only-dir", protectedDir],

‎src/filesystem/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,8 @@ export async function main(
185185
...directories,
186186
...readOnlyDirectories,
187187
]);
188+
// Rejects, so the server does not start, when a read-only directory
189+
// cannot be resolved: it could not be protected reliably.
188190
const resolvedReadOnlyDirectories =
189191
await resolveReadOnlyDirectories(readOnlyDirectories);
190192
// With no directories and a 2025-era client without Roots, the server

‎src/filesystem/read-only-directories.ts‎

Lines changed: 23 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,19 @@
1414
// The read-only list is the operator's and is fixed at startup. A 2025-era
1515
// client's Roots can replace the allowed directories, but Roots carry no
1616
// access mode, so they never lift the marking: whatever directories are in
17-
// force, a write into a read-only directory is refused. The directories here
18-
// are resolved like the allowed ones (each spelling of a symlinked directory
19-
// is kept) but are not filtered for existence: a marking that does not exist
20-
// yet is resolved through its nearest existing ancestor, so it still protects
21-
// the path a write would resolve to once it appears.
17+
// force, a write into a read-only directory is refused. Each directory must
18+
// exist when the server starts, and is resolved with the same realpath that
19+
// write validation uses (each spelling of a symlinked directory is kept). A
20+
// marking that cannot be resolved (missing, a dangling symlink, a name the
21+
// disk spells differently) refuses startup rather than guessing where it
22+
// will be, since a guess that differs from what write validation resolves
23+
// would leave the directory writable.
2224
//
2325
// move_file validates both ends in "move" mode, which also refuses a path that
2426
// contains a read-only directory: moving an ancestor would carry the protected
2527
// subtree to a path the marking no longer names.
2628

29+
import fs from "fs/promises";
2730
import path from "path";
2831
import {
2932
expandHome,
@@ -35,47 +38,33 @@ import { isPathWithinAllowedDirectories } from "./path-validation.js";
3538
/**
3639
* The read-only directories as given on the command line, in the forms they
3740
* are compared in: each one absolute and normalized, plus its resolved form
38-
* when it is a symlink (as macOS /tmp is for /private/tmp).
41+
* when it is a symlink (as macOS /tmp is for /private/tmp). Rejects when one
42+
* of them is not an existing directory.
3943
*/
4044
export async function resolveReadOnlyDirectories(
4145
directories: readonly string[],
4246
): Promise<string[]> {
4347
const resolved = await Promise.all(
4448
directories.map(async (dir) => {
4549
const absolute = path.resolve(expandHome(dir));
46-
return [
47-
normalizePathFormat(absolute),
48-
normalizePathFormat(await resolveThroughExistingAncestor(absolute)),
49-
];
50+
let resolved: string;
51+
try {
52+
resolved = await realpathWithRetry(absolute);
53+
if (!(await fs.stat(resolved)).isDirectory()) {
54+
throw new Error("not a directory");
55+
}
56+
} catch (error) {
57+
throw new Error(
58+
`--read-only-dir ${dir} is not an existing directory (${error instanceof Error ? error.message : String(error)}); a read-only directory must exist when the server starts`,
59+
{ cause: error },
60+
);
61+
}
62+
return [normalizePathFormat(absolute), normalizePathFormat(resolved)];
5063
}),
5164
);
5265
return [...new Set(resolved.flat())];
5366
}
5467

55-
/**
56-
* `absolute` with its longest existing ancestor realpath'd and the missing
57-
* components appended, so a directory that does not exist yet resolves to
58-
* where a write would put it: with `/alias` a symlink to `/work`, a missing
59-
* `/alias/later` resolves to `/work/later`.
60-
*/
61-
async function resolveThroughExistingAncestor(
62-
absolute: string,
63-
): Promise<string> {
64-
const missing: string[] = [];
65-
let current = absolute;
66-
for (;;) {
67-
try {
68-
return path.join(await realpathWithRetry(current), ...missing);
69-
} catch {
70-
const parent = path.dirname(current);
71-
/* v8 ignore next -- the file system root always resolves, so the walk ends before it */
72-
if (parent === current) return absolute;
73-
missing.unshift(path.basename(current));
74-
current = parent;
75-
}
76-
}
77-
}
78-
7968
/**
8069
* The read-only directory that `resolvedPath` (a path validatePath resolved)
8170
* falls in, or undefined when it is in none.

0 commit comments

Comments
 (0)