@lenne.tech/nest-server 11.37.0 → 11.38.0

package/docs/REQUEST-LIFECYCLE.md

@@ -78,7 +78,7 @@ JWT-based authentication for existing projects:
 | **Refresh Tokens** | Automatic token renewal |
 | **Sign In / Sign Up / Logout** | GraphQL mutations + REST endpoints |
 | **Rate Limiting** | Configurable per-endpoint rate limits (`auth.rateLimit`). Same `RateLimitStore` selection, async signatures and Redis-outage degradation as the BetterAuth row above (namespace `legacy-auth`) |
-| **Legacy Endpoint Controls** | Disable legacy endpoints after migration (`auth.legacyEndpoints`) |
+| **Legacy Endpoint Controls** | Legacy endpoints are OFF unless `auth.legacyEndpoints.enabled: true` (default flipped in 11.38.0 — it was an opt-out, it is now an opt-in). `CoreLegacyAuthDeprecationInitializer` reports the state and the IAM migration progress at boot |
 | **Migration Tracking** | `betterAuthMigrationStatus` query for monitoring |
 
 #### Role System
@@ -592,6 +592,40 @@ If authentication succeeds, `req.user` is set with the authenticated user (inclu
 > raw-forwarded routes. A forged `POST /iam/update-user {"roles":["admin"]}` is rejected with
 > `FIELD_NOT_ALLOWED` (HTTP 400) at the input-parse stage, before any persistence.
 
+> **"Raw" has one exception since 11.38.0: the password-setting reset routes.**
+> `CoreBetterAuthApiMiddleware.normalizeResetPassword()` rewrites the password field of
+> `/reset-password`, `/email-otp/reset-password` and `/phone-number/reset-password` to its
+> normalized (sha256) form **before** building the Web Request, then runs the Better-Auth handler
+> inside an `AsyncLocalStorage` context carrying that value.
+>
+> Both halves are load-bearing. Without the rewrite, a client posting a plaintext password would
+> have `scrypt(plaintext)` stored while every sign-in — which *is* normalized, in
+> `CoreBetterAuthController` — checks `scrypt(sha256(...))`: the account is locked out with the
+> password its owner just chose. Without the context, `emailAndPassword.onPasswordReset` knows
+> *which* user was reset but not to *what*, and cannot mirror the new password into the legacy
+> bcrypt store — leaving the old password valid on the legacy path after a reset.
+>
+> A project subclassing the middleware must know this: the body it forwards is no longer
+> byte-identical to the body it received. `normalizeResetPassword()` is `protected`.
+
+#### 2b. SecurityHeadersMiddleware
+
+Sets the browser security headers on **every** response — `X-Content-Type-Options`,
+`X-Frame-Options`, `Referrer-Policy`, `Strict-Transport-Security`, and the removal of
+`X-Powered-By`. On by default; `security.headers: false` disables it, individual fields switch off
+individually. No CSP is sent unless one is configured.
+
+Middleware rather than an interceptor, and the distinction is the whole point: an interceptor never
+runs for a request a guard turns away, and a `401` is still a response a browser renders. Those are
+also the responses an attacker generates most of. `tests/security-headers.e2e-spec.ts` asserts the
+headers on an actual guard rejection rather than trusting the ordering.
+
+HSTS is decided by the request protocol — `x-forwarded-proto` first, connection protocol as
+fallback — and never by configuration. A browser remembers it, so one sent over `http://localhost`
+makes every project on that host unreachable over http for up to a year, with no server-side undo.
+Behind a TLS-terminating proxy the inward connection is plain http, which makes `trustProxy`
+load-bearing for this header too.
+
 #### 3. graphqlUploadExpress
 
 Only for GraphQL routes. Handles multipart file upload requests according to the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec).

package/migration-guides/11.37.x-to-11.38.x.md

