@jsenv/https-local 3.0.7 → 3.1.0

package/README.md

@@ -1,4 +1,6 @@
-# https local [![npm package](https://img.shields.io/npm/v/@jsenv/https-local.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/https-local)
+# https local
+
+[![npm package](https://img.shields.io/npm/v/@jsenv/https-local.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/https-local)
 
 A programmatic way to generate locally trusted certificates.
 
@@ -8,88 +10,52 @@ Works on mac, linux and windows.
 
 # How to use
 
-1 - Install _@jsenv/https-local_
-
-```console
-npm install --save-dev @jsenv/https-local
-```
+The following steps can be taken to start a local server in https.
 
-2 - Create _install_certificate_authority.mjs_
+1. Install the root certificate using https-local
+2. Request certificate for your server
+3. Start that server
 
-```js
-/*
- * This file needs to be executed once.
- * After that the root certificate is valid for 20 years.
- * Re-executing this file will log the current root certificate validity and trust status.
- * Re-executing this file 20 years later would reinstall a root certificate and re-trust it.
- *
- * Read more in https://github.com/jsenv/https-local#installCertificateAuthority
- */
-
-import {
-  installCertificateAuthority,
-  verifyHostsFile,
-} from "@jsenv/https-local"
+## 1. Install the root certificate
 
-await installCertificateAuthority({
-  tryToTrust: true,
-  NSSDynamicInstall: true,
-})
-await verifyHostsFile({
-  ipMappings: {
-    "127.0.0.1": ["localhost"],
-  },
-  tryToUpdatesHostsFile: true,
-})
+```console
+npx @jsenv/https-local install --trust
 ```
 
-3 - Run with node
+This will install a root certificate valid for 20 years.
 
-```console
-node ./install_certificate_authority.mjs
-```
+- Re-executing this command will log the current root certificate validity and trust status.
+- Re-executing this command 20 years later would reinstall a root certificate and re-trust it
+
+## 2. Request certificate for your server
 
-4 - Create _start_dev_server.mjs_
+_start_dev_server.mjs_
 
 ```js
-/*
- * This file uses "@jsenv/https-local" to obtain a certificate used to start a server in https.
- * The certificate is valid for 1 year (396 days) and is issued by a certificate authority trusted on this machine.
- * If the certificate authority was not installed before executing this file, an error is thrown
- * explaining that certificate authority must be installed first.
- *
- * To install the certificate authority, you can use the following command
- *
- * > node ./install_certificate_authority.mjs
- *
- * Read more in https://github.com/jsenv/https-local#requestCertificate
- */
-
-import { createServer } from "node:https"
-import { requestCertificate } from "@jsenv/https-local"
-
-const { certificate, privateKey } = requestCertificate()
+import { createServer } from "node:https";
+import { requestCertificate } from "@jsenv/https-local";
 
+const { certificate, privateKey } = requestCertificate();
 const server = createServer(
   {
     cert: certificate,
     key: privateKey,
   },
   (request, response) => {
-    const body = "Hello world"
+    const body = "Hello world";
     response.writeHead(200, {
       "content-type": "text/plain",
       "content-length": Buffer.byteLength(body),
-    })
-    response.write(body)
-    response.end()
+    });
+    response.write(body);
+    response.end();
   },
-)
-server.listen(8080)
-console.log(`Server listening at https://local.example:8080`)
+);
+server.listen(8080);
+console.log(`Server listening at https://local.example:8080`);
 ```
 
-5 - Start server with node
+## 3. Start the server
 
 ```console
 node ./start_dev_server.mjs
