@sanity/sdk 3.0.0 → 3.2.0

package/src/auth/oauth/oauthAuth.ts

@@ -0,0 +1,168 @@
+import {defer, distinctUntilChanged, filter, map, type Subscription} from 'rxjs'
+
+import {type StoreContext} from '../../store/defineStore'
+import {DEFAULT_BASE} from '../authConstants'
+import {AuthStateType} from '../authStateType'
+import {type AuthStoreState} from '../authStore'
+import {type AuthStrategyOptions, type AuthStrategyResult} from '../authStrategy'
+import {subscribeToStateAndFetchCurrentUser} from '../subscribeToStateAndFetchCurrentUser'
+import {createLoggedInAuthState, getDefaultStorage, getStorageEvents} from '../utils'
+import {type OAuthTokens} from './types'
+
+/** localStorage (or configured `storageArea`) key for persisted OAuth tokens. */
+export const OAUTH_TOKENS_KEY = '__sanity_oauth_tokens'
+
+/** The persisted JSON shape of {@link OAuthTokens}, `expiresAt` as an ISO string. */
+interface SerializedOAuthTokens extends Omit<OAuthTokens, 'expiresAt'> {
+  expiresAt: string
+}
+
+/**
+ * Parses persisted token JSON back into {@link OAuthTokens}. Returns `null`
+ * when the value is missing or malformed.
+ *
+ * @internal
+ */
+export function deserializeTokens(raw: string | null): OAuthTokens | null {
+  if (!raw) return null
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    if (
+      typeof parsed !== 'object' ||
+      parsed === null ||
+      !('accessToken' in parsed) ||
+      typeof (parsed as SerializedOAuthTokens).accessToken !== 'string' ||
+      !('expiresAt' in parsed) ||
+      typeof (parsed as SerializedOAuthTokens).expiresAt !== 'string'
+    ) {
+      return null
+    }
+    const value = parsed as SerializedOAuthTokens
+    return {
+      accessToken: value.accessToken,
+      tokenType: 'bearer',
+      expiresIn: value.expiresIn,
+      expiresAt: new Date(value.expiresAt),
+      ...(value.refreshToken !== undefined && {refreshToken: value.refreshToken}),
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Resolves the initial auth state for OAuth mode.
+ *
+ * State discovery order:
+ * 1. Persisted tokens in `__sanity_oauth_tokens` → `LOGGED_IN`
+ * 2. Callback URL (contains `code`/`state`/`error` and matches `redirectUri`)
+ *    → `LOGGING_IN`
+ * 3. Otherwise → `LOGGED_OUT`
+ *
+ * @internal
+ */
+export function getOauthInitialState(options: AuthStrategyOptions): AuthStrategyResult {
+  const {authConfig, initialLocationHref} = options
+  const storageKey = OAUTH_TOKENS_KEY
+  const storageArea = authConfig.storageArea ?? getDefaultStorage()
+  const redirectUri = authConfig.oauth?.redirectUri
+
+  // Persisted tokens win
+  const tokens = deserializeTokens(storageArea?.getItem(OAUTH_TOKENS_KEY) ?? null)
+  if (tokens) {
+    return {
+      authState: createLoggedInAuthState(tokens.accessToken, null),
+      storageKey,
+      storageArea,
+      authMethod: 'localstorage',
+      dashboardContext: {},
+      oauthTokens: tokens,
+    }
+  }
+
+  // Callback URL with code/state/error whose origin + pathname match our
+  // redirect URI (query and hash are ignored).
+  const {searchParams} = new URL(initialLocationHref, DEFAULT_BASE)
+  const isCallback =
+    searchParams.has('code') || searchParams.has('state') || searchParams.has('error')
+  if (redirectUri && isCallback) {
+    const loc = new URL(initialLocationHref, DEFAULT_BASE)
+    const redirect = new URL(redirectUri, DEFAULT_BASE)
+    if (loc.origin === redirect.origin && loc.pathname === redirect.pathname) {
+      return {
+        authState: {type: AuthStateType.LOGGING_IN, isExchangingToken: false},
+        storageKey,
+        storageArea,
+        authMethod: undefined,
+        dashboardContext: {},
+      }
+    }
+  }
+
+  // No tokens, not a callback
+  return {
+    authState: {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false},
+    storageKey,
+    storageArea,
+    authMethod: undefined,
+    dashboardContext: {},
+  }
+}
+
+/**
+ * Subscribes to cross-tab `storage` events for the OAuth tokens key, syncing
+ * this tab's auth state when tokens change in another tab.
+ *
+ * @internal
+ */
+export function subscribeToOAuthStorageEvents({state}: StoreContext<AuthStoreState>): Subscription {
+  const {storageArea} = state.get().options
+
+  const tokens$ = defer(getStorageEvents).pipe(
+    filter((e) => e.storageArea === storageArea && e.key === OAUTH_TOKENS_KEY),
+    map(() => deserializeTokens(storageArea?.getItem(OAUTH_TOKENS_KEY) ?? null)),
+    distinctUntilChanged((a, b) => a?.accessToken === b?.accessToken),
+  )
+
+  return tokens$.subscribe((tokens) => {
+    state.set('updateOAuthTokensFromStorageEvent', {
+      authState: tokens
+        ? createLoggedInAuthState(tokens.accessToken, null)
+        : {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false},
+      oauthTokens: tokens ?? undefined,
+    })
+  })
+}
+
+/**
+ * Initialize OAuth auth subscriptions:
+ * - Subscribe to state changes and fetch current user
+ * - Subscribe to cross-tab storage events for the OAuth tokens key
+ *
+ * OAuth tokens are refreshed via the `refresh_token` grant (see
+ * `refreshOAuthTokens`), so the stamped-token refresher is not started here.
+ *
+ * @internal
+ */
+export function initializeOauthAuth(context: StoreContext<AuthStoreState>): {
+  dispose: () => void
+  tokenRefresherStarted: boolean
+} {
+  const subscriptions: Subscription[] = []
+
+  subscriptions.push(subscribeToStateAndFetchCurrentUser(context, {useProjectHostname: false}))
+
+  const storageArea = context.state.get().options?.storageArea
+  if (storageArea) {
+    subscriptions.push(subscribeToOAuthStorageEvents(context))
+  }
+
+  return {
+    dispose: () => {
+      for (const subscription of subscriptions) {
+        subscription.unsubscribe()
+      }
+    },
+    tokenRefresherStarted: false,
+  }
+}

package/src/auth/oauth/pkce.test.ts

@@ -0,0 +1,44 @@
+import {createHash} from 'node:crypto'
+
+import {describe, expect, it} from 'vitest'
+
+import {base64UrlEncode, generateCodeChallenge, generateCodeVerifier, generateState} from './pkce'
+
+describe('base64UrlEncode', () => {
+  it('encodes bytes as base64url without padding', () => {
+    // 0xff 0xef 0xbf → "/++/" in base64, "_--_" in base64url (minus padding)
+    const encoded = base64UrlEncode(new Uint8Array([0xff, 0xef, 0xbf]))
+    expect(encoded).not.toContain('+')
+    expect(encoded).not.toContain('/')
+    expect(encoded).not.toContain('=')
+    expect(encoded).toBe('_--_')
+  })
+})
+
+describe('generateCodeVerifier / generateState', () => {
+  it('generates unique, URL-safe strings', () => {
+    const a = generateCodeVerifier()
+    const b = generateCodeVerifier()
+    const s = generateState()
+    expect(a).not.toBe(b)
+    expect(a).toMatch(/^[A-Za-z0-9_-]+$/)
+    expect(s).toMatch(/^[A-Za-z0-9_-]+$/)
+    expect(a.length).toBeGreaterThanOrEqual(43)
+  })
+})
+
+describe('generateCodeChallenge', () => {
+  it('produces base64url(sha256(verifier))', async () => {
+    const verifier = 'test-verifier'
+    const challenge = await generateCodeChallenge(verifier)
+
+    const expected = createHash('sha256')
+      .update(verifier)
+      .digest('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '')
+
+    expect(challenge).toBe(expected)
+  })
+})

package/src/auth/oauth/pkce.ts

@@ -0,0 +1,60 @@
+/**
+ * PKCE (Proof Key for Code Exchange, RFC 7636) helpers for the OAuth
+ * authorization-code flow.
+ *
+ * @internal
+ */
+
+/** Number of random bytes used for the `code_verifier` and `state`. */
+const RANDOM_BYTE_LENGTH = 32
+
+/**
+ * Encodes a byte array as a base64url string (RFC 4648 §5) with no padding,
+ * as required for PKCE `code_verifier`/`code_challenge` values.
+ *
+ * @internal
+ */
+export function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte)
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function randomString(): string {
+  const bytes = new Uint8Array(RANDOM_BYTE_LENGTH)
+  crypto.getRandomValues(bytes)
+  return base64UrlEncode(bytes)
+}
+
+/**
+ * Generates a PKCE `code_verifier`
+ *
+ * @internal
+ */
+export function generateCodeVerifier(): string {
+  return randomString()
+}
+
+/**
+ * Generates the `state` parameter used to defend against CSRF on the OAuth
+ * callback.
+ *
+ * @internal
+ */
+export function generateState(): string {
+  return randomString()
+}
+
+/**
+ * Derives the PKCE `code_challenge` from a `code_verifier` using
+ * `base64url(sha256(verifier))` (the `S256` method).
+ *
+ * @internal
+ */
+export async function generateCodeChallenge(codeVerifier: string): Promise<string> {
+  const data = new TextEncoder().encode(codeVerifier)
+  const digest = await crypto.subtle.digest('SHA-256', data)
+  return base64UrlEncode(new Uint8Array(digest))
+}

package/src/auth/oauth/types.ts

@@ -0,0 +1,12 @@
+/**
+ * OAuth tokens issued by Sanity's OAuth token endpoint.
+ *
+ * @public
+ */
+export interface OAuthTokens {
+  accessToken: string
+  tokenType: 'bearer'
+  expiresIn: number
+  expiresAt: Date
+  refreshToken?: string
+}

package/src/auth/refreshStampedToken.ts

@@ -36,7 +36,7 @@ function createTokenRefreshStream(
 
     const subscription = client.observable
       .request<{token: string}>({
-        uri: 'auth/refresh-token',
+        url: 'auth/refresh-token',
         method: 'POST',
         tag: 'refresh-token',
         body: {

package/src/auth/studioModeAuth.test.ts

@@ -35,7 +35,7 @@ describe('checkForCookieAuth', () => {
 
     expect(result).toBe(true)
     expect(mockClient.request).toHaveBeenCalledWith({
-      uri: '/users/me',
+      url: '/users/me',
       withCredentials: true,
       tag: 'users.get-current',
     })

package/src/auth/studioModeAuth.ts

@@ -30,7 +30,7 @@ export async function checkForCookieAuth(
       timeout: COOKIE_AUTH_TIMEOUT_MS,
     })
     const user = await client.request({
-      uri: '/users/me',
+      url: '/users/me',
       withCredentials: true,
       tag: 'users.get-current',
     })

package/src/auth/subscribeToStateAndFetchCurrentUser.test.ts

@@ -57,7 +57,7 @@ describe('subscribeToStateAndFetchCurrentUser', () => {
     })
     expect(mockRequest).toHaveBeenCalledWith({
       method: 'GET',
-      uri: '/users/me',
+      url: '/users/me',
       tag: 'users.get-current',
     })
 
@@ -97,7 +97,7 @@ describe('subscribeToStateAndFetchCurrentUser', () => {
     })
     expect(mockRequest).toHaveBeenCalledWith({
       method: 'GET',
-      uri: '/users/me',
+      url: '/users/me',
       tag: 'users.get-current',
     })
 

package/src/auth/subscribeToStateAndFetchCurrentUser.ts

@@ -73,7 +73,7 @@ export const subscribeToStateAndFetchCurrentUser = (
       switchMap((client) =>
         client.observable
           .request<CurrentUser>({
-            uri: '/users/me',
+            url: '/users/me',
             method: 'GET',
             tag: 'users.get-current',
           })

package/src/comments/addonDatasetStore.test.ts

@@ -59,7 +59,7 @@ describe('getAddonDatasetState', () => {
     )
 
     expect(observableRequest).toHaveBeenCalledWith({
-      uri: '/projects/p/datasets?datasetProfile=comments&addonFor=d',
+      url: '/projects/p/datasets?datasetProfile=comments&addonFor=d',
       tag: 'comments.addon-dataset.list',
     })
   })
@@ -139,7 +139,7 @@ describe('provisionAddonDataset', () => {
 
     await expect(provisionAddonDataset(instance, {})).resolves.toBe('d-comments')
     expect(request).toHaveBeenCalledWith({
-      uri: '/comments/d/setup',
+      url: '/comments/d/setup',
       method: 'POST',
       tag: 'comments.addon-dataset.setup',
     })

package/src/comments/addonDatasetStore.ts

@@ -67,7 +67,7 @@ function requestAddonDataset(
 ): Observable<string | undefined> {
   return client.observable
     .request<{name: string}[] | undefined>({
-      uri: `/projects/${projectId}/datasets?datasetProfile=${ADDON_DATASET_PROFILE}&addonFor=${dataset}`,
+      url: `/projects/${projectId}/datasets?datasetProfile=${ADDON_DATASET_PROFILE}&addonFor=${dataset}`,
       tag: 'comments.addon-dataset.list',
     })
     .pipe(map((datasets) => datasets?.[0]?.name))
@@ -182,7 +182,7 @@ export const provisionAddonDataset: (
       })
 
       const response = await client.request<{datasetName?: string} | undefined>({
-        uri: `/comments/${resource.dataset}/setup`,
+        url: `/comments/${resource.dataset}/setup`,
         method: 'POST',
         tag: 'comments.addon-dataset.setup',
       })

package/src/comments/commentActions.ts

@@ -16,6 +16,7 @@ import {bindActionByResource, type BoundResourceKey} from '../store/createAction
 import {type SanityInstance} from '../store/createSanityInstance'
 import {type StoreState} from '../store/createStoreState'
 import {type StoreContext} from '../store/defineStore'
+import {randomUuid} from '../utils/ids'
 import {
   assertDatasetResource,
   getAddonDatasetState,
@@ -326,7 +327,7 @@ export const createComment: (
       options,
       buildCommentPayload({
         authorId: requireCurrentUserId(instance),
-        commentId: options.commentId ?? crypto.randomUUID(),
+        commentId: options.commentId ?? randomUuid(),
         contentSnapshot: options.contentSnapshot,
         context: options.context,
         documentRevisionId: options.documentRevisionId,
@@ -336,7 +337,7 @@ export const createComment: (
         fieldPath,
         selection: options.selection,
         status: options.status ?? 'open',
-        threadId: options.threadId ?? crypto.randomUUID(),
+        threadId: options.threadId ?? randomUuid(),
         ...(isReleasePerspective(perspective) ? {documentVersionId: perspective.releaseName} : {}),
       }),
     )
@@ -386,7 +387,7 @@ export const replyToComment: (
       options,
       buildCommentPayload({
         authorId: requireCurrentUserId(instance),
-        commentId: options.commentId ?? crypto.randomUUID(),
+        commentId: options.commentId ?? randomUuid(),
         handle: options,
         message: options.message,
         // Replies to a reply belong to the thread's first comment, matching how
@@ -420,7 +421,7 @@ export const updateComment: (
     {commentId, message}: UpdateCommentOptions,
   ) => {
     const lastEditedAt = new Date().toISOString()
-    const transactionId = crypto.randomUUID()
+    const transactionId = randomUuid()
     const previous = findCommentById(state, commentId)
 
     if (previous) {
@@ -468,7 +469,7 @@ export const setCommentStatus: (
     {state, instance, key}: StoreContext<CommentsStoreState, BoundResourceKey>,
     {commentId, status}: SetCommentStatusOptions,
   ) => {
-    const transactionId = crypto.randomUUID()
+    const transactionId = randomUuid()
     const previousComments: StoredComment[] = []
 
     for (const entry of Object.values(state.get().entries)) {

package/src/comments/commentsStore.ts

@@ -29,7 +29,7 @@ import {
 } from '../store/createStateSourceAction'
 import {type StoreState} from '../store/createStoreState'
 import {defineStore, type StoreContext} from '../store/defineStore'
-import {insecureRandomId} from '../utils/ids'
+import {randomId} from '../utils/ids'
 import {setCleanupTimeout} from '../utils/setCleanupTimeout'
 import {observeAddonDatasetClient} from './addonDatasetStore'
 import {buildCommentThreads} from './buildCommentThreads'
@@ -360,7 +360,7 @@ export const getCommentsState: (
     selector: selectComments,
     onSubscribe: ({state, instance}, options: CommentsOptions) => {
       const key = getCommentsKey(toCommentsKeyParts(instance, options))
-      const subscriptionId = insecureRandomId()
+      const subscriptionId = randomId(16)
       state.set('addSubscriber', addSubscriber(key, subscriptionId))
 
       return () => {
@@ -390,7 +390,7 @@ export const getCommentThreadsState: (
     selector: selectCommentThreads,
     onSubscribe: ({state, instance}, options: CommentsOptions) => {
       const key = getCommentsKey(toCommentsKeyParts(instance, options))
-      const subscriptionId = insecureRandomId()
+      const subscriptionId = randomId(16)
       state.set('addSubscriber', addSubscriber(key, subscriptionId))
 
       return () => {
@@ -452,7 +452,7 @@ function resolveList<T>(
   // fetch and this promise would never settle. Holding it only for the duration
   // of the resolve also means a component that suspends and then errors before
   // mounting does not leave a subscriber-less entry behind holding its error.
-  const subscriptionId = insecureRandomId()
+  const subscriptionId = randomId(16)
   state.set('addSubscriber', addSubscriber(key, subscriptionId))
 
   const release = () => state.set('removeSubscriber', removeSubscriber(key, subscriptionId))

package/src/config/authConfig.ts

@@ -76,4 +76,22 @@ export interface AuthConfig {
    * ignoring any storage or callback handling.
    */
   token?: string
+
+  oauth?: {
+    /**
+     * Opaque OAuth `client_id`.
+     */
+    clientId: string
+
+    /**
+     * The redirect URI registered for this client. The OAuth provider
+     * redirects back here with the authorization `code` and `state`.
+     */
+    redirectUri: string
+
+    /**
+     * Organisation id used for RFC 8707 resource scoping.
+     */
+    organizationId: string
+  }
 }

package/src/dashboard/messageBus/__fixtures__/test-topics.ts

@@ -0,0 +1,18 @@
+import {type EventTopicDef, type StateTopicDef} from '../topics'
+
+declare module '../topics' {
+  interface Topics {
+    'test.count': StateTopicDef<number>
+    'test.token': StateTopicDef<string | null>
+    'test.scheme': StateTopicDef<'light' | 'dark'>
+    'test.suspending': StateTopicDef<string>
+    'test.ping': EventTopicDef<{n: number}>
+    'test.echo': EventTopicDef<{n: number}, {n: number}>
+    'test.mint': EventTopicDef<void, string>
+    'test.profile': StateTopicDef<{
+      fullName: string
+      tags: readonly string[]
+    }>
+    'test.greet': EventTopicDef<{fullName: string}, {salutation: string; language: string}>
+  }
+}