oidc-spa 7.2.1 → 7.2.2

package/src/backend.ts

@@ -0,0 +1,391 @@
+import { fetch } from "./vendor/backend/node-fetch";
+import { assert, isAmong, id, type Equals, is, exclude } from "./vendor/backend/tsafe";
+import { JWK } from "./vendor/backend/node-jose";
+import * as jwt from "./vendor/backend/jsonwebtoken";
+import { z } from "./vendor/backend/zod";
+import { Evt } from "./vendor/backend/evt";
+import { throttleTime } from "./vendor/backend/evt";
+
+export type ParamsOfCreateOidcBackend<DecodedAccessToken extends Record<string, unknown>> = {
+    issuerUri: string;
+    decodedAccessTokenSchema?: { parse: (data: unknown) => DecodedAccessToken };
+};
+
+export type OidcBackend<DecodedAccessToken extends Record<string, unknown>> = {
+    verifyAndDecodeAccessToken(params: {
+        accessToken: string;
+    }): ResultOfAccessTokenVerify<DecodedAccessToken>;
+};
+
+export type ResultOfAccessTokenVerify<DecodedAccessToken> =
+    | ResultOfAccessTokenVerify.Valid<DecodedAccessToken>
+    | ResultOfAccessTokenVerify.Invalid;
+
+export namespace ResultOfAccessTokenVerify {
+    export type Valid<DecodedAccessToken> = {
+        isValid: true;
+        decodedAccessToken: DecodedAccessToken;
+
+        errorCase?: never;
+        errorMessage?: never;
+    };
+
+    export type Invalid = {
+        isValid: false;
+        errorCase: "expired" | "invalid signature" | "does not respect schema";
+        errorMessage: string;
+
+        decodedAccessToken?: never;
+    };
+}
+
+export async function createOidcBackend<DecodedAccessToken extends Record<string, unknown>>(
+    params: ParamsOfCreateOidcBackend<DecodedAccessToken>
+): Promise<OidcBackend<DecodedAccessToken>> {
+    const { issuerUri, decodedAccessTokenSchema = z.record(z.unknown()) } = params;
+
+    let publicSigningKeys = await fetchPublicSigningKeys({ issuerUri });
+
+    const evtInvalidSignature = Evt.create<void>();
+
+    evtInvalidSignature.pipe(throttleTime(3600_000)).attach(async () => {
+        const publicSigningKeys_new = await (async function callee(
+            count: number
+        ): Promise<PublicSigningKey[] | undefined> {
+            let wrap;
+
+            try {
+                wrap = await fetchPublicSigningKeys({ issuerUri });
+            } catch (error) {
+                if (count === 9) {
+                    console.warn(
+                        `Failed to refresh public key and signing algorithm after ${count + 1} attempts`
+                    );
+
+                    return undefined;
+                }
+
+                const delayMs = 1000 * Math.pow(2, count);
+
+                console.warn(
+                    `Failed to refresh public key and signing algorithm: ${String(
+                        error
+                    )}, retrying in ${delayMs}ms`
+                );
+
+                await new Promise(resolve => setTimeout(resolve, delayMs));
+
+                return callee(count + 1);
+            }
+
+            return wrap;
+        })(0);
+
+        if (publicSigningKeys_new === undefined) {
+            return;
+        }
+
+        publicSigningKeys = publicSigningKeys_new;
+    });
+
+    return {
+        verifyAndDecodeAccessToken: ({ accessToken }) => {
+            let kid: string;
+            let alg: jwt.Algorithm;
+
+            {
+                const jwtHeader_b64 = accessToken.split(".")[0];
+
+                let jwtHeader: string;
+
+                try {
+                    jwtHeader = Buffer.from(jwtHeader_b64, "base64").toString("utf8");
+                } catch {
+                    return {
+                        isValid: false,
+                        errorCase: "invalid signature",
+                        errorMessage: "Failed to decode the JWT header as a base64 string"
+                    };
+                }
+
+                let decodedHeader: unknown;
+
+                try {
+                    decodedHeader = JSON.parse(jwtHeader);
+                } catch {
+                    return {
+                        isValid: false,
+                        errorCase: "invalid signature",
+                        errorMessage: "Failed to parse the JWT header as a JSON"
+                    };
+                }
+
+                type DecodedHeader = {
+                    kid: string;
+                    alg: string;
+                };
+
+                const zDecodedHeader = z.object({
+                    kid: z.string(),
+                    alg: z.string()
+                });
+
+                assert<Equals<DecodedHeader, z.infer<typeof zDecodedHeader>>>();
+
+                try {
+                    zDecodedHeader.parse(decodedHeader);
+                } catch {
+                    return {
+                        isValid: false,
+                        errorCase: "invalid signature",
+                        errorMessage: "The decoded JWT header does not have a kid property"
+                    };
+                }
+
+                assert(is<DecodedHeader>(decodedHeader));
+
+                {
+                    const supportedAlgs = [
+                        "RS256",
+                        "RS384",
+                        "RS512",
+                        "ES256",
+                        "ES384",
+                        "ES512",
+                        "PS256",
+                        "PS384",
+                        "PS512"
+                    ] as const;
+
+                    assert<
+                        Equals<
+                            (typeof supportedAlgs)[number] | "none" | "HS256" | "HS384" | "HS512",
+                            jwt.Algorithm
+                        >
+                    >();
+
+                    if (!isAmong(supportedAlgs, decodedHeader.alg)) {
+                        return {
+                            isValid: false,
+                            errorCase: "invalid signature",
+                            errorMessage: `Unsupported or too week algorithm ${decodedHeader.alg}`
+                        };
+                    }
+                }
+
+                kid = decodedHeader.kid;
+                alg = decodedHeader.alg;
+            }
+
+            const publicSigningKey = publicSigningKeys.find(
+                publicSigningKey => publicSigningKey.kid === kid
+            );
+
+            if (publicSigningKey === undefined) {
+                return {
+                    isValid: false,
+                    errorCase: "invalid signature",
+                    errorMessage: `No public signing key found with kid ${kid}`
+                };
+            }
+
+            let result = id<ResultOfAccessTokenVerify<DecodedAccessToken> | undefined>(undefined);
+
+            jwt.verify(
+                accessToken,
+                publicSigningKey.publicKey,
+                { algorithms: [alg] },
+                (err, decoded) => {
+                    invalid: {
+                        if (!err) {
+                            break invalid;
+                        }
+
+                        if (err.name === "TokenExpiredError") {
+                            result = id<ResultOfAccessTokenVerify.Invalid>({
+                                isValid: false,
+                                errorCase: "expired",
+                                errorMessage: err.message
+                            });
+                            return;
+                        }
+
+                        evtInvalidSignature.post();
+
+                        result = id<ResultOfAccessTokenVerify.Invalid>({
+                            isValid: false,
+                            errorCase: "invalid signature",
+                            errorMessage: err.message
+                        });
+
+                        return;
+                    }
+
+                    let decodedAccessToken: DecodedAccessToken;
+
+                    try {
+                        decodedAccessToken = decodedAccessTokenSchema.parse(
+                            decoded
+                        ) as DecodedAccessToken;
+                    } catch (error) {
+                        result = id<ResultOfAccessTokenVerify.Invalid>({
+                            isValid: false,
+                            errorCase: "does not respect schema",
+                            errorMessage: String(error)
+                        });
+
+                        return;
+                    }
+
+                    result = id<ResultOfAccessTokenVerify.Valid<DecodedAccessToken>>({
+                        isValid: true,
+                        decodedAccessToken: decodedAccessToken
+                    });
+                }
+            );
+
+            assert(result !== undefined, "0522e6");
+
+            return result;
+        }
+    };
+}
+
+type PublicSigningKey = {
+    kid: string;
+    publicKey: string;
+};
+
+async function fetchPublicSigningKeys(params: { issuerUri: string }): Promise<PublicSigningKey[]> {
+    const { issuerUri } = params;
+
+    const { jwks_uri } = await (async () => {
+        const url = `${issuerUri.replace(/\/$/, "")}/.well-known/openid-configuration`;
+
+        const response = await fetch(url);
+
+        if (!response.ok) {
+            throw new Error(
+                `Failed to fetch openid configuration of the issuerUri: ${issuerUri} (${url}): ${response.statusText}`
+            );
+        }
+
+        let data: unknown;
+
+        try {
+            data = await response.json();
+        } catch (error) {
+            throw new Error(`Failed to parse json from ${url}: ${String(error)}`);
+        }
+
+        {
+            type WellKnownConfiguration = {
+                jwks_uri: string;
+            };
+
+            const zWellKnownConfiguration = z.object({
+                jwks_uri: z.string()
+            });
+
+            assert<Equals<WellKnownConfiguration, z.infer<typeof zWellKnownConfiguration>>>();
+
+            try {
+                zWellKnownConfiguration.parse(data);
+            } catch {
+                throw new Error(`${url} does not have a jwks_uri property`);
+            }
+
+            assert(is<WellKnownConfiguration>(data));
+        }
+
+        const { jwks_uri } = data;
+
+        return { jwks_uri };
+    })();
+
+    const { jwks } = await (async () => {
+        const response = await fetch(jwks_uri);
+
+        if (!response.ok) {
+            throw new Error(
+                `Failed to fetch public key and algorithm from ${jwks_uri}: ${response.statusText}`
+            );
+        }
+
+        let jwks: unknown;
+
+        try {
+            jwks = await response.json();
+        } catch (error) {
+            throw new Error(`Failed to parse json from ${jwks_uri}: ${String(error)}`);
+        }
+
+        {
+            type Jwks = {
+                keys: {
+                    kid: string;
+                    kty: string;
+                    e?: string;
+                    n?: string;
+                    use: string;
+                }[];
+            };
+
+            const zJwks = z.object({
+                keys: z.array(
+                    z.object({
+                        kid: z.string(),
+                        kty: z.string(),
+                        e: z.string().optional(),
+                        n: z.string().optional(),
+                        use: z.string()
+                    })
+                )
+            });
+
+            assert<Equals<Jwks, z.infer<typeof zJwks>>>();
+
+            try {
+                zJwks.parse(jwks);
+            } catch {
+                throw new Error(`${jwks_uri} does not have the expected shape`);
+            }
+
+            assert(is<Jwks>(jwks));
+        }
+
+        return { jwks };
+    })();
+
+    const publicSigningKeys: PublicSigningKey[] = await Promise.all(
+        jwks.keys
+            .filter(({ use }) => use === "sig")
+            .map(({ kid, kty, e, n }) => {
+                if (kty !== "RSA") {
+                    return undefined;
+                }
+
+                assert(e !== undefined, "e is undefined");
+                assert(n !== undefined, "n is undefined");
+
+                return { kid, e, n };
+            })
+            .filter(exclude(undefined))
+            .map(async ({ kid, e, n }) => {
+                const key = await JWK.asKey({ kty: "RSA", e, n });
+                const publicKey = key.toPEM(false);
+
+                return {
+                    kid,
+                    publicKey
+                };
+            })
+    );
+
+    assert(
+        publicSigningKeys.length !== 0,
+        `No public signing key found at ${jwks_uri}, ${JSON.stringify(jwks, null, 2)}`
+    );
+
+    return publicSigningKeys;
+}

