Add operations layer + USB Phase 2 chain (rounds 22-47)

Lands the full operations / admin layer plus the USB passthrough
chain that grew across rounds 22-47.

Operations layer (rounds 22-29):
- Folder sync (additive mirror) + coturn TURN config bundle
- REST API hardening: bearer auth + per-IP rate limit + audit hook +
  Prometheus /metrics + browser dashboard at /dashboard
- Multi-host admin console (parallel poll + broadcast) persisted to
  ~/.je_auto_control/admin_hosts.json (mode 0600)
- Tamper-evident audit log: SHA-256 hash chain + verify_chain()
- WebRTC packet inspector: rolling stats window + summary statistics
- USB device enumeration (read-only, cross-platform)
- System diagnostics CLI + REST + GUI tab
- Web admin dashboard (vanilla JS, sessionStorage token)

Test infrastructure + CI (rounds 30-31):
- Convert per-round smoke scripts into pytest under
  test/unit_test/headless/
- Add .github/workflows/quality.yml: ruff + bandit + pytest matrix
  (Windows 3.10/3.11/3.12)
- Pin lint/test deps in dev_requirements.txt
- Bandit B105 false-positive fix: exclude language_wrapper dicts via
  pyproject.toml [tool.bandit]

Latent bug fixes (rounds 33, 38):
- file_sync._loop no longer marks failed sends as already-synced
  (next-tick retry promise now honored)
- FolderSyncEngine.start() + _RestApiRegistry.start() race fixes
- Extract SessionQualityCache to replace two raw dicts shared between
  asyncio bridge and Qt threads in webrtc_panel

OpenAPI + config bundle (rounds 35-36):
- /openapi.json (auth-gated) generated from live route table
- /docs Swagger UI shell (sessionStorage bearer)
- Drift test catches new routes added without metadata
- ConfigBundleExporter / ConfigBundleImporter: 8-file allowlist,
  atomic write with .bak.<ts> backups, version-validated import

USB hotplug + Phase 2 chain (rounds 34, 37, 39-47):
- UsbHotplugWatcher: bounded ring buffer + sequence-numbered events
- Wire-level protocol (10 opcodes, 16 KiB cap, CREDIT-based flow
  control) over a WebRTC usb DataChannel
- Host-side UsbPassthroughSession with full CTRL/BULK/INT dispatch
- LibusbBackend with full transfers (Linux end-to-end)
- Viewer-side UsbPassthroughClient (blocking open / control_transfer
  / bulk_transfer / interrupt_transfer / close, outbound credit waits)
- Persistent UsbAcl (default deny, mode 0600) + host-side prompt
  QDialog with cross-thread bridge
- WinusbBackend (full ctypes wiring, hardware-unverified)
- IokitBackend skeleton (NotImplementedError pending pyobjc work)
- Audit-log integration for every ACL decision
- Feature flag (default off): enable_usb_passthrough(True) or
  JE_AUTOCONTROL_USB_PASSTHROUGH=1
- Test-stability fixes for two pre-existing flakes
  (test_destructive_confirmation_blocks elicitation typo +
  test_remote_desktop_websocket._wait_until budget bumps)

Verified: ruff clean, bandit zero issues, headless suite 605 passed
/ 7 skipped (cross-platform + aiortc-gated) / 0 failed across three
consecutive runs.

Author: JE-Chen

.github/workflows/quality.yml

