@aaarc/handfree-ssh-mcp 1.0.7 → 1.0.10

package/build/config/server.js

@@ -1,6 +1,6 @@
 export const SERVER_CONFIG = {
     name: "ssh-mcp-server",
-    version: "1.0.7",
+    version: "1.0.10",
 };
 export const SERVER_INSTRUCTIONS = `This server provides SSH access to servers loaded from OpenSSH config (~/.ssh/config by default) and optional YAML config/policy overlays.
 

package/build/services/ssh-connection-manager.js

@@ -721,6 +721,116 @@ export class SSHConnectionManager {
         }
         return Math.max(1, timeout);
     }
+    /**
+     * Run a transfer that reports progress through a callback, aborting it if no
+     * progress arrives within `timeoutMs` (an INACTIVITY watchdog, not a total
+     * duration cap -- a long but actively-streaming transfer is never killed).
+     * When `timeoutMs` is falsy the operation runs unbounded, preserving the
+     * previous behavior. `onTimeout` is invoked to tear down the stalled session.
+     */
+    runWithInactivityTimeout(start, timeoutMs, description, debug, onTimeout) {
+        if (!timeoutMs || timeoutMs <= 0) {
+            return start(() => { });
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer = null;
+            const clear = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+            };
+            const arm = () => {
+                clear();
+                timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    debug?.(`[mcp] ${description} stalled: no progress for ${timeoutMs}ms`);
+                    try {
+                        onTimeout?.();
+                    }
+                    catch {
+                        // Ignore cleanup failures after a stall.
+                    }
+                    reject(new ToolError("SSH_CONNECTION_FAILED", `${description} stalled: no progress for ${timeoutMs}ms`, true));
+                }, timeoutMs);
+            };
+            const onProgress = () => {
+                if (!settled)
+                    arm();
+            };
+            arm();
+            start(onProgress).then((value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clear();
+                resolve(value);
+            }, (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clear();
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Default inactivity window (ms) for SFTP data transfers when the caller does
+     * not pass an explicit timeout. Deliberately generous: a healthy transfer
+     * moves bytes far more often than this, so tripping it means the connection
+     * is effectively dead, not merely slow.
+     */
+    static DEFAULT_TRANSFER_STALL_TIMEOUT_MS = 60_000;
+    /** Chunk size for buffered SFTP writes, sized to yield per-ack progress. */
+    static SFTP_WRITE_CHUNK_BYTES = 256 * 1024;
+    /**
+     * Resolve the inactivity window for a data transfer: the caller's timeout if
+     * valid, otherwise the generous default so a dead connection never hangs.
+     */
+    transferStallTimeout(timeout) {
+        return (this.normalizeConnectTimeout(timeout) ??
+            SSHConnectionManager.DEFAULT_TRANSFER_STALL_TIMEOUT_MS);
+    }
+    /**
+     * Pipe a readable into a writable under the inactivity watchdog, aborting if
+     * no bytes flow for the stall window. Used by the non-fast download and relay
+     * paths, which otherwise settle only on close/finish/error and so hang on a
+     * dead reused connection. Read-side `data` events drive progress; the caller
+     * supplies error mappers so each path keeps its own error code/message.
+     */
+    pipeWithInactivityTimeout(readStream, writeStream, timeoutMs, description, debug, mapReadError, mapWriteError) {
+        const teardown = () => {
+            this.unpipeStream(readStream, writeStream);
+            this.destroyStream(readStream);
+            this.destroyStream(writeStream);
+        };
+        return this.runWithInactivityTimeout((onProgress) => new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (err) {
+                    teardown();
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            };
+            readStream.on("data", () => onProgress());
+            // Resolve on whichever completion event the write side emits: local fs
+            // writables emit "finish", SFTP writables emit "close".
+            writeStream.on("finish", () => settle());
+            writeStream.on("close", () => settle());
+            writeStream.on("error", (err) => settle(mapWriteError(err)));
+            readStream.on("error", (err) => settle(mapReadError(err)));
+            readStream.pipe(writeStream);
+        }), timeoutMs, description, debug, teardown);
+    }
     /**
      * Open a TCP tunnel from the target's jump chain to `config.host:config.port`
      * and return the duplex stream to be used as `sock` for the target SSH client.
@@ -1306,12 +1416,29 @@ export class SSHConnectionManager {
         return new Promise((resolve, reject) => {
             let timeoutId = null;
             let settled = false;
-            const cleanup = () => {
+            let channelOpened = false;
+            let activeStream = null;
+            const eventedClient = client;
+            const canObserveClientLifecycle = typeof eventedClient.once === "function" &&
+                typeof eventedClient.removeListener === "function";
+            const clearCommandTimer = () => {
                 if (timeoutId) {
                     clearTimeout(timeoutId);
                     timeoutId = null;
                 }
             };
+            const removeClientLifecycleListeners = () => {
+                if (!canObserveClientLifecycle) {
+                    return;
+                }
+                eventedClient.removeListener?.("error", onClientError);
+                eventedClient.removeListener?.("end", onClientEnd);
+                eventedClient.removeListener?.("close", onClientClose);
+            };
+            const cleanup = () => {
+                clearCommandTimer();
+                removeClientLifecycleListeners();
+            };
             const settle = (err, code) => {
                 if (settled)
                     return;
@@ -1330,6 +1457,24 @@ export class SSHConnectionManager {
                     // Ignore late-stream close errors after the promise has settled.
                 }
             };
+            const failOnClientEvent = (event, message) => {
+                const phase = channelOpened ? "running command" : "opening command channel";
+                const detail = message ? `: ${message}` : "";
+                sinks.debug?.(`[mcp] SSH client ${event} while ${phase}${detail}`);
+                if (activeStream) {
+                    closeLateStream(activeStream);
+                }
+                settle(new ToolError("SSH_CONNECTION_FAILED", `SSH connection ${event} while ${phase}${detail}`, true));
+            };
+            const onClientError = (err) => {
+                failOnClientEvent("failed", err.message);
+            };
+            const onClientEnd = () => {
+                failOnClientEvent("ended");
+            };
+            const onClientClose = () => {
+                failOnClientEvent("closed");
+            };
             const armExecOpenTimeout = () => {
                 const execOpenTimeout = Math.max(1, timeout);
                 timeoutId = setTimeout(() => {
@@ -1356,6 +1501,11 @@ export class SSHConnectionManager {
                 }, timeout);
             };
             armExecOpenTimeout();
+            if (canObserveClientLifecycle) {
+                eventedClient.once?.("error", onClientError);
+                eventedClient.once?.("end", onClientEnd);
+                eventedClient.once?.("close", onClientClose);
+            }
             sinks.debug?.(`[mcp] opening exec channel for command: ${cmdString}`);
             try {
                 client.exec(cmdString, (err, stream) => {
@@ -1371,7 +1521,9 @@ export class SSHConnectionManager {
                         settle(new ToolError(code, `Command execution error: ${err.message}`, isConnectionFailure));
                         return;
                     }
-                    cleanup();
+                    clearCommandTimer();
+                    channelOpened = true;
+                    activeStream = stream;
                     sinks.debug?.("[mcp] exec channel opened");
                     stream.on("data", (chunk) => {
                         sinks.stdoutCollector?.push(chunk);
@@ -2013,83 +2165,164 @@ export class SSHConnectionManager {
     }
     /**
      * Read an SFTP file fully into a Buffer.
+     *
+     * Guarded by an inactivity watchdog: if no bytes arrive for the stall window
+     * (a dead reused connection can open the channel but never stream) the read
+     * aborts with a retriable error instead of hanging. An actively-streaming
+     * read is never killed because each chunk resets the watchdog.
      */
     async sftpReadBuffer(client, remotePath, expectedSize, timeout, debug) {
         const sftp = await this.openSftp(client, "read", timeout, debug);
-        return new Promise((resolve, reject) => {
-            const chunks = [];
-            let received = 0;
-            const stream = sftp.createReadStream(remotePath);
-            stream.on("data", (chunk) => {
-                chunks.push(chunk);
-                received += chunk.length;
-            });
-            stream.on("error", (e) => {
-                sftp.end();
-                reject(this.makeSftpError("Remote read failed", e));
-            });
-            stream.on("end", () => {
+        const endSftp = () => {
+            try {
                 sftp.end();
-                if (received !== expectedSize) {
-                    return reject(new ToolError("SFTP_ERROR", `Remote read short: expected ${expectedSize} bytes, got ${received}`, false));
-                }
-                resolve(Buffer.concat(chunks, received));
-            });
-        });
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        };
+        try {
+            return await this.runWithInactivityTimeout((onProgress) => new Promise((resolve, reject) => {
+                const chunks = [];
+                let received = 0;
+                const stream = sftp.createReadStream(remotePath);
+                stream.on("data", (chunk) => {
+                    chunks.push(chunk);
+                    received += chunk.length;
+                    onProgress();
+                });
+                stream.on("error", (e) => {
+                    reject(this.makeSftpError("Remote read failed", e));
+                });
+                stream.on("end", () => {
+                    if (received !== expectedSize) {
+                        return reject(new ToolError("SFTP_ERROR", `Remote read short: expected ${expectedSize} bytes, got ${received}`, false));
+                    }
+                    resolve(Buffer.concat(chunks, received));
+                });
+            }), this.transferStallTimeout(timeout), `remote read ${remotePath}`, debug, endSftp);
+        }
+        finally {
+            endSftp();
+        }
     }
     /**
      * Write a Buffer to an SFTP path (overwrites if exists).
+     *
+     * The payload is written in chunks so the inactivity watchdog gets a real
+     * progress signal per acknowledged chunk: a dead reused connection that opens
+     * the channel but never acks a write aborts with a retriable error instead of
+     * hanging, while an actively-flushing write is never killed.
      */
     async sftpWriteBuffer(client, remotePath, payload, timeout, debug) {
         const sftp = await this.openSftp(client, "write", timeout, debug);
-        return new Promise((resolve, reject) => {
-            const writeStream = sftp.createWriteStream(remotePath);
-            writeStream.on("close", () => {
-                sftp.end();
-                resolve();
-            });
-            writeStream.on("error", (e) => {
+        const endSftp = () => {
+            try {
                 sftp.end();
-                reject(this.makeSftpError("File upload failed", e));
-            });
-            writeStream.end(payload);
-        });
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        };
+        try {
+            await this.runWithInactivityTimeout((onProgress) => new Promise((resolve, reject) => {
+                const writeStream = sftp.createWriteStream(remotePath);
+                let offset = 0;
+                let ended = false;
+                writeStream.on("close", () => resolve());
+                writeStream.on("error", (e) => {
+                    reject(this.makeSftpError("File upload failed", e));
+                });
+                const writeNext = () => {
+                    if (offset >= payload.length) {
+                        if (!ended) {
+                            ended = true;
+                            writeStream.end();
+                        }
+                        return;
+                    }
+                    const end = Math.min(offset + SSHConnectionManager.SFTP_WRITE_CHUNK_BYTES, payload.length);
+                    const chunk = payload.subarray(offset, end);
+                    offset = end;
+                    writeStream.write(chunk, (err) => {
+                        if (err) {
+                            // The "error" event will reject; nothing else to do here.
+                            return;
+                        }
+                        onProgress();
+                        writeNext();
+                    });
+                };
+                writeNext();
+            }), this.transferStallTimeout(timeout), `upload ${remotePath}`, debug, endSftp);
+        }
+        finally {
+            endSftp();
+        }
     }
     /**
      * Upload a local file using ssh2's parallel SFTP fastPut implementation.
      */
     async sftpFastPut(client, localPath, remotePath, options, timeout, debug) {
-        const sftp = await this.openSftp(client, "fastPut", timeout, debug);
+        // Validate transfer options BEFORE opening the channel so invalid options
+        // can never leak an SFTP channel.
         const transferOptions = this.createSftpTransferOptions(options);
+        const sftp = await this.openSftp(client, "fastPut", timeout, debug);
         debug?.(`[mcp] fastPut ${localPath} -> ${remotePath}, concurrency=${transferOptions.concurrency ?? "ssh2-default"}, chunkSize=${transferOptions.chunkSize ?? "ssh2-default"}`);
-        return new Promise((resolve, reject) => {
-            sftp.fastPut(localPath, remotePath, transferOptions, (err) => {
+        const endSftp = () => {
+            try {
                 sftp.end();
-                if (err) {
-                    reject(this.makeSftpError("Fast upload failed", err));
-                    return;
-                }
-                resolve();
-            });
-        });
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        };
+        try {
+            await this.runWithInactivityTimeout((onProgress) => new Promise((resolve, reject) => {
+                sftp.fastPut(localPath, remotePath, { ...transferOptions, step: () => onProgress() }, (err) => {
+                    if (err) {
+                        reject(this.makeSftpError("Fast upload failed", err));
+                        return;
+                    }
+                    resolve();
+                });
+            }), this.transferStallTimeout(timeout), `fast upload ${localPath} -> ${remotePath}`, debug, endSftp);
+        }
+        finally {
+            endSftp();
+        }
     }
     /**
      * Download a remote file using ssh2's parallel SFTP fastGet implementation.
      */
     async sftpFastGet(client, remotePath, localPath, options, timeout, debug) {
-        const sftp = await this.openSftp(client, "fastGet", timeout, debug);
+        // Validate transfer options BEFORE opening the channel so invalid options
+        // can never leak an SFTP channel.
         const transferOptions = this.createSftpTransferOptions(options);
+        const sftp = await this.openSftp(client, "fastGet", timeout, debug);
         debug?.(`[mcp] fastGet ${remotePath} -> ${localPath}, concurrency=${transferOptions.concurrency ?? "ssh2-default"}, chunkSize=${transferOptions.chunkSize ?? "ssh2-default"}`);
-        return new Promise((resolve, reject) => {
-            sftp.fastGet(remotePath, localPath, transferOptions, (err) => {
+        const endSftp = () => {
+            try {
                 sftp.end();
-                if (err) {
-                    reject(this.makeSftpError("Fast download failed", err));
-                    return;
-                }
-                resolve();
-            });
-        });
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        };
+        try {
+            await this.runWithInactivityTimeout((onProgress) => new Promise((resolve, reject) => {
+                sftp.fastGet(remotePath, localPath, { ...transferOptions, step: () => onProgress() }, (err) => {
+                    if (err) {
+                        reject(this.makeSftpError("Fast download failed", err));
+                        return;
+                    }
+                    resolve();
+                });
+            }), this.transferStallTimeout(timeout), `fast download ${remotePath} -> ${localPath}`, debug, endSftp);
+        }
+        finally {
+            endSftp();
+        }
     }
     /**
      * Download file
@@ -2114,27 +2347,17 @@ export class SSHConnectionManager {
                 return this.appendDebugOutput("File downloaded successfully via fast SFTP", debugCollector);
             }
             const sftp = await this.openSftp(connection.client, "download", options?.timeout, debug);
-            await new Promise((resolve, reject) => {
-                let settled = false;
-                const readStream = sftp.createReadStream(validatedRemotePath);
-                const writeStream = fs.createWriteStream(validatedLocalPath);
-                const settle = (err) => {
-                    if (settled)
-                        return;
-                    settled = true;
-                    if (err) {
-                        this.unpipeStream(readStream, writeStream);
-                        this.destroyStream(readStream);
-                        this.destroyStream(writeStream);
-                    }
+            try {
+                await this.pipeWithInactivityTimeout(sftp.createReadStream(validatedRemotePath), fs.createWriteStream(validatedLocalPath), this.transferStallTimeout(options?.timeout), `download ${validatedRemotePath} -> ${validatedLocalPath}`, debug, (err) => this.makeSftpError("File download failed", err), (err) => new ToolError("LOCAL_FILE_WRITE_FAILED", `Failed to save file: ${err.message}`, false));
+            }
+            finally {
+                try {
                     sftp.end();
-                    err ? reject(err) : resolve();
-                };
-                writeStream.on("finish", () => settle());
-                writeStream.on("error", (err) => settle(new ToolError("LOCAL_FILE_WRITE_FAILED", `Failed to save file: ${err.message}`, false)));
-                readStream.on("error", (err) => settle(this.makeSftpError("File download failed", err)));
-                readStream.pipe(writeStream);
-            });
+                }
+                catch {
+                    // Ignore late SFTP cleanup errors.
+                }
+            }
             return this.appendDebugOutput("File downloaded successfully", debugCollector);
         }
         catch (error) {
@@ -2240,6 +2463,7 @@ export class SSHConnectionManager {
         const validatedDestPath = this.validateRemotePath(destRemotePath, destName);
         const skipIfIdentical = options?.skipIfIdentical !== false; // default true
         const reuseConnection = options?.reuseConnection !== false;
+        const selfRelay = sourceName === destName;
         const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
         debug?.(`[mcp] sftp relay ${sourceName} -> ${destName}, reuseConnection=${reuseConnection}`);
         let srcConnection = null;
@@ -2253,12 +2477,16 @@ export class SSHConnectionManager {
                 debug,
                 purpose: "sftp",
             });
-            dstConnection = await this.acquireSshClient(destName, {
-                reuseConnection,
-                timeout: options?.timeout,
-                debug,
-                purpose: "sftp",
-            });
+            // Same host on both ends: reuse the one SSH client (two SFTP channels are
+            // still opened below) so we never open or close a second connection.
+            dstConnection = selfRelay
+                ? srcConnection
+                : await this.acquireSshClient(destName, {
+                    reuseConnection,
+                    timeout: options?.timeout,
+                    debug,
+                    purpose: "sftp",
+                });
             const srcClient = srcConnection.client;
             const dstClient = dstConnection.client;
             srcSftp = await this.openSftp(srcClient, "source", options?.timeout, debug);
@@ -2286,30 +2514,11 @@ export class SSHConnectionManager {
                     }
                 }
             }
-            const readStream = srcSftp.createReadStream(validatedSourcePath);
-            const writeStream = dstSftp.createWriteStream(validatedDestPath);
             // Bind the validated paths into the rest of the verification flow so
             // we never accidentally fall back to the un-validated originals.
             sourceRemotePath = validatedSourcePath;
             destRemotePath = validatedDestPath;
-            await new Promise((resolve, reject) => {
-                let settled = false;
-                const settle = (err) => {
-                    if (settled)
-                        return;
-                    settled = true;
-                    if (err) {
-                        this.unpipeStream(readStream, writeStream);
-                        this.destroyStream(readStream);
-                        this.destroyStream(writeStream);
-                    }
-                    err ? reject(err) : resolve();
-                };
-                writeStream.on("close", () => settle());
-                writeStream.on("error", (err) => settle(this.makeSftpError("Dest write error", err)));
-                readStream.on("error", (err) => settle(this.makeSftpError("Source read error", err)));
-                readStream.pipe(writeStream);
-            });
+            await this.pipeWithInactivityTimeout(srcSftp.createReadStream(validatedSourcePath), dstSftp.createWriteStream(validatedDestPath), this.transferStallTimeout(options?.timeout), `relay ${sourceName}:${validatedSourcePath} -> ${destName}:${validatedDestPath}`, debug, (err) => this.makeSftpError("Source read error", err), (err) => this.makeSftpError("Dest write error", err));
             // --- Verification ---
             const dstStat = await this.sftpStat(dstSftp, destRemotePath, "dest");
             const verification = [];
@@ -2338,7 +2547,8 @@ export class SSHConnectionManager {
         catch (error) {
             if (reuseConnection && this.isConnectionError(error)) {
                 this.closeClient(sourceName, true);
-                this.closeClient(destName, true);
+                if (!selfRelay)
+                    this.closeClient(destName, true);
             }
             throw this.appendDebugToError(error, debugCollector);
         }
@@ -2346,7 +2556,8 @@ export class SSHConnectionManager {
             srcSftp?.end();
             dstSftp?.end();
             srcConnection?.close();
-            dstConnection?.close();
+            if (!selfRelay)
+                dstConnection?.close();
         }
     }
     /**
@@ -2397,7 +2608,10 @@ export class SSHConnectionManager {
         const open = new Promise((resolve, reject) => {
             client.sftp((err, sftp) => {
                 if (err) {
-                    return reject(this.makeSftpError(`SFTP connection failed (${label})`, err));
+                    // A client that cannot open an SFTP channel is unusable, so treat the
+                    // failure as connection-shaped regardless of wording. This lets the
+                    // caller force-drop the stale cached client and self-heal on retry.
+                    return reject(new ToolError("SSH_CONNECTION_FAILED", `SFTP connection failed (${label}): ${err.message}`, true));
                 }
                 debug?.(`[mcp] sftp channel opened (${label})`);
                 resolve(sftp);
@@ -2537,21 +2751,37 @@ export class SSHConnectionManager {
      */
     async sftpMkdirRecursive(client, remotePath, timeout, debug) {
         const sftp = await this.openSftp(client, "mkdir", timeout, debug);
-        return new Promise((resolve) => {
+        const walk = new Promise((resolve, reject) => {
             const parts = remotePath.split("/").filter(Boolean);
             let current = "";
             const mkdirNext = (index) => {
                 if (index >= parts.length) {
-                    sftp.end();
                     return resolve();
                 }
                 current += "/" + parts[index];
-                sftp.mkdir(current, () => {
-                    // EEXIST is fine
+                sftp.mkdir(current, (err) => {
+                    // An existing directory (or other non-connection failure) is fine and
+                    // just means the path component already exists. A connection-shaped
+                    // error means the channel died mid-walk -- surface it instead of
+                    // silently marching on (and eventually hanging the per-file uploads).
+                    if (err && this.isConnectionShapedMessage(err.message)) {
+                        return reject(this.makeSftpError("Remote mkdir failed", err));
+                    }
                     mkdirNext(index + 1);
                 });
             };
             mkdirNext(0);
         });
+        try {
+            await this.withConnectionTimeout(walk, this.normalizeConnectTimeout(timeout), `SFTP mkdir ${remotePath}`, debug);
+        }
+        finally {
+            try {
+                sftp.end();
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        }
     }
 }

package/build/tools/execute-command.js

@@ -19,6 +19,7 @@ export function registerExecuteCommandTool(server) {
             .describe("Target server name from list-servers. Required when multiple servers are enabled; optional when only one server is enabled."),
         timeout: z
             .number()
+            .positive()
             .optional()
             .describe("Timeout in milliseconds applied separately to SSH connection setup, exec-channel opening, and remote command execution for each attempt. Defaults to 300000 when stream=true and 30000 when stream=false. Increase this for long-running commands; reduce it for fast probes."),
         stream: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaarc/handfree-ssh-mcp",
-  "version": "1.0.7",
+  "version": "1.0.10",
   "description": "Handfree SSH MCP Server - A hands-free SSH automation tool via MCP protocol",
   "main": "build/index.js",
   "type": "module",
@@ -19,7 +19,7 @@
     "access": "public"
   },
   "scripts": {
-    "test": "npm run build && node --test build/tests/config.test.js build/tests/command-validation.test.js build/tests/tool-error.test.js build/tests/tools.test.js build/tests/output-collector.test.js build/tests/output-log-writer.test.js build/tests/recent-fixes.test.js",
+    "test": "npm run build && node --test build/tests/config.test.js build/tests/command-validation.test.js build/tests/tool-error.test.js build/tests/tools.test.js build/tests/output-collector.test.js build/tests/output-log-writer.test.js build/tests/recent-fixes.test.js build/tests/sftp-stall-timeout.test.js",
     "test:config": "npm run build && node --test build/tests/config.test.js",
     "test:cmd": "npm run build && node --test build/tests/command-validation.test.js",
     "test:tools": "npm run build && node --test build/tests/tools.test.js",