cloudflare-dns.js

Go to the documentation of this file.

/**
 * @file routes/cloudflare-dns.js
 * @module routes/cloudflare-dns
 * @description
 *   Cloudflare DNS management API for zone and record CRUD operations.
 *   Provides comprehensive DNS record management with Redis caching for performance.
 *
 *   **Core Features:**
 *   - Zone listing and zone ID retrieval
 *   - DNS record CRUD (Create, Read, Update, Delete)
 *   - Redis cache with 5-minute sync interval
 *   - Cache invalidation on mutations
 *   - Support for all DNS record types (A, AAAA, CNAME, MX, TXT, etc.)
 *   - Cloudflare proxy toggle support
 *   - Audit logging for all changes
 *
 *   **Caching Strategy:**
 *   - GET requests use Redis cache (5-min TTL)
 *   - Force refresh with ?refresh=true query parameter
 *   - Cache automatically invalidated on POST/PUT/DELETE
 *   - Background worker syncs cache periodically
 *
 *   **Security:**
 *   - All routes require authentication
 *   - User actions logged with username
 *   - Cloudflare API token from environment
 *   @requires express
 *   @requires ../middleware/auth
 *   @requires ../services/cloudflare
 *   @requires ../dnsRecordsSyncWorker
 *   @author RMM-PSA Development Team
 *   @date 2026-03-12
 *   @since 1.0.0
 */
const express = require('express');
const router = express.Router();
const authenticateToken = require('../middleware/auth');
const { getTenantFilter } = require('../middleware/tenant');
const pool = require('../services/db');
const { 
  getZoneId,
  listDNSRecords,
  createDNSRecord,
  updateDNSRecord,
  deleteDNSRecord,
  listZones
} = require('../services/cloudflare');
const { getCachedDNSRecords, invalidateDNSCache } = require('../dnsRecordsSyncWorker');
 
// Apply authentication to all routes
router.use(authenticateToken);
 
/**
 * @api {get} /cloudflare-dns/zones List Cloudflare zones
 * @apiName ListCloudflareZones
 * @apiGroup CloudflareDNS
 * @apiDescription
 *   Retrieve all Cloudflare zones (domains) managed under the account.
 *   Returns zone metadata including names, IDs, and status.
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiSuccess {boolean} success Operation success flag
 * @apiSuccess {object[]} zones Array of zone objects
 * @apiSuccess {string} zones.id Zone ID
 * @apiSuccess {string} zones.name Domain name
 * @apiSuccess {string} zones.status Zone status (active, pending, moved, etc.)
 * @apiSuccess {DateTime} zones.created_on Zone creation date
 * @apiError (500) {Boolean} success=false Operation failed
 * @apiError (500) {String} error Error message
 * @apiError (500) {String} details Detailed error information
 * @apiExample {curl} Example usage:
 *   curl -X GET https://api.example.com/cloudflare-dns/zones \\
 *     -H "Authorization: Bearer YOUR_TOKEN"
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true,
 *     "zones": [
 *       {
 *         "id": "abc123",
 *         "name": "example.com",
 *         "status": "active",
 *         "created_on": "2026-01-15T10:00:00Z"
 *       }
 *     ]
 *   }
 */
router.get('/zones', async (req, res) => {
  try {
    const zones = await listZones();
    res.json({ success: true, zones });
  } catch (err) {
    console.error('Error fetching Cloudflare zones:', err);
    res.status(500).json({ 
      success: false, 
      error: 'Failed to fetch zones', 
      details: err.message 
    });
  }
});
 
