@lenne.tech/nest-server 11.36.0 → 11.36.1

package/docs/security-overrides.md

@@ -11,18 +11,17 @@ A green `pnpm audit` inside the framework repo says nothing about your tree.
 
 ## What this concretely means for you
 
-The framework pulls in three transitive packages that resolve to a **vulnerable** version unless you
+The framework pulls in two transitive packages that resolve to a **vulnerable** version unless you
 override them yourself:
 
 | Package | Advisory | Why it cannot resolve forward on its own |
 |---------|----------|------------------------------------------|
 | `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | `@nestjs/graphql` declares `"ws": "8.20.1"` — an **exact pin**, not a caret. No amount of updating moves it |
-| `@hono/node-server` | [GHSA-frvp-7c67-39w9](https://github.com/advisories/GHSA-frvp-7c67-39w9) (static-file path traversal) + [GHSA-9mqv-5hh9-4cgg](https://github.com/advisories/GHSA-9mqv-5hh9-4cgg) (unauthenticated memory leak). Patched `>=2.0.10` | `@modelcontextprotocol/sdk` declares `^1.19.9` and ships **no 1.x fix line**, so the fix is only available across a major |
 | `js-yaml` | [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5) — high: exponential parsing time in flow collections (DoS). Patched `>=5.2.2` | `@nestjs/swagger` declares `"js-yaml": "5.2.1"` — an **exact pin**, the same shape as the `ws` case. It cannot resolve forward |
 
 `@nestjs/graphql` is a plain `dependencies` entry, so `ws` is installed even when you run with
-`graphQl: false`. `@nestjs/swagger` is likewise a plain `dependencies` entry. None of the three is
-optional in practice.
+`graphQl: false`. `@nestjs/swagger` is likewise a plain `dependencies` entry. Neither is optional in
+practice.
 
 ## The fix
 
@@ -37,19 +36,26 @@ overrides:
   # Remove once @nestjs/graphql stops pinning it.
   'ws@>=8.0.0 <8.21.0': '8.21.3'
 
-  # @modelcontextprotocol/sdk declares @hono/node-server ^1.19.9 with no 1.x fix line
-  # (GHSA-frvp-7c67-39w9, GHSA-9mqv-5hh9-4cgg). Deliberately a CROSS-MAJOR override.
-  # Verified safe: the SDK's only consumed symbol is `getRequestListener`, whose signature
-  # `(fetchCallback, options?)` is unchanged in 2.x. Engines >=20 and peer hono@^4 both fit.
-  # Remove once @modelcontextprotocol/sdk moves its own range to ^2.
-  '@hono/node-server@<2.0.10': '2.0.11'
-
   # @nestjs/swagger exact-pins js-yaml@5.2.1 (GHSA-pm4m-ph32-ghv5, high, patched >=5.2.2).
   # Same shape as the ws entry: an exact pin cannot resolve forward.
   # Remove once @nestjs/swagger stops pinning it.
   'js-yaml@>=5.0.0 <5.2.2': '5.2.2'
 ```
 
+### Retired: `@hono/node-server` (removed 2026-08-22, nest-server 11.36.1)
+
+This list used to carry a third entry. `@modelcontextprotocol/sdk` declared `@hono/node-server@^1.19.9`
+with no 1.x fix line, so reaching the patched version needed a deliberate cross-major override.
+
+SDK `1.30.0` declares `"^1.19.9 || ^2.0.5"`, so a fresh resolve now picks the newest 2.x (2.1.1 at the
+time of writing) on its own — above the `>=2.0.10` that fixes GHSA-frvp-7c67-39w9 and
+GHSA-9mqv-5hh9-4cgg. The override became a **downgrade lock**: an override key is matched against the
+REQUESTED RANGE, not the resolved version, so the entry replaced the SDK's whole spec and pinned the
+tree to `2.0.11` even though nothing needed help any more.
+
+**Do not re-add it** unless the SDK narrows its range again. If you still carry it in your own
+`pnpm-workspace.yaml`, remove it and re-run `pnpm audit`.
+
 ### The `ws` target must stay in lockstep with the declared `ws` version
 
 `8.21.3` is not an arbitrary "latest patch" — it is the version `@lenne.tech/nest-server` declares as

package/migration-guides/11.36.0-to-11.36.1.md

