claudehq 1.0.3 → 1.0.5

package/lib/spawner/path-validator.js

@@ -0,0 +1,366 @@
+/**
+ * Path Validator - Security utilities for path validation
+ *
+ * Validates directory paths for safety before use in shell commands.
+ * Prevents command injection, path traversal, and other attacks.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Characters that could be dangerous in shell commands
+// Note: ~ is allowed as it's used for home directory expansion
+const SHELL_METACHARACTERS = /[;&|`$(){}[\]<>\\!#*?\n\r\x00]/;
+
+// Patterns that indicate path traversal attempts
+const PATH_TRAVERSAL_PATTERNS = [
+  /\.\.\//,        // ../
+  /\.\.\\/,        // ..\
+  /\.\.$/,         // ends with ..
+  /^\.\.$/         // just ..
+];
+
+// Maximum path length (OS limit is usually 4096, but we're conservative)
+const MAX_PATH_LENGTH = 1024;
+
+/**
+ * Validate a tmux session name
+ * @param {string} name - Session name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidTmuxSessionName(name) {
+  if (!name || typeof name !== 'string') {
+    return false;
+  }
+  // tmux session names can only contain alphanumeric, underscore, hyphen
+  return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+
+/**
+ * Validate a session name for safe use
+ * @param {string} name - Session name to validate
+ * @throws {Error} If validation fails
+ * @returns {string} The validated name
+ */
+function validateTmuxSessionName(name) {
+  if (!isValidTmuxSessionName(name)) {
+    throw new Error('Invalid tmux session name: must contain only alphanumeric characters, underscores, and hyphens');
+  }
+  return name;
+}
+
+/**
+ * Check if a path contains shell metacharacters
+ * @param {string} pathStr - Path to check
+ * @returns {boolean} True if contains dangerous characters
+ */
+function containsShellMetacharacters(pathStr) {
+  return SHELL_METACHARACTERS.test(pathStr);
+}
+
+/**
+ * Check if a path appears to be a path traversal attempt
+ * @param {string} pathStr - Path to check
+ * @returns {boolean} True if appears to be traversal attempt
+ */
+function isPathTraversalAttempt(pathStr) {
+  return PATH_TRAVERSAL_PATTERNS.some(pattern => pattern.test(pathStr));
+}
+
+/**
+ * Normalize and resolve a path, expanding ~ for home directory
+ * @param {string} pathStr - Path to normalize
+ * @returns {string} Normalized absolute path
+ */
+function normalizePath(pathStr) {
+  if (!pathStr || typeof pathStr !== 'string') {
+    return '';
+  }
+
+  // Expand ~ to home directory
+  if (pathStr.startsWith('~')) {
+    pathStr = path.join(os.homedir(), pathStr.slice(1));
+  }
+
+  // Resolve to absolute path
+  return path.resolve(pathStr);
+}
+
+/**
+ * Validate a directory path for safe use
+ * @param {string} dirPath - Directory path to validate
+ * @param {Object} options - Validation options
+ * @param {boolean} options.mustExist - If true, directory must exist (default: true)
+ * @param {boolean} options.allowCreate - If true, allows non-existent but valid paths (default: false)
+ * @returns {Object} Validation result { valid: boolean, path: string, error: string|null }
+ */
+function validateDirectoryPath(dirPath, options = {}) {
+  const { mustExist = true, allowCreate = false } = options;
+
+  // Check for null/undefined/empty
+  if (!dirPath || typeof dirPath !== 'string') {
+    return {
+      valid: false,
+      path: null,
+      error: 'Directory path is required'
+    };
+  }
+
+  // Trim whitespace
+  const trimmed = dirPath.trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      path: null,
+      error: 'Directory path cannot be empty'
+    };
+  }
+
+  // Check path length
+  if (trimmed.length > MAX_PATH_LENGTH) {
+    return {
+      valid: false,
+      path: null,
+      error: `Path exceeds maximum length of ${MAX_PATH_LENGTH} characters`
+    };
+  }
+
+  // Check for shell metacharacters
+  if (containsShellMetacharacters(trimmed)) {
+    return {
+      valid: false,
+      path: null,
+      error: 'Path contains invalid characters'
+    };
+  }
+
+  // Check for path traversal
+  if (isPathTraversalAttempt(trimmed)) {
+    return {
+      valid: false,
+      path: null,
+      error: 'Path contains invalid traversal patterns'
+    };
+  }
+
+  // Normalize the path
+  const normalized = normalizePath(trimmed);
+
+  // Check normalized path for shell metacharacters (after expansion)
+  if (containsShellMetacharacters(normalized)) {
+    return {
+      valid: false,
+      path: null,
+      error: 'Resolved path contains invalid characters'
+    };
+  }
+
+  // Check if path exists
+  if (mustExist && !allowCreate) {
+    try {
+      const stats = fs.statSync(normalized);
+      if (!stats.isDirectory()) {
+        return {
+          valid: false,
+          path: normalized,
+          error: 'Path exists but is not a directory'
+        };
+      }
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        return {
+          valid: false,
+          path: normalized,
+          error: 'Directory does not exist'
+        };
+      }
+      return {
+        valid: false,
+        path: normalized,
+        error: `Cannot access directory: ${e.message}`
+      };
+    }
+  }
+
+  // If allowCreate, check that parent exists
+  if (allowCreate && mustExist) {
+    const parentDir = path.dirname(normalized);
+    try {
+      const parentStats = fs.statSync(parentDir);
+      if (!parentStats.isDirectory()) {
+        return {
+          valid: false,
+          path: normalized,
+          error: 'Parent path is not a directory'
+        };
+      }
+    } catch (e) {
+      return {
+        valid: false,
+        path: normalized,
+        error: 'Parent directory does not exist'
+      };
+    }
+  }
+
+  return {
+    valid: true,
+    path: normalized,
+    error: null
+  };
+}
+
+/**
+ * Validate a file path for safe use
+ * @param {string} filePath - File path to validate
+ * @param {Object} options - Validation options
+ * @param {boolean} options.mustExist - If true, file must exist (default: false)
+ * @param {boolean} options.parentMustExist - If true, parent dir must exist (default: true)
+ * @returns {Object} Validation result { valid: boolean, path: string, error: string|null }
+ */
+function validateFilePath(filePath, options = {}) {
+  const { mustExist = false, parentMustExist = true } = options;
+
+  // Check for null/undefined/empty
+  if (!filePath || typeof filePath !== 'string') {
+    return {
+      valid: false,
+      path: null,
+      error: 'File path is required'
+    };
+  }
+
+  // Trim whitespace
+  const trimmed = filePath.trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      path: null,
+      error: 'File path cannot be empty'
+    };
+  }
+
+  // Check path length
+  if (trimmed.length > MAX_PATH_LENGTH) {
+    return {
+      valid: false,
+      path: null,
+      error: `Path exceeds maximum length of ${MAX_PATH_LENGTH} characters`
+    };
+  }
+
+  // Check for shell metacharacters
+  if (containsShellMetacharacters(trimmed)) {
+    return {
+      valid: false,
+      path: null,
+      error: 'Path contains invalid characters'
+    };
+  }
+
+  // Normalize the path
+  const normalized = normalizePath(trimmed);
+
+  // Check if file exists when required
+  if (mustExist) {
+    try {
+      const stats = fs.statSync(normalized);
+      if (stats.isDirectory()) {
+        return {
+          valid: false,
+          path: normalized,
+          error: 'Path is a directory, not a file'
+        };
+      }
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        return {
+          valid: false,
+          path: normalized,
+          error: 'File does not exist'
+        };
+      }
+      return {
+        valid: false,
+        path: normalized,
+        error: `Cannot access file: ${e.message}`
+      };
+    }
+  }
+
+  // Check parent directory exists
+  if (parentMustExist) {
+    const parentDir = path.dirname(normalized);
+    try {
+      const parentStats = fs.statSync(parentDir);
+      if (!parentStats.isDirectory()) {
+        return {
+          valid: false,
+          path: normalized,
+          error: 'Parent path is not a directory'
+        };
+      }
+    } catch (e) {
+      return {
+        valid: false,
+        path: normalized,
+        error: 'Parent directory does not exist'
+      };
+    }
+  }
+
+  return {
+    valid: true,
+    path: normalized,
+    error: null
+  };
+}
+
+/**
+ * Sanitize a string for use in a filename
+ * @param {string} str - String to sanitize
+ * @returns {string} Sanitized string
+ */
+function sanitizeForFilename(str) {
+  if (!str || typeof str !== 'string') {
+    return '';
+  }
+  // Replace invalid characters with underscore
+  return str.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 200);
+}
+
+/**
+ * Check if a path is within a base directory (prevent escaping)
+ * @param {string} targetPath - Path to check
+ * @param {string} basePath - Base directory that should contain the path
+ * @returns {boolean} True if target is within base
+ */
+function isPathWithin(targetPath, basePath) {
+  const normalizedTarget = normalizePath(targetPath);
+  const normalizedBase = normalizePath(basePath);
+
+  return normalizedTarget.startsWith(normalizedBase + path.sep) ||
+         normalizedTarget === normalizedBase;
+}
+
+module.exports = {
+  // Validation functions
+  validateDirectoryPath,
+  validateFilePath,
+  validateTmuxSessionName,
+  isValidTmuxSessionName,
+
+  // Check functions
+  containsShellMetacharacters,
+  isPathTraversalAttempt,
+  isPathWithin,
+
+  // Utility functions
+  normalizePath,
+  sanitizeForFilename,
+
+  // Constants
+  MAX_PATH_LENGTH,
+  SHELL_METACHARACTERS
+};