@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/db/mongo/MongoExpress.js

@@ -0,0 +1,187 @@
+/**
+ * Mongo Express Deployment Module
+ * @module src/db/mongo/MongoExpress
+ * @namespace MongoExpress
+ * @description Deploys the mongo-express web client used to inspect the cluster's MongoDB
+ * StatefulSet collections. The workload is a plain Deployment plus a ClusterIP Service, so the
+ * same manifests converge identically under Kind, Kubeadm and K3s; the only runtime-dependent
+ * decision is whether the deployed mongod enforces authentication, which selects the overlay.
+ */
+
+import { loggerFactory } from '../../server/ops/logger.js';
+import { shellExec } from '../../server/runtime/process.js';
+// Cyclic by construction (index -> cluster -> MongoExpress -> index), same as MongoBootstrap.js.
+// Safe because the binding is only dereferenced inside method bodies, never at module scope.
+import Underpost from '../../index.js';
+import { MONGODB_DEFAULT_PORT, MONGODB_SERVICE_NAME, MONGODB_STATEFULSET_NAME } from './MongooseDB.js';
+
+const logger = loggerFactory(import.meta);
+
+const MONGO_EXPRESS_NAME = 'mongo-express';
+const MONGO_EXPRESS_SERVICE_NAME = 'mongo-express-service';
+const MONGO_EXPRESS_IMAGE = 'mongo-express:1.0.2';
+const MONGO_EXPRESS_PORT = 8081;
+const MONGO_EXPRESS_NODE_PORT = 32081;
+const MONGO_EXPRESS_BASE_URL = '/mongo/';
+// The UI reads the root credentials and gates its own session with the same pair, so it consumes
+// the StatefulSet's secret rather than owning a second credential of its own.
+const MONGO_EXPRESS_SECRET_NAME = 'mongodb-secret';
+const MONGO_EXPRESS_MANIFEST_DIR = 'manifests/deployment/mongo-express';
+const MONGO_EXPRESS_NO_AUTH_MANIFEST_DIR = 'manifests/deployment/mongo-express-no-auth';
+
+// Literal and unescaped: kubectl's jsonpath quotes carry escape sequences of their own, and no
+// mongod argument contains a pipe.
+const MONGOD_ARGS_FIELD_SEPARATOR = '|';
+
+/**
+ * Parses the mongod argument vector reported by `kubectl -o jsonpath` for the StatefulSet.
+ * @param {string} raw - Raw jsonpath stdout: the StatefulSet name, then one field per argument.
+ * @returns {Array<string>|null} Argument vector, or null when no StatefulSet was reported.
+ * @memberof MongoExpress
+ */
+const parseMongodArgs = (raw) => {
+  const value = `${raw || ''}`;
+  if (!value.trim()) return null;
+  const [, ...args] = value.split(MONGOD_ARGS_FIELD_SEPARATOR);
+  return args.map((arg) => arg.trim()).filter(Boolean);
+};
+
+/**
+ * Decides whether mongo-express must authenticate against the deployed mongod.
+ *
+ * The deployed StatefulSet is the authority: `manifests/mongodb` starts mongod with `--auth` and
+ * `manifests/mongodb-4.4` does not, and either can be the one running regardless of which flag
+ * this invocation carries. The flags only answer for a cluster with no StatefulSet deployed yet,
+ * where `--mongodb` (the auth-enabled manifest set) is the default the platform installs.
+ * @param {object} [params={}] - Resolution inputs.
+ * @param {Array<string>|null} [params.args=null] - mongod argument vector, or null when undeployed.
+ * @param {object} [params.options={}] - Cluster options (`mongodb`, `mongodb4`).
+ * @returns {boolean} True when the admin credential pair must be projected.
+ * @memberof MongoExpress
+ */
+const mongoAuthEnabledFactory = ({ args = null, options = {} } = {}) => {
+  if (Array.isArray(args)) return args.includes('--auth');
+  return options.mongodb4 !== true;
+};
+
+/**
+ * Resolves the kustomization root the auth mode selects.
+ * @param {object} [params={}] - Path inputs.
+ * @param {string} [params.underpostRoot='.'] - Repository root holding `manifests/`.
+ * @param {boolean} [params.authEnabled=true] - Whether mongod enforces authentication.
+ * @returns {string} Kustomization directory path.
+ * @memberof MongoExpress
+ */
+const mongoExpressManifestPathFactory = ({ underpostRoot = '.', authEnabled = true } = {}) =>
+  `${underpostRoot}/${authEnabled ? MONGO_EXPRESS_MANIFEST_DIR : MONGO_EXPRESS_NO_AUTH_MANIFEST_DIR}`;
+
+/**
+ * Resolves the opt-in NodePort Service manifest path. It lives in the base directory and is left
+ * out of both kustomizations: exposing an admin UI on the node network is a caller's decision.
+ * @param {object} [params={}] - Path inputs.
+ * @param {string} [params.underpostRoot='.'] - Repository root holding `manifests/`.
+ * @returns {string} NodePort manifest path.
+ * @memberof MongoExpress
+ */
+const mongoExpressNodePortManifestFactory = ({ underpostRoot = '.' } = {}) =>
+  `${underpostRoot}/${MONGO_EXPRESS_MANIFEST_DIR}/mongo-express-nodeport.yaml`;
+
+/**
+ * @class MongoExpress
+ * @description Static deployment surface for the mongo-express admin client.
+ * @memberof MongoExpress
+ */
+class MongoExpress {
+  /**
+   * Reads the mongod argument vector from the deployed MongoDB StatefulSet.
+   *
+   * The projection leads with the StatefulSet name so a deployed server that declares no arguments
+   * stays distinguishable from no server at all — one is mongod on its defaults, the other is a
+   * cluster with no data tier yet, and both would otherwise reduce to empty output.
+   * @param {string} [namespace='default'] - Namespace holding the StatefulSet.
+   * @returns {Array<string>|null} Argument vector, or null when no StatefulSet is deployed.
+   * @memberof MongoExpress
+   */
+  static readMongodArgs(namespace = 'default') {
+    const raw = shellExec(
+      `kubectl get statefulset ${MONGODB_STATEFULSET_NAME} -n ${namespace} --ignore-not-found -o jsonpath=` +
+        `'{.metadata.name}{"${MONGOD_ARGS_FIELD_SEPARATOR}"}` +
+        `{range .spec.template.spec.containers[?(@.name=="${MONGODB_STATEFULSET_NAME}")].args[*]}` +
+        `{@}{"${MONGOD_ARGS_FIELD_SEPARATOR}"}{end}'`,
+      { stdout: true, silent: true, silentOnError: true },
+    );
+    return parseMongodArgs(raw);
+  }
+
+  /**
+   * Deploys mongo-express and, once it is Ready, applies the exposure and placement the caller
+   * asked for. Cluster-type agnostic by construction: only the image pull differs between Kind
+   * (loaded into the node's image store) and Kubeadm/K3s (pulled through the CRI).
+   * @param {object} [params={}] - Deployment parameters.
+   * @param {string} [params.namespace='default'] - Target namespace.
+   * @param {string} [params.underpostRoot='.'] - Repository root holding `manifests/`.
+   * @param {object} [params.options={}] - Cluster options (`pullImage`, `nodePort`, `nodeName`, `mongodb4`).
+   * @returns {Promise<boolean>} Whether the deployment reported Ready.
+   * @memberof MongoExpress
+   */
+  static async deploy({ namespace = 'default', underpostRoot = '.', options = {} } = {}) {
+    // Secret before workload: the Deployment's secretKeyRef must resolve at pod admission, and
+    // the encrypted store stays the source of truth wherever a manifest exists.
+    if (!Underpost.secret.applyIfPresent(MONGO_EXPRESS_SECRET_NAME, namespace))
+      Underpost.secret.applyFromOriginSeed(MONGO_EXPRESS_SECRET_NAME, namespace);
+
+    if (options.pullImage) Underpost.cluster.pullImage(MONGO_EXPRESS_IMAGE, options);
+
+    const args = MongoExpress.readMongodArgs(namespace);
+    const authEnabled = mongoAuthEnabledFactory({ args, options });
+    const manifestPath = mongoExpressManifestPathFactory({ underpostRoot, authEnabled });
+    logger.info('Deploying mongo-express', {
+      namespace,
+      authEnabled,
+      manifestPath,
+      mongodb: args ? 'deployed' : 'not deployed',
+    });
+    shellExec(`kubectl apply -k ${manifestPath} -n ${namespace}`);
+
+    const ready = await Underpost.test.statusMonitor(MONGO_EXPRESS_NAME, 'Running', 'pods', 1000, 60 * 10);
+    if (!ready) {
+      logger.error('mongo-express did not report Running', { namespace });
+      return false;
+    }
+
+    if (options.nodePort)
+      shellExec(`kubectl apply -f ${mongoExpressNodePortManifestFactory({ underpostRoot })} -n ${namespace}`);
+    if (options.nodeName)
+      Underpost.cluster.pinToNode({
+        kind: 'deployment',
+        name: MONGO_EXPRESS_NAME,
+        namespace,
+        node: options.nodeName,
+      });
+
+    logger.info('mongo-express ready', {
+      server: `${MONGODB_STATEFULSET_NAME}-0.${MONGODB_SERVICE_NAME}:${MONGODB_DEFAULT_PORT}`,
+      basicAuth: `secret/${MONGO_EXPRESS_SECRET_NAME}`,
+      clusterIp: `${MONGO_EXPRESS_SERVICE_NAME}:${MONGO_EXPRESS_PORT}${MONGO_EXPRESS_BASE_URL}`,
+      nodePort: options.nodePort ? `<node>:${MONGO_EXPRESS_NODE_PORT}${MONGO_EXPRESS_BASE_URL}` : null,
+      portForward: `kubectl port-forward -n ${namespace} svc/${MONGO_EXPRESS_SERVICE_NAME} ${MONGO_EXPRESS_PORT}:${MONGO_EXPRESS_PORT}`,
+    });
+    return true;
+  }
+}
+
+export {
+  MONGO_EXPRESS_BASE_URL,
+  MONGO_EXPRESS_IMAGE,
+  MONGO_EXPRESS_NAME,
+  MONGO_EXPRESS_NODE_PORT,
+  MONGO_EXPRESS_PORT,
+  MONGO_EXPRESS_SECRET_NAME,
+  MONGO_EXPRESS_SERVICE_NAME,
+  MongoExpress,
+  mongoAuthEnabledFactory,
+  mongoExpressManifestPathFactory,
+  mongoExpressNodePortManifestFactory,
+  parseMongodArgs,
+};
+export default MongoExpress;

