v0.1.0-release-plan.md

VPN Router v0.1.0 release plan

Last updated: 2026-07-30 KST

Release goal

Deliver Windows x64 and Apple Silicon macOS builds with the same user-visible profile, site-routing, DNS protection, fail-safe, lifecycle, and bounded diagnostic semantics defined in docs/platform-parity-contract.md. Native networking, privilege, storage, signing, and packaging implementations remain isolated by platform.

The Windows artifact remains a one-file portable build. The macOS artifact is a minimum-macOS-15 app containing the required Packet Tunnel and DNS Proxy Network Extensions. A release tag is blocked until the current source passes both native platform matrices and docs/platform-parity-audit.md has no unproven common behavior.

The Windows portable work below is retained as implementation and dogfooding history; its completed checks alone no longer authorize the shared release tag.

The Windows single executable is a distribution format, not a single-process architecture. At runtime it extracts a versioned private payload and starts:

• an unelevated WinUI desktop app;
• an elevated background process for WireGuard, DNS, routes, and recovery.

Runtime files are cached under %LOCALAPPDATA%\VpnRouter\app\<version>-<payload-hash>. Profiles, DPAPI-protected secrets, diagnostics, and recovery state remain under the existing %LOCALAPPDATA%\VpnRouter data root.

v0.1.0 scope

Included:

• Windows 11 x64 dogfooding build;
• Apple Silicon macOS 15-or-later build with embedded Packet Tunnel and DNS Proxy System Extension;
• cross-platform behavior and safety parity per docs/platform-parity-contract.md;
• external WireGuard for Windows prerequisite detection;
• WireGuard .conf import with DPAPI-protected private keys;
• root-domain and subdomain routing with media CDN expansion;
• IPv4 site routes and target-domain AAAA filtering;
• VPN DNS proxy and browser secure-DNS warning;
• DNS filter handoff for the currently supported AdGuard service case;
• disconnect cleanup, manual restore, and next-launch crash recovery;
• one-file portable distribution with no Windows Service or installer registration;
• current-user-only portable storage and privileged IPC authorization;
• troubleshooting output suitable for dogfooding reports.

Deferred until after v0.1.0:

• Windows x86 and ARM64 builds, plus Intel macOS;
• OpenVPN, L2TP, and mobile clients;
• application-based routing and full IPv6 split routing;
• automatic update;
• Store/MSIX distribution and a conventional installer;
• installer scope selection between Current user and All users, including matching storage, service registration, ACL, upgrade, and removal behavior;
• provider account automation;
• account-dependent Netflix automation;
• captive-portal discovery, sign-in, and recovery.

Streaming acceptance decision

Streaming validation is complete for v0.1.0 when both Netflix and YouTube traffic are observed through a Japanese VPN exit. Automated player advancement is not a release blocker when the service resolves to Japan and the relevant media/CDN traffic is routed through the WireGuard interface.

Delivery phases

Phase 1: portable launcher foundation

• Add a small x64 launcher that embeds the app and backend payload.
• Extract the payload atomically into a versioned LocalAppData cache.
• Start the backend with UAC and all three production networking features enabled.
• Wait for backend IPC readiness, then start the unelevated UI.
• Produce VpnRouter-<version>-x64.exe from one repeatable build command.
• Keep repository secrets and imported WireGuard configs out of the payload.

Acceptance:

• A clean build produces exactly one user-facing distribution file.
• Launching it shows one UAC prompt and opens the dashboard.
• Launching it again does not start a second backend.
• No Windows Service or uninstall entry is created by the launcher.

Build command:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\windows\build-portable.ps1 -Version 0.1.0

Current verified artifact:

artifacts\portable\VpnRouter-0.1.0-x64.exe
Size: 195,529,964 bytes
SHA-256: 54D37DE05EDA397EB5BB4059EF76D98CC8DE920006796E5DE49966BAD7D236BC

The embedded-payload extraction path has been exercised with --extract-only. The first UAC/backend/UI launch remains an owner-operated dogfooding check because it enables real WireGuard activation, Windows DNS mutation, and route mutation.

Phase 2: dogfooding safety and lifecycle

• Define UI-close behavior: keep the backend alive while connected, otherwise exit it.
• Reconnect the UI to an already-running backend.
• Add backend/version handshake and stale backend detection.
• Restrict the named pipe to the launching user SID and administrators.
• Never stop or reconfigure third-party DNS, ad-blocking, antivirus, or VPN services automatically.
• Gate connection on exclusive local DNS port availability and a unique DNS response ownership test.
• Monitor DNS response ownership while connected and fail safe through full connection cleanup if ownership is lost.
• Validate cached payload hashes before execution.
• Bound each active static/dynamic route plan to 512 IPv4 host routes before mutation.
• Retain the active and immediately previous payload versions; clean older caches only while disconnected.
• Add a visible portable-data cleanup action that refuses to run while connected.

Acceptance:

