rds.js

Go to the documentation of this file.

/**
 * @file rds.js
 * @module routes/rds
 * @description Remote Desktop Streaming (RDS) session management endpoints.
 * Handles WebSocket-based remote desktop sessions between agents and viewers.
 * Provides session lifecycle control, authentication tokens, and status monitoring.
 * @requires crypto
 * @requires jsonwebtoken
 * @requires express
 * @requires services/websocketManager
 * @author RMM-PSA Development Team
 * @copyright 2026 RMM-PSA Platform
 * @license Proprietary
 */
 
/**
 * @apiDefine RDS Remote Desktop Streaming
 * WebSocket-based remote desktop session management
 */
 
const crypto = require('crypto');
const jwt = require('jsonwebtoken');
const express = require('express');
const router = express.Router();
 
// Import WebSocket manager
const wsManager = require('../services/websocketManager');
 
// Utility: create session object
/**
 *
 * @param agentId
 */
function makeSession(agentId) {
  return {
    agentId,
    createdAt: Date.now(),
    active: true,
    viewer: null,
    agent: null
  };
}
 
/**
 * @api {post} /api/rds/start/:agent_uuid Start RDS session
 * @apiName StartRDSSession
 * @apiGroup RDS
 * @apiDescription Initiate remote desktop streaming session with agent.
 * Generates session ID, sends rds_start message to agent via WebSocket,
 * and returns JWT viewer token for authentication. Requires agent to be online.
 * @apiParam {string} agent_uuid Agent UUID
 * @apiSuccess {string} sessionId Generated session UUID
 * @apiSuccess {string} viewerToken JWT token for viewer authentication (expires in 10 minutes)
 * @apiSuccess {string} viewerUrl Viewer URL with embedded token
 * @apiError (404) {String} error="Agent not connected" Agent not online or WebSocket not ready
 * @apiError (404) {String[]} connectedAgents List of currently connected agents (for debugging)
 * @apiError (500) {String} error="Failed to start session" Internal error
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/rds/start/abc-123-uuid
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "sessionId": "550e8400-e29b-41d4-a716-446655440000",
 *     "viewerToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 *     "viewerUrl": "/api/rds/view/550e8400-e29b-41d4-a716-446655440000?t=eyJhbGc..."
 *   }
 */
router.post('/start/:agent_uuid', async (req, res) => {
  try {
    const { agent_uuid } = req.params;
 
    const ws = wsManager.agentConnections.get(agent_uuid);
    if (!ws || ws.readyState !== 1) {
      const connectedAgents = Array.from(wsManager.agentConnections.keys());
      console.error(`[RDS] Agent not connected: ${agent_uuid}. Connected agents:`, connectedAgents);
      return res.status(404).json({ error: 'Agent not connected', connectedAgents });
    }
 
    const sessionId = crypto.randomUUID();
 
    // Store session
    wsManager.rdsSessions.set(sessionId, makeSession(agent_uuid));
 
    // Tell agent to start streaming
    const rdsStartMsg = {
      type: "rds_start",
      sessionId
    };
    console.log(`[RDS] Sending rds_start to agent ${agent_uuid}:`, rdsStartMsg);
    ws.send(JSON.stringify(rdsStartMsg));
 
    console.log(`[RDS] ▶ Session STARTED: ${sessionId} for ${agent_uuid}`);
 
    // Sign viewer token
    const token = jwt.sign(
      { sessionId, agent_uuid },
      process.env.AGENT_SIGN_KEY,
      { expiresIn: "10m" }
    );
 
    return res.json({
      sessionId,
      viewerToken: token,
      viewerUrl: `/api/rds/view/${sessionId}?t=${token}`
    });
  } catch (err) {
    console.error('[RDS] Start error:', err);
    res.status(500).json({ error: 'Failed to start session' });
  }
});
 
