feat: Refactor to Fastify with auto-swagger and MCP support

- Replace Express with Fastify 5.x
- Add @fastify/swagger for automatic OpenAPI generation from JSON schemas
- Add @fastify/swagger-ui at /api/docs
- Implement MCP server plugin with container management tools
- Port all routers with JSON schema validation:
  - login/logout, register, reset-password (auth flows)
  - apikeys, settings (simple CRUD)
  - users, groups (user management)
  - sites, nodes, containers (infrastructure)
  - jobs (async task monitoring with SSE)
  - external-domains (DNS management)
- Create Fastify plugins:
  - auth.js: requireAuth, requireAdmin, requireLocalhostOrAdmin
  - flash.js: flash message support for EJS views
  - load-sites.js: site context for authenticated users
  - mcp.js: Model Context Protocol server
- Preserve dual HTML/JSON content negotiation
- Keep existing Sequelize models unchanged
- Maintain EJS views with @fastify/view

Author: horner

create-a-container/package-lock.json

@@ -5,13 +5,27 @@
     ]
   },
   "scripts": {
-    "dev": "nodemon server.js",
+    "start": "node server-fastify.js",
+    "start:express": "node server.js",
+    "dev": "nodemon server-fastify.js",
+    "dev:express": "nodemon server.js",
     "db:migrate": "sequelize db:migrate && sequelize db:seed:all",
     "job-runner": "node job-runner.js",
     "test": "npx playwright test",
     "test:ui": "npx playwright test --ui"
   },
   "dependencies": {
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/formbody": "^8.0.2",
+    "@fastify/rate-limit": "^10.3.0",
+    "@fastify/sensible": "^6.0.4",
+    "@fastify/session": "^11.1.1",
+    "@fastify/static": "^9.0.0",
+    "@fastify/swagger": "^9.7.0",
+    "@fastify/swagger-ui": "^5.2.5",
+    "@fastify/view": "^11.1.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "argon2": "^0.44.0",
     "axios": "^1.13.5",
     "connect-flash": "^0.1.1",
@@ -21,6 +35,8 @@
     "express-rate-limit": "^8.1.1",
     "express-session": "^1.18.2",
     "express-session-sequelize": "^2.3.0",
+    "fastify": "^5.8.2",
+    "fastify-plugin": "^5.1.0",
     "method-override": "^3.0.0",
     "morgan": "^1.10.1",
     "nodemailer": "^7.0.11",
@@ -34,6 +50,7 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",
-    "nodemon": "^3.1.10"
+    "nodemon": "^3.1.10",
+    "pino-pretty": "^13.1.3"
   }
 }

create-a-container/package.json

@@ -0,0 +1,143 @@
+const fp = require('fastify-plugin');
+
+/**
+ * Authentication plugin for Fastify
+ * Provides session and API key authentication with admin checks
+ */
+async function authPlugin(fastify, options) {
+  // Helper to check if request wants JSON response
+  function isApiRequest(request) {
+    const acceptHeader = request.headers.accept || '';
+    const acceptsJSON = acceptHeader.includes('application/json') || acceptHeader.includes('application/vnd.api+json');
+    const isAjax = request.headers['x-requested-with'] === 'XMLHttpRequest';
+    const isApiPath = request.url?.startsWith('/api/');
+    return acceptsJSON || isAjax || isApiPath;
+  }
+
+  // Decorate request with helper
+  fastify.decorateRequest('isApiRequest', function() {
+    return isApiRequest(this);
+  });
+
+  // Decorate request with user-related properties
+  fastify.decorateRequest('user', null);
+  fastify.decorateRequest('apiKey', null);
+  fastify.decorateRequest('isAdmin', false);
+
+  /**
+   * Authentication hook - validates session or API key
+   */
+  async function requireAuth(request, reply) {
+    // First check session authentication
+    if (request.session?.user) {
+      request.isAdmin = request.session.isAdmin || false;
+      return;
+    }
+
+    // Try API key authentication
+    const authHeader = request.headers.authorization;
+    if (authHeader && authHeader.startsWith('Bearer ')) {
+      const apiKey = authHeader.substring(7);
+
+      if (apiKey) {
+        const { ApiKey, User } = require('../models');
+        const { extractKeyPrefix } = require('../utils/apikey');
+
+        const keyPrefix = extractKeyPrefix(apiKey);
+
+        const apiKeys = await ApiKey.findAll({
+          where: { keyPrefix },
+          include: [{
+            model: User,
+            as: 'user',
+            include: [{ association: 'groups' }]
+          }]
+        });
+
+        for (const storedKey of apiKeys) {
+          const isValid = await storedKey.validateKey(apiKey);
+          if (isValid) {
+            request.user = storedKey.user;
+            request.apiKey = storedKey;
+            request.isAdmin = storedKey.user.groups?.some(g => g.isAdmin) || false;
+
+            // Populate session for compatibility
+            request.session.user = storedKey.user.uid;
+            request.session.isAdmin = request.isAdmin;
+
+            // Record usage asynchronously
+            storedKey.recordUsage().catch(err => {
+              fastify.log.error('Failed to update API key last used timestamp:', err);
+            });
+
+            return;
+          }
+        }
+      }
+    }
+
+    // Neither session nor API key authentication succeeded
+    if (isApiRequest(request)) {
+      return reply.code(401).send({ error: 'Unauthorized' });
+    }
+
+    // Browser request - redirect to login
+    const original = request.url || '/';
+    const redirectTo = '/login?redirect=' + encodeURIComponent(original);
+    return reply.redirect(redirectTo);
+  }
+
+  /**
+   * Admin check hook - must be used after requireAuth
+   */
+  async function requireAdmin(request, reply) {
+    if (request.session?.isAdmin || request.isAdmin) {
+      return;
+    }
+
+    if (isApiRequest(request)) {
+      return reply.code(403).send({ error: 'Forbidden: Admin access required' });
+    }
+
+    return reply.code(403).send('Forbidden: Admin access required');
+  }
+
+  /**
+   * Localhost or admin check hook
+   * Allows localhost requests without auth; remote requests need admin
+   */
+  async function requireLocalhostOrAdmin(request, reply) {
+    const isLocalhost = (ip) => {
+      return ip === '127.0.0.1' ||
+             ip === '::1' ||
+             ip === '::ffff:127.0.0.1' ||
+             ip === 'localhost';
+    };
+
+    const directIp = request.ip;
+    const realIp = request.headers['x-real-ip'];
+
+    // If direct connection is from localhost and no non-localhost X-Real-IP, allow through
+    if (isLocalhost(directIp) && (!realIp || isLocalhost(realIp))) {
+      return;
+    }
+
+    // Not localhost — require auth + admin
+    await requireAuth(request, reply);
+    if (reply.sent) return;
+    await requireAdmin(request, reply);
+  }
+
+  // Decorate fastify with auth hooks so routes can use them
+  fastify.decorate('requireAuth', requireAuth);
+  fastify.decorate('requireAdmin', requireAdmin);
+  fastify.decorate('requireLocalhostOrAdmin', requireLocalhostOrAdmin);
+
+  // Also expose isApiRequest as a utility
+  fastify.decorate('isApiRequest', isApiRequest);
+}
+
+module.exports = fp(authPlugin, {
+  name: 'auth',
+  dependencies: ['@fastify/session']
+});

