@lenne.tech/nest-server 11.20.1 → 11.21.1

package/src/core/common/plugins/mongoose-tenant.plugin.ts

@@ -1,3 +1,5 @@
+import { ForbiddenException } from '@nestjs/common';
+
 import { ConfigService } from '../services/config.service';
 import { RequestContext } from '../services/request-context.service';
 
@@ -15,18 +17,21 @@ import { RequestContext } from '../services/request-context.service';
  * - New documents get tenantId set automatically from context
  * - Aggregates get a $match stage prepended
  *
+ * **Filter modes:**
+ * - X-Tenant-Id header set → `{ tenantId: headerValue }` (single tenant)
+ * - No header + authenticated user → `{ tenantId: { $in: userTenantIds } }` (all user's tenants)
+ * - No header + no user → no filter (public/system routes)
+ *
  * **No filter applied when:**
  * - No RequestContext (system operations, cron jobs, migrations)
  * - `bypassTenantGuard` is active (via `RequestContext.runWithBypassTenantGuard()`)
  * - Schema's model name is in `excludeSchemas` config
- * - No user on request (public endpoints)
- *
- * **User without tenantId:**
- * - Filters by `{ tenantId: null }` — sees only data without tenant assignment
- * - Falsy values (undefined, null, empty string '') are all treated as "no tenant"
  */
 export function mongooseTenantPlugin(schema) {
-  // Only activate on schemas with a tenantId path
+  // Only activate on schemas with a tenantId path.
+  // CoreTenantMemberModel uses 'tenant' (not 'tenantId') intentionally, so this check
+  // excludes it at registration time. Additionally, 'TenantMember' is auto-added to
+  // excludeSchemas in CoreModule as defense-in-depth (see shouldBypass()).
   if (!schema.path('tenantId')) {
     return;
   }
@@ -54,22 +59,21 @@ export function mongooseTenantPlugin(schema) {
     schema.pre(hookName, function () {
       // Query hooks: `this` is a Mongoose Query — modelName is on `this.model`
       const modelName = this.model?.modelName;
-      const tenantId = resolveTenantId(modelName);
-      if (tenantId !== undefined) {
-        this.where({ tenantId });
+      const filter = resolveTenantFilter(modelName);
+      if (filter !== undefined) {
+        this.where(filter);
       }
     });
   }
 
   // === Save: set tenantId automatically on new documents ===
   // Intentional asymmetry: writes only set tenantId when truthy (not null).
-  // A user without tenantId creates "unassigned" documents, which the null-filter
-  // in query hooks will still make visible to them on reads.
+  // Only uses single tenantId from header — tenantIds array is for reads only.
   schema.pre('save', function () {
     if (this.isNew && !this['tenantId']) {
       // Document hooks: `this` is the document instance — modelName is on the constructor (the Model class)
       const modelName = (this.constructor as any).modelName;
-      const tenantId = resolveTenantId(modelName);
+      const tenantId = resolveSingleTenantId(modelName);
       if (tenantId) {
         this['tenantId'] = tenantId;
       }
@@ -80,7 +84,7 @@ export function mongooseTenantPlugin(schema) {
   schema.pre('insertMany', function (docs: any[]) {
     // Model-level hooks: `this` is the Model class itself — modelName is a direct property
     const modelName = this.modelName;
-    const tenantId = resolveTenantId(modelName);
+    const tenantId = resolveSingleTenantId(modelName);
     if (tenantId && Array.isArray(docs)) {
       for (const doc of docs) {
         if (!doc.tenantId) {
@@ -94,25 +98,27 @@ export function mongooseTenantPlugin(schema) {
   schema.pre('bulkWrite', function (ops: any[]) {
     // Model-level hooks: `this` is the Model class itself — modelName is a direct property
     const modelName = this.modelName;
-    const tenantId = resolveTenantId(modelName);
-    if (tenantId === undefined) return;
+    const filter = resolveTenantFilter(modelName);
+    if (filter === undefined) return;
+
+    const tenantId = resolveSingleTenantId(modelName);
 
     for (const op of ops) {
       if ('insertOne' in op) {
-        // Auto-set tenantId on insert (only if truthy, consistent with save hook)
+        // Auto-set tenantId on insert (only single tenantId, consistent with save hook)
         if (tenantId && !op.insertOne.document.tenantId) {
           op.insertOne.document.tenantId = tenantId;
         }
       } else if ('updateOne' in op) {
-        op.updateOne.filter = { ...op.updateOne.filter, tenantId };
+        op.updateOne.filter = { ...op.updateOne.filter, ...filter };
       } else if ('updateMany' in op) {
-        op.updateMany.filter = { ...op.updateMany.filter, tenantId };
+        op.updateMany.filter = { ...op.updateMany.filter, ...filter };
       } else if ('replaceOne' in op) {
-        op.replaceOne.filter = { ...op.replaceOne.filter, tenantId };
+        op.replaceOne.filter = { ...op.replaceOne.filter, ...filter };
       } else if ('deleteOne' in op) {
-        op.deleteOne.filter = { ...op.deleteOne.filter, tenantId };
+        op.deleteOne.filter = { ...op.deleteOne.filter, ...filter };
       } else if ('deleteMany' in op) {
-        op.deleteMany.filter = { ...op.deleteMany.filter, tenantId };
+        op.deleteMany.filter = { ...op.deleteMany.filter, ...filter };
       }
     }
   });
@@ -121,45 +127,72 @@ export function mongooseTenantPlugin(schema) {
   schema.pre('aggregate', function () {
     // Aggregate hooks: `this` is the Aggregation pipeline — the model is on the internal `_model` property
     const modelName = (this as any)._model?.modelName;
-    const tenantId = resolveTenantId(modelName);
-    if (tenantId !== undefined) {
-      this.pipeline().unshift({ $match: { tenantId } });
+    const filter = resolveTenantFilter(modelName);
+    if (filter !== undefined) {
+      this.pipeline().unshift({ $match: filter });
     }
   });
 }
 
 /**
- * Resolve tenant ID from RequestContext.
+ * Check common bypass conditions.
  *
- * @returns
- * - `undefined` → no filter should be applied
- * - `string` → filter by this tenant ID
- * - `null` → filter by `{ tenantId: null }` (user without tenant sees only unassigned data)
+ * @returns `true` if filtering should be skipped, `false` otherwise
  */
-function resolveTenantId(modelName?: string): string | null | undefined {
-  // Defense-in-depth: check config even if plugin is registered
+function shouldBypass(modelName?: string): boolean {
   const mtConfig = ConfigService.configFastButReadOnly?.multiTenancy;
-  if (!mtConfig || mtConfig.enabled === false) return undefined;
+  if (!mtConfig || mtConfig.enabled === false) return true;
 
   const context = RequestContext.get();
+  if (!context) return true;
+  if (context.bypassTenantGuard) return true;
+  if (modelName && mtConfig.excludeSchemas?.includes(modelName)) return true;
 
-  // No RequestContext (system operation, cron, migration) → no filter
-  if (!context) return undefined;
+  return false;
+}
 
-  // Explicit bypass
-  if (context.bypassTenantGuard) return undefined;
+/**
+ * Resolve tenant filter from RequestContext for read operations (queries, aggregates).
+ *
+ * Defense-in-depth: If a schema has tenantId but there is no valid tenant context,
+ * throws ForbiddenException instead of returning unfiltered data (Safety Net).
+ *
+ * @returns
+ * - `undefined` → no filter should be applied (bypass active or plugin disabled)
+ * - `{}` → empty filter (admin bypass without header — sees all data)
+ * - `{ tenantId: string }` → filter by single validated tenant
+ * - `{ tenantId: { $in: string[] } }` → filter by user's tenant memberships
+ * @throws ForbiddenException when tenantId-schema is accessed without valid tenant context
+ */
+function resolveTenantFilter(modelName?: string): Record<string, any> | undefined {
+  if (shouldBypass(modelName)) return undefined;
+
+  const context = RequestContext.get();
 
-  // Check excluded schemas (model names, e.g. ['User', 'Session'])
-  if (modelName && mtConfig.excludeSchemas?.includes(modelName)) return undefined;
+  // Validated tenant ID (set by CoreTenantGuard) → filter by it
+  const tenantId = context?.tenantId;
+  if (tenantId) return { tenantId };
 
-  const tenantId = context.tenantId;
+  // User has resolved memberships → filter by their tenants
+  const tenantIds = context?.tenantIds;
+  if (tenantIds) return { tenantId: { $in: tenantIds } };
 
-  // User has tenantId → filter by it (empty string is treated as falsy = no tenant)
-  if (tenantId) return tenantId;
+  // Admin bypass without header → no filter, sees all data
+  if (context?.isAdminBypass) return {};
 
-  // User is logged in but has no tenantId (undefined, null, or '') → null filter (sees only data without tenant)
-  if (context.currentUser) return null;
+  // SAFETY NET: Schema has tenantId but no valid tenant context.
+  // Throw instead of returning unfiltered data to prevent data leaks.
+  throw new ForbiddenException(
+    'Tenant context required: this data is tenant-scoped but no valid tenant context was provided',
+  );
+}
+
+/**
+ * Resolve single tenant ID for write operations (save, insertMany).
+ * Only returns a value when a specific tenant header is set.
+ */
+function resolveSingleTenantId(modelName?: string): string | undefined {
+  if (shouldBypass(modelName)) return undefined;
 
-  // No user (public endpoint) → no filter
-  return undefined;
+  return RequestContext.get()?.tenantId || undefined;
 }

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

@@ -1,6 +1,7 @@
 import type SMTPPool = require('nodemailer/lib/smtp-pool');
 
-import { Injectable } from '@nestjs/common';
+import { createHash } from 'crypto';
+import { Injectable, OnModuleDestroy } from '@nestjs/common';
 import nodemailer = require('nodemailer');
 import { Attachment } from 'nodemailer/lib/mailer';
 
@@ -12,7 +13,14 @@ import { TemplateService } from './template.service';
  * Email service
  */
 @Injectable()
-export class EmailService {
+export class EmailService implements OnModuleDestroy {
+  /**
+   * Cached transporter to avoid creating new SMTP connections per email.
+   * Reused as long as the SMTP config hasn't changed.
+   */
+  private cachedTransporter: nodemailer.Transporter | null = null;
+  private cachedSmtpConfig: string | null = null;
+
   /**
    * Inject services
    */
@@ -21,6 +29,14 @@ export class EmailService {
     protected templateService: TemplateService,
   ) {}
 
+  onModuleDestroy(): void {
+    if (this.cachedTransporter) {
+      this.cachedTransporter.close();
+      this.cachedTransporter = null;
+      this.cachedSmtpConfig = null;
+    }
+  }
+
   /**
    * Send a mail
    */
@@ -74,11 +90,16 @@ export class EmailService {
       isNonEmptyString(html);
     }
 
-    // Init transporter
-    const transporter = nodemailer.createTransport(smtp);
+    // Reuse transporter if SMTP config hasn't changed (avoids creating new connections per email)
+    // Use hash instead of raw JSON to avoid keeping credentials as a string in memory
+    const smtpKey = createHash('sha256').update(JSON.stringify(smtp)).digest('hex');
+    if (!this.cachedTransporter || this.cachedSmtpConfig !== smtpKey) {
+      this.cachedTransporter = nodemailer.createTransport(smtp);
+      this.cachedSmtpConfig = smtpKey;
+    }
 
     // Send mail
-    return transporter.sendMail({
+    return this.cachedTransporter.sendMail({
       attachments,
       from: `"${senderName}" <${senderEmail}>`,
       html,

package/src/core/common/services/request-context.service.ts

@@ -11,8 +11,14 @@ export interface IRequestContext {
   bypassRoleGuard?: boolean;
   /** When true, mongooseTenantPlugin skips tenant filtering */
   bypassTenantGuard?: boolean;
-  /** Tenant ID resolved from the current user */
+  /** Validated tenant ID (set by CoreTenantGuard after membership validation, not raw header) */
   tenantId?: string;
+  /** Tenant IDs from user's active tenant memberships (used when no specific header is set) */
+  tenantIds?: string[];
+  /** Tenant role of the current user in the active tenant */
+  tenantRole?: string;
+  /** When true, indicates admin bypass is active (admin without header sees all data) */
+  isAdminBypass?: boolean;
 }
 
 /**
@@ -64,6 +70,10 @@ export class RequestContext {
    */
   static runWithBypassRoleGuard<T>(fn: () => T): T {
     const currentStore = this.storage.getStore();
+    // Skip context creation if already bypassed (avoids redundant object spread)
+    if (currentStore?.bypassRoleGuard) {
+      return fn();
+    }
     const context: IRequestContext = {
       ...currentStore,
       bypassRoleGuard: true,
@@ -97,6 +107,10 @@ export class RequestContext {
    */
   static runWithBypassTenantGuard<T>(fn: () => T): T {
     const currentStore = this.storage.getStore();
+    // Skip context creation if already bypassed (avoids redundant object spread)
+    if (currentStore?.bypassTenantGuard) {
+      return fn();
+    }
     const context: IRequestContext = {
       ...currentStore,
       bypassTenantGuard: true,

package/src/core/modules/auth/guards/roles.guard.ts

@@ -16,6 +16,7 @@ import { BetterAuthTokenService } from '../../better-auth/better-auth-token.serv
 import { BetterAuthenticatedUser } from '../../better-auth/better-auth.types';
 import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
 import { ErrorCode } from '../../error-code';
+import { isMultiTenancyActive, isSystemRole, mergeRolesMetadata } from '../../tenant/core-tenant.helpers';
 import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
 import { ExpiredTokenException } from '../exceptions/expired-token.exception';
 import { InvalidTokenException } from '../exceptions/invalid-token.exception';
@@ -134,11 +135,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
       context.getHandler(),
       context.getClass(),
     ]);
-    const roles: string[] = reflectorRoles[0]
-      ? reflectorRoles[1]
-        ? [...reflectorRoles[0], ...reflectorRoles[1]]
-        : reflectorRoles[0]
-      : reflectorRoles[1];
+    const roles = mergeRolesMetadata(reflectorRoles);
 
     // Check if locked - always deny
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
@@ -294,11 +291,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
       context.getHandler(),
       context.getClass(),
     ]);
-    const roles: string[] = reflectorRoles[0]
-      ? reflectorRoles[1]
-        ? [...reflectorRoles[0], ...reflectorRoles[1]]
-        : reflectorRoles[0]
-      : reflectorRoles[1];
+    const roles = mergeRolesMetadata(reflectorRoles);
 
     // Check if locked
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
@@ -317,6 +310,13 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
         return user;
       }
 
+      // When multiTenancy active: pass through ALL non-system roles to CoreTenantGuard.
+      // CoreTenantGuard handles hierarchy (level) and non-hierarchy (exact) checks
+      // against membership.role (tenant) or user.roles (no tenant).
+      if (user && isMultiTenancyActive() && roles.some((r) => !isSystemRole(r))) {
+        return user;
+      }
+
       // If user is missing throw token exception
       if (!user) {
         if (err) {

package/src/core/modules/better-auth/better-auth-roles.guard.ts

@@ -10,6 +10,7 @@ import { GqlExecutionContext } from '@nestjs/graphql';
 
 import { RoleEnum } from '../../common/enums/role.enum';
 import { ErrorCode } from '../error-code';
+import { isMultiTenancyActive, isSystemRole, mergeRolesMetadata } from '../tenant/core-tenant.helpers';
 import { BetterAuthTokenService } from './better-auth-token.service';
 import { BetterAuthenticatedUser } from './better-auth.types';
 import { CoreBetterAuthModule } from './core-better-auth.module';
@@ -79,12 +80,7 @@ export class BetterAuthRolesGuard implements CanActivate {
     const classRoles = Reflect.getMetadata('roles', context.getClass()) as string[] | undefined;
 
     // Combine handler and class roles (handler takes precedence, like Reflector.getAll)
-    const reflectorRoles: (string[] | undefined)[] = [handlerRoles, classRoles];
-    const roles: string[] = reflectorRoles[0]
-      ? reflectorRoles[1]
-        ? [...reflectorRoles[0], ...reflectorRoles[1]]
-        : reflectorRoles[0]
-      : reflectorRoles[1];
+    const roles = mergeRolesMetadata([handlerRoles, classRoles]);
 
     // Check if locked - always deny
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
@@ -120,6 +116,13 @@ export class BetterAuthRolesGuard implements CanActivate {
       return true;
     }
 
+    // When multiTenancy active: pass through ALL non-system roles to CoreTenantGuard.
+    // CoreTenantGuard handles hierarchy (level) and non-hierarchy (exact) checks
+    // against membership.role (tenant) or user.roles (no tenant).
+    if (isMultiTenancyActive() && roles.some((r) => !isSystemRole(r))) {
+      return true;
+    }
+
     // Check S_SELF role - user is accessing their own data
     if (roles.includes(RoleEnum.S_SELF)) {
       // Get the target object's ID from params or args

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

@@ -97,10 +97,32 @@ export interface SyncedUserDocument {
  * - IAM → Legacy: Copies password from `accounts` to `users.password`
  * - Legacy → IAM: Creates account entry in `accounts` from `users.password`
  */
+/**
+ * Cached user data for mapSessionUser (lightweight: only the fields needed for MappedUser)
+ */
+interface CachedUserData {
+  expiresAt: number;
+  id: string;
+  roles: string[];
+  verified: boolean;
+}
+
 @Injectable()
 export class CoreBetterAuthUserMapper {
   private readonly logger = new Logger(CoreBetterAuthUserMapper.name);
 
+  /**
+   * Lightweight TTL cache for user DB lookups.
+   * Key: iamId (BetterAuth user ID), Value: minimal user data (id, roles, verified).
+   * Only caches ~100 bytes per entry (no full documents). Max 500 entries = ~50KB.
+   */
+  private readonly userCache = new Map<string, CachedUserData>();
+  private static readonly USER_CACHE_MAX = 500;
+
+  /** Cache TTL: 15s in production, disabled in test environments */
+  private static readonly USER_CACHE_TTL_MS =
+    process.env.VITEST === 'true' || process.env.NODE_ENV === 'test' || process.env.NODE_ENV === 'e2e' ? 0 : 15_000;
+
   constructor(@Optional() @InjectConnection() private readonly connection?: Connection) {}
 
   /**
@@ -135,6 +157,23 @@ export class CoreBetterAuthUserMapper {
     }
 
     try {
+      // Check lightweight cache first (only stores id, roles, verified — ~100 bytes per entry)
+      const ttl = CoreBetterAuthUserMapper.USER_CACHE_TTL_MS;
+      const now = Date.now();
+      const cached = ttl > 0 ? this.userCache.get(sessionUser.id) : undefined;
+      if (cached && now < cached.expiresAt) {
+        return this.createMappedUser({
+          email: sessionUser.email,
+          emailVerified: sessionUser.emailVerified,
+          iamId: sessionUser.id,
+          id: cached.id,
+          image: sessionUser.image,
+          name: sessionUser.name,
+          roles: cached.roles,
+          verified: cached.verified,
+        });
+      }
+
       // Look up the user in our database by email OR iamId
       // This ensures we find the user regardless of which system they signed up with
       const userCollection = this.connection.collection('users');
@@ -148,6 +187,11 @@ export class CoreBetterAuthUserMapper {
         // Use database verified status, fallback to Better-Auth emailVerified
         const verified = dbUser.verified === true || sessionUser.emailVerified === true;
 
+        // Cache only the minimal data needed (not the full document)
+        if (CoreBetterAuthUserMapper.USER_CACHE_TTL_MS > 0) {
+          this.cacheUserData(sessionUser.id, { id: dbUser._id.toString(), roles, verified });
+        }
+
         return this.createMappedUser({
           email: sessionUser.email,
           emailVerified: sessionUser.emailVerified,
@@ -190,32 +234,53 @@ export class CoreBetterAuthUserMapper {
     return {
       ...userData,
       _authenticatedViaBetterAuth: true,
-      hasRole: (checkRoles: string | string[]): boolean => {
-        const rolesToCheck = Array.isArray(checkRoles) ? checkRoles : [checkRoles];
+      // Bind to static method to avoid creating a new closure per request
+      hasRole: CoreBetterAuthUserMapper.createHasRole(roles, userData.verified === true),
+      roles,
+    };
+  }
 
-        // Check for special roles
-        if (rolesToCheck.includes(RoleEnum.S_EVERYONE)) {
-          return true;
-        }
+  /**
+   * Creates a hasRole function. Uses a shared factory to minimize per-request closure size.
+   * The returned function only captures `roles` (string[]) and `verified` (boolean) — no large objects.
+   */
+  private static createHasRole(roles: string[], verified: boolean): (checkRoles: string | string[]) => boolean {
+    return (checkRoles: string | string[]): boolean => {
+      const rolesToCheck = Array.isArray(checkRoles) ? checkRoles : [checkRoles];
 
-        if (rolesToCheck.includes(RoleEnum.S_USER)) {
-          return true; // User is authenticated via Better-Auth
-        }
+      if (rolesToCheck.includes(RoleEnum.S_EVERYONE)) return true;
+      if (rolesToCheck.includes(RoleEnum.S_USER)) return true;
+      if (rolesToCheck.includes(RoleEnum.S_NO_ONE)) return false;
+      if (rolesToCheck.includes(RoleEnum.S_VERIFIED)) return verified;
 
-        if (rolesToCheck.includes(RoleEnum.S_NO_ONE)) {
-          return false;
-        }
+      return rolesToCheck.some((role) => roles.includes(role));
+    };
+  }
 
-        // S_VERIFIED check - uses verified field (from DB or Better-Auth emailVerified)
-        if (rolesToCheck.includes(RoleEnum.S_VERIFIED)) {
-          return userData.verified === true;
-        }
+  /**
+   * Store minimal user data in the lightweight cache.
+   * Only stores id, roles, verified — no full documents or large objects.
+   */
+  private cacheUserData(iamId: string, data: Omit<CachedUserData, 'expiresAt'>): void {
+    // Evict oldest if at capacity (simple FIFO)
+    if (this.userCache.size >= CoreBetterAuthUserMapper.USER_CACHE_MAX) {
+      const firstKey = this.userCache.keys().next().value;
+      if (firstKey) this.userCache.delete(firstKey);
+    }
+    this.userCache.set(iamId, {
+      ...data,
+      expiresAt: Date.now() + CoreBetterAuthUserMapper.USER_CACHE_TTL_MS,
+    });
+  }
 
-        // Check actual roles
-        return rolesToCheck.some((role) => roles.includes(role));
-      },
-      roles,
-    };
+  /**
+   * Invalidate cached user data. Call when user roles or verified status change.
+   * Called automatically from `CoreUserService.setRoles()` and `CoreUserService.update()`.
+   *
+   * @param iamId - The BetterAuth user ID (from session/account, not MongoDB _id)
+   */
+  invalidateUserCache(iamId: string): void {
+    this.userCache.delete(iamId);
   }
 
   // ===================================================================================================================

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

@@ -1,4 +1,4 @@
-import { BadRequestException, Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { BadRequestException, Inject, Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { Request } from 'express';
 import { importJWK, jwtVerify } from 'jose';
@@ -61,7 +61,7 @@ export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
 export const BETTER_AUTH_COOKIE_DOMAIN = 'BETTER_AUTH_COOKIE_DOMAIN';
 
 @Injectable()
-export class CoreBetterAuthService {
+export class CoreBetterAuthService implements OnModuleInit {
   private readonly logger = new Logger(CoreBetterAuthService.name);
   private readonly config: IBetterAuth;
 
@@ -78,6 +78,31 @@ export class CoreBetterAuthService {
     this.config = this.resolvedConfig || this.configService?.get<IBetterAuth>('betterAuth') || {};
   }
 
+  /**
+   * Ensure performance indices exist on session and users collections.
+   * Indices are idempotent — calling createIndex on an existing index is a no-op.
+   */
+  async onModuleInit(): Promise<void> {
+    if (!this.isEnabled() || !this.connection?.db) return;
+
+    try {
+      const db = this.connection.db;
+
+      // Session collection: token lookup (getSessionByToken) and user+expiry lookup (getActiveSessionForUser)
+      await db.collection('session').createIndex({ token: 1 });
+      await db.collection('session').createIndex({ userId: 1, expiresAt: 1 });
+
+      // Users collection: iamId lookup (mapSessionUser uses $or with email and iamId)
+      // email is typically already indexed by Mongoose schema, but iamId may not be
+      await db.collection('users').createIndex({ iamId: 1 }, { sparse: true });
+
+      this.logger.debug('Performance indices ensured on session and users collections');
+    } catch (error) {
+      // Non-fatal: indices improve performance but are not required for correctness
+      this.logger.warn(`Could not create performance indices: ${error instanceof Error ? error.message : 'unknown'}`);
+    }
+  }
+
   /**
    * Checks if better-auth is enabled and initialized
    * Returns true only if: