ssh-server-manager 0.2.0__py3-none-any.whl

ssh_server_manager/paths.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from pathlib import Path
+
+
+APP_NAME = "ssh-server-manager"
+
+
+def skill_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def data_dir() -> Path:
+    override = os.environ.get("SSM_DATA_DIR")
+    if override:
+        return Path(override).expanduser().resolve()
+    try:
+        from platformdirs import user_data_path
+
+        return Path(user_data_path(APP_NAME, appauthor=False))
+    except ImportError:
+        home = Path.home()
+        if sys.platform == "darwin":
+            return home / "Library" / "Application Support" / APP_NAME
+        if os.name == "nt":
+            return Path(os.environ.get("LOCALAPPDATA", home / "AppData" / "Local")) / APP_NAME
+        return Path(os.environ.get("XDG_DATA_HOME", home / ".local" / "share")) / APP_NAME
+
+
+def ensure_private_dir(path: Path) -> Path:
+    if path.exists() or path.is_symlink():
+        info = path.lstat()
+        if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+            raise RuntimeError(f"private data path is not a real directory: {path}")
+        if os.name != "nt" and info.st_uid != os.getuid():
+            raise RuntimeError(f"private data directory is owned by another user: {path}")
+    else:
+        path.mkdir(parents=True, mode=stat.S_IRWXU)
+    if os.name != "nt":
+        current_mode = stat.S_IMODE(path.stat().st_mode)
+        if current_mode != stat.S_IRWXU:
+            path.chmod(stat.S_IRWXU)
+    return path
+
+
+def database_path() -> Path:
+    return data_dir() / "manager.db"
+
+
+def runtime_dir() -> Path:
+    override = os.environ.get("SSM_RUNTIME_DIR")
+    if override:
+        base = Path(override).expanduser()
+    elif os.name == "nt":
+        base = data_dir() / "runtime"
+    else:
+        # Keep this path short: OpenSSH limits Unix-domain ControlPath length.
+        base = Path("/tmp") / f"ssm-{os.getuid()}"
+    return ensure_private_dir(base.resolve())
+
+
+def original_ssh_config_path() -> Path:
+    override = os.environ.get("SSM_ORIGINAL_SSH_CONFIG")
+    if override:
+        return Path(override).expanduser().resolve()
+    return Path.home() / ".ssh" / "config"
+
+
+def managed_ssh_config_path() -> Path:
+    override = os.environ.get("SSM_MANAGED_SSH_CONFIG")
+    if override:
+        return Path(override).expanduser().resolve()
+    return Path.home() / ".ssh" / "ssh-server-manager.conf"
+
+
+def asset_dir() -> Path:
+    return Path(__file__).resolve().parent / "assets" / "ui"

