underpost 3.2.90 → 3.3.0

package/src/server/middlewares.js

@@ -2,6 +2,7 @@
  * Express middleware and controller/router helpers for engine APIs.
  *
  * @module src/server/middlewares.js
+ * @namespace Middlewares
  */
 
 import { loggerFactory } from './logger.js';
@@ -12,8 +13,11 @@ const logger = loggerFactory(import.meta);
 /**
  * The public-read CORS policy: reflect the request origin (or allow any)
  * and mark the resource embeddable cross-origin.
+ * @method setCrossOriginHeaders
  * @param {import('express').Request} req
  * @param {import('express').Response} res
+ * @returns {void}
+ * @memberof Middlewares
  */
 const setCrossOriginHeaders = (req, res) => {
   if (req && req.headers && req.headers.origin) res.set('Access-Control-Allow-Origin', req.headers.origin);
@@ -21,7 +25,15 @@ const setCrossOriginHeaders = (req, res) => {
   res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
 };
 
-/** Express middleware form of {@link setCrossOriginHeaders}. */
+/**
+ * Express middleware form of {@link setCrossOriginHeaders}.
+ * @method crossOriginMiddleware
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ * @returns {void}
+ * @memberof Middlewares
+ */
 const crossOriginMiddleware = (req, res, next) => {
   setCrossOriginHeaders(req, res);
   next();
@@ -31,7 +43,10 @@ const crossOriginMiddleware = (req, res, next) => {
  * Shallow request copy with `page`/`limit` parsed to integers.
  * `path` and `params` are copied explicitly because spreading an Express
  * request drops prototype getters.
+ * @method withParsedPagination
  * @param {import('express').Request} req
+ * @returns {import('express').Request} Request-like object with parsed pagination.
+ * @memberof Middlewares
  */
 const withParsedPagination = (req) => {
   const { page, limit } = req.query;
@@ -43,15 +58,35 @@ const withParsedPagination = (req) => {
   };
 };
 
+/**
+ * Sends the standard success response envelope.
+ * @method sendSuccess
+ * @param {import('express').Response} res
+ * @param {*} data - Response payload.
+ * @returns {import('express').Response} JSON response.
+ * @memberof Middlewares
+ */
 const sendSuccess = (res, data) => res.status(200).json({ status: 'success', data });
 
+/**
+ * Sends the standard error response envelope.
+ * @method sendError
+ * @param {import('express').Response} res
+ * @param {Error} error - Error to expose.
+ * @param {number} [status=400] - HTTP status code.
+ * @returns {import('express').Response} JSON response.
+ * @memberof Middlewares
+ */
 const sendError = (res, error, status = 400) => res.status(status).json({ status: 'error', message: error.message });
 
 /**
  * Binary response with cross-origin and content headers.
+ * @method sendBlob
  * @param {import('express').Request} req
  * @param {import('express').Response} res
  * @param {{ buffer: Buffer, mimetype: string, filename: string, disposition?: 'inline'|'attachment' }} blob
+ * @returns {import('express').Response} Completed binary response.
+ * @memberof Middlewares
  */
 const sendBlob = (req, res, { buffer, mimetype, filename, disposition = 'inline' }) => {
   setCrossOriginHeaders(req, res);
@@ -63,8 +98,11 @@ const sendBlob = (req, res, { buffer, mimetype, filename, disposition = 'inline'
 
 /**
  * Wraps a controller body with error logging and the error response envelope.
+ * @method controllerHandler
  * @param {(req, res, options) => Promise<any>} fn
  * @param {{ errorStatus?: number }} [config]
+ * @returns {Function} Async Express-compatible controller handler.
+ * @memberof Middlewares
  */
 const controllerHandler =
   (fn, { errorStatus = 400 } = {}) =>
@@ -80,8 +118,11 @@ const controllerHandler =
 /**
  * Builds a controller method that delegates to a service method and wraps the
  * result in the success envelope.
+ * @method serviceHandler
  * @param {(req, res, options) => Promise<any>} serviceFn
  * @param {{ errorStatus?: number, crossOrigin?: boolean, pagination?: boolean }} [config]
+ * @returns {Function} Async Express-compatible controller handler.
+ * @memberof Middlewares
  */
 const serviceHandler = (serviceFn, { errorStatus = 400, crossOrigin = false, pagination = false } = {}) =>
   controllerHandler(
@@ -96,14 +137,26 @@ const serviceHandler = (serviceFn, { errorStatus = 400, crossOrigin = false, pag
 /**
  * Builds a standard CRUD controller class (static post/get/put/delete) from a
  * service exposing the same methods. `get` parses pagination.
+ * @method buildCrudController
  * @param {{ post, get, put, delete }} service
  * @param {Object<string, Function>} [extend] - Extra or overriding static handlers.
+ * @returns {Function} CRUD controller class.
+ * @memberof Middlewares
  */
 const buildCrudController = (service, extend = {}) => {
+  /**
+   * Generated controller namespace containing static CRUD handlers.
+   * @class CrudController
+   * @memberof Middlewares
+   */
   class CrudController {
+    /** @static @memberof Middlewares */
     static post = serviceHandler(service.post);
+    /** @static @memberof Middlewares */
     static get = serviceHandler(service.get, { pagination: true });
+    /** @static @memberof Middlewares */
     static put = serviceHandler(service.put);
+    /** @static @memberof Middlewares */
     static delete = serviceHandler(service.delete);
   }
   Object.assign(CrudController, extend);
@@ -115,6 +168,7 @@ const buildCrudController = (service, extend = {}) => {
  * public reads, moderator-guarded writes, admin-guarded collection delete.
  * Custom routes must be registered before calling this (generic `/:id` routes
  * capture everything).
+ * @method registerCrudRoutes
  * @param {import('express').Router} router
  * @param {{ post, get, put, delete }} Controller
  * @param {import('../../api/types.js').RouterOptions} options
@@ -122,6 +176,7 @@ const buildCrudController = (service, extend = {}) => {
  *   Pass empty arrays for unguarded endpoints (e.g. player-written progress)
  *   or explicit guard chains (e.g. admin-only reads).
  * @returns {import('express').Router}
+ * @memberof Middlewares
  */
 const registerCrudRoutes = (router, Controller, options, { readGuards = [], writeGuards, deleteAllGuards } = {}) => {
   const write = writeGuards ?? [options.authMiddleware, moderatorGuard];

package/src/server/process.js

@@ -25,7 +25,6 @@ import shell from 'shelljs';
 import { loggerFactory } from './logger.js';
 import clipboard from 'clipboardy';
 import Underpost from '../index.js';
-import { getNpmRootPath } from './conf.js';
 const logger = loggerFactory(import.meta);
 /**
  * Gets the current working directory, replacing backslashes with forward slashes for consistency.

package/src/server/selinux.js

@@ -0,0 +1,185 @@
+/**
+ * SELinux policy, labeling, and enforcement command helpers.
+ *
+ * @module src/server/selinux.js
+ * @namespace SELinuxService
+ */
+'use strict';
+
+/**
+ * Main SELinux utility.
+ * @class SELinuxService
+ * @memberof SELinuxService
+ */
+class SELinuxService {
+  /** Shared container label every unprivileged container domain can read and write. */
+  static SHARED_CONTAINER_TYPE = 'container_file_t';
+
+  /**
+   * Quotes one shell argument used by generated SELinux commands.
+   * @param {*} value - Value to quote.
+   * @returns {string}
+   */
+  static shellArgumentFactory(value) {
+    return `'${`${value ?? ''}`.replaceAll("'", `'"'"'`)}'`;
+  }
+
+  /**
+   * Builds the Rocky/RHEL SELinux userspace installation command.
+   * @param {{sudo?: boolean}} [options]
+   * @returns {string}
+   */
+  static selinuxPackagesCommandFactory({ sudo = true } = {}) {
+    return `${sudo ? 'sudo ' : ''}dnf install -y policycoreutils policycoreutils-python-utils selinux-policy-targeted audit`;
+  }
+
+  /**
+   * Builds commands that make Enforcing mode persistent and active.
+   * @param {{sudo?: boolean, restorePaths?: string[]}} [options]
+   * @returns {string[]}
+   */
+  static selinuxEnforcingCommandsFactory({ sudo = true, restorePaths = [] } = {}) {
+    const prefix = sudo ? 'sudo ' : '';
+    return [
+      `if [ -f /etc/selinux/config ]; then ${prefix}sed -i -E 's/^SELINUX=.*/SELINUX=enforcing/' /etc/selinux/config; fi`,
+      // A host running with SELinux Disabled has an unlabeled filesystem, so the
+      // config flip alone would boot it into Enforcing with nothing labeled.
+      // `setenforce` cannot activate the mode from Disabled either: the switch
+      // completes on the next boot, and only after this relabel pass.
+      `if command -v getenforce >/dev/null 2>&1 && [ "$(getenforce)" = "Disabled" ]; then ${prefix}touch /.autorelabel; fi`,
+      ...(restorePaths.length > 0
+        ? [SELinuxService.selinuxRestoreconCommandFactory(restorePaths, { sudo })]
+        : []),
+      `if command -v getenforce >/dev/null 2>&1 && [ "$(getenforce)" != "Disabled" ]; then ${prefix}setenforce 1; fi`,
+    ];
+  }
+
+  /**
+   * Builds a command that restores policy-defined file contexts.
+   * @param {string|string[]} paths - Files or directories to label.
+   * @param {{recursive?: boolean, sudo?: boolean}} [options]
+   * @returns {string}
+   */
+  static selinuxRestoreconCommandFactory(paths, { recursive = true, sudo = true } = {}) {
+    const values = (Array.isArray(paths) ? paths : [paths]).filter(Boolean);
+    if (values.length === 0) throw new TypeError('selinuxRestoreconCommandFactory requires at least one path');
+    const operations = values
+      .map(SELinuxService.shellArgumentFactory)
+      .map(
+        (path) =>
+          `{ [ ! -e ${path} ] || ${sudo ? 'sudo ' : ''}restorecon ${recursive ? '-RF ' : ''}${path}; }`,
+      )
+      .join(' && ');
+    return `if command -v restorecon >/dev/null 2>&1; then ${operations}; fi`;
+  }
+
+  /**
+   * Builds an idempotent persistent file context mapping.
+   * @param {string} path - Directory or file prefix to map.
+   * @param {{type: string, sudo?: boolean}} options
+   * @returns {string}
+   */
+  static selinuxFileContextCommandFactory(path, { type, sudo = true } = {}) {
+    if (!path) throw new TypeError('selinuxFileContextCommandFactory requires a path');
+    if (!type) throw new TypeError('selinuxFileContextCommandFactory requires a type');
+    const prefix = sudo ? 'sudo ' : '';
+    const expression = SELinuxService.shellArgumentFactory(`${path}(/.*)?`);
+    return `if command -v selinuxenabled >/dev/null 2>&1 && selinuxenabled; then command -v semanage >/dev/null 2>&1 || { echo 'semanage is required for persistent file contexts' >&2; exit 1; }; ${prefix}semanage fcontext -a -t ${type} ${expression} 2>/dev/null || ${prefix}semanage fcontext -m -t ${type} ${expression}; fi`;
+  }
+
+  /**
+   * Builds persistent labeling commands for host paths bind-mounted into
+   * unprivileged containers. `container_t` cannot read the policy defaults of
+   * those trees (`kubernetes_file_t`, `var_lib_t`), and the mapping is
+   * registered before the files exist so entries created later inherit the
+   * shared label instead of requiring another relabel pass.
+   * @param {string|string[]} paths - Files or directories to share.
+   * @param {{sudo?: boolean}} [options]
+   * @returns {string[]}
+   */
+  static selinuxContainerSharedContextCommandsFactory(paths, { sudo = true } = {}) {
+    const values = (Array.isArray(paths) ? paths : [paths]).filter(Boolean);
+    if (values.length === 0)
+      throw new TypeError('selinuxContainerSharedContextCommandsFactory requires at least one path');
+    return [
+      ...values.map((path) =>
+        SELinuxService.selinuxFileContextCommandFactory(path, { type: SELinuxService.SHARED_CONTAINER_TYPE, sudo }),
+      ),
+      SELinuxService.selinuxRestoreconCommandFactory(values, { sudo }),
+    ];
+  }
+
+  /**
+   * Builds persistent labeling commands for an SSH directory.
+   * Standard /root and /home locations already have policy mappings; custom
+   * home locations receive an explicit ssh_home_t mapping.
+   * @param {{sshDirectory: string, sudo?: boolean}} options
+   * @returns {string[]}
+   */
+  static selinuxSshContextCommandsFactory({ sshDirectory, sudo = true } = {}) {
+    if (!sshDirectory) throw new TypeError('selinuxSshContextCommandsFactory requires sshDirectory');
+    const prefix = sudo ? 'sudo ' : '';
+    const standard = sshDirectory === '/root/.ssh' || /^\/home\/[^/]+\/\.ssh$/.test(sshDirectory);
+    const commands = [];
+    if (!standard) {
+      const expression = SELinuxService.shellArgumentFactory(`${sshDirectory}(/.*)?`);
+      commands.push(
+        `if command -v selinuxenabled >/dev/null 2>&1 && selinuxenabled; then command -v semanage >/dev/null 2>&1 || { echo 'semanage is required for a custom SSH home' >&2; exit 1; }; ${prefix}semanage fcontext -a -t ssh_home_t ${expression} 2>/dev/null || ${prefix}semanage fcontext -m -t ssh_home_t ${expression}; fi`,
+      );
+    }
+    commands.push(SELinuxService.selinuxRestoreconCommandFactory(sshDirectory, { sudo }));
+    return commands;
+  }
+
+  /**
+   * Builds an idempotent ssh_port_t assignment for a custom SSH port.
+   * @param {{port?: number|string, sudo?: boolean}} [options]
+   * @returns {string[]}
+   */
+  static selinuxSshPortCommandsFactory({ port = 22, sudo = true } = {}) {
+    const value = Number(port);
+    if (!Number.isInteger(value) || value < 1 || value > 65535) throw new RangeError('SSH port must be 1-65535');
+    if (value === 22) return [];
+    const prefix = sudo ? 'sudo ' : '';
+    return [
+      `if command -v selinuxenabled >/dev/null 2>&1 && selinuxenabled; then command -v semanage >/dev/null 2>&1 || { echo 'semanage is required for a custom SSH port' >&2; exit 1; }; ${prefix}semanage port -a -t ssh_port_t -p tcp ${value} 2>/dev/null || ${prefix}semanage port -m -t ssh_port_t -p tcp ${value}; fi`,
+    ];
+  }
+
+  /**
+   * Executes a generated command list.
+   * @param {string[]} [commands]
+   * @param {{execute: Function}} options
+   * @returns {*[]}
+   */
+  static runSELinuxCommands(commands = [], { execute } = {}) {
+    if (typeof execute !== 'function') throw new TypeError('runSELinuxCommands requires an executor');
+    return commands.map((command) => execute(command));
+  }
+}
+
+const {
+  runSELinuxCommands,
+  selinuxContainerSharedContextCommandsFactory,
+  selinuxEnforcingCommandsFactory,
+  selinuxFileContextCommandFactory,
+  selinuxPackagesCommandFactory,
+  selinuxRestoreconCommandFactory,
+  selinuxSshContextCommandsFactory,
+  selinuxSshPortCommandsFactory,
+  shellArgumentFactory,
+} = SELinuxService;
+
+export default SELinuxService;
+
+export {
+  runSELinuxCommands,
+  selinuxContainerSharedContextCommandsFactory,
+  selinuxEnforcingCommandsFactory,
+  selinuxFileContextCommandFactory,
+  selinuxPackagesCommandFactory,
+  selinuxRestoreconCommandFactory,
+  selinuxSshContextCommandsFactory,
+  selinuxSshPortCommandsFactory,
+  shellArgumentFactory,
+};

package/src/server/systemd.js

@@ -0,0 +1,205 @@
+/**
+ * General-purpose systemd unit rendering and service lifecycle helpers.
+ *
+ * Command construction is deterministic and separate from execution. Callers
+ * can execute commands explicitly or pass a list to {@link runSystemdCommands}.
+ *
+ * @module src/server/systemd.js
+ * @namespace SystemdService
+ */
+'use strict';
+
+/**
+ * Main systemd service utility.
+ * @class SystemdService
+ * @memberof SystemdService
+ */
+class SystemdService {
+  static #valuesFactory(value) {
+    return Array.isArray(value) ? value : [value];
+  }
+
+  static #sectionFactory(name, directives = {}) {
+    const lines = Object.entries(directives).flatMap(([directive, value]) =>
+      SystemdService.#valuesFactory(value)
+        .filter((entry) => entry !== undefined && entry !== null && `${entry}` !== '')
+        .map((entry) => `${directive}=${entry}`),
+    );
+    return lines.length > 0 ? [`[${name}]`, ...lines].join('\n') : '';
+  }
+
+  static #daemonReloadCommandFactory({ sudo = true } = {}) {
+    return SystemdService.systemctlCommandFactory({ action: 'daemon-reload', sudo });
+  }
+
+  /**
+   * Checks whether a path is inside a user home directory.
+   * @param {string} path - Candidate path.
+   * @returns {boolean}
+   */
+  static homeDirectoryPathFactory(path) {
+    return /^\/root(\/|$)|^\/home\//.test(`${path || ''}`.trim());
+  }
+
+  /**
+   * Renders a systemd unit from named sections and directives.
+   * @param {{header?: string, sections?: Object<string, Object<string, *>>}} [options]
+   * @returns {string}
+   */
+  static systemdUnitFactory({ header = '', sections = {} } = {}) {
+    const rendered = Object.entries(sections)
+      .map(([name, directives]) => SystemdService.#sectionFactory(name, directives))
+      .filter(Boolean);
+    return [...(`${header}`.trim() ? [`${header}`.trim()] : []), ...rendered].join('\n\n') + '\n';
+  }
+
+  /**
+   * Builds a systemctl command.
+   * @param {{action?: string, name?: string, sudo?: boolean, stderr?: boolean, allowFailure?: boolean}} [options]
+   * @returns {string}
+   */
+  static systemctlCommandFactory({ action, name = '', sudo = true, stderr = false, allowFailure = false } = {}) {
+    return [
+      sudo ? 'sudo' : '',
+      'systemctl',
+      `${action || ''}`.trim(),
+      `${name || ''}`.trim(),
+      stderr ? '2>/dev/null' : '',
+      allowFailure ? '|| true' : '',
+    ]
+      .filter(Boolean)
+      .join(' ');
+  }
+
+  /** @returns {string} Command that checks whether systemd-run is available. */
+  static systemdAvailableCommandFactory() {
+    return 'command -v systemd-run';
+  }
+
+  /**
+   * Builds a journalctl command for a service.
+   * @param {{name: string, lines?: number, follow?: boolean}} options
+   * @returns {string}
+   */
+  static journalctlCommandFactory({ name, lines, follow = false } = {}) {
+    return ['journalctl', '-u', name, lines ? `-n ${lines}` : '', follow ? '-f' : ''].filter(Boolean).join(' ');
+  }
+
+  /**
+   * Builds a transient systemd-run command.
+   * @param {{command?: string, user?: string, properties?: Object<string, *>, quiet?: boolean, collect?: boolean, wait?: boolean, sudo?: boolean}} [options]
+   * @returns {string}
+   */
+  static systemdRunCommandFactory({
+    command,
+    user,
+    properties = {},
+    quiet = true,
+    collect = true,
+    wait = true,
+    sudo = true,
+  } = {}) {
+    return [
+      sudo ? 'sudo' : '',
+      'systemd-run',
+      quiet ? '--quiet' : '',
+      collect ? '--collect' : '',
+      wait ? '--wait' : '',
+      user ? `--uid=${user}` : '',
+      ...Object.entries(properties).map(([name, value]) => `--property=${name}=${value}`),
+      `${command || ''}`.trim(),
+    ]
+      .filter(Boolean)
+      .join(' ');
+  }
+
+  /**
+   * Builds convergent ensure and remove command lists for a service.
+   * @param {{changed?: boolean, name: string, unitPath: string}} options
+   * @returns {{ensure: string[], remove: string[]}}
+   */
+  static systemdServiceCommandsFactory({ changed = false, name, unitPath } = {}) {
+    return {
+      ensure: [
+        ...(changed ? [SystemdService.#daemonReloadCommandFactory()] : []),
+        SystemdService.systemctlCommandFactory({ action: 'enable', name, allowFailure: true }),
+        SystemdService.systemctlCommandFactory({
+          action: changed ? 'restart' : 'start',
+          name,
+          allowFailure: true,
+        }),
+      ],
+      remove: [
+        SystemdService.systemctlCommandFactory({
+          action: 'disable --now',
+          name,
+          stderr: true,
+          allowFailure: true,
+        }),
+        `sudo rm -f ${unitPath}`,
+        SystemdService.#daemonReloadCommandFactory(),
+      ],
+    };
+  }
+
+  /**
+   * Builds service status and log commands.
+   * @param {string} name - Service name.
+   * @returns {{active: string, enabled: string, logs: string}}
+   */
+  static systemdStatusCommandsFactory(name) {
+    return {
+      active: SystemdService.systemctlCommandFactory({ action: 'is-active', name, sudo: false }),
+      enabled: SystemdService.systemctlCommandFactory({ action: 'is-enabled', name, sudo: false }),
+      logs: SystemdService.journalctlCommandFactory({ name }),
+    };
+  }
+
+  /**
+   * Builds a guarded reload command.
+   * @param {string} name - Service name.
+   * @returns {string}
+   */
+  static systemdReloadIfActiveCommandFactory(name) {
+    return `sudo sh -c 'systemctl is-active --quiet ${name} && systemctl reload ${name} || true'`;
+  }
+
+  /**
+   * Executes or reports a sequence of generated commands.
+   * @param {string[]} [commands]
+   * @param {{dryRun?: boolean, execute?: Function, onDryRun?: Function}} [options]
+   * @returns {*[]}
+   */
+  static runSystemdCommands(commands = [], { dryRun = false, execute, onDryRun = () => {} } = {}) {
+    if (!dryRun && typeof execute !== 'function') throw new TypeError('runSystemdCommands requires an executor');
+    return commands.map((command) => (dryRun ? onDryRun(command) : execute(command)));
+  }
+}
+
+const {
+  homeDirectoryPathFactory,
+  journalctlCommandFactory,
+  runSystemdCommands,
+  systemctlCommandFactory,
+  systemdAvailableCommandFactory,
+  systemdReloadIfActiveCommandFactory,
+  systemdRunCommandFactory,
+  systemdServiceCommandsFactory,
+  systemdStatusCommandsFactory,
+  systemdUnitFactory,
+} = SystemdService;
+
+export default SystemdService;
+
+export {
+  homeDirectoryPathFactory,
+  journalctlCommandFactory,
+  runSystemdCommands,
+  systemctlCommandFactory,
+  systemdAvailableCommandFactory,
+  systemdReloadIfActiveCommandFactory,
+  systemdRunCommandFactory,
+  systemdServiceCommandsFactory,
+  systemdStatusCommandsFactory,
+  systemdUnitFactory,
+};