ssh-mcp 2.8.3 → 2.9.0

package/README.md

@@ -142,7 +142,7 @@ claude mcp add --transport stdio ssh-mcp -- ssh-mcp
 
 ---
 
-## Tools (11)
+## Tools (14)
 
 | Tool | Purpose | readOnly | destructive |
 |------|---------|:--------:|:----------:|
@@ -156,8 +156,63 @@ claude mcp add --transport stdio ssh-mcp -- ssh-mcp
 | `privileged-command` | Execute with sudo (needs approval, unless `approvalPolicy = "auto"`) | — | ✅ |
 | `sftp-upload` | Upload a file via SFTP | — | ✅ |
 | `sftp-download` | Download a file via SFTP | ✅ | — |
+| `sftp-list` | List a remote directory, bounded in entries and bytes | ✅ | — |
+| `sftp-upload-file` | Stream a local file to the remote host, never through model context | — | ✅ |
+| `sftp-download-file` | Stream a remote file to local disk, never through model context | — | ✅ |
 | `signal-process` | Send INT/TERM/KILL to a remote PID | — | ✅ |
 
+### Streaming file transfer
+
+`sftp-upload`/`sftp-download` move file *contents* through the model's context:
+the text is an argument on the way out and a response on the way back. That is
+what you want for a config snippet and exactly what you do not want for a 200 MB
+tarball or anything binary.
+
+`sftp-upload-file` and `sftp-download-file` stream between the remote host and
+local disk instead. Neither the bytes nor a base64 encoding of them ever reaches
+the model — the response is a byte count and two paths.
+
+The two transfer tools are **off until you configure `defaults.transferRoot`**,
+and refuse with an explanation until then. (`sftp-list` has no local side and
+needs none of this.) That directory is the whole of their local reach:
+
+```toml
+[defaults]
+transferRoot = "/srv/ssh-mcp-transfers"
+transferMaxBytes = 268435456        # 256MB per transfer
+transferTimeoutMs = 300000          # 5min with no bytes moving
+```
+
+Checked on every call, and refused rather than degraded if any of it fails: the
+directory must be `0700` and owned by the account running this server, with no
+group- or world-writable parent, and must not overlap the ssh-mcp installation,
+the config directory, the audit log directory, or `~/.ssh`. Caller paths are
+confined to it, symlinks are refused rather than followed, and a download is
+staged as a sibling `.part` file and published atomically, so a failed transfer
+never leaves a half-written file at the destination.
+
+`transferTimeoutMs` is an **idle** budget, not a total one: it bounds one
+metadata round-trip, or one stretch of the copy with no bytes moving, and is
+re-armed on progress. A slow but live transfer of a large file survives it; a
+stalled channel still fails within one window. That is why the byte cap above
+does not have to be divided by it — a total budget would have made a 256MB cap
+mean "only if the link sustains 900 KB/s".
+
+Not available on Windows, where the transfer root cannot yet be verified
+private; the two transfer tools refuse there rather than writing into a
+directory other accounts may be able to read.
+
+`sftp-upload-file` takes an optional `mode` (1–511; setuid, setgid and the
+sticky bit are refused). Omitted, a new remote file is published `0600`; an
+overwritten one inherits the replaced file's permission bits — its permission
+bits only, not its setuid or setgid.
+
+What a transfer is authorized for includes these arguments: the string the
+policy engine classifies, the approval prompt a human reads, and the audit
+record all name `--overwrite` and `--mode` when they are given. So approving one
+upload to a path does not approve a different one to the same path, and an
+approval grant (`approvalGrantTtlMs`) cannot be replayed with a different mode.
+
 ### Interactive Sessions
 
 Sessions maintain state (CWD, environment variables) between commands:
@@ -189,6 +244,8 @@ OpenSSH on Windows 11.
 |---|:---:|:---:|
 | `read-command`, `run-command`, `privileged-command`, `signal-process` | ✅ | ✅ |
 | `sftp-upload`, `sftp-download` | ✅ | ✅ |
+| `sftp-list` | ✅ | ✅ |
+| `sftp-upload-file`, `sftp-download-file` | ✅ | ❌ (local side unverifiable) |
 | Background sessions | ✅ | ✅ |
 | **Interactive sessions** | ✅ | ❌ |
 
@@ -220,6 +277,9 @@ connectionIdleReapMs = 900000       # 15min
 commandQuotaPerDay = 0              # 0 = unlimited; circuit breaker for runaway agents
 approvalGrantTtlMs = 0              # 0 = always prompt; see "Approval Grants"
 approvalMode = "ask-destructive"    # auto | ask-destructive | ask-all | deny
+# transferRoot = "/srv/ssh-mcp-transfers"   # enables the streaming file tools; see above
+transferMaxBytes = 268435456        # 256MB per streaming transfer
+transferTimeoutMs = 300000          # 5min with no bytes moving (idle, not total)
 
 [[profiles]]
 name = "prod-web-1"
@@ -242,6 +302,8 @@ sessionMaxPerConnection = 3         # per-profile override
 sessionIdleTimeoutMs = 300000       # stricter for prod
 commandQuotaPerDay = 200            # per-profile override
 maxChars = 2000                     # per-profile override; stricter for prod
+transferMaxBytes = 16777216         # per-profile override; transferRoot is not per-profile
+transferTimeoutMs = 60000           # per-profile override
 
 # Optional. Merged over the built-in role matrix; see "Policy Engine" below.
 # roleBindings is keyed by role and then by tier, so the block below changes

package/build/cli.js

