tenant-meshcentral-sync.js

Go to the documentation of this file.

/**
 * @file Tenant MeshCentral Device Group Auto-Sync Service
 * @description
 * Provides automated synchronization of tenant data with MeshCentral device groups (meshes).
 * Ensures every tenant has a corresponding device group in MeshCentral for agent organization,
 * handles group creation/linking, and maintains persistent associations across MeshCentral
 * server restarts or database migrations.
 *
 * Key features:
 * - **Auto-group creation**: Creates "{Tenant Name} Devices" groups in MeshCentral
 * - **Intelligent matching**: Links existing groups by ID or name to prevent duplicates
 * - **Bulk synchronization**: Sync all tenants at once (/sync-all endpoint)
 * - **Individual tenant sync**: Ensure specific tenant has group (/ensure/:tenantId)
 * - **Status reporting**: Check sync status and identify missing groups (/status)
 * - **Startup integration**: Can run automatically on server startup
 *
 * Synchronization logic:
 * 1. Query all tenants from database
 * 2. Fetch all existing device groups (meshes) from MeshCentral
 * 3. For each tenant:
 *    a. If tenant has `meshcentral_group_id`, verify group still exists
 *    b. If group missing, search for match by name (exact then partial)
 *    c. If match found, link to tenant (update database)
 *    d. If no match, create new group in MeshCentral
 *    e. Update tenant record with group ID and `meshcentral_setup_complete=true`
 *
 * Name matching strategy (strict to prevent duplicates):
 * - **Exact match**: "{Tenant Name} Devices"
 * - **Fallback exact**: "{Tenant Name}"
 * - **Partial match**: Contains tenant name AND "Devices"
 *
 * Use cases:
 * - Initial platform setup (create groups for all tenants)
 * - MeshCentral server migration (re-link to new server)
 * - Manual group cleanup recovery
 * - Automated startup sync on server restart
 * - New tenant onboarding
 *
 * Security:
 * - All endpoints require authentication (`authenticateToken` middleware)
 * - Root tenant credentials required for MeshCentral API access
 * - Environment variables store admin credentials
 *
 * Environment variables:
 * - `MESHCENTRAL_URL`: MeshCentral server URL (default: Dev App Platform URL)
 * - `MESHCENTRAL_ADMIN_USER`: Admin username (default: 'admin')
 * - `MESHCENTRAL_ADMIN_PASS`: Admin password (default: 'admin')
 * @module routes/tenant-meshcentral-sync
 * @requires express
 * @requires ../db - PostgreSQL database connection
 * @requires ../lib/meshcentral-api - MeshCentral API client library
 * @requires ../middleware/auth - JWT authentication middleware
 * @see {@link module:lib/meshcentral-api}
 */
 
/**
 * Tenant MeshCentral Auto-Sync
 * Ensures all tenants have device groups in MeshCentral
 * 
 * This route handles:
 * - Auto-creation of device groups for tenants without them
 * - Syncing tenant names with MeshCentral group names
 * - Ensuring persistent device groups across MeshCentral restarts
 */
 
const express = require('express');
const router = express.Router();
const db = require('../db');
const MeshCentralAPI = require('../lib/meshcentral-api');
const authenticateToken = require('../middleware/auth');
 
const MESHCENTRAL_URL = process.env.MESHCENTRAL_URL || 'https://rmm-psa-meshcentral-aq48h.ondigitalocean.app';
const MESHCENTRAL_USER = process.env.MESHCENTRAL_ADMIN_USER || 'admin';
const MESHCENTRAL_PASSWORD = process.env.MESHCENTRAL_ADMIN_PASS || 'admin';
 
/**
 * Creates and authenticates MeshCentral API client instance.
 *
 * Initializes MeshCentralAPI with root admin credentials from environment variables.
 * Performs login to obtain authentication cookies/tokens. Returns authenticated API
 * instance ready for device group operations (create, list, delete, etc.).
 * @async
 * @private
 * @function getMeshAPI
 * @returns {Promise<MeshCentralAPI>} Authenticated MeshCentral API client instance
 * @throws {Error} If MeshCentral server unreachable or authentication fails
 * @example
 * const api = await getMeshAPI();
 * const meshes = await api.getMeshes();
 */
 
