ssh-mcp 2.6.0 → 2.8.0

package/README.md

@@ -487,7 +487,17 @@ When `--opaUrl` is set, commands the built-in engine allows are additionally
 evaluated by OPA. **OPA can only narrow.** A command the built-in engine has
 already denied returns that denial without OPA being consulted at all, so a
 sidecar answering `allow` cannot grant a class the role bindings withhold. To
-widen, edit `[policy]`. The request shape follows the AuthZEN Access Evaluation contract:
+widen, edit `[policy]`.
+
+An outage falls back to the local decision and logs one warning per minute. That is the
+default because OPA is an *additional* deny layer and stopping all work would be the worse
+failure — but an operator who deployed OPA *as* the authorization gate loses that gate
+during the outage, and the only signal is a stderr line MCP clients usually discard.
+`--opaFailClosed` makes the gate being down mean no; the refusal carries `ruleId:
+"opa-unavailable"` so the audit record says the gate was down rather than implying a policy
+refused the command.
+
+The request shape follows the AuthZEN Access Evaluation contract:
 
 ```json
 {
@@ -500,7 +510,7 @@ widen, edit `[policy]`. The request shape follows the AuthZEN Access Evaluation
 }
 ```
 
-OPA responds with `{ "result": true/false }`. If OPA denies (`result: false`), the command is blocked even if the built-in engine allows it. If OPA is unreachable, the built-in engine's decision stands (fail-open to avoid locking out access).
+OPA responds with `{ "result": true/false }`. If OPA denies (`result: false`), the command is blocked even if the built-in engine allows it. If OPA is unreachable, the built-in engine's decision stands by default (fail-open, to avoid locking out access); `--opaFailClosed` refuses instead. A 200 that carries no boolean `result` counts as unreachable — that is what OPA answers for an undefined document, so a misnamed package or an unactivated bundle is an outage rather than consent.
 
 Example Rego policy (`ssh-mcp.rego`):
 ```rego
@@ -618,6 +628,9 @@ ssh-mcp --transport=http --httpPort=3000 --bearerToken=secret --rateLimit=60
 | `--httpPort` | 3000 | HTTP listen port |
 | `--httpHost` | 127.0.0.1 | Bind address |
 | `--rateLimit` | 0 (off) | Max requests per minute (0 = unlimited) |
+| `--authFailureLimit` | 10 | Failed bearer-auth attempts allowed per client per minute (0 = off) |
+| `--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 |
 
 Endpoints: `POST /` (MCP Streamable HTTP), `GET /status`, `GET /health`
 
@@ -629,6 +642,25 @@ bearer token.
 
 When rate limit is exceeded, the server returns HTTP 429 with `Retry-After` header and a JSON-RPC error body so MCP clients can handle it gracefully.
 
+Failed authentication is throttled separately, and on by default. `--rateLimit` never saw a
+wrong bearer token, because the auth check answers before the limiter is reached — so
+guessing ran at network speed. `--authFailureLimit` gives each client its own small budget,
+spent only on a 401; a correct token never consumes from it, so a working client never
+throttles itself. Once an address has spent its budget every request from it waits,
+including one with the right token — that is deliberate, since answering the guess would
+otherwise tell the caller which token was right. Clients are told apart by socket address. **Behind a
+reverse proxy that means every client shares one budget**, so set `--trustProxy` when the
+proxy is yours — the server prints a warning the first time it sees `X-Forwarded-For`
+without it. `--trustProxy` takes the *rightmost* `X-Forwarded-For` entry, which is the hop
+the proxy itself appended; everything to its left came from the client, so reading the
+leftmost would let a client choose its own budget or spend a victim's. That only holds if a
+proxy actually appended the entry, so the header is read **only when the peer is the
+proxy** — bare `--trustProxy` means a loopback peer, which is the deployment above; name a
+proxy elsewhere with `--trustedProxies`. When the header cannot be read as an address, or
+the peer is not trusted, the server falls back to the socket address and says so once, so
+a flag that is not taking effect is not silent. One trusted hop is assumed. A malformed `--authFailureLimit` is refused at startup rather than silently
+disabling the check; only `0` turns it off.
+
 **Always terminate TLS at a reverse proxy** (Caddy/nginx). The server listens on `127.0.0.1` only.
 
 ---
