@lenne.tech/nest-server 11.38.0 → 11.40.0

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/ai/README.md

@@ -159,6 +159,39 @@ calling and executes tools itself through `CrudService` with the caller's permis
 the child runs in a temp dir so no `CLAUDE.md`/settings leak into the context. See
 `ClaudeCliProvider` for the full security model and the optional `ai.claudeCli` config.
 
+## Egress allowlist (`ai.allowedBaseUrlHosts`)
+
+A connection's `baseUrl` decides where the server sends outbound HTTP. It is admin-set, so the
+threat model is a compromised or mistyped admin rather than end-user input — but the request still
+leaves from inside your network, which is what makes it an SSRF surface.
+
+**Unset (the default) means no restriction**, so a local provider works out of the box. When set,
+only the listed hosts are reachable and everything else is refused with
+`ServiceUnavailableException` plus a WARN naming the host:
+
+```typescript
+ai: {
+  allowedBaseUrlHosts: ['llm.example.com', 'localhost:11434'],
+}
+```
+
+```bash
+# Same setting via the canonical env spelling — a comma-separated string is understood
+NSC__AI__ALLOWED_BASE_URL_HOSTS=llm.example.com,localhost:11434
+```
+
+Matching details worth knowing before you debug a refusal:
+
+- A bare hostname entry matches **any port** on that host. An entry that names the scheme's default
+  port (`example.com:443` for https) also matches the portless URL.
+- Entries and URLs are both trimmed, lowercased, and stripped of a fully-qualifying trailing dot, so
+  `LLM.Example.com`, `llm.example.com` and `llm.example.com.` are one host.
+- The check covers **all three** outbound paths: chat completions, the capability probe, and the
+  Ollama context-window probe.
+- A value that is neither a list nor a string carries no hostnames. The allowlist is then inactive
+  and the framework logs an error — from the outside that state is indistinguishable from
+  "correctly unset", which is exactly why it is not silent.
+
 ## Connections (DB configuration)
 
 Connections live in the `aiConnections` collection and are managed by admins via

package/src/core/modules/ai/providers/openai-compatible.provider.ts