/**
 * @api {get} /cloudflare-dns/:domain/zone-id Get zone ID
 * @apiName GetZoneId
 * @apiGroup CloudflareDNS
 * @apiDescription
 *   Retrieve Cloudflare zone ID for a specific domain.
 *   Zone IDs are required for DNS record operations.
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiParam {string} domain Domain name (e.g., "example.com")
 * @apiSuccess {boolean} success Operation success flag
 * @apiSuccess {string} zone_id Cloudflare zone identifier
 * @apiSuccess {string} domain Domain name
 * @apiError (404) {Boolean} success=false Zone not found
 * @apiError (404) {String} error="Zone not found in Cloudflare"
 * @apiError (500) {Boolean} success=false Operation failed
 * @apiError (500) {String} error Error message
 * @apiError (500) {String} details Detailed error information
 * @apiExample {curl} Example usage:
 *   curl -X GET https://api.example.com/cloudflare-dns/example.com/zone-id \\
 *     -H "Authorization: Bearer YOUR_TOKEN"
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true,
 *     "zone_id": "abc123xyz",
 *     "domain": "example.com"
 *   }
 */
router.get('/:domain/zone-id', async (req, res) => {
  const { domain } = req.params;
  
  try {
    const zoneId = await getZoneId(domain);
    
    if (!zoneId) {
      return res.status(404).json({ 
        success: false, 
        error: 'Zone not found in Cloudflare' 
      });
    }
    
    res.json({ success: true, zone_id: zoneId, domain });
  } catch (err) {
    console.error(`Error getting zone ID for ${domain}:`, err);
    res.status(500).json({ 
      success: false, 
      error: 'Failed to get zone ID', 
      details: err.message 
    });
  }
});
 
/**
 * @api {get} /cloudflare-dns/:domain/records List DNS records
 * @apiName ListDNSRecords
 * @apiGroup CloudflareDNS
 * @apiDescription
 *   Retrieve all DNS records for a domain with Redis caching.
 *   First checks Redis cache (5-min TTL), falls back to Cloudflare API on cache miss.
 *   Returns all record types: A, AAAA, CNAME, MX, TXT, SRV, etc.
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiParam {string} domain Domain name (e.g., "example.com")
 * @apiParam {boolean} [refresh=false] Force refresh from Cloudflare API (bypass cache)
 * @apiSuccess {boolean} success Operation success flag
 * @apiSuccess {string} domain Domain name
 * @apiSuccess {string} [zone_id] Cloudflare zone ID (if fetched from API)
 * @apiSuccess {object[]} records Array of DNS record objects
 * @apiSuccess {string} records.id Record ID
 * @apiSuccess {string} records.type Record type (A, AAAA, CNAME, MX, TXT, etc.)
 * @apiSuccess {string} records.name Record name/hostname
 * @apiSuccess {string} records.content Record value/target
 * @apiSuccess {number} records.ttl Time-to-live in seconds
 * @apiSuccess {boolean} records.proxied Cloudflare proxy status (orange cloud)
 * @apiSuccess {number} [records.priority] Priority (MX/SRV records)
 * @apiSuccess {DateTime} last_synced Last sync timestamp
 * @apiSuccess {boolean} from_cache Whether data came from Redis cache
 * @apiError (404) {Boolean} success=false Zone not found
 * @apiError (404) {String} error="Zone not found in Cloudflare"
 * @apiError (500) {Boolean} success=false Operation failed
 * @apiError (500) {String} error Error message
 * @apiError (500) {String} details Detailed error information
 * @apiExample {curl} Example usage (cached):
 *   curl -X GET https://api.example.com/cloudflare-dns/example.com/records \\
 *     -H "Authorization: Bearer YOUR_TOKEN"
 *
 * @apiExample {curl} Force refresh from API:
 *   curl -X GET https://api.example.com/cloudflare-dns/example.com/records?refresh=true \\
 *     -H "Authorization: Bearer YOUR_TOKEN"
 *
 * @apiSuccessExample {json} Success-Response (cached):
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true,
 *     "domain": "example.com",
 *     "records": [
 *       {
 *         "id": "rec123",
 *         "type": "A",
 *         "name": "example.com",
 *         "content": "192.0.2.1",
 *         "ttl": 3600,
 *         "proxied": true
 *       },
 *       {
 *         "id": "rec456",
 *         "type": "CNAME",
 *         "name": "www.example.com",
 *         "content": "example.com",
 *         "ttl": 3600,
 *         "proxied": true
 *       }
 *     ],
 *     "last_synced": "2026-03-12T10:05:00Z",
 *     "from_cache": true
 *   }
 */
