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

Add debug logging to detect server-side token swaps in multi-session scenarios:
- Session.ts: Check if returned token's sid matches requested session (token swap detection)
- AuthCookieService.ts: Log multi-session cookie updates to track active session
- AuthCookieService.ts: Log token fetch errors (4xx and degraded status)
- clerk.ts: Log session state before unauthenticated flow to see active sessions

Author: jacekradko

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

@@ -177,6 +177,15 @@ export class AuthCookieService {
       return;
     }
 
+    const sessions = (this.clerk.client as any)?.sessions;
+    if (sessions?.length > 1 && token) {
+      debugLogger.info(
+        'Updating session cookie (multi-session client)',
+        { activeSessionId: this.clerk.session?.id, sessionCount: sessions.length, hasActor: !!this.clerk.session?.actor },
+        'authCookieService',
+      );
+    }
+
     if (!token && !isValidBrowserOnline()) {
       debugLogger.warn('Removing session cookie (offline)', { sessionId: this.clerk.session?.id }, 'authCookieService');
     }
@@ -205,17 +214,23 @@ export class AuthCookieService {
 
     //sign user out if a 4XX error
     if (is4xxError(e)) {
+      debugLogger.warn(
+        'Token fetch failed with 4xx, triggering unauthenticated flow',
+        { errorCode: isClerkAPIResponseError(e) ? e.errors[0]?.code : undefined, sessionId: this.clerk.session?.id },
+        'authCookieService',
+      );
       void this.clerk.handleUnauthenticated().catch(noop);
       return;
     }
 
     // The poller failed to fetch a fresh session token, update status to `degraded`.
     this.clerkEventBus.emit(clerkEvents.Status, 'degraded');
 
-    // --------
-    // Treat any other error as a noop
-    // TODO(debug-logs): Once debug logs is available log this error.
-    // --------
+    debugLogger.warn(
+      'Token fetch failed, status degraded',
+      { error: e?.message || String(e), sessionId: this.clerk.session?.id },
+      'authCookieService',
+    );
   }
 
   private handleSignOut() {

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

@@ -2347,6 +2347,16 @@ export class Clerk implements ClerkInterface {
     if (!this.client || !this.session) {
       return;
     }
+    debugLogger.warn(
+      'handleUnauthenticated triggered',
+      {
+        activeSessionId: this.session.id,
+        hasActor: !!this.session.actor,
+        totalSessions: this.client.sessions.length,
+        signedInSessions: this.client.signedInSessions.map(s => ({ id: s.id, hasActor: !!s.actor })),
+      },
+      'clerk',
+    );
     try {
       const newClient = await Client.getOrCreateInstance().fetch();
       this.updateClient(newClient);

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

@@ -413,6 +413,15 @@ export class Session extends BaseResource implements SessionResource {
     SessionTokenCache.set({ tokenId, tokenResolver });
 
     return tokenResolver.then(token => {
+      const returnedSid = token.jwt?.claims?.sid;
+      if (returnedSid && returnedSid !== this.id) {
+        debugLogger.warn(
+          'Token session mismatch: requested token for one session but received token for another',
+          { requestedSessionId: this.id, returnedSessionId: returnedSid, tokenId, hasActor: !!this.actor },
+          'session',
+        );
+      }
+
       if (shouldDispatchTokenUpdate) {
         eventBus.emit(events.TokenUpdate, { token });