sfcc-dev-mcp 1.0.15 → 1.0.19

package/src/config/dw-json-loader.ts

@@ -3,12 +3,68 @@
  *
  * This module handles secure loading and validation of dw.json files
  * with comprehensive security checks for file access.
+ *
+ * Security features:
+ * - Path traversal attack prevention
+ * - System directory access blocking
+ * - File size limits to prevent DoS
+ * - JSON content validation
+ * - Symlink resolution and validation
  */
 
-import { readFileSync, existsSync, statSync } from 'fs';
-import { resolve, basename, extname } from 'path';
+import { readFileSync, existsSync, statSync, realpathSync } from 'fs';
+import { resolve, basename, extname, normalize, isAbsolute } from 'path';
 import { DwJsonConfig } from '../types/types.js';
 
+/**
+ * Dangerous system paths that should never be accessed
+ * These are blocked to prevent accidental or malicious access to sensitive areas
+ */
+const BLOCKED_SYSTEM_PATHS: readonly string[] = [
+  '/etc',
+  '/proc',
+  '/sys',
+  '/dev',
+  '/root',
+  '/var/log',
+  '/var/run',
+  '/boot',
+  '/sbin',
+  '/bin',
+  // Windows system paths
+  'C:\\Windows',
+  'C:\\Program Files',
+  'C:\\ProgramData',
+  // Common sensitive directories
+  '.ssh',
+  '.gnupg',
+  '.aws',
+  '.config/gcloud',
+] as const;
+
+/**
+ * Allowed path prefixes for configuration file access
+ * These are the typical locations where development projects and configs reside
+ */
+const ALLOWED_PATH_PATTERNS: readonly RegExp[] = [
+  // User home directories
+  /^\/Users\/[^/]+\//i, // macOS
+  /^\/home\/[^/]+\//i, // Linux (allow all users for development)
+  /^C:\\Users\\[^\\]+\\/i, // Windows
+  // Common project directories
+  /^\/opt\//i,
+  /^\/var\/www\//i,
+  /^\/srv\//i,
+  // Temp directories (for testing)
+  /^\/tmp\//i,
+  /^\/private\/tmp\//i, // macOS real temp path
+  /^\/var\/folders\//i, // macOS temp
+  /^\/private\/var\/folders\//i, // macOS real temp path (symlink resolved)
+  /^C:\\Temp\\/i, // Windows temp
+  // CI workspace paths
+  /^\/home\/runner\/work\//i, // GitHub Actions
+] as const;
+
 /**
  * Validates that a file path is safe to access and prevents path traversal attacks
  *
@@ -23,7 +79,7 @@ function validateSecurePath(filePath: string): string {
   }
 
   // Prevent excessively long paths that could cause DoS
-  if (filePath.length > 1000) {
+  if (filePath.length > 4096) {
     throw new Error('File path too long');
   }
 
@@ -33,28 +89,53 @@ function validateSecurePath(filePath: string): string {
     throw new Error('Only .json files are allowed');
   }
 
-  // Normalize the path to prevent path traversal
-  const resolvedPath = resolve(filePath);
+  // Normalize and resolve the path to prevent path traversal
+  const resolvedPath = normalize(resolve(filePath));
+
+  // Verify it's an absolute path after resolution
+  if (!isAbsolute(resolvedPath)) {
+    throw new Error('Path must resolve to an absolute path');
+  }
 
   // Additional check: ensure the resolved path still ends with .json
   // This prevents attacks like "file.json/../../../etc/passwd"
   if (!resolvedPath.toLowerCase().endsWith('.json')) {
-    throw new Error('Invalid file path');
+    throw new Error('Invalid file path after normalization');
   }
 
-  // Prevent access to system directories (additional security layer)
-  // Allow CI workspace paths like /home/runner/work/ but block sensitive system paths
-  const dangerousPaths = ['/etc/', '/proc/', '/sys/', '/dev/', '/root/'];
+  // Check against blocked system paths
   const lowerPath = resolvedPath.toLowerCase();
+  for (const blocked of BLOCKED_SYSTEM_PATHS) {
+    const blockedLower = blocked.toLowerCase();
+    if (
+      lowerPath === blockedLower ||
+      lowerPath.startsWith(`${blockedLower  }/`) ||
+      lowerPath.startsWith(`${blockedLower  }\\`) ||
+      lowerPath.includes(`/${  blockedLower  }/`) ||
+      lowerPath.includes(`\\${  blockedLower  }\\`)
+    ) {
+      throw new Error('Access to system directories not allowed');
+    }
+  }
 
-  // Check for dangerous system paths
-  if (dangerousPaths.some(dangerous => lowerPath.includes(dangerous))) {
-    throw new Error('Access to system directories not allowed');
+  // Check that path matches allowed patterns
+  const matchesAllowed = ALLOWED_PATH_PATTERNS.some(pattern => pattern.test(resolvedPath));
+  if (!matchesAllowed) {
+    throw new Error('Path is outside of allowed configuration directories');
   }
 
-  // Block /home/ but allow CI workspace paths (/home/runner/work/)
-  if (lowerPath.includes('/home/') && !lowerPath.includes('/home/runner/work/')) {
-    throw new Error('Access to system directories not allowed');
+  // If the file exists, resolve symlinks and re-validate the real path
+  if (existsSync(resolvedPath)) {
+    try {
+      const realPath = realpathSync(resolvedPath);
+      if (realPath !== resolvedPath) {
+        // Recursively validate the symlink target (but limit recursion)
+        return validateSecurePath(realPath);
+      }
+    } catch {
+      // If we can't resolve symlinks, continue with the original path
+      // The file might not exist yet, which is handled later
+    }
   }
 
   return resolvedPath;

package/src/config/workspace-roots.ts

@@ -0,0 +1,540 @@
+/**
+ * Workspace Roots Management for SFCC MCP Server
+ *
+ * This module handles secure discovery and validation of workspace roots
+ * provided by MCP clients, enabling automatic dw.json discovery from the
+ * VS Code workspace without requiring absolute paths.
+ *
+ * Configuration Discovery Priority:
+ * 1. CLI parameter (--dw-json) - handled in main.ts
+ * 2. Environment variables (SFCC_*) - handled in main.ts
+ * 3. MCP workspace roots (this module) - called after client connects
+ *
+ * This discovery mechanism is preferred over CWD-based search because
+ * MCP servers often start with cwd set to the user's home directory,
+ * not the project directory. The MCP workspace roots capability provides
+ * the correct project context from VS Code/Copilot/Cursor.
+ *
+ * Security considerations:
+ * - Only file:// URIs are accepted (per MCP spec)
+ * - Path traversal attacks are prevented
+ * - System directories are blocked
+ * - Symlink resolution is handled securely
+ */
+
+import { existsSync, realpathSync, statSync } from 'fs';
+import { resolve, normalize, join, isAbsolute } from 'path';
+import { fileURLToPath } from 'url';
+import { Logger } from '../utils/logger.js';
+import { DwJsonConfig } from '../types/types.js';
+import { loadSecureDwJson } from './dw-json-loader.js';
+
+/**
+ * MCP client root from roots/list response
+ */
+export interface MCPClientRoot {
+  uri: string;
+  name?: string;
+}
+
+/**
+ * Represents a validated workspace root
+ */
+export interface ValidatedWorkspaceRoot {
+  /** Original URI from the client */
+  uri: string;
+  /** Resolved absolute path */
+  path: string;
+  /** Optional name for the root */
+  name?: string;
+}
+
+/**
+ * Result of workspace roots discovery
+ */
+export interface WorkspaceDiscoveryResult {
+  /** Whether discovery was successful */
+  success: boolean;
+  /** Discovered dw.json configuration if found */
+  config?: DwJsonConfig;
+  /** Path to the discovered dw.json file */
+  dwJsonPath?: string;
+  /** Reason for failure or skip */
+  reason?: string;
+  /** Number of workspace roots received from client */
+  rootsReceived?: number;
+  /** Number of valid roots after security validation */
+  validRoots?: number;
+}
+
+/**
+ * Security validation result
+ */
+interface ValidationResult {
+  isValid: boolean;
+  error?: string;
+  resolvedPath?: string;
+}
+
+/**
+ * Dangerous system paths that should never be accessed
+ * These are blocked to prevent accidental or malicious access to sensitive areas
+ */
+const BLOCKED_SYSTEM_PATHS: readonly string[] = [
+  '/etc',
+  '/proc',
+  '/sys',
+  '/dev',
+  '/root',
+  '/var/log',
+  '/var/run',
+  '/boot',
+  '/sbin',
+  '/bin',
+  // Windows system paths
+  'C:\\Windows',
+  'C:\\Program Files',
+  'C:\\ProgramData',
+  // Common sensitive directories
+  '.ssh',
+  '.gnupg',
+  '.aws',
+  '.config/gcloud',
+] as const;
+
+/**
+ * Allowed path prefixes for workspace roots
+ * These are the typical locations where development projects reside
+ */
+const ALLOWED_PATH_PATTERNS: readonly RegExp[] = [
+  // User home directories
+  /^\/Users\/[^/]+\//i, // macOS
+  /^\/home\/[^/]+\//i, // Linux (allow all users, not just runner)
+  /^C:\\Users\\[^\\]+\\/i, // Windows
+  // Common project directories
+  /^\/opt\//i,
+  /^\/var\/www\//i,
+  /^\/srv\//i,
+  // Temp directories (for testing)
+  /^\/tmp\//i,
+  /^\/private\/tmp\//i, // macOS real temp path
+  /^\/var\/folders\//i, // macOS temp
+  /^\/private\/var\/folders\//i, // macOS real temp path (symlink resolved)
+  /^C:\\Temp\\/i, // Windows temp
+  // CI workspace paths
+  /^\/home\/runner\/work\//i, // GitHub Actions
+] as const;
+
+/**
+ * Validates that a file URI is safe and converts it to an absolute path
+ *
+ * @param uri - The file:// URI to validate
+ * @returns Validation result with resolved path or error
+ */
+function validateFileUri(uri: string): ValidationResult {
+  // Check for null bytes and other dangerous characters
+  if (uri.includes('\0') || uri.includes('\x00')) {
+    return { isValid: false, error: 'URI contains invalid characters' };
+  }
+
+  // Verify it's a file:// URI
+  if (!uri.startsWith('file://')) {
+    return { isValid: false, error: 'Only file:// URIs are supported for workspace roots' };
+  }
+
+  try {
+    // Convert file URI to path securely
+    const path = fileURLToPath(uri);
+    return validatePath(path);
+  } catch (error) {
+    return {
+      isValid: false,
+      error: `Invalid file URI: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    };
+  }
+}
+
+/**
+ * Validates that a file path is safe to use as a workspace root
+ *
+ * @param inputPath - The path to validate
+ * @returns Validation result with resolved path or error
+ */
+function validatePath(inputPath: string): ValidationResult {
+  // Check for null bytes
+  if (inputPath.includes('\0')) {
+    return { isValid: false, error: 'Path contains invalid characters' };
+  }
+
+  // Check for excessively long paths (DoS prevention)
+  if (inputPath.length > 4096) {
+    return { isValid: false, error: 'Path is too long' };
+  }
+
+  // Normalize and resolve the path
+  let resolvedPath: string;
+  try {
+    resolvedPath = normalize(resolve(inputPath));
+  } catch {
+    return { isValid: false, error: 'Failed to resolve path' };
+  }
+
+  // Verify it's an absolute path
+  if (!isAbsolute(resolvedPath)) {
+    return { isValid: false, error: 'Path must be absolute' };
+  }
+
+  // Check against blocked system paths
+  const lowerPath = resolvedPath.toLowerCase();
+  for (const blocked of BLOCKED_SYSTEM_PATHS) {
+    const blockedLower = blocked.toLowerCase();
+    if (lowerPath === blockedLower || lowerPath.startsWith(`${blockedLower  }/`) || lowerPath.startsWith(`${blockedLower  }\\`)) {
+      return { isValid: false, error: 'Access to system directories is not allowed' };
+    }
+  }
+
+  // Check that path matches allowed patterns
+  const matchesAllowed = ALLOWED_PATH_PATTERNS.some(pattern => pattern.test(resolvedPath));
+  if (!matchesAllowed) {
+    return {
+      isValid: false,
+      error: 'Path is outside of allowed workspace directories',
+    };
+  }
+
+  // Verify the path exists and is a directory
+  try {
+    if (!existsSync(resolvedPath)) {
+      return { isValid: false, error: 'Path does not exist' };
+    }
+
+    const stats = statSync(resolvedPath);
+    if (!stats.isDirectory()) {
+      return { isValid: false, error: 'Path is not a directory' };
+    }
+
+    // Resolve symlinks to verify the real path is also safe
+    const realPath = realpathSync(resolvedPath);
+    if (realPath !== resolvedPath) {
+      // Re-validate the resolved symlink path
+      const symlinkValidation = validatePath(realPath);
+      if (!symlinkValidation.isValid) {
+        return {
+          isValid: false,
+          error: `Symlink target is not allowed: ${symlinkValidation.error}`,
+        };
+      }
+      resolvedPath = realPath;
+    }
+  } catch (error) {
+    return {
+      isValid: false,
+      error: `Cannot access path: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    };
+  }
+
+  return { isValid: true, resolvedPath };
+}
+
+/**
+ * Service for managing workspace roots from MCP clients
+ *
+ * This class provides secure handling of workspace roots, enabling
+ * automatic discovery of configuration files (like dw.json) in the
+ * agent's working directories.
+ */
+export class WorkspaceRootsService {
+  private roots: ValidatedWorkspaceRoot[] = [];
+  private logger: Logger;
+
+  constructor(logger?: Logger) {
+    this.logger = logger ?? Logger.getInstance();
+  }
+
+  /**
+   * Update workspace roots from MCP client response
+   *
+   * @param clientRoots - Array of roots from the MCP client (roots/list response)
+   * @returns Array of successfully validated roots
+   */
+  updateRoots(clientRoots: Array<{ uri: string; name?: string }>): ValidatedWorkspaceRoot[] {
+    this.roots = [];
+
+    for (const root of clientRoots) {
+      const validation = validateFileUri(root.uri);
+
+      if (validation.isValid && validation.resolvedPath) {
+        this.roots.push({
+          uri: root.uri,
+          path: validation.resolvedPath,
+          name: root.name,
+        });
+        this.logger.debug(`Validated workspace root: ${root.name ?? root.uri} -> ${validation.resolvedPath}`);
+      } else {
+        this.logger.debug(`Rejected workspace root: ${root.uri} - ${validation.error}`);
+      }
+    }
+
+    this.logger.log(`Workspace roots updated: ${this.roots.length} valid root(s)`);
+    return [...this.roots];
+  }
+
+  /**
+   * Get all validated workspace roots
+   */
+  getRoots(): ValidatedWorkspaceRoot[] {
+    return [...this.roots];
+  }
+
+  /**
+   * Search for a file in all workspace roots
+   *
+   * @param filename - The filename to search for (e.g., 'dw.json')
+   * @param maxDepth - Maximum directory depth to search (default: 2)
+   * @returns The first matching file path, or undefined if not found
+   */
+  findFile(filename: string, maxDepth: number = 2): string | undefined {
+    // Validate filename to prevent path traversal
+    if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
+      this.logger.debug(`Invalid filename rejected: ${filename}`);
+      return undefined;
+    }
+
+    for (const root of this.roots) {
+      const found = this.searchInDirectory(root.path, filename, 0, maxDepth);
+      if (found) {
+        this.logger.debug(`Found ${filename} in workspace root: ${found}`);
+        return found;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Recursively search for a file in a directory
+   *
+   * @param directory - Directory to search
+   * @param filename - Filename to find
+   * @param currentDepth - Current recursion depth
+   * @param maxDepth - Maximum depth to search
+   * @returns File path if found, undefined otherwise
+   */
+  private searchInDirectory(
+    directory: string,
+    filename: string,
+    currentDepth: number,
+    maxDepth: number,
+  ): string | undefined {
+    // Check immediate file
+    const filePath = join(directory, filename);
+    if (existsSync(filePath)) {
+      try {
+        const stats = statSync(filePath);
+        if (stats.isFile()) {
+          return filePath;
+        }
+      } catch {
+        // Ignore access errors
+      }
+    }
+
+    // Don't recurse deeper if at max depth
+    if (currentDepth >= maxDepth) {
+      return undefined;
+    }
+
+    // Search subdirectories (limited set to avoid excessive scanning)
+    const allowedSubdirs = ['cartridges', 'config', '.vscode', 'sfcc'];
+    for (const subdir of allowedSubdirs) {
+      const subdirPath = join(directory, subdir);
+      try {
+        if (existsSync(subdirPath) && statSync(subdirPath).isDirectory()) {
+          const found = this.searchInDirectory(subdirPath, filename, currentDepth + 1, maxDepth);
+          if (found) {
+            return found;
+          }
+        }
+      } catch {
+        // Ignore access errors
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Check if a given path is within any of the validated workspace roots
+   *
+   * This is useful for validating that file operations stay within
+   * the allowed workspace boundaries.
+   *
+   * @param filePath - The path to check
+   * @returns true if the path is within a workspace root
+   */
+  isPathWithinRoots(filePath: string): boolean {
+    try {
+      // Normalize and resolve the path
+      const normalizedPath = normalize(resolve(filePath));
+
+      // For existing paths, resolve symlinks to get the real path
+      // For non-existing paths (like potential new files), use the normalized path
+      let checkPath = normalizedPath;
+      if (existsSync(normalizedPath)) {
+        checkPath = realpathSync(normalizedPath);
+      } else {
+        // For non-existing paths, try to resolve symlinks in the parent directory chain
+        // This handles cases like /var/folders on macOS which is a symlink to /private/var/folders
+        let parentPath = normalizedPath;
+        while (parentPath !== '/') {
+          const parent = resolve(parentPath, '..');
+          if (parent === parentPath) {break;}
+          parentPath = parent;
+          if (existsSync(parentPath)) {
+            // Found an existing parent, resolve its realpath and reconstruct
+            const realParent = realpathSync(parentPath);
+            const relativePart = normalizedPath.substring(parentPath.length);
+            checkPath = realParent + relativePart;
+            break;
+          }
+        }
+      }
+
+      return this.roots.some(root => {
+        return checkPath.startsWith(`${root.path  }/`) || checkPath.startsWith(`${root.path  }\\`) || checkPath === root.path;
+      });
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Clear all workspace roots
+   */
+  clear(): void {
+    this.roots = [];
+    this.logger.debug('Workspace roots cleared');
+  }
+
+  /**
+   * Discover dw.json from MCP client workspace roots
+   *
+   * This is the main entry point for workspace-based config discovery.
+   * It takes raw roots from the MCP client, validates them, searches for
+   * dw.json, and loads the configuration.
+   *
+   * @param clientRoots - Raw roots array from server.listRoots() response
+   * @returns Discovery result with config if found
+   */
+  discoverDwJson(clientRoots: MCPClientRoot[] | undefined): WorkspaceDiscoveryResult {
+    this.logger.log('[WorkspaceRoots] Starting dw.json discovery from client roots');
+
+    // Log what we received from the client
+    if (!clientRoots) {
+      this.logger.log('[WorkspaceRoots] No roots array received from client (undefined)');
+      return { success: false, reason: 'No roots array received from client' };
+    }
+
+    this.logger.log(`[WorkspaceRoots] Received ${clientRoots.length} root(s) from client`);
+
+    if (clientRoots.length === 0) {
+      this.logger.log('[WorkspaceRoots] Client returned empty roots array');
+      return { success: false, reason: 'Client returned empty roots array', rootsReceived: 0 };
+    }
+
+    // Log each root we received
+    clientRoots.forEach((root, index) => {
+      this.logger.log(`[WorkspaceRoots] Root ${index + 1}: uri="${root.uri}", name="${root.name ?? '(none)'}"`);
+    });
+
+    // Validate and store the workspace roots
+    const validRoots = this.updateRoots(clientRoots);
+    this.logger.log(`[WorkspaceRoots] After validation: ${validRoots.length} valid root(s)`);
+
+    if (validRoots.length === 0) {
+      this.logger.log('[WorkspaceRoots] No valid roots after security validation');
+      return {
+        success: false,
+        reason: 'No valid workspace roots after security validation',
+        rootsReceived: clientRoots.length,
+        validRoots: 0,
+      };
+    }
+
+    // Log validated roots
+    validRoots.forEach((root, index) => {
+      this.logger.log(`[WorkspaceRoots] Valid root ${index + 1}: path="${root.path}"`);
+    });
+
+    // Search for dw.json in workspace roots
+    this.logger.log('[WorkspaceRoots] Searching for dw.json in workspace roots...');
+    const dwJsonPath = this.findFile('dw.json');
+
+    if (!dwJsonPath) {
+      this.logger.log('[WorkspaceRoots] No dw.json found in any workspace root');
+      return {
+        success: false,
+        reason: 'No dw.json found in workspace roots',
+        rootsReceived: clientRoots.length,
+        validRoots: validRoots.length,
+      };
+    }
+
+    this.logger.log(`[WorkspaceRoots] Found dw.json at: ${dwJsonPath}`);
+
+    // Load and validate the dw.json
+    try {
+      const config = loadSecureDwJson(dwJsonPath);
+      this.logger.log('[WorkspaceRoots] Successfully loaded dw.json');
+      this.logger.log(`[WorkspaceRoots]   hostname: ${config.hostname}`);
+      this.logger.log(`[WorkspaceRoots]   username: ${config.username ? '(set)' : '(not set)'}`);
+      this.logger.log(`[WorkspaceRoots]   password: ${config.password ? '(set)' : '(not set)'}`);
+      this.logger.log(`[WorkspaceRoots]   client-id: ${config['client-id'] ? '(set)' : '(not set)'}`);
+      this.logger.log(`[WorkspaceRoots]   client-secret: ${config['client-secret'] ? '(set)' : '(not set)'}`);
+
+      return {
+        success: true,
+        config,
+        dwJsonPath,
+        rootsReceived: clientRoots.length,
+        validRoots: validRoots.length,
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`[WorkspaceRoots] Failed to load dw.json: ${errorMessage}`);
+      return {
+        success: false,
+        reason: `Failed to load dw.json: ${errorMessage}`,
+        dwJsonPath,
+        rootsReceived: clientRoots.length,
+        validRoots: validRoots.length,
+      };
+    }
+  }
+}
+
+/**
+ * Validate a path for dw.json access
+ *
+ * This is a standalone function that can be used by the dw-json-loader
+ * to validate paths before attempting to read them.
+ *
+ * @param filePath - The path to validate
+ * @returns Object with isValid flag and optional error message
+ */
+export function validateDwJsonPath(filePath: string): { isValid: boolean; error?: string } {
+  // First validate the directory containing the file
+  const directory = resolve(filePath, '..');
+  const validation = validatePath(directory);
+
+  if (!validation.isValid) {
+    return validation;
+  }
+
+  // Additional validation: ensure it's a .json file
+  if (!filePath.toLowerCase().endsWith('.json')) {
+    return { isValid: false, error: 'Only .json files are allowed' };
+  }
+
+  return { isValid: true };
+}

package/src/constants/index.ts

@@ -0,0 +1 @@
+// Constants module currently has no re-exports; reserved for future shared constants.