ssh-mcp 1.5.0 → 2.0.0

package/build/audit/store.js

@@ -0,0 +1,178 @@
+import { mkdir, stat, rename, chmod, open } from 'fs/promises';
+import { createWriteStream } from 'fs';
+import { homedir, platform } from 'os';
+import { join, dirname } from 'path';
+import { randomUUID, createHash } from 'crypto';
+import { redactText } from '../guard/redactor.js';
+import { tracer } from '../observability/tracer.js';
+const MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
+const MAX_FILES = 10;
+export function getAuditLogPath() {
+    const home = homedir();
+    const p = platform();
+    if (p === 'darwin') {
+        return join(home, 'Library', 'Logs', 'ssh-mcp', 'audit.log');
+    }
+    if (p === 'win32') {
+        return join(process.env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'ssh-mcp', 'audit.log');
+    }
+    const xdgData = process.env.XDG_DATA_HOME || join(home, '.local', 'share');
+    return join(xdgData, 'ssh-mcp', 'audit.log');
+}
+export class AuditStore {
+    logPath;
+    entropyScan;
+    tamperEvident;
+    lastHash = '';
+    writeStream = null;
+    dirEnsured = false;
+    recordCount = 0;
+    /** Bytes in the open log file; -1 means "read the baseline from disk". */
+    bytesWritten = -1;
+    writeQueue = Promise.resolve();
+    /** Rotation threshold; injectable so tests exercise it without a 100MB file. */
+    maxFileSize;
+    constructor(logPath, entropyScan = false, tamperEvident = false, maxFileSize = MAX_FILE_SIZE) {
+        this.logPath = logPath || getAuditLogPath();
+        this.entropyScan = entropyScan;
+        this.tamperEvident = tamperEvident;
+        this.maxFileSize = maxFileSize;
+    }
+    async record(entry) {
+        this.writeQueue = this.writeQueue
+            .catch(() => { })
+            .then(() => this._record(entry));
+        return this.writeQueue;
+    }
+    async close() {
+        try {
+            await this.writeQueue;
+        }
+        catch { /* queue may be rejected */ }
+        if (this.writeStream && !this.writeStream.destroyed) {
+            await new Promise((resolve) => this.writeStream.end(() => resolve()));
+            this.writeStream = null;
+        }
+    }
+    async _record(entry) {
+        const span = tracer.startSpan('audit.record');
+        span.setAttribute('audit.tamperEvident', this.tamperEvident);
+        try {
+            const record = {
+                ...entry,
+                timestamp: new Date().toISOString(),
+                eventId: randomUUID(),
+            };
+            const redactedCommand = redactText(record.command, { entropyScan: this.entropyScan });
+            const redactedError = record.error ? redactText(record.error, { entropyScan: this.entropyScan }) : undefined;
+            let lineObj = { ...record, command: redactedCommand, error: redactedError };
+            if (this.tamperEvident) {
+                if (!this.lastHash) {
+                    await this.loadLastHash();
+                }
+                const prevHash = this.lastHash;
+                const contentForHash = JSON.stringify(lineObj) + prevHash;
+                const selfHash = createHash('sha256').update(contentForHash).digest('hex');
+                lineObj = { ...lineObj, prevHash, selfHash };
+                this.lastHash = selfHash;
+            }
+            const line = JSON.stringify(lineObj) + '\n';
+            await this.rotateIfNeeded(Buffer.byteLength(line));
+            const stream = await this.ensureStream();
+            await new Promise((resolve, reject) => {
+                stream.write(line, (err) => err ? reject(err) : resolve());
+            });
+            this.bytesWritten += Buffer.byteLength(line);
+            span.setAttribute('audit.bytes', line.length);
+            this.recordCount++;
+        }
+        finally {
+            span.end();
+        }
+    }
+    async ensureStream() {
+        if (this.writeStream && !this.writeStream.destroyed)
+            return this.writeStream;
+        if (!this.dirEnsured) {
+            await mkdir(dirname(this.logPath), { recursive: true });
+            this.dirEnsured = true;
+        }
+        this.writeStream = createWriteStream(this.logPath, { flags: 'a' });
+        // Force a fresh baseline read for the newly opened file.
+        this.bytesWritten = -1;
+        try {
+            await chmod(this.logPath, 0o600);
+        }
+        catch { /* may not exist yet */ }
+        return this.writeStream;
+    }
+    async loadLastHash() {
+        let fd;
+        try {
+            // Open first, then stat the handle. Stat-then-open is a TOCTOU race
+            // (js/file-system-race): the size is used as a read offset, so a file
+            // that shrank in between would be read from the wrong position. Statting
+            // the open handle describes exactly the file being read.
+            fd = await open(this.logPath, 'r');
+            const fileStat = await fd.stat();
+            const readSize = Math.min(fileStat.size, 8192);
+            if (readSize === 0)
+                return;
+            const buf = Buffer.alloc(readSize);
+            await fd.read(buf, 0, readSize, fileStat.size - readSize);
+            const lines = buf.toString('utf8').split('\n').filter(Boolean);
+            if (lines.length === 0)
+                return;
+            const lastLine = JSON.parse(lines[lines.length - 1]);
+            this.lastHash = lastLine.selfHash || '';
+        }
+        catch {
+            // File doesn't exist or can't be read — start fresh
+        }
+        finally {
+            // The old code closed the handle only on the success path, leaking one
+            // per failed read.
+            await fd?.close().catch(() => { });
+        }
+    }
+    /**
+     * Rotate before the incoming record would push the file over the limit.
+     *
+     * The size is tracked from the open stream instead of stat()ing the file on
+     * every record: every tool call awaits this on the shared write queue, so
+     * that was a syscall per request to answer a question we already know.
+     */
+    async rotateIfNeeded(incomingBytes) {
+        try {
+            if (this.bytesWritten < 0) {
+                // First write on this stream — establish the baseline once.
+                this.bytesWritten = await stat(this.logPath).then((s) => s.size).catch(() => 0);
+            }
+            if (this.bytesWritten + incomingBytes < this.maxFileSize)
+                return;
+            if (this.writeStream && !this.writeStream.destroyed) {
+                await new Promise((resolve) => {
+                    this.writeStream.end(() => resolve());
+                });
+                this.writeStream = null;
+            }
+            for (let i = MAX_FILES - 1; i > 0; i--) {
+                const oldPath = `${this.logPath}.${i}`;
+                const newPath = `${this.logPath}.${i + 1}`;
+                try {
+                    await rename(oldPath, newPath);
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                }
+            }
+            await rename(this.logPath, `${this.logPath}.1`);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return;
+            throw err;
+        }
+    }
+}