@@ -0,0 +1,511 @@
+# Migration Guide: 11.37.x → 11.38.x
+
+> **This MINOR contains breaking changes.** In this repository the MAJOR digit states which NestJS
+> major the package targets and moves only when NestJS does, so a breaking change ships as a MINOR.
+> Read the version number as "NestJS 11, breaking step 38", not as a semver promise.
+
+## Overview
+
+| Category | Change | Effort |
+|----------|--------|--------|
+| **Breaking** | `auth.legacyEndpoints.enabled` now defaults to **`false`** | Low — one config line, only for projects still using Legacy Auth |
+| **Bugfix (security)** | A password reset now reaches **both** credential stores | None — but read *Existing users* below |
+| **Bugfix** | Native IAM reset routes normalize the password like sign-in does | None |
+| **New** | Boot warning naming the IAM migration status while Legacy Auth is open | None |
+| **Breaking (safe direction)** | Security headers are sent by default | None — unless a proxy already sets conflicting ones |
+| **Breaking (safe direction)** | The password-reset request no longer reveals whether an account exists | Low — one config line if you want the old hint back |
+| **Changed** | The password-reset mail links to the app instead of the API | Low — only if your reset page reads a PATH parameter |
+
+Nothing here changes the API surface of `CoreModule.forRoot()`. A project created from
+`nest-server-starter` — i.e. `CoreModule.forRoot(envConfig)`, IAM only — is unaffected by the
+breaking change and only gains the fixes.
+
+---
+
+## Quick Migration
+
+For an IAM-only project — the one-argument `CoreModule.forRoot(envConfig)` the starter uses —
+this release needs no code change at all:
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run build
+pnpm test
+```
+
+If you call the **three-argument** form, decide one config line first (§1):
+
+```typescript
+// config.env.ts — only if your users still need Legacy Auth
+auth: {
+  legacyEndpoints: { enabled: true },
+},
+```
+
+Then upgrade as above. The boot log tells you when you can remove that line again.
+
+---
+
+## 1. Breaking: Legacy Auth endpoints are off unless asked for
+
+### What changed
+
+`auth.legacyEndpoints.enabled` defaulted to `true`. A project that registered the legacy auth module
+and never made a decision therefore kept a second, fully functional password-authentication surface
+open indefinitely — `signIn`, `signUp`, `logout`, `refreshToken` over GraphQL and
+`/auth/signin`, `/auth/signup`, `/auth/logout`, `/auth/refresh-token` over REST.
+
+Since 11.38.0 the default is `false`. Disabled endpoints answer **HTTP 410 Gone**, as they always
+did when switched off explicitly.
+
+### Are you affected?
+
+Only if **all** of these are true:
+
+1. You call the three-argument form
+   `CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig)`, **and**
+2. you did not set `auth.legacyEndpoints` at all, **and**
+3. a client still uses a legacy endpoint.
+
+```bash
+# Do you register the legacy module?
+grep -n "CoreModule.forRoot(" src/server/server.module.ts
+
+# Did you already decide?
+grep -n "legacyEndpoints" src/config.env.ts
+```
+
+`CoreModule.forRoot(envConfig)` — the one-argument form the starter uses — never registers the
+legacy module, so none of this applies.
+
+### Migration
+
+If your users still need Legacy Auth, say so explicitly:
+
+```typescript
+// config.env.ts
+auth: {
+  legacyEndpoints: { enabled: true },
+},
+```
+
+If you were already migrating, this is the moment to finish. Ask the server how far it got:
+
+```graphql
+query {
+  betterAuthMigrationStatus {
+    totalUsers
+    fullyMigratedUsers
+    migrationPercentage
+    canDisableLegacyAuth
+    pendingUserEmails
+  }
+}
+```
+
+Once `canDisableLegacyAuth` is `true`, leave the new default in place and delete the config line.
+
+Since 11.38.0 you no longer have to ask: while any legacy endpoint is open, every boot logs the
+same figure. It is **best-effort** — the read runs detached from the boot so it cannot delay
+readiness, and a failure is swallowed at debug level. So the deprecation warning can appear
+without a percentage line under it; that means the status could not be read, not that there is
+nothing to report.
+
+The mirror case is reported too, and it is the one worth watching after this upgrade: when the
+endpoints are closed **while users are still unmigrated**, the boot says so and names the way
+back.
+
+```
+[CoreLegacyAuthDeprecationInitializer] Legacy Auth is ENABLED (GraphQL + REST). 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.
+[CoreLegacyAuthDeprecationInitializer] IAM migration status: 84/97 users migrated (87%).
+```
+
+### Per-transport flags
+
+`graphql` and `rest` still override `enabled` for one transport, with one rule made explicit:
+**an explicit `enabled: false` cannot be reopened by a per-transport `true`.** It is the setting a
+project reached for to close legacy down, and an upgrade must never widen it.
+
+| Configuration | Result |
+|---------------|--------|
+| `enabled: false` | off, whatever `graphql` / `rest` say |
+| `graphql: true` (no `enabled`) | GraphQL on, REST off |
+| `enabled: true` | both on |
+| nothing set | **off** (was: on) |
+
+Both transports now resolve this through one shared function, `isLegacyEndpointEnabled()`, exported
+from the package. If you override `checkLegacyGraphQLEnabled()` or `checkLegacyRESTEnabled()`, use
+it rather than re-implementing the table.
+
+---
+
+## 2. Security fix: a password reset now reaches both credential stores
+
+### What was wrong
+
+Legacy Auth stores `bcrypt(sha256(password))`, IAM stores `scrypt(sha256(password))`. Neither hash
+can be derived from the other, so a deployment running both has to write both on every password
+change. Two halves of that were broken, in opposite directions:
+
+**Legacy reset → IAM.** `CoreUserService.resetPassword()` and `.update()` skipped the IAM sync
+whenever the incoming password was already a 64-character hex string, on the reasoning that IAM
+"needs the plain password". It does not — `hashPasswordForBetterAuth()` runs its input through
+`normalizePasswordForIam()`, which passes a sha256 value through unchanged. And the lt auth client
+hashes in the browser (`ltSha256`, seven call sites in `@lenne.tech/nuxt-extensions`), so **the
+skipped branch was the only branch a real frontend ever took**. The legacy store got the new
+password, the IAM credential kept the old one, and the endpoint reported success either way.
+
+**IAM reset → legacy.** Nothing mirrored a Better-Auth reset back into the legacy store at all.
+
+The failure only surfaced at the next sign-in, to somebody who by definition had already lost their
+way in — and a reset performed *because* a password leaked did not actually revoke it.
+
+### What changed
+
+- Both `resetPassword()` and `update()` pass the submitted password to the IAM sync exactly as
+  received, whatever its shape.
+- `emailAndPassword.onPasswordReset` is now wired and mirrors an IAM reset into the legacy bcrypt
+  store, for every native reset route (token, email-OTP, phone-number).
+- A sync that does **not** happen is now logged as a warning instead of a success line. A silent
+  `false` return is how this stayed invisible.
+
+### Existing users
+
+The fix is forward-only for accounts that already reset during the broken window: their two stores
+still hold different passwords. **One further reset repairs the account** — `syncPasswordChangeToIam`
+rewrites an existing credential, so both stores converge in a single pass. No repair script is
+needed, and no data migration.
+
+There is nothing to do proactively. Affected users are not locked out: the password that works is
+the one from *before* the failed reset.
+
+---
+
+## 3. Bugfix: native IAM reset routes normalize the password
+
+`/iam/sign-in/email` and `/iam/sign-up/email` are handled by `CoreBetterAuthController`, which
+normalizes the password (`normalizePasswordForIam`). The native reset routes are forwarded to
+Better-Auth instead, and nothing normalized them.
+
+So a client that posted a **plaintext** password to `POST /iam/reset-password` stored
+`scrypt(plaintext)`, while every later sign-in checks `scrypt(sha256(plaintext))` — the account was
+locked out with the password its owner had just chosen, one request after being told the reset
+succeeded. A client that hashes first (every lt frontend) was unaffected, which is why it went
+unnoticed.
+
+`CoreBetterAuthApiMiddleware` now normalizes `/reset-password`, `/email-otp/reset-password` and
+`/phone-number/reset-password` before forwarding. No configuration required — with two things
+worth knowing:
+
+**Password length is now enforced by nest-server, and only on what the client actually sends.**
+Because the body is normalized to a 64-character sha256 before Better-Auth sees it, Better-Auth's
+own `minPasswordLength` / `maxPasswordLength` can never fire on these routes. nest-server therefore
+checks the submitted value itself (8–128 by default, or your
+`betterAuth.options.emailAndPassword.minPasswordLength` / `maxPasswordLength`) and answers **400**
+on a violation.
+
+Two things worth stating exactly, because it is easy to read this as a regression it is not:
+
+- **For a client that hashes before sending — every lt frontend does — nothing changed.**
+  Better-Auth's length check reads the submitted value, so a 64-character sha256 already defeated
+  it on every earlier version. This release does not open that gap; it makes it visible.
+- **For a client that sends plaintext, this is a net gain.** Better-Auth's check used to apply and
+  now cannot, so nest-server's replaces it — same enforcement, one layer earlier.
+
+Either way, **a hashed password carries no length information, so the policy has to live in your
+form as well.** The starter's `reset-password.vue`, `register.vue` and `setup.vue` all declare
+`v.minLength(8)`; a project using `@lenne.tech/nuxt-extensions` without those forms has to add it.
+
+**Normalization needs `CoreBetterAuthUserMapper` resolvable.** Every module variant that registers
+the middleware also provides the mapper, so this is not something you configure. If it is somehow
+absent the middleware now logs an **error** naming the consequence rather than forwarding quietly —
+the previous silence would have stored `scrypt(plaintext)` against a sign-in that checks
+`scrypt(sha256(...))`.
+
+### Sessions are not revoked by a reset unless you ask
+
+Related, and easy to assume otherwise now that the parity fix has landed: **a reset lands in both
+stores, but that is not the same as securing the account.** Since 11.38.0 the legacy reset also
+clears `refreshTokens`, so legacy sessions end — but the IAM half is opt-in:
+
+```typescript
+betterAuth: {
+  emailAndPassword: {
+    // Recommended. A reset is what somebody reaches for after a suspected takeover.
+    revokeSessionsOnPasswordReset: true,
+  },
+},
+```
+
+Off by default because it is a behaviour change for an existing deployment: after a reset the user
+is signed out everywhere, including on the devices they still hold.
+
+### Rate limiting is part of the definition of done here
+
+`POST /iam/request-password-reset` is unauthenticated, mints a token and sends mail, and the reset
+path now performs **two** expensive key derivations instead of one (scrypt for IAM plus bcrypt for
+the legacy mirror), each occupying a libuv threadpool slot. The IP-axis limiter is **off unless
+configured**:
+
+```typescript
+betterAuth: {
+  rateLimit: {},  // presence enables it; /request-password-reset gets the halved strict limit
+},
+```
+
+---
+
+## 4. Client side: use the framework's hashing, never your own
+
+The password hashing lives in `@lenne.tech/nuxt-extensions`' auth client, so no call site can forget
+it. Since **`@lenne.tech/nuxt-extensions` 1.16.0** — a different package with its own version
+line, not this one — the composable exposes the full pair:
+
+```typescript
+const { requestPasswordReset, resetPassword } = useLtAuth();
+
+await requestPasswordReset({ email, redirectTo: appUrl('/auth/reset-password') });
+await resetPassword({ newPassword, token });
+```
+
+**Do not hash passwords in project code.** A private `sha256` helper next to a `fetch` call is how a
+project ends up on a path the framework does not cover — and it is exactly how the defect in §2 was
+found in the field.
+
+If your project posts to the legacy `POST /users/password/reset-request` / `POST /users/password/reset`
+routes, prefer the IAM pair above. The legacy routes keep working (they are on the user module, not
+the auth module, so §1 does not close them), but they are the deprecated path.
+
+---
+
+## 5. Security headers are now sent by default
+
+`@lenne.tech/nest-server` set no browser security headers at all. Projects were rebuilding the same
+set by hand — one inline in `main.ts`, one as its own middleware — and a freshly generated project
+sent none. A missing header produces no error anywhere; it surfaces in a pentest report months
+later.
+
+Since 11.38.0 every response carries them, with no configuration:
+
+| Header | Value |
+|--------|-------|
+| `X-Content-Type-Options` | `nosniff` |
+| `X-Frame-Options` | `DENY` |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` |
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` — **only on an https request** |
+| `X-Powered-By` | removed |
+| `Content-Security-Policy` | **not sent** — opt-in only |
+
+They are set as **middleware**, so a request a guard rejects carries them too. That is deliberate:
+a `401` is still a response a browser renders, and those are the responses an attacker generates
+most of.
+
+### What you may need to change
+
+- **A reverse proxy already setting these** (Traefik, Caddy, nginx): nothing. The proxy writes
+  last, so its values win. This layer exists so a deployment *without* one is not bare.
+- **You embed your app in an iframe**: `X-Frame-Options: DENY` will block it. Set
+  `security: { headers: { frameOptions: 'SAMEORIGIN' } }` — or `false` for that field.
+- **You want a CSP**: set `contentSecurityPolicy` explicitly. There is no default because a wrong
+  one breaks the application rather than hardening it, and this package serves its own HTML from
+  the Hub and the GraphQL playground.
+- **Turn everything off**: `security: { headers: false }`.
+
+### HSTS never follows configuration
+
+It is decided by the request protocol — `x-forwarded-proto` first (the first hop of a chain),
+connection protocol as fallback. There is no flag that switches it on regardless, and that is a
+safety property rather than an omission: a browser **remembers** the header, so one sent from a dev
+server over `http://localhost` makes every project on that host unreachable over http for up to a
+year, and nothing on the server can withdraw it.
+
+One consequence worth knowing: behind a TLS-terminating proxy the connection reaching Node is plain
+http, so **`trustProxy` has to be configured** or no production request looks secure and no HSTS is
+sent. `preload` is off by default — it commits every subdomain to a browser-vendor list that is
+awkward to reverse, which is the domain owner's decision.
+
+---
+
+## 6. The password-reset request no longer reveals whether an account exists
+
+`POST /users/password/reset-request` answered **404** for an unknown address and **201** for a known
+one — a working oracle for "does this person have an account here". In a multi-tenant product that
+also answers who works at which customer. The framework already answered this correctly on the IAM
+path (Better-Auth returns the same body either way), so the two halves of one framework disagreed
+about the same question.
+
+Since 11.38.0 both cases answer identically. `CoreUserService.setPasswordResetTokenForEmail()`
+returns `null` for an unknown address instead of throwing.
+
+### The status code is the smaller half — and this affects YOUR code
+
+Response **time** separates the two cases far more loudly than the status code: the known path
+sends mail, which is a network round trip orders of magnitude above everything else in the request.
+A fix that changed only the status code would have given up the "unknown address" hint in the UI
+and kept the oracle fully intact.
+
+The framework equalises what it controls. The mail send lives in **your** `sendPasswordResetMail()`,
+so that half is yours:
+
+```typescript
+async sendPasswordResetMail(email: string, serviceOptions?: ServiceOptions): Promise<null | User> {
+  const user = await super.setPasswordResetTokenForEmail(email, serviceOptions);
+
+  if (!user) {
+    return null;   // unknown address — answer exactly as for a known one
+  }
+
+  // NOT awaited. Awaiting it makes the known path visibly slower whatever the status code says.
+  void this.emailService.sendMail(user.email, 'Password reset', { /* … */ })
+    .catch((error: unknown) => this.userServiceLogger.error(`Failed to send: ${String(error)}`));
+
+  return user;
+}
+```
+
+The reference implementation is `src/server/modules/user/user.service.ts`; copy that shape.
+
+### Migration
+
+Two things to check:
+
+1. **The return type widened to `null | TUser`.** If you override
+   `setPasswordResetTokenForEmail()` or call it directly, handle `null`.
+2. **Your reset form can no longer say "we do not know this address".** That is the only UX cost —
+   the endpoint carries no password, so the "wrong password vs unknown address" distinction is not
+   affected (that lives at sign-in, governed by the separate `auth.preventUserEnumeration`).
+
+To restore the old behaviour:
+
+```typescript
+auth: {
+  passwordReset: { preventUserEnumeration: false },
+},
+```
+
+---
+
+## 7. The password-reset mail now links to the app
+
+The mail used to carry the link Better-Auth generates, and that points at the **API**:
+
+```
+https://api.example.com/iam/reset-password/<token>?callbackURL=https://example.com/auth/reset-password
+```
+
+It works — the API validates the token and redirects to the app — but it puts a domain the
+recipient does not recognise into a password mail, which is the one thing people are trained to
+check before clicking. Since 11.38.0 the link points at the app:
+
+```
+https://example.com/auth/reset-password?token=<token>
+```
+
+### What this gives up, plainly
+
+Better-Auth's redirect route validates the token and its expiry **before** forwarding, so an
+expired link produced an error page rather than a form that fails on submit. Linking straight to
+the app moves that error later.
+
+It is **not** a security difference: the token ends up in the app URL either way, and the
+`callbackURL` origin check exists only because of the hop that is being removed. If you prefer the
+early error, keep the old behaviour:
+
+```typescript
+betterAuth: { emailVerification: { passwordResetLink: false } },
+```
+
+### Configuring it
+
+```typescript
+betterAuth: {
+  emailVerification: {
+    // Absolute, relative (resolved against appUrl), or with a {token} placeholder
+    passwordResetLink: 'https://example.com/auth/reset-password/{token}',
+  },
+},
+```
+
+`{token}` is substituted wherever it appears — that is what lets a page reading a **path**
+parameter work. Without the placeholder, `?token=` is appended.
+
+### Are you affected?
+
+- **Your reset page reads `?token=`** (the starter's shape): nothing to do.
+- **Your reset page reads a path parameter**: configure the `{token}` form above, or the link will
+  not match your route.
+- **No `appUrl` resolvable**: the old link is kept. A guessed host would 404, which is worse than a
+  working link — so this fails back rather than forward.
+
+Note this is separate from `email.passwordResetLink`, which serves the legacy
+`/users/password/reset-request` flow and appends the token as a path segment. A project using both
+should point them at the same page.
+
+---
+
+## 8. Vendor mode: three atomic file sets
+
+Projects that vendor `src/core/` into their own tree (no npm dependency, updated via
+`/lt-dev:backend:update-nest-server-core`) sync file by file. This release adds three new files,
+and each one is **already imported** by files it ships alongside — taking the importer without
+its new leaf leaves an unresolvable import.
+
+| New file | Existing core files that now import it |
+|---|---|
+| `auth/helpers/legacy-endpoints.helper.ts` | `auth/core-auth.controller.ts`, `auth/core-auth.resolver.ts`, `auth/core-legacy-auth-deprecation.initializer.ts`, `index.ts` |
+| `auth/core-legacy-auth-deprecation.initializer.ts` | `auth/core-auth.module.ts`, `index.ts` |
+| `better-auth/core-better-auth-password-reset.registry.ts` | `better-auth/core-better-auth-api.middleware.ts`, `better-auth/core-better-auth.module.ts` |
+| `common/middlewares/security-headers.middleware.ts` | `core.module.ts`, `index.ts` |
+
+**One dependency crosses a module boundary that did not exist before.** `CoreAuthModule` now
+registers `CoreLegacyAuthDeprecationInitializer`, which imports `CoreBetterAuthUserMapper` — so
+`auth/` transitively depends on `better-auth/`. A sync that takes `auth/` but leaves `better-auth/`
+at the old revision will not compile. Take both, or neither.
+
+The registry is marked `@internal` because it is not public API — that is not the same as
+optional. It is a mandatory file: two shipped core files import it.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status | Note |
+|---------|--------|------|
+| `CoreModule.forRoot(envConfig)` (IAM only) | Unaffected | The legacy module is never registered, so §1 cannot apply |
+| `CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(...), envConfig)` | **Check §1** | The default flip lands here |
+| Overriding `checkLegacyGraphQLEnabled()` / `checkLegacyRESTEnabled()` | Compatible | Both still `protected`. Call the exported `isLegacyEndpointEnabled()` rather than re-implementing the table |
+| Overriding `CoreUserService.resetPassword()` / `.update()` | Compatible | Signatures unchanged. A project override that added its own IAM sync as a workaround is now redundant — the second write is equivalent, so it can be dropped without a migration |
+| Subclassing `CoreBetterAuthApiMiddleware` | **Check** | `normalizeResetPassword()` is new and `protected`; the middleware now mutates `req.body` on the three reset routes before forwarding |
+| Setting `betterAuth.options.emailAndPassword` | Compatible | `password` and `onPasswordReset` are protected against being clobbered — see below |
+| Setting `betterAuth.options.emailAndPassword.onPasswordReset` | Compatible, behaviour worth knowing | Yours is **chained after** the framework's legacy mirror rather than replacing it. Both run; neither can silently cancel the other |
+| `LEGACY_AUTH_ENABLED=1` / `=yes` | **Breaking** | The value is matched strictly against `'true'`. A truthy-but-not-`'true'` value now resolves to off |
+| Embedding the app in an iframe | **Check §5** | `X-Frame-Options: DENY` is now sent. Set `frameOptions: 'SAMEORIGIN'` or `false` |
+| A reverse proxy already setting security headers | Compatible | The proxy writes last, so its values win |
+| Overriding `setPasswordResetTokenForEmail()` | **Check §6** | Return type widened to `null | TUser`; handle the unknown-address case |
+| A reset form that says "unknown address" | **Check §6** | The endpoint no longer distinguishes. Set `auth.passwordReset.preventUserEnumeration: false` to restore it |
+| A reset page reading `?token=` | Compatible | The new default link uses exactly that shape |
+| A reset page reading a PATH parameter | **Check §7** | Configure `passwordResetLink: '…/reset-password/{token}'` |
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `410 Gone` on `/auth/signin` or the `signIn` mutation after upgrading | §1 — the default flipped | Set `auth.legacyEndpoints: { enabled: true }` if you still need Legacy Auth |
+| A user reset their password before upgrading and the new one is refused | The IAM credential kept the old password (§2) | Reset once more; both stores converge |
+| Boot log warns about Legacy Auth on every start | Intended — legacy endpoints are open | Finish the migration, then remove `enabled: true` |
+| `Password reset ... was NOT synced to IAM (no credential account)` | The user exists in Legacy Auth only | Expected while migrating; the account gains a credential on its first IAM sign-in |
+| The app stopped rendering inside an iframe | §5 — `X-Frame-Options: DENY` | `security: { headers: { frameOptions: 'SAMEORIGIN' } }` |
+| No `Strict-Transport-Security` in production | The request does not look secure to the server | Configure `trustProxy` — behind a TLS-terminating proxy the inward connection is plain http (§5) |
+| A reset request for an unknown address returns 201 instead of 404 | §6 — intended | `auth.passwordReset: { preventUserEnumeration: false }` if you need the old behaviour |
+| TypeScript error on `setPasswordResetTokenForEmail()` | §6 — return type widened to `null | TUser` | Handle the `null` case |
+| The reset link in the mail 404s on the app | §7 — the link now points at the app, and your route shape differs | Configure `passwordResetLink` with `{token}`, or set it to `false` |
+
+## Module Documentation
+
+- [Better-Auth README](../src/core/modules/better-auth/README.md)
+- [Better-Auth Integration Checklist](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- [Module Deprecation Roadmap](../.claude/rules/module-deprecation.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.37.0",
+  "version": "11.38.0",
   "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",

package/src/config.env.ts

@@ -520,6 +520,10 @@ const config: { [env: string]: IServerOptions } = {
       maxIterations: 5,
       rateLimit: { max: 20, windowSeconds: 60 },
     },
+    // Legacy auth is OFF by default since 11.38.0 (see isLegacyEndpointEnabled). This
+    // repository's own `src/server` registers the legacy module and its suites exercise
+    // BOTH auth systems, so every non-production environment here opts in explicitly —
+    // which is exactly what a project still running legacy now has to do.
     auth: {
       legacyEndpoints: { enabled: true },
     },
@@ -653,7 +657,11 @@ const config: { [env: string]: IServerOptions } = {
   // ===========================================================================
   production: {
     auth: {
-      legacyEndpoints: { enabled: process.env.LEGACY_AUTH_ENABLED !== 'false' },
+      // Opt-IN since 11.38.0: an unset LEGACY_AUTH_ENABLED now means "no legacy auth",
+      // not "legacy auth, because nobody said otherwise". Deployments that still need
+      // the legacy endpoints set LEGACY_AUTH_ENABLED=true until their users are migrated
+      // (`betterAuthMigrationStatus.canDisableLegacyAuth` says when they are).
+      legacyEndpoints: { enabled: process.env.LEGACY_AUTH_ENABLED === 'true' },
     },
     automaticObjectIdFiltering: true,
     baseUrl: process.env.BASE_URL,