@lenne.tech/nest-server 11.37.0 → 11.39.0

package/src/core/modules/better-auth/core-better-auth-error-codes.helper.ts

@@ -0,0 +1,146 @@
+import { ErrorCode } from '../error-code/error-codes';
+
+/**
+ * Translate Better-Auth's own error codes into nest-server's `#LTNS_XXXX:` message format.
+ *
+ * ── Why this exists ────────────────────────────────────────────────────────────
+ * Frontends in this stack translate errors by parsing the message for nest-server's marker —
+ * `useLtErrorTranslation` matches `/^#([A-Z_]+_\d+):\s*(.+)$/` and nothing else. Better-Auth
+ * answers with `{ code: 'INVALID_TOKEN', message: 'Invalid token' }`, which carries no marker, so
+ * the parser finds no code and hands the raw string through. The end user is shown English
+ * developer text — not as an edge case, but as the NORMAL outcome of every IAM error.
+ *
+ * That is felt most on the password-reset page: a link that has expired produces `INVALID_TOKEN`,
+ * and the person who already cannot sign in is told "Invalid token" in a language the rest of the
+ * product does not use.
+ *
+ * Wrapping the message here fixes it for every consumer at once — including projects that do not
+ * use `@lenne.tech/nuxt-extensions` and would otherwise each need their own code table.
+ *
+ * ── Two rules that keep this safe ──────────────────────────────────────────────
+ * 1. The original `code` field is left ALONE. Anything keying on `code` — Better-Auth's own client,
+ *    a project's error branch — keeps working. Only the human-facing `message` is rewritten.
+ * 2. An unknown code is passed through UNCHANGED. A guessed mapping would show a confident,
+ *    wrong sentence, which is worse than an untranslated true one. New codes are added here
+ *    deliberately, not inferred.
+ *
+ * Mapping only where the meaning is unambiguous. Three deliberate absences:
+ *
+ * - `SESSION_EXPIRED` means "re-authenticate for this sensitive action", which is not what
+ *   nest-server's `TOKEN_EXPIRED` ("please sign in again") tells the user to do.
+ * - `USER_NOT_FOUND` is an account-enumeration signal. Better-Auth already exposes it as a `code`,
+ *   but translating it into the user's language would make the oracle friendlier and more legible
+ *   — the opposite direction from the rest of this release, which spent real effort closing the
+ *   legacy reset endpoint's equivalent. Left untranslated on purpose.
+ * - Anything else Better-Auth may add later. An unmapped code passes through unchanged.
+ *
+ * `PASSWORD_TOO_SHORT` / `PASSWORD_TOO_LONG` ARE mapped, and their reachability is worth stating
+ * because it is narrower than it looks: the lt frontend hashes with `ltSha256` before sending, so
+ * every password arrives as 64 hex characters and neither bound is crossed. They remain reachable
+ * for a client that does not hash (this is a framework, not only the lt stack) and for a project
+ * that configures `minPasswordLength` above 64 — which the middleware reads as a passthrough
+ * option, so it is a supported configuration rather than a hypothetical.
+ */
+const BETTER_AUTH_ERROR_CODE_MAP: Readonly<Record<string, string>> = Object.freeze({
+  EMAIL_ALREADY_VERIFIED: ErrorCode.EMAIL_ALREADY_VERIFIED,
+  EMAIL_NOT_VERIFIED: ErrorCode.EMAIL_VERIFICATION_REQUIRED,
+  INVALID_EMAIL_OR_PASSWORD: ErrorCode.INVALID_CREDENTIALS,
+  INVALID_PASSWORD: ErrorCode.INVALID_PASSWORD,
+  // Distinct codes, not LINK_INVALID_OR_EXPIRED: Better-Auth answers BOTH with HTTP 400 on
+  // `/reset-password`, so a page branching on status alone cannot tell them apart and shows "your
+  // link is dead". The user then requests a new link, pastes the same over-long passphrase from
+  // their password manager, and fails again — a closed loop that never names the cause.
+  PASSWORD_TOO_LONG: ErrorCode.PASSWORD_TOO_LONG,
+  PASSWORD_TOO_SHORT: ErrorCode.PASSWORD_TOO_SHORT,
+  // NOT ErrorCode.INVALID_TOKEN: that one is the legacy auth service's refresh/session token and
+  // reads "sign in again". Every Better-Auth INVALID_TOKEN reaches the user through a LINK in a
+  // mail — reset, verification, magic link — and telling somebody who cannot sign in to sign in is
+  // the one instruction that helps least.
+  INVALID_TOKEN: ErrorCode.LINK_INVALID_OR_EXPIRED,
+  // Also NOT ErrorCode.TOKEN_EXPIRED ("please sign in again"), for the same reason as above and
+  // with a sharper edge: Better-Auth throws TOKEN_EXPIRED in exactly ONE place — an expired
+  // verification LINK (email-verification.mjs:178) — one line above the INVALID_TOKEN it throws
+  // for a broken one. Splitting that single user action ("I clicked an old link in my mail") into
+  // two opposite instructions would be wrong in the MORE common half, since links expire far more
+  // often than they get mangled. Worse, at that point the user is typically not signed in at all,
+  // so "sign in again" is a dead end. `LINK_INVALID_OR_EXPIRED` covers expiry in its wording.
+  TOKEN_EXPIRED: ErrorCode.LINK_INVALID_OR_EXPIRED,
+  USER_ALREADY_EXISTS: ErrorCode.EMAIL_ALREADY_EXISTS,
+  USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL: ErrorCode.EMAIL_ALREADY_EXISTS,
+});
+
+/**
+ * The nest-server message for a Better-Auth error code, or `undefined` when it has no mapping.
+ *
+ * Exported so a project can reuse the same table rather than build a second one that drifts.
+ */
+export function mapBetterAuthErrorCode(code: unknown): string | undefined {
+  return typeof code === 'string' ? BETTER_AUTH_ERROR_CODE_MAP[code] : undefined;
+}
+
+/**
+ * Rewrite a failed Better-Auth response so its `message` carries nest-server's error marker.
+ *
+ * Returns the ORIGINAL response object whenever nothing should change — a successful response, a
+ * body that is not JSON, or a code with no mapping. That matters: the response body is a stream
+ * that can be read once, so handing back an untouched original rather than a rebuilt copy keeps
+ * every other consumer of it working.
+ *
+ * Never throws. An error surfacing from the error-formatting path would replace a useful message
+ * with a 500, which is the one outcome worse than an untranslated string.
+ */
+export async function wrapBetterAuthErrorResponse(response: Response): Promise<Response> {
+  if (response.ok) {
+    return response;
+  }
+
+  // A redirect is not ours to rewrite. Better-Auth reports some failures by REDIRECTING to the
+  // caller's `callbackURL` with `?error=<CODE>` (see `redirectOnError` in its email-verification
+  // route) — a 3xx with no JSON body, so there is no message to translate. Rewriting the code in
+  // that query string instead would invent a second contract on top of Better-Auth's documented
+  // one, which the frontend reads. Those cases stay untranslated on purpose, and the frontend maps
+  // `?error=` itself.
+  if (response.status >= 300 && response.status < 400) {
+    return response;
+  }
+
+  try {
+    const body = await response.clone().json();
+    const mapped = mapBetterAuthErrorCode(body?.code);
+
+    // No mapping, or a message that already carries the marker (a nest-server exception that
+    // travelled through Better-Auth): leave it exactly as it is.
+    if (!mapped || typeof body?.message !== 'string' || body.message.startsWith('#')) {
+      return response;
+    }
+
+    const headers = new Headers();
+
+    // `set-cookie` FIRST, and via getSetCookie/append rather than the forEach below. `forEach`
+    // yields each cookie separately and `set()` overwrites, so a response carrying two of them
+    // would keep only the last. Better-Auth CLEARS session and 2FA cookies on several failure
+    // paths — exactly the responses this function rewrites — so collapsing them leaves a stale
+    // credential in the browser. `sendWebResponse` uses getSetCookie() for the same reason.
+    for (const cookie of response.headers.getSetCookie?.() ?? []) {
+      headers.append('set-cookie', cookie);
+    }
+
+    response.headers.forEach((value, key) => {
+      const lower = key.toLowerCase();
+      // content-length: the rewritten body has a different length, and a stale one truncates the
+      // response. set-cookie: already appended above, and `set()` here would undo that.
+      if (lower !== 'content-length' && lower !== 'set-cookie') {
+        headers.set(key, value);
+      }
+    });
+
+    return new Response(JSON.stringify({ ...body, message: mapped }), {
+      headers,
+      status: response.status,
+      statusText: response.statusText,
+    });
+  } catch {
+    // Not JSON, or an unreadable body. The original is still the best answer available.
+    return response;
+  }
+}

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

