@lenne.tech/nest-server 11.31.2 → 11.32.0

package/src/core/modules/hub/helpers/hub-command-shape.helper.spec.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeCommandShape } from './hub-command-shape.helper';
+
+describe('normalizeCommandShape', () => {
+  it('replaces scalar values with a placeholder but keeps keys', () => {
+    const out = normalizeCommandShape({ email: 'alice@example.com', age: 30, active: true });
+    expect(out).toEqual({ active: '?', age: '?', email: '?' });
+  });
+
+  it('keeps Mongo operators as keys (they are structure, not data)', () => {
+    const out = normalizeCommandShape({ age: { $gte: 18, $lt: 65 } });
+    expect(out).toEqual({ age: { $gte: '?', $lt: '?' } });
+  });
+
+  it('collapses scalar arrays ($in) to a single placeholder', () => {
+    const out = normalizeCommandShape({ id: { $in: [1, 2, 3, 4] } });
+    expect(out).toEqual({ id: { $in: ['?'] } });
+  });
+
+  it('keeps per-stage shape for pipeline-like object arrays', () => {
+    const out = normalizeCommandShape([{ $match: { x: 1 } }, { $group: { _id: '$y' } }]) as unknown[];
+    expect(out).toHaveLength(2);
+    expect(out[0]).toEqual({ $match: { x: '?' } });
+  });
+
+  it('does NOT leak the original values (privacy)', () => {
+    const secret = 'super-secret@example.com';
+    const out = normalizeCommandShape({ filter: { email: secret } });
+    expect(JSON.stringify(out)).not.toContain(secret);
+  });
+
+  it('caps recursion depth', () => {
+    let deep: any = 'leaf';
+    for (let i = 0; i < 20; i++) {
+      deep = { nested: deep };
+    }
+    const out = JSON.stringify(normalizeCommandShape(deep));
+    // Must terminate and not blow the stack; the sentinel marks the cut.
+    expect(out).toContain('…');
+  });
+
+  it('produces identical output for identical query shapes (the N+1 template key)', () => {
+    const a = normalizeCommandShape({ filter: { email: 'a@x.com' }, limit: 1 });
+    const b = normalizeCommandShape({ filter: { email: 'b@y.com' }, limit: 999 });
+    expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+  });
+});

package/src/core/modules/hub/helpers/hub-command-shape.helper.ts

@@ -0,0 +1,47 @@
+/**
+ * Normalize a MongoDB command fragment into a value-free SHAPE.
+ *
+ * Every scalar becomes `'?'` while keys and `$operators` are preserved. This serves two purposes at
+ * once for the query profiler:
+ *  1. Privacy — no filter values, no document contents, ever enter the ring buffer.
+ *  2. N+1 detection — identical query shapes normalize to identical strings, so they can be grouped
+ *     and counted (the "top templates" view).
+ *
+ * Bounds keep a pathological command from exhausting memory/stack: depth 5, 32 keys per object,
+ * object-arrays truncated to 8 elements.
+ */
+
+const MAX_DEPTH = 5;
+const MAX_KEYS = 32;
+const MAX_ARRAY_ITEMS = 8;
+const DEPTH_SENTINEL = '…';
+const PLACEHOLDER = '?';
+
+export function normalizeCommandShape(value: unknown, depth = 0): unknown {
+  if (depth >= MAX_DEPTH) {
+    return DEPTH_SENTINEL;
+  }
+
+  if (Array.isArray(value)) {
+    // Object arrays (pipelines, bulk ops) keep per-element shape; scalar arrays ($in) collapse.
+    if (value.length > 0 && typeof value[0] === 'object' && value[0] !== null) {
+      return value.slice(0, MAX_ARRAY_ITEMS).map((item) => normalizeCommandShape(item, depth + 1));
+    }
+    return [PLACEHOLDER];
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    let count = 0;
+    for (const key of Object.keys(value as Record<string, unknown>)) {
+      if (++count > MAX_KEYS) {
+        out[DEPTH_SENTINEL] = DEPTH_SENTINEL;
+        break;
+      }
+      out[key] = normalizeCommandShape((value as Record<string, unknown>)[key], depth + 1);
+    }
+    return out;
+  }
+
+  return PLACEHOLDER;
+}

