CorsPlugin Schema

Schema definition for the CORS Plugin, which provides Cross-Origin Resource Sharing (CORS) support for web applications.

Schema Information

Property	Value
Schema URL	`https://rustybeam.net/schema/CorsPlugin`
Parent Schema	https://rustybeam.net/schema/UtilityPlugin
Description	Cross-Origin Resource Sharing (CORS) support with configurable policies

Properties

Property	Type	Cardinality	Description
allowed_origins	https://rustybeam.net/schema/Text	0..1	Comma-separated list of allowed origins. Use "" for all origins, or specific domains like "https://example.com". Defaults to "".
allowed_methods	https://rustybeam.net/schema/Text	0..1	Comma-separated list of allowed HTTP methods. Defaults to "GET,POST,PUT,DELETE,OPTIONS".
allowed_headers	https://rustybeam.net/schema/Text	0..1	Comma-separated list of allowed request headers. Defaults to "Content-Type,Authorization,X-Requested-With".
exposed_headers	https://rustybeam.net/schema/Text	0..1	Comma-separated list of headers to expose to the client. Defaults to empty (no additional headers exposed).
allow_credentials	https://rustybeam.net/schema/Boolean	0..1	Whether to allow credentials (cookies, authorization headers) in cross-origin requests. Defaults to false.
max_age	https://rustybeam.net/schema/Number	0..1	Maximum age in seconds for preflight cache. How long browsers can cache preflight responses. Defaults to 3600 (1 hour).
name	https://rustybeam.net/schema/Text	0..1	Plugin instance name for identification. Defaults to "cors" if not specified.

Usage Examples

Permissive CORS (Development)

<tr itemscope itemtype="https://rustybeam.net/schema/CorsPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_cors.so</span>
    <span itemprop="allowed_origins">*</span>
    <span itemprop="allow_credentials">false</span>
</tr>

Specific Domains Only (Production)

<tr itemscope itemtype="https://rustybeam.net/schema/CorsPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_cors.so</span>
    <span itemprop="allowed_origins">https://myapp.com,https://www.myapp.com</span>
    <span itemprop="allowed_methods">GET,POST,PUT,DELETE</span>
    <span itemprop="allow_credentials">true</span>
    <span itemprop="max_age">7200</span>
</tr>

API with Custom Headers

<tr itemscope itemtype="https://rustybeam.net/schema/CorsPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_cors.so</span>
    <span itemprop="allowed_origins">https://api-client.example.com</span>
    <span itemprop="allowed_methods">GET,POST,OPTIONS</span>
    <span itemprop="allowed_headers">Content-Type,Authorization,X-API-Key,X-Client-Version</span>
    <span itemprop="exposed_headers">X-Rate-Limit-Remaining,X-Rate-Limit-Reset</span>
    <span itemprop="name">api_cors</span>
</tr>

Restrictive CORS (Security Focus)

<tr itemscope itemtype="https://rustybeam.net/schema/CorsPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_cors.so</span>
    <span itemprop="allowed_origins">https://trusted-domain.com</span>
    <span itemprop="allowed_methods">GET,POST</span>
    <span itemprop="allowed_headers">Content-Type</span>
    <span itemprop="allow_credentials">false</span>
    <span itemprop="max_age">300</span>
</tr>

CORS Headers Generated

The CORS Plugin automatically adds the following headers based on configuration:

Header	Value Source	Description
`Access-Control-Allow-Origin`	allowed_origins	Specifies allowed origins for cross-origin requests
`Access-Control-Allow-Methods`	allowed_methods	HTTP methods allowed in cross-origin requests
`Access-Control-Allow-Headers`	allowed_headers	Headers allowed in cross-origin requests
`Access-Control-Expose-Headers`	exposed_headers	Headers exposed to client JavaScript
`Access-Control-Allow-Credentials`	allow_credentials	Whether credentials are allowed
`Access-Control-Max-Age`	max_age	Preflight cache duration in seconds

