@jsenv/core 41.5.35 → 41.5.38

package/src/dev/dev_server_plugins/dev_server_plugin_https_trust.js

@@ -0,0 +1,93 @@
+/*
+ * Lets another device (a phone) trust the root certificate that signs the dev
+ * server certificate, so it opens the dev server over https without a warning.
+ *
+ * Everything under HTTPS_TRUST_PATHNAME is served over plain http too (see the
+ * redirectHttpToHttps passed by startDevServer): it is the one page that must
+ * load before the certificate is trusted, over https it would show the very
+ * warning it exists to remove. Only the certificate is served, never its key.
+ *
+ * The page is sent as written, not cooked like the project pages: it needs
+ * nothing cooking injects, and a project plugin rewriting html must not be able
+ * to break the one page reached before trust.
+ *
+ * What it means for the device, and why the fingerprint must be compared with
+ * the terminal: docs/users/b_dev/b_dev.md, "Trusting it on a phone".
+ */
+
+import { readFileSync } from "node:fs";
+
+export const HTTPS_TRUST_PATHNAME = "/.internal/https/";
+
+const httpsTrustPageFileUrl = new URL(
+  "./client/https_trust.html",
+  import.meta.url,
+);
+
+// rootCertificate is a node:crypto X509Certificate
+export const devServerPluginHttpsTrust = ({ rootCertificate }) => {
+  const commonName = readCommonName(rootCertificate.subject);
+  const rootCertificateInfo = {
+    fingerprint256: rootCertificate.fingerprint256,
+    commonName,
+  };
+  // "https local root certificate" -> "https_local_root_certificate.crt"
+  const rootCertificateFilename = `${commonName.replace(/[^\w.-]+/g, "_")}.crt`;
+
+  return {
+    name: "jsenv:https_trust",
+    routes: [
+      {
+        endpoint: `GET ${HTTPS_TRUST_PATHNAME}`,
+        description:
+          "Page to trust the dev server https on another device (a phone). Served over http.",
+        declarationSource: import.meta.url,
+        fetch: () => {
+          return new Response(readFileSync(httpsTrustPageFileUrl), {
+            headers: { "content-type": "text/html" },
+          });
+        },
+      },
+      {
+        endpoint: `GET ${HTTPS_TRUST_PATHNAME}root.crt`,
+        description: "The root certificate signing the dev server certificate.",
+        declarationSource: import.meta.url,
+        fetch: () => {
+          return new Response(rootCertificate.toString(), {
+            headers: {
+              "content-type": "application/x-x509-ca-cert",
+              "content-disposition": `attachment; filename="${rootCertificateFilename}"`,
+            },
+          });
+        },
+      },
+      {
+        endpoint: `GET ${HTTPS_TRUST_PATHNAME}root.json`,
+        description: "Fingerprint and name of the root certificate.",
+        declarationSource: import.meta.url,
+        fetch: () => {
+          return Response.json(rootCertificateInfo);
+        },
+      },
+      {
+        endpoint: `GET ${HTTPS_TRUST_PATHNAME}ping`,
+        description:
+          "Fetched over https by the page: it fails as long as the device does not trust the certificate.",
+        declarationSource: import.meta.url,
+        fetch: () => {
+          return new Response(null, { status: 204 });
+        },
+      },
+    ],
+  };
+};
+
+// "CN=https local root certificate\nO=..." -> "https local root certificate"
+const readCommonName = (subject) => {
+  for (const line of subject.split("\n")) {
+    if (line.startsWith("CN=")) {
+      return line.slice("CN=".length);
+    }
+  }
+  return subject;
+};

package/src/dev/start_dev_server.js

@@ -17,6 +17,7 @@ import {
   browserDefaultRuntimeCompat,
   inferRuntimeCompatFromClosestPackage,
 } from "@jsenv/runtime-compat";
+import { X509Certificate } from "node:crypto";
 import { existsSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 
@@ -31,6 +32,10 @@ import { jsenvPluginPatches } from "../plugins/patches/jsenv_plugin_patches.js";
 import { getCorePlugins } from "../plugins/plugins.js";
 import { jsenvPluginServerEvents } from "../plugins/server_events/jsenv_plugin_server_events.js";
 import { devServerPluginChromeDevToolsJson } from "./dev_server_plugins/dev_server_plugin_chrome_devtools_json.js";
+import {
+  HTTPS_TRUST_PATHNAME,
+  devServerPluginHttpsTrust,
+} from "./dev_server_plugins/dev_server_plugin_https_trust.js";
 import { devServerPluginInjectServerResponseHeader } from "./dev_server_plugins/dev_server_plugin_inject_server_response_header.js";
 import { devServerPluginOmegaErrorHandler } from "./dev_server_plugins/dev_server_plugin_omega_error_handler.js";
 import { devServerPluginServeSourceFiles } from "./dev_server_plugins/dev_server_plugin_serve_source_files.js";
@@ -51,7 +56,7 @@ const EXECUTED_BY_TEST_PLAN = process.argv.includes("--jsenv-test");
  * @param {number} [params.port=3456] - Port to listen on (0 = a free port).
  * @param {string} [params.hostname] - Hostname to bind to.
  * @param {boolean} [params.acceptAnyIp=false] - Also accept connections on the machine's IPs (so other devices on the network — a phone — can reach the server). Off by default: exposing the dev server beyond localhost is an explicit choice, not something a dev tool decides.
- * @param {boolean|object} [params.https=false] - HTTPS as `{ certificate, privateKey }`.
+ * @param {object} [params.https] - HTTPS as `{ certificate, privateKey }` (PEM strings). With `rootCertificate` (the PEM of the authority that signed `certificate`) and `acceptAnyIp`, the dev server also serves `http://<ip>:<port>/.internal/https/`, a page to trust that authority on a phone (see docs/users/b_dev/b_dev.md, "Trusting it on a phone").
  * @param {boolean} [params.http2=false] - HTTP/2 (requires https).
  * @param {Array} [params.plugins=[]] - jsenv plugins (transformUrlContent, serverRoutes, serverEvents, effect, …).
  * @param {Array} [params.serverPlugins=[]] - `@jsenv/server`-level plugins.
@@ -184,6 +189,7 @@ export const startDevServer = async ({
       );
     }
   }
