@lenne.tech/nest-server 11.38.0 → 11.40.0

package/migration-guides/11.39.0-to-11.40.0.md

@@ -0,0 +1,186 @@
+# Migration Guide: 11.39.0 → 11.40.0
+
+> **Why a MINOR for what looks like a patch.** In this package the MAJOR digit tracks the NestJS
+> major (11.x = NestJS 11), so it is not ours to spend — and every breaking change of our own ships
+> as a MINOR instead. This release contains one: a security control that was silently inert starts
+> being enforced, and a deployment that relied on the inert behaviour can stop working. The number
+> of affected projects is small; the rule does not ask how many, it asks whether a working
+> deployment can break.
+
+## Overview
+
+| Category | Effort | Applies to |
+|----------|--------|-----------|
+| **Breaking (behaviour)** | 5 minutes | Projects that set `ai.allowedBaseUrlHosts` **as a string** (i.e. via `NSC__AI__ALLOWED_BASE_URL_HOSTS`) |
+| Bugfix | none | Everyone using the AI module |
+| Internal tooling | none | Nobody — `scripts/` does not ship |
+
+Almost every project can update with `pnpm update @lenne.tech/nest-server` and read no further.
+**One group cannot**, and for them the change is the uncomfortable kind: a security control that was
+silently inert starts working, and a working deployment can stop working as a result.
+
+## Quick Migration
+
+```bash
+# Does this affect you? If both come back empty, you are done.
+grep -r "NSC__AI__ALLOWED_BASE_URL_HOSTS" . --include="*.env*" --include="*.yml" --include="*.yaml" 2>/dev/null
+grep -rn "allowedBaseUrlHosts" src/ 2>/dev/null
+```
+
+## Breaking Change: `ai.allowedBaseUrlHosts` set as a string was never enforced
+
+### What was wrong
+
+`ai.allowedBaseUrlHosts` is the SSRF egress allowlist for AI connection base URLs. It is reachable
+through the framework's own environment mapping:
+
+```bash
+NSC__AI__ALLOWED_BASE_URL_HOSTS=llm.example.com,api.openai.com
+```
+
+`getEnvironmentObject()` turns that into `{ ai: { allowedBaseUrlHosts: '<string>' } }`, and lodash
+`merge` assigns the scalar straight over the configured array.
+
+**And there is no way to avoid that from the environment.** The `NSC__*` reader coerces exactly
+three things — `'true'`, `'false'`, and anything `Number()` accepts — and leaves everything else a
+string. No CSV, JSON array literal or other notation produces an array:
+
+```bash
+NSC__AI__ALLOWED_BASE_URL_HOSTS='["a.example.com"]'   # -> the string '["a.example.com"]'
+NSC__AI__MAX_ITERATIONS=7                             # -> the number 7
+```
+
+So this is not an edge case for people who happened to pick the wrong notation. **If you configured
+the allowlist through the environment at all, it was off — completely, on every deployment, for its
+whole life.** Verified empirically against the built `config.helper.js`, not inferred from the code.
+Reported by the nest-server-starter session, which went looking for why a string arrives in the
+first place.
+
+That gives you a clean dividing line, and it is the only thing you need to check:
+
+| How you set `ai.allowedBaseUrlHosts` | Were you affected? |
+|---|---|
+| `NSC__AI__ALLOWED_BASE_URL_HOSTS` (or any env route) | **Yes — the control was inert** |
+| A real array in `config.env.ts` | No — it worked as documented |
+| Not set at all | No — no restriction was intended |
+
+The guard then did:
+
+```typescript
+if (!Array.isArray(allowedHosts) || !allowedHosts.length) {
+  return;   // read as "no allowlist configured"
+}
+```
+
+So a string was read as **"not configured"** and the check was skipped entirely — no log line, no
+error. An operator who used the canonical `NSC__` spelling (the documented form for every other
+setting) had **no egress restriction at all** while believing the control was on.
+
+### What changes in 11.40.0
+
+A string is now parsed as a comma-separated list, so the setting does what it says.
+
+**This is a behaviour change in the restrictive direction.** If you set it as a string, your
+deployment went from *no restriction* to *enforced*. Any AI connection whose host is not in that
+list now fails with `ServiceUnavailableException` and a WARN naming the host. There is no
+deprecation window, because leaving an SSRF control off for a release cycle is worse than the
+breakage.
+
+### Before upgrading
+
+1. Find the configured value:
+   ```bash
+   grep -r "NSC__AI__ALLOWED_BASE_URL_HOSTS" . --include="*.env*" --include="*.yml" 2>/dev/null
+   ```
+2. List every `baseUrl` your connections actually use — including any seeded via
+   `ai.defaultConnection`, and any added at runtime through `aiConnections`:
+   ```
+   query { aiConnections { name baseUrl enabled } }
+   ```
+3. Confirm every one of those hosts appears in the list. Add the missing ones, or clear the setting
+   entirely if you did not mean to restrict egress:
+   ```bash
+   NSC__AI__ALLOWED_BASE_URL_HOSTS=llm.example.com,api.openai.com,localhost:11434
+   ```
+
+**Unset is still permissive**, unchanged — a local Ollama works out of the box.
+
+### Matching rules
+
+Worth reading once, because they are the likely cause of a surprising refusal:
+
+| Entry | Matches | Does not match |
+|-------|---------|----------------|
+| `llm.example.com` | any port on that host | `llm.example.com.evil.test` |
+| `llm.internal:8080` | exactly that port | `llm.internal:9200` |
+| `example.com:443` | `https://example.com/` (default port) | `http://example.com/` |
+| `LLM.Example.com` | `https://llm.example.com/` | — |
+
+Entries and URLs are both trimmed, lowercased and stripped of a fully-qualifying trailing dot, so
+neither side can win by spelling one DNS name differently.
+
+## Bugfix: the allowlist now covers every outbound path
+
+`probeContextWindow()` (the Ollama `/api/show` probe behind `detectContextWindow()`) reached the
+network **without consulting the allowlist**. It is not an admin-only path: `CoreAiService` calls
+`detectAndPersistCapabilities()` on an ordinary user prompt whenever `contextWindow` is undefined,
+and it runs *before* the AI rate limit.
+
+All three outbound paths — chat completions, the capability probe, and the context-window probe —
+now go through the same check. A refusal there degrades to "context window unknown" and falls back
+to the built-in model table, so nothing breaks for an allowed host.
+
+**No action required**, unless you were relying on the context-window probe reaching a host your
+allowlist excludes — in which case add that host.
+
+## Bugfix: a malformed value is now reported
+
+A value that is neither a list nor a string (a number, a boolean, an object — all reachable through
+`NEST_SERVER_CONFIG`) carries no hostnames, so the allowlist cannot be applied. That was silent.
+It is now logged as an error:
+
+```
+ai.allowedBaseUrlHosts is a number and carries no hostnames — the SSRF egress allowlist is
+NOT active. Use an array or a comma-separated string.
+```
+
+The behaviour is unchanged (permissive); only the silence is gone. From the outside, "misconfigured"
+and "deliberately unset" looked identical, which is what let the original defect survive.
+
+## Not consumer-facing
+
+The rest of this release is repository tooling and does not ship: a new `check:overrides` guard for
+stale pnpm overrides and audit suppressions, a `pnpm peers check` step, audit-count accounting in
+`scripts/check.mjs`, and test-evidence work. `package.json` `files` ships `dist` plus docs, and the
+CLI's vendor transformation copies `src/core/` — neither includes `scripts/`.
+
+Four further tooling fixes landed late in the release, all in the same area and all of the same
+kind — a gate that reported safety it had not established:
+
+| Fix | What it was |
+|-----|-------------|
+| Audit hang guard (`CHECK_AUDIT_TIMEOUT`, default 600s) | `pnpm audit` emits no intermediate output, so the existing idle watchdog structurally could not tell a hang from a healthy slow run. A second, absolute cap now kills it with its own cause |
+| `'unreadable'` degradation | An audit exiting **0** with no parseable tally printed a GREEN tick and a literal `0`, having assessed nothing. Reachable in practice: a pnpm version collision writes its error to stderr and exits 0 |
+| 5xx read from the code field only | The signature matched `\b5\d\d\b` against the whole envelope, so pnpm's own `audited 503 packages` degraded a run that had to block |
+| Reachability probe asked the wrong registry | Both check scripts hardcoded `registry.npmjs.org` while pnpm audits against the **configured** registry. Behind a private registry or proxy that reproduces the very false-green the probe removes: the real registry is unreachable, npmjs.org answers, the run reports "clean" |
+| Steps list contradicted the warning | A degraded audit printed a yellow warning and "NOT CHECKED" — and a **green tick** in the Steps list, which hard-coded one per step |
+| JSONC comment stripping | A regex stripper ate glob patterns out of `tsconfig.tests.json` and `.oxlintrc.json` (2783 bytes, and one whole `overrides` entry). Both files still parsed, so the assertions above them ran green against a mutilated config |
+
+None of them changes shipped behaviour; they are recorded because each one made a **check** claim
+something it had not verified, and that is the class of defect a consumer inherits indirectly — via
+a release that passed a gate which was not looking.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| AI stopped working after the update; log shows `host "…" is not in ai.allowedBaseUrlHosts` | The allowlist is now enforced where it previously was not | Add the host, or clear the setting |
+| `ServiceUnavailableException` on one connection only | That connection's `baseUrl` host is missing from the list | Add it — check `aiConnections`, not just `defaultConnection` |
+| Error log says the allowlist is `NOT active` | The value is not a list or a string | Use an array, or a comma-separated string |
+| An entry with `:443` stopped matching an `http://` URL | `:443` is the https default, not http's | Write the host without a port, or with the right one |
+
+## Module Documentation
+
+- `src/core/modules/ai/README.md` → "Egress allowlist (`ai.allowedBaseUrlHosts`)"
+- `.claude/rules/configurable-features.md` → "AI Egress Allowlist (SSRF)"
+- `src/core/common/interfaces/server-options.interface.ts` → `IAi.allowedBaseUrlHosts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.38.0",
+  "version": "11.40.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",
@@ -25,11 +25,12 @@
     "cf": "pnpm run check:fix",
     "check": "node scripts/check.mjs",
     "check:consumer": "node scripts/check-consumer.mjs",
-    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:manifest": "node scripts/check-package-manifest.mjs",
     "check:mutations": "node scripts/check-mutations.mjs",
-    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
-    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:overrides": "node scripts/check-overrides.mjs",
+    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run check:overrides && pnpm peers check && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",
     "cnaf": "pnpm run check:naf",
     "docs": "pnpm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",

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
@@ -712,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;
+}

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

@@ -856,3 +856,40 @@ export function typeofArray(arr: any[], strict = false): string {
   }
   return type;
 }
+
+/**
+ * Whether a value is safe to use as the right-hand side of a Mongoose equality filter.
+ *
+ * ── The hole this closes ───────────────────────────────────────────────────────
+ * A controller parameter declared as `@Body('token') token: string` has
+ * `metatype === String`, and `MapAndValidatePipe` short-circuits on exactly that shape:
+ * `if (!value || typeof value !== 'object' || !metatype || isBasicType(metatype)) return value`.
+ * The declared type is erased at runtime, so nothing checks it — a JSON object reaches the
+ * service verbatim.
+ *
+ * `findOne({ passwordResetToken: token })` with `token = { $ne: null }` therefore selects the
+ * first user holding ANY live reset token, and the caller sets that person's password without
+ * ever seeing their mail. Confirmed by probe against the real route, not by reading.
+ *
+ * Express parses query strings with `qs` in extended mode, so `?token[$ne]=` produces the same
+ * object without a JSON body at all — `@Query('token') token: string` is exposed identically.
+ *
+ * `{ $ne: null }` is the takeover primitive; `null` is the quieter one, because MongoDB matches
+ * MISSING fields against `null` and selects a user who never requested anything.
+ *
+ * ── Why a guard at the sink rather than `mongoose.set('sanitizeFilter', true)` ──
+ * The global switch wraps every object-valued filter in `$eq`, which would break the framework's
+ * own operator-bearing queries (`$in`, `$ne`, `$gt` in the filter helpers) unless each is wrapped
+ * in `mongoose.trusted()`. That is a fleet-wide audit, not a fix. This guard is exact: it says
+ * "this particular value came from a client and must be a plain string".
+ *
+ * Rejects an empty string too — `findOne({ token: '' })` is never a legitimate credential lookup,
+ * and `undefined` would be stripped from the filter entirely by Mongoose, turning the query into
+ * `findOne({})` and matching the first document in the collection.
+ *
+ * @param value - the raw value as it arrived from the transport
+ * @returns whether it may be used as a filter value
+ */
+export function isQueryableString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}

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

@@ -18,7 +18,15 @@ import { clone, plainToInstanceClean, processDeep } from './input.helper';
 // Fields like refreshTokens/tempTokens are kept — they are needed for token validation
 // and process flows (password reset, email verification). The CheckSecurityInterceptor
 // removes those from HTTP responses as a separate layer.
-const SECRET_FIELD_NAMES = Object.freeze(['password', 'verificationToken', 'passwordResetToken']);
+const SECRET_FIELD_NAMES = Object.freeze([
+  'password',
+  'verificationToken',
+  'passwordResetToken',
+  // `S_NO_ONE` covers Model instances; this list is what runs on a plain-object path (`.lean()`,
+  // `aggregate`, a spread). Its sibling token has always been here — the timestamp says "a reset
+  // is pending for this account", which is exactly what the field's own JSDoc calls attacker-useful.
+  'passwordResetTokenExpiresAt',
+]);
 
 /**
  * Helper class for services

package/src/core/common/interceptors/check-security.interceptor.ts

@@ -21,6 +21,7 @@ export class CheckSecurityInterceptor implements NestInterceptor {
       'password',
       'verificationToken',
       'passwordResetToken',
+      'passwordResetTokenExpiresAt',
       'refreshTokens',
       'tempTokens',
       'apiKeyEncrypted',

package/src/core/common/interfaces/server-options.interface.ts

@@ -297,6 +297,51 @@ export interface IAuthPasswordReset {
    * ```
    */
   preventUserEnumeration?: boolean;
