oidc-spa 8.2.1 → 8.2.3

package/src/core/createOidc.ts

@@ -25,12 +25,7 @@ import { notifyOtherTabsOfLogin, getPrOtherTabLogin } from "./loginPropagationTo
 import { getConfigId } from "./configId";
 import { oidcClientTsUserToTokens } from "./oidcClientTsUserToTokens";
 import { loginSilent } from "./loginSilent";
-import {
-    authResponseToUrl,
-    getPersistedRedirectAuthResponses,
-    setPersistedRedirectAuthResponses,
-    type AuthResponse
-} from "./AuthResponse";
+import { authResponseToUrl, type AuthResponse } from "./AuthResponse";
 import { getRootRelativeOriginalLocationHref, getRedirectAuthResponse } from "./earlyInit";
 import { getPersistedAuthState, persistAuthState } from "./persistedAuthState";
 import type { Oidc } from "./Oidc";
@@ -40,7 +35,7 @@ import {
     createLoginOrGoToAuthServer,
     getPrSafelyRestoredFromBfCacheAfterLoginBackNavigationOrInitializationError
 } from "./loginOrGoToAuthServer";
-import { createEphemeralSessionStorage } from "../tools/EphemeralSessionStorage";
+import { createLazySessionStorage } from "../tools/lazySessionStorage";
 import {
     startLoginOrRefreshProcess,
     waitForAllOtherOngoingLoginOrRefreshProcessesToComplete
@@ -53,6 +48,11 @@ import { prShouldLoadApp } from "./prShouldLoadApp";
 import { getBASE_URL } from "./BASE_URL";
 import { getIsLikelyDevServer } from "../tools/isLikelyDevServer";
 import { createObjectThatThrowsIfAccessed } from "../tools/createObjectThatThrowsIfAccessed";
+import {
+    evtIsThereMoreThanOneInstanceThatCantUserIframes,
+    notifyNewInstanceThatCantUseIframes
+} from "./instancesThatCantUseIframes";
+import { getDesiredPostLoginRedirectUrl } from "./desiredPostLoginRedirectUrl";
 
 // NOTE: Replaced at build time
 const VERSION = "{{OIDC_SPA_VERSION}}";
@@ -107,19 +107,6 @@ export type ParamsOfCreateOidc<
      *          extraTokenParams: { selectedCustomer: "xxx" }
      */
     extraTokenParams?: Record<string, string | undefined> | (() => Record<string, string | undefined>);
-    /**
-     * Usage discouraged, it's here because we don't want to assume too much on your
-     * usecase but I can't think of a scenario where you would want anything
-     * other than the current page.
-     *
-     * Where to redirect after successful login.
-     * Default: window.location.href (here)
-     *
-     * It does not need to include the origin, eg: "/dashboard"
-     *
-     * This parameter can also be passed to login() directly as `redirectUrl`.
-     */
-    postLoginRedirectUrl?: string;
 
     decodedIdTokenSchema?: {
         parse: (decodedIdToken_original: Oidc.Tokens.DecodedIdToken_OidcCoreSpec) => DecodedIdToken;
@@ -149,9 +136,43 @@ export type ParamsOfCreateOidc<
     autoLogin?: AutoLogin;
 
     /**
+     * Determines how session restoration is handled.
+     * Session restoration allows users to stay logged in between visits
+     * without needing to explicitly sign in each time.
+     *
+     * Options:
+     *
+     * - **"auto" (default)**:
+     *   Automatically selects the best method.
+     *   If the app’s domain shares a common parent domain with the authorization endpoint,
+     *   an iframe is used for silent session restoration.
+     *   Otherwise, a full-page redirect is used.
+     *
+     * - **"full page redirect"**:
+     *   Forces full-page reloads for session restoration.
+     *   Use this if your application is served with a restrictive CSP
+     *   (e.g., `Content-Security-Policy: frame-ancestors "none"`)
+     *   or `X-Frame-Options: DENY`, and you cannot modify those headers.
+     *   This mode provides a slightly less seamless UX and will lead oidc-spa to
+     *   store tokens in `localStorage` if multiple OIDC clients are used
+     *   (e.g., your app communicates with several APIs).
+     *
+     * - **"iframe"**:
+     *   Forces iframe-based session restoration.
+     *   In development, if you go in your browser setting and allow your auth server’s domain
+     *   to set third-party cookies this value will let you test your app
+     *   with the local dev server as it will behave in production.
+     *
+     *  See: https://docs.oidc-spa.dev/v/v8/resources/third-party-cookies-and-session-restoration
+     */
+    sessionRestorationMethod?: "iframe" | "full page redirect" | "auto";
+
+    /**
+     * @deprecated Use `sessionRestorationMethod: "full page redirect"` instead.
+     *
      * Default: false
      *
-     * See: https://docs.oidc-spa.dev/v/v8/resources/iframe-related-issues
+     * See: https://docs.oidc-spa.dev/v/v8/resources/third-party-cookies-and-session-restoration
      */
     noIframe?: boolean;
 
@@ -204,28 +225,28 @@ export type ParamsOfCreateOidc<
 
     /** @deprecated: Use BASE_URL (same thing, just renamed). */
     homeUrl?: string;
+
+    /**
+     * This parameter is irrelevant in most usecases.
+     * It tells where to redirect after a successful login or autoLogin.
+     *
+     * If you are not in autoLogin mode there is absolutely no reason to use
+     * this parameter since you can pass `login({ redirectUrl: "..." })`.
+     *
+     * It can only be useful in some edge case with `autoLogin: true`
+     * When you want to precisely redirect somewhere after login.
+     *
+     * This can make sense if you have multiple clients to talk with different
+     * API and no iframe capabilities.
+     */
+    postLoginRedirectUrl?: string;
 };
 
 const globalContext = {
     prOidcByConfigId: new Map<string, Promise<Oidc<any>>>(),
-    hasLogoutBeenCalled: id<boolean>(false),
-    evtRequestToPersistTokens: createEvt<{ configIdOfInstancePostingTheRequest: string }>()
+    hasLogoutBeenCalled: id<boolean>(false)
 };
 
-globalContext.evtRequestToPersistTokens.subscribe(() => {
-    const { authResponse } = getRedirectAuthResponse();
-
-    if (authResponse === undefined) {
-        return;
-    }
-
-    const { authResponses } = getPersistedRedirectAuthResponses();
-
-    setPersistedRedirectAuthResponses({
-        authResponses: [...authResponses, authResponse]
-    });
-});
-
 /** @see: https://docs.oidc-spa.dev/v/v8/usage */
 export async function createOidc<
     DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_OidcCoreSpec,
@@ -242,7 +263,7 @@ export async function createOidc<
         }
     }
 
