Add remote_desktop host and viewer (headless)

A new utils/remote_desktop module lets one machine stream its screen and
receive input from another. The wire format is a length-prefixed framing
on raw TCP (no extra deps), starting with an HMAC-SHA256
challenge/response handshake; viewers that fail auth are dropped before
they can see a frame.

Host: capture loop encodes JPEG frames at the configured fps/quality and
broadcasts them to authenticated viewers via a shared latest-frame slot
+ Condition, so a slow viewer drops frames instead of blocking the rest.
Viewer input messages are JSON, validated against an allowlist, and
applied through the existing wrapper helpers (lazy-imported so the
viewer side stays platform-agnostic).

Defaults bind to 127.0.0.1 — exposing this to untrusted networks should
be paired with an SSH tunnel or TLS front-end. Tests cover the protocol,
auth, the dispatch allowlist, and a full localhost host<->viewer
round-trip including auth failure and graceful shutdown.

Author: JE-Chen

je_auto_control/utils/remote_desktop/__init__.py

@@ -0,0 +1,27 @@
+"""Remote-desktop host/viewer for screen streaming and remote input.
+
+The protocol is a minimal length-prefixed framing on raw TCP (no extra
+deps). The host periodically encodes the screen as JPEG and pushes it to
+authenticated viewers; viewers send back JSON input messages that the
+host dispatches via the existing mouse/keyboard wrappers. Token-based
+HMAC-SHA256 authentication and a default loopback bind keep casual
+misuse difficult — this is *not* a hardened RDP replacement, and exposing
+it to untrusted networks should be paired with an SSH tunnel or TLS
+front-end.
+"""
+from je_auto_control.utils.remote_desktop.host import RemoteDesktopHost
+from je_auto_control.utils.remote_desktop.input_dispatch import (
+    InputDispatchError, dispatch_input,
+)
+from je_auto_control.utils.remote_desktop.protocol import (
+    AuthenticationError, MessageType, ProtocolError,
+    decode_frame_header, encode_frame,
+)
+from je_auto_control.utils.remote_desktop.viewer import RemoteDesktopViewer
+
+__all__ = [
+    "RemoteDesktopHost", "RemoteDesktopViewer",
+    "InputDispatchError", "AuthenticationError", "ProtocolError",
+    "MessageType", "encode_frame", "decode_frame_header",
+    "dispatch_input",
+]

je_auto_control/utils/remote_desktop/auth.py

@@ -0,0 +1,28 @@
+"""HMAC-SHA256 challenge/response helpers shared by host and viewer."""
+import hmac
+import os
+from hashlib import sha256
+
+NONCE_BYTES = 32
+
+
+def make_nonce() -> bytes:
+    """Return a fresh random nonce for the auth handshake."""
+    return os.urandom(NONCE_BYTES)
+
+
+def compute_response(token: str, nonce: bytes) -> bytes:
+    """Return ``HMAC_SHA256(token, nonce)`` for the given token."""
+    if not isinstance(token, str) or not token:
+        raise ValueError("token must be a non-empty string")
+    if not isinstance(nonce, (bytes, bytearray)) or len(nonce) != NONCE_BYTES:
+        raise ValueError(f"nonce must be {NONCE_BYTES} bytes")
+    return hmac.new(token.encode("utf-8"), bytes(nonce), sha256).digest()
+
+
+def verify_response(token: str, nonce: bytes, response: bytes) -> bool:
+    """Constant-time check that ``response`` matches the expected HMAC."""
+    expected = compute_response(token, nonce)
+    if not isinstance(response, (bytes, bytearray)):
+        return False
+    return hmac.compare_digest(expected, bytes(response))