@lenne.tech/nest-server 11.11.0 → 11.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.11.0",
+  "version": "11.12.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -105,7 +105,7 @@
     "cookie-parser": "1.4.7",
     "dotenv": "17.2.3",
     "ejs": "3.1.10",
-    "express": "5.1.0",
+    "express": "5.2.1",
     "graphql": "16.12.0",
     "graphql-query-complexity": "1.1.0",
     "graphql-subscriptions": "3.0.0",
@@ -117,7 +117,7 @@
     "mongoose": "9.1.5",
     "multer": "2.0.2",
     "node-mailjet": "6.0.11",
-    "nodemailer": "7.0.12",
+    "nodemailer": "7.0.13",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -131,20 +131,20 @@
     "@nestjs/cli": "11.0.16",
     "@nestjs/schematics": "11.0.9",
     "@nestjs/testing": "11.1.12",
-    "@swc/cli": "0.7.9",
-    "@swc/core": "1.15.10",
+    "@swc/cli": "0.7.10",
+    "@swc/core": "1.15.11",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
     "@types/express": "4.17.21",
     "@types/lodash": "4.17.23",
     "@types/multer": "2.0.0",
-    "@types/node": "25.0.10",
-    "@types/nodemailer": "7.0.5",
+    "@types/node": "25.2.0",
+    "@types/nodemailer": "7.0.9",
     "@types/passport": "1.0.17",
     "@types/supertest": "6.0.3",
-    "@typescript-eslint/eslint-plugin": "8.53.1",
-    "@typescript-eslint/parser": "8.53.1",
+    "@typescript-eslint/eslint-plugin": "8.54.0",
+    "@typescript-eslint/parser": "8.54.0",
     "@vitest/coverage-v8": "4.0.18",
     "@vitest/ui": "4.0.18",
     "ansi-colors": "4.1.3",
@@ -162,7 +162,7 @@
     "npm-watch": "0.13.0",
     "otpauth": "9.4.1",
     "pm2": "6.0.14",
-    "prettier": "3.7.4",
+    "prettier": "3.8.1",
     "pretty-quick": "4.2.2",
     "rimraf": "6.1.2",
     "supertest": "7.2.2",

package/src/core/modules/auth/core-auth.controller.ts

