@lenne.tech/nest-server 11.36.5 → 11.38.0

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

@@ -1,10 +1,12 @@
-import { Injectable, Logger, NestMiddleware, Optional } from '@nestjs/common';
+import { BadRequestException, Injectable, Logger, NestMiddleware, Optional } from '@nestjs/common';
 import { Response as ExpressResponse, NextFunction, Request } from 'express';
 
 import { isProduction } from '../../common/helpers/logging.helper';
 import { ConfigService } from '../../common/services/config.service';
 import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service';
 import { BetterAuthCookieHelper, createCookieHelper } from './core-better-auth-cookie.helper';
+import { runWithResetPassword } from './core-better-auth-password-reset.registry';
+import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
 import { extractSessionToken, sendWebResponse, signCookieValue, toWebRequest } from './core-better-auth-web.helper';
 import { CoreBetterAuthService } from './core-better-auth.service';
 
@@ -23,6 +25,29 @@ import { CoreBetterAuthService } from './core-better-auth.service';
  */
 const CONTROLLER_HANDLED_PATHS = ['/features', '/sign-in/email', '/sign-up/email', '/sign-out', '/session'];
 
+/**
+ * Native Better-Auth routes that set a NEW password from a token or OTP, with the body
+ * field each of them carries it in.
+ *
+ * These are forwarded (they are not in CONTROLLER_HANDLED_PATHS), so unlike sign-in and
+ * sign-up nothing normalizes their password — Better-Auth hashes whatever arrives. That
+ * is a problem, because the sign-in path DOES normalize: a plaintext reset would be
+ * stored as `scrypt(plaintext)` while every later sign-in checks `scrypt(sha256(...))`,
+ * and the account is locked out with the password its owner just chose. Normalizing
+ * here puts every write of a credential on the same footing as every read of one.
+ *
+ * Matching is EXACT (after trimming a trailing slash and lower-casing), not prefix-based. So
+ * `/reset-password/:token` — Better-Auth's GET redirect — never matches an entry at all and is
+ * forwarded untouched. That is the intended outcome, but for this reason and not because "the
+ * body has no password field": switching the matcher to `startsWith` would start rewriting that
+ * redirect's body on the strength of a comment that was never true.
+ */
+export const PASSWORD_RESET_PATHS: { field: string; path: string }[] = [
+  { field: 'newPassword', path: '/reset-password' },
+  { field: 'password', path: '/email-otp/reset-password' },
+  { field: 'newPassword', path: '/phone-number/reset-password' },
+];
+
 /**
  * Passkey paths that generate challenges
  */
@@ -59,8 +84,88 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
   constructor(
     private readonly betterAuthService: CoreBetterAuthService,
     @Optional() private readonly challengeService?: CoreBetterAuthChallengeService,
+    @Optional() private readonly userMapper?: CoreBetterAuthUserMapper,
   ) {}
 
