HTTP Access Control (CORS) Handler

1.0.1 · abandoned · verified Wed Apr 22

The `access-control` package offers a minimal and straightforward implementation for managing HTTP Access Control (CORS) according to the W3C specification. It is designed as a focused utility for applications needing to handle cross-origin requests, abstracting the complexities of CORS header management. As of its last known release, the package is at version 1.0.1, published over 8 years ago, indicating it is no longer actively maintained. Its core functionality involves configuring allowed origins, HTTP methods, credentials handling, preflight request caching (`maxAge`), and exposing/allowing specific headers. A key differentiator is its direct handling of `OPTIONS` preflight requests and automatic `403 Forbidden` responses for invalid CORS attempts, as well as automatic adjustment of `Access-Control-Allow-Origin` when `*` is combined with `credentials: true` for specification compliance.

Common errors

```
TypeError: access is not a function
```
cause Attempting to call the `access-control` module directly as a middleware, instead of first configuring it with options to get the actual middleware function.

fix First call `access(options)` to get the middleware, then use the returned function: `const cors = access({ ... }); http.createServer(function (req, res) { if (cors(req, res)) return; ... });`
```
Access to fetch at '...' from origin '...' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.
```
cause The origin of the client request is not allowed by the `origins` option, or other headers/methods are not permitted, leading to the library rejecting the request or not adding the necessary CORS headers.

fix Ensure the client's `Origin` header exactly matches one of the allowed origins (e.g., `'http://example.com'`) or configure `origins` to `*` if appropriate (though with caution for security). Also, verify `methods` and `headers` options cover all operations the client intends to perform.

Warnings

breaking This package is considered abandoned, with no updates in over 8 years. It may not be compatible with modern Node.js versions, current browser CORS specifications, or recent security best practices. Relying on an unmaintained package for security-sensitive features like CORS is strongly discouraged.
Fix: Migrate to an actively maintained CORS middleware solution like `cors` from npm or implement CORS headers manually.
gotcha When `credentials` is set to `true` and `origins` is set to `*`, the `Access-Control-Allow-Origin` header will automatically be changed from `*` to the actual `Origin` header from the request. This is done to comply with the W3C CORS specification, which disallows `*` with credentials.
Fix: Be aware of this automatic adjustment. If you require `*` origin and credentials, your setup is non-compliant and this library correctly modifies behavior. Consider specific origins instead of `*` when credentials are needed.
gotcha The package is written in CommonJS and does not officially support ES Modules. While it may be usable via an `import access from 'access-control';` statement in some environments, native ESM usage or specific tooling configurations might be required, and type definitions are not provided.
Fix: If using ESM, ensure your bundler or Node.js environment is configured to handle CommonJS imports. Consider using a TypeScript-first or ESM-native CORS solution for modern projects.

Install

npm install access-control npm
yarn add access-control yarn
pnpm add access-control pnpm

Imports

default
wrong:
```
import { access } from 'access-control';
```
correct:
```
import access from 'access-control';
```
The primary export is a default function that configures the middleware. This package predates widespread ESM usage and is primarily CommonJS (`require`).
access
wrong:
```
const { access } = require('access-control');
```
correct:
```
const access = require('access-control');
```
This is the standard CommonJS import pattern for the main function provided by the library.
ConfiguredCORSHandler
wrong:
```
access({ origins: ['http://example.com'] }); // Does not return the middleware
```
correct:
```
const corsMiddleware = access({ origins: ['http://example.com'] });
```
The `access` function returns another function (the actual CORS middleware) that should be used in your request handling logic.

Quickstart

Illustrates how to configure `access-control` with specific origins and credentials, and integrate the resulting middleware into a Node.js HTTP server to handle CORS preflight requests and secure responses.

'use strict';

const access = require('access-control');
const http = require('http');

// Configure the CORS middleware
const corsHandler = access({
  maxAge: '1 hour',
  credentials: true,
  origins: 'http://example.com'
});

const server = http.createServer((req, res) => {
  // The corsHandler function processes the request and response.
  // If it returns `true`, it means it handled the request (e.g., preflight or error),
  // and no further response is needed from your application logic.
  if (corsHandler(req, res)) {
    return;
  }

  // For valid, non-preflight requests that pass CORS checks, proceed with application logic.
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from a valid CORS request!');
});

server.listen(8080, () => {
  console.log('CORS-enabled server listening on http://localhost:8080');
});

view raw JSON →