Preflight Requests
The CORS Plugin automatically handles OPTIONS preflight requests, responding with appropriate CORS headers without passing the request to subsequent plugins in the pipeline.

Schema Inheritance

This schema inherits from the UtilityPlugin schema, which provides:

logfile - Log file path
directory - Directory configuration
enabled - Plugin enable/disable state

And ultimately from the base Plugin schema, which provides:

library - Plugin library path
plugin - Base plugin reference property

Security Considerations

Security Best Practices

Avoid "*" in Production: Don't use wildcard origins with credentials enabled
Specify Exact Domains: List specific allowed origins instead of wildcards
Limit Methods: Only allow necessary HTTP methods
Restrict Headers: Minimize allowed custom headers
Credential Policies: Be cautious with allow_credentials=true

Common Security Patterns

Use Case	Origins	Credentials	Security Level
Public API	*	false	Low (Open)
Partner API	https://partner.com	false	Medium
Same-Origin Variants	https://app.com,https://www.app.com	true	High
Development	http://localhost:*	false	Development Only

Validation Rules

allowed_origins should contain valid URLs or "*" for wildcard
allowed_methods must contain valid HTTP methods
allowed_headers should contain valid HTTP header names
allow_credentials must be "true" or "false" if specified
max_age must be a positive integer (seconds)
Don't combine wildcard origins ("*") with credentials (security risk)
The name property should be unique if multiple CORS plugins are used

Plugin Pipeline Placement
The CORS Plugin should be placed early in the plugin pipeline, before authentication and authorization plugins. This ensures that preflight OPTIONS requests are handled correctly even for protected resources.

Client-Side Integration

JavaScript Fetch API

// Simple CORS request
fetch('https://api.example.com/data', {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json'
    }
});

// CORS request with credentials
fetch('https://api.example.com/user', {
    method: 'POST',
    credentials: 'include',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer token123'
    },
    body: JSON.stringify({ name: 'John' })
});

// Custom headers (may trigger preflight)
fetch('https://api.example.com/data', {
    method: 'PUT',
    headers: {
        'X-API-Key': 'key123',
        'X-Client-Version': '1.0.0'
    }
});

Common CORS Scenarios

Simple Requests: GET, POST with standard headers (no preflight)
Preflight Requests: Custom methods/headers trigger OPTIONS preflight
Credentialed Requests: Cookies/auth headers require allow_credentials=true
Custom Headers: Non-standard headers must be in allowed_headers

Common Configuration Patterns

Development Environment

allowed_origins: *
allowed_methods: GET,POST,PUT,DELETE,OPTIONS,PATCH
allow_credentials: false
max_age: 300

Production API

allowed_origins: https://myapp.com,https://admin.myapp.com
allowed_methods: GET,POST,PUT,DELETE
allowed_headers: Content-Type,Authorization
allow_credentials: true
max_age: 3600

Public CDN/Assets

allowed_origins: *
allowed_methods: GET,HEAD
allowed_headers: Content-Type
allow_credentials: false
max_age: 86400

Integration with Other Plugins

Authorization Plugin: CORS headers applied before authorization checks
Basic Auth Plugin: Preflight requests bypass authentication
Rate Limit Plugin: CORS requests may be rate limited normally
Security Headers Plugin: Works together for comprehensive security
File Handler Plugin: Enables cross-origin file access

Troubleshooting CORS Issues

Error	Cause	Solution
Access-Control-Allow-Origin missing	Origin not in allowed_origins	Add origin to allowed_origins list
Method not allowed	HTTP method not in allowed_methods	Add method to allowed_methods
Header not allowed	Custom header not in allowed_headers	Add header to allowed_headers
Credentials not allowed	allow_credentials=false with credentials	Set allow_credentials=true
Wildcard with credentials	Security restriction	Use specific origins instead of "*"