router.get('/:domain/records', async (req, res) => {
  const { domain } = req.params;
  const { refresh } = req.query; // Optional: force refresh from API
  
  try {
    // Try cache first (unless refresh requested)
    if (!refresh) {
      const cached = await getCachedDNSRecords(domain);
      
      if (cached) {
        console.log(`[DNS] Cache hit for ${domain} (${cached.records.length} records, synced: ${cached.last_synced})`);
        return res.json({ 
          success: true, 
          domain,
          records: cached.records,
          last_synced: cached.last_synced,
          from_cache: true
        });
      }
    }
    
    // Cache miss or refresh requested - fetch from Cloudflare API
    console.log(`[DNS] Cache miss for ${domain}, fetching from Cloudflare...`);
    
    // Get zone ID first
    const zoneId = await getZoneId(domain);
    
    if (!zoneId) {
      return res.status(404).json({ 
        success: false, 
        error: 'Zone not found in Cloudflare' 
      });
    }
    
    // Get all DNS records from API
    const records = await listDNSRecords(zoneId);
    
    res.json({ 
      success: true, 
      domain,
      zone_id: zoneId,
      records,
      last_synced: new Date().toISOString(),
      from_cache: false
    });
  } catch (err) {
    console.error(`Error fetching DNS records for ${domain}:`, err);
    res.status(500).json({ 
      success: false, 
      error: 'Failed to fetch DNS records', 
      details: err.message 
    });
  }
});
 
/**
 * @api {post} /cloudflare-dns/:domain/records Create DNS record
 * @apiName CreateDNSRecord
 * @apiGroup CloudflareDNS
 * @apiDescription
 *   Create a new DNS record in Cloudflare zone.
 *   Supports all DNS record types with optional priority and proxy settings.
 *   Automatically invalidates Redis cache on success.
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} domain Domain name (URL parameter)
 * @apiParam {string} type Record type (A, AAAA, CNAME, MX, TXT, SRV, etc.)
 * @apiParam {string} name Record name/hostname (e.g., "www" or "@" for root)
 * @apiParam {string} content Record value (IP address, hostname, or text)
 * @apiParam {number} [ttl=3600] Time-to-live in seconds (1=auto)
 * @apiParam {number} [priority] Priority (required for MX/SRV records)
 * @apiParam {boolean} [proxied=false] Enable Cloudflare proxy (orange cloud)
 * @apiSuccess {boolean} success=true Operation succeeded
 * @apiSuccess {string} message="DNS record created successfully"
 * @apiSuccess {Object} record Created DNS record object with Cloudflare metadata
 * @apiError (400) {Boolean} success=false Validation failed
 * @apiError (400) {String} error="Missing required fields: type, name, content"
 * @apiError (404) {Boolean} success=false Zone not found
 * @apiError (404) {String} error="Zone not found in Cloudflare"
 * @apiError (409) {Boolean} success=false Record already exists
 * @apiError (409) {String} error="DNS record already exists"
 * @apiError (500) {Boolean} success=false Operation failed
 * @apiError (500) {String} error Error message
 * @apiError (500) {String} details Detailed error information
 * @apiExample {curl} Create A record:
 *   curl -X POST https://api.example.com/cloudflare-dns/example.com/records \\
 *     -H "Authorization: Bearer YOUR_TOKEN" \\
 *     -H "Content-Type: application/json" \\
 *     -d '{
 *       "type": "A",
 *       "name": "www",
 *       "content": "192.0.2.1",
 *       "ttl": 3600,
 *       "proxied": true
 *     }'
 * @apiExample {curl} Create MX record:
 *   curl -X POST https://api.example.com/cloudflare-dns/example.com/records \\
 *     -H "Authorization: Bearer YOUR_TOKEN" \\
 *     -H "Content-Type: application/json" \\
 *     -d '{
 *       "type": "MX",
 *       "name": "@",
 *       "content": "mail.example.com",
 *       "ttl": 3600,
 *       "priority": 10
 *     }'
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true,
 *     "message": "DNS record created successfully",
 *     "record": {
 *       "id": "newrec789",
 *       "type": "A",
 *       "name": "www.example.com",
 *       "content": "192.0.2.1",
 *       "ttl": 3600,
 *       "proxied": true
 *     }
 *   }
 */
