diff options
| -rw-r--r-- | docs/PACKAGING-GUIDE.md | 13 | ||||
| -rw-r--r-- | packages/meshbay-client/build/installer.nsh | 42 | ||||
| -rw-r--r-- | packages/meshbay-client/package.json | 4 | ||||
| -rw-r--r-- | packages/meshbay-node/tests/test_packaging_win.py | 55 | ||||
| -rw-r--r-- | packaging/win/README.md | 23 | ||||
| -rw-r--r-- | packaging/win/firewall.ps1 | 68 |
6 files changed, 190 insertions, 15 deletions
diff --git a/docs/PACKAGING-GUIDE.md b/docs/PACKAGING-GUIDE.md index 56504d4..c4f6b00 100644 --- a/docs/PACKAGING-GUIDE.md +++ b/docs/PACKAGING-GUIDE.md @@ -66,9 +66,16 @@ node (with `meshbay-common` inside it). There is no Windows hub. ### Install -Run the installer. It is **per-user** — no administrator prompt — and lands in -`%LOCALAPPDATA%\Programs\meshbay-client\`. The node daemon ships beside the app -at `resources\node-runtime\meshbay-node.exe`; the client finds it automatically. +Run the installer. It is **per-user** and lands in +`%LOCALAPPDATA%\Programs\meshbay-client\` without needing admin rights. The +node daemon ships beside the app at `resources\node-runtime\meshbay-node.exe`; +the client finds it automatically. + +It does ask one thing: **"Allow MeshBay through Windows Firewall now?"** — +say yes and one administrator confirmation adds both inbound rules the client +and the node need for WebRTC. Say no and the install finishes the same either +way; Windows will show its own "Allow access" dialog instead, once for each, +the first time they actually need to accept a connection. **ffmpeg** is required for video streaming and is *not* in the installer unless it was built with `-FfmpegDir`. Otherwise install it separately diff --git a/packages/meshbay-client/build/installer.nsh b/packages/meshbay-client/build/installer.nsh index 15a840f..67d103d 100644 --- a/packages/meshbay-client/build/installer.nsh +++ b/packages/meshbay-client/build/installer.nsh @@ -1,9 +1,11 @@ ; electron-builder NSIS customisation (auto-included: build/installer.nsh). ; -; Per-user install, no elevation (package.json build.nsis). This does two things -; beyond the default: put the bundled daemon on the user's PATH so `meshbay-node` -; works in a terminal, and clean up the one piece of state that lives outside -; the install directory (the W3 "run at sign-in" launcher). +; Per-user install, no elevation (package.json build.nsis). This does three +; things beyond the default: put the bundled daemon on the user's PATH so +; `meshbay-node` works in a terminal; offer to add the inbound firewall rules +; in one elevated step instead of two "Allow access" dialogs later; and clean +; up the one piece of state that lives outside the install directory (the W3 +; "run at sign-in" launcher). ; ; Deliberately NOT touched: ; - %LOCALAPPDATA%\meshbay\ (node.toml, keystore.enc, unlock.key, data/) -- @@ -12,9 +14,12 @@ !include "WinMessages.nsh" !include "WordFunc.nsh" +!include "LogicLib.nsh" !insertmacro WordAdd !insertmacro un.WordAdd +!define MB_PWSH "$SYSDIR\WindowsPowerShell\v1.0\powershell.exe" + ; The dir electron-builder drops resources into. `meshbay-node.exe` and its ; frozen Python live directly in here. A fixed suffix of $INSTDIR, so both the ; add (install) and the remove (uninstall, where $INSTDIR is still known) match @@ -34,6 +39,21 @@ ${WordAdd} "$0" ";" "+${MB_NODE_BIN}" $1 WriteRegExpandStr HKCU "Environment" "Path" "$1" SendMessage ${HWND_BROADCAST} ${WM_WININICHANGE} 0 "STR:Environment" /TIMEOUT=5000 + + ; Firewall. MeshBay.exe and meshbay-node.exe each bind UDP sockets for WebRTC, + ; and Windows prompts "Allow access" the first time each does. A per-user + ; installer cannot pre-create a firewall rule (that needs admin), so offer to + ; run one elevated helper now: one UAC prompt instead of two dialogs mid-use. + ; firewall.ps1 is idempotent and does nothing if the exes are missing. + ${IfNot} ${Silent} + MessageBox MB_YESNO|MB_ICONQUESTION \ + "Allow MeshBay through Windows Firewall now?$\n$\nMeshBay connects to other devices on your local network. Choosing Yes adds the rules in one step (Windows will ask for administrator confirmation). Choosing No is fine too -- Windows will ask you to allow access the first time MeshBay connects." \ + /SD IDYES IDNO mb_skip_fw + ExecShellWait "runas" "${MB_PWSH}" \ + '-NoProfile -ExecutionPolicy Bypass -File "$INSTDIR\resources\firewall.ps1" add' \ + SW_HIDE + mb_skip_fw: + ${EndIf} !macroend !macro customUnInstall @@ -45,6 +65,20 @@ WriteRegExpandStr HKCU "Environment" "Path" "$1" SendMessage ${HWND_BROADCAST} ${WM_WININICHANGE} 0 "STR:Environment" /TIMEOUT=5000 + ; Offer to take the firewall rules back out (needs admin again). A stale + ; allow-rule pointing at a deleted exe is inert, so this is opt-in and + ; default-No -- a silent uninstall skips it entirely. customUnInstall runs + ; before the files are removed, so firewall.ps1 is still there. + ${IfNot} ${Silent} + MessageBox MB_YESNO|MB_ICONQUESTION \ + "Remove MeshBay's Windows Firewall rules? This needs one administrator confirmation. They are harmless if left." \ + /SD IDNO IDNO mb_keep_fw + ExecShellWait "runas" "${MB_PWSH}" \ + '-NoProfile -ExecutionPolicy Bypass -File "$INSTDIR\resources\firewall.ps1" remove' \ + SW_HIDE + mb_keep_fw: + ${EndIf} + ; meshbay_node.platform._startup_vbs() -- if the user ran "meshbay-node ; autostart install" (or toggled it in the client), this points wscript at ; the binary we are about to delete, and would error at every sign-in. diff --git a/packages/meshbay-client/package.json b/packages/meshbay-client/package.json index 57acff8..7f5afcb 100644 --- a/packages/meshbay-client/package.json +++ b/packages/meshbay-client/package.json @@ -33,6 +33,10 @@ "from": "node-runtime", "to": "node-runtime", "filter": ["**/*"] + }, + { + "from": "../../packaging/win/firewall.ps1", + "to": "firewall.ps1" } ] }, diff --git a/packages/meshbay-node/tests/test_packaging_win.py b/packages/meshbay-node/tests/test_packaging_win.py index 77fb1e5..47a2842 100644 --- a/packages/meshbay-node/tests/test_packaging_win.py +++ b/packages/meshbay-node/tests/test_packaging_win.py @@ -71,6 +71,16 @@ def test_the_node_runtime_is_carried_as_an_extraresource(): "extraResources puts it") +def test_firewall_helper_is_carried_as_an_extraresource(): + """packaging/win/firewall.ps1 must ride into resources/, at the fixed + path installer.nsh invokes it from ($INSTDIR\\resources\\firewall.ps1).""" + extra = _pkg()["build"]["win"]["extraResources"] + entry = next((e for e in extra if e.get("to") == "firewall.ps1"), None) + assert entry, "no extraResources entry mapping to firewall.ps1" + assert entry["from"].endswith("packaging/win/firewall.ps1") + assert (ROOT / "packaging" / "win" / "firewall.ps1").exists() + + def test_dist_win_delegates_to_the_build_script(): """`dist` (Linux) delegates to build-client.sh; `dist:win` is its counterpart and must not be a second inline electron-builder invocation.""" @@ -166,6 +176,51 @@ def test_customInstall_stops_a_running_daemon_before_overwriting_it(): assert "taskkill /IM meshbay-node.exe /F" in body +# ── the one-time elevated firewall step ───────────────────────────────────── + +def _macro_body(nsh: str, name: str) -> str: + return nsh.split(f"!macro {name}", 1)[1].split("!macroend", 1)[0] + + +def test_the_installer_offers_one_elevated_firewall_step_instead_of_two_dialogs(): + """ + Adding a firewall rule needs admin; the install itself never elevates + (build.nsis allowElevation:false). So this must be opt-in (a Yes/No the + user can decline) and skipped entirely in a silent install — an + unattended `/S` install must never pop a UAC prompt on its own. + """ + nsh = NSH.read_text(encoding="utf-8") + install = _macro_body(nsh, "customInstall") + + assert "${IfNot} ${Silent}" in install, ( + "the firewall step is not guarded against silent installs") + assert 'MessageBox MB_YESNO' in install + assert 'ExecShellWait "runas"' in install + assert 'firewall.ps1" add' in install + + +def test_the_uninstaller_offers_to_remove_the_firewall_rules_default_no(): + """Opt-in on the way out too, and defaulting to No: a stale allow-rule + for a deleted exe is inert, so this should not nag.""" + nsh = NSH.read_text(encoding="utf-8") + uninstall = _macro_body(nsh, "customUnInstall") + + assert "${IfNot} ${Silent}" in uninstall + assert "/SD IDNO" in uninstall, "the uninstall firewall prompt should default to No" + assert 'firewall.ps1" remove' in uninstall + + +def test_firewall_ps1_targets_both_executables_and_is_idempotent(): + """One script, both rules — so installer.nsh only ever has to name it + once on the way in and once on the way out.""" + src = (ROOT / "packaging" / "win" / "firewall.ps1").read_text(encoding="utf-8") + assert "MeshBay.exe" in src + assert "node-runtime" in src and "meshbay-node.exe" in src + # Remove-then-add: a re-run (reinstall, or install after a manual add) + # must not leave duplicate rules. + assert src.index("Remove-NetFirewallRule") < src.index("New-NetFirewallRule") + + def test_the_bundled_daemon_goes_on_the_user_path_and_comes_back_off(): """ The installer has no console entry point of its own; without this the diff --git a/packaging/win/README.md b/packaging/win/README.md index 8c29785..7bd7f67 100644 --- a/packaging/win/README.md +++ b/packaging/win/README.md @@ -11,6 +11,7 @@ Linux). `meshbay-common` rides along inside the node runtime. ├─ 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) │ └─ node-runtime\ │ ├─ meshbay-node.exe frozen daemon (PyInstaller onedir) │ ├─ _internal\ … its Python + deps (aiortc, av, aioquic, …) @@ -88,14 +89,20 @@ publish their host candidate as an unresolvable `<uuid>.local` mDNS name that `aioice` discards — the browser always dials the node, never the reverse. So the node has to accept unsolicited inbound UDP from its peers. -**Windows Defender Firewall.** On the daemon's first run Windows pops a prompt -for `meshbay-node.exe`. Tick **both Private and Public** — a libvirt/VM adapter, -and sometimes a plain Ethernet one, registers as Public, and a Private-only rule -then silently drops every peer. The installer cannot pre-create this rule (it is -per-user and never elevates); the prompt is the mechanism. If you dismissed it, -add the rule by hand: *Windows Defender Firewall → Advanced → Inbound Rules → -New Rule → Program →* the bundled `…\resources\node-runtime\meshbay-node.exe` *→ -Allow → all profiles*. +**Windows Defender Firewall.** The setup wizard offers to add the inbound rules +for `MeshBay.exe` and `meshbay-node.exe` in one step — it needs one admin +confirmation (`build/installer.nsh` runs `firewall.ps1` via NSIS `ExecShellWait +"runas"`; the per-user install itself never elevates). Say yes and both +prompts you'd otherwise hit mid-use are gone; say no, or the UAC prompt is +dismissed, and Windows falls back to its own **"Allow access"** dialog the +first time each process binds a socket — tick **both Private and Public** then +(a libvirt/VM adapter, and sometimes a plain Ethernet one, registers as +Public; a Private-only rule silently drops every peer). Missed both? Add it by +hand: *Windows Defender Firewall → Advanced → Inbound Rules → New Rule → +Program →* the bundled `…\resources\node-runtime\meshbay-node.exe` *→ Allow → +all profiles*. `firewall.ps1` is idempotent and re-runnable +(`powershell -File resources\firewall.ps1 add`, elevated); it logs to +`%TEMP%\meshbay-firewall.log`. **A flat LAN needs nothing else.** The node offers a routable `192.168.x.y` host candidate and browsers on the same subnet connect straight to it — same as the diff --git a/packaging/win/firewall.ps1 b/packaging/win/firewall.ps1 new file mode 100644 index 0000000..abed109 --- /dev/null +++ b/packaging/win/firewall.ps1 @@ -0,0 +1,68 @@ +<# +.SYNOPSIS + Add (or remove) the inbound Windows Firewall rules MeshBay needs. + +.DESCRIPTION + WebRTC binds an ephemeral UDP port per connection and the browser always + dials the node (aioice cannot resolve the peer's mDNS `.local` candidate), + so the node must accept unsolicited inbound UDP. Without a rule, Windows + pops an "Allow access" dialog the first time each of MeshBay.exe and + meshbay-node.exe binds a socket. + + The installer runs this once, elevated, so the user answers one UAC prompt + instead of two firewall dialogs later. Declining the installer's offer is + fine -- the dialogs are the fallback. + + Shipped as an extraResource at <install>\resources\firewall.ps1, so it + locates the two executables from its own path and takes no arguments beyond + the action. Runs elevated and windowless, so it leaves a trace at + %TEMP%\meshbay-firewall.log. + +.PARAMETER Action + add (default) create/replace the rules + remove delete them +#> +[CmdletBinding()] +param( + [ValidateSet("add", "remove")] + [string]$Action = "add" +) + +$ErrorActionPreference = "Stop" +$log = Join-Path $env:TEMP "meshbay-firewall.log" +"[{0}] {1}" -f (Get-Date -Format s), $Action | Add-Content $log + +# This script sits at <install>\resources\firewall.ps1. +$resources = $PSScriptRoot +$install = Split-Path -Parent $resources +$GROUP = "MeshBay" + +$targets = @( + @{ Name = "MeshBay"; Path = Join-Path $install "MeshBay.exe" } + @{ Name = "MeshBay Node"; Path = Join-Path $resources "node-runtime\meshbay-node.exe" } +) + +try { + foreach ($t in $targets) { + # Idempotent: clear any existing rule of this name first. + Remove-NetFirewallRule -DisplayName $t.Name -ErrorAction SilentlyContinue + + if ($Action -eq "add") { + if (-not (Test-Path $t.Path)) { + " skip $($t.Name): $($t.Path) not found" | Add-Content $log + continue + } + New-NetFirewallRule -DisplayName $t.Name -Group $GROUP ` + -Direction Inbound -Action Allow ` + -Program $t.Path -Protocol UDP -Profile Any | Out-Null + " allowed $($t.Name) ($($t.Path))" | Add-Content $log + } + else { + " removed $($t.Name)" | Add-Content $log + } + } +} +catch { + " ERROR: $_" | Add-Content $log + throw +} |