3.2.33 ā€¢ Published 6 months ago

@jsenv/https-local v3.2.33

Weekly downloads
-
License
MIT
Repository
github
Last release
6 months ago

HTTPS Local npm package

A programmatic way to generate locally trusted certificates for HTTPS development.

šŸ”’ Generate certificates trusted by your operating system and browsers
šŸŒ Perfect for local HTTPS development
šŸ–„ļø Works on macOS, Linux, and Windows
āš” Simple API for certificate management

Table of Contents

Quick Start

# Install the package
npm install @jsenv/https-local

# Install and trust the root certificate
npx @jsenv/https-local install --trust
// In your server file
import { createServer } from "node:https";
import { requestCertificate } from "@jsenv/https-local";

const { certificate, privateKey } = requestCertificate();
const server = createServer(
  {
    cert: certificate,
    key: privateKey,
  },
  (request, response) => {
    response.end("Hello HTTPS world!");
  },
).listen(8443, () => {
  console.log("HTTPS server running at https://localhost:8443");
});

How to Use

The following steps can be taken to start a local server in HTTPS:

1. Install the Root Certificate

npx @jsenv/https-local install --trust

This will install a root certificate valid for 20 years.

  • 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

start_dev_server.mjs

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";
    response.writeHead(200, {
      "content-type": "text/plain",
      "content-length": Buffer.byteLength(body),
    });
    response.write(body);
    response.end();
  },
);
server.listen(8080);
console.log(`Server listening at https://local.example:8080`);

3. Start the Server

node ./start_dev_server.mjs

At this stage you have a server running in HTTPS.

Certificate Expiration

CertificateExpires afterHow to renew?
server1 yearRe-run requestCertificate
authority20 yearsRe-run installCertificateAuthority

The server certificate expires after one year, which is the maximum duration allowed by web browsers. In the unlikely scenario where a local server is running for more than a year without interruption, restart it to re-run requestCertificate.

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 to update certificate authority then restart your server.

JavaScript API

requestCertificate

The requestCertificate function returns a certificate and private key that can be used to start a server in HTTPS.

import { createServer } from "node:https";
import { requestCertificate } from "@jsenv/https-local";

const { certificate, privateKey } = requestCertificate({
  altNames: ["localhost", "local.example"],
});

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.

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:

> 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
> 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

Auto Update Hosts

It's possible to update hosts file programmatically using tryToUpdateHostsFile:

import { verifyHostsFile } from "@jsenv/https-local";

await verifyHostsFile({
  ipMappings: {
    "127.0.0.1": ["localhost", "local.example"],
  },
  tryToUpdateHostsFile: true,
});
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

> node ./verify_hosts.mjs

Check hosts file content...
āœ” all ip mappings found in hosts file
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

> node ./verify_hosts.mjs

Check hosts file content...
āœ” all ip mappings found in hosts file

installCertificateAuthority

The 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.

import { installCertificateAuthority } from "@jsenv/https-local";

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. This process can be done programmatically as explained in Auto Trust.

> node ./install_certificate_authority.mjs

ā„¹ authority root certificate not found in filesystem
Generating authority root certificate with a validity of 20 years...
āœ” authority root certificate written at /Users/dmail/https_local/http_local_root_certificate.crt
ā„¹ You should add root certificate to mac keychain
ā„¹ You should add root certificate to firefox

Second execution logs

> node ./install_certificate_authority.mjs

āœ” authority root certificate found in filesystem
Checking certificate validity...
āœ” certificate still valid for 19 years
Detect if certificate attributes have changed...
āœ” certificate attributes are the same
Check if certificate is in mac keychain...
ā„¹ certificate not found in mac keychain
Check if certificate is in firefox...
ā„¹ certificate not found in firefox
> node ./install_certificate_authority.mjs

ā„¹ authority root certificate not found in filesystem
Generating authority root certificate with a validity of 20 years...
āœ” authority root certificate written at /home/dmail/.config/https_local/https_local_root_certificate.crt
ā„¹ You should add certificate to linux
ā„¹ You should add certificate to chrome
ā„¹ You should add certificate to firefox

Second execution logs

> node ./install_certificate_authority.mjs

āœ” authority root certificate found in filesystem
Checking certificate validity...
āœ” certificate still valid for 19 years
Detect if certificate attributes have changed...
āœ” certificate attributes are the same
Check if certificate is in linux...
ā„¹ certificate in linux is outdated
Check if certificate is in chrome...
ā„¹ certificate not found in chrome
Check if certificate is in firefox...
ā„¹ certificate not found in firefox
> node ./install_certificate_authority.mjs

ā„¹ authority root certificate not found in filesystem
Generating authority root certificate with a validity of 20 years...
āœ” authority root certificate written at C:\Users\Dmail\AppData\Local\https_local\https_local_root_certificate.crt
ā„¹ You should add certificate to windows
ā„¹ You should add certificate to firefox

Second execution logs

> node ./install_certificate_authority.mjs

āœ” authority root certificate found in filesystem
Checking certificate validity...
āœ” certificate still valid for 19 years
Detect if certificate attributes have changed...
āœ” certificate attributes are the same
Check if certificate is trusted by windows...
ā„¹ certificate is not trusted by windows
Check if certificate is trusted by firefox...
ā„¹ unable to detect if certificate is trusted by firefox (not implemented on windows)

Auto Trust

