v3.0.4: ACME challenge reference implementation for Greenlock v2.7+ (and v3)

README.md

@@ -1,54 +1,122 @@
-| [Greenlock](https://git.coolaj86.com/coolaj86/greenlock.js) (library)
+# [greenlock-challenge-manual](https://git.coolaj86.com/coolaj86/greenlock-challenge-manual.js)
-| [Greenlock CLI](https://git.coolaj86.com/coolaj86/greenlock-cli.js)
-| [greenlock-express](https://git.coolaj86.com/coolaj86/greenlock-express.js)
-| [greenlock-koa](https://git.coolaj86.com/coolaj86/greenlock-koa.js)
-| [greenlock-hapi](https://git.coolaj86.com/coolaj86/greenlock-hapi.js)
-|
 
-le-challenge-manual
+| A [Root](https://rootprojects.org) Project |
-===================
 
-A [Root](https://rootprojects.org) Project
+An extremely simple reference implementation
+of an ACME (Let's Encrypt) challenge strategy
+for [Greenlock](https://git.coolaj86.com/coolaj86/greenlock-express.js) v2.7+ (and v3).
 
-A manual cli-based strategy for node-letsencrypt.
+* Prints the ACME challenge details to the terminal
+  * (waits for you to hit enter before continuing)
+* Asks you to enter the challenge response.
+* Let's you know it's safe to remove the challenge.
 
-Prints the ACME challenge Token and Key and then waits for you to hit enter before continuing.
+Other ACME Challenge Reference Implementations:
+
+* [**greenlock-challenge-manual**](https://git.coolaj86.com/coolaj86/greenlock-challenge-manual.js)
+* [greenlock-challenge-http](https://git.coolaj86.com/coolaj86/greenlock-challenge-http.js)
+* [greenlock-challenge-dns](https://git.coolaj86.com/coolaj86/greenlock-challenge-dns.js)
 
 Install
 -------
 
 ```bash
-npm install --save le-challenge-manual@2.x
+npm install --save greenlock-challenge-manual@3.x
 ```
 
 Usage
 -----
 
 ```bash
-var leChallenge = require('le-challenge-manual').create({
+var Greenlock = require('greenlock');
-, debug: false
-});
 
-var LE = require('letsencrypt');
+Greenlock.create({
-
+  ...
-LE.create({
+, challenges: { 'http-01': require('greenlock-challenge-manual')
-  server: LE.stagingServerUrl
+              , 'dns-01': require('greenlock-challenge-manual')
-, challenge: leChallenge
+              , 'tls-alpn-01': require('greenlock-challenge-manual')
+              }
+  ...
 });
 ```
 
-NOTE: If you request a certificate with 6 domains listed,
+Note: If you request a certificate with 6 domains listed,
 it will require 6 individual challenges.
 
-Exposed Methods
+Exposed (Promise) Methods
 ---------------
 
 For ACME Challenge:
 
-* `set(opts, domain, key, val, done)`
+* `set(opts)`
-* `get(defaults, domain, key, done)`
+* `remove(opts)`
-* `remove(defaults, domain, key, done)`
 
-For node-letsencrypt internals:
+The options will look like this for normal domains:
 
-* `getOptions()` returns the internal defaults merged with the user-supplied options
+```js
+{ challenge: {
+    type: 'http-01'
+  , identifier: { type: 'dns', value: 'example.com' }
+  , wildcard: false
+  , expires: '2012-01-01T12:00:00.000Z'
+  , token: 'abc123'
+  , thumbprint: '<<account key thumbprint>>'
+  , keyAuthorization: 'abc123.xxxx'
+  , dnsHost: '_acme-challenge.example.com'
+  , dnsAuthorization: 'yyyy'
+  , altname: 'example.com'
+  }
+}
+```
+
+And they'll look like this for wildcard domains:
+
+```js
+{ challenge: {
+    type: 'http-01'
+  , identifier: { type: 'dns', value: 'example.com' }
+  , wildcard: true
+  , expires: '2012-01-01T12:00:00.000Z'
+  , token: 'abc123'
+  , thumbprint: '<<account key thumbprint>>'
+  , keyAuthorization: 'abc123.xxxx'
+  , dnsHost: '_acme-challenge.example.com'
+  , dnsAuthorization: 'yyyy'
+  , altname: '*.example.com'
+  }
+}
+```
+
+The only difference is that `altname` will have the `*.` prefix (which you would expect
+but, of course, can't work as a specific a DNS record) and the `wildcard` property is `true`.
+
+Optional
+
+* `get(limitedOpts)`
+
+Because the get method is apart from the main flow (such as a DNS query),
+it's not always implemented and the options are much more limited in scope:
+
+```js
+{ challenge: {
+    type: 'http-01'
+  , identifier: { type: 'dns', value: 'example.com' }
+  , wildcard: false
+  , token: 'abc123'
+  , altname: 'example.com'
+  }
+}
+```
+
+If there were an implementation of Greenlock integrated directly into
+a NameServer (which currently there is not), it would probably look like this:
+
+```js
+{ challenge: {
+    type: 'dns-01'
+  , identifier: { type: 'dns', value: 'example.com' }
+  , token: 'abc123'
+  , dnsHost: '_acme-challenge.example.com'
+  }
+}
+```

index.js

@@ -1,50 +1,129 @@
 'use strict';
+/*global Promise*/
 
 var Challenge = module.exports;
 
-Challenge.create = function (defaults) {
+Challenge.create = function (config) {
-  return  {
+  // If your implementation needs config options, set them. Otherwise, don't bother (duh).
-    getOptions: function () {
+
-      return defaults;
+  var http01 = require('greenlock-challenge-http').create(config);
+  var dns01 = require('greenlock-challenge-dns').create(config);
+
+  var challenger = {};
+
+  // Note: normally you'd implement these right here, but for the sake of
+  // documentation I've abstracted them out "Table of Contents"-style.
+
+  // call out to set the challenge, wherever
+  challenger.set = function (opts, cb) {
+    // Note: this can be defined as a thunk (like this) or a Promise
+
+    var ch = opts.challenge;
+    if ('http-01' === ch.type) {
+      return http01.set(opts, cb);
+    } else if ('dns-01' === ch.type) {
+      return dns01.set(opts, cb);
+    } else {
+      return Challenge._setAny(opts, cb);
     }
-  , set: Challenge.set
-  , get: Challenge.get
-  , remove: Challenge.remove
   };
+
+  // call out to remove the challenge, wherever
+  challenger.remove = function (opts) {
+    // Note: this can be defined synchronously (like this) or as a Promise, or a thunk
+
+    var ch = opts.challenge;
+    if ('http-01' === ch.type) {
+      return http01.remove(opts);
+    } else if ('dns-01' === ch.type) {
+      return dns01.remove(opts);
+    } else {
+      return Challenge._removeAny(opts);
+    }
+  };
+
+  // only really useful for http
+  // (and tls-alpn-01, which isn't implemented yet)
+  challenger.get = function (opts) {
+    // Note: this can be defined as a Promise (like this) or synchronously, or a thunk
+
+    var ch = opts.challenge;
+    if ('http-01' === ch.type) {
+      return http01.get(opts);
+    } else if ('dns-01' === ch.type) {
+      return dns01.get(opts);
+    } else {
+      return Challenge._get(opts);
+    }
+  };
+
+  // Whatever you set to 'options' will be merged into 'opts' just before each call
+  // (for convenience, so you don't have to merge it yourself).
+  challenger.options = { debug: config.debug };
+
+  return challenger;
 };
 
-// Show the user the token and key and wait for them to be ready to continue
+Challenge._setAny = function (args, cb) {
-Challenge.set = function (args, domain, token, secret, cb) {
+  var ch = args.challenge;
+  console.info("[ACME " + ch.type + " '" + ch.altname + "' CHALLENGE]");
+  console.info("Your mission (since you chose to accept it):");
+  console.info("You must, by whatever means necessary, use the following information"
+    + " to make a device or service ready to respond to a '" + ch.type + "' request.");
   console.info("");
-  console.info("Challenge for '" + domain + "'");
+  console.info(JSON.stringify(ch, null, 2).replace(/^/gm, '\t'));
   console.info("");
-  console.info("We now present (for you copy-and-paste pleasure) your ACME Challenge");
+  console.info("Press the any key once the response is ready to continue with the '" + ch.type + "' challenge process");
-  console.info("public Token and secret Key, in that order, respectively:");
+  console.info("[Press the ANY key to continue...]");
-  console.info(token);
+
-  console.info(secret);
-  console.info("");
-  console.info(JSON.stringify({
-    domain: domain
-  , token: token
-  , key: secret
-  }, null, '  ').replace(/^/gm, '\t'));
-  console.info("");
-  console.info("hit enter to continue...");
   process.stdin.resume();
-  process.stdin.on('data', function () {
+  process.stdin.once('data', function () {
     process.stdin.pause();
-    cb(null);
+    cb(null, null);
   });
 };
 
-// nothing to do here, that's why it's manual
+Challenge._removeAny = function (args) {
-Challenge.get = function (args, domain, token, cb) {
+  var ch = args.challenge;
-  cb(null);
+  console.info("");
+  console.info("[ACME " + ch.type + " '" + ch.altname + "' COMPLETE]: " + ch.status);
+  console.info("You may now undo whatever you did to create and ready the response.");
+  console.info("");
+
+  return null;
 };
 
-// might as well tell the user that whatever they were setting up has been checked
+// This can be used for http-01 and tls-alpn-01 (when it's available), but not dns-01.
-Challenge.remove = function (args, domain, token, cb) {
+// And not all http-01 or tls-alpn-01 strategies will need to implement this.
-  console.info("Challenge for '" + domain + "' complete.");
+Challenge._get = function (args) {
-  console.info("");
+  var ch = args.challenge;
-  cb(null);
+
+  if (!Challenge._getCache[ch.altname + ':' + ch.token]) {
+    Challenge._getCache[ch.altname + ':' + ch.token] = true;
+    console.info("");
+    console.info("[ACME " + ch.type + " '" + ch.altname + "' REQUEST]: " + ch.status);
+    console.info("The '" + ch.type + "' challenge request has arrived!");
+    console.info("It's now time to painstakingly type out the expected response object with your bear hands.");
+    console.log("Yes. Your bear hands.");
+    console.log('ex: { "keyAuthorization": "xxxxxxxx.yyyyyyyy" }');
+    process.stdout.write("> ");
+  }
+
+  return new Promise(function (resolve, reject) {
+    process.stdin.resume();
+    process.stdin.once('error', reject);
+    process.stdin.once('data', function (chunk) {
+      process.stdin.pause();
+      var result = chunk.toString('utf8').trim();
+      try {
+        result = JSON.parse(result);
+      } catch(e) {
+        args.challenge.keyAuthorization = result;
+        result = args.challenge;
+      }
+      resolve(result);
+    });
+  });
 };
+// Because the ACME server will hammer us with requests, and that's confusing during a manual test:
+Challenge._getCache = {};

package-lock.json

@@ -1,5 +1,18 @@
 {
-  "name": "le-challenge-manual",
+  "name": "greenlock-challenge-manual",
-  "version": "2.1.1",
+  "version": "3.0.4",
-  "lockfileVersion": 1
+  "lockfileVersion": 1,
+  "requires": true,
+  "dependencies": {
+    "greenlock-challenge-dns": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/greenlock-challenge-dns/-/greenlock-challenge-dns-3.0.4.tgz",
+      "integrity": "sha512-CJI9RAtrZl9ICldyU5cRGzb1/wIbS3O+MJy9z7gKb7fLDNF7Wmw9Fv2agBLSOtIPr7TYgyyesvt8ppA4OIS+yg=="
+    },
+    "greenlock-challenge-http": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/greenlock-challenge-http/-/greenlock-challenge-http-3.0.1.tgz",
+      "integrity": "sha512-u+r8VtT+Qve0wucVZEPivFRT7DP+Jfl7McGMbna0BFVvAc+NJyOJGyvBa6aGDi4qgEhx7pjh0yCsCEKDHI2zDw=="
+    }
+  }
 }

package.json

@@ -1,22 +1,21 @@
 {
-  "name": "le-challenge-manual",
+  "name": "greenlock-challenge-manual",
-  "version": "2.1.1",
+  "version": "3.0.4",
   "description": "A cli-based strategy for node-letsencrypt. Prints the ACME challenge Token and Key and then waits for you to hit enter before continuing.",
   "main": "index.js",
-  "homepage": "https://git.coolaj86.com/coolaj86/le-challenge-manual.js",
+  "homepage": "https://git.coolaj86.com/coolaj86/greenlock-challenge-manual.js",
   "scripts": {
     "test": "node test.js"
   },
   "repository": {
     "type": "git",
-    "url": "https://git.coolaj86.com/coolaj86/le-challenge-manual.js.git"
+    "url": "https://git.coolaj86.com/coolaj86/greenlock-challenge-manual.js.git"
   },
   "keywords": [
-    "le-challenge",
+    "Let's Encrypt",
-    "le-challenge-",
+    "ACME",
+    "challenge",
     "manual",
-    "acme",
-    "letsencrypt",
     "certbot",
     "cli",
     "commandline"
@@ -24,6 +23,10 @@
   "author": "AJ ONeal <coolaj86@gmail.com> (https://coolaj86.com/)",
   "license": "MPL-2.0",
   "bugs": {
-    "url": "https://git.coolaj86.com/coolaj86/le-challenge-manual.js/issues"
+    "url": "https://git.coolaj86.com/coolaj86/greenlock-challenge-manual.js/issues"
+  },
+  "dependencies": {
+    "greenlock-challenge-dns": "^3.0.3",
+    "greenlock-challenge-http": "^3.0.0"
   }
 }

test.js

@@ -1,20 +1,25 @@
 'use strict';
 
-var challenge = require('./').create({});
+var tester = require('greenlock-challenge-test');
 
-var opts = challenge.getOptions();
+var challenger = require('./').create({});
+
+// 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 token = 'token-id';
+var wildname = '*.example.com';
-var key = 'secret-key';
 
-// this will cause the prompt to appear
+tester.test('http-01', domain, challenger).then(function () {
-challenge.set(opts, domain, token, key, function (err) {
+  console.info("PASS http-01");
-	// if there's an error, there's a problem
+  return tester.test('dns-01', wildname, challenger).then(function () {
-	if (err) {
+    console.info("PASS dns-01");
-		throw err;
+  });
-	}
+}).then(function () {
-
+  return tester.test('fake-01', domain, challenger).then(function () {
-	// this will cause the final completion message to appear
+    console.info("PASS fake-01");
-	challenge.remove(opts, domain, token, function () {
+  });
-	});
+}).catch(function (err) {
+  console.error("FAIL");
+  console.error(err);
+  process.exit(20);
 });