@neoline/hostbridge 0.2.0

package/src/server_control_mcp/secrets.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+from cryptography.fernet import Fernet, InvalidToken
+
+DEFAULT_KEY_FILE = Path("~/.hostbridge/key").expanduser()
+LEGACY_KEY_FILE = Path("~/.server_control_mcp/key").expanduser()
+SCHEME = "fernet.v1"
+
+
+def key_file_path() -> Path:
+    configured = os.environ.get("HOSTBRIDGE_KEY_FILE") or os.environ.get("SERVER_CONTROL_MCP_KEY_FILE")
+    if configured:
+        return Path(configured).expanduser()
+    if DEFAULT_KEY_FILE.exists() or not LEGACY_KEY_FILE.exists():
+        return DEFAULT_KEY_FILE
+    return LEGACY_KEY_FILE
+
+
+def _load_or_create_key() -> bytes:
+    path = key_file_path()
+    if path.exists():
+        return path.read_bytes().strip()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    key = Fernet.generate_key()
+    path.write_bytes(key + b"\n")
+    with suppress(OSError):
+        path.chmod(0o600)
+    return key
+
+
+def encrypt_secret(value: str) -> dict[str, str]:
+    if not isinstance(value, str) or value == "":
+        raise ValueError("secret value must not be empty")
+    token = Fernet(_load_or_create_key()).encrypt(value.encode("utf-8")).decode("ascii")
+    return {"scheme": SCHEME, "ciphertext": token}
+
+
+def decrypt_secret(payload: Any) -> str:
+    if not isinstance(payload, dict):
+        raise ValueError("encrypted secret must be an object")
+    if payload.get("scheme") != SCHEME:
+        raise ValueError(f"unsupported secret scheme: {payload.get('scheme')}")
+    ciphertext = payload.get("ciphertext")
+    if not isinstance(ciphertext, str) or not ciphertext:
+        raise ValueError("encrypted secret ciphertext must not be empty")
+    try:
+        return Fernet(_load_or_create_key()).decrypt(ciphertext.encode("ascii")).decode("utf-8")
+    except InvalidToken as exc:
+        raise ValueError("failed to decrypt secret with the configured key") from exc

