@lenne.tech/nest-server 11.35.1 → 11.36.1

package/src/core/common/interfaces/server-options.interface.ts

@@ -361,6 +361,23 @@ export interface IBetterAuthEmailVerificationConfig {
    */
   locale?: string;
 
+  /**
+   * Brevo transactional template ID for the PASSWORD-RESET mail.
+   *
+   * Separate from `brevoTemplateId` on purpose: that one is the verification
+   * mail, and reusing it would send "confirm your email address" to someone who
+   * asked to reset their password. When this is unset the reset mail goes out
+   * over SMTP with the `password-reset[-<locale>].ejs` template instead.
+   *
+   * Template variables passed to Brevo:
+   * - `name`: User display name
+   * - `link`: Reset URL
+   * - `appName`: Application name
+   *
+   * @default undefined (uses SMTP/EJS templates)
+   */
+  passwordResetBrevoTemplateId?: number;
+
   /**
    * Cooldown in seconds between resend requests for the same email address.
    * Prevents abuse by limiting how often verification emails can be resent.
@@ -543,8 +560,13 @@ export interface IBetterAuthPasskeyConfig {
  */
 export interface IBetterAuthRateLimit {
   /**
-   * Whether rate limiting is enabled
-   * @default false
+   * Whether rate limiting is enabled.
+   *
+   * Follows the "presence implies enabled" pattern: providing a `rateLimit` object at all — even
+   * `{}` — turns the limiter ON, and only an explicit `enabled: false` keeps it off while letting
+   * you pre-configure the rest. Omitting `rateLimit` entirely leaves it off.
+   *
+   * @default true when a `rateLimit` object is present, false when it is absent
    */
   enabled?: boolean;
 
@@ -3414,6 +3436,50 @@ interface IBetterAuthBase {
      * @default true
      */
     enabled?: boolean;
+
+    /**
+     * Whether Better-Auth's native password-reset flow is available.
+     *
+     * `CoreBetterAuthModule` wires the `sendResetPassword` hook automatically, and the presence of
+     * that hook is what Better-Auth treats as the on switch — so the flow is ON out of the box and
+     * `POST /iam/request-password-reset` mints a token and sends mail.
+     *
+     * Set `false` to withhold the hook, which makes that route answer `RESET_PASSWORD_DISABLED`
+     * again. For deployments whose reset policy is support-mediated or SSO-primary, and which
+     * therefore do not want an unauthenticated, token-minting, mail-sending endpoint at all.
+     *
+     * @default true
+     * @since 11.36.1
+     */
+    passwordReset?: boolean;
+
+    /**
+     * End every existing session when the user completes a password reset.
+     *
+     * A reset is what somebody reaches for when they suspect their account was
+     * taken over, so leaving the older sessions alive defeats the point: the
+     * attacker keeps theirs and the new password changes nothing for them.
+     *
+     * Left off by default because it is a behaviour change for existing
+     * deployments — a reset then signs the user out everywhere, including on
+     * the devices they still hold.
+     *
+     * Passed through to better-auth's native
+     * `emailAndPassword.revokeSessionsOnPasswordReset`. Prefer this named field
+     * over `options.emailAndPassword`: it is validated (`=== true`, so a JSON
+     * env string cannot enable a sign-out-everywhere behaviour), typed and
+     * discoverable.
+     *
+     * Until 11.36.1 the reason was harsher — `options` was spread SHALLOWLY, so
+     * an `options.emailAndPassword` replaced the whole block including the
+     * scrypt `password.hash` / `password.verify` pair, and every credential in
+     * the database stopped verifying. `emailAndPassword` is deep-merged now,
+     * with `password` re-applied as the base, so that trap is closed.
+     *
+     * @default false
+     * @since 11.36.0
+     */
+    revokeSessionsOnPasswordReset?: boolean;
   };
 
   /**

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

@@ -53,9 +53,8 @@ export class BrevoService {
         return false;
       }
 
-      // Exclude (test) users, must be done via config and not via configFastButReadOnly,
-      // otherwise the error TypeError: Cannot assign to read only property 'lastIndex' of object '[object RegExp]' occurs
-      if (this.configService.config?.brevo?.exclude?.test?.(to)) {
+      // Exclude (test) users
+      if (this.isExcluded(to)) {
         return 'TEST_USER!';
       }
 
@@ -98,9 +97,8 @@ export class BrevoService {
         return false;
       }
 
-      // Exclude (test) users, must be done via config and not via configFastButReadOnly,
-      // otherwise the error TypeError: Cannot assign to read only property 'lastIndex' of object '[object RegExp]' occurs
-      if (this.configService.config?.brevo?.exclude?.test?.(to)) {
+      // Exclude (test) users
+      if (this.isExcluded(to)) {
         return 'TEST_USER!';
       }
 
@@ -135,6 +133,36 @@ export class BrevoService {
     return { 'Idempotency-Key': randomUUID() };
   }
 
+  /**
+   * Checks a recipient against `brevo.exclude` without inheriting the pattern's match state.
+   *
+   * Two traps live in this one line, and both have bitten:
+   *
+   * 1. `RegExp.prototype.test` ADVANCES `lastIndex` on a pattern carrying `g` or `y`. The config
+   *    holds a single shared instance and projects declare it as `/…/gi`, so calling `.test()` on
+   *    it directly answers true, false, true, … for the very same address — every second excluded
+   *    recipient receives a real mail. Matching against a flagless copy keeps each call
+   *    independent and leaves the configured pattern untouched.
+   * 2. It must be read from `config`, never from `configFastButReadOnly`: assigning `lastIndex` on
+   *    the frozen copy throws `TypeError: Cannot assign to read only property 'lastIndex'`.
+   *    Point 1 removes the assignment, but the frozen object may still be a `deepFreeze`d clone
+   *    whose flags differ, so the mutable side stays the source of truth.
+   *
+   * @param to - Recipient email address
+   * @returns `true` when the recipient matches the configured exclude pattern
+   */
+  protected isExcluded(to: string): boolean {
+    const exclude = this.configService.config?.brevo?.exclude;
+    if (typeof exclude?.test !== 'function') {
+      return false;
+    }
+
+    const stateless =
+      exclude.global || exclude.sticky ? new RegExp(exclude.source, exclude.flags.replace(/[gy]/g, '')) : exclude;
+
+    return stateless.test(to);
+  }
+
   /**
    * Lazily constructs (and memoises) the Brevo SDK client.
    *

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

@@ -295,9 +295,27 @@ export class CustomEmailVerificationService extends CoreBetterAuthEmailVerificat
     await super.sendVerificationEmail(options);
     // Custom logic after (e.g., analytics)
   }
+
+  // The password-reset mail is a separate override point with the same shape. Better-Auth calls it
+  // through the `emailAndPassword.sendResetPassword` hook CoreBetterAuthModule injects.
+  override async sendPasswordResetEmail(options: SendPasswordResetEmailOptions): Promise<void> {
+    // e.g. supply a logo for the shipped templates, which render an <img> when `logoSrc` is set
+    await super.sendPasswordResetEmail(options);
+  }
+
+  // Subject lines are separate protected hooks on both flows.
+  protected override getPasswordResetSubject(appName: string): string {
+    return `${appName} — choose a new password`;
+  }
 }
 ```
 
+**Note:** `sendPasswordResetEmail()` re-throws a Brevo or SMTP send failure after logging it with
+the masked address. The framework's own caller wraps it in `sendAuthEmailSafely`, so a throw never
+reaches the request — an override that calls it directly must handle it. It is also throttled per
+recipient address (see `resendCooldownSeconds`); a send that fails releases the slot so the
+locked-out user may retry immediately.
+
 ### CoreBetterAuthUserMapper
 
 Handles user mapping between BetterAuth and nest-server User model. Extend when you need to:
@@ -324,7 +342,7 @@ Email templates are resolved in this order:
 | Template             | Purpose                             | Default Locales |
 | -------------------- | ----------------------------------- | --------------- |
 | `email-verification` | Email verification after sign-up    | `en`, `de`      |
-| `password-reset`     | Password reset email                | `en`            |
+| `password-reset`     | Password reset email                | `en`, `de`      |
 | `welcome`            | Welcome email (not used by default) | `en`            |
 
 ### How to Override Templates
@@ -357,12 +375,20 @@ const config = {
 
 Available variables in email templates:
 
-| Variable    | Type   | Description                                       |
-| ----------- | ------ | ------------------------------------------------- |
-| `name`      | string | User's name or email prefix                       |
-| `link`      | string | Verification/reset URL                            |
-| `appName`   | string | Application name from package.json                |
-| `expiresIn` | string | Human-readable expiration time (e.g., "24 hours") |
+| Variable    | Type   | Passed by             | Description                                                                                                                                                                              |
+| ----------- | ------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`      | string | both flows            | User's name or email prefix                                                                                                                                                              |
+| `link`      | string | both flows            | Verification/reset URL                                                                                                                                                                   |
+| `appName`   | string | both flows            | Application name from package.json                                                                                                                                                       |
+| `expiresIn` | string | verification only     | Human-readable expiration time (e.g., "24 hours")                                                                                                                                        |
+| `logoSrc`   | string | **nobody — optional** | Not supplied by the framework. The shipped password-reset templates render an `<img>` when it is present and the app name as text otherwise; pass it from a subclass override to use it. |
+
+**A template may only reference what its caller passes.** EJS resolves variables at render time, so
+a missing one is a `ReferenceError` and an HTTP 500, not a build error. Two shapes reach
+`password-reset`: the IAM flow passes `{ name, link, appName }`, and the LEGACY
+`POST /users/password/reset-request` flow (`UserService.sendPasswordResetMail()`) passes
+`{ name, link }` only. Guard anything else with `typeof x !== 'undefined'`, as the shipped
+templates do.
 
 ### Example Template
 

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

@@ -270,6 +270,44 @@ Available variables: `name`, `link`, `expiresIn`, `appName`
 
 ---
 
+## Password Reset (v11.36.1+)
+
+**Native password reset is ON by default and needs no configuration.**
+`CoreBetterAuthModule` injects the `emailAndPassword.sendResetPassword` hook, so
+`POST /iam/request-password-reset` is live from the first boot. Before 11.36.1 no hook was wired
+and the route answered `RESET_PASSWORD_DISABLED`, so **this changes behaviour on upgrade**: reset
+mail starts going out to real users.
+
+Check these four things when integrating:
+
+- [ ] **Rate limiting is on.** The route is unauthenticated and sends mail. `betterAuth.rateLimit`
+      is off unless you configure it — providing the object at all (even `{}`) enables it. The
+      mailer additionally holds a per-ADDRESS cooldown (`emailVerification.resendCooldownSeconds`,
+      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.
+- [ ] **`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.
+- [ ] **If you ship your own `password-reset.ejs`, it must render from `{ link, name }` alone.**
+      The legacy `POST /users/password/reset-request` flow resolves that exact template name and
+      passes nothing else. Locale variants (`password-reset-de.ejs` / `-en.ejs`) are only reached
+      by the IAM flow and may use `appName`.
+
+To turn the flow off entirely (support-mediated or SSO-primary reset policies):
+
+```typescript
+betterAuth: {
+  emailAndPassword: { passwordReset: false },
+},
+```
+
+Optional: `betterAuth.emailVerification.passwordResetBrevoTemplateId` routes the mail through
+Brevo. It deliberately does **not** fall back to `brevoTemplateId` — that is the verification
+template, which would tell the user to confirm their address instead of resetting their password.
+
+---
+
 ## Sign-Up Checks (v11.13.0+)
 
 Sign-up validation is **enabled by default** requiring `termsAndPrivacyAccepted`.

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

@@ -1732,31 +1732,116 @@ When a legacy user signs in via BetterAuth for the first time, their account is
 
 ### BetterAuth Password Reset Configuration
 
-BetterAuth provides native password reset via `/iam/forgot-password` and `/iam/reset-password` endpoints. To enable this, configure the `sendResetPassword` callback:
+BetterAuth provides native password reset via `/iam/request-password-reset` and
+`/iam/reset-password`. It is **enabled automatically** — `CoreBetterAuthModule`
+injects a `sendResetPassword` hook that delegates to
+`CoreBetterAuthEmailVerificationService.sendPasswordResetEmail()`. Nothing needs
+to be configured for the flow to work; without that hook Better-Auth answers
+`RESET_PASSWORD_DISABLED`.
+
+> **This is a live, unauthenticated endpoint on every deployment.** Anyone can
+> POST any address to it and cause a mail to be sent and a token to be minted.
+> Before you ship, check the two bounds below (rate limit + cooldown), or turn
+> the flow off if your reset policy is support-mediated or SSO-primary:
+>
+> ```typescript
+> betterAuth: {
+>   emailAndPassword: { passwordReset: false },  // route answers RESET_PASSWORD_DISABLED again
+> },
+> ```
+
+#### Rate limiting (check this)
+
+Two independent bounds, on different axes:
+
+| Bound                                                       | Axis              | Default                   |
+| ----------------------------------------------------------- | ----------------- | ------------------------- |
+| `betterAuth.rateLimit` (route middleware)                   | IP                | **off unless configured** |
+| Mailer cooldown (`emailVerification.resendCooldownSeconds`) | recipient address | 60 s                      |
+
+The recipient-axis cooldown is what stops an attacker rotating IPs to mail-bomb
+one victim; the IP-axis limiter is what stops one caller hammering the route.
+`/request-password-reset` is listed in `strictEndpoints`, so it receives the
+halved limit when the limiter is on. Providing a `rateLimit` object at all —
+even `{}` — enables it:
+
+```typescript
+betterAuth: {
+  rateLimit: { max: 10, windowSeconds: 60 },
+},
+```
+
+#### Branding the mail
+
+Drop your own template into the project template directory — it wins over the
+nest-server default via the usual project-first, locale-aware lookup:
+
+```
+src/assets/templates/password-reset-de.ejs   # or -en, or plain password-reset.ejs
+```
+
+| Variable  | Always passed | Notes                                                                                                                                                                                                                                                      |
+| --------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`    | yes           | `user.name`, falling back to the local part of the address                                                                                                                                                                                                 |
+| `link`    | yes           | the ready-made reset URL                                                                                                                                                                                                                                   |
+| `appName` | yes           | derived from `package.json` `name`                                                                                                                                                                                                                         |
+| `logoSrc` | **no**        | optional. The shipped templates render an `<img>` when it is present and the app name as text otherwise. Nothing in the framework supplies it — pass it from a subclass that overrides `sendPasswordResetEmail()`, or reference it from your own template. |
+
+> **Keep the un-suffixed `password-reset.ejs` renderable from `{ link, name }` alone.**
+> The legacy `POST /users/password/reset-request` flow (`UserService.sendPasswordResetMail()`)
+> resolves that exact name and passes nothing else, so a template that
+> references `appName` unguarded turns legacy password recovery into an HTTP 500.
+> The framework's own shipped templates guard it; `tests/unit/email-templates.spec.ts`
+> pins the contract.
+
+For Brevo, set a **reset-specific** template id (never reuse `brevoTemplateId` —
+that is the verification mail, and the user would be told to confirm their
+address instead of resetting their password):
 
 ```typescript
 // config.env.ts
 betterAuth: {
-  options: {
-    emailAndPassword: {
-      sendResetPassword: async ({ user, url, token }) => {
-        // Send password reset email
-        // 'url' contains the full reset URL with token
-        await emailService.sendEmail({
-          to: user.email,
-          subject: 'Reset Your Password',
-          html: `<a href="${url}">Click here to reset your password</a>`,
-        });
-      },
-    },
+  emailVerification: {
+    passwordResetBrevoTemplateId: 42,
   },
 },
 ```
 
+A Brevo send that reports failure by resolving to `null` falls through to SMTP
+rather than returning, so an outage does not leave a locked-out user with no
+mail at all.
+
+To replace the sending logic entirely, override `sendPasswordResetEmail()` in a
+subclass of `CoreBetterAuthEmailVerificationService`, exactly as with
+`sendVerificationEmail()`.
+
+#### Why not `betterAuth.options.emailAndPassword`
+
+You _can_ set `sendResetPassword` there, and it will win — `options` is merged
+last. That is precisely why it is the wrong place:
+
+- **Your callback replaces the framework hook entirely.** The mail no longer
+  goes through `sendPasswordResetEmail()` or the templates above, and it loses
+  the fire-and-forget wrapper that keeps the response time from revealing
+  whether the address exists.
+- **The block you are writing into carries the password hashing.** It holds
+  `password: { hash: nativeScryptHash, verify: nativeScryptVerify }` — the
+  hashing every stored credential was created with. Since 11.36.1 the merge
+  protects `password` key-by-key, so an unrelated key can no longer drop it, but
+  staying out of that block is still the safer habit.
+
+Use the hook, the template, and `passwordReset: false` to opt out.
+
 #### Password Reset Flow (BetterAuth)
 
-1. User requests reset: `POST /iam/forgot-password` with `{ email }`
-2. BetterAuth generates token and calls `sendResetPassword` callback
+1. User requests reset: `POST /iam/request-password-reset` with `{ email }` and
+   an optional `redirectTo`. `redirectTo` is validated against
+   `trustedOrigins` — a value outside it is rejected. Do not put a wildcard in
+   `trustedOrigins`: the reset redirect carries the token, so any origin the
+   wildcard admits can collect a live one.
+2. BetterAuth generates a token (valid 1 h by default,
+   `resetPasswordTokenExpiresIn`) and calls the built-in `sendResetPassword`
+   hook, which delegates to `sendPasswordResetEmail()`
 3. User clicks link in email → navigates to reset page
 4. Frontend submits: `POST /iam/reset-password` with `{ token, newPassword }`
 5. BetterAuth updates password in `account` collection

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

@@ -128,6 +128,18 @@ export interface CreateBetterAuthOptions {
    */
   onEmailVerified?: OnEmailVerifiedCallback;
 
+  /**
+   * Callback for sending the password-reset email.
+   * Injected from CoreBetterAuthModule to use NestJS services.
+   *
+   * When provided, it is wired into Better-Auth's
+   * `emailAndPassword.sendResetPassword` hook, which is what ENABLES the native
+   * `POST /iam/request-password-reset` flow. Without a callback Better-Auth
+   * answers `RESET_PASSWORD_DISABLED` and no reset mail is ever sent — a
+   * password-reset page that cannot work, and users locked out for good.
+   */
+  sendResetPasswordEmail?: SendResetPasswordEmailCallback;
+
   /**
    * Callback for sending verification email
    * Injected from CoreBetterAuthModule to use NestJS services
@@ -174,11 +186,35 @@ export type OnEmailVerifiedCallback = (userId: string) => Promise<void>;
  * Callback for sending verification email
  * Injected from CoreBetterAuthModule to use NestJS services
  */
-export type SendVerificationEmailCallback = (options: {
+export interface AuthEmailCallbackOptions {
+  /** The raw token, for consumers that build their own link. */
   token: string;
+
+  /** The ready-made URL Better-Auth generated. */
   url: string;
+
+  /** The user the mail is for. */
   user: { email: string; id: string; name?: null | string };
-}) => Promise<void>;
+}
+
+export type SendVerificationEmailCallback = (options: AuthEmailCallbackOptions) => Promise<void>;
+
+/**
+ * Sends the password-reset mail. Same shape as the verification callback —
+ * `url` is the ready-made reset link Better-Auth generated, `token` the raw
+ * token for consumers that build their own link.
+ */
+/**
+ * Sends the password-reset mail.
+ *
+ * Naming note — the word order flips at this boundary, once and deliberately. Everything on the
+ * Better-Auth side is `resetPassword` because Better-Auth's own option key is `sendResetPassword`;
+ * everything on the NestJS service side is `passwordReset`
+ * (`CoreBetterAuthEmailVerificationService.sendPasswordResetEmail`, `PASSWORD_RESET_TEMPLATE`,
+ * `passwordResetBrevoTemplateId`) because that is how the feature is named in this framework's
+ * config and templates. If you grep for one spelling and find half the feature, this is why.
+ */
+export type SendResetPasswordEmailCallback = (options: AuthEmailCallbackOptions) => Promise<void>;
 
 /**
  * Invoke an auth-email send (verification / password-reset) fire-and-forget.
@@ -192,6 +228,12 @@ export type SendVerificationEmailCallback = (options: {
  * rejection) to `onError` instead. `onError` itself is guarded too: if the
  * handler throws, the error is swallowed rather than crashing the process.
  *
+ * Do NOT remove this wrapper on the grounds that Better-Auth "already detaches". Verified against
+ * better-auth 1.6.26 (`context/create-context.mjs:214`): `runInBackgroundOrAwait` detaches ONLY when
+ * `advanced.backgroundTasks.handler` is configured, and `else await promise`. This framework does
+ * not configure a handler, so without this wrapper Better-Auth would await the send — and the
+ * response time would once again reveal whether the address exists.
+ *
  * Deliberate divergence from Better-Auth's own mechanism: Better-Auth awaits
  * these callbacks via `runInBackgroundOrAwait` and offers
  * `advanced.backgroundTasks` as its native non-blocking path. That option is
@@ -214,6 +256,23 @@ export function sendAuthEmailSafely(send: () => unknown, onError: (error: unknow
     });
 }
 
+/**
+ * Shallow-merge `override` onto `base`, skipping keys whose override value is `undefined`.
+ *
+ * Distinct from a spread on purpose — see the call site in the `emailAndPassword` merge.
+ */
+function mergeDefined(base: unknown, override: unknown): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...(base as Record<string, unknown> | undefined) };
+  if (override && typeof override === 'object') {
+    for (const [key, value] of Object.entries(override as Record<string, unknown>)) {
+      if (value !== undefined) {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
 /**
  * Better-Auth field type definition
  * Matches the DBFieldType from better-auth
@@ -312,7 +371,8 @@ export interface CreateBetterAuthResult {
 }
 
 export function createBetterAuthInstance(options: CreateBetterAuthOptions): CreateBetterAuthResult | null {
-  const { config, db, fallbackSecrets, onEmailVerified, sendVerificationEmail, serverEnv } = options;
+  const { config, db, fallbackSecrets, onEmailVerified, sendResetPasswordEmail, sendVerificationEmail, serverEnv } =
+    options;
 
   // Return null only if better-auth is explicitly disabled
   // BetterAuth is enabled by default (zero-config)
@@ -444,6 +504,36 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
         hash: nativeScryptHash,
         verify: nativeScryptVerify,
       },
+      // Opt-in: a reset then also ends the sessions that already existed, which
+      // is the point of resetting after a suspected takeover. Off by default so
+      // the behaviour of existing deployments does not change under them.
+      revokeSessionsOnPasswordReset: config.emailAndPassword?.revokeSessionsOnPasswordReset === true,
+      // Presence of this hook is what turns the native password reset ON, so withholding it is the
+      // only way to keep `POST /iam/request-password-reset` answering RESET_PASSWORD_DISABLED.
+      //
+      // Note what this condition does NOT buy: `CoreBetterAuthModule.createEmailVerificationCallbacks()`
+      // always supplies a callback — the "no mail service" case is handled INSIDE it — so for every
+      // consumer that goes through the module, the callback half is always true. An earlier comment
+      // 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.
+      // Mirrors the emailVerification.sendVerificationEmail wiring.
+      ...(sendResetPasswordEmail &&
+        config.emailAndPassword?.passwordReset !== false && {
+          sendResetPassword: async (data: AuthEmailCallbackOptions) => {
+            // Deliberately NOT awaited: Better-Auth answers the request the same
+            // way whether or not the address exists, and awaiting the send would
+            // leak that difference as response time. A failed send must still be
+            // logged rather than crash the process — see sendAuthEmailSafely.
+            sendAuthEmailSafely(
+              () => sendResetPasswordEmail(data),
+              (error) =>
+                logger.error(
+                  `Failed to send password-reset email: ${error instanceof Error ? error.message : String(error)}`,
+                ),
+            );
+          },
+        }),
     },
     plugins,
     secret: validation.resolvedSecret || config.secret,
@@ -463,15 +553,61 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
   // When undefined, Better-Auth uses its default CORS behavior (allows all origins)
   if (trustedOrigins) {
     betterAuthConfig.trustedOrigins = trustedOrigins;
+
+    // A wildcard here was a CORS-looseness problem before the password-reset flow was wired; it is
+    // an account-takeover vector now. `redirectTo` on POST /iam/request-password-reset is validated
+    // against trustedOrigins, and GET /iam/reset-password/:token redirects to
+    // `<callbackURL>?token=<token>` — so a wildcard that admits an attacker-controlled subdomain
+    // hands them a live reset token for whichever address they named.
+    const wildcardOrigins = trustedOrigins.filter((origin) => typeof origin === 'string' && origin.includes('*'));
+    if (wildcardOrigins.length) {
+      logger.warn(
+        `betterAuth.trustedOrigins contains a wildcard (${wildcardOrigins.join(', ')}). The password-reset ` +
+          'redirect is validated against this list, so any origin it admits can receive a live reset ' +
+          'token. List exact origins instead.',
+      );
+    }
   }
 
   // Merge with custom options passthrough
   // This allows projects to configure any Better-Auth option not explicitly defined
-  // Deep-merge 'advanced' to preserve cookiePrefix when options.advanced is provided
+  // Deep-merge 'advanced' to preserve cookiePrefix when options.advanced is provided,
+  // and 'emailAndPassword' to preserve the password hashing (see below).
   let finalConfig: Record<string, unknown>;
   if (config.options) {
-    const { advanced: optionsAdvanced, ...restOptions } = config.options as Record<string, unknown>;
+    const {
+      advanced: optionsAdvanced,
+      emailAndPassword: optionsEmailAndPassword,
+      ...restOptions
+    } = config.options as Record<string, unknown>;
     finalConfig = { ...betterAuthConfig, ...restOptions };
+
+    // `emailAndPassword` needs a DEEP merge, and this one is load-bearing.
+    // The block above carries `password: { hash: nativeScryptHash, verify:
+    // nativeScryptVerify }` — the hashing every stored credential was created
+    // with. A shallow spread would let a consumer who sets `options.
+    // emailAndPassword` for an unrelated reason (a `sendResetPassword` callback,
+    // `maxPasswordLength`) replace the whole block and drop those functions.
+    // Better-Auth would fall back to its own default hasher, every existing
+    // password would stop verifying, and every user of that deployment would be
+    // locked out at once — with nothing in the logs to say why.
+    // `password` is therefore re-applied as the BASE, so an explicit override
+    // still wins while an unrelated key can no longer clobber it.
+    if (optionsEmailAndPassword && typeof optionsEmailAndPassword === 'object') {
+      const base = betterAuthConfig.emailAndPassword as Record<string, unknown>;
+      const override = optionsEmailAndPassword as Record<string, unknown>;
+      finalConfig.emailAndPassword = {
+        ...base,
+        ...override,
+        // Merged key-by-key rather than spread, because object spread copies an EXPLICITLY
+        // undefined value as a present key: `password: { hash: undefined }` would survive as
+        // `hash: undefined`, and Better-Auth resolves `password?.hash || hashPassword`, silently
+        // switching to its own hasher for WRITES while nest-server's scrypt verify still handles
+        // 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),
+      };
+    }
     if (optionsAdvanced && typeof optionsAdvanced === 'object') {
       // Drift guard: a programmatic `options.advanced.cookiePrefix` would only
       // change what Better-Auth itself sets — the NestJS layer keeps resolving
@@ -586,10 +722,7 @@ function buildEmailVerificationConfig(
 
   // Add sendVerificationEmail callback if provided
   if (sendVerificationEmail) {
-    result.sendVerificationEmail = async (
-      data: { token: string; url: string; user: { email: string; id: string; name?: null | string } },
-      _request?: Request,
-    ) => {
+    result.sendVerificationEmail = async (data: AuthEmailCallbackOptions, _request?: Request) => {
       // Fire-and-forget (timing-attack mitigation, per Better-Auth docs) — but a
       // failed send must be logged, never crash the process (see sendAuthEmailSafely).
       // Note: delivery failures are also logged (with masked recipient) by the