@lenne.tech/nest-server 11.27.4 → 11.27.6

package/docs/REQUEST-LIFECYCLE.md

@@ -457,11 +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 |
 
-> **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.
+> **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` 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:** 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.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/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