-    const { issuerUri: issuerUri_params, clientId, scopes = ["profile"], debugLogs, ...rest } = params;
+    const { issuerUri: issuerUri_params, clientId, debugLogs, ...rest } = params;
 
     const issuerUri = toFullyQualifiedUrl({
         urlish: issuerUri_params,
@@ -298,7 +319,6 @@ export async function createOidc<
     const oidc = await createOidc_nonMemoized(rest, {
         issuerUri,
         clientId,
-        scopes,
         configId,
         log
     });
@@ -312,14 +332,10 @@ export async function createOidc_nonMemoized<
     DecodedIdToken extends Record<string, unknown>,
     AutoLogin extends boolean
 >(
-    params: Omit<
-        ParamsOfCreateOidc<DecodedIdToken, AutoLogin>,
-        "issuerUri" | "clientId" | "scopes" | "debugLogs"
-    >,
+    params: Omit<ParamsOfCreateOidc<DecodedIdToken, AutoLogin>, "issuerUri" | "clientId" | "debugLogs">,
     preProcessedParams: {
         issuerUri: string;
         clientId: string;
-        scopes: string[];
         configId: string;
         log: typeof console.log | undefined;
     }
@@ -357,12 +373,13 @@ export async function createOidc_nonMemoized<
         __unsafe_clientSecret,
         __unsafe_useIdTokenAsAccessToken = false,
         __metadata,
-        noIframe = false
+        scopes = ["openid", "profile"],
+        sessionRestorationMethod = params.autoLogin === true ? "full page redirect" : "auto"
     } = params;
 
     const BASE_URL_params = params.BASE_URL ?? params.homeUrl;
 
-    const { issuerUri, clientId, scopes, configId, log } = preProcessedParams;
+    const { issuerUri, clientId, configId, log } = preProcessedParams;
 
     const getExtraQueryParams = (() => {
         if (extraQueryParamsOrGetter === undefined) {
@@ -422,8 +439,7 @@ export async function createOidc_nonMemoized<
                 issuerUri,
                 clientId,
                 scopes,
-                configId,
-                homeUrlAndRedirectUri
+                oidcRedirectUri: homeUrlAndRedirectUri
             },
             null,
             2
@@ -435,8 +451,15 @@ export async function createOidc_nonMemoized<
     const oidcMetadata = __metadata ?? (await fetchOidcMetadata({ issuerUri }));
 
     const canUseIframe = (() => {
-        if (noIframe) {
-            return false;
+        switch (sessionRestorationMethod) {
+            case "auto":
+                break;
+            case "full page redirect":
+                return false;
+            case "iframe":
+                return true;
+            default:
+                assert<Equals<typeof sessionRestorationMethod, never>>;
         }
 
         third_party_cookies: {
@@ -515,7 +538,7 @@ export async function createOidc_nonMemoized<
                 log?.(
                     [
                         "Detected localhost environment.",
-                        "\nWhen reloading while logged in, you may briefly see",
+                        "\nWhen reloading while logged in, you will briefly see",
                         "some URL params appear in the address bar.",
                         "\nThis happens because session restore via iframe is disabled,",
                         "the browser treats your auth server as a third party.",
@@ -544,7 +567,7 @@ export async function createOidc_nonMemoized<
                             ];
                         })(),
                         "\n\nMore info:",
-                        "https://docs.oidc-spa.dev/v/v8/resources/end-of-third-party-cookies#when-are-cookies-considered-third-party"
+                        "https://docs.oidc-spa.dev/v/v8/resources/third-party-cookies-and-session-restoration"
                     ].join(" ")
                 );
             } else {
@@ -574,7 +597,7 @@ export async function createOidc_nonMemoized<
                             ];
                         })(),
                         "\nMore info:",
-                        "https://docs.oidc-spa.dev/v/v8/resources/end-of-third-party-cookies#when-are-cookies-considered-third-party"
+                        "https://docs.oidc-spa.dev/v/v8/resources/third-party-cookies-and-session-restoration"
                     ].join(" ")
                 );
             }
