@dloizides/auth-web 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 1.10.0 (2026-07-17)
+
+Additive release adding the shared **logout sequencer**. Purely additive — every
+1.9.x export is unchanged, no component behaviour changes, and apps that do not
+import `performBffLogout` are byte-identical.
+
+### Added
+
+- **`performBffLogout({ client, onClearSession?, onRedirect?, onError?, navigateToIdp? })`**
+  — the shared logout sequence, extracted because all six consuming apps
+  hand-rolled it in their own `AuthProvider` and the orderings disagreed. Runs:
+  1. `onClearSession()` — local state first, so the UI reflects the sign-out
+     immediately.
+  2. `await client.logout({ redirect: false })` — lets the `POST /bff/logout`
+     SETTLE, and takes the IdP logout URL rather than letting the client navigate
+     mid-sequence.
+  3. Navigates exactly once, last: to the IdP logout URL when the BFF returned
+     one (ending the IdP browser session), otherwise `onRedirect()`. When it
+     navigates to the IdP it deliberately does NOT also call `onRedirect` — two
+     competing navigations would race, and the IdP round-trip already returns the
+     user to the app.
+
+  Never rejects; always navigates, even when the BFF logout fails (a down BFF
+  must not trap the user on a page they asked to leave).
+- **`BffLogoutClient`** / **`PerformBffLogoutOptions`** types.
+
+### Why
+
+`zygos-web` and `agora-web` navigated FIRST and called the BFF second:
+
+```ts
+redirectTo('/(auth)/login');   // → window.location.replace() → document unload
+await bffAuthClient.logout();  // races the unload — may never be sent
+```
+
+That is wrong twice over:
+
+1. **The BFF call can be cancelled.** A document navigation kills in-flight
+   fetches, so `POST /bff/logout` may never reach the server: the SPA looks
+   logged out while the httpOnly session cookie stays alive. The `catch` logged
+   it "non-fatal", so the defect was silent.
+2. **The IdP session survives.** `BffAuthClient.logout()` ends the identity
+   provider's browser session with a top-level navigation to its RP-initiated
+   logout URL (only a real navigation carries the IdP's own cookie — a
+   back-channel POST cannot clear it). An app that navigates to its own login
+   route first pre-empts that navigation, so the IdP still considers the user
+   signed in and the next authorize round-trip silently re-authenticates them —
+   the "sign-out that signs you back in" bug the client's own docs warn about.
+
+Synthetic tests that stub the client never reproduce either failure (there is no
+real navigation to cancel the request), which is why they survived. The helper
+owns the sequence so neither can be reintroduced per-app.
+
 ## 1.8.0 (2026-07-09)
 
 Additive release for the Move 2b passkey in-app rebuild — the passkey ceremony

package/dist/index.d.mts

@@ -1694,30 +1694,6 @@ declare const enum PasskeyCeremonyStatus {
     Error = "error"
 }
 
-/**
- * Navigation helpers for the passkey (WebAuthn) BFF endpoints.
- *
- * Unlike the device-PIN client (which is plain `fetch`), the passkey login and
- * registration ceremonies are NOT fetches — they are full-page BROWSER
- * NAVIGATIONS. The BFF (`Bff.AspNetCore` 1.3.x) drives the WebAuthn ceremony
- * through Keycloak's hosted pages, then redirects the browser back:
- *  - login:        `/bff/passkey/login?returnUrl=<rel>` → on success the browser
- *    lands on `returnUrl` with the session cookie already set;
- *  - registration: `/bff/passkey/register?returnUrl=<rel>` → Keycloak re-auths
- *    the user (password) then runs the credential-creation ceremony, returning
- *    the browser to `returnUrl?passkey=registered`;
- *  - failure / cancel: the BFF redirects to `<login>?passkeyError=cancelled` or
- *    `<login>?passkeyError=failed`.
- *
- * react-query-FREE by construction: there is NO fetch here at all — every
- * function is a pure `window.location` read or `window.location.assign`. The
- * login route group has no QueryClient provider, so the passkey login button
- * (which lives there) MUST avoid any react-query primitive; navigation satisfies
- * that trivially.
- *
- * All reads are SSR-safe: when `window` is undefined (server render / native)
- * they return a benign default rather than throwing.
- */
 /** The recognised passkey error codes the BFF sends back via `?passkeyError=`. */
 type PasskeyErrorCode = 'cancelled' | 'failed';
 /**
@@ -1949,6 +1925,97 @@ declare function resolvePostLoginRoute(user: BffUser, table: RoleRouteTable): st
  */
 declare function resolveAccessibleRoutes(user: BffUser, table: RoleRouteTable): RoleRoute[];
 
