RoamSwitch Architecture & Security Whitepaper

§1About this document

RoamSwitch is a menu-bar app for the Mac. Depending on how much you trust the network you are currently connected to, it automatically switches the macOS firewall, sharing services, AirDrop, and DNS. It also watches for ARP spoofing, ports open to the outside, USB storage, and ransomware-like encryption activity, and when it detects something dangerous it will go as far as cutting off traffic with the packet filter (pf) — an emergency air-gap.

In other words, RoamSwitch installs a root-privileged daemon and, if it wanted to, could stop all network traffic on the Mac. It is built by one person, and "please trust me" is not enough to justify that privilege. So instead, this document explains the design in a form you can verify.

Who this is for

• Engineers deciding whether to install it
• Security researchers and journalists who want to understand the internals before a review or an article
• Security staff at partner companies evaluating an internal rollout or OEM bundling

What this document does not cover

It does not go into detection-threshold tuning, false-positive statistics, or UI walkthroughs. What it explains is four things: privileges, process boundaries, data flow, and cryptography. The feature specifications themselves are in the bundled MCP resource roamswitch://docs/features and in the in-app help.

What is disclosed, and how far (disclosure policy)

This document is written on the assumption that an attacker already has the distributed binary. Every endpoint URL, identifier, file path, XPC protocol, and embedded public key that appears here can be pulled out of the shipping RoamSwitch.app in a few minutes with strings, codesign -d, or a traffic proxy. Writing them down here therefore gives an attacker nothing new. The only thing it advances is a reviewer's understanding.

On the other hand, server-side implementation that cannot be seen from the binary — rate-limit thresholds, keys, admin endpoints, the DB schema, the Firebase project layout — is not included. The OEM and partner integration design is also out of scope here and is covered in a separate internal document. "What you can learn by observing the client" is the disclosure line for this document.

§2Components and the trust boundary

RoamSwitch.app is made up of three executables. Only one of them is privileged; the other two run with login-user rights. All three ship with Hardened Runtime enabled, Developer ID signed, and notarized.

Entitlements and signing

• All three targets have ENABLE_HARDENED_RUNTIME = true.
• App Sandbox is disabled (com.apple.security.app-sandbox = false). The helper's and MCPServer's entitlements are empty dictionaries.
• Distribution builds are Developer ID Application signed, Apple notarized, and stapled (§10).

§3The privileged helper

How it is registered

The helper is registered as a LaunchDaemon using SMAppService.daemon(plistName:). The plist embedded in the app (Contents/Library/LaunchDaemons/com.tetsuharu.RoamSwitch.Helper.plist) declares only Label, BundleProgram, a single MachServices entry, and AssociatedBundleIdentifiers. Because of how SMAppService works, registration is not even possible unless the app is in /Applications. On the first registration, the helper does not become active until the user approves it by hand in System Settings.

Whose connections it accepts (ClientValidator)

The helper inspects the connecting process in NSXPCListener's shouldAcceptNewConnection and hands out HelperProtocol only to those that pass. The inspection uses the audit_token rather than the PID, to avoid PID reuse and TOCTOU.

# Code-signing requirement demanded of the caller in Release builds
identifier "com.tetsuharu.RoamSwitch"
  and anchor apple generic
  and certificate leaf[subject.OU] = "GV76B6G4YU"

This requirement is checked with SecCodeCopyGuestWithAttributes and SecStaticCodeCheckValidity, and the connection is dropped if it does not pass. Only DEBUG builds drop the team-ID pin, for development convenience. What actually ships is always a Release build.

What the helper can do (the complete list)

The privileged operations defined in Shared/HelperProtocol.swift are all of them. There is no privileged API that is not listed here.

State inside the helper

• HelperTool.shared is a single instance shared across connections. It used to be a separate instance per connection, so an emergency containment that opened a new connection could hit a race that lost track of "which services to bring back."
• The sharing-service and DNS backups are only mutated on a serial queue (stateQueue).

§4How the packet filter (pf) is handled

Two features touch pf: the emergency air-gap, and the dev-server port guard. Both of them always go through a single entry point, PFRulesetCoordinator, and never run pfctl -f themselves.

Why there is a single entry point

Previously the two features each loaded rules with pfctl -f independently, competing over pf's single main ruleset. If the port guard's narrow rule block ... port {…} was loaded after the air-gap's block drop all, you could end up in a state where the screen said "isolated" but the Mac was still reachable. This bug was found by actually attacking the machine from another host, and was fixed in 1.4.3 (the story is written up in docs/marketing/zenn/03_lan_side_attack_test.md).

How it works now

