@lenne.tech/nest-server 11.36.0 → 11.36.2

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

@@ -4,6 +4,7 @@ import ejs = require('ejs');
 import * as fs from 'fs';
 import * as path from 'path';
 
+import { isProductionLikeEnv } 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';
@@ -11,14 +12,24 @@ 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 { formatProjectName } from './better-auth.config';
+import { AuthEmailCallbackOptions, formatProjectName } from './better-auth.config';
 
 /**
  * Resolved configuration type for email verification
- * Uses Required for mandatory fields but preserves optional nature of brevoTemplateId
+ * Uses Required for mandatory fields but preserves optional nature of the
+ * Brevo template ids — those stay undefined when no Brevo template is
+ * configured, which is what selects the SMTP/EJS path.
  */
-type ResolvedEmailVerificationConfig = Pick<IBetterAuthEmailVerificationConfig, 'brevoTemplateId' | 'callbackURL'> &
-  Required<Omit<IBetterAuthEmailVerificationConfig, 'brevoTemplateId' | 'callbackURL' | 'resendCooldownSeconds'>> & {
+type ResolvedEmailVerificationConfig = Pick<
+  IBetterAuthEmailVerificationConfig,
+  'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId'
+> &
+  Required<
+    Omit<
+      IBetterAuthEmailVerificationConfig,
+      'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId' | 'resendCooldownSeconds'
+    >
+  > & {
     resendCooldownSeconds: number;
   };
 
@@ -94,9 +105,36 @@ export interface SendVerificationEmailOptions {
  */
 const LOCAL_SLOT_TOKEN = 'local';
 
+/**
+ * Options for sending the password-reset email.
+ *
+ * Structurally the shared auth-email payload ({@link AuthEmailCallbackOptions}): `token` is the raw
+ * reset token for consumers that build their own link, `url` the ready-made link Better-Auth
+ * generated, `user` the account the reset was requested for. Aliased rather than redeclared so a
+ * future field lands in one place instead of six.
+ */
+export type SendPasswordResetEmailOptions = AuthEmailCallbackOptions;
+
+/**
+ * Template for the password-reset mail. Resolved through the same
+ * project-first / locale-aware lookup as the verification template, so a
+ * deployment brands it by dropping its own `password-reset[-<locale>].ejs`
+ * into the project template directory.
+ */
+const PASSWORD_RESET_TEMPLATE = 'password-reset';
+
 @Injectable()
 export class CoreBetterAuthEmailVerificationService {
   protected readonly logger = new Logger(CoreBetterAuthEmailVerificationService.name);
+
+  /** Memoised `getAppName()` result — see the note there. */
+  protected cachedAppName?: string;
+
+  /** Compiled nest-server templates, keyed by resolved absolute path — see renderFrameworkTemplate. */
+  protected readonly compiledTemplates = new Map<string, ejs.TemplateFunction>();
+
+  /** Memoised `resolveTemplatePath()` results, keyed by `<name>:<locale>`. */
+  protected readonly resolvedTemplatePaths = new Map<string, { isAbsolute: boolean; path: string }>();
   protected config: ResolvedEmailVerificationConfig = DEFAULT_CONFIG;
 
   /**
@@ -187,13 +225,7 @@ export class CoreBetterAuthEmailVerificationService {
         url = this.buildFrontendVerificationUrl(token);
       }
 
-      // Log verification URL in non-production environments for debugging and test capture
-      // Uses console.log directly to ensure reliable capture in test environments (Vitest)
-      // NestJS Logger may buffer output which makes interception unreliable in tests
-      if (process.env.NODE_ENV !== 'production') {
-        // oxlint-disable-next-line no-console
-        console.log(`[EMAIL VERIFICATION] User: ${user.email}, URL: ${url}`);
-      }
+      this.logAuthUrlForDevelopment('EMAIL VERIFICATION', user.email, url);
 
       // Brevo template path: send via Brevo transactional API if configured
       if (this.config.brevoTemplateId && this.brevoService) {
@@ -245,9 +277,8 @@ export class CoreBetterAuthEmailVerificationService {
         };
 
         if (resolved.isAbsolute) {
-          // Fallback template from nest-server: render directly via EJS
-          const templateContent = fs.readFileSync(`${resolved.path}.ejs`, 'utf-8');
-          const html = ejs.render(templateContent, templateData);
+          // Fallback template from nest-server: render directly via EJS (compiled once)
+          const html = this.renderFrameworkTemplate(resolved.path, templateData);
 
           await this.emailService.sendMail(user.email, this.getEmailSubject(appName), { html });
         } else {
@@ -273,6 +304,135 @@ export class CoreBetterAuthEmailVerificationService {
     }
   }
 
+  /**
+   * Send the password-reset email.
+   *
+   * Called from Better-Auth's `emailAndPassword.sendResetPassword` hook.
+   * Override to customise delivery.
+   *
+   * Deliberately does NOT consult `isEnabled()` / `emailVerification.enabled`. Those govern email
+   * VERIFICATION; switching that off must not also take away password recovery, which is a
+   * different concern and the only way back in for a locked-out user. The reset flow's own switch
+   * is `betterAuth.emailAndPassword.passwordReset`. (This method lives on the verification service
+   * because it shares the template lookup, the Brevo overlay and the cooldown store with it — the
+   * config key `passwordResetBrevoTemplateId` sits under `emailVerification` for the same reason.)
+   *
+   * Throttled per ADDRESS (see the slot comment in the body), not per session: the abuse this
+   * unauthenticated route enables runs on the recipient axis, which an IP-keyed limiter cannot
+   * express. The route-level `betterAuth.rateLimit` remains the IP-axis bound.
+   *
+   * @param options - The reset email options from Better-Auth
+   * @throws Re-throws a Brevo or SMTP send failure after logging it with the masked address. The
+   *   framework's own caller (`sendResetPassword` in better-auth.config.ts) invokes this through
+   *   `sendAuthEmailSafely`, which catches and logs — so a throw never reaches the request. An
+   *   override that calls this directly must handle it.
+   */
+  async sendPasswordResetEmail(options: SendPasswordResetEmailOptions): Promise<void> {
+    const { url, user } = options;
+
+    this.logAuthUrlForDevelopment('PASSWORD RESET', user.email, url);
+
+    // Per-ADDRESS throttle. The abuse this route enables runs on the RECIPIENT axis: an attacker
+    // rotating IPs mail-bombs one victim and writes one `verification` document per request, and an
+    // IP-keyed limiter cannot express "one reset mail per address per window". The slot is
+    // namespaced so the two flows cannot starve each other — a pending verification mail must not
+    // block a password reset.
+    //
+    // Returning early is enumeration-safe: Better-Auth has already produced its uniform
+    // "if this email exists in our system…" response by the time this hook runs, and the send is
+    // detached, so nothing about the response varies.
+    const slotKey = `${PASSWORD_RESET_TEMPLATE}:${user.email}`;
+    const slotToken = await this.acquireSendSlot(slotKey);
+    if (!slotToken) {
+      this.logger.debug(`Password-reset cooldown active for ${this.maskEmail(user.email)}, skipping email send`);
+      return;
+    }
+
+    // Only a SUCCESSFUL send may burn the cooldown — otherwise a transient SMTP failure would lock
+    // a user out of retrying for the whole window, on the one route that gets them back in.
+    let sent = false;
+
+    try {
+      const appName = this.getAppName();
+      const templateData = {
+        appName,
+        link: url,
+        name: user.name || user.email.split('@')[0],
+      };
+
+      // Brevo path: only when a reset-specific template is configured. Falling back
+      // to the VERIFICATION template id here would mail the user "confirm your
+      // address" for a password reset.
+      if (this.config.passwordResetBrevoTemplateId && this.brevoService) {
+        try {
+          const result = await this.brevoService.sendMail(
+            user.email,
+            this.config.passwordResetBrevoTemplateId,
+            templateData,
+          );
+
+          // `sendMail()` swallows SDK errors and resolves to `null` unless
+          // `brevo.throwOnError` is set, so "did not throw" is NOT "was delivered".
+          // Returning here on a null would leave a locked-out user with no mail at
+          // all; fall through to SMTP instead. Mirrors sendVerificationEmail.
+          if (result === null) {
+            this.logger.error(
+              `Brevo password-reset send failed for ${this.maskEmail(user.email)} — falling back to SMTP`,
+            );
+            // Deliberately no `return`: fall through to the EmailService path.
+          } else {
+            sent = true;
+            this.logger.debug(`Password-reset email sent via Brevo to ${this.maskEmail(user.email)}`);
+            return;
+          }
+        } catch (error) {
+          // Mirrors sendVerificationEmail: a Brevo THROW skips the SMTP fallback (only a `null`
+          // falls through). The address-identifying line matters — without it the only trace is
+          // the generic handler in better-auth.config.ts, which knows neither the user nor which
+          // of the two mail paths failed.
+          this.logger.error(
+            `Failed to send password-reset email via Brevo to ${this.maskEmail(user.email)}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          );
+          throw error;
+        }
+      }
+
+      if (!this.emailService) {
+        this.logger.warn('EmailService not available, cannot send password-reset email');
+        return;
+      }
+
+      try {
+        const resolved = await this.resolveTemplatePath(PASSWORD_RESET_TEMPLATE, this.config.locale);
+        const subject = this.getPasswordResetSubject(appName);
+
+        if (resolved.isAbsolute) {
+          // nest-server fallback template: render directly via EJS (compiled once, see the helper)
+          const html = this.renderFrameworkTemplate(resolved.path, templateData);
+          await this.emailService.sendMail(user.email, subject, { html });
+        } else {
+          // Project template: use TemplateService (relative path)
+          await this.emailService.sendMail(user.email, subject, {
+            htmlTemplate: resolved.path,
+            templateData,
+          });
+        }
+
+        sent = true;
+        this.logger.debug(`Password-reset email sent to ${this.maskEmail(user.email)}`);
+      } catch (error) {
+        this.logger.error(
+          `Failed to send password-reset email to ${this.maskEmail(user.email)}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+        throw error;
+      }
+    } finally {
+      if (!sent) {
+        await this.releaseSendSlot(slotKey, slotToken);
+      }
+    }
+  }
+
   /**
    * Reserve the resend-cooldown slot for an email address.
    *
@@ -448,6 +608,15 @@ export class CoreBetterAuthEmailVerificationService {
     templateName: string,
     locale: string,
   ): Promise<{ isAbsolute: boolean; path: string }> {
+    // Memoised: this walk costs up to four blocking `existsSync` calls, and it runs per outgoing
+    // auth mail on a route an unauthenticated caller can drive. Template files do not appear at
+    // runtime, so re-walking buys nothing after the first resolution.
+    const cacheKey = `${templateName}:${locale}`;
+    const cached = this.resolvedTemplatePaths.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
     const projectTemplatesPath = this.configService.getFastButReadOnly<string>('templates.path');
     const nestServerTemplatesPath = path.join(__dirname, '..', '..', '..', 'templates');
 
@@ -467,12 +636,13 @@ export class CoreBetterAuthEmailVerificationService {
 
       const fullPath = path.join(candidate.base, `${candidate.name}.ejs`);
       if (fs.existsSync(fullPath)) {
-        if (candidate.isNestServer) {
-          // nest-server template: return absolute path (rendered directly via EJS)
-          return { isAbsolute: true, path: fullPath.replace('.ejs', '') };
-        }
-        // Project template: return relative name (for TemplateService)
-        return { isAbsolute: false, path: candidate.name };
+        const resolved = candidate.isNestServer
+          ? // nest-server template: absolute path (rendered directly via EJS)
+            { isAbsolute: true, path: fullPath.replace('.ejs', '') }
+          : // Project template: relative name (for TemplateService)
+            { isAbsolute: false, path: candidate.name };
+        this.resolvedTemplatePaths.set(cacheKey, resolved);
+        return resolved;
       }
     }
 
@@ -484,7 +654,71 @@ export class CoreBetterAuthEmailVerificationService {
   /**
    * Get the app name for the email
    */
+  /**
+   * Render a nest-server fallback template, compiling it at most once per resolved path.
+   *
+   * `TemplateService` already caches compiled templates — but only for PROJECT templates. The
+   * absolute-path branch bypasses it entirely, so before this every outgoing auth mail re-read the
+   * file and re-compiled the EJS: measured at ~113 µs of event-loop-blocking work per mail against
+   * ~2 µs for a cached call. `readFileSync` blocks every other in-flight request while it runs, and
+   * the password-reset route that drives it is unauthenticated.
+   *
+   * Template files do not appear or change at runtime, so an unbounded map is bounded in practice
+   * by the number of templates on disk.
+   */
+  protected renderFrameworkTemplate(pathWithoutExtension: string, data: Record<string, unknown>): string {
+    let compiled = this.compiledTemplates.get(pathWithoutExtension);
+    if (!compiled) {
+      compiled = ejs.compile(fs.readFileSync(`${pathWithoutExtension}.ejs`, 'utf-8'));
+      this.compiledTemplates.set(pathWithoutExtension, compiled);
+    }
+    return compiled(data);
+  }
+
+  /**
+   * Print an auth link (verification / password reset) to stdout for local development.
+   *
+   * The URL embeds a bearer token: the verification link confirms an address, the reset link
+   * changes a password outright. Neither may reach a deployment holding real accounts, so the gate
+   * is `isProductionLikeEnv()` — the same two-layer check `EmailService` and the cookie helpers
+   * already use. `NODE_ENV !== 'production'` alone is NOT enough: a staging deployment sets
+   * `NODE_ENV=staging` so `getEnvironmentConfig()` loads its config block, which passes that test
+   * while holding real users.
+   *
+   * The address is masked (PII, and the rest of this file already masks it); the URL is printed in
+   * full because following it without a mail server is the whole point locally. Set
+   * `LT_LOG_AUTH_URLS=0` to suppress it even outside production.
+   *
+   * `console.log` rather than the NestJS logger, deliberately and for two reasons: the logger
+   * buffers, which makes interception unreliable under Vitest, and a logger call would route the
+   * token into `HubLogBufferService`'s ring buffer, which is readable over HTTP by any ADMIN.
+   */
+  protected logAuthUrlForDevelopment(label: string, email: string, url: string): void {
+    if (process.env.LT_LOG_AUTH_URLS === '0') {
+      return;
+    }
+    if (isProductionLikeEnv(this.configService?.getFastButReadOnly<string>('env'))) {
+      return;
+    }
+    // oxlint-disable-next-line no-console
+    console.log(`[${label}] User: ${this.maskEmail(email)}, URL: ${url}`);
+  }
+
   protected getAppName(): string {
+    // `package.json` never changes at runtime, but this runs once per outgoing auth mail — on a
+    // route an unauthenticated caller can drive. Cache it so that cannot become a synchronous
+    // file read per request. Mirrors `cachedProjectAppName` in better-auth.config.ts.
+    if (this.cachedAppName !== undefined) {
+      return this.cachedAppName;
+    }
+    this.cachedAppName = this.resolveAppName();
+    return this.cachedAppName;
+  }
+
+  /**
+   * Resolve the application name from package.json, falling back to a framework default.
+   */
+  protected resolveAppName(): string {
     // Try to get from package.json name
     try {
       const packageJsonPath = path.join(process.cwd(), 'package.json');
@@ -517,6 +751,17 @@ export class CoreBetterAuthEmailVerificationService {
     return `${appName} - Verify your email address`;
   }
 
+  /**
+   * Subject line of the password-reset mail.
+   */
+  protected getPasswordResetSubject(appName: string): string {
+    const subjects: Record<string, string> = {
+      de: `${appName} - Passwort zurücksetzen`,
+      en: `${appName} - Reset your password`,
+    };
+    return subjects[this.config.locale] ?? subjects.en;
+  }
+
   /**
    * Format expires in seconds to human readable string
    */

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

@@ -49,7 +49,21 @@ const DEFAULT_CONFIG: Required<IBetterAuthRateLimit> = {
   maxEntries: 10000,
   message: 'Too many requests, please try again later.',
   skipEndpoints: ['/session', '/callback'],
-  strictEndpoints: ['/sign-in', '/sign-up', '/forgot-password', '/reset-password'],
+  // The routes Better-Auth actually serves, plus the spellings a project may route itself.
+  // `/request-password-reset` is the entry point that MINTS a reset token and sends mail; it
+  // matched nothing here before (the only `/` in it is followed by `request`, so
+  // `includes('/reset-password')` is false), which left the expensive, mail-sending half of the
+  // flow on the FULL limit while the cheap submit half got the halved one. `/forget-password` is
+  // Better-Auth's own alias spelling — `/forgot-password` never matched any real route.
+  strictEndpoints: [
+    '/sign-in',
+    '/sign-up',
+    '/request-password-reset',
+    '/forget-password',
+    '/forgot-password',
+    '/reset-password',
+    '/change-password',
+  ],
   windowSeconds: 60,
 };
 
@@ -88,10 +102,24 @@ export class CoreBetterAuthRateLimiter {
    *
    * @param config - Rate limiting configuration
    */
-  configure(config: IBetterAuthRateLimit | undefined): void {
+  configure(config: IBetterAuthRateLimit | null | undefined): void {
+    // Absent config leaves rate limiting off — backward compatible.
+    if (config === undefined || config === null) {
+      return;
+    }
+
+    // Presence of config implies enabled, unless explicitly disabled. This is the contract
+    // `.claude/rules/configurable-features.md` documents for `betterAuth.rateLimit`, and the one
+    // `LegacyAuthRateLimiter.configure()` has always implemented. Spreading over an
+    // `enabled: false` default without recomputing meant the two sibling limiters had OPPOSITE
+    // semantics: a documented `rateLimit: { max: 20 }` armed the legacy limiter and silently
+    // armed nothing here — on the side where every new project lives.
+    const enabled = config.enabled !== false;
+
     this.config = {
       ...DEFAULT_CONFIG,
       ...config,
+      enabled,
       // Ensure arrays are properly merged
       skipEndpoints: config?.skipEndpoints ?? DEFAULT_CONFIG.skipEndpoints,
       strictEndpoints: config?.strictEndpoints ?? DEFAULT_CONFIG.strictEndpoints,

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

@@ -13,13 +13,19 @@ 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 { BetterAuthRolesGuard } from './better-auth-roles.guard';
 import { BetterAuthTokenService } from './better-auth-token.service';
-import { BetterAuthInstance, CreateBetterAuthResult, createBetterAuthInstance } from './better-auth.config';
+import {
+  AuthEmailCallbackOptions,
+  BetterAuthInstance,
+  CreateBetterAuthResult,
+  createBetterAuthInstance,
+} 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';
@@ -406,8 +412,14 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       consumer.apply(CoreBetterAuthMiddleware).forRoutes('(.*)'); // New path-to-regexp syntax for wildcard
       CoreBetterAuthModule.logger.debug('CoreBetterAuthMiddleware registered for all routes');
 
-      // Apply rate limiting to Better-Auth endpoints only
-      if (CoreBetterAuthModule.currentConfig?.rateLimit?.enabled) {
+      // Apply rate limiting to Better-Auth endpoints only.
+      // Mirrors the "presence implies enabled" contract `CoreBetterAuthRateLimiter.configure()`
+      // implements. Gating the MOUNT on `.enabled` alone made that fix unobservable: the limiter
+      // would report itself enabled while no middleware was ever registered.
+      if (
+        CoreBetterAuthModule.currentConfig?.rateLimit &&
+        CoreBetterAuthModule.currentConfig.rateLimit.enabled !== false
+      ) {
         consumer.apply(CoreBetterAuthRateLimitMiddleware).forRoutes(`${basePath}/*path`);
         CoreBetterAuthModule.logger.debug(`Rate limiting middleware registered for ${basePath}/*path endpoints`);
       }
@@ -655,7 +667,8 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
             const fallbackSecrets = [jwtConfig?.secret, jwtConfig?.refresh?.secret];
 
             // Create email verification callbacks that delegate to the NestJS service
-            const { onEmailVerified, sendVerificationEmail } = this.createEmailVerificationCallbacks();
+            const { onEmailVerified, sendResetPasswordEmail, sendVerificationEmail } =
+              this.createEmailVerificationCallbacks();
 
             // Note: Secret validation is now handled in createBetterAuthInstance
             // with fallback to jwt.secret, jwt.refresh.secret, or auto-generation
@@ -664,6 +677,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
               db,
               fallbackSecrets,
               onEmailVerified,
+              sendResetPasswordEmail,
               sendVerificationEmail,
             });
             this.authInstance = result?.instance ?? null;
@@ -802,11 +816,8 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    */
   private static createEmailVerificationCallbacks(): {
     onEmailVerified: (userId: string) => Promise<void>;
-    sendVerificationEmail: (options: {
-      token: string;
-      url: string;
-      user: { email: string; id: string; name?: null | string };
-    }) => Promise<void>;
+    sendResetPasswordEmail: (options: AuthEmailCallbackOptions) => Promise<void>;
+    sendVerificationEmail: (options: AuthEmailCallbackOptions) => Promise<void>;
   } {
     return {
       onEmailVerified: async (userId: string) => {
@@ -829,14 +840,33 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           );
         }
       },
+      sendResetPasswordEmail: async (options) => {
+        // Delegate to the NestJS service
+        if (this.emailVerificationService) {
+          await this.emailVerificationService.sendPasswordResetEmail(options);
+        } else {
+          // Report the failure, never the capability. The reset URL is a bearer token for account
+          // takeover, this branch has no environment gate, and `this.logger` feeds
+          // `HubLogBufferService`'s ring buffer — which is readable over HTTP by any ADMIN. The
+          // operator needs to know delivery is broken, not to be handed the victim's token.
+          this.logger.error(
+            `Password reset requested for ${maskEmail(options.user.email)} but CoreBetterAuthEmailVerificationService ` +
+              'is not available — NO mail was sent. Register the service, or disable the flow via ' +
+              'betterAuth.emailAndPassword.passwordReset: false.',
+          );
+        }
+      },
       sendVerificationEmail: async (options) => {
         // Delegate to the NestJS service
         if (this.emailVerificationService) {
           await this.emailVerificationService.sendVerificationEmail(options);
         } else {
-          // Fallback: Log verification URL if service not available
-          this.logger.warn('Email verification service not available, logging URL for development');
-          this.logger.log(`[DEV] Verification URL for ${options.user.email}: ${options.url}`);
+          // Same reasoning as the password-reset branch above: the URL carries a token and this
+          // logger feeds the ADMIN-readable Hub log buffer, so report the breakage instead.
+          this.logger.error(
+            `Verification mail requested for ${maskEmail(options.user.email)} but ` +
+              'CoreBetterAuthEmailVerificationService is not available — NO mail was sent.',
+          );
         }
       },
     };
@@ -902,13 +932,15 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
             this.mongoConnection = connection;
 
             // Create email verification callbacks that delegate to the NestJS service
-            const { onEmailVerified, sendVerificationEmail } = this.createEmailVerificationCallbacks();
+            const { onEmailVerified, sendResetPasswordEmail, sendVerificationEmail } =
+              this.createEmailVerificationCallbacks();
 
             // Build shared instance options
             const sharedInstanceOptions = {
               config,
               fallbackSecrets: options?.fallbackSecrets,
               onEmailVerified,
+              sendResetPasswordEmail,
               sendVerificationEmail,
               serverAppUrl: options?.serverAppUrl,
               serverBaseUrl: options?.serverBaseUrl,

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

@@ -93,7 +93,7 @@ export class CoreBetterAuthService implements OnModuleInit {
   }
 
   /**
-   * Ensure performance indices exist on session and users collections.
+   * Ensure performance indices exist on the session, users, account and verification collections.
    * Indices are idempotent — calling createIndex on an existing index is a no-op.
    */
   async onModuleInit(): Promise<void> {
@@ -112,9 +112,17 @@ export class CoreBetterAuthService implements OnModuleInit {
         // Account: userId lookup ($lookup in getMigrationStatus) and providerId filtering
         db.collection('account').createIndex({ userId: 1 }),
         db.collection('account').createIndex({ providerId: 1, userId: 1 }),
+        // Verification: identifier lookup (findVerificationValue runs on every verify/reset).
+        db.collection('verification').createIndex({ identifier: 1 }),
+        // Verification TTL — this one is correctness, not just speed. Better-Auth writes a
+        // verification document per email-verification AND per password-reset request, and removes
+        // it only when the token is CONSUMED. `POST /iam/request-password-reset` is unauthenticated,
+        // so every un-clicked request left a row that nothing would ever delete. The documents
+        // already carry `expiresAt`; `expireAfterSeconds: 0` makes MongoDB honour it.
+        db.collection('verification').createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 }),
       ]);
 
-      this.logger.debug('Performance indices ensured on session, users, and account collections');
+      this.logger.debug('Performance indices ensured on session, users, account, and verification 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'}`);

package/src/core/modules/tenant/core-tenant.service.ts

@@ -74,7 +74,22 @@ export class CoreTenantService {
   }
 
   /**
-   * Get a single membership (any status).
+   * Get a single membership REGARDLESS of its status.
+   *
+   * Read the name literally: a removal is a status change to `SUSPENDED`, not
+   * a delete, so this still answers for somebody who was thrown out. That is
+   * deliberate and `addMember` depends on it — it reactivates the existing row
+   * instead of creating a duplicate.
+   *
+   * It is therefore the WRONG method for an authorization check. Asking "is
+   * this user a member with role X?" through it answers yes for a removed
+   * member, and a route that guards itself this way keeps granting a
+   * suspended administrator the right to invite, remove and re-role — the very
+   * rights that being removed was supposed to take away. Routes that carry
+   * `@SkipTenantCheck()` and decide for themselves are exactly the ones at
+   * risk, because the tenant guard never sees them.
+   *
+   * For an authorization check use {@link getActiveMembership}.
    */
   async getMembership(tenantId: string, userId: string): Promise<CoreTenantMemberModel | null> {
     return this.memberModel
@@ -83,6 +98,25 @@ export class CoreTenantService {
       .exec() as Promise<CoreTenantMemberModel | null>;
   }
 
+  /**
+   * Get a membership only while it is live — the one to use when deciding what
+   * somebody may do.
+   *
+   * Returns `null` for a suspended or invited membership, so "removed" means
+   * removed everywhere, not just for the data the tenant guard happens to
+   * cover.
+   */
+  async getActiveMembership(tenantId: string, userId: string): Promise<CoreTenantMemberModel | null> {
+    if (!tenantId?.trim() || !userId?.trim()) {
+      return null;
+    }
+
+    return this.memberModel
+      .findOne({ status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId })
+      .lean()
+      .exec() as Promise<CoreTenantMemberModel | null>;
+  }
+
   /**
    * Add a member to a tenant.
    * Uses bypassTenantGuard to avoid tenant filtering on the membership collection itself.
@@ -193,8 +227,11 @@ export class CoreTenantService {
     assertAssignableMembershipRole(role);
     const highestRole = this.getHighestRole();
 
-    // If demoting from highest role, ensure it's not the last one
-    const existing = await this.getMembership(tenantId, userId);
+    // If demoting from highest role, ensure it's not the last one. Active
+    // only: a suspended membership is not an owner any more, and letting it
+    // trigger the guard produces "cannot demote the last owner" for a user who
+    // is not even a member.
+    const existing = await this.getActiveMembership(tenantId, userId);
     if (existing?.role === highestRole && role !== highestRole) {
       await this.assertNotLastOwner(tenantId, userId);
     }
@@ -237,7 +274,7 @@ export class CoreTenantService {
       });
 
       if (ownerCount <= 1) {
-        const membership = await this.getMembership(tenantId, userId);
+        const membership = await this.getActiveMembership(tenantId, userId);
         if (membership?.role === highestRole) {
           throw new BadRequestException('Cannot remove or demote the last owner of a tenant');
         }