68 lines
2.3 KiB
Markdown
68 lines
2.3 KiB
Markdown
# VPN Share
|
|
|
|
VPN Share is an open-source Android-first project for sharing an Android phone's
|
|
active VPN connection with nearby computers, tablets, and phones.
|
|
|
|
The product goal is simple for users: start the VPN they already trust on their
|
|
phone, tap **Share**, pair the receiving device, and let the client route traffic
|
|
through the phone automatically.
|
|
|
|
## Current Status
|
|
|
|
This repository contains the production architecture, protocol specification,
|
|
Android project scaffold, Rust core scaffold, and the first USB-first engine
|
|
interfaces. It is not yet a complete packet-forwarding release.
|
|
|
|
The first shippable milestone is:
|
|
|
|
- Android gateway app, Kotlin, minSdk 26.
|
|
- Rust `vpnshare-core` packet engine library.
|
|
- USB companion-client transport.
|
|
- Desktop client foundation for Windows, Linux, and macOS.
|
|
- Encrypted VSHP tunnel with QR/code pairing.
|
|
|
|
## Important Platform Constraint
|
|
|
|
VPN Share uses companion clients on receiving devices. This is required because
|
|
stock Android only allows one prepared `VpnService` owner at a time. The phone
|
|
gateway must preserve the already-running VPN app, so it does not create a
|
|
second phone-side VPN.
|
|
|
|
The Android app opens normal network sockets from the gateway process. When an
|
|
existing VPN app is the device default network, those sockets are routed through
|
|
that VPN by Android. The gateway must not call `VpnService.protect()` for
|
|
forwarded traffic, because protected sockets bypass VPN routing.
|
|
|
|
## Repository Layout
|
|
|
|
```text
|
|
apps/android/ Android application and feature modules
|
|
clients/desktop/ Desktop client CLI/service foundation
|
|
crates/vpnshare-core/ Packet, NAT, DNS, MTU, and gateway domain engine
|
|
crates/vpnshare-proto/ VSHP frame and pairing protocol primitives
|
|
crates/vpnshare-transport/ Transport abstraction shared by clients/gateway
|
|
crates/vpnshare-ffi/ C ABI surface for Android JNI integration
|
|
docs/ Architecture, protocol, security, testing, roadmap
|
|
```
|
|
|
|
## Build Notes
|
|
|
|
Rust validation:
|
|
|
|
```bash
|
|
cargo test --workspace
|
|
```
|
|
|
|
Android validation, once a healthy Gradle installation or wrapper is available:
|
|
|
|
```bash
|
|
gradle :apps:android:app:assembleDebug
|
|
```
|
|
|
|
The local environment used to create this scaffold had a broken system Gradle
|
|
native-platform installation, so Android compilation was not executed locally.
|
|
|
|
## License
|
|
|
|
Apache-2.0. See [LICENSE](LICENSE).
|