ssh-mcp 2.2.6 → 2.3.0

package/build/errors.js

@@ -0,0 +1,116 @@
+import { writeSync } from 'fs';
+import { inspect } from 'util';
+/**
+ * Errors caused by how the server was invoked or configured, as opposed to a
+ * defect in it.
+ *
+ * The distinction exists because the two need to be *presented* differently.
+ * `main()` used to hand every failure to `console.error('Fatal error:', error)`,
+ * which prints an Error object — name, message and full stack. A missing
+ * `--host` therefore reached the operator as a stack trace through
+ * `buildAppConfig` and `main`, which reads as a crash. The three lines of
+ * explanation we wrote for them were buried inside frames that only matter to
+ * someone debugging this codebase. It is the first thing the reporter of #138
+ * pasted, and none of it pointed at their actual problem.
+ *
+ * `reportFatal` below is the other half of that rule and lives here rather than
+ * in the CLI entry point, so the reasoning is written once and a unit test can
+ * reach it without importing a module that starts a server on import.
+ *
+ * The name says operator rather than user because in this codebase "user" is
+ * the SSH account a command runs as. This is about whoever started the server.
+ *
+ * Scope: any throw reachable from `main()` before the transport connects should
+ * be an OperatorError, and `reportFatal` is the only reader of that promise.
+ * `getProfile` also throws one for a profile name that does not exist, which a
+ * tool call can trigger at request time — there the message reaches the client
+ * through the MCP error rather than through `reportFatal`, and the wording is
+ * written for the same audience either way.
+ */
+export class OperatorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OperatorError';
+    }
+}
+/**
+ * No config file at the path we looked in.
+ *
+ * Separated from every other config failure because it is the one case that is
+ * not necessarily a problem: with no config file, `--host`/`--user` take over.
+ * `buildAppConfig` expressed that with a bare `catch {}`, which also swallowed
+ * "the file is there and unusable" — a malformed TOML, a schema violation, a
+ * permission failure — and reported all of them as "No config file found".
+ *
+ * That is what made #138 unfindable. A Windows operator with a valid config in
+ * the right place was told the file did not exist, while the real error (a
+ * permission check that cannot pass on Windows) was discarded unread.
+ *
+ * The type is the signal rather than the message text, so the fall-through
+ * cannot be widened by an unrelated edit to the wording.
+ */
+export class ConfigNotFoundError extends OperatorError {
+    configPath;
+    /**
+     * Kept because `loadConfig(customPath)` used to reject with Node's own
+     * SystemError for a missing file, and `.code` was observable on it. Nothing
+     * in this repo reads it, but a wrapper script plausibly might, and preserving
+     * it costs one line.
+     */
+    code = 'ENOENT';
+    constructor(configPath) {
+        super(`No config file found at ${configPath}. Create one or use --config <path>. ` +
+            'See documentation for the TOML schema.');
+        this.configPath = configPath;
+        this.name = 'ConfigNotFoundError';
+    }
+}
+/** Exit status for an operator error, so a supervisor can tell it from a crash. */
+export const EXIT_OPERATOR_ERROR = 2;
+/** Exit status for anything else. */
+export const EXIT_DEFECT = 1;
+/**
+ * How a failure reaches the operator.
+ *
+ * An OperatorError is about how the server was invoked or configured, so its
+ * message is the whole answer. Anything else keeps the stack, because for a
+ * real defect the stack is the part worth having — which also makes the stack a
+ * signal: present means "this is ours, report it".
+ *
+ * Returns the exit status rather than calling `process.exit`, so the two halves
+ * of the rule stay testable without spawning a process.
+ */
+export function reportFatal(error, log = writeStderr) {
+    if (error instanceof OperatorError) {
+        log(error.message);
+        return EXIT_OPERATOR_ERROR;
+    }
+    log('Fatal error:', error);
+    return EXIT_DEFECT;
+}
+/**
+ * The default sink: a synchronous write to fd 2.
+ *
+ * Not `console.error`, because the caller calls `process.exit` on the next line.
+ * Node's writes to stderr are synchronous for files, and for pipes on Linux and
+ * Windows — but **asynchronous for pipes on macOS**, and under the stdio
+ * transport stderr *is* a pipe owned by the MCP client. So on macOS the message
+ * this whole change exists to deliver could be queued and then truncated by the
+ * exit, leaving the operator with a disconnect and an exit status. CI runs on
+ * Linux, where the pipe is synchronous, so no test would have caught it.
+ */
+function writeStderr(...args) {
+    let line = '';
+    try {
+        // Inside the try: `util.inspect` does not catch a throwing
+        // `[util.inspect.custom]`, so formatting could throw while reporting a throw, which
+        // escaped main()'s catch as an unhandled rejection and printed nothing at all.
+        line = args.map((a) => (typeof a === 'string' ? a : inspect(a))).join(' ');
+        writeSync(2, `${line}\n`);
+    }
+    catch {
+        // EAGAIN on a non-blocking pipe, or a closed fd. Better a lost line than an
+        // exception thrown while reporting an exception.
+        console.error(line || `Fatal error: <unprintable ${typeof args[args.length - 1]}>`);
+    }
+}

