fix(tunnel): auto-strip macOS quarantine xattr to prevent Gatekeeper stalls

Brew --cask installs (and every subsequent upgrade) tag the devtunnel
binary with com.apple.quarantine. When TermBeam runs as a long-lived
service (e.g. under pm2), the next spawn after a brew upgrade is held by
Gatekeeper until the user clicks Allow on a system dialog on the host
machine. While held, the auth probe fails with no output and the
watchdog misclassifies it as auth expiration, logging a misleading
'DevTunnel auth restored' message once the dialog is dismissed.

This patch:

- Adds stripQuarantine, hasQuarantine, and resolveBinaryPath helpers in
  src/tunnel/install.js. resolveBinaryPath handles the bare-name PATH
  lookup case (findDevtunnel returns 'devtunnel' when on PATH), so
  fs.realpathSync no longer throws on the actual fix path.
- stripQuarantine returns 'noop' / 'stripped' / 'failed' so callers can
  distinguish 'nothing to do' from 'permission refused'.
- Calls stripQuarantine after every successful install and once at every
  TermBeam startup before spawning devtunnel.
- isLoggedIn() self-heals: if the spawn fails AND the binary actually
  carries com.apple.quarantine, strip it and retry once. A 'failed'
  outcome surfaces a one-time error with the manual remediation command.
  Warnings are throttled to once per session to avoid log spam.
- Adds a troubleshooting section to the site explaining the issue and
  the auto-recovery behavior.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

packages/site/src/content/docs/troubleshooting.md

@@ -86,6 +86,27 @@ If TermBeam is running as a long-lived service (`termbeam service`) and the tunn
 
 You'll see `[WARN] Tunnel paused — waiting for network connectivity` in the logs followed by `[INFO] Network connectivity restored — resuming tunnel` when it recovers. If the logs instead show repeated `Tunnel restart returned no URL` with no final giveup, the watchdog is still cycling through its 10 restart attempts; wait a few minutes for it to settle into network-wait.
 
+### macOS: tunnel paused after a brew upgrade ("DevTunnel auth restored" loop)
+
+On macOS, `brew install --cask devtunnel` (and every subsequent upgrade) tags the binary with the `com.apple.quarantine` extended attribute. The first time TermBeam spawns the new binary from a non-interactive context (e.g. a `pm2`-managed service), Gatekeeper holds the spawn and pops a system dialog — until you click **Open** on the host machine, the auth probe reads as a failure and the watchdog logs:
+
+```text
+[INFO] DevTunnel auth restored — resuming tunnel
+```
+
+…right after you dismiss the dialog (the misleading message is because the spawn failure looks like an auth failure to the watchdog).
+
+TermBeam **automatically strips the quarantine attribute** on every startup and re-strips it as a self-heal step inside the auth probe, so this should not recur. If you still see the dialog, run:
+
+```bash
+xattr -dr com.apple.quarantine "$(brew --prefix)/Caskroom/devtunnel"
+spctl --assess --verbose "$(readlink -f "$(which devtunnel)")"
+```
+
+:::tip
+This is harmless — the binary is still signed by Microsoft (`TeamIdentifier=UBF8T346G9`). Stripping `com.apple.quarantine` only removes the "downloaded from the internet" tag that triggers the Gatekeeper dialog.
+:::
+
 ---
 
 ## Authentication Issues

src/tunnel/index.js

@@ -5,7 +5,7 @@ const os = require('os');
 const dns = require('dns');
 const EventEmitter = require('events');
 const log = require('../utils/logger');
-const { promptInstall } = require('./install');
+const { promptInstall, stripQuarantine, resolveBinaryPath, hasQuarantine } = require('./install');
 
 const TUNNEL_CONFIG_DIR = path.join(os.homedir(), '.termbeam');
 const TUNNEL_CONFIG_PATH = path.join(TUNNEL_CONFIG_DIR, 'tunnel.json');
@@ -100,16 +100,53 @@ function isNetworkReachable() {
   });
 }
 
