` the audit cited), so the "blank screen on
load" problem is gone and is **out of scope**. Logout **error** feedback also already exists: `useLogout`
carries no `meta.suppressErrorToast`, so the global `MutationCache.onError` (`api/query-client.ts`)
already shows an error toast on logout failure — the only remaining logout gap is a pending/disabled
state.
**The crux:** the 401 handler lives in an openapi-fetch `Middleware` (`api/client.ts`), which runs
**outside** React and therefore cannot call `useNavigate`. The app uses a React Router 7 **data router**
(`createBrowserRouter`, `app.tsx`). The test harness `renderApp` (`src/test/render.tsx`) mounts the
component under test at `path:"*"` in a **fresh `createMemoryRouter`** — it does not use the app's real
`router` singleton.
### Decisions (from brainstorming)
1. **Soft redirect + return** (chosen over an in-place re-auth modal): router-navigate (no full reload)
to `/login?reason=expired&from=
`; login shows the reason and returns the user to `from`. The
React app + query cache survive; an unsaved edit form's typed values are still lost, but the user
lands back on the same record. (Full field-level preservation via an in-place modal is a deferred
follow-up.)
2. **Navigate-bridge module** (chosen over exporting the `router` singleton or a custom DOM event): a
module holds a settable `navigate` ref that a one-line component registers. This is testable with the
memory-router harness (tests call `setNavigate(mock)` directly); importing the singleton `router`
would be untestable because `renderApp` never mounts it.
## Components
### `api/auth-redirect.ts` (rewrite)
```ts
type NavigateFn = (to: string, opts?: { replace?: boolean }) => void;
let navigateFn: NavigateFn | null = null;
/** Register/unregister the router's navigate fn (called by NavigationBridge). */
export function setNavigate(fn: NavigateFn | null): void {
navigateFn = fn;
}
/** Soft-redirect to login on a 401, preserving SPA state and the return path.
* Falls back to a hard navigation when no router navigate is registered yet
* (e.g. a 401 during the very first load). No-op when already on /login. */
export function redirectToLogin(): void {
const { pathname, search } = window.location;
if (pathname === "/login") return;
const from = encodeURIComponent(pathname + search);
const target = `/login?reason=expired&from=${from}`;
if (navigateFn) {
navigateFn(target, { replace: true });
} else {
window.location.assign(target);
}
}
```
`api/client.ts` is unchanged — the middleware still calls `redirectToLogin()`; only its behaviour changes.
### `shell/navigation-bridge.tsx` (new)
```tsx
import { useEffect } from "react";
import { useNavigate } from "react-router-dom";
import { setNavigate } from "../api/auth-redirect";
/** Bridges React Router's navigate to the non-React 401 handler. Renders nothing. */
export function NavigationBridge() {
const navigate = useNavigate();
useEffect(() => {
setNavigate(navigate);
return () => setNavigate(null);
}, [navigate]);
return null;
}
```
### `app.tsx` (wrap routes in a pathless layout)
Add a pathless layout route around **all** existing routes whose element mounts the bridge plus an
``, so the bridge is always present (covers `/login` and the authed area):
```tsx
function RootLayout() {
return (
<>
);
}
```
```tsx
createRoutesFromElements(
}>
} />
{/* …existing RequireAuth / AppShell subtree unchanged… */}
} />
,
)
```
### `auth/login-page.tsx` (reason banner + return-to + empty-field guard)
- `const [params] = useSearchParams();`
- Reason banner when `params.get("reason") === "expired"`: render `t("auth.sessionExpired")` (a
non-error info note, distinct from the existing `role="alert"` invalid-credentials message).
- On success, navigate to `safeFrom(params.get("from"))` instead of the hardcoded `/objects`:
```ts
function safeFrom(raw: string | null): string {
if (!raw) return "/objects";
// single leading slash only — reject protocol-relative ("//host") / absolute URLs (open redirect)
return /^\/(?!\/)/.test(raw) ? raw : "/objects";
}
```
(`raw` from `useSearchParams` is already percent-decoded.)
- Disable submit on empty fields: `disabled={login.isPending || !email.trim() || !password}`.
### `auth/require-auth.tsx` (capture the attempted location)
```tsx
const location = useLocation();
// …
if (!user) {
const from = encodeURIComponent(location.pathname + location.search);
return ;
}
```
No `reason` here — an unauthenticated deep-link is not an expiry; login simply returns the user to `from`.
### `shell/user-menu.tsx` (logout pending state)
Keep the menu open during logout and show a pending state on the item (Base UI `MenuItem` supports both
`closeOnClick` and `disabled`):
```tsx
```
On success the mutation sets `me` to null and navigates to `/login`, so `UserMenu` unmounts (it returns
`null` when `!me`). Logout **error** already surfaces via the global toast (`useLogout` has no
`suppressErrorToast`). `closeOnClick={false}` also prevents a double-submit (the item is disabled while
pending).
### i18n (en + sv parity — 2 new keys)
- `auth.sessionExpired` = "Your session expired — please sign in again." /
"Din session har gått ut — logga in igen."
- `auth.signingOut` = "Signing out…" / "Loggar ut…"
## Data flow
API 401 → `client.ts` middleware → `redirectToLogin()` → registered `navigate("/login?reason=expired&
from=", {replace})` (no reload) → `LoginPage` reads `reason`/`from`, shows the banner → on success
`navigate(safeFrom(from), {replace})`. Deep-link-while-unauthed → `RequireAuth` → `/login?from=` →
same return-to. The `NavigationBridge` keeps `setNavigate` current for the lifetime of the app.
## Error handling / edges
- **Already on `/login`:** `redirectToLogin()` is a no-op (no redirect loop).
- **401 before the bridge mounts** (first paint): `navigateFn` is null → hard `window.location.assign`
to `/login?reason=expired&from=…` (graceful fallback; reason/return still preserved).
- **Open redirect:** `safeFrom` accepts only a single-leading-slash local path; `//evil.com`,
`https://…`, and empty → `/objects`.
- **Login success with no `from`:** defaults to `/objects` (unchanged behaviour).
- **StrictMode double-invoke:** the bridge effect is idempotent (sets the same fn; cleanup nulls it) —
safe.
- **Reason banner is informational**, not `role="alert"` (it is not an error and should not preempt the
credential-error alert region).
## Testing
- **`api/auth-redirect.test.ts`** (unit, jsdom): with `setNavigate(mock)` and a stubbed
`window.location` (pathname `/objects/abc`), `redirectToLogin()` calls `mock` with
`"/login?reason=expired&from=%2Fobjects%2Fabc"` and `{replace:true}`; with `setNavigate(null)` it calls
`window.location.assign` with the same target; when `pathname === "/login"` it does nothing.
- **`auth/login-page` test:** rendering at `/login?reason=expired` shows the `auth.sessionExpired` text;
a successful login at `/login?from=%2Fobjects%2F123` navigates to `/objects/123`; a bad `from`
(`//evil.com`) falls back to `/objects`; the submit button is disabled until both fields are non-empty.
- **`auth/require-auth` test:** when `useMe` resolves to no user, it renders a redirect to
`/login?from=…` carrying the attempted path.
- **`shell/user-menu` test:** with a delayed logout handler, after clicking Sign out the item shows the
`auth.signingOut` pending text (the menu stays open via `closeOnClick={false}`).
- **Gate:** `typecheck`/`lint`/`test`/`build`/`check:size`/`check:colors` green; en/sv parity (the #60
parity test guards the 2 new keys); no codename; no new dependency.
## Acceptance criteria
1. A 401 from an API call performs a **router** navigation (no full page reload) to
`/login?reason=expired&from=`; the React app/query cache are not torn down.
2. The login page shows a "session expired" message when `reason=expired`, and on success returns the
user to a **validated** `from` path (defaulting to `/objects`); protocol-relative/absolute `from`
values are rejected.
3. `RequireAuth` redirects unauthenticated users to `/login?from=` so deep links return
after login.
4. Login submit is disabled while either field is empty; the Sign out item shows a pending state
(`auth.signingOut`, disabled) while logging out.
5. `typecheck`/`lint`/`test`/`build`/`check:colors` green; `check:size` reported; en/sv parity (2 new
keys); no codename; no new dependency.
## Out of scope → follow-ups
- **In-place re-auth modal** that keeps the edit form mounted for full field-level preservation of
in-progress work (deferred by decision; soft redirect ships first).
- Idle/expiry **pre-warning** (e.g. "your session will expire soon") and token/silent refresh.
- Broader auth-event audit surfacing on the client.