# 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).