oidc-spa 7.2.0 → 7.2.2

package/src/mock/oidc.ts

@@ -0,0 +1,211 @@
+import type { Oidc } from "../core";
+import { createObjectThatThrowsIfAccessed } from "../tools/createObjectThatThrowsIfAccessed";
+import { id } from "../vendor/frontend/tsafe";
+import { toFullyQualifiedUrl } from "../tools/toFullyQualifiedUrl";
+import { getSearchParam, addOrUpdateSearchParam } from "../tools/urlSearchParams";
+import { initialLocationHref } from "../core/initialLocationHref";
+
+export type ParamsOfCreateMockOidc<
+    DecodedIdToken extends Record<string, unknown> = Record<string, unknown>,
+    AutoLogin extends boolean = false
+> = {
+    mockedParams?: Partial<Oidc["params"]>;
+    mockedTokens?: Partial<Oidc.Tokens<DecodedIdToken>>;
+    /**
+     * The URL of the home page of your app.
+     * We need to know this so we know where to redirect when you call `logout({ redirectTo: "home"})`.
+     * In the majority of cases it should be `homeUrl: "/"` but it could aso be something like `homeUrl: "/dashboard"`
+     * if your web app isn't hosted at the root of the domain.
+     */
+    homeUrl: string;
+    autoLogin?: AutoLogin;
+    postLoginRedirectUrl?: string;
+} & (AutoLogin extends true
+    ? { isUserInitiallyLoggedIn?: true }
+    : {
+          isUserInitiallyLoggedIn: boolean;
+      });
+
+const URL_SEARCH_PARAM_NAME = "isUserLoggedIn";
+
+export async function createMockOidc<
+    DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_base,
+    AutoLogin extends boolean = false
+>(
+    params: ParamsOfCreateMockOidc<DecodedIdToken, AutoLogin>
+): Promise<AutoLogin extends true ? Oidc.LoggedIn<DecodedIdToken> : Oidc<DecodedIdToken>> {
+    const {
+        isUserInitiallyLoggedIn = true,
+        mockedParams = {},
+        mockedTokens = {},
+        homeUrl: homeUrl_params,
+        autoLogin = false,
+        postLoginRedirectUrl
+    } = params;
+
+    const isUserLoggedIn = (() => {
+        const { wasPresent, value } = getSearchParam({
+            url: initialLocationHref,
+            name: URL_SEARCH_PARAM_NAME
+        });
+
+        if (!wasPresent) {
+            return isUserInitiallyLoggedIn;
+        }
+
+        remove_from_url: {
+            const { wasPresent, url_withoutTheParam } = getSearchParam({
+                url: window.location.href,
+                name: URL_SEARCH_PARAM_NAME
+            });
+
+            if (!wasPresent) {
+                break remove_from_url;
+            }
+
+            window.history.replaceState({}, "", url_withoutTheParam);
+        }
+
+        return value === "true";
+    })();
+
+    const homeUrl = toFullyQualifiedUrl({
+        urlish: homeUrl_params,
+        doAssertNoQueryParams: true,
+        doOutputWithTrailingSlash: true
+    });
+
+    const common: Oidc.Common = {
+        params: {
+            clientId: mockedParams.clientId ?? "mymockclient",
+            issuerUri: mockedParams.issuerUri ?? "https://my-mock-oidc-server.net/realms/mymockrealm"
+        }
+    };
+
+    const loginOrGoToAuthServer = async (params: {
+        redirectUrl: string | undefined;
+    }): Promise<never> => {
+        const { redirectUrl: redirectUrl_params } = params;
+
+        const redirectUrl = addOrUpdateSearchParam({
+            url: (() => {
+                if (redirectUrl_params === undefined) {
+                    return window.location.href;
+                }
+
+                return toFullyQualifiedUrl({
+                    urlish: redirectUrl_params,
+                    doAssertNoQueryParams: false
+                });
+            })(),
+            name: URL_SEARCH_PARAM_NAME,
+            value: "true",
+            encodeMethod: "www-form"
+        });
+
+        window.location.href = redirectUrl;
+
+        return new Promise<never>(() => {});
+    };
+
+    if (!isUserLoggedIn) {
+        const oidc = id<Oidc.NotLoggedIn>({
+            ...common,
+            isUserLoggedIn: false,
+            login: ({ redirectUrl }) => loginOrGoToAuthServer({ redirectUrl }),
+            initializationError: undefined
+        });
+        if (autoLogin) {
+            await oidc.login({
+                redirectUrl: postLoginRedirectUrl,
+                doesCurrentHrefRequiresAuth: true
+            });
+            // Never here
+        }
+        // @ts-expect-error: We know what we are doing
+        return oidc;
+    }
+
+    const oidc: Oidc.LoggedIn<DecodedIdToken> = {
+        ...common,
+        isUserLoggedIn: true,
+        renewTokens: async () => {},
+        ...(() => {
+            const tokens_common: Oidc.Tokens.Common<DecodedIdToken> = {
+                accessToken: mockedTokens.accessToken ?? "mocked-access-token",
+                accessTokenExpirationTime: mockedTokens.accessTokenExpirationTime ?? Infinity,
+                idToken: mockedTokens.idToken ?? "mocked-id-token",
+                decodedIdToken:
+                    mockedTokens.decodedIdToken ??
+                    createObjectThatThrowsIfAccessed<DecodedIdToken>({
+                        debugMessage: [
+                            "You haven't provided a mocked decodedIdToken",
+                            "See https://docs.oidc-spa.dev/v/v7/mock"
+                        ].join("\n")
+                    }),
+                decodedIdToken_original:
+                    mockedTokens.decodedIdToken_original ??
+                    createObjectThatThrowsIfAccessed<Oidc.Tokens.DecodedIdToken_base>({
+                        debugMessage: [
+                            "You haven't provided a mocked decodedIdToken_original",
+                            "See https://docs.oidc-spa.dev/v/v7/mock"
+                        ].join("\n")
+                    }),
+                issuedAtTime: Date.now()
+            };
+
+            const tokens: Oidc.Tokens<DecodedIdToken> =
+                mockedTokens.refreshToken !== undefined || mockedTokens.hasRefreshToken === true
+                    ? id<Oidc.Tokens.WithRefreshToken<DecodedIdToken>>({
+                          ...tokens_common,
+                          hasRefreshToken: true,
+                          refreshToken: mockedTokens.refreshToken ?? "mocked-refresh-token",
+                          refreshTokenExpirationTime: mockedTokens.refreshTokenExpirationTime
+                      })
+                    : id<Oidc.Tokens.WithoutRefreshToken<DecodedIdToken>>({
+                          ...tokens_common,
+                          hasRefreshToken: false
+                      });
+
+            return {
+                getTokens: () => Promise.resolve(tokens),
+                getDecodedIdToken: () => tokens_common.decodedIdToken
+            };
+        })(),
+        subscribeToTokensChange: () => ({
+            unsubscribe: () => {}
+        }),
+        logout: params => {
+            const redirectUrl = addOrUpdateSearchParam({
+                url: (() => {
+                    switch (params.redirectTo) {
+                        case "current page":
+                            return window.location.href;
+                        case "home":
+                            return homeUrl;
+                        case "specific url":
+                            return toFullyQualifiedUrl({
+                                urlish: params.url,
+                                doAssertNoQueryParams: false
+                            });
+                    }
+                })(),
+                name: URL_SEARCH_PARAM_NAME,
+                value: "false",
+                encodeMethod: "www-form"
+            });
+
+            window.location.href = redirectUrl;
+
+            return new Promise<never>(() => {});
+        },
+        subscribeToAutoLogoutCountdown: () => ({
+            unsubscribeFromAutoLogoutCountdown: () => {}
+        }),
+        goToAuthServer: async ({ redirectUrl }) => loginOrGoToAuthServer({ redirectUrl }),
+        isNewBrowserSession: false,
+        backFromAuthServer: undefined
+    };
+
+    return oidc;
+}

