download-spaces.js

Go to the documentation of this file.

/**
 * @file Agent Installer Download and Distribution Service
 * @description
 * Provides agent installer generation, storage, and distribution endpoints for RMM agent
 * deployment across multiple tenants. Supports both local file serving and DigitalOcean
 * Spaces CDN distribution with automatic installer building, caching, and signed URL generation.
 *
 * Key features:
 * - **Dynamic installer generation**: On-demand EXE build with tenant-specific configuration
 * - **DigitalOcean Spaces integration**: CDN-backed installer storage for global distribution
 * - **Multi-installer types**: Bootstrapper (dynamic/static), full agent, quick batch scripts
 * - **JWT-signed downloads**: Secure installer downloads with embedded tenant authentication
 * - **Build caching**: Reuses existing installers to reduce build time and server load
 * - **Admin management**: Upload, list, and cleanup installer artifacts
 *
 * Installer types:
 * - **Bootstrapper Dynamic**: Small EXE that downloads full agent on target machine
 * - **Bootstrapper Static**: Self-contained EXE with agent binary embedded
 * - **Generic Bootstrapper**: No tenant ID, prompts user during installation
 * - **Quick Install Batch**: Windows batch script with PowerShell download and install
 * - **Bootstrap PowerShell**: PowerShell script for automated deployment
 * - **Dev Agent**: Full agent installer for development testing
 *
 * Storage modes:
 * - **Local**: Installers stored in backend/downloads directory, served directly
 * - **Spaces**: Installers uploaded to DigitalOcean Spaces, accessed via signed URLs
 * - Controlled by `USE_DO_SPACES` environment variable
 *
 * Build workflow:
 * 1. Check if installer exists in Spaces (if enabled) or local cache
 * 2. If exists: Generate signed URL (Spaces) or serve file (local)
 * 3. If not exists: Build installer using Node.js builder scripts
 * 4. Upload to Spaces (if enabled) or cache locally
 * 5. Redirect to signed URL or serve file
 *
 * Security:
 * - JWT tokens signed with AGENT_SIGN_KEY for tenant authentication
 * - Signed URLs expire after 1 hour (configurable)
 * - Path traversal prevention for local file operations
 * - Admin endpoints require authentication
 *
 * Environment variables:
 * - `USE_DO_SPACES`: Enable DigitalOcean Spaces distribution (default: false)
 * - `AGENT_SIGN_KEY`: JWT signing key for agent authentication tokens
 * - `BACKEND_URL`: API base URL embedded in installers
 * - `CLEANUP_AFTER_UPLOAD`: Delete local files after Spaces upload (default: false)
 * @module routes/download-spaces
 * @requires express
 * @requires ../middleware/auth - JWT authentication for admin endpoints
 * @requires ../services/spacesService - DigitalOcean Spaces upload/download client
 * @requires child_process - Execute installer builder scripts
 * @see {@link module:services/spacesService}
 */
 
const express = require('express');
const path = require('path');
const fs = require('fs');
const authenticateToken = require('../middleware/auth');
const router = express.Router();
const { exec, execFileSync } = require('child_process');
const os = require('os');
const spacesService = require('../services/spacesService');
 
// Configuration: Use DO Spaces or local file serving
const USE_SPACES = process.env.USE_DO_SPACES === 'true' || false;
const jwt = require('jsonwebtoken');
const AGENT_SIGN_KEY = process.env.AGENT_SIGN_KEY;
 
/**
 * Helper function to build, cache, and serve agent installers.
 *
 * Implements hybrid storage strategy:
 * - Checks Spaces for existing installer (if USE_SPACES=true)
 * - Falls back to local cache check
 * - Builds installer if not found anywhere
 * - Uploads to Spaces and redirects to signed URL (if USE_SPACES=true)
 * - Serves local file if Spaces disabled
 * @async
 * @private
 * @function buildAndServeInstaller
 * @param {express.Request} req - Express request object
 * @param {express.Response} res - Express response object
 * @param {string} builderScript - Path to Node.js builder script (e.g., './builders/buildBootstrapper.js')
 * @param {string} outputPath - Local filesystem path for built installer (must be in backend/downloads)
 * @param {string} downloadName - Filename for downloaded installer (e.g., 'IBG-Agent-Setup-123.exe')
 * @param {string} tenantId - Tenant identifier for multi-tenant isolation
 * @param {string} installerType - Installer type for storage organization (e.g., 'bootstrapper-dynamic')
 * @returns {Promise<void>} Sends file download or redirects to signed URL
 * @throws {Error} If output path is outside backend/downloads (security check)
 * @throws {Error} If builder script execution fails or times out (4-minute timeout)
 */
 
