@lenne.tech/nest-server 11.31.2 → 11.32.0

package/src/core/modules/hub/index.ts

@@ -0,0 +1,25 @@
+export * from './core-hub-actions.controller';
+export * from './core-hub-html.service';
+export * from './core-hub.controller';
+export * from './core-hub.module';
+export * from './core-hub.service';
+export * from './services/core-hub-actions.service';
+export * from './services/core-hub-db.service';
+export * from './services/core-hub-email.service';
+export * from './services/core-hub-mailbox.service';
+export * from './services/core-hub-migrations.service';
+export * from './services/core-hub-sources.service';
+export * from './services/hub-log-buffer.service';
+export * from './services/hub-query-profiler.service';
+export * from './services/hub-trace-buffer.service';
+export * from './middleware/hub-trace.middleware';
+export * from './helpers/hub-command-shape.helper';
+export * from './helpers/hub-mask.helper';
+export * from './helpers/hub-mermaid.helper';
+export * from './helpers/hub-shell.helper';
+export * from './hub-config.helper';
+export * from './hub-nav';
+export * from './hub-ring-buffer';
+export * from './hub.constants';
+export * from './interfaces/hub-config.interface';
+export * from './interfaces/hub-panels.interface';

package/src/core/modules/hub/interfaces/hub-config.interface.ts

