ssh-client-wrapper 2.17.1 → 3.0.0

package/README.md

@@ -1,7 +1,7 @@
 [![npm version](https://badge.fury.io/js/ssh-client-wrapper.svg)](https://badge.fury.io/js/ssh-client-wrapper)
 [![Known Vulnerabilities](https://snyk.io/test/github/so5/ssh-client-wrapper/badge.svg)](https://snyk.io/test/github/so5/ssh-client-wrapper)
 [![Coverage Status](https://coveralls.io/repos/github/so5/ssh-client-wrapper/badge.svg?branch=main)](https://coveralls.io/github/so5/ssh-client-wrapper?branch=main)
-[![Maintainability](https://api.codeclimate.com/v1/badges/8f3c0ea00e755ae31081/maintainability)](https://codeclimate.com/github/so5/ssh-client-wrapper/maintainability)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=so5_ssh-client-wrapper&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=so5_ssh-client-wrapper)
 # ssh-client-wrapper
 open ssh client wrapper library for nodejs
 
@@ -64,6 +64,9 @@ Creates a new SSH client instance.
     *   `retryDuration` (number, optional): Time (msec) to wait between each retry. Defaults to `1000`.
     *   `retryableExitCodes` (number[], optional): Additional rsync exit codes to treat as retryable for `.send()`/`.recv()`. See [Retry behavior for `.send()` / `.recv()`](#retry-behavior-for-send--recv) below.
     *   `replaceRetryableExitCodes` (boolean, optional): If `true`, `retryableExitCodes` replaces the built-in retryable exit code list instead of adding to it.
+    *   `useAgent` (boolean, optional): Authenticate key-based hosts through an ssh-agent instead of replaying the passphrase on every connection. Defaults to `true` when `keyFile` is set. Set `false` to force the legacy behavior. See [SSH agent authentication](#ssh-agent-authentication) below.
+    *   `identityAgent` (string, optional): Path to an existing ssh-agent socket to authenticate through (emitted as `-oIdentityAgent`). When set, the wrapper uses that agent as-is and manages nothing.
+    *   `agentKeyTTL` (number, optional): Lifetime in seconds applied to keys the wrapper adds to an agent (`ssh-add -t`). Defaults to `3600`.
     *   And more... see `lib/index.js` for all available options.
 
 ### `.exec(cmd, [timeout], [outputCallback], [rcfile], [prependCmd])`
@@ -178,3 +181,24 @@ Checks if a connection to the remote host can be established.
 
 ### `.disconnect()`
 Closes the master SSH connection to the remote host.
+
+### `.dispose()`
+Removes this host's key from the wrapper-managed (or caller-supplied) ssh-agent and then closes the master SSH connection. It does **not** kill the shared agent process, since other hosts or processes may still be using it. Safe to call repeatedly.
+
+*   Returns: `Promise<void>`
+
+### SSH agent authentication
+
+When `keyFile` is set, key-based authentication goes through an **ssh-agent** by default (`useAgent: true`). The passphrase (if any) is consumed once to `ssh-add` the key; every subsequent connection and every master-connection rebuild after a `ControlPersist` expiry then authenticates non-interactively, so the wrapper never has to hold a replayable secret.
+
+How the agent is chosen, per host, at connect time:
+
+1.  If `identityAgent` is set, that socket is used as-is.
+2.  Otherwise, if `SSH_AUTH_SOCK` is present in the environment, that agent is used (the key is `ssh-add`ed into it with a `-t` lifetime, so it does not linger there indefinitely).
+3.  Otherwise, on POSIX, the wrapper spawns one shared `ssh-agent` per user, at a fixed socket under `$XDG_RUNTIME_DIR` / `/run/user/<uid>` / `/tmp` (overridable with `SSH_CLIENT_WRAPPER_AGENT_DIR`). It is reused by later runs and is not killed on exit; keys expire from it via `agentKeyTTL` (default 1 h).
+
+If no agent can be used, or `ssh-add` fails, the wrapper silently falls back to the legacy behavior of answering the passphrase prompt on each connection. Set `useAgent: false` to force that path.
+
+**Keyless / browser agents:** with no `keyFile`, set `identityAgent` to the socket of an already-populated agent (for example [`bssh-agent`](https://github.com/so5/browser-ssh-agent), which keeps the private key in a browser tab) and the wrapper will authenticate through it.
+
+**Windows:** an already-running agent (the OpenSSH Authentication Agent service, or a supplied `identityAgent`) is used, but the wrapper never spawns one; without a reachable agent it falls back to the legacy path.

package/lib/agent.js

@@ -0,0 +1,524 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { setTimeout as setTimeoutPromise } from "node:timers/promises";
+import Debug from "debug";
+import { spawn } from "node-pty-prebuilt-multiarch";
+import { rePhPrompt } from "./util.js";
+
+const debug = Debug("sshClientWrapper:debug:agent");
+const debugVerbose = Debug("sshClientWrapper:verbose:agent");
+
+const DEFAULT_TTL = 3600;
+const ADDKEY_TIMEOUT_SEC = 60;
+const CHILD_TIMEOUT_MS = 15000;
+const LOCK_TIMEOUT_MS = 15000;
+const LOCK_STALE_MS = 60000;
+const MAX_BAD_PASSPHRASE = 3;
+const MAX_SOCKET_PATH = 103;
+
+//sentinel candidate meaning "run ssh-add with the inherited environment and let
+//OpenSSH use its default agent (e.g. the Windows OpenSSH Authentication Agent pipe)"
+const AGENT_DEFAULT = "__scw_default_agent__";
+
+//injection seam for tests
+const _internal = {
+  spawn,
+  execFileP: promisify(execFile)
+};
+
+let sharedSock = null;
+let sharedInFlight = null;
+
+/**
+ * promisified sleep
+ * @param {number} ms - milliseconds to wait
+ * @returns {Promise<void>} - resolves after ms
+ */
+function sleep(ms) {
+  return setTimeoutPromise(ms);
+}
+
+/**
+ * check if path points to a regular file
+ * @param {string} p - path to check
+ * @returns {boolean} - true if p is an existing regular file
+ */
+function isFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * check if path points to an existing directory
+ * @param {string} p - path to check
+ * @returns {boolean} - true if p is an existing directory
+ */
+function dirExists(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * build an env object pointing ssh-add/ssh-agent at a specific socket
+ * @param {string} sock - agent socket path, or AGENT_DEFAULT to inherit unchanged
+ * @returns {object} - environment object for the child process
+ */
+function sockEnv(sock) {
+  if (sock === AGENT_DEFAULT) {
+    return { ...process.env };
+  }
+  return { ...process.env, SSH_AUTH_SOCK: sock };
+}
+
+/**
+ * whether this platform can spawn and manage a shared ssh-agent
+ * @returns {boolean} - true on POSIX platforms with a uid
+ */
+function canSpawnSharedAgent() {
+  return process.platform !== "win32" && typeof process.getuid === "function";
+}
+
+/**
+ * decide whether key-based auth for this host should go through an ssh-agent
+ * @param {object} hostInfo - hostinfo object
+ * @returns {boolean} - true to use the agent path, false for the legacy pty path
+ */
+function shouldUseAgent(hostInfo) {
+  if (hostInfo.useAgent === false) {
+    return false;
+  }
+  if (typeof hostInfo.identityAgent === "string" && hostInfo.identityAgent !== "") {
+    return true;
+  }
+  if (hostInfo.useAgent === true) {
+    return true;
+  }
+  return typeof hostInfo.keyFile === "string" && isFile(hostInfo.keyFile);
+}
+
+/**
+ * resolve a mode-0700, uid-owned directory to hold the shared agent socket
+ * @returns {string} - directory path
+ */
+function resolveWellKnownDir() {
+  const uid = process.getuid();
+  const candidates = [];
+
+  if (process.env.SSH_CLIENT_WRAPPER_AGENT_DIR) {
+    candidates.push(process.env.SSH_CLIENT_WRAPPER_AGENT_DIR);
+  }
+  if (process.env.XDG_RUNTIME_DIR) {
+    candidates.push(path.join(process.env.XDG_RUNTIME_DIR, "ssh-client-wrapper"));
+  }
+  if (dirExists(`/run/user/${uid}`)) {
+    candidates.push(`/run/user/${uid}/ssh-client-wrapper`);
+  }
+  candidates.push(path.join(os.tmpdir(), `scw-${uid}`), `/tmp/scw-${uid}`);
+
+  for (const dir of candidates) {
+    try {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      fs.chmodSync(dir, 0o700);
+      const st = fs.statSync(dir);
+      const shortEnough = path.join(dir, "agent.sock").length <= MAX_SOCKET_PATH;
+      if (st.uid === uid && (st.mode & 0o077) === 0 && shortEnough) {
+        return dir;
+      }
+    } catch (e) {
+      debugVerbose(`candidate agent dir ${dir} rejected: ${e.message}`);
+    }
+  }
+  const err = new Error("no usable directory for the shared ssh-agent socket");
+  err.code = "NO_AGENT_DIR";
+  throw err;
+}
+
+/**
+ * check that a pre-existing socket file is owned by us and not group/world accessible
+ * @param {string} sockPath - socket path to check
+ * @returns {boolean} - true if the socket is safe to reuse
+ */
+function socketIsTrusted(sockPath) {
+  try {
+    const st = fs.statSync(sockPath);
+    return st.uid === process.getuid() && (st.mode & 0o077) === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * take a cross-process advisory lock on the agent directory
+ * @param {string} dir - directory to lock
+ * @returns {Promise<void>} - resolves once the lock is held
+ */
+async function acquireLock(dir) {
+  const lock = path.join(dir, "agent.lock");
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+
+  for (;;) {
+    try {
+      fs.mkdirSync(lock);
+      return;
+    } catch (e) {
+      if (e.code !== "EEXIST") {
+        throw e;
+      }
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+          fs.rmdirSync(lock);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() > deadline) {
+        const err = new Error("timeout acquiring ssh-agent lock");
+        err.code = "LOCK_TIMEOUT";
+        throw err;
+      }
+      await sleep(100);
+    }
+  }
+}
+
+/**
+ * release the advisory lock on the agent directory
+ * @param {string} dir - directory to unlock
+ * @returns {void}
+ */
+function releaseLock(dir) {
+  try {
+    fs.rmdirSync(path.join(dir, "agent.lock"));
+  } catch {
+    //nothing to release
+  }
+}
+
+/**
+ * probe an agent socket with `ssh-add -l`
+ * @param {string} sock - agent socket path (or AGENT_DEFAULT)
+ * @returns {Promise<number>} - 0 has identities, 1 reachable but empty, 2 unreachable
+ */
+async function probeAgent(sock) {
+  try {
+    await _internal.execFileP("ssh-add", ["-l"], { env: sockEnv(sock), timeout: CHILD_TIMEOUT_MS });
+    return 0;
+  } catch (e) {
+    return e?.code === 1 ? 1 : 2;
+  }
+}
+
+/**
+ * resolve a passphrase value from a hostInfo passphrase callback/string
+ * @param {string | Function | undefined} ph - passphrase or callback
+ * @returns {Promise<string | null>} - the passphrase, or null when unavailable
+ */
+async function resolvePassphrase(ph) {
+  if (typeof ph === "string") {
+    return ph;
+  }
+  if (typeof ph === "function") {
+    const v = await ph();
+    return typeof v === "string" ? v : null;
+  }
+  return null;
+}
+
+/**
+ * add a key to an agent via `ssh-add`, answering the passphrase prompt from a pty
+ * @param {string} sock - agent socket path (or AGENT_DEFAULT)
+ * @param {string} keyFile - private key path
+ * @param {string | Function | undefined} phCallback - passphrase or callback
+ * @param {number} ttl - ssh-add -t lifetime in seconds
+ * @returns {Promise<void>} - resolves on success, rejects with err.code on failure
+ */
+function addKey(sock, keyFile, phCallback, ttl) {
+  return new Promise((resolve, reject)=>{
+    const pty = _internal.spawn("ssh-add", ["-t", String(ttl), keyFile], {
+      windowsHide: true,
+      env: sockEnv(sock)
+    });
+    let settled = false;
+    let badTries = 0;
+    let timer = null;
+
+    const finish = (fn, arg)=>{
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timer !== null) {
+        clearTimeout(timer);
+      }
+      try {
+        pty.kill();
+      } catch {
+        //already gone
+      }
+      fn(arg);
+    };
+    const fail = (code, message)=>{
+      const err = new Error(message);
+      err.code = code;
+      finish(reject, err);
+    };
+
+    timer = setTimeout(()=>{
+      fail("ADDKEY_TIMEOUT", `ssh-add did not finish within ${ADDKEY_TIMEOUT_SEC} sec`);
+    }, ADDKEY_TIMEOUT_SEC * 1000);
+
+    pty.onData((data)=>{
+      const output = data.toString();
+      debugVerbose(output);
+
+      if (/Could not open a connection to your authentication agent|Error connecting to agent/.test(output)) {
+        fail("NO_AGENT", "no ssh-agent is reachable");
+        return;
+      }
+      if (rePhPrompt.test(output)) {
+        resolvePassphrase(phCallback)
+          .then((v)=>{
+            if (v === null) {
+              fail("NO_PASSPHRASE", "key is encrypted but no passphrase is available");
+              return;
+            }
+            pty.write(`${v}\n`);
+          })
+          .catch((e)=>{
+            finish(reject, e);
+          });
+        return;
+      }
+      if (/Bad passphrase|incorrect passphrase/i.test(output)) {
+        badTries += 1;
+        if (badTries >= MAX_BAD_PASSPHRASE || typeof phCallback !== "function") {
+          fail("BAD_PASSPHRASE", "bad passphrase for private key");
+        }
+        return;
+      }
+      if (/Identity added/.test(output)) {
+        finish(resolve);
+      }
+    });
+
+    pty.onExit(({ exitCode })=>{
+      if (settled) {
+        return;
+      }
+      if (exitCode === 0) {
+        finish(resolve);
+        return;
+      }
+      fail("ADDKEY_FAILED", `ssh-add exited with ${exitCode}`);
+    });
+  });
+}
+
+/**
+ * remove a key from an agent (best effort)
+ * @param {string} sock - agent socket path (or AGENT_DEFAULT)
+ * @param {string} keyFile - private key path
+ * @returns {Promise<void>} - always resolves
+ */
+async function removeKey(sock, keyFile) {
+  try {
+    await _internal.execFileP("ssh-add", ["-d", keyFile], { env: sockEnv(sock), timeout: CHILD_TIMEOUT_MS });
+  } catch {
+    //best effort only
+  }
+}
+
+/**
+ * spawn (or find) the per-user shared ssh-agent and return its socket path
+ * @returns {Promise<string>} - socket path of a live shared agent
+ */
+async function spawnSharedAgent() {
+  const dir = resolveWellKnownDir();
+  const sock = path.join(dir, "agent.sock");
+
+  await acquireLock(dir);
+
+  try {
+    if (fs.existsSync(sock)) {
+      if (!socketIsTrusted(sock)) {
+        const err = new Error(`refusing to use untrusted agent socket ${sock}`);
+        err.code = "UNTRUSTED_SOCKET";
+        throw err;
+      }
+      if (await probeAgent(sock) !== 2) {
+        return sock;
+      }
+      try {
+        fs.unlinkSync(sock);
+      } catch {
+        //someone else may have cleaned it up
+      }
+    }
+    debug(`spawning shared ssh-agent at ${sock}`);
+    await _internal.execFileP("ssh-agent", ["-a", sock], { timeout: CHILD_TIMEOUT_MS });
+    return sock;
+  } finally {
+    releaseLock(dir);
+  }
+}
+
+/**
+ * get the shared agent socket, deduplicating concurrent callers in this process
+ * @returns {Promise<string>} - socket path of a live shared agent
+ */
+async function getSharedAgent() {
+  if (sharedSock && socketIsTrusted(sharedSock) && await probeAgent(sharedSock) !== 2) {
+    return sharedSock;
+  }
+  if (!sharedInFlight) {
+    sharedInFlight = spawnSharedAgent()
+      .then((s)=>{
+        sharedSock = s;
+        return s;
+      })
+      .finally(()=>{
+        sharedInFlight = null;
+      });
+  }
+  return sharedInFlight;
+}
+
+/**
+ * mark hostInfo as agent-ready
+ * @param {object} hostInfo - hostinfo object
+ * @param {string} sock - resolved agent socket (or AGENT_DEFAULT)
+ * @returns {void}
+ */
+function setReady(hostInfo, sock) {
+  hostInfo.managedAgentSock = sock === AGENT_DEFAULT ? undefined : sock;
+  hostInfo._agentEnsuredAt = Date.now();
+}
+
+/**
+ * ensure the private key is loaded into some reachable agent (two-step algorithm)
+ * @param {object} hostInfo - hostinfo object
+ * @param {string | null} candidate - preferred socket, AGENT_DEFAULT, or null
+ * @param {number} ttl - ssh-add -t lifetime in seconds
+ * @returns {Promise<void>} - resolves once loaded (or rejects to trigger legacy fallback)
+ */
+async function ensureKeyLoaded(hostInfo, candidate, ttl) {
+  if (candidate !== null) {
+    try {
+      await addKey(candidate, hostInfo.keyFile, hostInfo.passphrase, ttl);
+      setReady(hostInfo, candidate);
+      return;
+    } catch (e) {
+      if (e.code !== "NO_AGENT") {
+        throw e;
+      }
+      debug("no agent at the candidate socket; will spawn a shared one");
+    }
+  }
+  if (!canSpawnSharedAgent()) {
+    const err = new Error("no reachable ssh-agent and this platform cannot spawn one");
+    err.code = "NO_AGENT";
+    throw err;
+  }
+  const sock = await getSharedAgent();
+  await addKey(sock, hostInfo.keyFile, hostInfo.passphrase, ttl);
+  setReady(hostInfo, sock);
+}
+
+/**
+ * for a keyFile-less host, use an already-populated agent if one is reachable
+ * @param {object} hostInfo - hostinfo object
+ * @param {string | null} candidate - preferred socket, AGENT_DEFAULT, or null
+ * @returns {Promise<void>} - resolves; leaves hostInfo on the legacy path if unusable
+ */
+async function ensurePreloadedAgent(hostInfo, candidate) {
+  if (candidate === null || candidate === AGENT_DEFAULT) {
+    return;
+  }
+  if (await probeAgent(candidate) === 0) {
+    setReady(hostInfo, candidate);
+  }
+}
+
+/**
+ * effective ssh-add -t lifetime for a host
+ * @param {object} hostInfo - hostinfo object
+ * @returns {number} - lifetime in seconds
+ */
+function effectiveTtl(hostInfo) {
+  return Number.isFinite(hostInfo.agentKeyTTL) && hostInfo.agentKeyTTL > 0
+    ? Math.floor(hostInfo.agentKeyTTL)
+    : DEFAULT_TTL;
+}
+
+/**
+ * pick the agent socket to try for a host
+ * @param {object} hostInfo - hostinfo object
+ * @returns {string | null | undefined} - socket path, AGENT_DEFAULT, null to spawn a shared agent, or undefined to give up
+ */
+function resolveAgentCandidate(hostInfo) {
+  if (typeof hostInfo.identityAgent === "string" && hostInfo.identityAgent !== "") {
+    return hostInfo.identityAgent;
+  }
+  if (typeof process.env.SSH_AUTH_SOCK === "string" && process.env.SSH_AUTH_SOCK !== "") {
+    return process.env.SSH_AUTH_SOCK;
+  }
+  if (canSpawnSharedAgent()) {
+    return null;
+  }
+  return process.platform === "win32" ? AGENT_DEFAULT : undefined;
+}
+
+/**
+ * make sure this host can authenticate through an ssh-agent, if it should
+ * @param {object} hostInfo - hostinfo object (mutated: managedAgentSock, _agentEnsuredAt)
+ * @returns {Promise<void>} - resolves; on any recoverable problem hostInfo is left on the legacy path
+ */
+async function ensureAgentForHost(hostInfo) {
+  if (!shouldUseAgent(hostInfo)) {
+    return;
+  }
+  const ttl = effectiveTtl(hostInfo);
+
+  if (typeof hostInfo._agentEnsuredAt === "number" && Date.now() - hostInfo._agentEnsuredAt < ttl * 500) {
+    return;
+  }
+  const candidate = resolveAgentCandidate(hostInfo);
+
+  if (candidate === undefined) {
+    return;
+  }
+  const hasKey = typeof hostInfo.keyFile === "string" && isFile(hostInfo.keyFile);
+
+  try {
+    await (hasKey ? ensureKeyLoaded(hostInfo, candidate, ttl) : ensurePreloadedAgent(hostInfo, candidate));
+  } catch (e) {
+    if (e.code === "BAD_PASSPHRASE") {
+      throw e;
+    }
+    debug(`agent setup did not complete (${e.code || e.message}); using legacy pty auth`);
+    delete hostInfo.managedAgentSock;
+    delete hostInfo._agentEnsuredAt;
+  }
+}
+
+export {
+  shouldUseAgent,
+  canSpawnSharedAgent,
+  ensureAgentForHost,
+  removeKey,
+  probeAgent,
+  addKey,
+  resolveWellKnownDir,
+  socketIsTrusted,
+  _internal
+};

package/lib/index.d.ts

@@ -3,12 +3,13 @@ declare module "ssh-client-wrapper" {
     host: string;
     user: string;
     port?: number;
-    password?: string | (() => string);
-    passphrase?: string | (() => string);
+    password?: string | (() => string | Promise<string>);
+    passphrase?: string | (() => string | Promise<string>);
     keyFile?: string;
     noStrictHostKeyChecking?: boolean;
     ControlPersist?: number;
     ConnectTimeout?: number;
+    ControlPersistDir?: string;
     maxRetry?: number;
     retryDuration?: number;
     retryableExitCodes?: number[];
@@ -16,6 +17,10 @@ declare module "ssh-client-wrapper" {
     rcfile?: string;
     prependCmd?: string;
     sshOpt?: string[];
+    useAgent?: boolean;
+    identityAgent?: string;
+    agentKeyTTL?: number;
+    reauthRequired?: () => void;
   };
 
   class SshClientWrapper {
@@ -60,7 +65,15 @@ declare module "ssh-client-wrapper" {
       replaceRetryableExitCodes?: boolean
     ): Promise<void>;
     canConnect(timeout?: number): Promise<boolean>;
+    remoteToRemoteCopy(
+      src: string[],
+      dstHostInfo: HostInfo,
+      dst: string,
+      opt?: string[],
+      timeout?: number
+    ): Promise<void>;
     disconnect(): Promise<void>;
+    dispose(): Promise<void>;
   }
 
   export default SshClientWrapper;

package/lib/index.js

@@ -3,6 +3,7 @@ import path from "path";
 import Debug from "debug";
 import * as sshExecModule from "./sshExec.js";
 import * as rsyncExecModule from "./rsyncExec.js";
+import * as agentModule from "./agent.js";
 import { isArrayOfString, isArrayOfInteger, sanityCheck } from "./util.js";
 
 const debug = Debug("sshClientWrapper:debug:interface");
@@ -35,6 +36,10 @@ const debugVerbose = Debug("sshClientWrapper:verbose:interface");
  * @param {string} hostInfo.rcfile - rcfile path which will be sourced before executing actual command
  * @param {string} hostInfo.prependCmd - command string which will be executed before executing actual command
  * @param {string[]} hostInfo.sshOpt - additional options for ssh
+ * @param {boolean} hostInfo.useAgent - authenticate key-based hosts through an ssh-agent (default: true when keyFile is set). On win32 an already-running agent is used but none is spawned. Set false to force the legacy pty passphrase-replay path.
+ * @param {string} hostInfo.identityAgent - path to an existing ssh-agent socket to use (emitted as -oIdentityAgent); the wrapper manages nothing when this is set
+ * @param {Integer} hostInfo.agentKeyTTL - lifetime in seconds for keys added to the agent (ssh-add -t); default 3600
+ * @param {Function} hostInfo.reauthRequired - called when a fresh master connection hits an auth prompt despite the agent (unused by current consumers)
  */
 
 const logAndReject = (message)=>{
@@ -42,12 +47,14 @@ const logAndReject = (message)=>{
   return Promise.reject(new Error(message));
 };
 
+const defaultDeps = { ...sshExecModule, ...rsyncExecModule, ...agentModule };
+
 /**
  * Facade class.
  * @class
  */
 class SshClientWrapper {
-  constructor(hostInfo, deps = { ...sshExecModule, ...rsyncExecModule }) {
+  constructor(hostInfo, deps = defaultDeps) {
     debug("constructor called for", hostInfo.host);
     debugVerbose("hostInfo=", hostInfo);
     this.hostInfo = { ...hostInfo };
@@ -281,6 +288,22 @@ class SshClientWrapper {
     debug(`disconnect from ${this.hostInfo.host} called`);
     this.deps.disconnect(this.hostInfo);
   }
+
+  /**
+   * Remove this host's key from the wrapper-managed / external agent and tear down the
+   * master session. Does NOT kill the shared agent process (other hosts or processes may
+   * be using it). Safe to call repeatedly. (Unused by current consumers.)
+   * @returns {Promise<void>} - resolves when teardown is done
+   */
+  async dispose() {
+    debug(`dispose for ${this.hostInfo.host} called`);
+    if (this.hostInfo.managedAgentSock && this.hostInfo.keyFile) {
+      await this.deps.removeKey(this.hostInfo.managedAgentSock, this.hostInfo.keyFile);
+    }
+    delete this.hostInfo.managedAgentSock;
+    delete this.hostInfo._agentEnsuredAt;
+    await this.deps.disconnect(this.hostInfo);
+  }
 }
 
 export default SshClientWrapper;

package/lib/sshExec.js

@@ -1,8 +1,9 @@
 import crypto from "crypto";
 import { setTimeout as setTimeoutPromise } from "timers/promises";
 import Debug from "debug";
-import { sendPty, sshCmd, getSshOption, sanityCheck, watchDogTimer } from "./util.js";
+import { sendPty, sshCmd, getSshOption, sanityCheck, watchDogTimer, rePwPrompt, rePhPrompt } from "./util.js";
 import { fork, createMasterPty, sshLoginCallback } from "./fork.js";
+import { shouldUseAgent, ensureAgentForHost } from "./agent.js";
 
 const debug = Debug("sshClientWrapper:debug:sshExec");
 const debugVerbose = Debug("sshClientWrapper:verbose:sshExec");
@@ -147,6 +148,22 @@ async function existsMaster(hostInfo, argTimeout) {
 export async function connect(hostInfo, timeout = 60) {
   debug("connect called");
 
+  if (shouldUseAgent(hostInfo)) {
+    try {
+      await ensureAgentForHost(hostInfo);
+    } catch (e) {
+      if (e.code === "BAD_PASSPHRASE") {
+        throw e;
+      }
+      debug("agent setup failed; falling back to legacy pty auth", e);
+      delete hostInfo.managedAgentSock;
+      delete hostInfo._agentEnsuredAt;
+    }
+  } else {
+    delete hostInfo.managedAgentSock;
+    delete hostInfo._agentEnsuredAt;
+  }
+
   if (await existsMaster(hostInfo, timeout)) {
     debugVerbose("master connection exists");
     return;
@@ -201,6 +218,22 @@ export async function connect(hostInfo, timeout = 60) {
     });
     hostInfo.masterPty.onData((data)=>{
       const output = data.toString();
+
+      if (shouldUseAgent(hostInfo) && (rePwPrompt.test(output) || rePhPrompt.test(output))) {
+        if (typeof hostInfo.reauthRequired === "function") {
+          try {
+            hostInfo.reauthRequired();
+          } catch {
+            //a consumer hook must never break the connection
+          }
+        }
+        if (hostInfo.password == null && hostInfo.passphrase == null) {
+          const err = new Error("agent authentication failed and no secret is available for fallback");
+          err.code = "REAUTH_REQUIRED";
+          reject(err);
+          return;
+        }
+      }
       sshLoginCallback(output, hostInfo.masterPty, hostInfo.password, hostInfo.passphrase, debugSendMasterPty)
         .catch(reject);
     });

package/lib/util.js

@@ -53,7 +53,10 @@ const hostInfoSchema = {
       type: "array",
       minItems: 1,
       items: { type: "string", pattern: "\\S+", transform: ["trim"] }
-    }
+    },
+    useAgent: { type: "boolean" },
+    identityAgent: { type: "string", pattern: String.raw`\S+`, transform: ["trim"] },
+    agentKeyTTL: { type: "number", minimum: 1 }
   },
   required: ["host"]
 };
@@ -61,13 +64,15 @@ const hostInfoSchema = {
 const stringOptions = [
   "user",
   "keyFile",
-  "ControlPersistDir"
+  "ControlPersistDir",
+  "identityAgent"
 ];
 const numberOptions = [
   "ControlPersist",
   "ConnectTimeout",
   "maxRetry",
-  "retryDuration"
+  "retryDuration",
+  "agentKeyTTL"
 ];
 
 const validate = ajv.compile(hostInfoSchema);
@@ -133,6 +138,11 @@ export const sanityCheck = (hostInfo)=>{
       }
     }
   }
+  if (typeof hostInfo.identityAgent === "string" && /\s/.test(hostInfo.identityAgent)) {
+    const err = new Error(`invalid identityAgent specified ${hostInfo.identityAgent}`);
+    err.hostInfo = hostInfo;
+    throw err;
+  }
   if (["string", "function"].includes(typeof password)) {
     hostInfo.password = password;
   }
@@ -211,7 +221,13 @@ export const getSshOption = (hostInfo, withoutDestination)=>{
   if (hostInfo.keyFile) {
     args.push("-A");
   }
-  
+
+  //route auth through a wrapper-managed or caller-supplied ssh-agent when one is in play
+  const agentSock = hostInfo.managedAgentSock || hostInfo.identityAgent;
+  if (typeof agentSock === "string" && agentSock !== "") {
+    args.push(`-oIdentityAgent=${agentSock}`);
+  }
+
   const controlPersist = Number.isInteger(hostInfo.ControlPersist) && hostInfo.ControlPersist >= 0 ? hostInfo.ControlPersist : "180";
   const controlPersistDir = getControlPersistDir(hostInfo);
   args.push("-oControlMaster=auto");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssh-client-wrapper",
-  "version": "2.17.1",
+  "version": "3.0.0",
   "description": "wrapper library for open ssh client and rsync",
   "keywords": [
     "ssh",