@neoline/hostbridge 0.2.0

package/src/server_control_mcp/manager.py

@@ -0,0 +1,512 @@
+from __future__ import annotations
+
+import re
+import shlex
+import threading
+import time
+import uuid
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import pexpect
+
+from .hosts import HostRegistry
+from .policy import AuditSink, PolicyConfig, PolicyDecision, audit_event
+
+DEFAULT_CONNECT_TIMEOUT = 30
+DEFAULT_COMMAND_TIMEOUT = 60
+DEFAULT_REAPER_INTERVAL_SECONDS = 60
+MAX_OUTPUT_CHARS = 120_000
+REMOTE_JOB_ROOT = "$HOME/.hostbridge/jobs"
+REMOTE_SHELL = "bash"
+
+class PolicyDeniedError(RuntimeError):
+    """Raised when a command is blocked by the configured policy."""
+
+
+class ChildProcess(Protocol):
+    before: str
+    after: object
+
+    def sendline(self, line: str) -> None: ...
+
+    def send(self, text: str) -> None: ...
+
+    def expect(self, patterns: object, timeout: int | float = -1) -> int: ...
+
+    def isalive(self) -> bool: ...
+
+    def close(self, force: bool = False) -> None: ...
+
+    def read_nonblocking(self, size: int = 1, timeout: int | float = -1) -> str: ...
+
+
+ChildFactory = Callable[[str, list[str], int | float], ChildProcess]
+TokenFactory = Callable[[], str]
+
+
+class RemoteCommandError(RuntimeError):
+    """Raised when a remote session cannot execute a requested operation."""
+
+
+@dataclass(slots=True)
+class RemoteSession:
+    id: str
+    host_id: str
+    label: str
+    command: str
+    args: list[str]
+    child: ChildProcess
+    created_at: float = field(default_factory=time.time)
+    last_used_at: float = field(default_factory=time.time)
+    busy: bool = False
+    last_output: str = ""
+
+
+@dataclass(slots=True)
+class CommandResult:
+    session_id: str
+    host_id: str
+    command: str
+    exit_code: int | None
+    output: str
+    timed_out: bool = False
+
+
+@dataclass(slots=True)
+class RemoteTask:
+    id: str
+    session_id: str
+    host_id: str
+    command: str
+    job_dir: str
+    remote_pid: int | None
+    created_at: float = field(default_factory=time.time)
+
+
+def _new_token() -> str:
+    return uuid.uuid4().hex[:12]
+
+
+def _default_child_factory(command: str, args: list[str], timeout: int | float) -> ChildProcess:
+    return pexpect.spawn(
+        command,
+        args,
+        encoding="utf-8",
+        codec_errors="replace",
+        timeout=timeout,
+        echo=False,
+    )
+
+
+def _tail(value: str, limit: int = MAX_OUTPUT_CHARS) -> str:
+    if len(value) <= limit:
+        return value
+    return value[-limit:]
+
+
+def _extract_between_markers(raw: str, start_marker: str) -> str:
+    if start_marker in raw:
+        raw = raw.split(start_marker, 1)[1]
+    lines = raw.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    cleaned = [line for line in lines if not line.startswith("printf '") and "__SCM_EXIT_" not in line]
+    return "\n".join(cleaned).strip("\n")
+
+
+def _parse_exit_marker(marker: object, token: str) -> int | None:
+    text = marker.group(0) if hasattr(marker, "group") else str(marker)
+    match = re.search(rf"__SCM_EXIT_{re.escape(token)}:(\d+)", text)
+    return int(match.group(1)) if match else None
+
+
+def _contains_terminal_control(text: str) -> bool:
+    return "\x1b" in text or "\x07" in text or "\\x1b" in text or "\\u001b" in text
+
+
+def _looks_shell_prompt(text: str) -> bool:
+    return re.search(r"[#$](?:\\s\*)?$", text.strip()) is not None
+
+
+def _runtime_expect_pattern(pattern: str) -> str:
+    if _contains_terminal_control(pattern) and _looks_shell_prompt(pattern):
+        return r"(?m)[^\r\n]*[#$]\s*$"
+    return pattern
+
+
+class SessionManager:
+    """Manages long-lived interactive PTYs and remote background jobs."""
+
+    def __init__(
+        self,
+        hosts: HostRegistry,
+        *,
+        child_factory: ChildFactory = _default_child_factory,
+        remote_shell: str = REMOTE_SHELL,
+        policy: PolicyConfig | None = None,
+        audit_sink: AuditSink | None = None,
+    ):
+        self.hosts = hosts
+        self.child_factory = child_factory
+        self.remote_shell = remote_shell
+        self._sessions: dict[str, RemoteSession] = {}
+        self._tasks: dict[str, RemoteTask] = {}
+        self._policy = policy
+        self._audit = audit_sink
+        self._reaper_stop = threading.Event()
+        self._reaper_thread: threading.Thread | None = None
+
+    @property
+    def policy(self) -> PolicyConfig | None:
+        return self._policy
+
+    def start_idle_reaper(self, *, interval: int = DEFAULT_REAPER_INTERVAL_SECONDS) -> None:
+        """Spawn a background thread that closes idle sessions past policy timeout."""
+
+        if self._policy is None or not self._policy.enabled or self._policy.idle_timeout_seconds <= 0:
+            return
+        if self._reaper_thread is not None and self._reaper_thread.is_alive():
+            return
+        self._reaper_stop.clear()
+        timeout = self._policy.idle_timeout_seconds
+        thread = threading.Thread(
+            target=self._reap_loop,
+            kwargs={"interval": interval, "timeout": timeout},
+            daemon=True,
+            name="scm-idle-reaper",
+        )
+        self._reaper_thread = thread
+        thread.start()
+
+    def stop_idle_reaper(self) -> None:
+        self._reaper_stop.set()
+        thread = self._reaper_thread
+        if thread is not None and thread.is_alive():
+            thread.join(timeout=2.0)
+        self._reaper_thread = None
+
+    def _reap_loop(self, *, interval: int, timeout: int) -> None:
+        while not self._reaper_stop.wait(interval):
+            self._reap_idle(timeout)
+
+    def _reap_idle(self, timeout: int) -> int:
+        now = time.time()
+        expired = [
+            sid for sid, session in list(self._sessions.items())
+            if not session.busy and (now - session.last_used_at) > timeout
+        ]
+        for sid in expired:
+            self._safe_close(sid)
+            self._emit("session_idle_closed", session_id=sid, detail=f"idle > {timeout}s")
+        return len(expired)
+
+    def _safe_close(self, session_id: str) -> None:
+        session = self._sessions.pop(session_id, None)
+        if session is not None:
+            with suppress(Exception):
+                session.child.close(force=True)
+
+    def _emit(self, event: str, **fields: object) -> None:
+        if self._audit is None:
+            return
+        audit_event(self._audit, event=event, **{k: v for k, v in fields.items() if v is not None})  # type: ignore[arg-type]
+
+    def _check_policy(self, command: str) -> PolicyDecision | None:
+        if self._policy is None:
+            return None
+        return self._policy.evaluate(command)
+
+    def open_session(
+        self,
+        host_id: str,
+        *,
+        connect_timeout: int = DEFAULT_CONNECT_TIMEOUT,
+        token_factory: TokenFactory = _new_token,
+    ) -> RemoteSession:
+        host = self.hosts.get(host_id)
+        child = self.child_factory(host.command, list(host.args), connect_timeout)
+        token = token_factory()
+        marker = f"__SCM_READY_{token}__"
+        try:
+            self._run_login_steps(child, host, connect_timeout)
+            if getattr(host, "login_steps", []):
+                self._wait_for_ready_prompt(child, host, connect_timeout)
+            child.send(f"printf '\\n{marker}\\n'\r")
+            child.expect(re.escape(marker), timeout=connect_timeout)
+        except Exception as exc:  # pexpect.TIMEOUT/EOF and fake child errors are surfaced uniformly.
+            try:
+                child.close(force=True)
+            finally:
+                raise RemoteCommandError(f"failed to establish ready shell for {host_id}: {exc}") from exc
+
+        session = RemoteSession(
+            id=uuid.uuid4().hex,
+            host_id=host.id,
+            label=host.label,
+            command=host.command,
+            args=list(host.args),
+            child=child,
+            last_output=_tail(str(child.before)),
+        )
+        self._sessions[session.id] = session
+        self._emit("session_opened", session_id=session.id, host_id=host.id, outcome="ok")
+        return session
+
+    def _run_login_steps(self, child: ChildProcess, host: object, timeout: int) -> None:
+        for step in getattr(host, "login_steps", []):
+            child.expect(_runtime_expect_pattern(step.expect), timeout=timeout)
+            if step.send_secret is not None:
+                secrets = getattr(host, "secrets", {})
+                if step.send_secret not in secrets:
+                    raise RemoteCommandError(f"login step references missing secret '{step.send_secret}'")
+                self._send_login_text(child, secrets[step.send_secret])
+            else:
+                self._send_login_text(child, step.send or "")
+
+    def _send_login_text(self, child: ChildProcess, text: str) -> None:
+        # JumpServer-style menus often require carriage return rather than LF.
+        child.send(f"{text}\r")
+
+    def _wait_for_ready_prompt(self, child: ChildProcess, host: object, timeout: int) -> None:
+        ready_expect = getattr(host, "ready_expect", None)
+        pattern = ready_expect if isinstance(ready_expect, str) and ready_expect.strip() else r"(?m)[^\r\n]*[#$]\s*$"
+        child.expect(_runtime_expect_pattern(pattern), timeout=timeout)
+
+    def list_sessions(self) -> list[dict[str, object]]:
+        return [self._describe_session(session) for session in self._sessions.values()]
+
+    def close_all_sessions(self) -> dict[str, object]:
+        """Close every live session. Used for graceful shutdown."""
+
+        closed: list[str] = []
+        for session_id in list(self._sessions.keys()):
+            self._safe_close(session_id)
+            self._emit("session_closed", session_id=session_id, outcome="shutdown")
+            closed.append(session_id)
+        return {"closed": closed, "count": len(closed)}
+
+    def close_session(self, session_id: str) -> dict[str, object]:
+        session = self._get_session(session_id)
+        session.child.close(force=True)
+        self._sessions.pop(session_id, None)
+        self._emit("session_closed", session_id=session_id, host_id=session.host_id, outcome="user")
+        return {"session_id": session_id, "closed": True}
+
+    def stop_task(self, session_id: str, task_id: str) -> dict[str, object]:
+        """Best-effort terminate a background task by killing its remote PID."""
+
+        task = self._tasks.get(task_id)
+        if task is None:
+            raise RemoteCommandError(f"unknown task {task_id}")
+        if task.session_id != session_id:
+            raise RemoteCommandError(f"task {task_id} does not belong to session {session_id}")
+        if task.remote_pid is None:
+            raise RemoteCommandError(f"task {task_id} has no recorded remote pid")
+        kill_script = f'if [ -f "{task.job_dir}/exit_code" ]; then echo already; else kill -TERM {task.remote_pid} 2>/dev/null && echo killed || echo noop; fi'
+        result = self.run_command(session_id, kill_script, timeout=10)
+        outcome = result.output.strip().splitlines()[-1] if result.output.strip() else "unknown"
+        self._emit(
+            "task_stopped",
+            session_id=session_id,
+            task_id=task_id,
+            host_id=task.host_id,
+            outcome=outcome,
+        )
+        return {"task_id": task_id, "stopped": outcome in ("killed", "already"), "outcome": outcome}
+
+    def run_command(
+        self,
+        session_id: str,
+        command: str,
+        *,
+        timeout: int = DEFAULT_COMMAND_TIMEOUT,
+        token_factory: TokenFactory = _new_token,
+    ) -> CommandResult:
+        if not command.strip():
+            raise RemoteCommandError("command must not be empty")
+        decision = self._check_policy(command)
+        if decision is not None and not decision.allowed:
+            self._emit(
+                "command_denied",
+                session_id=session_id,
+                command=command,
+                outcome=decision.reason,
+                detail=decision.matched_pattern,
+            )
+            raise PolicyDeniedError(decision.reason)
+        session = self._get_session(session_id)
+        if session.busy:
+            raise RemoteCommandError(f"session {session_id} is busy")
+        if not session.child.isalive():
+            raise RemoteCommandError(f"session {session_id} is not alive")
+
+        token = token_factory()
+        start_marker = f"__SCM_START_{token}__"
+        exit_pattern = re.compile(rf"__SCM_EXIT_{re.escape(token)}:(\d+)")
+        remote_line = self._build_remote_line(command, token, start_marker)
+        session.busy = True
+        try:
+            session.child.sendline(remote_line)
+            session.child.expect(exit_pattern, timeout=timeout)
+            output = _extract_between_markers(str(session.child.before), start_marker)
+            exit_code = _parse_exit_marker(session.child.after, token)
+            result = CommandResult(session.id, session.host_id, command, exit_code, _tail(output))
+            self._emit(
+                "command_run",
+                session_id=session.id,
+                host_id=session.host_id,
+                command=command,
+                outcome=f"exit={exit_code}",
+            )
+        except pexpect.TIMEOUT:
+            output = _tail(str(session.child.before))
+            result = CommandResult(session.id, session.host_id, command, None, output, timed_out=True)
+            self._emit(
+                "command_run",
+                session_id=session.id,
+                host_id=session.host_id,
+                command=command,
+                outcome="timeout",
+            )
+        finally:
+            session.busy = False
+            session.last_used_at = time.time()
+            session.last_output = _tail(str(session.child.before))
+        return result
+
+    def start_task(
+        self,
+        session_id: str,
+        command: str,
+        *,
+        token_factory: TokenFactory = _new_token,
+    ) -> RemoteTask:
+        if not command.strip():
+            raise RemoteCommandError("command must not be empty")
+        decision = self._check_policy(command)
+        if decision is not None and not decision.allowed:
+            self._emit(
+                "task_denied",
+                session_id=session_id,
+                command=command,
+                outcome=decision.reason,
+                detail=decision.matched_pattern,
+            )
+            raise PolicyDeniedError(decision.reason)
+        task_id = token_factory()
+        job_dir = f"{REMOTE_JOB_ROOT}/{task_id}"
+        quoted_command = shlex.quote(command)
+        script = (
+            f'job_dir="{job_dir}"; '
+            'mkdir -p "$job_dir"; '
+            'date -u +%Y-%m-%dT%H:%M:%SZ > "$job_dir/started_at"; '
+            f'({self.remote_shell} -lc {quoted_command} > "$job_dir/stdout.log" 2>&1; '
+            'status=$?; printf "%s\\n" "$status" > "$job_dir/exit_code"; '
+            'date -u +%Y-%m-%dT%H:%M:%SZ > "$job_dir/finished_at") & '
+            'pid=$!; printf "%s\\n" "$pid" > "$job_dir/pid"; printf "%s" "$pid"'
+        )
+        result = self.run_command(session_id, script, timeout=10, token_factory=lambda: f"task_{task_id}")
+        pid_match = re.search(r"(\d+)", result.output)
+        task = RemoteTask(
+            id=task_id,
+            session_id=session_id,
+            host_id=self._get_session(session_id).host_id,
+            command=command,
+            job_dir=job_dir,
+            remote_pid=int(pid_match.group(1)) if pid_match else None,
+        )
+        self._tasks[task.id] = task
+        self._emit("task_started", session_id=session_id, task_id=task.id, host_id=task.host_id, command=command, outcome="ok")
+        return task
+
+    def task_status(self, session_id: str, task_id: str, *, tail_lines: int = 80) -> dict[str, object]:
+        task = self._tasks.get(task_id)
+        if task is None:
+            raise RemoteCommandError(f"unknown task {task_id}")
+        if task.session_id != session_id:
+            raise RemoteCommandError(f"task {task_id} does not belong to session {session_id}")
+        safe_tail_lines = max(1, min(int(tail_lines), 500))
+        script = (
+            f'job_dir="{task.job_dir}"; '
+            'pid=$(cat "$job_dir/pid" 2>/dev/null || true); '
+            'if [ -f "$job_dir/exit_code" ]; then state=finished; exit_code=$(cat "$job_dir/exit_code"); '
+            'elif [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then state=running; exit_code=""; '
+            'else state=unknown; exit_code=""; fi; '
+            'printf "STATE=%s\\nPID=%s\\nEXIT=%s\\n---LOG---\\n" "$state" "$pid" "$exit_code"; '
+            f'tail -n {safe_tail_lines} "$job_dir/stdout.log" 2>/dev/null || true'
+        )
+        result = self.run_command(session_id, script, timeout=15)
+        metadata, _, log = result.output.partition("---LOG---\n")
+        fields: dict[str, str] = {}
+        for line in metadata.splitlines():
+            key, sep, value = line.partition("=")
+            if sep:
+                fields[key] = value
+        exit_text = fields.get("EXIT") or ""
+        return {
+            "task_id": task.id,
+            "session_id": session_id,
+            "host_id": task.host_id,
+            "command": task.command,
+            "job_dir": task.job_dir,
+            "state": fields.get("STATE", "unknown"),
+            "pid": fields.get("PID") or task.remote_pid,
+            "exit_code": int(exit_text) if exit_text.isdigit() else None,
+            "log_tail": log,
+        }
+
+    def write(self, session_id: str, text: str) -> dict[str, object]:
+        session = self._get_session(session_id)
+        session.child.sendline(text)
+        session.last_used_at = time.time()
+        return {"session_id": session_id, "written": True}
+
+    def read(self, session_id: str, *, timeout: float = 1.0, max_chars: int = 20_000) -> dict[str, object]:
+        session = self._get_session(session_id)
+        chunks: list[str] = []
+        deadline = time.time() + max(0.0, timeout)
+        while len("".join(chunks)) < max_chars:
+            remaining = max(0.0, deadline - time.time())
+            if remaining <= 0 and chunks:
+                break
+            try:
+                chunk = session.child.read_nonblocking(size=4096, timeout=remaining)
+            except (pexpect.TIMEOUT, pexpect.EOF):
+                break
+            if not chunk:
+                break
+            chunks.append(str(chunk))
+        output = _tail("".join(chunks), max_chars)
+        session.last_output = output or session.last_output
+        session.last_used_at = time.time()
+        return {"session_id": session_id, "output": output, "alive": session.child.isalive()}
+
+    def _get_session(self, session_id: str) -> RemoteSession:
+        try:
+            return self._sessions[session_id]
+        except KeyError as exc:
+            raise RemoteCommandError(f"unknown session {session_id}") from exc
+
+    def _build_remote_line(self, command: str, token: str, start_marker: str) -> str:
+        quoted_command = shlex.quote(command)
+        return (
+            f"printf '\\n{start_marker}\\n'; "
+            f"{self.remote_shell} -lc {quoted_command}; "
+            "__scm_status=$?; "
+            f"printf '\\n__SCM_EXIT_{token}:%s\\n' \"$__scm_status\""
+        )
+
+    @staticmethod
+    def _describe_session(session: RemoteSession) -> dict[str, object]:
+        return {
+            "session_id": session.id,
+            "host_id": session.host_id,
+            "label": session.label,
+            "command": session.command,
+            "args": session.args,
+            "alive": session.child.isalive(),
+            "busy": session.busy,
+            "created_at": session.created_at,
+            "last_used_at": session.last_used_at,
+        }

