507 lines
19 KiB
Markdown
507 lines
19 KiB
Markdown
# Windows Tauri Proxy Client Implementation Plan
|
|
|
|
**Intent:** Build a separate Windows desktop proxy management app using Tauri 2, React, TypeScript, and Rust. The app manages three independent components: Control App, Proxyfier Layer, and optional Local sing-box.
|
|
**Current Behavior:** The repo contains a gateway/client Node + React web application and planning documents for a Windows mode inside that app. A newer product/technology brief now targets a standalone Windows desktop utility instead of extending the existing web control panel.
|
|
**Expected Outcome:** A compact Windows desktop utility lets the user configure app-level proxy routing through external SOCKS5/HTTP targets first, then optionally install and use local sing-box. The app remains useful when sing-box is absent.
|
|
**Target-Perspective Output:** A Windows user opens the desktop app, sees Overview, Profiles, Targets, Components, and Logs, adds Discord or another process/folder/exe profile, selects an external proxy target, applies changes to the proxyfier layer, and sees component status plus recent activity. Later, installing Local sing-box adds a local target without changing the profile model.
|
|
**Truth Owner:** Source configuration lives in the Tauri app's Rust domain model and JSON files under `C:\ProgramData\VpnProxy`. Generated ProxiFyre and sing-box configs are derived artifacts. Privileged install/service operations are owned by explicit helper/installer flows, not by React UI state.
|
|
**Contract Boundary:** React UI calls typed Tauri commands. Tauri Rust backend validates and persists profiles/targets/components. Proxy routing is behind a `ProxyRouterAdapter` boundary, with ProxiFyre as the first adapter. Privileged operations go through explicit helper/install commands returning structured JSON.
|
|
**Cutover:** Supersede the prior Node `APP_MODE=windows` implementation direction. Keep existing gateway/client code intact. New Windows work lives under a separate Tauri app slice.
|
|
**Displaced Path:** The old plan to add Windows mode into `src/server`/`src/web` is demoted to historical context. Do not add a third app mode to the current Node server for this product.
|
|
**Value Density:** The smallest high-value slice is the desktop app MVP with external SOCKS5 target + ProxiFyre profile apply. Local sing-box is optional and comes after the proxyfier MVP is proven.
|
|
**Evidence Gate:** Evidence must include target-perspective app proof: built Tauri app or dev window screenshot/state, generated proxyfier config artifact, mocked or real helper response, and manual Windows checklist when privileged components are involved.
|
|
**Acceptance Evidence:** Automated tests pass for Rust/TypeScript domain logic, app build succeeds, the MVP can create a profile and generate/apply ProxiFyre config against an external target, and Windows manual evidence proves independent component behavior.
|
|
**Evidence Lane:** Record command output, app screenshots/state payloads, generated configs, and manual verification in `docs/goals/windows-modular-client/EVIDENCE.md`.
|
|
**Kill Criteria:** No Windows implementation inside current Node gateway/client server; no mandatory sing-box dependency; no generated config as source truth; no hidden installation during profile apply; no direct UI parsing of raw PowerShell/stdout.
|
|
**Architecture Slice:** New standalone Tauri app under `apps/windows-client`, plus docs updates that point from older Windows plans to this plan.
|
|
**Plan Review Gate:** Requires PRE review before implementation execution.
|
|
|
|
## Source Brief
|
|
|
|
Product and technology source brief:
|
|
|
|
- `docs/windows-client-product-tech-brief.md`
|
|
|
|
This plan turns that brief into an execution-ready implementation sequence.
|
|
|
|
## Outcome Contract
|
|
|
|
Plan title: Windows Tauri Proxy Client
|
|
|
|
Intent: Build a native-feeling Windows utility that manages app-level proxy routing while keeping Control App, Proxyfier Layer, and Local sing-box separately installable and operable.
|
|
|
|
Current behavior:
|
|
- Existing runtime code is a Node HTTP server and Vite/React web UI for gateway and Mac-style client modes.
|
|
- Earlier Windows docs describe adding Windows mode to that existing app.
|
|
- The selected direction is now Tauri 2 + React/TypeScript + Rust as a separate Windows desktop app.
|
|
|
|
Expected outcome:
|
|
- `apps/windows-client` contains a Tauri 2 app.
|
|
- The app has Overview, Profiles, Targets, Components, and Logs surfaces.
|
|
- Profiles store process/folder/exe source items.
|
|
- Targets store external proxy endpoints and optional local sing-box.
|
|
- ProxiFyre is the first proxy router adapter.
|
|
- Local sing-box is optional and never required for external target profiles.
|
|
|
|
Target-perspective output:
|
|
- User can install/run only the Control App.
|
|
- User can see Proxyfier and Local sing-box as separate components.
|
|
- User can add an external SOCKS5 target.
|
|
- User can add a Discord process profile.
|
|
- User can apply the profile to generated ProxiFyre config.
|
|
- User sees activity confirming whether apply succeeded or why it was blocked.
|
|
|
|
Truth owner:
|
|
- Rust core domain crate owns normalized models and validation.
|
|
- JSON source files under `C:\ProgramData\VpnProxy\config` own persisted profiles/targets/component preferences.
|
|
- `ProxyRouterAdapter` owns conversion from source models to proxy-router generated config.
|
|
- `SingBoxAdapter` owns generated local sing-box config and service contract.
|
|
- React UI owns only transient UI state.
|
|
|
|
Contract boundary:
|
|
- UI -> Tauri commands with typed request/response DTOs.
|
|
- Tauri commands -> Rust core services.
|
|
- Core services -> adapter traits.
|
|
- Adapter traits -> helper/install/service commands when privileged operations are needed.
|
|
- Helper/install commands return structured JSON, never unstructured text for app logic.
|
|
|
|
Cutover:
|
|
- Add superseded notes to old Windows Node-mode docs.
|
|
- Keep `docs/windows-client-product-tech-brief.md` as product brief.
|
|
- Make this `PLAN.md` the execution plan.
|
|
- Do not implement Windows by adding `APP_MODE=windows` to the current Node server.
|
|
|
|
Displaced path:
|
|
- Displace old "Windows mode in current web app" implementation.
|
|
- Displace "full install vs ProxiFyre-only" as dominant architecture; those become recipes composed from separate components.
|
|
|
|
Value density:
|
|
- MVP must prove app-level routing with external proxy target and ProxiFyre before local sing-box work expands scope.
|
|
|
|
Evidence gate:
|
|
- Tests and build are not enough.
|
|
- Capture app-visible state and generated config.
|
|
- Capture Windows manual evidence for service/helper actions when those tasks execute.
|
|
|
|
Acceptance evidence:
|
|
- `cargo test` or equivalent Rust tests for domain/adapters.
|
|
- frontend typecheck/test/build for React.
|
|
- Tauri dev/build command result.
|
|
- Screenshot or state dump showing Windows app surfaces.
|
|
- Generated ProxiFyre config from a sample profile.
|
|
- Manual Windows checklist when privileged components are present.
|
|
|
|
Non-goals:
|
|
- No Electron.
|
|
- No extension of the current Node gateway/client UI for Windows MVP.
|
|
- No global Windows system proxy changes.
|
|
- No transparent routing without a proxy router.
|
|
- No mandatory local sing-box.
|
|
- No direct coupling of UI to ProxiFyre-specific config shape.
|
|
|
|
Risk if wrong:
|
|
- If built inside the current Node app, the product will inherit gateway/client assumptions and conflict with the selected Tauri direction.
|
|
- If ProxiFyre is not behind an adapter, licensing or engine changes will force UI/data rewrites.
|
|
- If privileged work is hidden behind apply, users lose control and failures become hard to diagnose.
|
|
|
|
## Architecture Slice
|
|
|
|
Files/directories to create:
|
|
- `apps/windows-client/package.json`
|
|
- `apps/windows-client/vite.config.ts`
|
|
- `apps/windows-client/tsconfig.json`
|
|
- `apps/windows-client/src/main.tsx`
|
|
- `apps/windows-client/src/app/App.tsx`
|
|
- `apps/windows-client/src/app/routes.tsx`
|
|
- `apps/windows-client/src/api/tauriCommands.ts`
|
|
- `apps/windows-client/src/domain/types.ts`
|
|
- `apps/windows-client/src/features/overview/*`
|
|
- `apps/windows-client/src/features/profiles/*`
|
|
- `apps/windows-client/src/features/targets/*`
|
|
- `apps/windows-client/src/features/components/*`
|
|
- `apps/windows-client/src/features/logs/*`
|
|
- `apps/windows-client/src/styles/*`
|
|
- `apps/windows-client/src-tauri/Cargo.toml`
|
|
- `apps/windows-client/src-tauri/tauri.conf.json`
|
|
- `apps/windows-client/src-tauri/capabilities/default.json`
|
|
- `apps/windows-client/src-tauri/src/main.rs`
|
|
- `apps/windows-client/src-tauri/src/commands.rs`
|
|
- `apps/windows-client/src-tauri/src/models.rs`
|
|
- `apps/windows-client/src-tauri/src/storage.rs`
|
|
- `apps/windows-client/src-tauri/src/activity.rs`
|
|
- `apps/windows-client/src-tauri/src/adapters/proxy_router.rs`
|
|
- `apps/windows-client/src-tauri/src/adapters/proxifyre.rs`
|
|
- `apps/windows-client/src-tauri/src/adapters/singbox.rs`
|
|
- `apps/windows-client/src-tauri/src/helper.rs`
|
|
- `apps/windows-client/src-tauri/tests/*`
|
|
- `apps/windows-client/scripts/install-control-app.ps1`
|
|
- `apps/windows-client/scripts/install-proxyfier.ps1`
|
|
- `apps/windows-client/scripts/install-singbox.ps1`
|
|
|
|
Files to modify:
|
|
- `README.md`
|
|
- `docs/roadmap.md`
|
|
- `docs/superpowers/specs/2026-05-21-windows-client-design.md`
|
|
- `docs/superpowers/plans/2026-05-21-windows-client.md`
|
|
- `docs/goals/windows-modular-client/GOAL.md`
|
|
- `docs/goals/windows-modular-client/EVIDENCE.md`
|
|
|
|
Files to avoid:
|
|
- `src/server/*` except if a later explicit migration asks for shared code extraction.
|
|
- `src/web/*` for Windows MVP.
|
|
- Docker, entrypoint, and compose files.
|
|
- macOS installer.
|
|
|
|
Source of truth:
|
|
- `C:\ProgramData\VpnProxy\config\profiles.json`
|
|
- `C:\ProgramData\VpnProxy\config\targets.json`
|
|
- `C:\ProgramData\VpnProxy\config\components.json`
|
|
- `C:\ProgramData\VpnProxy\state\activity.json`
|
|
|
|
Derived artifacts:
|
|
- `C:\ProgramData\VpnProxy\generated\proxifyre-app-config.json`
|
|
- `C:\ProgramData\VpnProxy\generated\sing-box-config.json`
|
|
- ProxiFyre runtime config copied/backed up by helper/apply operation.
|
|
|
|
Read path:
|
|
- React UI calls Tauri commands.
|
|
- Tauri commands read JSON source via Rust storage service.
|
|
- Component status combines source preferences, filesystem checks, service checks, and helper responses.
|
|
|
|
Write path:
|
|
- React UI sends typed mutations.
|
|
- Rust validates with domain models.
|
|
- Rust writes source JSON atomically with backups.
|
|
- Apply generates derived config and invokes adapter/helper.
|
|
|
|
Integration points:
|
|
- ProxiFyre adapter emits `app-config.json` compatible output.
|
|
- Local sing-box adapter emits `sing-box` JSON config and validates via `sing-box check` when binary exists.
|
|
- Tauri sidecar/helper permissions are declared explicitly.
|
|
- Installer scripts may be launched or displayed explicitly, never silently during apply.
|
|
|
|
Migration/cutover:
|
|
- Older Windows docs point to this plan and source brief.
|
|
- Existing Node app remains gateway/client only.
|
|
- If shared subscription parsing is needed later, extract it intentionally into a shared package rather than importing server internals.
|
|
|
|
Acceptance evidence gate:
|
|
- MVP evidence must show external-target flow works without local sing-box.
|
|
- Optional sing-box evidence must show the same profile model can switch targets after installing sing-box.
|
|
|
|
## Task Board
|
|
|
|
### Task 1: Supersede Old Windows Node Plan
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- `docs/windows-client-product-tech-brief.md`
|
|
- old Windows docs/plans
|
|
|
|
Files allowed:
|
|
- `docs/superpowers/specs/2026-05-21-windows-client-design.md`
|
|
- `docs/superpowers/plans/2026-05-21-windows-client.md`
|
|
- `docs/roadmap.md`
|
|
- `README.md`
|
|
|
|
Files forbidden:
|
|
- Runtime source files.
|
|
|
|
Output:
|
|
- Old Windows documents clearly point to this Tauri plan and no longer read as implementation authority.
|
|
|
|
Evidence:
|
|
- `rg -n "Tauri|superseded|windows-client-product-tech-brief|apps/windows-client" README.md docs`
|
|
|
|
Depends on: none
|
|
|
|
Parallel safe: yes
|
|
|
|
### Task 2: Scaffold Tauri App Shell
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- Tauri 2 app structure
|
|
- Product brief UI surfaces
|
|
|
|
Files allowed:
|
|
- `apps/windows-client/package.json`
|
|
- `apps/windows-client/vite.config.ts`
|
|
- `apps/windows-client/tsconfig.json`
|
|
- `apps/windows-client/index.html`
|
|
- `apps/windows-client/src/*`
|
|
- `apps/windows-client/src-tauri/*`
|
|
|
|
Files forbidden:
|
|
- Current root `src/server/*`
|
|
- Current root `src/web/*`
|
|
|
|
Output:
|
|
- Tauri app starts with empty shell and five navigation surfaces.
|
|
- No business logic yet.
|
|
|
|
Evidence:
|
|
- `cd apps/windows-client && npm install && npm run build`
|
|
- `cd apps/windows-client/src-tauri && cargo test` if Rust tests exist
|
|
|
|
Depends on: Task 1
|
|
|
|
Parallel safe: no
|
|
|
|
### Task 3: Define Domain Models And Validation
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- Profile/Target/Component models from brief
|
|
|
|
Files allowed:
|
|
- `apps/windows-client/src-tauri/src/models.rs`
|
|
- `apps/windows-client/src-tauri/src/validation.rs`
|
|
- `apps/windows-client/src/domain/types.ts`
|
|
- `apps/windows-client/src-tauri/tests/domain_tests.rs`
|
|
|
|
Files forbidden:
|
|
- Adapter/helper code except trait references.
|
|
|
|
Output:
|
|
- Typed Rust models for `Profile`, `ProfileItem`, `Target`, `ComponentStatus`, `ActivityEntry`.
|
|
- TypeScript DTOs mirror Rust command responses.
|
|
- Validation rejects malformed ports/protocols but allows missing local sing-box.
|
|
|
|
Evidence:
|
|
- Rust tests showing process/folder/exe normalization and external target validation.
|
|
|
|
Depends on: Task 2
|
|
|
|
Parallel safe: no
|
|
|
|
### Task 4: Implement JSON Storage And Activity Log
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- Domain models from Task 3
|
|
|
|
Files allowed:
|
|
- `apps/windows-client/src-tauri/src/storage.rs`
|
|
- `apps/windows-client/src-tauri/src/activity.rs`
|
|
- `apps/windows-client/src-tauri/tests/storage_tests.rs`
|
|
|
|
Files forbidden:
|
|
- UI screens except command wiring stubs.
|
|
|
|
Output:
|
|
- Atomic JSON read/write for profiles, targets, components, and activity.
|
|
- Backups before overwriting source files.
|
|
- Config root defaults to `C:\ProgramData\VpnProxy`, with test override.
|
|
|
|
Evidence:
|
|
- Tests prove roundtrip, invalid JSON fallback behavior, backup creation, activity cap/sort.
|
|
|
|
Depends on: Task 3
|
|
|
|
Parallel safe: no
|
|
|
|
### Task 5: Add Proxy Router Adapter Boundary And ProxiFyre Adapter
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- Domain models and storage
|
|
|
|
Files allowed:
|
|
- `apps/windows-client/src-tauri/src/adapters/proxy_router.rs`
|
|
- `apps/windows-client/src-tauri/src/adapters/proxifyre.rs`
|
|
- `apps/windows-client/src-tauri/tests/proxifyre_adapter_tests.rs`
|
|
|
|
Files forbidden:
|
|
- Direct UI coupling to ProxiFyre config fields.
|
|
|
|
Output:
|
|
- `ProxyRouterAdapter` trait.
|
|
- `ProxiFyreAdapter` generates config from enabled profiles and targets.
|
|
- External target flow does not require sing-box.
|
|
|
|
Evidence:
|
|
- Test generates ProxiFyre config for Discord + external SOCKS5 target.
|
|
- Test blocks local-singbox target only when target requires missing component.
|
|
|
|
Depends on: Task 4
|
|
|
|
Parallel safe: no
|
|
|
|
### Task 6: Add Tauri Commands
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- Storage and adapter services
|
|
|
|
Files allowed:
|
|
- `apps/windows-client/src-tauri/src/commands.rs`
|
|
- `apps/windows-client/src-tauri/src/main.rs`
|
|
- `apps/windows-client/src/api/tauriCommands.ts`
|
|
- `apps/windows-client/src-tauri/tests/command_tests.rs`
|
|
|
|
Files forbidden:
|
|
- Full UI implementation beyond command call wrappers.
|
|
|
|
Output:
|
|
- Commands for status, profiles, targets, components, scan/resolve preview, apply, logs.
|
|
- Commands return structured responses only.
|
|
|
|
Evidence:
|
|
- Command tests or integration tests prove apply generates derived config and records activity using a mock adapter/helper.
|
|
|
|
Depends on: Task 5
|
|
|
|
Parallel safe: no
|
|
|
|
### Task 7: Build MVP UI
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- Tauri command API
|
|
- Product brief layout
|
|
|
|
Files allowed:
|
|
- `apps/windows-client/src/app/*`
|
|
- `apps/windows-client/src/features/overview/*`
|
|
- `apps/windows-client/src/features/profiles/*`
|
|
- `apps/windows-client/src/features/targets/*`
|
|
- `apps/windows-client/src/features/components/*`
|
|
- `apps/windows-client/src/features/logs/*`
|
|
- `apps/windows-client/src/styles/*`
|
|
|
|
Files forbidden:
|
|
- Rust adapter behavior except fixing DTO mismatches.
|
|
|
|
Output:
|
|
- Compact utility UI with Overview, Profiles, Targets, Components, Logs.
|
|
- User can create/edit profile, external target, and trigger apply.
|
|
- Missing sing-box is shown as valid optional state.
|
|
|
|
Evidence:
|
|
- `npm run build`
|
|
- Screenshot or browser/app state showing missing sing-box and usable external target flow.
|
|
|
|
Depends on: Task 6
|
|
|
|
Parallel safe: no
|
|
|
|
### Task 8: Implement Helper And Explicit Installer Boundary
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- Component model
|
|
- Security model from brief
|
|
|
|
Files allowed:
|
|
- `apps/windows-client/src-tauri/src/helper.rs`
|
|
- `apps/windows-client/src-tauri/capabilities/default.json`
|
|
- `apps/windows-client/scripts/install-control-app.ps1`
|
|
- `apps/windows-client/scripts/install-proxyfier.ps1`
|
|
- `apps/windows-client/scripts/install-singbox.ps1`
|
|
- `apps/windows-client/src-tauri/tests/helper_tests.rs`
|
|
|
|
Files forbidden:
|
|
- Hidden installer invocation inside profile apply.
|
|
|
|
Output:
|
|
- Helper command abstraction for status/service/apply.
|
|
- Installer scripts are explicit and idempotent.
|
|
- Tauri sidecar/shell permissions are narrow and documented.
|
|
|
|
Evidence:
|
|
- Helper tests with mock command runner.
|
|
- PowerShell parser checks for installer scripts.
|
|
- Capability file shows limited sidecar permissions.
|
|
|
|
Depends on: Task 6
|
|
|
|
Parallel safe: partly, after command DTOs are stable
|
|
|
|
### Task 9: Add Optional Local Sing-Box Adapter
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- sing-box target model
|
|
- service/helper boundary
|
|
|
|
Files allowed:
|
|
- `apps/windows-client/src-tauri/src/adapters/singbox.rs`
|
|
- `apps/windows-client/src-tauri/tests/singbox_adapter_tests.rs`
|
|
- `apps/windows-client/src/features/components/*`
|
|
- `apps/windows-client/src/features/targets/*`
|
|
|
|
Files forbidden:
|
|
- Making sing-box mandatory for external targets.
|
|
|
|
Output:
|
|
- Generate local sing-box config.
|
|
- Validate via `sing-box check` when binary exists.
|
|
- Local target appears only when installed/configured or as an explicit install prompt.
|
|
|
|
Evidence:
|
|
- Tests show external target apply works without sing-box.
|
|
- Tests show local-singbox target requires installed/running component.
|
|
|
|
Depends on: Tasks 5 and 8
|
|
|
|
Parallel safe: no
|
|
|
|
### Task 10: Package, Verify, And Record Evidence
|
|
|
|
Owner: main agent
|
|
|
|
Input:
|
|
- Completed MVP implementation
|
|
|
|
Files allowed:
|
|
- `apps/windows-client/*`
|
|
- `README.md`
|
|
- `docs/roadmap.md`
|
|
- `docs/goals/windows-modular-client/EVIDENCE.md`
|
|
|
|
Files forbidden:
|
|
- Unrelated app code.
|
|
|
|
Output:
|
|
- Build/test commands documented.
|
|
- README explains separate Control App, Proxyfier, and Local sing-box install flows.
|
|
- Evidence file captures automated and target-perspective proof.
|
|
|
|
Evidence:
|
|
- `npm run build`
|
|
- Rust tests
|
|
- Tauri build/dev proof
|
|
- generated ProxiFyre config summary
|
|
- UI screenshot/state
|
|
- Windows manual checklist, or clearly mark `implemented but unproven` for Windows-only service behavior if not run on a Windows host.
|
|
|
|
Depends on: all previous tasks
|
|
|
|
Parallel safe: no
|
|
|
|
## Manual Windows Verification Checklist
|
|
|
|
1. Install/run only Control App.
|
|
2. Verify Proxyfier and Local sing-box show missing as separate components.
|
|
3. Add external SOCKS5 target.
|
|
4. Add Discord process profile.
|
|
5. Apply profile; verify generated ProxiFyre config and activity entry.
|
|
6. Install Proxyfier separately; verify status changes.
|
|
7. Apply profile to real Proxyfier service.
|
|
8. Install Local sing-box separately.
|
|
9. Import subscription or config, select outbound, and start Local sing-box.
|
|
10. Switch existing profile from external target to Local sing-box and apply.
|
|
11. Stop/restart Proxyfier and Local sing-box separately.
|
|
12. Copy diagnostics and verify secrets are redacted.
|
|
|