machine-bridge-mcp 0.18.0 → 1.0.0

package/src/local/runtime.mjs

@@ -2,11 +2,11 @@ import { randomBytes } from "node:crypto";
 import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { lstat, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import path, { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { RelayConnection } from "./relay-connection.mjs";
-import { MAX_COMMAND_BYTES, ProcessSessionManager } from "./process-sessions.mjs";
+import { ProcessSessionManager } from "./process-sessions.mjs";
 export { MAX_COMMAND_BYTES } from "./process-sessions.mjs";
-import { allToolNames, assertCanonicalFullPolicy, isCanonicalFullPolicy, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, normalizePolicy, POLICY_PROFILES, PolicyGate, SERVER_NAME } from "./tools.mjs";
+import { allToolNames, isCanonicalFullPolicy, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, normalizePolicy, POLICY_PROFILES, PolicyGate, SERVER_NAME } from "./tools.mjs";
 import { publicError } from "./errors.mjs";
 import { ProcessTracker } from "./process-tracker.mjs";
 import { CallRegistry } from "./call-registry.mjs";
@@ -367,9 +367,15 @@ export class LocalRuntime {
     const envelope = normalizeRelayToolCall(message);
     if (!envelope.ok) {
       this.logger.event?.("warn", "relay.tool_call.invalid", { has_call_id: Boolean(envelope.id) });
-      if (envelope.id) this.send({ type: "tool_result", id: envelope.id, ok: false, error: { code: "invalid_request", message: "invalid tool_call envelope", retryable: false } });
+      if (envelope.id) this.deliverRelayToolResult({
+        type: "tool_result",
+        id: envelope.id,
+        ok: false,
+        error: { code: "invalid_request", message: "invalid tool_call envelope", retryable: false },
+      });
       return;
     }
+    let response;
     try {
       const result = await this.executeTool(envelope.tool, envelope.arguments, {
         callId: envelope.id,
@@ -377,10 +383,18 @@ export class LocalRuntime {
         timeoutMs: envelope.timeoutMs,
         authorization: envelope.authorization,
       });
-      this.send({ type: "tool_result", id: envelope.id, ok: true, result });
+      response = { type: "tool_result", id: envelope.id, ok: true, result };
     } catch (error) {
-      this.send({ type: "tool_result", id: envelope.id, ok: false, error: publicError(error) });
+      response = { type: "tool_result", id: envelope.id, ok: false, error: publicError(error) };
     }
+    this.deliverRelayToolResult(response);
+  }
+
+  deliverRelayToolResult(response) {
+    if (this.send(response)) return true;
+    this.logger.event?.("warn", "relay.tool_result.delivery_failed", { call_id: shortCallId(response?.id) });
+    this.relay?.interrupt?.("relay_transport_error");
+    return false;
   }
 
   finishCall(callId) {

package/src/local/secure-file.mjs

@@ -1,17 +1,50 @@
-import { closeSync, constants as fsConstants, fstatSync, openSync, readSync } from "node:fs";
+import { closeSync, constants as fsConstants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readSync } from "node:fs";
 
-export function readBoundedRegularFileSync(file, maxBytes) {
-  return readBoundedRegularFileWithInfoSync(file, maxBytes).buffer;
+export function openRegularFileSync(file, flags, options = {}) {
+  const mode = Number.isInteger(options.mode) ? options.mode : undefined;
+  const label = String(options.label || "path");
+  const noFollow = Number(fsConstants.O_NOFOLLOW || 0);
+  let fd;
+  try {
+    fd = mode === undefined
+      ? openSync(file, Number(flags) | noFollow)
+      : openSync(file, Number(flags) | noFollow, mode);
+  } catch (error) {
+    if (error?.code === "ELOOP") throw new Error(`${label} must not be a symbolic link`, { cause: error });
+    throw error;
+  }
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile()) throw new Error(`${label} is not a regular file`);
+    if (Number.isInteger(options.chmod)) setDescriptorMode(fd, options.chmod);
+    return { fd, info };
+  } catch (error) {
+    closeSync(fd);
+    throw error;
+  }
+}
+
+function withRegularFileSync(file, flags, options, callback) {
+  const opened = openRegularFileSync(file, flags, options);
+  try {
+    return callback(opened.fd, opened.info);
+  } finally {
+    closeSync(opened.fd);
+  }
+}
+
+export function chmodRegularFileSync(file, mode, label = "path") {
+  return withRegularFileSync(file, fsConstants.O_RDONLY, { label, chmod: mode }, () => undefined);
+}
+
+export function readBoundedRegularFileSync(file, maxBytes, label = "path") {
+  return readBoundedRegularFileWithInfoSync(file, maxBytes, label).buffer;
 }
 
-export function readBoundedRegularFileWithInfoSync(file, maxBytes) {
+export function readBoundedRegularFileWithInfoSync(file, maxBytes, label = "path") {
   const limit = Number(maxBytes);
   if (!Number.isSafeInteger(limit) || limit < 0) throw new Error("maximum file size must be a non-negative safe integer");
-  const flags = Number(fsConstants.O_RDONLY) | Number(fsConstants.O_NOFOLLOW || 0);
-  const fd = openSync(file, flags);
-  try {
-    const info = fstatSync(fd);
-    if (!info.isFile()) throw new Error("path is not a regular file");
+  return withRegularFileSync(file, fsConstants.O_RDONLY, { label }, (fd, info) => {
     if (info.size > limit) throw new Error(`file exceeds ${limit} bytes`);
     const buffer = Buffer.alloc(info.size);
     let offset = 0;
@@ -21,7 +54,53 @@ export function readBoundedRegularFileWithInfoSync(file, maxBytes) {
       offset += count;
     }
     return { buffer: buffer.subarray(0, offset), info };
+  });
+}
+
+export function ensureOwnerOnlyDirectorySync(dir, options = {}) {
+  const platform = String(options.platform || process.platform);
+  const makeDirectory = options.mkdirSync || mkdirSync;
+  const inspectPath = options.lstatSync || lstatSync;
+  makeDirectory(dir, { recursive: true, mode: 0o700 });
+  if (platform === "win32") {
+    const info = inspectPath(dir);
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error("owner-only path must be a real directory");
+    return info;
+  }
+
+  const noFollow = Number(fsConstants.O_NOFOLLOW || 0);
+  const directoryOnly = Number(fsConstants.O_DIRECTORY || 0);
+  if (!noFollow || !directoryOnly) throw new Error("secure owner-only directory descriptors are unavailable on this platform");
+  const open = options.openSync || openSync;
+  const inspectDescriptor = options.fstatSync || fstatSync;
+  const restrictDescriptor = options.fchmodSync || fchmodSync;
+  const close = options.closeSync || closeSync;
+  let fd;
+  try {
+    fd = open(dir, Number(fsConstants.O_RDONLY) | noFollow | directoryOnly);
+  } catch (error) {
+    if (["ELOOP", "ENOTDIR"].includes(error?.code)) throw new Error("owner-only path must be a real directory and not a symbolic link", { cause: error });
+    throw error;
+  }
+  try {
+    let info = inspectDescriptor(fd);
+    if (!info.isDirectory()) throw new Error("owner-only path must be a directory");
+    try {
+      restrictDescriptor(fd, 0o700);
+    } catch (error) {
+      throw new Error("could not restrict owner-only directory permissions", { cause: error });
+    }
+    info = inspectDescriptor(fd);
+    if (!info.isDirectory()) throw new Error("owner-only directory identity changed during permission enforcement");
+    if ((info.mode & 0o077) !== 0) throw new Error("owner-only directory remains accessible to group or other users");
+    return info;
   } finally {
-    closeSync(fd);
+    if (fd !== undefined) close(fd);
+  }
+}
+
+function setDescriptorMode(fd, mode) {
+  try { fchmodSync(fd, mode); } catch (error) {
+    if (process.platform !== "win32") throw error;
   }
 }

package/src/local/service-convergence.mjs

@@ -0,0 +1,20 @@
+const DEFAULT_ATTEMPTS = 20;
+const DEFAULT_DELAY_MS = 100;
+
+export async function waitForInactiveStatus(
+  readStatus,
+  { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, sleep = delay } = {},
+) {
+  if (typeof readStatus !== "function") throw new TypeError("readStatus must be a function");
+  const maximum = Number.isInteger(attempts) && attempts > 0 ? attempts : DEFAULT_ATTEMPTS;
+  let status = await readStatus();
+  for (let attempt = 1; status?.active === true && attempt < maximum; attempt += 1) {
+    await sleep(delayMs);
+    status = await readStatus();
+  }
+  return status;
+}
+
+function delay(milliseconds) {
+  return new Promise(resolve => setTimeout(resolve, milliseconds));
+}

package/src/local/service.mjs

@@ -1,10 +1,11 @@
-import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, rmSync, statSync, writeSync } from "node:fs";
+import { closeSync, constants as fsConstants, existsSync, ftruncateSync, lstatSync, mkdirSync, readSync, realpathSync, rmSync, statSync, writeSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { run } from "./shell.mjs";
-import { ensureOwnerOnlyDir, expandHome, ownerOnlyFile } from "./state.mjs";
+import { runExecutable } from "./shell.mjs";
+import { ensureOwnerOnlyDir, expandHome } from "./state.mjs";
 import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
-import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { openRegularFileSync, readBoundedRegularFileSync } from "./secure-file.mjs";
+import { waitForInactiveStatus } from "./service-convergence.mjs";
 
 const LABEL = "dev.machine-bridge-mcp.daemon";
 const WINDOWS_TASK = "MachineBridgeMCP";
@@ -12,7 +13,11 @@ const SERVICE_COMMAND_OUTPUT_BYTES = 64 * 1024;
 const AUTOSTART_LOG_SCHEMA_VERSION = 3;
 
 function serviceRun(command, args) {
-  return run(command, args, {
+  return runServiceCommand(command, args);
+}
+
+export function runServiceCommand(command, args, execute = runExecutable) {
+  return execute(command, args, {
     capture: true,
     allowFailure: true,
     maxOutputBytes: SERVICE_COMMAND_OUTPUT_BYTES,
@@ -33,9 +38,9 @@ export async function uninstallAutostart({ stateRoot, logger = console } = {}) {
 }
 
 export async function autostartStatus({ logger = console } = {}) {
-  if (process.platform === "darwin") return statusLaunchd(logger);
-  if (process.platform === "win32") return statusWindowsTask(logger);
-  return statusSystemd(logger);
+  if (process.platform === "darwin") return statusLaunchd();
+  if (process.platform === "win32") return statusWindowsTask();
+  return statusSystemd();
 }
 
 export async function startAutostart({ logger = console } = {}) {
@@ -81,21 +86,18 @@ export function trimAutostartLogs(stateRoot, options = {}) {
     const file = path.join(logs, name);
     let fd;
     try {
-      if (!existsSync(file)) continue;
-      const before = lstatSync(file);
-      if (before.isSymbolicLink() || !before.isFile()) continue;
-      const noFollow = Number(fsConstants.O_NOFOLLOW || 0);
-      fd = openSync(file, Number(fsConstants.O_RDWR) | noFollow);
-      const info = fstatSync(fd);
-      if (!info.isFile()) continue;
+      const opened = openRegularFileSync(file, fsConstants.O_RDWR, {
+        label: "autostart log path",
+        chmod: 0o600,
+      });
+      fd = opened.fd;
       if (reset) {
         ftruncateSync(fd, 0);
-      } else if (info.size > maxBytes) {
-        const tail = readLogTail(fd, info.size, keepBytes);
+      } else if (opened.info.size > maxBytes) {
+        const tail = readLogTail(fd, opened.info.size, keepBytes);
         ftruncateSync(fd, 0);
         if (tail.length) writeSync(fd, tail, 0, tail.length, 0);
       }
-      try { chmodSync(file, 0o600); } catch {}
     } catch {
       // Log maintenance is best effort and must not stop daemon startup.
     } finally {
@@ -212,28 +214,17 @@ export function daemonArgs(spec) {
 }
 
 function ensurePrivateLogFile(file) {
-  if (existsSync(file)) {
-    const info = lstatSync(file);
-    if (info.isSymbolicLink() || !info.isFile()) throw new Error("autostart log path must be a regular non-symbolic-link file");
-  }
-  const noFollow = Number(fsConstants.O_NOFOLLOW || 0);
-  const fd = openSync(file, Number(fsConstants.O_WRONLY) | Number(fsConstants.O_CREAT) | Number(fsConstants.O_APPEND) | noFollow, 0o600);
-  try {
-    if (!fstatSync(fd).isFile()) throw new Error("autostart log path is not a regular file");
-  } finally {
-    closeSync(fd);
-  }
-  ownerOnlyFile(file);
+  const opened = openRegularFileSync(
+    file,
+    Number(fsConstants.O_WRONLY) | Number(fsConstants.O_CREAT) | Number(fsConstants.O_APPEND),
+    { label: "autostart log path", mode: 0o600, chmod: 0o600 },
+  );
+  closeSync(opened.fd);
 }
 
 function writePrivateServiceFile(file, content) {
   mkdirSync(path.dirname(file), { recursive: true });
-  if (existsSync(file)) {
-    const info = lstatSync(file);
-    if (info.isSymbolicLink() || !info.isFile()) throw new Error("autostart configuration path must be a regular non-symbolic-link file");
-  }
   replaceFileAtomicallySync(file, content, { mode: 0o600 });
-  ownerOnlyFile(file);
 }
 
 function launchdPlistPath() {
@@ -299,9 +290,10 @@ async function stopLaunchd(logger) {
   const byPlist = byServiceTarget.code === 0
     ? null
     : await serviceRun("launchctl", ["bootout", domainTarget, plistPath]);
-  const after = await statusLaunchd();
+  const after = await waitForInactiveStatus(statusLaunchd);
   const rawResult = byPlist || byServiceTarget;
-  const ok = !after.active;
+  const active = after?.active !== false;
+  const ok = !active;
   if (ok) logger.info?.("launchd service stopped");
   else logger.warn?.("launchd service is still active after the stop request");
   return {
@@ -310,7 +302,7 @@ async function stopLaunchd(logger) {
     provider: "launchd",
     installed: existsSync(plistPath),
     active_before: true,
-    active: after.active,
+    active,
     already_stopped: false,
     code: ok ? 0 : rawResult.code,
     bootout_service_target: byServiceTarget,

package/src/local/shell.mjs

@@ -4,11 +4,13 @@ import path from "node:path";
 import { packageRoot } from "./state.mjs";
 import { BoundedOutput } from "./bounded-output.mjs";
 
-export function run(command, args = [], options = {}) {
+export function runExecutable(command, args = [], options = {}) {
+  const executable = validateExecutable(command);
+  const argv = validateExecutableArgs(args);
   return new Promise((resolve, reject) => {
     const capture = Boolean(options.capture);
     const maxOutputBytes = Number.isFinite(Number(options.maxOutputBytes)) ? Math.max(1024, Number(options.maxOutputBytes)) : 2 * 1024 * 1024;
-    const child = spawn(command, args, {
+    const child = spawn(executable, argv, {
       cwd: options.cwd || process.cwd(),
       env: options.env || process.env,
       stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
@@ -54,7 +56,7 @@ export function run(command, args = [], options = {}) {
       };
       if ((!timedOut && code === 0) || options.allowFailure) resolve(result);
       else {
-        const error = new Error((result.stderr || result.stdout || `${command} exited ${result.code}`).trim());
+        const error = new Error((result.stderr || result.stdout || `${executable} exited ${result.code}`).trim());
         error.result = result;
         reject(error);
       }
@@ -63,6 +65,25 @@ export function run(command, args = [], options = {}) {
 }
 
 
+function validateExecutable(value) {
+  if (typeof value !== "string" || !value || value.includes("\0")) {
+    throw new TypeError("executable must be a non-empty string without NUL bytes");
+  }
+  if (Buffer.byteLength(value) > 32 * 1024) throw new RangeError("executable path exceeds 32 KiB");
+  return value;
+}
+
+function validateExecutableArgs(value) {
+  if (!Array.isArray(value) || value.length > 4096) throw new TypeError("executable arguments must be an array with at most 4096 entries");
+  let totalBytes = 0;
+  return value.map((entry) => {
+    if (typeof entry !== "string" || entry.includes("\0")) throw new TypeError("executable arguments must be strings without NUL bytes");
+    totalBytes += Buffer.byteLength(entry);
+    if (totalBytes > 1024 * 1024) throw new RangeError("executable arguments exceed 1 MiB");
+    return entry;
+  });
+}
+
 function terminateCommandTree(child, force) {
   if (!child?.pid) return;
   if (process.platform === "win32") {
@@ -94,16 +115,14 @@ function capturedResult(code, stdout, stderr, extraStderr = "") {
 
 function findWranglerCommand() {
   const suffix = process.platform === "win32" ? ".cmd" : "";
-  const local = path.join(packageRoot, "node_modules", ".bin", `wrangler${suffix}`);
-  if (existsSync(local)) return { cmd: local, argsPrefix: [] };
-  throw new Error("Wrangler dependency is not installed. Run `npm install` in the package/source directory and retry.");
+  return { cmd: path.join(packageRoot, "node_modules", ".bin", `wrangler${suffix}`), argsPrefix: [] };
 }
 
 export async function runWrangler(args, options = {}) {
   const wrangler = findWranglerCommand();
   const operation = String(args[0] || "");
   const timeoutMs = options.timeoutMs ?? (operation === "login" || operation === "deploy" ? 10 * 60 * 1000 : 2 * 60 * 1000);
-  return run(wrangler.cmd, [...wrangler.argsPrefix, ...args], { cwd: packageRoot, timeoutMs, ...options });
+  return runExecutable(wrangler.cmd, [...wrangler.argsPrefix, ...args], { cwd: packageRoot, timeoutMs, ...options });
 }
 
 export function workspaceShellCommand(command) {

package/src/local/ssh-key.mjs

@@ -1,8 +1,10 @@
 import { constants as fsConstants } from "node:fs";
-import { chmod, copyFile, link, lstat, mkdir, readFile, rm, stat, unlink } from "node:fs/promises";
-import { basename, dirname, resolve } from "node:path";
-import { randomBytes } from "node:crypto";
-import { run } from "./shell.mjs";
+import { chmod, copyFile, link, mkdir, mkdtemp, rm, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { tmpdir } from "node:os";
+import { runExecutable } from "./shell.mjs";
+import { chmodRegularFileSync, readBoundedRegularFileWithInfoSync } from "./secure-file.mjs";
 
 const KEY_TYPES = new Set(["ed25519", "rsa"]);
 
@@ -35,11 +37,10 @@ function normalizeKeyRequest(options) {
 }
 
 async function inspectExistingKeyFiles(privateKeyPath, publicKeyPath) {
-  const privateInfo = await safeLstat(privateKeyPath);
-  const publicInfo = await safeLstat(publicKeyPath);
-  if (privateInfo?.isSymbolicLink() || publicInfo?.isSymbolicLink()) throw new Error("SSH key path must not be a symbolic link");
-  if (!privateInfo && !publicInfo) return false;
-  if (!privateInfo?.isFile() || !publicInfo?.isFile()) throw new Error("SSH key pair is incomplete or not a pair of regular files");
+  const privateSnapshot = tryReadKeySnapshot(privateKeyPath, 1024 * 1024, "SSH private key");
+  const publicSnapshot = tryReadKeySnapshot(publicKeyPath, 64 * 1024, "SSH public key");
+  if (!privateSnapshot && !publicSnapshot) return false;
+  if (!privateSnapshot || !publicSnapshot) throw new Error("SSH key pair is incomplete or not a pair of regular files");
   return true;
 }
 
@@ -51,7 +52,7 @@ async function createSshKeyPair(request) {
     const args = ["-q", "-t", request.type];
     if (request.type === "rsa") args.push("-b", String(normalizeRsaBits(request.bits)));
     args.push("-N", "", "-f", tempPrivate, "-C", request.comment);
-    const generated = await run("ssh-keygen", args, { capture: true, timeoutMs: 30_000, maxOutputBytes: 64 * 1024 });
+    const generated = await runExecutable("ssh-keygen", args, { capture: true, timeoutMs: 30_000, maxOutputBytes: 64 * 1024 });
     if (generated.code !== 0) throw new Error("ssh-keygen failed");
     await secureKeyModes(tempPrivate, tempPublic);
     await installNoReplace(tempPrivate, request.privateKeyPath);
@@ -70,37 +71,47 @@ async function createSshKeyPair(request) {
 }
 
 export async function inspectSshKeyPair(privateKeyPath, publicKeyPath = `${privateKeyPath}.pub`, created = false) {
-  const privateInfo = await stat(privateKeyPath);
-  const publicInfo = await stat(publicKeyPath);
-  if (!privateInfo.isFile() || !publicInfo.isFile()) throw new Error("SSH key pair is not composed of regular files");
-  const derived = await run("ssh-keygen", ["-y", "-P", "", "-f", privateKeyPath], {
-    capture: true,
-    allowFailure: true,
-    timeoutMs: 15_000,
-    maxOutputBytes: 64 * 1024,
-  });
-  if (derived.code !== 0) throw new Error("SSH private key cannot be used non-interactively or is invalid");
-  const publicLine = (await readFile(publicKeyPath, "utf8")).trim();
-  if (!/^(ssh-ed25519|ssh-rsa)\s+[A-Za-z0-9+/=]+(?:\s+.*)?$/.test(publicLine)) throw new Error("generated SSH public key is invalid");
-  const expectedFields = publicLine.split(/\s+/).slice(0, 2).join(" ");
-  const derivedFields = derived.stdout.trim().split(/\s+/).slice(0, 2).join(" ");
-  if (expectedFields !== derivedFields) throw new Error("SSH public key does not match the private key");
-  const fingerprint = await run("ssh-keygen", ["-lf", publicKeyPath, "-E", "sha256"], {
-    capture: true,
-    timeoutMs: 15_000,
-    maxOutputBytes: 64 * 1024,
-  });
-  const fingerprintValue = fingerprint.stdout.trim().split(/\s+/)[1] || "";
-  if (!/^SHA256:[A-Za-z0-9+/=]+$/.test(fingerprintValue)) throw new Error("SSH key fingerprint output is invalid");
-  return {
-    created,
-    privateKeyPath: resolve(privateKeyPath),
-    publicKeyPath: resolve(publicKeyPath),
-    privateMode: process.platform === "win32" ? null : `0${(privateInfo.mode & 0o777).toString(8)}`,
-    publicMode: process.platform === "win32" ? null : `0${(publicInfo.mode & 0o777).toString(8)}`,
-    fingerprint: fingerprintValue,
-    publicKeyType: publicLine.split(/\s+/, 1)[0],
-  };
+  const privateSnapshot = readKeySnapshot(privateKeyPath, 1024 * 1024, "SSH private key");
+  const publicSnapshot = readKeySnapshot(publicKeyPath, 64 * 1024, "SSH public key");
+  const inspectionRoot = await mkdtemp(join(tmpdir(), "machine-mcp-key-inspection-"));
+  const inspectionPrivate = join(inspectionRoot, "key");
+  const inspectionPublic = `${inspectionPrivate}.pub`;
+  try {
+    await writeFile(inspectionPrivate, privateSnapshot.buffer, { mode: 0o600, flag: "wx" });
+    await writeFile(inspectionPublic, publicSnapshot.buffer, { mode: 0o600, flag: "wx" });
+    const derived = await runExecutable("ssh-keygen", ["-y", "-P", "", "-f", inspectionPrivate], {
+      capture: true,
+      allowFailure: true,
+      timeoutMs: 15_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    if (derived.code !== 0) throw new Error("SSH private key cannot be used non-interactively or is invalid");
+    const publicLine = new TextDecoder("utf-8", { fatal: true }).decode(publicSnapshot.buffer).trim();
+    if (!/^(ssh-ed25519|ssh-rsa)\s+[A-Za-z0-9+/=]+(?:\s+.*)?$/.test(publicLine)) throw new Error("generated SSH public key is invalid");
+    const expectedFields = publicLine.split(/\s+/).slice(0, 2).join(" ");
+    const derivedFields = derived.stdout.trim().split(/\s+/).slice(0, 2).join(" ");
+    if (expectedFields !== derivedFields) throw new Error("SSH public key does not match the private key");
+    const fingerprint = await runExecutable("ssh-keygen", ["-lf", inspectionPublic, "-E", "sha256"], {
+      capture: true,
+      timeoutMs: 15_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    const fingerprintValue = fingerprint.stdout.trim().split(/\s+/)[1] || "";
+    if (!/^SHA256:[A-Za-z0-9+/=]+$/.test(fingerprintValue)) throw new Error("SSH key fingerprint output is invalid");
+    assertKeySnapshotCurrent(privateKeyPath, privateSnapshot, 1024 * 1024, "SSH private key");
+    assertKeySnapshotCurrent(publicKeyPath, publicSnapshot, 64 * 1024, "SSH public key");
+    return {
+      created,
+      privateKeyPath: resolve(privateKeyPath),
+      publicKeyPath: resolve(publicKeyPath),
+      privateMode: process.platform === "win32" ? null : `0${(privateSnapshot.info.mode & 0o777).toString(8)}`,
+      publicMode: process.platform === "win32" ? null : `0${(publicSnapshot.info.mode & 0o777).toString(8)}`,
+      fingerprint: fingerprintValue,
+      publicKeyType: publicLine.split(/\s+/, 1)[0],
+    };
+  } finally {
+    await rm(inspectionRoot, { recursive: true, force: true });
+  }
 }
 
 async function installNoReplace(source, target) {
@@ -120,17 +131,32 @@ async function installNoReplace(source, target) {
 
 async function secureKeyModes(privateKeyPath, publicKeyPath) {
   if (process.platform === "win32") return;
-  await chmod(privateKeyPath, 0o600);
-  await chmod(publicKeyPath, 0o644);
+  chmodRegularFileSync(privateKeyPath, 0o600, "SSH private key");
+  chmodRegularFileSync(publicKeyPath, 0o644, "SSH public key");
 }
 
-async function safeLstat(path) {
-  try { return await lstat(path); } catch (error) {
+function tryReadKeySnapshot(path, maxBytes, label) {
+  try { return readKeySnapshot(path, maxBytes, label); } catch (error) {
     if (error?.code === "ENOENT") return null;
     throw error;
   }
 }
 
+function readKeySnapshot(path, maxBytes, label) {
+  return readBoundedRegularFileWithInfoSync(path, maxBytes, label);
+}
+
+function assertKeySnapshotCurrent(path, expected, maxBytes, label) {
+  const current = readKeySnapshot(path, maxBytes, label);
+  const sameIdentity = Number(current.info.dev) === Number(expected.info.dev)
+    && Number(current.info.ino) === Number(expected.info.ino)
+    && Number(current.info.size) === Number(expected.info.size)
+    && Number(current.info.mtimeMs) === Number(expected.info.mtimeMs);
+  const sameBytes = current.buffer.length === expected.buffer.length
+    && timingSafeEqual(current.buffer, expected.buffer);
+  if (!sameIdentity || !sameBytes) throw new Error(`${label} changed during inspection; retry`);
+}
+
 function boundedComment(value) {
   const comment = String(value || "").replace(/[\r\n\0\u200B-\u200F\u202A-\u202E\u2066-\u2069\uFEFF]/g, " ").replace(/\s+/g, " ").trim();
   if (!comment) return "machine-mcp";