aboutsummaryrefslogtreecommitdiffstats
path: root/packaging/win/README.md
diff options
context:
space:
mode:
authorChristophe Besson <cbesson@gmail.com>2026-09-04 17:29:24 +0200
committerChristophe Besson <cbesson@gmail.com>2026-09-04 17:29:24 +0200
commitb78288640d8c13cc0fb3f4ee7c82f3efac33940f (patch)
treef860bd35f2efd8b6781e8e279ee75389b5a06128 /packaging/win/README.md
parent13d145253a871ef47ef4344f90566eea21b994ab (diff)
downloadmeshbay-b78288640d8c13cc0fb3f4ee7c82f3efac33940f.tar.gz
feat: opt-in Windows service mode (boot-time, one elevation) + v1.0.0
The per-user Startup-folder launcher (W3) only ever runs after this user signs in. A real Windows Service would start earlier, but under LocalSystem/NetworkService -- accounts with no normal profile, so %LOCALAPPDATA%\meshbay\ (config, keystore, data) would not exist for it. Relocating storage to make that work is real surgery, deliberately not done here. Instead: a Scheduled Task, created once with admin rights, that runs AS THIS USER at boot without needing them to sign in first. `schtasks /create ... /ru <user> /rp ""` with no `/it` registers an S4U (Service For User) logon -- no password stored anywhere, and unlike LocalSystem it loads this account's own profile, so config_dir()/ data_dir() need zero changes. The cost: S4U carries no network credential, which the node never needed -- everything it touches is local disk plus outbound internet. Creating the task needs admin (a boot trigger touches system-wide scheduler state, the same reason /sc onlogon needed it); querying/starting/stopping an existing one does not -- Task Scheduler grants the owning user that much itself, which is what lets the Node page's Start/Stop/Restart drive it with no further UAC prompts. meshbay_node/platform.py service_install/_remove/_status/_run/_end -- mirrors autostart_* but for the Scheduled Task; TASK_NAME moved here (was decorative before) meshbay_node/daemon.py new `service install|remove|start|stop|status` verb; restart-daemon and reset now check for the service task too packaging/win/service.ps1 the installer-side equivalent (extraResource); status/run/end never self-elevate -- only install/remove do, exactly matching what Task Scheduler itself requires packaging/win/service-mode.ps1 ONE elevated helper running service.ps1 + firewall.ps1 together, so choosing service mode costs exactly one UAC prompt, not two build/installer.nsh the install-time choice: "run as a background service?" (one elevation, both jobs) vs the existing per-user + separate firewall question. Checked first, unelevated, so re-running setup with everything already configured asks nothing. Uninstall offers the matching one-elevation cleanup, default No. src/main.js winServiceTaskStatus/Run/End, wired into node:installed, node:service-status/-stop/-restart and node:start: when the Scheduled Task exists, drive it; otherwise fall back to the existing per-user spawn/kill path. This is the hard requirement -- Start/Stop/Restart from the Node page must work in either mode. node-page.js / locales a hint explaining why the per-user autostart toggle is absent when service mode is active (info.mode from the backend, no new field to gate on -- it just isn't sent in that case) package.json: 0.1.0 -> 1.0.0. Verified: electron-builder compiles the new NSIS choice logic and ships all three scripts; service.ps1's S4U install fails cleanly (Access denied) when run unelevated, and its status/run/end never touch "runas". Cannot verify the elevated success path myself (no admin in this session) -- that needs a real UAC click. Node suite 843 pass / 25 skip; test_packaging_win.py pins the one-elevation property, the S4U flags, and that main.js actually checks the service task in all three handlers. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Diffstat (limited to 'packaging/win/README.md')
-rw-r--r--packaging/win/README.md45
1 files changed, 43 insertions, 2 deletions
diff --git a/packaging/win/README.md b/packaging/win/README.md
index 01c8d1a..7bbec13 100644
--- a/packaging/win/README.md
+++ b/packaging/win/README.md
@@ -7,11 +7,13 @@ Linux). `meshbay-common` rides along inside the node runtime.
## What the installer contains
```
-%LOCALAPPDATA%\Programs\meshbay-client\
+%LOCALAPPDATA%\Programs\MeshBay\ (productName, not the npm package name)
├─ MeshBay.exe Electron client
├─ resources\
│ ├─ app.asar src/ + ui/ (the interface ships in the package)
-│ ├─ firewall.ps1 adds/removes the two inbound rules (see below)
+│ ├─ firewall.ps1 adds/removes the four inbound rules (see below)
+│ ├─ service.ps1 install/remove/status/run/end the boot-time task
+│ ├─ service-mode.ps1 elevated helper: service.ps1 + firewall.ps1 in one UAC prompt
│ └─ node-runtime\
│ ├─ meshbay-node.exe frozen daemon (PyInstaller onedir)
│ ├─ _internal\ … its Python + deps (aiortc, av, aioquic, …)
@@ -22,6 +24,9 @@ Linux). `meshbay-common` rides along inside the node runtime.
Runtime data stays where the node already puts it: `%LOCALAPPDATA%\meshbay\`
(`node.toml`, `keystore.enc`, `unlock.key`, `data\`). The installer never writes
there and the uninstaller never deletes it — installers place files, not secrets.
+That is also why service mode needed no code changes to `platform.py`: it runs
+as this same signed-in user (S4U, see below), so it is the same profile either
+way — not LocalSystem/NetworkService, which would have none of this.
`build/installer.nsh` also adds `…\resources\node-runtime` to the **per-user**
`Path` (`HKCU\Environment`) so `meshbay-node` works in a terminal, and takes it
@@ -29,6 +34,42 @@ back out on uninstall. New shells only — a `WM_SETTINGCHANGE` broadcast nudges
open ones. It uses stock `WordFunc.nsh` (the `EnVar` plugin is not in
electron-builder's NSIS bundle).
+## Autostart: two modes, one choice at install time
+
+**Per-user (default, no admin).** A `.vbs` in the Startup folder
+(`meshbay_node.platform._startup_vbs`), toggled from the Node page or
+`meshbay-node autostart install|remove`. Starts when *this user* signs in.
+
+**Service mode (one admin confirmation, at install time only).** A Scheduled
+Task, `meshbay_node.platform.service_install` / `packaging/win/service.ps1`,
+that starts **at boot, before anyone signs in**. A real Windows Service would
+run under LocalSystem/NetworkService — accounts with no normal user profile,
+so `%LOCALAPPDATA%\meshbay\` (config, keystore, data) would not exist for it.
+Relocating storage to make that work is real surgery, deliberately not this.
+
+The alternative used instead: `schtasks /create ... /ru <user> /rp ""` with no
+`/it` registers an **S4U** (Service For User) logon — no password stored
+anywhere, and unlike LocalSystem it loads *this account's own profile*, so
+`%LOCALAPPDATA%\meshbay\` keeps working with zero code changes. The cost: S4U
+carries no network credential (cannot reach a domain share as this user),
+which the node never needed — everything it touches is local disk plus
+outbound internet.
+
+Creating the task needs admin (a boot trigger touches system-wide scheduler
+state — the same reason `/sc onlogon` needed it too, back when Task Scheduler
+was tried for the per-user mode and abandoned for exactly that reason).
+Querying, starting and stopping an *already-created* task does not — Task
+Scheduler grants the owning user that much itself, which is what lets the Node
+page's Start/Stop/Restart drive it with no further UAC prompts
+(`src/main.js`'s `winServiceTaskStatus/Run/End`, mirroring `service.ps1`).
+
+**One elevation, not two.** Choosing service mode needs admin for both the
+Scheduled Task *and* the firewall rules; `service-mode.ps1` runs both from a
+single `ExecShellWait "runas"` in `installer.nsh`, so the choice costs exactly
+one UAC prompt. Re-running setup (an upgrade, a repair install) asks nothing
+if the firewall rules are already there — checked first, unelevated, the same
+pattern the per-user-only firewall step already used.
+
## Build
On a Windows machine with **Node ≥ 22**, **Python ≥ 3.12** (`py -3.12`) and