@neoline/hostbridge 2.0.2 → 2.0.4

package/src/server_control_mcp/policy.py

@@ -18,12 +18,16 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Protocol
 
+from .secure_files import open_private_append, read_private_text
+
 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_AUDIT_MAX_BYTES = 10 * 1024 * 1024
+DEFAULT_AUDIT_BACKUP_COUNT = 3
 
 DEFAULT_DENYLIST_PATTERNS = (
     r"\brm\s+-rf\s+/(?:\s|$)",
@@ -46,16 +50,37 @@ class _NullAudit:
 
 
 class _JsonlAudit:
-    def __init__(self, path: Path) -> None:
+    def __init__(self, path: Path, *, max_bytes: int, backup_count: int) -> None:
         self._path = path
+        self._max_bytes = max_bytes
+        self._backup_count = backup_count
         self._lock = threading.Lock()
 
     def write(self, event: dict[str, Any]) -> None:
         line = json.dumps(event, ensure_ascii=False, sort_keys=True) + "\n"
+        encoded_size = len(line.encode("utf-8"))
         with self._lock:
-            self._path.parent.mkdir(parents=True, exist_ok=True)
-            with self._path.open("a", encoding="utf-8") as handle:
+            current_size = self._path.stat().st_size if self._path.exists() else 0
+            if current_size and current_size + encoded_size > self._max_bytes:
+                self._rotate()
+            with open_private_append(self._path) as handle:
                 handle.write(line)
+                handle.flush()
+
+    def _rotate(self) -> None:
+        if self._backup_count == 0:
+            self._path.unlink(missing_ok=True)
+            return
+        oldest = self._backup_path(self._backup_count)
+        oldest.unlink(missing_ok=True)
+        for index in range(self._backup_count - 1, 0, -1):
+            source = self._backup_path(index)
+            if source.exists():
+                source.replace(self._backup_path(index + 1))
+        self._path.replace(self._backup_path(1))
+
+    def _backup_path(self, index: int) -> Path:
+        return self._path.with_name(f"{self._path.name}.{index}")
 
 
 @dataclass(frozen=True, slots=True)
@@ -70,6 +95,8 @@ 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
+    audit_max_bytes: int = DEFAULT_AUDIT_MAX_BYTES
+    audit_backup_count: int = DEFAULT_AUDIT_BACKUP_COUNT
     enabled: bool = True
 
     @classmethod
@@ -90,7 +117,9 @@ class PolicyConfig:
         idle_timeout = int(
             env.get(
                 "HOSTBRIDGE_IDLE_TIMEOUT",
-                env.get("SERVER_CONTROL_MCP_IDLE_TIMEOUT", raw.get("idle_timeout_seconds", DEFAULT_IDLE_TIMEOUT_SECONDS)),
+                env.get(
+                    "SERVER_CONTROL_MCP_IDLE_TIMEOUT", raw.get("idle_timeout_seconds", DEFAULT_IDLE_TIMEOUT_SECONDS)
+                ),
             )
         )
         idle_timeout = max(0, idle_timeout)
@@ -104,17 +133,43 @@ class PolicyConfig:
         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
+        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
+        audit_max_bytes = int(
+            env.get(
+                "HOSTBRIDGE_AUDIT_MAX_BYTES",
+                env.get(
+                    "SERVER_CONTROL_MCP_AUDIT_MAX_BYTES",
+                    raw.get("audit_max_bytes", DEFAULT_AUDIT_MAX_BYTES),
+                ),
+            )
+        )
+        audit_backup_count = int(
+            env.get(
+                "HOSTBRIDGE_AUDIT_BACKUP_COUNT",
+                env.get(
+                    "SERVER_CONTROL_MCP_AUDIT_BACKUP_COUNT",
+                    raw.get("audit_backup_count", DEFAULT_AUDIT_BACKUP_COUNT),
+                ),
+            )
+        )
+        if audit_max_bytes <= 0:
+            raise ValueError("audit_max_bytes must be positive")
+        if audit_backup_count < 0:
+            raise ValueError("audit_backup_count must be non-negative")
 
         return cls(
             idle_timeout_seconds=idle_timeout,
             command_denylist=tuple(re.compile(pattern) for pattern in patterns),
             audit_log_path=audit_path,
+            audit_max_bytes=audit_max_bytes,
+            audit_backup_count=audit_backup_count,
             enabled=True,
         )
 
@@ -130,7 +185,9 @@ class PolicyConfig:
 
 
 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 (
+    if (
+        os.environ.get("HOSTBRIDGE_DISABLE_POLICY", "") or os.environ.get("SERVER_CONTROL_MCP_DISABLE_POLICY", "")
+    ).lower() in (
         "1",
         "true",
         "yes",
@@ -141,24 +198,39 @@ def load_policy(config_path: Path | str | None = None) -> PolicyConfig:
         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)
+        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:
+        policy_text = read_private_text(path)
+    except FileNotFoundError:
+        policy_text = None
+    except OSError as exc:
+        raise ValueError(f"failed to read HostBridge policy file {path}") from exc
+    if policy_text is not None:
         try:
-            data = json.loads(path.read_text(encoding="utf-8"))
-            if isinstance(data, dict):
-                raw = data
-        except (OSError, json.JSONDecodeError):
-            raw = {}
+            data = json.loads(policy_text)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"HostBridge policy file {path} is not valid JSON") from exc
+        if not isinstance(data, dict):
+            raise ValueError(f"HostBridge policy file {path} must contain a JSON object")
+        raw = data
     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)
