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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "3.3.0",
+  "version": "3.4.0-rc.0",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -45,7 +45,7 @@
     "@module-federation/runtime": "^2.9.0",
     "@sanity/client": "^8.6.2",
     "@sanity/message-protocol": "^0.24.0",
-    "@sanity/sdk": "3.3.0",
+    "@sanity/sdk": "3.4.0-rc.0",
     "@sanity/types": "^6.14.1",
     "react-compiler-runtime": "^1.0.0",
     "react-error-boundary": "^6.1.5",

package/src/_exports/sdk-react.ts

@@ -29,8 +29,11 @@ export {useAuthState} from '../hooks/auth/useAuthState'
 export {useAuthToken} from '../hooks/auth/useAuthToken'
 export {useCurrentUser} from '../hooks/auth/useCurrentUser'
 export {useHandleAuthCallback} from '../hooks/auth/useHandleAuthCallback'
+export {useHandleOAuthCallback} from '../hooks/auth/useHandleOAuthCallback'
 export {useLoginUrl} from '../hooks/auth/useLoginUrl'
 export {useLogOut} from '../hooks/auth/useLogOut'
+export {useOAuthAuthorize} from '../hooks/auth/useOAuthAuthorize'
+export {useOAuthTokens, type UseOAuthTokensResult} from '../hooks/auth/useOAuthTokens'
 export {useVerifyOrgProjects} from '../hooks/auth/useVerifyOrgProjects'
 export {useClient} from '../hooks/client/useClient'
 export {

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

@@ -9,6 +9,7 @@ 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'
 
@@ -17,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 () => {}),
@@ -34,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
       }
@@ -176,6 +180,81 @@ describe('AuthBoundary', () => {
     }
   })
 
+  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,13 +1,14 @@
 import {CorsOriginError} from '@sanity/client'
 import {AuthStateType, getCorsErrorProjectId, isImportError} from '@sanity/sdk'
 import {isDashboardEnvironment, isStudioConfig} from '@sanity/sdk/_internal'
-import {useEffect, useMemo} from 'react'
+import {useEffect, useMemo, useState} from 'react'
 import {ErrorBoundary, type FallbackProps} from 'react-error-boundary'
 
 import {ComlinkTokenRefreshProvider} from '../../context/ComlinkTokenRefresh'
 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'
@@ -183,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/hooks/auth/useHandleOAuthCallback.test.tsx

@@ -0,0 +1,16 @@
+import {handleOAuthCallback} from '@sanity/sdk'
+import {identity} from 'rxjs'
+import {describe, it} from 'vitest'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+vi.mock('../helpers/createCallbackHook', () => ({createCallbackHook: vi.fn(identity)}))
+vi.mock('@sanity/sdk', () => ({handleOAuthCallback: vi.fn()}))
+
+describe('useHandleOAuthCallback', () => {
+  it('calls `createCallbackHook` with `handleOAuthCallback`', async () => {
+    const {useHandleOAuthCallback} = await import('./useHandleOAuthCallback')
+    expect(createCallbackHook).toHaveBeenCalledWith(handleOAuthCallback)
+    expect(useHandleOAuthCallback).toBe(handleOAuthCallback)
+  })
+})

package/src/hooks/auth/useHandleOAuthCallback.tsx

@@ -0,0 +1,49 @@
+import {handleOAuthCallback} from '@sanity/sdk'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+/**
+ * A React hook that returns a function for handling the OAuth redirect callback.
+ *
+ * @remarks
+ * This is the OAuth counterpart to `useHandleAuthCallback`. The returned
+ * function invokes core's `handleOAuthCallback`, which validates the `state`
+ * parameter, surfaces `?error=` redirects, exchanges the authorization `code`
+ * for tokens, persists them, and transitions the auth state to `LOGGED_IN` —
+ * all in core. On success it resolves the same-origin location the user was on
+ * when the flow started (so deep links survive login), otherwise the callback
+ * URL cleaned of the OAuth params (`code`, `state`, `error`,
+ * `error_description`). It resolves `false` when there was nothing to handle.
+ * The resolved URL may be a different route, so navigate to it rather than
+ * only calling `history.replaceState`.
+ *
+ * `AuthBoundary` runs this for you when the app lands on the OAuth redirect
+ * URI. Reach for this hook only when building a custom callback component.
+ *
+ * Concurrent calls are single-flight in core, so React StrictMode's double
+ * invocation will not trigger a second code exchange, and a repeated call with
+ * a stale callback URL is ignored once a session is established.
+ *
+ * @example
+ * ```tsx
+ * function OAuthCallback() {
+ *   const handleCallback = useHandleOAuthCallback()
+ *   const navigate = useNavigate() // your router's navigation
+ *
+ *   useEffect(() => {
+ *     handleCallback(window.location.href)
+ *       .then((nextUrl) => {
+ *         // Returns the user to where they started, with OAuth params removed
+ *         if (nextUrl) navigate(nextUrl, {replace: true})
+ *       })
+ *       .catch(console.error)
+ *   }, [handleCallback, navigate])
+ *
+ *   return <div>Completing sign-in…</div>
+ * }
+ * ```
+ *
+ * @returns A callback handler that processes the OAuth redirect
+ * @public
+ */
+export const useHandleOAuthCallback = createCallbackHook(handleOAuthCallback)

