feat(device): auto-detect ESP32 serial port in HSM setup

Author: TheCryptoDonkey

crates/heartwood-device/src/web.rs

@@ -1851,6 +1851,32 @@ async fn api_hsm_pin(
     }
 }
 
+/// `GET /api/hsm/detect` — scan for ESP32 serial devices.
+///
+/// Returns a JSON array of detected serial ports that look like Espressif
+/// devices (vendor ID 0x303a). Used by the setup UI to auto-populate the
+/// serial port field.
+async fn api_hsm_detect() -> impl IntoResponse {
+    let ports = serialport::available_ports().unwrap_or_default();
+    let espressif: Vec<serde_json::Value> = ports
+        .iter()
+        .filter_map(|p| {
+            if let serialport::SerialPortType::UsbPort(usb) = &p.port_type {
+                // Espressif vendor ID is 0x303a
+                if usb.vid == 0x303a {
+                    return Some(json!({
+                        "port": p.port_name,
+                        "product": usb.product.as_deref().unwrap_or("ESP32"),
+                        "serial": usb.serial_number.as_deref().unwrap_or(""),
+                    }));
+                }
+            }
+            None
+        })
+        .collect();
+    (StatusCode::OK, axum::Json(json!(espressif)))
+}
+
 /// Build and return the application router.
 ///
 /// No CORS layer is applied — the web UI uses same-origin requests.
@@ -1881,6 +1907,7 @@ pub fn create_router(state: Arc<AppState>) -> Router {
         .route("/api/client-keys", get(api_list_client_keys))
         .route("/api/derive-client-key", post(api_derive_client_key))
         .route("/api/hsm/pin", post(api_hsm_pin))
+        .route("/api/hsm/detect", get(api_hsm_detect))
         .layer(middleware::from_fn_with_state(state.clone(), lock_middleware))
         .layer(middleware::from_fn_with_state(state.clone(), auth_middleware))
         .layer(DefaultBodyLimit::max(65536))

web/index.html

@@ -257,9 +257,12 @@ <h3>Hardware HSM <span class="badge advanced">advanced</span></h3>
             <div id="fields-hsm" class="fields hidden">
                 <div class="field">
                     <label>Serial port path</label>
-                    <input type="text" id="hsm-serial-port" placeholder="/dev/ttyUSB0" autocomplete="off" spellcheck="false" style="width:100%; padding:0.65rem; background:#111; border:1px solid #333; border-radius:6px; color:#e0e0e0; font-family:monospace; font-size:0.9rem;">
+                    <div style="display:flex; gap:0.5rem; align-items:center;">
+                        <input type="text" id="hsm-serial-port" placeholder="/dev/ttyACM0" autocomplete="off" spellcheck="false" style="flex:1; padding:0.65rem; background:#111; border:1px solid #333; border-radius:6px; color:#e0e0e0; font-family:monospace; font-size:0.9rem;">
+                        <button type="button" onclick="detectEsp32()" style="padding:0.65rem 1rem; background:#2a2a2a; border:1px solid #444; border-radius:6px; color:#e0e0e0; cursor:pointer; white-space:nowrap; font-size:0.85rem;">Detect</button>
+                    </div>
+                    <p id="hsm-detect-msg" style="font-size:0.78rem; opacity:0.6; margin-top:0.25rem;"></p>
                 </div>
-                <p style="font-size:0.78rem; opacity:0.45; margin-top:0.25rem;">The ESP32 must be connected to this port before starting the bridge binary. Common paths: <code>/dev/ttyUSB0</code>, <code>/dev/ttyACM0</code>.</p>
             </div>
 
             <!-- PIN for encryption at rest -->
@@ -454,6 +457,26 @@ <h2>Device Password</h2>
             return { focus: () => input.focus(), reset: () => { input.value = ''; suggestions.classList.remove('visible'); } };
         }
 
+        async function detectEsp32() {
+            const msg = document.getElementById('hsm-detect-msg');
+            msg.textContent = 'Scanning...';
+            try {
+                const r = await fetch('/api/hsm/detect');
+                const devices = await r.json();
+                if (devices.length === 0) {
+                    msg.textContent = 'No ESP32 devices found. Check the USB connection.';
+                } else if (devices.length === 1) {
+                    document.getElementById('hsm-serial-port').value = devices[0].port;
+                    msg.textContent = 'Found: ' + devices[0].product + ' at ' + devices[0].port;
+                } else {
+                    document.getElementById('hsm-serial-port').value = devices[0].port;
+                    msg.textContent = 'Found ' + devices.length + ' devices. Using ' + devices[0].port;
+                }
+            } catch (e) {
+                msg.textContent = 'Detection failed: ' + e.message;
+            }
+        }
+
         function selectMode(mode) {
             currentMode = mode;
             document.querySelectorAll('.mode-card').forEach(c =>