fix(auth): getSession self-heals a stale bearer shadowing a valid cookie session (#1683)

A leftover auth-session-token in localStorage is injected on every auth
call and SHADOWS a fresh cookie session — SSO landings (cloud console
sso-exchange into a tenant env) only set the cookie and cannot touch
the target origin's localStorage, so affected users bounce back to the
login page forever (staging repro: env open → cloud login page).

On a bearer get-session miss, retry once cookie-only:
- live cookie session → adopt it, its token replaces the stale one
- affirmative double-miss (200 + no session) → drop the dead token
- transport errors → keep the token (they prove nothing) and return
  null instead of throwing (better-fetch rethrows network errors)

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

.changeset/stale-bearer-selfheal.md

@@ -0,0 +1,5 @@
+---
+"@object-ui/auth": patch
+---
+
+getSession self-heals a stale localStorage bearer: an invalid `auth-session-token` used to SHADOW a perfectly valid cookie session — SSO landings (e.g. the cloud console's sso-exchange into a tenant environment) only set the cookie and cannot touch the target origin's localStorage, so users with a leftover token bounced back to the login page forever. On a bearer get-session miss the client now retries once cookie-only: a live cookie session wins (its token replaces the stale one); an affirmative double-miss drops the dead token; transport errors keep it. getSession also no longer throws on network errors (better-fetch rethrows them).

packages/auth/src/__tests__/createAuthClient.test.ts

@@ -144,6 +144,58 @@ describe('createAuthClient', () => {
     expect(result?.user.id).toBe('1');
   });
 
+  it('getSession self-heals a stale bearer: cookie session wins and replaces the token', async () => {
+    const { TokenStorage } = await import('../createAuthClient');
+    TokenStorage.set('stale-token');
+    const session = { token: 'fresh-cookie-token', id: 's9', userId: '1', expiresAt: '2027-01-01' };
+    const user = { id: '1', name: 'Jack', email: 'jack@test.com' };
+    // Bearer-carrying call sees no session (stale token); the cookie-only
+    // retry (no Authorization header) sees the live SSO session.
+    const mockFn = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+      const headers = new Headers(init?.headers);
+      const hasBearer = Boolean(headers.get('Authorization'));
+      const body = hasBearer ? null : { user, session };
+      return new Response(JSON.stringify(body), { status: 200, headers: { 'Content-Type': 'application/json' } });
+    });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
+
+    const result = await client.getSession();
+
+    expect(result?.user.id).toBe('1');
+    expect(result?.session.token).toBe('fresh-cookie-token');
+    // The stale token was replaced by the live session's token.
+    expect(TokenStorage.get()).toBe('fresh-cookie-token');
+    TokenStorage.clear();
+  });
+
+  it('getSession drops a dead bearer when the cookie has no session either', async () => {
+    const { TokenStorage } = await import('../createAuthClient');
+    TokenStorage.set('dead-token');
+    // Both the bearer call and the cookie-only retry affirmatively report
+    // "no session" (200 + null) — the stored token is dead weight.
+    const mockFn = vi.fn(async () =>
+      new Response(JSON.stringify(null), { status: 200, headers: { 'Content-Type': 'application/json' } }));
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
+
+    const result = await client.getSession();
+
+    expect(result).toBeNull();
+    expect(TokenStorage.get()).toBeNull();
+  });
+
+  it('getSession keeps the bearer on transport errors (proves nothing about validity)', async () => {
+    const { TokenStorage } = await import('../createAuthClient');
+    TokenStorage.set('maybe-good-token');
+    const mockFn = vi.fn(async () => { throw new Error('network down'); });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
+
+    const result = await client.getSession();
+
+    expect(result).toBeNull();
+    expect(TokenStorage.get()).toBe('maybe-good-token');
+    TokenStorage.clear();
+  });
+
   it('getSession returns null on failure', async () => {
     const { mockFn } = createMockFetch({
       '/get-session': { status: 401, body: { message: 'Unauthorized' } },

packages/auth/src/createAuthClient.ts

@@ -274,14 +274,57 @@ export function createAuthClient(config: AuthClientConfig): AuthClient {
     },
 
     async getSession() {
-      const { data, error } = await betterAuth.getSession();
-      if (error || !data) return null;
-      const payload = data as unknown as { user: AuthUser; session: AuthSession };
-      // Keep localStorage in sync if the server returns a fresh token
-      if (payload.session?.token) {
-        TokenStorage.set(payload.session.token);
+      // better-fetch RETHROWS transport errors (it does not wrap them in
+      // `{ error }`); a network hiccup must read as "signed out for now",
+      // not an exception in every AuthProvider boot.
+      let data: unknown = null;
+      try {
+        const res = await betterAuth.getSession();
+        if (!res.error) data = res.data;
+      } catch { /* transport error — fall through to the retry/null path */ }
+      if (data) {
+        const payload = data as unknown as { user: AuthUser; session: AuthSession };
+        // Keep localStorage in sync if the server returns a fresh token
+        if (payload.session?.token) {
+          TokenStorage.set(payload.session.token);
+        }
+        return { user: payload.user, session: payload.session };
       }
-      return { user: payload.user, session: payload.session };
+
+      // Stale-bearer self-heal: every request injects the localStorage
+      // bearer, and an INVALID bearer shadows a perfectly valid cookie
+      // session. SSO landings (e.g. the cloud console's sso-exchange into a
+      // tenant environment) only set the cookie — they cannot touch this
+      // origin's localStorage — so a leftover token from an earlier login
+      // bounces a freshly signed-in user back to the login page forever.
+      // Retry once WITHOUT the bearer: a cookie session means the stored
+      // token was stale — adopt the live session (and its token) instead.
+      if (TokenStorage.get()) {
+        try {
+          const rawFetch = fetchFn || globalThis.fetch.bind(globalThis);
+          const resp = await rawFetch(`${origin}${basePath}/get-session`, {
+            method: 'GET',
+            credentials: 'include',
+            headers: { 'Content-Type': 'application/json' },
+          });
+          if (resp.ok) {
+            const body = (await resp.json().catch(() => null)) as
+              | { user?: AuthUser; session?: AuthSession }
+              | null;
+            if (body?.user && body?.session) {
+              if (body.session.token) TokenStorage.set(body.session.token);
+              else TokenStorage.clear();
+              return { user: body.user, session: body.session };
+            }
+            // The server affirmatively says the cookie has no session either
+            // — the stored bearer is dead weight; drop it so the next
+            // sign-in starts clean. (Transport errors keep the token: they
+            // prove nothing about its validity.)
+            TokenStorage.clear();
+          }
+        } catch { /* network hiccup — treat as signed out, keep the token */ }
+      }
+      return null;
     },
 
     async forgotPassword(email: string) {