@jsenv/https-local 3.6.2 → 4.0.0

package/README.md

@@ -19,6 +19,7 @@ Generate locally trusted HTTPS certificates for local development.
   - [Certificate Expiration](#certificate-expiration)
   - [JavaScript API](#javascript-api)
     - [requestCertificate](#requestcertificate)
+    - [trustCertificateAuthority](#trustcertificateauthority)
     - [verifyHostsFile](#verifyhostsfile)
       - [Auto Update Hosts](#auto-update-hosts)
     - [installCertificateAuthority](#installcertificateauthority)
@@ -176,6 +177,40 @@ const server = createServer(
 
 [`init`](#init) (or `installCertificateAuthority`) must be called once before using this function.
 
+It also makes the current process trust the certificate authority, as described in [trustCertificateAuthority](#trustcertificateauthority). Pass `trustAuthority: false` to keep the CA certificates of the process untouched:
+
+```js
+const { certificate, privateKey } = requestCertificate({
+  trustAuthority: false,
+});
+```
+
+### trustCertificateAuthority
+
+The root certificate authority is installed in the system keychain, which browsers read — but node does not: it uses its own CA list. A node process requesting a local HTTPS server signed by the authority therefore fails with `unable to verify the first certificate`, even on the machine that created the authority.
+
+`trustCertificateAuthority` adds the authority root certificate to the CA list of the current process:
+
+```js
+import { trustCertificateAuthority } from "@jsenv/https-local";
+
+trustCertificateAuthority();
+
+const response = await fetch("https://localhost:4000");
+```
+
+Only the authority root certificate is added; the CA certificates node trusts by default are preserved and the rest of the system keychain is left out. Calling it twice does nothing the second time.
+
+[requestCertificate](#requestcertificate) does this on its own, so this function is for processes acting only as a client — an integration test requesting a local HTTPS server started elsewhere, for instance.
+
+[`init`](#init) (or `installCertificateAuthority`) must be called once before using this function.
+
+> **Note:** it relies on [`tls.setDefaultCACertificates`](https://nodejs.org/api/tls.html#tlssetdefaultcacertificatescerts), available starting from node 22.19.0 and 24.5.0. On older versions the call logs a warning and does nothing; the alternative there is the `NODE_EXTRA_CA_CERTS` environment variable, pointing to the `rootCertificateFilePath` returned by [requestCertificate](#requestcertificate). It must be set before the process starts, which is why it does not replace this function:
+>
+> ```console
+> NODE_EXTRA_CA_CERTS="~/Library/Application Support/https_local/https_local_root_certificate.crt" node file.mjs
+> ```
+
 ### verifyHostsFile
 
 Verifies that IP mappings important for your local server are present in the hosts file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/https-local",
-  "version": "3.6.2",
+  "version": "4.0.0",
   "type": "module",
   "description": "A programmatic way to generate locally trusted certificates",
   "repository": {
@@ -50,7 +50,7 @@
     "@jsenv/https-local": "./",
     "@jsenv/performance-impact": "../performance-impact",
     "@jsenv/test": "../../related/test",
-    "playwright": "1.59.1"
+    "playwright": "1.61.1"
   },
   "publishConfig": {
     "access": "public"

package/src/certificate_request.js

@@ -3,6 +3,7 @@ import { UNICODE, createDetailedMessage, createLogger } from "@jsenv/humanize";
 import { readFileSync } from "node:fs";
 import { getAuthorityFileInfos } from "./internal/authority_file_infos.js";
 import { requestCertificateFromAuthority } from "./internal/certificate_generator.js";
+import { addCertificateToProcessCACertificates } from "./internal/process_ca_certificates.js";
 import { forge } from "./internal/forge.js";
 import { formatDuration } from "./internal/validity_formatting.js";
 import {
@@ -17,6 +18,7 @@ export const requestCertificate = ({
   altNames = ["localhost"],
   commonName = "https local server certificate",
   validityDurationInMs = createValidityDurationOfXDays(396),
+  trustAuthority = true,
 } = {}) => {
   if (typeof validityDurationInMs !== "number") {
     throw new TypeError(
@@ -105,6 +107,14 @@ npx @jsenv/https-local init`,
     )}`,
   );
 
+  if (trustAuthority) {
+    addCertificateToProcessCACertificates({
+      logger,
+      certificate: rootCertificate,
+      certificateFilePath: rootCertificateFileInfo.path,
+    });
+  }
+
   return {
     certificate: serverCertificate,
     privateKey: serverCertificatePrivateKey,

package/src/internal/process_ca_certificates.js

@@ -0,0 +1,63 @@
+/*
+ * Browsers trust the authority root certificate because it is installed in the
+ * system keychain; node ignores that keychain and uses its own CA list, so a
+ * node process fetching a local https server signed by the authority fails with
+ * "unable to verify the first certificate".
+ *
+ * Only the authority root certificate is added: reading the whole system
+ * keychain (tls.getCACertificates("system")) would also pull in whatever a
+ * corporate proxy installed there.
+ */
+
+import { UNICODE, createDetailedMessage } from "@jsenv/humanize";
+import tls from "node:tls";
+
+export const addCertificateToProcessCACertificates = ({
+  logger,
+  certificate,
+  certificateFilePath,
+}) => {
+  // named imports would make the whole package fail to link on node versions
+  // where these functions do not exist yet
+  const { getCACertificates, setDefaultCACertificates } = tls;
+  if (!getCACertificates || !setDefaultCACertificates) {
+    logger.warn(
+      createDetailedMessage(
+        `Cannot trust certificate authority: "tls.setDefaultCACertificates" is not available in node ${process.version} (available starting from node 22.19.0 and 24.5.0).`,
+        {
+          "suggested workaround": `start the process with NODE_EXTRA_CA_CERTS, it must be set before the process starts`,
+          "suggested command to run": `NODE_EXTRA_CA_CERTS="${certificateFilePath}" node file.mjs`,
+        },
+      ),
+    );
+    return false;
+  }
+
+  const defaultCertificates = getCACertificates("default");
+  const alreadyTrusted = defaultCertificates.some((defaultCertificate) => {
+    return isSameCertificate(defaultCertificate, certificate);
+  });
+  if (alreadyTrusted) {
+    logger.debug(
+      `${UNICODE.OK} authority root certificate already trusted by this process`,
+    );
+    return false;
+  }
+  setDefaultCACertificates([...defaultCertificates, certificate]);
+  logger.debug(
+    `${UNICODE.OK} authority root certificate trusted by this process`,
+  );
+  return true;
+};
+
+const isSameCertificate = (a, b) => {
+  return toCertificateBody(a) === toCertificateBody(b);
+};
+
+// PEM files describing the very same certificate differ by their line wrapping
+// and trailing newlines
+const toCertificateBody = (certificate) => {
+  return certificate
+    .replace(/-----(BEGIN|END) CERTIFICATE-----/g, "")
+    .replace(/\s/g, "");
+};

package/src/main.js

@@ -14,6 +14,7 @@ export {
 } from "./certificate_authority.js";
 export { requestCertificate } from "./certificate_request.js";
 export { verifyHostsFile } from "./hosts_file_verif.js";
+export { trustCertificateAuthority } from "./trust_certificate_authority.js";
 export {
   createValidityDurationOfXDays,
   createValidityDurationOfXYears,

package/src/trust_certificate_authority.js

@@ -0,0 +1,28 @@
+import { createLogger } from "@jsenv/humanize";
+import { readFileSync } from "node:fs";
+import { getAuthorityFileInfos } from "./internal/authority_file_infos.js";
+import { addCertificateToProcessCACertificates } from "./internal/process_ca_certificates.js";
+
+export const trustCertificateAuthority = ({
+  logLevel,
+  logger = createLogger({ logLevel }), // to be able to catch logs during unit tests
+} = {}) => {
+  const { rootCertificateFileInfo } = getAuthorityFileInfos();
+  if (!rootCertificateFileInfo.exists) {
+    throw new Error(
+      `Certificate authority not found, "installCertificateAuthority" must be called before "trustCertificateAuthority".
+--- Suggested command to run ---
+npx @jsenv/https-local init`,
+    );
+  }
+
+  const rootCertificate = readFileSync(
+    new URL(rootCertificateFileInfo.url),
+    "utf8",
+  );
+  return addCertificateToProcessCACertificates({
+    logger,
+    certificate: rootCertificate,
+    certificateFilePath: rootCertificateFileInfo.path,
+  });
+};