/**
 * Get or create MeshCentral API instance
 */
async function getMeshAPI() {
  const api = new MeshCentralAPI({
    url: MESHCENTRAL_URL,
    username: MESHCENTRAL_USER,
    password: MESHCENTRAL_PASSWORD
  });
  
  await api.login();
  return api;
}
 
/**
 * Ensures tenant has associated device group (mesh) in MeshCentral.
 *
 * Implements intelligent group matching and creation logic to prevent duplicates:
 * 1. If tenant has `meshcentral_group_id`, verifies group still exists in MeshCentral
 * 2. If group missing, searches existing groups by name (exact then partial match)
 * 3. If match found, links group to tenant (updates database)
 * 4. If no match, creates new group "{Tenant Name} Devices" in MeshCentral
 * 5. Updates tenant record with group ID and sets `meshcentral_setup_complete=true`
 *
 * Name matching precedence:
 * - **Exact match**: "{tenant.name} Devices"
 * - **Exact fallback**: "{tenant.name}"
 * - **Partial match**: Contains tenant.name AND "Devices"
 * @async
 * @private
 * @function ensureTenantMesh
 * @param {MeshCentralAPI} api - Authenticated MeshCentral API client
 * @param {object} tenant - Tenant database record
 * @param {number} tenant.tenant_id - Unique tenant identifier
 * @param {string} tenant.name - Tenant name (used for group naming)
 * @param {string} [tenant.meshcentral_group_id] - Existing MeshCentral group ID (if previously synced)
 * @param {object[]} [existingMeshes=null] - Cached array of existing MeshCentral groups (performance optimization)
 * @returns {Promise<object>} Sync result
 * @returns {string} return.meshId - MeshCentral group ID (existing or newly created)
 * @returns {boolean} return.created - True if new group was created in this call
 * @returns {boolean} return.linked - True if existing group was linked to tenant in this call
 * @throws {Error} If MeshCentral API calls fail or database updates fail
 * @example
 * const api = await getMeshAPI();
 * const meshes = await api.getMeshes();
 * const result = await ensureTenantMesh(api, { tenant_id: 5, name: 'ACME Corp' }, meshes);
 * // result: { meshId: 'mesh/domain/abc123', created: true, linked: false }
 */
 
/**
 * Ensure tenant has a device group in MeshCentral
 * Matches existing groups by ID or name, creates new ones if needed
 * @param api
 * @param tenant
 * @param existingMeshes
 */
async function ensureTenantMesh(api, tenant, existingMeshes = null) {
  try {
    const expectedMeshName = `${tenant.name} Devices`;
    
    // Fetch meshes if not provided
    if (!existingMeshes) {
      existingMeshes = await api.getMeshes();
    }
    
    // Check if tenant already has a mesh ID
    if (tenant.meshcentral_group_id) {
      // Verify it still exists in MeshCentral
      const meshExists = existingMeshes.some(m => m._id === tenant.meshcentral_group_id);
      
      if (meshExists) {
        console.log(`✅ [TenantSync] Tenant ${tenant.tenant_id} has mesh: ${tenant.meshcentral_group_id}`);
        return { meshId: tenant.meshcentral_group_id, created: false, linked: false };
      } else {
        console.log(`⚠️  [TenantSync] Tenant ${tenant.tenant_id} mesh not found, searching for match...`);
      }
    }
    
    // Try to find existing mesh by name (strict matching to prevent duplicates)
    // First try exact match with expected name, then exact match with tenant name
    let matchingMesh = existingMeshes.find(m => (m.name || '') === expectedMeshName);
    if (!matchingMesh) {
      matchingMesh = existingMeshes.find(m => (m.name || '') === tenant.name);
    }
    // Only fall back to partial match if no exact matches found
    if (!matchingMesh) {
      matchingMesh = existingMeshes.find(m => (m.name || '').includes(tenant.name) && (m.name || '').includes('Devices'));
    }
    
    if (matchingMesh) {
      console.log(`🔗 [TenantSync] Found existing mesh "${matchingMesh.name}" - linking to tenant ${tenant.tenant_id}`);
      
      // Link this mesh to the tenant
      await db.query(
        'UPDATE tenants SET meshcentral_group_id = $1, meshcentral_setup_complete = true WHERE tenant_id = $2',
        [matchingMesh._id, tenant.tenant_id]
      );
      
      console.log(`✅ [TenantSync] Linked mesh ${matchingMesh._id} to tenant ${tenant.tenant_id}`);
      return { meshId: matchingMesh._id, created: false, linked: true };
    }
    
    // Create new mesh
    console.log(`📦 [TenantSync] Creating mesh for tenant ${tenant.tenant_id}: ${expectedMeshName}`);
    
    const result = await api.createMesh(expectedMeshName, `Device group for ${tenant.name} (tenant:${tenant.tenant_id})`);
    
    if (!result || !result.meshId) {
      throw new Error('Failed to create mesh in MeshCentral');
    }
    
    // Store mesh ID in database
    await db.query(
      'UPDATE tenants SET meshcentral_group_id = $1, meshcentral_setup_complete = true WHERE tenant_id = $2',
      [result.meshId, tenant.tenant_id]
    );
    
    console.log(`✅ [TenantSync] Created and linked mesh ${result.meshId} for tenant ${tenant.tenant_id}`);
    
    return { meshId: result.meshId, created: true, linked: false };
    
  } catch (error) {
    console.error(`❌ [TenantSync] Error ensuring mesh for tenant ${tenant.tenant_id}:`, error.message);
    throw error;
  }
}
 
