underpost 3.2.30 → 3.2.80

package/src/cli/secrets.js

@@ -13,6 +13,58 @@ import { loggerFactory } from '../server/logger.js';
 
 const logger = loggerFactory(import.meta);
 
+// Shell/runtime-critical and Kubernetes-injected env keys that must never be persisted as
+// application secrets nor injected into a pod via `envFrom`. An injected PATH (or HOME, etc.)
+// overrides the container image's own and breaks coreutils/sudo resolution inside the pod
+// ("rm: command not found"). Single source of truth for both container-env capture and the
+// `underpost-config` secret built from an env file.
+const RESERVED_ENV_KEYS = new Set([
+  'HOME',
+  'HOSTNAME',
+  'PATH',
+  'TERM',
+  'SHLVL',
+  'PWD',
+  '_',
+  'LANG',
+  'LANGUAGE',
+  'LC_ALL',
+  'container',
+  'SHELL',
+  'USER',
+  'LOGNAME',
+  'MAIL',
+  'OLDPWD',
+  'LESSOPEN',
+  'LESSCLOSE',
+  'LS_COLORS',
+  'DISPLAY',
+  'COLORTERM',
+  'EDITOR',
+  'VISUAL',
+  'TERM_PROGRAM',
+  'TERM_PROGRAM_VERSION',
+  'SSH_AUTH_SOCK',
+  'SSH_CLIENT',
+  'SSH_CONNECTION',
+  'SSH_TTY',
+  'XDG_SESSION_ID',
+  'XDG_RUNTIME_DIR',
+  'XDG_DATA_DIRS',
+  'XDG_CONFIG_DIRS',
+  'DBUS_SESSION_BUS_ADDRESS',
+  'GPG_AGENT_INFO',
+  'WINDOWID',
+  'DESKTOP_SESSION',
+  'SESSION_MANAGER',
+  'XAUTHORITY',
+  'WAYLAND_DISPLAY',
+  'which_declare',
+]);
+const RESERVED_ENV_KEY_PREFIXES = ['KUBERNETES_', 'npm_', 'NODE_'];
+const isReservedEnvKey = (key) =>
+  RESERVED_ENV_KEYS.has(key) || RESERVED_ENV_KEY_PREFIXES.some((prefix) => key.startsWith(prefix));
+
 /**
  * @class UnderpostSecret
  * @description Manages the secrets of the application.
@@ -49,58 +101,35 @@ class UnderpostSecret {
        */
       createFromContainerEnv() {
         Underpost.env.clean();
-        const systemKeys = new Set([
-          'HOME',
-          'HOSTNAME',
-          'PATH',
-          'TERM',
-          'SHLVL',
-          'PWD',
-          '_',
-          'LANG',
-          'LANGUAGE',
-          'LC_ALL',
-          'container',
-          'SHELL',
-          'USER',
-          'LOGNAME',
-          'MAIL',
-          'OLDPWD',
-          'LESSOPEN',
-          'LESSCLOSE',
-          'LS_COLORS',
-          'DISPLAY',
-          'COLORTERM',
-          'EDITOR',
-          'VISUAL',
-          'TERM_PROGRAM',
-          'TERM_PROGRAM_VERSION',
-          'SSH_AUTH_SOCK',
-          'SSH_CLIENT',
-          'SSH_CONNECTION',
-          'SSH_TTY',
-          'XDG_SESSION_ID',
-          'XDG_RUNTIME_DIR',
-          'XDG_DATA_DIRS',
-          'XDG_CONFIG_DIRS',
-          'DBUS_SESSION_BUS_ADDRESS',
-          'GPG_AGENT_INFO',
-          'WINDOWID',
-          'DESKTOP_SESSION',
-          'SESSION_MANAGER',
-          'XAUTHORITY',
-          'WAYLAND_DISPLAY',
-          'which_declare',
-        ]);
-        const systemKeyPrefixes = ['KUBERNETES_', 'npm_', 'NODE_'];
         for (const [key, value] of Object.entries(process.env)) {
-          if (systemKeys.has(key)) continue;
-          if (systemKeyPrefixes.some((prefix) => key.startsWith(prefix))) continue;
+          if (isReservedEnvKey(key)) continue;
           Underpost.env.set(key, value);
         }
       },
     },
 