package/src/core/modules/hub/helpers/hub-mask.helper.spec.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import { maskConfigDeep } from './hub-mask.helper';
+
+describe('maskConfigDeep', () => {
+  it('masks values whose key matches the secret pattern', () => {
+    const out = maskConfigDeep({
+      jwt: { secret: 'SENTINEL_JWT', refresh: { secret: 'SENTINEL_REFRESH' } },
+      port: 3000,
+    });
+
+    expect(out.jwt.secret).toBe('***');
+    expect(out.jwt.refresh.secret).toBe('***');
+    expect(out.port).toBe(3000);
+  });
+
+  it('masks a broad set of secret-ish key names', () => {
+    const out = maskConfigDeep({
+      apiKey: 'AK',
+      betterAuth: { secret: 'BA' },
+      encryptionSecret: 'ENC',
+      password: 'PW',
+      privateKey: 'PK',
+      token: 'TK',
+    });
+
+    for (const value of Object.values(out)) {
+      const flat = JSON.stringify(value);
+      expect(flat).not.toMatch(/AK|BA|ENC|PW|PK|TK/);
+    }
+  });
+
+  it('deep-clones — the input object is never mutated', () => {
+    const input = { jwt: { secret: 'SENTINEL' }, nested: { arr: [{ token: 'T' }] } };
+    const out = maskConfigDeep(input);
+
+    expect(input.jwt.secret).toBe('SENTINEL');
+    expect(input.nested.arr[0].token).toBe('T');
+    expect(out.jwt.secret).toBe('***');
+    expect(out.nested.arr[0].token).toBe('***');
+  });
+
+  it('masks credentials embedded in URI-shaped values', () => {
+    const out = maskConfigDeep({ mongoose: { uri: 'mongodb://user:secretpw@host:27017/db' } });
+
+    expect(out.mongoose.uri).not.toContain('secretpw');
+    expect(out.mongoose.uri).toContain('mongodb://');
+    expect(out.mongoose.uri).toContain('host:27017');
+  });
+
+  it('honors additional explicit secret field names', () => {
+    const out = maskConfigDeep({ customField: 'HIDE_ME', other: 'keep' }, ['customField']);
+
+    expect(out.customField).toBe('***');
+    expect(out.other).toBe('keep');
+  });
+
+  it('passes through null, numbers, booleans and dates', () => {
+    const date = new Date('2026-01-01T00:00:00.000Z');
+    const out = maskConfigDeep({ a: null, b: 42, c: true, d: date });
+
+    expect(out.a).toBeNull();
+    expect(out.b).toBe(42);
+    expect(out.c).toBe(true);
+    expect(out.d).toBeInstanceOf(Date);
+  });
+});

package/src/core/modules/hub/helpers/hub-mask.helper.ts