/**
 * Helper: Build and optionally upload installer
 * @param req
 * @param res
 * @param builderScript
 * @param outputPath
 * @param downloadName
 * @param tenantId
 * @param installerType
 */
async function buildAndServeInstaller(req, res, builderScript, outputPath, downloadName, tenantId, installerType) {
  const downloadsDir = path.resolve(__dirname, '../downloads');
  
  // Security check
  if (!outputPath.startsWith(downloadsDir)) {
    console.error(`[INSTALLER] Output path is not in backend/downloads: ${outputPath}`);
    return res.status(500).json({ error: 'Output path misconfiguration' });
  }
 
  try {
    // Check if already exists in Spaces
    if (USE_SPACES && tenantId) {
      const key = `installers/${tenantId}/${installerType}/${downloadName}`;
      const exists = await spacesService.objectExists(key);
      
      if (exists) {
        console.log(`[INSTALLER] Found existing installer in Spaces: ${key}`);
        const signedUrl = spacesService.getSignedUrl(key, 3600);
        return res.redirect(signedUrl);
      }
    }
 
    // Check if already built locally
    if (fs.existsSync(outputPath)) {
      if (USE_SPACES && tenantId) {
        // Upload to Spaces and redirect
        console.log(`[INSTALLER] Uploading existing local installer to Spaces`);
        const result = await spacesService.uploadInstaller(outputPath, tenantId, installerType);
        return res.redirect(result.signedUrl);
      } else {
        // Serve locally
        console.log(`[INSTALLER] Serving existing local installer: ${outputPath}`);
        return res.download(outputPath, downloadName);
      }
    }
 
    // Build the installer
    console.log(`[INSTALLER] Building ${installerType} for tenant ${tenantId || 'generic'}`);
    execFileSync('node', [builderScript, tenantId, outputPath], {
      stdio: 'inherit',
      timeout: 4 * 60 * 1000,
      maxBuffer: 10 * 1024 * 1024
    });
 
    console.log(`[INSTALLER] Build complete: ${outputPath}`);
 
    // Upload to Spaces or serve locally
    if (USE_SPACES && tenantId) {
      const result = await spacesService.uploadInstaller(outputPath, tenantId, installerType);
      console.log(`[INSTALLER] Uploaded to Spaces, redirecting to signed URL`);
      
      // Optionally cleanup local file after upload
      if (process.env.CLEANUP_AFTER_UPLOAD === 'true') {
        fs.unlinkSync(outputPath);
        console.log(`[INSTALLER] Cleaned up local file: ${outputPath}`);
      }
      
      return res.redirect(result.signedUrl);
    } else {
      return res.download(outputPath, downloadName);
    }
 
  } catch (err) {
    console.error(`[INSTALLER] Build or serve failed: ${err.message}`);
    return res.status(500).json({ error: 'Build or serve failed', details: err.message });
  }
}
 
/**
 * @api {get} /download/bootstrapper-dynamic/:tenantId.exe Download Dynamic Bootstrapper
 * @apiName GetBootstrapperDynamic
 * @apiGroup AgentInstaller
 * @apiDescription
 * Generates or serves tenant-specific dynamic bootstrapper EXE. Dynamic bootstrappers are
 * lightweight executables that download the full agent installer on the target machine,
 * reducing initial download size and enabling always-current agent deployments.
 *
 * Workflow:
 * - Generates JWT token for tenant authentication (30-day expiration)
 * - Builds EXE using build_bootstrapper.js if not cached
 * - Uploads to DigitalOcean Spaces (if USE_DO_SPACES=true)
 * - Serves cached version on subsequent requests
 * @apiPermission public
 * @apiParam {string} tenantId Tenant identifier for bootstrapper customization
 * @apiSuccess (200) {Binary} file Dynamic bootstrapper executable (EXE format)
 * @apiHeader {string} Content-Disposition attachment; filename="bootstrapper_{tenantId}.exe"
 * @apiHeader {string} Content-Type application/octet-stream
 * @apiError (400) {String} error "Missing tenantId"
 * @apiError (500) {String} error "Missing AGENT_SIGN_KEY" (if JWT signing key not configured)
 * @apiError (500) {String} error "Build or serve failed"
 * @apiError (500) {String} details Detailed build error message
 * @apiExample {curl} Example Request:
 *     curl -o installer.exe https://api.ibghub.com/api/download/bootstrapper-dynamic/123.exe
 */
 
