net-bridge/docs/architecture.md

VPN Share Architecture

Product Contract

VPN Share shares an Android phone's active VPN with nearby devices through an encrypted application tunnel. The receiving device runs a small companion client that installs or opens its own virtual network interface and routes traffic to the phone automatically.

The phone app does not replace the user's VPN provider. It preserves the active VPN app and forwards client traffic through Android's default network routing.

Non-Negotiable Platform Constraints

• No root and Android 8+ means no direct manipulation of system NAT, tethering routing tables, or hotspot iptables.
• Only one Android app can be prepared as the active VpnService owner at a time. The gateway app therefore cannot run a phone-side VpnService while WireGuard, OpenVPN, Clash, V2Ray, or another VPN is active.
• Android LocalOnlyHotspot is local-only and does not provide Internet. VPN Share uses it only as a local transport for the encrypted tunnel.
• VpnService.protect() must not be used for forwarded gateway sockets because protected sockets bypass VPN routing.

Component Diagram

flowchart TB
  subgraph AndroidPhone[Android phone]
    UI[Compose app UI]
    FG[Gateway foreground service]
    DET[VpnDetector]
    DISC[Discovery: QR, mDNS, USB]
    FFI[Rust FFI adapter]
    ENG[vpnshare-core]
    NAT[Userspace TCP/UDP NAT]
    DNS[DNS forwarder/cache]
    MTU[MTU/MSS manager]
  end

  subgraph Clients[Receiving devices]
    DC[Desktop client]
    AC[Android client VpnService]
    IC[iOS Network Extension]
  end

  DC -->|USB/Wi-Fi/hotspot VSHP| FG
  AC -->|Wi-Fi/hotspot VSHP| FG
  IC -->|Wi-Fi/hotspot VSHP| FG
  UI --> FG
  FG --> DET
  FG --> DISC
  FG --> FFI
  FFI --> ENG
  ENG --> NAT
  ENG --> DNS
  ENG --> MTU
  NAT -->|Android sockets| VPN[Existing active VPN app]
  DNS -->|Android resolver/network DNS| VPN
  VPN --> Internet[Internet]

Data Flow

flowchart LR
  App[Client application traffic] --> TUN[Client virtual NIC]
  TUN --> Packetizer[Client VSHP packetizer]
  Packetizer --> Crypto[Noise session encryption]
  Crypto --> Transport[USB/Wi-Fi/hotspot transport]
  Transport --> Gateway[Android gateway service]
  Gateway --> Engine[Rust engine]
  Engine --> NAT[NAT / DNS / flow control]
  NAT --> Socket[Android TCP/UDP sockets]
  Socket --> ActiveVpn[Existing active VPN]
  ActiveVpn --> Internet

Main Sequences

USB-First Pairing

sequenceDiagram
  participant User
  participant Phone
  participant Desktop
  participant Engine

  User->>Phone: Tap Share
  Phone->>Phone: Start foreground gateway
  Phone->>Phone: Verify active VPN network
  Desktop->>Phone: Open USB accessory channel
  Desktop->>Phone: HELLO with client public key
  Phone->>User: Show pairing code and device name
  User->>Phone: Approve
  Phone->>Engine: Create peer lease
  Phone->>Desktop: AUTH + CONFIG
  Desktop->>Desktop: Configure virtual NIC/routes/DNS
  Desktop->>Phone: IP_PACKET frames
  Phone->>Internet: Forward via active VPN

Reconnection

sequenceDiagram
  Client->>Gateway: PING session_id, counters
  Gateway--xClient: Transport interruption
  Client->>Gateway: RESUME session_id, ticket
  Gateway->>Gateway: Validate ticket and peer policy
  Gateway->>Client: CONFIG delta
  Client->>Gateway: Continue packet frames

Android Domain Model

• GatewaySession: active share session with transport set, peer leases, VPN status, and byte counters.
• PeerDevice: trusted receiving device with public key, platform, label, first seen, last seen, and revocation status.
• PairingRequest: short-lived untrusted request created by USB, QR, or mDNS.
• TransportEndpoint: USB accessory, LAN UDP/TCP, or local-only-hotspot path.
• TunnelLease: client virtual IPs, DNS gateway, MTU, route set, and expiry.

Runtime Policy

• Gateway starts only from user action and remains foreground while sharing.
• Gateway shows a persistent notification with connected peer count and a stop action.
• If no active VPN network is detected, the app can still start local pairing but marks Internet sharing unavailable until the VPN appears.
• Forwarded traffic never leaves the device through a protected or underlying non-VPN socket unless the user explicitly enables a future advanced bypass mode.

Future Desktop Architecture

The Rust protocol/core crates are shared by Android gateway and desktop clients. Desktop-specific modules only provide virtual NIC, installer, service manager, tray UI, and OS network configuration.