refactor(ssh): split docker module into layered directory

ssh/docker/{index,routes,session-manager,container-routes,console}.ts:
server boot and wiring in index, HTTP handlers in routes, SSH session
registry and command execution in session-manager. Code motion only;
port 30007/30009 and endpoints unchanged. Swagger now scans ssh
subdirectories.

src/backend/ssh/docker/console.ts

@@ -0,0 +1,787 @@
+import { Client as SSHClient } from "ssh2";
+import { SSH_ALGORITHMS } from "../../utils/ssh-algorithms.js";
+import { WebSocketServer, WebSocket } from "ws";
+import { AuthManager } from "../../utils/auth-manager.js";
+import { createCurrentHostResolutionRepository } from "../../database/repositories/factory.js";
+import { systemLogger } from "../../utils/logger.js";
+import type { SSHHost } from "../../../types/index.js";
+import { applyAgentAuth } from "../terminal-auth-helpers.js";
+import {
+  containerCommand,
+  getContainerRuntimeConfig,
+  type ContainerRuntime,
+} from "../container-runtime.js";
+import { resolveSshConnectConfigHost } from "../ssh-dns.js";
+
+const sshLogger = systemLogger;
+
+interface SSHSession {
+  client: SSHClient;
+  stream: import("ssh2").ClientChannel | null;
+  isConnected: boolean;
+  containerId?: string;
+  shell?: string;
+  hostId?: number;
+  containerRuntime?: ContainerRuntime;
+}
+
+const activeSessions = new Map<string, SSHSession>();
+
+const wss = new WebSocketServer({
+  host: "0.0.0.0",
+  port: 30009,
+});
+
+async function detectShell(
+  session: SSHSession,
+  containerId: string,
+): Promise<string> {
+  const shells = ["bash", "sh", "ash"];
+
+  for (const shell of shells) {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        session.client.exec(
+          containerCommand(
+            session.containerRuntime,
+            `exec ${containerId} which ${shell}`,
+          ),
+          (err, stream) => {
+            if (err) return reject(err);
+
+            let output = "";
+            stream.on("data", (data: Buffer) => {
+              output += data.toString();
+            });
+
+            stream.on("close", (code: number) => {
+              if (code === 0 && output.trim()) {
+                resolve();
+              } else {
+                reject(new Error(`Shell ${shell} not found`));
+              }
+            });
+
+            stream.stderr.on("data", () => {});
+            stream.stderr.on("error", () => {});
+            stream.on("error", (streamErr) => {
+              reject(streamErr);
+            });
+          },
+        );
+      });
+
+      return shell;
+    } catch {
+      continue;
+    }
+  }
+
+  return "sh";
+}
+
+async function createJumpHostChain(
+  jumpHosts: Array<{ hostId: number }>,
+  userId: string,
+): Promise<SSHClient | null> {
+  if (!jumpHosts || jumpHosts.length === 0) {
+    return null;
+  }
+
+  let currentClient: SSHClient | null = null;
+  const repository = createCurrentHostResolutionRepository();
+
+  for (let i = 0; i < jumpHosts.length; i++) {
+    const jumpHostId = jumpHosts[i].hostId;
+
+    const resolvedJumpHost = await repository.findHostById(jumpHostId, userId);
+    if (!resolvedJumpHost || resolvedJumpHost.userId !== userId) {
+      throw new Error(`Jump host ${jumpHostId} not found`);
+    }
+
+    const jumpHost = resolvedJumpHost as unknown as SSHHost;
+    if (typeof jumpHost.jumpHosts === "string" && jumpHost.jumpHosts) {
+      try {
+        jumpHost.jumpHosts = JSON.parse(jumpHost.jumpHosts);
+      } catch (e) {
+        sshLogger.error("Failed to parse jump hosts", e, {
+          hostId: jumpHost.id,
+        });
+        jumpHost.jumpHosts = [];
+      }
+    }
+
+    let resolvedCredentials: {
+      password?: string;
+      sshKey?: string;
+      keyPassword?: string;
+      authType?: string;
+    } = {
+      password: jumpHost.password,
+      sshKey: jumpHost.key,
+      keyPassword: jumpHost.keyPassword,
+      authType: jumpHost.authType,
+    };
+
+    if (jumpHost.credentialId) {
+      const credential = await repository.findCredentialByIdForUser(
+        jumpHost.credentialId as number,
+        userId,
+      );
+
+      if (credential) {
+        resolvedCredentials = {
+          password: credential.password as string | undefined,
+          sshKey: (credential.key || credential.privateKey) as
+            | string
+            | undefined,
+          keyPassword: credential.keyPassword as string | undefined,
+          authType: credential.authType as string | undefined,
+        };
+      }
+    }
+
+    const client = new SSHClient();
+
+    const config: Record<string, unknown> = {
+      host: jumpHost.ip?.replace(/^\[|\]$/g, "") || jumpHost.ip,
+      port: jumpHost.port || 22,
+      username: jumpHost.username,
+      tryKeyboard: resolvedCredentials.authType !== "none",
+      readyTimeout: 60000,
+      keepaliveInterval: 30000,
+      keepaliveCountMax: 120,
+      tcpKeepAlive: true,
+      tcpKeepAliveInitialDelay: 30000,
+      algorithms: {
+        kex: [
+          "curve25519-sha256",
+          "curve25519-sha256@libssh.org",
+          "ecdh-sha2-nistp521",
+          "ecdh-sha2-nistp384",
+          "ecdh-sha2-nistp256",
+          "diffie-hellman-group-exchange-sha256",
+          "diffie-hellman-group18-sha512",
+          "diffie-hellman-group17-sha512",
+          "diffie-hellman-group16-sha512",
+          "diffie-hellman-group15-sha512",
+          "diffie-hellman-group14-sha256",
+          "diffie-hellman-group14-sha1",
+          "diffie-hellman-group-exchange-sha1",
+          "diffie-hellman-group1-sha1",
+        ],
+        serverHostKey: [
+          "ssh-ed25519",
+          "ecdsa-sha2-nistp521",
+          "ecdsa-sha2-nistp384",
+          "ecdsa-sha2-nistp256",
+          "rsa-sha2-512",
+          "rsa-sha2-256",
+          "ssh-rsa",
+          "ssh-dss",
+        ],
+        cipher: SSH_ALGORITHMS.cipher,
+        hmac: [
+          "hmac-sha2-512-etm@openssh.com",
+          "hmac-sha2-256-etm@openssh.com",
+          "hmac-sha2-512",
+          "hmac-sha2-256",
+          "hmac-sha1",
+          "hmac-md5",
+        ],
+        compress: ["none", "zlib@openssh.com", "zlib"],
+      },
+    };
+
+    if (
+      resolvedCredentials.authType === "password" &&
+      resolvedCredentials.password
+    ) {
+      config.password = resolvedCredentials.password;
+    } else if (
+      resolvedCredentials.authType === "key" &&
+      resolvedCredentials.sshKey
+    ) {
+      const cleanKey = resolvedCredentials.sshKey
+        .trim()
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n");
+      config.privateKey = Buffer.from(cleanKey, "utf8");
+      if (resolvedCredentials.keyPassword) {
+        config.passphrase = resolvedCredentials.keyPassword;
+      }
+    } else if (resolvedCredentials.authType === "agent") {
+      const result = await applyAgentAuth(
+        config,
+        jumpHost.terminalConfig as unknown as
+          | Record<string, unknown>
+          | undefined,
+      );
+      if ("error" in result) {
+        throw new Error(result.error);
+      }
+    }
+
+    client.on(
+      "keyboard-interactive",
+      (
+        _name: string,
+        _instructions: string,
+        _lang: string,
+        prompts: Array<{ prompt: string; echo: boolean }>,
+        finish: (responses: string[]) => void,
+      ) => {
+        const responses = prompts.map((p) => {
+          if (/password/i.test(p.prompt) && resolvedCredentials.password) {
+            return resolvedCredentials.password as string;
+          }
+          return "";
+        });
+        finish(responses);
+      },
+    );
+
+    if (currentClient) {
+      await new Promise<void>((resolve, reject) => {
+        currentClient!.forwardOut(
+          "127.0.0.1",
+          0,
+          jumpHost.ip,
+          jumpHost.port || 22,
+          (err, stream) => {
+            if (err) return reject(err);
+            config.sock = stream;
+            resolve();
+          },
+        );
+      });
+    }
+
+    if (!config.sock) {
+      await resolveSshConnectConfigHost(config);
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      client.on("ready", () => resolve());
+      client.on("error", reject);
+      client.connect(config);
+    });
+
+    currentClient = client;
+  }
+
+  return currentClient;
+}
+
+wss.on("connection", async (ws: WebSocket, req) => {
+  let token: string | undefined;
+
+  const cookieHeader = req.headers.cookie;
+  if (cookieHeader) {
+    const match = cookieHeader.match(/(?:^|;\s*)jwt=([^;]+)/);
+    if (match) token = decodeURIComponent(match[1]);
+  }
+
+  if (!token) {
+    const authHeader = req.headers.authorization;
+    if (authHeader?.startsWith("Bearer ")) {
+      token = authHeader.slice("Bearer ".length);
+    }
+  }
+
+  if (!token) {
+    const urlObj = new URL(req.url || "", "http://localhost");
+    const qp = urlObj.searchParams.get("token");
+    if (qp) token = qp;
+  }
+
+  if (!token) {
+    ws.close(1008, "Authentication required");
+    return;
+  }
+
+  const authManagerInstance = AuthManager.getInstance();
+  const payload = await authManagerInstance.verifyJWTToken(token);
+  if (!payload?.userId || payload.pendingTOTP) {
+    ws.close(1008, "Authentication required");
+    return;
+  }
+
+  const userId = payload.userId;
+  const sessionId = `docker-console-${Date.now()}-${Math.random()}`;
+  sshLogger.info("Docker console WebSocket connected", {
+    operation: "docker_console_connect",
+    sessionId,
+    userId,
+  });
+
+  let sshSession: SSHSession | null = null;
+
+  const wsPingInterval = setInterval(() => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.ping();
+    }
+  }, 30000);
+
+  ws.on("message", async (data) => {
+    try {
+      const message = JSON.parse(data.toString());
+
+      switch (message.type) {
+        case "connect": {
+          const { hostConfig, containerId, shell, cols, rows } =
+            message.data as {
+              hostConfig: SSHHost;
+              containerId: string;
+              shell?: string;
+              cols?: number;
+              rows?: number;
+            };
+
+          const hostId = hostConfig?.id;
+
+          if (!hostId || !containerId) {
+            ws.send(
+              JSON.stringify({
+                type: "error",
+                message: "Host configuration and container ID are required",
+              }),
+            );
+            return;
+          }
+
+          if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(containerId)) {
+            ws.send(
+              JSON.stringify({
+                type: "error",
+                message: "Invalid container ID",
+              }),
+            );
+            return;
+          }
+
+          const allowedShells = ["bash", "sh", "ash", "zsh"];
+          if (shell && !allowedShells.includes(shell)) {
+            ws.send(
+              JSON.stringify({
+                type: "error",
+                message: "Invalid shell",
+              }),
+            );
+            return;
+          }
+
+          if (!hostConfig.enableDocker) {
+            ws.send(
+              JSON.stringify({
+                type: "error",
+                message: "Docker is not enabled on this host",
+              }),
+            );
+            return;
+          }
+
+          try {
+            // Resolve host with credentials server-side
+            const { resolveHostById } = await import("../host-resolver.js");
+            const resolvedHost = await resolveHostById(hostId, userId);
+
+            if (!resolvedHost) {
+              ws.send(
+                JSON.stringify({
+                  type: "error",
+                  message: "Host not found",
+                }),
+              );
+              return;
+            }
+
+            if (!resolvedHost.enableDocker) {
+              ws.send(
+                JSON.stringify({
+                  type: "error",
+                  message:
+                    "Docker is not enabled for this host. Enable it in Host Settings.",
+                }),
+              );
+              return;
+            }
+
+            const client = new SSHClient();
+
+            const config: Record<string, unknown> = {
+              host: resolvedHost.ip?.replace(/^\[|\]$/g, "") || resolvedHost.ip,
+              port: resolvedHost.port || 22,
+              username: resolvedHost.username,
+              tryKeyboard: true,
+              readyTimeout: 60000,
+              keepaliveInterval: 30000,
+              keepaliveCountMax: 120,
+              tcpKeepAlive: true,
+              tcpKeepAliveInitialDelay: 30000,
+            };
+
+            if (resolvedHost.authType === "password" && resolvedHost.password) {
+              config.password = resolvedHost.password;
+            } else if (resolvedHost.authType === "key" && resolvedHost.key) {
+              const cleanKey = resolvedHost.key
+                .trim()
+                .replace(/\r\n/g, "\n")
+                .replace(/\r/g, "\n");
+              config.privateKey = Buffer.from(cleanKey, "utf8");
+              if (resolvedHost.keyPassword) {
+                config.passphrase = resolvedHost.keyPassword;
+              }
+            } else if (resolvedHost.authType === "agent") {
+              const result = await applyAgentAuth(
+                config,
+                resolvedHost.terminalConfig as unknown as
+                  | Record<string, unknown>
+                  | undefined,
+              );
+              if ("error" in result) {
+                ws.send(
+                  JSON.stringify({
+                    type: "error",
+                    message: result.error,
+                  }),
+                );
+                return;
+              }
+            }
+
+            if (resolvedHost.jumpHosts && resolvedHost.jumpHosts.length > 0) {
+              const jumpClient = await createJumpHostChain(
+                resolvedHost.jumpHosts,
+                userId,
+              );
+              if (jumpClient) {
+                const stream = await new Promise<import("ssh2").ClientChannel>(
+                  (resolve, reject) => {
+                    jumpClient.forwardOut(
+                      "127.0.0.1",
+                      0,
+                      resolvedHost.ip,
+                      resolvedHost.port || 22,
+                      (err, stream) => {
+                        if (err) return reject(err);
+                        resolve(stream);
+                      },
+                    );
+                  },
+                );
+                config.sock = stream;
+              }
+            }
+
+            if (!config.sock) {
+              await resolveSshConnectConfigHost(config);
+            }
+
+            await new Promise<void>((resolve, reject) => {
+              client.on("ready", () => resolve());
+              client.on("error", reject);
+              client.connect(config);
+            });
+
+            const { runtime: containerRuntime } = getContainerRuntimeConfig(
+              resolvedHost.dockerConfig,
+            );
+
+            sshSession = {
+              client,
+              stream: null,
+              isConnected: true,
+              containerId,
+              hostId: resolvedHost.id,
+              containerRuntime,
+            };
+
+            activeSessions.set(sessionId, sshSession);
+
+            let shellToUse = shell || "bash";
+
+            if (shell) {
+              try {
+                await new Promise<void>((resolve, reject) => {
+                  client.exec(
+                    containerCommand(
+                      containerRuntime,
+                      `exec ${containerId} which ${shell}`,
+                    ),
+                    (err, stream) => {
+                      if (err) return reject(err);
+
+                      let output = "";
+                      stream.on("data", (data: Buffer) => {
+                        output += data.toString();
+                      });
+
+                      stream.on("close", (code: number) => {
+                        if (code === 0 && output.trim()) {
+                          resolve();
+                        } else {
+                          reject(new Error(`Shell ${shell} not available`));
+                        }
+                      });
+
+                      stream.stderr.on("data", () => {});
+                      stream.stderr.on("error", () => {});
+                      stream.on("error", (streamErr) => {
+                        reject(streamErr);
+                      });
+                    },
+                  );
+                });
+              } catch {
+                sshLogger.warn(
+                  `Requested shell ${shell} not found, detecting available shell`,
+                  {
+                    operation: "shell_validation",
+                    sessionId,
+                    containerId,
+                    requestedShell: shell,
+                  },
+                );
+                shellToUse = await detectShell(sshSession, containerId);
+              }
+            } else {
+              shellToUse = await detectShell(sshSession, containerId);
+            }
+
+            sshSession.shell = shellToUse;
+
+            const execCommand = containerCommand(
+              containerRuntime,
+              `exec -it ${containerId} /bin/${shellToUse}`,
+            );
+            sshLogger.info("Attaching to Docker container", {
+              operation: "docker_attach",
+              sessionId,
+              userId,
+              hostId: resolvedHost.id,
+              containerId,
+            });
+
+            client.exec(
+              execCommand,
+              {
+                pty: {
+                  term: "xterm-256color",
+                  cols: cols || 80,
+                  rows: rows || 24,
+                },
+              },
+              (err, stream) => {
+                if (err) {
+                  sshLogger.error("Failed to create docker exec", err, {
+                    operation: "docker_exec",
+                    sessionId,
+                    containerId,
+                  });
+
+                  ws.send(
+                    JSON.stringify({
+                      type: "error",
+                      message: `Failed to start console: ${err.message}`,
+                    }),
+                  );
+                  return;
+                }
+
+                sshSession!.stream = stream;
+                sshLogger.success("Docker container attached", {
+                  operation: "docker_attach_success",
+                  sessionId,
+                  userId,
+                  hostId: resolvedHost.id,
+                  containerId,
+                });
+
+                stream.on("data", (data: Buffer) => {
+                  if (ws.readyState === WebSocket.OPEN) {
+                    ws.send(
+                      JSON.stringify({
+                        type: "output",
+                        data: data.toString("utf8"),
+                      }),
+                    );
+                  }
+                });
+
+                stream.stderr.on("data", () => {});
+                stream.stderr.on("error", () => {});
+
+                stream.on("error", (streamErr) => {
+                  sshLogger.error("Docker console stream error", streamErr, {
+                    operation: "docker_console_stream_error",
+                    sessionId,
+                    containerId,
+                  });
+                  if (ws.readyState === WebSocket.OPEN) {
+                    ws.send(
+                      JSON.stringify({
+                        type: "error",
+                        message: `Console error: ${streamErr.message}`,
+                      }),
+                    );
+                  }
+                });
+
+                stream.on("close", () => {
+                  if (ws.readyState === WebSocket.OPEN) {
+                    ws.send(
+                      JSON.stringify({
+                        type: "disconnected",
+                        message: "Console session ended",
+                      }),
+                    );
+                  }
+
+                  if (sshSession) {
+                    sshSession.client.end();
+                    activeSessions.delete(sessionId);
+                  }
+                });
+
+                ws.send(
+                  JSON.stringify({
+                    type: "connected",
+                    data: {
+                      shell: shellToUse,
+                      requestedShell: shell,
+                      shellChanged: shell && shell !== shellToUse,
+                    },
+                  }),
+                );
+              },
+            );
+          } catch (error) {
+            sshLogger.error("Failed to connect to container", error, {
+              operation: "console_connect",
+              sessionId,
+              containerId: message.data.containerId,
+            });
+
+            ws.send(
+              JSON.stringify({
+                type: "error",
+                message:
+                  error instanceof Error
+                    ? error.message
+                    : "Failed to connect to container",
+              }),
+            );
+          }
+          break;
+        }
+
+        case "input": {
+          if (sshSession && sshSession.stream) {
+            sshSession.stream.write(message.data);
+          }
+          break;
+        }
+
+        case "resize": {
+          if (sshSession && sshSession.stream) {
+            const { cols, rows } = message.data;
+            sshSession.stream.setWindow(rows, cols, rows, cols);
+          }
+          break;
+        }
+
+        case "disconnect": {
+          if (sshSession) {
+            if (sshSession.stream) {
+              sshSession.stream.end();
+            }
+            sshSession.client.end();
+            activeSessions.delete(sessionId);
+
+            ws.send(
+              JSON.stringify({
+                type: "disconnected",
+                message: "Disconnected from container",
+              }),
+            );
+          }
+          break;
+        }
+
+        case "ping": {
+          if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ type: "pong" }));
+          }
+          break;
+        }
+
+        default:
+          sshLogger.warn("Unknown message type", {
+            operation: "ws_message",
+            type: message.type,
+          });
+      }
+    } catch (error) {
+      sshLogger.error("WebSocket message error", error, {
+        operation: "ws_message",
+        sessionId,
+      });
+
+      ws.send(
+        JSON.stringify({
+          type: "error",
+          message: error instanceof Error ? error.message : "An error occurred",
+        }),
+      );
+    }
+  });
+
+  ws.on("close", () => {
+    clearInterval(wsPingInterval);
+    sshLogger.info("Docker console disconnected", {
+      operation: "docker_console_disconnect",
+      sessionId,
+      userId,
+      hostId: sshSession?.hostId,
+      containerId: sshSession?.containerId,
+    });
+    if (sshSession) {
+      if (sshSession.stream) {
+        sshSession.stream.end();
+      }
+      sshSession.client.end();
+      activeSessions.delete(sessionId);
+    }
+  });
+
+  ws.on("error", (error) => {
+    sshLogger.error("WebSocket error", error, {
+      operation: "ws_error",
+      sessionId,
+    });
+
+    if (sshSession) {
+      if (sshSession.stream) {
+        sshSession.stream.end();
+      }
+      sshSession.client.end();
+      activeSessions.delete(sessionId);
+    }
+  });
+});
+
+process.on("SIGTERM", () => {
+  activeSessions.forEach((session) => {
+    if (session.stream) {
+      session.stream.end();
+    }
+    session.client.end();
+  });
+
+  activeSessions.clear();
+
+  wss.close(() => {
+    process.exit(0);
+  });
+});

