142 lines
4.5 KiB
Markdown
142 lines
4.5 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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.
|