fix(backend): Improve satellite auth redirect failures

[jescalan]

Summary

Improves the debugging experience for production satellite-domain auth failures when the handshake redirect_url points at a host that is not associated with the instance, such as a dynamic preview deployment. FAPI now returns a dedicated host-scoped error for this case and renders a readable HTML response for document handshakes, while the backend SDK logs satellite-specific guidance when this condition turns into a redirect loop.

Changes in this repo

Updates the backend SDK handshake redirect-loop diagnostic to show satellite-domain and preview-deployment guidance for SatelliteCookieNeedsSyncing loops, with a focused authenticateRequest regression test.

Companion PRs

• clerk_go: https://github.com/clerk/clerk_go/pull/19088

Summary by CodeRabbit

Bug Fixes

• Improved satellite-domain diagnostics - Enhanced error messaging for satellite-domain redirect-loop detection, providing clearer guidance when cookie synchronization issues occur.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 12, 2026 9:57pm
swingset	Ready	Preview, Comment	Jun 12, 2026 9:57pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 155f856

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

This PR includes changesets to release 10 packages

Name	Type
@clerk/backend	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	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

[jescalan]

@codex review

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 68618679-bcd4-4bce-8ad4-cb6f09b69aa8

📥 Commits

Reviewing files that changed from the base of the PR and between b994202 and 155f856.

📒 Files selected for processing (3)

• .changeset/polite-satellites-wait.md
• packages/backend/src/tokens/__tests__/request.test.ts
• packages/backend/src/tokens/request.ts

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

• .changeset/polite-satellites-wait.md
• packages/backend/src/tokens/request.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/backend/src/tokens/tests/request.test.ts

---

📝 Walkthrough

Walkthrough

This PR extracts redirect-loop message generation into getHandshakeRedirectLoopMessage(reason) and uses it in authenticateRequest so the signed-out message is reason-aware (satellite-cookie-specific when reason === AuthErrorReason.SatelliteCookieNeedsSyncing, otherwise a generic message). It adds a vitest that simulates a satellite redirect loop asserting SignedOut with AuthErrorReason.SatelliteCookieNeedsSyncing and that console.log contains guidance substrings. The changeset documents a patch release for @clerk/backend noting improved diagnostics.

Satellite redirect-loop error messaging and testing

Layer / File(s)	Summary
Redirect-loop message helper and integration packages/backend/src/tokens/request.ts	Introduce getHandshakeRedirectLoopMessage(reason) and replace the hard-coded infinite-redirect message in authenticateRequest with a call to this helper.
Satellite redirect-loop test verification packages/backend/src/tokens/__tests__/request.test.ts	Add a vitest that simulates a satellite redirect loop (__clerk_synced=false, __clerk_redirect_count=3), expects SignedOut with AuthErrorReason.SatelliteCookieNeedsSyncing, and verifies three guidance console.log messages.
Changeset documentation .changeset/polite-satellites-wait.md	Bump @clerk/backend patch and add a release-note entry about improved satellite-domain redirect-loop diagnostics.

sequenceDiagram
  participant Client
  participant authenticateRequest
  participant getHandshakeRedirectLoopMessage
  participant Console
  Client->>authenticateRequest: request with __clerk_synced=false and __clerk_redirect_count=3
  authenticateRequest->>getHandshakeRedirectLoopMessage: getHandshakeRedirectLoopMessage(reason)
  getHandshakeRedirectLoopMessage-->>authenticateRequest: message string (satellite-specific or generic)
  authenticateRequest->>Console: console.log guidance messages

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

"I nibbled at a loop of redirects, polite and neat,
Found the handshake message and made it sweet.
A test tapped the drum with a cookie in tow,
Three little logs told the devs what to know.
Hops and hops — now the rabbit hops free 🐇"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(backend): Improve satellite auth redirect failures' accurately and concisely summarizes the main change—improving diagnostics and guidance for satellite-domain authentication redirect failures.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8636

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8636

@clerk/upgrade

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

