[BREAKING] Disable overrides via query string by default

.changeset/purple-hornets-kneel.md

@@ -0,0 +1,5 @@
+---
+"import-map-overrides": major
+---
+
+Disable query parameter overrides, by default. Add support for `allow-query-param-override` attribute to `<meta>` element, to opt-in to query parameter overrides.

docs/configuration.md

@@ -161,3 +161,17 @@ To configure domains, add a `<meta name="import-map-overrides-domains">` element
   content="allowlist:*.example.com,example-*.com"
 />
 ```
+
+## Query Parameter Overrides
+
+import-map-overrides has an opt-in feature that allows users to set overrides via the `imo` query parameter on the current page. When enabled, the `imo` query parameter value should be a URL-encoded import map. For example, an override map of `{"imports": {"module1": "/module1.js"}}` would be encoded via https://example.com?imo=%7B%22imports%22%3A%7B%22module1%22%3A%22%2Fmodule1.js%22%7D%7D
+
+To enable query parameter overrides, add the `allow-query-param-override` attribute to the `<meta name="importmap-type">` element:
+
+```html
+<meta
+  name="importmap-type"
+  content="systemjs-importmap"
+  allow-query-param-override
+/>
+```

docs/security.md

@@ -8,6 +8,7 @@ However, there are things you can do to protect your users from self XSS. Consid
 
 1. (**Most Important and Highly Recommended**) Configure your server to set a [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) HTTP header for your HTML file. In it, consider safelisting the domains that you trust. Doing so is important to protect your users from XSS and other attacks.
 1. Consider removing import-map-overrides from your production application's HTML file, or [configuring a domain list](/docs/configuration.md#domain-list) that disables import map overrides in production. If you properly set a Content-Security-Policy header, this provides no extra security. However, if you have not configured CSP, this will at least make it a bit harder for the user to self XSS. My recommendation is to do CSP instead of this whenever possible.
+1. Consider disabling query parameter overrides by removing the `allow-query-param-override` attribute on the `<meta>` element for import-map-overrides. See [query parameter overrides documentation](/docs/configuration.md#query-parameter-overrides).
 
 ## Node
 

src/api/js-api.imo.test.js

@@ -206,6 +206,56 @@ describe("window.importMapOverrides", () => {
         scopes: {},
       });
     });
+
+    describe("with overrides via query string", () => {
+      const metaElement = document.createElement("meta");
+      const url = new URL(window.location.href);
+
+      beforeEach(() => {
+        url.searchParams.set(
+          "imo",
+          JSON.stringify({
+            imports: { package3: "https://cdn.skypack.dev/package33" },
+          })
+        );
+        window.history.replaceState({}, "", url);
+        document.body.appendChild(metaElement);
+      });
+
+      afterEach(() => {
+        url.searchParams.delete("imo");
+        window.history.replaceState({}, "", url);
+        document.body.removeChild(metaElement);
+      });
+
+      it("should return an override map", async () => {
+        metaElement.setAttribute("name", "importmap-type");
+        metaElement.setAttribute("content", "importmap");
+        metaElement.setAttribute("allow-query-param-override", "");
+
+        await setDocumentAndLoadScript();
+
+        const map = await window.importMapOverrides.getOverrideMap();
+
+        expect(map).toEqual({
+          imports: { package3: "https://cdn.skypack.dev/package33" },
+          scopes: {},
+        });
+      });
+
+      it("disabled by default", async () => {
+        metaElement.removeAttribute("allow-query-param-override");
+
+        await setDocumentAndLoadScript();
+
+        const map = await window.importMapOverrides.getOverrideMap();
+
+        expect(map).toEqual({
+          imports: {},
+          scopes: {},
+        });
+      });
+    });
   });
 
   describe("Add/Remove/Enable/Disable overrides", () => {

src/api/js-api.js

@@ -70,6 +70,9 @@ function init() {
   const serverOnly = importMapMetaElement
     ? importMapMetaElement.hasAttribute("server-only")
     : false;
+  const allowQueryParamOverride = importMapMetaElement
+    ? importMapMetaElement.hasAttribute("allow-query-param-override")
+    : false;
 
   let defaultMapPromise;
 
@@ -109,25 +112,27 @@ function init() {
       }
 
       // get from url if query param exist
-      const queryParam = getParameterByName(
-        queryParamOverridesName,
-        window.location != window.parent.location
-          ? document.referrer
-          : window.location.href
-      );
+      if (allowQueryParamOverride) {
+        const queryParam = getParameterByName(
+          queryParamOverridesName,
+          window.location != window.parent.location
+            ? document.referrer
+            : window.location.href
+        );
 
-      if (queryParam) {
-        let queryParamImportMap;
-        try {
-          queryParamImportMap = JSON.parse(queryParam);
-        } catch (e) {
-          throw Error(
-            `Invalid importMap query param - text content must be json`
-          );
+        if (queryParam) {
+          let queryParamImportMap;
+          try {
+            queryParamImportMap = JSON.parse(queryParam);
+          } catch (e) {
+            throw Error(
+              `Invalid importMap query param - text content must be json`
+            );
+          }
+          Object.keys(queryParamImportMap.imports).forEach((moduleName) => {
+            setOverride(moduleName, queryParamImportMap.imports[moduleName]);
+          });
         }
-        Object.keys(queryParamImportMap.imports).forEach((moduleName) => {
-          setOverride(moduleName, queryParamImportMap.imports[moduleName]);
-        });
       }
 
       return overrides;

test/url.html

@@ -6,7 +6,11 @@
     <title>Import Map Overrides test</title>
     <meta name="viewport" content="width=device-width, initial-scale=1" />
 
-    <meta name="importmap-type" content="systemjs-importmap" />
+    <meta
+      name="importmap-type"
+      content="systemjs-importmap"
+      allow-query-param-override
+    />
 
     <script src="/import-map-overrides.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/systemjs/dist/system.js"></script>