init

docs/transports.md

@@ -0,0 +1,49 @@
+# Transport Designs
+
+## USB Transport
+
+USB is the first MVP transport.
+
+### Phone Side
+
+- Android uses accessory-mode APIs through `UsbManager.openAccessory`.
+- The gateway treats USB as an ordered byte stream carrying VSHP frames.
+- The USB session is accepted only after phone-side pairing approval.
+- If USB disconnects, the peer lease remains resumable for a short window.
+
+### Desktop Side
+
+- The desktop client acts as USB host and opens the Android Open Accessory
+  channel.
+- The client advertises platform, app version, and public key in `HELLO`.
+- After `CONFIG`, the client configures the local virtual interface and routes.
+
+### Failure Modes
+
+- Cable unplug: transport closes, session enters resumable state.
+- Host sleeps: session ticket can resume on reconnect.
+- Unknown host: no IP traffic is accepted before pairing approval.
+
+## Wi-Fi Transport
+
+- Discovery uses DNS-SD service type `_vpnshare._udp`.
+- QR pairing remains the reliable fallback when multicast is blocked.
+- The tunnel uses the same VSHP frame format as USB.
+- The gateway never assumes LAN is trusted.
+
+## Hotspot Transport
+
+- Android app-created hotspot uses `LocalOnlyHotspot`.
+- The local-only hotspot does not provide Internet; it only provides local reach
+  to the gateway app.
+- The client still installs its virtual interface and uses VSHP for all traffic.
+
+## Transport Selection
+
+Default order:
+
+1. USB if connected and paired.
+2. Known Wi-Fi peer on same LAN.
+3. Local-only hotspot if the user starts it from the app.
+
+Session resume can switch transports if the peer key and resume ticket validate.