@sanity/sdk 2.5.0 → 2.7.0

package/src/auth/dashboardAuth.ts

@@ -0,0 +1,132 @@
+import {type Subscription} from 'rxjs'
+
+import {type StoreContext} from '../store/defineStore'
+import {DEFAULT_BASE} from './authConstants'
+import {AuthStateType} from './authStateType'
+import {type AuthStoreState, type DashboardContext} from './authStore'
+import {type AuthStrategyOptions, type AuthStrategyResult} from './authStrategy'
+import {refreshStampedToken} from './refreshStampedToken'
+import {subscribeToStateAndFetchCurrentUser} from './subscribeToStateAndFetchCurrentUser'
+import {getAuthCode, getTokenFromLocation} from './utils'
+
+/**
+ * Parses the dashboard context from a location href's `_context` URL parameter.
+ * Strips the `sid` property from the parsed context (it's handled separately).
+ *
+ * @internal
+ */
+function parseDashboardContext(locationHref: string): DashboardContext {
+  try {
+    const parsedUrl = new URL(locationHref, DEFAULT_BASE)
+    const contextParam = parsedUrl.searchParams.get('_context')
+    if (contextParam) {
+      const parsedContext = JSON.parse(contextParam)
+
+      if (
+        parsedContext &&
+        typeof parsedContext === 'object' &&
+        !Array.isArray(parsedContext) &&
+        Object.keys(parsedContext).length > 0
+      ) {
+        // Explicitly remove the 'sid' property before assigning
+        delete parsedContext.sid
+        return parsedContext as DashboardContext
+      }
+    }
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error('Failed to parse dashboard context from initial location:', err)
+  }
+  return {} // Empty dashboard context if parsing fails
+}
+
+/**
+ * Resolves the initial auth state for Dashboard mode.
+ *
+ * In dashboard mode the token is provided by the parent frame via Comlink,
+ * so the SDK starts in a `LOGGED_OUT` state and waits for the token to arrive.
+ * The `_context` URL parameter provides dashboard metadata (orgId, mode, env).
+ *
+ * A provided token (`auth.token`) or an auth code/callback still takes
+ * precedence, even when running inside the dashboard.
+ *
+ * @internal
+ */
+export function getDashboardInitialState(options: AuthStrategyOptions): AuthStrategyResult {
+  const {authConfig, initialLocationHref} = options
+  const providedToken = authConfig.token
+  const callbackUrl = authConfig.callbackUrl
+  const storageKey = '__sanity_auth_token'
+
+  const dashboardContext = parseDashboardContext(initialLocationHref)
+
+  // Dashboard does NOT use localStorage — token comes from the parent frame
+  const storageArea = undefined
+
+  // Provided token always wins, even in dashboard
+  if (providedToken) {
+    return {
+      authState: {type: AuthStateType.LOGGED_IN, token: providedToken, currentUser: null},
+      storageKey,
+      storageArea,
+      authMethod: undefined,
+      dashboardContext,
+    }
+  }
+
+  // Check for auth code or token-from-location (callback handling)
+  if (getAuthCode(callbackUrl, initialLocationHref) || getTokenFromLocation(initialLocationHref)) {
+    return {
+      authState: {type: AuthStateType.LOGGING_IN, isExchangingToken: false},
+      storageKey,
+      storageArea,
+      authMethod: undefined,
+      dashboardContext,
+    }
+  }
+
+  // Default: logged out, waiting for Comlink to provide token
+  return {
+    authState: {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false},
+    storageKey,
+    storageArea,
+    authMethod: undefined,
+    dashboardContext,
+  }
+}
+
+/**
+ * Initialize Dashboard auth subscriptions:
+ * - Subscribe to state changes and fetch current user
+ * - Start stamped token refresh
+ *
+ * Note: storage events are NOT subscribed in dashboard mode since
+ * the dashboard does not use localStorage for token persistence.
+ *
+ * @internal
+ */
+export function initializeDashboardAuth(
+  context: StoreContext<AuthStoreState>,
+  tokenRefresherRunning: boolean,
+): {dispose: () => void; tokenRefresherStarted: boolean} {
+  const subscriptions: Subscription[] = []
+  let startedRefresher = false
+
+  subscriptions.push(subscribeToStateAndFetchCurrentUser(context, {useProjectHostname: false}))
+
+  // Dashboard does not subscribe to storage events
+
+  if (!tokenRefresherRunning) {
+    startedRefresher = true
+    subscriptions.push(refreshStampedToken(context))
+  }
+
+  return {
+    dispose: () => {
+      for (const subscription of subscriptions) {
+        subscription.unsubscribe()
+      }
+    },
+    tokenRefresherStarted: startedRefresher,
+  }
+}

