feat: auth sessions (#12483)

Adds full session functionality into Payload's existing local
authentication strategy.

It's enabled by default, because this is a more secure pattern that we
should enforce. However, we have provided an opt-out pattern for those
that want to stick to stateless JWT authentication by passing
`collectionConfig.auth.useSessions: false`.

Todo:

- [x] @jessrynkar to update the Next.js server functions for refresh and
logout to support these new features
- [x] @jessrynkar resolve build errors

---------

Co-authored-by: Elliot DeNolf <denolfe@gmail.com>
Co-authored-by: Jessica Chowdhury <jessica@trbl.design>
Co-authored-by: Jarrod Flesch <30633324+JarrodMFlesch@users.noreply.github.com>
Co-authored-by: Sasha <64744993+r1tsuu@users.noreply.github.com>

docs/authentication/operations.mdx

@@ -180,19 +180,22 @@ As Payload sets HTTP-only cookies, logging out cannot be done by just removing a
 **Example REST API logout**:
 
 ```ts
-const res = await fetch('http://localhost:3000/api/[collection-slug]/logout', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
+const res = await fetch(
+  'http://localhost:3000/api/[collection-slug]/logout?allSessions=false',
+  {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
   },
-})
+)
 ```
 
 **Example GraphQL Mutation**:
 
 ```
 mutation {
-  logout[collection-singular-label]
+  logoutUser(allSessions: false)
 }
 ```
 
@@ -203,6 +206,10 @@ mutation {
   docs](../local-api/server-functions#reusable-payload-server-functions).
 </Banner>
 
+#### Logging out with sessions enabled
+
+By default, logging out will only end the session pertaining to the JWT that was used to log out with. However, you can pass `allSessions: true` to the logout operation in order to end all sessions for the user logging out.
+
 ## Refresh
 
 Allows for "refreshing" JWTs. If your user has a token that is about to expire, but the user is still active and using the app, you might want to use the `refresh` operation to receive a new token by executing this operation via the authenticated user.

docs/authentication/overview.mdx

@@ -91,6 +91,7 @@ The following options are available:
 | **`strategies`**               | Advanced - an array of custom authentication strategies to extend this collection's authentication with. [More details](./custom-strategies).                                                                               |
 | **`tokenExpiration`**          | How long (in seconds) to keep the user logged in. JWTs and HTTP-only cookies will both expire at the same time.                                                                                                             |
 | **`useAPIKey`**                | Payload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection. [More details](./api-keys).                                                                                |
+| **`useSessions`**              | True by default. Set to `false` to use stateless JWTs for authentication instead of sessions.                                                                                                                               |
 | **`verify`**                   | Set to `true` or pass an object with verification options to require users to verify by email before they are allowed to log into your app. [More details](./email#email-verification).                                     |
 
 ### Login With Username

docs/local-api/server-functions.mdx

@@ -393,7 +393,7 @@ export default function LoginForm() {
 
 ### Logout
 
-Logs out the current user by clearing the authentication cookie.
+Logs out the current user by clearing the authentication cookie and current sessions.
 
 #### Importing the `logout` function
 
@@ -401,7 +401,7 @@ Logs out the current user by clearing the authentication cookie.
 import { logout } from '@payloadcms/next/auth'
 ```
 
-Similar to the login function, you now need to pass your Payload config to this function and this cannot be done in a client component. Use a helper server function as shown below.
+Similar to the login function, you now need to pass your Payload config to this function and this cannot be done in a client component. Use a helper server function as shown below. To ensure all sessions are cleared, set `allSessions: true` in the options, if you wish to logout but keep current sessions active, you can set this to `false` or leave it `undefined`.
 
 ```ts
 'use server'
@@ -411,7 +411,7 @@ import config from '@payload-config'
 
 export async function logoutAction() {
   try {
-    return await logout({ config })
+    return await logout({ allSessions: true, config })
   } catch (error) {
     throw new Error(
       `Logout failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
@@ -434,7 +434,7 @@ export default function LogoutButton() {
 
 ### Refresh
 
-Refreshes the authentication token for the logged-in user.
+Refreshes the authentication token and current session for the logged-in user.
 
 #### Importing the `refresh` function
 
@@ -453,7 +453,6 @@ import config from '@payload-config'
 export async function refreshAction() {
   try {
     return await refresh({
-      collection: 'users', // pass your collection slug
       config,
     })
   } catch (error) {

docs/plugins/sentry.mdx

@@ -74,9 +74,7 @@ import * as Sentry from '@sentry/nextjs'
 
 const config = buildConfig({
   collections: [Pages, Media],
-  plugins: [
-    sentryPlugin({ Sentry })
-  ],
+  plugins: [sentryPlugin({ Sentry })],
 })
 
 export default config
@@ -98,9 +96,7 @@ export default buildConfig({
     pool: { connectionString: process.env.DATABASE_URL },
     pg, // Inject the patched pg driver for Sentry instrumentation
   }),
-  plugins: [
-    sentryPlugin({ Sentry })
-  ],
+  plugins: [sentryPlugin({ Sentry })],
 })
 ```