v3.0.0: challenge strategy test suite for Greenlock v2.7+ (and v3)

README.md

@@ -61,14 +61,14 @@ tester.test('http-01', 'example.com', {
     //   // dns-01 only, for testing / dubgging
     // , altname: '...'
     // , dnsHost: '...'
-    // , dnsAuthorization: '...' }
+    // , wildcard: false }
     // Note: query.identifier.value is different for http-01 than for dns-01
 
-    return API.get(...).then(function () {
+    return API.get(...).then(function (secret) {
       // http-01
-      return { identifier: { type: 'dns', value: 'example.com' }, keyAuthorization: 'xxxx.yyyy' };
+      return { keyAuthorization: secret };
       // dns-01
-      //return { identifier: { type: 'dns', value: 'example.com' }, dnsAuthorization: 'zzzz' };
+      //return { dnsAuthorization: secret };
     });
   }
 , remove: function (opts) {

example.js

@@ -1,15 +1,24 @@
 'use strict';
 
-var tester = require('greenlock-challenge-test');
+//var tester = require('greenlock-challenge-test');
+var tester = require('./');
 
+var type = 'http-01';
 var challenger = require('greenlock-challenge-http').create({});
+//var type = 'dns-01';
 //var challenger = require('greenlock-challenge-dns').create({});
 //var challenger = require('./YOUR-CHALLENGE-STRATEGY').create({});
+//var type = 'YOUR-TYPE-01';
 
 // The dry-run tests can pass on, literally, 'example.com'
 // but the integration tests require that you have control over the domain
 var domain = 'example.com';
+//var domain = '*.example.com';
 
-tester.test('http-01', domain, challenger).then(function () {
+tester.test(type, domain, challenger).then(function () {
   console.info("PASS");
+}).catch(function (err) {
+  console.error("FAIL");
+  console.error(err);
+  process.exit(20);
 });

index.js

@@ -34,6 +34,7 @@ function promiseCheckAndCatch(obj, name) {
       throw new Error("'challenge.'" + name + "' should never return `undefined`. Please explicitly return null"
         + " (or fix the place where a value should have been returned but wasn't).");
     }
+    return result;
   }
 
   return function (opts) {
@@ -62,7 +63,8 @@ function run(challenger, opts) {
   // this will cause the prompt to appear
   return set(opts).then(function () {
     // this will cause the final completion message to appear
-    var query = { type: ch.type };
+    // _test is used by the manual cli reference implementations
+    var query = { type: ch.type, /*debug*/ status: ch.status, _test: true };
     if ('http-01' === ch.type) {
       query.identifier = ch.identifier;
       query.token = ch.token;
@@ -72,38 +74,48 @@ function run(challenger, opts) {
       query.identifier = { type: 'dns', value: ch.dnsHost };
       // For testing only
       query.altname = ch.altname;
-      query.dnsAuthorization = ch.dnsAuthorization;
+      // there should only be two possible TXT records per challenge domain:
+      // one for the bare domain, and the other if and only if there's a wildcard
+      query.wildcard = ch.wildcard;
     } else {
       query = JSON.parse(JSON.stringify(ch));
       query.comment = "unknown challenge type, supplying everything";
     }
-    return get({ challenge: query }).then(function (result) {
+    return get({ challenge: query }).then(function (secret) {
+      if ('string' === typeof secret) {
+        console.info("secret was passed as a string, which works historically, but should be an object instead:");
+        console.info('{ "keyAuthorization": "' + secret + '" }');
+        console.info("or");
+        // TODO this should be "keyAuthorizationDigest"
+        console.info('{ "dnsAuthorization": "' + secret + '" }');
+        console.info("This is to help keep greenlock (and associated plugins) future-proof for new challenge types");
+      }
+      // historically 'secret' has been a string, but I'd like it to transition to be an object.
+      // to make it backwards compatible in v2.7 to change it,
+      // so I'm not sure that we really need to.
       if ('http-01' === ch.type) {
-        if (ch.keyAuthorization !== result.keyAuthorization
+        secret = secret.keyAuthorization || secret;
-          // cross-checking on purpose
+        if (ch.keyAuthorization !== secret) {
-          || (ch.altname !== result.identifier.value || ch.identifier.value !== result.altname)
+          throw new Error("http-01 challenge.get() returned '" + secret + "', which does not match the keyAuthorization"
-        ) {
+            + " saved with challenge.set(), which was '" + ch.keyAuthorization + "'");
-          throw new Error("challenge.get() for http-01 should return the same altname, identifier.value,"
-            + " and keyAuthorization as were saved with challenge.set()");
         }
       } else if ('dns-01' === ch.type) {
-        if (ch.dnsAuthorization !== result.dnsAuthorization
+        secret = secret.dnsAuthorization || secret;
-          || ch.identifier.value !== result.identifier.value
+        if (ch.dnsAuthorization !== secret) {
-        ) {
+          throw new Error("dns-01 challenge.get() returned '" + secret + "', which does not match the dnsAuthorization"
-          throw new Error("challenge.get() for dns-01 should return the same identifier.value,"
+            + " (keyAuthDigest) saved with challenge.set(), which was '" + ch.dnsAuthorization + "'");
-            + " and dnsAuthorization as were saved with challenge.set()");
         }
       } else {
-        if (ch.identifier.value !== result.identifier.value) {
-          throw new Error("challenge.get() should always return the same identifier.value,"
-            + " and dnsAuthorization as were saved with challenge.set()");
-        }
         if ('tls-alpn-01' === ch.type) {
           console.warn("'tls-alpn-01' support is in development"
             + " (or developed and we haven't update this yet). Please contact us.");
         } else {
           console.warn("We don't know how to test '" + ch.type + "'... are you sure that's a thing?");
         }
+        secret = secret.keyAuthorization || secret;
+        if (ch.keyAuthorization !== secret) {
+          console.warn("The returned value doesn't match keyAuthorization", ch.keyAuthorization, secret);
+        }
       }
     }).then(function () {
       return remove(opts).then(function () {
@@ -126,16 +138,17 @@ function run(challenger, opts) {
 
 module.exports.test = function (type, altname, challenger) {
   var expires = new Date(Date.now() + (10*60*1000)).toISOString();
-  var token = crypto.randomBytes('8').toString('hex');
+  var token = crypto.randomBytes(8).toString('hex');
-  var thumb = crypto.randomBytes('16').toString('hex');
+  var thumb = crypto.randomBytes(16).toString('hex');
-  var keyAuth = token + '.' + crypto.randomBytes('16').toString('hex');
+  var keyAuth = token + '.' + crypto.randomBytes(16).toString('hex');
   var dnsAuth = crypto.createHash('sha256').update(keyAuth).digest('base64')
-    .replace(/\+/, '-').replace(/\//, '_').replace(/=/, '');
+    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
 
   var challenge = {
     type: type
   , identifier: { type: 'dns', value: null }  // completed below
   , wildcard: false                           // completed below
+  , status: 'pending'
   , expires: expires
   , token: token
   , thumbprint: thumb
@@ -144,6 +157,7 @@ module.exports.test = function (type, altname, challenger) {
   , dnsHost: '_acme-challenge.'               // completed below
   , dnsAuthorization: dnsAuth
   , altname: altname
+  , _test: true                               // used by CLI referenced implementations
   };
   if ('*.' === altname.slice(0, 2)) {
     challenge.wildcard = true;
@@ -153,11 +167,5 @@ module.exports.test = function (type, altname, challenger) {
   challenge.url = 'http://' + altname + '/.well-known/acme-challenge/' + challenge.token;
   challenge.dnsHost += altname;
 
-  run(challenger, { challenge: challenge }).then(function () {
+  return run(challenger, { challenge: challenge });
-    console.info("PASS");
-  }).catch(function (err) {
-    console.error("FAIL");
-    console.error(err);
-    process.exit(20);
-  });
 };

package.json

@@ -0,0 +1,27 @@
+{
+  "name": "greenlock-challenge-test",
+  "version": "3.0.0",
+  "description": "The base set of tests for all ACME challenge strategies. Any `greenlock-challenge-` plugin should be able to pass these tests.",
+  "main": "index.js",
+  "dependencies": {},
+  "devDependencies": {},
+  "scripts": {
+    "test": "node example.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://git.coolaj86.com/coolaj86/greenlock-challenge-test.js.git"
+  },
+  "keywords": [
+    "Let's Encrypt",
+    "ACME",
+    "http-01",
+    "dns-01",
+    "challenge",
+    "plugin",
+    "module",
+    "strategy"
+  ],
+  "author": "AJ ONeal <coolaj86@gmail.com> (https://coolaj86.com/)",
+  "license": "MPL-2.0"
+}