ssh-mcp 2.1.0 → 2.2.1

package/README.md

@@ -3,13 +3,13 @@
 [![NPM Version](https://img.shields.io/npm/v/ssh-mcp)](https://www.npmjs.com/package/ssh-mcp)
 [![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)
-[![codecov](https://codecov.io/gh/tufantunc/ssh-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/tufantunc/ssh-mcp)
+[![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)
 
 **SSH MCP Server** is a security-first Model Context Protocol server that gives LLM agents controlled SSH access to remote hosts — with command classification, policy-based authorization, human-in-the-loop approval, and full audit logging.
 
-> **WARNING — Lethal Trifecta Risk.** Giving an LLM SSH access creates a ["Lethal Trifecta"](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) (private data + untrusted input + network egress). **Never run as root. Never enable `auto` approval on production.** See [SECURITY.md](./SECURITY.md) for the full threat model and mitigation checklist.
+> **The risk this server exists to manage.** Giving an LLM shell access on a remote host puts private data, untrusted input and network egress in one place — Simon Willison's ["lethal trifecta"](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/). Prompt injection has no general fix, so ssh-mcp assumes any command may be attacker-influenced: it classifies before executing, authorizes against a role × host-group matrix, gates destructive work behind approval, and records the decision either way. That narrows the blast radius; it does not remove the risk. Two things stay yours: **never point it at a root account**, and **never set `auto` approval on a production profile**. [SECURITY.md](./SECURITY.md) has the full threat model.
 
 ---
 
@@ -166,7 +166,7 @@ auth = "agent"                      # agent | key | password | keychain
 keyRef = "~/.ssh/id_ed25519"        # for auth=key
 keychainEntry = "ssh-mcp/prod"      # for auth=keychain (requires @napi-rs/keyring)
 via = "bastion"                     # ProxyJump — route through bastion profile
-group = "prod"                      # Policy tier: prod | staging | dev
+group = "prod"                      # Policy tier: prod | staging | dev, or your own (see [policy])
 workdir = "/var/www"
 trustedHostKey = "SHA256:..."       # Pin host key (optional)
 tty = false
@@ -177,8 +177,24 @@ cert = false                        # SSH CA cert auth — auto-detects keyRef-c
 sessionMaxPerConnection = 3         # per-profile override
 sessionIdleTimeoutMs = 300000       # stricter for prod
 commandQuotaPerDay = 200            # per-profile override
+
+# Optional. Merged over the built-in role matrix; see "Policy Engine" below.
+# roleBindings is keyed by role and then by tier, so the block below changes
+# operator on prod and leaves operator's other tiers, and viewer and admin,
+# on their defaults.
+[policy]
+denylist = ["^terraform\\s+destroy"]
+
+[policy.roleBindings.operator]
+prod = ["read-only", "safe", "destructive"]
 ```
 
+Unknown sections and keys are a startup error, not a warning, so a typo cannot
+leave you running defaults you thought you had overridden. That extends to role
+and tier names: every one you write under `[policy.roleBindings]` has to be
+reachable by some profile, and every profile's role and tier has to resolve to
+real bindings. Both directions are checked at startup.
+
 ### ProxyJump (Bastion)
 
 Reach internal hosts behind a bastion/jump server. The `via` field specifies a profile name to tunnel through:
@@ -259,9 +275,69 @@ name = "build-box"
 group = "dev"
 ```
 
-Leaving a real production host on `prod` and granting sudo there is a policy
-change, not a flag: add `privileged` to `admin.prod` in the config's
-`roleBindings`.
+### Configuring the matrix
+
+The table above is the default, not a limit. An optional `[policy]` section is
+merged over it at startup, so granting sudo on a host you have honestly
+labelled `prod` is a reviewable line in a config file rather than a relabelling:
+
+```toml
+[policy.roleBindings.admin]
+prod = ["read-only", "safe", "destructive", "privileged"]
+```
+
+The merge is at role *and* tier depth. That block changes `admin` on `prod` and
+nothing else: `admin` on `staging` and `dev` keep their defaults, and `viewer`
+and `operator` are untouched. Roles and tiers the defaults have never heard of
+are added rather than rejected, which is what makes a custom `group` resolve to
+real bindings instead of falling back to the strictest tier:
+
+```toml
+[[profiles]]
+name = "build-box"
+role = "admin"
+group = "tier-1"
+
+[policy.roleBindings.admin]
+"tier-1" = ["read-only", "safe", "destructive"]
+```
+
+Extra deny patterns live in the same section, and are applied on top of the
+never-allowed list rather than replacing it:
+
+```toml
+[policy]
+denylist = ["^terraform\\s+destroy"]
+```
+
+Because role and tier names are free strings, nothing in the merge itself can
+tell a new custom role from a misspelling of an existing one. A cross-check at
+startup does, and these all fail there rather than at the point of use:
+
+- a command class outside `read-only | safe | destructive | privileged`, so a
+  `priviledged` typo cannot parse into a grant of nothing and then read as a
+  policy decision when a command is refused;
+- any unrecognised section or key anywhere in the config, so a block the parser
+  does not understand is an error rather than a clean startup with none of the
+  behaviour you configured;
+- a role or tier under `[policy.roleBindings]` that no profile uses, so
+  `[policy.roleBindings.operater]` cannot merge in as a fourth role while the
+  profiles you meant to restrict keep running on defaults;
+- a profile whose `role` has no bindings, or whose tier has none under that
+  role, so a host cannot end up on `read-only` for a reason nobody wrote down.
+
+The last one covers the tier you did not set as well as the one you did. A
+profile with no `group` still resolves to one by name, and that inferred tier
+has to exist under the profile's role like any other.
+
+A tier with no bindings for a role grants `read-only`, and never another tier's
+classes. There is no fallback between tiers: while the matrix was compiled in,
+falling back to `prod` meant falling back to a role's strictest cell, but a
+`[policy]` block can write that cell now.
+
+An OPA sidecar is not an alternative route to the same grant. OPA is consulted
+only for commands the local policy already allows, so it can refuse more but
+never widen. Widening happens here or not at all.
 
 ### Command Classification
 
@@ -323,7 +399,11 @@ For organizations that standardize on Open Policy Agent / Rego:
 ssh-mcp --opaUrl=http://localhost:8181
 ```
 
-When `--opaUrl` is set, every command is additionally evaluated by OPA after the built-in policy engine. The request shape follows the AuthZEN Access Evaluation contract:
+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:
 
 ```json
 {
@@ -344,7 +424,8 @@ package ssh.mcp
 
 default allow := false
 
-# Admins can run anything on dev hosts
+# Admins pass the OPA gate on dev hosts. The built-in policy still applies on
+# top: this widens nothing that the role bindings withhold.
 allow if {
   input.subject.role == "admin"
   startswith(input.subject.profile, "dev")

package/build/config/loader.js

@@ -57,8 +57,11 @@ export async function loadConfig(customPath) {
     }
     const result = configSchema.safeParse(parsed);
     if (!result.success) {
+        // A root-level issue has an empty path, which used to render as a bare
+        // colon. Unreachable while the root schema accepted anything; an unknown
+        // top-level section reaches it now.
         const issues = result.error.issues
-            .map((i) => `  ${i.path.join('.')}: ${i.message}`)
+            .map((i) => `  ${i.path.length ? i.path.join('.') : '(root)'}: ${i.message}`)
             .join('\n');
         throw new Error(`Config validation error:\n${issues}`);
     }
@@ -86,7 +89,10 @@ function normalizeConfig(raw) {
         sessionBackgroundMaxMs: p.sessionBackgroundMaxMs ?? defaults.sessionBackgroundMaxMs,
         commandQuotaPerDay: p.commandQuotaPerDay ?? defaults.commandQuotaPerDay,
     }));
-    return { defaults, profiles };
+    // Passed through untouched. mergePolicyRules() owns the layering over
+    // DEFAULT_RULES, so the loader has no policy semantics of its own to get
+    // wrong.
+    return { defaults, profiles, policy: raw.policy };
 }
 export function getProfile(config, name) {
     const targetName = name || config.defaults.defaultProfile;

package/build/config/schema.js

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 const authMethodSchema = z.enum(['agent', 'key', 'password', 'keychain']);
 const approvalModeSchema = z.enum(['auto', 'ask-destructive', 'ask-all', 'deny']);
+const commandClassSchema = z.enum(['read-only', 'safe', 'destructive', 'privileged']);
+/**
+ * Role and tier names, which are free strings so operators can define their own.
+ *
+ * `__proto__` is excluded because merging assigns into a plain object, and that
+ * assignment lands on the prototype instead of creating a key: a role by that
+ * name would be accepted and then not exist. `constructor` and `prototype` are
+ * excluded alongside it rather than reasoned about case by case.
+ */
+const RESERVED_BINDING_KEYS = ['__proto__', 'constructor', 'prototype'];
+const bindingKeySchema = z.string().min(1).refine((key) => !RESERVED_BINDING_KEYS.includes(key), { message: `Reserved name (${RESERVED_BINDING_KEYS.join(', ')}). Rename the role or tier.` });
 export const defaultsSchema = z.object({
     defaultProfile: z.string().optional(),
     sessionMaxPerConnection: z.number().int().positive().default(5),
@@ -47,7 +58,30 @@ export const profileSchema = z.object({
     sessionBackgroundMaxMs: z.number().int().positive().optional(),
     commandQuotaPerDay: z.number().int().nonnegative().optional(),
 }).strict();
+/**
+ * Overrides merged over the compiled-in DEFAULT_RULES at startup.
+ *
+ * `roleBindings` is keyed role → host group → command classes, and the group
+ * key is a free string on purpose: a config that defines its own tier makes
+ * `group = "tier-1"` on a profile resolve to that tier instead of falling back
+ * to the strictest one.
+ *
+ * Command classes are validated against the enum rather than accepted as free
+ * strings, so `priviledged` fails at load instead of parsing to a grant of
+ * nothing, which reads at runtime exactly like a policy decision.
+ *
+ * `allowlist` is deliberately absent: PolicyRules declares the field but no
+ * code reads it, so accepting it here would document a key that does nothing.
+ */
+export const policySchema = z.object({
+    roleBindings: z.record(bindingKeySchema, z.record(bindingKeySchema, z.array(commandClassSchema))).optional(),
+    denylist: z.array(z.string()).optional(),
+}).strict();
+// .strict() on the root as well: without it an unknown section (a typo, or a
+// key from a newer version) parses cleanly and is dropped with no warning, so
+// the operator gets a clean startup and none of the behaviour they configured.
 export const configSchema = z.object({
     defaults: defaultsSchema.default({}),
     profiles: z.array(profileSchema).min(1),
-});
+    policy: policySchema.optional(),
+}).strict();

package/build/guard/elicitation.js

@@ -31,8 +31,17 @@ export async function requestApproval(server, command, profileName, evaluation)
         return { approved: false };
     }
     catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        // stderr still gets it for the operator's logs, but it cannot be the only
+        // copy: for a stdio MCP server that is a client log file nobody reads, so
+        // the caller gets the diagnosis too and can put it in front of the user.
         console.error(`Approval request failed for ${evaluation.commandClass} command on "${profileName}" — denying. ` +
-            `Does this client support elicitation? Cause: ${err instanceof Error ? err.message : String(err)}`);
-        return { approved: false };
+            `Does this client support elicitation? Cause: ${cause}`);
+        return {
+            approved: false,
+            unavailable: `this MCP client could not be asked to approve it. The likely cause is a client without ` +
+                `elicitation support; a transport failure or a malformed reply does the same. Approval fails ` +
+                `closed, so the command was refused rather than run. Underlying error: ${cause}`,
+        };
     }
 }

package/build/index.js

@@ -3,7 +3,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { loadConfig } from './config/loader.js';
 import { ConnectionRegistry } from './ssh/connection-registry.js';
-import { PolicyEngine, DEFAULT_RULES, HOST_GROUPS } from './policy/engine.js';
+import { PolicyEngine, HOST_GROUPS, 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';
@@ -160,7 +160,7 @@ async function main() {
         await initTracing(argv.otelEndpoint, argv.otelServiceName || 'ssh-mcp');
     }
     const registry = new ConnectionRegistry(config, hostKeyMode);
-    const policy = new PolicyEngine(DEFAULT_RULES);
+    const policy = new PolicyEngine(resolvePolicyRules(config.profiles, config.policy));
     const audit = new AuditStore(undefined, entropyScan, tamperEvident);
     if (argv.opaUrl) {
         policy.setOpaUrl(argv.opaUrl);

package/build/policy/classifier.js

@@ -60,14 +60,9 @@ const FORBIDDEN_PATTERNS = [
     /mkfs\./,
     /dd\s.*\bof=\/dev\//,
     />\s*\/dev\/sd/,
-    /\bshutdown\b/,
-    /\breboot\b/,
-    /\bhalt\b/,
-    /\bpoweroff\b/,
     /:\(\)\s*\{\s*:\|:\&\s*\}\s*;\s*:/, // fork bomb
     /curl\s[^|]*\|\s*(sh|bash|zsh)/,
     /wget\s[^|]*\|\s*(sh|bash|zsh)/,
-    /\beval\b/,
     />\s*\/etc\/cron/,
     />\s*\/etc\/systemd/,
     />\s*~\/.ssh\/authorized_keys/,
@@ -75,6 +70,98 @@ const FORBIDDEN_PATTERNS = [
     /\bchmod\s+-R\s+777\s+\//,
     /\bchown\s+-R\s.*\s\/\s*$/,
 ];
+/**
+ * Words that are forbidden when *invoked*, which the patterns above cannot
+ * express.
+ *
+ * These used to be `/\breboot\b/` and friends, matching the word anywhere in
+ * the string. `last reboot` reads a log and was refused for containing the
+ * word; so were `grep -r reboot /etc/`, `cat /var/run/reboot-required` and
+ * `journalctl | grep shutdown`. On a NAS an agent checking boot history trips
+ * this on its first command, which is how it was reported (#91).
+ *
+ * Matching an invocation rather than a mention needs to know where a command
+ * word can start, and that is a tokenizer's job, not a regex's — the regex
+ * forms that come close all reintroduce the `\S*` backtracking the block above
+ * exists to avoid.
+ */
+const FORBIDDEN_INVOCATIONS = new Set(['shutdown', 'reboot', 'halt', 'poweroff', 'eval']);
+/** Binaries that take the dangerous action as an argument: `systemctl reboot`. */
+const ACTION_MULTIPLEXERS = new Set(['systemctl', 'init', 'telinit']);
+const PRIVILEGE_PREFIXES = new Set(['sudo', 'su', 'doas', 'pkexec']);
+/**
+ * Privilege-prefix flags that consume the next argument, so `sudo -u root
+ * reboot` is not read as invoking `root`. Enumerable because it is one tool's
+ * option set, unlike "every flag of every binary".
+ */
+const PREFIX_VALUE_FLAGS = new Set([
+    '-u', '-g', '-p', '-C', '-h', '-r', '-t', '-U', '-c',
+    '--user', '--group', '--prompt', '--close-from', '--host', '--role', '--type',
+    '--other-user', '--command',
+]);
+/** `/sbin/reboot` and `reboot` are the same invocation. */
+function stripPath(word) {
+    const slash = word.lastIndexOf('/');
+    return slash === -1 ? word : word.slice(slash + 1);
+}
+/**
+ * The command words a shell would actually execute — the head of every
+ * `;`/`&&`/`||`/`|`/newline-separated segment, past any privilege prefix, plus
+ * the arguments of a multiplexer like `systemctl`.
+ *
+ * Pure string work: split, trim, set lookups. No quantifiers, so nothing here
+ * can backtrack.
+ */
+function invokedWords(command) {
+    const invoked = [];
+    for (const segment of command.split(/[;&|\n]/)) {
+        const words = segment.trim().split(/\s+/).filter(Boolean).map(stripPath);
+        let i = 0;
+        while (i < words.length && PRIVILEGE_PREFIXES.has(words[i])) {
+            i++;
+            while (i < words.length && words[i].startsWith('-')) {
+                const consumesValue = PREFIX_VALUE_FLAGS.has(words[i]);
+                i++;
+                if (consumesValue)
+                    i++;
+            }
+        }
+        const head = words[i];
+        if (!head)
+            continue;
+        invoked.push(head);
+        // `systemctl reboot` restarts the host. Reading a unit that happens to be
+        // named after a power action is rare enough that erring towards refusal
+        // here costs little.
+        if (ACTION_MULTIPLEXERS.has(head)) {
+            invoked.push(...words.slice(i + 1).filter((w) => !w.startsWith('-')));
+        }
+    }
+    return invoked;
+}
+const FORBIDDEN_RULES = [
+    ...FORBIDDEN_PATTERNS.map((re) => ({ label: String(re), test: (c) => re.test(c) })),
+    {
+        label: 'invoking a power-state command (shutdown, reboot, halt, poweroff) or eval',
+        test: (command) => invokedWords(command).some((w) => FORBIDDEN_INVOCATIONS.has(w)),
+    },
+];
+/**
+ * Which never-allowed rule this command trips, or null. The single entry point:
+ * FORBIDDEN_PATTERNS is deliberately not exported, because half of the list
+ * lives in FORBIDDEN_RULES and a caller checking only the regexes would quietly
+ * permit `sudo reboot`.
+ */
+export function findForbiddenMatch(command) {
+    for (const rule of FORBIDDEN_RULES) {
+        if (rule.test(command))
+            return rule.label;
+    }
+    return null;
+}
+export function isForbidden(command) {
+    return findForbiddenMatch(command) !== null;
+}
 /**
  * Commands that are destructive but legitimate under approval — e.g.
  * `rm -rf /tmp/build`, which must NOT be confused with `rm -rf /`.
@@ -82,8 +169,17 @@ const FORBIDDEN_PATTERNS = [
 const DESTRUCTIVE_PATTERNS = [
     /rm\s+-rf?\s+\//,
 ];
-/** Everything that classifies as destructive: forbidden commands included. */
-const DESTRUCTIVE_DENYLIST = [...FORBIDDEN_PATTERNS, ...DESTRUCTIVE_PATTERNS];
+/**
+ * Everything that classifies as destructive: forbidden commands included.
+ *
+ * Goes through isForbidden() rather than the regex list, so a command caught by
+ * an invocation rule is classified destructive too — and, just as importantly,
+ * reading a log that mentions `reboot` is no longer classified destructive
+ * either.
+ */
+function isDestructive(command) {
+    return isForbidden(command) || DESTRUCTIVE_PATTERNS.some((re) => re.test(command));
+}
 const PRIVILEGED_INDICATORS = [
     /^\s*sudo\b/,
     /^\s*su\b/,
@@ -109,10 +205,8 @@ export function classifyCommand(command) {
     if (isPrivileged) {
         return { binary, fullCommand, class: 'privileged' };
     }
-    for (const pattern of DESTRUCTIVE_DENYLIST) {
-        if (pattern.test(trimmed)) {
-            return { binary, fullCommand, class: 'destructive' };
-        }
+    if (isDestructive(trimmed)) {
+        return { binary, fullCommand, class: 'destructive' };
     }
     const twoWordPrefix = fullCommand.split(/\s+/).slice(0, 2).join(' ');
     if (READ_ONLY_ALLOWLIST.has(binary) || READ_ONLY_ALLOWLIST.has(twoWordPrefix)) {
@@ -123,4 +217,4 @@ export function classifyCommand(command) {
     }
     return { binary, fullCommand, class: 'safe' };
 }
-export { READ_ONLY_ALLOWLIST, DESTRUCTIVE_DENYLIST, FORBIDDEN_PATTERNS };
+export { READ_ONLY_ALLOWLIST, isDestructive };

package/build/policy/engine.js

@@ -1,4 +1,4 @@
-import { classifyCommand, FORBIDDEN_PATTERNS } from './classifier.js';
+import { classifyCommand, findForbiddenMatch } from './classifier.js';
 /** Tiers, most restrictive first. Unknown/unset tiers resolve to the first. */
 export const HOST_GROUPS = ['prod', 'staging', 'dev'];
 export const DEFAULT_RULES = {
@@ -20,19 +20,157 @@ export const DEFAULT_RULES = {
         },
     },
 };
+/**
+ * Layer an operator's `[policy]` section over the compiled-in defaults.
+ *
+ * The merge is at role → group depth, not role depth. Replacing a whole role's
+ * bindings from a partial table is the trap here: a config naming only
+ * `admin.prod` would otherwise wipe `admin.staging` and `admin.dev` back to
+ * nothing, widening or narrowing two tiers the operator never mentioned.
+ *
+ * Roles and groups absent from the override keep their defaults, and a role or
+ * tier the defaults have never heard of is added rather than rejected. That is
+ * what makes a custom `group = "tier-1"` resolve to real bindings.
+ *
+ * `denylist` replaces rather than appends, because the defaults carry none and
+ * FORBIDDEN_PATTERNS is applied on top by the engine regardless.
+ *
+ * With nothing to layer, `base` is returned as-is rather than copied. The
+ * result is read-only either way — PolicyEngine only reads `rules`, and the
+ * copying below exists so a *later* merge cannot reach DEFAULT_RULES through a
+ * shared tier object, not because callers are expected to mutate what they get.
+ */
+export function mergePolicyRules(base, override) {
+    if (!override?.roleBindings && !override?.denylist)
+        return base;
+    // Copy every tier map: assigning base's objects straight through would let a
+    // later merge mutate DEFAULT_RULES, which is a module-level singleton.
+    const roleBindings = {};
+    for (const [role, groups] of Object.entries(base.roleBindings)) {
+        roleBindings[role] = { ...groups };
+    }
+    for (const [role, groups] of Object.entries(override.roleBindings ?? {})) {
+        roleBindings[role] = { ...(roleBindings[role] ?? {}), ...groups };
+    }
+    return {
+        roleBindings,
+        denylist: override.denylist ?? base.denylist,
+    };
+}
+/**
+ * Which tier's role binding applies to this profile.
+ *
+ * `profile.group` is authoritative. Without it we still infer from the name
+ * for convenience, but an unrecognised name resolves to the most restrictive
+ * tier: the previous default sent every unrecognised profile to `dev`, so a
+ * production host merely named "web-01" silently received the loosest
+ * permissions in the matrix.
+ *
+ * Exported rather than kept private because startup validation has to reach the
+ * same answer the engine will reach, inference included. Checking only the
+ * explicit `group` would pass every profile that never set one, which is where
+ * the widening below actually happens.
+ */
+export function resolveProfileGroup(profile) {
+    if (profile.group)
+        return profile.group;
+    const name = profile.name.toLowerCase();
+    if (name.includes('prod'))
+        return 'prod';
+    if (name.includes('staging'))
+        return 'staging';
+    if (/\b(dev|local|test|sandbox)\b/.test(name) || /(^|[-_])(dev|local|test|sandbox)([-_]|$)/.test(name)) {
+        return 'dev';
+    }
+    return HOST_GROUPS[0];
+}
+/**
+ * Every way a config's policy can mean something other than what it says.
+ *
+ * Checked in both directions, because a silent no-op is reachable from either:
+ * a profile can name a role or tier that nothing defines, and a `[policy]`
+ * block can define a role or tier that no profile can reach. #95 was the second
+ * kind (written, parsed, dropped), and the first kind lands on `['read-only']`,
+ * which at runtime is indistinguishable from a deliberate policy decision.
+ *
+ * The `[policy]` side is checked against `override`, never the merged table:
+ * the merge carries the three compiled-in roles, and no real config references
+ * all of them.
+ *
+ * Returns every problem rather than the first, matching the config validation
+ * error in loader.ts. An operator fixing a config file wants the whole list.
+ */
+export function findPolicyProblems(merged, profiles, override) {
+    const problems = [];
+    for (const profile of profiles) {
+        const roleBinding = merged.roleBindings[profile.role];
+        if (!roleBinding) {
+            problems.push(`profile "${profile.name}": role "${profile.role}" has no role bindings, so it can only ever ` +
+                `run read-only commands. Define [policy.roleBindings.${profile.role}], or set role to one of: ` +
+                `${Object.keys(merged.roleBindings).join(', ')}.`);
+            continue;
+        }
+        const group = resolveProfileGroup(profile);
+        if (roleBinding[group])
+            continue;
+        const tiers = Object.keys(roleBinding).join(', ');
+        problems.push(profile.group
+            ? `profile "${profile.name}": role "${profile.role}" has no bindings for group "${group}". ` +
+                `Add a "${group}" key under [policy.roleBindings.${profile.role}], or set group to one of: ${tiers}.`
+            : `profile "${profile.name}": no group is set, so the tier is inferred from the name as "${group}", ` +
+                `and role "${profile.role}" has no bindings for it. Set group explicitly to one of: ${tiers}, ` +
+                `or add a "${group}" key under [policy.roleBindings.${profile.role}].`);
+    }
+    const rolesInUse = [...new Set(profiles.map((p) => p.role))];
+    for (const [role, tiers] of Object.entries(override?.roleBindings ?? {})) {
+        if (!rolesInUse.includes(role)) {
+            problems.push(`[policy.roleBindings.${role}]: no profile uses role "${role}", so this block changes nothing. ` +
+                `Roles in use: ${rolesInUse.join(', ')}.`);
+        }
+        for (const tier of Object.keys(tiers)) {
+            if (HOST_GROUPS.includes(tier))
+                continue;
+            if (profiles.some((p) => p.group === tier))
+                continue;
+            problems.push(`[policy.roleBindings.${role}]: key "${tier}" matches no profile's group and is not a built-in ` +
+                `tier (${HOST_GROUPS.join(', ')}), so it changes nothing. Set group = "${tier}" on a profile, ` +
+                `or remove the key.`);
+        }
+    }
+    return problems;
+}
+/**
+ * The rules main() runs on: the compiled-in defaults, the operator's overrides
+ * layered on top, and a refusal to start when the two do not describe the same
+ * world.
+ *
+ * Refusing rather than warning. A warning here goes to stderr, which for a
+ * stdio MCP server means a log file the operator is not reading, and "written,
+ * ignored, nothing said" is the whole of #95.
+ */
+export function resolvePolicyRules(profiles, override) {
+    const merged = mergePolicyRules(DEFAULT_RULES, override);
+    const problems = findPolicyProblems(merged, profiles, override);
+    if (problems.length > 0) {
+        throw new Error('Policy configuration error:\n' +
+            problems.map((p) => `  ${p}`).join('\n') +
+            '\nSee the "Configuring the matrix" section of the README.');
+    }
+    return merged;
+}
 export class PolicyEngine {
     rules;
     opaUrl = null;
     /** Rate-limits the fail-open warning so one outage can't flood stderr. */
     lastOpaWarning = 0;
-    /** Canonical patterns plus the operator's, compiled once at construction. */
-    denyPatterns;
+    /** The operator's patterns, compiled once. The built-ins live in classifier.ts. */
+    userPatterns;
     constructor(rules = DEFAULT_RULES) {
         this.rules = rules;
         // Compile eagerly: a deny rule that silently degrades (the old code fell
         // back to substring-matching the command against the regex *source*) is
         // worse than a startup failure, because nothing surfaces the degradation.
-        const userPatterns = (rules.denylist ?? []).map((pattern) => {
+        this.userPatterns = (rules.denylist ?? []).map((pattern) => {
             try {
                 return new RegExp(pattern);
             }
@@ -40,7 +178,6 @@ export class PolicyEngine {
                 throw new Error(`Invalid denylist pattern ${JSON.stringify(pattern)}: ${err instanceof Error ? err.message : String(err)}`);
             }
         });
-        this.denyPatterns = [...FORBIDDEN_PATTERNS, ...userPatterns];
     }
     setOpaUrl(url) {
         this.opaUrl = url;
@@ -49,13 +186,14 @@ export class PolicyEngine {
         const parsed = classifyCommand(command);
         const allowedClasses = this.getAllowedClasses(profile);
         const classAllowed = allowedClasses.includes(parsed.class);
-        if (this.matchesDenylist(command)) {
+        const denied = this.findDenyMatch(command);
+        if (denied) {
             return {
                 decision: 'deny',
                 commandClass: parsed.class,
                 binary: parsed.binary,
                 ruleId: 'denylist',
-                reason: 'Command matches denylist pattern',
+                reason: denied,
             };
         }
         const needsApproval = parsed.class === 'destructive' || parsed.class === 'privileged';
@@ -161,24 +299,29 @@ export class PolicyEngine {
      * dev but not on prod. A reader concludes their role is simply incapable of
      * sudo and goes looking for a bigger role that does not exist (#91).
      *
-     * The inferred case matters most: a profile with no group set lands on the
-     * strictest tier, so the reason is something the operator never wrote down
-     * anywhere and cannot see.
+     * The inferred case matters most: a profile with no group set has its tier
+     * guessed from its name, so the reason is something the operator never wrote
+     * down anywhere and cannot see.
      */
     explainRoleDenial(profile, commandClass) {
         if (profile.readOnly) {
             return `Profile "${profile.name}" is read-only, so "${commandClass}" commands are refused. ` +
                 `Clear readOnly on the profile to allow them.`;
         }
-        const group = this.resolveHostGroup(profile);
+        const group = resolveProfileGroup(profile);
         const inferred = !profile.group;
         const allowed = this.getAllowedClasses(profile).join(', ');
         let reason = `Role "${profile.role}" on host group "${group}" cannot run "${commandClass}" commands ` +
             `(allowed: ${allowed}).`;
         if (inferred) {
+            // Not "defaulted to the most restrictive tier": the name is matched
+            // against prod/staging/dev first, so a profile called "staging-web" lands
+            // on staging and the old wording described a fallback that did not
+            // happen. What the operator needs to know is that nothing they wrote
+            // chose this tier.
             reason +=
-                ` No group is set for profile "${profile.name}", so it defaulted to the most restrictive tier.` +
-                    ` Set group = "dev" or "staging" on the profile, or pass --group, if this host is not production.`;
+                ` No group is set for profile "${profile.name}", so the tier was inferred from its name as "${group}".` +
+                    ` Set group explicitly on the profile, or pass --group, if that is not where this host belongs.`;
         }
         else {
             reason += ` Change the profile's group, or grant the class to this role in the policy's roleBindings.`;
@@ -193,31 +336,19 @@ export class PolicyEngine {
         if (!roleBinding) {
             return ['read-only'];
         }
-        const hostGroup = this.resolveHostGroup(profile);
-        // Falls back to the most restrictive tier, never to the loosest one.
-        return roleBinding[hostGroup] || roleBinding[HOST_GROUPS[0]] || ['read-only'];
-    }
-    /**
-     * Which tier's role binding applies to this profile.
-     *
-     * `profile.group` is authoritative. Without it we still infer from the name
-     * for convenience, but an unrecognised name resolves to the most restrictive
-     * tier: the previous default sent every unrecognised profile to `dev`, so a
-     * production host merely named "web-01" silently received the loosest
-     * permissions in the matrix.
-     */
-    resolveHostGroup(profile) {
-        if (profile.group)
-            return profile.group;
-        const name = profile.name.toLowerCase();
-        if (name.includes('prod'))
-            return 'prod';
-        if (name.includes('staging'))
-            return 'staging';
-        if (/\b(dev|local|test|sandbox)\b/.test(name) || /(^|[-_])(dev|local|test|sandbox)([-_]|$)/.test(name)) {
-            return 'dev';
-        }
-        return HOST_GROUPS[0];
+        // No hop to another tier when this one has no bindings. While roleBindings
+        // were compiled in, falling back to HOST_GROUPS[0] meant falling back to
+        // that role's *strictest* cell, so the old comment here was true. Once a
+        // [policy] block can write the prod cell, the same hop hands an unresolved
+        // tier whatever prod was granted. That is a widening, and a silent one.
+        //
+        // An unresolved tier is a startup error now (resolvePolicyRules), so
+        // reaching this line means the engine was constructed directly rather than
+        // from a config file. Fail closed.
+        //
+        // `??` rather than `||`: an empty class list is a deliberate lockdown, and
+        // whether it survives should not rest on `[]` being truthy.
+        return roleBinding[resolveProfileGroup(profile)] ?? ['read-only'];
     }
     /**
      * Whether this command trips the profile's approval gate. What happens at the
@@ -232,7 +363,28 @@ export class PolicyEngine {
         // ask-destructive and deny both gate on destructive/privileged commands.
         return needsApproval;
     }
-    matchesDenylist(command) {
-        return this.denyPatterns.some((pattern) => pattern.test(command));
+    /**
+     * Which deny rule refused this command, worded so the reader can act on it.
+     *
+     * The old message was `Command matches denylist pattern` and named nothing —
+     * not the rule, not where it came from, not whether the operator could change
+     * it. A user who hit it had no way to tell a built-in refusal from one they
+     * had written themselves (#91). explainRoleDenial already names the role, the
+     * group, the class and the allowed set; this path never got the same
+     * treatment.
+     */
+    findDenyMatch(command) {
+        const builtIn = findForbiddenMatch(command);
+        if (builtIn) {
+            return `Command matches a built-in never-allowed rule: ${builtIn}. ` +
+                `This list cannot be switched off — the [policy].denylist key adds patterns, it does not remove these.`;
+        }
+        for (const pattern of this.userPatterns) {
+            if (pattern.test(command)) {
+                return `Command matches /${pattern.source}/, a pattern from [policy].denylist in your config file. ` +
+                    `Remove or narrow it there to allow this command.`;
+            }
+        }
+        return null;
     }
 }

package/build/tools/pipeline.js

@@ -55,7 +55,12 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
                 }
                 const approval = await requestApproval(server, command, conn.profile.name, evaluation);
                 if (!approval.approved) {
-                    throw new PolicyRefusedError('APPROVAL_DENIED: User did not approve this command', evaluation);
+                    // Two different failures used to share one message. "User did not
+                    // approve" is true when the user declined and a lie when the client
+                    // could not be asked, and the reader cannot tell which they got (#91).
+                    throw new PolicyRefusedError(approval.unavailable
+                        ? `APPROVAL_UNAVAILABLE: ${approval.unavailable}`
+                        : 'APPROVAL_DENIED: User did not approve this command', evaluation);
                 }
                 grants.record(conn.profile.name, command, evaluation.commandClass);
                 return { conn, evaluation, approver: approval.approver };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
   "type": "module",
   "bin": {
@@ -41,17 +41,14 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.31.0",
-    "@types/node": "^24.5.2",
+    "@types/node": "^26.2.0",
     "@types/ssh2": "^1.15.5",
-    "@vitest/coverage-v8": "^3.2.7",
-    "cross-env": "^7.0.3",
-    "fast-check": "^3.23.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    "cross-env": "^10.1.0",
+    "fast-check": "^4.9.0",
     "shx": "^0.4.0",
-    "testcontainers": "^11.7.0",
-    "ts-node": "^10.9.2",
-    "tsx": "^4.20.6",
     "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.10"
   },
   "homepage": "https://github.com/tufantunc/ssh-mcp#readme",
   "repository": {