@@ -111,15 +77,142 @@ In the unlikely scenario where a local server is running for more than a year wi
 The **authority root certificate** expires after 20 years which is close to the maximum allowed duration.
 In the very unlikely scenario where you are using the same machine for more than 20 years, re-execute [installCertificateAuthority](#installCertificateAuthority) to update certificate authority then restart your server.
 
-# installCertificateAuthority
+# JavaScript API
+
+## requestCertificate
+
+_requestCertificate_ function returns a certificate and private key that can be used to start a server in HTTPS.
+
+```js
+import { createServer } from "node:https";
+import { requestCertificate } from "@jsenv/https-local";
+
+const { certificate, privateKey } = requestCertificate({
+  altNames: ["localhost", "local.example"],
+});
+```
+
+[installCertificateAuthority](#installCertificateAuthority) must be called before this function.
+
+## verifyHostsFile
+
+This function is not mandatory to obtain the https certificates.
+But it is useful to programmatically verify ip mappings that are important for your local server are present in hosts file.
+
+```js
+import { verifyHostsFile } from "@jsenv/https-local";
+
+await verifyHostsFile({
+  ipMappings: {
+    "127.0.0.1": ["localhost", "local.example"],
+  },
+});
+```
+
+Find below logs written in terminal when this function is executed.
+
+<details>
+  <summary>mac and linux</summary>
+
+```console
+> node ./verify_hosts.mjs
+
+Check hosts file content...
+⚠ 1 mapping is missing in hosts file
+--- hosts file path ---
+/etc/hosts
+--- line(s) to add ---
+127.0.0.1 localhost local.example
+```
+
+</details>
+
+<details>
+  <summary>windows</summary>
+
+```console
+> node ./verify_hosts.mjs
+
+Check hosts file content...
+⚠ 1 mapping is missing in hosts file
+--- hosts file path ---
+C:\\Windows\\System32\\Drivers\\etc\\hosts
+--- line(s) to add ---
+127.0.0.1 localhost local.example
+```
+
+</details>
+
+### Auto update hosts
+
+It's possible to update hosts file programmatically using _tryToUpdateHostsFile_.
+
+```js
+import { verifyHostsFile } from "@jsenv/https-local";
+
+await verifyHostsFile({
+  ipMappings: {
+    "127.0.0.1": ["localhost", "local.example"],
+  },
+  tryToUpdateHostsFile: true,
+});
+```
+
+<details>
+  <summary>mac and linux</summary>
+
+```console
+Check hosts file content...
+ℹ 1 mapping is missing in hosts file
+Adding 1 mapping(s) in hosts file...
+❯ echo "127.0.0.1 local.example" | sudo tee -a /etc/hosts
+Password:
+✔ mappings added to hosts file
+```
+
+_Second execution logs_
+
+```console
+> node ./verify_hosts.mjs
+
+Check hosts file content...
+✔ all ip mappings found in hosts file
+```
+
+</details>
+
+<details>
+  <summary>windows</summary>
+
+```console
+Check hosts file content...
+ℹ 1 mapping is missing in hosts file
+Adding 1 mapping(s) in hosts file...
+❯ (echo 127.0.0.1 local.example) >> C:\\Windows\\System32\\Drivers\\etc\\hosts
+Password:
+✔ mappings added to hosts file
+```
+
+_Second execution logs_
+
+```console
+> node ./verify_hosts.mjs
+
+Check hosts file content...
+✔ all ip mappings found in hosts file
+```
+
+</details>
+
+## installCertificateAuthority
 
 _installCertificateAuthority_ function generates a certificate authority valid for 20 years.
 This certificate authority is needed to generate local certificates that will be trusted by the operating system and web browsers.
 
 ```js
-import { installCertificateAuthority } from "@jsenv/https-local"
+import { installCertificateAuthority } from "@jsenv/https-local";
 
-await installCertificateAuthority()
+await installCertificateAuthority();
 ```
 
 By default, trusting authority root certificate is a manual process. This manual process is documented in [BenMorel/dev-certificates#Import the CA in your browser](https://github.com/BenMorel/dev-certificates/tree/c10cd68945da772f31815b7a36721ddf848ff3a3#import-the-ca-in-your-browser). This process can be done programmatically as explained in [Auto trust](#Auto-trust).
@@ -222,16 +315,16 @@ Check if certificate is trusted by firefox...
 
 </details>
 
-## Auto trust
+### Auto trust
 
 It's possible to trust root certificate programmatically using _tryToTrust_
 
 ```js
-import { installCertificateAuthority } from "@jsenv/https-local"
+import { installCertificateAuthority } from "@jsenv/https-local";
 
 await installCertificateAuthority({
   tryToTrust: true,
-})
+});
 ```
 
 <details>
@@ -354,128 +447,3 @@ Check if certificate is trusted by firefox...
 ```
 
 </details>
-
-# requestCertificate
-
-_requestCertificate_ function returns a certificate and private key that can be used to start a server in HTTPS.
-
-```js
-import { createServer } from "node:https"
-import { requestCertificate } from "@jsenv/https-local"
-
-const { certificate, privateKey } = requestCertificate({
-  altNames: ["localhost", "local.example"],
-})
-```
-
-[installCertificateAuthority](#installCertificateAuthority) must be called before this function.
-
-# verifyHostsFile
-
-This function is not mandatory to obtain the https certificates.
-But it is useful to programmatically verify ip mappings that are important for your local server are present in hosts file.
-
-```js
-import { verifyHostsFile } from "@jsenv/https-local"
-
-await verifyHostsFile({
-  ipMappings: {
-    "127.0.0.1": ["localhost", "local.example"],
-  },
-})
-```
-
-Find below logs written in terminal when this function is executed.
-
-<details>
-  <summary>mac and linux</summary>
-
-```console
-> node ./verify_hosts.mjs
-
-Check hosts file content...
-⚠ 1 mapping is missing in hosts file
---- hosts file path ---
-/etc/hosts
---- line(s) to add ---
-127.0.0.1 localhost local.example
-```
-
-</details>
-
-<details>
-  <summary>windows</summary>
-
-```console
-> node ./verify_hosts.mjs
-
-Check hosts file content...
-⚠ 1 mapping is missing in hosts file
---- hosts file path ---
-C:\\Windows\\System32\\Drivers\\etc\\hosts
---- line(s) to add ---
-127.0.0.1 localhost local.example
-```
-
-</details>
-
-## Auto update hosts
-
-It's possible to update hosts file programmatically using _tryToUpdateHostsFile_.
-
-```js
-import { verifyHostsFile } from "@jsenv/https-local"
-
-await verifyHostsFile({
-  ipMappings: {
-    "127.0.0.1": ["localhost", "local.example"],
-  },
-  tryToUpdateHostsFile: true,
-})
-```
-
-<details>
-  <summary>mac and linux</summary>
-
-```console
-Check hosts file content...
-ℹ 1 mapping is missing in hosts file
-Adding 1 mapping(s) in hosts file...
-❯ echo "127.0.0.1 local.example" | sudo tee -a /etc/hosts
-Password:
-✔ mappings added to hosts file
-```
-
-_Second execution logs_
-
-```console
-> node ./verify_hosts.mjs
-
-Check hosts file content...
-✔ all ip mappings found in hosts file
-```
-
-</details>
-
-<details>
-  <summary>windows</summary>
-
-```console
-Check hosts file content...
-ℹ 1 mapping is missing in hosts file
-Adding 1 mapping(s) in hosts file...
-❯ (echo 127.0.0.1 local.example) >> C:\\Windows\\System32\\Drivers\\etc\\hosts
-Password:
-✔ mappings added to hosts file
-```
-
-_Second execution logs_
-
-```console
-> node ./verify_hosts.mjs
-
-Check hosts file content...
-✔ all ip mappings found in hosts file
-```
-
-</details>

package/package.json

@@ -1,22 +1,18 @@
 {
   "name": "@jsenv/https-local",
-  "version": "3.0.7",
+  "version": "3.1.0",
   "description": "A programmatic way to generate locally trusted certificates",
   "license": "MIT",
-  "author": {
-    "name": "dmail",
-    "email": "dmaillard06@gmail.com",
-    "url": "https://twitter.com/damienmaillard"
-  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/jsenv/https-local"
+    "url": "https://github.com/jsenv/core",
+    "directory": "packages/independent/https-local"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=16.13.0"
+    "node": ">=20.0.0"
   },
   "type": "module",
   "exports": {
@@ -25,15 +21,14 @@
     },
     "./*": "./*"
   },
+  "bin": "./src/https_local_cli.mjs",
   "main": "./src/main.js",
   "files": [
     "/src/"
   ],
   "scripts": {
-    "eslint": "npx eslint . --ext=.js,.mjs,.cjs",
     "test": "node ./scripts/test/test.mjs",
     "performance": "node --expose-gc ./scripts/performance/performance.mjs  --local --log",
-    "test:coverage": "npm run test -- --coverage",
     "test:start-node-server": "node ./scripts/certificate/start_node_server.mjs",
     "ca:install": "node ./scripts/certificate/install_ca.mjs",
     "ca:log-trust": "node ./scripts/certificate/log_root_certificate_trust.mjs",
@@ -43,30 +38,15 @@
     "hosts:add-localhost-mappings": "node ./scripts/hosts/add_localhost_mappings.mjs",
     "hosts:remove-localhost-mappings": "node ./scripts/hosts/remove_localhost_mappings.mjs",
     "hosts:verify-localhost-mappings": "node ./scripts/hosts/verify_localhost_mappings.mjs",
-    "hosts:ensure-localhost-mappings": "node ./scripts/hosts/ensure_localhost_mappings.mjs",
-    "prettier": "prettier --write .",
-    "playwright:install": "npx playwright install-deps && npx playwright install"
+    "hosts:ensure-localhost-mappings": "node ./scripts/hosts/ensure_localhost_mappings.mjs"
   },
   "dependencies": {
-    "@jsenv/filesystem": "4.1.9",
-    "@jsenv/log": "3.3.2",
-    "@jsenv/urls": "1.2.8",
+    "@jsenv/filesystem": "4.10.2",
+    "@jsenv/humanize": "1.2.8",
+    "@jsenv/urls": "2.5.2",
     "command-exists": "1.2.9",
     "node-forge": "1.3.1",
     "sudo-prompt": "9.2.1",
-    "which": "3.0.0"
-  },
-  "devDependencies": {
-    "@jsenv/assert": "2.8.0",
-    "@jsenv/core": "30.0.4",
-    "@jsenv/eslint-config": "16.3.2",
-    "@jsenv/eslint-import-resolver": "0.4.4",
-    "@jsenv/github-release-package": "1.5.1",
-    "@jsenv/package-publish": "1.10.1",
-    "@jsenv/performance-impact": "4.1.0",
-    "eslint": "8.30.0",
-    "eslint-plugin-import": "2.26.0",
-    "playwright": "1.29.1",
-    "prettier": "2.8.1"
+    "which": "4.0.0"
   }
 }