@lenne.tech/nest-server 11.26.1 → 11.26.3

package/migration-guides/11.26.1-to-11.26.2.md

@@ -0,0 +1,234 @@
+# Migration Guide: 11.26.1 → 11.26.2
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **Bugfixes** | Latent BetterAuth session-cookie drift fixed — six call sites that independently derived the cookie name from `basePath` now share a single resolver, so a `cookiePrefix` override no longer breaks sign-in / authenticated requests / sign-out |
+| **New Features** | New `COOKIE_PREFIX` env variable — isolates the BetterAuth session cookie name on shared hosts (e.g. several lenne.tech apps on `*.localhost`). New helper module `better-auth-cookie-prefix.helper.ts` exporting `resolveBetterAuthCookiePrefix()`, `resolveBetterAuthSessionCookieName()`, `detectCookiePrefixDrift()`. New `CoreBetterAuthService.getCookiePrefix()`. Drift warning when `options.advanced.cookiePrefix` is used programmatically |
+| **Migration Effort** | 0 minutes (automatic) — opt-in `COOKIE_PREFIX` for multi-app shared-host deployments only |
+
+---
+
+## Quick Migration
+
+No code changes required. The fix and the new resolver activate automatically; `COOKIE_PREFIX` is opt-in.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.26.2
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+---
+
+## What's New in 11.26.2
+
+### 1. `COOKIE_PREFIX` env variable — isolate auth cookies per app
+
+**Use case:** Several lenne.tech apps deployed on the same host (e.g. via `lt dev` — `nest-server.localhost`, `offers.localhost`, `showroom.localhost` all served by Caddy on the same machine). Browser cookies are scoped by host, not port — without isolation a session cookie from one app collides with another and authentication breaks. The BetterAuth REST surface in 11.26.1 derives the cookie name from `basePath` (default: `iam.session_token`), which is identical across apps.
+
+**Fix:** Set `COOKIE_PREFIX` per app — the BetterAuth session cookie becomes `<prefix>.session_token`:
+
+```bash
+# App A
+COOKIE_PREFIX=offers   # → cookie name: offers.session_token
+
+# App B
+COOKIE_PREFIX=showroom # → cookie name: showroom.session_token
+```
+
+**Precedence (resolved by `resolveBetterAuthCookiePrefix`):**
+
+1. **`COOKIE_PREFIX` env** (dedicated, always wins) — sanitised to the safe cookie-name subset `[A-Za-z0-9._-]`; if it sanitises to empty it is ignored
+2. otherwise the **basePath-derived** prefix (`/iam` → `iam`, `/api/iam` → `api.iam`) — the previous default, fully backward compatible when `COOKIE_PREFIX` is unset
+
+**Frontend pairing (required when set):** The frontend `@lenne.tech/nuxt-extensions` exposes `NUXT_PUBLIC_COOKIE_PREFIX` (same precedence, same sanitisation). The two sides MUST agree, otherwise the browser sends one name and the server reads another. The backend logs a `COOKIE_PREFIX override active → …` line on bootstrap to make the override visible in operator logs.
+
+### 2. Single source of truth helper module
+
+New file: `src/core/modules/better-auth/better-auth-cookie-prefix.helper.ts`. Dependency-free on purpose so it can be imported from the config builder, the service, controllers and helpers without any import cycle.
+
+```typescript
+// All public API:
+import {
+  resolveBetterAuthCookiePrefix,        // → 'iam' (default) or 'acme' (under COOKIE_PREFIX=acme)
+  resolveBetterAuthSessionCookieName,   // → 'iam.session_token' or 'acme.session_token'
+  detectCookiePrefixDrift,              // → null | warning string
+} from '@lenne.tech/nest-server';
+```
+
+A `@deprecated` re-export from `./better-auth.config` keeps old imports working — new code should import from the helper directly.
+
+### 3. `CoreBetterAuthService.getCookiePrefix()` (new public method)
+
+```typescript
+class CoreBetterAuthService {
+  /** Cached on first read so it cannot drift away from the Better-Auth instance,
+   *  which captures the prefix once at bootstrap. */
+  getCookiePrefix(): string;
+  getSessionCookieName(): string; // unchanged signature, now backed by getCookiePrefix()
+}
+```
+
+### 4. Drift warning when `options.advanced.cookiePrefix` is set programmatically
+
+```typescript
+betterAuth: {
+  options: {
+    advanced: { cookiePrefix: 'custom' }, // ← BetterAuth would honour this, NestJS layer would not
+  },
+}
+```
+
+This pattern silently broke sign-in / read / sign-out in 11.26.1 and earlier. 11.26.2 detects the drift via `detectCookiePrefixDrift()` and emits a loud `logger.warn` at bootstrap:
+
+```
+options.advanced.cookiePrefix="custom" overrides Better-Auth but the NestJS layer
+still uses "iam". This will break sign-in / read / sign-out — use the COOKIE_PREFIX
+env variable instead (honoured by every call site).
+```
+
+---
+
+## What's Fixed in 11.26.2
+
+### Cross-layer cookie-prefix drift in the BetterAuth pipeline
+
+**Affects:** Any project that set a non-default `cookiePrefix` via `options.advanced.cookiePrefix` or via the proposed `COOKIE_PREFIX` env (introduced here). Default deployments (no override) are not affected.
+
+**Symptom (before 11.26.2):**
+With a non-default cookie prefix, Better-Auth set `Set-Cookie: <prefix>.session_token=…` but the NestJS layer kept reading `iam.session_token`:
+
+| Stage | Cookie name in 11.26.1 | Result |
+|---|---|---|
+| Sign-up / Sign-in | `<prefix>.session_token` (Better-Auth) | Cookie correctly set by Better-Auth |
+| Authenticated request | `iam.session_token` ([core-better-auth.controller.ts:778-781](../src/core/modules/better-auth/core-better-auth.controller.ts)) | User reads as anonymous (`success: false`) |
+| `getSession()` cookie-signing | `iam.session_token` ([core-better-auth.service.ts:437-438](../src/core/modules/better-auth/core-better-auth.service.ts)) | Session never resolved |
+| `extractSessionToken` (middleware) | `iam.session_token` ([core-better-auth-web.helper.ts:98-103](../src/core/modules/better-auth/core-better-auth-web.helper.ts)) | 401 on protected routes |
+| `BetterAuthCookieHelper` (set + clear) | `iam.session_token` ([core-better-auth-cookie.helper.ts:127-128](../src/core/modules/better-auth/core-better-auth-cookie.helper.ts)) | Sign-out leaves real cookie behind |
+
+**Fix (in 11.26.2):**
+All six call sites now resolve the cookie name through `resolveBetterAuthSessionCookieName(basePath)` — a single function that honours `COOKIE_PREFIX` and falls back to the basePath default. Cached on the service so a late `process.env` mutation (typical in tests) cannot drift the value away from the Better-Auth instance, which captures the prefix at bootstrap.
+
+---
+
+## Compatibility Notes
+
+- **Default deployments (no `COOKIE_PREFIX`, no programmatic override):** Cookie name remains `iam.session_token`, behaviour is bit-for-bit identical to 11.26.1. No change is observable.
+- **Projects that read `iam.session_token` directly in tests (hardcoded strings):** Continue to work as long as `COOKIE_PREFIX` is unset. Under override the hardcoded name is wrong — prefer `resolveBetterAuthSessionCookieName('/iam')` or the `TestHelper.extractSessionToken()` default (which now resolves through the same helper).
+- **`TestHelper.extractSessionToken(response, cookieName?)`:** The second parameter is now optional; when omitted it derives the cookie name through the shared resolver (so tests under `COOKIE_PREFIX=acme` automatically look at `acme.session_token`). Existing call sites that pass an explicit name are unaffected.
+- **`TestHelper.buildBetterAuthCookies(token, basePath = 'iam')`:** Already honoured `COOKIE_PREFIX` since the prior release via the same resolver — no caller change required.
+- **Programmatic `options.advanced.cookiePrefix`:** Still applied to the Better-Auth instance (no behaviour change in Better-Auth), but now emits a `logger.warn` drift notice on bootstrap. Switch to `COOKIE_PREFIX` (env) to remove the warning and the latent breakage.
+- **`BetterAuthCookieHelper.getNormalizedBasePath()`:** Unchanged — still returns the basePath-derived string (e.g. `'iam'`). It is **NOT** a cookie prefix; the JSDoc now carries a loud warning so future code never reconstructs the cookie name as `` `${getNormalizedBasePath()}.session_token` `` (which would re-introduce the drift).
+- **Vendor-mode consumers:** Same as npm consumers; the new file ships under `src/core/modules/better-auth/`.
+
+---
+
+## Adopting `COOKIE_PREFIX` (Optional)
+
+### Step 1: Decide the prefix per app
+
+Pick a short, unique slug per app — typically the project slug (`offers`, `showroom`) or a kebab/dot subset that matches your environment hygiene.
+
+| Pick | Valid? | Result |
+|---|---|---|
+| `offers` | ✓ | `offers.session_token` |
+| `kit-test_01` | ✓ | `kit-test_01.session_token` |
+| `a;c=me x\r\n` | sanitised | `acmex.session_token` (semicolons, equals, whitespace, CR/LF stripped) |
+| `;;==` | sanitises to empty → falls back to basePath | `iam.session_token` (the env is ignored) |
+
+### Step 2: Set both sides in lockstep
+
+```bash
+# Backend (this package)
+COOKIE_PREFIX=offers
+
+# Frontend (@lenne.tech/nuxt-extensions)
+NUXT_PUBLIC_COOKIE_PREFIX=offers
+```
+
+### Step 3: Verify
+
+```bash
+# Bootstrap should log:
+# COOKIE_PREFIX override active → auth cookies use prefix "offers" (e.g. "offers.session_token").
+# The frontend NUXT_PUBLIC_COOKIE_PREFIX MUST match.
+
+# Sign in and inspect the Set-Cookie header — it must use the overridden name:
+curl -i -X POST http://localhost:3000/iam/sign-in/email \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"…","password":"…"}' \
+  | grep -i set-cookie
+# Set-Cookie: offers.session_token=…; Path=/; HttpOnly; …
+```
+
+---
+
+## Troubleshooting
+
+### After setting `COOKIE_PREFIX`, sign-in succeeds but every follow-up request is unauthenticated
+
+Verify the frontend `NUXT_PUBLIC_COOKIE_PREFIX` matches the backend value. The most common cause is one side set in `.env` and the other still inheriting the default. The backend log line `COOKIE_PREFIX override active → …` confirms the backend value; check the browser's DevTools → Application → Cookies for the actual cookie name the browser holds.
+
+### Bootstrap log says `options.advanced.cookiePrefix="…" overrides Better-Auth but the NestJS layer still uses "…"`
+
+You are setting the cookie prefix programmatically via `betterAuth.options.advanced.cookiePrefix`. Move the override to the `COOKIE_PREFIX` env variable — that is the only path that is honoured by every call site (sign-up, sign-in, get-session, sign-out, middleware). The programmatic override is left untouched but the NestJS layer cannot follow it, so sign-in writes one cookie and authenticated requests look for another.
+
+### Existing browser cookies under the old name keep the user "logged in" after switching `COOKIE_PREFIX`
+
+Expected. Browser cookies are persistent — changing the prefix does not retroactively rename them. Users will be silently signed out (the server no longer reads the old name) and sign in again, after which the new cookie is set. Old cookies fall out of the browser at their max-age. To force a clean state, instruct users to clear cookies for the affected host, or set a one-off `Clear-Site-Data: "cookies"` header during the rollout.
+
+### Tests under `COOKIE_PREFIX=acme` return `{ success: false }` from `/iam/session` although sign-in succeeded
+
+Most likely you are passing the JWT-converted token (sign-in response body's `token` field) instead of the raw session token. With `betterAuth.jwt` enabled the response token is a JWT (`eyJ…`), which goes in the `Authorization: Bearer` header — not in the session cookie. For cookie-based authenticated tests, read the raw token from the `session` collection:
+
+```typescript
+const sessionRow = await db.collection('session').findOne(
+  { $or: [{ userId: iamUser._id }, { userId: iamUser._id.toString() }] },
+  { sort: { createdAt: -1 } },
+);
+const rawSessionToken = sessionRow.token;
+```
+
+See `tests/stories/better-auth-cookie-prefix.story.test.ts` for a complete e2e reference.
+
+### `TestHelper.extractSessionToken(response)` returns `null` although the cookie is in the Set-Cookie header
+
+You are likely on a `COOKIE_PREFIX=acme` setup but pass an explicit `cookieName: 'iam.session_token'` as the second argument. Either omit the argument (the new default goes through the resolver) or pass the resolved name explicitly.
+
+---
+
+## Module Documentation
+
+### BetterAuth Module
+
+- **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md)
+- **Integration Checklist:** [src/core/modules/better-auth/INTEGRATION-CHECKLIST.md](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- **Customization Guide:** [src/core/modules/better-auth/CUSTOMIZATION.md](../src/core/modules/better-auth/CUSTOMIZATION.md)
+- **Reference Implementation:** `src/server/modules/better-auth/`
+- **Key Files:**
+  - `src/core/modules/better-auth/better-auth-cookie-prefix.helper.ts` — single source of truth for the prefix (`resolveBetterAuthCookiePrefix`, `resolveBetterAuthSessionCookieName`, `detectCookiePrefixDrift`)
+  - `src/core/modules/better-auth/better-auth.config.ts` — bootstrap-time resolution + drift warning + `@deprecated` re-export
+  - `src/core/modules/better-auth/core-better-auth.service.ts` — `getCookiePrefix()` (new, cached), `getSessionCookieName()` (now via cache)
+  - `src/core/modules/better-auth/core-better-auth.controller.ts`, `core-better-auth-cookie.helper.ts`, `core-better-auth-web.helper.ts` — all converted to the shared resolver
+- **Reference tests:**
+  - `tests/unit/better-auth-cookie-prefix.spec.ts` — pure resolver + drift detector
+  - `tests/unit/better-auth-cookie-helper.spec.ts` — cross-layer set/read lockstep + service cache + `TestHelper` default
+  - `tests/stories/better-auth-cookie-prefix.story.test.ts` — e2e sign-up / authenticated request / sign-out against a real Mongo + Better-Auth boot under `COOKIE_PREFIX=acme`
+
+---
+
+## References
+
+- [Migration Guide 11.26.0 → 11.26.1](./11.26.0-to-11.26.1.md) — Previous release (roles in REST auth response)
+- [Configurable Features](../.claude/rules/configurable-features.md) — Pattern notes for env-driven overrides
+- [BetterAuth module rules](../.claude/rules/better-auth.md) — Standard-compliance & security baselines
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+- [@lenne.tech/nuxt-extensions `resolveLtCookiePrefix`](https://github.com/lenneTech/nuxt-extensions) — frontend pendant (`NUXT_PUBLIC_COOKIE_PREFIX`)

package/migration-guides/11.26.2-to-11.26.3.md

@@ -0,0 +1,186 @@
+# Migration Guide: 11.26.2 → 11.26.3
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **Bugfixes** | `@UnifiedField({ enum: … })` no longer emits a broken, unnamed `$ref` in the generated OpenAPI document under `@nestjs/swagger >= 11.4` — enum fields now produce proper named component schemas (or clean inline enums when `enumName: null` / auto-detection fails) instead of `allOf: [{ $ref: '#/components/schemas/' }]`, which crashed OpenAPI client generators like `@hey-api/openapi-ts` |
+| **New Features** | None |
+| **Migration Effort** | 0 minutes (automatic) — drop-in patch release |
+
+---
+
+## Quick Migration
+
+No code changes required. The fix applies automatically as soon as the package is updated.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.26.3
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+
+# (Optional) regenerate REST client SDK against the new OpenAPI document
+pnpm --filter @your-app/api-sdk openapi-ts
+```
+
+---
+
+## What's Fixed in 11.26.3
+
+### OpenAPI: broken empty `$ref` on enum-typed `@UnifiedField` properties
+
+**Affects:** Any project that
+
+- consumes `@lenne.tech/nest-server` together with `@nestjs/swagger >= 11.4` (this repo pinned to `11.4.2`), AND
+- exposes REST endpoints whose DTOs declare enum fields via `@UnifiedField({ enum: … })`, AND
+- runs an OpenAPI client generator (e.g. `@hey-api/openapi-ts`, `openapi-typescript`, `openapi-generator-cli`) against the bundled OpenAPI document.
+
+**Symptom (before 11.26.3):**
+
+The decorator passed `type: () => String` to `@nestjs/swagger` ALONGSIDE `enum` + `enumName`. `@nestjs/swagger <= 11.2` silently tolerated the combination, but `@nestjs/swagger >= 11.4` emits a broken, **unnamed** enum reference and never registers the enum under `components.schemas`:
+
+```jsonc
+// Generated OpenAPI document — BROKEN
+{
+  "components": {
+    "schemas": {
+      "SomeInput": {
+        "properties": {
+          "status": {
+            "allOf": [
+              { "$ref": "#/components/schemas/" }   // ← empty target!
+            ]
+          }
+        }
+      }
+      // ← StatusEnum is missing entirely from components.schemas
+    }
+  }
+}
+```
+
+Downstream tools crash:
+
+```
+@hey-api/openapi-ts: Missing $ref pointer "#/components/schemas/". Token "" does not exist.
+```
+
+**Fix (in 11.26.3):**
+
+`@UnifiedField` no longer sets `swaggerOpts.type` when the field is an enum. `@nestjs/swagger` derives the schema from `enum` + `enumName` correctly:
+
+```jsonc
+// Generated OpenAPI document — CORRECT
+{
+  "components": {
+    "schemas": {
+      "StatusEnum": { "type": "string", "enum": ["draft", "published", "review"] },
+      "SomeInput": {
+        "properties": {
+          "status": {
+            "allOf": [
+              { "$ref": "#/components/schemas/StatusEnum" }   // ← named, resolvable
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Behaviour matrix:**
+
+| `@UnifiedField` form | OpenAPI output before 11.26.3 | OpenAPI output in 11.26.3 |
+|---|---|---|
+| `{ enum: MyEnum, enumName: 'MyEnum' }` | Empty `$ref`, `MyEnum` missing from `components.schemas` | Named `MyEnum` schema, property uses `$ref` |
+| `{ enum: MyEnum }` + `registerEnum(MyEnum, { name: 'MyEnum' })` | Empty `$ref` | Named `MyEnum` schema, property uses `$ref` |
+| `{ enum: MyEnum, enumName: null }` (opt out) | Empty `$ref` | Inline `enum: [...]`, no `$ref`, no named schema |
+| `{ enum: MyEnum }` without registration | Empty `$ref` | Inline `enum: [...]`, no `$ref`, no named schema |
+| Long-form `{ enum: { enum: MyEnum, enumName: 'MyEnum' } }` (deprecated) | Empty `$ref` | Named `MyEnum` schema, property uses `$ref` (deprecation warning unchanged) |
+| Non-enum fields (`String`, `Number`, `Date`, custom classes, …) | Unchanged | Unchanged |
+
+GraphQL schema, class-validator runtime validation (`IsEnum`), Mongoose `@Prop`, and field-level `@Restricted` / `@Roles` behaviour are all bit-for-bit identical to 11.26.2.
+
+---
+
+## Compatibility Notes
+
+- **`@nestjs/swagger <= 11.2` consumers:** The previously emitted `type: () => String` was redundant; removing it produces the same enum schema as before. No observable change.
+- **`@nestjs/swagger >= 11.4` consumers:** The OpenAPI document for enum fields changes from a **broken** empty `$ref` to a **correct** named schema (or clean inline enum). This is strictly a defect fix — any client generator that was previously crashing now succeeds.
+- **OpenAPI client generators / SDK consumers:** After updating, regenerate the SDK once. Enum properties that were previously typed `string` (when the generator silently dropped the broken `$ref`) will now be typed as the proper enum union — review the generated SDK once and adjust call-sites if you relied on the loose `string` type.
+- **GraphQL consumers:** No change. The `Field(...)` factory and enum resolution are untouched.
+- **`@UnifiedField` public API:** Unchanged. All option shapes (`enum: MyEnum`, `enumName`, deprecated long-form `{ enum: { … } }`, `enumName: null`) keep their documented semantics.
+- **Mongoose / class-validator:** Unchanged. `@Prop({ type: baseType })` still applied for enum fields; `IsEnum(...)` is still the authoritative validator.
+- **Vendor-mode consumers:** Same fix lands in `src/core/common/decorators/unified-field.decorator.ts`. Sync via `/lt-dev:backend:update-nest-server-core`. No flatten-fix change required.
+- **Hidden / excluded enum fields (`@UnifiedField({ exclude: true })`):** Unaffected — those still hide from the OpenAPI document via `ApiHideProperty()`.
+
+---
+
+## Verifying the Fix
+
+If you previously hit the empty-`$ref` defect, confirm the regenerated OpenAPI document:
+
+```bash
+# 1. Boot the API and dump the OpenAPI document
+pnpm start &
+curl -s http://localhost:3000/api-json > /tmp/openapi.json
+
+# 2. There must be no empty/unnamed component refs
+grep -F '"$ref": "#/components/schemas/"' /tmp/openapi.json && echo 'BROKEN' || echo 'OK'
+
+# 3. Every enum used in a DTO must appear in components.schemas
+jq '.components.schemas | keys' /tmp/openapi.json
+```
+
+A complete regression test ships in `tests/unified-field-enum-swagger.e2e-spec.ts` and inspects the real document built by `SwaggerModule.createDocument()` for:
+
+- no empty `$ref` anywhere in the document,
+- a named component schema per enum (string / numeric / array / auto-detected / deprecated long-form),
+- correct enum values and property references,
+- inline-enum fallback for `enumName: null` and for unregistered enums (no empty `$ref`).
+
+---
+
+## Troubleshooting
+
+### After updating, my generated SDK still has an empty `$ref` error
+
+Make sure the SDK is regenerated against a **freshly rebuilt** API. Stale `openapi.json` artefacts checked into the consumer repo continue to be broken. Rebuild the API (`pnpm run build`) and re-export the document (`/api-json` or `SwaggerModule.createDocument` snapshot) before running your codegen.
+
+### My enum properties used to be typed `string` in the generated client and now they're a strict union
+
+That is the corrected behaviour — the previous client was generated against a broken document and silently widened the type. Update call-sites to use the enum union (or import the enum from your shared package). If you need the loose `string` type during the rollout, your codegen typically offers an `--enum-style` flag (e.g. `@hey-api/openapi-ts` → `enums: 'javascript'`) to keep the old shape.
+
+### I rely on the deprecated long-form `enum: { enum: MyEnum, enumName: 'MyEnum' }`
+
+It still works and now produces the same named schema as the shortcut form. The deprecation warning emitted at decoration time is unchanged. Plan to migrate to the shortcut form (`enum: MyEnum, enumName: 'MyEnum'`) before a future MINOR removes the long form.
+
+---
+
+## Module Documentation
+
+### Core Common — `@UnifiedField`
+
+- **Decorator:** `src/core/common/decorators/unified-field.decorator.ts`
+- **Architecture notes:** [.claude/rules/architecture.md](../.claude/rules/architecture.md) (Input Validation section)
+- **Reference tests:**
+  - `tests/unified-field-enum-swagger.e2e-spec.ts` — OpenAPI schema regression guard (the contract this release restores)
+  - `tests/unified-field-enum.e2e-spec.ts` — metadata-level enum behaviour
+  - `tests/unified-field-enum-api.e2e-spec.ts` — runtime REST/GraphQL enum behaviour
+
+---
+
+## References
+
+- [Migration Guide 11.26.1 → 11.26.2](./11.26.1-to-11.26.2.md) — Previous release (`COOKIE_PREFIX` env, cross-layer cookie-prefix lockstep)
+- [Architecture rules — Input Validation](../.claude/rules/architecture.md)
+- [@nestjs/swagger 11.4 release notes](https://github.com/nestjs/swagger/releases) — context for the schema-emission change that surfaced the latent defect
+- [@hey-api/openapi-ts](https://heyapi.dev/) — one of the OpenAPI client generators that was crashing on the broken document
+- [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.26.1",
+  "version": "11.26.3",
   "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",

package/src/core/common/decorators/unified-field.decorator.ts

@@ -408,13 +408,19 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
       swaggerOpts.required = true;
     }
 
-    // Set type for swagger
-    if (baseType) {
-      if (normalizedEnum) {
-        swaggerOpts.type = () => String;
-      } else {
-        swaggerOpts.type = baseType;
-      }
+    // Set type for swagger.
+    //
+    // For enum fields we deliberately do NOT set `type`: @nestjs/swagger derives
+    // the schema from `enum` + `enumName` (set further below). Passing
+    // `type: () => String` ALONGSIDE `enum`/`enumName` makes @nestjs/swagger
+    // >= 11.4 emit a broken, UNNAMED enum reference
+    // (`allOf: [{ $ref: '#/components/schemas/' }]`) and never adds the enum to
+    // `components.schemas`. That crashes OpenAPI client generators — e.g.
+    // @hey-api/openapi-ts fails with «Missing $ref pointer "#/components/schemas/"».
+    // (On @nestjs/swagger <= 11.2 the extra `type` was tolerated, which is why
+    // this only surfaced after a swagger bump.)
+    if (baseType && !normalizedEnum) {
+      swaggerOpts.type = baseType;
     }
 
     // Set description

package/src/core/modules/better-auth/better-auth-cookie-prefix.helper.ts

@@ -0,0 +1,84 @@
+/**
+ * Single source of truth for the Better-Auth session cookie prefix.
+ *
+ * The session cookie is named `<prefix>.session_token` (e.g. `iam.session_token`).
+ * The prefix is resolved here — and ONLY here — so every place that sets, reads,
+ * signs, extracts or clears the session cookie agrees on the exact name. (A
+ * previous bug derived the name from `basePath` independently in 6 places, so a
+ * `COOKIE_PREFIX` override broke the auth pipeline: Better-Auth set
+ * `acme.session_token` while the NestJS layer still looked for `iam.session_token`.)
+ *
+ * Dependency-free on purpose so it can be imported from the config builder, the
+ * service, controllers and helpers without any import cycle.
+ */
+
+/**
+ * Characters allowed in a cookie-name token. A safe subset of RFC 6265 that is
+ * IDENTICAL to the frontend resolver (`@lenne.tech/nuxt-extensions`
+ * `resolveLtCookiePrefix`), so a shared `COOKIE_PREFIX` produces the SAME prefix
+ * on both sides. Everything else (spaces, `;`, `=`, `\r`, `\n`, …) is stripped so
+ * a typo can never corrupt the `Set-Cookie` header.
+ */
+function sanitizeCookiePrefix(raw: string): string {
+  return raw.trim().replace(/[^A-Za-z0-9._-]/g, '');
+}
+
+/**
+ * Resolve the Better-Auth cookie prefix (the `iam` in `iam.session_token`).
+ *
+ * Precedence:
+ *   1. **`COOKIE_PREFIX` env** (dedicated, always wins) — for fully autonomous
+ *      cookie isolation on a shared host (several lenne.tech apps on the same
+ *      host, where cookies collide by host, not port). Sanitised to valid
+ *      cookie-name characters; if it sanitises to empty it is ignored.
+ *   2. otherwise the **basePath-derived** prefix (`/iam` → `iam`,
+ *      `/api/iam` → `api.iam`) — the previous behaviour, fully backward
+ *      compatible when `COOKIE_PREFIX` is unset.
+ *
+ * IMPORTANT: when `COOKIE_PREFIX` is set it MUST match the frontend
+ * `NUXT_PUBLIC_COOKIE_PREFIX` (see `@lenne.tech/nuxt-extensions`
+ * `resolveLtCookiePrefix`) — otherwise the two sides use different cookie names
+ * and authentication breaks.
+ *
+ * @param basePath - Better-Auth base path (e.g. `/iam`)
+ * @param env - environment to read `COOKIE_PREFIX` from (defaults to `process.env`)
+ */
+export function resolveBetterAuthCookiePrefix(basePath: string, env: NodeJS.ProcessEnv = process.env): string {
+  const basePathPrefix = (basePath || '/iam').replace(/^\//, '').replace(/\//g, '.');
+  const explicit = sanitizeCookiePrefix(typeof env.COOKIE_PREFIX === 'string' ? env.COOKIE_PREFIX : '');
+  return explicit || basePathPrefix;
+}
+
+/**
+ * Convenience: the full session-cookie name (`<prefix>.session_token`) for the
+ * given basePath, honouring `COOKIE_PREFIX`. Use this wherever the session
+ * cookie name is needed so all call sites stay in lockstep.
+ */
+export function resolveBetterAuthSessionCookieName(basePath: string, env: NodeJS.ProcessEnv = process.env): string {
+  return `${resolveBetterAuthCookiePrefix(basePath, env)}.session_token`;
+}
+
+/**
+ * Detect a Better-Auth cookie-prefix drift between the value the NestJS layer
+ * resolves (via {@link resolveBetterAuthCookiePrefix}) and a programmatic
+ * `options.advanced.cookiePrefix` passed straight to Better-Auth. Such a
+ * mismatch silently breaks the auth pipeline because Better-Auth sets the
+ * cookie under the programmatic prefix while the NestJS read/clear path still
+ * uses the resolved prefix.
+ *
+ * Returns `null` when there is no drift (no programmatic prefix, or it
+ * matches), otherwise a human-readable warning sentence ready for `logger.warn`.
+ *
+ * Extracted so the drift-detection logic is testable without booting the full
+ * Better-Auth instance (which requires Mongo).
+ */
+export function detectCookiePrefixDrift(resolvedPrefix: string, programmaticOptionsAdvanced: unknown): null | string {
+  if (!programmaticOptionsAdvanced || typeof programmaticOptionsAdvanced !== 'object') return null;
+  const programmaticPrefix = (programmaticOptionsAdvanced as Record<string, unknown>).cookiePrefix;
+  if (typeof programmaticPrefix !== 'string' || programmaticPrefix === resolvedPrefix) return null;
+  return (
+    `options.advanced.cookiePrefix="${programmaticPrefix}" overrides Better-Auth but the ` +
+    `NestJS layer still uses "${resolvedPrefix}". This will break sign-in / read / sign-out — ` +
+    `use the COOKIE_PREFIX env variable instead (honoured by every call site).`
+  );
+}

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

@@ -8,6 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface';
+import { detectCookiePrefixDrift, resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper';
 
 /**
  * Type for better-auth instance with plugins
@@ -325,9 +326,20 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
   // Build the base Better-Auth configuration
   // Use resolved baseUrl (with local defaults) or fallback
   const basePath = config.basePath || '/iam';
-  // Cookie prefix derived from basePath (e.g., '/iam' → 'iam')
-  // This ensures Better-Auth looks for cookies like 'iam.session_token' instead of 'better-auth.session_token'
-  const cookiePrefix = basePath.replace(/^\//, '').replace(/\//g, '.');
+  // Cookie prefix for Better-Auth's session cookies (e.g. 'iam.session_token').
+  // COOKIE_PREFIX env (always wins) lets a project fully isolate its auth
+  // cookies on a shared host; otherwise derived from basePath. The SAME pure
+  // resolver is used by every session-cookie call site (service, controller,
+  // web/cookie helpers) so the name stays in lockstep.
+  const cookiePrefix = resolveBetterAuthCookiePrefix(basePath);
+  // Operator visibility: make a non-default COOKIE_PREFIX override obvious in the
+  // logs, and remind that the frontend must mirror it or auth will break.
+  if ((process.env.COOKIE_PREFIX || '').trim()) {
+    logger.log(
+      `COOKIE_PREFIX override active → auth cookies use prefix "${cookiePrefix}" ` +
+        `(e.g. "${cookiePrefix}.session_token"). The frontend NUXT_PUBLIC_COOKIE_PREFIX MUST match.`,
+    );
+  }
 
   const betterAuthConfig: Record<string, unknown> = {
     advanced: {
@@ -382,6 +394,14 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
     const { advanced: optionsAdvanced, ...restOptions } = config.options as Record<string, unknown>;
     finalConfig = { ...betterAuthConfig, ...restOptions };
     if (optionsAdvanced && typeof optionsAdvanced === 'object') {
+      // Drift guard: a programmatic `options.advanced.cookiePrefix` would only
+      // change what Better-Auth itself sets — the NestJS layer keeps resolving
+      // through `resolveBetterAuthCookiePrefix(basePath, env)`, so sign-in /
+      // read / sign-out would silently fall out of lockstep. Loud warning so
+      // operators see the misconfiguration immediately. Use `COOKIE_PREFIX`
+      // (env) instead — it is honoured by every call site.
+      const driftWarning = detectCookiePrefixDrift(cookiePrefix, optionsAdvanced);
+      if (driftWarning) logger.warn(driftWarning);
       finalConfig.advanced = {
         ...(betterAuthConfig.advanced as Record<string, unknown>),
         ...(optionsAdvanced as Record<string, unknown>),
@@ -1081,6 +1101,17 @@ export interface ResolvedCrossSubDomainCookies {
   enabled: boolean;
 }
 
+/**
+ * Re-exported for backward compatibility.
+ *
+ * @deprecated Import from `./better-auth-cookie-prefix.helper` directly. The
+ * re-export exists only so callers that landed on `./better-auth.config`
+ * before the helper was extracted keep working; new code MUST import from the
+ * dedicated helper module to avoid pulling the heavy config-builder into the
+ * dependency graph (which forces import cycles in some build setups).
+ */
+export { resolveBetterAuthCookiePrefix, resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper';
+
 /**
  * Resolves the cross-subdomain cookies configuration.
  *

package/src/core/modules/better-auth/core-better-auth-cookie.helper.ts

@@ -2,6 +2,7 @@ import { Logger } from '@nestjs/common';
 import { Response } from 'express';
 
 import { isProductionLikeEnv } from '../../common/helpers/cookies.helper';
+import { resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper';
 import { signCookieValue } from './core-better-auth-web.helper';
 
 /**
@@ -124,8 +125,10 @@ export class BetterAuthCookieHelper {
   constructor(private readonly config: BetterAuthCookieHelperConfig) {
     // Normalize basePath: remove leading slash, replace slashes with dots
     this.normalizedBasePath = config.basePath.replace(/^\//, '').replace(/\//g, '.');
-    // Default cookie name based on basePath (e.g., 'iam.session_token')
-    this.cookieName = `${this.normalizedBasePath}.session_token`;
+    // Session cookie name via the single shared resolver: honours COOKIE_PREFIX
+    // (e.g. 'iam.session_token', or 'acme.session_token' when COOKIE_PREFIX=acme),
+    // so set/clear/read here always match the name Better-Auth itself uses.
+    this.cookieName = resolveBetterAuthSessionCookieName(config.basePath);
   }
 
   /**
@@ -153,6 +156,13 @@ export class BetterAuthCookieHelper {
 
   /**
    * Gets the normalized base path (e.g., 'iam' from '/iam').
+   *
+   * WARNING: This is the basePath-derived string, NOT the resolved cookie
+   * prefix — it intentionally ignores `COOKIE_PREFIX`. Do NOT use it to build
+   * a session cookie name (use {@link getCookieName} instead). Composing
+   * `${getNormalizedBasePath()}.session_token` would re-introduce the
+   * COOKIE_PREFIX drift bug where Better-Auth and the NestJS layer disagree
+   * on the cookie name (see better-auth-cookie-prefix.helper.ts).
    */
   getNormalizedBasePath(): string {
     return this.normalizedBasePath;