package/build/config/credential-resolver.js

@@ -0,0 +1,107 @@
+import { readFile } from 'fs/promises';
+import { resolve } from 'path';
+let keyringGet = null;
+let keyringSet = null;
+export function isKeychainAvailable() {
+    return keyringGet !== null;
+}
+export async function initKeychain() {
+    try {
+        // @ts-ignore — optional dependency, may not be installed
+        const mod = await import('@napi-rs/keyring');
+        keyringGet = async (service, account) => {
+            const entry = new mod.Entry(service, account);
+            return (await entry.getPassword()) || null;
+        };
+        keyringSet = async (service, account, password) => {
+            const entry = new mod.Entry(service, account);
+            await entry.setPassword(password);
+        };
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function setKeychainEntry(service, account, password) {
+    if (!keyringSet)
+        throw new Error('Keychain not initialized. Install @napi-rs/keyring.');
+    await keyringSet(service, account, password);
+}
+export async function resolveCredentials(profile) {
+    const creds = {};
+    const envPrefix = `SSH_MCP_${profile.name.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+    if (process.env.SSH_AUTH_SOCK && profile.auth === 'agent') {
+        creds.agentSocket = process.env.SSH_AUTH_SOCK;
+    }
+    // Warn rather than silently walking down to a weaker credential source: a
+    // profile that asked for the OS keychain and got an env var instead has a
+    // different security posture than the operator configured.
+    if (profile.auth === 'keychain' && !keyringGet) {
+        console.error(`Profile "${profile.name}" requests auth = "keychain" but @napi-rs/keyring is unavailable ` +
+            '(it is an optional dependency). Falling back to the remaining credential sources.');
+    }
+    if (profile.auth === 'keychain' && profile.keychainEntry && keyringGet) {
+        try {
+            const [service, account] = profile.keychainEntry.split('/');
+            const secret = await keyringGet(service || 'ssh-mcp', account || profile.name);
+            if (secret) {
+                if (profile.keyRef) {
+                    creds.privateKey = secret;
+                }
+                else {
+                    creds.password = secret;
+                }
+            }
+        }
+        catch (err) {
+            console.error(`Keychain lookup failed for ${profile.keychainEntry}:`, err);
+        }
+    }
+    if (process.env[`${envPrefix}_PASSWORD`]) {
+        creds.password = creds.password || process.env[`${envPrefix}_PASSWORD`];
+    }
+    else if (process.env.SSH_MCP_PASSWORD) {
+        creds.password = creds.password || process.env.SSH_MCP_PASSWORD;
+    }
+    if (process.env[`${envPrefix}_SUDO_PASSWORD`]) {
+        creds.sudoPassword = process.env[`${envPrefix}_SUDO_PASSWORD`];
+    }
+    else if (process.env.SSH_MCP_SUDO_PASSWORD) {
+        creds.sudoPassword = process.env.SSH_MCP_SUDO_PASSWORD;
+    }
+    if (process.env[`${envPrefix}_PASSPHRASE`]) {
+        creds.passphrase = process.env[`${envPrefix}_PASSPHRASE`];
+    }
+    else if (process.env.SSH_MCP_PASSPHRASE) {
+        creds.passphrase = process.env.SSH_MCP_PASSPHRASE;
+    }
+    const keyPath = profile.keyRef || process.env[`${envPrefix}_KEY`] || process.env.SSH_MCP_KEY;
+    if (keyPath && !creds.privateKey) {
+        try {
+            creds.privateKey = await readFile(resolve(keyPath.replace(/^~/, process.env.HOME || '~')), 'utf8');
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    if (profile.cert && creds.privateKey) {
+        const certPath = process.env[`${envPrefix}_CERT`]
+            || (keyPath ? `${keyPath.replace(/\.pub$/, '')}-cert.pub` : undefined);
+        if (certPath) {
+            try {
+                creds.certificate = await readFile(resolve(certPath.replace(/^~/, process.env.HOME || '~')), 'utf8');
+            }
+            catch (err) {
+                if (err.code !== 'ENOENT')
+                    throw err;
+            }
+        }
+    }
+    if (!creds.password && !creds.privateKey && !creds.agentSocket) {
+        throw new Error(`No credentials resolved for profile "${profile.name}". ` +
+            `Available methods: SSH agent (SSH_AUTH_SOCK), OS keychain (auth=keychain), env vars (SSH_MCP_PASSWORD), or key file (SSH_MCP_KEY).`);
+    }
+    return creds;
+}

package/build/config/loader.js

@@ -0,0 +1,100 @@
+import { readFile, stat } from 'fs/promises';
+import { homedir, platform } from 'os';
+import { join, dirname } from 'path';
+import { parse as parseTOML } from 'smol-toml';
+import { configSchema } from './schema.js';
+export function getConfigPath(customPath) {
+    if (customPath)
+        return customPath;
+    const home = homedir();
+    const p = platform();
+    if (p === 'darwin') {
+        return join(home, 'Library', 'Application Support', 'ssh-mcp', 'config.toml');
+    }
+    if (p === 'win32') {
+        return join(process.env.APPDATA || join(home, 'AppData', 'Roaming'), 'ssh-mcp', 'config.toml');
+    }
+    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}`);
+        }
+        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;
+        throw err;
+    }
+}
+export async function loadConfig(customPath) {
+    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;
+    }
+    await checkPermissions(configPath);
+    let parsed;
+    try {
+        parsed = parseTOML(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse TOML config at ${configPath}: ${err.message}`);
+    }
+    const result = configSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Config validation error:\n${issues}`);
+    }
+    return normalizeConfig(result.data);
+}
+/**
+ * Resolve every profile against [defaults]. Each of these keys is documented as
+ * a default that profiles inherit, so all of them must cascade — a key that is
+ * accepted by the schema but never applied silently ignores the operator's
+ * configuration (an `approvalMode` that never takes effect is a security
+ * downgrade, not just a papercut).
+ */
+function normalizeConfig(raw) {
+    const defaults = {
+        ...raw.defaults,
+    };
+    const profiles = raw.profiles.map((p) => ({
+        ...p,
+        timeout: p.timeout ?? defaults.commandTimeoutMs,
+        maxChars: p.maxChars ?? defaults.commandMaxChars,
+        maxOutputBytes: p.maxOutputBytes ?? defaults.commandMaxOutputBytes,
+        approvalPolicy: p.approvalPolicy ?? defaults.approvalMode,
+        sessionMaxPerConnection: p.sessionMaxPerConnection ?? defaults.sessionMaxPerConnection,
+        sessionIdleTimeoutMs: p.sessionIdleTimeoutMs ?? defaults.sessionIdleTimeoutMs,
+        sessionBackgroundMaxMs: p.sessionBackgroundMaxMs ?? defaults.sessionBackgroundMaxMs,
+        commandQuotaPerDay: p.commandQuotaPerDay ?? defaults.commandQuotaPerDay,
+    }));
+    return { defaults, profiles };
+}
+export function getProfile(config, name) {
+    const targetName = name || config.defaults.defaultProfile;
+    if (!targetName) {
+        return config.profiles[0];
+    }
+    const profile = config.profiles.find((p) => p.name === targetName);
+    if (!profile)
+        throw new Error(`Profile "${targetName}" not found`);
+    return profile;
+}

