Repository navigation
docs(filesystem): document the Windows parent-directory swap as a limit of the implementation - #5568
Conversation
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>
|
|
| Tools | Prompts | Resources | Resource templates | |
|---|---|---|---|---|
| Base | 16 | 0 | 0 | 1 |
| Head | 16 | 0 | 0 | 1 |
Updated by this run for 8d932c7e48a2d24602bfe33b6f21e11321d21c4a.
There was a problem hiding this comment.
🟢 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
|
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. |
Closes #5566
Description
Documents the Windows parent-directory swap as a limit of the
filesystemserver'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 theenginesfloor).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:
verifyWorkingDirectoryskips thegetcwd()read-back there, and what remains is the final-component check inopenInDirectory(a write refuses a link at the file's own name, and the opened file must be the one anlstatof that name finds afterwards). The README says that narrows the window without closing it, as the file's header does.Server Details
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 --stattouches onlysrc/filesystem/README.mdandsrc/filesystem/pinned-directory.ts, and the.tsdiff is three added//lines in the header comment.git grep -n 5260finds no other reference in the tree, and neither the rootREADME.mdnordocs/describes the swap protection, so nothing else needed the sentence.npm run local:gateexits 0 on the branch.Breaking Changes
None.
Types of changes
Checklist
🤖 Generated with Claude Code