refactor(satellite): update command path handling for dynamic resolution

Author: Lasim

services/satellite/src/config/security-validation.ts

@@ -23,14 +23,12 @@ export interface ValidationResult {
 export const ALLOWED_COMMANDS = new Set(['npx', 'node', 'uvx', 'python', 'python3']);
 
 /**
- * Command path mappings for nsjail (which requires full paths)
+ * DEPRECATED: Command paths are now resolved dynamically at runtime
+ * See runtime-validator.ts for dynamic path resolution
+ * This is kept for backwards compatibility but should not be used
  */
 export const COMMAND_PATHS: Record<string, string> = {
-  'npx': '/usr/bin/npx',
-  'node': '/usr/bin/node',
-  'uvx': '/usr/bin/uvx',
-  'python': '/usr/bin/python',
-  'python3': '/usr/bin/python3'
+  // Paths resolved dynamically - see DEPLOYSTACK_COMMAND_CACHE global
 };
 
 /**
@@ -192,9 +190,13 @@ export function validateArgs(args: string[], logger?: Logger): ValidationResult
 }
 
 /**
- * Resolves command to full path for nsjail execution
- * SECURE VERSION: Only returns paths for allowed commands
+ * DEPRECATED: Resolves command to full path for nsjail execution
  *
+ * This function is deprecated. Command paths are now resolved dynamically
+ * at startup and cached in DEPLOYSTACK_COMMAND_CACHE global.
+ * Use the cache directly via nsjail-spawner's getCommandPath() function.
+ *
+ * @deprecated Use dynamic path resolution from runtime-validator.ts
  * @param command - The command name (e.g., 'npx', 'node')
  * @param logger - Logger for security warnings
  * @returns Full path to command
@@ -207,16 +209,18 @@ export function resolveCommandPath(command: string, logger?: Logger): string {
     throw new Error(validation.error || 'Command not allowed');
   }
 
-  // Get the path from our known mappings
+  // Get path from runtime-resolved cache
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const cache = (global as any).DEPLOYSTACK_COMMAND_CACHE as Map<string, string> | undefined;
   const normalizedCommand = command.trim().toLowerCase();
-  const path = COMMAND_PATHS[normalizedCommand];
 
-  if (!path) {
-    // This shouldn't happen if ALLOWED_COMMANDS and COMMAND_PATHS are in sync
-    throw new Error(`No path mapping for command '${command}'`);
+  if (cache && cache.has(normalizedCommand)) {
+    return cache.get(normalizedCommand)!;
   }
 
-  return path;
+  // Fallback for backwards compatibility (should not happen after initialization)
+  console.warn(`WARNING: Command ${command} not found in cache, using /usr/bin fallback`);
+  return `/usr/bin/${normalizedCommand}`;
 }
 
 /**

services/satellite/src/process/nsjail-spawner.ts

@@ -7,8 +7,7 @@ import { MCPServerConfig } from './types';
 import { nsjailConfig, mcpCacheBaseDir, BLOCKED_ENV_VARS } from '../config/nsjail';
 import {
   validateCommand,
-  validateArgs,
-  COMMAND_PATHS
+  validateArgs
 } from '../config/security-validation';
 
 /**
@@ -18,14 +17,21 @@ import {
 const ALLOWED_BUILD_COMMANDS = new Set(['npm', 'uv', 'pip', 'pip3']);
 
 /**
- * Build command path mappings for nsjail
+ * Get command path from global cache
+ * Falls back to /usr/bin if cache miss (should not happen after initialization)
  */
-const BUILD_COMMAND_PATHS: Record<string, string> = {
-  'npm': '/usr/bin/npm',
-  'uv': '/usr/bin/uv',
-  'pip': '/usr/bin/pip',
-  'pip3': '/usr/bin/pip3'
-};
+function getCommandPath(command: string): string {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const cache = (global as any).DEPLOYSTACK_COMMAND_CACHE as Map<string, string> | undefined;
+
+  if (cache && cache.has(command)) {
+    return cache.get(command)!;
+  }
+
+  // Fallback to /usr/bin (should not happen after proper initialization)
+  console.warn(`WARNING: Command ${command} not found in cache, using /usr/bin fallback`);
+  return `/usr/bin/${command}`;
+}
 
 /**
  * Options for sandboxed build commands
@@ -112,6 +118,7 @@ export class ProcessSpawner {
    * Resolve command to full path for nsjail execution
    * SECURE: Only allows commands from the allowlist, rejects absolute paths
    * nsjail requires full paths for command execution
+   * Uses dynamically resolved paths from startup cache
    */
   resolveCommandPath(command: string): string {
     // Validate command first (defense in depth - backend should have validated)
@@ -125,18 +132,18 @@ export class ProcessSpawner {
       throw new Error(validation.error || `Command '${command}' not allowed`);
     }
 
-    // Get path from secure mappings (only known-safe commands)
+    // Get path from runtime-resolved cache (dynamically found at startup)
     const normalizedCommand = command.trim().toLowerCase();
-    const path = COMMAND_PATHS[normalizedCommand];
+    const path = getCommandPath(normalizedCommand);
 
     if (!path) {
-      // This shouldn't happen if ALLOWED_COMMANDS and COMMAND_PATHS are in sync
+      // This shouldn't happen if command cache was initialized
       this.logger.error({
         operation: 'resolve_command_path_no_mapping',
         command,
         normalizedCommand
-      }, `No path mapping found for allowed command '${command}'`);
-      throw new Error(`No path mapping for command '${command}'`);
+      }, `No path found for command '${command}' in cache`);
+      throw new Error(`Command path not found: ${command}`);
     }
 
     this.logger.debug({
@@ -448,10 +455,10 @@ export class ProcessSpawner {
       throw new Error(`Build command '${command}' not allowed. Allowed: ${Array.from(ALLOWED_BUILD_COMMANDS).join(', ')}`);
     }
 
-    // Get command path
-    const commandPath = BUILD_COMMAND_PATHS[normalizedCommand];
+    // Get command path from runtime-resolved cache
+    const commandPath = getCommandPath(normalizedCommand);
     if (!commandPath) {
-      throw new Error(`No path mapping for build command '${command}'`);
+      throw new Error(`Command path not found for build command '${command}'`);
     }
 
     // Get current user UID and GID

services/satellite/src/server.ts

@@ -22,7 +22,7 @@ import { McpActivityTracker } from './services/mcp-activity-tracker';
 import { ToolSearchService } from './services/tool-search-service';
 import { OAuthTokenService } from './services/oauth-token-service';
 import { SsePingService } from './services/sse-ping-service';
-import { validateSystemRuntimes } from './utils/runtime-validator';
+import { validateSystemRuntimes, initializeCommandCache } from './utils/runtime-validator';
 
 /**
  * Validate registration token format and availability
@@ -165,6 +165,12 @@ export async function createServer() {
     tempLogger.info({ operation: 'runtime_validation_complete' }, 'System runtime validation passed');
   }
 
+  // Initialize command path cache after validation
+  const commandCache = initializeCommandCache(tempLogger);
+
+  // Store command cache globally for access by process spawners
+  (global as any).DEPLOYSTACK_COMMAND_CACHE = commandCache;
+
   const server = fastify({
     logger: loggerConfig,
     disableRequestLogging: true,

services/satellite/src/utils/runtime-validator.ts

@@ -247,6 +247,115 @@ function buildWarningMessage(result: RuntimeCheckResult): string {
   return lines.join('\n');
 }
 
+/**
+ * Validate command path for security
+ * Only allow paths in known safe directories
+ */
+function validateCommandPath(commandPath: string): boolean {
+  // Must be absolute
+  if (!commandPath.startsWith('/')) return false;
+
+  // Must match allowed patterns
+  const allowedPatterns = [
+    /^\/usr\/bin\//,
+    /^\/usr\/local\/bin\//,
+    /^\/bin\//,
+    /^\/opt\/[^/]+\/bin\//
+  ];
+
+  // Add HOME-relative pattern if HOME is set
+  if (process.env.HOME) {
+    const homePattern = new RegExp(`^${process.env.HOME.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\/\.local\/bin\/`);
+    allowedPatterns.push(homePattern);
+  }
+
+  // Check if path matches any allowed pattern
+  if (!allowedPatterns.some(p => p.test(commandPath))) {
+    return false;
+  }
+
+  // Must not contain suspicious patterns
+  if (commandPath.includes('..')) return false;
+  if (commandPath.includes('//')) return false;
+
+  return true;
+}
+
+/**
+ * Resolve absolute path for a command using system PATH
+ * Returns null if command not found or validation fails
+ * Uses same PATH logic as checkCommand() for consistency
+ */
+export function resolveCommandPath(command: string): string | null {
+  try {
+    const result = spawnSync('which', [command], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000,
+      env: {
+        ...process.env,
+        PATH: buildEnhancedPath()
+      }
+    });
+
+    if (result.status === 0 && result.stdout) {
+      const path = result.stdout.trim();
+      if (validateCommandPath(path)) {
+        return path;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Initialize command path cache at startup
+ * Resolves all required commands once and caches results
+ * Called after validateSystemRuntimes() ensures they exist
+ *
+ * @param logger - Logger instance for logging resolved paths
+ * @returns Map of command name to absolute path
+ */
+export function initializeCommandCache(logger: Logger): Map<string, string> {
+  const commands = ['node', 'npm', 'npx', 'python3', 'python', 'uvx', 'uv', 'pip', 'pip3'];
+  const cache = new Map<string, string>();
+
+  logger.info(
+    { operation: 'command_cache_init_start', commands },
+    'Initializing command path cache...'
+  );
+
+  for (const command of commands) {
+    const path = resolveCommandPath(command);
+    if (path) {
+      cache.set(command, path);
+      logger.info(
+        { operation: 'command_resolved', command, path },
+        `Resolved: ${command} -> ${path}`
+      );
+    } else {
+      // Log warning but don't fail - validateSystemRuntimes already checked required commands
+      logger.info(
+        { operation: 'command_not_resolved', command },
+        `Warning: Could not resolve path for ${command} (may be optional)`
+      );
+    }
+  }
+
+  logger.info(
+    {
+      operation: 'command_cache_init_complete',
+      cached_commands: cache.size,
+      total_commands: commands.length
+    },
+    `Command path cache initialized with ${cache.size}/${commands.length} commands`
+  );
+
+  return cache;
+}
+
 /**
  * Build enhanced PATH for runtime checks
  * Exported for potential reuse in process spawner