agentManifest.js

Go to the documentation of this file.

/**
 * @file agentManifest.js
 * @module routes/agentManifest
 * @description Agent distribution manifest and file download endpoints for auto-updates.
 * Generates SHA-256 file manifests for agent version distribution and serves downloadable files.
 * Supports plugin auto-sync and agent executable updates.
 * @requires express
 * @requires fs
 * @requires path
 * @requires crypto
 * @author RMM-PSA Development Team
 * @copyright 2026 RMM-PSA Platform
 * @license Proprietary
 */
 
/**
 * @apiDefine AgentManifest Agent Distribution
 * Agent version manifest and file downloads for auto-updates
 */
 
const express = require('express');
const router = express.Router();
const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
 
const DIST_PATH = '/opt/apps/IBG_HUB_dist/agent';
 
/**
 * @api {get} /api/agent/manifest Get agent file manifest
 * @apiName GetAgentManifest
 * @apiGroup AgentManifest
 * @apiDescription Retrieve file manifest for latest agent version. Returns SHA-256 hashes,
 * file sizes, and modification times for all files in agent distribution (plugins, executables).
 * Used by agents to detect changes and sync files. Manifest is cached and regenerated on demand.
 * @apiSuccess {string} version Latest agent version (e.g., "1.0.5")
 * @apiSuccess {DateTime} generated Manifest generation timestamp
 * @apiSuccess {object} files File manifest dictionary (path → metadata)
 * @apiSuccess {string} files.path File relative path (key)
 * @apiSuccess {object} files.metadata File metadata (value)
 * @apiSuccess {string} files.metadata.hash SHA-256 hash of file content
 * @apiSuccess {number} files.metadata.size File size in bytes
 * @apiSuccess {DateTime} files.metadata.modified Last modified timestamp
 * @apiError (404) {String} error="No version available" latest_version.txt not found
 * @apiError (404) {String} error="Version directory not found" Version folder missing
 * @apiError (500) {String} error Error message from manifest generation
 * @apiExample {curl} Example:
 *   curl -X GET http://localhost:3000/api/agent/manifest
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "version": "1.0.5",
 *     "generated": "2026-03-12T10:00:00.000Z",
 *     "files": {
 *       "agent.exe": {
 *         "hash": "a3f2c1b...",
 *         "size": 8388608,
 *         "modified": "2026-03-10T08:00:00.000Z"
 *       },
 *       "plugins/rustdesk.js": {
 *         "hash": "b4e3d2c...",
 *         "size": 2048,
 *         "modified": "2026-03-11T12:30:00.000Z"
 *       }
 *     }
 *   }
 */
router.get('/manifest', async (req, res) => {
  try {
    console.log('[Manifest] GET /api/agent/manifest called');
    // Get latest version
    const versionFile = path.join(DIST_PATH, 'latest_version.txt');
    if (!fs.existsSync(versionFile)) {
      console.error('[Manifest] latest_version.txt not found');
      return res.status(404).json({ error: 'No version available' });
    }
    
    const version = fs.readFileSync(versionFile, 'utf8').trim();
    const versionDir = path.join(DIST_PATH, version);
    
    if (!fs.existsSync(versionDir)) {
      return res.status(404).json({ error: 'Version directory not found' });
    }
    
    // Check for cached manifest
    const manifestPath = path.join(versionDir, 'file-manifest.json');
    if (fs.existsSync(manifestPath)) {
      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
      return res.json(manifest);
    }
    
    // Generate manifest on the fly if not cached
    console.log('[Manifest] Generating manifest for version:', version);
    const manifest = await generateManifest(versionDir, version);
    
    // Cache it
    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
    
    res.json(manifest);
  } catch (err) {
    console.error('[Manifest] Error:', err);
    res.status(500).json({ error: err.message });
  }
});
 
