meshcentral-files.js

Go to the documentation of this file.

/**
 * @file MeshCentral File Browser WebSocket Proxy
 * @description
 * Provides secure WebSocket-based file management access to remote agents via MeshCentral
 * integration. Acts as authentication proxy and message router between client browsers
 * and MeshCentral's WebSocket API, eliminating iframe authentication complexity while
 * maintaining multi-tenant security isolation.
 *
 * Key features:
 * - **WebSocket proxy**: Bidirectional message forwarding between client and MeshCentral
 * - **Session validation**: Verifies session tokens from meshcentral_sessions table
 * - **Tenant isolation**: Each tenant uses separate MeshCentral API connection
 * - **File operations**: ls, download, upload, rm, rename, mkdir
 * - **Real-time updates**: Live directory listing updates and file operation status
 *
 * Protocol flow:
 * 1. Client connects WebSocket with agentId and sessionToken query parameters
 * 2. Backend validates session token existence and expiration in database
 * 3. Backend retrieves agent's meshcentral_nodeid and tenant_id
 * 4. Backend establishes connection to tenant's MeshCentral instance
 * 5. Messages forwarded bidirectionally with automatic protocol translation
 * 6. Session maintained until client disconnects or session expires
 *
 * Supported file actions (client -> MeshCentral):
 * - **ls**: List files and directories in path
 * - **download**: Download file by path
 * - **upload**: Upload file to path
 * - **rm**: Delete file or directory
 * - **rename**: Rename/move file or directory
 * - **mkdir**: Create new directory
 *
 * Message types (MeshCentral -> client):
 * - **notify**: Operation status notifications
 * - **download**: File download data stream
 * - **uploaddone**: Upload completion confirmation
 * - **ls**: Directory listing results
 *
 * Security:
 * - Session token required for all connections
 * - Session expiration enforced (expires_at check)
 * - Tenant-based API isolation (no cross-tenant access)
 * - Agent ID validated against session
 * @module routes/meshcentral-files
 * @requires ws - WebSocket server implementation
 * @requires url - URL parsing for query parameters
 * @requires ./meshcentral - Tenant MeshCentral API connection manager
 * @requires ../db - PostgreSQL database connection for session validation
 * @see {@link module:routes/meshcentral}
 */
 
const WebSocket = require('ws');
const url = require('url');
const { getTenantMeshAPI } = require('./meshcentral');
const db = require('../db');
 
/**
 * Initializes WebSocket server for MeshCentral file browser operations.
 *
 * Sets up WebSocket upgrade handler on HTTP server to intercept connections at
 * /api/meshcentral/files path. Creates isolated WebSocket connection per client,
 * validates session credentials, establishes MeshCentral API connection, and
 * maintains bidirectional message proxy until client disconnects.
 *
 * Connection URL format:
 * ```
 * ws://api.ibghub.com/api/meshcentral/files?sessionToken=abc123&agentId=456
 * ```
 *
 * Message protocol (client -> MeshCentral):
 * ```json
 * {
 * "action": "ls",
 * "path": "/",
 * "reqid": 1
 * }
 * ```
 *
 * Message protocol (MeshCentral -> client):
 * ```json
 * {
 * "action": "ls",
 * "reqid": 1,
 * "path": "/",
 * "dir": [
 * {"name": "file.txt", "size": 1024, "type": 3, "mtime": 1642012800},
 * {"name": "folder", "size": 0, "type": 2, "mtime": 1642012800}
 * ]
 * }
 * ```
 *
 * Error handling:
 * - Closes connection with code 1008 (policy violation) if missing parameters
 * - Closes connection with code 1008 if session invalid/expired
 * - Closes connection with code 1011 (internal error) if MeshCentral connection fails
 * @function setupFilesWebSocket
 * @param {http.Server} server - HTTP server instance to attach WebSocket upgrade handler
 * @returns {void}
 * @throws {Error} If WebSocket server initialization fails
 * @example
 * const http = require('http');
 * const { setupFilesWebSocket } = require('./routes/meshcentral-files');
 * 
 * const server = http.createServer(app);
 * setupFilesWebSocket(server);
 * server.listen(3000);
 */
 
/**
 * Setup file browser WebSocket server
 * @param {http.Server} server - HTTP server instance
 */
