@lenne.tech/nest-server 11.24.4 → 11.25.1

package/src/core/common/helpers/cookies.helper.ts

@@ -0,0 +1,298 @@
+import type { Response } from 'express';
+
+import type { ICookiesConfig, ICorsConfig, IServerOptions } from '../interfaces/server-options.interface';
+
+/**
+ * Module-scoped cache of `process.env.NODE_ENV === 'production'`.
+ *
+ * `process.env` reads are cheap but not free; the auth hot path calls cookie helpers
+ * on every sign-in/sign-up/refresh. Since `NODE_ENV` is established at process start
+ * and immutable for the server lifetime, we read it once at import time.
+ *
+ * @since 11.25.0
+ */
+const IS_PRODUCTION_NODE_ENV = process.env.NODE_ENV === 'production';
+
+/**
+ * Checks whether the given environment should be treated as production-like.
+ *
+ * Production-like means auth cookies must be set with `secure: true`
+ * (HTTPS-only). Triggers when EITHER:
+ * - `env === 'production'` or `env === 'staging'` (app-level `config.env`), OR
+ * - `process.env.NODE_ENV === 'production'` (runtime Node environment)
+ *
+ * Checking both layers protects staging deployments that set `config.env = 'staging'`
+ * but do not set `NODE_ENV=production`, and vice versa.
+ *
+ * @since 11.25.0
+ */
+export function isProductionLikeEnv(env?: string): boolean {
+  if (env === 'production' || env === 'staging') return true;
+  return IS_PRODUCTION_NODE_ENV;
+}
+
+/**
+ * Standard cookie options for authentication cookies.
+ *
+ * Applied to both Legacy Auth (`token`, `refreshToken`) and BetterAuth cookies.
+ * Enforces baseline security (httpOnly, sameSite=lax) and environment-aware
+ * secure flag (HTTPS-only in production).
+ *
+ * @since 11.25.0
+ */
+export interface AuthCookieDefaultOptions {
+  httpOnly: true;
+  sameSite: 'lax';
+  secure: boolean;
+}
+
+/**
+ * Returns the default secure cookie options for authentication cookies.
+ *
+ * - `httpOnly: true` — prevents JavaScript access (XSS mitigation)
+ * - `sameSite: 'lax'` — CSRF mitigation
+ * - `secure: isProductionLikeEnv(env)` — HTTPS-only in production/staging
+ *
+ * Used by both Legacy Auth and BetterAuth cookie helpers for consistent security.
+ *
+ * @param env - App-level environment from `IServerOptions.env` (e.g. `'production'`, `'staging'`, `'ci'`).
+ *              Falls back to `process.env.NODE_ENV === 'production'` if absent.
+ *
+ * @since 11.25.0
+ */
+export function getDefaultAuthCookieOptions(env?: string): AuthCookieDefaultOptions {
+  return {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: isProductionLikeEnv(env),
+  };
+}
+
+/**
+ * Asserts that the cookies configuration is safe for production/staging environments.
+ *
+ * Throws if `exposeTokenInBody: true` is combined with a production-like environment.
+ * Rationale: Exposing the session token in the response body negates the XSS
+ * protection of the httpOnly session cookie — it enables XSS attacks to read
+ * the token from the response body.
+ *
+ * Test environments (ci, e2e, development, local) may use `exposeTokenInBody: true`
+ * for TestHelper to read tokens — these are guarded against by the env check.
+ *
+ * @throws Error if configuration is unsafe for production/staging
+ *
+ * @since 11.25.0
+ */
+export function assertCookiesProductionSafe(
+  cookies: boolean | ICookiesConfig | undefined,
+  env: string | undefined,
+): void {
+  // Use the shared production-like detection so the guard triggers symmetrically with the
+  // `secure` cookie flag: both app-level `env` ('production'/'staging') AND runtime
+  // `NODE_ENV=production` are covered. A deployment that sets only `NODE_ENV=production`
+  // but forgets the app `env` field must still be blocked from exposeTokenInBody.
+  if (isProductionLikeEnv(env) && isExposeTokenInBodyEnabled(cookies)) {
+    throw new Error(
+      'SECURITY: cookies.exposeTokenInBody must not be true in production or staging. ' +
+        'Exposing the session token in the response body negates the XSS protection of ' +
+        'the httpOnly session cookie. If hybrid JWT+Cookie auth is required, handle the ' +
+        'token at the client layer (e.g., via getToken endpoint) instead of exposing it in ' +
+        'the login response body.',
+    );
+  }
+}
+
+/**
+ * Sets legacy auth cookies (`token`, `refreshToken`) on the response with secure defaults.
+ *
+ * Consolidates cookie-setting logic shared between `CoreAuthController` (REST) and
+ * `CoreAuthResolver` (GraphQL). Applies standard security options (httpOnly, sameSite,
+ * secure-in-production) and honors `exposeTokenInBody` by optionally stripping tokens
+ * from the response body after setting cookies.
+ *
+ * @param res - Express Response object
+ * @param result - Auth result containing `token` and `refreshToken` (modified in place)
+ * @param cookies - The `cookies` config value from IServerOptions
+ * @param env - App-level env from `IServerOptions.env` (used for `secure` flag derivation)
+ * @returns The (possibly modified) result object
+ *
+ * @since 11.25.0
+ */
+export function setLegacyAuthCookies<T extends { refreshToken?: string; token?: string } | null | undefined>(
+  res: Response,
+  result: T,
+  cookies: boolean | ICookiesConfig | undefined,
+  env?: string,
+): T {
+  if (!isCookiesEnabled(cookies)) {
+    return result;
+  }
+
+  const cookieOptions = getDefaultAuthCookieOptions(env);
+
+  // If result is absent or not an object, clear any existing cookies (logout path)
+  if (!result || typeof result !== 'object') {
+    res.cookie('token', '', cookieOptions);
+    res.cookie('refreshToken', '', cookieOptions);
+    return result;
+  }
+
+  res.cookie('token', result.token || '', cookieOptions);
+  res.cookie('refreshToken', result.refreshToken || '', cookieOptions);
+
+  // Remove tokens from response body unless exposeTokenInBody is enabled
+  if (!isExposeTokenInBodyEnabled(cookies)) {
+    if (result.token) {
+      delete result.token;
+    }
+    if (result.refreshToken) {
+      delete result.refreshToken;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Checks if cookies are enabled based on the cookies config value.
+ *
+ * Follows the Boolean Shorthand Pattern:
+ * - `undefined` → true (enabled by default)
+ * - `true` → true
+ * - `false` → false
+ * - `{}` → true (presence implies enabled)
+ * - `{ enabled: true }` → true
+ * - `{ enabled: false }` → false
+ * - `{ exposeTokenInBody: true }` → true (enabled, token exposed)
+ *
+ * @since 11.25.0
+ */
+export function isCookiesEnabled(cookies: boolean | ICookiesConfig | undefined): boolean {
+  if (cookies === false) return false;
+  if (typeof cookies === 'object' && cookies !== null) return cookies.enabled !== false;
+  return true; // undefined or true → enabled (default)
+}
+
+/**
+ * Checks if exposeTokenInBody is enabled based on the cookies config value.
+ *
+ * When true, authentication endpoints keep the token in the response body
+ * even when cookies are active. By default false — the httpOnly cookie
+ * provides XSS protection, exposing the token in the body would negate that.
+ *
+ * @since 11.25.0
+ */
+export function isExposeTokenInBodyEnabled(cookies: boolean | ICookiesConfig | undefined): boolean {
+  if (typeof cookies === 'object' && cookies !== null) return cookies.exposeTokenInBody === true;
+  return false; // Default: false
+}
+
+/**
+ * Determines whether a BetterAuth session token must be converted to a JWT
+ * before being returned to the client.
+ *
+ * Conversion is required when the client actually reads the token from the
+ * response body — otherwise the opaque session token travels via cookie only
+ * and never needs to be a JWT.
+ *
+ * Truth table:
+ *
+ * | cookies                         | jwtEnabled | convert? |
+ * |---------------------------------|------------|----------|
+ * | `false` (JWT-only mode)         | true       | yes      |
+ * | `true` / `{}` (cookie-only)     | true       | no       |
+ * | `{ exposeTokenInBody: true }`   | true       | yes      |
+ * | any                             | false      | no       |
+ *
+ * @param cookies - The `cookies` config value from IServerOptions
+ * @param jwtEnabled - Whether the BetterAuth JWT plugin is enabled
+ * @returns true if the caller should convert the session token to a JWT
+ *
+ * @since 11.25.0
+ */
+export function shouldConvertSessionTokenToJwt(
+  cookies: boolean | ICookiesConfig | undefined,
+  jwtEnabled: boolean,
+): boolean {
+  if (!jwtEnabled) return false;
+  const cookiesEnabled = isCookiesEnabled(cookies);
+  const exposeTokenInBody = isExposeTokenInBodyEnabled(cookies);
+  // Cookies-only mode: token delivered via cookie, no body JWT needed
+  if (cookiesEnabled && !exposeTokenInBody) return false;
+  return true;
+}
+
+/**
+ * Checks if CORS is disabled based on the cors config value.
+ *
+ * CORS is disabled when:
+ * - `cors === false`
+ * - `cors.enabled === false`
+ *
+ * @since 11.25.0
+ */
+export function isCorsDisabled(cors: boolean | ICorsConfig | undefined): boolean {
+  if (cors === false) return true;
+  if (typeof cors === 'object' && cors !== null) return cors.enabled === false;
+  return false;
+}
+
+/**
+ * Builds a CORS configuration object from server options.
+ *
+ * Resolution priority:
+ * 1. CORS disabled → empty object (no CORS)
+ * 2. Cookies disabled → empty object (no credentials needed, handled by simple enableCors())
+ * 3. `cors.allowAll` → `{ credentials: true, origin: true }` (mirror request origin)
+ * 4. `cors.allowedOrigins` + `appUrl`/`baseUrl` → deduplicated origin list
+ * 5. Only `appUrl`/`baseUrl` → those origins
+ * 6. Nothing configured → `{}` (no credentialed CORS — caller decides fallback)
+ *
+ * Used by both:
+ * - `CoreModule.buildCorsConfig()` for GraphQL (Apollo) CORS
+ * - `main.ts` reference implementation for REST (Express) CORS
+ *
+ * Security note: when no origins are resolvable AND cookies are enabled, the function
+ * returns `{}` rather than `{ credentials: true, origin: true }`. Returning open CORS
+ * with credentials would allow any website to make credentialed requests. Callers
+ * should either configure `appUrl`/`baseUrl`/`allowedOrigins`, enable `cors.allowAll`
+ * explicitly (for development), or accept no credentialed CORS.
+ *
+ * @param options - Server options containing `cors`, `cookies`, `appUrl`, `baseUrl`
+ * @returns CORS config object for Apollo/Express, or empty object if disabled/unconfigured
+ *
+ * @since 11.25.0
+ */
+export function buildCorsConfig(options: Partial<IServerOptions>): Record<string, unknown> {
+  if (isCorsDisabled(options?.cors)) {
+    return {};
+  }
+
+  if (!isCookiesEnabled(options?.cookies)) {
+    return {};
+  }
+
+  const corsObj = typeof options?.cors === 'object' ? options.cors : {};
+
+  // allowAll → mirror request origin (explicit opt-in for dev/test)
+  if (corsObj.allowAll) {
+    return { credentials: true, origin: true };
+  }
+
+  // Build origin list from appUrl, baseUrl, and allowedOrigins
+  const origins: string[] = [];
+  if (options?.appUrl) origins.push(options.appUrl);
+  if (options?.baseUrl) origins.push(options.baseUrl);
+  if (corsObj.allowedOrigins?.length) {
+    origins.push(...corsObj.allowedOrigins);
+  }
+
+  const uniqueOrigins = [...new Set(origins)];
+
+  if (uniqueOrigins.length > 0) {
+    return { credentials: true, origin: uniqueOrigins };
+  }
+
+  // No origins resolvable → return empty (secure default — no open CORS with credentials)
+  return {};
+}

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

@@ -944,6 +944,107 @@ export interface IMultiTenancy {
   cacheTtlMs?: number;
 }
 
+/**
+ * Cookie configuration for authentication handling.
+ *
+ * Follows the Boolean Shorthand Pattern:
+ * - `undefined` / `true`: Cookies enabled with default settings
+ * - `false`: Cookies disabled (JWT-only mode)
+ * - `{ exposeTokenInBody: true }`: Cookies enabled AND token returned in response body
+ *
+ * When cookies are enabled, the server:
+ * - Loads `cookie-parser` middleware
+ * - Sets `credentials: true` in CORS configuration
+ * - Sets signed httpOnly session cookies on authentication responses
+ *
+ * JWT authentication via `Authorization: Bearer` header works independently
+ * of the cookie configuration — it is always available regardless of this setting.
+ *
+ * @default true (cookies enabled, exposeTokenInBody disabled)
+ * @since 11.25.0
+ */
+export interface ICookiesConfig {
+  /**
+   * Whether cookies are enabled.
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Whether to include the session token in the response body when cookies are enabled.
+   *
+   * By default, when cookies are active, the token is removed from the response body
+   * because the httpOnly cookie protects against XSS — exposing the token in the body
+   * would negate this security benefit.
+   *
+   * Enable this only when clients need both JWT (via response body) AND cookies
+   * in parallel (e.g., hybrid mobile/web apps).
+   *
+   * @default false
+   */
+  exposeTokenInBody?: boolean;
+}
+
+/**
+ * CORS (Cross-Origin Resource Sharing) configuration.
+ *
+ * Controls which origins can access the API. This configuration propagates to
+ * all three CORS layers: GraphQL (Apollo), REST (Express), and BetterAuth (trustedOrigins).
+ *
+ * Follows the Boolean Shorthand Pattern:
+ * - `undefined` / `true` / `{}`: CORS enabled with auto-derived origins from `appUrl`/`baseUrl`
+ * - `false`: CORS disabled on all layers (including BetterAuth)
+ * - `{ allowedOrigins: [...] }`: Additional origins beyond `appUrl`/`baseUrl`
+ * - `{ allowAll: true }`: Allow all origins (mirrors request origin — NOT recommended for production)
+ *
+ * When cookies are enabled (default), CORS automatically includes `credentials: true`.
+ * Browsers reject `Access-Control-Allow-Origin: *` with credentials, so origins must
+ * be explicitly listed or `allowAll` must be set (which mirrors the request origin).
+ *
+ * @default undefined (enabled, origins auto-derived from appUrl/baseUrl)
+ * @since 11.25.0
+ */
+export interface ICorsConfig {
+  /**
+   * Allow all origins by mirroring the request Origin header back.
+   *
+   * This effectively allows any website to make credentialed requests to the API.
+   * Convenient for development but NOT recommended for production as it enables
+   * CSRF-like attacks from any domain.
+   *
+   * When true, overrides `allowedOrigins`. Also propagates to BetterAuth
+   * (trustedOrigins is set to undefined, allowing all origins).
+   *
+   * @default false
+   */
+  allowAll?: boolean;
+
+  /**
+   * Additional allowed origins beyond `appUrl` and `baseUrl`.
+   *
+   * These origins are merged with the auto-derived origins from `appUrl` and `baseUrl`
+   * (duplicates are removed). The combined list is used for both Express/Apollo CORS
+   * and BetterAuth's `trustedOrigins`.
+   *
+   * Only effective when `allowAll` is not set to `true`.
+   *
+   * @example ['https://admin.example.com', 'https://partner.example.com']
+   */
+  allowedOrigins?: string[];
+
+  /**
+   * Whether CORS is enabled.
+   *
+   * When set to `false`, disables CORS on all layers:
+   * - GraphQL: No CORS headers
+   * - REST: `enableCors()` not called
+   * - BetterAuth: `trustedOrigins` set to empty array (no origins allowed)
+   *
+   * @default true
+   */
+  enabled?: boolean;
+}
+
 /**
  * Options for the server
  */
@@ -1123,10 +1224,48 @@ export interface IServerOptions {
   compression?: boolean | compression.CompressionOptions;
 
   /**
-   * Whether to use cookies for authentication handling
+   * Cookie configuration for authentication handling.
+   *
+   * Controls whether session cookies are set on authentication responses and
+   * whether `cookie-parser` middleware is loaded.
+   *
+   * Accepts (Boolean Shorthand Pattern):
+   * - `undefined` / `true`: Cookies enabled (token removed from response body)
+   * - `false`: Cookies disabled (JWT-only mode, token stays in response body)
+   * - `{ exposeTokenInBody: true }`: Cookies enabled AND token in response body
+   *
+   * JWT authentication via `Authorization: Bearer` header works independently
+   * of this setting — always available regardless of cookie configuration.
+   *
    * See: https://docs.nestjs.com/techniques/cookies
+   *
+   * @default true
+   * @since 11.25.0 Changed default from false to true, added ICookiesConfig
+   * @see ICookiesConfig
+   */
+  cookies?: boolean | ICookiesConfig;
+
+  /**
+   * CORS (Cross-Origin Resource Sharing) configuration.
+   *
+   * Controls which origins can access the API. Propagates to all layers:
+   * GraphQL (Apollo), REST (Express), and BetterAuth (trustedOrigins).
+   *
+   * Origins are auto-derived from `appUrl` and `baseUrl` when available.
+   * Use `cors.allowedOrigins` to add additional origins, or `cors.allowAll`
+   * to allow all origins (development only).
+   *
+   * Accepts (Boolean Shorthand Pattern):
+   * - `undefined` / `true` / `{}`: CORS enabled with auto-derived origins
+   * - `false`: CORS disabled on all layers (including BetterAuth)
+   * - `{ allowedOrigins: [...] }`: Additional origins beyond appUrl/baseUrl
+   * - `{ allowAll: true }`: Allow all origins (not recommended for production)
+   *
+   * @default undefined (enabled with auto-derived origins)
+   * @since 11.25.0
+   * @see ICorsConfig
    */
-  cookies?: boolean;
+  cors?: boolean | ICorsConfig;
 
   /**
    * Cron jobs configuration object with the name of the cron job function as key

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

@@ -14,6 +14,8 @@ import { ApiCommonErrorResponses } from '../../common/decorators/common-error.de
 import { CurrentUser } from '../../common/decorators/current-user.decorator';
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
+import { setLegacyAuthCookies } from '../../common/helpers/cookies.helper';
+import type { ICookiesConfig } from '../../common/interfaces/server-options.interface';
 import { ConfigService } from '../../common/services/config.service';
 import { AuthGuardStrategy } from './auth-guard-strategy.enum';
 import { CoreAuthModel } from './core-auth.model';
@@ -187,30 +189,16 @@ export class CoreAuthController {
   // ===================================================================================================================
 
   /**
-   * Process cookies
+   * Process cookies — sets legacy auth cookies (token, refreshToken) with secure defaults
+   * and optionally strips tokens from the response body per `cookies.exposeTokenInBody`.
+   *
+   * Delegates to the shared `setLegacyAuthCookies()` helper to ensure consistent
+   * security options (httpOnly, sameSite=lax, secure in production) between the REST
+   * controller and GraphQL resolver.
    */
   protected processCookies(res: ResponseType, result: any) {
-    // 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 });
-        res.cookie('refreshToken', '', { httpOnly: true });
-        return result;
-      }
-      res.cookie('token', result?.token || '', { httpOnly: true });
-      res.cookie('refreshToken', result?.refreshToken || '', { httpOnly: true });
-
-      // Remove tokens from result
-      if (result.token) {
-        delete result.token;
-      }
-      if (result.refreshToken) {
-        delete result.refreshToken;
-      }
-    }
-
-    // Return prepared result
-    return result;
+    const cookiesConfig = this.configService.getFastButReadOnly<boolean | ICookiesConfig>('cookies');
+    const env = this.configService.getFastButReadOnly<string>('env');
+    return setLegacyAuthCookies(res, result, cookiesConfig, env);
   }
 }

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

@@ -6,6 +6,8 @@ import { CurrentUser } from '../../common/decorators/current-user.decorator';
 import { GraphQLServiceOptions } from '../../common/decorators/graphql-service-options.decorator';
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
+import { setLegacyAuthCookies } from '../../common/helpers/cookies.helper';
+import type { ICookiesConfig } from '../../common/interfaces/server-options.interface';
 import { ServiceOptions } from '../../common/interfaces/service-options.interface';
 import { ConfigService } from '../../common/services/config.service';
 import { AuthGuardStrategy } from './auth-guard-strategy.enum';
@@ -169,30 +171,16 @@ export class CoreAuthResolver {
   // ===================================================================================================================
 
   /**
-   * Process cookies
+   * Process cookies — sets legacy auth cookies (token, refreshToken) with secure defaults
+   * and optionally strips tokens from the response body per `cookies.exposeTokenInBody`.
+   *
+   * Delegates to the shared `setLegacyAuthCookies()` helper to ensure consistent
+   * security options (httpOnly, sameSite=lax, secure in production) between the REST
+   * controller and GraphQL resolver.
    */
   protected processCookies(ctx: { res: ResponseType }, result: any) {
-    // 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 });
-        ctx.res.cookie('refreshToken', '', { httpOnly: true });
-        return result;
-      }
-      ctx.res.cookie('token', result?.token || '', { httpOnly: true });
-      ctx.res.cookie('refreshToken', result?.refreshToken || '', { httpOnly: true });
-
-      // Remove tokens from result
-      if (result.token) {
-        delete result.token;
-      }
-      if (result.refreshToken) {
-        delete result.refreshToken;
-      }
-    }
-
-    // Return prepared result
-    return result;
+    const cookiesConfig = this.configService.getFastButReadOnly<boolean | ICookiesConfig>('cookies');
+    const env = this.configService.getFastButReadOnly<string>('env');
+    return setLegacyAuthCookies(ctx.res, result, cookiesConfig, env);
   }
 }

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -163,6 +163,24 @@ export class ServerModule {}
 **Modify:** `src/config.env.ts`
 **Reference:** `node_modules/@lenne.tech/nest-server/src/config.env.ts`
 
