@sanity/sdk-react 3.1.0 → 3.3.0-rc.0

package/src/components/auth/AuthBoundary.test.tsx

@@ -1,12 +1,15 @@
 import {AuthStateType} from '@sanity/sdk'
+import {installMessageBus} from '@sanity/sdk/_internal'
 import {render, screen, waitFor} from '@testing-library/react'
 import React from 'react'
 import {type FallbackProps} from 'react-error-boundary'
 import {beforeEach, describe, expect, it, type MockInstance, vi} from 'vitest'
 
+import {DashboardTokenRefreshProvider} from '../../context/DashboardTokenRefresh'
 import {ResourceProvider} from '../../context/ResourceProvider'
 import {useAuthState} from '../../hooks/auth/useAuthState'
 import {useLoginUrl} from '../../hooks/auth/useLoginUrl'
+import {useOAuthAuthorize} from '../../hooks/auth/useOAuthAuthorize'
 import {useVerifyOrgProjects} from '../../hooks/auth/useVerifyOrgProjects'
 import {AuthBoundary} from './AuthBoundary'
 
@@ -15,6 +18,9 @@ vi.mock('../../hooks/auth/useAuthState', () => ({
   useAuthState: vi.fn(() => 'logged-out'),
 }))
 vi.mock('../../hooks/auth/useLoginUrl')
