CORS Plugin

The CORS (Cross-Origin Resource Sharing) plugin enables controlled access to resources from different origins. It handles preflight requests and adds appropriate CORS headers to responses, allowing web applications to make cross-origin requests securely.

Overview

Modern web browsers enforce the Same-Origin Policy, which restricts web pages from making requests to a different domain than the one serving the page. CORS provides a way to relax this restriction in a controlled manner. This plugin implements the CORS protocol by handling OPTIONS preflight requests and adding the necessary response headers.

Key Features

Flexible origin control: Allow specific origins or use wildcards
Method whitelisting: Control which HTTP methods are allowed
Header management: Specify allowed and exposed headers
Credentials support: Enable cross-origin requests with cookies
Preflight caching: Configure how long preflight results are cached
Automatic preflight handling: Responds to OPTIONS requests automatically

Configuration

The CORS plugin is configured as part of the plugin pipeline in your host configuration:

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/cors.so</span>
    <meta itemprop="allowed_origins" content="https://app.example.com,https://www.example.com">
    <meta itemprop="allowed_methods" content="GET,POST,PUT,DELETE">
    <meta itemprop="allow_credentials" content="true">
</li>

Configuration Parameters

Parameter	Type	Required	Default	Description
`allowed_origins`	String (comma-separated)	No	"*"	Allowed origins. Use "*" for all origins (not recommended for production)
`allowed_methods`	String (comma-separated)	No	"GET,POST,PUT,DELETE,OPTIONS"	Allowed HTTP methods
`allowed_headers`	String (comma-separated)	No	"Content-Type,Authorization,X-Requested-With"	Headers that clients can include in requests
`exposed_headers`	String (comma-separated)	No	""	Headers exposed to the client beyond the safe list
`allow_credentials`	Boolean	No	false	Allow requests with credentials (cookies, auth headers)
`max_age`	Integer	No	None	How long (in seconds) browsers can cache preflight responses

CORS Request Flow

Simple Requests

For simple requests (GET, HEAD, POST with certain content types), the browser sends the request directly:

Browser includes Origin header in request
Server processes request normally
CORS plugin adds appropriate headers to response
Browser allows/blocks response based on headers

Preflight Requests

For complex requests, browsers send a preflight OPTIONS request first:

Browser sends OPTIONS request with:
- Origin: The requesting origin
- Access-Control-Request-Method: The intended method
- Access-Control-Request-Headers: Custom headers (if any)
CORS plugin responds with allowed methods, headers, etc.
If allowed, browser sends the actual request
Server processes and CORS plugin adds headers to response

Plugin Pipeline Placement

Important: The CORS plugin should be placed early in the pipeline to handle preflight requests before authentication or other processing.

Typical pipeline order:

1. cors.so            → Handles CORS preflight ✓
2. basic-auth.so      → Authenticates user
3. authorization.so   → Checks permissions
4. selector-handler.so → Processes requests
5. file-handler.so    → Serves files

Examples

Allow All Origins (Development)

<!-- WARNING: Only use in development! -->
<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/cors.so</span>
    <meta itemprop="allowed_origins" content="*">
</li>

Production Configuration

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/cors.so</span>
    <meta itemprop="allowed_origins" content="https://app.example.com,https://mobile.example.com">
    <meta itemprop="allowed_methods" content="GET,POST,PUT,DELETE">
    <meta itemprop="allowed_headers" content="Content-Type,Authorization,X-API-Key">
    <meta itemprop="exposed_headers" content="X-Total-Count,X-Page-Number">
    <meta itemprop="allow_credentials" content="true">
    <meta itemprop="max_age" content="3600">
</li>

Testing CORS

# Test preflight request
curl -X OPTIONS http://localhost:3000/api/data \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type" \
  -v

# Test actual request
curl -X POST http://localhost:3000/api/data \
  -H "Origin: https://app.example.com" \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}' \
  -v

JavaScript Fetch Example

// Simple CORS request
fetch('http://api.example.com/data', {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json'
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('CORS error:', error));

// Request with credentials
fetch('http://api.example.com/user', {
    method: 'GET',
    credentials: 'include', // Send cookies
    headers: {
        'Authorization': 'Bearer token123'
    }
})
.then(response => response.json())
.then(data => console.log(data));

Security Considerations

Security Warning: Improper CORS configuration can expose your API to security risks!

Common Security Issues

Wildcard with credentials: Never use allowed_origins: "*" with allow_credentials: true
Dynamic origin reflection: Don't blindly reflect the Origin header without validation
Over-permissive headers: Only allow headers that are actually needed
Excessive caching: Don't set max_age too high for dynamic policies

Best Practices

Explicitly list allowed origins in production
Use HTTPS for all origins when possible
Minimize allowed headers and methods
Be cautious with credentials support
Regularly review and update CORS policies

Browser Behavior

Safe Headers

These headers are always exposed to JavaScript without being listed in exposed_headers:

Cache-Control
Content-Language
Content-Type
Expires
Last-Modified
Pragma

Simple Request Criteria

Requests that don't trigger preflight must meet ALL these criteria:

Method is GET, HEAD, or POST
Headers are limited to: Accept, Accept-Language, Content-Language, Content-Type
Content-Type is: application/x-www-form-urlencoded, multipart/form-data, or text/plain

Troubleshooting

Common Issues

Issue	Cause	Solution
CORS error in browser console	Origin not in allowed list	Add origin to allowed_origins configuration
Preflight failing	Method or header not allowed	Add to allowed_methods or allowed_headers
Cookies not sent	Credentials not enabled	Set allow_credentials=true and use credentials:'include' in fetch
Headers not accessible in JS	Headers not exposed	Add headers to exposed_headers list
Wildcard origin with credentials	Security restriction	Specify exact origins when using credentials

Debug Tips

Use browser developer tools Network tab to inspect CORS headers
Check both preflight and actual request/response
Use curl -v to see all headers
Enable verbose logging with ./rusty-beam -v

Integration with Other Plugins

Authentication Plugins

CORS preflight requests are typically not authenticated. Ensure CORS plugin comes before authentication plugins to handle OPTIONS requests properly.

Security Headers Plugin

The security-headers plugin may add additional security headers. CORS headers take precedence for cross-origin requests.