src/backend/ssh/docker/index.ts

@@ -0,0 +1,70 @@
+import express from "express";
+import cookieParser from "cookie-parser";
+import { createCorsMiddleware } from "../../utils/cors-config.js";
+import { logger } from "../../utils/logger.js";
+import { AuthManager } from "../../utils/auth-manager.js";
+import { registerDockerContainerRoutes } from "./container-routes.js";
+import {
+  sshSessions,
+  pendingTOTPSessions,
+  cleanupSession,
+  executeDockerCommand,
+} from "./session-manager.js";
+import {
+  DOCKER_TIMESTAMP_RE,
+  getRequestUserId,
+  registerDockerSshRoutes,
+} from "./routes.js";
+
+const sshLogger = logger;
+
+const app = express();
+
+app.use(createCorsMiddleware(["GET", "POST", "PUT", "DELETE", "OPTIONS"]));
+
+app.use(cookieParser());
+app.use(express.json({ limit: "100mb" }));
+app.use(express.urlencoded({ limit: "100mb", extended: true }));
+app.use((_req, res, next) => {
+  res.setHeader("Cache-Control", "no-store");
+  next();
+});
+
+const authManager = AuthManager.getInstance();
+app.use(authManager.createAuthMiddleware());
+
+registerDockerSshRoutes(app);
+
+registerDockerContainerRoutes(app, {
+  sshSessions,
+  pendingTOTPSessions,
+  getRequestUserId,
+  executeDockerCommand,
+  dockerTimestampPattern: DOCKER_TIMESTAMP_RE,
+});
+
+const PORT = 30007;
+
+app.listen(PORT, async () => {
+  try {
+    await authManager.initialize();
+  } catch (err) {
+    sshLogger.error("Failed to initialize Docker backend", err, {
+      operation: "startup",
+    });
+  }
+});
+
+process.on("SIGINT", () => {
+  Object.keys(sshSessions).forEach((sessionId) => {
+    cleanupSession(sessionId);
+  });
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  Object.keys(sshSessions).forEach((sessionId) => {
+    cleanupSession(sessionId);
+  });
+  process.exit(0);
+});