package/build/config/schema.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+const authMethodSchema = z.enum(['agent', 'key', 'password', 'keychain']);
+const approvalModeSchema = z.enum(['auto', 'ask-destructive', 'ask-all', 'deny']);
+export const defaultsSchema = z.object({
+    defaultProfile: z.string().optional(),
+    sessionMaxPerConnection: z.number().int().positive().default(5),
+    sessionIdleTimeoutMs: z.number().int().positive().default(600_000),
+    sessionBackgroundMaxMs: z.number().int().positive().default(3_600_000),
+    commandTimeoutMs: z.number().int().positive().default(60_000),
+    commandMaxChars: z.number().int().positive().default(5000),
+    commandMaxOutputBytes: z.number().int().positive().default(1_048_576),
+    connectionIdleReapMs: z.number().int().positive().default(900_000),
+    // 0 = unlimited. A circuit breaker for runaway agents, not a rate limit.
+    commandQuotaPerDay: z.number().int().nonnegative().default(0),
+    // 0 = every destructive command prompts. Auto-approval weakens the gate, so
+    // it is opt-in rather than a default convenience.
+    approvalGrantTtlMs: z.number().int().nonnegative().default(0),
+    approvalMode: approvalModeSchema.default('ask-destructive'),
+}).strict();
+export const profileSchema = z.object({
+    name: z.string().min(1),
+    host: z.string().min(1),
+    port: z.number().int().min(1).max(65535).default(22),
+    user: z.string().min(1),
+    auth: authMethodSchema.default('agent'),
+    keyRef: z.string().optional(),
+    keychainEntry: z.string().optional(),
+    via: z.string().optional(),
+    // Drives the role-binding tier. Without it the tier is guessed from the
+    // profile name, and an unrecognised name resolves to the strictest tier.
+    group: z.string().optional(),
+    workdir: z.string().optional(),
+    trustedHostKey: z.string().optional(),
+    tty: z.boolean().default(false),
+    role: z.string().default('operator'),
+    readOnly: z.boolean().default(false),
+    cert: z.boolean().default(false),
+    // Left optional on purpose: normalizeConfig() fills these from [defaults], and
+    // a schema-level .default() would make "user omitted it" indistinguishable
+    // from "user set the default value", silently shadowing [defaults].
+    timeout: z.number().int().positive().optional(),
+    maxChars: z.number().int().positive().optional(),
+    maxOutputBytes: z.number().int().positive().optional(),
+    approvalPolicy: approvalModeSchema.optional(),
+    sessionMaxPerConnection: z.number().int().positive().optional(),
+    sessionIdleTimeoutMs: z.number().int().positive().optional(),
+    sessionBackgroundMaxMs: z.number().int().positive().optional(),
+    commandQuotaPerDay: z.number().int().nonnegative().optional(),
+}).strict();
+export const configSchema = z.object({
+    defaults: defaultsSchema.default({}),
+    profiles: z.array(profileSchema).min(1),
+});

