Skip to content

Commit 39c66a4

Browse files
cliffhallclaude
andcommitted
feat(filesystem): refuse NTFS alternate-data-stream paths on Windows
On Windows, isPathWithinAllowedDirectories now throws "Access denied - NTFS alternate data stream paths are not supported" for a path holding a colon anywhere but the drive-letter prefix (optionally behind \\?\ or \\.\), so file.txt:stream and file.txt::$DATA are refused by every tool with a clear error instead of reading or writing hidden streams. POSIX hosts are unaffected. Prototyped by andreiminca in modelcontextprotocol#4523. Closes modelcontextprotocol#5375 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 281b167 commit 39c66a4

5 files changed

Lines changed: 284 additions & 0 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+
On Windows, refuse paths that name an NTFS alternate data stream (`file.txt:stream`, `file.txt::$DATA`): a colon anywhere but the drive-letter prefix now fails with "Access denied - NTFS alternate data stream paths are not supported" instead of letting the tools read or write data no directory listing shows. POSIX hosts are unaffected, since a colon is an ordinary character in a file name there. Thanks to @andreiminca, whose #4523 prototyped the check.

‎src/filesystem/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ The server's directory access control follows this flow:
100100
/Users/username/project
101101
```
102102
- Server requires at least ONE allowed directory to operate
103+
- On Windows, a path naming an NTFS alternate data stream (`file.txt:stream`, `file.txt::$DATA`) is refused with "Access denied - NTFS alternate data stream paths are not supported", even inside an allowed directory: a colon is accepted only as a drive letter's (`C:\`, `\\?\C:\`). A stream holds data that no directory listing or diff of the file shows. On macOS and Linux a colon is an ordinary file-name character and is not refused
103104
104105
**Note**: The server will only allow operations within directories specified either via `args` or, for a 2025-era client, via Roots.
105106
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// The alternate-data-stream refusal (#5375) on the real host, with no path
2+
// simulation. On Windows (the CI Windows leg) a real NTFS stream path is
3+
// refused by the tools and no stream is written. On POSIX a colon is an
4+
// ordinary name character, so a file named with one must keep working:
5+
// the refusal is Windows-only.
6+
7+
import fs from "fs/promises";
8+
import path from "path";
9+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
10+
import {
11+
call,
12+
connect,
13+
makeTempDir,
14+
quietStderr,
15+
textOf,
16+
type Connected,
17+
} from "./helpers.js";
18+
19+
const REFUSAL = /NTFS alternate data stream paths are not supported/;
20+
21+
let dir: string;
22+
let conn: Connected;
23+
24+
beforeEach(async () => {
25+
quietStderr();
26+
dir = await makeTempDir("mcp-fs-ads-");
27+
conn = await connect([dir]);
28+
});
29+
30+
afterEach(async () => {
31+
vi.restoreAllMocks();
32+
await conn.close();
33+
await fs.rm(dir, { recursive: true, force: true });
34+
});
35+
36+
describe.runIf(process.platform === "win32")("on Windows", () => {
37+
it("refuses to write or read a file's alternate stream", async () => {
38+
const file = path.join(dir, "notes.txt");
39+
await fs.writeFile(file, "visible");
40+
41+
const write = await call(conn.client, "write_file", {
42+
path: `${file}:hidden`,
43+
content: "payload",
44+
});
45+
expect(write.isError).toBe(true);
46+
expect(textOf(write)).toMatch(REFUSAL);
47+
await expect(fs.readFile(`${file}:hidden`)).rejects.toThrow();
48+
49+
const read = await call(conn.client, "read_text_file", {
50+
path: `${file}::$DATA`,
51+
});
52+
expect(read.isError).toBe(true);
53+
expect(textOf(read)).toMatch(REFUSAL);
54+
});
55+
});
56+
57+
describe.skipIf(process.platform === "win32")("on POSIX", () => {
58+
it("still reads and writes a file whose name holds a colon", async () => {
59+
const file = path.join(dir, "notes.txt:not-a-stream");
60+
61+
const write = await call(conn.client, "write_file", {
62+
path: file,
63+
content: "plain file",
64+
});
65+
expect(write.isError).toBeFalsy();
66+
expect(await fs.readFile(file, "utf8")).toBe("plain file");
67+
68+
const read = await call(conn.client, "read_text_file", { path: file });
69+
expect(read.isError).toBeFalsy();
70+
expect(textOf(read)).toBe("plain file");
71+
});
72+
});
Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
// NTFS alternate-data-stream paths are refused on Windows (#5375), checked on
2+
// any host. As in win32.test.ts, the `path` module is replaced by `path.win32`
3+
// and `process.platform` reads "win32", so path-validation.ts takes its
4+
// Windows branch here on macOS and Linux CI too. The refusal happens before
5+
// any file system call, so a server built for a Windows drive path can be
6+
// driven over the protocol without that drive existing.
7+
8+
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
9+
10+
vi.mock("path", async () => {
11+
const actual = await vi.importActual<typeof import("path")>("path");
12+
return { ...actual.win32, default: actual.win32 };
13+
});
14+
// version.ts finds package.json by walking up a POSIX path, which path.win32
15+
// cannot do; the version is irrelevant to these tests.
16+
vi.mock("../version.js", () => ({ SERVER_VERSION: "0.0.0-test" }));
17+
18+
const { isPathWithinAllowedDirectories, namesAlternateDataStream } =
19+
await import("../path-validation.js");
20+
const { validatePath } = await import("../lib.js");
21+
const { call, connect, quietStderr, textOf } = await import("./helpers.js");
22+
23+
const realPlatform = process.platform;
24+
25+
beforeAll(() => {
26+
Object.defineProperty(process, "platform", { value: "win32" });
27+
});
28+
29+
afterAll(() => {
30+
Object.defineProperty(process, "platform", { value: realPlatform });
31+
});
32+
33+
const REFUSAL = /NTFS alternate data stream paths are not supported/;
34+
35+
describe("namesAlternateDataStream on win32", () => {
36+
it.each([
37+
"C:\\work\\file.txt",
38+
"C:\\",
39+
"\\\\server\\share\\file.txt",
40+
"\\\\?\\C:\\work\\file.txt",
41+
"\\\\.\\C:\\work\\file.txt",
42+
"\\\\?\\UNC\\server\\share\\file.txt",
43+
])("accepts %s, whose only colon is the drive's", (p) => {
44+
expect(namesAlternateDataStream(p)).toBe(false);
45+
});
46+
47+
it.each([
48+
"C:\\work\\file.txt:stream",
49+
"C:\\work\\file.txt::$DATA",
50+
"C:\\work\\file.txt:stream:$DATA",
51+
"C:\\work:stream",
52+
"\\\\server\\share\\file.txt:stream",
53+
"\\\\?\\C:\\work\\file.txt:stream",
54+
"\\\\?\\UNC\\server\\share\\file.txt:stream",
55+
"work\\file.txt:stream",
56+
"AB:\\work",
57+
])("refuses %s, which has a colon past the drive prefix", (p) => {
58+
expect(namesAlternateDataStream(p)).toBe(true);
59+
});
60+
});
61+
62+
describe("isPathWithinAllowedDirectories on win32 refuses alternate streams", () => {
63+
it("throws for a stream on a file inside an allowed directory", () => {
64+
expect(() =>
65+
isPathWithinAllowedDirectories("C:\\work\\file.txt:hidden", ["C:\\work"]),
66+
).toThrow(REFUSAL);
67+
});
68+
69+
it("throws for the default stream spelled out (::$DATA)", () => {
70+
expect(() =>
71+
isPathWithinAllowedDirectories("C:\\work\\file.txt::$DATA", ["C:\\work"]),
72+
).toThrow(REFUSAL);
73+
});
74+
75+
// The issue noted this one already failed containment; it stays refused.
76+
it("throws for a stream on the allowed directory itself", () => {
77+
expect(() =>
78+
isPathWithinAllowedDirectories("C:\\work:stream", ["C:\\work"]),
79+
).toThrow(REFUSAL);
80+
});
81+
82+
it("throws for a stream under a drive-root allowed directory", () => {
83+
expect(() =>
84+
isPathWithinAllowedDirectories("C:\\file.txt:s", ["C:\\"]),
85+
).toThrow(REFUSAL);
86+
});
87+
88+
it("throws for a stream on a UNC share path", () => {
89+
expect(() =>
90+
isPathWithinAllowedDirectories("\\\\server\\share\\f.txt:s", [
91+
"\\\\server\\share",
92+
]),
93+
).toThrow(REFUSAL);
94+
});
95+
96+
it("throws for a stream behind the \\\\?\\ long-path prefix", () => {
97+
expect(() =>
98+
isPathWithinAllowedDirectories("\\\\?\\C:\\work\\f.txt:s", [
99+
"\\\\?\\C:\\work",
100+
]),
101+
).toThrow(REFUSAL);
102+
});
103+
104+
it("still accepts a \\\\?\\ long path under a directory spelled the same way", () => {
105+
expect(
106+
isPathWithinAllowedDirectories("\\\\?\\C:\\work\\f.txt", [
107+
"\\\\?\\C:\\work",
108+
]),
109+
).toBe(true);
110+
});
111+
112+
// A drive-relative path resolves against that drive's current directory,
113+
// so its own colon is the drive's and only a further one is a stream.
114+
it("accepts a drive-relative path and refuses a stream on one", () => {
115+
expect(isPathWithinAllowedDirectories("C:file.txt", ["C:\\"])).toBe(true);
116+
expect(() =>
117+
isPathWithinAllowedDirectories("C:file.txt:s", ["C:\\"]),
118+
).toThrow(REFUSAL);
119+
});
120+
121+
it("names the requested path in the error", () => {
122+
expect(() =>
123+
isPathWithinAllowedDirectories("C:\\work\\a.txt:s", ["C:\\work"]),
124+
).toThrow("C:\\work\\a.txt:s");
125+
});
126+
127+
it("leaves ordinary paths to the containment check", () => {
128+
expect(
129+
isPathWithinAllowedDirectories("C:\\work\\a.txt", ["C:\\work"]),
130+
).toBe(true);
131+
expect(
132+
isPathWithinAllowedDirectories("D:\\other\\a.txt", ["C:\\work"]),
133+
).toBe(false);
134+
});
135+
});
136+
137+
describe("validatePath on win32 refuses alternate streams", () => {
138+
it("reports the stream refusal, not 'outside allowed directories'", async () => {
139+
await expect(
140+
validatePath("C:\\work\\file.txt:hidden", ["C:\\work"]),
141+
).rejects.toThrow(REFUSAL);
142+
});
143+
144+
it("refuses a relative path that names a stream", async () => {
145+
await expect(validatePath("file.txt:hidden", ["C:\\work"])).rejects.toThrow(
146+
REFUSAL,
147+
);
148+
});
149+
});
150+
151+
describe("the tools on win32 refuse alternate streams", () => {
152+
it("returns the refusal as a tool error for a read and a write", async () => {
153+
quietStderr();
154+
const conn = await connect(["C:\\work"]);
155+
try {
156+
const read = await call(conn.client, "read_text_file", {
157+
path: "C:\\work\\notes.txt:hidden",
158+
});
159+
expect(read.isError).toBe(true);
160+
expect(textOf(read)).toMatch(REFUSAL);
161+
162+
const write = await call(conn.client, "write_file", {
163+
path: "C:\\work\\notes.txt::$DATA",
164+
content: "payload",
165+
});
166+
expect(write.isError).toBe(true);
167+
expect(textOf(write)).toMatch(REFUSAL);
168+
} finally {
169+
await conn.close();
170+
vi.restoreAllMocks();
171+
}
172+
});
173+
});

‎src/filesystem/path-validation.ts‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,39 @@
11
import path from "path";
22

3+
// On Windows a colon may appear in a path only as a drive letter's
4+
// (`C:\dir`), optionally behind the `\\?\` or `\\.\` namespace prefix
5+
// (`\\?\C:\dir`). NTFS reads any other colon as an alternate data stream
6+
// (`file.txt:stream`, `file.txt::$DATA`): data stored inside the file that no
7+
// listing, diff or hash of the visible file shows, so the server refuses such
8+
// paths outright rather than let the tools read or write hidden streams
9+
// (#5375, prototyped in #4523). POSIX allows colons in
10+
// names, so the check runs only where `path` is the Windows implementation.
11+
const WINDOWS_DRIVE_PREFIX = /^(?:\\\\[?.]\\)?[A-Za-z]:/;
12+
13+
/**
14+
* True when `normalizedPath`, on Windows, holds a colon anywhere but the
15+
* drive-letter prefix, so NTFS would read it as naming an alternate data
16+
* stream. Always false on POSIX, where a colon is an ordinary name character.
17+
*/
18+
export function namesAlternateDataStream(normalizedPath: string): boolean {
19+
if (path.sep !== "\\") {
20+
return false;
21+
}
22+
const drive = WINDOWS_DRIVE_PREFIX.exec(normalizedPath);
23+
const rest = drive ? normalizedPath.slice(drive[0].length) : normalizedPath;
24+
return rest.includes(":");
25+
}
26+
327
/**
428
* Checks if an absolute path is within any of the allowed directories.
529
*
630
* @param absolutePath - The absolute path to check (will be normalized)
731
* @param allowedDirectories - Array of absolute allowed directory paths (will be normalized)
832
* @returns true if the path is within an allowed directory, false otherwise
933
* @throws Error if given relative paths after normalization
34+
* @throws Error, on Windows, if `absolutePath` names an NTFS alternate data
35+
* stream (a colon anywhere but the drive prefix), so the caller reports
36+
* why it was refused rather than "outside allowed directories" (#5375).
1037
*/
1138
export function isPathWithinAllowedDirectories(
1239
absolutePath: string,
@@ -36,6 +63,12 @@ export function isPathWithinAllowedDirectories(
3663
return false;
3764
}
3865

66+
if (namesAlternateDataStream(normalizedPath)) {
67+
throw new Error(
68+
`Access denied - NTFS alternate data stream paths are not supported (a colon is allowed only after a drive letter): ${absolutePath}`,
69+
);
70+
}
71+
3972
// Verify it's absolute after normalization
4073
/* v8 ignore next -- path.resolve always returns an absolute path, so this cannot fire */
4174
if (!path.isAbsolute(normalizedPath)) {

0 commit comments

Comments
 (0)