keycloakify 6.0.0-beta.3 → 6.0.0-beta.7

package/src/bin/create-keycloak-email-directory.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { downloadBuiltinKeycloakTheme } from "./download-builtin-keycloak-theme";
-import { keycloakThemeEmailDirPath } from "./build-keycloak-theme";
+import { keycloakThemeEmailDirPath } from "./keycloakify";
 import { join as pathJoin, basename as pathBasename } from "path";
 import { transformCodebase } from "./tools/transformCodebase";
 import { promptKeycloakVersion } from "./promptKeycloakVersion";
@@ -21,12 +21,12 @@ if (require.main === module) {
 
         downloadBuiltinKeycloakTheme({
             keycloakVersion,
-            "destDirPath": builtinKeycloakThemeTmpDirPath,
+            "destDirPath": builtinKeycloakThemeTmpDirPath
         });
 
         transformCodebase({
             "srcDirPath": pathJoin(builtinKeycloakThemeTmpDirPath, "base", "email"),
-            "destDirPath": keycloakThemeEmailDirPath,
+            "destDirPath": keycloakThemeEmailDirPath
         });
 
         console.log(`./${pathBasename(keycloakThemeEmailDirPath)} ready to be customized`);

package/src/bin/download-builtin-keycloak-theme.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { keycloakThemeBuildingDirPath } from "./build-keycloak-theme";
+import { keycloakThemeBuildingDirPath } from "./keycloakify";
 import { join as pathJoin } from "path";
 import { downloadAndUnzip } from "./tools/downloadAndUnzip";
 import { promptKeycloakVersion } from "./promptKeycloakVersion";
@@ -13,6 +13,7 @@ export function downloadBuiltinKeycloakTheme(params: { keycloakVersion: string;
             "destDirPath": destDirPath,
             "url": `https://github.com/keycloak/keycloak/archive/refs/tags/${keycloakVersion}.zip`,
             "pathOfDirToExtractInArchive": `keycloak-${keycloakVersion}/themes/src/main/resources${ext}/theme`,
+            "cacheDirPath": pathJoin(keycloakThemeBuildingDirPath, ".cache")
         });
     }
 }
@@ -27,7 +28,7 @@ if (require.main === module) {
 
         downloadBuiltinKeycloakTheme({
             keycloakVersion,
-            destDirPath,
+            destDirPath
         });
     })();
 }

package/src/bin/generate-i18n-messages.ts

@@ -1,15 +1,18 @@
 import "minimal-polyfills/Object.fromEntries";
 import * as fs from "fs";
-import { join as pathJoin, relative as pathRelative } from "path";
+import { join as pathJoin, relative as pathRelative, dirname as pathDirname } from "path";
 import { crawl } from "./tools/crawl";
 import { downloadBuiltinKeycloakTheme } from "./download-builtin-keycloak-theme";
 import { getProjectRoot } from "./tools/getProjectRoot";
 import { rm_rf, rm_r } from "./tools/rm";
 
+//NOTE: To run without argument when we want to generate src/i18n/generated_kcMessages files,
+// update the version array for generating for newer version.
+
 //@ts-ignore
 const propertiesParser = require("properties-parser");
 
-for (const keycloakVersion of ["11.0.3", "15.0.2", "16.1.0"]) {
+for (const keycloakVersion of ["11.0.3", "15.0.2", "18.0.1"]) {
     console.log({ keycloakVersion });
 
     const tmpDirPath = pathJoin(getProjectRoot(), "tmp_xImOef9dOd44");
@@ -18,7 +21,7 @@ for (const keycloakVersion of ["11.0.3", "15.0.2", "16.1.0"]) {
 
     downloadBuiltinKeycloakTheme({
         keycloakVersion,
-        "destDirPath": tmpDirPath,
+        "destDirPath": tmpDirPath
     });
 
     type Dictionary = { [idiomId: string]: string };
@@ -39,36 +42,40 @@ for (const keycloakVersion of ["11.0.3", "15.0.2", "16.1.0"]) {
 
             (record[typeOfPage] ??= {})[language.replace(/_/g, "-")] = Object.fromEntries(
                 Object.entries(propertiesParser.parse(fs.readFileSync(pathJoin(baseThemeDirPath, filePath)).toString("utf8"))).map(
-                    ([key, value]: any) => [key, value.replace(/''/g, "'")],
-                ),
+                    ([key, value]: any) => [key, value.replace(/''/g, "'")]
+                )
             );
         });
     }
 
     rm_r(tmpDirPath);
 
