@small-tech/auto-encrypt 4.3.0 → 5.0.1

package/lib/Configuration.js

@@ -1,11 +1,11 @@
 /**
- * Global configuration class. Use initialise() method to populate.
- *
- * @module lib/Configuration
- * @exports Configuration
- * @copyright © 2020 Aral Balkan, Small Technology Foundation.
- * @license AGPLv3 or later.
- */
+  Global configuration class. Use initialise() method to populate.
+
+  @module lib/Configuration
+  @exports Configuration
+  @copyright © 2020 Aral Balkan, Small Technology Foundation.
+  @license AGPLv3 or later.
+*/
 
 import os from 'os'
 import fs from 'fs'
@@ -21,11 +21,17 @@ const throws = new Throws({
     () => 'Domains array must be an array of strings'
 })
 
+/**
+ * @param {any[]} object
+ */
 function isAnArrayOfStrings (object) {
-  const containsOnlyStrings = arrayOfStrings => arrayOfStrings.length !== 0 && arrayOfStrings.filter(s => typeof s === 'string').length === arrayOfStrings.length
+  const containsOnlyStrings = (/** @type {any[]} */ arrayOfStrings) => arrayOfStrings.length !== 0 && arrayOfStrings.filter(s => typeof s === 'string').length === arrayOfStrings.length
   return Array.isArray(object) && containsOnlyStrings(object)
 }
 