// Dynamic bootstrapper EXE generator
router.get('/bootstrapper-dynamic/:tenantId.exe', async (req, res) => {
  const tenantId = req.params.tenantId;
  console.log(`[BOOTSTRAPPER] Incoming request for tenantId: ${tenantId}`);
  
  req.setTimeout(5 * 60 * 1000);
  res.setTimeout(5 * 60 * 1000);
  
  if (!tenantId) {
    console.error('[BOOTSTRAPPER] Missing tenantId');
    return res.status(400).json({ error: 'Missing tenantId' });
  }
  if (!AGENT_SIGN_KEY) {
    console.error('[BOOTSTRAPPER] Missing AGENT_SIGN_KEY');
    return res.status(500).json({ error: 'Missing AGENT_SIGN_KEY' });
  }
 
  const token = jwt.sign({ tenantId }, AGENT_SIGN_KEY, { expiresIn: '30d' });
  console.log(`[BOOTSTRAPPER] Generated JWT for tenantId: ${tenantId}`);
 
  const builderScript = path.resolve(__dirname, '../downloads/build_bootstrapper.js');
  const downloadsDir = path.resolve(__dirname, '../downloads');
  const outputExe = path.join(downloadsDir, `bootstrapper_${tenantId}.exe`);
  const downloadName = `bootstrapper_${tenantId}.exe`;
 
  await buildAndServeInstaller(
    req, res,
    builderScript,
    outputExe,
    downloadName,
    tenantId,
    'bootstrapper'
  );
});
 
/**
 * @api {get} /download/bootstrapper-static/:tenantId.exe Download Static Bootstrapper
 * @apiName GetBootstrapperStatic
 * @apiGroup AgentInstaller
 * @apiDescription
 * Serves pre-built tenant-specific static bootstrapper EXE from cache. Static bootstrappers
 * are self-contained executables with agent binary embedded, suitable for offline deployment
 * or air-gapped environments. Must be pre-built and uploaded by administrators.
 * @apiPermission public
 * @apiParam {string} tenantId Tenant identifier
 * @apiSuccess (200) {Binary} file Static bootstrapper executable
 * @apiError (404) {String} error "Bootstrapper not found" (if not pre-built/uploaded)
 * @apiExample {curl} Example Request:
 *     curl -o installer.exe https://api.ibghub.com/api/download/bootstrapper-static/123.exe
 */
 
// Serve tenant-specific static bootstrapper EXE
router.get('/bootstrapper-static/:tenantId.exe', async (req, res) => {
  const tenantId = req.params.tenantId;
  const downloadName = `bootstrapper_${tenantId}.exe`;
  
  if (USE_SPACES) {
    const key = `installers/${tenantId}/bootstrapper/${downloadName}`;
    const exists = await spacesService.objectExists(key);
    
    if (exists) {
      const signedUrl = spacesService.getSignedUrl(key, 3600);
      return res.redirect(signedUrl);
    }
  }
  
  const filePath = path.resolve(__dirname, `../downloads/${downloadName}`);
  if (!fs.existsSync(filePath)) {
    return res.status(404).json({ error: 'Bootstrapper not found' });
  }
  res.download(filePath, downloadName);
});
 
/**
 * @api {get} /download/bootstrapper.exe Download Generic Bootstrapper
 * @apiName GetBootstrapperGeneric
 * @apiGroup AgentInstaller
 * @apiDescription
 * Serves generic (non-tenant-specific) bootstrapper EXE. User prompted for tenant credentials
 * during installation, similar to Syncro/N-Central/Kaseya deployment model. Useful for
 * partner portals, downloads sections, or scenarios where tenant ID is unknown at download time.
 * @apiPermission public
 * @apiNote No authentication required - suitable for public download pages
 * @apiSuccess (200) {Binary} file Generic bootstrapper executable
 * @apiError (404) {String} error "Bootstrapper not found" (if not built)
 * @apiExample {curl} Example Request:
 *     curl -o installer.exe https://api.ibghub.com/api/download/bootstrapper.exe
 */
 
