@lenne.tech/nest-server 11.31.2 → 11.32.0

package/src/core/modules/hub/services/hub-query-profiler.service.ts

@@ -0,0 +1,274 @@
+import { Inject, Injectable, Logger, OnModuleDestroy, OnModuleInit, Optional } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import { Connection } from 'mongoose';
+
+import { redactSensitiveText } from '../../../common/helpers/logging.helper';
+import { HUB_CONFIG, HUB_QUERY_PENDING_LIMIT } from '../hub.constants';
+import { HubRingBuffer } from '../hub-ring-buffer';
+import { normalizeCommandShape } from '../helpers/hub-command-shape.helper';
+import { HubQueriesData, HubQueryRecord, HubQueryTemplate } from '../interfaces/hub-panels.interface';
+import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+
+interface ProfilerRecord extends HubQueryRecord {
+  timestamp: number;
+}
+
+interface PendingCommand {
+  collection: string;
+  operation: string;
+  shape: string;
+}
+
+/**
+ * Admin/heartbeat/metadata commands that are pure noise for a query profiler.
+ *
+ * `dbstats` / `listcollections` / `listindexes` are metadata reads (issued, among others, by the
+ * Hub's own DB panel) and are never app-level queries worth profiling. `aggregate` and `find` are
+ * deliberately NOT ignored — they carry real query shapes — so the Hub's own `$collStats`/`find`
+ * self-noise on the DB/Files panels is inherent and cannot be filtered by command name alone.
+ */
+const DEFAULT_IGNORE = new Set([
+  'authenticate',
+  'buildinfo',
+  'connectionstatus',
+  'dbstats',
+  'getnonce',
+  'getparameter',
+  'hello',
+  'ismaster',
+  'listcollections',
+  'listindexes',
+  'logout',
+  'ping',
+  'saslcontinue',
+  'saslstart',
+]);
+
+/** Only these command names carry a query shape worth normalizing. */
+const SHAPED_FIELDS = ['filter', 'query', 'pipeline', 'sort', 'projection', 'q', 'u', 'updates', 'deletes'];
+
+/**
+ * MongoDB query profiler backed by driver command monitoring.
+ *
+ * Requires the connection to be created with `monitorCommands: true` (opted in from core.module.ts
+ * only when this collector is enabled). Records command SHAPES (values → '?') — never values — which
+ * doubles as the N+1 template key. Zero cost when disabled: no `getClient`, no listeners.
+ */
+@Injectable()
+export class HubQueryProfilerService implements OnModuleDestroy, OnModuleInit {
+  protected readonly logger = new Logger(HubQueryProfilerService.name);
+
+  private buffer?: HubRingBuffer<ProfilerRecord>;
+  private client?: {
+    off?: (e: string, l: (...a: any[]) => void) => void;
+    on: (e: string, l: (...a: any[]) => void) => void;
+    options?: { monitorCommands?: boolean };
+    removeListener?: (e: string, l: (...a: any[]) => void) => void;
+  };
+  private cfg?: Exclude<ResolvedHubConfig['collectors']['queries'], false>;
+  private ignore = DEFAULT_IGNORE;
+  // Hot-path driver-event handlers. Each is fully guarded: an exception here runs inside the MongoDB
+  // driver's synchronous `emit()`, so it would surface as an UNCAUGHT exception and take the whole
+  // process down. Observability must never crash the app — swallow everything.
+  private readonly onFailed = (e: any): void => this.safe(() => this.handleFinished(e, e?.failure?.message));
+  private readonly onStarted = (e: any): void => this.safe(() => this.handleStarted(e));
+  private readonly onSucceeded = (e: any): void => this.safe(() => this.handleFinished(e, undefined));
+  private readonly pending = new Map<number, PendingCommand>();
+
+  constructor(
+    @Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig,
+    @Optional() @InjectConnection() protected readonly connection?: Connection,
+  ) {}
+
+  /** Clear the buffer (Hub action). */
+  clear(): void {
+    this.buffer?.clear();
+    this.pending.clear();
+  }
+
+  get enabled(): boolean {
+    return this.config.collectors.queries !== false;
+  }
+
+  getData(): HubQueriesData {
+    const records = this.buffer?.recent() ?? [];
+    return {
+      cursor: this.buffer?.lastSeq ?? -1,
+      recent: records.slice(-100),
+      slowest: [...records].sort((a, b) => b.durationMs - a.durationMs).slice(0, 10),
+      summary: this.summary(records),
+      topTemplates: this.topTemplates(records),
+    };
+  }
+
+  onModuleDestroy(): void {
+    if (!this.client) {
+      return;
+    }
+    const off = this.client.removeListener ?? this.client.off;
+    off?.call(this.client, 'commandStarted', this.onStarted);
+    off?.call(this.client, 'commandSucceeded', this.onSucceeded);
+    off?.call(this.client, 'commandFailed', this.onFailed);
+    this.pending.clear();
+    this.client = undefined;
+  }
+
+  onModuleInit(): void {
+    if (this.config.collectors.queries === false) {
+      return; // zero cost when disabled
+    }
+    this.cfg = this.config.collectors.queries;
+    this.buffer = new HubRingBuffer<ProfilerRecord>(this.cfg.capacity);
+    if (this.cfg.ignoreCommands?.length) {
+      this.ignore = new Set(this.cfg.ignoreCommands.map((c) => c.toLowerCase()));
+    }
+    const client = this.connection?.getClient?.() as unknown as HubQueryProfilerService['client'];
+    if (!client) {
+      return;
+    }
+    if (client.options?.monitorCommands !== true) {
+      this.logger.warn(
+        'hub.collectors.queries is enabled but the MongoDB driver was not started with monitorCommands — query profiling is inactive.',
+      );
+      return;
+    }
+    this.client = client;
+    client.on('commandStarted', this.onStarted);
+    client.on('commandSucceeded', this.onSucceeded);
+    client.on('commandFailed', this.onFailed);
+  }
+
+  /** Run a hot-path handler, swallowing any error so it can never escape into the driver's emit(). */
+  protected safe(fn: () => void): void {
+    try {
+      fn();
+    } catch {
+      /* observability must never crash the app */
+    }
+  }
+
+  protected classify(durationMs: number): HubQueryRecord['classification'] {
+    if (!this.cfg) {
+      return 'ok';
+    }
+    if (durationMs > this.cfg.criticalMs) {
+      return 'critical';
+    }
+    if (durationMs > this.cfg.warnMs) {
+      return 'warn';
+    }
+    return 'ok';
+  }
+
+  protected handleFinished(event: { duration?: number; requestId?: number }, errorMessage?: string): void {
+    const requestId = event?.requestId;
+    if (requestId === undefined) {
+      return;
+    }
+    const pending = this.pending.get(requestId);
+    this.pending.delete(requestId);
+    if (!pending || !this.buffer) {
+      return;
+    }
+    const durationMs = Number(event.duration ?? 0);
+    this.buffer.add({
+      classification: this.classify(durationMs),
+      collection: pending.collection,
+      commandSummary: pending.shape,
+      durationMs,
+      errorMessage: errorMessage ? redactSensitiveText(String(errorMessage)).slice(0, 300) : undefined,
+      failed: !!errorMessage,
+      operation: pending.operation,
+      requestId,
+    } as Omit<ProfilerRecord, 'seq' | 'timestamp'>);
+  }
+
+  protected handleStarted(event: {
+    command?: Record<string, unknown>;
+    commandName?: string;
+    requestId?: number;
+  }): void {
+    const operation = String(event?.commandName ?? '').toLowerCase();
+    if (!operation || this.ignore.has(operation) || event.requestId === undefined) {
+      return;
+    }
+    const command = event.command ?? {};
+    const collection = this.extractCollection(command, operation);
+    const shape = this.buildShape(operation, collection, command);
+
+    // Bound the pending map even if succeeded/failed events are lost (connection drop).
+    if (this.pending.size >= HUB_QUERY_PENDING_LIMIT) {
+      const oldest = this.pending.keys().next().value;
+      if (oldest !== undefined) {
+        this.pending.delete(oldest);
+      }
+    }
+    this.pending.set(event.requestId, { collection, operation, shape });
+  }
+
+  private buildShape(operation: string, collection: string, command: Record<string, unknown>): string {
+    const sections: Record<string, unknown> = {};
+    for (const field of SHAPED_FIELDS) {
+      if (command[field] !== undefined) {
+        sections[field] = normalizeCommandShape(command[field]);
+      }
+    }
+    if (Array.isArray(command.documents)) {
+      sections.documents = `documents(${command.documents.length})`;
+    }
+    const maxLen = this.cfg?.maxShapeLength ?? 512;
+    return `${operation} ${collection} ${JSON.stringify(sections)}`.slice(0, maxLen);
+  }
+
+  private extractCollection(command: Record<string, unknown>, operation: string): string {
+    const byName = command[operation] ?? command[Object.keys(command)[0]];
+    if (typeof byName === 'string') {
+      return byName;
+    }
+    if (typeof command.collection === 'string') {
+      return command.collection;
+    }
+    return '(unknown)';
+  }
+
+  private summary(records: ProfilerRecord[]): HubQueriesData['summary'] {
+    let total = 0;
+    let warnCount = 0;
+    let criticalCount = 0;
+    let failedCount = 0;
+    for (const r of records) {
+      total += r.durationMs;
+      if (r.classification === 'warn') {
+        warnCount++;
+      }
+      if (r.classification === 'critical') {
+        criticalCount++;
+      }
+      if (r.failed) {
+        failedCount++;
+      }
+    }
+    return {
+      avgMs: records.length ? total / records.length : 0,
+      criticalCount,
+      failedCount,
+      total: records.length,
+      warnCount,
+    };
+  }
+
+  private topTemplates(records: ProfilerRecord[]): HubQueryTemplate[] {
+    const map = new Map<string, { count: number; max: number; total: number }>();
+    for (const r of records) {
+      const entry = map.get(r.commandSummary) ?? { count: 0, max: 0, total: 0 };
+      entry.count++;
+      entry.total += r.durationMs;
+      entry.max = Math.max(entry.max, r.durationMs);
+      map.set(r.commandSummary, entry);
+    }
+    return [...map.entries()]
+      .map(([template, e]) => ({ avgMs: e.total / e.count, count: e.count, maxMs: e.max, template }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 10);
+  }
+}

package/src/core/modules/hub/services/hub-trace-buffer.service.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest';
+
+import { HubTraceBufferService } from './hub-trace-buffer.service';
+import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+
+function makeConfig(overrides: Partial<ResolvedHubConfig> = {}): ResolvedHubConfig {
+  return {
+    actions: true,
+    allowPublicAccessInProduction: false,
+    collectors: {
+      logs: false,
+      queries: false,
+      traces: { capacity: 50, captureGraphQlOperation: true, excludePaths: [], slowMs: 1000 },
+    },
+    db: false,
+    emailPreview: true,
+    env: 'local',
+    links: {},
+    loginEndpoint: '/iam/sign-in/email',
+    logoutEndpoint: '/iam/sign-out',
+    mailbox: false,
+    migrations: false,
+    path: 'hub',
+    pollIntervalMs: 5000,
+    roles: ['admin'],
+    version: '1.0.0',
+    ...overrides,
+  };
+}
+
+/** Minimal Express req/res doubles for record(). */
+function reqRes(path: string, method = 'GET', statusCode = 200) {
+  return {
+    req: { baseUrl: '', method, path, route: undefined } as never,
+    res: { getHeader: () => undefined, statusCode, writableFinished: true } as never,
+  };
+}
+
+describe('HubTraceBufferService', () => {
+  describe('isExcluded (boundary-aware)', () => {
+    it('excludes the Hub base path and its sub-paths', () => {
+      const service = new HubTraceBufferService(makeConfig());
+      expect(service.isExcluded('/hub')).toBe(true);
+      expect(service.isExcluded('/hub/logs.json')).toBe(true);
+      expect(service.isExcluded('/hub/actions/collectors/traces/clear')).toBe(true);
+    });
+
+    it('does NOT exclude a sibling route that merely shares the prefix string', () => {
+      const service = new HubTraceBufferService(makeConfig());
+      // Regression guard for the over-broad `startsWith(prefix)` bug: `/hubble` is not a Hub route.
+      expect(service.isExcluded('/hubble')).toBe(false);
+      expect(service.isExcluded('/hub-admin')).toBe(false);
+      expect(service.isExcluded('/hubbard/x')).toBe(false);
+    });
+
+    it('honours additional configured exclude prefixes with the same boundary rule', () => {
+      const service = new HubTraceBufferService(
+        makeConfig({
+          collectors: {
+            logs: false,
+            queries: false,
+            traces: { capacity: 50, captureGraphQlOperation: true, excludePaths: ['/health'], slowMs: 1000 },
+          },
+        }),
+      );
+      expect(service.isExcluded('/health')).toBe(true);
+      expect(service.isExcluded('/health/live')).toBe(true);
+      expect(service.isExcluded('/healthcheck')).toBe(false);
+    });
+  });
+
+  describe('record + getData', () => {
+    it('records a completed request with method, path and duration, and summarises', () => {
+      const service = new HubTraceBufferService(makeConfig());
+      const { req, res } = reqRes('/permissions/json');
+      service.record(req, res, 12.5, false, '/permissions/json');
+
+      const data = service.getData();
+      expect(data.traces).toHaveLength(1);
+      expect(data.traces[0].method).toBe('GET');
+      expect(data.traces[0].path).toBe('/permissions/json');
+      expect(data.traces[0].durationMs).toBe(12.5);
+      expect(data.summary.total).toBe(1);
+      expect(data.summary.avgMs).toBe(12.5);
+    });
+
+    it('flags slow and error traces in the summary', () => {
+      const service = new HubTraceBufferService(makeConfig());
+      const slow = reqRes('/slow');
+      service.record(slow.req, slow.res, 5000, false, '/slow');
+      const err = reqRes('/boom', 'GET', 500);
+      service.record(err.req, err.res, 3, false, '/boom');
+
+      const data = service.getData();
+      expect(data.summary.slowCount).toBe(1);
+      expect(data.summary.errorCount).toBe(1);
+    });
+
+    it('supports cursor-based polling via since', () => {
+      const service = new HubTraceBufferService(makeConfig());
+      const a = reqRes('/a');
+      service.record(a.req, a.res, 1, false, '/a');
+      const cursor = service.getData().cursor;
+      const b = reqRes('/b');
+      service.record(b.req, b.res, 2, false, '/b');
+
+      const next = service.getData(cursor);
+      expect(next.traces).toHaveLength(1);
+      expect(next.traces[0].path).toBe('/b');
+    });
+  });
+});

package/src/core/modules/hub/services/hub-trace-buffer.service.ts

@@ -0,0 +1,134 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+import { HUB_CONFIG } from '../hub.constants';
+import { HubRingBuffer } from '../hub-ring-buffer';
+import { HubTraceRecord, HubTracesData } from '../interfaces/hub-panels.interface';
+import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+
+interface TraceRecord extends HubTraceRecord {
+  timestamp: number;
+}
+
+/**
+ * Ring buffer for HTTP request traces, fed by {@link HubTraceMiddleware}.
+ *
+ * Structurally incapable of leaking secrets: it stores only method, route pattern (never the query
+ * string), status, duration, an optional GraphQL operation name and the user id — no headers,
+ * cookies, bodies or GraphQL variables.
+ */
+@Injectable()
+export class HubTraceBufferService {
+  private readonly buffer?: HubRingBuffer<TraceRecord>;
+  private readonly cfg?: Exclude<ResolvedHubConfig['collectors']['traces'], false>;
+  private readonly excludePrefixes: string[];
+
+  constructor(@Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig) {
+    if (config.collectors.traces !== false) {
+      this.cfg = config.collectors.traces;
+      this.buffer = new HubRingBuffer<TraceRecord>(this.cfg.capacity);
+    }
+    // Always exclude the Hub's own routes so polling does not flood the trace list with self-noise.
+    this.excludePrefixes = [...(this.cfg?.excludePaths ?? []), '/' + config.path];
+  }
+
+  clear(): void {
+    this.buffer?.clear();
+  }
+
+  get enabled(): boolean {
+    return this.config.collectors.traces !== false;
+  }
+
+  getData(since?: number): HubTracesData {
+    const records = !this.buffer ? [] : since === undefined ? this.buffer.recent() : this.buffer.since(since);
+    let totalMs = 0;
+    let slowCount = 0;
+    let errorCount = 0;
+    for (const r of records) {
+      totalMs += r.durationMs;
+      if (r.slow) {
+        slowCount++;
+      }
+      if (r.error) {
+        errorCount++;
+      }
+    }
+    return {
+      cursor: this.buffer?.lastSeq ?? -1,
+      dropped: this.buffer?.firstRetainedSeq ?? -1,
+      summary: { avgMs: records.length ? totalMs / records.length : 0, errorCount, slowCount, total: records.length },
+      traces: records,
+    };
+  }
+
+  /** True when the path is excluded (Hub routes, configured prefixes). */
+  isExcluded(path: string): boolean {
+    // Boundary-aware: a prefix of `/hub` excludes `/hub` and `/hub/...` but NOT `/hubble` — a bare
+    // `startsWith(prefix)` would wrongly drop sibling routes that merely share the prefix string.
+    return this.excludePrefixes.some((prefix) => path === prefix || path.startsWith(prefix + '/'));
+  }
+
+  /** Record a completed request. Called from the middleware at `finish`/`close`. */
+  record(req: Request, res: Response, durationMs: number, aborted: boolean, fullPath?: string): void {
+    if (!this.buffer || !this.cfg) {
+      return;
+    }
+    const statusCode = res.statusCode;
+    const contentLength = Number(res.getHeader('content-length')) || undefined;
+    this.buffer.add({
+      aborted: aborted || undefined,
+      contentLength,
+      durationMs,
+      error: statusCode >= 500 || undefined,
+      graphqlOperation: this.cfg.captureGraphQlOperation ? this.graphqlOperation(req) : undefined,
+      method: req.method,
+      path: this.routePattern(req, fullPath),
+      slow: durationMs > this.cfg.slowMs || undefined,
+      statusCode,
+      userId: (req as unknown as { user?: { id?: string } }).user?.id,
+    } as Omit<TraceRecord, 'seq' | 'timestamp'>);
+  }
+
+  /** Collapse high-cardinality ids so the buffer does not explode on 404s / unmatched routes. */
+  private collapseParams(path: string): string {
+    return path
+      .replace(/\/[a-f0-9]{24}(?=\/|$)/gi, '/:id')
+      .replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=\/|$)/gi, '/:id')
+      .replace(/\/\d+(?=\/|$)/g, '/:n');
+  }
+
+  private graphqlOperation(req: Request): string | undefined {
+    if (req.method !== 'POST' || !req.path.endsWith('/graphql')) {
+      return undefined;
+    }
+    const body = (req as unknown as { body?: unknown }).body;
+    if (Array.isArray(body)) {
+      return `batch(${body.length})`;
+    }
+    const op = (body as { operationName?: string; query?: string })?.operationName;
+    if (op) {
+      return op;
+    }
+    const query = (body as { query?: string })?.query;
+    if (typeof query === 'string') {
+      const match = /\b(query|mutation|subscription)\s+([A-Za-z_]\w*)/.exec(query.slice(0, 500));
+      if (match) {
+        return match[2];
+      }
+    }
+    return 'anonymous';
+  }
+
+  /** Route pattern when the router resolved one, else a param-collapsed raw path (never the query string). */
+  private routePattern(req: Request, fullPath?: string): string {
+    const route = (req as unknown as { route?: { path?: string } }).route?.path;
+    const base = req.baseUrl || '';
+    if (route && base) {
+      return base + (route === '/' ? '' : route) || '/';
+    }
+    // Fallback: the mount-stripped `req.path` is unreliable under `forRoutes('*')`; prefer the full
+    // path captured by the middleware, with high-cardinality ids collapsed.
+    return this.collapseParams(fullPath || req.baseUrl || req.path);
+  }
+}

