@small-tech/auto-encrypt 4.0.0 → 4.1.1

package/README.md

@@ -1,20 +1,18 @@
 # 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 will also forward HTTP calls to HTTPS on your server.
+When not provisioning certificates, Auto Encrypt also forwards HTTP calls to HTTPS on your server.
 
 ## Compatibility
 
-All tests pass on Node.js LTS (18.2+).
-
-[Tests fail on Node.js 19 (socket hang up error).](https://codeberg.org/small-tech/auto-encrypt/issues/3)
+All tests pass on Node.js LTS (version 22).
 
 ## Installation
 
@@ -49,7 +47,7 @@ npm i @small-tech/auto-encrypt
 
 ### 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'
@@ -69,7 +67,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
 
@@ -77,6 +75,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
@@ -111,7 +111,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
 
@@ -177,17 +177,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 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 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/).
 
@@ -203,24 +203,24 @@ From lower-level to higher-level:
 
 ### 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 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)
 
-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
 
@@ -228,7 +228,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'
@@ -77,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
@@ -174,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.
@@ -212,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()
   }
 
@@ -238,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/AcmeRequest.js

@@ -6,6 +6,9 @@
  * @license AGPLv3 or later.
  */
 
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
 import jose from 'jose'
 import prepareRequest from 'bent'
 import types from '../typedefs/lib/AcmeRequest.js'
@@ -23,6 +26,7 @@ const throws = new Throws({
   [Symbol.for('AcmeRequest.requestError')]: error => `(${error.status} ${error.type} ${error.detail})`
 })
 
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
 /**
  * Abstract base request class for carrying out signed ACME requests over HTTPS.
  *
@@ -34,6 +38,8 @@ export default class AcmeRequest {
   static accountIdentity = null
   static nonce = null
   static __account = null
+  /** @type {string} */
+  static autoEncryptVersion = JSON.parse(fs.readFileSync(path.join(__dirname, '../package.json'))).version
 
   static initialise (directory = throws.ifMissing(), accountIdentity = throws.ifMissing()) {
     this.directory = directory
@@ -228,7 +234,7 @@ export default class AcmeRequest {
 
     const httpsHeaders = {
       'Content-Type': 'application/jose+json',
-      'User-Agent': 'small-tech.org-acme/1.0.0 node/12.16.0',
+      'User-Agent': `small-tech.org-auto-encrypt/${AcmeRequest.autoEncryptVersion}`,
       'Accept-Language': 'en-US'
     }
 

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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@small-tech/auto-encrypt",
-  "version": "4.0.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.1",
+  "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"
   },
@@ -68,12 +68,11 @@
     "encodeurl": "^1.0.2",
     "jose": "^1.28.2",
     "moment": "^2.29.4",
-    "node-forge": "^1.3.1",
-    "ocsp": "^1.2.0"
+    "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.12.0",
     "dependency-cruiser": "^12.3.0",