+  /**
+   * Brings a native reset route's password to the same shape sign-in will present, and
+   * returns that value so the legacy mirror can reuse it.
+   *
+   * Returns `undefined` when this is not a password-setting route or the body carries no
+   * password — both mean "leave the request untouched".
+   *
+   * @throws BadRequestException when a plaintext password violates the configured length policy
+   */
+  protected normalizeResetPassword(req: Request, relativePath: string): string | undefined {
+    // Trailing slashes and case are normalized before matching. Express does not collapse a
+    // trailing slash on `originalUrl`, and Better-Auth's own router is more permissive than
+    // `===` — so a variant it accepts but this table does not would silently skip BOTH the
+    // normalization and the legacy mirror, i.e. reproduce the exact lockout this method exists
+    // to prevent, through a URL shape rather than a code change.
+    const normalizedPath = relativePath.replace(/\/+$/, '').toLowerCase();
+    const route = PASSWORD_RESET_PATHS.find((entry) => normalizedPath === entry.path);
+    if (!route) {
+      return undefined;
+    }
+
+    if (!this.userMapper) {
+      // Fail LOUD rather than open. Today every module variant that provides this middleware
+      // also provides the mapper, so this is unreachable — but silently forwarding an
+      // un-normalized password stores `scrypt(plaintext)` against a sign-in that checks
+      // `scrypt(sha256(...))`, and the user is locked out with the password they just chose.
+      // A guard on a correctness-critical step must not degrade quietly.
+      this.logger.error(
+        `No CoreBetterAuthUserMapper available — the password on ${relativePath} is NOT normalized. ` +
+          'Better-Auth will store scrypt(plaintext) while sign-in checks scrypt(sha256(...)), ' +
+          'locking the account out with its new password.',
+      );
+      return undefined;
+    }
+
+    const submitted = req.body?.[route.field];
+    if (!submitted || typeof submitted !== 'string') {
+      return undefined;
+    }
+
+    this.assertResetPasswordLength(submitted);
+
+    const normalized = this.userMapper.normalizePasswordForIam(submitted);
+    // `toWebRequest` serializes `req.body`, so writing it back here is what Better-Auth
+    // actually hashes.
+    req.body[route.field] = normalized;
+    return normalized;
+  }
+
+  /**
+   * Enforces the configured password length on the value the CLIENT actually sent.
+   *
+   * Better-Auth checks `minPasswordLength`/`maxPasswordLength` against the body it receives —
+   * and by then this middleware has replaced it with a 64-character sha256, so both bounds
+   * always pass. Without this check there would be no server-side minimum password length on
+   * any reset path at all.
+   *
+   * An already-hashed value carries no length information, so it cannot be checked here. That
+   * limit is real and belongs in the client; it is stated in the migration guide rather than
+   * pretended away.
+   */
+  protected assertResetPasswordLength(submitted: string): void {
+    if (/^[a-f0-9]{64}$/i.test(submitted)) {
+      return;
+    }
+
+    // The bounds live on the Better-Auth passthrough (`betterAuth.options.emailAndPassword`),
+    // not on the framework's own typed block — so they are read defensively. The fallbacks are
+    // Better-Auth's own defaults, which is what applied before this check existed.
+    const passthrough = (this.betterAuthService.getConfig()?.options as Record<string, any> | undefined)
+      ?.emailAndPassword;
+    const min = typeof passthrough?.minPasswordLength === 'number' ? passthrough.minPasswordLength : 8;
+    const max = typeof passthrough?.maxPasswordLength === 'number' ? passthrough.maxPasswordLength : 128;
+
+    if (submitted.length < min || submitted.length > max) {
+      throw new BadRequestException(`Password must be between ${min} and ${max} characters`);
+    }
+  }
+
   /**
    * Gets or creates the cookie helper instance.
    * Lazy initialization because betterAuthService may not be fully initialized in constructor.
@@ -186,6 +291,10 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
         }
       }
 
+      // Put a reset password into the shape sign-in expects BEFORE the body is
+      // serialized, and keep the value for the legacy mirror below.
+      const resetPassword = this.normalizeResetPassword(req, relativePath);
+
       // Convert Express request to Web Standard Request with proper cookie signing
       const webRequest = await toWebRequest(req, {
         basePath,
@@ -195,8 +304,15 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
         sessionToken,
       });
 
-      // Call Better Auth's native handler
-      const response = await authInstance.handler(webRequest);
+      // Call Better Auth's native handler.
+      //
+      // For a reset, the call is wrapped so that `emailAndPassword.onPasswordReset` — which
+      // Better-Auth invokes inside this call, and which is told WHICH user was reset but not
+      // to WHAT — can read the new password and mirror it into the legacy store. The context
+      // lives exactly as long as the handler call, so no other request can observe it.
+      const response = resetPassword
+        ? await runWithResetPassword(resetPassword, () => authInstance.handler(webRequest))
+        : await authInstance.handler(webRequest);
 
       this.logger.debug(`Better Auth handler response: ${response.status}`);
 

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

@@ -22,12 +22,12 @@ import { AuthEmailCallbackOptions, formatProjectName } from './better-auth.confi
  */
 type ResolvedEmailVerificationConfig = Pick<
   IBetterAuthEmailVerificationConfig,
-  'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId'
+  'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId' | 'passwordResetLink'
 > &
   Required<
     Omit<
       IBetterAuthEmailVerificationConfig,
