@studyportals/cors v2.8.0

CORS

Getting Started

This library can be used to add CORS validation to your API. It can also replace API gateway's implementation of CORS by adding an OPTIONS lambda. This is necessary when you API needs to function for wildcard domains like release candidates.

Installation

npm install @studyportals/cors

Setting up the CORS check in your repo

To use this package in a Lambda the CORS class needs to be constructed outside of the lambda handler. Example:

import {CORS, Scope, Environment} from '@studyportals/cors'

const cors = new CORS(Scope.Student, Environment.Production)

export async function handler(event: any) {
    const response = {body: 'someBody', headers: {}};
    const origin = event.headers['Origin']; // BEAWARE HEADERS ARE CASE SENSITIVE!!
    
    if(await cors.isValidDomain(origin)){
        response.headers['Access-Control-Allow-Origin'] = origin;
    }
    
    return response;
}

Make sure to use the correct Scope And Environment

The lambda needs to have access to these buckets. If this bucket is not in your account you need to ask Samurai Pizza Cats for access.

Setting up the Options lambda.

To add the OPTIONS lambda you need to make sure all lambda's have CORS disabled. After this you can create a lambda using the following snippet:

import {OptionsLambda, Scope, Environment} from '@studyportals/cors'

const optionsLambda = new OptionsLambda(Scope.Student, Environment.Production);
const handler = optionsLambda.getHandler();

// Lambda hook
export function handler;

This lambda handler needs to be added to the serverless.yaml file. The incoming event needs to be a http event with the path /{any+} and method OPTIONS

Express CORS

Express applications can use the ExpressMiddleware provided by this package. Example:

import { express } from 'express';
import {ExpressMiddleware, Scope, Environment} from '@studyportals/cors'
const app = express();

const corsMiddleWare = ExpressMiddleware.getMiddleWare(Scope.Student, Environment.Production);
app.use(corsMiddleWare);

S3 CORS rules

GoldenEye and other tools that need to generate S3 IAM policies can use the S3Rules provided in this package. Example:

import { CorsRule } from "aws-cdk-lib/aws-s3";
import * as cors from "@studyportals/cors";

generateRules = (scope: cors.Scope, environment: cors.Environment): CorsRule[] => {
		return cors.S3Rules.generate(scope, environment) as CorsRule[];
	};

Developing the package

Modifying allowed domain list

When modifying the allowed domain list follow the following rules

1. When a domain is added or removed for security reasons (Unauthorized access by thirdparty) the major version should be increased. All microservices need to update their version of this package ASAP.

2. When a domain is added for feature reasons (Added another micro website) the minor version should be increased. Only affected microservices should be required to update their CORS package ASAP

Compiling

In a terminal, run

tsc

The output JavaScript can be found in /bin.

Testing

Run npm test to execute the unit tests.

run npm test:coverage to run the unit tests as well as generate a coverage report.

If test fails, publishing will not continue. Consult the terminal to find out why this has happened.

We have a reference document for writing tests here.

Deploying

We publish an npm package, this is done by first committing and pushing the changes. updating the version number, followed by a npm run deploy command. This command prepares for deployment and then automatically publishes and pushes to GitHub.

House Rules

House Rules are located in the SamuraiPizzaCats repository.