// Serve static bootstrapper EXE for Syncro-style installer (no auth)
router.get('/bootstrapper.exe', async (req, res) => {
  const downloadName = 'bootstrapper.exe';
  
  if (USE_SPACES) {
    const key = `installers/public/${downloadName}`;
    const exists = await spacesService.objectExists(key);
    
    if (exists) {
      const signedUrl = spacesService.getSignedUrl(key, 3600);
      return res.redirect(signedUrl);
    }
  }
  
  const bootstrapperPath = path.resolve(__dirname, `../downloads/${downloadName}`);
  if (!fs.existsSync(bootstrapperPath)) {
    return res.status(404).json({ error: 'Bootstrapper not found' });
  }
  res.download(bootstrapperPath, downloadName);
});
 
/**
 * @api {get} /download/dev-agent/quick/:tenantId Download Quick Install Batch Script
 * @apiName GetQuickInstallBatch
 * @apiGroup AgentInstaller
 * @apiDescription
 * Generates Windows batch script (.bat) for one-click agent installation. Script creates
 * bootstrap.json with tenant configuration and JWT token, downloads full agent installer
 * via PowerShell Invoke-WebRequest, and runs silent installation. Ideal for email distribution,
 * documentation, or helpdesk guided installations.
 *
 * Generated batch script:
 * - Creates bootstrap.json in %PROGRAMDATA%\EverydayTechAgent with tenantId, JWT, backend URL
 * - Downloads agent installer using PowerShell
 * - Runs Inno Setup installer with /VERYSILENT flag
 * - Displays progress messages and error handling
 * @apiPermission public
 * @apiParam {string} tenantId Tenant identifier for agent registration
 * @apiSuccess (200) {string} script Windows batch script content
 * @apiHeader {string} Content-Type application/octet-stream
 * @apiHeader {string} Content-Disposition attachment; filename="Install_Agent.bat"
 * @apiError (400) {String} error "Missing tenantId"
 * @apiError (500) {String} error "Missing AGENT_SIGN_KEY"
 * @apiError (500) {String} error "Failed to generate installer"
 * @apiExample {curl} Example Request:
 *     curl -o Install_Agent.bat https://api.ibghub.com/api/download/dev-agent/quick/123
 * @apiExample {batch} Generated Script:
 *     @echo off
 *     REM EverydayTech Agent Quick Install
 *     echo { > "%PROGRAMDATA%\EverydayTechAgent\bootstrap.json"
 *     echo   "tenantId": "123", >> "%PROGRAMDATA%\EverydayTechAgent\bootstrap.json"
 *     echo   "jwt": "eyJhbGciOi...", >> "%PROGRAMDATA%\EverydayTechAgent\bootstrap.json"
 *     powershell -Command "Invoke-WebRequest -Uri 'https://api.ibghub.com/api/download/dev-agent' -OutFile '%TEMP%\Agent.exe'"
 *     "%TEMP%\Agent.exe" /VERYSILENT
 */
 
