Add support for SDK to use OAuth2.0 PKCE flow (#13804)

Adds helpers + refresh middleware and updates OAuth service to support
PKCE flow.

Makes API key only configs use the API-forward SDK type

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Dylan Jeffers <dylan@audius.co>
Co-authored-by: Ray Jacobson <ray@audius.co>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>

Author: 6 people

.changeset/breezy-lions-jog.md

@@ -0,0 +1,5 @@
+---
+"@audius/sdk": minor
+---
+
+Add support for OAuth2.0 PKCE access/refresh tokens

packages/sdk/src/sdk/createSdkWithServices.ts

@@ -29,9 +29,11 @@ import { developmentConfig } from './config/development'
 import { productionConfig } from './config/production'
 import {
   addAppInfoMiddleware,
-  addRequestSignatureMiddleware
+  addRequestSignatureMiddleware,
+  addTokenRefreshMiddleware
 } from './middleware'
 import { OAuth } from './oauth'
+import { OAuthTokenStore } from './oauth/tokenStore'
 import {
   PaymentRouterClient,
   getDefaultPaymentRouterClientConfig
@@ -133,7 +135,7 @@ export const createSdkWithServices = (config: SdkConfig) => {
     )
   }
 
-  // Initialize APIs
+  // Initialize APIs (also creates tokenStore and oauth)
   const apis = initializeApis({
     config,
     apiKey,
@@ -142,18 +144,7 @@ export const createSdkWithServices = (config: SdkConfig) => {
     services
   })
 
-  // Initialize OAuth
-  const oauth = isBrowser
-    ? new OAuth({
-        appName,
-        apiKey,
-        usersApi: apis.users,
-        logger: services.logger
-      })
-    : undefined
-
   return {
-    oauth,
     ...apis
   }
 }
@@ -460,11 +451,36 @@ const initializeApis = ({
     })
   ]
 
+  // Token store for PKCE flow — provides dynamic accessToken to Configuration
+  const tokenStore = new OAuthTokenStore()
+
+  // Auto-refresh middleware — intercepts 401s and retries with a fresh token.
+  const oauth =
+    typeof window !== 'undefined'
+      ? new OAuth({
+          apiKey,
+          tokenStore,
+          basePath
+        })
+      : undefined
+
+  if (apiKey && oauth) {
+    middleware.push(
+      addTokenRefreshMiddleware({
+        oauth
+      })
+    )
+  }
+
+  const bearerToken = 'bearerToken' in config ? config.bearerToken : undefined
+
   const apiClientConfig = new Configuration({
     fetchApi: fetch,
     middleware,
     basePath,
-    accessToken: 'bearerToken' in config ? config.bearerToken : undefined
+    // Static bearerToken takes precedence; otherwise use the dynamic store
+    // so PKCE login can inject tokens after construction.
+    accessToken: bearerToken ?? tokenStore.asAccessTokenProvider()
   })
 
   const tracks = new TracksApi(apiClientConfig, services)