@@ -678,13 +710,18 @@ Secrets are **never** passed as CLI arguments.
 | `--httpHost` | 127.0.0.1 | HTTP bind address |
 | `--bearerToken` | — | Bearer token for HTTP transport auth (required for `--transport=http`) |
 | `--rateLimit` | 0 | HTTP requests per minute on the MCP route (0 = unlimited) |
+| `--authFailureLimit` | 10 | Failed bearer-auth attempts allowed per client per minute (0 = off) |
+| `--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) |
 | `--opaUrl` | — | OPA sidecar URL for external policy |
+| `--opaFailClosed` | false | Refuse every command while OPA is unreachable, instead of falling back to local policy |
+| `--opaTimeoutMs` | 10000 | How long to wait for the OPA sidecar. Lower makes the fail-open cheaper to reach; higher makes an outage slower to notice |
 | `--commandQuota` | 0 (off) | Max commands per rolling 24h per profile |
 | `--approvalGrantTtl` | 0 (off) | Auto-approve an identical command for this many ms after approval |
 | `--auditEntropyScan` | false | Enable entropy-based secret scanning in audit |
@@ -751,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/cli.js

@@ -59,6 +59,35 @@ export function parseArgv(args = process.argv.slice(2)) {
  * `--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.
  */
+/**
+ * `--authFailureLimit`, refusing rather than guessing.
+ *
+ * `parseArgv` stores `null` for a flag written without a value, and `null !== undefined`,
+ * so a bare `--authFailureLimit` reached `parseInt` and produced NaN. NaN fails the `> 0`
+ * test the transport uses to decide whether to build the limiter at all, so a typo — or
+ * `--authFailureLimit=off`, which `0 = off` makes a plausible spelling — silently turned
+ * off a control that is on by default, with no line in the startup banner to say so. The
+ * same shape on `--rateLimit` is harmless because that one defaults to off; this one does
+ * not, which is what makes failing open new.
+ */
+export function parseFailureLimit(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === null || !/^\d+$/.test(raw.trim())) {
+        throw new OperatorError(`--authFailureLimit needs a non-negative whole number, got ${JSON.stringify(raw)}. ` +
+            'Use --authFailureLimit=0 to turn the check off deliberately.');
+    }
+    const value = Number(raw.trim());
+    // Bounded, because an unbounded one is the same fail-open this guard exists to stop:
+    // `--authFailureLimit=99999999999999999999` parsed to 1e20, a bucket that never empties
+    // and a `Retry-After` of 1 — configured on, functionally absent.
+    if (!Number.isSafeInteger(value) || value > MAX_AUTH_FAILURE_LIMIT) {
+        throw new OperatorError(`--authFailureLimit must be between 0 and ${MAX_AUTH_FAILURE_LIMIT}, got ${JSON.stringify(raw)}.`);
+    }
+    return value;
+}
+/** Far above any real budget; the point is that there is one. */
+const MAX_AUTH_FAILURE_LIMIT = 10_000;
 export function flagEnabled(argv, name) {
     if (!(name in argv))
         return false;
@@ -99,6 +128,53 @@ export function parseMaxChars(raw) {
         return 5_000;
     return parsed <= 0 ? Number.MAX_SAFE_INTEGER : parsed;
 }
+/**
+ * `--opaTimeoutMs`, bounded on both sides.
+ *
+ * Too low turns an explicit OPA deny into an allow whenever the sidecar is slow, which is
+ * the fail-open this budget exists inside; too high brings back the hang it replaced. One
+ * second is the floor and two minutes the ceiling.
+ */
+export function parseOpaTimeout(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = raw === null ? NaN : Number(raw.trim());
+    if (!Number.isSafeInteger(value) || value < 1_000 || value > 120_000) {
+        throw new OperatorError(`--opaTimeoutMs must be a whole number of milliseconds between 1000 and 120000, got ${JSON.stringify(raw)}.`);
+    }
+    return value;
+}
+/**
+ * `--opaUrl`, refused at startup rather than at every request.
+ *
+ * Only emptiness was checked, so anything `fetch` cannot use reached the engine and failed
+ * on every call — with `OPA sidecar enabled` printed at startup and one stderr line per
+ * minute as the only signal. `--opaUrl=localhost:8181` is a realistic slip, since OPA's own
+ * `--addr` is written `:8181`, and in the default mode it leaves a gate that looks
+ * configured and is never consulted. Credentials in the URL are refused too: `fetch`
+ * rejects such a URL outright, so it would be a gate that cannot work at all.
+ */
+export function parseOpaUrl(raw) {
+    if (!raw) {
+        throw new OperatorError('--opaUrl needs a URL, as --opaUrl=http://localhost:8181.');
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new OperatorError(`--opaUrl=${raw} is not a URL. Include the scheme, as --opaUrl=http://localhost:8181.`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new OperatorError(`--opaUrl must be http or https, got ${parsed.protocol}`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new OperatorError('--opaUrl must not embed credentials — fetch() refuses such a URL, so the gate would ' +
+            'never be consulted. Put the sidecar behind a network boundary instead.');
+    }
+    // A trailing slash would make the request path `//v1/data/...`.
+    return (parsed.origin + parsed.pathname).replace(/\/$/, '');
+}
 /**
  * `strict` was previously unreachable: nothing but test code could select it,
  * yet host-key.ts pointed users at a `--acceptNewHostKey` flag that never

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/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { reportFatal } from './errors.js';
+import { reportFatal, OperatorError } from './errors.js';
 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 { initKeychain } from './config/credential-resolver.js';
 import { SERVER_VERSION } from './version.js';
-import { parseArgv, buildAppConfig, checkRemovedFlags, flagEnabled, resolveHostKeyMode, } from './cli.js';
+import { parseArgv, buildAppConfig, checkRemovedFlags, flagEnabled, parseFailureLimit, parseOpaUrl, parseOpaTimeout, resolveHostKeyMode, } from './cli.js';
 async function main() {
     const argv = parseArgv();
     checkRemovedFlags(argv);
@@ -28,10 +28,16 @@ async function main() {
     const registry = new ConnectionRegistry(config, hostKeyMode);
     const policy = new PolicyEngine(resolvePolicyRules(config.profiles, config.policy));
     const audit = new AuditStore(undefined, entropyScan, tamperEvident);
-    if (argv.opaUrl) {
-        policy.setOpaUrl(argv.opaUrl);
+    if ('opaUrl' in argv) {
+        // Presence, not truthiness — the trap `flagEnabled` was written for. A
+        // space-separated `--opaUrl http://…` stores null, so the old guard dropped it
+        // silently, and dropped any `--opaFailClosed` the operator asked for with it.
+        policy.setOpaUrl(parseOpaUrl(argv.opaUrl), flagEnabled(argv, 'opaFailClosed'), parseOpaTimeout(argv.opaTimeoutMs));
         console.error(`OPA sidecar enabled: ${argv.opaUrl}`);
     }
+    else if (flagEnabled(argv, 'opaFailClosed')) {
+        throw new OperatorError('--opaFailClosed does nothing without --opaUrl.');
+    }
     // An McpServer binds to a single transport, so HTTP needs one per session.
     const createMcpServer = () => {
         // capabilities moved from serverInfo to ServerOptions in SDK 1.30.
@@ -50,6 +56,9 @@ async function main() {
             host: argv.httpHost || '127.0.0.1',
             bearerToken: argv.bearerToken,
             rateLimit: parseInt(argv.rateLimit) || 0,
+            authFailureLimit: parseFailureLimit(argv.authFailureLimit),
+            trustProxy: flagEnabled(argv, 'trustProxy'),
+            trustedProxies: argv.trustedProxies?.split(',').map((h) => h.trim()).filter(Boolean),
             allowedHosts: argv.allowedHosts?.split(',').map((h) => h.trim()).filter(Boolean),
             registry,
         });

package/build/policy/classifier.js

@@ -82,7 +82,19 @@ const FORBIDDEN_PATTERNS = [
     /rm\s+-rf?\s+\/(\s|$)/, // rm -rf / — the filesystem root itself
     /mkfs\./,
     />\s*\/dev\/sd/,
-    /:\(\)\s*\{\s*:\|:\&\s*\}\s*;\s*:/, // fork bomb
+    // Fork bomb, with whitespace allowed at the five positions bash allows it and the old
+    // pattern did not: before the parentheses, inside them, either side of the pipe, and
+    // before the ampersand. `: () { : | : & } ; :` ran and classified `safe`.
+    //
+    // What this still does not catch, so that nobody reads it as "fork bombs are handled":
+    // the same bomb under another name (`f(){ f|f& };f`), a body that separates the two
+    // calls with `&` or `;` rather than `|` (`:(){ :&:& };:`), and a comment between the
+    // tokens (`:() # x\n{ :|:& };:`). Matching the first needs a backreference over an
+    // unbounded body and this file has already shipped one ReDoS; the others would widen a
+    // list no role, tier or approval mode can override. The impact is a denial of service
+    // against the target host rather than against this server, which is not worth either
+    // trade — but it is a hole, not a closed door.
+    /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/,
     />\s*\/etc\/cron/,
     />\s*\/etc\/systemd/,
     />\s*~\/.ssh\/authorized_keys/,

package/build/policy/engine.js

@@ -1,5 +1,17 @@
 import { classifyCommand, findForbiddenMatch } from './classifier.js';
 import { OperatorError } from '../errors.js';
+/**
+ * How long to wait for the OPA sidecar before treating it as unavailable.
+ *
+ * Bounded because an unbounded wait held every tool call for undici's five-minute header
+ * timeout. Ten seconds and not two: in the default mode a timeout falls back to the local
+ * decision, so the budget is also the price of turning an explicit OPA *deny* into an
+ * allow — at two seconds a sidecar under load crosses it by accident, and anyone who can
+ * add latency crosses it on purpose. Ten is above a loaded sidecar's p99 and still thirty
+ * times cheaper than the hang it replaced. `--opaTimeoutMs` moves it: lower makes the
+ * fail-open cheaper to reach, higher makes an outage slower to notice.
+ */
+const DEFAULT_OPA_TIMEOUT_MS = 10_000;
 /** Tiers, most restrictive first. Unknown/unset tiers resolve to the first. */
 export const HOST_GROUPS = ['prod', 'staging', 'dev'];
 export const DEFAULT_RULES = {
@@ -184,6 +196,8 @@ export function resolvePolicyRules(profiles, override) {
 export class PolicyEngine {
     rules;
     opaUrl = null;
+    opaFailClosed = false;
+    opaTimeoutMs = DEFAULT_OPA_TIMEOUT_MS;
     /** Rate-limits the fail-open warning so one outage can't flood stderr. */
     lastOpaWarning = 0;
     /** The operator's patterns, compiled once. The built-ins live in classifier.ts. */
@@ -202,8 +216,15 @@ export class PolicyEngine {
             }
         });
     }
-    setOpaUrl(url) {
+    setOpaUrl(url, failClosed = false, timeoutMs = DEFAULT_OPA_TIMEOUT_MS) {
+        this.opaTimeoutMs = timeoutMs;
+        // Reset the warning throttle when the mode changes, or the one warning per minute can
+        // be the *previous* mode's sentence — "commands OPA would deny may now be allowed"
+        // printed while the engine refuses everything.
+        if (failClosed !== this.opaFailClosed || url !== this.opaUrl)
+            this.lastOpaWarning = 0;
         this.opaUrl = url;
+        this.opaFailClosed = failClosed;
     }
     evaluate(command, profile, _toolName) {
         const parsed = classifyCommand(command);
@@ -277,13 +298,31 @@ export class PolicyEngine {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ input }),
+                // A sidecar that accepts the connection and never answers is the canonical way
+                // OPA is "unreachable", and without this the call ran to undici's five-minute
+                // header timeout while every tool call waited on it. The abort lands in the catch
+                // below, so both modes reach their own answer inside the budget.
+                signal: AbortSignal.timeout(this.opaTimeoutMs),
             });
             if (!resp.ok) {
-                this.warnOpaUnavailable(`HTTP ${resp.status} from ${this.opaUrl}`);
-                return local;
+                return this.onOpaUnavailable(`HTTP ${resp.status}`, local);
             }
-            const data = await resp.json();
-            if (data.result === false) {
+            const payload = await resp.json();
+            // Guarded, not cast. `as { result?: unknown }` is a lie for a `null` body — reading
+            // `.result` off it threw, so the cause on stderr read as a defect in this server
+            // rather than as the "no decision" condition it names below.
+            const result = typeof payload === 'object' && payload !== null
+                ? payload.result
+                : undefined;
+            if (typeof result !== 'boolean') {
+                // A 200 carrying no decision is how OPA answers for an undefined document, which
+                // is what a wrong package path, an unactivated bundle, or an `allow` rule written
+                // without `default allow := false` all produce. Reading that as consent meant
+                // `--opaFailClosed` did not cover the way an OPA gate actually goes down: six of
+                // seven response shapes allowed, with no warning at all.
+                return this.onOpaUnavailable('no boolean `result` in the response', local);
+            }
+            if (result === false) {
                 return {
                     decision: 'deny',
                     commandClass: parsed.class,
@@ -294,10 +333,36 @@ export class PolicyEngine {
             }
         }
         catch (err) {
-            this.warnOpaUnavailable(err instanceof Error ? err.message : String(err));
+            return this.onOpaUnavailable(err instanceof Error ? err.message : String(err), local);
         }
         return local;
     }
+    /**
+     * What an OPA outage means, which is the operator's choice rather than ours.
+     *
+     * Falling back to the local decision is the default and stays the default: OPA is an
+     * additional deny layer, and an outage that stopped all work would be a worse failure
+     * than one that narrows the policy. But an operator who deployed OPA *as* the
+     * authorization gate has a control that disappears during an outage, and the only signal
+     * is a stderr line that MCP clients usually discard. `--opaFailClosed` lets them say
+     * that the gate being down means no.
+     */
+    onOpaUnavailable(cause, local) {
+        this.warnOpaUnavailable(cause);
+        if (!this.opaFailClosed)
+            return local;
+        return {
+            decision: 'deny',
+            commandClass: local.commandClass,
+            binary: local.binary,
+            ruleId: 'opa-unavailable',
+            // Fixed string. `cause` goes to stderr, where the operator is; this `reason` is
+            // rethrown as the tool's error text and written to the audit record, and it carried
+            // `this.opaUrl` — an internal hostname, and any credential embedded in it — out to
+            // the MCP client on every refusal.
+            reason: 'OPA evaluation unavailable and --opaFailClosed is set',
+        };
+    }
     /**
      * OPA is an *additional* deny layer, so an outage falls back to the local
      * decision rather than blocking all work. That is a deliberate trade-off, but
@@ -311,7 +376,9 @@ export class PolicyEngine {
             return;
         this.lastOpaWarning = now;
         console.error(`POLICY WARNING: OPA evaluation unavailable (${cause}). ` +
-            'Falling back to local policy — commands OPA would deny may now be allowed.');
+            (this.opaFailClosed
+                ? 'Refusing every command while it is down, because --opaFailClosed is set.'
+                : 'Falling back to local policy — commands OPA would deny may now be allowed.'));
     }
     /**
      * Say which three things produced the refusal, not one of them.

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/build/transport/http.js

@@ -1,5 +1,6 @@
 import { createServer } from 'http';
 import { randomUUID, timingSafeEqual } from 'crypto';
+import { isIP } from 'net';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { SERVER_VERSION } from '../version.js';
@@ -7,32 +8,193 @@ 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;
+/** How many failed auth attempts one client may make per minute. 0 disables the check. */
+export const DEFAULT_AUTH_FAILURE_LIMIT = 10;
+/** Cap on tracked clients, for the reason `MAX_SESSIONS` exists: churn must not grow a map. */
+export const MAX_TRACKED_CLIENTS = 1024;
+const REFILL_INTERVAL_MS = 60_000;
+/**
+ * One token-bucket step, shared by the two limiters so the refill arithmetic exists once.
+ *
+ * Mutates the bucket. Refills proportionally to elapsed time rather than on a timer, so an
+ * idle server costs nothing and there is no interval to clean up.
+ */
+function consume(bucket, maxTokens) {
+    const elapsed = Date.now() - bucket.lastRefill;
+    const refilled = Math.floor((elapsed / REFILL_INTERVAL_MS) * maxTokens);
+    if (refilled > 0) {
+        bucket.tokens = Math.min(maxTokens, bucket.tokens + refilled);
+        bucket.lastRefill += Math.round((refilled / maxTokens) * REFILL_INTERVAL_MS);
+    }
+    if (bucket.tokens > 0) {
+        bucket.tokens--;
+        return { allowed: true, retryAfterMs: 0 };
+    }
+    return { allowed: false, retryAfterMs: Math.ceil(REFILL_INTERVAL_MS / maxTokens) };
+}
 class RateLimiter {
-    tokens;
-    lastRefill;
     maxTokens;
-    refillIntervalMs;
-    constructor(maxRequestsPerMinute) {
-        this.maxTokens = maxRequestsPerMinute;
-        this.tokens = maxRequestsPerMinute;
-        this.lastRefill = Date.now();
-        this.refillIntervalMs = 60_000;
+    bucket;
+    constructor(maxTokens) {
+        this.maxTokens = maxTokens;
+        this.bucket = { tokens: maxTokens, lastRefill: Date.now() };
     }
     tryConsume() {
-        const now = Date.now();
-        const elapsed = now - this.lastRefill;
-        const refilled = Math.floor((elapsed / this.refillIntervalMs) * this.maxTokens);
-        if (refilled > 0) {
-            this.tokens = Math.min(this.maxTokens, this.tokens + refilled);
-            this.lastRefill += Math.round((refilled / this.maxTokens) * this.refillIntervalMs);
-        }
-        if (this.tokens > 0) {
-            this.tokens--;
+        return consume(this.bucket, this.maxTokens);
+    }
+}
+/**
+ * A bucket per client, for throttling failed authentication.
+ *
+ * Separate from the request limiter on purpose. The auth check returned before the request
+ * limiter was reached, so a wrong bearer token consumed nothing and guessing ran at network
+ * speed with no backoff — measured as twelve 401s and zero 429s against `--rateLimit=3`.
+ * Moving the request limiter above the auth check would have closed that and opened
+ * something worse: the request bucket is global, so unauthenticated traffic could then
+ * starve every legitimate client.
+ *
+ * Only failures consume a token, so a working client never builds a budget up and is never
+ * throttled by its own traffic — which is what makes this safe to have on by default. It
+ * is not a promise that a correct token always passes: once an address has spent its
+ * budget, everything from that address waits, correct tokens included. That is the whole
+ * point. Charging only after the comparison would leave the guess itself evaluated and the
+ * status code would still tell the attacker which token was right.
+ */
+export class AuthFailureLimiter {
+    maxTokens;
+    buckets = new Map();
+    constructor(maxTokens) {
+        this.maxTokens = maxTokens;
+    }
+    /** Whether this client may make another attempt. Does not consume. */
+    peek(key) {
+        const bucket = this.buckets.get(key);
+        if (bucket === undefined)
+            return { allowed: true, retryAfterMs: 0 };
+        const elapsed = Date.now() - bucket.lastRefill;
+        const refilled = Math.floor((elapsed / REFILL_INTERVAL_MS) * this.maxTokens);
+        const available = Math.min(this.maxTokens, bucket.tokens + Math.max(refilled, 0));
+        if (available > 0)
             return { allowed: true, retryAfterMs: 0 };
+        return { allowed: false, retryAfterMs: Math.ceil(REFILL_INTERVAL_MS / this.maxTokens) };
+    }
+    /** Charge this client for a failed attempt. */
+    recordFailure(key) {
+        let bucket = this.buckets.get(key);
+        if (bucket === undefined) {
+            bucket = { tokens: this.maxTokens, lastRefill: Date.now() };
+            if (this.buckets.size >= MAX_TRACKED_CLIENTS) {
+                // Evict the *fullest* entry, not the oldest. An exhausted bucket has the oldest
+                // `lastRefill` by construction, so evicting by age evicted the locked-out client
+                // first and then handed its key a fresh budget: minting enough keys cleared a
+                // lockout, which was measured end to end. A full bucket is the one with nothing
+                // worth remembering.
+                let fullestKey = null;
+                let fullest = -1;
+                for (const [k, b] of this.buckets) {
+                    if (b.tokens > fullest) {
+                        fullest = b.tokens;
+                        fullestKey = k;
+                    }
+                }
+                if (fullestKey !== null)
+                    this.buckets.delete(fullestKey);
+                // Every tracked client is spent, so the table itself is the signal and a new key
+                // does not get a full budget.
+                //
+                // The cost, stated because it is real and cannot be softened here: while the table
+                // is saturated an arriving client has one attempt rather than the full budget, so
+                // a first typo leaves its correct token waiting. Seeding one token instead of zero
+                // looks like it would help and does not — `consume` spends it immediately, and
+                // `peek` already allows a key it has never seen, so the first attempt is free
+                // either way and the second is refused either way. Measured both, identical.
+                // Giving an arriving key a real budget is the refund this rule exists to stop.
+                // Saturation needs 1024 addresses that have each spent a full budget.
+                if (fullest <= 0)
+                    bucket = { tokens: 0, lastRefill: Date.now() };
+            }
+            this.buckets.set(key, bucket);
         }
-        const retryAfterMs = Math.ceil(this.refillIntervalMs / this.maxTokens);
-        return { allowed: false, retryAfterMs };
+        consume(bucket, this.maxTokens);
+    }
+}
+/**
+ * Which client an attempt is charged to.
+ *
+ * The socket's remote address, which is the real client on a direct connection — how this
+ * server is normally run. `X-Forwarded-For` is read only when a proxy is explicitly
+ * trusted: honouring it unconditionally would let any client forge its own key and so opt
+ * out of the limit entirely.
+ *
+ * When it is read, the **rightmost** entry is the one taken, not the leftmost. A proxy
+ * appends the address it saw, so the rightmost entry is what the nearest trusted proxy
+ * observed while every entry to its left came from the client. Reading the leftmost was
+ * worse than having no limit: a client sending `X-Forwarded-For: 10.0.0.1` minted a fresh
+ * budget per request — measured as nine wrong tokens and zero 429s — and sending a
+ * victim's address burned *their* budget instead, locking out a correct token.
+ *
+ * This assumes exactly one trusted proxy in front, which is what `--trustProxy` means. A
+ * chain of two would need the second-from-right, and this does not try to guess the depth.
+ * Anything that is not an IP address is discarded rather than used as a map key.
+ */
+export function clientKey(req, trustProxy, trustedProxies) {
+    const peer = canonicalAddress(req.socket.remoteAddress ?? 'unknown');
+    const forwarded = req.headers['x-forwarded-for'];
+    if (!trustProxy || forwarded === undefined)
+        return { key: peer, forwardedIgnored: false };
+    // The rightmost entry is proxy-authored only if a proxy actually appended one. Nothing
+    // about the header says whether it did, so the *peer* has to be the proxy — otherwise a
+    // client reaching the listener directly sends one forged entry, that entry is the
+    // rightmost, and it picks its own key. Both attacks this keying was fixed to stop came
+    // back alive in exactly that configuration.
+    if (!isTrustedPeer(peer, trustedProxies)) {
+        return { key: peer, forwardedIgnored: true };
+    }
+    const raw = Array.isArray(forwarded) ? forwarded.join(',') : forwarded;
+    const entries = raw.split(',').map((e) => e.trim()).filter(Boolean);
+    const nearest = entries[entries.length - 1];
+    const address = nearest === undefined ? undefined : forwardedAddress(nearest);
+    if (address === undefined)
+        return { key: peer, forwardedIgnored: true };
+    return { key: address, forwardedIgnored: false };
+}
+/**
+ * Whether the peer may speak for other clients.
+ *
+ * Bare `--trustProxy` means a loopback peer, which is the deployment the README asks for:
+ * the server binds to 127.0.0.1 and a proxy on the same host terminates TLS. A proxy
+ * somewhere else has to be named, because "trust whoever connected" is the assumption that
+ * made the header forgeable again.
+ */
+function isTrustedPeer(peer, trustedProxies) {
+    if (trustedProxies !== undefined && trustedProxies.length > 0) {
+        return trustedProxies.includes(peer);
+    }
+    return peer === '127.0.0.1' || peer === '::1' || peer.startsWith('127.');
+}
+/**
+ * One `X-Forwarded-For` entry as an address, or undefined if it is not one.
+ *
+ * `net.isIP` rejects the bracketed and port-suffixed spellings, which is how IPv6 usually
+ * appears in this header — and rejecting silently collapsed every client onto the proxy's
+ * key, which is worse than not keying at all.
+ */
+function forwardedAddress(entry) {
+    let candidate = entry;
+    const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(candidate);
+    if (bracketed)
+        candidate = bracketed[1];
+    // A trailing `:port` only when what is left is not itself an IPv6 literal: `::1` has
+    // colons of its own and must not be truncated.
+    else if (isIP(candidate) === 0 && /^[^:]+:\d+$/.test(candidate)) {
+        candidate = candidate.slice(0, candidate.lastIndexOf(':'));
     }
+    candidate = canonicalAddress(candidate);
+    return isIP(candidate) === 0 ? undefined : candidate;
+}
+/** `::ffff:127.0.0.1` and `127.0.0.1` are the same client; key them the same way. */
+function canonicalAddress(address) {
+    return address.startsWith('::ffff:') ? address.slice(7) : address;
 }
 function jsonRpcError(res, status, code, message) {
     res.writeHead(status, { 'Content-Type': 'application/json' });
@@ -49,6 +211,26 @@ export async function startHttpServer(createMcpServer, opts) {
         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 authFailureLimit = opts.authFailureLimit ?? DEFAULT_AUTH_FAILURE_LIMIT;
+    const authFailureLimiter = authFailureLimit > 0
+        ? new AuthFailureLimiter(authFailureLimit)
+        : null;
+    // Said once, when it turns out to matter. Behind a proxy with `--trustProxy` off, every
+    // client is keyed on the proxy's socket address and so shares one budget — which means
+    // ten failures from anyone locks out everyone. The README tells operators to terminate
+    // TLS at a proxy, so this is the configuration it recommends, and the collapse is
+    // invisible until a legitimate client is refused.
+    let warnedSharedBudget = false;
+    const warnSharedBudget = () => {
+        if (warnedSharedBudget)
+            return;
+        warnedSharedBudget = true;
+        console.error('POLICY WARNING: X-Forwarded-For is present but not being used to tell clients ' +
+            'apart, so every client shares one failed-auth budget and one failing client can ' +
+            'lock out the rest. Either --trustProxy is off, or the peer is not a trusted proxy ' +
+            '(bare --trustProxy trusts a loopback peer; name others with --trustedProxies), or ' +
+            'the rightmost entry is not an address this server can read.');
+    };
     const rateLimiter = opts.rateLimit && opts.rateLimit > 0
         ? new RateLimiter(opts.rateLimit)
         : null;
@@ -102,6 +284,41 @@ export async function startHttpServer(createMcpServer, opts) {
         // 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) {
+            // Checked before the token is compared, not after — so an exhausted budget answers
+            // 429 without evaluating the guess. Gating only the 401 path instead would throttle
+            // nothing: the comparison would still happen and a correct token would still be
+            // served, so the status code would still tell an attacker which guess was right.
+            let key = '';
+            if (authFailureLimiter) {
+                const resolved = clientKey(req, opts.trustProxy === true, opts.trustedProxies);
+                key = resolved.key;
+                // Warned in both directions. Without `--trustProxy` a proxied deployment shares
+                // one budget; *with* it, an entry that could not be read leaves the same collapse
+                // in place, and that case used to be the silent one — the operator had set the
+                // flag and had no way to know it was not taking effect.
+                if (resolved.forwardedIgnored || (opts.trustProxy !== true && req.headers['x-forwarded-for'])) {
+                    warnSharedBudget();
+                }
+            }
+            if (authFailureLimiter) {
+                const { allowed, retryAfterMs } = authFailureLimiter.peek(key);
+                if (!allowed) {
+                    const retryAfterSec = Math.ceil(retryAfterMs / 1000);
+                    res.writeHead(429, {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(retryAfterSec),
+                    });
+                    res.end(JSON.stringify({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32604,
+                            message: `Too many failed authentication attempts. Retry after ${retryAfterSec}s.`,
+                        },
+                        id: null,
+                    }));
+                    return;
+                }
+            }
             const auth = req.headers.authorization || '';
             const expected = `Bearer ${bearerToken}`;
             const authBuf = Buffer.from(auth);
@@ -109,6 +326,7 @@ export async function startHttpServer(createMcpServer, opts) {
             const match = authBuf.length === expectedBuf.length &&
                 timingSafeEqual(authBuf, expectedBuf);
             if (!match) {
+                authFailureLimiter?.recordFailure(key);
                 // RFC 7235: a 401 must say how to authenticate. MCP clients also parse
                 // JSON-RPC envelopes on this route, so 401 speaks the same dialect as
                 // the 429 and 413 responses rather than a bare {error}.
@@ -248,6 +466,9 @@ export async function startHttpServer(createMcpServer, opts) {
             if (rateLimiter) {
                 console.error(`Rate limit: ${opts.rateLimit} req/min`);
             }
+            if (authFailureLimiter) {
+                console.error(`Auth failure limit: ${authFailureLimit}/min per client`);
+            }
             resolve();
         });
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.6.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",
@@ -38,8 +38,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "^0.7.0",
-    "@changesets/cli": "^2.31.0",
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.1",
     "@types/node": "^26.2.0",
     "@types/ssh2": "^1.15.5",
     "@vitest/coverage-v8": "^4.1.10",