-      'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId' | 'resendCooldownSeconds'
+      'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId' | 'passwordResetLink' | 'resendCooldownSeconds'
     >
   > & {
     resendCooldownSeconds: number;
@@ -328,7 +328,8 @@ export class CoreBetterAuthEmailVerificationService {
    *   override that calls this directly must handle it.
    */
   async sendPasswordResetEmail(options: SendPasswordResetEmailOptions): Promise<void> {
-    const { url, user } = options;
+    const { user } = options;
+    const url = this.buildPasswordResetUrl(options);
 
     this.logAuthUrlForDevelopment('PASSWORD RESET', user.email, url);
 
@@ -569,6 +570,69 @@ export class CoreBetterAuthEmailVerificationService {
     };
   }
 
+  /**
+   * Where the password-reset mail points.
+   *
+   * Defaults to the APP rather than to the link Better-Auth generates, which points at the API
+   * (`https://api.example.com/iam/reset-password/<token>?callbackURL=…`) and redirects from there.
+   * That works, but it puts an unfamiliar domain into a password mail — the one thing recipients
+   * are trained to check. In this stack an app host and an API host are the norm, so the app is
+   * the better default.
+   *
+   * WHAT THIS GIVES UP, STATED PLAINLY
+   *
+   * Better-Auth's redirect route validates the token and its expiry before forwarding, so an
+   * expired link produced an error page rather than a form that fails on submit. Linking straight
+   * to the app moves that error later. It is NOT a security difference: the token reaches the app
+   * URL either way, and the `callbackURL` origin check only exists because of the hop it removes.
+   * `passwordResetLink: false` keeps Better-Auth's link for anyone who wants the early error.
+   *
+   * Resolution order — the first that yields something wins:
+   *   1. `betterAuth.emailVerification.passwordResetLink` (`false` → Better-Auth's own link)
+   *   2. `<appUrl>/auth/reset-password` — the starter's reset page
+   *   3. Better-Auth's link, when no app URL can be resolved
+   *
+   * `{token}` is substituted anywhere in the configured value; without it the token is appended as
+   * `?token=`. That is what lets a page reading a PATH parameter configure
+   * `https://example.com/auth/reset-password/{token}`.
+   */
+  protected buildPasswordResetUrl(options: SendPasswordResetEmailOptions): string {
+    const configured = this.config.passwordResetLink;
+
+    // Explicit opt-out: keep Better-Auth's link, including its token validation hop.
+    if (configured === false) {
+      return options.url;
+    }
+
+    let target = typeof configured === 'string' && configured.trim().length ? configured.trim() : undefined;
+
+    if (!target) {
+      const appUrl = this.configService.getFastButReadOnly<string>('appUrl');
+      if (!appUrl) {
+        // Nothing to point at. Better-Auth's link at least works, which beats a guess.
+        return options.url;
+      }
+      target = `${appUrl.replace(/\/$/, '')}/auth/reset-password`;
+    }
+
+    // Resolve a relative value against appUrl, like buildFrontendVerificationUrl does.
+    if (target.startsWith('/')) {
+      const appUrl = this.configService.getFastButReadOnly<string>('appUrl');
+      if (!appUrl) {
+        return options.url;
+      }
+      target = `${appUrl.replace(/\/$/, '')}${target}`;
+    }
+
+    const token = options.token;
+    if (target.includes('{token}')) {
+      return target.replace(/\{token\}/g, encodeURIComponent(token));
+    }
+
+    const separator = target.includes('?') ? '&' : '?';
+    return `${target}${separator}token=${encodeURIComponent(token)}`;
+  }
+
   /**
    * Build the frontend verification URL from the configured callbackURL and token.
    *

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

@@ -0,0 +1,92 @@
+/**
+ * Carries the password of an in-flight IAM password reset from the API middleware
+ * to Better-Auth's `onPasswordReset` hook.
+ *
+ * WHY THIS EXISTS
+ *
+ * A reset has to land in BOTH credential stores when Legacy Auth and IAM run next to
+ * each other: IAM keeps scrypt, Legacy keeps bcrypt, and neither hash can be derived
+ * from the other. Mirroring a reset into the legacy store therefore needs the password
+ * itself — and the two halves are known in two different places:
+ *
+ * | half | known by |
+ * |------|----------|
+ * | the new password | `CoreBetterAuthApiMiddleware`, which sees the request body |
+ * | which user it belongs to | `emailAndPassword.onPasswordReset`, which Better-Auth calls with the user |
+ *
+ * Better-Auth hands its hook `{ user }` and the original `Request`, whose body is
+ * already consumed by then, so the hook cannot recover the password on its own. The
+ * alternative — resolving the user in the middleware by parsing Better-Auth's
+ * `reset-password:<token>` verification identifier — would couple us to an internal
+ * storage format that no contract keeps stable. Using the supported hook for the user
+ * and this registry for the password keeps the only coupling inside our own code.
+ *
+ * The value stored here is ALREADY NORMALIZED (`normalizePasswordForIam`), i.e. exactly
+ * what Better-Auth hashed, so the legacy mirror cannot drift from the IAM credential
+ * even when the client posts a plaintext password.
+ *
+ * A true leaf: it imports nothing but a Node built-in, so it can never be
+ * mid-evaluation when a cycle-adjacent file reads it (see
+ * `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)").
+ *
+ * @internal Not public API — but NOT optional. Two shipped core files import it
+ * (`core-better-auth-api.middleware.ts`, `core-better-auth.module.ts`), so a vendor-mode sync that
+ * skips this file leaves an unresolvable import. `@internal` means "do not depend on this from a
+ * project", never "you may leave it out".
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+
+interface PasswordResetContext {
+  /**
+   * The new password as Better-Auth will hash it — already normalized.
+   *
+   * Cleared on the first read (see {@link getInFlightResetPassword}), so the property is
+   * optional after that point.
+   */
+  normalizedPassword?: string;
+}
+
+const storage = new AsyncLocalStorage<PasswordResetContext>();
+
+/**
+ * Runs `fn` with the in-flight reset password attached to the async context.
+ *
+ * Wrap ONLY the Better-Auth handler call: the context has to be alive while
+ * `onPasswordReset` runs, and dead everywhere else, so an unrelated request can never
+ * pick up a password that was not its own.
+ *
+ * @internal
+ */
+export function runWithResetPassword<T>(normalizedPassword: string, fn: () => T): T {
+  return storage.run({ normalizedPassword }, fn);
+}
+
+/**
+ * The normalized password of the reset currently being handled, or `undefined`
+ * outside such a request.
+ *
+ * `undefined` means "not a reset we saw the body of" — never "no password". Callers
+ * must skip the mirror rather than guess, because writing a wrong bcrypt hash would
+ * lock the account out of the legacy path.
+ *
+ * @internal
+ */
+export function getInFlightResetPassword(): string | undefined {
+  const store = storage.getStore();
+  if (!store) {
+    return undefined;
+  }
+
+  // ONE-SHOT. The legacy mirror is the only legitimate reader and it reads once, so handing the
+  // value out a second time can only serve something that should not have it.
+  //
+  // Defence in depth rather than a fix for a known hole: an AsyncLocalStorage store is retained
+  // by any async resource created INSIDE the `run()` that outlives it — a timer registered during
+  // lazy plugin init, a cached promise. Such a resource would otherwise keep observing a
+  // password-equivalent from a request that finished long ago. Clearing on read bounds that to
+  // the moment the mirror actually runs.
+  const { normalizedPassword } = store;
+  store.normalizedPassword = undefined;
+  return normalizedPassword;
+}

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

@@ -1,3 +1,4 @@
+import { createLocalAccountIssuer } from '@better-auth/core/db';
 import { Injectable, Logger, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import * as bcrypt from 'bcrypt';
@@ -56,6 +57,22 @@ export interface MappedUser {
   verified?: boolean;
 }
 
+/**
+ * Options for {@link CoreBetterAuthUserMapper.getMigrationStatus}.
+ */
+export interface GetMigrationStatusOptions {
+  /**
+   * Whether to collect `pendingUserEmails` (up to 100 addresses).
+   *
+   * Costs two extra collection-scale queries, one of them a guaranteed COLLSCAN. Pass `false`
+   * from callers that only need the counts — they get the same numbers without the scan, and
+   * without handling addresses they were going to discard.
+   *
+   * @default true
+   */
+  includePendingEmails?: boolean;
+}
+
 /**
  * Interface for migration status result
  */
@@ -339,6 +356,11 @@ export class CoreBetterAuthUserMapper {
       const bcryptHash = await bcrypt.hash(normalizedPassword, saltRounds);
 
       // Update the users collection with the bcrypt hash
+      // `$or` across two different indexes (`users.email` unique, `users.iamId` sparse) forces an
+      // index-union plan rather than a single-index point lookup. Deliberate — the caller may know
+      // only one of the two — and irrelevant at password-change frequency. It would NOT be
+      // irrelevant in a bulk or migration loop; anything calling this in one should look up the
+      // user once and address it by `_id`.
       const result = await usersCollection.updateOne(
         { $or: [{ email: userEmail }, { iamId: iamUserId }] },
         { $set: { password: bcryptHash, updatedAt: new Date() } },
@@ -509,10 +531,16 @@ export class CoreBetterAuthUserMapper {
       // Store account matching Better-Auth's format:
       // - userId: ObjectId referencing users._id
       // - accountId: string version of users._id
+      // - issuer: from better-auth >= 1.7 accounts are keyed by (issuer,
+      //   accountId), and credential accounts carry a synthetic issuer. Writing
+      //   the row without it produces an account better-auth cannot find, so the
+      //   migrated user gets a 401 on the very sign-in that triggered the
+      //   migration. Always derive it from the helper, never hand-write it.
       await accountsCollection.insertOne({
         accountId: userIdHex,
         createdAt: now,
         id: this.generateId(),
+        issuer: createLocalAccountIssuer('credential'),
         password: passwordHash,
         providerId: 'credential',
         updatedAt: now,
@@ -969,7 +997,13 @@ export class CoreBetterAuthUserMapper {
    *
    * @returns Migration status object with counts and percentage
    */
-  async getMigrationStatus(): Promise<MigrationStatus> {
+  async getMigrationStatus(options?: GetMigrationStatusOptions): Promise<MigrationStatus> {
+    // Building `pendingUserEmails` costs two collection-scale queries, one of them a
+    // guaranteed COLLSCAN (`$exists: false` cannot use the sparse `iamId` index) that scans
+    // the WHOLE collection precisely in the all-migrated steady state, where it finds nothing.
+    // A caller that only needs the counts — the boot-time deprecation warning does — should
+    // not pay for a field it discards.
+    const includePendingEmails = options?.includePendingEmails !== false;
     if (!this.connection) {
       this.logger.warn('No database connection available - cannot get migration status');
       return {
@@ -997,10 +1031,13 @@ export class CoreBetterAuthUserMapper {
       });
 
       // Get unique userIds that have credential accounts
-      const credentialAccounts = await accountCollection
-        .aggregate([{ $match: { providerId: 'credential' } }, { $group: { _id: '$userId' } }])
+      // Counted server-side. The previous form materialized one `{_id}` object per distinct
+      // migrated user in the Node heap only to read `.length` — an allocation that grows with
+      // the user count, at boot, before the first request.
+      const credentialAccountCount = await accountCollection
+        .aggregate([{ $match: { providerId: 'credential' } }, { $group: { _id: '$userId' } }, { $count: 'count' }])
         .toArray();
-      const usersWithIamAccount = credentialAccounts.length;
+      const usersWithIamAccount = credentialAccountCount[0]?.count ?? 0;
 
       // Get users that are fully migrated (have both iamId AND credential account)
       // We need to find users where iamId exists AND there's a matching account
@@ -1040,15 +1077,17 @@ export class CoreBetterAuthUserMapper {
       // Get emails of pending users (limit to 100)
       // Two-phase approach: first get users without iamId (no $lookup needed),
       // then check users with iamId but missing credential account
-      const usersWithoutIamId = await usersCollection
-        .find({ $or: [{ iamId: { $exists: false } }, { iamId: null }] })
-        .limit(100)
-        .project({ email: 1 })
-        .toArray();
+      const usersWithoutIamId = !includePendingEmails
+        ? []
+        : await usersCollection
+            .find({ $or: [{ iamId: { $exists: false } }, { iamId: null }] })
+            .limit(100)
+            .project({ email: 1 })
+            .toArray();
 
       const remaining = 100 - usersWithoutIamId.length;
       let usersWithIamButNoAccount: { email?: string }[] = [];
-      if (remaining > 0) {
+      if (includePendingEmails && remaining > 0) {
         usersWithIamButNoAccount = await usersCollection
           .aggregate([
             { $match: { iamId: { $exists: true, $ne: null } } },

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

@@ -71,3 +71,29 @@ export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
  * Declared `@Optional()` in the CoreBetterAuthService constructor.
  */
 export const BETTER_AUTH_COOKIE_DOMAIN = 'BETTER_AUTH_COOKIE_DOMAIN';
+
+/**
+ * better-auth's default name for the account collection, and for the `issuer` field inside it.
+ *
+ * Both are overridable by a consumer through `betterAuth.options.account.modelName` /
+ * `.fields.issuer`, which `better-auth.config.ts` spreads onto the resolved config verbatim. Any
+ * framework code touching that collection directly MUST resolve the real names from the running
+ * instance and fall back to these — a hardcoded name silently addresses a collection better-auth
+ * does not use, which on the issuer backfill means every password user stays locked out while the
+ * operation reports success by saying nothing.
+ */
+export const DEFAULT_ACCOUNT_MODEL_NAME = 'account';
+export const DEFAULT_ACCOUNT_ISSUER_FIELD = 'issuer';
+
+/**
+ * Collection holding one-shot completion markers for boot-time data migrations, and the marker id
+ * of the `account.issuer` backfill (better-auth 1.7).
+ *
+ * The marker exists for cost, not for correctness: the backfill is idempotent and safe to repeat,
+ * but its filters (`$exists: false`, `$ne`) cannot use an index, so without a marker every boot of
+ * every replica pays a full pass over the account collection — forever, and inside the `await` that
+ * precedes `app.listen()`. Versioned in the id so a future backfill of the same field can run
+ * again without clearing this one.
+ */
+export const BACKFILL_MARKER_COLLECTION = 'better-auth-backfills';
+export const ACCOUNT_ISSUER_BACKFILL_ID = 'account-issuer-backfill-v1';

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

@@ -18,6 +18,7 @@ import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options
 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 {
@@ -25,6 +26,7 @@ import {
   BetterAuthInstance,
   CreateBetterAuthResult,
   createBetterAuthInstance,
+  OnPasswordResetCallback,
 } from './better-auth.config';
 import { DefaultBetterAuthResolver } from './better-auth.resolver';
 import { CoreBetterAuthApiMiddleware } from './core-better-auth-api.middleware';
@@ -32,6 +34,7 @@ import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.ser
 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 { 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';
@@ -261,6 +264,11 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   // Static reference to email verification service for Better-Auth hooks (outside DI context)
   private static emailVerificationService: CoreBetterAuthEmailVerificationService | null = null;
   private static mongoConnection: Connection | null = null;
+  /**
+   * Config reference for the Better-Auth callbacks, which run OUTSIDE the DI context.
+   * Set from the same factories that build the auth instance.
+   */
+  private static configServiceInstance: ConfigService | null = null;
   // Safety Net: Track if forRoot() has already been called to detect duplicate registration
   private static forRootCalled = false;
   private static cachedDynamicModule: DynamicModule | null = null;
@@ -662,12 +670,14 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
               throw new Error('MongoDB database not available');
             }
 
+            this.configServiceInstance = configService;
+
             // Get JWT secrets from config for backwards compatibility fallback
             const jwtConfig = configService.get<{ refresh?: { secret?: string }; secret?: string }>('jwt');
             const fallbackSecrets = [jwtConfig?.secret, jwtConfig?.refresh?.secret];
 
             // Create email verification callbacks that delegate to the NestJS service
-            const { onEmailVerified, sendResetPasswordEmail, sendVerificationEmail } =
+            const { onEmailVerified, onPasswordReset, sendResetPasswordEmail, sendVerificationEmail } =
               this.createEmailVerificationCallbacks();
 
             // Note: Secret validation is now handled in createBetterAuthInstance
@@ -677,6 +687,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
               db,
               fallbackSecrets,
               onEmailVerified,
+              onPasswordReset,
               sendResetPasswordEmail,
               sendVerificationEmail,
             });
@@ -814,8 +825,16 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    * They access the service via static reference since Better-Auth hooks run outside DI context.
    * @internal
    */
-  private static createEmailVerificationCallbacks(): {
+  /**
+   * `protected` rather than `private`: the callbacks it returns include `onPasswordReset`, which
+   * decides what mirroring a reset into the legacy store means for a deployment. A project with a
+   * different answer (a different store, an extra audit record, skipping it entirely) must be able
+   * to say so through the Module Inheritance Pattern rather than by reaching for
+   * `options.emailAndPassword` — which cannot replace the hook anyway, since the two are chained.
+   */
+  protected static createEmailVerificationCallbacks(): {
     onEmailVerified: (userId: string) => Promise<void>;
+    onPasswordReset: OnPasswordResetCallback;
     sendResetPasswordEmail: (options: AuthEmailCallbackOptions) => Promise<void>;
     sendVerificationEmail: (options: AuthEmailCallbackOptions) => Promise<void>;
   } {
@@ -840,6 +859,47 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           );
         }
       },
+      onPasswordReset: async ({ user }) => {
+        // Mirror the new password into the legacy bcrypt store, so a deployment running
+        // Legacy Auth next to IAM does not keep the OLD password valid on the legacy path
+        // after a reset — including a reset performed BECAUSE the old one leaked.
+        //
+        // The password is not in Better-Auth's callback payload: it comes from the API
+        // middleware through the reset registry, already normalized, i.e. byte-identical
+        // to what Better-Auth just hashed for IAM.
+        // Skip entirely where there is no legacy surface to keep in step. On an IAM-only
+        // deployment the mirror would maintain a bcrypt credential nothing ever reads, and its
+        // "the legacy password now differs" warning would name a consequence that cannot occur.
+        // Gated on the same resolver the endpoints themselves use, so the two cannot drift.
+        const legacyConfig = this.configServiceInstance?.getFastButReadOnly('auth')?.legacyEndpoints;
+        if (!isLegacyEndpointEnabled(legacyConfig, 'graphql') && !isLegacyEndpointEnabled(legacyConfig, 'rest')) {
+          return;
+        }
+
+        const normalizedPassword = getInFlightResetPassword();
+        if (!normalizedPassword) {
+          // Not a reset whose body we saw. Skipping is the only safe answer — writing a
+          // guessed hash would lock the account out of the legacy path.
+          this.logger.debug('Password reset without an in-flight password — skipping the legacy mirror.');
+          return;
+        }
+        if (!user?.email) {
+          this.logger.warn('Password reset without a user email — cannot mirror it to the legacy store.');
+          return;
+        }
+
+        const mirrored = await this.userMapperInstance?.syncPasswordToLegacy(user.id, user.email, normalizedPassword);
+        if (mirrored) {
+          this.logger.debug(`Mirrored IAM password reset to the legacy store for ${maskEmail(user.email)}`);
+        } else {
+          // Report the miss. A silent `false` here is exactly how the opposite direction of
+          // this sync stayed broken unnoticed: the endpoint answers success either way.
+          this.logger.warn(
+            `Could not mirror the IAM password reset to the legacy store for ${maskEmail(user.email)} — ` +
+              'the legacy password now differs from the IAM credential.',
+          );
+        }
+      },
       sendResetPasswordEmail: async (options) => {
         // Delegate to the NestJS service
         if (this.emailVerificationService) {
@@ -921,18 +981,20 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         {
           // Inject Mongoose Connection to ensure NestJS waits for it to be ready
           // Also inject EmailVerificationService to set static reference before Better-Auth init
-          inject: [getConnectionToken(), CoreBetterAuthEmailVerificationService],
+          inject: [getConnectionToken(), CoreBetterAuthEmailVerificationService, ConfigService],
           provide: BETTER_AUTH_INSTANCE,
           useFactory: async (
             connection: Connection,
             emailVerificationService: CoreBetterAuthEmailVerificationService,
+            configService: ConfigService,
           ) => {
             // Set static references for callbacks BEFORE creating Better-Auth instance
             this.setEmailVerificationService(emailVerificationService);
             this.mongoConnection = connection;
+            this.configServiceInstance = configService;
 
             // Create email verification callbacks that delegate to the NestJS service
-            const { onEmailVerified, sendResetPasswordEmail, sendVerificationEmail } =
+            const { onEmailVerified, onPasswordReset, sendResetPasswordEmail, sendVerificationEmail } =
               this.createEmailVerificationCallbacks();
 
             // Build shared instance options
@@ -940,6 +1002,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
               config,
               fallbackSecrets: options?.fallbackSecrets,
               onEmailVerified,
+              onPasswordReset,
               sendResetPasswordEmail,
               sendVerificationEmail,
               serverAppUrl: options?.serverAppUrl,