@lenne.tech/nest-server 11.31.2 → 11.32.0

package/src/core/common/interfaces/server-options.interface.ts

@@ -18,6 +18,7 @@ import * as SMTPTransport from 'nodemailer/lib/smtp-transport';
 import type * as StreamTransport from 'nodemailer/lib/stream-transport';
 
 import { Falsy } from '../types/falsy.type';
+import { IHubConfig } from '../../modules/hub/interfaces/hub-config.interface';
 import { IPermissions } from '../../modules/permissions/interfaces/permissions.interface';
 import { CronJobConfigWithTimeZone } from './cron-job-config-with-time-zone.interface';
 import { CronJobConfigWithUtcOffset } from './cron-job-config-with-utc-offset.interface';
@@ -1519,6 +1520,19 @@ export interface IServerOptions {
      */
     exclude?: RegExp;
 
+    /**
+     * How often the SDK retries a failed send (408 / 429 / 5xx).
+     *
+     * The Brevo SDK defaults to 2 retries and honours `Retry-After` with a cap of 60 SECONDS per
+     * attempt. `BrevoService.sendMail()` is awaited inside request handlers (e.g. the BetterAuth
+     * email-verification hook), so a rate-limited Brevo can otherwise park a user-facing HTTP
+     * request for roughly two minutes. The framework default of `0` keeps the request fast and
+     * leaves retrying to the caller.
+     *
+     * @default 0
+     */
+    maxRetries?: number;
+
     /**
      * Default sender for Brevo
      */
@@ -1526,6 +1540,25 @@ export interface IServerOptions {
       email: string;
       name: string;
     };
+
+    /**
+     * Whether a failed send should throw instead of resolving to `null`.
+     *
+     * `false` (default) preserves the historical contract: errors are logged and the method
+     * resolves to `null`. Set `true` when the caller must not proceed on a silent failure — the
+     * framework's own email-verification path checks the `null` either way.
+     *
+     * @default false
+     */
+    throwOnError?: boolean;
+
+    /**
+     * Per-request timeout in seconds. Unset means no timeout — a hung connection is then bounded
+     * only by the HTTP agent's own (300 s) limits, multiplied by `maxRetries`.
+     *
+     * @default 10
+     */
+    timeoutInSeconds?: number;
   };
 
   /**
@@ -1847,6 +1880,24 @@ export interface IServerOptions {
    */
   hostname?: string;
 
+  /**
+   * Hub admin area (operator cockpit).
+   *
+   * A build-free, ADMIN-gated dashboard of runtime information and admin tools (dashboard,
+   * diagnostics, logs, request traces, query profiler, migrations, DB stats, models/ERD, files,
+   * cron jobs, error codes, masked config, auth-migration progress, email preview, built-in mailbox,
+   * AI panel).
+   *
+   * Follows "presence implies enabled" — but is NEVER enabled implicitly. It must be switched on per
+   * environment (here or via `NSC__HUB__*`); no environment inherits it.
+   * - `true` / `{}`: enabled at `/hub`, admin-only, default collectors (logs + traces on, queries off)
+   * - `{ path: 'admin/hub', collectors: { queries: true } }`: custom path + query profiling
+   * - `{ enabled: false }` / `undefined`: disabled — every Hub route answers 404
+   *
+   * @default undefined (disabled)
+   */
+  hub?: boolean | IHubConfig;
+
   /**
    * Ignore selections in fieldSelection
    * [ConfigService must be integrated in ModuleService]
@@ -3312,4 +3363,31 @@ export interface ICoreModuleOverrides {
     controller?: Type<any>;
     service?: Type<any>;
   };
+
+  /**
+   * Override Hub controllers and/or services with project-specific subclasses.
+   *
+   * - `actionsController` must extend `CoreHubActionsController`
+   * - `actionsService` must extend `CoreHubActionsService`
+   * - `controller` must extend `CoreHubController`
+   * - `htmlService` must extend `CoreHubHtmlService`
+   * - `service` must extend `CoreHubService`
+   *
+   * @example
+   * ```typescript
+   * {
+   *   hub: {
+   *     service: MyHubService,
+   *     htmlService: MyHubHtmlService,
+   *   },
+   * }
+   * ```
+   */
+  hub?: {
+    actionsController?: Type<any>;
+    actionsService?: Type<any>;
+    controller?: Type<any>;
+    htmlService?: Type<any>;
+    service?: Type<any>;
+  };
 }

