@lenne.tech/nest-server 11.43.2 → 12.0.0

package/src/core/modules/better-auth/core-better-auth-api.middleware.ts

@@ -1,16 +1,16 @@
-import { BadRequestException, Injectable, Logger, NestMiddleware, Optional } from '@nestjs/common';
+import { BadRequestException, HttpException, Injectable, Logger, NestMiddleware, Optional } from '@nestjs/common';
 import { Response as ExpressResponse, NextFunction, Request } from 'express';
 
-import { isProduction } from '../../common/helpers/logging.helper';
-import { ConfigService } from '../../common/services/config.service';
-import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service';
-import { BetterAuthCookieHelper, createCookieHelper } from './core-better-auth-cookie.helper';
-import { wrapBetterAuthErrorResponse } from './core-better-auth-error-codes.helper';
-import { isControllerHandledPath } from './core-better-auth-openapi.helper';
-import { runWithResetPassword } from './core-better-auth-password-reset.registry';
-import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
-import { extractSessionToken, sendWebResponse, signCookieValue, toWebRequest } from './core-better-auth-web.helper';
-import { CoreBetterAuthService } from './core-better-auth.service';
+import { isProduction } from '../../common/helpers/logging.helper.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service.js';
+import { BetterAuthCookieHelper, createCookieHelper } from './core-better-auth-cookie.helper.js';
+import { wrapBetterAuthErrorResponse } from './core-better-auth-error-codes.helper.js';
+import { isControllerHandledPath } from './core-better-auth-openapi.helper.js';
+import { runWithResetPassword } from './core-better-auth-password-reset.registry.js';
+import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper.js';
+import { extractSessionToken, sendWebResponse, signCookieValue, toWebRequest } from './core-better-auth-web.helper.js';
+import { CoreBetterAuthService } from './core-better-auth.service.js';
 
 /**
  * Native Better-Auth routes that set a NEW password from a token or OTP, with the body
@@ -35,6 +35,43 @@ export const PASSWORD_RESET_PATHS: { field: string; path: string }[] = [
   { field: 'newPassword', path: '/phone-number/reset-password' },
 ];
 
+/**
+ * The other native Better-Auth routes whose body carries a password (Better-Auth 1.7 sources): `verify`
+ * fields are checked against the stored credential, `set` fields become the new one.
+ *
+ * Same reason as above, from the other side. Sign-in normalizes, so a client may send a plaintext or a
+ * sha256 password — but until 12.0.0 these routes were forwarded untouched. A plaintext `password` was then
+ * compared as `scrypt(plaintext)` against `scrypt(sha256(...))`: enabling 2FA, deleting the account or
+ * generating backup codes answered "Invalid password" for the right password. Worse, `change-password` stored
+ * a plaintext `newPassword` as `scrypt(plaintext)` and locked the account out at the next sign-in.
+ * nuxt-extensions hashes in the browser and never noticed; every other client (an app, a script, a test) did.
+ * Normalizing an already-hashed value is a no-op, so hashing clients are unaffected.
+ */
+/**
+ * A request path without trailing slashes and lower-cased — the form the route tables above are matched in.
+ *
+ * A loop, not `path.replace(/\/+$/, '')`: that regex backtracks quadratically on a long run of slashes followed by
+ * another character, and the path comes from an unauthenticated request. A 16 KB path (what Node's header limit
+ * allows) blocked the event loop for ~115 ms per call.
+ */
+export function normalizeIamRoutePath(path: string): string {
+  let end = path.length;
+  while (end > 0 && path.charCodeAt(end - 1) === 47 /* '/' */) {
+    end--;
+  }
+  return path.slice(0, end).toLowerCase();
+}
+
+export const PASSWORD_FIELD_PATHS: { path: string; set: string[]; verify: string[] }[] = [
+  { path: '/change-password', set: ['newPassword'], verify: ['currentPassword'] },
+  { path: '/delete-user', set: [], verify: ['password'] },
+  { path: '/two-factor/disable', set: [], verify: ['password'] },
+  { path: '/two-factor/enable', set: [], verify: ['password'] },
+  { path: '/two-factor/generate-backup-codes', set: [], verify: ['password'] },
+  { path: '/two-factor/get-totp-uri', set: [], verify: ['password'] },
+  { path: '/verify-password', set: [], verify: ['password'] },
+];
+
 /**
  * Passkey paths that generate challenges
  */
