@lenne.tech/nest-server 11.31.2 → 11.31.3

package/docs/REQUEST-LIFECYCLE.md

@@ -213,6 +213,7 @@ JWT-based authentication for existing projects:
 | **Health Check Module** | `GET /health` + GraphQL `healthCheck` query |
 | **Error Code Module** | Centralized error registry with unique IDs |
 | **Permissions Report** | Interactive HTML dashboard, JSON, and Markdown reports |
+| **Hub (Operator Cockpit)** | Build-free ADMIN-gated dashboard at `/hub` (config-gated per environment). Adds an optional HTTP trace middleware (registered by `CoreHubModule.configure()` only when traces are enabled), a chaining `Logger.overrideLogger()` delegate for the log buffer, an optional `EmailService` capture hook (`HUB_EMAIL_CAPTURE` token) for the mailbox, and — when the query profiler is enabled — opts the MongoDB driver into `monitorCommands` from `core.module.ts`. See `src/core/modules/hub/README.md`. |
 | **System Setup Module** | Initial admin creation for fresh deployments |
 | **Cron Jobs** | `CoreCronJobsService` with timezone/UTC offset support |
 | **Model Documentation** | Auto-generated model docs via `ModelDocService` |

package/migration-guides/11.31.2-to-11.31.3.md