router.post('/:domain/records', async (req, res) => {
  const { domain } = req.params;
  const { type, name, content, ttl, priority, proxied } = req.body;
  
  try {
    // Validate required fields
    if (!type || !name || !content) {
      return res.status(400).json({ 
        success: false, 
        error: 'Missing required fields: type, name, content' 
      });
    }
    
    // Get zone ID
    const zoneId = await getZoneId(domain);
    
    if (!zoneId) {
      return res.status(404).json({ 
        success: false, 
        error: 'Zone not found in Cloudflare' 
      });
    }
    
    // Create DNS record
    const record = await createDNSRecord(zoneId, {
      type,
      name,
      content,
      ttl: ttl || 3600,
      priority,
      proxied: proxied !== undefined ? proxied : false
    });
    
    // Invalidate cache so next fetch gets fresh data
    await invalidateDNSCache(domain);
    
    // Log the change
    console.log(`[DNS] User ${req.user.username} created ${type} record ${name} for ${domain}`);
    
    res.json({ 
      success: true, 
      message: 'DNS record created successfully',
      record 
    });
  } catch (err) {
    console.error(`Error creating DNS record for ${domain}:`, err);
    
    if (err.code === 'RECORD_EXISTS') {
      return res.status(409).json({ 
        success: false, 
        error: 'DNS record already exists' 
      });
    }
    
    res.status(500).json({ 
      success: false, 
      error: 'Failed to create DNS record', 
      details: err.message 
    });
  }
});
 
/**
 * @api {put} /cloudflare-dns/:domain/records/:recordId Update DNS record
 * @apiName UpdateDNSRecord
 * @apiGroup CloudflareDNS
 * @apiDescription
 *   Update an existing DNS record in Cloudflare zone.
 *   Requires all fields (partial updates not supported by Cloudflare API).
 *   Automatically invalidates Redis cache on success.
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} domain Domain name (URL parameter)
 * @apiParam {string} recordId Cloudflare record ID (URL parameter)
 * @apiParam {string} type Record type (A, AAAA, CNAME, MX, TXT, etc.)
 * @apiParam {string} name Record name/hostname
 * @apiParam {string} content Record value
 * @apiParam {number} [ttl=3600] Time-to-live in seconds
 * @apiParam {number} [priority] Priority (for MX/SRV records)
 * @apiParam {boolean} [proxied=false] Cloudflare proxy status
 * @apiSuccess {boolean} success=true Operation succeeded
 * @apiSuccess {string} message="DNS record updated successfully"
 * @apiSuccess {Object} record Updated DNS record object
 * @apiError (400) {Boolean} success=false Validation failed
 * @apiError (400) {String} error="Missing required fields: type, name, content"
 * @apiError (404) {Boolean} success=false Zone or record not found
 * @apiError (404) {String} error="Zone not found in Cloudflare"
 * @apiError (500) {Boolean} success=false Operation failed
 * @apiError (500) {String} error Error message
 * @apiError (500) {String} details Detailed error information
 * @apiExample {curl} Update A record:
 *   curl -X PUT https://api.example.com/cloudflare-dns/example.com/records/rec123 \\
 *     -H "Authorization: Bearer YOUR_TOKEN" \\
 *     -H "Content-Type: application/json" \\
 *     -d '{
 *       "type": "A",
 *       "name": "www",
 *       "content": "192.0.2.2",
 *       "ttl": 1800,
 *       "proxied": false
 *     }'
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true,
 *     "message": "DNS record updated successfully",
 *     "record": {
 *       "id": "rec123",
 *       "type": "A",
 *       "name": "www.example.com",
 *       "content": "192.0.2.2",
 *       "ttl": 1800,
 *       "proxied": false
 *     }
 *   }
 */
