feat(next)!: allows auth strategies to return headers that need to be… (#6964)

## Description

Some authentication strategies may need to set headers for responses,
such as updating cookies via a refresh token, and similar. This PR
extends Payload's auth strategy capabilities with a manner of
accomplishing this.

This is a breaking change if you have custom authentication strategies
in Payload's 3.0 beta. But it's a simple one to update.

Instead of your custom auth strategy returning the `user`, now you must
return an object with a `user` property.

This is because you can now also optionally return `responseHeaders`,
which will be returned by Payload API responses if you define them in
your auth strategies. This can be helpful for cases where you need to
set cookies and similar, directly within your auth strategies.

Before: 

```ts
return user
```

After:

```ts
return { user }
```

Author: jmikrut

docs/authentication/custom-strategies.mdx

@@ -33,10 +33,12 @@ The `authenticate` function is passed the following arguments:
 
 ### Example Strategy
 
-At its core a strategy simply takes information from the incoming request and returns a user. This is exactly how Payloads built-in strategies function.
+At its core a strategy simply takes information from the incoming request and returns a user. This is exactly how Payload's built-in strategies function.
+
+Your `authenticate` method should return an object containing a Payload user document and any optional headers that you'd like Payload to set for you when we return a response.
 
 ```ts
-import { CollectionConfig } from 'payload/types'
+import { CollectionConfig } from 'payload'
 
 export const Users: CollectionConfig = {
   slug: 'users',
@@ -59,7 +61,18 @@ export const Users: CollectionConfig = {
             },
           })
 
-          return usersQuery.docs[0] || null
+          return {
+            // Send the user back to authenticate,
+            // or send null if no user should be authenticated
+            user: usersQuery.docs[0] || null,
+
+            // Optionally, you can return headers
+            // that you'd like Payload to set here when
+            // it returns the response
+            responseHeaders: new Headers({
+              'some-header': 'my header value'
+            })
+          }
         }
       }
     ]

packages/next/src/routes/graphql/handler.ts

@@ -9,6 +9,7 @@ import { addDataAndFileToRequest } from '../../utilities/addDataAndFileToRequest
 import { addLocalesToRequestFromData } from '../../utilities/addLocalesToRequest.js'
 import { createPayloadRequest } from '../../utilities/createPayloadRequest.js'
 import { headersWithCors } from '../../utilities/headersWithCors.js'
+import { mergeHeaders } from '../../utilities/mergeHeaders.js'
 
 const handleError = async (
   payload: Payload,
@@ -122,7 +123,7 @@ export const POST =
         return response
       },
       schema,
-      validationRules: (request, args, defaultRules) => defaultRules.concat(validationRules(args)),
+      validationRules: (_, args, defaultRules) => defaultRules.concat(validationRules(args)),
     })(originalRequest)
 
     const resHeaders = headersWithCors({
@@ -134,6 +135,10 @@ export const POST =
       resHeaders.append(key, headers[key])
     }
 
+    if (basePayloadRequest.responseHeaders) {
+      mergeHeaders(basePayloadRequest.responseHeaders, resHeaders)
+    }
+
     return new Response(apiResponse.body, {
       headers: resHeaders,
       status: apiResponse.status,

packages/next/src/routes/rest/index.ts

@@ -21,6 +21,7 @@ import { addDataAndFileToRequest } from '../../utilities/addDataAndFileToRequest
 import { addLocalesToRequestFromData } from '../../utilities/addLocalesToRequest.js'
 import { createPayloadRequest } from '../../utilities/createPayloadRequest.js'
 import { headersWithCors } from '../../utilities/headersWithCors.js'
+import { mergeHeaders } from '../../utilities/mergeHeaders.js'
 import { access } from './auth/access.js'
 import { forgotPassword } from './auth/forgotPassword.js'
 import { init } from './auth/init.js'
@@ -122,15 +123,15 @@ const endpoints = {
   },
 }
 
-const handleCustomEndpoints = ({
+const handleCustomEndpoints = async ({
   endpoints,
   entitySlug,
   payloadRequest,
 }: {
   endpoints: Endpoint[] | GlobalConfig['endpoints']
   entitySlug?: string
   payloadRequest: PayloadRequest
-}): Promise<Response> | Response => {
+}): Promise<Response> => {
   if (endpoints && endpoints.length > 0) {
     let handlerParams = {}
     const { pathname } = payloadRequest
@@ -170,7 +171,15 @@ const handleCustomEndpoints = ({
         ...payloadRequest.routeParams,
         ...handlerParams,
       }
-      return customEndpoint.handler(payloadRequest)
+      const res = await customEndpoint.handler(payloadRequest)
+
+      if (res instanceof Response) {
+        if (payloadRequest.responseHeaders) {
+          mergeHeaders(payloadRequest.responseHeaders, res.headers)
+        }
+
+        return res
+      }
     }
   }
 
@@ -376,13 +385,20 @@ export const GET =
         res = await endpoints.root.GET[slug1]({ req: payloadRequest })
       }
 
-      if (res instanceof Response) return res
+      if (res instanceof Response) {
+        if (req.responseHeaders) {
+          mergeHeaders(req.responseHeaders, res.headers)
+        }
+
+        return res
+      }
 
       // root routes
       const customEndpointResponse = await handleCustomEndpoints({
         endpoints: req.payload.config.endpoints,
         payloadRequest: req,
       })
+
       if (customEndpointResponse) return customEndpointResponse
 
       return RouteNotFoundResponse({
@@ -545,13 +561,20 @@ export const POST =
         res = await endpoints.root.POST[slug1]({ req: payloadRequest })
       }
 
-      if (res instanceof Response) return res
+      if (res instanceof Response) {
+        if (req.responseHeaders) {
+          mergeHeaders(req.responseHeaders, res.headers)
+        }
+
+        return res
+      }
 
       // root routes
       const customEndpointResponse = await handleCustomEndpoints({
         endpoints: req.payload.config.endpoints,
         payloadRequest: req,
       })
+
       if (customEndpointResponse) return customEndpointResponse
 
       return RouteNotFoundResponse({
@@ -626,13 +649,20 @@ export const DELETE =
         }
       }
 
-      if (res instanceof Response) return res
+      if (res instanceof Response) {
+        if (req.responseHeaders) {
+          mergeHeaders(req.responseHeaders, res.headers)
+        }
+
+        return res
+      }
 
       // root routes
       const customEndpointResponse = await handleCustomEndpoints({
         endpoints: req.payload.config.endpoints,
         payloadRequest: req,
       })
+
       if (customEndpointResponse) return customEndpointResponse
 
       return RouteNotFoundResponse({
@@ -708,13 +738,20 @@ export const PATCH =
         }
       }
 
-      if (res instanceof Response) return res
+      if (res instanceof Response) {
+        if (req.responseHeaders) {
+          mergeHeaders(req.responseHeaders, res.headers)
+        }
+
+        return res
+      }
 
       // root routes
       const customEndpointResponse = await handleCustomEndpoints({
         endpoints: req.payload.config.endpoints,
         payloadRequest: req,
       })
+
       if (customEndpointResponse) return customEndpointResponse
 
       return RouteNotFoundResponse({

packages/next/src/utilities/createPayloadRequest.ts

@@ -97,11 +97,15 @@ export const createPayloadRequest = async ({
 
   req.payloadDataLoader = getDataLoader(req)
 
-  req.user = await executeAuthStrategies({
+  const { responseHeaders, user } = await executeAuthStrategies({
     headers: req.headers,
     isGraphQL,
     payload,
   })
 
+  req.user = user
+
+  if (responseHeaders) req.responseHeaders = responseHeaders
+
   return req
 }

packages/next/src/utilities/mergeHeaders.ts

@@ -0,0 +1,33 @@
+const headersToJoin = ['set-cookie', 'warning', 'www-authenticate', 'proxy-authenticate', 'vary']
+
+export function mergeHeaders(sourceHeaders: Headers, destinationHeaders: Headers): void {
+  // Create a map to store combined headers
+  const combinedHeaders = new Headers()
+
+  // Add existing destination headers to the combined map
+  destinationHeaders.forEach((value, key) => {
+    combinedHeaders.set(key, value)
+  })
+
+  // Add source headers to the combined map, joining specific headers
+  sourceHeaders.forEach((value, key) => {
+    const lowerKey = key.toLowerCase()
+    if (headersToJoin.includes(lowerKey)) {
+      if (combinedHeaders.has(key)) {
+        combinedHeaders.set(key, `${combinedHeaders.get(key)}, ${value}`)
+      } else {
+        combinedHeaders.set(key, value)
+      }
+    } else {
+      combinedHeaders.set(key, value)
+    }
+  })
+
+  // Clear the destination headers and set the combined headers
+  destinationHeaders.forEach((_, key) => {
+    destinationHeaders.delete(key)
+  })
+  combinedHeaders.forEach((value, key) => {
+    destinationHeaders.append(key, value)
+  })
+}

packages/payload/src/auth/executeAuthStrategies.ts

@@ -1,14 +1,16 @@
-import type { TypedUser } from '../index.js'
-import type { AuthStrategyFunctionArgs } from './index.js'
+import type { AuthStrategyFunctionArgs, AuthStrategyResult } from './index.js'
 
 export const executeAuthStrategies = async (
   args: AuthStrategyFunctionArgs,
-): Promise<TypedUser | null> => {
-  return args.payload.authStrategies.reduce(async (accumulatorPromise, strategy) => {
-    const authUser = await accumulatorPromise
-    if (!authUser) {
-      return strategy.authenticate(args)
-    }
-    return authUser
-  }, Promise.resolve(null))
+): Promise<AuthStrategyResult> => {
+  return args.payload.authStrategies.reduce(
+    async (accumulatorPromise, strategy) => {
+      const result: AuthStrategyResult = await accumulatorPromise
+      if (!result.user) {
+        return strategy.authenticate(args)
+      }
+      return result
+    },
+    Promise.resolve({ user: null }),
+  )
 }

packages/payload/src/auth/operations/auth.ts

@@ -15,6 +15,7 @@ export type AuthArgs = {
 
 export type AuthResult = {
   permissions: Permissions
+  responseHeaders?: Headers
   user: TypedUser | null
 }
 
@@ -26,12 +27,13 @@ export const auth = async (args: Required<AuthArgs>): Promise<AuthResult> => {
   try {
     const shouldCommit = await initTransaction(req)
 
-    const user = await executeAuthStrategies({
+    const { responseHeaders, user } = await executeAuthStrategies({
       headers,
       payload,
     })
 
     req.user = user
+    req.responseHeaders = responseHeaders
 
     const permissions = await getAccessResults({
       req,
@@ -41,6 +43,7 @@ export const auth = async (args: Required<AuthArgs>): Promise<AuthResult> => {
 
     return {
       permissions,
+      responseHeaders,
       user,
     }
   } catch (error: unknown) {

packages/payload/src/auth/strategies/apiKey.ts

@@ -48,12 +48,14 @@ export const APIKeyAuthentication =
           user.collection = collectionConfig.slug
           user._strategy = 'api-key'
 
-          return user as User
+          return {
+            user: user as User,
+          }
         }
       } catch (err) {
-        return null
+        return { user: null }
       }
     }
 
-    return null
+    return { user: null }
   }

packages/payload/src/auth/strategies/jwt.ts

@@ -29,11 +29,13 @@ export const JWTAuthentication: AuthStrategyFunction = async ({
     if (user && (!collection.config.auth.verify || user._verified)) {
       user.collection = collection.config.slug
       user._strategy = 'local-jwt'
-      return user as User
+      return {
+        user: user as User,
+      }
     } else {
-      return null
+      return { user: null }
     }
   } catch (error) {
-    return null
+    return { user: null }
   }
 }

packages/payload/src/auth/types.ts

@@ -101,9 +101,15 @@ export type AuthStrategyFunctionArgs = {
   isGraphQL?: boolean
   payload: Payload
 }
+
+export type AuthStrategyResult = {
+  responseHeaders?: Headers
+  user: User | null
+}
+
 export type AuthStrategyFunction = (
   args: AuthStrategyFunctionArgs,
-) => Promise<User | null> | User | null
+) => AuthStrategyResult | Promise<AuthStrategyResult>
 export type AuthStrategy = {
   authenticate: AuthStrategyFunction
   name: string