Feature request: Implement CORS middleware for REST API

[svozza]

Use case

We should have a middleware that adds CORS headers to responses. The middelware should have sane defaults than can be overridden when initilising the middleware.

Solution/User Experience

The middleware will be applied like any other:

import {cors} from from '@aws-lambda-powertools/event-handler/rest/middleware';

// use defaults
app.use(cors());

// custom configuration
app.use(cors({
  allowHeaders: ['X-My-Header'],
  allowMethods: ['GET', 'POST', 'OPTIONS'],
  credentials: true,
  exposeHeaders: ['Content-Length'],
  maxAge: 300,
  origin: 'http://mysite.com',
}));

As per the Python implementation the defaults are:

{
  origin: '*',
  allowHeaders: ['Authorization', 'Content-Type', 'X-Amz-Date', 'X-Api-Key', 'X-Amz-Security-Token'],
  allowMethods: ['DELETE', 'GET', 'HEAD', 'PATCH', 'POST', 'PUT'  ],
  exposeHeaders: [],
  credentials: false,
}

Pre-flight (OPTIONS) calls are typically handled at the API Gateway or Lambda Function URL so no Lambda integration is necessary. However, ALB expects you to handle pre-flight requests so our implementation should still check for the OPTIONS verb and short-circuit so that we can future proof. This involves returning a Web Response with the necessary headers and a HTTP status code of 204.

Alternative solutions

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[powertools-for-aws-oss-automation]

Note

For those interested in contributing, please leave a comment below so that we can assign the issue to you and make sure we don't duplicate efforts. If you have any further questions, please don't hesitate to ask below or on our Discord server.

[dcabib]

I can work on this one...

[dreamorosi]

I've assigned the issue to you, thank you!

Before we move onto a PR, I suggest we discuss a high level implementation plan in this thread so we can agree on a path forward before investing time in creating and reviewing a PR.

If you have any questions or doubts about the issue or its requirements please don't hesitate to comment here.

[dcabib]

It's time to get my hands dirty... Please guide me to the best way to implement this request.. I am new on contributing to open source, so any tips is always welcome.

What I guess it will be the plan:

1 . CORS Middleware Factory

Maybe starting with creating a corsMiddleware() factory function that returns a standard Middleware function. The interesting of this approach is that the current middleware system is already perfectly set up for this - it follows the onion model and can handle both global and route-specific middleware.

2. Configuration Options

The factory would accept a config object with the usual CORS suspects:

{
  origin: string | string[] | function | boolean,
  methods: ['GET', 'POST', ...],
  allowedHeaders: string[],
  exposedHeaders: string[],
  credentials: boolean,
  maxAge: number,
  preflightContinue: boolean
}

3. End-2-Eend approach:

• Preflight handling: For OPTIONS requests, the middleware would automatically respond with the appropriate CORS headers and return early (no need to call next())

• Actual requests: What about the ideia for regular requests, it would just add the CORS headers to the existing response and call next()

Next, work on Integration patterns:
Since the solution already have router.use() for global middleware and route-specific middleware support, users could do:

// Global CORS
router.use(corsMiddleware({ origin: '*' }));

// Route-specific CORS
router.get('/api/data', [corsMiddleware({ origin: 'https://myapp.com' })], handler);

Also thougth about the response header logic:

The middleware would tap into the RequestContext.res object to add headers like Access-Control-Allow-Origin, Access-Control-Allow-Methods, etc.

The nice thing is we don't need to change any of the core Router logic - the existing middleware composition in composeMiddleware() will handle everything perfectly. We're just adding a new middleware that knows how to speak CORS.

What do you think about this approach? I'm particularly curious about whether you'd want any Router-level convenience methods (like router.cors()) or if keeping it purely as middleware is cleaner.

[svozza]

It's time to get my hands dirty... Please guide me to the best way to implement this request.. I am new on contributing to open source, so any tips is always welcome.

What I guess it will be the plan:

1 . CORS Middleware Factory

Maybe starting with creating a corsMiddleware() factory function that returns a standard Middleware function.

I would just call it cors and put it in a folder called middleware where all our first party middleware can live.

2. Configuration Options

The factory would accept a config object with the usual CORS suspects:

{
origin: string | string[] | function | boolean,
methods: ['GET', 'POST', ...],
allowedHeaders: string[],
exposedHeaders: string[],
credentials: boolean,
maxAge: number,
preflightContinue: boolean
}

What is this preflightContinue option, I'm unfamiliar with that. On ,liooking it up it seems like it's an Express thing to allow processing to continue if getting an OPTIONS request. Let's leave it for the moment as I don't see any other framewroks that do this. We can add it later if there is customer demand.

3. End-2-End approach:


* **Preflight handling**: For OPTIONS requests, the middleware would automatically respond with the appropriate CORS headers and return early (no need to call `next()`)

* **Actual requests**: What about the ideia for regular requests, it would just add the CORS headers to the existing response and call `next()`

Next, work on Integration patterns: Since the solution already have router.use() for global middleware and route-specific middleware support, users could do:

// Global CORS
router.use(corsMiddleware({ origin: '*' }));

// Route-specific CORS
router.get('/api/data', [corsMiddleware({ origin: 'https://myapp.com' })], handler);

Yes, this is how it should work. Something like this:

export const cors: Middleware = (options) => async (params, reqCtx, next) => {
  const origin = options.origin ?? '*';
  reqCtx.res.headers.set('origin', origin);
  // more logic to get other headers
  await next();
}

I'm particularly curious about whether you'd want any Router-level convenience methods (like router.cors()) or if keeping it purely as middleware is cleaner.

Let's just stick with the pure middleware approach for now.

[leandrodamascena]

What is this preflightContinue option, I'm unfamiliar with that. On ,liooking it up it seems like it's an Express thing to allow processing to continue if getting an OPTIONS request. Let's leave it for the moment as I don't see any other framewroks that do this. We can add it later if there is customer demand.

I don't think you need to add the preflightContinue because it can confuse customers what that means, but you should not force customers to set OPTIONS + Other verbs (GET, POST, whatever) in every single route if cors is enabled. If you do that you will force customers to repeat OPTIONS in every single route to make sure will be able to deal with cors. Instead you should do what we do in Python here.

The workflow should be:

If CORS is enabled and the request method is OPTIONS, it indicates a preflight request. In this case, handle the preflight and return a 204 with appropriate headers.