[bug]: Remote SSH to LAN hosts fails with EHOSTUNREACH — missing NSLocalNetworkUsageDescription in Info.plist

[houllette]

Bug Description

Connecting a remote project to an SSH host on the local subnet fails
immediately with EHOSTUNREACH. The same host connects fine from a
terminal.

The cause is macOS Local Network Privacy. Emdash's Info.plist is missing
NSLocalNetworkUsageDescription, so macOS blocks the connection but has
no usage string to build a consent prompt from. The result is that Emdash
never appears in System Settings → Privacy & Security → Local Network,
so there is no toggle to enable and no way for the user to fix it.

The bundle currently sets NSAllowsLocalNetworking, which is an App
Transport Security key for relaxing HTTPS requirements on local hostnames.
It does not grant the Local Network privacy permission.

$ plutil -p /Applications/Emdash.app/Contents/Info.plist | grep -i localnetwork
"NSAllowsLocalNetworking" => true

This breaks remote development for any host on the user's LAN. Remotes
reachable over the public internet are unaffected, which likely masked it.

Same root cause as anthropics/claude-code#27828.

Steps to Reproduce

1. On macOS, have an SSH server on a machine on the same subnet
   (e.g. 10.7.1.68, reachable via ssh root@10.7.1.68 from Terminal).
2. In Emdash, go to Settings → Connections and add an SSH connection
   to that host (or select the alias from the ~/.ssh/config dropdown).
3. Click Test Connection.
4. Observe the failure.
5. Open System Settings → Privacy & Security → Local Network.
   Emdash is not listed, and there is no way to add it.

Actual vs Expected Behavior

Actual

Custom crypto binding not available
Local ident: 'SSH-2.0-ssh2js1.17.0'
Client: Trying 10.7.1.68 on port 22 ...
Socket error: connect EHOSTUNREACH 10.7.1.68:22 - Local (10.7.1.61:50496)

The TCP connect never completes. macOS logs the block:

$ sudo log stream --predicate 'eventMessage CONTAINS[c] "local network"' --info
UserEventAgent: (com.apple.networkextension) Got local network blocked
notification: pid: 9164, uuid: 4C4C4426-5555-3144-A164-8BF7EAB320E6,
bundle_id: (null)

The null bundle_id is why no entry is ever created in System Settings.

The same host connects fine from Ghostty, which does have Local Network
permission:

$ ssh -v root@10.7.1.68     # succeeds

Expected

macOS prompts for Local Network access on first attempt, Emdash appears
in the Local Network list, and the SSH connection succeeds.

emdash Version

v1.1.40

Operating System

macOS 27.0

Additional Context

Fix

Add the usage description to the electron-builder mac config:

"mac": {
  "extendInfo": {
    "NSLocalNetworkUsageDescription": "Emdash needs local network access to connect to SSH hosts on your network."
  }
}

Ruled out during debugging

• Code signature is valid and notarized:
  spctl -a -vv returns accepted, source=Notarized Developer ID,
  Developer ID Application: Arne Strickmann (2AZ6648627)
• App is running from /Applications, not a symlink or mounted DMG
• LaunchServices re-registration (lsregister -f -R -trusted) made no difference
• Network/routing is fine — same host reachable from other apps on the
  same machine

Workaround

Adding a Port 443 listener to sshd on the remote host and pointing
Emdash at :443 works, since macOS exempts ports 80 and 443 from the
Local Network check.

Possibly related

Some reports on Apple's developer forums describe apps that set
NSLocalNetworkUsageDescription correctly and still fail to appear in the
Local Network list. The missing key is clearly the first-order bug here,
but it may be worth verifying the fix on a clean macOS user account
(Local Network state is per-user).

[HAOoool]

AI authorship disclosure: This comment was authored by an AI agent running on the reporter's machine, based on a live debugging session with the human operator. All findings below were verified with real tool output (direct reads of the authorization store, unified system logs, controlled experiments). Full details: NousResearch/hermes-agent#81563 (comment)

Same class of bug — we investigated this in our project (Hermes desktop) and found the mechanism; please verify in your environment

We hit the identical symptom (Electron app, macOS 27, LAN access silently denied, no Local Network permission prompt ever) and spent two nights isolating it. Everything below was verified on our setup (macOS 27.0 26A5406e, Hermes desktop, standard electron-builder packaging). Your case may differ — but the check methods are included so you can verify quickly.

1. The prompt can be suppressed for locally-built Electron apps, so the grant never gets created.
macOS only shows the Local Network alert for programs in the undetermined state (TN3179 / WWDC20-10110 / WWDC24-10123). For our locally-built Electron shell, the responsible-process bundle ID resolved to (null) at judgment time, so the system fell back to the Electron framework UUID — and that fallback was gated by Electron's own grant state. Once any Electron app on the machine had been granted or denied Local Network, fresh bundle IDs never saw a prompt again. No prompt → no grant → permanent No route to host / EHOSTUNREACH.

2. The grant store is per bundle ID (and per interpreter path).
Grants live in /Library/Preferences/com.apple.networkextension.plist → PathController.Rules (NSKeyedArchiver), keyed by SigningIdentifier (bundle ID) or Path. System Settings → Privacy & Security → Local Network toggles write exactly this file (verified bidirectionally in our session). Undetermined rules carry DenyMulticast=True; granted ones DenyMulticast=False. You can read this file directly to see whether your app has a rule at all.

3. The usage-description key was not the fix in our case.
We packed NSLocalNetworkUsageDescription into the app (verified present in the built Info.plist) — a fresh bundle ID still never prompted and never connected. It is still worth adding as intent declaration, but it did not trigger the prompt for our class of app.

4. A workaround that worked for us (single-variable experiment).
Build/run with the same bundle ID as a signed release that has been granted once (or run the signed release once and accept the prompt). We took an Apple-Development-signed local build that was permanently denied under a fresh bundle ID, changed only appId in package.json to the granted ID, rebuilt — and it connected immediately. The grant survived arbitrary rebuilds (adhoc re-signing, repacks).

5. Quick check on an affected machine.
Settings → Privacy & Security → Local Network: if there is an existing "Electron" / "python3.11" / other entry, the fresh app's prompt may be suppressed by that entry's decision. Granting/toggling that entry changes nothing for the fresh bundle ID; the fresh ID needs its own rule, which only a prompt can create.

Our interpretation: an Electron responsible-process identity issue (bundle ID → null) interacting with macOS's per-bundle grant model. This may affect every Electron app on macOS — possibly worth an upstream (Electron) report eventually.

Full write-up with the complete test matrix, logs, grant-store dumps, and methodology: NousResearch/hermes-agent#81563 (comment)