package/src/mock/react.tsx

@@ -0,0 +1,11 @@
+import { createOidcReactApi_dependencyInjection } from "../react/react";
+import { createMockOidc, type ParamsOfCreateMockOidc } from "./oidc";
+import type { ValueOrAsyncGetter } from "../tools/ValueOrAsyncGetter";
+
+/** @see: https://docs.oidc-spa.dev/v/v7/mock */
+export function createMockReactOidc<
+    DecodedIdToken extends Record<string, unknown> = Record<string, unknown>,
+    AutoLogin extends boolean = false
+>(params: ValueOrAsyncGetter<ParamsOfCreateMockOidc<DecodedIdToken, AutoLogin>>) {
+    return createOidcReactApi_dependencyInjection(params, createMockOidc);
+}

package/src/react/index.ts

@@ -0,0 +1 @@
+export { type OidcReact, createReactOidc } from "./react";

package/src/react/react.tsx

@@ -0,0 +1,476 @@
+import {
+    useEffect,
+    useState,
+    createContext,
+    useContext,
+    type ReactNode,
+    type ComponentType,
+    type FC,
+    type JSX
+} from "react";
+import {
+    type Oidc,
+    createOidc,
+    type ParamsOfCreateOidc,
+    OidcInitializationError,
+    handleOidcCallback
+} from "../core";
+import { assert, type Equals, type Param0 } from "../vendor/frontend/tsafe";
+import { id } from "../vendor/frontend/tsafe";
+import type { ValueOrAsyncGetter } from "../tools/ValueOrAsyncGetter";
+import { Deferred } from "../tools/Deferred";
+import { toFullyQualifiedUrl } from "../tools/toFullyQualifiedUrl";
+
+export type OidcReact<DecodedIdToken extends Record<string, unknown>> =
+    | OidcReact.NotLoggedIn
+    | OidcReact.LoggedIn<DecodedIdToken>;
+
+export namespace OidcReact {
+    export type Common = Oidc.Common & {
+        useAutoLogoutWarningCountdown: (params: { warningDurationSeconds: number }) => {
+            secondsLeft: number | undefined;
+        };
+    };
+
+    export type NotLoggedIn = Common & {
+        isUserLoggedIn: false;
+        login: (params?: {
+            extraQueryParams?: Record<string, string | undefined>;
+            redirectUrl?: string;
+            transformUrlBeforeRedirect?: (url: string) => string;
+            doesCurrentHrefRequiresAuth?: boolean;
+        }) => Promise<never>;
+        initializationError: OidcInitializationError | undefined;
+
+        decodedIdToken?: never;
+        logout?: never;
+        renewTokens?: never;
+        goToAuthServer?: never;
+        backFromAuthServer?: never;
+        isNewBrowserSession?: never;
+    };
+
+    export type LoggedIn<DecodedIdToken extends Record<string, unknown>> = Common & {
+        isUserLoggedIn: true;
+        decodedIdToken: DecodedIdToken;
+        logout: Oidc.LoggedIn["logout"];
+        renewTokens: Oidc.LoggedIn["renewTokens"];
+        login?: never;
+        initializationError?: never;
+        goToAuthServer: (params: {
+            extraQueryParams?: Record<string, string>;
+            redirectUrl?: string;
+            transformUrlBeforeRedirect?: (url: string) => string;
+        }) => Promise<never>;
+
+        backFromAuthServer:
+            | {
+                  extraQueryParams: Record<string, string>;
+                  result: Record<string, string>;
+              }
+            | undefined;
+
+        isNewBrowserSession: boolean;
+    };
+}
+{
+    type Actual = Param0<OidcReact.NotLoggedIn["login"]>;
+    type Expected = Omit<Param0<Oidc.NotLoggedIn["login"]>, "doesCurrentHrefRequiresAuth"> & {
+        doesCurrentHrefRequiresAuth?: boolean;
+    };
+
+    assert<Equals<Actual, Expected>>();
+}
+
+type OidcReactApi<DecodedIdToken extends Record<string, unknown>, AutoLogin extends boolean> = {
+    OidcProvider: AutoLogin extends true
+        ? (props: {
+              fallback?: ReactNode;
+              ErrorFallback?: (props: { initializationError: OidcInitializationError }) => ReactNode;
+              children: ReactNode;
+          }) => JSX.Element
+        : (props: { fallback?: ReactNode; children: ReactNode }) => JSX.Element;
+    useOidc: AutoLogin extends true
+        ? {
+              (params?: { assert: "user logged in" }): OidcReact.LoggedIn<DecodedIdToken>;
+          }
+        : {
+              (params?: { assert?: undefined }): OidcReact<DecodedIdToken>;
+              (params: { assert: "user logged in" }): OidcReact.LoggedIn<DecodedIdToken>;
+              (params: { assert: "user not logged in" }): OidcReact.NotLoggedIn;
+          };
+    getOidc: () => Promise<
+        AutoLogin extends true ? Oidc.LoggedIn<DecodedIdToken> : Oidc<DecodedIdToken>
+    >;
+} & (AutoLogin extends true
+    ? {}
+    : {
+          withLoginEnforced: <Props extends Record<string, unknown>>(
+              Component: ComponentType<Props>,
+              params?: {
+                  onRedirecting: () => JSX.Element | null;
+              }
+          ) => FC<Props>;
+          enforceLogin: (loaderParams: {
+              request?: { url?: string };
+              cause?: "preload" | string;
+              location?: {
+                  href?: string;
+              };
+          }) => Promise<void | never>;
+      });
+
+export function createOidcReactApi_dependencyInjection<
+    DecodedIdToken extends Record<string, unknown>,
+    ParamsOfCreateOidc extends {
+        autoLogin?: boolean;
+    } & (
+        | {
+              decodedIdTokenSchema: { parse: (data: unknown) => DecodedIdToken } | undefined;
+          }
+        | {}
+    )
+>(
+    paramsOrGetParams: ValueOrAsyncGetter<ParamsOfCreateOidc>,
+    createOidc: (params: ParamsOfCreateOidc) => Promise<Oidc<DecodedIdToken>>
+): OidcReactApi<
+    DecodedIdToken,
+    ParamsOfCreateOidc extends { autoLogin?: true | undefined } ? true : false
+> {
+    const dReadyToCreate = new Deferred<void>();
+
+    const oidcContext = createContext<{ oidc: Oidc<DecodedIdToken>; fallback: ReactNode } | undefined>(
+        undefined
+    );
+
+    // NOTE: It can be InitializationError only if autoLogin is true
+    const prOidcOrInitializationError = (async () => {
+        // We're doing this here just for people that wouldn't have
+        // configured the early init in entrypoint.
+        {
+            const { isHandled } = handleOidcCallback();
+
+            if (isHandled) {
+                return new Promise<never>(() => {});
+            }
+        }
+
+        const params = await (async () => {
+            if (typeof paramsOrGetParams === "function") {
+                const getParams = paramsOrGetParams;
+
+                await dReadyToCreate.pr;
+
+                const params = await getParams();
+
+                return params;
+            }
+
+            const params = paramsOrGetParams;
+
+            return params;
+        })();
+
+        let oidc: Oidc<DecodedIdToken>;
+
+        try {
+            oidc = await createOidc(params);
+        } catch (error) {
+            if (!(error instanceof OidcInitializationError)) {
+                throw error;
+            }
+
+            return error;
+        }
+
+        return oidc;
+    })();
+
+    let prOidcOrInitializationError_resolvedValue:
+        | Oidc<DecodedIdToken>
+        | OidcInitializationError
+        | undefined = undefined;
+    prOidcOrInitializationError.then(value => (prOidcOrInitializationError_resolvedValue = value));
+
+    function OidcProvider(props: {
+        fallback?: ReactNode;
+        ErrorFallback?: (props: { initializationError: OidcInitializationError }) => ReactNode;
+        children: ReactNode;
+    }) {
+        const { fallback, ErrorFallback, children } = props;
+
+        const [oidcOrInitializationError, setOidcOrInitializationError] = useState<
+            Oidc<DecodedIdToken> | OidcInitializationError | undefined
+        >(prOidcOrInitializationError_resolvedValue);
+
+        useEffect(() => {
+            if (oidcOrInitializationError !== undefined) {
+                return;
+            }
+
+            dReadyToCreate.resolve();
+            prOidcOrInitializationError.then(setOidcOrInitializationError);
+        }, []);
+
+        if (oidcOrInitializationError === undefined) {
+            return <>{fallback === undefined ? null : fallback}</>;
+        }
+
+        if (oidcOrInitializationError instanceof OidcInitializationError) {
+            const initializationError = oidcOrInitializationError;
+
+            return (
+                <>
+                    {ErrorFallback === undefined ? (
+                        <h1 style={{ color: "red" }}>
+                            An error occurred while initializing the OIDC client:&nbsp;
+                            {initializationError.message}
+                        </h1>
+                    ) : (
+                        <ErrorFallback initializationError={initializationError} />
+                    )}
+                </>
+            );
+        }
+
+        const oidc = oidcOrInitializationError;
+
+        return (
+            <oidcContext.Provider value={{ oidc, fallback: fallback ?? null }}>
+                {children}
+            </oidcContext.Provider>
+        );
+    }
+
+    const useAutoLogoutWarningCountdown: OidcReact.LoggedIn<DecodedIdToken>["useAutoLogoutWarningCountdown"] =
+        ({ warningDurationSeconds }) => {
+            const contextValue = useContext(oidcContext);
+
+            assert(contextValue !== undefined);
+
+            const { oidc } = contextValue;
+
+            const [secondsLeft, setSecondsLeft] = useState<number | undefined>(undefined);
+
+            useEffect(() => {
+                if (!oidc.isUserLoggedIn) {
+                    return;
+                }
+
+                const { unsubscribeFromAutoLogoutCountdown } = oidc.subscribeToAutoLogoutCountdown(
+                    ({ secondsLeft }) =>
+                        setSecondsLeft(
+                            secondsLeft === undefined || secondsLeft > warningDurationSeconds
+                                ? undefined
+                                : secondsLeft
+                        )
+                );
+
+                return () => {
+                    unsubscribeFromAutoLogoutCountdown();
+                };
+            }, [warningDurationSeconds]);
+
+            return { secondsLeft };
+        };
+
+    function useOidc(params?: {
+        assert?: "user logged in" | "user not logged in";
+    }): OidcReact<DecodedIdToken> {
+        const { assert: assert_params } = params ?? {};
+
+        const contextValue = useContext(oidcContext);
+
+        assert(contextValue !== undefined, "You must use useOidc inside the corresponding OidcProvider");
+
+        const { oidc } = contextValue;
+
+        check_assertion: {
+            if (assert_params === undefined) {
+                break check_assertion;
+            }
+
+            const getMessage = (v: string) =>
+                [
+                    "There is a logic error in the application.",
+                    `If this component is mounted the user is supposed ${v}.`,
+                    "An explicit assertion was made in this sense."
+                ].join(" ");
+
+            switch (assert_params) {
+                case "user logged in":
+                    if (!oidc.isUserLoggedIn) {
+                        throw new Error(getMessage("to be logged in but currently they arn't"));
+                    }
+                    break;
+                case "user not logged in":
+                    if (oidc.isUserLoggedIn) {
+                        throw new Error(getMessage("not to be logged in but currently they are"));
+                    }
+                    break;
+                default:
+                    assert<Equals<typeof assert_params, never>>(false);
+            }
+        }
+
+        const [, reRenderIfDecodedIdTokenChanged] = useState(
+            !oidc.isUserLoggedIn ? undefined : oidc.getDecodedIdToken()
+        );
+
+        useEffect(() => {
+            if (!oidc.isUserLoggedIn) {
+                return;
+            }
+
+            const { unsubscribe } = oidc.subscribeToTokensChange(() =>
+                reRenderIfDecodedIdTokenChanged(oidc.getDecodedIdToken())
+            );
+
+            reRenderIfDecodedIdTokenChanged(oidc.getDecodedIdToken());
+
+            return unsubscribe;
+        }, []);
+
+        const common: OidcReact.Common = {
+            params: oidc.params,
+            useAutoLogoutWarningCountdown
+        };
+
+        if (!oidc.isUserLoggedIn) {
+            return id<OidcReact.NotLoggedIn>({
+                ...common,
+                isUserLoggedIn: false,
+                login: ({ doesCurrentHrefRequiresAuth = false, ...rest } = {}) =>
+                    oidc.login({ doesCurrentHrefRequiresAuth, ...rest }),
+                initializationError: oidc.initializationError
+            });
+        }
+
+        const oidcReact: OidcReact.LoggedIn<DecodedIdToken> = {
+            ...common,
+            isUserLoggedIn: true,
+            decodedIdToken: oidc.getDecodedIdToken(),
+            logout: oidc.logout,
+            renewTokens: oidc.renewTokens,
+            goToAuthServer: oidc.goToAuthServer,
+            isNewBrowserSession: oidc.isNewBrowserSession,
+            backFromAuthServer: oidc.backFromAuthServer
+        };
+
+        return oidcReact;
+    }
+
+    function withLoginEnforced<Props extends Record<string, unknown>>(
+        Component: ComponentType<Props>,
+        params?: {
+            onRedirecting?: () => JSX.Element | null;
+        }
+    ): FC<Props> {
+        const { onRedirecting } = params ?? {};
+
+        function ComponentWithLoginEnforced(props: Props) {
+            const contextValue = useContext(oidcContext);
+
+            assert(contextValue !== undefined, "094283");
+
+            const { oidc, fallback } = contextValue;
+
+            useEffect(() => {
+                if (oidc.isUserLoggedIn) {
+                    return;
+                }
+
+                oidc.login({ doesCurrentHrefRequiresAuth: true });
+            }, []);
+
+            if (!oidc.isUserLoggedIn) {
+                return onRedirecting === undefined ? fallback : onRedirecting();
+            }
+
+            return <Component {...props} />;
+        }
+
+        ComponentWithLoginEnforced.displayName = `${
+            Component.displayName ?? Component.name ?? "Component"
+        }WithLoginEnforced`;
+
+        return ComponentWithLoginEnforced;
+    }
+
+    async function enforceLogin(loaderParams: {
+        request?: { url?: string };
+        cause?: "preload" | string;
+        location?: { href?: string };
+    }): Promise<void | never> {
+        const { cause } = loaderParams;
+
+        const redirectUrl = (() => {
+            if (loaderParams.request?.url !== undefined) {
+                return toFullyQualifiedUrl({
+                    urlish: loaderParams.request.url,
+                    doAssertNoQueryParams: false
+                });
+            }
+
+            if (loaderParams.location?.href !== undefined) {
+                return toFullyQualifiedUrl({
+                    urlish: loaderParams.location.href,
+                    doAssertNoQueryParams: false
+                });
+            }
+
+            return location.href;
+        })();
+
+        const oidc = await getOidc();
+
+        if (!oidc.isUserLoggedIn) {
+            if (cause === "preload") {
+                throw new Error(
+                    "oidc-spa: User is not yet logged in. This is an expected error, nothing to be addressed."
+                );
+            }
+            const doesCurrentHrefRequiresAuth =
+                location.href.replace(/\/$/, "") === redirectUrl.replace(/\/$/, "");
+
+            await oidc.login({
+                redirectUrl,
+                doesCurrentHrefRequiresAuth
+            });
+        }
+    }
+
+    async function getOidc(): Promise<Oidc<DecodedIdToken>> {
+        dReadyToCreate.resolve();
+
+        const oidcOrInitializationError = await prOidcOrInitializationError;
+
+        if (oidcOrInitializationError instanceof OidcInitializationError) {
+            const error = oidcOrInitializationError;
+            throw error;
+        }
+
+        const oidc = oidcOrInitializationError;
+
+        return oidc;
+    }
+
+    const oidcReact: OidcReactApi<DecodedIdToken, false> = {
+        OidcProvider,
+        useOidc: useOidc as any,
+        getOidc,
+        withLoginEnforced,
+        enforceLogin
+    };
+
+    // @ts-expect-error: We know what we are doing
+    return oidcReact;
+}
+
+/** @see: https://docs.oidc-spa.dev/v/v7/usage#react-api */
+export function createReactOidc<
+    DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_base,
+    AutoLogin extends boolean = false
+>(params: ValueOrAsyncGetter<ParamsOfCreateOidc<DecodedIdToken, AutoLogin>>) {
+    return createOidcReactApi_dependencyInjection(params, createOidc);
+}