@openmrs/esm-api 10.0.1-pre.5605 → 10.0.1-pre.5616

package/src/current-user.test.ts

@@ -10,9 +10,12 @@ import {
   setSessionLocation,
   setUserProperties,
   sessionStore,
+  setSessionLocale,
+  verifyTotpCode,
+  logout,
 } from './current-user';
 import type * as openmrsFetchExport from './openmrs-fetch';
-import { openmrsFetch } from './openmrs-fetch';
+import { OpenmrsFetchError, openmrsFetch } from './openmrs-fetch';
 import { reportError } from '@openmrs/esm-error-handling';
 import type { LoggedInUser, Privilege, Role, Session } from './types';
 
@@ -32,6 +35,10 @@ vi.mock('@openmrs/esm-error-handling', () => ({
 const mockOpenmrsFetch = vi.mocked(openmrsFetch);
 const mockReportError = vi.mocked(reportError);
 
+function createAuthFailure(status: number, responseBody: unknown = null) {
+  return new OpenmrsFetchError('/openmrs/ws/rest/v1/session', { status } as Response, responseBody as any, Error());
+}
+
 // Helper to create mock fetch responses
 function createMockFetchResponse<T>(data: T, ok = true): any {
   return {
@@ -247,7 +254,7 @@ describe('setUserLanguage', () => {
 describe('getLoggedInUser', () => {
   beforeEach(() => {
     // Reset session store
-    sessionStore.setState({ loaded: false, session: null });
+    sessionStore.setState({ loaded: false, session: null }, true);
   });
 
   it('should return logged in user when session is loaded', async () => {
@@ -314,7 +321,7 @@ describe('getLoggedInUser', () => {
 
 describe('getCurrentUser', () => {
   beforeEach(() => {
-    sessionStore.setState({ loaded: false, session: null });
+    sessionStore.setState({ loaded: false, session: null }, true);
     mockOpenmrsFetch.mockClear();
     mockReportError.mockClear();
     // Mock openmrsFetch to prevent unhandled promise rejections
@@ -446,6 +453,23 @@ describe('getCurrentUser', () => {
     expect(resolvedSession).toEqual(mockSession);
   });
 
+  it('should resolve with the last loaded session when a refresh fails', async () => {
+    vi.useFakeTimers();
+
+    try {
+      const staleSession: Session = { authenticated: true, sessionId: 'stale-session', user: buildMockUser() };
+      mockOpenmrsFetch.mockResolvedValue(createMockFetchResponse(staleSession));
+      await refetchCurrentUser();
+
+      vi.setSystemTime(Date.now() + 61 * 1000);
+      mockOpenmrsFetch.mockRejectedValue(new Error('Bad gateway'));
+
+      await expect(getCurrentUser({ includeAuthStatus: true })).resolves.toEqual(staleSession);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('should not resolve until the session is loaded', async () => {
     // Prevent the automatic refetch from resolving the session so the only way
     // the promise settles is the manual store update below.
@@ -476,7 +500,7 @@ describe('getCurrentUser', () => {
 
 describe('refetchCurrentUser', () => {
   beforeEach(() => {
-    sessionStore.setState({ loaded: false, session: null });
+    sessionStore.setState({ loaded: false, session: null }, true);
     mockOpenmrsFetch.mockClear();
   });
 
@@ -495,6 +519,7 @@ describe('refetchCurrentUser', () => {
       expect.stringContaining('/session'),
       expect.objectContaining({
         headers: {},
+        rejectAuthFailure: true,
       }),
     );
   });
@@ -517,6 +542,7 @@ describe('refetchCurrentUser', () => {
         headers: {
           Authorization: expectedAuth,
         },
+        rejectAuthFailure: true,
       }),
     );
   });
@@ -561,6 +587,69 @@ describe('refetchCurrentUser', () => {
 
     expect(mockReportError).toHaveBeenCalled();
   });
+
+  it('should record the error when the fetch fails before any session has loaded', async () => {
+    const error = new Error('Bad gateway');
+    mockOpenmrsFetch.mockRejectedValue(error);
+
+    await expect(refetchCurrentUser()).rejects.toEqual({ loaded: false, session: null, error });
+    expect(sessionStore.getState()).toEqual({ loaded: false, session: null, error });
+  });
+
+  it('should keep an already-loaded session when a later fetch fails', async () => {
+    const mockSession: Session = { authenticated: true, sessionId: 'test-session', user: {} as LoggedInUser };
+    sessionStore.setState({ loaded: true, session: mockSession }, true);
+    mockReportError.mockClear();
+    mockOpenmrsFetch.mockRejectedValue(new Error('Bad gateway'));
+
+    await expect(refetchCurrentUser()).rejects.toEqual({ loaded: true, session: mockSession });
+    expect(sessionStore.getState()).toEqual({ loaded: true, session: mockSession });
+    expect(mockReportError).toHaveBeenCalled();
+  });
+
+  it('should record an error when the session endpoint does not respond with a session', async () => {
+    mockOpenmrsFetch.mockResolvedValue(createMockFetchResponse('<html>Bad gateway</html>'));
+
+    await expect(refetchCurrentUser()).rejects.toMatchObject({ loaded: false, session: null });
+    expect(sessionStore.getState()).toMatchObject({
+      loaded: false,
+      error: new Error('The session endpoint did not respond with a session'),
+    });
+  });
+
+  it('should use the unauthenticated session in the body of a 401 response', async () => {
+    const unauthenticated = { authenticated: false, sessionId: 'abc', allowedLocales: ['en', 'fr'] };
+    mockOpenmrsFetch.mockRejectedValue(createAuthFailure(401, unauthenticated));
+
+    await expect(refetchCurrentUser()).resolves.toEqual({ loaded: true, session: unauthenticated });
+  });
+
+  it.each([401, 403])(
+    'should record a logged-out session when the session endpoint responds with %i',
+    async (status) => {
+      mockReportError.mockClear();
+      mockOpenmrsFetch.mockRejectedValue(createAuthFailure(status));
+
+      await expect(refetchCurrentUser()).resolves.toEqual({
+        loaded: true,
+        session: { authenticated: false, sessionId: '' },
+      });
+
+      expect(sessionStore.getState()).toEqual({
+        loaded: true,
+        session: { authenticated: false, sessionId: '' },
+      });
+      expect(mockReportError).not.toHaveBeenCalled();
+    },
+  );
+
+  it('should not leave readers waiting on the failed request after an auth failure', async () => {
+    mockOpenmrsFetch.mockRejectedValueOnce(createAuthFailure(401));
+    await refetchCurrentUser();
+
+    await expect(getCurrentUser()).resolves.toEqual({ authenticated: false, sessionId: '' });
+    expect(mockOpenmrsFetch).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe('setSessionLocation', () => {
@@ -592,6 +681,7 @@ describe('setSessionLocation', () => {
         headers: {
           'Content-Type': 'application/json',
         },
+        rejectAuthFailure: true,
         signal: abortController.signal,
       }),
     );
@@ -632,24 +722,21 @@ describe('setUserProperties', () => {
       favoriteColor: 'blue',
     };
 
-    mockOpenmrsFetch
-      .mockResolvedValueOnce(createMockFetchResponse({})) // First call to update properties
-      .mockResolvedValueOnce(
-        createMockFetchResponse({
-          // Second call to refetch session
-          authenticated: true,
-          sessionId: 'test-session',
-          user: {
-            uuid: userUuid,
-            userProperties,
-          } as unknown as LoggedInUser,
-        }),
-      );
+    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse({}));
+    mockOpenmrsFetch.mockResolvedValueOnce(
+      createMockFetchResponse({
+        authenticated: true,
+        sessionId: 'test-session',
+        user: {
+          uuid: userUuid,
+          userProperties,
+        } as unknown as LoggedInUser,
+      }),
+    );
 
     await setUserProperties(userUuid, userProperties);
 
-    expect(mockOpenmrsFetch).toHaveBeenNthCalledWith(
-      1,
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(
       expect.stringContaining(`/user/${userUuid}`),
       expect.objectContaining({
         method: 'POST',
@@ -669,7 +756,8 @@ describe('setUserProperties', () => {
     const userProperties = { defaultLocale: 'fr-FR' };
     const abortController = new AbortController();
 
-    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse({})).mockResolvedValueOnce(
+    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse({}));
+    mockOpenmrsFetch.mockResolvedValueOnce(
       createMockFetchResponse({
         authenticated: true,
         sessionId: 'test-session',
@@ -679,8 +767,7 @@ describe('setUserProperties', () => {
 
     await setUserProperties(userUuid, userProperties, abortController);
 
-    expect(mockOpenmrsFetch).toHaveBeenNthCalledWith(
-      1,
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(
       expect.anything(),
       expect.objectContaining({
         signal: abortController.signal,
@@ -692,7 +779,8 @@ describe('setUserProperties', () => {
     const userUuid = 'user-uuid-123';
     const userProperties = { defaultLocale: 'es-ES' };
 
-    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse({})).mockResolvedValueOnce(
+    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse({}));
+    mockOpenmrsFetch.mockResolvedValueOnce(
       createMockFetchResponse({
         authenticated: true,
         sessionId: 'test-session',
@@ -702,8 +790,7 @@ describe('setUserProperties', () => {
 
     await setUserProperties(userUuid, userProperties);
 
-    expect(mockOpenmrsFetch).toHaveBeenNthCalledWith(
-      1,
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(
       expect.anything(),
       expect.objectContaining({
         signal: expect.any(AbortSignal),
@@ -711,3 +798,121 @@ describe('setUserProperties', () => {
     );
   });
 });
+
+describe('setSessionLocale', () => {
+  beforeEach(() => {
+    mockOpenmrsFetch.mockClear();
+  });
+
+  it('should set the session locale and refetch the session', async () => {
+    const mockSession: Session = { authenticated: true, sessionId: 'test-session', locale: 'fr' };
+    const abortController = new AbortController();
+    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse(mockSession));
+    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse(mockSession));
+
+    await expect(setSessionLocale('fr', abortController)).resolves.toEqual({ loaded: true, session: mockSession });
+
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(
+      '/ws/rest/v1/session',
+      expect.objectContaining({
+        method: 'POST',
+        body: { locale: 'fr' },
+        signal: abortController.signal,
+      }),
+    );
+    expect(mockOpenmrsFetch).toHaveBeenLastCalledWith(
+      '/ws/rest/v1/session',
+      expect.objectContaining({ rejectAuthFailure: true }),
+    );
+  });
+
+  it('should reject with the fetch error when the server does not accept the locale', async () => {
+    const error = new OpenmrsFetchError('/openmrs/ws/rest/v1/session', { status: 400 } as Response, null, Error());
+    mockOpenmrsFetch.mockRejectedValueOnce(error);
+
+    await expect(setSessionLocale('xx')).rejects.toBe(error);
+    expect(mockOpenmrsFetch).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('verifyTotpCode', () => {
+  beforeEach(() => {
+    mockOpenmrsFetch.mockClear();
+  });
+
+  it('should send the code and ask the server to remember the device only when requested', async () => {
+    mockOpenmrsFetch.mockResolvedValue(createMockFetchResponse({ authenticated: false, sessionId: '' }));
+
+    await verifyTotpCode('123456');
+    expect(mockOpenmrsFetch).toHaveBeenLastCalledWith('/ws/rest/v1/session', {
+      headers: { 'X-Totp-Code': '123456' },
+    });
+
+    await verifyTotpCode('123456', true);
+    expect(mockOpenmrsFetch).toHaveBeenLastCalledWith('/ws/rest/v1/session?rememberMe=true', {
+      headers: { 'X-Totp-Code': '123456' },
+    });
+  });
+
+  it('should refetch and resolve with the session when the code is accepted', async () => {
+    const mockSession: Session = { authenticated: true, sessionId: 'test-session', user: {} as LoggedInUser };
+    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse({ authenticated: true, sessionId: 'test-session' }));
+    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse(mockSession));
+
+    await expect(verifyTotpCode('123456')).resolves.toEqual(mockSession);
+    expect(sessionStore.getState()).toEqual({ loaded: true, session: mockSession });
+  });
+
+  it('should resolve with the unauthenticated session without refetching when the code is not accepted', async () => {
+    const unauthenticated = { authenticated: false, sessionId: '' };
+    mockOpenmrsFetch.mockResolvedValueOnce(createMockFetchResponse(unauthenticated));
+
+    await expect(verifyTotpCode('000000')).resolves.toEqual(unauthenticated);
+    expect(mockOpenmrsFetch).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('logout', () => {
+  const loggedOut = { loaded: true, session: { authenticated: false, sessionId: '' } };
+
+  beforeEach(() => {
+    sessionStore.setState(
+      {
+        loaded: true,
+        session: { authenticated: true, sessionId: 'test-session', user: {} as LoggedInUser },
+      },
+      true,
+    );
+    mockOpenmrsFetch.mockReset();
+  });
+
+  it('should delete the session and record a logged-out session', async () => {
+    mockOpenmrsFetch
+      .mockResolvedValueOnce(createMockFetchResponse(null))
+      .mockResolvedValueOnce(createMockFetchResponse({ authenticated: false, sessionId: '' }));
+
+    await logout();
+
+    expect(mockOpenmrsFetch).toHaveBeenNthCalledWith(1, '/ws/rest/v1/session', {
+      method: 'DELETE',
+      rejectAuthFailure: true,
+    });
+    expect(sessionStore.getState()).toEqual(loggedOut);
+  });
+
+  it('should treat a session the server has already ended as logged out', async () => {
+    mockOpenmrsFetch.mockRejectedValue(createAuthFailure(401));
+
+    await expect(logout()).resolves.toBeUndefined();
+    expect(sessionStore.getState()).toEqual(loggedOut);
+  });
+
+  it('should reject and keep the session when the server fails to end it', async () => {
+    const before = sessionStore.getState();
+    const error = new OpenmrsFetchError('/openmrs/ws/rest/v1/session', { status: 500 } as Response, null, Error());
+    mockOpenmrsFetch.mockRejectedValueOnce(error);
+
+    await expect(logout()).rejects.toBe(error);
+    expect(sessionStore.getState()).toEqual(before);
+  });
+});

package/src/current-user.ts

@@ -2,7 +2,7 @@
 import { reportError } from '@openmrs/esm-error-handling';
 import { createGlobalStore } from '@openmrs/esm-state';
 import { isUndefined } from 'lodash-es';
-import { openmrsFetch, restBaseUrl, sessionEndpoint } from './openmrs-fetch';
+import { OpenmrsFetchError, openmrsFetch, restBaseUrl, sessionEndpoint } from './openmrs-fetch';
 import type { LoggedInUser, SessionLocation, Privilege, Role, Session, FetchResponse } from './types';
 
 export type SessionStore = LoadedSessionStore | UnloadedSessionStore;
@@ -15,6 +15,8 @@ export type LoadedSessionStore = {
 export type UnloadedSessionStore = {
   loaded: false;
   session: null;
+  /** Set when fetching the session failed before any session had loaded. */
+  error?: Error;
 };
 
 /** @internal */
@@ -62,7 +64,8 @@ function refreshSessionIfStale(): Promise<SessionStore> | null {
  * current user's session. If the session hasn't been loaded, was loaded more than
  * a minute ago, or is in the middle of being refetched, the Promise waits for the
  * fetch in question rather than resolving with data that may be out of date. The
- * session it resolves with is therefore never more than a minute old.
+ * session it resolves with is therefore never more than a minute old, unless that fetch fails,
+ * in which case it resolves with the last session that loaded.
  *
  * The function accepts an optional `opts` object with an `includeAuthStatus` boolean
  * property that defaults to `true`. When `true`, the entire {@link Session} object
@@ -104,17 +107,23 @@ function getCurrentUser(opts?: { includeAuthStatus?: boolean }): Promise<Session
   const includeAuthStatus = opts?.includeAuthStatus ?? true;
   const select = (session: Session) => (includeAuthStatus ? session : (session.user as LoggedInUser));
 
-  if (!refreshSessionIfStale()) {
+  const refresh = refreshSessionIfStale();
+  if (!refresh) {
     return Promise.resolve(select((sessionStore.getState() as LoadedSessionStore).session));
   }
 
   return new Promise<Session | LoggedInUser>((resolve) => {
-    const unsubscribe = sessionStore.subscribe((state) => {
+    const resolveIfLoaded = () => {
+      const state = sessionStore.getState();
       if (state.loaded) {
         unsubscribe();
         resolve(select(state.session));
       }
-    });
+    };
+    const unsubscribe = sessionStore.subscribe(resolveIfLoaded);
+    // A failed refresh keeps an already-loaded session without updating the store, so the
+    // subscription alone would never fire.
+    refresh.then(resolveIfLoaded, resolveIfLoaded);
   });
 }
 
@@ -212,7 +221,12 @@ function isSuperUser(user: { roles: Array<Role> }) {
  * the user. All subscribers to the session store will be notified of the
  * new user once the new version of the user object is downloaded.
  *
- * @returns A Promise resolving to the updated session store state.
+ * If the server rejects the request as unauthenticated (401 or 403), the store records a
+ * logged-out session. If the request fails for any other reason, a session that has already
+ * loaded is kept; otherwise the store records the error.
+ *
+ * @returns A Promise resolving to the updated session store state. It rejects with the
+ *   store state if the request fails for a reason other than authentication.
  *
  * @example
  * ```js
@@ -230,6 +244,7 @@ export function refetchCurrentUser(username?: string, password?: string) {
   const refresh = handleSessionResponse(
     openmrsFetch(sessionEndpoint, {
       headers,
+      rejectAuthFailure: true,
     }),
   );
 
@@ -259,10 +274,13 @@ export function refetchCurrentUser(username?: string, password?: string) {
  * ```
  */
 export function clearCurrentUser() {
-  sessionStore.setState({
-    loaded: true,
-    session: { authenticated: false, sessionId: '' },
-  });
+  sessionStore.setState(
+    {
+      loaded: true,
+      session: { authenticated: false, sessionId: '' },
+    },
+    true,
+  );
 }
 
 /**
@@ -375,7 +393,7 @@ export async function getSessionLocation(): Promise<SessionLocation | undefined>
  * await setSessionLocation('location-uuid-here', abortController);
  * ```
  */
-export async function setSessionLocation(locationUuid: string, abortController: AbortController): Promise<any> {
+export async function setSessionLocation(locationUuid: string, abortController?: AbortController): Promise<any> {
   return handleSessionResponse(
     openmrsFetch(sessionEndpoint, {
       method: 'POST',
@@ -383,11 +401,42 @@ export async function setSessionLocation(locationUuid: string, abortController:
       headers: {
         'Content-Type': 'application/json',
       },
-      signal: abortController.signal,
+      rejectAuthFailure: true,
+      signal: abortController?.signal,
     }),
   );
 }
 
+/**
+ * Sets the locale for the current session only, leaving the user's default locale unchanged.
+ * Use {@link setUserProperties} with a `defaultLocale` property to change the default instead.
+ *
+ * @param locale The locale in Java's `Locale#toString()` form, e.g. `en_GB`.
+ * @param abortController Optional AbortController to allow cancellation of the request.
+ * @returns A Promise that resolves with the updated SessionStore after refetching the current user.
+ *   It rejects with an {@link OpenmrsFetchError} if the server does not accept the locale.
+ *
+ * @example
+ * ```ts
+ * import { setSessionLocale } from '@openmrs/esm-api';
+ * await setSessionLocale('fr');
+ * ```
+ *
+ * @internal
+ */
+export async function setSessionLocale(locale: string, abortController?: AbortController): Promise<SessionStore> {
+  await openmrsFetch(sessionEndpoint, {
+    method: 'POST',
+    body: { locale },
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    signal: abortController?.signal,
+  });
+
+  return refetchCurrentUser();
+}
+
 /**
  * Updates the user properties for a specific user. User properties are key-value
  * pairs that store user-specific settings and preferences. After updating the
@@ -433,26 +482,126 @@ export async function setUserProperties(
   return refetchCurrentUser();
 }
 
+/**
+ * Submits a TOTP code to complete a two-factor login challenge. When the code is accepted, the
+ * session store is refreshed with the now-authenticated session.
+ *
+ * @param code The code from the user's authenticator app.
+ * @param rememberDevice Whether the server should skip the challenge on this device in future.
+ * @returns A Promise resolving to the session. Its `authenticated` property is `false` if the
+ *   code was not accepted. It rejects with an {@link OpenmrsFetchError} if the server rejects the
+ *   request, in which case `responseBody` may explain why.
+ *
+ * @example
+ * ```ts
+ * import { verifyTotpCode } from '@openmrs/esm-api';
+ * const session = await verifyTotpCode('123456', true);
+ * ```
+ *
+ * @internal
+ */
+export async function verifyTotpCode(code: string, rememberDevice = false): Promise<Session> {
+  const response = await openmrsFetch<Session>(
+    rememberDevice ? `${sessionEndpoint}?rememberMe=true` : sessionEndpoint,
+    {
+      headers: {
+        'X-Totp-Code': code,
+      },
+    },
+  );
+
+  if (response.data?.authenticated) {
+    // `refetchCurrentUser` only resolves once the store holds a session.
+    const store = (await refetchCurrentUser()) as LoadedSessionStore;
+    return store.session;
+  }
+
+  return response.data;
+}
+
+/**
+ * Ends the current session on the server and records a logged-out session in the session store.
+ * A server that has already ended the session (401 or 403) counts as a successful logout.
+ *
+ * Other data cached for the logged-in user, such as SWR caches, is the caller's to clear.
+ *
+ * @returns A Promise that resolves once the session store holds a logged-out session.
+ *
+ * @example
+ * ```ts
+ * import { logout } from '@openmrs/esm-api';
+ * await logout();
+ * ```
+ *
+ * @internal
+ */
+export async function logout(): Promise<void> {
+  try {
+    await openmrsFetch(sessionEndpoint, { method: 'DELETE', rejectAuthFailure: true });
+  } catch (err) {
+    if (!isAuthFailure(err)) {
+      throw err;
+    }
+  }
+
+  clearCurrentUser();
+  // The session just cleared is already correct, so a failed refresh loses nothing.
+  await refetchCurrentUser().catch(() => {});
+}
+
 function handleSessionResponse(result: Promise<FetchResponse<Session>>) {
   return new Promise<SessionStore>((resolve, reject) => {
     result
       .then((res) => {
-        let nextState: SessionStore;
         if (typeof res?.data === 'object') {
-          nextState = { loaded: true, session: res.data };
-          sessionStore.setState(nextState);
+          const nextState: SessionStore = { loaded: true, session: res.data };
+          sessionStore.setState(nextState, true);
           resolve(nextState);
         } else {
-          nextState = { loaded: false, session: null };
-          sessionStore.setState(nextState);
-          reject(nextState);
+          reject(recordSessionFailure(Error('The session endpoint did not respond with a session')));
         }
       })
       .catch((err) => {
+        // An auth failure is the session endpoint's answer for "not logged in", not a failed lookup.
+        if (isAuthFailure(err)) {
+          if (isUnauthenticatedSession(err.responseBody)) {
+            sessionStore.setState({ loaded: true, session: err.responseBody }, true);
+          } else {
+            clearCurrentUser();
+          }
+          resolve(sessionStore.getState());
+          return;
+        }
+
         reportError(`Failed to fetch new session information: ${err}`);
-        const nextState: SessionStore = { loaded: false, session: null };
-        sessionStore.setState(nextState);
-        reject(nextState);
+        reject(recordSessionFailure(err));
       });
   });
 }
+
+function isAuthFailure(err: unknown): err is OpenmrsFetchError {
+  return err instanceof OpenmrsFetchError && (err.response.status === 401 || err.response.status === 403);
+}
+
+function isUnauthenticatedSession(body: unknown): body is Session {
+  return typeof body === 'object' && body !== null && (body as Session).authenticated === false;
+}
+
+/**
+ * A session that has already loaded is kept when a later fetch fails, since it is still the best answer
+ * available. With nothing to fall back on, the error is recorded so the app shell can show an error page.
+ */
+function recordSessionFailure(err: unknown): SessionStore {
+  if (!sessionStore.getState().loaded) {
+    sessionStore.setState(
+      {
+        loaded: false,
+        session: null,
+        error: err instanceof Error ? err : Error(String(err)),
+      },
+      true,
+    );
+  }
+
+  return sessionStore.getState();
+}

package/src/openmrs-fetch.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { getConfig } from '@openmrs/esm-config';
 import { navigate } from '@openmrs/esm-navigation';
-import { openmrsFetch } from './openmrs-fetch';
+import { OpenmrsFetchError, openmrsFetch } from './openmrs-fetch';
 
 vi.mock('@openmrs/esm-navigation', () => ({
   clearHistory: vi.fn(),
@@ -231,4 +231,14 @@ describe('openmrsFetch', () => {
       to: '/openmrs/spa/login',
     });
   });
+
+  it('navigates to login and rejects on a 401 when rejectAuthFailure is set', async () => {
+    mockFetch.mockResolvedValue(new Response('', { status: 401, statusText: 'Unauthorized' }));
+
+    const result = openmrsFetch('/ws/rest/v1/session', { rejectAuthFailure: true });
+
+    await expect(result).rejects.toBeInstanceOf(OpenmrsFetchError);
+    await expect(result).rejects.toMatchObject({ response: { status: 401 } });
+    expect(mockNavigate).toHaveBeenCalledWith({ to: '${openmrsSpaBase}/login' });
+  });
 });