// Quick install - downloads batch script that fetches installer
router.get('/dev-agent/quick/:tenantId', async (req, res) => {
  const tenantId = req.params.tenantId;
  
  if (!tenantId) {
    return res.status(400).json({ error: 'Missing tenantId' });
  }
  
  if (!AGENT_SIGN_KEY) {
    return res.status(500).json({ error: 'Missing AGENT_SIGN_KEY' });
  }
  
  const jwtToken = jwt.sign({ tenantId }, AGENT_SIGN_KEY, { expiresIn: '365d' });
  
  try {
    console.log(`[QUICK-INSTALL] Generating batch installer for tenant: ${tenantId}`);
    
    const backendUrl = process.env.BACKEND_URL || 'https://everydaytech.au/api';
    
    const batchScript = `@echo off
REM EverydayTech Agent Quick Install
REM Generated for tenant: ${tenantId}
 
echo.
echo ========================================
echo  EverydayTech Agent Installer
echo ========================================
echo.
 
REM Create bootstrap.json in agent data directory
echo Creating bootstrap configuration...
set "DATADIR=%PROGRAMDATA%\\EverydayTechAgent"
if not exist "%DATADIR%" mkdir "%DATADIR%"
 
echo { > "%DATADIR%\\bootstrap.json"
echo   "tenantId": "${tenantId}", >> "%DATADIR%\\bootstrap.json"
echo   "jwt": "${jwtToken}", >> "%DATADIR%\\bootstrap.json"
echo   "backend": "${backendUrl}" >> "%DATADIR%\\bootstrap.json"
echo } >> "%DATADIR%\\bootstrap.json"
 
echo Bootstrap configuration created.
echo.
 
echo Downloading installer...
set "INSTALLER=%TEMP%\\EverydayTechAgent_Installer.exe"
 
powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-WebRequest -Uri '${backendUrl}/download/dev-agent' -OutFile '%INSTALLER%' -UseBasicParsing"
 
if not exist "%INSTALLER%" (
    echo.
    echo ERROR: Download failed. Please check your internet connection.
    echo.
    pause
    exit /b 1
)
 
echo.
echo Starting installation...
echo.
 
REM Run Inno Setup installer (will detect bootstrap.json)
"%INSTALLER%" /VERYSILENT /SUPPRESSMSGBOXES /NORESTART
 
echo.
echo Installation complete! The agent will appear in your dashboard shortly.
echo.
pause
exit /b 0
`;
    
    res.setHeader('Content-Type', 'application/octet-stream');
    res.setHeader('Content-Disposition', 'attachment; filename="Install_Agent.bat"');
    res.send(batchScript);
    
  } catch (err) {
    console.error(`[QUICK-INSTALL] Failed to generate installer: ${err.message}`);
    return res.status(500).json({ error: 'Failed to generate installer', details: err.message });
  }
});
 
/**
 * @api {get} /download/dev-agent/bootstrap.ps1 Download Bootstrap PowerShell Script
 * @apiName GetBootstrapPowerShell
 * @apiGroup AgentInstaller
 * @apiDescription
 * Generates PowerShell script (.ps1) for agent deployment via automation tools (RMM scripts,
 * GPO, SCCM, Intune). Legacy endpoint requiring tenant and token as query parameters.
 * Script downloads installer and runs with tenant/token arguments.
 * @apiPermission public
 * @apiQuery {string} tenant Tenant identifier
 * @apiQuery {string} token Authentication token
 * @apiSuccess (200) {string} script PowerShell script content
 * @apiHeader {string} Content-Type application/x-powershell
 * @apiHeader {string} Content-Disposition attachment; filename="agent_bootstrap_{tenant}.ps1"
 * @apiError (400) {String} error "Missing ?tenant="
 * @apiError (400) {String} error "Missing ?token="
 * @apiExample {curl} Example Request:
 *     curl -o bootstrap.ps1 "https://api.ibghub.com/api/download/dev-agent/bootstrap.ps1?tenant=123&token=abc123"
 */
 
// Legacy PowerShell bootstrap script generator
router.get('/dev-agent/bootstrap.ps1', async (req, res) => {
  const { tenant, token } = req.query;
  if (!tenant)
    return res.status(400).json({ error: 'Missing ?tenant=' });
  if (!token)
    return res.status(400).json({ error: 'Missing ?token=' });
 
  const backendUrl = process.env.BACKEND_URL || 'https://everydaytech.au/api';
  const installerUrl = `${backendUrl}/download/dev-agent?tenant=${encodeURIComponent(tenant)}&token=${encodeURIComponent(token)}`;
  
  const script = `
$tenant = "${tenant}"
$token = "${token}"
$installer = "$env:TEMP\\EverydayTechAgent_Installer.exe"
 
Invoke-WebRequest "${installerUrl}" -OutFile $installer
Start-Process $installer -ArgumentList "/tenant=$tenant /token=$token" -Wait
`;
  res.setHeader('Content-Type', 'application/x-powershell');
  res.setHeader('Content-Disposition', `attachment; filename=agent_bootstrap_${tenant}.ps1`);
  res.send(script);
});
 