/**
 * @api {post} /tenant-meshcentral-sync/sync-all Sync All Tenants with MeshCentral
 * @apiName SyncAllTenantsMeshCentral
 * @apiGroup TenantSync
 * @apiDescription
 * Performs bulk synchronization of all tenants with MeshCentral device groups. Creates
 * missing groups, links existing groups by name matching, and updates database records.
 * Useful for initial setup, MeshCentral server migrations, or manual cleanup after data loss.
 *
 * Operation workflow:
 * 1. Authenticate with MeshCentral as root admin
 * 2. Fetch all tenants from database
 * 3. Fetch all existing device groups from MeshCentral
 * 4. For each tenant: call ensureTenantMesh() to create/link group
 * 5. Return detailed results for each tenant
 * @apiPermission authenticated
 * @apiUse AuthHeader
 * @apiSuccess {number} totalTenants Total number of tenants processed
 * @apiSuccess {number} synced Number of tenants successfully synced
 * @apiSuccess {number} created Number of new device groups created
 * @apiSuccess {number} linked Number of existing groups linked
 * @apiSuccess {object[]} results Detailed results for each tenant
 * @apiSuccess {number} results.tenantId Tenant ID
 * @apiSuccess {string} results.name Tenant name
 * @apiSuccess {string} results.meshId MeshCentral group ID
 * @apiSuccess {boolean} results.created True if group was newly created
 * @apiSuccess {boolean} results.linked True if existing group was linked
 * @apiSuccess {string} [results.error] Error message if sync failed for this tenant
 * @apiError (500) {String} error "Sync failed"
 * @apiError (500) {String} details Detailed error message
 * @apiExample {curl} Example Request:
 *     curl -X POST https://api.ibghub.com/api/tenant-meshcentral-sync/sync-all \\
 *       -H "Authorization: Bearer YOUR_JWT_TOKEN"
 * @apiExample {json} Example Response:
 *     {
 *       "totalTenants": 10,
 *       "synced": 10,
 *       "created": 3,
 *       "linked": 2,
 *       "results": [
 *         {"tenantId": 1, "name": "ACME Corp", "meshId": "mesh/domain/abc", "created": true, "linked": false},
 *         {"tenantId": 2, "name": "Tech Inc", "meshId": "mesh/domain/def", "created": false, "linked": true}
 *       ]
 *     }
 */
 
/**
 * Sync all tenants with MeshCentral
 * POST /api/tenant-meshcentral-sync/sync-all
 */
