@neoline/hostbridge 2.0.4 → 2.0.5

package/src/server_control_mcp/remote_mux_agent.py

@@ -0,0 +1,769 @@
+"""Event-driven TCP forwarding service used by the remote PTY agent."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import ipaddress
+import os
+import signal
+import socket
+import sys
+import tempfile
+from collections import deque
+from collections.abc import Sequence
+from contextlib import suppress
+
+from .async_lifecycle import finish_task_before_cancellation, stop_input_after_peer_eof
+from .mux_records import MAX_RECORD_PAYLOAD_BYTES, MuxRecord, MuxRecordChannel, encode_record
+from .mux_rpc import MuxRpcFailure, serve_mux_rpc
+from .mux_stream import MuxRpcStream
+
+DEFAULT_MAX_AGENT_STREAMS = 128
+DEFAULT_CONNECT_TIMEOUT = 30.0
+DEFAULT_CLEANUP_TIMEOUT = 5.0
+MAX_CONNECT_TIMEOUT = 180.0
+TCP_CHUNK_BYTES = 64 * 1024
+MAX_EXEC_OUTPUT_BYTES = 16 * 1024 * 1024
+MAX_EXEC_TIMEOUT = 24 * 60 * 60
+MAX_TRANSFER_BYTES = 1024 * 1024 * 1024
+MAX_TRANSFER_CHUNK_BYTES = 1024 * 1024
+
+
+class RemoteMuxAgent:
+    def __init__(
+        self,
+        *,
+        max_streams: int = DEFAULT_MAX_AGENT_STREAMS,
+        cleanup_timeout_seconds: float = DEFAULT_CLEANUP_TIMEOUT,
+    ) -> None:
+        if not isinstance(max_streams, int) or isinstance(max_streams, bool) or max_streams <= 0:
+            raise ValueError("max_streams must be a positive integer")
+        if (
+            not isinstance(cleanup_timeout_seconds, (int, float))
+            or isinstance(cleanup_timeout_seconds, bool)
+            or cleanup_timeout_seconds <= 0
+        ):
+            raise ValueError("cleanup_timeout_seconds must be positive")
+        self.max_streams = max_streams
+        self.cleanup_timeout_seconds = float(cleanup_timeout_seconds)
+        self.active_streams = 0
+        self.peak_streams = 0
+        self._shells: dict[str, asyncio.subprocess.Process] = {}
+        self._shell_read_locks: dict[str, asyncio.Lock] = {}
+        self._shell_write_locks: dict[str, asyncio.Lock] = {}
+        self._shell_creation_lock = asyncio.Lock()
+
+    async def serve(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            await serve_mux_rpc(
+                reader,
+                writer,
+                self._handle_unary,
+                max_handlers=self.max_streams,
+                stream_handler=self._handle_stream,
+            )
+        finally:
+            await asyncio.gather(
+                *(self._close_shell(shell_id) for shell_id in tuple(self._shells)), return_exceptions=True
+            )
+
+    async def _handle_unary(self, method: str, params: dict[str, object]) -> dict[str, object]:
+        raise MuxRpcFailure("not_found", f"remote agent does not support unary method {method!r}")
+
+    async def _handle_stream(
+        self,
+        method: str,
+        params: dict[str, object],
+        stream: MuxRpcStream,
+    ) -> dict[str, object]:
+        if method not in {
+            "tcp.connect",
+            "exec.start",
+            "transfer.upload",
+            "transfer.download",
+            "shell.write",
+            "shell.read",
+            "shell.attach",
+            "shell.close",
+        }:
+            raise MuxRpcFailure("not_found", f"remote agent does not support stream method {method!r}")
+        if self.active_streams >= self.max_streams:
+            raise MuxRpcFailure("busy", "remote agent stream capacity is exhausted", retryable=True)
+        self.active_streams += 1
+        self.peak_streams = max(self.peak_streams, self.active_streams)
+        if method == "exec.start":
+            try:
+                return await _run_exec(stream, params, self.cleanup_timeout_seconds)
+            finally:
+                self.active_streams -= 1
+        if method == "transfer.upload":
+            try:
+                return await _receive_upload(stream, params)
+            finally:
+                self.active_streams -= 1
+        if method == "transfer.download":
+            try:
+                return await _send_download(stream, params)
+            finally:
+                self.active_streams -= 1
+        if method == "shell.write":
+            try:
+                return await self._shell_write(stream, params)
+            finally:
+                self.active_streams -= 1
+        if method == "shell.read":
+            try:
+                return await self._shell_read(stream, params)
+            finally:
+                self.active_streams -= 1
+        if method == "shell.attach":
+            try:
+                return await self._shell_attach(stream, params)
+            finally:
+                self.active_streams -= 1
+        if method == "shell.close":
+            try:
+                shell_id = _shell_id(params)
+                await stream.accept()
+                while await stream.receive(TCP_CHUNK_BYTES):
+                    raise MuxRpcFailure("invalid_request", "shell.close does not accept data")
+                await self._close_shell(shell_id)
+                return {"closed": True}
+            finally:
+                self.active_streams -= 1
+        writer: asyncio.StreamWriter | None = None
+        try:
+            destination = await _resolve_destination(params)
+            try:
+                async with asyncio.timeout(destination.timeout):
+                    reader, writer = await asyncio.open_connection(
+                        destination.address,
+                        destination.port,
+                        family=destination.family,
+                    )
+            except TimeoutError as exc:
+                raise MuxRpcFailure("timeout", "destination connection timed out", retryable=True) from exc
+            except OSError as exc:
+                raise MuxRpcFailure(
+                    "connection_lost",
+                    f"destination connection failed: {exc}",
+                    retryable=True,
+                ) from exc
+            await stream.accept()
+            return await _bridge_tcp(stream, reader, writer)
+        finally:
+            if writer is not None:
+                writer.close()
+                with suppress(Exception):
+                    async with asyncio.timeout(self.cleanup_timeout_seconds):
+                        await writer.wait_closed()
+            self.active_streams -= 1
+
+    async def _shell_write(self, stream: MuxRpcStream, params: dict[str, object]) -> dict[str, object]:
+        allowed = {"shell_id", "max_bytes"}
+        unknown = sorted(set(params) - allowed)
+        if unknown:
+            raise MuxRpcFailure("invalid_request", f"unknown shell.write fields: {', '.join(unknown)}")
+        shell_id = _shell_id(params)
+        max_bytes = _bounded_integer(params.get("max_bytes", 1024 * 1024), "max_bytes", maximum=MAX_TRANSFER_BYTES)
+        process = await self._ensure_shell(shell_id)
+        if process.stdin is None:
+            raise MuxRpcFailure("connection_lost", "shell stdin is unavailable", retryable=True)
+        await stream.accept()
+        written = 0
+        async with self._shell_write_locks[shell_id]:
+            while chunk := await stream.receive(TCP_CHUNK_BYTES):
+                written += len(chunk)
+                if written > max_bytes:
+                    raise MuxRpcFailure("resource_limit", f"shell write exceeds {max_bytes} bytes")
+                process.stdin.write(chunk)
+                await process.stdin.drain()
+        return {"written": written}
+
+    async def _shell_read(self, stream: MuxRpcStream, params: dict[str, object]) -> dict[str, object]:
+        allowed = {"shell_id", "timeout", "max_bytes"}
+        unknown = sorted(set(params) - allowed)
+        if unknown:
+            raise MuxRpcFailure("invalid_request", f"unknown shell.read fields: {', '.join(unknown)}")
+        shell_id = _shell_id(params)
+        timeout_value = params.get("timeout")
+        timeout = (
+            None
+            if timeout_value is None
+            else _bounded_non_negative_number(timeout_value, "timeout", maximum=MAX_EXEC_TIMEOUT)
+        )
+        max_bytes = _bounded_integer(params.get("max_bytes", 4096), "max_bytes", maximum=MAX_TRANSFER_BYTES)
+        process = await self._ensure_shell(shell_id)
+        if process.stdout is None:
+            raise MuxRpcFailure("connection_lost", "shell stdout is unavailable", retryable=True)
+        await stream.accept()
+        while await stream.receive(TCP_CHUNK_BYTES):
+            raise MuxRpcFailure("invalid_request", "shell.read does not accept data")
+        async with self._shell_read_locks[shell_id]:
+            if timeout is None:
+                data = await process.stdout.read(max_bytes)
+            else:
+                try:
+                    async with asyncio.timeout(timeout):
+                        data = await process.stdout.read(max_bytes)
+                except TimeoutError:
+                    data = b""
+        await stream.send(bytes(data))
+        return {"alive": process.returncode is None, "bytes": len(data)}
+
+    async def _shell_attach(self, stream: MuxRpcStream, params: dict[str, object]) -> dict[str, object]:
+        allowed = {"shell_id", "max_bytes"}
+        unknown = sorted(set(params) - allowed)
+        if unknown:
+            raise MuxRpcFailure("invalid_request", f"unknown shell.attach fields: {', '.join(unknown)}")
+        shell_id = _shell_id(params)
+        max_bytes = _bounded_integer(params.get("max_bytes", 64 * 1024), "max_bytes", maximum=MAX_TRANSFER_BYTES)
+        process = await self._ensure_shell(shell_id)
+        if process.stdin is None or process.stdout is None:
+            raise MuxRpcFailure("connection_lost", "shell pipes are unavailable", retryable=True)
+        shell_stdin = process.stdin
+        shell_stdout = process.stdout
+        await stream.accept()
+
+        async def send_input() -> None:
+            async with self._shell_write_locks[shell_id]:
+                while chunk := await stream.receive(TCP_CHUNK_BYTES):
+                    if len(chunk) > max_bytes:
+                        raise MuxRpcFailure("resource_limit", f"shell input chunk exceeds {max_bytes} bytes")
+                    shell_stdin.write(chunk)
+                    await shell_stdin.drain()
+                shell_stdin.write_eof()
+                with suppress(BrokenPipeError, ConnectionResetError):
+                    await shell_stdin.drain()
+
+        input_task = asyncio.create_task(send_input(), name=f"hostbridge-remote-shell-input-{shell_id}")
+        transferred = 0
+        try:
+            async with self._shell_read_locks[shell_id]:
+                while data := await shell_stdout.read(max_bytes):
+                    await stream.send(bytes(data))
+                    transferred += len(data)
+            await stop_input_after_peer_eof(input_task)
+            returncode = await process.wait()
+            if returncode < 0:
+                try:
+                    signal_name = signal.Signals(-returncode).name
+                except ValueError:
+                    signal_name = f"SIG{-returncode}"
+                return {"exit_code": None, "signal": signal_name, "bytes": transferred}
+            return {"exit_code": returncode, "signal": None, "bytes": transferred}
+        finally:
+            if not input_task.done():
+                input_task.cancel()
+            cleanup = asyncio.gather(input_task, return_exceptions=True)
+            await finish_task_before_cancellation(cleanup)
+
+    async def _ensure_shell(self, shell_id: str) -> asyncio.subprocess.Process:
+        async with self._shell_creation_lock:
+            process = self._shells.get(shell_id)
+            if process is not None and process.returncode is None:
+                return process
+            process = await asyncio.create_subprocess_exec(
+                "/bin/sh",
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+                start_new_session=True,
+            )
+            self._shells[shell_id] = process
+            self._shell_read_locks[shell_id] = asyncio.Lock()
+            self._shell_write_locks[shell_id] = asyncio.Lock()
+            return process
+
+    async def _close_shell(self, shell_id: str) -> None:
+        async with self._shell_creation_lock:
+            process = self._shells.pop(shell_id, None)
+            self._shell_read_locks.pop(shell_id, None)
+            self._shell_write_locks.pop(shell_id, None)
+        if process is not None:
+            await _terminate_process(process, self.cleanup_timeout_seconds)
+
+
+class _CombinedOutput:
+    def __init__(self, limit: int) -> None:
+        self._limit = limit
+        self._segments: deque[tuple[MuxRecordChannel, bytes]] = deque()
+        self._size = 0
+
+    def append(self, channel: MuxRecordChannel, chunk: bytes) -> None:
+        if not chunk:
+            return
+        self._segments.append((channel, bytes(chunk)))
+        self._size += len(chunk)
+        excess = self._size - self._limit
+        while excess > 0:
+            segment_channel, segment = self._segments[0]
+            if len(segment) <= excess:
+                self._segments.popleft()
+                self._size -= len(segment)
+                excess -= len(segment)
+            else:
+                self._segments[0] = (segment_channel, segment[excess:])
+                self._size -= excess
+                excess = 0
+
+    async def send(self, stream: MuxRpcStream) -> None:
+        for channel, segment in self._segments:
+            for offset in range(0, len(segment), MAX_RECORD_PAYLOAD_BYTES):
+                payload = segment[offset : offset + MAX_RECORD_PAYLOAD_BYTES]
+                await stream.send(encode_record(MuxRecord(channel, payload)))
+
+
+async def _run_exec(
+    stream: MuxRpcStream,
+    params: dict[str, object],
+    cleanup_timeout_seconds: float,
+) -> dict[str, object]:
+    allowed = {"command", "timeout", "output_limit"}
+    unknown = sorted(set(params) - allowed)
+    if unknown:
+        raise MuxRpcFailure("invalid_request", f"unknown exec.start fields: {', '.join(unknown)}")
+    command = _required_string(params, "command")
+    timeout = _bounded_number(params.get("timeout", 60), "timeout", maximum=MAX_EXEC_TIMEOUT)
+    output_limit = _bounded_integer(
+        params.get("output_limit", 1_000_000),
+        "output_limit",
+        maximum=MAX_EXEC_OUTPUT_BYTES,
+    )
+    try:
+        process = await asyncio.create_subprocess_exec(
+            "/bin/sh",
+            "-lc",
+            command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            start_new_session=True,
+        )
+    except OSError as exc:
+        raise MuxRpcFailure("connection_lost", f"failed to start command: {exc}", retryable=True) from exc
+    stdin_writer = process.stdin
+    stdout_reader = process.stdout
+    stderr_reader = process.stderr
+    if stdin_writer is None or stdout_reader is None or stderr_reader is None:
+        await _terminate_process(process, cleanup_timeout_seconds)
+        raise MuxRpcFailure("internal", "command subprocess pipes are unavailable")
+    await stream.accept()
+    output = _CombinedOutput(output_limit)
+
+    async def write_stdin() -> None:
+        try:
+            while chunk := await stream.receive(TCP_CHUNK_BYTES):
+                stdin_writer.write(chunk)
+                await stdin_writer.drain()
+            if stdin_writer.can_write_eof():
+                stdin_writer.write_eof()
+                await stdin_writer.drain()
+            else:
+                stdin_writer.close()
+        except (BrokenPipeError, ConnectionResetError):
+            return
+
+    async def read_output(reader: asyncio.StreamReader, channel: MuxRecordChannel) -> None:
+        while chunk := await reader.read(TCP_CHUNK_BYTES):
+            output.append(channel, chunk)
+
+    tasks = [
+        asyncio.create_task(write_stdin(), name=f"remote-agent-exec-stdin-{stream.stream_id}"),
+        asyncio.create_task(
+            read_output(stdout_reader, MuxRecordChannel.STDOUT),
+            name=f"remote-agent-exec-stdout-{stream.stream_id}",
+        ),
+        asyncio.create_task(
+            read_output(stderr_reader, MuxRecordChannel.STDERR),
+            name=f"remote-agent-exec-stderr-{stream.stream_id}",
+        ),
+    ]
+    timed_out = False
+    try:
+        async with asyncio.timeout(timeout):
+            await asyncio.gather(process.wait(), *tasks)
+    except TimeoutError:
+        timed_out = True
+        await _terminate_process(process, cleanup_timeout_seconds)
+    except BaseException:
+        await _terminate_process(process, cleanup_timeout_seconds)
+        raise
+    finally:
+        for task in tasks:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+    await output.send(stream)
+    return {
+        "exit_code": None if timed_out else process.returncode,
+        "timed_out": timed_out,
+    }
+
+
+async def _terminate_process(process: asyncio.subprocess.Process, timeout: float) -> None:
+    cleanup = asyncio.create_task(
+        _terminate_process_owned(process, timeout),
+        name=f"remote-agent-process-reap-{process.pid}",
+    )
+    cancellation: asyncio.CancelledError | None = None
+    while not cleanup.done():
+        try:
+            await asyncio.shield(cleanup)
+        except asyncio.CancelledError as exc:
+            cancellation = exc
+    cleanup.result()
+    if cancellation is not None:
+        raise cancellation
+
+
+async def _terminate_process_owned(process: asyncio.subprocess.Process, timeout: float) -> None:
+    if process.returncode is not None:
+        await process.wait()
+        return
+    with suppress(ProcessLookupError):
+        os.killpg(process.pid, signal.SIGTERM)
+    try:
+        async with asyncio.timeout(timeout):
+            await process.wait()
+    except TimeoutError:
+        with suppress(ProcessLookupError):
+            os.killpg(process.pid, signal.SIGKILL)
+        await process.wait()
+
+
+async def _receive_upload(stream: MuxRpcStream, params: dict[str, object]) -> dict[str, object]:
+    allowed = {"remote_path", "mode", "expected_size", "expected_sha256", "max_bytes"}
+    unknown = sorted(set(params) - allowed)
+    if unknown:
+        raise MuxRpcFailure("invalid_request", f"unknown transfer.upload fields: {', '.join(unknown)}")
+    remote_path = _remote_path(params, "remote_path")
+    mode = _file_mode(params.get("mode", 0o644))
+    max_bytes = _bounded_integer(
+        params.get("max_bytes", MAX_TRANSFER_BYTES),
+        "max_bytes",
+        maximum=MAX_TRANSFER_BYTES,
+    )
+    expected_size_value = params.get("expected_size")
+    expected_size = (
+        None
+        if expected_size_value is None
+        else _non_negative_integer(expected_size_value, "expected_size", maximum=max_bytes)
+    )
+    expected_sha256 = _optional_sha256(params.get("expected_sha256"))
+    parent = os.path.dirname(remote_path) or "."
+    prefix = f".{os.path.basename(remote_path)}.hostbridge-"
+    try:
+        descriptor, temporary = tempfile.mkstemp(prefix=prefix, dir=parent)
+    except OSError as exc:
+        raise MuxRpcFailure("remote_error", f"failed to create upload temporary file: {exc}") from exc
+    transferred = 0
+    digest = hashlib.sha256()
+    file = os.fdopen(descriptor, "wb", buffering=0)
+    try:
+        os.fchmod(file.fileno(), 0o600)
+        await stream.accept()
+        while chunk := await stream.receive(TCP_CHUNK_BYTES):
+            transferred += len(chunk)
+            if transferred > max_bytes:
+                raise MuxRpcFailure("resource_limit", f"upload exceeds {max_bytes} bytes")
+            await asyncio.to_thread(file.write, chunk)
+            digest.update(chunk)
+        if expected_size is not None and transferred != expected_size:
+            raise MuxRpcFailure(
+                "integrity_error",
+                f"upload size mismatch: expected {expected_size}, received {transferred}",
+            )
+        actual_sha256 = digest.hexdigest()
+        if expected_sha256 is not None and actual_sha256 != expected_sha256:
+            raise MuxRpcFailure(
+                "integrity_error",
+                f"upload SHA-256 mismatch: expected {expected_sha256}, received {actual_sha256}",
+            )
+        await asyncio.to_thread(os.fsync, file.fileno())
+        file.close()
+        os.chmod(temporary, mode)
+        os.replace(temporary, remote_path)
+    except BaseException:
+        file.close()
+        with suppress(FileNotFoundError):
+            os.unlink(temporary)
+        raise
+    return {"bytes_transferred": transferred, "sha256": digest.hexdigest()}
+
+
+async def _send_download(stream: MuxRpcStream, params: dict[str, object]) -> dict[str, object]:
+    allowed = {"remote_path", "chunk_size", "max_bytes"}
+    unknown = sorted(set(params) - allowed)
+    if unknown:
+        raise MuxRpcFailure("invalid_request", f"unknown transfer.download fields: {', '.join(unknown)}")
+    remote_path = _remote_path(params, "remote_path")
+    chunk_size = _bounded_integer(
+        params.get("chunk_size", 256 * 1024),
+        "chunk_size",
+        maximum=MAX_TRANSFER_CHUNK_BYTES,
+    )
+    if chunk_size < 4096:
+        raise MuxRpcFailure("invalid_request", "chunk_size must be at least 4096")
+    max_bytes = _bounded_integer(
+        params.get("max_bytes", MAX_TRANSFER_BYTES),
+        "max_bytes",
+        maximum=MAX_TRANSFER_BYTES,
+    )
+    transferred = 0
+    digest = hashlib.sha256()
+    try:
+        with open(remote_path, "rb", buffering=0) as file:  # noqa: PTH123
+            await stream.accept()
+            while chunk := await asyncio.to_thread(file.read, chunk_size):
+                transferred += len(chunk)
+                if transferred > max_bytes:
+                    raise MuxRpcFailure("resource_limit", f"download exceeds {max_bytes} bytes")
+                digest.update(chunk)
+                await stream.send(chunk)
+    except OSError as exc:
+        raise MuxRpcFailure("remote_error", f"failed to read download source: {exc}") from exc
+    return {"bytes_transferred": transferred, "sha256": digest.hexdigest()}
+
+
+class _PipeWriterProtocol(asyncio.streams.FlowControlMixin):
+    def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
+        super().__init__(loop=loop)
+        self._closed = loop.create_future()
+
+    def connection_lost(self, exc: Exception | None) -> None:
+        super().connection_lost(exc)
+        if self._closed.done():
+            return
+        if exc is None:
+            self._closed.set_result(None)
+        else:
+            self._closed.set_exception(exc)
+
+    def _get_close_waiter(self, stream: object) -> asyncio.Future[None]:  # noqa: ARG002
+        return self._closed
+
+
+async def run_stdio_agent() -> int:
+    loop = asyncio.get_running_loop()
+    reader = asyncio.StreamReader()
+    reader_protocol = asyncio.StreamReaderProtocol(reader)
+    read_transport, _ = await loop.connect_read_pipe(lambda: reader_protocol, sys.stdin.buffer)
+    write_protocol = _PipeWriterProtocol(loop)
+    write_transport, _ = await loop.connect_write_pipe(lambda: write_protocol, sys.stdout.buffer)
+    writer = asyncio.StreamWriter(write_transport, write_protocol, reader, loop)
+    try:
+        await RemoteMuxAgent().serve(reader, writer)
+    finally:
+        read_transport.close()
+    return 0
+
+
+class _Destination:
+    __slots__ = ("address", "family", "port", "timeout")
+
+    def __init__(self, address: str, family: socket.AddressFamily, port: int, timeout: float) -> None:
+        self.address = address
+        self.family = family
+        self.port = port
+        self.timeout = timeout
+
+
+async def _resolve_destination(params: dict[str, object]) -> _Destination:
+    allowed = {
+        "host",
+        "port",
+        "allow_hostnames",
+        "allow_cidrs",
+        "allow_ports",
+        "connect_timeout",
+    }
+    unknown = sorted(set(params) - allowed)
+    if unknown:
+        raise MuxRpcFailure("invalid_request", f"unknown tcp.connect fields: {', '.join(unknown)}")
+
+    host = _required_string(params, "host")
+    port = _port(params.get("port"), "port")
+    allow_ports = _ports(params.get("allow_ports"), "allow_ports")
+    if port not in allow_ports:
+        raise MuxRpcFailure("denied", f"destination port {port} is not allowed")
+    networks = _networks(params.get("allow_cidrs"))
+    hostnames = _strings(params.get("allow_hostnames"), "allow_hostnames")
+    timeout = _timeout(params.get("connect_timeout", DEFAULT_CONNECT_TIMEOUT))
+
+    try:
+        literal = ipaddress.ip_address(host)
+    except ValueError:
+        literal = None
+
+    if literal is not None:
+        _require_allowed_address(literal, networks)
+        family = socket.AF_INET6 if literal.version == 6 else socket.AF_INET
+        return _Destination(str(literal), family, port, timeout)
+
+    normalized_host = host.rstrip(".").casefold()
+    if normalized_host not in {value.rstrip(".").casefold() for value in hostnames}:
+        raise MuxRpcFailure("denied", f"destination hostname {host!r} is not allowed")
+    try:
+        records = await asyncio.get_running_loop().getaddrinfo(
+            host,
+            port,
+            family=socket.AF_UNSPEC,
+            type=socket.SOCK_STREAM,
+            proto=socket.IPPROTO_TCP,
+        )
+    except OSError as exc:
+        raise MuxRpcFailure("connection_lost", f"destination resolution failed: {exc}", retryable=True) from exc
+    if not records:
+        raise MuxRpcFailure("connection_lost", "destination resolution returned no addresses", retryable=True)
+
+    resolved: list[tuple[socket.AddressFamily, ipaddress.IPv4Address | ipaddress.IPv6Address]] = []
+    for family, _socktype, _protocol, _canonical_name, sockaddr in records:
+        if family not in {socket.AF_INET, socket.AF_INET6}:
+            continue
+        address = ipaddress.ip_address(sockaddr[0])
+        _require_allowed_address(address, networks)
+        resolved.append((family, address))
+    if not resolved:
+        raise MuxRpcFailure("connection_lost", "destination resolution returned no TCP addresses", retryable=True)
+    family, address = resolved[0]
+    return _Destination(str(address), family, port, timeout)
+
+
+async def _bridge_tcp(
+    stream: MuxRpcStream,
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+) -> dict[str, object]:
+    bytes_sent = 0
+    bytes_received = 0
+
+    async def upstream() -> None:
+        nonlocal bytes_sent
+        while chunk := await stream.receive(TCP_CHUNK_BYTES):
+            writer.write(chunk)
+            await writer.drain()
+            bytes_sent += len(chunk)
+        if writer.can_write_eof():
+            writer.write_eof()
+            await writer.drain()
+
+    async def downstream() -> None:
+        nonlocal bytes_received
+        while chunk := await reader.read(TCP_CHUNK_BYTES):
+            await stream.send(chunk)
+            bytes_received += len(chunk)
+
+    try:
+        async with asyncio.TaskGroup() as group:
+            group.create_task(upstream(), name=f"remote-agent-upstream-{stream.stream_id}")
+            group.create_task(downstream(), name=f"remote-agent-downstream-{stream.stream_id}")
+    except* (ConnectionError, OSError) as group:
+        error = group.exceptions[0]
+        raise MuxRpcFailure("connection_lost", f"destination stream failed: {error}", retryable=True) from error
+    return {"bytes_sent": bytes_sent, "bytes_received": bytes_received}
+
+
+def _required_string(params: dict[str, object], name: str) -> str:
+    value = params.get(name)
+    if not isinstance(value, str) or not value:
+        raise MuxRpcFailure("invalid_request", f"{name} must be a non-empty string")
+    return value
+
+
+def _strings(value: object, name: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+        raise MuxRpcFailure("invalid_request", f"{name} must be a list of non-empty strings")
+    return tuple(value)
+
+
+def _ports(value: object, name: str) -> tuple[int, ...]:
+    if not isinstance(value, list):
+        raise MuxRpcFailure("invalid_request", f"{name} must be a list of ports")
+    return tuple(_port(item, name) for item in value)
+
+
+def _port(value: object, name: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 1 <= value <= 65535:
+        raise MuxRpcFailure("invalid_request", f"{name} must contain ports between 1 and 65535")
+    return value
+
+
+def _networks(value: object) -> tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...]:
+    values = _strings(value, "allow_cidrs")
+    try:
+        return tuple(ipaddress.ip_network(item, strict=True) for item in values)
+    except ValueError as exc:
+        raise MuxRpcFailure("invalid_request", f"allow_cidrs contains an invalid network: {exc}") from exc
+
+
+def _require_allowed_address(
+    address: ipaddress.IPv4Address | ipaddress.IPv6Address,
+    networks: Sequence[ipaddress.IPv4Network | ipaddress.IPv6Network],
+) -> None:
+    if not any(address.version == network.version and address in network for network in networks):
+        raise MuxRpcFailure("denied", f"resolved destination address {address} is not allowed")
+
+
+def _timeout(value: object) -> float:
+    if not isinstance(value, int | float) or isinstance(value, bool) or not 0 < float(value) <= MAX_CONNECT_TIMEOUT:
+        raise MuxRpcFailure("invalid_request", f"connect_timeout must be between 0 and {MAX_CONNECT_TIMEOUT:g}")
+    return float(value)
+
+
+def _bounded_number(value: object, name: str, *, maximum: float) -> float:
+    if not isinstance(value, int | float) or isinstance(value, bool) or not 0 < float(value) <= maximum:
+        raise MuxRpcFailure("invalid_request", f"{name} must be between 0 and {maximum:g}")
+    return float(value)
+
+
+def _bounded_non_negative_number(value: object, name: str, *, maximum: float) -> float:
+    if not isinstance(value, int | float) or isinstance(value, bool) or not 0 <= float(value) <= maximum:
+        raise MuxRpcFailure("invalid_request", f"{name} must be between 0 and {maximum:g}")
+    return float(value)
+
+
+def _bounded_integer(value: object, name: str, *, maximum: int) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 0 < value <= maximum:
+        raise MuxRpcFailure("invalid_request", f"{name} must be between 1 and {maximum}")
+    return value
+
+
+def _non_negative_integer(value: object, name: str, *, maximum: int) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 0 <= value <= maximum:
+        raise MuxRpcFailure("invalid_request", f"{name} must be between 0 and {maximum}")
+    return value
+
+
+def _file_mode(value: object) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 0 <= value <= 0o7777:
+        raise MuxRpcFailure("invalid_request", "mode must be an integer between 0 and 07777")
+    return value
+
+
+def _shell_id(params: dict[str, object]) -> str:
+    shell_id = _required_string(params, "shell_id")
+    if len(shell_id) > 128 or any(
+        character not in "0123456789abcdefghijklmnopqrstuvwxyz-_" for character in shell_id.lower()
+    ):
+        raise MuxRpcFailure("invalid_request", "shell_id contains unsupported characters")
+    return shell_id
+
+
+def _optional_sha256(value: object) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or len(value) != 64:
+        raise MuxRpcFailure("invalid_request", "expected_sha256 must be 64 hexadecimal characters or null")
+    normalized = value.lower()
+    if any(character not in "0123456789abcdef" for character in normalized):
+        raise MuxRpcFailure("invalid_request", "expected_sha256 must be 64 hexadecimal characters or null")
+    return normalized
+
+
+def _remote_path(params: dict[str, object], name: str) -> str:
+    value = _required_string(params, name)
+    if "\x00" in value:
+        raise MuxRpcFailure("invalid_request", f"{name} must not contain NUL bytes")
+    return value