@@ -0,0 +1,79 @@
+name: AutoControl Code Quality
+
+# Static analysis (ruff, bandit) plus the headless pytest suite added in
+# rounds 22-30. Decoupled from the existing dev/stable workflows, which
+# run legacy standalone test scripts and exist for hardware integration
+# coverage on Windows runners.
+
+on:
+  push:
+    branches: [ "dev", "main", "stable" ]
+  pull_request:
+    branches: [ "dev", "main", "stable" ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install ruff
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Run ruff
+        run: ruff check je_auto_control/
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install bandit
+        run: |
+          python -m pip install --upgrade pip
+          pip install bandit
+
+      - name: Run bandit (recursive, skip tests + i18n dicts)
+        run: bandit -r je_auto_control/ -c pyproject.toml
+
+  pytest-headless:
+    runs-on: windows-2022
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.10", "3.11", "3.12" ]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip wheel
+          pip install -r dev_requirements.txt
+          pip install -e .
+
+      - name: Run headless pytest suite
+        run: pytest test/unit_test/headless/ -v --tb=short --timeout=120

dev_requirements.txt

@@ -8,3 +8,9 @@ PySide6==6.11.0
 qt-material==2.17
 mss==10.2.0
 defusedxml==0.7.1
+
+# Quality tooling — used by .github/workflows/quality.yml and locally.
+ruff==0.15.9
+bandit==1.9.4
+pytest==9.0.2
+pytest-timeout==2.4.0

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

@@ -0,0 +1,251 @@
+============================================================
+USB Passthrough — Operator Guide
+============================================================
+
+Step-by-step recipe for getting a USB device on a host machine to
+respond to traffic from a remote viewer. Assumes Phase 2a.1 (current
+shipping state) — host-side end-to-end works on Linux libusb; Windows
+WinUSB is hardware-unverified; macOS IOKit is not yet implemented.
+
+If you're a security reviewer instead of an operator, you want
+:doc:`usb_passthrough_security_review`. If you're a developer wanting
+the protocol details, :doc:`usb_passthrough_design`.
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+Prerequisites
+=============
+
+On the **host** (the machine with the physical USB device):
+
+- Python 3.10+ with AutoControl installed.
+- The optional ``webrtc`` extra: ``pip install je_auto_control[webrtc]``.
+- ``pyusb`` installed if you want the libusb backend:
+  ``pip install pyusb``.
+- The USB device the viewer will use, plugged in.
+- Per-OS setup (see *Driver setup* below).
+
+On the **viewer** (the remote machine that will use the device):
+
+- Python 3.10+ with AutoControl installed.
+- Network reach to the host's REST API port (default 9939) **and** to
+  the WebRTC signalling / TURN endpoints if the viewer is behind NAT.
+- The host's bearer token (operator hands it over out-of-band).
+
+
+Driver setup (per OS)
+=====================
+
+Linux (libusb)
+--------------
+
+The libusb backend is the most-tested path today. Steps:
+
+1. Install ``libusb-1.0`` development files (e.g. ``apt install
+   libusb-1.0-0``).
+2. Add a ``udev`` rule so the AutoControl host process can claim the
+   device without root. Example for a YubiKey 5
+   (vendor ``1050``, product ``0407``)::
+
+       # /etc/udev/rules.d/99-autocontrol-usb.rules
+       SUBSYSTEM=="usb", ATTRS{idVendor}=="1050",
+         ATTRS{idProduct}=="0407", MODE="0660",
+         GROUP="plugdev"
+
+   Then ``sudo udevadm control --reload && sudo udevadm trigger``.
+3. Make sure your AutoControl user is in ``plugdev``.
+4. If the device is a HID, AutoControl's libusb wrapper detaches
+   ``usbhid`` on ``open`` and re-attaches on ``close``. Don't be
+   alarmed if your local keyboard input briefly hiccups during a
+   claim of a HID device.
+
+Windows (WinUSB) — *hardware-unverified*
+----------------------------------------
+
+The ctypes wiring exists but has not been validated against real
+hardware. Treat as alpha. Steps:
+
+1. Use `Zadig <https://zadig.akeo.ie/>`_ or libwdi to associate the
+   target device with the WinUSB driver. Do not do this for devices
+   the host OS already manages (printers, hubs, keyboards).
+2. After binding, the device should appear in
+   ``WinusbBackend().list()``.
+3. Hardware testing is required before relying on transfers. See
+   the security review checklist for the expected test matrix.
+
+macOS (IOKit) — *not yet implemented*
+-------------------------------------
+
+The skeleton exists; ``IokitBackend()`` constructs but ``list`` /
+``open`` raise ``NotImplementedError``. Track Phase 2c.
+
+
+Enabling the feature
+====================
+
+USB passthrough is **off by default**. Two ways to opt in:
+
+- Environment variable, picked up at process start::
+
+      export JE_AUTOCONTROL_USB_PASSTHROUGH=1
+      python -m je_auto_control.cli start-rest
+
+- Programmatic, in your bootstrap script (overrides env)::
+
+      from je_auto_control.utils.usb.passthrough import enable_usb_passthrough
+      enable_usb_passthrough(True)
+
+Confirm with :func:`is_usb_passthrough_enabled`::
+
+      from je_auto_control.utils.usb.passthrough import is_usb_passthrough_enabled
+      assert is_usb_passthrough_enabled()
+
+
+ACL setup
+=========
+
+The ACL defaults to ``"deny"`` so a viewer cannot claim a device the
+operator hasn't approved. Add per-device rules:
+
+1. From the GUI — the *USB* tab on the host shows the prompt dialog
+   on first OPEN of an unknown device. Tick *Remember this decision*
+   to persist a permanent allow rule.
+2. From Python::
+
+      from je_auto_control.utils.usb.passthrough import (
+          AclRule, UsbAcl,
+      )
+      acl = UsbAcl()
+      acl.add_rule(AclRule(
+          vendor_id="1050", product_id="0407",
+          serial=None,            # match any serial
+          label="YubiKey 5",
+          allow=True,
+          prompt_on_open=False,   # silent allow once approved
+      ))
+
+3. By editing ``~/.je_auto_control/usb_acl.json`` directly. The file
+   is permission-checked (mode ``0600`` on POSIX). Bad JSON or an
+   unknown ``version`` falls back to default-deny.
+
+Decision precedence:
+
+- First matching rule wins. ``prompt_on_open=True`` means re-ask the
+  operator each time, even if the rule is ``allow=True``.
+- If no rule matches, the file's ``default`` (``"deny"`` out of the
+  box) applies.
+
+
+Starting the host
+=================
+
+The host needs the REST API running (so the viewer can enumerate)
+and a WebRTC peer connection to the viewer (so transfers can flow).
+
+REST::
+
+    from je_auto_control.utils.rest_api import start_rest_api_server
+    server = start_rest_api_server(host="0.0.0.0", port=9939)
+    print("Bearer:", server.token)
+
+WebRTC: use the existing remote desktop pipeline (see
+:doc:`operations_layer_doc`) to bring up a session. The viewer's
+``UsbPassthroughClient`` then plugs into the negotiated DataChannel.
+
+
+Viewer-side: claim and transfer
+===============================
+
+Enumerate
+---------
+
+From Python::
+
+    import urllib.request, json
+    req = urllib.request.Request(
+        "http://host:9939/usb/devices",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    with urllib.request.urlopen(req) as r:
+        body = json.loads(r.read())
+    for d in body["devices"]:
+        print(d["vendor_id"], d["product_id"], d.get("product"))
+
+Or via the *USB Browser* GUI tab on the viewer side: paste the host's
+REST URL + token, click *Fetch devices*.
+
+Open + transfer
+---------------
+
+::
+
+    from je_auto_control.utils.usb.passthrough import (
+        UsbPassthroughClient, encode_frame, decode_frame,
+    )
+
+    # `data_channel` is your WebRTC RTCDataChannel for the "usb" channel.
+    def send(frame):
+        data_channel.send(encode_frame(frame))
+
+    client = UsbPassthroughClient(send_frame=send)
+    # Wire the channel's on-message callback:
+    data_channel.on("message")(lambda raw: client.feed_frame(decode_frame(raw)))
+
+    handle = client.open(vendor_id="1050", product_id="0407")
+    response = handle.control_transfer(
+        bm_request_type=0xC0, b_request=6, w_value=0x0100, length=18,
+    )
+    print("device descriptor:", response.hex())
+    handle.close()
+    client.shutdown()
+
+Errors:
+
+- ``UsbClientTimeout`` — the host took longer than ``reply_timeout_s``
+  (default 10s) to respond. Check the network / host process.
+- ``UsbClientError`` — the host replied with ``{ok: false, error: ...}``.
+  The most common case is *denied by ACL policy* — go check the
+  prompt dialog or the ACL rule on the host.
+- ``UsbClientClosed`` — the client or its handle was already shut down.
+
+
+Troubleshooting matrix
+======================
+
+==========================================  =====================================================
+Symptom                                     Likely cause / fix
+==========================================  =====================================================
+``open`` returns ``denied by ACL policy``   No allow rule + ``default = deny``. Add a rule or
+                                            enable a prompt callback.
+``open`` returns ``no device matches``      Device not enumerated. Check ``UsbHotplugWatcher``
+                                            output or run ``list_usb_devices()`` directly.
+                                            On Windows, confirm Zadig binding.
+``credit exhausted`` on transfer            Viewer sent more frames than the host's
+                                            ``initial_credits`` window allows. Either lower
+                                            request rate or raise ``initial_credits`` on
+                                            the session.
+Transfer ``UsbClientTimeout``               Host process is busy or the WebRTC channel is
+                                            broken. Inspect the *Packet Inspector* tab for
+                                            RTT / packet loss.
+After OPEN, host's keyboard stops working   Linux: a HID device was claimed and
+                                            ``usbhid`` was detached. The driver re-attaches
+                                            on CLOSE; if not, ``udevadm trigger`` to recover.
+Audit chain shows ``broken_at_id``          Someone edited ``audit.db`` directly. Restore
+                                            from a backup; investigate.
+==========================================  =====================================================
+
+
+What is *not* shipped yet
+=========================
+
+- WebRTC viewer GUI does not auto-wire the ``usb`` DataChannel — the
+  *USB Browser* tab's *Open* button shows a "not yet wired" message.
+  You can drive the protocol from Python today.
+- Windows WinUSB transfer methods are written but not validated
+  against real hardware. Do not use in production.
+- macOS IOKit backend is unimplemented (Phase 2c).
+- Phase 2e external security review has not been signed; the feature
+  flag must remain explicit opt-in.