@small-tech/auto-encrypt 4.3.0 → 5.0.0

package/README.md

@@ -1,20 +1,28 @@
 # Auto Encrypt
 
-Automatically provisions and renews [Let’s Encrypt](https://letsencrypt.org) TLS certificates on [Node.js](https://nodejs.org) [https](https://nodejs.org/dist/latest-v12.x/docs/api/https.html) servers (including [Kitten](https://kitten.small-web.org), [Polka](https://github.com/lukeed/polka/tree/next), [Express.js](https://expressjs.com/), etc.)
+Automatically provisions and renews [Let’s Encrypt](https://letsencrypt.org) TLS certificates on [Node.js](https://nodejs.org) [https](https://nodejs.org/docs/latest-v24.x/api/https.html) servers. As used in [@small-tech/https](https://codeberg.org/small-tech/https) and [Kitten](https://kitten.small-web.org).
 
 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.
 
 ## How it works
 
-The first time your web site is hit, it takes a couple of seconds to load as your Let’s Encrypt TLS certificates are automatically provisioned for you. From there on, your certificates are seamlessly renewed 30 days before their expiry date.
+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](https://ar.al/2025/06/25/web-numbers/) on the Small Web.
 
 When not provisioning certificates, Auto Encrypt also forwards HTTP calls to HTTPS on your server.
 
 ## Compatibility
 
-Node.js 18.20.0+.
+Node.js 18.20.0+ on Linux and macOS.
+
+All tests pass on Node.js LTS (version 24).
 
-All tests pass on Node.js LTS (version 22).
+> 💡 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](https://www.bdsmovement.net/microsoft) and [Small Technology Foundation](https://small-tech.org/) stands in solidarity with the [Boycott, Divestment, and Sanctions (BDS) movement](https://www.bdsmovement.net/). **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](https://gaza-verified.org/donate/).
 
 ## Installation
 
@@ -27,46 +35,53 @@ npm i @small-tech/auto-encrypt
 ### Instructions
 
 1. Import the module:
-   
+
    ```js
    import AutoEncrypt from '@small-tech/auto-encrypt'
    ```
 
-2. Prefix your server creation code with a reference to the Auto Encrypt class:
-   
-   ```js
-   // const server = https.createServer(…) becomes
-   const server = AutoEncrypt.https.createServer(…)
-   ```
+2. Create your server:
 
-3. When done, close your server as you would normally:
-   
-   ```js
-   server.close(() => {
-     console.log('The server is now closed.')
-   })
-   ```
+    ```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.')
+    ```
 
 ### Example
 
-The following code creates an HTTPS server running on port 443 that automatically provisions and renews TLS certificates from [Let’s Encrypt](https://letsencrypt.org) for the domains _<hostname>_ and _www.<hostname>_.
+The following code creates an HTTPS server running on port 443 that automatically provisions and renews TLS certificates from [Let’s Encrypt](https://letsencrypt.org) for the domains _<hostname>_.
 
 ```js
 import AutoEncrypt from '@small-tech/auto-encrypt'
 
-const server = AutoEncrypt.https.createServer((request, response) => {
+const server = await AutoEncrypt.https.createServer((_request, response) => {
   response.end('Hello, world')
 })
 
-server.listen(() => {
-  console.log(`Auto-encrypted HTTPS server is running at ${os.hostname()} and www.${os.hostname()}.`)
-})
+await server.listen()
 
-// Later…
+const domain = os.hostname()
+console.info(`Auto-encrypted HTTPS server is running at ${domain}.`)
 
-server.close(() => {
-  console.log('The server is now closed.')
-})
+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”](#a-note-on-linux-and-the-security-farce-that-is-priviliged-ports). If you just need a [Small Web](https://ar.al/2024/06/24/small-web-computer-science-colloquium-at-university-of-groningen/) server that handles all that and more for you (or to see how to implement privilege escalation seamlessly in your own servers, see [Kitten](https://kitten.small-web.org)).
@@ -77,6 +92,12 @@ You can customise the default configuration by adding Auto Encrypt-specific opti
 
 You can specify the domains you want the certificate to support, whether the Let’s Encrypt staging server or a local [Pebble](https://github.com/letsencrypt/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](https://codeberg.org/small-tech/node-pebble) to enable testing with a local Pebble server from Node.js.)
 
 ### Example
@@ -88,13 +109,14 @@ const options = {
   // Regular HTTPS server and TLS server options, if any, go here.
 
   // Optional Auto Encrypt options:
-  domains: ['first.domain', 'second.domain', /* … */],
+  ipv4: true,
+  ipOnly: true,
   server: AutoEncrypt.server.STAGING,
   settingsPath: '/custom/settings/path'
 }
 
 // Pass the options object to https.createServer()
-const server = AutoEncrypt.https.createServer(options, listener)
+const server = await AutoEncrypt.https.createServer(options, listener)
 
 // …
 ```
@@ -106,38 +128,19 @@ 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](https://letsencrypt.org/docs/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.
 
 ## Making a graceful exit
 
-When you’re ready to exit your app, just call the `server.close()` method as you would normally. 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.
+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.
 
 ## Developer documentation
 
 If you want to help improve Auto Encrypt or better understand how it is structured and operates, please see the [developer documentation](https://codeberg.org/small-tech/auto-encrypt/src/branch/main/developer-documentation.md).
 
-## Examples
-
-### Regular https
-
-```js
-import AutoEncrypt from '@small-tech/auto-encrypt'
-
-const server = AutoEncrypt.https.createServer({ domains: ['dev.ar.al'] }, (request, response) => {
-    response.end('Hello, world!')
-})
-
-server.listen(() => {
-  console.log('Auto-encrypted HTTPS server is running at https://dev.ar.al')
-})
-
-// Later…
-
-server.close(() => {
-  console.log('The server is now closed.')
-})
-```
-
-### Express.js
+### Express.js example
 
 ```js
 const express = require('express')
@@ -148,21 +151,18 @@ app.get('/', (request, response) => {
   response.end('Hello, world!')
 })
 
-const server = AutoEncrypt.https.createServer(
-  autoEncrypt({ domains: ['dev.ar.al'] }),
+const myDomain = 'dev.ar.al'
+const server = await AutoEncrypt.https.createServer(
+  { domains: [myDomain] },
   app
 )
 
-server.listen(() => {
-  console.log('Auto-encrypted Express server is running at https://dev.ar.al')
-})
-
+await server.listen()
+console.log(`Auto-encrypted Express server is running at https://${myDomain}`)
 
 // Later…
-
-server.close(() => {
-  console.log('The server is now closed.')
-})
+await server.close()
+console.info ('The server is now closed.')
 ```
 
 ## Like this? Fund us!
@@ -226,7 +226,7 @@ A [💕 Small Web](https://ar.al/2020/08/07/what-is-the-small-web/) development
 
 ## Tests and coverage
 
-This project aims for > 80% coverage. At a recent check, coverage was at 97.42% (statements), 92.64% (branch), 91.49% (functions), 97.42% (lines).
+This project aims for > 80% coverage and currently has > 90%.
 
 To see the current state of code coverage, run `npm run coverage`.
 

package/index.d.ts

@@ -0,0 +1,152 @@
+/**
+  Automatically provisions and renews Let’s Encrypt™ TLS certificates for 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 Node.js https server to provision TLS certificates from Let’s Encrypt using the HTTP-01 challenge.
+
+  The certificates are provisioned, if necessary, at time of server creation, prior to server start with hourly renewal checks  and automatic renewals.
+
+  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 (see https://ar.al/2025/06/25/web-numbers/).
+
+  Remember that Auto Encrypt is for the Small Web (peer-to-peer Web). You might find it useful for everyday web purposes also but it is specifically focused for Small Web use cases and explicitly does not aim to be a generic or exhaustive ACME client.
+
+  @module @small-tech/auto-encrypt
+  @copyright © 2020-present Aral Balkan, Small Technology Foundation.
+  @license AGPLv3 or later.
+*/
+
+import { Server, ServerOptions } from 'node:https'
+import { SecureContext } from 'node:tls'
+import { IncomingMessage, ServerResponse } from 'node:http'
+
+/**
+  Options for creating an AutoEncrypt server. Extends Node’s https.ServerOptions.
+*/
+export interface AutoEncryptOptions extends ServerOptions {
+  /**
+    The domains for which to provision and renew certificates.
+  */
+  domains?: string[]
+
+  /**
+    Type of Let’s Encrypt server to use. Use AutoEncrypt.serverType constants.
+  */
+  serverType?: number
+
+  /**
+    Path where settings and certificates will be stored.
+  */
+  settingsPath?: string
+
+  /**
+    Whether to automatically detect and use the machine’s IPv4 address.
+  */
+  ipv4?: boolean
+
+  /**
+    Whether to automatically detect and use the machine’s stable IPv6 addresses.
+  */
+  ipv6?: boolean
+
+  /**
+    If true, only IP addresses (IPv4/IPv6 as requested) are used, ignoring the hostname.
+  */
+  ipOnly?: boolean
+}
+
+/**
+  Request listener function signature.
+*/
+export type RequestListener = (req: IncomingMessage, res: ServerResponse) => void
+
+/**
+  Enumeration of Let’s Encrypt server types.
+*/
+export interface ServerType {
+  PRODUCTION: 0
+  STAGING: 1
+  PEBBLE: 2
+  MOCK: 3
+}
+
+/**
+  Represents a Let’s Encrypt TLS certificate.
+*/
+export interface Certificate {
+  getSecureContext(): Promise<SecureContext | null>
+  checkForRenewal(): Promise<void>
+  stopCheckingForRenewal(): void
+  readonly isProvisioned: boolean
+  readonly pem: string | Buffer | Array<string | Buffer> | undefined
+}
+
+/**
+  Represents a Let’s Encrypt server instance.
+*/
+export interface LetsEncryptServer {
+  readonly type: number
+  readonly name: string
+  readonly endpoint: string
+}
+
+/**
+  The monkey-patched https.Server instance returned by AutoEncrypt.
+*/
+export interface AutoEncryptedServer extends Server {
+  listen(...args:any[]): Promise<AutoEncryptedServer>
+  async close(): Promise<void>
+}
+
+/**
+  Auto Encrypt is a static class. Please do not instantiate.
+
+  Use: AutoEncrypt.https.createServer(…)
+
+  @alias module:@small-tech/auto-encrypt
+  @hideconstructor
+*/
+export default class AutoEncrypt {
+  static letsEncryptServer: LetsEncryptServer | null
+  static defaultDomains   : string[] | null
+  static domains          : string[] | null
+  static settingsPath     : string | null
+  static listener         : RequestListener | null
+  static certificate      : Certificate | null
+
+  /**
+    Enumeration.
+
+    @static
+    @readonly
+  */
+  static readonly serverType: ServerType
+
+  /**
+    By aliasing the https property to the AutoEncrypt static class itself, we enable people to add AutoEncrypt to their existing apps by requiring the module and prefixing their https.createServer(…) line with AutoEncrypt:
+
+    @example import AutoEncrypt from '@small-tech/auto-encrypt'
+    const server = AutoEncrypt.https.createServer()
+
+    @static
+  */
+  static readonly https: typeof AutoEncrypt
+
+  /**
+    Automatically manages Let’s Encrypt certificate provisioning and renewal for Node.js https servers using the HTTP-01 challenge on first hit of an HTTPS route via use of the Server Name Indication (SNI) callback.
+
+    @static
+
+    @param {AutoEncryptOptions | RequestListener} [options] Configuration options or a request listener.
+    @param {RequestListener} [listener] Optional request listener if options were provided.
+    @returns {Promise<AutoEncryptedServer>} The server instance returned by Node’s https.createServer() method.
+  */
+  static async createServer(options?: AutoEncryptOptions | RequestListener, listener?: RequestListener): Promise<AutoEncryptedServer>
+
+  /**
+    Shut Auto Encrypt down. Do this before app exit. Performs necessary clean-up and removes any references that might cause the app to not exit.
+  */
+  static async shutdown(): Promise<void>
+
+  private constructor()
+}