@neoline/hostbridge 2.0.3 → 2.0.5

package/src/server_control_mcp/doctor.py

@@ -10,6 +10,7 @@ from typing import Protocol
 
 from . import __version__
 from .config import load_v1_config
+from .mux_protocol import MUX_PROTOCOL_VERSION
 from .runtime import runtime_paths
 
 
@@ -17,6 +18,9 @@ class DoctorClient(Protocol):
     def hello(self) -> dict[str, object]:
         raise NotImplementedError
 
+    def tunnel_health(self) -> dict[str, object]:
+        raise NotImplementedError
+
 
 @dataclass(frozen=True, slots=True)
 class DiagnosticResult:
@@ -46,6 +50,7 @@ def collect_diagnostics(
         _config_diagnostic(config_path),
         _runtime_diagnostic(),
         _daemon_diagnostic(client),
+        _tunnel_diagnostic(client),
         _executable_diagnostic(executable_paths),
     ]
     return DoctorReport(tuple(results))
@@ -60,8 +65,10 @@ def _version_diagnostic() -> DiagnosticResult:
         "npm": npm.get("version"),
         "python": pyproject.get("project", {}).get("version"),
     }
-    status = "pass" if len(set(versions.values())) == 1 and __version__ == "2.0.3" else "fail"
-    return DiagnosticResult("version", status, "version sources agree" if status == "pass" else "version drift detected", versions)
+    status = "pass" if len(set(versions.values())) == 1 else "fail"
+    return DiagnosticResult(
+        "version", status, "version sources agree" if status == "pass" else "version drift detected", versions
+    )
 
 
 def _config_diagnostic(config_path: Path | str) -> DiagnosticResult:
@@ -69,7 +76,9 @@ def _config_diagnostic(config_path: Path | str) -> DiagnosticResult:
         config = load_v1_config(config_path)
     except (OSError, ValueError) as exc:
         return DiagnosticResult("config", "fail", str(exc), {"path": str(config_path)})
-    return DiagnosticResult("config", "pass", "schema v1 configuration is valid", {"path": str(config.path), "hosts": len(config.hosts)})
+    return DiagnosticResult(
+        "config", "pass", "schema v1 configuration is valid", {"path": str(config.path), "hosts": len(config.hosts)}
+    )
 
 
 def _runtime_diagnostic() -> DiagnosticResult:
@@ -93,15 +102,42 @@ def _daemon_diagnostic(client: DoctorClient) -> DiagnosticResult:
         hello = client.hello()
     except Exception as exc:
         return DiagnosticResult("daemon", "fail", f"daemon unavailable: {exc}", {})
-    valid = hello.get("service") == "hostbridge" and hello.get("protocol") == 1
+    valid = (
+        hello.get("service") == "hostbridge"
+        and hello.get("protocol") == MUX_PROTOCOL_VERSION
+        and hello.get("version") == __version__
+    )
     return DiagnosticResult(
         "daemon",
         "pass" if valid else "fail",
-        "daemon protocol v1 is healthy" if valid else "daemon returned an incompatible handshake",
+        f"daemon protocol v{MUX_PROTOCOL_VERSION} is healthy" if valid else "daemon returned an incompatible handshake",
         dict(hello),
     )
 
 
+def _tunnel_diagnostic(client: DoctorClient) -> DiagnosticResult:
+    try:
+        result = client.tunnel_health()
+    except Exception as exc:
+        return DiagnosticResult("tunnel", "fail", f"tunnel diagnostics unavailable: {exc}", {})
+    hosts = result.get("hosts")
+    if not isinstance(hosts, list) or any(not isinstance(host, dict) for host in hosts):
+        return DiagnosticResult("tunnel", "fail", "daemon returned invalid tunnel diagnostics", dict(result))
+    enabled = [host for host in hosts if host.get("enabled") is True]
+    failed = [host for host in enabled if host.get("state") == "failed"]
+    inactive = [host for host in enabled if host.get("state") != "ready"]
+    if failed:
+        status = "fail"
+        message = f"{len(failed)} tunnel provider runtime(s) failed"
+    elif inactive:
+        status = "warn"
+        message = f"{len(inactive)} tunnel provider runtime(s) configured but not handshaken"
+    else:
+        status = "pass"
+        message = "tunnel provider runtimes are ready"
+    return DiagnosticResult("tunnel", status, message, dict(result))
+
+
 def _executable_diagnostic(paths: list[str]) -> DiagnosticResult:
     if not paths:
         return DiagnosticResult("executable", "fail", "hostbridge executable was not found", {"paths": []})

