webhooks.js

Go to the documentation of this file.

/**
 * @file webhooks.js
 * @module WebhooksRoutes
 * @description MeshCentral webhook handler for device events and agent auto-linking. Receives webhooks from MeshCentral for device lifecycle events (connect, disconnect, change) and automatically links devices to agents by hostname or MAC address. Includes webhook verification, auto-creation of agents, and configuration endpoints.
 * @see {@link ../lib/meshcentral-api} for MeshCentral API integration
 * @see {@link ../db} for database connection
 * @apiDefine WebhooksGroup Webhooks
 * @apiGroup Webhooks
 * @apiHeader {string} [X-MeshCentral-Secret] Webhook secret for authentication (optional in development).
 * @apiError (Error 401) Unauthorized Invalid webhook secret.
 * @apiError (Error 500) ServerError Failed to process webhook.
 *
 * Webhook Events:
 * - device.connect/node.connect: Device comes online, triggers auto-link
 * - device.disconnect/node.disconnect: Device goes offline, updates connection status
 * - device.change/node.change: Device information changes, updates last seen
 */
 
const express = require('express');
const router = express.Router();
const db = require('../db');
const MeshCentralAPI = require('../lib/meshcentral-api');
 
/**
 * Verify webhook is from MeshCentral
 * @param req
 * @param res
 * @param next
 */
