@small-tech/auto-encrypt 4.2.0 → 5.0.0

package/lib/Identity.js

@@ -1,33 +1,39 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// Identity (abstract base class; do not use directly).
-//
-// Generates, stores, loads, and saves an identity from/to the file
-// storage settings path. Meant to be subclassed and instantiated by different
-// singletons for different types of Identity (e.g., AccountIdentity and
-// DomainIdentity).
-//
-// The private key uses the RS256 algorithm with a 2048-bit key.
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  Identity (abstract base class; do not use directly).
+
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import util from 'util'
 import fs from 'fs'
-import jose from 'jose'
+import crypto from 'node:crypto'
 import Throws from './util/Throws.js'
 import log from './util/log.js'
 
 const throws = new Throws({
-  [Symbol.for('UnsupportedIdentityType')]: identityFilePath => `The identity file path passed (${identityFilePath}) is for an unsupported identity type.`
+  [Symbol.for('UnsupportedIdentityType')]: (/** @type {string} */ identityFilePath) => `The identity file path passed (${identityFilePath}) is for an unsupported identity type.`
 })
 
 export default class Identity {
+  /** @type { crypto.KeyObject } */
+  _key
+
+  /**
+    Generates, stores, loads, and saves an identity from/to the file
+    storage settings path. Meant to be subclassed and instantiated by different
+    singletons for different types of Identity (e.g., AccountIdentity and
+    DomainIdentity).
 
+    The private key uses the RS256 algorithm with a 2048-bit key.
+
+    @param { import('./Configuration.js').default | void } configuration
+    @param { string | void } identityFilePathKey
+  */
   constructor (configuration = throws.ifMissing(), identityFilePathKey = throws.ifMissing()) {
-    const identityFilePath = configuration[identityFilePathKey]
+    /** @type {string} */
+    const identityFilePath = /** @type { import('./Configuration.js').default } */ (configuration)[/** @type {string} */ (identityFilePathKey)]
 
     if (identityFilePath === undefined) {
       throws.error(Symbol.for('UnsupportedIdentityType'))
@@ -39,47 +45,67 @@ export default class Identity {
 
     if (!fs.existsSync(this.#identityFilePath)) {
       // The identity file does not already exist, generate and save it.
-      this._key = jose.JWK.generateSync('RSA')
+      const { privateKey } = crypto.generateKeyPairSync('rsa', {
+        modulusLength: 2048
+      })
+      this._key = privateKey
       fs.writeFileSync(this.#identityFilePath, this.privatePEM, 'utf-8')
     } else {
       // Load the key from storage.
       const _privatePEM = fs.readFileSync(this.#identityFilePath, 'utf-8')
-      this._key = jose.JWK.asKey(_privatePEM)
+      this._key = crypto.createPrivateKey(_privatePEM)
     }
+
+    // Pre-calculate thumbprint synchronously using node:crypto as jose.calculateJwkThumbprint is async.
+    // RFC 7638: for RSA, the thumbprint is calculated over 'e', 'kty', and 'n' in lexicographical order.
+    const jwk = this.publicJWK
+    const thumbprintSource = JSON.stringify({
+      e: jwk.e,
+      kty: jwk.kty,
+      n: jwk.n
+    })
+    this.#thumbprint = crypto.createHash('sha256').update(thumbprintSource).digest('base64url')
   }
 
   //
   // Accessors.
   //
 
-  // The JSON Web Key (JWK) instance.
-  // https://github.com/panva/jose/blob/master/docs/README.md#jwk-json-web-key.
-  get key        () { return this._key                                         }
+  // The KeyObject instance.
+  get key () { return this._key }
 
-  // Returns the private key in PEM format.s
-  get privatePEM () { return this._key.toPEM(/* private = */ true)             }
+  // Returns the private key in PEM format.
+  get privatePEM () { return this._key.export({ type: 'pkcs8', format: 'pem' }).toString() }
 
   // The JWK thumbprint as calculated according to
   // RFC 7638 (https://tools.ietf.org/html/rfc7638).
-  get thumbprint () { return this._key.thumbprint                              }
+  get thumbprint () { return this.#thumbprint }
 
   // Returns JWK-formatted objects.
-  // https://github.com/panva/jose/blob/master/docs/README.md#keytojwkprivate.
-  get privateJWK () { return this._key.toJWK(/* private = */ true)             }
-  get publicJWK  () { return this._key.toJWK()                                 }
+  get privateJWK () { return this._key.export({ format: 'jwk' }) }
+  get publicJWK  () {
+    const jwk = this.privateJWK
+    delete jwk.d
+    delete jwk.p
+    delete jwk.q
+    delete jwk.dp
+    delete jwk.dq
+    delete jwk.qi
+    return jwk
+  }
 
   // The file path of the private key (saved in PEM format).
-  get filePath   () { return this.#identityFilePath                             }
+  get filePath   () { return this.#identityFilePath }
 
   //
   // Control access to read-only properties.
   //
-  set key        (value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'key')        }
-  set privatePEM (value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'privatePEM') }
-  set thumbprint (value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'thumbprint') }
-  set privateJWK (value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'privateJWK') }
-  set publicJWK  (value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'publicJWK')  }
-  set filePath   (value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'filePath')   }
+  set key        (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'key')        }
+  set privatePEM (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'privatePEM') }
+  set thumbprint (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'thumbprint') }
+  set privateJWK (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'privateJWK') }
+  set publicJWK  (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'publicJWK')  }
+  set filePath   (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'filePath')   }
 
   // Custom object description for console output (for debugging).
   [util.inspect.custom] () {
@@ -93,7 +119,7 @@ export default class Identity {
 
       ## Properties
 
-      - .key        : the jose.JWK.RSAKey instance
+      - .key        : the crypto.KeyObject instance
       - .privatePEM : PEM representation of the private key
       - .thumbprint : JWK thumbprint calculated according to RFC 7638
       - .privateJWK : JavaScript object representation of JWK (private key)
@@ -107,5 +133,7 @@ export default class Identity {
   //
   // Private
   //
+  /** @type {string} */
   #identityFilePath = null
+  #thumbprint = null
 }

package/lib/LetsEncryptServer.js

@@ -2,15 +2,15 @@ import util from 'util'
 
 export default class LetsEncryptServer {
   /**
-   * Enumeration.
-   *
-   * @property PRODUCTION Use the production server.
-   * @property STAGING Use the staging server.
-   * @property PEBBLE Use a local pebble testing server.
-   * @property MOCK Use local mock server.
-   * @readonly
-   * @static
-   */
+    Enumeration.
+
+    @property PRODUCTION Use the production server.
+    @property STAGING Use the staging server.
+    @property PEBBLE Use a local pebble testing server.
+    @property MOCK Use local mock server.
+    @readonly
+    @static
+  */
   static type = {
     PRODUCTION: 0,
     STAGING: 1,
@@ -19,10 +19,10 @@ export default class LetsEncryptServer {
   }
 
   /**
-   *Creates an instance of LetsEncryptServer.
-   * @param {LetsEncryptServer.type} type
-   * @memberof LetsEncryptServer
-   */
+    Creates an instance of LetsEncryptServer.
+    @param {Number} type
+    @memberof LetsEncryptServer
+  */
   constructor (type) {
     this.#type = type
   }
@@ -50,7 +50,7 @@ export default class LetsEncryptServer {
   #endpoints = [
     'https://acme-v02.api.letsencrypt.org/directory',
     'https://acme-staging-v02.api.letsencrypt.org/directory',
-    'https://localhost:14000/dir',
-    'http://localhost:9829/directory'
+    'https://127.0.0.1:14000/dir',
+    'http://127.0.0.1:9829/directory'
   ]
 }

package/lib/Nonce.js

@@ -1,36 +1,41 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// Nonce
-//
-// In order to protect ACME resources from any possible replay attacks,
-// ACME POST requests have a mandatory anti-replay mechanism.  This
-// mechanism is based on the server maintaining a list of nonces that it
-// has issued, and requiring any signed request from the client to carry
-// such a nonce. – RFC 8555 § 6.5
-//
-// Before sending a POST request to the server, an ACME client needs to
-// have a fresh anti-replay nonce to put in the "nonce" header of the
-// JWS.  In most cases, the client will have gotten a nonce from a
-// previous request.  However, the client might sometimes need to get a
-// new nonce, e.g., on its first request to the server or if an existing
-// nonce is no longer valid. – RFC 8555 § 7.2
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
-
-import prepareRequest from 'bent'
+/**
+  Nonce
+
+  In order to protect ACME resources from any possible replay attacks,
+  ACME POST requests have a mandatory anti-replay mechanism.  This
+  mechanism is based on the server maintaining a list of nonces that it
+  has issued, and requiring any signed request from the client to carry
+  such a nonce. – RFC 8555 § 6.5
+
+  Before sending a POST request to the server, an ACME client needs to
+  have a fresh anti-replay nonce to put in the "nonce" header of the
+  JWS.  In most cases, the client will have gotten a nonce from a
+  previous request.  However, the client might sometimes need to get a
+  new nonce, e.g., on its first request to the server or if an existing
+  nonce is no longer valid. – RFC 8555 § 7.2
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
+
 import log from './util/log.js'
 import Throws from './util/Throws.js'
 
 const throws = new Throws()
 
+/**
+  @typedef { import('./Directory.js').default } Directory
+*/
+
 export default class Nonce {
+  /**
+    @param { Directory | void } directory
+  */
   constructor (directory = throws.ifMissing()) {
-    this.#directory = directory
+    this.#directory = /** @type { Directory } */ (directory);
   }
 
+  /** @param {string} freshNonce */ 
   set (freshNonce) {
     if (freshNonce === undefined || freshNonce === null) {
       log('   ⚠    ❨auto-encrypt❩ nonce.set called with undefined/null. Not saving nonce. No effect on functionality. ')
@@ -59,9 +64,9 @@ export default class Nonce {
       // code 200 (OK).  The server MUST also respond to GET requests for this
       // resource, returning an empty body (while still providing a Replay-
       // Nonce header) with a status code of 204 (No Content). – RFC 8555 § 7.2
-      const newNonceRequest = prepareRequest('HEAD', this.#directory.newNonceUrl)
-      const newNonceResponse = await newNonceRequest()
-      freshNonce = newNonceResponse.headers['replay-nonce']
+
+      const newNonceResponse = await fetch(this.#directory.newNonceUrl, { method: 'HEAD' })
+      freshNonce = newNonceResponse.headers.get('replay-nonce')
 
       // Note: we do not persist the freshNonce in this.#freshNonce as we
       // ===== are returning it and thus we consider it used.
@@ -70,6 +75,10 @@ export default class Nonce {
   }
 
   // Private
+
+  /** @type { Directory } */
   #directory = null
+
+  /** @type { string } */
   #freshNonce = null
 }

package/lib/Order.js

@@ -1,16 +1,14 @@
-///////////////////////////////////////////////////////////////////////////////
-//
-// Order
-//
-// (Please use async factory method Order.getInstanceAsync() to instantiate.)
-//
-// Represents a Let’s Encrypt order.
-// 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.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  Order
+
+  (Please use async factory method Order.getInstanceAsync() to instantiate.)
+
+  Represents a Let’s Encrypt order.
+  See RFC 8555 § 7.1.3 (Order Objects), 7.4 (Applying for Certificate Issuance)
+
+  Copyright © 2020-present Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import fsPromises from 'fs/promises'
 import Authorisation from './Authorisation.js'
@@ -35,17 +33,35 @@ export default class Order {
   #order               = null
   #certificate         = null
   #certificateIdentity = null
+
+  /** @type { Array<Authorisation> } */
   #authorisations      = []
 
+  /** @type { import('./Configuration.js').default } */
+  configuration
+
+  /** @type { import('./identities/AccountIdentity.js').default } */
+  accountIdentity
+
+  /** @type { string } */
+  ariCertId
+
   //
   // Factory method (async).
   //
   static isBeingInstantiatedViaFactoryMethod = false
 
-  static async getInstanceAsync (configuration = throws.ifMissing(), accountIdentity = throws.ifMissing()) {
+  /**
+    Async factory method. Use this to instantiate this class.
+    
+    @param { import('./Configuration.js').default | void } configuration (Required) Configuration instance.
+    @param { import('./identities/AccountIdentity.js').default | void } accountIdentity (Required) Account identity.
+    @param { string | void } ariCertId (Required) ARI certificate ID.
+  */
+  static async createAsync (configuration = throws.ifMissing(), accountIdentity = throws.ifMissing(), ariCertId = throws.ifMissing()) {
     Order.isBeingInstantiatedViaFactoryMethod = true
-    const instance = Order.instance = new Order(configuration, accountIdentity)
-    await Order.instance.init()
+    const instance = new Order(configuration, accountIdentity, ariCertId)
+    await instance.init()
     return instance
   }
 
@@ -74,35 +90,37 @@ export default class Order {
     this.#order = this.#data.body
   }
 
-  set certificate         (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'certificate'))         }
-  set certificateIdentity (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'certificateIdentity')) }
-  set authorisations      (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'authorisations'))      }
-  set finaliseUrl         (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'finaliseUrl'))         }
-  set identifiers         (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'identifiers'))         }
-  set authorisations      (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'authorisations'))      }
-  set status              (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'status'))              }
-  set expires             (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'expires'))             }
-  set certificateUrl      (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'certificateUrl'))      }
-  set headers             (value) { throws.error(Symbol.for('ReadOnlyAccessorError', 'headers'))             }
+  set certificate         (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'certificate')         }
+  set certificateIdentity (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'certificateIdentity') }
+  set authorisations      (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'authorisations')      }
+  set finaliseUrl         (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'finaliseUrl')         }
+  set identifiers         (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'identifiers')         }
+  set status              (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'status')              }
+  set expires             (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'expires')             }
+  set certificateUrl      (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'certificateUrl')      }
+  set headers             (_value) { throws.error(Symbol.for('ReadOnlyAccessorError'), 'headers')             }
 
   //
   // Private.
   //
 
   /**
-   * Creates an instance of Order.
-   *
-   * @param {Configuration} configuration (Required) Configuration instance.
-   */
-  constructor (configuration = throws.ifMissing(), accountIdentity = throws.ifMissing()) {
+    Creates an instance of Order.
+
+    @param { import('./Configuration.js').default | void } configuration (Required) Configuration instance.
+    @param { import('./identities/AccountIdentity.js').default | void } accountIdentity (Required) Account identity.
+    @param { string | void } ariCertId (Required) ARI certificate ID.
+  */
+  constructor (configuration = throws.ifMissing(), accountIdentity = throws.ifMissing(), ariCertId = throws.ifMissing()) {
     // Ensure singleton access.
     if (Order.isBeingInstantiatedViaFactoryMethod === false) {
       throw new Error('Order constructor is private. Please instantiate using :await Order.getInstanceAsync().')
     }
 
-    this.configuration   = configuration
-    this.domains         = configuration.domains
-    this.accountIdentity = accountIdentity
+    this.configuration   = /** @type { import('./Configuration.js').default } */ (configuration)
+    this.domains         = this.configuration.domains
+    this.accountIdentity = /** @type { import('./identities/AccountIdentity.js').default } */ (accountIdentity)
+    this.ariCertId       = /** @type { string } */ (ariCertId)
 
     Order.isBeingInstantiatedViaFactoryMethod = false
   }
@@ -110,10 +128,18 @@ export default class Order {
 
   async init () {
     try {
-      this.data = await ((new NewOrderRequest()).execute(this.configuration))
+      this.data = await ((new NewOrderRequest()).execute(this.configuration, this.ariCertId))
     } catch (error) {
-      // TODO: Handle error.
-      throw new Error(error)
+      if (this.ariCertId !== null) {
+        log(`   ⚠    ❨auto-encrypt❩ Failed to create order with ARI replacement info (${error.message}). Retrying without it…`)
+        try {
+          this.data = await ((new NewOrderRequest()).execute(this.configuration, null))
+        } catch (retryError) {
+          throw new Error(retryError)
+        }
+      } else {
+        throw new Error(error)
+      }
     }
 
     this.#authorisations = []
@@ -128,7 +154,7 @@ export default class Order {
     // instances will handle settings up to answer their challenges themselves.
     await asyncForEach(
       this.data.body.authorizations,
-      async authorisationUrl => {
+      async ( /** @type { string } */ authorisationUrl ) => {
         // An authorisation only returns when it is validated.
         // TODO: handle errors.
         const authorisation = await Authorisation.getInstanceAsync(authorisationUrl, this.accountIdentity)
@@ -159,7 +185,7 @@ export default class Order {
     this.#certificateIdentity = new CertificateIdentity(this.configuration)
 
     // Generate a Certificate Signing Request in the unique format that ACME expects.
-    const csr = await acmeCsr(this.domains, this.certificateIdentity.key)
+    const csr = acmeCsr(this.domains, this.certificateIdentity.key)
 
     let numAttempts = 0
     while (this.status !== 'valid' && this.status !== 'invalid') {

package/lib/acme-requests/AuthorisationRequest.js

@@ -1,15 +1,13 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// AuthorisationRequest
-//
-// Representations an authorisation that needs to be fulfilled.
-//
-// See RFC 8555 § 7.5 (Identifier Authorisation)
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  AuthorisationRequest
+
+  Representations an authorisation that needs to be fulfilled.
+
+  See RFC 8555 § 7.5 (Identifier Authorisation)
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import AcmeRequest from '../AcmeRequest.js'
 import Throws from '../util/Throws.js'
@@ -17,6 +15,9 @@ import Throws from '../util/Throws.js'
 const throws = new Throws()
 
 export default class AuthorisationRequest extends AcmeRequest {
+  /**
+    @param { string | void } authorisationUrl
+  */
   async execute (authorisationUrl = throws.ifMissing()) {
     // This is a POST-as-GET request so it doesn’t have a payload.
     // See RFC 8555 § 6.3 (GET and POST-as-GET requests).
@@ -24,12 +25,12 @@ export default class AuthorisationRequest extends AcmeRequest {
 
     // 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(
+    const response = await super.request(
       /* command =      */ '', // see URL, below.
       /* payload =      */ noPayload,
       /* useKid =       */ true,
       /* successCodes = */ [200],
-      /* url =          */ authorisationUrl
+      /* url =          */ /** @type { string } */ (authorisationUrl)
     )
     return response
   }

package/lib/acme-requests/CertificateRequest.js

@@ -1,16 +1,9 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// CertificateRequest
-//
-// Requests download of the TLS certificate for a validated order.
-//
-// See RFC 8555 § 7.4.2 (Downloading the Certificate).
-// The certificate type is application/pem-certificate-chain (RFC 8555 § 9.1).
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  CertificateRequest
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import AcmeRequest from '../AcmeRequest.js'
 import Throws from '../util/Throws.js'
@@ -18,6 +11,14 @@ import Throws from '../util/Throws.js'
 const throws = new Throws()
 
 export default class CertificateRequest extends AcmeRequest {
+  /**
+    Requests download of the TLS certificate for a validated order.
+
+    See RFC 8555 § 7.4.2 (Downloading the Certificate).
+    The certificate type is application/pem-certificate-chain (RFC 8555 § 9.1).
+
+    @param { string | void } certificateUrl
+  */
   async execute (certificateUrl = throws.ifMissing()) {
     // This is a POST-as-GET request so it doesn’t have a payload.
     // See RFC 8555 § 6.3 (GET and POST-as-GET requests).
@@ -25,12 +26,12 @@ export default class CertificateRequest extends AcmeRequest {
 
     // 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(
+    const response = await super.request(
       /* command =                 */ '', // see URL, below.
       /* payload =                 */ noPayload,
       /* useKid =                  */ true,
       /* successCodes =            */ [200],
-      /* url =                     */ certificateUrl,
+      /* url =                     */ /** @type { string } */ (certificateUrl),
       /* parseResponseBodyAsJSON = */ false
     )
 

package/lib/acme-requests/CheckOrderStatusRequest.js

@@ -1,18 +1,10 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// CheckOrderStatusRequest
-//
-// If the order was not valid at time of finalise call (this doesn’t happen
-// as per the Let’s Encrypt implementation – Boulder – but could under RFC 8555),
-// then we need to send a POST-as-GET request to the finalise url to wait until
-// the order is valid.
-//
-// See RFC 8555 § 7.4 (Applying for Certificate Issuance).
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+
+  CheckOrderStatusRequest
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import AcmeRequest from '../AcmeRequest.js'
 import Throws from '../util/Throws.js'
@@ -20,16 +12,26 @@ import Throws from '../util/Throws.js'
 const throws = new Throws()
 
 export default class CheckOrderStatusRequest extends AcmeRequest {
+  /**
+    If the order was not valid at time of finalise call (this doesn’t happen
+    as per the Let’s Encrypt implementation – Boulder – but could under RFC 8555),
+    then we need to send a POST-as-GET request to the finalise url to wait until
+    the order is valid.
+
+    See RFC 8555 § 7.4 (Applying for Certificate Issuance).
+
+    @param { string | void } orderUrl
+  */
   async execute (orderUrl = throws.ifMissing()) {
 
     const payload = '' // POST-as-GET
 
-    const response = await super.execute(
+    const response = await super.request(
         /* command =      */ '', // see URL, below.
         /* payload =      */ payload,
         /* useKid =       */ true,
         /* successCodes = */ [200],
-        /* url =          */ orderUrl
+        /* url =          */ /** @type { string } */ (orderUrl)
     )
 
     return response