@lenne.tech/nest-server 11.27.4 → 11.27.5

package/docs/REQUEST-LIFECYCLE.md

@@ -460,8 +460,15 @@ if (!isCorsDisabled(envConfig.cors)) {
 | `cors: { allowAll: true }` | `origin: true` | `origin: true` | `trustedOrigins: undefined` |
 | `cors: { allowedOrigins: [...] }` | `origin: [merged list]` | `origin: [merged list]` | `trustedOrigins: [merged list]` |
 | `cors: { enabled: false }` | No CORS headers | No CORS headers | `trustedOrigins: []` |
+| `cors: { deriveAppUrl: false }` | `appUrl` not derived from `baseUrl` | same | same |
 
-> **Note:** GraphQL CORS is configured in `CoreModule.buildCorsConfig()` using raw config values. BetterAuth derives `trustedOrigins` using resolved URLs (auto-derived from `baseUrl`). In edge cases (no explicit `appUrl`), these may differ slightly. Set `appUrl` explicitly for consistent behavior across all layers.
+**URL resolution (since v11.27.5):** all three layers resolve `appUrl`/`baseUrl` through the single `resolveServerUrls()` helper in `cookies.helper.ts`, so they can no longer drift:
+
+1. `appUrl` set explicitly → used as-is
+2. `env: 'local' | 'ci' | 'e2e'` with a localhost `baseUrl` → `appUrl` defaults to `http://localhost:3001`
+3. otherwise derived from `baseUrl` by stripping a leading `api.` label (`https://api.example.com` → `https://example.com`), unless `cors.deriveAppUrl: false`
+
+> **Security:** step 3 grants the derived origin credentialed CORS. If the apex domain is not trusted (e.g. a third-party-hosted marketing site whose XSS surface you do not control), set `cors.deriveAppUrl: false` and list the frontend origin explicitly via `appUrl` or `cors.allowedOrigins`. The derivation never yields a bare TLD (`https://api.dev` stays unchanged) and never emits the opaque `null` origin.
 
 ### NestJS Middleware Chain (CoreModule)
 

package/migration-guides/11.27.4-to-11.27.5.md

@@ -0,0 +1,241 @@
+# Migration Guide: 11.27.4 → 11.27.5
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None (API-compatible). One **behavior change**: a config that sets only `baseUrl` now also trusts the derived app origin in the REST/GraphQL CORS allowlist — see [Behavior Change](#behavior-change-cors-allowlist-derives-appurl). |
+| **New Features** | `cors.deriveAppUrl` opt-out; exported `resolveServerUrls()` and `deriveAppUrlFromBaseUrl()` helpers. |
+| **Bugfixes** | REST/GraphQL CORS blocked the frontend origin on `api.<host>` deployments and in `local`/`ci`/`e2e`; the `api.`-strip could produce a bare TLD or the opaque `null` origin; trailing-slash `baseUrl` produced a never-matching origin entry. |
+| **Security Updates** | `better-auth` + `@better-auth/passkey` `1.6.11` → `1.6.23` (GHSA-86j7-9j95-vpqj, High); `@xhmikosr/decompress` pinned to `11.1.3` via override (GHSA-mp2f-45pm-3cg9, Critical). |
+| **Migration Effort** | 0 minutes for most projects (`pnpm update`). ~2 minutes if your apex domain is untrusted — see below. |
+
+The three CORS layers (GraphQL/Apollo, REST/Express, BetterAuth `trustedOrigins`)
+previously each resolved `appUrl`/`baseUrl` on their own and had drifted. They now
+share a single `resolveServerUrls()` helper, so they cannot disagree.
+
+---
+
+## Quick Migration
+
+No code changes required for the common case.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.5
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+---
+
+## What's Fixed in 11.27.5
+
+### 1. `api.<host>` deployments: the frontend origin was blocked
+
+A deployment that sets only `baseUrl` (the typical `NSC__BASE_URL` /
+`BASE_URL` setup) got a CORS allowlist containing just the API's own origin.
+BetterAuth already derived `https://example.com` from
+`https://api.example.com` for its `trustedOrigins`, but the REST and GraphQL
+layers did not — so IAM endpoints worked cross-origin while every other
+endpoint failed preflight.
+
+Both layers now derive `appUrl` identically:
+
+```typescript
+// config.env.ts — no appUrl needed
+baseUrl: 'https://api.example.com',
+// → CORS allowlist: ['https://example.com', 'https://api.example.com']
+```
+
+### 2. `local` / `ci` / `e2e`: localhost defaults were not applied to CORS
+
+`resolveUrls()` in BetterAuth mapped these environments to
+`appUrl = http://localhost:3001` (API on `:3000`, app on `:3001`).
+`buildCorsConfig()` had no such branch, so the frontend was blocked. The
+shared resolver now applies the same defaults on every layer.
+
+> The framework's own `development` environment is **not** one of the
+> localhost-default environments. `src/config.env.ts` now sets
+> `appUrl: process.env.APP_URL || 'http://localhost:3001'` there explicitly.
+> Projects that copied the `development` block from the starter and run their
+> frontend on `:3001` should do the same.
+
+### 3. Hardened `api.`-label stripping
+
+| `baseUrl` | Before | After |
+|-----------|--------|-------|
+| `https://api.example.com` | `https://example.com` | unchanged |
+| `https://api.dev.example.com` | `https://dev.example.com` | unchanged |
+| `https://api.dev` | `https://dev` (bare TLD!) | `https://api.dev` (no strip) |
+| `https://api.` | `https://api.` (silent no-op) | `https://api.` (explicit no-op) |
+| `custom://api.example.com` | `"null"` (opaque origin!) | `custom://api.example.com` |
+| `https://api.example.com/` | `https://example.com` + dead `…/` entry | both entries origin-normalized |
+
+The `"null"` case was the most serious: `URL.origin` serializes opaque origins
+to the literal string `"null"`, which is exactly the `Origin` header a
+sandboxed iframe sends. In a `credentials: true` allowlist that would have
+granted credentialed access to any site able to frame a sandboxed document.
+Only `http:`/`https:` URLs are normalized to origins now.
+
+### 4. Security updates in dependencies
+
+| Package | Change | Advisory |
+|---------|--------|----------|
+| `better-auth` | `1.6.11` → `1.6.23` (direct) | [GHSA-86j7-9j95-vpqj](https://github.com/advisories/GHSA-86j7-9j95-vpqj) — High: stored XSS in the auth-server origin via a `javascript:` `redirect_uri` in `oidc-provider` and `mcp` |
+| `@better-auth/passkey` | `1.6.11` → `1.6.23` (direct) | Kept in lockstep — peers on `better-auth@^1.6.23` |
+| `@xhmikosr/decompress` | pinned to `11.1.3` via `pnpm.overrides` | [GHSA-mp2f-45pm-3cg9](https://github.com/advisories/GHSA-mp2f-45pm-3cg9) — Critical: archive extraction can create files/links outside the target directory |
+
+`@xhmikosr/decompress` is transitive via `@swc/cli > @xhmikosr/bin-wrapper > @xhmikosr/downloader`.
+`@swc/cli@0.8.1` is the latest release and still resolves the vulnerable range, so an override
+with a fixed target is the only available fix.
+
+Both `better-auth` bumps stay inside `1.6.x` — no BetterAuth API change. The full suite
+(2019 tests) passes unchanged.
+
+npm-mode consumers get all three fixes with a plain `pnpm update`. Vendor-mode consumers must
+bump `better-auth`/`@better-auth/passkey` in their own `package.json` and copy the
+`@xhmikosr/decompress` override — the vendored file set does not carry `package.json`.
+
+---
+
+## Behavior Change: CORS allowlist derives `appUrl`
+
+**Who is affected:** projects that configure `baseUrl` but neither `appUrl`
+nor `cors.allowedOrigins`, and whose apex domain is not under their control.
+
+Deriving `appUrl` means the apex origin (`https://example.com`) receives
+**credentialed** cross-origin access (`Access-Control-Allow-Credentials: true`).
+That is the intended, documented `appUrl` auto-detection and matches what
+BetterAuth's `trustedOrigins` has always done — but it now also applies to the
+REST and GraphQL layers.
+
+If your apex is a third-party-hosted marketing site (WordPress, Webflow,
+HubSpot) whose XSS surface you do not control, opt out:
+
+```typescript
+// config.env.ts
+{
+  baseUrl: 'https://api.example.com',
+  cors: {
+    // Do not trust https://example.com implicitly
+    deriveAppUrl: false,
+    // List the real frontend origin instead
+    allowedOrigins: ['https://app.example.com'],
+  },
+}
+```
+
+`deriveAppUrl: false` suppresses the derivation on **all three** layers
+(GraphQL, REST, BetterAuth `trustedOrigins`). It has no effect when `appUrl`
+is set explicitly, and it does not disable the `local`/`ci`/`e2e` localhost
+defaults.
+
+---
+
+## What's New in 11.27.5
+
+### `cors.deriveAppUrl`
+
+| Value | Effect |
+|-------|--------|
+| `true` (default) | `appUrl` is derived from `baseUrl` by stripping a leading `api.` label |
+| `false` | No derivation; configure `appUrl` / `cors.allowedOrigins` explicitly |
+
+### Exported URL helpers
+
+Both are exported from the package root (`cookies.helper.ts`):
+
+```typescript
+import { deriveAppUrlFromBaseUrl, resolveServerUrls } from '@lenne.tech/nest-server';
+
+deriveAppUrlFromBaseUrl('https://api.example.com'); // 'https://example.com'
+
+resolveServerUrls({ baseUrl: 'https://api.example.com' });
+// { appUrl: 'https://example.com', appUrlSource: 'derived',
+//   baseUrl: 'https://api.example.com', baseUrlSource: 'explicit' }
+```
+
+`appUrlSource` / `baseUrlSource` (`'explicit' | 'localhost-default' | 'derived' | 'none'`)
+let callers emit accurate startup diagnostics without re-deriving the resolution logic.
+
+---
+
+## Breaking Changes
+
+None. `ICorsConfig` gained an optional field; no signature, export, or Core
+class changed.
+
+---
+
+## Compatibility Notes
+
+- **npm-mode consumers:** `pnpm update` is sufficient. Review the
+  [behavior change](#behavior-change-cors-allowlist-derives-appurl) if your
+  apex domain is untrusted.
+- **Vendor-mode consumers:** the change touches `src/core/common/helpers/cookies.helper.ts`,
+  `src/core/common/interfaces/server-options.interface.ts` and
+  `src/core/modules/better-auth/better-auth.config.ts` — all inside the vendored
+  `src/core/` file set. Sync via `/lt-dev:backend:update-nest-server-core`.
+  `better-auth.config.ts` now imports `resolveServerUrls` from
+  `../../common/helpers/cookies.helper` (still inside `src/core/`, so the
+  self-containment rule holds).
+- **Projects that set `appUrl` explicitly:** unaffected. Explicit values are
+  never overridden by the derivation.
+- **Projects that set `cors.allowAll: true`:** unaffected. `allowAll` short-circuits
+  before URL resolution.
+- **Passkey / WebAuthn in `development`:** if you adopt the new
+  `appUrl: 'http://localhost:3001'` in the `development` block, the Passkey
+  `origin` becomes `http://localhost:3001` (where the browser actually runs)
+  instead of the API's `:3000`. This is a fix — WebAuthn ceremonies from the
+  frontend previously used the wrong origin.
+- **A duplicate private `deriveAppUrlFromBaseUrl()` was removed** from
+  `better-auth.config.ts`. It was never exported; nothing to migrate.
+
+---
+
+## Troubleshooting
+
+### My frontend is still blocked by CORS
+
+Check, in order:
+
+1. `cors.enabled` is not `false`.
+2. `cookies` is not disabled — `buildCorsConfig()` returns `{}` when cookies
+   are off (REST then falls back to permissive `enableCors()` without credentials).
+3. Your frontend origin is actually derivable. `baseUrl: 'https://my-api.example.com'`
+   has no `api.` label to strip, so `appUrl` resolves to the API's own origin.
+   Set `appUrl` explicitly.
+4. `env` is one of `local`/`ci`/`e2e` if you rely on the `localhost:3001` default.
+   `development` is not — set `appUrl` there.
+
+### My apex domain unexpectedly appears in the allowlist
+
+That is the `appUrl` derivation. Set `cors.deriveAppUrl: false` and list the
+frontend origin explicitly. See
+[Behavior Change](#behavior-change-cors-allowlist-derives-appurl).
+
+### `https://api.dev` no longer derives an app origin
+
+Intended. Stripping would leave the bare TLD `dev`, which is not a deployable
+host. Set `appUrl` explicitly for such domains.
+
+---
+
+## Module Documentation
+
+- **Request lifecycle & CORS:** [docs/REQUEST-LIFECYCLE.md](../docs/REQUEST-LIFECYCLE.md) — section `0b. CORS`
+- **Configurable features:** [.claude/rules/configurable-features.md](../.claude/rules/configurable-features.md) — `CORS` row
+- **BetterAuth:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md)
+
+---
+
+## References
+
+- [Migration Guide 11.27.3 → 11.27.4](./11.27.3-to-11.27.4.md) — Previous release (test tooling)
+- [Migration Guide 11.24.x → 11.25.0](./11.24.x-to-11.25.0.md) — Introduced the unified `cors` config
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — reference implementation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.27.4",
+  "version": "11.27.5",
   "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",
@@ -77,7 +77,7 @@
   "dependencies": {
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
-    "@better-auth/passkey": "1.6.11",
+    "@better-auth/passkey": "1.6.23",
     "@getbrevo/brevo": "3.0.1",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/apollo": "13.4.2",
@@ -96,7 +96,7 @@
     "@tus/server": "2.4.1",
     "@types/supertest": "7.2.0",
     "bcrypt": "6.0.0",
-    "better-auth": "1.6.11",
+    "better-auth": "1.6.23",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
     "compression": "1.8.1",
@@ -216,7 +216,8 @@
       "hono@<4.12.25": "Security: multiple CVEs <4.12.25 (prototype pollution, bodyLimit/Vary bypass, JWT NumericDate) - transitive via @nestjs/terminus>prisma>@prisma/dev",
       "nodemailer@<9.0.1": "Security: email/header injection CVEs <9.0.1 - direct dependency",
       "multer@<2.2.0": "Security: unhandled multipart errors / DoS <2.2.0 - transitive via @nestjs/platform-express",
-      "js-yaml@<4.2.0": "Security: special-character handling / prototype pollution (patched in 4.2.0; 4.1.2 was never published) - transitive via @nestjs/swagger"
+      "js-yaml@<4.2.0": "Security: special-character handling / prototype pollution (patched in 4.2.0; 4.1.2 was never published) - transitive via @nestjs/swagger",
+      "@xhmikosr/decompress@<11.1.3": "Security: archive extraction can create files/links outside the target directory (GHSA-mp2f-45pm-3cg9, critical) - transitive via @swc/cli>@xhmikosr/bin-wrapper>@xhmikosr/downloader; @swc/cli 0.8.1 is already the latest release and still resolves the vulnerable range, so an override is the only fix"
     },
     "overrides": {
       "axios@<1.16.0": "1.16.0",
@@ -252,7 +253,8 @@
       "hono@<4.12.25": "4.12.25",
       "nodemailer@<9.0.1": "9.0.1",
       "multer@<2.2.0": "2.2.0",
-      "js-yaml@<4.2.0": "4.2.0"
+      "js-yaml@<4.2.0": "4.2.0",
+      "@xhmikosr/decompress@<11.1.3": "11.1.3"
     },
     "//peerDependencyRules": "allowedVersions: deps lag behind our newer majors (graphql-upload wants @types/express@^4, the deprecated apollo playground plugin wants @apollo/server@^4) — both work with our v5. ignoreMissing: browser-only vis-network peers pulled in transitively via yuml-diagram (server-side UML generation never renders, so these are not needed).",
     "peerDependencyRules": {

package/src/config.env.ts

@@ -170,6 +170,10 @@ const config: { [env: string]: IServerOptions } = {
   // Development environment
   // ===========================================================================
   development: {
+    // `development` is not one of the localhost-default environments (local/ci/e2e), so appUrl
+    // must be set explicitly: deriving it from baseUrl would yield the API's own :3000 origin
+    // and leave the frontend on :3001 outside the CORS allowlist.
+    appUrl: process.env.APP_URL || 'http://localhost:3001',
     auth: {
       legacyEndpoints: { enabled: true },
     },

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

@@ -237,6 +237,190 @@ export function isCorsDisabled(cors: boolean | ICorsConfig | undefined): boolean
   return false;
 }
 
+// =================================================================================================
+// Server URL resolution
+//
+// Single source of truth for "which app/API origin is this server reachable under".
+// Consumed by `buildCorsConfig()` (REST + GraphQL CORS) and by BetterAuth's `resolveUrls()`
+// (trustedOrigins, Passkey rpId/origin, cross-subdomain cookies). Keeping one implementation
+// is what makes the three CORS layers agree — previously each layer derived URLs on its own
+// and they drifted (BetterAuth applied localhost defaults, the CORS layer did not).
+// =================================================================================================
+
+/**
+ * Default URLs for local/test environments (`local`, `ci`, `e2e`).
+ *
+ * These environments run on localhost and have no deployed domain: the API listens on
+ * port 3000, the frontend app on port 3001.
+ *
+ * @since 11.27.5
+ */
+export const LOCALHOST_URL_DEFAULTS = {
+  apiUrl: 'http://localhost:3000',
+  appUrl: 'http://localhost:3001',
+} as const;
+
+/**
+ * Environments that fall back to {@link LOCALHOST_URL_DEFAULTS} when no URLs are configured.
+ *
+ * @since 11.27.5
+ */
+export const LOCALHOST_URL_ENVS: readonly string[] = ['ci', 'e2e', 'local'];
+
+/**
+ * The hostname label stripped from `baseUrl` to derive `appUrl`.
+ */
+const API_HOST_LABEL = 'api.';
+
+/**
+ * Normalizes a URL string to its http(s) origin, or `undefined` when it is not a usable
+ * http(s) URL.
+ *
+ * The `protocol` guard is security-relevant, not cosmetic: `URL.origin` serializes to the
+ * literal string `'null'` for opaque origins (any non-special scheme, e.g. `custom://host`).
+ * That string is exactly the `Origin` header a sandboxed iframe sends, so letting it into a
+ * `credentials: true` allowlist would grant credentialed access to any site able to frame a
+ * sandboxed document.
+ */
+function toHttpOrigin(value: string): string | undefined {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return undefined;
+  }
+
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    return undefined;
+  }
+
+  return url.origin;
+}
+
+/**
+ * Whether the URL points at the local machine (localhost, `*.localhost`, loopback IP).
+ */
+function isLocalhostUrl(value: string | undefined): boolean {
+  if (!value) {
+    return false;
+  }
+
+  try {
+    const { hostname } = new URL(value);
+    return (
+      hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '127.0.0.1' || hostname === '[::1]'
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether stripping the leading `api.` label from the hostname leaves a deployable host.
+ *
+ * Guards two cases where a naive strip produces a bogus origin:
+ * - `api.dev` → `dev` — a bare TLD. `api.dev`/`api.io`/`api.co` are registrable domains, so
+ *   this is reachable configuration, and the result would be an unreachable host in a
+ *   credentialed allowlist.
+ * - `api.` → `` — not a host at all. Assigning an empty hostname is silently ignored by the
+ *   `URL` setter for special schemes, so the strip would appear to succeed but do nothing.
+ *
+ * `localhost` is the one legitimate single-label host (`api.localhost` → `localhost`).
+ */
+function canStripApiLabel(hostname: string): boolean {
+  if (!hostname.startsWith(API_HOST_LABEL)) {
+    return false;
+  }
+
+  const remainder = hostname.slice(API_HOST_LABEL.length);
+  return remainder === 'localhost' || remainder.includes('.');
+}
+
+/**
+ * Derives the frontend app URL from the API base URL by stripping a leading `api.`
+ * label from the hostname (e.g. `https://api.example.com` → `https://example.com`,
+ * `https://api.dev.example.com` → `https://dev.example.com`).
+ *
+ * Returns the origin unchanged when there is no strippable `api.` prefix, and returns the
+ * input unchanged when it is not an http(s) URL — callers decide what to do with a value
+ * they cannot normalize.
+ *
+ * @since 11.27.5
+ */
+export function deriveAppUrlFromBaseUrl(baseUrl: string): string {
+  const origin = toHttpOrigin(baseUrl);
+  if (!origin) {
+    return baseUrl;
+  }
+
+  const url = new URL(origin);
+  if (canStripApiLabel(url.hostname)) {
+    url.hostname = url.hostname.slice(API_HOST_LABEL.length);
+  }
+
+  return url.origin;
+}
+
+/**
+ * Where a resolved URL came from. Callers use this to emit accurate startup diagnostics
+ * without re-deriving the resolution logic.
+ *
+ * @since 11.27.5
+ */
+export interface IResolvedServerUrls {
+  appUrl: string | undefined;
+  appUrlSource: 'derived' | 'explicit' | 'localhost-default' | 'none';
+  baseUrl: string | undefined;
+  baseUrlSource: 'explicit' | 'localhost-default' | 'none';
+}
+
+/**
+ * Resolves the effective app/API URLs for a server configuration.
+ *
+ * `baseUrl`: explicit → localhost default (local/ci/e2e only) → none.
+ * `appUrl`: explicit → localhost default (local/ci/e2e with a localhost `baseUrl`) →
+ * derived from `baseUrl` → none.
+ *
+ * `baseUrl` is returned verbatim (not origin-normalized) because BetterAuth passes it
+ * straight through as its `baseURL`; normalization for origin matching is the caller's job.
+ *
+ * @param input.deriveAppUrl - Set to `false` to disable the `api.`-strip derivation. The
+ *                             localhost defaults are unaffected — they are an explicit,
+ *                             documented behavior of the `local`/`ci`/`e2e` environments.
+ *
+ * @since 11.27.5
+ */
+export function resolveServerUrls(input: {
+  appUrl?: string;
+  baseUrl?: string;
+  deriveAppUrl?: boolean;
+  env?: string;
+}): IResolvedServerUrls {
+  const usesLocalhostDefaults = LOCALHOST_URL_ENVS.includes(input.env ?? '');
+
+  let baseUrl = input.baseUrl;
+  let baseUrlSource: IResolvedServerUrls['baseUrlSource'] = baseUrl ? 'explicit' : 'none';
+  if (!baseUrl && usesLocalhostDefaults) {
+    baseUrl = LOCALHOST_URL_DEFAULTS.apiUrl;
+    baseUrlSource = 'localhost-default';
+  }
+
+  if (input.appUrl) {
+    return { appUrl: input.appUrl, appUrlSource: 'explicit', baseUrl, baseUrlSource };
+  }
+
+  // API on :3000 and app on :3001 — deriving from baseUrl would yield the API's own origin.
+  if (usesLocalhostDefaults && isLocalhostUrl(baseUrl)) {
+    return { appUrl: LOCALHOST_URL_DEFAULTS.appUrl, appUrlSource: 'localhost-default', baseUrl, baseUrlSource };
+  }
+
+  if (baseUrl && input.deriveAppUrl !== false) {
+    return { appUrl: deriveAppUrlFromBaseUrl(baseUrl), appUrlSource: 'derived', baseUrl, baseUrlSource };
+  }
+
+  return { appUrl: undefined, appUrlSource: 'none', baseUrl, baseUrlSource };
+}
+
 /**
  * Builds a CORS configuration object from server options.
  *
@@ -244,21 +428,30 @@ export function isCorsDisabled(cors: boolean | ICorsConfig | undefined): boolean
  * 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
+ * 4. `cors.allowedOrigins` + resolved `appUrl`/`baseUrl` → deduplicated origin list
+ * 5. Only resolved `appUrl`/`baseUrl` → those origins
  * 6. Nothing configured → `{}` (no credentialed CORS — caller decides fallback)
  *
+ * `appUrl`/`baseUrl` are resolved via {@link resolveServerUrls}, the same function BetterAuth
+ * uses, so all three CORS layers (GraphQL, REST, BetterAuth `trustedOrigins`) agree.
+ *
  * 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`
+ * Security notes:
+ * - 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.
+ * - Configuring only `baseUrl` grants credentialed CORS to the derived app origin as well
+ *   (`https://api.example.com` → also `https://example.com`). This is the documented
+ *   `appUrl` auto-detection and matches BetterAuth's `trustedOrigins`. Deployments whose
+ *   apex domain is not trusted (e.g. a third-party-hosted marketing site) must opt out with
+ *   `cors.deriveAppUrl: false` and list the real frontend origin explicitly.
+ *
+ * @param options - Server options containing `cors`, `cookies`, `appUrl`, `baseUrl`, `env`
  * @returns CORS config object for Apollo/Express, or empty object if disabled/unconfigured
  *
  * @since 11.25.0
@@ -279,10 +472,23 @@ export function buildCorsConfig(options: Partial<IServerOptions>): Record<string
     return { credentials: true, origin: true };
   }
 
-  // Build origin list from appUrl, baseUrl, and allowedOrigins
+  // Build origin list from the shared URL resolution (appUrl auto-derived from baseUrl,
+  // localhost defaults for local/ci/e2e), then allowedOrigins.
+  const { appUrl, baseUrl } = resolveServerUrls({
+    appUrl: options?.appUrl,
+    baseUrl: options?.baseUrl,
+    deriveAppUrl: corsObj.deriveAppUrl,
+    env: options?.env,
+  });
+
+  // Normalize to origins before deduplicating: a browser's `Origin` header is always a bare
+  // scheme://host[:port] triple, so a configured `https://api.example.com/` (trailing slash —
+  // common in env-var-sourced URLs) could never match, and would defeat the Set below.
+  // Values we cannot normalize are passed through verbatim rather than dropped.
   const origins: string[] = [];
-  if (options?.appUrl) origins.push(options.appUrl);
-  if (options?.baseUrl) origins.push(options.baseUrl);
+  for (const url of [appUrl, baseUrl]) {
+    if (url) origins.push(toHttpOrigin(url) ?? url);
+  }
   if (corsObj.allowedOrigins?.length) {
     origins.push(...corsObj.allowedOrigins);
   }

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

@@ -1032,6 +1032,28 @@ export interface ICorsConfig {
    */
   allowedOrigins?: string[];
 
+  /**
+   * Whether `appUrl` may be auto-derived from `baseUrl` when it is not set explicitly.
+   *
+   * By default the leading `api.` label is stripped from `baseUrl`'s hostname
+   * (`https://api.example.com` → `https://example.com`), and the result is trusted by all
+   * three CORS layers (GraphQL, REST, BetterAuth `trustedOrigins`). This is what makes the
+   * common `api.<host>` / `<host>` deployment work without extra configuration.
+   *
+   * Set to `false` when the derived apex domain must NOT receive credentialed cross-origin
+   * access — for example when `example.com` is a third-party-hosted marketing site whose
+   * XSS surface you do not control. With `false`, configure the frontend origin explicitly
+   * via `appUrl` or `allowedOrigins`.
+   *
+   * Has no effect on the localhost defaults applied for `env: 'local' | 'ci' | 'e2e'`, and
+   * no effect when `appUrl` is set explicitly.
+   *
+   * @default true
+   *
+   * @since 11.27.5
+   */
+  deriveAppUrl?: boolean;
+
   /**
    * Whether CORS is enabled.
    *