@lenne.tech/nest-server 11.27.4 → 11.27.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.27.4",
+  "version": "11.27.6",
   "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",
@@ -48,8 +48,9 @@
     "start:dev:swc": "nest start -b swc -w --type-check",
     "start:local": "NODE_ENV=local nodemon",
     "start:local:swc": "NODE_ENV=local nest start -b swc -w --type-check",
-    "test": "pnpm run vitest",
-    "test:ci": "pnpm run vitest:ci",
+    "test": "pnpm run vitest:unit && pnpm run vitest",
+    "test:ci": "pnpm run vitest:unit && pnpm run vitest:ci",
+    "test:cov": "pnpm run vitest:unit:cov && pnpm run vitest:cov",
     "test:e2e": "pnpm run vitest",
     "prepack": "pnpm run prestart:prod",
     "prepublishOnly": "pnpm run lint && pnpm run test:ci",
@@ -59,6 +60,7 @@
     "vitest:cov": "NODE_ENV=e2e vitest run --coverage --config vitest-e2e.config.ts",
     "vitest:watch": "NODE_ENV=e2e vitest --config vitest-e2e.config.ts",
     "vitest:unit": "vitest run --config vitest.config.ts",
+    "vitest:unit:cov": "vitest run --coverage --config vitest.config.ts",
     "test:unit:watch": "vitest --config vitest.config.ts",
     "test:types": "tsc --noEmit --skipLibCheck -p tests/types/tsconfig.json",
     "test:cleanup": "find tests -type f \\( -name '*.txt' -o -name '*.bin' \\) -not -name '.gitkeep' -delete && echo 'Test artifacts cleaned up'",
@@ -72,12 +74,12 @@
     "url": "https://github.com/lenneTech/nest-server/issues"
   },
   "engines": {
-    "node": ">= 20"
+    "node": ">= 22"
   },
   "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 +98,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",
@@ -211,12 +213,15 @@
       "follow-redirects@<=1.15.11": "Security: Custom Authentication Headers leak on cross-domain redirect (GHSA-r4q5-vmmm-2653) - transitive via axios>@getbrevo/brevo and axios>node-mailjet",
       "uuid@<14.0.0": "Security: Missing buffer bounds check in v3/v5/v6 (GHSA-w5hq-g745-h8pq) - transitive via @compodoc/compodoc and @compodoc/compodoc>@compodoc/live-server>http-auth",
       "postcss@<8.5.10": "Security: XSS via Unescaped </style> in CSS Stringify Output (GHSA-qx2v-qp2m-jg93) - transitive via vite. Remove when vite ships with postcss>=8.5.10",
+      "esbuild@>=0.17.0 <0.28.1": "Security: esbuild dev-server responds to any request origin, letting any website the developer visits read files it serves (GHSA-67mh-4wv8-2f99, moderate); pinned to the latest patched release to keep esbuild aligned across the toolchain - dev-only, transitive via vite>vitest and @nestjs build tooling. Remove when all consumers resolve esbuild>=0.28.1",
       "form-data@<4.0.6": "Security: CRLF injection via unescaped multipart field names/filenames (GHSA-hmw2-7cc7-3qxx) - transitive via @getbrevo/brevo>axios and node-mailjet>axios",
       "vite@>=8.0.0 <8.0.16": "Security: fs.deny bypass on Windows alternate paths + file read CVEs - transitive via better-auth>vitest",
       "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",
+      "morgan@<1.11.0": "Security: Log Forging via unneutralized control characters in :remote-user (GHSA-4vj7-5mj6-jm8m, moderate, patched in 1.11.0) - dev-only, transitive via @compodoc/compodoc>@compodoc/live-server>morgan"
     },
     "overrides": {
       "axios@<1.16.0": "1.16.0",
@@ -252,7 +257,9 @@
       "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",
+      "morgan@<1.11.0": "1.11.0"
     },
     "//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,265 @@ 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.';
