@trivajs/cors

CORS middleware for Triva framework. Handles Cross-Origin Resource Sharing with full configuration support.

Installation

npm install @trivajs/cors triva

Quick Start

import { build, get, use, listen } from 'triva';
import { cors } from '@trivajs/cors';

await build();

// Enable CORS for all routes
use(cors());

get('/api/data', (req, res) => {
  res.json({ message: 'CORS enabled!' });
});

listen(3000);

Features

✅ Simple & Flexible - Works seamlessly with Triva middleware system
✅ Zero Dependencies - Lightweight, no external dependencies
✅ Full Configuration - Complete control over CORS headers
✅ Pre-configured Modes - Development, strict, multi-origin, dynamic
✅ Preflight Handling - Automatic OPTIONS request handling
✅ Origin Validation - String, Array, RegExp, or Function validation

Usage

Basic Configuration

import { cors } from '@trivajs/cors';

// Allow all origins (default)
use(cors());

// Specific origin
use(cors({
  origin: 'https://example.com'
}));

// Multiple origins
use(cors({
  origin: ['https://example.com', 'https://app.example.com']
}));

// RegExp pattern
use(cors({
  origin: /\.example\.com$/
}));

// Dynamic validation
use(cors({
  origin: (requestOrigin) => {
    return requestOrigin.endsWith('.trusted-domain.com');
  }
}));

Advanced Configuration

use(cors({
  // Origin validation
  origin: 'https://example.com',
  
  // Allow credentials (cookies, authorization headers)
  credentials: true,
  
  // Allowed HTTP methods
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  
  // Allowed request headers
  allowedHeaders: ['Content-Type', 'Authorization'],
  
  // Headers exposed to the client
  exposedHeaders: ['X-Total-Count', 'X-RateLimit-Remaining'],
  
  // Preflight cache duration (seconds)
  maxAge: 86400,
  
  // Pass preflight to next handler
  preflightContinue: false,
  
  // Preflight response status code
  optionsSuccessStatus: 204
}));

Pre-configured Modes

Development Mode (Allow All)

import { corsDevMode } from '@trivajs/cors';

use(corsDevMode());
// Allows all origins, methods, headers

Strict Mode (Single Origin)

import { corsStrict } from '@trivajs/cors';

use(corsStrict('https://app.example.com'));
// Credentials enabled, limited methods

Multi-Origin Mode

import { corsMultiOrigin } from '@trivajs/cors';

use(corsMultiOrigin([
  'https://app.example.com',
  'https://admin.example.com'
]));

Dynamic Mode

import { corsDynamic } from '@trivajs/cors';

use(corsDynamic((origin) => {
  // Custom validation logic
  const allowedDomains = ['example.com', 'trusted.com'];
  return allowedDomains.some(domain => origin.endsWith(domain));
}));

Configuration Options

Option	Type	Default	Description
origin	string | array | RegExp | Function	'*'	Allowed origin(s)
methods	string[]	['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']	Allowed methods
allowedHeaders	string[]	[]	Allowed request headers (empty = reflect request)
exposedHeaders	string[]	[]	Headers exposed to client
credentials	boolean	false	Allow credentials
maxAge	number | null	null	Preflight cache duration (seconds)
preflightContinue	boolean	false	Pass preflight to next handler
optionsSuccessStatus	number	204	Preflight response status

Examples

API with Authentication

import { build, get, post, use, listen } from 'triva';
import { cors } from '@trivajs/cors';

await build();

// CORS with credentials for authentication
use(cors({
  origin: 'https://app.example.com',
  credentials: true,
  allowedHeaders: ['Content-Type', 'Authorization']
}));

get('/api/user', (req, res) => {
  // Cookies and auth headers allowed
  res.json({ user: 'authenticated' });
});

listen(3000);

Multiple Environments

import { cors, corsDevMode, corsStrict } from '@trivajs/cors';

const isDev = process.env.NODE_ENV === 'development';

if (isDev) {
  use(corsDevMode()); // Allow all in development
} else {
  use(corsStrict('https://production.example.com')); // Strict in production
}

Route-Specific CORS

import { get, use } from 'triva';
import { cors, corsDevMode } from '@trivajs/cors';

// Public API - allow all
get('/api/public/data', use(corsDevMode()), (req, res) => {
  res.json({ public: true });
});

// Private API - strict CORS
get('/api/private/data', use(cors({
  origin: 'https://app.example.com',
  credentials: true
})), (req, res) => {
  res.json({ private: true });
});

Dynamic Origin with Database

import { corsDynamic } from '@trivajs/cors';

// Check origin against database
use(corsDynamic(async (origin) => {
  const allowedOrigins = await db.getAllowedOrigins();
  return allowedOrigins.includes(origin);
}));

Subdomain Wildcard

use(cors({
  origin: /^https:\/\/.*\.example\.com$/
}));
// Allows: https://app.example.com, https://admin.example.com
// Blocks: https://malicious.com

How It Works

1. Origin Check - Validates request origin against configuration
2. Set Headers - Adds appropriate CORS headers to response
3. Preflight - Handles OPTIONS requests for preflight
4. Next - Calls next middleware or route handler

Security Best Practices

❌ Don't use origin: '*' with credentials: true
✅ Do specify exact origins in production

❌ Don't expose sensitive headers unnecessarily
✅ Do limit exposedHeaders to what's needed

❌ Don't allow all methods by default
✅ Do specify only required methods

Troubleshooting

CORS Error: Origin Not Allowed

Check that your origin is exactly configured:

// Wrong (missing protocol)
origin: 'example.com'

// Correct
origin: 'https://example.com'

Credentials Not Working

Ensure both are set:

use(cors({
  origin: 'https://example.com', // NOT '*'
  credentials: true
}));

And in client:

fetch('https://api.example.com', {
  credentials: 'include'
});

Preflight Failing

Add your headers to allowedHeaders:

use(cors({
  allowedHeaders: ['Content-Type', 'X-Custom-Header']
}));

Testing

# Run tests
npm test

# Run example
npm run example

License

MIT License - see LICENSE file

Contributing

Issues and PRs welcome! See main Triva repository for contribution guidelines.

Related

• Triva Framework - Main framework
• CORS Specification