git-watchtower 1.14.15 → 1.14.17

package/bin/git-watchtower.js

@@ -104,6 +104,7 @@ const { WebDashboardServer } = require('../src/server/web');
 const { Coordinator, Worker, generateProjectId, getActiveCoordinator, tryAcquireLock, finalizeLock, removeLock, removeSocket, isProcessAlive } = require('../src/server/coordinator');
 const monitorLock = require('../src/utils/monitor-lock');
 const { createPipeErrorHandler } = require('../src/utils/pipe-error');
+const { getRecursiveWatchSupport } = require('../src/utils/fs-watch');
 
 const PROJECT_ROOT = process.cwd();
 
@@ -841,7 +842,7 @@ const { parseDiffStats, stash: gitStash, stashPop: gitStashPop } = require('../s
 
 // Server process command parsing and static server utilities
 const { parseCommand } = require('../src/server/process');
-const { getMimeType, injectLiveReload } = require('../src/server/static');
+const { getMimeType, injectLiveReload, resolveStaticPath } = require('../src/server/static');
 
 // State (non-store globals)
 let previousBranchStates = new Map(); // branch name -> commit hash
@@ -2224,52 +2225,67 @@ function createStaticServer() {
   }
 
   pathname = path.normalize(pathname).replace(/^(\.\.[\/\\])+/, '');
-  let filePath = path.join(STATIC_DIR, pathname);
+  const candidate = path.join(STATIC_DIR, pathname);
 
-  // Security: ensure resolved path stays within STATIC_DIR to prevent path traversal.
-  // Use realpath to follow symlinks — without this, a symlink inside STATIC_DIR
-  // pointing outside would bypass the startsWith check.
-  const resolvedStaticDir = path.resolve(STATIC_DIR);
-  let resolvedPath = path.resolve(filePath);
-  try {
-    resolvedPath = fs.realpathSync(resolvedPath);
-  } catch {
-    // File doesn't exist — path.resolve is sufficient since there's no symlink to follow.
-  }
+  // Realpath the static root once per request. A failure here means the
+  // install is broken (missing dir, bad permissions) — fall back to the
+  // resolved-but-not-realpath'd form so the request still gets a 403
+  // from resolveStaticPath rather than crashing.
   let realStaticDir;
   try {
-    realStaticDir = fs.realpathSync(resolvedStaticDir);
+    realStaticDir = fs.realpathSync(path.resolve(STATIC_DIR));
   } catch (e) {
-    // STATIC_DIR comes from our own package layout, so a realpath failure
-    // means the install is broken (missing dir, permissions, etc.) — worth
-    // diagnosing. Fall back to the unresolved path so the request still
-    // gets its 403 rather than crashing.
     telemetry.captureError(e);
-    realStaticDir = resolvedStaticDir;
+    realStaticDir = path.resolve(STATIC_DIR);
   }
-  if (!resolvedPath.startsWith(realStaticDir + path.sep) && resolvedPath !== realStaticDir) {
+
+  const send403 = () => {
     res.writeHead(403, { 'Content-Type': 'text/html' });
     res.end('<h1>403 Forbidden</h1>');
     addServerLog(`GET ${logPath} → 403 (path traversal blocked)`, true);
-    return;
-  }
+  };
 
-  if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
-    filePath = path.join(filePath, 'index.html');
-  }
+  const send404 = () => {
+    res.writeHead(404, { 'Content-Type': 'text/html' });
+    res.end('<h1>404 Not Found</h1>');
+    addServerLog(`GET ${logPath} → 404`, true);
+  };
 
