@neoline/hostbridge 0.2.0

package/src/server_control_mcp/hosts.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .secrets import decrypt_secret
+
+DEFAULT_HOSTS_FILE = Path("~/.hostbridge/hosts.json").expanduser()
+LEGACY_HOSTS_FILE = Path("~/.server_control_mcp/hosts.json").expanduser()
+HOST_ID_PATTERN = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+
+@dataclass(frozen=True, slots=True)
+class LoginStep:
+    expect: str
+    send: str | None = None
+    send_secret: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HostConfig:
+    """A single approved connection target."""
+
+    id: str
+    label: str
+    command: str
+    args: list[str]
+    connection_type: str = "command"
+    script_path: Path | None = None
+    secrets: dict[str, str] = field(default_factory=dict)
+    login_steps: list[LoginStep] = field(default_factory=list)
+    ready_expect: str | None = None
+
+    @classmethod
+    def script(cls, host_id: str, label: str, script: Path | str) -> HostConfig:
+        path = Path(script).expanduser()
+        return cls(host_id, label, "/bin/sh", [str(path)], "script", path)
+
+    @classmethod
+    def command_line(
+        cls,
+        host_id: str,
+        label: str,
+        command: str,
+        args: Sequence[str] | None = None,
+        *,
+        connection_type: str = "command",
+        secrets: dict[str, str] | None = None,
+        login_steps: list[LoginStep] | None = None,
+        ready_expect: str | None = None,
+    ) -> HostConfig:
+        return cls(
+            host_id,
+            label,
+            command,
+            [str(arg) for arg in (args or ())],
+            connection_type,
+            None,
+            secrets or {},
+            login_steps or [],
+            ready_expect,
+        )
+
+    def describe(self) -> dict[str, object]:
+        info: dict[str, object] = {
+            "id": self.id,
+            "label": self.label,
+            "connection_type": self.connection_type,
+            "command": self.command,
+            "args": list(self.args),
+        }
+        if self.script_path is not None:
+            info.update(
+                {
+                    "script": str(self.script_path),
+                    "script_exists": self.script_path.exists(),
+                    "script_executable": self.script_path.exists() and self.script_path.stat().st_mode & 0o111 != 0,
+                    "script_runnable_via_sh": self.script_path.exists(),
+                }
+            )
+        return info
+
+
+# Kept as an empty compatibility constant so imports do not leak personal paths.
+DEFAULT_HOSTS: list[HostConfig] = []
+
+
+def load_hosts(config_path: Path | str | None = None) -> list[HostConfig]:
+    """Load approved hosts from JSON configuration."""
+
+    configured = config_path or os.environ.get("HOSTBRIDGE_HOSTS_FILE") or os.environ.get("SERVER_CONTROL_MCP_HOSTS_FILE")
+    path = Path(configured).expanduser() if configured else _default_hosts_path()
+    if not path.exists():
+        return []
+
+    data = json.loads(path.read_text(encoding="utf-8"))
+    raw_hosts = data.get("hosts") if isinstance(data, dict) else None
+    if not isinstance(raw_hosts, list):
+        raise ValueError(f"{path} must contain a top-level 'hosts' list")
+
+    hosts_by_id: dict[str, HostConfig] = {}
+    order: list[str] = []
+    for index, item in enumerate(raw_hosts):
+        host = _parse_host(item, path, index)
+        if host.id not in hosts_by_id:
+            order.append(host.id)
+        hosts_by_id[host.id] = host
+
+    return [hosts_by_id[host_id] for host_id in order]
+
+
+def _parse_host(item: object, path: Path, index: int) -> HostConfig:
+    if not isinstance(item, dict):
+        raise ValueError(f"{path} hosts[{index}] must be an object")
+    host_id = str(item.get("id", "")).strip()
+    label = str(item.get("label", host_id)).strip()
+    if not host_id or not HOST_ID_PATTERN.fullmatch(host_id):
+        raise ValueError(f"{path} hosts[{index}].id contains invalid characters")
+    if not label:
+        raise ValueError(f"{path} hosts[{index}].label must not be empty")
+
+    styles = [name for name in ("script", "ssh", "command") if name in item]
+    if len(styles) != 1:
+        raise ValueError(f"{path} hosts[{index}] must define exactly one of: script, ssh, command")
+
+    secrets = _parse_secrets(item.get("secrets", {}), path, index)
+    login_steps = _parse_login_steps(item.get("login_steps", []), path, index)
+    ready_expect = _parse_ready_expect(item.get("ready_expect"), path, index)
+
+    if "script" in item:
+        script = str(item.get("script", "")).strip()
+        if not script:
+            raise ValueError(f"{path} hosts[{index}].script must not be empty")
+        host = HostConfig.script(host_id, label, script)
+        return HostConfig(host.id, host.label, host.command, host.args, host.connection_type, host.script_path, secrets, login_steps, ready_expect)
+
+    if "ssh" in item:
+        return HostConfig.command_line(host_id, label, "ssh", _parse_ssh_args(item["ssh"], path, index), connection_type="ssh", secrets=secrets, login_steps=login_steps, ready_expect=ready_expect)
+
+    command = str(item.get("command", "")).strip()
+    args = item.get("args", [])
+    if not command:
+        raise ValueError(f"{path} hosts[{index}].command must not be empty")
+    if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args):
+        raise ValueError(f"{path} hosts[{index}].args must be a list of strings")
+    return HostConfig.command_line(host_id, label, command, args, secrets=secrets, login_steps=login_steps, ready_expect=ready_expect)
+
+
+def _parse_ready_expect(raw_ready_expect: object, path: Path, index: int) -> str | None:
+    if raw_ready_expect in (None, ""):
+        return None
+    if not isinstance(raw_ready_expect, str):
+        raise ValueError(f"{path} hosts[{index}].ready_expect must be a string")
+    return raw_ready_expect
+
+
+def _parse_secrets(raw_secrets: object, path: Path, index: int) -> dict[str, str]:
+    if raw_secrets in (None, {}):
+        return {}
+    if not isinstance(raw_secrets, dict) or not all(isinstance(name, str) for name in raw_secrets):
+        raise ValueError(f"{path} hosts[{index}].secrets must be an object")
+    return {name: decrypt_secret(payload) for name, payload in raw_secrets.items()}
+
+
+def _parse_login_steps(raw_steps: object, path: Path, index: int) -> list[LoginStep]:
+    if raw_steps in (None, []):
+        return []
+    if not isinstance(raw_steps, list):
+        raise ValueError(f"{path} hosts[{index}].login_steps must be a list")
+    steps: list[LoginStep] = []
+    for step_index, raw_step in enumerate(raw_steps):
+        if not isinstance(raw_step, dict):
+            raise ValueError(f"{path} hosts[{index}].login_steps[{step_index}] must be an object")
+        expect = str(raw_step.get("expect", "")).strip()
+        send = raw_step.get("send")
+        send_secret = raw_step.get("send_secret")
+        if not expect:
+            raise ValueError(f"{path} hosts[{index}].login_steps[{step_index}].expect must not be empty")
+        if (send is None) == (send_secret is None):
+            raise ValueError(f"{path} hosts[{index}].login_steps[{step_index}] must define exactly one of send or send_secret")
+        steps.append(LoginStep(expect=expect, send=None if send is None else str(send), send_secret=None if send_secret is None else str(send_secret)))
+    return steps
+
+
+def _parse_ssh_args(raw_ssh: object, path: Path, index: int) -> list[str]:
+    if not isinstance(raw_ssh, dict):
+        raise ValueError(f"{path} hosts[{index}].ssh must be an object")
+    target = str(raw_ssh.get("host", "")).strip()
+    if not target:
+        raise ValueError(f"{path} hosts[{index}].ssh.host must not be empty")
+
+    args: list[str] = []
+    port = raw_ssh.get("port")
+    if port not in (None, ""):
+        args.extend(["-p", str(int(port))])
+    identity_file = str(raw_ssh.get("identity_file", "")).strip()
+    if identity_file:
+        args.extend(["-i", str(Path(identity_file).expanduser())])
+    proxy_jump = str(raw_ssh.get("proxy_jump", "")).strip()
+    if proxy_jump:
+        args.extend(["-J", proxy_jump])
+    extra_args = raw_ssh.get("extra_args", [])
+    if not isinstance(extra_args, list) or not all(isinstance(arg, str) for arg in extra_args):
+        raise ValueError(f"{path} hosts[{index}].ssh.extra_args must be a list of strings")
+    args.extend(extra_args)
+    args.append(target)
+    return args
+
+
+class HostRegistry:
+    """Allowlist of connection targets that the MCP server may spawn."""
+
+    def __init__(self, hosts: Iterable[HostConfig]):
+        self._hosts = {host.id: host for host in hosts}
+
+    @classmethod
+    def from_specs(cls, specs: Iterable[tuple[str, str, str, Sequence[str]]]) -> HostRegistry:
+        return cls(HostConfig.command_line(host_id, label, command, args) for host_id, label, command, args in specs)
+
+    def get(self, host_id: str) -> HostConfig:
+        try:
+            return self._hosts[host_id]
+        except KeyError as exc:
+            if not self._hosts:
+                raise KeyError(
+                    "no hosts are configured; create ~/.hostbridge/hosts.json "
+                    "or set HOSTBRIDGE_HOSTS_FILE"
+                ) from exc
+            valid = ", ".join(sorted(self._hosts))
+            raise KeyError(f"unknown host '{host_id}'; valid hosts: {valid}") from exc
+
+    def describe(self) -> list[dict[str, object]]:
+        return [host.describe() for host in self._hosts.values()]
+
+
+def _default_hosts_path() -> Path:
+    if DEFAULT_HOSTS_FILE.exists() or not LEGACY_HOSTS_FILE.exists():
+        return DEFAULT_HOSTS_FILE
+    return LEGACY_HOSTS_FILE