cors

Validates CORS requests against allowed origins, methods, and headers. No-op when the Origin header is absent (same-origin requests). Preflight OPTIONS requests are handled at the router level by ergo-router.

Pipeline stage: Negotiation

Import

import {cors} from '@centralping/ergo';

Options

Option	Type	Default	Description
origins	string | string[] | RegExp | function	'*'	Allowed origins
allowMethods	string[]	All standard methods	Allowed HTTP methods (default: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE)
allowHeaders	string | string[] | RegExp | function	'*'	Allowed request headers
exposeHeaders	string | string[]	—	Headers exposed to the client
allowCredentials	boolean	false	Allow credentials (cookies, auth headers)
maxAge	number	—	Preflight cache duration in seconds

Return Value

The middleware returns one of three results:

• No Origin header: undefined (no-op, same-origin request)
• CORS allowed: {response: {headers: [...]}} with Access-Control-Allow-Origin and related headers
• CORS denied: {response: {statusCode: 403}}

Error Responses

Status	Condition
403 Forbidden	Origin header present but not allowed by policy

Usage

Standalone

import {compose, cors} from '@centralping/ergo';

const pipeline = compose(
  [cors({
    origins: ['https://app.example.com'],
    allowMethods: ['GET', 'POST'],
    allowHeaders: ['Authorization', 'Content-Type'],
 }), 'cors'],
);

ergo-router

const router = createRouter({
  cors: {
    origins: ['https://app.example.com'],
    allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowCredentials: true,
  },
});

Security Notes

Wildcard + Credentials

Configuring origins: '*' with allowCredentials: true allows any site to make credentialed cross-origin requests (cookies, Authorization headers). This is an OWASP-documented misconfiguration that can enable data exfiltration.

ergo emits a one-time process.emitWarning with code ERGO_CORS_WILDCARD_CREDENTIALS when this combination is detected at factory time.

Recommended fix: replace the wildcard with an explicit origin allowlist:

cors({
  origins: ['https://app.example.com', 'https://admin.example.com'],
  allowCredentials: true
})

RFC References

• Fetch Standard — CORS Protocol

Related Recipes

• Mixed-Auth CORS & CSRF — Configuring CORS and CSRF together for browser and token-based clients

API Reference

See the auto-generated cors API docs.