dokril/vpn-proxy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: add windows client design

Browse Source
This commit is contained in:
Dmitriy Petrov
2026-05-21 19:55:08 +03:00
parent ab44626a0f
commit f4990a4f55
2 changed files with 230 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -6,6 +6,7 @@ _archive/
*.env.local
data/
.vpn-proxy/
.superpowers/
# Node/Vite
node_modules/

229
docs/superpowers/specs/2026-05-21-windows-client-design.md Normal file
View File

@@ -0,0 +1,229 @@
# Windows Client Design
## Goal
Restore the old Windows workflow in a cleaner product shape: a one-command PowerShell installer can install either a full local `sing-box` + ProxiFyre setup or ProxiFyre-only routing to an existing proxy, then expose a small local web UI for profiles, folders, executable files, status, and logs.
## Product Shape
The Windows mode is script-first and UI-assisted. The installer remains the durable entrypoint because Windows driver/service setup needs administrator rights and must stay easy to debug from PowerShell. The web UI is a local control surface on top of the same scripts, not a separate desktop app in the first version.
The installer supports two paths:
- **Full install:** install native `sing-box.exe`, configure a local SOCKS/HTTP proxy on `127.0.0.1:1080`, install WinPacketFilter and ProxiFyre, then route selected Windows apps through the local proxy.
- **ProxiFyre only:** install WinPacketFilter and ProxiFyre, then point selected Windows apps to an existing proxy target such as `127.0.0.1:8080`, `192.168.50.111:8080`, or another reachable SOCKS5 endpoint.
The default UI direction is the approved cleaner mockup: one route status, profiles as the main object, selected profile details on the right, and a short recent activity/log section below. The first screen should answer: what is the active proxy target, whether services are running, and which profiles are currently enabled.
## User Flows
### Install
The user opens PowerShell 7 as Administrator and runs:
```powershell
irm https://git.dokops.ru/dokril/vpn-proxy/raw/branch/master/scripts/install-windows-client.ps1 | iex
```
The installer checks administrator rights, PowerShell version, architecture, internet access, and required paths. It installs under `C:\Tools\vpn-proxy-windows` and keeps third-party runtime files in focused subdirectories:
- `C:\Tools\vpn-proxy-windows\app` for this project checkout or archive.
- `C:\Tools\vpn-proxy-windows\runtime\node` for portable Node.js when no suitable Node is installed.
- `C:\Tools\vpn-proxy-windows\runtime\sing-box` for `sing-box.exe`, config, and logs.
- `C:\Tools\ProxiFyre` for ProxiFyre, matching the legacy script path.
If the user chooses Full install, the installer asks for a subscription or VLESS link, parses it through the existing subscription logic where possible, lets the user select a server, writes the native `sing-box` config, installs a scheduled task for `sing-box`, and starts it.
If the user chooses ProxiFyre only, the installer asks for a SOCKS5 proxy target and verifies TCP connectivity before writing ProxiFyre config.
After setup, the installer starts the local control UI on `http://127.0.0.1:3456` and prints recovery commands:
```powershell
& "C:\Tools\vpn-proxy-windows\manage.ps1"
& "C:\Tools\vpn-proxy-windows\manage.ps1" -OpenUi
& "C:\Tools\vpn-proxy-windows\manage.ps1" -Status
```
### Profile Management
Profiles are the central unit. A profile contains a name, enabled flag, proxy target, protocol list, and app items. Supported item types:
- `process`: process name such as `Discord`, `Update`, or `Vesktop`.
- `folder`: folder path; the system scans `.exe` files and converts them to routable entries.
- `exe`: explicit executable file path; the system resolves it to the executable name for ProxiFyre and keeps the full path for display and diagnostics.
Folder and exe entries are intentionally stored as user-facing source items, while the generated ProxiFyre config is derived. This keeps the UI understandable and makes future ProxiFyre/Proxifier adapter changes possible without changing the profile model.
When a profile changes, the UI marks it as pending. The user applies changes once. Apply regenerates ProxiFyre `app-config.json`, restarts the ProxiFyre service, then writes an activity entry showing what changed.
### Runtime Operations
The UI exposes these actions:
- start, stop, restart `sing-box` when local mode is installed;
- start, stop, restart ProxiFyre;
- switch a profile between `local-singbox` and an external proxy target;
- add process, folder, or exe entries;
- scan folder entries again;
- copy diagnostics for support/debugging;
- open logs.
The UI does not auto-change global Windows proxy settings. Routing happens only through ProxiFyre profiles.
## Architecture
The active project already has a plain Node API server, React/Vite UI, subscription parser, `sing-box` config generator, logs, traffic parsing, and client/gateway modes. Windows mode should reuse those pieces and add a Windows helper boundary.
### App Mode
Add `APP_MODE=windows`. In Windows mode:
- the HTTP server binds to `127.0.0.1`;
- the UI uses Windows labels and hides gateway-only TProxy/device controls;
- config generation is proxy-only like client mode, but it targets native `sing-box.exe` rather than Docker;
- service and driver actions go through the PowerShell helper, not direct Node assumptions.
### Windows Helper Boundary
Create a PowerShell helper module that owns privileged Windows operations:
- install/update `sing-box.exe`;
- install/start/stop scheduled tasks;
- install/update WinPacketFilter;
- install/update ProxiFyre;
- write ProxiFyre config;
- query service/task status;
- read recent log files;
- test proxy connectivity;
- manage firewall rules for local proxy ports.
The Node server calls the helper with explicit command names and JSON input/output. The helper returns structured JSON for every operation:
```json
{
"success": true,
"action": "proxies.apply",
"changed": true,
"message": "ProxiFyre config applied and service restarted"
}
```
Errors use the same shape with `success: false`, `error`, and optional `details`. The UI never parses raw PowerShell text.
### Data Files
Windows mode stores state under `C:\Tools\vpn-proxy-windows\data`:
- `windows-profiles.json` for profile source data.
- `proxy-targets.json` for `local-singbox` and external proxy targets.
- `windows-state.json` for last applied profile revision and UI status.
- `subscription-cache.json` and `state.json` stay compatible with existing subscription/server selection logic.
Profile shape:
```json
{
"id": "discord-vesktop",
"name": "Discord + Vesktop",
"enabled": true,
"proxyTargetId": "local-singbox",
"protocols": ["TCP", "UDP"],
"items": [
{ "type": "process", "value": "Discord" },
{ "type": "process", "value": "Update" },
{
"type": "folder",
"value": "%LOCALAPPDATA%\\vesktop",
"recursive": true
},
{
"type": "exe",
"value": "C:\\Games\\SomeGame\\game.exe"
}
]
}
```
Generated ProxiFyre config is not edited directly. It is derived from enabled profiles and proxy targets, then written to `C:\Tools\ProxiFyre\app-config.json`.
### API Surface
Add Windows-specific endpoints:
- `GET /api/windows/status`: returns install mode, `sing-box` status, ProxiFyre status, active target, pending changes, and recent activity.
- `GET /api/windows/profiles`: returns profile source data with resolved executable counts.
- `PUT /api/windows/profiles`: saves profiles without applying.
- `POST /api/windows/profiles/apply`: generates ProxiFyre config and restarts service.
- `POST /api/windows/profiles/scan`: resolves folder and exe entries for preview.
- `GET /api/windows/targets`: returns `local-singbox` and external proxy targets.
- `PUT /api/windows/targets`: saves external proxy targets after validation.
- `POST /api/windows/service`: start, stop, or restart `sing-box`, ProxiFyre, or the UI service.
- `GET /api/windows/logs`: returns recent helper, `sing-box`, and ProxiFyre logs.
Existing generic endpoints for subscription fetch, server selection, apply, logs, and config validation should be reused where the behavior matches Windows mode.
## UI Design
The approved direction is a restrained operational UI:
- top bar: product name, restart/stop/add profile actions;
- left nav: Overview, Profiles, Targets, Logs, Settings;
- main status panel: one sentence describing the active route, plus a compact route line such as `Selected apps -> ProxiFyre -> sing-box -> VPN`;
- main workspace: profile list on the left, selected profile details on the right;
- profile details: target selector, add process/folder/exe input, resolved items list, save/apply controls;
- activity panel: recent traffic/service events, not a full noisy log dump.
Avoid duplicate status blocks. Avoid showing raw implementation concepts like WinPacketFilter unless the user is in diagnostics/settings. The primary terms should be `Profile`, `Proxy target`, `Local sing-box`, `Existing proxy`, `App/folder/exe`, and `Apply changes`.
## Safety And Constraints
The UI binds only to `127.0.0.1`. Windows actions that require elevation stay in the installer/helper path. The installer must not delete existing `C:\Tools\vpn-proxy` legacy folders without confirmation.
Folder and exe routing needs a clear diagnostic note: ProxiFyre routing ultimately depends on what the installed ProxiFyre version accepts. The first implementation should resolve folders and exe paths to executable names for compatibility, while preserving full paths in profile data and diagnostics. If direct path matching is verified in ProxiFyre, the adapter can emit full paths without changing the UI model.
The installer should be idempotent:
- re-running it updates project files;
- existing subscriptions and profiles are preserved unless the user chooses reset;
- existing ProxiFyre config is backed up before overwrite;
- failed applies leave the previous generated config available for rollback.
## Testing And Verification
Use focused tests for pure logic:
- profile normalization;
- folder/exe item resolution;
- ProxiFyre config generation;
- proxy target validation;
- Windows helper JSON command contract;
- `APP_MODE=windows` public state and config generation.
Use manual Windows verification for privileged operations:
- fresh Full install;
- fresh ProxiFyre-only install;
- re-run installer over existing install;
- add process profile;
- add folder profile;
- add explicit exe profile;
- switch a profile from local sing-box to external proxy;
- restart ProxiFyre and verify service status;
- copy diagnostics after a failed proxy target check.
Local non-Windows development should still run `npm test` and `npm run build`. Windows-only helper commands should have dry-run or mockable modes so logic can be tested without installing drivers on the development machine.
## Non-Goals For First Version
- No Electron or Tauri wrapper.
- No global Windows system proxy changes.
- No transparent routing without ProxiFyre.
- No remote multi-device management.
- No automatic uninstall of unrelated WinPacketFilter users.
- No Proxifier support until ProxiFyre behavior is stable.
## Implementation Defaults
- The UI server runs when opened by `manage.ps1 -OpenUi` in the first version. An at-logon scheduled UI task can be added later after the helper and UI are stable.
- Full install uses portable Node/npm when the machine has no suitable Node.js. The installer builds the React UI locally for MVP; a prebuilt release artifact can replace that later without changing user-facing behavior.
- ProxiFyre generation emits process names in the first version for compatibility. Full folder and exe paths remain in profile data and diagnostics; the adapter can start emitting full paths later if ProxiFyre path matching is verified.