create-a-container/plugins/auth.js

@@ -0,0 +1,65 @@
+const fp = require('fastify-plugin');
+
+/**
+ * Flash messages plugin for Fastify
+ * Provides Express-compatible flash() functionality using sessions
+ */
+async function flashPlugin(fastify, options) {
+  // Decorate request with flash method
+  fastify.decorateRequest('flash', function(type, message) {
+    if (!this.session) {
+      throw new Error('Flash requires session support');
+    }
+
+    // Initialize flash storage
+    if (!this.session.flash) {
+      this.session.flash = {};
+    }
+
+    // If no arguments, return and clear all flash messages
+    if (arguments.length === 0) {
+      const messages = this.session.flash || {};
+      this.session.flash = {};
+      return messages;
+    }
+
+    // If only type provided, return messages for that type
+    if (arguments.length === 1) {
+      const messages = this.session.flash[type] || [];
+      delete this.session.flash[type];
+      return messages;
+    }
+
+    // Add message to flash
+    if (!this.session.flash[type]) {
+      this.session.flash[type] = [];
+    }
+    this.session.flash[type].push(message);
+
+    return this.session.flash[type].length;
+  });
+
+  // Pre-handler to expose flash messages to views
+  fastify.addHook('preHandler', async (request, reply) => {
+    // Make flash messages available to templates
+    reply.locals = reply.locals || {};
+    
+    // Get flash messages without clearing them yet
+    const flashMessages = request.session?.flash || {};
+    
+    reply.locals.successMessages = flashMessages.success || [];
+    reply.locals.errorMessages = flashMessages.error || [];
+    reply.locals.warningMessages = flashMessages.warning || [];
+    reply.locals.infoMessages = flashMessages.info || [];
+    
+    // Clear flash after reading
+    if (request.session) {
+      request.session.flash = {};
+    }
+  });
+}
+
+module.exports = fp(flashPlugin, {
+  name: 'flash',
+  dependencies: ['@fastify/session']
+});

create-a-container/plugins/flash.js

@@ -0,0 +1,49 @@
+const fp = require('fastify-plugin');
+
+/**
+ * Load sites plugin for Fastify
+ * Loads all sites for authenticated users and attaches to reply.locals
+ */
+async function loadSitesPlugin(fastify, options) {
+  const { Site } = require('../models');
+
+  fastify.addHook('preHandler', async (request, reply) => {
+    // Only load sites for authenticated users
+    if (!request.session?.user) {
+      return;
+    }
+
+    reply.locals = reply.locals || {};
+
+    try {
+      const sites = await Site.findAll({
+        attributes: ['id', 'name'],
+        order: [['name', 'ASC']]
+      });
+      reply.locals.sites = sites;
+      reply.locals.currentSite = request.session.currentSite || null;
+    } catch (error) {
+      fastify.log.error('Error loading sites:', error);
+      reply.locals.sites = [];
+      reply.locals.currentSite = null;
+    }
+  });
+
+  /**
+   * Helper to set current site from route param
+   */
+  function setCurrentSite(request, reply) {
+    if (request.params.siteId) {
+      request.session.currentSite = parseInt(request.params.siteId, 10);
+      reply.locals = reply.locals || {};
+      reply.locals.currentSite = request.session.currentSite;
+    }
+  }
+
+  fastify.decorate('setCurrentSite', setCurrentSite);
+}
+
+module.exports = fp(loadSitesPlugin, {
+  name: 'load-sites',
+  dependencies: ['@fastify/session']
+});