forge-remote 0.1.2 → 0.1.4

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "forge-remote",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Desktop relay for Forge Remote — monitor and control Claude Code sessions from your phone",
   "type": "module",
-  "license": "AGPL-3.0",
+  "license": "UNLICENSED",
   "author": "Daniel Wendel <daniel@ironforgeapps.com> (https://ironforgeapps.com)",
   "repository": {
     "type": "git",
@@ -22,7 +22,6 @@
   "files": [
     "src/",
     "firestore.rules",
-    "LICENSE",
     "README.md"
   ],
   "scripts": {

package/src/cli.js

@@ -3,10 +3,9 @@
 // Forge Remote Relay — Desktop Agent for Forge Remote
 // Copyright (c) 2025-2026 Iron Forge Apps
 // Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
-// AGPL-3.0 License — See LICENSE
 
 import { program } from "commander";
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 import { readFileSync, existsSync, writeFileSync } from "fs";
 import { join } from "path";
 import { hostname, homedir } from "os";
@@ -67,10 +66,14 @@ function loadSdkConfig() {
     return null;
   }
 
+  // Validate project ID before using it in any command.
+  if (!/^[a-z][a-z0-9-]{4,28}[a-z0-9]$/.test(projectId)) return null;
+
   // 3. Fetch via Firebase CLI.
   try {
-    const output = execSync(
-      `firebase apps:sdkconfig web --project ${projectId}`,
+    const output = execFileSync(
+      "firebase",
+      ["apps:sdkconfig", "web", "--project", projectId],
       { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
     );
 
@@ -110,7 +113,7 @@ function loadSdkConfig() {
     if (!config.apiKey || !config.projectId) return null;
 
     // Cache for next time.
-    writeFileSync(cachedPath, JSON.stringify(config, null, 2));
+    writeFileSync(cachedPath, JSON.stringify(config, null, 2), { mode: 0o600 });
     return config;
   } catch {
     return null;

package/src/cloudflared-installer.js

@@ -1,7 +1,6 @@
 // Forge Remote Relay — Desktop Agent for Forge Remote
 // Copyright (c) 2025-2026 Iron Forge Apps
 // Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
-// AGPL-3.0 License — See LICENSE
 
 import { execSync } from "child_process";
 import {

package/src/google-auth.js

@@ -1,7 +1,6 @@
 // Forge Remote Relay — Desktop Agent for Forge Remote
 // Copyright (c) 2025-2026 Iron Forge Apps
 // Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
-// AGPL-3.0 License — See LICENSE
 
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
@@ -86,28 +85,66 @@ export async function getAccessToken() {
 /**
  * Enable Anonymous Authentication for the given Firebase project.
  * Uses the Identity Toolkit Admin v2 API.
+ *
+ * If the project hasn't had Auth initialized yet (CONFIGURATION_NOT_FOUND),
+ * we first initialize the Identity Platform, then enable Anonymous.
  */
 export async function enableAnonymousAuth(projectId) {
   const token = await getAccessToken();
 
-  const response = await fetch(
-    `https://identitytoolkit.googleapis.com/admin/v2/projects/${projectId}/config?updateMask=signIn.anonymous.enabled`,
-    {
-      method: "PATCH",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-        "X-Goog-User-Project": projectId,
+  const patchAuth = async () => {
+    return fetch(
+      `https://identitytoolkit.googleapis.com/admin/v2/projects/${projectId}/config?updateMask=signIn.anonymous.enabled`,
+      {
+        method: "PATCH",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          "X-Goog-User-Project": projectId,
+        },
+        body: JSON.stringify({
+          signIn: {
+            anonymous: {
+              enabled: true,
+            },
+          },
+        }),
       },
-      body: JSON.stringify({
-        signIn: {
-          anonymous: {
-            enabled: true,
+    );
+  };
+
+  let response = await patchAuth();
+
+  // If config doesn't exist yet, initialize Identity Platform first.
+  if (!response.ok) {
+    const err = await response.json().catch(() => ({}));
+    const errMsg = err.error?.message || "";
+
+    if (errMsg.includes("CONFIGURATION_NOT_FOUND")) {
+      // Initialize Identity Platform for this project.
+      const initResp = await fetch(
+        `https://identitytoolkit.googleapis.com/v2/projects/${projectId}/identityPlatform:initializeAuth`,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            "X-Goog-User-Project": projectId,
           },
         },
-      }),
-    },
-  );
+      );
+
+      if (!initResp.ok) {
+        const initErr = await initResp.json().catch(() => ({}));
+        throw new Error(
+          `Failed to initialize Identity Platform: ${initErr.error?.message || initResp.statusText}`,
+        );
+      }
+
+      // Retry enabling Anonymous Auth after initialization.
+      response = await patchAuth();
+    }
+  }
 
   if (!response.ok) {
     const err = await response.json().catch(() => ({}));
@@ -119,6 +156,64 @@ export async function enableAnonymousAuth(projectId) {
   return true;
 }
 
+// ─── API Key Management ─────────────────────────────────────────────────────
+
+/**
+ * Remove browser-only restrictions from the project's API key.
+ *
+ * Firebase creates a "Browser key" with browserKeyRestrictions, which blocks
+ * requests from mobile apps (they don't send HTTP referrers). We keep the
+ * API target restrictions but remove the platform restriction so the key
+ * works from iOS and Android.
+ */
+export async function removeBrowserKeyRestriction(projectId, projectNumber) {
+  const token = await getAccessToken();
+
+  // List all keys for the project.
+  const listResp = await fetch(
+    `https://apikeys.googleapis.com/v2/projects/${projectNumber}/locations/global/keys`,
+    { headers: { Authorization: `Bearer ${token}` } },
+  );
+
+  if (!listResp.ok) {
+    throw new Error("Failed to list API keys.");
+  }
+
+  const listData = await listResp.json();
+  const keys = listData.keys || [];
+
+  for (const key of keys) {
+    if (key.restrictions?.browserKeyRestrictions) {
+      // Remove browser restriction but keep API target restrictions.
+      const updateResp = await fetch(
+        `https://apikeys.googleapis.com/v2/${key.name}?updateMask=restrictions`,
+        {
+          method: "PATCH",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            restrictions: {
+              apiTargets: key.restrictions.apiTargets || [],
+            },
+          }),
+        },
+      );
+
+      if (!updateResp.ok) {
+        const err = await updateResp.json().catch(() => ({}));
+        throw new Error(
+          `Failed to update API key: ${err.error?.message || updateResp.statusText}`,
+        );
+      }
+      return true;
+    }
+  }
+
+  return false; // No browser-restricted keys found.
+}
+
 // ─── Google Cloud API Enablement ─────────────────────────────────────────────
 
 /**
@@ -252,9 +347,11 @@ export async function createServiceAccountKey(projectId, serviceAccountEmail) {
 /**
  * Deploy Firestore security rules via the Firebase Rules REST API.
  *
- * Two-step process:
+ * Three-step process:
  *   1. Create a new ruleset containing the rules source.
- *   2. Update (or create) the `cloud.firestore` release to point to it.
+ *   2. Update (or create) the `cloud.firestore` release for the (default) database.
+ *   3. Also deploy to `cloud.firestore/database/default` for the named "default"
+ *      database (firebase CLI creates a named db, not the (default) alias).
  */
 export async function deployFirestoreRules(projectId, rulesContent) {
   const token = await getAccessToken();
@@ -293,41 +390,46 @@ export async function deployFirestoreRules(projectId, rulesContent) {
   const ruleset = await rulesetResponse.json();
   const rulesetName = ruleset.name;
 
-  // Step 2: Update existing release, or create if it doesn't exist yet
-  const releaseName = `projects/${projectId}/releases/cloud.firestore`;
-  const releaseBody = {
-    release: {
-      name: releaseName,
-      rulesetName: rulesetName,
-    },
-  };
+  // Step 2: Deploy the ruleset as the release for the (default) database.
+  const releaseNames = [`projects/${projectId}/releases/cloud.firestore`];
 
-  let releaseResponse = await fetch(
-    `https://firebaserules.googleapis.com/v1/${releaseName}`,
-    {
-      method: "PATCH",
-      headers,
-      body: JSON.stringify(releaseBody),
-    },
-  );
-
-  if (!releaseResponse.ok && releaseResponse.status === 404) {
-    // Release doesn't exist yet — create it
-    releaseResponse = await fetch(
+  for (const releaseName of releaseNames) {
+    // Try creating the release first (works for new projects).
+    let releaseResponse = await fetch(
       `https://firebaserules.googleapis.com/v1/projects/${projectId}/releases`,
       {
         method: "POST",
         headers,
-        body: JSON.stringify(releaseBody),
+        body: JSON.stringify({
+          name: releaseName,
+          rulesetName: rulesetName,
+        }),
       },
     );
-  }
 
-  if (!releaseResponse.ok) {
-    const err = await releaseResponse.json().catch(() => ({}));
-    throw new Error(
-      `Failed to deploy rules release: ${err.error?.message || releaseResponse.statusText}`,
-    );
+    if (!releaseResponse.ok && releaseResponse.status === 409) {
+      // Release already exists — update it via PATCH (requires wrapper + updateMask).
+      releaseResponse = await fetch(
+        `https://firebaserules.googleapis.com/v1/${releaseName}?updateMask=rulesetName`,
+        {
+          method: "PATCH",
+          headers,
+          body: JSON.stringify({
+            release: {
+              name: releaseName,
+              rulesetName: rulesetName,
+            },
+          }),
+        },
+      );
+    }
+
+    if (!releaseResponse.ok) {
+      const err = await releaseResponse.json().catch(() => ({}));
+      throw new Error(
+        `Failed to deploy rules release: ${err.error?.message || releaseResponse.statusText}`,
+      );
+    }
   }
 
   return true;

package/src/init.js

@@ -1,9 +1,8 @@
 // Forge Remote Relay — Desktop Agent for Forge Remote
 // Copyright (c) 2025-2026 Iron Forge Apps
 // Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
-// AGPL-3.0 License — See LICENSE
 
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import { createInterface } from "readline";
 import { hostname, platform, homedir } from "os";
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
@@ -21,6 +20,7 @@ import {
   findFirebaseAdminSdkAccount,
   createServiceAccountKey,
   deployFirestoreRules,
+  removeBrowserKeyRestriction,
 } from "./google-auth.js";
 import {
   installCloudflared,
@@ -30,12 +30,14 @@ import {
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
 /**
- * Run a shell command and return stdout (trimmed).
- * Returns null if the command fails.
+ * Run a shell command safely using execFileSync (no shell interpolation).
+ * Pass command as [binary, ...args] array.
+ * Returns stdout (trimmed) or null on failure.
  */
-function run(cmd, { silent = false } = {}) {
+function run(args, { silent = false } = {}) {
   try {
-    return execSync(cmd, {
+    const [cmd, ...rest] = Array.isArray(args) ? args : [args];
+    return execFileSync(cmd, rest, {
       encoding: "utf-8",
       stdio: silent ? "pipe" : ["pipe", "pipe", "pipe"],
     }).trim();
@@ -45,17 +47,24 @@ function run(cmd, { silent = false } = {}) {
 }
 
 /**
- * Run a shell command, throwing on failure with a descriptive message.
+ * Run a shell command safely, throwing on failure with a descriptive message.
+ * Pass command as [binary, ...args] array.
  */
-function runOrFail(cmd, errorMsg) {
+function runOrFail(args, errorMsg) {
   try {
-    return execSync(cmd, {
+    const [cmd, ...rest] = Array.isArray(args) ? args : [args];
+    return execFileSync(cmd, rest, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
     }).trim();
   } catch (e) {
-    const stderr = e.stderr ? e.stderr.toString().trim() : e.message;
-    throw new Error(`${errorMsg}\n  Command: ${cmd}\n  ${stderr}`);
+    const stderr = e.stderr ? e.stderr.toString().trim() : "";
+    const stdout = e.stdout ? e.stdout.toString().trim() : "";
+    const details = stderr || stdout || e.message;
+    const err = new Error(`${errorMsg}\n  Command: ${args}\n  ${details}`);
+    err.stdout = stdout;
+    err.stderr = stderr;
+    throw err;
   }
 }
 
@@ -113,9 +122,10 @@ function waitForEnter(message) {
 function openBrowser(url) {
   const p = platform();
   try {
-    if (p === "darwin") execSync(`open "${url}"`, { stdio: "pipe" });
-    else if (p === "win32") execSync(`start "" "${url}"`, { stdio: "pipe" });
-    else execSync(`xdg-open "${url}"`, { stdio: "pipe" });
+    if (p === "darwin") execFileSync("open", [url], { stdio: "pipe" });
+    else if (p === "win32")
+      execFileSync("cmd", ["/c", "start", "", url], { stdio: "pipe" });
+    else execFileSync("xdg-open", [url], { stdio: "pipe" });
   } catch {
     // Silently fail — URL is always printed for manual opening.
   }
@@ -184,7 +194,7 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
 
   console.log(chalk.bold("\n📋 Step 1/11 — Checking Firebase CLI...\n"));
 
-  const firebaseVersion = run("firebase --version", { silent: true });
+  const firebaseVersion = run(["firebase", "--version"], { silent: true });
   if (!firebaseVersion) {
     console.error(chalk.red("  ✗ Firebase CLI not found.\n"));
     console.error(chalk.bold("  Install it with:\n"));
@@ -200,7 +210,7 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
 
   console.log(chalk.bold("\n📋 Step 2/11 — Checking Firebase login...\n"));
 
-  const loginList = run("firebase login:list", { silent: true });
+  const loginList = run(["firebase", "login:list"], { silent: true });
   const isLoggedIn = loginList && !loginList.includes("No authorized accounts");
 
   if (!isLoggedIn) {
@@ -208,7 +218,7 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
       chalk.yellow("  Not logged into Firebase. Opening login flow...\n"),
     );
     try {
-      execSync("firebase login", { stdio: "inherit" });
+      execFileSync("firebase", ["login"], { stdio: "inherit" });
     } catch {
       console.error(chalk.red("\n  Firebase login failed or was cancelled."));
       console.error(
@@ -219,7 +229,7 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
   }
 
   // Re-check after login.
-  const loginListAfter = run("firebase login:list", { silent: true });
+  const loginListAfter = run(["firebase", "login:list"], { silent: true });
   if (!loginListAfter || loginListAfter.includes("No authorized accounts")) {
     console.error(chalk.red("  Firebase login required. Aborting.\n"));
     process.exit(1);
@@ -275,7 +285,7 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
   // Check if the project already exists.
   let projectExists = false;
   try {
-    execSync(`firebase apps:list --project ${projectId}`, {
+    execFileSync("firebase", ["apps:list", "--project", projectId], {
       encoding: "utf-8",
       stdio: "pipe",
     });
@@ -291,7 +301,13 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
   } else {
     try {
       runOrFail(
-        `firebase projects:create ${projectId} --display-name "Forge Remote"`,
+        [
+          "firebase",
+          "projects:create",
+          projectId,
+          "--display-name",
+          "Forge Remote",
+        ],
         "Failed to create Firebase project.",
       );
       console.log(chalk.green(`  ✓ Firebase project created: ${projectId}`));
@@ -333,7 +349,7 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
   // First, check if a web app already exists for this project.
   try {
     const appsList = runOrFail(
-      `firebase apps:list --project ${projectId}`,
+      ["firebase", "apps:list", "--project", projectId],
       "Failed to list apps.",
     );
 
@@ -355,7 +371,14 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
     // No existing web app — create one.
     try {
       const createAppOutput = runOrFail(
-        `firebase apps:create web "Forge Remote Mobile" --project ${projectId}`,
+        [
+          "firebase",
+          "apps:create",
+          "web",
+          "Forge Remote Mobile",
+          "--project",
+          projectId,
+        ],
         "Failed to create web app.",
       );
 
@@ -373,7 +396,7 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
     if (!appId) {
       try {
         const appsList = runOrFail(
-          `firebase apps:list --project ${projectId}`,
+          ["firebase", "apps:list", "--project", projectId],
           "Failed to list apps.",
         );
 
@@ -403,14 +426,59 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
 
   console.log(chalk.green(`  ✓ App ID: ${appId}`));
 
-  // Get SDK config.
+  // Get SDK config (with retry — newly created apps may take a few seconds to propagate).
   let sdkConfig = {};
 
   try {
-    const sdkOutput = runOrFail(
-      `firebase apps:sdkconfig web ${appId} --project ${projectId}`,
-      "Failed to get SDK config.",
-    );
+    let sdkOutput = null;
+    const maxSdkRetries = 4;
+    const retryDelayMs = 5000; // 5 seconds between retries.
+
+    for (let attempt = 1; attempt <= maxSdkRetries; attempt++) {
+      try {
+        sdkOutput = runOrFail(
+          ["firebase", "apps:sdkconfig", "web", appId, "--project", projectId],
+          "Failed to get SDK config.",
+        );
+        break; // Success — exit retry loop.
+      } catch (e) {
+        if (attempt < maxSdkRetries) {
+          console.log(
+            chalk.yellow(
+              `  ⚠ SDK config not available yet (attempt ${attempt}/${maxSdkRetries}). ` +
+                `Retrying in ${retryDelayMs / 1000}s...`,
+            ),
+          );
+          await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+        } else {
+          // All retries exhausted — throw with helpful instructions.
+          const fallbackErr = new Error(
+            `Could not retrieve SDK config after ${maxSdkRetries} attempts.\n\n` +
+              chalk.bold(
+                "  This usually means the Firebase web app hasn't fully propagated yet.\n",
+              ) +
+              chalk.bold("  Try these steps:\n\n") +
+              chalk.cyan(
+                `  1. Wait 30 seconds, then re-run: forge-remote init\n`,
+              ) +
+              chalk.cyan(`  2. Or run manually:\n`) +
+              chalk.dim(
+                `     firebase apps:sdkconfig web ${appId} --project ${projectId}\n`,
+              ) +
+              chalk.dim(
+                `     Then copy the config into: ~/.forge-remote/sdk-config.json\n`,
+              ) +
+              chalk.dim(
+                `     Format: { "apiKey": "...", "authDomain": "...", "projectId": "...",\n`,
+              ) +
+              chalk.dim(
+                `              "storageBucket": "...", "messagingSenderId": "...", "appId": "..." }\n`,
+              ),
+          );
+          throw fallbackErr;
+        }
+      }
+    }
 
     // Parse the config — output may be JSON or JS object.
     const jsonMatch = sdkOutput.match(/\{[\s\S]*\}/);
@@ -462,7 +530,30 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
 
     // Cache SDK config so `pair` can read it without the Firebase CLI.
     const sdkCachePath = join(forgeDir, "sdk-config.json");
-    writeFileSync(sdkCachePath, JSON.stringify(sdkConfig, null, 2));
+    writeFileSync(sdkCachePath, JSON.stringify(sdkConfig, null, 2), {
+      mode: 0o600,
+    });
+
+    // Remove browser-only restriction from API key so it works from mobile.
+    try {
+      const projectNumber = sdkConfig.messagingSenderId;
+      const removed = await removeBrowserKeyRestriction(
+        projectId,
+        projectNumber,
+      );
+      if (removed) {
+        console.log(chalk.green("  ✓ API key updated for mobile access"));
+      }
+    } catch (e) {
+      console.log(
+        chalk.yellow(`  ⚠ Could not update API key restrictions: ${e.message}`),
+      );
+      console.log(
+        chalk.dim(
+          "  You may need to remove browser restrictions manually in Google Cloud Console.",
+        ),
+      );
+    }
   } catch (e) {
     console.error(chalk.red(`  ✗ ${e.message}`));
     process.exit(1);
@@ -474,11 +565,11 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
 
   // First check if Firestore already exists by listing databases.
   const existingDbs = run(
-    `firebase firestore:databases:list --project ${projectId}`,
+    ["firebase", "firestore:databases:list", "--project", projectId],
     { silent: true },
   );
 
-  if (existingDbs && existingDbs.includes("(default)")) {
+  if (existingDbs && existingDbs.includes("default")) {
     console.log(chalk.yellow("  ⚠ Firestore already enabled — continuing."));
     results.firestoreEnabled = true;
   } else {
@@ -487,7 +578,14 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
     for (let attempt = 0; attempt < maxFirestoreRetries; attempt++) {
       try {
         runOrFail(
-          `firebase firestore:databases:create default --project ${projectId} --location=nam5`,
+          [
+            "firebase",
+            "firestore:databases:create",
+            "(default)",
+            "--project",
+            projectId,
+            "--location=nam5",
+          ],
           "Failed to enable Firestore.",
         );
         console.log(
@@ -503,7 +601,8 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
         if (
           fullOutput.includes("already exists") ||
           fullOutput.includes("ALREADY_EXISTS") ||
-          fullOutput.includes("database already exists")
+          fullOutput.includes("database already exists") ||
+          fullOutput.includes("409")
         ) {
           console.log(
             chalk.yellow("  ⚠ Firestore already enabled — continuing."),
@@ -853,7 +952,9 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
 
   // Persist project ID and desktop ID so re-runs (even on different networks)
   // always target the same Firebase project and desktop document.
-  writeFileSync(configPath, JSON.stringify({ projectId, desktopId }, null, 2));
+  writeFileSync(configPath, JSON.stringify({ projectId, desktopId }, null, 2), {
+    mode: 0o600,
+  });
   console.log(
     chalk.dim(`  Config saved to ${configPath} (stable across networks)`),
   );

package/src/project-scanner.js

@@ -1,9 +1,10 @@
-import { readdirSync, statSync, existsSync } from "fs";
+import { readdirSync, readFileSync, statSync, existsSync } from "fs";
 import { join, basename } from "path";
 import { homedir } from "os";
+import * as log from "./logger.js";
 
-// Directories to scan (one level deep) for projects.
-const SCAN_DIRS = [
+// Default directories to scan for projects.
+const DEFAULT_SCAN_DIRS = [
   join(homedir(), "Documents"),
   join(homedir(), "Projects"),
   join(homedir(), "Developer"),
@@ -15,6 +16,29 @@ const SCAN_DIRS = [
   join(homedir(), "Desktop"),
 ];
 
+// Maximum depth to recurse into each scan directory.
+const MAX_DEPTH = 4;
+
+// Directories to skip during recursive scanning.
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "__pycache__",
+  "target",
+  "build",
+  "dist",
+  ".next",
+  ".nuxt",
+  "vendor",
+  ".dart_tool",
+  ".pub-cache",
+  "Pods",
+  ".gradle",
+  "venv",
+  ".venv",
+  "env",
+]);
+
 // Files that indicate a directory is a project root.
 const PROJECT_MARKERS = [
   ".git",
@@ -29,8 +53,34 @@ const PROJECT_MARKERS = [
   "build.gradle",
   "Makefile",
   "CMakeLists.txt",
+  ".xcodeproj", // Xcode projects (check for any child matching)
+  "Podfile",
+  "composer.json",
+  "mix.exs",
+  "stack.yaml",
+  "dune-project",
 ];
 
+/**
+ * Load user-configured extra scan paths from ~/.forge-remote/config.json.
+ * The config can contain a "scanPaths" array of absolute directory paths.
+ */
+function loadExtraScanPaths() {
+  try {
+    const configPath = join(homedir(), ".forge-remote", "config.json");
+    if (!existsSync(configPath)) return [];
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    if (Array.isArray(config.scanPaths)) {
+      return config.scanPaths.filter(
+        (p) => typeof p === "string" && p.startsWith("/"),
+      );
+    }
+  } catch {
+    // Ignore config parse errors.
+  }
+  return [];
+}
+
 /**
  * Scan common directories for projects.
  * Returns an array of { path, name, lastOpened } objects.
@@ -39,64 +89,80 @@ export async function scanProjects() {
   const projects = [];
   const seen = new Set();
 
-  for (const scanDir of SCAN_DIRS) {
-    if (!existsSync(scanDir)) continue;
+  const extraPaths = loadExtraScanPaths();
+  const scanDirs = [...DEFAULT_SCAN_DIRS, ...extraPaths];
 
-    try {
-      const entries = readdirSync(scanDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        if (entry.name.startsWith(".")) continue;
-
-        const dirPath = join(scanDir, entry.name);
-        if (seen.has(dirPath)) continue;
-
-        if (isProject(dirPath)) {
-          seen.add(dirPath);
-          const stat = statSync(dirPath);
-          projects.push({
-            path: dirPath,
-            name: basename(dirPath),
-            lastOpened: stat.mtime.toISOString(),
-          });
-        }
-
-        // Also scan one level deeper for nested project dirs
-        // (e.g. ~/Documents/IronForgeApps/Mobile/ForgeRemote).
-        try {
-          const subEntries = readdirSync(dirPath, { withFileTypes: true });
-          for (const sub of subEntries) {
-            if (!sub.isDirectory() || sub.name.startsWith(".")) continue;
-            const subPath = join(dirPath, sub.name);
-            if (seen.has(subPath)) continue;
-
-            if (isProject(subPath)) {
-              seen.add(subPath);
-              const stat = statSync(subPath);
-              projects.push({
-                path: subPath,
-                name: basename(subPath),
-                lastOpened: stat.mtime.toISOString(),
-              });
-            }
-          }
-        } catch {
-          // Skip subdirs we can't read.
-        }
-      }
-    } catch {
-      // Skip dirs we can't read.
-    }
+  log.info(`Scanning ${scanDirs.length} directories for projects...`);
+
+  for (const scanDir of scanDirs) {
+    if (!existsSync(scanDir)) continue;
+    scanRecursive(scanDir, 0, projects, seen);
   }
 
   // Sort by lastOpened descending.
   projects.sort((a, b) => b.lastOpened.localeCompare(a.lastOpened));
 
+  log.info(`Found ${projects.length} projects`);
   return projects;
 }
 
+/**
+ * Recursively scan a directory for projects up to MAX_DEPTH.
+ * When a project is found, it is added to the list and we do NOT recurse
+ * into it (a project root's subdirectories are not separate projects).
+ */
+function scanRecursive(dirPath, depth, projects, seen) {
+  if (depth > MAX_DEPTH) return;
+
+  let entries;
+  try {
+    entries = readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return; // Permission denied or unreadable.
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const name = entry.name;
+    if (name.startsWith(".") && name !== ".git") continue;
+    if (SKIP_DIRS.has(name)) continue;
+
+    const fullPath = join(dirPath, name);
+    if (seen.has(fullPath)) continue;
+
+    if (isProject(fullPath)) {
+      seen.add(fullPath);
+      try {
+        const stat = statSync(fullPath);
+        projects.push({
+          path: fullPath,
+          name: basename(fullPath),
+          lastOpened: stat.mtime.toISOString(),
+        });
+      } catch {
+        // stat failed — skip.
+      }
+      // Don't recurse into project directories.
+      continue;
+    }
+
+    // Not a project — recurse deeper.
+    scanRecursive(fullPath, depth + 1, projects, seen);
+  }
+}
+
 function isProject(dirPath) {
   for (const marker of PROJECT_MARKERS) {
+    // For .xcodeproj, check if any child ends with .xcodeproj
+    if (marker === ".xcodeproj") {
+      try {
+        const children = readdirSync(dirPath);
+        if (children.some((c) => c.endsWith(".xcodeproj"))) return true;
+      } catch {
+        // ignore
+      }
+      continue;
+    }
     if (existsSync(join(dirPath, marker))) return true;
   }
   return false;

package/src/session-manager.js

@@ -1,10 +1,13 @@
 // Forge Remote Relay — Desktop Agent for Forge Remote
 // Copyright (c) 2025-2026 Iron Forge Apps
 // Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
-// AGPL-3.0 License — See LICENSE
 
 import { getDb, FieldValue } from "./firebase.js";
+import { readdir, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
 import { spawn, execSync } from "child_process";
+import { Socket } from "net";
 import * as log from "./logger.js";
 import { startTunnel, stopTunnel } from "./tunnel-manager.js";
 import {
@@ -27,9 +30,52 @@ import {
  * ANTHROPIC_API_KEY, etc.).  Finally, strip any CLAUDECODE / CLAUDE_CODE_*
  * vars that block nested launches.
  */
+// Environment variables that are safe to pass to spawned Claude processes.
+// Everything else is stripped to prevent leaking secrets to Firestore.
+const ENV_ALLOWLIST = new Set([
+  // Essential for process execution
+  "PATH",
+  "HOME",
+  "USER",
+  "SHELL",
+  "TERM",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TMPDIR",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_CACHE_HOME",
+  // Required for Claude / Anthropic
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_BASE_URL",
+  // Node.js
+  "NODE_PATH",
+  "NODE_ENV",
+  "NODE_OPTIONS",
+  "NPM_CONFIG_PREFIX",
+  // Common dev tools
+  "EDITOR",
+  "VISUAL",
+  "PAGER",
+  "GIT_AUTHOR_NAME",
+  "GIT_AUTHOR_EMAIL",
+  "GIT_COMMITTER_NAME",
+  "GIT_COMMITTER_EMAIL",
+  // Platform-specific
+  "HOMEBREW_PREFIX",
+  "HOMEBREW_CELLAR",
+  // Encoding
+  "PYTHONIOENCODING",
+  "PYTHONUTF8",
+]);
+
+// Prefixes that are always blocked (override allowlist).
+const BLOCKED_PREFIXES = ["CLAUDECODE", "CLAUDE_CODE"];
+
 function buildSpawnEnv() {
   // Start with current runtime env — this has auth context.
-  const env = { ...process.env };
+  const fullEnv = { ...process.env };
 
   // Try to merge shell profile vars (picks up PATH changes, API keys, etc.).
   try {
@@ -44,8 +90,8 @@ function buildSpawnEnv() {
       if (idx > 0) {
         const key = line.slice(0, idx);
         // Only add vars that aren't already set — don't overwrite runtime env.
-        if (!(key in env)) {
-          env[key] = line.slice(idx + 1);
+        if (!(key in fullEnv)) {
+          fullEnv[key] = line.slice(idx + 1);
         }
       }
     }
@@ -53,12 +99,15 @@ function buildSpawnEnv() {
     log.warn("Could not resolve user shell profile — using process.env only");
   }
 
-  // Remove ALL env vars that block Claude from spawning.
-  const BLOCKED_PREFIXES = ["CLAUDECODE", "CLAUDE_CODE"];
-  for (const key of Object.keys(env)) {
+  // Filter to allowlisted vars only, then remove any blocked prefixes.
+  const env = {};
+  for (const key of Object.keys(fullEnv)) {
     if (BLOCKED_PREFIXES.some((prefix) => key.startsWith(prefix))) {
       log.info(`Removing blocking env var: ${key}`);
-      delete env[key];
+      continue;
+    }
+    if (ENV_ALLOWLIST.has(key)) {
+      env[key] = fullEnv[key];
     }
   }
 
@@ -115,6 +164,30 @@ function getActiveSessionCount() {
   return count;
 }
 
+// ---------------------------------------------------------------------------
+// Rate limiting — prevents command spam / DoS
+// ---------------------------------------------------------------------------
+
+const RATE_LIMIT_WINDOW_MS = 60_000; // 1 minute
+const RATE_LIMIT_MAX = 30; // max commands per window
+const commandTimestamps = [];
+
+function isRateLimited() {
+  const now = Date.now();
+  // Remove timestamps older than the window.
+  while (
+    commandTimestamps.length > 0 &&
+    commandTimestamps[0] < now - RATE_LIMIT_WINDOW_MS
+  ) {
+    commandTimestamps.shift();
+  }
+  if (commandTimestamps.length >= RATE_LIMIT_MAX) {
+    return true;
+  }
+  commandTimestamps.push(now);
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // Command listeners
 // ---------------------------------------------------------------------------
@@ -149,6 +222,29 @@ export function listenForCommands(desktopId) {
 // Desktop commands
 // ---------------------------------------------------------------------------
 
+// Allowlist of valid desktop command types.
+const VALID_DESKTOP_COMMANDS = new Set([
+  "start_session",
+  "rescan_projects",
+  "list_directory",
+]);
+
+// Sensitive directories that should never be browsed.
+const BLOCKED_DIRS = [
+  "/proc",
+  "/sys",
+  "/dev",
+  "/etc",
+  // User secret directories (expanded from home)
+  path.join(homedir(), ".ssh"),
+  path.join(homedir(), ".gnupg"),
+  path.join(homedir(), ".aws"),
+  path.join(homedir(), ".forge-remote"),
+  path.join(homedir(), ".config/gcloud"),
+  path.join(homedir(), ".docker"),
+  path.join(homedir(), ".kube"),
+];
+
 async function handleDesktopCommand(desktopId, commandDoc) {
   const data = commandDoc.data();
   const db = getDb();
@@ -158,16 +254,74 @@ async function handleDesktopCommand(desktopId, commandDoc) {
     .collection("commands")
     .doc(commandDoc.id);
 
+  // Rate limiting — reject if too many commands per minute.
+  if (isRateLimited()) {
+    log.warn(`Rate limited: rejecting command ${data.type}`);
+    await cmdRef.update({
+      status: "failed",
+      error: "Rate limited. Try again in a moment.",
+    });
+    return;
+  }
+
+  // Validate command type against allowlist.
+  if (!VALID_DESKTOP_COMMANDS.has(data.type)) {
+    log.warn(`Unknown desktop command type: ${data.type}`);
+    await cmdRef.update({
+      status: "failed",
+      error: `Unknown command type: ${data.type}`,
+    });
+    return;
+  }
+
   log.command(data.type, data.payload?.projectPath || "");
   await cmdRef.update({ status: "processing" });
 
   try {
     switch (data.type) {
-      case "start_session":
-        await startNewSession(desktopId, data.payload);
+      case "start_session": {
+        const sessionId = await startNewSession(desktopId, data.payload);
+        await cmdRef.update({
+          status: "completed",
+          result: { sessionId },
+        });
+        return; // Skip generic completed update below
+      }
+      case "rescan_projects": {
+        const { scanProjects } = await import("./project-scanner.js");
+        const { updateProjects } = await import("./desktop.js");
+        const projects = await scanProjects();
+        await updateProjects(desktopId, projects);
+        log.info(`Rescanned projects: found ${projects.length}`);
         break;
-      default:
-        log.warn(`Unknown desktop command type: ${data.type}`);
+      }
+      case "list_directory": {
+        const rawPath = data.payload?.path || homedir();
+
+        // Security: only allow absolute paths, resolve to real path to
+        // prevent symlink traversal, and block sensitive system dirs.
+        if (!path.isAbsolute(rawPath)) {
+          throw new Error("Path must be absolute");
+        }
+        const targetPath = await realpath(path.resolve(rawPath));
+
+        if (BLOCKED_DIRS.some((d) => targetPath.startsWith(d))) {
+          throw new Error("Access to this directory is not allowed");
+        }
+
+        const entries = await readdir(targetPath, { withFileTypes: true });
+        const dirs = entries
+          .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+          .map((e) => e.name)
+          .sort((a, b) =>
+            a.localeCompare(b, undefined, { sensitivity: "base" }),
+          );
+        await cmdRef.update({
+          status: "completed",
+          result: { path: targetPath, dirs },
+        });
+        return; // Skip generic completed update below
+      }
     }
     await cmdRef.update({ status: "completed" });
   } catch (e) {
@@ -198,6 +352,14 @@ function watchSessionCommands(sessionId) {
     });
 }
 
+// Allowlist of valid session command types.
+const VALID_SESSION_COMMANDS = new Set([
+  "send_prompt",
+  "stop_session",
+  "kill_session",
+  "retry_tunnel",
+]);
+
 async function handleSessionCommand(sessionId, commandDoc) {
   const data = commandDoc.data();
   const db = getDb();
@@ -207,6 +369,26 @@ async function handleSessionCommand(sessionId, commandDoc) {
     .collection("commands")
     .doc(commandDoc.id);
 
+  // Rate limiting.
+  if (isRateLimited()) {
+    log.warn(`Rate limited: rejecting session command ${data.type}`);
+    await cmdRef.update({
+      status: "failed",
+      error: "Rate limited. Try again in a moment.",
+    });
+    return;
+  }
+
+  // Validate command type.
+  if (!VALID_SESSION_COMMANDS.has(data.type)) {
+    log.warn(`Unknown session command type: ${data.type}`);
+    await cmdRef.update({
+      status: "failed",
+      error: `Unknown command type: ${data.type}`,
+    });
+    return;
+  }
+
   await cmdRef.update({ status: "processing" });
 
   try {
@@ -230,8 +412,6 @@ async function handleSessionCommand(sessionId, commandDoc) {
         log.command("retry_tunnel", sessionId.slice(0, 8));
         await retryTunnel(sessionId);
         break;
-      default:
-        log.warn(`Unknown session command type: ${data.type}`);
     }
     await cmdRef.update({ status: "completed" });
   } catch (e) {
@@ -282,6 +462,17 @@ export async function startNewSession(desktopId, payload) {
   const db = getDb();
   const resolvedModel = model || "sonnet";
   const resolvedPath = projectPath || process.cwd();
+
+  // Security: validate that projectPath is absolute and exists.
+  if (!path.isAbsolute(resolvedPath)) {
+    throw new Error("projectPath must be an absolute path");
+  }
+  try {
+    await realpath(resolvedPath);
+  } catch {
+    throw new Error(`projectPath does not exist: ${resolvedPath}`);
+  }
+
   const projectName = resolvedPath.split("/").pop();
 
   // Create session document.
@@ -1195,21 +1386,85 @@ const LOCALHOST_PATTERNS = [
   /(?:running|serving|available|dev server)\b.*?\bport\s+(\d{3,5})/i,
 ];
 
+// If any of these appear in the text, the port mention is likely an error — skip it.
+const ERROR_CONTEXT_PATTERNS = [
+  /port.*(?:conflict|in use|already|busy|occupied|EADDRINUSE)/i,
+  /(?:conflict|in use|already|busy|occupied|EADDRINUSE).*port/i,
+  /(?:failed|error|couldn't|cannot|unable).*(?:start|bind|listen)/i,
+  /(?:address|port).*already.*in.*use/i,
+  /EADDRINUSE/i,
+];
+
 // Ports we've already tunneled for a session (avoid duplicates).
 const tunneledPorts = new Map(); // sessionId → Set<port>
 
+/**
+ * Quick check: is something actually listening on this port?
+ * Tries IPv4 (127.0.0.1) first, then IPv6 (::1) — modern Node/Angular
+ * dev servers often bind to IPv6 only.
+ */
+function checkPortServing(port) {
+  return new Promise((resolve) => {
+    const tryConnect = (host, fallback) => {
+      const socket = new Socket();
+      socket.setTimeout(1500);
+      socket.once("connect", () => {
+        socket.destroy();
+        resolve(true);
+      });
+      socket.once("error", () => {
+        if (fallback) {
+          tryConnect(fallback, null);
+        } else {
+          resolve(false);
+        }
+      });
+      socket.once("timeout", () => {
+        socket.destroy();
+        if (fallback) {
+          tryConnect(fallback, null);
+        } else {
+          resolve(false);
+        }
+      });
+      socket.connect(port, host);
+    };
+    tryConnect("127.0.0.1", "::1");
+  });
+}
+
 async function detectAndTunnelDevServer(sessionId, text) {
   if (!text) return;
 
+  // Skip if the text is about a port error (conflict, already in use, etc.).
+  for (const errPattern of ERROR_CONTEXT_PATTERNS) {
+    if (errPattern.test(text)) {
+      return;
+    }
+  }
+
   for (const pattern of LOCALHOST_PATTERNS) {
     const match = text.match(pattern);
     if (match) {
       const port = parseInt(match[1], 10);
       if (port < 1024 || port > 65535) continue;
 
-      // Skip if we already tunneled this port for this session.
       const ported = tunneledPorts.get(sessionId) || new Set();
+
+      // Verify the port is actually serving before tunneling.
+      const isServing = await checkPortServing(port);
+      if (!isServing) {
+        // Port mentioned but nothing listening — clear from set so a
+        // future restart can re-trigger tunneling.
+        ported.delete(port);
+        tunneledPorts.set(sessionId, ported);
+        log.info(`Port ${port} mentioned but not serving — skipping tunnel`);
+        return;
+      }
+
+      // Already tunneled and server still up — skip.
       if (ported.has(port)) return;
+
       ported.add(port);
       tunneledPorts.set(sessionId, ported);
 

package/src/tunnel-manager.js

@@ -140,7 +140,7 @@ function startHostProxy(targetPort) {
       );
 
       const opts = {
-        hostname: "127.0.0.1",
+        hostname: "localhost",
         port: targetPort,
         path: clientReq.url,
         method: clientReq.method,
@@ -182,7 +182,7 @@ function startHostProxy(targetPort) {
 
     // Handle WebSocket upgrades (Vite HMR needs this).
     proxy.on("upgrade", (req, clientSocket, head) => {
-      const serverSocket = connect(targetPort, "127.0.0.1", () => {
+      const serverSocket = connect(targetPort, "localhost", () => {
         // Rebuild the upgrade request with scrubbed headers.
         const headers = scrubHeaders(req.headers, targetPort);
         let reqStr = `${req.method} ${req.url} HTTP/1.1\r\n`;