@axa-fr/oidc-client 7.27.16 → 7.27.18

package/src/login.spec.ts

@@ -0,0 +1,151 @@
+// Tests for the guards added to loginCallbackAsync to surface missing /
+// mismatched state and missing nonce as typed `OidcStateError` instead of a
+// generic TypeError. See https://github.com/AxaFrance/oidc-client/issues/1678
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ILOidcLocation } from './location';
+import { loginCallbackAsync } from './login';
+import { OidcStateError, OidcStateErrorCode } from './oidcStateError';
+
+const makeStorage = (): Storage => {
+  const store: Record<string, string> = {};
+  return {
+    getItem: (key: string) => store[key] ?? null,
+    setItem: (key: string, value: string) => {
+      store[key] = value;
+    },
+    removeItem: (key: string) => {
+      delete store[key];
+    },
+    clear: () => {
+      for (const key of Object.keys(store)) {
+        delete store[key];
+      }
+    },
+    get length() {
+      return Object.keys(store).length;
+    },
+    key: (index: number) => Object.keys(store)[index] ?? null,
+    [Symbol.iterator]: function* () {
+      yield* Object.entries(store);
+    },
+  } as unknown as Storage;
+};
+
+class FakeLocation implements ILOidcLocation {
+  constructor(private currentHref: string) {}
+  open(): void {}
+  reload(): void {}
+  getCurrentHref(): string {
+    return this.currentHref;
+  }
+  getPath(): string {
+    return '/callback';
+  }
+  getOrigin(): string {
+    return 'http://localhost:4200';
+  }
+}
+
+const buildOidc = ({ href, storage }: { href: string; storage: Storage }) => {
+  const publishedEvents: Array<{ name: string; data: unknown }> = [];
+  const configurationName = 'default';
+  const configuration = {
+    client_id: 'interactive.public.short',
+    redirect_uri: 'http://localhost:4200/authentication/callback',
+    silent_redirect_uri: 'http://localhost:4200/authentication/silent-callback',
+    scope: 'openid profile email',
+    authority: 'http://api',
+    refresh_time_before_tokens_expiration_in_second: 70,
+    token_request_timeout: 30000,
+    authority_configuration: null,
+    storage,
+    login_state_storage: storage,
+    // no service_worker_relative_url -> initWorkerAsync returns null
+  };
+  const oidc: any = {
+    configuration,
+    configurationName,
+    location: new FakeLocation(href),
+    publishEvent: (name: string, data: unknown) => {
+      publishedEvents.push({ name, data });
+    },
+    initAsync: vi.fn(async () => ({
+      issuer: 'http://api',
+      authorizationEndpoint: 'http://api/connect/authorize',
+      tokenEndpoint: 'http://api/connect/token',
+      checkSessionIframe: 'http://api/connect/checksession',
+    })),
+    startCheckSessionAsync: vi.fn(async () => undefined),
+  };
+  return { oidc, publishedEvents };
+};
+
+describe('loginCallbackAsync — state/nonce guards (issue #1678)', () => {
+  let storage: Storage;
+
+  beforeEach(() => {
+    storage = makeStorage();
+  });
+
+  it('throws OidcStateError(STATE_MISSING) when stored state is missing but callback URL contains state', async () => {
+    // No `oidc.state.default` written into storage at all (simulates a
+    // private-browsing tab, manual storage clear, or browser eviction
+    // between the authorize redirect and the callback).
+    const href = 'http://localhost:4200/authentication/callback?code=abc&state=server-state-value';
+    const { oidc, publishedEvents } = buildOidc({ href, storage });
+
+    await expect(loginCallbackAsync(oidc)()).rejects.toBeInstanceOf(OidcStateError);
+    await expect(loginCallbackAsync(oidc)()).rejects.toMatchObject({
+      code: OidcStateErrorCode.STATE_MISSING,
+    });
+
+    // The error must also be published as a loginCallbackAsync_error event
+    // so listeners (incl. the React provider) can react to it.
+    const errorEvent = publishedEvents.find(e => e.name === 'loginCallbackAsync_error');
+    expect(errorEvent).toBeDefined();
+    expect(errorEvent!.data).toBeInstanceOf(OidcStateError);
+  });
+
+  it('throws OidcStateError(STATE_MISMATCH) when the stored state differs from the returned one', async () => {
+    storage[`oidc.state.default`] = 'stored-state-value';
+    storage[`oidc.nonce.default`] = 'stored-nonce-value';
+    const href =
+      'http://localhost:4200/authentication/callback?code=abc&state=different-state-value';
+    const { oidc } = buildOidc({ href, storage });
+
+    await expect(loginCallbackAsync(oidc)()).rejects.toBeInstanceOf(OidcStateError);
+    await expect(loginCallbackAsync(oidc)()).rejects.toMatchObject({
+      code: OidcStateErrorCode.STATE_MISMATCH,
+    });
+  });
+
+  it('throws OidcStateError(NONCE_MISSING) when state is valid but nonce is missing from storage', async () => {
+    storage[`oidc.state.default`] = 'matching-state';
+    // No oidc.nonce.default written -> getNonceAsync returns { nonce: undefined }
+    const href = 'http://localhost:4200/authentication/callback?code=abc&state=matching-state';
+    const { oidc } = buildOidc({ href, storage });
+
+    await expect(loginCallbackAsync(oidc)()).rejects.toBeInstanceOf(OidcStateError);
+    await expect(loginCallbackAsync(oidc)()).rejects.toMatchObject({
+      code: OidcStateErrorCode.NONCE_MISSING,
+    });
+  });
+
+  it('does not throw a generic TypeError when state and nonce are both missing', async () => {
+    // Regression: before the fix, a missing nonce would surface as
+    // "Cannot read properties of undefined (reading 'nonce')" when reaching
+    // isTokensOidcValid(..., nonceData.nonce, ...).
+    const href = 'http://localhost:4200/authentication/callback?code=abc&state=server-state-value';
+    const { oidc } = buildOidc({ href, storage });
+
+    let caught: unknown;
+    try {
+      await loginCallbackAsync(oidc)();
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(OidcStateError);
+    expect(caught).not.toBeInstanceOf(TypeError);
+  });
+});

package/src/login.ts

@@ -5,6 +5,7 @@ import { initWorkerAsync } from './initWorker.js';
 import { generateJwkAsync, generateJwtDemonstratingProofOfPossessionAsync } from './jwt';
 import { ILOidcLocation } from './location';
 import Oidc from './oidc';
+import { OidcStateError, OidcStateErrorCode } from './oidcStateError.js';
 import { isTokensOidcValid } from './parseTokens.js';
 import { performAuthorizationRequestAsync, performFirstTokenRequestAsync } from './requests.js';
 import { getParseQueryStringFromLocation } from './route-utils.js';
@@ -156,8 +157,28 @@ export const loginCallbackAsync =
           `Issuer not valid (expected: ${oidcServerConfiguration.issuer}, received: ${queryParams.iss})`,
         );
       }