package/src/hooks/auth/useOAuthAuthorize.test.tsx

@@ -0,0 +1,16 @@
+import {startOAuthAuthorization} from '@sanity/sdk'
+import {identity} from 'rxjs'
+import {describe, it} from 'vitest'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+vi.mock('../helpers/createCallbackHook', () => ({createCallbackHook: vi.fn(identity)}))
+vi.mock('@sanity/sdk', () => ({startOAuthAuthorization: vi.fn()}))
+
+describe('useOAuthAuthorize', () => {
+  it('calls `createCallbackHook` with `startOAuthAuthorization`', async () => {
+    const {useOAuthAuthorize} = await import('./useOAuthAuthorize')
+    expect(createCallbackHook).toHaveBeenCalledWith(startOAuthAuthorization)
+    expect(useOAuthAuthorize).toBe(startOAuthAuthorization)
+  })
+})

package/src/hooks/auth/useOAuthAuthorize.tsx

@@ -0,0 +1,28 @@
+import {startOAuthAuthorization} from '@sanity/sdk'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+/**
+ * A React hook that returns a function for starting the OAuth authorization-code + PKCE flow.
+ *
+ * @remarks
+ * The returned function invokes core's `startOAuthAuthorization`, which generates
+ * the PKCE `code_verifier`, `code_challenge` and `state`, persists the verifier and
+ * state to `sessionStorage`, and navigates the browser to the authorize endpoint.
+ * `clientId`, `redirectUri` and `organizationId` are read from the instance's
+ * `auth.oauth` config. The returned promise rejects if the instance has no `auth.oauth` config.
+ *
+ * Pair with {@link useHandleOAuthCallback} on the redirect URI to complete the flow.
+ *
+ * @example
+ * ```tsx
+ * function LoginButton() {
+ *   const authorize = useOAuthAuthorize()
+ *   return <button onClick={() => authorize().catch(console.error)}>Sign in</button>
+ * }
+ * ```
+ *
+ * @returns A function that starts the OAuth flow by navigating to the authorization URL
+ * @public
+ */
+export const useOAuthAuthorize = createCallbackHook(startOAuthAuthorization)

package/src/hooks/auth/useOAuthTokens.test.tsx

