spa/.planning/phase-1-foundation/08-logout-flow.md

Task 1.8 — Logout flow

Phase: 1 — Foundation Status: ⬜ Not started Depends on: 1.7 Wiki refs: docs/wiki/entities/react-spa.md

Goal

Wire the "Sign out" button rendered by 1.7's home page to a real logout flow: call useAuthStore.logout(), invalidate the TanStack Query cache, navigate to /login. Small task, but worth its own file because it touches three subsystems and has subtle requirements (cache invalidation, race with concurrent calls).

After this task the Phase 1 happy path is end-to-end: log in → see home → log out → back to login.

Deliverables

• src/auth/logout.ts — orchestration helper:

  export async function performLogout(opts: { queryClient: QueryClient; navigate: NavigateFn }) {
    await useAuthStore.getState().logout();
    opts.queryClient.clear();
    await opts.navigate({ to: '/login', replace: true });
  }
  

• src/ui/components/logout-button.tsx — small shadcn Button wrapping the call:

  export function LogoutButton({ variant = 'outline' }: Props) {
    const queryClient = useQueryClient();
    const navigate = useNavigate();
    const [isLoggingOut, setIsLoggingOut] = useState(false);
  
    async function onClick() {
      if (isLoggingOut) return;
      setIsLoggingOut(true);
      try {
        await performLogout({ queryClient, navigate });
      } catch {
        // Even if logout fails, the store state is now anonymous; the navigate has happened.
        // Nothing useful to do beyond logging.
      }
    }
  
    return (
      <Button variant={variant} onClick={onClick} disabled={isLoggingOut}>
        {isLoggingOut ? 'Signing out…' : 'Sign out'}
      </Button>
    );
  }
  

• src/routes/_authed/index.tsx updated to use <LogoutButton /> instead of the placeholder button from 1.7.

• Cross-tab logout handling — src/auth/cross-tab-sync.ts:

  • Subscribes to window.addEventListener('storage', ...) for a trm-auth-version key.
  • On change, re-runs useAuthStore.getState().initialize() to pick up the new state.
  • Mounted once at app boot from <RuntimeConfigProvider>'s success path (alongside the initial initialize() call).

Specification

Why clear the query cache on logout

After logout, the next user (someone else logging in on the same browser) shouldn't see cached data the previous user pulled. TanStack Query's cache is keyed by query keys, not by user identity — without an explicit clear, the next login would briefly show stale data while refetches resolve. queryClient.clear() removes everything; subsequent queries will refetch fresh.

The Zustand auth store also resets to 'anonymous'. No user data leaks across sessions in process memory.

Why a separate orchestration helper

Three things have to happen in order: server-side logout, client-side cache clear, navigation. Wrapping them in a function (performLogout) means:

1. Components call one thing.
2. The order is documented in code, not in the component.
3. If we ever add another step (e.g. closing the live WS in Phase 2), it lands in one place.

Cross-tab sync

Pattern: when a user logs out in one tab, other tabs should also lose their session. Two ways:

Option A: BroadcastChannel. Modern API; the auth store posts on logout/login; other tabs listen. Cleaner.

Option B: localStorage + storage event. Older but universal. Write a "version" key on auth events; other tabs see the storage event and re-init.

Pick B for now. Slightly broader browser support; simpler. Migrate to BroadcastChannel later if it becomes preferred.

// src/auth/cross-tab-sync.ts
const VERSION_KEY = 'trm-auth-version';

export function startCrossTabSync() {
  // After every login/logout in this tab, bump the version so other tabs see a storage event.
  useAuthStore.subscribe((state, prev) => {
    if (state.status !== prev.status) {
      localStorage.setItem(VERSION_KEY, String(Date.now()));
    }
  });

  // React to bumps from other tabs.
  window.addEventListener('storage', (ev) => {
    if (ev.key !== VERSION_KEY) return;
    useAuthStore.getState().initialize();
  });
}

Worth flagging a subtlety: writing to localStorage doesn't trigger the storage event in the same tab. So this works exactly right — bump in tab A, tab B sees it.

What logout does NOT do

• No "Are you sure?" confirmation. Click and out. Race operators clicking accidentally is unlikely in stage day operation; the nuisance of a confirmation modal isn't worth the marginal protection.
• No server-side session enumeration / kill all sessions. Directus's /auth/logout invalidates the current session's refresh token. Other concurrent sessions (other browsers, other devices) keep working. If a "log out everywhere" feature is needed, that's a Phase 4 idea.
• No analytics event. No analytics platform yet.

