Add Phase 6 hardening: encryption, regression, semantic replay, resume, WoL

Six new subsystems landing in one batch:

- 6.1 Wake-on-LAN GUI: right-click a Quick Connect recent entry to
  send a magic packet; MAC + broadcast persisted in AddressBook.
- 6.2 EncryptedJpegSequenceRecorder: AES-256-GCM per-frame with a
  HMAC-SHA256-signed manifest; key derivation from passphrase
  (PBKDF2 600k SHA-256) and round-trip + tamper-detection tests.
- 6.3 Visual regression framework: PIL-only golden image compare
  with per-pixel threshold, region masks, and pytest-friendly
  DiffResult.write_diff().
- 6.4 Semantic recording enrichment: walk a recording, ask the
  accessibility tree for the smallest element covering each click,
  attach role/name/app_name as an `anchor` payload.
- 6.6 Resume tokens: in-memory TTL store; host ships a one-shot
  token inside AUTH_OK, viewer reconnects with it and skips the
  approval popup while keeping its saved permission (view-only
  preserves across the reconnect).
- 6.7 Replay-anywhere: at replay, use the anchor to look up the
  current element via the accessibility tree, rewrite x/y, fall
  back to the recorded coordinates when lookup fails.

41 new headless tests, ruff clean, complexity all ≤ 10.

Author: JE-Chen

je_auto_control/gui/language_wrapper/english.py

@@ -899,6 +899,10 @@
     "rd_quick_publish_signaling": (
         "Publish via signaling (let viewers connect by 9-digit ID)"
     ),
