@lenne.tech/nest-server 11.37.0 → 11.39.0

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

@@ -0,0 +1,456 @@
+# Migration Guide: 11.38.x → 11.39.x
+
+## Overview
+
+| Category | Change | Effort |
+|----------|--------|--------|
+| **Security (Critical)** | A NoSQL operator sent where a token string belongs could take over an account | None here — **but audit your own controllers** (§1) |
+| **Security** | The legacy password-reset token now expires (default 60 min); it never did | Low — unredeemed old links stop working (§2) |
+| **Bugfix (critical path)** | The reset mail can finally contain a token, and a validated link | **Required** if you send that mail yourself (§3) |
+| **Changed** | `redirectTo` from the caller outranks the framework default | None — unless you relied on the default (§4) |
+| **Changed** | Both reset flows resolve the app URL identically | None — the IAM flow gains behaviours it lacked (§4) |
+| **Changed** | IAM error messages carry nest-server's `#LTNS_XXXX:` code | None — unless you match on the English text (§5) |
+| **Bugfix** | The production SMTP default could not send mail at all | **Required** — the fix lives in *your* `config.env.ts` (§6) |
+| **Security** | SMTP now requires STARTTLS instead of accepting a downgrade | Low — one env var if your relay cannot do TLS (§6) |
+| **Changed** | The verification link carries `&email=` so a resend button can render | None (§7) |
+| **Bugfix** | A `Set-Cookie` clear on an IAM failure path was being dropped | None (§8) |
+| **New** | Partial index on `passwordResetToken` | None — created at boot (§9) |
+
+Nothing here changes the API surface of `CoreModule.forRoot()`.
+
+**This is a MINOR, and it contains breaking changes.** In this package the MAJOR digit states which
+NestJS major is targeted and moves only when NestJS does, so a breaking change ships as a minor. Two
+things can stop working for an existing deployment: unredeemed password-reset links (§2) and SMTP
+against a relay that offers no STARTTLS (§6).
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run build
+pnpm test
+```
+
+Then do three things, in this order of consequence:
+
+1. **§6 — edit your own `config.env.ts`.** The SMTP fix does not arrive with the package. Without
+   this edit a production deployment on the default port sends **no mail at all**, silently.
+2. **§3 — switch your `sendPasswordResetMail()` to the two new methods**, if you send that mail
+   yourself. Anything still reading `user.passwordResetToken` off a `process()` result is mailing
+   the word `undefined` today.
+3. **§1 — grep your controllers** for `@Body('x') x: string` / `@Query('x') x: string` whose value
+   reaches a database query.
+
+---
+
+## 1. Security: an operator where a string belongs
+
+`POST /users/password/reset` accepted a JSON **object** in place of the token string:
+
+```jsonc
+{ "token": { "$ne": null }, "password": "…" }
+```
+
+`findOne({ passwordResetToken: { $ne: null } })` then selected the first user holding *any* live
+reset token and set that account's password. The attacker never saw the mail. Confirmed against the
+live route, not inferred: the victim's token was consumed and their password hash changed.
+
+**Why nothing caught it.** A parameter declared `@Body('token') token: string` has
+`metatype === String`, and `MapAndValidatePipe` returns basic-type values verbatim — the declared
+type is erased at runtime, so nothing validates it. Express parses query strings with `qs` in
+extended mode, so `?token[$ne]=` reaches a `@Query('token') token: string` identically.
+
+This is **pre-existing**, not introduced by 11.38.0. The framework's five affected sinks are now
+guarded.
+
+### What you must do
+
+**The structural answer is not the guard — it is the DTO.** A parameter typed as a class is
+validated by the pipe; a basic-type parameter is not:
+
+```typescript
+// Exposed: metatype is String, the pipe returns whatever arrived
+async resetPassword(@Body('token') token: string) { … }
+
+// Safe: metatype is a class, the pipe validates, an object is rejected before your code runs
+async resetPassword(@Body() input: ResetPasswordInput) { … }   // token: @IsString()
+```
+
+For an existing signature you do not want to change, `isQueryableString` is exported:
+
+```typescript
+import { isQueryableString } from '@lenne.tech/nest-server';
+
+if (!isQueryableString(token)) {
+  throw new NotFoundException(ErrorCode.LINK_INVALID_OR_EXPIRED);
+}
+```
+
+Guard in the **service**, not the controller, if anything other than HTTP reaches it — an MCP tool
+or a cron job calling the service directly bypasses a controller-level check.
+
+**Deliberately NOT done:** `mongoose.set('sanitizeFilter', true)` globally. It wraps every
+object-valued filter in `$eq`, which breaks the framework's own operator-bearing queries unless each
+is wrapped in `mongoose.trusted()`. That is a fleet-wide audit, not a fix.
+
+---
+
+## 2. Security: the legacy password-reset token now expires
+
+It never did. `resetPassword()` looked the token up by value and compared no time at all — while the
+exception it threw read `Invalid or expired password reset token`, claiming a check that did not
+exist.
+
+A reset link takes over an **existing** account, which makes it the most powerful token this
+framework mints. Unbounded, it means a mail in an archive, a forwarded message or a restored backup
+opens that account years later. The IAM half already expired after an hour; only the legacy half had
+nothing.
+
+```typescript
+auth: {
+  passwordReset: { tokenExpiresInMinutes: 60 },   // the default; 0 disables expiry entirely
+},
+```
+
+| Value | Meaning |
+|-------|---------|
+| unset | 60 minutes |
+| a positive number | that many minutes |
+| `0` | no expiry — restores the previous behaviour |
+| negative, `NaN`, empty, non-numeric | **60 minutes**, not "unbounded" |
+
+That last row is deliberate. Switching off the expiry of an account-takeover credential is a decision
+somebody has to state; a typo must never be the thing that states it. (`Number('')` is `0`, so an
+empty variable would otherwise read as a deliberate opt-out.)
+
+An expired token is answered exactly like an unknown one — **404**, same message — and deleted on
+sight. Distinguishing them would confirm to somebody holding a stale token that it was once real.
+
+### Are you affected?
+
+| Situation | Effect |
+|-----------|--------|
+| A user holds an unredeemed reset mail from before the upgrade | It stops working. They request a new one — which, for most projects, is the first link that actually works (§3) |
+| Your tests write a `passwordResetToken` directly into the database | **Set `passwordResetTokenExpiresAt` too**, or they now get 404 |
+| You need the old behaviour | `tokenExpiresInMinutes: 0` |
+
+`CoreUserModel` gains `passwordResetTokenExpiresAt`, `@Restricted(S_NO_ONE)` like the token itself.
+
+### The mail now states the deadline
+
+An expiry the recipient is not told about is no better than a broken link — both arrive, look right,
+and fail on click. All three shipped templates state it, from a new optional `templateData` field:
+
+```typescript
+templateData: { link, linkExpiresInMinutes: 60, name }   // omit it, or pass 0, and no sentence renders
+```
+
+Take the value from the flow you are in: `auth.passwordReset.tokenExpiresInMinutes` for legacy,
+Better-Auth's `resetPasswordTokenExpiresIn` (seconds) for IAM. They expire independently, and
+announcing the other one's deadline is worse than announcing none.
+
+---
+
+## 3. Bugfix: the reset mail can finally carry a token and a working link
+
+Two production incidents, one after the other, both reaching real recipients.
+
+**The token was never in the link.** `setPasswordResetTokenForEmail()` returns the user through
+`process()`, and the security interceptor strips `passwordResetToken` there — correctly: a reset
+token in a response body is one in a log, a proxy cache and a browser history. So the method named
+after setting the token could not hand it over, and callers mailed `undefined`.
+
+**The base was never validated.** `email.passwordResetLink` had no default and callers concatenated
+it anyway, so a project that never set it mailed `undefined/<token>`.
+
+Every test stayed green both times, because each checked a piece: the config spec asserted the base,
+the story test read the token from the *database*, the enumeration spec asserted status and timing.
+Nothing asserted the one value the recipient actually receives.
+
+### What you must do
+
+```typescript
+async sendPasswordResetMail(email: string, serviceOptions?: ServiceOptions): Promise<null | User> {
+  // NOT setPasswordResetTokenForEmail — that one cannot return the token, by design.
+  const created = await this.createPasswordResetToken(email, serviceOptions);
+  if (!created) {
+    return null;   // unknown address — answer exactly as for a known one
+  }
+
+  const link = this.buildPasswordResetLink(created.token);
+  if (!link) {
+    // Sending a mail whose link cannot work is worse than sending none.
+    this.userServiceLogger.error('Password reset mail not sent: set `email.passwordResetLink` or `appUrl`.');
+    return created.user;
+  }
+
+  // NOT awaited: awaiting it makes the known path visibly slower whatever the status code says.
+  void this.emailService.sendMail(created.user.email, 'Password reset', {
+    htmlTemplate: 'password-reset',
+    templateData: { link, linkExpiresInMinutes: this.passwordResetTokenExpiryMinutes(), name: created.user.username },
+  }).catch((error: unknown) => this.userServiceLogger.error(`Failed to send: ${String(error)}`));
+
+  return created.user;
+}
+```
+
+The reference implementation is `src/server/modules/user/user.service.ts`; copy that shape.
+
+### Two link conventions, and which applies depends on whether you set the option at all
+
+| `email.passwordResetLink` | Resulting link |
+|---------------------------|----------------|
+| not set | `<appUrl>/auth/reset-password?token=<token>` |
+| set, containing `{token}` | your value, placeholder substituted |
+| set, **without** `{token}` | your value + `/<token>` as a **path segment** |
+
+Writing the default out by hand therefore gives a **different** link than leaving the line out. That
+looks like a trap and is kept deliberately: a project that configures such a value has a page built
+for a path segment, and moving it silently would break the very flow this release repairs. The unset
+default instead matches the page `nuxt-base-starter` ships, which reads `route.query.token`.
+
+Because the rule is not guessable, **the framework warns once at boot** when the option is set
+without `{token}`. The warning names a precondition: `{token}` is substituted by
+`buildPasswordResetLink()` and nothing else, so a caller still concatenating by hand must switch
+first or it mails the placeholder verbatim.
+
+---
+
+## 4. Changed: `redirectTo` wins, and both flows resolve the app URL identically
+
+**Your own `redirectTo` now outranks the framework default.** If the client passed one to
+`requestPasswordReset` — `nuxt-base-starter` does on every request — the mail links there.
+Resolution order: explicit config → the caller's `redirectTo` → `<appUrl>/auth/reset-password` →
+Better-Auth's own link. `passwordResetLink: false` still wins over a `redirectTo`.
+
+This matters for a project that renamed its reset route: before, the mail carried the framework's
+guess and the recipient landed on a route that does not exist. It also restores exact equivalence
+with Better-Auth's redirect hop, which sends the user to `redirectTo?token=`.
+
+**On safety:** `redirectTo` arrives in the body of an unauthenticated endpoint, so putting it into a
+mail would be a token-exfiltration vector — were it not validated first. Better-Auth runs
+`originCheck` on it at request time, so a value outside your `trustedOrigins` is rejected before any
+mail is built. That makes `trustedOrigins` load-bearing for this path as well as for CORS; keep
+`cors.allowedOrigins` as narrow as your frontends need.
+
+**Both flows now resolve the app URL through one function.** The IAM flow previously read `appUrl`
+straight off the configuration while the legacy flow had been moved to the shared resolver — two
+hand-maintained copies of one decision, and they drifted. The IAM flow gains three behaviours it
+lacked: the localhost default that `local`/`ci`/`e2e` depend on (none of them set `appUrl`),
+derivation from a host-split `baseUrl` such as `https://api.crm.localhost`, and the
+`cors.deriveAppUrl` opt-out that keeps a reset token out of an untrusted apex domain.
+
+In practice this changes the IAM link only where `appUrl` is unset — local and CI. Production, where
+it is set, is unaffected.
+
+---
+
+## 5. Changed: IAM error messages carry nest-server's error code
+
+Better-Auth answers with its own vocabulary — `{ code: 'INVALID_TOKEN', message: 'Invalid token' }` —
+while the frontends in this stack translate by parsing nest-server's marker. The parser found no
+code and passed the raw string through, so **every** IAM error reached end users as English
+developer text. It was felt hardest where it could least be afforded: an expired reset link answers
+`INVALID_TOKEN`, so the person who already cannot sign in was the one reading it.
+
+```jsonc
+// before
+{ "code": "INVALID_TOKEN", "message": "Invalid token" }
+// after
+{ "code": "INVALID_TOKEN", "message": "#LTNS_0027: Link is invalid or expired" }
+```
+
+**The `code` field is unchanged**, so anything branching on it keeps working.
+
+New codes: `LTNS_0027 LINK_INVALID_OR_EXPIRED`, `LTNS_0028 PASSWORD_TOO_LONG`,
+`LTNS_0029 PASSWORD_TOO_SHORT`.
+
+Three deliberate absences, each for a reason worth knowing:
+
+- **`INVALID_TOKEN` and `TOKEN_EXPIRED` map to the same message.** Better-Auth throws
+  `TOKEN_EXPIRED` in exactly one place — an expired verification *link*, one line above the
+  `INVALID_TOKEN` it throws for a broken one. Same user action, so the same instruction. The
+  session-oriented "sign in again" would be a dead end there: at that moment the user is usually not
+  signed in at all.
+- **`USER_NOT_FOUND` is left untranslated.** It is an account-enumeration signal. Better-Auth already
+  exposes it as a `code`, but translating it would make the oracle friendlier and more legible — the
+  opposite direction from the rest of this release.
+- **`SESSION_EXPIRED` is left untranslated.** It means "re-authenticate for this action", which is
+  not what nest-server's `TOKEN_EXPIRED` tells the user to do.
+
+Reachable programmatically via `mapBetterAuthErrorCode(code)`.
+
+### Two boundaries
+
+- **A redirect is not rewritten.** Better-Auth reports some failures by redirecting to your
+  `callbackURL` with `?error=<CODE>` rather than answering with a body — nothing to translate, and
+  rewriting that query string would invent a second contract over its documented one. Read `?error=`
+  in the frontend. Narrower than it sounds: with `betterAuth.emailVerification.callbackURL` set —
+  which the starter does — the mail links straight at the frontend and the redirect route is never
+  walked.
+- **`PASSWORD_TOO_SHORT` / `PASSWORD_TOO_LONG` are rarely reachable through the lt frontend**, which
+  hashes with `ltSha256` before sending, so every password arrives as 64 hex characters. They remain
+  reachable for a client that does not hash, and for a project configuring `minPasswordLength` above
+  64.
+
+### Are you affected?
+
+| Situation | Effect |
+|-----------|--------|
+| You use `@lenne.tech/nuxt-extensions` | Errors become translatable; no change needed |
+| You branch on `error.code` | Unaffected |
+| You match on the exact English `message` string | **Update it** — prefer `code`, which is stable |
+
+---
+
+## 6. Bugfix: the production SMTP default could not send mail
+
+The `production` profile paired the default port **587** with `secure` resolving to **true**. Those
+two cannot go together: `secure` means implicit TLS, which only port **465** speaks, while 587 opens
+in plaintext and upgrades through STARTTLS. Nodemailer sent a TLS ClientHello to a server answering
+with an SMTP greeting, and OpenSSL reported `wrong version number`.
+
+A deployment configuring only `SMTP_HOST` and credentials could therefore send **no mail at all** —
+invisibly, because authentication mail is deliberately not awaited, so the failure never reached a
+response. The API answered 200 while every password-reset message died in transport.
+
+### This does NOT arrive with `pnpm update`
+
+The fix landed in the framework's own `src/config.env.ts`; your project has its own copy, seeded from
+the starter at init and never re-synced. Upgrading gives you a boot warning — the repair is an edit
+you make:
+
+```typescript
+import { resolveSmtpSecure } from '@lenne.tech/nest-server';
+
+const smtpPort = parseInt(process.env.SMTP_PORT || '587', 10);
+// …
+smtp: {
+  host: process.env.SMTP_HOST,
+  port: smtpPort,
+- secure: process.env.SMTP_SECURE !== 'false',
++ secure: resolveSmtpSecure(process.env.SMTP_SECURE, smtpPort),
++ requireTLS: process.env.SMTP_REQUIRE_TLS !== 'false',
+},
+```
+
+| `SMTP_SECURE` | Result |
+|---------------|--------|
+| `true` / `false` | honoured, even where it cannot work — and warned about |
+| unset, or anything else (`1`, `yes`, a typo) | derived: `true` on port 465, `false` otherwise |
+
+Only the two canonical values override, because `secure` is not an independent setting but a
+consequence of the port. Both obvious string rules have a silent wrong side — `!== 'false'` makes an
+unknown value `true` on 587 (this outage), `=== 'true'` makes `1` resolve to `false` on 465 (the same
+outage mirrored). Deferring to the port is the only rule under which no input produces a pair that
+cannot connect.
+
+### `requireTLS` is the second half, and it is new
+
+`secure: false` alone means **opportunistic** STARTTLS: nodemailer upgrades only when the server
+advertises it. An on-path attacker who strips that capability line gets a plaintext session carrying
+your SMTP credentials and a working password-reset link. Before the repair nothing was sent at all,
+so this exposure is created by the fix — which is why the fix has to include the floor.
+
+Set `SMTP_REQUIRE_TLS=false` only for an internal relay that genuinely offers no STARTTLS.
+`EmailService` warns once when the resolved pair cannot connect — reported, never overruled.
+
+---
+
+## 7. Changed: the verification link carries the address
+
+`{callbackURL}?token=<token>&email=<address>`. The verification page needs it to offer "send a new
+email" once the token has expired, and it cannot recover the address itself: that value lives inside
+the token's JWT payload, and reading it there would mean rendering data from an unverified
+signature. Without it, a user with an expired link is told correctly what happened and given no way
+to fix it.
+
+---
+
+## 8. Bugfix: a `Set-Cookie` clear was being dropped
+
+The header rebuild in the new error wrapper used `Headers.forEach` + `set()`. `forEach` yields each
+`set-cookie` entry separately and `set()` overwrites, so all but the last were discarded. Better-Auth
+**clears** session and 2FA cookies on several failure paths — precisely the responses being rewritten
+— so the clear was lost and a stale credential stayed in the browser.
+
+No action required. Noted because a failed 2FA attempt against an 11.39.0 pre-release could have left
+a session cookie behind.
+
+---
+
+## 9. New: partial index on `passwordResetToken`
+
+`findOne({ passwordResetToken: token })` runs on an unauthenticated, unrated endpoint and had no
+index — a full collection scan of `users` per call. The index is partial
+(`partialFilterExpression: { passwordResetToken: { $type: 'string' } }`) and the reset path now
+`$unset`s the field rather than writing `null`, so it stays small.
+
+**Never give `passwordResetTokenExpiresAt` a TTL index.** It is a `Date`, and a TTL index there would
+delete the **user document**, not the token.
+
+---
+
+## 10. Operations: two boot warnings you may now see
+
+**`jwks` under a throwaway or fallback secret.** The JWT plugin persists a `jwks` document encrypted
+with whatever secret is active. Booting once without a permanent `betterAuth.secret` — or on the
+`jwt.secret` fallback — leaves a row that a later, different secret cannot decrypt. Nothing fails at
+the time; `/iam/token` starts answering `Failed to decrypt private key` whenever somebody next asks
+for a JWT, which on a low-traffic deployment can be months later. Observed in production with five
+weeks between cause and symptom.
+
+Remedy: reuse the same value, or drop the `jwks` collection after setting a permanent secret.
+Better-Auth creates a new key; previously issued JWTs were already unusable.
+
+---
+
+## 11. Vendor mode: one new file
+
+| New file | Existing core files that now import it |
+|---|---|
+| `better-auth/core-better-auth-error-codes.helper.ts` | `better-auth/core-better-auth-api.middleware.ts`, `better-auth/index.ts` |
+
+Taking the middleware without the helper leaves an unresolvable import.
+
+---
+
+## 12. Dependencies: two security overrides raised
+
+`fast-uri` and `qs` were already overridden, and both entries had **aged past their own patch line**.
+A stale override is not inert — it pins matching paths *below* the current fix, and adding a second,
+higher entry does not help because the narrower key claims its paths first and the tree ends up
+carrying both versions.
+
+Raised in place: `'fast-uri@<3.1.6': '3.1.6'` and `'qs@<6.16.0': '6.16.0'`. `pnpm audit` is clean.
+
+If you maintain your own overrides, the tell is: **`pnpm audit` reporting a package you already
+override is never "transitive, pre-existing, not our problem"** — it means the entry is the cause.
+See `.claude/rules/package-management.md` for both aging modes.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| The reset mail link ends in `/undefined` | §3 — the token was read off a `process()` result, where the interceptor strips it | `createPasswordResetToken()`, read `created.token` |
+| The reset mail link STARTS with `undefined/` | §3 — `email.passwordResetLink` unset and the caller concatenated anyway | `buildPasswordResetLink()`, which returns `null` instead of guessing |
+| The reset page reports an invalid token, but the URL looks fine | §3 — the link carries a path segment and the page reads `?token=`, or the reverse | Configure `email.passwordResetLink` with `{token}` where your page expects it |
+| A reset link that worked yesterday now 404s | §2 — tokens expire after 60 minutes | Request a new one, or `tokenExpiresInMinutes: 0` |
+| `POST /users/password/reset` answers 404 for a token that exists | §1 — the value was not a plain string, or §2 — it expired | Both answer identically on purpose |
+| Production sends no mail and the log shows `wrong version number` | §6 — port 587 with `secure: true` | Apply the `config.env.ts` edit |
+| Production sends no mail and the log mentions STARTTLS | §6 — `requireTLS` and a relay that offers none | `SMTP_REQUIRE_TLS=false`, after confirming the relay really cannot |
+| `/iam/token` fails with `Failed to decrypt private key` | §10 — a `jwks` key encrypted under a different secret | Drop the `jwks` collection after setting a permanent secret |
+| Your tests get 404 on a reset token they wrote directly | §2 — the row has no `passwordResetTokenExpiresAt` and counts as expired | Set it in the fixture |
+
+---
+
+## Module Documentation
+
+- [BetterAuth README](../src/core/modules/better-auth/README.md)
+- [BetterAuth Integration Checklist](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- [Request Lifecycle](../docs/REQUEST-LIFECYCLE.md)
+- [Configurable Features](../.claude/rules/configurable-features.md)

package/package.json

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

@@ -3,7 +3,7 @@ import * as dotenv from 'dotenv';
 import { join } from 'path';
 
 import { RoleEnum } from './core/common/enums/role.enum';
-import { getEnvironmentConfig } from './core/common/helpers/config.helper';
+import { getEnvironmentConfig, resolveSmtpSecure } from './core/common/helpers/config.helper';
 import { IServerOptions } from './core/common/interfaces/server-options.interface';
 
 /**
@@ -22,6 +22,16 @@ import { IServerOptions } from './core/common/interfaces/server-options.interfac
 // misconfiguration still surface.
 dotenv.config({ quiet: true });
 
+/**
+ * Resolved once so the TLS flag can be derived from the very port that will be used.
+ *
+ * `secure` means implicit TLS, which only port 465 speaks; 587 upgrades via STARTTLS and needs
+ * `secure: false`. This profile used to hard-default `secure` to true alongside port 587 — a pair
+ * that cannot connect, and which killed every outgoing mail in a default production deployment
+ * while the API still answered 200. See `resolveSmtpSecure()` for the full account.
+ */
+const productionSmtpPort = parseInt(process.env.SMTP_PORT || '587', 10);
+
 const config: { [env: string]: IServerOptions } = {
   // ===========================================================================
   // CI environment
@@ -520,6 +530,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 +667,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,
@@ -704,8 +722,14 @@ const config: { [env: string]: IServerOptions } = {
           user: process.env.SMTP_USER,
         },
         host: process.env.SMTP_HOST,
-        port: parseInt(process.env.SMTP_PORT || '587', 10),
-        secure: process.env.SMTP_SECURE !== 'false',
+        port: productionSmtpPort,
+        // Refuse to send rather than send in the clear. `secure: false` means STARTTLS, and
+        // nodemailer upgrades only when the server ADVERTISES it — an on-path attacker who strips
+        // that capability line gets the SMTP credentials and a working password-reset link in
+        // plaintext, silently. Repairing the transport without pinning it would have shipped that.
+        // Inert on 465, where the connection is already TLS from the first byte.
+        requireTLS: process.env.SMTP_REQUIRE_TLS !== 'false',
+        secure: resolveSmtpSecure(process.env.SMTP_SECURE, productionSmtpPort),
       },
     },
     env: 'production',

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

