feat(clerk-js): Add debugLogger for session token swap detection

[jacekradko]

Description

Add debug logging to detect server-side token swaps in multi-session scenarios (e.g., regular session + impersonation session with actor token). BAPI's refresh endpoint could return a token for a different session than the one requested — these logs give client-side visibility to detect this.

Logging added:

• Session.ts: After token resolves, check if returned token's sid claim matches the requesting session ID — logs a warning on mismatch (the token swap signal)
• AuthCookieService.ts: Log multi-session cookie updates (guarded by sessions.length > 1), 4xx token fetch errors with error code, and degraded status with error name
• clerk.ts: Log session state (active session ID, actor presence, total session count) when handleUnauthenticated triggers

Privacy considerations:

• Only logs opaque Clerk IDs (sess_xxx), booleans, counts, and error codes/names — no tokens, URLs, PII, or raw error messages
• Follows existing debugLogger patterns (same fields logged in tokenCache.ts, AuthCookieService.ts, etc.)
• Multi-session cookie logging is guarded to avoid noise on single-session clients

Checklist

• pnpm build runs as expected.
• pnpm test 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: Debug observability

[changeset-bot]

🦋 Changeset detected

Latest commit: 2774a75

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

This PR includes changesets to release 3 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-expo	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	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 27, 2026 1:40am

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch jacekradko/debug-token-swap

---

_{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@7945

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/elements

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

@clerk/clerk-expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/clerk-react

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

@clerk/react-router

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

@clerk/remix

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/themes

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

@clerk/types

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

@clerk/upgrade

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

@clerk/vue

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

commit: 2774a75