@jsenv/https-local 4.0.1 → 4.0.3

package/README.md

@@ -5,6 +5,7 @@ Generate locally trusted HTTPS certificates for local development.
 🔒 Certificates trusted by your operating system and browsers  
 🌐 Perfect for local HTTPS development  
 🖥️ Works on macOS, Linux, and Windows  
+📱 Trusted by iOS simulators too  
 ⚡ Simple CLI and JavaScript API
 
 ## Table of Contents
@@ -14,6 +15,7 @@ Generate locally trusted HTTPS certificates for local development.
   - [Quick Start](#quick-start)
   - [CLI](#cli)
     - [init](#init)
+      - [iOS simulator](#ios-simulator)
     - [generate](#generate)
     - [cleanup](#cleanup)
   - [Certificate Expiration](#certificate-expiration)
@@ -59,7 +61,7 @@ const server = createServer(
 npx @jsenv/https-local init
 ```
 
-Installs a root certificate authority, trusts it in your OS and browsers, and ensures `localhost` is mapped to `127.0.0.1` in your hosts file. Safe to re-run — subsequent runs report the current status.
+Installs a root certificate authority, trusts it in your OS, your browsers and the [iOS simulators](#ios-simulator) currently booted, and ensures `localhost` is mapped to `127.0.0.1` in your hosts file. Safe to re-run — subsequent runs report the current status.
 
 <details>
   <summary>First execution (macOS)</summary>
@@ -76,6 +78,11 @@ Password:
 ✔ certificate added to mac keychain
 Adding certificate to firefox...
 ✔ certificate added to Firefox
+Check if certificate is in iOS simulator "iPhone 17"...
+ℹ certificate not found in iOS simulator "iPhone 17"
+Adding certificate to iOS simulator "iPhone 17"...
+❯ xcrun simctl keychain 3353AABB-2A54-49FA-B69D-AA4454350523 add-root-cert "/Users/you/https_local/https_local_root_certificate.crt"
+✔ certificate added to iOS simulator "iPhone 17"
 Check hosts file content...
 ✔ all ip mappings found in hosts file
 ```
@@ -97,12 +104,26 @@ Check if certificate is in mac keychain...
 ✔ certificate found in mac keychain
 Check if certificate is in Firefox...
 ✔ certificate found in Firefox
+Check if certificate is in iOS simulator "iPhone 17"...
+✔ certificate found in iOS simulator "iPhone 17"
 Check hosts file content...
 ✔ all ip mappings found in hosts file
 ```
 
 </details>
 
+#### iOS simulator
+
+An iOS simulator has a trust store of its own: a certificate trusted by the mac keychain is still refused by Safari inside the simulator, and a `fetch` towards another origin fails with `TypeError: Load failed` — WebKit only offers the "Visit website" exception for the page itself, not for cross-origin requests.
+
+`init` adds the root certificate to every simulator booted at the time it runs, with full trust: there is nothing to enable in Settings › General › About › Certificate Trust Settings afterwards (that toggle is for certificates installed from a profile). Boot the simulator, then run `init` again; or add it by hand, `booted` standing for every running simulator:
+
+```console
+xcrun simctl keychain booted add-root-cert "$HOME/Library/Application Support/https_local/https_local_root_certificate.crt"
+```
+
+The certificate stays in the simulator across reboots. It cannot be removed on its own, so `cleanup` leaves it there; `xcrun simctl keychain <udid> reset` wipes the whole simulator keychain.
+
 ### generate
 
 ```console

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/https-local",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "type": "module",
   "description": "A programmatic way to generate locally trusted certificates",
   "repository": {
@@ -37,7 +37,7 @@
     "test:start-node-server": "node ./scripts/certificate/start_node_server.mjs"
   },
   "dependencies": {
-    "@jsenv/filesystem": "4.15.18",
+    "@jsenv/filesystem": "4.15.19",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/urls": "2.9.10",
     "command-exists": "1.2.9",

package/src/https_local_cli.mjs

@@ -37,7 +37,8 @@ if (values.help || positionals.length === 0) {
 Usage:
 
 npx @jsenv/https-local init
-  Install root certificate, trust it and ensure localhost is mapped to 127.0.0.1
+  Install root certificate, trust it (os, browsers, booted iOS simulators)
+  and ensure localhost is mapped to 127.0.0.1
 
 npx @jsenv/https-local cleanup
   Uninstall root certificate and remove its trust from os and browsers
@@ -52,7 +53,7 @@ Advanced commands:
 
 npx @jsenv/https-local install --trust
   Install root certificate on the filesystem
-  - trust: Try to add root certificate to os and browser trusted stores
+  - trust: Try to add root certificate to os, browser and booted iOS simulator trusted stores
 
 npx @jsenv/https-local uninstall
   Uninstall root certificate from the filesystem

package/src/internal/mac/ios_simulator.js

@@ -0,0 +1,287 @@
+/*
+ * iOS simulators have a trust store of their own: a certificate trusted by the
+ * mac keychain is still refused by Safari (and by fetch) inside a simulator.
+ * Xcode's `simctl keychain <device> add-root-cert` writes the certificate into
+ * the trust store of a booted simulator with an empty trust settings array,
+ * which Apple reads as "trust as root for every policy" — no toggle in
+ * Settings › General › About › Certificate Trust Settings afterwards.
+ *
+ * simctl cannot list or remove trusted roots ("reset" wipes the whole keychain),
+ * so membership is read from the simulator's trust store database, where
+ * certificates are keyed by their fingerprint, with the sqlite3 binary
+ * shipped with macOS.
+ */
+
+import { createDetailedMessage, UNICODE } from "@jsenv/humanize";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { commandExists } from "../command.js";
+import { exec } from "../exec.js";
+import { forge } from "../forge.js";
+import {
+  VERB_ADD_TRUST,
+  VERB_CHECK_TRUST,
+  VERB_ENSURE_TRUST,
+  VERB_REMOVE_TRUST,
+} from "../trust_query.js";
+
+const REASON_SIMCTL_NOT_AVAILABLE = "xcrun simctl not available";
+const REASON_NO_BOOTED_SIMULATOR = "no booted iOS simulator";
+const REASON_NEW_AND_TRY_TO_TRUST_DISABLED =
+  "certificate is new and tryToTrust is disabled";
+const REASON_NOT_IN_SIMULATOR = "certificate not found in iOS simulator";
+const REASON_IN_SIMULATOR = "certificate found in iOS simulator";
+const REASON_TRUST_STORE_UNREADABLE =
+  "cannot read the iOS simulator trust store";
+const REASON_ADD_TO_SIMULATOR_COMMAND_FAILED =
+  "command to add certificate in iOS simulator failed";
+const REASON_ADD_TO_SIMULATOR_COMMAND_COMPLETED =
+  "command to add certificate in iOS simulator completed";
+const REASON_CANNOT_REMOVE_FROM_SIMULATOR =
+  "certificate cannot be removed from iOS simulator";
+
+export const executeTrustQueryOnIosSimulator = async ({
+  logger,
+  certificateFileUrl,
+  certificateIsNew,
+  certificate,
+  verb,
+}) => {
+  const certificateFilePath = fileURLToPath(certificateFileUrl);
+  const { simctlAvailable, bootedSimulators } = await listBootedIosSimulators({
+    logger,
+  });
+  if (!simctlAvailable) {
+    return {
+      status: "other",
+      reason: REASON_SIMCTL_NOT_AVAILABLE,
+    };
+  }
+  if (bootedSimulators.length === 0) {
+    if (verb === VERB_ADD_TRUST || verb === VERB_ENSURE_TRUST) {
+      logger.info(
+        `${UNICODE.INFO} no booted iOS simulator, to trust the certificate in one boot it and re-run, or run:
+${UNICODE.COMMAND} xcrun simctl keychain booted add-root-cert "${certificateFilePath}"`,
+      );
+    } else {
+      logger.debug(`${UNICODE.INFO} no booted iOS simulator`);
+    }
+    return {
+      status: "other",
+      reason: REASON_NO_BOOTED_SIMULATOR,
+    };
+  }
+  if (verb === VERB_CHECK_TRUST && certificateIsNew) {
+    logger.info(`${UNICODE.INFO} You should add certificate to iOS simulator`);
+    return {
+      status: "not_trusted",
+      reason: REASON_NEW_AND_TRY_TO_TRUST_DISABLED,
+    };
+  }
+
+  const fingerprints = getCertificateFingerprints(certificate);
+  const results = [];
+  for (const simulator of bootedSimulators) {
+    results.push(
+      await executeTrustQueryOnOneSimulator({
+        logger,
+        simulator,
+        certificateFilePath,
+        fingerprints,
+        verb,
+      }),
+    );
+  }
+  // one entry stands for all booted simulators: the first one not trusted, if any
+  const notTrustedResult = results.find(
+    (result) => result.status !== "trusted",
+  );
+  return notTrustedResult || results[0];
+};
+
+/**
+ * Booted simulators as reported by simctl.
+ * simctlAvailable is false when Xcode is not installed: /usr/bin/xcrun then
+ * exists but has no simctl to run.
+ */
+export const listBootedIosSimulators = async ({ logger } = {}) => {
+  const xcrunExists = await commandExists("xcrun");
+  if (!xcrunExists) {
+    return { simctlAvailable: false, bootedSimulators: [] };
+  }
+  const listCommand = `xcrun simctl list devices booted -j`;
+  if (logger) {
+    logger.debug(`${UNICODE.COMMAND} ${listCommand}`);
+  }
+  let listCommandOutput;
+  try {
+    listCommandOutput = await exec(listCommand);
+  } catch {
+    return { simctlAvailable: false, bootedSimulators: [] };
+  }
+  const { devices } = JSON.parse(listCommandOutput);
+  const bootedSimulators = [];
+  for (const runtime of Object.keys(devices)) {
+    for (const device of devices[runtime]) {
+      bootedSimulators.push({
+        udid: device.udid,
+        name: device.name,
+        dataPath: device.dataPath,
+      });
+    }
+  }
+  return { simctlAvailable: true, bootedSimulators };
+};
+
+const executeTrustQueryOnOneSimulator = async ({
+  logger,
+  simulator,
+  certificateFilePath,
+  fingerprints,
+  verb,
+}) => {
+  const simulatorLabel = `iOS simulator "${simulator.name}"`;
+
+  logger.info(`Check if certificate is in ${simulatorLabel}...`);
+  const found = await findCertificateInSimulatorTrustStore({
+    logger,
+    simulator,
+    fingerprints,
+  });
+
+  const addCert = async () => {
+    const addRootCertCommand = `xcrun simctl keychain ${simulator.udid} add-root-cert "${certificateFilePath}"`;
+    logger.info(`Adding certificate to ${simulatorLabel}...`);
+    logger.info(`${UNICODE.COMMAND} ${addRootCertCommand}`);
+    try {
+      await exec(addRootCertCommand);
+      logger.info(`${UNICODE.OK} certificate added to ${simulatorLabel}`);
+      return {
+        status: "trusted",
+        reason: REASON_ADD_TO_SIMULATOR_COMMAND_COMPLETED,
+      };
+    } catch (e) {
+      logger.error(
+        createDetailedMessage(
+          `${UNICODE.FAILURE} failed to add certificate to ${simulatorLabel}`,
+          {
+            "error stack": e.stack,
+            "certificate file": certificateFilePath,
+          },
+        ),
+      );
+      return {
+        status: "not_trusted",
+        reason: REASON_ADD_TO_SIMULATOR_COMMAND_FAILED,
+      };
+    }
+  };
+
+  if (found === null) {
+    logger.info(
+      `${UNICODE.INFO} cannot check if certificate is in ${simulatorLabel}`,
+    );
+    if (verb === VERB_ADD_TRUST || verb === VERB_ENSURE_TRUST) {
+      // add-root-cert replaces an existing entry, so adding blindly is safe
+      return addCert();
+    }
+    return {
+      status: "unknown",
+      reason: REASON_TRUST_STORE_UNREADABLE,
+    };
+  }
+
+  if (!found) {
+    logger.info(`${UNICODE.INFO} certificate not found in ${simulatorLabel}`);
+    if (verb === VERB_CHECK_TRUST || verb === VERB_REMOVE_TRUST) {
+      return {
+        status: "not_trusted",
+        reason: REASON_NOT_IN_SIMULATOR,
+      };
+    }
+    return addCert();
+  }
+
+  logger.info(`${UNICODE.OK} certificate found in ${simulatorLabel}`);
+  if (verb === VERB_REMOVE_TRUST) {
+    logger.info(
+      `${UNICODE.INFO} certificate stays in ${simulatorLabel}: simctl cannot remove a single root certificate, "xcrun simctl keychain ${simulator.udid} reset" wipes the whole simulator keychain`,
+    );
+    return {
+      status: "trusted",
+      reason: REASON_CANNOT_REMOVE_FROM_SIMULATOR,
+    };
+  }
+  return {
+    status: "trusted",
+    reason: REASON_IN_SIMULATOR,
+  };
+};
+
+// Relative to the simulator data directory. The first one is where trustd keeps
+// the store on current runtimes (checked on iOS 26), the second is the location
+// of older runtimes. The table keys certificates by sha256 on current runtimes,
+// by sha1 on older ones.
+const TRUST_STORE_RELATIVE_PATHS = [
+  "private/var/protected/trustd/private/TrustStore.sqlite3",
+  "Library/Keychains/TrustStore.sqlite3",
+];
+
+/**
+ * true/false when the trust store answers, null when it cannot be read
+ * (sqlite3 missing, unexpected layout).
+ * A simulator where no root certificate was ever added has no store file,
+ * which means "not found".
+ */
+const findCertificateInSimulatorTrustStore = async ({
+  logger,
+  simulator,
+  fingerprints,
+}) => {
+  const trustStorePath = TRUST_STORE_RELATIVE_PATHS.map(
+    (relativePath) => `${simulator.dataPath}/${relativePath}`,
+  ).find((path) => existsSync(path));
+  if (!trustStorePath) {
+    return false;
+  }
+  const sqlite3Exists = await commandExists("sqlite3");
+  if (!sqlite3Exists) {
+    logger.debug(`${UNICODE.INFO} sqlite3 not found`);
+    return null;
+  }
+  for (const [column, fingerprint] of [
+    ["sha256", fingerprints.sha256],
+    ["sha1", fingerprints.sha1],
+  ]) {
+    const selectCommand = `sqlite3 -readonly "${trustStorePath}" "select hex(${column}) from tsettings"`;
+    logger.debug(`${UNICODE.COMMAND} ${selectCommand}`);
+    let selectCommandOutput;
+    try {
+      selectCommandOutput = await exec(selectCommand);
+    } catch {
+      continue;
+    }
+    const storedFingerprints = selectCommandOutput
+      .split("\n")
+      .map((line) => line.trim().toUpperCase());
+    return storedFingerprints.includes(fingerprint);
+  }
+  logger.debug(
+    `${UNICODE.INFO} unexpected trust store layout at ${trustStorePath}`,
+  );
+  return null;
+};
+
+const getCertificateFingerprints = (certificate) => {
+  const { pki, asn1 } = forge;
+  const certificateForgeObject = pki.certificateFromPem(certificate);
+  const der = asn1
+    .toDer(pki.certificateToAsn1(certificateForgeObject))
+    .getBytes();
+  const derBuffer = Buffer.from(der, "binary");
+  return {
+    sha256: createHash("sha256").update(derBuffer).digest("hex").toUpperCase(),
+    sha1: createHash("sha1").update(derBuffer).digest("hex").toUpperCase(),
+  };
+};

package/src/internal/mac/mac.js

@@ -6,6 +6,7 @@
 
 import { executeTrustQueryOnChrome } from "./chrome_mac.js";
 import { executeTrustQueryOnFirefox } from "./firefox_mac.js";
+import { executeTrustQueryOnIosSimulator } from "./ios_simulator.js";
 import { executeTrustQueryOnMacKeychain } from "./mac_keychain.js";
 import { executeTrustQueryOnSafari } from "./safari.js";
 
@@ -48,10 +49,20 @@ export const executeTrustQuery = async ({
     macTrustInfo,
   });
 
+  // simulators have their own trust store, the mac keychain does not reach them
+  const iosSimulatorTrustInfo = await executeTrustQueryOnIosSimulator({
+    logger,
+    certificateFileUrl,
+    certificateIsNew,
+    certificate,
+    verb,
+  });
+
   return {
     mac: macTrustInfo,
     chrome: chromeTrustInfo,
     firefox: firefoxTrustInfo,
     safari: safariTrustInfo,
+    iosSimulator: iosSimulatorTrustInfo,
   };
 };