@small-tech/https 5.4.0 → 6.0.0

package/README.md

@@ -12,7 +12,7 @@ Simply replace Node’s `https` module with `@small-tech/https` and get:
 
 That’s it.
 
-___Note:__ This is a standard ECMAScript Modules (ESM; es6 modules) project. If you need to use legacy CommonJS, [please see the 2.x branch](https://github.com/small-tech/https/tree/2.x) which is deprecated but still receives bug fixes._
+***Note:** This is a standard ECMAScript Modules (ESM; es6 modules) project. If you need to use legacy CommonJS, [please see the 2.x branch](https://github.com/small-tech/https/tree/2.x) which is deprecated but still receives bug fixes.*
 
 ## System requirements
 
@@ -24,11 +24,12 @@ __Tested and supported on:__
 
 - Linux (tested on Fedora Silverblue 37 and Ubuntu 22.04)
 - macOS (tested on Intel: Monterey, M1: Ventura, M4: Sequoia)
-- Windows (10 and 11 under Windows Terminal and with Windows PowerShell)
 
 > 💡 On macOS, if you’re using a third-party terminal application like iTerm, you must give it Full Disk Access rights or @small-tech/https will fail to install the policy file inside Firefox when creating local development servers. You can do this on the latest version of the operating system by adding iTerm to the list at System Settings → Privacy & Security → Full Disk Access.
 
->  💡 On Windows, @small-tech/https will also run under WSL 2 but this is not recommended when creating local development servers as local development certificates will not be automatically installed in your Windows browsers for you since your guest Linux system knows nothing about and cannot configure your host Windows environment.
+>  💡 Windows support has been removed 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/).
 
 ## Testing
 
@@ -81,19 +82,21 @@ npm i @small-tech/https
 ```js
 import https from '@small-tech/https'
 
-const server = https.createServer((request, response) => {
+const server = await https.createServer((request, response) => {
   response.end('Hello, world!')
 })
 
-server.listen(443, () => {
-  console.log(' 🎉 Server running at https://localhost.')
-})
+await server.listen(443)
+
+console.info(' 🎉 Server running at https://localhost.')
 ```
 
 Hit `https://localhost` and you should see your site with locally-trusted TLS certificates.
 
 > 💡 As of version 5.2.0, you can also use the localhost aliases _place1.localhost_ - _place4.localhost_ when testing the peer-to-peer features of [Small Web](https://ar.al/2020/08/07/what-is-the-small-web/) apps.
 
+> 💡 You can have a maximum of one server per Node process.
+
 @small-tech/https uses [Auto Encrypt Localhost](https://codeberg.org/small-tech/auto-encrypt-localhost) to create a local Certificate Authority (cA) and add it to the various trust stores. It then uses that CA to create locally-trusted TLS certificates that are automatically used by your server.
 
 ### At hostname with automatically-provisioned Let’s Encrypt certificates.
@@ -105,18 +108,20 @@ import os form 'os'
 const hostname = os.hostname()
 const options = { domains: [hostname] }
 
-const server = https.createServer((request, response) => {
+const server = await https.createServer((request, response) => {
   response.end('Hello, world!')
 })
 
-server.listen(443, () => {
-  console.log(` 🎉 Server running at https://${hostname}.`)
-})
+await server.listen(443)
+
+console.info(` 🎉 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.
 
-@small-tech/https automatically provisions Let’s Encrypt certificates for you the first time your server is hit using [Auto Encrypt](https://codeberg.org/small-tech/auto-encrypt) (this first load will take longer than future ones). During this initial load, other requests are ignored. This module will also automatically renew your certificates as necessary in plenty of time before they expire.
+> 💡 As of version 6, you can also pass the options `ipv4:true` and `ipv6:true` to automatically provision certificates for your server’s externally-reachable IPv4 address (as determined by hitting https://ip.small-web.org) and any locally-detected stable IPv6 addresses, respectively. You can also pass `ipOnly:true` to _only_ provision certificates for IP addresses (and ignore the automatically-detected hostname or any domains passed in the `domains` array).
+
+@small-tech/https automatically provisions Let’s Encrypt certificates for you when your server starts using [Auto Encrypt](https://codeberg.org/small-tech/auto-encrypt) This module will also automatically renew your certificates as necessary in plenty of time before they expire.
 
 You can find a version of this example in the `/example` folder. To download and run that version:
 
@@ -150,7 +155,7 @@ Or, if you want to cling to ancient historic relics like a conservative to a rac
 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](https://github.com/nexe/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](https://sitejs.org), [see this listing](https://source.ind.ie/site.js/app/blob/master/bin/lib/ensure.js#L124).
+If you are wrapping your Node app into an executable binary using a module like [Nexe](https://github.com/nexe/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](https://sitejs.org), [see this listing](https://codeberg.org/site.js/app/src/branch/main/bin/lib/ensure.js#L127).
 
 ## Related projects
 

package/index.js

@@ -1,7 +1,6 @@
 import os from 'node:os'
 import process from 'node:process'
 import path from 'node:path'
-import https from 'node:https'
 import EventEmitter from 'node:events'
 
 import AutoEncrypt from '@small-tech/auto-encrypt'
@@ -26,56 +25,55 @@ const DATA_HOME = path.join(
 export const SMALL_TECH_HOME_PATH = path.join(DATA_HOME, 'small-tech.org')
 export const DEFAULT_SETTINGS_PATH = path.join(SMALL_TECH_HOME_PATH, 'https')
 
-// Only modify this instance of the https module with our own createServer method.
-const smallTechHttps = Object.assign({}, https)
-
-smallTechHttps.createServer = function (options, listener) {
-    // The first parameter is optional. If omitted, listener should be passed as the first argument.
-    if (typeof options === 'function') {
-      listener = options
-      options = {}
-    }
-
-    const localDomains = ['localhost', 'place1.localhost', 'place2.localhost', 'place3.localhost', 'place4.localhost']
-    const isLocal = options.domains == undefined || options.domains.some(domain => localDomains.includes(domain))
-    const serverScope =  isLocal ? 'local' : 'global'
-    const settingsPath = options.settingsPath ? path.join(path.resolve(options.settingsPath), serverScope) : path.join(DEFAULT_SETTINGS_PATH, serverScope)
-    options.settingsPath = settingsPath
-
-    if (options.staging) { options.serverType = AUTO_ENCRYPT_STAGING_SERVER_TYPE }
-    delete options.staging
-
-    const autoEncryptScope = {
-      local: AutoEncryptLocalhost,
-      global: AutoEncrypt
-    }
-
-    const messageSuffix = {
-      local: 'at localhost with locally-trusted certificates',
-      global: 'with globally-trusted Let’s Encrypt certificates'
-    }
-    events.emit(events.CREATING_SERVER, `Creating server ${messageSuffix[serverScope]}.`)
-
-    const server = autoEncryptScope[serverScope].https.createServer(options, listener)
-
-    function emitCloseEvent() {
-      events.emit(events.SERVER_CLOSED, 'Server closed.')
-    }
-
-    if (serverScope === 'global') {
-      // Allow AutoEncrypt to perform clean-up (e.g., remove interval timer for renewal check, etc.)
-      server.on('close', () => {
-        AutoEncrypt.shutdown()
-        emitCloseEvent()
-      })
-    } else {
-      // No additional clean-up required for Auto Encrypt Localhost.
+export default class https {
+  /** @type { import('@small-tech/auto-encrypt-localhost').AutoEncryptedLocalhostServer| import('@small-tech/auto-encrypt').AutoEncryptedServer} */
+  static server = null
+
+  /**
+    Creates new AutoEncryped or AutoEncrypedLocalhost https server (asynchronous).
+
+    @param {import('./index.d.ts').SmallTechHttpsOptions | import('node:http').RequestListener} [options]
+    @param {import('node:http').RequestListener} [listener]
+  */
+  static async createServer (options = {}, listener) {
+      // There can be only server per node process. Enforce that here.
+      if (this.server !== null) {
+        console.warn('Create server called when server already exists for this process. Returning existing server instance.')
+        return this.server
+      }
+      
+      // The first parameter is optional. If omitted, listener should be passed as the first argument.
+      if (typeof options === 'function') {
+        listener = /** @type {import('node:http').RequestListener} */ (options)
+        options = {}
+      }
+
+      const localDomains = ['localhost', 'place1.localhost', 'place2.localhost', 'place3.localhost', 'place4.localhost']
+      const isLocal = (options.domains == undefined || options.domains.some(domain => localDomains.includes(domain))) && !options.ipv4 && !options.ipv6 && !options.ipOnly
+      const serverScope =  isLocal ? 'local' : 'global'
+      const settingsPath = options.settingsPath ? path.join(path.resolve(options.settingsPath), serverScope) : path.join(DEFAULT_SETTINGS_PATH, serverScope)
+      options.settingsPath = settingsPath
+
+      if (options.staging) { options.serverType = AUTO_ENCRYPT_STAGING_SERVER_TYPE }
+      delete options.staging
+
+      const messageSuffix = {
+        local: 'at localhost with locally-trusted certificates',
+        global: 'with globally-trusted Let’s Encrypt certificates'
+      }
+      events.emit(events.CREATING_SERVER, `Creating server ${messageSuffix[serverScope]}.`)
+
+      const server = await (serverScope === 'local'
+        ? AutoEncryptLocalhost.https.createServer(options, listener)
+        : AutoEncrypt.https.createServer(options, listener))
+
+      function emitCloseEvent() {
+        events.emit(events.SERVER_CLOSED, 'Server closed.')
+      }
       server.on('close', emitCloseEvent)
-    }
 
-    events.emit(events.SERVER_CREATED, 'Created HTTPS server.')
+      events.emit(events.SERVER_CREATED, 'Created HTTPS server.')
 
-    return server
+      return server
+  }
 }
-
-export default smallTechHttps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@small-tech/https",
-  "version": "5.4.0",
+  "version": "6.0.0",
   "description": "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.",
   "main": "index.js",
   "files": [
@@ -49,13 +49,13 @@
   },
   "license": "AGPL-3.0",
   "dependencies": {
-    "@small-tech/auto-encrypt": "^4.3.0",
-    "@small-tech/auto-encrypt-localhost": "^8.3.2"
+    "@small-tech/auto-encrypt": "^5.0.0",
+    "@small-tech/auto-encrypt-localhost": "^10.0.0"
   },
   "devDependencies": {
-    "@small-tech/cross-platform-hostname": "^1.0.0",
     "@small-tech/esm-tape-runner": "^1.0.3",
     "@small-tech/tap-monkey": "^1.3.0",
+    "@types/node": "^25.0.9",
     "bent": "^7.3.12",
     "c8": "^7.6.0",
     "tape": "^5.2.2"