agentFiles.js

Go to the documentation of this file.

/**
 * @file agentFiles.js
 * @module routes/agentFiles
 * @description Remote file management endpoints for RMM agents via WebSocket communication.
 * Provides file browser, upload, and download capabilities for remote device file systems.
 * @requires express
 * @requires middleware/auth
 * @requires services/websocketManager
 * @author RMM-PSA Development Team
 * @copyright 2026 RMM-PSA Platform
 * @license Proprietary
 */
 
/**
 * @apiDefine AgentFiles Agent File Management
 * Remote file system operations via RMM agents
 */
 
const express = require('express');
const router = express.Router();
const authenticateToken = require('../middleware/auth');
const wsManager = require('../services/websocketManager');
 
/**
 * @api {get} /api/agent/:agentId/files List agent files
 * @apiName ListAgentFiles
 * @apiGroup AgentFiles
 * @apiDescription Retrieve directory listing from remote agent file system via WebSocket.
 * Returns list of files and folders at specified path. Requires authentication.
 * @apiParam {string} agentId Agent ID or UUID
 * @apiParam {string} [path=/] Directory path to list (query parameter, default: root)
 * @apiSuccess {object[]} files Array of file/folder objects
 * @apiSuccess {string} files.name File or folder name
 * @apiSuccess {string} files.type Type: "file" or "directory"
 * @apiSuccess {number} files.size File size in bytes (files only)
 * @apiSuccess {DateTime} files.modified Last modified timestamp
 * @apiError (500) {String} error Error message from WebSocket communication
 * @apiExample {curl} Example:
 *   curl -X GET "http://localhost:3000/api/agent/123/files?path=/var/log" \\
 *     -H "Authorization: Bearer YOUR_TOKEN"
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "files": [
 *       {
 *         "name": "syslog",
 *         "type": "file",
 *         "size": 1048576,
 *         "modified": "2026-03-12T10:00:00.000Z"
 *       },
 *       {
 *         "name": "nginx",
 *         "type": "directory",
 *         "modified": "2026-03-10T08:30:00.000Z"
 *       }
 *     ]
 *   }
 */
router.get('/:agentId/files', authenticateToken, async (req, res) => {
  const { agentId } = req.params;
  const { path = '/' } = req.query;
  try {
    const files = await wsManager.requestAgentFileList(agentId, path);
    res.json({ files });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});
 
/**
 * @api {post} /api/agent/:agentId/files Upload file to agent
 * @apiName UploadAgentFile
 * @apiGroup AgentFiles
 * @apiDescription Upload file to remote agent file system via WebSocket.
 * TODO: Implementation pending - will forward uploaded file data to agent.
 * @apiParam {string} agentId Agent ID or UUID
 * @apiParam {File} file File to upload (multipart/form-data)
 * @apiParam {string} [path=/] Destination directory path
 * @apiSuccess {boolean} success=true Upload initiated successfully
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/agent/123/files \\
 *     -H "Authorization: Bearer YOUR_TOKEN" \\
 *     -F "file=@/local/path/script.ps1" \\
 *     -F "path=/opt/scripts"
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true
 *   }
 */
router.post('/:agentId/files', authenticateToken, async (req, res) => {
  const { agentId } = req.params;
  // TODO: Handle file upload, forward to agent
  res.json({ success: true });
});
 
/**
 * @api {get} /api/agent/:agentId/files/download Download file from agent
 * @apiName DownloadAgentFile
 * @apiGroup AgentFiles
 * @apiDescription Download file from remote agent file system via WebSocket stream.
 * TODO: Implementation pending - will stream file from agent to client.
 * @apiParam {string} agentId Agent ID or UUID
 * @apiParam {string} filePath Full path to file on agent (query parameter)
 * @apiSuccess {File} file Binary file stream
 * @apiExample {curl} Example:
 *   curl -X GET "http://localhost:3000/api/agent/123/files/download?filePath=/var/log/syslog" \\
 *     -H "Authorization: Bearer YOUR_TOKEN" \\
 *     -o syslog.txt
 * @apiSuccessExample {binary} Success-Response:
 *   HTTP/1.1 200 OK
 *   Content-Type: application/octet-stream
 *   Content-Disposition: attachment; filename="syslog"
 *   
 *   [binary file content]
 */
router.get('/:agentId/files/download', authenticateToken, async (req, res) => {
  const { agentId } = req.params;
  const { filePath } = req.query;
  // TODO: Stream file from agent
  res.download('/tmp/example.txt'); // Placeholder
});
 
module.exports = router;