@@ -0,0 +1,78 @@
+/**
+ * Recursive, non-mutating config masker for the Hub config viewer.
+ *
+ * CRITICAL: this deep-clones before masking. Hub JSON sidecars must never hand a live,
+ * service-owned object to the response pipeline — `CheckSecurityInterceptor` deletes secret-named
+ * keys IN PLACE, which would corrupt the running server config. Cloning here is the guarantee.
+ */
+
+/** Key-name heuristics that mark a value as secret. Matched case-insensitively against each key. */
+const SECRET_KEY_PATTERN =
+  /secret|passwd|password|passphrase|credential|api[-_]?key|access[-_]?token|refresh[-_]?token|private[-_]?key|encryption|\btoken\b|\bpass\b|(^|[^a-z])key([^a-z]|$)/i;
+
+/** Value-shape heuristic: a connection URI carrying `scheme://user:password@host`. */
+const URI_CREDENTIAL_PATTERN = /^([a-z][a-z0-9+.-]*:\/\/[^/@:\s]+:)([^@/\s]+)(@)/i;
+
+const MASK = '***';
+
+/**
+ * Deep-clone `value` and mask every secret it contains.
+ *
+ * A value is masked when its key matches {@link SECRET_KEY_PATTERN} or appears in `extraSecretKeys`.
+ * Additionally, any string that looks like a credentialed connection URI has its password segment
+ * masked regardless of key name.
+ *
+ * @param value - the object/value to mask (not mutated)
+ * @param extraSecretKeys - additional exact key names to always mask (e.g. `security.secretFields`)
+ */
+export function maskConfigDeep<T>(value: T, extraSecretKeys: string[] = []): T {
+  const extra = new Set(extraSecretKeys.map((k) => k.toLowerCase()));
+  return maskValue(value, false, extra) as T;
+}
+
+function isSecretKey(key: string, extra: Set<string>): boolean {
+  return extra.has(key.toLowerCase()) || SECRET_KEY_PATTERN.test(key);
+}
+
+function maskString(value: string): string {
+  const uriMatch = value.match(URI_CREDENTIAL_PATTERN);
+  if (uriMatch) {
+    return value.replace(URI_CREDENTIAL_PATTERN, `$1${MASK}$3`);
+  }
+  return value;
+}
+
+function maskValue(value: unknown, keyIsSecret: boolean, extra: Set<string>): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  // Primitives.
+  if (typeof value !== 'object') {
+    if (keyIsSecret) {
+      return MASK;
+    }
+    return typeof value === 'string' ? maskString(value) : value;
+  }
+
+  // A whole secret-keyed object/array is collapsed to the mask (never leak its interior).
+  if (keyIsSecret) {
+    return MASK;
+  }
+
+  // Preserve non-plain objects verbatim (Date, Buffer, etc.) — cloning would lose their type and
+  // they never carry framework secrets.
+  if (value instanceof Date || Buffer.isBuffer(value)) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => maskValue(item, false, extra));
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+    out[key] = maskValue(val, isSecretKey(key, extra), extra);
+  }
+  return out;
+}