package/src/server_control_mcp/server.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import asdict
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from . import cli
+from .hosts import HostRegistry, load_hosts
+from .manager import (
+    DEFAULT_COMMAND_TIMEOUT,
+    DEFAULT_CONNECT_TIMEOUT,
+    PolicyDeniedError,
+    RemoteCommandError,
+    SessionManager,
+)
+from .policy import build_audit_sink, load_policy
+
+mcp = FastMCP("hostbridge")
+_registry = HostRegistry(load_hosts())
+_policy = load_policy()
+_audit = build_audit_sink(_policy)
+_manager = SessionManager(_registry, policy=_policy, audit_sink=_audit)
+_manager.start_idle_reaper()
+
+
+_ERROR_CODES = {
+    PolicyDeniedError: "denied",
+    RemoteCommandError: "remote_error",
+}
+
+
+def _error_code(exc: Exception) -> str:
+    for exc_type, code in _ERROR_CODES.items():
+        if isinstance(exc, exc_type):
+            return code
+    if "unknown host" in str(exc).lower() or "unknown session" in str(exc).lower() or "unknown task" in str(exc).lower():
+        return "not_found"
+    return "internal"
+
+
+def _reload_hosts() -> HostRegistry:
+    """Reload host allowlist without dropping existing remote sessions."""
+
+    global _registry
+    _registry = HostRegistry(load_hosts())
+    _manager.hosts = _registry
+    return _registry
+
+
+def _error(exc: Exception) -> dict[str, object]:
+    return {"ok": False, "error": str(exc), "error_code": _error_code(exc)}
+
+
+def _ok(**payload: object) -> dict[str, object]:
+    return {"ok": True, **payload}
+
+
+@mcp.tool()
+def hosts_list() -> dict[str, object]:
+    """List approved connection targets and local metadata when available.
+
+    Returns an object with ``hosts``: an array of host descriptors. Safe to call
+    repeatedly; it triggers a config reload from hosts.json.
+    """
+    try:
+        registry = _reload_hosts()
+        return _ok(hosts=registry.describe())
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def hosts_reload() -> dict[str, object]:
+    """Reload approved connection targets from hosts.json without restarting.
+
+    Returns the same shape as ``hosts_list``. Use this when you know the config
+    file changed and want a fresh descriptor immediately.
+    """
+    try:
+        registry = _reload_hosts()
+        return _ok(hosts=registry.describe())
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def session_open(host_id: str, connect_timeout: int = DEFAULT_CONNECT_TIMEOUT) -> dict[str, object]:
+    """Open a persistent interactive shell for one approved host.
+
+    Args:
+        host_id: identifier of a host in hosts.json.
+        connect_timeout: seconds to wait for the shell to become ready (5-180).
+
+    Returns the opened session descriptor. Keep the ``session_id`` for later calls.
+    """
+    try:
+        _reload_hosts()
+        timeout = max(5, min(int(connect_timeout), 180))
+        session = _manager.open_session(host_id, connect_timeout=timeout)
+        sessions = [item for item in _manager.list_sessions() if item["session_id"] == session.id]
+        return _ok(session=sessions[0])
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def sessions_list() -> dict[str, object]:
+    """List currently open sessions held by this MCP process."""
+    return _ok(sessions=_manager.list_sessions())
+
+
+@mcp.tool()
+def session_close(session_id: str) -> dict[str, object]:
+    """Close one persistent session and free its PTY.
+
+    Args:
+        session_id: value returned by ``session_open``.
+    """
+    try:
+        return _ok(**_manager.close_session(session_id))
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def sessions_close_all() -> dict[str, object]:
+    """Close every live session. Use during graceful shutdown or reset.
+
+    Returns ``{"closed": [...session_ids], "count": N}``.
+    """
+    try:
+        return _ok(**_manager.close_all_sessions())
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def command_run(session_id: str, command: str, timeout: int = DEFAULT_COMMAND_TIMEOUT) -> dict[str, object]:
+    """Run a foreground command on an open session and wait for completion or timeout.
+
+    Args:
+        session_id: an open session from ``session_open``.
+        command: the shell command string to execute.
+        timeout: max seconds to wait (1 - 86400). On timeout the result has ``timed_out=true``.
+
+    The command is checked against the configured denylist before execution;
+    a blocked command returns ``error_code="denied"``.
+    """
+    try:
+        safe_timeout = max(1, min(int(timeout), 24 * 60 * 60))
+        result = _manager.run_command(session_id, command, timeout=safe_timeout)
+        return _ok(result=asdict(result))
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def task_start(session_id: str, command: str) -> dict[str, object]:
+    """Start a long-running background task on the remote host.
+
+    Args:
+        session_id: an open session.
+        command: the shell command to run detached on the remote host.
+
+    Returns a task descriptor with ``task_id`` for polling via ``task_status``.
+    The command is checked against the configured denylist before execution.
+    """
+    try:
+        task = _manager.start_task(session_id, command)
+        return _ok(task=asdict(task))
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def task_status(session_id: str, task_id: str, tail_lines: int = 80) -> dict[str, object]:
+    """Poll a background task: state, exit code, and recent log tail.
+
+    Args:
+        session_id: the session that owns the task.
+        task_id: value returned by ``task_start``.
+        tail_lines: number of trailing log lines to return (1 - 500).
+    """
+    try:
+        return _ok(status=_manager.task_status(session_id, task_id, tail_lines=tail_lines))
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def task_stop(session_id: str, task_id: str) -> dict[str, object]:
+    """Best-effort terminate a background task by sending SIGTERM to its remote PID.
+
+    Args:
+        session_id: the session that owns the task.
+        task_id: value returned by ``task_start``.
+
+    Returns ``{"task_id": ..., "stopped": bool, "outcome": "killed|already|noop"}``.
+    """
+    try:
+        return _ok(**_manager.stop_task(session_id, task_id))
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def session_write(session_id: str, text: str) -> dict[str, object]:
+    """Send one raw line to a session for rare interactive operations; prefer command_run otherwise.
+
+    Args:
+        session_id: an open session.
+        text: the literal line to send. Must not be empty.
+    """
+    try:
+        if not text.strip():
+            raise RemoteCommandError("text must not be empty")
+        return _ok(**_manager.write(session_id, text))
+    except Exception as exc:
+        return _error(exc)
+
+
+@mcp.tool()
+def session_read(session_id: str, timeout: float = 1.0, max_chars: int = 20000) -> dict[str, object]:
+    """Read currently available raw output from a session after session_write or interactive commands.
+
+    Args:
+        session_id: an open session.
+        timeout: max seconds to block waiting for output (0.0 - 10.0).
+        max_chars: cap on returned characters (1 - 120000).
+    """
+    try:
+        safe_timeout = max(0.0, min(float(timeout), 10.0))
+        safe_max = max(1, min(int(max_chars), 120000))
+        return _ok(**_manager.read(session_id, timeout=safe_timeout, max_chars=safe_max))
+    except Exception as exc:
+        return _error(exc)
+
+
+def main(argv: list[str] | None = None) -> Any:
+    args = sys.argv[1:] if argv is None else argv
+    if args and (args[0] in cli.SETUP_COMMANDS or args[0] in {"-h", "--help"}):
+        return cli.main(args)
+    return mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()