package/src/core/common/services/brevo.service.spec.ts

@@ -0,0 +1,266 @@
+import { Logger } from '@nestjs/common';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { Brevo, BrevoClient as RealBrevoClient } from '@getbrevo/brevo';
+
+import { BrevoService } from './brevo.service';
+import type { ConfigService } from './config.service';
+
+/**
+ * Type-level contract against the REAL SDK.
+ *
+ * Everything below runs against a hand-written mock, so the mock alone could keep passing after a
+ * breaking SDK upgrade. `sendMail()` is declared `Promise<unknown>`, which gives tsc nothing to
+ * check either. These assertions close that gap: they compile against the installed
+ * `@getbrevo/brevo`, and `pnpm run typecheck:tests` covers `src/**\/*.spec.ts`, so a v7 that
+ * re-introduces a `.body` envelope or renames the request type fails the build here rather than
+ * silently at runtime.
+ */
+type SendFn = RealBrevoClient['transactionalEmails']['sendTransacEmail'];
+/** Awaiting the call must yield the payload itself — v3's `{ response, body }` envelope is gone. */
+type AssertNoEnvelope = Awaited<ReturnType<SendFn>> extends { body: unknown } ? never : true;
+/** The request type the service builds must still be assignable to the SDK's parameter. */
+type AssertRequestType = Brevo.SendTransacEmailRequest extends NonNullable<Parameters<SendFn>[0]> ? true : never;
+// Consumed by an assertion below so the contract cannot be dead-code-eliminated or linted away.
+const sdkContract: [AssertNoEnvelope, AssertRequestType] = [true, true];
+
+/**
+ * Shared handles into the mocked SDK. `vi.hoisted` runs before the `vi.mock` factory below, so the
+ * spies exist by the time the module graph is wired up.
+ */
+const brevoMock = vi.hoisted(() => ({
+  /** Every options object the client was constructed with, in call order. */
+  clientOptions: [] as unknown[],
+  sendTransacEmail: vi.fn(),
+}));
+
+vi.mock('@getbrevo/brevo', () => ({
+  BrevoClient: class {
+    transactionalEmails = { sendTransacEmail: brevoMock.sendTransacEmail };
+
+    constructor(options: unknown) {
+      brevoMock.clientOptions.push(options);
+    }
+  },
+}));
+
+const API_KEY = 'test-api-key';
+const SENDER = { email: 'noreply@test.com', name: 'Test Sender' };
+
+/** Matches the per-send `Idempotency-Key` header without pinning the random UUID. */
+const anyIdempotencyHeaders = { 'Idempotency-Key': expect.any(String) as unknown as string };
+
+/**
+ * Minimal ConfigService double.
+ *
+ * `exclude` can be set independently on the mutable (`config`) and the frozen
+ * (`configFastButReadOnly`) side so the tests can prove which one the service reads.
+ */
+function makeConfigService(
+  options: {
+    exclude?: RegExp;
+    frozenExclude?: RegExp;
+    maxRetries?: number;
+    throwOnError?: boolean;
+    timeoutInSeconds?: number;
+    withBrevo?: boolean;
+  } = {},
+): ConfigService {
+  const { exclude, frozenExclude = exclude, maxRetries, throwOnError, timeoutInSeconds, withBrevo = true } = options;
+  const base = { apiKey: API_KEY, maxRetries, sender: SENDER, throwOnError, timeoutInSeconds };
+  return {
+    config: withBrevo ? { brevo: { ...base, exclude } } : {},
+    configFastButReadOnly: withBrevo ? { brevo: { ...base, exclude: frozenExclude } } : {},
+  } as unknown as ConfigService;
+}
+
+describe('@getbrevo/brevo SDK contract', () => {
+  it('still resolves the payload directly and accepts the request type we build', () => {
+    // The assertion is the COMPILATION of `sdkContract` above, which `pnpm run typecheck:tests`
+    // performs against the really installed SDK. This test body exists so the contract is also
+    // referenced at runtime — otherwise it reads as dead code and invites deletion.
+    expect(sdkContract).toEqual([true, true]);
+  });
+});
+
+describe('BrevoService', () => {
+  let loggerError: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    brevoMock.sendTransacEmail.mockReset();
+    brevoMock.clientOptions.length = 0;
+    loggerError = vi.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    // The spies above are never restored otherwise. File-level isolation contains it today, but a
+    // leaked Logger spy is the kind of thing that only surfaces as an unrelated flake later.
+    vi.restoreAllMocks();
+  });
+
+  describe('constructor', () => {
+    it('throws when the Brevo configuration is missing', () => {
+      expect(() => new BrevoService(makeConfigService({ withBrevo: false }))).toThrow('Brevo configuration not set!');
+    });
+
+    it('does NOT construct the SDK client eagerly', async () => {
+      // The SDK is ~580 CommonJS modules and BrevoService is re-exported from the package barrel,
+      // so a static import would put that cost on every consumer's cold start — including the
+      // majority that never configure Brevo.
+      const service = new BrevoService(makeConfigService());
+      expect(brevoMock.clientOptions).toEqual([]);
+
+      brevoMock.sendTransacEmail.mockResolvedValue({ messageId: '<x@brevo>' });
+      await service.sendMail('user@example.com', 42);
+      expect(brevoMock.clientOptions).toHaveLength(1);
+    });
+
+    it('creates the client with the configured API key and safe request limits', async () => {
+      brevoMock.sendTransacEmail.mockResolvedValue({ messageId: '<x@brevo>' });
+      const service = new BrevoService(makeConfigService());
+      await service.sendMail('user@example.com', 42);
+
+      // The SDK defaults to 2 retries honouring `Retry-After` with a 60 s cap PER attempt and to
+      // no timeout at all. Both send methods are awaited inside request handlers, so those
+      // defaults would let a rate-limited Brevo park a user-facing request for ~2 minutes.
+      expect(brevoMock.clientOptions).toEqual([{ apiKey: API_KEY, maxRetries: 0, timeoutInSeconds: 10 }]);
+    });
+
+    it('honours configured retry and timeout overrides', async () => {
+      brevoMock.sendTransacEmail.mockResolvedValue({ messageId: '<x@brevo>' });
+      const service = new BrevoService(makeConfigService({ maxRetries: 3, timeoutInSeconds: 30 }));
+      await service.sendMail('user@example.com', 42);
+      expect(brevoMock.clientOptions).toEqual([{ apiKey: API_KEY, maxRetries: 3, timeoutInSeconds: 30 }]);
+    });
+
+    it('reuses the client across sends', async () => {
+      brevoMock.sendTransacEmail.mockResolvedValue({ messageId: '<x@brevo>' });
+      const service = new BrevoService(makeConfigService());
+      await service.sendMail('user@example.com', 42);
+      await service.sendMail('other@example.com', 42);
+      expect(brevoMock.clientOptions).toHaveLength(1);
+    });
+  });
+
+  describe('sendMail', () => {
+    it('rejects incomplete input without calling the API', async () => {
+      const service = new BrevoService(makeConfigService());
+      await expect(service.sendMail('', 42)).resolves.toBe(false);
+      await expect(service.sendMail('user@example.com', 0)).resolves.toBe(false);
+      expect(brevoMock.sendTransacEmail).not.toHaveBeenCalled();
+    });
+
+    it('sends template, recipient and params, and returns the response unwrapped', async () => {
+      const response = { messageId: '<mail-1@brevo>' };
+      brevoMock.sendTransacEmail.mockResolvedValue(response);
+      const service = new BrevoService(makeConfigService());
+
+      // Identity check: v6 resolves the payload directly, there is no `.body` envelope any more
+      await expect(service.sendMail('user@example.com', 42, { name: 'Test' })).resolves.toBe(response);
+      expect(brevoMock.sendTransacEmail).toHaveBeenCalledWith({
+        headers: anyIdempotencyHeaders,
+        params: { name: 'Test' },
+        templateId: 42,
+        to: [{ email: 'user@example.com' }],
+      });
+    });
+
+    it('sends a unique Idempotency-Key per call', async () => {
+      // The SDK retries POSTs on 408/429/5xx. Without a key, a retry issued after a delivered
+      // response whose reply was lost sends the mail twice.
+      brevoMock.sendTransacEmail.mockResolvedValue({ messageId: '<x@brevo>' });
+      const service = new BrevoService(makeConfigService());
+      await service.sendMail('user@example.com', 42);
+      await service.sendMail('user@example.com', 42);
+
+      const keys = brevoMock.sendTransacEmail.mock.calls.map(
+        ([request]) => (request as Brevo.SendTransacEmailRequest).headers?.['Idempotency-Key'],
+      );
+      expect(keys[0]).toBeTypeOf('string');
+      expect(keys[0]).not.toBe(keys[1]);
+    });
+
+    it('skips excluded (test) recipients', async () => {
+      const service = new BrevoService(makeConfigService({ exclude: /@test\.com$/i }));
+      await expect(service.sendMail('user@test.com', 42)).resolves.toBe('TEST_USER!');
+      expect(brevoMock.sendTransacEmail).not.toHaveBeenCalled();
+    });
+
+    it('reads the exclude pattern from the mutable config, not the frozen one', async () => {
+      // A frozen RegExp carrying the `g` flag throws on `.test()` (it assigns `lastIndex`).
+      // Reading `exclude` off `configFastButReadOnly` would therefore fail instead of excluding.
+      const service = new BrevoService(
+        makeConfigService({ exclude: /@test\.com$/i, frozenExclude: Object.freeze(/@test\.com$/gi) }),
+      );
+      await expect(service.sendMail('user@test.com', 42)).resolves.toBe('TEST_USER!');
+    });
+
+    it('returns null when the API call fails', async () => {
+      brevoMock.sendTransacEmail.mockRejectedValue(new Error('Brevo down'));
+      const service = new BrevoService(makeConfigService());
+      await expect(service.sendMail('user@example.com', 42)).resolves.toBeNull();
+    });
+
+    it('logs the failure through the Nest logger', async () => {
+      // The whole point of the sibling diagnostics work is that silent failures cost debugging
+      // sessions. Asserting only the `null` return would let the observability half regress.
+      brevoMock.sendTransacEmail.mockRejectedValue(new Error('Brevo down'));
+      const service = new BrevoService(makeConfigService());
+      await service.sendMail('user@example.com', 42);
+      expect(loggerError).toHaveBeenCalledWith(expect.stringContaining('Brevo down'));
+    });
+
+    it('rethrows when throwOnError is enabled', async () => {
+      const service = new BrevoService(makeConfigService({ throwOnError: true }));
+      brevoMock.sendTransacEmail.mockRejectedValue(new Error('Brevo down'));
+      await expect(service.sendMail('user@example.com', 42)).rejects.toThrow('Brevo down');
+    });
+  });
+
+  describe('sendHtmlMail', () => {
+    it('rejects incomplete input without calling the API', async () => {
+      const service = new BrevoService(makeConfigService());
+      await expect(service.sendHtmlMail('', 'Subject', '<p>Hi</p>')).resolves.toBe(false);
+      await expect(service.sendHtmlMail('user@example.com', '', '<p>Hi</p>')).resolves.toBe(false);
+      await expect(service.sendHtmlMail('user@example.com', 'Subject', '')).resolves.toBe(false);
+      expect(brevoMock.sendTransacEmail).not.toHaveBeenCalled();
+    });
+
+    it('sends html, subject and the configured sender, and returns the response unwrapped', async () => {
+      const response = { messageId: '<mail-2@brevo>' };
+      brevoMock.sendTransacEmail.mockResolvedValue(response);
+      const service = new BrevoService(makeConfigService());
+
+      await expect(
+        service.sendHtmlMail('user@example.com', 'Subject', '<p>Hi</p>', { params: { code: '123' } }),
+      ).resolves.toBe(response);
+      expect(brevoMock.sendTransacEmail).toHaveBeenCalledWith({
+        headers: anyIdempotencyHeaders,
+        htmlContent: '<p>Hi</p>',
+        params: { code: '123' },
+        sender: SENDER,
+        subject: 'Subject',
+        to: [{ email: 'user@example.com' }],
+      });
+    });
+
+    it('skips excluded (test) recipients', async () => {
+      const service = new BrevoService(makeConfigService({ exclude: /@test\.com$/i }));
+      await expect(service.sendHtmlMail('user@test.com', 'Subject', '<p>Hi</p>')).resolves.toBe('TEST_USER!');
+      expect(brevoMock.sendTransacEmail).not.toHaveBeenCalled();
+    });
+
+    it('returns null when the API call fails', async () => {
+      brevoMock.sendTransacEmail.mockRejectedValue(new Error('Brevo down'));
+      const service = new BrevoService(makeConfigService());
+      await expect(service.sendHtmlMail('user@example.com', 'Subject', '<p>Hi</p>')).resolves.toBeNull();
+    });
+
+    it('logs the failure through the Nest logger', async () => {
+      brevoMock.sendTransacEmail.mockRejectedValue(new Error('Brevo down'));
+      const service = new BrevoService(makeConfigService());
+      await service.sendHtmlMail('user@example.com', 'Subject', '<p>Hi</p>');
+      expect(loggerError).toHaveBeenCalledWith(expect.stringContaining('Brevo down'));
+    });
+  });
+});

