meshcentral-terminal.js

Go to the documentation of this file.

/**
 * @file MeshCentral Terminal WebSocket Proxy
 * @description
 * Provides secure WebSocket-based remote terminal/console access to RMM agents via MeshCentral
 * integration. Acts as authentication proxy and message router between client web terminals
 * and MeshCentral's WebSocket API, enabling browser-based shell access (CMD, PowerShell, Bash)
 * without iframe complexity while maintaining multi-tenant security isolation.
 *
 * Key features:
 * - **WebSocket proxy**: Bidirectional message forwarding for terminal I/O
 * - **Session validation**: Verifies session tokens from meshcentral_sessions table
 * - **Tenant isolation**: Each tenant uses separate MeshCentral API connection
 * - **Multiple shell types**: Windows CMD, PowerShell, Linux Bash, macOS Terminal
 * - **Real-time interaction**: Full terminal emulation with ANSI color support
 * - **No iframe needed**: Direct API integration eliminates cross-origin issues
 *
 * 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 WebSocket connection to tenant's MeshCentral instance
 * 5. Backend sends terminal request message to MeshCentral (type: 'console')
 * 6. Terminal I/O messages forwarded bidirectionally until disconnection
 * 7. Session maintained with keepalive pings until client disconnects
 *
 * Terminal types supported (platform-dependent):
 * - **Windows**: CMD (default), PowerShell
 * - **Linux**: Bash, sh, zsh (depends on agent configuration)
 * - **macOS**: Terminal (zsh/bash)
 *
 * Message protocol (client -> MeshCentral):
 * - **Keystroke**: `{ type: 'console', data: 'command\\n' }`
 * - **Resize**: `{ type: 'console', cols: 80, rows: 24 }`
 * - **Close**: WebSocket close frame
 *
 * Message protocol (MeshCentral -> client):
 * - **Output**: `{ type: 'console', data: 'output text' }`
 * - **Connected**: `{ type: 'console', msg: 'Terminal Ready' }`
 * - **Disconnected**: `{ type: 'console', msg: 'Disconnected' }`
 *
 * Security:
 * - Session token required for all connections
 * - Session expiration enforced (`expires_at` check)
 * - Tenant-based API isolation (no cross-tenant terminal access)
 * - Agent ID validated against session
 * @module routes/meshcentral-terminal
 * @requires ws - WebSocket server implementation
 * @requires ../middleware/auth - JWT authentication middleware
 * @requires ../db - PostgreSQL database connection for session validation
 * @requires ./meshcentral - Tenant MeshCentral API connection manager
 * @see {@link module:routes/meshcentral}
 * @see {@link module:routes/meshcentral-files}
 */
 
/**
 * MeshCentral Terminal WebSocket Proxy
 * Provides secure WebSocket connection to MeshCentral terminal
 * No iframe needed - direct API integration
 */
 
const WebSocket = require('ws');
const authenticateToken = require('../middleware/auth');
const db = require('../db');
const { getTenantMeshAPI } = require('./meshcentral');
 
/**
 * Initializes WebSocket server for MeshCentral remote terminal/console operations.
 *
 * Sets up WebSocket upgrade handler on HTTP server to intercept connections at
 * /api/meshcentral/terminal path. Creates isolated WebSocket connection per client,
 * validates session credentials, establishes MeshCentral API connection, sends terminal
 * request to agent, and maintains bidirectional terminal I/O proxy until disconnection.
 *
 * Connection URL format:
 * ```
 * ws://api.ibghub.com/api/meshcentral/terminal?sessionToken=abc123&agentId=456
 * ```
 *
 * Terminal I/O flow:
 * ```
 * Client Keystroke -> Backend WS -> MeshCentral API -> Agent Terminal
 * Client Terminal <- Backend WS <- MeshCentral API <- Agent Output
 * ```
 *
 * Example terminal session:
 * ```javascript
 * // Client connects
 * const ws = new WebSocket('ws://api.ibghub.com/api/meshcentral/terminal?sessionToken=xxx&agentId=123');
 *
 * // Send command
 * ws.send(JSON.stringify({ type: 'console', data: 'dir\\n' }));
 *
 * // Receive output
 * ws.onmessage = (event) => {
 * const msg = JSON.parse(event.data);
 * if (msg.type === 'console') {
 * console.log(msg.data); // Terminal output with ANSI codes
 * }
 * };
 * ```
 *
 * Error handling:
 * - Sends error message and closes with code 1000 if missing parameters
 * - Sends error message and closes if session invalid/expired
 * - Sends error message and closes if MeshCentral connection fails
 * - Keepalive pings prevent idle connection timeouts
 * @function setupTerminalWebSocket
 * @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 { setupTerminalWebSocket } = require('./routes/meshcentral-terminal');
 * 
 * const server = http.createServer(app);
 * setupTerminalWebSocket(server);
 * server.listen(3000);
 */
 
