@lenne.tech/nest-server 11.27.5 → 11.27.6

package/docs/REQUEST-LIFECYCLE.md

@@ -457,18 +457,31 @@ if (!isCorsDisabled(envConfig.cors)) {
 
 | Config | REST (Express) | GraphQL (Apollo) | BetterAuth |
 |--------|----------------|-------------------|------------|
-| `cors: { allowAll: true }` | `origin: true` | `origin: true` | `trustedOrigins: undefined` |
+| `cors: { allowAll: true }` | `origin: true` | `origin: true` | `trustedOrigins: [appUrl] (+ passkey origins)` |
 | `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 |
 
+> **BetterAuth has no "allow all origins" mode (since v11.27.6).** `cors.allowAll` mirrors the request origin for REST/GraphQL, but BetterAuth's origin check is a security control with no meaningful "allow everything" setting. So `allowAll` yields the known-good origins (`appUrl` + any passkey origins), NOT `undefined` — returning nothing there would leave BetterAuth trusting only its own `baseURL` and silently answer `403 INVALID_ORIGIN` for a separately hosted frontend on `two-factor/enable`, passkey registration, etc. For the same reason `trustedOrigins: []` (the `enabled: false` row) does **not** switch the origin check off: BetterAuth always trusts its own `baseURL`, so `[]` and `undefined` behave identically. To accept arbitrary origins for auth, set `betterAuth.trustedOrigins` explicitly.
+
 **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`
+2. `env: 'local' | 'ci' | 'e2e'` with a localhost `baseUrl` that splits API and app by **host** → derived from `baseUrl` (see below)
+3. `env: 'local' | 'ci' | 'e2e'` with any other localhost `baseUrl` → `appUrl` defaults to `http://localhost:3001`
+4. otherwise derived from `baseUrl` by stripping a leading `api.` label (`https://api.example.com` → `https://example.com`), unless `cors.deriveAppUrl: false`
+
+**Port split vs. host split (step 2 vs. 3, since v11.27.6).** The localhost defaults encode a *port split*: one host, API on `:3000`, app on `:3001`. `lt dev up` instead serves a *host split* behind Caddy — API on `https://api.<slug>.localhost`, app on `https://<slug>.localhost`. The two are told apart by what the `api.` label strips to, never by the port:
+
+| `baseUrl` (`env: 'local'`) | Split | Resolved `appUrl` |
+|---------------------------|-------|-------------------|
+| `https://api.crm.localhost` | host | `https://crm.localhost` |
+| `https://api.crm.localhost:8443` | host | `https://crm.localhost:8443` |
+| `https://api.localhost` | port (strips to the bare host the API answers on) | `http://localhost:3001` |
+| `http://api.localhost:3000` | port | `http://localhost:3001` |
+| `http://localhost:3000` | port (no `api.` label) | `http://localhost:3001` |
 
-> **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.
+> **Security:** steps 2 and 4 grant 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. With `cors.deriveAppUrl: false`, a host-split localhost `baseUrl` falls back to the `http://localhost:3001` default.
 
 ### NestJS Middleware Chain (CoreModule)
 

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

@@ -0,0 +1,359 @@
+# Migration Guide: 11.27.5 → 11.27.6
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None. No existing signature, export, or Core class was removed or changed shape. |
+| **New Features** | Two additive exports: `DEFAULT_MIGRATION_FILE_PATTERN` (the migration runner's default file matcher) and `strippedApiHostname` (the `api.`-label strip helper). Purely additive — nothing existing changed. |
+| **Bugfixes** | (1) `resolveServerUrls()` ignored a host-split localhost `baseUrl` in `local`/`ci`/`e2e`: `https://api.crm.localhost` resolved `appUrl` to the flat `http://localhost:3001` default instead of deriving `https://crm.localhost`, blocking the frontend origin in the CORS allowlist, BetterAuth's `trustedOrigins`, and the Passkey `rpId`/`origin` for every `lt dev up` project. (2) `buildTrustedOrigins()` returned `undefined` for `cors.allowAll`, silently breaking 2FA/passkey. (3) `MigrationRunner`'s default pattern loaded `*.d.ts` declaration files as migrations and threw. (4) `bin/migrate.js` failed to find the CLI from vendored layouts. (5) BetterAuth's native handlers (2FA enable/verify, passkey register/list, backup codes, `/token`) returned `401 UNAUTHORIZED` on an `https://` baseURL because BetterAuth auto-prefixed its session cookie with `__Secure-` while the nest-server cookie helper writes the unprefixed name — a split-brain where `GET /iam/get-session` was `200` but every sensitive native endpoint was `401`. (6) `deriveCookieDomainFromUrls()` collapsed `api.<bare-TLD>` (e.g. `api.dev`) to the browser-rejected public suffix `dev`, dropping every cross-subdomain session cookie. |
+| **Behavior Changes** | Five consumer-visible shifts — see [Behavior changes in framework source](#behavior-changes-in-framework-source): the host-split `appUrl` derivation above (an `api.*.localhost` `baseUrl` with no explicit `appUrl` now derives the sibling host instead of `localhost:3001`); `cors.allowAll` now yields `[appUrl]` for BetterAuth `trustedOrigins`; the migration runner's default pattern now skips `*.d.ts`; BetterAuth's native session cookie loses its `__Secure-` prefix (the `Secure` attribute is preserved), opt-out via `betterAuth.options.advanced.useSecureCookies`; and the cross-subdomain cookie domain keeps `api.<bare-TLD>` as-is instead of collapsing to a public suffix. |
+| **Security Updates** | None. The `allowAll` fix removes an availability bug (the origin check was never loosened), and the BetterAuth cookie-**name** change preserves the `Secure` attribute — `createBetterAuthInstance()` restores it via `advanced.defaultCookieAttributes` on an `https://` baseURL, so session-cookie confidentiality is unchanged on every path, including the native handlers that forward `Set-Cookie` verbatim. |
+| **Migration Effort** | 0 minutes (`pnpm update`) for the vast majority. A few edge cases need a one-line config: see [Behavior changes in framework source](#behavior-changes-in-framework-source). Optional: adopt the updated `scripts/check.mjs` / vitest configs / `test` scripts — see [Repo-internal tooling](#repo-internal-tooling). |
+
+This is a **follow-up bugfix to the URL unification shipped in 11.27.5**. The
+`api.`-strip derivation was already implemented and unit-tested for
+`api.<slug>.localhost` hosts, but `resolveServerUrls()` never reached it in the
+environments where those hosts actually occur. It also folds in three smaller
+framework-source fixes (BetterAuth `allowAll`, the migration file pattern, and
+the `bin/migrate.js` layout resolution) that shipped in the same release.
+
+---
+
+## Quick Migration
+
+No code changes required.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.6
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+---
+
+## What's Fixed in 11.27.6
+
+### `lt dev up` projects: the app origin was resolved to `localhost:3001`
+
+`resolveServerUrls()` checked `usesLocalhostDefaults && isLocalhostUrl(baseUrl)`
+**before** the derivation branch, and `isLocalhostUrl()` matches `*.localhost`
+subdomains. Any localhost `baseUrl` therefore short-circuited to the flat
+localhost default, and the derivation branch became unreachable in exactly the
+`local`/`ci`/`e2e` environments where `.localhost` hosts are used.
+
+That contradicted `strippedApiHostname()` (formerly `canStripApiLabel()`), which
+explicitly supports `api.localhost → localhost` ("`localhost` is the one
+legitimate single-label host"), and the existing unit test `should strip api. in
+front of localhost (lt dev: api.<slug>.localhost)`. The helper did the right
+thing; nothing called it on that path.
+
+| `env` | `baseUrl` | `appUrl` before | `appUrl` after |
+|-------|-----------|-----------------|----------------|
+| `local` | `https://api.crm.localhost` | `http://localhost:3001` | `https://crm.localhost` |
+| `local` | `https://api.crm.localhost:8443` | `http://localhost:3001` | `https://crm.localhost:8443` |
+| `local` | `https://api.nest-server.localhost` | `http://localhost:3001` | `https://nest-server.localhost` |
+| `local` | `https://api.localhost` | `http://localhost:3001` | unchanged |
+| `local` | `http://api.localhost:3000` | `http://localhost:3001` | unchanged |
+| `local` | `http://localhost:3000` | `http://localhost:3001` | unchanged |
+| `local` | `http://127.0.0.1:3000` | `http://localhost:3001` | unchanged |
+| `develop` | `https://api.example.com` | `https://example.com` | unchanged |
+
+### Port split vs. host split
+
+The localhost defaults encode a **port split**: one host, API on `:3000`, app on
+`:3001`. `lt dev up` instead serves a **host split** behind Caddy — API on
+`https://api.<slug>.localhost`, app on `https://<slug>.localhost`. Only the
+second shape can name a distinct app origin, so only it takes precedence over
+the localhost default.
+
+The two are told apart by **what the `api.` label strips to**, never by the port:
+
+- `api.crm.localhost` → `crm.localhost` — a sibling host the API never answers
+  on. **Host split**, derive it. This holds on any port, so
+  `https://api.crm.localhost:8443` derives `https://crm.localhost:8443`.
+- `api.localhost` → `localhost` — the bare host the API already answers on. Only
+  the port tells app and API apart. **Port split**, keep `http://localhost:3001`.
+  This holds whether or not a port is written out, so both
+  `http://api.localhost:3000` and `https://api.localhost` keep the default.
+
+> A port-based rule ("no explicit port ⇒ host split") looks equivalent on the two
+> most common inputs and is wrong on both edges: it sends `api.crm.localhost:8443`
+> back to `localhost:3001`, and it derives the unreachable `https://localhost`
+> (port 443) from `https://api.localhost`.
+
+### Impact per layer
+
+All three CORS layers share `resolveServerUrls()` since 11.27.5, so all three
+were affected identically:
+
+- **REST / GraphQL CORS:** the allowlist contained `http://localhost:3001`
+  instead of `https://<slug>.localhost`, so the frontend was blocked by
+  preflight. Projects whose local config sets `cors.allowAll: true` did **not**
+  see this — `allowAll` short-circuits before URL resolution.
+- **BetterAuth `trustedOrigins`:** taken straight from the resolved `appUrl`, so
+  the real frontend origin was not trusted.
+- **Passkey `rpId` / `origin`:** both auto-detected from `appUrl`, so `rpId`
+  resolved to `localhost` and `origin` to `http://localhost:3001` instead of the
+  `lt dev` host. Projects that set `betterAuth.passkey.rpId`/`origin` explicitly
+  were unaffected.
+
+**Not affected by this fix:** the `crossSubDomainCookies` domain. For the host-split
+`appUrl` derivation, `deriveCookieDomainFromUrls()` skips an `appUrl` whose hostname is
+exactly `localhost` and falls back to the `baseUrl` with its `api.` label stripped — so it
+already resolved to `crm.localhost` before this fix. (The function itself **did** change this
+release, but for a separate reason — the `api.<bare-TLD>` guard, [behavior change #5](#5-cross-subdomain-cookie-domain-keeps-apibare-tld-as-is) below.)
+
+Projects that set `APP_URL` explicitly were never affected — `lt dev up` exports
+both `BASE_URL` and `APP_URL`, and explicit values always win
+(`appUrlSource: 'explicit'`). The bug surfaced only when `baseUrl` was set
+without `appUrl`.
+
+---
+
+## Behavior changes in framework source
+
+All three ship inside the published `dist/` and reach every consumer via
+`pnpm update`. None changes an existing signature — they change what existing
+code *does* — so review this section even though the [Overview](#overview) lists
+no breaking changes.
+
+### 1. Host-split `appUrl` derivation (the primary fix)
+
+For `env: 'local' | 'ci' | 'e2e'`, a `baseUrl` whose `api.` label strips to a
+**sibling host** now derives that host instead of falling back to the flat
+`http://localhost:3001` default:
+
+| `env` | `baseUrl` (no `appUrl` set) | `appUrl` before | `appUrl` after |
+|-------|----------------------------|-----------------|----------------|
+| `local` | `https://api.crm.localhost` | `http://localhost:3001` | **`https://crm.localhost`** |
+| `local` | `https://api.localhost` | `http://localhost:3001` | `http://localhost:3001` (unchanged) |
+
+This is the intended fix for `lt dev up`, but it **is** a behavior change for any
+project that previously relied on the `localhost:3001` default while setting an
+`api.*.localhost` `baseUrl`. If your frontend really does run on
+`http://localhost:3001` (e.g. a plain `pnpm dev`, not behind Caddy), set
+`appUrl: 'http://localhost:3001'` or `cors.deriveAppUrl: false` — both suppress
+the derivation. `lt dev up` projects need no action (they export `APP_URL`).
+
+### 2. `cors.allowAll` no longer disables BetterAuth's origin check
+
+`buildTrustedOrigins()` used to `return undefined` for `cors.allowAll`, in the
+belief that BetterAuth then allowed all origins. It does not: without
+`trustedOrigins`, BetterAuth trusts **only its own `baseURL`** (its
+`getTrustedOrigins()` unconditionally pushes `new URL(baseURL).origin`), so the
+separately hosted app origin was rejected and every origin-checked endpoint
+(`two-factor/enable`, passkey registration) answered `403 INVALID_ORIGIN`. That
+silently broke 2FA and passkeys in exactly the setups that run with `allowAll` —
+local dev and CI.
+
+`allowAll` now falls through to the known-good origins (`appUrl` + passkey), so
+BetterAuth trusts the real app origin. An origin check has no meaningful "allow
+everything" mode; projects that genuinely need to accept arbitrary origins for
+auth must set `betterAuth.trustedOrigins` explicitly. **No action needed** unless
+you depended on the (broken) old behavior.
+
+### 3. Migration runner skips `*.d.ts`
+
+`MigrationRunner`'s default file pattern changed from `/\.(ts|js)$/` to
+`DEFAULT_MIGRATION_FILE_PATTERN` (`/(?:(?<!\.d)\.ts|\.js)$/`), which matches
+`foo.ts` / `foo.js` but not `foo.d.ts`. A compiled migration directory ships a
+declaration file next to each `.js`; the old pattern loaded it as a *second*
+migration and threw (`export declare …` is not valid CommonJS). Projects that
+passed an explicit `pattern` to `MigrationRunner` are unaffected. Projects on the
+default now correctly ignore declaration files. The pattern is exported as
+`DEFAULT_MIGRATION_FILE_PATTERN` if you need to extend rather than replace it.
+
+> `bin/migrate.js` also gained multi-layout CLI resolution (npm package, vendored
+> repo, vendored production image). This is transparent — it only widens where the
+> shim looks for the compiled CLI — and needs no action.
+
+### 4. BetterAuth native session cookie loses its `__Secure-` prefix (`Secure` preserved)
+
+`createBetterAuthInstance()` now pins `advanced.useSecureCookies: false`. On an `https://`
+baseURL Better-Auth otherwise auto-enables secure cookies **and** prefixes its session cookie
+with `__Secure-`, so its native handlers (2FA enable/verify, passkey register/list, backup
+codes, `/token`) look for `__Secure-<cookiePrefix>.session_token` — a cookie the nest-server
+cookie helper never writes (it emits the unprefixed name) — and answer `401 UNAUTHORIZED`,
+while `GET /iam/get-session` (reading the unprefixed cookie) still returns `200`. Pinning the
+name realigns the native read path with the helper.
+
+**The `Secure` attribute is NOT dropped.** `useSecureCookies: false` would by itself also strip
+`Secure` from every cookie Better-Auth sets — including the ones its native handlers forward
+**verbatim** (2FA verify, social callback, magic link, passkey) without passing through the
+cookie helper. To avoid a transport downgrade, `createBetterAuthInstance()` restores the exact
+`Secure` flag Better-Auth would have derived (an `https://` baseURL) via
+`advanced.defaultCookieAttributes`, so on production HTTPS the session cookie still ships with
+`Secure`.
+
+**Opt-out.** Consumers who manage cookies entirely through Better-Auth (not the nest-server
+helper) can re-enable the `__Secure-` prefix with
+`betterAuth.options.advanced.useSecureCookies: true` (deep-merged). Most projects need no
+action — `pnpm update` is sufficient.
+
+### 5. Cross-subdomain cookie domain keeps `api.<bare-TLD>` as-is
+
+`deriveCookieDomainFromUrls()` now strips the `api.` label through the shared
+`strippedApiHostname()` guard. Previously a `baseUrl` like `https://api.dev` (with
+`crossSubDomainCookies` enabled) derived the cookie domain `dev` — a public suffix browsers
+reject outright, dropping every session cookie. It now keeps `api.dev`. Only projects with
+`crossSubDomainCookies` on an `api.<single-label>` host are affected, and only for the better.
+
+> Known limitation (fails closed): a **multi-label** public suffix (`api.co.uk` → `co.uk`) is
+> still not recognised without a Public-Suffix-List check, which this security-critical module
+> avoids adding as a dependency. For such apex domains set
+> `betterAuth.crossSubDomainCookies.domain` explicitly.
+
+---
+
+## Repo-internal tooling
+
+These changes touch **no framework source** and ship no behavior change to
+consuming projects. They are listed because `nest-server-starter` mirrors these
+files, so projects that copied them can adopt the same fixes.
+
+### Unit tests ran in the e2e runner
+
+`vitest-e2e.config.ts` used `include: ['tests/**/*.ts']`, which matched
+`tests/unit/**` as well. Every unit test therefore ran inside the e2e runner —
+under `NODE_ENV=e2e`, the mongod `globalSetup` and `retry: 5`, none of which a
+unit test needs. The include now names the suites that actually need a database:
+
+```typescript
+include: ['tests/**/*.e2e-spec.ts', 'tests/stories/**/*.story.test.ts'],
+```
+
+Story tests are matched explicitly — they are e2e-grade and must keep the
+globalSetup. The pattern also stops matching helpers, `global-setup.ts`,
+`setup.ts` and the DB reporter, so `exclude` could be dropped entirely (which
+restores vitest's own defaults for `node_modules`, `dist`, … instead of
+replacing them).
+
+Because the unit tests no longer come along for the ride, `test` now runs both
+runners:
+
+```jsonc
+"test":    "pnpm run vitest:unit && pnpm run vitest",
+"test:ci": "pnpm run vitest:unit && pnpm run vitest:ci",
+```
+
+Three follow-on fixes were needed to make that split safe:
+
+1. **`vitest.config.ts` gained `setupFiles: ['tests/setup.ts']`.** The e2e config
+   had it; without it the unit run loses `Logger.overrideLogger(['error','fatal'])`
+   and the `@UnifiedField` deprecation-warning filter, and drowns in expected
+   DEBUG/WARN output.
+2. **`tests/unit/test-file-routing.spec.ts` guards the include patterns.** Narrow
+   patterns mean a file matching *neither* runner runs nowhere and still reports
+   green — `tests/stories/foo.test.ts` (missing `.story.`),
+   `tests/integration/bar.spec.ts`, `tests/unit/baz.test.ts`. The spec reads the
+   `include` patterns out of both configs and asserts every `*.spec.ts` /
+   `*.test.ts` in the repo is claimed by exactly one runner.
+3. **Coverage covers both suites again.** `vitest:cov` only ever ran the e2e
+   config, which no longer sees the unit tests. New `vitest:unit:cov`, and
+   `test:cov` runs both. The two runners are separate vitest processes, so each
+   writes its own report (`coverage/unit`, `coverage/e2e`) rather than
+   overwriting the other.
+
+### `check.mjs` under-reported multi-run test steps
+
+`parseVitest()` used `String.match()` without the `g` flag and read only the
+**first** vitest summary block in a step's output. With `test` now invoking
+vitest twice, the report would have shown the unit run's `passed` count and
+silently dropped the e2e run — and the test count is the only visible evidence in
+the report that a suite ran at all. It now sums every summary block, is exported,
+and is covered by `tests/unit/check-script-metrics.spec.ts`. The script only
+executes its pipeline when invoked directly (`process.argv[1]` check), so
+importing it for tests does not spawn a check run.
+
+---
+
+## Behavior Change
+
+Five consumer-visible behavior changes ship in this release — the host-split
+`appUrl` derivation, the `cors.allowAll` origin handling, the migration file
+pattern, the BetterAuth native-cookie name change (`Secure` preserved), and the
+cross-subdomain `api.<bare-TLD>` cookie-domain guard. Each is described, with its
+opt-out where one exists, under
+[Behavior changes in framework source](#behavior-changes-in-framework-source).
+
+Unchanged: `deriveAppUrl: false` still suppresses the derivation on all three
+layers, and still does **not** disable the `local`/`ci`/`e2e` localhost defaults —
+a host-split `baseUrl` with `deriveAppUrl: false` falls back to
+`http://localhost:3001`, exactly as before.
+
+---
+
+## Breaking Changes
+
+None — every change is additive or a bugfix; no existing signature was removed or
+altered. `separatesApiAndAppByHost()` and `toHttpUrl()` remain module-private.
+`deriveAppUrlFromBaseUrl()` and `resolveServerUrls()` keep their signatures. Two
+new named exports are added (both additive): `DEFAULT_MIGRATION_FILE_PATTERN` and
+`strippedApiHostname()` (the latter promoted from module-private so BetterAuth's
+cookie-domain derivation can share its bare-TLD guard). Both are free
+helpers/constants, so they do not appear in `FRAMEWORK-API.md` (which tracks
+interfaces, `CoreModule.forRoot()` overloads, and `CrudService` methods). The
+tooling changes live in `scripts/` and the vitest configs, outside the published
+`dist/`.
+
+---
+
+## Compatibility Notes
+
+- **npm-mode consumers:** `pnpm update` is sufficient.
+- **Projects that copied `scripts/check.mjs` / `vitest-e2e.config.ts` from the
+  starter:** optionally adopt the updated files. Check first whether your
+  `vitest-e2e.config.ts` matches `tests/unit/**`; if it does, your unit tests are
+  running inside the e2e runner against a database they do not use.
+- **Vendor-mode consumers:** the change touches
+  `src/core/common/helpers/cookies.helper.ts` and the `appUrl` JSDoc in
+  `src/core/common/interfaces/server-options.interface.ts` — both inside the
+  vendored `src/core/` file set. Sync via
+  `/lt-dev:backend:update-nest-server-core`.
+- **Projects that set `appUrl` / `APP_URL` explicitly:** unaffected.
+- **Projects that set `cors.allowAll: true` in local envs:** unaffected on the
+  CORS layer; the `trustedOrigins` and Passkey fixes still apply.
+- **Deployed envs (`develop` / `test` / `production`):** unaffected. They are not
+  localhost-default environments, so the derivation branch was always reachable
+  there.
+
+---
+
+## Troubleshooting
+
+### My `lt dev` frontend is still blocked by CORS
+
+Check, in order:
+
+1. You are on 11.27.6 or later.
+2. `baseUrl` carries an `api.` label. `https://crm.localhost` has nothing to
+   strip — set `appUrl` explicitly.
+3. The label strips to a **sibling host**, not to the bare `localhost`.
+   `https://api.localhost` is a port split and resolves to `http://localhost:3001`
+   by design.
+4. `cors.deriveAppUrl` is not `false`.
+
+### I rely on `http://localhost:3001` for an `api.<slug>.localhost` baseUrl
+
+Set `appUrl: 'http://localhost:3001'` explicitly, or `cors.deriveAppUrl: false`.
+Both suppress the derivation.
+
+---
+
+## Module Documentation
+
+- **Request lifecycle & CORS:** [docs/REQUEST-LIFECYCLE.md](../docs/REQUEST-LIFECYCLE.md) — section `0b. CORS`
+- **BetterAuth:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md)
+
+---
+
+## References
+
+- [Migration Guide 11.27.4 → 11.27.5](./11.27.4-to-11.27.5.md) — introduced `resolveServerUrls()`
+- [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.5",
+  "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,7 +74,7 @@
     "url": "https://github.com/lenneTech/nest-server/issues"
   },
   "engines": {
-    "node": ">= 20"
+    "node": ">= 22"
   },
   "dependencies": {
     "@apollo/server": "5.5.1",
@@ -211,13 +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",
-      "@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"
+      "@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",
@@ -254,7 +258,8 @@
       "nodemailer@<9.0.1": "9.0.1",
       "multer@<2.2.0": "2.2.0",
       "js-yaml@<4.2.0": "4.2.0",
-      "@xhmikosr/decompress@<11.1.3": "11.1.3"
+      "@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": {