@@ -0,0 +1,265 @@
+import type { LogLevel } from '@nestjs/common';
+
+/**
+ * Configuration for the Hub admin area (operator cockpit).
+ *
+ * Follows the "presence implies enabled" pattern (see .claude/rules/configurable-features.md):
+ * - `true`: enabled with all defaults (admin-only, served at `/hub`)
+ * - `{}`: same as `true`
+ * - `{ path: 'admin/hub' }`: enabled with a custom base path
+ * - `{ enabled: false, ... }`: pre-configured but disabled
+ * - `undefined`: disabled — every Hub route answers 404
+ *
+ * The Hub is NEVER enabled implicitly. It must be switched on per environment (in `config.env.ts`
+ * or via `NSC__HUB__*` env vars). No environment inherits it.
+ */
+export interface IHubConfig {
+  /**
+   * Master switch for every mutating endpoint (migrations run/down, cron control, buffer clears,
+   * file delete, test mail). When `false`, the actions controller is not registered at all, so
+   * those routes answer 404.
+   *
+   * @default true
+   */
+  actions?: boolean;
+
+  /**
+   * Runtime collectors feeding the Logs, Traces and Queries panels.
+   * When the Hub is enabled: `logs` and `traces` default on, `queries` defaults off
+   * (query profiling opts the MongoDB driver into command monitoring, so it is opt-in).
+   */
+  collectors?: IHubCollectorsConfig;
+
+  /**
+   * MongoDB stats panel (dbStats, per-collection collStats).
+   *
+   * @default true
+   */
+  db?: boolean | IHubDbConfig;
+
+  /**
+   * Whether the Hub is enabled. Presence of the config object already implies `true`; set to
+   * `false` to keep a pre-configured block dormant.
+   */
+  enabled?: boolean;
+
+  /**
+   * Email preview panel (renders EJS templates with sample data).
+   *
+   * @default true
+   */
+  emailPreview?: boolean;
+
+  /** External links surfaced on the dashboard and in the navigation. Set a value to `false` to hide it. */
+  links?: IHubLinksConfig;
+
+  /**
+   * Endpoint the built-in login form POSTs `{ email, password }` to. It must set a session cookie on
+   * success (BetterAuth IAM does). Lets an admin log into the Hub directly, without the frontend.
+   *
+   * @default '/iam/sign-in/email'
+   */
+  loginEndpoint?: string;
+
+  /**
+   * Endpoint the built-in "Sign out" button POSTs to. It must clear the session cookie (BetterAuth
+   * IAM's `/iam/sign-out` does). Only used after authentication, so it is delivered in the ADMIN-gated
+   * session payload, never in the public shell.
+   *
+   * @default '/iam/sign-out'
+   */
+  logoutEndpoint?: string;
+
+  /**
+   * Built-in mailbox (a Mailpit-style capture of outgoing mail for local/test use).
+   *
+   * @default disabled
+   */
+  mailbox?: boolean | IHubMailboxConfig;
+
+  /**
+   * Migrations panel + actions.
+   *
+   * @default enabled with dir `./migrations`, collection `migrations`
+   */
+  migrations?: false | IHubMigrationsConfig;
+
+  /**
+   * Base path for all Hub routes.
+   *
+   * @default 'hub'
+   */
+  path?: string;
+
+  /**
+   * Default client poll interval (ms) for JSON sidecars. Clamped to a minimum of 1000 ms.
+   *
+   * @default 5000
+   */
+  pollIntervalMs?: number;
+
+  /**
+   * Role(s) required to access the Hub.
+   * - `undefined`: defaults to `RoleEnum.ADMIN`
+   * - `string | string[]`: required role(s), OR semantics
+   * - `false`: NO auth check at all — every route becomes public. Only ever use behind a network
+   *   boundary you fully control; a public Hub exposes config, logs and destructive actions.
+   *   **Forbidden in `production`/`staging` unless {@link allowPublicAccessInProduction} is set** —
+   *   see that flag.
+   *
+   * @default RoleEnum.ADMIN
+   */
+  roles?: false | string | string[];
+
+  /**
+   * Acknowledge, explicitly, that a PUBLIC Hub (`roles: false`, no auth check) may run in a reachable
+   * environment. Without this, `roles: false` throws at startup in `production`/`staging`, because it
+   * exposes the config viewer, logs and DESTRUCTIVE admin actions (migrations, file delete, cron) to
+   * unauthenticated requests. Set to `true` ONLY when the Hub sits behind a fully-controlled network
+   * boundary (VPN / IP allow-list / authenticating reverse proxy). Has no effect unless `roles: false`.
+   *
+   * @default false
+   */
+  allowPublicAccessInProduction?: boolean;
+}
+
+/** Collector toggles (each: boolean shorthand or an options object). */
+export interface IHubCollectorsConfig {
+  /** Log ring buffer. @default on (capacity 500). */
+  logs?: boolean | IHubLogsConfig;
+  /** MongoDB query profiler (driver command monitoring). @default off. */
+  queries?: boolean | IHubQueriesConfig;
+  /** HTTP request traces. @default on (capacity 200). */
+  traces?: boolean | IHubTracesConfig;
+}
+
+export interface IHubCollectorBaseConfig {
+  /** Ring-buffer capacity (entries). */
+  capacity?: number;
+  /** @default true when the parent object is present. */
+  enabled?: boolean;
+}
+
+export interface IHubDbConfig {
+  enabled?: boolean;
+  /** Include index size/definitions per collection (extra collStats work). @default false. */
+  includeIndexes?: boolean;
+}
+
+export interface IHubLinksConfig {
+  /** GraphQL sandbox link. @default '/graphql' when GraphQL is enabled. */
+  graphql?: false | string;
+  /** Externally hosted Mailpit URL. @default undefined. */
+  mailpit?: string;
+  /** Permissions cockpit link. @default derived from the permissions module path when enabled. */
+  permissions?: false | string;
+  /** Swagger UI link. @default '/swagger'. */
+  swagger?: false | string;
+}
+
+export interface IHubLogsConfig extends IHubCollectorBaseConfig {
+  /** Context names never captured (e.g. noisy framework contexts). @default []. */
+  excludeContexts?: string[];
+  /** Levels captured into the buffer (independent of console output level). @default ['log','warn','error','fatal']. */
+  levels?: LogLevel[];
+  /** Per-record message cap (characters). @default 2048. */
+  maxMessageLength?: number;
+}
+
+export interface IHubMailboxConfig {
+  /** Number of captured mails retained. @default 100. */
+  capacity?: number;
+  enabled?: boolean;
+  /** Per-field body cap (bytes); the html and text bodies are EACH truncated to this. @default 262144. */
+  maxMailSize?: number;
+  /**
+   * - `capture`: intercept mail and DO NOT send it — for local/test use (a Mailpit replacement).
+   *   Throws at startup in `production`/`staging` to prevent silently swallowing real mail.
+   * - `copy`: send mail normally AND record a copy in the mailbox.
+   *
+   * @default 'capture'
+   */
+  mode?: 'capture' | 'copy';
+}
+
+export interface IHubMigrationsConfig {
+  /** MongoDB collection holding migration state. @default 'migrations'. */
+  collectionName?: string;
+  /** Filesystem directory of migration files. @default './migrations'. */
+  dir?: string;
+  enabled?: boolean;
+  /** Collection used for cluster-safe locking during migration actions. @default undefined. */
+  lockCollectionName?: string;
+}
+
+export interface IHubQueriesConfig extends IHubCollectorBaseConfig {
+  /** Duration (ms) above which a query is classified "critical". @default 200. */
+  criticalMs?: number;
+  /** Command names never recorded (replaces the default admin/heartbeat ignore set when provided). */
+  ignoreCommands?: string[];
+  /** Command-summary length cap (characters). @default 512. */
+  maxShapeLength?: number;
+  /** Duration (ms) above which a query is classified "warn". @default 50. */
+  warnMs?: number;
+}
+
+export interface IHubTracesConfig extends IHubCollectorBaseConfig {
+  /** Capture the GraphQL operationName for POST /graphql. @default true. */
+  captureGraphQlOperation?: boolean;
+  /** Path prefixes never traced. The Hub base path is always added on top. @default ['/hub']. */
+  excludePaths?: string[];
+  /** Duration (ms) above which a trace is flagged slow. @default 1000. */
+  slowMs?: number;
+}
+
+/**
+ * Fully-resolved Hub configuration (all defaults applied, booleans normalized to objects).
+ * This is the shape bound to the `HUB_CONFIG` token and injected everywhere in the module.
+ */
+export interface ResolvedHubConfig {
+  actions: boolean;
+  /** Explicit acknowledgment that lets a public (`roles: false`) Hub run in production/staging. */
+  allowPublicAccessInProduction: boolean;
+  collectors: {
+    logs: false | Required<Omit<IHubLogsConfig, 'enabled'>>;
+    queries: false | (Required<Omit<IHubQueriesConfig, 'enabled' | 'ignoreCommands'>> & { ignoreCommands?: string[] });
+    traces: false | Required<Omit<IHubTracesConfig, 'enabled'>>;
+  };
+  db: false | { includeIndexes: boolean };
+  emailPreview: boolean;
+  /** The environment name (from `IServerOptions.env`), used for the production mailbox guard + header badge. */
+  env: string;
+  links: { graphql?: string; mailpit?: string; permissions?: string; swagger?: string };
+  loginEndpoint: string;
+  logoutEndpoint: string;
+  mailbox: false | { capacity: number; maxMailSize: number; mode: 'capture' | 'copy' };
+  migrations: false | { collectionName: string; dir: string; lockCollectionName?: string };
+  path: string;
+  pollIntervalMs: number;
+  roles: false | string[];
+  /** The framework/app version (from `IServerOptions.version`), used for the header badge + hub.js cache-busting. */
+  version: string;
+}
+
+/**
+ * The capture hook injected into `EmailService`. Implemented by the mailbox service.
+ * Kept minimal so `EmailService` never depends on the Hub module type graph.
+ */
+export interface IHubEmailCapture {
+  /**
+   * Record an outgoing mail. Returns `true` when the caller should SKIP the actual transport
+   * (mailbox `mode: 'capture'`), `false` when it should send normally (`mode: 'copy'`).
+   */
+  capture(mail: IHubCapturedMailInput): boolean;
+}
+
+export interface IHubCapturedMailInput {
+  bcc?: string;
+  cc?: string;
+  from?: string;
+  html?: string;
+  subject?: string;
+  templateName?: string;
+  text?: string;
+  to?: string;
+}

