@sanity/sdk 3.1.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/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}>
+  }
+}