feat: [REL-12062] iframe domain whitelist error UX (#627)

* feat: add UX state for when the toolbar is not able to mount/communicate with the auth iframe

* chore: update README

* fix: fix rendering bug

* test: add test coverage

Author: cspath1

e2e/tests/iframe-error.spec.ts

@@ -0,0 +1,78 @@
+import { expect } from '@playwright/test';
+import type { Page } from '@playwright/test';
+import { test } from '../setup/global';
+
+/**
+ * Block all postMessage communication from the iframe so the toolbar
+ * never receives an auth response and eventually shows the error screen.
+ */
+async function blockAllIframeMessages(page: Page) {
+  await page.addInitScript(() => {
+    const originalAddEventListener = window.addEventListener;
+    window.addEventListener = function (this: any, type: any, listener: any, options: any) {
+      if (type === 'message') {
+        const wrappedListener = function (this: any, event: any) {
+          const data = event.data;
+          if (data && data.type && typeof data.type === 'string') {
+            console.log('[Test] Blocked iframe message:', data.type);
+            return;
+          }
+          (listener as any).call(this, event);
+        };
+        return originalAddEventListener.call(this, type, wrappedListener as any, options);
+      }
+      return originalAddEventListener.call(this, type, listener, options);
+    } as any;
+  });
+}
+
+test.describe('LaunchDarkly Toolbar - Iframe Error Screen', () => {
+  test('should show error screen when iframe communication is blocked', async ({ page }: { page: Page }) => {
+    await blockAllIframeMessages(page);
+
+    await page.goto('/sdk');
+
+    await page.getByTestId('launchdarkly-toolbar').waitFor({ state: 'visible' });
+
+    await page.getByRole('img', { name: 'LaunchDarkly' }).click();
+
+    const errorScreen = page.getByTestId('iframe-error-screen');
+    await expect(errorScreen).toBeVisible({ timeout: 15000 });
+
+    await expect(page.getByText('Unable to connect to LaunchDarkly')).toBeVisible();
+    await expect(page.getByText(/domain that is not whitelisted/)).toBeVisible();
+  });
+
+  test('should display a link to the integration settings page', async ({ page }: { page: Page }) => {
+    await blockAllIframeMessages(page);
+
+    await page.goto('/sdk');
+    await page.getByTestId('launchdarkly-toolbar').waitFor({ state: 'visible' });
+    await page.getByRole('img', { name: 'LaunchDarkly' }).click();
+
+    const errorScreen = page.getByTestId('iframe-error-screen');
+    await expect(errorScreen).toBeVisible({ timeout: 15000 });
+
+    const whitelistLink = page.getByRole('link', { name: /here to whitelist your domain/i });
+    await expect(whitelistLink).toBeVisible();
+    await expect(whitelistLink).toHaveAttribute('target', '_blank');
+
+    const href = await whitelistLink.getAttribute('href');
+    expect(href).toContain('/settings/integrations/launchdarkly-developer-toolbar/new');
+  });
+
+  test('should not show normal toolbar content when in error state', async ({ page }: { page: Page }) => {
+    await blockAllIframeMessages(page);
+
+    await page.goto('/sdk');
+    await page.getByTestId('launchdarkly-toolbar').waitFor({ state: 'visible' });
+    await page.getByRole('img', { name: 'LaunchDarkly' }).click();
+
+    const errorScreen = page.getByTestId('iframe-error-screen');
+    await expect(errorScreen).toBeVisible({ timeout: 15000 });
+
+    await expect(page.getByLabel('Flags', { exact: true })).not.toBeVisible();
+    await expect(page.getByLabel('Analytics', { exact: true })).not.toBeVisible();
+    await expect(page.getByLabel('Settings', { exact: true })).not.toBeVisible();
+  });
+});

packages/demo/vite.config.ts

@@ -43,6 +43,7 @@ export default defineConfig(({ command }) => {
     },
     server: isDev
       ? {
+          allowedHosts: true,
           fs: {
             allow: [rootDir],
           },

packages/toolbar/README.md

@@ -259,6 +259,15 @@ declare global {
 }
 ```
 
+## Usage in a Hosted Environment
+
+By default, the LaunchDarkly Developer Toolbar is configured to only allow hosting on apps running on localhost. However, if you want to run the toolbar in a hosted environment,
+you can whitelist additional domains to circumvent this limitation. To do so, navigate to the Integrations page of your LaunchDarkly organization settings [here](https://app.launchdarkly.com/settings/integrations).
+Search for the LaunchDarkly Developer Toolbar integration, and click `Add` to configure. When configuring, enter any of the domains you would like to whitelist,
+and click `Save` to save the integration settings. This list can be updated at any time to add additional domains or remove whitelisted domains.
+
+Note: After configuring, it may take up to 5 minutes for changes to reflect in the Developer Toolbar, as it caches the list of valid domains.
+
 ## Framework Support
 
 The toolbar provides first-class support for popular frameworks:

packages/toolbar/src/core/tests/AuthProviderIframeError.test.tsx

@@ -0,0 +1,165 @@
+import React from 'react';
+import { render, screen, act, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+
+const mockIframeLoaded = { value: false };
+
+vi.mock('../ui/Toolbar/context/api/IFrameProvider', () => ({
+  IFrameProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  useIFrameContext: () => ({
+    ref: { current: null },
+    iframeSrc: 'https://integrations.launchdarkly.com',
+    iframeLoaded: mockIframeLoaded.value,
+    onIFrameLoad: vi.fn(),
+  }),
+  IFRAME_COMMANDS: {
+    LOGOUT: 'logout',
+    GET_PROJECTS: 'get-projects',
+    GET_FLAGS: 'get-flags',
+    GET_FLAG: 'get-flag',
+  },
+  IFRAME_EVENTS: {
+    AUTHENTICATED: 'toolbar-authenticated',
+    AUTH_REQUIRED: 'toolbar-authentication-required',
+    AUTH_ERROR: 'toolbar-authentication-error',
+    API_READY: 'api-ready',
+  },
+  getResponseTopic: (command: string) => `${command}-response`,
+  getErrorTopic: (command: string) => `${command}-error`,
+}));
+
+vi.mock('../ui/Toolbar/context/telemetry/AnalyticsProvider', () => ({
+  useAnalytics: () => ({
+    trackLoginSuccess: vi.fn(),
+    trackAuthError: vi.fn(),
+  }),
+}));
+
+vi.mock('../ui/Toolbar/context/telemetry/InternalClientProvider', () => ({
+  useInternalClient: () => ({
+    client: null,
+    loading: false,
+    error: null,
+    updateContext: vi.fn(),
+  }),
+}));
+
+import { AuthProvider, useAuthContext } from '../ui/Toolbar/context/api/AuthProvider';
+
+function AuthStateDisplay() {
+  const { loading, iframeError, authenticated } = useAuthContext();
+  return (
+    <div>
+      <span data-testid="loading">{String(loading)}</span>
+      <span data-testid="iframe-error">{String(iframeError)}</span>
+      <span data-testid="authenticated">{String(authenticated)}</span>
+    </div>
+  );
+}
+
+describe('AuthProvider - Iframe Error Detection', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    mockIframeLoaded.value = false;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should not set iframeError before iframe loads', () => {
+    mockIframeLoaded.value = false;
+
+    render(
+      <AuthProvider>
+        <AuthStateDisplay />
+      </AuthProvider>,
+    );
+
+    expect(screen.getByTestId('iframe-error')).toHaveTextContent('false');
+    expect(screen.getByTestId('loading')).toHaveTextContent('true');
+  });
+
+  it('should set iframeError after iframe loads and no message arrives within timeout', async () => {
+    mockIframeLoaded.value = true;
+
+    render(
+      <AuthProvider>
+        <AuthStateDisplay />
+      </AuthProvider>,
+    );
+
+    expect(screen.getByTestId('iframe-error')).toHaveTextContent('false');
+
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+
+    expect(screen.getByTestId('iframe-error')).toHaveTextContent('true');
+    expect(screen.getByTestId('loading')).toHaveTextContent('false');
+  });
+
+  it('should not set iframeError if a message arrives before the timeout', async () => {
+    mockIframeLoaded.value = true;
+
+    render(
+      <AuthProvider>
+        <AuthStateDisplay />
+      </AuthProvider>,
+    );
+
+    act(() => {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          origin: 'https://integrations.launchdarkly.com',
+          data: { type: 'toolbar-authentication-required' },
+        }),
+      );
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+
+    expect(screen.getByTestId('iframe-error')).toHaveTextContent('false');
+    expect(screen.getByTestId('loading')).toHaveTextContent('false');
+  });
+
+  it('should not set iframeError before the full timeout elapses', () => {
+    mockIframeLoaded.value = true;
+
+    render(
+      <AuthProvider>
+        <AuthStateDisplay />
+      </AuthProvider>,
+    );
+
+    act(() => {
+      vi.advanceTimersByTime(4999);
+    });
+
+    expect(screen.getByTestId('iframe-error')).toHaveTextContent('false');
+    expect(screen.getByTestId('loading')).toHaveTextContent('true');
+  });
+
+  it('should set loading to false when iframeError is triggered', () => {
+    mockIframeLoaded.value = true;
+
+    render(
+      <AuthProvider>
+        <AuthStateDisplay />
+      </AuthProvider>,
+    );
+
+    expect(screen.getByTestId('loading')).toHaveTextContent('true');
+
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+
+    expect(screen.getByTestId('loading')).toHaveTextContent('false');
+    expect(screen.getByTestId('iframe-error')).toHaveTextContent('true');
+  });
+});

packages/toolbar/src/core/tests/IFrameErrorScreen.test.tsx

@@ -0,0 +1,90 @@
+import { render, screen } from '@testing-library/react';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import React from 'react';
+
+vi.mock('../ui/Toolbar/context/state/PluginsProvider', () => ({
+  usePlugins: vi.fn(),
+}));
+
+import { usePlugins } from '../ui/Toolbar/context/state/PluginsProvider';
+import { IFrameErrorScreen } from '../ui/Toolbar/components/IFrameErrorScreen/IFrameErrorScreen';
+
+describe('IFrameErrorScreen', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    (usePlugins as any).mockReturnValue({
+      baseUrl: 'https://app.launchdarkly.com',
+    });
+  });
+
+  describe('Content and Messaging', () => {
+    it('displays the error title', () => {
+      render(<IFrameErrorScreen />);
+
+      expect(screen.getByText('Unable to connect to LaunchDarkly')).toBeInTheDocument();
+    });
+
+    it('displays the error description with whitelisting guidance', () => {
+      render(<IFrameErrorScreen />);
+
+      expect(
+        screen.getByText(/typically caused by trying to load the toolbar from a domain that is not whitelisted/),
+      ).toBeInTheDocument();
+    });
+
+    it('renders the error screen container with correct test id', () => {
+      render(<IFrameErrorScreen />);
+
+      expect(screen.getByTestId('iframe-error-screen')).toBeInTheDocument();
+    });
+  });
+
+  describe('Whitelist Link', () => {
+    it('constructs the link using baseUrl from context', () => {
+      (usePlugins as any).mockReturnValue({
+        baseUrl: 'https://app.launchdarkly.com',
+      });
+
+      render(<IFrameErrorScreen />);
+
+      const link = screen.getByRole('link', { name: /here to whitelist your domain/i });
+      expect(link).toHaveAttribute(
+        'href',
+        'https://app.launchdarkly.com/settings/integrations/launchdarkly-developer-toolbar/new',
+      );
+    });
+
+    it('uses a custom baseUrl when configured', () => {
+      (usePlugins as any).mockReturnValue({
+        baseUrl: 'https://custom-ld-instance.example.com',
+      });
+
+      render(<IFrameErrorScreen />);
+
+      const link = screen.getByRole('link', { name: /here to whitelist your domain/i });
+      expect(link).toHaveAttribute(
+        'href',
+        'https://custom-ld-instance.example.com/settings/integrations/launchdarkly-developer-toolbar/new',
+      );
+    });
+
+    it('opens the link in a new tab with security attributes', () => {
+      render(<IFrameErrorScreen />);
+
+      const link = screen.getByRole('link', { name: /here to whitelist your domain/i });
+      expect(link).toHaveAttribute('target', '_blank');
+      expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+    });
+  });
+
+  describe('Interaction', () => {
+    it('forwards onMouseDown to the logo for drag handling', () => {
+      const mockOnMouseDown = vi.fn();
+      render(<IFrameErrorScreen onMouseDown={mockOnMouseDown} />);
+
+      const errorScreen = screen.getByTestId('iframe-error-screen');
+      expect(errorScreen).toBeInTheDocument();
+    });
+  });
+});

packages/toolbar/src/core/ui/Toolbar/LaunchDarklyToolbar.tsx

@@ -19,6 +19,7 @@ import {
 } from './context';
 import { CircleLogo } from './components';
 import { LoadingScreen } from './components/LoadingScreen';
+import { IFrameErrorScreen } from './components/IFrameErrorScreen';
 import { ExpandedToolbarContent } from './components/new/ExpandedToolbarContent';
 import { InteractiveWrapper } from './components/new/Interactive';
 import { AuthenticationModal } from './components/AuthenticationModal/AuthenticationModal';
@@ -33,7 +34,7 @@ export function LdToolbar() {
   const analytics = useAnalytics();
   const { activeTab, setActiveTab } = useActiveTabContext();
   const { isOptedInToSessionReplay } = useAnalyticsPreferences();
-  const { loading: authLoading } = useAuthContext();
+  const { loading: authLoading, iframeError } = useAuthContext();
   const { loading: internalClientLoading } = useInternalClient();
   const defaultActiveTab = getDefaultActiveTab();
   const [isAuthModalOpen, setIsAuthModalOpen] = useState(false);
@@ -169,8 +170,9 @@ export function LdToolbar() {
     >
       <AnimatePresence>{!isExpanded ? <CircleLogo onMouseDown={handleMouseDown} /> : null}</AnimatePresence>
       <AnimatePresence>
-        {isExpanded && isInitializing ? <LoadingScreen onMouseDown={handleMouseDown} /> : null}
-        {isExpanded && !isInitializing ? (
+        {isExpanded && iframeError ? <IFrameErrorScreen onMouseDown={handleMouseDown} /> : null}
+        {isExpanded && !iframeError && isInitializing ? <LoadingScreen onMouseDown={handleMouseDown} /> : null}
+        {isExpanded && !iframeError && !isInitializing ? (
           <ExpandedToolbarContent
             onClose={handleClose}
             onHeaderMouseDown={handleMouseDown}