+/**
+ * @param {fs.PathLike} directory
+ */
 function ensureDirSync (directory) {
   if (!fs.existsSync(directory)) {
     fs.mkdirSync(directory, { recursive: true })
@@ -33,9 +39,9 @@ function ensureDirSync (directory) {
 }
 
 /**
- * @alias module:lib/Configuration
- * @hideconstructor
- */
+  @alias module:lib/Configuration
+  @hideconstructor
+*/
 export default class Configuration {
   #server = null
   #domains = null
@@ -47,35 +53,42 @@ export default class Configuration {
   #certificateIdentityPath = null
 
   /**
-   * Initialise the configuration. Must be called before accessing settings. May be called more than once.
-   *
-   * @param {Object}            settings                   Settings to initialise configuration with.
-   * @param {String[]}          settings.domains           List of domains Auto Encrypt will manage TLS certs for.
-   * @param {LetsEncryptServer} settings.server            Let’s Encrypt Server to use.
-   * @param {String}            settings.settingsPath      Root settings path to use. Will use default path if null.
-   */
+    Initialise the configuration. Must be called before accessing settings. May be called more than once.
+
+    @typedef { import('./LetsEncryptServer.js').default } LetsEncryptServer
+
+    @typedef {{
+      domains: string[],
+      server: LetsEncryptServer,
+      settingsPath: string
+    }} Settings
+
+    @param {Settings | void} settings
+  */
   constructor (settings = throws.ifMissing()) {
 
+    const __settings = /** @type { Settings } */ (settings)
+
     // Additional argument validation.
-    throws.ifUndefinedOrNull(settings.server, 'settings.server')
-    throws.ifUndefined(settings.settingsPath, 'settings.settingsPath')
-    throws.if(!isAnArrayOfStrings(settings.domains), Symbol.for('Configuration.domainsArrayIsNotAnArrayOfStringsError'))
+    throws.ifUndefinedOrNull(__settings.server, 'settings.server')
+    throws.ifUndefined(__settings.settingsPath, 'settings.settingsPath')
+    throws.if(!isAnArrayOfStrings(__settings.domains), Symbol.for('Configuration.domainsArrayIsNotAnArrayOfStringsError'))
 
-    if (!util.inspect(settings.server).includes('Let’s Encrypt Server (instance)')) {
+    if (!util.inspect(__settings.server).includes('Let’s Encrypt Server (instance)')) {
       throws.error(Symbol.for('ArgumentError'), 'settings.server', 'must be an instance of LetsEncryptServer but isn’t')
     }
 
-    this.#server = settings.server
-    this.#domains = settings.domains
+    this.#server = __settings.server
+    this.#domains = __settings.domains
 
-    const defaultPathFor = serverName => path.join(os.homedir(), '.small-tech.org', 'auto-encrypt', serverName)
+    const defaultPathFor = (/** @type {string} */ serverName) => path.join(os.homedir(), '.small-tech.org', 'auto-encrypt', serverName)
 
-    if (settings.settingsPath === null) {
+    if (__settings.settingsPath === null) {
       // Use the correct default path based on staging state.
       this.#settingsPath = defaultPathFor(this.#server.name)
     } else {
       // Create the path to use based on the custom root path we’ve been passed.
-      this.#settingsPath = path.join(settings.settingsPath, this.#server.name)
+      this.#settingsPath = path.join(__settings.settingsPath, this.#server.name)
     }
 
     // And ensure that the settings path exists in the file system.
@@ -104,7 +117,7 @@ export default class Configuration {
         // For more than 5 domains, show the first two, followed by the number of domains, and a
         // hash to ensure that the directory name is unique.
         // e.g., ar.al--www.ar.al--and--4--others--9364bd18ea526b3462e4cebc2a6d97c2ffd3b5312ef7b8bb6165c66a37975e46
-        const hashOf = arrayOfStrings => crypto.createHash('blake2s256').update(arrayOfStrings.join('--')).digest('hex')
+        const hashOf = (/** @type {string[]} */ arrayOfStrings) => crypto.createHash('blake2s256').update(arrayOfStrings.join('--')).digest('hex')
         return domains.slice(0, 2).join('--').concat(`--and--${domains.length-2}--others--${hashOf(domains)}`)
       }
     })(this.#domains)
@@ -125,91 +138,94 @@ export default class Configuration {
   //
 
   /**
-   * The Let’s Encrypt Server instance.
-   *
-   * @type {LetsEncryptServer}
-   * @readonly
-   */
+    The Let’s Encrypt Server instance.
+
+    @type {LetsEncryptServer}
+    @readonly
+  */
   get server () {
     return this.#server
   }
 
   /**
-   * List of domains that Auto Encrypt will manage TLS certificates for.
-   *
-   * @type {String[]}
-   * @readonly
-   */
+    List of domains that Auto Encrypt will manage TLS certificates for.
+
+    @type {String[]}
+    @readonly
+  */
   get domains () {
     return this.#domains
   }
 
   /**
-   * The root settings path. There is a different root settings path for pebble, staging and production modes.
-   *
-   * @type {String}
-   * @readonly
-   */
+    The root settings path. There is a different root settings path for pebble, staging and production modes.
+
+    @type {String}
+    @readonly
+  */
   get settingsPath () {
     return this.#settingsPath
   }
 
   /**
-   * Path to the account.json file that contains the Key Id that uniquely identifies and authorises your account
-   * in the absence of a JWT (see RFC 8555 § 6.2. Request Authentication).
-   *
-   * @type {String}
-   * @readonly
-   */
+    Path to the account.json file that contains the Key Id that uniquely identifies and authorises your account
+    in the absence of a JWT (see RFC 8555 § 6.2. Request Authentication).
+
+    @type {String}
+    @readonly
+  */
   get accountPath () {
     return this.#accountPath
   }
 
   /**
-   * The path to the account-identity.pem file that contains the private key for the account.
-   *
-   * @type {String}
-   * @readonly
-   */
+    The path to the account-identity.pem file that contains the private key for the account.
+
+    @type {String}
+    @readonly
+  */
   get accountIdentityPath () { return this.#accountIdentityPath }
 
   /**
-   * The path to the certificate.pem file that contains the certificate chain provisioned from Let’s Encrypt.
-   *
-   * @type {String}
-   * @readonly
-   */
+    The path to the certificate.pem file that contains the certificate chain provisioned from Let’s Encrypt.
+
+    @type {String}
+    @readonly
+  */
   get certificatePath () { return this.#certificatePath }
 
   /**
-   * The directory the certificate and certificate identity (private key) PEM files are stored in.
-   *
-   * @type {String}
-   * @readonly
-   */
+    The directory the certificate and certificate identity (private key) PEM files are stored in.
+
+    @type {String}
+    @readonly
+  */
   get certificateDirectoryPath () { return this.#certificateDirectoryPath }
 
   /**
-   * The path to the certificate-identity.pem file that holds the private key for the TLS certificate.
-   *
-   * @type {String}
-   * @readonly
-   */
+    The path to the certificate-identity.pem file that holds the private key for the TLS certificate.
+
+    @type {String}
+    @readonly
+  */
   get certificateIdentityPath () { return this.#certificateIdentityPath }
 
   //
   // Enforce read-only access.
   //
 
-  set server                   (state) { this.throwReadOnlyAccessorError('server')                   }
-  set domains                  (state) { this.throwReadOnlyAccessorError('domains')                  }
-  set settingsPath             (state) { this.throwReadOnlyAccessorError('settingsPath')             }
-  set accountPath              (state) { this.throwReadOnlyAccessorError('accountPath')              }
-  set accountIdentityPath      (state) { this.throwReadOnlyAccessorError('accountIdentityPath')      }
-  set certificatePath          (state) { this.throwReadOnlyAccessorError('certificatePath')          }
-  set certificateDirectoryPath (state) { this.throwReadOnlyAccessorError('certificateDirectoryPath') }
-  set certificateIdentityPath  (state) { this.throwReadOnlyAccessorError('certificateIdentityPath')  }
+  set server                   (_state) { this.throwReadOnlyAccessorError('server')                   }
+  set domains                  (_state) { this.throwReadOnlyAccessorError('domains')                  }
+  set settingsPath             (_state) { this.throwReadOnlyAccessorError('settingsPath')             }
+  set accountPath              (_state) { this.throwReadOnlyAccessorError('accountPath')              }
+  set accountIdentityPath      (_state) { this.throwReadOnlyAccessorError('accountIdentityPath')      }
+  set certificatePath          (_state) { this.throwReadOnlyAccessorError('certificatePath')          }
+  set certificateDirectoryPath (_state) { this.throwReadOnlyAccessorError('certificateDirectoryPath') }
+  set certificateIdentityPath  (_state) { this.throwReadOnlyAccessorError('certificateIdentityPath')  }
 
+  /**
+     * @param {string} setterName
+     */
   throwReadOnlyAccessorError (setterName) {
     throws.error(Symbol.for('ReadOnlyAccessorError'), setterName, 'All configuration accessors are read-only.')
   }

package/lib/Directory.js

@@ -1,18 +1,15 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// Directory
-//
-// In order to help clients configure themselves with the right URLs for
-// each ACME operation, ACME servers provide a directory object.  This
-// should be the only URL needed to configure clients. (RFC §7.1.1)
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  Directory
+
+  In order to help clients configure themselves with the right URLs for
+  each ACME operation, ACME servers provide a directory object.  This
+  should be the only URL needed to configure clients. (RFC §7.1.1)
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import util from 'util'
-import prepareRequest from 'bent'
 import log from './util/log.js'
 import Throws from './util/Throws.js'
 
@@ -21,16 +18,18 @@ const throws = new Throws()
 export default class Directory {
   directory         = null
   letsEncryptServer = null
-  directoryRequest  = null
 
   //
   // Factory method access (async).
   //
   static isBeingInstantiatedViaAsyncFactoryMethod = false
 
+  /**
+    @param {import('./Configuration.js').default|void} configuration
+  */
   static async getInstanceAsync (configuration = throws.ifMissing()) {
     Directory.isBeingInstantiatedViaAsyncFactoryMethod = true
-    const directory = new Directory(configuration)
+    const directory = new Directory(/** @type {import('./Configuration.js').default} */ (configuration))
     await directory.getUrls()
     return directory
   }
@@ -47,11 +46,16 @@ export default class Directory {
   get revokeCertUrl()     { return this.directory.revokeCert }
   get termsOfServiceUrl() { return this.directory.meta.termsOfService }
   get websiteUrl()        { return this.directory.meta.website        }
+  get renewalInfoUrl()    { return this.directory.renewalInfo         }
+  get profiles()          { return this.directory.meta.profiles       }
 
   //
   // Private.
   //
 
+  /**
+    @param {import('./Configuration.js').default} configuration
+  */
   constructor(configuration) {
     // Ensure async factory method instantiation.
     if (Directory.isBeingInstantiatedViaAsyncFactoryMethod === false) {
@@ -60,7 +64,6 @@ export default class Directory {
     Directory.isBeingInstantiatedViaAsyncFactoryMethod = false
 
     this.letsEncryptServer = configuration.server
-    this.directoryRequest = prepareRequest('GET', 'json', this.letsEncryptServer.endpoint)
 
     log(`   📕    ❨auto-encrypt❩ Directory is using endpoint ${this.letsEncryptServer.endpoint}`)
   }
@@ -68,7 +71,13 @@ export default class Directory {
   // (Async) Fetches the latest Urls from the Let’s Encrypt ACME endpoint being used.
   // This will throw if the request fails. Ensure that you catch the error when
   // using it.
-  async getUrls() { this.directory = await this.directoryRequest() }
+  async getUrls() {
+    const response = await fetch(this.letsEncryptServer.endpoint)
+    if (!response.ok) {
+      throw new Error(`HTTP Error: ${response.status} ${response.statusText}`)
+    }
+    this.directory = await response.json()
+  }
 
   // Custom object description for console output (for debugging).
   [util.inspect.custom] () {
@@ -86,6 +95,8 @@ export default class Directory {
       - revokeCertUrl    : ${this.revokeCertUrl}
       - termsOfServiceUrl: ${this.termsOfServiceUrl}
       - websiteUrl       : ${this.websiteUrl}
+      - renewalInfoUrl   : ${this.renewalInfoUrl}
+      - profiles         : ${Object.entries(this.profiles).map(([key, value], index) => `${index > 0 ? ', ' : ''}${key} (${value})`)}
     `
   }
 }

package/lib/HttpServer.js

@@ -1,29 +1,27 @@
+/**
 
-////////////////////////////////////////////////////////////////////////////////
-//
-// HttpServer
-//
-// (Singleton; please use HttpServer.getSharedInstance() to access.)
-//
-// A simple HTTP server that:
-//
-//   A. While provisioning Let’s Encrypt certificates:
-//   =================================================
-//
-//   Acts as a challenge server. See RFC 8555 § 8.3 (HTTP Challenge)
-//
-//   Responds to http-01 challenges and forwards all other
-//   requests to an HTTPS server that it expects to be active at the same domain.
-//
-//   B. At all other times:
-//   ======================
-//
-//   Forwards http requests to https requests using a 307 redirect.
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+  HttpServer
+
+  (Singleton; please use HttpServer.getSharedInstance() to access.)
+
+  A simple HTTP server that:
+
+   A. While provisioning Let’s Encrypt certificates:
+   =================================================
+
+   Acts as a challenge server. See RFC 8555 § 8.3 (HTTP Challenge)
+
+   Responds to http-01 challenges and forwards all other
+   requests to an HTTPS server that it expects to be active at the same domain.
+
+   B. At all other times:
+   ======================
+
+   Forwards http requests to https requests using a 307 redirect.
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import http from 'http'
 import encodeUrl from 'encodeurl'
@@ -33,12 +31,18 @@ export default class HttpServer {
   //
   // Singleton access (async).
   //
+  /** @type { HttpServer } */
   static instance = null
   static isBeingInstantiatedViaSingletonFactoryMethod = false
 
   // Is the HTTP server acting as a Let’s Encrypt challenge server?
   #isChallengeServer = false
 
+  /** @typedef { (request: http.IncomingMessage, response: http.ServerResponse) => Boolean } Responder
+
+  /** @type Array<Responder> */
+  responders
+
   static async getSharedInstance () {
     if (HttpServer.instance === null) {
       HttpServer.isBeingInstantiatedViaSingletonFactoryMethod = true
@@ -59,6 +63,11 @@ export default class HttpServer {
     log('   🚮    ❨auto-encrypt❩ HTTP Server is destroyed.')
   }
 
+  /**
+    Adds a responder to this server’s responders list.
+
+    @param { Responder } responder
+  */
   addResponder (responder) {
     this.responders.push(responder)
   }
@@ -85,6 +94,8 @@ export default class HttpServer {
         // Act as a Let’s Encrypt challenge server.
         let responded = false
 
+        log(`   📥    ❨auto-encrypt❩ Received HTTP request: ${request.url} on ${request.headers.host}`)
+
         for (let i = 0; i < this.responders.length; i++) {
           const responder = this.responders[i]
           responded = responder(request, response)
@@ -113,14 +124,19 @@ export default class HttpServer {
         }
 
         // Redirect HTTP to HTTPS.
-        log(`   👉    ❨auto-encrypt❩ Redirecting HTTP request to HTTPS.`)
+        log(`   👉    ❨auto-encrypt❩ Redirecting HTTP request to HTTPS: ${httpsUrl.toString()}`)
         response.statusCode = 307
-        response.setHeader('Location', encodeUrl(httpsUrl))
+        response.setHeader('Location', encodeUrl(httpsUrl.toString()))
         response.end()
       }
     })
   }
 
+  /**
+    Sets the state of the server (either to challenge server (true) or to HTTP -> HTTPS forwarding server (false)).
+
+    @param { Boolean } state
+  */
   set challengeServer (state) {
     if (state) {
       log(`   🔒    ❨auto-encrypt❩ HTTP server is now only responding to Let’s Encrypt challenges.`)
@@ -138,7 +154,8 @@ export default class HttpServer {
     // vulnerability at worst in the global digital network age.
     await new Promise((resolve, reject) => {
       try {
-        this.server.listen(80, () => {
+        // Listen on all IP addresses, including IPv6.
+        this.server.listen(80, '::', () => {
           log(`   🔒    ❨auto-encrypt❩ HTTP server is listening on port 80.`)
           resolve()
         })
@@ -149,12 +166,22 @@ export default class HttpServer {
   }
 
   async destroy () {
+    if (!this.server.listening) {
+      log('   🚮    ❨auto-encrypt❩ HTTP Server is not listening. Nothing to destroy.')
+      return
+    }
+
     // Starts killing all connections and closes the server.
     this.server.closeAllConnections()
 
     await new Promise((resolve, reject) => {
       this.server.close(error => {
         if (error) {
+          // If the server was already closed or not running, we don't want to throw an error.
+          if (error.code === 'ERR_SERVER_NOT_RUNNING') {
+            resolve()
+            return
+          }
           console.error(error)
           reject(error)
         }

package/lib/IPAddresses.js

@@ -0,0 +1,114 @@
+/**
+  Gathers external IPv4 address information using https://ip.small-web.org/
+
+  And Ipv6 information using built-in `networkInterfaces` function from node:os.
+*/
+
+import os from 'node:os'
+import dns from 'node:dns'
+import { execSync } from 'node:child_process'
+import Throws from './util/Throws.js'
+
+const throws = new Throws()
+
+export default class IPAddresses {
+  /** @type {IPAddresses} */
+  static instance
+
+  static extractIPv6Address = "sed -n 's/.*inet6 \\([a-f0-9:]*\\).*/\\1/p'"
+  static platformSpecificStableIPv6DiscoveryCommands = {
+    'linux': `ip -6 address show scope global | grep -v 'temporary' | ${IPAddresses.extractIPv6Address}`,
+    'darwin': `ifconfig | grep 'inet6' | grep 'secured' | grep -v 'fe80:' | ${IPAddresses.extractIPv6Address}`
+  }
+
+  /** @type {string|undefined} */
+  ipv4Address
+
+  /** @type {Array<string>} */
+  ipv6Addresses = []
+
+  //
+  // Factory method access (async).
+  //
+  static isBeingInstantiatedViaAsyncFactoryMethod = false
+
+  static async getInstanceAsync () {
+    if (this.instance !== undefined) {
+      return this.instance
+    }
+
+    // Create singleton instance.
+    this.isBeingInstantiatedViaAsyncFactoryMethod = true
+
+    this.instance = new IPAddresses()
+
+    // Initialise it asynchronously.
+    await this.instance.discoverIpAddresses()
+
+    return this.instance
+  }
+
+  get hasIPv4Address () {
+    return this.ipv4Address !== undefined
+  }
+
+  get hasIPv6Addresses () {
+    return this.ipv6Addresses.length > 0
+  }
+
+  //
+  // Private.
+  // 
+
+  constructor () {
+    // Ensure singelton access.
+    if (IPAddresses.isBeingInstantiatedViaAsyncFactoryMethod === false) {
+      throws.error(Symbol.for('MustBeInstantiatedViaAsyncFactoryMethodError'), 'IPAddresses')
+    }
+
+    // This reverts IP address sort order to pre-Node 17 behaviour.
+    // See https://github.com/nodejs/node/issues/40537
+    dns.setDefaultResultOrder('ipv4first')
+
+    IPAddresses.isBeingInstantiatedViaAsyncFactoryMethod = false
+  }
+
+  async discoverIpAddresses() {
+    await this.discoverIPv4Address()
+    this.discoverIPv6Addresses()
+  }
+
+  async discoverIPv4Address () {
+    try {
+      const response = await fetch('https://ip.small-web.org/json/')
+      if (response.status === 200) {
+        const ip = (await response.json()).ip
+        if (ip !== '::1') {
+          this.ipv4Address = ip
+        }
+      }
+    } catch (error) {
+      console.warn('Could not discover external IPv4 address.', error)
+    }
+  }
+
+  /**
+    Runs platform-specific command for retriving stable IPv6 addresses as we don’t
+    have a built-in way of differentiating between stable and temporary addresses
+    using Node.js alone (`os.networkInterfaces()` does not have that information.)
+  */
+  discoverIPv6Addresses () {
+    const platform = os.platform()
+    const platformSpecificStableIPv6DiscoveryCommand = IPAddresses.platformSpecificStableIPv6DiscoveryCommands[platform]
+
+    try {
+      const stdout = execSync(platformSpecificStableIPv6DiscoveryCommand, { encoding: 'utf-8' })
+      this.ipv6Addresses = stdout
+        .split('\n')
+        .map(address => address.trim())
+        .filter(address => address.length > 0)
+    } catch (error) {
+      console.warn(`[Auto Encrypt] Failed to discover IPv6 addresses using platform-specific (${platform}) command:`, platformSpecificStableIPv6DiscoveryCommand, error)
+    }
+  }
+}