@lenne.tech/nest-server 11.31.1 → 11.31.3

package/src/core/modules/hub/core-hub-actions.controller.ts

@@ -0,0 +1,137 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Delete,
+  ForbiddenException,
+  Headers,
+  Param,
+  Post,
+} from '@nestjs/common';
+
+import { HubActionMessage } from './hub-action-messages';
+import { CoreHubActionsService } from './services/core-hub-actions.service';
+
+/** Body shape shared by the confirm-guarded actions. */
+interface ConfirmBody {
+  confirm?: string;
+}
+
+/**
+ * The Hub's mutating actions (migrations, file delete, cron control, buffer clears, test mail).
+ *
+ * Registered as a SEPARATE controller only when `hub.actions !== false`, so disabling actions simply
+ * removes the routes (404). Path + roles metadata are assigned at runtime in `CoreHubModule.forRoot()`
+ * exactly like the read controller.
+ *
+ * Every mutating request must carry the `X-Hub-Request: 1` header (CSRF defense in depth: a custom
+ * header makes the request non-simple, so a cross-origin attempt triggers a CORS preflight the
+ * framework will not approve). Destructive actions additionally require a server-validated `confirm`
+ * keyword that the UI makes the operator type.
+ *
+ * Overridable via `overrides.hub.actionsController`.
+ */
+@Controller()
+export class CoreHubActionsController {
+  constructor(protected readonly actions: CoreHubActionsService) {}
+
+  @Post('actions/collectors/:name/clear')
+  async clearCollector(
+    @Param('name') name: string,
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    this.requireConfirm(body, 'CLEAR');
+    if (!['logs', 'mailbox', 'queries', 'traces'].includes(name)) {
+      throw new BadRequestException(HubActionMessage.unknownCollector);
+    }
+    return this.wrap(() =>
+      Promise.resolve(this.actions.clearBuffer(name as 'logs' | 'mailbox' | 'queries' | 'traces')),
+    );
+  }
+
+  @Post('actions/cron/:name/:action')
+  async cron(
+    @Param('name') name: string,
+    @Param('action') action: string,
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    if (!['start', 'stop', 'trigger'].includes(action)) {
+      throw new BadRequestException(HubActionMessage.unknownCronAction);
+    }
+    this.requireConfirm(body, name);
+    return this.wrap(() => Promise.resolve(this.actions.controlCron(name, action as 'start' | 'stop' | 'trigger')));
+  }
+
+  @Delete('actions/files/:id')
+  async deleteFile(
+    @Param('id') id: string,
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    if (!body?.confirm) {
+      throw new BadRequestException(HubActionMessage.confirmationFilenameRequired);
+    }
+    return this.wrap(() => this.actions.deleteFile(id, body.confirm as string));
+  }
+
+  @Post('actions/email/test')
+  async emailTest(
+    @Body() body: { locale?: string; template?: string; to?: string },
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    if (!body?.to) {
+      throw new BadRequestException(HubActionMessage.recipientRequired);
+    }
+    return this.wrap(() => this.actions.sendTestEmail(body.to as string, body.template, body.locale));
+  }
+
+  @Post('actions/migrations/down')
+  async migrationsDown(
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    this.requireConfirm(body, 'DOWN');
+    return this.wrap(() => this.actions.rollbackMigration());
+  }
+
+  @Post('actions/migrations/run')
+  async migrationsRun(
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    this.requireConfirm(body, 'RUN');
+    return this.wrap(() => this.actions.runMigrations());
+  }
+
+  /** Validate the server-side confirmation keyword. */
+  protected requireConfirm(body: ConfirmBody, expected: string): void {
+    if (body?.confirm !== expected) {
+      throw new BadRequestException(HubActionMessage.confirmationKeywordMismatch(expected));
+    }
+  }
+
+  /** CSRF defense: mutating requests must carry the X-Hub-Request header. */
+  protected requireHubRequest(header: string | undefined): void {
+    if (!header) {
+      throw new ForbiddenException(HubActionMessage.missingHubRequestHeader);
+    }
+  }
+
+  /** Run an action, mapping domain errors to 400 (admin-facing plain message). */
+  protected async wrap(fn: () => Promise<unknown>): Promise<unknown> {
+    try {
+      const result = await fn();
+      return { ok: true, timestamp: new Date().toISOString(), ...(result as object) };
+    } catch (error) {
+      throw new BadRequestException(error instanceof Error ? error.message : HubActionMessage.actionFailed);
+    }
+  }
+}

