@small-tech/auto-encrypt 4.2.0 → 5.0.0

package/lib/acme-requests/FinaliseOrderRequest.js

@@ -1,15 +1,9 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// FinaliseOrderRequest
-//
-// Attempts to finalise an order by posting the passed CSR (see RFC 2986).
-//
-// See RFC 8555 § 7.4 (Applying for Certificate Issuance).
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  FinaliseOrderRequest
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import AcmeRequest from '../AcmeRequest.js'
 import Throws from '../util/Throws.js'
@@ -17,16 +11,24 @@ import Throws from '../util/Throws.js'
 const throws = new Throws()
 
 export default class FinaliseOrderRequest extends AcmeRequest {
+  /**
+    Attempts to finalise an order by posting the passed CSR (see RFC 2986).
+
+    See RFC 8555 § 7.4 (Applying for Certificate Issuance).
+
+    @param { string | void } finaliseUrl
+    @param { string | void } csr
+  */
   async execute (finaliseUrl = throws.ifMissing(), csr = throws.ifMissing()) {
 
-    const payload = { csr }
+    const payload = { csr: /** @type { string } */ (csr) }
 
-    const response = await super.execute(
-        /* command =      */ '', // see URL, below.
-        /* payload =      */ payload,
-        /* useKid =       */ true,
-        /* successCodes = */ [200],
-        /* url =          */ finaliseUrl
+    const response = await super.request(
+      /* command =      */ '', // see URL, below.
+      /* payload =      */ payload,
+      /* useKid =       */ true,
+      /* successCodes = */ [200],
+      /* url =          */ /** @type { string } */ (finaliseUrl)
     )
 
     return response

package/lib/acme-requests/NewAccountRequest.js

@@ -1,27 +1,26 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// NewAccountRequest
-//
-// Requests a new account (or existing account if one already exists) and saves
-// the returned kid for future use.
-//
-// See RFC 8555 § 7.3 (Account Management).
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  NewAccountRequest
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import AcmeRequest from '../AcmeRequest.js'
 
 export default class NewAccountRequest extends AcmeRequest {
+  /**
+    Requests a new account (or existing account if one already exists) and saves
+    the returned kid for future use.
+
+    See RFC 8555 § 7.3 (Account Management).
+  */
   async execute () {
     // Set the only required element.
     const payload = { termsOfServiceAgreed: true }
 
     // Note: a 201 (Created) is returned if the account is new, a 200 (Success) is returned
     // ===== if an existing account is found. (RFC 8555 § 7.3 & 7.3.1).
-    const response = await super.execute('newAccount', payload, /* useKid = */ false, /* successCodes = */[200, 201])
+    const response = await super.request('newAccount', payload, /* useKid = */ false, /* successCodes = */[200, 201])
 
     // This is what we will be using in the kid field in the future
     // **in place of** the JWK.

package/lib/acme-requests/NewOrderRequest.js

@@ -1,27 +1,40 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// NewOrderRequest
-//
-// Creates a new order request to start the process of obtaining
-// Let’s Encrypt TLS certificates.
-//
-// See RFC 8555 § 7.1.3 (Order Objects), 7.4 (Applying for Certificate Issuance)
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  NewOrderRequest
 
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
+
+import net from 'node:net'
 import AcmeRequest from '../AcmeRequest.js'
 import Throws from '../util/Throws.js'
 const throws = new Throws()
 
 export default class NewOrderRequest extends AcmeRequest {
-  async execute (configuration = throws.ifMissing()) {
-    const identifiers = configuration.domains.map(domain => { return { type: 'dns', value: domain} })
-    const payload = { identifiers }
+  /**
+    Creates a new order request to start the process of obtaining
+    Let’s Encrypt TLS certificates.
+
+    See RFC 8555 § 7.1.3 (Order Objects), 7.4 (Applying for Certificate Issuance)
 
-    const response = await super.execute('newOrder', payload, /* useKid = */ true, /* successCodes = */ [201])
+    @param { import('../Configuration.js').default | void } configuration
+    @param { string | void } ariCertId
+  */
+  async execute (configuration = throws.ifMissing(), ariCertId = throws.ifMissing()) {
+    const identifiers = /** @type { import('../Configuration.js').default } */(configuration).domains.map(domain => {
+      // Determine whether this is a domain name or an IP address (IPv4 or IPv6)
+      return { type: net.isIP(domain) ? 'ip' : 'dns', value: domain} }
+    )
+    // As of end of December, 2025, Auto Encrypt only supports
+    // Let’s Encrypt’s new short-lived profiles.
+    // See: https://datatracker.ietf.org/doc/draft-ietf-acme-profiles/
+    const payload = { identifiers, profile: 'shortlived' }
+    // If this is a renewal, mark the certificate it’s replacing (ARI)
+    // See: https://letsencrypt.org/2024/04/25/guide-to-integrating-ari-into-existing-acme-clients/#step-6-indicating-which-certificate-is-replaced-by-this-new-order
+    if (ariCertId !== null) {
+      payload.replaces = ariCertId
+    }
+    const response = await super.request('newOrder', payload, /* useKid = */ true, /* successCodes = */ [201])
     return response
   }
 }

package/lib/acme-requests/ReadyForChallengeValidationRequest.js

@@ -1,17 +1,9 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// ReadyForChallengeValidationRequest
-//
-// The client indicates to the server that it is ready for the challenge
-// validation by sending an empty JSON body ("{}") carried in a POST
-// request to the challenge URL (not the authorization URL).
-//
-//                           – RFC 8555 § 7.5.1 (Responding to Challenges)
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  ReadyForChallengeValidationRequest
+
+  Copyright © 2020-present Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import AcmeRequest from '../AcmeRequest.js'
 import Throws from '../util/Throws.js'
@@ -19,15 +11,24 @@ import Throws from '../util/Throws.js'
 const throws = new Throws()
 
 export default class ReadyForChallengeValidationRequest extends AcmeRequest {
+  /**
+    The client indicates to the server that it is ready for the challenge
+    validation by sending an empty JSON body ("{}") carried in a POST
+    request to the challenge URL (not the authorization URL).
+
+      – RFC 8555 § 7.5.1 (Responding to Challenges)
+
+    @param { string | void } challengeUrl
+  */
   async execute (challengeUrl = throws.ifMissing()) {
     const emptyPayload = {}
 
-    const response = await super.execute(
+    const response = await super.request(
       /* command =      */ '', // see URL, below.
       /* payload =      */ emptyPayload,
       /* useKid =       */ true,
       /* successCodes = */ [200],
-      /* url =          */ challengeUrl
+      /* url =          */ /** @type { string } */ (challengeUrl)
     )
 
     return response

package/lib/acmeCsr.js

@@ -1,87 +1,144 @@
-///////////////////////////////////////////////////////////////////////////////
-//
-// ACME CSR
-//
-// Given a regular Certification Request in PEM format, returns an
-// ACME-formatted CSR (single-line PEM without the header or footer and encoded
-// in base64Url instead of base64 format).
-//
-// See RFC 8555 § 7.4 (Applying for Certificate Issuance).
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
-import forge from 'node-forge'
-const DNS = 2 // The ANS.1 type for DNS name.
-
-// Returns a valid ACME-formatted (RFC 8555) CSR.
+/**
+  ACME CSR
+
+  Given a regular Certification Request in PEM format, returns an
+  ACME-formatted CSR (single-line PEM without the header or footer and encoded
+  in base64Url instead of base64 format).
+
+  See RFC 8555 § 7.4 (Applying for Certificate Issuance).
+
+  Copyright © 2020-present Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
+
+import net from 'node:net'
+import crypto from 'node:crypto'
+import {
+  CertificationRequest,
+  CertificationRequestInfo,
+  SubjectPublicKeyInfo,
+  Extensions
+} from './x.509/rfc5280.js'
 
 /**
- * Return an ACME-formatted (RFC 8555) CSR given a list of domains and a Jose JWK.rsaKey.
- *
- * @param {String[]}   domains
- * @param {JWK.rsaKey} key
- * @returns {String} An ACME-formatted CSR in PEM format.
- */
+  Return an ACME-formatted (RFC 8555) CSR given a list of domains and a crypto.KeyObject.
+
+  @param { string[] }   domains
+  @param { crypto.KeyObject } key
+  @returns { string } An ACME-formatted CSR in PEM format.
+*/
 export default function (domains, key) { return pemToAcmeCsr(csrAsPem(domains, key)) }
 
 /**
- * Create a CSR given a list of domains and a Jose JWK.rsaKey.
- *
- * @param {String[]}   domains
- * @param {JWK.rsaKey} key
- * @returns {String} A CSR in PEM format.
- */
+  Create a CSR given a list of domains and a crypto.KeyObject.
+
+  @param { string[] }   domains
+  @param { crypto.KeyObject } key
+  @returns { string } A CSR in PEM format.
+*/
 function csrAsPem (domains, key) {
-  var csr = forge.pki.createCertificationRequest()
+  const altNames = domains.map(domain => {
+    if (net.isIP(domain)) {
+      // IP address.
+      let ipBytes
+      if (net.isIPv4(domain)) {
+        ipBytes = Buffer.from(domain.split('.').map(Number))
+      } else {
+        // IPv6.
+        const parts = domain.split('::')
+        const left = parts[0] ? parts[0].split(':') : []
+        const right = parts[1] ? parts[1].split(':') : []
+        const missing = 8 - (left.length + right.length)
+        const expanded = [...left, ...Array(missing).fill('0'), ...right]
+        ipBytes = Buffer.from(expanded.flatMap(x => {
+            const hex = x.padStart(4, '0')
+            return [parseInt(hex.slice(0, 2), 16), parseInt(hex.slice(2, 4), 16)]
+        }))
+      }
 
-  const keys = {
-    public: forge.pki.publicKeyFromPem(key.toPEM(/* private = */ false)),
-    private: forge.pki.privateKeyFromPem(key.toPEM(/* private = */ true))
-  }
+      return { type: 'iPAddress', value: ipBytes }
+    } else {
+      // Domain.
+      return { type: 'dNSName', value: domain }
+    }
+  })
 
-  csr.publicKey = keys.public
+  const spki = crypto.createPublicKey(key).export({ type: 'spki', format: 'der' })
+  const subjectPKInfo = SubjectPublicKeyInfo.decode(spki, 'der')
 
-  const altNames = domains.map(domain => {
-    return {type: DNS, value: domain}
-  })
+  const certificationRequestInfo = {
+    version: 0,
+    // According to RFC 8555, we *either* need to specify the subject or
+    // the subjectAltName so skip the subject. (We use an empty subject.)
+    subject: { type: 'rdnSequence', value: [] },
+    subjectPKInfo,
+    attributes: [
+      {
+        type: [1, 2, 840, 113549, 1, 9, 14], // extensionRequest
+        values: [
+          Extensions.encode([
+            {
+              extnID: 'subjectAlternativeName',
+              critical: false,
+              extnValue: altNames
+            }
+          ], 'der')
+        ]
+      }
+    ]
+  }
 
-  // According to RFC 8555, we *either* need to specify the subject or the subjectAltName so skip the subject.
-  csr.setAttributes([{
-    name: 'extensionRequest',
-    extensions: [{
-      name: 'subjectAltName',
-      altNames
-    }]
-  }])
+  const tbsDer = CertificationRequestInfo.encode(certificationRequestInfo, 'der')
+  const signature = crypto.sign('sha256', tbsDer, key)
 
-  csr.sign(keys.private, forge.md.sha256.create())
+  const csr = {
+    certificationRequestInfo,
+    signatureAlgorithm: {
+      algorithm: [1, 2, 840, 113549, 1, 1, 11], // sha256WithRSAEncryption
+      parameters: Buffer.alloc(0)
+    },
+    signature: {
+      data: signature,
+      unused: 0
+    }
+  }
 
-  const pem = forge.pki.certificationRequestToPem(csr)
+  const der = CertificationRequest.encode(csr, 'der')
+  const pem = `-----BEGIN CERTIFICATE REQUEST-----\n${der.toString('base64').match(/.{1,64}/g).join('\n')}\n-----END CERTIFICATE REQUEST-----`
   return pem
 }
 
+/**
+  @param { string } csr
+*/
 function pemToAcmeCsr (csr) {
   csr = pemToHeaderlessSingleLinePem(csr)
   csr = base64ToBase64Url(csr)
   return csr
 }
 
-// Strip the PEM headers and covert to a non-newline delimited Base64Url-encoded
-// string as required by RFC 8555 (would be nice if this was explicitly-mentioned in the spec).
+/**
+  Strip the PEM headers and covert to a non-newline delimited Base64Url-encoded
+  string as required by RFC 8555 (would be nice if this was explicitly-mentioned in the spec).
+
+  @param { string } str
+*/
 function pemToHeaderlessSingleLinePem (str) {
   return str
-            .replace('-----BEGIN CERTIFICATE REQUEST-----', '')
-            .replace('-----END CERTIFICATE REQUEST-----', '')
-            .replace(/\n/g, '')
+    .replace('-----BEGIN CERTIFICATE REQUEST-----', '')
+    .replace('-----END CERTIFICATE REQUEST-----', '')
+    .replace(/\n/g, '')
 }
 
-// Convert a base64-encoded string into a base64Url-encoded string.
+/**
+  Convert base64-encoded string into a base64Url-encoded string.
+
+  @param { string } str
+*/
 function base64ToBase64Url (str) {
   return str
-           .replace(/\+/g, '-')
-           .replace(/\//g, '_')
-           .replace(/=/g, '')
-           .replace(/\r/g, '')
+   .replace(/\+/g, '-')
+   .replace(/\//g, '_')
+   .replace(/=/g, '')
+   .replace(/\r/g, '')
 }

package/lib/identities/AccountIdentity.js

@@ -1,23 +1,24 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// AccountIdentity
-//
-// Generates, stores, loads, and saves the account identity. The default
-// account identity file path is:
-//
-// ~/.small-tech.org/auto-encrypt/account.pem
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  AccountIdentity
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import Identity from '../Identity.js'
 import Throws from '../util/Throws.js'
 const throws = new Throws()
 
 export default class AccountIdentity extends Identity {
+  /**
+    Generates, stores, loads, and saves the account identity. The default
+    account identity file path is:
+
+    ~/.small-tech.org/auto-encrypt/account.pem
+
+    @param {import('../Configuration.js').default | void} configuration
+  */
   constructor (configuration = throws.ifMissing()) {
-    super(configuration, 'accountIdentityPath')
+    super(/** @type { import('../Configuration.js').default } */ (configuration), 'accountIdentityPath')
   }
 }

package/lib/identities/CertificateIdentity.js

@@ -3,24 +3,24 @@ import Throws from '../util/Throws.js'
 const throws = new Throws()
 
 /**
- * Generates, stores, loads, and saves the certificate identity. The default
- * certificate identity file path is:
- *
- * ~/.small-tech.org/auto-encrypt/certificate-identity.pem
- *
- * @class CertificateIdentity
- * @extends {Identity}
- * @copyright Aral Balkan, Small Technology Foundation
- * @license AGPLv3 or later
- */
+  Generates, stores, loads, and saves the certificate identity. The default
+  certificate identity file path is:
+
+  ~/.small-tech.org/auto-encrypt/certificate-identity.pem
+
+  @class CertificateIdentity
+  @extends {Identity}
+  @copyright Aral Balkan, Small Technology Foundation
+  @license AGPLv3 or later
+*/
 export default class CertificateIdentity extends Identity {
   /**
-   * Creates an instance of CertificateIdentity.
-   *
-   * @param {Configuration} configuration (Required) Configuration instance.
-   * @memberof CertificateIdentity
-   */
+    Creates an instance of CertificateIdentity.
+
+    @param { import('../Configuration.js').default | void } configuration (Required) Configuration instance.
+    @memberof CertificateIdentity
+  */
   constructor (configuration = throws.ifMissing()) {
-    super(configuration, 'certificateIdentityPath')
+    super(/** @type { import('../Configuration.js').default } */ (configuration), 'certificateIdentityPath')
   }
 }

package/lib/staging/monkeyPatchTls.js

@@ -1,12 +1,12 @@
 /**
- * Monkey patches the TLS module to accept run-time root and intermediary Certificate Authority (CA) certificates.
- *
- * Based on the method provided by David Barral at https://link.medium.com/6xHYLeUVq5.
- *
- * @module
- * @copyright Copyright © 2020 Aral Balkan, Small Technology Foundation.
- * @license AGPLv3 or later.
- */
+  Monkey patches the TLS module to accept run-time root and intermediary Certificate Authority (CA) certificates.
+
+  Based on the method provided by David Barral at https://link.medium.com/6xHYLeUVq5.
+
+  @module
+  @copyright Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  @license AGPLv3 or later.
+*/
 import fs from 'fs'
 import tls from 'tls'
 import path from 'path'
@@ -15,10 +15,10 @@ import { fileURLToPath } from 'url'
 const __dirname = fileURLToPath(new URL('.', import.meta.url))
 
 /**
- * Monkey patches the TLS module to accept the Let’s Encrypt staging certificate.
- *
- * @alias module:lib/MonkeyPatchTls
- */
+  Monkey patches the TLS module to accept the Let’s Encrypt staging certificate. 
+ 
+  @alias module:lib/MonkeyPatchTls
+*/
 export default function monkeyPatchTLS () {
   const originalCreateSecureContext = tls.createSecureContext
 

package/lib/test-helpers/index.js

@@ -1,8 +1,6 @@
-//////////////////////////////////////////////////////////////////////
-//
-// Unit test helpers.
-//
-//////////////////////////////////////////////////////////////////////
+/**
+  Unit test helpers.
+*/
 
 import fs from 'fs'
 import os from 'os'
@@ -27,7 +25,7 @@ export class MockServer {
   static async getInstanceAsync (responseHandler = throws.ifMissing()) {
     this.#isBeingInstantiatedViaAsyncFactoryMethod = true
     const instance = new MockServer(responseHandler)
-    await instance.create(responseHandler)
+    await instance.create()
     this.#isBeingInstantiatedViaAsyncFactoryMethod = false
     return instance
   }
@@ -96,16 +94,16 @@ export class TestContext {
 //
 
 export function timeIt(func) {
-  const startTime = new Date()
+  const startTime = new Date().getTime()
   const returnValue = func()
-  const endTime = new Date()
+  const endTime = new Date().getTime()
   return { returnValue, duration: endTime - startTime }
 }
 
 export async function timeItAsync(func) {
-  const startTime = new Date()
+  const startTime = new Date().getTime()
   const returnValue = await func()
-  const endTime = new Date()
+  const endTime = new Date().getTime()
   return { returnValue, duration: endTime - startTime }
 }
 
@@ -164,16 +162,3 @@ export function createTestSettingsPath () {
   fs.rmSync(testSettingsPath, { recursive: true, force: true })
   return testSettingsPath
 }
-
-export function initialiseStagingConfigurationWithOneDomainAtTestSettingsPath () {
-  Configuration.reset()
-  Configuration.initialise({
-    domains: ['dev.ar.al'],
-    server: new LetsEncryptServer(LetsEncryptServer.type.STAGING),
-    settingsPath: createTestSettingsPath()
-  })
-}
-
-export function setupStagingConfigurationWithOneDomainAtTestSettingsPath () {
-  initialiseStagingConfigurationWithOneDomainAtTestSettingsPath()
-}

package/lib/util/Pluralise.js

@@ -10,10 +10,10 @@ export default class Pluralise {
   }
 
   static isAre (array) {
-    return array.length === 1 ? 'is' : 'are'
+    return array === undefined || array.length === 1 ? 'is' : 'are'
   }
 
   static word (word, array) {
-    return array.length === 1 ? word : `${word}${this.requiresEs(word) ? 'es' : 's'}`
+    return array === undefined || array.length === 1 ? word : `${word}${this.requiresEs(word) ? 'es' : 's'}`
   }
 }