feat: rename session strategy (#3144)

BREAKING CHANGE:

The `session.jwt: boolean` option has been renamed to `session.strategy: "jwt" | "database"`. The goal is to make the user's options more intuitive:

1. No adapter, `strategy: "jwt"`: This is the default. The session is saved in a cookie and never persisted anywhere.
2. With Adapter, `strategy: "database"`: If an Adapter is defined, this will be the implicit setting. No user config is needed.
3. With Adapter, `strategy: "jwt"`: The user can explicitly instruct `next-auth` to use JWT even if a database is available. This can result in faster lookups in compromise of lowered security. Read more about: https://next-auth.js.org/faq#json-web-tokens

Example:

```diff
session: {
-  jwt: true,
+ strategy: "jwt",
}
```

Author: balazsorban44

src/core/init.ts

@@ -85,7 +85,8 @@ export async function init({
     providers,
     // Session options
     session: {
-      jwt: !userOptions.adapter, // If no adapter specified, force use of JSON Web Tokens (stateless)
+      // If no adapter specified, force use of JSON Web Tokens (stateless)
+      strategy: userOptions.adapter ? "database" : "jwt",
       maxAge,
       updateAge: 24 * 60 * 60,
       ...userOptions.session,

src/core/lib/callback-handler.ts

@@ -36,7 +36,7 @@ export default async function callbackHandler(params: {
     adapter,
     jwt,
     events,
-    session: { jwt: useJwtSession },
+    session: { strategy: sessionStrategy },
   } = options
 
   // If no adapter is configured then we don't have a database and cannot
@@ -61,6 +61,8 @@ export default async function callbackHandler(params: {
   let user: AdapterUser | null = null
   let isNewUser = false
 
+  const useJwtSession = sessionStrategy === "jwt"
+
   if (sessionToken) {
     if (useJwtSession) {
       try {

src/core/lib/cookie.ts

@@ -1,8 +1,8 @@
 // REVIEW: Is there any way to defer two types of strings?
-import { NextAuthResponse } from "../../lib/types"
-import { CookiesOptions } from "../.."
-import { CookieOption } from "../types"
-import { ServerResponse } from "http"
+import type { NextAuthResponse } from "../../lib/types"
+import type { CookiesOptions } from "../.."
+import type { CookieOption, SessionStrategy } from "../types"
+import type { ServerResponse } from "http"
 
 /** Stringified form of `JWT`. Extract the content with `jwt.decode` */
 export type JWTString = string
@@ -12,8 +12,11 @@ export type SetCookieOptions = Partial<CookieOption["options"]> & {
   encode?: (val: unknown) => string
 }
 
-/** If `options.session.jwt` is set to `true`, this is a stringified `JWT`. In case of a database persisted session, this is the `sessionToken` of the session in the database.. */
-export type SessionToken<T extends "jwt" | "db" = "jwt"> = T extends "jwt"
+/**
+ * If `options.session.strategy` is set to `jwt`, this is a stringified `JWT`.
+ * In case of `strategy: "database"`, this is the `sessionToken` of the session in the database.
+ */
+export type SessionToken<T extends SessionStrategy = "jwt"> = T extends "jwt"
   ? JWTString
   : string
 

src/core/routes/callback.ts

@@ -27,12 +27,14 @@ export default async function callback(params: {
     jwt,
     events,
     callbacks,
-    session: { jwt: useJwtSession, maxAge: sessionMaxAge },
+    session: { strategy: sessionStrategy, maxAge: sessionMaxAge },
     logger,
   } = options
 
   const cookies: cookie.Cookie[] = []
 
+  const useJwtSession = sessionStrategy === "jwt"
+
   if (provider.type === "oauth") {
     try {
       const {

src/core/routes/session.ts

@@ -18,9 +18,14 @@ export default async function session(
   params: SessionParams
 ): Promise<OutgoingResponse<Session | {}>> {
   const { options, sessionToken } = params
-  const { adapter, jwt, events, callbacks, logger } = options
-  const useJwtSession = options.session.jwt
-  const sessionMaxAge = options.session.maxAge
+  const {
+    adapter,
+    jwt,
+    events,
+    callbacks,
+    logger,
+    session: { strategy: sessionStrategy, maxAge: sessionMaxAge },
+  } = options
 
   const response: OutgoingResponse<Session | {}> = {
     body: {},
@@ -30,7 +35,7 @@ export default async function session(
 
   if (!sessionToken) return response
 
-  if (useJwtSession) {
+  if (sessionStrategy === "jwt") {
     try {
       // Decrypt and verify token
       const decodedToken = await jwt.decode({ ...jwt, token: sessionToken })
@@ -77,7 +82,7 @@ export default async function session(
       await events.session?.({ session, token })
     } catch (error) {
       // If JWT not verifiable, make sure the cookie for it is removed and return empty object
-      logger.error("JWT_SESSION_ERROR", (error as Error))
+      logger.error("JWT_SESSION_ERROR", error as Error)
 
       response.cookies?.push({
         name: options.cookies.sessionToken.name,
@@ -160,7 +165,7 @@ export default async function session(
         })
       }
     } catch (error) {
-      logger.error("SESSION_ERROR", (error as Error))
+      logger.error("SESSION_ERROR", error as Error)
     }
   }
 

src/core/routes/signout.ts

@@ -9,15 +9,14 @@ export default async function signout(params: {
   sessionToken?: string
 }): Promise<OutgoingResponse> {
   const { options, sessionToken } = params
-  const { adapter, cookies, events, jwt, callbackUrl, logger } = options
+  const { adapter, cookies, events, jwt, callbackUrl, logger, session } =
+    options
 
   if (!sessionToken) {
     return { redirect: callbackUrl }
   }
 
-  const useJwtSession = options.session.jwt
-
-  if (useJwtSession) {
+  if (session.strategy === "jwt") {
     // Dispatch signout event
     try {
       const decodedJwt = await jwt.decode({ ...jwt, token: sessionToken })

src/core/types.ts

@@ -429,9 +429,23 @@ export interface DefaultSession extends Record<string, unknown> {
  */
 export interface Session extends Record<string, unknown>, DefaultSession {}
 
+export type SessionStrategy = "jwt" | "database"
+
 /** [Documentation](https://next-auth.js.org/configuration/options#session) */
 export interface SessionOptions {
-  jwt: boolean
+  /**
+   * Choose how you want to save the user session.
+   * The default is `"jwt"`, an encrypted JWT (JWE) in the session cookie.
+   *
+   * If you use an `adapter` however, we default it to `"database"` instead.
+   * You can still force a JWT session by explicitly defining `"jwt"`.
+   *
+   * When using `"database"`, the session cookie will only contain a `sessionToken` value,
+   * which is used to look up the session in the database.
+   *
+   * [Documentation](https://next-auth.js.org/configuration/options#session) | [Adapter](https://next-auth.js.org/configuration/options#adapter) | [About JSON Web Tokens](https://next-auth.js.org/faq#json-web-tokens)
+   */
+  strategy: SessionStrategy
   /**
    * Relative time from now in seconds when to expire the session
    * @default 2592000 // 30 days
@@ -463,13 +477,3 @@ export interface DefaultUser {
  * [`profile` OAuth provider callback](https://next-auth.js.org/configuration/providers#using-a-custom-provider)
  */
 export interface User extends Record<string, unknown>, DefaultUser {}
-
-declare global {
-  // eslint-disable-next-line @typescript-eslint/no-namespace
-  namespace NodeJS {
-    interface ProcessEnv {
-      NEXTAUTH_URL?: string
-      VERCEL_URL?: string
-    }
-  }
-}

src/next/index.ts

@@ -121,3 +121,13 @@ export async function getServerSession(
   if (body && Object.keys(body).length) return body as Session
   return null
 }
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace NodeJS {
+    interface ProcessEnv {
+      NEXTAUTH_URL?: string
+      VERCEL_URL?: string
+    }
+  }
+}