+    return _JsonlAudit(
+        policy.audit_log_path,
+        max_bytes=policy.audit_max_bytes,
+        backup_count=policy.audit_backup_count,
+    )
 
 
 def audit_event(

package/src/server_control_mcp/protocol.py

@@ -66,6 +66,21 @@ def encode_frame(frame: BinaryFrame) -> bytes:
 def decode_frame(data: bytes) -> tuple[BinaryFrame, bytes]:
     if not isinstance(data, bytes):
         raise ProtocolError("frame data must be bytes")
+    sequence, flags, stream_id_length, payload_length = _decode_header(data)
+    frame_length = _FRAME_HEADER.size + stream_id_length + payload_length
+    if len(data) < frame_length:
+        raise ProtocolError("incomplete frame payload")
+    stream_id_start = _FRAME_HEADER.size
+    payload_start = stream_id_start + stream_id_length
+    try:
+        stream_id = data[stream_id_start:payload_start].decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ProtocolError("stream_id must be valid UTF-8") from exc
+    payload = data[payload_start:frame_length]
+    return BinaryFrame(_required_text(stream_id, "stream_id"), sequence, flags, payload), data[frame_length:]
+
+
+def _decode_header(data: bytes) -> tuple[int, FrameFlags, int, int]:
     if len(data) < _FRAME_HEADER.size:
         raise ProtocolError("incomplete frame header")
     magic, protocol, raw_flags, reserved, sequence, stream_id_length, payload_length = _FRAME_HEADER.unpack_from(data)
@@ -79,23 +94,13 @@ def decode_frame(data: bytes) -> tuple[BinaryFrame, bytes]:
         raise ProtocolError(f"stream_id exceeds {MAX_STREAM_ID_BYTES} bytes")
     if payload_length > MAX_FRAME_BYTES:
         raise ProtocolError(f"frame payload exceeds {MAX_FRAME_BYTES} bytes")
-    frame_length = _FRAME_HEADER.size + stream_id_length + payload_length
-    if len(data) < frame_length:
-        raise ProtocolError("incomplete frame payload")
-    stream_id_start = _FRAME_HEADER.size
-    payload_start = stream_id_start + stream_id_length
-    try:
-        stream_id = data[stream_id_start:payload_start].decode("utf-8")
-    except UnicodeDecodeError as exc:
-        raise ProtocolError("stream_id must be valid UTF-8") from exc
     try:
         flags = FrameFlags(raw_flags)
     except ValueError as exc:
         raise ProtocolError("flags contain an unsupported frame flag") from exc
     if not flags or int(flags) & ~int(FrameFlags.DATA | FrameFlags.EOF | FrameFlags.CANCEL):
         raise ProtocolError("flags contain an unsupported frame flag")
-    payload = data[payload_start:frame_length]
-    return BinaryFrame(_required_text(stream_id, "stream_id"), sequence, flags, payload), data[frame_length:]
+    return sequence, flags, stream_id_length, payload_length
 
 
 def _read_exact(stream: BinaryIO, size: int) -> bytes:
@@ -110,9 +115,7 @@ def _read_exact(stream: BinaryIO, size: int) -> bytes:
 
 def read_frame(stream: BinaryIO) -> BinaryFrame:
     header = _read_exact(stream, _FRAME_HEADER.size)
-    _, _, _, _, _, stream_id_length, payload_length = _FRAME_HEADER.unpack(header)
-    if stream_id_length > MAX_STREAM_ID_BYTES or payload_length > MAX_FRAME_BYTES:
-        decode_frame(header)
+    _, _, stream_id_length, payload_length = _decode_header(header)
     body = _read_exact(stream, stream_id_length + payload_length)
     frame, remainder = decode_frame(header + body)
     if remainder:
@@ -169,9 +172,7 @@ class FrameSequenceValidator:
     def accept(self, frame: BinaryFrame) -> None:
         expected = self._next_by_stream.get(frame.stream_id, 0)
         if frame.sequence != expected:
-            raise ProtocolError(
-                f"stream {frame.stream_id!r} expected sequence {expected}, received {frame.sequence}"
-            )
+            raise ProtocolError(f"stream {frame.stream_id!r} expected sequence {expected}, received {frame.sequence}")
         self._next_by_stream[frame.stream_id] = expected + 1
 
 

package/src/server_control_mcp/remote_task_agent.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import shlex
+from collections.abc import Iterable
+
+REMOTE_TASK_LOG_MAX_BYTES = 1024 * 1024
+REMOTE_TASK_READ_CHUNK_BYTES = 64 * 1024
+
+REMOTE_TASK_AGENT = r"""
+import os
+import pathlib
+import subprocess
+import sys
+
+command, job_dir_text, log_limit_text = sys.argv[1], sys.argv[2], sys.argv[3]
+job_dir = pathlib.Path(job_dir_text)
+log_limit = int(log_limit_text)
+
+
+def write_atomic(name, value):
+    temporary = job_dir / ("." + name + ".tmp")
+    temporary.write_text(str(value) + "\n", encoding="ascii")
+    os.replace(temporary, job_dir / name)
+
+
+os.setsid()
+write_atomic("pid", os.getpid())
+with (job_dir / "stdout.log").open("w+b", buffering=0) as output:
+    process = subprocess.Popen(
+        ["/bin/sh", "-lc", command],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    current_size = 0
+    while True:
+        chunk = process.stdout.read(65536)
+        if not chunk:
+            break
+        if len(chunk) >= log_limit:
+            retained = chunk[-log_limit:]
+        elif current_size + len(chunk) > log_limit:
+            keep = log_limit - len(chunk)
+            output.seek(current_size - keep)
+            retained = output.read(keep) + chunk
+        else:
+            output.seek(current_size)
+            output.write(chunk)
+            current_size += len(chunk)
+            continue
+        output.seek(0)
+        output.write(retained)
+        output.truncate()
+        current_size = len(retained)
+    returncode = process.wait()
+status = returncode if returncode >= 0 else 128 - returncode
+write_atomic("exit_code", status)
+"""
+
+
+def remote_job_dir(task_id: str) -> str:
+    return f"$HOME/.hostbridge/jobs/{task_id}"
+
+
+def remote_job_dir_assignment(task_id: str) -> str:
+    relative_path = shlex.quote(f".hostbridge/jobs/{task_id}")
+    return f'job_dir="$HOME"/{relative_path}'
+
+
+def build_remote_task_command(command: str, task_id: str) -> str:
+    supervisor = (
+        f'python3 -u -c {shlex.quote(REMOTE_TASK_AGENT)} {shlex.quote(command)} "$job_dir" {REMOTE_TASK_LOG_MAX_BYTES}'
+    )
+    return (
+        'umask 077; [ -n "${HOME:-}" ] || exit 1; '
+        f'{remote_job_dir_assignment(task_id)}; mkdir -p -- "$job_dir" || exit $?; '
+        'chmod 700 "$HOME/.hostbridge" "$HOME/.hostbridge/jobs" "$job_dir" || exit $?; '
+        f"nohup {supervisor} </dev/null >/dev/null 2>&1 & launcher=$!; "
+        'attempt=0; while [ "$attempt" -lt 100 ]; do '
+        'if [ -s "$job_dir/pid" ]; then cat "$job_dir/pid"; exit 0; fi; '
+        'if ! kill -0 "$launcher" 2>/dev/null; then break; fi; '
+        "attempt=$((attempt + 1)); sleep 0.05; done; exit 1"
+    )
+
+
+def build_remote_tasks_cleanup_command(tasks: Iterable[tuple[str, int | None]]) -> str:
+    cleanup_steps = ["umask 077", '[ -n "${HOME:-}" ] || exit 1']
+    for task_id, recorded_pid in tasks:
+        fallback_pid = str(recorded_pid) if recorded_pid is not None else ""
+        cleanup_steps.extend(
+            (
+                remote_job_dir_assignment(task_id),
+                f'pid=$(cat "$job_dir/pid" 2>/dev/null || printf %s {shlex.quote(fallback_pid)})',
+                'if [ ! -f "$job_dir/exit_code" ] && [ -n "$pid" ] && kill -0 -- -"$pid" 2>/dev/null; then '
+                'kill -TERM -- -"$pid" 2>/dev/null || true; attempt=0; '
+                'while kill -0 -- -"$pid" 2>/dev/null && [ "$attempt" -lt 20 ]; do '
+                "attempt=$((attempt + 1)); sleep 0.05; done; "
+                'kill -KILL -- -"$pid" 2>/dev/null || true; fi',
+                'rm -rf -- "$job_dir" || exit $?',
+            )
+        )
+    return "; ".join(cleanup_steps)

package/src/server_control_mcp/remote_tunnel_agent.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import shlex
+
+REMOTE_TUNNEL_AGENT = r"""
+import base64
+import os
+import socket
+import sys
+import termios
+import threading
+
+host, port, prefix = sys.argv[1], int(sys.argv[2]), sys.argv[3]
+prefix_bytes = prefix.encode("ascii")
+write_lock = threading.Lock()
+downstream_sequence = 0
+upstream_sequence = 0
+terminal_attributes = None
+connection = None
+receiver_error = []
+
+
+def emit(kind, payload=b"", status=None):
+    global downstream_sequence
+    status_text = "-" if status is None else str(status)
+    encoded = base64.b64encode(payload).decode("ascii")
+    with write_lock:
+        line = "%s:V1:D:%d:%s:%s:%s" % (
+            prefix,
+            downstream_sequence,
+            kind,
+            status_text,
+            encoded,
+        )
+        downstream_sequence += 1
+        print(line, flush=True)
+
+
+def disable_echo():
+    global terminal_attributes
+    if not os.isatty(sys.stdin.fileno()):
+        return
+    terminal_attributes = termios.tcgetattr(sys.stdin.fileno())
+    updated = list(terminal_attributes)
+    updated[3] &= ~termios.ECHO
+    termios.tcsetattr(sys.stdin.fileno(), termios.TCSANOW, updated)
+
+
+def restore_terminal():
+    if terminal_attributes is not None:
+        termios.tcsetattr(sys.stdin.fileno(), termios.TCSANOW, terminal_attributes)
+
+
+def decode_upstream(raw_line):
+    global upstream_sequence
+    line = raw_line.rstrip(b"\r\n")
+    marker = prefix_bytes + b":V"
+    offset = line.find(marker)
+    if offset < 0:
+        return None
+    fields = line[offset:].split(b":", 6)
+    if len(fields) != 7:
+        raise ValueError("malformed upstream frame")
+    frame_prefix, version, direction, sequence, kind, status, payload = fields
+    if frame_prefix != prefix_bytes or version != b"V1" or direction != b"U":
+        raise ValueError("invalid upstream frame header")
+    if int(sequence) != upstream_sequence:
+        raise ValueError("unexpected upstream frame sequence")
+    upstream_sequence += 1
+    if status != b"-":
+        raise ValueError("upstream frame must not contain status")
+    kind_text = kind.decode("ascii")
+    if kind_text not in {"DATA", "EOF"}:
+        raise ValueError("invalid upstream frame kind")
+    decoded = base64.b64decode(payload, validate=True)
+    if kind_text == "EOF" and decoded:
+        raise ValueError("upstream EOF must not contain payload")
+    return kind_text, decoded
+
+
+def receive():
+    try:
+        while True:
+            data = connection.recv(16 * 1024)
+            if not data:
+                emit("EOF")
+                return
+            emit("DATA", data)
+    except Exception as exc:
+        receiver_error.append(exc)
+        emit("ERROR", str(exc).encode("utf-8", errors="replace"))
+
+
+status = 0
+try:
+    disable_echo()
+    connection = socket.create_connection((host, port), timeout=15)
+    connection.settimeout(None)
+    emit("READY")
+    receiver = threading.Thread(target=receive, daemon=True)
+    receiver.start()
+    saw_upstream_eof = False
+    for raw_line in sys.stdin.buffer:
+        frame = decode_upstream(raw_line)
+        if frame is None:
+            continue
+        kind, payload = frame
+        if kind == "DATA":
+            connection.sendall(payload)
+        else:
+            connection.shutdown(socket.SHUT_WR)
+            saw_upstream_eof = True
+            break
+    if not saw_upstream_eof:
+        raise EOFError("upstream tunnel closed without EOF frame")
+    receiver.join()
+    if receiver_error:
+        status = 1
+except Exception as exc:
+    status = 1
+    emit("ERROR", str(exc).encode("utf-8", errors="replace"))
+finally:
+    if connection is not None:
+        try:
+            connection.close()
+        except Exception:
+            status = 1
+    try:
+        restore_terminal()
+    except Exception as exc:
+        status = 1
+        emit("ERROR", str(exc).encode("utf-8", errors="replace"))
+    emit("CLOSED", status=status)
+
+raise SystemExit(status)
+"""
+
+
+def build_remote_tunnel_command(dest_host: str, dest_port: int, prefix: str) -> bytes:
+    command = (
+        f"python3 -u -c {shlex.quote(REMOTE_TUNNEL_AGENT)} {shlex.quote(dest_host)} {dest_port} {shlex.quote(prefix)}\n"
+    )
+    return command.encode("utf-8")

package/src/server_control_mcp/runtime.py

@@ -9,6 +9,8 @@ import tempfile
 from dataclasses import dataclass
 from pathlib import Path
 
+from .secure_files import ensure_private_directory
+
 
 @dataclass(frozen=True, slots=True)
 class RuntimePaths:
@@ -18,8 +20,7 @@ class RuntimePaths:
     log: Path
 
     def ensure_directory(self) -> None:
-        self.directory.mkdir(mode=0o700, parents=True, exist_ok=True)
-        self.directory.chmod(0o700)
+        ensure_private_directory(self.directory)
 
 
 def _default_runtime_dir() -> Path:

package/src/server_control_mcp/secrets.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
 import os
-from contextlib import suppress
 from pathlib import Path
 from typing import Any
 
 from cryptography.fernet import Fernet, InvalidToken
 
+from .secure_files import create_private_file, validate_private_file
+
 DEFAULT_KEY_FILE = Path("~/.hostbridge/key").expanduser()
 LEGACY_KEY_FILE = Path("~/.server_control_mcp/key").expanduser()
 SCHEME = "fernet.v1"
@@ -24,13 +25,12 @@ def key_file_path() -> Path:
 def _load_or_create_key() -> bytes:
     path = key_file_path()
     if path.exists():
+        validate_private_file(path)
         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
+    if create_private_file(path, key + b"\n"):
+        return key
+    return path.read_bytes().strip()
 
 
 def encrypt_secret(value: str) -> dict[str, str]:

package/src/server_control_mcp/secure_files.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import errno
+import os
+import stat
+import tempfile
+from contextlib import suppress
+from pathlib import Path
+
+
+def ensure_private_directory(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with suppress(FileExistsError):
+        os.mkdir(path, 0o700)
+    metadata = path.lstat()
+    if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
+        raise RuntimeError(f"secure directory is not a real directory: {path}")
+    if metadata.st_uid != os.getuid():
+        raise PermissionError(f"secure directory is not owned by the current user: {path}")
+    path.chmod(0o700)
+
+
+def validate_private_file(path: Path) -> None:
+    metadata = path.lstat()
+    if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISREG(metadata.st_mode):
+        raise RuntimeError(f"private file is not a regular file: {path}")
+    if metadata.st_uid != os.getuid():
+        raise PermissionError(f"private file is not owned by the current user: {path}")
+    path.chmod(0o600)
+
+
+def read_private_text(path: Path) -> str:
+    nofollow = getattr(os, "O_NOFOLLOW", None)
+    if nofollow is None:
+        raise RuntimeError("secure private file reads require O_NOFOLLOW")
+    flags = os.O_RDONLY | nofollow
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    try:
+        descriptor = os.open(path, flags)
+    except OSError as exc:
+        if exc.errno == errno.ELOOP:
+            raise RuntimeError(f"private file is not a regular file: {path}") from exc
+        raise
+    try:
+        metadata = os.fstat(descriptor)
+        if not stat.S_ISREG(metadata.st_mode):
+            raise RuntimeError(f"private file is not a regular file: {path}")
+        if metadata.st_uid != os.getuid():
+            raise PermissionError(f"private file is not owned by the current user: {path}")
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "r", encoding="utf-8") as handle:
+            descriptor = -1
+            return handle.read()
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+
+
+def create_private_file(path: Path, data: bytes) -> bool:
+    ensure_private_directory(path.parent)
+    descriptor, name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(name)
+    try:
+        os.fchmod(descriptor, 0o600)
+        _write_all(descriptor, data)
+        os.fsync(descriptor)
+        os.close(descriptor)
+        descriptor = -1
+        try:
+            os.link(temporary, path)
+        except FileExistsError:
+            validate_private_file(path)
+            return False
+        validate_private_file(path)
+        return True
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        temporary.unlink(missing_ok=True)
+
+
+def replace_private_file(path: Path, data: bytes) -> None:
+    ensure_private_directory(path.parent)
+    descriptor, name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(name)
+    try:
+        os.fchmod(descriptor, 0o600)
+        _write_all(descriptor, data)
+        os.fsync(descriptor)
+        os.close(descriptor)
+        descriptor = -1
+        temporary.replace(path)
+        validate_private_file(path)
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        temporary.unlink(missing_ok=True)
+
+
+def open_private_append(path: Path):
+    ensure_private_directory(path.parent)
+    flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    descriptor = os.open(path, flags, 0o600)
+    metadata = os.fstat(descriptor)
+    if not stat.S_ISREG(metadata.st_mode) or metadata.st_uid != os.getuid():
+        os.close(descriptor)
+        raise PermissionError(f"private log is not owned by the current user: {path}")
+    os.fchmod(descriptor, 0o600)
+    return os.fdopen(descriptor, "a", encoding="utf-8")
+
+
+def _write_all(descriptor: int, data: bytes) -> None:
+    remaining = memoryview(data)
+    while remaining:
+        written = os.write(descriptor, remaining)
+        if written <= 0:
+            raise OSError("private file write made no progress")
+        remaining = remaining[written:]