PeekDesktop Auto-Updater

Technical documentation for PeekDesktop's in-place auto-update system. Zero external dependencies — built entirely on System.IO.Compression (BCL) and Win32 P/Invoke.

How It Works

User Experience

1. Background check — 2 seconds after startup, PeekDesktop queries the GitHub Releases API for the latest version
2. Notification — if a newer version exists, a balloon/toast notification appears: "Version X.Y.Z is available"
3. User prompt — clicking the balloon (or using tray menu → "Check for Updates") shows a dialog: "Download and install? PeekDesktop will restart automatically."
4. Automatic update — on "Yes", the app downloads, verifies, swaps, and restarts in ~1 second
5. Settings — users can disable background checks via tray menu → "Auto-Check for Updates"

The Update Sequence

┌─────────────────────────────────────────────────────────────────┐
│ 1. Query GitHub API: /repos/shanselman/PeekDesktop/releases/latest │
│ 2. Parse assets[] array → pick correct zip (x64 or arm64)      │
│ 3. Download zip to %TEMP%\PeekDesktop-update-{guid}.zip         │
│ 4. Extract PeekDesktop.exe → same directory as PeekDesktop.new.exe │
│ 5. Verify Authenticode signature + signer identity              │
│ 6. Preflight: verify directory is writable                      │
│ 7. Rename PeekDesktop.exe → PeekDesktop.old.exe                 │
│ 8. Rename PeekDesktop.new.exe → PeekDesktop.exe                 │
│ 9. Launch new PeekDesktop.exe --restarting                      │
│ 10. Remove tray icon, release mutex, exit                       │
└─────────────────────────────────────────────────────────────────┘

Architecture Detection

The updater uses RuntimeInformation.ProcessArchitecture to select the correct release asset:

Architecture	Asset pattern
X64	PeekDesktop-vX.Y.Z-win-x64.zip
Arm64	PeekDesktop-vX.Y.Z-win-arm64.zip

This means an x64 build running under emulation on ARM64 stays on x64. Users who want native ARM64 should download that build manually once.

---

Security

Authenticode Signature Verification

Every downloaded update is verified before installation using two layers:

1. Chain trust — WinVerifyTrust with WINTRUST_ACTION_GENERIC_VERIFY_V2 verifies the binary has a valid Authenticode signature from a trusted certificate authority, with full revocation checking (WTD_REVOKE_WHOLECHAIN)

2. Signer identity — after trust verification, the updater extracts the signer's display name using WTHelperProvDataFromStateData → WTHelperGetProvSignerFromChain → CertGetNameStringW, and compares it against the expected publisher substring ("Hanselman")

If either check fails, the update is rejected with a clear error message and no files are modified.

Resource Cleanup

WinVerifyTrust is called with WTD_STATEACTION_VERIFY followed by WTD_STATEACTION_CLOSE in a finally path to prevent leaking the Authenticode certificate store.

URL Validation

Release URLs are validated against https://github.com/shanselman/PeekDesktop/ before being used. The download uses the browser_download_url from the GitHub API response, which redirects to GitHub's CDN. WinHTTP follows HTTPS→HTTPS redirects automatically.

Download Safety

• Downloads are capped at 50 MB to prevent memory exhaustion
• WinHTTP read/query errors throw immediately (no silent truncation)
• Temp files are cleaned up on failure

---

The Swap Dance

The trickiest part of the auto-updater is replacing the running executable. Windows allows renaming a running exe (the OS holds a handle to the inode, not the filename), so the sequence is:

PeekDesktop.exe      (running)
PeekDesktop.new.exe  (verified new version)

Step 1: File.Move(PeekDesktop.exe → PeekDesktop.old.exe, overwrite: true)
Step 2: File.Move(PeekDesktop.new.exe → PeekDesktop.exe)
Step 3: CreateProcessW("PeekDesktop.exe" --restarting)
Step 4: Remove tray icon, release mutex, Environment.Exit(0)

Why the Exact Path Matters

The autostart registry entry (HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Run\PeekDesktop) stores the exact exe path. If the new exe doesn't land at exactly the same path with the same filename, "Start with Windows" breaks. That's why we do in-place replacement, not "install to a new version folder."

Rollback on Failure

If any step fails after the rename:

• If PeekDesktop.exe is missing but PeekDesktop.old.exe exists → rename it back
• Partial downloads (.new.exe, temp zips) are cleaned up
• The user sees an error dialog but the app keeps running on the old version

Startup Recovery

On every launch, CleanupPreviousUpdate() runs (after acquiring the mutex) to delete:

• PeekDesktop.old.exe — leftover from successful update
• PeekDesktop.new.exe — leftover from failed update
• PeekDesktop-update-*.zip in %TEMP% — leftover temp downloads

---

Mutex Handoff

