139 lines
4.3 KiB
Markdown
139 lines
4.3 KiB
Markdown
# VPN Proxy Windows Client
|
|
|
|
Standalone Windows desktop utility for app-level proxy routing. This app is
|
|
separate from the current Docker gateway/client runtime and must not be wired
|
|
through `APP_MODE=windows`.
|
|
|
|
## Components
|
|
|
|
- Control App: Tauri 2 + React/TypeScript UI and Rust command layer.
|
|
- Proxyfier Layer: ProxiFyre adapter for per-application routing.
|
|
- Local sing-box: optional local runtime, used only by targets that explicitly
|
|
require `singbox`.
|
|
|
|
External SOCKS5 targets are the MVP path and do not require Local sing-box.
|
|
|
|
## Source And Generated Files
|
|
|
|
Source configuration is owned by Rust domain models and JSON files under:
|
|
|
|
```text
|
|
C:\ProgramData\VpnProxy\config\profiles.json
|
|
C:\ProgramData\VpnProxy\config\targets.json
|
|
C:\ProgramData\VpnProxy\config\components.json
|
|
C:\ProgramData\VpnProxy\config\local-singbox.json
|
|
C:\ProgramData\VpnProxy\state\singbox-subscription-cache.json
|
|
C:\ProgramData\VpnProxy\state\activity.json
|
|
```
|
|
|
|
Generated artifacts are derived and can be recreated:
|
|
|
|
```text
|
|
C:\ProgramData\VpnProxy\generated\proxifyre-app-config.json
|
|
C:\ProgramData\VpnProxy\generated\sing-box-config.json
|
|
```
|
|
|
|
## Development
|
|
|
|
```powershell
|
|
cd apps/windows-client
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
Run the browser preview shell:
|
|
|
|
```powershell
|
|
npm run dev -- --host 127.0.0.1
|
|
```
|
|
|
|
Run Tauri checks when the native Windows toolchain is installed:
|
|
|
|
```powershell
|
|
npm run tauri -- info
|
|
npm run tauri -- dev
|
|
npm run tauri -- build
|
|
```
|
|
|
|
Run Rust tests when Rust/Cargo are installed:
|
|
|
|
```powershell
|
|
cd apps/windows-client/src-tauri
|
|
cargo test
|
|
```
|
|
|
|
Native Tauri build requires WebView2, Rust via rustup, and Visual Studio Build
|
|
Tools with MSVC and Windows SDK components.
|
|
|
|
## Explicit Installer Boundaries
|
|
|
|
Installer scripts are explicit per component and return structured JSON in
|
|
`-PlanOnly` mode:
|
|
|
|
```powershell
|
|
& .\scripts\install-control-app.ps1 -PlanOnly
|
|
& .\scripts\install-proxyfier.ps1 -PlanOnly
|
|
& .\scripts\install-singbox.ps1 -PlanOnly
|
|
```
|
|
|
|
Installers must be launched intentionally by the user or by a future narrow
|
|
helper permission. Profile apply must not silently install Control App,
|
|
Proxyfier, or Local sing-box.
|
|
|
|
Local sing-box install creates this optional runtime:
|
|
|
|
```text
|
|
C:\Program Files\VpnProxy\sing-box\sing-box.exe
|
|
C:\Program Files\VpnProxy\sing-box\VpnProxySingBox.exe
|
|
Windows service: VpnProxySingBox
|
|
```
|
|
|
|
The install flow downloads `sing-box` from `SagerNet/sing-box` releases and the
|
|
WinSW service wrapper from `winsw/winsw` releases, then writes a service config
|
|
that points at `C:\ProgramData\VpnProxy\generated\sing-box-config.json`. It
|
|
requires UAC confirmation. Uninstall is scoped to the configured
|
|
`VpnProxy\sing-box` install root.
|
|
|
|
The external proxy route remains independent from Local sing-box. Choosing
|
|
Local sing-box in the UI generates `sing-box-config.json`, ensures the
|
|
`local-singbox` SOCKS5 target at `127.0.0.1:1080`, and then applies ProxiFyre
|
|
to that local target.
|
|
|
|
## Existing Proxyfier Detection
|
|
|
|
The app detects an already installed Proxyfier layer before showing component
|
|
status or applying profiles. Detection checks:
|
|
|
|
- uninstall registry entries for `ProxiFyre` and `Proxifier`;
|
|
- common install folders such as `C:\Tools\ProxiFyre`,
|
|
`%ProgramFiles%\ProxiFyre`, and `%ProgramFiles%\Proxifier`;
|
|
- running `ProxiFyre` / `Proxifier` processes and the `ProxiFyreService`
|
|
service.
|
|
|
|
For portable installs, set an override before launching the app:
|
|
|
|
```powershell
|
|
$env:VPN_PROXY_PROXIFYRE_ROOT = 'D:\Tools\ProxiFyre'
|
|
npm run tauri -- dev
|
|
```
|
|
|
|
`ProxiFyre` installs are compatible with the current generated
|
|
`app-config.json` apply path. Plain `Proxifier` installs are detected and shown,
|
|
but automatic profile apply is not enabled for them yet because they use a
|
|
different profile format.
|
|
|
|
## MVP Verification Flow
|
|
|
|
1. Start the Control App or browser preview.
|
|
2. Confirm Components shows Control App, Proxyfier Layer, and optional Local
|
|
sing-box separately.
|
|
3. Add or keep an external SOCKS5 target.
|
|
4. Add a process/folder/exe profile such as Discord.
|
|
5. Apply profiles and verify generated ProxiFyre config plus activity entry.
|
|
6. Install Proxyfier separately before applying to a real service.
|
|
7. Install and start Local sing-box only when using a local target.
|
|
|
|
Task evidence is recorded in
|
|
`docs/goals/windows-modular-client/EVIDENCE.md` and
|
|
`docs/goals/windows-local-singbox/EVIDENCE.md`.
|