@small-tech/auto-encrypt 4.3.0 → 5.0.0

package/index.js

@@ -1,139 +1,203 @@
 /**
- * Automatically provisions and renews Let’s Encrypt™ TLS certificates for
- * Node.js® https servers (including Express.js, etc.)
- *
- * 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.
- *
- * @module @small-tech/auto-encrypt
- * @copyright © 2020 Aral Balkan, Small Technology Foundation.
- * @license AGPLv3 or later.
+  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 os from 'os'
 import util from 'util'
 import https from 'https'
-import ocsp from 'ocsp'
 import monkeyPatchTls from './lib/staging/monkeyPatchTls.js'
 import LetsEncryptServer from './lib/LetsEncryptServer.js'
 import Configuration from './lib/Configuration.js'
 import Certificate from './lib/Certificate.js'
+import AcmeRequest from './lib/AcmeRequest.js'
 import Pluralise from './lib/util/Pluralise.js'
 import Throws from './lib/util/Throws.js'
 import HttpServer from './lib/HttpServer.js'
+import IPAddresses from './lib/IPAddresses.js'
 import log from './lib/util/log.js'
 
-// This reverts IP address sort order to pre-Node 17 behaviour.
-// See https://github.com/nodejs/node/issues/40537
-import dns from 'node:dns'
-dns.setDefaultResultOrder('ipv4first')
+// Use module-level await to ensure we have the IP address information we need.
+const ipAddresses = await IPAddresses.getInstanceAsync()
 
 // Custom errors thrown by the autoEncrypt function.
 const throws = new Throws({
   [Symbol.for('BusyProvisioningCertificateError')]:
     () => 'We’re busy provisioning TLS certificates and rejecting all other calls at the moment.',
 
+  [Symbol.for('IPv4AddressNotFound')]:
+    () => 'IPv4 certificate requested but could not automatically find machine’s IPv4 address',
+
+  [Symbol.for('IPv6AddressNotFound')]:
+    () => 'IPv6 certificates requested but could not automatically find any stable IPv6 addresses',
+
   [Symbol.for('SNIIgnoreUnsupportedDomainError')]:
-    (serverName, domains) => {
+    (/** @type {string} */ serverName, /** @type {Array<string>} */ domains) => {
       return `SNI: Not responding to request for unsupported domain ${serverName} (valid ${Pluralise.word('domain', domains)} ${Pluralise.isAre(domains)} ${domains}).`
     }
 })
 
 /**
- * Auto Encrypt is a static class. Please do not instantiate.
- *
- * Use: AutoEncrypt.https.createServer(…)
- *
- * @alias module:@small-tech/auto-encrypt
- * @hideconstructor
- */
+  @typedef {import('./index.d.ts').AutoEncryptedServer} AutoEncryptedServer
+*/
+
+/**
+  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 {
+  /** @type { AutoEncryptedServer } */
+  static server = null
+
+  /** @type { import('./lib/LetsEncryptServer.js').default | null } */
   static letsEncryptServer = null
+
+  /** @type { string[] | null } */
   static defaultDomains    = null
+
+  /** @type { string[] | null } */
   static domains           = null
+
+  /** @type { string | null } */
   static settingsPath      = null
+
+  /** @type { ((req: import('http').IncomingMessage, res: import('http').ServerResponse) => void) | null } */
   static listener          = null