+/**
+ * `performBffLogout` — the shared logout sequencer.
+ *
+ * Every app hand-rolled its own logout ordering inside its `AuthProvider`, and
+ * the orderings disagreed. Two of them (zygos-web, agora-web) navigated FIRST
+ * and called the BFF second:
+ *
+ * ```ts
+ * redirectTo('/(auth)/login');   // window.location.replace() → document unload
+ * await bffAuthClient.logout();  // races the unload — may never be sent
+ * ```
+ *
+ * That is wrong twice over:
+ *
+ * 1. **The BFF call can be cancelled.** A document navigation kills in-flight
+ *    fetches, so `POST /bff/logout` may never reach the server: the SPA looks
+ *    logged out while the httpOnly session cookie stays ALIVE. The `catch`
+ *    logged it "non-fatal", so the defect was silent.
+ * 2. **The IdP session survives.** `BffAuthClient.logout()` ends the *identity
+ *    provider's* browser session by doing a top-level navigation to the IdP's
+ *    RP-initiated logout URL (only a real navigation carries the IdP's own
+ *    cookie — a back-channel POST cannot clear it). An app that navigates to
+ *    its own login route first pre-empts that navigation, so the IdP still
+ *    considers the user signed in and the next authorize round-trip silently
+ *    re-authenticates them. That is the "sign-out that signs you back in" bug
+ *    the client's own docs warn about.
+ *
+ * This helper owns the whole sequence so neither can be reintroduced per-app:
+ *
+ *   1. `onClearSession()` — drop local state immediately so the UI reflects the
+ *      sign-out right away (perceived performance; no spinner needed).
+ *   2. `await client.logout({ redirect: false })` — let the network call SETTLE,
+ *      and take the IdP logout URL rather than letting the client navigate mid-
+ *      sequence. Errors are captured, never rethrown.
+ *   3. Navigate LAST, exactly once, when nothing is in flight to cancel:
+ *      - an IdP logout URL → a top-level navigation to the IdP, which ends that
+ *        session and bounces the user back. `onRedirect` is deliberately NOT
+ *        called: two competing navigations would race, and the IdP round-trip
+ *        already returns the user to the app.
+ *      - otherwise (ROPC / OTP / device-PIN logins never had an IdP cookie, so
+ *        the URL is `null`) → `onRedirect()`, the app's own login route.
+ *
+ * Step 3 runs even when step 2 rejects: a BFF that is down must not trap the
+ * user on a page they asked to leave. The local session is already gone, so the
+ * client-side sign-out holds regardless.
+ *
+ * Headless and framework-free: it takes callbacks, so an app can pair it with
+ * Redux, a context, expo-router, or `window.location` without this package
+ * knowing about any of them.
+ */
+/**
+ * The only part of a `BffAuthClient` this helper needs. Structural, so it is
+ * trivially fakeable in tests and does not couple to the full client surface.
+ */
+interface BffLogoutClient {
+    /**
+     * `POST /bff/logout` — ends the server-side session. With `redirect: false`
+     * it returns the IdP's RP-initiated logout URL (or `null` when the session
+     * never involved an IdP browser cookie) instead of navigating there itself.
+     */
+    logout: (options?: {
+        redirect?: boolean;
+    }) => Promise<string | null>;
+}
+/** Callbacks + client for {@link performBffLogout}. */
+interface PerformBffLogoutOptions {
+    /** The BFF auth client whose `logout()` ends the server-side session. */
+    client: BffLogoutClient;
+    /** Drop local session state. Runs BEFORE the network call. Optional. */
+    onClearSession?: () => void;
+    /**
+     * Navigate to the app's logged-out route. Runs only AFTER the network call
+     * settles, and only when there is no IdP logout URL to honour. Optional.
+     */
+    onRedirect?: () => void;
+    /** Observe a failed logout step (e.g. to log it). Never rethrown. Optional. */
+    onError?: (error: Error) => void;
+    /**
+     * Test seam: perform the top-level navigation to the IdP logout URL. Defaults
+     * to `window.location.assign`. Must be a real navigation — a `fetch` here
+     * would not carry the IdP cookie and would silently fail to end the session.
+     */
+    navigateToIdp?: (url: string) => void;
+}
+/**
+ * End the session: clear locally, await the BFF, then navigate exactly once.
+ *
+ * Never rejects — callers may `void` it safely.
+ */
+declare function performBffLogout(options: Readonly<PerformBffLogoutOptions>): Promise<void>;
+
 /**
  * The discrete ways a password can fail the shared client-side policy.
  *
@@ -1994,4 +2061,4 @@ declare function validatePasswordPolicy(password: string): PasswordPolicyError[]
 /** `true` when the password satisfies every policy rule. */
 declare function isPasswordValid(password: string): boolean;
 