+  let httpsTrust = null;
   // params normalization
   {
     if (runtimeCompat === undefined) {
@@ -198,6 +204,16 @@ export const startDevServer = async ({
     if (clientAutoreload === false) {
       clientAutoreload = { enabled: false };
     }
+    if (https) {
+      const { certificate, privateKey, rootCertificate } = https;
+      https = { certificate, privateKey };
+      // a localhost-only server has no phone to serve
+      if (rootCertificate && acceptAnyIp) {
+        httpsTrust = {
+          rootCertificate: new X509Certificate(rootCertificate),
+        };
+      }
+    }
   }
 
   const logger = createLogger({ logLevel });
@@ -355,6 +371,7 @@ export const startDevServer = async ({
     }),
     // chrome devtools
     devServerPluginChromeDevToolsJson({ sourceDirectoryUrl }),
+    ...(httpsTrust ? [devServerPluginHttpsTrust(httpsTrust)] : []),
     ...serverPlugins,
     devServerPluginServeSourceFiles({
       packageDirectory,
@@ -393,6 +410,12 @@ export const startDevServer = async ({
     startLog: false,
 
     https,
+    ...(httpsTrust
+      ? {
+          redirectHttpToHttps: ({ resource }) =>
+            !resource.startsWith(HTTPS_TRUST_PATHNAME),
+        }
+      : {}),
     http2,
     acceptAnyIp,
     hostname,
@@ -418,6 +441,17 @@ export const startDevServer = async ({
   logger.info(``);
   Object.keys(server.origins).forEach((key) => {
     logger.info(`- ${server.origins[key]}`);
+    if (httpsTrust && key === "externalip") {
+      const externalHostname = new URL(server.origins.externalip).hostname;
+      const httpsTrustPageUrl = new URL(
+        HTTPS_TRUST_PATHNAME,
+        `http://${externalHostname}:${server.port}`,
+      );
+      logger.info(`  trust it on a phone: ${httpsTrustPageUrl}`);
+      logger.info(
+        `  root certificate SHA-256: ${httpsTrust.rootCertificate.fingerprint256}`,
+      );
+    }
   });
   logger.info(``);
   return {

package/src/kitchen/errors.js

@@ -140,7 +140,7 @@ ${reason}`,
       return createFailedToFetchUrlContentError({
         code: "NOT_FOUND",
         reason: "no entry on filesystem",
-        ...detailsFromInjectionsOnOwner(urlInfo.firstReference),
+        ...detailsFromHtmlUrlNotFound(urlInfo.firstReference),
       });
     }
   }
@@ -400,6 +400,31 @@ const detailsFromInjectionsOnOwner = (reference) => {
   };
 };
 
+// An url of an html attribute leading to no file may be meant for a server rather
+// than for jsenv: a route of a backend, which "jsenv-ignore" leaves alone. Only the
+// build is concerned: in dev the browser requests the url whatever jsenv does with it.
+const detailsFromHtmlUrlNotFound = (reference) => {
+  const detailsFromInjections = detailsFromInjectionsOnOwner(reference);
+  if (detailsFromInjections.suggestion) {
+    return detailsFromInjections;
+  }
+  if (!reference) {
+    return {};
+  }
+  const ownerUrlInfo = reference.ownerUrlInfo;
+  if (ownerUrlInfo.type !== "html" || !ownerUrlInfo.context.build) {
+    return {};
+  }
+  const { node, attributeName } = reference.astInfo || {};
+  if (!node || !attributeName) {
+    return {};
+  }
+  return {
+    suggestion: `when "${reference.specifier}" is answered by a server rather than a file, add "jsenv-ignore" so the build leaves that url alone:
+<${node.nodeName} jsenv-ignore ${attributeName}="${reference.specifier}" />`,
+  };
+};
+
 const detailsFromPluginController = (jsenvPluginsController) => {
   const currentPlugin = jsenvPluginsController.getCurrentPlugin();
   if (!currentPlugin) {