@lenne.tech/nest-server 11.26.1 → 11.26.2

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.1",
+  "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.

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

@@ -776,8 +776,7 @@ export class CoreBetterAuthController {
     }
 
     // Check cookies - Better-Auth native cookie first, then legacy token
-    const basePath = this.betterAuthService.getBasePath().replace(/^\//, '').replace(/\//g, '.');
-    const cookieName = `${basePath}.session_token`;
+    const cookieName = this.betterAuthService.getSessionCookieName();
     return req.cookies?.[cookieName] || req.cookies?.['token'] || null;
   }
 

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

@@ -9,6 +9,7 @@ import { maskEmail, maskToken } from '../../common/helpers/logging.helper';
 import { IBetterAuth, ICookiesConfig } from '../../common/interfaces/server-options.interface';
 import { ConfigService } from '../../common/services/config.service';
 import { ErrorCode } from '../error-code/error-codes';
+import { resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper';
 import { BetterAuthInstance } from './better-auth.config';
 import { BetterAuthSessionUser } from './core-better-auth-user.mapper';
 import { convertExpressHeaders, parseCookieHeader, signCookieValueIfNeeded } from './core-better-auth-web.helper';
@@ -65,6 +66,11 @@ export const BETTER_AUTH_COOKIE_DOMAIN = 'BETTER_AUTH_COOKIE_DOMAIN';
 export class CoreBetterAuthService implements OnModuleInit {
   private readonly logger = new Logger(CoreBetterAuthService.name);
   private readonly config: IBetterAuth;
+  // Cached cookie prefix — frozen on first read so the value cannot drift away
+  // from the Better-Auth instance (which captured it at bootstrap). Without
+  // this cache a test or fork that mutates `process.env.COOKIE_PREFIX` after
+  // boot would push the service and the Better-Auth instance out of lockstep.
+  private cachedCookiePrefix: null | string = null;
 
   constructor(
     @Optional() @Inject(BETTER_AUTH_INSTANCE) private readonly authInstance: BetterAuthInstance | null,
@@ -280,8 +286,28 @@ export class CoreBetterAuthService implements OnModuleInit {
    * @returns The session cookie name
    */
   getSessionCookieName(): string {
-    const basePath = this.getBasePath()?.replace(/^\//, '').replace(/\//g, '.') || 'iam';
-    return `${basePath}.session_token`;
+    return `${this.getCookiePrefix()}.session_token`;
+  }
+
+  /**
+   * Gets the cookie prefix (the `iam` in `iam.session_token`).
+   *
+   * Single source of truth: honours the `COOKIE_PREFIX` env override and falls
+   * back to the basePath-derived prefix. Every session-cookie call site must
+   * resolve the name through this (or {@link getSessionCookieName}) so the name
+   * stays in lockstep across the whole auth pipeline.
+   *
+   * The resolved value is cached on first read and reused for the lifetime of
+   * the service so it cannot drift away from the Better-Auth instance, which
+   * captures the prefix once at bootstrap. A late mutation of
+   * `process.env.COOKIE_PREFIX` (typical in tests / forked workers) would
+   * otherwise make set, read and clear use different names.
+   */
+  getCookiePrefix(): string {
+    if (this.cachedCookiePrefix === null) {
+      this.cachedCookiePrefix = resolveBetterAuthCookiePrefix(this.getBasePath() || '/iam');
+    }
+    return this.cachedCookiePrefix;
   }
 
   // ===================================================================================================================
@@ -434,8 +460,7 @@ export class CoreBetterAuthService implements OnModuleInit {
       // Browser clients send unsigned cookies, but Better-Auth expects signed cookies
       const cookieHeader = headers.get('cookie');
       if (cookieHeader && this.config?.secret) {
-        const basePath = this.getBasePath()?.replace(/^\//, '').replace(/\//g, '.') || 'iam';
-        const sessionCookieName = `${basePath}.session_token`;
+        const sessionCookieName = this.getSessionCookieName();
         const cookies = parseCookieHeader(cookieHeader);
         let modified = false;
 

package/src/test/test.helper.ts

@@ -8,6 +8,7 @@ import util = require('util');
 import ws = require('ws');
 
 import { getStringIds } from '../core/common/helpers/db.helper';
+import { resolveBetterAuthSessionCookieName } from '../core/modules/better-auth/better-auth-cookie-prefix.helper';
 
 /**
  * GraphQL request type
@@ -830,8 +831,11 @@ export class TestHelper {
    * Sets the token in all relevant cookie names for compatibility.
    */
   static buildBetterAuthCookies(sessionToken: string, basePath: string = 'iam'): Record<string, string> {
+    // Resolve the session cookie name through the shared resolver so tests honour
+    // a COOKIE_PREFIX override exactly like the runtime (otherwise an authenticated
+    // request in a COOKIE_PREFIX=acme app would send the wrong cookie name).
     return {
-      [`${basePath}.session_token`]: sessionToken,
+      [resolveBetterAuthSessionCookieName(basePath)]: sessionToken,
       token: sessionToken,
     };
   }
@@ -861,10 +865,16 @@ export class TestHelper {
   /**
    * Extract a session token from Set-Cookie headers of a supertest response.
    * Handles signed cookies (value.signature format) by returning only the value part.
+   *
+   * The default cookie name is resolved through the shared resolver so it
+   * honours a `COOKIE_PREFIX` env override exactly like the runtime (otherwise
+   * tests against a `COOKIE_PREFIX=acme` app would look for the wrong cookie
+   * and silently return `null`). Tests can still pass an explicit name.
    */
-  static extractSessionToken(response: any, cookieName: string = 'iam.session_token'): null | string {
+  static extractSessionToken(response: any, cookieName?: string): null | string {
+    const resolvedCookieName = cookieName ?? resolveBetterAuthSessionCookieName('/iam');
     const cookies = TestHelper.extractCookies(response);
-    const value = cookies[cookieName];
+    const value = cookies[resolvedCookieName];
     if (!value) {
       return null;
     }