package/src/server_control_mcp/hosts.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
-import json
 import os
 import re
 from collections.abc import Iterable, Sequence
 from dataclasses import dataclass, field
+from ipaddress import ip_address, ip_network
 from pathlib import Path
 
+from .config import load_v1_config
 from .secrets import decrypt_secret
 
 DEFAULT_HOSTS_FILE = Path("~/.hostbridge/hosts.json").expanduser()
@@ -14,6 +15,17 @@ 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 HostLimits:
+    max_sessions: int = 16
+    command_timeout_seconds: int = 24 * 60 * 60
+    max_output_bytes: int = 1_000_000
+    max_stdin_bytes: int = 100 * 1024 * 1024
+    max_transfer_bytes: int = 100 * 1024 * 1024
+    max_text_bytes: int = 4 * 1024 * 1024
+    max_shell_bytes: int = 1024 * 1024
+
+
 @dataclass(frozen=True, slots=True)
 class LoginStep:
     expect: str
@@ -21,6 +33,27 @@ class LoginStep:
     send_secret: str | None = None
 
 
+@dataclass(frozen=True, slots=True)
+class SshHostConfig:
+    host: str
+    username: str | None = None
+    port: int = 22
+    identity_file: Path | None = None
+    proxy_jump: str | None = None
+    extra_args: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ForwardingPolicy:
+    enabled: bool = False
+    allow_cidrs: tuple[str, ...] = ()
+    allow_hostnames: tuple[str, ...] = ()
+    allow_ports: tuple[int, ...] = ()
+    max_streams: int = 128
+    idle_timeout_seconds: float = 300
+    stream_deadline_seconds: float = 24 * 60 * 60
+
+
 @dataclass(frozen=True, slots=True)
 class HostConfig:
     """A single approved connection target."""
@@ -35,11 +68,33 @@ class HostConfig:
     login_steps: list[LoginStep] = field(default_factory=list)
     ready_expect: str | None = None
     transport: str = "auto"
+    limits: HostLimits = field(default_factory=HostLimits)
+    ssh: SshHostConfig | None = None
+    forwarding: ForwardingPolicy = field(default_factory=ForwardingPolicy)
 
     @classmethod
-    def script(cls, host_id: str, label: str, script: Path | str, *, transport: str = "auto") -> HostConfig:
+    def script(
+        cls,
+        host_id: str,
+        label: str,
+        script: Path | str,
+        *,
+        transport: str = "auto",
+        limits: HostLimits | None = None,
+        forwarding: ForwardingPolicy | None = None,
+    ) -> HostConfig:
         path = Path(script).expanduser()
-        return cls(host_id, label, "/bin/sh", [str(path)], "script", path, transport=transport)
+        return cls(
+            host_id,
+            label,
+            "/bin/sh",
+            [str(path)],
+            "script",
+            path,
+            transport=transport,
+            limits=limits or HostLimits(),
+            forwarding=forwarding or ForwardingPolicy(),
+        )
 
     @classmethod
     def command_line(
@@ -54,6 +109,9 @@ class HostConfig:
         login_steps: list[LoginStep] | None = None,
         ready_expect: str | None = None,
         transport: str = "auto",
+        limits: HostLimits | None = None,
+        ssh: SshHostConfig | None = None,
+        forwarding: ForwardingPolicy | None = None,
     ) -> HostConfig:
         return cls(
             host_id,
@@ -66,6 +124,9 @@ class HostConfig:
             login_steps or [],
             ready_expect,
             transport,
+            limits or HostLimits(),
+            ssh,
+            forwarding or ForwardingPolicy(),
         )
 
     def describe(self) -> dict[str, object]:
@@ -76,6 +137,12 @@ class HostConfig:
             "command": self.command,
             "args": list(self.args),
             "transport": self.transport,
+            "forwarding": {
+                "enabled": self.forwarding.enabled,
+                "max_streams": self.forwarding.max_streams,
+                "idle_timeout_seconds": self.forwarding.idle_timeout_seconds,
+                "stream_deadline_seconds": self.forwarding.stream_deadline_seconds,
+            },
         }
         if self.script_path is not None:
             info.update(
@@ -96,25 +163,29 @@ 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()
+    path = configured_hosts_path(config_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")
+    raw_hosts = load_v1_config(path).hosts
 
-    hosts_by_id: dict[str, HostConfig] = {}
-    order: list[str] = []
+    hosts: list[HostConfig] = []
+    seen: set[str] = set()
     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
+        if host.id in seen:
+            raise ValueError(f"{path} contains duplicate host id {host.id!r}")
+        seen.add(host.id)
+        hosts.append(host)
 
-    return [hosts_by_id[host_id] for host_id in order]
+    return hosts
+
+
+def configured_hosts_path(config_path: Path | str | None = None) -> Path:
+    configured = (
+        config_path or os.environ.get("HOSTBRIDGE_HOSTS_FILE") or os.environ.get("SERVER_CONTROL_MCP_HOSTS_FILE")
+    )
+    return Path(configured).expanduser() if configured else _default_hosts_path()
 
 
 def _parse_host(item: object, path: Path, index: int) -> HostConfig:
@@ -137,12 +208,23 @@ def _parse_host(item: object, path: Path, index: int) -> HostConfig:
     transport = str(item.get("transport", "auto")).strip().lower()
     if transport not in {"auto", "pty", "ssh"}:
         raise ValueError(f"{path} hosts[{index}].transport must be one of: auto, pty, ssh")
+    if transport == "ssh" and "ssh" not in item:
+        raise ValueError(f"{path} hosts[{index}].transport ssh requires an ssh connection")
+    limits = _parse_limits(item.get("limits"), path, index)
+    forwarding = _parse_forwarding(item.get("forwarding"), 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, transport=transport)
+        host = HostConfig.script(
+            host_id,
+            label,
+            script,
+            transport=transport,
+            limits=limits,
+            forwarding=forwarding,
+        )
         return HostConfig(
             host.id,
             host.label,
@@ -154,19 +236,29 @@ def _parse_host(item: object, path: Path, index: int) -> HostConfig:
             login_steps,
             ready_expect,
             transport,
+            limits,
+            forwarding=forwarding,
         )
 
     if "ssh" in item:
+        ssh_config, ssh_args = _parse_ssh(item["ssh"], path, index)
+        if transport == "ssh" and ssh_config.extra_args:
+            raise ValueError(f"{path} hosts[{index}].ssh.extra_args cannot be used with native ssh transport")
+        if transport == "ssh" and login_steps:
+            raise ValueError(f"{path} hosts[{index}].login_steps cannot be used with native ssh transport")
         return HostConfig.command_line(
             host_id,
             label,
             "ssh",
-            _parse_ssh_args(item["ssh"], path, index),
+            ssh_args,
             connection_type="ssh",
             secrets=secrets,
             login_steps=login_steps,
             ready_expect=ready_expect,
             transport=transport,
+            limits=limits,
+            ssh=ssh_config,
+            forwarding=forwarding,
         )
 
     command = str(item.get("command", "")).strip()
@@ -184,9 +276,119 @@ def _parse_host(item: object, path: Path, index: int) -> HostConfig:
         login_steps=login_steps,
         ready_expect=ready_expect,
         transport=transport,
+        limits=limits,
+        forwarding=forwarding,
     )
 
 
+def _parse_forwarding(raw: object, path: Path, index: int) -> ForwardingPolicy:
+    if raw is None:
+        return ForwardingPolicy()
+    if not isinstance(raw, dict):
+        raise ValueError(f"{path} hosts[{index}].forwarding must be an object")
+    allowed_fields = {
+        "enabled",
+        "allow_cidrs",
+        "allow_hostnames",
+        "allow_ports",
+        "max_streams",
+        "idle_timeout_seconds",
+        "stream_deadline_seconds",
+    }
+    unknown = sorted(set(raw) - allowed_fields)
+    if unknown:
+        raise ValueError(f"{path} hosts[{index}].forwarding contains unknown field {unknown[0]!r}")
+
+    enabled = raw.get("enabled", False)
+    if not isinstance(enabled, bool):
+        raise ValueError(f"{path} hosts[{index}].forwarding.enabled must be a boolean")
+
+    raw_cidrs = raw.get("allow_cidrs", [])
+    if not isinstance(raw_cidrs, list) or not all(isinstance(value, str) for value in raw_cidrs):
+        raise ValueError(f"{path} hosts[{index}].forwarding.allow_cidrs must be a list of CIDR strings")
+    cidrs: list[str] = []
+    for value in raw_cidrs:
+        try:
+            network = ip_network(value, strict=True)
+        except ValueError as exc:
+            raise ValueError(f"{path} hosts[{index}].forwarding contains invalid CIDR {value!r}") from exc
+        cidrs.append(str(network))
+
+    raw_hostnames = raw.get("allow_hostnames", [])
+    if not isinstance(raw_hostnames, list) or not all(isinstance(value, str) for value in raw_hostnames):
+        raise ValueError(f"{path} hosts[{index}].forwarding.allow_hostnames must be a list of hostnames")
+    hostnames: list[str] = []
+    for value in raw_hostnames:
+        hostname = value.strip().rstrip(".").lower()
+        if not _valid_exact_hostname(hostname):
+            raise ValueError(f"{path} hosts[{index}].forwarding contains invalid hostname {value!r}")
+        hostnames.append(hostname)
+
+    raw_ports = raw.get("allow_ports", [])
+    if not isinstance(raw_ports, list) or any(
+        not isinstance(port, int) or isinstance(port, bool) or not 1 <= port <= 65535 for port in raw_ports
+    ):
+        raise ValueError(f"{path} hosts[{index}].forwarding.allow_ports must contain valid TCP ports")
+
+    max_streams = raw.get("max_streams", 128)
+    if not isinstance(max_streams, int) or isinstance(max_streams, bool) or not 1 <= max_streams <= 4096:
+        raise ValueError(f"{path} hosts[{index}].forwarding.max_streams must be between 1 and 4096")
+    idle_timeout = raw.get("idle_timeout_seconds", 300)
+    if not isinstance(idle_timeout, (int, float)) or isinstance(idle_timeout, bool) or not 0 < idle_timeout <= 86400:
+        raise ValueError(f"{path} hosts[{index}].forwarding.idle_timeout_seconds must be between 0 and 86400")
+    stream_deadline = raw.get("stream_deadline_seconds", 24 * 60 * 60)
+    if (
+        not isinstance(stream_deadline, (int, float))
+        or isinstance(stream_deadline, bool)
+        or not 0 < stream_deadline <= 7 * 24 * 60 * 60
+    ):
+        raise ValueError(f"{path} hosts[{index}].forwarding.stream_deadline_seconds must be between 0 and 604800")
+
+    return ForwardingPolicy(
+        enabled=enabled,
+        allow_cidrs=tuple(dict.fromkeys(cidrs)),
+        allow_hostnames=tuple(dict.fromkeys(hostnames)),
+        allow_ports=tuple(dict.fromkeys(raw_ports)),
+        max_streams=max_streams,
+        idle_timeout_seconds=float(idle_timeout),
+        stream_deadline_seconds=float(stream_deadline),
+    )
+
+
+def _valid_exact_hostname(hostname: str) -> bool:
+    if not hostname or len(hostname) > 253 or "*" in hostname or "\x00" in hostname:
+        return False
+    try:
+        ip_address(hostname)
+    except ValueError:
+        pass
+    else:
+        return False
+    labels = hostname.split(".")
+    return all(
+        1 <= len(label) <= 63
+        and label[0].isalnum()
+        and label[-1].isalnum()
+        and all(character.isalnum() or character == "-" for character in label)
+        for label in labels
+    )
+
+
+def _parse_limits(raw_limits: object, path: Path, index: int) -> HostLimits:
+    if raw_limits is None:
+        return HostLimits()
+    if not isinstance(raw_limits, dict):
+        raise ValueError(f"{path} hosts[{index}].limits must be an object")
+    values = {field: getattr(HostLimits(), field) for field in HostLimits.__dataclass_fields__}
+    for name, value in raw_limits.items():
+        if name not in values:
+            raise ValueError(f"{path} hosts[{index}].limits contains unknown limit {name!r}")
+        if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+            raise ValueError(f"{path} hosts[{index}].limits.{name} must be a positive integer")
+        values[name] = value
+    return HostLimits(**values)
+
+
 def _parse_ready_expect(raw_ready_expect: object, path: Path, index: int) -> str | None:
     if raw_ready_expect in (None, ""):
         return None
@@ -218,20 +420,36 @@ def _parse_login_steps(raw_steps: object, path: Path, index: int) -> list[LoginS
         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)))