package/src/core/modules/hub/helpers/hub-mermaid.helper.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildErDiagram, type HubModelDescriptor } from './hub-mermaid.helper';
+
+describe('buildErDiagram', () => {
+  const models: HubModelDescriptor[] = [
+    {
+      fields: [
+        { name: 'email', type: 'String' },
+        { name: 'age', type: 'Number' },
+        { name: 'company', ref: 'Company', type: 'ObjectId' },
+      ],
+      name: 'User',
+    },
+    {
+      fields: [{ name: 'name', type: 'String' }],
+      name: 'Company',
+    },
+  ];
+
+  it('opens an erDiagram block', () => {
+    const out = buildErDiagram(models);
+    expect(out.startsWith('erDiagram')).toBe(true);
+  });
+
+  it('emits one entity per model with its fields and types', () => {
+    const out = buildErDiagram(models);
+    expect(out).toContain('User {');
+    expect(out).toContain('Company {');
+    expect(out).toContain('String email');
+    expect(out).toContain('Number age');
+  });
+
+  it('renders a relationship for a ref field', () => {
+    const out = buildErDiagram(models);
+    expect(out).toMatch(/User \|\|--o\{ Company : company/);
+  });
+
+  it('ignores refs pointing at models that are not present', () => {
+    const out = buildErDiagram([{ fields: [{ name: 'ghost', ref: 'Missing', type: 'ObjectId' }], name: 'Solo' }]);
+    expect(out).toContain('Solo {');
+    expect(out).not.toContain('Missing');
+  });
+
+  it('sanitizes field/entity names so the diagram stays valid', () => {
+    const out = buildErDiagram([{ fields: [{ name: 'weird-field.name', type: 'String' }], name: 'Odd Name' }]);
+    expect(out).not.toContain('weird-field.name');
+    expect(out).not.toContain('Odd Name {');
+  });
+
+  it('handles an empty model list without throwing', () => {
+    expect(buildErDiagram([])).toBe('erDiagram');
+  });
+});

package/src/core/modules/hub/helpers/hub-mermaid.helper.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure builder for a Mermaid `erDiagram` from a normalized description of the Mongoose models.
+ *
+ * The CoreHubDbService walks `connection.models` and the ModelRegistry to produce the descriptors;
+ * keeping the string builder pure makes it unit-testable without a live database and CDN-free
+ * (the client shows the source + a mermaid.live link; no diagram library ships with the framework).
+ */
+
+export interface HubModelDescriptor {
+  fields: HubModelField[];
+  name: string;
+}
+
+export interface HubModelField {
+  name: string;
+  /** Referenced model name (Mongoose `ref`), if this field is a relation. */
+  ref?: string;
+  /** Human-readable type label (String, Number, ObjectId, …). */
+  type: string;
+}
+
+/** Mermaid identifiers must be alphanumeric/underscore; collapse everything else. */
+function sanitizeIdentifier(value: string): string {
+  const cleaned = String(value ?? '').replace(/[^A-Za-z0-9_]/g, '_');
+  return /^[A-Za-z_]/.test(cleaned) ? cleaned : `_${cleaned}`;
+}
+
+/**
+ * Build a Mermaid `erDiagram`. Entities carry their fields (`Type name`); ref fields become
+ * one-to-many relationships (`A ||--o{ B : field`) when the target model is also present.
+ */
+export function buildErDiagram(models: HubModelDescriptor[]): string {
+  if (!models || models.length === 0) {
+    return 'erDiagram';
+  }
+
+  const present = new Set(models.map((m) => m.name));
+  const lines: string[] = ['erDiagram'];
+
+  for (const model of models) {
+    const entity = sanitizeIdentifier(model.name);
+    lines.push(`  ${entity} {`);
+    for (const field of model.fields) {
+      const type = sanitizeIdentifier(field.type || 'Mixed');
+      const name = sanitizeIdentifier(field.name);
+      lines.push(`    ${type} ${name}`);
+    }
+    lines.push('  }');
+  }
+
+  for (const model of models) {
+    const from = sanitizeIdentifier(model.name);
+    for (const field of model.fields) {
+      if (field.ref && present.has(field.ref)) {
+        const to = sanitizeIdentifier(field.ref);
+        lines.push(`  ${from} ||--o{ ${to} : ${sanitizeIdentifier(field.name)}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/core/modules/hub/helpers/hub-shell.helper.spec.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildHubCsp,
+  buildHubSecurityHeaders,
+  escapeHtml,
+  escapeJsString,
+  generateNonce,
+  injectNonce,
+} from './hub-shell.helper';
+
+describe('hub-shell.helper', () => {
+  describe('escapeHtml', () => {
+    it('escapes all five HTML-significant characters', () => {
+      expect(escapeHtml(`<img src="x" onerror='y'>&`)).toBe('&lt;img src=&quot;x&quot; onerror=&#39;y&#39;&gt;&amp;');
+    });
+
+    it('neutralizes a script-tag XSS payload', () => {
+      const out = escapeHtml('<script>alert(1)</script>');
+      expect(out).not.toContain('<script>');
+      expect(out).toContain('&lt;script&gt;');
+    });
+
+    it('handles empty / non-string-ish input', () => {
+      expect(escapeHtml('')).toBe('');
+    });
+  });
+
+  describe('escapeJsString', () => {
+    it('escapes characters that would break out of a JS string / script context', () => {
+      const out = escapeJsString(`a'b\\c</script>`);
+      expect(out).not.toContain('</script>');
+      expect(out).toContain("\\'");
+      expect(out).toContain('\\\\');
+      // The closing angle bracket must be escaped so `</script>` cannot terminate the tag.
+      expect(out).toContain('\\u003c');
+    });
+
+    it('escapes CR / LF into their JS escapes', () => {
+      const out = escapeJsString('line1\r\nline2');
+      expect(out).toBe('line1\\r\\nline2');
+    });
+
+    it('escapes U+2028 / U+2029, which are line terminators inside a JS string literal', () => {
+      // Built via fromCharCode so this test file stays pure ASCII (a literal separator would itself
+      // terminate the source line). A raw U+2028 in a `'...'` literal is a syntax error at runtime.
+      const lineSep = String.fromCharCode(0x2028);
+      const paraSep = String.fromCharCode(0x2029);
+      const out = escapeJsString(`before${lineSep}mid${paraSep}after`);
+      expect(out).toContain('\\u2028');
+      expect(out).toContain('\\u2029');
+      expect(out).not.toContain(lineSep);
+      expect(out).not.toContain(paraSep);
+      // The escaped result must be a valid single-line JS string literal.
+      expect(() => new Function(`return '${out}';`)()).not.toThrow();
+      expect(new Function(`return '${out}';`)()).toBe(`before${lineSep}mid${paraSep}after`);
+    });
+  });
+
+  describe('generateNonce', () => {
+    it('produces a non-empty base64 nonce that differs each call', () => {
+      const a = generateNonce();
+      const b = generateNonce();
+      expect(a.length).toBeGreaterThan(10);
+      expect(a).not.toBe(b);
+    });
+  });
+
+  describe('injectNonce', () => {
+    it('replaces every __CSP_NONCE__ placeholder', () => {
+      const html = `<style nonce="__CSP_NONCE__"></style><script nonce="__CSP_NONCE__"></script>`;
+      const out = injectNonce(html, 'abc123');
+      expect(out).not.toContain('__CSP_NONCE__');
+      expect(out).toContain('nonce="abc123"');
+      expect((out.match(/abc123/g) ?? []).length).toBe(2);
+    });
+  });
+
+  describe('buildHubCsp', () => {
+    it('is a strict, self-contained policy pinned to the nonce', () => {
+      const csp = buildHubCsp('nonce123');
+      expect(csp).toContain("default-src 'none'");
+      expect(csp).toContain("script-src 'nonce-nonce123'");
+      expect(csp).toContain("frame-ancestors 'none'");
+      expect(csp).not.toContain('unsafe-inline');
+    });
+  });
+
+  describe('buildHubSecurityHeaders', () => {
+    it('returns the strict header set with no-store for HTML by default', () => {
+      const headers = buildHubSecurityHeaders('n1');
+      expect(headers['Content-Security-Policy']).toContain('nonce-n1');
+      expect(headers['X-Frame-Options']).toBe('DENY');
+      expect(headers['X-Content-Type-Options']).toBe('nosniff');
+      expect(headers['Referrer-Policy']).toBe('no-referrer');
+      expect(headers['Cache-Control']).toContain('no-store');
+    });
+
+    it('uses a long-lived immutable cache for the cacheable script bundle', () => {
+      const headers = buildHubSecurityHeaders('n1', { cacheable: true });
+      expect(headers['Cache-Control']).toContain('max-age');
+      expect(headers['Cache-Control']).toContain('immutable');
+      expect(headers['Cache-Control']).not.toContain('no-store');
+    });
+  });
+});

