@lenne.tech/nest-server 11.27.5 → 11.27.6

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

@@ -273,8 +273,7 @@ export const LOCALHOST_URL_ENVS: readonly string[] = ['ci', 'e2e', 'local'];
 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.
+ * 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`).
@@ -282,7 +281,7 @@ const API_HOST_LABEL = 'api.';
  * `credentials: true` allowlist would grant credentialed access to any site able to frame a
  * sandboxed document.
  */
-function toHttpOrigin(value: string): string | undefined {
+function toHttpUrl(value: string): undefined | URL {
   let url: URL;
   try {
     url = new URL(value);
@@ -294,7 +293,15 @@ function toHttpOrigin(value: string): string | undefined {
     return undefined;
   }
 
-  return url.origin;
+  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;
 }
 
 /**
@@ -316,7 +323,8 @@ function isLocalhostUrl(value: string | undefined): boolean {
 }
 
 /**
- * Whether stripping the leading `api.` label from the hostname leaves a deployable host.
+ * 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
@@ -326,14 +334,65 @@ function isLocalhostUrl(value: string | undefined): boolean {
  *   `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.
  */
-function canStripApiLabel(hostname: string): boolean {
+export function strippedApiHostname(hostname: string): string | undefined {
   if (!hostname.startsWith(API_HOST_LABEL)) {
-    return false;
+    return undefined;
   }
 
   const remainder = hostname.slice(API_HOST_LABEL.length);
-  return remainder === 'localhost' || remainder.includes('.');
+  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';
 }
 
 /**
@@ -341,6 +400,8 @@ function canStripApiLabel(hostname: string): boolean {
  * 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.
@@ -348,17 +409,8 @@ function canStripApiLabel(hostname: string): boolean {
  * @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;
+  const url = toHttpUrl(baseUrl);
+  return url ? deriveAppOriginFromUrl(url) : baseUrl;
 }
 
 /**
@@ -378,15 +430,22 @@ export interface IResolvedServerUrls {
  * 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.
+ * `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.
+ *                             documented behavior of the `local`/`ci`/`e2e` environments, and
+ *                             a host-split localhost `baseUrl` falls back to them.
  *
  * @since 11.27.5
  */
@@ -409,13 +468,29 @@ export function resolveServerUrls(input: {
     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)) {
+  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 && input.deriveAppUrl !== false) {
-    return { appUrl: deriveAppUrlFromBaseUrl(baseUrl), appUrlSource: 'derived', 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 };

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
    */
@@ -1337,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`)
    *
@@ -1362,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;
@@ -2784,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
    *     },
@@ -2795,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,
       },
     },

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

@@ -7,7 +7,7 @@ import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { resolveServerUrls } from '../../common/helpers/cookies.helper';
+import { resolveServerUrls, strippedApiHostname } from '../../common/helpers/cookies.helper';
 import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface';
 import { detectCookiePrefixDrift, resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper';
 
@@ -380,15 +380,47 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
     );
   }
 
+  // Better-Auth base URL (resolved localhost defaults → explicit config → fallback).
+  const betterAuthBaseUrl = resolvedUrls.baseUrl || config.baseUrl || 'http://localhost:3000';
+  // The `Secure` attribute Better-Auth WOULD derive for its cookies if `useSecureCookies`
+  // were not pinned below: an `https://` baseURL is Better-Auth's own signal
+  // (createCookieGetter → `baseURLString.startsWith('https://')`). We keep exactly this value so
+  // the pinned `useSecureCookies: false` (needed for name alignment, see below) does not silently
+  // strip `Secure` from the cookies Better-Auth's native handlers forward.
+  const secureCookies = betterAuthBaseUrl.startsWith('https://');
+
   const betterAuthConfig: Record<string, unknown> = {
     advanced: {
       cookiePrefix,
       ...(crossSubDomain.enabled && {
         crossSubDomainCookies: { domain: crossSubDomain.domain, enabled: true },
       }),
+      // Keep Better-Auth's NATIVE handlers on the SAME cookie name the
+      // nest-server cookie helpers actually write. Those helpers always emit
+      // the UNPREFIXED `<cookiePrefix>.session_token`. Better-Auth, left to its
+      // own devices on an `https://` baseURL, auto-enables secure cookies AND
+      // prefixes the name with `__Secure-`, so its native handlers (2FA
+      // enable/disable, passkey register/list, backup codes, `/token`) look for
+      // `__Secure-<cookiePrefix>.session_token` — a cookie that is never written
+      // — and return `401 UNAUTHORIZED`, while the project's own session
+      // resolver (which reads the unprefixed cookie) still returns a session: a
+      // split-brain where `GET /iam/get-session` is 200 but every sensitive
+      // Better-Auth endpoint is 401. Pinning `useSecureCookies: false` keeps the
+      // native read path aligned with the cookie helper.
+      useSecureCookies: false,
+      // …BUT `useSecureCookies: false` also forces `secure: false` on EVERY cookie
+      // Better-Auth sets (createCookieGetter → `secure: !!secureCookiePrefix`), and the
+      // native handlers forward their `Set-Cookie` VERBATIM via `sendWebResponse`
+      // (2FA verify, social callback, magic link, passkey) WITHOUT passing through the
+      // cookie helper — so those session cookies would ship without `Secure` in
+      // production. Restore the exact Secure flag Better-Auth itself would have derived
+      // (an `https://` baseURL), keeping the unprefixed NAME while preserving the
+      // `Secure` TRANSPORT flag. Only injected on https so http/local and a consumer's
+      // own `options.advanced.useSecureCookies` override are left untouched.
+      ...(secureCookies && { defaultCookieAttributes: { secure: true } }),
     },
     basePath,
-    baseURL: resolvedUrls.baseUrl || config.baseUrl || 'http://localhost:3000',
+    baseURL: betterAuthBaseUrl,
     database: mongodbAdapter(db),
     // Enable email/password authentication by default (required by Better-Auth 1.x)
     // Can be disabled by setting config.emailAndPassword.enabled = false
@@ -681,12 +713,20 @@ function buildSocialProviders(config: IBetterAuth): Record<string, SocialProvide
  *
  * Behavior (in priority order):
  * 1. Explicit betterAuth.trustedOrigins → use those (always takes precedence)
- * 2. Server CORS disabled → empty array (BetterAuth CORS also disabled)
- * 3. Server CORS allowAll → undefined (BetterAuth allows all origins)
+ * 2. Server CORS disabled → empty array (adds no extra trusted origins beyond BetterAuth's own
+ *    baseURL — see NOTE; it does NOT switch BetterAuth's origin check off)
+ * 3. Server CORS allowAll → fall through to rules 4-7 (see below)
  * 4. Server CORS allowedOrigins → merge with appUrl/baseUrl
  * 5. Passkey trustedOrigins → use from normalizePasskeyConfig()
  * 6. Fallback to resolved appUrl
- * 7. Otherwise → undefined (allows all origins via Better-Auth's default)
+ * 7. Otherwise → undefined (Better-Auth then trusts only its own baseURL)
+ *
+ * NOTE on rules 2 and 7: neither an empty array (rule 2) nor `undefined` (rule 7) means "any
+ * origin is allowed", and neither disables BetterAuth's origin check. In both cases BetterAuth
+ * still derives and trusts its own `baseURL` origin (see `getTrustedOrigins()` in
+ * `better-auth/context`, which unconditionally pushes `new URL(baseURL).origin` before appending
+ * `options.trustedOrigins`), so `[]` and `undefined` are behaviorally identical here: a
+ * separately hosted frontend is still rejected by every origin-checked endpoint.
  *
  * @param config - Better-auth configuration
  * @param options - Passkey normalization, resolved URLs, and server CORS context
@@ -706,15 +746,25 @@ export function buildTrustedOrigins(
     return config.trustedOrigins;
   }
 
-  // 2. Server CORS disabled → BetterAuth CORS also disabled
+  // 2. Server CORS disabled → add no extra trusted origins. BetterAuth still trusts its own
+  //    baseURL (see the NOTE above), so this does NOT turn its origin check off — it only means
+  //    "no separately hosted frontend is trusted". Behaviorally identical to rule 7's undefined.
   if (serverCorsConfig === false || (typeof serverCorsConfig === 'object' && serverCorsConfig?.enabled === false)) {
     return [];
   }
 
-  // 3. Server CORS allowAll → BetterAuth allows all origins
-  if (typeof serverCorsConfig === 'object' && serverCorsConfig?.allowAll) {
-    return undefined;
-  }
+  // 3. Server CORS allowAll → fall through to the appUrl / passkey rules below.
+  //
+  // This used to `return undefined` in the belief that BetterAuth then "allows all
+  // origins". It does not: without trustedOrigins BetterAuth trusts only its own
+  // baseURL, so the *app* origin is rejected and every origin-checked endpoint
+  // (two-factor/enable, passkey) answers 403 INVALID_ORIGIN. That silently broke
+  // 2FA and passkeys in exactly the setups that use allowAll — local dev and CI.
+  //
+  // An origin check has no meaningful "allow everything" mode — that is the very
+  // thing it defends against — so allowAll now yields the known-good origins
+  // (appUrl, passkey) instead of none. Projects that really do want to accept
+  // arbitrary origins can still set `betterAuth.trustedOrigins` explicitly (rule 1).
 
   // 4. Server allowedOrigins → merge with appUrl/baseUrl.
   // Order (appUrl, baseUrl, allowedOrigins) mirrors buildCorsConfig() in cookies.helper.ts
@@ -1183,6 +1233,17 @@ export function resolveCrossSubDomainCookies(
  * 3. Use baseUrl hostname as-is
  *
  * Returns undefined for localhost (cross-subdomain not meaningful there).
+ *
+ * The `api.` strip reuses {@link strippedApiHostname} so it shares that helper's guard against
+ * bogus results: `api.dev` → `dev` would set a public-suffix cookie domain that browsers reject
+ * outright (dropping every session cookie), so `api.dev` is kept as-is instead.
+ *
+ * KNOWN LIMITATION (fails closed, no leak): the single-label guard cannot recognise a MULTI-label
+ * public suffix — `api.co.uk` still strips to `co.uk`, a Public-Suffix-List entry browsers also
+ * reject, so cross-subdomain auth would break (cookie dropped) rather than over-scope. A full PSL
+ * check would need a dependency, which this security-critical module deliberately avoids; for such
+ * apex domains set `betterAuth.crossSubDomainCookies.domain` explicitly instead of relying on
+ * derivation. See migration guide 11.27.5 → 11.27.6.
  */
 function deriveCookieDomainFromUrls(appUrl?: string, baseUrl?: string): string | undefined {
   // Priority 1: appUrl hostname (this IS the parent domain in typical setups)
@@ -1204,11 +1265,9 @@ function deriveCookieDomainFromUrls(appUrl?: string, baseUrl?: string): string |
       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;
+      // Strip api. prefix to get parent domain — but keep the host unchanged when stripping
+      // would leave a bare TLD (`api.dev`) or empty host (`api.`).
+      return strippedApiHostname(hostname) ?? hostname;
     } catch {
       return undefined;
     }

package/src/core/modules/migrate/migration-runner.ts

@@ -19,13 +19,27 @@ export interface MigrationFile {
   up: () => Promise<void>;
 }
 
+/**
+ * Default file pattern for migration files: `*.ts` and `*.js`, but never `*.d.ts`.
+ *
+ * A compiled migration ships `foo.js` next to `foo.d.ts` (whenever the project
+ * builds with `declaration: true`). A plain `/\.(ts|js)$/` matches the
+ * declaration file too, so the runner would load it as a *second* migration and
+ * throw — `export declare …` is not valid CommonJS.
+ *
+ * The lookbehind guards the `.ts` branch only. Writing it as `(?<!\.d)\.(ts|js)$`
+ * would also reject a perfectly valid `foo.d.js`, since `.d` precedes `.js` there
+ * as well.
+ */
+export const DEFAULT_MIGRATION_FILE_PATTERN = /(?:(?<!\.d)\.ts|\.js)$/;
+
 /**
  * Migration runner configuration
  */
 export interface MigrationRunnerOptions {
   /** Directory containing migration files */
   migrationsDirectory: string;
-  /** Pattern to match migration files (default: *.ts, *.js) */
+  /** Pattern to match migration files (default: {@link DEFAULT_MIGRATION_FILE_PATTERN}) */
   pattern?: RegExp;
   /** State store for tracking migrations */
   stateStore: MongoStateStore;
@@ -59,7 +73,7 @@ export class MigrationRunner {
 
   constructor(options: MigrationRunnerOptions) {
     this.options = options;
-    this.pattern = options.pattern || /\.(ts|js)$/;
+    this.pattern = options.pattern || DEFAULT_MIGRATION_FILE_PATTERN;
   }
 
   /**