net-bridge/docs/continuation-plan.md

# VPN Share Continuation Plan

Last updated: 2026-05-31

This file captures the original product/technical plan and the implementation
checkpoint reached in this workspace, so development can continue without
reconstructing context from chat history.

## Original Product Goal

VPN Share is an open-source Android-first application that lets non-technical
users share the active VPN connection of an Android phone with computers,
tablets, and other phones with one click.

The receiving device must treat the phone as a normal internet gateway. Users
must not need to manually configure proxies, routes, DNS, SSH tunnels, or app
network settings.

## Core Requirements

- Android app written in Kotlin.
- Open source.
- No root required on Android.
- Android 8+.
- Must work while an existing VPN app is already active on the phone.
- Compatible with WireGuard, OpenVPN, Clash, V2Ray, and Android `VpnService`
  based VPNs.
- Traffic from connected devices must pass through the active VPN on the phone.
- Support USB sharing.
- Support Wi-Fi sharing.
- Support hotspot sharing.
- Support Windows, Linux, macOS, Android, and iOS receiving clients.
- One-click user experience.
- Automatic service discovery.
- QR code pairing.
- Secure encrypted communication.
- Automatic reconnection.
- Low battery usage.

## Architecture Plan

The application is split into an Android gateway, a reusable networking core,
transport modules, and receiving-device clients.

Primary modules:

- Android app: Kotlin UI, foreground gateway service, permissions, pairing UI.
- Android gateway service: exposes local/transport endpoints and forwards
  traffic through Android's current default network, which should be the active
  VPN when a VPN app is connected.
- VPN Share Engine: packet, NAT, DNS, MTU, route, session, and recovery logic.
- Protocol layer: VSHP frame format, pairing protocol, encryption, session
  resume.
- Transport layer: USB, Wi-Fi, hotspot, discovery, reconnection.
- Desktop clients: Linux TUN, Windows Wintun, macOS utun, future tray/service.
- Mobile receiving clients: Android `VpnService`, future iOS Network Extension.

Important platform rule:

- The phone-side gateway must not call `VpnService.protect()` for forwarded
  sockets, because protected sockets bypass the phone VPN. Normal gateway
  sockets should follow Android's active default network, which is the existing
  VPN app when connected.

## Technical Plan

- Create a packet tunnel between each client and the Android gateway.
- Use virtual network interfaces on receiving devices:
  - Linux: TUN.
  - Windows: Wintun.
  - macOS/iOS: utun or Network Extension.
  - Android receiver: `VpnService`.
- Implement NAT/session tracking in the gateway/core.
- Implement DNS forwarding and DNS leak prevention.
- Support IPv4 first, then IPv6.
- Manage MTU conservatively, starting at 1280.
- Add reconnect/session resume.
- Optimize bandwidth and battery through batching, backpressure, foreground
  service lifecycle, and idle timeouts.

## Protocol Plan

- VSHP is the long-term application protocol.
- Pairing should use QR/code flow with explicit user approval.
- Handshake should establish an encrypted session.
- Tunnel frames should carry IP packets, control messages, heartbeats, stats,
  and resume tickets.
- Transports should be swappable underneath the same VSHP session model.

The current Linux gateway implementation uses an interim SOCKS5 transport
inside the USB ADB forward so we can provide useful OS-level gateway behavior
before VSHP packet framing is complete.

## MVP Roadmap

M0 foundation:

- Repository metadata, license, contribution docs.
- Android Gradle project and Rust workspace.
- Domain model and engine interface.
- Foreground service skeleton.
- VSHP frame parser with unit tests.

M1 USB-first MVP:

- Android USB gateway transport.
- Desktop USB host transport.
- Encrypted pairing over USB with phone approval.
- Linux TUN and Windows Wintun virtual interface.
- TCP, UDP, and DNS forwarding through Android gateway.
- Reconnection and session resume.

M2 desktop productization:

- macOS utun support.
- Installers and background service management.
- Tray UI with connect/disconnect/status.
- Android peer revoke/rename UI.
- Crash-safe logs without traffic content.

M3 Wi-Fi and hotspot:

- mDNS/DNS-SD discovery.
- QR pairing for Wi-Fi.
- LocalOnlyHotspot setup flow.
- Transport fallback between USB and Wi-Fi.

M4 Android receiver:

- Android receiving app using its own `VpnService`.
- QR pairing and one-tap connect.
- Per-app include/exclude.

M5 IPv6/performance/iOS:

- IPv6 route validation.
- MTU probing and MSS clamping.
- iOS Network Extension client.
- Battery/throughput test matrix.

## Repository State

Implemented project structure:

- `apps/android/`: Android Kotlin app and modules.
- `apps/android/app/`: application entry point and Compose screen.
- `apps/android/service/gateway/`: foreground service and USB gateway.
- `apps/android/core/domain/`: domain models.
- `apps/android/core/engine/`: gateway engine interface/skeleton.
- `clients/desktop/`: Rust desktop CLI.
- `crates/vpnshare-core/`: packet/NAT/DNS/MTU core primitives.
- `crates/vpnshare-proto/`: VSHP frame and pairing primitives.
- `crates/vpnshare-transport/`: transport abstraction.
- `crates/vpnshare-ffi/`: C ABI surface.
- `docs/`: architecture, protocol, security, transports, testing, roadmap.

## Progress Made

Android:

- Created Android Kotlin project with minSdk 26.
- Added Compose-based `ShareScreen`.
- Added `MainActivity` desktop start action:
  `org.vpnshare.action.START_FROM_DESKTOP`.
- Added `VpnShareGatewayService` foreground service.
- Added `VpnDetector` to detect active VPN network state.
- Added `UsbSocksGateway` bound to phone loopback `127.0.0.1:10808`.
- Implemented SOCKS5 no-auth TCP CONNECT forwarding.
- Implemented SOCKS5 UDP-over-TCP forwarding using command `0x05`
  (`HEV_SOCKS5_REQ_CMD_FWD_UDP`) for Linux TUN DNS/UDP support.
- Installed the updated debug APK on connected device `R5CX33ESWGH`.
- Verified the gateway foreground service is running on the device.

Desktop:

- Replaced the placeholder desktop client with a real CLI.
- Added commands:
  - `status`
  - `android-launch`
  - `connect`
  - `system-gateway`
  - `cleanup`
- `connect` starts the Android gateway and creates:
  `adb forward tcp:10808 tcp:10808`.
- Added `tun2socks = "0.1.10"` for Linux TUN routing.
- `system-gateway`:
  - requires Linux and `/dev/net/tun`;
  - requires root/CAP_NET_ADMIN on the desktop;
  - checks that `127.0.0.1:10808` is already open;
  - creates `vpnshare0`;
  - starts `tun2socks` with MTU `1280`;
  - routes IPv4 using split-default routes:
    `0.0.0.0/1` and `128.0.0.0/1`;
  - attempts IPv6 split-default routes:
    `::/1` and `8000::/1`;
  - configures systemd-resolved DNS on `vpnshare0` when `resolvectl` exists;
  - keeps the gateway active while the process is running.
- `cleanup` removes VPN Share split-default routes and reverts DNS if possible.

Core/protocol:

- Added Rust core modules for NAT, DNS, MTU, packet parsing, leases, and gateway
  state.
- Added VSHP protocol primitives and pairing URI helpers.
- Added unit tests for core/protocol/transport behavior.

Docs:

- Added architecture, protocol, security, transport, testing/CI, roadmap,
  desktop migration, repository structure, and desktop client docs.
- Updated README to reflect Linux TUN gateway mode.

## Verified In This Workspace

Rust:

```bash
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo build -p vpnshare-desktop
```

Results:

- Rust tests passed.
- Formatting check passed.
- Clippy passed.
- Desktop binary built.

Android:

```bash
GRADLE_USER_HOME=/tmp/vpnshare-gradle-home \
ANDROID_HOME=/tmp/vpnshare-android-sdk \
ANDROID_SDK_ROOT=/tmp/vpnshare-android-sdk \
env -u GRADLE_HOME \
/tmp/vpnshare-gradle/gradle-9.4.1/bin/gradle :apps:android:app:assembleDebug
```

