sshand 0.1.0__py3-none-any.whl

host_config.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+host_config.py — SSH host inventory management.
+
+Reads and writes a YAML file (hosts.yaml by default) that stores named SSH
+targets with their connection and authentication details.  Three auth types
+are supported:
+  - key      : private-key file on disk
+  - password : plaintext password (stored in the YAML – handle with care)
+  - agent    : delegate to the running ssh-agent process
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Literal, Optional
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# ---------------------------------------------------------------------------
+# Default location for the hosts inventory file
+# ---------------------------------------------------------------------------
+
+_DEFAULT_HOSTS_FILE = Path(
+    os.environ.get("SSH_MCP_HOSTS_FILE", str(Path(__file__).parent / "hosts.yaml"))
+)
+
+
+# ---------------------------------------------------------------------------
+# Pydantic models
+# ---------------------------------------------------------------------------
+
+
+class KeyAuth(BaseModel):
+    """Authentication via a private-key file."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    type: Literal["key"] = "key"
+    key_path: str = Field(
+        ...,
+        description=(
+            "Absolute or ~-relative path to the private key file "
+            "(e.g., '~/.ssh/id_rsa', '/home/user/.ssh/deploy_key')."
+        ),
+    )
+    passphrase: Optional[str] = Field(
+        default=None,
+        description="Optional passphrase to decrypt the private key.",
+    )
+
+    @field_validator("key_path")
+    @classmethod
+    def expand_path(cls, v: str) -> str:
+        return str(Path(v).expanduser())
+
+
+class PasswordAuth(BaseModel):
+    """Authentication via username + password."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    type: Literal["password"] = "password"
+    password: str = Field(..., description="SSH password for the user.")
+
+
+class AgentAuth(BaseModel):
+    """Authentication via the local ssh-agent."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["agent"] = "agent"
+
+
+AuthConfig = KeyAuth | PasswordAuth | AgentAuth
+
+
+class HostEntry(BaseModel):
+    """A single SSH host in the inventory."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    hostname: str = Field(
+        ...,
+        description="IP address or fully-qualified domain name of the host.",
+    )
+    port: int = Field(default=22, ge=1, le=65535, description="SSH port (default 22).")
+    username: str = Field(
+        ...,
+        description="SSH username (e.g., 'ubuntu', 'ec2-user', 'root').",
+    )
+    auth: AuthConfig = Field(
+        ...,
+        description="Authentication config.  Use type='key', 'password', or 'agent'.",
+    )
+    description: Optional[str] = Field(
+        default=None, description="Human-readable note about this host."
+    )
+
+    @field_validator("hostname")
+    @classmethod
+    def hostname_not_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("hostname must not be empty")
+        return v
+
+
+# ---------------------------------------------------------------------------
+# Inventory helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_raw(hosts_file: Path) -> Dict[str, Any]:
+    """Return the raw YAML dict, creating an empty one if the file is absent."""
+    if not hosts_file.exists():
+        return {"hosts": {}}
+    with hosts_file.open("r", encoding="utf-8") as fh:
+        data = yaml.safe_load(fh) or {}
+    if "hosts" not in data:
+        data["hosts"] = {}
+    return data
+
+
+def _save_raw(data: Dict[str, Any], hosts_file: Path) -> None:
+    hosts_file.parent.mkdir(parents=True, exist_ok=True)
+    with hosts_file.open("w", encoding="utf-8") as fh:
+        yaml.dump(data, fh, default_flow_style=False, allow_unicode=True, sort_keys=True)
+
+
+def list_hosts(hosts_file: Path = _DEFAULT_HOSTS_FILE) -> Dict[str, HostEntry]:
+    """
+    Return all hosts from the inventory as a dict of {alias: HostEntry}.
+
+    Returns an empty dict if the inventory file does not exist yet.
+    """
+    data = _load_raw(hosts_file)
+    result: Dict[str, HostEntry] = {}
+    for alias, raw in data["hosts"].items():
+        try:
+            result[alias] = HostEntry.model_validate(raw)
+        except Exception as exc:
+            # Skip malformed entries but don't crash
+            result[alias] = exc  # type: ignore[assignment]
+    return result
+
+
+def get_host(alias: str, hosts_file: Path = _DEFAULT_HOSTS_FILE) -> HostEntry:
+    """
+    Retrieve a single host by alias.
+
+    Raises KeyError if not found, ValueError if the entry is malformed.
+    """
+    data = _load_raw(hosts_file)
+    if alias not in data["hosts"]:
+        raise KeyError(f"Host '{alias}' not found in inventory.")
+    return HostEntry.model_validate(data["hosts"][alias])
+
+
+def add_host(
+    alias: str,
+    entry: HostEntry,
+    overwrite: bool = False,
+    hosts_file: Path = _DEFAULT_HOSTS_FILE,
+) -> None:
+    """
+    Add (or replace) a host in the inventory.
+
+    Raises ValueError if the alias already exists and overwrite=False.
+    """
+    data = _load_raw(hosts_file)
+    if alias in data["hosts"] and not overwrite:
+        raise ValueError(
+            f"Host '{alias}' already exists.  Pass overwrite=True to replace it."
+        )
+    data["hosts"][alias] = entry.model_dump()
+    _save_raw(data, hosts_file)
+
+
+def remove_host(alias: str, hosts_file: Path = _DEFAULT_HOSTS_FILE) -> None:
+    """
+    Remove a host from the inventory.
+
+    Raises KeyError if the alias does not exist.
+    """
+    data = _load_raw(hosts_file)
+    if alias not in data["hosts"]:
+        raise KeyError(f"Host '{alias}' not found in inventory.")
+    del data["hosts"][alias]
+    _save_raw(data, hosts_file)

