macOS client (DriverKit VHCI equivalent)

[stanvx]

What to build

Port the client import side to macOS so a Mac can import a remote USB device and present it as locally attached. Unlike Linux (vhci-hcd), Windows (usbip-win2), and Android (VHCI module), macOS has no built-in virtual USB host controller kernel module. This issue requires deciding the approach before coding begins.

Architecture decision (HITL)

Three known paths:

1. DriverKit dext: Write a macOS DriverKit extension that implements a virtual USB host controller. Modern path, but undocumented for VHCI use.
2. IOUSBHostFamily: Build on Apple's open-source I/O Kit USB host controller family. Available in I/O Kit framework.
3. Third-party shim: Investigate whether an existing userspace VHCI equivalent exists for macOS (e.g., usbip-macos projects) and wrap/contribute to it.

The implementer should spike 2-3 paths for feasibility before committing. This is HITL — a human must approve the approach.

Acceptance criteria

• Design doc or ADR describing the chosen VHCI approach with rationale
• Connection to remote server: TCP connect on port 3240
• Device import protocol: OP_REQ_IMPORT / OP_REP_IMPORT handshake
• URB receive path: USB/IP commands from server forwarded to virtual controller
• URB send path: virtual controller completions forwarded back to server
• Device appears in macOS System Information under USB
• Interrupt, bulk, and control transfers all work
• Encryption path works (same AES-256-GCM as other platforms)
• launchd plist for background operation (client daemon mode on macOS)

Blocked by

None — can start immediately (investigation/spike phase does not depend on other tickets).