ssh-handler 1.0.0__py3-none-any.whl

ssh_handler/core.py

@@ -0,0 +1,793 @@
+"""
+The main SSH handler: command execution, interactive shells, sudo, full SFTP
+file operations, optional SCP, jump-host chaining, and remote-OS awareness.
+
+Designed for three consumers from one object:
+  * test-automation framework  -> raise-on-error (default)
+  * standalone CLI script       -> see ssh_handler.cli
+  * PyQt5 tool                  -> safe=True + log_callback (see pyqt_worker)
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import stat
+import time
+import logging
+import posixpath
+from typing import Callable, Optional, Sequence, Union
+
+import paramiko
+
+from .config import SSHConfig
+from .credentials import Secret, mask
+from .results import CommandResult, TransferResult, ShellResult, OperationResult
+from .exceptions import (
+    SSHError,
+    SSHConnectionError,
+    SSHAuthenticationError,
+    SSHTimeoutError,
+    SSHCommandError,
+    SSHTransferError,
+    SSHNotConnectedError,
+)
+
+try:  # optional SCP support
+    from scp import SCPClient
+    _HAS_SCP = True
+except Exception:  # pragma: no cover
+    SCPClient = None
+    _HAS_SCP = False
+
+
+# --------------------------------------------------------------------------- #
+# Interactive shell session
+# --------------------------------------------------------------------------- #
+class ShellSession:
+    """
+    A persistent interactive shell (one PTY channel) for devices/flows that
+    need state between commands, prompts, or send/expect interaction.
+    """
+
+    def __init__(self, channel: paramiko.Channel, encoding: str = "utf-8"):
+        self._chan = channel
+        self.encoding = encoding
+
+    def send(self, data: str) -> None:
+        if not data.endswith("\n"):
+            data += "\n"
+        self._chan.send(data)
+
+    def read_until(self, marker: str, timeout: float = 30.0) -> ShellResult:
+        """Read output until *marker* appears or *timeout* elapses."""
+        start = time.time()
+        buf = ""
+        self._chan.settimeout(0.5)
+        while time.time() - start < timeout:
+            try:
+                chunk = self._chan.recv(65536)
+                if not chunk:
+                    break
+                buf += chunk.decode(self.encoding, errors="replace")
+                if marker in buf:
+                    return ShellResult(buf, marker, False, time.time() - start)
+            except socket.timeout:
+                continue
+        return ShellResult(buf, None, True, time.time() - start)
+
+    def read_available(self) -> str:
+        out = ""
+        self._chan.settimeout(0.2)
+        while self._chan.recv_ready():
+            try:
+                out += self._chan.recv(65536).decode(self.encoding, errors="replace")
+            except socket.timeout:
+                break
+        return out
+
+    def close(self) -> None:
+        try:
+            self._chan.close()
+        except Exception:
+            pass
+
+    def __enter__(self) -> "ShellSession":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+# --------------------------------------------------------------------------- #
+# The handler
+# --------------------------------------------------------------------------- #
+class SSHHandler:
+    """High-level SSH + SFTP + SCP handler. See package README for recipes."""
+
+    _POLICIES = {
+        "auto": paramiko.AutoAddPolicy,
+        "reject": paramiko.RejectPolicy,
+        "warn": paramiko.WarningPolicy,
+    }
+
+    def __init__(
+        self,
+        config: SSHConfig,
+        *,
+        log_callback: Optional[Callable[[str], None]] = None,
+        logger: Optional[logging.Logger] = None,
+        safe: bool = False,
+    ):
+        self.config = config
+        self._safe_default = safe
+        self._log_callback = log_callback
+        self.log = logger or self._build_logger()
+
+        self._client: Optional[paramiko.SSHClient] = None
+        self._sftp: Optional[paramiko.SFTPClient] = None
+        self._jump: Optional["SSHHandler"] = None
+        self._remote_os: Optional[str] = (
+            None if config.remote_os == "auto" else config.remote_os
+        )
+
+    # ------------------------------------------------------------------ #
+    # Logging (secret-aware)
+    # ------------------------------------------------------------------ #
+    def _build_logger(self) -> logging.Logger:
+        logger = logging.getLogger(f"ssh_handler.{self.config.host}")
+        if not logger.handlers:
+            handler = logging.StreamHandler()
+            handler.setFormatter(
+                logging.Formatter("%(asctime)s [%(levelname)s] %(name)s: %(message)s")
+            )
+            logger.addHandler(handler)
+            logger.setLevel(logging.INFO)
+        return logger
+
+    def _secrets(self) -> list:
+        s = [self.config.password, self.config.key_passphrase]
+        if self.config.jump_host:
+            s += [self.config.jump_host.password, self.config.jump_host.key_passphrase]
+        return [x for x in s if x]
+
+    def _emit(self, level: int, msg: str) -> None:
+        safe_msg = mask(msg, *self._secrets())
+        self.log.log(level, safe_msg)
+        if self._log_callback:
+            try:
+                self._log_callback(f"[{logging.getLevelName(level)}] {safe_msg}")
+            except Exception:
+                pass
+
+    # ------------------------------------------------------------------ #
+    # Safe-mode wrapper
+    # ------------------------------------------------------------------ #
+    def _guard(self, action: str, fn, *args, safe: Optional[bool] = None, **kwargs):
+        use_safe = self._safe_default if safe is None else safe
+        if not use_safe:
+            return fn(*args, **kwargs)
+        try:
+            return OperationResult(True, action, value=fn(*args, **kwargs))
+        except Exception as exc:
+            self._emit(logging.ERROR, f"{action} failed: {exc}")
+            return OperationResult(False, action, error=exc)
+
+    # ------------------------------------------------------------------ #
+    # State
+    # ------------------------------------------------------------------ #
+    @property
+    def is_connected(self) -> bool:
+        if self._client is None:
+            return False
+        t = self._client.get_transport()
+        return bool(t and t.is_active())
+
+    @property
+    def client(self) -> paramiko.SSHClient:
+        """The underlying paramiko SSHClient (for anything not wrapped here)."""
+        self._ensure_connected()
+        return self._client
+
+    @property
+    def transport(self) -> paramiko.Transport:
+        return self.client.get_transport()
+
+    def _ensure_connected(self) -> None:
+        if self.is_connected:
+            return
+        if self.config.auto_reconnect:
+            self._emit(logging.WARNING, "Session not active; reconnecting…")
+            self._connect_with_retries()
+        else:
+            raise SSHNotConnectedError("Not connected (auto_reconnect disabled).")
+
+    # ------------------------------------------------------------------ #
+    # Connect / disconnect
+    # ------------------------------------------------------------------ #
+    def connect(self, *, safe: Optional[bool] = None):
+        return self._guard("connect", self._connect_with_retries, safe=safe)
+
+    def _make_client(self) -> paramiko.SSHClient:
+        client = paramiko.SSHClient()
+        if self.config.known_hosts:
+            try:
+                client.load_host_keys(os.path.expanduser(self.config.known_hosts))
+            except FileNotFoundError:
+                self._emit(logging.WARNING,
+                           f"known_hosts not found: {self.config.known_hosts}")
+        else:
+            client.load_system_host_keys()
+        policy = self._POLICIES.get(self.config.host_key_policy, paramiko.AutoAddPolicy)
+        client.set_missing_host_key_policy(policy())
+        return client
+
+    def _open_jump_channel(self):
+        """Connect the jump host and return a direct-tcpip channel to target."""
+        self._jump = SSHHandler(
+            self.config.jump_host,
+            log_callback=self._log_callback,
+            logger=self.log,
+        )
+        self._jump._connect_with_retries()
+        self._emit(logging.INFO, f"Tunnelling through jump host "
+                                 f"{self.config.jump_host.host}.")
+        return self._jump.transport.open_channel(
+            "direct-tcpip",
+            dest_addr=(self.config.host, self.config.port),
+            src_addr=("127.0.0.1", 0),
+        )
+
+    def _build_connect_kwargs(self, *, empty_password: bool, sock) -> dict:
+        cfg = self.config
+        pw = cfg.password.reveal() if isinstance(cfg.password, Secret) else cfg.password
+        passphrase = (cfg.key_passphrase.reveal()
+                      if isinstance(cfg.key_passphrase, Secret) else cfg.key_passphrase)
+        has_password = pw is not None and pw != ""
+
+        kwargs: dict = {
+            "hostname": cfg.host,
+            "port": cfg.port,
+            "username": cfg.auth_username,
+            "timeout": cfg.connect_timeout,
+            "auth_timeout": cfg.auth_timeout,
+            "banner_timeout": cfg.banner_timeout,
+            "compress": cfg.compress,
+            "allow_agent": cfg.allow_agent,
+            "look_for_keys": cfg.look_for_keys,
+        }
+        if sock is not None:
+            kwargs["sock"] = sock
+
+        keys = cfg.normalized_key_files()
+        if keys:
+            kwargs["key_filename"] = keys
+        if passphrase:
+            kwargs["passphrase"] = passphrase
+
+        if cfg.passwordless:
+            kwargs["allow_agent"] = True
+            kwargs["look_for_keys"] = True
+        elif empty_password:
+            kwargs["password"] = ""
+            kwargs["look_for_keys"] = False
+            kwargs["allow_agent"] = False
+        elif has_password:
+            kwargs["password"] = pw
+            # Performance: with a password and no explicit key, skip the slow
+            # agent/key probing that otherwise runs first (and can trip the
+            # server's MaxAuthTries -> "Too many authentication failures").
+            if cfg.fast_auth and not keys:
+                kwargs["allow_agent"] = False
+                kwargs["look_for_keys"] = False
+        return kwargs
+
+    def _attempt_strategies(self, sock) -> None:
+        cfg = self.config
+        last_auth: Optional[Exception] = None
+        strategies = [False]
+        if cfg.allow_empty_password and not cfg.passwordless:
+            strategies.append(True)
+
+        for empty in strategies:
+            client = self._make_client()
+            kwargs = self._build_connect_kwargs(empty_password=empty, sock=sock)
+            label = "empty-password" if empty else "primary"
+            try:
+                self._emit(logging.DEBUG, f"Auth attempt ({label}) as "
+                                          f"{cfg.auth_username}…")
+                client.connect(**kwargs)
+                self._client = client
+                self._post_connect()
+                self._emit(logging.INFO,
+                           f"Connected to {cfg.auth_username}@{cfg.host}:{cfg.port} "
+                           f"({label}).")
+                return
+            except paramiko.AuthenticationException as exc:
+                last_auth = exc
+                client.close()
+                self._emit(logging.DEBUG, f"Auth strategy '{label}' rejected.")
+            except (paramiko.SSHException, OSError) as exc:
+                client.close()
+                raise exc
+        raise SSHAuthenticationError(
+            f"All authentication strategies failed for "
+            f"{cfg.auth_username}@{cfg.host}: {last_auth}"
+        )
+
+    def _connect_with_retries(self) -> "SSHHandler":
+        cfg = self.config
+        attempt, delay, last_exc = 0, cfg.retry_backoff, None
+        while attempt < max(1, cfg.max_retries):
+            attempt += 1
+            sock = None
+            try:
+                if cfg.jump_host:
+                    sock = self._open_jump_channel()
+                self._attempt_strategies(sock)
+                return self
+            except SSHAuthenticationError:
+                raise  # retrying won't help
+            except socket.timeout as exc:
+                last_exc = exc
+                self._emit(logging.WARNING,
+                           f"Connect timeout (attempt {attempt}/{cfg.max_retries}).")
+            except (OSError, paramiko.SSHException) as exc:
+                last_exc = exc
+                self._emit(logging.WARNING,
+                           f"Connect error (attempt {attempt}/{cfg.max_retries}): {exc}")
+            if attempt < cfg.max_retries:
+                time.sleep(delay)
+                delay *= cfg.retry_backoff
+
+        if isinstance(last_exc, socket.timeout):
+            raise SSHTimeoutError(f"Timed out connecting to {cfg.host}:{cfg.port}") \
+                from last_exc
+        raise SSHConnectionError(f"Could not connect to {cfg.host}:{cfg.port}: "
+                                 f"{last_exc}") from last_exc
+
+    def _post_connect(self) -> None:
+        t = self._client.get_transport()
+        if t and self.config.keepalive_interval > 0:
+            t.set_keepalive(self.config.keepalive_interval)
+        self._sftp = None
+
+    def disconnect(self) -> None:
+        if self._sftp is not None:
+            try:
+                self._sftp.close()
+            except Exception:
+                pass
+            self._sftp = None
+        if self._client is not None:
+            try:
+                self._client.close()
+            except Exception:
+                pass
+            self._emit(logging.INFO, f"Disconnected from {self.config.host}.")
+            self._client = None
+        if self._jump is not None:
+            self._jump.disconnect()
+            self._jump = None
+
+    close = disconnect
+
+    # ------------------------------------------------------------------ #
+    # Remote OS awareness
+    # ------------------------------------------------------------------ #
+    def detect_os(self) -> str:
+        """Return 'windows' or 'linux' (cached). Runs one probe command."""
+        if self._remote_os:
+            return self._remote_os
+        self._ensure_connected()
+        probe = self._run("uname -s || ver", timeout=10, check=False,
+                          get_pty=False, environment=None, encoding="utf-8")
+        text = (probe.stdout + probe.stderr).lower()
+        self._remote_os = "windows" if ("windows" in text or "microsoft" in text) \
+            else "linux"
+        self._emit(logging.DEBUG, f"Detected remote OS: {self._remote_os}")
+        return self._remote_os
+
+    @property
+    def is_windows(self) -> bool:
+        return self.detect_os() == "windows"
+
+    # ------------------------------------------------------------------ #
+    # Command execution
+    # ------------------------------------------------------------------ #
+    def run(self, command: str, *, timeout: Optional[float] = None,
+            check: bool = False, get_pty: bool = False,
+            environment: Optional[dict] = None, encoding: str = "utf-8",
+            safe: Optional[bool] = None):
+        """Execute a command. Returns CommandResult (or OperationResult if safe)."""
+        return self._guard("run", self._run, command, timeout=timeout, check=check,
+                           get_pty=get_pty, environment=environment,
+                           encoding=encoding, safe=safe)
+
+    def _run(self, command, *, timeout, check, get_pty, environment, encoding):
+        self._ensure_connected()
+        eff_timeout = timeout if timeout is not None else self.config.command_timeout
+        self._emit(logging.INFO, f"$ {command}")
+        start = time.time()
+        try:
+            _, stdout, stderr = self._client.exec_command(
+                command, timeout=eff_timeout, get_pty=get_pty, environment=environment)
+            exit_code = stdout.channel.recv_exit_status()
+            out = stdout.read().decode(encoding, errors="replace")
+            err = stderr.read().decode(encoding, errors="replace")
+        except socket.timeout as exc:
+            raise SSHTimeoutError(
+                f"Command timed out after {eff_timeout}s: {command!r}") from exc
+        except paramiko.SSHException as exc:
+            res = CommandResult(command, -1, "", str(exc), time.time() - start,
+                                host=self.config.host)
+            raise SSHCommandError(command, res) from exc
+
+        result = CommandResult(command, exit_code, out, err, time.time() - start,
+                               host=self.config.host)
+        lvl = logging.INFO if result.ok else logging.WARNING
+        self._emit(lvl, f"exit={result.exit_code} ({result.duration:.2f}s)")
+        if check and not result.ok:
+            raise SSHCommandError(command, result)
+        return result
+
+    def run_many(self, commands: Sequence[str], *, stop_on_error: bool = True,
+                 **kwargs) -> list[CommandResult]:
+        results = []
+        for cmd in commands:
+            res = self._run(cmd, timeout=kwargs.get("timeout"), check=False,
+                            get_pty=kwargs.get("get_pty", False),
+                            environment=kwargs.get("environment"),
+                            encoding=kwargs.get("encoding", "utf-8"))
+            results.append(res)
+            if stop_on_error and not res.ok:
+                self._emit(logging.WARNING,
+                           f"Stopping batch: {cmd!r} exited {res.exit_code}.")
+                break
+        return results
+
+    def sudo(self, command: str, password: Optional[Union[str, Secret]] = None,
+             *, timeout: Optional[float] = None, check: bool = False,
+             safe: Optional[bool] = None):
+        """Run a command via ``sudo -S`` feeding the password on stdin."""
+        pw = password if password is not None else self.config.password
+        raw = pw.reveal() if isinstance(pw, Secret) else (pw or "")
+
+        def _do():
+            self._ensure_connected()
+            full = f"sudo -S -p '' {command}"
+            self._emit(logging.INFO, f"$ sudo {command}")
+            start = time.time()
+            stdin, stdout, stderr = self._client.exec_command(full, timeout=timeout,
+                                                              get_pty=True)
+            if raw:
+                stdin.write(raw + "\n")
+                stdin.flush()
+            exit_code = stdout.channel.recv_exit_status()
+            out = stdout.read().decode("utf-8", errors="replace")
+            err = stderr.read().decode("utf-8", errors="replace")
+            result = CommandResult(f"sudo {command}", exit_code, out, err,
+                                   time.time() - start, host=self.config.host)
+            if check and not result.ok:
+                raise SSHCommandError(command, result)
+            return result
+
+        return self._guard("sudo", _do, safe=safe)
+
+    # ------------------------------------------------------------------ #
+    # Interactive shell
+    # ------------------------------------------------------------------ #
+    def open_shell(self, *, term: str = "xterm", width: int = 200,
+                   height: int = 50, safe: Optional[bool] = None):
+        """Open a persistent interactive ShellSession (PTY)."""
+        def _do():
+            self._ensure_connected()
+            chan = self._client.invoke_shell(term=term, width=width, height=height)
+            return ShellSession(chan)
+        return self._guard("open_shell", _do, safe=safe)
+
+    # ------------------------------------------------------------------ #
+    # SFTP — full operation surface
+    # ------------------------------------------------------------------ #
+    def sftp(self) -> paramiko.SFTPClient:
+        """Return the live SFTPClient (opened lazily, reused)."""
+        self._ensure_connected()
+        if self._sftp is None:
+            self._sftp = self._client.open_sftp()
+        return self._sftp
+
+    @staticmethod
+    def _rnorm(path: str) -> str:
+        return path.replace("\\", "/")
+
+    def _remote_is_dir(self, sftp, path: str) -> bool:
+        try:
+            return stat.S_ISDIR(sftp.stat(path).st_mode)
+        except IOError:
+            return False
+
+    def _remote_exists(self, sftp, path: str) -> bool:
+        try:
+            sftp.stat(path)
+            return True
+        except IOError:
+            return False
+
+    def _mkdir_p(self, sftp, remote_dir: str) -> None:
+        remote_dir = self._rnorm(remote_dir)
+        if remote_dir in ("", "/", "."):
+            return
+        is_abs = remote_dir.startswith("/")
+        parts = [p for p in remote_dir.split("/") if p]
+        current = ""
+        for part in parts:
+            current = (f"/{part}" if is_abs else part) if current == "" \
+                else f"{current}/{part}"
+            if not self._remote_exists(sftp, current):
+                try:
+                    sftp.mkdir(current)
+                except IOError:
+                    pass
+
+    # thin pass-throughs (paramiko parity) -----------------------------
+    def listdir(self, path: str = ".", *, safe=None):
+        return self._guard("listdir", lambda: self.sftp().listdir(self._rnorm(path)),
+                           safe=safe)
+
+    def listdir_attr(self, path: str = ".", *, safe=None):
+        return self._guard("listdir_attr",
+                           lambda: self.sftp().listdir_attr(self._rnorm(path)), safe=safe)
+
+    def stat(self, path: str, *, safe=None):
+        return self._guard("stat", lambda: self.sftp().stat(self._rnorm(path)), safe=safe)
+
+    def lstat(self, path: str, *, safe=None):
+        return self._guard("lstat", lambda: self.sftp().lstat(self._rnorm(path)),
+                           safe=safe)
+
+    def exists(self, path: str, *, safe=None):
+        return self._guard("exists",
+                           lambda: self._remote_exists(self.sftp(), self._rnorm(path)),
+                           safe=safe)
+
+    def isdir(self, path: str, *, safe=None):
+        return self._guard("isdir",
+                           lambda: self._remote_is_dir(self.sftp(), self._rnorm(path)),
+                           safe=safe)
+
+    def mkdir(self, path: str, mode: int = 0o777, *, safe=None):
+        return self._guard("mkdir",
+                           lambda: self.sftp().mkdir(self._rnorm(path), mode), safe=safe)
+
+    def makedirs(self, path: str, *, safe=None):
+        return self._guard("makedirs", lambda: self._mkdir_p(self.sftp(), path),
+                           safe=safe)
+
+    def rmdir(self, path: str, *, safe=None):
+        return self._guard("rmdir", lambda: self.sftp().rmdir(self._rnorm(path)),
+                           safe=safe)
+
+    def remove(self, path: str, *, safe=None):
+        return self._guard("remove", lambda: self.sftp().remove(self._rnorm(path)),
+                           safe=safe)
+
+    def rename(self, old: str, new: str, *, safe=None):
+        return self._guard("rename",
+                           lambda: self.sftp().posix_rename(self._rnorm(old),
+                                                            self._rnorm(new)), safe=safe)
+
+    def chmod(self, path: str, mode: int, *, safe=None):
+        return self._guard("chmod", lambda: self.sftp().chmod(self._rnorm(path), mode),
+                           safe=safe)
+
+    def chown(self, path: str, uid: int, gid: int, *, safe=None):
+        return self._guard("chown",
+                           lambda: self.sftp().chown(self._rnorm(path), uid, gid),
+                           safe=safe)
+
+    def symlink(self, source: str, dest: str, *, safe=None):
+        return self._guard("symlink",
+                           lambda: self.sftp().symlink(source, self._rnorm(dest)),
+                           safe=safe)
+
+    def readlink(self, path: str, *, safe=None):
+        return self._guard("readlink", lambda: self.sftp().readlink(self._rnorm(path)),
+                           safe=safe)
+
+    def open(self, path: str, mode: str = "r", bufsize: int = -1, *, safe=None):
+        """Open a remote file object (paramiko SFTPFile)."""
+        return self._guard("open",
+                           lambda: self.sftp().open(self._rnorm(path), mode, bufsize),
+                           safe=safe)
+
+    def read_text(self, path: str, encoding: str = "utf-8", *, safe=None):
+        def _do():
+            with self.sftp().open(self._rnorm(path), "r") as fh:
+                return fh.read().decode(encoding, errors="replace")
+        return self._guard("read_text", _do, safe=safe)
+
+    def write_text(self, path: str, data: str, encoding: str = "utf-8", *, safe=None):
+        def _do():
+            with self.sftp().open(self._rnorm(path), "w") as fh:
+                fh.write(data.encode(encoding))
+            return len(data)
+        return self._guard("write_text", _do, safe=safe)
+
+    def walk(self, remote_path: str):
+        """Generator like os.walk over a remote tree (dirpath, dirs, files)."""
+        sftp = self.sftp()
+        remote_path = self._rnorm(remote_path)
+        dirs, files = [], []
+        for entry in sftp.listdir_attr(remote_path):
+            (dirs if stat.S_ISDIR(entry.st_mode) else files).append(entry.filename)
+        yield remote_path, dirs, files
+        for d in dirs:
+            yield from self.walk(posixpath.join(remote_path, d))
+
+    # ------------------------------------------------------------------ #
+    # Push / Pull (SFTP) with TransferResult
+    # ------------------------------------------------------------------ #
+    def push(self, local_path: str, remote_path: str, *, recursive: bool = False,
+             make_dirs: bool = True, callback=None, safe: Optional[bool] = None):
+        """Upload a file or directory (SFTP). Returns TransferResult."""
+        return self._guard("push", self._push, local_path, remote_path,
+                           recursive=recursive, make_dirs=make_dirs,
+                           callback=callback, safe=safe)
+
+    def _push(self, local_path, remote_path, *, recursive, make_dirs, callback):
+        local_path = os.path.expanduser(local_path)
+        remote_path = self._rnorm(remote_path)
+        sftp = self.sftp()
+        if not os.path.exists(local_path):
+            raise SSHTransferError(f"Local path does not exist: {local_path}")
+        start = time.time()
+        try:
+            if os.path.isdir(local_path):
+                if not recursive:
+                    raise SSHTransferError(f"{local_path} is a directory; "
+                                           f"pass recursive=True.")
+                size, count = self._push_dir(sftp, local_path, remote_path, callback)
+            else:
+                if make_dirs:
+                    parent = posixpath.dirname(remote_path)
+                    if parent:
+                        self._mkdir_p(sftp, parent)
+                self._emit(logging.INFO, f"PUSH {local_path} -> {remote_path}")
+                sftp.put(local_path, remote_path, callback=callback)
+                size, count = os.path.getsize(local_path), 1
+        except SSHTransferError:
+            raise
+        except (IOError, OSError, paramiko.SSHException) as exc:
+            raise SSHTransferError(f"Failed to push {local_path} -> {remote_path}: "
+                                   f"{exc}") from exc
+        return TransferResult(local_path, remote_path, "push", "sftp", size,
+                              time.time() - start, count)
+
+    def _push_dir(self, sftp, local_dir, remote_dir, callback):
+        self._mkdir_p(sftp, remote_dir)
+        total, count = 0, 0
+        for entry in os.listdir(local_dir):
+            lpath = os.path.join(local_dir, entry)
+            rpath = posixpath.join(remote_dir, entry)
+            if os.path.isdir(lpath):
+                s, c = self._push_dir(sftp, lpath, rpath, callback)
+                total += s
+                count += c
+            else:
+                self._emit(logging.INFO, f"PUSH {lpath} -> {rpath}")
+                sftp.put(lpath, rpath, callback=callback)
+                total += os.path.getsize(lpath)
+                count += 1
+        return total, count
+
+    def pull(self, remote_path: str, local_path: str, *, recursive: bool = False,
+             make_dirs: bool = True, callback=None, safe: Optional[bool] = None):
+        """Download a file or directory (SFTP). Returns TransferResult."""
+        return self._guard("pull", self._pull, remote_path, local_path,
+                           recursive=recursive, make_dirs=make_dirs,
+                           callback=callback, safe=safe)
+
+    def _pull(self, remote_path, local_path, *, recursive, make_dirs, callback):
+        remote_path = self._rnorm(remote_path)
+        local_path = os.path.expanduser(local_path)
+        sftp = self.sftp()
+        start = time.time()
+        try:
+            if self._remote_is_dir(sftp, remote_path):
+                if not recursive:
+                    raise SSHTransferError(f"{remote_path} is a directory; "
+                                           f"pass recursive=True.")
+                size, count = self._pull_dir(sftp, remote_path, local_path, callback)
+            else:
+                if make_dirs:
+                    parent = os.path.dirname(local_path)
+                    if parent and not os.path.exists(parent):
+                        os.makedirs(parent, exist_ok=True)
+                self._emit(logging.INFO, f"PULL {remote_path} -> {local_path}")
+                sftp.get(remote_path, local_path, callback=callback)
+                size, count = os.path.getsize(local_path), 1
+        except SSHTransferError:
+            raise
+        except (IOError, OSError, paramiko.SSHException) as exc:
+            raise SSHTransferError(f"Failed to pull {remote_path} -> {local_path}: "
+                                   f"{exc}") from exc
+        return TransferResult(remote_path, local_path, "pull", "sftp", size,
+                              time.time() - start, count)
+
+    def _pull_dir(self, sftp, remote_dir, local_dir, callback):
+        os.makedirs(local_dir, exist_ok=True)
+        total, count = 0, 0
+        for entry in sftp.listdir_attr(remote_dir):
+            rpath = posixpath.join(remote_dir, entry.filename)
+            lpath = os.path.join(local_dir, entry.filename)
+            if stat.S_ISDIR(entry.st_mode):
+                s, c = self._pull_dir(sftp, rpath, lpath, callback)
+                total += s
+                count += c
+            else:
+                self._emit(logging.INFO, f"PULL {rpath} -> {lpath}")
+                sftp.get(rpath, lpath, callback=callback)
+                total += entry.st_size or 0
+                count += 1
+        return total, count
+
+    # ------------------------------------------------------------------ #
+    # SCP (optional, via the 'scp' package)
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def scp_available() -> bool:
+        return _HAS_SCP
+
+    def _scp_client(self, callback=None):
+        if not _HAS_SCP:
+            raise SSHTransferError(
+                "SCP support needs the 'scp' package. Install it with: pip install scp "
+                "(SFTP push/pull already works without it).")
+        self._ensure_connected()
+        progress = (lambda fn, sz, sent: callback(sent, sz)) if callback else None
+        return SCPClient(self.transport, progress=progress)
+
+    def scp_push(self, local_path: str, remote_path: str, *, recursive: bool = False,
+                 callback=None, safe: Optional[bool] = None):
+        """Upload via the SCP protocol (alternative to SFTP push)."""
+        def _do():
+            start = time.time()
+            with self._scp_client(callback) as scp:
+                scp.put(os.path.expanduser(local_path), remote_path,
+                        recursive=recursive)
+            size = (os.path.getsize(os.path.expanduser(local_path))
+                    if os.path.isfile(os.path.expanduser(local_path)) else 0)
+            return TransferResult(local_path, remote_path, "push", "scp", size,
+                                  time.time() - start)
+        return self._guard("scp_push", _do, safe=safe)
+
+    def scp_pull(self, remote_path: str, local_path: str, *, recursive: bool = False,
+                 callback=None, safe: Optional[bool] = None):
+        """Download via the SCP protocol (alternative to SFTP pull)."""
+        def _do():
+            start = time.time()
+            with self._scp_client(callback) as scp:
+                scp.get(remote_path, os.path.expanduser(local_path),
+                        recursive=recursive)
+            lp = os.path.expanduser(local_path)
+            size = os.path.getsize(lp) if os.path.isfile(lp) else 0
+            return TransferResult(remote_path, local_path, "pull", "scp", size,
+                                  time.time() - start)
+        return self._guard("scp_pull", _do, safe=safe)
+
+    # ------------------------------------------------------------------ #
+    # Context manager
+    # ------------------------------------------------------------------ #
+    def __enter__(self) -> "SSHHandler":
+        result = self.connect()
+        if isinstance(result, OperationResult) and not result.success:
+            raise result.error or SSHConnectionError("connect failed")
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.disconnect()
+
+    def __repr__(self) -> str:
+        state = "connected" if self.is_connected else "disconnected"
+        return (f"<SSHHandler {self.config.auth_username}@{self.config.host}:"
+                f"{self.config.port} {state}>")