PeekDesktop uses a named mutex (Local\PeekDesktop_SingleInstance) to prevent multiple instances. During an update restart:

1. Old process launches new process with --restarting flag
2. Old process releases the mutex and exits
3. New process detects --restarting and retries mutex acquisition for up to 5 seconds (20 × 250ms)
4. If the old process is slow to exit, AbandonedMutexException is caught and treated as success

The launch happens before the mutex release — if CreateProcessW fails, the mutex is never released, and the old process stays running with an error message.

---

Files Changed

File	Role
AppUpdater.cs	Core update logic: check, download, extract, verify, swap, restart, cleanup
NativeMethods.cs	WinVerifyTrust, WTHelper*, CertGetNameStringW, CreateProcessW P/Invoke
WinHttp.cs	DownloadToFile() — writes HTTP response to disk (50MB cap)
Program.cs	--restarting mutex retry, cleanup on startup, mutex release wiring
Settings.cs	AutoCheckForUpdates property (default: true)
TrayIcon.cs	"Auto-Check for Updates" toggle, balloon → prompt → install flow

---

Dependencies

Zero new NuGet packages. Everything uses:

Capability	Source	Binary cost
HTTP downloads	winhttp.dll (OS native, already in use)	0 KB
ZIP extraction	System.IO.Compression (BCL)	~200-400 KB
Signature verification	wintrust.dll + crypt32.dll (OS native)	0 KB
Process launch	kernel32.dll CreateProcessW (OS native)	0 KB
JSON parsing	System.Text.Json.Utf8JsonReader (already in use)	0 KB

---

Testing

Interop Harness Tests

7 auto-updater tests in PeekDesktop.InteropHarness:

Test	What it covers
Version comparison logic	Model shape, tag normalization
Asset matching by architecture	x64/arm64 selection, fake arch rejection
Release JSON deserialization	assets[] array parsing with Utf8JsonReader
Authenticode rejects unsigned	Fake PE file correctly rejected by WinVerifyTrust
WinHttp download to file	Get() + DownloadToFile() against real HTTPS endpoints
Zip extraction round-trip	Create zip → extract PeekDesktop.exe → verify content
WinVerifyTrust state cleanup	100 calls with no handle leak

Run with: dotnet run --project src\PeekDesktop.InteropHarness\PeekDesktop.InteropHarness.csproj

Manual Swap Dance Test

To test the full download→swap→restart flow locally:

1. Add #if DEBUG bypasses in AppUpdater.cs:
   • Around the version comparison (force update regardless of version)
   • Around the signature check (skip for unsigned dev builds)
2. Build debug: dotnet build src\PeekDesktop\PeekDesktop.csproj
3. Run: dotnet run --project src\PeekDesktop\PeekDesktop.csproj
4. Right-click tray → "Check for Updates" → Yes
5. Watch it download v0.8.5, swap, and restart
6. Verify: About → should show v0.8.5

Full Signed Test

To test with real Authenticode verification:

1. Tag a new version: git tag v0.9.0 and push
2. The CI workflow builds, signs (Azure Trusted Signing), and creates a GitHub Release
3. Run the previous signed release — it should auto-update to v0.9.0
4. Verify the signer identity check passes in the log

---

Design Decisions

Why not a separate updater process?

A separate updater exe adds complexity (two binaries to ship, coordinate, keep in sync). Since Windows allows renaming running executables, the app can update itself in-place.

Why not Squirrel, WinSparkle, or other update frameworks?

They pull in significant dependencies that conflict with the project's goal of minimal binary size and zero NuGet runtime deps. The entire auto-updater adds ~200-400 KB (from System.IO.Compression) vs megabytes for a framework.

Why WinHTTP instead of HttpClient?

HttpClient pulls in the entire managed networking stack (~1 MB in AOT). WinHTTP uses the OS HTTP+TLS stack at zero binary cost and is already used for update checks.

Why not download in the background automatically?

The user should consent before we download and replace their executable. A ~2 MB download on metered connections deserves a prompt. The "Auto-Check for Updates" toggle controls only the check, not the download.

Why require Authenticode verification?

Without it, a compromised GitHub release or MITM attack could inject a malicious binary. The signature check ensures only properly signed binaries from the expected publisher are installed.

What about the signer name constant?

NativeMethods.cs contains ExpectedSignerSubstring = "Hanselman". This must match the CN or display name from the Azure Trusted Signing certificate. After signing a release, verify with signtool verify /pa /v PeekDesktop.exe and update the constant if needed.

---

Transition for Existing Users

Users on v0.8.5 and earlier have the old AppUpdater that only opens the browser. Their upgrade path:

1. They see "new version available" → opens GitHub Releases page
2. They download and extract manually (one last time)
3. From that point forward, all updates are automatic via this auto-updater

This is an inherent one-time transition — there's no way to silently upgrade the updater itself without the user installing the new version first.