@@ -229,6 +229,13 @@ export function defaultsFromArgv(argv) {
         commandQuotaPerDay: parseInt(argv.commandQuota) || 0,
         approvalGrantTtlMs: parseInt(argv.approvalGrantTtl) || 0,
         approvalMode: 'ask-destructive',
+        // No flag for transferRoot on purpose. It is the consent to touch local
+        // disk, and the quick-start path exists for someone who passed a host and a
+        // user on a command line — not a place to acquire that consent in passing.
+        // The streaming file tools therefore refuse under `--host/--user` until a
+        // config file names a root.
+        transferMaxBytes: 268_435_456,
+        transferTimeoutMs: 300_000,
     };
 }
 export async function buildAppConfig(argv) {
@@ -330,6 +337,8 @@ export async function buildAppConfig(argv) {
         sessionIdleTimeoutMs: defaults.sessionIdleTimeoutMs,
         sessionBackgroundMaxMs: defaults.sessionBackgroundMaxMs,
         commandQuotaPerDay: defaults.commandQuotaPerDay,
+        transferMaxBytes: defaults.transferMaxBytes,
+        transferTimeoutMs: defaults.transferTimeoutMs,
     };
     return { defaults, profiles: [profile] };
 }

package/build/config/loader.js

@@ -169,6 +169,8 @@ function normalizeConfig(raw) {
         sessionIdleTimeoutMs: p.sessionIdleTimeoutMs ?? defaults.sessionIdleTimeoutMs,
         sessionBackgroundMaxMs: p.sessionBackgroundMaxMs ?? defaults.sessionBackgroundMaxMs,
         commandQuotaPerDay: p.commandQuotaPerDay ?? defaults.commandQuotaPerDay,
+        transferMaxBytes: p.transferMaxBytes ?? defaults.transferMaxBytes,
+        transferTimeoutMs: p.transferTimeoutMs ?? defaults.transferTimeoutMs,
     }));
     // Passed through untouched. mergePolicyRules() owns the layering over
     // DEFAULT_RULES, so the loader has no policy semantics of its own to get

package/build/config/schema.js