router.put('/:domain/records/:recordId', async (req, res) => {
  const { domain, recordId } = req.params;
  const { type, name, content, ttl, priority, proxied } = req.body;
  
  try {
    // Validate required fields
    if (!type || !name || !content) {
      return res.status(400).json({ 
        success: false, 
        error: 'Missing required fields: type, name, content' 
      });
    }
    
    // Get zone ID
    const zoneId = await getZoneId(domain);
    
    if (!zoneId) {
      return res.status(404).json({ 
        success: false, 
        error: 'Zone not found in Cloudflare' 
      });
    }
    
    // Update DNS record
    const record = await updateDNSRecord(zoneId, recordId, {
      type,
      name,
      content,
      ttl: ttl || 3600,
      priority,
      proxied: proxied !== undefined ? proxied : false
    });
    
    // Invalidate cache so next fetch gets fresh data
    await invalidateDNSCache(domain);
    
    // Log the change
    console.log(`[DNS] User ${req.user.username} updated ${type} record ${name} for ${domain}`);
    
    res.json({ 
      success: true, 
      message: 'DNS record updated successfully',
      record 
    });
  } catch (err) {
    console.error(`Error updating DNS record ${recordId} for ${domain}:`, err);
    res.status(500).json({ 
      success: false, 
      error: 'Failed to update DNS record', 
      details: err.message 
    });
  }
});
 
/**
 * @api {delete} /cloudflare-dns/:domain/records/:recordId Delete DNS record
 * @apiName DeleteDNSRecord
 * @apiGroup CloudflareDNS
 * @apiDescription
 *   Delete a DNS record from Cloudflare zone.
 *   Permanently removes the record and invalidates Redis cache.
 *   Action is logged with username for audit trail.
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiParam {string} domain Domain name (URL parameter)
 * @apiParam {string} recordId Cloudflare record ID (URL parameter)
 * @apiSuccess {boolean} success=true Operation succeeded
 * @apiSuccess {string} message="DNS record deleted successfully"
 * @apiError (404) {Boolean} success=false Zone or record not found
 * @apiError (404) {String} error="Zone not found in Cloudflare"
 * @apiError (500) {Boolean} success=false Operation failed
 * @apiError (500) {String} error Error message
 * @apiError (500) {String} details Detailed error information
 * @apiExample {curl} Delete record:
 *   curl -X DELETE https://api.example.com/cloudflare-dns/example.com/records/rec123 \\
 *     -H "Authorization: Bearer YOUR_TOKEN"
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true,
 *     "message": "DNS record deleted successfully"
 *   }
 */
router.delete('/:domain/records/:recordId', async (req, res) => {
  const { domain, recordId } = req.params;
  
  try {
    // Get zone ID
    const zoneId = await getZoneId(domain);
    
    if (!zoneId) {
      return res.status(404).json({ 
        success: false, 
        error: 'Zone not found in Cloudflare' 
      });
    }
    
    // Delete DNS record
    await deleteDNSRecord(zoneId, recordId);
    
    // Invalidate cache so next fetch gets fresh data
    await invalidateDNSCache(domain);
    
    // Log the change
    console.log(`[DNS] User ${req.user.username} deleted record ${recordId} for ${domain}`);
    
    res.json({ 
      success: true, 
      message: 'DNS record deleted successfully' 
    });
  } catch (err) {
    console.error(`Error deleting DNS record ${recordId} for ${domain}:`, err);
    res.status(500).json({ 
      success: false, 
      error: 'Failed to delete DNS record', 
      details: err.message 
    });
  }
});
 
module.exports = router;