feat: adds new canSetHeaders prop to auth strategies (#12591)

Exposes a new argument to authentication strategies which allows the
author to determine if this auth strategy has the capability of setting
response headers or not.

This is useful because some auth strategies may want to set headers, but
in Next.js server components (AKA the admin panel), it's not possible to
set headers. It is, however, possible to set headers within API
responses and similar contexts.

So, an author might decide to only run operations that require setting
headers (i.e. refreshing an access token) if the auth strategy is being
executed in contexts where setting headers is possible.

Author: jmikrut

docs/authentication/custom-strategies.mdx

@@ -25,11 +25,12 @@ A strategy is made up of the following:
 
 The `authenticate` function is passed the following arguments:
 
-| Argument         | Description                                                                                       |
-| ---------------- | ------------------------------------------------------------------------------------------------- |
-| **`headers`** \* | The headers on the incoming request. Useful for retrieving identifiable information on a request. |
-| **`payload`** \* | The Payload class. Useful for authenticating the identifiable information against Payload.        |
-| **`isGraphQL`**  | Whether or not the request was made from a GraphQL endpoint. Default is `false`.                  |
+| Argument               | Description                                                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **`canSetHeaders`** \* | Whether or not the strategy is being executed from a context where response headers can be set. Default is `false`. |
+| **`headers`** \*       | The headers on the incoming request. Useful for retrieving identifiable information on a request.                   |
+| **`payload`** \*       | The Payload class. Useful for authenticating the identifiable information against Payload.                          |
+| **`isGraphQL`**        | Whether or not the strategy is being executed within the GraphQL endpoint. Default is `false`.                      |
 
 ### Example Strategy
 

docs/local-api/overview.mdx

@@ -329,7 +329,7 @@ available:
 //    responseHeaders: { ... } // returned headers from the response
 // }
 
-const result = await payload.auth({ headers })
+const result = await payload.auth({ headers, canSetHeaders: false })
 ```
 
 ### Login

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

@@ -99,6 +99,7 @@ export const POST =
   (config: Promise<SanitizedConfig> | SanitizedConfig) => async (request: Request) => {
     const originalRequest = request.clone()
     const req = await createPayloadRequest({
+      canSetHeaders: true,
       config,
       request,
     })

packages/next/src/utilities/initReq.ts

@@ -49,11 +49,13 @@ const reqCache = selectiveCache<Result>('req')
  * As access control and getting the request locale is dependent on the current URL and
  */
 export const initReq = async function ({
+  canSetHeaders,
   configPromise,
   importMap,
   key,
   overrides,
 }: {
+  canSetHeaders?: boolean
   configPromise: Promise<SanitizedConfig> | SanitizedConfig
   importMap: ImportMap
   key: string
@@ -77,6 +79,7 @@ export const initReq = async function ({
     })
 
     const { responseHeaders, user } = await executeAuthStrategies({
+      canSetHeaders,
       headers,
       payload,
     })

packages/payload/src/auth/executeAuthStrategies.ts

@@ -14,6 +14,8 @@ export const executeAuthStrategies = async (
   for (const strategy of args.payload.authStrategies) {
     // add the configured AuthStrategy `name` to the strategy function args
     args.strategyName = strategy.name
+    args.isGraphQL = Boolean(args.isGraphQL)
+    args.canSetHeaders = Boolean(args.canSetHeaders)
 
     try {
       const authResult = await strategy.authenticate(args)

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

@@ -6,6 +6,10 @@ import { executeAuthStrategies } from '../executeAuthStrategies.js'
 import { getAccessResults } from '../getAccessResults.js'
 
 export type AuthArgs = {
+  /**
+   * Specify if it's possible for auth strategies to set headers within this operation.
+   */
+  canSetHeaders?: boolean
   headers: Request['headers']
   req?: Omit<PayloadRequest, 'user'>
 }
@@ -17,12 +21,13 @@ export type AuthResult = {
 }
 
 export const auth = async (args: Required<AuthArgs>): Promise<AuthResult> => {
-  const { headers } = args
+  const { canSetHeaders, headers } = args
   const req = args.req as PayloadRequest
   const { payload } = req
 
   try {
     const { responseHeaders, user } = await executeAuthStrategies({
+      canSetHeaders,
       headers,
       payload,
     })

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

@@ -8,6 +8,7 @@ export const auth = async (payload: Payload, options: AuthArgs): Promise<AuthRes
   const { headers, req } = options
 
   return await authOperation({
+    canSetHeaders: Boolean(options.canSetHeaders),
     headers,
     req: await createLocalReq({ req }, payload),
   })

packages/payload/src/auth/types.ts

@@ -158,6 +158,10 @@ type GenerateForgotPasswordEmailSubject<TUser = any> = (args?: {
 }) => Promise<string> | string
 
 export type AuthStrategyFunctionArgs = {
+  /**
+   * Specifies whether or not response headers can be set from this strategy.
+   */
+  canSetHeaders?: boolean
   headers: Request['headers']
   isGraphQL?: boolean
   payload: Payload

packages/payload/src/utilities/createPayloadRequest.ts

@@ -13,6 +13,7 @@ import { getRequestLanguage } from './getRequestLanguage.js'
 import { parseCookies } from './parseCookies.js'
 
 type Args = {
+  canSetHeaders?: boolean
   config: Promise<SanitizedConfig> | SanitizedConfig
   params?: {
     collection: string
@@ -21,6 +22,7 @@ type Args = {
 }
 
 export const createPayloadRequest = async ({
+  canSetHeaders,
   config: configPromise,
   params,
   request,
@@ -105,6 +107,7 @@ export const createPayloadRequest = async ({
   req.payloadDataLoader = getDataLoader(req)
 
   const { responseHeaders, user } = await executeAuthStrategies({
+    canSetHeaders,
     headers: req.headers,
     isGraphQL,
     payload,

packages/payload/src/utilities/handleEndpoints.ts

@@ -104,7 +104,7 @@ export const handleEndpoints = async ({
   }
 
   try {
-    req = await createPayloadRequest({ config: incomingConfig, request })
+    req = await createPayloadRequest({ canSetHeaders: true, config: incomingConfig, request })
 
     if (req.method.toLowerCase() === 'options') {
       return Response.json(