ssh-mcp 2.2.6 → 2.3.0

package/README.md

@@ -23,7 +23,13 @@ npm install -g ssh-mcp
 
 ### 2. Configure
 
-Create `~/.config/ssh-mcp/config.toml` (Linux/macOS) or `%APPDATA%\ssh-mcp\config.toml` (Windows):
+Create the config file at the path for your platform:
+
+| Platform | Path |
+|---|---|
+| Linux | `~/.config/ssh-mcp/config.toml` (or `$XDG_CONFIG_HOME/ssh-mcp/config.toml`) |
+| macOS | `~/Library/Application Support/ssh-mcp/config.toml` |
+| Windows | `%APPDATA%\ssh-mcp\config.toml` |
 
 ```toml
 [defaults]
@@ -42,9 +48,39 @@ approvalPolicy = "auto"    # dev is permissive
 ```
 
 ```bash
-chmod 600 ~/.config/ssh-mcp/config.toml
+chmod 700 ~/.config/ssh-mcp && chmod 600 ~/.config/ssh-mcp/config.toml
 ```
 
+The server refuses to start if anyone but you can read the config, since it
+decides which hosts, roles and policy rules this server honours.
+
+On Linux and macOS that is the mode check above — the directory too, which is why
+`chmod 700` is in that command: `mkdir -p` under the default umask leaves it 0755. On Windows there are no mode
+bits, so it reads the ACL instead and requires that only your account, `SYSTEM`
+and `Administrators` hold access. A config under `%APPDATA%` inherits exactly
+that and needs nothing done to it. One created elsewhere does not — a file under
+`C:\` inherits read access for every local account and modify for every
+authenticated one — and the refusal names the two `icacls` commands that fix it,
+or, when the directory is a filesystem root or sits outside your user profile, leads with
+moving the config instead — it still prints the commands, but removing entries from a
+directory other accounts share is a judgement only you can make.
+
+If the ACL cannot be read at all, the server refuses rather than assuming the file is
+private, and `--allowUncheckedConfigAcl` loads it unverified. Two cases do not need the
+flag — `icacls` being absent from the machine, and the check running out of time — because
+both are statements about the machine rather than about the file. Each warns and loads.
+
+### Exit statuses
+
+| Status | Meaning |
+|---|---|
+| `0` | Clean shutdown |
+| `1` | A defect in the server — printed with a stack trace; please report it |
+| `2` | How it was invoked or configured — printed as a message, no stack |
+
+A supervisor that treats any non-zero status as a failure needs no change. One
+that matched on `1` to detect a startup problem should match on `2` as well.
+
 ### 3. Set credentials via environment variables
 
 ```bash
@@ -479,7 +515,7 @@ See [SECURITY.md](./SECURITY.md) for the full threat model, vulnerability report
 - [ ] Restrict network egress on target hosts
 - [ ] Use `readOnly = true` for monitoring profiles
 - [ ] Review audit logs regularly
-- [ ] Run `chmod 600 config.toml`
+- [ ] Run `chmod 700 <config dir> && chmod 600 config.toml` (Windows: the ACL under `%APPDATA%` is already restricted)
 
 ---
 