+
+/**
+ * Parses a URL string into a `URL`, or returns `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 toHttpUrl(value: string): undefined | URL {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return undefined;
+  }
+
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    return undefined;
+  }
+
+  return url;
+}
+
+/**
+ * Normalizes a URL string to its http(s) origin, or `undefined` when it is not a usable
+ * http(s) URL. See {@link toHttpUrl} for why the protocol guard matters.
+ */
+function toHttpOrigin(value: string): string | undefined {
+  return toHttpUrl(value)?.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;
+  }
+}
+
+/**
+ * The hostname with its leading `api.` label removed, or `undefined` when the label is absent
+ * or stripping it would not leave 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`).
+ *
+ * Exported for reuse by BetterAuth's `deriveCookieDomainFromUrls()`, so the cookie-domain
+ * derivation shares this bare-TLD/empty guard instead of re-implementing a naive `api.`-strip.
+ */
+export function strippedApiHostname(hostname: string): string | undefined {
+  if (!hostname.startsWith(API_HOST_LABEL)) {
+    return undefined;
+  }
+
+  const remainder = hostname.slice(API_HOST_LABEL.length);
+  if (remainder !== 'localhost' && !remainder.includes('.')) {
+    return undefined;
+  }
+
+  return remainder;
+}
+
+/**
+ * Derives the app origin from an already-parsed API base `URL` by stripping a leading `api.`
+ * label from its hostname. Mutates and re-serializes the passed `URL`, so callers must not
+ * reuse it afterwards. Shared by {@link deriveAppUrlFromBaseUrl} (string entry point) and
+ * {@link resolveServerUrls} (which parses `baseUrl` once and threads the result through).
+ */
+function deriveAppOriginFromUrl(url: URL): string {
+  const stripped = strippedApiHostname(url.hostname);
+  if (stripped !== undefined) {
+    url.hostname = stripped;
+  }
+
+  return url.origin;
+}
+
+/**
+ * Whether stripping the `api.` label from `baseUrl` names a host the API itself is NOT served
+ * from — i.e. API and app are separated by HOST rather than by PORT.
+ *
+ * {@link LOCALHOST_URL_DEFAULTS} encode a port split: one host, API on `:3000`, app on `:3001`.
+ * `http://api.localhost:3000` and `https://api.localhost` are both that shape — the label
+ * strips to the bare `localhost` the API already answers on, so only the port tells app and API
+ * apart, and the flat `http://localhost:3001` default is the right answer.
+ *
+ * `https://api.crm.localhost` (as served by `lt dev up` behind Caddy) strips to the sibling host
+ * `crm.localhost`, which the API never answers on. There the derivation names the real app
+ * origin and must win over the flat default.
+ *
+ * Keyed on the stripped LABEL, never on the presence of a port: a host split stays a host split
+ * behind a non-default port (`https://api.crm.localhost:8443` → `https://crm.localhost:8443`),
+ * and a port split stays a port split on the default port (`https://api.localhost`).
+ *
+ * Takes an already-parsed `URL` (or `undefined` for an unparseable/absent `baseUrl`) so the
+ * caller parses `baseUrl` only once.
+ */
+function separatesApiAndAppByHost(url: undefined | URL): boolean {
+  if (!url) {
+    return false;
+  }
+
+  const stripped = strippedApiHostname(url.hostname);
+  return stripped !== undefined && stripped !== 'localhost';
+}
+
+/**
+ * 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`).
+ *
+ * The port is preserved (`https://api.example.com:8443` → `https://example.com:8443`).
+ *
+ * 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 url = toHttpUrl(baseUrl);
+  return url ? deriveAppOriginFromUrl(url) : baseUrl;
+}
+
+/**
+ * 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 → derived from a host-split localhost `baseUrl` (local/ci/e2e) →
+ * localhost default (local/ci/e2e with a localhost `baseUrl`) → derived from `baseUrl` → none.
+ *
+ * The localhost defaults assume a PORT split (API `:3000`, app `:3001`, one host). A localhost
+ * `baseUrl` whose `api.` label strips to a SIBLING host — `https://api.crm.localhost` from
+ * `lt dev up` — derives that host on whatever port it carries, because the flat
+ * `http://localhost:3001` default would name a host the app never serves from. See
+ * {@link separatesApiAndAppByHost}.
+ *
+ * `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, and
+ *                             a host-split localhost `baseUrl` falls back to them.
+ *
+ * @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 };
+  }
+
+  const mayDerive = input.deriveAppUrl !== false;
+
+  // Parse `baseUrl` once and reuse the result for both the host-split check and the derivation
+  // below (the localhost check keeps its own string parse — its loopback-IP matching differs
+  // from `toHttpUrl`'s http(s)-only guard). Gated on `mayDerive`: both consumers of
+  // `parsedBaseUrl` sit behind it (the host-split check via short-circuit, the derivation via its
+  // own guard), so with `deriveAppUrl: false` the parse is never needed and is skipped entirely.
+  const parsedBaseUrl = baseUrl && mayDerive ? toHttpUrl(baseUrl) : undefined;
+
+  // API on :3000 and app on :3001 — deriving from a port-split baseUrl would yield the API's
+  // own origin. A baseUrl that splits API and app by host instead (`https://api.crm.localhost`,
+  // from `lt dev up`) derives the real app origin, so prefer it over the flat default.
+  // `separatesApiAndAppByHost` is evaluated last, so every deployed (non-localhost) environment
+  // short-circuits before paying for the parse.
+  if (usesLocalhostDefaults && isLocalhostUrl(baseUrl) && !(mayDerive && separatesApiAndAppByHost(parsedBaseUrl))) {
+    return { appUrl: LOCALHOST_URL_DEFAULTS.appUrl, appUrlSource: 'localhost-default', baseUrl, baseUrlSource };
+  }
+
+  if (baseUrl && mayDerive) {
+    // `parsedBaseUrl` is mutated by `deriveAppOriginFromUrl`; a non-http(s) `baseUrl` (parse
+    // failed) is returned verbatim, matching `deriveAppUrlFromBaseUrl`.
+    const appUrl = parsedBaseUrl ? deriveAppOriginFromUrl(parsedBaseUrl) : baseUrl;
+    return { appUrl, appUrlSource: 'derived', baseUrl, baseUrlSource };
+  }
+
+  return { appUrl: undefined, appUrlSource: 'none', baseUrl, baseUrlSource };
+}
+
 /**
  * Builds a CORS configuration object from server options.
  *
@@ -244,21 +503,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 +547,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

@@ -1012,8 +1012,17 @@ export interface ICorsConfig {
    * 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).
+   * When true, overrides `allowedOrigins`.
+   *
+   * **This does NOT disable BetterAuth's origin check.** BetterAuth keeps
+   * verifying the `Origin` header against its `trustedOrigins`, which are derived
+   * from `appUrl` (and the passkey config). Leaving `trustedOrigins` empty would
+   * not "allow everything" — BetterAuth then trusts only its own `baseURL`, and
+   * origin-checked endpoints such as `two-factor/enable` or passkey registration
+   * answer `403 INVALID_ORIGIN` for a separately hosted frontend.
+   *
+   * To accept arbitrary origins for auth as well, set `betterAuth.trustedOrigins`
+   * explicitly — an origin check has no meaningful "allow everything" mode.
    *
    * @default false
    */