platform_utils.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+platform_utils.py -- Windows-specific SSH agent helpers.
+
+On macOS/Linux the ssh-agent is managed by the OS or the user's shell
+profile and just works.  On Windows it is an optional service that ships
+with the built-in OpenSSH client but is disabled by default.
+
+This module lets setup_wizard.py and ssh_client.py:
+  - Detect whether the current platform is Windows
+  - Check whether the OpenSSH Authentication Agent service is running
+  - Attempt to enable + start it (requires Administrator privileges)
+  - Surface clear, actionable instructions when it cannot be auto-fixed
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from enum import Enum, auto
+from typing import Tuple
+
+
+# ---------------------------------------------------------------------------
+# Platform detection
+# ---------------------------------------------------------------------------
+
+IS_WINDOWS: bool = sys.platform == "win32"
+
+
+# ---------------------------------------------------------------------------
+# Service status
+# ---------------------------------------------------------------------------
+
+class AgentStatus(Enum):
+    NOT_WINDOWS   = auto()   # macOS / Linux -- no check needed
+    RUNNING       = auto()   # service is active and ready
+    STOPPED       = auto()   # service exists but is not running
+    DISABLED      = auto()   # service start type is set to Disabled
+    NOT_INSTALLED = auto()   # OpenSSH not installed at all
+    UNKNOWN       = auto()   # could not determine (non-admin, etc.)
+
+
+# PowerShell snippet shown to users who need to fix the service manually
+WINDOWS_FIX_INSTRUCTIONS = """\
+  Run the following in PowerShell as Administrator:
+
+    Set-Service ssh-agent -StartupType Automatic
+    Start-Service ssh-agent
+    ssh-add               # optionally load your key into the agent
+
+  To open an elevated PowerShell:
+    Press Win+X  ->  "Windows PowerShell (Admin)"  or  "Terminal (Admin)"
+"""
+
+
+def get_agent_status() -> AgentStatus:
+    """
+    Query the Windows OpenSSH Authentication Agent service state.
+
+    Returns AgentStatus.NOT_WINDOWS on non-Windows platforms so callers
+    can use this unconditionally without a platform guard.
+    """
+    if not IS_WINDOWS:
+        return AgentStatus.NOT_WINDOWS
+
+    try:
+        result = subprocess.run(
+            ["sc", "query", "ssh-agent"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        output = result.stdout.upper()
+
+        if result.returncode != 0:
+            # Service not found
+            if "DOES NOT EXIST" in output or "1060" in result.stdout:
+                return AgentStatus.NOT_INSTALLED
+            return AgentStatus.UNKNOWN
+
+        if "RUNNING" in output:
+            return AgentStatus.RUNNING
+
+        # Check start type for DISABLED
+        config_result = subprocess.run(
+            ["sc", "qc", "ssh-agent"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if "DISABLED" in config_result.stdout.upper():
+            return AgentStatus.DISABLED
+
+        return AgentStatus.STOPPED
+
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return AgentStatus.UNKNOWN
+
+
+def is_windows_admin() -> bool:
+    """Return True if the current process has Administrator privileges on Windows."""
+    if not IS_WINDOWS:
+        return False
+    try:
+        import ctypes
+        return bool(ctypes.windll.shell32.IsUserAnAdmin())
+    except Exception:
+        return False
+
+
+def start_agent_service() -> Tuple[bool, str]:
+    """
+    Attempt to set the ssh-agent service to Automatic and start it.
+
+    Must be called with Administrator privileges.  Returns (success, message).
+    """
+    if not IS_WINDOWS:
+        return False, "Not running on Windows."
+
+    try:
+        subprocess.run(
+            ["sc", "config", "ssh-agent", "start=auto"],
+            check=True, capture_output=True, timeout=10,
+        )
+        subprocess.run(
+            ["net", "start", "ssh-agent"],
+            check=True, capture_output=True, timeout=10,
+        )
+        # Verify it actually started
+        if get_agent_status() == AgentStatus.RUNNING:
+            return True, "OpenSSH Authentication Agent service started successfully."
+        return False, "Service start command ran but the service is not RUNNING."
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.decode(errors="replace") if exc.stderr else ""
+        return False, f"sc/net command failed: {stderr.strip() or exc}"
+    except Exception as exc:
+        return False, f"Unexpected error: {exc}"
+
+
+def agent_status_message(status: AgentStatus) -> str:
+    """
+    Return a human-readable, actionable description of the given AgentStatus.
+    Suitable for printing in the wizard or as an MCP error message.
+    """
+    if status == AgentStatus.NOT_WINDOWS:
+        return ""   # nothing to report on mac/linux
+
+    if status == AgentStatus.RUNNING:
+        return "OpenSSH Authentication Agent is running. Agent auth will work."
+
+    if status == AgentStatus.STOPPED:
+        return (
+            "OpenSSH Authentication Agent service exists but is not running.\n"
+            + WINDOWS_FIX_INSTRUCTIONS
+        )
+
+    if status == AgentStatus.DISABLED:
+        return (
+            "OpenSSH Authentication Agent service is disabled.\n"
+            + WINDOWS_FIX_INSTRUCTIONS
+        )
+
+    if status == AgentStatus.NOT_INSTALLED:
+        return (
+            "OpenSSH does not appear to be installed on this Windows machine.\n\n"
+            "  Install it via Settings -> Apps -> Optional Features -> OpenSSH Client\n"
+            "  or in PowerShell (Admin):\n\n"
+            "    Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0\n\n"
+            "  Then run:\n"
+            "    Set-Service ssh-agent -StartupType Automatic\n"
+            "    Start-Service ssh-agent\n"
+        )
+
+    # UNKNOWN
+    return (
+        "Could not determine the state of the OpenSSH Authentication Agent service.\n"
+        + WINDOWS_FIX_INSTRUCTIONS
+    )