@@ -585,7 +608,16 @@ export async function createOidc_nonMemoized<
         return true;
     })();
 
-    let isUserStoreInMemoryOnly: boolean | undefined = undefined;
+    notifyNewInstanceThatCantUseIframes();
+
+    if (evtIsThereMoreThanOneInstanceThatCantUserIframes.current) {
+        log?.(
+            [
+                "More than one oidc instance can't use iframe",
+                "falling back to persisting tokens in session storage"
+            ].join(" ")
+        );
+    }
 
     const oidcClientTsUserManager =
         oidcMetadata === undefined
@@ -606,27 +638,18 @@ export async function createOidc_nonMemoized<
                   userStore: new WebStorageStateStore({
                       store: (() => {
                           if (canUseIframe) {
-                              isUserStoreInMemoryOnly = true;
                               return new InMemoryWebStorage();
                           }
 
-                          isUserStoreInMemoryOnly = false;
-
-                          const storage = createEphemeralSessionStorage({
-                              sessionStorageTtlMs: 3 * 60_000
-                          });
-
-                          const { evtRequestToPersistTokens } = globalContext;
-
-                          evtRequestToPersistTokens.subscribe(
-                              ({ configIdOfInstancePostingTheRequest }) => {
-                                  if (configIdOfInstancePostingTheRequest === configId) {
-                                      return;
-                                  }
+                          const storage = createLazySessionStorage({ storageId: configId });
 
+                          if (evtIsThereMoreThanOneInstanceThatCantUserIframes.current) {
+                              storage.persistCurrentStateAndSubsequentChanges();
+                          } else {
+                              evtIsThereMoreThanOneInstanceThatCantUserIframes.subscribe(() => {
                                   storage.persistCurrentStateAndSubsequentChanges();
-                              }
-                          );
+                              });
+                          }
 
                           return storage;
                       })()
@@ -675,75 +698,67 @@ export async function createOidc_nonMemoized<
             });
         }
 
