Realm Auto-Protection

airgap.js 9.0 and later automatically protects the default realms of newly created accessible realm sources (e.g. iframes, JavaScript open() calls, etc.). 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.

  • nav:sync (default) - Synchronous same-origin navigation request hook. Better compatibility at the cost of ux performance.
  • nav:async - Asynchronous same-origin navigation request hook. Better ux performance at the cost of compatibility.

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. This hook requires airgap.js 9.28 or later.

airgap.js network protections can be applied in web workers without these realm auto-protection hooks.

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.