package/src/core/modules/hub/interfaces/hub-panels.interface.ts

@@ -0,0 +1,186 @@
+/**
+ * Response DTOs for the Hub JSON sidecars — the stable contract between the server data providers
+ * and the client runtime (and any future richer UI). Every panel that depends on an optional source
+ * returns `{ available: false, hint }` instead of erroring when that source is absent.
+ */
+
+export interface HubUnavailable {
+  available: false;
+  hint: string;
+}
+
+/**
+ * Cockpit-chrome data served (ADMIN-gated) by `GET /{hub}/session.json`. The public shell HTML
+ * carries none of this — the client builds the navigation, environment badge, version and external
+ * links from this payload only AFTER the auth probe succeeds, so an unauthenticated request reveals
+ * nothing of the Hub's structure.
+ */
+export interface HubSessionData {
+  authenticated: true;
+  env: string;
+  links: Record<string, string | undefined>;
+  logoutEndpoint: string;
+  panelGroups: string[];
+  panels: { available: boolean; group: string; id: string; optional: boolean; path: string; title: string }[];
+  version: string;
+}
+
+export interface HubDashboardData {
+  build: { commit?: string; env: string; version: string };
+  features: Record<string, boolean>;
+  health?: { details?: Record<string, unknown>; status: string };
+  links: Record<string, string>;
+  memory: { heapTotal: number; heapUsed: number; rss: number };
+  mongo: { readyState: number; state: string };
+  time: string;
+  uptimeSeconds: number;
+}
+
+export interface HubDiagnosticsData {
+  arch: string;
+  buffers: Record<string, { capacity: number; enabled: boolean; size: number }>;
+  cpuUsage: { system: number; user: number };
+  env: string;
+  memory: { arrayBuffers: number; external: number; heapTotal: number; heapUsed: number; rss: number };
+  nodeVersion: string;
+  pid: number;
+  platform: string;
+  time: string;
+  uptimeSeconds: number;
+}
+
+export interface HubDbData {
+  collections: HubDbCollection[];
+  stats: { collections: number; dataSize: number; indexSize: number; objects: number; storageSize: number };
+}
+
+export interface HubDbCollection {
+  avgObjSize?: number;
+  count: number;
+  indexCount?: number;
+  indexSize?: number;
+  name: string;
+  size: number;
+  storageSize: number;
+}
+
+export interface HubModelsData {
+  entities: { fields: { name: string; ref?: string; type: string }[]; name: string }[];
+  mermaid: string;
+  modelCount: number;
+  relationCount: number;
+}
+
+export interface HubMigrationsData {
+  completed: string[];
+  dirAvailable: boolean;
+  lastRun?: string;
+  pending: string[];
+  source: 'collection' | 'runner';
+}
+
+export interface HubFilesData {
+  bucket: string;
+  files: { contentType?: string; filename: string; id: string; length: number; uploadDate?: string }[];
+  total: number;
+}
+
+export interface HubCronData {
+  intervals: string[];
+  jobs: { lastDate?: string; name: string; nextDate?: string; running: boolean }[];
+  timeouts: string[];
+}
+
+export interface HubErrorCodesData {
+  codes: { code: string; de?: string; en?: string }[];
+  locale: string;
+}
+
+export interface HubEmailsData {
+  templates: { locales: string[]; name: string; source: 'framework' | 'project' }[];
+}
+
+export interface HubMailboxData {
+  cursor: number;
+  dropped: number;
+  mails: HubMailboxEntry[];
+  mode: 'capture' | 'copy';
+}
+
+export interface HubLogRecord {
+  context?: string;
+  level: string;
+  message: string;
+  seq: number;
+  stack?: string;
+  timestamp: number;
+}
+
+export interface HubLogsData {
+  cursor: number;
+  dropped: number;
+  records: HubLogRecord[];
+}
+
+export interface HubTraceRecord {
+  aborted?: boolean;
+  contentLength?: number;
+  durationMs: number;
+  error?: boolean;
+  graphqlOperation?: string;
+  method: string;
+  path: string;
+  seq: number;
+  slow?: boolean;
+  statusCode: number;
+  timestamp: number;
+  userId?: string;
+}
+
+export interface HubTracesData {
+  cursor: number;
+  dropped: number;
+  summary: { avgMs: number; errorCount: number; slowCount: number; total: number };
+  traces: HubTraceRecord[];
+}
+
+export interface HubQueryRecord {
+  classification: 'critical' | 'ok' | 'warn';
+  collection: string;
+  commandSummary: string;
+  durationMs: number;
+  errorMessage?: string;
+  failed?: boolean;
+  operation: string;
+  requestId: number;
+  seq: number;
+  timestamp: number;
+}
+
+export interface HubQueryTemplate {
+  avgMs: number;
+  count: number;
+  maxMs: number;
+  template: string;
+}
+
+export interface HubQueriesData {
+  cursor: number;
+  recent: HubQueryRecord[];
+  slowest: HubQueryRecord[];
+  summary: { avgMs: number; criticalCount: number; failedCount: number; total: number; warnCount: number };
+  topTemplates: HubQueryTemplate[];
+}
+
+export interface HubMailboxEntry {
+  bcc?: string;
+  cc?: string;
+  from?: string;
+  hasHtml: boolean;
+  hasText: boolean;
+  seq: number;
+  subject?: string;
+  templateName?: string;
+  timestamp: number;
+  to?: string;
+}

