@lenne.tech/nest-server 11.31.2 → 11.32.0

package/docs/REQUEST-LIFECYCLE.md

@@ -213,6 +213,8 @@ JWT-based authentication for existing projects:
 | **Health Check Module** | `GET /health` + GraphQL `healthCheck` query |
 | **Error Code Module** | Centralized error registry with unique IDs |
 | **Permissions Report** | Interactive HTML dashboard, JSON, and Markdown reports |
+| **Hub (Operator Cockpit)** | Build-free ADMIN-gated dashboard at `/hub` (config-gated per environment). Adds an optional HTTP trace middleware (registered by `CoreHubModule.configure()` only when traces are enabled), a chaining `Logger.overrideLogger()` delegate for the log buffer, an optional `EmailService` capture hook (`HUB_EMAIL_CAPTURE` token) for the mailbox, and — when the query profiler is enabled — opts the MongoDB driver into `monitorCommands` from `core.module.ts`. See `src/core/modules/hub/README.md`. |
+| **Process Diagnostics** | Opt-in process-level exit diagnostics (`installProcessDiagnostics()` + `handleFatalBootstrapError`, `src/core/common/helpers/process-diagnostics.helper.ts`). Wired into `main.ts` — **NOT** into `CoreModule.forRoot()`, because it must run before `NestFactory.create()` and installs a `process.exit(1)` path that must never arm inside `Test.createTestingModule()`. Logs unhandled rejections without crashing (configurable), uncaught exceptions before the exit, non-zero exit codes, and labels SIGTERM/SIGINT/SIGHUP/SIGQUIT as external terminations. Pair with `server.enableShutdownHooks()` — see the helper docblock |
 | **System Setup Module** | Initial admin creation for fresh deployments |
 | **Cron Jobs** | `CoreCronJobsService` with timezone/UTC offset support |
 | **Model Documentation** | Auto-generated model docs via `ModelDocService` |

package/docs/brevo-manual-test.md

