ssh-mcp 2.3.3 → 2.4.0

package/build/index.js

@@ -1,222 +1,14 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { loadConfig, getConfigPath } from './config/loader.js';
-import { OperatorError, ConfigNotFoundError, reportFatal } from './errors.js';
+import { reportFatal } from './errors.js';
 import { ConnectionRegistry } from './ssh/connection-registry.js';
-import { PolicyEngine, HOST_GROUPS, resolvePolicyRules } from './policy/engine.js';
+import { PolicyEngine, resolvePolicyRules } from './policy/engine.js';
 import { AuditStore } from './audit/store.js';
 import { registerTools, registerResources, getToolHashes } from './tools/registry.js';
 import { initKeychain } from './config/credential-resolver.js';
 import { SERVER_VERSION } from './version.js';
-function parseArgv() {
-    const args = process.argv.slice(2);
-    const config = {};
-    for (const arg of args) {
-        if (arg.startsWith('--')) {
-            const eq = arg.indexOf('=');
-            if (eq === -1) {
-                config[arg.slice(2)] = null;
-            }
-            else {
-                config[arg.slice(2, eq)] = arg.slice(eq + 1);
-            }
-        }
-    }
-    return config;
-}
-/**
- * Whether a boolean flag was passed at all.
- *
- * `parseArgv` stores `null` for a flag written without `=`, which is how every
- * documented boolean flag is written. Testing that value for truthiness makes
- * the flag a no-op: `--disableApproval`, `--auditEntropyScan` and
- * `--auditTamperEvident` all did nothing unless spelled `--flag=1`, which
- * nothing documents (#91). The two call sites that got it right already used
- * `!== undefined`; this gives the check a name so the next one cannot miss it.
- *
- * `--flag=false` and `--flag=0` turn it off, because a flag that cannot be
- * turned off once written into a wrapper script is its own annoyance.
- */
-function flagEnabled(argv, name) {
-    if (!(name in argv))
-        return false;
-    const value = argv[name];
-    if (value === null || value === '')
-        return true;
-    return !['false', '0', 'no', 'off'].includes(value.toLowerCase());
-}
-/**
- * v1 flags that v2 removed. Silently ignoring them means the user only finds
- * out at the first command, as an auth failure with no hint about the cause.
- */
-const REMOVED_V1_FLAGS = {
-    password: 'Use the SSH_MCP_PASSWORD env var (or a per-profile SSH_MCP_<PROFILE>_PASSWORD).',
-    suPassword: 'Use the SSH_MCP_SUDO_PASSWORD env var.',
-    sudoPassword: 'Use the SSH_MCP_SUDO_PASSWORD env var.',
-    disableSudo: 'Sudo is now a separate tool; restrict it with a role/policy that disallows the "privileged" class.',
-};
-function checkRemovedFlags(argv) {
-    const found = Object.keys(REMOVED_V1_FLAGS).filter((f) => f in argv);
-    if (found.length === 0)
-        return;
-    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.');
-}
-/**
- * v1 documented `--maxChars=none` (and 0/negative) as "no limit". Parsing it
- * with `parseInt(...) || 5000` silently turned that into a 5000-char cap.
- */
-function parseMaxChars(raw) {
-    if (typeof raw !== 'string' || raw === '')
-        return 5_000;
-    if (raw.toLowerCase() === 'none')
-        return Number.MAX_SAFE_INTEGER;
-    const parsed = parseInt(raw);
-    if (isNaN(parsed))
-        return 5_000;
-    return parsed <= 0 ? Number.MAX_SAFE_INTEGER : parsed;
-}
-/**
- * `strict` was previously unreachable: nothing but test code could select it,
- * yet host-key.ts pointed users at a `--acceptNewHostKey` flag that never
- * existed. `--insecureHostKey` is kept as an alias for the documented flag.
- */
-function resolveHostKeyMode(argv) {
-    if (flagEnabled(argv, 'insecureHostKey'))
-        return 'insecure';
-    const mode = argv.hostKeyMode;
-    if (mode === null || mode === undefined)
-        return 'tofu';
-    if (mode === 'tofu' || mode === 'strict' || mode === 'insecure')
-        return mode;
-    throw new OperatorError(`Invalid --hostKeyMode=${mode}. Expected one of: tofu, strict, insecure.`);
-}
-/**
- * Which policy tier a CLI-configured host belongs to.
- *
- * Without this there was no way to say it from the command line at all. The
- * inline profile carries no group, so it fell to the strictest tier, where the
- * `admin` role has no `privileged` — meaning `sudo` could never run for anyone
- * who had not written a config file (#91).
- *
- * The default stays `prod`. Guessing an unknown host is production is the safe
- * direction; what was missing was a way to correct the guess.
- */
-export function resolveHostGroup(argv) {
-    const group = argv.group;
-    if (group === null || group === undefined)
-        return 'prod';
-    if (HOST_GROUPS.includes(group))
-        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 OperatorError(`Invalid --group=${group}. Expected one of: ${HOST_GROUPS.join(', ')}.`);
-}
-/**
- * Every ACL finding, in the order it happened — both "readable beyond its owner" and
- * "could not be checked".
- *
- * 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 aclFindings = [];
-async function buildAppConfig(argv) {
-    // 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 = {
-        enforce: flagEnabled(argv, 'strictConfigAcl'),
-        allowUnchecked: flagEnabled(argv, 'allowUncheckedConfigAcl'),
-        onFinding: (f) => {
-            aclFindings.push(f);
-            console.error(`Warning: ${f.message}`);
-        },
-    };
-    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 {
-        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 (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 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 = {
-        sessionMaxPerConnection: parseInt(argv.sessionMax) || 5,
-        sessionIdleTimeoutMs: parseInt(argv.sessionTtl) || 600_000,
-        sessionBackgroundMaxMs: 3_600_000,
-        commandTimeoutMs: parseInt(argv.timeout) || 60_000,
-        commandMaxChars: parseMaxChars(argv.maxChars),
-        commandMaxOutputBytes: 1_048_576,
-        connectionIdleReapMs: 900_000,
-        commandQuotaPerDay: parseInt(argv.commandQuota) || 0,
-        approvalGrantTtlMs: parseInt(argv.approvalGrantTtl) || 0,
-        approvalMode: 'ask-destructive',
-    };
-    const profile = {
-        name: 'default',
-        host: argv.host,
-        port: parseInt(argv.port) || 22,
-        user: argv.user,
-        auth: argv.key ? 'key' : 'password',
-        keyRef: argv.key || undefined,
-        workdir: argv.workdir || undefined,
-        tty: false,
-        timeout: defaults.commandTimeoutMs,
-        maxChars: defaults.commandMaxChars,
-        maxOutputBytes: defaults.commandMaxOutputBytes,
-        role: 'admin',
-        group: resolveHostGroup(argv),
-        readOnly: false,
-        approvalPolicy: flagEnabled(argv, 'disableApproval') ? 'auto' : defaults.approvalMode,
-        cert: false,
-        sessionMaxPerConnection: defaults.sessionMaxPerConnection,
-        sessionIdleTimeoutMs: defaults.sessionIdleTimeoutMs,
-        sessionBackgroundMaxMs: defaults.sessionBackgroundMaxMs,
-        commandQuotaPerDay: defaults.commandQuotaPerDay,
-    };
-    return { defaults, profiles: [profile] };
-}
+import { parseArgv, buildAppConfig, checkRemovedFlags, flagEnabled, resolveHostKeyMode, } from './cli.js';
 async function main() {
     const argv = parseArgv();
     checkRemovedFlags(argv);
@@ -342,4 +134,3 @@ if (isCliEnabled || isTestMode) {
         process.exit(reportFatal(error));
     });
 }
-export { parseArgv, buildAppConfig, checkRemovedFlags, parseMaxChars, flagEnabled, resolveHostKeyMode };

package/build/ssh/connection-registry.js

@@ -1,4 +1,5 @@
-import { getProfile as getConfigProfile } from '../config/loader.js';
+import { getProfile as getConfigProfile, getConfigPath } from '../config/loader.js';
+import { UnconfiguredError } from '../errors.js';
 import { resolveCredentials } from '../config/credential-resolver.js';
 import { SSHConnection } from './connection.js';
 export class ConnectionRegistry {
@@ -69,7 +70,25 @@ export class ConnectionRegistry {
         const profile = this.getProfile(profileName);
         return this.connections.get(profile.name);
     }
+    /**
+     * Refuse everything while nothing is configured.
+     *
+     * The server now starts with `profiles: []` so a directory or a client's "add server"
+     * flow can read `tools/list` (see cli.ts). This is where that state stops being
+     * readable and starts being refused, and it sits here rather than in the loader's
+     * `getProfile` for one measured reason: the loader's empty check can only live in the
+     * no-profile-named branch, so a client calling `run-command` with `profile: "prod"`
+     * against an unconfigured server got `Profile "prod" not found` — a message telling the
+     * operator they mistyped a name when in fact they have no config at all, and omitting
+     * the config path this whole change exists to deliver. Checking before the lookup
+     * covers both.
+     */
+    assertConfigured() {
+        if (this.config.profiles.length === 0)
+            throw new UnconfiguredError(getConfigPath());
+    }
     getProfile(profileName) {
+        this.assertConfigured();
         return getConfigProfile(this.config, profileName);
     }
     listConnections() {

package/build/tools/command-tools.js

@@ -42,7 +42,6 @@ export function registerCommandTools({ server, registry, policy }, pipeline) {
         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',
@@ -51,7 +50,11 @@ export function registerCommandTools({ server, registry, policy }, pipeline) {
             // 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');
+                // Resolved here rather than before `runAudited`: `defaultProfileName` reaches
+                // `registry.getProfile()`, which refuses on an unconfigured server, and outside
+                // the pipeline's try that refusal escaped without an audit record. `preCheck`
+                // runs inside it.
+                const rawEval = policy.evaluate(cleanCmd, registry.getProfile(defaultProfileName(profile)), 'privileged-command');
                 if (rawEval.decision === 'deny') {
                     throw new PolicyRefusedError(`POLICY_DENIED: ${rawEval.reason || 'Command not allowed'}`, rawEval);
                 }

package/build/tools/pipeline.js

@@ -75,7 +75,12 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
         await audit.record({
             mcpRequestId: ctx.requestId,
             profile: profileName,
-            user: registry.getProfile(profileName).user,
+            // Looked up without throwing. This used to be `registry.getProfile(profileName).user`,
+            // which throws for exactly the reason the tool call is being audited as a failure —
+            // an unconfigured server, or a profile name that does not exist — and `auditFailure`
+            // swallows that by design. The record the operator most needs was the one record that
+            // could not be written.
+            user: profileUser(profileName),
             command,
             commandClass: evaluation.commandClass,
             binary: evaluation.binary,
@@ -113,6 +118,10 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
     function defaultProfileName(profile) {
         return profile || registry.getProfile().name;
     }
+    /** The profile's SSH user, or a placeholder — never throws, so an audit write cannot fail. */
+    function profileUser(profileName) {
+        return registry.listAllProfiles().find((p) => p.name === profileName)?.user ?? '(unresolved)';
+    }
     function makeProgressSender(extra) {
         const token = extra?._meta?.progressToken;
         if (token === undefined)
@@ -135,15 +144,21 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
      */
     async function runAudited(command, opts, run) {
         const ctx = makeCtx(opts.extra, opts.profile, opts.session);
-        const profileName = defaultProfileName(opts.profile);
-        const profile = registry.getProfile(profileName);
         const onProgress = makeProgressSender(opts.extra);
         const abortSignal = opts.extra?.signal;
-        // Sanitization runs inside the try so a rejected (empty, control-char-only,
-        // over-length) command still leaves an audit trail — a client probing with
-        // malformed payloads used to leave none.
+        // Named before the try because `auditFailure` needs something to file the record
+        // under even when resolution itself is what failed. Reassigned to the resolved name as
+        // the first statement inside, so the quota key and the audit record are unchanged on
+        // every path that gets that far.
+        let profileName = opts.profile ?? '(default)';
+        // Profile resolution and sanitization both run inside the try, so a rejected call
+        // still leaves an audit trail — a client probing with malformed payloads, or probing
+        // a server that has no config at all, used to leave none. The unconfigured refusal
+        // reaches this the same way a bad command does.
         const state = { command };
         try {
+            profileName = defaultProfileName(opts.profile);
+            const profile = registry.getProfile(profileName);
             let effective = opts.synthetic ? command : sanitizeCommand(command, profile.maxChars);
             state.command = effective;
             opts.preCheck?.(effective);

package/build/tools/session-tools.js

@@ -38,6 +38,14 @@ export function registerSessionTools({ server, registry }, pipeline) {
     const { runAudited, resolveConn, auditResult, auditFailure, makeCtx, defaultProfileName } = pipeline;
     // ─── list-connections ──────────────────────────────────────────────────
     server.tool('list-connections', D["list-connections"], {}, { readOnlyHint: true }, async () => {
+        // The one tool that reads only `listAllProfiles()` and so never touches
+        // `getProfile`. Without this it answered an unconfigured server with a
+        // zero-length success — on the tool whose own description sends an agent here
+        // 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.
+        registry.assertConfigured();
         const connections = registry.listConnections();
         const profiles = registry.listAllProfiles();
         const lines = profiles.map((p) => {
@@ -104,19 +112,27 @@ export function registerSessionTools({ server, registry }, pipeline) {
         profile: z.string().optional().describe('Profile name'),
     }, { destructiveHint: true }, async ({ name, profile }, extra) => {
         const cleanName = sanitizeSessionName(name);
-        const profileName = defaultProfileName(profile);
+        // Both the profile name and the connection are resolved inside the try below. They
+        // used to be resolved above it, so a refusal — an unconfigured server, an unknown
+        // profile name — escaped before `auditFailure` could record that a release was
+        // attempted. The placeholders are what the record is filed under if resolution is
+        // itself what failed.
+        let profileName = profile ?? '(default)';
         const ctx = makeCtx(extra, profileName, cleanName);
-        const conn = await resolveConn(profile);
-        // Recorded with the session's kind, so a remote SIGKILL is greppable in the log and
-        // distinguishable from ending a local shell — `open-session` encodes its type the
-        // same way.
-        // Through `toInfo()` rather than an `instanceof` check: the type is public API, and a
-        // tool handler reaching for a constructor identity is the layer leak this repo's own
-        // rules call out.
-        const kind = conn.getSession(cleanName)?.toInfo().type ?? 'unknown';
-        const command = `session:close ${kind} ${cleanName}`;
+        let command = `session:close unknown ${cleanName}`;
         const startedAt = Date.now();
         try {
+            profileName = defaultProfileName(profile);
+            ctx.profile = profileName;
+            const conn = await resolveConn(profile);
+            // Recorded with the session's kind, so a remote SIGKILL is greppable in the log and
+            // distinguishable from ending a local shell — `open-session` encodes its type the
+            // same way.
+            // Through `toInfo()` rather than an `instanceof` check: the type is public API, and a
+            // tool handler reaching for a constructor identity is the layer leak this repo's own
+            // rules call out.
+            const kind = conn.getSession(cleanName)?.toInfo().type ?? 'unknown';
+            command = `session:close ${kind} ${cleanName}`;
             const outcome = await conn.closeSession(cleanName);
             await auditResult(ctx, profileName, command, RELEASE, {
                 stdout: '',

package/build/transport/http.js

@@ -98,7 +98,8 @@ export async function startHttpServer(createMcpServer, opts) {
     const httpServer = createServer(async (req, res) => {
         const url = new URL(req.url || '/', `http://${req.headers.host}`);
         // Liveness probes are conventionally unauthenticated, and the README lists
-        // /health without an auth caveat. It exposes nothing beyond "process is up".
+        // /health without an auth caveat. It exposes "process is up" and whether any profile
+        // is configured — see the handler below for why that second bit is not a secret.
         const isHealthProbe = req.method === 'GET' && url.pathname === '/health';
         if (!isHealthProbe) {
             const auth = req.headers.authorization || '';
@@ -210,8 +211,18 @@ export async function startHttpServer(createMcpServer, opts) {
             return;
         }
         if (req.method === 'GET' && url.pathname === '/health') {
+            // `configured` is liveness telling the truth about readiness. Since the server
+            // learned to start with nothing configured, an HTTP deployment whose config bind
+            // mount silently did not attach comes up, binds the port, and fails 100% of tool
+            // calls — while this probe said `healthy: true` and the explaining stderr warning
+            // scrolled past at boot. The status stays 200 so an existing probe does not start
+            // failing on upgrade; the field is what an operator can alert on.
+            //
+            // It widens what this unauthenticated route discloses by exactly one bit, and that
+            // bit is worth little to anyone: a server with no profile is one that cannot reach
+            // any host. `/status` carries the profile list itself and stays behind the token.
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ healthy: true }));
+            res.end(JSON.stringify({ healthy: true, configured: registry.listAllProfiles().length > 0 }));
             return;
         }
         res.writeHead(404, { 'Content-Type': 'application/json' });

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.3.3",
+  "version": "2.4.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",
   "bin": {
     "ssh-mcp": "build/index.js"
@@ -13,7 +14,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.test.json",
     "inspect": "npx @modelcontextprotocol/inspector node build/index.js",
     "changeset": "changeset",
-    "version": "changeset version",
+    "version": "changeset version && node scripts/sync-server-json.mjs",
     "test": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run",
     "test:unit": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run test/unit/ test/property/",
     "test:integration": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run test/integration/",