Skip to content

Commit f621c75

Browse files
cliffhallclaude
andcommitted
fix(filesystem): resolve paths that differ from disk only in Unicode form (#1970)
An NFC spelling of an allowed directory whose name is NFD on disk failed the allow-list check, a string comparison, before the Unicode walk ran. validatePath now maps such a request onto the allowed directory's own spelling, so the result is inside that directory by construction and every later check still runs against the real allow-list; a request that does not spell an allowed directory is refused as before. The Unicode walk also treats Unicode space separators (U+202F, U+00A0) as U+0020 when the exact name is missing, so a macOS screenshot name sent back with a plain space before "PM" resolves instead of failing with ENOENT. An exact match still wins, and two matches are still ambiguous. The KNOWN BUG #1970 pinning test now asserts the corrected behavior. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 571e2b3 commit f621c75

3 files changed

Lines changed: 124 additions & 9 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-filesystem": patch
3+
---
4+
5+
Paths that differ from the names on disk only in Unicode form now resolve (#1970). An NFC spelling of an allowed directory whose name is stored NFD (macOS "Capture d’écran", Japanese dakuten) is no longer refused as outside the allowed directories, and a request that spells a U+202F or U+00A0 in a name as a plain space (the macOS screenshot "Screenshot … at 2.40.40 PM.png") finds the file instead of failing with ENOENT. The exact spelling still wins when it exists, and a name matching two entries is refused as ambiguous.

‎src/filesystem/__tests__/server-paths.test.ts‎

Lines changed: 70 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -269,11 +269,10 @@ describe("Unicode normalization", () => {
269269
},
270270
);
271271

272-
// KNOWN BUG #1970: pins current (wrong) behavior; the fix changes this assertion.
273272
// #1970: when the allowed directory's own name is NFD, an NFC spelling of
274-
// it fails the allow-list prefix check (a string comparison) before the
275-
// Unicode walk starts, on any file system.
276-
it("refuses an NFC spelling of an NFD allowed directory (#1970)", async () => {
273+
// it used to fail the allow-list prefix check (a string comparison) before
274+
// the Unicode walk started, on any file system.
275+
it("accepts an NFC spelling of an NFD allowed directory (#1970)", async () => {
277276
const nfdRoot = path.join(dir, "Capture d\u2019e\u0301cran");
278277
await fs.mkdir(nfdRoot);
279278
await fs.writeFile(path.join(nfdRoot, "shot.png"), "png");
@@ -283,11 +282,75 @@ describe("Unicode normalization", () => {
283282
const result = await call(scoped.client, "read_text_file", {
284283
path: requested,
285284
});
286-
expect(textOf(result)).toBe(
287-
`Access denied - path outside allowed directories: ${requested} not in ${nfdRoot}`,
288-
);
285+
expect(textOf(result)).toBe("png");
289286
} finally {
290287
await scoped.close();
291288
}
292289
});
290+
291+
// #1970: a respelled allowed directory must not open a path into a
292+
// different directory that merely shares its name up to normalization.
293+
it.skipIf(!distinctForms)(
294+
"maps an NFD spelling of an NFC allowed directory onto it, never onto an NFD sibling (#1970)",
295+
async () => {
296+
const nfcRoot = path.join(dir, "caf\u00e9");
297+
const nfdSibling = path.join(dir, "cafe\u0301");
298+
await fs.mkdir(nfcRoot);
299+
await fs.mkdir(nfdSibling);
300+
await fs.writeFile(path.join(nfcRoot, "f.txt"), "allowed");
301+
await fs.writeFile(path.join(nfdSibling, "f.txt"), "secret");
302+
const scoped = await connect([nfcRoot]);
303+
try {
304+
const result = await call(scoped.client, "read_text_file", {
305+
path: path.join(nfdSibling, "f.txt"),
306+
});
307+
expect(textOf(result)).toBe("allowed");
308+
} finally {
309+
await scoped.close();
310+
}
311+
},
312+
);
313+
314+
it("refuses a path that only shares a normalized prefix with the allowed directory's name", async () => {
315+
const result = await read(`${dir}\u00a0x/f.txt`);
316+
expect(textOf(result)).toMatch(/^Access denied - path outside/);
317+
});
318+
});
319+
320+
// #1970: macOS names screenshots "Screenshot ... at 2.40.40\u202fPM.png";
321+
// a client lists the file, then sends the name back with a plain space.
322+
describe("Unicode space separators (#1970)", () => {
323+
const onDisk = "Screenshot 2025-04-23 at 2.40.40\u202fPM.png";
324+
const typed = "Screenshot 2025-04-23 at 2.40.40 PM.png";
325+
326+
it("reads a file whose U+202F the request spells as U+0020", async () => {
327+
await fs.writeFile(path.join(dir, onDisk), "shot");
328+
expect(textOf(await read(path.join(dir, typed)))).toBe("shot");
329+
});
330+
331+
it("moves a file whose U+00A0 the request spells as U+0020", async () => {
332+
await fs.mkdir(path.join(dir, "Images"));
333+
await fs.writeFile(path.join(dir, "a\u00a0b.png"), "x");
334+
const result = await call(client, "move_file", {
335+
source: path.join(dir, "a b.png"),
336+
destination: path.join(dir, "Images", "a b.png"),
337+
});
338+
expect(result.isError).toBeFalsy();
339+
expect(await fs.readdir(path.join(dir, "Images"))).toEqual(["a b.png"]);
340+
expect(await fs.readdir(dir)).toEqual(["Images"]);
341+
});
342+
343+
it("prefers the exact spelling when both are on disk", async () => {
344+
await fs.writeFile(path.join(dir, onDisk), "nnbsp");
345+
await fs.writeFile(path.join(dir, typed), "space");
346+
expect(textOf(await read(path.join(dir, typed)))).toBe("space");
347+
expect(textOf(await read(path.join(dir, onDisk)))).toBe("nnbsp");
348+
});
349+
350+
it("refuses a name that matches two entries differing only in their spaces", async () => {
351+
await fs.writeFile(path.join(dir, "a\u00a0b"), "1");
352+
await fs.writeFile(path.join(dir, "a\u202fb"), "2");
353+
const result = await read(path.join(dir, "a b"));
354+
expect(textOf(result)).toBe("Ambiguous Unicode path component: a b");
355+
});
293356
});

‎src/filesystem/lib.ts‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,48 @@ function resolveRelativePathAgainstAllowedDirectories(
9292
}
9393

9494
// Security & Validation Functions
95+
96+
// The form two path components are compared in when the exact spelling is not
97+
// on disk (#1970): canonically equivalent spellings (NFC/NFD, as macOS stores
98+
// "é" or Japanese dakuten) match, and so do the Unicode space separators
99+
// (U+00A0, the U+202F macOS puts before "PM" in a screenshot's name, ...),
100+
// which a client typing the name back almost always sends as U+0020.
101+
function unicodeMatchKey(component: string): string {
102+
return component.normalize("NFC").replace(/\p{Zs}/gu, " ");
103+
}
104+
105+
// An allowed directory whose own name is spelled differently on disk (NFD)
106+
// from the request (NFC) fails the allow-list check, which compares strings
107+
// (#1970). Map such a request onto the allowed directory's own spelling, so
108+
// the result is inside that directory by construction and every later check
109+
// still runs against the real allow-list. A request that does not spell an
110+
// allowed directory is returned unchanged and is refused as before.
111+
function respellAllowedDirectoryPrefix(
112+
absolutePath: string,
113+
allowedDirectories: readonly string[],
114+
): string {
115+
const requestedParts = absolutePath.split(path.sep).filter(Boolean);
116+
const candidates = allowedDirectories
117+
.map((directory) => path.resolve(directory))
118+
.sort((left, right) => right.length - left.length);
119+
for (const directory of candidates) {
120+
const directoryParts = directory.split(path.sep).filter(Boolean);
121+
if (
122+
directoryParts.length <= requestedParts.length &&
123+
directoryParts.every(
124+
(part, index) =>
125+
unicodeMatchKey(part) === unicodeMatchKey(requestedParts[index]),
126+
)
127+
) {
128+
return path.join(
129+
directory,
130+
...requestedParts.slice(directoryParts.length),
131+
);
132+
}
133+
}
134+
return absolutePath;
135+
}
136+
95137
async function resolveUnicodeEquivalentPath(
96138
absolutePath: string,
97139
allowedDirectories: readonly string[],
@@ -120,7 +162,7 @@ async function resolveUnicodeEquivalentPath(
120162
const equivalentMatches = exactMatch
121163
? [exactMatch]
122164
: entries.filter(
123-
(entry) => entry.normalize("NFC") === requestedPart.normalize("NFC"),
165+
(entry) => unicodeMatchKey(entry) === unicodeMatchKey(requestedPart),
124166
);
125167

126168
if (equivalentMatches.length > 1) {
@@ -171,12 +213,17 @@ export async function validatePath(
171213
`Access denied - Windows-style path received on a POSIX host: ${requestedPath}`,
172214
);
173215
}
174-
const absolute = path.isAbsolute(expandedPath)
216+
let absolute = path.isAbsolute(expandedPath)
175217
? path.resolve(expandedPath)
176218
: resolveRelativePathAgainstAllowedDirectories(
177219
expandedPath,
178220
allowedDirectories,
179221
);
222+
if (
223+
!isPathWithinAllowedDirectories(normalizePath(absolute), allowedDirectories)
224+
) {
225+
absolute = respellAllowedDirectoryPrefix(absolute, allowedDirectories);
226+
}
180227

181228
const normalizedRequested = normalizePath(absolute);
182229

0 commit comments

Comments
 (0)