/**
 * @api {get} /download/dev-agent Download Full Agent Installer
 * @apiName GetFullAgentInstaller
 * @apiGroup AgentInstaller
 * @apiDescription
 * Downloads complete agent installer EXE. This is the full-featured agent installer built
 * with Inno Setup, used by bootstrappers and quick install scripts. Can also be downloaded
 * directly for manual installation or distribution via other channels.
 * @apiPermission public
 * @apiNote Optional query parameters (tenant, token) for legacy compatibility but not enforced
 * @apiQuery {string} [tenant] Legacy tenant identifier (not required)
 * @apiQuery {string} [token] Legacy authentication token (not required)
 * @apiSuccess (200) {Binary} file Full agent installer executable (dev-agent.exe)
 * @apiError (404) {String} error "Installer not built yet. Run: builder/dev/installer/build_installer.sh"
 * @apiExample {curl} Example Request:
 *     curl -o dev-agent.exe https://api.ibghub.com/api/download/dev-agent
 */
 
// Main agent installer download
router.get('/dev-agent', async (req, res) => {
  const { tenant, token } = req.query;
  const downloadName = 'dev-agent.exe';
  
  if (USE_SPACES) {
    const key = `installers/public/agent/${downloadName}`;
    const exists = await spacesService.objectExists(key);
    
    if (exists) {
      const signedUrl = spacesService.getSignedUrl(key, 3600);
      return res.redirect(signedUrl);
    }
  }
  
  const installerPath = path.resolve(__dirname, `../downloads/${downloadName}`);
  
  if (!fs.existsSync(installerPath)) {
    return res.status(404).json({ 
      error: 'Installer not built yet. Run: builder/dev/installer/build_installer.sh' 
    });
  }
  
  res.download(installerPath, downloadName);
});
 
/**
 * @api {post} /download/admin/upload-installer/:installerType Upload Installer to Spaces
 * @apiName UploadInstallerToSpaces
 * @apiGroup AgentInstaller
 * @apiDescription
 * Administrative endpoint to upload locally-built installer to DigitalOcean Spaces CDN.
 * Supports multipart file upload with automatic path organization by tenant and installer type.
 * Used for pre-building static bootstrappers or uploading custom agent builds.
 * @apiPermission admin
 * @apiUse AuthHeader
 * @apiParam {String="bootstrapper","agent","custom"} installerType Type of installer being uploaded
 * @apiBody {string} tenantId Tenant identifier for installer attribution
 * @apiBody {File} file Installer file (EXE) via multipart/form-data
 * @apiSuccess {boolean} success Operation success status (true)
 * @apiSuccess {string} message Success message
 * @apiSuccess {string} key DigitalOcean Spaces object key
 * @apiSuccess {string} signedUrl Time-limited signed URL for installer download
 * @apiError (400) {String} error "No file uploaded"
 * @apiError (400) {String} error "Missing tenantId in request body"
 * @apiError (500) {String} error Upload failure message
 * @apiError (500) {String} details Detailed error description
 * @apiExample {curl} Example Request:
 *     curl -X POST https://api.ibghub.com/api/download/admin/upload-installer/bootstrapper \
 *       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
 *       -F "tenantId=123" \
 *       -F "file=@/path/to/bootstrapper.exe"
 */
 
// Upload installer to Spaces (admin only)
router.post('/admin/upload-installer/:installerType', authenticateToken, async (req, res) => {
  if (!USE_SPACES) {
    return res.status(400).json({ error: 'DO Spaces not enabled' });
  }
 
  const { installerType } = req.params;
  const { fileName, tenantId } = req.body;
  
  if (!fileName) {
    return res.status(400).json({ error: 'Missing fileName' });
  }
 
  const filePath = path.resolve(__dirname, '../downloads', fileName);
  
  if (!fs.existsSync(filePath)) {
    return res.status(404).json({ error: 'File not found' });
  }
 
  try {
    const result = await spacesService.uploadInstaller(
      filePath,
      tenantId || 'public',
      installerType
    );
    
    res.json({
      success: true,
      key: result.key,
      signedUrl: result.signedUrl,
      fileName: result.fileName
    });
  } catch (error) {
    console.error('[UPLOAD] Failed:', error.message);
    res.status(500).json({ error: 'Upload failed', details: error.message });
  }
});
 
