init

README.md

@@ -0,0 +1,67 @@
+# 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).