@@ -0,0 +1,283 @@
+# Migration Guide: 11.36.0 → 11.36.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None in signature. But **behaviour changes without any config change**: `POST /iam/request-password-reset` goes from inert to live and starts sending mail to real users (§1). Read §1 and §2 before upgrading |
+| **New Features** | `betterAuth.emailAndPassword.passwordReset` off switch (§1). `betterAuth.emailVerification.passwordResetBrevoTemplateId` (§3). Branded, locale-aware reset templates (§4). `CoreTenantService.getActiveMembership()` (§9) |
+| **Bugfixes** | `betterAuth.rateLimit: {}` / `{ max: N }` now actually enables the limiter, as documented (§2). Reset URLs are no longer written to logs in staging, and no longer survive log redaction (§5). `options.emailAndPassword` can no longer drop the scrypt password pair (§6). Expired `verification` documents are now removed by a TTL index (§7) |
+| **Migration Effort** | **§1, §2 and §9 are mandatory reading.** §4 matters only if you ship your own `password-reset.ejs`. The rest is automatic |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.36.1
+pnpm run build
+pnpm test
+```
+
+Then decide §1 (do you want the reset flow?) and check §2 (is your rate limiter actually on?).
+
+**Vendor-mode projects:** the changes span
+`modules/tenant/core-tenant.service.ts` (§9),
+`modules/better-auth/better-auth.config.ts`,
+`modules/better-auth/core-better-auth-email-verification.service.ts`,
+`modules/better-auth/core-better-auth.module.ts`,
+`modules/better-auth/core-better-auth.service.ts`,
+`modules/better-auth/core-better-auth-rate-limiter.service.ts`,
+`common/helpers/logging.helper.ts`,
+`common/interfaces/server-options.interface.ts` and `templates/password-reset*.ejs`.
+§1 and §2 each need their interface half AND their implementation half — taking the config field
+without the implementation gives you a setting that type-checks and does nothing.
+
+---
+
+## 1. Native password reset is now ON (behaviour change, no config needed)
+
+Better-Auth treats the **presence** of an `emailAndPassword.sendResetPassword` hook as the enable
+flag for `POST /iam/request-password-reset`. Until now nest-server wired no hook, so that route
+answered `RESET_PASSWORD_DISABLED` and no reset mail was ever sent — a password-reset page built
+against it could not work.
+
+`CoreBetterAuthModule` now always injects the hook, delegating to
+`CoreBetterAuthEmailVerificationService.sendPasswordResetEmail()`.
+
+**What changes for you on `pnpm update` alone:**
+
+- The route becomes a live, **unauthenticated**, token-minting, mail-sending endpoint.
+- Real users receive real reset mail — including anyone an attacker names.
+- If your `email.smtp` uses `jsonTransport` outside production, that mail is silently discarded on a
+  flow that previously failed loudly.
+
+**If you do not want the flow**, turn it off explicitly — there is no other off switch:
+
+```typescript
+// config.env.ts
+betterAuth: {
+  emailAndPassword: { passwordReset: false },
+},
+```
+
+**If you do want it**, verify before shipping:
+
+1. Your frontend reset page submits `POST /iam/reset-password` with `{ token, newPassword }`.
+2. `betterAuth.rateLimit` is genuinely on — see §2.
+3. `betterAuth.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 now warns at boot if it finds one.
+
+---
+
+## 2. `betterAuth.rateLimit` presence now enables the limiter (bugfix — check your config)
+
+`.claude/rules/configurable-features.md` has always documented this key as *"Presence Implies
+Enabled"*, and `LegacyAuthRateLimiter` has always implemented it that way. `CoreBetterAuthRateLimiter`
+did not: it spread your config over an `enabled: false` default without recomputing, and the
+middleware mount checked `.enabled` separately. So this silently limited **nothing**:
+
+```typescript
+betterAuth: {
+  rateLimit: { max: 20, windowSeconds: 60 },   // before 11.36.1: NO middleware, NO limiter
+},
+```
+
+Only an explicit `enabled: true` worked. Both layers now follow the documented contract.
+
+**What this means for you:** if you wrote a `rateLimit` block without `enabled: true` believing your
+auth endpoints were throttled, **they were not, and now they are**. Requests that previously always
+passed can now receive 429. Check your `max` / `windowSeconds` are values you actually want before
+upgrading — particularly on machines that share an egress IP, and particularly if `trustProxy` is
+unset (all clients then collapse onto one bucket).
+
+To keep the previous no-op behaviour, be explicit:
+
+```typescript
+betterAuth: {
+  rateLimit: { enabled: false, max: 20 },
+},
+```
+
+`strictEndpoints` also gained the routes Better-Auth actually serves. `/request-password-reset` and
+`/forget-password` now receive the halved limit; `/forgot-password` (a spelling Better-Auth uses
+nowhere) is kept only for projects that route it themselves.
+
+---
+
+## 3. Brevo template for the reset mail (new, optional)
+
+```typescript
+betterAuth: {
+  emailVerification: {
+    passwordResetBrevoTemplateId: 42,
+  },
+},
+```
+
+Deliberately separate from `brevoTemplateId` and with **no fallback to it** — that one is the
+verification mail, and reusing it would tell somebody who asked to reset their password to confirm
+their address instead. 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.
+
+Template variables: `name`, `link`, `appName`.
+
+---
+
+## 4. Reset mail templates — check yours renders (action required if you ship one)
+
+nest-server now ships `password-reset-de.ejs` and `password-reset-en.ejs` as branded HTML mails, and
+keeps `password-reset.ejs` as the plain fallback.
+
+**Project templates still win** via the usual project-first, locale-aware lookup, so if you ship your
+own `password-reset.ejs` you keep it and will not see the new design. Add
+`password-reset-<locale>.ejs` if you want per-locale variants.
+
+**The rule that matters:** the un-suffixed `password-reset.ejs` must render 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. Locale
+variants are only reached by the IAM flow and may use `appName` freely.
+
+`logoSrc` is supported by the shipped templates but is **not** passed by the framework — supply it
+from a subclass that overrides `sendPasswordResetEmail()` if you want a logo.
+
+---
+
+## 5. Reset URLs no longer leak into logs (security fix, automatic)
+
+Two problems, both fixed:
+
+- The development log line was gated on `process.env.NODE_ENV !== 'production'`. A staging
+  deployment sets `NODE_ENV=staging` so `getEnvironmentConfig()` loads its block — which passes that
+  test while holding real users. The gate is now `isProductionLikeEnv()`, the same two-layer check
+  (`config.env === 'production' || 'staging'`, or `NODE_ENV === 'production'`) that `EmailService`
+  and the cookie helpers already use. The address is masked, and `LT_LOG_AUTH_URLS=0` suppresses the
+  line entirely.
+- `redactSensitiveText()` masked `/reset/<token>` but not `/reset-password/<token>`, which is what
+  Better-Auth actually emits — so a reset token reached the ADMIN-readable Hub log panel verbatim.
+  The path rule now covers `request-password-reset`, `reset-password` and `forget-password`.
+
+The same treatment was applied to the verification-mail log line and to the module's fallback
+branches, which previously printed the URL through the NestJS logger with **no** environment gate at
+all.
+
+Nothing to configure. If you parse `[PASSWORD RESET]` / `[EMAIL VERIFICATION]` lines out of your own
+logs, note the address is now masked (`re***@test.com`).
+
+---
+
+## 6. `options.emailAndPassword` no longer drops the password hashing (security fix, automatic)
+
+`config.options` was merged with a shallow spread (only `advanced` was deep-merged). An
+`options.emailAndPassword` therefore did not add a key — it **replaced the whole block**, including
+the `password: { hash, verify }` scrypt pair nest-server installs. Better-Auth fell back to its own
+hasher, every stored credential stopped verifying, and every user of that deployment was locked out
+at once, at runtime and with nothing in the logs. The module README recommended exactly that shape.
+
+`emailAndPassword` is now deep-merged, with `password` merged key-by-key on top of the framework's
+pair. An explicit override still wins; an explicitly-`undefined` half is ignored (Better-Auth
+resolves `password?.hash || hashPassword`, so honouring `undefined` would switch the hasher for
+writes while scrypt still handled reads — an asymmetric pair, and anyone who reset their password
+could never sign in again).
+
+**If you worked around the old behaviour** by re-specifying `password.hash` / `password.verify`
+defensively in `options.emailAndPassword`, you can remove that now. **If you set `sendResetPassword`
+there**, note it still wins over the framework hook — your callback replaces
+`sendPasswordResetEmail()` entirely and loses the fire-and-forget wrapper that keeps response time
+from revealing whether an address exists. Prefer the service override.
+
+---
+
+## 7. `verification` documents now expire (automatic)
+
+Better-Auth writes a `verification` document per email-verification and per password-reset request,
+and removes it only when the token is **consumed**. With an unauthenticated reset route, every
+un-clicked request left a row that nothing would ever delete.
+
+`CoreBetterAuthService.onModuleInit()` now creates a TTL index on `verification.expiresAt`
+(`expireAfterSeconds: 0`) alongside an `identifier` lookup index. Both are idempotent.
+
+**Existing deployments:** MongoDB removes already-expired documents within ~60 s of the index being
+built. If your `verification` collection has grown large, expect a one-off background deletion pass
+after the first boot on 11.36.1.
+
+---
+
+## 8. Per-address cooldown on reset mail (automatic)
+
+`sendPasswordResetEmail()` reuses the existing `emailVerification.resendCooldownSeconds` window
+(default 60 s) under its own namespace, so a pending verification mail cannot block a reset and vice
+versa. A send that fails releases the slot, so a transient SMTP error does not lock the user out of
+retrying.
+
+This is the axis that matters: an attacker rotating IPs to mail-bomb one victim is bounded by the
+recipient-address cooldown, not by the IP-keyed limiter.
+
+---
+
+## 9. Tenant membership: use `getActiveMembership()` for authorization (audit required)
+
+`CoreTenantService.getMembership()` answers **regardless of status**. A removal is a status change
+to `SUSPENDED`, not a delete — so it still returns a row for somebody who was thrown out. That is
+deliberate and `addMember()` depends on it (it reactivates the existing row instead of creating a
+duplicate).
+
+It is therefore the **wrong method for an authorization decision**. Asking "is this user a member
+with role X?" through it answers yes for a removed member, so a route that guards itself this way
+keeps granting a suspended administrator the right to invite, remove and re-role — the very rights
+that removing them was supposed to take away.
+
+**A new method makes the distinction explicit:**
+
+```typescript
+// Deciding what somebody MAY DO → active only
+const membership = await this.tenantService.getActiveMembership(tenantId, userId);
+if (!membership) throw accessDeniedException(currentUser);
+
+// Looking up a row REGARDLESS of status (reactivation, audit views, admin UIs)
+const anyMembership = await this.tenantService.getMembership(tenantId, userId);
+```
+
+`getActiveMembership()` returns `null` for a suspended or invited membership, and `null` for an
+empty/blank id rather than matching an arbitrary row. Its query is identical to the one
+`CoreTenantGuard` already uses internally, so the two now agree by construction.
+
+**Who needs to act.** `CoreTenantGuard` always filtered on `ACTIVE`, so anything guarded by it was
+never affected. The exposure is in routes that carry `@SkipTenantCheck()` and decide for themselves —
+the guard never sees those. **Audit your project for `getMembership(` used in a permission decision**
+and switch those call sites:
+
+```bash
+grep -rn "getMembership(" src/ | grep -v "getActiveMembership"
+```
+
+**Behaviour change inside the framework.** `updateMemberRole()` and `assertNotLastOwner()` now resolve
+the membership with `getActiveMembership()`. Previously `assertNotLastOwner()` was internally
+inconsistent: it counted owners with `status: ACTIVE` but resolved the membership without a status
+filter, so a **suspended** owner could trigger `"Cannot remove or demote the last owner of a tenant"`
+while not being counted as one. That error no longer fires for a non-active membership.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Users suddenly receive password-reset mail | §1 — the flow is now on | Intended. Set `emailAndPassword.passwordReset: false` to opt out |
+| `POST /iam/request-password-reset` returns 429 | §2 — your `rateLimit` block is now effective | Raise `max`, or set `enabled: false` to restore the previous no-op |
+| Legacy `POST /users/password/reset-request` returns 500 | Your own `password-reset.ejs` references a variable the legacy caller does not pass | §4 — keep the un-suffixed template renderable from `{ link, name }` alone |
+| Reset mail no longer shows the app name | Your template uses `appName` and is reached by the legacy flow | §4 — guard with `typeof appName !== 'undefined'` |
+| `[PASSWORD RESET]` log line is gone | §5 — you are on a production-like env, or `LT_LOG_AUTH_URLS=0` | Intended. Use the Hub mailbox in development |
+| Boot warning about `trustedOrigins` wildcard | §1 — the reset redirect carries the token | List exact origins |
+| `"Cannot remove or demote the last owner"` stopped firing | §9 — it no longer counts a suspended membership | Intended; the membership was not an active owner |
+
+---
+
+## Module Documentation
+
+- [BetterAuth README](../src/core/modules/better-auth/README.md) — password-reset configuration, rate limiting, template branding
+- [BetterAuth INTEGRATION-CHECKLIST](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md) — the four-point password-reset checklist
+- [BetterAuth CUSTOMIZATION](../src/core/modules/better-auth/CUSTOMIZATION.md) — `sendPasswordResetEmail()` override point, template variables
+- [Configurable Features](../.claude/rules/configurable-features.md) — `passwordReset`, `passwordResetBrevoTemplateId`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.36.0",
+  "version": "11.36.1",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -166,14 +166,14 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1112.0",
-    "@aws-sdk/s3-request-presigner": "3.1112.0",
+    "@aws-sdk/client-s3": "3.1115.0",
+    "@aws-sdk/s3-request-presigner": "3.1115.0",
     "@compodoc/compodoc": "2.0.0",
     "@nestjs/cli": "11.0.24",
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.2.1",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.16.0",
+    "@swc/core": "1.16.1",
     "@tus/s3-store": "2.0.6",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
