fix(credentials): cover OAuth handoff edge cases

Author: TheodoreSpeaks

apps/desktop/src/main/handoff.test.ts

@@ -249,14 +249,17 @@ describe('createHandoffManager', () => {
     const manager = createHandoffManager(deps, makeCallbacks())
     await manager.beginConnect('google-email', {
       workspaceId: 'workspace-1',
+      draftId: 'draft-1',
       chatAttemptId: 'attempt-1',
     })
-    const state = new URL(vi.mocked(deps.openExternal).mock.calls[0][0]).searchParams.get(
-      'state'
-    ) as string
+    const landing = new URL(vi.mocked(deps.openExternal).mock.calls[0][0])
+    const state = landing.searchParams.get('state') as string
+
+    expect(landing.searchParams.get('draftId')).toBe('draft-1')
 
     expect(manager.consumeConnect(state)).toEqual({
       workspaceId: 'workspace-1',
+      draftId: 'draft-1',
       chatAttemptId: 'attempt-1',
     })
     expect(manager.consumeConnect(state)).toBeNull()

apps/desktop/src/main/handoff.ts

@@ -67,6 +67,7 @@ export interface HandoffManagerDeps {
 export interface ConnectScope {
   workspaceId?: string
   credentialId?: string
+  draftId?: string
   chatAttemptId?: string
 }
 
@@ -292,6 +293,7 @@ export function createHandoffManager(
           ...(userId ? { user: userId } : {}),
           ...(scope.workspaceId ? { workspaceId: scope.workspaceId } : {}),
           ...(scope.credentialId ? { credentialId: scope.credentialId } : {}),
+          ...(scope.draftId ? { draftId: scope.draftId } : {}),
         },
         scope
       )

apps/desktop/src/main/ipc.test.ts

@@ -335,21 +335,24 @@ describe('registerIpcHandlers', () => {
     expect(await handler?.(appEvent, 'slack')).toBe(true)
     expect(deps.beginOAuthConnect).toHaveBeenCalledWith('slack', {})
 
-    // Chip-initiated connects carry workspace/credential scope; malformed
+    // Connects carry workspace/credential or exact-draft scope; malformed
     // scopes (wrong types, unsafe ids) are rejected before the handoff.
     expect(
       await handler?.(appEvent, 'slack', {
         workspaceId: 'ws1',
         credentialId: 'cred_1',
+        draftId: 'draft_1',
         chatAttemptId: 'attempt_1',
       })
     ).toBe(true)
     expect(deps.beginOAuthConnect).toHaveBeenCalledWith('slack', {
       workspaceId: 'ws1',
       credentialId: 'cred_1',
+      draftId: 'draft_1',
       chatAttemptId: 'attempt_1',
     })
     expect(await handler?.(appEvent, 'slack', { workspaceId: 'ws/../evil' })).toBe(false)
+    expect(await handler?.(appEvent, 'slack', { draftId: '../wrong' })).toBe(false)
     expect(await handler?.(appEvent, 'slack', { chatAttemptId: '../wrong' })).toBe(false)
     expect(await handler?.(appEvent, 'slack', 'not-an-object')).toBe(false)
   })

apps/desktop/src/main/ipc.ts

@@ -95,6 +95,7 @@ function parseDesktopScope(raw: unknown): string | null {
 export interface OAuthConnectScope {
   workspaceId?: string
   credentialId?: string
+  draftId?: string
   chatAttemptId?: string
 }
 
@@ -110,9 +111,10 @@ export function parseOAuthConnectScope(raw: unknown): OAuthConnectScope | undefi
   if (typeof raw !== 'object') {
     return undefined
   }
-  const { workspaceId, credentialId, chatAttemptId } = raw as {
+  const { workspaceId, credentialId, draftId, chatAttemptId } = raw as {
     workspaceId?: unknown
     credentialId?: unknown
+    draftId?: unknown
     chatAttemptId?: unknown
   }
   if (
@@ -127,6 +129,9 @@ export function parseOAuthConnectScope(raw: unknown): OAuthConnectScope | undefi
   ) {
     return undefined
   }
+  if (draftId !== undefined && (typeof draftId !== 'string' || !ID_PATTERN.test(draftId))) {
+    return undefined
+  }
   if (
     chatAttemptId !== undefined &&
     (typeof chatAttemptId !== 'string' || !ID_PATTERN.test(chatAttemptId))
@@ -136,6 +141,7 @@ export function parseOAuthConnectScope(raw: unknown): OAuthConnectScope | undefi
   return {
     ...(workspaceId !== undefined ? { workspaceId } : {}),
     ...(credentialId !== undefined ? { credentialId } : {}),
+    ...(draftId !== undefined ? { draftId } : {}),
     ...(chatAttemptId !== undefined ? { chatAttemptId } : {}),
   }
 }

apps/sim/app/desktop/connect/page.tsx

@@ -50,8 +50,16 @@ export default async function DesktopConnectPage({ searchParams }: DesktopConnec
   const port = parseLoopbackPort(typeof params.port === 'string' ? params.port : '')
   const workspaceId = isValidOpaqueId(params.workspaceId) ? params.workspaceId : undefined
   const credentialId = isValidOpaqueId(params.credentialId) ? params.credentialId : undefined
+  const draftId = isValidOpaqueId(params.draftId) ? params.draftId : undefined
   const expectedUserId = isValidOpaqueId(params.user) ? params.user : undefined
-  if (!isValidOAuthProviderId(providerId) || !isValidHandoffState(state) || port === null) {
+  const hasInvalidDraftId = params.draftId !== undefined && draftId === undefined
+  if (
+    !isValidOAuthProviderId(providerId) ||
+    !isValidHandoffState(state) ||
+    port === null ||
+    hasInvalidDraftId ||
+    (workspaceId !== undefined && draftId !== undefined)
+  ) {
     return <InvalidRequest />
   }
 
@@ -65,6 +73,7 @@ export default async function DesktopConnectPage({ searchParams }: DesktopConnec
         buildDesktopConnectPath(providerId, state, port, {
           workspaceId,
           credentialId,
+          draftId,
           user: expectedUserId,
         })
       )}`
@@ -86,6 +95,7 @@ export default async function DesktopConnectPage({ searchParams }: DesktopConnec
           returnTo={buildDesktopConnectPath(providerId, state, port, {
             workspaceId,
             credentialId,
+            draftId,
             user: expectedUserId,
           })}
         />
@@ -113,6 +123,9 @@ export default async function DesktopConnectPage({ searchParams }: DesktopConnec
   }
 
   return (
-    <ConnectLauncher providerId={providerId} completePath={buildConnectCompletePath(state, port)} />
+    <ConnectLauncher
+      providerId={providerId}
+      completePath={buildConnectCompletePath(state, port, draftId)}
+    />
   )
 }

apps/sim/app/desktop/connect/validation.test.ts

@@ -2,6 +2,7 @@
  * @vitest-environment node
  */
 import { describe, expect, it } from 'vitest'
+import { OAUTH_CREDENTIAL_DRAFT_CALLBACK_PARAM } from '@/lib/credentials/draft-constants'
 import {
   buildConnectCompletePath,
   buildConnectLoopbackUrl,
@@ -36,19 +37,23 @@ describe('sanitizeOAuthErrorSlug', () => {
 
 describe('URL builders', () => {
   it('buildDesktopConnectPath round-trips provider, state, and port', () => {
-    const path = buildDesktopConnectPath('google-email', STATE, 49152)
+    const path = buildDesktopConnectPath('google-email', STATE, 49152, {
+      draftId: 'draft-1',
+    })
     const url = new URL(path, 'https://sim.ai')
     expect(url.pathname).toBe('/desktop/connect')
     expect(url.searchParams.get('provider')).toBe('google-email')
     expect(url.searchParams.get('state')).toBe(STATE)
     expect(url.searchParams.get('port')).toBe('49152')
+    expect(url.searchParams.get('draftId')).toBe('draft-1')
   })
 
-  it('buildConnectCompletePath carries state and port', () => {
-    const url = new URL(buildConnectCompletePath(STATE, 49152), 'https://sim.ai')
+  it('buildConnectCompletePath carries state, port, and the exact credential draft', () => {
+    const url = new URL(buildConnectCompletePath(STATE, 49152, 'draft-1'), 'https://sim.ai')
     expect(url.pathname).toBe('/desktop/connect/complete')
     expect(url.searchParams.get('state')).toBe(STATE)
     expect(url.searchParams.get('port')).toBe('49152')
+    expect(url.searchParams.get(OAUTH_CREDENTIAL_DRAFT_CALLBACK_PARAM)).toBe('draft-1')
   })
 
   it('buildConnectLoopbackUrl targets the 127.0.0.1 connect callback, error optional', () => {

apps/sim/app/desktop/connect/validation.ts

@@ -1,3 +1,5 @@
+import { OAUTH_CREDENTIAL_DRAFT_CALLBACK_PARAM } from '@/lib/credentials/draft-constants'
+
 /**
  * OAuth providerIds are kebab-case service slugs (e.g. "google-email"). The
  * value is only used to start a better-auth oauth2.link flow, which validates
@@ -36,6 +38,7 @@ export function isValidOpaqueId(value: unknown): value is string {
 export interface ConnectScope {
   workspaceId?: string
   credentialId?: string
+  draftId?: string
   /** The account the desktop app is signed in as; the flow is pinned to it. */
   user?: string
 }
@@ -53,6 +56,7 @@ export function buildDesktopConnectPath(
   const params = new URLSearchParams({ provider: providerId, state, port: String(port) })
   if (scope.workspaceId) params.set('workspaceId', scope.workspaceId)
   if (scope.credentialId) params.set('credentialId', scope.credentialId)
+  if (scope.draftId) params.set('draftId', scope.draftId)
   if (scope.user) params.set('user', scope.user)
   return `/desktop/connect?${params.toString()}`
 }
@@ -61,8 +65,9 @@ export function buildDesktopConnectPath(
  * The same-origin path better-auth redirects the browser to after the OAuth
  * callback — the complete page then bounces to the desktop app's loopback.
  */
-export function buildConnectCompletePath(state: string, port: number): string {
+export function buildConnectCompletePath(state: string, port: number, draftId?: string): string {
   const params = new URLSearchParams({ state, port: String(port) })
+  if (draftId) params.set(OAUTH_CREDENTIAL_DRAFT_CALLBACK_PARAM, draftId)
   return `/desktop/connect/complete?${params.toString()}`
 }
 

apps/sim/app/workspace/[workspaceId]/components/connect-oauth-modal/connect-oauth-modal.tsx

@@ -285,7 +285,11 @@ export function ConnectOAuthModal(props: ConnectOAuthModalProps) {
             .filter(
               (credential) => credential.type === 'oauth' && credential.providerId === providerId
             )
-            .map((credential) => ({ id: credential.id, accountId: credential.accountId })),
+            .map((credential) => ({
+              id: credential.id,
+              accountId: credential.accountId,
+              updatedAt: credential.updatedAt,
+            })),
           workspaceId,
           requestedAt: Date.now(),
         }

apps/sim/hooks/queries/oauth/oauth-connections.ts

@@ -180,7 +180,10 @@ export function useConnectOAuthService() {
       // which refreshes caches and shows the connected toast.
       const desktopBridge = getDesktopBridge()
       if (desktopBridge?.beginOAuthConnect) {
-        const opened = await desktopBridge.beginOAuthConnect(providerId)
+        const opened = await desktopBridge.beginOAuthConnect(
+          providerId,
+          draftId ? { draftId } : undefined
+        )
         if (!opened) {
           throw new Error('Could not open your browser to connect this account.')
         }

apps/sim/hooks/use-oauth-return.test.ts

@@ -0,0 +1,85 @@
+/**
+ * @vitest-environment node
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  requestJson: vi.fn(),
+  requireWorkspaceCredentialListResponse: vi.fn(),
+}))
+
+vi.mock('@sim/emcn', () => ({
+  toast: { error: vi.fn(), success: vi.fn() },
+}))
+vi.mock('next/navigation', () => ({
+  useParams: vi.fn(),
+  useRouter: vi.fn(),
+}))
+vi.mock('@/lib/api/client/request', () => ({ requestJson: mocks.requestJson }))
+vi.mock('@/hooks/queries/utils/fetch-workspace-credentials', () => ({
+  requireWorkspaceCredentialListResponse: mocks.requireWorkspaceCredentialListResponse,
+}))
+
+import type { OAuthReturnContext } from '@/lib/credentials/client-state'
+import { resolveOAuthMessage } from '@/hooks/use-oauth-return'
+
+const context: OAuthReturnContext = {
+  origin: 'integrations',
+  displayName: 'New Gmail',
+  providerId: 'google-email',
+  preCount: 1,
+  baselineCredentials: [
+    {
+      id: 'credential-existing',
+      accountId: 'account-1',
+      updatedAt: '2026-08-14T17:00:00.000Z',
+    },
+  ],
+  workspaceId: 'workspace-1',
+  requestedAt: Date.now(),
+}
+
+const existingCredential = {
+  id: 'credential-existing',
+  workspaceId: 'workspace-1',
+  type: 'oauth' as const,
+  displayName: 'Existing Gmail',
+  description: null,
+  providerId: 'google-email',
+  accountId: 'account-1',
+  envKey: null,
+  envOwnerUserId: null,
+  createdBy: 'user-1',
+  createdAt: '2026-08-01T00:00:00.000Z',
+  updatedAt: '2026-08-14T18:00:00.000Z',
+}
+
+describe('resolveOAuthMessage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.requestJson.mockResolvedValue({})
+  })
+
+  it('recognizes an idempotent already-connected account from its reconnect timestamp', async () => {
+    mocks.requireWorkspaceCredentialListResponse.mockReturnValue([existingCredential])
+
+    await expect(resolveOAuthMessage(context)).resolves.toEqual({
+      kind: 'success',
+      text: 'This account is already connected as "Existing Gmail".',
+    })
+  })
+
+  it('does not report success when the credential list is unchanged', async () => {
+    mocks.requireWorkspaceCredentialListResponse.mockReturnValue([
+      {
+        ...existingCredential,
+        updatedAt: context.baselineCredentials?.[0].updatedAt,
+      },
+    ])
+
+    await expect(resolveOAuthMessage(context)).resolves.toEqual({
+      kind: 'error',
+      text: 'We couldn’t verify the "New Gmail" connection. Try again.',
+    })
+  })
+})