package/src/core/common/services/brevo.service.ts

@@ -1,27 +1,50 @@
-import { SendSmtpEmail, TransactionalEmailsApi, TransactionalEmailsApiApiKeys } from '@getbrevo/brevo';
-import { Injectable } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+
+import type { Brevo, BrevoClient } from '@getbrevo/brevo';
 
 import { ConfigService } from './config.service';
 
 /**
  * Brevo service to send transactional emails
+ *
+ * ## Return contract
+ *
+ * Both send methods resolve to one of four things, and callers on security-critical paths
+ * (verification, password reset, magic link) MUST distinguish them:
+ *
+ * | Value | Meaning |
+ * |-------|---------|
+ * | `false` | Rejected before sending — a required argument was missing |
+ * | `'TEST_USER!'` | Recipient matched `brevo.exclude`, nothing was sent (by design) |
+ * | `null` | The send FAILED. The error was logged, not thrown |
+ * | otherwise | The Brevo `SendTransacEmailResponse` (`{ messageId?, messageIds? }`) |
+ *
+ * A `null` is the one that bites: treating "did not throw" as "was delivered" silently drops mail.
+ * Set `brevo.throwOnError: true` if you would rather have the exception propagate.
  */
 @Injectable()
 export class BrevoService {
   brevoConfig: ConfigService['configFastButReadOnly']['brevo'];
-  private apiInstance: TransactionalEmailsApi;
+  protected readonly logger = new Logger(BrevoService.name);
+  private client: BrevoClient | undefined;
 
   constructor(protected configService: ConfigService) {
     this.brevoConfig = configService.configFastButReadOnly.brevo;
     if (!this.brevoConfig) {
       throw new Error('Brevo configuration not set!');
     }
-    this.apiInstance = new TransactionalEmailsApi();
-    this.apiInstance.setApiKey(TransactionalEmailsApiApiKeys.apiKey, this.brevoConfig.apiKey);
   }
 
   /**
    * Send a transactional email via Brevo
+   *
+   * @param to - Recipient email address
+   * @param templateId - Brevo template id
+   * @param params - Template parameters. These are rendered SERVER-SIDE by the Brevo template
+   *   engine, so any user-controlled value placed here is content-injection surface owned by
+   *   whoever wrote the template — escape it there, or do not pass it.
+   * @returns The Brevo response, `false` on missing input, `'TEST_USER!'` when excluded, `null` on failure
    */
   async sendMail(to: string, templateId: number, params?: object): Promise<unknown> {
     try {
@@ -37,25 +60,31 @@ export class BrevoService {
       }
 
       // Prepare data
-      const sendSmtpEmail: SendSmtpEmail = {
-        params,
+      const request: Brevo.SendTransacEmailRequest = {
+        headers: this.buildIdempotencyHeaders(),
+        // The public signature keeps the wider `object` so existing callers stay source-compatible;
+        // the SDK narrowed its own field to an index-signature type in v6.
+        params: params as Record<string, unknown>,
         templateId,
         to: [{ email: to }],
       };
 
       // Send email
-      const result = await this.apiInstance.sendTransacEmail(sendSmtpEmail);
-      return result.body;
+      const client = await this.getClient();
+      return await client.transactionalEmails.sendTransacEmail(request);
     } catch (error) {
-      console.error(error);
+      return this.handleSendError(error, to);
     }
-
-    // Return null if error
-    return null;
   }
 
   /**
    * Send HTML mail
+   *
+   * @param to - Recipient email address
+   * @param subject - Email subject
+   * @param html - HTML body
+   * @param options - Optional template parameters
+   * @returns The Brevo response, `false` on missing input, `'TEST_USER!'` when excluded, `null` on failure
    */
   async sendHtmlMail(
     to: string,
@@ -76,7 +105,8 @@ export class BrevoService {
       }
 
       // Prepare data
-      const sendSmtpEmail: SendSmtpEmail = {
+      const request: Brevo.SendTransacEmailRequest = {
+        headers: this.buildIdempotencyHeaders(),
         htmlContent: html,
         params: options?.params,
         sender: this.brevoConfig.sender,
@@ -85,12 +115,65 @@ export class BrevoService {
       };
 
       // Send email
-      const result = await this.apiInstance.sendTransacEmail(sendSmtpEmail);
-      return result.body;
+      const client = await this.getClient();
+      return await client.transactionalEmails.sendTransacEmail(request);
     } catch (error) {
-      console.error(error);
+      return this.handleSendError(error, to);
     }
+  }
+
+  /**
+   * Builds the per-send idempotency header.
+   *
+   * The SDK retries POSTs on 408/429/5xx. Without a key, a retry issued after a response that was
+   * actually delivered (but whose reply was lost) sends the mail twice. Brevo deduplicates on
+   * `Idempotency-Key`.
+   *
+   * @returns Custom headers for the send request
+   */
+  protected buildIdempotencyHeaders(): Record<string, unknown> {
+    return { 'Idempotency-Key': randomUUID() };
+  }
 
+  /**
+   * Lazily constructs (and memoises) the Brevo SDK client.
+   *
+   * The import is dynamic on purpose: `@getbrevo/brevo` pulls in ~580 CommonJS modules, and
+   * `BrevoService` is re-exported from the package barrel. A static import would put that cost on
+   * every consumer's cold start, including the majority that never configure Brevo at all.
+   *
+   * @returns The memoised SDK client
+   */
+  protected async getClient(): Promise<BrevoClient> {
+    if (!this.client) {
+      const { BrevoClient: BrevoClientCtor } = await import('@getbrevo/brevo');
+      this.client = new BrevoClientCtor({
+        apiKey: this.brevoConfig.apiKey,
+        // The SDK defaults to 2 retries honouring `Retry-After` with a 60 s cap PER attempt, and to
+        // no timeout at all. Both send methods are awaited inside request handlers, so those
+        // defaults let a rate-limited Brevo park a user-facing request for roughly two minutes.
+        maxRetries: this.brevoConfig.maxRetries ?? 0,
+        timeoutInSeconds: this.brevoConfig.timeoutInSeconds ?? 10,
+      });
+    }
+    return this.client;
+  }
+
+  /**
+   * Logs a failed send through the Nest logger and applies the configured failure policy.
+   *
+   * @param error - The thrown SDK error
+   * @param to - Recipient, for correlation
+   * @returns `null` (the historical contract) unless `brevo.throwOnError` is set
+   * @throws The original error when `brevo.throwOnError` is `true`
+   */
+  protected handleSendError(error: unknown, to: string): null {
+    this.logger.error(
+      `Brevo sendTransacEmail failed for ${to}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    if (this.brevoConfig.throwOnError) {
+      throw error;
+    }
     // Return null if error
     return null;
   }

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