Skip to content

docs(filesystem): document the Windows parent-directory swap as a limit of the implementation - #5568

Merged
cliffhall merged 1 commit into
v2/mainfrom
v2/docs/5566-filesystem-windows-swap-limit
Nov 18, 2026
Merged

cliffhall merged 1 commit into
v2/mainfrom
v2/docs/5566-filesystem-windows-swap-limit

Conversation

@cliffhall

Copy link
Copy Markdown
Member

Closes #5566

Description

Documents the Windows parent-directory swap as a limit of the filesystem server's implementation, now that #5260 is closed as not planned.

  • src/filesystem/README.md, under Access Control, beside the existing Windows path notes: a new bullet stating that Linux and macOS anchor each operation to the directory they validated and Windows cannot, so on Windows a second local process that can already write inside an allowed directory can replace a parent directory with a junction between the server's check and its open and redirect a read or a write outside the allowed directories. It gives the precondition (a concurrent local process with write access inside an allowed directory; no tool of this server creates a junction or symlink), the guidance (on Windows, do not allow a directory that untrusted local processes or users can write to), and why it is not fixed (handle-relative opens need native code, out of scope for a reference server; may be revisited when Node ships a stable built-in FFI under the engines floor).
  • src/filesystem/pinned-directory.ts: three comment lines added to the file header's Windows paragraph, saying the gap is a decided limit rather than pending work and pointing at the README. Comment only.

The README wording follows what the code does on Windows: verifyWorkingDirectory skips the getcwd() read-back there, and what remains is the final-component check in openInDirectory (a write refuses a link at the file's own name, and the opened file must be the one an lstat of that name finds afterwards). The README says that narrows the window without closing it, as the file's header does.

Server Details

  • Server: filesystem
  • Changes to: docs (README), one source comment

Motivation and Context

#5566. A reader of the README would otherwise conclude that "restricted to allowed directories" holds equally on every platform. Background: #5237 (the Linux/macOS fix) and the closing comment on #5260.

How Has This Been Tested?

This change has no client-observable surface, so the evidence is a targeted probe rather than client runs:

  • git diff origin/v2/main --stat touches only src/filesystem/README.md and src/filesystem/pinned-directory.ts, and the .ts diff is three added // lines in the header comment.
  • No other document repeats the claim: git grep -n 5260 finds no other reference in the tree, and neither the root README.md nor docs/ describes the swap protection, so nothing else needed the sentence.
  • npm run local:gate exits 0 on the branch.

Breaking Changes

None.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Protocol Documentation (not applicable: no protocol feature is touched)
  • My changes follow MCP security best practices (the change documents a known limit and the guidance for it)
  • I have updated the server's README accordingly
  • I have added a changeset (not applicable: a README change and a source comment change nothing a TypeScript server publishes that behaves differently; filesystem: document the Windows parent-directory swap as a limit of the implementation #5566 calls for none)
  • I have tested this with an LLM client (not applicable: documentation only, no server behavior changed, so there is nothing for a client to exercise)
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling (not applicable: no code path changed)
  • I have documented all environment variables and configuration options (not applicable: none added)

🤖 Generated with Claude Code

The README now states that on Windows a parent directory swapped for a
junction between the server's check and its open is not protected against,
what exploiting it takes, the guidance for Windows, and why it is not fixed.
The header of pinned-directory.ts says the gap is a decided limit rather
than pending work. No behavior changes.

Closes #5566

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@cliffhall cliffhall added the v2 label Nov 18, 2026
@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 8d932c7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@github-actions

Copy link
Copy Markdown
Contributor

filesystem: MCP interface diff

Base: 88af1edb1b61 (Merge pull request #5564 from modelcontextprotocol/v2/fix/5557-fetch-pin-checked-address)
Head: the build in this checkout, at 75af30cdc603 (Merge 8d932c7 into 88af1ed)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 16 0 0 1
Head 16 0 0 1

Updated by this run for 8d932c7e48a2d24602bfe33b6f21e11321d21c4a.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the change documenting the Windows parent-directory swap limitation.

No open issues 🎉

What changed in this PR

Documents the filesystem server’s Windows parent-directory swap limitation, as requested in #5566, following the decision not to pursue a native-code fix in #5260.

Changes:

  • Explains the Windows limitation, its exploitation preconditions, and guidance for choosing trusted allowed directories.
  • Updates the source header to describe the gap as an accepted implementation limit rather than pending work.
  • Changes documentation and comments only; runtime behavior is unchanged.
File Description
src/​filesystem/​README.md Documents platform protection differences, Windows risks, and user guidance.
src/​filesystem/​pinned-directory.ts Adds header comments recording the decision and pointing to the README.

Review effort: Balanced

@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 1: clean. The review posted no comments and no suppressed findings ("No open issues"), so the loop ends here on the first clean round. Nothing was pushed in response.

@cliffhall
cliffhall merged commit aef8fd7 into v2/main Nov 18, 2026
46 checks passed
@cliffhall
cliffhall deleted the v2/docs/5566-filesystem-windows-swap-limit branch November 18, 2026 05:48
@cliffhall cliffhall mentioned this pull request Nov 18, 2026
10 of 13 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

filesystem: document the Windows parent-directory swap as a limit of the implementation

2 participants