Protect against multiple instantiations of FidesJS and GPP (#6416)

Author: gilluminate

CHANGELOG.md

@@ -24,6 +24,9 @@ Changes can also be flagged with a GitHub label for tracking purposes. The URL o
 
 ## [2.67.1](https://github.com/ethyca/fides/compare/2.67.0...2.67.1)
 
+### Added
+- Added protection against multiple FidesJS script loading on the same page with configurable override option [#6416](https://github.com/ethyca/fides/pull/6416)
+
 ### Fixed
 - Fix default tab not being set in the integration detail page for Manual Tasks integrations [#6417](https://github.com/ethyca/fides/pull/6417)
 

clients/fides-js/docs/interfaces/FidesOptions.md

@@ -346,3 +346,21 @@ Whether to show the modal immediately on page load.
 
 - "immediate" = skips banner and shows the modal immediately on page load
 - "default" = shows the modal when the "manage preferences" link is clicked (default behavior)
+
+***
+
+### fides\_unsupported\_repeated\_script\_loading?
+
+> `optional` **fides\_unsupported\_repeated\_script\_loading**: `"enabled_acknowledge_not_supported"` \| `"disabled"`
+
+Controls handling of unsupported repeated script loading scenarios. When
+FidesJS is loaded multiple times on the same page, this setting determines
+the behavior.
+
+- "enabled_acknowledge_not_supported" = allows repeated loading but acknowledges
+  this is not a supported configuration
+- "disabled" = prevents repeated script loading entirely
+
+See [Troubleshooting](/docs/dev-docs/js/troubleshooting) for more information.
+
+Defaults to `"disabled"`.

clients/fides-js/package.json

@@ -12,16 +12,19 @@
   ],
   "exports": {
     ".": {
+      "module": "./dist/fides.mjs",
       "import": "./dist/fides.mjs",
       "require": "./dist/fides.js",
       "types": "./dist/fides.d.ts"
     },
     "./headless": {
+      "module": "./dist/fides-headless.mjs",
       "import": "./dist/fides-headless.mjs",
       "require": "./dist/fides-headless.js",
       "types": "./dist/fides-headless.d.ts"
     },
     "./tcf": {
+      "module": "./dist/fides-tcf.mjs",
       "import": "./dist/fides-tcf.mjs",
       "require": "./dist/fides-tcf.js",
       "types": "./dist/fides-tcf.d.ts"

clients/fides-js/rollup.config.mjs

@@ -14,7 +14,8 @@ import fs from "fs";
 import jsxRemoveAttributes from "rollup-plugin-jsx-remove-attributes";
 import { importFidesPackageVersion } from "../build-utils.js";
 
-const NAME = "fides";
+const GLOBAL_NAME = "Fides";
+const FILE_NAME = "fides";
 const IS_DEV = process.env.NODE_ENV === "development";
 const IS_TEST = process.env.IS_TEST === "true";
 const GZIP_SIZE_ERROR_KB = 50; // fail build if bundle size exceeds this
@@ -32,6 +33,8 @@ const GZIP_SIZE_HEADLESS_WARN_KB = 20;
 const GZIP_SIZE_GPP_ERROR_KB = 40;
 const GZIP_SIZE_GPP_WARN_KB = 35;
 
+const multipleLoadingMessage = `${GLOBAL_NAME} detected that it was already loaded on this page, aborting execution! See https://www.ethyca.com/docs/dev-docs/js/troubleshooting for more information.`;
+
 const preactAliases = {
   entries: [
     { find: "react", replacement: "preact/compat" },
@@ -117,22 +120,22 @@ const fidesScriptsJSPlugins = ({ name, gzipWarnSizeKb, gzipErrorSizeKb }) => [
 
 const SCRIPTS = [
   {
-    name: NAME,
+    name: FILE_NAME,
     gzipWarnSizeKb: GZIP_SIZE_WARN_KB,
     gzipErrorSizeKb: GZIP_SIZE_ERROR_KB,
   },
   {
-    name: `${NAME}-tcf`,
+    name: `${FILE_NAME}-tcf`,
     gzipWarnSizeKb: GZIP_SIZE_TCF_WARN_KB,
     gzipErrorSizeKb: GZIP_SIZE_TCF_ERROR_KB,
   },
   {
-    name: `${NAME}-headless`,
+    name: `${FILE_NAME}-headless`,
     gzipWarnSizeKb: GZIP_SIZE_HEADLESS_WARN_KB,
     gzipErrorSizeKb: GZIP_SIZE_HEADLESS_ERROR_KB,
   },
   {
-    name: `${NAME}-ext-gpp`,
+    name: `${FILE_NAME}-ext-gpp`,
     gzipWarnSizeKb: GZIP_SIZE_GPP_WARN_KB,
     gzipErrorSizeKb: GZIP_SIZE_GPP_ERROR_KB,
     isExtension: true,
@@ -169,12 +172,16 @@ SCRIPTS.forEach(({ name, gzipErrorSizeKb, gzipWarnSizeKb, isExtension }) => {
       {
         // Intended for browser <script> tag - defines `Fides` global. Also supports UMD loaders.
         file: `dist/${name}.js`,
-        name: isExtension ? undefined : "Fides",
+        name: isExtension ? undefined : GLOBAL_NAME,
         format: isExtension ? "es" : "umd",
         sourcemap: IS_DEV ? "inline" : false,
         amd: {
           define: undefined, // prevent the bundle from registering itself as an AMD module, even if an AMD loader (like RequireJS) is present on the page. This allows FidesJS to use Rollup's `umd` format to support both `iife` and `cjs` modules, but excludes AMD.
         },
+        // Use the "banner" option to prepend a defensive check into the code to guard against loading FidesJS multiple times on the same page
+        banner: isExtension
+          ? undefined
+          : `if(typeof ${GLOBAL_NAME}!=="undefined" && ${GLOBAL_NAME}.options?.fidesUnsupportedRepeatedScriptLoading!=="enabled_acknowledge_not_supported") {throw new Error("${multipleLoadingMessage}");}`,
       },
     ],
     onLog,

clients/fides-js/src/docs/fides-options.ts

@@ -306,4 +306,21 @@ export interface FidesOptions {
    *
    */
   fides_modal_display?: "immediate" | "default";
+
+  /**
+   * Controls handling of unsupported repeated script loading scenarios. When
+   * FidesJS is loaded multiple times on the same page, this setting determines
+   * the behavior.
+   *
+   * - "enabled_acknowledge_not_supported" = allows repeated loading but acknowledges
+   *   this is not a supported configuration
+   * - "disabled" = prevents repeated script loading entirely
+   *
+   * See [Troubleshooting](/docs/dev-docs/js/troubleshooting) for more information.
+   *
+   * Defaults to `"disabled"`.
+   */
+  fides_unsupported_repeated_script_loading?:
+    | "enabled_acknowledge_not_supported"
+    | "disabled";
 }

clients/fides-js/src/fides-ext-gpp.ts

@@ -303,7 +303,11 @@ const initializeGppCmpApi = () => {
   });
 };
 window.addEventListener("FidesInitializing", (event) => {
-  if (event.detail.extraDetails?.gppEnabled) {
+  if (
+    event.detail.extraDetails?.gppEnabled &&
+    typeof window !== "undefined" &&
+    !window.Fides?.initialized
+  ) {
     initializeGppCmpApi();
   }
 });

clients/fides-js/src/lib/consent-constants.ts

@@ -129,6 +129,12 @@ export const FIDES_OVERRIDE_OPTIONS_VALIDATOR_MAP: FidesOverrideValidatorMap[] =
       overrideKey: "fides_modal_display",
       validationRegex: /^(immediate|default)$/,
     },
+    {
+      overrideName: "fidesUnsupportedRepeatedScriptLoading",
+      overrideType: "string",
+      overrideKey: "fides_unsupported_repeated_script_loading",
+      validationRegex: /^(enabled_acknowledge_not_supported|disabled)$/,
+    },
   ];
 
 /**

clients/fides-js/src/lib/consent-types.ts

@@ -185,6 +185,11 @@ export interface FidesInitOptions {
    *
    */
   fidesModalDisplay?: "immediate" | "default";
+
+  // Controls handling of unsupported repeated script loading
+  fidesUnsupportedRepeatedScriptLoading?:
+    | "enabled_acknowledge_not_supported"
+    | "disabled";
 }
 
 /**
@@ -838,6 +843,7 @@ export type FidesInitOptionsOverrides = Pick<
   | "fidesInitializedEventMode"
   | "fidesModalDefaultView"
   | "fidesModalDisplay"
+  | "fidesUnsupportedRepeatedScriptLoading"
 >;
 
 export type FidesExperienceTranslationOverrides = {

clients/fides-js/src/lib/debugger.ts

@@ -3,9 +3,11 @@
  * @param isDebugMode boolean whether or not to enable the debugger
  */
 export const initializeDebugger = (isDebugMode: boolean) => {
-  if (typeof window !== "undefined" && !window.fidesDebugger) {
-    // eslint-disable-next-line no-console
-    window.fidesDebugger = isDebugMode ? console.log : () => {};
+  if (typeof window !== "undefined") {
+    if (!window.fidesDebugger) {
+      // eslint-disable-next-line no-console
+      window.fidesDebugger = isDebugMode ? console.log : () => {};
+    }
   } else {
     // avoid any errors if window is not defined
     (globalThis as any).fidesDebugger = () => {};

clients/privacy-center/app/server-environment.ts

@@ -73,6 +73,7 @@ export type PrivacyCenterClientSettings = Pick<
   | "FIDES_CONSENT_NON_APPLICABLE_FLAG_MODE"
   | "FIDES_CONSENT_FLAG_TYPE"
   | "FIDES_INITIALIZED_EVENT_MODE"
+  | "FIDES_UNSUPPORTED_REPEATED_SCRIPT_LOADING"
 >;
 
 export type Styles = string;
@@ -338,6 +339,8 @@ export const getClientSettings = (): PrivacyCenterClientSettings => {
       settings.FIDES_CONSENT_NON_APPLICABLE_FLAG_MODE,
     FIDES_CONSENT_FLAG_TYPE: settings.FIDES_CONSENT_FLAG_TYPE,
     FIDES_INITIALIZED_EVENT_MODE: settings.FIDES_INITIALIZED_EVENT_MODE,
+    FIDES_UNSUPPORTED_REPEATED_SCRIPT_LOADING:
+      settings.FIDES_UNSUPPORTED_REPEATED_SCRIPT_LOADING,
   };
 
   return clientSettings;