@lenne.tech/nest-server 11.37.0 → 11.39.0

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

@@ -53,7 +53,7 @@ function generateSecureSecret(): string {
  * Hash a password using Node.js native crypto.scrypt (libuv thread pool).
  * Output format matches Better-Auth: "salt:hash" (both hex encoded).
  */
-async function nativeScryptHash(password: string): Promise<string> {
+export async function nativeScryptHash(password: string): Promise<string> {
   const salt = crypto.randomBytes(16).toString('hex');
   const normalized = password.normalize('NFKC');
   const key = await new Promise<Buffer>((resolve, reject) => {
@@ -67,8 +67,14 @@ async function nativeScryptHash(password: string): Promise<string> {
 
 /**
  * Verify a password against a Better-Auth scrypt hash using Node.js native crypto.scrypt.
+ *
+ * Exported so tests can ask the PRODUCT whether a stored credential accepts a password, rather
+ * than re-declaring the scrypt parameters next to their assertion. A copy drifts silently: change
+ * a parameter here and the copy derives a different key, turning every affected assertion into a
+ * red with a misleading diagnosis — or, if both drift compatibly, into a green for the wrong
+ * reason.
  */
-async function nativeScryptVerify(data: { hash: string; password: string }): Promise<boolean> {
+export async function nativeScryptVerify(data: { hash: string; password: string }): Promise<boolean> {
   const [salt, storedKey] = data.hash.split(':');
   if (!salt || !storedKey) return false;
   const normalized = data.password.normalize('NFKC');
@@ -128,6 +134,13 @@ export interface CreateBetterAuthOptions {
    */
   onEmailVerified?: OnEmailVerifiedCallback;
 
+  /**
+   * Callback invoked after a password reset has been written to the IAM credential.
+   * Injected from CoreBetterAuthModule to mirror the new password into the legacy store,
+   * so a deployment running both systems does not end up with two different passwords.
+   */
+  onPasswordReset?: OnPasswordResetCallback;
+
   /**
    * Callback for sending the password-reset email.
    * Injected from CoreBetterAuthModule to use NestJS services.
@@ -179,6 +192,51 @@ export interface CreateBetterAuthOptions {
  */
 export type OnEmailVerifiedCallback = (userId: string) => Promise<void>;
 
+/**
+ * Callback for when a password reset has been APPLIED to the IAM credential.
+ *
+ * Injected from CoreBetterAuthModule so the new password can also be mirrored into the
+ * legacy bcrypt store. Better-Auth reports only WHICH user was reset — the password
+ * itself comes from `core-better-auth-password-reset.registry.ts`, which the API
+ * middleware fills for the duration of the handler call.
+ *
+ * Fires for every native reset route (token, email-OTP, phone-number).
+ */
+/**
+ * Combines the framework's `onPasswordReset` with a project-supplied one so neither is lost.
+ *
+ * Returns an empty object when there is nothing to install, so the caller can spread it
+ * unconditionally without writing an `onPasswordReset: undefined` key — Better-Auth resolves
+ * the hook by presence, and an explicitly-undefined key reads as "declared, does nothing".
+ *
+ * The framework hook runs FIRST and its failure does not prevent the project hook: they are
+ * independent consequences of the same event, and one broken listener must not silently
+ * cancel the other.
+ */
+function chainOnPasswordReset(base: unknown, override: unknown): { onPasswordReset?: OnPasswordResetCallback } {
+  const baseHook = typeof base === 'function' ? (base as OnPasswordResetCallback) : undefined;
+  const overrideHook = typeof override === 'function' ? (override as OnPasswordResetCallback) : undefined;
+
+  if (!baseHook) {
+    return overrideHook ? { onPasswordReset: overrideHook } : {};
+  }
+  if (!overrideHook) {
+    return { onPasswordReset: baseHook };
+  }
+
+  return {
+    onPasswordReset: async (data) => {
+      const results = await Promise.allSettled([baseHook(data), overrideHook(data)]);
+      const failure = results.find((result) => result.status === 'rejected');
+      if (failure && failure.status === 'rejected') {
+        throw failure.reason;
+      }
+    },
+  };
+}
+
+export type OnPasswordResetCallback = (data: { user: { email?: string; id: string } }) => Promise<void>;
+
 /**
  * Options for creating a better-auth instance
  */
@@ -371,8 +429,16 @@ export interface CreateBetterAuthResult {
 }
 
 export function createBetterAuthInstance(options: CreateBetterAuthOptions): CreateBetterAuthResult | null {
-  const { config, db, fallbackSecrets, onEmailVerified, sendResetPasswordEmail, sendVerificationEmail, serverEnv } =
-    options;
+  const {
+    config,
+    db,
+    fallbackSecrets,
+    onEmailVerified,
+    onPasswordReset,
+    sendResetPasswordEmail,
+    sendVerificationEmail,
+    serverEnv,
+  } = options;
 
   // Return null only if better-auth is explicitly disabled
   // BetterAuth is enabled by default (zero-config)
@@ -517,6 +583,29 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
       // here claimed a mail-less server would keep answering RESET_PASSWORD_DISABLED; it would not.
       // `emailAndPassword.passwordReset: false` is the real off switch, for deployments whose reset
       // policy is support-mediated or SSO-primary.
+      // Mirror an applied reset into the legacy bcrypt store.
+      //
+      // Without this, a deployment running Legacy Auth next to IAM keeps the OLD password
+      // valid on the legacy path after a reset — including a reset somebody performed
+      // BECAUSE the old password was compromised. Better-Auth tells us which user was
+      // reset; the password comes from the API middleware via the reset registry.
+      ...(onPasswordReset && {
+        onPasswordReset: (async (data) => {
+          try {
+            await onPasswordReset(data);
+          } catch (error) {
+            // Never fail the reset itself: the IAM credential is already written, and
+            // refusing the response would tell the user their reset did not work when it
+            // half did. Report it instead.
+            logger.error(
+              `Failed to mirror the password reset to the legacy store: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+            );
+          }
+        }) satisfies OnPasswordResetCallback,
+      }),
+
       // Mirrors the emailVerification.sendVerificationEmail wiring.
       ...(sendResetPasswordEmail &&
         config.emailAndPassword?.passwordReset !== false && {
@@ -606,6 +695,19 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
         // READS. The result is an asymmetric pair — anyone who resets their password can then
         // never sign in again. An explicit override still wins; only `undefined` is ignored.
         password: mergeDefined(base.password, override.password),
+        // `onPasswordReset` is subject to the SAME hazard as `password` above, and needs the
+        // opposite treatment: it must not be replaceable at all.
+        //
+        // It is what mirrors an applied IAM reset into the legacy bcrypt store. A project has
+        // an entirely reasonable motive to declare its own (audit logging, a notification
+        // mail) — and the spread would then drop the framework's, silently restoring the
+        // pre-11.38.0 defect where the OLD password stays valid on the legacy path after a
+        // reset, including a reset performed BECAUSE it leaked. Both stores report success.
+        //
+        // So the two are CHAINED rather than merged: the framework mirror always runs, the
+        // project hook runs after it. That is a deliberate asymmetry to `password`, where an
+        // explicit override wins — a hasher is a choice, a credential-store mirror is not.
+        ...chainOnPasswordReset(base.onPasswordReset, override.onPasswordReset),
       };
     }
     if (optionsAdvanced && typeof optionsAdvanced === 'object') {
@@ -1589,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).',
       );
@@ -1598,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

@@ -1,10 +1,13 @@
-import { Injectable, Logger, NestMiddleware, Optional } from '@nestjs/common';
+import { BadRequestException, Injectable, Logger, NestMiddleware, Optional } from '@nestjs/common';
 import { Response as ExpressResponse, NextFunction, Request } from 'express';
 
 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';
 import { CoreBetterAuthService } from './core-better-auth.service';
 
@@ -23,6 +26,29 @@ import { CoreBetterAuthService } from './core-better-auth.service';
  */
 const CONTROLLER_HANDLED_PATHS = ['/features', '/sign-in/email', '/sign-up/email', '/sign-out', '/session'];
 
+/**
+ * Native Better-Auth routes that set a NEW password from a token or OTP, with the body
+ * field each of them carries it in.
+ *
+ * These are forwarded (they are not in CONTROLLER_HANDLED_PATHS), so unlike sign-in and
+ * sign-up nothing normalizes their password — Better-Auth hashes whatever arrives. That
+ * is a problem, because the sign-in path DOES normalize: a plaintext reset would be
+ * stored as `scrypt(plaintext)` while every later sign-in checks `scrypt(sha256(...))`,
+ * and the account is locked out with the password its owner just chose. Normalizing
+ * here puts every write of a credential on the same footing as every read of one.
+ *
+ * Matching is EXACT (after trimming a trailing slash and lower-casing), not prefix-based. So
+ * `/reset-password/:token` — Better-Auth's GET redirect — never matches an entry at all and is
+ * forwarded untouched. That is the intended outcome, but for this reason and not because "the
+ * body has no password field": switching the matcher to `startsWith` would start rewriting that
+ * redirect's body on the strength of a comment that was never true.
+ */
+export const PASSWORD_RESET_PATHS: { field: string; path: string }[] = [
+  { field: 'newPassword', path: '/reset-password' },
+  { field: 'password', path: '/email-otp/reset-password' },
+  { field: 'newPassword', path: '/phone-number/reset-password' },
+];
+
 /**
  * Passkey paths that generate challenges
  */
@@ -59,8 +85,88 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
   constructor(
     private readonly betterAuthService: CoreBetterAuthService,
     @Optional() private readonly challengeService?: CoreBetterAuthChallengeService,
+    @Optional() private readonly userMapper?: CoreBetterAuthUserMapper,
   ) {}
 
+  /**
+   * Brings a native reset route's password to the same shape sign-in will present, and
+   * returns that value so the legacy mirror can reuse it.
+   *
+   * Returns `undefined` when this is not a password-setting route or the body carries no
+   * password — both mean "leave the request untouched".
+   *
+   * @throws BadRequestException when a plaintext password violates the configured length policy
+   */
+  protected normalizeResetPassword(req: Request, relativePath: string): string | undefined {
+    // Trailing slashes and case are normalized before matching. Express does not collapse a
+    // trailing slash on `originalUrl`, and Better-Auth's own router is more permissive than
+    // `===` — so a variant it accepts but this table does not would silently skip BOTH the
+    // normalization and the legacy mirror, i.e. reproduce the exact lockout this method exists
+    // to prevent, through a URL shape rather than a code change.
+    const normalizedPath = relativePath.replace(/\/+$/, '').toLowerCase();
+    const route = PASSWORD_RESET_PATHS.find((entry) => normalizedPath === entry.path);
+    if (!route) {
+      return undefined;
+    }
+
+    if (!this.userMapper) {
+      // Fail LOUD rather than open. Today every module variant that provides this middleware
+      // also provides the mapper, so this is unreachable — but silently forwarding an
+      // un-normalized password stores `scrypt(plaintext)` against a sign-in that checks
+      // `scrypt(sha256(...))`, and the user is locked out with the password they just chose.
+      // A guard on a correctness-critical step must not degrade quietly.
+      this.logger.error(
+        `No CoreBetterAuthUserMapper available — the password on ${relativePath} is NOT normalized. ` +
+          'Better-Auth will store scrypt(plaintext) while sign-in checks scrypt(sha256(...)), ' +
+          'locking the account out with its new password.',
+      );
+      return undefined;
+    }
+
+    const submitted = req.body?.[route.field];
+    if (!submitted || typeof submitted !== 'string') {
+      return undefined;
+    }
+
+    this.assertResetPasswordLength(submitted);
+
+    const normalized = this.userMapper.normalizePasswordForIam(submitted);
+    // `toWebRequest` serializes `req.body`, so writing it back here is what Better-Auth
+    // actually hashes.
+    req.body[route.field] = normalized;
+    return normalized;
+  }
+
+  /**
+   * Enforces the configured password length on the value the CLIENT actually sent.
+   *
+   * Better-Auth checks `minPasswordLength`/`maxPasswordLength` against the body it receives —
+   * and by then this middleware has replaced it with a 64-character sha256, so both bounds
+   * always pass. Without this check there would be no server-side minimum password length on
+   * any reset path at all.
+   *
+   * An already-hashed value carries no length information, so it cannot be checked here. That
+   * limit is real and belongs in the client; it is stated in the migration guide rather than
+   * pretended away.
+   */
+  protected assertResetPasswordLength(submitted: string): void {
+    if (/^[a-f0-9]{64}$/i.test(submitted)) {
+      return;
+    }
+
+    // The bounds live on the Better-Auth passthrough (`betterAuth.options.emailAndPassword`),
+    // not on the framework's own typed block — so they are read defensively. The fallbacks are
+    // Better-Auth's own defaults, which is what applied before this check existed.
+    const passthrough = (this.betterAuthService.getConfig()?.options as Record<string, any> | undefined)
+      ?.emailAndPassword;
+    const min = typeof passthrough?.minPasswordLength === 'number' ? passthrough.minPasswordLength : 8;
+    const max = typeof passthrough?.maxPasswordLength === 'number' ? passthrough.maxPasswordLength : 128;
+
+    if (submitted.length < min || submitted.length > max) {
+      throw new BadRequestException(`Password must be between ${min} and ${max} characters`);
+    }
+  }
+
   /**
    * Gets or creates the cookie helper instance.
    * Lazy initialization because betterAuthService may not be fully initialized in constructor.
@@ -186,6 +292,10 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
         }
       }
 
+      // Put a reset password into the shape sign-in expects BEFORE the body is
+      // serialized, and keep the value for the legacy mirror below.
+      const resetPassword = this.normalizeResetPassword(req, relativePath);
+
       // Convert Express request to Web Standard Request with proper cookie signing
       const webRequest = await toWebRequest(req, {
         basePath,
@@ -195,8 +305,21 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
         sessionToken,
       });
 
-      // Call Better Auth's native handler
-      const response = await authInstance.handler(webRequest);
+      // Call Better Auth's native handler.
+      //
+      // For a reset, the call is wrapped so that `emailAndPassword.onPasswordReset` — which
+      // 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 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}`);
 

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';
@@ -22,12 +22,12 @@ import { AuthEmailCallbackOptions, formatProjectName } from './better-auth.confi
  */
 type ResolvedEmailVerificationConfig = Pick<
   IBetterAuthEmailVerificationConfig,
-  'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId'
+  'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId' | 'passwordResetLink'
 > &
   Required<
     Omit<
       IBetterAuthEmailVerificationConfig,
-      'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId' | 'resendCooldownSeconds'
+      'brevoTemplateId' | 'callbackURL' | 'passwordResetBrevoTemplateId' | 'passwordResetLink' | 'resendCooldownSeconds'
     >
   > & {
     resendCooldownSeconds: number;
@@ -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);
@@ -328,7 +328,8 @@ export class CoreBetterAuthEmailVerificationService {
    *   override that calls this directly must handle it.
    */
   async sendPasswordResetEmail(options: SendPasswordResetEmailOptions): Promise<void> {
-    const { url, user } = options;
+    const { user } = options;
+    const url = this.buildPasswordResetUrl(options);
 
     this.logAuthUrlForDevelopment('PASSWORD RESET', user.email, url);
 
@@ -357,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],
       };
 
@@ -569,6 +574,139 @@ export class CoreBetterAuthEmailVerificationService {
     };
   }
 
+  /**
+   * Where the password-reset mail points.
+   *
+   * Defaults to the APP rather than to the link Better-Auth generates, which points at the API
+   * (`https://api.example.com/iam/reset-password/<token>?callbackURL=…`) and redirects from there.
+   * That works, but it puts an unfamiliar domain into a password mail — the one thing recipients
+   * are trained to check. In this stack an app host and an API host are the norm, so the app is
+   * the better default.
+   *
+   * WHAT THIS GIVES UP, STATED PLAINLY
+   *
+   * Better-Auth's redirect route validates the token and its expiry before forwarding, so an
+   * expired link produced an error page rather than a form that fails on submit. Linking straight
+   * to the app moves that error later. It is NOT a security difference: the token reaches the app
+   * URL either way, and the `callbackURL` origin check only exists because of the hop it removes.
+   * `passwordResetLink: false` keeps Better-Auth's link for anyone who wants the early error.
+   *
+   * Resolution order — the first that yields something wins:
+   *   1. `betterAuth.emailVerification.passwordResetLink` (`false` → Better-Auth's own link)
+   *   2. `<appUrl>/auth/reset-password` — the starter's reset page
+   *   3. Better-Auth's link, when no app URL can be resolved
+   *
+   * `{token}` is substituted anywhere in the configured value; without it the token is appended as
+   * `?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;
+
+    // Explicit opt-out: keep Better-Auth's link, including its token validation hop.
+    if (configured === false) {
+      return options.url;
+    }
+
+    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) {
+      if (!appUrl) {
+        // Nothing to point at. Better-Auth's link at least works, which beats a guess.
+        return options.url;
+      }
+      target = `${appUrl.replace(/\/$/, '')}/auth/reset-password`;
+    }
+
+    // Resolve a relative value against appUrl, like buildFrontendVerificationUrl does.
+    if (target.startsWith('/')) {
+      if (!appUrl) {
+        return options.url;
+      }
+      target = `${appUrl.replace(/\/$/, '')}${target}`;
+    }
+
+    const token = options.token;
+    if (target.includes('{token}')) {
+      return target.replace(/\{token\}/g, encodeURIComponent(token));
+    }
+
+    const separator = target.includes('?') ? '&' : '?';
+    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.
    *
@@ -577,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
@@ -588,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;
   }
 
   /**