+> **Since v11.25.0 — Cookie & CORS Defaults**
+>
+> Cookies are now **enabled by default** (`cookies: true`). Authentication responses
+> set signed httpOnly session cookies and **remove the token from the response body**.
+>
+> For test environments where `TestHelper` reads the token from the response body
+> (signIn → token → subsequent requests with `Authorization: Bearer`), set:
+>
+> ```typescript
+> ci: { cookies: { exposeTokenInBody: true }, cors: { allowAll: true } },
+> e2e: { cookies: { exposeTokenInBody: true }, cors: { allowAll: true } },
+> ```
+>
+> **Never set `exposeTokenInBody: true` in production** — the framework throws at
+> startup if this is detected in `production` or `staging` environments (XSS-risk guard).
+>
+> To keep the old behavior (cookies off, tokens in body everywhere), set `cookies: false`.
+
 #### Zero-Config (Default):
 
 BetterAuth is **enabled by default** with JWT + 2FA. No configuration required!

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

@@ -260,6 +260,13 @@ Read the security section below for production deployments.
 | `basePath`       | Endpoint routing   | 404 on API calls            |
 | `passkey.origin` | WebAuthn security  | Passkey auth fails          |
 
+**Global server-level settings that affect BetterAuth behavior (since v11.25.0):**
+
+| Setting (top-level `IServerOptions`)                                          | Technical Purpose                                                                                                                                                                      | Impact of Wrong Value                                                                                                         |
+| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `cookies` (`boolean \| ICookiesConfig`, default: `true`)                      | Controls cookie-parser middleware and session cookie setting. `cookies.exposeTokenInBody` additionally returns the token in the response body (test-only; **forbidden in production**) | Tokens missing from response body surprises test clients; `exposeTokenInBody` in prod = XSS-risk, framework throws at startup |
+| `cors` (`boolean \| ICorsConfig`, default: enabled with auto-derived origins) | Unified CORS config — propagates to GraphQL (Apollo), REST (Express), and BetterAuth `trustedOrigins` from a single source                                                             | `cors.enabled: false` disables all three layers; `cors.allowAll` allows any origin (dev only)                                 |
+
 **For Development:** The defaults (`http://localhost:3000`, `/iam`) are correct.
 
 ### Passkey Auto-Detection (Recommended)