A drop-in standard Node.js HTTPS module replacement with both automatic development-time (localhost) certificates via Auto Encrypt Localhost and automatic production certificates via Auto Encrypt.
Note: This is the CommonJS (CJS) version of the library. For the ECMAScript Modules (ESM) version, please see the main branch.
Simply replace Node’s https module with @small-tech/https and get:
- Automatically-provisioned TLS certificates at localhost with no browser warnings.
- Automatically-provisioned TLS certificates at hostname via Let’s Encrypt.
- Automatic HTTP to HTTPS forwarding at hostname.
That’s it.
This is basically a batteries-included version of the standard Node.js https module.
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.
Works on Linux, macOS, and Windows (WSL is not supported for certificates at localhost unless you’re running your browser under WSL also).
npm i @small-tech/httpsconst https = require('@small-tech/https')
const server = https.createServer((request, response) => {
response.end('Hello, world!')
})
server.listen(443, () => {
console.log(' 🎉 Server running at https://localhost.')
})Hit https://localhost and you should see your site with locally-trusted TLS certificates.
const https = require('@small-tech/https')
const os = require('os')
const hostname = os.hostname()
const options = { domains: [hostname] }
const server = https.createServer((request, response) => {
response.end('Hello, world!')
})
server.listen(443, () => {
console.log(` 🎉 Server running at https://${hostname}.`)
})To provision globally-trusted Let’s Encrypt certificates, we additionally create an options object containing the domain(s) we want to support, and pass it as the first argument in the createServer() method.
You can find a version of this example in the /example folder. To download and run that version:
# Clone this repository.
git clone https://source.small-tech.org/site.js/lib/https.git
# Switch to the directory.
cd https
# Install dependencies.
npm i
# Run the example.
npm run exampleLinux 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:
sudo sysctl -w net.ipv4.ip_unprivileged_port_start=0Or, 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:
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.
Lower-level:
- Source: https://source.small-tech.org/site.js/lib/auto-encrypt
- Package: @small-tech/auto-encrypt
Adds automatic provisioning and renewal of Let’s Encrypt TLS certificates with OCSP Stapling to Node.js https servers (including Express.js, etc.)
- Source: https://source.small-tech.org/site.js/lib/auto-encrypt-localhost
- Package: @small-tech/auto-encrypt-localhost
Automatically provisions and installs locally-trusted TLS certificates for Node.js https servers (including Express.js, etc.) using mkcert.
Higher level:
- Web site: https://sitejs.org
- Source: https://source.small-tech.org/site.js/app
A complete small technology tool for developing, testing, and deploying a secure static or dynamic personal web site or app with zero configuration.
© 2020-2021 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.