+            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]:
+def _parse_ssh(raw_ssh: object, path: Path, index: int) -> tuple[SshHostConfig, 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")
 
+    username: str | None = None
+    host = target
+    if "@" in target:
+        username, host = target.rsplit("@", 1)
+        if not username or not host:
+            raise ValueError(f"{path} hosts[{index}].ssh.host must be [username@]hostname")
+
     args: list[str] = []
     port = raw_ssh.get("port")
+    parsed_port = 22
     if port not in (None, ""):
         if isinstance(port, bool) or not isinstance(port, int | str):
             raise ValueError(f"{path} hosts[{index}].ssh.port must be an integer")
@@ -243,8 +461,9 @@ def _parse_ssh_args(raw_ssh: object, path: Path, index: int) -> list[str]:
             raise ValueError(f"{path} hosts[{index}].ssh.port must be between 1 and 65535")
         args.extend(["-p", str(parsed_port)])
     identity_file = str(raw_ssh.get("identity_file", "")).strip()
+    identity_path = Path(identity_file).expanduser() if identity_file else None
     if identity_file:
-        args.extend(["-i", str(Path(identity_file).expanduser())])
+        args.extend(["-i", str(identity_path)])
     proxy_jump = str(raw_ssh.get("proxy_jump", "")).strip()
     if proxy_jump:
         args.extend(["-J", proxy_jump])
@@ -253,7 +472,17 @@ def _parse_ssh_args(raw_ssh: object, path: Path, index: int) -> list[str]:
         raise ValueError(f"{path} hosts[{index}].ssh.extra_args must be a list of strings")
     args.extend(extra_args)
     args.append(target)
-    return args
+    return (
+        SshHostConfig(
+            host=host,
+            username=username,
+            port=parsed_port,
+            identity_file=identity_path,
+            proxy_jump=proxy_jump or None,
+            extra_args=tuple(extra_args),
+        ),
+        args,
+    )
 
 
 class HostRegistry:
@@ -272,8 +501,7 @@ class HostRegistry:
         except KeyError as exc:
             if not self._hosts:
                 raise KeyError(
-                    "no hosts are configured; create ~/.hostbridge/hosts.json "
-                    "or set HOSTBRIDGE_HOSTS_FILE"
+                    "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