-    const targetDirPath = pathJoin(getProjectRoot(), "src", "lib", "i18n", "generated_kcMessages", keycloakVersion);
-
-    fs.mkdirSync(targetDirPath, { "recursive": true });
-
     Object.keys(record).forEach(pageType => {
-        const filePath = pathJoin(targetDirPath, `${pageType}.ts`);
-
-        fs.writeFileSync(
-            filePath,
-            Buffer.from(
-                [
-                    `//This code was automatically generated by running ${pathRelative(getProjectRoot(), __filename)}`,
-                    "//PLEASE DO NOT EDIT MANUALLY",
-                    "",
-                    "/* spell-checker: disable */",
-                    `export const kcMessages= ${JSON.stringify(record[pageType], null, 2)};`,
-                    "/* spell-checker: enable */",
-                ].join("\n"),
-                "utf8",
-            ),
-        );
-
-        console.log(`${filePath} wrote`);
+        const recordForPageType = record[pageType];
+
+        Object.keys(recordForPageType).forEach(language => {
+            const filePath = pathJoin(getProjectRoot(), "src", "lib", "i18n", "generated_messages", keycloakVersion, pageType, `${language}.ts`);
+
+            fs.mkdirSync(pathDirname(filePath), { "recursive": true });
+
+            fs.writeFileSync(
+                filePath,
+                Buffer.from(
+                    [
+                        `//This code was automatically generated by running ${pathRelative(getProjectRoot(), __filename)}`,
+                        "//PLEASE DO NOT EDIT MANUALLY",
+                        "",
+                        "/* spell-checker: disable */",
+                        `const messages= ${JSON.stringify(recordForPageType[language], null, 2)};`,
+                        "",
+                        "export default messages;",
+                        "/* spell-checker: enable */"
+                    ].join("\n"),
+                    "utf8"
+                )
+            );
+
+            console.log(`${filePath} wrote`);
+        });
     });
 }

package/src/bin/keycloakify/BuildOptions.ts