package/src/core/modules/hub/core-hub-html.service.ts

@@ -0,0 +1,135 @@
+import { Inject, Injectable } from '@nestjs/common';
+
+import { HUB_CONFIG } from './hub.constants';
+
+/**
+ * Per-process cache-bust token for the client bundle (`hub.js?v=<token>`). It changes on every server
+ * start, so the browser refetches the script after a restart/redeploy (a dev code change is never
+ * masked by the immutable cache), while a single boot keeps the long-lived cache. The app version is
+ * deliberately NOT part of this public URL — it would leak the version to unauthenticated requests
+ * (the version is shown only in the ADMIN-gated, client-built topbar from session.json).
+ */
+const HUB_ASSET_TOKEN = Date.now().toString(36);
+import { getHubClientJs } from './helpers/hub-client-js.helper';
+import { escapeHtml, escapeJsString, HUB_NONCE_PLACEHOLDER } from './helpers/hub-shell.helper';
+import { ResolvedHubConfig } from './interfaces/hub-config.interface';
+
+/**
+ * Builds the Hub's single, self-contained HTML shell. Every page route serves the same shell (the
+ * client router picks the active panel from the URL), so this is stateless apart from the injected
+ * config. All server-provided values are escaped; the auth token (when present) is embedded as a JS
+ * string so sidecar fetches carry it in cookie-less setups.
+ *
+ * Overridable: a project may replace it via `overrides.hub.htmlService` to re-skin the cockpit.
+ */
+@Injectable()
+export class CoreHubHtmlService {
+  constructor(@Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig) {}
+
+  /** The shared client runtime script — served verbatim from `GET /{hub}/hub.js`. */
+  buildClientScript(): string {
+    return getHubClientJs();
+  }
+
+  /**
+   * Build the full shell HTML with `__CSP_NONCE__` placeholders. The controller replaces the
+   * placeholders per request via `injectNonce()`.
+   *
+   * @param authHeader - the incoming `Authorization` header, embedded so client fetches can replay it
+   */
+  buildShell(authHeader?: string): string {
+    const base = '/' + this.config.path;
+
+    const bootstrap = [
+      `window.__HUB_BASE__='${escapeJsString(base)}';`,
+      `window.__HUB_POLL_MS__=${Number(this.config.pollIntervalMs) || 5000};`,
+      `window.__HUB_LOGIN__='${escapeJsString(this.config.loginEndpoint)}';`,
+      authHeader ? `window.__HUB_TOKEN__='${escapeJsString(authHeader)}';` : '',
+    ].join('');
+
+    // SECURITY (self-sufficient login): the shell is PUBLIC because it must render the login form
+    // before authentication. It therefore carries NO cockpit chrome — no navigation, no environment
+    // badge, no version, no external links. The client builds all of that ONLY after a successful
+    // ADMIN auth check, from the ADMIN-gated `session.json` payload. So an unauthenticated request to
+    // any /hub page reveals nothing of the Hub's structure; #hub-app stays empty until login.
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Hub · nest-server</title>
+  <style nonce="${HUB_NONCE_PLACEHOLDER}">${this.css()}</style>
+</head>
+<body class="hub-locked">
+  <div id="hub-gate" class="hub-gate"></div>
+  <div id="hub-app"></div>
+  <dialog id="hub-confirm" class="hub-dialog"></dialog>
+  <script nonce="${HUB_NONCE_PLACEHOLDER}">${bootstrap}</script>
+  <script nonce="${HUB_NONCE_PLACEHOLDER}" src="${escapeHtml(base)}/hub.js?v=${HUB_ASSET_TOKEN}"></script>
+</body>
+</html>`;
+  }
+
+  protected css(): string {
+    return `
+:root{--bg:#0b0d12;--panel:#141821;--panel2:#1b212d;--border:#242c3a;--text:#e6ebf2;--muted:#8b97a8;--accent:#4f8cff;--ok:#3fb950;--warn:#d29922;--err:#f85149}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--text);font:14px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif}
+.hub-layout{display:flex;min-height:100vh}
+.hub-nav{width:230px;flex:0 0 230px;background:var(--panel);border-right:1px solid var(--border);padding:16px 10px;overflow-y:auto}
+.hub-brand{font-weight:700;font-size:18px;padding:4px 10px 14px;display:flex;align-items:center;gap:8px}
+.hub-env{font-size:10px;text-transform:uppercase;letter-spacing:.05em;padding:2px 6px;border-radius:4px;background:var(--panel2);color:var(--muted)}
+.hub-env-production{background:#3d1418;color:#ff7b72}
+.hub-nav h3{font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);margin:16px 10px 4px}
+.hub-nav a{display:block;padding:6px 10px;border-radius:6px;color:var(--text);text-decoration:none;font-size:13px}
+.hub-nav a:hover{background:var(--panel2)}
+.hub-nav a.active{background:var(--accent);color:#fff}
+.hub-nav a.hub-nav-disabled{opacity:.38;cursor:not-allowed}
+.hub-nav a.hub-nav-disabled:hover{background:none}
+.hub-nav a.hub-ext::after{content:' ↗';color:var(--muted)}
+.hub-main{flex:1;min-width:0;display:flex;flex-direction:column}
+.hub-topbar{display:flex;align-items:center;justify-content:space-between;padding:14px 22px;border-bottom:1px solid var(--border)}
+.hub-topbar h1{font-size:18px;margin:0}
+.hub-meta{color:var(--muted);font-size:12px;display:flex;align-items:center;gap:8px}
+.hub-dot{width:9px;height:9px;border-radius:50%;display:inline-block;background:var(--muted)}
+.hub-dot-ok{background:var(--ok)}.hub-dot-err{background:var(--err)}
+.hub-content{padding:22px;overflow:auto}
+.hub-tiles{display:grid;grid-template-columns:repeat(auto-fill,minmax(180px,1fr));gap:12px;margin-bottom:20px}
+.hub-tile{background:var(--panel);border:1px solid var(--border);border-radius:10px;padding:14px}
+.hub-tile-label{color:var(--muted);font-size:12px}
+.hub-tile-value{font-size:22px;font-weight:600;margin-top:4px}
+.hub-tile-value.ok{color:var(--ok)}.hub-tile-value.warn{color:var(--warn)}.hub-tile-value.err{color:var(--err)}
+.hub-tile-sub{color:var(--muted);font-size:11px;margin-top:4px}
+.hub-table{width:100%;border-collapse:collapse;background:var(--panel);border:1px solid var(--border);border-radius:8px;overflow:hidden}
+.hub-table th{text-align:left;padding:8px 12px;background:var(--panel2);color:var(--muted);font-size:12px;font-weight:600;cursor:pointer}
+.hub-table td{padding:8px 12px;border-top:1px solid var(--border);font-size:13px}
+.hub-table tr:hover td{background:var(--panel2)}
+.hub-json{background:var(--panel);border:1px solid var(--border);border-radius:8px;padding:14px;overflow:auto;font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;white-space:pre;max-width:100%}
+.hub-empty{color:var(--muted);padding:40px;text-align:center;border:1px dashed var(--border);border-radius:8px}
+.hub-btn{background:var(--panel2);color:var(--text);border:1px solid var(--border);border-radius:6px;padding:6px 12px;font-size:13px;cursor:pointer}
+.hub-btn:hover{border-color:var(--accent)}
+.hub-btn:disabled{opacity:.5;cursor:not-allowed}
+.hub-btn-primary{background:var(--accent);border-color:var(--accent);color:#fff}
+.hub-btn-danger{background:var(--err);border-color:var(--err);color:#fff}
+.hub-signout{padding:4px 10px;font-size:12px;margin-left:4px}
+.hub-input{width:100%;background:var(--bg);border:1px solid var(--border);border-radius:6px;padding:8px;color:var(--text);margin:8px 0;font-size:13px}
+.hub-dialog{background:var(--panel);color:var(--text);border:1px solid var(--border);border-radius:12px;padding:20px;max-width:440px;width:90%}
+.hub-dialog::backdrop{background:rgba(0,0,0,.6)}
+.hub-dialog h3{margin:0 0 8px}
+.hub-dialog-actions{display:flex;justify-content:flex-end;gap:8px;margin-top:12px}
+.hub-hint{color:var(--muted);font-size:12px}
+.hub-chip{display:inline-block;padding:1px 7px;border-radius:10px;font-size:11px;background:var(--panel2);color:var(--muted)}
+.hub-chip-ok{background:#132d1c;color:var(--ok)}.hub-chip-warn{background:#2d2611;color:var(--warn)}.hub-chip-err{background:#3d1418;color:var(--err)}
+.hub-toast{position:fixed;bottom:20px;right:20px;background:var(--panel2);border:1px solid var(--accent);color:var(--text);padding:12px 16px;border-radius:8px;font-size:13px;z-index:9999;box-shadow:0 6px 20px rgba(0,0,0,.4)}
+.hub-toast-err{border-color:var(--err)}
+/* Auth gate: nothing of the app is visible until authenticated. The client builds the layout into
+   #hub-app only after a successful auth check, so body.hub-locked just hides the (empty) app root. */
+.hub-gate{display:none;position:fixed;inset:0;background:var(--bg);z-index:100;align-items:center;justify-content:center;padding:20px}
+.hub-locked .hub-gate{display:flex}
+.hub-locked #hub-app{display:none}
+.hub-gate-card{background:var(--panel);border:1px solid var(--border);border-radius:12px;padding:28px;width:360px;max-width:100%}
+.hub-gate-card h2{margin:0 0 4px}
+.hub-gate-brand{font-weight:700;font-size:20px;margin-bottom:18px;display:flex;align-items:center;gap:8px}
+`;
+  }
+}

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

@@ -0,0 +1,286 @@
+import { Controller, Get, Headers, Optional, Param, Query, Res } from '@nestjs/common';
+import { Response } from 'express';
+
+import { Roles } from '../../common/decorators/roles.decorator';
+import { RoleEnum } from '../../common/enums/role.enum';
+
+import { CoreHubHtmlService } from './core-hub-html.service';
+import { CoreHubService } from './core-hub.service';
+import { HUB_PANELS } from './hub-nav';
+import { CoreHubDbService } from './services/core-hub-db.service';
+import { CoreHubEmailService } from './services/core-hub-email.service';
+import { CoreHubMailboxService } from './services/core-hub-mailbox.service';
+import { CoreHubMigrationsService } from './services/core-hub-migrations.service';
+import { CoreHubSourcesService } from './services/core-hub-sources.service';
+import { HubLogBufferService } from './services/hub-log-buffer.service';
+import { HubQueryProfilerService } from './services/hub-query-profiler.service';
+import { HubTraceBufferService } from './services/hub-trace-buffer.service';
+import { buildHubSecurityHeaders, escapeHtml, generateNonce, injectNonce } from './helpers/hub-shell.helper';
+
+/** Route sub-paths of every non-root panel — the shell handler answers all of them. */
+const HUB_PAGE_PATHS = HUB_PANELS.filter((panel) => panel.path).map((panel) => panel.path);
+
+/**
+ * Serves the Hub SPA shell (all panel routes), the shared client runtime and the read-only JSON
+ * sidecars. Mutating operations live in `CoreHubActionsController`.
+ *
+ * The controller path and required roles are assigned at runtime in `CoreHubModule.forRoot()` via
+ * `Reflect.defineMetadata` (same pattern as the permissions module), so they follow the configured
+ * `hub.path` / `hub.roles`.
+ *
+ * Every response uses `@Res()` and is written manually: this bypasses the four global response
+ * interceptors (which would otherwise walk/mutate the payload — `CheckSecurityInterceptor` deletes
+ * secret-named keys in place) and lets the Hub set its own strict CSP + no-store headers.
+ *
+ * Overridable via `overrides.hub.controller`.
+ */
+@Controller()
+export class CoreHubController {
+  private cachedClientScript?: string;
+
+  constructor(
+    protected readonly hubService: CoreHubService,
+    protected readonly htmlService: CoreHubHtmlService,
+    protected readonly dbService: CoreHubDbService,
+    protected readonly migrationsService: CoreHubMigrationsService,
+    protected readonly sourcesService: CoreHubSourcesService,
+    protected readonly emailService: CoreHubEmailService,
+    protected readonly logBuffer: HubLogBufferService,
+    protected readonly traceBuffer: HubTraceBufferService,
+    protected readonly queryProfiler: HubQueryProfilerService,
+    // Only provided when the mailbox is enabled.
+    @Optional() protected readonly mailboxService?: CoreHubMailboxService,
+  ) {}
+
+  @Get('ai.json')
+  async aiJson(@Res() res: Response): Promise<void> {
+    this.sendJson(res, await this.sourcesService.getAi());
+  }
+
+  @Get('auth-migration.json')
+  async authMigrationJson(@Res() res: Response): Promise<void> {
+    this.sendJson(res, await this.sourcesService.getAuthMigration());
+  }
+
+  @Get('config.json')
+  configJson(@Res() res: Response): void {
+    this.sendJson(res, this.hubService.getConfigMasked());
+  }
+
+  @Get('cron.json')
+  cronJson(@Res() res: Response): void {
+    this.sendJson(res, this.sourcesService.getCron());
+  }
+
+  @Get('emails.json')
+  emailsJson(@Res() res: Response): void {
+    if (!this.emailService.previewEnabled) {
+      this.sendJson(res, { available: false, hint: 'The email preview panel is disabled (hub.emailPreview: false).' });
+      return;
+    }
+    this.sendJson(res, this.emailService.getTemplates());
+  }
+
+  @Get('error-codes.json')
+  errorCodesJson(@Query('locale') locale: string | undefined, @Res() res: Response): void {
+    this.sendJson(res, this.sourcesService.getErrorCodes(locale || 'en'));
+  }
+
+  @Get('dashboard.json')
+  dashboardJson(@Res() res: Response): void {
+    this.sendJson(res, this.hubService.getDashboard());
+  }
+
+  @Get('db.json')
+  async dbJson(@Res() res: Response): Promise<void> {
+    this.sendJson(res, await this.dbService.getDbStats());
+  }
+
+  @Get('diagnostics.json')
+  diagnosticsJson(@Res() res: Response): void {
+    this.sendJson(res, this.hubService.getDiagnostics(this.collectorBuffers()));
+  }
+
+  @Get('files.json')
+  async filesJson(
+    @Query('bucket') bucket: string | undefined,
+    @Query('skip') skip: string | undefined,
+    @Query('limit') limit: string | undefined,
+    @Res() res: Response,
+  ): Promise<void> {
+    this.sendJson(res, await this.dbService.getFiles(bucket || 'fs', Number(skip) || 0, Number(limit) || 100));
+  }
+
+  @Get('migrations.json')
+  async migrationsJson(@Res() res: Response): Promise<void> {
+    this.sendJson(res, await this.migrationsService.getStatus());
+  }
+
+  @Get('mailbox.json')
+  mailboxJson(@Query('since') since: string | undefined, @Res() res: Response): void {
+    if (!this.mailboxService) {
+      this.sendJson(res, { available: false, hint: 'The mailbox is not enabled.' });
+      return;
+    }
+    this.sendJson(res, this.mailboxService.getMailbox(since !== undefined ? Number(since) : undefined));
+  }
+
+  @Get('mailbox/:seq/html')
+  mailboxHtml(@Param('seq') seq: string, @Res() res: Response): void {
+    const html = this.mailboxService?.getMailHtml(Number(seq));
+    res.set({
+      'Cache-Control': 'no-store',
+      'Content-Security-Policy': "default-src 'none'; img-src * data:; style-src 'unsafe-inline'; font-src data:",
+      'X-Content-Type-Options': 'nosniff',
+      'X-Frame-Options': 'SAMEORIGIN',
+    });
+    res
+      .type('html')
+      .send(
+        html ??
+          '<!DOCTYPE html><html><body style="font-family:sans-serif;color:#8b97a8;padding:20px">No preview available.</body></html>',
+      );
+  }
+
+  @Get('logs.json')
+  logsJson(@Query('since') since: string | undefined, @Res() res: Response): void {
+    if (!this.logBuffer.enabled) {
+      this.sendJson(res, { available: false, hint: 'The logs collector is disabled.' });
+      return;
+    }
+    this.sendJson(res, this.logBuffer.getData(since !== undefined ? Number(since) : undefined));
+  }
+
+  @Get('models.json')
+  modelsJson(@Res() res: Response): void {
+    this.sendJson(res, this.dbService.getModels());
+  }
+
+  /**
+   * ADMIN-gated auth probe AND cockpit-chrome payload: 200 returns the navigation, environment badge,
+   * version and external links the client uses to build the layout; 401/403 keeps the shell showing
+   * only the login form. The public shell HTML deliberately carries none of this data.
+   */
+  @Get('session.json')
+  sessionJson(@Res() res: Response): void {
+    this.sendJson(res, this.hubService.getSessionPayload());
+  }
+
+  @Get('queries.json')
+  queriesJson(@Res() res: Response): void {
+    if (!this.queryProfiler.enabled) {
+      this.sendJson(res, {
+        available: false,
+        hint: 'The query profiler is disabled (opt-in via hub.collectors.queries).',
+      });
+      return;
+    }
+    this.sendJson(res, this.queryProfiler.getData());
+  }
+
+  @Get('traces.json')
+  tracesJson(@Query('since') since: string | undefined, @Res() res: Response): void {
+    if (!this.traceBuffer.enabled) {
+      this.sendJson(res, { available: false, hint: 'The traces collector is disabled.' });
+      return;
+    }
+    this.sendJson(res, this.traceBuffer.getData(since !== undefined ? Number(since) : undefined));
+  }
+
+  @Get('routes.json')
+  async routesJson(@Res() res: Response): Promise<void> {
+    this.sendJson(res, await this.sourcesService.getRoutes());
+  }
+
+  /**
+   * Server-rendered email preview, delivered as sandboxed HTML for an <iframe>. A dedicated,
+   * stricter CSP (no scripts) applies to the rendered template markup.
+   */
+  @Get('emails/preview')
+  async emailPreview(
+    @Query('template') template: string | undefined,
+    @Query('locale') locale: string | undefined,
+    @Res() res: Response,
+  ): Promise<void> {
+    const result = await this.emailService.renderPreview(template || '', locale);
+    res.set({
+      'Cache-Control': 'no-store',
+      'Content-Security-Policy': "default-src 'none'; img-src * data:; style-src 'unsafe-inline'; font-src data:",
+      'X-Content-Type-Options': 'nosniff',
+      'X-Frame-Options': 'SAMEORIGIN',
+    });
+    if ('available' in result && result.available === false) {
+      res
+        .type('html')
+        .send(
+          `<!DOCTYPE html><html><body style="font-family:sans-serif;color:#8b97a8;padding:20px">${escapeHtml(result.hint)}</body></html>`,
+        );
+      return;
+    }
+    // The rendered template is trusted framework/project EJS output; the sandbox CSP blocks scripts.
+    res.type('html').send((result as { html: string }).html);
+  }
+
+  // Public: the shared client runtime carries no secrets, and the public /hub/auth token-paste page
+  // must be able to load it in cookie-less setups.
+  @Get('hub.js')
+  @Roles(RoleEnum.S_EVERYONE)
+  hubJs(@Res() res: Response): void {
+    if (!this.cachedClientScript) {
+      this.cachedClientScript = this.htmlService.buildClientScript();
+    }
+    res.set(buildHubSecurityHeaders(generateNonce(), { cacheable: true }));
+    res.type('application/javascript').send(this.cachedClientScript);
+  }
+
+  /**
+   * Root panel (dashboard). PUBLIC — the shell is only the cockpit chrome (no data), and the client
+   * shows a login form when the ADMIN-gated data sidecars answer 401. This makes the Hub
+   * self-sufficient: an admin can log in directly at the API without the frontend. The panel
+   * structure is already discoverable via the public `hub.js`, so serving the shell adds no exposure;
+   * every `*.json` sidecar and every action stays ADMIN-gated.
+   */
+  @Get()
+  @Roles(RoleEnum.S_EVERYONE)
+  root(@Headers('authorization') authHeader: string | undefined, @Res() res: Response): void {
+    this.sendShell(res, authHeader);
+  }
+
+  /** All other panel routes serve the same (public) shell; the client router picks the active panel. */
+  @Get(HUB_PAGE_PATHS)
+  @Roles(RoleEnum.S_EVERYONE)
+  page(@Headers('authorization') authHeader: string | undefined, @Res() res: Response): void {
+    this.sendShell(res, authHeader);
+  }
+
+  /** Backward-compatible alias for the login/token-paste entry (now handled inline by the shell). */
+  @Get('auth')
+  @Roles(RoleEnum.S_EVERYONE)
+  authPage(@Res() res: Response): void {
+    this.sendShell(res, undefined);
+  }
+
+  /** Buffer fill levels for the diagnostics panel. */
+  protected collectorBuffers(): Record<string, { capacity: number; enabled: boolean; size: number }> {
+    const logs = this.logBuffer.getData();
+    const traces = this.traceBuffer.getData();
+    const queries = this.queryProfiler.getData();
+    return {
+      logs: { capacity: 0, enabled: this.logBuffer.enabled, size: logs.records.length },
+      queries: { capacity: 0, enabled: this.queryProfiler.enabled, size: queries.recent.length },
+      traces: { capacity: 0, enabled: this.traceBuffer.enabled, size: traces.traces.length },
+    };
+  }
+
+  protected sendJson(res: Response, data: unknown): void {
+    res.set(buildHubSecurityHeaders(generateNonce()));
+    res.type('application/json').send(JSON.stringify(data));
+  }
+
+  protected sendShell(res: Response, authHeader?: string): void {
+    const nonce = generateNonce();
+    const html = injectNonce(this.htmlService.buildShell(authHeader), nonce);
+    res.set(buildHubSecurityHeaders(nonce));
+    res.type('html').send(html);
+  }
+}

package/src/core/modules/hub/core-hub.module.spec.ts

@@ -0,0 +1,108 @@
+import { PATH_METADATA } from '@nestjs/common/constants';
+import { describe, expect, it } from 'vitest';
+
+import { CoreHubController } from './core-hub.controller';
+import { CoreHubModule } from './core-hub.module';
+
+const ctx = { env: 'local', version: '1.0.0' };
+
+describe('CoreHubModule.forRoot', () => {
+  it('builds a dynamic module with the hub controller', () => {
+    const mod = CoreHubModule.forRoot({ config: {}, ctx });
+    expect(mod.module).toBe(CoreHubModule);
+    expect(mod.controllers?.length).toBeGreaterThan(0);
+  });
+
+  it('becomes global and provides the email-capture binding when the mailbox is enabled', () => {
+    const mod = CoreHubModule.forRoot({ config: { mailbox: { mode: 'capture' } }, ctx });
+    expect(mod.global).toBe(true);
+  });
+
+  it('is not global when the mailbox is disabled', () => {
+    const mod = CoreHubModule.forRoot({ config: {}, ctx });
+    expect(mod.global).toBeFalsy();
+  });
+
+  it('throws when mailbox capture mode is used in production (silent mail suppression guard)', () => {
+    expect(() =>
+      CoreHubModule.forRoot({ config: { mailbox: { mode: 'capture' } }, ctx: { env: 'production', version: '1' } }),
+    ).toThrow(/capture.*not permitted/i);
+  });
+
+  it('allows mailbox copy mode in production', () => {
+    expect(() =>
+      CoreHubModule.forRoot({ config: { mailbox: { mode: 'copy' } }, ctx: { env: 'production', version: '1' } }),
+    ).not.toThrow();
+  });
+
+  describe('public-access guard (roles: false in a reachable env)', () => {
+    it('throws when roles:false in production without acknowledgment', () => {
+      expect(() =>
+        CoreHubModule.forRoot({ config: { roles: false }, ctx: { env: 'production', version: '1' } }),
+      ).toThrow(/roles: false.*not permitted/i);
+    });
+
+    it('throws when roles:false in staging without acknowledgment', () => {
+      expect(() => CoreHubModule.forRoot({ config: { roles: false }, ctx: { env: 'staging', version: '1' } })).toThrow(
+        /not permitted/i,
+      );
+    });
+
+    it('throws for CUSTOM reachable env names too (fail-safe — not just production/staging)', () => {
+      // Regression guard for the exact-string bypass: prod / live / preprod / production-eu / staging-2
+      // must all be treated as reachable.
+      for (const env of ['prod', 'live', 'preprod', 'production-eu', 'staging-2']) {
+        expect(() => CoreHubModule.forRoot({ config: { roles: false }, ctx: { env, version: '1' } })).toThrow(
+          /not permitted/i,
+        );
+      }
+    });
+
+    it('allows roles:false in production ONLY with explicit allowPublicAccessInProduction', () => {
+      expect(() =>
+        CoreHubModule.forRoot({
+          config: { allowPublicAccessInProduction: true, roles: false },
+          ctx: { env: 'production', version: '1' },
+        }),
+      ).not.toThrow();
+    });
+
+    it('allows roles:false in non-reachable envs (local, development)', () => {
+      expect(() => CoreHubModule.forRoot({ config: { roles: false }, ctx })).not.toThrow(); // ctx = local
+      expect(() =>
+        CoreHubModule.forRoot({ config: { roles: false }, ctx: { env: 'development', version: '1' } }),
+      ).not.toThrow();
+    });
+
+    it('allows the default ADMIN gate in production (no roles set)', () => {
+      expect(() => CoreHubModule.forRoot({ config: {}, ctx: { env: 'production', version: '1' } })).not.toThrow();
+    });
+  });
+
+  describe('runtime path/roles metadata (shared controller class)', () => {
+    it('writes the configured base path onto the controller class', () => {
+      CoreHubModule.forRoot({ config: { path: 'cockpit' }, ctx });
+      expect(Reflect.getMetadata(PATH_METADATA, CoreHubController)).toBe('cockpit');
+    });
+
+    it('fully overwrites stale metadata on a second forRoot (no cross-instance pollution)', () => {
+      // The controller class is shared across app instances in the same process (parallel tests). A
+      // second forRoot must overwrite the first, never leak the previous path/roles.
+      CoreHubModule.forRoot({ config: { path: 'first', roles: 'admin' }, ctx });
+      expect(Reflect.getMetadata(PATH_METADATA, CoreHubController)).toBe('first');
+      expect(Reflect.getMetadata('roles', CoreHubController)).toEqual(['admin']);
+
+      CoreHubModule.forRoot({ config: { path: 'second', roles: ['ops', 'admin'] }, ctx });
+      expect(Reflect.getMetadata(PATH_METADATA, CoreHubController)).toBe('second');
+      expect(Reflect.getMetadata('roles', CoreHubController)).toEqual(['ops', 'admin']);
+    });
+
+    it('clears the roles metadata when roles: false (public opt-out)', () => {
+      CoreHubModule.forRoot({ config: { roles: 'admin' }, ctx });
+      expect(Reflect.getMetadata('roles', CoreHubController)).toEqual(['admin']);
+
+      CoreHubModule.forRoot({ config: { roles: false }, ctx });
+      expect(Reflect.getMetadata('roles', CoreHubController)).toBeUndefined();
+    });
+  });
+});