+    /**
+     * @method sanitizeSecretEnvFile
+     * @description Strips shell/runtime-critical and Kubernetes-injected keys (PATH, HOME, …) from
+     * raw `.env` file content so the resulting `underpost-config` secret can be safely injected via
+     * `envFrom` without clobbering the container image's own PATH. Blank lines and comments are
+     * preserved. Uses the same {@link RESERVED_ENV_KEYS} blocklist as container-env capture.
+     * @param {string} envFileContent - Raw contents of a `.env.<env>` file.
+     * @returns {string} Filtered env-file content.
+     * @memberof UnderpostSecret
+     */
+    sanitizeSecretEnvFile(envFileContent) {
+      return envFileContent
+        .split('\n')
+        .filter((line) => {
+          const trimmed = line.trimStart();
+          if (!trimmed || trimmed.startsWith('#')) return true;
+          const key = line.slice(0, line.indexOf('=')).trim();
+          return !key || !isReservedEnvKey(key);
+        })
+        .join('\n');
+    },
+
     /**
      * Removes all filesystem traces of secrets after deployment startup.
      * Centralizes the defense-in-depth cleanup performed

package/src/cli/ssh.js

@@ -532,12 +532,28 @@ EOF`);
       if (!host) throw new Error('copyDirToNode requires a host');
       if (!localDir || !fs.existsSync(localDir)) throw new Error(`copyDirToNode: local dir not found: ${localDir}`);
       if (!remoteDir) throw new Error('copyDirToNode requires a remoteDir');
-      shellExec(`chmod 600 ${keyPath}`, { silent: true, silentOnError: true, disableLog: true });
-      const sshOpts = `-i ${keyPath} -o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p ${port}`;
-      shellExec(`ssh ${sshOpts} ${user}@${host} 'mkdir -p ${remoteDir}'`);
-      shellExec(`tar -C ${localDir} -c . | ssh ${sshOpts} ${user}@${host} 'tar -C ${remoteDir} -x'`);
-      const fixups = `${owner ? `chown -R ${owner} ${remoteDir}; ` : ''}${mode ? `chmod -R ${mode} ${remoteDir}` : ''}`.trim();
-      if (fixups) shellExec(`ssh ${sshOpts} ${user}@${host} '${fixups}'`);
+      try {
+        shellExec(`chmod 600 ${keyPath}`, { silent: true, silentOnError: true, disableLog: true });
+        const sshOpts = `-i ${keyPath} -o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p ${port}`;
+        shellExec(`ssh ${sshOpts} ${user}@${host} 'mkdir -p ${remoteDir}'`, {
+          silent: true,
+          disableLog: true,
+        });
+        shellExec(`tar -C ${localDir} -c . | ssh ${sshOpts} ${user}@${host} 'tar -C ${remoteDir} -x'`, {
+          silent: true,
+          disableLog: true,
+        });
+        const fixups =
+          `${owner ? `chown -R ${owner} ${remoteDir}; ` : ''}${mode ? `chmod -R ${mode} ${remoteDir}` : ''}`.trim();
+        if (fixups)
+          shellExec(`ssh ${sshOpts} ${user}@${host} '${fixups}'`, {
+            silent: true,
+            disableLog: true,
+          });
+      } catch (err) {
+        logger.error(`copyDirToNode failed`);
+        process.exit(1);
+      }
     },
 
     /**
@@ -703,11 +719,14 @@ EOF
 
       let last = { ok: false, code: 255, stdout: '', stderr: '', attempts: 0 };
       for (let attempt = 1; attempt <= retries; attempt++) {
-        const result = shellExec(`ssh ${sshOpts} ${user}@${host} bash -s <<'UNDERPOST_SSH_BATCH_EOF'\n${command}\nUNDERPOST_SSH_BATCH_EOF`, {
-          stdout: false,
-          silentOnError: true,
-          disableLog: true,
-        });
+        const result = shellExec(
+          `ssh ${sshOpts} ${user}@${host} bash -s <<'UNDERPOST_SSH_BATCH_EOF'\n${command}\nUNDERPOST_SSH_BATCH_EOF`,
+          {
+            stdout: false,
+            silentOnError: true,
+            disableLog: true,
+          },
+        );
         last = {
           ok: result.code === 0,
           code: result.code,

package/src/client/components/core/Modal.js

@@ -425,8 +425,8 @@ class Modal {
               s(`.main-body-btn-ui-menu-menu`).classList.add('hide');
               s(`.main-body-btn-ui-menu-close`).classList.remove('hide');
               if (s(`.btn-bar-center-icon-menu`)) {
-                s(`.btn-bar-center-icon-close`).classList.remove('hide');
-                s(`.btn-bar-center-icon-menu`).classList.add('hide');
+                sa(`.btn-bar-center-icon-close`).forEach((el) => el.classList.remove('hide'));
+                sa(`.btn-bar-center-icon-menu`).forEach((el) => el.classList.add('hide'));
               }
 
               s(`.main-body-btn-container`).style[
@@ -449,8 +449,8 @@ class Modal {
               s(`.main-body-btn-ui-menu-close`).classList.add('hide');
               s(`.main-body-btn-ui-menu-menu`).classList.remove('hide');
               if (s(`.btn-bar-center-icon-menu`)) {
-                s(`.btn-bar-center-icon-menu`).classList.remove('hide');
-                s(`.btn-bar-center-icon-close`).classList.add('hide');
+                sa(`.btn-bar-center-icon-menu`).forEach((el) => el.classList.remove('hide'));
+                sa(`.btn-bar-center-icon-close`).forEach((el) => el.classList.add('hide'));
               }
               s(`.main-body-btn-container`).style[
                 true || (options.mode && options.mode.match('right')) ? 'right' : 'left'
@@ -683,6 +683,34 @@ class Modal {
                       >
                     </div>`
                   : ''}
+                ${idModal === 'modal-menu' && options.mode !== 'slide-menu-right'
+                  ? html`<div
+                        class="abs main-btn-menu-top-container"
+                        style="bottom: 0px; left: 0px; z-index: 10; height: ${originHeightTopBar}px; width: ${originHeightTopBar}px"
+                      >
+                        ${await BtnIcon.instance({
+                          style: `height: 100%`,
+                          class: `in fll main-btn-menu-top action-bar-box action-btn-center-top`,
+                          label: html`<div class="abs center">
+                            <i class="far fa-square btn-bar-center-icon-square hide"></i>
+                            <span class="btn-bar-center-icon-close hide">${barConfig.buttons.close.label}</span>
+                            <span class="btn-bar-center-icon-menu">${barConfig.buttons.menu.label}</span>
+                          </div>`,
+                        })}
+                      </div>
+
+                      <style>
+                        .a-link-top-banner {
+                          padding-left: 35px;
+                        }
+                        .main-body-btn-bar-custom {
+                          top: 50px !important;
+                        }
+                        .main-body-btn-menu {
+                          display: none;
+                        }
+                      </style>`
+                  : ''}
               </div>`,
             );
             EventsUI.onClick(`.action-btn-profile-log-in`, () => {
@@ -697,6 +725,12 @@ class Modal {
               }
               s(`.main-btn-sign-up`).click();
             });
+            if (idModal === 'modal-menu' && options.mode !== 'slide-menu-right') {
+              EventsUI.onClick(`.action-btn-center-top`, (e) => {
+                e.preventDefault();
+                Modal.actionBtnCenter();
+              });
+            }
             s(`.input-info-${inputSearchBoxId}`).style.textAlign = 'left';
             htmls(`.input-info-${inputSearchBoxId}`, '');
             const inputInfoNode = s(`.input-info-${inputSearchBoxId}`).cloneNode(true);

package/src/index.js

@@ -45,7 +45,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v3.2.30';
+  static version = 'v3.2.80';
 
   /**
    * Required Node.js major version

package/src/server/catalog.js

@@ -24,6 +24,8 @@ const EMPTY_CATALOG = {
   privateConfPaths: [],
   templatePaths: [],
   stripPaths: [],
+  moves: [],
+  copies: [],
   keywords: [],
   description: '',
 };

package/src/server/conf.js

@@ -476,9 +476,6 @@ const loadConf = (deployId = DEFAULT_DEPLOY_ID, subConf) => {
     fs.removeSync(`${path}/.env.production`);
     fs.removeSync(`${path}/.env.development`);
     fs.removeSync(`${path}/.env.test`);
-    if (fs.existsSync(`${path}/typedoc.json`)) shellExec(`git checkout ${path}/typedoc.json`);
-    shellExec(`git checkout ${path}/package.json`);
-    shellExec(`git checkout ${path}/package-lock.json`);
     return;
   }
   const folder = getConfFolder(deployId);
@@ -1775,6 +1772,165 @@ const loadConfServerJson = (jsonPath, options) => {
   return options && options.resolve === true ? resolveConfSecrets(raw) : raw;
 };
 
+/**
+ * @method deepReplaceToken
+ * @description Recursively replaces every occurrence of `from` with `to` in all
+ * string leaves of a JSON-shaped value, returning a new structure.
+ * @param {*} value - Any JSON-serialisable value.
+ * @param {string} from - Token to replace.
+ * @param {string} to - Replacement token.
+ * @returns {*} A structurally identical value with the token replaced.
+ * @memberof ServerConfBuilder
+ */
+const deepReplaceToken = (value, from, to) => {
+  if (typeof value === 'string') return value.split(from).join(to);
+  if (Array.isArray(value)) return value.map((entry) => deepReplaceToken(entry, from, to));
+  if (value && typeof value === 'object')
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, deepReplaceToken(v, from, to)]));
+  return value;
+};
+
+/**
+ * @method readConfInstances
+ * @description Reads `conf.instances.json` and returns the bare array of instance
+ * entries. The canonical shape is a plain array; the historical `{ instances }`
+ * object wrapper is still unwrapped for backward compatibility. Multi-instance is
+ * declared per entry under `entry.multiInstance` (not deploy-wide).
+ * @param {string} deployId - Deployment identifier (e.g. `dd-cyberia`).
+ * @returns {Array<object>} Instance entries.
+ * @memberof ServerConfBuilder
+ */
+const readConfInstances = (deployId) => {
+  const raw = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.instances.json`, 'utf8'));
+  return Array.isArray(raw) ? raw : raw.instances || [];
+};
+
+/**
+ * @method loadInstanceTopology
+ * @description Returns `{ default, variants }` describing the deploy's instance
+ * variants, or `null` when the deploy is single-instance. The topology is
+ * declared per instance entry (`entry.multiInstance.default` / `.variants`); all
+ * multi-instance entries share the same variant set, so this returns it from the
+ * first entry that declares one.
+ * @param {string} deployId - Deployment identifier (e.g. `dd-cyberia`).
+ * @returns {?{default: string, variants: Array<object>}} The topology, or `null`.
+ * @memberof ServerConfBuilder
+ */
+const loadInstanceTopology = (deployId) => {
+  for (const entry of readConfInstances(deployId)) {
+    const mi = entry.multiInstance;
+    if (mi && Array.isArray(mi.variants) && mi.variants.length > 0)
+      return { default: mi.default || mi.variants[0].code, variants: mi.variants };
+  }
+  return null;
+};
+
+/**
+ * @method resolveInstanceEnvValue
+ * @description Resolves one declared env value. A plain string is used verbatim;
+ * an object is treated as env-scoped (`{ development, production }`), matching the
+ * convention already used by `lifecycle` / `readinessProbe` / `livenessProbe`.
+ * Placeholders are substituted from the variant tokens.
+ * @param {string|object} value - Declared value.
+ * @param {string} env - `development` | `production`.
+ * @param {Object<string,string>} tokens - Placeholder name → replacement.
+ * @returns {?string} Resolved value, or `null` when the env has no entry.
+ * @memberof ServerConfBuilder
+ */
+const resolveInstanceEnvValue = (value, env, tokens) => {
+  const scoped = value && typeof value === 'object' && !Array.isArray(value) ? value[env] : value;
+  if (scoped === undefined || scoped === null) return null;
+  return `${scoped}`.replace(/\{\{(\w+)\}\}/g, (match, token) => (token in tokens ? tokens[token] : match));
+};
+
+/**
+ * @method loadConfInstances
+ * @description Loads `conf.instances.json` and expands every entry carrying a
+ * `multiInstance` block into one concrete instance per declared variant.
+ *
+ * A template entry is never deployed as-is once variants exist: each variant
+ * produces its own entry whose id, env file path, volume mount and
+ * container-status strings are derived by replacing the template id token
+ * throughout. The variant whose `slug` is empty keeps the template id verbatim,
+ * so pre-existing deployments, PVCs and env directories survive the move to
+ * multi-instance untouched.
+ *
+ * Nothing here is application-specific: the variant set (`default` + `variants`),
+ * which env keys an instance needs (`env`), and prefix-stripping (`stripPathPrefix`)
+ * are all declared per entry under `entry.multiInstance`. Env values may use the
+ * `{{code}}`, `{{slug}}`, `{{path}}`, `{{id}}` and `{{default}}` placeholders and
+ * may be env-scoped objects.
+ *
+ * Every expanded entry carries three extra fields consumed by the deploy runners:
+ * `instanceCode` (the variant this instance serves), `templateId` (so targeting
+ * the template id acts on the whole family) and `instanceEnv` (the resolved env
+ * keys to write, keyed by environment: `{ development, production }`, so a build
+ * in either mode can emit a complete env directory).
+ *
+ * @param {string} deployId - Deployment identifier (e.g. `dd-cyberia`).
+ * @returns {Array<object>} Expanded instance entries.
+ * @memberof ServerConfBuilder
+ */
+const INSTANCE_ENVS = ['development', 'production'];
+
+const loadConfInstances = (deployId) => {
+  const expanded = [];
+  for (const entry of readConfInstances(deployId)) {
+    const spec = entry.multiInstance;
+    const variants = spec?.variants;
+    if (!Array.isArray(variants) || 0 === variants.length) {
+      expanded.push(entry);
+      continue;
+    }
+    for (const variant of variants) {
+      const id = variant.slug ? `${entry.id}-${variant.slug}` : entry.id;
+      const instance = variant.slug ? deepReplaceToken(entry, entry.id, id) : JSON.parse(JSON.stringify(entry));
+      delete instance.multiInstance;
+      instance.id = id;
+      instance.path = variant.path;
+      instance.instanceCode = variant.code;
+      instance.templateId = entry.id;
+
+      const tokens = {
+        code: variant.code,
+        slug: variant.slug || '',
+        path: variant.path,
+        id,
+        default: spec.default || '',
+      };
+      // Resolve the declared env keys for both environments so a build in either
+      // mode writes a complete env directory (development.env + production.env).
+      instance.instanceEnv = Object.fromEntries(INSTANCE_ENVS.map((e) => [e, {}]));
+      for (const [key, value] of Object.entries(spec.env || {}))
+        for (const e of INSTANCE_ENVS) {
+          const resolved = resolveInstanceEnvValue(value, e, tokens);
+          if (resolved !== null) instance.instanceEnv[e][key] = resolved;
+        }
+
+      // A backend that serves its routes at the root knows nothing about the
+      // variant prefix — it is selected by env instead. Strip the prefix at the
+      // proxy so the runtime stays instance-agnostic.
+      if (spec.stripPathPrefix && variant.path !== '/')
+        instance.pathRewritePolicy = [{ prefix: variant.path, replacement: '/' }];
+      expanded.push(instance);
+    }
+  }
+  return expanded;
+};
+
+/**
+ * @method selectConfInstances
+ * @description Filters expanded instances for a deploy target. Targeting a
+ * template id (`mmo-server`) selects the whole instance family; targeting a
+ * concrete id (`mmo-server-forest`) selects just that one.
+ * @param {Array<object>} instances - Expanded entries from {@link loadConfInstances}.
+ * @param {string} id - Target instance id or template id.
+ * @returns {Array<object>} Matching entries.
+ * @memberof ServerConfBuilder
+ */
+const selectConfInstances = (instances, id) =>
+  instances.filter((instance) => instance.id === id || instance.templateId === id);
+
 /**
  * Creates and writes the /etc/hosts file for a deployment.
  * @method etcHostFactory
@@ -2103,6 +2259,10 @@ git add .`);
 export {
   Config,
   loadConf,
+  loadConfInstances,
+  loadInstanceTopology,
+  readConfInstances,
+  selectConfInstances,
   loadReplicas,
   cloneConf,
   getCapVariableName,

package/src/server/downloader.js

@@ -41,18 +41,18 @@ class Downloader {
           const writer = fs.createWriteStream(fullPath);
           response.data.pipe(writer);
           writer.on('finish', () => {
-            logger.info('Download complete. File saved at', fullPath);
+            logger.info('Download completet');
             return resolve(fullPath);
           });
           writer.on('error', (error) => {
-            logger.error(error, 'Error downloading the file');
+            logger.error('Error downloading the file');
             // Cleanup incomplete file if possible
             if (fs.existsSync(fullPath)) fs.unlinkSync(fullPath);
             return reject(error);
           });
         })
         .catch((error) => {
-          logger.error(error, 'Error in the request');
+          logger.error('Error in the request');
           return reject(error);
         }),
     );