@@ -134,8 +134,8 @@ export class OpenAiCompatibleProvider implements ILlmProvider {
    * admin, not an end-user input.
    */
   protected assertBaseUrlAllowed(url: string): void {
-    const allowedHosts = ConfigService.get<string[]>('ai.allowedBaseUrlHosts');
-    if (!Array.isArray(allowedHosts) || !allowedHosts.length) {
+    const allowedHosts = this.resolveAllowedBaseUrlHosts();
+    if (!allowedHosts.length) {
       return;
     }
     let parsed: URL;
@@ -144,7 +144,17 @@ export class OpenAiCompatibleProvider implements ILlmProvider {
     } catch {
       throw new ServiceUnavailableException(ErrorCode.AI_CONNECTION_INVALID_URL);
     }
-    if (!allowedHosts.includes(parsed.host) && !allowedHosts.includes(parsed.hostname)) {
+    // A hostname entry stays host-wide (any port); the extra candidates only make an
+    // operator who was MORE explicit than necessary succeed rather than fail. `URL.host`
+    // omits the default port, so a conscientious `llm.example.com:443` entry would
+    // otherwise never match `https://llm.example.com/` — a lockout whose only symptom is
+    // a WARN and "the AI stopped working". Nothing here widens the set of reachable hosts.
+    const defaultPort = parsed.protocol === 'https:' ? '443' : parsed.protocol === 'http:' ? '80' : '';
+    const candidates = [parsed.host, parsed.hostname];
+    if (defaultPort && parsed.host === parsed.hostname) {
+      candidates.push(`${parsed.hostname}:${defaultPort}`);
+    }
+    if (!candidates.map((candidate) => this.normaliseHostEntry(candidate)).some((c) => allowedHosts.includes(c))) {
       this.logger.warn(
         `AI connection "${this.connection.name}" host "${parsed.host}" is not in ai.allowedBaseUrlHosts`,
       );
@@ -152,6 +162,62 @@ export class OpenAiCompatibleProvider implements ILlmProvider {
     }
   }
 
+  /**
+   * The configured egress allowlist as a lowercase array, whatever shape it has.
+   *
+   * A STRING is split as CSV rather than rejected, because `ai.allowedBaseUrlHosts`
+   * is reachable through the framework's own `NSC__AI__ALLOWED_BASE_URL_HOSTS`
+   * environment mapping: `getEnvironmentObject()` turns that variable into
+   * `{ ai: { allowedBaseUrlHosts: '<string>' } }` and lodash `merge` assigns the
+   * scalar straight over the configured array. A bare `!Array.isArray(...) -> return`
+   * then reads it as "no allowlist configured" and skips the check entirely — so an
+   * operator using the canonical `NSC__` spelling silently disables SSRF egress
+   * control, with no log line and no error. A malformed security setting must be
+   * interpreted or fail CLOSED, never fail open.
+   *
+   * Entries are lowercased because `URL.host` / `URL.hostname` always are; a
+   * differently-cased entry would otherwise fail closed for no stated reason, and
+   * the only symptom would be a WARN log plus "the AI stopped working".
+   *
+   * A value that is NEITHER an array nor a string carries no hostnames and cannot be
+   * interpreted — `NSC__AI__ALLOWED_BASE_URL_HOSTS=0` coerces to a number, and
+   * `NEST_SERVER_CONFIG` can deliver an object. Returning an empty list there is the
+   * only honest answer, but it reopens egress while the operator believes the control
+   * is on, so it is LOGGED every time rather than passed over in silence. That is the
+   * difference between this and the documented unset-is-permissive default: unset is a
+   * decision, a malformed value is an accident nobody is told about.
+   */
+  protected resolveAllowedBaseUrlHosts(): string[] {
+    const configured = ConfigService.get<unknown>('ai.allowedBaseUrlHosts');
+    if (configured === undefined || configured === null) {
+      return [];
+    }
+    const entries = typeof configured === 'string' ? configured.split(',') : configured;
+    if (!Array.isArray(entries)) {
+      this.logger.error(
+        `ai.allowedBaseUrlHosts is a ${typeof configured} and carries no hostnames — the SSRF egress ` +
+          'allowlist is NOT active. Use an array or a comma-separated string.',
+      );
+      return [];
+    }
+    return entries.map((host) => this.normaliseHostEntry(String(host))).filter(Boolean);
+  }
+
+  /**
+   * Lowercase, trim, and drop a fully-qualifying trailing dot.
+   *
+   * Applied to BOTH the allowlist entry and the URL being checked, so neither side can
+   * win by spelling the same DNS name differently. `llm.example.com.` and
+   * `llm.example.com` resolve identically, so treating them as different hosts only ever
+   * produced a confusing refusal — never protection.
+   */
+  protected normaliseHostEntry(value: string): string {
+    return value
+      .trim()
+      .toLowerCase()
+      .replace(/\.(?=$|:)/, '');
+  }
+
   /**
    * Probe the backend to auto-detect capabilities for flags the connection left
    * undefined. Explicit flags are authoritative and are NOT probed. Best effort:
@@ -263,6 +329,13 @@ export class OpenAiCompatibleProvider implements ILlmProvider {
     if (!base.startsWith('http')) {
       return undefined;
     }
+    // The third outbound path from the same admin-controlled baseUrl, and the one the
+    // allowlist used to miss. It is NOT admin-only in practice: CoreAiService calls
+    // detectAndPersistCapabilities() on an ordinary user prompt whenever contextWindow is
+    // undefined, and it runs BEFORE checkRateLimit(). A guard applied to two of three
+    // egress paths is not a guard. Throwing is right here — detectContextWindow() already
+    // wraps this call, so a refusal degrades to "context window unknown".
+    this.assertBaseUrlAllowed(`${base}/api/show`);
     const response = await fetch(`${base}/api/show`, {
       body: JSON.stringify({ name: this.connection.model }),
       headers: { 'Content-Type': 'application/json' },

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;
   }
 
   /**

package/src/core/modules/better-auth/core-better-auth-error-codes.helper.ts

@@ -0,0 +1,146 @@
+import { ErrorCode } from '../error-code/error-codes';
+
+/**
+ * Translate Better-Auth's own error codes into nest-server's `#LTNS_XXXX:` message format.
+ *
+ * ── Why this exists ────────────────────────────────────────────────────────────
+ * Frontends in this stack translate errors by parsing the message for nest-server's marker —
+ * `useLtErrorTranslation` matches `/^#([A-Z_]+_\d+):\s*(.+)$/` and nothing else. Better-Auth
+ * answers with `{ code: 'INVALID_TOKEN', message: 'Invalid token' }`, which carries no marker, so
+ * the parser finds no code and hands the raw string through. The end user is shown English
+ * developer text — not as an edge case, but as the NORMAL outcome of every IAM error.
+ *
+ * That is felt most on the password-reset page: a link that has expired produces `INVALID_TOKEN`,
+ * and the person who already cannot sign in is told "Invalid token" in a language the rest of the
+ * product does not use.
+ *
+ * Wrapping the message here fixes it for every consumer at once — including projects that do not
+ * use `@lenne.tech/nuxt-extensions` and would otherwise each need their own code table.
+ *
+ * ── Two rules that keep this safe ──────────────────────────────────────────────
+ * 1. The original `code` field is left ALONE. Anything keying on `code` — Better-Auth's own client,
+ *    a project's error branch — keeps working. Only the human-facing `message` is rewritten.
+ * 2. An unknown code is passed through UNCHANGED. A guessed mapping would show a confident,
+ *    wrong sentence, which is worse than an untranslated true one. New codes are added here
+ *    deliberately, not inferred.
+ *
+ * Mapping only where the meaning is unambiguous. Three deliberate absences:
+ *
+ * - `SESSION_EXPIRED` means "re-authenticate for this sensitive action", which is not what
+ *   nest-server's `TOKEN_EXPIRED` ("please sign in again") tells the user to do.
+ * - `USER_NOT_FOUND` is an account-enumeration signal. Better-Auth already exposes it as a `code`,
+ *   but translating it into the user's language would make the oracle friendlier and more legible
+ *   — the opposite direction from the rest of this release, which spent real effort closing the
+ *   legacy reset endpoint's equivalent. Left untranslated on purpose.
+ * - Anything else Better-Auth may add later. An unmapped code passes through unchanged.
+ *
+ * `PASSWORD_TOO_SHORT` / `PASSWORD_TOO_LONG` ARE mapped, and their reachability is worth stating
+ * because it is narrower than it looks: the lt frontend hashes with `ltSha256` before sending, so
+ * every password arrives as 64 hex characters and neither bound is crossed. They remain reachable
+ * for a client that does not hash (this is a framework, not only the lt stack) and for a project
+ * that configures `minPasswordLength` above 64 — which the middleware reads as a passthrough
+ * option, so it is a supported configuration rather than a hypothetical.
+ */
+const BETTER_AUTH_ERROR_CODE_MAP: Readonly<Record<string, string>> = Object.freeze({
+  EMAIL_ALREADY_VERIFIED: ErrorCode.EMAIL_ALREADY_VERIFIED,
+  EMAIL_NOT_VERIFIED: ErrorCode.EMAIL_VERIFICATION_REQUIRED,
+  INVALID_EMAIL_OR_PASSWORD: ErrorCode.INVALID_CREDENTIALS,
+  INVALID_PASSWORD: ErrorCode.INVALID_PASSWORD,
+  // Distinct codes, not LINK_INVALID_OR_EXPIRED: Better-Auth answers BOTH with HTTP 400 on
+  // `/reset-password`, so a page branching on status alone cannot tell them apart and shows "your
+  // link is dead". The user then requests a new link, pastes the same over-long passphrase from
+  // their password manager, and fails again — a closed loop that never names the cause.
+  PASSWORD_TOO_LONG: ErrorCode.PASSWORD_TOO_LONG,
+  PASSWORD_TOO_SHORT: ErrorCode.PASSWORD_TOO_SHORT,
+  // NOT ErrorCode.INVALID_TOKEN: that one is the legacy auth service's refresh/session token and
+  // reads "sign in again". Every Better-Auth INVALID_TOKEN reaches the user through a LINK in a
+  // mail — reset, verification, magic link — and telling somebody who cannot sign in to sign in is
+  // the one instruction that helps least.
+  INVALID_TOKEN: ErrorCode.LINK_INVALID_OR_EXPIRED,
+  // Also NOT ErrorCode.TOKEN_EXPIRED ("please sign in again"), for the same reason as above and
+  // with a sharper edge: Better-Auth throws TOKEN_EXPIRED in exactly ONE place — an expired
+  // verification LINK (email-verification.mjs:178) — one line above the INVALID_TOKEN it throws
+  // for a broken one. Splitting that single user action ("I clicked an old link in my mail") into
+  // two opposite instructions would be wrong in the MORE common half, since links expire far more
+  // often than they get mangled. Worse, at that point the user is typically not signed in at all,
+  // so "sign in again" is a dead end. `LINK_INVALID_OR_EXPIRED` covers expiry in its wording.
+  TOKEN_EXPIRED: ErrorCode.LINK_INVALID_OR_EXPIRED,
+  USER_ALREADY_EXISTS: ErrorCode.EMAIL_ALREADY_EXISTS,
+  USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL: ErrorCode.EMAIL_ALREADY_EXISTS,
+});
+
+/**
+ * The nest-server message for a Better-Auth error code, or `undefined` when it has no mapping.
+ *
+ * Exported so a project can reuse the same table rather than build a second one that drifts.
+ */
+export function mapBetterAuthErrorCode(code: unknown): string | undefined {
+  return typeof code === 'string' ? BETTER_AUTH_ERROR_CODE_MAP[code] : undefined;
+}
+
+/**
+ * Rewrite a failed Better-Auth response so its `message` carries nest-server's error marker.
+ *
+ * Returns the ORIGINAL response object whenever nothing should change — a successful response, a
+ * body that is not JSON, or a code with no mapping. That matters: the response body is a stream
+ * that can be read once, so handing back an untouched original rather than a rebuilt copy keeps
+ * every other consumer of it working.
+ *
+ * Never throws. An error surfacing from the error-formatting path would replace a useful message
+ * with a 500, which is the one outcome worse than an untranslated string.
+ */
+export async function wrapBetterAuthErrorResponse(response: Response): Promise<Response> {
+  if (response.ok) {
+    return response;
+  }
+
+  // A redirect is not ours to rewrite. Better-Auth reports some failures by REDIRECTING to the
+  // caller's `callbackURL` with `?error=<CODE>` (see `redirectOnError` in its email-verification
+  // route) — a 3xx with no JSON body, so there is no message to translate. Rewriting the code in
+  // that query string instead would invent a second contract on top of Better-Auth's documented
+  // one, which the frontend reads. Those cases stay untranslated on purpose, and the frontend maps
+  // `?error=` itself.
+  if (response.status >= 300 && response.status < 400) {
+    return response;
+  }
+
+  try {
+    const body = await response.clone().json();
+    const mapped = mapBetterAuthErrorCode(body?.code);
+
+    // No mapping, or a message that already carries the marker (a nest-server exception that
+    // travelled through Better-Auth): leave it exactly as it is.
+    if (!mapped || typeof body?.message !== 'string' || body.message.startsWith('#')) {
+      return response;
+    }
+
+    const headers = new Headers();
+
+    // `set-cookie` FIRST, and via getSetCookie/append rather than the forEach below. `forEach`
+    // yields each cookie separately and `set()` overwrites, so a response carrying two of them
+    // would keep only the last. Better-Auth CLEARS session and 2FA cookies on several failure
+    // paths — exactly the responses this function rewrites — so collapsing them leaves a stale
+    // credential in the browser. `sendWebResponse` uses getSetCookie() for the same reason.
+    for (const cookie of response.headers.getSetCookie?.() ?? []) {
+      headers.append('set-cookie', cookie);
+    }
+
+    response.headers.forEach((value, key) => {
+      const lower = key.toLowerCase();
+      // content-length: the rewritten body has a different length, and a stale one truncates the
+      // response. set-cookie: already appended above, and `set()` here would undo that.
+      if (lower !== 'content-length' && lower !== 'set-cookie') {
+        headers.set(key, value);
+      }
+    });
+
+    return new Response(JSON.stringify({ ...body, message: mapped }), {
+      headers,
+      status: response.status,
+      statusText: response.statusText,
+    });
+  } catch {
+    // Not JSON, or an unreadable body. The original is still the best answer available.
+    return response;
+  }
+}

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

@@ -31,6 +31,7 @@ export * from './core-better-auth-api.middleware';
 export * from './core-better-auth-auth.model';
 export * from './core-better-auth-cookie.helper';
 export * from './core-better-auth-email-verification.service';
+export * from './core-better-auth-error-codes.helper';
 export * from './core-better-auth-migration-status.model';
 export * from './core-better-auth-models';
 export * from './core-better-auth-rate-limit.middleware';