# 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 a Linux-first USB gateway
prototype.

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.

The current desktop binary provides USB sharing through the Android gateway. On
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
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
```

## License

Apache-2.0. See [LICENSE](LICENSE).