@lenne.tech/nest-server 11.27.2 → 11.27.4

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/migration-guides/11.27.3-to-11.27.4.md

@@ -0,0 +1,236 @@
+# Migration Guide: 11.27.3 → 11.27.4
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | Opt-in `CHECK_LOW_RESOURCE` e2e mode (keeps parallel test runs stable under load); `check.mjs` now labels signal-killed steps (`SIGTERM`/`SIGKILL`) instead of showing a bare exit code. |
+| **Bugfixes** | Idle watchdog no longer false-kills output-buffering steps (build / typecheck / audit); a stray `SIGKILL` after PID reuse is prevented; an invalid `--idle-timeout` value now falls back to the default instead of silently disabling the watchdog. |
+| **Migration Effort** | 0 minutes for npm consumers (`pnpm update` is enough). Optional: projects that copied `scripts/check.mjs` / `vitest-e2e.config.ts` from the starter can adopt the updated files. |
+
+This is a **repo-internal tooling & test-infrastructure release**. It touches
+**no framework source** (`src/` is unchanged) — only `scripts/check.mjs` and
+`vitest-e2e.config.ts`. The npm package (`dist/`) is functionally identical to
+11.27.3; consuming projects need no code or config changes.
+
+---
+
+## Quick Migration
+
+No code changes required.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.4
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+> These files ship in the git repository / starter, **not** in the npm package.
+> An npm-mode consumer is unaffected. A project that copied `scripts/check.mjs`
+> and/or `vitest-e2e.config.ts` from the starter (11.27.1+) can copy the updated
+> versions to get the improvements below — see **Compatibility Notes**.
+
+---
+
+## What's New in 11.27.4
+
+### 1. Opt-in low-resource e2e mode (`CHECK_LOW_RESOURCE`)
+
+Running several full e2e suites at the same time on one machine (e.g. multiple
+parallel `lt dev` / `lt ticket` environments, or a second terminal) can saturate
+CPU and the shared MongoDB. Under that load individual requests exceed the 30s
+`testTimeout` and auth queries fail — surfacing as intermittent `401`s or
+per-file timeouts. Data isolation was never the cause (every run already gets a
+unique database); the cause is **physical resource contention**.
+
+`vitest-e2e.config.ts` now supports an **opt-in** throttle. It changes nothing
+by default — solo and moderately parallel runs stay at full speed:
+
+```bash
+# Full speed (default) — nothing changes
+pnpm test
+
+# Opt in when you deliberately run MANY suites in parallel
+CHECK_LOW_RESOURCE=1 pnpm test
+
+# Pin the fork cap explicitly (otherwise ~1/3 of CPU cores)
+CHECK_LOW_RESOURCE=1 CHECK_LOW_RESOURCE_FORKS=2 pnpm test
+```
+
+| `CHECK_LOW_RESOURCE` | Effect |
+|----------------------|--------|
+| unset / `0` / `false` (default) | No cap, no timeout change — full speed |
+| `1` / `true` | `poolOptions.forks.maxForks` capped (`~cores/3`, min 2), `testTimeout` 30s → 60s, `hookTimeout` 120s → 240s |
+| any value + `CHECK_LOW_RESOURCE_FORKS=<n>` | Fork cap pinned to `<n>` |
+
+When active it prints a one-line notice at startup:
+`[e2e] low-resource mode active: maxForks=…, timeouts raised`.
+
+### 2. Signal-exit labelling in `scripts/check.mjs`
+
+When a step's process is killed by a signal, the package manager surfaces it as
+a numeric `Command failed with exit code 143` (SIGTERM) / `137` (SIGKILL) line,
+while the outer shell reports only a generic exit `1`. The `check` report now
+detects that and appends a clear reason so it isn't mistaken for a test-assertion
+failure:
+
+```
+[check] step ended via SIGTERM (exit 143) — the process was killed, not an
+assertion failure. Usual cause: resource pressure (parallel checks/builds
+swapping) or an external kill. Re-run this project's check alone to confirm.
+```
+
+The hint is suppressed when the step was killed by the check's own idle
+watchdog (that path already carries its own `[watchdog]` note), and it only
+matches the package manager's own failure line — never an `exit code 143` a test
+happens to log — so real assertion failures are never mislabeled.
+
+---
+
+## What's Fixed in 11.27.4
+
+All fixes are in `scripts/check.mjs`, refining the idle watchdog introduced in
+11.27.x.
+
+### Watchdog now applies to test steps only
+
+The idle watchdog kills a step whose child produces no output for the timeout
+window (default 300s). It previously watched **every** step. But `build`,
+`typecheck` and `audit` legitimately buffer all their output to the end (and go
+silent under a non-TTY pipe) — watching them risked false-killing a slow but
+progressing run. The watchdog is now armed **only for test steps**, whose
+runners stream progress continuously, so prolonged silence genuinely means
+deadlocked workers. The run header reflects this: `watchdog: 5m 0s (tests)`.
+
+### No stray `SIGKILL` after PID reuse
+
+When the watchdog fires it sends `SIGTERM`, then escalates to `SIGKILL` after a
+5s grace window. That escalation timer is now tracked and cancelled once the
+child exits within the grace window — previously the stray timer could fire
+later and `SIGKILL` an **unrelated** process that had reused the freed PID.
+
+### Invalid `--idle-timeout` falls back to the default
+
+An unparseable, negative, or unit-suffixed value (e.g. `--idle-timeout=30s`)
+now keeps the watchdog at its default (300s) and prints a notice, instead of
+silently evaluating to `0` and disabling the protection. Only an explicit `0`
+disables the watchdog.
+
+```bash
+--idle-timeout=120     # 120s
+--idle-timeout=0       # explicitly disabled
+--idle-timeout=30s     # invalid → default 300s + "[check] ignoring invalid idle-timeout" notice
+CHECK_IDLE_TIMEOUT=90  # env equivalent
+```
+
+### Clearer watchdog reason
+
+The `[watchdog]` note now suggests re-running the **actual** failing command
+(`Re-run the step directly to debug: <cmd>`) instead of a hard-coded
+`pnpm run vitest`.
+
+---
+
+## Breaking Changes
+
+None.
+
+---
+
+## Compatibility Notes
+
+- **npm-mode consumers:** unaffected. `scripts/check.mjs` and
+  `vitest-e2e.config.ts` are not part of the npm package (`dist/`); no runtime
+  or API behavior changed. `pnpm update` is sufficient.
+- **`IServerOptions` / `CoreModule.forRoot()` / all Core classes:** unchanged.
+  No source, export, or method signature changed in this release.
+- **Starter-derived projects** (copied `scripts/check.mjs` / `vitest-e2e.config.ts`
+  from nest-server-starter 11.27.1+): copy the updated files to adopt the
+  test-only watchdog, the PID-reuse fix, the signal-exit hint, and the opt-in
+  `CHECK_LOW_RESOURCE` mode. All changes are backward compatible — the default
+  behavior (no env vars set) is unchanged, so an updated `check.mjs` /
+  `vitest-e2e.config.ts` is a drop-in replacement.
+- **Vendor-mode consumers:** not applicable — `scripts/` and
+  `vitest-e2e.config.ts` are repo/starter tooling, not part of the vendored
+  `src/core/` file set. Nothing to sync.
+- **`lt dev` / `lt ticket` parallel workflows:** the throttle is **manual**
+  (`CHECK_LOW_RESOURCE=1`). To have it apply automatically inside isolated
+  environments, the lt CLI can export it into the test env (the same way it
+  exports `LT_DEV_TEST_SHARDS` for the Playwright config). That is a CLI change,
+  not a framework change.
+- **Nuxt / Playwright side:** no equivalent needed. The Playwright config
+  already uses `workers: 1` plus a `LT_DEV_TEST_SHARDS`-driven relaxed mode for
+  load, so the same class of contention is already handled there.
+
+---
+
+## Troubleshooting
+
+### My `build` / `typecheck` / `audit` step is no longer killed after 300s
+
+Intended. Only **test** steps are watched now (they stream progress). Buffering
+steps that legitimately go silent are no longer at risk of a false watchdog
+kill. If such a step genuinely hangs, it still fails via its own tool timeout or
+the overall run.
+
+### The check aborted with "step ended via SIGTERM (exit 143)"
+
+That step's process was killed by a signal, not by a failed assertion. The usual
+cause is resource pressure (several heavy checks/builds/test suites running at
+once and swapping the machine) or an external kill. Re-run that project's check
+alone to confirm — it will typically pass.
+
+### e2e tests flake (401 / timeouts) only when I run many suites in parallel
+
+This is physical CPU/MongoDB contention, not a data-isolation bug (each run has
+its own database). Opt into the throttle for those sessions:
+`CHECK_LOW_RESOURCE=1 pnpm test`. It caps parallel forks and raises timeouts so
+the suites share the machine without starving each other.
+
+### `CHECK_LOW_RESOURCE` seems to have no effect
+
+Confirm the value is truthy (`1` / `true`) and not `0` / `false` / empty. When
+active, the run prints `[e2e] low-resource mode active: maxForks=…` at startup.
+
+---
+
+## Repo-Internal Tooling Changes (no consumer action)
+
+Summary of everything in this release, for projects that track the tooling
+(all listed above in detail):
+
+- `scripts/check.mjs`: idle watchdog restricted to test steps; stray-`SIGKILL`
+  (PID-reuse) fix; invalid `--idle-timeout` falls back to default instead of
+  disabling; watchdog reason shows the actual command; new `signalExitHint`
+  labelling `SIGTERM`/`SIGKILL` step exits.
+- `vitest-e2e.config.ts`: opt-in `CHECK_LOW_RESOURCE` mode (fork cap + raised
+  timeouts) for stable parallel e2e runs; default behavior unchanged.
+
+These carry forward the tooling introduced in
+[11.27.1 → 11.27.2](./11.27.1-to-11.27.2.md) (chain-faithful audit) and
+[11.27.2 → 11.27.3](./11.27.2-to-11.27.3.md) (idle watchdog + per-run test
+databases).
+
+---
+
+## Module Documentation
+
+No core module changed in this release. Relevant testing documentation:
+
+- **Testing rules:** [.claude/rules/testing.md](../.claude/rules/testing.md) —
+  test framework, per-run database lifecycle, parallel execution
+- **Reference implementation:** [nest-server-starter](https://github.com/lenneTech/nest-server-starter)
+  — carries the same `scripts/check.mjs` + `vitest-e2e.config.ts`
+
+---
+
+## References
+
+- [Migration Guide 11.27.2 → 11.27.3](./11.27.2-to-11.27.3.md) — Previous release (verification-email crash fix + idle watchdog + per-run test DBs)
+- [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.4",
   "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,
+          ),
+      );
     };
   }