ssh-mcp 2.8.0 → 2.8.2

package/build/config/path-containment.js

@@ -0,0 +1,15 @@
+import { isAbsolute, relative, sep } from 'node:path';
+/**
+ * Path-segment-aware containment; unlike a prefix check, siblings never match.
+ *
+ * The `..` cases are spelled out rather than using `rel.startsWith('..')`,
+ * which also rejects a legitimately named sibling such as `..cache`.
+ */
+export function isWithinRoot(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+/** True when either path contains the other, including equality. */
+export function pathsOverlap(left, right) {
+    return isWithinRoot(left, right) || isWithinRoot(right, left);
+}

package/build/config/windows-acl.js

@@ -3,8 +3,9 @@ import { promisify } from 'util';
 import { existsSync, realpathSync } from 'fs';
 import { mkdtemp, readFile, rm } from 'fs/promises';
 import { tmpdir, userInfo } from 'os';
-import { join, resolve, relative, isAbsolute, parse as parsePath } from 'path';
+import { join, resolve, parse as parsePath } from 'path';
 import { OperatorError } from '../errors.js';
+import { isWithinRoot } from './path-containment.js';
 import { parseDacl, aclIdentity, } from './sddl.js';
 const run = promisify(execFile);
 const WINDOWS_ROOT = /^[A-Za-z]:\\Windows$/;
@@ -287,8 +288,11 @@ function isTightenable(path, kind) {
     // path.relative rather than a prefix match: a hardcoded separator was wrong on
     // the platform the tests run on, and a bare startsWith would also accept a
     // sibling whose name merely begins with the profile's (`C:\\Users\\meloud`).
-    const rel = relative(canonical(home), canonical(path));
-    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+    //
+    // Through isWithinRoot rather than a local `!rel.startsWith('..')`, which
+    // rejected a legitimately named child such as `..cache` as an escape. One
+    // containment implementation, shared with the transfer-root gate.
+    return isWithinRoot(canonical(home), canonical(path));
 }
 /**
  * A path in the form the filesystem itself uses, lowercased.

package/build/policy/classifier.js

@@ -1000,13 +1000,24 @@ function hasUnnameableCommand(command) {
  * `~/.ssh/authorized_keys` without touching a shell. Opening a session is the same
  * argument, since it hands over an interactive shell.
  *
- * `sftp:download` and `session:close` are deliberately absent. Both would move *down*
- * from `safe` — download to `read-only`, matching its `readOnlyHint`, and close being a
- * release rather than an acquisition. Lowering a class is a widening, and a security
- * release is the wrong place for one; they keep the class they have today.
+ * `sftp:download`, `sftp:list` and `session:close` are deliberately absent. Each would
+ * move *down* from `safe` — download and list to `read-only`, matching their
+ * `readOnlyHint`, and close being a release rather than an acquisition. Lowering a class
+ * is a widening, and a security release is the wrong place for one; they keep the class
+ * they have today. `sftp:list` is worth spelling out because it is new: a `read-only`
+ * entry for it would also be inert, since the floor below can only raise, and the effect
+ * anyone reaching for it actually wants — letting a `viewer` list a remote directory — is
+ * a binding change, not a classification one.
+ *
+ * `sftp:upload-file` and `sftp:download-file` are `destructive` because each writes a
+ * file: the first on the remote host, the second inside the operator's transfer root.
+ * Without a floor both classify `safe` from the verb alone, which would let an `operator`
+ * write to disk through a tool nobody had approved for it.
  */
 const SYNTHETIC_CLASSES = Object.assign(Object.create(null), {
     'sftp:upload': 'destructive',
+    'sftp:upload-file': 'destructive',
+    'sftp:download-file': 'destructive',
     'session:open': 'destructive',
 });
 /** The first word, tokenised — the synthetic verb when there is one. */

package/build/ssh/sftp.js

@@ -1,4 +1,332 @@
+import ssh2 from 'ssh2';
+import { once } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path/posix';
 import { openWithRetry } from './channel-retry.js';
+/*
+ * Through the default import, not `import { utils } from 'ssh2'`.
+ *
+ * ssh2 is CommonJS. Node's ESM loader statically detects some of its named
+ * exports (`Client`, which connection.ts imports that way) but not `utils`, so
+ * the named form type-checks, passes every vitest run — vitest transforms the
+ * module itself — and then throws `SyntaxError: Named export 'utils' not found`
+ * the first time the *built* artifact is loaded. Only the e2e suite, which
+ * spawns build/index.js, would have caught it.
+ */
+const { STATUS_CODE } = ssh2.utils.sftp;
+/**
+ * The numeric SFTP status a failed request carries, if any.
+ *
+ * ssh2 sets `code` only from the SSH_FXP_STATUS word (a number), never a
+ * libuv-style string — an earlier version of this file also tested for
+ * `'ENOENT'` and `'OP_UNSUPPORTED'`, which can never match. Those dead
+ * comparisons were what forced `(err as any).code`, and the cast in turn hid
+ * that they were dead. Errors ssh2 raises itself (`'No response from server'`,
+ * and the unadvertised-extension throw below) carry no `code` at all, which is
+ * why this returns `undefined` rather than a sentinel.
+ */
+function statusCode(err) {
+    const code = err?.code;
+    return typeof code === 'number' ? code : undefined;
+}
+/**
+ * Thrown when a step's own bound expired, as distinct from the server refusing.
+ *
+ * The difference matters at exactly one place: a publish whose *wait* expired
+ * may still have landed, because the bound covers the wait and not the request.
+ * A publish the server actively refused has definitively not landed. Treating
+ * both as ambiguous told a caller its file "may already hold this upload" when
+ * the real answer was a permission error.
+ */
+export class DeadlineExceededError extends Error {
+}
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * Refuse a bound that cannot do its job, rather than letting it fail oddly.
+ *
+ * `idleTimeoutMs` above 2^31-1 (or `Infinity`, or `NaN`) is clamped by Node to
+ * 1ms, so every step then fails immediately with a message quoting the value
+ * the caller asked for — self-refuting output from a plausible input. `0` is
+ * worse than useless here: elsewhere in this codebase 0 means "no limit"
+ * (`commandQuotaPerDay`, `approvalGrantTtlMs`), so a caller following the house
+ * convention would get the exact opposite of what it asked for.
+ */
+function assertBounds(idleTimeoutMs, byteBudget, label) {
+    if (!Number.isInteger(idleTimeoutMs) || idleTimeoutMs < 1 || idleTimeoutMs > MAX_TIMER_MS) {
+        throw new Error(`${label}: idleTimeoutMs must be an integer between 1 and ${MAX_TIMER_MS}; ` +
+            `0 does not mean "unlimited" here`);
+    }
+    if (!Number.isSafeInteger(byteBudget) || byteBudget < 1) {
+        throw new Error(`${label}: the byte budget must be a positive safe integer`);
+    }
+}
+/** One place the wire shape becomes this module's own, so the masks exist once. */
+function toSftpStat(path, attrs) {
+    return {
+        path,
+        size: attrs.size,
+        mode: attrs.mode,
+        isDirectory: (attrs.mode & 0o170000) === 0o040000,
+        isFile: (attrs.mode & 0o170000) === 0o100000,
+        mtime: new Date(attrs.mtime * 1000),
+        atime: new Date(attrs.atime * 1000),
+    };
+}
+/**
+ * Copy `source` into `destination`, failing if either stalls or the byte cap is
+ * exceeded. Returns the number of bytes the far side acknowledged.
+ *
+ * The cap is enforced on the stream as it flows, not only from a prior stat: a
+ * remote size can be stale, unavailable, or a lie, and a local file can grow
+ * while it is read.
+ *
+ * **Ownership:** this ends `destination` — that is how the bytes are flushed and
+ * how the count becomes trustworthy — but never closes what the destination
+ * wraps. A caller whose `Writable` sits on a resource that must outlive the
+ * stream (a `FileHandle` it still has to `sync()` and publish) must construct it
+ * with `autoClose: false`; otherwise `end()` closes the handle here and the
+ * caller's later `sync()` fails with EBADF.
+ */
+async function transfer(source, destination, opts, direction) {
+    const controller = new AbortController();
+    let rejectFailure;
+    const failure = new Promise((_resolve, reject) => { rejectFailure = reject; });
+    const abortStreams = () => {
+        const reason = controller.signal.reason instanceof Error
+            ? controller.signal.reason
+            : new Error(`SFTP file ${direction} aborted`);
+        rejectFailure(reason);
+        source.destroy();
+        destination.destroy();
+    };
+    const onSourceError = (err) => rejectFailure(err);
+    const onDestinationError = (err) => rejectFailure(err);
+    // Derived once. These three facts are the same question — which end is the
+    // SFTP-backed stream, and therefore which completion event is authoritative —
+    // and re-deriving them at each use made the body read as five decisions.
+    const remoteStream = direction === 'upload' ? destination : source;
+    const settledEvent = direction === 'upload' ? 'close' : 'finish';
+    const destinationSettled = () => (direction === 'upload' ? destination.closed : destination.writableFinished);
+    // Re-armed after every chunk, and once more for the finalize. A slow-but-live
+    // transfer survives; a channel that stops delivering fails within one window.
+    let idle;
+    const arm = () => {
+        if (idle)
+            clearTimeout(idle);
+        idle = setTimeout(() => controller.abort(new Error(`SFTP file ${direction} stalled: no progress for ${opts.idleTimeoutMs}ms`)), opts.idleTimeoutMs);
+    };
+    const disarm = () => { if (idle)
+        clearTimeout(idle); idle = undefined; };
+    const onAbort = () => controller.abort(opts.abortSignal?.reason ?? new Error(`SFTP file ${direction} aborted`));
+    controller.signal.addEventListener('abort', abortStreams, { once: true });
+    source.on('error', onSourceError);
+    destination.on('error', onDestinationError);
+    opts.abortSignal?.addEventListener('abort', onAbort, { once: true });
+    if (opts.abortSignal?.aborted)
+        onAbort();
+    let bytes = 0;
+    let resolveRemoteClosed;
+    const remoteClosed = new Promise((resolve) => { resolveRemoteClosed = resolve; });
+    const onRemoteClose = () => resolveRemoteClosed();
+    remoteStream.once('close', onRemoteClose);
+    // ssh2 constructs its streams with emitClose: false, so a close that has
+    // already happened never replays. Bounded, because this is a courtesy wait
+    // after the work is done, not a step that may hang the caller.
+    const waitForRemoteClose = async () => {
+        if (remoteStream.closed)
+            return;
+        let timer;
+        try {
+            await Promise.race([
+                remoteClosed,
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, Math.min(opts.idleTimeoutMs, 1_000));
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+    arm();
+    try {
+        const copy = async () => {
+            for await (const value of source) {
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+                const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+                bytes += chunk.length;
+                if (bytes > opts.maxBytes) {
+                    throw new Error(`SFTP file ${direction} exceeds the ${opts.maxBytes} byte transfer limit`);
+                }
+                arm();
+                // With the signal: `once` settles on 'drain' or 'error' only, and ssh2's
+                // destroy path emits 'close' without 'error'. A destination that went
+                // away cleanly while we were backpressured therefore left this waiting
+                // for the whole idle window, and surfaced as "no progress" rather than
+                // as the close it was.
+                if (!destination.write(chunk)) {
+                    await once(destination, 'drain', { signal: controller.signal });
+                }
+            }
+            // The finalize costs an SSH_FXP_CLOSE round-trip whose latency has nothing
+            // to do with chunk cadence. Without re-arming, it ran on whatever was left
+            // of the window the last chunk set — sometimes almost nothing — and a
+            // transfer in which every byte was acknowledged failed as "stalled".
+            arm();
+            const completed = new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    destination.removeListener(settledEvent, done);
+                    destination.removeListener('error', failed);
+                };
+                const done = () => { cleanup(); resolve(); };
+                const failed = (err) => { cleanup(); reject(err); };
+                destination.once(settledEvent, done);
+                destination.once('error', failed);
+            });
+            destination.end();
+            if (!destinationSettled())
+                await completed;
+            // Not dead code on the download side, though it looks it: `source` there
+            // is ssh2's SFTP read stream, built with emitClose: false, so `.closed`
+            // never becomes true and finishing the `for await` does not get
+            // SSH_FXP_CLOSE onto the wire. Without this the handle is still open when
+            // withSftp ends the subsystem channel. A review round called it dead after
+            // checking a plain Readable, where it genuinely is.
+            if (direction === 'download' && !source.destroyed)
+                source.destroy();
+            await waitForRemoteClose();
+            return bytes;
+        };
+        return await Promise.race([copy(), failure]);
+    }
+    catch (err) {
+        source.destroy();
+        destination.destroy();
+        await waitForRemoteClose();
+        if (controller.signal.aborted && controller.signal.reason instanceof Error) {
+            throw controller.signal.reason;
+        }
+        throw err;
+    }
+    finally {
+        disarm();
+        controller.signal.removeEventListener('abort', abortStreams);
+        source.removeListener('error', onSourceError);
+        destination.removeListener('error', onDestinationError);
+        remoteStream.removeListener('close', onRemoteClose);
+        opts.abortSignal?.removeEventListener('abort', onAbort);
+    }
+}
+/**
+ * Run one callback-style SFTP operation under its own bound.
+ *
+ * Every metadata round-trip gets `idleTimeoutMs` measured from its own start, so
+ * no single step can hang and none of them consume a budget the next step needs.
+ *
+ * It bounds the *wait*, not the request: a reply that arrives after the bound
+ * finds `settled` already true and is dropped. Callers for whom a late success
+ * matters have to re-establish the state rather than assume failure.
+ *
+ * Exported for its own tests. Driving the timeout through a real SFTP call
+ * cannot pin it: against a container on loopback a metadata round-trip finishes
+ * inside a 1ms bound, so the copy's stall wins the race and the branch this
+ * helper exists for stays unexercised.
+ */
+export function callbackBeforeDeadline(opts, label, start) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (err, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            opts.abortSignal?.removeEventListener('abort', abort);
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        };
+        const abort = () => finish(opts.abortSignal?.reason instanceof Error
+            ? opts.abortSignal.reason
+            : new Error(`${label} aborted`));
+        const timer = setTimeout(() => finish(new DeadlineExceededError(`${label} timed out after ${opts.idleTimeoutMs}ms`)), opts.idleTimeoutMs);
+        opts.abortSignal?.addEventListener('abort', abort, { once: true });
+        if (opts.abortSignal?.aborted)
+            abort();
+        else {
+            try {
+                start(finish);
+            }
+            catch (err) {
+                finish(err);
+            }
+        }
+    });
+}
+function remoteTemporaryPath(remotePath) {
+    return join(dirname(remotePath), `.ssh-mcp-upload-${randomUUID()}.part`);
+}
+/**
+ * Publish a staged upload, atomically where the server allows it.
+ *
+ * ssh2 does not report an unadvertised extension through the callback — it
+ * `throw`s before sending anything, with no `code` on the Error. Both extension
+ * calls are therefore wrapped: an earlier version tested the callback for
+ * `code === 8`, so the plain-`rename` fallback written for exactly these servers
+ * was unreachable and `overwrite: true` failed outright against anything that
+ * does not advertise posix-rename@openssh.com.
+ *
+ * Exported for its own tests. No server in this repo can exercise the throw:
+ * docker-compose pins OpenSSH's sftp-server, and even the Dropbear image
+ * installs openssh-sftp-server because Dropbear ships no SFTP subsystem — so
+ * both extensions are always advertised and the fallback would stay unverified
+ * without a stub.
+ */
+export function publishRemote(sftp, temporary, remotePath, opts) {
+    return callbackBeforeDeadline(opts, 'SFTP upload publish', (callback) => {
+        const standardRename = () => sftp.rename(temporary, remotePath, (err) => callback(err ?? undefined));
+        const unsupported = () => callback(new Error('The SFTP server cannot atomically publish a file without overwrite; retry with overwrite=true'));
+        if (!opts.overwrite) {
+            // SFTP v3 rename has no portable no-clobber semantics. The OpenSSH
+            // hardlink extension maps to link(2), which fails atomically if the
+            // destination appeared after the stat above.
+            try {
+                sftp.ext_openssh_hardlink(temporary, remotePath, (err) => {
+                    if (!err)
+                        return callback();
+                    const code = statusCode(err);
+                    if (code === STATUS_CODE.OP_UNSUPPORTED)
+                        return unsupported();
+                    // v3 has no dedicated "already exists" status, so OpenSSH reports
+                    // EEXIST as FAILURE. Anything else — permission, a filesystem that
+                    // cannot hardlink, quota — used to be reported as a lost race too,
+                    // sending the reader to look for a concurrent writer that never was.
+                    if (code === STATUS_CODE.FAILURE) {
+                        return callback(new Error('Refusing to overwrite a remote file created during transfer'));
+                    }
+                    return callback(new Error(`SFTP upload publish failed: ${err.message}`));
+                });
+            }
+            catch {
+                unsupported();
+            }
+            return;
+        }
+        try {
+            sftp.ext_openssh_rename(temporary, remotePath, (err) => {
+                if (statusCode(err) === STATUS_CODE.OP_UNSUPPORTED)
+                    standardRename();
+                else
+                    callback(err ?? undefined);
+            });
+        }
+        catch {
+            standardRename();
+        }
+    });
+}
 export class SftpClient {
     conn;
     constructor(conn) {
@@ -36,6 +364,19 @@ export class SftpClient {
             catch { /* already torn down */ }
         }
     }
+    /**
+     * Write string or Buffer content to a remote path.
+     *
+     * Deliberately a direct write at 0o644, not a staged `.part` published with
+     * rename, and `||` rather than `??` so `mode: 0` falls back instead of
+     * producing a file nobody can read. This is a pre-existing tool: staging
+     * needs write permission on the *directory* where a direct write needs it
+     * only on the file, and republishing discards the target's mode, owner and
+     * ACL. #185 asked for the text-based tools to stay unchanged, and
+     * test/integration/ssh-sftp.test.ts pins all three properties.
+     *
+     * The streaming path with the opposite trade-offs is uploadFile().
+     */
     async upload(opts) {
         return this.withSftp(async (sftp) => {
             return new Promise((resolve, reject) => {
@@ -47,20 +388,145 @@ export class SftpClient {
         });
     }
     /**
-     * Download a remote file, refusing anything over the cap.
+     * Upload from an already-open source without buffering it in the MCP process.
+     *
+     * Publishes through a sibling `.part` so a failed transfer never leaves a
+     * half-written file at the destination — the right trade for a new tool whose
+     * destination is expected to be new, and the wrong one for upload() above.
+     *
+     * Note what `overwrite: true` costs, since it is the case where the
+     * destination is *not* new: publishing by rename replaces the inode, so the
+     * target's owner and ACL do not survive. The mode does, unless the caller
+     * passes one — see the chmod below.
+     */
+    async uploadFile(source, remotePath, opts) {
+        assertBounds(opts.idleTimeoutMs, opts.maxBytes, 'SFTP upload');
+        return this.withSftp(async (sftp) => {
+            const exists = async () => callbackBeforeDeadline(opts, 'SFTP upload stat', (callback) => {
+                sftp.stat(remotePath, (err) => {
+                    if (!err)
+                        callback(undefined, true);
+                    else if (statusCode(err) === STATUS_CODE.NO_SUCH_FILE)
+                        callback(undefined, false);
+                    else
+                        callback(new Error(`SFTP upload stat failed: ${err.message}`));
+                });
+            });
+            if (!opts.overwrite && await exists()) {
+                throw new Error('Refusing to overwrite an existing remote file');
+            }
+            // Read before the transfer, because after it the destination is about to
+            // be replaced and its mode is the only part we can carry across.
+            const inheritedMode = opts.overwrite && opts.mode === undefined
+                ? await callbackBeforeDeadline(opts, 'SFTP upload mode stat', (callback) => {
+                    sftp.stat(remotePath, (err, stats) => callback(undefined, err ? undefined : stats?.mode));
+                })
+                : undefined;
+            const temporary = remoteTemporaryPath(remotePath);
+            let published = false;
+            try {
+                const destination = sftp.createWriteStream(temporary, {
+                    flags: 'wx',
+                    mode: opts.mode || 0o600,
+                });
+                const bytes = await transfer(source, destination, opts, 'upload');
+                if (inheritedMode !== undefined) {
+                    // Without this, replacing a 0644 service config with a 0600 one is a
+                    // successful-looking upload that silently breaks every other reader.
+                    await callbackBeforeDeadline(opts, 'SFTP upload chmod', (callback) => {
+                        sftp.chmod(temporary, inheritedMode & 0o7777, (err) => callback(err ?? undefined));
+                    });
+                }
+                if (!opts.overwrite && await exists()) {
+                    throw new Error('Refusing to overwrite a remote file created during transfer');
+                }
+                try {
+                    await publishRemote(sftp, temporary, remotePath, opts);
+                    published = true;
+                }
+                catch (err) {
+                    // Only a bound that expired is ambiguous: the request may still be
+                    // in flight, so the destination existing afterwards could be this
+                    // upload. Reporting that as a plain failure sent a retrying caller
+                    // into "Refusing to overwrite an existing remote file" —
+                    // indistinguishable from a squatter, and an argument for
+                    // `overwrite: true` built on a false premise. A publish the server
+                    // actively refused is not ambiguous and must keep its own error.
+                    if (err instanceof DeadlineExceededError && await exists().catch(() => false)) {
+                        published = true;
+                        throw new Error('SFTP upload publish did not confirm within its bound, but the destination now exists. ' +
+                            'Verify the remote file before retrying; it may already hold this upload.');
+                    }
+                    throw err;
+                }
+                if (!opts.overwrite) {
+                    // The hardlink above left two names for one inode; drop ours.
+                    await this.removeTemporary(sftp, temporary, opts.idleTimeoutMs).catch(() => {
+                        console.error('Warning: an SFTP upload was published but its stale .part hard link could not be removed');
+                    });
+                }
+                return bytes;
+            }
+            finally {
+                if (!published) {
+                    await this.removeTemporary(sftp, temporary, opts.idleTimeoutMs).catch(() => {
+                        // Logged, not swallowed: this is the case that leaves remote state
+                        // nobody knows about. local-path.ts says the same thing for the
+                        // local half, and saying nothing here was the asymmetry.
+                        console.error(`Warning: an unpublished SFTP upload left a staging file in ${dirname(remotePath)}; ` +
+                            'look for .ssh-mcp-upload-*.part and remove it');
+                    });
+                }
+            }
+        });
+    }
+    /**
+     * Remove a staging file.
+     *
+     * Takes the timeout as a number rather than the caller's options, because it
+     * deliberately ignores `abortSignal`: cleanup runs on the aborted path, and a
+     * signal threaded through here would make it unrunnable exactly when needed.
+     * Its own short bound keeps it from extending a transfer that already failed.
+     */
+    async removeTemporary(sftp, temporary, idleTimeoutMs) {
+        return callbackBeforeDeadline({ idleTimeoutMs: Math.min(idleTimeoutMs, 1_000) }, 'SFTP upload cleanup', (callback) => sftp.unlink(temporary, (err) => callback(err ?? undefined)));
+    }
+    /**
+     * Download into an already-open destination without buffering it in memory.
      *
-     * exec output has always been capped, but SFTP download was not: the whole
-     * file was buffered, concatenated, decoded to a UTF-16 string and entropy
-     * scanned. A large remote file therefore turned one tool call into multi-GB
-     * RSS and a multi-second event-loop stall for the entire server.
+     * Ends the destination when the transfer completes — see transfer()'s
+     * ownership note. A caller holding a `FileHandle` it still needs (to `sync()`
+     * and publish) must create the stream with `autoClose: false`.
      */
+    async downloadFile(remotePath, destination, opts) {
+        assertBounds(opts.idleTimeoutMs, opts.maxBytes, 'SFTP download');
+        return this.withSftp(async (sftp) => {
+            const size = await callbackBeforeDeadline(opts, 'SFTP download stat', (callback) => {
+                sftp.stat(remotePath, (err, stats) => callback(undefined, err ? undefined : stats?.size));
+            });
+            if (size !== undefined && size > opts.maxBytes) {
+                throw new Error(`SFTP file download exceeds the ${opts.maxBytes} byte transfer limit (${size} bytes)`);
+            }
+            const source = sftp.createReadStream(remotePath);
+            return transfer(source, destination, opts, 'download');
+        });
+    }
     async download(opts) {
         const maxBytes = opts.maxBytes ?? this.conn.profile.maxOutputBytes;
         return this.withSftp(async (sftp) => {
             // Refuse before transferring anything when the size is known up front.
-            const size = await new Promise((resolve) => {
-                sftp.stat(opts.remotePath, (err, stats) => resolve(err ? undefined : stats?.size));
-            });
+            //
+            // Bounded, because this promise had no reject path and no timeout: a
+            // server that accepted SSH_FXP_STAT and never answered left this tool
+            // call suspended for the life of the connection, with no error and
+            // nothing for a caller to act on. That is the same shape as #197 on the
+            // exec side. The bound is the profile's command timeout, which is what
+            // every other step of a tool call already answers to; an unanswerable
+            // stat now falls through to the streaming cap below, exactly as an
+            // unavailable one always did.
+            const size = await callbackBeforeDeadline({ idleTimeoutMs: this.conn.profile.timeout }, 'SFTP download stat', (callback) => {
+                sftp.stat(opts.remotePath, (err, stats) => callback(undefined, err ? undefined : stats?.size));
+            }).catch(() => undefined);
             if (size !== undefined && size > maxBytes) {
                 throw new Error(`Refusing to download ${opts.remotePath}: ${size} bytes exceeds the ${maxBytes} byte limit ` +
                     `(commandMaxOutputBytes). Narrow the file or raise the limit for this profile.`);
@@ -85,25 +551,77 @@ export class SftpClient {
             });
         });
     }
-    async list(remotePath) {
+    /**
+     * List a remote directory, retaining at most `maxEntries + 1` entries.
+     *
+     * Reads happen in server-sized batches; the bound is on what is *retained*,
+     * and the one entry past the limit is what makes `truncated` honest without a
+     * second round-trip. Unbounded readdir was the previous shape, and a directory
+     * with a million entries turned one call into a million-object array.
+     */
+    async list(remotePath, opts) {
+        assertBounds(opts.idleTimeoutMs, opts.maxResponseBytes, 'SFTP list');
+        if (!Number.isInteger(opts.maxEntries) || opts.maxEntries < 1) {
+            throw new Error('SFTP list: maxEntries must be a positive integer');
+        }
         return this.withSftp(async (sftp) => {
-            return new Promise((resolve, reject) => {
-                sftp.readdir(remotePath, (err, list) => {
-                    if (err) {
-                        reject(new Error(`SFTP list error: ${err.message}`));
-                        return;
-                    }
-                    resolve(list.map((entry) => ({
-                        path: `${remotePath}/${entry.filename}`,
-                        size: entry.attrs.size,
-                        mode: entry.attrs.mode,
-                        isDirectory: (entry.attrs.mode & 0o170000) === 0o040000,
-                        isFile: (entry.attrs.mode & 0o170000) === 0o100000,
-                        mtime: new Date(entry.attrs.mtime * 1000),
-                        atime: new Date(entry.attrs.atime * 1000),
-                    })));
+            const handle = await callbackBeforeDeadline(opts, 'SFTP list open', (callback) => {
+                sftp.opendir(remotePath, (err, opened) => {
+                    callback(err ? new Error(`SFTP list error: ${err.message}`) : undefined, opened);
                 });
             });
+            const entries = [];
+            let retained = 0;
+            let responseBytes = 0;
+            let budgetTruncated = false;
+            try {
+                while (retained <= opts.maxEntries && !budgetTruncated) {
+                    const batch = await callbackBeforeDeadline(opts, 'SFTP list read', (callback) => {
+                        // `{ full: true }` so `.` and `..` reach us. Without it ssh2 splices
+                        // them out before the callback, and a server whose READDIR batch
+                        // holds only those two names arrives here as a zero-length batch —
+                        // which the loop would read as EOF and report a listing it never
+                        // read as complete. Genuine EOF is the EOF status, nothing else.
+                        sftp.readdir(handle, { full: true }, (err, list) => {
+                            if (statusCode(err) === STATUS_CODE.EOF)
+                                callback(undefined, null);
+                            else if (err)
+                                callback(new Error(`SFTP list error: ${err.message}`));
+                            else
+                                callback(undefined, list);
+                        });
+                    });
+                    if (batch === null)
+                        break;
+                    for (const entry of batch) {
+                        if (entry.filename === '.' || entry.filename === '..')
+                            continue;
+                        // Bill what is actually retained. `longname` is the server's `ls -l`
+                        // line — attacker-controlled, unbounded up to the packet limit, and
+                        // repeating the filename — so charging only the filename let a
+                        // hostile server retain three orders of magnitude more than the
+                        // budget said. Projecting to SftpStat here rather than pushing
+                        // ssh2's object drops `longname` instead of holding it.
+                        responseBytes += Buffer.byteLength(entry.filename, 'utf8')
+                            + Buffer.byteLength(entry.longname ?? '', 'utf8')
+                            + 256;
+                        if (responseBytes > opts.maxResponseBytes) {
+                            budgetTruncated = true;
+                            break;
+                        }
+                        retained++;
+                        if (retained > opts.maxEntries)
+                            break;
+                        entries.push(toSftpStat(join(remotePath, entry.filename), entry.attrs));
+                    }
+                }
+            }
+            finally {
+                await callbackBeforeDeadline(opts, 'SFTP list close', (callback) => {
+                    sftp.close(handle, () => callback());
+                }).catch(() => { });
+            }
+            return { truncated: budgetTruncated || retained > opts.maxEntries, entries };
         });
     }
     async stat(remotePath) {
@@ -114,15 +632,7 @@ export class SftpClient {
                         reject(new Error(`SFTP stat error: ${err.message}`));
                         return;
                     }
-                    resolve({
-                        path: remotePath,
-                        size: stats.size,
-                        mode: stats.mode,
-                        isDirectory: (stats.mode & 0o170000) === 0o040000,
-                        isFile: (stats.mode & 0o170000) === 0o100000,
-                        mtime: new Date(stats.mtime * 1000),
-                        atime: new Date(stats.atime * 1000),
-                    });
+                    resolve(toSftpStat(remotePath, stats));
                 });
             });
         });

package/build/tools/file-tools.js

@@ -16,7 +16,11 @@ export function registerFileTools({ server }, pipeline) {
             await new SftpClient(rt.conn).upload({ remotePath, content });
             return {
                 audited: syntheticSuccess(rt.profileName),
-                output: textResult(`Uploaded ${content.length} bytes to ${remotePath}`),
+                // Byte count, not string length: `content` is a JS string, so
+                // `.length` counts UTF-16 code units and under-reports every
+                // multi-byte character. SftpClient.upload writes Buffer.from(content),
+                // which is utf8, so this is exactly what lands on the remote side.
+                output: textResult(`Uploaded ${Buffer.byteLength(content, 'utf8')} bytes to ${remotePath}`),
             };
         });
     });

package/build/tools/local-path.js

@@ -0,0 +1,313 @@
+import { randomUUID } from 'node:crypto';
+import { constants, realpath as realpathCb } from 'node:fs';
+import { open, lstat, rename, link, unlink, stat } from 'node:fs/promises';
+import { platform } from 'node:os';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { isWithinRoot, pathsOverlap } from '../config/path-containment.js';
+const INSTALL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+const PATH_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028-\u202e\u2066-\u2069]/;
+/**
+ * `fs.promises.realpath` does not expand Windows 8.3 short names, so two
+ * spellings of one path can compare unequal. The native binding does. On POSIX
+ * the two behave alike, so this is the safe default everywhere rather than a
+ * platform branch that only ever gets exercised on one OS.
+ */
+const realpath = promisify(realpathCb.native);
+function invalid(message) {
+    throw new McpError(ErrorCode.InvalidParams, message);
+}
+function validateInput(input) {
+    if (!input.trim())
+        invalid('Local path cannot be empty');
+    if (PATH_CONTROL_CHARS.test(input)) {
+        invalid('Local path cannot contain control or bidi formatting characters');
+    }
+}
+function display(root, candidate) {
+    const value = relative(root, candidate);
+    return value || '.';
+}
+function confined(root, candidate) {
+    if (!isWithinRoot(root, candidate))
+        invalid('Local path must stay within defaults.transferRoot');
+}
+async function assertPrivateTransferRoot(root) {
+    const info = await stat(root);
+    const uid = process.getuid?.();
+    if (uid !== undefined && info.uid !== uid) {
+        invalid('defaults.transferRoot must be owned by the SSH MCP account');
+    }
+    if ((info.mode & 0o077) !== 0) {
+        invalid('defaults.transferRoot permissions must be 0700');
+    }
+    // A writable ancestor could replace the root between realpath() and open(). Sticky
+    // directories such as /tmp are safe for an owner-controlled child and are allowed.
+    let child = root;
+    for (let parent = dirname(root); parent !== child; child = parent, parent = dirname(parent)) {
+        const parentInfo = await stat(parent);
+        if (uid !== undefined && parentInfo.uid !== uid && parentInfo.uid !== 0) {
+            invalid('defaults.transferRoot has a parent owned by an untrusted account');
+        }
+        const writableByOthers = (parentInfo.mode & 0o022) !== 0;
+        const sticky = (parentInfo.mode & 0o1000) !== 0;
+        if (writableByOthers && !sticky) {
+            invalid('defaults.transferRoot has an unsafe writable parent directory');
+        }
+    }
+}
+async function configuredRoot(ctx) {
+    // Windows is refused outright rather than verified with the config-file ACL
+    // posture, which waives a read-exposed directory, never reads the `O:` owner,
+    // and treats a missing or slow `icacls.exe` as a pass. A transfer root that
+    // cannot be verified must disable the tools, not enable them.
+    if (platform() === 'win32') {
+        invalid('Streaming SFTP file tools are not available on Windows: the transfer root cannot yet ' +
+            'be verified private there, and an unverifiable root would leave every downloaded file ' +
+            'readable by other accounts on the machine.');
+    }
+    const input = ctx.transferRoot;
+    if (!input)
+        invalid('Streaming SFTP file tools require defaults.transferRoot in config.toml');
+    if (!isAbsolute(input))
+        invalid('defaults.transferRoot must be an absolute path');
+    let canonical;
+    try {
+        canonical = await realpath(input);
+    }
+    catch {
+        invalid('defaults.transferRoot is not an accessible directory');
+    }
+    const info = await stat(canonical);
+    if (!info.isDirectory())
+        invalid('defaults.transferRoot must name a directory');
+    const install = await realpath(INSTALL_DIR);
+    if (pathsOverlap(canonical, install)) {
+        invalid('defaults.transferRoot must be separate from the SSH MCP installation');
+    }
+    if (ctx.configPath) {
+        let configDir;
+        try {
+            configDir = dirname(await realpath(resolve(ctx.configPath)));
+        }
+        catch {
+            invalid('The SSH MCP config directory cannot be resolved safely');
+        }
+        if (pathsOverlap(canonical, configDir)) {
+            invalid('defaults.transferRoot must be separate from the SSH MCP config directory');
+        }
+    }
+    // The install and config directories are not the only sensitive ones. A root
+    // containing the audit log lets a download replace the tamper-evident record
+    // of the transfer that wrote it, and a root shaped like ~/.ssh turns the same
+    // tools into "read the private key" and "append to authorized_keys". Both are
+    // conventionally 0700 and owner-owned, so the privacy checks above accept
+    // them; they have to be excluded by name.
+    for (const entry of ctx.forbidden ?? []) {
+        let forbidden;
+        try {
+            forbidden = await realpath(entry.path);
+        }
+        catch {
+            // A directory that does not exist yet cannot contain the root, but its
+            // lexical form still can once it is created.
+            forbidden = resolve(entry.path);
+        }
+        if (pathsOverlap(canonical, forbidden)) {
+            invalid(`defaults.transferRoot must be separate from ${entry.reason}`);
+        }
+    }
+    await assertPrivateTransferRoot(canonical);
+    return { configured: resolve(input), canonical };
+}
+/**
+ * Make a caller's path comparable to the canonical root without touching the
+ * filesystem outside it.
+ *
+ * `resolve(root, input)` ignores `root` entirely when `input` is absolute, so a
+ * legitimate absolute path spelled the way a shell shows it — macOS `/var/...`
+ * for a root canonicalized to `/private/var/...` — is not yet comparable. The
+ * previous shape confined this lexical form immediately and therefore refused
+ * those outright, on every host whose transfer root sits behind a symlink.
+ *
+ * Accepting either spelling fixes that. The check stays lexical so that a path
+ * outside the root is refused before anything stats it, which is what keeps
+ * these tools from answering "does this file exist?" for arbitrary paths.
+ */
+function lexicalCandidate(root, input) {
+    const candidate = resolve(root.canonical, input);
+    if (isWithinRoot(root.canonical, candidate))
+        return candidate;
+    if (isWithinRoot(root.configured, candidate))
+        return candidate;
+    invalid('Local path must stay within defaults.transferRoot');
+}
+/** Open an existing regular file once, so the transfer never re-resolves its path. */
+export async function localFileForRead(ctx, input, onResolved) {
+    try {
+        validateInput(input);
+        const root = await configuredRoot(ctx);
+        const lexical = lexicalCandidate(root, input);
+        // Canonicalize the parent before the leaf: the leaf may be a symlink that
+        // has to be refused rather than followed, and its own realpath would hide
+        // that. Confining the parent first also means the leaf is only ever lstat'd
+        // once it is known to be inside the root.
+        const parent = await realpath(dirname(lexical));
+        confined(root.canonical, parent);
+        const candidate = resolve(parent, basename(lexical));
+        confined(root.canonical, candidate);
+        onResolved?.(display(root.canonical, candidate));
+        if ((await lstat(candidate)).isSymbolicLink()) {
+            invalid(`Local upload source cannot be a symlink: ${input}`);
+        }
+        const real = await realpath(candidate);
+        confined(root.canonical, real);
+        const handle = await open(real, constants.O_RDONLY | NO_FOLLOW);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile())
+                invalid(`Local path is not a regular file: ${input}`);
+            return { handle, size: info.size, displayPath: display(root.canonical, real) };
+        }
+        catch (err) {
+            await handle.close().catch(() => { });
+            throw err;
+        }
+    }
+    catch (err) {
+        if (err instanceof McpError)
+            throw err;
+        invalid(`Local upload source is not an accessible regular file: ${input}`);
+    }
+}
+/** Resolve a destination through its real parent and enforce overwrite policy. */
+export async function localFileForWrite(ctx, input, overwrite, onResolved) {
+    try {
+        validateInput(input);
+        const root = await configuredRoot(ctx);
+        const lexical = lexicalCandidate(root, input);
+        const parent = await realpath(dirname(lexical));
+        confined(root.canonical, parent);
+        const destination = resolve(parent, basename(lexical));
+        confined(root.canonical, destination);
+        const target = { destination, displayPath: display(root.canonical, destination), parent };
+        onResolved?.(target);
+        try {
+            const info = await lstat(destination);
+            if (!overwrite)
+                invalid(`Refusing to overwrite existing local file: ${input}`);
+            if (info.isSymbolicLink())
+                invalid(`Refusing to overwrite a local symlink: ${input}`);
+            if (!info.isFile())
+                invalid(`Local destination is not a regular file: ${input}`);
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                throw err;
+        }
+        return target;
+    }
+    catch (err) {
+        if (err instanceof McpError)
+            throw err;
+        invalid(`Local download destination is not accessible: ${input}`);
+    }
+}
+async function assertParentUnchanged(target) {
+    let currentParent;
+    try {
+        currentParent = await realpath(dirname(target.destination));
+    }
+    catch {
+        invalid('Local destination parent changed during transfer');
+    }
+    if (currentParent !== target.parent)
+        invalid('Local destination parent changed during transfer');
+}
+/** Create a same-directory temporary file and publish it atomically. */
+export async function createLocalDownload(ctx, input, overwrite, onResolved) {
+    const target = await localFileForWrite(ctx, input, overwrite, onResolved);
+    await assertParentUnchanged(target);
+    const temporary = resolve(target.parent, `.ssh-mcp-download-${randomUUID()}.part`);
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NO_FOLLOW, 0o600);
+    }
+    catch {
+        invalid('Local download temporary file could not be created safely');
+    }
+    let published = false;
+    // Handed out by createStream() and torn down here, because the two belong
+    // together: an `autoClose: false` stream that has finished but not been
+    // destroyed makes `handle.close()` hang indefinitely — measured, not
+    // theorised. Giving the caller the stream without owning its teardown just
+    // moved the hazard one level out.
+    let stream;
+    const releaseStream = () => {
+        if (stream && !stream.destroyed)
+            stream.destroy();
+        stream = undefined;
+    };
+    return {
+        handle,
+        temporary,
+        target,
+        createStream() {
+            stream ??= handle.createWriteStream({ autoClose: false });
+            return stream;
+        },
+        async publish() {
+            // No releaseStream() here: destroying the stream closes the handle even
+            // with autoClose: false, and sync() below needs it open. Teardown belongs
+            // to cleanup(), which the caller always runs.
+            await assertParentUnchanged(target);
+            try {
+                await handle.sync();
+                if (overwrite) {
+                    await rename(temporary, target.destination);
+                    published = true;
+                }
+                else {
+                    // link() fails with EEXIST rather than clobbering, which is the
+                    // no-overwrite guarantee; the temporary is unlinked afterwards.
+                    await link(temporary, target.destination);
+                    published = true;
+                    await unlink(temporary).catch(() => {
+                        console.error('Warning: an SFTP download was published but its stale .part hard link could not be removed');
+                    });
+                }
+            }
+            catch (err) {
+                if (err?.code === 'EEXIST')
+                    invalid('Refusing to overwrite a local file created during transfer');
+                throw new McpError(ErrorCode.InternalError, 'Local download could not be published safely');
+            }
+            try {
+                const parentHandle = await open(target.parent, constants.O_RDONLY);
+                try {
+                    await parentHandle.sync();
+                }
+                finally {
+                    await parentHandle.close();
+                }
+            }
+            catch {
+                console.error('Warning: SFTP download was published, but its directory metadata could not be synced');
+            }
+        },
+        async cleanup() {
+            releaseStream();
+            await handle.close().catch(() => { });
+            if (!published) {
+                await unlink(temporary).catch((err) => {
+                    console.error(err?.code === 'ENOENT'
+                        ? 'Warning: an unpublished SFTP temporary file is no longer reachable; check transferRoot for stale .part files'
+                        : 'Warning: an unpublished SFTP temporary file could not be removed; check transferRoot for stale .part files');
+                });
+            }
+        },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
   "mcpName": "io.github.tufantunc/ssh-mcp",
   "type": "module",
@@ -33,7 +33,7 @@
     "@opentelemetry/resources": "^2.9.0",
     "@opentelemetry/sdk-node": "^0.221.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
-    "smol-toml": "^1.7.0",
+    "smol-toml": "^1.7.1",
     "ssh2": "^1.17.0",
     "zod": "^4.4.3"
   },