@@ -0,0 +1,177 @@
+import { z } from "zod";
+import { assert } from "tsafe/assert";
+import type { Equals } from "tsafe";
+import { id } from "tsafe/id";
+import { parse as urlParse } from "url";
+
+type ParsedPackageJson = {
+    name: string;
+    version: string;
+    homepage?: string;
+    keycloakify?: {
+        extraPages?: string[];
+        extraThemeProperties?: string[];
+        isAppAndKeycloakServerSharingSameDomain?: boolean;
+    };
+};
+
+const zParsedPackageJson = z.object({
+    "name": z.string(),
+    "version": z.string(),
+    "homepage": z.string().optional(),
+    "keycloakify": z
+        .object({
+            "extraPages": z.array(z.string()).optional(),
+            "extraThemeProperties": z.array(z.string()).optional(),
+            "isAppAndKeycloakServerSharingSameDomain": z.boolean().optional()
+        })
+        .optional()
+});
+
+assert<Equals<ReturnType<typeof zParsedPackageJson["parse"]>, ParsedPackageJson>>();
+
+/** Consolidated build option gathered form CLI arguments and config in package.json */
+export type BuildOptions = BuildOptions.Standalone | BuildOptions.ExternalAssets;
+
+export namespace BuildOptions {
+    export type Common = {
+        version: string;
+        themeName: string;
+        extraPages?: string[];
+        extraThemeProperties?: string[];
+        //NOTE: Only for the pom.xml file, questionable utility...
+        groupId: string;
+    };
+
+    export type Standalone = Common & {
+        isStandalone: true;
+        urlPathname: string | undefined;
+    };
+
+    export type ExternalAssets = ExternalAssets.SameDomain | ExternalAssets.DifferentDomains;
+
+    export namespace ExternalAssets {
+        export type CommonExternalAssets = Common & {
+            isStandalone: false;
+        };
+
+        export type SameDomain = CommonExternalAssets & {
+            isAppAndKeycloakServerSharingSameDomain: true;
+        };
+
+        export type DifferentDomains = CommonExternalAssets & {
+            isAppAndKeycloakServerSharingSameDomain: false;
+            urlOrigin: string;
+            urlPathname: string | undefined;
+        };
+    }
+}
+
+export function readBuildOptions(params: {
+    packageJson: string;
+    CNAME: string | undefined;
+    isExternalAssetsCliParamProvided: boolean;
+}): BuildOptions {
+    const { packageJson, CNAME, isExternalAssetsCliParamProvided } = params;
+
+    const parsedPackageJson = zParsedPackageJson.parse(JSON.parse(packageJson));
+
+    const url = (() => {
+        const { homepage } = parsedPackageJson;
+
+        let url: URL | undefined = undefined;
+
+        if (homepage !== undefined) {
+            url = new URL(homepage);
+        }
+
+        if (CNAME !== undefined) {
+            url = new URL(`https://${CNAME.replace(/\s+$/, "")}`);
+        }
+
+        if (url === undefined) {
+            return undefined;
+        }
+
+        return {
+            "origin": url.origin,
+            "pathname": (() => {
+                const out = url.pathname.replace(/([^/])$/, "$1/");
+
+                return out === "/" ? undefined : out;
+            })()
+        };
+    })();
+
+    const common: BuildOptions.Common = (() => {
+        const { name, keycloakify = {}, version, homepage } = parsedPackageJson;
+
+        const { extraPages, extraThemeProperties } = keycloakify ?? {};
+
+        const themeName = name
+            .replace(/^@(.*)/, "$1")
+            .split("/")
+            .join("-");
+
+        return {
+            themeName,
+            "groupId": (() => {
+                const fallbackGroupId = `${themeName}.keycloak`;
+
+                return (
+                    (!homepage
+                        ? fallbackGroupId
+                        : urlParse(homepage)
+                              .host?.replace(/:[0-9]+$/, "")
+                              ?.split(".")
+                              .reverse()
+                              .join(".") ?? fallbackGroupId) + ".keycloak"
+                );
+            })(),
+            "version": version,
+            extraPages,
+            extraThemeProperties
+        };
+    })();
+
+    if (isExternalAssetsCliParamProvided) {
+        const commonExternalAssets = id<BuildOptions.ExternalAssets.CommonExternalAssets>({
+            ...common,
+            "isStandalone": false
+        });
+
+        if (parsedPackageJson.keycloakify?.isAppAndKeycloakServerSharingSameDomain) {
+            return id<BuildOptions.ExternalAssets.SameDomain>({
+                ...commonExternalAssets,
+                "isAppAndKeycloakServerSharingSameDomain": true
+            });
+        } else {
+            assert(
+                url !== undefined,
+                [
+                    "Can't compile in external assets mode if we don't know where",
+                    "the app will be hosted.",
+                    "You should provide a homepage field in the package.json (or create a",
+                    "public/CNAME file.",
+                    "Alternatively, if your app and the Keycloak server are on the same domain, ",
+                    "eg https://example.com is your app and https://example.com/auth is the keycloak",
+                    'admin UI, you can set "keycloakify": { "isAppAndKeycloakServerSharingSameDomain": true }',
+                    "in your package.json"
+                ].join(" ")
+            );
+
+            return id<BuildOptions.ExternalAssets.DifferentDomains>({
+                ...commonExternalAssets,
+                "isAppAndKeycloakServerSharingSameDomain": false,
+                "urlOrigin": url.origin,
+                "urlPathname": url.pathname
+            });
+        }
+    }
+
+    return id<BuildOptions.Standalone>({
+        ...common,
+        "isStandalone": true,
+        "urlPathname": url?.pathname
+    });
+}