/**
 * @api {post} /api/rds/stop/:agent_uuid Stop RDS session
 * @apiName StopRDSSession
 * @apiGroup RDS
 * @apiDescription Stop all remote desktop sessions for specified agent.
 * Sends rds_stop message to agent via WebSocket and removes all sessions from memory.
 * Safe to call even if agent is offline.
 * @apiParam {string} agent_uuid Agent UUID
 * @apiSuccess {boolean} ok=true Sessions stopped successfully
 * @apiError (500) {String} error="Failed to stop session" Internal error
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/rds/stop/abc-123-uuid
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true
 *   }
 */
router.post('/stop/:agent_uuid', (req, res) => {
  try {
    const { agent_uuid } = req.params;
 
    const ws = wsManager.agentConnections.get(agent_uuid);
    if (ws && ws.readyState === 1) {
      const rdsStopMsg = { type: "rds_stop" };
      console.log(`[RDS] Sending rds_stop to agent ${agent_uuid}:`, rdsStopMsg);
      ws.send(JSON.stringify(rdsStopMsg));
    }
 
    // Remove all sessions for this agent
    for (const [id, session] of wsManager.rdsSessions.entries()) {
      if (session.agentId === agent_uuid) {
        wsManager.rdsSessions.delete(id);
        console.log(`[RDS] ⛔ Session STOPPED: ${id} for ${agent_uuid}`);
      }
    }
 
    return res.json({ ok: true });
  } catch (err) {
    console.error('[RDS] Stop error:', err);
    res.status(500).json({ error: 'Failed to stop session' });
  }
});
 
/**
 * @api {get} /api/rds/status/:sessionId Get session status
 * @apiName GetRDSSessionStatus
 * @apiGroup RDS
 * @apiDescription Retrieve current status of remote desktop session.
 * Returns session metadata including activity status and viewer connection state.
 * @apiParam {string} sessionId Session UUID
 * @apiSuccess {string} sessionId Session UUID
 * @apiSuccess {boolean} active Session active flag
 * @apiSuccess {string} agentId Associated agent UUID
 * @apiSuccess {boolean} viewerConnected Whether viewer WebSocket is connected
 * @apiError (404) {String} error="Not found" Session ID not found
 * @apiExample {curl} Example:
 *   curl -X GET http://localhost:3000/api/rds/status/550e8400-e29b-41d4-a716-446655440000
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "sessionId": "550e8400-e29b-41d4-a716-446655440000",
 *     "active": true,
 *     "agentId": "abc-123-uuid",
 *     "viewerConnected": true
 *   }
 */
router.get('/status/:sessionId', (req, res) => {
  const session = wsManager.rdsSessions.get(req.params.sessionId);
  if (!session) return res.status(404).json({ error: 'Not found' });
 
  res.json({
    sessionId: req.params.sessionId,
    active: session.active,
    agentId: session.agentId,
    viewerConnected: !!session.viewer
  });
});
 
/**
 * @api {post} /api/rds/ping/:agent_uuid Ping agent
 * @apiName PingRDSAgent
 * @apiGroup RDS
 * @apiDescription Test agent WebSocket connectivity by sending ping message.
 * Used for debugging and health checks. Requires agent to be online.
 * @apiParam {string} agent_uuid Agent UUID
 * @apiSuccess {boolean} sent=true Ping message sent successfully
 * @apiError (404) {String} error="Agent not connected" Agent not online or WebSocket not ready
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/rds/ping/abc-123-uuid
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "sent": true
 *   }
 */
router.post('/ping/:agent_uuid', (req, res) => {
  const { agent_uuid } = req.params;
  const ws = wsManager.agentConnections.get(agent_uuid);
  if (!ws || ws.readyState !== 1) {
    return res.status(404).json({ error: 'Agent not connected' });
  }
  ws.send(JSON.stringify({ type: "ping", timestamp: Date.now() }));
  res.json({ sent: true });
});
 
module.exports = router;