function setupFilesWebSocket(server) {
  const wss = new WebSocket.Server({ 
    noServer: true,
    path: '/meshcentral/files'
  });
 
  // Handle WebSocket upgrade
  server.on('upgrade', (request, socket, head) => {
    const pathname = url.parse(request.url).pathname;
    
    if (pathname === '/api/meshcentral/files') {
      wss.handleUpgrade(request, socket, head, (ws) => {
        wss.emit('connection', ws, request);
      });
    }
  });
 
  wss.on('connection', async (ws, request) => {
    const params = url.parse(request.url, true).query;
    const sessionToken = params.sessionToken;
    const agentId = params.agentId;
 
    console.log(`[Files WebSocket] New connection: agentId=${agentId}, sessionToken=${sessionToken?.substring(0, 8)}...`);
 
    if (!sessionToken || !agentId) {
      console.error('[Files WebSocket] Missing sessionToken or agentId');
      ws.close(1008, 'Missing required parameters');
      return;
    }
 
    try {
      // Validate session and get device info
      const sessionResult = await db.query(
        `SELECT s.*, a.meshcentral_nodeid, a.tenant_id 
         FROM meshcentral_sessions s
         JOIN agents a ON a.agent_id = s.agent_id
         WHERE s.session_token = $1 AND s.agent_id = $2 AND s.expires_at > NOW()`,
        [sessionToken, agentId]
      );
 
      if (sessionResult.rows.length === 0) {
        console.error('[Files WebSocket] Invalid or expired session');
        ws.close(1008, 'Invalid or expired session');
        return;
      }
 
      const session = sessionResult.rows[0];
      const nodeId = session.meshcentral_nodeid;
      const tenantId = session.tenant_id;
 
      console.log(`[Files WebSocket] Session validated: tenantId=${tenantId}, nodeId=${nodeId}`);
 
      // Get tenant's MeshCentral API connection
      const api = await getTenantMeshAPI(tenantId);
      if (!api || !api.ws) {
        console.error('[Files WebSocket] Failed to connect to MeshCentral');
        ws.close(1011, 'MeshCentral connection failed');
        return;
      }
 
      console.log(`[Files WebSocket] Connected to MeshCentral for tenant ${tenantId}`);
 
      // Forward messages from MeshCentral to client
      api.ws.on('message', (data) => {
        try {
          const message = JSON.parse(data.toString());
          
          // Only forward file-related messages
          if (message.type === 'notify' || 
              message.type === 'download' ||
              message.type === 'uploaddone' ||
              message.action === 'ls' ||
              message.action === 'download' ||
              message.action === 'upload') {
            
            console.log(`[Files WebSocket] -> Client: ${message.action || message.type}`);
            ws.send(JSON.stringify(message));
          }
        } catch (err) {
          console.error('[Files WebSocket] Error parsing MeshCentral message:', err);
        }
      });
 
      // Forward messages from client to MeshCentral
      ws.on('message', (data) => {
        try {
          const clientMessage = JSON.parse(data.toString());
          console.log(`[Files WebSocket] <- Client: ${clientMessage.action}`, {
            path: clientMessage.path,
            reqid: clientMessage.reqid
          });
 
          // Build MeshCentral protocol message
          const meshMessage = {
            action: 'msg',
            type: 'files',
            nodeid: nodeId,
            ...clientMessage
          };
 
          api.ws.send(JSON.stringify(meshMessage));
        } catch (err) {
          console.error('[Files WebSocket] Error forwarding client message:', err);
          ws.send(JSON.stringify({
            type: 'error',
            message: 'Failed to process request'
          }));
        }
      });
 
      // Handle disconnection
      ws.on('close', () => {
        console.log(`[Files WebSocket] Client disconnected: agentId=${agentId}`);
        // Note: We don't close api.ws as it may be shared by other connections
      });
 
      ws.on('error', (err) => {
        console.error('[Files WebSocket] WebSocket error:', err);
      });
 
      // Send initial connection success
      ws.send(JSON.stringify({
        type: 'connected',
        nodeId: nodeId
      }));
 
    } catch (err) {
      console.error('[Files WebSocket] Connection error:', err);
      ws.close(1011, 'Internal server error');
    }
  });
 
  console.log('[Files WebSocket] File browser WebSocket server setup complete');
}
 
module.exports = { setupFilesWebSocket };