fix: custom OPTIONS endpoints are intercepted and cannot set custom CORS headers (#15153)

### What?

Fixes an issue where custom OPTIONS endpoint handlers were never called
because Payload intercepted all OPTIONS requests early and returned
default CORS headers.

### Why?

Users need to define custom CORS headers for specific endpoints in some
cases (like allowing different origins for different routes). The
previous behavior made this impossible since OPTIONS requests were
handled globally before checking if a custom handler existed.

### How?

Moved the default OPTIONS/CORS handling to after the endpoint matching
logic.

If a custom OPTIONS handler is found, it gets called and can set its own
CORS headers. If no custom handler exists, Payload falls back to the
default CORS response.

Also updated `headersWithCors` to only set CORS headers if they haven't
already been set by the custom handler, preventing them from being
overwritten.

Fixes #14551

Author: PatrikKozak

packages/payload/src/utilities/handleEndpoints.ts

@@ -140,19 +140,6 @@ export const handleEndpoints = async ({
       request,
     })
 
-    if (req.method?.toLowerCase() === 'options') {
-      return Response.json(
-        {},
-        {
-          headers: headersWithCors({
-            headers: new Headers(),
-            req,
-          }),
-          status: 200,
-        },
-      )
-    }
-
     const { payload } = req
     const { config } = payload
 
@@ -257,6 +244,21 @@ export const handleEndpoints = async ({
     }
 
     if (!handler) {
+      // If no custom handler found and this is an OPTIONS request,
+      // return default CORS response for preflight requests
+      if (req.method?.toLowerCase() === 'options') {
+        return Response.json(
+          {},
+          {
+            headers: headersWithCors({
+              headers: new Headers(),
+              req,
+            }),
+            status: 200,
+          },
+        )
+      }
+
       return notFoundResponse(req, pathname)
     }
 

packages/payload/src/utilities/headersWithCors.ts

@@ -20,28 +20,35 @@ export const headersWithCors = ({ headers, req }: CorsArgs): Headers => {
       'X-Payload-HTTP-Method-Override',
     ]
 
-    headers.set('Access-Control-Allow-Methods', 'PUT, PATCH, POST, GET, DELETE, OPTIONS')
+    // Only set default CORS headers if they haven't been set by custom handler
+    if (!headers.has('Access-Control-Allow-Methods')) {
+      headers.set('Access-Control-Allow-Methods', 'PUT, PATCH, POST, GET, DELETE, OPTIONS')
+    }
 
-    if (typeof cors === 'object' && 'headers' in cors) {
-      headers.set(
-        'Access-Control-Allow-Headers',
-        [...defaultAllowedHeaders, ...cors.headers].filter(Boolean).join(', '),
-      )
-    } else {
-      headers.set('Access-Control-Allow-Headers', defaultAllowedHeaders.join(', '))
+    if (!headers.has('Access-Control-Allow-Headers')) {
+      if (typeof cors === 'object' && 'headers' in cors) {
+        headers.set(
+          'Access-Control-Allow-Headers',
+          [...defaultAllowedHeaders, ...cors.headers].filter(Boolean).join(', '),
+        )
+      } else {
+        headers.set('Access-Control-Allow-Headers', defaultAllowedHeaders.join(', '))
+      }
     }
 
-    if (cors === '*' || (typeof cors === 'object' && 'origins' in cors && cors.origins === '*')) {
-      headers.set('Access-Control-Allow-Origin', '*')
-    } else if (
-      (Array.isArray(cors) && cors.indexOf(requestOrigin!) > -1) ||
-      (!Array.isArray(cors) &&
-        typeof cors === 'object' &&
-        'origins' in cors &&
-        cors.origins.indexOf(requestOrigin!) > -1)
-    ) {
-      headers.set('Access-Control-Allow-Credentials', 'true')
-      headers.set('Access-Control-Allow-Origin', requestOrigin!)
+    if (!headers.has('Access-Control-Allow-Origin')) {
+      if (cors === '*' || (typeof cors === 'object' && 'origins' in cors && cors.origins === '*')) {
+        headers.set('Access-Control-Allow-Origin', '*')
+      } else if (
+        (Array.isArray(cors) && cors.indexOf(requestOrigin!) > -1) ||
+        (!Array.isArray(cors) &&
+          typeof cors === 'object' &&
+          'origins' in cors &&
+          cors.origins.indexOf(requestOrigin!) > -1)
+      ) {
+        headers.set('Access-Control-Allow-Credentials', 'true')
+        headers.set('Access-Control-Allow-Origin', requestOrigin!)
+      }
     }
   }
 

test/endpoints/endpoints/root.ts

@@ -1,6 +1,6 @@
 import type { Config } from 'payload'
 
-import { applicationEndpoint, rootEndpoint } from '../shared.js'
+import { applicationEndpoint, customCorsEndpoint, rootEndpoint } from '../shared.js'
 
 export const endpoints: Config['endpoints'] = [
   {
@@ -38,4 +38,21 @@ export const endpoints: Config['endpoints'] = [
     method: 'post',
     path: `/${rootEndpoint}`,
   },
+  {
+    handler: () => {
+      return Response.json(
+        { message: 'Custom OPTIONS handler' },
+        {
+          headers: {
+            'Access-Control-Allow-Origin': 'https://custom-domain.com',
+            'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
+            'Access-Control-Allow-Headers': 'X-Custom-Header',
+          },
+          status: 200,
+        },
+      )
+    },
+    method: 'options',
+    path: `/${customCorsEndpoint}`,
+  },
 ]

test/endpoints/int.spec.ts

@@ -9,6 +9,7 @@ import { initPayloadInt } from '../helpers/initPayloadInt.js'
 import {
   applicationEndpoint,
   collectionSlug,
+  customCorsEndpoint,
   globalEndpoint,
   globalSlug,
   noEndpointsCollectionSlug,
@@ -113,5 +114,19 @@ describe('Endpoints', () => {
       expect(response.status).toBe(200)
       expect(params).toMatchObject(data)
     })
+
+    it('should call custom OPTIONS endpoint with custom CORS headers', async () => {
+      const response = await restClient.OPTIONS(`/${customCorsEndpoint}`)
+      const data = await response.json()
+
+      // Custom OPTIONS handler should be called and return custom response
+      expect(response.status).toBe(200)
+      expect(data.message).toBe('Custom OPTIONS handler')
+
+      // Custom CORS headers should be present
+      expect(response.headers.get('Access-Control-Allow-Origin')).toBe('https://custom-domain.com')
+      expect(response.headers.get('Access-Control-Allow-Methods')).toBe('POST, GET, OPTIONS')
+      expect(response.headers.get('Access-Control-Allow-Headers')).toBe('X-Custom-Header')
+    })
   })
 })

test/endpoints/shared.ts

@@ -11,3 +11,5 @@ export const rootEndpoint = 'root'
 export const noEndpointsCollectionSlug = 'no-endpoints'
 
 export const noEndpointsGlobalSlug = 'global-no-endpoints'
+
+export const customCorsEndpoint = 'custom-cors'

test/helpers/NextRESTClient.ts

@@ -213,6 +213,22 @@ export class NextRESTClient {
     return result
   }
 
+  async OPTIONS(
+    path: ValidPath,
+    options: Omit<RequestInit, 'body'> & RequestOptions = {},
+  ): Promise<Response> {
+    const { slug, params, url } = this.generateRequestParts(path)
+    const { query, ...rest } = options || {}
+    const queryParams = generateQueryString(query, params)
+
+    const request = new Request(`${url}${queryParams}`, {
+      ...rest,
+      headers: this.buildHeaders(options),
+      method: 'OPTIONS',
+    })
+    return this._GET(request, { params: Promise.resolve({ slug }) })
+  }
+
   async PATCH(path: ValidPath, options: FileArg & RequestInit & RequestOptions): Promise<Response> {
     const { slug, params, url } = this.generateRequestParts(path)
     const { query, ...rest } = options