package/src/core/AuthResponse.ts

@@ -0,0 +1,26 @@
+import { addOrUpdateSearchParam } from "../tools/urlSearchParams";
+
+export type AuthResponse = {
+    state: string;
+    [key: string]: string | undefined;
+};
+
+export function authResponseToUrl(authResponse: AuthResponse): string {
+    let authResponseUrl = "https://dummy.com";
+
+    for (const [name, value] of Object.entries(authResponse)) {
+        if (value === undefined) {
+            continue;
+        }
+        authResponseUrl = addOrUpdateSearchParam({
+            url: authResponseUrl,
+            name,
+            value,
+            encodeMethod: "www-form"
+        });
+    }
+
+    authResponseUrl = `${authResponseUrl}#${authResponseUrl.split("?")[1]}`;
+
+    return authResponseUrl;
+}

package/src/core/Oidc.ts

@@ -0,0 +1,140 @@
+import type { OidcInitializationError } from "./OidcInitializationError";
+
+export declare type Oidc<
+    DecodedIdToken extends Record<string, unknown> = Oidc.Tokens.DecodedIdToken_base
+> = Oidc.LoggedIn<DecodedIdToken> | Oidc.NotLoggedIn;
+
+export declare namespace Oidc {
+    export type Common = {
+        params: {
+            issuerUri: string;
+            clientId: string;
+        };
+    };
+
+    export type NotLoggedIn = Common & {
+        isUserLoggedIn: false;
+        login: (params: {
+            doesCurrentHrefRequiresAuth: boolean;
+            /**
+             * Add extra query parameters to the url before redirecting to the login pages.
+             */
+            extraQueryParams?: Record<string, string | undefined>;
+            /**
+             * Where to redirect after successful login.
+             * Default: window.location.href (here)
+             *
+             * It does not need to include the origin, eg: "/dashboard"
+             */
+            redirectUrl?: string;
+
+            /**
+             * Transform the url before redirecting to the login pages.
+             * Prefer using the extraQueryParams parameter if you're only adding query parameters.
+             */
+            transformUrlBeforeRedirect?: (url: string) => string;
+        }) => Promise<never>;
+        initializationError: OidcInitializationError | undefined;
+    };
+
+    export type LoggedIn<DecodedIdToken extends Record<string, unknown> = Record<string, unknown>> =
+        Common & {
+            isUserLoggedIn: true;
+            renewTokens(params?: {
+                extraTokenParams?: Record<string, string | undefined>;
+            }): Promise<void>;
+            getTokens: () => Promise<Tokens<DecodedIdToken>>;
+            subscribeToTokensChange: (onTokenChange: (tokens: Tokens<DecodedIdToken>) => void) => {
+                unsubscribe: () => void;
+            };
+            getDecodedIdToken: () => DecodedIdToken;
+            logout: (
+                params:
+                    | { redirectTo: "home" | "current page" }
+                    | { redirectTo: "specific url"; url: string }
+            ) => Promise<never>;
+            goToAuthServer: (params: {
+                extraQueryParams?: Record<string, string | undefined>;
+                redirectUrl?: string;
+                transformUrlBeforeRedirect?: (url: string) => string;
+            }) => Promise<never>;
+            subscribeToAutoLogoutCountdown: (
+                tickCallback: (params: { secondsLeft: number | undefined }) => void
+            ) => { unsubscribeFromAutoLogoutCountdown: () => void };
+            /**
+             * If you called `goToAuthServer` or `login` with extraQueryParams, this object let you know the outcome of the
+             * of the action that was intended.
+             *
+             * For example, on a Keycloak server, if you called `goToAuthServer({ extraQueryParams: { kc_action: "UPDATE_PASSWORD" } })`
+             * you'll get back: `{ extraQueryParams: { kc_action: "UPDATE_PASSWORD" }, result: { kc_action_status: "success" } }` (or "cancelled")
+             */
+            backFromAuthServer:
+                | {
+                      extraQueryParams: Record<string, string>;
+                      result: Record<string, string>;
+                  }
+                | undefined;
+            /**
+             * This is true when the user has just returned from the login pages.
+             * This is also true when the user navigate to your app and was able to be silently signed in because there was still a valid session.
+             * This false however when the use just reload the page.
+             *
+             * This can be used to perform some action related to session initialization
+             * but avoiding doing it repeatedly every time the user reload the page.
+             *
+             * Note that this is referring to the browser session and not the OIDC session
+             * on the server side.
+             *
+             * If you want to perform an action only when a new OIDC session is created
+             * you can test oidc.isNewBrowserSession && oidc.backFromAuthServer !== undefined
+             */
+            isNewBrowserSession: boolean;
+        };
+
+    export type Tokens<DecodedIdToken extends Record<string, unknown> = Tokens.DecodedIdToken_base> =
+        | Tokens.WithRefreshToken<DecodedIdToken>
+        | Tokens.WithoutRefreshToken<DecodedIdToken>;
+
+    export namespace Tokens {
+        export type Common<DecodedIdToken> = {
+            accessToken: string;
+            accessTokenExpirationTime: number;
+            idToken: string;
+            decodedIdToken: DecodedIdToken;
+            /**
+             * decodedIdToken_original = decodeJwt(idToken);
+             * decodedIdToken = decodedIdTokenSchema.parse(decodedIdToken_original)
+             *
+             * The idea here is that if you have provided a zod schema as `decodedIdTokenSchema`
+             * it will strip out every claim that you haven't specified.
+             * You might even be applying some transformation.
+             *
+             * `decodedIdToken_original` is the actual decoded payload of the  id_token, untransformed.
+             * */
+            decodedIdToken_original: DecodedIdToken_base;
+            /** Read from id_token's JWT, iat claim value, it's a JavaScript timestamp (millisecond epoch) */
+            issuedAtTime: number;
+        };
+
+        export type WithRefreshToken<DecodedIdToken> = Common<DecodedIdToken> & {
+            hasRefreshToken: true;
+            refreshToken: string;
+            refreshTokenExpirationTime: number | undefined;
+        };
+
+        export type WithoutRefreshToken<DecodedIdToken> = Common<DecodedIdToken> & {
+            hasRefreshToken: false;
+            refreshToken?: never;
+            refreshTokenExpirationTime?: never;
+        };
+
+        export type DecodedIdToken_base = {
+            iss: string;
+            sub: string;
+            aud: string | string[];
+            exp: number;
+            iat: number;
+            [claimName: string]: unknown;
+        };
+    }
+}

package/src/core/OidcInitializationError.ts

@@ -0,0 +1,19 @@
+export class OidcInitializationError extends Error {
+    public readonly isAuthServerLikelyDown: boolean;
+
+    constructor(params: { messageOrCause: string | Error; isAuthServerLikelyDown: boolean }) {
+        super(
+            (() => {
+                if (typeof params.messageOrCause === "string") {
+                    return params.messageOrCause;
+                } else {
+                    return `Unknown initialization error: ${params.messageOrCause.message}`;
+                }
+            })(),
+            // @ts-expect-error
+            { cause: typeof params.messageOrCause === "string" ? undefined : params.messageOrCause }
+        );
+        this.isAuthServerLikelyDown = params.isAuthServerLikelyDown;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}