keycloakify 6.13.2 → 7.0.0-rc.3

package/src/kcContext/KcContext.ts

@@ -0,0 +1,499 @@
+import type { PageId } from "../bin/keycloakify/generateFtl";
+import { assert } from "tsafe/assert";
+import type { Equals } from "tsafe";
+import type { MessageKey } from "../i18n/i18n";
+
+type ExtractAfterStartingWith<Prefix extends string, StrEnum> = StrEnum extends `${Prefix}${infer U}` ? U : never;
+
+/** Take theses type definition with a grain of salt.
+ * Some values might be undefined on some pages.
+ * (ex: url.loginAction is undefined on error.ftl)
+ */
+export type KcContext =
+    | KcContext.Login
+    | KcContext.Register
+    | KcContext.RegisterUserProfile
+    | KcContext.Info
+    | KcContext.Error
+    | KcContext.LoginResetPassword
+    | KcContext.LoginVerifyEmail
+    | KcContext.Terms
+    | KcContext.LoginOtp
+    | KcContext.LoginUsername
+    | KcContext.WebauthnAuthenticate
+    | KcContext.LoginPassword
+    | KcContext.LoginUpdatePassword
+    | KcContext.LoginUpdateProfile
+    | KcContext.LoginIdpLinkConfirm
+    | KcContext.LoginIdpLinkEmail
+    | KcContext.LoginPageExpired
+    | KcContext.LoginConfigTotp
+    | KcContext.LogoutConfirm
+    | KcContext.UpdateUserProfile
+    | KcContext.IdpReviewUserProfile;
+
+export declare namespace KcContext {
+    export type Common = {
+        url: {
+            loginAction: string;
+            resourcesPath: string;
+            resourcesCommonPath: string;
+            loginRestartFlowUrl: string;
+            loginUrl: string;
+        };
+        realm: {
+            name: string;
+            displayName?: string;
+            displayNameHtml?: string;
+            internationalizationEnabled: boolean;
+            registrationEmailAsUsername: boolean;
+        };
+        /** Undefined if !realm.internationalizationEnabled */
+        locale?: {
+            supported: {
+                url: string;
+                label: string;
+                languageTag: string;
+            }[];
+            currentLanguageTag: string;
+        };
+        auth?: {
+            showUsername?: boolean;
+            showResetCredentials?: boolean;
+            showTryAnotherWayLink?: boolean;
+            attemptedUsername?: string;
+        };
+        scripts: string[];
+        message?: {
+            type: "success" | "warning" | "error" | "info";
+            summary: string;
+        };
+        client: {
+            clientId: string;
+            name?: string;
+            description?: string;
+        };
+        isAppInitiatedAction: boolean;
+        messagesPerField: {
+            printIfExists: <T>(fieldName: string, x: T) => T | undefined;
+            existsError: (fieldName: string) => boolean;
+            get: (fieldName: string) => string;
+            exists: (fieldName: string) => boolean;
+        };
+    };
+
+    export type Login = Common & {
+        pageId: "login.ftl";
+        url: {
+            loginResetCredentialsUrl: string;
+            registrationUrl: string;
+        };
+        realm: {
+            loginWithEmailAllowed: boolean;
+            rememberMe: boolean;
+            password: boolean;
+            resetPasswordAllowed: boolean;
+            registrationAllowed: boolean;
+        };
+        auth: {
+            selectedCredential?: string;
+        };
+        registrationDisabled: boolean;
+        login: {
+            username?: string;
+            rememberMe?: boolean;
+        };
+        usernameEditDisabled: boolean;
+        social: {
+            displayInfo: boolean;
+            providers?: {
+                loginUrl: string;
+                alias: string;
+                providerId: string;
+                displayName: string;
+            }[];
+        };
+    };
+
+    export type Register = RegisterUserProfile.CommonWithLegacy & {
+        pageId: "register.ftl";
+        register: {
+            formData: {
+                firstName?: string;
+                displayName?: string;
+                lastName?: string;
+                email?: string;
+                username?: string;
+            };
+        };
+    };
+
+    export type RegisterUserProfile = RegisterUserProfile.CommonWithLegacy & {
+        pageId: "register-user-profile.ftl";
+        profile: {
+            context: "REGISTRATION_PROFILE";
+            attributes: Attribute[];
+            attributesByName: Record<string, Attribute>;
+        };
+    };
+
+    export namespace RegisterUserProfile {
+        export type CommonWithLegacy = Common & {
+            url: {
+                registrationAction: string;
+            };
+            passwordRequired: boolean;
+            recaptchaRequired: boolean;
+            recaptchaSiteKey?: string;
+            social: {
+                displayInfo: boolean;
+                providers?: {
+                    loginUrl: string;
+                    alias: string;
+                    providerId: string;
+                    displayName: string;
+                }[];
+            };
+        };
+    }
+
+    export type Info = Common & {
+        pageId: "info.ftl";
+        messageHeader?: string;
+        requiredActions?: ExtractAfterStartingWith<"requiredAction.", MessageKey>[];
+        skipLink: boolean;
+        pageRedirectUri?: string;
+        actionUri?: string;
+        client: {
+            baseUrl?: string;
+        };
+    };
+
+    export type Error = Common & {
+        pageId: "error.ftl";
+        client?: {
+            baseUrl?: string;
+        };
+        message: NonNullable<Common["message"]>;
+    };
+
+    export type LoginResetPassword = Common & {
+        pageId: "login-reset-password.ftl";
+        realm: {
+            loginWithEmailAllowed: boolean;
+        };
+    };
+
+    export type LoginVerifyEmail = Common & {
+        pageId: "login-verify-email.ftl";
+        //NOTE: Optional because maybe it wasn't defined in older keycloak versions.
+        user?: {
+            email: string;
+        };
+    };
+
+    export type Terms = Common & {
+        pageId: "terms.ftl";
+    };
+
+    export type LoginOtp = Common & {
+        pageId: "login-otp.ftl";
+        otpLogin: {
+            userOtpCredentials: { id: string; userLabel: string }[];
+        };
+    };
+
+    export type LoginUsername = Common & {
+        pageId: "login-username.ftl";
+        url: {
+            loginResetCredentialsUrl: string;
+            registrationUrl: string;
+        };
+        realm: {
+            loginWithEmailAllowed: boolean;
+            rememberMe: boolean;
+            password: boolean;
+            resetPasswordAllowed: boolean;
+            registrationAllowed: boolean;
+        };
+        registrationDisabled: boolean;
+        login: {
+            username?: string;
+            rememberMe?: boolean;
+        };
+        usernameHidden?: boolean;
+        social: {
+            displayInfo: boolean;
+            providers?: {
+                loginUrl: string;
+                alias: string;
+                providerId: string;
+                displayName: string;
+            }[];
+        };
+    };
+
+    export type LoginPassword = Common & {
+        pageId: "login-password.ftl";
+        url: {
+            loginResetCredentialsUrl: string;
+            registrationUrl: string;
+        };
+        realm: {
+            resetPasswordAllowed: boolean;
+        };
+        auth?: {
+            showUsername?: boolean;
+            showResetCredentials?: boolean;
+            showTryAnotherWayLink?: boolean;
+            attemptedUsername?: string;
+        };
+        social: {
+            displayInfo: boolean;
+        };
+        login: {
+            password?: string;
+        };
+    };
+
+    export type WebauthnAuthenticate = Common & {
+        pageId: "webauthn-authenticate.ftl";
+        authenticators: {
+            authenticators: WebauthnAuthenticate.WebauthnAuthenticator[];
+        };
+        challenge: string;
+        // I hate this:
+        userVerification: UserVerificationRequirement | "not specified";
+        rpId: string;
+        createTimeout: string;
+        isUserIdentified: "true" | "false";
+        shouldDisplayAuthenticators: boolean;
+        social: {
+            displayInfo: boolean;
+        };
+        login: {};
+    };
+
+    export namespace WebauthnAuthenticate {
+        export type WebauthnAuthenticator = {
+            credentialId: string;
+            transports: {
+                iconClass: string;
+                displayNameProperties: MessageKey[];
+            };
+            label: string;
+            createdAt: string;
+        };
+    }
+
+    export type LoginUpdatePassword = Common & {
+        pageId: "login-update-password.ftl";
+        username: string;
+    };
+
+    export type LoginUpdateProfile = Common & {
+        pageId: "login-update-profile.ftl";
+        user: {
+            editUsernameAllowed: boolean;
+            username?: string;
+            email?: string;
+            firstName?: string;
+            lastName?: string;
+        };
+    };
+
+    export type LoginIdpLinkConfirm = Common & {
+        pageId: "login-idp-link-confirm.ftl";
+        idpAlias: string;
+    };
+
+    export type LoginIdpLinkEmail = Common & {
+        pageId: "login-idp-link-email.ftl";
+        brokerContext: {
+            username: string;
+        };
+        idpAlias: string;
+    };
+
+    export type LoginPageExpired = Common & {
+        pageId: "login-page-expired.ftl";
+    };
+
+    export type LoginConfigTotp = Common & {
+        pageId: "login-config-totp.ftl";
+        mode?: "qr" | "manual" | undefined | null;
+        totp: {
+            totpSecretEncoded: string;
+            qrUrl: string;
+            policy: {
+                supportedApplications: string[];
+                algorithm: "HmacSHA1" | "HmacSHA256" | "HmacSHA512";
+                digits: number;
+                lookAheadWindow: number;
+            } & (
+                | {
+                      type: "totp";
+                      period: number;
+                  }
+                | {
+                      type: "hotp";
+                      initialCounter: number;
+                  }
+            );
+            totpSecretQrCode: string;
+            manualUrl: string;
+            totpSecret: string;
+            otpCredentials: { id: string; userLabel: string }[];
+        };
+    };
+
+    export type LogoutConfirm = Common & {
+        pageId: "logout-confirm.ftl";
+        url: {
+            logoutConfirmAction: string;
+        };
+        client: {
+            baseUrl?: string;
+        };
+        logoutConfirm: {
+            code: string;
+            skipLink?: boolean;
+        };
+    };
+
+    export type UpdateUserProfile = Common & {
+        pageId: "update-user-profile.ftl";
+        profile: {
+            attributes: Attribute[];
+            attributesByName: Record<string, Attribute>;
+        };
+    };
+
+    export type IdpReviewUserProfile = Common & {
+        pageId: "idp-review-user-profile.ftl";
+        profile: {
+            context: "IDP_REVIEW";
+            attributes: Attribute[];
+            attributesByName: Record<string, Attribute>;
+        };
+    };
+}
+
+export type Attribute = {
+    name: string;
+    displayName?: string;
+    required: boolean;
+    value?: string;
+    group?: string;
+    groupDisplayHeader?: string;
+    groupDisplayDescription?: string;
+    readOnly: boolean;
+    validators: Validators;
+    annotations: Record<string, string>;
+    groupAnnotations: Record<string, string>;
+    autocomplete?:
+        | "on"
+        | "off"
+        | "name"
+        | "honorific-prefix"
+        | "given-name"
+        | "additional-name"
+        | "family-name"
+        | "honorific-suffix"
+        | "nickname"
+        | "email"
+        | "username"
+        | "new-password"
+        | "current-password"
+        | "one-time-code"
+        | "organization-title"
+        | "organization"
+        | "street-address"
+        | "address-line1"
+        | "address-line2"
+        | "address-line3"
+        | "address-level4"
+        | "address-level3"
+        | "address-level2"
+        | "address-level1"
+        | "country"
+        | "country-name"
+        | "postal-code"
+        | "cc-name"
+        | "cc-given-name"
+        | "cc-additional-name"
+        | "cc-family-name"
+        | "cc-number"
+        | "cc-exp"
+        | "cc-exp-month"
+        | "cc-exp-year"
+        | "cc-csc"
+        | "cc-type"
+        | "transaction-currency"
+        | "transaction-amount"
+        | "language"
+        | "bday"
+        | "bday-day"
+        | "bday-month"
+        | "bday-year"
+        | "sex"
+        | "tel"
+        | "tel-country-code"
+        | "tel-national"
+        | "tel-area-code"
+        | "tel-local"
+        | "tel-extension"
+        | "impp"
+        | "url"
+        | "photo";
+};
+
+export type Validators = Partial<{
+    length: Validators.DoIgnoreEmpty & Validators.Range;
+    double: Validators.DoIgnoreEmpty & Validators.Range;
+    integer: Validators.DoIgnoreEmpty & Validators.Range;
+    email: Validators.DoIgnoreEmpty;
+    "up-immutable-attribute": {};
+    "up-attribute-required-by-metadata-value": {};
+    "up-username-has-value": {};
+    "up-duplicate-username": {};
+    "up-username-mutation": {};
+    "up-email-exists-as-username": {};
+    "up-blank-attribute-value": Validators.ErrorMessage & {
+        "fail-on-null": boolean;
+    };
+    "up-duplicate-email": {};
+    "local-date": Validators.DoIgnoreEmpty;
+    pattern: Validators.DoIgnoreEmpty & Validators.ErrorMessage & { pattern: string };
+    "person-name-prohibited-characters": Validators.DoIgnoreEmpty & Validators.ErrorMessage;
+    uri: Validators.DoIgnoreEmpty;
+    "username-prohibited-characters": Validators.DoIgnoreEmpty & Validators.ErrorMessage;
+    /** Made up validator that only exists in Keycloakify */
+    _compareToOther: Validators.DoIgnoreEmpty &
+        Validators.ErrorMessage & {
+            name: string;
+            shouldBe: "equal" | "different";
+        };
+    options: Validators.Options;
+}>;
+
+export declare namespace Validators {
+    export type DoIgnoreEmpty = {
+        "ignore.empty.value"?: boolean;
+    };
+
+    export type ErrorMessage = {
+        "error-message"?: string;
+    };
+
+    export type Range = {
+        /** "0", "1", "2"... yeah I know, don't tell me */
+        min?: `${number}`;
+        max?: `${number}`;
+    };
+    export type Options = {
+        options: string[];
+    };
+}
+
+assert<Equals<KcContext["pageId"], PageId>>();

