@lenne.tech/nest-server 11.36.2 → 11.36.4

package/docs/REQUEST-LIFECYCLE.md

@@ -1460,6 +1460,14 @@ All security features are configured in `config.env.ts` under the `security` key
 | JWT-only | `cookies: false` | Yes | No | Yes |
 | Hybrid | `cookies: { exposeTokenInBody: true }` | Yes | Yes | Yes |
 
+> **In hybrid mode the body token and the cookie are DIFFERENT values.** With the JWT plugin active,
+> the body carries a JWT while the cookie keeps the opaque Better-Auth session token — Better-Auth
+> resolves a session by that opaque value, so a JWT in the cookie authenticates nothing. Treating
+> them as one token is what caused 11.36.3, where sign-in succeeded and every following request was
+> anonymous. `setSessionCookies()` now refuses a JWT-shaped cookie value. Hybrid mode is confined to
+> development and CI: `assertCookiesProductionSafe()` forbids `exposeTokenInBody` in `production`
+> and `staging`.
+
 ### Guardian Gates
 
 | Config Path | Type | Default | Description |

package/migration-guides/11.36.2-to-11.36.3.md

@@ -0,0 +1,131 @@
+# Migration Guide: 11.36.2 → 11.36.3
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None |
+| **Bugfixes** | **The session cookie carried the wrong token in hybrid mode** — sign-in succeeded and every following request was anonymous (§1). Development and CI only |
+| **Migration Effort** | **None for most projects.** `pnpm update`. Read §2 only if you OVERRIDE `processAuthResult()` or `processCookies()` |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.36.3
+```
+
+**Vendor-mode projects:** the fix spans four files that form an ATOMIC set — syncing a subset
+produces a TypeScript build failure, because the cookie helper and the controller both now import
+`isJwtShaped` from the token helper, and the controller imports `hasToken` from the types module:
+
+- `src/core/modules/better-auth/better-auth.types.ts`
+- `src/core/modules/better-auth/core-better-auth-token.helper.ts`
+- `src/core/modules/better-auth/core-better-auth-cookie.helper.ts`
+- `src/core/modules/better-auth/core-better-auth.controller.ts`
+
+---
+
+## 1. Session cookie no longer carries the body's JWT
+
+**Were you affected?** Only if all three of these are true:
+
+1. `cookies.exposeTokenInBody: true`, **and**
+2. the Better-Auth JWT plugin is enabled, **and**
+3. the environment is `local`, `development`, `ci` or `e2e`.
+
+**Production and staging were never affected.** `assertCookiesProductionSafe()` throws at boot when
+`exposeTokenInBody` is set in either, so no live deployment could reach this state. If you are
+upgrading because you read "session cookie bug", this is a development and CI fix — no emergency.
+
+**The symptom, if you had it:** sign-in returns `200` and sets a cookie, and the very next request is
+anonymous. `GET /iam/session` answers `success: false` for a session that plainly exists in the
+database. In a browser the user is signed out again the moment they navigate. Cookie-based E2E
+suites fail in CI while passing locally — because in this framework's own `config.env.ts` only `ci`
+and `e2e` set `exposeTokenInBody`, while `local`, `development` and `production` leave it unset. In
+cookies-only mode both carriers hold the same value, so the defect is invisible there. Check your own
+config rather than assuming these defaults.
+
+**The cause.** With `exposeTokenInBody`, `resolveJwtToken()` converts the opaque session token into a
+JWT for the response body — correct, that is what a bearer client wants. The cookie was then written
+with that same JWT. Better-Auth resolves a session by the **opaque** token it stored, so a JWT there
+matches nothing.
+
+**What changed.** The cookie now receives the opaque session token while the body keeps the JWT.
+Beyond the fix itself, `setSessionCookies()` now **refuses** a JWT-shaped value outright and logs an
+error, so the same mistake can no longer be made silently by any future call site or by your own
+override.
+
+Nothing to configure. If you work around this today by disabling `exposeTokenInBody` in CI, you can
+undo that.
+
+---
+
+## 2. If you override `processAuthResult()` or a sign-in handler (action required)
+
+`BetterAuthCookieHelper.processAuthResult()` takes a fifth parameter, `sessionToken`, since 11.36.3:
+
+```typescript
+processAuthResult(res, result, cookiesEnabled, exposeTokenInBody, sessionToken?)
+```
+
+**TypeScript permits an override with fewer parameters.** A subclass still declaring the old
+four-argument signature compiles cleanly and silently drops the session token. Check yours:
+
+```bash
+grep -rn "processAuthResult\|processCookies" src/
+```
+
+Since 11.36.3 that mistake is no longer silent — `setSessionCookies()` refuses the JWT and logs an
+error, so you lose the cookie rather than getting one that authenticates nothing. Still worth fixing:
+add the parameter and pass it through.
+
+**Deriving the value yourself?** Use `this.sessionTokenForCookie(response)` rather than reading
+`response.session?.token`. `session.token` is optional on the `hasSession()` type guard, and
+`api.signInEmail()` returns the token at the **top level with no `session` object at all** — so the
+obvious expression yields `undefined` in exactly the case that matters, and the cookie falls back to
+the JWT.
+
+---
+
+## 3. Tooling, framework repo only
+
+Not shipped behaviour; relevant if you maintain a fork of this repo's tooling.
+
+`scripts/check-mutations.mjs` gained `--no-infra` (the mutations that need no MongoDB) and
+`--since=<ref>` (mutations touching files changed since a ref). Both are for local work and print
+what they did **not** check. `--since` is a heuristic — it does not follow transitive imports — and
+is deliberately kept off the publish path.
+
+Several defects in that script were fixed in the same pass, all of the same family: a non-zero exit
+with no reported test failures is now **INCONCLUSIVE** rather than "evidence confirmed"; the parallel
+path no longer disables the e2e starvation guards it itself triggers; the worktree-failure fallback
+no longer runs every mutation concurrently against the real working tree; the race guard no longer
+overwrites the concurrent edit it was written to detect; `--since` no longer accepts a value git
+would read as an option (`--output=<path>` truncated arbitrary files); and an empty selection exits
+`2` instead of `0`, so no wrapper can read "nothing ran" as "everything passed".
+
+---
+
+## Module Documentation
+
+The better-auth module's own docs were updated in the same pass — read these if §2 applies to you:
+
+| Document | What changed |
+|----------|--------------|
+| [`better-auth/CUSTOMIZATION.md`](../src/core/modules/better-auth/CUSTOMIZATION.md) | New section *"Session cookie vs. body token — do not conflate them"*: which carrier holds which value, why `sessionTokenForCookie()` is the right source in an override, and the fifth-parameter warning |
+| [`better-auth/README.md`](../src/core/modules/better-auth/README.md) | The `cookies` row now states that the body token is a JWT when the JWT plugin is active, and that this is NOT the value the session cookie carries |
+| [`better-auth/INTEGRATION-CHECKLIST.md`](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md) | §6 (the `ci` / `e2e` config block that turns `exposeTokenInBody` on) now points at the CUSTOMIZATION section above |
+| [`docs/REQUEST-LIFECYCLE.md`](../docs/REQUEST-LIFECYCLE.md) | The auth-modes table gained a note on the hybrid row |
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Refusing to write a JWT into the session cookie` in the log | An override or custom handler passed the body token | §2 — pass the opaque session token, or use `sessionTokenForCookie()` |
+| Cookie auth worked before the upgrade, now no cookie is set | Same as above, previously silent | §2 |
+| `check:mutations` reports INCONCLUSIVE | The run failed without reporting failing tests — crash, timeout or starvation | Re-run that mutation alone; it is no longer counted as evidence |