-export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, PasskeyCeremonyMode, PasskeyCeremonyStatus, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePasskeyCeremonyOptions, type UsePasskeyCeremonyResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePasskeyCeremony, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };
+export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type BffLogoutClient, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, PasskeyCeremonyMode, PasskeyCeremonyStatus, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, type PerformBffLogoutOptions, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePasskeyCeremonyOptions, type UsePasskeyCeremonyResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, performBffLogout, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePasskeyCeremony, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };

package/dist/index.d.ts

@@ -1694,30 +1694,6 @@ declare const enum PasskeyCeremonyStatus {
     Error = "error"
 }
 
-/**
- * Navigation helpers for the passkey (WebAuthn) BFF endpoints.
- *
- * Unlike the device-PIN client (which is plain `fetch`), the passkey login and
- * registration ceremonies are NOT fetches — they are full-page BROWSER
- * NAVIGATIONS. The BFF (`Bff.AspNetCore` 1.3.x) drives the WebAuthn ceremony
- * through Keycloak's hosted pages, then redirects the browser back:
- *  - login:        `/bff/passkey/login?returnUrl=<rel>` → on success the browser
- *    lands on `returnUrl` with the session cookie already set;
- *  - registration: `/bff/passkey/register?returnUrl=<rel>` → Keycloak re-auths
- *    the user (password) then runs the credential-creation ceremony, returning
- *    the browser to `returnUrl?passkey=registered`;
- *  - failure / cancel: the BFF redirects to `<login>?passkeyError=cancelled` or
- *    `<login>?passkeyError=failed`.
- *
- * react-query-FREE by construction: there is NO fetch here at all — every
- * function is a pure `window.location` read or `window.location.assign`. The
- * login route group has no QueryClient provider, so the passkey login button
- * (which lives there) MUST avoid any react-query primitive; navigation satisfies
- * that trivially.
- *
- * All reads are SSR-safe: when `window` is undefined (server render / native)
- * they return a benign default rather than throwing.
- */
 /** The recognised passkey error codes the BFF sends back via `?passkeyError=`. */
 type PasskeyErrorCode = 'cancelled' | 'failed';
 /**
@@ -1949,6 +1925,97 @@ declare function resolvePostLoginRoute(user: BffUser, table: RoleRouteTable): st
  */
 declare function resolveAccessibleRoutes(user: BffUser, table: RoleRouteTable): RoleRoute[];
 
