9remote 0.1.64 → 2.0.1

package/cli/utils/cloudflared.js

@@ -3,6 +3,7 @@ import path from "path";
 import https from "https";
 import os from "os";
 import { execSync, spawn } from "child_process";
+import { writePid, readPid, clearPid } from "./pids.js";
 
 // Network change detection
 let networkMonitorInterval = null;
@@ -14,7 +15,8 @@ const BINARY_NAME = "cloudflared";
 const IS_WINDOWS = os.platform() === "win32";
 const BIN_NAME = IS_WINDOWS ? `${BINARY_NAME}.exe` : BINARY_NAME;
 const BIN_PATH = path.join(BIN_DIR, BIN_NAME);
-const PID_FILE = path.join(os.homedir(), ".9remote", "cloudflared.pid");
+// Legacy PID file — kept for one-time cleanup of installs from older versions
+const LEGACY_PID_FILE = path.join(os.homedir(), ".9remote", "cloudflared.pid");
 
 // Track intentional shutdown to suppress exit logs
 let isIntentionalShutdown = false;
@@ -64,34 +66,58 @@ function getDownloadUrl() {
   return `${GITHUB_BASE_URL}/${binaryName}`;
 }
 
+// Emit progress at most every N ms to avoid render thrash
+const PROGRESS_THROTTLE_MS = 150;
+
 /**
- * Download file from URL
+ * Download file from URL with progress tracking
+ * @param {string} url
+ * @param {string} dest
+ * @param {(percent: number) => void} [onProgress]
  */
