Realm auto-protection

airgap.js 9.0 and later automatically protects the default realms of newly created accessible embedded documents (e.g. iframes). Realm auto-protection can be configured to only protect the context realm where airgap.js is loaded by setting data-protect-realms="self" on the script tag, mirroring pre-9.0 behavior.

Our experimental realm auto-protection system for external same-origin resources can be enabled to auto-protect accessible same-origin sub-realms. This feature is disabled by default and can be enabled by specifying enabled hooks in the space-separated data-realm-protection-hooks attribute on the airgap.js script tag. Example configuration: data-realm-protection-hooks="nav worker".

⚠️ Realm protection hooks change the location of intercepted resources, which has the potential to break scripts that self-attest their original location.

The nav hook intercepts the loading of same-origin documents in embeds such as iframe, embed, object, and frame elements. This hook is useful if airgap.js is not already included in embedded documents that may contain trackers.

The worker hook intercepts the creation of same-origin web workers (such as Workers, SharedWorkers, and worklets) to automatically apply airgap.js protections inside the worker.

To apply airgap.js network protections in a web worker without this hook, use the following snippets:

self.airgap = {
  loadOptions: {
    airgap: '[location of airgap.js]',
    baseUrl: '[URL of the original worker script]',
  },
};

Classic worker

importScripts(self.airgap.loadOptions.airgap);

Module worker

await import(self.airgap.loadOptions.airgap);

Partytown works by proxying main-thread JavaScript functionality onto web worker threads. Partytown can interrupt the main thread with synchronous requests to worker threads. Our experimental worker realm protection hook may cause 'page freeze' issues if an improper airgap configuration causes requests used by Partytown workers to be blocked. If you're encountering an issue with Partytown workers, double check your configuration to make sure that their requests are allowed through.