@@ -194,3 +194,82 @@ export function merge(obj: Record<string, any>, ...sources: any[]): any {
     }
   });
 }
+
+/**
+ * Resolve nodemailer's `smtp.secure` flag, deriving it from the port when it was not set.
+ *
+ * ── The defect this exists for ─────────────────────────────────────────────────
+ * `secure` does not mean "use encryption". It means "start the TLS handshake IMMEDIATELY, before
+ * any SMTP conversation" — implicit TLS, which only port **465** speaks. Port 587 is the
+ * submission port: the session opens in plaintext and is upgraded via STARTTLS, which nodemailer
+ * does on its own with `secure: false`.
+ *
+ * Pairing the common default port 587 with `secure: true` therefore cannot work. Nodemailer sends
+ * a TLS ClientHello, the server answers with an SMTP greeting, and OpenSSL reports
+ * `wrong version number`. This framework's `production` profile shipped exactly that pairing —
+ * port 587 by default, `secure` true unless explicitly disabled — so a deployment that configured
+ * nothing beyond host and credentials could not send ANY mail.
+ *
+ * It stayed invisible because authentication mail is deliberately fire-and-forget: the send is not
+ * awaited (it would leak whether an address exists), so the failure never reached a response. The
+ * API answered 200, the operator saw success, and every password-reset mail died in transport with
+ * only a log line. Found in production, not by a test.
+ *
+ * ── Why ONLY the two canonical values override ─────────────────────────────────
+ * `secure` is not an independent setting. It is a CONSEQUENCE of the port: 465 negotiates TLS
+ * immediately, everything else upgrades through STARTTLS. Letting the two be configured
+ * independently is precisely what allowed the broken pairing to exist.
+ *
+ * Both obvious string rules have a silent wrong side:
+ *
+ *   `value !== 'false'`  — an unset or unknown value yields TRUE, paired with 587. The reported
+ *                          outage.
+ *   `value === 'true'`   — `1` or `yes` yields FALSE. On port 465 that is a plaintext handshake
+ *                          against a TLS-only port: the same outage, mirrored.
+ *
+ * So only `'true'` and `'false'` override. Anything else — `1`, `yes`, a typo — falls back to the
+ * port, which is the fact rather than a guess. No input value can produce a pair that cannot
+ * connect, which is a stronger property than either rule had.
+ *
+ * The one behaviour change for a value that IS set: a non-canonical value on a non-465 port now
+ * resolves to `false` where it used to be `true`. Every such combination was broken, so this fixes
+ * rather than regresses — and `SMTP_SECURE=1` on 465, the case worth protecting, still resolves to
+ * `true` via the port.
+ *
+ * An explicit `'true'` on 587 (or `'false'` on 465) is still honoured and still impossible; that is
+ * deliberate, and `warnOnImpossibleSmtpTlsCombination()` reports it rather than overruling it.
+ *
+ * @param value - the raw `SMTP_SECURE` environment value, if any
+ * @param port  - the resolved SMTP port
+ * @returns whether nodemailer should open the connection with implicit TLS
+ */
+export function resolveSmtpSecure(value: string | undefined, port: number): boolean {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : undefined;
+
+  if (normalized === 'true') {
+    return true;
+  }
+  if (normalized === 'false') {
+    return false;
+  }
+
+  // Unset or non-canonical: 465 is the only port that speaks implicit TLS.
+  return port === 465;
+}
+
+/**
+ * Whether an SMTP port/TLS pair describes a connection that cannot succeed.
+ *
+ * `secure: true` off port 465 is the fatal one — a TLS handshake against a plaintext greeting.
+ * `secure: false` ON 465 is its mirror and equally broken, just rarer.
+ *
+ * Reported rather than corrected: a deployment may legitimately run submission on a non-standard
+ * port, and silently overriding an explicit setting is how the original defect became invisible in
+ * the first place.
+ */
+export function isImpossibleSmtpTlsCombination(port: number, secure: boolean): boolean {
+  if (!Number.isFinite(port)) {
+    return false;
+  }
+  return secure ? port !== 465 : port === 465;
+}

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