package/src/auth/standaloneAuth.ts

@@ -0,0 +1,109 @@
+import {type Subscription} from 'rxjs'
+
+import {type StoreContext} from '../store/defineStore'
+import {AuthStateType} from './authStateType'
+import {type AuthStoreState} from './authStore'
+import {type AuthStrategyOptions, type AuthStrategyResult} from './authStrategy'
+import {refreshStampedToken} from './refreshStampedToken'
+import {subscribeToStateAndFetchCurrentUser} from './subscribeToStateAndFetchCurrentUser'
+import {subscribeToStorageEventsAndSetToken} from './subscribeToStorageEventsAndSetToken'
+import {getAuthCode, getDefaultStorage, getTokenFromLocation, getTokenFromStorage} from './utils'
+
+/**
+ * Resolves the initial auth state for Standalone mode.
+ *
+ * Token discovery order:
+ * 1. Provided token (`auth.token` in config)
+ * 2. Auth code or token from location (OAuth callback)
+ * 3. localStorage: `__sanity_auth_token`
+ * 4. Falls back to `LOGGED_OUT`
+ *
+ * @internal
+ */
+export function getStandaloneInitialState(options: AuthStrategyOptions): AuthStrategyResult {
+  const {authConfig, initialLocationHref} = options
+  const providedToken = authConfig.token
+  const callbackUrl = authConfig.callbackUrl
+  const storageKey = '__sanity_auth_token'
+  const storageArea = authConfig.storageArea ?? getDefaultStorage()
+
+  // Provided token always wins
+  if (providedToken) {
+    return {
+      authState: {type: AuthStateType.LOGGED_IN, token: providedToken, currentUser: null},
+      storageKey,
+      storageArea,
+      authMethod: undefined,
+      dashboardContext: {},
+    }
+  }
+
+  // Check for auth code or token-from-location (OAuth callback)
+  if (getAuthCode(callbackUrl, initialLocationHref) || getTokenFromLocation(initialLocationHref)) {
+    return {
+      authState: {type: AuthStateType.LOGGING_IN, isExchangingToken: false},
+      storageKey,
+      storageArea,
+      authMethod: undefined,
+      dashboardContext: {},
+    }
+  }
+
+  // Try localStorage
+  const token = getTokenFromStorage(storageArea, storageKey)
+  if (token) {
+    return {
+      authState: {type: AuthStateType.LOGGED_IN, token, currentUser: null},
+      storageKey,
+      storageArea,
+      authMethod: 'localstorage',
+      dashboardContext: {},
+    }
+  }
+
+  // No token found
+  return {
+    authState: {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false},
+    storageKey,
+    storageArea,
+    authMethod: undefined,
+    dashboardContext: {},
+  }
+}
+
+/**
+ * Initialize Standalone auth subscriptions:
+ * - Subscribe to state changes and fetch current user
+ * - Subscribe to storage events for token key
+ * - Start stamped token refresh
+ *
+ * @internal
+ */
+export function initializeStandaloneAuth(
+  context: StoreContext<AuthStoreState>,
+  tokenRefresherRunning: boolean,
+): {dispose: () => void; tokenRefresherStarted: boolean} {
+  const subscriptions: Subscription[] = []
+  let startedRefresher = false
+
+  subscriptions.push(subscribeToStateAndFetchCurrentUser(context, {useProjectHostname: false}))
+
+  const storageArea = context.state.get().options?.storageArea
+  if (storageArea) {
+    subscriptions.push(subscribeToStorageEventsAndSetToken(context))
+  }
+
+  if (!tokenRefresherRunning) {
+    startedRefresher = true
+    subscriptions.push(refreshStampedToken(context))
+  }
+
+  return {
+    dispose: () => {
+      for (const subscription of subscriptions) {
+        subscription.unsubscribe()
+      }
+    },
+    tokenRefresherStarted: startedRefresher,
+  }
+}

package/src/auth/studioAuth.ts