@@ -89,7 +126,7 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
     // `===` — so a variant it accepts but this table does not would silently skip BOTH the
     // normalization and the legacy mirror, i.e. reproduce the exact lockout this method exists
     // to prevent, through a URL shape rather than a code change.
-    const normalizedPath = relativePath.replace(/\/+$/, '').toLowerCase();
+    const normalizedPath = normalizeIamRoutePath(relativePath);
     const route = PASSWORD_RESET_PATHS.find((entry) => normalizedPath === entry.path);
     if (!route) {
       return undefined;
@@ -123,6 +160,32 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
     return normalized;
   }
 
+  /**
+   * Brings every other password a native route carries (see {@link PASSWORD_FIELD_PATHS}) to the shape the
+   * stored credential was written in. Matched like {@link normalizeResetPassword}: exact, after trimming a
+   * trailing slash and lower-casing.
+   *
+   * @throws BadRequestException when a plaintext NEW password violates the configured length policy
+   */
+  protected normalizeNativePasswords(req: Request, relativePath: string): void {
+    const normalizedPath = normalizeIamRoutePath(relativePath);
+    const route = PASSWORD_FIELD_PATHS.find((entry) => normalizedPath === entry.path);
+    if (!route || !this.userMapper) {
+      // A missing mapper is reported by normalizeResetPassword() for the routes where it locks accounts out.
+      return;
+    }
+    for (const field of [...route.verify, ...route.set]) {
+      const submitted = req.body?.[field];
+      if (!submitted || typeof submitted !== 'string') {
+        continue;
+      }
+      if (route.set.includes(field)) {
+        this.assertResetPasswordLength(submitted);
+      }
+      req.body[field] = this.userMapper.normalizePasswordForIam(submitted);
+    }
+  }
+
   /**
    * Enforces the configured password length on the value the CLIENT actually sent.
    *
@@ -283,6 +346,8 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
       // Put a reset password into the shape sign-in expects BEFORE the body is
       // serialized, and keep the value for the legacy mirror below.
       const resetPassword = this.normalizeResetPassword(req, relativePath);
+      // …and every password a non-reset native route carries (2FA, change-password, delete-user, …).
+      this.normalizeNativePasswords(req, relativePath);
 
       // Convert Express request to Web Standard Request with proper cookie signing
       const webRequest = await toWebRequest(req, {
@@ -458,6 +523,13 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
       // Convert Web Standard Response to Express response using shared helper
       await sendWebResponse(res, response);
     } catch (error) {
+      // A refused request (the password length policy) is an answer, not a handler failure. Nest's middleware
+      // proxy hands a thrown exception to the exception filters, so it is rendered like the same refusal from a
+      // controller: 400 with its message, and no ERROR line. Answering it here as a 500 told the client nothing.
+      if (error instanceof HttpException) {
+        throw error;
+      }
+
       // Log error with appropriate detail level
       if (this.isProd) {
         this.logger.error('Better Auth handler error');

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

@@ -1,8 +1,8 @@
 import { Field, ObjectType } from '@nestjs/graphql';
 
-import { Restricted } from '../../common/decorators/restricted.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
-import { CoreBetterAuthSessionInfoModel, CoreBetterAuthUserModel } from './core-better-auth-models';
+import { Restricted } from '../../common/decorators/restricted.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { CoreBetterAuthSessionInfoModel, CoreBetterAuthUserModel } from './core-better-auth-models.js';
 
 /**
  * Better-Auth Authentication Response Model

package/src/core/modules/better-auth/core-better-auth-challenge.service.ts

@@ -2,10 +2,10 @@ import { Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import * as crypto from 'crypto';
 import { Collection, Document } from 'mongodb';
-import { Connection } from 'mongoose';
+import type { Connection } from 'mongoose';
 
-import { IBetterAuth } from '../../common/interfaces/server-options.interface';
-import { ConfigService } from '../../common/services/config.service';
+import { IBetterAuth } from '../../common/interfaces/server-options.interface.js';
+import { ConfigService } from '../../common/services/config.service.js';
 
 /**
  * WebAuthn challenge mapping document structure.

package/src/core/modules/better-auth/core-better-auth-cookie.helper.ts

@@ -1,10 +1,10 @@
 import { Logger } from '@nestjs/common';
 import { Response } from 'express';
 
-import { isProductionLikeEnv } from '../../common/helpers/cookies.helper';
-import { resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper';
-import { isJwtShaped } from './core-better-auth-token.helper';
-import { signCookieValue } from './core-better-auth-web.helper';
+import { isProductionLikeEnv } from '../../common/helpers/cookies.helper.js';
+import { resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper.js';
+import { isJwtShaped } from './core-better-auth-token.helper.js';
+import { signCookieValue } from './core-better-auth-web.helper.js';
 
 /**
  * Last-resort logger for the JWT refusal below.

package/src/core/modules/better-auth/core-better-auth-email-verification.service.ts

@@ -1,18 +1,19 @@
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';
-import ejs = require('ejs');
+import ejs from 'ejs';
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { isLocalEnv, isProductionLikeEnv, resolveAppUrlFromConfig } from '../../common/helpers/cookies.helper';
-import { maskEmail } from '../../common/helpers/logging.helper';
-import { IBetterAuthEmailVerificationConfig } from '../../common/interfaces/server-options.interface';
-import { BrevoService } from '../../common/services/brevo.service';
-import { ConfigService } from '../../common/services/config.service';
-import { CoreRedisService } from '../../common/services/core-redis.service';
-import { EmailService } from '../../common/services/email.service';
-import { TemplateService } from '../../common/services/template.service';
-import { AuthEmailCallbackOptions, formatProjectName } from './better-auth.config';
+import { isLocalEnv, isProductionLikeEnv, resolveAppUrlFromConfig } from '../../common/helpers/cookies.helper.js';
+import { maskEmail } from '../../common/helpers/logging.helper.js';
+import { IBetterAuthEmailVerificationConfig } from '../../common/interfaces/server-options.interface.js';
+import { BrevoService } from '../../common/services/brevo.service.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { CoreRedisService } from '../../common/services/core-redis.service.js';
+import { EmailService } from '../../common/services/email.service.js';
+import { TemplateService } from '../../common/services/template.service.js';
+import { AuthEmailCallbackOptions, formatProjectName } from './better-auth.config.js';
+import { callerDirectory } from '../../common/helpers/module-location.helper.js';
 
 /**
  * Resolved configuration type for email verification
@@ -637,6 +638,15 @@ export class CoreBetterAuthEmailVerificationService {
     // a client that names its page is a better authority on that page than a framework default.
     if (!target) {
       target = this.readCallbackUrlFromBetterAuthLink(options.url);
+      // Only an absolute http(s) URL or a root-relative path names a page. Anything else — a path without
+      // its leading slash (`redirectTo: 'reset'`), or a template literal over an unset variable
+      // (`${baseUrl}/reset` → 'undefined/reset') — would reach the mail as a relative link that resolves
+      // nowhere, and a mail is the one place nobody can fix it afterwards. Use the default page instead.
+      // Debug, not warn: the route is unauthenticated, and a log line per request is a log-flooding lever.
+      if (target && !target.startsWith('/') && !/^https?:\/\//i.test(target)) {
+        this.logger.debug(`Ignoring redirectTo "${target}" for the reset link: not an absolute URL or a path`);
+        target = undefined;
+      }
     }
 
     // The SAME resolver the legacy twin uses. Until 11.39.0 this read `appUrl` straight off the
@@ -777,7 +787,7 @@ export class CoreBetterAuthEmailVerificationService {
     }
 
     const projectTemplatesPath = this.configService.getFastButReadOnly<string>('templates.path');
-    const nestServerTemplatesPath = path.join(__dirname, '..', '..', '..', 'templates');
+    const nestServerTemplatesPath = path.join(callerDirectory(), '..', '..', '..', 'templates');
 
     const candidates = [
       // Project templates (with locale)

package/src/core/modules/better-auth/core-better-auth-error-codes.helper.ts

@@ -1,4 +1,4 @@
-import { ErrorCode } from '../error-code/error-codes';
+import { ErrorCode } from '../error-code/error-codes.js';
 
 /**
  * Translate Better-Auth's own error codes into nest-server's `#LTNS_XXXX:` message format.

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

@@ -1,7 +1,7 @@
 import { Field, ObjectType } from '@nestjs/graphql';
 
-import { Restricted } from '../../common/decorators/restricted.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
+import { Restricted } from '../../common/decorators/restricted.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
 
 /**
  * Better-Auth User Model for GraphQL

package/src/core/modules/better-auth/core-better-auth-openapi.helper.ts

@@ -1,4 +1,4 @@
-import type { IBetterAuth } from '../../common/interfaces/server-options.interface';
+import type { IBetterAuth } from '../../common/interfaces/server-options.interface.js';
 
 /**
  * What the Swagger document needs to know about the routes under the Better-Auth base path.

package/src/core/modules/better-auth/core-better-auth-rate-limit.middleware.ts

@@ -1,8 +1,8 @@
 import { HttpException, HttpStatus, Injectable, NestMiddleware } from '@nestjs/common';
 import { NextFunction, Request, Response } from 'express';
 
-import { CoreBetterAuthRateLimiter, RateLimitResult } from './core-better-auth-rate-limiter.service';
-import { CoreBetterAuthService } from './core-better-auth.service';
+import { CoreBetterAuthRateLimiter, RateLimitResult } from './core-better-auth-rate-limiter.service.js';
+import { CoreBetterAuthService } from './core-better-auth.service.js';
 
 /**
  * Middleware that applies rate limiting to Better-Auth endpoints

package/src/core/modules/better-auth/core-better-auth-rate-limiter.service.ts

@@ -1,14 +1,14 @@
 import { Injectable, Logger, Optional } from '@nestjs/common';
 
-import { IBetterAuthRateLimit } from '../../common/interfaces/server-options.interface';
-import { CoreRedisService } from '../../common/services/core-redis.service';
+import { IBetterAuthRateLimit } from '../../common/interfaces/server-options.interface.js';
+import { CoreRedisService } from '../../common/services/core-redis.service.js';
 import {
   InMemoryRateLimitStore,
   rateLimitKey,
   rateLimitKeyPrefix,
   RateLimitStore,
   RedisRateLimitStore,
-} from '../../common/services/rate-limit-store';
+} from '../../common/services/rate-limit-store.js';
 
 /**
  * Result of a rate limit check

package/src/core/modules/better-auth/core-better-auth-signup-validator.service.ts

@@ -1,8 +1,8 @@
 import { BadRequestException, Injectable, Logger } from '@nestjs/common';
 
-import { IBetterAuthSignUpChecksConfig } from '../../common/interfaces/server-options.interface';
-import { ConfigService } from '../../common/services/config.service';
-import { ErrorCode } from '../error-code/error-codes';
+import { IBetterAuthSignUpChecksConfig } from '../../common/interfaces/server-options.interface.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { ErrorCode } from '../error-code/error-codes.js';
 
 /**
  * Default configuration for sign-up checks

package/src/core/modules/better-auth/core-better-auth-user.mapper.ts

@@ -4,7 +4,7 @@ import * as bcrypt from 'bcrypt';
 import { randomBytes, scrypt, ScryptOptions } from 'crypto';
 import { sha256 } from 'js-sha256';
 import { ObjectId } from 'mongodb';
-import { Connection } from 'mongoose';
+import type { Connection } from 'mongoose';
 
 // Promisify Node.js crypto.scrypt
 const scryptPromise = (password: string, salt: string, keylen: number, options: ScryptOptions): Promise<Buffer> => {
@@ -16,9 +16,9 @@ const scryptPromise = (password: string, salt: string, keylen: number, options:
   });
 };
 
-import { RoleEnum } from '../../common/enums/role.enum';
-import { maskEmail } from '../../common/helpers/logging.helper';
-import { legacyCredentialAccountIssuer } from './core-better-auth-account-issuer.helper';
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { maskEmail } from '../../common/helpers/logging.helper.js';
+import { legacyCredentialAccountIssuer } from './core-better-auth-account-issuer.helper.js';
 
 /**
  * Interface for Better-Auth session user
@@ -124,6 +124,17 @@ interface CachedUserData {
   verified: boolean;
 }
 
+/**
+ * Whether an error means the application closed its own database connection under a running query.
+ *
+ * Matched by `name`, not `instanceof`: a project may resolve a second copy of the driver, and the name is
+ * the driver's documented discriminator for both classes.
+ */
+function isClosedConnectionError(error: unknown): boolean {
+  const name = (error as { name?: unknown } | null)?.name;
+  return name === 'MongoClientClosedError' || name === 'MongoTopologyClosedError';
+}
+
 @Injectable()
 export class CoreBetterAuthUserMapper {
   private readonly logger = new Logger(CoreBetterAuthUserMapper.name);
@@ -1122,7 +1133,16 @@ export class CoreBetterAuthUserMapper {
         usersWithIamId,
       };
     } catch (error) {
-      this.logger.error(`Error getting migration status: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      if (isClosedConnectionError(error)) {
+        // The application is shutting down. The boot-time report of CoreLegacyAuthDeprecationInitializer
+        // runs detached on purpose (it must not delay readiness), so a process that closes right after
+        // init() — `docs:ci`, a script, a test — closes the connection under it. Nothing failed.
+        this.logger.debug('Migration status not read: the database connection was closed (application shutting down)');
+      } else {
+        this.logger.error(
+          `Error getting migration status: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+      }
       return {
         canDisableLegacyAuth: false,
         fullyMigratedUsers: 0,

package/src/core/modules/better-auth/core-better-auth-web.helper.ts

@@ -2,8 +2,8 @@ import { Logger } from '@nestjs/common';
 import * as crypto from 'crypto';
 import { Request, Response } from 'express';
 
-import { resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper';
-import { isSessionToken } from './core-better-auth-token.helper';
+import { resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper.js';
+import { isSessionToken } from './core-better-auth-token.helper.js';
 
 /**
  * Cookie names used by Better Auth and nest-server

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

@@ -26,29 +26,30 @@ import {
   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';
-import { RoleEnum } from '../../common/enums/role.enum';
-import { isCookiesEnabled, isExposeTokenInBodyEnabled } from '../../common/helpers/cookies.helper';
-import type { ICookiesConfig } from '../../common/interfaces/server-options.interface';
-import { maskEmail, maskToken } from '../../common/helpers/logging.helper';
-import { ConfigService } from '../../common/services/config.service';
-import { ErrorCode } from '../error-code/error-codes';
+import type { Request, Response } from 'express';
+
+import { Roles } from '../../common/decorators/roles.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { isCookiesEnabled, isExposeTokenInBodyEnabled } from '../../common/helpers/cookies.helper.js';
+import type { ICookiesConfig } from '../../common/interfaces/server-options.interface.js';
+import { maskEmail, maskToken } from '../../common/helpers/logging.helper.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { ErrorCode } from '../error-code/error-codes.js';
 import {
   BetterAuthSignInResponse,
   hasSession,
   hasUser,
   requires2FA,
   sessionTokenFromResponse,
-} from './better-auth.types';
-import { BetterAuthCookieHelper, createCookieHelper } from './core-better-auth-cookie.helper';
-import { CoreBetterAuthEmailVerificationService } from './core-better-auth-email-verification.service';
-import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service';
-import { isJwtShaped, isSessionToken } from './core-better-auth-token.helper';
-import { BetterAuthSessionUser, CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
-import { convertExpressHeaders, sendWebResponse, toWebRequest } from './core-better-auth-web.helper';
-import { CoreBetterAuthService } from './core-better-auth.service';
+} from './better-auth.types.js';
+import { BetterAuthCookieHelper, createCookieHelper } from './core-better-auth-cookie.helper.js';
+import { CoreBetterAuthEmailVerificationService } from './core-better-auth-email-verification.service.js';
+import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service.js';
+import { isJwtShaped, isSessionToken } from './core-better-auth-token.helper.js';
+import { BetterAuthSessionUser, CoreBetterAuthUserMapper } from './core-better-auth-user.mapper.js';
+import { convertExpressHeaders, sendWebResponse, toWebRequest } from './core-better-auth-web.helper.js';
+import { CoreBetterAuthService } from './core-better-auth.service.js';
+import { registerBetterAuthHandlerClass } from './core-better-auth.registry.js';
 
 // ===================================================================================================================
 // Response Models
@@ -1122,3 +1123,5 @@ export class CoreBetterAuthController {
     return this.extractSessionToken(req);
   }
 }
+
+registerBetterAuthHandlerClass(CoreBetterAuthController);

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

@@ -1,11 +1,11 @@
 import { Injectable, Logger, NestMiddleware } from '@nestjs/common';
 import { NextFunction, Request, Response } from 'express';
 
-import { hasApiTokenCredential } from '../api-token/core-api-token.helpers';
-import { isLegacyJwt } from './core-better-auth-token.helper';
-import { BetterAuthSessionUser, CoreBetterAuthUserMapper, MappedUser } from './core-better-auth-user.mapper';
-import { convertExpressHeaders, extractSessionToken } from './core-better-auth-web.helper';
-import { CoreBetterAuthService } from './core-better-auth.service';
+import { hasApiTokenCredential } from '../api-token/core-api-token.helpers.js';
+import { isLegacyJwt } from './core-better-auth-token.helper.js';
+import { BetterAuthSessionUser, CoreBetterAuthUserMapper, MappedUser } from './core-better-auth-user.mapper.js';
+import { convertExpressHeaders, extractSessionToken } from './core-better-auth-web.helper.js';
+import { CoreBetterAuthService } from './core-better-auth.service.js';
 
 /**
  * Extended Express Request with Better-Auth session data

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

@@ -13,41 +13,41 @@ import { APP_GUARD } from '@nestjs/core';
 import { getConnectionToken } from '@nestjs/mongoose';
 import mongoose, { Connection } from 'mongoose';
 
-import { maskEmail } from '../../common/helpers/logging.helper';
-import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface';
-import { BrevoService } from '../../common/services/brevo.service';
-import { ConfigService } from '../../common/services/config.service';
-import { RolesGuardRegistry } from '../auth/guards/roles-guard-registry';
-import { isLegacyEndpointEnabled } from '../auth/helpers/legacy-endpoints.helper';
-import { BetterAuthRolesGuard } from './better-auth-roles.guard';
-import { BetterAuthTokenService } from './better-auth-token.service';
+import { maskEmail } from '../../common/helpers/logging.helper.js';
+import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface.js';
+import { BrevoService } from '../../common/services/brevo.service.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { RolesGuardRegistry } from '../auth/guards/roles-guard-registry.js';
+import { isLegacyEndpointEnabled } from '../auth/helpers/legacy-endpoints.helper.js';
+import { BetterAuthRolesGuard } from './better-auth-roles.guard.js';
+import { BetterAuthTokenService } from './better-auth-token.service.js';
 import {
   AuthEmailCallbackOptions,
   BetterAuthInstance,
   CreateBetterAuthResult,
   createBetterAuthInstance,
   OnPasswordResetCallback,
-} from './better-auth.config';
-import { DefaultBetterAuthResolver } from './better-auth.resolver';
-import { CoreBetterAuthApiMiddleware } from './core-better-auth-api.middleware';
-import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service';
-import { CoreBetterAuthEmailVerificationService } from './core-better-auth-email-verification.service';
-import { CoreBetterAuthRateLimitMiddleware } from './core-better-auth-rate-limit.middleware';
-import { CoreBetterAuthRateLimiter } from './core-better-auth-rate-limiter.service';
-import { revokeApiTokensOfUser } from '../api-token/core-api-token.registry';
-import { getInFlightResetPassword } from './core-better-auth-password-reset.registry';
-import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service';
-import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
-import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
-import { CoreBetterAuthController } from './core-better-auth.controller';
-import { CoreBetterAuthMiddleware } from './core-better-auth.middleware';
+} from './better-auth.config.js';
+import { DefaultBetterAuthResolver } from './better-auth.resolver.js';
+import { CoreBetterAuthApiMiddleware } from './core-better-auth-api.middleware.js';
+import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service.js';
+import { CoreBetterAuthEmailVerificationService } from './core-better-auth-email-verification.service.js';
+import { CoreBetterAuthRateLimitMiddleware } from './core-better-auth-rate-limit.middleware.js';
+import { CoreBetterAuthRateLimiter } from './core-better-auth-rate-limiter.service.js';
+import { revokeApiTokensOfUser } from '../api-token/core-api-token.registry.js';
+import { getInFlightResetPassword } from './core-better-auth-password-reset.registry.js';
+import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service.js';
+import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper.js';
+import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, BETTER_AUTH_INSTANCE } from './core-better-auth.constants.js';
+import { CoreBetterAuthController } from './core-better-auth.controller.js';
+import { CoreBetterAuthMiddleware } from './core-better-auth.middleware.js';
 import {
   getBetterAuthTokenService,
   resetBetterAuthRegistry,
   setBetterAuthTokenService,
-} from './core-better-auth.registry';
-import { CoreBetterAuthResolver } from './core-better-auth.resolver';
-import { CoreBetterAuthService } from './core-better-auth.service';
+} from './core-better-auth.registry.js';
+import { CoreBetterAuthResolver } from './core-better-auth.resolver.js';
+import { CoreBetterAuthService } from './core-better-auth.service.js';
 
 /**
  * @deprecated Import from `./core-better-auth.constants` instead. Re-exported only
@@ -65,7 +65,7 @@ import { CoreBetterAuthService } from './core-better-auth.service';
  * ambiguity error. The mechanical guards are `pnpm run check:swc-tdz` and
  * `tests/unit/better-auth-di-tokens.spec.ts`.
  */
-export { BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
+export { BETTER_AUTH_INSTANCE } from './core-better-auth.constants.js';
 
 /**
  * Options for CoreBetterAuthModule.forRoot()
@@ -439,7 +439,9 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       // Apply session middleware to all routes FIRST
       // This resolves JWT tokens to DB sessions, making req.betterAuthSession available
       // for the API middleware to use when forwarding to Better Auth's native handler.
-      consumer.apply(CoreBetterAuthMiddleware).forRoutes('(.*)'); // New path-to-regexp syntax for wildcard
+      // `{*path}` — path-to-regexp 8's named, optional wildcard: every route, the root included. The old
+      // `(.*)` only worked because Nest's LegacyRouteConverter rewrites it to exactly this.
+      consumer.apply(CoreBetterAuthMiddleware).forRoutes('{*path}');
       CoreBetterAuthModule.logger.debug('CoreBetterAuthMiddleware registered for all routes');
 
       // Apply rate limiting to Better-Auth endpoints only.

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

@@ -20,7 +20,7 @@
  * the cycle.
  */
 
-import type { BetterAuthTokenService } from './better-auth-token.service';
+import type { BetterAuthTokenService } from './better-auth-token.service.js';
 
 let tokenServiceInstance: BetterAuthTokenService | null = null;
 
@@ -51,3 +51,37 @@ export function getBetterAuthTokenService(): BetterAuthTokenService | null {
 export function resetBetterAuthRegistry(): void {
   tokenServiceInstance = null;
 }
+
+/** A class decorated as an IAM controller or resolver; subclasses in projects count as the same handler. */
+type BetterAuthHandlerClass = abstract new (...args: any[]) => unknown;
+
+const handlerClasses = new Set<BetterAuthHandlerClass>();
+
+/**
+ * Records `CoreBetterAuthController` / `CoreBetterAuthResolver`, called once by each file as it is loaded.
+ *
+ * `CoreTenantGuard` skips the tenant check for IAM handlers and has to recognise them without importing them —
+ * tenant and better-auth reach each other. It used a lazy `require()` of both files for that, which exists only
+ * in CommonJS; this registry is the form that works in both module systems. Not cleared by
+ * `resetBetterAuthRegistry()`: the classes are registered when their file loads, which happens once per process.
+ * @internal
+ */
+export function registerBetterAuthHandlerClass(handlerClass: BetterAuthHandlerClass): void {
+  handlerClasses.add(handlerClass);
+}
+
+/**
+ * Whether `handlerClass` is one of the registered IAM handler classes or extends one.
+ * @internal
+ */
+export function isBetterAuthHandlerClass(handlerClass: Function | undefined): boolean {
+  if (!handlerClass) {
+    return false;
+  }
+  for (const base of handlerClasses) {
+    if (handlerClass === base || handlerClass.prototype instanceof base) {
+      return true;
+    }
+  }
+  return false;
+}