0xDocs 0x.limo

Docs / Security

Isolation headers (COOP, COEP, CORP)

Hosted sites are cross-origin isolated (COOP same-origin, COEP credentialless), which enables SharedArrayBuffer and threads; what breaks and how to fix it.

Every file of a hosted site is served with:

http
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: credentialless
Cross-Origin-Resource-Policy: cross-origin
Access-Control-Allow-Origin: *
X-Content-Type-Options: nosniff

Files the swarm service worker serves carry the same three Cross-Origin-* headers, so a file behaves the same whether it came from a peer or from the origin.

#What you get

With COOP same-origin and COEP credentialless your page is cross-origin isolated (self.crossOriginIsolated === true) when it is the top-level page. That gives you:

  • SharedArrayBuffer and Atomics.wait, so Emscripten pthreads, wasm threads and multi-threaded engines work;
  • high-resolution timers (performance.now() at full precision) and performance.measureUserAgentSpecificMemory().

CORP: cross-origin and ACAO: * let other isolated pages embed your files. The 0x store's player does this.

#Inside the 0x store

On 0x.limo/play/<id>, the store serves the page with COOP same-origin and COEP credentialless when the game's site is on a hosted origin. It frames your game with allow="... cross-origin-isolated", so your game is cross-origin isolated in the store as well. Games hosted elsewhere, and the worlds, are framed without isolation.

0x.limo/embed/<id> (X player cards, oEmbed and blogs) is framed by other sites, which are not isolated. There your game runs without cross-origin isolation, so it gets no SharedArrayBuffer. If your engine needs threads, give it a single-threaded fallback when crossOriginIsolated is false.

#What breaks, and how to fix it

COEP credentialless means that cross-origin no-cors requests (an <img>, <script> or <audio> pointing at another host, without CORS) are sent without cookies or credentials. They still load. Requests in CORS mode behave as usual. In practice:

symptomcausefix
An image or script from another host loads logged out, or failsIt needed cookies. Under credentialless no-cors requests carry none.Serve it from your own site, or use CORS (crossorigin="anonymous" and an Access-Control-Allow-Origin header on the other host).
An <iframe> of another site stays blankThe framed site must allow being embedded by a COEP page (Cross-Origin-Embedder-Policy on it, or CORP/credentialless support).Use an <iframe credentialless> where supported, or open the site in a new window. Also declare it under frame in "csp".
window.opener is null / a popup can't talk backCOOP same-origin severs links to cross-origin windows.Use postMessage through a frame you control, or redirects instead of popups. OAuth popups to other hosts need a redirect flow.
A worker script fails with a COEP errorThe worker script must carry COEP/CORP itself.Serve workers from your own site. 0x adds the headers there, and on swarm responses.
SharedArrayBuffer is not definedThe page isn't isolated (embedded on another site, or opened from a non-hosted host).Check crossOriginIsolated and fall back to one thread.

#Testing locally

0x dev serves your game on localhost, but it does not send COOP/COEP. To check threads before you publish, publish a version and open it on its -play origin, or serve your build with the same two headers.

bash
curl -sI https://<site>-play.0x.limo/sites/<site>/<n>/ | grep -i cross-origin