ssh_server_manager/service.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from typing import Any
+
+from .db import Database
+from .vault import VaultProtocol
+
+
+class CredentialService:
+    def __init__(self, database: Database, vault: VaultProtocol) -> None:
+        self.database = database
+        self.vault = vault
+
+    def create_password(self, label: str, secret: str) -> dict[str, Any]:
+        identifier = str(uuid.uuid4())
+        credential = self.database.create_credential(
+            credential_id=identifier, label=label, kind="password", has_secret=False
+        )
+        try:
+            self.vault.set_secret(identifier, "password", secret)
+            return self.database.update_credential(identifier, has_secret=True)
+        except Exception:
+            self.vault.delete_secret(identifier, "password")
+            self.database.delete_credential(identifier)
+            raise
+
+    def create_key(self, label: str, key_path: str, passphrase: str | None = None) -> dict[str, Any]:
+        identifier = str(uuid.uuid4())
+        credential = self.database.create_credential(
+            credential_id=identifier,
+            label=label,
+            kind="key",
+            key_path=key_path,
+            has_passphrase=False,
+        )
+        if not passphrase:
+            return credential
+        try:
+            self.vault.set_secret(identifier, "passphrase", passphrase)
+            return self.database.update_credential(identifier, has_passphrase=True)
+        except Exception:
+            self.vault.delete_secret(identifier, "passphrase")
+            self.database.delete_credential(identifier)
+            raise
+
+    def create_agent(self, label: str) -> dict[str, Any]:
+        return self.database.create_credential(label=label, kind="agent")
+
+    def update(
+        self,
+        identifier: str,
+        *,
+        label: str | None = None,
+        key_path: str | None = None,
+        secret: str | None = None,
+        passphrase: str | None = None,
+        clear_passphrase: bool = False,
+    ) -> dict[str, Any]:
+        credential = self.database.get_credential(identifier)
+        changes: dict[str, Any] = {}
+        if label is not None:
+            changes["label"] = label
+        if key_path is not None:
+            changes["key_path"] = key_path
+        if secret is not None:
+            if credential["kind"] != "password":
+                raise ValueError("only password credentials have a password secret")
+            self.vault.set_secret(credential["id"], "password", secret)
+            changes["has_secret"] = True
+        if passphrase is not None:
+            if credential["kind"] != "key":
+                raise ValueError("only key credentials have a passphrase")
+            self.vault.set_secret(credential["id"], "passphrase", passphrase)
+            changes["has_passphrase"] = True
+        if clear_passphrase:
+            self.vault.delete_secret(credential["id"], "passphrase")
+            changes["has_passphrase"] = False
+        return self.database.update_credential(credential["id"], **changes) if changes else credential
+
+    def delete(self, identifier: str) -> dict[str, Any]:
+        credential = self.database.get_credential(identifier)
+        # The database enforces that referenced credentials cannot be removed.
+        removed = self.database.delete_credential(credential["id"])
+        self.vault.delete_secret(credential["id"], "password")
+        self.vault.delete_secret(credential["id"], "passphrase")
+        return removed
+
+    def reveal(self, identifier: str) -> dict[str, Any]:
+        credential = self.database.get_credential(identifier)
+        if credential["kind"] == "password":
+            slot = "password"
+        elif credential["kind"] == "key" and credential["has_passphrase"]:
+            slot = "passphrase"
+        else:
+            raise ValueError("this credential has no revealable secret")
+        value = self.vault.get_secret(credential["id"], slot)
+        if value is None:
+            raise ValueError("the OS credential vault has no matching secret")
+        return {"credential_id": credential["id"], "slot": slot, "value": value}
+

