ssh-mcp 1.5.0 → 2.0.1

package/build/ssh/session.js

@@ -0,0 +1,350 @@
+import { randomBytes } from 'crypto';
+import { tracer } from '../observability/tracer.js';
+const ANSI_REGEX = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b\][^\x07]*\x07|\r/g;
+export function stripAnsi(text) {
+    return text.replace(ANSI_REGEX, '');
+}
+/**
+ * Trim leading and trailing newlines by index rather than with /^\n+/ and
+ * /\n+$/.
+ *
+ * The trailing pattern is unanchored at the start, so on output that is mostly
+ * newlines but does not end in one the engine retries `\n+` from every offset:
+ * quadratic in the length of the output. That output is whatever the remote
+ * command printed and the session buffer holds up to 2 MB of it, which measured
+ * at roughly 25 minutes of blocked event loop — and the loop is shared by every
+ * session and connection this server has open.
+ */
+/**
+ * A per-command marker separating the command's own output from the trailer
+ * carrying `$?` and `$PWD`.
+ *
+ * Guessing one is enough to forge an exit code or a working directory — a
+ * failed command reported as successful, in a server whose whole claim is an
+ * auditable record of what ran. Every marker is written to the remote host in
+ * the clear, so anything watching that session collects a stream of them, and
+ * Math.random() is reconstructible from such a stream.
+ *
+ * base64url keeps the value safe both inside the single-quoted printf that
+ * emits it and inside the RegExp built from it: no quotes, no metacharacters.
+ */
+export function generateSessionMarker() {
+    return randomBytes(12).toString('base64url');
+}
+export function trimNewlines(text) {
+    let start = 0;
+    let end = text.length;
+    while (start < end && text.charCodeAt(start) === 10)
+        start++;
+    while (end > start && text.charCodeAt(end - 1) === 10)
+        end--;
+    return start === 0 && end === text.length ? text : text.slice(start, end);
+}
+export class Session {
+    id;
+    name;
+    profile;
+    type;
+    createdAt;
+    lastActivity;
+    ttlMs;
+    /** Absolute lifetime cap, measured from createdAt. Undefined = no cap. */
+    maxLifetimeMs;
+    _status = 'active';
+    constructor(id, name, profile, type, ttlMs, maxLifetimeMs) {
+        this.id = id;
+        this.name = name;
+        this.profile = profile;
+        this.type = type;
+        this.createdAt = new Date();
+        this.lastActivity = new Date();
+        this.ttlMs = ttlMs;
+        this.maxLifetimeMs = maxLifetimeMs;
+    }
+    get status() {
+        return this._status;
+    }
+    isExpired() {
+        // The idle TTL alone never fires for a chatty background process, because
+        // every data chunk touches lastActivity. The absolute cap is what actually
+        // bounds a `tail -f`-style session.
+        if (this.maxLifetimeMs !== undefined && Date.now() - this.createdAt.getTime() > this.maxLifetimeMs) {
+            return true;
+        }
+        return Date.now() - this.lastActivity.getTime() > this.ttlMs;
+    }
+    touch() {
+        this.lastActivity = new Date();
+    }
+    markDisconnected() {
+        if (this._status === 'active') {
+            this._status = 'disconnected';
+        }
+    }
+    toInfo() {
+        return {
+            id: this.id,
+            name: this.name,
+            profile: this.profile,
+            type: this.type,
+            status: this._status,
+            createdAt: this.createdAt,
+            lastActivity: this.lastActivity,
+            ttlMs: this.ttlMs,
+        };
+    }
+}
+export class InteractiveSession extends Session {
+    stream;
+    cwd = '~';
+    static MAX_OUTPUT = 1_048_576;
+    constructor(id, name, profile, stream, ttlMs) {
+        super(id, name, profile, 'interactive', ttlMs);
+        this.stream = stream;
+        stream.on('close', () => {
+            this._status = 'closed';
+        });
+    }
+    async run(command, timeoutMs = 60_000, abortSignal) {
+        if (this._status !== 'active') {
+            throw new Error(`Session ${this.name} is not active (status: ${this._status})`);
+        }
+        const span = tracer.startSpan('ssh.session.run');
+        span.setAttribute('session.id', this.id);
+        span.setAttribute('session.name', this.name);
+        const marker = this.generateMarker();
+        // Split literals: the shell assembles these at runtime, so the *echoed*
+        // command line never contains the assembled marker — only the command's
+        // actual output does. That is what makes the parse below deterministic
+        // instead of a guess about which echoed line to skip.
+        const beginParts = ['SSHMCP_BEG', `_${marker}`];
+        const endParts = ['SSHMCP_END', `_${marker}`];
+        const beginMarker = beginParts.join('');
+        const endMarker = endParts.join('');
+        const startTime = Date.now();
+        return new Promise((resolve, reject) => {
+            let buffer = '';
+            let resolved = false;
+            // Assigned below; declared here so every settle path can detach it.
+            let detachAbort = () => { };
+            const timeoutId = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    this.stream.removeListener('data', dataHandler);
+                    detachAbort();
+                    try {
+                        this.stream.write('\x03');
+                    }
+                    catch { /* */ }
+                    setTimeout(() => { try {
+                        this.stream.signal('TERM');
+                    }
+                    catch { /* */ } }, 500);
+                    span.end();
+                    reject(new Error(`Command timed out after ${timeoutMs}ms in session ${this.name}`));
+                }
+            }, timeoutMs);
+            // The trailer carries the exit code and the shell's real CWD, so neither
+            // has to be inferred (cwd used to be guessed from the command text, which
+            // was wrong for relative paths, `cd -`, symlinks and `cd` with no arg).
+            const endRegex = new RegExp(`${endMarker}__(\\d+)__([^\\r\\n]*)`);
+            const dataHandler = (data) => {
+                const prevLength = buffer.length;
+                buffer += data.toString();
+                if (buffer.length > InteractiveSession.MAX_OUTPUT * 2) {
+                    buffer = buffer.slice(-InteractiveSession.MAX_OUTPUT * 2);
+                }
+                // The marker can only appear at the tail, so search the newly-arrived
+                // bytes plus an overlap rather than rescanning the whole buffer on
+                // every chunk — that was O(total x buffer) for a chatty command. The
+                // cheap indexOf also gates the ANSI strip, which is the expensive part.
+                const searchFrom = Math.max(0, Math.min(prevLength, buffer.length) - endMarker.length - 32);
+                if (resolved || buffer.indexOf(endMarker, searchFrom) === -1)
+                    return;
+                const cleaned = stripAnsi(buffer);
+                const match = cleaned.match(endRegex);
+                if (match && !resolved) {
+                    resolved = true;
+                    clearTimeout(timeoutId);
+                    this.stream.removeListener('data', dataHandler);
+                    detachAbort();
+                    const exitCode = parseInt(match[1]);
+                    const reportedCwd = match[2].trim();
+                    // Output is exactly what lies between the two printed markers.
+                    // Anything before the begin marker — the echoed command, leftover
+                    // shell init, a prompt that PS1="" had not suppressed yet — is
+                    // discarded by construction rather than by counting lines.
+                    const beginIdx = cleaned.indexOf(beginMarker);
+                    const afterBegin = beginIdx >= 0
+                        ? cleaned.slice(cleaned.indexOf('\n', beginIdx) + 1)
+                        : cleaned;
+                    const endIdx = afterBegin.indexOf(endMarker);
+                    const between = endIdx >= 0 ? afterBegin.slice(0, endIdx) : afterBegin;
+                    const output = trimNewlines(between);
+                    if (reportedCwd)
+                        this.cwd = reportedCwd;
+                    this.touch();
+                    resolve({
+                        stdout: output,
+                        stderr: '',
+                        exitCode,
+                        durationMs: Date.now() - startTime,
+                        cwd: this.cwd,
+                        sessionId: this.id,
+                        profile: this.profile,
+                    });
+                    span.setAttribute('ssh.exitCode', exitCode);
+                    span.end();
+                }
+            };
+            if (abortSignal) {
+                if (abortSignal.aborted) {
+                    resolved = true;
+                    clearTimeout(timeoutId);
+                    span.end();
+                    reject(new Error('Command aborted before execution'));
+                    return;
+                }
+                const onAbort = () => {
+                    if (!resolved) {
+                        resolved = true;
+                        clearTimeout(timeoutId);
+                        this.stream.removeListener('data', dataHandler);
+                        try {
+                            this.stream.write('\x03');
+                        }
+                        catch { /* */ }
+                        setTimeout(() => { try {
+                            this.stream.signal('TERM');
+                        }
+                        catch { /* */ } }, 1000);
+                        span.end();
+                        reject(new Error('Command aborted'));
+                    }
+                };
+                abortSignal.addEventListener('abort', onAbort, { once: true });
+                // Without this the listener outlived the run, and its closure retained
+                // the run's buffer (up to 2MB) for the lifetime of the signal.
+                detachAbort = () => abortSignal.removeEventListener('abort', onAbort);
+            }
+            this.stream.on('data', dataHandler);
+            // One line, so the PTY produces exactly one echo and it necessarily
+            // precedes the begin marker's output. Written as three lines, the shell
+            // echoed each just before running it, interleaving the echoes of the
+            // command and the trailer *after* the begin marker — right in the middle
+            // of what we treat as output.
+            //
+            // The markers are printed from split literals, so the echo of this line
+            // never contains an assembled marker; only the shell's own output does.
+            this.stream.write(`printf '%s%s\\n' '${beginParts[0]}' '${beginParts[1]}'; ` +
+                `${command}; ` +
+                `printf '%s%s__%s__%s\\n' '${endParts[0]}' '${endParts[1]}' "$?" "$PWD"\n`);
+        });
+    }
+    generateMarker() {
+        return generateSessionMarker();
+    }
+    async close() {
+        try {
+            this.stream.end();
+        }
+        catch { /* ignore */ }
+        this._status = 'closed';
+    }
+    get currentCwd() {
+        return this.cwd;
+    }
+    /** Record the shell's starting directory when the profile sets a workdir. */
+    setCwd(dir) {
+        this.cwd = dir;
+    }
+}
+export class BackgroundSession extends Session {
+    stream;
+    ringBuffer = [];
+    ringBytes = 0;
+    ringMax = 10_000;
+    /** Tail of the last chunk when it did not end on a line boundary. */
+    partialLine = '';
+    exitCode = null;
+    static RING_CHAR_LIMIT = 100_000;
+    constructor(id, name, profile, stream, ttlMs, maxLifetimeMs) {
+        super(id, name, profile, 'background', ttlMs, maxLifetimeMs);
+        this.stream = stream;
+        stream.on('data', (data) => {
+            // Splitting each chunk independently corrupted the output twice over: a
+            // line spanning two chunks became two entries (readOutput joins with
+            // '\n', inventing a break that was never in the stream), and a chunk
+            // ending on '\n' produced a trailing '' entry, so a blank line was
+            // inserted between every chunk. Carry the incomplete tail instead.
+            const text = this.partialLine + data.toString();
+            const lines = text.split('\n');
+            this.partialLine = lines.pop() ?? '';
+            for (const line of lines) {
+                this.ringBuffer.push(line);
+                this.ringBytes += line.length + 1;
+            }
+            this.trimRingBuffer();
+            this.touch();
+        });
+        stream.on('close', (code) => {
+            // Flush a final line that never got its newline.
+            if (this.partialLine) {
+                this.ringBuffer.push(this.partialLine);
+                this.ringBytes += this.partialLine.length + 1;
+                this.partialLine = '';
+                this.trimRingBuffer();
+            }
+            this.exitCode = code;
+            this._status = this.isExpired() ? 'expired' : 'closed';
+        });
+    }
+    /**
+     * Evict from the head in one splice. Looping `shift()` moved every remaining
+     * element per evicted line, so a chatty process paid O(lines x buffer) on the
+     * shared event loop once the buffer was full.
+     */
+    trimRingBuffer() {
+        let dropCount = 0;
+        let freed = 0;
+        while (this.ringBytes - freed > BackgroundSession.RING_CHAR_LIMIT &&
+            dropCount < this.ringBuffer.length) {
+            freed += this.ringBuffer[dropCount].length + 1;
+            dropCount++;
+        }
+        const remaining = this.ringBuffer.length - dropCount;
+        if (remaining > this.ringMax) {
+            const extra = remaining - this.ringMax;
+            for (let i = 0; i < extra; i++) {
+                freed += this.ringBuffer[dropCount + i].length + 1;
+            }
+            dropCount += extra;
+        }
+        if (dropCount > 0) {
+            this.ringBuffer.splice(0, dropCount);
+            this.ringBytes -= freed;
+        }
+    }
+    readOutput(lines = 50) {
+        // Include the in-flight partial line so output that has not yet ended with
+        // a newline is still visible to a caller polling the session.
+        const all = this.partialLine ? [...this.ringBuffer, this.partialLine] : this.ringBuffer;
+        return all.slice(-lines).join('\n');
+    }
+    isRunning() {
+        return this._status === 'active';
+    }
+    getExitCode() {
+        return this.exitCode;
+    }
+    async run(_command) {
+        throw new Error('Background sessions do not support run(). The command was started when the session was opened.');
+    }
+    async close() {
+        try {
+            this.stream.close();
+        }
+        catch { /* ignore */ }
+        this._status = 'closed';
+    }
+}