• Rebuilt in full every time. The entire required ruleset is rebuilt from the current state and applied in one shot. It is never applied as a diff.
• One serial queue. Every pf change runs on the same DispatchQueue, so whether it came from an XPC connection, the helper's startup, or the failsafe timer, changes are processed in order.
• The priority is as follows (higher wins):
  1. Emergency air-gap → set skip on lo0 and block drop all (nothing else is considered)
  2. Dev-server guard → block drop in quick proto tcp ... port { … }
  3. Neither → reload /etc/pf.conf and return pf to its original state
• Read back after applying. pfctl -sr reads the rules back to confirm that block drop all, or each port's rule, is actually loaded. A case where pfctl -f was silently ignored is not treated as success.
• The temp file is written to a path containing a UUID and deleted once applied (v1.4.5 dropped the fixed path in favor of a hard-to-guess one). The state directory is /Library/Application Support/RoamSwitch.

§5How a block is applied, and how it lifts

The three kinds of block are each different

How the air-gap is kept from lingering

• It lifts after 10 minutes at most. Right after startup, and on a 60-second timer, the helper runs releaseAirGapIfExpired(), and if the timestamp in /Library/Application Support/RoamSwitch/pf_airgap_since is older than 10 minutes it force-lifts the block. Even if the app crashed or was killed and never reached the "lift" button, traffic returns on its own.
• It re-applies after a reboot or a daemon respawn. On startup the helper reads the on-disk state with reapplyFromDisk() and restores it itself, in the order air-gap, port guard, system default (the 10-minute rule applies here too).
• A failed lift is treated as a failure. If block drop all could not actually be removed, the timestamp is written back so that the failsafe timer and the retry have something to converge on. The screen never falsely shows "lifted."
• You can take back control at any time — with the lift button in the modal, or simply by turning off Wi-Fi.

§6Everyday untrusted-network protection

When you connect to a network you have not registered, the "protection level" switch does not use pf. It simply changes standard OS settings in a way that can be reversed later.

None of this is a new blocking mechanism that RoamSwitch adds — it is just toggling OS settings. If you delete the app, the only thing that stops is the network-dependent switching; the last OS settings that were applied stay as they are. Nothing is left locked, but if you want to err on the safe side, set it back to "Open" on a trusted network before uninstalling.

§7Data handling and Zero Telemetry

What stays on the Mac

Traffic that leaves the machine (the complete list)

There is no code anywhere that collects and sends diagnostic results, port information, URLs, or logs. No analytics SDK and no crash-reporter SDK are included. The only external library is Sparkle (updates). What goes out to the network is these four, and that is all.

§8The MCP server security model

RoamSwitchMCPServer is a standalone command-line tool bundled at RoamSwitch.app/Contents/MacOS/. An MCP client such as Claude Desktop or Claude Code launches it as a subprocess and talks to it over stdio (newline-delimited JSON-RPC 2.0). The official SDK would not build against this machine's macOS SDK, so it is implemented by hand on top of Foundation's JSONSerialization.

What the design constrains

• It is read-only. There is simply no API for changing the security level, isolating a port, or ejecting a device. This is not something forgotten in v1 — it is left out deliberately. Letting external code (here, an LLM) rewrite a security tool's protection state would break trust for every user.
• It opens no socket. It neither registers a service nor listens. It reads one line from stdin, returns one line on stdout, and then the client ends the process.
• It sends nothing out. All diagnostics complete inside the Mac.
• It reads settings from a different domain. UserDefaults(suiteName: "com.tetsuharu.RoamSwitch") reads the app's domain explicitly (its own bundle-ID domain is empty). It only reads; it does not write.

The tools it exposes