What happens if directus.logout() fails

useAuthStore.logout() (from 1.5) already swallows the error and forces local state to 'anonymous'. So the user is "logged out from the SPA" even if the server call failed (e.g. network outage). The refresh cookie may still be valid server-side, but without local state to replay it the SPA can't reuse it. On next login attempt, Directus may overwrite or invalidate the dangling cookie naturally.

This is the right trade-off: logout that fails should not leave the user appearing logged in.

Acceptance criteria

• pnpm typecheck, pnpm lint, pnpm format:check clean.
• Click "Sign out" → button shows "Signing out…" briefly → SPA navigates to /login → refresh cookie is gone (verifiable: refreshing the page now stays on /login instead of going to /).
• Logging in twice (in two tabs) and logging out in tab A → tab B's auth state transitions to 'anonymous' (verifiable by watching the route gate redirect tab B to /login on next interaction).
• After logout, opening the React Query devtools shows an empty cache.
• Logout while offline (DevTools "Network: offline"): button completes, navigates to /login, no UI hang. Refreshing the page stays on /login.
• Double-click on the logout button doesn't cause a duplicate /auth/logout call (the isLoggingOut flag guards).

Risks / open questions

• Refresh-cookie zombie. If directus.logout() fails server-side, the refresh cookie may still be valid. On next page load, initialize() calls /users/me, which triggers a silent refresh, and the user is logged back in transparently. To force complete logout, the SPA should also issue a request to clear the cookie locally before navigating. Test this against stage and document the behaviour.
• Cross-tab sync race. If tab A logs out and tab B is mid-request, tab B's request might 401 mid-flight. Handle gracefully: TanStack Query's default error handling shows a toast / retry; the route gate then redirects to login. Acceptable for v1.
• Multiple BroadcastChannel listeners on hot-reload. During Vite dev HMR, startCrossTabSync() may run multiple times. Guard with a module-level boolean to ensure single registration.

Done

• src/auth/logout.ts — performLogout({ queryClient, navigate? }) orchestration helper. Calls useAuthStore.getState().logout() (which swallows server-call failures and forces local state to anonymous), then queryClient.clear() (so the next user doesn't see cached data), then navigates to /login if a navigate function was passed.
• src/auth/cross-tab-sync.ts — startCrossTabSync(). Subscribes to the auth store and bumps a trm-auth-version localStorage key on status transitions. Listens for storage events and re-runs initialize() when another tab bumps the key. Idempotent (HMR-safe) via a module-level started flag. Gracefully no-ops if localStorage is unavailable (private browsing, quota).
• src/ui/components/logout-button.tsx — <LogoutButton> component wraps the shadcn Button. Pass-through props (variant, size, etc.) but locks onClick / disabled / children so callers can't override the orchestration. Local isLoggingOut state shows "Signing out…" while the call is in flight; double-click guard.
• src/auth/bootstrap.tsx — <AuthBootstrap> updated to call startCrossTabSync() alongside initDirectusClient() and initialize(). Single mount point for all auth-side wiring.
• src/auth/index.ts — re-exports performLogout and startCrossTabSync. Alphabetised the exports.
• src/routes/_authed/index.tsx — replaced the inline button with <LogoutButton />. The page's existing useEffect on the 'anonymous' status transition still handles the navigation when the cross-tab sync fires (no separate code path needed).

Bonus from this task — caught a missing "strict": true in tsconfig.app.json. TanStack Router emits a "strictNullChecks must be enabled" conditional-type error in editors when strict mode is off; CI's tsc -b was lenient. Added strict: true (along with the existing strict-adjacent flags); typecheck still green.

Smoke check: pnpm typecheck, pnpm lint, pnpm format:check, pnpm build all green. Bundle: 353KB main + same per-route chunks as 1.7 (login 37KB, _authed 1.4KB grew slightly with the LogoutButton). No measurable bundle impact from the logout orchestration.

Browser smoke pending:

1. Sign in. Click "Sign out". Watch button show "Signing out…", then redirect to /login. Hard refresh on /login stays on /login.
2. Sign in in tab A. Open tab B (same SPA). Sign out in tab A. Tab B's home page should redirect to /login on next interaction (or immediately, depending on whether the storage event triggers re-render).
3. With DevTools "Network: offline", click sign out. Should still navigate to /login (server call fails, local state forced to anonymous).

Landed in 1ee339c.