package/build/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { loadConfig } from './config/loader.js';
+import { loadConfig, getConfigPath } from './config/loader.js';
+import { OperatorError, ConfigNotFoundError, reportFatal } from './errors.js';
 import { ConnectionRegistry } from './ssh/connection-registry.js';
 import { PolicyEngine, HOST_GROUPS, resolvePolicyRules } from './policy/engine.js';
 import { AuditStore } from './audit/store.js';
@@ -59,7 +60,7 @@ function checkRemovedFlags(argv) {
     const found = Object.keys(REMOVED_V1_FLAGS).filter((f) => f in argv);
     if (found.length === 0)
         return;
-    throw new Error('These flags were removed in v2:\n' +
+    throw new OperatorError('These flags were removed in v2:\n' +
         found.map((f) => `  --${f}: ${REMOVED_V1_FLAGS[f]}`).join('\n') +
         '\nSee the "Migrating from v1" section of the README.');
 }
@@ -90,7 +91,7 @@ function resolveHostKeyMode(argv) {
         return 'tofu';
     if (mode === 'tofu' || mode === 'strict' || mode === 'insecure')
         return mode;
-    throw new Error(`Invalid --hostKeyMode=${mode}. Expected one of: tofu, strict, insecure.`);
+    throw new OperatorError(`Invalid --hostKeyMode=${mode}. Expected one of: tofu, strict, insecure.`);
 }
 /**
  * Which policy tier a CLI-configured host belongs to.
@@ -111,21 +112,72 @@ export function resolveHostGroup(argv) {
         return group;
     // Falling through would silently apply the prod bindings to a typo, and the
     // operator would read the refusal as policy rather than as their own slip.
-    throw new Error(`Invalid --group=${group}. Expected one of: ${HOST_GROUPS.join(', ')}.`);
+    throw new OperatorError(`Invalid --group=${group}. Expected one of: ${HOST_GROUPS.join(', ')}.`);
 }
+/**
+ * ACL checks that could not be performed, in the order they happened.
+ *
+ * Collected rather than only printed so `main()` can act on them once there is somewhere
+ * durable to put them; see the note at the sink below.
+ */
+const unverified = [];
 async function buildAppConfig(argv) {
-    if (argv.config) {
-        return loadConfig(argv.config);
+    // The way past an ACL that could not be read, rather than an operator with no
+    // exit. See assertPrivateOnWindows.
+    // The sink is supplied here rather than left to the module's default, which is the
+    // point of having one: "this security check did not run" is a decision about what the
+    // operator must be told, and the loader is not the layer that owns that. Routing it to
+    // the audit store as well needs an AuditRecord variant for a startup event — that type
+    // is hash-chained and tamper-evident, so it is its own change, and it is queued.
+    const aclOpts = {
+        allowUnchecked: flagEnabled(argv, 'allowUncheckedConfigAcl'),
+        onUnverified: (e) => {
+            unverified.push(e);
+            console.error(`Warning: the ACL of ${e.path} was not checked (${e.reason}: ${e.detail}), so ` +
+                'whether other accounts can read your config is unverified. Loading it anyway.');
+        },
+    };
+    if (argv.config !== undefined) {
+        // `parseArgv` stores null for a flag written without `=`, so a bare `--config` used to
+        // be falsy here and fall into the default-path branch — which now refuses rather than
+        // silently ignoring an unusable file, so the operator got a refusal naming a path they
+        // never asked for.
+        if (argv.config === null || argv.config === '') {
+            throw new OperatorError('--config needs a path: --config=<path>');
+        }
+        return loadConfig(argv.config, aclOpts);
     }
     try {
-        return await loadConfig();
+        const fromFile = await loadConfig(undefined, aclOpts);
+        // Before #138 every Windows config was rejected by the mode-bit check and
+        // the rejection was swallowed, so an operator who also passed --host/--user
+        // was silently running off the flags. Now that the file loads, it takes
+        // precedence — a flip worth one line rather than a surprise about which host
+        // a command reached.
+        if (argv.host || argv.user) {
+            console.error(`Note: ${getConfigPath()} was loaded, so --host/--user are ignored. ` +
+                'Pass --config <path> to choose a different file.');
+        }
+        return fromFile;
     }
-    catch {
-        // No config file — fall through to CLI args
+    catch (err) {
+        // Only "there is no file" means fall through. A file that exists and is
+        // unusable — malformed TOML, a schema violation, a permission failure —
+        // used to be swallowed here too and reported as a missing config, which is
+        // how #138 stayed unfindable: the operator's file was in the right place,
+        // and the real error was discarded before anyone could read it.
+        //
+        // Falling through would also be wrong on its own terms whenever
+        // --host/--user happen to be present: the server would start, silently
+        // ignoring every profile, policy and role binding the operator wrote.
+        if (!(err instanceof ConfigNotFoundError))
+            throw err;
     }
     if (!argv.host || !argv.user) {
-        throw new Error('No config file found and missing required --host/--user.\n' +
-            'Either create a config file at ~/.config/ssh-mcp/config.toml or pass --config <path>.\n' +
+        throw new OperatorError('No config file found and missing required --host/--user.\n' +
+            // Was hardcoded to ~/.config/ssh-mcp/config.toml on every platform, so on
+            // Windows and macOS it named a path this code never reads.
+            `Either create a config file at ${getConfigPath()} or pass --config <path>.\n` +
             'For quick start: --host=<host> --user=<user> (credentials via env vars).');
     }
     const defaults = {
@@ -259,8 +311,7 @@ const isTestMode = process.env.SSH_MCP_TEST === '1';
 const isCliEnabled = process.env.SSH_MCP_DISABLE_MAIN !== '1';
 if (isCliEnabled || isTestMode) {
     main().catch((error) => {
-        console.error('Fatal error:', error);
-        process.exit(1);
+        process.exit(reportFatal(error));
     });
 }
 export { parseArgv, buildAppConfig, checkRemovedFlags, parseMaxChars, flagEnabled, resolveHostKeyMode };

package/build/policy/engine.js

@@ -1,4 +1,5 @@
 import { classifyCommand, findForbiddenMatch } from './classifier.js';
+import { OperatorError } from '../errors.js';
 /** Tiers, most restrictive first. Unknown/unset tiers resolve to the first. */
 export const HOST_GROUPS = ['prod', 'staging', 'dev'];
 export const DEFAULT_RULES = {
@@ -152,7 +153,7 @@ export function resolvePolicyRules(profiles, override) {
     const merged = mergePolicyRules(DEFAULT_RULES, override);
     const problems = findPolicyProblems(merged, profiles, override);
     if (problems.length > 0) {
-        throw new Error('Policy configuration error:\n' +
+        throw new OperatorError('Policy configuration error:\n' +
             problems.map((p) => `  ${p}`).join('\n') +
             '\nSee the "Configuring the matrix" section of the README.');
     }
@@ -175,7 +176,7 @@ export class PolicyEngine {
                 return new RegExp(pattern);
             }
             catch (err) {
-                throw new Error(`Invalid denylist pattern ${JSON.stringify(pattern)}: ${err instanceof Error ? err.message : String(err)}`);
+                throw new OperatorError(`Invalid denylist pattern ${JSON.stringify(pattern)}: ${err instanceof Error ? err.message : String(err)}`);
             }
         });
     }

package/build/ssh/host-key.js

@@ -1,4 +1,5 @@
 import { createHash } from 'crypto';
+import { OperatorError } from '../errors.js';
 export function fingerprintPublicKey(key) {
     const hash = createHash('sha256').update(key).digest('base64');
     // `={0,2}` rather than `=+`: base64 padding is never longer than two
@@ -17,7 +18,7 @@ export function verifyHostKey(host, port, fingerprint, knownHosts, mode) {
             // Two very different things produce this, and the message has to let the
             // reader tell them apart — otherwise the reflex is --insecureHostKey,
             // which turns the check off for every host rather than for this one.
-            throw new Error(`HOST_KEY_MISMATCH: the key presented by ${host}:${port} is not the one seen before.\n` +
+            throw new OperatorError(`HOST_KEY_MISMATCH: the key presented by ${host}:${port} is not the one seen before.\n` +
                 `  expected ${stored}\n` +
                 `  received ${fingerprint}\n` +
                 'Either the server was rebuilt, reinstalled or had its address reused — in which case the new key is ' +
@@ -31,7 +32,7 @@ export function verifyHostKey(host, port, fingerprint, knownHosts, mode) {
         return true;
     }
     if (mode === 'strict') {
-        throw new Error(`HOST_KEY_UNKNOWN: No known key for ${host}:${port} and --hostKeyMode=strict is set. ` +
+        throw new OperatorError(`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);

package/build/transport/http.js

@@ -3,6 +3,7 @@ import { randomUUID, timingSafeEqual } from 'crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { SERVER_VERSION } from '../version.js';
+import { OperatorError } from '../errors.js';
 const MAX_BODY_SIZE = 1_048_576; // 1MB
 /** Cap on concurrent MCP sessions, so unauthenticated-adjacent churn can't grow the map without bound. */
 const MAX_SESSIONS = 64;
@@ -45,7 +46,7 @@ function jsonRpcError(res, status, code, message) {
 export async function startHttpServer(createMcpServer, opts) {
     const { port, host = '127.0.0.1', bearerToken, registry } = opts;
     if (!bearerToken) {
-        throw new Error('HTTP transport requires --bearerToken. Example: --transport=http --bearerToken=secret\n' +
+        throw new OperatorError('HTTP transport requires --bearerToken. Example: --transport=http --bearerToken=secret\n' +
             'Without authentication, any network client can execute SSH commands on your hosts.');
     }
     const rateLimiter = opts.rateLimit && opts.rateLimit > 0
@@ -221,9 +222,14 @@ export async function startHttpServer(createMcpServer, opts) {
     // immediately regardless, so the caller carried on as if the server was up.
     await new Promise((resolve, reject) => {
         httpServer.once('error', (err) => {
-            reject(err.code === 'EADDRINUSE'
-                ? new Error(`Cannot bind ${host}:${port} — address already in use.`)
-                : err);
+            // OperatorError, not Error: every listen failure at this point is about how the
+            // server was invoked — a port already taken, a privileged port, a mistyped
+            // --httpHost. Leaving them on the defect path printed a stack and exited 1, which
+            // under this codebase's rule invites the operator to report their own port choice
+            // as a bug.
+            reject(new OperatorError(err.code === 'EADDRINUSE'
+                ? `Cannot bind ${host}:${port} — address already in use.`
+                : `Cannot bind ${host}:${port}: ${err.message}`));
         });
         httpServer.listen(port, host, () => {
             console.error(`SSH MCP Server v2 (HTTP) listening on http://${host}:${port}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.2.6",
+  "version": "2.3.0",
   "description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "test:integration": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run test/integration/",
     "test:watch": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest",
     "coverage": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run --coverage",
+    "coverage:unit": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run --coverage test/unit/ test/property/",
     "test:e2e": "npm run build && cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run test/e2e/"
   },
   "files": [