@lenne.tech/nest-server 11.27.2 → 11.27.3

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.2",
+  "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",

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