@lenne.tech/nest-server 11.15.2 → 11.15.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.15.2",
+  "version": "11.15.4",
   "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",
@@ -189,4 +189,4 @@
       "@apollo/protobufjs"
     ]
   }
-}
+}

package/src/core/common/interfaces/server-options.interface.ts

@@ -1681,6 +1681,38 @@ export interface ITusExpirationConfig {
   expiresIn?: string;
 }
 
+/**
+ * Configuration for cross-subdomain cookie sharing.
+ *
+ * When enabled, authentication cookies are set with a `domain` attribute
+ * so they are shared across all subdomains (e.g., `api.example.com` ↔ `ws.example.com`).
+ *
+ * Also configures Better-Auth's native `advanced.crossSubDomainCookies` setting
+ * and sets the domain on nest-server's own cookie helper.
+ *
+ * **Note:** This configures only the cookie `domain` attribute (browser sends cookies).
+ * For the server to accept cross-subdomain requests, `trustedOrigins` must also include
+ * the origins of all subdomains that make requests.
+ *
+ * @see IBetterAuthBase.crossSubDomainCookies
+ * @since 11.15.1
+ */
+export interface IBetterAuthCrossSubDomainCookiesConfig {
+  /**
+   * Cookie domain for cross-subdomain sharing.
+   * When omitted, auto-derived from `baseUrl` hostname.
+   *
+   * @example 'example.com' → cookies shared across *.example.com
+   */
+  domain?: string;
+
+  /**
+   * Whether cross-subdomain cookies are enabled.
+   * @default true (when object is provided)
+   */
+  enabled?: boolean;
+}
+
 /**
  * Base interface for better-auth configuration (shared properties)
  * This contains all properties except passkey and trustedOrigins,
@@ -1767,6 +1799,62 @@ interface IBetterAuthBase {
    */
   controller?: Type<any>;
 
+  /**
+   * Enable cross-subdomain cookie sharing.
+   *
+   * When your API and frontend (or other services) run on different subdomains
+   * (e.g., `api.example.com` and `app.example.com`), cookies are not shared by default.
+   * This option configures a cookie domain so authentication cookies work across subdomains.
+   *
+   * Accepts (Boolean Shorthand Pattern):
+   * - `undefined`: Disabled (default, backward compatible)
+   * - `true` or `{}`: Enable, domain auto-derived from `appUrl` or `baseUrl`
+   * - `{ domain: 'example.com' }`: Enable with explicit domain
+   * - `false` or `{ enabled: false }`: Disabled
+   *
+   * Domain auto-derivation priority:
+   * 1. `appUrl` hostname (e.g., `https://dev.example.com` → `dev.example.com`)
+   * 2. `baseUrl` hostname with `api.` prefix stripped (e.g., `https://api.dev.example.com` → `dev.example.com`)
+   * 3. `baseUrl` hostname as-is (if no `api.` prefix)
+   *
+   * When enabled, sets:
+   * - Better-Auth's native `advanced.crossSubDomainCookies`
+   * - Domain attribute on nest-server's own cookie helper
+   *
+   * **Important:** This only configures cookie sharing (browser sends cookies to subdomains).
+   * For cross-subdomain requests to be accepted by the server, `trustedOrigins` must also
+   * include the origins of all subdomains that make requests. `trustedOrigins` is auto-derived
+   * from `baseUrl` and `appUrl`, but additional subdomains must be added explicitly.
+   *
+   * @see trustedOrigins
+   * @default undefined (disabled)
+   * @since 11.15.1
+   *
+   * @example
+   * ```typescript
+   * // Recommended: appUrl + baseUrl for auto-derivation
+   * betterAuth: {
+   *   appUrl: 'https://dev.example.com',
+   *   baseUrl: 'https://api.dev.example.com',
+   *   crossSubDomainCookies: true,
+   *   // → domain = 'dev.example.com' (from appUrl)
+   * }
+   *
+   * // Without appUrl: strips api. prefix from baseUrl
+   * betterAuth: {
+   *   baseUrl: 'https://api.dev.example.com',
+   *   crossSubDomainCookies: true,
+   *   // → domain = 'dev.example.com'
+   * }
+   *
+   * // Explicit domain
+   * betterAuth: {
+   *   crossSubDomainCookies: { domain: 'example.com' },
+   * }
+   * ```
+   */
+  crossSubDomainCookies?: boolean | IBetterAuthCrossSubDomainCookiesConfig;
+
   /**
    * Email/password authentication configuration.
    * Enabled by default.
@@ -1881,9 +1969,16 @@ interface IBetterAuthBase {
    *   advanced: {
    *     cookiePrefix: 'my-app',
    *     useSecureCookies: true,
+   *     crossSubDomainCookies: {
+   *       domain: 'example.com', // Cookies shared across *.example.com
+   *     },
    *   },
    * }
    * ```
+   *
+   * **Note on `advanced` options:** The `advanced` object is deep-merged with internal defaults
+   * (e.g., `cookiePrefix` derived from `basePath`). You do not need to re-specify `cookiePrefix`
+   * when adding other `advanced` options like `crossSubDomainCookies`.
    */
   options?: Record<string, unknown>;
 