package/src/kcContext/getKcContext.ts

@@ -0,0 +1,131 @@
+import type { KcContext, Attribute } from "./KcContext";
+import { kcContextMocks, kcContextCommonMock } from "./kcContextMocks";
+import type { DeepPartial } from "../tools/DeepPartial";
+import { deepAssign } from "../tools/deepAssign";
+import { id } from "tsafe/id";
+import { exclude } from "tsafe/exclude";
+import { assert } from "tsafe/assert";
+import type { ExtendKcContext } from "./getKcContextFromWindow";
+import { getKcContextFromWindow } from "./getKcContextFromWindow";
+import { pathJoin } from "../bin/tools/pathJoin";
+import { pathBasename } from "../tools/pathBasename";
+import { mockTestingResourcesCommonPath } from "../bin/mockTestingResourcesPath";
+import { symToStr } from "tsafe/symToStr";
+
+export function getKcContext<KcContextExtension extends { pageId: string } = never>(params?: {
+    mockPageId?: ExtendKcContext<KcContextExtension>["pageId"];
+    mockData?: readonly DeepPartial<ExtendKcContext<KcContextExtension>>[];
+}): { kcContext: ExtendKcContext<KcContextExtension> | undefined } {
+    const { mockPageId, mockData } = params ?? {};
+
+    const realKcContext = getKcContextFromWindow<KcContextExtension>();
+
+    if (mockPageId !== undefined && realKcContext === undefined) {
+        //TODO maybe trow if no mock fo custom page
+
+        console.log(
+            [
+                `%cKeycloakify: ${symToStr({ mockPageId })} set to ${mockPageId}.`,
+                `If assets are missing make sure you have built your Keycloak theme at least once.`
+            ].join(" "),
+            "background: red; color: yellow; font-size: medium"
+        );
+
+        const kcContextDefaultMock = kcContextMocks.find(({ pageId }) => pageId === mockPageId);
+
+        const partialKcContextCustomMock = mockData?.find(({ pageId }) => pageId === mockPageId);
+
+        if (kcContextDefaultMock === undefined && partialKcContextCustomMock === undefined) {
+            console.warn(
+                [
+                    `WARNING: You declared the non build in page ${mockPageId} but you didn't `,
+                    `provide mock data needed to debug the page outside of Keycloak as you are trying to do now.`,
+                    `Please check the documentation of the getKcContext function`
+                ].join("\n")
+            );
+        }
+
+        const kcContext: any = {};
+
+        deepAssign({
+            "target": kcContext,
+            "source": kcContextDefaultMock !== undefined ? kcContextDefaultMock : { "pageId": mockPageId, ...kcContextCommonMock }
+        });
+
+        if (partialKcContextCustomMock !== undefined) {
+            deepAssign({
+                "target": kcContext,
+                "source": partialKcContextCustomMock
+            });
+
+            if (
+                partialKcContextCustomMock.pageId === "register-user-profile.ftl" ||
+                partialKcContextCustomMock.pageId === "update-user-profile.ftl" ||
+                partialKcContextCustomMock.pageId === "idp-review-user-profile.ftl"
+            ) {
+                assert(
+                    kcContextDefaultMock?.pageId === "register-user-profile.ftl" ||
+                        kcContextDefaultMock?.pageId === "update-user-profile.ftl" ||
+                        kcContextDefaultMock?.pageId === "idp-review-user-profile.ftl"
+                );
+
+                const { attributes } = kcContextDefaultMock.profile;
+
+                id<KcContext.RegisterUserProfile>(kcContext).profile.attributes = [];
+                id<KcContext.RegisterUserProfile>(kcContext).profile.attributesByName = {};
+
+                const partialAttributes = [
+                    ...((partialKcContextCustomMock as DeepPartial<KcContext.RegisterUserProfile>).profile?.attributes ?? [])
+                ].filter(exclude(undefined));
+
+                attributes.forEach(attribute => {
+                    const partialAttribute = partialAttributes.find(({ name }) => name === attribute.name);
+
+                    const augmentedAttribute: Attribute = {} as any;
+
+                    deepAssign({
+                        "target": augmentedAttribute,
+                        "source": attribute
+                    });
+
+                    if (partialAttribute !== undefined) {
+                        partialAttributes.splice(partialAttributes.indexOf(partialAttribute), 1);
+
+                        deepAssign({
+                            "target": augmentedAttribute,
+                            "source": partialAttribute
+                        });
+                    }
+
+                    id<KcContext.RegisterUserProfile>(kcContext).profile.attributes.push(augmentedAttribute);
+                    id<KcContext.RegisterUserProfile>(kcContext).profile.attributesByName[augmentedAttribute.name] = augmentedAttribute;
+                });
+
+                partialAttributes
+                    .map(partialAttribute => ({ "validators": {}, ...partialAttribute }))
+                    .forEach(partialAttribute => {
+                        const { name } = partialAttribute;
+
+                        assert(name !== undefined, "If you define a mock attribute it must have at least a name");
+
+                        id<KcContext.RegisterUserProfile>(kcContext).profile.attributes.push(partialAttribute as any);
+                        id<KcContext.RegisterUserProfile>(kcContext).profile.attributesByName[name] = partialAttribute as any;
+                    });
+            }
+        }
+
+        return { kcContext };
+    }
+
+    if (realKcContext === undefined) {
+        return { "kcContext": undefined };
+    }
+
+    {
+        const { url } = realKcContext;
+
+        url.resourcesCommonPath = pathJoin(url.resourcesPath, pathBasename(mockTestingResourcesCommonPath));
+    }
+
+    return { "kcContext": realKcContext };
+}

package/src/kcContext/getKcContextFromWindow.ts

@@ -0,0 +1,11 @@
+import type { KcContext } from "./KcContext";
+import type { AndByDiscriminatingKey } from "../tools/AndByDiscriminatingKey";
+import { ftlValuesGlobalName } from "../bin/keycloakify/ftlValuesGlobalName";
+
+export type ExtendKcContext<KcContextExtension extends { pageId: string }> = [KcContextExtension] extends [never]
+    ? KcContext
+    : AndByDiscriminatingKey<"pageId", KcContextExtension & KcContext.Common, KcContext>;
+
+export function getKcContextFromWindow<KcContextExtension extends { pageId: string } = never>(): ExtendKcContext<KcContextExtension> | undefined {
+    return typeof window === "undefined" ? undefined : (window as any)[ftlValuesGlobalName];
+}

package/src/kcContext/index.ts

@@ -0,0 +1 @@
+export type { KcContext } from "./KcContext";