package/src/core/modules/hub/helpers/hub-shell.helper.ts

@@ -0,0 +1,90 @@
+import { randomBytes } from 'crypto';
+
+/**
+ * Pure helpers for the Hub's self-contained HTML shell: escaping, CSP nonce handling and the
+ * response security-header set. Kept free of Express/Nest types so they are trivially unit-testable
+ * and reusable from both the page controller and the email-preview route.
+ */
+
+/** Placeholder written into the shell template; replaced per-request by {@link injectNonce}. */
+export const HUB_NONCE_PLACEHOLDER = '__CSP_NONCE__';
+
+// Unicode line/paragraph separators. Built via fromCharCode so the source file stays pure ASCII —
+// a literal U+2028/U+2029 in a regex literal would itself terminate the line and break parsing.
+const LINE_SEPARATOR = String.fromCharCode(0x2028);
+const PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029);
+
+/** Escape the five HTML-significant characters. Every server-provided value in the shell goes through this. */
+export function escapeHtml(value: string): string {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Escape a value for embedding inside a `<script>` JS string literal. Escapes backslash, single
+ * quote and the `<` character (as `<`) so a `</script>` sequence in the data cannot terminate
+ * the surrounding tag. Also escapes U+2028 / U+2029, which are literal line terminators inside a
+ * JS string and would otherwise break the script (or enable injection) despite looking like text.
+ */
+export function escapeJsString(value: string): string {
+  return String(value ?? '')
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/</g, '\\u003c')
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n')
+    .split(LINE_SEPARATOR)
+    .join('\\u2028')
+    .split(PARAGRAPH_SEPARATOR)
+    .join('\\u2029');
+}
+
+/** Generate a fresh per-request CSP nonce. */
+export function generateNonce(): string {
+  return randomBytes(16).toString('base64');
+}
+
+/** Replace every {@link HUB_NONCE_PLACEHOLDER} in a pre-built shell string with the actual nonce. */
+export function injectNonce(html: string, nonce: string): string {
+  return html.split(HUB_NONCE_PLACEHOLDER).join(nonce);
+}
+
+/**
+ * Build the strict Content-Security-Policy for a Hub HTML response. `default-src 'none'` denies
+ * everything by default; scripts and styles are allowed only via the per-request nonce (plus `'self'`
+ * for the shared hub.js bundle). No `unsafe-inline`, no external origins.
+ */
+export function buildHubCsp(nonce: string): string {
+  return [
+    "default-src 'none'",
+    `script-src 'nonce-${nonce}' 'self'`,
+    `style-src 'nonce-${nonce}'`,
+    "img-src 'self' data:",
+    "connect-src 'self'",
+    "frame-src 'self'",
+    "frame-ancestors 'none'",
+    "base-uri 'none'",
+    "form-action 'self'",
+  ].join('; ');
+}
+
+/**
+ * The full response header set for Hub responses.
+ *
+ * @param nonce - the per-request CSP nonce
+ * @param opts.cacheable - when true, use a long-lived immutable cache (for the versioned hub.js
+ *   bundle); otherwise `no-store` (HTML pages and JSON sidecars must never be cached)
+ */
+export function buildHubSecurityHeaders(nonce: string, opts?: { cacheable?: boolean }): Record<string, string> {
+  return {
+    'Cache-Control': opts?.cacheable ? 'private, max-age=86400, immutable' : 'no-store',
+    'Content-Security-Policy': buildHubCsp(nonce),
+    'Referrer-Policy': 'no-referrer',
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+  };
+}

