MeghdadFadaee/net-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
net-bridge/docs/continuation-plan.md
Meghdad Fadaee b544332aca
Some checks failed
CI / Android (push) Failing after 3s
Details
CI / Rust (push) Successful in 29s
Details
add the handoff file.
2026-05-31 20:13:39 +03:30

11 KiB
Raw Permalink Blame History

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:

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:

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:

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:

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:

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:

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.
Reference in New Issue View Git Blame Copy Permalink