@lenne.tech/nest-server 11.36.0 → 11.36.2

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)
@@ -448,6 +508,32 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
       // 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,
@@ -467,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
@@ -590,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