underpost 2.8.884 → 2.8.886

package/src/server/proxy.js

@@ -1,3 +1,9 @@
+/**
+ * Manages the creation and configuration of the reverse proxy server,
+ * including handling HTTP/HTTPS listeners and routing based on host configuration.
+ * @module src/server/proxy.js
+ * @namespace ProxyService
+ */
 'use strict';
 
 import express from 'express';
@@ -5,7 +11,7 @@ import dotenv from 'dotenv';
 
 import { createProxyMiddleware } from 'http-proxy-middleware';
 import { loggerFactory, loggerMiddleware } from './logger.js';
-import { createSslServer, sslRedirectMiddleware } from './ssl.js';
+import { TLS } from './tls.js';
 import { buildPortProxyRouter, buildProxyRouter } from './conf.js';
 import UnderpostStartUp from './start.js';
 
@@ -13,81 +19,92 @@ dotenv.config();
 
 const logger = loggerFactory(import.meta);
 
-const buildProxy = async () => {
-  // default target
-
-  express().listen(process.env.PORT);
-
-  const proxyRouter = buildProxyRouter();
-
-  for (let port of Object.keys(proxyRouter)) {
-    port = parseInt(port);
-    const hosts = proxyRouter[port];
-    const proxyPath = '/';
-    const proxyHost = 'localhost';
-    const runningData = { host: proxyHost, path: proxyPath, client: null, runtime: 'nodejs', meta: import.meta };
-    const app = express();
-
-    // set logger
-    app.use(loggerMiddleware(import.meta));
-
-    // instance proxy options
-    // https://github.com/chimurai/http-proxy-middleware/tree/v2.0.4#readme
-
-    // proxy middleware options
-    /** @type {import('http-proxy-middleware/dist/types').Options} */
-    const options = {
-      ws: true,
-      // changeOrigin: true,
-      // autoRewrite: false,
-      target: `http://localhost:${process.env.PORT}`,
-      router: {},
-      xfwd: true, // adds x-forward headers
-      // preserveHeaderKeyCase: true,
-      // secure: true, warn validator
-      onProxyReq: (proxyReq, req, res, options) => {
-        // https://wtools.io/check-http-status-code
-        // http://nexodev.org
-        sslRedirectMiddleware(req, res, port, proxyRouter);
-      },
-      pathRewrite: {
-        // only add path
-        // '^/target-path': '/',
-      },
-    };
-    options.router = buildPortProxyRouter(port, proxyRouter);
-
-    const filter = false
-      ? (pathname, req) => {
-          // return pathname.match('^/api') && req.method === 'GET';
-          return true;
-        }
-      : proxyPath;
-    app.use(proxyPath, createProxyMiddleware(filter, options));
-
-    switch (process.env.NODE_ENV) {
-      case 'production':
-        switch (port) {
-          case 443:
-            const { ServerSSL } = await createSslServer(app, hosts);
-            await UnderpostStartUp.API.listenPortController(ServerSSL, port, runningData);
-            break;
-
-          default:
-            await UnderpostStartUp.API.listenPortController(app, port, runningData);
-
-            break;
-        }
-
-        break;
-
-      default:
-        await UnderpostStartUp.API.listenPortController(app, port, runningData);
-
-        break;
+/**
+ * Main class for building and running the proxy server.
+ * All utility methods are implemented as static to serve as a namespace container.
+ * @class Proxy
+ * @augments Proxy
+ * @memberof ProxyService
+ */
+class Proxy {
+  /**
+   * Initializes and starts the reverse proxy server for all configured ports and hosts.
+   * @async
+   * @static
+   * @memberof ProxyService
+   * @returns {Promise<void>}
+   * @memberof ProxyService
+   */
+  static async buildProxy() {
+    // Start a default Express listener on process.env.PORT (potentially unused, but ensures Express is initialized)
+    express().listen(process.env.PORT);
+
+    const proxyRouter = buildProxyRouter();
+
+    for (let port of Object.keys(proxyRouter)) {
+      port = parseInt(port);
+      const hosts = proxyRouter[port];
+      const proxyPath = '/';
+      const proxyHost = 'localhost';
+      const runningData = { host: proxyHost, path: proxyPath, client: null, runtime: 'nodejs', meta: import.meta };
+      const app = express();
+
+      // Set logger middleware
+      app.use(loggerMiddleware(import.meta));
+
+      // Proxy middleware options
+      /** @type {import('http-proxy-middleware/dist/types').Options} */
+      const options = {
+        ws: true, // Enable websocket proxying
+        target: `http://localhost:${process.env.PORT}`, // Default target (should be overridden by router)
+        router: {},
+        xfwd: true, // Adds x-forward headers (Host, Proto, etc.)
+        onProxyReq: (proxyReq, req, res, options) => {
+          // Use the static method from the TLS class for redirection logic
+          TLS.sslRedirectMiddleware(req, res, port, proxyRouter);
+        },
+        pathRewrite: {
+          // Add path rewrite rules here if necessary
+        },
+      };
+
+      options.router = buildPortProxyRouter(port, proxyRouter, { orderByPathLength: true });
+
+      const filter = proxyPath; // Use '/' as the general filter
+      app.use(proxyPath, createProxyMiddleware(filter, options));
+
+      // Determine which server to start (HTTP or HTTPS) based on port and environment
+      switch (process.env.NODE_ENV) {
+        case 'production':
+          switch (port) {
+            case 443:
+              // For port 443 (HTTPS), create the SSL server
+              const { ServerSSL } = await TLS.createSslServer(app, hosts);
+              await UnderpostStartUp.API.listenPortController(ServerSSL, port, runningData);
+              break;
+
+            default:
+              // For other ports in production, use standard HTTP
+              await UnderpostStartUp.API.listenPortController(app, port, runningData);
+              break;
+          }
+          break;
+
+        default:
+          // In non-production, always use standard HTTP listener
+          await UnderpostStartUp.API.listenPortController(app, port, runningData);
+          break;
+      }
+      logger.info('Proxy running', { port, options });
     }
-    logger.info('Proxy running', { port, options });
   }
-};
+}
 
-export { buildProxy };
+/**
+ * Backward compatibility export
+ * @type {function(): Promise<void>}
+ * @memberof ProxyService
+ */
+const buildProxy = Proxy.buildProxy;
+
+export { Proxy, buildProxy };

package/src/server/runtime.js

@@ -1,8 +1,9 @@
 /**
- * @namespace Runtime
- * @description The main runtime orchestrator responsible for reading configuration,
+ * The main runtime orchestrator responsible for reading configuration,
  * initializing services (Prometheus, Ports, DB, Mailer), and building the
  * specific server runtime for each host/path (e.g., nodejs, lampp).
+ * @module src/server/runtime.js
+ * @namespace Runtime
  */
 
 import fs from 'fs-extra';
@@ -27,11 +28,12 @@ const logger = loggerFactory(import.meta);
  *
  * @memberof Runtime
  * @returns {Promise<void>}
+ * @function buildRuntime
  */
 const buildRuntime = async () => {
   const deployId = process.env.DEPLOY_ID;
 
-  // 1. Initialize Prometheus Metrics
+  // Initialize Prometheus Metrics
   const collectDefaultMetrics = promClient.collectDefaultMetrics;
   collectDefaultMetrics();
 
@@ -45,16 +47,13 @@ const buildRuntime = async () => {
   const initPort = parseInt(process.env.PORT) + 1;
   let currentPort = initPort;
 
-  // 2. Load Configuration
+  // Load Configuration
   const confServer = JSON.parse(fs.readFileSync(`./conf/conf.server.json`, 'utf8'));
   const confSSR = JSON.parse(fs.readFileSync(`./conf/conf.ssr.json`, 'utf8'));
-  const singleReplicaHosts = [];
 
-  // 3. Iterate through hosts and paths
+  // Iterate through hosts and paths
   for (const host of Object.keys(confServer)) {
-    if (singleReplicaHosts.length > 0)
-      currentPort += singleReplicaHosts.reduce((accumulator, currentValue) => accumulator + currentValue.replicas, 0);
-
+    let singleReplicaOffsetPortCount = 0;
     const rootHostPath = `/public/${host}`;
     for (const path of Object.keys(confServer[host])) {
       confServer[host][path].port = newInstance(currentPort);
@@ -74,21 +73,19 @@ const buildRuntime = async () => {
         replicas,
         valkey,
         apiBaseHost,
+        useLocalSsl,
       } = confServer[host][path];
 
       // Calculate context data
-      const { redirectTarget, singleReplicaHost } = await getInstanceContext({
+      const { redirectTarget, singleReplicaOffsetPortSum } = await getInstanceContext({
+        deployId,
         redirect,
-        singleReplicaHosts,
         singleReplica,
         replicas,
       });
 
-      if (singleReplicaHost) {
-        singleReplicaHosts.push({
-          host,
-          replicas: replicas.length,
-        });
+      if (singleReplicaOffsetPortSum > 0) {
+        singleReplicaOffsetPortCount += singleReplicaOffsetPortSum;
         continue;
       }
 
@@ -103,10 +100,6 @@ const buildRuntime = async () => {
 
       switch (runtime) {
         case 'nodejs':
-          // The devApiPort is used for development CORS origin calculation
-          // It needs to account for the current port and potential peer server increment
-          const devApiPort = currentPort + (peer ? 2 : 1);
-
           logger.info('Build nodejs server runtime', `${host}${path}:${port}`);
 
           const { portsUsed } = await ExpressService.createApp({
@@ -117,6 +110,7 @@ const buildRuntime = async () => {
             apis,
             origins,
             directory,
+            useLocalSsl,
             ws,
             mailer,
             db,
@@ -124,7 +118,6 @@ const buildRuntime = async () => {
             peer,
             valkey,
             apiBaseHost,
-            devApiPort, // Pass the dynamically calculated dev API port
             redirectTarget,
             rootHostPath,
             confSSR,
@@ -161,6 +154,7 @@ const buildRuntime = async () => {
       }
       currentPort++;
     }
+    currentPort += singleReplicaOffsetPortCount;
   }
 
   if (Lampp.enabled() && Lampp.router) Lampp.initService();

package/src/server/ssr.js

@@ -1,7 +1,7 @@
 /**
  * Module for managing server side rendering
  * @module src/server/ssr.js
- * @namespace SSR
+ * @namespace ServerSideRendering
  */
 
 import fs from 'fs-extra';
@@ -23,7 +23,7 @@ const logger = loggerFactory(import.meta);
  * It reads the component file, formats it, and executes it in a sandboxed Node.js VM context to extract the component.
  * @param {string} [componentPath='./src/client/ssr/Render.js'] - The path to the SSR component file.
  * @returns {Promise<Function>} A promise that resolves to the SSR component function.
- * @memberof SSR
+ * @memberof ServerSideRendering
  */
 const ssrFactory = async (componentPath = `./src/client/ssr/Render.js`) => {
   const context = { SrrComponent: () => {}, npm_package_version: Underpost.version };
@@ -39,7 +39,7 @@ const ssrFactory = async (componentPath = `./src/client/ssr/Render.js`) => {
  * @param {object} req - The Express request object.
  * @param {string} html - The HTML string to sanitize.
  * @returns {string} The sanitized HTML string with nonces.
- * @memberof SSR
+ * @memberof ServerSideRendering
  */
 const sanitizeHtml = (res, req, html) => {
   const nonce = res.locals.nonce;
@@ -58,7 +58,7 @@ const sanitizeHtml = (res, req, html) => {
  * @param {string} options.rootHostPath - The root path for the host's public files.
  * @param {string} options.path - The base path for the instance.
  * @returns {Promise<{error500: Function, error400: Function}>} A promise that resolves to an object containing the 500 and 404 error handling middleware.
- * @memberof SSR
+ * @memberof ServerSideRendering
  */
 const ssrMiddlewareFactory = async ({ app, directory, rootHostPath, path }) => {
   const Render = await ssrFactory();

package/src/server/start.js

@@ -1,3 +1,9 @@
+/**
+ * Manages the startup and runtime configuration of Underpost applications.
+ * @module src/server/start.js
+ * @namespace UnderpostStartUp
+ */
+
 import UnderpostDeploy from '../cli/deploy.js';
 import fs from 'fs-extra';
 import { awaitDeployMonitor } from './conf.js';
@@ -7,8 +13,17 @@ import UnderpostRootEnv from '../cli/env.js';
 
 const logger = loggerFactory(import.meta);
 
+/**
+ * @class UnderpostStartUp
+ * @description Manages the startup and runtime configuration of Underpost applications.
+ * @memberof UnderpostStartUp
+ */
 class UnderpostStartUp {
   static API = {
+    /**
+     * Logs the runtime network configuration.
+     * @memberof UnderpostStartUp
+     */
     logRuntimeRouter: () => {
       const displayLog = {};
 
@@ -18,6 +33,12 @@ class UnderpostStartUp {
 
       logger.info('Runtime network', displayLog);
     },
+    /**
+     * Creates a server factory.
+     * @memberof UnderpostStartUp
+     * @param {Function} logic - The logic to execute when the server is listening.
+     * @returns {Object} An object with a listen method.
+     */
     listenServerFactory: (logic = async () => {}) => {
       return {
         listen: async (...args) => {
@@ -36,6 +57,15 @@ class UnderpostStartUp {
         },
       };
     },
+
+    /**
+     * Controls the listening port for a server.
+     * @memberof UnderpostStartUp
+     * @param {Object} server - The server to listen on.
+     * @param {number|string} port - The port number or colon for all ports.
+     * @param {Object} metadata - Metadata for the server.
+     * @returns {Promise<boolean>} A promise that resolves to true if the server is listening, false otherwise.
+     */
     listenPortController: async (server, port, metadata) =>
       new Promise((resolve) => {
         try {
@@ -79,6 +109,15 @@ class UnderpostStartUp {
         }
       }),
 
+    /**
+     * Starts a deployment.
+     * @memberof UnderpostStartUp
+     * @param {string} deployId - The ID of the deployment.
+     * @param {string} env - The environment of the deployment.
+     * @param {Object} options - Options for the deployment.
+     * @param {boolean} options.build - Whether to build the deployment.
+     * @param {boolean} options.run - Whether to run the deployment.
+     */
     async callback(deployId = 'dd-default', env = 'development', options = { build: false, run: false }) {
       if (options.build === true) await UnderpostStartUp.API.build(deployId, env);
       if (options.run === true) await UnderpostStartUp.API.run(deployId, env);

package/src/server/tls.js

@@ -0,0 +1,251 @@
+/**
+ * Provides utilities for managing, building, and serving SSL/TLS contexts,
+ * primarily using Certbot files and creating HTTPS servers.
+ * @module src/server/tls.js
+ * @namespace TransportLayerSecurity
+ */
+
+import fs from 'fs-extra';
+import https from 'https';
+import path from 'path';
+import dotenv from 'dotenv';
+import { loggerFactory } from './logger.js';
+
+dotenv.config();
+const logger = loggerFactory(import.meta);
+
+const DEFAULT_HOST = 'localhost';
+const SSL_BASE = (host = DEFAULT_HOST) => path.resolve(`./engine-private/ssl/${host}`);
+
+// Common filename candidates for certs/keys produced by various tools (mkcert, certbot, openssl scripts).
+const CERT_CANDIDATES = [
+  'fullchain.pem',
+  'cert.pem',
+  'ca_bundle.crt',
+  'crt.crt',
+  `${DEFAULT_HOST}.pem`,
+  `${DEFAULT_HOST}.crt`,
+  `${DEFAULT_HOST}-fullchain.pem`,
+];
+const KEY_CANDIDATES = [
+  'privkey.pem',
+  'key.key',
+  'private.key',
+  'key.pem',
+  `${DEFAULT_HOST}-key.pem`,
+  `${DEFAULT_HOST}.key`,
+];
+const ROOT_CANDIDATES = ['rootCA.pem', 'ca.pem', 'ca.crt', 'root.pem'];
+
+class TLS {
+  /**
+   * Look for existing SSL files under engine-private/ssl/<host> and return canonical paths.
+   * It attempts to be permissive: accepts cert-only, cert+ca, or fullchain.
+   * @param {string} host
+   * @returns {{key?:string, cert?:string, fullchain?:string, ca?:string, dir:string}}
+   * @memberof TransportLayerSecurity
+   */
+  static locateSslFiles(host = DEFAULT_HOST) {
+    const dir = SSL_BASE(host);
+    const result = { dir };
+
+    if (!fs.existsSync(dir)) {
+      logger.warn('SSL dir does not exist', { dir });
+      return result;
+    }
+
+    // find key
+    for (const name of KEY_CANDIDATES) {
+      const p = path.join(dir, name);
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+        result.key = p;
+        break;
+      }
+    }
+
+    // find fullchain first
+    for (const name of CERT_CANDIDATES) {
+      const p = path.join(dir, name);
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+        // treat fullchain.pem / ca_bundle.crt as fullchain if name indicates so
+        if (
+          ['fullchain.pem', 'ca_bundle.crt', `${host}-fullchain.pem`].includes(name) ||
+          name.endsWith('fullchain.pem')
+        ) {
+          result.fullchain = p;
+          result.cert = p; // fullchain will be used as cert when building context
+          break;
+        }
+        // otherwise candidate may be leaf cert
+        if (!result.cert) result.cert = p;
+      }
+    }
+
+    // find root/ca if not using fullchain
+    if (!result.fullchain) {
+      // check for direct ca bundle (cert + ca combined) names
+      const caCandidates = ROOT_CANDIDATES.concat(['ca_bundle.crt']);
+      for (const name of caCandidates) {
+        const p = path.join(dir, name);
+        if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+          result.ca = p;
+          break;
+        }
+      }
+      // if no dedicated ca found but cert looks like leaf and there is separate ca under other known names,
+      // try to detect cert + ca in a single file (not trivial) — we prefer explicit ca
+    }
+
+    return result;
+  }
+
+  /**
+   * Validate that a secure context can be built for host (key + cert or fullchain present)
+   * @param {string} host
+   * @returns {boolean}
+   * @memberof TransportLayerSecurity
+   */
+  static validateSecureContext(host = DEFAULT_HOST) {
+    const files = TLS.locateSslFiles(host);
+    return Boolean((files.key && files.cert) || (files.key && files.fullchain));
+  }
+
+  /**
+   * Build a Node.js https.createServer options object (key, cert, ca) for the given host.
+   * If a fullchain is available it will be used for cert and ca will be omitted (fullchain already includes chain).
+   * If separate cert + ca are found, they will be used accordingly.
+   * @param {string} host
+   * @returns {{key:string, cert:string, ca?:string}} options
+   * @memberof TransportLayerSecurity
+   */
+  static buildSecureContext(host = DEFAULT_HOST) {
+    const files = TLS.locateSslFiles(host);
+    if (!files.key) throw new Error(`SSL key not found for host ${host} (looked in ${files.dir})`);
+    if (!files.cert) throw new Error(`SSL certificate not found for host ${host} (looked in ${files.dir})`);
+
+    const key = fs.readFileSync(files.key, 'utf8');
+    const cert = fs.readFileSync(files.cert, 'utf8');
+
+    // If we have a root CA file (explicit) and cert is leaf-only, include ca
+    if (files.ca && files.ca !== files.cert) {
+      const ca = fs.readFileSync(files.ca, 'utf8');
+      return { key, cert, ca };
+    }
+
+    // If cert is fullchain (already contains chain), just return key/cert
+    return { key, cert };
+  }
+
+  /**
+   * Convenience: ensure default host directory exists and copy any matching cert/key files into it using canonical names.
+   * This is useful if your generator produced nonstandard names and you want to normalize them.
+   * The function will copy existing discovered files to: key.key, crt.crt, ca_bundle.crt when possible.
+   * @param {string} host
+   * @returns {boolean} true if at least key+cert exist after operation
+   * @memberof TransportLayerSecurity
+   */
+  static async buildLocalSSL(host = DEFAULT_HOST) {
+    const dir = SSL_BASE(host);
+    await fs.ensureDir(dir);
+    const files = TLS.locateSslFiles(host);
+
+    // If key+cert already exist under canonical names, done
+    const canonicalKey = path.join(dir, 'key.key');
+    const canonicalCert = path.join(dir, 'crt.crt');
+    const canonicalCa = path.join(dir, 'ca_bundle.crt');
+
+    try {
+      if (files.key && files.key !== canonicalKey) await fs.copy(files.key, canonicalKey, { overwrite: true });
+      if (files.cert && files.cert !== canonicalCert) await fs.copy(files.cert, canonicalCert, { overwrite: true });
+      if (files.ca && files.ca !== canonicalCa) await fs.copy(files.ca, canonicalCa, { overwrite: true });
+
+      // If we had a fullchain but not a separate ca, write fullchain also to ca_bundle if missing
+      if (files.fullchain && !fs.existsSync(canonicalCa)) {
+        await fs.copy(files.fullchain, canonicalCa, { overwrite: false });
+      }
+    } catch (err) {
+      logger.warn('buildLocalSSL copy step failed', { err: err.message });
+    }
+
+    return TLS.validateSecureContext(host);
+  }
+
+  /**
+   * Create an HTTPS server (first host) and/or attach SNI contexts for additional hosts.
+   * hosts param is an object whose keys are hostnames (e.g. { 'localhost': {...} }).
+   * Returns the created https.Server instance (or undefined if none created).
+   * @param {import('express').Application} app
+   * @param {Object<string, any>} hosts
+   * @returns {{ServerSSL?: https.Server}}
+   * @memberof TransportLayerSecurity
+   */
+  static async createSslServer(app, hosts = { [DEFAULT_HOST]: {} }) {
+    let server;
+    for (const host of Object.keys(hosts)) {
+      // ensure canonical files exist (copies where possible)
+      await TLS.buildLocalSSL(host);
+      if (!TLS.validate_secure_context_check(host)) {
+        // backward compatibility: some callers expect validateSecureContext
+        if (!TLS.validateSecureContext(host)) {
+          logger.error('Invalid SSL context, skipping host', { host });
+          continue;
+        }
+      }
+
+      // build secure context options
+      try {
+        const ctx = TLS.buildSecureContext(host);
+        if (!server) {
+          server = https.createServer(ctx, app);
+          logger.info('Created HTTPS server for host', { host });
+        } else {
+          server.addContext(host, ctx);
+          logger.info('Added SNI context for host', { host });
+        }
+      } catch (err) {
+        logger.error('Failed to build secure context', { host, message: err.message });
+      }
+    }
+
+    return { ServerSSL: server };
+  }
+
+  /**
+   * Middleware that redirects HTTP -> HTTPS in production for recognized hosts.
+   * Skips ACME challenge paths.
+   * @param {import('express').Request} req
+   * @param {import('express').Response} res
+   * @param {number} port
+   * @param {Object<string, any>} proxyRouter
+   * @returns {import('express').RequestHandler}
+   * @memberof TransportLayerSecurity
+   */
+  static sslRedirectMiddleware(req, res, port = 80, proxyRouter = {}) {
+    const sslRedirectUrl = `https://${req.headers.host}${req.url}`;
+    if (
+      process.env.NODE_ENV === 'production' &&
+      port !== 443 &&
+      !req.secure &&
+      !req.url.startsWith('/.well-known/acme-challenge') &&
+      proxyRouter[443] &&
+      Object.keys(proxyRouter[443]).find((host) => {
+        const [hostSSL] = host.split('/');
+        return sslRedirectUrl.match(hostSSL) && TLS.validateSecureContext(hostSSL);
+      })
+    ) {
+      return res.status(302).redirect(sslRedirectUrl);
+    }
+  }
+}
+
+// small helper for internal backward compatibility check name typo in older code
+TLS.validate_secure_context_check = TLS.validateSecureContext;
+
+// Backward compatibility exports
+const buildSSL = TLS.buildLocalSSL;
+const buildSecureContext = TLS.buildSecureContext;
+const validateSecureContext = TLS.validateSecureContext;
+const createSslServer = TLS.createSslServer;
+const sslRedirectMiddleware = TLS.sslRedirectMiddleware;
+
+export { TLS, buildSSL, buildSecureContext, validateSecureContext, createSslServer, sslRedirectMiddleware };