package/src/core/modules/hub/middleware/hub-trace.middleware.ts

@@ -0,0 +1,45 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { NextFunction, Request, Response } from 'express';
+
+import { HubTraceBufferService } from '../services/hub-trace-buffer.service';
+
+/**
+ * Measures request duration and records a trace at response completion.
+ *
+ * Registered by `CoreHubModule.configure()` ONLY when the traces collector is enabled (zero cost
+ * otherwise — not even a no-op layer). Uses `hrtime` for timing and a latch so `finish` and `close`
+ * (Express 5 / Node http.ServerResponse) never double-record; `close` without `writableFinished`
+ * marks a client-aborted request.
+ */
+@Injectable()
+export class HubTraceMiddleware implements NestMiddleware {
+  constructor(private readonly traceBuffer: HubTraceBufferService) {}
+
+  use(req: Request, res: Response, next: NextFunction): void {
+    // NestJS mounts `forRoutes('*')` middleware at a level where `req.path` is stripped to '/'; the
+    // full request path lives in `req.originalUrl`. Use that for the exclusion check (and pass it to
+    // the recorder as a fallback), otherwise the Hub's own routes are never excluded.
+    const fullPath = (req.originalUrl || req.url || '').split('?')[0] || '/';
+    if (!this.traceBuffer.enabled || this.traceBuffer.isExcluded(fullPath)) {
+      next();
+      return;
+    }
+    const start = process.hrtime.bigint();
+    let recorded = false;
+    const record = (aborted: boolean): void => {
+      if (recorded) {
+        return;
+      }
+      recorded = true;
+      const durationMs = Number(process.hrtime.bigint() - start) / 1e6;
+      try {
+        this.traceBuffer.record(req, res, durationMs, aborted, fullPath);
+      } catch {
+        /* never let trace recording break the response path */
+      }
+    };
+    res.on('finish', () => record(false));
+    res.on('close', () => record(!res.writableFinished));
+    next();
+  }
+}

