feat(satellite): validate GitHub deployment base directory permissions

Author: Lasim

services/satellite/Dockerfile

@@ -28,6 +28,12 @@ RUN pip3 install --break-system-packages uv && \
 RUN mkdir -p /opt/deploystack/mcp-cache && \
     chown -R deploystack:deploystack /opt/deploystack
 
+# Create GitHub deployment base directory for production tmpfs mounts
+# Required when NODE_ENV=production and platform=linux
+RUN mkdir -p /opt/mcp-deployments && \
+    chown deploystack:deploystack /opt/mcp-deployments && \
+    chmod 755 /opt/mcp-deployments
+
 WORKDIR /app
 
 # Create persistent_data directory with proper ownership

services/satellite/src/lib/deployment-directory-validator.ts

@@ -0,0 +1,112 @@
+import { access, constants } from 'fs/promises';
+import { Logger } from 'pino';
+
+/**
+ * Validate GitHub deployment base directory permissions
+ * Follows fail-fast pattern - satellite cannot start without proper permissions
+ *
+ * This check runs only in production on Linux where:
+ * - Satellite runs as 'deploystack' user (UID 1001)
+ * - /opt/mcp-deployments must exist with deploystack:deploystack ownership
+ * - Directory must have read/write permissions for tmpfs mount operations
+ */
+export async function validateDeploymentDirectory(
+  baseDir: string,
+  logger: Logger
+): Promise<void> {
+  logger.info({
+    operation: 'deployment_directory_validation_start',
+    path: baseDir
+  }, 'Validating GitHub deployment base directory permissions...');
+
+  try {
+    // Check if directory exists
+    await access(baseDir, constants.F_OK);
+
+    logger.debug({
+      operation: 'deployment_directory_exists',
+      path: baseDir
+    }, 'GitHub deployment base directory exists');
+  } catch (error) {
+    const accessError = error as NodeJS.ErrnoException;
+
+    if (accessError.code === 'ENOENT') {
+      logger.fatal({
+        operation: 'deployment_directory_missing',
+        path: baseDir,
+        error: 'Directory does not exist',
+        fix_command: `sudo mkdir -p ${baseDir} && sudo chown deploystack:deploystack ${baseDir} && sudo chmod 755 ${baseDir}`,
+        help: 'Create directory with correct ownership during satellite setup'
+      }, `❌ FATAL: GitHub deployment base directory does not exist: ${baseDir}`);
+
+      throw new Error(
+        `GitHub deployment base directory missing: ${baseDir}. ` +
+        `Fix: sudo mkdir -p ${baseDir} && sudo chown deploystack:deploystack ${baseDir}`
+      );
+    } else {
+      // Unexpected error accessing directory
+      logger.fatal({
+        operation: 'deployment_directory_access_error',
+        path: baseDir,
+        error: accessError.message
+      }, `❌ FATAL: Cannot access GitHub deployment base directory: ${baseDir}`);
+
+      throw new Error(`Failed to access deployment base directory: ${accessError.message}`);
+    }
+  }
+
+  // Check read permission
+  try {
+    await access(baseDir, constants.R_OK);
+    logger.debug({
+      operation: 'deployment_directory_readable',
+      path: baseDir
+    }, 'GitHub deployment base directory is readable');
+  } catch (error) {
+    const readError = error as NodeJS.ErrnoException;
+
+    logger.fatal({
+      operation: 'deployment_directory_not_readable',
+      path: baseDir,
+      error: readError.message,
+      current_user: process.env.USER || 'unknown',
+      fix_command: `sudo chown -R deploystack:deploystack ${baseDir} && sudo chmod 755 ${baseDir}`,
+      help: 'Directory must be readable by deploystack user (UID 1001)'
+    }, `❌ FATAL: No read permission for GitHub deployment base directory: ${baseDir}`);
+
+    throw new Error(
+      `No read permission for ${baseDir}. ` +
+      `Fix: sudo chown deploystack:deploystack ${baseDir} && sudo chmod 755 ${baseDir}`
+    );
+  }
+
+  // Check write permission
+  try {
+    await access(baseDir, constants.W_OK);
+    logger.debug({
+      operation: 'deployment_directory_writable',
+      path: baseDir
+    }, 'GitHub deployment base directory is writable');
+  } catch (error) {
+    const writeError = error as NodeJS.ErrnoException;
+
+    logger.fatal({
+      operation: 'deployment_directory_not_writable',
+      path: baseDir,
+      error: writeError.message,
+      current_user: process.env.USER || 'unknown',
+      fix_command: `sudo chown -R deploystack:deploystack ${baseDir} && sudo chmod 755 ${baseDir}`,
+      help: 'Directory must be writable by deploystack user (UID 1001) to create tmpfs mounts'
+    }, `❌ FATAL: No write permission for GitHub deployment base directory: ${baseDir}`);
+
+    throw new Error(
+      `No write permission for ${baseDir}. ` +
+      `Fix: sudo chown deploystack:deploystack ${baseDir} && sudo chmod 755 ${baseDir}`
+    );
+  }
+
+  logger.info({
+    operation: 'deployment_directory_validation_success',
+    path: baseDir
+  }, `✅ GitHub deployment base directory validated: ${baseDir}`);
+}

services/satellite/src/server.ts

@@ -237,6 +237,24 @@ export async function createServer() {
     process.exit(1);
   }
 
+  // Validate GitHub deployment base directory permissions (production Linux only)
+  if (process.env.NODE_ENV === 'production' && process.platform === 'linux') {
+    const { githubDeploymentBaseDir } = await import('./config/nsjail');
+    const { validateDeploymentDirectory } = await import('./lib/deployment-directory-validator');
+
+    try {
+      await validateDeploymentDirectory(githubDeploymentBaseDir, server.log as any);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      server.log.fatal({
+        operation: 'deployment_directory_validation_failed',
+        path: githubDeploymentBaseDir,
+        error: errorMessage
+      }, 'Failed to validate GitHub deployment base directory - cannot continue');
+      process.exit(1);
+    }
+  }
+
   // Initialize MCP Activity Tracker for personal dashboard feature
   const activityTracker = new McpActivityTracker(server.log);
   server.decorate('activityTracker', activityTracker);