chore: import upstream snapshot with attribution

2026-07-13 12:31:33 +08:00
commit 9e8f1bbeed
1156 changed files with 235330 additions and 0 deletions
@@ -0,0 +1,145 @@
+# Network configuration (Wi-Fi management)
+
+ODS can join the host to a Wi-Fi network through the dashboard. This is wired into the first-boot wizard but the endpoints are also callable directly.
+
+## Platform support
+
+| OS / stack | Supported | Notes |
+|---|---|---|
+| Linux + NetworkManager | ✅ | Primary target. Ubuntu 22.04+, Debian 12+, Fedora 41+, most desktop distros ship `nmcli` by default. |
+| Linux + systemd-networkd / wpa_supplicant-only | ❌ | The endpoints return `501` with a clear error. Configure manually until we add this. |
+| macOS | ❌ | The system controls Wi-Fi. The endpoints return a clear "not supported" response and the wizard falls back to "use Ethernet." |
+| Windows | ❌ | Same as macOS. |
+
+The dashboard's `/api/setup/network-status` always returns `200` (never `5xx`) on unsupported platforms — the body carries `platform_supported: false` so the wizard can render a fallback without error handling.
+
+## Architecture
+
+```
+Dashboard React UI
+       │ /api/setup/wifi-scan
+       │ /api/setup/wifi-connect
+       │ /api/setup/network-status
+       ▼
+dashboard-api (FastAPI, container)
+       │ /v1/network/...
+       ▼
+ods-host-agent (HTTP server on host, root)
+       │ subprocess
+       ▼
+   nmcli ─→ NetworkManager
+```
+
+The container can't run `nmcli` directly — it needs root and access to the host's NetworkManager D-Bus. Routing through the host-agent is the same pattern we already use for `.env` writes and Docker recreates.
+
+## API surface
+
+All endpoints require the standard dashboard-api Bearer token (auth handled at the dashboard-api edge; the host-agent has its own API key for the inner hop).
+
+### `GET /api/setup/wifi-scan`
+
+Returns nearby Wi-Fi networks, strongest signal first.
+
+```json
+{
+  "networks": [
+    {"ssid": "Home WiFi", "signal": 88, "security": "WPA2", "in_use": true},
+    {"ssid": "Guest",     "signal": 50, "security": "WPA2", "in_use": false}
+  ]
+}
+```
+
+The endpoint triggers a fresh rescan (best-effort) then returns nmcli's cached list. Duplicate SSIDs (multiple BSSIDs of the same network) are collapsed.
+
+### `POST /api/setup/wifi-connect`
+
+Joins a Wi-Fi network.
+
+```json
+{ "ssid": "Home WiFi", "password": "supersecret" }
+```
+
+Returns `{"success": true, "ssid": "..."}` on success.
+
+Error responses:
+- `400 Wrong password` — auth failed
+- `400 Network not found` — SSID is not visible
+- `504 Connection attempt timed out` — handshake / DHCP didn't complete in 45s
+- `501` — host is not Linux + NetworkManager
+- `503` — host-agent itself is unreachable
+
+The password is **never** logged. The host-agent passes it to nmcli via argv; the only thing in the log is `wifi-connect ssid=<name> password_set=true`.
+
+### `GET /api/setup/network-status`
+
+Current connectivity. Always returns 200.
+
+```json
+{
+  "platform_supported": true,
+  "devices": [
+    {
+      "device": "wlan0",
+      "type": "wifi",
+      "state": "connected",
+      "connection": "Home WiFi",
+      "ip": "192.168.1.42",
+      "gateway": "192.168.1.1"
+    }
+  ],
+  "wifi_connected": true
+}
+```
+
+On unsupported platforms:
+
+```json
+{ "platform_supported": false, "platform": "Windows", "reason": "..." }
+```
+
+### `POST /api/setup/wifi-forget`
+
+Deletes a saved NetworkManager connection profile.
+
+```json
+{ "connection": "OldNetwork" }
+```
+
+## Security notes
+
+- **Password lifetime in process memory.** The password lives in the host-agent's memory while the subprocess runs, then in nmcli's argv until the process exits. On modern Linux with `kernel.yama.ptrace_scope >= 1` (default on Ubuntu/Fedora), unprivileged processes can't read the cmdline of another user's process — and the host-agent runs as root anyway. The exposure window is acceptable for v1.
+- **Not for hostile networks.** This is a local-LAN admin surface. Don't expose the dashboard-api to the public internet without a real auth layer in front.
+- **Connection profiles persist.** Once connected, NetworkManager remembers the password. `/api/setup/wifi-forget` is how you remove it.
+
+## Troubleshooting
+
+### `nmcli not found`
+
+The host-agent returns `501`. Install NetworkManager via your distro:
+
+```bash
+# Debian / Ubuntu
+sudo apt install network-manager
+
+# Fedora
+sudo dnf install NetworkManager
+
+# Arch
+sudo pacman -S networkmanager
+```
+
+Some distros use systemd-networkd by default; switching to NetworkManager is the supported path today.
+
+### Scan returns no networks
+
+- The radio may be soft-blocked. Run `rfkill list` and unblock with `rfkill unblock wifi`.
+- If running in a container/VM, the host needs Wi-Fi hardware passthrough; running in a generic VM almost never works.
+- Some hardware needs proprietary firmware (e.g. Broadcom). Check `dmesg | grep firmware`.
+
+### Connect succeeds but no IP
+
+NetworkManager handles DHCP; if the AP authenticated you but no IP arrives, the upstream DHCP server is the problem. Verify with `nmcli connection show <ssid>` then `nmcli connection up <ssid>`.
+
+### Two networks with the same SSID
+
+The scan collapses on SSID. If you genuinely need to target a specific BSSID, use `nmcli` directly — the wizard intentionally does not surface BSSID selection.