Window.originAgentCluster — Eigenschaft · JavaScript-Referenz

Signatur

Window.originAgentCluster

Beschreibung

Die Eigenschaft window.originAgentCluster (global auch als originAgentCluster erreichbar) zeigt an, ob das aktuelle Dokument in einem origin-gebundenen Agent-Cluster läuft. Normalerweise gruppieren Browser Dokumente nach Site (Schema + registrierbare Domain). Deshalb können z. B. https://a.example.com und https://b.example.com denselben Agent-Cluster teilen und sich über document.domain gegenseitig synchron erreichen. In einem origin-gebundenen Cluster zählt dagegen der vollständige Origin (Schema + Host + Port).

Ein Dokument meldet einen origin-gebundenen Cluster über den HTTP-Antwort-Header Origin-Agent-Cluster: ?1 an. Der Browser kann das Dokument dann in einem eigenen Prozess oder Thread ausführen. Das bringt mehr Leistungsisolation (lange Skripte einer Subdomain bremsen andere Subdomains nicht) und mehr Schutz vor Seitenkanal-Angriffen wie Spectre. Als Folge funktioniert das Setzen von document.domain nicht mehr, und WebAssembly.Memory bzw. SharedArrayBuffer lassen sich nicht mehr an Dokumente anderer Origins derselben Site senden.

Nützlich ist die Eigenschaft vor allem zur Laufzeit-Erkennung: Bevor Code sich auf document.domain oder auf Speicherteilung zwischen Subdomains verlässt, kann er prüfen, ob die Isolation greift. Außerdem hilft sie, eine Header-Konfiguration zu kontrollieren. Die Eigenschaft ist nur lesbar und hat keine Parameter.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Fenster in einem origin-gebundenen Agent-Cluster läuft, sonst false. In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Isolationsstatus abfragen

if (!('originAgentCluster' in window)) {
  console.log('originAgentCluster wird nicht unterstützt');
} else if (window.originAgentCluster) {
  console.log('Origin-gebundener Agent-Cluster aktiv');
} else {
  console.log('Site-gebundener Agent-Cluster');
}

Origin-gebundener Agent-Cluster aktiv

Vor dem Setzen von document.domain prüfen

// Legacy-Code, der zwei Subdomains per document.domain verbindet
const relaxDomain = (baseDomain) => {
  if (window.originAgentCluster) {
    console.warn('document.domain ist hier wirkungslos – postMessage verwenden.');
    return false;
  }
  document.domain = baseDomain;
  return true;
};

console.log(relaxDomain('example.com'));

document.domain ist hier wirkungslos – postMessage verwenden. false

Server-Header setzen und Ergebnis kontrollieren (Node.js + Browser)

// server.mjs – Node.js
import { createServer } from 'node:http';

createServer((req, res) => {
  res.setHeader('Origin-Agent-Cluster', '?1');
  res.setHeader('Content-Type', 'text/html; charset=utf-8');
  res.end(`<!doctype html><script>
    console.log('originAgentCluster:', window.originAgentCluster);
  </script>`);
}).listen(8080, () => console.log('http://localhost:8080'));

originAgentCluster: true

Status an ein Monitoring melden

const reportIsolation = async () => {
  const payload = {
    originAgentCluster: window.originAgentCluster ?? null,
    crossOriginIsolated: window.crossOriginIsolated ?? null,
    origin: location.origin
  };
  await fetch('/api/isolation-report', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });
  console.log(payload);
};

reportIsolation();

{ originAgentCluster: true, crossOriginIsolated: false, origin: 'https://app.example.com' }

// Wichtig · Fallstricke

Nur ein Hinweis an den Browser: Origin-Agent-Cluster: ?1 garantiert keinen eigenen Prozess. Der Wert der Eigenschaft sagt aus, ob die Cluster-Zuordnung nach Origin erfolgt. Über die tatsächliche Prozessaufteilung sagt er nichts aus.
Konsistenz pro Browsing-Context-Group: Hat der Browser einen Origin einmal site-gebunden geladen (z. B. in einem anderen Tab oder iframe derselben Gruppe), bleibt er dort site-gebunden, auch wenn eine spätere Antwort den Header sendet. Das Ergebnis kann also false sein, obwohl der Header gesetzt ist.
Standardverhalten ändert sich: Chromium plant, origin-gebundene Cluster zum Standard zu machen. Dann ist true auch ohne Header möglich, und nur Origin-Agent-Cluster: ?0 erzwingt die Site-Bindung. Code, der auf document.domain angewiesen ist, sollte auf postMessage() umgestellt werden.
Cross-Origin-Isolation: Ist crossOriginIsolated gleich true (COOP + COEP), ist das Fenster immer origin-gebunden.
Kompatibilität: Chromium-Browser unterstützen die Eigenschaft seit Version 88, Safari seit 15.2 und Firefox erst in neueren Versionen. Deshalb vorher mit 'originAgentCluster' in window prüfen. Nur in sicheren Kontexten (HTTPS) ist der Header sinnvoll wirksam.

Siehe auch

Window.crossOriginIsolated Document.domain Window.postMessage() SharedArrayBuffer Window.isSecureContext Window ViewTimeline.endOffset