package/build/guard/elicitation.js

@@ -0,0 +1,38 @@
+/**
+ * Ask the MCP client to confirm a destructive or privileged command.
+ *
+ * Uses the SDK's typed `Server.elicitInput()` rather than a hand-built
+ * `elicitation/create` envelope, so a protocol change breaks the build instead
+ * of silently disabling the gate that guards every destructive command.
+ *
+ * Fails closed: any error (client without elicitation support, transport
+ * failure, malformed reply) denies the command. The failure is logged, because
+ * a gate that always denies for an unnoticed reason is its own kind of outage.
+ */
+export async function requestApproval(server, command, profileName, evaluation) {
+    const message = `Confirm ${evaluation.commandClass} command on "${profileName}":\n\n${command}`;
+    try {
+        const result = await server.server.elicitInput({
+            message,
+            requestedSchema: {
+                type: 'object',
+                properties: {
+                    confirm: {
+                        type: 'boolean',
+                        title: 'Approve this command?',
+                    },
+                },
+                required: ['confirm'],
+            },
+        });
+        if (result.action === 'accept' && result.content?.confirm === true) {
+            return { approved: true, approver: 'mcp-client' };
+        }
+        return { approved: false };
+    }
+    catch (err) {
+        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 };
+    }
+}

package/build/guard/redactor.js

