Refuse to bind a device that exposes no interfaces

`bind` accepted a VIA Labs 2109:8887 and reported that no driver or process
held it. Every transfer then failed with "Interface 0 not found", because
the device has no interfaces to open: macOS had never configured it, so no
interface nodes exist in the registry. Its only child there was the user
client of a browser driving it over WebUSB.

The classifier could not tell the two cases apart. "No drivers attached to
any interface" and "no interfaces at all" both reached it as an empty list,
and both came back unbound. It now distinguishes them, and a device with
nothing to open is refused with an explanation naming the likely cause,
rather than accepted and left to fail on first use.

Found by ./Scripts/verify-hardware.sh, which picks the first bindable
non-hub device and had been choosing this one — so the failure was the first
thing the script reported on this machine, and it said nothing about the
build it was meant to be validating.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017rmyikdjWveP99ZUCDLY89

Author: beriberikix

Sources/USBIPDCLI/Commands.swift

@@ -239,6 +239,17 @@ public class BindCommand: Command {
             case .unbound:
                 break
 
+            case .noInterfaces:
+                // Nothing to open, so nothing can be served. Accepting the bind here
+                // produced a device that looked shared and failed every transfer with
+                // "Interface 0 not found".
+                logger.info("Refusing to bind a device with no interfaces", context: ["busid": busid])
+                print("Cannot share \(busid): the device exposes no USB interfaces.")
+                print("macOS has not configured it, which usually means another process is")
+                print("driving it directly — a browser tab using WebUSB, for instance. Quit")
+                print("that program and try again.")
+                throw CommandLineError.invalidArguments("Device \(busid) exposes no USB interfaces")
+
             case .partiallyClaimed(let free, let claimedBy):
                 // Some interfaces are owned and some are not. A composite debug probe
                 // looks like this: CMSIS-DAP free, the CDC serial port taken by macOS.

Sources/USBIPDCore/Device/DeviceOwnership.swift

@@ -20,6 +20,15 @@ public enum DeviceOwnership: Equatable {
     /// alike — one is a dead end, the other is a thing the user can act on.
     case userspaceProcess(clients: [String])
 
+    /// The device exposes no interfaces at all, so there is nothing to open.
+    ///
+    /// Usually this means macOS has not configured it — no configuration is selected,
+    /// so no interface nodes exist — which is common for devices another process is
+    /// driving directly, such as a WebUSB page in a browser. Reporting it as free was
+    /// worse than useless: `bind` accepted the device, announced that nothing held it,
+    /// and then every transfer failed with "Interface 0 not found".
+    case noInterfaces
+
     /// Some interfaces are free and others are owned. Common on debug probes, which
     /// pair a vendor-specific debug interface with a CDC serial port that macOS claims:
     /// a Raspberry Pi Debug Probe has CMSIS-DAP free on interface 0 while
@@ -33,7 +42,7 @@ public enum DeviceOwnership: Equatable {
         switch self {
         case .unbound, .partiallyClaimed:
             return true
-        case .kernelDriver, .userspaceProcess:
+        case .kernelDriver, .userspaceProcess, .noInterfaces:
             return false
         }
     }
@@ -182,6 +191,11 @@ public struct DeviceOwnershipInspector {
     }
 
     private func classify(_ perInterface: [(drivers: [String], opens: Bool)]) -> DeviceOwnership {
+        // Distinguish "no interfaces exist" from "interfaces exist and nothing has
+        // claimed them". Both used to arrive here with no driver names and both were
+        // called unbound, so a device with nothing to open was offered for sharing.
+        guard !perInterface.isEmpty else { return .noInterfaces }
+
         let all = perInterface.flatMap { $0.drivers }
         guard !all.isEmpty else { return .unbound }
 

Tests/USBIPDCoreTests/Device/DeviceOwnershipTests.swift

@@ -115,4 +115,33 @@ extension DeviceOwnershipTests {
         XCTAssertEqual(ownership, .kernelDriver(drivers: ["AppleUserHIDDevice"]))
         XCTAssertFalse(ownership.isServable)
     }
+
+    /// A device with no interface nodes has nothing to open, so it cannot be served.
+    ///
+    /// This reported as unbound, because "no drivers attached" and "no interfaces at
+    /// all" both arrived at the classifier as an empty list. `bind` accepted a VIA Labs
+    /// device that macOS had never configured — its only registry child was the user
+    /// client of a browser driving it over WebUSB — announced that nothing held it, and
+    /// then every transfer failed with "Interface 0 not found".
+    func testDeviceWithNoInterfacesIsNotServable() {
+        let ioKit = MockIOKitInterface()
+        ioKit.mockDevices = [MockUSBDevice(vendorID: 0x2109, productID: 0x8887)]
+        ioKit.classNamesByEntry[deviceEntry] = "IOUSBHostDevice"
+        // No interface children at all.
+        ioKit.childrenByEntry[deviceEntry] = []
+
+        let ownership = DeviceOwnershipInspector(ioKit: ioKit)
+            .ownership(vendorID: 0x2109, productID: 0x8887)
+
+        XCTAssertEqual(ownership, .noInterfaces)
+        XCTAssertFalse(ownership.isServable)
+    }
+
+    /// The distinction that makes the check above meaningful: an interface that exists
+    /// and has no driver is still the servable case.
+    func testInterfaceWithNoDriverIsStillServable() {
+        let ownership = inspector(interfaceDrivers: []).ownership(vendorID: 0x1366, productID: 0x0101)
+        XCTAssertEqual(ownership, .unbound)
+        XCTAssertTrue(ownership.isServable)
+    }
 }