-        handle_redirect_auth_response: {
-            let stateDataAndAuthResponse:
-                | { stateData: StateData.Redirect; authResponse: AuthResponse }
-                | undefined = undefined;
+        restore_from_session_storage: {
+            if (canUseIframe) {
+                break restore_from_session_storage;
+            }
 
-            get_stateData_and_authResponse: {
-                from_memory: {
-                    const { authResponse, clearAuthResponse } = getRedirectAuthResponse();
+            if (!evtIsThereMoreThanOneInstanceThatCantUserIframes.current) {
+                break restore_from_session_storage;
+            }
 
-                    if (authResponse === undefined) {
-                        break from_memory;
-                    }
+            let oidcClientTsUser: OidcClientTsUser | null;
 
-                    const stateData = getStateData({ stateUrlParamValue: authResponse.state });
+            try {
+                oidcClientTsUser = await oidcClientTsUserManager.getUser();
+            } catch {
+                // NOTE: Not sure if it can throw, but let's be safe.
+                oidcClientTsUser = null;
+                try {
+                    await oidcClientTsUserManager.removeUser();
+                } catch {}
+            }
 
-                    if (stateData === undefined) {
-                        clearAuthResponse();
-                        break from_memory;
-                    }
+            if (oidcClientTsUser === null) {
+                break restore_from_session_storage;
+            }
 
-                    if (stateData.configId !== configId) {
-                        break from_memory;
-                    }
+            log?.("Session was restored from session storage");
 
-                    assert(stateData.context === "redirect", "3229492");
+            return {
+                oidcClientTsUser,
+                backFromAuthServer: undefined
+            };
+        }
 
-                    clearAuthResponse();
+        handle_redirect_auth_response: {
+            let stateDataAndAuthResponse:
+                | { stateData: StateData.Redirect; authResponse: AuthResponse }
+                | undefined = undefined;
 
-                    stateDataAndAuthResponse = { stateData, authResponse };
+            {
+                const { authResponse, clearAuthResponse } = getRedirectAuthResponse();
 
-                    break get_stateData_and_authResponse;
+                if (authResponse === undefined) {
+                    break handle_redirect_auth_response;
                 }
 
-                // from storage, this is for race condition in multiple instance
-                // setup where one instance would need to redirect before
-                // the authResponse in memory had the chance to be processed.
-                // This can only happen if:
-                // 1) There are multiple oidc instances in the App.
-                // 2) They are instantiated in a non deterministic order.
-                // 3) We can't use iframe
-                // We practically never persist the auth response and do it only in session
-                // an ephemeral session storage, when we know it's gonna be required.
-                {
-                    const { authResponses } = getPersistedRedirectAuthResponses();
-
-                    for (const authResponse of authResponses) {
-                        const stateData = getStateData({ stateUrlParamValue: authResponse.state });
-
-                        if (stateData === undefined) {
-                            continue;
-                        }
+                const stateData = getStateData({ stateUrlParamValue: authResponse.state });
 
-                        if (stateData.configId !== configId) {
-                            continue;
-                        }
+                if (stateData === undefined) {
+                    clearAuthResponse();
+                    break handle_redirect_auth_response;
+                }
 
-                        assert(stateData.context === "redirect", "35935591");
+                if (stateData.configId !== configId) {
+                    break handle_redirect_auth_response;
+                }
 
-                        setPersistedRedirectAuthResponses({
-                            authResponses: authResponses.filter(
-                                authResponse_i => authResponse_i !== authResponse
-                            )
-                        });
+                assert(stateData.context === "redirect", "3229492");
 
-                        stateDataAndAuthResponse = { stateData, authResponse };
+                clearAuthResponse();
 
-                        break get_stateData_and_authResponse;
-                    }
-                }
+                stateDataAndAuthResponse = { stateData, authResponse };
             }
 
             if (stateDataAndAuthResponse === undefined) {
@@ -856,39 +871,6 @@ export async function createOidc_nonMemoized<
             }
         }
 
-        // NOTE: We almost never persist tokens, we have to only to support edge case
-        // of multiple oidc instance in a single App with no iframe support.
-        restore_from_session_storage: {
-            assert(isUserStoreInMemoryOnly !== undefined, "3392204");
-
-            if (isUserStoreInMemoryOnly) {
-                break restore_from_session_storage;
-            }
-
-            let oidcClientTsUser: OidcClientTsUser | null;
-
-            try {
-                oidcClientTsUser = await oidcClientTsUserManager.getUser();
-            } catch {
-                // NOTE: Not sure if it can throw, but let's be safe.
-                oidcClientTsUser = null;
-                try {
-                    await oidcClientTsUserManager.removeUser();
-                } catch {}
-            }
-
-            if (oidcClientTsUser === null) {
-                break restore_from_session_storage;
-            }
-
-            log?.("Restored the auth from ephemeral session storage");
-
-            return {
-                oidcClientTsUser,
-                backFromAuthServer: undefined
-            };
-        }
-
         silent_login_if_possible_and_auto_login: {
             const persistedAuthState = getPersistedAuthState({ configId });
 
@@ -956,7 +938,7 @@ export async function createOidc_nonMemoized<
                         redirectUri: homeUrlAndRedirectUri,
                         clientId,
                         issuerUri,
-                        noIframe
+                        canUseIframe
                     });
                 }
 
@@ -1002,8 +984,6 @@ export async function createOidc_nonMemoized<
                 ) {
                     log?.("Performing auto login with redirect");
 
-                    persistAuthState({ configId, state: undefined });
-
                     completeLoginOrRefreshProcess();
 
                     if (autoLogin && persistedAuthState !== "logged in") {
@@ -1015,16 +995,20 @@ export async function createOidc_nonMemoized<
                             getPrSafelyRestoredFromBfCacheAfterLoginBackNavigationOrInitializationError()
                     });
 