package/migration-guides/11.36.3-to-11.36.4.md

@@ -0,0 +1,145 @@
+# Migration Guide: 11.36.3 → 11.36.4
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None |
+| **Bugfixes** | **The test-database drop guard accepted ordinary project databases** — a name merely CONTAINING `ci`/`test` read as disposable, so an e2e run started from an `lt dev` shell could drop the developer's DEVELOPMENT database (§1). Framework-internal, but every starter-derived project carries a private copy of the same code |
+| **Migration Effort** | **None** for the framework itself — `tests/` is not published. **~1 minute, recommended**, if your project was generated from `nest-server-starter`: apply the one-line fix in §1 to your own `tests/db-lifecycle.reporter.ts` |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.36.4
+```
+
+Then read §1 — it is the only thing in this release that can affect you, and `pnpm update` does
+**not** deliver it, because the affected file lives in your repository, not in the package.
+
+---
+
+## 1. Recommended: tighten the test-database drop guard in your own `tests/`
+
+**Why this reaches you at all.** `tests/db-lifecycle.reporter.ts` is not part of the npm package
+(`package.json` → `files` does not include `tests/`) and not part of the vendor-mode file set. It is
+a **template** file: `nest-server-starter` ships it, and every project ever generated from the
+starter holds a private copy that no update channel ever touches. So this guide is the only way the
+fix reaches an existing project.
+
+**Were you affected?** Only if all three are true:
+
+1. Your project's slug contains `ci`, `test`, `e2e` or `acctest` **as a substring** — including
+   inside an ordinary word: `ci` hides in so**ci**al, spe**ci**al, finan**ci**al, invoi**ci**ng,
+   pri**ci**ng, muni**ci**pal; `test` hides in la**test**, con**test**, **test**imonials.
+2. You use `lt dev up`, which exports `MONGODB_URI` pointing at `<slug>-local` — your **development**
+   database.
+3. You started the e2e suite from that same shell.
+
+Then `tests/global-setup.ts` dropped that database. The guard meant to prevent exactly this accepted
+it, because it matched the marker anywhere in the name rather than as a delimited segment.
+
+### The fix
+
+```diff
+- export const SAFE_TEST_DB_PATTERN = /(e2e|ci|test|acctest)/i;
++ export const SAFE_TEST_DB_PATTERN = /(^|[-_])(e2e|ci|test|acctest)([-_]|$)/i;
+```
+
+The marker must now be a whole segment, delimited by `-`, `_`, or a string boundary.
+
+### Check your own database names before applying it
+
+The change is a strict narrowing — every name the new pattern accepts, the old one accepted too, so
+it cannot start dropping something it previously spared. The risk runs the other way: if your **base**
+test database name does not carry the marker as a delimited segment (`shope2e`, `app-e2edb`,
+`projecttest`), the guard now refuses it and **cleanup silently stops collecting** — the databases
+accumulate with nothing removing them.
+
+```bash
+# What does your suite actually name its databases?
+grep -n "mongodb://" src/config.env.ts
+```
+
+`myproject-e2e` and `myproject_ci` are fine. `myproje2e` is not — rename the database rather than
+loosening the pattern.
+
+Since 11.36.4 both sweep loops **count and log** the stale databases the guard refused, so this
+condition announces itself instead of leaking quietly:
+
+```
+Startup sweep: 3 stale database(s) skipped by the safety guard —
+"shope2e" needs a delimited e2e/ci/test/acctest segment for cleanup to work.
+```
+
+### Two further hardening steps, worth copying
+
+Both live in the same file and are optional, but they close the residual cases the pattern alone
+cannot:
+
+**A second guard for the one drop site that has no other condition.** The startup sweep and the
+post-run collection both additionally require `isStaleTestDb()` — the name must belong to your own
+base. The externally-supplied-`MONGODB_URI` branch has no such backstop, and a project slug may
+legitimately carry a marker as a *whole word*: `ci` is the ordinary German abbreviation for
+*Corporate Identity*, `test` a product noun for an exam. `ci-portal-local` passes the segment rule.
+
+```typescript
+export const NON_DISPOSABLE_DB_PATTERN
+  = /(^|[-_])(local|dev|develop|development|prod|production|staging|stage|live)([-_]|$)/i;
+
+export function isDroppableTestDb(name: string): boolean {
+  return SAFE_TEST_DB_PATTERN.test(name) && !NON_DISPOSABLE_DB_PATTERN.test(name);
+}
+```
+
+Then use `isDroppableTestDb(db.databaseName)` in place of `SAFE_TEST_DB_PATTERN.test(...)` in
+`tests/global-setup.ts` — **only there**. Applying it to the sweep paths could only turn a collected
+database into a leaked one.
+
+**Refuse a URI that names no database.** `mongodb://127.0.0.1` makes the driver fall back to its
+default database, `test` — a name the guard accepts, so a truncated `MONGODB_URI` dropped the
+server's `test` database instead of failing. Note that this needs the `splitMongoUri()` fix too: the
+previous greedy form reported the **host** as the database name for such a URI, so the check could
+never fire.
+
+```typescript
+const match = uri.match(/^(mongodb(?:\+srv)?:\/\/[^/?]*)(?:\/([^/?]*))?(\?.*)?$/i);
+```
+
+This also fixes a second case the greedy form got wrong: an option value containing a slash
+(`?tlsCAFile=/etc/ssl/ca.pem`) previously reported `ca.pem` as the database name.
+
+### Pin it
+
+The framework's own spec is `tests/unit/db-lifecycle-guard.spec.ts` — copy it alongside the fix. Its
+refusal list *is* the specification, and reverting the anchoring turns 13 cases red.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| npm-mode projects | Unaffected by the package update; apply §1 to your own `tests/` |
+| Vendor-mode projects | Same — `tests/` is outside the vendor file set |
+| CI pipelines that pin `MONGODB_URI` | Unaffected, unless the pinned URI names no database or carries an environment suffix. A CI database called `myproject-ci` is fine; one called `myproject-ci-staging` is now refused |
+| Projects not generated from `nest-server-starter` | Nothing to do |
+
+---
+
+## Troubleshooting
+
+**`Refusing to dropDatabase("…"): not a recognized disposable test database`**
+Your `MONGODB_URI` points at something the guard will not delete. That is the guard working. Check
+whether the URI is aimed at your development database — an `lt dev` shell exports it that way — and
+point it at a disposable test database instead. Do not loosen the pattern to get past this.
+
+**`Refusing to use MONGODB_URI="…": it names no database`**
+The URI has no path (`mongodb://host` rather than `mongodb://host/mydb`). Add the database name.
+
+**`N stale database(s) skipped by the safety guard`**
+Your base database name does not carry a delimited marker, so cleanup cannot collect its leftovers.
+Rename the database (see §1).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.36.2",
+  "version": "11.36.4",
   "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/CUSTOMIZATION.md

