ssh-mcp 2.7.0 → 2.8.0

package/README.md

@@ -714,8 +714,8 @@ Secrets are **never** passed as CLI arguments.
 | `--trustProxy` | false | Read the client address from `X-Forwarded-For`, but only when the peer is the proxy — bare means a loopback peer |
 | `--trustedProxies` | — | Comma-separated peer addresses allowed to send `X-Forwarded-For`. Empty means loopback only |
 | `--allowedHosts` | bind address + localhost | Comma-separated Host headers accepted by the DNS-rebinding guard |
-| `--hostKeyMode` | `tofu` | `tofu \| strict \| insecure`. See [SECURITY.md](./SECURITY.md#host-key-trust-does-not-survive-a-restart) — `strict` currently refuses every host |
-| `--insecureHostKey` | false | Disable host key verification (test only!) |
+| `--hostKeyMode` | `tofu` | `tofu \| strict \| insecure`. `strict` accepts only hosts pinned with `trustedHostKey`. See [SECURITY.md](./SECURITY.md#host-key-trust-does-not-survive-a-restart) |
+| `--insecureHostKey` | false | Disable host key verification for hosts with no `trustedHostKey` — a pin still refuses (test only!) |
 | `--allowUncheckedConfigAcl` | false | Windows: report every ACL finding and refuse none |
 | `--strictConfigAcl` | false | Windows: refuse on every ACL finding, including a read-only over-grant |
 | `--disableApproval` | false | Skip the approval gate (quick start profile only) |
@@ -788,7 +788,8 @@ process fails the connection. Nothing is written to disk and `~/.ssh/known_hosts
 is not consulted, so a restart accepts afresh — see
 [SECURITY.md](./SECURITY.md#host-key-trust-does-not-survive-a-restart). Pin
 explicitly with `trustedHostKey` in a profile, which is the only control here that
-survives a restart, or pass `--insecureHostKey` to opt out (test environments only).
+survives a restart — and which no host key mode overrides, so `--insecureHostKey`
+is an opt-out only for hosts you have not pinned (test environments only).
 
 ---
 

package/build/config/schema.js

@@ -115,7 +115,15 @@ export const profileSchema = z.object({
     // profile name, and an unrecognised name resolves to the strictest tier.
     group: z.string().optional(),
     workdir: z.string().optional(),
-    trustedHostKey: z.string().optional(),
+    // `.trim().min(1)` rather than a bare string. `trustedHostKey = ""` passed
+    // validation and then did nothing: the old gate in connection.ts tested it for
+    // truthiness, so an empty pin was silently inert and the operator who wrote the
+    // line believed they were pinned. A blank pin is always a mistake, and a loud
+    // one at startup beats a profile that quietly verifies nothing. The trim is for
+    // the same reason in the other direction — the comparison against a fingerprint
+    // is exact, so a trailing newline from a heredoc or an editor refused every
+    // key with no hint as to why.
+    trustedHostKey: z.string().trim().min(1, 'trustedHostKey cannot be empty').optional(),
     tty: z.boolean().default(false),
     role: z.string().default('operator'),
     readOnly: z.boolean().default(false),

package/build/ssh/connection.js

@@ -161,11 +161,13 @@ export class SSHConnection {
                 username: this.profile.user,
                 algorithms: FROZEN_ALGORITHMS,
                 hostVerifier: (key) => {
-                    const fp = fingerprintPublicKey(key);
-                    if (this.profile.trustedHostKey && fp !== this.profile.trustedHostKey) {
-                        return false;
-                    }
-                    return verifyHostKey(this.profile.host, this.profile.port, fp, this.knownHostsStore, this.hostKeyMode);
+                    // The pin used to be checked here, as a `return false` ahead of
+                    // verifyHostKey. That made it reject-only: a *matching* pin fell
+                    // through and was refused anyway under `strict`, whose store can never
+                    // be populated. Passing it in puts one function in charge of the whole
+                    // decision, and `return false` gave ssh2 a generic handshake failure
+                    // where verifyHostKey raises a message that names what decided.
+                    return verifyHostKey(this.profile.host, this.profile.port, fingerprintPublicKey(key), this.knownHostsStore, this.hostKeyMode, this.profile.trustedHostKey);
                 },
                 readyTimeout: 20000,
                 keepaliveInterval: 15000,

package/build/ssh/host-key.js

@@ -1,5 +1,11 @@
 import { createHash } from 'crypto';
 import { OperatorError } from '../errors.js';
+/**
+ * Shared as a literal, not through a message builder: the three refusals below
+ * diverge in their advice, and message-quality.test.ts asserts each one's wording
+ * separately. Only the command is common, and only it should be.
+ */
+const CONFIRM_OUT_OF_BAND = '`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` on the server';
 export function fingerprintPublicKey(key) {
     const hash = createHash('sha256').update(key).digest('base64');
     // `={0,2}` rather than `=+`: base64 padding is never longer than two
@@ -8,10 +14,65 @@ export function fingerprintPublicKey(key) {
     // quantifier is the shape worth not copying elsewhere.
     return `SHA256:${hash.replace(/={0,2}$/, '')}`;
 }
-export function verifyHostKey(host, port, fingerprint, knownHosts, mode) {
+/**
+ * Decide whether to accept the key a host just presented.
+ *
+ * `knownHosts` is one Map shared by every profile (connection-registry.ts), which
+ * is why a pin never *reads* it: consulting it for a pinned host would make two
+ * profiles pinning different keys for one host:port collide with a false
+ * HOST_KEY_MISMATCH, once the host presents each its own key.
+ *
+ * Why `--hostKeyMode=strict` refused every host before 2.8.0 is in
+ * .changeset/lucky-keys-pinned.md and SECURITY.md; the branch order here is what
+ * that history left behind.
+ *
+ * @param pinnedFingerprint `trustedHostKey` from the profile. Falsy means no pin.
+ *   A value decides the outcome in every mode, `insecure` included. It is never
+ *   compared against `knownHosts`, but a match does record into it under `tofu` —
+ *   see the pin branch for why those two differ.
+ */
+export function verifyHostKey(host, port, fingerprint, knownHosts, mode, pinnedFingerprint) {
+    const key = `${host}:${port}`;
+    // Before `insecure`, not after: the gate this replaced sat ahead of
+    // verifyHostKey in connection.ts, so a key contradicting the pin was refused in
+    // every mode, `insecure` included. Pinned by host-key.test.ts, "refuses a key
+    // that contradicts the pin, in every mode including insecure".
+    //
+    // Truthiness, not `!== undefined`: `trustedHostKey = ""` was inert on 2.7.0
+    // because that gate tested truthiness, and `!== undefined` would turn the same
+    // config into "refuse every host". The schema rejects a blank pin, so this is
+    // defence in depth rather than the primary guard.
+    if (pinnedFingerprint) {
+        if (pinnedFingerprint !== fingerprint) {
+            // No "or turn the check off" exit here, unlike the two refusals below.
+            // Nothing overrides a pin — not tofu, not insecure — so offering a mode
+            // would describe a way out that does not exist.
+            throw new OperatorError(`HOST_KEY_PIN_MISMATCH: the key presented by ${host}:${port} is not the pinned key.\n` +
+                `  pinned   ${pinnedFingerprint}\n` +
+                `  received ${fingerprint}\n` +
+                'trustedHostKey on this profile is what decided, and no host key mode overrides it. ' +
+                'Either the pin is stale — the server was rebuilt or its address reused, in which case ' +
+                `confirm the new fingerprint out of band (${CONFIRM_OUT_OF_BAND}) ` +
+                'and update trustedHostKey — or something is intercepting this connection, ' +
+                'which is what pinning exists to catch.');
+        }
+        // Matched. Two constraints on the write, neither derivable from the code:
+        //
+        // `tofu` only — under `strict` the store is the only thing that admits an
+        // *unpinned* profile, so seeding it there would let one profile's pin authorise
+        // another. Fill-only — an unconditional set makes the entry order-dependent for
+        // an unpinned sibling, and 2.7.0's write was reachable only on a store miss, so
+        // this writes exactly when that one would have.
+        //
+        // And it is inside the match, below the throw: recording on the refusal path
+        // would put an interceptor's fingerprint into the shared store, which is the
+        // failure the write exists to prevent.
+        if (mode === 'tofu' && !knownHosts.has(key))
+            knownHosts.set(key, fingerprint);
+        return true;
+    }
     if (mode === 'insecure')
         return true;
-    const key = `${host}:${port}`;
     const stored = knownHosts.get(key);
     if (stored) {
         if (stored !== fingerprint) {
@@ -24,7 +85,7 @@ export function verifyHostKey(host, port, fingerprint, knownHosts, mode) {
                 'Either the server was rebuilt, reinstalled or had its address reused — in which case the new key is ' +
                 'genuine — or something is intercepting this connection, which is what this check exists to catch. ' +
                 'Nothing here can tell those apart; confirm the fingerprint out of band, from the host itself ' +
-                '(`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` on the server) or from whoever rebuilt it.\n' +
+                `(${CONFIRM_OUT_OF_BAND}) or from whoever rebuilt it.\n` +
                 'If it matches, pin it with trustedHostKey on the profile. Do not reach for --insecureHostKey to get ' +
                 'past this: it disables verification for every host and every future connection, including the case ' +
                 'this message is warning you about.');

package/package.json

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