/**
 * @api {get} /download/admin/list-installers/:tenantId? List Installers in Spaces
 * @apiName ListInstallersInSpaces
 * @apiGroup AgentInstaller
 * @apiDescription
 * Administrative endpoint to list all installers stored in DigitalOcean Spaces. Optionally
 * filter by tenant ID. Returns metadata including file keys, sizes, last modified timestamps,
 * and signed download URLs. Useful for audit trails, inventory management, and cleanup planning.
 * @apiPermission admin
 * @apiUse AuthHeader
 * @apiParam {string} [tenantId] Optional tenant ID to filter installers
 * @apiSuccess {object[]} installers Array of installer objects from Spaces
 * @apiSuccess {string} installers.key Object storage key (e.g., "installers/123/bootstrapper/file.exe")
 * @apiSuccess {number} installers.size File size in bytes
 * @apiSuccess {string} installers.lastModified ISO timestamp of last modification
 * @apiSuccess {string} installers.signedUrl Time-limited download URL (1-hour expiration)
 * @apiError (400) {String} error "DO Spaces not enabled" (if USE_DO_SPACES=false)
 * @apiError (500) {String} error "List failed"
 * @apiError (500) {String} details Detailed error from Spaces API
 * @apiExample {curl} Example Request (all installers):
 *     curl -X GET https://api.ibghub.com/api/download/admin/list-installers \
 *       -H "Authorization: Bearer YOUR_JWT_TOKEN"
 * @apiExample {curl} Example Request (tenant-specific):
 *     curl -X GET https://api.ibghub.com/api/download/admin/list-installers/123 \
 *       -H "Authorization: Bearer YOUR_JWT_TOKEN"
 */
 
// List installers in Spaces (admin only)
router.get('/admin/list-installers/:tenantId?', authenticateToken, async (req, res) => {
  if (!USE_SPACES) {
    return res.status(400).json({ error: 'DO Spaces not enabled' });
  }
 
  const { tenantId } = req.params;
  const prefix = tenantId ? `installers/${tenantId}/` : 'installers/';
 
  try {
    const objects = await spacesService.listObjects(prefix);
    const installers = objects.map(obj => ({
      key: obj.Key,
      size: obj.Size,
      lastModified: obj.LastModified,
      signedUrl: spacesService.getSignedUrl(obj.Key, 3600)
    }));
    
    res.json({ installers });
  } catch (error) {
    console.error('[LIST] Failed:', error.message);
    res.status(500).json({ error: 'List failed', details: error.message });
  }
});
 
/**
 * @api {post} /download/admin/cleanup-installers/:tenantId Cleanup Old Installers
 * @apiName CleanupOldInstallers
 * @apiGroup AgentInstaller
 * @apiDescription
 * Administrative endpoint to delete old installer versions from DigitalOcean Spaces to
 * free storage and reduce costs. Keeps most recent N versions (default: 5) and deletes
 * older installers for specified tenant. Use with caution as operation is irreversible.
 * @apiPermission admin
 * @apiUse AuthHeader
 * @apiParam {string} tenantId Tenant identifier for cleanup scope
 * @apiBody {number} [keepRecent=5] Number of recent installer versions to retain
 * @apiSuccess {boolean} success Operation success status (true)
 * @apiSuccess {string} message Success message with tenant ID
 * @apiError (400) {String} error "DO Spaces not enabled" (if USE_DO_SPACES=false)
 * @apiError (500) {String} error "Cleanup failed"
 * @apiError (500) {String} details Detailed error from Spaces API
 * @apiExample {curl} Example Request (keep 5 recent):
 *     curl -X POST https://api.ibghub.com/api/download/admin/cleanup-installers/123 \
 *       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
 *       -H "Content-Type: application/json" \
 *       -d '{"keepRecent": 5}'
 * @apiExample {json} Example Response:
 *     {
 *       "success": true,
 *       "message": "Cleaned up old installers for 123"
 *     }
 */
 
// Cleanup old installers (admin only)
router.post('/admin/cleanup-installers/:tenantId', authenticateToken, async (req, res) => {
  if (!USE_SPACES) {
    return res.status(400).json({ error: 'DO Spaces not enabled' });
  }
 
  const { tenantId } = req.params;
  const { keepRecent } = req.body;
 
  try {
    await spacesService.cleanupOldInstallers(tenantId, keepRecent || 5);
    res.json({ success: true, message: `Cleaned up old installers for ${tenantId}` });
  } catch (error) {
    console.error('[CLEANUP] Failed:', error.message);
    res.status(500).json({ error: 'Cleanup failed', details: error.message });
  }
});
 
module.exports = router;