@@ -181,6 +181,31 @@ export class IamController extends CoreBetterAuthController {
 }
 ```
 
+### Session cookie vs. body token — do not conflate them
+
+If you override a sign-in / sign-up handler, or `processCookies()` itself, know that these two
+carry **different values** whenever `cookies.exposeTokenInBody` is on together with the JWT plugin:
+
+| Carrier                              | Value                                    |
+| ------------------------------------ | ---------------------------------------- |
+| `Set-Cookie: <prefix>.session_token` | the **opaque** Better-Auth session token |
+| response body `token`                | a **JWT**                                |
+
+Better-Auth resolves a session by the opaque token it stored, so a JWT in the cookie authenticates
+nothing — sign-in succeeds and every following request is anonymous. That shipped once (11.36.3).
+
+In an override, derive the cookie value with `this.sessionTokenForCookie(response)` rather than
+reading `response.session?.token` yourself: `session.token` is optional on the `hasSession()` type
+guard, and `api.signInEmail()` returns the token at the top level with no `session` object at all,
+so the obvious expression yields `undefined` in exactly the case that matters.
+
+You do not have to get this right for it to be safe: `setSessionCookies()` refuses a JWT-shaped
+value and logs an error, so a mistake here costs you the cookie, not the session.
+
+Overriding `processAuthResult()` on `BetterAuthCookieHelper`? Keep the fifth parameter
+(`sessionToken`). TypeScript accepts an override with fewer parameters, so dropping it compiles
+cleanly and silently disables the distinction above.
+
 ### Important Notes
 
 - Always extend `CoreBetterAuthController`

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -179,6 +179,12 @@ export class ServerModule {}
 > **Never set `exposeTokenInBody: true` in production** — the framework throws at
 > startup if this is detected in `production` or `staging` environments (XSS-risk guard).
 >
+> **In this hybrid mode the body token and the session cookie carry DIFFERENT values** whenever
+> the JWT plugin is also active: the body gets a JWT, the cookie keeps the opaque Better-Auth
+> session token. If you override a sign-in handler or `processCookies()`, read
+> [CUSTOMIZATION.md → _Session cookie vs. body token_](./CUSTOMIZATION.md#session-cookie-vs-body-token--do-not-conflate-them)
+> before you derive the cookie value yourself — conflating the two is what caused 11.36.3.
+>
 > To keep the old behavior (cookies off, tokens in body everywhere), set `cookies: false`.
 
 #### Zero-Config (Default):

package/src/core/modules/better-auth/README.md

@@ -262,10 +262,10 @@ Read the security section below for production deployments.
 
 **Global server-level settings that affect BetterAuth behavior (since v11.25.0):**
 
-| Setting (top-level `IServerOptions`)                                          | Technical Purpose                                                                                                                                                                      | Impact of Wrong Value                                                                                                                                                                                                  |
-| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cookies` (`boolean \| ICookiesConfig`, default: `true`)                      | Controls cookie-parser middleware and session cookie setting. `cookies.exposeTokenInBody` additionally returns the token in the response body (test-only; **forbidden in production**) | Tokens missing from response body surprises test clients; `exposeTokenInBody` in prod = XSS-risk, framework throws at startup                                                                                          |
-| `cors` (`boolean \| ICorsConfig`, default: enabled with auto-derived origins) | Unified CORS config — propagates to GraphQL (Apollo), REST (Express), and BetterAuth `trustedOrigins` from a single source                                                             | `cors.enabled: false` disables the REST/GraphQL layers; `cors.allowAll` mirrors any request origin for REST/GraphQL (dev only) but BetterAuth keeps restricting to `appUrl` (its origin check has no "allow all" mode) |
+| Setting (top-level `IServerOptions`)                                          | Technical Purpose                                                                                                                                                                                                                                                                                    | Impact of Wrong Value                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cookies` (`boolean \| ICookiesConfig`, default: `true`)                      | Controls cookie-parser middleware and session cookie setting. `cookies.exposeTokenInBody` additionally returns a token in the response body — a JWT when the JWT plugin is active, which is NOT the value the session cookie carries (see CUSTOMIZATION.md) (test-only; **forbidden in production**) | Tokens missing from response body surprises test clients; `exposeTokenInBody` in prod = XSS-risk, framework throws at startup                                                                                          |
+| `cors` (`boolean \| ICorsConfig`, default: enabled with auto-derived origins) | Unified CORS config — propagates to GraphQL (Apollo), REST (Express), and BetterAuth `trustedOrigins` from a single source                                                                                                                                                                           | `cors.enabled: false` disables the REST/GraphQL layers; `cors.allowAll` mirrors any request origin for REST/GraphQL (dev only) but BetterAuth keeps restricting to `appUrl` (its origin check has no "allow all" mode) |
 
 **For Development:** The defaults (`http://localhost:3000`, `/iam`) are correct.
 

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