@@ -0,0 +1,135 @@
+# Migration Guide: 11.31.2 → 11.31.3
+
+## Overview
+
+| Category | Effort | Required? |
+|----------|--------|-----------|
+| **New Feature** | Opt-in | No — purely additive |
+| Breaking Changes | None | — |
+| Config Changes | Optional | Only if you enable the Hub |
+
+This release adds the **Hub** — a build-free, ADMIN-gated operator cockpit served directly by the
+framework at `/hub`. It is **disabled by default** and must be switched on per environment, so
+existing projects are unaffected until they opt in. No code changes are required to update.
+
+It also includes a **security patch**: three moderate `axios` advisories (recursion DoS + prototype
+pollution, transitive via the Brevo and Mailjet mail SDKs) are closed by pinning `axios` to `1.18.1`.
+Nothing to do on your side — just update.
+
+## Quick Migration
+
+```bash
+# Update package
+pnpm update @lenne.tech/nest-server
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+Nothing else is required — the Hub stays dormant (every `/hub` route answers 404) until you add a
+`hub` block to a config environment.
+
+## What's New in 11.31.3
+
+### Hub — admin area / operator cockpit
+
+A dependency-free dashboard of runtime information and admin tools, rendered as server-side HTML +
+a vanilla-JS SPA (no React, no build step), so it works identically in npm- and vendor-mode.
+
+**16 panels:** Dashboard, Diagnostics, Logs, Request Traces, Query Performance, Cron Jobs, Database,
+Models/ERD, Migrations, Files (GridFS), Config (secrets masked), Auth Migration (Legacy→IAM), Error
+Codes, Email Preview, Mailbox, AI. Each has a `*.json` sidecar (the stable data contract) the client
+polls; optional sources degrade to an "unavailable" state instead of erroring.
+
+**3 runtime collectors** (in-memory ring buffers, per-app-instance, parallel-test-safe):
+- **Logs** — a chaining `Logger.overrideLogger()` delegate (no main.ts change), secrets redacted.
+- **Traces** — an Express middleware bound only when the collector is enabled (zero cost otherwise).
+- **Queries** — MongoDB driver command monitoring; records value-free query SHAPES (N+1 templates),
+  never values. Enabling it opts the driver into `monitorCommands`.
+
+**Built-in Mailbox** — a Mailpit-style capture of outgoing mail hooked into `EmailService`. In
+`mode: 'capture'` mail is recorded and NOT sent (dev/test); in `mode: 'copy'` it is sent AND a copy
+is recorded (with tokens/links redacted in the stored copy). `capture` throws at startup in
+`production`/`staging` so it can never silently swallow real mail.
+
+**Admin actions** (opt-out via `hub.actions: false`) — migrations run/rollback, GridFS file delete,
+cron start/stop/trigger, collector-buffer clear, test mail. Every mutating request requires the
+`X-Hub-Request: 1` header (CSRF defense) and destructive ones a server-validated type-to-confirm
+keyword; each writes a `[HUB-ACTION] <action> by user <id>` audit line.
+
+#### Enable it
+
+The Hub is **never enabled implicitly** — switch it on per environment in `config.env.ts`:
+
+```typescript
+// config.env.ts (development / local)
+hub: {
+  collectors: { queries: true },   // opt-in query profiler
+  mailbox: { mode: 'capture' },    // capture outgoing mail locally (Mailpit replacement)
+},
+
+// production — usually omit `hub` entirely. If you do want it (still ADMIN-gated),
+// never use mailbox capture mode there:
+// hub: { mailbox: false },
+```
+
+Boolean shorthand `hub: true` enables it at `/hub`, admin-only, with default collectors. See
+`IHubConfig` for every option. Env-var equivalents exist via `NSC__HUB__*` (see `.env.example`).
+
+Then sign in as a user with `RoleEnum.ADMIN` and open `/hub`. The shell is self-sufficient: if you
+are not authenticated it shows a login form that posts to `loginEndpoint` (default
+`/iam/sign-in/email`), so an admin can sign in directly at the API without the frontend. In a
+fullstack setup, a cross-subdomain session cookie from the app login already authenticates `/hub`.
+
+#### Customization (optional)
+
+Replace any Hub controller/service with a project subclass via `CoreModule.forRoot`:
+
+```typescript
+CoreModule.forRoot(envConfig, {
+  hub: {
+    controller: MyHubController,           // extends CoreHubController
+    actionsController: MyHubActionsController, // extends CoreHubActionsController
+    service: MyHubService,                 // extends CoreHubService
+    htmlService: MyHubHtmlService,         // extends CoreHubHtmlService
+    actionsService: MyHubActionsService,   // extends CoreHubActionsService
+  },
+});
+```
+
+## Breaking Changes
+
+None. The Hub is opt-in and disabled by default.
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| Projects that never set `hub` | Unaffected | Every `/hub` route answers 404 |
+| Custom `EmailService` subclass | Compatible | The mailbox capture hook is injected optionally (`@Optional()`) — absent when the Hub/mailbox is off, so there is zero cost and no behavior change |
+| No auth system enabled | ⚠️ Action required | The Hub relies on the app-wide `RolesGuard`/`BetterAuthRolesGuard` to enforce `@Roles(ADMIN)`. With BetterAuth and legacy auth both disabled, no guard runs and the gate is inert — keep an auth module enabled or leave the Hub disabled |
+| `queries` collector enabled | Compatible | Opts the MongoDB driver into `monitorCommands` from `core.module.ts` when the consumer has not set it |
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `/hub` → 404 everywhere | `hub` is not set in that environment's config block — add `hub: true` (or an options object) |
+| Startup error mentioning mailbox `capture` | `mailbox.mode: 'capture'` is forbidden in `production`/`staging` — use `copy` or disable the mailbox there |
+| Query panel empty | The queries collector is opt-in — set `hub.collectors.queries: true` |
+| Cron panel empty | Import `ScheduleModule.forRoot()` in your ServerModule |
+| Hub reachable without login | You disabled all auth systems, so no roles guard runs — see the Compatibility note above |
+
+## Module Documentation
+
+- `src/core/modules/hub/README.md` — full panel/action/collector/security reference
+- `src/core/modules/hub/INTEGRATION-CHECKLIST.md` — config-only setup + common mistakes
+- `.claude/rules/configurable-features.md` — Hub row in the configurable-features table
+
+## References
+
+- Configurable-features pattern: `.claude/rules/configurable-features.md`
+- Request lifecycle (middleware + logger override + email hook): `docs/REQUEST-LIFECYCLE.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.31.2",
+  "version": "11.31.3",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -23,9 +23,9 @@
     "build:dev": "pnpm run build",
     "c": "pnpm run check",
     "check": "node scripts/check.mjs",
-    "check:raw": "pnpm install --frozen-lockfile && pnpm audit && pnpm run format:check && pnpm run lint && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
-    "check:fix": "pnpm install && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
-    "check:naf": "pnpm install && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:raw": "pnpm install --frozen-lockfile && pnpm audit && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:fix": "pnpm install && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:naf": "pnpm install && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:manifest": "node scripts/check-package-manifest.mjs",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",
     "cf": "pnpm run check:fix",