Result:

- Android debug build passed.
- APK installed successfully with `adb install -r -t -d`.

Runtime:

```bash
VPN_SHARE_ADB=/tmp/vpnshare-platform-tools-36/platform-tools/adb \
./target/debug/vpnshare-desktop status
```

Observed:

- `os=linux`
- `tun_available=true`
- one authorized ADB device: `R5CX33ESWGH`
- Android package installed: true
- Android gateway foreground: true

USB gateway:

```bash
VPN_SHARE_ADB=/tmp/vpnshare-platform-tools-36/platform-tools/adb \
./target/debug/vpnshare-desktop connect
```

Observed:

- USB SOCKS endpoint ready at `socks5h://127.0.0.1:10808`.

Traffic checks:

- HTTPS through the Android gateway worked via SOCKS:
  public IP returned `205.237.109.233`.
- UDP-over-TCP DNS through the Android gateway worked:
  DNS query to `1.1.1.1:53` for `example.com` returned a valid response.

System gateway:

- Non-root startup check correctly fails with a root/CAP_NET_ADMIN message.
- Could not start `system-gateway` from the tool because local sudo requires the
  user's password.

## How To Run Current Linux Gateway

From the repo root:

```bash
cargo build -p vpnshare-desktop
VPN_SHARE_ADB=/tmp/vpnshare-platform-tools-36/platform-tools/adb \
./target/debug/vpnshare-desktop connect
sudo ./target/debug/vpnshare-desktop system-gateway
```

Keep `system-gateway` running while sharing.

Cleanup:

```bash
sudo ./target/debug/vpnshare-desktop cleanup
```

## Local Environment Notes

- Reliable ADB path:
  `/tmp/vpnshare-platform-tools-36/platform-tools/adb`
- Local Android SDK:
  `/tmp/vpnshare-android-sdk`
- Local Gradle:
  `/tmp/vpnshare-gradle/gradle-9.4.1/bin/gradle`
- Local Gradle user home:
  `/tmp/vpnshare-gradle-home`
- Device used for testing:
  `R5CX33ESWGH`, Samsung `SM-A556E`
- System Gradle under `$HOME/.gradle/native/...` was broken/read-only, so the
  local Gradle path above was used.
- Gradle inside the sandbox can fail with:
  `Could not determine a usable wildcard IP for this machine`.
  Running Gradle outside the sandbox fixed it.

## Known Limitations

- Android gateway currently exposes an interim SOCKS5 endpoint over ADB forward.
  The desktop TUN mode uses `tun2socks` over that endpoint.
- Full VSHP encrypted packet tunnel is not wired end to end yet.
- Pairing approval, QR pairing, device trust store, and session resume are not
  wired into the runtime path.
- Linux TUN gateway needs `sudo` or CAP_NET_ADMIN on the desktop.
- Windows Wintun, macOS utun, Android receiver, and iOS receiver are not
  implemented yet.
- Wi-Fi, hotspot, mDNS discovery, and QR pairing transports are not implemented
  yet.
- Android UDP forwarding is simple and should be hardened/performance-tested for
  high-volume UDP traffic.
- Route cleanup is best effort. If interrupted badly, run:
  `sudo ./target/debug/vpnshare-desktop cleanup`.

## Recommended Next Steps

1. Manually run `sudo ./target/debug/vpnshare-desktop system-gateway` and verify
   normal browser/app traffic uses the phone VPN without proxy settings.
2. Add a desktop integration test for UDP-over-TCP SOCKS frames.
3. Add Android unit tests for `UsbSocksGateway` request/frame parsing.
4. Replace the interim SOCKS transport with VSHP packet frames over USB.
5. Add encrypted pairing and a phone approval UI.
6. Make route/DNS management crash-safe with a guard file and startup cleanup.
7. Add a desktop service/tray wrapper for one-click connect.
8. Add Windows Wintun support after Linux path is stable.
9. Add Wi-Fi/hotspot discovery and QR pairing.
10. Add receiving-device Android app using `VpnService`.