@lenne.tech/nest-server 11.38.0 → 11.40.0

package/docs/REQUEST-LIFECYCLE.md

@@ -608,6 +608,20 @@ If authentication succeeds, `req.user` is set with the authenticated user (inclu
 > 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`.
 
+> **Response side, since 11.38.0 — `wrapBetterAuthErrorResponse()`.** The mirror image of the note
+> above. Immediately after `authInstance.handler()` returns, every **failed** response passes
+> through a single choke point that rewrites its `message` to carry nest-server's `#LTNS_XXXX:`
+> marker, so frontends can translate it instead of showing Better-Auth's English. The `code` field
+> is left untouched, successful responses are returned **by identity** (the body is a single-read
+> stream, so rebuilding one would break every later branch), and 3xx is skipped — Better-Auth
+> reports some failures by redirecting with `?error=<CODE>`, and rewriting that query string would
+> invent a second contract over its documented one.
+>
+> It sits at ONE point on purpose: every branch below it acts only on `response.ok`, so all error
+> exits inherit the rewrite without any of them being touched. A subclass overriding the middleware
+> must know the counterpart of the rule above — the response body it forwards is no longer
+> byte-identical to the one Better-Auth produced.
+
 #### 2b. SecurityHeadersMiddleware
 
 Sets the browser security headers on **every** response — `X-Content-Type-Options`,

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

@@ -181,6 +181,21 @@ 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.
 
+### On an IAM-only deployment, "both stores" means one store
+
+The mirror into the legacy bcrypt column runs only where a legacy surface exists — gated on the same
+`auth.legacyEndpoints` resolver the endpoints themselves use. That is deliberate: on an IAM-only
+deployment nothing ever reads that column.
+
+The visible effect surprises people: after an IAM reset, `users.password` still holds the OLD hash.
+It is inert — sign-in goes through IAM — but a database inspection shows two different passwords on
+one account and looks like the bug this release fixes.
+
+**The part that is not inert:** if you later switch legacy endpoints back on (§1), every account that
+reset while they were off becomes reachable with its **pre-reset** password — including any account
+reset *because* the old password leaked. Before enabling `auth.legacyEndpoints` on a deployment that
+has been IAM-only, force a password change for affected users or clear the stale `password` field.
+
 ---
 
 ## 3. Bugfix: native IAM reset routes normalize the password
@@ -372,7 +387,9 @@ The reference implementation is `src/server/modules/user/user.service.ts`; copy
 Two things to check:
 
 1. **The return type widened to `null | TUser`.** If you override
-   `setPasswordResetTokenForEmail()` or call it directly, handle `null`.
+   `setPasswordResetTokenForEmail()` or call it directly, handle `null`. **If your endpoint returned
+   `!!user`, it now answers `false` for an unknown address and `true` for a known one** — the same
+   oracle, one layer up, reintroduced by this very fix. Return a constant instead.
 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`).

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)