/**
 * @api {get} /api/agent/file Download agent file
 * @apiName DownloadAgentFile
 * @apiGroup AgentManifest
 * @apiDescription Download specific file from agent distribution directory.
 * File path provided via query parameter. Includes directory traversal protection
 * and real path validation to prevent unauthorized file access. Used by agents
 * to download updated plugins and executables during auto-update process.
 * @apiParam {string} path Relative file path (query parameter, e.g., "plugins/rustdesk.js")
 * @apiSuccess {File} file Binary file download with attachment disposition
 * @apiError (400) {String} error="Invalid file path" Path contains ".." or starts with "/"
 * @apiError (404) {String} error="No version available" latest_version.txt not found
 * @apiError (404) {String} error="File not found" Requested file does not exist
 * @apiError (403) {String} error="Access denied" File path outside version directory (security)
 * @apiError (500) {String} error Error message from file system operations
 * @apiExample {curl} Example:
 *   curl -X GET "http://localhost:3000/api/agent/file?path=plugins/rustdesk.js" \\
 *     -o rustdesk.js
 * @apiSuccessExample {binary} Success-Response:
 *   HTTP/1.1 200 OK
 *   Content-Type: application/javascript
 *   Content-Disposition: attachment; filename="rustdesk.js"
 *   
 *   [binary file content]
 */
router.get('/file', async (req, res) => {
  try {
    // Get path from query parameter
    const relativePath = decodeURIComponent(req.query.path || '');
    
    // Security: prevent directory traversal
    if (relativePath.includes('..') || relativePath.startsWith('/')) {
      return res.status(400).json({ error: 'Invalid file path' });
    }
    
    // Get latest version
    const versionFile = path.join(DIST_PATH, 'latest_version.txt');
    if (!fs.existsSync(versionFile)) {
      return res.status(404).json({ error: 'No version available' });
    }
    
    const version = fs.readFileSync(versionFile, 'utf8').trim();
    const filePath = path.join(DIST_PATH, version, relativePath);
    
    if (!fs.existsSync(filePath)) {
      return res.status(404).json({ error: 'File not found' });
    }
    
    // Security: ensure file is within version directory
    const realPath = fs.realpathSync(filePath);
    const realVersionDir = fs.realpathSync(path.join(DIST_PATH, version));
    if (!realPath.startsWith(realVersionDir)) {
      return res.status(403).json({ error: 'Access denied' });
    }
    
    // Send file
    const filename = path.basename(filePath);
    res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
    res.sendFile(realPath);
  } catch (err) {
    console.error('[Manifest] File download error:', err);
    res.status(500).json({ error: err.message });
  }
});
 
/**
 * Generate manifest by scanning directory
 * @param versionDir
 * @param version
 */
async function generateManifest(versionDir, version) {
  const manifest = {
    version: version,
    generated: new Date().toISOString(),
    files: {}
  };
  
  // Files/directories to include in manifest
  const includePaths = [
    'plugins',  // All plugin files
    // Add other directories as needed
  ];
  
  // Include specific files
  const includeFiles = [
    'EverydayTechTray.exe',  // Tray icon executable
    'agent.exe'              // Main agent executable
  ];
  
  for (const includePath of includePaths) {
    const fullPath = path.join(versionDir, includePath);
    if (fs.existsSync(fullPath)) {
      scanDirectory(fullPath, versionDir, manifest.files);
    }
  }
  
  // Add specific files to manifest
  for (const includeFile of includeFiles) {
    const fullPath = path.join(versionDir, includeFile);
    if (fs.existsSync(fullPath)) {
      const stats = fs.statSync(fullPath);
      const hash = getFileHash(fullPath);
      
      manifest.files[includeFile] = {
        hash: hash,
        size: stats.size,
        modified: stats.mtime.toISOString()
      };
    }
  }
  
  return manifest;
}
 
/**
 * Recursively scan directory and add files to manifest
 * @param dirPath
 * @param basePath
 * @param files
 */
function scanDirectory(dirPath, basePath, files) {
  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
  
  for (const entry of entries) {
    const fullPath = path.join(dirPath, entry.name);
    
    if (entry.isDirectory()) {
      scanDirectory(fullPath, basePath, files);
    } else if (entry.isFile()) {
      const relativePath = path.relative(basePath, fullPath).replace(/\\/g, '/');
      const stats = fs.statSync(fullPath);
      const hash = getFileHash(fullPath);
      
      files[relativePath] = {
        hash: hash,
        size: stats.size,
        modified: stats.mtime.toISOString()
      };
    }
  }
}
 
/**
 * Calculate SHA-256 hash of file
 * @param filePath
 */
function getFileHash(filePath) {
  const hash = crypto.createHash('sha256');
  const data = fs.readFileSync(filePath);
  hash.update(data);
  return hash.digest('hex');
}
 
module.exports = router;