+    "rd_quick_wake_host": "Wake host (WoL)",
+    "rd_quick_edit_mac": "Edit MAC address…",
+    "rd_quick_wol_mac_prompt": "MAC address (AA:BB:CC:DD:EE:FF):",
+    "rd_quick_wol_sent": "Magic packet sent to {mac}.",
     "rd_host_security_warning": (
         "WARNING: anyone with the host:port and token gets full mouse / "
         "keyboard control of this machine. Default bind is 127.0.0.1; "

je_auto_control/gui/language_wrapper/japanese.py

@@ -899,6 +899,10 @@
     "rd_quick_publish_signaling": (
         "シグナリングに公開（ビューアが 9 桁 ID で接続できるようにする）"
     ),
+    "rd_quick_wake_host": "ホストを起動（WoL）",
+    "rd_quick_edit_mac": "MAC アドレスを編集…",
+    "rd_quick_wol_mac_prompt": "MAC アドレス（AA:BB:CC:DD:EE:FF）:",
+    "rd_quick_wol_sent": "マジックパケットを {mac} へ送信しました。",
     "rd_host_security_warning": (
         "警告：host:port と token を知る相手は、このマシンのマウス／キーボードを"
         "完全に操作できます。既定は 127.0.0.1。外部公開は SSH トンネルか"

je_auto_control/gui/language_wrapper/simplified_chinese.py

@@ -885,6 +885,10 @@
     "rd_quick_approval_view_only": "仅检视",
     "rd_quick_approval_deny": "拒绝",
     "rd_quick_publish_signaling": "发布到 signaling（让对方用 9 位数 ID 连线）",
+    "rd_quick_wake_host": "唤醒主机（WoL）",
+    "rd_quick_edit_mac": "编辑 MAC 地址…",
+    "rd_quick_wol_mac_prompt": "MAC 地址（AA:BB:CC:DD:EE:FF）：",
+    "rd_quick_wol_sent": "Magic packet 已发送到 {mac}。",
     "rd_host_security_warning": (
         "警告：取得本机 host:port 与 token 的人，可以完全控制本机的鼠标／键盘。"
         "默认仅绑 127.0.0.1；要对外请透过 SSH tunnel 或可信的 VPN。"

je_auto_control/gui/language_wrapper/traditional_chinese.py

@@ -888,6 +888,10 @@
     "rd_quick_approval_view_only": "僅檢視",
     "rd_quick_approval_deny": "拒絕",
     "rd_quick_publish_signaling": "發布到 signaling（讓對方用 9 位數 ID 連線）",
+    "rd_quick_wake_host": "喚醒主機（WoL）",
+    "rd_quick_edit_mac": "編輯 MAC 位址…",
+    "rd_quick_wol_mac_prompt": "MAC 位址（AA:BB:CC:DD:EE:FF）：",
+    "rd_quick_wol_sent": "Magic packet 已送出到 {mac}。",
     "rd_host_security_warning": (
         "警告：取得本機 host:port 與 token 的人，可以完全控制本機的滑鼠／鍵盤。"
         "預設只綁 127.0.0.1；要對外請透過 SSH tunnel 或可信的 VPN。"

je_auto_control/gui/remote_desktop/connection_screen.py

@@ -21,8 +21,8 @@
 from PySide6.QtCore import Qt, QTimer, Signal
 from PySide6.QtGui import QGuiApplication, QImage
 from PySide6.QtWidgets import (
-    QGroupBox, QHBoxLayout, QLabel, QLineEdit, QListWidget, QListWidgetItem,
-    QMessageBox, QPushButton, QVBoxLayout, QWidget,
+    QGroupBox, QHBoxLayout, QInputDialog, QLabel, QLineEdit, QListWidget,
+    QListWidgetItem, QMenu, QMessageBox, QPushButton, QVBoxLayout, QWidget,
 )
 
 from je_auto_control.gui._i18n_helpers import TranslatableMixin
@@ -42,6 +42,9 @@
 )
 from je_auto_control.utils.remote_desktop.host_id import format_host_id
 from je_auto_control.utils.remote_desktop.registry import registry
+from je_auto_control.utils.remote_desktop.wake_on_lan import (
+    send_magic_packet,
+)
 
 _HOST_ID_CSS = (
     "font-family: 'Consolas', 'Menlo', 'Courier New', monospace; "
@@ -118,6 +121,11 @@ def __init__(self, parent: Optional[QWidget] = None) -> None:
         self._connect_token.setEchoMode(QLineEdit.EchoMode.Password)
         self._recent = QListWidget()
         self._recent.itemActivated.connect(self._on_recent_activated)
+        # Phase 6.1: right-click a recent entry → "Wake host" via
+        # build_magic_packet / send_magic_packet (the MAC is stored in
+        # AddressBook when the operator saved it for a previous session).
+        self._recent.setContextMenuPolicy(Qt.ContextMenuPolicy.CustomContextMenu)
+        self._recent.customContextMenuRequested.connect(self._on_recent_menu)
         self._start_btn: Optional[QPushButton] = None
         self._stop_btn: Optional[QPushButton] = None
         self._connect_btn: Optional[QPushButton] = None
@@ -552,6 +560,80 @@ def _on_recent_activated(self, item: QListWidgetItem) -> None:
         target = item.data(Qt.ItemDataRole.UserRole) or item.text()
         self._connect_target.setText(str(target))
 
+    def _on_recent_menu(self, pos) -> None:
+        """Right-click menu on the Recent list: edit MAC, send WoL."""
+        item = self._recent.itemAt(pos)
+        if item is None:
+            return
+        host_id = str(item.data(Qt.ItemDataRole.UserRole) or item.text())
+        entry = self._find_address_book_entry(host_id)
+        menu = QMenu(self._recent)
+        wake = menu.addAction(_t("rd_quick_wake_host"))
+        edit = menu.addAction(_t("rd_quick_edit_mac"))
+        chosen = menu.exec(self._recent.mapToGlobal(pos))
+        if chosen is wake:
+            self._send_wake_on_lan(entry, host_id)
+        elif chosen is edit:
+            self._edit_recent_mac(entry, host_id)
+
+    def _find_address_book_entry(self, host_id: str):
+        for entry in self._book.list_entries():
+            if entry.get("host_id") == host_id:
+                return entry
+        return None
+
+    def _send_wake_on_lan(self, entry, host_id: str) -> None:
+        mac = (entry or {}).get("mac_address") if entry else None
+        if not mac:
+            mac, ok = QInputDialog.getText(
+                self, _t("rd_quick_wake_host"),
+                _t("rd_quick_wol_mac_prompt"),
+            )
+            if not ok or not mac:
+                return
+            self._save_mac_to_book(host_id, mac)
+        broadcast = (entry or {}).get("broadcast_address") if entry else None
+        try:
+            send_magic_packet(
+                mac, broadcast=broadcast or "255.255.255.255",
+            )
+        except (OSError, ValueError) as error:
+            QMessageBox.warning(
+                self, _t("rd_quick_wake_host"), str(error),
+            )
+            return
+        QMessageBox.information(
+            self, _t("rd_quick_wake_host"),
+            _t("rd_quick_wol_sent").replace("{mac}", mac),
+        )
+
+    def _edit_recent_mac(self, entry, host_id: str) -> None:
+        current = (entry or {}).get("mac_address") if entry else ""
+        mac, ok = QInputDialog.getText(
+            self, _t("rd_quick_edit_mac"),
+            _t("rd_quick_wol_mac_prompt"),
+            text=str(current or ""),
+        )
+        if not ok or not mac:
+            return
+        self._save_mac_to_book(host_id, mac)
+
+    def _save_mac_to_book(self, host_id: str, mac: str) -> None:
+        """Persist the MAC against the matching AddressBook entry."""
+        for entry in self._book.list_entries():
+            if entry.get("host_id") == host_id:
+                try:
+                    self._book.upsert(
+                        host_id=host_id,
+                        server_url=entry.get("server_url", host_id),
+                        label=entry.get("label", ""),
+                        mac_address=mac,
+                    )
+                except (ValueError, OSError):
+                    return
+                self._refresh_recent()
+                return
+
     # --- status -------------------------------------------------------
 
     def _refresh_status(self) -> None:

je_auto_control/utils/remote_desktop/host.py

@@ -31,6 +31,9 @@
 from je_auto_control.utils.remote_desktop.protocol import (
     AuthenticationError, MessageType, ProtocolError,
 )
+from je_auto_control.utils.remote_desktop.resume_tokens import (
+    ResumeTokenStore,
+)
 from je_auto_control.utils.remote_desktop.transport import (
     MessageChannel, TcpMessageChannel,
 )
@@ -390,21 +393,34 @@ def _authenticate(self) -> None:
             raise AuthenticationError(
                 f"expected AUTH_RESPONSE, got {msg_type.name}"
             )
-        if not self._host._verify_token(nonce, payload):
-            self._channel.send_typed(MessageType.AUTH_FAIL, b"bad token")
-            raise AuthenticationError("bad token")
-        # Host operator gates the session *before* AUTH_OK so the viewer
-        # surfaces the rejection as an AuthenticationError instead of
-        # connecting and then mysteriously disconnecting.
-        permission = self._resolve_permission()
-        if permission == PERMISSION_DENIED:
-            self._channel.send_typed(
-                MessageType.AUTH_FAIL, b"rejected by host",
-            )
-            raise AuthenticationError("rejected by host")
-        self.permission = permission
+        # Phase 6.6: a viewer reconnecting with a valid resume token
+        # signs with that token directly — host short-circuits the
+        # approval popup and reuses the saved permission.
+        resumed = self._host._try_consume_resume(nonce, payload)
+        if resumed is not None:
+            self.permission = resumed
+        else:
+            if not self._host._verify_token(nonce, payload):
+                self._channel.send_typed(MessageType.AUTH_FAIL, b"bad token")
+                raise AuthenticationError("bad token")
+            # Host operator gates the session *before* AUTH_OK so the
+            # viewer surfaces the rejection as an AuthenticationError
+            # instead of connecting and then mysteriously disconnecting.
+            permission = self._resolve_permission()
+            if permission == PERMISSION_DENIED:
+                self._channel.send_typed(
+                    MessageType.AUTH_FAIL, b"rejected by host",
+                )
+                raise AuthenticationError("rejected by host")
+            self.permission = permission
+        # Issue a fresh resume token so the viewer can reconnect
+        # within the store's TTL without the approval popup.
+        resume_token = self._host._resume_store.issue(self.permission)
         ok_payload = json.dumps(
-            {"host_id": self._host.host_id}, ensure_ascii=False,
+            {"host_id": self._host.host_id,
+             "resume_token": resume_token,
+             "resume_ttl": self._host._resume_store.ttl},
+            ensure_ascii=False,
         ).encode("utf-8")
         self._channel.send_typed(MessageType.AUTH_OK, ok_payload)
         self._channel.settimeout(None)
@@ -652,6 +668,9 @@ def __init__(
         self._on_chat = on_chat
         # Phase 4.1: TOTP secret. None disables 2FA (default).
         self._totp_secret = totp_secret
+        # Phase 6.6: in-memory resume tokens — viewer reconnects within
+        # the TTL skip the approval popup and re-use the saved permission.
+        self._resume_store = ResumeTokenStore()
         self._listen_sock: Optional[socket.socket] = None
         self._accept_thread: Optional[threading.Thread] = None
         self._capture_thread: Optional[threading.Thread] = None
@@ -857,6 +876,21 @@ def send_file_to_viewers(self, source_path: str, dest_path: str,
                 )
         return len(clients)
 
+    def _try_consume_resume(self, nonce: bytes,
+                            payload: bytes) -> Optional[str]:
+        """Phase 6.6: find a resume token whose HMAC matches ``payload``.
+
+        Returns the saved permission string and removes the matching
+        token from the store. Returns ``None`` when no token in the
+        store signed this nonce — caller then falls back to the normal
+        ``_verify_token`` path.
+        """
+        for token, perm in self._resume_store.list_active().items():
+            if verify_response(token, nonce, payload):
+                self._resume_store.remove(token)
+                return perm
+        return None
+
     def _verify_token(self, nonce: bytes, payload: bytes) -> bool:
         """Phase 4.2 + 4.1: token / single-use code / TOTP-bound token.