Cross Domain Utils

Common errors

• Uncaught DOMException: Blocked a frame with origin "https://example.com" from accessing a cross-origin frame.

  cause Attempting to directly access properties or methods (e.g., `contentWindow.location.href`) of an iframe or window object that is on a different origin due to browser same-origin policy.
  fix Instead of direct access, use `cross-domain-utils` methods like `isSameDomain(win)`, `isWindowClosed(win)`, `getTop(win)` which are designed to handle cross-origin security boundaries gracefully.

• Error: Window is not on the same domain as current window

  cause Calling `getDomain(win)` or similar domain-sensitive functions when `win` refers to a window or iframe from a different origin.
  fix Before calling `getDomain(win)`, ensure that `isSameDomain(win)` returns `true`. If `isSameDomain(win)` is `false`, you cannot retrieve the domain for security reasons unless the library provides a specific, safe cross-origin method (which `getDomain` does not for direct access).

Warnings

• breaking Starting from version 3.0.0, the `cross-domain-utils` package was migrated to the `@krakenjs` npm scope. This means the package name changed from `cross-domain-utils` to `@krakenjs/cross-domain-utils`.
  Fix: Update your `package.json` dependency and all import statements from `import { ... } from 'cross-domain-utils'` to `import { ... } from '@krakenjs/cross-domain-utils'`.
• gotcha Several utility functions, such as `getDomain`, `isBlankDomain`, and `getUserAgent`, expect the target `Window` object to be on the same domain as the current window or will throw an exception. Use `isSameDomain` first for safe checks.
  Fix: Always use `isSameDomain(win)` before attempting to call domain-sensitive functions like `getDomain(win)` if the origin of `win` is uncertain. For cross-origin windows, some information is inherently inaccessible due to browser security policies.
• gotcha The `isWindowClosed` function has known reliability issues in IE/Edge for frame windows where the iframe element has been dynamically removed from the DOM. In such scenarios, the window object may not reliably indicate its closed status.
  Fix: Be aware of this limitation, especially when targeting older IE/Edge environments. Consider alternative or supplementary checks for iframe removal from the DOM for critical scenarios.
• gotcha The `win.mockDomain` and `win.navigator.mockUserAgent` properties are custom overrides designed solely for testing purposes. Relying on these in production code can lead to unexpected behavior or security vulnerabilities.
  Fix: Only use `mockDomain` or `mockUserAgent` within test environments to simulate different window origins or user agents. Never use these properties in live application code.

Install

• npm install cross-domain-utils npm
• yarn add cross-domain-utils yarn
• pnpm add cross-domain-utils pnpm

Imports

• getDomain
  wrong:

  const getDomain = require('cross-domain-utils').getDomain;

  correct:

  import { getDomain } from 'cross-domain-utils';

  Primary import for versions < 3.0.0. For v3+, use 'import { getDomain } from '@krakenjs/cross-domain-utils';'
• isSameDomain
  wrong:

  import isSameDomain from 'cross-domain-utils';

  correct:

  import { isSameDomain } from 'cross-domain-utils';

  Functions are named exports. For v3+, use '@krakenjs/cross-domain-utils'.
• getTop
  wrong:

  const { getTop } = require('cross-domain-utils');

  correct:

  import { getTop } from 'cross-domain-utils';

  CommonJS `require` works but ESM named imports are preferred for modern projects. For v3+, use '@krakenjs/cross-domain-utils'.

Quickstart

This quickstart demonstrates key utilities like `getDomain`, `isSameDomain`, `getTop`, `getParent`, and `isWindowClosed` in both same-domain and simulated cross-domain scenarios, highlighting how the library handles security boundaries.

import { getDomain, isSameDomain, getTop, getParent, isWindowClosed } from 'cross-domain-utils';

function setupIframe(url) {
  return new Promise(resolve => {
    const iframe = document.createElement('iframe');
    iframe.src = url;
    iframe.onload = () => resolve(iframe);
    document.body.appendChild(iframe);
  });
}

async function runExample() {
  const currentWindow = window;
  console.log(`Current window domain: ${getDomain(currentWindow)}`);

  // Simulate a same-domain iframe
  const sameDomainIframe = await setupIframe(window.location.href);
  const sameDomainWin = sameDomainIframe.contentWindow;
  console.log(`Same-domain iframe loaded. Domain: ${getDomain(sameDomainWin)}`);
  console.log(`Is same domain as current: ${isSameDomain(sameDomainWin)}`);
  console.log(`Iframe's parent: ${getParent(sameDomainWin) === currentWindow ? 'current window' : 'other'}`);

  // Simulate a cross-domain iframe (requires a different origin, e.g., a local server on another port)
  // For demonstration, we'll just illustrate the conceptual call, as actual cross-domain setup is complex.
  // Replace with a real cross-origin URL for actual testing.
  const crossDomainUrl = 'http://localhost:8081/other-page.html'; // Example, needs a running server
  const crossDomainIframe = await setupIframe(crossDomainUrl);
  const crossDomainWin = crossDomainIframe.contentWindow;

  // Accessing cross-domain properties directly would throw SecurityError.
  // cross-domain-utils handles this gracefully.
  console.log(`
Attempting cross-domain checks...`);
  console.log(`Is cross-domain window closed: ${isWindowClosed(crossDomainWin)}`); // Safe check
  console.log(`Is cross-domain window on same domain: ${isSameDomain(crossDomainWin)}`); // Safe check

  try {
    getDomain(crossDomainWin);
  } catch (e) {
    console.warn(`getDomain on cross-domain window threw: ${e.message}`); // Expected behavior
  }

  const topWindow = getTop(currentWindow);
  console.log(`Top-level window is current window: ${topWindow === currentWindow}`);

  // Clean up iframes
  document.body.removeChild(sameDomainIframe);
  document.body.removeChild(crossDomainIframe);
}

runExample();