@small-tech/auto-encrypt 4.2.0 → 4.3.0

package/index.js

@@ -14,6 +14,7 @@
 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'
@@ -76,6 +77,9 @@ 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
@@ -170,7 +174,19 @@ export default class AutoEncrypt {
       }
     }
 
-    const server = https.createServer(options, listener)
+    const shouldAddOcspMustStaple = certificate.hasOcspMustStaple || false
+
+    // During the transitionary period where Let’s Encrypt has shut down
+    // OCSP support but there are still servers out there with certificates
+    // that have OCSP stapling because their 6-month validity period isn’t
+    // over, we create the server accordingly based on whether the certificate
+    // has OCSP stapling or not so it works for both cases.
+    // TODO: OCSP support can be fully removed in August 2025. All existing
+    // servers with valid certificates will be non-OCSP at that point.
+    const serverWithoutOcspMustStaple = https.createServer(options, listener)
+     const server = shouldAddOcspMustStaple
+     ? this.addOcspStapling(serverWithoutOcspMustStaple)
+     : serverWithoutOcspMustStaple
 
     //
     // Monkey-patch the server.
@@ -208,11 +224,25 @@ 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()
   }
 
@@ -220,6 +250,64 @@ 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

@@ -94,29 +94,32 @@ export default class Certificate {
   #_serialNumber = null
   #_issueDate = null
   #_expiryDate = null
-
-  get isProvisioned    () { return this.#_pem !== null     }
-  get pem              () { return this.#_pem              }
-  get identity         () { return this.#_identity         }
-  get key              () { return this.#_key              }
-  get serialNumber     () { return this.#_serialNumber     }
-  get issuer           () { return this.#_issuer           }
-  get subject          () { return this.#_subject          }
-  get alternativeNames () { return this.#_alternativeNames }
-  get issueDate        () { return this.#_issueDate        }
-  get expiryDate       () { return this.#_expiryDate       }
-  get renewalDate      () { return this.#renewalDate       }
+  #_hasOcspMustStaple = null
+
+  get isProvisioned     () { return this.#_pem !== null     }
+  get pem               () { return this.#_pem              }
+  get identity          () { return this.#_identity         }
+  get key               () { return this.#_key              }
+  get serialNumber      () { return this.#_serialNumber     }
+  get issuer            () { return this.#_issuer           }
+  get subject           () { return this.#_subject          }
+  get alternativeNames  () { return this.#_alternativeNames }
+  get issueDate         () { return this.#_issueDate        }
+  get expiryDate        () { return this.#_expiryDate       }
+  get renewalDate       () { return this.#renewalDate       }
+  get hasOcspMustStaple () { return this.#_hasOcspMustStaple }
 
   set pem (certificatePem) {
     this.#_pem = certificatePem
 
     const details = this.parseDetails(certificatePem)
-    this.#_serialNumber     = details.serialNumber
-    this.#_issuer           = details.issuer
-    this.#_subject          = details.subject
-    this.#_alternativeNames = details.alternativeNames
-    this.#_issueDate        = moment(details.issuedAt)
-    this.#_expiryDate       = moment(details.expiresAt)
+    this.#_serialNumber      = details.serialNumber
+    this.#_issuer            = details.issuer
+    this.#_subject           = details.subject
+    this.#_alternativeNames  = details.alternativeNames
+    this.#_issueDate         = moment(details.issuedAt)
+    this.#_expiryDate        = moment(details.expiresAt)
+    this.#_hasOcspMustStaple = details.hasOcspMustStaple
 
     // Display the certificate with a nice border :)
     const logMessagePrefix = '         ❨auto-encrypt❩ '
@@ -370,18 +373,26 @@ export default class Certificate {
     const issuedAt = new Date(certificate.validity.notBefore.value)
     const expiresAt = new Date(certificate.validity.notAfter.value)
     const subject = certificate.subject.value.length > 0 ? certificate.subject.value[0][0].value.toString('utf-8').slice(2).trim() : '(No subject)'
+    let hasOcspMustStaple = false
 
     const alternativeNames = ((certificate.extensions.filter(extension => {
       return extension.extnID === 'subjectAlternativeName'
     }))[0].extnValue).map(name => name.value)
 
+    certificate.extensions.forEach(extension => {
+      if (Array.isArray(extension.extnID) && extension.extnID.join('.') === '1.3.6.1.5.5.7.1.24') {
+        hasOcspMustStaple = true
+      }
+    })
+
     return {
       serialNumber,
       issuer,
       subject,
       alternativeNames,
       issuedAt,
-      expiresAt
+      expiresAt,
+      hasOcspMustStaple
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@small-tech/auto-encrypt",
-  "version": "4.2.0",
+  "version": "4.3.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.20.0"
@@ -68,7 +68,8 @@
     "encodeurl": "^1.0.2",
     "jose": "^1.28.2",
     "moment": "^2.29.4",
-    "node-forge": "^1.3.1"
+    "node-forge": "^1.3.1",
+    "ocsp": "^1.2.0"
   },
   "devDependencies": {
     "@small-tech/esm-tape-runner": "^1.0.3",