package/src/core/modules/hub/hub-action-messages.ts

@@ -0,0 +1,47 @@
+/**
+ * Centralized admin-facing messages for the Hub's mutating actions.
+ *
+ * The Hub deliberately does NOT route these through the ErrorCode i18n catalog: that module is
+ * OPTIONAL (a consumer project may not register it — e.g. `errorCode.autoRegister: false`), so the
+ * Hub, which must stay self-contained, cannot hard-depend on it. It is also a single-admin operator
+ * tool where a plain English message is the right level of detail — not something an end-user sees.
+ *
+ * Centralizing the strings here (instead of scattering literals across the action controller and
+ * services) keeps the wording consistent and reusable, and gives a single place to review every
+ * message the mutating-action surface can emit. See the Hub README ("Action errors").
+ *
+ * Pure, import-free data — safe to import from anywhere in the module.
+ */
+export const HubActionMessage = {
+  /** Generic fallback when an action throws a non-Error value. */
+  actionFailed: 'Action failed.',
+  /** Delete file: the typed confirmation filename did not match the stored filename. */
+  confirmationFilenameMismatch: 'Confirmation filename does not match.',
+  /** Delete file: no confirmation filename was supplied. */
+  confirmationFilenameRequired: 'Confirmation filename required.',
+  /** Test mail: the EmailService is not wired into this app. */
+  emailServiceUnavailable: 'EmailService is not available.',
+  /** Delete file: no GridFS file with the given id. */
+  fileNotFound: 'File not found.',
+  /** Delete file: the id is not a valid ObjectId. */
+  invalidFileId: 'Invalid file id.',
+  /** Migrations action while the migrations panel is disabled. */
+  migrationsDisabled: 'The migrations panel is disabled.',
+  /** CSRF guard: the mutating request lacked the X-Hub-Request header. */
+  missingHubRequestHeader: 'Missing X-Hub-Request header.',
+  /** Any action that needs the Mongo connection while it is unavailable. */
+  mongoUnavailable: 'No MongoDB connection is available.',
+  /** Migrations action while no Mongo URI is configured. */
+  mongoUriMissing: 'No MongoDB URI is configured.',
+  /** Test mail: no recipient supplied. */
+  recipientRequired: 'Recipient (to) required.',
+  /** Clear-collector action with an unknown collector name. */
+  unknownCollector: 'Unknown collector.',
+  /** Cron action with an unknown sub-action (not start/stop/trigger). */
+  unknownCronAction: 'Unknown cron action.',
+
+  /** Confirm-guarded action: the typed keyword did not match the expected one. */
+  confirmationKeywordMismatch: (expected: string): string => `Confirmation keyword mismatch (expected "${expected}").`,
+  /** Test mail: the requested template is not in the inventory (allowlist). */
+  unknownEmailTemplate: (name: string): string => `Unknown email template "${name}".`,
+} as const;