@@ -65,6 +65,7 @@
     "vitest:unit:cov": "vitest run --coverage --config vitest.config.ts",
     "test:unit:watch": "vitest --config vitest.config.ts",
     "test:types": "tsc --noEmit --skipLibCheck -p tests/types/tsconfig.json",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
     "test:cleanup": "find tests -type f \\( -name '*.txt' -o -name '*.bin' \\) -not -name '.gitkeep' -delete && echo 'Test artifacts cleaned up'",
     "watch": "npm-watch"
   },

package/src/config.env.ts

@@ -20,6 +20,7 @@ import { IServerOptions } from './core/common/interfaces/server-options.interfac
 // which is purely cosmetic and carries promotional content. Warnings (`⚠`) for genuine
 // misconfiguration still surface.
 dotenv.config({ quiet: true });
+
 const config: { [env: string]: IServerOptions } = {
   // ===========================================================================
   // CI environment
@@ -141,6 +142,10 @@ const config: { [env: string]: IServerOptions } = {
       modelDocumentation: false,
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-ci',
     },
+    hub: {
+      collectors: { queries: { warnMs: 1 } },
+      mailbox: { mode: 'capture' },
+    },
     permissions: true,
     port: Number(process.env.PORT) || 3000,
     security: {
@@ -260,6 +265,14 @@ const config: { [env: string]: IServerOptions } = {
       modelDocumentation: false,
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-dev',
     },
+    // Hub (operator cockpit) — OPTIONAL and enabled PER ENVIRONMENT (it is never on implicitly).
+    // `queries` (query profiler) and `mailbox` are opt-in; the whole thing stays ADMIN-gated.
+    // See src/core/modules/hub/README.md. In production it is off by default (see that block for how
+    // to enable it safely). Also toggleable via `NSC__HUB__*` env vars (see .env.example).
+    hub: {
+      collectors: { queries: true },
+      mailbox: { mode: 'capture' },
+    },
     permissions: true,
     port: Number(process.env.PORT) || 3000,
     security: {
@@ -405,6 +418,10 @@ const config: { [env: string]: IServerOptions } = {
       modelDocumentation: false,
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-e2e',
     },
+    hub: {
+      collectors: { queries: { warnMs: 1 } },
+      mailbox: { mode: 'capture' },
+    },
     permissions: true,
     port: Number(process.env.PORT) || 3000,
     security: {
@@ -559,9 +576,14 @@ const config: { [env: string]: IServerOptions } = {
       modelDocumentation: true,
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-local',
     },
-    permissions: {
-      role: false,
+    hub: {
+      collectors: { queries: true },
+      mailbox: { mode: 'capture' },
     },
+    // Authored intent: ADMIN-gated (reach it via the Hub's "Routes / Permissions" panel). The
+    // permissions-follows-hub invariant is enforced centrally by enforcePermissionsSecurity() below —
+    // e.g. if the Hub here is disabled, that pass flips this to a public localhost-only report.
+    permissions: true,
     port: Number(process.env.PORT) || 3000,
     security: {
       checkResponseInterceptor: {
@@ -665,6 +687,18 @@ const config: { [env: string]: IServerOptions } = {
       },
       enabled: true,
     },
+    // Hub (operator cockpit) is OFF in production by default (never enabled implicitly). To turn it
+    // on here — it stays ADMIN-gated — uncomment the block below. Note the production guard-rails:
+    //   - mailbox: NEVER 'capture' in production/staging (it suppresses real mail; it throws at
+    //     startup). Use `false`, or `{ mode: 'copy' }` if you want a redacted audit copy.
+    //   - collectors.queries: opt-in (it opts the MongoDB driver into command monitoring).
+    // The standalone permissions report follows the Hub (see enforcePermissionsSecurity below), so
+    // enabling the Hub also makes the ADMIN-gated "Routes / Permissions" panel available.
+    // See src/core/modules/hub/README.md; also configurable via NSC__HUB__* (see .env.example).
+    // hub: {
+    //   collectors: { queries: false },
+    //   mailbox: false,
+    // },
     ignoreSelectionsForPopulate: true,
     jwt: {
       refresh: {
@@ -716,6 +750,45 @@ const config: { [env: string]: IServerOptions } = {
   },
 };
 
+/**
+ * Enforce the permissions-report security invariant across every environment.
+ *
+ * The report is the full authorization map (every route + its required roles + `@Restricted` field
+ * rules) — a reconnaissance goldmine. The Hub does NOT need it (its "Routes / Permissions" panel
+ * reuses the scanner but degrades gracefully when the module is absent), so the rule is about the
+ * DANGEROUS direction: the report must never become a standalone, reachable surface.
+ *
+ * Derived per environment from THAT env's Hub state:
+ * - Hub OFF, non-`local` → report NOT registered (no in-app consumer → pure attack surface). This
+ *   makes the combination "non-local + Hub off + visible permissions" impossible to configure.
+ * - Hub OFF, `local`     → public (`role: false`) report allowed — frictionless, safe ONLY because
+ *   `local` is a non-reachable localhost env with no admin surface.
+ * - Hub ON               → left as authored (ADMIN when enabled, or off — the panel just degrades),
+ *   EXCEPT a public (`role: false`) report is forced back to ADMIN in every non-`local` stage.
+ *
+ * NOTE: runs on the statically-authored config; `NSC__HUB__*` / `NSC__PERMISSIONS__*` env overrides
+ * are applied afterwards by getEnvironmentConfig and take precedence.
+ */
+export function enforcePermissionsSecurity(cfg: { [env: string]: IServerOptions }): void {
+  for (const [envName, opts] of Object.entries(cfg)) {
+    const hub = opts.hub;
+    const hubOn =
+      hub === true || (typeof hub === 'object' && hub !== null && (hub as { enabled?: boolean }).enabled !== false);
+    const perms = opts.permissions;
+    const isPublic = typeof perms === 'object' && perms !== null && (perms as { role?: unknown }).role === false;
+
+    if (!hubOn) {
+      // Hub off: only a public localhost report (in `local`) is allowed; never register it elsewhere.
+      opts.permissions = envName === 'local' ? { role: false } : false;
+    } else if (envName !== 'local' && isPublic) {
+      // Reachable stage with the Hub on: the report must never be public — force the ADMIN gate.
+      opts.permissions = true;
+    }
+  }
+}
+
+enforcePermissionsSecurity(config);
+
 /**
  * Export config merged with other configs and environment variables as default
  */

package/src/core/common/helpers/logging.helper.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+
+import { redactSensitiveText } from './logging.helper';
+
+describe('redactSensitiveText', () => {
+  it('redacts JWTs appearing anywhere in a line', () => {
+    const jwt = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U';
+    const out = redactSensitiveText(`token issued: ${jwt} done`);
+
+    expect(out).not.toContain(jwt);
+    expect(out).toContain('token issued:');
+    expect(out).toContain('done');
+  });
+
+  it('redacts Authorization Bearer values', () => {
+    const out = redactSensitiveText('Authorization: Bearer abcdef1234567890secret');
+
+    expect(out).not.toContain('abcdef1234567890secret');
+    expect(out.toLowerCase()).toContain('authorization');
+  });
+
+  it('redacts key/value secrets regardless of separator or quoting', () => {
+    expect(redactSensitiveText('password=SuperSecret123')).not.toContain('SuperSecret123');
+    expect(redactSensitiveText('token: "abcd1234efgh"')).not.toContain('abcd1234efgh');
+    expect(redactSensitiveText("apiKey='pk_live_9999'")).not.toContain('pk_live_9999');
+    expect(redactSensitiveText('client_secret=verySecretValue')).not.toContain('verySecretValue');
+  });
+
+  it('redacts cookie headers', () => {
+    const out = redactSensitiveText('cookie: session=abc123; other=xyz789');
+
+    expect(out).not.toContain('abc123');
+    expect(out).not.toContain('xyz789');
+  });
+
+  it('redacts reset/verification tokens carried as a URL PATH segment (not key=value)', () => {
+    const link = 'https://app.example.com/verify/AbCdEf0123456789XyZtoken please click';
+    const out = redactSensitiveText(link);
+    expect(out).not.toContain('AbCdEf0123456789XyZtoken');
+    expect(out).toContain('/verify/');
+    // also for reset / set-password style links
+    expect(redactSensitiveText('/reset/SUPERSECRETVALUE1234567890')).not.toContain('SUPERSECRETVALUE1234567890');
+    expect(redactSensitiveText('/set-password/ZZZ1112223334445556667')).not.toContain('ZZZ1112223334445556667');
+  });
+
+  it('leaves harmless short path segments untouched', () => {
+    // Only long token-like segments (>= 16 chars) are masked — normal routes stay readable.
+    const text = 'GET /verify/email done';
+    expect(redactSensitiveText(text)).toBe(text);
+  });
+
+  it('leaves harmless text untouched', () => {
+    const text = 'User signed in successfully with id 507f1f77bcf86cd799439011';
+    expect(redactSensitiveText(text)).toBe(text);
+  });
+
+  it('handles empty / non-secret input without throwing', () => {
+    expect(redactSensitiveText('')).toBe('');
+    expect(redactSensitiveText('plain message')).toBe('plain message');
+  });
+});

package/src/core/common/helpers/logging.helper.ts

@@ -132,3 +132,51 @@ export function maskToken(token: null | string | undefined): string {
   }
   return `${token.substring(0, 4)}...${token.substring(token.length - 4)}`;
 }
+
+/**
+ * Redacts secrets from a free-form log line.
+ *
+ * Composes the individual maskers above into a single regex-based pass for text where the sensitive
+ * value is not at a known position (log messages, error strings). Applied by the Hub log collector
+ * before truncation, so a truncation cut can never leak the prefix of a secret.
+ *
+ * Covers: JWTs anywhere in the line, `Authorization: Bearer …`, common `key=value` secrets
+ * (password/token/secret/apiKey/client_secret/refresh_token/…), and cookie headers.
+ *
+ * @param text - The log line to redact
+ * @returns The line with secret values replaced by masked placeholders
+ *
+ * @example
+ * redactSensitiveText('password=hunter2') // 'password=***'
+ */
+export function redactSensitiveText(text: string): string {
+  if (!text) {
+    return text;
+  }
+  return (
+    text
+      // JWTs anywhere in the line
+      .replace(/eyJ[\w-]{6,}\.[\w-]{6,}\.[\w-]{4,}/g, (match) => maskToken(match))
+      // reset/verification/invite tokens carried as a URL PATH segment (e.g. /verify/<token>,
+      // /reset/<token>) — these have no `key=value`, so the query-style rule below misses them.
+      .replace(
+        /(\/(?:verify|reset|confirm|activate|invite|magic-?link|set-password|change-email)\/)([A-Za-z0-9._~-]{16,})/gi,
+        (_m, prefix, token) => `${prefix}${maskToken(token)}`,
+      )
+      // authorization: Bearer xyz / Authorization=xyz
+      .replace(
+        /(authorization["']?\s*[:=]\s*["']?)(?:Bearer\s+)?([^\s"',;]+)/gi,
+        (_m, prefix, value) => `${prefix}${maskToken(value)}`,
+      )
+      // cookie headers (mask every value, keep names)
+      .replace(
+        /((?:^|[\s,;])cookie["']?\s*[:=]\s*)([^\n]+)/gi,
+        (_m, prefix, value) => `${prefix}${maskCookieHeader(value)}`,
+      )
+      // key/value secrets: password=..., token: "...", apiKey=..., secret=..., client_secret=..., refresh_token=...
+      .replace(
+        /((?:password|passwd|pwd|token|secret|api[-_]?key|client[-_]?secret|refresh[-_]?token|access[-_]?token|private[-_]?key)["']?\s*[:=]\s*["']?)([^\s"',;&}]+)/gi,
+        (_m, prefix, value) => `${prefix}${maskSensitive(value)}`,
+      )
+  );
+}

package/src/core/common/helpers/meta.helper.ts

@@ -15,12 +15,18 @@
  * @see getBuildInfo
  */
 
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
 /** Default environment variable the build commit SHA is baked into. */
 export const DEFAULT_COMMIT_ENV = 'APP_VERSION_COMMIT';
 
 /** Defined value returned when no commit could be resolved. */
 export const UNKNOWN_COMMIT = 'unknown';
 
+/** Cached package.json version lookup (`null` = looked up and not found). */
+let cachedVersion: null | string | undefined;
+
 /**
  * Build identity of the running process.
  */
@@ -64,6 +70,45 @@ export function getBuildInfo(options: { commitEnvName?: string; env?: string; ve
   return {
     commit: getCommit(options.commitEnvName),
     env: options.env,
-    version: options.version || UNKNOWN_COMMIT,
+    version: options.version || getVersion(),
   };
 }
+
+/**
+ * Resolve the semantic version of the running app from its `package.json`.
+ *
+ * Reads the `version` field of the nearest `package.json` (searching up from the current working
+ * directory), cached after the first lookup. This is the deployed app's own version — in a consumer
+ * project that is the API's version, in this repo it is the framework version. Falls back to
+ * `'unknown'` when no `package.json` / version can be resolved.
+ *
+ * Prefer an explicit `IServerOptions.version` when set; this is the zero-config default.
+ */
+export function getVersion(): string {
+  if (cachedVersion !== undefined) {
+    return cachedVersion ?? UNKNOWN_COMMIT;
+  }
+  cachedVersion = null;
+  try {
+    // Walk up from cwd so a monorepo `projects/api` started from the repo root still resolves.
+    let dir = process.cwd();
+    for (let i = 0; i < 6; i++) {
+      const pkgPath = join(dir, 'package.json');
+      if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: string };
+        if (typeof pkg.version === 'string' && pkg.version) {
+          cachedVersion = pkg.version;
+          break;
+        }
+      }
+      const parent = join(dir, '..');
+      if (parent === dir) {
+        break;
+      }
+      dir = parent;
+    }
+  } catch {
+    /* ignore — fall back to 'unknown' */
+  }
+  return cachedVersion ?? UNKNOWN_COMMIT;
+}

package/src/core/common/interfaces/server-options.interface.ts

@@ -18,6 +18,7 @@ import * as SMTPTransport from 'nodemailer/lib/smtp-transport';
 import type * as StreamTransport from 'nodemailer/lib/stream-transport';
 
 import { Falsy } from '../types/falsy.type';
+import { IHubConfig } from '../../modules/hub/interfaces/hub-config.interface';
 import { IPermissions } from '../../modules/permissions/interfaces/permissions.interface';
 import { CronJobConfigWithTimeZone } from './cron-job-config-with-time-zone.interface';
 import { CronJobConfigWithUtcOffset } from './cron-job-config-with-utc-offset.interface';
@@ -1847,6 +1848,24 @@ export interface IServerOptions {
    */
   hostname?: string;
 
+  /**
+   * Hub admin area (operator cockpit).
+   *
+   * A build-free, ADMIN-gated dashboard of runtime information and admin tools (dashboard,
+   * diagnostics, logs, request traces, query profiler, migrations, DB stats, models/ERD, files,
+   * cron jobs, error codes, masked config, auth-migration progress, email preview, built-in mailbox,
+   * AI panel).
+   *
+   * Follows "presence implies enabled" — but is NEVER enabled implicitly. It must be switched on per
+   * environment (here or via `NSC__HUB__*`); no environment inherits it.
+   * - `true` / `{}`: enabled at `/hub`, admin-only, default collectors (logs + traces on, queries off)
+   * - `{ path: 'admin/hub', collectors: { queries: true } }`: custom path + query profiling
+   * - `{ enabled: false }` / `undefined`: disabled — every Hub route answers 404
+   *
+   * @default undefined (disabled)
+   */
+  hub?: boolean | IHubConfig;
+
   /**
    * Ignore selections in fieldSelection
    * [ConfigService must be integrated in ModuleService]
@@ -3312,4 +3331,31 @@ export interface ICoreModuleOverrides {
     controller?: Type<any>;
     service?: Type<any>;
   };
+
+  /**
+   * Override Hub controllers and/or services with project-specific subclasses.
+   *
+   * - `actionsController` must extend `CoreHubActionsController`
+   * - `actionsService` must extend `CoreHubActionsService`
+   * - `controller` must extend `CoreHubController`
+   * - `htmlService` must extend `CoreHubHtmlService`
+   * - `service` must extend `CoreHubService`
+   *
+   * @example
+   * ```typescript
+   * {
+   *   hub: {
+   *     service: MyHubService,
+   *     htmlService: MyHubHtmlService,
+   *   },
+   * }
+   * ```
+   */
+  hub?: {
+    actionsController?: Type<any>;
+    actionsService?: Type<any>;
+    controller?: Type<any>;
+    htmlService?: Type<any>;
+    service?: Type<any>;
+  };
 }

package/src/core/common/services/email.service.ts

@@ -1,12 +1,14 @@
 import { createHash } from 'crypto';
-import { Injectable, OnModuleDestroy } from '@nestjs/common';
+import { Inject, Injectable, OnModuleDestroy, Optional } from '@nestjs/common';
 import nodemailer = require('nodemailer');
 import { Attachment } from 'nodemailer/lib/mailer';
 
 import { isNonEmptyString, isTrue, returnFalse } from '../helpers/input.helper';
 import { MailTransportOptions } from '../interfaces/server-options.interface';
+import { HUB_EMAIL_CAPTURE } from '../../modules/hub/hub.constants';
 import { ConfigService } from './config.service';
 import { TemplateService } from './template.service';
+import type { IHubEmailCapture } from '../../modules/hub/interfaces/hub-config.interface';
 
 /**
  * Email service
@@ -26,6 +28,9 @@ export class EmailService implements OnModuleDestroy {
   constructor(
     protected configService: ConfigService,
     protected templateService: TemplateService,
+    // Optional Hub mailbox hook. When the Hub mailbox is enabled it captures outgoing mail (and, in
+    // capture mode, suppresses the actual send). Undefined otherwise — zero cost.
+    @Optional() @Inject(HUB_EMAIL_CAPTURE) protected readonly emailCapture?: IHubEmailCapture,
   ) {}
 
   onModuleDestroy(): void {
@@ -104,6 +109,33 @@ export class EmailService implements OnModuleDestroy {
       }
     }
 
+    // Hub mailbox capture (Mailpit-style). Runs after templates are rendered, before the transport.
+    // In capture mode it records the mail and suppresses the send (returns a jsonTransport-like ack).
+    // Fully guarded: a broken mailbox hook must never break (or crash) the mail path.
+    if (this.emailCapture) {
+      let skipTransport = false;
+      try {
+        skipTransport = this.emailCapture.capture({
+          from: `"${senderName}" <${senderEmail}>`,
+          html,
+          subject,
+          templateName: htmlTemplate ?? textTemplate,
+          text,
+          to: Array.isArray(recipients) ? recipients.join(', ') : recipients,
+        });
+      } catch {
+        /* mailbox capture must never break mail sending */
+      }
+      if (skipTransport) {
+        return {
+          accepted: Array.isArray(recipients) ? recipients : [recipients],
+          captured: true,
+          messageId: 'hub-mailbox',
+          rejected: [],
+        };
+      }
+    }
+
     // Reuse transporter if SMTP config hasn't changed (avoids creating new connections per email)
     // Use hash instead of raw JSON to avoid keeping credentials as a string in memory
     const smtpKey = createHash('sha256').update(JSON.stringify(smtp)).digest('hex');

package/src/core/common/services/template.service.ts

@@ -2,7 +2,7 @@ import { Injectable } from '@nestjs/common';
 import { TemplateFunction } from 'ejs';
 import ejs = require('ejs');
 import fs = require('fs');
-import { join } from 'path';
+import { resolve, sep } from 'path';
 
 import { ConfigService } from './config.service';
 
@@ -36,27 +36,32 @@ export class TemplateService {
    * @param filePath Directory names (separated via '/' if template is in subdirectory) + name of the template file without extension
    */
   protected async getTemplate(filePath: string): Promise<TemplateFunction> {
-    return new Promise<TemplateFunction>((resolve, reject) => {
+    // Resolve the template file to an absolute path and enforce that it stays within the configured
+    // templates directory. Legitimate template names never contain '..'; this guard is a defense in
+    // depth against path traversal for any caller that forwards user-influenced template names.
+    const baseDir = resolve(this.configService.getFastButReadOnly('templates.path'));
+    const fullPath = resolve(baseDir, `${filePath}.ejs`);
+    if (fullPath !== baseDir && !fullPath.startsWith(baseDir + sep)) {
+      throw new Error(`Invalid template path "${filePath}".`);
+    }
+
+    return new Promise<TemplateFunction>((res, reject) => {
       // Get template from cache
       if (this.templates[filePath]) {
-        resolve(this.templates[filePath]);
+        res(this.templates[filePath]);
         return;
       }
 
       // Get template file
-      fs.readFile(
-        `${join(this.configService.getFastButReadOnly('templates.path'), filePath)}.ejs`,
-        { encoding: 'utf8' },
-        (err, data) => {
-          if (err) {
-            reject(err);
-          } else {
-            // Compile and return template
-            this.templates[filePath] = ejs.compile(data);
-            resolve(this.templates[filePath]);
-          }
-        },
-      );
+      fs.readFile(fullPath, { encoding: 'utf8' }, (err, data) => {
+        if (err) {
+          reject(err);
+        } else {
+          // Compile and return template
+          this.templates[filePath] = ejs.compile(data);
+          res(this.templates[filePath]);
+        }
+      });
     });
   }
 }