package/src/db/mongo/MongooseDB.js

@@ -1,6 +1,6 @@
 import mongoose from 'mongoose';
 import { getCapVariableName } from '../../client/components/core/CommonJs.js';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 
 /**
  * Module for connecting to and loading models for a MongoDB database using Mongoose.
@@ -13,16 +13,13 @@ const logger = loggerFactory(import.meta);
 const MONGODB_SERVICE_NAME = 'mongodb-service';
 const MONGODB_STATEFULSET_NAME = 'mongodb';
 const MONGODB_DEFAULT_AUTH_SOURCE = 'admin';
+const MONGODB_DEFAULT_PORT = 27017;
 const MONGODB_DEFAULT_REPLICA_SET = 'rs0';
 const MONGODB_DEFAULT_REPLICA_COUNT = 3;
-// Node-local base path backing the hostPath PVs (`<root>/v<replica index>`),
-// generated one-per-replica by MongoBootstrap.applyReplicaVolumes().
 const MONGODB_DATA_ROOT = '/data/mongodb';
-// Replica volumes are hostPath PVs generated one per member, each pinned by `claimRef`. The class
-// must stay static: a dynamic provisioner competes with the static binder and makes
-// member-to-directory assignment non-deterministic.
 const MONGODB_STORAGE_CLASS_NAME = 'mongodb-storage-class';
 const MONGODB_STORAGE_CLASS_PROVISIONER = 'kubernetes.io/no-provisioner';
+
 /**
  * Mongoose connection options for MongoDB, with sensible defaults for production and development environments.
  * @type {import('mongoose').ConnectOptions}
@@ -51,12 +48,12 @@ const resolveMongoReplicaHosts = ({ hostList = '', replicaCount = MONGODB_DEFAUL
       .split(',')
       .map((host) => host.trim())
       .filter(Boolean)
-      .map((host) => (host.includes(':') ? host : `${host}:27017`));
+      .map((host) => (host.includes(':') ? host : `${host}:${MONGODB_DEFAULT_PORT}`));
   }
 
   return Array.from(
     { length: replicaCount },
-    (_, index) => `${MONGODB_STATEFULSET_NAME}-${index}.${MONGODB_SERVICE_NAME}:27017`,
+    (_, index) => `${MONGODB_STATEFULSET_NAME}-${index}.${MONGODB_SERVICE_NAME}:${MONGODB_DEFAULT_PORT}`,
   );
 };
 
@@ -208,6 +205,8 @@ export {
   MongooseDB,
   MongooseDBService as MongooseDBClass,
   MONGODB_DATA_ROOT,
+  MONGODB_DEFAULT_AUTH_SOURCE,
+  MONGODB_DEFAULT_PORT,
   MONGODB_DEFAULT_REPLICA_COUNT,
   MONGODB_DEFAULT_REPLICA_SET,
   MONGODB_SERVICE_NAME,

package/src/{server/valkey.js → db/valkey/Valkey.js}

@@ -9,12 +9,13 @@
  * Out of scope: domain model factories, DTO projection — those belong in
  * their respective service modules (e.g. guest.service.js).
  *
- * @module src/server/valkey.js
+ * @module src/db/valkey/Valkey.js
  * @namespace ValkeyService
  */
 import Valkey from 'iovalkey';
