---
title: Redirect to sign-in on session timeout instead of hanging / "couldn't load events"
date: 2026-06-07
priority: high
phase_hint: Phase 03 (auth-entry UX) / Gate 2 polish
---

# Redirect to sign-in on session timeout instead of hanging

## Problem (observed in live Gate 2 testing)

When the OIDC session expires **mid-use** (e.g. user leaves the tab open past
the session/refresh lifespan, then tries to delete an event), the app does not
recognize the signed-out state. The action (delete) appears to hang — no sync
toast, no progress — and shortly after the calendar shows a generic
**"couldn't load events"** error. The user is fooled into thinking the app is
working/broken rather than understanding they've been signed out and need to
re-authenticate.

## Root cause

Re-auth is only wired to the **initial** `/api/me` failure:
- `CalendarShell.tsx` calls `maybeRedirectToLogin()` only on `meQuery.isError`.
- `maybeRedirectToLogin()` (apps/pwa/src/lib/loginRedirect.ts) is **one-shot**
  (guarded by the `familysync.loginRedirectAttempted` sessionStorage flag) and
  `clearLoginRedirect()` runs on a successful `/api/me`.
- Other calls don't drive re-auth:
  - `fetchEvents` uses `redirect: 'follow'`, so a timed-out session 302s to
    Authelia (cross-origin) → the XHR rejects → `eventsQuery` just errors
    ("couldn't load events"), no redirect.
  - Write mutations (create/edit/**delete**) call the API directly; on an
    expired session the request 302s/opaque-fails and the mutation hangs/errors
    with no re-auth and no clear feedback.

So a session that expires after the first successful load has no path back to
login except a manual full refresh.

## Desired behavior

Any API response that indicates "not authenticated anymore" (401, or an
`opaqueredirect`/`type: 'opaqueredirect'` from the OIDC guard's 302 to Authelia)
should put the app into a clear **signed-out** state and trigger a top-level
re-auth navigation to `/api/login` — from ANY query or mutation, not just the
initial `/api/me`. The user should never be left staring at a hung action or a
generic data-load error when the real cause is an expired session.

## Scope to decide when promoted

- Centralize auth-expiry detection in the API client (apps/pwa/src/api/client.ts):
  a shared helper that classifies a response as "session expired" (401 or
  opaqueredirect) and throws a typed `SessionExpiredError`.
- Apply `redirect: 'manual'` consistently (fetchEvents/mutations) so the guard's
  302 is detectable instead of hanging on the cross-origin follow.
- A single TanStack Query handler (e.g. QueryCache/MutationCache `onError`, or
  a small auth-state listener) that, on `SessionExpiredError`, calls a
  re-armed `maybeRedirectToLogin()` — the one-shot loop guard must be reset so
  a genuine later expiry can redirect again (clear the flag on detected expiry,
  not only on successful `/api/me`).
- Decide UX: immediate redirect to `/api/login` vs a brief "Your session
  expired — signing you back in…" toast/interstitial before redirecting (the
  non-technical Apple member should not see a raw error).
- Make sure an in-flight write that fails on expiry is not silently lost — after
  re-auth, either resurface the unsaved action or clearly tell the user it
  wasn't saved (ties to T-03-18 no-silent-loss).

## Notes

- Relates to the earlier one-shot login redirect work (quick 260606-tv8) and the
  OIDC state-cookie-churn fix (commit bb61d21 — gate events query on auth).
- Verify with a real expiry (or shorten `OIDC_AUTH_EXPIRES` / Authelia
  `refresh_token_lifespan` in a test) rather than only reasoning about it.