From b544332acabed9008a8b8c00269aafa5bdb74414 Mon Sep 17 00:00:00 2001 From: Meghdad Fadaee Date: Sun, 31 May 2026 20:13:39 +0330 Subject: [PATCH] add the handoff file. --- README.md | 3 + docs/continuation-plan.md | 351 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 354 insertions(+) create mode 100644 docs/continuation-plan.md diff --git a/README.md b/README.md index 7b49be6..444a432 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,9 @@ Linux it can create a real `vpnshare0` TUN interface and route normal OS/app traffic through the phone with `sudo ./target/debug/vpnshare-desktop system-gateway`. See [docs/desktop-client.md](docs/desktop-client.md). +For the original plan and current implementation checkpoint, see +[docs/continuation-plan.md](docs/continuation-plan.md). + ## Important Platform Constraint VPN Share uses companion clients on receiving devices. This is required because diff --git a/docs/continuation-plan.md b/docs/continuation-plan.md new file mode 100644 index 0000000..78c6346 --- /dev/null +++ b/docs/continuation-plan.md @@ -0,0 +1,351 @@ +# 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`.