-import { loggerFactory } from './logger.js';
-import Underpost from '../index.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import Underpost from '../../index.js';
+import { latchRuntimeError } from '../../server/runtime/runtime-status.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -71,7 +72,7 @@ const createValkeyConnection = async (instance = {}, connectionOptions = {}) =>
   client.on('error', (err) => {
     ValkeyStatus[key] = 'error';
     logger.error('Valkey error', { err: err?.message, instance });
-    if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error');
+    latchRuntimeError();
   });
   client.on('reconnecting', () => {
     ValkeyStatus[key] = 'reconnecting';

package/src/grpc/cyberia/grpc-server.js

@@ -1,10 +1,9 @@
 /**
  * gRPC transport for the Cyberia Engine data pipeline.
  *
- * Runs alongside Express on a separate port (default 50051).
- * Thin adapter over src/projects/cyberia/instance-data.js — the shared
- * world-load/boot assembly also served by the REST fallback at
- * /api/cyberia-instance/boot/* — so both transports stay equivalent.
+ * Runs beside Express on its own port (default 50051). Thin adapter over
+ * src/projects/cyberia/instance-data.js, the same assembly the REST fallback
+ * at /api/cyberia-instance/boot/* serves, so both transports stay equivalent.
  *
  * @module src/grpc/cyberia/grpc-server.js
  */
@@ -13,10 +12,9 @@ import * as grpc from '@grpc/grpc-js';
 import * as protoLoader from '@grpc/proto-loader';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import {
   buildFallbackConfig,
-  buildFallbackInstanceConfig,
   fetchFullInstance,
   fetchMapData,
   fetchObjectLayer,
@@ -131,7 +129,7 @@ class GrpcServer {
 
     server.addService(proto.CyberiaDataService.service, buildHandlers(dbKey));
 
-    // gRPC runs over Kubernetes internal network (ClusterIP) — always insecure
+    // gRPC stays on the cluster-internal network, so credentials are insecure.
     const creds = grpc.ServerCredentials.createInsecure();
 
     return new Promise((resolve, reject) => {
@@ -159,4 +157,4 @@ class GrpcServer {
   }
 }
 
-export { GrpcServer, buildFallbackConfig, buildFallbackInstanceConfig };
+export { GrpcServer, buildFallbackConfig };

package/src/index.js

@@ -5,23 +5,28 @@
  */
 
 import UnderpostBaremetal from './cli/baremetal.js';
+import UnderpostApp from './cli/app.js';
+import UnderpostClient from './cli/client.js';
+import UnderpostHost from './cli/host.js';
 import UnderpostCloudInit from './cli/cloud-init.js';
 import UnderpostKickStart from './cli/kickstart.js';
 import UnderpostCluster from './cli/cluster.js';
 import UnderpostDB from './cli/db.js';
 import UnderpostDeploy from './cli/deploy.js';
 import UnderpostDockerCompose from './cli/docker-compose.js';
+import UnderpostEvent from './cli/event.js';
 import UnderpostKubectl from './cli/kubectl.js';
-import UnderpostRootEnv from './cli/env.js';
 import UnderpostFileStorage from './cli/fs.js';
 import UnderpostIPFS from './cli/ipfs.js';
 import UnderpostImage from './cli/image.js';
 import UnderpostLxd from './cli/lxd.js';
 import UnderpostMonitor from './cli/monitor.js';
+import UnderpostPackage from './cli/package.js';
 import UnderpostRepository from './cli/repository.js';
 import UnderpostRun from './cli/run.js';
 import UnderpostSecret from './cli/secrets.js';
 import UnderpostSSH from './cli/ssh.js';
+import UnderpostState from './cli/state.js';
 import UnderpostStatic from './cli/static.js';
 import UnderpostTest from './cli/test.js';
 import UnderpostRelease from './cli/release.js';
@@ -29,11 +34,11 @@ import UnderpostSystemProvisionig from './cli/system.js';
 import UnderpostVultr from './cli/vultr.js';
 import UnderpostWireguard from './cli/wireguard.js';
 
-import UnderpostDns from './server/dns.js';
-import UnderpostBackup from './server/backup.js';
-import UnderpostCron from './server/cron.js';
-import UnderpostStartUp from './server/start.js';
-import UnderpostTLS from './server/tls.js';
+import UnderpostDns from './server/network/dns.js';
+import UnderpostBackup from './server/storage/backup.js';
+import UnderpostCron from './server/ops/cron.js';
+import UnderpostStartUp from './server/runtime/start.js';
+import UnderpostTLS from './server/network/tls.js';
 
 /**
  * Underpost main module methods
@@ -47,7 +52,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v3.3.0';
+  static version = 'v3.3.76';
 
   /**
    * Required Node.js major version
@@ -67,24 +72,14 @@ class Underpost {
     return UnderpostRepository.API;
   }
   /**
-   * Root Env cli API
+   * Client build cli API
    * @static
-   * @type {UnderpostRootEnv.API}
+   * @type {UnderpostClient.API}
    * @memberof Underpost
    */
-  static get env() {
-    return UnderpostRootEnv.API;
+  static get client() {
+    return UnderpostClient.API;
   }
-  /**
-   * Test cli API
-   * @static
-   * @type {UnderpostTest.API}
-   * @memberof Underpost
-   */
-  static get test() {
-    return UnderpostTest.API;
-  }
-
   /**
    * Static cli API
    * @static
@@ -119,6 +114,33 @@ class Underpost {
    * @type {UnderpostSecret.API}
    * @memberof Underpost
    */
+  static get host() {
+    return UnderpostHost.API;
+  }
+  /**
+   * App deployment environment domain cli API
+   * @static
+   * @type {UnderpostApp.API}
+   * @memberof Underpost
+   */
+  static get app() {
+    return UnderpostApp.API;
+  }
+  /**
+   * Workload secret store domain cli API
+   * @static
+   * @type {UnderpostSecret.API}
+   * @memberof Underpost
+   */
+  static get state() {
+    return UnderpostState.API;
+  }
+  /**
+   * Workload secret store domain cli API
+   * @static
+   * @type {UnderpostSecret.API}
+   * @memberof Underpost
+   */
   static get secret() {
     return UnderpostSecret.API;
   }
@@ -185,6 +207,15 @@ class Underpost {
   static get monitor() {
     return UnderpostMonitor.API;
   }
+  /**
+   * Operational event dispatcher cli API
+   * @static
+   * @type {UnderpostEvent.API}
+   * @memberof Underpost
+   */
+  static get event() {
+    return UnderpostEvent.API;
+  }
   /**
    * SSH cli API
    * @static
@@ -333,6 +364,26 @@ class Underpost {
   static get release() {
     return UnderpostRelease.API;
   }
+
+  /**
+   * Test runner cli API
+   * @static
+   * @type {UnderpostTest.API}
+   * @memberof Underpost
+   */
+  static get test() {
+    return UnderpostTest.API;
+  }
+
+  /**
+   * Deploy package manifest cli API
+   * @static
+   * @type {UnderpostPackage.API}
+   * @memberof Underpost
+   */
+  static get package() {
+    return UnderpostPackage.API;
+  }
 }
 
 if (!process.version || !process.version.startsWith(`${Underpost.majorNodejsVersion}.`))
@@ -354,20 +405,25 @@ export {
   UnderpostDB,
   UnderpostDeploy,
   UnderpostDockerCompose,
+  UnderpostEvent,
   UnderpostKubectl,
-  UnderpostRootEnv,
   UnderpostFileStorage,
   UnderpostImage,
   UnderpostStatic,
+  UnderpostTest,
   UnderpostLxd,
   UnderpostKickStart,
   UnderpostIPFS,
   UnderpostMonitor,
+  UnderpostPackage,
+  UnderpostApp,
+  UnderpostClient,
+  UnderpostHost,
   UnderpostRepository,
   UnderpostRun,
   UnderpostSecret,
   UnderpostSSH,
-  UnderpostTest,
+  UnderpostState,
   UnderpostDns,
   UnderpostBackup,
   UnderpostCron,

package/src/mailer/EmailRender.js

@@ -98,8 +98,8 @@ class EmailRenderService {
     for (const templateKey of Object.keys(options.templates)) {
       const ssrEmailComponent = options.templates[templateKey];
       // Note: ssrFactory is assumed to load and return a functional component/function
-      const SrrComponent = await ssrFactory(`./src/client/ssr/mailer/${ssrEmailComponent}.js`);
-      templates[templateKey] = SrrComponent(this, options);
+      const SSRComponent = await ssrFactory(`./src/client/ssr/mailer/${ssrEmailComponent}.js`);
+      templates[templateKey] = SSRComponent(this, options);
     }
     return templates;
   }

package/src/mailer/MailerInterceptor.js

@@ -0,0 +1,87 @@
+import { MailerProvider } from './MailerProvider.js';
+
+/**
+ * General-purpose capture of everything {@link MailerProviderService#send}
+ * delivers, built on the provider's send middleware.
+ *
+ * Assertions about mail are otherwise only possible against a real inbox. The
+ * interceptor records the delivery context and the transport result of each
+ * send, which is what lets a caller wait for a specific message and know
+ * whether the transport actually accepted it.
+ *
+ * @module src/mailer/MailerInterceptor.js
+ * @namespace MailerInterceptor
+ */
+
+/**
+ * @typedef {object} InterceptedMail
+ * @property {string} id - Mailer instance the message was sent through.
+ * @property {object} sendOptions - Nodemailer options as the transport received them.
+ * @property {object|undefined} info - Transport result; `undefined` when delivery failed.
+ * @property {boolean} accepted - Whether the transport accepted the message.
+ * @property {string} at - ISO timestamp of the delivery attempt.
+ * @memberof MailerInterceptor
+ */
+
+/**
+ * @method mailerInterceptorFactory
+ * @description Installs a send interceptor and returns its recorder.
+ *
+ * The interceptor is transparent: it forwards every send to the transport and
+ * records the outcome. `suppress` holds the message instead, for callers that
+ * must exercise the send path without delivering.
+ *
+ * @param {object} [params]
+ * @param {import('./MailerProvider.js').MailerProvider} [params.provider] - Provider to intercept.
+ * @param {function(object): boolean} [params.filter] - Records only the contexts it accepts.
+ * @param {boolean} [params.suppress=false] - Record without handing the message to the transport.
+ * @returns {{messages: Array<InterceptedMail>, waitFor: function, close: function(): void}} Recorder.
+ * @memberof MailerInterceptor
+ */
+const mailerInterceptorFactory = ({ provider = MailerProvider, filter, suppress = false } = {}) => {
+  const messages = [];
+
+  const dispose = provider.use(async (context, next) => {
+    const matched = !filter || filter(context);
+    const info = matched && suppress ? { messageId: `suppressed:${Date.now()}`, suppressed: true } : await next();
+    if (matched)
+      messages.push({
+        id: context.id,
+        sendOptions: context.sendOptions,
+        info,
+        accepted: Boolean(info),
+        at: new Date().toISOString(),
+      });
+    return info;
+  });
+
+  return {
+    messages,
+
+    /**
+     * Resolves with the first recorded message matching `predicate`.
+     *
+     * Polls rather than resolving on registration, because a send started
+     * before the caller began waiting must still satisfy the wait.
+     *
+     * @param {function(InterceptedMail): boolean} predicate - Match to wait for.
+     * @param {object} [options]
+     * @param {number} [options.timeoutMs=60000] - Maximum wait.
+     * @param {number} [options.intervalMs=250] - Poll interval.
+     * @returns {Promise<InterceptedMail|undefined>} The match, or `undefined` on timeout.
+     */
+    async waitFor(predicate, { timeoutMs = 60000, intervalMs = 250 } = {}) {
+      const deadline = Date.now() + timeoutMs;
+      do {
+        const match = messages.find(predicate);
+        if (match) return match;
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      } while (Date.now() < deadline);
+      return messages.find(predicate);
+    },
+
+    close: dispose,
+  };
+};
+
+export { mailerInterceptorFactory };

package/src/mailer/MailerProvider.js

@@ -1,5 +1,5 @@
 import nodemailer from 'nodemailer';
-import { loggerFactory } from '../server/logger.js';
+import { loggerFactory } from '../server/ops/logger.js';
 import { EmailRender } from './EmailRender.js';
 
 /**
@@ -45,6 +45,12 @@ class MailerProviderService {
    */
   #instance = {};
 
+  /**
+   * Registered send middlewares, in the order they wrap a delivery.
+   * @type {Array<function(object, function(): Promise<object|undefined>): Promise<object|undefined>>}
+   */
+  #middlewares = [];
+
   /**
    * Retrieves the internal instance storage for direct access (used for backward compatibility).
    * @returns {object.<string, object>} The internal mailer instance map.
@@ -53,6 +59,28 @@ class MailerProviderService {
     return this.#instance;
   }
 
+  /**
+   * Registers a send middleware.
+   *
+   * Middlewares wrap every {@link MailerProviderService#send}, in registration
+   * order, and receive the delivery context plus the `next` continuation that
+   * yields the transport result. A middleware that never calls `next` suppresses
+   * the delivery, which is what makes this usable both for cross-cutting
+   * concerns (auditing, rate limiting) and for capturing mail in a test run.
+   *
+   * @param {function(object, function(): Promise<object|undefined>): Promise<object|undefined>} middleware -
+   * Receives `({ id, sendOptions, sender }, next)`.
+   * @returns {function(): void} Disposer that unregisters the middleware.
+   */
+  use(middleware) {
+    if (typeof middleware !== 'function') throw new Error('[mailer] a send middleware must be a function');
+    this.#middlewares.push(middleware);
+    return () => {
+      const index = this.#middlewares.indexOf(middleware);
+      if (index !== -1) this.#middlewares.splice(index, 1);
+    };
+  }
+
   /**
    * Loads and initializes a new mailer provider instance using Nodemailer.
    * The created instance is stored internally and includes the transporter and rendered templates.
@@ -145,6 +173,24 @@ class MailerProviderService {
     }
   }
 
+  /**
+   * Closes a loaded instance's transport and forgets it.
+   *
+   * A transport holds an open socket, which keeps a one-shot process alive long
+   * after its work is done. Callers that load an instance for a single delivery
+   * release it here; a long-running server keeps its instances loaded instead.
+   *
+   * @param {string} id - Mailer instance id.
+   * @returns {boolean} True when an instance was closed.
+   */
+  close(id) {
+    const instance = this.#instance[id];
+    if (!instance) return false;
+    if (typeof instance.transporter?.close === 'function') instance.transporter.close();
+    delete this.#instance[id];
+    return true;
+  }
+
   /**
    * Sends an email using a previously loaded transporter instance.
    *
@@ -189,12 +235,10 @@ class MailerProviderService {
 
       if (!sendOptions.from) sendOptions.from = `${instance.sender.name} <${instance.sender.email}>`;
 
-      // send mail with defined transport object
-      const info = await instance.transporter.sendMail(sendOptions);
-
-      // logger.info('Message sent', info);
+      const context = { id, sendOptions, sender: instance.sender };
+      const deliver = () => instance.transporter.sendMail(sendOptions);
 
-      return info;
+      return await this.#middlewares.reduceRight((next, middleware) => () => middleware(context, next), deliver)();
     } catch (error) {
       logger.error(error, error.stack);
       return undefined;