@@ -57,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
  */
@@ -340,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() } },
@@ -976,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 {
@@ -1004,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
@@ -1047,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.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,

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

@@ -31,6 +31,7 @@ export * from './core-better-auth-api.middleware';
 export * from './core-better-auth-auth.model';
 export * from './core-better-auth-cookie.helper';
 export * from './core-better-auth-email-verification.service';
+export * from './core-better-auth-error-codes.helper';
 export * from './core-better-auth-migration-status.model';
 export * from './core-better-auth-models';
 export * from './core-better-auth-rate-limit.middleware';

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

@@ -287,6 +287,61 @@ export const LtnsErrors = {
     },
   },
 
+  /**
+   * A link the user followed from an email is invalid, already used, or expired.
+   *
+   * Deliberately SEPARATE from `INVALID_TOKEN` (LTNS_0003), which the legacy auth service uses for
+   * refresh/session tokens. Those two look alike to a developer and are opposites to a user: one
+   * means "your session ended, sign in again", the other means "the link in your mail is dead,
+   * request another". Telling somebody who cannot sign in to sign in is the worse of the two.
+   *
+   * Deliberately BROADER than `EMAIL_VERIFICATION_TOKEN_INVALID` (LTNS_0024), because the
+   * underlying `INVALID_TOKEN` from Better-Auth covers password reset, email verification and
+   * magic links alike, and cannot tell them apart.
+   *
+   * "nicht (mehr) gültig" covers unknown AND expired on purpose: Better-Auth answers both with the
+   * same code, so a message claiming to know which one would be guessing half the time.
+   */
+  /**
+   * The submitted password is outside the configured length bounds.
+   *
+   * Separate codes rather than one "does not meet requirements", because the recipient can only
+   * act on a message that names the direction. Better-Auth answers `PASSWORD_TOO_LONG` with the
+   * same HTTP 400 it uses for an invalid token, so without a distinct code a reset page shows
+   * "this link is no longer valid" — the user requests a new link, pastes the same over-long
+   * passphrase from their password manager, and fails again. A closed loop with no hint at the
+   * cause.
+   *
+   * The numbers are Better-Auth's defaults (8 / 128) and a project may configure others; the text
+   * therefore names the common case rather than claiming to know the deployment's bounds.
+   */
+  PASSWORD_TOO_LONG: {
+    code: 'LTNS_0028',
+    message: 'Password exceeds the maximum length',
+    translations: {
+      de: 'Das Passwort ist zu lang. Erlaubt sind standardmäßig höchstens 128 Zeichen.',
+      en: 'The password is too long. The default maximum is 128 characters.',
+    },
+  },
+
+  PASSWORD_TOO_SHORT: {
+    code: 'LTNS_0029',
+    message: 'Password is below the minimum length',
+    translations: {
+      de: 'Das Passwort ist zu kurz. Erforderlich sind standardmäßig mindestens 8 Zeichen.',
+      en: 'The password is too short. The default minimum is 8 characters.',
+    },
+  },
+
+  LINK_INVALID_OR_EXPIRED: {
+    code: 'LTNS_0027',
+    message: 'Link is invalid or expired',
+    translations: {
+      de: 'Dieser Link ist nicht (mehr) gültig. Bitte fordern Sie einen neuen an.',
+      en: 'This link is no longer valid. Please request a new one.',
+    },
+  },
+
   // =====================================================
   // Authorization Errors (LTNS_0100-LTNS_0199)
   // =====================================================

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