-      if (queryParams.state && queryParams.state !== state) {
-        throw new Error(`State not valid (expected: ${state}, received: ${queryParams.state})`);
+      // Surface missing / mismatched login state as a typed, identifiable error
+      // rather than a generic TypeError when later dereferencing nonceData.nonce.
+      // See https://github.com/AxaFrance/oidc-client/issues/1678
+      if (queryParams.state) {
+        if (!state) {
+          throw new OidcStateError(
+            OidcStateErrorCode.STATE_MISSING,
+            'OIDC state is missing from storage. The login state may have been cleared between the authorization redirect and the callback (e.g., private browsing, storage cleared, or browser eviction).',
+          );
+        }
+        if (queryParams.state !== state) {
+          throw new OidcStateError(
+            OidcStateErrorCode.STATE_MISMATCH,
+            `OIDC state does not match the stored one (expected: ${state}, received: ${queryParams.state}).`,
+          );
+        }
+      }
+      if (!nonceData || !nonceData.nonce) {
+        throw new OidcStateError(
+          OidcStateErrorCode.NONCE_MISSING,
+          'OIDC nonce is missing from storage. The login state may have been cleared between the authorization redirect and the callback (e.g., private browsing, storage cleared, or browser eviction).',
+        );
       }
 
       const data = {

package/src/logout.spec.ts

@@ -2,8 +2,9 @@
 
 import { describe, expect, it, vi } from 'vitest';
 
+import { eventNames } from './events';
 import { ILOidcLocation } from './location';
-import { logoutAsync } from './logout';
+import { clearSessionAsync, logoutAsync } from './logout';
 
 describe('Logout test suite', () => {
   const expectedFinalUrl =
@@ -138,4 +139,210 @@ describe('Logout test suite', () => {
       expect(finalUrl).toBe(expectedFinalUrl);
     },
   );
+
+  it('navigates to end_session_endpoint before clearing the local session (issue #1677)', async () => {
+    // This is the regression test for the race described in issue #1677.
+    // `OidcProvider`/`OidcSecure` watches `oidc.tokens`; if `destroyAsync`
+    // runs before `oicLocation.open`, the React tree can briefly observe a
+    // null token state and kick off a new auth flow before the navigation
+    // to the IdP's end-session endpoint commits.
+    const configuration = {
+      client_id: 'interactive.public.short',
+      authority: 'http://api',
+      logout_tokens_to_invalidate: ['access_token', 'refresh_token'],
+    };
+
+    const callOrder: string[] = [];
+
+    const mockFetchFn = vi.fn().mockImplementation(() => {
+      callOrder.push('revoke');
+      return Promise.resolve({ status: 200 });
+    });
+
+    const oidc: any = {
+      configuration,
+      tokens: {
+        idToken: 'abcd',
+        accessToken: 'abcd',
+        refreshToken: 'abdc',
+        idTokenPayload: { sub: 'sub-123' },
+      },
+      isLoggingOut: false,
+      initAsync: () =>
+        Promise.resolve({
+          revocationEndpoint: 'http://api/connect/revocation',
+          endSessionEndpoint: 'http://api/connect/endsession',
+        }),
+      destroyAsync: vi.fn().mockImplementation(() => {
+        callOrder.push('destroyAsync');
+        oidc.tokens = null;
+        return Promise.resolve();
+      }),
+      logoutSameTabAsync: () => Promise.resolve(),
+      publishEvent: (name: string) => callOrder.push(`publishEvent:${name}`),
+    };
+
+    const oidcDatabase = { default: oidc };
+
+    let navigatedUrl = '';
+    class OidcLocationMock implements ILOidcLocation {
+      open(url: string): void {
+        callOrder.push('open');
+        navigatedUrl = url;
+      }
+      getCurrentHref() {
+        return '';
+      }
+      getPath() {
+        return '';
+      }
+      reload() {
+        callOrder.push('reload');
+      }
+      getOrigin() {
+        return 'http://localhost:4200';
+      }
+    }
+
+    await logoutAsync(
+      oidc,
+      oidcDatabase,
+      mockFetchFn,
+      console,
+      new OidcLocationMock(),
+    )('/logged_out', null);
+
+    // Revocation comes first (so tokens are still valid when revoked),
+    // navigation comes second (page starts unloading), and only then we
+    // clear local state and broadcast `logout_from_same_tab`.
+    expect(callOrder[0]).toBe('revoke');
+    expect(callOrder[1]).toBe('revoke');
+    expect(callOrder[2]).toBe('open');
+    expect(callOrder.indexOf('destroyAsync')).toBeGreaterThan(callOrder.indexOf('open'));
+    expect(callOrder.indexOf(`publishEvent:${eventNames.logout_from_same_tab}`)).toBeGreaterThan(
+      callOrder.indexOf('open'),
+    );
+
+    // The id_token_hint must still be present on the navigation URL, even
+    // though local tokens have been cleared by `destroyAsync` afterwards.
+    expect(navigatedUrl).toContain('id_token_hint=abcd');
+    expect(navigatedUrl).toContain(
+      'post_logout_redirect_uri=http%3A%2F%2Flocalhost%3A4200%2Flogged_out',
+    );
+
+    // The flag stays set after the call returns: the page is expected to be
+    // unloading and any UI re-render that briefly observes `tokens === null`
+    // should skip starting a new login flow.
+    expect(oidc.isLoggingOut).toBe(true);
+  });
+
+  it('resets isLoggingOut and does not navigate when no_reload is requested', async () => {
+    const configuration = {
+      client_id: 'interactive.public.short',
+      authority: 'http://api',
+      logout_tokens_to_invalidate: [],
+    };
+
+    const events: string[] = [];
+    let navigated = false;
+    const oidc: any = {
+      configuration,
+      tokens: {
+        idToken: 'abcd',
+        accessToken: 'abcd',
+        refreshToken: 'abdc',
+        idTokenPayload: { sub: 'sub-123' },
+      },
+      isLoggingOut: false,
+      initAsync: () =>
+        Promise.resolve({
+          revocationEndpoint: 'http://api/connect/revocation',
+          endSessionEndpoint: 'http://api/connect/endsession',
+        }),
+      destroyAsync: () => Promise.resolve(),
+      logoutSameTabAsync: () => Promise.resolve(),
+      publishEvent: (name: string) => events.push(name),
+    };
+    const oidcDatabase = { default: oidc };
+
+    class OidcLocationMock implements ILOidcLocation {
+      open() {
+        navigated = true;
+      }
+      getCurrentHref() {
+        return '';
+      }
+      getPath() {
+        return '';
+      }
+      reload() {
+        navigated = true;
+      }
+      getOrigin() {
+        return 'http://localhost:4200';
+      }
+    }
+
+    await logoutAsync(
+      oidc,
+      oidcDatabase,
+      vi.fn(),
+      console,
+      new OidcLocationMock(),
+    )('/logged_out', { 'no_reload:oidc': 'true' });
+
+    expect(navigated).toBe(false);
+    expect(events).toContain(eventNames.logout_from_same_tab);
+    expect(oidc.isLoggingOut).toBe(false);
+  });
+
+  describe('clearSessionAsync', () => {
+    it('clears the local session and emits logout_from_same_tab without contacting the IdP', async () => {
+      const events: { name: string; data: unknown }[] = [];
+      const oidc: any = {
+        configuration: { client_id: 'interactive.public.short' },
+        tokens: {
+          idToken: 'abcd',
+          accessToken: 'abcd',
+          refreshToken: 'abdc',
+          idTokenPayload: { sub: 'sub-123' },
+        },
+        destroyAsync: vi.fn().mockImplementation(status => {
+          oidc.tokens = null;
+          events.push({ name: 'destroyAsync', data: status });
+          return Promise.resolve();
+        }),
+        logoutSameTabAsync: vi.fn().mockResolvedValue(undefined),
+        publishEvent: (name: string, data: unknown) => events.push({ name, data }),
+      };
+      const oidcDatabase = { default: oidc };
+
+      await clearSessionAsync(oidc, oidcDatabase)();
+
+      expect(oidc.destroyAsync).toHaveBeenCalledWith('LOGGED_OUT');
+      expect(oidc.tokens).toBeNull();
+      expect(events.some(e => e.name === eventNames.logout_from_same_tab)).toBe(true);
+    });
+
+    it('calls logoutSameTabAsync for sibling OIDC clients registered in the same tab', async () => {
+      const oidc: any = {
+        configuration: { client_id: 'interactive.public.short' },
+        tokens: {
+          idToken: 'abcd',
+          accessToken: 'abcd',
+          refreshToken: 'abdc',
+          idTokenPayload: { sub: 'sub-123' },
+        },
+        destroyAsync: () => Promise.resolve(),
+        logoutSameTabAsync: vi.fn().mockResolvedValue(undefined),
+        publishEvent: () => undefined,
+      };
+      const sibling: any = { configuration: { client_id: 'other' } };
+      const oidcDatabase = { default: oidc, other: sibling };
+
+      await clearSessionAsync(oidc, oidcDatabase)();
+
+      expect(oidc.logoutSameTabAsync).toHaveBeenCalledWith('interactive.public.short', 'sub-123');
+    });
+  });
 });

package/src/logout.ts

@@ -59,6 +59,58 @@ export const destroyAsync = oidc => async status => {
   oidc.userInfo = null;
 };
 
+/**
+ * Clears the local OIDC session (tokens, user info, service-worker storage)
+ * and broadcasts `logout_from_same_tab` to any other OIDC clients registered
+ * in the same tab.
+ *
+ * It is intentionally decoupled from `logoutAsync`: callers that want to drop
+ * the local session without contacting the identity provider — for example a
+ * service-worker-only flow, a SPA-only logout, or an error-recovery path —
+ * can use this helper directly. `logoutAsync` itself calls it as the very
+ * last step, after the browser navigation to `end_session_endpoint` has been
+ * scheduled, so that the React tree never observes a transient "no tokens"
+ * state before the page is unloaded.
+ */
+export const clearSessionAsync = (oidc, oidcDatabase) => async () => {
+  const sub = oidc.tokens?.idTokenPayload?.sub ?? null;
+  await oidc.destroyAsync('LOGGED_OUT');
+  for (const [, itemOidc] of Object.entries(oidcDatabase)) {
+    if (itemOidc !== oidc) {
+      // @ts-ignore
+      await oidc.logoutSameTabAsync(oidc.configuration.client_id, sub);
+    } else {
+      oidc.publishEvent(eventNames.logout_from_same_tab, {});
+    }
+  }
+};
+
+const buildEndSessionUrl = (
+  endSessionEndpoint: string,
+  endPointExtras: StringMap,
+  idToken: string,
+  postLogoutRedirectUri: string | null,
+): string => {
+  if (!('id_token_hint' in endPointExtras)) {
+    endPointExtras['id_token_hint'] = idToken;
+  }
+  if (!('post_logout_redirect_uri' in endPointExtras) && postLogoutRedirectUri !== null) {
+    endPointExtras['post_logout_redirect_uri'] = postLogoutRedirectUri;
+  }
+  let queryString = '';
+  for (const [key, value] of Object.entries(endPointExtras)) {
+    if (value !== null && value !== undefined) {
+      if (queryString === '') {
+        queryString += '?';
+      } else {
+        queryString += '&';
+      }
+      queryString += `${key}=${encodeURIComponent(value)}`;
+    }
+  }
+  return `${endSessionEndpoint}${queryString}`;
+};
+
 export const logoutAsync =
   (oidc, oidcDatabase, fetch, console, oicLocation: ILOidcLocation) =>
   async (callbackPathOrUrl: string | null | undefined = undefined, extras: StringMap = null) => {
@@ -79,94 +131,111 @@ export const logoutAsync =
     if (callbackPathOrUrl) {
       isUri = callbackPathOrUrl.includes('https://') || callbackPathOrUrl.includes('http://');
     }
-    const url = isUri ? callbackPathOrUrl : oicLocation.getOrigin() + path;
+    const postLogoutRedirectUri =
+      callbackPathOrUrl === null
+        ? null
+        : isUri
+          ? callbackPathOrUrl
+          : oicLocation.getOrigin() + path;
+    // Capture identifiers from the live session *before* any clear happens, so the
+    // values stay valid no matter when we drop local state.
     // @ts-ignore
     const idToken = oidc.tokens ? oidc.tokens.idToken : '';
+
+    // Mark the instance as "logout in progress" so consumers (OidcSecure, route
+    // guards, silent renew, 401 retry interceptors, …) can back off from
+    // triggering a new auth flow during the window between us clearing the
+    // local session and the browser actually navigating away.
+    oidc.isLoggingOut = true;
+
     try {
-      const revocationEndpoint = oidcServerConfiguration.revocationEndpoint;
-      if (revocationEndpoint) {
-        const promises = [];
-        const accessToken = oidc.tokens ? oidc.tokens.accessToken : null;
-        if (
-          accessToken &&
-          configuration.logout_tokens_to_invalidate.includes(oidcLogoutTokens.access_token)
-        ) {
-          const revokeAccessTokenExtras = extractExtras(extras, ':revoke_access_token');
-          const revokeAccessTokenPromise = performRevocationRequestAsync(fetch)(
-            revocationEndpoint,
-            accessToken,
-            TOKEN_TYPE.access_token,
-            configuration.client_id,
-            revokeAccessTokenExtras,
-          );
-          promises.push(revokeAccessTokenPromise);
-        }
-        const refreshToken = oidc.tokens ? oidc.tokens.refreshToken : null;
-        if (
-          refreshToken &&
-          configuration.logout_tokens_to_invalidate.includes(oidcLogoutTokens.refresh_token)
-        ) {
-          const revokeAccessTokenExtras = extractExtras(extras, ':revoke_refresh_token');
-          const revokeRefreshTokenPromise = performRevocationRequestAsync(fetch)(
-            revocationEndpoint,
-            refreshToken,
-            TOKEN_TYPE.refresh_token,
-            configuration.client_id,
-            revokeAccessTokenExtras,
-          );
-          promises.push(revokeRefreshTokenPromise);
-        }
-        if (promises.length > 0) {
-          await Promise.all(promises);
+      try {
+        const revocationEndpoint = oidcServerConfiguration.revocationEndpoint;
+        if (revocationEndpoint) {
+          const promises = [];
+          const accessToken = oidc.tokens ? oidc.tokens.accessToken : null;
+          if (
+            accessToken &&
+            configuration.logout_tokens_to_invalidate.includes(oidcLogoutTokens.access_token)
+          ) {
+            const revokeAccessTokenExtras = extractExtras(extras, ':revoke_access_token');
+            const revokeAccessTokenPromise = performRevocationRequestAsync(fetch)(
+              revocationEndpoint,
+              accessToken,
+              TOKEN_TYPE.access_token,
+              configuration.client_id,
+              revokeAccessTokenExtras,
+            );
+            promises.push(revokeAccessTokenPromise);
+          }
+          const refreshToken = oidc.tokens ? oidc.tokens.refreshToken : null;
+          if (
+            refreshToken &&
+            configuration.logout_tokens_to_invalidate.includes(oidcLogoutTokens.refresh_token)
+          ) {
+            const revokeAccessTokenExtras = extractExtras(extras, ':revoke_refresh_token');
+            const revokeRefreshTokenPromise = performRevocationRequestAsync(fetch)(
+              revocationEndpoint,
+              refreshToken,
+              TOKEN_TYPE.refresh_token,
+              configuration.client_id,
+              revokeAccessTokenExtras,
+            );
+            promises.push(revokeRefreshTokenPromise);
+          }
+          if (promises.length > 0) {
+            // Revocation must be awaited *before* navigation, so a cancelled
+            // navigation can never leave valid tokens behind both in storage
+            // and on the authorization server.
+            await Promise.all(promises);
+          }
         }
+      } catch (exception) {
+        console.warn(
+          'logoutAsync: error when revoking tokens, if the error persist, you ay configure property logout_tokens_to_invalidate from configuration to avoid this error',
+        );
+        console.warn(exception);
       }
-    } catch (exception) {
-      console.warn(
-        'logoutAsync: error when revoking tokens, if the error persist, you ay configure property logout_tokens_to_invalidate from configuration to avoid this error',
-      );
-      console.warn(exception);
-    }
-    const sub = oidc.tokens?.idTokenPayload?.sub ?? null;
-
-    await oidc.destroyAsync('LOGGED_OUT');
-    for (const [, itemOidc] of Object.entries(oidcDatabase)) {
-      if (itemOidc !== oidc) {
-        // @ts-ignore
-        await oidc.logoutSameTabAsync(oidc.configuration.client_id, sub);
-      } else {
-        oidc.publishEvent(eventNames.logout_from_same_tab, {});
-      }
-    }
-
-    const oidcExtras = extractExtras(extras, ':oidc');
-    const noReload = oidcExtras && oidcExtras['no_reload'] === 'true';
-
-    if (noReload) {
-      return;
-    }
 
-    const endPointExtras = keepExtras(extras);
+      const oidcExtras = extractExtras(extras, ':oidc');
+      const noReload = oidcExtras && oidcExtras['no_reload'] === 'true';
 
-    if (oidcServerConfiguration.endSessionEndpoint) {
-      if (!('id_token_hint' in endPointExtras)) {
-        endPointExtras['id_token_hint'] = idToken;
-      }
-      if (!('post_logout_redirect_uri' in endPointExtras) && callbackPathOrUrl !== null) {
-        endPointExtras['post_logout_redirect_uri'] = url;
+      if (noReload) {
+        // No navigation happens here: this branch is essentially a "clear local
+        // session" call dressed as a logout. We can drop state immediately and
+        // reset the flag since the call returns normally to the caller.
+        await clearSessionAsync(oidc, oidcDatabase)();
+        oidc.isLoggingOut = false;
+        return;
       }
-      let queryString = '';
-      for (const [key, value] of Object.entries(endPointExtras)) {
-        if (value !== null && value !== undefined) {
-          if (queryString === '') {
-            queryString += '?';
-          } else {
-            queryString += '&';
-          }
-          queryString += `${key}=${encodeURIComponent(value)}`;
-        }
+
+      // Navigate to the end-session endpoint (or reload) *before* clearing the
+      // local session. This closes the race where `OidcProvider` /
+      // `OidcSecure` / silent-renew timers observe a null `tokens` and kick
+      // off a new auth flow in the window between local clear and navigation.
+      const endPointExtras = keepExtras(extras);
+      if (oidcServerConfiguration.endSessionEndpoint) {
+        const endSessionUrl = buildEndSessionUrl(
+          oidcServerConfiguration.endSessionEndpoint,
+          endPointExtras,
+          idToken,
+          postLogoutRedirectUri,
+        );
+        oicLocation.open(endSessionUrl);
+      } else {
+        oicLocation.reload();
       }
-      oicLocation.open(`${oidcServerConfiguration.endSessionEndpoint}${queryString}`);
-    } else {
-      oicLocation.reload();
+
+      // Now that navigation has been scheduled, drop the local session. By the
+      // time React re-renders against the null tokens the page is already
+      // unloading; if for any reason it is not (e.g. navigation cancelled by a
+      // `beforeunload` handler) the `isLoggingOut` flag stays set so guards
+      // still know not to start a fresh auth flow.
+      await clearSessionAsync(oidc, oidcDatabase)();
+    } catch (exception) {
+      // If anything went wrong, reset the flag so the app is not stuck in a
+      // "logging out forever" state.
+      oidc.isLoggingOut = false;
+      throw exception;
     }
   };