package/src/core.module.ts

@@ -43,6 +43,8 @@ import { CoreBetterAuthModule } from './core/modules/better-auth/core-better-aut
 import { CoreBetterAuthService } from './core/modules/better-auth/core-better-auth.service';
 import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
+import { CoreHubModule } from './core/modules/hub/core-hub.module';
+import { isHubEnabled, isHubQueriesEnabled } from './core/modules/hub/hub-config.helper';
 import { CorePermissionsModule } from './core/modules/permissions/core-permissions.module';
 import { CoreSystemSetupModule } from './core/modules/system-setup/core-system-setup.module';
 import { CoreTenantModule } from './core/modules/tenant/core-tenant.module';
@@ -335,6 +337,16 @@ export class CoreModule implements NestModule {
     // and: https://mongoosejs.com/docs/guide.html#strictQuery
     mongoose.set('strictQuery', config.mongoose.strictQuery || false);
 
+    // Opt the MongoDB driver into command monitoring only when the Hub query profiler is enabled
+    // (zero cost otherwise). An explicit `monitorCommands: false` by the consumer wins — the profiler
+    // then warns once and stays inert.
+    if (isHubQueriesEnabled(config.hub)) {
+      config.mongoose.options = config.mongoose.options || {};
+      if ((config.mongoose.options as { monitorCommands?: boolean }).monitorCommands === undefined) {
+        (config.mongoose.options as { monitorCommands?: boolean }).monitorCommands = true;
+      }
+    }
+
     const imports: any[] = [MongooseModule.forRoot(config.mongoose.uri, config.mongoose.options)];
 
     if (isGraphQlEnabled && config.graphQl) {
@@ -375,10 +387,39 @@ export class CoreModule implements NestModule {
 
     // Permissions report (development tool)
     const permissionsConfig = config.permissions;
-    if (permissionsConfig === true || (typeof permissionsConfig === 'object' && permissionsConfig.enabled !== false)) {
+    const permissionsEnabled =
+      permissionsConfig === true || (typeof permissionsConfig === 'object' && permissionsConfig.enabled !== false);
+    if (permissionsEnabled) {
       imports.push(CorePermissionsModule.forRoot(permissionsConfig));
     }
 
+    // Hub admin area (operator cockpit). Presence implies enabled — but NEVER implicitly:
+    // it must be switched on per environment. Overrides pass project subclasses through.
+    if (isHubEnabled(config.hub)) {
+      const permissionsPath =
+        permissionsEnabled && typeof permissionsConfig === 'object' && permissionsConfig.path
+          ? permissionsConfig.path
+          : permissionsEnabled
+            ? 'permissions'
+            : undefined;
+      imports.push(
+        CoreHubModule.forRoot({
+          actionsController: overrides?.hub?.actionsController,
+          actionsService: overrides?.hub?.actionsService,
+          config: config.hub,
+          controller: overrides?.hub?.controller,
+          ctx: {
+            env: config.env,
+            graphQlEnabled: isGraphQlEnabled,
+            permissionsPath,
+            version: config.version ?? 'unknown',
+          },
+          htmlService: overrides?.hub?.htmlService,
+          service: overrides?.hub?.service,
+        }),
+      );
+    }
+
     // Add CoreBetterAuthModule based on mode
     // IAM-only mode: BetterAuth is enabled by default (it's the only auth option)
     // Legacy mode: Only register if autoRegister is explicitly true
@@ -438,6 +479,25 @@ export class CoreModule implements NestModule {
       }
     }
 
+    // SECURITY: the Hub's ADMIN gate is enforced by the app-wide roles guard, which is registered by
+    // BetterAuth (IAM mode) or the legacy Auth module. When the Hub is enabled and gated but NEITHER is
+    // active, nothing enforces its @Roles(ADMIN) metadata — the whole cockpit, INCLUDING destructive
+    // migration/file-delete/cron actions, would be reachable unauthenticated, silently. A project may
+    // still register its own APP_GUARD, so this is a loud warning rather than a hard error.
+    if (isHubEnabled(config.hub)) {
+      const hubIsGated = !(typeof config.hub === 'object' && config.hub.roles === false);
+      const noBuiltInRolesGuard = isIamOnlyMode && !isBetterAuthEnabled;
+      if (hubIsGated && noBuiltInRolesGuard) {
+        console.warn(
+          'CoreModule: the Hub is enabled and ADMIN-gated, but neither BetterAuth (IAM) nor the legacy ' +
+            'Auth module is active — so no built-in guard enforces its @Roles(ADMIN) metadata. Unless you ' +
+            'have registered your own APP_GUARD that reads @Roles, the Hub (including its destructive ' +
+            'migration/file-delete/cron actions) is reachable UNAUTHENTICATED. Enable an auth module or ' +
+            'register a roles guard.',
+        );
+      }
+    }
+
     // Add CoreSystemSetupModule when BetterAuth is active
     // Enabled by default - disable explicitly via systemSetup: { enabled: false }
     if (isBetterAuthEnabled && config.systemSetup?.enabled !== false) {

package/src/index.ts

@@ -43,6 +43,7 @@ export * from './core/common/helpers/input.helper';
 export * from './core/common/helpers/logging.helper';
 export * from './core/common/helpers/meta.helper';
 export * from './core/common/helpers/model.helper';
+export * from './core/common/helpers/process-diagnostics.helper';
 export * from './core/common/helpers/register-enum.helper';
 export * from './core/common/helpers/scim.helper';
 export * from './core/common/helpers/service.helper';
@@ -181,6 +182,12 @@ export * from './core/modules/health-check/core-health-check.module';
 export * from './core/modules/health-check/core-health-check.resolver';
 export * from './core/modules/health-check/core-health-check.service';
 
+// =====================================================================================================================
+// Core - Modules - Hub
+// =====================================================================================================================
+
+export * from './core/modules/hub';
+
 // =====================================================================================================================
 // Core - Modules - Migrate
 // =====================================================================================================================

package/src/main.ts

@@ -9,6 +9,7 @@ import envConfig from './config.env';
 import { FilterArgs } from './core/common/args/filter.args';
 import { buildCorsConfig, isCookiesEnabled, isCorsDisabled } from './core/common/helpers/cookies.helper';
 import { HttpExceptionLogFilter } from './core/common/filters/http-exception-log.filter';
+import { handleFatalBootstrapError, installProcessDiagnostics } from './core/common/helpers/process-diagnostics.helper';
 import { CorePersistenceModel } from './core/common/models/core-persistence.model';
 import { CoreAuthModel } from './core/modules/auth/core-auth.model';
 import { CoreUserModel } from './core/modules/user/core-user.model';
@@ -21,6 +22,11 @@ import { ServerModule } from './server/server.module';
  * Preparations for server start
  */
 async function bootstrap() {
+  // Make the exit reason diagnosable: log unhandled rejections without crashing, log uncaught
+  // exceptions before the restart, and label external termination signals so a silent
+  // "app crashed" always has a reason. See process-diagnostics.helper.ts for the rationale.
+  installProcessDiagnostics();
+
   // Create a new server based on express
   const server = await NestFactory.create<NestExpressApplication>(
     // Include server module, with all necessary modules for the project
@@ -106,9 +112,20 @@ async function bootstrap() {
     jsonDocumentUrl: '/api-docs-json',
   });
 
+  // Drain the event loop on SIGTERM/SIGINT so the process actually exits.
+  //
+  // This is load-bearing in a container, where `docker-entrypoint.sh` runs node under `exec` and it
+  // therefore becomes PID 1. A PID-namespace init is SIGNAL_UNKILLABLE: a userspace signal whose
+  // disposition is the default is silently discarded by the kernel, so re-raising is a no-op there.
+  // Meanwhile the listening HTTP server keeps the event loop non-empty, so nothing exits on its own
+  // and `docker stop` waits out its full grace period before SIGKILL — dropping in-flight requests
+  // and skipping every onModuleDestroy(). enableShutdownHooks() is what closes the app and drains
+  // the loop; installProcessDiagnostics() then correctly defers to it instead of re-raising.
+  server.enableShutdownHooks();
+
   // Start server on configured port
   await server.listen(envConfig.port, envConfig.hostname);
-  console.debug(`Server startet at ${await server.getUrl()}`);
+  console.debug(`Server started at ${await server.getUrl()}`);
 
   // Run command after server init
   if (envConfig.execAfterInit) {
@@ -126,5 +143,7 @@ async function bootstrap() {
   }
 }
 
-// Start server
-bootstrap();
+// Start server. A rejection here is a fatal startup failure (e.g. port already in use, DB
+// unreachable) — surface it and exit rather than let it become a silent unhandledRejection
+// that leaves a zombie process "alive" but listening on nothing.
+bootstrap().catch(handleFatalBootstrapError);