ssh-mcp 2.14.0 → 2.15.0

package/README.md

@@ -4,6 +4,7 @@
 [![Downloads](https://img.shields.io/npm/dm/ssh-mcp)](https://www.npmjs.com/package/ssh-mcp)
 [![CI](https://github.com/tufantunc/ssh-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tufantunc/ssh-mcp/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/tufantunc/ssh-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/tufantunc/ssh-mcp)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15082/badge)](https://www.bestpractices.dev/projects/15082)
 [![codecov](https://codecov.io/gh/tufantunc/ssh-mcp/graph/badge.svg?branch=main)](https://codecov.io/gh/tufantunc/ssh-mcp)
 [![License](https://img.shields.io/github/license/tufantunc/ssh-mcp)](./LICENSE)
 [![GitHub issues](https://img.shields.io/github/issues/tufantunc/ssh-mcp)](https://github.com/tufantunc/ssh-mcp/issues)
@@ -763,7 +764,7 @@ ssh-mcp --transport=http --httpPort=3000 --bearerToken=secret --rateLimit=60
 | `--bearerToken` | required | Bearer token for authentication (all routes except `GET /health`) |
 | `--httpPort` | 3000 | HTTP listen port |
 | `--httpHost` | 127.0.0.1 | Bind address |
-| `--rateLimit` | 0 (off) | Max requests per minute (0 = unlimited) |
+| `--rateLimit` | 0 (off) | Max authenticated requests per minute, per client (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 |
@@ -776,7 +777,13 @@ case of a config bind mount that silently did not attach: the server binds the p
 refuses every tool call. `GET /status` carries the profile list itself and stays behind the
 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.
+`--rateLimit` is a budget per client, keyed the same way as the failed-auth budget below,
+and every authenticated request spends from it: `POST /` and the rest of the MCP route,
+`GET /status`, and an authenticated request to a path that does not exist. `GET /health`
+never does. A wrong token never does either, so unauthenticated traffic cannot spend a
+working client's budget. When a client's budget is spent the server returns HTTP 429 with
+a JSON-RPC error body, and `Retry-After` gives the seconds until that client's next request
+will be accepted.
 
 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
@@ -784,18 +791,20 @@ guessing ran at network speed. `--authFailureLimit` gives each client its own sm
 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.
+otherwise tell the caller which token was right. Clients are told apart by socket address,
+for this budget and for `--rateLimit` alike. **Behind a reverse proxy that means every
+client shares one of each**, 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.
 
@@ -845,7 +854,7 @@ Secrets are **never** passed as CLI arguments.
 | `--httpPort` | 3000 | HTTP transport port |
 | `--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) |
+| `--rateLimit` | 0 | Max authenticated requests per minute, per client (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 |

package/build/transport/http.js

@@ -13,6 +13,54 @@ 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;
+/** Whole tokens earned since `lastRefill`. Negative when the clock stepped back; callers clamp. */
+function tokensEarned(bucket, maxTokens) {
+    return Math.floor(((Date.now() - bucket.lastRefill) / REFILL_INTERVAL_MS) * maxTokens);
+}
+/** Tokens the bucket would hold if refilled now, without changing it. */
+function availableTokens(bucket, maxTokens) {
+    return Math.min(maxTokens, bucket.tokens + Math.max(tokensEarned(bucket, maxTokens), 0));
+}
+/**
+ * How long until this bucket earns its next token, for `Retry-After`.
+ *
+ * Exact, where it used to be the fixed `REFILL_INTERVAL_MS / maxTokens`. That is how long
+ * one token takes, so a client refused halfway through the interval was told to wait
+ * twice as long as it had to. Bounded on both sides: below at a second, because
+ * `Retry-After` is whole seconds and `0` reads as "retry now"; above at one token's
+ * interval, because a clock that stepped backwards puts `lastRefill` in the future, and
+ * the raw difference would then advertise an arbitrarily long wait. Rounded up to whole
+ * milliseconds: a limit that does not divide a minute gives a fractional interval, and
+ * rounding down would name a moment at which the token has not yet arrived.
+ */
+function nextTokenWaitMs(bucket, maxTokens) {
+    const interval = REFILL_INTERVAL_MS / maxTokens;
+    return Math.max(1000, Math.ceil(Math.min(interval, bucket.lastRefill + interval - Date.now())));
+}
+/**
+ * The tracked key whose bucket holds the most tokens *after refill*: the entry with the
+ * least worth remembering, so the one to evict.
+ *
+ * Refilled, not stored. A key that stops sending keeps its stored count forever, so
+ * ranking by `tokens` treated a bucket spent an hour ago as still spent. A table that
+ * was saturated once was then judged saturated for good, which was measured.
+ *
+ * Linear in the table, and left that way: it runs only when a new key arrives at a full
+ * table, and stops early at the first full bucket. The worst case, every bucket partly
+ * spent, measured about 46µs per new key at 1024 entries (Apple M4 Max, Node 24), and
+ * the same for both limiters.
+ */
+function fullestBucket(buckets, maxTokens) {
+    let fullest;
+    for (const [key, bucket] of buckets) {
+        const available = availableTokens(bucket, maxTokens);
+        if (fullest === undefined || available > fullest.available)
+            fullest = { key, available };
+        if (available === maxTokens)
+            break;
+    }
+    return fullest;
+}
 /**
  * One token-bucket step, shared by the two limiters so the refill arithmetic exists once.
  *
@@ -20,8 +68,7 @@ const REFILL_INTERVAL_MS = 60_000;
  * 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);
+    const refilled = tokensEarned(bucket, maxTokens);
     if (refilled > 0) {
         bucket.tokens = Math.min(maxTokens, bucket.tokens + refilled);
         bucket.lastRefill += Math.round((refilled / maxTokens) * REFILL_INTERVAL_MS);
@@ -30,17 +77,41 @@ function consume(bucket, maxTokens) {
         bucket.tokens--;
         return { allowed: true, retryAfterMs: 0 };
     }
-    return { allowed: false, retryAfterMs: Math.ceil(REFILL_INTERVAL_MS / maxTokens) };
+    return { allowed: false, retryAfterMs: nextTokenWaitMs(bucket, maxTokens) };
 }
-class RateLimiter {
+/**
+ * A request bucket per client, so `--rateLimit` means N requests per minute *per caller*.
+ *
+ * It was one bucket for the process: one client spent `--rateLimit` for every other, and
+ * a client that had sent nothing was refused (#187, measured). Keyed by `clientKey()`,
+ * the same key the failure budget uses, and charged only after the token check passes,
+ * so unauthenticated traffic cannot create entries or drain anyone's budget.
+ *
+ * Bounded like `AuthFailureLimiter`, and it evicts the fullest bucket for the same reason.
+ * Where it differs: an arriving key always starts full, even when every tracked bucket is
+ * spent. Saturating this table takes 1024 addresses that hold the token, and a token
+ * holder with that many addresses already has that many budgets. The refund opens nothing
+ * new, while starting empty would refuse a legitimate client's first request because of
+ * other clients' traffic.
+ */
+export class ClientRateLimiter {
     maxTokens;
-    bucket;
+    buckets = new Map();
     constructor(maxTokens) {
         this.maxTokens = maxTokens;
-        this.bucket = { tokens: maxTokens, lastRefill: Date.now() };
     }
-    tryConsume() {
-        return consume(this.bucket, this.maxTokens);
+    tryConsume(key) {
+        let bucket = this.buckets.get(key);
+        if (bucket === undefined) {
+            if (this.buckets.size >= MAX_TRACKED_CLIENTS) {
+                const fullest = fullestBucket(this.buckets, this.maxTokens);
+                if (fullest !== undefined)
+                    this.buckets.delete(fullest.key);
+            }
+            bucket = { tokens: this.maxTokens, lastRefill: Date.now() };
+            this.buckets.set(key, bucket);
+        }
+        return consume(bucket, this.maxTokens);
     }
 }
 /**
@@ -50,8 +121,8 @@ class RateLimiter {
  * 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.
+ * something worse: its 429 would answer a guess without evaluating it, and unauthenticated
+ * traffic reaching a request bucket could spend a victim's budget under a spoofable key.
  *
  * 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
@@ -71,12 +142,9 @@ export class AuthFailureLimiter {
         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)
+        if (availableTokens(bucket, this.maxTokens) > 0)
             return { allowed: true, retryAfterMs: 0 };
-        return { allowed: false, retryAfterMs: Math.ceil(REFILL_INTERVAL_MS / this.maxTokens) };
+        return { allowed: false, retryAfterMs: nextTokenWaitMs(bucket, this.maxTokens) };
     }
     /** Charge this client for a failed attempt. */
     recordFailure(key) {
@@ -89,16 +157,9 @@ export class AuthFailureLimiter {
                 // 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);
+                const fullest = fullestBucket(this.buckets, this.maxTokens);
+                if (fullest !== undefined)
+                    this.buckets.delete(fullest.key);
                 // Every tracked client is spent, so the table itself is the signal and a new key
                 // does not get a full budget.
                 //
@@ -109,8 +170,9 @@ export class AuthFailureLimiter {
                 // `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)
+                // Saturation needs 1024 addresses that have each spent a full budget *recently*:
+                // `fullestBucket` ranks by refilled tokens, so the condition ends once they refill.
+                if (fullest === undefined || fullest.available <= 0)
                     bucket = { tokens: 0, lastRefill: Date.now() };
             }
             this.buckets.set(key, bucket);
@@ -216,23 +278,25 @@ export async function startHttpServer(createMcpServer, opts) {
         ? 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.
+    // client is keyed on the proxy's socket address and so shares one failure budget and one
+    // request budget — ten failures from anyone locks out everyone, and one busy client
+    // starves the rest. 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.');
+            'apart, so every client is charged to one key: one failed-auth budget and one ' +
+            'request budget between them, for whichever of the two is on, and one client can ' +
+            'lock out or starve 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)
+        ? new ClientRateLimiter(opts.rateLimit)
         : null;
     // DNS rebinding: a page the user visits can make their browser POST to a
     // localhost server, and the bearer token does not help if the browser is
@@ -284,22 +348,24 @@ 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) {
+            if (authFailureLimiter || rateLimiter) {
                 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.
+                // Resolved for either limiter: with only `--rateLimit` on, skipping this charged
+                // every client to one key and kept the warning silent.
                 if (resolved.forwardedIgnored || (opts.trustProxy !== true && req.headers['x-forwarded-for'])) {
                     warnSharedBudget();
                 }
             }
+            // 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.
             if (authFailureLimiter) {
                 const { allowed, retryAfterMs } = authFailureLimiter.peek(key);
                 if (!allowed) {
@@ -341,23 +407,29 @@ export async function startHttpServer(createMcpServer, opts) {
                 }));
                 return;
             }
-        }
-        if (rateLimiter && url.pathname === '/' && (req.method === 'POST' || req.method === 'GET' || req.method === 'DELETE')) {
-            const { allowed, retryAfterMs } = rateLimiter.tryConsume();
-            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: `Rate limit exceeded. Retry after ${retryAfterSec}s.`,
-                    },
-                }));
-                return;
+            // Charged after the token check, never before: a request bucket is per client, but
+            // unauthenticated traffic reaching it could still spend a victim's budget under a
+            // spoofable key, and its 429 would answer a guess without evaluating it. Every
+            // authenticated route spends from it, `/status` and 404s included: `/status` was
+            // unlimited, so a token holder could poll it without bound.
+            if (rateLimiter) {
+                const { allowed, retryAfterMs } = rateLimiter.tryConsume(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: `Rate limit exceeded. Retry after ${retryAfterSec}s.`,
+                        },
+                        id: null,
+                    }));
+                    return;
+                }
             }
         }
         if (req.method === 'POST' && url.pathname === '/') {
@@ -464,7 +536,7 @@ export async function startHttpServer(createMcpServer, opts) {
             console.error(`SSH MCP Server v2 (HTTP) listening on http://${host}:${port}`);
             console.error('Endpoints: POST / (MCP), GET /status, GET /health');
             if (rateLimiter) {
-                console.error(`Rate limit: ${opts.rateLimit} req/min`);
+                console.error(`Rate limit: ${opts.rateLimit} req/min per client`);
             }
             if (authFailureLimiter) {
                 console.error(`Auth failure limit: ${authFailureLimit}/min per client`);

package/package.json

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