@lenne.tech/nest-server 11.27.1 → 11.27.3

package/migration-guides/11.27.1-to-11.27.2.md

@@ -0,0 +1,191 @@
+# Migration Guide: 11.27.1 → 11.27.2
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None |
+| **Bugfixes** | `scripts/check.mjs` no longer hides devDependency vulnerabilities for library packages. The audit step now runs the chain's own audit command verbatim (same scope / `--prod` flag / `--audit-level`) instead of a hardcoded `pnpm audit --prod --json`. Repo-internal tooling — no consumer impact. |
+| **Security** | 3 new / refreshed `pnpm.overrides` entries — `undici` range widened to `<7.28.0`, plus new entries for `piscina <4.9.3` and `@babel/core <7.29.6`. All transitive via the build/test toolchain. |
+| **Migration Effort** | 0 minutes (automatic) — `pnpm update` is enough. ~2 minutes optional to mirror the security overrides into your own project's `package.json`. |
+
+This is a **maintenance release**. No source-code or config changes are required.
+
+---
+
+## Quick Migration
+
+No code changes required.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.2
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+
+# Re-run audit to confirm advisories cleared
+pnpm audit
+```
+
+---
+
+## What's New in 11.27.2
+
+### 1. Security overrides refreshed
+
+`pnpm.overrides` in this repo's `package.json` gained two new entries and
+widened one existing range. Every override targets a **fixed version** (per
+`.claude/rules/package-management.md` override rules — no `>=` / `^` / `~`):
+
+| Package | Override | Advisory | Pulled in via |
+|---------|----------|----------|---------------|
+| `undici` | `7.28.0` (was `7.25.0`) | Various CVEs `<7.28.0` (incl. high) | `@compodoc/compodoc > cheerio`, `better-auth` |
+| `piscina` | `4.9.3` *(new)* | High CVE in `piscina <4.9.3` | build/test toolchain |
+| `@babel/core` | `7.29.6` *(new)* | `@babel/core <7.29.6` advisory | `@compodoc/compodoc > @babel/preset-env` |
+
+#### Why your project may still see CVEs after upgrading
+
+`pnpm.overrides` is **scoped to the package that declares it**. The framework's
+overrides do **not** propagate into consumer projects' lockfiles. If your own
+`pnpm audit` flags `undici / piscina / @babel/core`, mirror the entries into
+your project's `package.json`:
+
+```jsonc
+// projects/api/package.json (or your project's package.json)
+"pnpm": {
+  "//overrides": {
+    "undici@>=7.0.0 <7.28.0": "Security: various CVEs <7.28.0 (incl. high) - transitive via @compodoc/compodoc>cheerio + better-auth",
+    "piscina@<4.9.3": "Security: high CVE in piscina <4.9.3 - transitive via the build/test toolchain",
+    "@babel/core@<7.29.6": "Security: @babel/core <7.29.6 advisory - transitive via @compodoc/compodoc>@babel/preset-env"
+  },
+  "overrides": {
+    "undici@>=7.0.0 <7.28.0": "7.28.0",
+    "piscina@<4.9.3": "4.9.3",
+    "@babel/core@<7.29.6": "7.29.6"
+  }
+}
+```
+
+After adding, run `pnpm install && pnpm audit && pnpm test`.
+
+### 2. `scripts/check.mjs` audit step is now chain-faithful
+
+The audit step in the `check.mjs` wrapper previously hardcoded
+`pnpm audit --prod --json` with a separate gate level extracted from the
+chain's `--audit-level` flag. For library packages where dev-only dependencies
+ship vulnerabilities, this **masked the vulnerabilities** that a bare
+`pnpm audit` would have surfaced — because `--prod` excludes devDependencies.
+
+The audit step now runs the **chain's own audit command verbatim** (same scope,
+same `--prod` flag if any, same `--audit-level` if any), only appending `--json`
+for the structured counts. The blocking gate becomes the command's own exit
+code, so `check` blocks **precisely when a bare `<auditCmd>` would** —
+never with a narrower scope than the chain.
+
+What this means in practice:
+
+- **Library packages** (this repo, plus any consumer that runs `pnpm audit` —
+  not `pnpm audit --prod` — in their `check` script) now see devDep vulns
+  surface in the wrapper run, matching what their bare audit command reports.
+- **Application packages** that use `pnpm audit --prod` keep the exact same
+  behaviour — their scope is unchanged.
+- The status header now shows the **full audit command** (e.g.
+  `audit: pnpm audit --audit-level=high`) instead of just `audit gate: high`,
+  so the gate is auditable at a glance.
+
+If your `check` chain has no audit step at all, the wrapper now correctly
+**skips** the audit phase (previously it ran a hardcoded one anyway).
+
+> **Consumer impact:** None unless you copied `scripts/check.mjs` into your
+> own project from 11.27.1. If you did, the upgrade fixes a silent gap in your
+> security gate — review the next `pnpm run check` for previously hidden
+> devDep findings.
+
+---
+
+## Breaking Changes
+
+None.
+
+---
+
+## Compatibility Notes
+
+- **`IServerOptions` / `CoreModule.forRoot()`:** unchanged.
+- **`FRAMEWORK-API.md`:** regenerated for the new version stamp only — no API
+  surface differences vs. 11.27.1.
+- **`config.env.ts`:** no new fields, no deprecations.
+- **Vendor-mode consumers:** nothing to sync. The override changes live in
+  `package.json` at the **repo root**, which is excluded from
+  `convertCloneToVendored`. The `scripts/check.mjs` wrapper also lives outside
+  `src/core/`, so vendor projects keep their existing `check` setup.
+- **Custom controllers / resolvers extending Core* classes:** no impact —
+  no Core method signatures changed.
+
+---
+
+## Verifying
+
+```bash
+# 1. Update + install
+pnpm add @lenne.tech/nest-server@11.27.2
+pnpm install
+
+# 2. Confirm advisories cleared (or only show unaffected residuals)
+pnpm audit
+
+# 3. Smoke-test the new check wrapper (only relevant in this repo)
+pnpm run check        # quiet, report-driven — audit now mirrors the chain
+pnpm run check:raw    # original chain, full noise
+
+# 4. Tests + build
+pnpm test
+pnpm run build
+```
+
+---
+
+## Troubleshooting
+
+### `pnpm audit` in my consumer project still reports `undici` / `piscina` / `@babel/core`
+
+Expected — `pnpm.overrides` is scoped to the declaring package. Mirror the
+entries listed under [Why your project may still see CVEs after upgrading](#why-your-project-may-still-see-cves-after-upgrading).
+
+### `pnpm run check` suddenly reports more vulnerabilities than 11.27.1
+
+Working as intended — the previous wrapper silently narrowed the audit to
+`--prod` scope. The new wrapper mirrors your chain's own audit command, so
+devDep vulnerabilities a bare `pnpm audit` would have flagged now appear in
+the wrapper run. Either:
+
+- Mirror the relevant overrides from this guide (recommended), or
+- Narrow your chain's audit command to `pnpm audit --prod --audit-level=high`
+  if devDep vulns are out of scope for your gate.
+
+### Audit step is skipped — "audit: none" in the header
+
+Your `check` chain has no audit step. Add `pnpm audit` (or
+`pnpm audit --prod --audit-level=high`) at the start of the chain in
+`package.json` to re-enable the gate.
+
+---
+
+## Module Documentation
+
+No module documentation changes in this release. Reference documentation:
+
+- **Package management rules:** [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) — fixed-version overrides only, never ranges
+- **Framework compatibility:** [`.claude/rules/framework-compatibility.md`](../.claude/rules/framework-compatibility.md) — what ships in the npm package
+
+---
+
+## References
+
+- [Migration Guide 11.27.0 → 11.27.1](./11.27.0-to-11.27.1.md) — Previous release (initial `scripts/check.mjs` introduction + 7 security overrides)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — reference implementation

package/migration-guides/11.27.2-to-11.27.3.md

@@ -0,0 +1,177 @@
+# Migration Guide: 11.27.2 → 11.27.3
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None (one new internal helper export: `sendAuthEmailSafely`) |
+| **Bugfixes** | A failed verification-email send (e.g. SMTP not configured, delivery failure) no longer crashes the Node process via an unhandled promise rejection. The send stays fire-and-forget (timing-attack mitigation) but every failure — sync throw or async rejection — is now caught and logged instead. |
+| **Migration Effort** | 0 minutes (automatic) — `pnpm update` is enough. |
+
+This is a **stability bugfix release**. No source-code or config changes are
+required in consuming projects.
+
+---
+
+## Quick Migration
+
+No code changes required.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.3
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+---
+
+## What's Fixed in 11.27.3
+
+### Process crash on failed verification-email send
+
+**The bug:** BetterAuth's `emailVerification.sendVerificationEmail` callback
+invoked the email send fire-and-forget (intentionally not awaited, per
+Better-Auth's recommendation, so response timing cannot leak whether an
+account exists). But the detached promise had **no rejection handler**. When
+the send failed — SMTP not configured, provider outage, delivery rejection —
+the rejection became an *unhandled promise rejection*, which terminates the
+Node process under Node's default `--unhandled-rejections=throw` (Node ≥ 15).
+
+**Observed trigger:** signing up an unverified user and then signing in
+(`sendOnSignUp` / `sendOnSignIn` are enabled by default) while no working
+SMTP transport was configured took the whole API down.
+
+**The fix:** sends are now routed through a small hardened wrapper:
+
+```typescript
+// src/core/modules/better-auth/better-auth.config.ts
+export function sendAuthEmailSafely(send: () => unknown, onError: (error: unknown) => void): void {
+  void Promise.resolve()
+    .then(send)
+    .catch((error) => {
+      try {
+        onError(error);
+      } catch {
+        // A throwing error handler must not crash the process either.
+      }
+    });
+}
+```
+
+Behavior after the fix:
+
+- The send remains **non-blocking** — response timing is unchanged
+  (timing-attack mitigation preserved).
+- Sync throws and async rejections are both caught and logged via the NestJS
+  logger (context `BetterAuthConfig`), including the **stack trace**:
+  `Failed to send verification email: <message>`.
+- Even a throwing error handler (e.g. a custom logger transport failing)
+  cannot re-introduce the crash.
+- The API response to the client is unchanged (it never reflected send
+  failures — this matches Better-Auth's own default behavior).
+
+**Covered by regression tests:** `tests/unit/better-auth-email-safe.spec.ts`
+(async rejection, sync throw, success path, non-blocking guarantee, no
+unhandled rejection, throwing error handler).
+
+---
+
+## Breaking Changes
+
+None.
+
+---
+
+## Compatibility Notes
+
+- **`IServerOptions` / `CoreModule.forRoot()`:** unchanged.
+- **`SendVerificationEmailCallback` contract:** unchanged (`{ token, url, user }`
+  → `Promise<void>`). Projects supplying their own callback need no changes —
+  their callback is now additionally protected by the wrapper.
+- **Monitoring / operations:** if you relied on the process crash (supervisor
+  restart loops) as an implicit signal for a broken mail setup, switch your
+  alerting to the error log line `Failed to send verification email: …`
+  (logger context `BetterAuthConfig`). Note that the email-verification
+  service additionally logs delivery failures with a masked recipient address
+  before rethrowing — a real outage produces both lines.
+- **Workarounds can be removed:** a custom `process.on('unhandledRejection')`
+  handler added to a project's `main.ts` solely to survive this crash is no
+  longer needed for this path.
+- **Better-Auth standard mechanism:** the framework deliberately detaches only
+  the sends it owns instead of enabling Better-Auth's global
+  `advanced.backgroundTasks` option (which would detach ALL background tasks —
+  OTP, invites, password reset — and route failures to Better-Auth's internal
+  logger instead of the NestJS logger). Projects that want the native
+  mechanism can still enable it via the `betterAuth.options.advanced`
+  passthrough.
+- **Vendor-mode consumers:** the fix lives in
+  `src/core/modules/better-auth/better-auth.config.ts` and is picked up by the
+  next core sync (`/lt-dev:backend:update-nest-server-core`). The regression
+  test file (`tests/unit/`) is framework-repo-only and is not part of the
+  vendored file set.
+- **Custom controllers / resolvers extending Core\* classes:** no impact — no
+  Core method signatures changed.
+
+---
+
+## Troubleshooting
+
+### Verification emails silently don't arrive after updating
+
+Nothing regressed — before this fix the same situation crashed the API
+instead. Check the logs for `Failed to send verification email: …`
+(context `BetterAuthConfig`) and fix the underlying SMTP/Brevo configuration
+(`email.smtp` / provider settings in `config.env.ts`).
+
+### I see two error log lines for one failed send
+
+Expected. The email-verification service logs the delivery failure with a
+masked recipient address and rethrows; the wrapper logs the same failure once
+more (with stack trace) as the final safety net. The wrapper line additionally
+covers failures thrown outside the service's own try/catch.
+
+---
+
+## Repo-Internal Tooling Changes (no consumer action)
+
+These affect only this repository's development workflow — listed here because
+some projects copied `scripts/check.mjs` from 11.27.1+:
+
+- **`scripts/check.mjs` idle watchdog:** a step whose child produces no output
+  for 300s (configurable via `--idle-timeout=<seconds>` / `CHECK_IDLE_TIMEOUT`,
+  `0` disables) is now killed — including its whole process tree — and the
+  check fails with a clear `[watchdog]` reason. Previously a deadlocked test
+  run (workers idle at 0% CPU) spun the live view forever. If you copied
+  `check.mjs` into your project, update your copy to get the watchdog.
+- **Per-run test databases:** `tests/global-setup.ts` now gives every vitest
+  run a unique database (`<base>-run-<timestamp>-p<pid>`) instead of dropping
+  a shared fixed-name DB — concurrent runs (second terminal, IDE runner) can
+  no longer wipe each other's users/sessions mid-flight. A new reporter
+  (`tests/db-lifecycle.reporter.ts`) drops the DB after a successful run and
+  collects stale leftovers; after a failed run the DB is kept for debugging
+  until the next successful run. An externally set `MONGODB_URI` (CI) keeps
+  the previous behavior.
+
+---
+
+## Module Documentation
+
+### BetterAuth
+
+- **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md)
+- **Integration Checklist:** [src/core/modules/better-auth/INTEGRATION-CHECKLIST.md](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- **Key File:** `src/core/modules/better-auth/better-auth.config.ts` —
+  `sendAuthEmailSafely()` helper + `buildEmailVerificationConfig()` wiring
+
+---
+
+## References
+
+- [Migration Guide 11.27.1 → 11.27.2](./11.27.1-to-11.27.2.md) — Previous release (chain-faithful audit step + security overrides)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — reference implementation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.27.1",
+  "version": "11.27.3",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -192,7 +192,9 @@
       "minimatch@>=10.0.0 <10.2.5": "Security: RegExp DoS - transitive via @nestjs/apollo>ts-morph>@ts-morph/common and nodemon",
       "ajv@<6.14.0": "Security: prototype pollution - transitive via @getbrevo/brevo>rewire>eslint",
       "ajv@>=7.0.0-alpha.0 <8.18.0": "Security: prototype pollution - transitive via @nestjs/cli>@angular-devkit",
-      "undici@>=7.0.0 <7.25.0": "Security: various CVEs - transitive via @compodoc/compodoc>cheerio",
+      "undici@>=7.0.0 <7.28.0": "Security: various CVEs <7.28.0 (incl. high) - transitive via @compodoc/compodoc>cheerio + better-auth",
+      "piscina@<4.9.3": "Security: high CVE in piscina <4.9.3 - transitive via the build/test toolchain",
+      "@babel/core@<7.29.6": "Security: @babel/core <7.29.6 advisory - transitive via @compodoc/compodoc>@babel/preset-env",
       "handlebars@>=4.0.0 <4.7.9": "Security: prototype pollution (GHSA-q42p-pg8m-cqh6) - transitive via @compodoc/compodoc",
       "brace-expansion@<1.1.13": "Security: RegExp DoS - transitive via eslint>minimatch",
       "brace-expansion@>=4.0.0 <5.0.6": "Security: RegExp DoS - Large numeric range defeats brace expansion (GHSA-jxxr-4gwj-5jf2) - transitive via nodemon>minimatch and @ts-morph/common>minimatch and @compodoc/compodoc>glob>minimatch",
@@ -225,7 +227,9 @@
       "minimatch@>=10.0.0 <10.2.5": "10.2.5",
       "ajv@<6.14.0": "6.14.0",
       "ajv@>=7.0.0-alpha.0 <8.18.0": "8.18.0",
-      "undici@>=7.0.0 <7.25.0": "7.25.0",
+      "undici@>=7.0.0 <7.28.0": "7.28.0",
+      "piscina@<4.9.3": "4.9.3",
+      "@babel/core@<7.29.6": "7.29.6",
       "handlebars@>=4.0.0 <4.7.9": "4.7.9",
       "brace-expansion@<1.1.13": "1.1.13",
       "brace-expansion@>=4.0.0 <5.0.6": "5.0.6",

package/src/core/modules/better-auth/better-auth.config.ts

@@ -15,6 +15,11 @@ import { detectCookiePrefixDrift, resolveBetterAuthCookiePrefix } from './better
  */
 export type BetterAuthInstance = ReturnType<typeof betterAuth>;
 
+/**
+ * Shared logger for all functions in this config module
+ */
+const logger = new Logger('BetterAuthConfig');
+
 // ---------------------------------------------------------------------------
 // Performance-optimized password hashing using Node.js native crypto.scrypt
 //
@@ -174,6 +179,40 @@ export type SendVerificationEmailCallback = (options: {
   user: { email: string; id: string; name?: null | string };
 }) => Promise<void>;
 
+/**
+ * Invoke an auth-email send (verification / password-reset) fire-and-forget.
+ *
+ * Better-Auth recommends NOT awaiting these sends so the response time does not
+ * leak whether an account exists (timing attack). The catch here is essential:
+ * a rejected send (e.g. SMTP not configured / delivery failure) must never
+ * become an unhandled promise rejection — that crashes the Node process (an
+ * unverified sign-up + sign-in took the whole API down in dev). This wrapper
+ * keeps the send non-blocking while routing every failure (sync throw or async
+ * rejection) to `onError` instead. `onError` itself is guarded too: if the
+ * handler throws, the error is swallowed rather than crashing the process.
+ *
+ * Deliberate divergence from Better-Auth's own mechanism: Better-Auth awaits
+ * these callbacks via `runInBackgroundOrAwait` and offers
+ * `advanced.backgroundTasks` as its native non-blocking path. That option is
+ * global (it detaches ALL background tasks — OTP, invites, password reset, …)
+ * and routes failures to Better-Auth's internal logger instead of the NestJS
+ * logger, so this wrapper detaches only the sends the framework owns. Projects
+ * can still opt into `advanced.backgroundTasks` via the `options` passthrough.
+ */
+export function sendAuthEmailSafely(send: () => unknown, onError: (error: unknown) => void): void {
+  void Promise.resolve()
+    .then(send)
+    .catch((error) => {
+      try {
+        onError(error);
+      } catch {
+        // Last resort: the error handler itself failed. Swallowing here keeps
+        // the no-unhandled-rejection guarantee — a throwing handler must not
+        // crash the process this helper exists to protect.
+      }
+    });
+}
+
 /**
  * Better-Auth field type definition
  * Matches the DBFieldType from better-auth
@@ -264,7 +303,6 @@ export interface CreateBetterAuthResult {
 }
 
 export function createBetterAuthInstance(options: CreateBetterAuthOptions): CreateBetterAuthResult | null {
-  const logger = new Logger('BetterAuthConfig');
   const { config, db, fallbackSecrets, onEmailVerified, sendVerificationEmail, serverEnv } = options;
 
   // Return null only if better-auth is explicitly disabled
@@ -495,9 +533,19 @@ function buildEmailVerificationConfig(
       data: { token: string; url: string; user: { email: string; id: string; name?: null | string } },
       _request?: Request,
     ) => {
-      // Don't await to prevent timing attacks (as recommended by Better-Auth docs)
-
-      sendVerificationEmail(data);
+      // Fire-and-forget (timing-attack mitigation, per Better-Auth docs) — but a
+      // failed send must be logged, never crash the process (see sendAuthEmailSafely).
+      // Note: delivery failures are also logged (with masked recipient) by the
+      // email-verification service before rethrowing; this line additionally
+      // covers failures thrown outside the service's own try/catch.
+      sendAuthEmailSafely(
+        () => sendVerificationEmail(data),
+        (error) =>
+          logger.error(
+            `Failed to send verification email: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            error instanceof Error ? error.stack : undefined,
+          ),
+      );
     };
   }