@small-tech/auto-encrypt 4.3.0 → 5.0.0

package/lib/AcmeRequest.js

@@ -1,15 +1,13 @@
 /**
- * Abstract base request class for carrying out signed ACME requests over HTTPS.
- *
- * @module
- * @copyright Copyright © 2020 Aral Balkan, Small Technology Foundation.
- * @license AGPLv3 or later.
- */
+  Abstract base request class for carrying out signed ACME requests over HTTPS.
+
+  @module
+  @copyright Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  @license AGPLv3 or later.
+*/
 
 import packageJson from '../package.json' with { type: 'json' }
-import jose from 'jose'
-import prepareRequest from 'bent'
-import types from '../typedefs/lib/AcmeRequest.js'
+import crypto from 'node:crypto'
 import Nonce from './Nonce.js'
 import Throws from './util/Throws.js'
 import log from './util/log.js'
@@ -21,40 +19,57 @@ const throws = new Throws({
   [Symbol.for('AcmeRequest.accountNotSetError')]:
     () => 'You cannot issue calls that require an account KeyId without first injecting a reference to the account',
 
-  [Symbol.for('AcmeRequest.requestError')]: error => `(${error.status} ${error.type} ${error.detail})`
+  [Symbol.for('AcmeRequest.requestError')]:
+    (/** @type {{ status: number, type: string, detail: string }} */ error) => `(${error.status} ${error.type} ${error.detail})`
 })
 
 /**
- * Abstract base request class for carrying out signed ACME requests over HTTPS.
- *
- * @alias module:lib/AcmeRequest
- */
+  Abstract base request class for carrying out signed ACME requests over HTTPS.
+
+  @alias module:lib/AcmeRequest
+*/
 export default class AcmeRequest {
   static initialised = false
+  static initialisationPromise = null
+
+  /** @import('./Directory.js').default */
   static directory = null
+
+  /** @import('./identities/AccountIdentity.js').default */
   static accountIdentity = null
+
   static nonce = null
   static __account = null
   /** @type {string} */
   static autoEncryptVersion = packageJson.version
 
+  /**
+    Initialise the AcmeRequest class with the directory and account identity.
+
+    @param {import('./Directory.js').default|void} directory - (Required) The ACME directory.
+
+    @param {import('./identities/AccountIdentity.js').default|void} accountIdentity - (Required) The account identity.
+  */
   static initialise (directory = throws.ifMissing(), accountIdentity = throws.ifMissing()) {
-    this.directory = directory
-    this.accountIdentity = accountIdentity
-    this.nonce = new Nonce(directory)
-    this.initialised = true
+    AcmeRequest.directory = /** @type { import('./Directory.js').default } */ (directory)
+    AcmeRequest.accountIdentity = accountIdentity
+    AcmeRequest.nonce = new Nonce(AcmeRequest.directory)
+    AcmeRequest.initialised = true
   }
 
   static uninitialise () {
-    this.directory = null
-    this.accountIdentity = null
-    this.nonce = null
-    this.__account = null
-    this.initialised = false
+    AcmeRequest.directory = null
+    AcmeRequest.accountIdentity = null
+    AcmeRequest.nonce = null
+    AcmeRequest.__account = null
+    AcmeRequest.initialised = false
+    AcmeRequest.initialisationPromise = null
   }
 
-  static set account (_account = throws.ifMissing()) { this.__account = _account }
-  static get account () { return this.__account }
+  static set account (/** import('./Account.js').default */ _account) { AcmeRequest.__account = _account }
+
+  /** @returns { import('./Account.js').default } */
+  static get account () { return AcmeRequest.__account }
 
   constructor () {
     if (!AcmeRequest.initialised) {
@@ -63,17 +78,21 @@ export default class AcmeRequest {
   }
 
   /**
-   * Executes a remote Let’s Encrypt command and either returns the result or throws.
-   *
-   * @param {String}        command                        Name of {@link Directory} command to invoke e.g. 'newAccount'
-   * @param {Object|String} payload                        Object to use as payload. For no payload, pass empty string.
-   * @param {Boolean}       useKid                         Use Key ID (true) or public JWK (false) (see RFC 8555 § 6.2).
-   * @param {Number[]}      [successCodes=[200]]           Return codes accepted as success. Any other code throws.
-   * @param {String}        [url=null]                     If specified, use this URL, ignoring the command parameter.
-   * @param {Boolean}       [parseResponseBodyAsJSON=true] Parse response body as JSON (true) or as string (false).
-   * @returns {types.ResponseObject}
-   */
-  async execute (
+    Executes a remote Let’s Encrypt command and either returns the result or throws.
+
+    @param {string|void} command - (Required) Name of {@link Directory} command to invoke e.g. 'newAccount'.
+
+    @param {Object|string|void} payload - (Required) Object to use as payload. For no payload, pass empty string.
+
+    @param {boolean} [useKid=true] - Use Key ID (true) or public JWK (false) (see RFC 8555 § 6.2).
+
+    @param {Number[]} [successCodes=[200]] - Optional array of codes that signals success. Any other code throws.
+
+    @param {string} [url=null] - If specified, use this URL, ignoring the command parameter.
+
+    @param {boolean} [parseResponseBodyAsJSON=true] - Parse response body as JSON (true) or as string (false).
+  */
+  async request (
     command                 = throws.ifMissing(),
     payload                 = throws.ifMissing(),
     useKid                  = true,
@@ -83,76 +102,90 @@ export default class AcmeRequest {
   ) {
     if (useKid && AcmeRequest.account === null) { throws.error(Symbol.for('AcmeRequest.accountNotSetError')) }
 
-    const preparedRequest = await this.prepare(command, payload, useKid, successCodes, url)
+    const preparedRequest = await this.prepare(/** @type { string } */ (command), payload, useKid, successCodes, url)
     const responseObject = await this._execute(preparedRequest, parseResponseBodyAsJSON)
     return responseObject
   }
 
   /**
-   * Executes a prepared request.
-   *
-   * @param {types.PreparedRequest} preparedRequest         The prepared request, ready to be executed.
-   * @param {Boolean}               parseResponseBodyAsJSON Should the request body be parsed as JSON (true) or should
-   *                                                        the native response object be returned (false).
-   * @returns {types.ResponseObject}
-   */
+    Executes a prepared request.
+
+    @param {Awaited<ReturnType<typeof this.prepare>>|void} preparedRequest - (Required) The prepared request, ready to be executed.
+
+    @param {boolean|void} parseResponseBodyAsJSON - (Required) Should the request body be parsed as JSON (true) or should the native response object be returned (false).
+  */
   async _execute (preparedRequest = throws.ifMissing(), parseResponseBodyAsJSON = throws.ifMissing()) {
-    const { signedRequest, httpsRequest, httpsHeaders, originalRequestDetails } = preparedRequest
+    const { signedRequest, httpsRequest, httpsHeaders, originalRequestDetails } = /** @type {Awaited<ReturnType<typeof this.prepare>>} */ (preparedRequest)
 
     let response, errorHeaders, errorBody
     try {
       response = await httpsRequest('', signedRequest, httpsHeaders)
     } catch (error) {
       errorBody = error.responseBody
-      errorHeaders = error.responseHeaders
-    }
+      errorHeaders = error.headers
+
+      // The error body is a promise. Wait for it to resolve.
+      if (errorBody) {
+        const errorBodyBuffer = await errorBody
+        const errorBodyString = Buffer.from(errorBodyBuffer).toString('utf-8')
+
+        // If the error body is JSON (i.e., as expected to be returned from Let’s Encrypt),
+        // handle it. If not (for whatever reason), still handle the error gracefully.
+        let acmeError = null
+        try {
+          acmeError = JSON.parse(errorBodyString)
+        } catch (_) {
+          acmeError = {
+            status: -1,
+            type: 'Unexpected error',
+            detail: errorBodyString
+          }
+        }
 
-    // The error body is a promise. Wait for it to resolve.
-    if (errorBody) {
-      const errorBodyBuffer = await errorBody
-
-      // If the error body is JSON (i.e., as expected to be returned from Let’s Encrypt),
-      // handle it. If not (for whatever reason), still handle the error gracefully.
-      let error = null
-      const errorBodyString = errorBodyBuffer.toString('utf-8')
-
-      try {
-        error = JSON.parse(errorBodyString)
-      } catch (_) {
-        error = {
-          status: -1,
-          type: 'Unexpected error',
-          detail: errorBodyString
+        // If it’s valid JSON but doesn’t have the expected ACME error fields, wrap it.
+        if (acmeError && acmeError.status === undefined && acmeError.type === undefined) {
+          acmeError = {
+            status: -1,
+            type: 'Unexpected JSON error',
+            detail: errorBodyString
+          }
         }
-      }
 
-      // According to RFC 8555 § 6.5, a bad nonce error should result in retry attempt.
-      if (error.status === 400 && error.type === 'urn:ietf:params:acme:error:badNonce') {
-        log('   🔄    ❨auto-encrypt❩ Server returned a bad nonce error. Retrying with provided nonce. (RFC 8555 § 6.5)')
-        const serverProvidedNonce = errorHeaders['replay-nonce']
-
-        // Take the original request details (arguments array passed to the prepare() method) and
-        // re-prepare and retry the request, replacing the nonce (last argument), with the one provided
-        // by the ACME server.
-        const originalRequestWithServerProvidedNonce = originalRequestDetails
-        originalRequestWithServerProvidedNonce[originalRequestWithServerProvidedNonce.length-1] = serverProvidedNonce
-
-        return await this._execute(
-          await this.prepare(...originalRequestWithServerProvidedNonce),
-          parseResponseBodyAsJSON
-        )
+        // According to RFC 8555 § 6.5, a bad nonce error should result in retry attempt.
+        if (acmeError.status === 400 && acmeError.type === 'urn:ietf:params:acme:error:badNonce') {
+          log('   🔄    ❨auto-encrypt❩ Server returned a bad nonce error. Retrying with provided nonce. (RFC 8555 § 6.5)')
+          const serverProvidedNonce = errorHeaders && errorHeaders['replay-nonce']
+
+          if (!serverProvidedNonce) {
+            throws.error(Symbol.for('AcmeRequest.requestError'), acmeError)
+          }
+
+          // Take the original request details (arguments array passed to the prepare() method) and
+          // re-prepare and retry the request, replacing the nonce (last argument), with the one provided
+          // by the ACME server.
+          const originalRequestWithServerProvidedNonce = [...originalRequestDetails]
+          originalRequestWithServerProvidedNonce[originalRequestWithServerProvidedNonce.length - 1] = serverProvidedNonce
+
+          return await this._execute(
+            await this.prepare(...originalRequestWithServerProvidedNonce),
+            parseResponseBodyAsJSON
+          )
+        }
+
+        throws.error(Symbol.for('AcmeRequest.requestError'), acmeError)
       }
 
-      throws.error(Symbol.for('AcmeRequest.requestError'), error)
+      // If we got here, it's a non-ACME error (e.g. network error).
+      throw error
     }
 
     // Always save the fresh nonce returned from API calls.
-    const freshNonce = response.headers['replay-nonce']
+    const freshNonce = response.headers.get('replay-nonce')
     AcmeRequest.nonce.set(freshNonce)
 
     // The response returned is the raw response object. Let’s consume
     // it and return a more relevant response.
-    const headers = response.headers
+    const headers = Object.fromEntries(response.headers.entries())
     const responseBodyBuffer = await this.getBuffer(response)
     let body = responseBodyBuffer.toString('utf-8')
     if (parseResponseBodyAsJSON) {
@@ -166,36 +199,31 @@ export default class AcmeRequest {
   }
 
   /**
-   * Concatenates the output of a stream and returns a buffer. Taken from the bent module.
-   *
-   * @param {stream} stream A Node stream.
-   * @returns {Promise<Buffer>}      The concatenated output of the Node stream.
-   */
-  getBuffer (stream) {
-    return new Promise((resolve, reject) => {
-      const parts = []
-      stream.on('error', reject)
-      stream.on('end', () => resolve(Buffer.concat(parts)))
-      stream.on('data', d => parts.push(d))
-    })
+    Returns a buffer from the response body.
+
+    @param {Response} response - (Required) A fetch response.
+
+    @returns {Promise<Buffer>} The body of the response as a buffer.
+  */
+  async getBuffer (response) {
+    return Buffer.from(await response.arrayBuffer())
   }
 
   /**
-   * Separate the preparation of a request from the execution of it so we can easily test
-   * that different request configurations conform to our expectations.
-   *
-   * @param {String}        command              (Required) Name of Let’s Encrypt command to invoke (see Directory).
-   *                                             (sans 'Url' suffix). e.g. 'newAccount', 'newOrder', etc.
-   * @param {Object|String} payload              (Required) Either an object to use as the payload or, if there is no
-   *                                             payload, an empty string.
-   * @param {Boolean}       useKid               (Required) Should request use a Key ID (true) or, public JWK (false).
-   *                                             (See RFC 8555 § 6.2 Request Authentication)
-   * @param {Number[]}      [successCodes=[200]] Optional array of codes that signals success. Any other code throws.
-   * @param {String}        [url=null]           If specified, will use this URL directly, ignoring the value in
-   *                                             the command parameter.
-   *
-   * @returns {types.PreparedRequest}
-   */
+    Separate the preparation of a request from the execution of it so we can easily test that different request configurations conform to our expectations.
+
+    @param {string|void} command - (Required) Name of Let’s Encrypt command to invoke (see Directory; sans 'Url' suffix). e.g. 'newAccount', 'newOrder', etc.
+
+    @param {Object|string|void} payload - (Required) Either an object to use as the payload or, if there is no payload, an empty string.
+
+    @param {boolean|void} useKid - (Required) Should request use a Key ID (true) or, public JWK (false). (See RFC 8555 § 6.2 Request Authentication.)
+
+    @param {Number[]} [successCodes=[200]] - Optional array of codes that signals success. Any other code throws.
+
+    @param {string} [url=null] - If specified, will use this URL directly, ignoring the value in the command parameter.
+
+    @param {Nonce} [nonce=null] - If specified, the nonce to use.
+  */
   async prepare (
     command = throws.ifMissing(),
     payload = throws.ifMissing(),
@@ -204,15 +232,21 @@ export default class AcmeRequest {
     url = null,
     nonce = null
   ) {
+    command = /** @type { String } */ (command)
+    payload = /** @type { Object | String } */ (payload)
+    useKid = /** @type { Boolean } */ (useKid)
+
     if (useKid && AcmeRequest.account === null) { throws.error(Symbol.for('AcmeRequest.accountNotSetError')) }
 
-    // We will also return the original request details in case the call needs to be retried later.
-    // Note: we have to create our own object using the actual individual argument values instead of
-    // ===== the arguments array as the latter does not reflect default parameters.
+    // We will also return the original request details in case the call needs to be retried later. Note: we have to create our own object using the actual individual argument values instead of the arguments array as the latter does not reflect default parameters.
     const originalRequestDetails = [command, payload, useKid, successCodes, url, nonce]
 
     url = url || AcmeRequest.directory[`${command}Url`]
 
+    // Capture static state at the beginning of method to avoid race conditions if uninitialise() is called while awaiting a nonce. (This should really only be a race condition encountered during unit tests, but still.)
+    const account = AcmeRequest.account
+    const accountIdentity = AcmeRequest.accountIdentity
+
     const protectedHeader = {
       alg: 'RS256',
       nonce: nonce || await AcmeRequest.nonce.get(),
@@ -221,13 +255,30 @@ export default class AcmeRequest {
 
     if (useKid) {
       // The kid is the account location URL as previously returned by the ACME server.
-      protectedHeader.kid = AcmeRequest.account.kid
+      protectedHeader.kid = account.kid
     } else {
       // If we’re not using the kid, we must use the public JWK (see RFC 8555 § 6.2 Request Authentication)
-      protectedHeader.jwk = AcmeRequest.accountIdentity.publicJWK
+      protectedHeader.jwk = accountIdentity.publicJWK
     }
 
-    const signedRequest = jose.JWS.sign.flattened(payload, AcmeRequest.accountIdentity.key, protectedHeader)
+    // Flatten the payload and sign it and use the signature in the signed request.
+    // (We were previously using jose.FlattenedSign for this.)
+
+    const encoder = new TextEncoder()
+    const protectedHeaderBase64 = Buffer.from(encoder.encode(JSON.stringify(protectedHeader))).toString('base64url')
+    const payloadBase64 = Buffer.from(typeof payload === 'string' ? encoder.encode(payload) : encoder.encode(JSON.stringify(payload))).toString('base64url')
+
+    const signature = crypto.sign(
+      'sha256',
+      Buffer.from(`${protectedHeaderBase64}.${payloadBase64}`),
+      accountIdentity.key
+    )
+
+    const signedRequest = {
+      protected: protectedHeaderBase64,
+      payload: payloadBase64,
+      signature: signature.toString('base64url')
+    }
 
     const httpsHeaders = {
       'Content-Type': 'application/jose+json',
@@ -235,8 +286,27 @@ export default class AcmeRequest {
       'Accept-Language': 'en-US'
     }
 
-    // Prepare a new account request (RFC 8555 § 7.3 Account Management)
-    const httpsRequest = prepareRequest('POST', url, /* acceptable responses are */ ...successCodes)
+    // Carries out an https request.
+    const httpsRequest = async (/** @type {string} */ _path, /** @type {any} */ body, /** @type {any} */ headers) => {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body)
+      })
+
+      if (!successCodes.includes(response.status)) {
+        const error = new Error(`HTTP Error: ${response.status} ${response.statusText}`)
+        // @ts-ignore Error object mixin.
+        error.status = response.status
+        // @ts-ignore Error object mixin.
+        error.headers = Object.fromEntries(response.headers.entries())
+        // @ts-ignore Error object mixin.
+        error.responseBody = response.arrayBuffer().then(Buffer.from)
+        throw error
+      }
+
+      return response
+    }
 
     return {
         protectedHeader,

package/lib/Authorisation.js

@@ -1,17 +1,16 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// Authorisation
-//
-// (Use the async static get() method to await a fully-resolved instance.)
-//
-// Holds a single authorisation object. Note that the only authorisation type
-// supported by this library is HTTP-01 and this is hardcoded in its
-// behaviour. See RFC 8555 § 7.5, 7.5.1.
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+
+  Authorisation
+
+  (Use the async static get() method to await a fully-resolved instance.)
+
+  Holds a single authorisation object. Note that the only authorisation type
+  supported by this library is HTTP-01 and this is hardcoded in its
+  behaviour. See RFC 8555 § 7.5, 7.5.1.
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import EventEmitter from 'events'
 import log from './util/log.js'
@@ -20,10 +19,23 @@ import ReadyForChallengeValidationRequest from './acme-requests/ReadyForChalleng
 import HttpServer from './HttpServer.js'
 import waitFor from './util/waitFor.js'
 
+/**
+  @typedef {{
+    type: string,
+    url: string,
+    token: string,
+    status: string
+  }} Challenge
+*/
+
 export default class Authorisation extends EventEmitter {
 
   // Async factory method. Use this to instantiate.
   // TODO: add check to ensure factory method is used.
+  /**
+    @param {string} authorisationUrl
+    @param {import('./identities/AccountIdentity.js').default } accountIdentity
+  */
   static async getInstanceAsync (authorisationUrl, accountIdentity) {
     const authorisation = new Authorisation(authorisationUrl, accountIdentity)
     await authorisation.init()
@@ -32,6 +44,7 @@ export default class Authorisation extends EventEmitter {
 
   // Events
   static VALIDATED = 'validated'
+  static ERROR = 'error'
 
   //
   // Accessors.
@@ -40,13 +53,17 @@ export default class Authorisation extends EventEmitter {
   get domain ()    { return this._domain   }
   get challenge () { return this._challenge }
 
-  set domain (value)    { throw new Error('domain is a read-only property')    }
-  set challenge (value) { throw new Error('challenge is a read-only property') }
+  set domain (_value)    { throw new Error('domain is a read-only property')    }
+  set challenge (_value) { throw new Error('challenge is a read-only property') }
 
   //
   // Private.
   //
 
+  /**
+    @param {string} authorisationUrl
+    @param {import('./identities/AccountIdentity.js').default} accountIdentity
+  */
   constructor (authorisationUrl, accountIdentity) {
     super()
     this.authorisationUrl = authorisationUrl
@@ -78,7 +95,7 @@ export default class Authorisation extends EventEmitter {
 
     // We’re only interested in the HTTP-01 challenge url and token so make it easy to get at these.
     // See RFC 8555 § 7.5 (Identifier Authorization).
-    this.authorisation.challenges.forEach(challenge => {
+    this.authorisation.challenges.forEach(( /** @type { Challenge } */ challenge ) => {
       if (challenge.type === 'http-01') {
         // Add the domain to the challenge object.
         this._challenge = challenge
@@ -134,7 +151,9 @@ export default class Authorisation extends EventEmitter {
       this.once(Authorisation.VALIDATED, () => {
         resolve()
       })
-      // TODO: Also listen for errors and reject the promise accordingly.
+      this.once(Authorisation.ERROR, error => {
+        reject(error)
+      })
     })
   }
 
@@ -154,30 +173,55 @@ export default class Authorisation extends EventEmitter {
     this.pollForValidationState()
   }
 
-  async pollForValidationState () {
+  /**
+      Calculates polling duration according to RFC 7231 (referenced by RFC 8555).
+
+      The Retry-After header can contain either a non-negative integer representing the delay duration in seconds or an HTTP-date instance.
 
+      @param {{ retryAfterHeader: string? }} parameterObject
+  */
+  pollingDurationBasedOn ({ retryAfterHeader }) {
+    let pollingDuration = 1000
+    if (retryAfterHeader) {
+      const delaySeconds = parseInt(retryAfterHeader, 10)
+      if (!isNaN(delaySeconds)) {
+        pollingDuration = delaySeconds * 1000
+      } else {
+        // Try parsing as HTTP-date
+        const date = new Date(retryAfterHeader)
+        if (!isNaN(date.getTime())) {
+          pollingDuration = date.getTime() - Date.now()
+        }
+      }
+    }
+    if (pollingDuration < 1000) {
+      pollingDuration = 1000
+    }
+    return pollingDuration
+  }
+
+  async pollForValidationState () {
     log(`   👋    ❨auto-encrypt❩ Polling for authorisation state for domain ${this.domain}…`)
 
-    const result = await (new AuthorisationRequest()).execute(this.authorisationUrl)
+    try {
+      const result = await (new AuthorisationRequest()).execute(this.authorisationUrl)
 
-    if (result.body.status === 'valid') {
-      log(`   🎉    ❨auto-encrypt❩ Authorisation validated for domain ${this.domain}`)
-      this.emit(Authorisation.VALIDATED)
-      return
-    } else {
-      // Check if there is a Retry-After header – there SHOULD be, according to RFC 8555 § 7.5.1
-      // (Responding to Challenges) – and use that as the polling interval. If there isn’t, default
-      // to polling every second.
-      const retryAfterHeader = result.headers['Retry-After']
-      let pollingDuration = 1000
-      if (retryAfterHeader) {
-        pollingDuration = parseInt(retryAfterHeader)
-      }
+      if (result.body.status === 'valid') {
+        log(`   🎉    ❨auto-encrypt❩ Authorisation validated for domain ${this.domain}`)
+        this.emit(Authorisation.VALIDATED)
+        return
+      } else {
+        const retryAfterHeader = result.headers['Retry-After']
+        const pollingDuration = this.pollingDurationBasedOn({ retryAfterHeader })
 
-      log(`   ⌚    ❨auto-encrypt❩ Authorisation not valid yet for domain ${this.domain}. Waiting to check again in ${pollingDuration/1000} second${pollingDuration === 1000 ? '' : 's'}…`)
+        log(`   ⌚    ❨auto-encrypt❩ Authorisation not valid yet for domain ${this.domain}. Waiting to check again in ${pollingDuration/1000} second${pollingDuration === 1000 ? '' : 's'}…`)
 
-      await waitFor(pollingDuration)
-      await this.pollForValidationState()
+        await waitFor(pollingDuration)
+        await this.pollForValidationState()
+      }
+    } catch (error) {
+      log(`   ❌    ❨auto-encrypt❩ Error during polling for authorisation state for domain ${this.domain}: ${error.message}`)
+      this.emit(Authorisation.ERROR, error)
     }
   }
 }