@lenne.tech/nest-server 11.35.1 → 11.36.0

package/migration-guides/11.35.1-to-11.36.0.md

@@ -0,0 +1,168 @@
+# Migration Guide: 11.35.1 → 11.36.0
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | Sign-in and sign-up now **validate their input**. An address that does not satisfy `IsEmail` is refused with a 400 before Better-Auth sees it — which can lock out an existing account created outside `CoreUserInput` (§2) |
+| **New Features** | `betterAuth.emailAndPassword.revokeSessionsOnPasswordReset` — opt-in, ends the sessions that already existed when the user resets their password (§1) |
+| **Bugfixes** | `brevo.exclude` stopped excluding every second recipient (§3). Malformed or absent sign-in input answers 400 instead of 500 (§2) |
+| **Migration Effort** | **Read §2 before upgrading** and run the account audit there. §1 is opt-in and off by default; §3 needs nothing |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.36.0
+pnpm run build
+pnpm test
+```
+
+Then run the audit in §2 — it is the only step that can surprise you.
+
+**Vendor-mode projects:** all three changes are independent and single-file —
+`modules/better-auth/better-auth.config.ts` (§1),
+`modules/better-auth/core-better-auth.controller.ts` (§2),
+`common/services/brevo.service.ts` (§3). §1 also adds the option to
+`common/interfaces/server-options.interface.ts`; taking the config field without the
+`better-auth.config.ts` half gives you a setting that type-checks and does nothing, so sync those two
+together.
+
+---
+
+## 1. End existing sessions on a password reset (opt-in)
+
+A password reset is what somebody reaches for when they suspect their account was taken over.
+Leaving the older sessions alive defeats the point: the attacker keeps theirs, and the new password
+changes nothing for them.
+
+```typescript
+// config.env.ts
+betterAuth: {
+  emailAndPassword: {
+    revokeSessionsOnPasswordReset: true,
+  },
+},
+```
+
+Forwarded to Better-Auth's native flag, which honours it on **all three** reset routes — password
+reset, email-OTP and phone-number.
+
+**Off by default, and staying that way.** It is a behaviour change for an existing deployment: after
+a reset the user is signed out everywhere, including on the devices they still hold. That is worth
+choosing, not worth inflicting on upgrade.
+
+The value is matched with `=== true`, so a truthy-but-not-`true` value arriving as JSON through
+`NSC__*` or `NEST_SERVER_CONFIG` (a hand-written `"true"`, say) does **not** silently enable a
+sign-out-everywhere behaviour.
+
+> **Do not route this through `betterAuth.options` instead.** That object is spread *shallowly* over
+> the resolved config — only `advanced` is deep-merged — so an `options.emailAndPassword` does not
+> add a key, it **replaces the whole block**, including the scrypt `password.hash` / `password.verify`
+> pair the framework installs. Every credential in your database would stop verifying, at runtime,
+> with no boot error. This is why the flag is a first-class config field.
+
+---
+
+## 2. Sign-in and sign-up validate their input — read this before upgrading
+
+### What changed
+
+`CoreBetterAuthSignInInput` and `CoreBetterAuthSignUpInput` carried `@ApiProperty()` only:
+documentation, no validation. Every line of the handler then reads `input.email`, so a body that was
+malformed or absent produced a `TypeError` and reached the client as a **500**.
+
+| Request | Before | After |
+|---|---|---|
+| `{"email": "not-an-email", "password": "x"}` | `500` | `400`, naming the field |
+| `{}` | `500` | `400`, naming both fields |
+| no body at all | `500` | `400` `Missing input` |
+| valid credentials | unchanged | unchanged |
+
+On the most-probed endpoint any deployment has, a 500 tells the caller to retry something that can
+never succeed and files their mistake in the same bucket as a real outage. The legacy sign-in
+answered these cases with a 400; that contract is restored.
+
+### The part that can lock someone out
+
+`@IsEmail()` is now enforced on **sign-in**, not just on sign-up. An account whose stored address
+does not satisfy it can no longer authenticate — the request is refused before Better-Auth is
+reached.
+
+This is unlikely but not impossible. `CoreUserInput.email` has always carried the same `IsEmail()`
+validator, so an account created through the normal API cannot be affected. An account can still
+have been created another way:
+
+- a seed script or migration writing directly through Mongoose,
+- Better-Auth's own native sign-up route,
+- an import from another system.
+
+The addresses at risk are the ones that look fine to a human and fail `validator.js`: no TLD
+(`admin@localhost`), a dotless domain (`test@test`), or trailing whitespace.
+
+**Audit before upgrading.** Use the real validator rather than a hand-written pattern — `IsEmail`
+delegates to `validator.js`, whose rules are far more involved than any regex you would write for
+this, and a check that disagrees with the one actually enforced is worse than none:
+
+```js
+// node — run from your project root, where class-validator's `validator` resolves
+const isEmail = require('validator/lib/isEmail');
+const { MongoClient } = require('mongodb');
+
+const client = await MongoClient.connect(process.env.MONGODB_URI);
+const users = await client.db().collection('users').find({}, { projection: { email: 1 } }).toArray();
+const locked = users.filter(u => !u.email || !isEmail(u.email));
+
+console.log(`${locked.length} account(s) can no longer sign in:`);
+locked.forEach(u => console.log(' ', JSON.stringify(u.email), u._id.toString()));
+await client.close();
+```
+
+Anything this lists needs its address corrected before the upgrade, or those users are refused with a
+validation error rather than an authentication error — and the message will not point at the cause.
+
+### If you subclass the controller
+
+The validation lives on the DTOs, so an override that keeps the parameter types inherits it. A
+subclass that declares its **own** input class is responsible for its own validators —
+`MapAndValidatePipe` walks the prototype chain child-first and skips a property once a child class
+has validated it.
+
+`termsAndPrivacyAccepted` is deliberately the one sign-up field without a presence validator: whether
+consent is required is a policy question answered by `betterAuth.signUpValidation` through
+`CoreBetterAuthSignUpValidatorService`, not by the DTO. It does now carry `@IsBoolean()`.
+
+---
+
+## 3. `brevo.exclude` excluded only every second recipient
+
+`BrevoService` called `.test()` on the configured `RegExp`. Projects declare that pattern with the
+`g` flag:
+
+```typescript
+brevo: { exclude: /@(testuser\.com|test\.de)/gi }
+```
+
+`RegExp.prototype.test` advances `lastIndex` on a `g` or `y` pattern, and the config holds a single
+shared instance — so the same address answered `true`, `false`, `true`, … across calls. **Every
+second excluded recipient was sent a real, billable transactional mail.**
+
+Found in production: a CI end-to-end run delivered five mails to a `@testuser.com` address that the
+project's own exclude pattern lists, and the provider flagged the runner's IP before anyone noticed
+the guard was only half working.
+
+The check now matches against a flagless copy, so each call is independent and the configured
+pattern's `lastIndex` is left untouched — it is shared process-wide, and mutating it leaked into
+every later reader. Both send paths were affected; both are fixed.
+
+**Nothing to do.** If you kept the `g` flag off as a workaround, you can stop — it no longer matters
+either way.
+
+---
+
+## Module Documentation
+
+- BetterAuth integration: [`src/core/modules/better-auth/INTEGRATION-CHECKLIST.md`](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- BetterAuth customization: [`src/core/modules/better-auth/CUSTOMIZATION.md`](../src/core/modules/better-auth/CUSTOMIZATION.md)
+- Configuration patterns: [`.claude/rules/configurable-features.md`](../.claude/rules/configurable-features.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.35.1",
+  "version": "11.36.0",
   "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",
@@ -91,21 +91,21 @@
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
     "@better-auth/passkey": "1.6.26",
-    "@getbrevo/brevo": "6.0.2",
+    "@getbrevo/brevo": "6.0.3",
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@nestjs/apollo": "13.4.2",
-    "@nestjs/common": "11.1.29",
-    "@nestjs/core": "11.1.29",
-    "@nestjs/graphql": "13.4.2",
+    "@nestjs/apollo": "13.4.5",
+    "@nestjs/common": "11.2.1",
+    "@nestjs/core": "11.2.1",
+    "@nestjs/graphql": "13.4.5",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.1.29",
+    "@nestjs/platform-express": "11.2.1",
     "@nestjs/schedule": "6.1.3",
-    "@nestjs/swagger": "11.4.6",
+    "@nestjs/swagger": "11.4.7",
     "@nestjs/terminus": "11.1.1",
     "@tus/file-store": "2.1.1",
-    "@tus/server": "2.4.3",
+    "@tus/server": "2.4.4",
     "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
     "better-auth": "1.6.26",
@@ -122,12 +122,12 @@
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
     "graphql-ws": "6.2.1",
-    "jose": "6.2.8",
+    "jose": "6.2.9",
     "js-sha256": "1.0.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
     "mongodb": "7.5.0",
-    "mongoose": "9.9.1",
+    "mongoose": "9.9.3",
     "multer": "2.2.0",
     "node-mailjet": "6.0.11",
     "nodemailer": "9.0.5",
@@ -166,15 +166,15 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1106.0",
-    "@aws-sdk/s3-request-presigner": "3.1106.0",
+    "@aws-sdk/client-s3": "3.1112.0",
+    "@aws-sdk/s3-request-presigner": "3.1112.0",
     "@compodoc/compodoc": "2.0.0",
     "@nestjs/cli": "11.0.24",
     "@nestjs/schematics": "11.1.0",
-    "@nestjs/testing": "11.1.28",
+    "@nestjs/testing": "11.2.1",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.15.47",
-    "@tus/s3-store": "2.0.5",
+    "@swc/core": "1.16.0",
+    "@tus/s3-store": "2.0.6",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
@@ -187,22 +187,22 @@
     "@vitest/coverage-v8": "4.1.10",
     "@vitest/ui": "4.1.10",
     "ansi-colors": "4.1.3",
-    "bullmq": "6.0.9",
+    "bullmq": "6.1.2",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
     "ioredis": "6.0.0",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.1",
-    "oxfmt": "0.62.0",
-    "oxlint": "1.77.0",
+    "oxfmt": "0.63.0",
+    "oxlint": "1.78.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
-    "tsx": "4.23.11",
+    "tsx": "4.23.12",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
-    "unplugin-swc": "1.5.10",
+    "unplugin-swc": "1.5.11",
     "vite": "8.2.1",
     "vite-plugin-node": "8.0.0",
     "vitest": "4.1.10"

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

@@ -3414,6 +3414,30 @@ interface IBetterAuthBase {
      * @default true
      */
     enabled?: boolean;
+
+    /**
+     * End every existing session when the user completes a password reset.
+     *
+     * A reset is what somebody reaches for when they suspect their account was
+     * taken over, so leaving the older sessions alive defeats the point: the
+     * attacker keeps theirs and the new password changes nothing for them.
+     *
+     * Left off by default because it is a behaviour change for existing
+     * deployments — a reset then signs the user out everywhere, including on
+     * the devices they still hold.
+     *
+     * Passed through to better-auth's native
+     * `emailAndPassword.revokeSessionsOnPasswordReset`. It cannot be set via
+     * `options` instead: that object is spread SHALLOWLY over the resolved
+     * config, so an `options.emailAndPassword` would replace the whole block
+     * — including the scrypt `password.hash` / `password.verify` pair this
+     * framework installs — and every credential in the database would stop
+     * verifying.
+     *
+     * @default false
+     * @since 11.36.0
+     */
+    revokeSessionsOnPasswordReset?: boolean;
   };
 
   /**

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

@@ -53,9 +53,8 @@ export class BrevoService {
         return false;
       }
 
-      // Exclude (test) users, must be done via config and not via configFastButReadOnly,
-      // otherwise the error TypeError: Cannot assign to read only property 'lastIndex' of object '[object RegExp]' occurs
-      if (this.configService.config?.brevo?.exclude?.test?.(to)) {
+      // Exclude (test) users
+      if (this.isExcluded(to)) {
         return 'TEST_USER!';
       }
 
@@ -98,9 +97,8 @@ export class BrevoService {
         return false;
       }
 
-      // Exclude (test) users, must be done via config and not via configFastButReadOnly,
-      // otherwise the error TypeError: Cannot assign to read only property 'lastIndex' of object '[object RegExp]' occurs
-      if (this.configService.config?.brevo?.exclude?.test?.(to)) {
+      // Exclude (test) users
+      if (this.isExcluded(to)) {
         return 'TEST_USER!';
       }
 
@@ -135,6 +133,36 @@ export class BrevoService {
     return { 'Idempotency-Key': randomUUID() };
   }
 
+  /**
+   * Checks a recipient against `brevo.exclude` without inheriting the pattern's match state.
+   *
+   * Two traps live in this one line, and both have bitten:
+   *
+   * 1. `RegExp.prototype.test` ADVANCES `lastIndex` on a pattern carrying `g` or `y`. The config
+   *    holds a single shared instance and projects declare it as `/…/gi`, so calling `.test()` on
+   *    it directly answers true, false, true, … for the very same address — every second excluded
+   *    recipient receives a real mail. Matching against a flagless copy keeps each call
+   *    independent and leaves the configured pattern untouched.
+   * 2. It must be read from `config`, never from `configFastButReadOnly`: assigning `lastIndex` on
+   *    the frozen copy throws `TypeError: Cannot assign to read only property 'lastIndex'`.
+   *    Point 1 removes the assignment, but the frozen object may still be a `deepFreeze`d clone
+   *    whose flags differ, so the mutable side stays the source of truth.
+   *
+   * @param to - Recipient email address
+   * @returns `true` when the recipient matches the configured exclude pattern
+   */
+  protected isExcluded(to: string): boolean {
+    const exclude = this.configService.config?.brevo?.exclude;
+    if (typeof exclude?.test !== 'function') {
+      return false;
+    }
+
+    const stateless =
+      exclude.global || exclude.sticky ? new RegExp(exclude.source, exclude.flags.replace(/[gy]/g, '')) : exclude;
+
+    return stateless.test(to);
+  }
+
   /**
    * Lazily constructs (and memoises) the Brevo SDK client.
    *

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

@@ -444,6 +444,10 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
         hash: nativeScryptHash,
         verify: nativeScryptVerify,
       },
+      // Opt-in: a reset then also ends the sessions that already existed, which
+      // is the point of resetting after a suspected takeover. Off by default so
+      // the behaviour of existing deployments does not change under them.
+      revokeSessionsOnPasswordReset: config.emailAndPassword?.revokeSessionsOnPasswordReset === true,
     },
     plugins,
     secret: validation.resolvedSecret || config.secret,

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

@@ -24,6 +24,7 @@ import {
   ApiProperty,
   ApiTags,
 } from '@nestjs/swagger';
+import { IsBoolean, IsEmail, IsNotEmpty, IsOptional, IsString } from 'class-validator';
 import { Request, Response } from 'express';
 
 import { Roles } from '../../common/decorators/roles.decorator';
@@ -122,10 +123,18 @@ export class CoreBetterAuthResponse {
  * Sign-in input DTO
  */
 export class CoreBetterAuthSignInInput {
+  // Validated, not merely documented. Without these the sign-in endpoint — the
+  // most-probed surface of any deployment — answered malformed input with a
+  // 500 from the first property read, which tells a client to retry something
+  // that can never work and buries real faults in the same bucket.
   @ApiProperty({ description: 'User email address', example: 'user@example.com' })
+  @IsNotEmpty()
+  @IsEmail()
   email: string;
 
   @ApiProperty({ description: 'User password' })
+  @IsNotEmpty()
+  @IsString()
   password: string;
 }
 
@@ -134,15 +143,30 @@ export class CoreBetterAuthSignInInput {
  */
 export class CoreBetterAuthSignUpInput {
   @ApiProperty({ description: 'User email address', example: 'user@example.com' })
+  @IsNotEmpty()
+  @IsEmail()
   email: string;
 
   @ApiProperty({ description: 'Display name', example: 'John Doe', required: false })
+  @IsOptional()
+  @IsString()
   name?: string;
 
   @ApiProperty({ description: 'User password (min 8 characters)' })
+  @IsNotEmpty()
+  @IsString()
   password: string;
 
+  // Deliberately left without a validator, unlike its three neighbours. Whether this field is
+  // REQUIRED is a policy question the framework cannot answer here — it depends on
+  // `betterAuth.signUpValidation`, which the handler consults through
+  // CoreBetterAuthSignUpValidatorService before anything else happens. A `@IsNotEmpty()` here would
+  // hard-code "consent is mandatory" into the DTO and reject a sign-up for a deployment that never
+  // asked for consent, with a message that names the wrong cause. The others carry validators
+  // because "an email must look like an email" needs no policy.
   @ApiProperty({ description: 'Whether user accepted terms and privacy policy', required: false })
+  @IsBoolean()
+  @IsOptional()
   termsAndPrivacyAccepted?: boolean;
 }
 
@@ -329,6 +353,15 @@ export class CoreBetterAuthController {
   ): Promise<CoreBetterAuthResponse> {
     this.ensureEnabled();
 
+    // A request with no body at all reaches here as `undefined`, and every line
+    // below reads `input.email`. Without this the caller gets a 500 for what is
+    // plainly their own malformed request — and a 500 tells a client to retry
+    // later, which will never help. The legacy sign-in answered this case with
+    // a 400 "Missing input"; keep that contract.
+    if (!input) {
+      throw new BadRequestException('Missing input');
+    }
+
     const api = this.betterAuthService.getApi();
     if (!api) {
       throw new BadRequestException(ErrorCode.BETTERAUTH_API_NOT_AVAILABLE);
@@ -494,6 +527,11 @@ export class CoreBetterAuthController {
     this.ensureEnabled();
     this.betterAuthService.ensureSignUpEnabled();
 
+    // Same reasoning as in signIn: a body-less request must not become a 500.
+    if (!input) {
+      throw new BadRequestException('Missing input');
+    }
+
     // Validate sign-up input (termsAndPrivacyAccepted is required by default)
     if (this.signUpValidator) {
       this.signUpValidator.validateSignUpInput({ termsAndPrivacyAccepted: input.termsAndPrivacyAccepted });