@small-tech/auto-encrypt 3.1.0 → 4.1.0

package/README.md

@@ -1,12 +1,20 @@
 # 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.)
+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.)
+
+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 will take a couple of seconds to load as your Let’s Encrypt TLS certificates are automatically provisioned for you. From there on, your certificates will be seamlessly renewed 30 days before their expiry date.
+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.
+
+When not provisioning certificates, Auto Encrypt also forwards HTTP calls to HTTPS on your server.
+
+## Compatibility
 
-When not provisioning certificates, Auto Encrypt will also forward HTTP calls to HTTPS on your server.
+All tests pass on Node.js LTS (version 22).
+
+[Tests fail on Node.js 19 (socket hang up error).](https://codeberg.org/small-tech/auto-encrypt/issues/3)
 
 ## Installation
 
@@ -19,30 +27,29 @@ npm i @small-tech/auto-encrypt
 ### Instructions
 
 1. Import the module:
-
-    ```js
-    import AutoEncrypt from '@small-tech/auto-encrypt'
-    ```
+   
+   ```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(…)
-    ```
+   
+   ```js
+   // const server = https.createServer(…) becomes
+   const server = AutoEncrypt.https.createServer(…)
+   ```
 
 3. When done, close your server as you would normally:
-
-    ```js
-    server.close(() => {
-      console.log('The server is now closed.')
-    })
-    ```
+   
+   ```js
+   server.close(() => {
+     console.log('The server is now closed.')
+   })
+   ```
 
 ### Example
 
-The following code creates an HTTPS server running on port 443 with [OCSP Stapling](https://letsencrypt.org/docs/integration-guide/#implement-ocsp-stapling) 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>_ and _www.<hostname>_.
 
 ```js
 import AutoEncrypt from '@small-tech/auto-encrypt'
@@ -62,7 +69,7 @@ server.close(() => {
 })
 ```
 
-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 Node web server that handles all that and more for you (or to see how to implement privilege escalation seamlessly in your own servers, see [Site.js](https://sitejs.org)).
+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)).
 
 ## Configuration
 
@@ -70,6 +77,8 @@ 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.
 
+(Auto Encrypt uses [Node Pebble](https://codeberg.org/small-tech/node-pebble) to enable testing with a local Pebble server from Node.js.)
+
 ### Example
 
 ```js
@@ -94,9 +103,9 @@ const server = AutoEncrypt.https.createServer(options, listener)
 
 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/_
+- `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/_
 
 ## Making a graceful exit
 
@@ -104,7 +113,7 @@ When you’re ready to exit your app, just call the `server.close()` method as y
 
 ## 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://github.com/small-tech/auto-encrypt/blob/master/developer-documentation.md).
+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
 
@@ -170,18 +179,17 @@ If you’re evaluating this for a “startup” or an enterprise, let us save yo
 
 ## Client details
 
-Auto Encrypt does one thing and one thing well: it automatically provisions a Let’s Encrypt TLS certificate for your Node.js https servers using the HTTP-01 challenge method when your server is first hit from its hostname, serves it using OCSP Stapling, and automatically renews your certificate thereafter. And, when not provisioning certificates, it forwards any HTTP requests that your machine gets to HTTPS.
+Auto Encrypt does one thing and one thing well: it automatically provisions a Let’s Encrypt TLS certificate for your Node.js https servers using the HTTP-01 challenge method when your server is first hit from its hostname, and automatically renews your certificate thereafter. When not provisioning certificates, it forwards any HTTP requests that your machine gets to HTTPS.
 
-Auto Encrypt __does not_ and __will not__:
+__Auto Encrypt _does not_ and _will not:___
 
-  - Implement wildcard certificates. For most [small tech](https://small-tech.org/about/#small-technology) needs (personal web sites and web apps), you will likely need no more than two domains (the root domain and, due to historic and conventional reasons, the www subdomain). You will definitely not need more than the 100 domains that are supported per certificate. If you do, chances are you are looking to use Auto Encrypt in a startup or corporate setting, which is not what its for.
-
-  - Implement DNS-01 or any other methods that cannot be fully automated.
+- __Implement wildcard certificates.__ For most [small tech](https://small-tech.org/about/#small-technology) needs (personal web sites and web apps), you will likely need no more than two domains (the root domain and, due to historic and conventional reasons, the www subdomain). You will definitely not need more than the 100 domains that are supported per certificate. If you do, chances are you are looking to use Auto Encrypt in a startup or corporate setting, which is not what its for.
 
+- __Implement DNS-01__ or any other methods that cannot be fully automated.
 
 ## Staging and production server behaviour and rate limits
 
-By default, Auto Encrypt will use the Let’s Encrypt production environment. This is most likely what you want as it means that your HTTPS server will Just Work™, provisioning its TLS certificate automatically the first time the server is hit via its hostname and from thereon automatically renewing the certificate a month ahead of its expiry date.
+By default, Auto Encrypt uses Let’s Encrypt’s production environment. This is most likely what you want as it means your HTTPS server will Just Work™, i.e., provision its TLS certificate automatically the first time the server is hit via its hostname and from thereon automatically renew the certificate a month ahead of its expiry date.
 
 However, be aware that the production server has [rate limits](https://letsencrypt.org/docs/rate-limits/).
 
@@ -191,31 +199,30 @@ If you do use the staging environment, be aware that browsers will reject the st
 
 Needless to say, do not add the fake certificate root to the same trust store you use for your everyday browsing.
 
-
 ## Related projects
 
 From lower-level to higher-level:
 
 ### Auto Encrypt Localhost
 
-  - Source: https://source.small-tech.org/site.js/lib/auto-encrypt-localhost
-  - Package: [@small-tech/auto-encrypt-localhost](https://www.npmjs.com/package/@small-tech/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 in 100% JavaScript (without any native dependencies like mkcert and certutil).
 
 ### HTTPS
 
-  - Source: https://source.small-tech.org/site.js/lib/https
-  - Package: [@small-tech/https](https://www.npmjs.com/package/@small-tech/https)
+- Source: https://source.small-tech.org/site.js/lib/https
+- Package: [@small-tech/https](https://www.npmjs.com/package/@small-tech/https)
 
-A drop-in [standard Node.js HTTPS module](https://nodejs.org/dist/latest-v12.x/docs/api/https.html) replacement with both automatic development-time (localhost) certificates via Auto Encrypt Localhost and automatic production certificates via Auto Encrypt.
+Drop-in replace for the [standard Node.js HTTPS module](https://nodejs.org/dist/latest-v12.x/docs/api/https.html) replacement that automatically handles TLS certificate provisioning and renewal both at localhost (via Auto Encrypt Localhost) and at hostname (via Auto Encrypt).
 
-### Site.js
+### Kitten
 
-  - Web site: https://sitejs.org
-  - Source: https://source.small-tech.org/site.js/app
+- Site: https://kitten.small-web.org
+- Source: https://codeberg.org/kitten/app
 
-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.
+A [💕 Small Web](https://ar.al/2020/08/07/what-is-the-small-web/) development kit.
 
 ## Tests and coverage
 
@@ -223,7 +230,7 @@ This project aims for > 80% coverage. At a recent check, coverage was at 97.42%
 
 To see the current state of code coverage, run `npm run coverage`.
 
-For more details, please see the [developer documentation](https://github.com/small-tech/auto-encrypt/blob/master/developer-documentation.md#tests).
+For more details, please see the [developer documentation](https://codeberg.org/small-tech/auto-encrypt/src/branch/main/developer-documentation.md#tests).
 
 ## A note on Linux and the security farce that is “privileged ports”
 

package/index.js

@@ -14,7 +14,6 @@
 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'
@@ -24,6 +23,11 @@ import Throws from './lib/util/Throws.js'
 import HttpServer from './lib/HttpServer.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')
+
 // Custom errors thrown by the autoEncrypt function.
 const throws = new Throws({
   [Symbol.for('BusyProvisioningCertificateError')]:
@@ -72,9 +76,6 @@ export default class AutoEncrypt {
    */
   static get https () { return AutoEncrypt }
 
-
-  static ocspCache = null
-
   /**
    * 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
@@ -169,7 +170,7 @@ export default class AutoEncrypt {
       }
     }
 
-    const server = this.addOcspStapling(https.createServer(options, listener))
+    const server = https.createServer(options, listener)
 
     //
     // Monkey-patch the server.
@@ -207,25 +208,11 @@ export default class AutoEncrypt {
   }
 
 
-  /**
-   * 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)
-      })
-    }
-  }
-
   /**
    * 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()
   }
 
@@ -233,64 +220,6 @@ export default class AutoEncrypt {
   // 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/Certificate.js

@@ -369,7 +369,7 @@ export default class Certificate {
     const issuer = certificate.issuer.value[0][0].value.toString('utf-8').slice(2).trim()
     const issuedAt = new Date(certificate.validity.notBefore.value)
     const expiresAt = new Date(certificate.validity.notAfter.value)
-    const subject = certificate.subject.value[0][0].value.toString('utf-8').slice(2).trim()
+    const subject = certificate.subject.value.length > 0 ? certificate.subject.value[0][0].value.toString('utf-8').slice(2).trim() : '(No subject)'
 
     const alternativeNames = ((certificate.extensions.filter(extension => {
       return extension.extnID === 'subjectAlternativeName'

package/lib/HttpServer.js

@@ -18,7 +18,7 @@
 //   B. At all other times:
 //   ======================
 //
-//   Forwards http requests to https requests using a 302 redirect.
+//   Forwards http requests to https requests using a 307 redirect.
 //
 // Copyright © 2020 Aral Balkan, Small Technology Foundation.
 // License: AGPLv3 or later.
@@ -27,7 +27,6 @@
 
 import http from 'http'
 import encodeUrl from 'encodeurl'
-import enableDestroy from 'server-destroy'
 import log from './util/log.js'
 
 export default class HttpServer {
@@ -120,18 +119,13 @@ export default class HttpServer {
         response.end()
       }
     })
-
-    // Enable server to be destroyed without waiting for any existing connections to close.
-    // (While there shouldn’t be any existing connections and while the likelihood of someone
-    // trying to denial-of-service this very low, it’s still the right thing to do.)
-    enableDestroy(this.server)
   }
 
   set challengeServer (state) {
     if (state) {
       log(`   🔒    ❨auto-encrypt❩ HTTP server is now only responding to Let’s Encrypt challenges.`)
     } else {
-      log(`   🔒    ❨auto-encrypt❩ HTTP server is now forwarding HTTP requests to HTTPS (302).`)
+      log(`   🔒    ❨auto-encrypt❩ HTTP server is now forwarding HTTP requests to HTTPS (307).`)
     }
     this.#isChallengeServer = state
   }
@@ -156,16 +150,16 @@ export default class HttpServer {
 
   async destroy () {
     // Starts killing all connections and closes the server.
-    this.server.destroy()
+    this.server.closeAllConnections()
 
-    // Wait until the server is closed before returning.
     await new Promise((resolve, reject) => {
-      this.server.on('close', () => {
+      this.server.close(error => {
+        if (error) {
+          console.error(error)
+          reject(error)
+        }
         resolve()
       })
-      this.server.on('error', (error) => {
-        reject(error)
-      })
     })
   }
 }

package/lib/Order.js

@@ -31,6 +31,7 @@ const throws = new Throws()
 export default class Order {
   #data                = null
   #headers             = null
+  #location            = null
   #order               = null
   #certificate         = null
   #certificateIdentity = null
@@ -65,6 +66,10 @@ export default class Order {
   get data () { return this.#data }
   set data (value) {
     this.#data = value
+    // It seems that Let’s Encrypt are no longer sending the location
+    // back on status checks, only on order finalisation, so let’s\
+    // make sure we don’t accidentally.
+    if (this.#data.headers.location !== undefined) this.#location = this.#data.headers.location
     this.#headers = this.#data.headers
     this.#order = this.#data.body
   }
@@ -168,10 +173,12 @@ export default class Order {
       try {
         if (numAttempts === 1) {
           // Finalise using CSR.
+          log('   📝    ❨auto-encrypt❩ Finalising using CSR.')
           this.data = await (new FinaliseOrderRequest()).execute(this.finaliseUrl, csr)
         } else {
           // Check for order status.
-          this.data = await (new CheckOrderStatusRequest()).execute(this.#headers.location)
+          log('   👀    ❨auto-encrypt❩ Checking for order status.')
+          this.data = await (new CheckOrderStatusRequest()).execute(this.#location)
         }
       } catch (error) {
         // TODO: Handle error.

package/lib/acmeCsr.js

@@ -53,12 +53,6 @@ function csrAsPem (domains, key) {
     extensions: [{
       name: 'subjectAltName',
       altNames
-    }, {
-      // OCSP Must Staple
-      // RFC 7633. Also see https://scotthelme.co.uk/ocsp-must-staple/
-      // 1.3.6.1.5.5.7.1.24 = DER(3003020105) (Sequence > Int > 5) *smh* ASN.1 is devil spawn.
-      id: '1.3.6.1.5.5.7.1.24',
-      value: forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, [ forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.INTEGER, false, forge.asn1.integerToDer(5).getBytes())])
     }]
   }])
 

package/lib/test-helpers/index.js

@@ -8,7 +8,6 @@ import fs from 'fs'
 import os from 'os'
 import path from 'path'
 import http from 'http'
-import enableServerDestroy from 'server-destroy'
 import Configuration from '../Configuration.js'
 import LetsEncryptServer from '../LetsEncryptServer.js'
 import Throws from '../util/Throws.js'
@@ -19,7 +18,7 @@ import log from '../util/log.js'
 //
 
 const throws = new Throws({
-  [Symbol.for('MockServerCouldNotBeStartedError')]: details => `Mock server could not be started (${error})`
+  [Symbol.for('MockServerCouldNotBeStartedError')]: error => `Mock server could not be started (${error})`
 })
 
 export class MockServer {
@@ -45,7 +44,6 @@ export class MockServer {
 
   async create () {
     const server = http.createServer(this.#responseHandler)
-    enableServerDestroy(server)
     this.#server = server
     await new Promise((resolve, reject) => {
       try {
@@ -60,12 +58,21 @@ export class MockServer {
   }
 
   async destroy () {
-    this.#server.destroy()
+    this.#server.closeAllConnections()
+    return new Promise((resolve, reject) => {
+      this.#server.close(error => {
+        if (error) {
+          console.error(error)
+          reject(error)
+        }
+        resolve()
+      })
+    })
   }
 }
 
 export async function httpServerWithResponse (mockResponse) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve, _reject) => {
     const server = http.createServer((request, response) => {
       response.statusCode = mockResponse.statusCode
       response.end(mockResponse.body)

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@small-tech/auto-encrypt",
-  "version": "3.1.0",
-  "description": "Adds automatic provisioning and renewal of Let’s Encrypt TLS certificates with OCSP Stapling to Node.js https servers (including Express.js, etc.)",
+  "version": "4.1.0",
+  "description": "Automatically provisions and renews Let’s Encrypt TLS certificates on Node.js https servers (including Kitten, Polka, Express.js, etc.)",
+  "engines": {
+    "node": ">=18.2.0"
+  },
   "keywords": [
     "let's encrypt",
     "acme",
@@ -10,6 +13,7 @@
     "tls",
     "auto encrypt",
     "small tech",
+    "small web",
     "automatic"
   ],
   "author": {
@@ -60,24 +64,19 @@
     ]
   },
   "dependencies": {
-    "bent": "aral/bent#errors-with-response-headers",
+    "bent": "^7.3.12",
     "encodeurl": "^1.0.2",
-    "jose": "^1.24.0",
-    "moment": "^2.24.0",
-    "node-forge": "^1.3.1",
-    "ocsp": "^1.2.0",
-    "server-destroy": "^1.0.1"
+    "jose": "^1.28.2",
+    "moment": "^2.29.4",
+    "node-forge": "^1.3.1"
   },
   "devDependencies": {
     "@small-tech/esm-tape-runner": "^1.0.3",
-    "@small-tech/node-pebble": "^4.2.4",
+    "@small-tech/node-pebble": "^5.1.3",
     "@small-tech/tap-monkey": "^1.3.0",
-    "c8": "^7.11.3",
-    "dependency-cruiser": "^9.15.1",
-    "esbuild": "^0.8.53",
-    "jsdoc": "^3.6.6",
+    "c8": "^7.12.0",
+    "dependency-cruiser": "^12.3.0",
     "jsdoc-to-markdown": "^6.0.1",
-    "tape": "^5.2.1",
-    "wtfnode": "^0.8.1"
+    "tape": "^5.2.1"
   }
 }