fix(backend): Complete satellite domain sync

.changeset/tricky-pillows-juggle.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix infinite redirect loop in multi-domain development flows by reordering authentication checks to prioritize satellite sync requests over dev-browser-sync handshakes.

packages/backend/src/tokens/__tests__/request.test.ts

@@ -810,6 +810,32 @@ describe('tokens.authenticateRequest(options)', () => {
     expect(requestState.toAuth()).toBeNull();
   });
 
+  test('cookieToken: primary responds to syncing takes precedence over dev-browser-sync in multi-domain flow', async () => {
+    const sp = new URLSearchParams();
+    sp.set('__clerk_redirect_url', 'http://localhost:3001/dashboard');
+    sp.set('__clerk_db_jwt', mockJwt);
+    const requestUrl = `http://localhost:3000/sign-in?${sp.toString()}`;
+    const requestState = await authenticateRequest(
+      mockRequestWithCookies(
+        { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+        { __client_uat: '12345', __session: mockJwt, __clerk_db_jwt: mockJwt },
+        requestUrl,
+      ),
+      mockOptions({ secretKey: 'sk_test_deadbeef', isSatellite: false }),
+    );
+
+    expect(requestState).toMatchHandshake({
+      reason: AuthErrorReason.PrimaryRespondsToSyncing,
+    });
+    expect(requestState.message).toBe('');
+    expect(requestState.toAuth()).toBeNull();
+
+    const location = requestState.headers.get('location');
+    expect(location).toBeTruthy();
+    expect(location).toContain('localhost:3001/dashboard');
+    expect(location).toContain('__clerk_synced=true');
+  });
+
   test('cookieToken: returns signed out when no cookieToken and no clientUat in production [4y]', async () => {
     const requestState = await authenticateRequest(
       mockRequestWithCookies(),

packages/backend/src/tokens/request.ts

@@ -461,16 +461,6 @@ export const authenticateRequest: AuthenticateRequest = (async (
         }
       }
     }
-    /**
-     * Otherwise, check for "known unknown" auth states that we can resolve with a handshake.
-     */
-    if (
-      authenticateContext.instanceType === 'development' &&
-      authenticateContext.clerkUrl.searchParams.has(constants.QueryParameters.DevBrowser)
-    ) {
-      return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.DevBrowserSync, '');
-    }
-
     const isRequestEligibleForMultiDomainSync =
       authenticateContext.isSatellite && authenticateContext.secFetchDest === 'document';
 
@@ -500,7 +490,9 @@ export const authenticateRequest: AuthenticateRequest = (async (
       return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.SatelliteCookieNeedsSyncing, '', headers);
     }
 
-    // Multi-domain development sync flow
+    // Multi-domain development sync flow - primary responds to syncing
+    // IMPORTANT: This must come BEFORE dev-browser-sync check to avoid the root domain
+    // triggering its own handshakes when it's in the middle of handling a satellite sync request
     const redirectUrl = new URL(authenticateContext.clerkUrl).searchParams.get(
       constants.QueryParameters.ClerkRedirectUrl,
     );
@@ -524,6 +516,16 @@ export const authenticateRequest: AuthenticateRequest = (async (
      * End multi-domain sync flows
      */
 
+    /**
+     * Otherwise, check for "known unknown" auth states that we can resolve with a handshake.
+     */
+    if (
+      authenticateContext.instanceType === 'development' &&
+      authenticateContext.clerkUrl.searchParams.has(constants.QueryParameters.DevBrowser)
+    ) {
+      return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.DevBrowserSync, '');
+    }
+
     if (authenticateContext.instanceType === 'development' && !hasDevBrowserToken) {
       return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.DevBrowserMissing, '');
     }