feat(sftp): add the local-path gate for the streaming file tools

[tufantunc]

Second piece of the #186 takeover, after #205. The module is inert — nothing imports it yet, so no tool behaviour changes. Wiring it to sftp-list / sftp-upload-file / sftp-download-file is the next PR.

What differs from #186

1. The path-resolution order (was one of the two blocking test failures)

const root = await configuredRoot(...);   // realpath'd → /private/var/...
const lexical = resolve(root, input);     // ignores `root` when input is absolute
confined(root, lexical);                  // ← threw here
const candidate = await realpath(lexical);// the correct check, never reached

resolve(root, input) ignores root entirely for an absolute input, so a path spelled the way an operator's shell shows it is not yet comparable to a realpath'd root. Confining that form first refused every legitimate absolute path on any host whose transfer root sits behind a symlink — which is every macOS host.

Fixed by checking the candidate against both spellings of the root (canonical and as-configured) lexically, then canonicalizing the parent before the leaf.

2. The refusal stays lexical, on purpose

The obvious fix — delete the early check and rely on realpath-then-confine — would make these tools answer "does this path exist?" for arbitrary locations, since a resolvable parent and an unresolvable one produce different errors. A test pins it:

const existing = localFileForRead(ctx, '/etc/hosts');
const absent   = localFileForRead(ctx, '/ssh-mcp-no-such-root-9f3a/file');
expect(a).toBe(b);   // byte-identical

It fails if the lexical gate is removed. Verified by removing it.

3. Windows is refused outright

Not reused from the config-file ACL posture, which waives a read-exposed directory, never consults the O: owner, and treats a missing or slow icacls.exe as a pass. A root that cannot be verified must disable the tools. The Windows gate is its own piece (C).

4. The audit log and SSH key directories are excludable

Both are conventionally 0700 and owner-owned, so the ownership/permission checks accept them — and a transfer root containing either turns a download into overwrite the record of this transfer and an upload into read the private key. A forbidden directory that does not exist yet still counts, so creating it later cannot re-open the hole.

Verification

Every claim above was checked by mutating the source and re-running:

Mutation	Result
restore #186's immediate confined(root, lexical)	2 tests red — the same two failures the review found
drop the lexical gate entirely	the existence-oracle test goes red

27 new unit tests; npm run test:unit is 867 passing. windows-acl keeps its 100 (14 win32-only skip locally, they run on the windows job).

Also here

• a macos CI job, wired into the required ci aggregate — without it the bug in §1 is invisible, since neither ubuntu-latest nor windows-latest has a symlinked temp dir. Lean: no docker, so no integration/e2e, no coverage upload.
• windows-acl.ts containment now uses the shared helper instead of its own !rel.startsWith('..'), which rejected a legitimately named ..cache as an escape. That one is a real if narrow fix, so it carries the changeset.

Still to come

• B2 — the three tools, sftp.ts streaming, and the ordering answer from Streaming SFTP tools need the audited string resolved before policy without side effects preceding it #207
• C — the Windows gate, fail-closed
• Streaming SFTP transfers need their own timeout, not commandTimeoutMs #206 (transfer timeout), Streaming SFTP tools need the audited string resolved before policy without side effects preceding it #207 (audited string vs policy ordering)

[codecov]

Codecov Report

❌ Patch coverage is 74.81481% with 34 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.41%. Comparing base (9296af2) to head (1bf6c56).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/tools/local-path.ts	74.04%	20 Missing and 14 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #208      +/-   ##
==========================================
- Coverage   82.90%   82.41%   -0.49%     
==========================================
  Files          35       37       +2     
  Lines        2176     2309     +133     
  Branches      606      640      +34     
==========================================
+ Hits         1804     1903      +99     
- Misses        257      277      +20     
- Partials      115      129      +14     

Files with missing lines	Coverage Δ
src/config/path-containment.ts	100.00% <100.00%> (ø)
src/config/windows-acl.ts	88.88% <100.00%> (-0.11%)	⬇️
src/tools/local-path.ts	74.04% <74.04%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.