+// One-time per-session flag so the "stripped quarantine" warning isn't
+// spammed if the auth-poll loop trips it repeatedly during a brew upgrade.
+let quarantineWarned = false;
+
 function isLoggedIn() {
-  try {
-    const out = execFileSync(devtunnelCmd, ['user', 'show'], {
+  const tryShow = () =>
+    execFileSync(devtunnelCmd, ['user', 'show'], {
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
       timeout: 10_000,
       windowsHide: true,
     });
+  try {
+    const out = tryShow();
     return out && !out.toLowerCase().includes('not logged in');
-  } catch {
+  } catch (err) {
+    // On macOS, brew upgrades silently re-tag the devtunnel binary with
+    // com.apple.quarantine, which causes Gatekeeper to block our spawn and
+    // makes this throw with no useful output. If we can prove the binary is
+    // actually quarantined, strip and retry once before reporting failure.
+    if (process.platform === 'darwin' && err && err.code !== 'ENOENT') {
+      const resolved = resolveBinaryPath(devtunnelCmd);
+      if (resolved && hasQuarantine(resolved)) {
+        const result = stripQuarantine(devtunnelCmd);
+        if (result === 'stripped') {
+          if (!quarantineWarned) {
+            log.warn(
+              'devtunnel was quarantined by macOS Gatekeeper (likely after a brew upgrade); ' +
+                'stripped com.apple.quarantine and retrying',
+            );
+            quarantineWarned = true;
+          }
+          try {
+            const out = tryShow();
+            return out && !out.toLowerCase().includes('not logged in');
+          } catch {
+            // fall through and return false
+          }
+        } else if (result === 'failed' && !quarantineWarned) {
+          log.error(
+            'devtunnel is quarantined by macOS Gatekeeper but quarantine removal failed. ' +
+              `Run manually: xattr -dr com.apple.quarantine "${resolved}"`,
+          );
+          quarantineWarned = true;
+        }
+      }
+    }
     return false;
   }
 }
@@ -638,6 +675,12 @@ async function startTunnel(port, options = {}) {
   }
   devtunnelCmd = found;
 
+  // On macOS, brew --cask installs (and upgrades) tag the binary with
+  // com.apple.quarantine. The first time we spawn devtunnel from a
+  // non-interactive context Gatekeeper would block it and prompt the user.
+  // Strip the attribute on every startup so brew upgrades don't break us.
+  stripQuarantine(devtunnelCmd);
+
   log.info('Starting devtunnel...');
   try {
     // Ensure user is logged in. Prefer Entra over GitHub — Entra tokens auto-refresh

src/tunnel/install.js

@@ -11,6 +11,95 @@ function getInstallDir() {
   return INSTALL_DIR;
 }
 
+/**
+ * Resolve a binary name or path to an absolute path. Bare names (e.g. just
+ * "devtunnel") are looked up on `$PATH`. Returns the realpath (symlinks
+ * resolved) on success, or `null` if the binary couldn't be found.
+ */
+function resolveBinaryPath(binPathOrName) {
+  if (!binPathOrName) return null;
+  if (path.isAbsolute(binPathOrName)) {
+    try {
+      return fs.realpathSync(binPathOrName);
+    } catch {
+      return null;
+    }
+  }
+  const PATH = process.env.PATH || '';
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const exts =
+    process.platform === 'win32'
+      ? (process.env.PATHEXT || '.EXE').split(';').map((e) => e.toLowerCase())
+      : [''];
+  for (const dir of PATH.split(sep)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, binPathOrName + ext);
+      try {
+        const stat = fs.statSync(candidate);
+        if (stat.isFile()) {
+          try {
+            return fs.realpathSync(candidate);
+          } catch {
+            return candidate;
+          }
+        }
+      } catch {
+        // not in this dir
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns true when the file at `absPath` carries the macOS
+ * `com.apple.quarantine` extended attribute. Always false on non-darwin.
+ */
+function hasQuarantine(absPath) {
+  if (process.platform !== 'darwin' || !absPath) return false;
+  try {
+    execFileSync('xattr', ['-p', 'com.apple.quarantine', absPath], {
+      stdio: 'pipe',
+      timeout: 3000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Strip the macOS `com.apple.quarantine` extended attribute from a binary.
+ * Brew casks tag downloaded binaries with this attribute, which causes
+ * Gatekeeper to block execution and pop a system dialog ("are you sure you
+ * want to open…") the first time the binary runs in a non-interactive
+ * context (e.g. spawned from a service). On the next brew upgrade the new
+ * binary is re-tagged, so this needs to run after every install and as a
+ * best-effort self-heal step at runtime.
+ *
+ * Accepts an absolute path OR a bare command name (which is resolved via
+ * `$PATH`). Returns one of:
+ *   - 'noop'     — non-darwin, unresolvable, or no quarantine attribute
+ *   - 'stripped' — quarantine was present and successfully removed
+ *   - 'failed'   — quarantine was present and removal failed (e.g. EPERM)
+ */
+function stripQuarantine(binPathOrName) {
+  if (process.platform !== 'darwin' || !binPathOrName) return 'noop';
+  const resolved = resolveBinaryPath(binPathOrName);
+  if (!resolved) return 'noop';
+  if (!hasQuarantine(resolved)) return 'noop';
+  try {
+    execFileSync('xattr', ['-d', 'com.apple.quarantine', resolved], {
+      stdio: 'pipe',
+      timeout: 5000,
+    });
+  } catch {
+    // Removal refused (e.g. EPERM). Verify outcome below.
+  }
+  return hasQuarantine(resolved) ? 'failed' : 'stripped';
+}
+
 function getBinaryName() {
   return process.platform === 'win32' ? 'devtunnel.exe' : 'devtunnel';
 }
@@ -83,6 +172,10 @@ async function installDevtunnel() {
     // Find the installed binary
     const found = findInstalledBinary();
     if (found) {
+      // On macOS, brew --cask tags the binary with com.apple.quarantine which
+      // causes Gatekeeper to block execution from non-interactive contexts.
+      // Strip it now so the first spawn doesn't trigger a system dialog.
+      stripQuarantine(found);
       log.info(`${green('✔')} DevTunnel CLI installed and verified successfully.`);
       return found;
     }
@@ -139,4 +232,11 @@ function findInstalledBinary() {
   return null;
 }
 
-module.exports = { installDevtunnel, promptInstall, getInstallDir };
+module.exports = {
+  installDevtunnel,
+  promptInstall,
+  getInstallDir,
+  stripQuarantine,
+  resolveBinaryPath,
+  hasQuarantine,
+};