package/src/bin/{build-keycloak-theme → keycloakify}/generateFtl/ftl_object_to_js_code_declaring_an_object.ftl

@@ -30,6 +30,9 @@ ${ftl_object_to_js_code_declaring_an_object(.data_model, [])?no_esc};
         </#attempt>
     
         "printIfExists": function (fieldName, x) {
+            <#if !messagesPerField?? >
+                return undefined;
+            </#if>
             <#list fieldNames as fieldName>
                 if(fieldName === "${fieldName}" ){
                     <#attempt>
@@ -41,6 +44,9 @@ ${ftl_object_to_js_code_declaring_an_object(.data_model, [])?no_esc};
             throw new Error("There is no " + fieldName + " field");
         },
         "existsError": function (fieldName) {
+            <#if !messagesPerField?? >
+                return false;
+            </#if>
             <#list fieldNames as fieldName>
                 if(fieldName === "${fieldName}" ){
                     <#attempt>
@@ -52,6 +58,9 @@ ${ftl_object_to_js_code_declaring_an_object(.data_model, [])?no_esc};
             throw new Error("There is no " + fieldName + " field");
         },
         "get": function (fieldName) {
+            <#if !messagesPerField?? >
+                return '';
+            </#if>
             <#list fieldNames as fieldName>
                 if(fieldName === "${fieldName}" ){
                     <#attempt>
@@ -65,6 +74,9 @@ ${ftl_object_to_js_code_declaring_an_object(.data_model, [])?no_esc};
             throw new Error("There is no " + fieldName + " field");
         },
         "exists": function (fieldName) {
+            <#if !messagesPerField?? >
+                return false;
+            </#if>
             <#list fieldNames as fieldName>
                 if(fieldName === "${fieldName}" ){
                     <#attempt>
@@ -137,6 +149,9 @@ ${ftl_object_to_js_code_declaring_an_object(.data_model, [])?no_esc};
                         key == "identityProviderBrokerCtx" && 
                         are_same_path(path, []) &&
                         ["login-idp-link-confirm.ftl", "login-idp-link-email.ftl" ]?seq_contains(pageId)
+                    ) ||  (
+                        ["masterAdminClient", "delegateForUpdate", "defaultRole"]?seq_contains(key) &&
+                        are_same_path(path, ["realm"])
                     )
                 >
                     <#local out_seq += ["/*If you need '" + key + "' on " + pageId + ", please submit an issue to the Keycloakify repo*/"]>
@@ -155,33 +170,6 @@ ${ftl_object_to_js_code_declaring_an_object(.data_model, [])?no_esc};
 
                 </#if>
                 
-                <#if key == "showUsername" && are_same_path(path, ["auth"])>
-                    <#attempt>
-                        <#return auth.showUsername()?c>
-                    <#recover>
-                        <#local out_seq += ["/*Couldn't evaluate auth.showUsername()*/"]>
-                        <#continue>
-                    </#attempt>
-                </#if>
-
-                <#if key == "showResetCredentials" && are_same_path(path, ["auth"])>
-                    <#attempt>
-                        <#return auth.showResetCredentials()?c>
-                    <#recover>
-                        <#local out_seq += ["/*Couldn't evaluate auth.showResetCredentials()*/"]>
-                        <#continue>
-                    </#attempt>
-                </#if>
-
-                <#if key == "showTryAnotherWayLink" && are_same_path(path, ["auth"])>
-                    <#attempt>
-                        <#return auth.showTryAnotherWayLink()?c>
-                    <#recover>
-                        <#local out_seq += ["/*Couldn't evaluate auth.showTryAnotherWayLink()*/"]>
-                        <#continue>
-                    </#attempt>
-                </#if>
-
                 <#attempt>
                     <#if !object[key]??>
                         <#continue>
@@ -229,6 +217,31 @@ ${ftl_object_to_js_code_declaring_an_object(.data_model, [])?no_esc};
         </#attempt>
 
         <#if isMethod>
+
+            <#if are_same_path(path, ["auth", "showUsername"])>
+                <#attempt>
+                    <#return auth.showUsername()?c>
+                <#recover>
+                    <#return "ABORT: Couldn't evaluate auth.showUsername()">
+                </#attempt>
+            </#if>
+
+            <#if are_same_path(path, ["auth", "showResetCredentials"])>
+                <#attempt>
+                    <#return auth.showResetCredentials()?c>
+                <#recover>
+                    <#return "ABORT: Couldn't evaluate auth.showResetCredentials()">
+                </#attempt>
+            </#if>
+
+            <#if are_same_path(path, ["auth", "showTryAnotherWayLink"])>
+                <#attempt>
+                    <#return auth.showTryAnotherWayLink()?c>
+                <#recover>
+                    <#return "ABORT: Couldn't evaluate auth.showTryAnotherWayLink()">
+                </#attempt>
+            </#if>
+
             <#return "ABORT: It's a method">
         </#if>
 
@@ -292,7 +305,7 @@ ${ftl_object_to_js_code_declaring_an_object(.data_model, [])?no_esc};
 </#function>
 <#function are_same_path path searchedPath>
 
-    <#if path?size != path?size>
+    <#if path?size != searchedPath?size>
         <#return false>
     </#if>
 

package/src/bin/keycloakify/generateFtl/generateFtl.ts

@@ -0,0 +1,185 @@
+import cheerio from "cheerio";
+import { replaceImportsFromStaticInJsCode } from "../replacers/replaceImportsFromStaticInJsCode";
+import { generateCssCodeToDefineGlobals } from "../replacers/replaceImportsInCssCode";
+import { replaceImportsInInlineCssCode } from "../replacers/replaceImportsInInlineCssCode";
+import * as fs from "fs";
+import { join as pathJoin } from "path";
+import { objectKeys } from "tsafe/objectKeys";
+import { ftlValuesGlobalName } from "../ftlValuesGlobalName";
+import type { BuildOptions } from "../BuildOptions";
+import { assert } from "tsafe/assert";
+import { Reflect } from "tsafe/Reflect";
+
+// https://github.com/keycloak/keycloak/blob/main/services/src/main/java/org/keycloak/forms/login/freemarker/Templates.java
+export const pageIds = [
+    "login.ftl",
+    "register.ftl",
+    "register-user-profile.ftl",
+    "info.ftl",
+    "error.ftl",
+    "login-reset-password.ftl",
+    "login-verify-email.ftl",
+    "terms.ftl",
+    "login-otp.ftl",
+    "login-update-profile.ftl",
+    "login-update-password.ftl",
+    "login-idp-link-confirm.ftl",
+    "login-idp-link-email.ftl",
+    "login-page-expired.ftl",
+    "login-config-totp.ftl",
+    "logout-confirm.ftl"
+] as const;
+
+export type BuildOptionsLike = BuildOptionsLike.Standalone | BuildOptionsLike.ExternalAssets;
+
+export namespace BuildOptionsLike {
+    export type Standalone = {
+        isStandalone: true;
+        urlPathname: string | undefined;
+    };
+
+    export type ExternalAssets = ExternalAssets.SameDomain | ExternalAssets.DifferentDomains;
+
+    export namespace ExternalAssets {
+        export type CommonExternalAssets = {
+            isStandalone: false;
+        };
+
+        export type SameDomain = CommonExternalAssets & {
+            isAppAndKeycloakServerSharingSameDomain: true;
+        };
+
+        export type DifferentDomains = CommonExternalAssets & {
+            isAppAndKeycloakServerSharingSameDomain: false;
+            urlOrigin: string;
+            urlPathname: string | undefined;
+        };
+    }
+}
+
+{
+    const buildOptions = Reflect<BuildOptions>();
+
+    assert<typeof buildOptions extends BuildOptionsLike ? true : false>();
+}
+
+export type PageId = typeof pageIds[number];
+
+export function generateFtlFilesCodeFactory(params: {
+    indexHtmlCode: string;
+    //NOTE: Expected to be an empty object if external assets mode is enabled.
+    cssGlobalsToDefine: Record<string, string>;
+    buildOptions: BuildOptionsLike;
+}) {
+    const { cssGlobalsToDefine, indexHtmlCode, buildOptions } = params;
+
+    const $ = cheerio.load(indexHtmlCode);
+
+    fix_imports_statements: {
+        if (!buildOptions.isStandalone && buildOptions.isAppAndKeycloakServerSharingSameDomain) {
+            break fix_imports_statements;
+        }
+
+        $("script:not([src])").each((...[, element]) => {
+            const { fixedJsCode } = replaceImportsFromStaticInJsCode({
+                "jsCode": $(element).html()!,
+                buildOptions
+            });
+
+            $(element).text(fixedJsCode);
+        });
+
+        $("style").each((...[, element]) => {
+            const { fixedCssCode } = replaceImportsInInlineCssCode({
+                "cssCode": $(element).html()!,
+                buildOptions
+            });
+
+            $(element).text(fixedCssCode);
+        });
+
+        (
+            [
+                ["link", "href"],
+                ["script", "src"]
+            ] as const
+        ).forEach(([selector, attrName]) =>
+            $(selector).each((...[, element]) => {
+                const href = $(element).attr(attrName);
+
+                if (href === undefined) {
+                    return;
+                }
+
+                $(element).attr(
+                    attrName,
+                    buildOptions.isStandalone
+                        ? href.replace(new RegExp(`^${(buildOptions.urlPathname ?? "/").replace(/\//g, "\\/")}`), "${url.resourcesPath}/build/")
+                        : href.replace(/^\//, `${buildOptions.urlOrigin}/`)
+                );
+            })
+        );
+
+        if (Object.keys(cssGlobalsToDefine).length !== 0) {
+            $("head").prepend(
+                [
+                    "",
+                    "<style>",
+                    generateCssCodeToDefineGlobals({
+                        cssGlobalsToDefine,
+                        buildOptions
+                    }).cssCodeToPrependInHead,
+                    "</style>",
+                    ""
+                ].join("\n")
+            );
+        }
+    }
+
+    //FTL is no valid html, we can't insert with cheerio, we put placeholder for injecting later.
+    const replaceValueBySearchValue = {
+        '{ "x": "vIdLqMeOed9sdLdIdOxdK0d" }': fs
+            .readFileSync(pathJoin(__dirname, "ftl_object_to_js_code_declaring_an_object.ftl"))
+            .toString("utf8")
+            .match(/^<script>const _=((?:.|\n)+)<\/script>[\n]?$/)![1],
+        "<!-- xIdLqMeOedErIdLsPdNdI9dSlxI -->": [
+            "<#if scripts??>",
+            "    <#list scripts as script>",
+            '        <script src="${script}" type="text/javascript"></script>',
+            "    </#list>",
+            "</#if>"
+        ].join("\n")
+    };
+
+    $("head").prepend(
+        [
+            "<script>",
+            `    window.${ftlValuesGlobalName}= ${objectKeys(replaceValueBySearchValue)[0]};`,
+            "</script>",
+            "",
+            objectKeys(replaceValueBySearchValue)[1]
+        ].join("\n")
+    );
+
+    const partiallyFixedIndexHtmlCode = $.html();
+
+    function generateFtlFilesCode(params: { pageId: string }): {
+        ftlCode: string;
+    } {
+        const { pageId } = params;
+
+        const $ = cheerio.load(partiallyFixedIndexHtmlCode);
+
+        let ftlCode = $.html();
+
+        Object.entries({
+            ...replaceValueBySearchValue,
+            //If updated, don't forget to change in the ftl script as well.
+            "PAGE_ID_xIgLsPgGId9D8e": pageId
+        }).map(([searchValue, replaceValue]) => (ftlCode = ftlCode.replace(searchValue, replaceValue)));
+
+        return { ftlCode };
+    }
+
+    return { generateFtlFilesCode };
+}