+
+  /** @type { Certificate | null } */
   static certificate       = null
 
   /**
-   * Enumeration.
-   *
-   * @type {LetsEncryptServer.type}
-   * @readonly
-   * @static
-   */
+    Enumeration.
+
+    @type {LetsEncryptServer.type}
+    @readonly
+    @static
+  */
   static serverType = LetsEncryptServer.type
 
   /**
-   * 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 get https () { return AutoEncrypt }
+    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 await AutoEncrypt:
 
+    @example import AutoEncrypt from '@small-tech/auto-encrypt'
+    const server = await AutoEncrypt.https.createServer()
 
-  static ocspCache = null
+    @static
+  */
+  static get https () { return 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 {Object}   [options]               Optional HTTPS options object with optional additional
-   *                                           Auto Encrypt-specific configuration settings.
-   * @param {String[]} [options.domains]       Domain names to provision TLS certificates for. If missing, defaults to
-   *                                           the hostname of the current computer and its www prefixed subdomain.
-   * @param {Enum}     [options.serverType=AutoEncrypt.serverType.PRODUCTION] Let’s Encrypt server type to use.
-   *                                                                  AutoEncrypt.serverType.PRODUCTION, ….STAGING,
-   *                                                                  or ….PEBBLE (see LetsEncryptServer.type).
-   * @param {String}   [options.settingsPath=~/.small-tech.org/auto-encrypt/] Path to save certificates/keys to.
-   *
-   * @returns {https.Server} The server instance returned by Node’s https.createServer() method.
-   */
-  static createServer(_options, _listener) {
+    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 {import('tls').SecureContextOptions & {
+      domains?: Array<string>,
+      serverType?: number,
+      settingsPath?: string,
+      ipv4?: boolean,
+      ipv6?: boolean,
+      ipOnly?: boolean,
+      SNICallback?: (serverName: string, callback: (...args: any[]) => void) => Promise<void> | void
+    } | ((...any: any[]) => void)} _options
+    
+    @param {(...any: any[]) => void} [_listener]
+
+    @returns {Promise<import('./index.d.ts').AutoEncryptedServer>} A promise for the server instance (a monkey-patched https.Server similar to the one returned by Node’s https.createServer() method).
+  */
+  static async createServer(_options, _listener) {
+    //  Auto Encrypt only supports one server per Node process. As such, if the server already exists, return the existing instance.
+    if (this.server !== null) {
+      log('   ☝️    ❨auto-encrypt❩ Returning reference to existing server (there can be only one… per process).')
+      return this.server
+    }
+
     // The first parameter is optional. If omitted, the first argument, if any, is treated as the request listener.
     if (typeof _options === 'function') {
       _listener = _options
       _options = {}
     }
 
-    const defaultStagingAndProductionDomains = [os.hostname(), `www.${os.hostname()}`]
-    const defaultPebbleDomains               = ['localhost', 'pebble']
+    const defaultPebbleDomains               = []
     const options                            = _options || {}
     const letsEncryptServer                  = new LetsEncryptServer(options.serverType || LetsEncryptServer.type.PRODUCTION)
     const listener                           = _listener || null
     const settingsPath                       = options.settingsPath || null
 
-    //
-    // Ignore passed domains (if any) if we’re using pebble as we can only issue for localhost and pebble.
-    //
+    let defaultStagingAndProductionDomains = []
+    if (!options.ipOnly) {
+      defaultStagingAndProductionDomains.push(os.hostname())
+      defaultPebbleDomains.push('localhost')
+      defaultPebbleDomains.push('pebble')
+    }
+
+    if (options.ipv4 === true) {
+      if (letsEncryptServer.type === LetsEncryptServer.type.PEBBLE) {
+        const localIPv4Address = '127.0.0.1'
+        defaultPebbleDomains.push(localIPv4Address)
+        log(`   📍    ❨auto-encrypt❩ Will provision TLS certificate from Pebble server for local IPv4 address (${localIPv4Address})`)
+      } else {
+        if (ipAddresses.hasIPv4Address) {
+          const ipv4Address = ipAddresses.ipv4Address
+          defaultStagingAndProductionDomains.push(ipv4Address)
+          log(`   📍    ❨auto-encrypt❩ Will provision TLS certificate for detected IPv4 address: ${ipv4Address}`)
+        } else {
+          throws.error(Symbol.for('IPv4AddressNotFound'))
+        }
+      }
+    }
+
+    if (options.ipv6 === true) {
+      if (letsEncryptServer.type === LetsEncryptServer.type.PEBBLE) {
+        // IPv6: Pebble.
+        const localIPv6Address = '::1'
+        defaultPebbleDomains.push(localIPv6Address)
+        log(`   📍    ❨auto-encrypt❩ Will provision TLS certificate from Pebble server for local IPv6 address (${localIPv6Address})`)
+      } else {
+        // IPv6:  Staging and production.
+        const ipv6Addresses = ipAddresses.ipv6Addresses
+        if (ipv6Addresses.length > 0) {
+          defaultStagingAndProductionDomains = defaultStagingAndProductionDomains.concat(ipv6Addresses)
+          ipv6Addresses.forEach(ipv6Address => defaultPebbleDomains.push(ipv6Address))
+          log(`   📍    ❨auto-encrypt❩ Will provision TLS certificate for detected stable IPv6 address${ipv6Addresses.length > 1 ? 'es' : ''}: ${ipv6Addresses}`)
+        } else {
+          throws.error(Symbol.for('IPv6AddressNotFound'))
+        }
+      }
+    }
+
     let defaultDomains = defaultStagingAndProductionDomains
 
+    // Behaviour specific to Let’s Encrypt server type (Pebble/staging).
     switch (letsEncryptServer.type) {
       case LetsEncryptServer.type.PEBBLE:
         options.domains = null
         defaultDomains = defaultPebbleDomains
       break
 
-      // If this is a staging server, we add the intermediary certificate to Node.js’s trust store (only valid during
-      // the current Node.js process) so that Node will accept the certificate. Useful when running tests against the
-      // staging server.
-      //
-      // If you’re using Pebble for your tests, please install and use node-pebble manually in your tests.
-      // (We cannot automatically provide support for Pebble as it dynamically generates its root and
-      // intermediary CA certificates, which is an asynchronous process whereas the createServer method is
-      // synchronous.)*
-      //
-      // * Yes, we could check for and start the Pebble server in the asynchronous SNICallback, below, but given how
-      // often that function is called, I will not add anything to it beyond the essentials for performance reasons.
       case LetsEncryptServer.type.STAGING:
+        // Add the intermediary certificate to Node.js’s trust store (only valid during the current Node.js process) so that Node will accept the certificate. Useful when running tests against the staging server.
         monkeyPatchTls()
       break
     }
@@ -144,6 +208,9 @@ export default class AutoEncrypt {
     delete options.domains
     delete options.serverType
     delete options.settingsPath
+    delete options.ipv4
+    delete options.ipv6
+    delete options.ipOnly
 
     const configuration = new Configuration({ settingsPath, domains, server: letsEncryptServer})
     const certificate = new Certificate(configuration)
@@ -155,159 +222,107 @@ export default class AutoEncrypt {
     this.listener          = listener
     this.certificate       = certificate
 
-    function sniError (symbolName, callback, emoji, ...args) {
-      const error = Symbol.for(symbolName)
-      log(`   ${emoji}    ❨auto-encrypt❩ ${throws.errors[error](...args)}`)
-      callback(throws.createError(error, ...args))
-    }
+    // Start HTTP server.
+    log('   🌍    ❨auto-encrypt❩ Starting HTTP challenge responder server…')
+    await HttpServer.getSharedInstance()
 
-    options.SNICallback = async (serverName, callback) => {
-      if (domains.includes(serverName)) {
-        const secureContext = await certificate.getSecureContext()
-        if (secureContext === null) {
-          sniError('BusyProvisioningCertificateError', callback, '⏳')
-          return
-        }
-        callback(null, secureContext)
-      } else {
-        sniError('SNIIgnoreUnsupportedDomainError', callback, '🤨', serverName, domains)
-      }
-    }
+    // Provision certificate (if required).
+    log(`   📃    ❨auto-encrypt❩ Provisioning certificate (if required) for domains: ${domains.join(', ')}…`)
+    await certificate.getSecureContext()
+    log('   ✅    ❨auto-encrypt❩ Certificate provisioned (or already exists).')
 
-    const shouldAddOcspMustStaple = certificate.hasOcspMustStaple || false
+    // Pass the certificate and key to the https.createServer options as well.
+    // This is required for IP hits (which don't use SNI) and also acts as the 
+    // default certificate.
+    options.key = certificate.key
+    options.cert = certificate.pem
 
-    // During the transitionary period where Let’s Encrypt has shut down
-    // OCSP support but there are still servers out there with certificates
-    // that have OCSP stapling because their 6-month validity period isn’t
-    // over, we create the server accordingly based on whether the certificate
-    // has OCSP stapling or not so it works for both cases.
-    // TODO: OCSP support can be fully removed in August 2025. All existing
-    // servers with valid certificates will be non-OCSP at that point.
-    const serverWithoutOcspMustStaple = https.createServer(options, listener)
-     const server = shouldAddOcspMustStaple
-     ? this.addOcspStapling(serverWithoutOcspMustStaple)
-     : serverWithoutOcspMustStaple
+    // Create node:https server.
+    const server = /** @type {import('./index.d.ts').AutoEncryptedServer} */ (/** @type {unknown} */ (https.createServer(options, listener)))
+    this.server = server
 
     //
-    // Monkey-patch the server.
+    // Monkey-patch server.
     //
 
-    server.__autoEncrypt__self = this
-
-    // Monkey-patch the server’s listen method so that we can start up the HTTP
-    // Server at the same time.
-    server.__autoEncrypt__originalListen = server.listen
-    server.listen = function(...args) {
-      // Start the HTTP server.
-      HttpServer.getSharedInstance().then(() => {
-        // Start the HTTPS server.
-        return this.__autoEncrypt__originalListen.apply(this, args)
+    /**
+      Auto Encrypt’s async version of Node’s built-in `https.listen()` method.
+
+      You can use this method with exactly the same signature as Node’s and
+      with a callback but, ideally, you should be awaiting it and not using the callback.
+    
+      @param {...*} args - Arguments to pass to https.Server.listen()
+      @returns {Promise<AutoEncryptedServer>}
+    */
+    const listenAsync = async function (...args) {
+      return new Promise((resolve, reject) => {
+        const server = this['__original_listen__'](...args)
+          .once('listening', () => resolve(server))
+          .once('error', reject)
       })
     }
-
-
-    // Monkey-patch the server’s close method so that we can perform clean-up and
-    // also shut down the HTTP server transparently when server.close() is called.
-    server.__autoEncrypt__originalClose = server.close
-    server.close = function (...args) {
+    server['__original_listen__'] = server.listen.bind(server)
+    server.listen = listenAsync.bind(server)
+
+    /**
+      Auto Encrypt Localhost’s async version of Node’s built-in `https.close()` method.
+
+      Unlike Node’s `close()` method, this version also calls `closeAllConnections()` so it
+      will sever any existing idle and active connections. When `await`ed, this call will
+      only return once `node:https`’s close callback is called. This is also where your
+      callback will fire, if you are using Node’s original method signature will callbacks.
+
+      You can still use this method with exactly the same signature as Node’s and
+      with a callback but, ideally, you should be awaiting it and not using the callback.
+    
+      @returns {Promise<void>}
+    */
+    const closeAsync = async function () {
       // Clean-up our own house.
-      this.__autoEncrypt__self.shutdown()
-
-      // Shut down the HTTP server.
-      HttpServer.destroySharedInstance().then(() => {
-        // Shut down the HTTPS server.
-        return this.__autoEncrypt__originalClose.apply(this, args)
+      await AutoEncrypt.shutdown()
+
+      // Start shutting down the HTTPS server.
+      const closePromise = new Promise((resolve, reject) => {
+        this['__original_close__']((/** @type { Error } */ error) => {
+          if (error) {
+            reject(error)
+          } else {
+            resolve()
+          }
+        })
       })
-    }
-
-    return server
-  }
 
+      // Sever all idle and active connections.
+      this.closeAllConnections()
 
-  /**
-   * The OCSP module does not have a means of clearing its cache check timers
-   * so we do it here. (Otherwise, the test suite would hang.)
-   */
-  static clearOcspCacheTimers () {
-    if (this.ocspCache !== null) {
-      const cacheIds = Object.keys(this.ocspCache.cache)
-      cacheIds.forEach(cacheId => {
-        clearInterval(this.ocspCache.cache[cacheId].timer)
-      })
+      // Only now await the promise.
+      // (See note at: https://nodejs.org/docs/latest-v24.x/api/http.html#servercloseallconnections)
+      await closePromise
     }
-  }
+    server['__original_close__'] = server.close.bind(server)
+    server.close = closeAsync.bind(server)
 
+    // Return the server singleton.
+    return this.server
+  }
+  
   /**
-   * 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 shutdown () {
-    this.clearOcspCacheTimers()
-    this.certificate.stopCheckingForRenewal()
+    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 () {
+    if (this.certificate) {
+      this.certificate.stopCheckingForRenewal()
+    }
+    await HttpServer.destroySharedInstance()
+    AcmeRequest.uninitialise()
+    this.server = null
   }
 
   //
   // Private.
   //
 
-  /**
-   * Adds Online Certificate Status Protocol (OCSP) stapling (also known as TLS Certificate Status Request extension)
-   * support to the passed server instance.
-   *
-   * @private
-   * @param {https.Server} server HTTPS server instance without OCSP Stapling support.
-   * @returns {https.Server} HTTPS server instance with OCSP Stapling support.
-   */
-  static addOcspStapling(server) {
-    // OCSP stapling
-    //
-    // Many browsers will fetch OCSP from Let’s Encrypt when they load your site. This is a performance and privacy
-    // problem. Ideally, connections to your site should not wait for a secondary connection to Let’s Encrypt. Also,
-    // OCSP requests tell Let’s Encrypt which sites people are visiting. We have a good privacy policy and do not record
-    // individually identifying details from OCSP requests, we’d rather not even receive the data in the first place.
-    // Additionally, we anticipate our bandwidth costs for serving OCSP every time a browser visits a Let’s Encrypt site
-    // for the first time will be a big part of our infrastructure expense.
-    //
-    // By turning on OCSP Stapling, you can improve the performance of your website, provide better privacy protections
-    // … and help Let’s Encrypt efficiently serve as many people as possible.
-    //
-    // (Source: https://letsencrypt.org/docs/integration-guide/implement-ocsp-stapling)
-
-    this.ocspCache = new ocsp.Cache()
-    const cache = this.ocspCache
-
-    server.on('OCSPRequest', (certificate, issuer, callback) => {
-
-      if (certificate == null) {
-        return callback(new Error('Cannot OCSP staple: certificate not yet provisioned.'))
-      }
-
-      ocsp.getOCSPURI(certificate, function(error, uri) {
-        if (error) return callback(error)
-        if (uri === null) return callback()
-
-        const request = ocsp.request.generate(certificate, issuer)
-
-        cache.probe(request.id, (error, cached) => {
-          if (error) return callback(error)
-
-          if (cached !== false) {
-            return callback(null, cached.response)
-          }
-
-          const options = {
-            url: uri,
-            ocsp: request.data
-          }
-
-          cache.request(request.id, options, callback);
-        })
-      })
-    })
-
-    return server
-  }
-
   // Custom object description for console output (for debugging).
   static [util.inspect.custom] () {
     return `

package/lib/Account.js

@@ -1,18 +1,10 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// Account
-//
-// (Async; please use Account.getInstanceAsync() factory method.)
-//
-// Represents a Let’s Encrypt account. Currently this is limited to the account
-// URL used as the "kid" value in the JWS authenticating subsequent requests
-// by this account after it is created using the JWT public key.
-// See RFC 8555 § 6.2, 7.3.
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  Represents a Let’s Encrypt account. 
+
+ @module
+ @copyright Copyright © 2020-present Aral Balkan, Small Technology Foundation.
+ @license AGPLv3 or later.
+*/
 
 import fs from 'fs'
 import Throws from './util/Throws.js'
@@ -22,11 +14,23 @@ const throws = new Throws({
   // No custom errors are thrown by this class.
 })
 
+/**
+  (Async; please use Account.getInstanceAsync() factory method.)
+
+  Represents a Let’s Encrypt account. Currently this is limited to the account
+  URL used as the "kid" value in the JWS authenticating subsequent requests
+  by this account after it is created using the JWT public key.
+  See RFC 8555 § 6.2, 7.3.
+
+  @alias module:lib/Account
+*/
 export default class Account {
-  //
-  // Async factory method.
-  //
+  /**
+    Async static factory method. __Use this to instantiate, not the constructor.__
 
+    @param { import('./Configuration.js').default } configuration
+    @public
+  */
   static async getInstanceAsync (configuration) {
       Account.isBeingInstantiatedViaSingletonFactoryMethod = true
       const account = new Account(configuration)
@@ -39,6 +43,10 @@ export default class Account {
   //
   static isBeingInstantiatedViaSingletonFactoryMethod = false
 
+  /**
+    @private
+    @param { import('./Configuration.js').default } configuration
+  */
   constructor (configuration) {
     // Ensure factory method-based initialisation.
     if (Account.isBeingInstantiatedViaSingletonFactoryMethod === false) {
@@ -61,7 +69,7 @@ export default class Account {
     }
   }
 
-  // TODO: throw error if Account has not been initialised instead of crashing in getter below.
+  /** @type { string } */
   get kid ()      { return this.data.kid                                     }
-  set kid (value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'kid') }
+  set kid (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'kid') }
 }