-async function downloadFile(url, dest) {
+async function downloadFile(url, dest, onProgress) {
   return new Promise((resolve, reject) => {
     const file = fs.createWriteStream(dest);
-    
+
     https.get(url, (response) => {
       if ([301, 302].includes(response.statusCode)) {
         file.close();
         fs.unlinkSync(dest);
-        downloadFile(response.headers.location, dest).then(resolve).catch(reject);
+        downloadFile(response.headers.location, dest, onProgress).then(resolve).catch(reject);
         return;
       }
-      
+
       if (response.statusCode !== 200) {
         file.close();
         fs.unlinkSync(dest);
         reject(new Error(`Download failed with status ${response.statusCode}`));
         return;
       }
-      
+
+      const total = parseInt(response.headers["content-length"] || "0", 10);
+      let received = 0;
+      let lastEmit = 0;
+      let lastPercent = -1;
+
+      response.on("data", (chunk) => {
+        received += chunk.length;
+        if (!onProgress || !total) return;
+        const now = Date.now();
+        const percent = Math.min(100, Math.floor((received / total) * 100));
+        if (percent !== lastPercent && now - lastEmit >= PROGRESS_THROTTLE_MS) {
+          lastEmit = now;
+          lastPercent = percent;
+          onProgress(percent);
+        }
+      });
+
       response.pipe(file);
-      
+
       file.on("finish", () => {
+        if (onProgress && total) onProgress(100);
         file.close(() => resolve(dest));
       });
-      
+
       file.on("error", (err) => {
         file.close();
         fs.unlinkSync(dest);
@@ -107,39 +133,40 @@ async function downloadFile(url, dest) {
 
 /**
  * Ensure cloudflared binary exists
+ * @param {(progress: { phase: "download" | "extract", percent?: number }) => void} [onProgress]
  */
-export async function ensureCloudflared() {
+export async function ensureCloudflared(onProgress) {
   if (!fs.existsSync(BIN_DIR)) {
     fs.mkdirSync(BIN_DIR, { recursive: true });
   }
-  
+
   if (fs.existsSync(BIN_PATH)) {
     if (!IS_WINDOWS) {
       fs.chmodSync(BIN_PATH, "755");
     }
     return BIN_PATH;
   }
-  
-  console.log("📥 Downloading tunnel binary...");
-  
+
   const url = getDownloadUrl();
   const isArchive = url.endsWith(".tgz");
   const downloadDest = isArchive ? path.join(BIN_DIR, "cloudflared.tgz") : BIN_PATH;
-  
+
   try {
-    await downloadFile(url, downloadDest);
-    
+    onProgress?.({ phase: "download", percent: 0 });
+    await downloadFile(url, downloadDest, (percent) => {
+      onProgress?.({ phase: "download", percent });
+    });
+
     if (isArchive) {
-      console.log("✅ Extracting...");
-      execSync(`tar -xzf "${downloadDest}" -C "${BIN_DIR}"`, { stdio: "pipe" });
+      onProgress?.({ phase: "extract" });
+      execSync(`tar -xzf "${downloadDest}" -C "${BIN_DIR}"`, { stdio: "pipe", windowsHide: true });
       fs.unlinkSync(downloadDest);
     }
-    
+
     if (!IS_WINDOWS) {
       fs.chmodSync(BIN_PATH, "755");
     }
-    
-    console.log("✅ cloudflared ready");
+
     return BIN_PATH;
   } catch (error) {
     console.error("❌ Failed to download cloudflared:", error.message);
@@ -199,11 +226,11 @@ export async function spawnQuickTunnel(localPort, onUrlUpdate = null) {
 
   const child = spawn(
     binaryPath,
-    ["tunnel", "--url", `http://localhost:${localPort}`, "--config", configPath, "--no-autoupdate"],
+    ["tunnel", "--url", `http://localhost:${localPort}`, "--config", configPath, "--no-autoupdate", "--protocol", "http2"],
     { detached: false, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }
   );
 
-  fs.writeFileSync(PID_FILE, child.pid.toString());
+  writePid("cloudflared", child.pid);
   isIntentionalShutdown = false;
 
   return new Promise((resolve, reject) => {
@@ -286,6 +313,7 @@ export async function spawnCloudflared(tunnelToken, onRestart = null) {
   
   const child = spawn(binaryPath, ["tunnel", "run", "--token", tunnelToken], {
     detached: false,
+    windowsHide: true,
     stdio: ["ignore", "pipe", "pipe"]
   });
   
@@ -360,8 +388,8 @@ export async function spawnCloudflared(tunnelToken, onRestart = null) {
   });
   
   // Save PID
-  fs.writeFileSync(PID_FILE, child.pid.toString());
-  
+  writePid("cloudflared", child.pid);
+
   // Start network monitor
   startNetworkMonitor();
   
@@ -372,18 +400,26 @@ export async function spawnCloudflared(tunnelToken, onRestart = null) {
  * Kill cloudflared process
  */
 export function killCloudflared() {
+  // Clean up legacy PID file from older installs (one-time migration)
   try {
-    if (fs.existsSync(PID_FILE)) {
-      isIntentionalShutdown = true;
-      const pid = parseInt(fs.readFileSync(PID_FILE, "utf8"));
-      // console.log(`🔄 Killing cloudflared process PID: ${pid}`);
-      process.kill(pid);
-      fs.unlinkSync(PID_FILE);
-      console.log(`✅ Cloudflared killed`);
+    if (fs.existsSync(LEGACY_PID_FILE)) {
+      const legacyPid = parseInt(fs.readFileSync(LEGACY_PID_FILE, "utf8"));
+      if (Number.isFinite(legacyPid)) {
+        isIntentionalShutdown = true;
+        try { process.kill(legacyPid); } catch {}
+      }
+      fs.unlinkSync(LEGACY_PID_FILE);
     }
-  } catch (error) {
-    // console.log(`⚠️  Error killing cloudflared: ${error.message}`);
-  }
+  } catch {}
+
+  const pid = readPid("cloudflared");
+  if (!pid) return;
+  isIntentionalShutdown = true;
+  try {
+    process.kill(pid);
+    console.log(`✅ Cloudflared killed`);
+  } catch {}
+  clearPid("cloudflared");
 }
 
 /**

package/cli/utils/permissions.js

@@ -25,13 +25,13 @@ export function checkPermissions() {
     let sr = false, ax = false, done = 0;
     const finish = () => { if (++done === 2) resolve({ screenRecording: sr, accessibility: ax }); };
 
-    // Accessibility: attempt a real keystroke action — fails without permission
-    exec(`osascript -e 'tell application "System Events" to key code 0 using {}'`,
+    // Accessibility: reading UI elements truly requires AX permission (reflects revoke instantly)
+    exec(`osascript -e 'tell application "System Events" to tell process "Finder" to get name of every window'`,
       { timeout: 3000 }, (err) => { ax = !err; finish(); });
 
-    // Screen Recording: capture 1px — fails silently without permission
-    exec(`screencapture -x -R 0,0,1,1 /tmp/9remote_perm_check.png && rm -f /tmp/9remote_perm_check.png`,
-      { timeout: 5000 }, (err) => { sr = !err; finish(); });
+    // Screen Recording: CGPreflightScreenCaptureAccess via CoreGraphics — reflects TCC state in realtime
+    exec(`osascript -e 'use framework "CoreGraphics"' -e "return (current application's CGPreflightScreenCaptureAccess()) as boolean"`,
+      { timeout: 3000 }, (err, stdout) => { sr = !err && stdout.trim() === "true"; finish(); });
   });
 }
 

package/cli/utils/pids.js

@@ -0,0 +1,114 @@
+/**
+ * Centralized PID management for 9remote long-lived processes.
+ *
+ * We track ONLY two PIDs — the minimum needed to safely release file locks
+ * during `npm i -g 9remote@latest` without killing unrelated apps on the
+ * machine:
+ *
+ *   - agent        → the CLI that holds dist/cli.cjs open. Its children
+ *                    (server node.exe + tray helper binary) die automatically
+ *                    when we kill the agent tree (`taskkill /F /T`).
+ *   - cloudflared  → spawned as a child of agent too, but tracked separately
+ *                    because it may become orphan if agent crashes, and
+ *                    because `killCloudflared()` is called at runtime for
+ *                    network-change restarts.
+ *
+ * PID files live in ~/.9remote/pids/<name>.pid. Update scripts kill by PID
+ * only — never by image name (taskkill /IM) or commandline match, since
+ * those would also terminate unrelated node.exe / cloudflared.exe processes.
+ */
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { execSync } from "child_process";
+
+const PIDS_DIR = path.join(os.homedir(), ".9remote", "pids");
+
+function ensureDir() {
+  try {
+    if (!fs.existsSync(PIDS_DIR)) fs.mkdirSync(PIDS_DIR, { recursive: true });
+  } catch {}
+}
+
+function pidPath(name) {
+  return path.join(PIDS_DIR, `${name}.pid`);
+}
+
+/** Write PID to ~/.9remote/pids/<name>.pid. Silent fail. */
+export function writePid(name, pid) {
+  if (!pid) return;
+  try {
+    ensureDir();
+    fs.writeFileSync(pidPath(name), String(pid));
+  } catch {}
+}
+
+/** Read PID from file, or null if missing/invalid. */
+export function readPid(name) {
+  try {
+    const raw = fs.readFileSync(pidPath(name), "utf8").trim();
+    const pid = parseInt(raw, 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Remove PID file. Silent fail. */
+export function clearPid(name) {
+  try {
+    fs.unlinkSync(pidPath(name));
+  } catch {}
+}
+
+/** Check if a PID is still alive (does not kill). */
+export function isAlive(pid) {
+  if (!pid) return false;
+  try {
+    // Signal 0 = existence check on all platforms
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Kill one tracked process by name. Uses SIGKILL on POSIX, `taskkill /F /PID`
+ * on Windows. Clears the PID file regardless of outcome.
+ * Returns true if a kill was attempted, false if no PID on record.
+ */
+export function killByName(name) {
+  const pid = readPid(name);
+  clearPid(name);
+  if (!pid) return false;
+  try {
+    if (process.platform === "win32") {
+      // taskkill /T also terminates the entire child tree (needed for systray
+      // helper which spawns its own child, and for detached background agent).
+      execSync(`taskkill /F /T /PID ${pid}`, { stdio: "ignore", windowsHide: true });
+    } else {
+      process.kill(pid, "SIGKILL");
+    }
+  } catch {}
+  return true;
+}
+
+/** Names of every tracked PID. Shared with update shell scripts.
+ *  NOTE: ptyDaemon is intentionally excluded — we never kill it to keep
+ *  terminal sessions alive across agent restarts / updates. */
+export const TRACKED_NAMES = ["cloudflared", "agent"];
+
+/** Kill every tracked 9remote process. Safe to call repeatedly. */
+export function killAll() {
+  // Cloudflared first so it can't reconnect mid-shutdown; agent's `/F /T`
+  // then sweeps server + tray (direct children).
+  for (const name of TRACKED_NAMES) {
+    killByName(name);
+  }
+}
+
+/** Absolute path to the PIDs directory (for shell scripts). */
+export function getPidsDir() {
+  return PIDS_DIR;
+}

package/cli/utils/token.js

@@ -1,3 +1,5 @@
+import { browserFetch } from "../../lib/constants.js";
+
 const TEMP_KEY_EXPIRY_MINUTES = 30;
 
 /**
@@ -8,7 +10,7 @@ const TEMP_KEY_EXPIRY_MINUTES = 30;
  */
 export async function createTempKey(apiKey, workerUrl) {
   try {
-    const response = await fetch(`${workerUrl}/api/temp-key/create`, {
+    const response = await browserFetch(`${workerUrl}/api/temp-key/create`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ 

package/cli/utils/tray.js

@@ -0,0 +1,251 @@
+/**
+ * System tray module — optional, silent fail if not supported
+ */
+
+import { spawn } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+let trayInstance = null;
+let trayState = { port: 0, tunnelUrl: "", running: false };
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// PNG 64x64 base64 for macOS/Linux (generated from agent/ui/public/favicon.svg)
+const TRAY_ICON_PNG = "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";
+
+// Windows requires ICO format; resolve ICO path across dev + bundled layouts
+const ICO_CANDIDATES = [
+  path.join(__dirname, "assets", "trayIcon.ico"),           // dev: agent/cli/utils/assets/
+  path.join(__dirname, "..", "assets", "trayIcon.ico"),      // bundled: agent/dist/assets/
+];
+
+function getIconBase64() {
+  if (process.platform === "win32") {
+    for (const p of ICO_CANDIDATES) {
+      try {
+        if (fs.existsSync(p)) return fs.readFileSync(p).toString("base64");
+      } catch {}
+    }
+    return TRAY_ICON_PNG;
+  }
+  return TRAY_ICON_PNG;
+}
+
+function isTraySupported() {
+  const platform = process.platform;
+  if (!["darwin", "win32", "linux"].includes(platform)) return false;
+  if (platform === "linux" && !process.env.DISPLAY) return false;
+  return true;
+}
+
+function buildTooltip() {
+  const { port, tunnelUrl, running } = trayState;
+  const status = running
+    ? (tunnelUrl ? "Tunnel ON" : "Local only")
+    : "Idle";
+  const url = `http://localhost:${port}`;
+  // Windows tray tooltip limit is ~127 chars; keep it compact but informative
+  return `9Remote • ${status}\nLocal: ${url}\nRight-click to open / quit`;
+}
+
+function buildMenu() {
+  const { port, tunnelUrl } = trayState;
+  const isWin = process.platform === "win32";
+  const statusLine = tunnelUrl
+    ? `9Remote (Port ${port}) • Tunnel ON`
+    : `9Remote (Port ${port}) • Local only`;
+  return {
+    icon: getIconBase64(),
+    title: isWin ? `9Remote - Port ${port}` : "",
+    tooltip: buildTooltip(),
+    items: [
+      { title: statusLine, tooltip: tunnelUrl || `http://localhost:${port}`, checked: false, enabled: false },
+      { title: "Open Web UI", tooltip: `Open http://localhost:${port} in your browser`, checked: false, enabled: true },
+      { title: "Shutdown", tooltip: "Stop 9Remote server, tunnel and quit", checked: false, enabled: true },
+    ],
+  };
+}
+
+/**
+ * Initialize system tray
+ * @param {{ port: number, onQuit: () => void, onOpenUI: () => void }} options
+ */
+export async function initTray({ port, onQuit, onOpenUI }) {
+  if (!isTraySupported()) return null;
+
+  try {
+    const mod = await import("systray");
+    const SysTray = mod.default?.default || mod.default;
+
+    trayState = { port, tunnelUrl: "", running: true };
+
+    trayInstance = new SysTray({ menu: buildMenu(), debug: false, copyDir: true });
+    // Tray helper is a direct child of agent; no separate PID file needed.
+    // `taskkill /F /T /PID <agent>` at update time terminates it along with
+    // the agent tree — safer than matching by image name.
+
+    trayInstance.onClick((action) => {
+      if (action.item.title === "Open Web UI") {
+        onOpenUI?.();
+      } else if (action.item.title === "Shutdown") {
+        onQuit?.();
+        killTray();
+        setTimeout(() => process.exit(0), 500);
+      }
+    });
+
+    trayInstance.onReady(() => {});
+    trayInstance.onError(() => {});
+
+    return trayInstance;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Update tray tooltip / status so the user knows current tunnel state.
+ * Safe to call before tray is ready — values are captured for next refresh.
+ */
+export function updateTrayTooltip({ tunnelUrl, running } = {}) {
+  if (tunnelUrl !== undefined) trayState.tunnelUrl = tunnelUrl;
+  if (running !== undefined) trayState.running = running;
+  if (!trayInstance) return;
+  try {
+    trayInstance.sendAction({
+      type: "update-menu",
+      menu: buildMenu(),
+      seq_id: -1,
+    });
+  } catch {}
+}
+
+export function killTray() {
+  const instance = trayInstance;
+  trayInstance = null;
+  if (instance) {
+    try { instance.kill(true); } catch {}
+  }
+}
+
+/**
+ * Show a native OS notification (balloon tip on Windows, toast on macOS/Linux).
+ * Silent fail if the platform tool isn't available.
+ * @param {{ title?: string, message: string }} opts
+ */
+export function showTrayNotification({ title = "9Remote", message }) {
+  const platform = process.platform;
+  if (!message) return;
+
+  if (platform === "win32") {
+    // Prefer Windows 10/11 Toast Notification (WinRT) so the popup actually
+    // appears on modern Windows (ShowBalloonTip is effectively deprecated and
+    // only lands silently in Action Center on Win10+). Falls back to the
+    // classic NotifyIcon balloon tip if WinRT is unavailable (older Windows,
+    // Server Core, constrained PowerShell).
+    const esc = (s) =>
+      String(s)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/'/g, "&apos;")
+        .replace(/"/g, "&quot;");
+    const escPs = (s) => String(s).replace(/'/g, "''");
+    const appId = "9Remote";
+    const toastXml =
+      `<toast><visual><binding template="ToastText02">` +
+      `<text id="1">${esc(title)}</text>` +
+      `<text id="2">${esc(message)}</text>` +
+      `</binding></visual></toast>`;
+    const ps = [
+      `try {`,
+      `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] > $null;`,
+      `[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType=WindowsRuntime] > $null;`,
+      `$xml = New-Object Windows.Data.Xml.Dom.XmlDocument;`,
+      `$xml.LoadXml('${escPs(toastXml)}');`,
+      `$toast = [Windows.UI.Notifications.ToastNotification]::new($xml);`,
+      `[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${escPs(appId)}').Show($toast);`,
+      `} catch {`,
+      `Add-Type -AssemblyName System.Windows.Forms;`,
+      `$n = New-Object System.Windows.Forms.NotifyIcon;`,
+      `$n.Icon = [System.Drawing.SystemIcons]::Information;`,
+      `$n.BalloonTipTitle = '${escPs(title)}';`,
+      `$n.BalloonTipText = '${escPs(message)}';`,
+      `$n.Visible = $true;`,
+      `$n.ShowBalloonTip(5000);`,
+      `Start-Sleep -Seconds 6;`,
+      `$n.Dispose();`,
+      `}`,
+    ].join(" ");
+    try {
+      const child = spawn(
+        "powershell.exe",
+        ["-NoProfile", "-WindowStyle", "Hidden", "-Command", ps],
+        { detached: true, stdio: "ignore", windowsHide: true }
+      );
+      child.unref();
+    } catch {}
+    return;
+  }
+
+  if (platform === "darwin") {
+    try {
+      const esc = (s) => String(s).replace(/"/g, '\\"');
+      const script = `display notification "${esc(message)}" with title "${esc(title)}"`;
+      const child = spawn("osascript", ["-e", script], { detached: true, stdio: "ignore" });
+      child.unref();
+    } catch {}
+    return;
+  }
+
+  // Linux / other POSIX
+  try {
+    const child = spawn("notify-send", [title, message], { detached: true, stdio: "ignore" });
+    child.unref();
+  } catch {}
+}
+
+export function openBrowser(url) {
+  const platform = process.platform;
+
+  // Windows: prefer `rundll32.exe` (GUI subsystem — no cmd window flash) over
+  // `cmd /c start` which briefly flashes a black console window even with
+  // `windowsHide: true`. Fallback to cmd/start if rundll32 ever fails.
+  if (platform === "win32") {
+    try {
+      const child = spawn("rundll32.exe", ["url.dll,FileProtocolHandler", url], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      child.unref();
+      return;
+    } catch {}
+    // Fallback: cmd /c start "" "url"
+    try {
+      const child = spawn("cmd.exe", ["/d", "/s", "/c", "start", "", url], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      child.unref();
+    } catch {}
+    return;
+  }
+
+  if (platform === "darwin") {
+    try {
+      const child = spawn("open", [url], { detached: true, stdio: "ignore" });
+      child.unref();
+    } catch {}
+    return;
+  }
+
+  // Linux / other POSIX
+  try {
+    const child = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+    child.unref();
+  } catch {}
+}