Wire USB passthrough over WebRTC channel, add resume tokens and hotplug refresh

Make USB passthrough work cross-machine and survive reconnects.

- WebRTC usb DataChannel: UsbChannelHost / UsbChannelClient adapters
  bridge the protocol over an aiortc RTCDataChannel (mirroring the file
  channel). webrtc_host creates the "usb" channel gated on viewer auth +
  the feature flag; webrtc_viewer exposes viewer.usb_client(). Adapters
  are transport-decoupled and unit-tested with a fake channel.
- Claim resume: OPENED carries a resume_token; a reconnecting viewer
  sends RESUME to re-bind a claim the host session still holds, keeping
  device state and claim_id intact (new 0x0A RESUME opcode).
- USB Sharing panel auto-refreshes its local device table from the
  hotplug watcher when enabled.

Docs updated; i18n across four languages; import je_auto_control stays
Qt-free and aiortc-free.

Author: JE-Chen

docs/source/Eng/doc/operations_layer/usb_passthrough_design.rst

@@ -77,6 +77,17 @@ Channel
 
 A dedicated WebRTC ``DataChannel`` named ``usb`` per session, with
 ``ordered=True`` and ``maxRetransmits=None`` (full reliability).
+
+**Wired up:** the host (``webrtc_host``) creates the ``usb`` channel and
+feeds it to a session through ``UsbChannelHost`` (gated on viewer
+authentication + the feature flag); the viewer (``webrtc_viewer``)
+wraps the incoming channel in ``UsbChannelClient``, exposed via
+``viewer.usb_client()`` for ``list_devices`` / ``open`` / ``resume``.
+The adapters are transport-decoupled and unit-tested with a fake
+channel (see ``test_usb_webrtc_channel``). **Reconnect:** OPENED carries
+a ``resume_token``; if the host session outlives the viewer's transport
+drop, the viewer sends ``RESUME{resume_token}`` to re-bind the existing
+claim — keeping device state and ``claim_id`` — instead of re-OPENing.
 Bulk and interrupt USB transfers tolerate the latency far better
 than they tolerate loss; the existing video/audio channels already
 demonstrate that the underlying SCTP transport handles ordered
@@ -130,6 +141,7 @@ Op (hex)          Direction                                  Purpose
 ``0x07 CREDIT``   viewer ↔ host                              Backpressure window update
 ``0x08 CLOSE``    viewer → host                              Release the claim
 ``0x09 CLOSED``   host → viewer                              Acknowledgement (or unsolicited on host-side disconnect)
+``0x0A RESUME``   viewer → host                              Re-bind an existing claim after reconnect via resume_token
 ``0xFF ERROR``    either                                     Protocol error / unsupported op
 ================  =========================================  ==============
 

docs/source/Eng/doc/operations_layer/usb_passthrough_operator_guide.rst

@@ -279,11 +279,13 @@ What is *not* shipped yet
   one (a descriptor read proves the full stack). The *USB Browser* tab's
   *Open* button now also works against a **localhost** target via the
   same loopback path.
-- Cross-machine open still needs the WebRTC ``usb`` DataChannel, which
-  the viewer GUI does not yet auto-wire — against a remote host the
-  *Open* button shows a "not yet wired" message. You can drive the
-  protocol from Python today (including
-  ``UsbPassthroughClient.list_devices()`` over the channel).
+- Cross-machine transport is now wired: the WebRTC host creates a
+  ``usb`` DataChannel and the viewer exposes ``viewer.usb_client()``
+  (a ``UsbChannelClient`` with ``list_devices`` / ``open`` / ``resume``).
+  Drive it from Python today over a live WebRTC session. The simple
+  *USB Browser* / *USB Sharing* panels still use the local loopback +
+  REST paths; auto-wiring those panels to a live WebRTC viewer session
+  is the remaining GUI integration step.
 - Windows WinUSB and macOS IOKit transfer paths are written but not yet
   validated against real hardware. Do not use in production until the
   Phase 2e hardware test matrix passes.

