How should AuthProvider recover from transient authentication failures?

[Dudeplayz]

Context

AuthProvider starts by calling getAuthenticatedUser. A 401 used to leave the auth context in its loading state (#2237); #2242 fixed that case by treating UnauthorizedResponseError as an unauthenticated user.

Other failures still propagate from authenticate() and are swallowed by the initial Effect after LOGIN_FETCH was dispatched. The provider can therefore remain in loading: true, with no public way to refresh the authenticated user. #2432 added callbacks for custom login/logout workflows, including offline storage, but does not cover recovery of the initial user lookup.

Use cases

• Application starts offline and connectivity returns later.
• Initial user lookup encounters a temporary timeout or 502/503 response.
• Authentication session is not yet observable immediately after an external login redirect.
• Device resumes or changes network while the application remains open.

401 should continue to mean unauthenticated and should not be retried automatically.

Possible approaches

1. Expose explicit recovery

Transition non-401 failures to an error state and expose refresh() (or reloadUser()) from useAuth. Applications could then retry from a button, focus handler, or online/offline hook. This provides a recovery primitive without imposing retry policy.

2. Keep recovery application-managed through reload

Applications can already wire browser connectivity to a full reload:

useEffect(() => {
  const reloadWhenOnline = () => window.location.reload();
  window.addEventListener('online', reloadWhenOnline);
  return () => window.removeEventListener('online', reloadWhenOnline);
}, []);

An application-specific useOnline() hook can implement the same behavior when state changes from offline to online. This is simple, but reloads the whole application, loses transient UI state, and requires repeated application code.

3. Add opt-in retry behavior

AuthProvider could optionally retry transient failures with a bounded backoff or after an online event. This is convenient, but error classification is difficult because getAuthenticatedUser is an application-provided callback and may reject with arbitrary errors. Automatic retries also introduce hidden network policy.

Questions

• Should non-401 failures leave loading state and expose an explicit error?
• Should useAuth provide a manual refresh() primitive?
• Should online recovery or bounded retry remain application-managed, or become an opt-in provider feature?

Goal: make transient initial-authentication failures recoverable without changing 401 semantics or forcing automatic retry behavior on every application.