package/src/server/middlewares.js

@@ -0,0 +1,152 @@
+/**
+ * Express middleware and controller/router helpers for engine APIs.
+ *
+ * @module src/server/middlewares.js
+ */
+
+import { loggerFactory } from './logger.js';
+import { moderatorGuard, adminGuard } from './auth.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * The public-read CORS policy: reflect the request origin (or allow any)
+ * and mark the resource embeddable cross-origin.
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ */
+const setCrossOriginHeaders = (req, res) => {
+  if (req && req.headers && req.headers.origin) res.set('Access-Control-Allow-Origin', req.headers.origin);
+  else res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
+};
+
+/** Express middleware form of {@link setCrossOriginHeaders}. */
+const crossOriginMiddleware = (req, res, next) => {
+  setCrossOriginHeaders(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.
+ * @param {import('express').Request} req
+ */
+const withParsedPagination = (req) => {
+  const { page, limit } = req.query;
+  return {
+    ...req,
+    path: req.path,
+    params: req.params,
+    query: { ...req.query, page: parseInt(page), limit: parseInt(limit) },
+  };
+};
+
+const sendSuccess = (res, data) => res.status(200).json({ status: 'success', data });
+
+const sendError = (res, error, status = 400) => res.status(status).json({ status: 'error', message: error.message });
+
+/**
+ * Binary response with cross-origin and content headers.
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {{ buffer: Buffer, mimetype: string, filename: string, disposition?: 'inline'|'attachment' }} blob
+ */
+const sendBlob = (req, res, { buffer, mimetype, filename, disposition = 'inline' }) => {
+  setCrossOriginHeaders(req, res);
+  res.setHeader('Content-Type', mimetype);
+  res.setHeader('Content-Length', buffer.length);
+  res.setHeader('Content-Disposition', `${disposition}; filename="${filename}"`);
+  return res.status(200).end(buffer);
+};
+
+/**
+ * Wraps a controller body with error logging and the error response envelope.
+ * @param {(req, res, options) => Promise<any>} fn
+ * @param {{ errorStatus?: number }} [config]
+ */
+const controllerHandler =
+  (fn, { errorStatus = 400 } = {}) =>
+  async (req, res, options) => {
+    try {
+      return await fn(req, res, options);
+    } catch (error) {
+      logger.error(error, error.stack);
+      return sendError(res, error, errorStatus);
+    }
+  };
+
+/**
+ * Builds a controller method that delegates to a service method and wraps the
+ * result in the success envelope.
+ * @param {(req, res, options) => Promise<any>} serviceFn
+ * @param {{ errorStatus?: number, crossOrigin?: boolean, pagination?: boolean }} [config]
+ */
+const serviceHandler = (serviceFn, { errorStatus = 400, crossOrigin = false, pagination = false } = {}) =>
+  controllerHandler(
+    async (req, res, options) => {
+      if (crossOrigin) setCrossOriginHeaders(req, res);
+      const result = await serviceFn(pagination ? withParsedPagination(req) : req, res, options);
+      return sendSuccess(res, result);
+    },
+    { errorStatus },
+  );
+
+/**
+ * Builds a standard CRUD controller class (static post/get/put/delete) from a
+ * service exposing the same methods. `get` parses pagination.
+ * @param {{ post, get, put, delete }} service
+ * @param {Object<string, Function>} [extend] - Extra or overriding static handlers.
+ */
+const buildCrudController = (service, extend = {}) => {
+  class CrudController {
+    static post = serviceHandler(service.post);
+    static get = serviceHandler(service.get, { pagination: true });
+    static put = serviceHandler(service.put);
+    static delete = serviceHandler(service.delete);
+  }
+  Object.assign(CrudController, extend);
+  return CrudController;
+};
+
+/**
+ * Registers the standard CRUD routes with the standard guard policy:
+ * public reads, moderator-guarded writes, admin-guarded collection delete.
+ * Custom routes must be registered before calling this (generic `/:id` routes
+ * capture everything).
+ * @param {import('express').Router} router
+ * @param {{ post, get, put, delete }} Controller
+ * @param {import('../../api/types.js').RouterOptions} options
+ * @param {{ readGuards?: Function[], writeGuards?: Function[], deleteAllGuards?: Function[] }} [config]
+ *   Pass empty arrays for unguarded endpoints (e.g. player-written progress)
+ *   or explicit guard chains (e.g. admin-only reads).
+ * @returns {import('express').Router}
+ */
+const registerCrudRoutes = (router, Controller, options, { readGuards = [], writeGuards, deleteAllGuards } = {}) => {
+  const write = writeGuards ?? [options.authMiddleware, moderatorGuard];
+  const deleteAll = deleteAllGuards ?? [options.authMiddleware, adminGuard];
+  const handle = (method) => async (req, res) => await Controller[method](req, res, options);
+  router.post(`/:id`, ...write, handle('post'));
+  router.post(`/`, ...write, handle('post'));
+  router.get(`/:id`, ...readGuards, handle('get'));
+  router.get(`/`, ...readGuards, handle('get'));
+  router.put(`/:id`, ...write, handle('put'));
+  router.put(`/`, ...write, handle('put'));
+  router.delete(`/:id`, ...write, handle('delete'));
+  router.delete(`/`, ...deleteAll, handle('delete'));
+  return router;
+};
+
+export {
+  setCrossOriginHeaders,
+  crossOriginMiddleware,
+  withParsedPagination,
+  sendSuccess,
+  sendError,
+  sendBlob,
+  controllerHandler,
+  serviceHandler,
+  buildCrudController,
+  registerCrudRoutes,
+};