@lenne.tech/nest-server 11.15.1 → 11.15.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.15.1",
+  "version": "11.15.3",
   "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",

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',
@@ -348,12 +364,28 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Bett
 
   // Merge with custom options passthrough
   // This allows projects to configure any Better-Auth option not explicitly defined
-  const finalConfig = config.options ? { ...betterAuthConfig, ...config.options } : betterAuthConfig;
+  // Deep-merge 'advanced' to preserve cookiePrefix when options.advanced is provided
+  let finalConfig: Record<string, unknown>;
+  if (config.options) {
+    const { advanced: optionsAdvanced, ...restOptions } = config.options as Record<string, unknown>;
+    finalConfig = { ...betterAuthConfig, ...restOptions };
+    if (optionsAdvanced && typeof optionsAdvanced === 'object') {
+      finalConfig.advanced = {
+        ...(betterAuthConfig.advanced as Record<string, unknown>),
+        ...(optionsAdvanced as Record<string, unknown>),
+      };
+    }
+  } else {
+    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),
+  };
 }
 
 /**
@@ -1001,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-cookie.helper.ts

@@ -24,6 +24,7 @@ export const AUTH_COOKIE_NAMES = {
  * Cookie options for authentication cookies.
  */
 export interface AuthCookieOptions {
+  domain?: string;
   httpOnly: boolean;
   maxAge?: number;
   sameSite: 'lax' | 'none' | 'strict';
@@ -36,6 +37,14 @@ export interface AuthCookieOptions {
 export interface BetterAuthCookieHelperConfig {
   /** Base path for Better-Auth (e.g., '/iam' or 'iam') */
   basePath: string;
+  /**
+   * Cookie domain for cross-subdomain cookie sharing.
+   * When set, cookies are sent to all subdomains of this domain.
+   * Read from betterAuth.options.advanced.crossSubDomainCookies.domain.
+   *
+   * @example 'example.com' → cookies shared across api.example.com, ws.example.com, etc.
+   */
+  domain?: string;
   /**
    * Enable legacy 'token' cookie for backwards compatibility with < 11.7.0.
    * Only needed when Legacy Auth (Passport) is also active.
@@ -116,11 +125,17 @@ export class BetterAuthCookieHelper {
    * @returns Cookie options with httpOnly, sameSite, and secure settings
    */
   getDefaultCookieOptions(): AuthCookieOptions {
-    return {
+    const options: AuthCookieOptions = {
       httpOnly: true,
       sameSite: 'lax',
       secure: process.env.NODE_ENV === 'production',
     };
+
+    if (this.config.domain) {
+      options.domain = this.config.domain;
+    }
+
+    return options;
   }
 
   /**
@@ -311,11 +326,12 @@ export class BetterAuthCookieHelper {
  */
 export function createCookieHelper(
   basePath: string,
-  options?: { legacyCookieEnabled?: boolean; secret?: string },
+  options?: { domain?: string; legacyCookieEnabled?: boolean; secret?: string },
   logger?: Logger,
 ): BetterAuthCookieHelper {
   return new BetterAuthCookieHelper({
     basePath,
+    domain: options?.domain,
     legacyCookieEnabled: options?.legacyCookieEnabled ?? false,
     logger,
     secret: options?.secret,

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

@@ -219,10 +219,11 @@ export class CoreBetterAuthController {
     // CRITICAL: Cookies must be signed for Passkey/2FA to work
     const betterAuthConfig = this.betterAuthService.getConfig();
 
-    // Initialize cookie helper with Legacy Auth detection and secret
+    // Initialize cookie helper with Legacy Auth detection, secret, and optional cross-subdomain domain
     this.cookieHelper = createCookieHelper(
       this.betterAuthService.getBasePath(),
       {
+        domain: this.betterAuthService.getCookieDomain(),
         legacyCookieEnabled: legacyAuthEnabled,
         secret: betterAuthConfig?.secret,
       },