Cross-Origin Policies

Modern cross-origin security headers for controlling resource sharing, embedding, and browsing context isolation.

Capabilities

Cross-Origin Embedder Policy

Controls how resources are embedded in documents to enable cross-origin isolation and access to high-resolution timers.

/**
 * Sets Cross-Origin-Embedder-Policy header
 * @param options - COEP configuration options
 * @returns Express middleware function
 */
function crossOriginEmbedderPolicy(
  options?: CrossOriginEmbedderPolicyOptions
): MiddlewareFunction;

interface CrossOriginEmbedderPolicyOptions {
  /** Policy value (default: "require-corp") */
  policy?: "require-corp" | "credentialless" | "unsafe-none";
}

Usage Examples:

import { crossOriginEmbedderPolicy } from "helmet";

// Default: require-corp
app.use(crossOriginEmbedderPolicy());

// Allow credentialless requests
app.use(crossOriginEmbedderPolicy({ 
  policy: "credentialless" 
}));

// Disable COEP (not recommended)
app.use(crossOriginEmbedderPolicy({ 
  policy: "unsafe-none" 
}));

Policy Values:

• require-corp: Requires explicit Cross-Origin-Resource-Policy header on all embedded resources
• credentialless: Allows cross-origin resources without credentials
• unsafe-none: Disables cross-origin isolation (default browser behavior)

Cross-Origin Opener Policy

Controls how documents can open and access other browsing contexts to prevent certain types of attacks.

/**
 * Sets Cross-Origin-Opener-Policy header
 * @param options - COOP configuration options
 * @returns Express middleware function
 */
function crossOriginOpenerPolicy(
  options?: CrossOriginOpenerPolicyOptions
): MiddlewareFunction;

interface CrossOriginOpenerPolicyOptions {
  /** Policy value (default: "same-origin") */
  policy?: "same-origin" | "same-origin-allow-popups" | "unsafe-none";
}

Usage Examples:

import { crossOriginOpenerPolicy } from "helmet";

// Default: same-origin
app.use(crossOriginOpenerPolicy());

// Allow popups to same origin
app.use(crossOriginOpenerPolicy({ 
  policy: "same-origin-allow-popups" 
}));

// Disable COOP
app.use(crossOriginOpenerPolicy({ 
  policy: "unsafe-none" 
}));

Policy Values:

• same-origin: Isolates browsing context to same-origin documents only
• same-origin-allow-popups: Same as same-origin but allows popups that don't set COOP
• unsafe-none: Allows cross-origin documents to access the browsing context (default browser behavior)

Cross-Origin Resource Policy

Controls which origins can embed or load resources from your server.

/**
 * Sets Cross-Origin-Resource-Policy header
 * @param options - CORP configuration options
 * @returns Express middleware function
 */
function crossOriginResourcePolicy(
  options?: CrossOriginResourcePolicyOptions
): MiddlewareFunction;

interface CrossOriginResourcePolicyOptions {
  /** Policy value (default: "same-origin") */
  policy?: "same-origin" | "same-site" | "cross-origin";
}

Usage Examples:

import { crossOriginResourcePolicy } from "helmet";

// Default: same-origin
app.use(crossOriginResourcePolicy());

// Allow same-site requests
app.use(crossOriginResourcePolicy({ 
  policy: "same-site" 
}));

// Allow all cross-origin requests
app.use(crossOriginResourcePolicy({ 
  policy: "cross-origin" 
}));

Policy Values:

• same-origin: Only allow same-origin requests
• same-site: Allow requests from same site (including subdomains)
• cross-origin: Allow requests from any origin

Origin Agent Cluster

Enables origin isolation to improve security and performance by preventing documents from different origins from sharing the same agent cluster.

/**
 * Sets Origin-Agent-Cluster header to "?1"
 * @returns Express middleware function
 */
function originAgentCluster(): MiddlewareFunction;

Usage Example:

import { originAgentCluster } from "helmet";

// Enable origin agent clustering
app.use(originAgentCluster());

This header helps browsers optimize performance and provides additional security isolation between origins.

Cross-Origin Isolation

To enable cross-origin isolation (required for features like SharedArrayBuffer), you need to set both COOP and COEP headers:

import { crossOriginOpenerPolicy, crossOriginEmbedderPolicy } from "helmet";

app.use(crossOriginOpenerPolicy({ policy: "same-origin" }));
app.use(crossOriginEmbedderPolicy({ policy: "require-corp" }));

When cross-origin isolation is enabled:

• self.crossOriginIsolated returns true
• High-resolution timers and SharedArrayBuffer are available
• All embedded resources must have appropriate CORP headers

Compatibility Considerations

Cross-Origin Embedder Policy

• Can break third-party embeds (ads, widgets, iframes) that don't set CORP headers
• May require adding CORP headers to your own resources
• Consider using "credentialless" for better compatibility

Cross-Origin Opener Policy

• Can break sites that rely on cross-origin popup communication
• May affect third-party authentication flows
• Test thoroughly before deploying "same-origin" policy

Cross-Origin Resource Policy

• "same-origin" may break CDN resources if served from different domain
• Consider "same-site" if using subdomains for assets
• "cross-origin" provides no protection but maintains compatibility

Security Benefits

• COEP: Prevents timing attacks via cross-origin resource loading
• COOP: Prevents cross-origin documents from accessing window references
• CORP: Prevents unauthorized cross-origin resource inclusion
• Origin-Agent-Cluster: Provides additional process isolation

These headers work together to create defense-in-depth against various cross-origin attacks and enable modern web platform features that require cross-origin isolation.