docs/source/Zh/doc/operations_layer/usb_passthrough_design.rst

@@ -70,6 +70,16 @@ Channel
 
 每個 session 一條專用的 WebRTC ``DataChannel``\ ，名稱 ``usb``\ ，
 ``ordered=True`` 且 ``maxRetransmits=None``\ （完全可靠傳輸）。
+
+**已串接：** host（``webrtc_host``）會建立 ``usb`` channel 並以
+``UsbChannelHost`` 餵給 session（綁定 viewer 認證 + feature flag）；
+viewer（``webrtc_viewer``）收到該 channel 後以 ``UsbChannelClient``
+包裝，透過 ``viewer.usb_client()`` 供上層呼叫 ``list_devices`` /
+``open`` / ``resume``。adapter 與 transport 解耦，可用 fake channel
+單測（見 ``test_usb_webrtc_channel``）。**斷線續租：** OPENED 會帶
+``resume_token``；若 host session 撐過 viewer 的 transport 中斷，
+viewer 重連後送 ``RESUME{resume_token}`` 即可重綁原 claim、保留裝置
+狀態，不需重新 OPEN。
 USB 的 bulk 與 interrupt 傳輸對延遲的容忍度遠高於對遺失的容忍度；
 既有的 video/audio channel 也已示範底層 SCTP 傳輸足以承擔有序可靠
 串流。
@@ -118,6 +128,7 @@ Op (hex)          方向                                   用途
 ``0x07 CREDIT``   viewer ↔ host                          Backpressure 視窗更新
 ``0x08 CLOSE``    viewer → host                          釋放 claim
 ``0x09 CLOSED``   host → viewer                          確認（host 端斷線時也可主動發出）
+``0x0A RESUME``   viewer → host                          重連後以 resume_token 重新綁定既有 claim
 ``0xFF ERROR``    雙向                                   協定錯誤／不支援 op
 ================  =====================================  ======================
 

docs/source/Zh/doc/operations_layer/usb_passthrough_operator_guide.rst

@@ -258,9 +258,12 @@ OPEN 後 host 鍵盤停止運作                   Linux：HID 裝置被 claim 
   做 ACL 允許／封鎖；右側經 in-process channel 列出分享裝置並 *開啟*
   其中一個（讀描述元即證明整條堆疊運作）。*USB Browser* 分頁的 *Open*
   按鈕現在對 **localhost** 目標也會走同一條 loopback 路徑。
-- 跨機器開啟仍需 WebRTC ``usb`` DataChannel，viewer GUI 尚未自動串接 —
-  對遠端主機按 *Open* 會顯示「尚未串接」訊息。今天可以從 Python 驅動
-  協定（含經 channel 的 ``UsbPassthroughClient.list_devices()``\ ）。
+- 跨機器 transport 已串接：WebRTC host 會建立 ``usb`` DataChannel，
+  viewer 以 ``viewer.usb_client()`` 暴露 ``UsbChannelClient``\ （含
+  ``list_devices`` / ``open`` / ``resume``\ ）。今天即可在 WebRTC session
+  上從 Python 驅動。簡易的 *USB Browser* / *USB 分享* 面板目前仍走本機
+  loopback + REST；把面板自動接到 live WebRTC viewer session 是剩餘的
+  GUI 整合步驟。
 - Windows WinUSB 與 macOS IOKit 的 transfer 路徑已寫但尚未對實體硬體
   驗證。在 Phase 2e 硬體測試矩陣通過前請勿用於 production。
 - Phase 2e 外部安全審查尚未簽核；feature flag 必須維持顯式 opt-in。

je_auto_control/gui/language_wrapper/english.py

@@ -155,6 +155,7 @@
     "usb_share_acl_exported": "ACL exported.",
     "usb_share_acl_imported": "Imported {count} rule(s).",
     "usb_share_acl_import_failed": "ACL I/O failed: {error}",