@@ -0,0 +1,217 @@
+import {type Subscription} from 'rxjs'
+
+import {type TokenSource} from '../config/sanityConfig'
+import {type StoreContext} from '../store/defineStore'
+import {AuthStateType} from './authStateType'
+import {type AuthStoreState, type LoggedInAuthState} from './authStore'
+import {type AuthStrategyOptions, type AuthStrategyResult} from './authStrategy'
+import {refreshStampedToken} from './refreshStampedToken'
+import {checkForCookieAuth, getStudioTokenFromLocalStorage} from './studioModeAuth'
+import {subscribeToStateAndFetchCurrentUser} from './subscribeToStateAndFetchCurrentUser'
+import {subscribeToStorageEventsAndSetToken} from './subscribeToStorageEventsAndSetToken'
+import {getDefaultStorage} from './utils'
+
+/**
+ * Resolves the initial auth state for Studio mode.
+ *
+ * When a `tokenSource` is provided (via `config.studio.auth.token`), the
+ * initial state is `LOGGING_IN` — the actual token arrives asynchronously
+ * via the subscription set up in `initializeStudioAuth`.
+ *
+ * Fallback token discovery order (no tokenSource):
+ * 1. Provided token (`auth.token` in config)
+ * 2. localStorage: `__studio_auth_token_${projectId}`
+ * 3. Falls back to `LOGGED_OUT` (cookie auth is checked async in `initializeStudioAuth`)
+ *
+ * @internal
+ */
+export function getStudioInitialState(options: AuthStrategyOptions): AuthStrategyResult {
+  const {authConfig, projectId, tokenSource} = options
+  const storageArea = authConfig.storageArea ?? getDefaultStorage()
+  const studioStorageKey = `__studio_auth_token_${projectId ?? ''}`
+
+  // When a reactive token source is available, start in LOGGING_IN state.
+  // The actual token will arrive via subscription in initializeStudioAuth.
+  if (tokenSource) {
+    return {
+      authState: {type: AuthStateType.LOGGING_IN, isExchangingToken: false},
+      storageKey: studioStorageKey,
+      storageArea,
+      authMethod: undefined,
+      dashboardContext: {},
+    }
+  }
+
+  // Fallback: discover token from config or localStorage
+  const providedToken = authConfig.token
+
+  // Check localStorage first — mirrors original authStore behavior where
+  // the localStorage read always runs before the providedToken check.
+  let authMethod: AuthStrategyResult['authMethod'] = undefined
+  const token = getStudioTokenFromLocalStorage(storageArea, studioStorageKey)
+  if (token) {
+    authMethod = 'localstorage'
+  }
+
+  if (providedToken) {
+    return {
+      authState: {type: AuthStateType.LOGGED_IN, token: providedToken, currentUser: null},
+      storageKey: studioStorageKey,
+      storageArea,
+      authMethod,
+      dashboardContext: {},
+    }
+  }
+
+  if (token) {
+    return {
+      authState: {type: AuthStateType.LOGGED_IN, token, currentUser: null},
+      storageKey: studioStorageKey,
+      storageArea,
+      authMethod: 'localstorage',
+      dashboardContext: {},
+    }
+  }
+
+  // No token found — start logged out, cookie auth will be checked asynchronously
+  return {
+    authState: {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false},
+    storageKey: studioStorageKey,
+    storageArea,
+    authMethod: undefined,
+    dashboardContext: {},
+  }
+}
+
+/**
+ * Initialize Studio auth subscriptions.
+ *
+ * When a `tokenSource` is available (reactive path), subscribes to it for
+ * ongoing token sync. The Studio is the token authority — no independent
+ * token refresh or cookie auth probing is needed.
+ *
+ * Fallback path (no tokenSource):
+ * - Subscribe to state changes and fetch current user
+ * - Subscribe to storage events for studio token key
+ * - Check for cookie auth asynchronously if no token was found
+ * - Start stamped token refresh
+ *
+ * @internal
+ */
+export function initializeStudioAuth(
+  context: StoreContext<AuthStoreState>,
+  tokenRefresherRunning: boolean,
+): {dispose: () => void; tokenRefresherStarted: boolean} {
+  const tokenSource = context.instance.config.studio?.auth?.token
+
+  // Reactive token path — Studio provides the token
+  if (tokenSource) {
+    return initializeWithTokenSource(context, tokenSource)
+  }
+
+  // Fallback path — discover token from localStorage/cookies
+  return initializeWithFallback(context, tokenRefresherRunning)
+}
+
+/**
+ * Subscribe to a reactive token source from the Studio workspace.
+ * The Studio is the single authority for auth — the SDK does not run
+ * its own token refresher or cookie auth checks.
+ */
+function initializeWithTokenSource(
+  context: StoreContext<AuthStoreState>,
+  tokenSource: TokenSource,
+): {dispose: () => void; tokenRefresherStarted: boolean} {
+  const subscriptions: Subscription[] = []
+
+  // Subscribe to the current user fetcher — runs whenever auth state changes
+  subscriptions.push(subscribeToStateAndFetchCurrentUser(context, {useProjectHostname: true}))
+
+  // Subscribe to the Studio's token stream
+  const tokenSub = tokenSource.subscribe({
+    next: (token) => {
+      const {state} = context
+      if (token) {
+        state.set('studioTokenSource', (prev) => ({
+          options: {...prev.options, authMethod: undefined},
+          authState: {type: AuthStateType.LOGGED_IN, token, currentUser: null},
+        }))
+      } else {
+        state.set('studioTokenSourceLoggedOut', (prev) => ({
+          options: {...prev.options, authMethod: undefined},
+          authState: {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false},
+        }))
+      }
+    },
+  })
+
+  return {
+    dispose: () => {
+      tokenSub.unsubscribe()
+      for (const subscription of subscriptions) {
+        subscription.unsubscribe()
+      }
+    },
+    // Studio handles token refresh — do not start the SDK's refresher
+    tokenRefresherStarted: false,
+  }
+}
+
+/**
+ * Fallback initialization when no reactive token source is available.
+ * Uses localStorage/cookie discovery (existing behavior).
+ */
+function initializeWithFallback(
+  context: StoreContext<AuthStoreState>,
+  tokenRefresherRunning: boolean,
+): {dispose: () => void; tokenRefresherStarted: boolean} {
+  const subscriptions: Subscription[] = []
+  let startedRefresher = false
+
+  subscriptions.push(subscribeToStateAndFetchCurrentUser(context, {useProjectHostname: true}))
+
+  const storageArea = context.state.get().options?.storageArea
+  if (storageArea) {
+    subscriptions.push(subscribeToStorageEventsAndSetToken(context))
+  }
+
+  // If no token found during getInitialState, try cookie auth asynchronously
+  try {
+    const {instance, state} = context
+    const token: string | null =
+      state.get().authState?.type === AuthStateType.LOGGED_IN
+        ? (state.get().authState as LoggedInAuthState).token
+        : null
+
+    if (!token) {
+      const projectIdValue = instance.config.projectId
+      const clientFactory = state.get().options.clientFactory
+      checkForCookieAuth(projectIdValue, clientFactory).then((isCookieAuthEnabled) => {
+        if (!isCookieAuthEnabled) return
+        state.set('enableCookieAuth', (prev) => ({
+          options: {...prev.options, authMethod: 'cookie'},
+          authState:
+            prev.authState.type === AuthStateType.LOGGED_IN
+              ? prev.authState
+              : {type: AuthStateType.LOGGED_IN, token: '', currentUser: null},
+        }))
+      })
+    }
+  } catch {
+    // best-effort cookie detection
+  }
+
+  if (!tokenRefresherRunning) {
+    startedRefresher = true
+    subscriptions.push(refreshStampedToken(context))
+  }
+
+  return {
+    dispose: () => {
+      for (const subscription of subscriptions) {
+        subscription.unsubscribe()
+      }
+    },
+    tokenRefresherStarted: startedRefresher,
+  }
+}