ssh_server_manager/ssh_config.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import glob
+import os
+import shlex
+import stat
+import tempfile
+from pathlib import Path
+from typing import Iterable
+
+from .db import Database
+from .paths import managed_ssh_config_path, original_ssh_config_path
+
+
+class SSHConfigError(RuntimeError):
+    pass
+
+
+def quote_value(value: str) -> str:
+    if not value or any(ch.isspace() or ch in {'"', "'", "#", "\\"} for ch in value):
+        return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+    return value
+
+
+def split_config_line(line: str) -> list[str]:
+    """Tokenize one OpenSSH config line.
+
+    On Windows a backslash is a path separator, not an escape character, so
+    it is preserved before POSIX-style quote handling is applied.
+    """
+    if os.name == "nt":
+        line = line.replace("\\", "\\\\")
+    try:
+        return shlex.split(line, comments=True, posix=True)
+    except ValueError:
+        return []
+
+
+def _parse_include_tokens(line: str) -> list[str]:
+    tokens = split_config_line(line)
+    if not tokens or tokens[0].casefold() != "include":
+        return []
+    return tokens[1:]
+
+
+def _expand_include(pattern: str, parent: Path) -> list[Path]:
+    expanded = os.path.expanduser(pattern)
+    path = Path(expanded)
+    if not path.is_absolute():
+        path = parent / path
+    return [Path(item).resolve() for item in sorted(glob.glob(str(path)))]
+
+
+def includes_target(config: Path, target: Path, seen: set[Path] | None = None) -> bool:
+    config = config.expanduser().resolve()
+    target = target.expanduser().resolve()
+    if not config.exists():
+        return False
+    seen = seen or set()
+    if config in seen:
+        return False
+    seen.add(config)
+    try:
+        lines = config.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError):
+        return False
+    for line in lines:
+        for token in _parse_include_tokens(line):
+            expanded = os.path.expanduser(token)
+            candidate = Path(expanded)
+            if not candidate.is_absolute():
+                candidate = config.parent / candidate
+            try:
+                if candidate.resolve() == target:
+                    return True
+            except OSError:
+                pass
+            for include in _expand_include(token, config.parent):
+                if include == target or includes_target(include, target, seen):
+                    return True
+    return False
+
+
+def _render_server(server: dict, credential: dict | None) -> list[str]:
+    lines = [
+        f"Host {server['alias']}",
+        f"  HostName {quote_value(server['hostname'])}",
+        f"  Port {server['port']}",
+        f"  User {quote_value(server['username'])}",
+    ]
+    jumps = server["proxy_jumps"]
+    lines.append(f"  ProxyJump {','.join(jumps) if jumps else 'none'}")
+    if credential and credential["kind"] == "password":
+        lines.extend(
+            [
+                "  IdentityFile none",
+                "  IdentitiesOnly yes",
+                "  PubkeyAuthentication no",
+                "  PasswordAuthentication yes",
+                "  KbdInteractiveAuthentication yes",
+                "  PreferredAuthentications keyboard-interactive,password",
+            ]
+        )
+    elif credential and credential["kind"] == "key":
+        lines.extend(
+            [
+                f"  IdentityFile {quote_value(credential['key_path'])}",
+                "  IdentitiesOnly yes",
+                "  PubkeyAuthentication yes",
+                "  PreferredAuthentications publickey",
+            ]
+        )
+    lines.append("")
+    return lines
+
+
+def render_config(
+    database: Database,
+    *,
+    destination: str | Path | None = None,
+    original: str | Path | None = None,
+) -> Path:
+    destination_path = Path(destination) if destination else managed_ssh_config_path()
+    original_path = Path(original) if original else original_ssh_config_path()
+    destination_path = destination_path.expanduser().resolve()
+    original_path = original_path.expanduser().resolve()
+    if includes_target(original_path, destination_path):
+        raise SSHConfigError(
+            f"refusing to create an Include cycle: {original_path} already includes {destination_path}"
+        )
+    lines = [
+        "# Generated by ssh-server-manager. Do not edit this file directly.",
+        "# Edit hosts with serverctl or the local UI.",
+        "",
+    ]
+    credentials = {item["id"]: item for item in database.list_credentials()}
+    for server in database.list_servers():
+        lines.extend(_render_server(server, credentials.get(server["credential_id"])))
+    if original_path.exists() and original_path != destination_path:
+        lines.extend([f"Include {quote_value(str(original_path))}", ""])
+    content = "\n".join(lines)
+    destination_path.parent.mkdir(parents=True, exist_ok=True)
+    if os.name != "nt":
+        destination_path.parent.chmod(stat.S_IRWXU)
+    file_descriptor, temporary = tempfile.mkstemp(prefix=".ssh-server-manager-", dir=destination_path.parent)
+    temporary_path = Path(temporary)
+    try:
+        with os.fdopen(file_descriptor, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if os.name != "nt":
+            temporary_path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+        os.replace(temporary_path, destination_path)
+    finally:
+        temporary_path.unlink(missing_ok=True)
+    return destination_path
+
+
+def effective_config_args(database: Database) -> list[str]:
+    return ["-F", str(render_config(database))]
+

ssh_server_manager/ssh_runner.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import shutil
+import stat
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Sequence
+
+from .db import Database, NotFoundError
+from .paths import runtime_dir
+from .ssh_config import render_config
+
+
+class SSHError(RuntimeError):
+    pass
+
+
+PROMPT_REDACTIONS = [
+    (re.compile(r"(?i)(password|passphrase)(\s*[:=]\s*)\S+"), r"\1\2[REDACTED]"),
+    (re.compile(r"(?i)(token|secret|cookie)(\s*[:=]\s*)\S+"), r"\1\2[REDACTED]"),
+]
+
+
+def redact(text: str) -> str:
+    result = text
+    for pattern, replacement in PROMPT_REDACTIONS:
+        result = pattern.sub(replacement, result)
+    return result[:4000]
+
+
+def classify_error(stderr: str, returncode: int) -> str:
+    lowered = stderr.casefold()
+    if "host key verification failed" in lowered or "no host key is known" in lowered:
+        return "host-key-untrusted"
+    if "permission denied" in lowered or "authentication failed" in lowered:
+        return "authentication-failed"
+    if "connection timed out" in lowered or "operation timed out" in lowered:
+        return "timeout"
+    if "connection refused" in lowered:
+        return "connection-refused"
+    if "could not resolve hostname" in lowered or "name or service not known" in lowered:
+        return "dns-failed"
+    if "no route to host" in lowered or "network is unreachable" in lowered:
+        return "network-unreachable"
+    if returncode == 127:
+        return "ssh-not-found"
+    return "ssh-failed"
+
+
+class SSHRunner:
+    def __init__(self, database: Database, *, ssh_binary: str | None = None) -> None:
+        self.database = database
+        self.ssh_binary = ssh_binary or shutil.which("ssh") or "ssh"
+
+    def _credential_descriptor(self, server: dict[str, Any]) -> dict[str, Any] | None:
+        if not server.get("credential_id"):
+            return None
+        credential = self.database.get_credential(server["credential_id"])
+        if credential["kind"] == "password":
+            return {
+                "credential_id": credential["id"],
+                "slot": "password",
+                "alias": server["alias"],
+                "hostname": server["hostname"],
+                "username": server["username"],
+            }
+        if credential["kind"] == "key" and credential["has_passphrase"]:
+            return {
+                "credential_id": credential["id"],
+                "slot": "passphrase",
+                "alias": server["alias"],
+                "hostname": server["hostname"],
+                "username": server["username"],
+                "key_path": credential["key_path"],
+            }
+        return None
+
+    def _auth_descriptors(self, server: dict[str, Any]) -> list[dict[str, Any]]:
+        descriptors: list[dict[str, Any]] = []
+        visited: set[str] = set()
+
+        def add(item: dict[str, Any]) -> None:
+            key = item["alias"].casefold()
+            if key in visited:
+                return
+            visited.add(key)
+            for jump in item["proxy_jumps"]:
+                try:
+                    add(self.database.get_server(jump))
+                except NotFoundError:
+                    continue
+            descriptor = self._credential_descriptor(item)
+            if descriptor:
+                descriptors.append(descriptor)
+
+        add(server)
+        return descriptors
+
+    def _askpass_launcher(self) -> Path:
+        directory = runtime_dir()
+        if os.name == "nt":
+            launcher = Path(sys.executable).parent / "ssh-server-manager-askpass.exe"
+            if not launcher.exists():
+                raise SSHError("Windows AskPass launcher is missing; run scripts\\bootstrap.cmd")
+            return launcher
+        else:
+            # Invoke the packaged module so the launcher works both from a
+            # source checkout and from a pipx/uv tool install. The package
+            # parent goes on PYTHONPATH because ssh launches this in a fresh
+            # process that has no knowledge of how serverctl was started.
+            package_parent = Path(__file__).resolve().parents[1]
+            launcher = directory / "askpass"
+            content = (
+                "#!/bin/sh\n"
+                f'PYTHONPATH={shlex.quote(str(package_parent))}${{PYTHONPATH:+:$PYTHONPATH}}\n'
+                "export PYTHONPATH\n"
+                f'exec {shlex.quote(sys.executable)} -m ssh_server_manager.askpass "$@"\n'
+            )
+        if not launcher.exists() or launcher.read_text(encoding="utf-8") != content:
+            launcher.write_text(content, encoding="utf-8", newline="\n")
+            if os.name != "nt":
+                launcher.chmod(stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR)
+        return launcher
+
+    def _environment(self, server: dict[str, Any]) -> dict[str, str]:
+        environment = os.environ.copy()
+        descriptors = self._auth_descriptors(server)
+        if descriptors:
+            environment["SSH_ASKPASS"] = str(self._askpass_launcher())
+            environment["SSH_ASKPASS_REQUIRE"] = "force"
+            environment.setdefault("DISPLAY", "ssh-server-manager:0")
+            environment["SSM_ASKPASS_MAP"] = json.dumps(descriptors, separators=(",", ":"))
+        return environment
+
+    def _base_command(self, server: dict[str, Any], *, timeout: int, reuse: int = 0) -> list[str]:
+        config = render_config(self.database)
+        command = [
+            self.ssh_binary,
+            "-F",
+            str(config),
+            "-o",
+            f"ConnectTimeout={timeout}",
+            "-o",
+            "ConnectionAttempts=1",
+            "-o",
+            "GSSAPIAuthentication=no",
+            "-o",
+            "ServerAliveInterval=15",
+            "-o",
+            "ServerAliveCountMax=2",
+            "-o",
+            "LogLevel=ERROR",
+        ]
+        if reuse > 0 and os.name != "nt":
+            command.extend(
+                [
+                    "-o",
+                    "ControlMaster=auto",
+                    "-o",
+                    f"ControlPersist={reuse}",
+                    "-o",
+                    f"ControlPath={runtime_dir() / 'cm-%C'}",
+                ]
+            )
+        command.append(server["alias"])
+        return command
+
+    def test(self, identifier: str, *, timeout: int = 8) -> dict[str, Any]:
+        server = self.database.get_server(identifier)
+        command = self._base_command(server, timeout=timeout)
+        command[-1:-1] = ["-T", "-o", "StrictHostKeyChecking=yes", "-o", "NumberOfPasswordPrompts=1"]
+        command.append("true")
+        start = time.monotonic()
+        try:
+            result = subprocess.run(
+                command,
+                text=True,
+                capture_output=True,
+                env=self._environment(server),
+                timeout=timeout + 5,
+                check=False,
+            )
+            latency = round((time.monotonic() - start) * 1000)
+            success = result.returncode == 0
+            error_code = None if success else classify_error(result.stderr, result.returncode)
+            message = "connection succeeded" if success else redact(result.stderr.strip() or "SSH returned no diagnostics")
+        except subprocess.TimeoutExpired:
+            latency = round((time.monotonic() - start) * 1000)
+            success, error_code, message = False, "timeout", f"connection exceeded {timeout + 5} seconds"
+        except OSError as exc:
+            latency = round((time.monotonic() - start) * 1000)
+            success, error_code, message = False, "ssh-not-found", str(exc)
+        self.database.record_test(
+            server["id"],
+            status="ok" if success else "failed",
+            latency_ms=latency,
+            error_code=error_code,
+            message=message,
+        )
+        return {
+            "alias": server["alias"],
+            "ok": success,
+            "latency_ms": latency,
+            "error_code": error_code,
+            "message": message,
+        }
+
+    def connect(self, identifier: str, *, timeout: int = 12) -> int:
+        server = self.database.get_server(identifier)
+        command = self._base_command(server, timeout=timeout)
+        return subprocess.call(command, env=self._environment(server))
+
+    def execute(
+        self,
+        identifier: str,
+        remote_args: Sequence[str],
+        *,
+        stdin_data: str | bytes | None = None,
+        timeout: int = 30,
+        reuse: int = 0,
+        capture: bool = False,
+    ) -> dict[str, Any]:
+        if not remote_args:
+            raise SSHError("a remote command is required after --")
+        server = self.database.get_server(identifier)
+        command = self._base_command(server, timeout=timeout, reuse=reuse)
+        command[-1:-1] = ["-T", "-o", "StrictHostKeyChecking=yes", "-o", "NumberOfPasswordPrompts=1"]
+        command.append(shlex.join(list(remote_args)))
+        start = time.monotonic()
+        binary_input = isinstance(stdin_data, bytes)
+        result = subprocess.run(
+            command,
+            input=stdin_data,
+            text=not binary_input,
+            capture_output=capture,
+            env=self._environment(server),
+            check=False,
+        )
+        output = {
+            "alias": server["alias"],
+            "ok": result.returncode == 0,
+            "returncode": result.returncode,
+            "latency_ms": round((time.monotonic() - start) * 1000),
+        }
+        if capture:
+            stdout = result.stdout
+            stderr = result.stderr
+            if isinstance(stdout, bytes):
+                stdout = stdout.decode("utf-8", errors="replace")
+            if isinstance(stderr, bytes):
+                stderr = stderr.decode("utf-8", errors="replace")
+            output["stdout"] = stdout
+            output["stderr"] = redact(stderr)
+            if result.returncode:
+                output["error_code"] = classify_error(stderr, result.returncode)
+        return output

ssh_server_manager/validation.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import ipaddress
+import re
+from pathlib import Path
+from typing import Iterable
+
+
+ALIAS_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$")
+CONTROL_RE = re.compile(r"[\x00-\x1f\x7f]")
+KINDS = {"password", "key", "agent"}
+
+
+class ValidationError(ValueError):
+    pass
+
+
+def validate_alias(value: str) -> str:
+    value = value.strip()
+    if not ALIAS_RE.fullmatch(value):
+        raise ValidationError("alias must be 1-63 characters using letters, digits, '.', '_' or '-'")
+    return value
+
+
+def validate_hostname(value: str) -> str:
+    value = value.strip()
+    if not value or len(value) > 253 or CONTROL_RE.search(value) or any(c.isspace() for c in value):
+        raise ValidationError("hostname must be a non-empty DNS name or IP address without whitespace")
+    try:
+        ipaddress.ip_address(value.strip("[]"))
+    except ValueError:
+        labels = value.rstrip(".").split(".")
+        if any(not label or len(label) > 63 for label in labels):
+            raise ValidationError("invalid hostname")
+    return value
+
+
+def validate_port(value: int | str) -> int:
+    try:
+        port = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValidationError("port must be an integer") from exc
+    if not 1 <= port <= 65535:
+        raise ValidationError("port must be between 1 and 65535")
+    return port
+
+
+def validate_username(value: str) -> str:
+    value = value.strip()
+    if not value or len(value) > 128 or CONTROL_RE.search(value) or any(c.isspace() for c in value):
+        raise ValidationError("username must not be empty or contain whitespace")
+    return value
+
+
+def validate_label(value: str) -> str:
+    value = value.strip()
+    if not value or len(value) > 100 or CONTROL_RE.search(value):
+        raise ValidationError("credential label must be 1-100 printable characters")
+    return value
+
+
+def validate_kind(value: str) -> str:
+    if value not in KINDS:
+        raise ValidationError(f"credential kind must be one of {', '.join(sorted(KINDS))}")
+    return value
+
+
+def validate_key_path(value: str) -> str:
+    path = Path(value).expanduser()
+    if not path.is_absolute():
+        path = path.resolve()
+    if not path.exists() or not path.is_file():
+        raise ValidationError(f"private key does not exist: {path}")
+    return str(path)
+
+
+def validate_proxy_jumps(alias: str, jumps: Iterable[str]) -> list[str]:
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for jump in jumps:
+        item = validate_alias(jump)
+        key = item.casefold()
+        if key == alias.casefold():
+            raise ValidationError("a server cannot ProxyJump through itself")
+        if key not in seen:
+            normalized.append(item)
+            seen.add(key)
+    return normalized
+