Connection Allowlists

at a glance

why it exists

Content Security Policy's connect-src directive can restrict where a page connects, but it is set by the server as a policy header and cannot easily be updated per-response or composed with dynamic endpoint lists. Connection Allowlists takes a complementary approach: the server sends a structured list of permitted URL patterns in the Connection-Allowlist response header, and the browser evaluates every outgoing connection — subresource fetches, navigations, redirects, prefetch, preload, WebSocket connections, and history.back()/history.forward() navigations — against that list before the connection is made. Connections that don't match are blocked at the network level. A report-only variant (Connection-Allowlist-Report-Only) lets developers audit their connection surface before enforcing it.

Syntax

HTTP response header grammar defined in the WICG Connection Allowlists specification:

Connection-Allowlist: ( [ <item> ... ] ) [ ; report-to=<endpoint> ]
Connection-Allowlist-Report-Only: ( [ <item> ... ] ) [ ; report-to=<endpoint> ]

# Where <item> is:
# - response-origin (dynamically permits response own origin)
# - "<url-pattern>" (quoted URLPattern string for absolute URLs)

the header

Connection-Allowlist

The header value is a Structured Field list containing a single inner list. Each element is either the token response-origin (dynamically adds the response's own origin) or a quoted string matching the URLPattern syntax for absolute URLs.

Optional report-to parameter

Append ; report-to=<endpoint-name> to route violation reports to a Reporting API endpoint.

Inputs and parameters

The header accepts structured field parameters formatted as an inner list of patterns. Permitted tokens include response-origin and quoted pattern strings complying with the WHATWG URLPattern specification. The optional report-to parameter takes an endpoint identifier defined in a companion Reporting-Endpoints header.

Outputs and return values

When an outgoing request matches an allowlist entry, it proceeds normally through the network stack. When a request fails to match an active Connection-Allowlist header, the browser aborts the request immediately before dispatch; JavaScript APIs such as fetch() reject with a TypeError: Failed to fetch. In report-only mode, the connection is allowed while a violation report is queued.

Errors and exceptions

If the Connection-Allowlist header contains malformed Structured Field syntax, the user agent discards invalid list items or ignores the header according to standard Structured Field error-handling rules. Blocked network connections trigger standard fetch or resource error pathways, emitting network error events to the initiating element or script.

Execution context and exposure

The policy applies to the browsing context or worker context established by the response that provided the header. It governs connections initiated by that document or worker, including subresource fetches, navigation redirects, and WebSocket handshakes.

Lifecycle and state transitions

The allowlist takes effect upon receipt and parsing of the HTTP response headers. It persists for the lifetime of that specific document or worker execution environment and is re-evaluated independently on subsequent response navigations.

Examples

Declare permitted connection destinations in HTTP response headers:

# Basic allowlist — same origin plus a CDN:
Connection-Allowlist: (response-origin "https://cdn.example.com/*")

Multiple trusted endpoints

Connection-Allowlist: (response-origin "https://api.example.com/*" "https://*.assets.example.com")

Report-only mode (audit without blocking)

Connection-Allowlist-Report-Only: ("https://api.example.com/*" response-origin); report-to=security-endpoint

Express / Node.js middleware snippet

app.use((req, res, next) => {
  res.setHeader(
    'Connection-Allowlist',
    '(response-origin "https://api.example.com/*" "https://fonts.googleapis.com/*")'
  );
  next();
});

Origin trial token

<meta http-equiv="origin-trial" content="YOUR_TOKEN_HERE">

Obtain a token at developer.chrome.com/origintrials — search for "Connection Allowlists".

what the allowlist covers

At the start of the origin trial the following outgoing connections are checked against the allowlist:

• Subresource fetches (fetch(), <img>, <script>, <link>, etc.)
• Navigation requests and redirects
• Fetches from local-scheme navigations
• history.back() and history.forward() navigations
• Link prefetch and preload
• WebSocket connections

Browser compatibility

Security and privacy considerations

Connection Allowlists restricts outgoing network connections at the browser network layer before network packets are dispatched. By enforcing granular URLPattern match rules, it mitigates data exfiltration from cross-site scripting (XSS) and rogue third-party dependency compromise.

see also

• WICG Connection Allowlists — spec
• WICG/connection-allowlists — GitHub explainer
• Connection Allowlists origin trial — Chrome for Developers
• chromestatus — Connection Allowlists (5175745573945344)
• ChromeStatus API record (5175745573945344)
• Chromium Issue 447954811
• blink-dev Intent to Experiment
• blink-dev Intent to Ship
• Mozilla Standards Position #1322
• WebKit Standards Position #583
• WHATWG URLPattern specification
• MDN Reporting API
• chrome-platform-showcase — live demo