@lenne.tech/nest-server 11.24.4 → 11.25.1

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

@@ -7,7 +7,7 @@ import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { IBetterAuth } from '../../common/interfaces/server-options.interface';
+import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface';
 
 /**
  * Type for better-auth instance with plugins
@@ -139,6 +139,14 @@ export interface CreateBetterAuthOptions {
    */
   serverBaseUrl?: string;
 
+  /**
+   * Server-level CORS configuration (from IServerOptions.cors).
+   * Used to align BetterAuth's trustedOrigins with the server-level CORS config.
+   *
+   * @since 11.25.0
+   */
+  serverCorsConfig?: boolean | ICorsConfig;
+
   /**
    * Server environment (from IServerOptions.env).
    * Used for local environment defaults.
@@ -298,7 +306,11 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
   // Build configuration components (pass normalized passkey config and resolved URLs)
   const plugins = buildPlugins(config, { passkeyNormalization, serverEnv });
   const socialProviders = buildSocialProviders(config);
-  const trustedOrigins = buildTrustedOrigins(config, { passkeyNormalization, resolvedUrls });
+  const trustedOrigins = buildTrustedOrigins(config, {
+    passkeyNormalization,
+    resolvedUrls,
+    serverCorsConfig: options.serverCorsConfig,
+  });
   const additionalFields = buildUserFields(config);
 
   // Resolve cross-subdomain cookies (Boolean Shorthand)
@@ -598,40 +610,66 @@ function buildSocialProviders(config: IBetterAuth): Record<string, SocialProvide
 /**
  * Builds the trusted origins array for CORS configuration.
  *
- * Behavior:
- * - If trustedOrigins is explicitly configured → use those origins
- * - If Passkey is enabled → use trustedOrigins from normalizePasskeyConfig()
- * - Fallback to resolved appUrl
- * - Otherwise → return undefined (allows all origins via Better-Auth's default)
+ * Behavior (in priority order):
+ * 1. Explicit betterAuth.trustedOrigins → use those (always takes precedence)
+ * 2. Server CORS disabled → empty array (BetterAuth CORS also disabled)
+ * 3. Server CORS allowAll → undefined (BetterAuth allows all origins)
+ * 4. Server CORS allowedOrigins → merge with appUrl/baseUrl
+ * 5. Passkey trustedOrigins → use from normalizePasskeyConfig()
+ * 6. Fallback to resolved appUrl
+ * 7. Otherwise → undefined (allows all origins via Better-Auth's default)
  *
  * @param config - Better-auth configuration
- * @param options - Passkey normalization and resolved URLs context
+ * @param options - Passkey normalization, resolved URLs, and server CORS context
  */