@@ -190,8 +190,8 @@ export class CoreAuthController {
    * Process cookies
    */
   protected processCookies(res: ResponseType, result: any) {
-    // Check if cookie handling is activated
-    if (this.configService.getFastButReadOnly('cookies')) {
+    // Check if cookie handling is activated (enabled by default, unless explicitly set to false)
+    if (this.configService.getFastButReadOnly('cookies') !== false) {
       // Set cookies
       if (!result || typeof result !== 'object') {
         res.cookie('token', '', { httpOnly: true });

package/src/core/modules/auth/core-auth.resolver.ts

@@ -172,8 +172,8 @@ export class CoreAuthResolver {
    * Process cookies
    */
   protected processCookies(ctx: { res: ResponseType }, result: any) {
-    // Check if cookie handling is activated
-    if (this.configService.getFastButReadOnly('cookies')) {
+    // Check if cookie handling is activated (enabled by default, unless explicitly set to false)
+    if (this.configService.getFastButReadOnly('cookies') !== false) {
       // Set cookies
       if (!result || typeof result !== 'object') {
         ctx.res.cookie('token', '', { httpOnly: true });

package/src/core/modules/better-auth/better-auth-token.service.ts

@@ -49,9 +49,10 @@ export class BetterAuthTokenService {
   /**
    * Extracts a token from the request's Authorization header or cookies.
    *
-   * Checks in order:
+   * Cookie priority (v11.12+):
    * 1. Authorization header (Bearer token)
-   * 2. Session cookies (iam.session_token, better-auth.session_token, token)
+   * 2. `{basePath}.session_token` (e.g., `iam.session_token`) - Better-Auth native
+   * 3. `token` - Legacy nest-server cookie
    *
    * @param request - HTTP request object with headers and cookies
    * @returns Token extraction result with token and source
@@ -70,14 +71,10 @@ export class BetterAuthTokenService {
       }
     }
 
-    // Try cookies
+    // Try cookies - Better-Auth native cookie first, then legacy
     if (request.cookies && this.betterAuthService) {
       const cookieName = this.betterAuthService.getSessionCookieName();
-      const token =
-        request.cookies[cookieName] ||
-        request.cookies['better-auth.session_token'] ||
-        request.cookies['token'] ||
-        undefined;
+      const token = request.cookies[cookieName] || request.cookies['token'] || undefined;
 
       if (token) {
         return { source: 'cookie', token };

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

@@ -4,6 +4,8 @@ import { betterAuth, BetterAuthPlugin } from 'better-auth';
 import { mongodbAdapter } from 'better-auth/adapters/mongodb';
 import { jwt, twoFactor } from 'better-auth/plugins';
 import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
 
 import { IBetterAuth } from '../../common/interfaces/server-options.interface';
 
@@ -27,10 +29,16 @@ function generateSecureSecret(): string {
 
 /**
  * Cached auto-generated secret for the current server instance.
- * Generated once at module load to ensure consistency within a single run.
+ * Generated once at a module load to ensure consistency within a single run.
  */
 let cachedAutoGeneratedSecret: null | string = null;
 
+/**
+ * Cached project app name for the current server instance.
+ * Read once from package.json to avoid repeated file reads.
+ */
+let cachedProjectAppName: null | string = null;
+
 /**
  * Options for creating a better-auth instance
  */
@@ -165,7 +173,7 @@ interface ValidationResult {
  */
 export function createBetterAuthInstance(options: CreateBetterAuthOptions): BetterAuthInstance | null {
   const logger = new Logger('BetterAuthConfig');
-  const { config, db, fallbackSecrets } = options;
+  const { config, db, fallbackSecrets, serverEnv } = options;
 
   // Return null only if better-auth is explicitly disabled
   // BetterAuth is enabled by default (zero-config)
@@ -184,7 +192,7 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
   // Normalize Passkey configuration with auto-detection from resolved URLs
   // This must happen BEFORE validation to allow graceful degradation
   // Passkey is now AUTO-ACTIVATED by default (not opt-in)
-  const passkeyNormalization = normalizePasskeyConfig(config, resolvedUrls);
+  const passkeyNormalization = normalizePasskeyConfig(config, { resolvedUrls, serverEnv });
 
   // Log passkey normalization warnings (info about auto-detection or disabled status)
   for (const warning of passkeyNormalization.warnings) {
@@ -205,15 +213,23 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
   }
 
   // Build configuration components (pass normalized passkey config and resolved URLs)
-  const plugins = buildPlugins(config, passkeyNormalization);
+  const plugins = buildPlugins(config, { passkeyNormalization, serverEnv });
   const socialProviders = buildSocialProviders(config);
   const trustedOrigins = buildTrustedOrigins(config, passkeyNormalization, resolvedUrls);
   const additionalFields = buildUserFields(config);
 
   // Build the base Better-Auth configuration
   // Use resolved baseUrl (with local defaults) or fallback
+  const basePath = config.basePath || '/iam';
+  // Cookie prefix derived from basePath (e.g., '/iam' → 'iam')
+  // This ensures Better-Auth looks for cookies like 'iam.session_token' instead of 'better-auth.session_token'
+  const cookiePrefix = basePath.replace(/^\//, '').replace(/\//g, '.');
+
   const betterAuthConfig: Record<string, unknown> = {
-    basePath: config.basePath || '/iam',
+    advanced: {
+      cookiePrefix,
+    },
+    basePath,
     baseURL: resolvedUrls.baseUrl || config.baseUrl || 'http://localhost:3000',
     database: mongodbAdapter(db),
     // Enable email/password authentication by default (required by Better-Auth 1.x)
@@ -257,9 +273,15 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
  * - `undefined`: Disabled (default)
  *
  * @param config - Better-auth configuration
- * @param passkeyNormalization - Normalized passkey configuration from normalizePasskeyConfig()
+ * @param options - Additional options
+ * @param options.passkeyNormalization - Normalized passkey configuration from normalizePasskeyConfig()
+ * @param options.serverEnv - Server environment for auto-detected app name suffix
  */
-function buildPlugins(config: IBetterAuth, passkeyNormalization: PasskeyNormalizationResult): BetterAuthPlugin[] {
+function buildPlugins(
+  config: IBetterAuth,
+  options: { passkeyNormalization: PasskeyNormalizationResult; serverEnv?: string },
+): BetterAuthPlugin[] {
+  const { passkeyNormalization, serverEnv } = options;
   const plugins: BetterAuthPlugin[] = [];
 
   // JWT Plugin for API client compatibility
@@ -285,7 +307,8 @@ function buildPlugins(config: IBetterAuth, passkeyNormalization: PasskeyNormaliz
     const twoFactorConfig = typeof config.twoFactor === 'object' ? config.twoFactor : {};
     plugins.push(
       twoFactor({
-        issuer: twoFactorConfig.appName || 'Nest Server',
+        // issuer: Use explicit config, or auto-detect from package.json with environment suffix
+        issuer: twoFactorConfig.appName || getProjectAppName(serverEnv),
       }),
     );
   }
@@ -447,6 +470,50 @@ function buildUserFields(config: IBetterAuth): Record<string, UserFieldConfig> {
   return coreFields;
 }
 
+/**
+ * Formats the environment name as a suffix.
+ * Only adds suffix for development/test environments.
+ *
+ * @example
+ * formatEnvSuffix('local')      // → '(Local)'
+ * formatEnvSuffix('development') // → '(Development)'
+ * formatEnvSuffix('test')       // → '(Test)'
+ * formatEnvSuffix('production') // → '' (no suffix for production)
+ * formatEnvSuffix(undefined)    // → ''
+ */
+function formatEnvSuffix(env?: string): string {
+  if (!env) return '';
+
+  // Don't add suffix for production
+  if (env === 'production' || env === 'prod') return '';
+
+  // Capitalize first letter
+  const formatted = env.charAt(0).toUpperCase() + env.slice(1).toLowerCase();
+  return `(${formatted})`;
+}
+
+/**
+ * Formats a package name to a human-readable display name.
+ * Converts kebab-case and snake_case to Title Case.
+ *
+ * @example
+ * formatProjectName('my-awesome-app')     // → 'My Awesome App'
+ * formatProjectName('@org/my-app')        // → 'My App'
+ * formatProjectName('nest_server_starter') // → 'Nest Server Starter'
+ */
+function formatProjectName(name: string): string {
+  // Remove scope (e.g., '@org/my-app' → 'my-app')
+  let formatted = name.replace(/^@[^/]+\//, '');
+
+  // Split by hyphens and underscores, capitalize each word
+  formatted = formatted
+    .split(/[-_]/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(' ');
+
+  return formatted;
+}
+
 /**
  * Gets or generates the fallback secret for development.
  * The secret is cached to ensure consistency during the server's lifetime.
@@ -458,6 +525,37 @@ function getAutoGeneratedSecret(): string {
   return cachedAutoGeneratedSecret;
 }
 
+/**
+ * Gets the project's app name from package.json.
+ *
+ * This function reads the `name` field from the project's package.json
+ * and formats it for display (converts a kebab-case to Title Case).
+ *
+ * Used as default for:
+ * - `betterAuth.passkey.rpName` (displayed in browser Passkey prompts)
+ * - `betterAuth.twoFactor.appName` (displayed in authenticator apps)
+ *
+ * @param serverEnv - Optional server environment to append as suffix (e.g., 'local' → '(Local)')
+ * @returns The formatted project name, or 'Nest Server' as fallback
+ *
+ * @example
+ * // package.json: { "name": "my-awesome-app" }
+ * getProjectAppName()           // → 'My Awesome App'
+ * getProjectAppName('local')    // → 'My Awesome App (Local)'
+ * getProjectAppName('test')     // → 'My Awesome App (Test)'
+ */
+function getProjectAppName(serverEnv?: string): string {
+  // Return cached value if available (without env suffix, will be added after)
+  if (cachedProjectAppName === null) {
+    cachedProjectAppName = readProjectNameFromPackageJson();
+  }
+
+  // Add environment suffix for non-production environments
+  // This helps developers distinguish Passkeys when running multiple projects locally
+  const envSuffix = formatEnvSuffix(serverEnv);
+  return envSuffix ? `${cachedProjectAppName} ${envSuffix}` : cachedProjectAppName;
+}
+
 /**
  * Checks if a secret has valid minimum length (32 characters)
  */
@@ -477,6 +575,28 @@ function isValidUrl(url: string): boolean {
   }
 }
 
+/**
+ * Reads the project name from package.json in the current working directory.
+ * Falls back to 'Nest Server' if package.json cannot be read or has no name.
+ */
+function readProjectNameFromPackageJson(): string {
+  const fallback = 'Nest Server';
+
+  try {
+    const packageJsonPath = path.join(process.cwd(), 'package.json');
+    const packageJsonContent = fs.readFileSync(packageJsonPath, 'utf-8');
+    const packageJson = JSON.parse(packageJsonContent);
+
+    if (packageJson.name && typeof packageJson.name === 'string') {
+      return formatProjectName(packageJson.name);
+    }
+  } catch {
+    // Ignore errors - use fallback
+  }
+
+  return fallback;
+}
+
 /**
  * Default URLs for local/test environments (local, ci, e2e)
  * These environments typically run on localhost and don't have a deployed domain.
@@ -598,10 +718,16 @@ function extractRpIdFromUrl(url: string): string {
  * - `trustedOrigins`: from config.trustedOrigins > [resolvedUrls.appUrl]
  *
  * @param config - Better-auth configuration
- * @param resolvedUrls - Resolved URLs from resolveUrls()
+ * @param options - Additional options
+ * @param options.resolvedUrls - Resolved URLs from resolveUrls()
+ * @param options.serverEnv - Server environment for auto-detected app name suffix
  * @returns Normalization result with enabled status, config, and warnings
  */
-function normalizePasskeyConfig(config: IBetterAuth, resolvedUrls: ResolvedUrls): PasskeyNormalizationResult {
+function normalizePasskeyConfig(
+  config: IBetterAuth,
+  options: { resolvedUrls: ResolvedUrls; serverEnv?: string },
+): PasskeyNormalizationResult {
+  const { resolvedUrls, serverEnv } = options;
   const warnings: string[] = [];
 
   // Check if Passkey is explicitly DISABLED
@@ -657,10 +783,11 @@ function normalizePasskeyConfig(config: IBetterAuth, resolvedUrls: ResolvedUrls)
   }
 
   // Build normalized config
+  // rpName: Use explicit config, or auto-detect from package.json with environment suffix
   const normalizedConfig: NormalizedPasskeyConfig = {
     origin: finalOrigin,
     rpId: finalRpId,
-    rpName: rawConfig.rpName || 'Nest Server',
+    rpName: rawConfig.rpName || getProjectAppName(serverEnv),
   };
 
   // Copy optional fields from explicit config
@@ -853,7 +980,7 @@ function validateConfig(
             errors.push(`Social provider '${name}' is missing clientSecret`);
           }
         } else {
-          // No credentials provided but provider is configured and not disabled
+          // No credentials provided, but the provider is configured and not disabled
           // This is likely a configuration mistake - warn the user
           warnings.push(
             `Social provider '${name}' is configured but missing both clientId and clientSecret. ` +

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

@@ -3,6 +3,7 @@ import { NextFunction, Request, Response } from 'express';
 
 import { isProduction } from '../../common/helpers/logging.helper';
 import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service';
+import { BetterAuthCookieHelper, createCookieHelper } from './core-better-auth-cookie.helper';
 import { extractSessionToken, sendWebResponse, signCookieValue, toWebRequest } from './core-better-auth-web.helper';
 import { CoreBetterAuthService } from './core-better-auth.service';
 
@@ -19,28 +20,17 @@ import { CoreBetterAuthService } from './core-better-auth.service';
  * All other paths (Passkey, 2FA, etc.) go directly to Better Auth's
  * native handler via this middleware for maximum compatibility.
  */
-const CONTROLLER_HANDLED_PATHS = [
-  '/sign-in/email',
-  '/sign-up/email',
-  '/sign-out',
-  '/session',
-];
+const CONTROLLER_HANDLED_PATHS = ['/sign-in/email', '/sign-up/email', '/sign-out', '/session'];
 
 /**
  * Passkey paths that generate challenges
  */
-const PASSKEY_GENERATE_PATHS = [
-  '/passkey/generate-register-options',
-  '/passkey/generate-authenticate-options',
-];
+const PASSKEY_GENERATE_PATHS = ['/passkey/generate-register-options', '/passkey/generate-authenticate-options'];
 
 /**
  * Passkey paths that verify challenges
  */
-const PASSKEY_VERIFY_PATHS = [
-  '/passkey/verify-registration',
-  '/passkey/verify-authentication',
-];
+const PASSKEY_VERIFY_PATHS = ['/passkey/verify-registration', '/passkey/verify-authentication'];
 
 /**
  * Middleware that forwards Better Auth API requests to the native Better Auth handler.
@@ -63,12 +53,36 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
   private readonly logger = new Logger(CoreBetterAuthApiMiddleware.name);
   private readonly isProd = isProduction();
   private loggedChallengeStorageMode = false;
+  private cookieHelper?: BetterAuthCookieHelper;
 
   constructor(
     private readonly betterAuthService: CoreBetterAuthService,
     @Optional() private readonly challengeService?: CoreBetterAuthChallengeService,
   ) {}
 
+  /**
+   * Gets or creates the cookie helper instance.
+   * Lazy initialization because betterAuthService may not be fully initialized in constructor.
+   *
+   * Note: Legacy cookie is not enabled in middleware since we can't access ConfigService.
+   * The middleware only needs to set the native Better-Auth cookie.
+   * Secret is required for cookie signing (Passkey/2FA).
+   */
+  private getCookieHelper(): BetterAuthCookieHelper {
+    if (!this.cookieHelper) {
+      const config = this.betterAuthService.getConfig();
+      this.cookieHelper = createCookieHelper(
+        this.betterAuthService.getBasePath(),
+        {
+          legacyCookieEnabled: false, // Middleware doesn't need legacy cookie
+          secret: config?.secret, // Required for cookie signing
+        },
+        this.logger,
+      );
+    }
+    return this.cookieHelper;
+  }
+
   /**
    * Check if database challenge storage should be used.
    * This is checked dynamically because the ChallengeService initializes in onModuleInit.
@@ -134,7 +148,9 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
       let challengeIdToDelete: string | undefined;
       if (isPasskeyVerify && this.challengeService) {
         const challengeId = req.body?.challengeId;
-        this.logger.debug(`Passkey verify: challengeId=${challengeId ? `${challengeId.substring(0, 8)}...` : 'MISSING'}, body keys=${Object.keys(req.body || {}).join(', ')}`);
+        this.logger.debug(
+          `Passkey verify: challengeId=${challengeId ? `${challengeId.substring(0, 8)}...` : 'MISSING'}, body keys=${Object.keys(req.body || {}).join(', ')}`,
+        );
         if (challengeId) {
           const verificationToken = await this.challengeService.getVerificationToken(challengeId);
           if (verificationToken) {
@@ -244,9 +260,19 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
         }
       }
 
-      // Clean up the used challenge mapping after verification (success or failure)
-      if (challengeIdToDelete && this.challengeService) {
+      // Clean up the used challenge mapping only after SUCCESSFUL verification
+      // On failure, keep the challenge so the user can retry with a different passkey
+      if (challengeIdToDelete && this.challengeService && response.ok) {
         await this.challengeService.deleteChallengeMapping(challengeIdToDelete);
+      } else if (challengeIdToDelete && !response.ok) {
+        this.logger.debug(`Keeping challenge mapping after failed verification (status=${response.status}) for retry`);
+      }
+
+      // For successful passkey verify-authentication, set session cookie
+      // Better-Auth's native handler sets its own cookies, but we extract and
+      // re-set them using our cookie helper for consistent cookie handling.
+      if (relativePath === '/passkey/verify-authentication' && response.ok) {
+        this.getCookieHelper().setSessionCookiesFromWebResponse(res, response);
       }
 
       // Convert Web Standard Response to Express response using shared helper
@@ -261,9 +287,7 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
 
       // Send error response if headers not sent
       if (!res.headersSent) {
-        const message = this.isProd
-          ? 'Authentication error'
-          : (error instanceof Error ? error.message : 'Unknown error');
+        const message = this.isProd ? 'Authentication error' : error instanceof Error ? error.message : 'Unknown error';
         res.status(500).json({
           error: 'Authentication handler error',
           message,