It's possible to trust root certificate programmatically using tryToTrust:

import { installCertificateAuthority } from "@jsenv/https-local";

await installCertificateAuthority({
  tryToTrust: true,
});
> node ./install_certificate_authority.mjs

ā„¹ authority root certificate not found in filesystem
Generating authority root certificate with a validity of 20 years...
āœ” authority root certificate written at /Users/dmail/https_local/https_local_root_certificate.crt
Adding certificate to mac keychain...
āÆ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "/Users/dmail/https_local/https_local_root_certificate.crt"
Password:
āœ” certificate added to mac keychain
Adding certificate to firefox...
āœ” certificate added to Firefox

Second execution logs

> node ./install_certificate_authority.mjs

āœ” authority root certificate found in filesystem
Checking certificate validity...
āœ” certificate still valid for 19 years
Detect if certificate attributes have changed...
āœ” certificate attributes are the same
Check if certificate is in mac keychain...
āœ” certificate found in mac keychain
Check if certificate is in Firefox...
āœ” certificate found in Firefox
> node ./install_certificate_authority.mjs

āœ” authority root certificate found in filesystem
Checking certificate validity...
āœ” certificate still valid for 19 years
Detect if certificate attributes have changed...
āœ” certificate attributes are the same
Check if certificate is in linux...
ā„¹ certificate not in linux
Adding certificate to linux...
āÆ sudo /bin/cp -f "/home/dmail/.config/https_local/https_local_root_certificate.crt" /usr/local/share/ca-certificates/https_local_root_certificate.crt
[sudo] Password for dmail :
āÆ sudo update-ca-certificates
āœ” certificate added to linux
Check if certificate is in chrome...
ā„¹ certificate not found in chrome
Adding certificate to chrome...
āœ” certificate added to chrome
Check if certificate is in firefox...
ā„¹ certificate not found in firefox
Adding certificate to firefox...
āœ” certificate added to firefox

Second execution logs

> node ./install_certificate_authority.mjs

āœ” authority root certificate found in filesystem
Checking certificate validity...
āœ” certificate still valid for 19 years
Detect if certificate attributes have changed...
āœ” certificate attributes are the same
Check if certificate is in linux...
āœ” certificate found in linux
Check if certificate is in chrome...
āœ” certificate found in chrome
Check if certificate is in firefox...
āœ” certificate found in firefox
> node ./install_certificate_authority.mjs

āœ” authority root certificate found in filesystem
Checking certificate validity...
āœ” certificate still valid for 19 years
Detect if certificate attributes have changed...
āœ” certificate attributes are the same
Check if certificate is trusted by windows...
ā„¹ certificate not trusted by windows
Adding certificate to windows...
āÆ certutil -addstore -user root C:\Users\Dmail\AppData\Local\https_local\https_local_root_certificate.crt
āœ” certificate added to windows
Check if certificate is trusted by firefox...
ā„¹ unable to detect if certificate is trusted by firefox (not implemented on windows)

Second execution logs

> node ./install_certificate_authority.mjs

āœ” authority root certificate found in filesystem
Checking certificate validity...
āœ” certificate still valid for 19 years
Detect if certificate attributes have changed...
āœ” certificate attributes are the same
Check if certificate is trusted by windows...
āœ” certificate trusted by windows
Check if certificate is trusted by firefox...
ā„¹ unable to detect if certificate is trusted by firefox (not implemented on windows)
@jsenv/filesystem@jsenv/humanize@jsenv/urlscommand-existsnode-forgesudo-promptwhich
@infinitebrahmanuniverse/nolb-_jse@everything-registry/sub-chunk-498@zalastax/nolb-_jse
3.2.24

9 months ago

3.2.23

9 months ago

3.2.26

9 months ago

3.2.25

9 months ago

3.2.28

8 months ago

3.2.27

9 months ago

3.2.29

8 months ago

3.2.20

10 months ago

3.2.22

9 months ago

3.2.21

9 months ago

3.2.31

7 months ago

3.2.30

8 months ago

3.2.33

6 months ago

3.2.32

7 months ago

3.2.13

12 months ago

3.2.12

12 months ago

3.2.15

11 months ago

3.2.14

12 months ago

3.2.17

10 months ago

3.2.16

11 months ago

3.2.19

10 months ago

3.2.18

10 months ago

3.2.11

1 year ago

3.2.9

1 year ago

3.2.8

1 year ago

3.2.7

1 year ago

3.2.2

1 year ago

3.2.1

1 year ago

3.2.0

1 year ago

3.1.1

1 year ago

3.1.0

1 year ago

3.2.6

1 year ago

3.2.5

1 year ago

3.2.4

1 year ago

3.2.3

1 year ago

3.2.10

1 year ago

3.0.7

2 years ago

3.0.4

3 years ago

3.0.3

3 years ago

3.0.2

3 years ago

3.0.6

3 years ago

3.0.5

3 years ago

1.1.0

3 years ago

3.0.1

3 years ago

3.0.0

3 years ago

2.1.0

3 years ago

2.0.0

3 years ago

1.0.11

3 years ago

1.0.10

3 years ago

1.0.8

4 years ago

1.0.7

4 years ago

1.0.6

4 years ago

1.0.5

4 years ago

1.0.3

4 years ago

1.0.2

4 years ago

1.0.1

4 years ago

1.0.0

4 years ago