underpost 3.2.80 → 3.3.0

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,
+};

package/src/server/underpost-compression.js

@@ -0,0 +1,186 @@
+/**
+ * Response compression policy for the Nginx workloads on the request path.
+ *
+ * @module src/server/underpost-compression.js
+ * @namespace UnderpostCompression
+ */
+
+/**
+ * @constant UNDERPOST_COMPRESSION
+ * @description The compression policy both edge workloads render from.
+ *
+ * `text/html` appears in no type list on purpose: nginx and ngx_brotli both
+ * always compress it, and naming it again only invites the two lists to drift.
+ * Every entry is a format that is still text on the wire — already-compressed
+ * media (png, woff2, mp4) is excluded, since re-encoding it spends CPU to add
+ * bytes.
+ * @memberof UnderpostCompression
+ */
+const UNDERPOST_COMPRESSION = {
+  types: [
+    'application/atom+xml',
+    'application/geo+json',
+    'application/javascript',
+    'application/json',
+    'application/ld+json',
+    'application/manifest+json',
+    'application/rss+xml',
+    'application/vnd.api+json',
+    'application/wasm',
+    'application/x-javascript',
+    'application/xhtml+xml',
+    'application/xml',
+    'font/otf',
+    'font/ttf',
+    'image/svg+xml',
+    'image/x-icon',
+    'text/css',
+    'text/javascript',
+    'text/markdown',
+    'text/plain',
+    'text/xml',
+  ],
+  // Below roughly this size a compressed body plus its headers is no smaller
+  // than the original, and can be larger.
+  minLength: 512,
+  // Level 5 of 9: within a few percent of maximum ratio at a fraction of the
+  // CPU. The edge compresses every response of every host, so the cost of a
+  // higher level is paid on the shared workload, not on one deploy.
+  gzipLevel: 5,
+  // Brotli's scale runs to 11, where dynamic compression becomes slower than
+  // the transfer it saves. 5 is the usual on-the-fly ceiling.
+  brotliLevel: 5,
+  filterModule: 'ngx_http_brotli_filter_module.so',
+  staticModule: 'ngx_http_brotli_static_module.so',
+  defaultImage: 'nginx:alpine',
+  env: {
+    image: 'UNDERPOST_NGINX_IMAGE',
+    brotliModules: 'UNDERPOST_NGINX_BROTLI_MODULES',
+    enabled: 'UNDERPOST_NGINX_COMPRESSION',
+  },
+};
+
+/**
+ * @method nginxImageFactory
+ * @description The image both edge workloads run.
+ *
+ * Resolved in one place because the two have to agree: they sit on the same
+ * request path, and brotli is a property of the image rather than of the
+ * config. An image carrying ngx_brotli is the only way the brotli directives
+ * below can be rendered at all.
+ * @returns {string} Container image reference.
+ * @memberof UnderpostCompression
+ */
+const nginxImageFactory = () =>
+  `${process.env[UNDERPOST_COMPRESSION.env.image] || ''}`.trim() || UNDERPOST_COMPRESSION.defaultImage;
+
+/**
+ * @method brotliModuleDirFactory
+ * @description Directory holding the brotli dynamic modules, or an empty string
+ * when the image is not declared to carry them.
+ *
+ * Empty is the default and the safe state: gzip alone, on a stock image, with
+ * no `load_module` line that could fail to resolve.
+ * @returns {string} Absolute directory path, or `''`.
+ * @memberof UnderpostCompression
+ */
+const brotliModuleDirFactory = () =>
+  `${process.env[UNDERPOST_COMPRESSION.env.brotliModules] || ''}`.trim().replace(/\/+$/, '');
+
+/**
+ * @method compressionEnabledFactory
+ * @description Whether responses are compressed at all.
+ *
+ * The escape hatch for a CPU-bound edge node: compression trades cycles for
+ * bytes, and an operator who is out of the former rather than the latter needs
+ * to turn it off without editing generated configuration.
+ * @returns {boolean} True unless explicitly disabled.
+ * @memberof UnderpostCompression
+ */
+const compressionEnabledFactory = () =>
+  !['off', '0', 'false', 'no'].includes(`${process.env[UNDERPOST_COMPRESSION.env.enabled] || ''}`.trim().toLowerCase());
+
+/**
+ * @method compressionModulesConfFactory
+ * @description The `load_module` lines brotli needs, in nginx's main context.
+ *
+ * Rendered only alongside the brotli directives that require them, so a config
+ * never loads a module it does not use or uses one it did not load — using one
+ * that was not loaded is a start-up failure, and the reverse is surface on a
+ * workload that has no documents to serve from it.
+ * @param {string} [brotliModuleDir] - Directory holding the modules; empty renders nothing.
+ * @param {boolean} [enabled] - Whether compression is on at all.
+ * @param {boolean} [staticRoot] - Whether the workload serves documents from disk.
+ * @returns {string} Main-context directives, or an empty string.
+ * @memberof UnderpostCompression
+ */
+const compressionModulesConfFactory = ({
+  brotliModuleDir = brotliModuleDirFactory(),
+  enabled = compressionEnabledFactory(),
+  staticRoot = false,
+} = {}) => {
+  if (!enabled || !brotliModuleDir) return '';
+  return [
+    `load_module ${brotliModuleDir}/${UNDERPOST_COMPRESSION.filterModule};`,
+    ...(staticRoot ? [`load_module ${brotliModuleDir}/${UNDERPOST_COMPRESSION.staticModule};`] : []),
+  ].join('\n');
+};
+
+/**
+ * @method compressionConfFactory
+ * @description The compression block for an nginx `http` context.
+ *
+ * `gzip_proxied any` is what makes this worth rendering on a reverse proxy at
+ * all: the default is `off`, which suppresses compression for exactly the
+ * responses these workloads exist to forward. A response the upstream already
+ * encoded is passed through untouched either way — nginx never re-compresses
+ * one that carries `Content-Encoding`.
+ *
+ * `*_static` is only rendered where a document root exists. It costs one stat()
+ * per request to serve an operator-placed `.gz`/`.br` sibling with no CPU at
+ * all, and has nothing to look for on a workload that serves no files.
+ * @param {boolean} [enabled] - Whether compression is on at all.
+ * @param {string} [brotliModuleDir] - Directory holding the brotli modules; empty renders gzip alone.
+ * @param {boolean} [staticRoot] - Whether the workload serves documents from disk.
+ * @param {string} [indent] - Leading whitespace for each line.
+ * @returns {string} `http`-context directives, or an empty string.
+ * @memberof UnderpostCompression
+ */
+const compressionConfFactory = ({
+  enabled = compressionEnabledFactory(),
+  brotliModuleDir = brotliModuleDirFactory(),
+  staticRoot = false,
+  indent = '  ',
+} = {}) => {
+  if (!enabled) return '';
+  const types = UNDERPOST_COMPRESSION.types.join(' ');
+  const lines = [
+    'gzip on;',
+    // Compressed and uncompressed bodies share a URL, so a cache that ignores
+    // this header serves one to a client that asked for the other.
+    'gzip_vary on;',
+    `gzip_comp_level ${UNDERPOST_COMPRESSION.gzipLevel};`,
+    `gzip_min_length ${UNDERPOST_COMPRESSION.minLength};`,
+    'gzip_proxied any;',
+    `gzip_types ${types};`,
+    ...(staticRoot ? ['gzip_static on;'] : []),
+  ];
+  if (brotliModuleDir)
+    lines.push(
+      'brotli on;',
+      `brotli_comp_level ${UNDERPOST_COMPRESSION.brotliLevel};`,
+      `brotli_min_length ${UNDERPOST_COMPRESSION.minLength};`,
+      `brotli_types ${types};`,
+      ...(staticRoot ? ['brotli_static on;'] : []),
+    );
+  return lines.map((line) => `${indent}${line}`).join('\n');
+};
+
+export {
+  UNDERPOST_COMPRESSION,
+  brotliModuleDirFactory,
+  compressionConfFactory,
+  compressionEnabledFactory,
+  compressionModulesConfFactory,
+  nginxImageFactory,
+};