+    "usb_share_auto_refresh": "Auto-refresh (hotplug)",
 
     # Inspector tab
     "inspector_metrics_group": "Rolling metrics",

je_auto_control/gui/language_wrapper/japanese.py

@@ -153,6 +153,7 @@
     "usb_share_acl_exported": "ACL をエクスポートしました。",
     "usb_share_acl_imported": "{count} 件のルールをインポートしました。",
     "usb_share_acl_import_failed": "ACL 入出力に失敗：{error}",
+    "usb_share_auto_refresh": "自動更新(ホットプラグ)",
 
     # 監視タブ
     "inspector_metrics_group": "集約メトリクス",

je_auto_control/gui/language_wrapper/simplified_chinese.py

@@ -144,6 +144,7 @@
     "usb_share_acl_exported": "ACL 已导出。",
     "usb_share_acl_imported": "已导入 {count} 条规则。",
     "usb_share_acl_import_failed": "ACL 读写失败：{error}",
+    "usb_share_auto_refresh": "自动刷新(热插拔)",
 
     # 包监测分页
     "inspector_metrics_group": "汇总指标",

je_auto_control/gui/language_wrapper/traditional_chinese.py

@@ -145,6 +145,7 @@
     "usb_share_acl_exported": "ACL 已匯出。",
     "usb_share_acl_imported": "已匯入 {count} 條規則。",
     "usb_share_acl_import_failed": "ACL 讀寫失敗：{error}",
+    "usb_share_auto_refresh": "自動刷新(熱插拔)",
 
     # 封包監測分頁
     "inspector_metrics_group": "彙整指標",

je_auto_control/gui/usb_passthrough_panel.py

@@ -19,11 +19,11 @@
 
 from typing import Any, Callable, List, Optional
 
-from PySide6.QtCore import QObject, QThread, Signal
+from PySide6.QtCore import QObject, QThread, QTimer, Signal
 from PySide6.QtWidgets import (
-    QFileDialog, QGroupBox, QHBoxLayout, QHeaderView, QLabel, QLineEdit,
-    QMessageBox, QPushButton, QTableWidget, QTableWidgetItem, QVBoxLayout,
-    QWidget,
+    QCheckBox, QFileDialog, QGroupBox, QHBoxLayout, QHeaderView, QLabel,
+    QLineEdit, QMessageBox, QPushButton, QTableWidget, QTableWidgetItem,
+    QVBoxLayout, QWidget,
 )
 
 from je_auto_control.gui._i18n_helpers import TranslatableMixin
@@ -37,6 +37,7 @@
     export_acl_to_file, import_acl_from_file,
 )
 from je_auto_control.utils.usb.usb_devices import list_usb_devices
+from je_auto_control.utils.usb.usb_watcher import default_usb_watcher
 
 
 def _t(key: str) -> str:
@@ -84,6 +85,12 @@ def __init__(self, parent: Optional[QWidget] = None, *,
         self._thread: Optional[QThread] = None
         self._host_badge = _StatusBadge()
         self._viewer_status = QLabel("")
+        self._auto_check = QCheckBox()
+        self._auto_check.toggled.connect(self._on_auto_toggled)
+        self._hotplug_timer = QTimer(self)
+        self._hotplug_timer.setInterval(2000)
+        self._hotplug_timer.timeout.connect(self._poll_hotplug)
+        self._last_seen_seq = 0
         self._local_table = _make_table(5)
         self._shared_table = _make_table(4)
         self._remote_url = QLineEdit("http://127.0.0.1:9939")
@@ -133,6 +140,8 @@ def _build_host_section(self) -> QWidget:
         acl_row.addWidget(refresh_btn)
         acl_row.addWidget(allow_btn)
         acl_row.addWidget(block_btn)
+        self._tr(self._auto_check, "usb_share_auto_refresh")
+        acl_row.addWidget(self._auto_check)
         layout.addLayout(acl_row)
         io_row = QHBoxLayout()
         export_btn = self._tr(QPushButton(), "usb_share_export_acl")
@@ -251,6 +260,25 @@ def _refresh_local_devices(self) -> None:
             for col, text in enumerate(cells):
                 self._local_table.setItem(row, col, QTableWidgetItem(text))
 
+    def _on_auto_toggled(self, on: bool) -> None:
+        watcher = default_usb_watcher()
+        if on:
+            watcher.start()
+            self._hotplug_timer.start()
+        else:
+            self._hotplug_timer.stop()
+            watcher.stop()
+
+    def _poll_hotplug(self) -> None:
+        watcher = default_usb_watcher()
+        if not watcher.is_running:
+            return
+        events = watcher.recent_events(since=self._last_seen_seq, limit=20)
+        if not events:
+            return
+        self._last_seen_seq = events[-1]["seq"]
+        self._refresh_local_devices()
+
     def _set_policy(self, allow: bool) -> None:
         row = _selected_row(self._local_table)
         if row is None:
@@ -408,6 +436,9 @@ def _cell(table: QTableWidget, row: int, col: int) -> str:
         return "" if text == "-" else text
 
     def closeEvent(self, event) -> None:  # noqa: N802  # Qt override name
+        self._hotplug_timer.stop()
+        if self._auto_check.isChecked():
+            default_usb_watcher().stop()
         self._disable_sharing()
         super().closeEvent(event)
 

je_auto_control/utils/remote_desktop/webrtc_host.py

@@ -99,6 +99,8 @@ def __init__(self, *, token: str,  # NOSONAR python:S107  # public constructor;
         self._mic_receiver = None  # Optional[MicUplinkReceiver]
         self._files_channel = None
         self._files_receiver = None  # Optional[FileTransferReceiver]
+        self._usb_channel = None
+        self._usb_host = None  # Optional[UsbChannelHost]
         self._on_file_received: Optional[Callable] = None
         self._on_viewer_video_frame: Optional[Callable] = None
         self._viewer_video_task = None
@@ -187,6 +189,8 @@ async def _async_create_offer(self) -> str:
         self._wire_mic_channel(self._mic_channel)
         self._files_channel = self._pc.createDataChannel("files")
         self._wire_files_channel(self._files_channel)
+        self._usb_channel = self._pc.createDataChannel("usb")
+        self._wire_usb_channel(self._usb_channel)
         self._wire_state_handlers(self._pc)
         self._wire_viewer_video_handler(self._pc)
         offer = await self._pc.createOffer()
@@ -378,6 +382,36 @@ def _on_message(message) -> None:
                 on_done=self._on_file_done,
             )
 
+    def _wire_usb_channel(self, channel) -> None:
+        """Carry USB passthrough over the ``usb`` DataChannel.
+
+        Gated on viewer authentication *and* the global passthrough flag
+        (default off); per-device access is governed by the host's
+        ``UsbAcl`` (default deny). The session is built lazily on the
+        first frame so a host without the USB backend installed pays
+        nothing until a viewer actually uses the channel.
+        """
+        from je_auto_control.utils.usb.passthrough import UsbChannelHost
+
+        def _factory():
+            from je_auto_control.utils.usb.passthrough import (
+                UsbAcl, UsbPassthroughSession, default_passthrough_backend,
+            )
+            return UsbPassthroughSession(
+                default_passthrough_backend(), acl=UsbAcl(),
+                viewer_id=getattr(self, "_viewer_id", None),
+            )
+
+        def _enabled() -> bool:
+            from je_auto_control.utils.usb.passthrough import (
+                is_usb_passthrough_enabled,
+            )
+            return bool(self._authenticated) and is_usb_passthrough_enabled()
+
+        self._usb_host = UsbChannelHost(
+            channel, session_factory=_factory, enabled_check=_enabled,
+        )
+
     def set_file_received_callback(self, callback) -> None:
         """Register a sync callback ``cb(path: Path)`` for completed transfers."""
         self._on_file_received = callback