-function buildTrustedOrigins(
+export function buildTrustedOrigins(
   config: IBetterAuth,
   options: {
     passkeyNormalization: PasskeyNormalizationResult;
     resolvedUrls: ResolvedUrls;
+    serverCorsConfig?: boolean | ICorsConfig;
   },
 ): string[] | undefined {
-  const { passkeyNormalization, resolvedUrls } = options;
-  // If trustedOrigins is explicitly configured, use it
+  const { passkeyNormalization, resolvedUrls, serverCorsConfig } = options;
+
+  // 1. Explicit betterAuth.trustedOrigins always takes precedence (backward compatible)
   if (config.trustedOrigins?.length) {
     return config.trustedOrigins;
   }
 
-  // If Passkey is enabled, use the trustedOrigins from normalization
+  // 2. Server CORS disabled → BetterAuth CORS also disabled
+  if (serverCorsConfig === false || (typeof serverCorsConfig === 'object' && serverCorsConfig?.enabled === false)) {
+    return [];
+  }
+
+  // 3. Server CORS allowAll → BetterAuth allows all origins
+  if (typeof serverCorsConfig === 'object' && serverCorsConfig?.allowAll) {
+    return undefined;
+  }
+
+  // 4. Server allowedOrigins → merge with appUrl/baseUrl.
+  // Order (appUrl, baseUrl, allowedOrigins) mirrors buildCorsConfig() in cookies.helper.ts
+  // for consistency — the final Set is order-equivalent, but the array order helps readers
+  // trace which value came from which source.
+  if (typeof serverCorsConfig === 'object' && serverCorsConfig?.allowedOrigins?.length) {
+    const origins: string[] = [];
+    if (resolvedUrls.appUrl) origins.push(resolvedUrls.appUrl);
+    if (resolvedUrls.baseUrl) origins.push(resolvedUrls.baseUrl);
+    origins.push(...serverCorsConfig.allowedOrigins);
+    return [...new Set(origins)];
+  }
+
+  // 5. If Passkey is enabled, use the trustedOrigins from normalization
   if (passkeyNormalization.enabled && passkeyNormalization.trustedOrigins?.length) {
     return passkeyNormalization.trustedOrigins;
   }
 
-  // Fallback to resolved appUrl (for CORS even without Passkey)
+  // 6. Fallback to resolved appUrl (for CORS even without Passkey)
   if (resolvedUrls.appUrl) {
     return [resolvedUrls.appUrl];
   }
 
-  // Otherwise, let Better-Auth handle CORS with its default behavior
-  // This allows all origins for requests without credentials
+  // 7. Otherwise, let Better-Auth handle CORS with its default behavior
   return undefined;
 }
 

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

@@ -2,6 +2,7 @@ import { 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 { extractSessionToken, sendWebResponse, signCookieValue, toWebRequest } from './core-better-auth-web.helper';
@@ -64,17 +65,19 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
    * 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).
+   * Note: Legacy cookie is not enabled in middleware. The middleware only needs to set
+   * the native Better-Auth cookie. Secret is required for cookie signing (Passkey/2FA).
+   * `env` is read via the frozen ConfigService snapshot so the `secure` flag covers staging.
    */
   private getCookieHelper(): BetterAuthCookieHelper {
     if (!this.cookieHelper) {
       const config = this.betterAuthService.getConfig();
+      const env = ConfigService.configFastButReadOnly?.env as string | undefined;
       this.cookieHelper = createCookieHelper(
         this.betterAuthService.getBasePath(),
         {
           domain: this.betterAuthService.getCookieDomain(),
+          env,
           legacyCookieEnabled: false, // Middleware doesn't need legacy cookie
           secret: config?.secret, // Required for cookie signing
         },

package/src/core/modules/better-auth/core-better-auth-cookie.helper.ts

@@ -1,6 +1,7 @@
 import { Logger } from '@nestjs/common';
 import { Response } from 'express';
 
+import { isProductionLikeEnv } from '../../common/helpers/cookies.helper';
 import { signCookieValue } from './core-better-auth-web.helper';
 
 /**
@@ -45,6 +46,14 @@ export interface BetterAuthCookieHelperConfig {
    * @example 'example.com' → cookies shared across api.example.com, ws.example.com, etc.
    */
   domain?: string;
+  /**
+   * App-level environment from `IServerOptions.env` (e.g. `'production'`, `'staging'`).
+   * Used to derive the `secure` flag for cookies in conjunction with `process.env.NODE_ENV`.
+   *
+   * @since 11.25.0 Covers staging deployments where `config.env === 'staging'` but
+   *                `NODE_ENV !== 'production'`.
+   */
+  env?: string;
   /**
    * Enable legacy 'token' cookie for backwards compatibility with < 11.7.0.
    * Only needed when Legacy Auth (Passport) is also active.
@@ -122,13 +131,17 @@ export class BetterAuthCookieHelper {
   /**
    * Gets the default cookie options for authentication cookies.
    *
+   * The `secure` flag is `true` when either `config.env` is production-like
+   * (`production` / `staging`) or `NODE_ENV === 'production'`. This covers
+   * staging deployments where only one of the two signals is set.
+   *
    * @returns Cookie options with httpOnly, sameSite, and secure settings
    */
   getDefaultCookieOptions(): AuthCookieOptions {
     const options: AuthCookieOptions = {
       httpOnly: true,
       sameSite: 'lax',
-      secure: process.env.NODE_ENV === 'production',
+      secure: isProductionLikeEnv(this.config.env),
     };
 
     if (this.config.domain) {
@@ -286,18 +299,28 @@ export class BetterAuthCookieHelper {
   }
 
   /**
-   * Processes a result object by setting appropriate cookies and removing token from body.
+   * Processes a result object by setting appropriate cookies and optionally keeping token in body.
    *
    * This method handles the common pattern of:
    * 1. Setting cookies if cookie handling is enabled
-   * 2. Removing the token from the response body (it's now in cookies)
+   * 2. Removing the token from the response body (unless exposeTokenInBody is true)
+   *
+   * When exposeTokenInBody is false (default), the token is removed from the response
+   * body because the httpOnly cookie provides XSS protection — exposing the token in
+   * the body would negate this security benefit.
    *
    * @param res - Express Response object
    * @param result - The result object to process (modified in place)
    * @param cookiesEnabled - Whether cookie handling is enabled (from config)
+   * @param exposeTokenInBody - Whether to keep the token in the response body (default: false)
    * @returns The modified result (same reference as input)
    */
-  processAuthResult<T extends CookieProcessingResult>(res: Response, result: T, cookiesEnabled: boolean): T {
+  processAuthResult<T extends CookieProcessingResult>(
+    res: Response,
+    result: T,
+    cookiesEnabled: boolean,
+    exposeTokenInBody: boolean = false,
+  ): T {
     if (!cookiesEnabled) {
       return result;
     }
@@ -306,8 +329,10 @@ export class BetterAuthCookieHelper {
       // Set cookies
       this.setSessionCookies(res, result.token);
 
-      // Remove token from response body (it's now in cookies)
-      delete result.token;
+      // Remove token from response body unless exposeTokenInBody is enabled
+      if (!exposeTokenInBody) {
+        delete result.token;
+      }
     }
 
     return result;
@@ -326,12 +351,13 @@ export class BetterAuthCookieHelper {
  */
 export function createCookieHelper(
   basePath: string,
-  options?: { domain?: string; legacyCookieEnabled?: boolean; secret?: string },
+  options?: { domain?: string; env?: string; legacyCookieEnabled?: boolean; secret?: string },
   logger?: Logger,
 ): BetterAuthCookieHelper {
   return new BetterAuthCookieHelper({
     basePath,
     domain: options?.domain,
+    env: options?.env,
     legacyCookieEnabled: options?.legacyCookieEnabled ?? false,
     logger,
     secret: options?.secret,

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

@@ -27,6 +27,8 @@ import { Request, Response } from 'express';
 
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
+import { isCookiesEnabled, isExposeTokenInBodyEnabled } from '../../common/helpers/cookies.helper';
+import type { ICookiesConfig } from '../../common/interfaces/server-options.interface';
 import { maskEmail, maskToken } from '../../common/helpers/logging.helper';
 import { ConfigService } from '../../common/services/config.service';
 import { ErrorCode } from '../error-code/error-codes';
@@ -224,6 +226,7 @@ export class CoreBetterAuthController {
       this.betterAuthService.getBasePath(),
       {
         domain: this.betterAuthService.getCookieDomain(),
+        env: this.configService.getFastButReadOnly<string>('env'),
         legacyCookieEnabled: legacyAuthEnabled,
         secret: betterAuthConfig?.secret,
       },
@@ -828,19 +831,25 @@ export class CoreBetterAuthController {
     result: CoreBetterAuthResponse,
     sessionToken?: string,
   ): CoreBetterAuthResponse {
-    const cookiesEnabled = this.configService.getFastButReadOnly('cookies') !== false;
+    // Cookies config is read per-request (not cached in the constructor) because tests
+    // and runtime config changes (e.g. `ConfigService.setProperty('cookies', ...)`) must
+    // take effect immediately. The `getFastButReadOnly` call is a single property access
+    // on a frozen snapshot — overhead is negligible.
+    const cookiesConfig = this.configService.getFastButReadOnly<boolean | ICookiesConfig>('cookies');
+    const cookiesEnabled = isCookiesEnabled(cookiesConfig);
+    const exposeTokenInBody = isExposeTokenInBodyEnabled(cookiesConfig);
 
     // If a specific session token is provided, use it directly
     if (sessionToken && cookiesEnabled) {
       this.cookieHelper.setSessionCookies(res, sessionToken, result.session?.id);
-      if (result.token) {
+      if (!exposeTokenInBody && result.token) {
         delete result.token;
       }
       return result;
     }
 
     // Otherwise, use the cookie helper's standard processing
-    return this.cookieHelper.processAuthResult(res, result, cookiesEnabled);
+    return this.cookieHelper.processAuthResult(res, result, cookiesEnabled, exposeTokenInBody);
   }
 
   /**

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

@@ -13,7 +13,7 @@ import { APP_GUARD } from '@nestjs/core';
 import { getConnectionToken } from '@nestjs/mongoose';
 import mongoose, { Connection } from 'mongoose';
 
-import { IBetterAuth } from '../../common/interfaces/server-options.interface';
+import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface';
 import { BrevoService } from '../../common/services/brevo.service';
 import { ConfigService } from '../../common/services/config.service';
 import { RolesGuardRegistry } from '../auth/guards/roles-guard-registry';
@@ -161,6 +161,14 @@ export interface CoreBetterAuthModuleOptions {
    */
   serverBaseUrl?: string;
 
+  /**
+   * Server-level CORS configuration (from IServerOptions.cors).
+   * Used to align BetterAuth's trustedOrigins with the server-level CORS config.
+   *
+   * @since 11.25.0
+   */
+  serverCorsConfig?: boolean | ICorsConfig;
+
   /**
    * Server environment (from IServerOptions.env).
    * Used for local environment defaults:
@@ -452,6 +460,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       resolver,
       serverAppUrl,
       serverBaseUrl,
+      serverCorsConfig,
       serverEnv,
     } = options;
 
@@ -535,10 +544,14 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     // Always use deferred initialization to ensure MongoDB is ready
     // This prevents timing issues during application startup
     // Pass server-level URLs for Passkey auto-detection (using effective values from ConfigService fallback)
+    // Auto-detect server CORS config from ConfigService if not explicitly provided
+    const effectiveServerCorsConfig = serverCorsConfig ?? globalConfig?.cors;
+
     this.cachedDynamicModule = this.createDeferredModule(config, {
       fallbackSecrets: effectiveFallbackSecrets,
       serverAppUrl: effectiveServerAppUrl,
       serverBaseUrl: effectiveServerBaseUrl,
+      serverCorsConfig: effectiveServerCorsConfig,
       serverEnv: effectiveServerEnv,
     });
     return this.cachedDynamicModule;
@@ -816,6 +829,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       fallbackSecrets?: (string | undefined)[];
       serverAppUrl?: string;
       serverBaseUrl?: string;
+      serverCorsConfig?: boolean | ICorsConfig;
       serverEnv?: string;
     },
   ): DynamicModule {
@@ -872,6 +886,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
               sendVerificationEmail,
               serverAppUrl: options?.serverAppUrl,
               serverBaseUrl: options?.serverBaseUrl,
+              serverCorsConfig: options?.serverCorsConfig,
               serverEnv: options?.serverEnv,
             };
 

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

@@ -4,8 +4,9 @@ import { Request } from 'express';
 import { importJWK, jwtVerify } from 'jose';
 import { Connection } from 'mongoose';
 
+import { shouldConvertSessionTokenToJwt } from '../../common/helpers/cookies.helper';
 import { maskEmail, maskToken } from '../../common/helpers/logging.helper';
-import { IBetterAuth } from '../../common/interfaces/server-options.interface';
+import { IBetterAuth, ICookiesConfig } from '../../common/interfaces/server-options.interface';
 import { ConfigService } from '../../common/services/config.service';
 import { ErrorCode } from '../error-code/error-codes';
 import { BetterAuthInstance } from './better-auth.config';
@@ -288,20 +289,32 @@ export class CoreBetterAuthService implements OnModuleInit {
   // ===================================================================================================================
 
   /**
-   * Resolves a session token to a JWT when cookies are disabled and JWT is enabled.
+   * Resolves a session token to a JWT when JWT conversion is needed.
    *
-   * When cookies are disabled, BetterAuth's internal API may return a session token
-   * (opaque string like "TVRRtiL19h9q...") instead of a JWT. This method detects
-   * non-JWT tokens and converts them to proper JWTs via the BetterAuth JWT plugin.
+   * JWT conversion is performed when:
+   * - Cookies are disabled (JWT-only mode) — clients need a JWT in the response body
+   * - exposeTokenInBody is true — clients need a JWT alongside cookies for parallel auth
+   *
+   * When cookies are enabled WITHOUT exposeTokenInBody, the token stays as a session token
+   * (it's delivered via cookie, not the response body).
+   *
+   * On conversion failure (BetterAuth JWT plugin not warmed up, transient error, etc.),
+   * this method returns `undefined` rather than the raw session token. Returning the raw
+   * session token in a body meant for a JWT would expose a database-backed opaque identifier
+   * outside the httpOnly cookie boundary (see SEC-005, v11.25.0). Callers must handle
+   * `undefined` by forcing client retry / re-authentication.
    *
    * @param token - The token from BetterAuth response (may be session token or JWT)
-   * @returns A proper JWT token, or the original token if conversion is not needed/possible
+   * @returns A proper JWT, the original token if conversion is not needed, or `undefined`
+   *          when conversion was needed but failed.
    */
   async resolveJwtToken(token: string | undefined): Promise<string | undefined> {
     if (!token) return undefined;
 
-    const cookiesEnabled = ConfigService.configFastButReadOnly?.cookies !== false;
-    if (cookiesEnabled || !this.isJwtEnabled()) {
+    const cookiesConfig = ConfigService.configFastButReadOnly?.cookies as boolean | ICookiesConfig | undefined;
+
+    // Skip conversion when cookies-only mode or JWT plugin disabled
+    if (!shouldConvertSessionTokenToJwt(cookiesConfig, this.isJwtEnabled())) {
       return token;
     }
 
@@ -325,8 +338,11 @@ export class CoreBetterAuthService implements OnModuleInit {
       return jwt;
     }
 
-    this.logger.warn('Failed to resolve session token to JWT - returning session token as fallback');
-    return token;
+    // Do NOT return the raw session token as fallback — that would leak an opaque
+    // DB identifier into the response body where clients expect a JWT. Force the
+    // caller to either retry or surface an auth error to the client.
+    this.logger.warn('Failed to resolve session token to JWT - returning undefined to avoid session token exposure');
+    return undefined;
   }
 
   /**

package/src/core/modules/migrate/templates/migration-project.template.ts

@@ -1,6 +1,5 @@
 import { getDb, uploadFileToGridFS } from '@lenne.tech/nest-server';
 import { Db, ObjectId } from 'mongodb';
-import config from '../src/config.env';
 
 /**
  * Migration template for nest-server projects
@@ -11,9 +10,24 @@ import config from '../src/config.env';
  * Available helpers:
  * - getDb(uri): Get MongoDB connection
  * - uploadFileToGridFS(uri, filePath, options): Upload file to GridFS
+ *
+ * MongoDB URI resolution (in order):
+ * 1. config.env.ts (local development via ts-node)
+ * 2. NSC__MONGOOSE__URI environment variable (Docker production)
  */
 
-const MONGO_URL = config.mongoose.uri;
+let MONGO_URL: string;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const config = require('../src/config.env');
+  MONGO_URL = (config.default || config).mongoose.uri;
+} catch {
+  // Fallback for Docker production where config.env.ts is not available as TypeScript source
+  if (!process.env.NSC__MONGOOSE__URI) {
+    throw new Error('MongoDB URI not available. Set NSC__MONGOOSE__URI or ensure config.env.ts is loadable.');
+  }
+  MONGO_URL = process.env.NSC__MONGOOSE__URI;
+}
 
 /**
  * Run migration

package/src/core.module.ts

@@ -12,7 +12,18 @@ import { CheckResponseInterceptor } from './core/common/interceptors/check-respo
 import { CheckSecurityInterceptor } from './core/common/interceptors/check-security.interceptor';
 import { ResponseModelInterceptor } from './core/common/interceptors/response-model.interceptor';
 import { TranslateResponseInterceptor } from './core/common/interceptors/translate-response.interceptor';
-import { ICoreModuleOverrides, IServerOptions } from './core/common/interfaces/server-options.interface';
+import {
+  assertCookiesProductionSafe,
+  buildCorsConfig,
+  isCookiesEnabled,
+  isCorsDisabled,
+  isExposeTokenInBodyEnabled,
+} from './core/common/helpers/cookies.helper';
+import {
+  ICookiesConfig,
+  ICoreModuleOverrides,
+  IServerOptions,
+} from './core/common/interfaces/server-options.interface';
 import { RequestContextMiddleware } from './core/common/middleware/request-context.middleware';
 import { MapAndValidatePipe } from './core/common/pipes/map-and-validate.pipe';
 import { ComplexityPlugin } from './core/common/plugins/complexity.plugin';
@@ -169,14 +180,15 @@ export class CoreModule implements NestModule {
       ? (authModuleOrUndefined as ICoreModuleOverrides | undefined)
       : overridesOrUndefined;
 
-    // Process config
-    let cors = {};
-    if (options?.cookies) {
-      cors = {
-        credentials: true,
-        origin: true,
-      };
-    }
+    // Guard against unsafe cookie configuration in production/staging.
+    // Throws if `cookies.exposeTokenInBody: true` is set in a production-like environment.
+    assertCookiesProductionSafe(options?.cookies, options?.env);
+
+    // Process CORS config (unified across GraphQL, REST, and BetterAuth).
+    // When CORS is explicitly disabled, pass `false` to Apollo — not `{}`.
+    // Apollo treats `cors: {}` as "open CORS with no credentials" (via Express cors() defaults),
+    // so we must distinguish the "disabled" case from the "no origins configured" case.
+    const cors: false | object = isCorsDisabled(options?.cors) ? false : buildCorsConfig(options);
 
     // Determine if GraphQL is enabled (false means explicitly disabled)
     const isGraphQlEnabled = options.graphQl !== false;
@@ -421,6 +433,8 @@ export class CoreModule implements NestModule {
             // When env: 'local', defaults are: baseUrl=localhost:3000, appUrl=localhost:3001
             serverAppUrl: config.appUrl,
             serverBaseUrl: config.baseUrl,
+            // Pass server-level CORS config so BetterAuth trustedOrigins aligns
+            serverCorsConfig: config.cors,
             serverEnv: config.env,
           }),
         );
@@ -472,7 +486,7 @@ export class CoreModule implements NestModule {
    * Uses CoreBetterAuthService for subscription authentication via JWT tokens.
    * This is the recommended mode for new projects.
    */
-  private static buildIamOnlyGraphQlDriver(cors: object, options: Partial<IServerOptions>) {
+  private static buildIamOnlyGraphQlDriver(cors: false | object, options: Partial<IServerOptions>) {
     // This method is only called when graphQl !== false, extract config with type narrowing
     const graphQlOpts = typeof options?.graphQl === 'object' ? options.graphQl : undefined;
     return {
@@ -569,7 +583,7 @@ export class CoreModule implements NestModule {
    * This is safe because `onConnect` is only called when a WebSocket connection is made,
    * which happens after all modules are initialized.
    */
-  private static buildLazyIamGraphQlDriver(cors: object, options: Partial<IServerOptions>) {
+  private static buildLazyIamGraphQlDriver(cors: false | object, options: Partial<IServerOptions>) {
     // This method is only called when graphQl !== false, extract config with type narrowing
     const graphQlOpts = typeof options?.graphQl === 'object' ? options.graphQl : undefined;
     return {
@@ -675,7 +689,7 @@ export class CoreModule implements NestModule {
   private static buildLegacyGraphQlDriver(
     AuthService: any,
     AuthModule: any,
-    cors: object,
+    cors: false | object,
     options: Partial<IServerOptions>,
   ) {
     // This method is only called when graphQl !== false, extract config with type narrowing
@@ -746,4 +760,18 @@ export class CoreModule implements NestModule {
         ),
     };
   }
+
+  /**
+   * @deprecated Use `isCookiesEnabled` from `core/common/helpers/cookies.helper` instead.
+   */
+  static isCookiesEnabled(cookies: boolean | ICookiesConfig | undefined): boolean {
+    return isCookiesEnabled(cookies);
+  }
+
+  /**
+   * @deprecated Use `isExposeTokenInBodyEnabled` from `core/common/helpers/cookies.helper` instead.
+   */
+  static isExposeTokenInBodyEnabled(cookies: boolean | ICookiesConfig | undefined): boolean {
+    return isExposeTokenInBodyEnabled(cookies);
+  }
 }

package/src/index.ts

@@ -30,6 +30,7 @@ export * from './core/common/filters/http-exception-log.filter';
 export * from './core/common/helpers/common.helper';
 export * from './core/common/helpers/config.helper';
 export * from './core/common/helpers/context.helper';
+export * from './core/common/helpers/cookies.helper';
 export * from './core/common/helpers/db.helper';
 export * from './core/common/helpers/decorator.helper';
 export * from './core/common/helpers/file.helper';

package/src/main.ts

@@ -7,6 +7,7 @@ import cookieParser = require('cookie-parser');
 
 import envConfig from './config.env';
 import { FilterArgs } from './core/common/args/filter.args';
+import { buildCorsConfig, isCookiesEnabled, isCorsDisabled } from './core/common/helpers/cookies.helper';
 import { HttpExceptionLogFilter } from './core/common/filters/http-exception-log.filter';
 import { CorePersistenceModel } from './core/common/models/core-persistence.model';
 import { CoreAuthModel } from './core/modules/auth/core-auth.model';
@@ -47,9 +48,18 @@ async function bootstrap() {
     server.use(compression(compressionOptions));
   }
 
-  // Cookie handling
-  if (envConfig.cookies) {
-    server.use(cookieParser());
+  // Cookie handling (enabled by default, disable with cookies: false)
+  // Pass a signing secret (if configured) to cookieParser so signed cookies can be
+  // verified via req.signedCookies. BetterAuth signs its own session cookies
+  // independently via HMAC, but the Express layer still benefits from a secret —
+  // Legacy Auth cookies and any custom signed cookies rely on this.
+  //
+  // Fallback chain: jwt.secret → betterAuth.secret (IAM-only mode) → unsigned
+  const cookiesEnabled = isCookiesEnabled(envConfig.cookies);
+  if (cookiesEnabled) {
+    const betterAuthSecret = typeof envConfig.betterAuth === 'object' ? envConfig.betterAuth?.secret : undefined;
+    const cookieSecret = envConfig.jwt?.secret || betterAuthSecret;
+    server.use(cookieSecret ? cookieParser(cookieSecret) : cookieParser());
   }
 
   // Asset directory
@@ -59,8 +69,25 @@ async function bootstrap() {
   server.setBaseViewsDir(envConfig.templates.path);
   server.setViewEngine(envConfig.templates.engine);
 
-  // Enable cors to allow requests from other domains
-  server.enableCors();
+  // Enable CORS (unified with GraphQL and BetterAuth via shared buildCorsConfig helper).
+  //
+  // Three cases:
+  // 1. CORS explicitly disabled (`cors: false` or `cors.enabled: false`) → skip `enableCors()`
+  //    entirely. No CORS headers emitted. Same-origin requests still work.
+  // 2. Origins resolvable (appUrl/baseUrl/allowedOrigins or allowAll) → use the computed options.
+  // 3. Cookies disabled → permissive `enableCors()` without credentials (backward-compatible).
+  if (isCorsDisabled(envConfig.cors)) {
+    // Case 1 — CORS explicitly disabled. Do nothing.
+  } else {
+    const corsOptions = buildCorsConfig(envConfig);
+    if (Object.keys(corsOptions).length > 0) {
+      server.enableCors(corsOptions); // Case 2
+    } else if (!cookiesEnabled) {
+      server.enableCors(); // Case 3
+    }
+    // else: cookies enabled but no origins resolvable → secure default (no `enableCors()` call
+    // to avoid open CORS with credentials). Callers should configure appUrl/baseUrl/allowedOrigins.
+  }
 
   // Swagger documentation
   const config = new DocumentBuilder()

package/src/test/test.helper.ts

@@ -78,6 +78,19 @@ export interface TestGraphQLOptions {
    */
   convertEnums?: boolean | string[];
 
+  /**
+   * Cookies for the request. Three usage modes (same as `TestRestOptions.cookies`):
+   * - string (plain token without = or ;): Auto-detected as session token
+   *   and converted via `buildBetterAuthCookies()` to all relevant cookie names
+   *   (iam.session_token, token)
+   * - string (with = or ;): Used as-is as a cookie string
+   * - Record<string, string>: Key-value pairs joined into a cookie string
+   *
+   * Use this for cookie-based authentication (default since 11.25.0). Can be
+   * combined with `token` — both headers will be sent.
+   */
+  cookies?: Record<string, string> | string;
+
   /**
    * Count of subscription messages, specifies how many messages are to be received on subscription
    */
@@ -305,7 +318,7 @@ export class TestHelper {
     };
 
     // Init vars
-    const { language, log, logError, statusCode, token, variables } = config;
+    const { cookies, language, log, logError, statusCode, token, variables } = config;
 
     // Init
     let query = '';
@@ -402,6 +415,7 @@ export class TestHelper {
 
     // Request configuration
     const requestConfig: any = {
+      cookies,
       method: 'POST',
       payload: { query },
       url: '/graphql',