@@ -101,6 +101,39 @@ export const defaultsSchema = z.object({
     // it is opt-in rather than a default convenience.
     approvalGrantTtlMs: z.number().int().nonnegative().default(0),
     approvalMode: approvalModeSchema.default('ask-destructive'),
+    /**
+     * Where the streaming SFTP file tools may read and write on this machine.
+     *
+     * No default, and deliberately not a per-profile key. It names a directory on
+     * the machine running this server rather than anything about a remote host,
+     * and the gate in tools/local-path.ts insists the directory be 0700 and owned
+     * by this account — so an operator who has not chosen one has not consented to
+     * those tools touching local disk at all. Absent, they refuse; there is no
+     * spelling of it that means "anywhere".
+     */
+    transferRoot: z.string().optional(),
+    // 256 MiB. Also a disk-usage bound on `transferRoot`, because a download is
+    // staged there as a `.part` before it is published, so the cap is how much a
+    // single call can put in a directory the operator may not be watching.
+    //
+    // Bounded above at MAX_SAFE_INTEGER because `assertBounds` in ssh/sftp.ts
+    // refuses anything larger. Without that bound here, a config naming a bigger
+    // number started cleanly and then failed every transfer at call time — the
+    // "accepted by the schema but never applied" shape this file's other comments
+    // exist to prevent, moved one layer down.
+    transferMaxBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).default(268_435_456),
+    // An *idle* budget, not a wall-clock one: it bounds one metadata round-trip,
+    // or one stretch of the copy with no bytes moving, and is re-armed on progress
+    // (see TransferBounds in ssh/sftp.ts). That is what lets a slow-but-live
+    // transfer of a large file survive a generous byte cap, so the two do not have
+    // to be divided into each other to check they are coherent (#206). It does not
+    // make a stall cheaper to notice: a channel that stops delivering still costs
+    // one full window, which at this default is five minutes.
+    //
+    // Capped at 2^31-1, the largest delay `setTimeout` honours — Node clamps a
+    // larger one to 1ms, so every step would fail immediately while quoting the
+    // value the operator asked for.
+    transferTimeoutMs: z.number().int().positive().max(2_147_483_647).default(300_000),
 }).strict();
 export const profileSchema = z.object({
     name: z.string().min(1),
@@ -140,6 +173,11 @@ export const profileSchema = z.object({
     sessionIdleTimeoutMs: z.number().int().positive().optional(),
     sessionBackgroundMaxMs: z.number().int().positive().optional(),
     commandQuotaPerDay: z.number().int().nonnegative().optional(),
+    // Per-profile, unlike transferRoot: how large a transfer may be, and how long
+    // a silent wire is tolerated, are properties of the link to that host. Same
+    // upper bounds as [defaults], for the same reason.
+    transferMaxBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+    transferTimeoutMs: z.number().int().positive().max(2_147_483_647).optional(),
 }).strict();
 /**
  * Overrides merged over the compiled-in DEFAULT_RULES at startup.

package/build/guard/sanitizer.js

@@ -41,6 +41,95 @@ export function sanitizeCommand(command, maxChars) {
     }
     return cleaned;
 }
+/**
+ * Every character that could make the audited string, the approval prompt and
+ * the path actually used disagree with each other.
+ *
+ * C0 and C1 controls, the Unicode line separators, the whole Bidi_Control set
+ * (U+061C, U+200E, U+200F, U+202A-U+202E, U+2066-U+2069) and the zero-width
+ * formatters. A remote path is quoted back to a human in the approval prompt
+ * and written into a hash-chained audit record, so a name carrying a
+ * right-to-left override renders as one path and transfers another, and one
+ * carrying a zero-width space renders identically to a different path.
+ *
+ * An earlier version stopped at the overrides and isolates, which left the
+ * marks that reorder *neutral* characters — and a path is mostly neutrals:
+ * slashes, dots, hyphens and digits.
+ *
+ * Exported because `tools/local-path.ts` asks the same question of the local
+ * half. The two *functions* are split for a real reason — that one has to stat
+ * and this one must not — but the character class is one threat model, and two
+ * copies of it drift the first time a codepoint is added.
+ */
+export const PATH_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/;
+/** Longer than any path a real filesystem accepts, so this bounds nothing legitimate. */
+const MAX_REMOTE_PATH_CHARS = 4096;
+/** What the audit record calls a path that never passed validation. */
+export const REJECTED_REMOTE_PATH = '(rejected: invalid remote path)';
+/**
+ * Validate a caller-supplied *remote* path for the streaming SFTP file tools.
+ *
+ * Pure: it touches no filesystem and reaches no host, which is what lets it run
+ * before the policy decision (#207). The local half of the same question is
+ * `tools/local-path.ts`, and that one cannot be pure — it has to stat — so it
+ * runs after approval instead.
+ *
+ * Leading and trailing whitespace is **refused**, not trimmed. `sanitizeCommand`
+ * trims because a shell ignores whitespace at either end of a command, so
+ * trimming cannot change what runs. A path is not a command: only NUL and `/`
+ * are excluded from a POSIX filename, so `"report.txt "` and `"report.txt"` are
+ * two different files. Trimming here silently retargeted the transfer and
+ * audited the name it did not use.
+ *
+ * Shell metacharacters are deliberately *not* refused. The path is interpolated
+ * into a synthetic command (`sftp:upload-file <path>`) that the classifier then
+ * reads, and `classifyCommand` treats anything a shell would read as a carrier
+ * by taking the *higher* class — so `/tmp/x; sudo id` classifies `privileged`
+ * and is refused by policy rather than slipping through at `destructive`. A
+ * filename that genuinely contains a `$` is refused for the same reason, which
+ * is the direction to fail in.
+ */
+export function sanitizeRemotePath(path) {
+    if (typeof path !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'Remote path must be a string');
+    }
+    if (!path) {
+        throw new McpError(ErrorCode.InvalidParams, 'Remote path cannot be empty');
+    }
+    if (path !== path.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'Remote path cannot begin or end with whitespace: a filename may legitimately ' +
+            'contain it, so trimming would transfer a different file than the one named ' +
+            'and audit the name it did not use.');
+    }
+    if (path.length > MAX_REMOTE_PATH_CHARS) {
+        throw new McpError(ErrorCode.InvalidParams, `Remote path is too long (max ${MAX_REMOTE_PATH_CHARS} characters)`);
+    }
+    if (PATH_CONTROL_CHARS.test(path)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Remote path cannot contain control, bidirectional or zero-width formatting ' +
+            'characters: the approval prompt and the audit record quote this path back, ' +
+            'and such a character makes what is shown differ from what is transferred.');
+    }
+    return path;
+}
+/**
+ * The same path, or a fixed placeholder when it is invalid — never throws.
+ *
+ * So that a refused call still has something to file an audit record under. The
+ * audited string has to be built before `runAudited` can evaluate anything, and
+ * building it from an unvalidated path would put a control character into a
+ * hash-chained log; building it from nothing left a client probing the
+ * validation boundary invisible to the operator, which is the failure
+ * `pipeline.ts` moved sanitization inside its own try to remove. The throwing
+ * check still runs, in `preCheck`, where the refusal is audited.
+ */
+export function remotePathForAudit(path) {
+    try {
+        return sanitizeRemotePath(path);
+    }
+    catch {
+        return REJECTED_REMOTE_PATH;
+    }
+}
 export function sanitizeSessionName(name) {
     if (!/^[a-zA-Z0-9_-]{1,64}$/.test(name)) {
         throw new McpError(ErrorCode.InvalidParams, 'Session name must be 1-64 chars, alphanumeric/dash/underscore only');

package/build/index.js

@@ -6,7 +6,9 @@ import { ConnectionRegistry } from './ssh/connection-registry.js';
 import { PolicyEngine, resolvePolicyRules } from './policy/engine.js';
 import { AuditStore } from './audit/store.js';
 import { registerTools, registerResources, getToolHashes } from './tools/registry.js';
+import { transferForbiddenDirs } from './tools/forbidden-dirs.js';
 import { initKeychain } from './config/credential-resolver.js';
+import { getConfigPath } from './config/loader.js';
 import { SERVER_VERSION } from './version.js';
 import { parseArgv, buildAppConfig, checkRemovedFlags, flagEnabled, parseFailureLimit, parseOpaUrl, parseOpaTimeout, resolveHostKeyMode, } from './cli.js';
 async function main() {
@@ -25,6 +27,13 @@ async function main() {
         const { initTracing } = await import('./observability/tracer.js');
         await initTracing(argv.otelEndpoint, argv.otelServiceName || 'ssh-mcp');
     }
+    // Everything the transfer-root gate needs that it must not reach for itself:
+    // which config file was actually loaded, and which directories are off limits.
+    const localPath = {
+        transferRoot: config.defaults.transferRoot,
+        configPath: getConfigPath(argv.config || undefined),
+        forbidden: transferForbiddenDirs(),
+    };
     const registry = new ConnectionRegistry(config, hostKeyMode);
     const policy = new PolicyEngine(resolvePolicyRules(config.profiles, config.policy));
     const audit = new AuditStore(undefined, entropyScan, tamperEvident);
@@ -44,6 +53,7 @@ async function main() {
         const server = new McpServer({ name: 'SSH MCP Server', version: SERVER_VERSION }, { capabilities: { tools: {}, resources: {} } });
         registerTools(server, registry, policy, audit, {
             approvalGrantTtlMs: config.defaults.approvalGrantTtlMs,
+            localPath,
         });
         registerResources(server, registry);
         return server;

package/build/ssh/sftp.js

@@ -396,8 +396,9 @@ export class SftpClient {
      *
      * 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.
+     * target's owner and ACL do not survive. The permission bits do, unless the
+     * caller passes a mode — but only the low nine: setuid, setgid and the sticky
+     * bit are dropped rather than carried across. See the chmod below.
      */
     async uploadFile(source, remotePath, opts) {
         assertBounds(opts.idleTimeoutMs, opts.maxBytes, 'SFTP upload');
@@ -433,8 +434,16 @@ export class SftpClient {
                 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.
+                    //
+                    // The low nine bits only. `& 0o7777` also carried setuid, setgid and
+                    // the sticky bit across, which turns "may replace this file" into "may
+                    // run code as its owner" — measured against a 04755 destination owned
+                    // by the SSH user: the content became the caller's and the mode stayed
+                    // 4755. Nothing else in the upload path could have caught it, because
+                    // the caller never named a mode; it arrived by inheritance, through the
+                    // one argument the caller can omit.
                     await callbackBeforeDeadline(opts, 'SFTP upload chmod', (callback) => {
-                        sftp.chmod(temporary, inheritedMode & 0o7777, (err) => callback(err ?? undefined));
+                        sftp.chmod(temporary, inheritedMode & 0o777, (err) => callback(err ?? undefined));
                     });
                 }
                 if (!opts.overwrite && await exists()) {
@@ -574,6 +583,15 @@ export class SftpClient {
             let retained = 0;
             let responseBytes = 0;
             let budgetTruncated = false;
+            // The loop advances on retained entries or on EOF, and neither is
+            // guaranteed: a batch holding only `.`/`..` is legitimately empty after
+            // filtering and must not be read as EOF, so a server answering every
+            // READDIR that way kept this issuing requests forever. Each step has its
+            // own idle bound; nothing bounded the number of steps, and a synthetic
+            // tool call carries no overall deadline — so the call never settled.
+            // Sixteen is far past any real directory layout and still terminates.
+            const MAX_BARREN_BATCHES = 16;
+            let barren = 0;
             try {
                 while (retained <= opts.maxEntries && !budgetTruncated) {
                     const batch = await callbackBeforeDeadline(opts, 'SFTP list read', (callback) => {
@@ -593,6 +611,7 @@ export class SftpClient {
                     });
                     if (batch === null)
                         break;
+                    const before = retained;
                     for (const entry of batch) {
                         if (entry.filename === '.' || entry.filename === '..')
                             continue;
@@ -614,6 +633,14 @@ export class SftpClient {
                             break;
                         entries.push(toSftpStat(join(remotePath, entry.filename), entry.attrs));
                     }
+                    if (retained === before && !budgetTruncated) {
+                        if (++barren >= MAX_BARREN_BATCHES) {
+                            throw new Error(`SFTP list error: server returned ${MAX_BARREN_BATCHES} consecutive batches with no entries and no EOF`);
+                        }
+                    }
+                    else {
+                        barren = 0;
+                    }
                 }
             }
             finally {

package/build/tools/descriptions.js

@@ -10,6 +10,9 @@ export const TOOL_DESCRIPTIONS = {
     'privileged-command': 'Execute a command with sudo elevation. Goes through the approval gate; approvalPolicy on the profile decides whether that is a prompt, an automatic allow, or a refusal. The sudo password is piped via stdin (never visible in process list). Single-line only: a command containing a line break is refused, so upload a multi-line script with sftp-upload and run it by path.',
     '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.',
+    'sftp-list': 'List a remote directory over SFTP, with a bounded number of entries and a bounded response size. Read-only.',
+    'sftp-upload-file': 'Upload a local file to the remote host over SFTP, streaming it without passing the contents through model context. The local file must be inside the transferRoot directory the operator configured; without that setting this tool refuses. Use this for binary or large files; use sftp-upload for short text you already have.',
+    'sftp-download-file': 'Download a remote file to local disk over SFTP, streaming it without passing the contents through model context. The destination must be inside the transferRoot directory the operator configured; without that setting this tool refuses. Use this for binary or large files; use sftp-download when you need to read the contents.',
     'signal-process': 'Send a signal (INT, TERM, KILL) to a remote process by PID.',
 };
 export function getToolHashes() {

package/build/tools/forbidden-dirs.js

@@ -0,0 +1,31 @@
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getAuditLogPath } from '../audit/store.js';
+/**
+ * Directories the transfer root must not overlap, beyond the two the gate
+ * already derives for itself (the installation and the config directory).
+ *
+ * Its own module rather than a literal at the call site in index.ts, because
+ * there the list sat inside `main()`'s body, which no test can reach — it is not
+ * exported, and nothing short of starting the server evaluates it. So the list
+ * was the one input to the transfer-root gate that nothing verified, while the
+ * gate itself was thoroughly tested against whatever it was handed. (index.ts
+ * does not run `main()` under test: the call is gated on SSH_MCP_DISABLE_MAIN,
+ * which every test script sets. Unreachable, not unimportable.) The gate takes
+ * the list as an argument precisely so that knowing where the audit log went is
+ * somebody else's job — this is that somebody.
+ *
+ * Both entries are conventionally 0700 and owner-owned, so every privacy check
+ * the gate applies accepts them. They have to be excluded by name:
+ *
+ * - a root containing the audit log lets a download replace the tamper-evident
+ *   record of the transfer that wrote it;
+ * - a root shaped like `~/.ssh` turns the same two tools into "read the private
+ *   key" and "append to authorized_keys".
+ */
+export function transferForbiddenDirs() {
+    return [
+        { path: dirname(getAuditLogPath()), reason: 'the audit log directory' },
+        { path: join(homedir(), '.ssh'), reason: 'the SSH client directory (~/.ssh)' },
+    ];
+}

package/build/tools/local-path.js

@@ -7,9 +7,12 @@ 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';
+// One class, one threat model. It lived here as a private copy and in
+// guard/sanitizer.ts as a byte-identical second one, so widening it — a bidi
+// mark, a zero-width formatter — reached whichever file the author had open.
+import { PATH_CONTROL_CHARS } from '../guard/sanitizer.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
@@ -27,6 +30,33 @@ function validateInput(input) {
         invalid('Local path cannot contain control or bidi formatting characters');
     }
 }
+/** What the audit record and the approval prompt call a path that never validated. */
+export const REJECTED_LOCAL_PATH = '(rejected: invalid local path)';
+/**
+ * The caller's own spelling of a local path, or a placeholder — never throws,
+ * and touches no filesystem.
+ *
+ * Everything else in this file has to stat, which is why it all runs after the
+ * policy decision. This one does not, which is what lets the *approval prompt*
+ * name both ends of a transfer. Without it the human approving a download saw
+ * the remote path and nothing about where on their own disk the bytes would
+ * land — and the local write is the half that makes a download `destructive`.
+ *
+ * It is the caller's spelling, not the resolved one: resolving needs `realpath`.
+ * `onResolved` replaces it with the canonical form once the gate has run, so the
+ * audit record ends up with the path actually used.
+ */
+export function localPathForAudit(input) {
+    if (typeof input !== 'string')
+        return REJECTED_LOCAL_PATH;
+    try {
+        validateInput(input);
+        return input;
+    }
+    catch {
+        return REJECTED_LOCAL_PATH;
+    }
+}
 function display(root, candidate) {
     const value = relative(root, candidate);
     return value || '.';

package/build/tools/pipeline.js

@@ -179,10 +179,21 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
                 throw new PolicyRefusedError(`QUOTA_EXCEEDED: profile "${profileName}" has used its ${profile.commandQuotaPerDay} commands ` +
                     `for the last 24h. Next slot frees at ${budget.retryAt?.toISOString()}.`, { ...evaluation, decision: 'deny', ruleId: 'command-quota' });
             }
+            const approved = effective;
+            const refineCommand = (refined) => {
+                if (!refined.startsWith(approved)) {
+                    throw new Error('Internal: an audited command may only be elaborated, not replaced');
+                }
+                state.command = refined;
+            };
             const { audited, output } = await run({
                 conn, command: effective, profileName, onProgress, abortSignal, extra: opts.extra,
+                refineCommand,
             });
-            await auditResult(ctx, profileName, effective, evaluation, audited, approver);
+            // `state.command`, not `effective`: identical unless the handler refined
+            // it, and the refinement is exactly what the success record should carry.
+            // The failure path below already reads `state`, so the two agree.
+            await auditResult(ctx, profileName, state.command, evaluation, audited, approver);
             return output;
         }
         catch (err) {

package/build/tools/registry.js

@@ -2,14 +2,16 @@ import { createPipeline } from './pipeline.js';
 import { registerSessionTools } from './session-tools.js';
 import { registerCommandTools } from './command-tools.js';
 import { registerFileTools } from './file-tools.js';
+import { registerTransferTools } from './transfer-tools.js';
 // Re-exported so existing importers keep a single entry point for the tool layer.
 export { TOOL_DESCRIPTIONS, getToolHashes } from './descriptions.js';
 export { registerResources } from './resources.js';
 /**
  * Wire every MCP tool onto the server.
  *
- * The handlers live in three groups by subject (sessions, commands, files) and
- * share one audited pipeline, built here. Splitting them up is what keeps the
+ * The handlers live in four groups by subject (sessions, commands, text-mode
+ * file transfer, streaming file transfer) and share one audited pipeline, built
+ * here. Splitting them up is what keeps the
  * pipeline the only route from caller input to a remote command: a handler that
  * wanted to bypass policy or audit would have to reach past `pipeline` for the
  * registry, which it is not given.
@@ -20,4 +22,5 @@ export function registerTools(server, registry, policy, audit, opts = {}) {
     registerSessionTools(deps, pipeline);
     registerCommandTools(deps, pipeline);
     registerFileTools(deps, pipeline);
+    registerTransferTools(deps, pipeline);
 }

package/build/tools/session-tools.js

@@ -44,7 +44,7 @@ export function registerSessionTools({ server, registry }, pipeline) {
         // first ("discover available hosts before running commands"), and on the one
         // channel where the startup stderr warning is not visible. The agent saw "no
         // hosts" rather than "not configured". Refusing here is what makes the claim in
-        // the README, the changeset and the startup warning true of all eleven tools.
+        // the README, the changeset and the startup warning true of every tool.
         registry.assertConfigured();
         const connections = registry.listConnections();
         const profiles = registry.listAllProfiles();

package/build/tools/transfer-tools.js

@@ -0,0 +1,341 @@
+import { z } from 'zod';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { redactText } from '../guard/redactor.js';
+import { remotePathForAudit, sanitizeRemotePath } from '../guard/sanitizer.js';
+import { SftpClient } from '../ssh/sftp.js';
+import { TOOL_DESCRIPTIONS as D } from './descriptions.js';
+import { createLocalDownload, localFileForRead, localPathForAudit, } from './local-path.js';
+import { syntheticSuccess, textResult } from './results.js';
+/**
+ * Upper bound on `maxEntries`, independent of what the caller asks for.
+ *
+ * The response is also capped in bytes by the profile's `maxOutputBytes`, so
+ * this is not the thing that keeps a huge directory out of the model's context
+ * — that bound does. This one keeps the *count* an argument cannot inflate, so
+ * a caller cannot turn one tool call into an unbounded walk of a remote tree.
+ */
+const MAX_LIST_ENTRIES = 1000;
+const DEFAULT_LIST_ENTRIES = 200;
+/**
+ * rwx triples the way `ls -l` prints them, setuid/setgid/sticky included.
+ *
+ * Reading only the low nine bits renders `-rwsr-xr-x` as `-rwxr-xr-x`: a format
+ * that imitates `ls -l` while dropping the only three bits that carry privilege.
+ * An operator or a model deciding whether a remote file is safe to overwrite
+ * could not see that it was setuid — which is precisely the precondition that
+ * makes overwriting one dangerous.
+ */
+function renderPermissions(mode) {
+    const rwx = 'rwxrwxrwx';
+    const out = [];
+    for (let i = 0; i < 9; i++)
+        out.push((mode & (1 << (8 - i))) ? rwx[i] : '-');
+    // Each special bit replaces the x of its own triple, upper-case when that x is
+    // not set — setuid without execute is `S`, with it `s`, as `ls` renders it.
+    const special = [
+        [0o4000, 2, 's'],
+        [0o2000, 5, 's'],
+        [0o1000, 8, 't'],
+    ];
+    for (const [bit, at, char] of special) {
+        if (mode & bit)
+            out[at] = out[at] === 'x' ? char : char.toUpperCase();
+    }
+    return out.join('');
+}
+/**
+ * The `ls -l` type character, from the mode's file-type bits.
+ *
+ * Read from the mode rather than from `isDirectory`/`isFile`, which between
+ * them cover two of the seven types and report everything else as neither.
+ * Measured against the test image's `/usr/bin`, where nearly every entry is a
+ * symlink: a listing built from those two booleans rendered the whole directory
+ * as `?`, which tells a model less than the raw filename did.
+ */
+function typeChar(mode) {
+    switch (mode & 0o170000) {
+        case 0o040000: return 'd';
+        case 0o100000: return '-';
+        case 0o120000: return 'l';
+        case 0o060000: return 'b';
+        case 0o020000: return 'c';
+        case 0o010000: return 'p';
+        case 0o140000: return 's';
+        default: return '?';
+    }
+}
+/** Width of an ISO timestamp, so the placeholder below keeps the columns aligned. */
+const MTIME_WIDTH = 24;
+/**
+ * A remote mtime is optional on the wire, so it may be no date at all.
+ *
+ * ssh2 fills `attrs.mtime` only when the entry carries SSH_FILEXFER_ACMODTIME,
+ * and `toSftpStat` turns a missing one into `new Date(NaN)`. `toISOString()`
+ * throws `RangeError: Invalid time value` on that, inside the `map` that builds
+ * the response — so a single entry from a server that omits the flag failed the
+ * whole listing with an opaque error instead of returning the directory. The
+ * mode fields already degrade rather than throw (`undefined & mask` is 0, which
+ * renders as `?` and `---------`); this makes the timestamp behave the same way.
+ */
+function renderMtime(mtime) {
+    return Number.isNaN(mtime.getTime()) ? '(no mtime)'.padStart(MTIME_WIDTH) : mtime.toISOString();
+}
+function renderEntry(entry) {
+    const size = String(entry.size).padStart(12, ' ');
+    return `${typeChar(entry.mode)}${renderPermissions(entry.mode)} ${size}  ${renderMtime(entry.mtime)}  ${entry.path}`;
+}
+/**
+ * Render the listing, stopping at the byte budget the caller's profile sets.
+ *
+ * `SftpClient.list` bills `filename + longname + 256` per retained entry, which
+ * is a proxy for what a line costs and not the line itself: `entry.path` is the
+ * directory joined to the filename, so the directory is repeated on every line
+ * and the flat 256 never covered it. With a long remote path the rendered body
+ * ran several times past the profile's `maxOutputBytes` while the layer that
+ * believed it was enforcing the budget had spent a fraction of it.
+ *
+ * So the bound is applied to the bytes actually produced. The primitive's budget
+ * still matters — it is what stops a hostile server's `longname` being retained
+ * in memory — but the number the operator configured now describes the thing
+ * they configured it for, which is what reaches the model.
+ */
+function renderListing(entries, maxBytes) {
+    const lines = [];
+    let bytes = 0;
+    for (const entry of entries) {
+        const line = renderEntry(entry);
+        const cost = Buffer.byteLength(line, 'utf8') + 1;
+        if (bytes + cost > maxBytes)
+            return { body: lines.join('\n'), truncated: true };
+        bytes += cost;
+        lines.push(line);
+    }
+    return { body: lines.join('\n'), truncated: false };
+}
+/**
+ * Refuse a mode that grants authority the transfer itself does not carry.
+ *
+ * Everything above the low nine bits is setuid, setgid and the sticky bit. A
+ * caller allowed to write a file is not thereby allowed to write one that runs
+ * as its owner, and `uploadFile` passes this straight to the remote `open`.
+ *
+ * `0` is refused rather than accepted. `uploadFile` reads it as "unset" through
+ * an `||`, so a caller asking for mode 0 got 0600 — and on the overwrite path it
+ * also suppressed the inherit-the-destination's-mode step, yielding neither the
+ * mode asked for nor the one replaced. An argument silently rewritten is worse
+ * than one refused.
+ *
+ * Runs as a `preCheck`, i.e. inside the pipeline, so a caller probing the
+ * boundary leaves an audit record. The range is deliberately *not* duplicated as
+ * a zod bound on the field: the SDK validates the schema before the handler is
+ * entered, so a bound there refused a setuid mode outside the pipeline — no
+ * audit record, and this message unreachable. Measured: with both in place, a
+ * probe at 0o4755 produced no audit record at all.
+ */
+export function checkMode(mode) {
+    if (mode === undefined)
+        return undefined;
+    if (!Number.isInteger(mode) || mode < 1 || mode > 0o777) {
+        throw new McpError(ErrorCode.InvalidParams, 'mode must be between 1 and 511 (0o777), or omitted. setuid, setgid and the sticky bit ' +
+            'are refused: uploading a file does not carry the authority to make it run as its owner. ' +
+            '0 is refused because it is read as "unset" downstream rather than as a mode.');
+    }
+    return mode;
+}
+/** The arguments that change what a transfer does, spelled for policy and the approver. */
+function effectSuffix(overwrite, mode) {
+    return (overwrite ? ' --overwrite' : '') + (mode !== undefined ? ` --mode=${mode.toString(8)}` : '');
+}
+/**
+ * What the audit record adds once the local path has been resolved.
+ *
+ * Appended rather than substituted, and empty when the two agree. The refinement
+ * has to satisfy the pipeline's append-only rule — the audited string may
+ * elaborate what was approved, never replace it — and swapping `./sub/../x.bin`
+ * for `x.bin` is a replacement, which `refineCommand` correctly threw on.
+ *
+ * Appending turns out to be the better record anyway: an auditor sees the
+ * spelling the caller sent *and* the file it resolved to, so a divergence
+ * between them is visible rather than silently normalised away.
+ */
+function resolvedSuffix(asked, resolved) {
+    return asked === resolved ? '' : ` (resolved ${resolved})`;
+}
+/**
+ * Streaming SFTP tools: bounded directory listing, and transfers that move
+ * between the remote host and local disk without passing through model context.
+ *
+ * Two orderings are load-bearing here, and both come from #207.
+ *
+ * **Nothing observable precedes the decision.** The audited string is built from
+ * the caller's own spelling of both paths, through `remotePathForAudit` and
+ * `localPathForAudit`, neither of which performs any I/O. Every local effect —
+ * the existence check, the staged `.part`, the operator-configuration errors the
+ * transfer-root gate produces — happens inside `run()`, which the pipeline
+ * reaches only after the call is allowed and approved. The throwing validators
+ * run as `preCheck`, inside the pipeline's own try, so a refused call still
+ * leaves an audit record rather than letting a client probe the boundary
+ * invisibly.
+ *
+ * **The decision is about the whole operation.** `overwrite` and `mode` change
+ * what a call does — one destroys an existing remote file, the other sets its
+ * permissions — so they belong in the string policy classifies, in the prompt a
+ * human reads, and in the key an approval grant is remembered under. Left out,
+ * one approval of a path covered every other spelling of the call.
+ *
+ * The resolved local path is then *appended* to the audit record through
+ * `onResolved`, which the gate fires after confining the path and before it
+ * stats or opens anything — so a refusal raised by the checks that follow is
+ * audited with the resolution too, not only a success. Appended and not
+ * substituted, because the pipeline's rule is that an audited string may be
+ * elaborated and never replaced, and because an auditor is better served seeing
+ * both the spelling that was approved and the file it resolved to.
+ */
+export function registerTransferTools({ server, localPath }, pipeline) {
+    const { runAudited } = pipeline;
+    // Absent only when nothing was configured. The gate reads `transferRoot` and
+    // refuses with the message that names the config key, which is the same
+    // answer an operator who has a config but no root should get.
+    const ctx = localPath ?? { transferRoot: undefined };
+    // ─── sftp-list ─────────────────────────────────────────────────────────
+    server.tool('sftp-list', D['sftp-list'], {
+        remotePath: z.string().describe('Remote directory to list'),
+        maxEntries: z.number().int().min(1).max(MAX_LIST_ENTRIES).optional()
+            .describe(`Max entries to return (default ${DEFAULT_LIST_ENTRIES}, hard cap ${MAX_LIST_ENTRIES})`),
+        profile: z.string().optional().describe('Profile name'),
+    }, { readOnlyHint: true }, async ({ remotePath, maxEntries, profile }, extra) => {
+        return runAudited(`sftp:list ${remotePathForAudit(remotePath)}`, {
+            toolName: 'sftp-list',
+            failureClass: 'read-only',
+            profile,
+            extra,
+            synthetic: true,
+            preCheck: () => { sanitizeRemotePath(remotePath); },
+        }, async (rt) => {
+            const budget = rt.conn.profile.maxOutputBytes;
+            const { entries, truncated } = await new SftpClient(rt.conn).list(remotePath, {
+                maxEntries: maxEntries ?? DEFAULT_LIST_ENTRIES,
+                // The listing is output headed for the model, so it is billed
+                // against the same budget every other tool's output is.
+                maxResponseBytes: budget,
+                idleTimeoutMs: rt.conn.profile.transferTimeoutMs,
+                abortSignal: rt.abortSignal,
+            });
+            const rendered = renderListing(entries, budget);
+            const body = rendered.body || '(empty directory)';
+            const note = truncated || rendered.truncated
+                ? '\n\n[truncated: more entries exist than the entry or byte budget allowed]'
+                : '';
+            return {
+                audited: syntheticSuccess(rt.profileName),
+                // Filenames are remote, attacker-influenced content on their way
+                // into model context, exactly like command output.
+                output: textResult(redactText(body, { entropyScan: true }) + note),
+            };
+        });
+    });
+    // ─── sftp-upload-file ──────────────────────────────────────────────────
+    server.tool('sftp-upload-file', D['sftp-upload-file'], {
+        localPath: z.string().describe('Local file to upload, inside defaults.transferRoot'),
+        remotePath: z.string().describe('Remote destination path'),
+        overwrite: z.boolean().optional().describe('Replace an existing remote file (default false)'),
+        // The range is deliberately NOT declared here, only in `checkMode`. The SDK
+        // validates this schema before the handler runs, so a zod bound refuses a
+        // setuid mode *outside* the pipeline — no audit record, and the message
+        // explaining why setuid is refused unreachable. A probe at a security
+        // boundary that leaves no trace is the thing `preCheck` exists to prevent,
+        // so the bound lives where the refusal can be logged. `.int()` stays,
+        // because a non-integer is a type error rather than a probe.
+        mode: z.number().int().optional()
+            .describe('Remote file mode, 1 to 511 (0o777); setuid, setgid and the sticky bit are refused. e.g. 420 for 0644. Omit for 0600 on a new file, or the replaced file’s permission bits.'),
+        profile: z.string().optional().describe('Profile name'),
+    }, { destructiveHint: true }, async ({ localPath: source, remotePath, overwrite, mode, profile }, extra) => {
+        const target = remotePathForAudit(remotePath);
+        const approved = `sftp:upload-file ${target}${effectSuffix(overwrite, mode)} <- ${localPathForAudit(source)}`;
+        return runAudited(approved, {
+            toolName: 'sftp-upload-file',
+            failureClass: 'destructive',
+            profile,
+            extra,
+            synthetic: true,
+            preCheck: () => { sanitizeRemotePath(remotePath); checkMode(mode); },
+        }, async (rt) => {
+            const maxBytes = rt.conn.profile.transferMaxBytes;
+            // Refined through `onResolved`, which the gate fires after confining
+            // the path and before it stats or opens anything. Refining after the
+            // call returned covered only the success path — every refusal the gate
+            // itself raises (symlink source, outside the root, the root's own
+            // misconfiguration) audited the caller's spelling instead.
+            const local = await localFileForRead(ctx, source, (displayPath) => {
+                rt.refineCommand(`${approved}${resolvedSuffix(source, displayPath)}`);
+            });
+            try {
+                // Checked here as well as inside the transfer, because the size is
+                // already known: refusing before a byte moves beats refusing after
+                // the cap is passed mid-stream and a remote `.part` has to be
+                // cleaned up.
+                if (local.size > maxBytes) {
+                    throw new McpError(ErrorCode.InvalidParams, `Local file is ${local.size} bytes, over this profile's ${maxBytes} byte transfer limit`);
+                }
+                const bytes = await new SftpClient(rt.conn).uploadFile(local.handle.createReadStream({ autoClose: false }), remotePath, {
+                    maxBytes,
+                    idleTimeoutMs: rt.conn.profile.transferTimeoutMs,
+                    abortSignal: rt.abortSignal,
+                    overwrite,
+                    mode,
+                });
+                return {
+                    audited: syntheticSuccess(rt.profileName),
+                    output: textResult(`Uploaded ${bytes} bytes from ${local.displayPath} to ${remotePath}`),
+                };
+            }
+            finally {
+                await local.handle.close().catch(() => { });
+            }
+        });
+    });
+    // ─── sftp-download-file ────────────────────────────────────────────────
+    server.tool('sftp-download-file', D['sftp-download-file'], {
+        remotePath: z.string().describe('Remote file to download'),
+        localPath: z.string().describe('Local destination, inside defaults.transferRoot'),
+        overwrite: z.boolean().optional().describe('Replace an existing local file (default false)'),
+        profile: z.string().optional().describe('Profile name'),
+    }, { destructiveHint: true }, async ({ remotePath, localPath: destination, overwrite, profile }, extra) => {
+        const target = remotePathForAudit(remotePath);
+        const approved = `sftp:download-file ${target}${effectSuffix(overwrite)} -> ${localPathForAudit(destination)}`;
+        return runAudited(approved, {
+            toolName: 'sftp-download-file',
+            failureClass: 'destructive',
+            profile,
+            extra,
+            synthetic: true,
+            preCheck: () => { sanitizeRemotePath(remotePath); },
+        }, async (rt) => {
+            // As on the upload side, and for the same reason: refined before the
+            // `.part` exists, so the overwrite and symlink refusals are audited
+            // with the resolved destination, and a throw from `refineCommand`
+            // itself cannot strand a staged file.
+            const download = await createLocalDownload(ctx, destination, overwrite ?? false, (t) => {
+                rt.refineCommand(`${approved}${resolvedSuffix(destination, t.displayPath)}`);
+            });
+            try {
+                const bytes = await new SftpClient(rt.conn).downloadFile(remotePath, download.createStream(), {
+                    maxBytes: rt.conn.profile.transferMaxBytes,
+                    idleTimeoutMs: rt.conn.profile.transferTimeoutMs,
+                    abortSignal: rt.abortSignal,
+                });
+                await download.publish();
+                return {
+                    audited: syntheticSuccess(rt.profileName),
+                    output: textResult(`Downloaded ${bytes} bytes from ${remotePath} to ${download.target.displayPath}`),
+                };
+            }
+            finally {
+                // Always, and after publish(): destroying the stream closes the
+                // handle, and publish() needs it open to sync(). On the failure
+                // path this is what removes the staged `.part`.
+                await download.cleanup();
+            }
+        });
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.8.3",
+  "version": "2.9.0",
   "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",