+
+  /**
+   * How long a LEGACY password-reset token stays valid, in minutes.
+   *
+   * **Before 11.38.0 it never expired at all.** `resetPassword()` looked the token up by value and
+   * nothing else, while the exception it threw on a miss read "Invalid or expired password reset
+   * token" — a message describing a check that did not exist. A reset link is a bearer credential
+   * for full account takeover, so an unbounded one means a mail sitting in an archive, a forwarded
+   * message or a restored backup opens the account years later.
+   *
+   * That gap became more reachable in this very release, which is why it is closed here: until now
+   * a project relying on the default mailed a link containing the word `undefined`, so the eternal
+   * token was unusable by accident. Repairing the link without adding an expiry would have turned a
+   * dead credential into a live and permanent one.
+   *
+   * The IAM flow already expires its token after one hour (Better-Auth's
+   * `resetPasswordTokenExpiresIn`), so 60 matches the half of the framework that had it right.
+   *
+   * **Value semantics — the two ends mean different things, deliberately:**
+   *
+   * | Value | Meaning |
+   * |-------|---------|
+   * | unset | 60 minutes |
+   * | a positive number | that many minutes |
+   * | `0` | **no expiry** — restores the pre-11.38.0 behaviour |
+   * | negative, `NaN`, non-numeric | 60 minutes, i.e. the safe default rather than "unbounded" |
+   *
+   * `0` opting OUT while an invalid value falls back to the DEFAULT is intentional: switching the
+   * expiry off is a decision somebody has to state, and a typo in an environment variable must
+   * never be the thing that states it.
+   *
+   * **Upgrade note:** a token minted before this release carries no expiry timestamp and is treated
+   * as expired. Anyone holding an unredeemed reset mail must request a new one — which, for every
+   * project that relied on the default link, is the first one that will actually work.
+   *
+   * @default 60
+   *
+   * @example
+   * ```typescript
+   * auth: {
+   *   passwordReset: { tokenExpiresInMinutes: 15 },
+   * }
+   * ```
+   */
+  tokenExpiresInMinutes?: number;
 }
 
 export interface IAuthLegacyEndpoints {
@@ -493,6 +538,12 @@ export interface IBetterAuthEmailVerificationConfig {
    * When not set, the verification link points directly to the backend
    * endpoint which handles verification and redirects.
    *
+   * Since 11.38.0 the generated link carries the recipient's address as well —
+   * `{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.
+   *
    * @default undefined (backend-handled verification)
    * @since 11.13.0
    */
@@ -560,9 +611,15 @@ export interface IBetterAuthEmailVerificationConfig {
    *
    * Set to `false` to keep Better-Auth's own link.
    *
+   * **Resolution order**, first hit wins: this option → the caller's `redirectTo` → `<appUrl>/auth/
+   * reset-password` → Better-Auth's own URL. `false` is a hard opt-out that a `redirectTo` does not
+   * override.
+   *
    * Note this is separate from `email.passwordResetLink`, which serves the LEGACY
-   * `/users/password/reset-request` flow and appends the token as a path segment. Two flows, two
-   * conventions; a project using both should point them at the same page.
+   * `/users/password/reset-request` flow. Both DEFAULTS point at the same page with `?token=`; what
+   * still differs is the fallback for a configured value without a placeholder — `?token=` here, a
+   * path segment there. A project using both should point them at the same page, and writing
+   * `{token}` in both makes them identical.
    *
    * @default `<appUrl>/auth/reset-password?token={token}`
    * @since 11.38.0
@@ -1655,9 +1712,25 @@ export interface IAi {
    * bare `hostname`); unset → permissive (so local providers like Ollama on localhost
    * work out of the box). `baseUrl` is admin-only, so this guards a compromised or
    * misconfigured admin, not end-user input.
+   *
+   * Accepts an array OR a comma-separated string. The string form is not a convenience:
+   * it is the shape the framework's own env mapping produces. `NSC__AI__ALLOWED_BASE_URL_HOSTS`
+   * becomes `{ ai: { allowedBaseUrlHosts: '<string>' } }`, and lodash `merge` assigns that
+   * scalar straight over a configured array — so the canonical `NSC__` spelling MUST be
+   * understood here or the control silently switches itself off.
+   *
+   * Entries are trimmed, lowercased and stripped of a fully-qualifying trailing dot, and the
+   * same normalisation is applied to the URL being checked, so neither side can win by
+   * spelling the same DNS name differently. A bare hostname entry matches any port on that
+   * host; an entry naming the scheme's default port (`example.com:443` for https) also matches
+   * the portless URL. A value that is neither an array nor a string carries no hostnames, so
+   * the allowlist is inactive — that case is LOGGED as an error rather than passed over, since
+   * it looks identical to "correctly unset" from the outside.
+   *
    * @example ['llm.example.com', 'localhost:11434']
+   * @example 'llm.example.com,localhost:11434'   // NSC__AI__ALLOWED_BASE_URL_HOSTS
    */
-  allowedBaseUrlHosts?: string[];
+  allowedBaseUrlHosts?: string | string[];
 
   /**
    * Persist an audit record (`aiInteractions`) for every prompt run (admin-readable).
@@ -2184,7 +2257,50 @@ export interface IServerOptions {
     mailjet?: MailjetOptions;
 
     /**
-     * Password reset link for email
+     * Base of the link in the LEGACY password-reset mail (`/users/password/reset-request`).
+     *
+     * Three cases, and the difference between them is where the token lands:
+     *
+     * | Value                                   | Link the recipient gets                  |
+     * | --------------------------------------- | ---------------------------------------- |
+     * | contains `{token}`                      | placeholder replaced, wherever it sits   |
+     * | set, but no `{token}`                   | token appended as a PATH segment         |
+     * | not set (the default below)             | `?token=<token>`, per the default's shape |
+     *
+     * **Copying the default is safe; writing your own base is where it gets sharp.** The default
+     * carries `{token}`, so pasting it lands in row one and behaves exactly as leaving the option
+     * out. A base WITHOUT the placeholder lands in row two instead — same URL, different link. That
+     * is deliberate: it is the convention the legacy flow has always used, and changing it would
+     * silently break every project whose page reads a path parameter. It is also easy to walk into
+     * by accident, so the framework logs a warning at boot for any configured value without a
+     * placeholder. The way to silence it is to write `{token}` where you want the token, which
+     * states the convention in the place it applies instead of leaving it implicit.
+     *
+     * Build the link with `CoreUserService.buildPasswordResetLink(token)` rather than by
+     * concatenation. It returns `null` when it can resolve nothing — which is the difference
+     * between sending no mail and sending one whose link reads `undefined/<token>`. The latter
+     * happened in a downstream project and reached real recipients: the request succeeds, the mail
+     * arrives, it looks right, and only the click reveals it, to somebody who by definition has no
+     * second way in.
+     *
+     * Note this is separate from `betterAuth.emailVerification.passwordResetLink`, which serves the
+     * IAM flow. Both DEFAULTS now point at the same page with `?token=`; what still differs is the
+     * fallback for a configured value without a placeholder — path segment here, `?token=` there.
+     * A project using both flows should point them at the same page, and writing `{token}` in both
+     * makes them identical.
+     *
+     * @default `<appUrl>/auth/reset-password?token={token}`
+     * @since 11.38.0
+     *
+     * @example
+     * ```typescript
+     * email: {
+     *   // A page that reads the token from the path. Spelling out `{token}` is what keeps the
+     *   // boot warning quiet — `'https://example.com/auth/reset-password'` produces the same
+     *   // link, but leaves the reader guessing which convention was meant.
+     *   passwordResetLink: 'https://example.com/auth/reset-password/{token}',
+     * }
+     * ```
      */
     passwordResetLink?: string;