add the handoff file.

2026-05-31 20:13:39 +03:30
parent 266cae92ce
commit b544332aca
2 changed files with 354 additions and 0 deletions
--- a/docs/continuation-plan.md
+++ 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`.