net-bridge/docs/transports.md

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.