router.post('/sync-all', authenticateToken, async (req, res) => {
  try {
    console.log('\n🔄 [TenantSync] Starting full tenant-mesh sync...');
    
    // Get all tenants
    const tenantsResult = await db.query(
      'SELECT tenant_id, name, meshcentral_group_id, meshcentral_setup_complete FROM tenants ORDER BY created_at'
    );
    
    if (tenantsResult.rows.length === 0) {
      return res.json({
        success: true,
        message: 'No tenants to sync',
        processed: 0
      });
    }
    
    console.log(`📊 [TenantSync] Found ${tenantsResult.rows.length} tenants`);
    
    // Connect to MeshCentral
    const api = await getMeshAPI();
    
    // Fetch all existing meshes once
    console.log('📦 [TenantSync] Fetching existing mesh groups...');
    const existingMeshes = await api.getMeshes();
    console.log(`✅ [TenantSync] Found ${existingMeshes.length} existing mesh group(s)`);
    
    // Process each tenant
    const results = [];
    for (const tenant of tenantsResult.rows) {
      try {
        const result = await ensureTenantMesh(api, tenant, existingMeshes);
        results.push({
          tenantId: tenant.tenant_id,
          tenantName: tenant.name,
          meshId: result.meshId,
          created: result.created,
          linked: result.linked,
          success: true
        });
      } catch (error) {
        results.push({
          tenantId: tenant.tenant_id,
          tenantName: tenant.name,
          success: false,
          error: error.message
        });
      }
    }
    
    const created = results.filter(r => r.created).length;
    const linked = results.filter(r => r.linked).length;
    const existing = results.filter(r => r.success && !r.created && !r.linked).length;
    const failed = results.filter(r => !r.success).length;
    
    console.log(`\n✅ [TenantSync] Sync complete: ${created} created, ${linked} linked, ${existing} existing, ${failed} failed`);
    
    res.json({
      success: true,
      message: `Synced ${tenantsResult.rows.length} tenants`,
      created,
      linked,
      existing,
      failed,
      results
    });
    
  } catch (error) {
    console.error('❌ [TenantSync] Error during sync:', error);
    res.status(500).json({
      success: false,
      error: 'Failed to sync tenants with MeshCentral',
      details: error.message
    });
  }
});
 
/**
 * @api {post} /tenant-meshcentral-sync/ensure/:tenantId Ensure Tenant Device Group Exists
 * @apiName EnsureTenantMeshCentral
 * @apiGroup TenantSync
 * @apiDescription
 * Ensures a specific tenant has a device group in MeshCentral. Creates group if missing,
 * links if existing group found by name. Used during tenant onboarding or to manually
 * fix sync issues for individual tenants.
 * @apiPermission authenticated
 * @apiUse AuthHeader
 * @apiParam {number} tenantId Tenant ID to sync
 * @apiSuccess {boolean} success Operation success status (true)
 * @apiSuccess {string} meshId MeshCentral device group ID
 * @apiSuccess {boolean} created True if new group was created
 * @apiSuccess {boolean} linked True if existing group was linked
 * @apiSuccess {string} message Success message with operation details
 * @apiError (404) {String} error "Tenant not found"
 * @apiError (500) {String} error "Sync failed"
 * @apiError (500) {String} details Detailed error message
 * @apiExample {curl} Example Request:
 *     curl -X POST https://api.ibghub.com/api/tenant-meshcentral-sync/ensure/5 \
 *       -H "Authorization: Bearer YOUR_JWT_TOKEN"
 * @apiExample {json} Example Response:
 *     {
 *       "success": true,
 *       "meshId": "mesh/domain/abc123",
 *       "created": true,
 *       "linked": false,
 *       "message": "Created new mesh for tenant 5"
 *     }
 */
 
/**
 * Ensure single tenant has a mesh
 * POST /api/tenant-meshcentral-sync/ensure/:tenantId
 */
router.post('/ensure/:tenantId', authenticateToken, async (req, res) => {
  try {
    const { tenantId } = req.params;
    
    console.log(`\n🔄 [TenantSync] Ensuring mesh for tenant ${tenantId}...`);
    
    // Get tenant
    const tenantResult = await db.query(
      'SELECT tenant_id, name, meshcentral_group_id, meshcentral_setup_complete FROM tenants WHERE tenant_id = $1',
      [tenantId]
    );
    
    if (tenantResult.rows.length === 0) {
      return res.status(404).json({
        success: false,
        error: 'Tenant not found'
      });
    }
    
    const tenant = tenantResult.rows[0];
    
    // Connect to MeshCentral and ensure mesh exists
    const api = await getMeshAPI();
    const result = await ensureTenantMesh(api, tenant);
    
    res.json({
      success: true,
      tenantId: tenant.tenant_id,
      tenantName: tenant.name,
      meshId: result.meshId,
      created: result.created
    });
    
  } catch (error) {
    console.error('❌ [TenantSync] Error ensuring mesh:', error);
    res.status(500).json({
      success: false,
      error: 'Failed to ensure mesh for tenant',
      details: error.message
    });
  }
});
 