@@ -0,0 +1,240 @@
+import {
+  getOAuthTokensState,
+  type OAuthTokens,
+  refreshOAuthTokens,
+  revokeOAuthTokens,
+  type StateSource,
+} from '@sanity/sdk'
+import {act, renderHook} from '@testing-library/react'
+import {throwError} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {useOAuthTokens} from './useOAuthTokens'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {
+    ...original,
+    getOAuthTokensState: vi.fn(),
+    refreshOAuthTokens: vi.fn(),
+    revokeOAuthTokens: vi.fn(),
+  }
+})
+
+/**
+ * A controllable stand-in for core's token state source. `set` mimics core
+ * updating the store (refresh/revoke or a cross-tab `storage` event) and
+ * notifies subscribers so the hook re-renders.
+ */
+function createFakeTokenSource(initial: OAuthTokens | null) {
+  let current = initial
+  const listeners = new Set<() => void>()
+  const source: StateSource<OAuthTokens | null> & {set: (next: OAuthTokens | null) => void} = {
+    subscribe: (onStoreChanged?: () => void) => {
+      if (onStoreChanged) listeners.add(onStoreChanged)
+      return () => {
+        if (onStoreChanged) listeners.delete(onStoreChanged)
+      }
+    },
+    getCurrent: () => current,
+    observable: throwError(() => new Error('unexpected usage of observable')),
+    set: (next) => {
+      current = next
+      for (const listener of listeners) listener()
+    },
+  }
+  return source
+}
+
+const makeTokens = (overrides: Partial<OAuthTokens> = {}): OAuthTokens => ({
+  accessToken: 'access-token',
+  tokenType: 'bearer',
+  expiresIn: 3600,
+  expiresAt: new Date(Date.now() + 3600_000),
+  refreshToken: 'refresh-token',
+  ...overrides,
+})
+
+const wrapper = ({children}: {children: React.ReactNode}) => (
+  <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+    {children}
+  </ResourceProvider>
+)
+
+describe('useOAuthTokens', () => {
+  const mockGetState = vi.mocked(getOAuthTokensState)
+  const mockRefresh = vi.mocked(refreshOAuthTokens)
+  const mockRevoke = vi.mocked(revokeOAuthTokens)
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('returns the stored tokens with isExpired=false when expiresAt is in the future', () => {
+    const tokens = makeTokens()
+    mockGetState.mockReturnValue(createFakeTokenSource(tokens))
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+
+    expect(result.current.tokens).toEqual(tokens)
+    expect(result.current.isExpired()).toBe(false)
+  })
+
+  it('derives isExpired=true when expiresAt is in the past', () => {
+    mockGetState.mockReturnValue(
+      createFakeTokenSource(makeTokens({expiresAt: new Date(Date.now() - 1000)})),
+    )
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+
+    expect(result.current.isExpired()).toBe(true)
+  })
+
+  it('treats expiresAt exactly equal to now as expired (<= boundary)', () => {
+    vi.useFakeTimers()
+    const now = new Date('2030-01-01T00:00:00.000Z')
+    vi.setSystemTime(now)
+    mockGetState.mockReturnValue(createFakeTokenSource(makeTokens({expiresAt: new Date(now)})))
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+
+    expect(result.current.isExpired()).toBe(true)
+  })
+
+  it('re-evaluates isExpired against the clock at call time, with no re-render or token change', () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2030-01-01T00:00:00.000Z'))
+    const expiresAt = new Date(Date.now() + 10_000)
+    mockGetState.mockReturnValue(createFakeTokenSource(makeTokens({expiresAt})))
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+    const {isExpired} = result.current
+    expect(isExpired()).toBe(false)
+
+    // Advance past expiry. The same function reference must now report expired,
+    // proving the read happens at call time, not render time.
+    vi.setSystemTime(new Date(expiresAt.getTime() + 1000))
+    expect(isExpired()).toBe(true)
+  })
+
+  it('returns tokens=null and isExpired=false when there are no tokens', () => {
+    mockGetState.mockReturnValue(createFakeTokenSource(null))
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+
+    expect(result.current.tokens).toBeNull()
+    expect(result.current.isExpired()).toBe(false)
+  })
+
+  it('calls core refreshOAuthTokens and re-renders with the new tokens', async () => {
+    const source = createFakeTokenSource(makeTokens())
+    mockGetState.mockReturnValue(source)
+    const refreshed = makeTokens({accessToken: 'refreshed-token'})
+    mockRefresh.mockImplementation(() => {
+      source.set(refreshed)
+      return Promise.resolve(refreshed)
+    })
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+
+    let returned: OAuthTokens | null = null
+    await act(async () => {
+      returned = await result.current.refresh()
+    })
+
+    expect(mockRefresh).toHaveBeenCalledTimes(1)
+    expect(returned).toEqual(refreshed)
+    expect(result.current.tokens).toEqual(refreshed)
+  })
+
+  it('resolves null from refresh when core has no refresh token, and tokens become null', async () => {
+    const existing = makeTokens({refreshToken: undefined})
+    const source = createFakeTokenSource(existing)
+    mockGetState.mockReturnValue(source)
+    // Core clears stored tokens and logs out on the no-refresh-token path.
+    mockRefresh.mockImplementation(() => {
+      source.set(null)
+      return Promise.resolve(null)
+    })
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+
+    let returned: OAuthTokens | null = existing
+    await act(async () => {
+      returned = await result.current.refresh()
+    })
+
+    expect(returned).toBeNull()
+    expect(result.current.tokens).toBeNull()
+  })
+
+  it('propagates a rejected refresh and leaves tokens unchanged', async () => {
+    const existing = makeTokens()
+    mockGetState.mockReturnValue(createFakeTokenSource(existing))
+    mockRefresh.mockRejectedValue(new Error('network'))
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+
+    await act(async () => {
+      await expect(result.current.refresh()).rejects.toThrow('network')
+    })
+
+    expect(result.current.tokens).toEqual(existing)
+  })
+
+  it('propagates an unrecoverable refresh rejection after core has cleared tokens', async () => {
+    const source = createFakeTokenSource(makeTokens())
+    mockGetState.mockReturnValue(source)
+    // Core clears stored tokens and logs out before rethrowing a 4xx.
+    mockRefresh.mockImplementation(() => {
+      source.set(null)
+      return Promise.reject(new Error('invalid_grant'))
+    })
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+
+    await act(async () => {
+      await expect(result.current.refresh()).rejects.toThrow('invalid_grant')
+    })
+
+    expect(result.current.tokens).toBeNull()
+  })
+
+  it('calls core revokeOAuthTokens and re-renders with tokens=null', async () => {
+    const source = createFakeTokenSource(makeTokens())
+    mockGetState.mockReturnValue(source)
+    mockRevoke.mockImplementation(() => {
+      source.set(null)
+      return Promise.resolve()
+    })
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+
+    await act(async () => {
+      await result.current.revoke()
+    })
+
+    expect(mockRevoke).toHaveBeenCalledTimes(1)
+    expect(result.current.tokens).toBeNull()
+  })
+
+  it('re-renders when tokens change externally (e.g. another tab)', () => {
+    const source = createFakeTokenSource(null)
+    mockGetState.mockReturnValue(source)
+
+    const {result} = renderHook(() => useOAuthTokens(), {wrapper})
+    expect(result.current.tokens).toBeNull()
+
+    const otherTabTokens = makeTokens({accessToken: 'other-tab-token'})
+    act(() => {
+      source.set(otherTabTokens)
+    })
+
+    expect(result.current.tokens).toEqual(otherTabTokens)
+  })
+})