@lenne.tech/nest-server 11.37.0 → 11.39.0

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

@@ -1,8 +1,9 @@
 import { createHash } from 'crypto';
-import { Inject, Injectable, OnModuleDestroy, Optional } from '@nestjs/common';
+import { Inject, Injectable, Logger, OnModuleDestroy, Optional } from '@nestjs/common';
 import nodemailer = require('nodemailer');
 import { Attachment } from 'nodemailer/lib/mailer';
 
+import { isImpossibleSmtpTlsCombination } from '../helpers/config.helper';
 import { isNonEmptyString, isTrue, returnFalse } from '../helpers/input.helper';
 import { MailTransportOptions } from '../interfaces/server-options.interface';
 import { HUB_EMAIL_CAPTURE } from '../../modules/hub/hub.constants';
@@ -22,6 +23,11 @@ export class EmailService implements OnModuleDestroy {
   private cachedTransporter: nodemailer.Transporter | null = null;
   private cachedSmtpConfig: string | null = null;
 
+  protected readonly emailServiceLogger = new Logger(EmailService.name);
+
+  /** Once-per-process latch for the SMTP TLS warning — a per-send warning would be noise. */
+  private smtpTlsWarningEmitted = false;
+
   /**
    * Inject services
    */
@@ -33,6 +39,43 @@ export class EmailService implements OnModuleDestroy {
     @Optional() @Inject(HUB_EMAIL_CAPTURE) protected readonly emailCapture?: IHubEmailCapture,
   ) {}
 
+  /**
+   * Warn once when the SMTP port and TLS mode describe a connection that cannot be established.
+   *
+   * `secure: true` means implicit TLS, which only port 465 speaks. On 587 — the submission port,
+   * which upgrades through STARTTLS — nodemailer sends a TLS ClientHello, the server answers with
+   * an SMTP greeting, and OpenSSL reports `wrong version number`. This package's own `production`
+   * profile shipped that pair, and because authentication mail is deliberately not awaited, the
+   * API answered 200 while every message died in transport. It was found in production.
+   *
+   * Reported rather than corrected: a deployment may legitimately run submission on a non-standard
+   * port, and silently overriding an explicit setting is how the original defect stayed invisible.
+   * A warning names the problem without deciding it.
+   */
+  protected warnOnImpossibleSmtpTlsCombination(smtp: unknown): void {
+    if (this.smtpTlsWarningEmitted || typeof smtp !== 'object' || smtp === null) {
+      return;
+    }
+
+    const { port, secure } = smtp as { port?: unknown; secure?: unknown };
+    if (typeof port !== 'number' || typeof secure !== 'boolean') {
+      return;
+    }
+
+    if (!isImpossibleSmtpTlsCombination(port, secure)) {
+      return;
+    }
+
+    this.smtpTlsWarningEmitted = true;
+    this.emailServiceLogger.warn(
+      `SMTP is configured with port ${port} and secure: ${secure}, a combination that cannot connect. ` +
+        '`secure: true` starts TLS immediately, which only port 465 supports; port 587 and friends open in ' +
+        'plaintext and upgrade via STARTTLS, which needs `secure: false`. Expect ' +
+        '"wrong version number" from OpenSSL and NO outgoing mail — silently, because authentication mail ' +
+        'is not awaited. Set SMTP_SECURE=false for port 587, or SMTP_PORT=465 to keep implicit TLS.',
+    );
+  }
+
   onModuleDestroy(): void {
     if (this.cachedTransporter) {
       this.cachedTransporter.close();
@@ -109,6 +152,8 @@ export class EmailService implements OnModuleDestroy {
       }
     }
 
+    this.warnOnImpossibleSmtpTlsCombination(smtp);
+
     // Hub mailbox capture (Mailpit-style). Runs after templates are rendered, before the transport.
     // In capture mode it records the mail and suppresses the send (returns a jsonTransport-like ack).
     // Fully guarded: a broken mailbox hook must never break (or crash) the mail path.

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

@@ -177,6 +177,7 @@ export abstract class ModuleService<T extends CoreModel = any> {
             'password',
             'verificationToken',
             'passwordResetToken',
+            'passwordResetTokenExpiresAt',
             'refreshTokens',
             'tempTokens',
           ]);

package/src/core/modules/auth/README.md

@@ -0,0 +1,104 @@
+# Auth Module (Legacy Auth)
+
+JWT-based email/password authentication: `signIn`, `signUp`, `logout`, `refreshToken` over GraphQL,
+and `POST /auth/signin`, `/auth/signup`, `/auth/logout`, `/auth/refresh-token` over REST.
+
+> **This module is deprecated in favour of IAM (Better-Auth) and will be removed.** Since 11.38.0
+> its endpoints are **off unless explicitly enabled**. New projects should not register it — the
+> one-argument `CoreModule.forRoot(envConfig)` never does. See
+> [`.claude/rules/module-deprecation.md`](../../../../.claude/rules/module-deprecation.md) for the
+> migration path.
+
+## When this module exists at all
+
+Only when a project passes the three-argument form:
+
+```typescript
+CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig);
+```
+
+The one-argument form (`CoreModule.forRoot(envConfig)`) registers IAM only, and nothing in this
+directory is loaded. If you are reading this while planning a new project, that is the form you
+want.
+
+## Enabling the endpoints
+
+Registering the module is no longer enough. Since 11.38.0 the endpoints answer **HTTP 410 Gone**
+until asked for:
+
+```typescript
+// config.env.ts
+auth: {
+  legacyEndpoints: { enabled: true },   // or LEGACY_AUTH_ENABLED=true
+},
+```
+
+The default flipped because a second, fully functional password-authentication surface that nobody
+chose is a liability: it is served by `CoreAuthService` rather than Better-Auth, so it bypasses
+every IAM-side control an operator may believe is now in force — two-factor, passkey enforcement,
+Better-Auth session revocation.
+
+Resolution is one exported function, `isLegacyEndpointEnabled(config, transport)`, shared by both
+transports so they cannot answer differently:
+
+| Configuration                               | Result                               |
+| ------------------------------------------- | ------------------------------------ |
+| `enabled: false`                            | off, whatever `graphql` / `rest` say |
+| per-transport flag set (`graphql` / `rest`) | that flag wins                       |
+| `enabled: true`                             | on                                   |
+| nothing set                                 | **off**                              |
+
+An explicit `enabled: false` is a hard off switch that a per-transport `true` cannot reopen — it is
+the setting a project reached for to close legacy down, and an upgrade must never widen it.
+
+## Knowing when you can turn it off
+
+`CoreLegacyAuthDeprecationInitializer` reports at every boot, in both directions:
+
+- while any endpoint is open: a deprecation warning plus the IAM migration percentage,
+- while all are closed but users are still unmigrated: a warning that those users cannot sign in,
+  naming the way back.
+
+Both are best-effort — the status read runs detached from the boot so it cannot delay readiness.
+The same figures are available on demand through the `betterAuthMigrationStatus` query
+(`canDisableLegacyAuth` is the signal to act on).
+
+## Relationship to IAM while both run
+
+The two systems share one user collection and keep each other's credentials in step:
+
+| Event                                       | Written by      | Mirrored into                         |
+| ------------------------------------------- | --------------- | ------------------------------------- |
+| Sign-up via IAM                             | IAM (scrypt)    | legacy (bcrypt)                       |
+| Sign-up via Legacy                          | legacy (bcrypt) | IAM, on first IAM sign-in (migration) |
+| Password reset via the legacy user endpoint | legacy          | IAM                                   |
+| Password reset via IAM                      | IAM             | legacy (11.38.0+)                     |
+| Password change via `update()`              | legacy          | IAM                                   |
+
+`CoreAuthService.signIn` **delegates to IAM** as soon as a user carries an `iamId`, so for a
+migrated user both endpoints answer from the IAM credential. That is worth knowing when debugging:
+a stale legacy bcrypt hash is invisible through either API and only surfaces if IAM is switched
+off.
+
+Hash formats differ irreversibly (`bcrypt(sha256(pw))` vs `scrypt(sha256(pw))`), which is why the
+mirrors exist rather than a one-off migration script.
+
+## Extending
+
+Standard Module Inheritance Pattern. Both endpoint guards are `protected` and must be called from
+an override:
+
+| Class                | Method to call                    |
+| -------------------- | --------------------------------- |
+| `CoreAuthResolver`   | `checkLegacyGraphQLEnabled(name)` |
+| `CoreAuthController` | `checkLegacyRESTEnabled(name)`    |
+
+Forgetting one re-opens a disabled endpoint. Use the exported `isLegacyEndpointEnabled()` rather
+than re-implementing the table if you override the check itself.
+
+## Related
+
+- [`.claude/rules/module-deprecation.md`](../../../../.claude/rules/module-deprecation.md) — the migration roadmap
+- [`.claude/rules/role-system.md`](../../../../.claude/rules/role-system.md) — `@Roles` vs `@UseGuards`, and why `refreshToken` is the one place `@UseGuards` is still required
+- [`../better-auth/README.md`](../better-auth/README.md) — the system replacing this one
+- [`../better-auth/INTEGRATION-CHECKLIST.md`](../better-auth/INTEGRATION-CHECKLIST.md) — integrating IAM

package/src/core/modules/auth/core-auth.controller.ts

@@ -22,6 +22,7 @@ import { CoreAuthModel } from './core-auth.model';
 import { LegacyAuthDisabledException } from './exceptions/legacy-auth-disabled.exception';
 import { AuthGuard } from './guards/auth.guard';
 import { LegacyAuthRateLimitGuard } from './guards/legacy-auth-rate-limit.guard';
+import { isLegacyEndpointEnabled } from './helpers/legacy-endpoints.helper';
 import { CoreAuthSignInInput } from './inputs/core-auth-sign-in.input';
 import { CoreAuthSignUpInput } from './inputs/core-auth-sign-up.input';
 import { ICoreAuthUser } from './interfaces/core-auth-user.interface';
@@ -70,23 +71,15 @@ export class CoreAuthController {
   /**
    * Check if legacy REST endpoints are enabled
    *
-   * Throws LegacyAuthDisabledException if:
-   * - config.auth.legacyEndpoints.enabled is false
-   * - config.auth.legacyEndpoints.rest is false
+   * Since 11.38.0 legacy endpoints are OFF unless a project asks for them — see
+   * `isLegacyEndpointEnabled()` for the full resolution table.
    *
    * @throws LegacyAuthDisabledException
    */
   protected checkLegacyRESTEnabled(endpointName: string): void {
     const authConfig = this.configService.getFastButReadOnly('auth');
-    const legacyConfig = authConfig?.legacyEndpoints;
 
-    // Check if legacy endpoints are globally disabled
-    if (legacyConfig?.enabled === false) {
-      throw new LegacyAuthDisabledException(endpointName);
-    }
-
-    // Check if REST endpoints specifically are disabled
-    if (legacyConfig?.rest === false) {
+    if (!isLegacyEndpointEnabled(authConfig?.legacyEndpoints, 'rest')) {
       throw new LegacyAuthDisabledException(endpointName);
     }
   }

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

@@ -12,6 +12,7 @@ import { RolesGuardRegistry } from './guards/roles-guard-registry';
 import { RolesGuard } from './guards/roles.guard';
 import { CoreAuthUserService } from './services/core-auth-user.service';
 import { CoreAuthService } from './services/core-auth.service';
+import { CoreLegacyAuthDeprecationInitializer } from './core-legacy-auth-deprecation.initializer';
 import { LegacyAuthRateLimiter } from './services/legacy-auth-rate-limiter.service';
 import { JwtRefreshStrategy } from './strategies/jwt-refresh.strategy';
 import { JwtStrategy } from './strategies/jwt.strategy';
@@ -64,6 +65,10 @@ export class CoreAuthModule {
     let providers: any[] = [
       // [Global] The GraphQLAuthGuard integrates the user into context
       ...rolesGuardProvider,
+      // Reports at boot that this deployment still exposes Legacy Auth, and how far the
+      // IAM migration has come. Registered here because this module exists only in
+      // legacy mode — an IAM-only project never loads it.
+      CoreLegacyAuthDeprecationInitializer,
       {
         provide: CoreAuthUserService,
         useClass: UserService,

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

@@ -15,6 +15,7 @@ import { CoreAuthModel } from './core-auth.model';
 import { LegacyAuthDisabledException } from './exceptions/legacy-auth-disabled.exception';
 import { AuthGuard } from './guards/auth.guard';
 import { LegacyAuthRateLimitGuard } from './guards/legacy-auth-rate-limit.guard';
+import { isLegacyEndpointEnabled } from './helpers/legacy-endpoints.helper';
 import { CoreAuthSignInInput } from './inputs/core-auth-sign-in.input';
 import { CoreAuthSignUpInput } from './inputs/core-auth-sign-up.input';
 import { ICoreAuthUser } from './interfaces/core-auth-user.interface';
@@ -62,23 +63,15 @@ export class CoreAuthResolver {
   /**
    * Check if legacy GraphQL endpoints are enabled
    *
-   * Throws LegacyAuthDisabledException if:
-   * - config.auth.legacyEndpoints.enabled is false
-   * - config.auth.legacyEndpoints.graphql is false
+   * Since 11.38.0 legacy endpoints are OFF unless a project asks for them — see
+   * `isLegacyEndpointEnabled()` for the full resolution table.
    *
    * @throws LegacyAuthDisabledException
    */
   protected checkLegacyGraphQLEnabled(endpointName: string): void {
     const authConfig = this.configService.getFastButReadOnly('auth');
-    const legacyConfig = authConfig?.legacyEndpoints;
 
-    // Check if legacy endpoints are globally disabled
-    if (legacyConfig?.enabled === false) {
-      throw new LegacyAuthDisabledException(endpointName);
-    }
-
-    // Check if GraphQL endpoints specifically are disabled
-    if (legacyConfig?.graphql === false) {
+    if (!isLegacyEndpointEnabled(authConfig?.legacyEndpoints, 'graphql')) {
       throw new LegacyAuthDisabledException(endpointName);
     }
   }

package/src/core/modules/auth/core-legacy-auth-deprecation.initializer.ts

@@ -0,0 +1,128 @@
+import { Injectable, Logger, OnApplicationBootstrap, Optional } from '@nestjs/common';
+
+import { ConfigService } from '../../common/services/config.service';
+import { CoreBetterAuthUserMapper } from '../better-auth/core-better-auth-user.mapper';
+import { isLegacyEndpointEnabled } from './helpers/legacy-endpoints.helper';
+
+/**
+ * Says out loud, once at boot, that this deployment still exposes Legacy Auth.
+ *
+ * WHY THIS EXISTS
+ *
+ * Legacy Auth is superseded by IAM (Better-Auth) and slated for removal (see
+ * `.claude/rules/module-deprecation.md`). Until 11.38.0 nothing ever mentioned that a
+ * project was still running it: `auth.legacyEndpoints.enabled` defaulted to `true`, so a
+ * second fully functional password-authentication surface stayed open by inertia, and
+ * `betterAuthMigrationStatus.canDisableLegacyAuth` — which exists precisely to say when
+ * it can be closed — only answered when somebody thought to ask.
+ *
+ * Registered only by `CoreAuthModule`, which exists only when a project passes the
+ * legacy three-argument `CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(...),
+ * envConfig)`. An IAM-only project never sees any of this.
+ *
+ * It only REPORTS. Turning legacy auth off for a project that still needs it would lock
+ * out every user who has not signed in through IAM yet, which is the opposite of a safe
+ * default — the migration has to be finished before the door closes, and only the
+ * operator can know when that is.
+ */
+@Injectable()
+export class CoreLegacyAuthDeprecationInitializer implements OnApplicationBootstrap {
+  protected readonly logger = new Logger(CoreLegacyAuthDeprecationInitializer.name);
+
+  constructor(
+    protected readonly configService: ConfigService,
+    @Optional() protected readonly userMapper?: CoreBetterAuthUserMapper,
+  ) {}
+
+  onApplicationBootstrap(): void {
+    const legacyConfig = this.configService.getFastButReadOnly('auth')?.legacyEndpoints;
+    const graphqlOn = isLegacyEndpointEnabled(legacyConfig, 'graphql');
+    const restOn = isLegacyEndpointEnabled(legacyConfig, 'rest');
+
+    if (!graphqlOn && !restOn) {
+      // Every endpoint is closed. That is the state the migration aims at — but it is only
+      // GOOD if the migration is actually finished, and 11.38.0 made this the DEFAULT. So a
+      // project that upgraded without deciding lands here whether or not its users can still
+      // sign in.
+      //
+      // Reporting only the enabled case would mean the warning fires in the safe state and
+      // stays silent in the dangerous one. This branch says the other half: you just closed a
+      // door some of your users still need.
+      void this.reportLockoutRisk();
+      return;
+    }
+
+    const surfaces = [graphqlOn && 'GraphQL', restOn && 'REST'].filter(Boolean).join(' + ');
+    this.logger.warn(
+      `Legacy Auth is ENABLED (${surfaces}). It is deprecated in favour of IAM (Better-Auth) and will be removed. ` +
+        'Close it with auth.legacyEndpoints.enabled: false once your users are migrated.',
+    );
+
+    // Say how far the migration actually is, so the warning carries a next step rather
+    // than just a verdict.
+    //
+    // Deliberately NOT awaited. Nest waits for every onApplicationBootstrap hook before
+    // `listen()` resolves, and `getMigrationStatus()` is collection-scale work — so awaiting it
+    // would add to time-to-ready on every pod of every rolling deploy, for a log line. A
+    // readiness probe that fails while the server counts users is a worse outcome than a
+    // warning that arrives a second late.
+    void this.reportMigrationStatus();
+  }
+
+  /**
+   * Warns when legacy auth is closed while users still depend on it.
+   *
+   * The counterpart to the deprecation warning: that one fires when the door is open, this one
+   * when it was just shut on people who cannot get in any other way. Best-effort and detached
+   * from the boot, for the same reason as {@link reportMigrationStatus}.
+   */
+  protected async reportLockoutRisk(): Promise<void> {
+    try {
+      const status = await this.userMapper?.getMigrationStatus?.({ includePendingEmails: false });
+      if (!status || status.totalUsers === 0 || status.canDisableLegacyAuth) {
+        return;
+      }
+
+      this.logger.warn(
+        `Legacy Auth is DISABLED, but only ${status.fullyMigratedUsers}/${status.totalUsers} users ` +
+          `(${status.migrationPercentage}%) are migrated to IAM — the rest cannot sign in at all. ` +
+          'Set auth.legacyEndpoints.enabled: true (LEGACY_AUTH_ENABLED=true) until this reaches 100%.',
+      );
+    } catch (error) {
+      this.logger.debug(
+        `Could not read the IAM migration status: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
+
+  /**
+   * Reads and logs the IAM migration progress. Best-effort by construction: it runs detached
+   * from the boot, and a failure is reported at debug level rather than surfaced.
+   */
+  protected async reportMigrationStatus(): Promise<void> {
+    try {
+      // `includePendingEmails: false` — this reporter needs the counts, never the addresses.
+      // Collecting them costs two more collection-scale queries, one a guaranteed COLLSCAN,
+      // and handling PII that is then discarded.
+      const status = await this.userMapper?.getMigrationStatus?.({ includePendingEmails: false });
+      if (!status) {
+        return;
+      }
+      if (status.canDisableLegacyAuth) {
+        this.logger.warn(
+          `All ${status.totalUsers} users are migrated to IAM — Legacy Auth can be switched off now ` +
+            '(auth.legacyEndpoints.enabled: false).',
+        );
+      } else {
+        this.logger.log(
+          `IAM migration status: ${status.fullyMigratedUsers}/${status.totalUsers} users migrated ` +
+            `(${status.migrationPercentage}%). Legacy Auth stays required until this reaches 100%.`,
+        );
+      }
+    } catch (error) {
+      this.logger.debug(
+        `Could not read the IAM migration status: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
+}

package/src/core/modules/auth/helpers/legacy-endpoints.helper.ts

@@ -0,0 +1,69 @@
+import type { IAuthLegacyEndpoints } from '../../../common/interfaces/server-options.interface';
+
+/**
+ * The two transports legacy auth is reachable over.
+ */
+export type LegacyEndpointTransport = 'graphql' | 'rest';
+
+/**
+ * Decides whether the legacy auth endpoints are reachable over one transport.
+ *
+ * ONE resolver for both transports on purpose: the GraphQL resolver and the REST
+ * controller each carried their own copy of this decision, and a rule about which auth
+ * endpoints exist is exactly the kind of rule that must not be able to answer
+ * differently depending on which door somebody knocks on.
+ *
+ * **Since 11.38.0 the default is OFF.** Legacy auth is superseded by IAM
+ * (Better-Auth), which every project created from the starter has used for a while:
+ * `CoreModule.forRoot(envConfig)` never registers the legacy module at all. What
+ * changed is the answer for a project that DOES register it and never made a decision
+ * about `legacyEndpoints` — previously it kept a second, fully functional
+ * password-authentication surface open indefinitely, silently. A second way in that
+ * nobody chose is a liability, so it now has to be asked for.
+ *
+ * Resolution order:
+ *
+ * | Configuration | Result |
+ * |---------------|--------|
+ * | `enabled: false` | off, whatever the per-transport flags say |
+ * | per-transport flag set (`graphql` / `rest`) | that flag wins |
+ * | `enabled: true` | on |
+ * | nothing set | **off** (was: on, before 11.38.0) |
+ *
+ * `enabled: false` stays a hard off switch rather than something a per-transport `true`
+ * can reopen: it is the setting a project reached for to close legacy down, and an
+ * upgrade must never widen it.
+ *
+ * @param legacyConfig the `auth.legacyEndpoints` config block, if any
+ * @param transport which transport is asking
+ * @returns `true` when the legacy endpoints are reachable over that transport, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * // In a project that overrides the check on its own resolver
+ * protected override checkLegacyGraphQLEnabled(endpointName: string): void {
+ *   const legacyConfig = this.configService.getFastButReadOnly('auth')?.legacyEndpoints;
+ *   if (!isLegacyEndpointEnabled(legacyConfig, 'graphql')) {
+ *     throw new LegacyAuthDisabledException(endpointName);
+ *   }
+ * }
+ * ```
+ *
+ * Call this rather than re-implementing the table: the two transports resolving the same rule
+ * differently is the defect the shared function exists to prevent.
+ */
+export function isLegacyEndpointEnabled(
+  legacyConfig: IAuthLegacyEndpoints | undefined,
+  transport: LegacyEndpointTransport,
+): boolean {
+  if (legacyConfig?.enabled === false) {
+    return false;
+  }
+
+  const perTransport = legacyConfig?.[transport];
+  if (typeof perTransport === 'boolean') {
+    return perTransport;
+  }
+
+  return legacyConfig?.enabled === true;
+}

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -135,8 +135,13 @@ The `CoreBetterAuthUserMapper` enables bidirectional password synchronization:
 
 - User signs up via BetterAuth → password synced to Legacy Auth (bcrypt hash)
 - User changes password → synced between both systems
+- User resets via IAM → mirrored into the legacy store (11.38.0+; see Password Reset below)
+- User resets via the legacy user endpoint → synced into the IAM credential
 - **Without this, users can only authenticate via ONE system!**
 
+The mapper is also what the IAM→legacy reset mirror runs through. Without it registered, that
+mirror is skipped — the reset itself still succeeds, and a warning names the divergence.
+
 ---
 
 ### 5. Update ServerModule
@@ -315,6 +320,23 @@ Check these four things when integrating:
       60 s), which is the axis that matters against mail-bombing one victim from rotating IPs.
 - [ ] **Your reset page exists and points at `POST /iam/reset-password`** with `{ token, newPassword }`.
       Tokens are valid for 1 h by default.
+- [ ] **The IAM→legacy mirror is wired (11.38.0+).** `emailAndPassword.onPasswordReset` mirrors an
+      applied IAM reset into the legacy bcrypt store, for every native reset route (token,
+      email-OTP, phone-number), so a deployment running both systems does not keep the OLD
+      password valid on the legacy path — including after a reset performed _because_ it leaked.
+      Automatic, but it needs `CoreBetterAuthUserMapper` resolvable (see above), and it is skipped
+      entirely when no legacy endpoint is enabled. A skipped mirror logs
+      `Could not mirror the IAM password reset to the legacy store` — if you see that, the mapper
+      is missing, not the reset.
+- [ ] **You did not add your own `options.emailAndPassword.onPasswordReset`** expecting it to
+      replace the framework's. It cannot: the two are CHAINED, framework first. That is
+      deliberate — a project hook is an addition, never a way to silently switch off credential-
+      store parity.
+- [ ] **Password length is enforced client-side too.** The middleware normalizes a plaintext reset
+      password to sha256 before Better-Auth sees it, so Better-Auth's own
+      `minPasswordLength`/`maxPasswordLength` cannot fire. nest-server checks the raw value it
+      receives — but a client that hashes before sending (every lt frontend does) presents a
+      64-hex string that carries no length information. The policy has to live in the form.
 - [ ] **`trustedOrigins` contains no wildcard.** `redirectTo` is validated against it and the reset
       redirect carries the token, so a wildcard hands a live token to any origin it admits. The
       framework warns at boot if it finds one.

package/src/core/modules/better-auth/README.md

@@ -1745,23 +1745,37 @@ When both Legacy Auth and BetterAuth (IAM) are active, passwords are automatical
 | Sign up via BetterAuth          | IAM    | Legacy | ✅ Yes                  |
 | Sign up via Legacy Auth         | Legacy | IAM    | ⚠️ On first IAM sign-in |
 | Password reset via Legacy       | Legacy | IAM    | ✅ Yes                  |
-| Password reset via BetterAuth   | IAM    | Legacy | ⚠️ See below            |
+| Password reset via BetterAuth   | IAM    | Legacy | ✅ Yes (since 11.38.0)  |
 | Password change via user update | Legacy | IAM    | ✅ Yes                  |
 
 #### IAM Password Reset → Legacy Sync
 
-When a user resets their password via BetterAuth's native `/iam/reset-password` endpoint, the password is hashed with scrypt before storage. Since we don't have access to the plain password after hashing, we **cannot** automatically sync to Legacy Auth.
+**Automatic since 11.38.0. No configuration, and nothing to implement.**
 
-**Solutions:**
+This used to be the one direction the framework could not cover, on the reasoning that the
+plain password is gone once BetterAuth has hashed it with scrypt. That is true of the hash,
+but the password is still in the request — and the two halves needed to mirror it are simply
+known in two different places:
 
-1. **Recommended: Custom Password Reset Flow**
-   Override the password reset to capture the plain password for sync. See [Custom Password Reset with Sync](#custom-password-reset-with-sync).
+| half                     | known by                                                                 |
+| ------------------------ | ------------------------------------------------------------------------ |
+| the new password         | `CoreBetterAuthApiMiddleware`, which sees the request body               |
+| which user it belongs to | `emailAndPassword.onPasswordReset`, which BetterAuth calls with the user |
 
-2. **Use Legacy Password Reset Only**
-   Direct users to the Legacy Auth password reset flow, which syncs to IAM automatically.
+The middleware normalizes the password on the native reset routes and puts it on an
+`AsyncLocalStorage` context scoped to exactly that handler call
+(`core-better-auth-password-reset.registry.ts`); the `onPasswordReset` hook reads it there and
+calls `syncPasswordToLegacy()`. The mirror therefore covers **every** native reset route —
+token, email-OTP and phone-number — and writes the same value BetterAuth just hashed, so the
+two stores cannot drift.
 
-3. **Re-authenticate After Reset**
-   After IAM password reset, users can sign in via IAM. On next Legacy sign-in attempt, they'll need to reset via Legacy too.
+Failure is non-fatal by design: the hook is wrapped, and a failed mirror is logged rather than
+turned into a failed reset. The IAM credential is already written at that point, and telling a
+user their reset did not work when it half did is the worse outcome.
+
+> **Why this matters beyond convenience.** Before 11.38.0 a reset performed _because a password
+> leaked_ left that password valid on the legacy path. Two stores that disagree about a
+> credential is not an inconvenience — it is the old password still working somewhere.
 
 ### Automatic Sync (No Configuration Required)
 
@@ -1982,57 +1996,16 @@ await betterAuthUserMapper.migrateAccountToIam(email, plainPassword);
 
 ### Custom Password Reset with Sync
 
-To enable bidirectional password reset sync, implement a custom password reset endpoint that captures the plain password and syncs to both systems:
-
-```typescript
-// src/server/modules/better-auth/better-auth.controller.ts
-import { Body, Controller, Post } from '@nestjs/common';
-import { CoreBetterAuthController, CoreBetterAuthUserMapper, Roles, RoleEnum } from '@lenne.tech/nest-server';
-
-@Controller('iam')
-export class BetterAuthController extends CoreBetterAuthController {
-  constructor(
-    // ... other dependencies
-    private readonly betterAuthUserMapper: CoreBetterAuthUserMapper,
-  ) {
-    super(...);
-  }
-
-  /**
-   * Custom password reset that syncs to both auth systems
-   */
-  @Post('reset-password-sync')
-  @Roles(RoleEnum.S_EVERYONE)
-  async resetPasswordWithSync(
-    @Body() input: { token: string; newPassword: string },
-  ): Promise<{ success: boolean }> {
-    // 1. Reset password via BetterAuth native API
-    const api = this.betterAuthService.getApi();
-    await api.resetPassword({
-      body: { token: input.token, newPassword: input.newPassword },
-    });
-
-    // 2. Sync to Legacy Auth using the plain password
-    // Get user email from the token (you may need to decode it or lookup)
-    const userEmail = await this.getUserEmailFromToken(input.token);
-    if (userEmail) {
-      await this.betterAuthUserMapper.syncPasswordToLegacy(
-        '', // iamUserId not needed for email lookup
-        userEmail,
-        input.newPassword,
-      );
-    }
-
-    return { success: true };
-  }
+**Retired in 11.38.0 — do not build this.** This section used to carry a custom
+`reset-password-sync` controller endpoint, because the framework could not mirror an IAM reset
+into the legacy store. It now does, automatically, for every native reset route (see
+[IAM Password Reset → Legacy Sync](#iam-password-reset--legacy-sync)).
 
-  private async getUserEmailFromToken(token: string): Promise<string | null> {
-    // Implementation depends on your token structure
-    // You may need to query the database or decode the token
-    return null;
-  }
-}
-```
+Re-implementing it is now actively harmful: the middleware has already normalized the body, so
+a hand-rolled endpoint that calls `normalizePasswordForIam()` again would hash an
+already-hashed value and store a credential nothing can verify. If you carry such an override
+from an earlier version, remove it — the framework mirror runs either way, and the second write
+is what breaks.
 
 **Alternative: Use Legacy Password Reset**