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>

Author: 5 people

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 =awaitfetch('http://localhost:3000/api/[collection-slug]/logout', {
- method: 'POST',
- headers: {
-'Content-Type': 'application/json',
+const res =awaitfetch(
+'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,15 +393,15 @@ 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
 
 ```ts
 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'
 
 exportasyncfunction logoutAction() {
 try {
-returnawaitlogout({ config })
+returnawaitlogout({ allSessions: true, config })
  } catch (error) {
 thrownewError(
 `Logout failed: ${errorinstanceofError?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'
 exportasyncfunction refreshAction() {
 try {
 returnawaitrefresh({
- 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 })],
 })
 
 exportdefaultconfig
@@ -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 })],
 })
 ```
 

packages/graphql/src/resolvers/auth/logout.ts

@@ -7,6 +7,7 @@ import type { Context } from '../types.js'
 exportfunctionlogout(collection: Collection): any{
 asyncfunctionresolver(_,args,context: Context){
 constoptions={
+allSessions: args.allSessions,
  collection,
 req: isolateObjectProperty(context.req,'transactionID'),
 }

packages/graphql/src/schema/initCollections.ts

@@ -487,6 +487,9 @@ export function initCollections({ config, graphqlResult }: InitCollectionsGraphQ
 
 graphqlResult.Mutation.fields[`logout${singularName}`]={
 type: GraphQLString,
+args: {
+allSessions: {type: GraphQLBoolean},
+},
 resolve: logout(collection),
 }
 

packages/next/src/auth/logout.ts

@@ -1,24 +1,46 @@
 'use server'
 
+importtype{SanitizedConfig}from'payload'
+
 import{cookiesasgetCookies,headersasnextHeaders}from'next/headers.js'
-import{getPayload}from'payload'
+import{createLocalReq,getPayload,logoutOperation}from'payload'
 
 import{getExistingAuthToken}from'../utilities/getExistingAuthToken.js'
 
-exportasyncfunctionlogout({ config }: {config: any}){
+exportasyncfunctionlogout({
+ allSessions =false,
+ config,
+}: {
+allSessions?: boolean
+config: Promise<SanitizedConfig>|SanitizedConfig
+}){
 constpayload=awaitgetPayload({ config })
 constheaders=awaitnextHeaders()
-constresult=awaitpayload.auth({ headers })
+constauthResult=awaitpayload.auth({ headers })
 
-if(!result.user){
+if(!authResult.user){
 return{message: 'User already logged out',success: true}
 }
 
-constexistingCookie=awaitgetExistingAuthToken(payload.config.cookiePrefix)
+const{ user }=authResult
+constreq=awaitcreateLocalReq({ user },payload)
+constcollection=payload.collections[user.collection]
 
+constlogoutResult=awaitlogoutOperation({
+ allSessions,
+ collection,
+ req,
+})
+
+if(!logoutResult){
+return{message: 'Logout failed',success: false}
+}
+
+constexistingCookie=awaitgetExistingAuthToken(payload.config.cookiePrefix)
 if(existingCookie){
 constcookies=awaitgetCookies()
 cookies.delete(existingCookie.name)
-return{message: 'User logged out successfully',success: true}
 }
+
+return{message: 'User logged out successfully',success: true}
 }

packages/next/src/auth/refresh.ts

@@ -3,33 +3,45 @@
 importtype{CollectionSlug}from'payload'
 
 import{headersasnextHeaders}from'next/headers.js'
-import{getPayload}from'payload'
+import{createLocalReq,getPayload,refreshOperation}from'payload'
 
 import{getExistingAuthToken}from'../utilities/getExistingAuthToken.js'
 import{setPayloadAuthCookie}from'../utilities/setPayloadAuthCookie.js'
 
-exportasyncfunctionrefresh({collection,config }: {collection: CollectionSlug;config: any}){
+exportasyncfunctionrefresh({ config }: {config: any}){
 constpayload=awaitgetPayload({ config })
-constauthConfig=payload.collections[collection]?.config.auth
+constheaders=awaitnextHeaders()
+constresult=awaitpayload.auth({ headers })
 
-if(!authConfig){
+if(!result.user){
+thrownewError('Cannot refresh token: user not authenticated')
+}
+
+constcollection: CollectionSlug|undefined=result.user.collection
+constcollectionConfig=payload.collections[collection]
+
+if(!collectionConfig?.config.auth){
 thrownewError(`No auth config found for collection: ${collection}`)
 }
 
-const{ user }=awaitpayload.auth({headers: awaitnextHeaders()})
+constreq=awaitcreateLocalReq({user: result.user},payload)
 
-if(!user){
-thrownewError('User not authenticated')
+constrefreshResult=awaitrefreshOperation({
+collection: collectionConfig,
+ req,
+})
+
+if(!refreshResult){
+return{message: 'Token refresh failed',success: false}
 }
 
 constexistingCookie=awaitgetExistingAuthToken(payload.config.cookiePrefix)
-
 if(!existingCookie){
-return{message: 'No valid token found',success: false}
+return{message: 'No valid token found to refresh',success: false}
 }
 
 awaitsetPayloadAuthCookie({
- authConfig,
+authConfig: collectionConfig.config.auth,
 cookiePrefix: payload.config.cookiePrefix,
 token: existingCookie.value,
 })

packages/payload/src/auth/baseFields/sessions.ts

@@ -0,0 +1,32 @@
+importtype{ArrayField}from'../../fields/config/types.js'
+
+exportconstsessionsFieldConfig: ArrayField={
+name: 'sessions',
+type: 'array',
+access: {
+read: ({ doc,req: { user }})=>{
+returnuser?.id===doc?.id
+},
+update: ()=>false,
+},
+admin: {
+disabled: true,
+},
+fields: [
+{
+name: 'id',
+type: 'text',
+required: true,
+},
+{
+name: 'createdAt',
+type: 'date',
+defaultValue: ()=>newDate(),
+},
+{
+name: 'expiresAt',
+type: 'date',
+required: true,
+},
+],
+}

packages/payload/src/auth/endpoints/logout.ts

@@ -9,8 +9,10 @@ import { logoutOperation } from '../operations/logout.js'
 
 exportconstlogoutHandler: PayloadHandler=async(req)=>{
 constcollection=getRequestCollection(req)
-const{ t }=req
+const{ searchParams, t }=req
+
 constresult=awaitlogoutOperation({
+allSessions: searchParams.get('allSessions')==='true',
  collection,
  req,
 })