@clerk/vue

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

commit: 155f856

[jescalan]

@codex review
@coderabbitai review

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Get the PR details and diff
gh pr view 8636 --repo clerk/javascript --json title,body,files,additions,deletions,changedFiles

# Get the diff
gh pr diff 8636 --repo clerk/javascript

Length of output: 5215

---

---

@jescalan: The changes look clean and focused. Here's my review:

---

packages/backend/src/tokens/request.ts

Correctness ✅ — The branching logic is correct. SatelliteCookieNeedsSyncing gets a targeted, actionable message while all other redirect-loop reasons fall back to the original generic message. No behavioral regression for non-satellite flows.

Minor: function placement — getHandshakeRedirectLoopMessage is declared (via hoisting) after its call site. While this is valid TypeScript, moving the function definition above its first use would improve readability:

// Define before use at line ~338
function getHandshakeRedirectLoopMessage(reason: string): string {
  if (reason === AuthErrorReason.SatelliteCookieNeedsSyncing) {
    return `Clerk: Satellite-domain authentication resulted in an infinite redirect loop. ...`;
  }
  return `Clerk: Refreshing the session token resulted in an infinite redirect loop. ...`;
}

const isRedirectLoop = handshakeService.checkAndTrackRedirectLoop(handshakeHeaders);
if (isRedirectLoop) {
  const msg = getHandshakeRedirectLoopMessage(reason);
  // ...
}

Optional: module-level extraction — Since the function doesn't close over any local variables, it could also be extracted to module level to avoid re-declaration on each authenticateRequest invocation. Low impact but cleaner.

---

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

Test coverage ✅ — The regression test is well-structured:

• Correctly uses __clerk_redirect_count: '3' + __clerk_synced=false + isSatellite: true to trigger the satellite redirect loop
• Asserts the full signed-out state (reason, isSatellite, domain, signInUrl)
• Verifies all three key substrings of the satellite guidance message
• Properly restores the spy with consoleSpy.mockRestore()

No issues with the test logic or assertions.

---

Summary

The PR achieves its goal with minimal surface area. The only actionable suggestion is readability-oriented (move the function definition above its call site). The test coverage is solid for the new branch. ✅

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-03T19:30:41.354Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	1
🟢 Additions	0

🤖 This report was reviewed by claude-sonnet-4-6.

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/testing ./cypress: Symbol not found for identifier: Cypress

---

@clerk/shared

Current version: 4.15.0
Recommended bump: MINOR → 4.16.0

Subpath ./apiUrlFromPublishableKey

🟡 Non-breaking Changes (1)

Modified: apiUrlFromPublishableKey

- apiUrlFromPublishableKey: (publishableKey: string) => "https://api.lclclerk.com" | "https://api.clerkstage.dev" | "https://api.clerk.com"
+ apiUrlFromPublishableKey: (publishableKey: string) => "https://api.clerk.com" | "https://api.lclclerk.com" | "https://api.clerkstage.dev"

Static analyzer: Breaking change in function apiUrlFromPublishableKey: Return type changed: "https://api.lclclerk.com"|"https://api.clerkstage.dev"|"https://api.clerk.com" → "https://api.clerk.com"|"https://api.lclclerk.com"|"https://api.clerkstage.dev"

🤖 AI review (reclassified as non-breaking) (99%): The union type contains exactly the same three string literal members; only their order changed, and TypeScript union member order is irrelevant to assignability or type-checking for consumers.

---

Report generated by Break Check

_{Last ran on b994202. Pushes that change no tracked declarations (no API surface change vs. base) are skipped and don't update this comment.}

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-12T21:59:26.593Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

Note
Break Check could not snapshot 1 subpath; the diff below excludes them.

• @clerk/astro ./env: ambient declaration file (no top-level import or export): API Extractor can only analyze module entry points, so this global-augmentation surface cannot be snapshotted; add the subpath to ignoreSubpaths to acknowledge it (API Extractor: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts)

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 155f856.}