-                    if (persistedAuthState === "logged in") {
-                        globalContext.evtRequestToPersistTokens.post({
-                            configIdOfInstancePostingTheRequest: configId
-                        });
-                    }
-
                     await loginOrGoToAuthServer({
                         action: "login",
                         doForceReloadOnBfCache: true,
-                        redirectUrl: getRootRelativeOriginalLocationHref(),
+                        redirectUrl: (() => {
+                            if (postLoginRedirectUrl_default) {
+                                return postLoginRedirectUrl_default;
+                            }
+
+                            if (!evtIsThereMoreThanOneInstanceThatCantUserIframes.current) {
+                                return getRootRelativeOriginalLocationHref();
+                            }
+
+                            return getDesiredPostLoginRedirectUrl() ?? window.location.href;
+                        })(),
                         // NOTE: Wether or not it's the preferred behavior, pushing to history
                         // only works on user interaction so it have to be false
                         doNavigateBackToLastPublicUrlIfTheTheUserNavigateBack: false,
@@ -1040,7 +1024,10 @@ export async function createOidc_nonMemoized<
                             }
 
                             return "ensure no interaction";
-                        })()
+                        })(),
+                        preRedirectHook: () => {
+                            persistAuthState({ configId, state: undefined });
+                        }
                     });
                 }
 
@@ -1161,7 +1148,8 @@ export async function createOidc_nonMemoized<
                             interaction:
                                 getPersistedAuthState({ configId }) === "explicitly logged out"
                                     ? "ensure interaction"
-                                    : "directly redirect if active session show login otherwise"
+                                    : "directly redirect if active session show login otherwise",
+                            preRedirectHook: undefined
                         });
                     },
                     initializationError: undefined
@@ -1233,6 +1221,7 @@ export async function createOidc_nonMemoized<
                 state: {
                     stateDescription: "logged in",
                     refreshTokenExpirationTime: currentTokens.refreshTokenExpirationTime,
+                    serverDateNow: currentTokens.getServerDateNow(),
                     idleSessionLifetimeInSeconds
                 }
             });
@@ -1382,10 +1371,6 @@ export async function createOidc_nonMemoized<
                         prUnlock: new Promise<never>(() => {})
                     });
 
-                    globalContext.evtRequestToPersistTokens.post({
-                        configIdOfInstancePostingTheRequest: configId
-                    });
-
                     await loginOrGoToAuthServer({
                         action: "login",
                         redirectUrl: window.location.href,
@@ -1393,7 +1378,8 @@ export async function createOidc_nonMemoized<
                         extraQueryParams_local: undefined,
                         transformUrlBeforeRedirect_local: undefined,
                         doNavigateBackToLastPublicUrlIfTheTheUserNavigateBack: false,
-                        interaction: "directly redirect if active session show login otherwise"
+                        interaction: "directly redirect if active session show login otherwise",
+                        preRedirectHook: undefined
                     });
                     assert(false, "136134");
                 };
