feat(packaging): offer one elevated firewall step instead of two dialogs

Installing used to mean clicking through two separate Windows "Allow
access" prompts later — one for MeshBay.exe, one for meshbay-node.exe —
each confusing on its own and worse before the exe carried a version
resource. Adding a firewall rule needs admin, and the installer is
deliberately per-user with no elevation, so this can only ever be opt-in.

packaging/win/firewall.ps1 (new, shipped as an extraResource at
resources\firewall.ps1): idempotent add/remove of the two inbound UDP
rules ("MeshBay", "MeshBay Node"), grouped, logged to
%TEMP%\meshbay-firewall.log. Locates both executables from its own path,
no arguments needed beyond the action.

build/installer.nsh: customInstall asks "Allow MeshBay through Windows
Firewall now?" and runs firewall.ps1 via NSIS ExecShellWait "runas" — one
UAC prompt — only when not ${Silent}; declining or dismissing UAC falls
back to Windows' own per-process prompts, unchanged. customUnInstall
offers the same in reverse, defaulted to No (a stale rule for a deleted
exe is inert, so this should not nag on the way out) and skipped for a
silent uninstall.

Verified: rebuilt MeshBay-Setup-0.1.0.exe (electron-builder compiles the
new LogicLib.nsh / ExecShellWait NSIS successfully); firewall.ps1 run
unelevated fails cleanly into its log ("Access is denied") rather than
silently doing nothing, confirming the fallback path. Node suite 835
pass / 25 skip.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

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
+}