LanGuard: Instructions file for Claude Code

LanGuard

macOS menu-bar app. Turns Wi-Fi off when a wired LAN link goes up, on when it goes down. Replaces the old shell com.roy.wifitoggle LaunchAgent (the app removes it on first launch).

Layout

• LanGuard/ — app target (LanGuardApp.swift): MenuBarExtra (+ Settings… command); AppDelegate starts AppModel, shows the first-launch WelcomeWindow (didShowWelcome; skipped under LANGUARD_TEST=1, set by the UI test) and opens Settings on reopen (Finder/Raycast).
• LanGuardPackage/Sources/LanGuardFeature/ — all logic (modular, unit-tested):
  • InterfaceCatalog — enumerate + classify Ethernet/Wi-Fi via SystemConfiguration. isVirtual(bsdName:displayName:) flags bridge/VPN/VM/tunnel adapters (pure, tested).
  • NetworkMonitor — SCDynamicStore callbacks (link/IPv4) + NSWorkspace sleep/wake; per-interface link reads (SC kSCPropNetLinkActive, ifconfig fallback). Flap guard: ignores link changes while asleep (willSleepNotification → suspended), waits a settle interval after didWakeNotification before evaluating once, and debounces callback bursts/brief flaps (1.5s). Stops a docked Mac's Ethernet dropping on sleep + returning on wake from looking like a real unplug→replug.
  • WiFiController — CoreWLAN setPower / powerOn (no sudo, no shell).
  • Notifier — UNUserNotificationCenter wrapper; banners on Wi-Fi toggle (needs OS permission, requested on launch).
  • Log — opt-in file logger. When debugLoggingEnabled (Settings → Debug) is on, appends timestamped events to ~/Library/Logs/LanGuard/languard.log (rotates at ~1MB, one backup). Log.write is a no-op while off. revealInFinder() / clear() back the Settings buttons. Instrumented across start / evaluate / edges / setWiFiPower / sleep-wake so users can capture + send a log.
  • MenuIcon — MenuState (lan/wifi/paused, pure mapping) + MenuIconStyle (icon / icon+label / label) + MenuBarLabel view used as the MenuBarExtra label.
  • ToggleEngine — edge-based decision logic, dependencies injected → testable.
  • Handover — make-before-break moves. toLAN: wait until the LAN reaches the internet (Probe, TCP to 1.1.1.1:443 scoped by requiredInterfaceType), protection.settle() with preferWiFi=false, then Wi-Fi off (kept on if protection could not leave Wi-Fi). toWiFi (menu + global HotKey, recordable HotKeyCombo): Wi-Fi on → reachable → protection.settle() with preferWiFi=true → "safe to unplug" popup. Floating ProgressPanel while it runs. Pressed again while switchedToWiFi (LAN still plugged) → AppModel.backToLAN() (reset → reconcile → engine.reapply() → toLAN).
  • Protection — connection protection: a stable per-network /32 address A on whichever link is active + routes 0.0.0.0/1,128.0.0.0/1 -ifa A, so TCP connections survive LAN↔Wi-Fi (TCP is pinned to its source IP; A moves, the IP doesn't change). Own undebounced SCDynamicStore watcher + 5 s common-mode timer; serial queue; settings captured as a main-thread Snapshot. Link-flap refresh: a State:/Network/Interface/<if>/Link change on A's interface (or another en* on the same router) marks it pending; once the link is usable again the app re-runs up (down + up = fresh /1s + alias). A 0.25 s en8 flap left A + /1s in place and Network.framework flows to hosts in use then timed out for 12 h while kernel sockets worked (2026-10-30); also once after an adopt at launch. Only on networks (router IP@MAC) where LAN+Wi-Fi shared a router (learned) or ticked by hand; user "off" → disabledNetworks, never re-learned. 30-min hold only when the guardian tore down as unhealthy; 5-min hold on verify failure / no free address.
  • NetHelper — root side (quitting LanGuard KEEPS protection: the guardian guards it, the next launch adopts it; disable/panic/uninstall remove it): Resources/languard-net.sh → /Library/PrivilegedHelperTools/languard-net (verbs up/move/adopt/down/panic/arm/check/status; exit codes mirrored in NetHelper.Exit), LaunchDaemon com.roypadina.languard-net (KeepAlive guard loop runs check every 3 s; launchd only (PPID 1); default 10 s throttle, AbandonProcessGroup so a bootout never kills a check mid-down; stamps /var/run/languard-net.tick; never back to a 3 s StartInterval: the job-respawn flood + an open Login Items settings pane panicked launchd, 2026-10-24), sudoers /etc/sudoers.d/languard = that helper path only. State-changing verbs run one at a time under lockf (/var/run/languard-net.lock, 0600; on a 15 s timeout panic/down run unlocked, others exit 75). Guardian: a vanished interface is a normal strike (iface-gone); instant teardown only on corrupt state (bad-state) — an instant undock teardown raced the app's move (2026-10-09). Health = router via A AND TCP 1.1.1.1:443 via A vs the plain address (nc -G, never -w: macOS -w is idle-only, a dead SYN waits 75 s); toWiFi checks Net.internetVia(A) before "Safe to unplug", else back to LAN (2026-10-11 office outage). attach also adds the /1s -ifscope each OTHER en* on the same router (scope_others; down → unscope): sockets bound to the still-primary dock NIC (Tailscale NE → MagicDNS 100.100.100.100) otherwise get ENETUNREACH while A is on Wi-Fi = every name lookup SERVFAIL until unplug (root cause of the 10-11/10-12 office outages; by-IP checks never see it). attach and down unscope FIRST: with a scoped and an unscoped /1 on the same iface, route get returns the scoped one (IFSCOPE) → route_if empty → verify fails (1.1.5 bug). One admin prompt (install/remove). App never arms without a fresh tick. Panic: menu → helper panic → admin fallback → inline panicOneLiner (also README + ~/Raycast-Scripts/languard-panic.sh). Safety contract in the script header; reviewed by 3 Fable gates (2026-10-06).
  • AppSettings — UserDefaults. Physical wired + Wi-Fi = opt-out (disabledWired/disabledWiFi); virtual wired = opt-in (enabledVirtual, off by default). notificationsEnabled (Wi-Fi back on), notifyMovedToLAN, switchProgressPopup, safeToUnplugPopup, hotKey, menuIconStyle, protectionEnabled, protectedNetworks/disabledNetworks, per-network stable address + holds (UserDefaults dicts).
  • LoginItem / LegacyCleanup — SMAppService login item (self-healing, see below); removes legacy LaunchAgent.
  • AppModel — wires everything; singleton AppModel.shared. setWiFiPower is idempotent — only toggles interfaces whose power actually differs and only posts the banner when something really changed.
  • Views — MenuContent (menu), ConfigView(model:pane:) (one Settings pane; virtual adapters get a "virtual" badge), About window, progress panel. SettingsWindow = AppKit NSTabViewController (toolbar tabs, per-pane height, last pane remembered) hosting one ConfigView per pane; AccessoryWindows flips the app to .regular while Settings/About/Welcome are open. WelcomeWindow also holds LaunchAtLoginToggle and SupportBox.
• Config/ — xcconfig + entitlements. Un-sandboxed (CoreWLAN power + launchctl), ad-hoc signed, LSUIElement=YES (no Dock icon).