@lenne.tech/nest-server 11.36.5 → 11.38.0

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

@@ -2,7 +2,7 @@
 
 **For integrating BetterAuth into projects using `@lenne.tech/nest-server`.**
 
-> **Estimated time:** 10-15 minutes
+> **Estimated time:** 10-15 minutes (plus Step 0 on a fresh integration)
 
 **Need customization?** See [CUSTOMIZATION.md](./CUSTOMIZATION.md) for:
 
@@ -12,6 +12,29 @@
 
 ---
 
+## Step 0: Install the Peer Dependencies (required from 11.37.0)
+
+From `@lenne.tech/nest-server` 11.37.0, better-auth is **not** a dependency of this package. It is a
+non-optional **peer dependency**, so your project declares and owns the version:
+
+```bash
+pnpm add better-auth@1.7.1 @better-auth/passkey@1.7.1 @better-auth/core@1.7.1
+```
+
+**Pin all three to the same exact version** — no `^`, no `~`. They are one release train, and a
+mixed set fails in ways the type checker does not catch.
+
+> **Do not rely on `pnpm install` to remind you.** On pnpm's default `autoInstallPeers: true` the
+> packages are installed silently at whatever version satisfies `>=1.7.1 <1.8.0` — your build stays
+> green while the version is unpinned and free to drift. Verify with `pnpm why better-auth`.
+
+**Why peers rather than dependencies:** in a fullstack project the frontend talks to better-auth
+too. When this package owned the version, the API and the app could silently end up on different
+better-auth versions with incompatible payload shapes. Owning it in your own manifest makes that a
+single, visible decision.
+
+---
+
 ## Choose Your Scenario
 
 | Scenario                         | Use When                        | CoreModule Signature                                     | Steps |
@@ -112,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
@@ -292,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

