fix(oauth): coalesce slack token refresh per installation and preserve provider refresh errors

Author: TheodoreSpeaks

apps/sim/app/api/auth/oauth/token/route.test.ts

@@ -27,6 +27,7 @@ vi.mock('@/lib/auth/credential-access', () => ({
 }))
 
 import { TokenServiceAccountValidationError } from '@/lib/credentials/token-service-accounts/errors'
+import { OAuthRefreshError } from '@/lib/oauth/errors'
 import { GET, POST } from '@/app/api/auth/oauth/token/route'
 
 describe('OAuth Token API Routes', () => {
@@ -301,6 +302,38 @@ describe('OAuth Token API Routes', () => {
       )
     })
 
+    it('should surface the provider error detail on typed refresh failures', async () => {
+      mockAuthorizeCredentialUse.mockResolvedValueOnce({
+        ok: true,
+        authType: 'session',
+        requesterUserId: 'test-user-id',
+        credentialOwnerUserId: 'owner-user-id',
+      })
+      authOAuthUtilsMockFns.mockGetCredential.mockResolvedValueOnce({
+        id: 'credential-id',
+        accessToken: 'test-token',
+        refreshToken: 'refresh-token',
+        accessTokenExpiresAt: new Date(Date.now() - 3600 * 1000),
+        providerId: 'google',
+      })
+      authOAuthUtilsMockFns.mockRefreshTokenIfNeeded.mockRejectedValueOnce(
+        new OAuthRefreshError('google', 'invalid_grant', 'Token has been expired or revoked.')
+      )
+
+      const req = createMockRequest('POST', {
+        credentialId: 'credential-id',
+      })
+
+      const response = await POST(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data).toHaveProperty(
+        'error',
+        'Failed to refresh access token: invalid_grant (google: Token has been expired or revoked.)'
+      )
+    })
+
     describe('credentialAccountUserId + providerId path', () => {
       it('should reject unauthenticated requests', async () => {
         hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValueOnce({

apps/sim/app/api/auth/oauth/token/route.ts

@@ -12,6 +12,7 @@ import { AuthType, checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { TokenServiceAccountValidationError } from '@/lib/credentials/token-service-accounts/errors'
+import { OAuthRefreshError } from '@/lib/oauth/errors'
 import { captureServerEvent } from '@/lib/posthog/server'
 import {
   getCredential,
@@ -300,7 +301,11 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       )
     } catch (error) {
       logger.error(`[${requestId}] Failed to refresh access token:`, error)
-      return NextResponse.json({ error: 'Failed to refresh access token' }, { status: 401 })
+      const detail = error instanceof OAuthRefreshError ? `: ${error.message}` : ''
+      return NextResponse.json(
+        { error: `Failed to refresh access token${detail}` },
+        { status: 401 }
+      )
     }
   } catch (error) {
     logger.error(`[${requestId}] Error getting access token`, error)
@@ -410,8 +415,13 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
         },
         { status: 200 }
       )
-    } catch (_error) {
-      return NextResponse.json({ error: 'Failed to refresh access token' }, { status: 401 })
+    } catch (error) {
+      logger.error(`[${requestId}] Failed to refresh access token:`, error)
+      const detail = error instanceof OAuthRefreshError ? `: ${error.message}` : ''
+      return NextResponse.json(
+        { error: `Failed to refresh access token${detail}` },
+        { status: 401 }
+      )
     }
   } catch (error) {
     logger.error(`[${requestId}] Error fetching access token`, error)

apps/sim/app/api/auth/oauth/utils.test.ts

@@ -166,7 +166,28 @@ describe('OAuth Utils', () => {
 
       await expect(
         refreshTokenIfNeeded('request-id', mockCredential, 'credential-id')
-      ).rejects.toThrow('Failed to refresh token')
+      ).rejects.toThrow('invalid_grant (google)')
+    })
+
+    it('should preserve the provider error description in the thrown error', async () => {
+      const mockCredential = {
+        id: 'credential-id',
+        accessToken: 'expired-token',
+        refreshToken: 'refresh-token',
+        accessTokenExpiresAt: new Date(Date.now() - 3600 * 1000),
+        providerId: 'google',
+      }
+
+      mockRefreshOAuthToken.mockResolvedValueOnce({
+        ok: false,
+        errorCode: 'invalid_grant',
+        errorDescription: 'Token has been expired or revoked.',
+        message: 'Failed',
+      })
+
+      await expect(
+        refreshTokenIfNeeded('request-id', mockCredential, 'credential-id')
+      ).rejects.toThrow('invalid_grant (google: Token has been expired or revoked.)')
     })
 
     it('should not attempt refresh if no refresh token', async () => {
@@ -282,6 +303,121 @@ describe('OAuth Utils', () => {
     })
   })
 
+  describe('Slack installation-scoped refresh', () => {
+    const SLACK_ACCOUNT_ID = 'T08CM6ZNYBE-usr_U08USBQ9B1T-cbf46a7e-ca75-4a2e-bef5-fd467299eaae'
+    const past = new Date(Date.now() - 3600 * 1000)
+    const future = new Date(Date.now() + 3600 * 1000)
+
+    /** Select chain for getFreshestSlackChain: where() -> orderBy() -> limit(). */
+    function mockSelectOrderedChain(limitResult: unknown[]) {
+      const mockLimit = vi.fn().mockReturnValue(limitResult)
+      const mockOrderBy = vi.fn().mockReturnValue({ limit: mockLimit })
+      const mockWhere = vi.fn().mockReturnValue({ orderBy: mockOrderBy, limit: mockLimit })
+      const mockFrom = vi.fn().mockReturnValue({ where: mockWhere })
+      mockDb.select.mockReturnValueOnce({ from: mockFrom })
+      return { mockWhere, mockOrderBy, mockLimit }
+    }
+
+    function slackCredential(overrides: Record<string, unknown> = {}) {
+      return {
+        id: 'row-1',
+        resolvedCredentialId: 'row-1',
+        accountId: SLACK_ACCOUNT_ID,
+        accessToken: 'stale-at',
+        refreshToken: 'stale-rt',
+        accessTokenExpiresAt: past,
+        providerId: 'slack',
+        ...overrides,
+      }
+    }
+
+    it('locks per installation and refreshes with the freshest sibling refresh token', async () => {
+      mockSelectOrderedChain([
+        { accessToken: 'stale-at', refreshToken: 'live-rt', accessTokenExpiresAt: past },
+      ])
+      mockRefreshOAuthToken.mockResolvedValueOnce({
+        ok: true,
+        accessToken: 'new-at',
+        expiresIn: 43200,
+        refreshToken: 'new-rt',
+      })
+      const { mockSet } = mockUpdateChain()
+
+      const result = await refreshTokenIfNeeded('request-id', slackCredential(), 'row-1')
+
+      expect(result).toEqual({ accessToken: 'new-at', refreshed: true })
+      expect(redisConfigMockFns.mockAcquireLock.mock.calls[0][0]).toBe(
+        'oauth:refresh:slack:T08CM6ZNYBE'
+      )
+      expect(mockRefreshOAuthToken).toHaveBeenCalledWith('slack', 'live-rt')
+      expect(mockSet).toHaveBeenCalledWith(
+        expect.objectContaining({ accessToken: 'new-at', refreshToken: 'new-rt' })
+      )
+    })
+
+    it('returns the freshest sibling token without refreshing when it is still valid', async () => {
+      mockSelectOrderedChain([
+        { accessToken: 'sibling-at', refreshToken: 'live-rt', accessTokenExpiresAt: future },
+      ])
+      const { mockSet } = mockUpdateChain()
+
+      const result = await refreshTokenIfNeeded('request-id', slackCredential(), 'row-1')
+
+      expect(result).toEqual({ accessToken: 'sibling-at', refreshed: true })
+      expect(mockRefreshOAuthToken).not.toHaveBeenCalled()
+      expect(mockSet).toHaveBeenCalledWith(
+        expect.objectContaining({ accessToken: 'sibling-at', refreshToken: 'live-rt' })
+      )
+    })
+
+    it('keeps per-row behavior for pasted custom-bot account ids', async () => {
+      mockRefreshOAuthToken.mockResolvedValueOnce({
+        ok: true,
+        accessToken: 'new-at',
+        expiresIn: 43200,
+        refreshToken: 'new-rt',
+      })
+      mockUpdateChain()
+
+      const result = await refreshTokenIfNeeded(
+        'request-id',
+        slackCredential({ accountId: 'slack-bot-1764756583292' }),
+        'row-1'
+      )
+
+      expect(result).toEqual({ accessToken: 'new-at', refreshed: true })
+      expect(redisConfigMockFns.mockAcquireLock.mock.calls[0][0]).toBe('oauth:refresh:row-1')
+      expect(mockRefreshOAuthToken).toHaveBeenCalledWith('slack', 'stale-rt')
+    })
+
+    it('dead-flags the installation, not the row, on terminal refresh errors', async () => {
+      const fakeRedis = {
+        set: vi.fn().mockResolvedValue('OK'),
+        get: vi.fn().mockResolvedValue(null),
+        del: vi.fn().mockResolvedValue(1),
+      }
+      redisConfigMockFns.mockGetRedisClient.mockReturnValue(fakeRedis)
+      mockSelectOrderedChain([
+        { accessToken: 'stale-at', refreshToken: 'live-rt', accessTokenExpiresAt: past },
+      ])
+      mockRefreshOAuthToken.mockResolvedValueOnce({
+        ok: false,
+        errorCode: 'token_revoked',
+      })
+
+      await expect(refreshTokenIfNeeded('request-id', slackCredential(), 'row-1')).rejects.toThrow(
+        'token_revoked (slack)'
+      )
+
+      expect(fakeRedis.set).toHaveBeenCalledWith(
+        'oauth:dead:slack:T08CM6ZNYBE',
+        'token_revoked',
+        'EX',
+        3600
+      )
+    })
+  })
+
   describe('resolveServiceAccountToken', () => {
     it('throws loudly for an unknown provider (never silently attempts Google)', async () => {
       await expect(resolveServiceAccountToken('cred-1', 'mystery-provider')).rejects.toThrow(