package/src/auth/studioModeAuth.test.ts

@@ -21,7 +21,7 @@ describe('checkForCookieAuth', () => {
 
     await checkForCookieAuth(projectId, clientFactory)
 
-    expect(clientFactory).toHaveBeenCalledWith({projectId, useCdn: false})
+    expect(clientFactory).toHaveBeenCalledWith(expect.objectContaining({projectId, useCdn: false}))
   })
 
   it('should return true if client request returns a user with id', async () => {
@@ -64,6 +64,48 @@ describe('checkForCookieAuth', () => {
 
     expect(result).toBe(false)
   })
+
+  it('should return false if client request returns null', async () => {
+    const projectId = 'test-project'
+    const mockClient = {
+      request: vi.fn().mockResolvedValue(null),
+    } as unknown as SanityClient
+    const clientFactory = vi.fn().mockReturnValue(mockClient)
+
+    const result = await checkForCookieAuth(projectId, clientFactory)
+
+    expect(result).toBe(false)
+  })
+
+  it('should return false if client request returns a non-object', async () => {
+    const projectId = 'test-project'
+    const mockClient = {
+      request: vi.fn().mockResolvedValue('unexpected-string'),
+    } as unknown as SanityClient
+    const clientFactory = vi.fn().mockReturnValue(mockClient)
+
+    const result = await checkForCookieAuth(projectId, clientFactory)
+
+    expect(result).toBe(false)
+  })
+
+  it('should pass timeout to client factory', async () => {
+    const projectId = 'test-project'
+    const mockClient = {
+      request: vi.fn().mockResolvedValue({id: 'user-id'}),
+    } as unknown as SanityClient
+    const clientFactory = vi.fn().mockReturnValue(mockClient)
+
+    await checkForCookieAuth(projectId, clientFactory)
+
+    expect(clientFactory).toHaveBeenCalledWith(
+      expect.objectContaining({
+        projectId,
+        useCdn: false,
+        timeout: 10_000,
+      }),
+    )
+  })
 })
 
 describe('getStudioTokenFromLocalStorage', () => {

package/src/auth/studioModeAuth.ts

@@ -2,6 +2,13 @@ import {type ClientConfig, type SanityClient} from '@sanity/client'
 
 import {getTokenFromStorage} from './utils'
 
+/**
+ * Cookie auth is a best-effort probe — if the API doesn't respond quickly,
+ * the user likely isn't cookie-authenticated and we should move on rather
+ * than block the auth flow indefinitely.
+ */
+const COOKIE_AUTH_TIMEOUT_MS = 10_000
+
 /**
  * Attempts to check for cookie auth by making a withCredentials request to the users endpoint.
  * @param projectId - The project ID to check for cookie auth.
@@ -18,13 +25,15 @@ export async function checkForCookieAuth(
     const client = clientFactory({
       projectId,
       useCdn: false,
+      requestTagPrefix: 'sdk',
+      timeout: COOKIE_AUTH_TIMEOUT_MS,
     })
     const user = await client.request({
       uri: '/users/me',
       withCredentials: true,
       tag: 'users.get-current',
     })
-    return typeof user?.id === 'string'
+    return user != null && typeof user === 'object' && typeof user.id === 'string'
   } catch {
     return false
   }

package/src/auth/subscribeToStateAndFetchCurrentUser.ts

@@ -3,20 +3,35 @@ import {distinctUntilChanged, filter, map, type Subscription, switchMap} from 'r
 
 import {type StoreContext} from '../store/defineStore'
 import {DEFAULT_API_VERSION, REQUEST_TAG_PREFIX} from './authConstants'
+import {isStudioConfig} from './authMode'
 import {AuthStateType} from './authStateType'
 import {type AuthMethodOptions, type AuthState, type AuthStoreState} from './authStore'
 
-export const subscribeToStateAndFetchCurrentUser = ({
-  state,
-  instance,
-}: StoreContext<AuthStoreState>): Subscription => {
+/**
+ * Subscribes to auth state changes and fetches the current user when
+ * the state transitions to `LOGGED_IN` without a `currentUser`.
+ *
+ * @param context - The store context for the auth store.
+ * @param fetchOptions - Configuration options. When `useProjectHostname` is
+ *   `true`, requests use the project-specific hostname (required for Studio
+ *   cookie auth). Set to `true` for studio mode, `false` otherwise.
+ *
+ * @internal
+ */
+export const subscribeToStateAndFetchCurrentUser = (
+  {state, instance}: StoreContext<AuthStoreState>,
+  fetchOptions?: {useProjectHostname?: boolean},
+): Subscription => {
   const {clientFactory, apiHost} = state.get().options
-  const useProjectHostname = !!instance.config.studioMode?.enabled
+  const useProjectHostname = fetchOptions?.useProjectHostname ?? isStudioConfig(instance.config)
   const projectId = instance.config.projectId
 
   const currentUser$ = state.observable
     .pipe(
-      map(({authState, options}) => ({authState, authMethod: options.authMethod})),
+      map(({authState, options: storeOptions}) => ({
+        authState,
+        authMethod: storeOptions.authMethod,
+      })),
       filter(
         (
           value,