@@ -119,6 +119,36 @@ export function hasSession<T>(
   );
 }
 
+/**
+ * Whether a Better-Auth response carries a usable top-level `token`.
+ *
+ * Sibling of {@link hasSession} / {@link hasUser}, and the reason it exists: `api.signInEmail()`
+ * and `api.signUpEmail()` return the session token at the TOP level and no `session` object at all,
+ * so `response.session?.token` is `undefined` on exactly the routes that matter most.
+ */
+export function hasToken<T>(response: T): response is T & { token: string } {
+  return typeof (response as { token?: unknown })?.token === 'string' && (response as { token: string }).token !== '';
+}
+
+/**
+ * The OPAQUE Better-Auth session token carried by an outgoing auth response, if any.
+ *
+ * A PRECEDENCE CHAIN, not a ternary on {@link hasSession}, and the difference is load-bearing:
+ * `hasSession()` narrows to `session: { …; token?: string }`, so `token` is OPTIONAL on the guard
+ * itself. A response carrying a `session` object WITHOUT a token inside it satisfies the guard,
+ * yields `undefined` and skips the top-level fallback. `api.signInEmail()` is the mirror case:
+ * top-level token, no `session` object at all.
+ *
+ * Neither shape is reachable in better-auth 1.6.26 today; both are one minor bump away, and the
+ * failure is silent — which is why every caller that needs the stored session value shares this
+ * one chain rather than re-deriving it. Callers that need the value for a COOKIE must additionally
+ * refuse a JWT; see `CoreBetterAuthController.sessionTokenForCookie()`.
+ */
+export function sessionTokenFromResponse(response: unknown): string | undefined {
+  const fromSession = hasSession(response) && hasToken(response.session) ? response.session.token : undefined;
+  return fromSession ?? (hasToken(response) ? response.token : undefined);
+}
+
 /**
  * Type guard to check if response has user
  * Preserves the original type while asserting user is defined

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

@@ -3,8 +3,20 @@ import { Response } from 'express';
 
 import { isProductionLikeEnv } from '../../common/helpers/cookies.helper';
 import { resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper';
+import { isJwtShaped } from './core-better-auth-token.helper';
 import { signCookieValue } from './core-better-auth-web.helper';
 
+/**
+ * Last-resort logger for the JWT refusal below.
+ *
+ * `BetterAuthCookieHelperConfig.logger` is optional and `createCookieHelper()` takes it as an
+ * optional third argument, so a consumer constructing this class directly gets none. The refusal
+ * is the one message here that must never be silent: without it the symptom is "no cookie, HTTP
+ * 200, no explanation" — the same diagnostic blind spot that let the defect it guards against ship
+ * in the first place.
+ */
+const fallbackLogger = new Logger('BetterAuthCookieHelper');
+
 /**
  * Standard cookie names used by Better-Auth and nest-server.
  *
@@ -193,6 +205,24 @@ export class BetterAuthCookieHelper {
    * @param _sessionId - Deprecated, kept for API compatibility but no longer used
    */
   setSessionCookies(res: Response, sessionToken: string, _sessionId?: string): void {
+    // Structural invariant, independent of whichever call site got here: Better-Auth resolves a
+    // session by the OPAQUE token it stored, so a JWT in this cookie authenticates nothing. That is
+    // not hypothetical — it shipped: with `cookies.exposeTokenInBody` the body's JWT was written
+    // here, sign-in appeared to work and every following request was anonymous.
+    //
+    // Enforced here rather than at the call sites because a call site can forget, and this one
+    // cannot: whoever adds the next authentication route inherits the guard for free.
+    if (isJwtShaped(sessionToken)) {
+      // NOT `this.config.logger?.error(...)`: `logger` is optional, and a silent refusal leaves the
+      // caller with no cookie, a 200 response and nothing to go on.
+      (this.config.logger ?? fallbackLogger).error(
+        'Refusing to write a JWT into the session cookie — Better-Auth resolves a session by the ' +
+          'opaque token it stored, so this would authenticate nothing. Pass the session token, ' +
+          'not the value destined for the response body.',
+      );
+      return;
+    }
+
     const cookieOptions = this.getDefaultCookieOptions();
 
     // Sign the session token for Better-Auth
@@ -323,6 +353,13 @@ export class BetterAuthCookieHelper {
    * @param result - The result object to process (modified in place)
    * @param cookiesEnabled - Whether cookie handling is enabled (from config)
    * @param exposeTokenInBody - Whether to keep the token in the response body (default: false)
+   * @param sessionToken - The OPAQUE Better-Auth session token, for the COOKIE. Pass it whenever
+   *   the body's `token` may already be a JWT — i.e. `exposeTokenInBody` together with the JWT
+   *   plugin. Better-Auth resolves a session by the opaque value it stored, so a JWT in the cookie
+   *   authenticates nothing: sign-in appears to succeed and every following request is anonymous.
+   *   Falls back to `result.token`, which is correct only in cookies-only mode, where the two
+   *   values are the same thing. `setSessionCookies()` refuses a JWT-shaped value regardless, so
+   *   omitting this fails loudly rather than silently.
    * @returns The modified result (same reference as input)
    */
   processAuthResult<T extends CookieProcessingResult>(
@@ -330,19 +367,24 @@ export class BetterAuthCookieHelper {
     result: T,
     cookiesEnabled: boolean,
     exposeTokenInBody: boolean = false,
+    sessionToken?: string,
   ): T {
     if (!cookiesEnabled) {
       return result;
     }
 
-    if (result.token) {
-      // Set cookies
-      this.setSessionCookies(res, result.token);
+    // The cookie and the body carry DIFFERENT values whenever both delivery modes are on at once —
+    // see the `sessionToken` note on the signature above. `result.token` is the fallback for
+    // cookies-only mode, where the two are the same thing anyway.
+    const cookieToken = sessionToken ?? result.token;
 
-      // Remove token from response body unless exposeTokenInBody is enabled
-      if (!exposeTokenInBody) {
-        delete result.token;
-      }
+    if (cookieToken) {
+      this.setSessionCookies(res, cookieToken);
+    }
+
+    // Remove token from response body unless exposeTokenInBody is enabled
+    if (result.token && !exposeTokenInBody) {
+      delete result.token;
     }
 
     return result;

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

@@ -156,6 +156,22 @@ export function isJwt(token: string): boolean {
   return result.type === TokenType.LEGACY_JWT || result.type === TokenType.BETTER_AUTH_JWT;
 }
 
+/**
+ * Whether a value has the SHAPE of a JWT — three dot-separated segments starting with `eyJ`.
+ *
+ * Deliberately structural and deliberately not `startsWith('eyJ')` alone: a Better-Auth session
+ * token is `generateId(32)` over `a-zA-Z0-9-_`, so roughly one in 262 144 of them begins with those
+ * three characters by chance. That is rare enough to reach production as a ghost and frequent
+ * enough to happen. Requiring the dots removes the false positive entirely, because an opaque
+ * session token can never contain one.
+ *
+ * Unlike {@link analyzeToken} this makes no claim about the token's CONTENTS or validity — it
+ * answers "could this be a JWT?", which is the question a guard on a session cookie needs.
+ */
+export function isJwtShaped(value: unknown): value is string {
+  return typeof value === 'string' && value.startsWith('eyJ') && value.split('.').length === 3;
+}
+
 /**
  * Checks if a token is a Legacy JWT (Passport/JWT strategy).
  *

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

@@ -34,11 +34,17 @@ import type { ICookiesConfig } from '../../common/interfaces/server-options.inte
 import { maskEmail, maskToken } from '../../common/helpers/logging.helper';
 import { ConfigService } from '../../common/services/config.service';
 import { ErrorCode } from '../error-code/error-codes';
-import { BetterAuthSignInResponse, hasSession, hasUser, requires2FA } from './better-auth.types';
+import {
+  BetterAuthSignInResponse,
+  hasSession,
+  hasUser,
+  requires2FA,
+  sessionTokenFromResponse,
+} from './better-auth.types';
 import { BetterAuthCookieHelper, createCookieHelper } from './core-better-auth-cookie.helper';
 import { CoreBetterAuthEmailVerificationService } from './core-better-auth-email-verification.service';
 import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service';
-import { isSessionToken } from './core-better-auth-token.helper';
+import { isJwtShaped, isSessionToken } from './core-better-auth-token.helper';
 import { BetterAuthSessionUser, CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
 import { convertExpressHeaders, sendWebResponse, toWebRequest } from './core-better-auth-web.helper';
 import { CoreBetterAuthService } from './core-better-auth.service';
@@ -469,8 +475,15 @@ export class CoreBetterAuthController {
         // Get token: JWT accessToken > top-level token > session.token
         const rawToken =
           responseAny.accessToken || responseAny.token || (hasSession(response) ? response.session.token : undefined);
+        // `rawToken` prefers the top-level token; `sessionTokenForCookie()` prefers `session.token`.
+        // The inversion is deliberate: the body wants whatever Better-Auth called the token, the
+        // cookie wants the stored session value specifically.
         const token = await this.resolveJwtToken(rawToken);
 
+        // Kept separately from `token`: `resolveJwtToken` turns the session token into a JWT when
+        // the body is meant to carry one, and the cookie must not get that JWT.
+        const sessionToken = this.sessionTokenForCookie(response);
+
         const result: CoreBetterAuthResponse = {
           requiresTwoFactor: false,
           session: hasSession(response) ? this.mapSession(response.session) : undefined,
@@ -479,7 +492,7 @@ export class CoreBetterAuthController {
           user: mappedUser ? this.mapUser(response.user, mappedUser) : undefined,
         };
 
-        return this.processCookies(res, result);
+        return this.processCookies(res, result, sessionToken);
       }
 
       throw new UnauthorizedException(ErrorCode.INVALID_CREDENTIALS);
@@ -583,7 +596,11 @@ export class CoreBetterAuthController {
         // The user must verify their email before they can use any session
         if (this.emailVerificationService?.isEnabled()) {
           // Revoke the Better-Auth session server-side so the token is invalidated
-          const sessionToken = hasSession(response) ? response.session.token : undefined;
+          // Shared chain, NOT `hasSession(response) ? response.session.token : undefined`: `token` is
+          // optional on the guard, so that expression returns `undefined` for a response shape that
+          // still carries a revocable token — and the endpoint would then report a revoked session
+          // while a live one remained in the database.
+          const sessionToken = sessionTokenFromResponse(response);
           if (sessionToken) {
             await this.betterAuthService.revokeSession(sessionToken);
           }
@@ -607,7 +624,9 @@ export class CoreBetterAuthController {
           user: mappedUser ? this.mapUser(response.user, mappedUser) : undefined,
         };
 
-        return this.processCookies(res, result);
+        // Same as sign-in: the cookie gets the opaque session token, the body keeps whatever
+        // `resolveJwtToken` produced.
+        return this.processCookies(res, result, this.sessionTokenForCookie(response));
       }
 
       throw new BadRequestException(ErrorCode.SIGNUP_FAILED);
@@ -867,6 +886,27 @@ export class CoreBetterAuthController {
     };
   }
 
+  /**
+   * The value that belongs in the SESSION COOKIE — never the value destined for the response body.
+   *
+   * Not to be confused with {@link extractSessionToken}, which reads a token out of an INCOMING
+   * request. This one derives it from an OUTGOING Better-Auth response; the two run in opposite
+   * directions, which is why they do not share a name.
+   *
+   * The precedence chain itself lives in {@link sessionTokenFromResponse}, shared with the
+   * session-revocation paths so the two cannot drift. What this method adds is the COOKIE-specific
+   * half: a JWT-shaped result is refused outright, because Better-Auth resolves a session by the
+   * opaque value it stored and a JWT in the cookie would authenticate nothing.
+   *
+   * Override to source the cookie token differently. `setSessionCookies()` refuses a JWT-shaped
+   * value regardless, so an override cannot reintroduce the defect either.
+   */
+  protected sessionTokenForCookie(response: unknown): string | undefined {
+    const resolved = sessionTokenFromResponse(response);
+    // A JWT here means somebody handed over the body's value; refuse rather than pass it on.
+    return isJwtShaped(resolved) ? undefined : resolved;
+  }
+
   /**
    * Process cookies for response
    *
@@ -903,8 +943,14 @@ export class CoreBetterAuthController {
       return result;
     }
 
-    // Otherwise, use the cookie helper's standard processing
-    return this.cookieHelper.processAuthResult(res, result, cookiesEnabled, exposeTokenInBody);
+    // Otherwise the helper's standard processing. Read this carefully before deleting anything:
+    // a TRUTHY `sessionToken` reaches here only when cookies are disabled, in which case
+    // `processAuthResult` returns immediately anyway. But `sessionTokenForCookie()` legitimately
+    // returns `undefined` — no token in the response, or a JWT it refused — and THAT case falls
+    // through with cookies ENABLED, where `cookieToken` falls back to `result.token`, i.e. the
+    // body's JWT. What makes that safe is not unreachability; it is `setSessionCookies()` refusing
+    // a JWT-shaped value. Remove the refusal and this line reinstates the defect.
+    return this.cookieHelper.processAuthResult(res, result, cookiesEnabled, exposeTokenInBody, sessionToken);
   }
 
   /**