+vi.mock('../../hooks/auth/useOAuthAuthorize', () => ({
+  useOAuthAuthorize: vi.fn(() => vi.fn().mockResolvedValue(undefined)),
+}))
 vi.mock('../../hooks/auth/useVerifyOrgProjects')
 vi.mock('../../hooks/auth/useHandleAuthCallback', () => ({
   useHandleAuthCallback: vi.fn(() => async () => {}),
@@ -32,8 +38,8 @@ vi.mock('./AuthError', async (importOriginal) => {
   return {
     ...actual,
     AuthError: class MockAuthError extends Error {
-      constructor(error: Error) {
-        super(error.message)
+      constructor(error: unknown) {
+        super(error instanceof Error ? error.message : undefined)
         this.name = 'AuthError'
         this.cause = error
       }
@@ -142,6 +148,113 @@ describe('AuthBoundary', () => {
     })
   })
 
+  it('does not redirect when a host bus is installed but the provider has not connected yet', () => {
+    // Workbench remotes start LOGGED_OUT (the host mints the token over the bus) and are not
+    // in an iframe, so the only thing standing between them and a login redirect is the
+    // dashboard check. AuthSwitch's effect runs before its parent provider's, so the check
+    // must not depend on the provider having connected first.
+    vi.mocked(useAuthState).mockReturnValue({
+      type: AuthStateType.LOGGED_OUT,
+      isDestroyingSession: false,
+    })
+    const originalLocation = window.location
+    const location = {href: 'http://remote.test/'}
+    Object.defineProperty(window, 'location', {value: location, writable: true})
+    vi.stubGlobal('__SANITY_APP_ID__', 'remote')
+    const globals = globalThis as {[key: symbol]: unknown}
+    const busKey = Symbol.for('sanity.os.bus')
+    installMessageBus({appId: 'dashboard'})
+    try {
+      render(
+        <ResourceProvider projectId="p" dataset="d" fallback={null}>
+          <DashboardTokenRefreshProvider>
+            <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
+          </DashboardTokenRefreshProvider>
+        </ResourceProvider>,
+      )
+      expect(location.href).toBe('http://remote.test/')
+    } finally {
+      delete globals[busKey]
+      vi.unstubAllGlobals()
+      Object.defineProperty(window, 'location', {value: originalLocation, writable: true})
+    }
+  })
+
+  describe('oauth mode', () => {
+    const oauth = {
+      clientId: 'client-abc',
+      redirectUri: 'https://app.example.com/callback',
+      organizationId: 'org123',
+    }
+
+    it('starts the OAuth authorization flow when authState="logged-out"', async () => {
+      const authorize = vi.fn().mockResolvedValue(undefined)
+      vi.mocked(useOAuthAuthorize).mockReturnValue(authorize)
+      vi.mocked(useAuthState).mockReturnValue({
+        type: AuthStateType.LOGGED_OUT,
+        isDestroyingSession: false,
+      })
+      render(
+        <ResourceProvider projectId="p" dataset="d" auth={{oauth}} fallback={null}>
+          <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
+        </ResourceProvider>,
+      )
+
+      await waitFor(() => expect(authorize).toHaveBeenCalledTimes(1))
+      expect(screen.queryByText('Protected Content')).not.toBeInTheDocument()
+    })
+
+    it('does not start the OAuth flow when logged out without oauth config', async () => {
+      const authorize = vi.fn().mockResolvedValue(undefined)
+      vi.mocked(useOAuthAuthorize).mockReturnValue(authorize)
+      vi.mocked(useAuthState).mockReturnValue({
+        type: AuthStateType.LOGGED_OUT,
+        isDestroyingSession: false,
+      })
+      render(
+        <ResourceProvider projectId="p" dataset="d" fallback={null}>
+          <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
+        </ResourceProvider>,
+      )
+
+      await waitFor(() => expect(screen.queryByText('Protected Content')).not.toBeInTheDocument())
+      expect(authorize).not.toHaveBeenCalled()
+    })
+
+    it('renders the error fallback when starting the OAuth flow rejects', async () => {
+      // A falsy rejection reason must still surface as an error, not a blank screen.
+      vi.mocked(useOAuthAuthorize).mockReturnValue(vi.fn().mockRejectedValue(undefined))
+      vi.mocked(useAuthState).mockReturnValue({
+        type: AuthStateType.LOGGED_OUT,
+        isDestroyingSession: false,
+      })
+      render(
+        <ResourceProvider projectId="p" dataset="d" auth={{oauth}} fallback={null}>
+          <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
+        </ResourceProvider>,
+      )
+
+      await waitFor(() => expect(screen.getByText('Authentication Error')).toBeInTheDocument())
+    })
+
+    it('renders the error fallback without restarting the flow when authState="error"', async () => {
+      const authorize = vi.fn().mockResolvedValue(undefined)
+      vi.mocked(useOAuthAuthorize).mockReturnValue(authorize)
+      vi.mocked(useAuthState).mockReturnValue({
+        type: AuthStateType.ERROR,
+        error: new Error('access_denied'),
+      })
+      render(
+        <ResourceProvider projectId="p" dataset="d" auth={{oauth}} fallback={null}>
+          <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
+        </ResourceProvider>,
+      )
+
+      await waitFor(() => expect(screen.getByText('Authentication Error')).toBeInTheDocument())
+      expect(authorize).not.toHaveBeenCalled()
+    })
+  })
+
   it('renders the empty LoginCallback component when authState="logging-in"', () => {
     vi.mocked(useAuthState).mockReturnValue({
       type: AuthStateType.LOGGING_IN,

package/src/components/auth/AuthBoundary.tsx

@@ -1,14 +1,14 @@
 import {CorsOriginError} from '@sanity/client'
 import {AuthStateType, getCorsErrorProjectId, isImportError} from '@sanity/sdk'
-import {isStudioConfig} from '@sanity/sdk/_internal'
-import {useEffect, useMemo} from 'react'
+import {isDashboardEnvironment, isStudioConfig} from '@sanity/sdk/_internal'
+import {useEffect, useMemo, useState} from 'react'
 import {ErrorBoundary, type FallbackProps} from 'react-error-boundary'
 
 import {ComlinkTokenRefreshProvider} from '../../context/ComlinkTokenRefresh'
-import {isDashboardEnvironment} from '../../context/dashboardToken'
 import {DashboardTokenRefreshProvider} from '../../context/DashboardTokenRefresh'
 import {useAuthState} from '../../hooks/auth/useAuthState'
 import {useLoginUrl} from '../../hooks/auth/useLoginUrl'
+import {useOAuthAuthorize} from '../../hooks/auth/useOAuthAuthorize'
 import {useVerifyOrgProjects} from '../../hooks/auth/useVerifyOrgProjects'
 import {useSanityInstance} from '../../hooks/context/useSanityInstance'
 import {ChunkLoadError} from '../errors/ChunkLoadError'
@@ -184,21 +184,34 @@ function AuthSwitch({
   const orgError = useVerifyOrgProjects(disableVerifyOrg, projectIds)
 
   const isLoggedOut = authState.type === AuthStateType.LOGGED_OUT && !authState.isDestroyingSession
+  const isOAuth = !!instance.config.auth?.oauth
   const loginUrl = useLoginUrl()
+  const authorize = useOAuthAuthorize()
+  const [authorizeError, setAuthorizeError] = useState<{error: unknown} | null>(null)
 
   useEffect(() => {
     if (isLoggedOut && !isInIframe() && !isStudio && !isDashboardEnvironment()) {
       // We don't want to redirect to login if we're in the Dashboard, in studio
       // mode, or in the workbench (the OS owns the session and mints the token)
-      window.location.href = loginUrl
+      if (isOAuth) {
+        // PKCE params and navigation are owned by core. LOGGED_OUT renders
+        // null, so a rejection here must be surfaced or the user sees nothing.
+        authorize().catch((error) => setAuthorizeError({error}))
+      } else {
+        window.location.href = loginUrl
+      }
     }
-  }, [isLoggedOut, loginUrl, isStudio])
+  }, [isLoggedOut, isOAuth, authorize, loginUrl, isStudio])
 
   // Only check the error if verification is enabled
   if (verifyOrganization && orgError) {
     throw new ConfigurationError({message: orgError})
   }
 
+  if (authorizeError) {
+    throw new AuthError(authorizeError.error)
+  }
+
   switch (authState.type) {
     case AuthStateType.ERROR: {
       throw new AuthError(authState.error)

package/src/components/auth/LoginCallback.test.tsx

@@ -9,7 +9,14 @@ vi.mock('../../hooks/auth/useHandleAuthCallback', () => ({
     const parsedUrl = new URL(url)
     const sid = new URLSearchParams(parsedUrl.hash.slice(1)).get('sid')
     if (sid === 'valid') {
-      return 'https://example.com/new-location'
+      // same document, hash stripped
+      return 'http://localhost/'
+    }
+    if (sid === 'deep-link') {
+      return 'http://localhost/documents/abc?x=1'
+    }
+    if (sid === 'cross-origin') {
+      return 'https://evil.example.com/'
     }
     return false
   }),
@@ -48,7 +55,25 @@ describe('LoginCallback', () => {
 
   it('handles a successful callback and calls history.replaceState', async () => {
     // Simulate a valid `sid` in the location hash
-    vi.stubGlobal('location', {href: 'http://localhost#sid=valid'})
+    const replace = vi.fn()
+    vi.stubGlobal('location', {href: 'http://localhost/#sid=valid', replace})
+    const {LoginCallback} = await import('./LoginCallback') // Reload after resetModules
+
+    render(
+      <ResourceProvider fallback={null}>
+        <LoginCallback />
+      </ResourceProvider>,
+    )
+
+    await waitFor(() => {
+      expect(history.replaceState).toHaveBeenCalledWith(null, '', 'http://localhost/')
+    })
+    expect(replace).not.toHaveBeenCalled()
+  })
+
+  it('navigates when the callback resolves to a different route', async () => {
+    const replace = vi.fn()
+    vi.stubGlobal('location', {href: 'http://localhost/#sid=deep-link', replace})
     const {LoginCallback} = await import('./LoginCallback') // Reload after resetModules
 
     render(
@@ -58,11 +83,25 @@ describe('LoginCallback', () => {
     )
 
     await waitFor(() => {
-      expect(history.replaceState).toHaveBeenCalledWith(
-        null,
-        '',
-        'https://example.com/new-location',
-      )
+      expect(replace).toHaveBeenCalledWith('http://localhost/documents/abc?x=1')
+    })
+    expect(history.replaceState).not.toHaveBeenCalled()
+  })
+
+  it('does not navigate when the callback resolves to a different origin', async () => {
+    const replace = vi.fn()
+    vi.stubGlobal('location', {href: 'http://localhost/#sid=cross-origin', replace})
+    const {LoginCallback} = await import('./LoginCallback') // Reload after resetModules
+
+    render(
+      <ResourceProvider fallback={null}>
+        <LoginCallback />
+      </ResourceProvider>,
+    )
+
+    await waitFor(() => {
+      expect(replace).not.toHaveBeenCalled()
+      expect(history.replaceState).not.toHaveBeenCalled()
     })
   })
 

package/src/components/auth/LoginCallback.tsx

@@ -5,7 +5,15 @@ import {useHandleAuthCallback} from '../../hooks/auth/useHandleAuthCallback'
 /**
  * Component shown during auth callback processing that handles login completion.
  * Automatically processes the auth callback when mounted and updates the URL
- * to remove callback parameters without triggering a page reload.
+ * to remove callback parameters without triggering a page reload. When the
+ * callback resolves to a different route (the OAuth flow returns the user to
+ * where they started), a real navigation is performed instead so the app's
+ * router picks it up.
+ *
+ * A different route is detected by pathname only, so apps that route in the
+ * hash (`#/documents/abc`) will not be navigated to the deep link. Those apps
+ * should build a custom callback component with `useHandleOAuthCallback` and
+ * their router's `navigate`.
  *
  * @alpha
  */
@@ -15,10 +23,20 @@ export function LoginCallback(): React.ReactNode {
   useEffect(() => {
     const url = new URL(location.href)
     handleAuthCallback(url.toString()).then((replacementLocation) => {
-      if (replacementLocation) {
-        // history API with `replaceState` is used to prevent a reload but still
-        // remove the short-lived token from the URL
+      if (!replacementLocation) return
+      const next = new URL(replacementLocation, url)
+      // Core only returns same-origin locations; guard here too since this is
+      // the code that navigates.
+      if (next.origin !== url.origin) return
+      if (next.pathname === url.pathname) {
+        // Same document: `replaceState` strips the callback params without a
+        // reload. Routers do not observe this, which is fine when only the
+        // query/hash changed. Caveat: a same-path return with different app
+        // query params won't re-run router search-param hooks until the next
+        // navigation.
         history.replaceState(null, '', replacementLocation)
+      } else {
+        location.replace(replacementLocation)
       }
     })
   }, [handleAuthCallback])

package/src/context/DashboardTokenRefresh.test.tsx

@@ -1,17 +1,25 @@
 import {AuthStateType, setAuthToken} from '@sanity/sdk'
+import {getDashboardMessageBus} from '@sanity/sdk/_internal'
 import {act, render} from '@testing-library/react'
 import {of} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
 
+import {getDashboardModuleContext} from '../dashboard/module'
 import {useAuthState} from '../hooks/auth/useAuthState'
-import {
-  isDashboardEnvironment,
-  observeDashboardToken,
-  refreshDashboardToken,
-} from './dashboardToken'
+import {useSanityInstance} from '../hooks/context/useSanityInstance'
 import {DashboardTokenRefreshProvider} from './DashboardTokenRefresh'
 import {ResourceProvider} from './ResourceProvider'
 
+const messageBus = vi.hoisted(() => ({
+  client: undefined as
+    | undefined
+    | {emit: ReturnType<typeof vi.fn>; subscribe: ReturnType<typeof vi.fn>},
+  emit: vi.fn(),
+  subscribe: vi.fn(),
+  // A spy so tests can observe the forwarded arguments.
+  getDashboardMessageBus: vi.fn(),
+}))
+
 vi.mock('@sanity/sdk', async () => {
   const actual = await vi.importActual('@sanity/sdk')
   return {
@@ -24,17 +32,13 @@ vi.mock('../hooks/auth/useAuthState', () => ({
   useAuthState: vi.fn(),
 }))
 
-vi.mock('./dashboardToken', () => ({
-  isDashboardEnvironment: vi.fn(() => false),
-  observeDashboardToken: vi.fn(() => undefined),
-  refreshDashboardToken: vi.fn(),
+vi.mock('@sanity/sdk/_internal', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@sanity/sdk/_internal')>()),
+  getDashboardMessageBus: messageBus.getDashboardMessageBus,
 }))
 
 const mockSetAuthToken = setAuthToken as Mock
 const mockUseAuthState = useAuthState as Mock
-const mockIsDashboardEnvironment = isDashboardEnvironment as Mock
-const mockObserveDashboardToken = observeDashboardToken as Mock
-const mockRefreshDashboardToken = refreshDashboardToken as Mock
 
 const renderProvider = () =>
   render(
@@ -47,6 +51,9 @@ const renderProvider = () =>
 
 describe('DashboardTokenRefreshProvider', () => {
   beforeEach(() => {
+    messageBus.client = undefined
+    messageBus.getDashboardMessageBus.mockReset()
+    messageBus.getDashboardMessageBus.mockImplementation(() => messageBus.client)
     mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
   })
 
@@ -55,9 +62,7 @@ describe('DashboardTokenRefreshProvider', () => {
   })
 
   describe('when not in the dashboard', () => {
-    it('does not subscribe to the OS token', () => {
-      mockIsDashboardEnvironment.mockReturnValue(false)
-
+    it('does not subscribe to a dashboard token', () => {
       act(() => {
         renderProvider()
       })
@@ -68,12 +73,13 @@ describe('DashboardTokenRefreshProvider', () => {
 
   describe('when in the dashboard', () => {
     beforeEach(() => {
-      mockIsDashboardEnvironment.mockReturnValue(true)
+      messageBus.client = messageBus
+      messageBus.subscribe.mockReturnValue(of('dashboard-token'))
+      // `emit` returns a lazily-awaited reply the provider attaches a `.catch` to.
+      messageBus.emit.mockReturnValue(Promise.resolve(undefined))
     })
 
-    it('mirrors the OS token into the auth store', () => {
-      mockObserveDashboardToken.mockReturnValue(of('dashboard-token'))
-
+    it('mirrors the dashboard token into the auth store', () => {
       act(() => {
         renderProvider()
       })
@@ -81,9 +87,80 @@ describe('DashboardTokenRefreshProvider', () => {
       expect(mockSetAuthToken).toHaveBeenCalledWith(expect.anything(), 'dashboard-token')
     })
 
-    it('asks the OS to reissue the token on a 401', () => {
-      mockObserveDashboardToken.mockReturnValue(of('dashboard-token'))
+    it('renders children bare when no host bus is installed', () => {
+      messageBus.client = undefined
+
+      act(() => {
+        renderProvider()
+      })
+
+      expect(messageBus.getDashboardMessageBus).toHaveBeenCalledTimes(1)
+      expect(mockSetAuthToken).not.toHaveBeenCalled()
+    })
+
+    it('connects with the module id before any child reads the bus during render', () => {
+      // getDashboardMessageBus is first-caller-wins per instance. A hook reading the bus in
+      // its render runs before any parent effect, so the provider must connect during render
+      // or the connection is pinned to the app id.
+      const ModuleContext = getDashboardModuleContext()
+      function ReadsBus() {
+        getDashboardMessageBus(useSanityInstance())
+        return null
+      }
+
+      act(() => {
+        render(
+          <ModuleContext.Provider value="favorites/views/list/panel">
+            <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+              <DashboardTokenRefreshProvider>
+                <ReadsBus />
+              </DashboardTokenRefreshProvider>
+            </ResourceProvider>
+          </ModuleContext.Provider>,
+        )
+      })
+
+      expect(messageBus.getDashboardMessageBus.mock.calls[0]).toEqual([
+        expect.anything(),
+        'favorites/views/list/panel',
+      ])
+    })
+
+    it('forwards the module id from the dashboard module context', () => {
+      const ModuleContext = getDashboardModuleContext()
+
+      act(() => {
+        render(
+          <ModuleContext.Provider value="favorites/views/list/panel">
+            <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+              <DashboardTokenRefreshProvider>
+                <div>Test</div>
+              </DashboardTokenRefreshProvider>
+            </ResourceProvider>
+          </ModuleContext.Provider>,
+        )
+      })
+
+      expect(messageBus.getDashboardMessageBus).toHaveBeenCalledWith(
+        expect.anything(),
+        'favorites/views/list/panel',
+      )
+    })
+
+    it('treats subscription failures as a missing token', () => {
+      messageBus.subscribe.mockImplementationOnce(() => {
+        throw new Error('Incompatible message bus')
+      })
+
+      expect(() => {
+        act(() => {
+          renderProvider()
+        })
+      }).not.toThrow()
+      expect(mockSetAuthToken).toHaveBeenCalledWith(expect.anything(), null)
+    })
 
+    it('asks the message bus to reissue the token on a 401', () => {
       const {rerender} = renderProvider()
 
       mockUseAuthState.mockReturnValue({
@@ -100,7 +177,32 @@ describe('DashboardTokenRefreshProvider', () => {
         )
       })
 
-      expect(mockRefreshDashboardToken).toHaveBeenCalledTimes(1)
+      expect(messageBus.emit).toHaveBeenCalledWith('auth.token.refresh', undefined)
+    })
+
+    it('logs a failed token reissue instead of dropping it silently', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      messageBus.emit.mockReturnValueOnce(Promise.reject(new Error('NO_RESPONDER')))
+      const {rerender} = renderProvider()
+
+      mockUseAuthState.mockReturnValue({
+        type: AuthStateType.ERROR,
+        error: {statusCode: 401, message: 'Unauthorized'},
+      })
+      await act(async () => {
+        rerender(
+          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+            <DashboardTokenRefreshProvider>
+              <div>Test</div>
+            </DashboardTokenRefreshProvider>
+          </ResourceProvider>,
+        )
+      })
+
+      expect(warn).toHaveBeenCalledWith(
+        '[sanity/sdk] Dashboard token refresh failed:',
+        expect.any(Error),
+      )
     })
   })
 })

package/src/context/DashboardTokenRefresh.tsx

@@ -1,14 +1,14 @@
 import {type ClientError} from '@sanity/client'
 import {AuthStateType, setAuthToken} from '@sanity/sdk'
-import React, {type PropsWithChildren, useEffect, useRef} from 'react'
+import {getDashboardMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBus} from '@sanity/sdk/dashboard'
+import React, {type PropsWithChildren, useContext, useEffect, useRef, useState} from 'react'
+import {defer, of} from 'rxjs'
+import {catchError} from 'rxjs/operators'
 
+import {getDashboardModuleContext} from '../dashboard/module'
 import {useAuthState} from '../hooks/auth/useAuthState'
 import {useSanityInstance} from '../hooks/context/useSanityInstance'
-import {
-  isDashboardEnvironment,
-  observeDashboardToken,
-  refreshDashboardToken,
-} from './dashboardToken'
 
 /**
  * Keeps the SDK auth token in sync with the dashboard "OS".
@@ -20,17 +20,20 @@ import {
  * (the token expired), we ask the OS to reissue rather than tearing the session
  * down; the new token arrives back through the same subscription.
  */
-function DashboardTokenRefresh({children}: PropsWithChildren) {
+function DashboardTokenRefresh({
+  children,
+  messageBus,
+}: PropsWithChildren<{messageBus: MessageBus}>) {
   const instance = useSanityInstance()
   const authState = useAuthState()
   const processed401ErrorRef = useRef<unknown | null>(null)
 
   useEffect(() => {
-    const token$ = observeDashboardToken()
-    if (!token$) return undefined
-    const subscription = token$.subscribe((token) => setAuthToken(instance, token))
+    const subscription = defer(() => messageBus.subscribe('auth.token'))
+      .pipe(catchError(() => of(null)))
+      .subscribe((token) => setAuthToken(instance, token))
     return () => subscription.unsubscribe()
-  }, [instance])
+  }, [instance, messageBus])
 
   useEffect(() => {
     const has401Error =
@@ -38,11 +41,15 @@ function DashboardTokenRefresh({children}: PropsWithChildren) {
 
     if (has401Error && processed401ErrorRef.current !== authState.error) {
       processed401ErrorRef.current = authState.error
-      refreshDashboardToken()
+      // Event topics have no replay, so a missing responder or timeout is otherwise dropped silently.
+      messageBus.emit('auth.token.refresh', undefined).catch((error) => {
+        // eslint-disable-next-line no-console
+        console.warn('[sanity/sdk] Dashboard token refresh failed:', error)
+      })
     } else if (!has401Error) {
       processed401ErrorRef.current = null
     }
-  }, [authState])
+  }, [authState, messageBus])
 
   return children
 }
@@ -87,8 +94,17 @@ function DashboardTokenRefresh({children}: PropsWithChildren) {
  * @public
  */
 export const DashboardTokenRefreshProvider: React.FC<PropsWithChildren> = ({children}) => {
-  if (isDashboardEnvironment()) {
-    return <DashboardTokenRefresh>{children}</DashboardTokenRefresh>
+  const instance = useSanityInstance()
+  const moduleId = useContext(getDashboardModuleContext())
+  // The connection is first-caller-wins per instance, and hooks below read it during their
+  // render, before any effect here could run. Connecting in the first render pins the module
+  // identity before they do; nothing has subscribed to the store yet, so the write is safe.
+  // The module id is read once: the CLI wrapper provides it statically above this tree.
+  // No retry: the host installs the bus at module evaluation, before any remote renders, and
+  // a standalone app has no host to wait for.
+  const [messageBus] = useState(() => getDashboardMessageBus(instance, moduleId))
+  if (messageBus) {
+    return <DashboardTokenRefresh messageBus={messageBus}>{children}</DashboardTokenRefresh>
   }
 
   return children