• UI crash does not silently dismantle an active route;
• backend crash or forced termination is recovered on the next launch;
• a non-launching interactive process cannot issue privileged IPC commands;
• failed extraction or elevation produces a useful user-facing error.

Phase 3: dogfooding matrix

• Fresh launch with WireGuard installed; the owner waived the clean-machine and WireGuard-missing variants for v0.1.0.
• Import, rename, select/validate, and delete a sanitized WireGuard profile without changing the existing real-profile count or secret-file name set.
• Add and remove YouTube and Netflix rules.
• Confirm YouTube and Netflix resolve to a Japanese exit.
• Confirm unrelated traffic retains the normal route.
• Disconnect and verify DNS, routes, WireGuard adapter, and AdGuard restoration.
• Kill UI while connected and reopen it.
• Kill backend while connected and verify next-launch recovery.
• Reboot while connected and verify next-launch recovery.
• Exercise invalid profile and DNS-conflict automation plus real UAC cancellation; the owner waived the WireGuard-missing variant.
• Verify the failure-independent bounded troubleshooting schema with focused prohibited-pattern checks and an owner-inspected 19-line report.

Dogfooding findings are recorded with reproduction steps, expected behavior, actual behavior, recovery result, and the troubleshooting artifact timestamp. Credentials and raw WireGuard private keys must never be attached.

Phase 4: v0.1.0 release hardening

• Resolve trimming/serialization warnings or disable unsafe trimming for v0.1.0.
• Complete launcher/UAC readiness evidence through protocol, extraction, and cache automation plus live stale-backend rejection and UAC cancellation.
• Run the existing focused test executable and both solution builds.
• Set product and file versions to 0.1.0 consistently.
• Write a short README covering prerequisites, limitations, recovery, and data location.
• Generate SHA-256 checksums for the release artifact.
• Prepare the historical Windows unsigned public-preview artifact and document checksum verification and expected Windows warnings. It is not the shared parity release.
• Implement the macOS common behavior contract and focused automated checks.
• Produce a reproducible unsigned arm64/minimum-macOS-15 macOS Release package as compile/package evidence.
• Pass the current owner-signed macOS connection, DNS, route, lifecycle, recovery, Keychain, diagnostic, and accessibility matrix.
• Pass Developer ID nested signing, required Network Extension entitlement, notarization, stapling, Gatekeeper, and clean supported-Mac installation.
• Rebuild WinUI and pass all focused tests plus recovery/UI smoke checks on native Windows after the parity corrections.
• Tag only the exact artifact-producing commit as v0.1.0.

Release gates

All gates must pass before the v0.1.0 tag:

1. Release solution build succeeds without functional publish warnings.
2. Focused tests pass.
3. The one-file x64 artifact is reproducibly generated.
4. YouTube and Netflix are confirmed through Japan during dogfooding.
5. Normal disconnect, UI crash, backend crash, and reboot recovery leave DNS and routes healthy.
6. WireGuard private keys do not appear in logs, payloads, or troubleshooting output.
7. Known limitations and manual recovery instructions are documented.
8. The current macOS source passes the signed runtime matrix; compilation alone is not accepted as Network Extension evidence.
9. The macOS artifact contains both required Network Extensions and passes scripts/macos/verify-signed-app.sh --mode distribution --notarized.
10. Current native Windows WinUI builds and all focused tests pass after parity changes.
11. docs/platform-parity-audit.md contains no remaining common-behavior or release-proof gap.

Immediate work order

1. Produce an owner-signed macOS development build from the current source and complete the matrix in docs/macos-next-session.md.
2. Rebuild WinUI and rerun all focused, recovery, and UI smoke checks on native Windows from the same commit.
3. Produce the hardened Developer ID macOS artifact, notarize and staple it, then pass the signed-app verifier and clean supported-Mac installation.
4. Reconcile both result sets in docs/platform-parity-audit.md.
5. Build final artifacts from the exact candidate commit and create v0.1.0 only when every release gate is closed.

First dogfooding run

1. Confirm WireGuard for Windows is installed.
2. Stop any development VpnRouter.App or VpnRouter.Service process.
3. Run artifacts\portable\VpnRouter-0.1.0-x64.exe and approve the UAC prompt.
4. In Diagnostics, confirm WireGuard activation, DNS mutation, and route mutation are all enabled.
5. Import a real WireGuard profile, add youtube.com and netflix.com, and connect.
6. Confirm both services identify the exit as Japan while unrelated traffic retains the normal route.
7. Disconnect from the dashboard and confirm DNS, the WireGuard adapter, and routes are restored.
8. Confirm VPN Router did not stop, disable, or change the startup mode of AdGuard or another security product.
9. If normal recovery fails, run the existing administrator recovery script before continuing testing.

If another product owns or intercepts local DNS, VPN Router must refuse the connection and ask the user to disable that product's DNS protection manually. It must not stop the product itself. Do not share the imported .conf, its private key, or raw troubleshooting data without reviewing it for secrets.