@@ -1514,6 +1500,7 @@ export async function createOidc_nonMemoized<
                         state: {
                             stateDescription: "logged in",
                             refreshTokenExpirationTime: currentTokens.refreshTokenExpirationTime,
+                            serverDateNow: currentTokens.getServerDateNow(),
                             idleSessionLifetimeInSeconds
                         }
                     });

package/src/core/desiredPostLoginRedirectUrl.ts

@@ -0,0 +1,9 @@
+let postLoginRedirectUrl: string | undefined;
+
+export function setDesiredPostLoginRedirectUrl(params: { postLoginRedirectUrl: string | undefined }) {
+    postLoginRedirectUrl = params.postLoginRedirectUrl;
+}
+
+export function getDesiredPostLoginRedirectUrl() {
+    return postLoginRedirectUrl;
+}

package/src/core/diagnostic.ts

@@ -90,9 +90,9 @@ export async function createIframeTimeoutInitializationError(params: {
     redirectUri: string;
     issuerUri: string;
     clientId: string;
-    noIframe: boolean;
+    canUseIframe: boolean;
 }): Promise<OidcInitializationError> {
-    const { redirectUri, issuerUri, clientId, noIframe } = params;
+    const { redirectUri, issuerUri, clientId, canUseIframe } = params;
 
     check_if_well_known_endpoint_is_reachable: {
         const isValid = await getIsValidRemoteJson(`${issuerUri}${WELL_KNOWN_PATH}`);
@@ -105,7 +105,7 @@ export async function createIframeTimeoutInitializationError(params: {
     }
 
     iframe_blocked: {
-        if (noIframe) {
+        if (!canUseIframe) {
             break iframe_blocked;
         }
 
@@ -189,7 +189,7 @@ export async function createIframeTimeoutInitializationError(params: {
             messageOrCause: [
                 `${redirectUri} is currently served by your web server with the HTTP header \`${key_problem}: ${headers[key_problem]}\`.\n`,
                 "This header prevents the silent sign-in process from working.\n",
-                "Refer to this documentation page to fix this issue: https://docs.oidc-spa.dev/v/v8/resources/iframe-related-issues"
+                "Refer to this documentation page to fix this issue: https://docs.oidc-spa.dev/v/v8/resources/third-party-cookies-and-session-restoration"
             ].join(" ")
         });
     }

package/src/core/instancesThatCantUseIframes.ts

@@ -0,0 +1,24 @@
+import { createStatefulEvt } from "../tools/StatefulEvt";
+
+const SESSION_STORAGE_KEY = "oidc-spa:more-than-one-instance-cant-use-iframe";
+
+export const evtIsThereMoreThanOneInstanceThatCantUserIframes = createStatefulEvt(
+    () => sessionStorage.getItem(SESSION_STORAGE_KEY) !== null
+);
+
+let count = 0;
+
+export function notifyNewInstanceThatCantUseIframes() {
+    count++;
+
+    if (count === 1) {
+        return;
+    }
+
+    if (evtIsThereMoreThanOneInstanceThatCantUserIframes.current) {
+        return;
+    }
+
+    sessionStorage.setItem(SESSION_STORAGE_KEY, "true");
+    evtIsThereMoreThanOneInstanceThatCantUserIframes.current = true;
+}

package/src/core/loginOrGoToAuthServer.ts

@@ -30,6 +30,7 @@ namespace Params {
             | "ensure no interaction"
             | "ensure interaction"
             | "directly redirect if active session show login otherwise";
+        preRedirectHook: (() => void) | undefined;
     };
 
     export type GoToAuthServer = Common & {
@@ -305,6 +306,10 @@ export function createLoginOrGoToAuthServer(params: {
 
         log?.(`redirectMethod: ${redirectMethod}`);
 
+        if (rest.action === "login") {
+            rest.preRedirectHook?.();
+        }
+
         return oidcClientTsUserManager
             .signinRedirect({
                 state: stateData,