@@ -547,7 +583,7 @@ Secrets are **never** passed as CLI arguments.
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--config` | XDG path | Path to TOML config file |
+| `--config` | platform config dir (see [Configure](#2-configure)) | Path to TOML config file |
 | `--host` | — | Quick start: SSH host (creates single-profile config) |
 | `--user` | — | Quick start: SSH username |
 | `--port` | 22 | Quick start: SSH port |
@@ -565,6 +601,7 @@ Secrets are **never** passed as CLI arguments.
 | `--rateLimit` | 0 | HTTP requests per minute on the MCP route (0 = unlimited) |
 | `--allowedHosts` | bind address + localhost | Comma-separated Host headers accepted by the DNS-rebinding guard |
 | `--insecureHostKey` | false | Disable host key verification (test only!) |
+| `--allowUncheckedConfigAcl` | false | Windows: load the config even if its ACL could not be read |
 | `--disableApproval` | false | Skip the approval gate (quick start profile only) |
 | `--opaUrl` | — | OPA sidecar URL for external policy |
 | `--commandQuota` | 0 (off) | Max commands per rolling 24h per profile |

package/build/config/credential-resolver.js

@@ -1,5 +1,6 @@
 import { readFile } from 'fs/promises';
 import { resolve } from 'path';
+import { OperatorError } from '../errors.js';
 let keyringGet = null;
 let keyringSet = null;
 export function isKeychainAvailable() {
@@ -25,7 +26,7 @@ export async function initKeychain() {
 }
 export async function setKeychainEntry(service, account, password) {
     if (!keyringSet)
-        throw new Error('Keychain not initialized. Install @napi-rs/keyring.');
+        throw new OperatorError('Keychain not initialized. Install @napi-rs/keyring.');
     await keyringSet(service, account, password);
 }
 export async function resolveCredentials(profile) {
@@ -110,7 +111,7 @@ export async function resolveCredentials(profile) {
             keychain: `the OS keychain returned nothing${profile.keychainEntry ? ` for "${profile.keychainEntry}"` : ' — keychainEntry is not set on the profile'}`,
             password: `SSH_MCP_PASSWORD and SSH_MCP_${profile.name.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_PASSWORD are both unset`,
         };
-        throw new Error(`No credentials resolved for profile "${profile.name}", which asks for auth = "${asked}": ${why[asked] ?? 'nothing was found'}.\n` +
+        throw new OperatorError(`No credentials resolved for profile "${profile.name}", which asks for auth = "${asked}": ${why[asked] ?? 'nothing was found'}.\n` +
             'Fix that method rather than switching to another if you can — the fallbacks are ordered by how much ' +
             'they expose. In order: an SSH agent (nothing on disk), an encrypted key with SSH_MCP_KEY, the OS ' +
             `keychain, and last a password in SSH_MCP_PASSWORD, which is readable by every process running as you.`);

package/build/config/loader.js

@@ -3,6 +3,8 @@ import { homedir, platform } from 'os';
 import { join, dirname } from 'path';
 import { parse as parseTOML } from 'smol-toml';
 import { configSchema } from './schema.js';
+import { OperatorError, ConfigNotFoundError } from '../errors.js';
+import { assertPrivateOnWindows } from './windows-acl.js';
 export function getConfigPath(customPath) {
     if (customPath)
         return customPath;
@@ -17,43 +19,93 @@ export function getConfigPath(customPath) {
     const xdgConfig = process.env.XDG_CONFIG_HOME || join(home, '.config');
     return join(xdgConfig, 'ssh-mcp', 'config.toml');
 }
-export async function checkPermissions(filePath) {
-    try {
-        const fileStat = await stat(filePath);
-        const mode = fileStat.mode & 0o777;
-        if (mode & 0o077) {
-            throw new Error(`Config file ${filePath} is group/world accessible (mode ${mode.toString(8)}). Required: 0600. Run: chmod 600 ${filePath}`);
+/**
+ * Refuse a config file that anyone but its owner can read, because it holds the
+ * hosts, roles and policy rules that decide what this server will run.
+ *
+ * One question, asked of two different access-control systems. Mode bits are
+ * POSIX's answer and are meaningless on Windows, which is the whole of #138:
+ * Node synthesises `0o666` for every readable file there, so `& 0o077` was
+ * non-zero unconditionally and every Windows config that has ever existed was
+ * rejected. The `chmod 600` it prescribed could not lift that rejection —
+ * measured on Windows 11, `chmod(path, 0o600)` leaves the mode at `0o666`,
+ * because `fs.chmod` there only toggles the read-only bit. Following the
+ * instruction exactly returned the operator to where they started.
+ *
+ * Windows reads the ACL instead; see assertPrivateOnWindows.
+ */
+export async function checkPermissions(filePath, opts = {}) {
+    return platform() === 'win32'
+        ? assertPrivateOnWindows(filePath, opts)
+        : checkPosixMode(filePath);
+}
+/**
+ * Split out so its own refusals do not pass back through the `catch` that
+ * tolerates ENOENT. They survived it only because an OperatorError carries no
+ * `.code`, which was a coincidence rather than a design.
+ */
+async function checkPosixMode(filePath) {
+    const dir = dirname(filePath);
+    const modeOf = async (path) => {
+        try {
+            return (await stat(path)).mode & 0o777;
         }
-        const dirMode = (await stat(dirname(filePath))).mode & 0o777;
-        if (dirMode & 0o077) {
-            throw new Error(`Config directory is group/world accessible (mode ${dirMode.toString(8)}). Required: 0700.`);
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
         }
+    };
+    // The file is tested before the directory is even stat'd, which is the order
+    // main used: batching both stats first meant a 0644 file whose directory
+    // vanished in between took the ENOENT path and was accepted.
+    const fileMode = await modeOf(filePath);
+    if (fileMode === null)
+        return;
+    if (fileMode & 0o077) {
+        throw new OperatorError(`Config file ${filePath} is group/world accessible (mode ${fileMode.toString(8)}). ` +
+            `Required: 0600. Run: chmod 600 ${filePath}`);
     }
-    catch (err) {
-        if (err.code === 'ENOENT')
-            return;
-        throw err;
+    const dirMode = await modeOf(dir);
+    if (dirMode !== null && dirMode & 0o077) {
+        throw new OperatorError(`Config directory ${dir} is group/world accessible (mode ${dirMode.toString(8)}). ` +
+            `Required: 0700. Run: chmod 700 ${dir}\n` +
+            // The published Docker image created this directory 0755, so a container
+            // with a config bind-mounted at the default path met this on every start
+            // with no way to chmod a path baked into the image.
+            'If the directory is not yours to change — a container image, or a mount point — ' +
+            'bind-mount a 0700 directory over it, or point --config at one you control.');
     }
 }
-export async function loadConfig(customPath) {
+export async function loadConfig(customPath, opts = {}) {
     const configPath = getConfigPath(customPath);
     let raw;
     try {
         raw = await readFile(configPath, 'utf8');
     }
     catch (err) {
-        if (err.code === 'ENOENT' && !customPath) {
-            throw new Error(`No config file found at ${configPath}. Create one or use --config <path>. See documentation for the TOML schema.`);
-        }
-        throw err;
+        // Also for an explicit --config that points nowhere. That used to escape
+        // as the raw system error ("ENOENT: no such file or directory, open ..."),
+        // which says the same thing in the vocabulary of a syscall.
+        if (err.code === 'ENOENT')
+            throw new ConfigNotFoundError(configPath);
+        // Everything else here is still the operator's file — a directory passed as
+        // --config, a mode or ACL that denies reading, a mount that went away. Those
+        // escaped raw too, so `reportFatal` printed them with a stack through our
+        // own frames: the presentation this change exists to remove.
+        // `.code` is carried through for the same reason ConfigNotFoundError keeps it: a
+        // wrapper script distinguishing "unreadable, remount and retry" from "absent, run the
+        // installer" was matching on it, and preserving it on one branch while dropping it on
+        // the adjacent one is a half-applied rule.
+        throw Object.assign(new OperatorError(`Config file ${configPath} could not be read: ${err.message}`), { code: err.code, cause: err });
     }
-    await checkPermissions(configPath);
+    await checkPermissions(configPath, opts);
     let parsed;
     try {
         parsed = parseTOML(raw);
     }
     catch (err) {
-        throw new Error(`Failed to parse TOML config at ${configPath}: ${err.message}`);
+        throw new OperatorError(`Failed to parse TOML config at ${configPath}: ${err.message}`);
     }
     const result = configSchema.safeParse(parsed);
     if (!result.success) {
@@ -63,7 +115,7 @@ export async function loadConfig(customPath) {
         const issues = result.error.issues
             .map((i) => `  ${i.path.length ? i.path.join('.') : '(root)'}: ${i.message}`)
             .join('\n');
-        throw new Error(`Config validation error:\n${issues}`);
+        throw new OperatorError(`Config validation error:\n${issues}`);
     }
     return normalizeConfig(result.data);
 }
@@ -95,9 +147,10 @@ function normalizeConfig(raw) {
     // survives anywhere in AppConfig. Leaving the raw value on `defaults` left one
     // object carrying two encodings of "unlimited" — `profile.maxChars` as
     // MAX_SAFE_INTEGER, `defaults.commandMaxChars` as 0 — with nothing in the
-    // types to tell them apart. index.ts:161 already copies straight across
-    // (`maxChars: defaults.commandMaxChars`), and was correct only because that
-    // path's value comes from parseMaxChars, which never returns 0. Correct by
+    // types to tell them apart. buildAppConfig's quick-start path already copies it
+    // straight across (`maxChars: defaults.commandMaxChars`), and was correct only
+    // because that path's value comes from parseMaxChars, which never returns 0.
+    // Correct by
     // coincidence of another surface is not a property to leave standing when the
     // wrong encoding rejects every non-empty command.
     const defaults = {
@@ -130,13 +183,13 @@ export function getProfile(config, name) {
         // unambiguous; more than one is a question the caller has to answer.
         if (config.profiles.length > 1) {
             const names = config.profiles.map((p) => p.name).join(', ');
-            throw new Error(`No profile selected and no default configured, but ${config.profiles.length} profiles exist: ${names}. ` +
+            throw new OperatorError(`No profile selected and no default configured, but ${config.profiles.length} profiles exist: ${names}. ` +
                 `Pass a "profile" argument, or set defaults.defaultProfile in the config.`);
         }
         return config.profiles[0];
     }
     const profile = config.profiles.find((p) => p.name === targetName);
     if (!profile)
-        throw new Error(`Profile "${targetName}" not found`);
+        throw new OperatorError(`Profile "${targetName}" not found`);
     return profile;
 }