/**
 * @api {get} /tenant-meshcentral-sync/status Get Tenant Sync Status
 * @apiName GetTenantSyncStatus
 * @apiGroup TenantSync
 * @apiDescription
 * Returns synchronization status for all tenants, identifying which tenants have device
 * groups configured and which need sync. Useful for monitoring dashboards and diagnosing
 * sync issues before running bulk operations.
 * @apiPermission authenticated
 * @apiUse AuthHeader
 * @apiSuccess {number} totalTenants Total number of tenants in database
 * @apiSuccess {number} synced Number of tenants with `meshcentral_setup_complete=true`
 * @apiSuccess {number} unsynced Number of tenants without device groups
 * @apiSuccess {object[]} unsyncedTenants List of tenants needing sync
 * @apiSuccess {number} unsyncedTenants.tenant_id Tenant ID
 * @apiSuccess {string} unsyncedTenants.name Tenant name
 * @apiSuccess {string} unsyncedTenants.subdomain Tenant subdomain
 * @apiSuccess {boolean} unsyncedTenants.meshcentral_setup_complete Always false for this array
 * @apiError (500) {String} error "Failed to get sync status"
 * @apiError (500) {String} details Detailed error message
 * @apiExample {curl} Example Request:
 *     curl -X GET https://api.ibghub.com/api/tenant-meshcentral-sync/status \
 *       -H "Authorization: Bearer YOUR_JWT_TOKEN"
 * @apiExample {json} Example Response:
 *     {
 *       "totalTenants": 15,
 *       "synced": 12,
 *       "unsynced": 3,
 *       "unsyncedTenants": [
 *         {"tenant_id": 8, "name": "New Customer LLC", "subdomain": "newcustomer", "meshcentral_setup_complete": false},
 *         {"tenant_id": 9, "name": "Beta Testing Co", "subdomain": "betatest", "meshcentral_setup_complete": false}
 *       ]
 *     }
 */
 
/**
 * Get sync status for all tenants
 * GET /api/tenant-meshcentral-sync/status
 */
router.get('/status', authenticateToken, async (req, res) => {
  try {
    const tenantsResult = await db.query(`
      SELECT 
        tenant_id, 
        name, 
        meshcentral_group_id, 
        meshcentral_setup_complete,
        (SELECT COUNT(*) FROM agents WHERE tenant_id = tenants.tenant_id AND meshcentral_nodeid IS NOT NULL) as linked_agents
      FROM tenants 
      ORDER BY created_at
    `);
    
    // Get all meshes from MeshCentral
    const api = await getMeshAPI();
    const meshes = await api.getMeshes();
    const meshIds = new Set(meshes.map(m => m._id));
    
    // Check each tenant's status
    const status = tenantsResult.rows.map(tenant => ({
      tenantId: tenant.tenant_id,
      tenantName: tenant.name,
      hasMeshId: !!tenant.meshcentral_group_id,
      meshId: tenant.meshcentral_group_id,
      meshExists: tenant.meshcentral_group_id ? meshIds.has(tenant.meshcentral_group_id) : false,
      setupComplete: tenant.meshcentral_setup_complete,
      linkedAgents: parseInt(tenant.linked_agents) || 0,
      needsSync: !tenant.meshcentral_group_id || !meshIds.has(tenant.meshcentral_group_id)
    }));
    
    const needsSync = status.filter(s => s.needsSync).length;
    
    res.json({
      success: true,
      totalTenants: status.length,
      needsSync,
      tenants: status
    });
    
  } catch (error) {
    console.error('❌ [TenantSync] Error getting status:', error);
    res.status(500).json({
      success: false,
      error: 'Failed to get sync status',
      details: error.message
    });
  }
});
 
module.exports = router;