ssh-mcp 1.5.0 → 2.0.0

package/build/ssh/connection.js

@@ -0,0 +1,375 @@
+import { Client } from 'ssh2';
+import { FROZEN_ALGORITHMS } from './algorithms.js';
+import { verifyHostKey, fingerprintPublicKey } from './host-key.js';
+import { SessionManager } from './session-manager.js';
+import { tracer } from '../observability/tracer.js';
+import { redactText } from '../guard/redactor.js';
+import { shellSingleQuote } from '../guard/sanitizer.js';
+import { openWithRetry } from './channel-retry.js';
+export class SSHConnection {
+    profile;
+    client = null;
+    credentials;
+    sessions;
+    activeChannels = 0;
+    connecting = null;
+    connected = false;
+    connectedAt = null;
+    lastActivity = new Date();
+    knownHostsStore;
+    hostKeyMode;
+    bastionSock;
+    constructor(profile, credentials, knownHostsStore, hostKeyMode = 'tofu', bastionSock) {
+        this.profile = profile;
+        this.credentials = credentials;
+        this.knownHostsStore = knownHostsStore;
+        this.hostKeyMode = hostKeyMode;
+        this.bastionSock = bastionSock ?? null;
+        this.sessions = new SessionManager({
+            // Live read: the profile object can be replaced after construction.
+            profile: () => this.profile,
+            openShell: () => new Promise((resolve, reject) => {
+                this.getClient().shell({ term: 'xterm-256color', cols: 200, rows: 50 }, (err, stream) => (err ? reject(err) : resolve(stream)));
+            }),
+            openExec: (command) => new Promise((resolve, reject) => {
+                this.getClient().exec(this.applyWorkdir(command), (err, stream) => (err ? reject(err) : resolve(stream)));
+            }),
+            onChannelOpened: () => { this.activeChannels++; },
+            onChannelClosed: () => { this.activeChannels--; },
+        });
+    }
+    async ensureConnected() {
+        if (this.isConnected())
+            return;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.connect();
+        return this.connecting;
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            // Every handler below acts on `client`, not `this.client`, and only
+            // mutates shared state while it is still the current client. A late event
+            // from a superseded attempt must not tear down the connection that
+            // replaced it.
+            const client = new Client();
+            this.client = client;
+            const isCurrent = () => this.client === client;
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeoutId);
+                if (isCurrent())
+                    this.connecting = null;
+                fn();
+            };
+            const timeoutId = setTimeout(() => {
+                settle(() => {
+                    try {
+                        client.end();
+                    }
+                    catch { /* already gone */ }
+                    if (isCurrent())
+                        this.client = null;
+                    reject(new Error('SSH connection timeout'));
+                });
+            }, 20000);
+            client.on('ready', () => {
+                settle(() => {
+                    this.connected = true;
+                    this.connectedAt = new Date();
+                    this.lastActivity = new Date();
+                    resolve();
+                });
+            });
+            client.on('error', (err) => {
+                settle(() => {
+                    if (isCurrent())
+                        this.client = null;
+                    reject(new Error(`SSH connection error: ${err.message}`));
+                });
+            });
+            // 'end'/'close' also fire long after a successful handshake, when the
+            // connection drops — that path must clear connection state but leave the
+            // already-resolved promise alone.
+            const onDisconnect = (reason) => () => {
+                if (!isCurrent())
+                    return;
+                this.connected = false;
+                this.sessions.markAllDisconnected();
+                this.client = null;
+                this.connectedAt = null;
+                // Without clearing the timer here, a handshake that fails via a clean
+                // TCP close left a 20s bomb armed: it would later end a *newer* client
+                // mid-handshake and null its `connecting`, leaving that attempt hung.
+                settle(() => reject(new Error(`SSH connection ${reason} during handshake`)));
+            };
+            client.on('end', onDisconnect('ended'));
+            client.on('close', onDisconnect('closed'));
+            const connectConfig = {
+                host: this.profile.host,
+                port: this.profile.port,
+                username: this.profile.user,
+                algorithms: FROZEN_ALGORITHMS,
+                hostVerifier: (key) => {
+                    const fp = fingerprintPublicKey(key);
+                    if (this.profile.trustedHostKey && fp !== this.profile.trustedHostKey) {
+                        return false;
+                    }
+                    return verifyHostKey(this.profile.host, this.profile.port, fp, this.knownHostsStore, this.hostKeyMode);
+                },
+                readyTimeout: 20000,
+                keepaliveInterval: 15000,
+                keepaliveCountMax: 3,
+            };
+            if (this.credentials.agentSocket) {
+                connectConfig.agent = this.credentials.agentSocket;
+            }
+            if (this.credentials.privateKey) {
+                connectConfig.privateKey = this.credentials.certificate
+                    ? this.credentials.privateKey + '\n' + this.credentials.certificate
+                    : this.credentials.privateKey;
+                if (this.credentials.passphrase) {
+                    connectConfig.passphrase = this.credentials.passphrase;
+                }
+            }
+            if (this.credentials.password) {
+                connectConfig.password = this.credentials.password;
+            }
+            if (this.bastionSock) {
+                connectConfig.sock = this.bastionSock;
+            }
+            client.connect(connectConfig);
+        });
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    getClient() {
+        if (!this.client)
+            throw new Error('SSH connection not established');
+        return this.client;
+    }
+    getSudoPassword() {
+        return this.credentials.sudoPassword;
+    }
+    /**
+     * Prefix a command with the profile's working directory, if configured.
+     * Applied here rather than at the tool layer so the string the policy engine
+     * classified is never the string that carries the `&&`.
+     */
+    applyWorkdir(command) {
+        if (!this.profile.workdir)
+            return command;
+        return `cd ${shellSingleQuote(this.profile.workdir)} && ${command}`;
+    }
+    async exec(rawCommand, opts = {}) {
+        await this.ensureConnected();
+        const command = this.applyWorkdir(rawCommand);
+        const timeoutMs = opts.timeoutMs ?? this.profile.timeout;
+        const startTime = Date.now();
+        const span = tracer.startSpan('ssh.exec');
+        span.setAttribute('ssh.host', this.profile.host);
+        span.setAttribute('ssh.port', this.profile.port);
+        span.setAttribute('ssh.command', redactText(command));
+        return new Promise((resolve, reject) => {
+            let activeStream = null;
+            let resolved = false;
+            const timeoutId = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    if (activeStream) {
+                        try {
+                            activeStream.signal('INT');
+                        }
+                        catch { /* */ }
+                        setTimeout(() => {
+                            try {
+                                activeStream?.signal('TERM');
+                            }
+                            catch { /* */ }
+                            setTimeout(() => { try {
+                                activeStream?.close();
+                            }
+                            catch { /* */ } }, 1000);
+                        }, 1000);
+                    }
+                    span.setAttribute('ssh.timedOut', true);
+                    span.end();
+                    reject(new Error(`Command timed out after ${timeoutMs}ms`));
+                }
+            }, timeoutMs);
+            const execOpts = {};
+            if (opts.tty || this.profile.tty) {
+                execOpts.pty = { term: 'xterm-256color', cols: 200, rows: 50 };
+            }
+            // Retried: some servers (Dropbear especially) intermittently refuse a
+            // channel right after a previous one was released. Only the open is
+            // retried — once a stream exists, nothing here re-runs the command.
+            const openExecChannel = async () => {
+                // Re-established per attempt: the refusal can be a dropped connection
+                // rather than a refused channel.
+                await this.ensureConnected();
+                const activeClient = this.getClient();
+                return new Promise((res, rej) => {
+                    activeClient.exec(command, execOpts, (err, stream) => (err ? rej(err) : res(stream)));
+                });
+            };
+            const onExecChannel = (err, stream) => {
+                if (err) {
+                    if (!resolved) {
+                        resolved = true;
+                        clearTimeout(timeoutId);
+                        span.end();
+                        reject(new Error(`SSH exec error: ${err.message}`));
+                    }
+                    return;
+                }
+                activeStream = stream;
+                this.activeChannels++;
+                let stdout = '';
+                let stderr = '';
+                const maxOutput = this.profile.maxOutputBytes;
+                let lastProgressSent = 0;
+                const PROGRESS_INTERVAL = 500;
+                if (opts.stdin) {
+                    try {
+                        stream.write(opts.stdin);
+                    }
+                    catch { /* */ }
+                }
+                try {
+                    stream.end();
+                }
+                catch { /* */ }
+                if (opts.abortSignal) {
+                    if (opts.abortSignal.aborted) {
+                        resolved = true;
+                        clearTimeout(timeoutId);
+                        this.activeChannels--;
+                        // client.exec() has already dispatched the command, so rejecting
+                        // without signalling left it running to completion on the host and
+                        // held a channel until it finished.
+                        try {
+                            stream.signal('INT');
+                        }
+                        catch { /* */ }
+                        try {
+                            stream.close();
+                        }
+                        catch { /* */ }
+                        span.end();
+                        reject(new Error('Command aborted before execution'));
+                        return;
+                    }
+                    const onAbort = () => {
+                        if (!resolved) {
+                            resolved = true;
+                            clearTimeout(timeoutId);
+                            try {
+                                stream.signal('INT');
+                            }
+                            catch { /* */ }
+                            setTimeout(() => {
+                                try {
+                                    stream.signal('TERM');
+                                }
+                                catch { /* */ }
+                                setTimeout(() => { try {
+                                    stream.close();
+                                }
+                                catch { /* */ } }, 1000);
+                            }, 1000);
+                            span.end();
+                            reject(new Error('Command aborted'));
+                        }
+                    };
+                    opts.abortSignal.addEventListener('abort', onAbort, { once: true });
+                    stream.on('close', () => { opts.abortSignal.removeEventListener('abort', onAbort); });
+                }
+                stream.on('data', (data) => {
+                    if (stdout.length < maxOutput)
+                        stdout += data.toString();
+                    if (opts.onProgress && Date.now() - lastProgressSent >= PROGRESS_INTERVAL) {
+                        lastProgressSent = Date.now();
+                        let tail = stdout;
+                        for (let i = 0; i < 3; i++) {
+                            const idx = tail.lastIndexOf('\n', tail.length - 2);
+                            if (idx < 0)
+                                break;
+                            tail = tail.substring(idx + 1);
+                        }
+                        opts.onProgress(stdout.length, redactText(tail.trim(), { entropyScan: true }));
+                    }
+                });
+                stream.stderr.on('data', (data) => {
+                    if (stderr.length < maxOutput)
+                        stderr += data.toString();
+                });
+                stream.on('close', (code, signal) => {
+                    this.activeChannels--;
+                    if (!resolved) {
+                        resolved = true;
+                        clearTimeout(timeoutId);
+                        this.lastActivity = new Date();
+                        resolve({
+                            stdout,
+                            stderr,
+                            exitCode: code,
+                            durationMs: Date.now() - startTime,
+                            profile: this.profile.name,
+                            signal: signal || undefined,
+                        });
+                        span.setAttribute('ssh.exitCode', code);
+                        if (signal)
+                            span.setAttribute('ssh.signal', signal);
+                        span.end();
+                    }
+                });
+            };
+            openWithRetry(openExecChannel).then((stream) => onExecChannel(undefined, stream), (err) => onExecChannel(err, undefined));
+        });
+    }
+    // ─── Sessions (delegated to SessionManager) ──────────────────────────
+    async openSession(opts) {
+        await this.ensureConnected();
+        return this.sessions.open(opts);
+    }
+    getSession(name) {
+        return this.sessions.get(name);
+    }
+    listSessions() {
+        return this.sessions.list();
+    }
+    async closeSession(name) {
+        return this.sessions.close(name);
+    }
+    reapExpiredSessions() {
+        this.sessions.reapExpired();
+    }
+    async close() {
+        await this.sessions.closeAll();
+        if (this.client) {
+            this.client.end();
+            this.client = null;
+        }
+        this.connecting = null;
+        this.connected = false;
+        this.connectedAt = null;
+    }
+    toInfo() {
+        return {
+            profile: this.profile.name,
+            host: this.profile.host,
+            port: this.profile.port,
+            user: this.profile.user,
+            status: this.isConnected() ? 'connected' : 'closed',
+            sessionCount: this.sessions.size,
+            activeChannels: this.activeChannels,
+            connectedAt: this.connectedAt || undefined,
+            lastActivity: this.lastActivity,
+        };
+    }
+}

