@lenne.tech/nest-server 11.31.1 → 11.31.3

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]);
+        }
+      });
     });
   }
 }

package/src/core/modules/ai/core-ai.controller.ts

@@ -1,4 +1,4 @@
-import { Body, Controller, Delete, Get, Param, Post, Put, Res } from '@nestjs/common';
+import { Body, Controller, Delete, Get, Param, Post, Put, Query, Res } from '@nestjs/common';
 import { Response } from 'express';
 
 import { RESTServiceOptions } from '../../common/decorators/rest-service-options.decorator';
@@ -266,7 +266,9 @@ export class CoreAiController {
   }
 
   /**
-   * Find the current user's AI conversations (admins see all).
+   * Find the current user's AI conversations (own only by default). An admin may
+   * pass `?all=true` to list every user's conversations; each result carries its
+   * `createdBy` owner id for attribution. The flag is ignored for non-admins.
    *
    * The `messages` subdocument array is excluded from the list result — clients
    * fetching the conversation detail via `getConversation` get the full message
@@ -274,13 +276,14 @@ export class CoreAiController {
    */
   @Get('conversations')
   @Roles(RoleEnum.S_USER)
-  async findConversations(@RESTServiceOptions() serviceOptions: ServiceOptions): Promise<CoreAiConversation[]> {
-    const currentUser = serviceOptions?.currentUser;
-    const filterQuery = currentUser?.roles?.includes(RoleEnum.ADMIN) ? {} : { createdBy: currentUser?.id };
-    return this.conversationService.find(
-      { filterQuery },
-      { ...serviceOptions, roles: [RoleEnum.ADMIN, RoleEnum.S_CREATOR, RoleEnum.S_SELF], select: '-messages' },
-    );
+  async findConversations(
+    @RESTServiceOptions() serviceOptions: ServiceOptions,
+    @Query('all') all?: string,
+  ): Promise<CoreAiConversation[]> {
+    // Owner-scoped list shared with the GraphQL resolver — see
+    // CoreAiConversationService.findForCurrentUser for the role/ownership rationale.
+    // Admins default to their own conversations and opt in to the cross-user view via ?all=true.
+    return this.conversationService.findForCurrentUser(serviceOptions, { all: all === 'true' });
   }
 
   /**

package/src/core/modules/ai/core-ai.resolver.ts

@@ -270,21 +270,26 @@ export class CoreAiResolver {
   }
 
   /**
-   * Find the current user's AI conversations (admins see all).
+   * Find the current user's AI conversations (own only by default). An admin may
+   * pass `all: true` to list every user's conversations; each result carries its
+   * `createdBy` owner id for attribution. The argument is ignored for non-admins.
    *
    * The `messages` subdocument array is excluded from the list result — clients
    * fetching the conversation detail via `getAiConversation` get the full message
    * history. List payloads stay small even for users with many long conversations.
    */
-  @Query(() => [CoreAiConversation], { description: 'Find AI conversations of the current user' })
+  @Query(() => [CoreAiConversation], {
+    description: "Find AI conversations of the current user (admins may pass all: true to see every user's)",
+  })
   @Roles(RoleEnum.S_USER)
-  async findAiConversations(@GraphQLServiceOptions() serviceOptions: ServiceOptions): Promise<CoreAiConversation[]> {
-    const currentUser = serviceOptions?.currentUser;
-    const filterQuery = currentUser?.roles?.includes(RoleEnum.ADMIN) ? {} : { createdBy: currentUser?.id };
-    return this.conversationService.find(
-      { filterQuery },
-      { ...serviceOptions, roles: [RoleEnum.ADMIN, RoleEnum.S_CREATOR, RoleEnum.S_SELF], select: '-messages' },
-    );
+  async findAiConversations(
+    @GraphQLServiceOptions() serviceOptions: ServiceOptions,
+    @Args('all', { nullable: true, type: () => Boolean }) all?: boolean,
+  ): Promise<CoreAiConversation[]> {
+    // Owner-scoped list shared with the REST controller — see
+    // CoreAiConversationService.findForCurrentUser for the role/ownership rationale.
+    // Admins default to their own conversations and opt in to the cross-user view via all: true.
+    return this.conversationService.findForCurrentUser(serviceOptions, { all: all === true });
   }
 
   /**

package/src/core/modules/ai/models/core-ai-conversation.model.ts

@@ -6,6 +6,7 @@ import { Restricted } from '../../../common/decorators/restricted.decorator';
 import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
 import { RoleEnum } from '../../../common/enums/role.enum';
 import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+import { JSON } from '../../../common/scalars/json.scalar';
 import { CoreAiMessage } from './core-ai-message.model';
 
 export type AiConversationDocument = CoreAiConversation & Document;
@@ -45,6 +46,22 @@ export class CoreAiConversation extends CorePersistenceModel {
   })
   createdBy?: string = undefined;
 
+  /**
+   * Resolved creator identity (`{ id, email, firstName, lastName, username }`),
+   * attached at read time ONLY for an admin's cross-user list view (`all: true`)
+   * so each conversation is attributable to a named user. Not persisted and left
+   * unset on a normal own-only fetch, where the owner is the caller.
+   */
+  @UnifiedField({
+    description:
+      'Resolved creator identity (id, email, name) — set only in the admin cross-user list view, not persisted',
+    gqlType: JSON,
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => Object,
+  })
+  createdByUser?: Record<string, any> = undefined;
+
   /**
    * Conversation messages (appended via $push).
    */
@@ -76,7 +93,7 @@ export class CoreAiConversation extends CorePersistenceModel {
     if (force) {
       return this;
     }
-    if (user && (user.hasRole?.(RoleEnum.ADMIN) || (this.createdBy && String(this.createdBy) === user.id))) {
+    if (user && (user.hasRole?.(RoleEnum.ADMIN) || (this.createdBy && String(this.createdBy) === String(user.id)))) {
       return this;
     }
     // Hide conversations owned by other users (filtered out of list responses).

package/src/core/modules/ai/services/core-ai-conversation.service.ts

@@ -1,7 +1,9 @@
 import { Inject, Injectable } from '@nestjs/common';
-import { InjectModel } from '@nestjs/mongoose';
-import { Model, Types } from 'mongoose';
+import { InjectConnection, InjectModel } from '@nestjs/mongoose';
+import { Connection, Model, Types } from 'mongoose';
 
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { ServiceOptions } from '../../../common/interfaces/service-options.interface';
 import { CrudService } from '../../../common/services/crud.service';
 import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
 import { CoreAiConversationCreateInput } from '../inputs/core-ai-conversation-create.input';
@@ -21,8 +23,15 @@ export { AI_CONVERSATION_CLASS, AI_CONVERSATION_MODEL } from '../core-ai.constan
  * CRUD service for multi-turn {@link CoreAiConversation}s.
  *
  * `appendMessage()` adds a turn via `$push` (never round-trips the subdocument
- * array through `update()`). Ownership is enforced by the model's `securityCheck`
- * and by the resolver/controller passing `S_CREATOR`/`S_SELF` roles.
+ * array through `update()`). `findForCurrentUser()` is the shared owner-scoped
+ * list used by both the REST controller and the GraphQL resolver.
+ *
+ * Ownership is enforced differently per operation shape:
+ * - single-object `get`/`delete`: the controller/resolver pass
+ *   `S_CREATOR`/`S_SELF`, evaluated against the loaded `dbObject`.
+ * - list (`findForCurrentUser`): a list has no single `dbObject`, so the gate
+ *   uses `S_USER` and ownership is scoped by the server-computed `createdBy`
+ *   filterQuery plus the model's `securityCheck`.
  */
 @Injectable()
 export class CoreAiConversationService extends CrudService<
@@ -37,10 +46,107 @@ export class CoreAiConversationService extends CrudService<
     @InjectModel(AI_CONVERSATION_MODEL) protected override readonly mainDbModel: Model<AiConversationDocument>,
     @Inject(AI_CONVERSATION_CLASS)
     protected override readonly mainModelConstructor: CoreModelConstructor<CoreAiConversation>,
+    @InjectConnection() protected readonly connection: Connection,
   ) {
     super();
   }
 
+  /**
+   * List the AI conversations visible to the current user. By default — for
+   * every user, admins included — this returns only the caller's own
+   * conversations, newest first. An admin may opt in to the cross-user view
+   * (every user's conversations) by passing `{ all: true }`; the flag is
+   * ignored for non-admins, so it can never widen a regular user's scope.
+   *
+   * Each result carries its `createdBy` owner id. In the admin cross-user view
+   * (`all: true`) each result additionally carries a resolved `createdByUser`
+   * (`{ id, email, firstName, lastName, username }`) so the list is attributable
+   * to named users; on a normal own-only fetch that lookup is skipped, since the
+   * owner is the caller. The heavy `messages` subdocument array is excluded from
+   * the list payload — fetch a single conversation via `get()` for the full
+   * message history.
+   *
+   * Shared by the REST controller (`GET /ai/conversations`) and the GraphQL
+   * resolver (`findAiConversations`) so both API surfaces enforce ownership
+   * identically and cannot drift apart.
+   *
+   * A LIST operation has no single `dbObject`, so the per-document roles
+   * `S_CREATOR` / `S_SELF` can never be satisfied at the operation level —
+   * passing them rejected every non-admin with a 403 before ownership scoping
+   * ran. The operation gate therefore uses `[S_USER]`; the server-computed
+   * `createdBy` filterQuery and the model `securityCheck` scope the result to
+   * the owner.
+   */
+  async findForCurrentUser(
+    serviceOptions?: ServiceOptions,
+    options?: { all?: boolean },
+  ): Promise<CoreAiConversation[]> {
+    const currentUser = serviceOptions?.currentUser;
+    const isAdmin = !!currentUser?.roles?.includes(RoleEnum.ADMIN);
+    // Default is own-only for everyone; only an admin may opt in to all users' conversations.
+    const seeAll = isAdmin && options?.all === true;
+    const filterQuery = seeAll ? {} : { createdBy: currentUser?.id };
+    const conversations = await this.find(
+      { filterQuery, queryOptions: { sort: { createdAt: -1 } } },
+      { ...serviceOptions, roles: [RoleEnum.S_USER], select: '-messages' },
+    );
+    // Resolve creators to named users ONLY for the admin cross-user view — a normal
+    // fetch returns just the caller's own conversations, so the owner is already known.
+    if (seeAll && conversations.length) {
+      await this.attachCreators(conversations);
+    }
+    return conversations;
+  }
+
+  /**
+   * Attach a lightweight resolved creator (`{ id, email, firstName, lastName,
+   * username }`) as `createdByUser` to each conversation, so an admin's
+   * cross-user list is attributable to named users. Read-only lookup of
+   * non-sensitive identity fields via the shared `User` model on the same
+   * connection; fails soft (leaves `createdByUser` unset) when no `User` model is
+   * registered. Never called on a normal own-only fetch.
+   */
+  protected async attachCreators(conversations: CoreAiConversation[]): Promise<void> {
+    const ids = [
+      ...new Set(
+        conversations
+          .map((conversation) => conversation.createdBy)
+          .filter(Boolean)
+          .map(String),
+      ),
+    ];
+    if (!ids.length) {
+      return;
+    }
+    let userModel: Model<any>;
+    try {
+      userModel = this.connection.model('User');
+    } catch {
+      // No `User` model registered on this connection (exotic setup) — skip attribution.
+      return;
+    }
+    const users = await userModel
+      .find({ _id: { $in: ids } })
+      .select('email firstName lastName username')
+      .lean()
+      .exec();
+    const byId = new Map(
+      (users as any[]).map((user) => [
+        String(user._id),
+        {
+          email: user.email,
+          firstName: user.firstName,
+          id: String(user._id),
+          lastName: user.lastName,
+          username: user.username,
+        },
+      ]),
+    );
+    for (const conversation of conversations) {
+      conversation.createdByUser = byId.get(String(conversation.createdBy));
+    }
+  }
+
   /**
    * Append a message to a conversation via `$push` (system-internal; the user
    * already authorized the prompt that produced it). The array is capped at

package/src/core/modules/hub/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,64 @@
+# Hub Integration Checklist
+
+The Hub is **config-only** — no files need to be created in the consuming project. It is auto-registered
+by `CoreModule.forRoot()` when `hub` is present in the config.
+
+## Reference Implementation
+
+- Local: `node_modules/@lenne.tech/nest-server/src/core/modules/hub/`
+- The framework's own e2e config (`src/config.env.ts`) enables it in `local`/`development`/`e2e`/`ci`.
+
+## Quick Setup
+
+### 1. Enable per environment
+
+**Edit:** `src/config.env.ts`
+
+```typescript
+// development / local
+hub: {
+  collectors: { queries: true },   // opt-in query profiler
+  mailbox: { mode: 'capture' },    // capture outgoing mail locally (Mailpit replacement)
+},
+
+// production — usually omit `hub` entirely, or (if you want it, still ADMIN-gated):
+// hub: { collectors: { queries: false }, mailbox: false },
+```
+
+That's it. Sign in as a user with `RoleEnum.ADMIN` and open `/hub`.
+
+## Optional Enhancements
+
+| Want                        | Do                                                                                                                                                                             |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Cron panel populated**    | Import `ScheduleModule.forRoot()` in your ServerModule (usually already present).                                                                                              |
+| **Query profiler**          | Set `hub.collectors.queries: true` (opts the driver into `monitorCommands`).                                                                                                   |
+| **Migrations run/rollback** | Set `hub.migrations.dir` to your migrations directory (default `./migrations`). In compiled deployments point it at the built JS. Use `lockCollectionName` for cluster safety. |
+| **Custom look / behavior**  | Pass `overrides.hub.{controller,actionsController,service,htmlService,actionsService}` to `CoreModule.forRoot()`.                                                              |
+
+## Verification Checklist
+
+- [ ] `pnpm run build` succeeds
+- [ ] Sign in as ADMIN → `GET /hub` returns the dashboard HTML
+- [ ] A non-admin user gets `403`; an anonymous request gets `401`
+- [ ] `GET /hub/dashboard.json` returns build/memory/features
+- [ ] `GET /hub/config.json` shows `***` for secrets (never the real values)
+- [ ] Mutating actions without `X-Hub-Request: 1` return `403`
+
+## Common Mistakes
+
+| Mistake                                          | Symptom                                                        | Fix                                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hub` not set in the target environment          | `/hub` → 404                                                   | Add `hub: true` (or an options object) to that env's config block                                                                                                                                                                                                                                  |
+| `mailbox.mode: 'capture'` in production          | Startup error                                                  | Use `mode: 'copy'` or disable the mailbox in production — capture suppresses all mail                                                                                                                                                                                                              |
+| Query panel empty                                | queries collector off (default)                                | `hub.collectors.queries: true`                                                                                                                                                                                                                                                                     |
+| Cron panel empty                                 | `ScheduleModule.forRoot()` not imported                        | Import it in your ServerModule                                                                                                                                                                                                                                                                     |
+| Hub path collides with a project route           | 404 / wrong page                                               | Set a distinct `hub.path` (e.g. `admin/hub`)                                                                                                                                                                                                                                                       |
+| No roles guard registered (auth system disabled) | Every `/hub` sidecar/action returns 200 for anonymous requests | The Hub relies on the framework's `RolesGuard`/`BetterAuthRolesGuard` (registered by the auth/BetterAuth module) to enforce `@Roles(RoleEnum.ADMIN)`. If you disable BetterAuth AND legacy auth, no guard runs and the ADMIN gate is inert. Keep an auth module enabled, or do not expose the Hub. |
+
+> **Auth dependency (why):** the Hub does not register its own guard — it assigns `@Roles(hub.roles)`
+> (default `ADMIN`) as metadata and depends on the app-wide `RolesGuard` / `BetterAuthRolesGuard` to
+> read it. That guard ships with the auth/BetterAuth modules. In a normal project one of them is
+> active, so the gate works out of the box; but an app that runs with _no_ auth system has no guard
+> to enforce the roles, and the sidecars/actions would be reachable unauthenticated. Either keep an
+> auth module enabled or leave the Hub disabled in such a setup.

package/src/core/modules/hub/README.md

@@ -0,0 +1,159 @@
+# Hub — Admin Area (Operator Cockpit)
+
+A build-free, ADMIN-gated dashboard of runtime information and admin tools, served directly by the
+framework. Inspired by the sister project [nest-base](https://github.com/lenneTech/nest-base)'s Hub,
+but adapted to this stack (NestJS + GraphQL + Mongoose) and shipped as **dependency-free server-side
+HTML + a vanilla-JS SPA** (no React, no build step) so it works identically in npm- and vendor-mode.
+
+## Enable it
+
+The Hub is **never enabled implicitly** — switch it on per environment:
+
+```typescript
+// config.env.ts
+{
+  hub: true,                          // enabled at /hub, admin-only, default collectors
+  // or, with options:
+  hub: {
+    path: 'hub',                      // default 'hub'
+    collectors: { queries: true },    // query profiler is opt-in (enables driver command monitoring)
+    mailbox: { mode: 'capture' },     // built-in Mailpit-style mail capture (dev/test)
+  },
+}
+```
+
+Do NOT set `hub` in the `production` block unless you intend the cockpit to be reachable there
+(it stays ADMIN-gated). See `IHubConfig` in `interfaces/hub-config.interface.ts` for every option.
+
+## Panels
+
+| Panel                | Route                 | Source                                                          |
+| -------------------- | --------------------- | --------------------------------------------------------------- |
+| Dashboard            | `/hub`                | health, build info, memory, feature matrix, links               |
+| Diagnostics          | `/hub/diagnostics`    | heap/rss, node/platform, collector buffer levels                |
+| Logs                 | `/hub/logs`           | in-memory log ring buffer (redacted)                            |
+| Request Traces       | `/hub/traces`         | HTTP timing middleware                                          |
+| Query Performance    | `/hub/queries`        | MongoDB driver command monitoring (opt-in)                      |
+| Cron Jobs            | `/hub/cron`           | `@nestjs/schedule` `SchedulerRegistry` (optional)               |
+| Database             | `/hub/db`             | dbStats / per-collection collStats                              |
+| Models / ERD         | `/hub/models`         | Mongoose schemas → Mermaid ER diagram                           |
+| Migrations           | `/hub/migrations`     | `MigrationRunner` status + run/rollback                         |
+| Files                | `/hub/files`          | GridFS listing + delete                                         |
+| Config               | `/hub/config`         | full config, secrets masked                                     |
+| Auth Migration       | `/hub/auth-migration` | Legacy → IAM progress (BetterAuth, optional)                    |
+| Routes / Permissions | `/hub/routes`         | route + role + `@Restricted` map (Permissions module, optional) |
+| Error Codes          | `/hub/error-codes`    | de/en catalog (ErrorCode module, optional)                      |
+| Email Preview        | `/hub/emails`         | EJS templates rendered with sample data                         |
+| Mailbox              | `/hub/mailbox`        | captured outgoing mail (Mailpit replacement)                    |
+| AI                   | `/hub/ai`             | AI usage summary (AI module, optional)                          |
+
+Each panel has a `*.json` sidecar (the stable data contract) that the client polls. Optional sources
+degrade to an "unavailable" state instead of erroring.
+
+## Actions (mutating)
+
+Enabled by default (`actions: true`). Every mutating request requires the `X-Hub-Request: 1` header
+(CSRF defense) and destructive ones a server-validated `confirm` keyword:
+
+| Action                  | Endpoint                                   | Confirm      |
+| ----------------------- | ------------------------------------------ | ------------ |
+| Run pending migrations  | `POST /hub/actions/migrations/run`         | `RUN`        |
+| Rollback last migration | `POST /hub/actions/migrations/down`        | `DOWN`       |
+| Delete GridFS file      | `DELETE /hub/actions/files/:id`            | the filename |
+| Cron start/stop/trigger | `POST /hub/actions/cron/:name/:action`     | the job name |
+| Clear collector buffer  | `POST /hub/actions/collectors/:name/clear` | `CLEAR`      |
+| Send test mail          | `POST /hub/actions/email/test`             | —            |
+
+Every action writes an audit line: `[HUB-ACTION] <action> by user <id>`.
+
+## Security
+
+- **Auth**: the DATA sidecars (`*.json`) and all actions are `@Roles(RoleEnum.ADMIN)` (configurable
+  via `hub.roles`; `false` = public — dangerous). The **shell** (page routes) is public chrome only —
+  it shows a **login form** when the data is 401, so the Hub is self-sufficient: an admin can sign in
+  directly at the API (email/password → `loginEndpoint`, default `/iam/sign-in/email` → session cookie)
+  without the frontend, with a token-paste fallback for cookie-less setups. In fullstack, a
+  cross-subdomain session cookie from the app login already authenticates `/hub` — no separate login.
+  A **"Sign out"** button in the topbar POSTs to `hub.logoutEndpoint` (default `/iam/sign-out`),
+  clears the session cookie + any pasted token, and returns to the login gate. The logout endpoint is
+  delivered only in the ADMIN-gated `session.json` payload, never in the public shell.
+  - **Public-shell trade-off (by design):** because the shell must render before authentication, its
+    HTML source reveals the panel structure, the environment name (shown on the login card) and any
+    configured external links (`hub.links.*`) to an unauthenticated request. This is intentional — the
+    panel structure is already discoverable via the public `hub.js` — and carries no data: every
+    `*.json` sidecar and every action stays ADMIN-gated. Do not place secrets in `hub.links.*` (e.g.
+    an internal Mailpit URL) if the shell's origin is reachable by untrusted clients.
+- **Action errors**: mutating actions return plain admin-facing messages (not `ErrorCode` catalog
+  entries) by design — the `ErrorCode` i18n module is optional and the Hub cannot hard-depend on it.
+  The messages are centralized in `hub-action-messages.ts` (`HubActionMessage`) so the wording stays
+  consistent and reviewable in one place.
+- **CSP**: strict per-request nonce; no `unsafe-inline`; `X-Frame-Options: DENY`; `no-store`.
+- **Secrets**: the config viewer deep-clones and masks by key pattern + `security.secretFields`.
+- **Interceptor safety**: sidecars return pre-serialized JSON strings, so the global response
+  interceptors never walk/mutate live config.
+- **Mailbox guard**: `mode: 'capture'` throws at startup in any **reachable** environment (anything
+  whose `env` is not `local`/`development`/`test`/`ci`/`e2e`) — it suppresses outgoing mail.
+- **Public-access guard**: `roles: false` (no auth check — public config viewer, logs and destructive
+  actions) throws at startup in any **reachable** environment unless `hub.allowPublicAccessInProduction:
+true` is set explicitly. This closes the single most dangerous Hub misconfiguration (a `roles: false`
+  copied from a local config into a reachable environment). The reachable check is fail-safe: it treats
+  every env name except the known local/test set as reachable, so a custom name (`prod`, `preprod`,
+  `staging-2`, …) cannot bypass it. Only acknowledge public access behind a fully-controlled network
+  boundary (VPN / IP allow-list / authenticating reverse proxy).
+- **No-guard warning**: the Hub registers no guard of its own — its ADMIN gate is enforced by the
+  app-wide roles guard from BetterAuth (IAM) or the legacy Auth module. If the Hub is enabled and
+  gated but neither is active (and you have not registered your own `APP_GUARD`), `CoreModule` logs a
+  loud startup warning, because nothing would then enforce the gate.
+- **CSRF**: mutating actions require the `X-Hub-Request` custom header, which forces a CORS preflight
+  that a restrictive allowlist rejects for foreign origins — **that header** (not the type-to-confirm
+  keyword, which is public UX safety, not a token) is the CSRF barrier. It holds with the default
+  `SameSite=Lax` session cookie or Bearer-token auth. Do NOT combine `cors.allowAll: true` with a
+  `SameSite=None` cookie (cross-subdomain fullstack): that lets any origin pass the preflight — pin
+  `cors` to your `appUrl` instead.
+- **Redaction is best-effort (ADMIN-only surfaces)**: the config viewer masks by key pattern +
+  `security.secretFields` (a secret under an unusual key can slip); the logs/queries collectors and
+  the copy-mode mailbox redact patterned secrets (JWT / Bearer / `key=value` / cookie / reset-link
+  path tokens) but cannot catch an arbitrary value logged without a recognizable shape. All are
+  ADMIN-gated — treat Hub access as equivalent to config/log read access.
+
+### Routes / Permissions panel vs. the standalone `/permissions` endpoint
+
+The **Routes / Permissions** panel renders the same data as the standalone permissions module — the
+full security map (every route + its required roles + `@Restricted` field rules) — but _inside_ the
+Hub, so it inherits the Hub's ADMIN gate, per-environment opt-in and strict CSP. It reuses the
+permissions **scanner** (`CorePermissionsService`), so it needs the `permissions` module enabled
+(`config.permissions`); otherwise the panel degrades to an "unavailable" state.
+
+The two surfaces are **independent** and answer the common "how do I reach it?" questions:
+
+| Situation                                       | How to reach the report                                                                                                                                                                                                                                                    |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Hub **on**, `permissions` **on**                | Hub → **Routes / Permissions** panel (ADMIN, login-gated by the Hub). The standalone `/permissions` also works per its own `role` (default ADMIN).                                                                                                                         |
+| Hub **off**, `permissions` **on** (ADMIN)       | The standalone `/permissions` is ADMIN-gated but has **no login page** — reach it with an ADMIN **session cookie** (be logged in via the app) or a **bearer token** (`Authorization: Bearer <jwt>` from `POST /iam/sign-in/email`), exactly like any other ADMIN endpoint. |
+| Hub **off**, want frictionless **local** access | Set `permissions: { role: false }` — public, no auth. Legitimate **only** on a local, non-network-reachable machine, as a conscious opt-in. Never ship it to a reachable environment: the report is a reconnaissance goldmine.                                             |
+| `permissions` **off**                           | No report anywhere: `/permissions` is not registered (404) and the Hub panel shows "unavailable".                                                                                                                                                                          |
+
+**Security note:** the permissions report exposes your entire authorization model. Keep it ADMIN
+(the default) everywhere it could be reachable; use `role: false` only behind a network boundary you
+fully control. In production the framework's own config does not register the permissions module at all.
+
+## Collectors
+
+Three in-memory ring buffers (fixed capacity, no timers, per-app-instance — parallel-test-safe):
+
+- **Logs** — installs a chaining `Logger.overrideLogger()` delegate (no main.ts change), restored on shutdown.
+- **Traces** — an Express middleware registered only when 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` from `core.module.ts`.
+
+## Overrides
+
+```typescript
+CoreModule.forRoot(envConfig, {
+  hub: { service: MyHubService, htmlService: MyHubHtmlService },
+});
+```
+
+Fields: `controller`, `actionsController`, `service`, `htmlService`, `actionsService`.
+
+See [INTEGRATION-CHECKLIST.md](./INTEGRATION-CHECKLIST.md) for setup in a consumer project.