package/src/core/modules/hub/services/core-hub-actions.service.ts

@@ -0,0 +1,133 @@
+import { Injectable, Logger, Optional } from '@nestjs/common';
+
+import { EmailService } from '../../../common/services/email.service';
+import { RequestContext } from '../../../common/services/request-context.service';
+import { HubActionMessage } from '../hub-action-messages';
+import { CoreHubDbService } from './core-hub-db.service';
+import { CoreHubEmailService } from './core-hub-email.service';
+import { CoreHubMailboxService } from './core-hub-mailbox.service';
+import { CoreHubMigrationsService } from './core-hub-migrations.service';
+import { CoreHubSourcesService } from './core-hub-sources.service';
+import { HubLogBufferService } from './hub-log-buffer.service';
+import { HubQueryProfilerService } from './hub-query-profiler.service';
+import { HubTraceBufferService } from './hub-trace-buffer.service';
+
+/** Illustrative sample data for the test-mail action. */
+const TEST_MAIL_DATA = {
+  appName: 'Nest Server',
+  firstName: 'Hub',
+  link: 'https://example.com/verify?token=SAMPLE',
+  name: 'Hub Admin',
+  url: 'https://example.com/verify?token=SAMPLE',
+};
+
+/**
+ * Executes the Hub's mutating actions, each behind an audit log line recording the acting admin.
+ *
+ * Read/mutate separation: this service holds all state-changing operations, so a project can override
+ * it (`overrides.hub.actionsService`) to veto or extend actions in one place.
+ */
+@Injectable()
+export class CoreHubActionsService {
+  protected readonly logger = new Logger('HubAction');
+
+  constructor(
+    protected readonly migrationsService: CoreHubMigrationsService,
+    protected readonly dbService: CoreHubDbService,
+    protected readonly sourcesService: CoreHubSourcesService,
+    protected readonly hubEmailService: CoreHubEmailService,
+    protected readonly logBuffer: HubLogBufferService,
+    protected readonly traceBuffer: HubTraceBufferService,
+    protected readonly queryProfiler: HubQueryProfilerService,
+    @Optional() protected readonly emailService?: EmailService,
+    @Optional() protected readonly mailboxService?: CoreHubMailboxService,
+  ) {}
+
+  /** Clear a collector's ring buffer. */
+  clearBuffer(name: 'logs' | 'mailbox' | 'queries' | 'traces'): { cleared: string } {
+    this.audit(`clear ${name} buffer`);
+    switch (name) {
+      case 'logs':
+        this.logBuffer.clear();
+        break;
+      case 'mailbox':
+        this.mailboxService?.clear();
+        break;
+      case 'queries':
+        this.queryProfiler.clear();
+        break;
+      case 'traces':
+        this.traceBuffer.clear();
+        break;
+    }
+    return { cleared: name };
+  }
+
+  /** Fire/stop/start a cron job. */
+  controlCron(name: string, action: 'start' | 'stop' | 'trigger'): { action: string; name: string } {
+    this.audit(`cron ${action} ${name}`);
+    this.sourcesService.controlCron(name, action);
+    return { action, name };
+  }
+
+  /** Delete a GridFS file (the confirm keyword must equal its filename). */
+  async deleteFile(id: string, expectedFilename: string): Promise<{ deleted: { filename: string; id: string } }> {
+    this.audit(`delete file ${id}`);
+    return { deleted: await this.dbService.deleteFile(id, expectedFilename) };
+  }
+
+  /** Roll back the last migration. */
+  async rollbackMigration(): Promise<{ rolledBack?: string }> {
+    this.audit('rollback last migration');
+    return this.migrationsService.rollbackLast();
+  }
+
+  /** Run all pending migrations. */
+  async runMigrations(): Promise<{ ran: string[] }> {
+    this.audit('run pending migrations');
+    return this.migrationsService.runPending();
+  }
+
+  /** Send a test mail (lands in the mailbox when capture mode is active). */
+  async sendTestEmail(to: string, template?: string, locale?: string): Promise<{ sent: boolean; to: string }> {
+    if (!this.emailService) {
+      throw new Error(HubActionMessage.emailServiceUnavailable);
+    }
+    const htmlTemplate = this.resolveTestTemplate(template, locale);
+    this.audit(`send test mail to ${to}`);
+    await this.emailService.sendMail(to, 'Hub test email', {
+      htmlTemplate,
+      templateData: { ...TEST_MAIL_DATA, email: to },
+    });
+    return { sent: true, to };
+  }
+
+  /**
+   * Resolve the template file name for a test mail, validated against the live template inventory.
+   *
+   * Security: a caller-supplied `template`/`locale` is only accepted when it maps to a real entry in
+   * `CoreHubEmailService.getTemplates()`. This mirrors `renderPreview`'s allowlist so the test-mail
+   * action can never point the renderer at a path outside the templates directory (`..` traversal).
+   */
+  protected resolveTestTemplate(template?: string, locale?: string): string {
+    const inventory = this.hubEmailService.getTemplates().templates;
+    // Preserve the historical defaults ('welcome', or 'email-verification' when a locale is given),
+    // but bound every path to the inventory.
+    const requestedBase = template || (locale ? 'email-verification' : 'welcome');
+    const match = inventory.find((entry) => entry.name === requestedBase);
+    if (!match) {
+      throw new Error(HubActionMessage.unknownEmailTemplate(requestedBase));
+    }
+    // Append the locale suffix only when it is a known variant of this template.
+    if (locale && match.locales.includes(locale)) {
+      return `${requestedBase}-${locale}`;
+    }
+    return requestedBase;
+  }
+
+  /** Write an audit line with the acting admin's id (from the async request context). */
+  protected audit(action: string): void {
+    const userId = RequestContext.getCurrentUser()?.id ?? 'unknown';
+    this.logger.warn(`[HUB-ACTION] ${action} by user ${userId}`);
+  }
+}