@small-tech/auto-encrypt-localhost

Auto Encrypt Localhost

Automatically provision trusted development-time (localhost) certificates in Node.js without browser errors via mkcert.

Install

npm i @small-tech/auto-encrypt-localhost

Use

// Create an https server using locally-trusted certificates.

const https = require('https')
const autoEncryptLocalhost = require('@small-tech/auto-encrypt-localhost')

const server = https.createServer(autoEncryptLocalhost(), (request, response) => {
  response.end('Hello, world!')
})

server.listen(() => {
  console.log('Web server is running at https://localhost')
})

PS. You can find this example in the example/ folder in the source code. Run it by typing node example.

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.

Audience

This is small technology.

If you’re evaluating this for a “startup” or an enterprise, let us save you some time: this is not the right tool for you. This tool is for individual developers to build personal web sites and apps for themselves and for others in a non-colonial manner that respects the human rights of the people who use them.

Details

Auto Encrypt Localhost is a Node.js wrapper for mkcert that:

• Uses the 64-bit release binaries to support Linux, macOS, and Windows.

• Automatically installs the certutil (nss) dependency on Linux on systems with apt, pacman, yum (untested) and and on macOS if you have Homebrew or MacPorts (untested).

• Creates a root Certificate Authority

• Creates locally-trusted TLS certificates for localhost, 127.0.0.1, and ::1

You can use these certificates for local development without triggering self-signed certificate errors.

It should Just Work™ 🤞

Auto Encrypt Localhost is used in Site.js, a personal web tool for human beings (not startups or enterprises) that lets you develop, test, and deploy your secure static or dynamic personal web site with zero configuration.

For more details on how Auto Encrypt Localhost works behind the scenes, please see the mkcert README.

Advanced usage

Auto Encrypt Localhost is exposed as a function and it accepts an optional parameter object with optional options and settingsPath properties. The defaults for both are shown below.

autoEncryptLocalhost({ options: {}, settingsPath: '~/.small-tech.org/auto-encrypt-localhost' })

Use custom https server options

Auto Encrypt Localhost generates a locally-trusted private key and certificate using mkcert and then loads them in and returns an options object that you can pass directly to the https.createServer() method. If you want to pass other options to the server while creating it, just pass your regular options object to Auto Encrypt Localhost wrapped in a parameter object as shown below.

const options = { /* your other https server options go here */ }
const server = https.createServer(autoEncryptLocalhost({ options }), (request, response) => {
  response.end('Hello, world!')
})

Use a custom settings path

By default, Auto Encrypt Localhost creates and uses the ~/.small-tech.org/auto-encrypt-localhost directory as its settings path, to store your certificate and its private key. You can tell it to use a different path instead by specifying the path to use in the settingsPath property of its parameter object.

const os = require('os')
const path = require('path')
const settingsPath = path.join(os.homedir(), '.my-namespace', 'magic-localhost-certificates')
const server = https.createServer(autoEncryptLocalhost({ settingsPath }), (request, response) => {
  response.end('Hello, world!')
})

In the above example, your certificate and its private key will be stored in the ~/.my-namespace/magic-localhost-certificates directory (with the names localhost.pem and localhost-key.pem, respectively).

Command-line interface

Install

npm i -g @small-tech/auto-encrypt-localhost

Use

auto-encrypt-localhost

Your certificates will be created in the ~/.small-tech.org/auto-encrypt-localhost directory.

Caveats

Windows

Locally-trusted certificates do not work under Firefox. Please use Edge or Chrome on this platform. This is a mkcert limitation

API

require('@small-tech/auto-encrypt-localhost')()

Note that Auto Encrypt Localhost is synchronous. It will block your main thread. It is designed to be run before you initialise your app’s web server.

As of version 3.1.1, you can now pass a custom directory for Auto Encrypt Localhost to use instead of the default (~/.small-tech.org/auto-encrypt-localhost) directory and the created certificates will be stored there.

For example:

const os = require('os)
const path = require('path')
const autoEncryptLocalhost = require('@small-tech/auto-encrypt-localhost')

const customDirectory = path.join(os.homedir(), '.my-app', 'tls', 'local')

nodecert(customDirectory)

Help wanted

• Linux: certutil (nss) auto-installation has not been tested with yum.
• macOS: certutil (nss) auto-installation has not been tested with MacPorts.

TODO: update the Github Mirror URL!

I can use your help in testing these out. Let me know if it works or blows up by opening an issue on the GitHub mirror. Pull requests are also welcome.

Thanks in advance! 🤓👍 – Aral

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.

Copyright

Copyright © Aral Balkan, Small Technology Foundation.

License

Auto Encrypt Localhost is released under AGPL 3.0 or later.