Automatically provisions and renews Let’s Encrypt TLS certificates on Node.js https servers (including Kitten, Polka, Express.js, etc.)
Automatically provisions and renews Let’s Encrypt TLS certificates on Node.js https servers. As used in @small-tech/https and Kitten.
Implements the subset of RFC 8555 – Automatic Certificate Management Environment (ACME) – necessary for a client to support TLS certificate provisioning from Let’s Encrypt using HTTP-01 challenges.
Let’s Encrypt TLS certificates are automatically provisioned for you before your server starts.
Auto Encrypt uses the new Let’s Encrypt shortlived profile exclusively, which means certificates are valid for (and renewed before) 160 hours. This should occur at around the 80 hour mark of the certificate’s lifespan, in accordance with data returned by ACME Renewal Information (ARI).
Auto Encrypt also implements automatic support for obtaining certificates on IPv4 and IPv6 addresses to enable the use of Web Numbers on the Small Web.
When not provisioning certificates, Auto Encrypt also forwards HTTP calls to HTTPS on your server.
Node.js 18.20.0+ on Linux and macOS.
All tests pass on Node.js LTS (version 24).
> 💡 The module was tested to run on Windows 10 & 11 but it is no longer supported on Windows as Microsoft is complicit in Israel’s genocide of the Palestinian people and Small Technology Foundation stands in solidarity with the Boycott, Divestment, and Sanctions (BDS) movement. Windows is an ad-infested and surveillance-ridden dumpster fire of an operating system and, alongside supporting genocide, you are putting both yourself and others at risk by using it.
>
> 🇵🇸 To support families facing genocide in Gaza, consider donating to them via Gaza Verified.
``sh`
npm i @small-tech/auto-encrypt
1. Import the module:
`js`
import AutoEncrypt from '@small-tech/auto-encrypt'
2. Create your server:
`js`
// const server = https.createServer(…) becomes
const server = await AutoEncrypt.https.createServer(…)
> 💡 Auto Encrypt supports _one_ server per Node process. If you call createServer() again, any arguments you pass will be ignored and your will get the same server back. To create another server in the same process (e.g., when testing), call await server.close() first (see below) and then create the new server.
3. When done, close your server:
`js`
await server.close()
console.info ('The server is now closed.')
The following code creates an HTTPS server running on port 443 that automatically provisions and renews TLS certificates from Let’s Encrypt for the domains _<hostname>_.
`js
import AutoEncrypt from '@small-tech/auto-encrypt'
const server = await AutoEncrypt.https.createServer((_request, response) => {
response.end('Hello, world')
})
await server.listen()
const domain = os.hostname()
console.info(Auto-encrypted HTTPS server is running at ${domain}.)
try {
const response = await fetch(https://${domain}/)
const responseText = await response.text()
console.info('Server says:', responseText)
} catch (error) {
console.error(error)
}
await server.close()
console.info ('The server is now closed.')
`
Note that on Linux, ports 80 and 443 require special privileges. Please see A note on Linux and the security farce that is “privileged ports”. If you just need a Small Web server that handles all that and more for you (or to see how to implement privilege escalation seamlessly in your own servers, see Kitten).
You can customise the default configuration by adding Auto Encrypt-specific options to the options object you pass to the Node https server.
You can specify the domains you want the certificate to support, whether the Let’s Encrypt staging server or a local Pebble server should be used instead of the default production server (useful during development and testing), and to specify a custom settings path for your Let’s Encrypt account and certificate information to be stored in.
You can also set the ipv4 flag to true to make Auto Encrypt auto-detect your external IPv4 address (using https://ip.small-web.org/) and provision a certificate for it.
Similarly, you can set the ipv6 flag to true to make Auto Encrypt auto-detect stable IPv6 addresses on your machine (this is done locally) and provision certificates for them.
If you pass ipOnly: true, then certificates will only be provisioned for IP addresses. This turns off the automatic provisioning of certificates for the machine’s hostname and overrides any domains you may have passed in the domains array.
(Auto Encrypt uses Node Pebble to enable testing with a local Pebble server from Node.js.)
`js
import AutoEncrypt from '@small-tech/auto-encrypt'
const options = {
// Regular HTTPS server and TLS server options, if any, go here.
// Optional Auto Encrypt options:
ipv4: true,
ipOnly: true,
server: AutoEncrypt.server.STAGING,
settingsPath: '/custom/settings/path'
}
// Pass the options object to https.createServer()
const server = await AutoEncrypt.https.createServer(options, listener)
// …
`
Here is the full list of Auto Encrypt options (all optional) and their defaults:
- domains: the hostname of the current computer and the www subdomain at that hostname.server
- : it will use the production server (which has rate limits). Valid values are AutoEncrypt.server.(PEBBLE|STAGING|PRODUCTION).settingsPath
- : _~/.small-tech.org/auto-encrypt/_ipv4
- : true/false – whether or not to automatically detect external IPv4 address and add it to the TLS certificate being provisioned.ipv6
- : true/false – whether or not to automatically detect stable IPv6 addresses and add them to the TLS certificate being provisioned.ipOnly
- : When true, the machines hostname is not added to the TLS certificate and neither are the domains passed in the domains array, if any.
When you’re ready to exit your app, just call the await server.close() method. This will allow Auto Encrypt to perform housekeeping like shutting own the HTTP server that is used for answering Let’s Encrypt challenges as well as performing HTTP to HTTPS redirections and to destroy its certificate check update interval which, if not destroyed, will prevent your app from exiting.
If you want to help improve Auto Encrypt or better understand how it is structured and operates, please see the developer documentation.
`js
const express = require('express')
import AutoEncrypt from '@small-tech/auto-encrypt'
const app = express()
app.get('/', (request, response) => {
response.end('Hello, world!')
})
const myDomain = 'dev.ar.al'
const server = await AutoEncrypt.https.createServer(
{ domains: [myDomain] },
app
)
await server.listen()
console.log(Auto-encrypted Express server is running at https://${myDomain})
// Later…
await server.close()
console.info ('The server is now closed.')
`
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.
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.
Auto Encrypt does one thing and one thing well: it automatically provisions a Let’s Encrypt TLS certificate for your Node.js https servers using the HTTP-01 challenge method when your server is first hit from its hostname, and automatically renews your certificate thereafter. When not provisioning certificates, it forwards any HTTP requests that your machine gets to HTTPS.
__Auto Encrypt _does not_ and _will not:___
- __Implement wildcard certificates.__ For most small tech needs (personal web sites and web apps), you will likely need no more than two domains (the root domain and, due to historic and conventional reasons, the www subdomain). You will definitely not need more than the 100 domains that are supported per certificate. If you do, chances are you are looking to use Auto Encrypt in a startup or corporate setting, which is not what its for.
- __Implement DNS-01__ or any other methods that cannot be fully automated.
By default, Auto Encrypt uses Let’s Encrypt’s production environment. This is most likely what you want as it means your HTTPS server will Just Work™, i.e., provision its TLS certificate automatically the first time the server is hit via its hostname and from thereon automatically renew the certificate a month ahead of its expiry date.
However, be aware that the production server has rate limits.
For testing, Auto Encrypt provides seamless support for using the included local Pebble server or the Let’s Encrypt staging server.
If you do use the staging environment, be aware that browsers will reject the staging certificates unless you trust the Fake LE Root X1 certificate. If testing with an external https client written in Node, you can add the fake root certificate to your trust store temporarily, using the NODE_EXTRA_CA_CERTS environment variable or setting the ca options property when creating your https server. (Note that if you’re testing with the staging or Pebble server from the same process that Auto Encrypt is running in, Auto Encrypt automatically does this for you by monkeypatching Node’s TLS module with the necessary CA certificates.)
Needless to say, do not add the fake certificate root to the same trust store you use for your everyday browsing.
From lower-level to higher-level:
- Source: https://codeberg.org/small-tech/auto-encrypt-localhost
- Package: @small-tech/auto-encrypt-localhost
Automatically provisions and installs locally-trusted TLS certificates for Node.js https servers in 100% JavaScript (without any native dependencies like mkcert and certutil).
- Source: https://source.small-tech.org/site.js/lib/https
- Package: @small-tech/https
Drop-in replace for the standard Node.js HTTPS module replacement that automatically handles TLS certificate provisioning and renewal both at localhost (via Auto Encrypt Localhost) and at hostname (via Auto Encrypt).
- Site: https://kitten.small-web.org
- Source: https://codeberg.org/kitten/app
A 💕 Small Web development kit.
This project aims for > 80% coverage and currently has > 90%.
To see the current state of code coverage, run npm run coverage.
For more details, please see the developer documentation.
Linux has an outdated feature dating from the mainframe days that requires a process that wants to bind to ports < 1024 to have elevated privileges. While this was a security feature in the days of dumb terminals, today it is a security anti-feature. (macOS has dropped this requirement as of macOS Mojave.)
On modern Linux systems, you can disable privileged ports like this:
`sh`
sudo sysctl -w net.ipv4.ip_unprivileged_port_start=0
Or, if you want to cling to ancient historic relics like a conservative to a racist statue, ensure your Node process has the right to bind to so-called “privileged” ports by issuing the following command before use:
`sh`
sudo setcap cap_net_bind_service=+ep $(which node)
If you are wrapping your Node app into an executable binary using a module like Nexe, you will have to ensure that every build of your app has that capability set. For an example of how we do this in Site.js, see this listing.
Implements the subset of RFC 8555 – Automatic Certificate Management Environment (ACME) – necessary for a Node.js https server to provision TLS certificates from Let’s Encrypt using the HTTP-01 challenge on first hit of an HTTPS route via use of the Server Name Indication (SNI) callback.
The code uses TC39 class fields with the following naming conventions for private fields:
`js``
#property // safe property access (either via accessor or where property is both safe to get and set)
#_property // unsafe property access (should only be used in accessors)
(Documenting these here as private class fields – ‘hashnames’ – are relatively new as of this writing and may not be familiar to some. The use of the underscore to differentiate direct property access from mediated access via an accessor is a project convention.)
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.
© 2020-present Aral Balkan, Small Technology Foundation.
Let’s Encrypt is a trademark of the Internet Security Research Group (ISRG). All rights reserved. Node.js is a trademark of Joyent, Inc. and is used with its permission. We are not endorsed by or affiliated with Joyent or ISRG.