@kontextmind/kxm 0.7.5 → 0.7.7

package/plugins/kxm/src/ssh-remote.ts

@@ -0,0 +1,560 @@
+/**
+ * Multiplexed remote SSH execution, worker orchestration, and secure config discovery.
+ *
+ * Implements:
+ * - Safe `~/.ssh/config` parsing and alias discovery without socket connections or credential leaks.
+ * - OpenSSH `ControlMaster` connection reuse (.kxm/run/ssh-sockets/%C) for low-latency command execution.
+ * - In-memory masked credential passing via `sshpass -e` (env) and `sudo -S -p ''` (stdin).
+ * - Safety seatbelt validation and pinned host key verification.
+ * - Output bounding and truncation (50KB / 2000 lines).
+ */
+
+import { spawnSync, type SpawnSyncOptionsWithStringEncoding } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { assertCommandSeatbelt, assertPinnedSshHostKeyPolicy } from "./safety-integrity.ts";
+
+export const MAX_SSH_OUTPUT_BYTES = 50 * 1024; // 50KB
+export const MAX_SSH_OUTPUT_LINES = 2000;
+export const DEFAULT_SOCKET_DIR = ".kxm/run/ssh-sockets";
+export const DEFAULT_CONTROL_PERSIST = "10m";
+
+export interface SshHostInfo {
+  alias: string;
+  hostName?: string | undefined;
+  user?: string | undefined;
+  port?: number | undefined;
+  proxyJump?: string | undefined;
+  identityFiles?: string[] | undefined;
+}
+
+export interface SshRunParams {
+  action: "info" | "command" | "file";
+  host?: string | undefined;
+  command?: string | undefined;
+  sudo?: boolean | undefined;
+  file_path?: string | undefined;
+  file_content?: string | undefined;
+  file_op?: "write" | "read" | "append" | undefined;
+  reason?: string | undefined;
+  password?: string | undefined;
+  sudo_password?: string | undefined;
+  socket_dir?: string | undefined;
+  control_persist?: string | undefined;
+  timeout_ms?: number | undefined;
+  strict_host_key?: boolean | undefined;
+  execFn?: ((cmd: string, args: string[], options: SpawnSyncOptionsWithStringEncoding) => {
+    status: number | null;
+    stdout: string | Buffer;
+    stderr: string | Buffer;
+    error?: Error | undefined;
+  }) | undefined;
+}
+
+export interface SshExecutionReceipt {
+  ok: boolean;
+  action: "info" | "command" | "file";
+  host?: string | undefined;
+  resolvedHost?: string | undefined;
+  user?: string | undefined;
+  port?: number | undefined;
+  exitCode?: number | undefined;
+  stdout?: string | undefined;
+  stderr?: string | undefined;
+  durationMs?: number | undefined;
+  truncated?: boolean | undefined;
+  socketReused?: boolean | undefined;
+  fileProcessed?: string | undefined;
+  bytesProcessed?: number | undefined;
+  hosts?: SshHostInfo[] | undefined;
+  error?: string | undefined;
+}
+
+/**
+ * Truncates output to 50KB and 2000 lines max.
+ */
+export function truncateSshOutput(raw: string): { text: string; truncated: boolean } {
+  let text = raw;
+  let truncated = false;
+
+  if (Buffer.byteLength(text, "utf-8") > MAX_SSH_OUTPUT_BYTES) {
+    const buf = Buffer.from(text, "utf-8");
+    text = buf.subarray(0, MAX_SSH_OUTPUT_BYTES).toString("utf-8");
+    truncated = true;
+  }
+
+  const lines = text.split("\n");
+  if (lines.length > MAX_SSH_OUTPUT_LINES) {
+    text = lines.slice(0, MAX_SSH_OUTPUT_LINES).join("\n");
+    truncated = true;
+  }
+
+  if (truncated) {
+    text += `\n\n[kxm: ssh output truncated to ${MAX_SSH_OUTPUT_BYTES / 1024}KB / ${MAX_SSH_OUTPUT_LINES} lines]`;
+  }
+
+  return { text, truncated };
+}
+
+/**
+ * Parses ~/.ssh/config safely to list host aliases and their configurations.
+ * Does not read private key files or open network sockets.
+ */
+export function parseSshConfig(configPath?: string): SshHostInfo[] {
+  const targetPath = configPath ?? join(homedir(), ".ssh", "config");
+  if (!existsSync(targetPath)) {
+    return [];
+  }
+
+  try {
+    const content = readFileSync(targetPath, "utf-8");
+    const lines = content.split("\n");
+    const hosts: SshHostInfo[] = [];
+    let currentHosts: SshHostInfo[] = [];
+
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith("#")) continue;
+
+      const spaceIdx = line.search(/\s/);
+      if (spaceIdx === -1) continue;
+
+      const key = line.slice(0, spaceIdx).trim().toLowerCase();
+      const value = line.slice(spaceIdx + 1).trim();
+
+      if (key === "host") {
+        // Space-separated host patterns; skip wildcard-only matches like "*"
+        const aliases = value.split(/\s+/).filter((a) => a !== "*");
+        currentHosts = [];
+        for (const alias of aliases) {
+          const entry: SshHostInfo = { alias, identityFiles: [] };
+          currentHosts.push(entry);
+          hosts.push(entry);
+        }
+      } else if (currentHosts.length > 0) {
+        for (const currentHost of currentHosts) {
+          if (key === "hostname") {
+            currentHost.hostName = value;
+          } else if (key === "user") {
+            currentHost.user = value;
+          } else if (key === "port") {
+            const p = Number.parseInt(value, 10);
+            if (!Number.isNaN(p)) currentHost.port = p;
+          } else if (key === "proxyjump") {
+            currentHost.proxyJump = value;
+          } else if (key === "identityfile") {
+            currentHost.identityFiles = currentHost.identityFiles ?? [];
+            currentHost.identityFiles.push(value);
+          }
+        }
+      }
+    }
+
+    return hosts;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolves effective SSH parameters for a specific host using `ssh -G <host>`.
+ * Does not initiate any network connections.
+ */
+export function resolveSshHostG(
+  host: string,
+  execFn: typeof spawnSync = spawnSync,
+): SshHostInfo {
+  try {
+    const result = execFn("ssh", ["-G", host], { encoding: "utf-8" });
+    if (result.status !== 0 || !result.stdout) {
+      return { alias: host, hostName: host };
+    }
+
+    const lines = String(result.stdout).split("\n");
+    const info: SshHostInfo = { alias: host, identityFiles: [] };
+
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (!line) continue;
+      const spaceIdx = line.indexOf(" ");
+      if (spaceIdx === -1) continue;
+
+      const key = line.slice(0, spaceIdx).toLowerCase();
+      const value = line.slice(spaceIdx + 1).trim();
+
+      if (key === "hostname") {
+        info.hostName = value;
+      } else if (key === "user") {
+        info.user = value;
+      } else if (key === "port") {
+        const p = Number.parseInt(value, 10);
+        if (!Number.isNaN(p)) info.port = p;
+      } else if (key === "proxyjump") {
+        if (value && value !== "none") info.proxyJump = value;
+      } else if (key === "identityfile") {
+        info.identityFiles = info.identityFiles ?? [];
+        info.identityFiles.push(value);
+      }
+    }
+
+    return info;
+  } catch {
+    return { alias: host, hostName: host };
+  }
+}
+
+/**
+ * Ensures control socket directory exists with secure permissions (0700).
+ */
+export function ensureSocketDir(socketDir: string = DEFAULT_SOCKET_DIR): string {
+  const resolved = resolve(socketDir);
+  if (!existsSync(resolved)) {
+    mkdirSync(resolved, { recursive: true, mode: 0o700 });
+  }
+  return resolved;
+}
+
+/**
+ * Formats standard OpenSSH arguments including ControlMaster multiplexing
+ * and safety invariants.
+ */
+export function buildSshArgs(options: {
+  host: string;
+  socketDir?: string | undefined;
+  controlPersist?: string | undefined;
+  batchMode?: boolean | undefined;
+  strictHostKey?: boolean | undefined;
+  extraArgs?: string[] | undefined;
+}): string[] {
+  const socketDir = ensureSocketDir(options.socketDir ?? DEFAULT_SOCKET_DIR);
+  const controlPath = join(socketDir, "%C");
+  const persist = options.controlPersist ?? DEFAULT_CONTROL_PERSIST;
+
+  const args: string[] = [
+    "-o", `ControlMaster=auto`,
+    "-o", `ControlPath=${controlPath}`,
+    "-o", `ControlPersist=${persist}`,
+  ];
+
+  if (options.batchMode !== false) {
+    args.push("-o", "BatchMode=yes");
+  }
+
+  if (options.strictHostKey !== false) {
+    args.push("-o", "StrictHostKeyChecking=yes");
+  }
+
+  if (options.extraArgs) {
+    args.push(...options.extraArgs);
+  }
+
+  // Validate that no insecure host key flags are present
+  assertPinnedSshHostKeyPolicy(args);
+
+  args.push(options.host);
+  return args;
+}
+
+/**
+ * Checks if a ControlMaster socket is active for the target host.
+ */
+export function checkControlSocket(
+  host: string,
+  socketDir: string = DEFAULT_SOCKET_DIR,
+  execFn: typeof spawnSync = spawnSync,
+): boolean {
+  const resolvedDir = ensureSocketDir(socketDir);
+  const controlPath = join(resolvedDir, "%C");
+  try {
+    const result = execFn("ssh", ["-O", "check", "-o", `ControlPath=${controlPath}`, host], {
+      encoding: "utf-8",
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Closes an active ControlMaster socket for the target host.
+ */
+export function closeControlSocket(
+  host: string,
+  socketDir: string = DEFAULT_SOCKET_DIR,
+  execFn: typeof spawnSync = spawnSync,
+): boolean {
+  const resolvedDir = ensureSocketDir(socketDir);
+  const controlPath = join(resolvedDir, "%C");
+  try {
+    const result = execFn("ssh", ["-O", "stop", "-o", `ControlPath=${controlPath}`, host], {
+      encoding: "utf-8",
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Cleans up all orphaned or expired ControlMaster sockets in the socket directory.
+ */
+export function pruneSocketDir(socketDir: string = DEFAULT_SOCKET_DIR): number {
+  const resolvedDir = ensureSocketDir(socketDir);
+  let removed = 0;
+  try {
+    const entries = readdirSync(resolvedDir);
+    for (const entry of entries) {
+      const fullPath = join(resolvedDir, entry);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isSocket()) {
+          rmSync(fullPath, { force: true });
+          removed++;
+        }
+      } catch {
+        // Skip unreadable entries
+      }
+    }
+  } catch {
+    // Ignore directory read errors
+  }
+  return removed;
+}
+
+/**
+ * Main execution handler for `ssh_run` tool.
+ */
+export function executeSshRun(params: SshRunParams): SshExecutionReceipt {
+  const startTime = Date.now();
+  const execSyncFn = params.execFn ?? spawnSync;
+
+  // 1. Action: "info"
+  if (params.action === "info") {
+    if (params.host) {
+      const hostInfo = resolveSshHostG(params.host, execSyncFn as typeof spawnSync);
+      return {
+        ok: true,
+        action: "info",
+        host: params.host,
+        resolvedHost: hostInfo.hostName ?? params.host,
+        user: hostInfo.user,
+        port: hostInfo.port,
+        hosts: [hostInfo],
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    const discovered = parseSshConfig();
+    return {
+      ok: true,
+      action: "info",
+      hosts: discovered,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  // Require host for command and file actions
+  if (!params.host) {
+    return {
+      ok: false,
+      action: params.action,
+      error: 'Parameter "host" is required for command and file actions.',
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  const host = params.host;
+  const socketDir = params.socket_dir ?? DEFAULT_SOCKET_DIR;
+  const wasSocketActive = checkControlSocket(host, socketDir, execSyncFn as typeof spawnSync);
+
+  // 2. Action: "command"
+  if (params.action === "command") {
+    if (!params.command) {
+      return {
+        ok: false,
+        action: "command",
+        host,
+        error: 'Parameter "command" is required for command action.',
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    // Safety check: block destructive commands
+    try {
+      assertCommandSeatbelt(params.command);
+    } catch (err: unknown) {
+      return {
+        ok: false,
+        action: "command",
+        host,
+        error: (err as Error).message,
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    let remoteCommand = params.command;
+    let inputStdin: string | undefined = undefined;
+
+    // Handle remote sudo via stdin pipe
+    if (params.sudo) {
+      const sudoPwd = params.sudo_password ?? params.password;
+      if (sudoPwd) {
+        inputStdin = `${sudoPwd}\n`;
+        remoteCommand = `sudo -S -p '' -- sh -c ${JSON.stringify(params.command)}`;
+      } else {
+        remoteCommand = `sudo -- sh -c ${JSON.stringify(params.command)}`;
+      }
+    }
+
+    const useSshPass = Boolean(params.password);
+    const sshArgs = buildSshArgs({
+      host,
+      socketDir,
+      controlPersist: params.control_persist,
+      batchMode: !useSshPass,
+      strictHostKey: params.strict_host_key,
+    });
+    sshArgs.push("--", remoteCommand);
+
+    const spawnEnv: NodeJS.ProcessEnv = { ...process.env };
+    let binary = "ssh";
+    let finalArgs = sshArgs;
+
+    // Masked credential security: SSH password via SSHPASS environment variable
+    if (useSshPass && params.password) {
+      binary = "sshpass";
+      finalArgs = ["-e", "ssh", ...sshArgs];
+      spawnEnv.SSHPASS = params.password;
+    }
+
+    try {
+      const result = execSyncFn(binary, finalArgs, {
+        encoding: "utf-8",
+        env: spawnEnv,
+        input: inputStdin,
+        timeout: params.timeout_ms ?? 120_000,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+
+      const stdoutRaw = String(result.stdout || "");
+      const stderrRaw = String(result.stderr || "");
+
+      // Sanitize stderr from potential sudo password echoes
+      const sanitizedStderr = stderrRaw.replace(/\[sudo\] password for [^:]+:\s*/gi, "");
+
+      const stdoutTrunc = truncateSshOutput(stdoutRaw);
+      const stderrTrunc = truncateSshOutput(sanitizedStderr);
+
+      return {
+        ok: result.status === 0,
+        action: "command",
+        host,
+        exitCode: result.status ?? 1,
+        stdout: stdoutTrunc.text,
+        stderr: stderrTrunc.text,
+        truncated: stdoutTrunc.truncated || stderrTrunc.truncated,
+        socketReused: wasSocketActive,
+        durationMs: Date.now() - startTime,
+        error: result.error ? result.error.message : undefined,
+      };
+    } catch (err: unknown) {
+      return {
+        ok: false,
+        action: "command",
+        host,
+        error: (err as Error).message,
+        durationMs: Date.now() - startTime,
+      };
+    }
+  }
+
+  // 3. Action: "file"
+  if (params.action === "file") {
+    if (!params.file_path) {
+      return {
+        ok: false,
+        action: "file",
+        host,
+        error: 'Parameter "file_path" is required for file action.',
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    const filePath = params.file_path;
+    const op = params.file_op ?? "write";
+
+    if (op === "read") {
+      const readCmd = params.sudo ? `sudo cat ${JSON.stringify(filePath)}` : `cat ${JSON.stringify(filePath)}`;
+      return executeSshRun({
+        ...params,
+        action: "command",
+        command: readCmd,
+      });
+    }
+
+    const content = params.file_content ?? "";
+    const redirectOp = op === "append" ? ">>" : ">";
+    const writeCmd = params.sudo
+      ? `sudo tee ${op === "append" ? "-a " : ""}${JSON.stringify(filePath)} > /dev/null`
+      : `cat ${redirectOp} ${JSON.stringify(filePath)}`;
+
+    const useSshPass = Boolean(params.password);
+    const sshArgs = buildSshArgs({
+      host,
+      socketDir,
+      controlPersist: params.control_persist,
+      batchMode: !useSshPass,
+      strictHostKey: params.strict_host_key,
+    });
+    sshArgs.push("--", writeCmd);
+
+    const spawnEnv: NodeJS.ProcessEnv = { ...process.env };
+    let binary = "ssh";
+    let finalArgs = sshArgs;
+
+    if (useSshPass && params.password) {
+      binary = "sshpass";
+      finalArgs = ["-e", "ssh", ...sshArgs];
+      spawnEnv.SSHPASS = params.password;
+    }
+
+    try {
+      const result = execSyncFn(binary, finalArgs, {
+        encoding: "utf-8",
+        env: spawnEnv,
+        input: content,
+        timeout: params.timeout_ms ?? 60_000,
+      });
+
+      return {
+        ok: result.status === 0,
+        action: "file",
+        host,
+        exitCode: result.status ?? 1,
+        stdout: String(result.stdout || ""),
+        stderr: String(result.stderr || ""),
+        fileProcessed: filePath,
+        bytesProcessed: Buffer.byteLength(content, "utf-8"),
+        socketReused: wasSocketActive,
+        durationMs: Date.now() - startTime,
+        error: result.error ? result.error.message : undefined,
+      };
+    } catch (err: unknown) {
+      return {
+        ok: false,
+        action: "file",
+        host,
+        error: (err as Error).message,
+        durationMs: Date.now() - startTime,
+      };
+    }
+  }
+
+  return {
+    ok: false,
+    action: params.action,
+    error: `Unknown action: ${(params as { action: string }).action}`,
+    durationMs: Date.now() - startTime,
+  };
+}

package/schemas/vnext/modes.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/vnext/modes.schema.json",
+  "title": "KXM Modes Configuration",
+  "description": "Declarative major modes and domain modules for selective tool loading and context scoping",
+  "type": "object",
+  "required": ["schema", "majorModes"],
+  "properties": {
+    "schema": { "const": "kxm.modes.v1" },
+    "majorModes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["baseTools"],
+        "properties": {
+          "description": { "type": "string" },
+          "baseTools": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "contextFiles": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "thinkingLevel": {
+            "type": "string",
+            "enum": ["low", "medium", "high", "xhigh"]
+          },
+          "model": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "domains": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["tools"],
+        "properties": {
+          "description": { "type": "string" },
+          "tools": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "contextFiles": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "promptSnippet": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}