@lenne.tech/nest-server 11.31.2 → 11.31.3

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

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

@@ -0,0 +1,159 @@
+import { DynamicModule, MiddlewareConsumer, Module, NestModule, Provider, Type } from '@nestjs/common';
+import { PATH_METADATA } from '@nestjs/common/constants';
+
+import { CoreHubActionsController } from './core-hub-actions.controller';
+import { CoreHubHtmlService } from './core-hub-html.service';
+import { CoreHubController } from './core-hub.controller';
+import { CoreHubService } from './core-hub.service';
+import { HUB_CONFIG, HUB_EMAIL_CAPTURE } from './hub.constants';
+import { HubConfigContext, isReachableEnv, normalizeHubConfig } from './hub-config.helper';
+import { HubTraceMiddleware } from './middleware/hub-trace.middleware';
+import { CoreHubActionsService } from './services/core-hub-actions.service';
+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 { IHubConfig } from './interfaces/hub-config.interface';
+
+/** Options passed by `CoreModule.forRoot()` when it registers the Hub. */
+export interface CoreHubModuleOptions {
+  /** Override the actions controller (must extend `CoreHubActionsController`). */
+  actionsController?: Type<any>;
+  /** Override the actions service (must extend `CoreHubActionsService`). */
+  actionsService?: Type<any>;
+  /** Raw hub config from `IServerOptions.hub`. */
+  config: boolean | IHubConfig;
+  /** Override the page/sidecar controller (must extend `CoreHubController`). */
+  controller?: Type<any>;
+  /** Environment-derived defaults (env name, version, GraphQL/permissions link resolution). */
+  ctx: HubConfigContext;
+  /** Override the HTML shell service (must extend `CoreHubHtmlService`). */
+  htmlService?: Type<any>;
+  /** Override the aggregator service (must extend `CoreHubService`). */
+  service?: Type<any>;
+}
+
+/**
+ * The Hub admin area (operator cockpit).
+ *
+ * Registered by `CoreModule.forRoot()` when `IServerOptions.hub` is enabled. The controller path and
+ * required roles are assigned to the controller class at runtime (via `Reflect.defineMetadata`)
+ * because they come from configuration — the same pattern the permissions module uses.
+ */
+@Module({})
+export class CoreHubModule implements NestModule {
+  // Write-once-per-forRoot (same accepted pattern as CoreModule.graphQlEnabled). Read by configure()
+  // to decide whether to bind the trace middleware. The last forRoot wins in multi-app processes.
+  private static traceEnabled = false;
+
+  configure(consumer: MiddlewareConsumer): void {
+    if (CoreHubModule.traceEnabled) {
+      // Bind before RequestContextMiddleware so timing starts early; the trace path never reads
+      // RequestContext (it uses req.user directly), so ordering is a non-issue.
+      consumer.apply(HubTraceMiddleware).forRoutes('*');
+    }
+  }
+
+  static forRoot(options: CoreHubModuleOptions): DynamicModule {
+    const resolved = normalizeHubConfig(options.config, options.ctx);
+    CoreHubModule.traceEnabled = resolved.collectors.traces !== false;
+
+    // Guard: capture mode silently suppresses outgoing mail — forbid it in production/staging so a
+    // misconfiguration cannot make password-reset, 2FA and verification mail vanish (mirrors the
+    // JSONTransport guard in EmailService).
+    if (resolved.mailbox !== false && resolved.mailbox.mode === 'capture' && isReachableEnv(resolved.env)) {
+      throw new Error(
+        `Hub mailbox mode 'capture' is not permitted in a reachable environment (${resolved.env}): it ` +
+          "suppresses all outgoing mail. Use mode 'copy' (send + record) or disable the mailbox.",
+      );
+    }
+
+    // Guard: a PUBLIC Hub (roles: false → no auth check whatsoever) in a reachable environment exposes
+    // the config viewer, logs and DESTRUCTIVE admin actions (migrations, file delete, cron control) to
+    // ANY unauthenticated request. Forbid it in production/staging unless the operator has EXPLICITLY
+    // acknowledged it via `allowPublicAccessInProduction` (only sane behind a fully-controlled network
+    // boundary). This mirrors the mailbox-capture guard above and closes the single most dangerous
+    // Hub misconfiguration (e.g. a `roles: false` copied from a local config).
+    if (resolved.roles === false && isReachableEnv(resolved.env) && !resolved.allowPublicAccessInProduction) {
+      throw new Error(
+        `Hub 'roles: false' (no auth check) is not permitted in a reachable environment (${resolved.env}): ` +
+          'it exposes the config viewer, logs and destructive admin actions to unauthenticated requests. ' +
+          'Keep the default ADMIN gate (omit `roles`), or — ONLY behind a fully-controlled network ' +
+          'boundary — set hub.allowPublicAccessInProduction: true to acknowledge the risk.',
+      );
+    }
+
+    const ControllerClass = options.controller || CoreHubController;
+    const ActionsControllerClass = options.actionsController || CoreHubActionsController;
+
+    // Runtime path + roles metadata (see permissions module), applied to BOTH controllers. Written
+    // UNCONDITIONALLY so a second forRoot on the same class fully overrides the first — otherwise
+    // stale metadata leaks across app instances that share the class (a real hazard in multi-app
+    // tests). `roles: false` clears the metadata, which the guards read as "public" — a deliberate,
+    // dangerous opt-out (documented in IHubConfig.roles).
+    for (const Ctrl of resolved.actions ? [ControllerClass, ActionsControllerClass] : [ControllerClass]) {
+      Reflect.defineMetadata(PATH_METADATA, resolved.path, Ctrl);
+      if (resolved.roles === false) {
+        Reflect.deleteMetadata('roles', Ctrl);
+      } else {
+        Reflect.defineMetadata('roles', resolved.roles, Ctrl);
+      }
+    }
+
+    const providers: Provider[] = [
+      { provide: HUB_CONFIG, useValue: resolved },
+      { provide: CoreHubService, useClass: options.service || CoreHubService },
+      { provide: CoreHubHtmlService, useClass: options.htmlService || CoreHubHtmlService },
+      CoreHubDbService,
+      CoreHubEmailService,
+      CoreHubMigrationsService,
+      CoreHubSourcesService,
+      // Collectors are always provided; each is inert when its own config slice is disabled, so the
+      // sidecar can answer `{ enabled: false }` rather than 404.
+      HubLogBufferService,
+      HubQueryProfilerService,
+      HubTraceBufferService,
+      HubTraceMiddleware,
+    ];
+
+    // Actions controller/service only when actions are enabled (disabling removes the routes → 404).
+    const controllers: Type<any>[] = [ControllerClass];
+    if (resolved.actions) {
+      controllers.push(ActionsControllerClass);
+      providers.push({ provide: CoreHubActionsService, useClass: options.actionsService || CoreHubActionsService });
+    }
+
+    // When the mailbox is enabled, provide it AND bind it to the EMAIL_CAPTURE token so EmailService
+    // (which injects the token optionally) starts capturing. The module must be global for the token
+    // to reach EmailService, which lives in a different module.
+    const global = resolved.mailbox !== false;
+    if (global) {
+      providers.push(CoreHubMailboxService);
+      providers.push({ provide: HUB_EMAIL_CAPTURE, useExisting: CoreHubMailboxService });
+    }
+
+    return {
+      controllers,
+      exports: [
+        CoreHubService,
+        CoreHubHtmlService,
+        CoreHubDbService,
+        CoreHubEmailService,
+        CoreHubMigrationsService,
+        CoreHubSourcesService,
+        HubLogBufferService,
+        HubQueryProfilerService,
+        HubTraceBufferService,
+        HUB_CONFIG,
+        ...(global ? [CoreHubMailboxService, HUB_EMAIL_CAPTURE] : []),
+      ],
+      global,
+      module: CoreHubModule,
+      providers,
+    };
+  }
+}