@@ -20,6 +20,7 @@ const FRAMEWORK_SECRET_FIELDS = [
   'password',
   'verificationToken',
   'passwordResetToken',
+  'passwordResetTokenExpiresAt',
   'refreshTokens',
   'tempTokens',
   'apiKeyEncrypted',

package/src/core/modules/user/core-user.model.ts

@@ -95,11 +95,38 @@ export abstract class CoreUserModel extends CorePersistenceModel {
    */
   @UnifiedField({
     isOptional: true,
-    mongoose: true,
+    // PARTIAL, not plain and not sparse. `findOne({ passwordResetToken: token })` runs on an
+    // unauthenticated, unrated endpoint, and without an index every call is a full collection scan
+    // of `users` — the dominant cost of that path and an easy amplifier for a request loop.
+    // Sparse would be wrong: the reset path clears the field by UNSETTING it, but a document that
+    // once held `null` would still count as present, so the index would accumulate an entry for
+    // every user who ever requested a reset. The `$type: 'string'` predicate keeps it to the rows
+    // that can actually match.
+    //
+    // NEVER give the companion `passwordResetTokenExpiresAt` a TTL index: it is a Date, and a TTL
+    // index there would delete the USER DOCUMENT rather than the token.
+    mongoose: { index: { partialFilterExpression: { passwordResetToken: { $type: 'string' } } } },
     roles: RoleEnum.S_NO_ONE,
   })
   passwordResetToken: string = undefined;
 
+  /**
+   * When the current password-reset token stops being valid.
+   *
+   * `S_NO_ONE` like the token itself: it never belongs in a response, and revealing that a reset is
+   * pending is information an account holder gains nothing from and an attacker does.
+   *
+   * A user document written before 11.38.0 has no value here, and the reset path treats that as
+   * expired — see `IAuthPasswordReset.tokenExpiresInMinutes` for why that direction was chosen.
+   */
+  @UnifiedField({
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.S_NO_ONE,
+    type: () => Date,
+  })
+  passwordResetTokenExpiresAt: Date = undefined;
+
   /**
    * Refresh tokens (for devices)
    * key: Token