+/**
+ * `performBffLogout` — the shared logout sequencer.
+ *
+ * Every app hand-rolled its own logout ordering inside its `AuthProvider`, and
+ * the orderings disagreed. Two of them (zygos-web, agora-web) navigated FIRST
+ * and called the BFF second:
+ *
+ * ```ts
+ * redirectTo('/(auth)/login');   // window.location.replace() → document unload
+ * await bffAuthClient.logout();  // races the unload — may never be sent
+ * ```
+ *
+ * That is wrong twice over:
+ *
+ * 1. **The BFF call can be cancelled.** A document navigation kills in-flight
+ *    fetches, so `POST /bff/logout` may never reach the server: the SPA looks
+ *    logged out while the httpOnly session cookie stays ALIVE. The `catch`
+ *    logged it "non-fatal", so the defect was silent.
+ * 2. **The IdP session survives.** `BffAuthClient.logout()` ends the *identity
+ *    provider's* browser session by doing a top-level navigation to the IdP's
+ *    RP-initiated logout URL (only a real navigation carries the IdP's own
+ *    cookie — a back-channel POST cannot clear it). An app that navigates to
+ *    its own login route first pre-empts that navigation, so the IdP still
+ *    considers the user signed in and the next authorize round-trip silently
+ *    re-authenticates them. That is the "sign-out that signs you back in" bug
+ *    the client's own docs warn about.
+ *
+ * This helper owns the whole sequence so neither can be reintroduced per-app:
+ *
+ *   1. `onClearSession()` — drop local state immediately so the UI reflects the
+ *      sign-out right away (perceived performance; no spinner needed).
+ *   2. `await client.logout({ redirect: false })` — let the network call SETTLE,
+ *      and take the IdP logout URL rather than letting the client navigate mid-
+ *      sequence. Errors are captured, never rethrown.
+ *   3. Navigate LAST, exactly once, when nothing is in flight to cancel:
+ *      - an IdP logout URL → a top-level navigation to the IdP, which ends that
+ *        session and bounces the user back. `onRedirect` is deliberately NOT
+ *        called: two competing navigations would race, and the IdP round-trip
+ *        already returns the user to the app.
+ *      - otherwise (ROPC / OTP / device-PIN logins never had an IdP cookie, so
+ *        the URL is `null`) → `onRedirect()`, the app's own login route.
+ *
+ * Step 3 runs even when step 2 rejects: a BFF that is down must not trap the
+ * user on a page they asked to leave. The local session is already gone, so the
+ * client-side sign-out holds regardless.
+ *
+ * Headless and framework-free: it takes callbacks, so an app can pair it with
+ * Redux, a context, expo-router, or `window.location` without this package
+ * knowing about any of them.
+ */
+/**
+ * The only part of a `BffAuthClient` this helper needs. Structural, so it is
+ * trivially fakeable in tests and does not couple to the full client surface.
+ */
+interface BffLogoutClient {
+    /**
+     * `POST /bff/logout` — ends the server-side session. With `redirect: false`
+     * it returns the IdP's RP-initiated logout URL (or `null` when the session
+     * never involved an IdP browser cookie) instead of navigating there itself.
+     */
+    logout: (options?: {
+        redirect?: boolean;
+    }) => Promise<string | null>;
+}
+/** Callbacks + client for {@link performBffLogout}. */
+interface PerformBffLogoutOptions {
+    /** The BFF auth client whose `logout()` ends the server-side session. */
+    client: BffLogoutClient;
+    /** Drop local session state. Runs BEFORE the network call. Optional. */
+    onClearSession?: () => void;
+    /**
+     * Navigate to the app's logged-out route. Runs only AFTER the network call
+     * settles, and only when there is no IdP logout URL to honour. Optional.
+     */
+    onRedirect?: () => void;
+    /** Observe a failed logout step (e.g. to log it). Never rethrown. Optional. */
+    onError?: (error: Error) => void;
+    /**
+     * Test seam: perform the top-level navigation to the IdP logout URL. Defaults
+     * to `window.location.assign`. Must be a real navigation — a `fetch` here
+     * would not carry the IdP cookie and would silently fail to end the session.
+     */
+    navigateToIdp?: (url: string) => void;
+}
+/**
+ * End the session: clear locally, await the BFF, then navigate exactly once.
+ *
+ * Never rejects — callers may `void` it safely.
+ */
+declare function performBffLogout(options: Readonly<PerformBffLogoutOptions>): Promise<void>;
+
 /**
  * The discrete ways a password can fail the shared client-side policy.
  *
@@ -1994,4 +2061,4 @@ declare function validatePasswordPolicy(password: string): PasswordPolicyError[]
 /** `true` when the password satisfies every policy rule. */
 declare function isPasswordValid(password: string): boolean;
 
-export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, PasskeyCeremonyMode, PasskeyCeremonyStatus, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePasskeyCeremonyOptions, type UsePasskeyCeremonyResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePasskeyCeremony, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };
+export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type BffLogoutClient, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, PasskeyCeremonyMode, PasskeyCeremonyStatus, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, type PerformBffLogoutOptions, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePasskeyCeremonyOptions, type UsePasskeyCeremonyResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, performBffLogout, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePasskeyCeremony, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };

package/dist/index.js

@@ -2520,6 +2520,18 @@ var PasskeyCeremonyMode = /* @__PURE__ */ ((PasskeyCeremonyMode2) => {
   return PasskeyCeremonyMode2;
 })(PasskeyCeremonyMode || {});
 
+// src/passkey/browserLocation.ts
+function getBrowserLocation() {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  const browserLocation = window.location;
+  if (browserLocation === void 0) {
+    return null;
+  }
+  return browserLocation;
+}
+
 // src/passkey/passkeyNavigation.ts
 var PASSKEY_LOGIN_ENDPOINT = "/bff/passkey/login";
 var PASSKEY_REGISTER_ENDPOINT = "/bff/passkey/register";
