@lenne.tech/nest-server 11.43.3 → 12.1.0

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

@@ -10,44 +10,53 @@ import {
   Type,
 } from '@nestjs/common';
 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 { getConnectionToken } from '../../common/persistence/mongo/mongoose-compat.js';
+import type { Connection } from 'mongoose';
+
+import { maskEmail } from '../../common/helpers/logging.helper.js';
+import { getPersistenceRuntime } from '../../common/persistence/persistence-runtime.registry.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 { ROLE_GUARD } from '../auth/guards/role-guard.token.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,
+  buildBetterAuthOptions,
+  type CreateBetterAuthOptions,
   CreateBetterAuthResult,
-  createBetterAuthInstance,
+  instantiateBetterAuth,
   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 { applyBetterAuthSchema } from './better-auth-sql.helper.js';
+import { getBetterAuthSqlStore, setBetterAuthSqlStore } from './core-better-auth-sql.registry.js';
+import { BetterAuthSqlStore, type IamSqlQueryable } from './core-better-auth-sql.store.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';
+import { newObjectId } from '../../common/persistence/mongo/mongoose-compat.js';
+import { requireMongoPackages } from '../../common/persistence/mongo/mongo-packages.js';
 
 /**
  * @deprecated Import from `./core-better-auth.constants` instead. Re-exported only
@@ -65,7 +74,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 +448,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.
@@ -462,6 +473,38 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     }
   }
 
+  /**
+   * Better-Auth on the database the `users` table lives in (one row per user, shared with the user model): on a SQL
+   * source its adapter runs on that source's application pool, and its tables are brought up to date before the
+   * instance exists — Better-Auth validates its schema as it starts.
+   */
+  private static async createInstance(options: CreateBetterAuthOptions): Promise<CreateBetterAuthResult | null> {
+    const storage = await getPersistenceRuntime()?.iamStorage();
+    setBetterAuthSqlStore(undefined);
+    const built = buildBetterAuthOptions({ ...options, sqlPool: storage?.pool });
+    if (!built) {
+      return null;
+    }
+    if (storage) {
+      await applyBetterAuthSchema(built.options, storage);
+    }
+    const result = instantiateBetterAuth(built);
+    if (storage) {
+      setBetterAuthSqlStore(new BetterAuthSqlStore(storage.users, result.instance, storage.pool as IamSqlQueryable));
+    }
+    return result;
+  }
+
+  /** The MongoDB database Better-Auth's adapter runs on, once the connection is up */
+  private static async mongoDatabase(): Promise<unknown> {
+    await this.waitForMongoConnection();
+    const db = requireMongoPackages('Better-Auth on MongoDB').mongoose.connection.db;
+    if (!db) {
+      throw new Error('MongoDB database not available');
+    }
+    return db;
+  }
+
   /**
    * Waits for mongoose connection to be ready using polling
    * This is more reliable than event-based waiting in test environments
@@ -470,6 +513,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   private static async waitForMongoConnection(): Promise<void> {
     const maxAttempts = 60; // 60 attempts * 500ms = 30 seconds max
     const pollInterval = 500;
+    const { mongoose } = requireMongoPackages('Better-Auth on MongoDB (the user model is not routed to a SQL source)');
 
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       // Check if already connected
@@ -685,12 +729,9 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
             // Enable middleware registration
             this.betterAuthEnabled = true;
 
-            await this.waitForMongoConnection();
-
-            const db = mongoose.connection.db;
-            if (!db) {
-              throw new Error('MongoDB database not available');
-            }
+            // On a SQL source Better-Auth runs on that source's pool (createInstance()); MongoDB is neither awaited
+            // nor needed then — a project on PostgreSQL alone has none
+            const db = (await getPersistenceRuntime()?.iamStorage()) ? undefined : await this.mongoDatabase();
 
             this.configServiceInstance = configService;
 
@@ -704,7 +745,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
 
             // Note: Secret validation is now handled in createBetterAuthInstance
             // with fallback to jwt.secret, jwt.refresh.secret, or auto-generation
-            const result = createBetterAuthInstance({
+            const result = await this.createInstance({
               config,
               db,
               fallbackSecrets,
@@ -800,6 +841,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    */
   static reset(): void {
     this.authInstance = null;
+    setBetterAuthSqlStore(undefined);
     this.initialized = false;
     this.initLogged = false;
     this.betterAuthEnabled = false;
@@ -892,12 +934,16 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         // This callback is called by Better-Auth when email is verified
         // Sync nest-server's verified/verifiedAt fields with Better-Auth's emailVerified
         try {
+          const sql = getBetterAuthSqlStore();
           const db = this.mongoConnection?.db;
-          if (db) {
-            const { ObjectId } = await import('mongodb');
+          if (sql) {
+            // One row per user on SQL: Better-Auth's user id is the row's id
+            await sql.updateUser({ id: userId }, { verified: true, verifiedAt: new Date() });
+            this.logger.debug(`Email verified for user ${userId} - synced verified/verifiedAt`);
+          } else if (db) {
             await db
               .collection('users')
-              .updateOne({ _id: new ObjectId(userId) }, { $set: { verified: true, verifiedAt: new Date() } });
+              .updateOne({ _id: newObjectId(userId) }, { $set: { verified: true, verifiedAt: new Date() } });
             this.logger.debug(`Email verified for user ${userId} - synced verified/verifiedAt`);
           } else {
             this.logger.warn(`Cannot sync verifiedAt for user ${userId} - no database connection`);
@@ -1038,7 +1084,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           inject: [getConnectionToken(), CoreBetterAuthEmailVerificationService, ConfigService],
           provide: BETTER_AUTH_INSTANCE,
           useFactory: async (
-            connection: Connection,
+            connection: Connection | null,
             emailVerificationService: CoreBetterAuthEmailVerificationService,
             configService: ConfigService,
           ) => {
@@ -1065,26 +1111,13 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
               serverEnv: options?.serverEnv,
             };
 
-            // Connection is now guaranteed to be established
-            let result: CreateBetterAuthResult | null;
-            const db = connection.db;
-            if (!db) {
-              // Fallback to global mongoose if connection.db is not yet available
-              await this.waitForMongoConnection();
-              const globalDb = mongoose.connection.db;
-              if (!globalDb) {
-                throw new Error('MongoDB database not available');
-              }
-              result = createBetterAuthInstance({
-                ...sharedInstanceOptions,
-                db: globalDb,
-              });
-            } else {
-              result = createBetterAuthInstance({
-                ...sharedInstanceOptions,
-                db,
-              });
-            }
+            // On a SQL source Better-Auth runs on that source's pool; on MongoDB on the injected connection, falling
+            // back to the global mongoose connection while its database is not yet available
+            const sqlStorage = await getPersistenceRuntime()?.iamStorage();
+            const result: CreateBetterAuthResult | null = await this.createInstance({
+              ...sharedInstanceOptions,
+              db: sqlStorage ? undefined : (connection?.db ?? (await this.mongoDatabase())),
+            });
             this.authInstance = result?.instance ?? null;
             this.resolvedCookieDomain = result?.cookieDomain;
 
@@ -1161,7 +1194,12 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         ...(this.shouldRegisterRolesGuardGlobally && !RolesGuardRegistry.isRegistered()
           ? (() => {
               RolesGuardRegistry.markRegistered('CoreBetterAuthModule');
-              return [BetterAuthRolesGuard, { provide: APP_GUARD, useExisting: BetterAuthRolesGuard }];
+              return [
+                BetterAuthRolesGuard,
+                { provide: APP_GUARD, useExisting: BetterAuthRolesGuard },
+                // How CoreTenantGuard reaches it
+                { provide: ROLE_GUARD, useExisting: BetterAuthRolesGuard },
+              ];
             })()
           : []),
       ],

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

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

@@ -2,10 +2,10 @@ import { BadRequestException, Logger, Optional, UnauthorizedException } from '@n
 import { Args, Context, Mutation, Query, Resolver } from '@nestjs/graphql';
 import { Request, Response } from 'express';
 
-import { Roles } from '../../common/decorators/roles.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
-import { maskEmail } from '../../common/helpers/logging.helper';
-import { ErrorCode } from '../error-code/error-codes';
+import { Roles } from '../../common/decorators/roles.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { maskEmail } from '../../common/helpers/logging.helper.js';
+import { ErrorCode } from '../error-code/error-codes.js';
 import {
   BetterAuth2FAResponse,
   BetterAuthSignInResponse,
@@ -14,10 +14,10 @@ import {
   hasUser,
   requires2FA,
   sessionTokenFromResponse,
-} from './better-auth.types';
-import { CoreBetterAuthAuthModel } from './core-better-auth-auth.model';
-import { CoreBetterAuthEmailVerificationService } from './core-better-auth-email-verification.service';
-import { CoreBetterAuthMigrationStatusModel } from './core-better-auth-migration-status.model';
+} from './better-auth.types.js';
+import { CoreBetterAuthAuthModel } from './core-better-auth-auth.model.js';
+import { CoreBetterAuthEmailVerificationService } from './core-better-auth-email-verification.service.js';
+import { CoreBetterAuthMigrationStatusModel } from './core-better-auth-migration-status.model.js';
 import {
   CoreBetterAuth2FASetupModel,
   CoreBetterAuthFeaturesModel,
@@ -25,11 +25,12 @@ import {
   CoreBetterAuthPasskeyModel,
   CoreBetterAuthSessionModel,
   CoreBetterAuthUserModel,
-} from './core-better-auth-models';
-import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service';
-import { BetterAuthSessionUser, CoreBetterAuthUserMapper, MappedUser } from './core-better-auth-user.mapper';
-import { convertExpressHeaders } from './core-better-auth-web.helper';
-import { CoreBetterAuthService } from './core-better-auth.service';
+} from './core-better-auth-models.js';
+import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service.js';
+import { BetterAuthSessionUser, CoreBetterAuthUserMapper, MappedUser } from './core-better-auth-user.mapper.js';
+import { convertExpressHeaders } from './core-better-auth-web.helper.js';
+import { CoreBetterAuthService } from './core-better-auth.service.js';
+import { registerBetterAuthHandlerClass } from './core-better-auth.registry.js';
 
 /**
  * Abstract GraphQL Resolver for Better-Auth operations
@@ -957,3 +958,5 @@ export class CoreBetterAuthResolver {
     };
   }
 }
+
+registerBetterAuthHandlerClass(CoreBetterAuthResolver);