fix(backend,clerk-js): treat undefined satelliteAutoSync as false (#8001)

Author: nikosdouvlis

.changeset/fix-satellite-auto-sync-default.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/clerk-js": patch
+---
+
+Fix `satelliteAutoSync` to default to `false` as documented. Previously, not passing the prop resulted in `undefined`, which was treated as `true` due to a strict equality check (`=== false`). This preserved Core 2 auto-sync behavior instead of the intended Core 3 default. The check is now `!== true`, so both `undefined` and `false` skip automatic satellite sync.

integration/tests/handshake.test.ts

@@ -532,7 +532,7 @@ test.describe('Client handshake @generic', () => {
     expect(res.status).toBe(200);
   });
 
-  test('signed out satellite with sec-fetch-dest=document - prod', async () => {
+  test('signed out satellite with sec-fetch-dest=document skips handshake by default (satelliteAutoSync unset) - prod', async () => {
     const config = generateConfig({
       mode: 'live',
     });
@@ -546,13 +546,8 @@ test.describe('Client handshake @generic', () => {
       }),
       redirect: 'manual',
     });
-    expect(res.status).toBe(307);
-    const locationUrl = new URL(res.headers.get('location'));
-    expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
-    expect(locationUrl.searchParams.get('redirect_url')).toBe(`${app.serverUrl}/`);
-    expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
-    expect(locationUrl.searchParams.has('__clerk_api_version')).toBe(true);
-    expect(locationUrl.searchParams.get('suffixed_cookies')).toBe('false');
+    // In Core 3, satelliteAutoSync defaults to false, so no handshake redirect
+    expect(res.status).toBe(200);
   });
 
   test('signed out satellite - dev', async () => {
@@ -631,7 +626,28 @@ test.describe('Client handshake @generic', () => {
     expect(res.status).toBe(200);
   });
 
-  test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+  test('signed out satellite with satelliteAutoSync unset triggers handshake when __clerk_synced=false - prod', async () => {
+    const config = generateConfig({
+      mode: 'live',
+    });
+    const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+      headers: new Headers({
+        'X-Publishable-Key': config.pk,
+        'X-Secret-Key': config.sk,
+        'X-Satellite': 'true',
+        'X-Domain': 'example.com',
+        'Sec-Fetch-Dest': 'document',
+      }),
+      redirect: 'manual',
+    });
+    // Even without satelliteAutoSync, __clerk_synced=false (post sign-in) should trigger handshake
+    expect(res.status).toBe(307);
+    const locationUrl = new URL(res.headers.get('location'));
+    expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+    expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+  });
+
+  test('signed out satellite with satelliteAutoSync=true (explicit opt-in) triggers handshake - prod', async () => {
     const config = generateConfig({
       mode: 'live',
     });
@@ -646,7 +662,7 @@ test.describe('Client handshake @generic', () => {
       }),
       redirect: 'manual',
     });
-    // Should redirect to handshake with default/true satelliteAutoSync
+    // Should redirect to handshake when satelliteAutoSync is explicitly true
     expect(res.status).toBe(307);
     const locationUrl = new URL(res.headers.get('location'));
     expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');

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

@@ -651,7 +651,7 @@ describe('tokens.authenticateRequest(options)', () => {
     expect(requestState).toBeSignedOutToAuth();
   });
 
-  test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite and not is synced [11y]', async () => {
+  test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite with satelliteAutoSync=true and not is synced [11y]', async () => {
     server.use(
       http.get('https://api.clerk.test/v1/jwks', () => {
         return HttpResponse.json(mockJwks);
@@ -671,6 +671,7 @@ describe('tokens.authenticateRequest(options)', () => {
         isSatellite: true,
         signInUrl: 'https://primary.dev/sign-in',
         domain: 'satellite.dev',
+        satelliteAutoSync: true,
       }),
     );
 
@@ -684,7 +685,7 @@ describe('tokens.authenticateRequest(options)', () => {
     expect(requestState.toAuth()).toBeNull();
   });
 
-  test('cookieToken: redirects to signInUrl when is satellite dev and not synced', async () => {
+  test('cookieToken: redirects to signInUrl when is satellite dev with satelliteAutoSync=true and not synced', async () => {
     server.use(
       http.get('https://api.clerk.test/v1/jwks', () => {
         return HttpResponse.json(mockJwks);
@@ -705,6 +706,7 @@ describe('tokens.authenticateRequest(options)', () => {
         isSatellite: true,
         signInUrl: 'https://primary.dev/sign-in',
         domain: 'satellite.dev',
+        satelliteAutoSync: true,
       }),
     );
 
@@ -873,6 +875,114 @@ describe('tokens.authenticateRequest(options)', () => {
     expect(requestState.toAuth()).toBeSignedOutToAuth();
   });
 
+  test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - prod', async () => {
+    const requestState = await authenticateRequest(
+      mockRequestWithCookies(
+        { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+        { __client_uat: '0' },
+        `http://satellite.example/path`,
+      ),
+      mockOptions({
+        secretKey: 'deadbeef',
+        publishableKey: PK_LIVE,
+        signInUrl: 'https://primary.example/sign-in',
+        isSatellite: true,
+        domain: 'satellite.example',
+      }),
+    );
+
+    expect(requestState).toBeSignedOut({
+      reason: AuthErrorReason.SessionTokenAndUATMissing,
+      isSatellite: true,
+      domain: 'satellite.example',
+      signInUrl: 'https://primary.example/sign-in',
+    });
+    expect(requestState.toAuth()).toBeSignedOutToAuth();
+    expect(requestState.headers.get('location')).toBeNull();
+  });
+
+  test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - dev', async () => {
+    const requestState = await authenticateRequest(
+      mockRequestWithCookies(
+        { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+        {
+          __client_uat: '0',
+          __clerk_db_jwt: mockJwt,
+        },
+      ),
+      mockOptions({
+        secretKey: 'sk_test_deadbeef',
+        publishableKey: PK_TEST,
+        isSatellite: true,
+        signInUrl: 'https://primary.dev/sign-in',
+        domain: 'satellite.dev',
+      }),
+    );
+
+    expect(requestState).toBeSignedOut({
+      reason: AuthErrorReason.SessionTokenAndUATMissing,
+      isSatellite: true,
+      domain: 'satellite.dev',
+      signInUrl: 'https://primary.dev/sign-in',
+    });
+    expect(requestState.toAuth()).toBeSignedOutToAuth();
+    expect(requestState.headers.get('location')).toBeNull();
+  });
+
+  test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - prod', async () => {
+    const requestState = await authenticateRequest(
+      mockRequestWithCookies(
+        { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+        { __client_uat: '0' },
+        `http://satellite.example/path?__clerk_synced=false`,
+      ),
+      mockOptions({
+        secretKey: 'deadbeef',
+        publishableKey: PK_LIVE,
+        signInUrl: 'https://primary.example/sign-in',
+        isSatellite: true,
+        domain: 'satellite.example',
+      }),
+    );
+
+    expect(requestState).toMatchHandshake({
+      reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+      isSatellite: true,
+      domain: 'satellite.example',
+      signInUrl: 'https://primary.example/sign-in',
+    });
+  });
+
+  test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - dev', async () => {
+    const requestState = await authenticateRequest(
+      mockRequestWithCookies(
+        { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+        {
+          __client_uat: '0',
+          __clerk_db_jwt: mockJwt,
+        },
+        `http://satellite.dev/path?__clerk_synced=false`,
+      ),
+      mockOptions({
+        secretKey: 'sk_test_deadbeef',
+        publishableKey: PK_TEST,
+        signInUrl: 'https://primary.dev/sign-in',
+        isSatellite: true,
+        domain: 'satellite.dev',
+      }),
+    );
+
+    expect(requestState).toMatchHandshake({
+      reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+      isSatellite: true,
+      domain: 'satellite.dev',
+      signInUrl: 'https://primary.dev/sign-in',
+    });
+    expect(requestState.headers.get('location')).toEqual(
+      `https://primary.dev/sign-in?__clerk_redirect_url=http%3A%2F%2Fexample.com%2Fpath%3F__clerk_synced%3Dfalse`,
+    );
+  });
+
   test('cookieToken: returns handshake when app is not satellite and responds to syncing on dev instances[12y]', async () => {
     const sp = new URLSearchParams();
     sp.set('__clerk_redirect_url', 'http://localhost:3000');

packages/backend/src/tokens/request.ts

@@ -484,7 +484,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
      * - 'false' (NeedsSync): Trigger sync - satellite returning from primary sign-in
      * - 'true' (Completed): Sync done - prevents re-sync loop
      *
-     * With satelliteAutoSync=false:
+     * With satelliteAutoSync=false or unset (Core 3 default):
      * - Skip handshake on first visit if no cookies exist (return signedOut immediately)
      * - Trigger handshake when __clerk_synced=false is present (post sign-in redirect)
      * - Allow normal token verification flow when cookies exist (enables refresh)
@@ -499,8 +499,8 @@ export const authenticateRequest: AuthenticateRequest = (async (
     const hasCookies = hasSessionToken || hasActiveClient;
 
     // Determine if we should skip handshake for satellites with no cookies
-    // satelliteAutoSync defaults to true, so we only skip when explicitly set to false
-    const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync === false && !hasCookies && !needsSync;
+    // satelliteAutoSync defaults to false (Core 3), so we skip unless explicitly set to true
+    const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync !== true && !hasCookies && !needsSync;
 
     if (authenticateContext.instanceType === 'production' && isRequestEligibleForMultiDomainSync && !syncCompleted) {
       // With satelliteAutoSync=false: skip handshake if no cookies and no sync trigger

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2386,6 +2386,7 @@ describe('Clerk singleton', () => {
   describe('Clerk().isSatellite and Clerk().domain getters', () => {
     beforeEach(() => {
       mockClientFetch.mockReset();
+      mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [] }));
       mockEnvironmentFetch.mockReturnValue(
         Promise.resolve({
           authConfig: {},

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -116,7 +116,7 @@ export class AuthCookieService {
     if (!this.clerk.loaded) {
       return this.clientUat.get() <= 0;
     }
-    return !!this.clerk.user;
+    return !this.clerk.user;
   }
 
   public async handleUnauthenticatedDevBrowser() {

packages/clerk-js/src/core/clerk.ts

@@ -2860,10 +2860,9 @@ export class Clerk implements ClerkInterface {
       return true;
     }
 
-    // Check if satelliteAutoSync is disabled - if so, skip automatic sync
-    // unless explicitly triggered via __clerk_synced=false
-    if (this.#options.satelliteAutoSync === false) {
-      // Skip automatic sync when satelliteAutoSync is false
+    // Check if satelliteAutoSync is enabled - only auto-sync when explicitly opted in
+    // In Core 3, satelliteAutoSync defaults to false (undefined is treated as false)
+    if (this.#options.satelliteAutoSync !== true) {
       return false;
     }