@@ -2125,11 +2220,24 @@ interface IBetterAuthWithoutPasskey extends IBetterAuthBase {
    * Optional when Passkey is disabled.
    * If not set, all origins are allowed (CORS `*`).
    *
+   * Auto-derived from `baseUrl` and `appUrl` when these are configured.
+   * Explicitly listed origins are merged with the auto-derived ones.
+   *
+   * **Important for cross-subdomain setups:** When using `crossSubDomainCookies`,
+   * cookies are shared across subdomains, but the server also needs to accept requests
+   * from those subdomains. `baseUrl` and `appUrl` are auto-added, but additional
+   * subdomains (e.g., `https://ws.example.com`) must be listed here explicitly.
+   *
+   * @see crossSubDomainCookies
+   *
    * @example
    * ```typescript
    * // Restrict origins even without Passkey
    * trustedOrigins: ['https://app.example.com'],
    *
+   * // Cross-subdomain: add extra subdomains beyond baseUrl/appUrl
+   * trustedOrigins: ['https://ws.example.com', 'https://admin.example.com'],
+   *
    * // Or leave undefined for open CORS
    * ```
    */
@@ -2172,6 +2280,16 @@ interface IBetterAuthWithPasskey extends IBetterAuthBase {
    * Passkey uses `credentials: 'include'` which requires explicit CORS origins.
    * Browsers don't allow wildcard `*` with credentials.
    *
+   * Auto-derived from `baseUrl` and `appUrl` when these are configured.
+   * Explicitly listed origins are merged with the auto-derived ones.
+   *
+   * **Important for cross-subdomain setups:** When using `crossSubDomainCookies`,
+   * cookies are shared across subdomains, but the server also needs to accept requests
+   * from those subdomains. `baseUrl` and `appUrl` are auto-added, but additional
+   * subdomains (e.g., `https://ws.example.com`) must be listed here explicitly.
+   *
+   * @see crossSubDomainCookies
+   *
    * @example
    * ```typescript
    * // Development
@@ -2179,6 +2297,9 @@ interface IBetterAuthWithPasskey extends IBetterAuthBase {
    *
    * // Production
    * trustedOrigins: process.env.TRUSTED_ORIGINS?.split(',') || [],
+   *
+   * // Cross-subdomain: add extra subdomains beyond baseUrl/appUrl
+   * trustedOrigins: ['https://ws.example.com', 'https://admin.example.com'],
    * ```
    */
   trustedOrigins: string[];

package/src/core/modules/better-auth/README.md

@@ -727,6 +727,67 @@ const config = {
 
 See [Better-Auth Options Reference](https://www.better-auth.com/docs/reference/options) for all available options.
 
+#### Cross-Subdomain Cookies (v11.15.1+)
+
+When your API and other services run on different subdomains (e.g., `api.example.com` and `ws.example.com`), authentication cookies need to be shared across subdomains.
+
+**Recommended: Boolean Shorthand (v11.15.1+)**
+
+```typescript
+const config = {
+  baseUrl: 'https://api.dev.example.com',
+  appUrl: 'https://dev.example.com',
+  betterAuth: {
+    crossSubDomainCookies: true, // Domain auto-derived → 'dev.example.com'
+  },
+};
+```
+
+**Domain resolution order:**
+
+1. `appUrl` hostname (if set) — e.g., `https://dev.example.com` → `dev.example.com`
+2. `baseUrl` hostname with `api.` prefix removed — e.g., `https://api.dev.example.com` → `dev.example.com`
+3. `baseUrl` hostname as-is (if no `api.` prefix) — e.g., `https://example.com` → `example.com`
+
+**Options:**
+
+| Value                           | Behavior                                                  |
+| ------------------------------- | --------------------------------------------------------- |
+| `undefined`                     | Disabled (default, backward compatible)                   |
+| `true` or `{}`                  | Enabled, domain auto-derived (see resolution order above) |
+| `{ domain: 'example.com' }`     | Enabled with explicit domain                              |
+| `false` or `{ enabled: false }` | Disabled                                                  |
+
+**Explicit domain:**
+
+```typescript
+betterAuth: {
+  crossSubDomainCookies: { domain: 'example.com' }, // Cookies shared across *.example.com
+}
+```
+
+This sets the `domain` attribute on all authentication cookies (both Better-Auth's native cookies and nest-server's cookie helper), allowing them to be sent to any subdomain of the configured domain.
+
+> **Important: `crossSubDomainCookies` + `trustedOrigins`**
+>
+> `crossSubDomainCookies` only configures cookie sharing (the `domain` attribute). Better-Auth also validates the **origin** of incoming requests via `trustedOrigins`. Both are required for cross-subdomain setups to work:
+>
+> - `crossSubDomainCookies` → Browser **sends** cookies to subdomains
+> - `trustedOrigins` → Server **accepts** requests from those subdomains
+>
+> `trustedOrigins` is auto-derived from `baseUrl` and `appUrl` (e.g., `https://api.example.com` and `https://example.com`). If you have **additional** subdomains (e.g., `https://ws.example.com`), add them explicitly:
+>
+> ```typescript
+> betterAuth: {
+>   crossSubDomainCookies: true,
+>   trustedOrigins: ['https://ws.example.com'], // Merged with auto-derived origins
+> }
+> ```
+
+> **Note:** For localhost environments, cross-subdomain cookies are automatically disabled even when `true` is set, since subdomains are not meaningful on localhost.
+
+**Legacy approach (still supported):** You can also configure cross-subdomain cookies via `options.advanced.crossSubDomainCookies` passthrough. However, the Boolean Shorthand above is recommended as it also sets the domain on nest-server's own cookie helper (middleware + controller).
+
 ## Plugins and Extensions
 
 Better-Auth provides a rich plugin ecosystem. This module uses a **hybrid approach**:
@@ -1290,23 +1351,24 @@ export class MyService {
 
 ### Available Methods
 
-| Method                               | Description                           |
-| ------------------------------------ | ------------------------------------- |
-| `isEnabled()`                        | Check if Better-Auth is enabled       |
-| `getInstance()`                      | Get the Better-Auth instance          |
-| `getApi()`                           | Get the Better-Auth API               |
-| `getConfig()`                        | Get the current configuration         |
-| `isJwtEnabled()`                     | Check if JWT plugin is enabled        |
-| `isTwoFactorEnabled()`               | Check if 2FA is enabled               |
-| `isPasskeyEnabled()`                 | Check if Passkey is enabled           |
-| `isSignUpEnabled()`                  | Check if sign-up is enabled           |
-| `getEnabledSocialProviders()`        | Get list of enabled social providers  |
-| `getBasePath()`                      | Get the base path for endpoints       |
-| `getBaseUrl()`                       | Get the base URL                      |
-| `getSession(req)`                    | Get current session from request      |
-| `revokeSession(token)`               | Revoke a session (logout)             |
-| `isSessionExpiringSoon(session, t?)` | Check if session is expiring soon     |
-| `getSessionTimeRemaining(session)`   | Get remaining session time in seconds |
+| Method                               | Description                                |
+| ------------------------------------ | ------------------------------------------ |
+| `isEnabled()`                        | Check if Better-Auth is enabled            |
+| `getInstance()`                      | Get the Better-Auth instance               |
+| `getApi()`                           | Get the Better-Auth API                    |
+| `getConfig()`                        | Get the current configuration              |
+| `isJwtEnabled()`                     | Check if JWT plugin is enabled             |
+| `isTwoFactorEnabled()`               | Check if 2FA is enabled                    |
+| `isPasskeyEnabled()`                 | Check if Passkey is enabled                |
+| `isSignUpEnabled()`                  | Check if sign-up is enabled                |
+| `getEnabledSocialProviders()`        | Get list of enabled social providers       |
+| `getBasePath()`                      | Get the base path for endpoints            |
+| `getBaseUrl()`                       | Get the base URL                           |
+| `getCookieDomain()`                  | Get resolved cross-subdomain cookie domain |
+| `getSession(req)`                    | Get current session from request           |
+| `revokeSession(token)`               | Revoke a session (logout)                  |
+| `isSessionExpiringSoon(session, t?)` | Check if session is expiring soon          |
+| `getSessionTimeRemaining(session)`   | Get remaining session time in seconds      |
 
 ## Security Integration
 

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

@@ -247,7 +247,14 @@ interface ValidationResult {
  * @returns Configured better-auth instance or null if not enabled
  * @throws Error if configuration validation fails
  */
-export function createBetterAuthInstance(options: CreateBetterAuthOptions): BetterAuthInstance | null {
+export interface CreateBetterAuthResult {
+  /** Resolved cookie domain for cross-subdomain cookies, or undefined if disabled */
+  cookieDomain: string | undefined;
+  /** The better-auth instance */
+  instance: BetterAuthInstance;
+}
+
+export function createBetterAuthInstance(options: CreateBetterAuthOptions): CreateBetterAuthResult | null {
   const logger = new Logger('BetterAuthConfig');
   const { config, db, fallbackSecrets, onEmailVerified, sendVerificationEmail, serverEnv } = options;
 
@@ -294,6 +301,12 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
   const trustedOrigins = buildTrustedOrigins(config, { passkeyNormalization, resolvedUrls });
   const additionalFields = buildUserFields(config);
 
+  // Resolve cross-subdomain cookies (Boolean Shorthand)
+  const crossSubDomain = resolveCrossSubDomainCookies(config, resolvedUrls);
+  if (crossSubDomain.enabled) {
+    logger.log(`Cross-subdomain cookies enabled (domain: ${crossSubDomain.domain})`);
+  }
+
   // Build email verification configuration
   const emailVerificationConfig = buildEmailVerificationConfig(config, { onEmailVerified, sendVerificationEmail });
 
@@ -307,6 +320,9 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
   const betterAuthConfig: Record<string, unknown> = {
     advanced: {
       cookiePrefix,
+      ...(crossSubDomain.enabled && {
+        crossSubDomainCookies: { domain: crossSubDomain.domain, enabled: true },
+      }),
     },
     basePath,
     baseURL: resolvedUrls.baseUrl || config.baseUrl || 'http://localhost:3000',
@@ -363,10 +379,13 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
     finalConfig = betterAuthConfig;
   }
 
-  // Create and return the better-auth instance
+  // Create and return the better-auth instance with resolved metadata
   // Type assertion needed for maximum flexibility - allows projects to use any Better-Auth option
 
-  return betterAuth(finalConfig as any);
+  return {
+    cookieDomain: crossSubDomain.enabled ? crossSubDomain.domain : undefined,
+    instance: betterAuth(finalConfig as any),
+  };
 }
 
 /**
@@ -1014,6 +1033,118 @@ function normalizePasskeyConfig(
   };
 }
 
+/**
+ * Result of cross-subdomain cookies resolution
+ */
+export interface ResolvedCrossSubDomainCookies {
+  /** The resolved cookie domain (e.g., 'example.com') */
+  domain: string | undefined;
+  /** Whether cross-subdomain cookies are enabled */
+  enabled: boolean;
+}
+
+/**
+ * Resolves the cross-subdomain cookies configuration.
+ *
+ * Follows the Boolean Shorthand Pattern:
+ * - `undefined` / `false` → disabled
+ * - `true` / `{}` → enabled, domain auto-derived from appUrl or baseUrl
+ * - `{ domain: 'x.com' }` → enabled with explicit domain
+ * - `{ enabled: false }` → disabled (allows pre-configuration)
+ *
+ * Domain auto-derivation priority:
+ * 1. Explicit `crossSubDomainCookies.domain`
+ * 2. `appUrl` hostname (e.g., `https://dev.example.com` → `dev.example.com`)
+ * 3. `baseUrl` hostname with `api.` prefix stripped (e.g., `https://api.dev.example.com` → `dev.example.com`)
+ * 4. `baseUrl` hostname as-is (if no `api.` prefix)
+ *
+ * The parent domain is preferred because cross-subdomain cookies need to cover
+ * both the API subdomain and the App domain (e.g., `api.dev.example.com` ↔ `dev.example.com`).
+ *
+ * @param config - Better-auth configuration
+ * @param resolvedUrls - Resolved URLs for domain auto-detection
+ * @returns Resolved cross-subdomain cookie settings
+ */
+export function resolveCrossSubDomainCookies(
+  config: IBetterAuth,
+  resolvedUrls: ResolvedUrls,
+): ResolvedCrossSubDomainCookies {
+  const csdc = config.crossSubDomainCookies;
+
+  // undefined or false → disabled
+  if (csdc === undefined || csdc === null || csdc === false) {
+    return { domain: undefined, enabled: false };
+  }
+
+  // Object with enabled: false → disabled (pre-configuration)
+  if (typeof csdc === 'object' && csdc.enabled === false) {
+    return { domain: undefined, enabled: false };
+  }
+
+  // true or {} or { domain: ... } → enabled
+  const explicitDomain = typeof csdc === 'object' ? csdc.domain : undefined;
+
+  if (explicitDomain) {
+    return { domain: explicitDomain, enabled: true };
+  }
+
+  // Auto-derive domain: prefer appUrl (= parent domain), then strip api. from baseUrl
+  const domain = deriveCookieDomainFromUrls(resolvedUrls.appUrl, resolvedUrls.baseUrl || config.baseUrl);
+  if (domain) {
+    return { domain, enabled: true };
+  }
+
+  // No usable URL available → cannot derive domain, disable
+  return { domain: undefined, enabled: false };
+}
+
+/**
+ * Derives the cookie domain from available URLs.
+ *
+ * For cross-subdomain cookies, the domain must be the PARENT domain that covers
+ * both the API and App subdomains. For example:
+ * - API: `api.dev.example.com`, App: `dev.example.com` → domain: `dev.example.com`
+ *
+ * Resolution:
+ * 1. Use appUrl hostname (if available and not localhost)
+ * 2. Strip `api.` prefix from baseUrl hostname
+ * 3. Use baseUrl hostname as-is
+ *
+ * Returns undefined for localhost (cross-subdomain not meaningful there).
+ */
+function deriveCookieDomainFromUrls(appUrl?: string, baseUrl?: string): string | undefined {
+  // Priority 1: appUrl hostname (this IS the parent domain in typical setups)
+  if (appUrl) {
+    try {
+      const hostname = new URL(appUrl).hostname;
+      if (hostname !== 'localhost' && hostname !== '127.0.0.1') {
+        return hostname;
+      }
+    } catch {
+      // Fall through to baseUrl
+    }
+  }
+
+  // Priority 2: baseUrl hostname with api. prefix stripped
+  if (baseUrl) {
+    try {
+      const hostname = new URL(baseUrl).hostname;
+      if (hostname === 'localhost' || hostname === '127.0.0.1') {
+        return undefined;
+      }
+      // Strip api. prefix to get parent domain
+      if (hostname.startsWith('api.')) {
+        return hostname.substring(4);
+      }
+      return hostname;
+    } catch {
+      return undefined;
+    }
+  }
+
+  return undefined;
+}
+
 function resolveUrls(options: CreateBetterAuthOptions): ResolvedUrls {
   const { config, serverAppUrl, serverBaseUrl, serverEnv } = options;
   const warnings: string[] = [];

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

@@ -74,6 +74,7 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
       this.cookieHelper = createCookieHelper(
         this.betterAuthService.getBasePath(),
         {
+          domain: this.betterAuthService.getCookieDomain(),
           legacyCookieEnabled: false, // Middleware doesn't need legacy cookie
           secret: config?.secret, // Required for cookie signing
         },

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

@@ -219,15 +219,11 @@ export class CoreBetterAuthController {
     // CRITICAL: Cookies must be signed for Passkey/2FA to work
     const betterAuthConfig = this.betterAuthService.getConfig();
 
-    // Read crossSubDomainCookies domain from Better Auth options
-    // This enables cookie sharing across subdomains (e.g., api.example.com → ws.example.com)
-    const crossSubDomainDomain = (betterAuthConfig?.options as any)?.advanced?.crossSubDomainCookies?.domain;
-
-    // Initialize cookie helper with Legacy Auth detection, secret, and optional domain
+    // Initialize cookie helper with Legacy Auth detection, secret, and optional cross-subdomain domain
     this.cookieHelper = createCookieHelper(
       this.betterAuthService.getBasePath(),
       {
-        domain: crossSubDomainDomain,
+        domain: this.betterAuthService.getCookieDomain(),
         legacyCookieEnabled: legacyAuthEnabled,
         secret: betterAuthConfig?.secret,
       },

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

@@ -19,7 +19,7 @@ import { ConfigService } from '../../common/services/config.service';
 import { RolesGuardRegistry } from '../auth/guards/roles-guard-registry';
 import { BetterAuthRolesGuard } from './better-auth-roles.guard';
 import { BetterAuthTokenService } from './better-auth-token.service';
-import { BetterAuthInstance, createBetterAuthInstance } from './better-auth.config';
+import { BetterAuthInstance, CreateBetterAuthResult, createBetterAuthInstance } from './better-auth.config';
 import { DefaultBetterAuthResolver } from './better-auth.resolver';
 import { CoreBetterAuthApiMiddleware } from './core-better-auth-api.middleware';
 import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service';
@@ -31,7 +31,7 @@ import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
 import { CoreBetterAuthController } from './core-better-auth.controller';
 import { CoreBetterAuthMiddleware } from './core-better-auth.middleware';
 import { CoreBetterAuthResolver } from './core-better-auth.resolver';
-import { BETTER_AUTH_CONFIG, CoreBetterAuthService } from './core-better-auth.service';
+import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, CoreBetterAuthService } from './core-better-auth.service';
 
 /**
  * Token for injecting the better-auth instance
@@ -235,6 +235,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   private static serviceInstance: CoreBetterAuthService | null = null;
   private static userMapperInstance: CoreBetterAuthUserMapper | null = null;
   private static tokenServiceInstance: BetterAuthTokenService | null = null;
+  private static resolvedCookieDomain: string | undefined = undefined;
 
   /**
    * Gets the controller class to use (custom or default)
@@ -277,6 +278,14 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     return this.tokenServiceInstance;
   }
 
+  /**
+   * Gets the resolved cookie domain for cross-subdomain cookie sharing.
+   * Returns the domain resolved during Better-Auth instance creation, or undefined if disabled.
+   */
+  static getCookieDomain(): string | undefined {
+    return this.resolvedCookieDomain;
+  }
+
   constructor(
     @Optional() private readonly betterAuthService?: CoreBetterAuthService,
     @Optional() private readonly rateLimiter?: CoreBetterAuthRateLimiter,
@@ -614,13 +623,15 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
 
             // Note: Secret validation is now handled in createBetterAuthInstance
             // with fallback to jwt.secret, jwt.refresh.secret, or auto-generation
-            this.authInstance = createBetterAuthInstance({
+            const result = createBetterAuthInstance({
               config,
               db,
               fallbackSecrets,
               onEmailVerified,
               sendVerificationEmail,
             });
+            this.authInstance = result?.instance ?? null;
+            this.resolvedCookieDomain = result?.cookieDomain;
 
             // Store a config copy with the resolved secret so that consumers
             // (CoreBetterAuthService, CoreBetterAuthController) can sign cookies.
@@ -645,17 +656,25 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           provide: BETTER_AUTH_CONFIG,
           useFactory: () => this.currentConfig,
         },
+        // Provide the resolved cookie domain for cross-subdomain cookie sharing
+        // IMPORTANT: Must depend on BETTER_AUTH_INSTANCE to ensure resolvedCookieDomain is set
+        {
+          inject: [BETTER_AUTH_INSTANCE],
+          provide: BETTER_AUTH_COOKIE_DOMAIN,
+          useFactory: () => this.resolvedCookieDomain,
+        },
         // CoreBetterAuthService needs to be a factory that explicitly depends on BETTER_AUTH_INSTANCE
         // to ensure proper initialization order
         {
-          inject: [BETTER_AUTH_INSTANCE, BETTER_AUTH_CONFIG, getConnectionToken()],
+          inject: [BETTER_AUTH_INSTANCE, BETTER_AUTH_CONFIG, getConnectionToken(), BETTER_AUTH_COOKIE_DOMAIN],
           provide: CoreBetterAuthService,
           useFactory: (
             authInstance: BetterAuthInstance | null,
             resolvedConfig: IBetterAuth | null,
             connection: Connection,
+            cookieDomain: string | undefined,
           ) => {
-            return new CoreBetterAuthService(authInstance, connection, resolvedConfig);
+            return new CoreBetterAuthService(authInstance, connection, resolvedConfig, undefined, cookieDomain);
           },
         },
         CoreBetterAuthUserMapper,
@@ -714,6 +733,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     // Lazy GraphQL driver: Reset service references
     this.serviceInstance = null;
     this.userMapperInstance = null;
+    this.resolvedCookieDomain = undefined;
     // Reset shared RolesGuard registry (shared with CoreAuthModule)
     RolesGuardRegistry.reset();
   }
@@ -856,6 +876,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
             };
 
             // Connection is now guaranteed to be established
+            let result: CreateBetterAuthResult | null;
             const db = connection.db;
             if (!db) {
               // Fallback to global mongoose if connection.db is not yet available
@@ -864,16 +885,18 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
               if (!globalDb) {
                 throw new Error('MongoDB database not available');
               }
-              this.authInstance = createBetterAuthInstance({
+              result = createBetterAuthInstance({
                 ...sharedInstanceOptions,
                 db: globalDb,
               });
             } else {
-              this.authInstance = createBetterAuthInstance({
+              result = createBetterAuthInstance({
                 ...sharedInstanceOptions,
                 db,
               });
             }
+            this.authInstance = result?.instance ?? null;
+            this.resolvedCookieDomain = result?.cookieDomain;
 
             // Store a config copy with the resolved secret (same as first forRoot variant)
             const fallbacks = options?.fallbackSecrets;
@@ -902,17 +925,25 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           provide: BETTER_AUTH_CONFIG,
           useFactory: () => this.currentConfig,
         },
+        // Provide the resolved cookie domain for cross-subdomain cookie sharing
+        // IMPORTANT: Must depend on BETTER_AUTH_INSTANCE to ensure resolvedCookieDomain is set
+        {
+          inject: [BETTER_AUTH_INSTANCE],
+          provide: BETTER_AUTH_COOKIE_DOMAIN,
+          useFactory: () => this.resolvedCookieDomain,
+        },
         // CoreBetterAuthService needs to be a factory that explicitly depends on BETTER_AUTH_INSTANCE
         // to ensure proper initialization order
         {
-          inject: [BETTER_AUTH_INSTANCE, BETTER_AUTH_CONFIG, getConnectionToken()],
+          inject: [BETTER_AUTH_INSTANCE, BETTER_AUTH_CONFIG, getConnectionToken(), BETTER_AUTH_COOKIE_DOMAIN],
           provide: CoreBetterAuthService,
           useFactory: (
             authInstance: BetterAuthInstance | null,
             resolvedConfig: IBetterAuth | null,
             connection: Connection,
+            cookieDomain: string | undefined,
           ) => {
-            return new CoreBetterAuthService(authInstance, connection, resolvedConfig);
+            return new CoreBetterAuthService(authInstance, connection, resolvedConfig, undefined, cookieDomain);
           },
         },
         CoreBetterAuthUserMapper,