novac 2.1.1 → 2.2.0

package/kits/kitSSH/kitdef.js

@@ -0,0 +1,1272 @@
+// kitdef.js — kitSSH
+// A complete OpenSSH-equivalent kit for the standard library.
+// Covers: connections, sessions, command execution, key management,
+// tunneling, port forwarding, SCP/SFTP, agent forwarding,
+// multiplexing, jump hosts, known_hosts, authorized_keys, and more.
+//
+// Backed by the `ssh2` npm package for real execution.
+// Every method returns a structured result object.
+//
+// const { kitSSH } = require('./kitdef').kitdef;
+
+// ── Dependencies (real execution layer) ─────────────────────────────────────
+// npm install ssh2
+
+let _ssh2;
+try { _ssh2 = require("ssh2"); } catch { _ssh2 = null; }
+
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+const { execSync, spawn } = require("child_process");
+const crypto = require("crypto");
+const net  = require("net");
+
+// ── Internal state ───────────────────────────────────────────────────────────
+
+const _connections   = new Map(); // id → { client, config, tunnels, sftp }
+const _knownHosts    = new Map(); // "host:port" → { fingerprint, addedAt }
+const _agentSockets  = new Map(); // id → socketPath
+const _pool          = new Map(); // poolKey → Connection[]
+let _connectionCounter = 1;
+
+function _connId() { return `ssh-conn-${_connectionCounter++}`; }
+function _poolKey(config) { return `${config.username}@${config.host}:${config.port || 22}`; }
+
+function _requireSsh2() {
+  if (!_ssh2) throw new Error("ssh2 package not installed. Run: npm install ssh2");
+}
+
+function _getConn(id) {
+  const c = _connections.get(id);
+  if (!c) throw new Error(`No active connection "${id}". Call connect() first.`);
+  return c;
+}
+
+function _fingerprint(key) {
+  return crypto.createHash("sha256").update(key).digest("base64");
+}
+
+function _sshDir() {
+  return path.join(os.homedir(), ".ssh");
+}
+
+// ── Export ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+
+    name: "kitSSH",
+    version: "1.0.0",
+    description: "Complete OpenSSH kit: connections, sessions, exec, keys, tunnels, SFTP, SCP, agent, multiplexing, jump hosts, and more.",
+
+    // ──────────────────────────────────────────────────────────────────────
+    // CONNECTION MANAGEMENT
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Open an SSH connection to a remote host.
+     * Returns a connection ID used by all subsequent operations.
+     *
+     * @param {object} config
+     * @param {string}  config.host
+     * @param {number}  [config.port=22]
+     * @param {string}  config.username
+     * @param {string}  [config.password]
+     * @param {string}  [config.privateKey]    - Path to private key file, or raw key string.
+     * @param {string}  [config.passphrase]    - Passphrase for encrypted private key.
+     * @param {number}  [config.timeout=10000] - Connection timeout ms.
+     * @param {boolean} [config.agentForward=false]
+     * @param {string}  [config.jumpHost]      - ProxyJump host connection ID.
+     * @returns {Promise<{ id: string, host: string, port: number, username: string, status: string }>}
+     *
+     * @example
+     *   const { id } = await kitSSH.connect({
+     *     host: "192.168.1.10",
+     *     username: "admin",
+     *     privateKey: "~/.ssh/id_ed25519",
+     *   });
+     */
+    connect(config) {
+      _requireSsh2();
+      return new Promise((resolve, reject) => {
+        const id = _connId();
+        const client = new _ssh2.Client();
+        const port = config.port || 22;
+        const timeout = config.timeout || 10000;
+
+        let privateKey = config.privateKey;
+        if (privateKey && !privateKey.includes("-----")) {
+          const expanded = privateKey.replace(/^~/, os.homedir());
+          privateKey = fs.readFileSync(expanded, "utf8");
+        }
+
+        const sshConfig = {
+          host: config.host,
+          port,
+          username: config.username,
+          password: config.password,
+          privateKey: privateKey || undefined,
+          passphrase: config.passphrase,
+          readyTimeout: timeout,
+          agentForward: config.agentForward || false,
+          agent: config.agentForward ? (process.env.SSH_AUTH_SOCK || undefined) : undefined,
+        };
+
+        // ProxyJump / jump host
+        if (config.jumpHost) {
+          const jump = _getConn(config.jumpHost);
+          jump.client.forwardOut("127.0.0.1", 0, config.host, port, (err, stream) => {
+            if (err) return reject(err);
+            sshConfig.sock = stream;
+            _finishConnect(client, sshConfig, id, config, resolve, reject);
+          });
+        } else {
+          _finishConnect(client, sshConfig, id, config, resolve, reject);
+        }
+      });
+    },
+
+    /**
+     * Disconnect a session by connection ID.
+     * @param {string} id
+     * @returns {{ id, status }}
+     */
+    disconnect(id) {
+      const c = _connections.get(id);
+      if (c) {
+        c.client.end();
+        _connections.delete(id);
+      }
+      return { id, status: "DISCONNECTED" };
+    },
+
+    /**
+     * Disconnect all open connections.
+     * @returns {{ disconnected: number }}
+     */
+    disconnectAll() {
+      let count = 0;
+      for (const [id, c] of _connections) {
+        c.client.end();
+        _connections.delete(id);
+        count++;
+      }
+      return { disconnected: count };
+    },
+
+    /**
+     * Check whether a connection is still alive.
+     * @param {string} id
+     * @returns {{ id, alive: boolean }}
+     */
+    isAlive(id) {
+      const c = _connections.get(id);
+      return { id, alive: !!c };
+    },
+
+    /**
+     * List all currently open connections.
+     * @returns {object[]}
+     */
+    listConnections() {
+      return Array.from(_connections.entries()).map(([id, c]) => ({
+        id,
+        host: c.config.host,
+        port: c.config.port || 22,
+        username: c.config.username,
+        tunnelCount: c.tunnels ? c.tunnels.length : 0,
+        openedAt: c.openedAt,
+      }));
+    },
+
+    /**
+     * Get detailed info about a specific connection.
+     * @param {string} id
+     * @returns {object}
+     */
+    connectionInfo(id) {
+      const c = _getConn(id);
+      return {
+        id,
+        host: c.config.host,
+        port: c.config.port || 22,
+        username: c.config.username,
+        agentForward: c.config.agentForward || false,
+        tunnels: c.tunnels || [],
+        openedAt: c.openedAt,
+      };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // COMMAND EXECUTION
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Execute a command on a remote host and return stdout/stderr.
+     * @param {string} id - Connection ID.
+     * @param {string} command
+     * @param {object} [options]
+     * @param {object} [options.env]       - Environment variables.
+     * @param {boolean}[options.pty=false] - Request a pseudo-TTY.
+     * @returns {Promise<{ stdout: string, stderr: string, code: number, signal?: string }>}
+     *
+     * @example
+     *   const { stdout } = await kitSSH.exec(id, "uname -a");
+     */
+    exec(id, command, options = {}) {
+      const c = _getConn(id);
+      return new Promise((resolve, reject) => {
+        const execOptions = { env: options.env };
+        if (options.pty) execOptions.pty = true;
+
+        c.client.exec(command, execOptions, (err, stream) => {
+          if (err) return reject(err);
+          let stdout = "", stderr = "";
+          stream.on("data", d => { stdout += d; });
+          stream.stderr.on("data", d => { stderr += d; });
+          stream.on("close", (code, signal) => resolve({ stdout, stderr, code, signal }));
+        });
+      });
+    },
+
+    /**
+     * Execute multiple commands sequentially on the same connection.
+     * @param {string} id
+     * @param {string[]} commands
+     * @returns {Promise<Array<{ command, stdout, stderr, code }>>}
+     *
+     * @example
+     *   await kitSSH.execMany(id, ["apt update", "apt upgrade -y", "reboot"]);
+     */
+    async execMany(id, commands) {
+      const results = [];
+      for (const command of commands) {
+        const result = await this.exec(id, command);
+        results.push({ command, ...result });
+      }
+      return results;
+    },
+
+    /**
+     * Execute a command and stream output line-by-line via a callback.
+     * @param {string} id
+     * @param {string} command
+     * @param {{ onStdout?: function, onStderr?: function }} callbacks
+     * @returns {Promise<{ code: number }>}
+     */
+    execStream(id, command, { onStdout, onStderr } = {}) {
+      const c = _getConn(id);
+      return new Promise((resolve, reject) => {
+        c.client.exec(command, (err, stream) => {
+          if (err) return reject(err);
+          stream.on("data", chunk => {
+            const lines = chunk.toString().split("\n").filter(Boolean);
+            lines.forEach(line => onStdout && onStdout(line));
+          });
+          stream.stderr.on("data", chunk => {
+            const lines = chunk.toString().split("\n").filter(Boolean);
+            lines.forEach(line => onStderr && onStderr(line));
+          });
+          stream.on("close", code => resolve({ code }));
+        });
+      });
+    },
+
+    /**
+     * Open an interactive shell session.
+     * @param {string} id
+     * @param {object} [options]
+     * @param {object} [options.ptyOptions] - e.g. { term: "xterm-256color", cols: 220, rows: 50 }
+     * @returns {Promise<stream>} - A duplex stream you can pipe to/from.
+     */
+    shell(id, options = {}) {
+      const c = _getConn(id);
+      const ptyOptions = options.ptyOptions || { term: "xterm-256color", cols: 220, rows: 50 };
+      return new Promise((resolve, reject) => {
+        c.client.shell(ptyOptions, (err, stream) => {
+          if (err) return reject(err);
+          resolve(stream);
+        });
+      });
+    },
+
+    /**
+     * Execute a command with a timeout. Kills the remote process if exceeded.
+     * @param {string} id
+     * @param {string} command
+     * @param {number} timeoutMs
+     * @returns {Promise<{ stdout, stderr, code, timedOut }>}
+     */
+    execTimeout(id, command, timeoutMs) {
+      return new Promise((resolve, reject) => {
+        const c = _getConn(id);
+        let timedOut = false;
+        let stdout = "", stderr = "";
+
+        c.client.exec(command, (err, stream) => {
+          if (err) return reject(err);
+
+          const timer = setTimeout(() => {
+            timedOut = true;
+            stream.close();
+          }, timeoutMs);
+
+          stream.on("data", d => { stdout += d; });
+          stream.stderr.on("data", d => { stderr += d; });
+          stream.on("close", code => {
+            clearTimeout(timer);
+            resolve({ stdout, stderr, code, timedOut });
+          });
+        });
+      });
+    },
+
+    /**
+     * Run a local script file on the remote host.
+     * Uploads it, executes it, then removes it.
+     * @param {string} id
+     * @param {string} localScriptPath
+     * @param {string[]} [args]
+     * @returns {Promise<{ stdout, stderr, code }>}
+     */
+    async runScript(id, localScriptPath, args = []) {
+      const remotePath = `/tmp/_kitSSH_script_${Date.now()}.sh`;
+      await this.upload(id, localScriptPath, remotePath);
+      await this.exec(id, `chmod +x ${remotePath}`);
+      const result = await this.exec(id, `${remotePath} ${args.join(" ")}`);
+      await this.exec(id, `rm -f ${remotePath}`);
+      return result;
+    },
+
+    /**
+     * Run a command as a different user via sudo.
+     * @param {string} id
+     * @param {string} command
+     * @param {string} [sudoPassword]
+     * @returns {Promise<{ stdout, stderr, code }>}
+     */
+    sudo(id, command, sudoPassword) {
+      const wrapped = sudoPassword
+        ? `echo '${sudoPassword}' | sudo -S ${command}`
+        : `sudo ${command}`;
+      return this.exec(id, wrapped);
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // SFTP / FILE TRANSFER
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Open an SFTP session on an existing connection.
+     * @param {string} id
+     * @returns {Promise<sftp>}
+     */
+    openSFTP(id) {
+      const c = _getConn(id);
+      return new Promise((resolve, reject) => {
+        c.client.sftp((err, sftp) => {
+          if (err) return reject(err);
+          c.sftp = sftp;
+          resolve(sftp);
+        });
+      });
+    },
+
+    /**
+     * Upload a local file to the remote host.
+     * @param {string} id
+     * @param {string} localPath
+     * @param {string} remotePath
+     * @param {{ onProgress?: function }} [options]
+     * @returns {Promise<{ localPath, remotePath, status }>}
+     *
+     * @example
+     *   await kitSSH.upload(id, "./deploy.sh", "/home/admin/deploy.sh");
+     */
+    async upload(id, localPath, remotePath, options = {}) {
+      const sftp = await this.openSFTP(id);
+      return new Promise((resolve, reject) => {
+        const readStream  = fs.createReadStream(localPath);
+        const writeStream = sftp.createWriteStream(remotePath);
+        if (options.onProgress) {
+          let transferred = 0;
+          const total = fs.statSync(localPath).size;
+          readStream.on("data", chunk => {
+            transferred += chunk.length;
+            options.onProgress({ transferred, total, percent: (transferred / total * 100).toFixed(1) });
+          });
+        }
+        writeStream.on("close", () => resolve({ localPath, remotePath, status: "UPLOADED" }));
+        writeStream.on("error", reject);
+        readStream.pipe(writeStream);
+      });
+    },
+
+    /**
+     * Download a remote file to local disk.
+     * @param {string} id
+     * @param {string} remotePath
+     * @param {string} localPath
+     * @param {{ onProgress?: function }} [options]
+     * @returns {Promise<{ remotePath, localPath, status }>}
+     */
+    async download(id, remotePath, localPath, options = {}) {
+      const sftp = await this.openSFTP(id);
+      return new Promise((resolve, reject) => {
+        const readStream  = sftp.createReadStream(remotePath);
+        const writeStream = fs.createWriteStream(localPath);
+        readStream.on("error", reject);
+        writeStream.on("close", () => resolve({ remotePath, localPath, status: "DOWNLOADED" }));
+        readStream.pipe(writeStream);
+      });
+    },
+
+    /**
+     * Upload an entire directory recursively.
+     * @param {string} id
+     * @param {string} localDir
+     * @param {string} remoteDir
+     * @returns {Promise<{ uploaded: string[] }>}
+     */
+    async uploadDir(id, localDir, remoteDir) {
+      const uploaded = [];
+      const walk = async (local, remote) => {
+        await this.exec(id, `mkdir -p ${remote}`);
+        for (const entry of fs.readdirSync(local, { withFileTypes: true })) {
+          const lp = path.join(local, entry.name);
+          const rp = `${remote}/${entry.name}`;
+          if (entry.isDirectory()) {
+            await walk(lp, rp);
+          } else {
+            await this.upload(id, lp, rp);
+            uploaded.push(rp);
+          }
+        }
+      };
+      await walk(localDir, remoteDir);
+      return { uploaded };
+    },
+
+    /**
+     * List files in a remote directory.
+     * @param {string} id
+     * @param {string} remotePath
+     * @returns {Promise<object[]>}
+     */
+    async listDir(id, remotePath) {
+      const sftp = await this.openSFTP(id);
+      return new Promise((resolve, reject) => {
+        sftp.readdir(remotePath, (err, list) => {
+          if (err) return reject(err);
+          resolve(list.map(f => ({
+            name: f.filename,
+            size: f.attrs.size,
+            mode: f.attrs.mode,
+            modified: new Date(f.attrs.mtime * 1000).toISOString(),
+            isDirectory: (f.attrs.mode & 0o40000) !== 0,
+          })));
+        });
+      });
+    },
+
+    /**
+     * Read a remote file's contents into a string.
+     * @param {string} id
+     * @param {string} remotePath
+     * @returns {Promise<string>}
+     */
+    async readFile(id, remotePath) {
+      const sftp = await this.openSFTP(id);
+      return new Promise((resolve, reject) => {
+        const chunks = [];
+        const stream = sftp.createReadStream(remotePath);
+        stream.on("data", d => chunks.push(d));
+        stream.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        stream.on("error", reject);
+      });
+    },
+
+    /**
+     * Write a string to a remote file.
+     * @param {string} id
+     * @param {string} remotePath
+     * @param {string} content
+     * @returns {Promise<{ remotePath, status }>}
+     */
+    async writeFile(id, remotePath, content) {
+      const sftp = await this.openSFTP(id);
+      return new Promise((resolve, reject) => {
+        const stream = sftp.createWriteStream(remotePath);
+        stream.on("close", () => resolve({ remotePath, status: "WRITTEN" }));
+        stream.on("error", reject);
+        stream.end(content, "utf8");
+      });
+    },
+
+    /**
+     * Delete a file on the remote host.
+     * @param {string} id
+     * @param {string} remotePath
+     * @returns {Promise<{ remotePath, status }>}
+     */
+    async deleteFile(id, remotePath) {
+      const sftp = await this.openSFTP(id);
+      return new Promise((resolve, reject) => {
+        sftp.unlink(remotePath, err => {
+          if (err) return reject(err);
+          resolve({ remotePath, status: "DELETED" });
+        });
+      });
+    },
+
+    /**
+     * Get the stat of a remote path.
+     * @param {string} id
+     * @param {string} remotePath
+     * @returns {Promise<object>}
+     */
+    async stat(id, remotePath) {
+      const sftp = await this.openSFTP(id);
+      return new Promise((resolve, reject) => {
+        sftp.stat(remotePath, (err, stats) => {
+          if (err) return reject(err);
+          resolve({
+            size: stats.size,
+            mode: stats.mode,
+            uid: stats.uid,
+            gid: stats.gid,
+            accessed: new Date(stats.atime * 1000).toISOString(),
+            modified: new Date(stats.mtime * 1000).toISOString(),
+            isDirectory: stats.isDirectory(),
+            isFile: stats.isFile(),
+            isSymlink: stats.isSymbolicLink(),
+          });
+        });
+      });
+    },
+
+    /**
+     * Rename/move a file on the remote host.
+     * @param {string} id
+     * @param {string} remoteSrc
+     * @param {string} remoteDest
+     * @returns {Promise<{ status }>}
+     */
+    async rename(id, remoteSrc, remoteDest) {
+      const sftp = await this.openSFTP(id);
+      return new Promise((resolve, reject) => {
+        sftp.rename(remoteSrc, remoteDest, err => {
+          if (err) return reject(err);
+          resolve({ status: "RENAMED", from: remoteSrc, to: remoteDest });
+        });
+      });
+    },
+
+    /**
+     * Create a directory on the remote host.
+     * @param {string} id
+     * @param {string} remotePath
+     * @param {boolean} [recursive=true]
+     * @returns {Promise<{ remotePath, status }>}
+     */
+    async mkdir(id, remotePath, recursive = true) {
+      if (recursive) {
+        await this.exec(id, `mkdir -p ${remotePath}`);
+        return { remotePath, status: "CREATED" };
+      }
+      const sftp = await this.openSFTP(id);
+      return new Promise((resolve, reject) => {
+        sftp.mkdir(remotePath, err => {
+          if (err) return reject(err);
+          resolve({ remotePath, status: "CREATED" });
+        });
+      });
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // TUNNELING & PORT FORWARDING
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Open a local port forward (ssh -L).
+     * Traffic to localhost:localPort is forwarded to remoteHost:remotePort via the SSH server.
+     *
+     * @param {string} id - Connection ID.
+     * @param {object} options
+     * @param {number} options.localPort
+     * @param {string} options.remoteHost
+     * @param {number} options.remotePort
+     * @param {string} [options.bindAddress="127.0.0.1"]
+     * @returns {Promise<{ tunnelId, localPort, remoteHost, remotePort, server }>}
+     *
+     * @example
+     *   await kitSSH.localForward(id, { localPort: 5432, remoteHost: "db.internal", remotePort: 5432 });
+     */
+    localForward(id, { localPort, remoteHost, remotePort, bindAddress = "127.0.0.1" }) {
+      const c = _getConn(id);
+      const tunnelId = `tunnel-local-${localPort}`;
+
+      return new Promise((resolve, reject) => {
+        const server = net.createServer(sock => {
+          c.client.forwardOut(bindAddress, localPort, remoteHost, remotePort, (err, stream) => {
+            if (err) { sock.destroy(); return; }
+            sock.pipe(stream).pipe(sock);
+          });
+        });
+
+        server.listen(localPort, bindAddress, () => {
+          c.tunnels = c.tunnels || [];
+          c.tunnels.push({ tunnelId, type: "local", localPort, remoteHost, remotePort, server });
+          resolve({ tunnelId, localPort, remoteHost, remotePort, status: "ACTIVE" });
+        });
+
+        server.on("error", reject);
+      });
+    },
+
+    /**
+     * Open a remote port forward (ssh -R).
+     * Traffic to remotePort on the SSH server is forwarded to localHost:localPort.
+     *
+     * @param {string} id
+     * @param {object} options
+     * @param {number} options.remotePort
+     * @param {string} options.localHost
+     * @param {number} options.localPort
+     * @returns {Promise<{ tunnelId, remotePort, localHost, localPort }>}
+     */
+    remoteForward(id, { remotePort, localHost, localPort }) {
+      const c = _getConn(id);
+      const tunnelId = `tunnel-remote-${remotePort}`;
+
+      return new Promise((resolve, reject) => {
+        c.client.forwardIn("0.0.0.0", remotePort, (err) => {
+          if (err) return reject(err);
+
+          c.client.on("tcp connection", (info, accept) => {
+            if (info.destPort !== remotePort) return;
+            const stream = accept();
+            const sock = net.connect(localPort, localHost);
+            stream.pipe(sock).pipe(stream);
+          });
+
+          c.tunnels = c.tunnels || [];
+          c.tunnels.push({ tunnelId, type: "remote", remotePort, localHost, localPort });
+          resolve({ tunnelId, remotePort, localHost, localPort, status: "ACTIVE" });
+        });
+      });
+    },
+
+    /**
+     * Open a dynamic SOCKS5 proxy tunnel (ssh -D).
+     * @param {string} id
+     * @param {number} localPort - Local SOCKS5 proxy port.
+     * @returns {Promise<{ tunnelId, localPort, type }>}
+     */
+    dynamicForward(id, localPort) {
+      const c = _getConn(id);
+      const tunnelId = `tunnel-dynamic-${localPort}`;
+
+      return new Promise((resolve, reject) => {
+        const server = net.createServer(sock => {
+          // Minimal SOCKS5 handshake
+          sock.once("data", data => {
+            if (data[0] !== 0x05) { sock.destroy(); return; }
+            sock.write(Buffer.from([0x05, 0x00])); // no auth
+
+            sock.once("data", req => {
+              if (req[1] !== 0x01) { sock.destroy(); return; } // CONNECT only
+              const hostLen = req[4];
+              const host = req.slice(5, 5 + hostLen).toString();
+              const port = req.readUInt16BE(5 + hostLen);
+
+              c.client.forwardOut("127.0.0.1", localPort, host, port, (err, stream) => {
+                if (err) { sock.destroy(); return; }
+                const resp = Buffer.alloc(10);
+                resp[0] = 0x05; resp[1] = 0x00; resp[3] = 0x01;
+                sock.write(resp);
+                sock.pipe(stream).pipe(sock);
+              });
+            });
+          });
+        });
+
+        server.listen(localPort, "127.0.0.1", () => {
+          c.tunnels = c.tunnels || [];
+          c.tunnels.push({ tunnelId, type: "dynamic-socks5", localPort, server });
+          resolve({ tunnelId, localPort, type: "SOCKS5", status: "ACTIVE" });
+        });
+
+        server.on("error", reject);
+      });
+    },
+
+    /**
+     * Close a specific tunnel by its tunnel ID.
+     * @param {string} id - Connection ID.
+     * @param {string} tunnelId
+     * @returns {{ tunnelId, status }}
+     */
+    closeTunnel(id, tunnelId) {
+      const c = _getConn(id);
+      const idx = (c.tunnels || []).findIndex(t => t.tunnelId === tunnelId);
+      if (idx === -1) throw new Error(`Tunnel "${tunnelId}" not found.`);
+      const tunnel = c.tunnels[idx];
+      if (tunnel.server) tunnel.server.close();
+      c.tunnels.splice(idx, 1);
+      return { tunnelId, status: "CLOSED" };
+    },
+
+    /**
+     * List all active tunnels on a connection.
+     * @param {string} id
+     * @returns {object[]}
+     */
+    listTunnels(id) {
+      const c = _getConn(id);
+      return (c.tunnels || []).map(({ server, ...rest }) => rest);
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // KEY MANAGEMENT
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Generate a new SSH key pair.
+     * @param {object} [options]
+     * @param {'ed25519'|'rsa'|'ecdsa'} [options.type='ed25519']
+     * @param {number}  [options.bits=4096]         - RSA bits.
+     * @param {string}  [options.comment='']
+     * @param {string}  [options.passphrase='']
+     * @param {string}  [options.outputPath]        - Base path (no extension). Defaults to ~/.ssh/id_<type>.
+     * @returns {{ privateKeyPath, publicKeyPath, fingerprint, type }}
+     *
+     * @example
+     *   kitSSH.generateKey({ type: "ed25519", comment: "deploy@prod" });
+     */
+    generateKey(options = {}) {
+      const type       = options.type || "ed25519";
+      const bits       = options.bits || 4096;
+      const comment    = options.comment || "";
+      const passphrase = options.passphrase || "";
+      const basePath   = options.outputPath || path.join(_sshDir(), `id_${type}_${Date.now()}`);
+      const privPath   = basePath;
+      const pubPath    = `${basePath}.pub`;
+
+      let cmd = `ssh-keygen -t ${type} -C "${comment}" -f "${privPath}" -N "${passphrase}"`;
+      if (type === "rsa") cmd += ` -b ${bits}`;
+
+      execSync(cmd, { stdio: "pipe" });
+
+      const pub = fs.readFileSync(pubPath, "utf8").trim();
+      const fingerprint = execSync(`ssh-keygen -lf "${pubPath}"`, { encoding: "utf8" }).trim();
+
+      return { privateKeyPath: privPath, publicKeyPath: pubPath, fingerprint, type, comment };
+    },
+
+    /**
+     * Add a public key to the remote host's authorized_keys for a user.
+     * @param {string} id - Connection ID.
+     * @param {string} publicKey - Path to .pub file or raw public key string.
+     * @param {string} [remoteUser] - Defaults to the connected user.
+     * @returns {Promise<{ status }>}
+     */
+    async authorizeKey(id, publicKey, remoteUser) {
+      let key = publicKey;
+      if (!key.startsWith("ssh-") && !key.startsWith("ecdsa-")) {
+        key = fs.readFileSync(publicKey.replace(/^~/, os.homedir()), "utf8").trim();
+      }
+      const user = remoteUser || _getConn(id).config.username;
+      const cmd = `mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo '${key}' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys`;
+      await this.exec(id, cmd);
+      return { status: "KEY AUTHORIZED", user, fingerprint: _fingerprint(key) };
+    },
+
+    /**
+     * Remove a public key from the remote host's authorized_keys.
+     * @param {string} id
+     * @param {string} publicKey - Path to .pub file or raw public key string.
+     * @returns {Promise<{ status }>}
+     */
+    async revokeKey(id, publicKey) {
+      let key = publicKey;
+      if (!key.startsWith("ssh-") && !key.startsWith("ecdsa-")) {
+        key = fs.readFileSync(publicKey.replace(/^~/, os.homedir()), "utf8").trim();
+      }
+      const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      await this.exec(id, `sed -i '/${escaped}/d' ~/.ssh/authorized_keys`);
+      return { status: "KEY REVOKED" };
+    },
+
+    /**
+     * List all public keys in the remote host's authorized_keys.
+     * @param {string} id
+     * @returns {Promise<string[]>}
+     */
+    async listAuthorizedKeys(id) {
+      const { stdout } = await this.exec(id, "cat ~/.ssh/authorized_keys 2>/dev/null || echo ''");
+      return stdout.trim().split("\n").filter(Boolean);
+    },
+
+    /**
+     * Add a remote host's fingerprint to the local known_hosts file.
+     * @param {string} host
+     * @param {number} [port=22]
+     * @returns {{ host, fingerprint, status }}
+     */
+    addKnownHost(host, port = 22) {
+      const result = execSync(`ssh-keyscan -p ${port} ${host} 2>/dev/null`, { encoding: "utf8" }).trim();
+      const knownHostsPath = path.join(_sshDir(), "known_hosts");
+      fs.mkdirSync(_sshDir(), { recursive: true });
+      fs.appendFileSync(knownHostsPath, `\n${result}\n`);
+      const fingerprint = _fingerprint(result);
+      _knownHosts.set(`${host}:${port}`, { fingerprint, addedAt: new Date().toISOString() });
+      return { host, port, fingerprint, status: "ADDED TO KNOWN_HOSTS" };
+    },
+
+    /**
+     * Remove a host from the local known_hosts file.
+     * @param {string} host
+     * @param {number} [port=22]
+     * @returns {{ status }}
+     */
+    removeKnownHost(host, port = 22) {
+      execSync(`ssh-keygen -R "[${host}]:${port}" 2>/dev/null || ssh-keygen -R "${host}" 2>/dev/null`, { stdio: "pipe" });
+      _knownHosts.delete(`${host}:${port}`);
+      return { host, port, status: "REMOVED FROM KNOWN_HOSTS" };
+    },
+
+    /**
+     * Check if a host's fingerprint is already trusted in known_hosts.
+     * @param {string} host
+     * @param {number} [port=22]
+     * @returns {{ trusted: boolean, fingerprint?: string }}
+     */
+    checkKnownHost(host, port = 22) {
+      try {
+        const result = execSync(`ssh-keygen -F "[${host}]:${port}" 2>/dev/null`, { encoding: "utf8" });
+        return { trusted: result.trim().length > 0, fingerprint: _fingerprint(result) };
+      } catch {
+        return { trusted: false };
+      }
+    },
+
+    /**
+     * Get the fingerprint of a remote host without connecting.
+     * @param {string} host
+     * @param {number} [port=22]
+     * @returns {{ host, port, fingerprint }}
+     */
+    getHostFingerprint(host, port = 22) {
+      const raw = execSync(`ssh-keyscan -p ${port} ${host} 2>/dev/null`, { encoding: "utf8" }).trim();
+      return { host, port, fingerprint: _fingerprint(raw), raw };
+    },
+
+    /**
+     * Change the passphrase on an existing private key.
+     * @param {string} privateKeyPath
+     * @param {string} oldPassphrase
+     * @param {string} newPassphrase
+     * @returns {{ status }}
+     */
+    changePassphrase(privateKeyPath, oldPassphrase, newPassphrase) {
+      const expanded = privateKeyPath.replace(/^~/, os.homedir());
+      execSync(`ssh-keygen -p -P "${oldPassphrase}" -N "${newPassphrase}" -f "${expanded}"`, { stdio: "pipe" });
+      return { status: "PASSPHRASE CHANGED", path: expanded };
+    },
+
+    /**
+     * Get the fingerprint of a local key file.
+     * @param {string} keyPath - Path to public or private key.
+     * @returns {{ fingerprint, type }}
+     */
+    getKeyFingerprint(keyPath) {
+      const expanded = keyPath.replace(/^~/, os.homedir());
+      const result = execSync(`ssh-keygen -lf "${expanded}"`, { encoding: "utf8" }).trim();
+      const [bits, fingerprint, ...rest] = result.split(" ");
+      return { bits: parseInt(bits), fingerprint, comment: rest.slice(0, -1).join(" "), type: rest[rest.length - 1] };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // SSH AGENT
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Add a key to the local SSH agent.
+     * @param {string} keyPath
+     * @param {string} [passphrase]
+     * @returns {{ status }}
+     */
+    agentAddKey(keyPath, passphrase) {
+      const expanded = keyPath.replace(/^~/, os.homedir());
+      if (passphrase) {
+        execSync(`ssh-add "${expanded}"`, {
+          env: { ...process.env, SSH_ASKPASS_REQUIRE: "never" },
+          input: passphrase,
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+      } else {
+        execSync(`ssh-add "${expanded}"`, { stdio: "pipe" });
+      }
+      return { status: "KEY ADDED TO AGENT", path: expanded };
+    },
+
+    /**
+     * List all keys currently loaded in the SSH agent.
+     * @returns {string[]}
+     */
+    agentListKeys() {
+      try {
+        const result = execSync("ssh-add -l", { encoding: "utf8" }).trim();
+        return result.split("\n").filter(Boolean);
+      } catch {
+        return [];
+      }
+    },
+
+    /**
+     * Remove a key from the SSH agent.
+     * @param {string} keyPath
+     * @returns {{ status }}
+     */
+    agentRemoveKey(keyPath) {
+      const expanded = keyPath.replace(/^~/, os.homedir());
+      execSync(`ssh-add -d "${expanded}"`, { stdio: "pipe" });
+      return { status: "KEY REMOVED FROM AGENT", path: expanded };
+    },
+
+    /**
+     * Remove all keys from the SSH agent.
+     * @returns {{ status }}
+     */
+    agentClearKeys() {
+      execSync("ssh-add -D", { stdio: "pipe" });
+      return { status: "ALL KEYS REMOVED FROM AGENT" };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // CONNECTION POOLING / MULTIPLEXING
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Get or create a pooled connection.
+     * Reuses an existing alive connection to the same host/user/port.
+     * @param {object} config - Same as connect().
+     * @returns {Promise<{ id, reused: boolean }>}
+     */
+    async pooledConnect(config) {
+      const key = _poolKey(config);
+      const existing = (_pool.get(key) || []).find(id => _connections.has(id));
+      if (existing) return { id: existing, reused: true };
+
+      const { id } = await this.connect(config);
+      const poolList = _pool.get(key) || [];
+      poolList.push(id);
+      _pool.set(key, poolList);
+      return { id, reused: false };
+    },
+
+    /**
+     * Release a pooled connection (but keep it open for reuse).
+     * @param {string} id
+     * @returns {{ id, status }}
+     */
+    poolRelease(id) {
+      return { id, status: "RETURNED TO POOL" };
+    },
+
+    /**
+     * Drain the pool — close all pooled connections for a host.
+     * @param {string} host
+     * @param {string} username
+     * @param {number} [port=22]
+     * @returns {{ drained: number }}
+     */
+    poolDrain(host, username, port = 22) {
+      const key = `${username}@${host}:${port}`;
+      const ids = _pool.get(key) || [];
+      ids.forEach(id => this.disconnect(id));
+      _pool.delete(key);
+      return { drained: ids.length };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // JUMP HOSTS / PROXY
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Connect to a target host via one or more jump hosts (ProxyJump chain).
+     * @param {object[]} hops - Array of connection configs, last entry is the target.
+     * @returns {Promise<{ id: string, hops: number }>}
+     *
+     * @example
+     *   const { id } = await kitSSH.jumpConnect([
+     *     { host: "bastion.example.com", username: "admin", privateKey: "~/.ssh/id_ed25519" },
+     *     { host: "internal.db.local",   username: "postgres", privateKey: "~/.ssh/id_ed25519" },
+     *   ]);
+     */
+    async jumpConnect(hops) {
+      if (hops.length === 0) throw new Error("At least one hop required.");
+      let prevId = null;
+      for (let i = 0; i < hops.length; i++) {
+        const config = { ...hops[i] };
+        if (prevId) config.jumpHost = prevId;
+        const { id } = await this.connect(config);
+        prevId = id;
+      }
+      return { id: prevId, hops: hops.length };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // CONFIG FILE
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Parse the local ~/.ssh/config file and return entries as objects.
+     * @returns {object[]}
+     */
+    parseConfig() {
+      const configPath = path.join(_sshDir(), "config");
+      if (!fs.existsSync(configPath)) return [];
+      const text = fs.readFileSync(configPath, "utf8");
+      const entries = [];
+      let current = null;
+      for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const [key, ...rest] = trimmed.split(/\s+/);
+        const value = rest.join(" ");
+        if (key.toLowerCase() === "host") {
+          if (current) entries.push(current);
+          current = { Host: value };
+        } else if (current) {
+          current[key] = value;
+        }
+      }
+      if (current) entries.push(current);
+      return entries;
+    },
+
+    /**
+     * Add a host entry to ~/.ssh/config.
+     * @param {object} entry - e.g. { Host: "myserver", HostName: "1.2.3.4", User: "admin", IdentityFile: "~/.ssh/id_ed25519" }
+     * @returns {{ status, configPath }}
+     */
+    addConfigEntry(entry) {
+      const configPath = path.join(_sshDir(), "config");
+      fs.mkdirSync(_sshDir(), { recursive: true });
+      const lines = ["", `Host ${entry.Host}`];
+      for (const [k, v] of Object.entries(entry)) {
+        if (k !== "Host") lines.push(`  ${k} ${v}`);
+      }
+      fs.appendFileSync(configPath, lines.join("\n") + "\n");
+      return { status: "ENTRY ADDED", configPath };
+    },
+
+    /**
+     * Remove a host entry from ~/.ssh/config by Host pattern.
+     * @param {string} hostPattern
+     * @returns {{ status }}
+     */
+    removeConfigEntry(hostPattern) {
+      const configPath = path.join(_sshDir(), "config");
+      if (!fs.existsSync(configPath)) return { status: "CONFIG NOT FOUND" };
+      const text = fs.readFileSync(configPath, "utf8");
+      const blocks = text.split(/(?=^Host )/m);
+      const filtered = blocks.filter(b => !b.startsWith(`Host ${hostPattern}`));
+      fs.writeFileSync(configPath, filtered.join(""));
+      return { status: "ENTRY REMOVED", hostPattern };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // DIAGNOSTICS & UTILITIES
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Check if a remote port is reachable from the SSH server.
+     * @param {string} id
+     * @param {string} host
+     * @param {number} port
+     * @param {number} [timeoutSeconds=5]
+     * @returns {Promise<{ reachable: boolean, host, port }>}
+     */
+    async checkPort(id, host, port, timeoutSeconds = 5) {
+      const { stdout } = await this.exec(
+        id,
+        `(echo >/dev/tcp/${host}/${port}) &>/dev/null && echo "open" || echo "closed"`,
+      );
+      return { reachable: stdout.trim() === "open", host, port };
+    },
+
+    /**
+     * Get system information from the remote host.
+     * @param {string} id
+     * @returns {Promise<object>}
+     */
+    async systemInfo(id) {
+      const [os_, hostname, uptime, mem, disk, cpu] = await Promise.all([
+        this.exec(id, "uname -a"),
+        this.exec(id, "hostname"),
+        this.exec(id, "uptime -p 2>/dev/null || uptime"),
+        this.exec(id, "free -h 2>/dev/null || vm_stat"),
+        this.exec(id, "df -h /"),
+        this.exec(id, "nproc 2>/dev/null || sysctl -n hw.ncpu"),
+      ]);
+      return {
+        os: os_.stdout.trim(),
+        hostname: hostname.stdout.trim(),
+        uptime: uptime.stdout.trim(),
+        memory: mem.stdout.trim(),
+        disk: disk.stdout.trim(),
+        cpuCores: cpu.stdout.trim(),
+      };
+    },
+
+    /**
+     * Measure round-trip latency to the SSH server.
+     * @param {string} id
+     * @param {number} [samples=5]
+     * @returns {Promise<{ avgMs: number, minMs: number, maxMs: number, samples: number[] }>}
+     */
+    async ping(id, samples = 5) {
+      const times = [];
+      for (let i = 0; i < samples; i++) {
+        const start = Date.now();
+        await this.exec(id, "echo 1");
+        times.push(Date.now() - start);
+      }
+      return {
+        avgMs: Math.round(times.reduce((a, b) => a + b, 0) / times.length),
+        minMs: Math.min(...times),
+        maxMs: Math.max(...times),
+        samples: times,
+      };
+    },
+
+    /**
+     * Test connectivity to a host without establishing a full session.
+     * @param {string} host
+     * @param {number} [port=22]
+     * @param {number} [timeoutMs=5000]
+     * @returns {Promise<{ reachable: boolean, latencyMs?: number }>}
+     */
+    testConnectivity(host, port = 22, timeoutMs = 5000) {
+      return new Promise(resolve => {
+        const start = Date.now();
+        const sock = net.connect(port, host);
+        sock.setTimeout(timeoutMs);
+        sock.on("connect", () => {
+          const latencyMs = Date.now() - start;
+          sock.destroy();
+          resolve({ reachable: true, latencyMs });
+        });
+        sock.on("error", () => resolve({ reachable: false }));
+        sock.on("timeout", () => { sock.destroy(); resolve({ reachable: false }); });
+      });
+    },
+
+    /**
+     * Get the remote host's SSH server version banner.
+     * @param {string} host
+     * @param {number} [port=22]
+     * @returns {Promise<{ banner: string }>}
+     */
+    getServerBanner(host, port = 22) {
+      return new Promise((resolve, reject) => {
+        const sock = net.connect(port, host);
+        let banner = "";
+        sock.on("data", data => {
+          banner += data.toString();
+          if (banner.includes("\n")) {
+            sock.destroy();
+            resolve({ host, port, banner: banner.split("\n")[0].trim() });
+          }
+        });
+        sock.on("error", reject);
+        setTimeout(() => { sock.destroy(); reject(new Error("Banner timeout")); }, 5000);
+      });
+    },
+
+    /**
+     * Copy a file between two remote hosts (remote-to-remote via local bounce).
+     * @param {string} srcId  - Source connection ID.
+     * @param {string} srcPath
+     * @param {string} dstId  - Destination connection ID.
+     * @param {string} dstPath
+     * @returns {Promise<{ status }>}
+     */
+    async remoteCopy(srcId, srcPath, dstId, dstPath) {
+      const tmpPath = path.join(os.tmpdir(), `kitSSH_bounce_${Date.now()}`);
+      await this.download(srcId, srcPath, tmpPath);
+      await this.upload(dstId, tmpPath, dstPath);
+      fs.unlinkSync(tmpPath);
+      return { status: "COPIED", from: `${srcId}:${srcPath}`, to: `${dstId}:${dstPath}` };
+    },
+
+    /**
+     * Watch a remote file for changes and call a callback when it changes.
+     * Uses polling.
+     * @param {string} id
+     * @param {string} remotePath
+     * @param {function} onChange - Called with new content string.
+     * @param {number} [intervalMs=2000]
+     * @returns {{ stop: function }} - Call stop() to end watching.
+     */
+    watchFile(id, remotePath, onChange, intervalMs = 2000) {
+      let last = null;
+      const timer = setInterval(async () => {
+        try {
+          const content = await this.readFile(id, remotePath);
+          if (content !== last) { last = content; onChange(content); }
+        } catch { /* file may not exist yet */ }
+      }, intervalMs);
+      return { stop: () => clearInterval(timer) };
+    },
+
+    /**
+     * Tail a remote log file, streaming new lines to a callback.
+     * @param {string} id
+     * @param {string} remotePath
+     * @param {function} onLine
+     * @param {number} [lines=10] - Initial lines to show.
+     * @returns {Promise<{ stop: function }>}
+     */
+    async tailFile(id, remotePath, onLine, lines = 10) {
+      const stream = await this.shell(id);
+      stream.write(`tail -n ${lines} -f ${remotePath}\n`);
+      let buf = "";
+      stream.on("data", data => {
+        buf += data.toString();
+        const parts = buf.split("\n");
+        buf = parts.pop();
+        parts.forEach(line => onLine(line));
+      });
+      return { stop: () => stream.end("exit\n") };
+    },
+
+  }
+};
+
+// ── Internal helpers (outside kitdef for cleanliness) ────────────────────────
+
+function _finishConnect(client, sshConfig, id, originalConfig, resolve, reject) {
+  client.on("ready", () => {
+    _connections.set(id, {
+      client,
+      config: originalConfig,
+      tunnels: [],
+      sftp: null,
+      openedAt: new Date().toISOString(),
+    });
+    resolve({
+      id,
+      host: originalConfig.host,
+      port: originalConfig.port || 22,
+      username: originalConfig.username,
+      status: "CONNECTED",
+    });
+  });
+  client.on("error", reject);
+  client.connect(sshConfig);
+}