src/backend/ssh/docker/session-manager.ts

@@ -0,0 +1,171 @@
+import { Client as SSHClient } from "ssh2";
+import { logger } from "../../utils/logger.js";
+import type { ContainerRuntime } from "../container-runtime.js";
+
+const sshLogger = logger;
+
+export interface SSHSession {
+  client: SSHClient;
+  isConnected: boolean;
+  lastActive: number;
+  timeout?: NodeJS.Timeout;
+  activeOperations: number;
+  hostId?: number;
+  userId?: string;
+  isWindows?: boolean;
+  containerRuntime?: ContainerRuntime;
+}
+
+export interface PendingTOTPSession {
+  client: SSHClient;
+  finish: (responses: string[]) => void;
+  config: Record<string, unknown>;
+  createdAt: number;
+  sessionId: string;
+  hostId?: number;
+  ip?: string;
+  port?: number;
+  username?: string;
+  userId?: string;
+  prompts?: Array<{ prompt: string; echo: boolean }>;
+  totpPromptIndex?: number;
+  resolvedPassword?: string;
+  totpAttempts: number;
+  isWarpgate?: boolean;
+  containerRuntime?: ContainerRuntime;
+}
+
+export const sshSessions: Record<string, SSHSession> = {};
+export const pendingTOTPSessions: Record<string, PendingTOTPSession> = {};
+
+const SESSION_IDLE_TIMEOUT = 60 * 60 * 1000;
+
+setInterval(() => {
+  const now = Date.now();
+  Object.keys(pendingTOTPSessions).forEach((sessionId) => {
+    const session = pendingTOTPSessions[sessionId];
+    if (now - session.createdAt > 180000) {
+      try {
+        session.client.end();
+      } catch {
+        // expected
+      }
+      delete pendingTOTPSessions[sessionId];
+    }
+  });
+}, 60000);
+
+export function cleanupSession(sessionId: string) {
+  const session = sshSessions[sessionId];
+  if (session) {
+    if (session.activeOperations > 0) {
+      sshLogger.warn(
+        `Deferring session cleanup for ${sessionId} - ${session.activeOperations} active operations`,
+        {
+          operation: "cleanup_deferred",
+          sessionId,
+          activeOperations: session.activeOperations,
+        },
+      );
+      scheduleSessionCleanup(sessionId);
+      return;
+    }
+
+    try {
+      session.client.end();
+    } catch {
+      // expected
+    }
+    clearTimeout(session.timeout);
+    delete sshSessions[sessionId];
+  }
+}
+
+export function scheduleSessionCleanup(sessionId: string) {
+  const session = sshSessions[sessionId];
+  if (session) {
+    if (session.timeout) clearTimeout(session.timeout);
+
+    session.timeout = setTimeout(() => {
+      cleanupSession(sessionId);
+    }, SESSION_IDLE_TIMEOUT);
+  }
+}
+
+export async function executeDockerCommand(
+  session: SSHSession,
+  command: string,
+  sessionId?: string,
+  userId?: string,
+  hostId?: number,
+): Promise<string> {
+  const startTime = Date.now();
+  sshLogger.info("Executing Docker command", {
+    operation: "docker_command_exec",
+    sessionId,
+    userId,
+    hostId,
+    command: command.split(" ")[1],
+  });
+  return new Promise((resolve, reject) => {
+    session.client.exec(command, (err, stream) => {
+      if (err) {
+        sshLogger.error("Docker command execution error", err, {
+          operation: "execute_docker_command",
+          sessionId,
+          userId,
+          hostId,
+          command: command.split(" ")[1],
+        });
+        return reject(err);
+      }
+
+      let stdout = "";
+      let stderr = "";
+
+      stream.on("close", (code: number) => {
+        if (code !== 0) {
+          sshLogger.error("Docker command failed", undefined, {
+            operation: "execute_docker_command",
+            sessionId,
+            userId,
+            hostId,
+            command: command.split(" ")[1],
+            exitCode: code,
+            stderr,
+          });
+          reject(new Error(stderr || `Command exited with code ${code}`));
+        } else {
+          sshLogger.success("Docker command completed", {
+            operation: "docker_command_success",
+            sessionId,
+            userId,
+            hostId,
+            command: command.split(" ")[1],
+            duration: Date.now() - startTime,
+          });
+          resolve(stdout);
+        }
+      });
+
+      stream.on("data", (data: Buffer) => {
+        stdout += data.toString();
+      });
+
+      stream.stderr.on("data", (data: Buffer) => {
+        stderr += data.toString();
+      });
+
+      stream.on("error", (streamErr: Error) => {
+        sshLogger.error("Docker command stream error", streamErr, {
+          operation: "execute_docker_command",
+          sessionId,
+          userId,
+          hostId,
+          command: command.split(" ")[1],
+        });
+        reject(streamErr);
+      });
+    });
+  });
+}