underpost 2.8.881 → 2.8.883

package/src/server/crypto.js

@@ -1,91 +1,210 @@
+/**
+ * Module for managing crypto operations
+ * @module src/server/crypto.js
+ * @namespace Crypto
+ */
+
 import crypto from 'crypto';
-import fs from 'fs-extra';
-
-const CryptoBuilder = {
-  symmetric: {
-    instance: function (options = { iv: '', encryptionKey: '' }) {
-      // Generate a random 32-byte encryption key
-      const encryptionKey = option?.encryptionKey ? options.encryptionKey : crypto.randomBytes(32);
-      const iv = option?.iv ? options.iv : crypto.randomBytes(16); // Generate a new Initialization Vector (IV) for each encryption
-
-      // Function to encrypt data
-      function encryptData(plaintext = '') {
-        const cipher = crypto.createCipheriv('aes-256-cbc', encryptionKey, iv);
-        let encrypted = cipher.update(plaintext, 'utf8', 'hex');
-        encrypted += cipher.final('hex');
-        return `${iv.toString('hex')}:${encrypted}`;
+
+/* ----------------------------- SymmetricCrypto ----------------------------- */
+
+class SymmetricCrypto {
+  #encryptionKey;
+
+  /**
+   * @param {object} [options]
+   * @param {Buffer | string} [options.encryptionKey] - 32-byte key as Buffer or hex string. If not provided, a new random key is generated.
+   */
+  /** @memberof Crypto */
+  constructor(options = {}) {
+    const { encryptionKey } = options;
+
+    if (encryptionKey) {
+      this.#encryptionKey = typeof encryptionKey === 'string' ? Buffer.from(encryptionKey, 'hex') : encryptionKey;
+    } else {
+      this.#encryptionKey = crypto.randomBytes(32);
+    }
+
+    if (!Buffer.isBuffer(this.#encryptionKey) || this.#encryptionKey.length !== 32) {
+      throw new Error('Encryption key must be a 32-byte Buffer or 64-length hex string.');
+    }
+
+    // Provide a compatibility IV property expected by some test suites / legacy code.
+    // This IV is not reused for each encryption operation (encryptData will generate its own IV).
+    // It exists so tests that expect an ivHex on the instance (16 bytes) continue to work.
+    this.ivHex = crypto.randomBytes(16).toString('hex'); // 16 bytes -> 32 hex chars
+  }
+
+  /** Returns encryption key as hex. */
+  /** @memberof Crypto */
+  get encryptionKeyHex() {
+    return this.#encryptionKey.toString('hex');
+  }
+
+  /**
+   * Encrypts plaintext using AES-256-GCM and returns `iv_hex:ciphertext_hex:authTag_hex`.
+   *
+   * @param {string} [plaintext='']
+   * @returns {string}
+   * @memberof Crypto
+   */
+  encryptData(plaintext = '') {
+    // GCM recommended IV size is 12 bytes
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', this.#encryptionKey, iv);
+
+    const encryptedPart = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+
+    return `${iv.toString('hex')}:${encryptedPart.toString('hex')}:${authTag.toString('hex')}`;
+  }
+
+  /**
+   * Decrypts data. Supports two formats:
+   *  - AES-256-GCM: `iv_hex:ciphertext_hex:authTag_hex` (preferred)
+   *  - Legacy AES-256-CBC: `iv_hex:ciphertext_hex` (fallback for backward compatibility)
+   *
+   * @param {string} [ciphertext='']
+   * @returns {string} plaintext
+   * @throws {Error} Generic error on failure (to avoid leaking details).
+   * @memberof Crypto
+   */
+  decryptData(ciphertext = '') {
+    try {
+      const parts = ciphertext.split(':');
+
+      if (parts.length === 3) {
+        // AES-256-GCM
+        const [ivHex, encryptedHex, tagHex] = parts;
+        const iv = Buffer.from(ivHex, 'hex');
+        const encrypted = Buffer.from(encryptedHex, 'hex');
+        const authTag = Buffer.from(tagHex, 'hex');
+
+        const decipher = crypto.createDecipheriv('aes-256-gcm', this.#encryptionKey, iv);
+        decipher.setAuthTag(authTag);
+
+        const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+        return decrypted.toString('utf8');
       }
 
-      // Function to decrypt data
-      function decryptData(ciphertext = '') {
-        const [ivHex, encrypted] = ciphertext.split(':');
-        const _iv = Buffer.from(ivHex, 'hex');
-        const decipher = crypto.createDecipheriv('aes-256-cbc', encryptionKey, _iv);
+      if (parts.length === 2) {
+        // Legacy: AES-256-CBC (no authentication). Provided for compatibility only.
+        const [ivHex, encryptedHex] = parts;
+        const iv = Buffer.from(ivHex, 'hex');
+        const encrypted = encryptedHex;
+
+        const decipher = crypto.createDecipheriv('aes-256-cbc', this.#encryptionKey, iv);
         let decrypted = decipher.update(encrypted, 'hex', 'utf8');
         decrypted += decipher.final('utf8');
         return decrypted;
       }
 
-      return {
-        encryptionKey,
-        iv,
-        encryptData,
-        decryptData,
-      };
-    },
-  },
-  asymmetric: {
-    instance: function (
-      options = {
-        publicKey: '', // fs.readFileSync('./key.pem', 'utf8')
-        privateKey: '', // fs.readFileSync('./key.pem', 'utf8')
-      },
-    ) {
-      // Generate a new key pair
-      const { privateKey, publicKey } = options
-        ? options
-        : crypto.generateKeyPairSync('rsa', {
-            modulusLength: 2048, // Key size in bits
-            publicKeyEncoding: {
-              type: 'spki',
-              format: 'pem',
-            },
-            privateKeyEncoding: {
-              type: 'pkcs8',
-              format: 'pem',
-            },
-          });
-
-      // Function to encrypt data
-      function encryptData(plaintext) {
-        const buffer = Buffer.from(plaintext, 'utf8');
-        const encrypted = crypto.publicEncrypt(publicKey, buffer);
-        return encrypted.toString('hex');
-      }
+      throw new Error('Invalid ciphertext format.');
+    } catch (err) {
+      // Do not leak internal error details (stack, key material, etc.).
+      // Optional: instrument monitoring/logging but avoid logging sensitive inputs.
+      throw new Error('Decryption failed. Check key, IV, or ciphertext integrity.');
+    }
+  }
+}
 
-      // Function to decrypt data
-      function decryptData(ciphertext) {
-        const buffer = Buffer.from(ciphertext, 'hex');
-        const decrypted = crypto.privateDecrypt(privateKey, buffer);
-        return decrypted.toString('utf8');
+/* ---------------------------- AsymmetricCrypto ---------------------------- */
+
+class AsymmetricCrypto {
+  #publicKey;
+  #privateKey;
+  #modulusLength;
+
+  /**
+   * @param {object} [options]
+   * @param {string|Buffer} [options.publicKey] - PEM-formatted public key
+   * @param {string|Buffer} [options.privateKey] - PEM-formatted private key
+   * @param {number} [options.modulusLength=2048] - If keys are not provided, generates a new key pair of this size (bits). Consider 3072 for long-lived keys.
+   */
+  /** @memberof Crypto */
+  constructor(options = {}) {
+    const { publicKey, privateKey } = options;
+    this.#modulusLength = options.modulusLength || 2048;
+
+    if (!publicKey || !privateKey) {
+      // Generate an in-memory key pair. No file I/O; keys remain in process memory only.
+      const { publicKey: pub, privateKey: priv } = crypto.generateKeyPairSync('rsa', {
+        modulusLength: this.#modulusLength,
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+      });
+      this.#publicKey = pub;
+      this.#privateKey = priv;
+    } else {
+      // Accept provided keys (string or Buffer)
+      this.#publicKey = typeof publicKey === 'string' || Buffer.isBuffer(publicKey) ? publicKey : String(publicKey);
+      this.#privateKey =
+        typeof privateKey === 'string' || Buffer.isBuffer(privateKey) ? privateKey : String(privateKey);
+
+      // Basic validation: ensure PEM headers exist. This is intentionally lightweight.
+      const pubStr = String(this.#publicKey);
+      const privStr = String(this.#privateKey);
+      if (!pubStr.includes('BEGIN PUBLIC KEY') || !privStr.includes('BEGIN')) {
+        throw new Error('Provided keys do not appear to be valid PEM-formatted keys.');
       }
+    }
+  }
 
-      fs.writeFileSync('./public.pem', publicKey);
-      fs.writeFileSync('./private.pem', privateKey);
+  /** @memberof Crypto */
+  get publicKey() {
+    return this.#publicKey;
+  }
+
+  /** @memberof Crypto */
+  get privateKey() {
+    return this.#privateKey;
+  }
+
+  /**
+   * Encrypts plaintext using RSA-OAEP with SHA-256. Returns hex-encoded ciphertext.
+   * Note: RSA encryption is intended for small payloads. For larger data use hybrid encryption (encrypt a symmetric key and then use AES-GCM).
+   * @param {string} plaintext
+   * @returns {string} hex ciphertext
+   * @memberof Crypto
+   */
+  encryptData(plaintext) {
+    const buffer = Buffer.from(plaintext, 'utf8');
+    const encrypted = crypto.publicEncrypt(
+      {
+        key: this.#publicKey,
+        padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
+        oaepHash: 'sha256',
+      },
+      buffer,
+    );
 
-      const result = {
-        privateKey: fs.readFileSync('./public.pem', 'utf8'),
-        publicKey: fs.readFileSync('./private.pem', 'utf8'),
-        encryptData,
-        decryptData,
-      };
+    return encrypted.toString('hex');
+  }
 
-      fs.removeSync('./public.pem');
-      fs.removeSync('./private.pem');
+  /**
+   * Decrypts RSA-OAEP hex ciphertext and returns utf8 plaintext.
+   * @param {string} ciphertextHex
+   * @returns {string}
+   * @memberof Crypto
+   */
+  decryptData(ciphertextHex) {
+    try {
+      const buffer = Buffer.from(ciphertextHex, 'hex');
+      const decrypted = crypto.privateDecrypt(
+        {
+          key: this.#privateKey,
+          padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
+          oaepHash: 'sha256',
+        },
+        buffer,
+      );
 
-      return result;
-    },
-  },
-};
+      return decrypted.toString('utf8');
+    } catch (err) {
+      // Avoid leaking details about keys or ciphertext
+      throw new Error('Decryption failed. Check private key or ciphertext integrity.');
+    }
+  }
+}
 
-export { CryptoBuilder };
+export { SymmetricCrypto, AsymmetricCrypto };

package/src/server/peer.js

@@ -1,30 +1,72 @@
+/**
+ * Module for peerjs server management.
+ * Initializes and configures the PeerJS server instance, typically running
+ * alongside a main Node.js application.
+ *
+ * @module src/server/peer.js
+ * @namespace Peer
+ */
+
 import { PeerServer } from 'peer';
 import dotenv from 'dotenv';
 import { loggerFactory } from './logger.js';
-import fs from 'fs-extra';
 import UnderpostStartUp from './start.js';
 
 dotenv.config();
 
+/**
+ * Logger instance for this module, utilizing the framework's factory.
+ * @type {function(*): void}
+ * @memberof Peer
+ * @private
+ */
 const logger = loggerFactory(import.meta);
 
+// Documentation references:
 // https://github.com/peers/peerjs
 // https://github.com/peers/peerjs-server
 
+/**
+ * Creates and starts a configured PeerJS server instance.
+ *
+ * This function handles port configuration, CORS origins, and paths, then uses
+ * a listener factory to start the server.
+ *
+ * @async
+ * @function createPeerServer
+ * @memberof Peer
+ * @param {object} config - Configuration object for the PeerJS server setup.
+ * @param {number} config.port - The primary port on which the PeerJS server will listen.
+ * @param {number} [config.devPort] - Optional development port. If provided and in 'development' NODE_ENV, 'http://localhost:${devPort}' is added to allowed origins.
+ * @param {string[]} config.origins - An array of allowed domain origins for Cross-Origin Resource Sharing (CORS).
+ * @param {string} config.host - The host address the server is bound to (used internally for configuration).
+ * @param {string} config.path - The base path for the API. The PeerJS path ('/peer') will be appended to this.
+ * @returns {Promise<object>} A promise that resolves to an object containing the final configuration and the server instance.
+ * @returns {import('peer').IConfig} return.options - The final options object used to create the PeerServer.
+ * @returns {import('peer').Server} return.peerServer - The created and listening PeerServer instance (wrapped by the listening server factory).
+ * @returns {object} return.meta - The module's import meta object (`import.meta`).
+ */
 const createPeerServer = async ({ port, devPort, origins, host, path }) => {
-  if (process.env.NODE_ENV === 'development' && devPort) origins.push(`http://localhost:${devPort}`);
+  if (process.env.NODE_ENV === 'development' && devPort) {
+    logger.warn(`Adding development origin: http://localhost:${devPort}`);
+    origins.push(`http://localhost:${devPort}`);
+  }
+
   /** @type {import('peer').IConfig} */
   const options = {
     port,
+    // Ensure the path is correctly formatted, handling the root path case
     path: `${path === '/' ? '' : path}/peer`,
     corsOptions: {
       origin: origins,
     },
     proxied: true,
-    // key: fs.readFileSync(''),
-    // cert: fs.readFileSync(''),
-    // ca: fs.readFileSync(''),
+    // key: fs.readFileSync(''), // Example for HTTPS/SSL
+    // cert: fs.readFileSync(''), // Example for HTTPS/SSL
+    // ca: fs.readFileSync(''),   // Example for HTTPS/SSL
   };
+
+  // Use the framework's factory to listen on the server, ensuring graceful startup/shutdown
   const peerServer = UnderpostStartUp.API.listenServerFactory(() => PeerServer(options));
 
   return { options, peerServer, meta: import.meta };

package/src/server/process.js

@@ -1,8 +1,14 @@
+/**
+ * Module for process and shell command management.
+ * Provides utilities for executing shell commands, managing signals, and handling environment details.
+ * @module src/server/process.js
+ * @namespace Process
+ */
+
 // https://nodejs.org/api/process
 
 import shell from 'shelljs';
 import dotenv from 'dotenv';
-import fs from 'fs-extra';
 import { loggerFactory } from './logger.js';
 import clipboard from 'clipboardy';
 import UnderpostRootEnv from '../cli/env.js';
@@ -11,9 +17,23 @@ dotenv.config();
 
 const logger = loggerFactory(import.meta);
 
+/**
+ * Gets the current working directory, replacing backslashes with forward slashes for consistency.
+ * @memberof Process
+ * @returns {string} The root directory path.
+ */
 const getRootDirectory = () => process.cwd().replace(/\\/g, '/');
 
+/**
+ * Controls and manages process-level events and signals.
+ * @namespace ProcessController
+ */
 const ProcessController = {
+  /**
+   * List of signals to listen for for graceful shutdown/handling.
+   * @memberof ProcessController
+   * @type {string[]}
+   */
   SIG: [
     'SIGPIPE',
     'SIGHUP',
@@ -28,6 +48,13 @@ const ProcessController = {
     'SIGSEGV',
     'SIGILL',
   ],
+
+  /**
+   * Sets up listeners for various process signals defined in {@link ProcessController.SIG}.
+   * Handles graceful exit on 'SIGINT' (Ctrl+C).
+   * @memberof ProcessController
+   * @returns {Array<process.Process>} An array of process listener handles.
+   */
   onSigListen: function () {
     return this.SIG.map((sig) =>
       process.on(sig, (...args) => {
@@ -42,6 +69,14 @@ const ProcessController = {
       }),
     );
   },
+
+  /**
+   * Initializes the ProcessController.
+   * Sets up signal listeners, registers a listener for the 'exit' event, and cleans up temporary deployment environment variables.
+   * @memberof ProcessController
+   * @param {Object} logger - The logger instance to use for internal logging.
+   * @returns {void}
+   */
   init: function (logger) {
     this.logger = logger;
     process.on('exit', (...args) => {
@@ -52,33 +87,82 @@ const ProcessController = {
   },
 };
 
+/**
+ * Executes a shell command using shelljs.
+ * @memberof Process
+ * @param {string} cmd - The command string to execute.
+ * @param {Object} [options] - Options for execution.
+ * @param {boolean} [options.silent=false] - Suppress output from shell commands.
+ * @param {boolean} [options.async=false] - Run command asynchronously.
+ * @param {boolean} [options.stdout=false] - Return stdout content (string) instead of shelljs result object.
+ * @param {boolean} [options.disableLog=false] - Prevent logging of the command.
+ * @returns {string|shelljs.ShellString} The result of the shell command (string if `stdout: true`, otherwise a ShellString object).
+ */
 const shellExec = (cmd, options = { silent: false, async: false, stdout: false, disableLog: false }) => {
   if (!options.disableLog) logger.info(`cmd`, cmd);
   return options.stdout ? shell.exec(cmd, options).stdout : shell.exec(cmd, options);
 };
 
+/**
+ * Changes the current working directory using shelljs.
+ * @memberof Process
+ * @param {string} cd - The path to change the directory to.
+ * @param {Object} [options] - Options for the CD operation.
+ * @param {boolean} [options.disableLog=false] - Prevent logging of the CD command.
+ * @returns {shelljs.ShellString} The result of the shelljs cd command.
+ */
 const shellCd = (cd, options = { disableLog: false }) => {
   if (!options.disableLog) logger.info(`cd`, cd);
   return shell.cd(cd);
 };
 
+/**
+ * Opens a new GNOME terminal and executes a command.
+ * Note: This function is environment-specific (GNOME/Linux).
+ * @memberof Process
+ * @param {string} cmd - The command to execute in the new terminal.
+ * @param {Object} [options] - Options for the terminal opening.
+ * @param {boolean} [options.single=false] - If true, execute as a single session process using `setsid`.
+ * @returns {void}
+ */
 const openTerminal = (cmd, options = { single: false }) => {
   if (options.single === true) {
+    // Run as a single session process
     shellExec(`setsid gnome-terminal -- bash -ic "${cmd}; exec bash" >/dev/null 2>&1 &`);
     return;
   }
+  // Run asynchronously and disown
   shellExec(`gnome-terminal -- bash -c "${cmd}; exec bash" & disown`, {
     async: true,
     stdout: true,
   });
 };
 
+/**
+ * Wraps a command to run it as a daemon process in a shell (keeping the process alive/terminal open).
+ * @memberof Process
+ * @param {string} cmd - The command to daemonize.
+ * @returns {string} The shell command string for the daemon process.
+ */
 const daemonProcess = (cmd) => `exec bash -c '${cmd}; exec tail -f /dev/null'`;
 
+/**
+ * Retrieves the process ID (PID) of the most recently created gnome-terminal instance.
+ * Note: This function is environment-specific (GNOME/Linux) and uses `pgrep -n`.
+ * @memberof Process
+ * @returns {number} The PID of the last gnome-terminal process.
+ */
 // list all terminals: pgrep gnome-terminal
 // list last terminal: pgrep -n gnome-terminal
 const getTerminalPid = () => JSON.parse(shellExec(`pgrep -n gnome-terminal`, { stdout: true, silent: true }));
 
+/**
+ * Copies text content to the system clipboard using clipboardy.
+ * Logs the copied content for confirmation.
+ * @memberof Process
+ * @param {string} [data='🦄'] - The data to copy. Defaults to '🦄'.
+ * @returns {void}
+ */
 function pbcopy(data) {
   clipboard.writeSync(data || '🦄');
   logger.info(`copied to clipboard`, clipboard.readSync());

package/src/server/runtime.js

@@ -14,7 +14,6 @@ import { MailerProvider } from '../mailer/MailerProvider.js';
 import { DataBaseProvider } from '../db/DataBaseProvider.js';
 import { createPeerServer } from './peer.js';
 import { Lampp } from '../runtime/lampp/Lampp.js';
-import { Xampp } from '../runtime/xampp/Xampp.js';
 import { createValkeyConnection } from './valkey.js';
 import { applySecurity, authMiddlewareFactory } from './auth.js';
 import { getInstanceContext } from './conf.js';
@@ -99,6 +98,8 @@ const buildRuntime = async () => {
             return next();
           });
 
+          if (process.env.NODE_ENV === 'production') app.set('trust proxy', true);
+
           app.use((req, res, next) => {
             requestCounter.inc({
               instance: `${host}:${port}${path}`,
@@ -161,6 +162,15 @@ const buildRuntime = async () => {
             continue;
           }
 
+          // Flag swagger requests before security middleware is applied
+          const swaggerJsonPath = `./public/${host}${path === '/' ? path : `${path}/`}swagger-output.json`;
+          const swaggerPath = `${path === '/' ? `/api-docs` : `${path}/api-docs`}`;
+          if (fs.existsSync(swaggerJsonPath))
+            app.use(swaggerPath, (req, res, next) => {
+              res.locals.isSwagger = true;
+              next();
+            });
+
           // security
           applySecurity(app, {
             origin: origins.concat(
@@ -191,22 +201,14 @@ const buildRuntime = async () => {
           if (peer) currentPort++;
 
           if (!apiBaseHost) {
-            const swaggerJsonPath = `./public/${host}${path === '/' ? path : `${path}/`}swagger-output.json`;
             if (fs.existsSync(swaggerJsonPath)) {
-              // logger.info('Build swagger serve', swaggerJsonPath);
-
               const swaggerInstance =
                 (swaggerDoc) =>
                 (...args) =>
                   swaggerUi.setup(swaggerDoc)(...args);
-
               const swaggerDoc = JSON.parse(fs.readFileSync(swaggerJsonPath, 'utf8'));
-
-              app.use(
-                `${path === '/' ? `/api-docs` : `${path}/api-docs`}`,
-                swaggerUi.serve,
-                swaggerInstance(swaggerDoc),
-              );
+              const swaggerPath = `${path === '/' ? `/api-docs` : `${path}/api-docs`}`;
+              app.use(swaggerPath, swaggerUi.serve, swaggerInstance(swaggerDoc));
             }
 
             if (db && apis) await DataBaseProvider.load({ apis, host, path, db });
@@ -308,26 +310,6 @@ const buildRuntime = async () => {
             );
           }
           break;
-        case 'xampp':
-          {
-            const { disabled } = await Xampp.createApp({
-              port,
-              host,
-              path,
-              directory,
-              rootHostPath,
-              redirect,
-              redirectTarget,
-              resetRouter: currentPort === initPort,
-            });
-            if (disabled) continue;
-            await UnderpostStartUp.API.listenPortController(
-              UnderpostStartUp.API.listenServerFactory(),
-              port,
-              runningData,
-            );
-          }
-          break;
         default:
           break;
       }
@@ -335,7 +317,6 @@ const buildRuntime = async () => {
     }
   }
 
-  if (Xampp.enabled() && Xampp.router) Xampp.initService();
   if (Lampp.enabled() && Lampp.router) Lampp.initService();
 
   UnderpostStartUp.API.logRuntimeRouter();