@@ -577,3 +577,41 @@ export function buildCorsConfig(options: Partial<IServerOptions>): Record<string
   // No origins resolvable → return empty (secure default — no open CORS with credentials)
   return {};
 }
+
+/**
+ * The app URL as every mail-link builder in this package must resolve it.
+ *
+ * ── Why this exists rather than four inline reads ──────────────────────────────
+ * Two classes build a password-reset link — `CoreUserService.buildPasswordResetLink()` for the
+ * legacy flow and `CoreBetterAuthEmailVerificationService.buildPasswordResetUrl()` for IAM — and a
+ * third builds the verification link. They are near-identical by construction and were maintained
+ * by hand, which is exactly how they drifted: one was fixed to resolve through `resolveServerUrls`
+ * while the others kept reading `appUrl` straight off the configuration.
+ *
+ * A raw read is wrong in three situations that all look fine locally:
+ *
+ * - `local` / `ci` / `e2e` do not set `appUrl` — their localhost default lives inside
+ *   `resolveServerUrls`, so a raw read yields nothing and the builder falls back or returns null.
+ * - A host-split `baseUrl` such as `https://api.crm.localhost` (what `lt dev up` serves) carries
+ *   the app origin one label away; a raw read cannot see it.
+ * - `cors.deriveAppUrl: false` is how a deployment states that the apex domain is NOT its own —
+ *   the documented case being a third-party-hosted marketing site. Deriving anyway puts a
+ *   password-reset token into that origin's access log.
+ *
+ * The third point is why this is a shared function rather than a convention: it is a security
+ * decision, and a security decision repeated by hand in three places is one that will eventually
+ * be made differently in one of them.
+ *
+ * @param configService - anything exposing the frozen-config reader
+ * @returns the resolved app URL, or `undefined` when nothing can be resolved — never a guess
+ */
+export function resolveAppUrlFromConfig(configService: {
+  getFastButReadOnly<T = any>(key: string, defaultValue?: any): T;
+}): string | undefined {
+  return resolveServerUrls({
+    appUrl: configService.getFastButReadOnly<string>('appUrl'),
+    baseUrl: configService.getFastButReadOnly<string>('baseUrl'),
+    deriveAppUrl: configService.getFastButReadOnly<boolean>('cors.deriveAppUrl'),
+    env: configService.getFastButReadOnly<string>('env'),
+  }).appUrl;
+}