-  if (!fs.existsSync(filePath)) {
-    if (fs.existsSync(filePath + '.html')) {
-      filePath = filePath + '.html';
+  // All downstream reads go through `finalPath` — the realpath-resolved
+  // target from resolveStaticPath(). Using the pre-realpath candidate
+  // opens a TOCTOU window where a symlink inside STATIC_DIR could be
+  // swapped between the containment check and the fs.readFile to point
+  // outside the root.
+  let finalPath = null;
+
+  const initial = resolveStaticPath(candidate, realStaticDir);
+  if (initial.status === 'forbidden') { send403(); return; }
+  if (initial.status === 'ok') {
+    // Directory requests resolve the index.html *inside the realpath'd*
+    // directory. Without this second realpath+check, a symlinked dir
+    // whose target pointed outside would serve its attacker-controlled
+    // index.html through our root check.
+    if (fs.statSync(initial.path).isDirectory()) {
+      const indexResult = resolveStaticPath(
+        path.join(initial.path, 'index.html'),
+        realStaticDir,
+      );
+      if (indexResult.status === 'forbidden') { send403(); return; }
+      if (indexResult.status === 'ok') finalPath = indexResult.path;
+      // 'missing' → fall through to 404 (no .html fallback for dirs)
     } else {
-      res.writeHead(404, { 'Content-Type': 'text/html' });
-      res.end('<h1>404 Not Found</h1>');
-      addServerLog(`GET ${logPath} → 404`, true);
-      return;
+      finalPath = initial.path;
     }
+  } else {
+    // 'missing' — try the `foo` → `foo.html` convenience fallback.
+    const htmlFallback = resolveStaticPath(candidate + '.html', realStaticDir);
+    if (htmlFallback.status === 'forbidden') { send403(); return; }
+    if (htmlFallback.status === 'ok') finalPath = htmlFallback.path;
   }
 
-  serveFile(res, filePath, logPath);
+  if (!finalPath) { send404(); return; }
+
+  serveFile(res, finalPath, logPath);
   });
 }
 
@@ -2290,6 +2306,21 @@ function setupFileWatcher() {
     addLog(`Loaded ${ignorePatterns.length} ignore patterns from .gitignore`, 'info');
   }
 
