@lenne.tech/nest-server 11.38.0 → 11.39.0

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
@@ -2184,7 +2241,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;
 

package/src/core/common/services/email.service.ts

@@ -1,8 +1,9 @@
 import { createHash } from 'crypto';
-import { Inject, Injectable, OnModuleDestroy, Optional } from '@nestjs/common';
+import { Inject, Injectable, Logger, OnModuleDestroy, Optional } from '@nestjs/common';
 import nodemailer = require('nodemailer');
 import { Attachment } from 'nodemailer/lib/mailer';
 
+import { isImpossibleSmtpTlsCombination } from '../helpers/config.helper';
 import { isNonEmptyString, isTrue, returnFalse } from '../helpers/input.helper';
 import { MailTransportOptions } from '../interfaces/server-options.interface';
 import { HUB_EMAIL_CAPTURE } from '../../modules/hub/hub.constants';
@@ -22,6 +23,11 @@ export class EmailService implements OnModuleDestroy {
   private cachedTransporter: nodemailer.Transporter | null = null;
   private cachedSmtpConfig: string | null = null;
 
+  protected readonly emailServiceLogger = new Logger(EmailService.name);
+
+  /** Once-per-process latch for the SMTP TLS warning — a per-send warning would be noise. */
+  private smtpTlsWarningEmitted = false;
+
   /**
    * Inject services
    */
@@ -33,6 +39,43 @@ export class EmailService implements OnModuleDestroy {
     @Optional() @Inject(HUB_EMAIL_CAPTURE) protected readonly emailCapture?: IHubEmailCapture,
   ) {}
 
+  /**
+   * Warn once when the SMTP port and TLS mode describe a connection that cannot be established.
+   *
+   * `secure: true` means implicit TLS, which only port 465 speaks. On 587 — the submission port,
+   * which upgrades through STARTTLS — nodemailer sends a TLS ClientHello, the server answers with
+   * an SMTP greeting, and OpenSSL reports `wrong version number`. This package's own `production`
+   * profile shipped that pair, and because authentication mail is deliberately not awaited, the
+   * API answered 200 while every message died in transport. It was found in production.
+   *
+   * 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 stayed invisible.
+   * A warning names the problem without deciding it.
+   */
+  protected warnOnImpossibleSmtpTlsCombination(smtp: unknown): void {
+    if (this.smtpTlsWarningEmitted || typeof smtp !== 'object' || smtp === null) {
+      return;
+    }
+
+    const { port, secure } = smtp as { port?: unknown; secure?: unknown };
+    if (typeof port !== 'number' || typeof secure !== 'boolean') {
+      return;
+    }
+
+    if (!isImpossibleSmtpTlsCombination(port, secure)) {
+      return;
+    }
+
+    this.smtpTlsWarningEmitted = true;
+    this.emailServiceLogger.warn(
+      `SMTP is configured with port ${port} and secure: ${secure}, a combination that cannot connect. ` +
+        '`secure: true` starts TLS immediately, which only port 465 supports; port 587 and friends open in ' +
+        'plaintext and upgrade via STARTTLS, which needs `secure: false`. Expect ' +
+        '"wrong version number" from OpenSSL and NO outgoing mail — silently, because authentication mail ' +
+        'is not awaited. Set SMTP_SECURE=false for port 587, or SMTP_PORT=465 to keep implicit TLS.',
+    );
+  }
+
   onModuleDestroy(): void {
     if (this.cachedTransporter) {
       this.cachedTransporter.close();
@@ -109,6 +152,8 @@ export class EmailService implements OnModuleDestroy {
       }
     }
 
+    this.warnOnImpossibleSmtpTlsCombination(smtp);
+
     // Hub mailbox capture (Mailpit-style). Runs after templates are rendered, before the transport.
     // In capture mode it records the mail and suppresses the send (returns a jsonTransport-like ack).
     // Fully guarded: a broken mailbox hook must never break (or crash) the mail path.

package/src/core/common/services/module.service.ts

@@ -177,6 +177,7 @@ export abstract class ModuleService<T extends CoreModel = any> {
             'password',
             'verificationToken',
             'passwordResetToken',
+            'passwordResetTokenExpiresAt',
             'refreshTokens',
             'tempTokens',
           ]);

package/src/core/modules/better-auth/better-auth.config.ts

@@ -1691,6 +1691,18 @@ function validateConfig(
     case 'auto-generated':
       warnings.push('BETTER_AUTH: No secret configured - using auto-generated secret.');
       warnings.push('CONSEQUENCE: All user sessions will be invalidated on server restart!');
+      // The session consequence above is transient — a restart clears it. This one is not, and it
+      // surfaces long after the cause: the JWT plugin PERSISTS a `jwks` document encrypted with
+      // whatever secret was active when it was created. Booting once without a secret is therefore
+      // enough to leave a row that no later, real secret can 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 deployment with few sign-ins can be months later. Observed in
+      // production on a key written at setup time.
+      warnings.push(
+        'CONSEQUENCE: a `jwks` key persisted now is encrypted with THIS throwaway secret and stays ' +
+          'unreadable once a real one is configured — /iam/token then fails with "Failed to decrypt ' +
+          'private key". Drop the `jwks` collection after setting a permanent secret.',
+      );
       warnings.push(
         'FOR PRODUCTION: Set betterAuth.secret in config or provide a valid fallback secret (min 32 chars).',
       );
@@ -1700,6 +1712,19 @@ function validateConfig(
       warnings.push(
         'BETTER_AUTH: Using fallback secret (backwards compatible). Consider setting betterAuth.secret explicitly.',
       );
+      // The same persistence trap as the auto-generated branch, and MORE likely to be walked into,
+      // because this transition is a planned upgrade step rather than an accident: a deployment
+      // runs on `jwt.secret`, the JWT plugin persists a `jwks` document encrypted with it, and
+      // months later somebody "configures betterAuth properly" with a NEW value. The key is then
+      // unreadable, nothing fails at the time, and `/iam/token` starts answering "Failed to
+      // decrypt private key" whenever the next JWT is requested. Observed in production, where
+      // cause and symptom were five weeks apart.
+      warnings.push(
+        'BEFORE setting betterAuth.secret later: any `jwks` key persisted now is encrypted with THIS ' +
+          'fallback secret. Setting a DIFFERENT explicit secret makes it unreadable and /iam/token ' +
+          'then fails with "Failed to decrypt private key" — reuse the same value, or drop the `jwks` ' +
+          'collection when you change it.',
+      );
       break;
     // 'explicit' - no warning needed, explicitly configured
   }

package/src/core/modules/better-auth/core-better-auth-api.middleware.ts

@@ -5,6 +5,7 @@ import { isProduction } from '../../common/helpers/logging.helper';
 import { ConfigService } from '../../common/services/config.service';
 import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service';
 import { BetterAuthCookieHelper, createCookieHelper } from './core-better-auth-cookie.helper';
+import { wrapBetterAuthErrorResponse } from './core-better-auth-error-codes.helper';
 import { runWithResetPassword } from './core-better-auth-password-reset.registry';
 import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
 import { extractSessionToken, sendWebResponse, signCookieValue, toWebRequest } from './core-better-auth-web.helper';
@@ -310,10 +311,16 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
       // Better-Auth invokes inside this call, and which is told WHICH user was reset but not
       // to WHAT — can read the new password and mirror it into the legacy store. The context
       // lives exactly as long as the handler call, so no other request can observe it.
-      const response = resetPassword
+      const rawResponse = resetPassword
         ? await runWithResetPassword(resetPassword, () => authInstance.handler(webRequest))
         : await authInstance.handler(webRequest);
 
+      // The single choke point for every error exit below. Each later branch acts only on
+      // `response.ok`, so rewriting failures HERE reaches all of them without touching any — and
+      // without a second place that has to remember to do it. Successful responses are returned
+      // by identity, so nothing on the happy path changes shape.
+      const response = await wrapBetterAuthErrorResponse(rawResponse);
+
       this.logger.debug(`Better Auth handler response: ${response.status}`);
 
       // For passkey generate requests with DB storage, extract verificationToken and store mapping

package/src/core/modules/better-auth/core-better-auth-email-verification.service.ts

@@ -4,7 +4,7 @@ import ejs = require('ejs');
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { isProductionLikeEnv } from '../../common/helpers/cookies.helper';
+import { isProductionLikeEnv, resolveAppUrlFromConfig } from '../../common/helpers/cookies.helper';
 import { maskEmail } from '../../common/helpers/logging.helper';
 import { IBetterAuthEmailVerificationConfig } from '../../common/interfaces/server-options.interface';
 import { BrevoService } from '../../common/services/brevo.service';
@@ -222,7 +222,7 @@ export class CoreBetterAuthEmailVerificationService {
     try {
       // Override URL if callbackURL is configured (frontend-based verification)
       if (this.config.callbackURL) {
-        url = this.buildFrontendVerificationUrl(token);
+        url = this.buildFrontendVerificationUrl(token, user.email);
       }
 
       this.logAuthUrlForDevelopment('EMAIL VERIFICATION', user.email, url);
@@ -358,6 +358,10 @@ export class CoreBetterAuthEmailVerificationService {
       const templateData = {
         appName,
         link: url,
+        // Better-Auth's own lifetime, NOT the legacy `auth.passwordReset.tokenExpiresInMinutes`.
+        // The two flows expire independently, and announcing the wrong one would be worse than
+        // announcing none.
+        linkExpiresInMinutes: this.passwordResetLinkExpiryMinutes(),
         name: user.name || user.email.split('@')[0],
       };
 
@@ -596,6 +600,27 @@ export class CoreBetterAuthEmailVerificationService {
    * `?token=`. That is what lets a page reading a PATH parameter configure
    * `https://example.com/auth/reset-password/{token}`.
    */
+  /**
+   * How long the IAM reset link stays valid, in whole minutes, for the mail to state.
+   *
+   * Read from Better-Auth's own `emailAndPassword.resetPasswordTokenExpiresIn` — expressed in
+   * SECONDS, defaulting to 3600 (`password.mjs`). Deliberately not the legacy
+   * `auth.passwordReset.tokenExpiresInMinutes`: the two flows expire independently, and a mail that
+   * announces the other flow's deadline is worse than one that announces none.
+   *
+   * Returns 0 for anything unusable, which the templates render as no sentence at all — silence is
+   * the safe failure for a deadline nobody can verify.
+   */
+  protected passwordResetLinkExpiryMinutes(): number {
+    const raw = this.configService.getFastButReadOnly<unknown>(
+      'betterAuth.options.emailAndPassword.resetPasswordTokenExpiresIn',
+    );
+    const seconds = typeof raw === 'string' ? Number(raw) : raw;
+    const resolved = typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0 ? seconds : 3600;
+
+    return Math.max(1, Math.round(resolved / 60));
+  }
+
   protected buildPasswordResetUrl(options: SendPasswordResetEmailOptions): string {
     const configured = this.config.passwordResetLink;
 
@@ -606,8 +631,21 @@ export class CoreBetterAuthEmailVerificationService {
 
     let target = typeof configured === 'string' && configured.trim().length ? configured.trim() : undefined;
 
+    // The caller's own `redirectTo`, when it sent one, beats anything this server would guess.
+    // `nuxt-base-starter` sends it on every request (`forgot-password.vue` →
+    // `requestPasswordReset({ email, redirectTo: appUrl('/auth/reset-password', siteUrl) })`), and
+    // a client that names its page is a better authority on that page than a framework default.
+    if (!target) {
+      target = this.readCallbackUrlFromBetterAuthLink(options.url);
+    }
+
+    // The SAME resolver the legacy twin uses. Until 11.39.0 this read `appUrl` straight off the
+    // configuration, which meant no localhost default in local/ci/e2e, no host-split `baseUrl`
+    // derivation, and no `cors.deriveAppUrl` opt-out — three behaviours the other half of the same
+    // framework had. Two hand-maintained copies of one decision is how that happened.
+    const appUrl = resolveAppUrlFromConfig(this.configService);
+
     if (!target) {
-      const appUrl = this.configService.getFastButReadOnly<string>('appUrl');
       if (!appUrl) {
         // Nothing to point at. Better-Auth's link at least works, which beats a guess.
         return options.url;
@@ -617,7 +655,6 @@ export class CoreBetterAuthEmailVerificationService {
 
     // Resolve a relative value against appUrl, like buildFrontendVerificationUrl does.
     if (target.startsWith('/')) {
-      const appUrl = this.configService.getFastButReadOnly<string>('appUrl');
       if (!appUrl) {
         return options.url;
       }
@@ -633,6 +670,43 @@ export class CoreBetterAuthEmailVerificationService {
     return `${target}${separator}token=${encodeURIComponent(token)}`;
   }
 
+  /**
+   * Read the `callbackURL` out of the link Better-Auth built, i.e. the caller's own `redirectTo`.
+   *
+   * ── Why reading this back is SAFE, and why that is not obvious ──────────────────
+   * `redirectTo` arrives in the REQUEST BODY of `/request-password-reset`, which is unauthenticated.
+   * Putting a client-supplied URL into a password-reset mail would otherwise be a token-exfiltration
+   * vector in its purest form: an attacker requests a reset for a victim's address with
+   * `redirectTo: https://evil.example`, and the victim receives a genuine mail, from the real
+   * sender, carrying a valid token to the attacker's site.
+   *
+   * It is safe here only because Better-Auth validates the value BEFORE this runs. The endpoint
+   * declares `use: [originCheck((ctx) => ctx.body.redirectTo)]`, so a `redirectTo` outside
+   * `trustedOrigins` is rejected at request time and `sendResetPassword` is never reached. By the
+   * time we see it, the origin is one this deployment already trusts.
+   *
+   * That makes `trustedOrigins` load-bearing for THIS path too, not only for CORS — which is worth
+   * knowing before anyone widens it. `cors.allowAll` does not widen it (an origin check has no
+   * "allow everything" mode), but an over-broad `allowedOrigins` would.
+   *
+   * Returns `undefined` for anything unparseable or absent, so the caller falls through to its own
+   * resolution rather than to a half-formed URL.
+   */
+  protected readCallbackUrlFromBetterAuthLink(betterAuthUrl: string): string | undefined {
+    if (typeof betterAuthUrl !== 'string' || !betterAuthUrl.length) {
+      return undefined;
+    }
+
+    try {
+      const callbackUrl = new URL(betterAuthUrl).searchParams.get('callbackURL');
+      return callbackUrl?.trim().length ? callbackUrl.trim() : undefined;
+    } catch {
+      // Not a parseable absolute URL. Nothing to read, and nothing worth logging — the caller has
+      // two further fallbacks.
+      return undefined;
+    }
+  }
+
   /**
    * Build the frontend verification URL from the configured callbackURL and token.
    *
@@ -641,7 +715,7 @@ export class CoreBetterAuthEmailVerificationService {
    * @param token - The verification token from Better-Auth
    * @returns The full frontend URL with token query parameter
    */
-  protected buildFrontendVerificationUrl(token: string): string {
+  protected buildFrontendVerificationUrl(token: string, email?: string): string {
     let baseUrl = this.config.callbackURL!;
 
     // Resolve relative paths against appUrl
@@ -652,7 +726,28 @@ export class CoreBetterAuthEmailVerificationService {
 
     // Append token as query parameter
     const separator = baseUrl.includes('?') ? '&' : '?';
-    return `${baseUrl}${separator}token=${token}`;
+    let url = `${baseUrl}${separator}token=${encodeURIComponent(token)}`;
+
+    // The address travels alongside the token so the page can offer "send a new email" when the
+    // token turns out to be expired — which is the ONLY moment that button matters, and precisely
+    // the moment the page has nothing else to work with. The verification page shipped by
+    // nuxt-base-starter gates that button on `route.query.email`, so without this the user is told
+    // correctly what went wrong and left with no way to fix it.
+    //
+    // The frontend cannot recover the address itself. It is inside the token's JWT payload, and
+    // reading it there would mean trusting an unverified signature for display — not a pattern to
+    // put in a starter.
+    //
+    // The cost, stated plainly: the address appears in the URL, so it reaches browser history and
+    // any access log the app keeps. It is the recipient's OWN address, arriving in their own
+    // mailbox next to a token that is far more sensitive, so this widens nothing that the link did
+    // not already carry. Encoded, because a `+` in an address (Gmail tags, and therefore most test
+    // addresses) would otherwise arrive as a space.
+    if (email) {
+      url += `&email=${encodeURIComponent(email)}`;
+    }
+
+    return url;
   }
 
   /**