package/build/ssh/host-key.js

@@ -0,0 +1,23 @@
+import { createHash } from 'crypto';
+export function fingerprintPublicKey(key) {
+    const hash = createHash('sha256').update(key).digest('base64');
+    return `SHA256:${hash.replace(/=+$/, '')}`;
+}
+export function verifyHostKey(host, port, fingerprint, knownHosts, mode) {
+    if (mode === 'insecure')
+        return true;
+    const key = `${host}:${port}`;
+    const stored = knownHosts.get(key);
+    if (stored) {
+        if (stored !== fingerprint) {
+            throw new Error(`HOST_KEY_MISMATCH: ${host}:${port} key changed (expected ${stored.slice(0, 20)}..., got ${fingerprint.slice(0, 20)}...)`);
+        }
+        return true;
+    }
+    if (mode === 'strict') {
+        throw new Error(`HOST_KEY_UNKNOWN: No known key for ${host}:${port} and --hostKeyMode=strict is set. ` +
+            'Pin the key with trustedHostKey in the profile, or use --hostKeyMode=tofu to trust on first use.');
+    }
+    knownHosts.set(key, fingerprint);
+    return true;
+}

package/build/ssh/session-manager.js

@@ -0,0 +1,164 @@
+import { InteractiveSession, BackgroundSession, stripAnsi } from './session.js';
+import { shellSingleQuote } from '../guard/sanitizer.js';
+import { openWithRetry } from './channel-retry.js';
+import { randomUUID } from 'crypto';
+/** Owns the named sessions of a single SSH connection. */
+export class SessionManager {
+    deps;
+    sessions = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get size() {
+        return this.sessions.size;
+    }
+    async open(opts) {
+        const profile = this.deps.profile();
+        if (this.sessions.size >= profile.sessionMaxPerConnection) {
+            throw new Error(`Session limit reached for ${profile.name} (max: ${profile.sessionMaxPerConnection})`);
+        }
+        if (this.sessions.has(opts.name)) {
+            throw new Error(`Session "${opts.name}" already exists on ${profile.name}`);
+        }
+        const ttlMs = opts.ttlMs ?? profile.sessionIdleTimeoutMs;
+        const id = randomUUID();
+        if (opts.type === 'interactive') {
+            return this.openInteractive(id, opts.name, ttlMs);
+        }
+        if (!opts.command)
+            throw new Error('Background sessions require a command');
+        return this.openBackground(id, opts.name, opts.command, ttlMs);
+    }
+    /**
+     * Register a session and tie its lifetime to its channel.
+     *
+     * The eviction is guarded: close() only ends the stream, so a channel's
+     * 'close' can arrive long after the same name was reused, and an unguarded
+     * delete would evict the *new* session — leaving its channel open but
+     * unreachable through get/list/close/reap.
+     */
+    register(name, session, stream) {
+        this.sessions.set(name, session);
+        this.deps.onChannelOpened();
+        stream.on('close', () => {
+            this.deps.onChannelClosed();
+            if (this.sessions.get(name) === session)
+                this.sessions.delete(name);
+        });
+    }
+    async openInteractive(id, name, ttlMs) {
+        let stream;
+        try {
+            stream = await openWithRetry(() => this.deps.openShell());
+        }
+        catch (err) {
+            throw new Error(`Failed to open interactive session: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const session = new InteractiveSession(id, name, this.deps.profile().name, stream, ttlMs);
+        this.register(name, session, stream);
+        try {
+            await this.primeShell(stream, session);
+        }
+        catch (err) {
+            await session.close().catch(() => { });
+            this.sessions.delete(name);
+            throw err;
+        }
+        return session;
+    }
+    /**
+     * Quiet the shell down and confirm it can run the session protocol — in one
+     * round trip.
+     *
+     * Priming suppresses the prompt, history and bracketed paste, all of which
+     * would otherwise land in command output. The readiness marker at the end
+     * doubles as the handshake: it comes back only from a shell that can run
+     * `printf`, which is the same capability every later command depends on.
+     *
+     * This replaced two weaker mechanisms. Waiting for a prompt with /[#$>]\s*$/
+     * was a guess that failed on busybox ash (its prompt is followed by a
+     * cursor-position query) and would silently "succeed" on cmd.exe, which
+     * presents a `>` prompt and then cannot run a single command — every call
+     * afterwards sat until the 60s command timeout with nothing useful to say.
+     */
+    primeShell(stream, session) {
+        const { workdir, name: profileName } = this.deps.profile();
+        // Split literals: the echoed input never contains the assembled marker, so
+        // only the shell's own output can satisfy the match.
+        const parts = ['SSHMCP_RDY', `_${randomUUID()}`];
+        const marker = parts.join('');
+        return new Promise((resolve, reject) => {
+            let buffer = '';
+            let settled = false;
+            const settle = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                stream.removeListener('data', onData);
+                err ? reject(err) : resolve();
+            };
+            const onData = (data) => {
+                buffer += data.toString();
+                if (stripAnsi(buffer).includes(marker))
+                    settle();
+            };
+            const timer = setTimeout(() => settle(new Error(`Interactive sessions are not supported on ${profileName}: its shell did not complete the ` +
+                'session handshake. The protocol requires a POSIX shell (sh/bash/ash/zsh); cmd.exe and ' +
+                'PowerShell do not provide it. Use read-command / run-command instead, which work on any shell.')), 5000);
+            stream.on('data', onData);
+            stream.write('PS1=""\n');
+            stream.write('set +o history 2>/dev/null\n');
+            stream.write('bind "set enable-bracketed-paste off" 2>/dev/null\n');
+            if (workdir) {
+                stream.write(`cd ${shellSingleQuote(workdir)}\n`);
+                session.setCwd(workdir);
+            }
+            stream.write(`printf '%s%s\\n' '${parts[0]}' '${parts[1]}'\n`);
+        });
+    }
+    async openBackground(id, name, command, ttlMs) {
+        let stream;
+        try {
+            stream = await openWithRetry(() => this.deps.openExec(command));
+        }
+        catch (err) {
+            throw new Error(`Failed to open background session: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const profile = this.deps.profile();
+        const session = new BackgroundSession(id, name, profile.name, stream, ttlMs, profile.sessionBackgroundMaxMs);
+        this.register(name, session, stream);
+        return session;
+    }
+    get(name) {
+        return this.sessions.get(name);
+    }
+    list() {
+        return Array.from(this.sessions.values());
+    }
+    async close(name) {
+        const session = this.sessions.get(name);
+        if (!session)
+            throw new Error(`Session "${name}" not found on ${this.deps.profile().name}`);
+        await session.close();
+        this.sessions.delete(name);
+    }
+    async closeAll() {
+        for (const name of [...this.sessions.keys()]) {
+            await this.close(name).catch(() => { });
+        }
+    }
+    reapExpired() {
+        for (const [name, session] of this.sessions) {
+            if (session.isExpired()) {
+                session.close().catch(() => { });
+                this.sessions.delete(name);
+            }
+        }
+    }
+    markAllDisconnected() {
+        for (const session of this.sessions.values()) {
+            session.markDisconnected();
+        }
+    }
+}