function verifyWebhookAuth(req, res, next) {
  const webhookSecret = process.env.MESHCENTRAL_WEBHOOK_SECRET;
  
  if (!webhookSecret) {
    // If no secret configured, allow (for development)
    console.warn('⚠️  [MeshWebhook] No MESHCENTRAL_WEBHOOK_SECRET configured');
    return next();
  }
  
  const providedSecret = req.headers['x-meshcentral-secret'] || req.query.secret;
  
  if (providedSecret !== webhookSecret) {
    console.error('❌ [MeshWebhook] Invalid webhook secret');
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  next();
}
 
/**
 * Get MeshCentral API instance
 */
async function getMeshAPI() {
  const api = new MeshCentralAPI({
    url: process.env.MESHCENTRAL_URL || 'https://rmm-psa-meshcentral-aq48h.ondigitalocean.app',
    username: process.env.MESHCENTRAL_ADMIN_USER || 'admin',
    password: process.env.MESHCENTRAL_ADMIN_PASS || 'admin'
  });
  
  await api.login();
  return api;
}
 
/**
 * Try to auto-link a device to an agent
 * @param nodeId
 * @param nodeName
 * @param nodeHostname
 * @param nodeInfo
 */
async function autoLinkDevice(nodeId, nodeName, nodeHostname, nodeInfo = {}) {
  try {
    console.log(`\n🔗 [MeshWebhook] Auto-linking device: ${nodeHostname || nodeName} (${nodeId})`);
    
    // Check if already linked
    const existingLink = await db.query(
      'SELECT agent_id, hostname FROM agents WHERE meshcentral_nodeid = $1',
      [nodeId]
    );
    
    if (existingLink.rows.length > 0) {
      console.log(`✅ [MeshWebhook] Device already linked to agent ${existingLink.rows[0].agent_id}`);
      // Update connection status
      await db.query(
        'UPDATE agents SET meshcentral_connected = true, meshcentral_last_seen = NOW() WHERE meshcentral_nodeid = $1',
        [nodeId]
      );
      return { alreadyLinked: true, agentId: existingLink.rows[0].agent_id };
    }
    
    const hostname = nodeHostname || nodeName;
    if (!hostname) {
      console.log(`⚠️  [MeshWebhook] Device has no hostname, cannot auto-link`);
      return { success: false, reason: 'no_hostname' };
    }
    
    // Try to find matching agent by hostname
    const hostnameMatch = await db.query(
      'SELECT agent_id, agent_uuid, hostname, tenant_id FROM agents WHERE LOWER(hostname) = LOWER($1) AND meshcentral_nodeid IS NULL LIMIT 1',
      [hostname]
    );
    
    if (hostnameMatch.rows.length > 0) {
      const agent = hostnameMatch.rows[0];
      
      // Link agent to device
      await db.query(
        `UPDATE agents 
         SET meshcentral_nodeid = $1, 
             meshcentral_connected = true, 
             meshcentral_last_seen = NOW()
         WHERE agent_id = $2`,
        [nodeId, agent.agent_id]
      );
      
      console.log(`✅ [MeshWebhook] Linked agent ${agent.agent_id} (${agent.hostname}) to device ${nodeId}`);
      
      return {
        success: true,
        agentId: agent.agent_id,
        agentUuid: agent.agent_uuid,
        hostname: agent.hostname,
        method: 'hostname'
      };
    }
    
    // Try MAC address matching if available
    if (nodeInfo.mac || (nodeInfo.netif && Object.keys(nodeInfo.netif).length > 0)) {
      const macAddresses = [];
      
      if (nodeInfo.mac) {
        macAddresses.push(nodeInfo.mac);
      }
      
      if (nodeInfo.netif) {
        for (const iface of Object.values(nodeInfo.netif)) {
          if (iface.mac && iface.mac !== '00:00:00:00:00:00') {
            macAddresses.push(iface.mac);
          }
        }
      }
      
      for (const mac of macAddresses) {
        const macMatch = await db.query(`
          SELECT agent_id, agent_uuid, hostname
          FROM agents 
          WHERE meshcentral_nodeid IS NULL 
          AND hardware_data IS NOT NULL
          AND hardware_data::text ILIKE $1
          LIMIT 1
        `, [`%${mac}%`]);
        
        if (macMatch.rows.length > 0) {
          const agent = macMatch.rows[0];
          
          await db.query(
            `UPDATE agents 
             SET meshcentral_nodeid = $1, 
                 meshcentral_connected = true, 
                 meshcentral_last_seen = NOW()
             WHERE agent_id = $2`,
            [nodeId, agent.agent_id]
          );
          
          console.log(`✅ [MeshWebhook] Linked agent ${agent.agent_id} via MAC ${mac}`);
          
          return {
            success: true,
            agentId: agent.agent_id,
            agentUuid: agent.agent_uuid,
            hostname: agent.hostname,
            method: 'mac_address',
            mac: mac
          };
        }
      }
    }
    
    // No existing agent found - create a new one
    console.log(`🆕 [MeshWebhook] No matching agent found - creating new agent for: ${hostname}`);
    
    const crypto = require('crypto');
    const newAgentUuid = crypto.randomUUID();
    
    // Determine platform from node info
    let platform = 'unknown';
    if (nodeInfo.osdesc || nodeInfo.platform) {
      const osDesc = (nodeInfo.osdesc || nodeInfo.platform || '').toLowerCase();
      if (osDesc.includes('windows')) platform = 'windows';
      else if (osDesc.includes('linux')) platform = 'linux';
      else if (osDesc.includes('darwin') || osDesc.includes('mac')) platform = 'darwin';
    }
    
    // Get default tenant (tenant_id = 1) or null
    const tenantResult = await db.query('SELECT tenant_id FROM tenants WHERE tenant_id = 1 LIMIT 1');
    const defaultTenantId = tenantResult.rows.length > 0 ? tenantResult.rows[0].tenant_id : null;
    
    // Create new agent
    const insertResult = await db.query(
      `INSERT INTO agents (
        agent_uuid, tenant_id, hostname, platform, 
        meshcentral_nodeid, meshcentral_connected, meshcentral_last_seen,
        status, last_seen, created_at
      ) VALUES ($1, $2, $3, $4, $5, $6, NOW(), 'online', NOW(), NOW())
      RETURNING agent_id, agent_uuid, hostname`,
      [newAgentUuid, defaultTenantId, hostname, platform, nodeId, true]
    );
    
    const newAgent = insertResult.rows[0];
    console.log(`✅ [MeshWebhook] Created new agent ${newAgent.agent_id} (${newAgent.hostname}) linked to device ${nodeId}`);
    
    return {
      success: true,
      created: true,
      agentId: newAgent.agent_id,
      agentUuid: newAgent.agent_uuid,
      hostname: newAgent.hostname,
      method: 'created_new'
    };
    
  } catch (error) {
    console.error('❌ [MeshWebhook] Auto-link error:', error.message);
    throw error;
  }
}
 
/**
 * @api {post} /webhooks/meshcentral Receive MeshCentral event webhook
 * @apiName ReceiveMeshCentralWebhook
 * @apiGroup Webhooks
 * @apiDescription Main webhook endpoint that receives device lifecycle events from MeshCentral. Handles device connect/disconnect/change events, auto-links devices to agents by hostname or MAC address, and creates new agents if no match is found. Requires webhook secret authentication (X-MeshCentral-Secret header or query param).
 * @apiHeader {string} [X-MeshCentral-Secret] Webhook authentication secret (optional in dev).
 * @apiParam {string} event Event type (device.connect, device.disconnect, device.change, node.connect, node.disconnect, node.change).
 * @apiParam {string} nodeId MeshCentral node ID of the device.
 * @apiParam {string} [nodeName] Device name.
 * @apiParam {string} [hostname] Device hostname.
 * @apiParam {object} [node] Device information object (platform, MAC, network interfaces, etc.).
 * @apiSuccess {boolean} success Operation success status.
 * @apiSuccess {string} event Event type processed.
 * @apiSuccess {Object} [linkResult] Auto-link result (for connect events).
 * @apiSuccess {boolean} [linkResult.success] Auto-link success status.
 * @apiSuccess {string} [linkResult.agentId] Linked or created agent ID.
 * @apiSuccess {string} [linkResult.method] Link method (hostname, mac_address, created_new).
 * @apiSuccess {boolean} [updated] Device status updated (for disconnect/change events).
 * @apiError (Error 401) Unauthorized Invalid webhook secret.
 * @apiError (Error 500) ServerError Failed to process webhook.
 * @apiExample {curl} Example usage:
 *     curl -X POST -H "X-MeshCentral-Secret: <secret>" -d '{"event":"device.connect","nodeId":"node//abc123","nodeName":"SERVER01","hostname":"server01.local"}' https://api.example.com/webhooks/meshcentral
 */
router.post('/meshcentral', verifyWebhookAuth, async (req, res) => {
  try {
    const event = req.body;
    
    console.log(`\n📬 [MeshWebhook] Received event: ${event.event}`);
    console.log(`   Node: ${event.nodeName || event.nodeId}`);
    
    // Handle different event types
    switch (event.event) {
      case 'device.connect':
      case 'node.connect': {
        // Device connected - try to auto-link
        const result = await autoLinkDevice(
          event.nodeId,
          event.nodeName,
          event.hostname || event.host,
          event.node || {}
        );
        
        return res.json({
          success: true,
          event: event.event,
          linkResult: result
        });
      }
      
      case 'device.disconnect':
      case 'node.disconnect': {
        // Update connection status
        await db.query(
          'UPDATE agents SET meshcentral_connected = false WHERE meshcentral_nodeid = $1',
          [event.nodeId]
        );
        
        console.log(`📴 [MeshWebhook] Device disconnected: ${event.nodeName}`);
        
        return res.json({
          success: true,
          event: event.event,
          updated: true
        });
      }
      
      case 'device.change':
      case 'node.change': {
        // Device information changed - update last seen
        await db.query(
          'UPDATE agents SET meshcentral_last_seen = NOW() WHERE meshcentral_nodeid = $1',
          [event.nodeId]
        );
        
        console.log(`🔄 [MeshWebhook] Device changed: ${event.nodeName}`);
        
        return res.json({
          success: true,
          event: event.event,
          updated: true
        });
      }
      
      default: {
        console.log(`ℹ️  [MeshWebhook] Unhandled event type: ${event.event}`);
        return res.json({
          success: true,
          event: event.event,
          handled: false
        });
      }
    }
    
  } catch (error) {
    console.error('❌ [MeshWebhook] Error processing webhook:', error);
    res.status(500).json({ error: 'Failed to process webhook', message: error.message });
  }
});
 
/**
 * @api {post} /webhooks/meshcentral-test Test webhook (no authentication)
 * @apiName TestMeshCentralWebhook
 * @apiGroup Webhooks
 * @apiDescription Test endpoint for webhook development and debugging. Accepts any JSON payload and logs it to console. No authentication required.
 * @apiParam {object} * Any JSON payload for testing.
 * @apiSuccess {boolean} success Always true.
 * @apiSuccess {string} message Status message.
 * @apiSuccess {object} receivedData Echo of received payload.
 * @apiExample {curl} Example usage:
 *     curl -X POST -d '{"test":"data"}' https://api.example.com/webhooks/meshcentral-test
 */
router.post('/meshcentral-test', async (req, res) => {
  console.log('\n🧪 [MeshWebhook Test] Received test webhook:');
  console.log(JSON.stringify(req.body, null, 2));
  
  res.json({
    success: true,
    message: 'Test webhook received',
    receivedData: req.body
  });
});
 
/**
 * @api {get} /webhooks/meshcentral/config Get webhook configuration
 * @apiName GetWebhookConfig
 * @apiGroup Webhooks
 * @apiDescription Returns webhook configuration details including URLs, secret status, supported events, and sample MeshCentral config.json snippet for easy integration.
 * @apiSuccess {string} webhookUrl Production webhook URL.
 * @apiSuccess {string} testUrl Test webhook URL (no auth).
 * @apiSuccess {boolean} secretConfigured Whether webhook secret is configured.
 * @apiSuccess {string[]} events Supported event types.
 * @apiSuccess {object} meshcentralConfig Sample MeshCentral configuration.
 * @apiExample {curl} Example usage:
 *     curl https://api.example.com/webhooks/meshcentral/config
 * @apiExample {json} Response example:
 *     {
 *       "webhookUrl": "https://api.example.com/webhooks/meshcentral",
 *       "testUrl": "https://api.example.com/webhooks/meshcentral-test",
 *       "secretConfigured": true,
 *       "events": ["device.connect", "device.disconnect", "device.change"],
 *       "meshcentralConfig": {
 *         "settings": {
 *           "webhooks": {
 *             "deviceEvents": "https://api.example.com/webhooks/meshcentral",
 *             "authToken": "YOUR_SECRET_HERE"
 *           }
 *         }
 *       }
 *     }
 */
router.get('/meshcentral/config', async (req, res) => {
  const webhookUrl = `${process.env.BACKEND_URL || 'https://everydaytech.au'}/api/webhooks/meshcentral`;
  const webhookSecret = process.env.MESHCENTRAL_WEBHOOK_SECRET || '(not configured)';
  
  res.json({
    webhookUrl: webhookUrl,
    testUrl: `${process.env.BACKEND_URL || 'https://everydaytech.au'}/api/webhooks/meshcentral-test`,
    secretConfigured: !!process.env.MESHCENTRAL_WEBHOOK_SECRET,
    events: [
      'device.connect',
      'device.disconnect',
      'device.change',
      'node.connect',
      'node.disconnect',
      'node.change'
    ],
    meshcentralConfig: {
      note: 'Add this to your MeshCentral config.json',
      config: {
        settings: {
          webhooks: {
            deviceEvents: webhookUrl,
            authToken: webhookSecret !== '(not configured)' ? webhookSecret : 'YOUR_SECRET_HERE'
          }
        }
      }
    }
  });
});
 
module.exports = router;