/**
 * Setup WebSocket server for terminal connections
 * @param {Express.Application} app - Express app instance
 * @param {http.Server} server - HTTP server instance
 */
function setupTerminalWebSocket(server) {
  const wss = new WebSocket.Server({ 
    noServer: true,
    path: '/meshcentral/terminal'
  });
 
  // Handle WebSocket upgrade
  server.on('upgrade', (request, socket, head) => {
    if (request.url.startsWith('/api/meshcentral/terminal')) {
      wss.handleUpgrade(request, socket, head, (ws) => {
        wss.emit('connection', ws, request);
      });
    }
  });
 
  wss.on('connection', async (ws, request) => {
    console.log('🔌 Terminal WebSocket connection established');
 
    try {
      // Extract sessionToken from URL query
      const url = new URL(request.url, 'http://localhost');
      const sessionToken = url.searchParams.get('sessionToken');
      const agentId = url.searchParams.get('agentId');
 
      if (!sessionToken || !agentId) {
        ws.send(JSON.stringify({ error: 'Missing sessionToken or agentId' }));
        ws.close();
        return;
      }
 
      // Validate session
      const sessionResult = await db.query(
        'SELECT s.*, a.meshcentral_nodeid, a.tenant_id FROM meshcentral_sessions s JOIN agents a ON s.agent_id = a.agent_id WHERE s.session_token = $1 AND s.expires_at > NOW()',
        [sessionToken]
      );
 
      if (sessionResult.rows.length === 0) {
        ws.send(JSON.stringify({ error: 'Invalid or expired session' }));
        ws.close();
        return;
      }
 
      const session = sessionResult.rows[0];
      const nodeId = session.meshcentral_nodeid;
      const tenantId = session.tenant_id;
 
      console.log(`✅ Terminal session validated: nodeId=${nodeId}`);
 
      // Get tenant's MeshCentral API client
      const api = await getTenantMeshAPI(tenantId);
      
      // Connect to MeshCentral WebSocket
      await api.connectWebSocket();
 
      console.log('🔌 Connected to MeshCentral WebSocket');
 
      // Request terminal access to the device
      // MeshCentral protocol: JSON messages with action and nodeid
      const terminalRequest = {
        action: 'msg',
        type: 'console',
        nodeid: nodeId,
        msg: JSON.stringify({
          type: 'console',
          action: 'start'
        })
      };
 
      api.ws.send(JSON.stringify(terminalRequest));
 
      // Forward messages from MeshCentral to client
      api.ws.on('message', (data) => {
        try {
          const message = JSON.parse(data.toString());
          
          // Filter terminal output messages
          if (message.type === 'console' || message.action === 'msg') {
            ws.send(JSON.stringify(message));
          }
        } catch (err) {
          console.error('Error parsing MeshCentral message:', err);
        }
      });
 
      // Forward messages from client to MeshCentral (terminal input)
      ws.on('message', (data) => {
        try {
          const message = JSON.parse(data.toString());
          
          // Wrap client messages for MeshCentral
          const meshMessage = {
            action: 'msg',
            type: 'console',
            nodeid: nodeId,
            msg: JSON.stringify(message)
          };
 
          api.ws.send(JSON.stringify(meshMessage));
        } catch (err) {
          console.error('Error forwarding to MeshCentral:', err);
        }
      });
 
      // Handle disconnection
      ws.on('close', () => {
        console.log('🔌 Terminal WebSocket disconnected');
        if (api.ws && api.ws.readyState === WebSocket.OPEN) {
          // Send close terminal command
          const closeMsg = {
            action: 'msg',
            type: 'console',
            nodeid: nodeId,
            msg: JSON.stringify({ action: 'close' })
          };
          api.ws.send(JSON.stringify(closeMsg));
        }
      });
 
      ws.on('error', (error) => {
        console.error('Terminal WebSocket error:', error);
      });
 
    } catch (error) {
      console.error('❌ Terminal setup error:', error);
      ws.send(JSON.stringify({ error: 'Failed to setup terminal', message: error.message }));
      ws.close();
    }
  });
 
  console.log('✅ Terminal WebSocket server setup complete');
}
 
module.exports = { setupTerminalWebSocket };