@certd/acme-client 0.2.0 → 0.3.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017-2020 Publish Lab
+Copyright (c) 2017-2022 Publish Lab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -8,21 +8,33 @@ This module is written to handle communication with a Boulder/Let's Encrypt-styl
 * Boulder divergences from ACME: [https://github.com/letsencrypt/boulder/blob/master/docs/acme-divergences.md](https://github.com/letsencrypt/boulder/blob/master/docs/acme-divergences.md)
 
 
+## Important upgrade notice
+
+On September 15, 2022, Let's Encrypt will stop accepting Certificate Signing Requests signed using the obsolete SHA-1 hash. This change affects all `acme-client` versions lower than `3.3.2` and `4.2.4`. Please upgrade ASAP to ensure that your certificates can still be issued following this date.
+
+A more detailed explanation can be found [at the Let's Encrypt forums](https://community.letsencrypt.org/t/rejecting-sha-1-csrs-and-validation-using-tls-1-0-1-1-urls/175144).
+
+
 ### Compatibility
 
-| acme-client   | API       | Style     | Node.js |
-| ------------- | --------- | --------- | ------- |
-| v4.x          | ACMEv2    | Promise   | >= v10  |
-| v3.x          | ACMEv2    | Promise   | >= v8   |
-| v2.x          | ACMEv2    | Promise   | >= v4   |
-| v1.x          | ACMEv1    | callback  | >= v4   |
+| acme-client   | Node.js   |                                           |
+| ------------- | --------- | ----------------------------------------- |
+| v5.x          | >= v16    | [Upgrade guide](docs/upgrade-v5.md)       |
+| v4.x          | >= v10    | [Changelog](CHANGELOG.md#v400-2020-05-29) |
+| v3.x          | >= v8     | [Changelog](CHANGELOG.md#v300-2019-07-13) |
+| v2.x          | >= v4     | [Changelog](CHANGELOG.md#v200-2018-04-02) |
+| v1.x          | >= v4     | [Changelog](CHANGELOG.md#v100-2017-10-20) |
 
 
 ### Table of contents
 
 * [Installation](#installation)
 * [Usage](#usage)
+    * [Directory URLs](#directory-urls)
+    * [External account binding](#external-account-binding)
+    * [Specifying the account URL](#specifying-the-account-url)
 * [Cryptography](#cryptography)
+    * [Legacy .forge interface](#legacy-forge-interface)
 * [Auto mode](#auto-mode)
     * [Challenge priority](#challenge-priority)
     * [Internal challenge verification](#internal-challenge-verification)
@@ -56,42 +68,87 @@ const client = new acme.Client({
 ### Directory URLs
 
 ```js
+acme.directory.buypass.staging;
+acme.directory.buypass.production;
+
 acme.directory.letsencrypt.staging;
 acme.directory.letsencrypt.production;
+
+acme.directory.zerossl.production;
 ```
 
 
-## Cryptography
+### External account binding
+
+To enable [external account binding](https://tools.ietf.org/html/rfc8555#section-7.3.4) when creating your ACME account, provide your KID and HMAC key to the client constructor.
+
+```js
+const client = new acme.Client({
+    directoryUrl: 'https://acme-provider.example.com/directory-url',
+    accountKey: accountPrivateKey,
+    externalAccountBinding: {
+        kid: 'YOUR-EAB-KID',
+        hmacKey: 'YOUR-EAB-HMAC-KEY'
+    }
+});
+```
 
-For key pair generation and Certificate Signing Requests, `acme-client` uses [node-forge](https://www.npmjs.com/package/node-forge), a pure JavaScript implementation of the TLS protocol.
 
-These utility methods are exposed through `.forge`.
+### Specifying the account URL
 
-__API documentation: [docs/forge.md](docs/forge.md)__
+During the ACME account creation process, the server will check the supplied account key and either create a new account if the key is unused, or return the existing ACME account bound to that key.
 
+In some cases, for example with some EAB providers, this account creation step may be prohibited and might require you to manually specify the account URL beforehand. This can be done through `accountUrl` in the client constructor.
 
-#### Example
+```js
+const client = new acme.Client({
+    directoryUrl: acme.directory.letsencrypt.staging,
+    accountKey: accountPrivateKey,
+    accountUrl: 'https://acme-v02.api.letsencrypt.org/acme/acct/12345678'
+});
+```
+
+You can fetch the clients current account URL, either after creating an account or supplying it through the constructor, using `getAccountUrl()`:
 
 ```js
-const privateKey = await acme.forge.createPrivateKey();
+const myAccountUrl = client.getAccountUrl();
+```
 
-const [certificateKey, certificateCsr] = await acme.forge.createCsr({
+
+## Cryptography
+
+For key pairs `acme-client` utilizes native Node.js cryptography APIs, supporting signing and generation of both RSA and ECDSA keys. The module [jsrsasign](https://www.npmjs.com/package/jsrsasign) is used to generate and parse Certificate Signing Requests.
+
+These utility methods are exposed through `.crypto`.
+
+* __Documentation: [docs/crypto.md](docs/crypto.md)__
+
+```js
+const privateRsaKey = await acme.crypto.createPrivateRsaKey();
+const privateEcdsaKey = await acme.crypto.createPrivateEcdsaKey();
+
+const [certificateKey, certificateCsr] = await acme.crypto.createCsr({
     commonName: '*.example.com',
     altNames: ['example.com']
 });
 ```
 
 
-## Auto mode
+### Legacy `.forge` interface
 
-For convenience an `auto()` method is included in the client that takes a single config object. This method will handle the entire process of getting a certificate for one or multiple domains.
+The legacy `node-forge` crypto interface is still available for backward compatibility, however this interface is now considered deprecated and will be removed in a future major version of `acme-client`.
 
-A full example can be found at [examples/auto.js](examples/auto.js).
+You should consider migrating to the new `.crypto` API at your earliest convenience. More details can be found in the [acme-client v5 upgrade guide](docs/upgrade-v5.md).
 
-__Documentation: [docs/client.md#AcmeClient+auto](docs/client.md#AcmeClient+auto)__
+* __Documentation: [docs/forge.md](docs/forge.md)__
 
 
-#### Example
+## Auto mode
+
+For convenience an `auto()` method is included in the client that takes a single config object. This method will handle the entire process of getting a certificate for one or multiple domains.
+
+* __Documentation: [docs/client.md#AcmeClient+auto](docs/client.md#AcmeClient+auto)__
+* __Full example: [examples/auto.js](examples/auto.js)__
 
 ```js
 const autoOpts = {
@@ -142,12 +199,8 @@ await client.auto({
 
 For more fine-grained control you can interact with the ACME API using the methods documented below.
 
-A full example can be found at [examples/api.js](examples/api.js).
-
-__API documentation: [docs/client.md](docs/client.md)__
-
-
-#### Example
+* __Documentation: [docs/client.md](docs/client.md)__
+* __Full example: [examples/api.js](examples/api.js)__
 
 ```js
 const account = await client.createAccount({
@@ -187,7 +240,17 @@ A complete list of axios options and documentation can be found at:
 
 ## Debugging
 
-`acme-client` uses [debug](https://www.npmjs.com/package/debug) for debugging which can be enabled by running
+To get a better grasp of what `acme-client` is doing behind the scenes, you can either pass it a logger function, or enable debugging through an environment variable.
+
+Setting a logger function may for example be useful for passing messages on to another logging system, or just dumping them to the console.
+
+```js
+acme.setLogger((message) => {
+    console.log(message);
+});
+```
+
+Debugging to the console can also be enabled through [debug](https://www.npmjs.com/package/debug) by setting an environment variable.
 
 ```bash
 DEBUG=acme-client node index.js

package/package.json

@@ -1,50 +1,46 @@
 {
     "name": "@certd/acme-client",
-    "description": "Simple and unopinionated ACME client,base version 4.1.2",
-    "author": "greper",
-    "version": "0.2.0",
+    "description": "Simple and unopinionated ACME client",
+    "author": "nmorsman",
+    "version": "0.3.1",
     "main": "src/index.js",
     "types": "types",
     "license": "MIT",
     "homepage": "https://github.com/publishlab/node-acme-client",
     "engines": {
-        "node": ">= 10"
+        "node": ">= 16"
     },
     "files": [
         "src",
         "types"
     ],
     "dependencies": {
-        "axios": "0.21.1",
-        "backo2": "^1.0.0",
-        "bluebird": "^3.5.0",
+        "axios": "0.27.2",
         "debug": "^4.1.1",
-        "log4js": "^6.3.0",
-        "node-forge": "^0.10.0"
+        "jsrsasign": "^10.5.26",
+        "node-forge": "^1.3.1"
     },
     "devDependencies": {
-        "@types/node": "^14.0.5",
-        "chai": "^4.1.0",
-        "chai-as-promised": "^7.0.0",
-        "dtslint": "^4.0.0",
-        "eslint": "^7.1.0",
-        "eslint-config-airbnb-base": "^14.0.0",
-        "eslint-plugin-import": "^2.10.0",
-        "jsdoc-to-markdown": "^6.0.1",
-        "mocha": "^8.1.3",
-        "nock": "^13.0.4",
-        "typescript": "^4.0.2",
-        "uuid": "^8.1.0",
-        "webpack-cli": "^4.3.1"
+        "@types/node": "^18.6.1",
+        "chai": "^4.3.6",
+        "chai-as-promised": "^7.1.1",
+        "dtslint": "^4.2.1",
+        "eslint": "^8.11.0",
+        "eslint-config-airbnb-base": "^15.0.0",
+        "eslint-plugin-import": "^2.25.4",
+        "jsdoc-to-markdown": "^7.1.1",
+        "mocha": "^10.0.0",
+        "nock": "^13.2.4",
+        "typescript": "^4.8.4",
+        "uuid": "^8.3.2"
     },
     "scripts": {
-        "build-docs": "jsdoc2md src/client.js > docs/client.md && jsdoc2md src/crypto/forge.js > docs/forge.md",
+        "build-docs": "jsdoc2md src/client.js > docs/client.md && jsdoc2md src/crypto/index.js > docs/crypto.md && jsdoc2md src/crypto/forge.js > docs/forge.md",
         "lint": "eslint .",
         "lint-types": "dtslint types",
-        "1prepublishOnly": "npm run build-docs",
-        "test": "mocha -b -t 60000 \"test/setup.js\" \"test/**/*.spec.js\"",
-        "test-local": "/bin/bash scripts/run-tests.sh",
-        "build": "webpack ./src/index.js ./dist/bundle.js"
+        "prepublishOnly": "npm run build-docs",
+        "test": "mocha -t 60000 \"test/setup.js\" \"test/**/*.spec.js\"",
+        "test-local": "/bin/bash scripts/run-tests.sh"
     },
     "repository": {
         "type": "git",
@@ -60,6 +56,5 @@
     ],
     "bugs": {
         "url": "https://github.com/publishlab/node-acme-client/issues"
-    },
-    "gitHead": "5fbd7742665c0a949333d805153e9b6af91c0a71"
+    }
 }

package/src/api.js

@@ -42,13 +42,15 @@ class AcmeApi {
      * @param {string} url Request URL
      * @param {object} [payload] Request payload, default: `null`
      * @param {array} [validStatusCodes] Array of valid HTTP response status codes, default: `[]`
-     * @param {boolean} [jwsKid] Use KID in JWS header, default: `true`
+     * @param {object} [opts]
+     * @param {boolean} [opts.includeJwsKid] Include KID instead of JWK in JWS header, default: `true`
+     * @param {boolean} [opts.includeExternalAccountBinding] Include EAB in request, default: `false`
      * @returns {Promise<object>} HTTP response
      */
 
-    async apiRequest(url, payload = null, validStatusCodes = [], jwsKid = true) {
-        const kid = jwsKid ? this.getAccountUrl() : null;
-        const resp = await this.http.signedRequest(url, payload, kid);
+    async apiRequest(url, payload = null, validStatusCodes = [], { includeJwsKid = true, includeExternalAccountBinding = false } = {}) {
+        const kid = includeJwsKid ? this.getAccountUrl() : null;
+        const resp = await this.http.signedRequest(url, payload, { kid, includeExternalAccountBinding });
 
         if (validStatusCodes.length && (validStatusCodes.indexOf(resp.status) === -1)) {
             throw new Error(util.formatResponseError(resp));
@@ -65,13 +67,15 @@ class AcmeApi {
      * @param {string} resource Request resource name
      * @param {object} [payload] Request payload, default: `null`
      * @param {array} [validStatusCodes] Array of valid HTTP response status codes, default: `[]`
-     * @param {boolean} [jwsKid] Use KID in JWS header, default: `true`
+     * @param {object} [opts]
+     * @param {boolean} [opts.includeJwsKid] Include KID instead of JWK in JWS header, default: `true`
+     * @param {boolean} [opts.includeExternalAccountBinding] Include EAB in request, default: `false`
      * @returns {Promise<object>} HTTP response
      */
 
-    async apiResourceRequest(resource, payload = null, validStatusCodes = [], jwsKid = true) {
+    async apiResourceRequest(resource, payload = null, validStatusCodes = [], { includeJwsKid = true, includeExternalAccountBinding = false } = {}) {
         const resourceUrl = await this.http.getResourceUrl(resource);
-        return this.apiRequest(resourceUrl, payload, validStatusCodes, jwsKid);
+        return this.apiRequest(resourceUrl, payload, validStatusCodes, { includeJwsKid, includeExternalAccountBinding });
     }
 
 
@@ -98,7 +102,10 @@ class AcmeApi {
      */
 
     async createAccount(data) {
-        const resp = await this.apiResourceRequest('newAccount', data, [200, 201], false);
+        const resp = await this.apiResourceRequest('newAccount', data, [200, 201], {
+            includeJwsKid: false,
+            includeExternalAccountBinding: (data.onlyReturnExisting !== true)
+        });
 
         /* Set account URL */
         if (resp.headers.location) {

package/src/auto.js

@@ -2,11 +2,8 @@
  * ACME auto helper
  */
 
-const Promise = require('bluebird');
-const logger = require('./util.log.js');
-
-const debug = logger.info;
-const forge = require('./crypto/forge');
+const { readCsrDomains } = require('./crypto');
+const { log } = require('./logger');
 
 const defaultOpts = {
     csr: null,
@@ -20,13 +17,6 @@ const defaultOpts = {
 };
 
 
-function sleep(time) {
-    return new Promise((resovle) => {
-        setTimeout(() => {
-            resovle();
-        }, time);
-    });
-}
 /**
  * ACME client auto mode
  *
@@ -52,14 +42,14 @@ module.exports = async function(client, userOpts) {
      * Register account
      */
 
-    logger.info('[auto] Checking account');
+    log('[auto] Checking account');
 
     try {
         client.getAccountUrl();
-        logger.info('[auto] Account URL already exists, skipping account registration');
+        log('[auto] Account URL already exists, skipping account registration');
     }
     catch (e) {
-        logger.info('[auto] Registering account');
+        log('[auto] Registering account');
         await client.createAccount(accountPayload);
     }
 
@@ -68,136 +58,136 @@ module.exports = async function(client, userOpts) {
      * Parse domains from CSR
      */
 
-    logger.info('[auto] Parsing domains from Certificate Signing Request');
-    const csrDomains = await forge.readCsrDomains(opts.csr);
+    log('[auto] Parsing domains from Certificate Signing Request');
+    const csrDomains = readCsrDomains(opts.csr);
     const domains = [csrDomains.commonName].concat(csrDomains.altNames);
+    const uniqueDomains = Array.from(new Set(domains));
 
-    logger.info(`[auto] Resolved ${domains.length} domains from parsing the Certificate Signing Request`);
+    log(`[auto] Resolved ${uniqueDomains.length} unique domains from parsing the Certificate Signing Request`);
 
 
     /**
      * Place order
      */
 
-    logger.info('[auto] Placing new certificate order with ACME provider');
-    const orderPayload = { identifiers: domains.map((d) => ({ type: 'dns', value: d })) };
+    log('[auto] Placing new certificate order with ACME provider');
+    const orderPayload = { identifiers: uniqueDomains.map((d) => ({ type: 'dns', value: d })) };
     const order = await client.createOrder(orderPayload);
     const authorizations = await client.getAuthorizations(order);
 
-    logger.info(`[auto] Placed certificate order successfully, received ${authorizations.length} identity authorizations`);
+    log(`[auto] Placed certificate order successfully, received ${authorizations.length} identity authorizations`);
 
 
     /**
      * Resolve and satisfy challenges
      */
 
-    logger.info('[auto] Resolving and satisfying authorization challenges');
+    log('[auto] Resolving and satisfying authorization challenges');
 
-    // 获取challenge列表
-    const challengePromises = authorizations.map(async (authz) => {
+    const challengeFunc = async (authz) => {
         const d = authz.identifier.value;
+        let challengeCompleted = false;
 
-        /* Select challenge based on priority */
-        const challenge = authz.challenges.sort((a, b) => {
-            const aidx = opts.challengePriority.indexOf(a.type);
-            const bidx = opts.challengePriority.indexOf(b.type);
-
-            if (aidx === -1) return 1;
-            if (bidx === -1) return -1;
-            return aidx - bidx;
-        }).slice(0, 1)[0];
-
-        if (!challenge) {
-            throw new Error(`Unable to select challenge for ${d}, no challenge found`);
+        /* Skip authz that already has valid status */
+        if (authz.status === 'valid') {
+            log(`[auto] [${d}] Authorization already has valid status, no need to complete challenges`);
+            return;
         }
 
-        logger.info(`[auto] [${d}] Found ${authz.challenges.length} challenges, selected type: ${challenge.type}`);
-
-        const keyAuthorization = await client.getChallengeKeyAuthorization(challenge);
-
-        return {
-            authz, keyAuthorization, domain: d, challenge
-        };
-    });
+        try {
+            /* Select challenge based on priority */
+            const challenge = authz.challenges.sort((a, b) => {
+                const aidx = opts.challengePriority.indexOf(a.type);
+                const bidx = opts.challengePriority.indexOf(b.type);
+
+                if (aidx === -1) return 1;
+                if (bidx === -1) return -1;
+                return aidx - bidx;
+            }).slice(0, 1)[0];
+
+            if (!challenge) {
+                throw new Error(`Unable to select challenge for ${d}, no challenge found`);
+            }
 
-    // 执行获取challenge信息列表
-    const challengeInfos = await Promise.all(challengePromises);
+            log(`[auto] [${d}] Found ${authz.challenges.length} challenges, selected type: ${challenge.type}`);
 
+            /* Trigger challengeCreateFn() */
+            log(`[auto] [${d}] Trigger challengeCreateFn()`);
+            const keyAuthorization = await client.getChallengeKeyAuthorization(challenge);
 
-    // 创建dns records 的promise
-    const challengeCreatePromises = challengeInfos.map(async (challengeInfo, index) => {
-        const { domain, authz, challenge, keyAuthorization } = challengeInfo;
-        try {
-            await sleep(index * 2000); // 延迟2秒再请求下一个
-            logger.info(`[auto] [${domain}] Trigger challengeCreateFn()`);
-            challengeInfo.record = await opts.challengeCreateFn(authz, challenge, keyAuthorization);
-            return challengeInfo;
+            try {
+                await opts.challengeCreateFn(authz, challenge, keyAuthorization);
+
+                /* Challenge verification */
+                if (opts.skipChallengeVerification === true) {
+                    log(`[auto] [${d}] Skipping challenge verification since skipChallengeVerification=true`);
+                }
+                else {
+                    log(`[auto] [${d}] Running challenge verification`);
+                    await client.verifyChallenge(authz, challenge);
+                }
+
+                /* Complete challenge and wait for valid status */
+                log(`[auto] [${d}] Completing challenge with ACME provider and waiting for valid status`);
+                await client.completeChallenge(challenge);
+                challengeCompleted = true;
+
+                await client.waitForValidStatus(challenge);
+            }
+            finally {
+                /* Trigger challengeRemoveFn(), suppress errors */
+                log(`[auto] [${d}] Trigger challengeRemoveFn()`);
+
+                try {
+                    await opts.challengeRemoveFn(authz, challenge, keyAuthorization);
+                }
+                catch (e) {
+                    log(`[auto] [${d}] challengeRemoveFn threw error: ${e.message}`);
+                }
+            }
         }
         catch (e) {
-            logger.error('challengeCreate error', e);
-            return e;
+            /* Deactivate pending authz when unable to complete challenge */
+            if (!challengeCompleted) {
+                log(`[auto] [${d}] Unable to complete challenge: ${e.message}`);
+
+                try {
+                    log(`[auto] [${d}] Deactivating failed authorization`);
+                    await client.deactivateAuthorization(authz);
+                }
+                catch (f) {
+                    /* Suppress deactivateAuthorization() errors */
+                    log(`[auto] [${d}] Authorization deactivation threw error: ${f.message}`);
+                }
+            }
+
+            throw e;
         }
-    });
+    };
 
-    // 执行创建dns record
-    const challengeRecordInfos = await Promise.all(challengeCreatePromises);
+    const challengePromises = authorizations.map((authz) => async () => {
+        await challengeFunc(authz);
+    });
 
-    try {
-        // 如果创建record有错误，直接报错
-        const hasError = challengeRecordInfos.filter((item) => item instanceof Error);
-        if (hasError.length > 0) {
-            throw new Error(hasError[0]);
-        }
-        // 等待30秒，尽量等dns记录更新到远端
-        logger.info('[auto] 等待30秒');
-        await sleep(30000);
-        // 开始验证
-        const verifys = challengeRecordInfos.map(async (challengeInfo) => {
-            const { domain, authz, challenge } = challengeInfo;
-            const d = domain;
-            /* Challenge verification */
-            if (opts.skipChallengeVerification === true) {
-                logger.info(`[auto] [${d}] Skipping challenge verification since skipChallengeVerification=true`);
-            }
-            else {
-                logger.info(`[auto] [${d}] Running challenge verification`);
-                await client.verifyChallenge(authz, challenge);
-            }
+    log('[auto] Waiting for challenge valid status');
+    // await Promise.all(challengePromises);
 
-            /* Complete challenge and wait for valid status */
-            logger.info(`[auto] [${d}] Completing challenge with ACME provider and waiting for valid status`);
-            await client.completeChallenge(challenge);
-            await client.waitForValidStatus(challenge);
+    log('开始challenge');
+    let promise = Promise.resolve();
+    function runPromisesSerially(tasks) {
+        tasks.forEach((task) => {
+            promise = promise.then(task);
         });
-        logger.info('[auto] Waiting for challenge valid status');
-        await Promise.all(verifys);
-        // 验证成功
-        logger.info('[auto] challenge verify success');
-    }
-    catch (e) {
-        logger.error('申请时出错:', e);
-        throw e;
+        return promise;
     }
-    finally {
-        // 删除record
-        const willRemovePromises = challengeRecordInfos.filter((item) => item && !(item instanceof Error)).map(async (challengeInfo, index) => {
-            await sleep(index * 2000); // 延迟2秒再请求下一个
-            const { authz, challenge, keyAuthorization, record, domain } = challengeInfo;
-            /* Trigger challengeRemoveFn(), suppress errors */
-            logger.info(`[auto] [${domain}] Trigger challengeRemoveFn()`);
 
-            try {
-                await opts.challengeRemoveFn(authz, challenge, keyAuthorization, record);
-            }
-            catch (e) {
-                logger.info(`[auto] [${domain}] challengeRemoveFn threw error: ${e.message}`);
-            }
-        });
-
-        await Promise.all(willRemovePromises);
-    }
+    await runPromisesSerially(challengePromises);
+    log('challenge结束');
+    /**
+     * Finalize order and download certificate
+     */
 
-    logger.info('[auto] Finalizing order and downloading certificate');
-    await client.finalizeOrder(order, opts.csr);
-    return client.getCertificate(order, opts.preferredChain);
+    log('[auto] Finalizing order and downloading certificate');
+    const finalized = await client.finalizeOrder(order, opts.csr);
+    return client.getCertificate(finalized, opts.preferredChain);
 };