@@ -507,6 +523,8 @@ const initializeApis = ({
   const search = new SearchApi(apiClientConfig)
 
   return {
+    oauth,
+    tokenStore,
     tracks,
     users,
     albums,

packages/sdk/src/sdk/createSdkWithoutServices.ts

@@ -26,9 +26,11 @@ import { developmentConfig } from './config/development'
 import { productionConfig } from './config/production'
 import {
   addAppInfoMiddleware,
-  addRequestSignatureMiddleware
+  addRequestSignatureMiddleware,
+  addTokenRefreshMiddleware
 } from './middleware'
 import { OAuth } from './oauth'
+import { OAuthTokenStore } from './oauth/tokenStore'
 import { Logger, Storage, StorageNodeSelector } from './services'
 import { type SdkConfig } from './types'
 
@@ -54,6 +56,19 @@ export const createSdkWithoutServices = (config: SdkConfig) => {
 
   const middleware: Middleware[] = []
 
+  // Token store for PKCE flow — provides dynamic accessToken to Configuration
+  const tokenStore = new OAuthTokenStore()
+
+  // Initialize OAuth early so it can be passed to middleware
+  const oauth =
+    typeof window !== 'undefined'
+      ? new OAuth({
+          apiKey,
+          tokenStore,
+          basePath
+        })
+      : undefined
+
   if (apiSecret || services?.audiusWalletClient) {
     middleware.push(
       addRequestSignatureMiddleware({
@@ -81,25 +96,30 @@ export const createSdkWithoutServices = (config: SdkConfig) => {
     )
   }
 
+  // Auto-refresh middleware — intercepts 401s and retries with a fresh token.
+  if (apiKey && oauth) {
+    middleware.push(
+      addTokenRefreshMiddleware({
+        oauth
+      })
+    )
+  }
+
   const apiConfig = new Configuration({
     fetchApi: fetch,
     middleware,
     basePath,
-    accessToken: bearerToken
+    // Static bearerToken takes precedence; otherwise use the dynamic store
+    // so PKCE login can inject tokens after construction.
+    accessToken: bearerToken ?? tokenStore.asAccessTokenProvider()
   })
 
-  // Initialize OAuth
+  // Initialize API clients
   const usersApi = new UsersApi(apiConfig)
-  const oauth =
-    typeof window !== 'undefined'
-      ? new OAuth({
-          apiKey,
-          usersApi
-        })
-      : undefined
 
   return {
     oauth,
+    tokenStore,
     tracks: new TracksApi(apiConfig),
     users: usersApi,
     // albums

packages/sdk/src/sdk/middleware/addTokenRefreshMiddleware.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+import type { OAuth } from '../oauth/OAuth'
+
+import { addTokenRefreshMiddleware } from './addTokenRefreshMiddleware'
+
+// Minimal fetch mock helper
+function mockResponse(status: number, body?: object): Response {
+  return new Response(body ? JSON.stringify(body) : null, {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+
+function createMockOAuth(
+  refreshBehaviour: () => Promise<string | null>,
+  hasRefreshToken = true
+): OAuth {
+  return {
+    hasRefreshToken,
+    refreshAccessToken: refreshBehaviour
+  } as unknown as OAuth
+}
+
+describe('addTokenRefreshMiddleware', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('passes through non-401 responses unchanged', async () => {
+    const oauth = createMockOAuth(async () => 'token')
+    const mw = addTokenRefreshMiddleware({ oauth })
+    const response = mockResponse(200, { data: 'ok' })
+
+    const result = await mw.post!({
+      fetch,
+      url: 'https://api.example.com/v1/users/me',
+      init: {},
+      response
+    })
+
+    expect(result).toBe(response)
+  })
+
+  it('passes through 401 without calling refreshAccessToken when unauthenticated', async () => {
+    const refreshFn = vi.fn()
+    const oauth = createMockOAuth(refreshFn, false)
+    const mw = addTokenRefreshMiddleware({ oauth })
+    const response = mockResponse(401)
+
+    const result = await mw.post!({
+      fetch,
+      url: 'https://api.example.com/v1/users/me',
+      init: {},
+      response
+    })
+
+    expect(result).toBe(response)
+    expect(refreshFn).not.toHaveBeenCalled()
+  })
+
+  it('passes through 401 when refresh returns null (no refresh token)', async () => {
+    const oauth = createMockOAuth(async () => null)
+    const mw = addTokenRefreshMiddleware({ oauth })
+    const response = mockResponse(401)
+
+    const result = await mw.post!({
+      fetch,
+      url: 'https://api.example.com/v1/users/me',
+      init: {},
+      response
+    })
+
+    expect(result).toBe(response)
+  })
+
+  it('refreshes and retries on 401 when refresh succeeds', async () => {
+    const oauth = createMockOAuth(async () => 'new-access')
+    const retryResponse = mockResponse(200, { data: 'success' })
+    const contextFetch = vi.fn().mockResolvedValueOnce(retryResponse)
+
+    const mw = addTokenRefreshMiddleware({ oauth })
+
+    const result = await mw.post!({
+      fetch: contextFetch,
+      url: 'https://api.example.com/v1/tracks/123',
+      init: {
+        method: 'GET',
+        headers: { Authorization: 'Bearer expired-access' }
+      },
+      response: mockResponse(401)
+    })
+
+    // Original request was retried with new token
+    expect(contextFetch).toHaveBeenCalledWith(
+      'https://api.example.com/v1/tracks/123',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer new-access'
+        })
+      })
+    )
+
+    expect(result).toBe(retryResponse)
+  })
+
+  it('surfaces 401 when refresh fails', async () => {
+    const oauth = createMockOAuth(async () => null)
+    const mw = addTokenRefreshMiddleware({ oauth })
+    const original401 = mockResponse(401)
+
+    const result = await mw.post!({
+      fetch,
+      url: 'https://api.example.com/v1/tracks/123',
+      init: {},
+      response: original401
+    })
+
+    expect(result).toBe(original401)
+  })
+
+  it('surfaces 401 when refreshAccessToken throws', async () => {
+    const oauth = createMockOAuth(async () => {
+      throw new Error('network failure')
+    })
+    const mw = addTokenRefreshMiddleware({ oauth })
+    const original401 = mockResponse(401)
+
+    const result = await mw.post!({
+      fetch,
+      url: 'https://api.example.com/v1/tracks/123',
+      init: {},
+      response: original401
+    })
+
+    expect(result).toBe(original401)
+  })
+})

packages/sdk/src/sdk/middleware/addTokenRefreshMiddleware.ts

@@ -0,0 +1,60 @@
+import type { Middleware, ResponseContext } from '../api/generated/default'
+import type { OAuth } from '../oauth/OAuth'
+import fetch from '../utils/fetch'
+
+/**
+ * Middleware that transparently refreshes an expired access token on 401.
+ *
+ * When a response comes back with HTTP 401 the middleware delegates to
+ * `OAuth.refreshAccessToken()` which checks for a refresh token, performs the
+ * HTTP exchange, and updates the token store.  On success the original request
+ * is retried with the fresh access token.  On failure the 401 propagates.
+ *
+ * When the client is unauthenticated (no refresh token stored) the middleware
+ * short-circuits immediately, avoiding noisy error callbacks.
+ */
+export const addTokenRefreshMiddleware = ({
+  oauth
+}: {
+  oauth: OAuth
+}): Middleware => {
+  let refreshInFlight: Promise<string | null> | null = null
+
+  return {
+    post: async (context: ResponseContext): Promise<Response | void> => {
+      if (context.response.status !== 401) {
+        return context.response
+      }
+
+      // Skip refresh when unauthenticated to avoid noisy error callbacks.
+      if (!oauth.hasRefreshToken) {
+        return context.response
+      }
+
+      // Coalesce concurrent 401s into a single refresh call.
+      if (!refreshInFlight) {
+        refreshInFlight = oauth
+          .refreshAccessToken()
+          .catch(() => null)
+          .finally(() => {
+            refreshInFlight = null
+          })
+      }
+
+      const newAccessToken = await refreshInFlight
+      if (!newAccessToken) {
+        return context.response
+      }
+
+      // Retry the original request with the new access token.
+      const retryInit: RequestInit = {
+        ...context.init,
+        headers: {
+          ...((context.init.headers as Record<string, string>) ?? {}),
+          Authorization: `Bearer ${newAccessToken}`
+        }
+      }
+      return fetch(context.url, retryInit)
+    }
+  }
+}

packages/sdk/src/sdk/middleware/index.ts

@@ -1,2 +1,3 @@
 export { addAppInfoMiddleware } from './addAppInfoMiddleware'
 export { addRequestSignatureMiddleware } from './addRequestSignatureMiddleware'
+export { addTokenRefreshMiddleware } from './addTokenRefreshMiddleware'