This document is for human contributors and AI coding agents. It defines the layer boundaries, threading model, and coding rules that all contributions must follow. Violations are catalogued at the end.
| Repo | Role |
|---|---|
solo2-python (src/solo2/) |
Hardware abstraction library. Owns all transport code (USB HID, PC/SC, USB bootloader). The only place that imports pyusb, pyscard, fido2, or any other transport-level library. |
solokeys-gui (src/solo_gui/) |
GUI application. Imports solo2 as a library. Must not import transport libraries directly. |
Dependency arrows point downward only. Upper layers must never reach past the layer directly below them.
┌─────────────────────────────────────────────┐
│ Views (tabs/, main_window.py) │ Layer 5 — UI only
│ Reads cached state. Never does I/O. │
├─────────────────────────────────────────────┤
│ Workers (workers/) │ Layer 4 — background I/O
│ QThread helpers. Call solo2 APIs. │
├─────────────────────────────────────────────┤
│ DeviceManager (device_manager.py) │ Layer 3 — session state
│ Long-lived CTAP2 session, PIN-token cache. │ Only fido2 exception lives here.
├─────────────────────────────────────────────┤
│ Models (models/) │ Layer 2 — domain objects
│ Solo2Device, DeviceMonitor, DeviceInfo. │ Thin wrappers over solo2.
├─────────────────────────────────────────────┤
│ solo2 library (separate repo) │ Layer 1 — transport
│ USB HID, PC/SC, bootloader, fido2, pyusb. │
└─────────────────────────────────────────────┘
All transport I/O belongs in solo2-python. The GUI calls into these APIs:
| Transport | solo2 module | GUI entry point |
|---|---|---|
| USB HID (CTAP2/FIDO2) | solo2.hid_backend |
Solo2Device.open_hid_device() |
| PC/SC (CCID applets) | solo2.pcsc |
solo2.pcsc.iter_pcsc_connections() |
| USB bootloader | solo2.discovery |
list_bootloader_descriptors() |
| Device discovery | solo2.discovery |
DeviceWatcher, list_regular_descriptors() |
Workers that talk to CCID applets (PIV, OpenPGP, OATH) must use:
from solo2.pcsc import PCSC_AVAILABLE, PCSC_IMPORT_ERROR, iter_pcsc_connections
for connection in iter_pcsc_connections():
response, sw1, sw2 = connection.transmit(apdu_list)
# ... handle response ...
connection.close()iter_pcsc_connections() handles protocol selection (T=1 preferred, then auto)
internally. Workers must not import smartcard, pyscard, or any other
PC/SC library directly.
Use solo2.discovery.DeviceWatcher (via utils/usb_monitor.py) or the
DeviceMonitor poll timer. Never call usb.core.find() from the GUI layer.
Main thread (Qt event loop)
├── DeviceManager runs on main thread
│ Owns CTAP2 session, PIN-token cache, credential list.
│ Called by workers via direct method calls (thread-safe by design).
│
├── DeviceMonitor runs on main thread
│ QTimer-based poller, calls solo2.discovery APIs every 1 s.
│ USBMonitor (background thread) triggers faster scans.
│
└── QThread workers background threads
PivWorker, GpgWorker, AdminWorker, FirmwareWorker, …
Each creates a temporary PC/SC or HID connection for its task.
Communicate back to the UI via Qt signals only.
Rules:
- Workers must never touch Qt widgets directly.
- Workers must never access
DeviceManager._ctap2or internal CTAP2 state. - Only
DeviceManagermay callDeviceManager.get_pin_retries(),set_pin(),change_pin(),get_credentials()etc. - Views read only cached/already-computed data (no blocking I/O on main thread).
- Background threads must never open HID device handles on Windows (see §8).
Use
list_presence_ids()for presence checks, not fido2 enumeration. - Tab
set_device()methods must not send APDUs. Use a separateload_data()method triggered after the required applet has been selected (see §8 HmacTab).
| Layer | Allowed imports |
|---|---|
| Views | PySide6, solo_gui.models, solo_gui.device_manager |
| Workers | PySide6.QtCore, solo2.*, solo_gui.models |
| DeviceManager | PySide6.QtCore, solo2.*, fido2.* (documented exception) |
| Models | PySide6.QtCore, solo2.* |
| Library | Reason |
|---|---|
usb, usb.core (pyusb) |
Transport owned by solo2.discovery |
smartcard.* (pyscard) |
Transport owned by solo2.pcsc |
fido2.* anywhere except device_manager.py |
State owned by DeviceManager |
These files re-export solo2 types and are not violations:
| File | What it does |
|---|---|
models/device.py |
Re-exports Solo2Device, SoloDevice, DeviceInfo |
hid_backend.py |
Re-exports solo2.hid_backend |
device_transport.py |
Re-exports solo2 transport helpers |
| File | Violation | Severity | Status |
|---|---|---|---|
utils/helpers.py |
from fido2.ctap2 import PinProtocolV1 — dead verify_pin_with_retry() |
Low | Fixed (function deleted) |
utils/usb_monitor.py |
import usb.core — duplicate discovery path |
Medium | Fixed (replaced with DeviceWatcher) |
workers/piv_worker.py |
from smartcard.System import readers |
High | Fixed (replaced with iter_pcsc_connections()) |
workers/gpg_worker.py |
from smartcard.System import readers |
High | Fixed (replaced with iter_pcsc_connections()) |
| File | Import | Reason |
|---|---|---|
device_manager.py |
from fido2.ctap2 import Ctap2, CredentialManagement, ClientPin, CTAPHID |
DeviceManager is the sole owner of the long-lived CTAP2 session with PIN-token caching. This cannot be delegated to a stateless solo2 wrapper. Must never migrate to workers, tabs, helpers, or views. |
| File | Violation | Severity | Fix |
|---|---|---|---|
workers/fido2_worker_simple.py |
from fido2.ctap2.base import Ctap2, Info |
Medium | Migrate CTAP2 calls into DeviceManager methods; this worker should call device_manager.make_credential() etc. |
workers/firmware_worker.py |
from fido2.ctap2 import Ctap2 (inside a function) |
Low | Move into DeviceManager or solo2 helper |
The .deb and .rpm packages contain the PyInstaller onedir GUI payload plus
the PyInstaller native-messaging-host binary. Runtime package installation must
not call pip, require network access, depend on the system Python ABI, or depend
on distro PySide6/Qt6 packages.
| File/area | Role |
|---|---|
solokeys_gui.spec |
Builds the bundled GUI payload used by AppImage, .deb, and .rpm |
native_host.spec |
Builds the bundled native messaging host binary |
packaging/linux/build_package_root.sh |
Installs build deps, runs both PyInstaller specs, copies payload into /usr/lib/solokeys-gui |
packaging/linux/bin/* |
Thin wrappers that launch the bundled binaries from /usr/lib/solokeys-gui |
Only system libraries that are intentionally not bundled, such as libusb, may
remain native package dependencies. Browser manifests, desktop files, icons and
udev rules are still installed as normal package files.
USBMonitor (in utils/usb_monitor.py) runs on all platforms but uses a
different backend depending on the OS:
| Platform | Backend | Why |
|---|---|---|
| Linux/macOS | DeviceWatcher (fido2 enumeration) |
Reads /dev/hidraw* without opening devices — lightweight and safe |
| Windows | list_presence_ids() (hidapi hid.enumerate) |
Reads VID/PID/path via SetupAPI without opening a data connection |
Why not fido2 on Windows? fido2's HID enumeration opens device handles,
which conflicts with the active CTAP2 session held by DeviceManager. This caused:
- APDU errors (0x6d00) from interrupted applet selection
- Spurious disconnect/reconnect cycles
- Constant device LED blinking
list_presence_ids() (solo2.discovery) calls hid.enumerate() which uses
SetupAPI/HidD_GetAttributes to read device info without opening data connections.
It returns device IDs in the same hid:{path!r} format as list_regular_descriptors().
Detection flow on Windows:
USBMonitorpollslist_presence_ids()every 0.5 s in a background thread- On connect: emits
device_connected→DeviceMonitor._on_usb_device_connected()triggers_scan_devices()(full discovery) immediately + delayed retries at 750 ms and 1500 ms (Windows can emit USB arrival before the new mode is fully discoverable) - On disconnect: emits
device_disconnected→ if the device_id matches a tracked device, immediate disconnect; otherwise the 1 s poll timer with grace period handles it - The 1 s
QTimerinDeviceMonitorruns as a fallback on all platforms
Do not replace the Windows backend with fido2 enumeration unless fido2 adds a lightweight presence-check mode that does not open HID handles.
On Windows the CTAP2 HID handle can go stale (OSError / WinError 1167) if
the 1 s discovery poll or vault APDU commands interfere with the session.
_ensure_device() only checks self._ctap2 is not None — it does not verify
the handle is alive.
_do_set_pin, _do_change_pin, and _do_browser_apdu catch OSError, reopen
the device via _reopen_device(), and retry once. If adding new _do_* handlers
to DeviceManager, follow the same pattern.
HmacTab.set_device() must not send APDUs immediately. The OATH applet
needs to be selected first by VaultTab._check_status() (which sends SELECT
OATH). HmacTab sets up the worker in set_device() but waits for
VaultTab._on_status_checked() to call hmac_tab.load_data(). Sending
INS_LIST before SELECT → 0x6d00 on any platform.
| Symptom | Root cause | Rule |
|---|---|---|
| 0x6d00 APDU errors, device LED blinking | Background thread opens HID handles (fido2 enumeration) while CTAP session is active | Never use DeviceWatcher/fido2 HID enum on Windows; use list_presence_ids() |
| 0x6d00 on tab load | APDU sent before applet SELECT | Tab set_device() must not send APDUs; defer to load_data() after applet selection |
WinError 1167 / OSError on PIN ops |
Stale HID handle after concurrent access | _do_* handlers must catch OSError, call _reopen_device(), retry once |
| Device unplug not detected on Windows | USBMonitor disabled or using wrong backend | USBMonitor must run on Windows with list_presence_ids() backend |
| Spurious disconnect/reconnect on Windows | Discovery poll transiently fails | Use _disconnect_grace_scans = 3 on Windows (consecutive misses before disconnect) |
| Device reconnect missed on Windows | USB arrival event fires before new mode is discoverable | _on_usb_device_connected must trigger delayed re-scans (750 ms + 1500 ms) |
Before merging any change to src/solo_gui/, verify:
# Must be empty (only device_manager.py may import fido2):
grep -r "from fido2" src/solo_gui/ | grep -v device_manager.py
# Must be empty (pyusb belongs in solo2-python):
grep -r "import usb" src/solo_gui/
# Must be empty (pyscard belongs in solo2-python):
grep -r "from smartcard" src/solo_gui/
# Workers must use solo2.pcsc, not raw pyscard:
grep -r "readers()\|createConnection\|CardConnection" src/solo_gui/workers/Additional checks:
- New workers import
solo2.*, not transport libs directly. - New UI code (tabs, views) only reads cached
DeviceInfo— no blocking calls. - PIN operations go through
DeviceManager, not rawClientPin. - Device discovery goes through
DeviceMonitororsolo2.discovery, not pyusb. - PC/SC connections use
iter_pcsc_connections()fromsolo2.pcsc.
- No code opens HID device handles in a background thread (causes CTAP session
conflicts on Windows). Use
list_presence_ids()for presence detection. -
USBMonitorchanges preserve the platform split:DeviceWatcheron Linux/macOS,list_presence_ids()on Windows. Never use fido2 HID enumeration on Windows. - Tab
set_device()does not send APDUs. Applet selection must happen first (e.g. VaultTab sends SELECT OATH before HmacTab can send INS_LIST). - New
DeviceManager._do_*handlers catchOSErrorand retry after_reopen_device()(Windows stale HID handle pattern, see §8). -
DeviceMonitordisconnect detection uses grace period on Windows (_disconnect_grace_scans = 3) — do not reduce without testing. -
_on_usb_device_connectedtriggers_scan_devices()with delayed retries (750 ms, 1500 ms) — Windows USB arrival fires before mode is discoverable. - If bumping a dep version in
pyproject.toml, also updaterequirements.txt/ PyInstaller hidden imports as needed (see §7).