+  // Before calling fs.watch, surface any known incompatibility explicitly —
+  // the generic catch below would otherwise report a confusing
+  // "Could not set up file watcher: ..." for the well-known case of a
+  // forced install on Node <20 Linux, where recursive watching is
+  // unreliable. A clear message points the user at the real fix
+  // (upgrade Node) instead of making them debug a live-reload that
+  // appears to work but silently ignores subdirectory edits.
+  const support = getRecursiveWatchSupport();
+  if (!support.supported) {
+    addLog(
+      `Live reload may miss nested file changes: ${support.reason}`,
+      'error',
+    );
+  }
+
   try {
     fileWatcher = fs.watch(STATIC_DIR, { recursive: true }, (eventType, filename) => {
       if (!filename) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-watchtower",
-  "version": "1.14.15",
+  "version": "1.14.17",
   "description": "Terminal-based Git branch monitor with activity sparklines and optional dev server with live reload",
   "main": "bin/git-watchtower.js",
   "bin": {

package/src/server/static.js

@@ -3,6 +3,9 @@
  * @module server/static
  */
 
+const fs = require('fs');
+const path = require('path');
+
 /**
  * MIME type mapping by file extension.
  */
@@ -63,9 +66,61 @@ function injectLiveReload(html) {
   return html;
 }
 
+/**
+ * Resolve a static-server request candidate to a safe, realpath'd path
+ * inside the static root.
+ *
+ * The critical property: the returned `path` is the realpath-resolved
+ * target, so all downstream file reads operate on the same bytes the
+ * containment check approved. Previously the server would realpath the
+ * candidate for the 403 check but then read the pre-realpath path — a
+ * TOCTOU window where a symlink inside the static dir could be swapped
+ * between check and read to point outside the root.
+ *
+ * Contract:
+ * - 'ok'        → the candidate exists inside `realStaticDir`; serve `path`.
+ * - 'missing'   → the candidate resolves (or would resolve) inside the
+ *                 root but doesn't exist. Callers can try an extension
+ *                 fallback (e.g. `.html`) or return 404.
+ * - 'forbidden' → the candidate resolves outside the root, via symlink
+ *                 or via path traversal like `../../etc/passwd`. Return
+ *                 403; do not attempt fallbacks, since the attacker
+ *                 controls the request.
+ *
+ * @param {string} candidate - Unresolved absolute path (e.g.
+ *   `path.join(STATIC_DIR, pathname)`).
+ * @param {string} realStaticDir - The realpath'd absolute path of the
+ *   static root. Callers should cache this per-request.
+ * @returns {{ status: 'ok', path: string } | { status: 'missing' } | { status: 'forbidden' }}
+ */
+function resolveStaticPath(candidate, realStaticDir) {
+  const resolvedCandidate = path.resolve(candidate);
+  let realPath;
+  let exists;
+  try {
+    realPath = fs.realpathSync(resolvedCandidate);
+    exists = true;
+  } catch (_) {
+    // Doesn't exist. Fall back to the normalized form so path-traversal
+    // attempts against non-existent files (`../../etc/passwd`) still get
+    // rejected with 403 instead of silently 404'ing.
+    realPath = resolvedCandidate;
+    exists = false;
+  }
+
+  if (realPath !== realStaticDir && !realPath.startsWith(realStaticDir + path.sep)) {
+    return { status: 'forbidden' };
+  }
+  if (!exists) {
+    return { status: 'missing' };
+  }
+  return { status: 'ok', path: realPath };
+}
+
 module.exports = {
   MIME_TYPES,
   getMimeType,
   LIVE_RELOAD_SCRIPT,
   injectLiveReload,
+  resolveStaticPath,
 };

package/src/utils/fs-watch.js

@@ -0,0 +1,84 @@
+/**
+ * fs.watch recursive-option support detection.
+ *
+ * `fs.watch(..., { recursive: true })` was not reliable on Linux before
+ * Node 20 — depending on the point release it either threw
+ * ERR_FEATURE_UNAVAILABLE_ON_PLATFORM or silently ignored the flag and
+ * watched only the top-level directory, leaving subdirectory changes
+ * undetected. macOS and Windows have supported recursive watching for
+ * much longer.
+ *
+ * git-watchtower declares engines.node >=20 in package.json, but users
+ * can bypass that with `npm install --force`. When they do, the static-
+ * server live-reload watcher needs to warn clearly rather than appear
+ * to work but silently miss edits in nested directories.
+ *
+ * @module utils/fs-watch
+ */
+
+'use strict';
+
+/**
+ * Parse `process.version` ("v20.11.1") into a numeric major version.
+ * Exported so tests can drive edge cases (malformed strings, pre-releases).
+ *
+ * @param {string} versionString
+ * @returns {number} major version, or NaN if unparseable
+ */
+function parseMajor(versionString) {
+  if (typeof versionString !== 'string') return NaN;
+  const match = /^v?(\d+)\./.exec(versionString);
+  if (!match) return NaN;
+  return parseInt(match[1], 10);
+}
+
+/**
+ * Decide whether fs.watch recursive mode is reliably supported on the
+ * current Node/platform combination.
+ *
+ * @param {Object} [env] - Injected for tests.
+ * @param {string} [env.version] - e.g. process.version
+ * @param {string} [env.platform] - e.g. process.platform
+ * @returns {{ supported: boolean, reason: string | null }}
+ *   reason is a short, user-facing explanation when !supported.
+ */
+function getRecursiveWatchSupport(env = {}) {
+  const version = env.version !== undefined ? env.version : process.version;
+  const platform = env.platform !== undefined ? env.platform : process.platform;
+
+  // macOS and Windows have supported recursive watching since well before
+  // any Node version we care about.
+  if (platform === 'darwin' || platform === 'win32') {
+    return { supported: true, reason: null };
+  }
+
+  if (platform === 'linux') {
+    const major = parseMajor(version);
+    if (Number.isNaN(major)) {
+      return {
+        supported: false,
+        reason: `could not parse Node version "${version}"`,
+      };
+    }
+    if (major < 20) {
+      return {
+        supported: false,
+        reason:
+          `Node ${version} on Linux does not reliably support fs.watch({ recursive: true }); ` +
+          'upgrade to Node >=20 (see package.json engines).',
+      };
+    }
+    return { supported: true, reason: null };
+  }
+
+  // Unknown platform (AIX, FreeBSD, etc.). Don't claim support we can't verify.
+  return {
+    supported: false,
+    reason: `recursive fs.watch support is not verified on platform "${platform}"`,
+  };
+}
+
+module.exports = {
+  parseMajor,
+  getRecursiveWatchSupport,
+};