The instructions field in the initialize response also states plainly, "Cannot change security level, isolate ports, or eject devices," communicating the capability boundary to the client-side LLM. The MCP resources (roamswitch://docs/*) are read-only Markdown documents as well.

§9License activation cryptography

The token

• It uses Ed25519 (Curve25519 signatures). The public key is embedded in the app (LicenseVerifier.embeddedPublicKeyBase64). The corresponding private key exists only in the license backend (a Firebase Functions environment variable) and is not in the repository.
• The signed data is canonical JSON. The signature is created and verified over the exact bytes produced by encoding LicensePayload (license key, tier, device hash, issued-at, expiry, seat count) with JSONEncoder's .sortedKeys and .withoutEscapingSlashes.
• It is designed to fail closed. If the embedded key is missing or malformed, or if the signature or the canonical JSON cannot be produced, the result is not "verified" — it returns invalidSignature.

Device binding

device_hash = SHA-256( "RoamSwitch-LifetimeSalt-v1" : lowercase(IOPlatformUUID) )

The raw hardware UUID is not sent to the server. In the rare case where IOKit does not return a UUID, it falls back to a random UUID kept in UserDefaults. At verification time, if the token's device_hash does not match the current device hash, the result is deviceMismatch.

It works offline

The default is a one-time (Lifetime) purchase; expires_at is checked only when is_lifetime is false. Seat count is expressed by tier — 2 for personal Pro, 5 for Team.

§10Distribution and updates

Signing and notarization (scripts/release.sh)

1. Run xcodebuild archive (Release, manual signing, Developer ID Application).
2. Export with -exportArchive as method: developer-id.
3. After notarytool submit --wait, run stapler staple on the .app.
4. Verify with spctl -a -t exec -vv.
5. Re-zip after stapling to produce the Sparkle update artifact (so the notarization ticket is included and it runs offline without a Gatekeeper warning).
6. Build the DMG, notarize and staple the DMG as well, and verify with stapler validate.

Updates (Sparkle 2.9.6)

Before an update is applied, the EdDSA signature listed in the appcast is verified against the SUPublicEDKey embedded in the app. The private signing key exists only in the build environment. The appcast is served over HTTPS. Delta updates are signature-verified the same way.

§11Threat model, and what we don't do

What RoamSwitch is meant to handle

• Probing and attacks from an attacker on the same LAN, or from a compromised IoT device. It responds with stealth, exposed-port auditing, and isolation from outside.
• Exposure on a network you don't trust. It automatically stops sharing services and AirDrop.
• Detecting ARP spoofing (a man-in-the-middle attack), and an emergency air-gap on detection. "Preventing" it on a home router is essentially impossible, so the approach is to "notice it and cut faster than a human would."
• Finding dev servers and databases (Redis, MongoDB, Elasticsearch, and so on) exposed on 0.0.0.0 without authentication, and blocking them from outside.
• Catching ransomware-like unauthorized encryption activity early and stopping all traffic (it does not rely on signatures).
• Auto-ejecting USB storage that is not allowed, and automatically running a ClamAV scan on attached storage (optional).

What we have decided not to do

• It is not a replacement for antivirus. ClamAV and XProtect are used as auxiliaries; RoamSwitch on its own is not a general-purpose malware detector.
• It is not a guarantee. It is one layer in a defense-in-depth stack, not something that "completely prevents ransomware." Marketing copy is reviewed on this premise too.
• It cannot protect an already-compromised root or kernel. If an attacker already has root, they can remove the helper's pf rules too.
• It does not prevent ARP spoofing (only detection and after-the-fact blocking).
• It is not a substitute for enterprise DHCP snooping or Dynamic ARP Inspection.

Attack surface that installing RoamSwitch adds

Appendix ACheck it yourself

Everything stated in this document can be verified against the distributed artifact with the following commands.

Signing and notarization

# Developer ID signature and team ID
codesign -dvvv /Applications/RoamSwitch.app 2>&1 | grep -E 'Authority|TeamIdentifier|flags'

# whether the notarization ticket is stapled
stapler validate /Applications/RoamSwitch.app
spctl -a -t exec -vvv /Applications/RoamSwitch.app

# signatures of the bundled helper / MCP server
codesign -dvvv /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchHelper
codesign -dvvv /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer

Entitlements (no network-send permission)

codesign -d --entitlements :- /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchHelper
codesign -d --entitlements :- /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer
# → an empty entitlements dictionary. There are no app-sandbox / network-client keys

Measuring the traffic

# Run Little Snitch / tcpdump alongside and confirm no traffic during normal use
sudo tcpdump -i any -n 'host not 127.0.0.1' and 'not port 53'
# No traffic other than license activation, the update check, and ClamAV updates

The privileged helper itself

# the registered LaunchDaemon
sudo launchctl print system/com.tetsuharu.RoamSwitch.Helper

# the pf rules currently loaded (the real state of the air-gap / port guard)
sudo pfctl -sr

# the helper's state directory
ls -la "/Library/Application Support/RoamSwitch/"

The MCP server's response (offline check)

BIN=/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
              '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | "$BIN"
# serverInfo and the definitions of the 5 tools come back. No network connection happens

The MCP server's source and tests

git clone https://github.com/lafine1211/roamswitch-mcp
cd roamswitch-mcp
swift build -c release        # same source as the shipping binary
swift test                    # unit, adversarial-input, stdio, mutation fuzzing
# SECURITY_TESTING.md has what's tested and the issues found so far

Device identifier

# the raw value bound into the token (only the salted SHA-256 is ever sent)
ioreg -d2 -c IOPlatformExpertDevice | awk -F'"' '/IOPlatformUUID/{print $4}'