@@ -184,18 +184,18 @@
     "@types/node": "26.2.0",
     "@types/nodemailer": "8.0.1",
     "@types/passport": "1.0.17",
-    "@vitest/coverage-v8": "4.1.10",
-    "@vitest/ui": "4.1.10",
+    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/ui": "4.1.11",
     "ansi-colors": "4.1.3",
-    "bullmq": "6.1.2",
+    "bullmq": "6.2.0",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
     "ioredis": "6.0.0",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.1",
-    "oxfmt": "0.63.0",
-    "oxlint": "1.78.0",
+    "oxfmt": "0.64.0",
+    "oxlint": "1.79.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
@@ -203,9 +203,9 @@
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "1.5.11",
-    "vite": "8.2.1",
+    "vite": "8.2.2",
     "vite-plugin-node": "8.0.0",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core/common/helpers/logging.helper.ts

@@ -159,8 +159,16 @@ export function redactSensitiveText(text: string): string {
       .replace(/eyJ[\w-]{6,}\.[\w-]{6,}\.[\w-]{4,}/g, (match) => maskToken(match))
       // reset/verification/invite tokens carried as a URL PATH segment (e.g. /verify/<token>,
       // /reset/<token>) — these have no `key=value`, so the query-style rule below misses them.
+      //
+      // The COMPOUND spellings must come first and must be listed at all: Better-Auth emits
+      // `/reset-password/<token>`, and a bare `reset` alternative does not match it (`reset` is
+      // followed by `-password`, not `/`). That gap let a full account-takeover URL through
+      // `HubLogBufferService` into the ADMIN-readable Hub log panel verbatim, while the
+      // verification token — which travels as `?token=` and is caught by the rule below — was
+      // correctly masked. Order matters: alternation is first-match, so `reset-password` has to
+      // precede `reset`.
       .replace(
-        /(\/(?:verify|reset|confirm|activate|invite|magic-?link|set-password|change-email)\/)([A-Za-z0-9._~-]{16,})/gi,
+        /(\/(?:request-password-reset|reset-password|forget-password|forgot-password|set-password|change-email|magic-?link|verify|reset|confirm|activate|invite)\/)([A-Za-z0-9._~-]{16,})/gi,
         (_m, prefix, token) => `${prefix}${maskToken(token)}`,
       )
       // authorization: Bearer xyz / Authorization=xyz

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;
 
@@ -3415,6 +3437,22 @@ interface IBetterAuthBase {
      */
     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.
      *
@@ -3427,12 +3465,16 @@ interface IBetterAuthBase {
      * the devices they still hold.
      *
      * Passed through to better-auth's native
-     * `emailAndPassword.revokeSessionsOnPasswordReset`. It cannot be set via
-     * `options` instead: that object is spread SHALLOWLY over the resolved
-     * config, so an `options.emailAndPassword` would replace the whole block
-     * — including the scrypt `password.hash` / `password.verify` pair this
-     * framework installs — and every credential in the database would stop
-     * verifying.
+     * `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

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`.