@lenne.tech/nest-server 11.26.0 → 11.26.2

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

@@ -0,0 +1,193 @@
+# Migration Guide: 11.26.0 → 11.26.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **Bugfixes** | BetterAuth REST sign-in/sign-up/get-session responses now include the user's `roles` from the synced legacy user (previously silently dropped) |
+| **New Features** | New optional field `roles?: string[]` on `CoreBetterAuthUserResponse` (additive, Swagger-documented) |
+| **Migration Effort** | 0 minutes (automatic) — optional cleanup if your project shipped a `mapUser()` override as a workaround |
+
+---
+
+## Quick Migration
+
+No code changes required. The fix activates automatically.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.26.1
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+---
+
+## What's Fixed in 11.26.1
+
+### `roles` is now exposed on BetterAuth REST auth responses
+
+**Affects:** Every project that uses BetterAuth (IAM) and reads `response.user` from the
+REST endpoints `POST /iam/sign-in/email`, `POST /iam/sign-up/email`, or `GET /iam/session`.
+
+**Symptom (before 11.26.1):**
+The sign-in response body looked like this regardless of the user's role assignment:
+
+```json
+{
+  "success": true,
+  "user": {
+    "id": "ba-user-1",
+    "email": "admin@example.com",
+    "emailVerified": true,
+    "name": "Admin"
+  },
+  "token": "..."
+}
+```
+
+Frontend consumers (e.g. `useLtAuth().setUser()` in `@lenne.tech/nuxt-extensions`,
+the `lt-auth-state` cookie cache) persisted a roles-less user. Client-side admin gating
+(e.g. routing the `nest-server-starter` setup flow into `/admin/*` based on
+`roles: ['admin']`) silently failed for every freshly authenticated user.
+
+**Fix (in 11.26.1):**
+`CoreBetterAuthController.mapUser()` now forwards `roles` from the DB-synced legacy user:
+
+```json
+{
+  "success": true,
+  "user": {
+    "id": "ba-user-1",
+    "email": "admin@example.com",
+    "emailVerified": true,
+    "name": "Admin",
+    "roles": ["admin"]
+  },
+  "token": "..."
+}
+```
+
+**Where the roles come from:**
+
+`CoreBetterAuthController.mapUser()` reads `roles` from the result of
+`CoreBetterAuthUserMapper.mapSessionUser()`, which looks the user up in the
+`users` collection (`findOne({ $or: [{ email }, { iamId }] })`) and returns
+`Array.isArray(dbUser.roles) ? dbUser.roles : []`. The client cannot influence
+the value — roles remain server-authoritative.
+
+**Defensive defaults:**
+
+| `mappedUser` value                | Response `roles` |
+|-----------------------------------|------------------|
+| `{ roles: ['admin'] }`            | `['admin']`      |
+| `{ roles: [] }`                   | `[]`             |
+| `null` / `undefined`              | `[]`             |
+| `{ roles: 'admin' }` (not array)  | `[]`             |
+| `{}` (no `roles` field)           | `[]`             |
+
+---
+
+## Compatibility Notes
+
+- **Frontend consumers (additive change):** Frontends that previously ignored
+  `response.user.roles` because it was always missing continue to work. Frontends
+  that now want to use it (admin gating, role-based UI) can read it directly —
+  no extra `/api/users/me` round-trip required after login.
+- **Swagger / OpenAPI clients:** The generated schema gains `roles?: string[]`
+  on `CoreBetterAuthUserResponse`. Regenerate any SDK that consumes the OpenAPI
+  spec (e.g. `nuxt-base-starter` runs `pnpm run generate:types` against the API
+  schema).
+- **Existing project-level `mapUser()` overrides (optional cleanup):**
+  If your project shipped a `mapUser()` override solely to add `roles` to the
+  response as a workaround, you can now delete it. See **Cleanup** below.
+- **Subclasses that override `mapUser()`:** The second positional parameter is
+  unchanged in shape but was renamed `_mappedUser` → `mappedUser` (the leading
+  underscore previously signalled "unused"). Existing overrides keep working —
+  parameter names are local to each function signature.
+- **Projects without BetterAuth:** Not affected. Legacy `signIn` GraphQL/REST
+  responses already included `user.roles` and are unchanged.
+
+---
+
+## Cleanup (Optional)
+
+If your project previously added a `mapUser()` override in its
+`BetterAuthController` subclass solely to surface `roles`, the override is now
+redundant and can be removed. Example pattern that can be deleted:
+
+```typescript
+// Project: src/server/modules/better-auth/better-auth.controller.ts
+//
+// REMOVE this override — the core now does the same thing.
+protected override mapUser(sessionUser: BetterAuthSessionUser, mappedUser: any) {
+  return {
+    ...super.mapUser(sessionUser, mappedUser),
+    roles: Array.isArray(mappedUser?.roles) ? mappedUser.roles : [],
+  };
+}
+```
+
+Keep the override if it adds project-specific fields beyond `roles` (e.g.
+`status`, `type`, `avatar`). In that case, drop only the `roles` line — `roles`
+is now part of the base response.
+
+---
+
+## Troubleshooting
+
+### `roles` is still missing in the response
+
+Check, in this order:
+
+1. **You actually pulled the new version.** Run `pnpm list @lenne.tech/nest-server`
+   and confirm 11.26.1 (or via the upstream-core-updater agent for vendored projects).
+2. **The user has been synced to the `users` collection.** `mapSessionUser()` looks
+   up the user via `$or: [{ email }, { iamId }]`. A user signed up exclusively via
+   BetterAuth but never created in the legacy `users` collection will fall through
+   to the "no DB user" branch which returns `roles: []` — assign roles in the
+   `users` collection (e.g. via `CoreUserService.setRoles()`), not in the
+   `iam_user` collection.
+3. **The role is a `S_`-prefixed system role.** Per project rule, `S_USER`,
+   `S_VERIFIED`, `S_CREATOR`, `S_SELF` etc. are runtime checks and must never be
+   stored in `user.roles`. They will not appear in the response.
+4. **A custom `mapUser()` override strips `roles`.** Search your project for
+   `mapUser` and confirm the override either calls `super.mapUser(...)` or
+   forwards `roles` explicitly.
+5. **The user-mapper cache is stale.** In production the mapper caches DB lookups
+   for 15s per `iamId`. `CoreUserService.setRoles()` / `update()` already invalidate
+   the cache; manual DB writes do not. Force a re-read by calling
+   `userMapper.invalidateUserCache(iamId)` after a direct write, or wait 15s.
+
+### Swagger schema shows `roles` as `required`
+
+It is not — the property is declared as `required: false`. If your generated
+client marks it required, regenerate after pulling 11.26.1.
+
+---
+
+## 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) — patterns for overriding controller / resolver
+- **Reference Implementation:** `src/server/modules/better-auth/`
+- **Key Files:**
+  - `src/core/modules/better-auth/core-better-auth.controller.ts` — `mapUser()` (the fix), `CoreBetterAuthUserResponse` (the response DTO with the new `roles` field)
+  - `src/core/modules/better-auth/core-better-auth-user.mapper.ts` — `mapSessionUser()` (source of `roles`, with 15s TTL cache and `invalidateUserCache()`)
+
+---
+
+## References
+
+- [Role System](../.claude/rules/role-system.md) — Real roles vs. `S_`-prefixed runtime checks
+- [Module Inheritance Pattern](../.claude/rules/module-inheritance.md) — How to extend `CoreBetterAuthController.mapUser()` cleanly
+- [Migration Guide 11.25.x → 11.26.0](./11.25.x-to-11.26.0.md) — Previous release
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.26.0",
+  "version": "11.26.2",
   "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/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;

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