package/src/server_control_mcp/policy.py

@@ -0,0 +1,187 @@
+"""Lightweight policy layer for hostbridge.
+
+This module implements an optional, defense-in-depth policy that augments the
+existing allowlist model. It is not an authentication or authorization layer:
+any local process that can invoke the MCP server already runs as the same user
+and can bypass it (e.g. by setting ``HOSTBRIDGE_DISABLE_POLICY=1``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+DEFAULT_POLICY_FILE = Path("~/.hostbridge/policy.json").expanduser()
+LEGACY_POLICY_FILE = Path("~/.server_control_mcp/policy.json").expanduser()
+DEFAULT_AUDIT_LOG = Path("~/.hostbridge/audit.jsonl").expanduser()
+LEGACY_AUDIT_LOG = Path("~/.server_control_mcp/audit.jsonl").expanduser()
+DEFAULT_IDLE_TIMEOUT_SECONDS = 1800
+DEFAULT_REAPER_INTERVAL_SECONDS = 60
+
+DEFAULT_DENYLIST_PATTERNS = (
+    r"\brm\s+-rf\s+/(?:\s|$)",
+    r"\bmkfs\.\w+\b",
+    r"\bdd\s+.*\bof=/dev/(?:sd|nvme|hd)",
+    r":\(\)\s*\{\s*:\|:\s*&\s*\};",
+    r"\bshutdown\b",
+    r"\breboot\b",
+    r">\s*/dev/sda",
+)
+
+
+class AuditSink(Protocol):
+    def write(self, event: dict[str, Any]) -> None: ...
+
+
+class _NullAudit:
+    def write(self, event: dict[str, Any]) -> None:  # noqa: ARG002
+        pass
+
+
+class _JsonlAudit:
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._lock = threading.Lock()
+
+    def write(self, event: dict[str, Any]) -> None:
+        line = json.dumps(event, ensure_ascii=False, sort_keys=True) + "\n"
+        with self._lock:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            with self._path.open("a", encoding="utf-8") as handle:
+                handle.write(line)
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyDecision:
+    allowed: bool
+    reason: str = ""
+    matched_pattern: str | None = None
+
+
+@dataclass(slots=True)
+class PolicyConfig:
+    idle_timeout_seconds: int = DEFAULT_IDLE_TIMEOUT_SECONDS
+    command_denylist: tuple[re.Pattern[str], ...] = field(default_factory=tuple)
+    audit_log_path: Path | None = None
+    enabled: bool = True
+
+    @classmethod
+    def disabled(cls) -> PolicyConfig:
+        return cls(enabled=False, audit_log_path=None)
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any], *, env: dict[str, str] | None = None) -> PolicyConfig:
+        env = env if env is not None else dict(os.environ)
+        if (env.get("HOSTBRIDGE_DISABLE_POLICY", "") or env.get("SERVER_CONTROL_MCP_DISABLE_POLICY", "")).lower() in (
+            "1",
+            "true",
+            "yes",
+        ):
+            return cls.disabled()
+
+        raw = raw or {}
+        idle_timeout = int(
+            env.get(
+                "HOSTBRIDGE_IDLE_TIMEOUT",
+                env.get("SERVER_CONTROL_MCP_IDLE_TIMEOUT", raw.get("idle_timeout_seconds", DEFAULT_IDLE_TIMEOUT_SECONDS)),
+            )
+        )
+        idle_timeout = max(0, idle_timeout)
+
+        patterns: list[str] = []
+        if raw.get("command_denylist"):
+            patterns = [str(p) for p in raw["command_denylist"]]
+        elif raw.get("use_default_denylist", True):
+            patterns = list(DEFAULT_DENYLIST_PATTERNS)
+        env_extra = env.get("HOSTBRIDGE_DENYLIST") or env.get("SERVER_CONTROL_MCP_DENYLIST")
+        if env_extra:
+            patterns.extend(p for p in env_extra.split(os.pathsep) if p)
+
+        default_audit = DEFAULT_AUDIT_LOG if DEFAULT_AUDIT_LOG.exists() or not LEGACY_AUDIT_LOG.exists() else LEGACY_AUDIT_LOG
+        audit_path_str = env.get(
+            "HOSTBRIDGE_AUDIT_LOG",
+            env.get("SERVER_CONTROL_MCP_AUDIT_LOG", str(raw.get("audit_log_path") or default_audit)),
+        )
+        audit_path = Path(audit_path_str).expanduser() if audit_path_str else None
+
+        return cls(
+            idle_timeout_seconds=idle_timeout,
+            command_denylist=tuple(re.compile(pattern) for pattern in patterns),
+            audit_log_path=audit_path,
+            enabled=True,
+        )
+
+    def evaluate(self, command: str) -> PolicyDecision:
+        if not self.enabled:
+            return PolicyDecision(allowed=True, reason="policy disabled")
+        if not command.strip():
+            return PolicyDecision(allowed=False, reason="empty command")
+        for pattern in self.command_denylist:
+            if pattern.search(command):
+                return PolicyDecision(False, "command matched denylist", pattern.pattern)
+        return PolicyDecision(True)
+
+
+def load_policy(config_path: Path | str | None = None) -> PolicyConfig:
+    if (os.environ.get("HOSTBRIDGE_DISABLE_POLICY", "") or os.environ.get("SERVER_CONTROL_MCP_DISABLE_POLICY", "")).lower() in (
+        "1",
+        "true",
+        "yes",
+    ):
+        return PolicyConfig.disabled()
+
+    path = Path(
+        config_path
+        or os.environ.get("HOSTBRIDGE_POLICY_FILE")
+        or os.environ.get("SERVER_CONTROL_MCP_POLICY_FILE")
+        or (DEFAULT_POLICY_FILE if DEFAULT_POLICY_FILE.exists() or not LEGACY_POLICY_FILE.exists() else LEGACY_POLICY_FILE)
+    ).expanduser()
+
+    raw: dict[str, Any] = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                raw = data
+        except (OSError, json.JSONDecodeError):
+            raw = {}
+    return PolicyConfig.from_dict(raw)
+
+
+def build_audit_sink(policy: PolicyConfig) -> AuditSink:
+    if not policy.enabled or policy.audit_log_path is None:
+        return _NullAudit()
+    return _JsonlAudit(policy.audit_log_path)
+
+
+def audit_event(
+    sink: AuditSink,
+    *,
+    event: str,
+    session_id: str | None = None,
+    host_id: str | None = None,
+    command: str | None = None,
+    task_id: str | None = None,
+    outcome: str | None = None,
+    detail: str | None = None,
+    clock: Callable[[], float] = time.time,
+) -> None:
+    payload: dict[str, Any] = {"ts": clock(), "event": event}
+    for key, value in {
+        "session_id": session_id,
+        "host_id": host_id,
+        "command": command,
+        "task_id": task_id,
+        "outcome": outcome,
+        "detail": detail,
+    }.items():
+        if value is not None:
+            payload[key] = value
+    sink.write(payload)