@@ -30,6 +30,7 @@ const config = {
 - [Features](#features)
 - [Quick Integration](#quick-integration-for-claude-code--ai-assistants)
 - [Project Integration Guide](#project-integration-guide-required-steps)
+- [Boot-Time Behaviour](#boot-time-behaviour)
 - [Configuration](#configuration)
 - [REST API Endpoints](#rest-api-endpoints)
 - [GraphQL API](#graphql-api)
@@ -1015,6 +1016,61 @@ const config = {
 - Full flexibility for specialized plugins
 - No package updates needed for new Better-Auth plugins
 
+## Boot-Time Behaviour
+
+`CoreBetterAuthService.onModuleInit()` runs two steps against the database before the application
+starts listening. Both are `protected`, so a subclass can override either — **an override of
+`onModuleInit()` that does not call `super.onModuleInit()` skips both.**
+
+### 1. `ensureIndices()` — performance
+
+Idempotent indices on `session`, `users`, `account` and `verification`, including a TTL index that
+expires unconsumed verification and password-reset documents. Failures are logged at `warn` and do
+not block the boot: these help speed, not correctness.
+
+### 2. `backfillAccountIssuers()` — correctness (11.37.0+)
+
+From better-auth 1.7 an account is keyed by `(issuer, accountId)` and the sign-in route filters on
+it verbatim. Rows written by better-auth 1.6 have no `issuer` field, so **every existing password
+user would be locked out by the upgrade**, with a bare 401 and nothing in the log to explain it.
+This step repairs those rows on the first boot after the upgrade.
+
+| Property         | Behaviour                                                                                                                                                                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Scope            | Credential accounts only. OAuth/SSO rows are reported, never rewritten — see below                                                                                                           |
+| Idempotency      | Structural: only rows missing the field are selected                                                                                                                                         |
+| Repeat cost      | A completion marker in `better-auth-backfills` short-circuits later boots to one `_id` lookup. Neither backfill query is indexable, so without it every boot would scan the whole collection |
+| Schema overrides | Collection and field names are resolved from the running better-auth instance; a customised name is logged at `warn`                                                                         |
+| Partial failure  | The write is unordered, so one bad row cannot shadow the rest. The marker is **not** written, and the next boot retries                                                                      |
+| Failure          | Logged at `error`; the boot continues. A server that starts with a loud error beats one that will not start                                                                                  |
+
+**Log lines to expect on the first boot after upgrading:**
+
+| Line                                                           | Meaning                                                                                                |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `Backfilled account.issuer on N credential account(s)`         | Success — those N users can sign in again                                                              |
+| `Backfilled N/M credential accounts. X user(s) CANNOT sign in` | Partial. Usually a duplicate `(issuer, accountId)` pair from an earlier migration. Resolve and restart |
+| `Could not backfill the account issuer: …`                     | The operation failed entirely. Affected users cannot sign in until it succeeds                         |
+| `At least one non-credential account has no "issuer"`          | See below — act before the next social sign-in                                                         |
+| `Backfilling the account issuer against a customised schema`   | You renamed the account model or issuer field                                                          |
+
+**Why OAuth/SSO rows are not backfilled.** `local:credential` is a pure function of the provider id
+and therefore derivable. An OAuth issuer is not — it is either the provider's real OIDC issuer or
+the synthetic `local:oauth:<providerId>` fallback, decided per provider. Guessing would not fail
+loudly: better-auth falls back to matching the user by the provider-asserted email and implicitly
+links a **second** account row; if that email has changed, it creates a **new user** and orphans the
+old account together with its provider tokens, which no unlink will ever remove. So those rows are
+reported and the decision stays with the project. Set the issuer per provider **before** the first
+social sign-in after the upgrade — see
+[migration-guides/11.36.x-to-11.37.0.md](../../../../migration-guides/11.36.x-to-11.37.0.md) §4.
+
+> **Do not add `issuer` to this package's own reads of the `account` collection**
+> (`syncPasswordChangeToIam`, `migrateAccountToIam`, `getMigrationStatus`). They filter on
+> `providerId` alone on purpose, so they keep working on rows the backfill has not reached yet —
+> which matters most when the backfill has failed.
+
+---
+
 ## Module Setup
 
 See the [Project Integration Guide](#project-integration-guide-required-steps) at the top of this document for complete step-by-step instructions.
@@ -1689,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)
 
@@ -1895,6 +1965,14 @@ When a user is deleted:
    db.account.findOne({ userId: ObjectId('...'), providerId: 'credential' });
    ```
 
+   From better-auth 1.7 the row must ALSO carry `issuer: 'local:credential'`. A row matching only
+   `providerId` is not usable — better-auth keys accounts by `(issuer, accountId)` and will not find
+   it, so sign-in answers 401 while this query happily reports that the account exists:
+
+   ```javascript
+   db.account.findOne({ issuer: 'local:credential', providerId: 'credential', userId: ObjectId('...') });
+   ```
+
 3. Check server logs for sync warnings:
    ```
    [CoreUserService] Failed to sync password to IAM...
@@ -1918,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:
+**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)).
 
-```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 };
-  }
-
-  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**
 

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

@@ -53,7 +53,7 @@ function generateSecureSecret(): string {
  * Hash a password using Node.js native crypto.scrypt (libuv thread pool).
  * Output format matches Better-Auth: "salt:hash" (both hex encoded).
  */
-async function nativeScryptHash(password: string): Promise<string> {
+export async function nativeScryptHash(password: string): Promise<string> {
   const salt = crypto.randomBytes(16).toString('hex');
   const normalized = password.normalize('NFKC');
   const key = await new Promise<Buffer>((resolve, reject) => {
@@ -67,8 +67,14 @@ async function nativeScryptHash(password: string): Promise<string> {
 
 /**
  * Verify a password against a Better-Auth scrypt hash using Node.js native crypto.scrypt.
+ *
+ * Exported so tests can ask the PRODUCT whether a stored credential accepts a password, rather
+ * than re-declaring the scrypt parameters next to their assertion. A copy drifts silently: change
+ * a parameter here and the copy derives a different key, turning every affected assertion into a
+ * red with a misleading diagnosis — or, if both drift compatibly, into a green for the wrong
+ * reason.
  */
-async function nativeScryptVerify(data: { hash: string; password: string }): Promise<boolean> {
+export async function nativeScryptVerify(data: { hash: string; password: string }): Promise<boolean> {
   const [salt, storedKey] = data.hash.split(':');
   if (!salt || !storedKey) return false;
   const normalized = data.password.normalize('NFKC');
@@ -128,6 +134,13 @@ export interface CreateBetterAuthOptions {
    */
   onEmailVerified?: OnEmailVerifiedCallback;
 
+  /**
+   * Callback invoked after a password reset has been written to the IAM credential.
+   * Injected from CoreBetterAuthModule to mirror the new password into the legacy store,
+   * so a deployment running both systems does not end up with two different passwords.
+   */
+  onPasswordReset?: OnPasswordResetCallback;
+
   /**
    * Callback for sending the password-reset email.
    * Injected from CoreBetterAuthModule to use NestJS services.
@@ -179,6 +192,51 @@ export interface CreateBetterAuthOptions {
  */
 export type OnEmailVerifiedCallback = (userId: string) => Promise<void>;
 
+/**
+ * Callback for when a password reset has been APPLIED to the IAM credential.
+ *
+ * Injected from CoreBetterAuthModule so the new password can also be mirrored into the
+ * legacy bcrypt store. Better-Auth reports only WHICH user was reset — the password
+ * itself comes from `core-better-auth-password-reset.registry.ts`, which the API
+ * middleware fills for the duration of the handler call.
+ *
+ * Fires for every native reset route (token, email-OTP, phone-number).
+ */
+/**
+ * Combines the framework's `onPasswordReset` with a project-supplied one so neither is lost.
+ *
+ * Returns an empty object when there is nothing to install, so the caller can spread it
+ * unconditionally without writing an `onPasswordReset: undefined` key — Better-Auth resolves
+ * the hook by presence, and an explicitly-undefined key reads as "declared, does nothing".
+ *
+ * The framework hook runs FIRST and its failure does not prevent the project hook: they are
+ * independent consequences of the same event, and one broken listener must not silently
+ * cancel the other.
+ */
+function chainOnPasswordReset(base: unknown, override: unknown): { onPasswordReset?: OnPasswordResetCallback } {
+  const baseHook = typeof base === 'function' ? (base as OnPasswordResetCallback) : undefined;
+  const overrideHook = typeof override === 'function' ? (override as OnPasswordResetCallback) : undefined;
+
+  if (!baseHook) {
+    return overrideHook ? { onPasswordReset: overrideHook } : {};
+  }
+  if (!overrideHook) {
+    return { onPasswordReset: baseHook };
+  }
+
+  return {
+    onPasswordReset: async (data) => {
+      const results = await Promise.allSettled([baseHook(data), overrideHook(data)]);
+      const failure = results.find((result) => result.status === 'rejected');
+      if (failure && failure.status === 'rejected') {
+        throw failure.reason;
+      }
+    },
+  };
+}
+
+export type OnPasswordResetCallback = (data: { user: { email?: string; id: string } }) => Promise<void>;
+
 /**
  * Options for creating a better-auth instance
  */
@@ -371,8 +429,16 @@ export interface CreateBetterAuthResult {
 }
 
 export function createBetterAuthInstance(options: CreateBetterAuthOptions): CreateBetterAuthResult | null {
-  const { config, db, fallbackSecrets, onEmailVerified, sendResetPasswordEmail, sendVerificationEmail, serverEnv } =
-    options;
+  const {
+    config,
+    db,
+    fallbackSecrets,
+    onEmailVerified,
+    onPasswordReset,
+    sendResetPasswordEmail,
+    sendVerificationEmail,
+    serverEnv,
+  } = options;
 
   // Return null only if better-auth is explicitly disabled
   // BetterAuth is enabled by default (zero-config)
@@ -517,6 +583,29 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
       // here claimed a mail-less server would keep answering RESET_PASSWORD_DISABLED; it would not.
       // `emailAndPassword.passwordReset: false` is the real off switch, for deployments whose reset
       // policy is support-mediated or SSO-primary.
+      // Mirror an applied reset into the legacy bcrypt store.
+      //
+      // Without this, a deployment running Legacy Auth next to IAM keeps the OLD password
+      // valid on the legacy path after a reset — including a reset somebody performed
+      // BECAUSE the old password was compromised. Better-Auth tells us which user was
+      // reset; the password comes from the API middleware via the reset registry.
+      ...(onPasswordReset && {
+        onPasswordReset: (async (data) => {
+          try {
+            await onPasswordReset(data);
+          } catch (error) {
+            // Never fail the reset itself: the IAM credential is already written, and
+            // refusing the response would tell the user their reset did not work when it
+            // half did. Report it instead.
+            logger.error(
+              `Failed to mirror the password reset to the legacy store: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+            );
+          }
+        }) satisfies OnPasswordResetCallback,
+      }),
+
       // Mirrors the emailVerification.sendVerificationEmail wiring.
       ...(sendResetPasswordEmail &&
         config.emailAndPassword?.passwordReset !== false && {
@@ -606,6 +695,19 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
         // READS. The result is an asymmetric pair — anyone who resets their password can then
         // never sign in again. An explicit override still wins; only `undefined` is ignored.
         password: mergeDefined(base.password, override.password),
+        // `onPasswordReset` is subject to the SAME hazard as `password` above, and needs the
+        // opposite treatment: it must not be replaceable at all.
+        //
+        // It is what mirrors an applied IAM reset into the legacy bcrypt store. A project has
+        // an entirely reasonable motive to declare its own (audit logging, a notification
+        // mail) — and the spread would then drop the framework's, silently restoring the
+        // pre-11.38.0 defect where the OLD password stays valid on the legacy path after a
+        // reset, including a reset performed BECAUSE it leaked. Both stores report success.
+        //
+        // So the two are CHAINED rather than merged: the framework mirror always runs, the
+        // project hook runs after it. That is a deliberate asymmetry to `password`, where an
+        // explicit override wins — a hasher is a choice, a credential-store mirror is not.
+        ...chainOnPasswordReset(base.onPasswordReset, override.onPasswordReset),
       };
     }
     if (optionsAdvanced && typeof optionsAdvanced === 'object') {