package/build/ssh/sftp.js

@@ -0,0 +1,130 @@
+import { openWithRetry } from './channel-retry.js';
+export class SftpClient {
+    conn;
+    constructor(conn) {
+        this.conn = conn;
+    }
+    async withSftp(fn) {
+        // ensureConnected lives inside the retry: Dropbear drops the whole
+        // connection under SFTP channel churn, so an attempt can fail because the
+        // link died rather than because the channel was refused. Re-establishing
+        // before each attempt covers both.
+        const sftp = await openWithRetry(async () => {
+            await this.conn.ensureConnected();
+            const client = this.conn.getClient();
+            return new Promise((resolve, reject) => {
+                client.sftp((err, handle) => {
+                    if (err) {
+                        reject(new Error(`SFTP error: ${err.message}`));
+                        return;
+                    }
+                    resolve(handle);
+                });
+            });
+        });
+        try {
+            return await fn(sftp);
+        }
+        finally {
+            // Every client.sftp() opens a new subsystem channel. Without end() they
+            // accumulate for the life of the connection until the server's MaxSessions
+            // limit (OpenSSH default: 10) is hit, after which no channel — SFTP, exec
+            // or shell — can be opened on this connection any more.
+            try {
+                sftp.end();
+            }
+            catch { /* already torn down */ }
+        }
+    }
+    async upload(opts) {
+        return this.withSftp(async (sftp) => {
+            return new Promise((resolve, reject) => {
+                const stream = sftp.createWriteStream(opts.remotePath, { mode: opts.mode || 0o644 });
+                stream.on('error', reject);
+                stream.on('close', resolve);
+                stream.end(Buffer.isBuffer(opts.content) ? opts.content : Buffer.from(opts.content));
+            });
+        });
+    }
+    /**
+     * Download a remote file, refusing anything over the cap.
+     *
+     * 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.
+     */
+    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));
+            });
+            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.`);
+            }
+            return new Promise((resolve, reject) => {
+                const chunks = [];
+                let received = 0;
+                const stream = sftp.createReadStream(opts.remotePath);
+                stream.on('data', (chunk) => {
+                    received += chunk.length;
+                    // stat can be stale or unavailable (growing file, no permission), so
+                    // enforce the cap on the stream too and stop reading immediately.
+                    if (received > maxBytes) {
+                        stream.destroy();
+                        reject(new Error(`Refusing to download ${opts.remotePath}: exceeded the ${maxBytes} byte limit while transferring.`));
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                stream.on('error', reject);
+                stream.on('close', () => resolve(Buffer.concat(chunks)));
+            });
+        });
+    }
+    async list(remotePath) {
+        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),
+                    })));
+                });
+            });
+        });
+    }
+    async stat(remotePath) {
+        return this.withSftp(async (sftp) => {
+            return new Promise((resolve, reject) => {
+                sftp.stat(remotePath, (err, stats) => {
+                    if (err) {
+                        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),
+                    });
+                });
+            });
+        });
+    }
+}

package/build/tools/command-tools.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { shellSingleQuote } from '../guard/sanitizer.js';
+import { TOOL_DESCRIPTIONS as D } from './descriptions.js';
+import { commandOutput, textResult } from './results.js';
+import { PolicyRefusedError } from './pipeline.js';
+/** Tools that run a command on the remote host. */
+export function registerCommandTools({ server, registry, policy }, pipeline) {
+    const { runAudited, execAndReport, defaultProfileName } = pipeline;
+    // ─── read-command ──────────────────────────────────────────────────────
+    server.tool('read-command', D["read-command"], {
+        command: z.string().describe('Read-only shell command (must be in the allowlist)'),
+        profile: z.string().optional().describe('Profile name'),
+    }, { readOnlyHint: true }, async ({ command, profile }, extra) => {
+        return runAudited(command, { toolName: 'read-command', failureClass: 'read-only', enforceClass: 'read-only', profile, extra }, execAndReport());
+    });
+    // ─── run-command ───────────────────────────────────────────────────────
+    server.tool('run-command', D["run-command"], {
+        command: z.string().describe('Shell command to execute'),
+        profile: z.string().optional().describe('Profile name'),
+        session: z.string().optional().describe('Run in an existing interactive session (stateful)'),
+        tty: z.boolean().optional().describe('Allocate a pseudo-terminal'),
+    }, { destructiveHint: true }, async ({ command, profile, session, tty }, extra) => {
+        return runAudited(command, { toolName: 'run-command', failureClass: 'safe', profile, session, extra }, async (rt) => {
+            // A session run keeps the caller's shell state; a plain exec does not.
+            let audited;
+            if (session) {
+                const sess = rt.conn.getSession(session);
+                if (!sess)
+                    throw new Error(`Session "${session}" not found`);
+                audited = await sess.run(rt.command, undefined, rt.abortSignal);
+            }
+            else {
+                audited = await rt.conn.exec(rt.command, {
+                    tty, onProgress: rt.onProgress, abortSignal: rt.abortSignal,
+                });
+            }
+            return { audited, output: commandOutput(audited) };
+        });
+    });
+    // ─── privileged-command ────────────────────────────────────────────────
+    server.tool('privileged-command', D["privileged-command"], {
+        command: z.string().describe('Command to execute with sudo'),
+        profile: z.string().optional().describe('Profile name'),
+    }, { destructiveHint: true }, async ({ command, profile }, extra) => {
+        const profileName = defaultProfileName(profile);
+        return runAudited(command, {
+            toolName: 'privileged-command',
+            failureClass: 'privileged',
+            profile,
+            extra,
+            // Evaluate the bare command too: the sudo wrapper would otherwise
+            // hide a forbidden command inside a quoted `sh -c` argument.
+            preCheck: (cleanCmd) => {
+                const rawEval = policy.evaluate(cleanCmd, registry.getProfile(profileName), 'privileged-command');
+                if (rawEval.decision === 'deny') {
+                    throw new PolicyRefusedError(`POLICY_DENIED: ${rawEval.reason || 'Command not allowed'}`, rawEval);
+                }
+            },
+            wrap: (cleanCmd) => `sudo -p "" -S sh -c ${shellSingleQuote(cleanCmd)}`,
+        }, (rt) => {
+            const sudoPassword = rt.conn.getSudoPassword();
+            return execAndReport({ stdin: sudoPassword ? sudoPassword + '\n' : undefined })(rt);
+        });
+    });
+    // ─── signal-process ────────────────────────────────────────────────────
+    server.tool('signal-process', D["signal-process"], {
+        pid: z.number().int().min(1).describe('Process ID to signal (positive integer)'),
+        signal: z.enum(['INT', 'TERM', 'KILL']).default('TERM').describe('Signal to send'),
+        profile: z.string().optional().describe('Profile name'),
+    }, { destructiveHint: true }, async ({ pid, signal, profile }, extra) => {
+        return runAudited(`kill -${signal} ${pid}`, { toolName: 'signal-process', failureClass: 'destructive', profile, extra, synthetic: true }, async (rt) => {
+            const { audited, output } = await execAndReport()(rt);
+            // `kill` is silent on success — confirm what was sent rather than
+            // returning an empty result.
+            const silentSuccess = !output.isError && !audited.stdout.trim() && !audited.stderr.trim();
+            return {
+                audited,
+                output: silentSuccess ? textResult(`Signal ${signal} sent to PID ${pid}`) : output,
+            };
+        });
+    });
+}

package/build/tools/descriptions.js

@@ -0,0 +1,21 @@
+import { createHash } from 'crypto';
+export const TOOL_DESCRIPTIONS = {
+    'list-connections': 'List all configured SSH profiles and their connection status. Use this to discover available hosts before running commands.',
+    'list-sessions': 'List active sessions for a given SSH profile.',
+    'open-session': 'Open a named session on a remote host. Use type="interactive" for stateful shell (CWD/env persists between commands) or type="background" for long-running processes.',
+    'close-session': 'Close a named session, releasing its resources.',
+    'read-session-output': 'Read recent output from a background session (e.g., tail -f logs).',
+    'read-command': 'Execute a READ-ONLY command from an allowlist (ls, cat, grep, find, stat, df, etc.). This tool does NOT modify the system. Prefer this tool for all read operations.',
+    'run-command': 'Execute an arbitrary shell command on the remote server. May modify the system. Destructive commands require user approval.',
+    'privileged-command': 'Execute a command with sudo elevation. ALWAYS requires user approval. The sudo password is piped via stdin (never visible in process list).',
+    'sftp-upload': 'Upload a file to the remote server via SFTP (secure file transfer, not shell-based).',
+    'sftp-download': 'Download a file from the remote server via SFTP.',
+    'signal-process': 'Send a signal (INT, TERM, KILL) to a remote process by PID.',
+};
+export function getToolHashes() {
+    const hashes = {};
+    for (const [name, desc] of Object.entries(TOOL_DESCRIPTIONS)) {
+        hashes[name] = createHash('sha256').update(desc).digest('hex').slice(0, 16);
+    }
+    return hashes;
+}

package/build/tools/file-tools.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { redactText } from '../guard/redactor.js';
+import { SftpClient } from '../ssh/sftp.js';
+import { TOOL_DESCRIPTIONS as D } from './descriptions.js';
+import { syntheticSuccess, textResult } from './results.js';
+/** SFTP transfer tools. */
+export function registerFileTools({ server }, pipeline) {
+    const { runAudited } = pipeline;
+    // ─── sftp-upload ───────────────────────────────────────────────────────
+    server.tool('sftp-upload', D["sftp-upload"], {
+        remotePath: z.string().describe('Remote file path'),
+        content: z.string().describe('File content to upload'),
+        profile: z.string().optional().describe('Profile name'),
+    }, { destructiveHint: true }, async ({ remotePath, content, profile }, extra) => {
+        return runAudited(`sftp:upload ${remotePath}`, { toolName: 'sftp-upload', failureClass: 'destructive', profile, extra, synthetic: true }, async (rt) => {
+            await new SftpClient(rt.conn).upload({ remotePath, content });
+            return {
+                audited: syntheticSuccess(rt.profileName),
+                output: textResult(`Uploaded ${content.length} bytes to ${remotePath}`),
+            };
+        });
+    });
+    // ─── sftp-download ─────────────────────────────────────────────────────
+    server.tool('sftp-download', D["sftp-download"], {
+        remotePath: z.string().describe('Remote file path to download'),
+        profile: z.string().optional().describe('Profile name'),
+    }, { readOnlyHint: true }, async ({ remotePath, profile }, extra) => {
+        return runAudited(`sftp:download ${remotePath}`, { toolName: 'sftp-download', failureClass: 'read-only', profile, extra, synthetic: true }, async (rt) => {
+            const data = await new SftpClient(rt.conn).download({ remotePath });
+            return {
+                audited: syntheticSuccess(rt.profileName),
+                output: textResult(redactText(data.toString('utf8'), { entropyScan: true })),
+            };
+        });
+    });
+}