@@ -1032,6 +1041,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.
    *
@@ -1315,13 +1346,19 @@ export interface IServerOptions {
    * - Frontend redirect URLs
    *
    * **Auto-Detection from `baseUrl`:**
-   * If not set, `appUrl` is derived from `baseUrl`:
+   * If not set, `appUrl` is derived from `baseUrl` (the port is preserved):
    * - `https://api.example.com` → `https://example.com` (removes 'api.' prefix)
    * - `https://example.com` → `https://example.com` (unchanged)
    *
    * **Localhost Environment Defaults:**
-   * When `env` is 'local', 'ci', or 'e2e' and neither `baseUrl` nor `appUrl` is set:
-   * - `appUrl` defaults to `http://localhost:3001`
+   * When `env` is 'local', 'ci', or 'e2e', `appUrl` is not set, and `baseUrl` is unset or points at
+   * localhost, `appUrl` defaults to `http://localhost:3001`. These defaults encode a PORT split:
+   * one host, API on `:3000`, app on `:3001`.
+   *
+   * A localhost `baseUrl` whose `api.` label strips to a SIBLING host is a HOST split and is
+   * derived instead — `https://api.crm.localhost` → `https://crm.localhost`, as served by
+   * `lt dev up` behind Caddy. `https://api.localhost` strips to the bare `localhost` the API
+   * already answers on, so it keeps the `http://localhost:3001` default.
    *
    * **Environment Variable:** `APP_URL` (only needed if not auto-derivable from `BASE_URL`)
    *
@@ -1340,6 +1377,11 @@ export interface IServerOptions {
    * env: 'local', // or 'ci' or 'e2e'
    * // baseUrl defaults to 'http://localhost:3000'
    * // appUrl defaults to 'http://localhost:3001'
+   *
+   * // Local/CI/E2E behind `lt dev up` (host split — appUrl auto-derived)
+   * env: 'local',
+   * baseUrl: 'https://api.crm.localhost',
+   * // → appUrl auto-derived: 'https://crm.localhost'
    * ```
    */
   appUrl?: string;
@@ -2762,7 +2804,8 @@ interface IBetterAuthBase {
    *   },
    *   advanced: {
    *     cookiePrefix: 'my-app',
-   *     useSecureCookies: true,
+   *     useSecureCookies: true, // re-enables the __Secure- prefix; safe ONLY when Better-Auth
+   *                             // fully manages your cookies — see the note below.
    *     crossSubDomainCookies: {
    *       domain: 'example.com', // Cookies shared across *.example.com
    *     },
@@ -2773,6 +2816,14 @@ interface IBetterAuthBase {
    * **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`.
+   *
+   * **`useSecureCookies` is pinned to `false` by default (since v11.27.6).** The framework keeps
+   * Better-Auth's native handlers on the same UNPREFIXED cookie name the nest-server cookie helper
+   * writes; the `Secure` attribute is still applied on an `https://` baseURL via
+   * `advanced.defaultCookieAttributes`, so transport security is unchanged. Only set
+   * `useSecureCookies: true` if Better-Auth manages your session cookies entirely (not the
+   * nest-server helper) — otherwise its native handlers look for a `__Secure-`-prefixed cookie the
+   * helper never writes and answer `401` on 2FA / passkey / `/token`.
    */
   options?: Record<string, unknown>;
 

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

@@ -262,10 +262,10 @@ Read the security section below for production deployments.
 
 **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)                                 |
+| 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 the REST/GraphQL layers; `cors.allowAll` mirrors any request origin for REST/GraphQL (dev only) but BetterAuth keeps restricting to `appUrl` (its origin check has no "allow all" mode) |
 
 **For Development:** The defaults (`http://localhost:3000`, `/iam`) are correct.
 
@@ -725,6 +725,12 @@ const config = {
       },
       advanced: {
         cookiePrefix: 'my-app',
+        // Since v11.27.6 the framework pins `useSecureCookies: false` so Better-Auth's native
+        // handlers read the same UNPREFIXED cookie the nest-server helper writes (the `Secure`
+        // attribute is still applied on https via `advanced.defaultCookieAttributes`). Only set
+        // `true` if Better-Auth manages your cookies entirely — otherwise its native handlers
+        // look for a `__Secure-`-prefixed cookie that is never written and answer 401 on
+        // 2FA / passkey / `/token`.
         useSecureCookies: true,
       },
     },