fix(backend): Complete satellite domain sync

[jacekradko]

Description

When a satellite app initiated a multi-domain sync by redirecting to the root domain with __clerk_redirect_url, the root domain was incorrectly triggering its own dev-browser-sync handshake before completing the satellite's sync request. This caused an infinite redirect loop between domains.

Reordered the authentication checks so that when the root domain detects it's handling a multi-domain sync request (via __clerk_redirect_url), it immediately redirects back to the satellite with __clerk_synced=true and the dev browser token—without triggering its own handshakes first.

Fixes: USER-3522

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Refactor

  • Reordered authentication handshake checks so multi-domain synchronization is evaluated before dev-browser sync, preventing redundant handshakes and reducing redirect loops in multi-domain development flows.

• Tests

  • Added a test verifying primary-domain sync signals take precedence and produce the expected handshake result and redirect.

• Documentation

  • Added clarifying comments describing sync precedence in the authentication flow.

[changeset-bot]

🦋 Changeset detected

Latest commit: 080a183

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@clerk/backend	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Oct 18, 2025 2:17am

💡 Enable Vercel Agent with $100 free credit for automated AI reviews

[coderabbitai]

Walkthrough

Reordered the DevBrowserSync handshake check in the token request authentication flow so multi-domain (MD) development sync handling runs first; added comments clarifying MD sync precedence to avoid root-domain handshakes during satellite handling. DevBrowserSync handling is re-applied after MD checks and returns via handleMaybeHandshakeStatus when triggered.

Changes

Cohort / File(s)	Change Summary
Token request authentication flow packages/backend/src/tokens/request.ts	Moved the DevBrowserSync handshake check to execute after the multi-domain (MD) sync handling block; added comments explaining that MD dev-sync must precede DevBrowser handshakes to prevent root-domain handshakes during satellite handling. Restored the DevBrowserSync early return via handleMaybeHandshakeStatus at the new location.
Tests packages/backend/src/tokens/__tests__/request.test.ts	Added a test asserting that in a multi-domain flow a primary syncing signal (__clerk_db_jwt) takes precedence over dev-browser-sync, producing a handshake with reason PrimaryRespondsToSyncing and a redirect Location to the primary dashboard including __clerk_synced=true.
Release metadata .changeset/tricky-pillows-juggle.md	Added a changeset describing a patch fix for an infinite redirect loop in multi-domain development flows by reordering authentication checks to prioritize satellite sync requests over dev-browser-sync handshakes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Client
  participant AuthFn as authenticateRequest
  participant MDCheck as MultiDomainSyncCheck
  participant DevBrowser as DevBrowserSyncCheck
  participant Handshake as handleMaybeHandshakeStatus
  participant Response

  Client->>AuthFn: request with possible __clerk_db_jwt / dev sync params
  AuthFn->>MDCheck: evaluate multi-domain (primary/satellite) sync
  alt Primary sync present
    MDCheck-->>Handshake: PrimaryRespondsToSyncing
    Handshake-->>Response: redirect to primary with __clerk_synced=true
  else No primary sync
    MDCheck->>DevBrowser: evaluate dev-browser-sync
    alt DevBrowser handshake needed
      DevBrowser-->>Handshake: DevBrowser handshake
      Handshake-->>Response: handshake response
    else
      DevBrowser-->>AuthFn: continue normal dev-cookie / auth flow
      AuthFn-->>Response: normal authentication result
    end
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through code with ears alert and quick,
Moved MD first so handshakes won't conflict,
Primary sync answers, dev-browser waits in line,
No more loops — the redirects now align. 🥕✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "fix(backend): Complete satellite domain sync" is directly related to the changes in the pull request. The changeset addresses reordering authentication checks to prioritize satellite domain synchronization, which is exactly what the title describes. While the title could be more specific about the underlying problem (infinite redirect loop), it accurately captures the essence of the fix by referring to satellite domain sync, which is the core objective. The title is concise, clear, and would allow a teammate scanning history to understand that this is a backend fix related to satellite domain synchronization.
Linked Issues Check	✅ Passed	The code changes directly address all objectives from USER-3522. The modifications to request.ts reorder the authentication checks to prioritize multi-domain sync detection (via __clerk_redirect_url) over dev-browser-sync handshakes, preventing the root domain from initiating its own handshake before completing the satellite's sync request. The new test case in request.test.ts validates that the multi-domain sync flow with __clerk_db_jwt takes precedence, correctly resulting in a redirect with __clerk_synced=true to the primary domain. These changes implement the core fix required to stop the infinite redirect loop described in the issue by ensuring the root domain completes the multi-domain sync flow rather than triggering reciprocal redirects.
Out of Scope Changes Check	✅ Passed	All changes in the pull request are directly scoped to the objective of fixing the redirect loop in multi-domain development flows. The modifications to request.ts reorder authentication checks specifically to address the satellite sync issue, the test additions validate the corrected behavior, and the changeset documents the fix. There are no unrelated changes such as refactoring, unrelated bug fixes, cleanup tasks, or other work items present in this pull request. Every modification directly supports resolving USER-3522.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/localhost-satellite-sync

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 80a201a and 200b8a9.

📒 Files selected for processing (1)

• .changeset/tricky-pillows-juggle.md (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• .changeset/tricky-pillows-juggle.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: Build Packages
• GitHub Check: Formatting | Dedupe | Changeset
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: semgrep-cloud-platform/scan
• GitHub Check: semgrep-cloud-platform/scan

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7018

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7018

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7018

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7018

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7018

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7018

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@7018

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@7018

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7018

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7018

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7018

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7018

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7018

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7018

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@7018

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7018

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@7018

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7018

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7018

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7018

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@7018

@clerk/types

npm i https://pkg.pr.new/@clerk/types@7018

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7018

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7018

commit: 080a183