@@ -0,0 +1,166 @@
+# Brevo: manual test against the real API
+
+> **Framework repo only.** This page ships inside the npm package (because `docs/**` is in
+> `package.json` `files`), but the things it tells you to run do **not**: `scripts/` and
+> `.env.example` are excluded from the tarball, and `src/config.env.ts` is a path that only exists
+> in this repository. If you are reading this from
+> `node_modules/@lenne.tech/nest-server/docs/`, clone
+> [lenneTech/nest-server](https://github.com/lenneTech/nest-server) to follow along. For configuring
+> Brevo in *your* project, see the `brevo` block in `FRAMEWORK-API.md` instead.
+
+The unit spec (`src/core/common/services/brevo.service.spec.ts`) covers `BrevoService` against a
+mocked SDK. That proves the logic, not the wire format. This guide is the one-off manual check
+against the **live** Brevo endpoint — worth running once after an SDK upgrade, and any time you
+suspect a credential or sender problem.
+
+> Every send here costs one transactional email from your Brevo quota and really lands in a mailbox.
+
+## 1. Get the credentials
+
+| What                | Where to get it                                                                                          |
+| ------------------- | -------------------------------------------------------------------------------------------------------- |
+| **API key**         | <https://app.brevo.com/settings/keys/api> → *Generate a new API key*. Starts with `xkeysib-`.              |
+| **Verified sender** | <https://app.brevo.com/senders/list> → *Add a sender*, then confirm the mail Brevo sends to that address.  |
+| **Template ID**     | *(optional)* <https://app.brevo.com/templates/listing> → open a template, the numeric ID is in the URL.    |
+
+Two pitfalls, both of which produce a confusing failure:
+
+- **Use the API v3 key, not the SMTP key.** Brevo issues two kinds of credential on neighbouring
+  settings pages. The REST API — which `BrevoService` talks to — only accepts a key starting with
+  **`xkeysib-`**. A key starting with `xsmtpsib-` is the SMTP password for `smtp-relay.brevo.com`
+  and is rejected by every `api.brevo.com/v3/*` endpoint with `401 {"message":"Key not found"}`.
+- **The sender address must be verified in Brevo.** An unverified sender is the most common cause
+  of a send that fails with HTTP 400 despite a valid key.
+
+To check a key in isolation before spending a send, hit an endpoint that takes no payload:
+
+```bash
+curl -s -w '\nHTTP %{http_code}\n' -H "api-key: $BREVO_API_KEY" https://api.brevo.com/v3/account
+```
+
+`HTTP 200` plus your account JSON means the key is good; `401 "Key not found"` means it is the
+wrong kind of key or belongs to a deleted account.
+
+## 2. Put them in `.env`
+
+`src/config.env.ts` calls `dotenv.config()` at import time, so a `.env` in the repo root is picked
+up by both the server and the smoke script. There is no `.env` in the repo — create one from the
+template:
+
+```bash
+cp .env.example .env
+```
+
+Then set these four keys in `.env`. `EMAIL_DEFAULT_SENDER` is already an **active** line in the
+template; `EMAIL_DEFAULT_SENDER_NAME`, `BREVO_API_KEY`, `BREVO_SMOKE_TO` and
+`BREVO_SMOKE_TEMPLATE_ID` are there as comments — uncomment and fill them in:
+
+```dotenv
+# API key from app.brevo.com/settings/keys/api
+BREVO_API_KEY=xkeysib-your-real-key
+
+# Sender - must be a VERIFIED sender in Brevo
+EMAIL_DEFAULT_SENDER=noreply@your-verified-domain.tld
+EMAIL_DEFAULT_SENDER_NAME=Nest Server Manual Test
+
+# Recipient for the smoke script - a mailbox you can actually open
+BREVO_SMOKE_TO=you@your-mailbox.tld
+
+# Optional: only needed for the template send in step 3b
+# BREVO_SMOKE_TEMPLATE_ID=12
+```
+
+`.env` is git-ignored — never commit real keys.
+
+Config-wise this is all that is needed: `config.env.ts` only builds the `brevo` block **when
+`BREVO_API_KEY` is set** (`...(process.env.BREVO_API_KEY ? { brevo: {...} } : {})`). Without the
+key there is no `brevo` config, `BrevoService` refuses to construct, and everything falls back to
+SMTP.
+
+## 3. Run the smoke script
+
+```bash
+pnpm exec tsx scripts/brevo-smoke.ts
+```
+
+It builds a real `ConfigService` + `BrevoService` (no mocks, no Nest bootstrap) and sends through
+the same code path the server uses.
+
+### 3a. What you should see
+
+```
+[brevo-smoke] sender:    Nest Server Manual Test <noreply@your-verified-domain.tld>
+[brevo-smoke] recipient: you@your-mailbox.tld
+[brevo-smoke] sending HTML mail via sendHtmlMail() ...
+[brevo-smoke] sendHtmlMail result: { messageId: '<2026...@smtp-relay.mailin.fr>' }
+[brevo-smoke] OK - check the recipient mailbox and https://app.brevo.com/transactional/email/logs.
+```
+
+A `messageId` means Brevo accepted the mail. Confirm it twice:
+
+1. The mail arrives in the recipient mailbox (check spam on the first run).
+2. It shows up under **Transactional → Logs**: <https://app.brevo.com/transactional/email/logs>.
+
+### 3b. Also test a template (optional)
+
+Templates are what `sendMail()` uses in production (e.g. BetterAuth email verification via
+`betterAuth.emailVerification.brevoTemplateId`). Set `BREVO_SMOKE_TEMPLATE_ID` in `.env` and re-run
+— the script then additionally calls `sendMail(to, templateId, { smokeTestStamp })`. Put
+`{{ params.smokeTestStamp }}` somewhere in the template body to see the parameter substitution
+land.
+
+Note: template parameters only substitute when the template uses Brevo's **New Template Language**.
+Old-language templates silently ignore `params`.
+
+### 3c. Reading a failure
+
+`BrevoService` catches SDK errors, logs them and returns `null` — so the script prints the full
+error object above a `result: null`. The status code tells you which knob is wrong:
+
+| Status                       | Cause                                                                        |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| **401 Unauthorized**         | `BREVO_API_KEY` wrong, revoked, or from a different Brevo account.            |
+| **400 Bad Request**          | Usually an unverified sender, or an invalid/foreign `templateId`.            |
+| **402 Payment Required**     | Free-plan daily quota exhausted.                                              |
+| **`result: 'TEST_USER!'`**   | The recipient matched `config.brevo.exclude` — nothing was sent (see step 5). |
+
+A quick way to confirm the wiring without spending a send: run it with a bogus key. You should get
+a clean 401 from `https://api.brevo.com/v3/smtp/email` — which proves client construction, request
+build and error handling all work:
+
+```bash
+BREVO_API_KEY=xkeysib-invalid BREVO_SMOKE_TO=smoke@test.com \
+  EMAIL_DEFAULT_SENDER=noreply@test.com pnpm exec tsx scripts/brevo-smoke.ts
+```
+
+## 4. End-to-end through the server (optional)
+
+To test the path a real feature takes rather than the service in isolation, use BetterAuth's email
+verification, which is the framework's built-in `BrevoService` consumer
+(`core-better-auth-email-verification.service.ts:180`):
+
+1. In `src/config.env.ts`, set `betterAuth.emailVerification.brevoTemplateId` to your template ID
+   for the `local` environment.
+2. Start the server: `pnpm run start:local`.
+3. Sign up a user with an address you can read — the verification mail is sent through Brevo
+   instead of SMTP.
+
+If `brevoTemplateId` is unset or `BrevoService` is unavailable, the flow silently uses the SMTP
+transport instead — so seeing an SMTP mail is the expected signal that the Brevo overlay is *not*
+active.
+
+## 5. The `exclude` guard
+
+`config.brevo.exclude` is a `RegExp` that suppresses sends to matching addresses (returns the
+string `'TEST_USER!'` instead). It is unset by default and the smoke script deliberately does not
+set one. If you add one to `config.env.ts` for local work, remember the recipient you are testing
+with must **not** match it, or nothing will be sent.
+
+Note for maintainers: the guard is read from `configService.config`, never from
+`configFastButReadOnly`. A deep-frozen `RegExp` carrying the `g` flag throws on `.test()` because
+the call assigns `lastIndex`. The unit spec pins this behaviour.
+
+## 6. Clean up
+
+Remove the real key from `.env` when you are done, or delete the file. Revoke the key in Brevo if
+it was created only for this test.

package/docs/security-overrides.md

@@ -0,0 +1,90 @@
+# Security Overrides — and why yours are not inherited
+
+## The problem in one sentence
+
+**pnpm `overrides:` apply only to the ROOT project of an install.** The overrides declared in
+`@lenne.tech/nest-server`'s own `pnpm-workspace.yaml` therefore do **not** travel with the published
+package. Your project resolves its own dependency tree with *your* overrides — which, by default,
+are none.
+
+A green `pnpm audit` inside the framework repo says nothing about your tree.
+
+## What this concretely means for you
+
+The framework pulls in two transitive packages that resolve to a **vulnerable** version unless you
+override them yourself:
+
+| Package | Advisory | Why it cannot resolve forward on its own |
+|---------|----------|------------------------------------------|
+| `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | `@nestjs/graphql` declares `"ws": "8.20.1"` — an **exact pin**, not a caret. No amount of updating moves it |
+| `@hono/node-server` | [GHSA-frvp-7c67-39w9](https://github.com/advisories/GHSA-frvp-7c67-39w9) (static-file path traversal) + [GHSA-9mqv-5hh9-4cgg](https://github.com/advisories/GHSA-9mqv-5hh9-4cgg) (unauthenticated memory leak). Patched `>=2.0.10` | `@modelcontextprotocol/sdk` declares `^1.19.9` and ships **no 1.x fix line**, so the fix is only available across a major |
+
+`@nestjs/graphql` is a plain `dependencies` entry, so `ws` is installed even when you run with
+`graphQl: false`. Neither package is optional in practice.
+
+## The fix
+
+Add this to your project's `pnpm-workspace.yaml` (pnpm 11+; in pnpm 10 and earlier it lives under
+`pnpm.overrides` in `package.json`):
+
+```yaml
+overrides:
+  # @nestjs/graphql exact-pins ws@8.20.1 (GHSA-96hv-2xvq-fx4p, high, patched >=8.21.0).
+  # An exact pin cannot resolve forward — the override is the only fix.
+  # Remove once @nestjs/graphql stops pinning it.
+  'ws@>=8.0.0 <8.21.0': '8.21.1'
+
+  # @modelcontextprotocol/sdk declares @hono/node-server ^1.19.9 with no 1.x fix line
+  # (GHSA-frvp-7c67-39w9, GHSA-9mqv-5hh9-4cgg). Deliberately a CROSS-MAJOR override.
+  # Verified safe: the SDK's only consumed symbol is `getRequestListener`, whose signature
+  # `(fetchCallback, options?)` is unchanged in 2.x. Engines >=20 and peer hono@^4 both fit.
+  # Remove once @modelcontextprotocol/sdk moves its own range to ^2.
+  '@hono/node-server@<2.0.10': '2.0.11'
+```
+
+Then:
+
+```bash
+pnpm install
+pnpm audit          # must report no known vulnerabilities
+pnpm test           # nothing should regress
+```
+
+Commit `package.json`/`pnpm-workspace.yaml` **and** `pnpm-lock.yaml` together.
+
+> Projects generated from `nest-server-starter` or `lt-monorepo` already carry both entries. This
+> page is for projects that predate that, or that were assembled by hand.
+
+## Rules for writing your own overrides
+
+These are the same rules the framework applies to itself
+(`.claude/rules/package-management.md`):
+
+1. **The target must be a fixed version.** Never `>=x`, `^x`, `~x`, `*`. An unbounded target lets
+   pnpm install the newest match, which can silently cross a major version. This is not
+   hypothetical — an override written as `'vite@>=7.0.0 <=7.3.1': '>=7.3.2'` resolved to `vite@8.0.8`
+   and broke peer dependencies across three packages.
+
+2. **Prefer a bounded key.** `'pkg@>=2.0.0 <2.1.2': '2.1.2'` leaves non-vulnerable versions alone
+   and limits the blast radius. `'pkg': '2.1.2'` replaces *every* version in the tree.
+
+3. **Floor the key inside the major you mean.** A key like `'brace-expansion@>=3.0.0 <5.0.7'` also
+   matches a future 3.x or 4.x dependency and would force it across two majors. Write `>=5.0.0`.
+
+4. **An override is a hard pin, not a floor.** pnpm replaces the whole matched spec with your
+   target. `'hono@>=4.0.0 <4.12.27': '4.12.27'` does not mean "at least 4.12.27" — it pins to
+   exactly that, holding the package back from later patches. Remove an override as soon as the
+   package resolves patched on its own; otherwise today's fix is tomorrow's downgrade-lock.
+
+5. **Document each entry**: the advisory, which package pulls the vulnerable version in, and the
+   condition under which the entry can be deleted.
+
+6. **Verify it is load-bearing.** Resolve a lockfile with the entry removed. If the package still
+   lands on a patched version, the override is inert — keep it only deliberately, and re-check it
+   every maintenance run.
+
+## Related
+
+- [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) — fixed-version
+  policy, the pnpm pin contract, and the incident behind rule 1
+- `pnpm-workspace.yaml` in this package — the framework's own annotated override block

package/migration-guides/11.31.2-to-11.31.3.md

@@ -0,0 +1,135 @@
+# Migration Guide: 11.31.2 → 11.31.3
+
+## Overview
+
+| Category | Effort | Required? |
+|----------|--------|-----------|
+| **New Feature** | Opt-in | No — purely additive |
+| Breaking Changes | None | — |
+| Config Changes | Optional | Only if you enable the Hub |
+
+This release adds the **Hub** — a build-free, ADMIN-gated operator cockpit served directly by the
+framework at `/hub`. It is **disabled by default** and must be switched on per environment, so
+existing projects are unaffected until they opt in. No code changes are required to update.
+
+It also includes a **security patch**: three moderate `axios` advisories (recursion DoS + prototype
+pollution, transitive via the Brevo and Mailjet mail SDKs) are closed by pinning `axios` to `1.18.1`.
+Nothing to do on your side — just update.
+
+## Quick Migration
+
+```bash
+# Update package
+pnpm update @lenne.tech/nest-server
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+Nothing else is required — the Hub stays dormant (every `/hub` route answers 404) until you add a
+`hub` block to a config environment.
+
+## What's New in 11.31.3
+
+### Hub — admin area / operator cockpit
+
+A dependency-free dashboard of runtime information and admin tools, rendered as server-side HTML +
+a vanilla-JS SPA (no React, no build step), so it works identically in npm- and vendor-mode.
+
+**16 panels:** Dashboard, Diagnostics, Logs, Request Traces, Query Performance, Cron Jobs, Database,
+Models/ERD, Migrations, Files (GridFS), Config (secrets masked), Auth Migration (Legacy→IAM), Error
+Codes, Email Preview, Mailbox, AI. Each has a `*.json` sidecar (the stable data contract) the client
+polls; optional sources degrade to an "unavailable" state instead of erroring.
+
+**3 runtime collectors** (in-memory ring buffers, per-app-instance, parallel-test-safe):
+- **Logs** — a chaining `Logger.overrideLogger()` delegate (no main.ts change), secrets redacted.
+- **Traces** — an Express middleware bound only when the collector is 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`.
+
+**Built-in Mailbox** — a Mailpit-style capture of outgoing mail hooked into `EmailService`. In
+`mode: 'capture'` mail is recorded and NOT sent (dev/test); in `mode: 'copy'` it is sent AND a copy
+is recorded (with tokens/links redacted in the stored copy). `capture` throws at startup in
+`production`/`staging` so it can never silently swallow real mail.
+
+**Admin actions** (opt-out via `hub.actions: false`) — migrations run/rollback, GridFS file delete,
+cron start/stop/trigger, collector-buffer clear, test mail. Every mutating request requires the
+`X-Hub-Request: 1` header (CSRF defense) and destructive ones a server-validated type-to-confirm
+keyword; each writes a `[HUB-ACTION] <action> by user <id>` audit line.
+
+#### Enable it
+
+The Hub is **never enabled implicitly** — switch it on per environment in `config.env.ts`:
+
+```typescript
+// config.env.ts (development / local)
+hub: {
+  collectors: { queries: true },   // opt-in query profiler
+  mailbox: { mode: 'capture' },    // capture outgoing mail locally (Mailpit replacement)
+},
+
+// production — usually omit `hub` entirely. If you do want it (still ADMIN-gated),
+// never use mailbox capture mode there:
+// hub: { mailbox: false },
+```
+
+Boolean shorthand `hub: true` enables it at `/hub`, admin-only, with default collectors. See
+`IHubConfig` for every option. Env-var equivalents exist via `NSC__HUB__*` (see `.env.example`).
+
+Then sign in as a user with `RoleEnum.ADMIN` and open `/hub`. The shell is self-sufficient: if you
+are not authenticated it shows a login form that posts to `loginEndpoint` (default
+`/iam/sign-in/email`), so an admin can sign in directly at the API without the frontend. In a
+fullstack setup, a cross-subdomain session cookie from the app login already authenticates `/hub`.
+
+#### Customization (optional)
+
+Replace any Hub controller/service with a project subclass via `CoreModule.forRoot`:
+
+```typescript
+CoreModule.forRoot(envConfig, {
+  hub: {
+    controller: MyHubController,           // extends CoreHubController
+    actionsController: MyHubActionsController, // extends CoreHubActionsController
+    service: MyHubService,                 // extends CoreHubService
+    htmlService: MyHubHtmlService,         // extends CoreHubHtmlService
+    actionsService: MyHubActionsService,   // extends CoreHubActionsService
+  },
+});
+```
+
+## Breaking Changes
+
+None. The Hub is opt-in and disabled by default.
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| Projects that never set `hub` | Unaffected | Every `/hub` route answers 404 |
+| Custom `EmailService` subclass | Compatible | The mailbox capture hook is injected optionally (`@Optional()`) — absent when the Hub/mailbox is off, so there is zero cost and no behavior change |
+| No auth system enabled | ⚠️ Action required | The Hub relies on the app-wide `RolesGuard`/`BetterAuthRolesGuard` to enforce `@Roles(ADMIN)`. With BetterAuth and legacy auth both disabled, no guard runs and the gate is inert — keep an auth module enabled or leave the Hub disabled |
+| `queries` collector enabled | Compatible | Opts the MongoDB driver into `monitorCommands` from `core.module.ts` when the consumer has not set it |
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `/hub` → 404 everywhere | `hub` is not set in that environment's config block — add `hub: true` (or an options object) |
+| Startup error mentioning mailbox `capture` | `mailbox.mode: 'capture'` is forbidden in `production`/`staging` — use `copy` or disable the mailbox there |
+| Query panel empty | The queries collector is opt-in — set `hub.collectors.queries: true` |
+| Cron panel empty | Import `ScheduleModule.forRoot()` in your ServerModule |
+| Hub reachable without login | You disabled all auth systems, so no roles guard runs — see the Compatibility note above |
+
+## Module Documentation
+
+- `src/core/modules/hub/README.md` — full panel/action/collector/security reference
+- `src/core/modules/hub/INTEGRATION-CHECKLIST.md` — config-only setup + common mistakes
+- `.claude/rules/configurable-features.md` — Hub row in the configurable-features table
+
+## References
+
+- Configurable-features pattern: `.claude/rules/configurable-features.md`
+- Request lifecycle (middleware + logger override + email hook): `docs/REQUEST-LIFECYCLE.md`

package/migration-guides/11.31.3-to-11.32.0.md

@@ -0,0 +1,254 @@
+# Migration Guide: 11.31.3 → 11.32.0
+
+## Overview
+
+| Category | Change | Effort |
+|----------|--------|--------|
+| **Breaking** | `@getbrevo/brevo` upgraded 3.x → 6.x — three public SDK symbols no longer exist | 5 min *(only if you import them)* |
+| **Breaking** | `BrevoService` now logs failures via the Nest `Logger` instead of `console.error` | 0 min *(unless you assert on stdout)* |
+| **Security** | pnpm `overrides:` do **not** reach your project — two entries you must add yourself | 5 min |
+| **New** | `installProcessDiagnostics()` / `handleFatalBootstrapError()` — make a silent crash diagnosable | 5 min *(opt-in, two lines in `main.ts`)* |
+| **New** | `server.enableShutdownHooks()` recommendation — without it a container hangs on `docker stop` | 1 min |
+| **New** | `brevo.maxRetries`, `brevo.timeoutInSeconds`, `brevo.throwOnError` config | 0 min *(safe defaults)* |
+| **Changed** | The Brevo SDK is now imported lazily — faster cold start for everyone not using Brevo | 0 min |
+
+**Why MINOR and not PATCH:** `@getbrevo/brevo` is a direct `dependencies` entry of this package, so
+`pnpm update` pulls v6 into your tree. Its v3 symbols are gone. Per
+[`.claude/rules/versioning.md`](../.claude/rules/versioning.md), a breaking change increments MINOR.
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run build   # surfaces the Brevo symbol removals, if any apply to you
+```
+
+If the build is clean and you do not use `BrevoService`, you are done — but please still read
+[Security: add two overrides](#security-add-two-overrides), which applies to every project.
+
+---
+
+## Breaking Changes
+
+### 1. `@getbrevo/brevo` 3.x → 6.x: three symbols removed
+
+v6 is a full rewrite around a `BrevoClient` facade. These no longer exist:
+
+| Removed in v6 | Replacement |
+|---------------|-------------|
+| `TransactionalEmailsApi` | `BrevoClient` (`client.transactionalEmails.*`) |
+| `TransactionalEmailsApiApiKeys` | `new BrevoClient({ apiKey })` |
+| `SendSmtpEmail` | `Brevo.SendTransacEmailRequest` |
+
+**Before**
+
+```typescript
+import { SendSmtpEmail, TransactionalEmailsApi, TransactionalEmailsApiApiKeys } from '@getbrevo/brevo';
+
+const api = new TransactionalEmailsApi();
+api.setApiKey(TransactionalEmailsApiApiKeys.apiKey, apiKey);
+
+const mail: SendSmtpEmail = { templateId, to: [{ email }] };
+const result = await api.sendTransacEmail(mail);
+return result.body;                       // <- v3 wrapped the payload in an envelope
+```
+
+**After**
+
+```typescript
+import { BrevoClient } from '@getbrevo/brevo';
+import type { Brevo } from '@getbrevo/brevo';
+
+const client = new BrevoClient({ apiKey });
+
+const request: Brevo.SendTransacEmailRequest = { templateId, to: [{ email }] };
+return await client.transactionalEmails.sendTransacEmail(request);   // <- payload directly
+```
+
+**The awaited data shape is unchanged.** v3's `.body` was `{ messageId?, messageIds? }`; v6's
+awaited result is `SendTransacEmailResponse`, which is the same shape. Only the envelope is gone.
+If you need the raw HTTP response, v6 offers `.withRawResponse()`.
+
+**The thrown error type changed** from an axios-shaped `{ response, body }` to
+`BrevoError { statusCode, body, rawResponse, requestId }`. Adjust any `catch` block that reached
+into `error.response`.
+
+> If you only ever call `BrevoService`, nothing changes for you — its method signatures and return
+> values are unchanged.
+
+### 2. `BrevoService` failures now go through the Nest `Logger`
+
+`console.error(error)` was replaced with `this.logger.error(...)`. The return contract is
+unchanged, but the output now carries the `[BrevoService]` context and participates in whatever log
+transport you configured. Only relevant if you assert on raw stdout in tests.
+
+---
+
+## Security: add two overrides
+
+**This applies to every project, whether or not you use Brevo.**
+
+pnpm `overrides:` are honoured only for the **root** project of an install. The overrides declared
+inside `@lenne.tech/nest-server` therefore do **not** travel with the published package — your
+project resolves its own tree, with your overrides. Two transitive dependencies land on a
+known-vulnerable version without help:
+
+```yaml
+# pnpm-workspace.yaml (pnpm 11+; pnpm.overrides in package.json for pnpm 10 and earlier)
+overrides:
+  # @nestjs/graphql exact-pins ws@8.20.1 (GHSA-96hv-2xvq-fx4p, high). An exact pin
+  # cannot resolve forward — the override is the only fix.
+  'ws@>=8.0.0 <8.21.0': '8.21.1'
+
+  # @modelcontextprotocol/sdk declares @hono/node-server ^1.19.9 with no 1.x fix line
+  # (GHSA-frvp-7c67-39w9, GHSA-9mqv-5hh9-4cgg). Deliberately cross-major; verified safe
+  # (the SDK's only consumed symbol, `getRequestListener`, is unchanged in 2.x).
+  '@hono/node-server@<2.0.10': '2.0.11'
+```
+
+Then `pnpm install && pnpm audit` — it must report no known vulnerabilities.
+
+Projects generated from `nest-server-starter` or `lt-monorepo` already carry these.
+Full rationale and the rules for writing your own:
+[`docs/security-overrides.md`](../docs/security-overrides.md).
+
+---
+
+## What's New
+
+### Process diagnostics (opt-in, two lines)
+
+A Node API can die *silently*: the dev runner prints only `app crashed` with no stacktrace, and in a
+container the process just vanishes. A missing stacktrace means a SIGNAL killed it, not a throw.
+
+`installProcessDiagnostics()` makes the reason visible — unhandled rejections are logged without
+killing the server, uncaught exceptions are logged before the exit, non-zero exit codes are
+reported, and SIGTERM/SIGINT/SIGHUP/SIGQUIT are labelled as *external* terminations so they stop
+masquerading as in-process crashes.
+
+**Consumers own their own `main.ts`, so this does not arrive automatically.** Add it:
+
+```typescript
+// src/main.ts
+import { handleFatalBootstrapError, installProcessDiagnostics } from '@lenne.tech/nest-server';
+
+async function bootstrap() {
+  // FIRST statement — it must run before NestFactory.create() to catch module-construction failures
+  installProcessDiagnostics();
+
+  const server = await NestFactory.create<NestExpressApplication>(ServerModule);
+
+  // ... your configuration ...
+
+  server.enableShutdownHooks();   // see below — required for a clean container stop
+  await server.listen(envConfig.port);
+}
+
+// A rejection here is a fatal startup failure (EADDRINUSE, DB unreachable). Without the .catch it
+// becomes a mere unhandledRejection and leaves a zombie process, "alive" but listening on nothing.
+bootstrap().catch(handleFatalBootstrapError);
+```
+
+Do **not** call it from a module. It must run before `NestFactory.create()`, and it installs a
+`process.exit(1)` path that would otherwise arm inside `Test.createTestingModule()` and kill your
+whole test runner instead of failing one spec.
+
+Options:
+
+```typescript
+installProcessDiagnostics({
+  onUnhandledRejection: 'exit',   // default 'log' — 'exit' restores Node's own fail-fast
+  shutdownTimeoutMs: 30_000,      // watchdog when another handler owns the shutdown; 0 disables
+});
+```
+
+### `server.enableShutdownHooks()` — fixes a container that will not stop
+
+Independent of the diagnostics, and worth doing even if you skip them.
+
+In a container Node usually runs as **PID 1**. A PID-namespace init is `SIGNAL_UNKILLABLE`: a signal
+with the default disposition is silently discarded by the kernel. The listening HTTP server keeps
+the event loop non-empty, so nothing exits on its own — `docker stop` waits out its **full grace
+period** and then SIGKILLs. In-flight requests are dropped and every `onModuleDestroy()` is skipped.
+
+`enableShutdownHooks()` closes the app and drains the loop, so the process exits normally.
+Belt-and-braces: run a real init in the image (`docker run --init`, or `tini` as `ENTRYPOINT`).
+
+### New `brevo` config
+
+```typescript
+brevo: {
+  apiKey: '...',
+  sender: { email: '...', name: '...' },
+  maxRetries: 0,          // default 0 — see below
+  timeoutInSeconds: 10,   // default 10
+  throwOnError: false,    // default false
+}
+```
+
+The v6 SDK introduced a retry policy v3 did not have: 2 retries on 408/429/5xx, honouring
+`Retry-After` with a cap of **60 seconds per attempt**, and no request timeout. Since
+`BrevoService.sendMail()` is awaited inside request handlers (e.g. the BetterAuth
+email-verification hook), those defaults would let a rate-limited Brevo park a user-facing HTTP
+request for roughly two minutes. This framework therefore defaults to `maxRetries: 0` and
+`timeoutInSeconds: 10`. Raise them deliberately if you want SDK-level retrying.
+
+`throwOnError: true` makes a failed send throw instead of resolving to `null` — useful on
+security-critical delivery paths.
+
+### Brevo SDK is now lazily imported
+
+`@getbrevo/brevo` is ~580 CommonJS modules and `BrevoService` is re-exported from the package
+barrel, so every consumer paid that cold-start cost whether or not Brevo was configured. The SDK is
+now loaded on first send. No API change.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|:------:|-------|
+| Calling `BrevoService.sendMail()` / `sendHtmlMail()` | Compatible | Signatures and return values unchanged |
+| Extending `BrevoService` | Compatible | `getClient()`, `handleSendError()`, `buildIdempotencyHeaders()` are `protected` and overridable |
+| Importing `TransactionalEmailsApi` / `SendSmtpEmail` / `TransactionalEmailsApiApiKeys` | **Breaking** | Removed in v6 — see above |
+| Reading `result.body` from a direct SDK call | **Breaking** | v6 resolves the payload directly |
+| Not using Brevo at all | Compatible | Cold start improves |
+| Existing `main.ts` without the diagnostics | Compatible | Purely opt-in; nothing regresses |
+
+### Checking whether a failed send was silently swallowed
+
+`BrevoService` resolves to `null` on failure rather than throwing (unless `throwOnError` is set).
+If you call it directly, check for it — "did not throw" is not "was delivered":
+
+```typescript
+const result = await this.brevoService.sendMail(email, templateId, params);
+if (result === null) {
+  // log, fall back to SMTP, retry — but do NOT record this as a successful send
+}
+```
+
+The framework's own email-verification path was fixed to do exactly this: it now falls through to
+the SMTP fallback instead of marking the address as mailed.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Module '"@getbrevo/brevo"' has no exported member 'TransactionalEmailsApi'` | v6 removed it | Use `BrevoClient` — see [Breaking Changes](#1-getbrevobrevo-3x--6x-three-symbols-removed) |
+| `pnpm audit` reports `ws` / `@hono/node-server` | Overrides are not inherited | [Add the two entries](#security-add-two-overrides) |
+| `docker stop` takes the full grace period, then kills the container | No `enableShutdownHooks()`, node is PID 1 | Add the call; optionally `--init` / `tini` |
+| Sign-up request hangs ~2 minutes when Brevo is rate-limited | v6 retry defaults | Already fixed by the `maxRetries: 0` default — verify you did not override it |
+| Verification mail silently never arrives, logs say "sent" | Pre-11.32.0 swallow bug | Fixed; on custom callers, check for `null` |
+| `[exit] process exiting with code 0` no longer logged | Intentional | A clean exit is not a diagnostic; only non-zero codes are logged |
+| Process warnings no longer double-printed | Intentional | Node prints them itself, with more detail — use `--trace-warnings` for a stack |
+
+---
+
+## Module Documentation
+
+- [`docs/security-overrides.md`](../docs/security-overrides.md) — why overrides are not inherited, and the rules for writing them
+- [`docs/REQUEST-LIFECYCLE.md`](../docs/REQUEST-LIFECYCLE.md) — Process Diagnostics row under "Development & Operations"
+- `src/core/common/helpers/process-diagnostics.helper.ts` — full rationale in the module docblock
+- [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) — fixed-version policy for overrides