@@ -2,6 +2,7 @@ import { Logger } from '@nestjs/common';
 import * as crypto from 'crypto';
 import { Request, Response } from 'express';
 
+import { resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper';
 import { isSessionToken } from './core-better-auth-token.helper';
 
 /**
@@ -94,13 +95,12 @@ export function extractSessionToken(
     }
   }
 
-  // Normalize basePath (remove leading slash, replace slashes with dots)
-  const normalizedBasePath = basePath.replace(/^\//, '').replace(/\//g, '.');
-
   // Cookie names to check (in order of priority)
-  // v11.12+: Only native Better-Auth cookie and legacy token
+  // v11.12+: Only native Better-Auth cookie and legacy token. The session cookie
+  // name is resolved through the single shared resolver (honours COOKIE_PREFIX),
+  // so it always matches what Better-Auth actually sets.
   const cookieNames = [
-    `${normalizedBasePath}.session_token`, // Better-Auth native (PRIMARY)
+    resolveBetterAuthSessionCookieName(basePath), // Better-Auth native (PRIMARY)
     BETTER_AUTH_COOKIE_NAMES.TOKEN, // Legacy nest-server cookie
   ];
 
@@ -320,8 +320,7 @@ export async function toWebRequest(req: Request, options: ToWebRequestOptions):
   if (sessionToken) {
     headers.set('authorization', `Bearer ${sessionToken}`);
 
-    const normalizedBasePath = basePath?.replace(/^\//, '').replace(/\//g, '.') || 'iam';
-    const primaryCookieName = `${normalizedBasePath}.session_token`;
+    const primaryCookieName = resolveBetterAuthSessionCookieName(basePath || '/iam');
     const existingCookieString = headers.get('cookie') || '';
 
     // Check if the request already has a signed session cookie.