@small-tech/https 4.0.0 → 5.0.1

package/README.md

@@ -1,27 +1,35 @@
 # @small-tech/https
 
-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.
+A batteries-included version of the standard Node.js `https` module.
 
 Simply replace Node’s `https` module with `@small-tech/https` and get:
 
-- Automatically-provisioned TLS certificates at localhost with no browser warnings via [mkcert](https://github.com/FiloSottile/mkcert).
-- Automatically-provisioned TLS certificates at hostname via [Let’s Encrypt](https://letsencrypt.org/).
-- Automatic HTTP to HTTPS forwarding at hostname.
+- Automatically-provisioned trusted local development TLS certificates via [Auto Encrypt Localhost](https://codeberg.org/small-tech/auto-encrypt-localhost)
 
-That’s it.
+- Automatically-provisioned [Let’s Encrypt](https://letsencrypt.org/) TLS certificates via [Auto Encrypt](https://codeberg.org/small-tech/auto-encrypt).
 
-This is basically a batteries-included version of the standard Node.js `https` module.
+- Automatic HTTP to HTTPS forwarding.
 
-___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 currently still being maintained._
+That’s it.
 
-## Compatibility
+___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._
 
-- Version 4.x: Node 18.2 LTS+
+## System requirements
 
+- Version 4.x, 5.x+: Node 18.2 LTS+
 - Version 3.x: Node 16 LTS
-
 - Version 2.x: CJS, Node 16 LTS
 
+__Tested and supported on:__
+
+- Linux (tested on Fedora Silverblue 37 and Ubuntu 22.04)
+- macOS (tested on Intel: Monterey, M1: Ventura)
+- 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.
+
 ## Like this? Fund us!
 
 [Small Technology Foundation](https://small-tech.org) is a tiny, independent not-for-profit.
@@ -34,27 +42,15 @@ This is [small technology](https://small-tech.org/about/#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.
 
-## Platform support
-
-Tested and supported on:
-
-- Linux (tested with elementary OS 5.x/Hera)
-- macOS (tested on Big Sur)
-- Windows 10 (tested in Windows Terminal with PowerShell)
-
-(WSL is not supported for certificates at localhost unless you’re running your browser under WSL also).
-
 ## Install
 
 ```sh
 npm i @small-tech/https
 ```
 
-Note that during installation, this module’s Auto Encrypt Localhost dependency will download the correct mkcert binary to your machine.
-
 ## Examples
 
-### At localhost with automatically-provisioned development certificates via mkcert.
+### At localhost with automatically-provisioned localhost development certificates.
 
 ```js
 import https from '@small-tech/https'
@@ -70,7 +66,7 @@ server.listen(443, () => {
 
 Hit `https://localhost` and you should see your site with locally-trusted TLS certificates.
 
-@small-tech/https uses mkcert to create a local certificate authority and add it to the various trust stores. It then uses it to create locally-trusted TLS certificates that are automatically used by your server.
+@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.
 
@@ -92,7 +88,7 @@ server.listen(443, () => {
 
 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 (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.
+@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.
 
 You can find a version of this example in the `/example` folder. To download and run that version:
 
@@ -134,26 +130,36 @@ Lower-level:
 
 ### Auto Encrypt
 
-- Source: https://source.small-tech.org/site.js/lib/auto-encrypt
+- Source: https://github.com/small-tech/auto-encrypt
 - Package: [@small-tech/auto-encrypt](https://www.npmjs.com/package/@small-tech/auto-encrypt)
 
-Adds automatic provisioning and renewal of [Let’s Encrypt](https://letsencrypt.org) TLS certificates with [OCSP Stapling](https://letsencrypt.org/docs/integration-guide/#implement-ocsp-stapling) to [Node.js](https://nodejs.org) [https](https://nodejs.org/dist/latest-v12.x/docs/api/https.html) servers (including [Express.js](https://expressjs.com/), etc.)
+Adds automatic provisioning and renewal of [Let’s Encrypt](https://letsencrypt.org) TLS certificates with [OCSP Stapling](https://letsencrypt.org/docs/integration-guide/#implement-ocsp-stapling) to [Node.js](https://nodejs.org) [https](https://nodejs.org/dist/latest-v12.x/docs/api/https.html) servers (including Polka, Express.js, etc.)
 
 ### Auto Encrypt Localhost
 
-- Source: https://source.small-tech.org/site.js/lib/auto-encrypt-localhost
+- Source: https://codeberg.org/small-tech/auto-encrypt-localhost
 - Package: [@small-tech/auto-encrypt-localhost](https://www.npmjs.com/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](https://github.com/FiloSottile/mkcert/).
+Automatically provisions and installs locally-trusted TLS certificates for Node.js https servers (including Polka, Express.js, etc.).
 
 Higher level:
 
 ### Site.js
 
 - Web site: https://sitejs.org
-- Source: https://source.small-tech.org/site.js/app
+- Source: https://github.com/small-tech/site.js
+
+A tool for developing, testing, and deploying a secure static or dynamic personal web site or app with zero configuration.
+
+Note: **Deprecated.** Site.js is being used to serve a number of our own web sites and isn’t going away anytime soon but all new development work is on Kitten.
+
+### Kitten
+
+- Web site/source code: https://codeberg.org/kitten/app
+
+A [Small Web](https://small-tech.org/research-and-development/) development kit.
 
-A complete [small technology](https://small-tech.org/about/#small-technology) tool for developing, testing, and deploying a secure static or dynamic personal web site or app with zero configuration.
+Create your Small Web site using plain HTML, CSS, and JavaScript then enhance it with [htmx](https://htmx.org/) and [Alpine.js](https://alpinejs.dev), if you like.
 
 ## Copyright
 
@@ -163,4 +169,4 @@ Let’s Encrypt is a trademark of the Internet Security Research Group (ISRG). A
 
 ## License
 
-[AGPL version 3.0 or later.](https://www.gnu.org/licenses/agpl-3.0.en.html)
+[AGPL version 3.0.](https://www.gnu.org/licenses/agpl-3.0.en.html)

package/index.js

@@ -1,13 +1,31 @@
-import os from 'os'
-import fs from 'fs-extra'
-import path from 'path'
-import https from 'https'
+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'
 import AutoEncryptLocalhost from '@small-tech/auto-encrypt-localhost'
-import log from './lib/util/log.js'
+
+class Events extends EventEmitter {
+  CREATING_SERVER = Symbol()
+  SERVER_CREATED = Symbol()
+  SERVER_CLOSED = Symbol()
+}
+
+export const events = new Events()
 
 const AUTO_ENCRYPT_STAGING_SERVER_TYPE = 1
 
+const DATA_HOME = path.join(
+  process.env.XDG_DATA_HOME || process.env.HOME || os.homedir(),
+  '.local',
+  'share'
+)
+
+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)
 
@@ -18,46 +36,43 @@ smallTechHttps.createServer = function (options, listener) {
       options = {}
     }
 
-    const defaultSettingsPath = path.join(os.homedir(), '.small-tech.org', 'https')
     const serverScope = options.domains == undefined || options.domains.includes('localhost') ? 'local' : 'global'
-
-    const settingsPath = options.settingsPath ? path.join(path.resolve(options.settingsPath), serverScope) : path.join(defaultSettingsPath, serverScope)
-
+    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 logMessage = {
-      local: 'at localhost with locally-trusted certificates',
-      global: 'with globally-trusted Let’s Encrypt certificates'
-    }
-
     const autoEncryptScope = {
       local: AutoEncryptLocalhost,
       global: AutoEncrypt
     }
 
-    log(`   🔒    ❨https❩ Creating server ${logMessage[serverScope]}.`)
+    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)
 
-    if (serverScope === 'global') {
-      // Migration: 1.1.0 and earlier to 1.2.0+:
-      // Remove the old Let’s Encrypt client’s certificate settings.
-      // (And thus force upgrade to certificates managed by Auto Encrypt on first hit of server.)
-      const oldLetsEncryptSettingsPathFor = directory => path.join(settingsPath, directory)
-      fs.removeSync(oldLetsEncryptSettingsPathFor('accounts'))
-      fs.removeSync(oldLetsEncryptSettingsPathFor('archive'))
-      fs.removeSync(oldLetsEncryptSettingsPathFor('live'))
-      fs.removeSync(oldLetsEncryptSettingsPathFor('renewal'))
+    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.
+      server.on('close', emitCloseEvent)
     }
 
-    log('   🔒    ❨https❩ Created HTTPS server.')
+    events.emit(events.SERVER_CREATED, 'Created HTTPS server.')
+
     return server
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@small-tech/https",
-  "version": "4.0.0",
+  "version": "5.0.1",
   "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": [
@@ -44,11 +44,10 @@
     "email": "aral@small-tech.org",
     "url": "https://ar.al"
   },
-  "license": "AGPL-3.0-or-later",
+  "license": "AGPL-3.0",
   "dependencies": {
     "@small-tech/auto-encrypt": "^4.0.0",
-    "@small-tech/auto-encrypt-localhost": "^7.2.0",
-    "fs-extra": "^9.0.1"
+    "@small-tech/auto-encrypt-localhost": "^8.2.0"
   },
   "devDependencies": {
     "@small-tech/cross-platform-hostname": "^1.0.0",
@@ -56,13 +55,11 @@
     "@small-tech/tap-monkey": "^1.3.0",
     "bent": "^7.3.12",
     "c8": "^7.6.0",
-    "tape": "^5.2.2",
-    "wtfnode": "^0.8.1"
+    "tape": "^5.2.2"
   },
   "nyc": {
     "exclude": [
-      "test/**/*.js",
-      "lib/util/*.js"
+      "test/**/*.js"
     ]
   }
 }

package/lib/util/log.js

@@ -1,6 +0,0 @@
-export default function log(...args) {
-  if (process.env.QUIET) {
-    return
-  }
-  console.log(...args)
-}