@lenne.tech/nest-server 11.9.0 → 11.10.1

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

@@ -4,18 +4,6 @@ import { Request, Response } from 'express';
 
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
-import { BetterAuthAuthModel } from './better-auth-auth.model';
-import { BetterAuthMigrationStatusModel } from './better-auth-migration-status.model';
-import {
-  BetterAuth2FASetupModel,
-  BetterAuthFeaturesModel,
-  BetterAuthPasskeyChallengeModel,
-  BetterAuthPasskeyModel,
-  BetterAuthSessionModel,
-  BetterAuthUserModel,
-} from './better-auth-models';
-import { BetterAuthSessionUser, BetterAuthUserMapper, MappedUser } from './better-auth-user.mapper';
-import { BetterAuthService } from './better-auth.service';
 import {
   BetterAuth2FAResponse,
   BetterAuthSignInResponse,
@@ -24,6 +12,18 @@ import {
   hasUser,
   requires2FA,
 } from './better-auth.types';
+import { CoreBetterAuthAuthModel } from './core-better-auth-auth.model';
+import { CoreBetterAuthMigrationStatusModel } from './core-better-auth-migration-status.model';
+import {
+  CoreBetterAuth2FASetupModel,
+  CoreBetterAuthFeaturesModel,
+  CoreBetterAuthPasskeyChallengeModel,
+  CoreBetterAuthPasskeyModel,
+  CoreBetterAuthSessionModel,
+  CoreBetterAuthUserModel,
+} from './core-better-auth-models';
+import { BetterAuthSessionUser, CoreBetterAuthUserMapper, MappedUser } from './core-better-auth-user.mapper';
+import { CoreBetterAuthService } from './core-better-auth.service';
 
 /**
  * Abstract GraphQL Resolver for Better-Auth operations
@@ -38,11 +38,11 @@ import {
  * @example
  * ```typescript
  * // In your project's better-auth.resolver.ts
- * @Resolver(() => BetterAuthAuthModel)
+ * @Resolver(() => CoreBetterAuthAuthModel)
  * export class BetterAuthResolver extends CoreBetterAuthResolver {
  *   constructor(
- *     betterAuthService: BetterAuthService,
- *     userMapper: BetterAuthUserMapper,
+ *     betterAuthService: CoreBetterAuthService,
+ *     userMapper: CoreBetterAuthUserMapper,
  *     private readonly emailService: EmailService,
  *   ) {
  *     super(betterAuthService, userMapper);
@@ -59,14 +59,14 @@ import {
  * }
  * ```
  */
-@Resolver(() => BetterAuthAuthModel, { isAbstract: true })
+@Resolver(() => CoreBetterAuthAuthModel, { isAbstract: true })
 @Roles(RoleEnum.ADMIN)
 export class CoreBetterAuthResolver {
   protected readonly logger = new Logger(CoreBetterAuthResolver.name);
 
   constructor(
-    protected readonly betterAuthService: BetterAuthService,
-    protected readonly userMapper: BetterAuthUserMapper,
+    protected readonly betterAuthService: CoreBetterAuthService,
+    protected readonly userMapper: CoreBetterAuthUserMapper,
   ) {}
 
   // ===========================================================================
@@ -76,12 +76,12 @@ export class CoreBetterAuthResolver {
   /**
    * Get current Better-Auth session
    */
-  @Query(() => BetterAuthSessionModel, {
+  @Query(() => CoreBetterAuthSessionModel, {
     description: 'Get current Better-Auth session',
     nullable: true,
   })
   @Roles(RoleEnum.S_USER)
-  async betterAuthSession(@Context() ctx: { req: Request }): Promise<BetterAuthSessionModel | null> {
+  async betterAuthSession(@Context() ctx: { req: Request }): Promise<CoreBetterAuthSessionModel | null> {
     if (!this.betterAuthService.isEnabled()) {
       return null;
     }
@@ -116,9 +116,9 @@ export class CoreBetterAuthResolver {
   /**
    * Get enabled Better-Auth features
    */
-  @Query(() => BetterAuthFeaturesModel, { description: 'Get enabled Better-Auth features' })
+  @Query(() => CoreBetterAuthFeaturesModel, { description: 'Get enabled Better-Auth features' })
   @Roles(RoleEnum.S_EVERYONE)
-  betterAuthFeatures(): BetterAuthFeaturesModel {
+  betterAuthFeatures(): CoreBetterAuthFeaturesModel {
     return {
       enabled: this.betterAuthService.isEnabled(),
       jwt: this.betterAuthService.isJwtEnabled(),
@@ -164,11 +164,11 @@ export class CoreBetterAuthResolver {
    * currently be removed because CoreModule.forRoot requires AuthService
    * for GraphQL Subscriptions authentication.
    */
-  @Query(() => BetterAuthMigrationStatusModel, {
+  @Query(() => CoreBetterAuthMigrationStatusModel, {
     description: 'Get migration status from Legacy Auth to Better-Auth (IAM) - Admin only',
   })
   @Roles(RoleEnum.ADMIN)
-  async betterAuthMigrationStatus(): Promise<BetterAuthMigrationStatusModel> {
+  async betterAuthMigrationStatus(): Promise<CoreBetterAuthMigrationStatusModel> {
     const status = await this.userMapper.getMigrationStatus();
     return status;
   }
@@ -188,7 +188,7 @@ export class CoreBetterAuthResolver {
    *
    * Override this method to add custom pre/post sign-in logic.
    */
-  @Mutation(() => BetterAuthAuthModel, {
+  @Mutation(() => CoreBetterAuthAuthModel, {
     description: 'Sign in via Better-Auth (email/password)',
   })
   @Roles(RoleEnum.S_EVERYONE)
@@ -197,7 +197,7 @@ export class CoreBetterAuthResolver {
     @Args('password') password: string,
     // eslint-disable-next-line unused-imports/no-unused-vars -- Reserved for future cookie/session handling
     @Context() _ctx: { req: Request; res: Response },
-  ): Promise<BetterAuthAuthModel> {
+  ): Promise<CoreBetterAuthAuthModel> {
     this.ensureEnabled();
 
     const api = this.betterAuthService.getApi();
@@ -219,9 +219,9 @@ export class CoreBetterAuthResolver {
   protected async attemptSignIn(
     email: string,
     password: string,
-    api: ReturnType<BetterAuthService['getApi']>,
+    api: ReturnType<CoreBetterAuthService['getApi']>,
     allowMigration: boolean,
-  ): Promise<BetterAuthAuthModel> {
+  ): Promise<CoreBetterAuthAuthModel> {
     try {
       // Try sign-in with original password first (for native IAM users)
       const response = (await api!.signInEmail({
@@ -300,8 +300,8 @@ export class CoreBetterAuthResolver {
   private async attemptSignInDirect(
     email: string,
     password: string,
-    api: ReturnType<BetterAuthService['getApi']>,
-  ): Promise<BetterAuthAuthModel> {
+    api: ReturnType<CoreBetterAuthService['getApi']>,
+  ): Promise<CoreBetterAuthAuthModel> {
     const response = (await api!.signInEmail({
       body: { email, password },
     })) as BetterAuthSignInResponse | null;
@@ -334,7 +334,7 @@ export class CoreBetterAuthResolver {
    *
    * Override this method to add custom pre/post sign-up logic (e.g., sending welcome emails).
    */
-  @Mutation(() => BetterAuthAuthModel, {
+  @Mutation(() => CoreBetterAuthAuthModel, {
     description: 'Sign up via Better-Auth (email/password)',
   })
   @Roles(RoleEnum.S_EVERYONE)
@@ -342,7 +342,7 @@ export class CoreBetterAuthResolver {
     @Args('email') email: string,
     @Args('password') password: string,
     @Args('name', { nullable: true }) name?: string,
-  ): Promise<BetterAuthAuthModel> {
+  ): Promise<CoreBetterAuthAuthModel> {
     this.ensureEnabled();
 
     const api = this.betterAuthService.getApi();
@@ -417,14 +417,14 @@ export class CoreBetterAuthResolver {
   /**
    * Verify 2FA code
    */
-  @Mutation(() => BetterAuthAuthModel, {
+  @Mutation(() => CoreBetterAuthAuthModel, {
     description: 'Verify 2FA code during sign-in',
   })
   @Roles(RoleEnum.S_EVERYONE)
   async betterAuthVerify2FA(
     @Args('code') code: string,
     @Context() ctx: { req: Request },
-  ): Promise<BetterAuthAuthModel> {
+  ): Promise<CoreBetterAuthAuthModel> {
     this.ensureEnabled();
 
     if (!this.betterAuthService.isTwoFactorEnabled()) {
@@ -483,14 +483,14 @@ export class CoreBetterAuthResolver {
    * Enable 2FA for the current user
    * Returns TOTP URI for QR code generation and backup codes
    */
-  @Mutation(() => BetterAuth2FASetupModel, {
+  @Mutation(() => CoreBetterAuth2FASetupModel, {
     description: 'Enable 2FA for the current user',
   })
   @Roles(RoleEnum.S_USER)
   async betterAuthEnable2FA(
     @Args('password') password: string,
     @Context() ctx: { req: Request },
-  ): Promise<BetterAuth2FASetupModel> {
+  ): Promise<CoreBetterAuth2FASetupModel> {
     this.ensureEnabled();
 
     if (!this.betterAuthService.isTwoFactorEnabled()) {
@@ -628,11 +628,11 @@ export class CoreBetterAuthResolver {
    * Get passkey registration challenge
    * Returns the challenge data needed for WebAuthn registration
    */
-  @Mutation(() => BetterAuthPasskeyChallengeModel, {
+  @Mutation(() => CoreBetterAuthPasskeyChallengeModel, {
     description: 'Get passkey registration challenge for WebAuthn',
   })
   @Roles(RoleEnum.S_USER)
-  async betterAuthGetPasskeyChallenge(@Context() ctx: { req: Request }): Promise<BetterAuthPasskeyChallengeModel> {
+  async betterAuthGetPasskeyChallenge(@Context() ctx: { req: Request }): Promise<CoreBetterAuthPasskeyChallengeModel> {
     this.ensureEnabled();
 
     if (!this.betterAuthService.isPasskeyEnabled()) {
@@ -672,12 +672,12 @@ export class CoreBetterAuthResolver {
   /**
    * List passkeys for the current user
    */
-  @Query(() => [BetterAuthPasskeyModel], {
+  @Query(() => [CoreBetterAuthPasskeyModel], {
     description: 'List passkeys for the current user',
     nullable: true,
   })
   @Roles(RoleEnum.S_USER)
-  async betterAuthListPasskeys(@Context() ctx: { req: Request }): Promise<BetterAuthPasskeyModel[] | null> {
+  async betterAuthListPasskeys(@Context() ctx: { req: Request }): Promise<CoreBetterAuthPasskeyModel[] | null> {
     if (!this.betterAuthService.isEnabled() || !this.betterAuthService.isPasskeyEnabled()) {
       return null;
     }
@@ -809,9 +809,9 @@ export class CoreBetterAuthResolver {
   }
 
   /**
-   * Map MappedUser to BetterAuthUserModel
+   * Map MappedUser to CoreBetterAuthUserModel
    */
-  protected mapToUserModel(user: MappedUser): BetterAuthUserModel {
+  protected mapToUserModel(user: MappedUser): CoreBetterAuthUserModel {
     return {
       email: user.email,
       emailVerified: user.emailVerified,

package/src/core/modules/better-auth/{better-auth.service.ts → core-better-auth.service.ts}

@@ -4,11 +4,12 @@ import { Request } from 'express';
 import { importJWK, jwtVerify } from 'jose';
 import { Connection } from 'mongoose';
 
+import { isProduction, maskCookieHeader, maskEmail, maskToken } from '../../common/helpers/logging.helper';
 import { IBetterAuth } from '../../common/interfaces/server-options.interface';
 import { ConfigService } from '../../common/services/config.service';
-import { BetterAuthSessionUser } from './better-auth-user.mapper';
 import { BetterAuthInstance } from './better-auth.config';
-import { BETTER_AUTH_INSTANCE } from './better-auth.module';
+import { BetterAuthSessionUser } from './core-better-auth-user.mapper';
+import { BETTER_AUTH_INSTANCE } from './core-better-auth.module';
 
 /**
  * Result of a session validation
@@ -24,7 +25,7 @@ export interface SessionResult {
 }
 
 /**
- * BetterAuthService provides a NestJS-friendly wrapper around the better-auth instance.
+ * CoreBetterAuthService provides a NestJS-friendly wrapper around the better-auth instance.
  *
  * This service:
  * - Provides access to the better-auth API
@@ -35,7 +36,7 @@ export interface SessionResult {
  * ```typescript
  * @Injectable()
  * export class MyService {
- *   constructor(private readonly betterAuthService: BetterAuthService) {}
+ *   constructor(private readonly betterAuthService: CoreBetterAuthService) {}
  *
  *   async doSomething() {
  *     if (this.betterAuthService.isEnabled()) {
@@ -52,8 +53,9 @@ export interface SessionResult {
 export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
 
 @Injectable()
-export class BetterAuthService {
-  private readonly logger = new Logger(BetterAuthService.name);
+export class CoreBetterAuthService {
+  private readonly logger = new Logger(CoreBetterAuthService.name);
+  private readonly isProd = isProduction();
   private readonly config: IBetterAuth;
 
   constructor(
@@ -304,15 +306,28 @@ export class BetterAuthService {
         }
       }
 
+      // Debug: Log the cookie header being sent to api.getSession (masked for security)
+      if (!this.isProd) {
+        const cookieHeader = headers.get('cookie');
+        this.logger.debug(`getSession called with cookies: ${maskCookieHeader(cookieHeader)}`);
+      }
+
       const response = await api.getSession({ headers });
 
+      // Debug: Log the response from api.getSession
+      if (!this.isProd) {
+        this.logger.debug(`getSession response: ${JSON.stringify(response)?.substring(0, 200)}`);
+      }
+
       if (response && typeof response === 'object' && 'user' in response) {
         return response as SessionResult;
       }
 
       return { session: null, user: null };
     } catch (error) {
-      this.logger.debug(`getSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      if (!this.isProd) {
+        this.logger.debug(`getSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      }
       return { session: null, user: null };
     }
   }
@@ -355,7 +370,9 @@ export class BetterAuthService {
       await api.signOut({ headers });
       return true;
     } catch (error) {
-      this.logger.debug(`revokeSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      if (!this.isProd) {
+        this.logger.debug(`revokeSession error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      }
       return false;
     }
   }
@@ -416,59 +433,86 @@ export class BetterAuthService {
    * @returns Session and user data, or null if not found/expired
    */
   async getSessionByToken(token: string): Promise<SessionResult> {
-    if (!this.isEnabled() || !this.connection) {
+    if (!this.isEnabled() || !this.connection?.db) {
       return { session: null, user: null };
     }
 
     try {
       const db = this.connection.db;
-      if (!db) {
-        return { session: null, user: null };
-      }
-
       const sessionsCollection = db.collection('session');
-      // Better-Auth is configured to use 'users' (plural) as the model name
-      // This matches the existing Legacy users collection for migration compatibility
-      const usersCollection = db.collection('users');
 
-      // Find session by token
-      const session = await sessionsCollection.findOne({ token });
-
-      if (!session) {
+      // Use aggregation pipeline for single-query lookup with automatic userId type handling
+      // This handles both ObjectId and string userId formats efficiently
+      const results = await sessionsCollection
+        .aggregate([
+          // Match session by token
+          { $match: { token } },
+          // Join with users collection - handles both ObjectId and string userId
+          {
+            $lookup: {
+              as: 'userDoc',
+              from: 'users',
+              let: { sessionUserId: '$userId' },
+              pipeline: [
+                {
+                  $match: {
+                    $expr: {
+                      $or: [
+                        // Match by _id (ObjectId comparison)
+                        { $eq: ['$_id', '$$sessionUserId'] },
+                        // Match by _id with string conversion
+                        { $eq: [{ $toString: '$_id' }, { $toString: '$$sessionUserId' }] },
+                        // Match by id field (string field)
+                        { $eq: ['$id', { $toString: '$$sessionUserId' }] },
+                      ],
+                    },
+                  },
+                },
+              ],
+            },
+          },
+          // Unwind user document (results in null if no match)
+          { $unwind: { path: '$userDoc', preserveNullAndEmptyArrays: true } },
+          // Project final result
+          { $limit: 1 },
+        ])
+        .toArray();
+
+      const result = results[0];
+
+      if (!result) {
+        if (!this.isProd) {
+          this.logger.debug(`getSessionByToken: session not found for token ${maskToken(token)}`);
+        }
         return { session: null, user: null };
       }
 
       // Check if session is expired
-      if (session.expiresAt && new Date(session.expiresAt) < new Date()) {
+      if (result.expiresAt && new Date(result.expiresAt) < new Date()) {
+        if (!this.isProd) {
+          this.logger.debug(`getSessionByToken: session expired`);
+        }
         return { session: null, user: null };
       }
 
-      // Get user from the user collection
-      // Better-Auth stores userId as a string, try both string id and ObjectId
-      const { ObjectId } = require('mongodb');
-
-      let user = await usersCollection.findOne({ id: session.userId });
+      const user = result.userDoc;
       if (!user) {
-        // Try with ObjectId conversion
-        try {
-          const objectId = new ObjectId(session.userId);
-          user = await usersCollection.findOne({ _id: objectId });
-        } catch {
-          // userId might not be a valid ObjectId, try string match
-          user = await usersCollection.findOne({ _id: session.userId });
+        if (!this.isProd) {
+          this.logger.debug(`getSessionByToken: user not found for session`);
         }
+        return { session: null, user: null };
       }
 
-      if (!user) {
-        return { session: null, user: null };
+      if (!this.isProd) {
+        this.logger.debug(`getSessionByToken: found session for user ${maskEmail(user.email)}`);
       }
 
       return {
         session: {
-          expiresAt: session.expiresAt,
-          id: session.id || session._id?.toString(),
-          userId: session.userId?.toString(),
-          ...session,
+          expiresAt: result.expiresAt,
+          id: result.id || result._id?.toString(),
+          token: result.token,
+          userId: result.userId?.toString(),
         },
         user: {
           email: user.email,
@@ -478,7 +522,9 @@ export class BetterAuthService {
         },
       };
     } catch (error) {
-      this.logger.debug(`getSessionByToken error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      if (!this.isProd) {
+        this.logger.debug(`getSessionByToken error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      }
       return { session: null, user: null };
     }
   }

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

@@ -1,5 +1,5 @@
 /**
- * BetterAuth Module exports
+ * CoreBetterAuth Module exports
  *
  * Provides integration with the better-auth authentication framework.
  * This module supports:
@@ -11,23 +11,30 @@
  * - Rate limiting for brute-force protection
  * - Parallel operation with Legacy Auth (bcrypt compatible)
  *
+ * Naming Convention (consistent with other Core modules):
+ * - Core* prefix: Base classes for extension (CoreBetterAuthService, CoreBetterAuthModule, etc.)
+ * - Default* prefix: Default implementations (DefaultBetterAuthResolver)
+ * - No prefix in consuming projects: Your project's implementations (BetterAuthService, BetterAuthResolver)
+ *
  * Extension points:
  * - CoreBetterAuthController: Abstract controller for REST extension
  * - CoreBetterAuthResolver: Abstract resolver for GraphQL extension (isAbstract: true)
- * - BetterAuthController/BetterAuthResolver: Default implementations
+ * - DefaultBetterAuthResolver: Default resolver implementation (use as fallback)
  */
 
-export * from './better-auth-auth.model';
-export * from './better-auth-migration-status.model';
-export * from './better-auth-models';
-export * from './better-auth-rate-limit.middleware';
-export * from './better-auth-rate-limiter.service';
-export * from './better-auth-user.mapper';
 export * from './better-auth.config';
-export * from './better-auth.middleware';
-export * from './better-auth.module';
 export * from './better-auth.resolver';
-export * from './better-auth.service';
 export * from './better-auth.types';
+export * from './core-better-auth-api.middleware';
+export * from './core-better-auth-auth.model';
+export * from './core-better-auth-migration-status.model';
+export * from './core-better-auth-models';
+export * from './core-better-auth-rate-limit.middleware';
+export * from './core-better-auth-rate-limiter.service';
+export * from './core-better-auth-user.mapper';
+export * from './core-better-auth-web.helper';
 export * from './core-better-auth.controller';
+export * from './core-better-auth.middleware';
+export * from './core-better-auth.module';
 export * from './core-better-auth.resolver';
+export * from './core-better-auth.service';

package/src/core/modules/error-code/INTEGRATION-CHECKLIST.md

@@ -273,12 +273,15 @@ const orderCode = ProjectErrorCode.ORDER_NOT_FOUND;  // '#PROJ_0001: Order not f
 ```json
 {
   "errors": {
-    "LTNS_0001": "Benutzer mit E-Mail {email} wurde nicht gefunden.",
+    "LTNS_0001": "Benutzer wurde nicht gefunden.",
+    "LTNS_0100": "Sie sind nicht angemeldet.",
     "PROJ_0001": "Bestellung mit ID {orderId} wurde nicht gefunden."
   }
 }
 ```
 
+> **Note:** Core LTNS_* translations are user-friendly messages without placeholders. Project-specific errors (PROJ_*) may include placeholders like `{orderId}` if defined in your `ProjectErrors` registry.
+
 ---
 
 ## Detailed Documentation

package/src/core/modules/error-code/core-error-code.controller.ts

@@ -33,8 +33,9 @@ export class CoreErrorCodeController {
    * ```json
    * {
    *   "errors": {
-   *     "LTNS_0001": "Benutzer mit E-Mail {email} wurde nicht gefunden.",
-   *     "LTNS_0002": "Das eingegebene Passwort ist ungültig."
+   *     "LTNS_0001": "Benutzer wurde nicht gefunden.",
+   *     "LTNS_0002": "Das eingegebene Passwort ist ungültig.",
+   *     "LTNS_0100": "Sie sind nicht angemeldet."
    *   }
    * }
    * ```

package/src/core/modules/user/interfaces/core-user-service-options.interface.ts

@@ -1,4 +1,4 @@
-import { BetterAuthUserMapper } from '../../better-auth/better-auth-user.mapper';
+import { CoreBetterAuthUserMapper } from '../../better-auth/core-better-auth-user.mapper';
 
 /**
  * Optional configuration for CoreUserService
@@ -8,8 +8,8 @@ import { BetterAuthUserMapper } from '../../better-auth/better-auth-user.mapper'
  */
 export interface CoreUserServiceOptions {
   /**
-   * Optional BetterAuthUserMapper for syncing between Legacy and IAM auth systems.
+   * Optional CoreBetterAuthUserMapper for syncing between Legacy and IAM auth systems.
    * When provided, email changes and user deletions are automatically synced.
    */
-  betterAuthUserMapper?: BetterAuthUserMapper;
+  betterAuthUserMapper?: CoreBetterAuthUserMapper;
 }

package/src/core.module.ts

@@ -19,9 +19,9 @@ import { EmailService } from './core/common/services/email.service';
 import { MailjetService } from './core/common/services/mailjet.service';
 import { ModelDocService } from './core/common/services/model-doc.service';
 import { TemplateService } from './core/common/services/template.service';
-import { BetterAuthUserMapper } from './core/modules/better-auth/better-auth-user.mapper';
-import { BetterAuthModule } from './core/modules/better-auth/better-auth.module';
-import { BetterAuthService } from './core/modules/better-auth/better-auth.service';
+import { CoreBetterAuthUserMapper } from './core/modules/better-auth/core-better-auth-user.mapper';
+import { CoreBetterAuthModule } from './core/modules/better-auth/core-better-auth.module';
+import { CoreBetterAuthService } from './core/modules/better-auth/core-better-auth.service';
 import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
 
@@ -86,8 +86,8 @@ export class CoreModule implements NestModule {
    *
    * **Requirements:**
    * - Configure `betterAuth` in your config (enabled by default)
-   * - Create BetterAuthModule, Resolver, and Controller in your project
-   * - Inject BetterAuthUserMapper in UserService
+   * - Create CoreBetterAuthModule, Resolver, and Controller in your project
+   * - Inject CoreBetterAuthUserMapper in UserService
    *
    * ### Legacy + IAM Signature (For existing projects)
    *
@@ -246,8 +246,8 @@ export class CoreModule implements NestModule {
       imports.push(CoreHealthCheckModule);
     }
 
-    // Add BetterAuthModule based on mode
-    // IAM-only mode: Always register BetterAuthModule (required for subscription auth)
+    // Add CoreBetterAuthModule based on mode
+    // IAM-only mode: Always register CoreBetterAuthModule (required for subscription auth)
     // Legacy mode: Only register if autoRegister is explicitly true
     // betterAuth can be: boolean | IBetterAuth | undefined
     const betterAuthConfig = config.betterAuth;
@@ -258,7 +258,7 @@ export class CoreModule implements NestModule {
     if (isBetterAuthEnabled) {
       if (isIamOnlyMode || isAutoRegister) {
         imports.push(
-          BetterAuthModule.forRoot({
+          CoreBetterAuthModule.forRoot({
             config: betterAuthConfig === true ? {} : betterAuthConfig || {},
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
@@ -289,14 +289,14 @@ export class CoreModule implements NestModule {
   /**
    * Build GraphQL driver configuration for IAM-only mode
    *
-   * Uses BetterAuthService for subscription authentication via JWT tokens.
+   * Uses CoreBetterAuthService for subscription authentication via JWT tokens.
    * This is the recommended mode for new projects.
    */
   private static buildIamOnlyGraphQlDriver(cors: object, options: Partial<IServerOptions>) {
     return {
-      imports: [BetterAuthModule],
-      inject: [BetterAuthService, BetterAuthUserMapper],
-      useFactory: async (betterAuthService: BetterAuthService, userMapper: BetterAuthUserMapper) =>
+      imports: [CoreBetterAuthModule],
+      inject: [CoreBetterAuthService, CoreBetterAuthUserMapper],
+      useFactory: async (betterAuthService: CoreBetterAuthService, userMapper: CoreBetterAuthUserMapper) =>
         Object.assign(
           {
             autoSchemaFile: 'schema.gql',

package/src/index.ts

@@ -36,6 +36,7 @@ export * from './core/common/helpers/filter.helper';
 export * from './core/common/helpers/graphql.helper';
 export * from './core/common/helpers/gridfs.helper';
 export * from './core/common/helpers/input.helper';
+export * from './core/common/helpers/logging.helper';
 export * from './core/common/helpers/model.helper';
 export * from './core/common/helpers/register-enum.helper';
 export * from './core/common/helpers/scim.helper';

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

@@ -3,9 +3,9 @@ import { Controller } from '@nestjs/common';
 import { Roles } from '../../../core/common/decorators/roles.decorator';
 import { RoleEnum } from '../../../core/common/enums/role.enum';
 import { ConfigService } from '../../../core/common/services/config.service';
-import { BetterAuthUserMapper } from '../../../core/modules/better-auth/better-auth-user.mapper';
-import { BetterAuthService } from '../../../core/modules/better-auth/better-auth.service';
+import { CoreBetterAuthUserMapper } from '../../../core/modules/better-auth/core-better-auth-user.mapper';
 import { CoreBetterAuthController } from '../../../core/modules/better-auth/core-better-auth.controller';
+import { CoreBetterAuthService } from '../../../core/modules/better-auth/core-better-auth.service';
 
 /**
  * Server BetterAuth REST Controller
@@ -32,8 +32,8 @@ import { CoreBetterAuthController } from '../../../core/modules/better-auth/core
 @Roles(RoleEnum.ADMIN)
 export class BetterAuthController extends CoreBetterAuthController {
   constructor(
-    protected override readonly betterAuthService: BetterAuthService,
-    protected override readonly userMapper: BetterAuthUserMapper,
+    protected override readonly betterAuthService: CoreBetterAuthService,
+    protected override readonly userMapper: CoreBetterAuthUserMapper,
     protected override readonly configService: ConfigService,
   ) {
     super(betterAuthService, userMapper, configService);

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

@@ -1,7 +1,7 @@
 import { DynamicModule, Module } from '@nestjs/common';
 
 import { IBetterAuth } from '../../../core/common/interfaces/server-options.interface';
-import { BetterAuthModule as CoreBetterAuthModule } from '../../../core/modules/better-auth/better-auth.module';
+import { CoreBetterAuthModule } from '../../../core/modules/better-auth/core-better-auth.module';
 import { BetterAuthController } from './better-auth.controller';
 import { BetterAuthResolver } from './better-auth.resolver';