@@ -0,0 +1,67 @@
+const SENSITIVE_FIELDS = new Set([
+    'password', 'privateKey', 'sudoPassword', 'suPassword', 'passphrase',
+    'token', 'secret', 'apiKey', 'api_key', 'authorization',
+]);
+const REGEX_PATTERNS = [
+    { name: 'aws-access-key', pattern: /AKIA[0-9A-Z]{16}/g },
+    { name: 'github-token', pattern: /gh[pousr]_[A-Za-z0-9]{36,}/g },
+    { name: 'gitlab-token', pattern: /glpat-[A-Za-z0-9_-]{20}/g },
+    { name: 'jwt', pattern: /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g },
+    // Body is bounded: an unbounded lazy [\s\S]*? rescans to end-of-input for
+    // every BEGIN that has no matching END, so k unmatched markers in a 1MB
+    // output cost O(k x 1MB) of synchronous regex time. 64KB comfortably covers
+    // any real private key (an 8192-bit RSA key is well under 8KB).
+    { name: 'pem-private-key', pattern: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----[\s\S]{0,65536}?-----END (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/g },
+    { name: 'bearer-auth', pattern: /[Bb]earer\s+[A-Za-z0-9._~+\/-]+=*/g },
+    { name: 'generic-api-key', pattern: /(?:api[_-]?key|api[_-]?secret)["'\s]*[:=]\s*["']([A-Za-z0-9_\-]{20,})["']/gi },
+];
+function shannonEntropy(str) {
+    if (!str || str.length < 20)
+        return 0;
+    const freq = new Map();
+    for (const ch of str) {
+        freq.set(ch, (freq.get(ch) || 0) + 1);
+    }
+    let entropy = 0;
+    for (const count of freq.values()) {
+        const p = count / str.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+export function redactText(text, opts = {}) {
+    let result = text;
+    for (const { name, pattern } of REGEX_PATTERNS) {
+        result = result.replace(pattern, (match) => {
+            return `[REDACTED:${name}:${match.length}]`;
+        });
+    }
+    if (opts.entropyScan) {
+        const threshold = opts.entropyThreshold ?? 4.5;
+        result = result.replace(/[A-Za-z0-9+/=_-]{20,}/g, (match) => {
+            if (shannonEntropy(match) > threshold) {
+                return `[REDACTED:entropy:${match.length}]`;
+            }
+            return match;
+        });
+    }
+    return result;
+}
+export function redactRecord(obj, opts = {}) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (SENSITIVE_FIELDS.has(key) || /(?<![^a-z])(token|secret|key|password)$/i.test(key)) {
+            result[key] = '[REDACTED]';
+        }
+        else if (typeof value === 'string') {
+            result[key] = redactText(value, opts);
+        }
+        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            result[key] = redactRecord(value, opts);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/build/guard/sanitizer.js

@@ -0,0 +1,24 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+const CONTROL_CHARS = /[\r\n\u2028\u2029\x00]/g;
+export function sanitizeCommand(command, maxChars) {
+    if (typeof command !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'Command must be a string');
+    }
+    const cleaned = command.replace(CONTROL_CHARS, ' ').trim();
+    if (!cleaned) {
+        throw new McpError(ErrorCode.InvalidParams, 'Command cannot be empty');
+    }
+    if (Number.isFinite(maxChars) && cleaned.length > maxChars) {
+        throw new McpError(ErrorCode.InvalidParams, `Command is too long (max ${maxChars} characters)`);
+    }
+    return cleaned;
+}
+export function sanitizeSessionName(name) {
+    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(name)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Session name must be 1-64 chars, alphanumeric/dash/underscore only');
+    }
+    return name;
+}
+export function shellSingleQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}