@@ -2533,22 +2545,25 @@ function buildNavigationUrl(endpoint, returnUrl) {
   return `${endpoint}?${RETURN_URL_PARAM}=${encodeURIComponent(returnUrl)}`;
 }
 function readSearchParams() {
-  if (typeof window === "undefined") {
+  const browserLocation = getBrowserLocation();
+  if (browserLocation === null) {
     return null;
   }
-  return new URLSearchParams(window.location.search);
+  return new URLSearchParams(browserLocation.search);
 }
 function startPasskeyLogin(returnUrl) {
-  if (typeof window === "undefined") {
+  const browserLocation = getBrowserLocation();
+  if (browserLocation === null) {
     return;
   }
-  window.location.assign(buildNavigationUrl(PASSKEY_LOGIN_ENDPOINT, returnUrl));
+  browserLocation.assign(buildNavigationUrl(PASSKEY_LOGIN_ENDPOINT, returnUrl));
 }
 function startPasskeyRegistration(returnUrl) {
-  if (typeof window === "undefined") {
+  const browserLocation = getBrowserLocation();
+  if (browserLocation === null) {
     return;
   }
-  window.location.assign(buildNavigationUrl(PASSKEY_REGISTER_ENDPOINT, returnUrl));
+  browserLocation.assign(buildNavigationUrl(PASSKEY_REGISTER_ENDPOINT, returnUrl));
 }
 function readPasskeyError() {
   const params = readSearchParams();
@@ -2725,8 +2740,9 @@ function usePasskeyCeremony(optionsArg) {
         onSuccess(user);
         return;
       }
-      if (mode === "login" /* Login */ && typeof window !== "undefined") {
-        window.location.assign(returnUrl);
+      const browserLocation = getBrowserLocation();
+      if (mode === "login" /* Login */ && browserLocation !== null) {
+        browserLocation.assign(returnUrl);
       }
     },
     [mode, onSuccess, returnUrl]
@@ -2848,10 +2864,11 @@ function PasskeyLoginButton({
 }
 var DEFAULT_RETURN_PATH = "/";
 function readCurrentPath() {
-  if (typeof window === "undefined") {
+  const browserLocation = getBrowserLocation();
+  if (browserLocation === null) {
     return DEFAULT_RETURN_PATH;
   }
-  return window.location.pathname;
+  return browserLocation.pathname;
 }
 function PasskeySettingsCard({
   returnUrl,
@@ -3269,6 +3286,43 @@ function resolveAccessibleRoutes(user, table) {
   return table.routes.filter((entry) => userRoles.has(entry.role));
 }
 
+// src/session/performBffLogout.ts
+function toError4(caught) {
+  return caught instanceof Error ? caught : new Error(String(caught));
+}
+function runGuarded(callback, onError) {
+  if (callback === void 0) {
+    return;
+  }
+  try {
+    callback();
+  } catch (caught) {
+    onError?.(toError4(caught));
+  }
+}
+function assignLocation(url) {
+  if (typeof window === "undefined") {
+    return;
+  }
+  window.location.assign(url);
+}
+async function performBffLogout(options) {
+  const { client, onClearSession, onRedirect, onError, navigateToIdp = assignLocation } = options;
+  runGuarded(onClearSession, onError);
+  let idpLogoutUrl = null;
+  try {
+    idpLogoutUrl = await client.logout({ redirect: false });
+  } catch (caught) {
+    onError?.(toError4(caught));
+  }
+  if (idpLogoutUrl !== null) {
+    const url = idpLogoutUrl;
+    runGuarded(() => navigateToIdp(url), onError);
+    return;
+  }
+  runGuarded(onRedirect, onError);
+}
+
 Object.defineProperty(exports, "BffAuthClient", {
   enumerable: true,
   get: function () { return authClient.BffAuthClient; }
@@ -3331,6 +3385,7 @@ exports.defaultAuthTheme = defaultAuthTheme;
 exports.isAllowedPinDigits = isAllowedPinDigits;
 exports.isPasswordValid = isPasswordValid;
 exports.isValidForgotPasswordEmail = isValidForgotPasswordEmail;
+exports.performBffLogout = performBffLogout;
 exports.readCachedPreferredMethod = readCachedPreferredMethod;
 exports.readPasskeyError = readPasskeyError;
 exports.readPasskeyRegistered = readPasskeyRegistered;