From 0d27ad4dd4f7b310419170551c792c75ef7198e7 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 6 Jun 2019 05:41:27 +0000 Subject: [PATCH 1/8] add another sample --- README.md | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a44c74a..f16807c 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ The tests account for single-domain certificates (`example.com`) as well as mult wildcards (`*.example.com`), and valid private / localhost certificates. As someone creating a challenge strategy that's not something you have to take special consideration for - just pass the tests. +**Node v6 Support**: Please build community plugins using node v6 / vanillajs to ensure that all acme.js and greenlock.js users are fully supported. + ## Install ```bash @@ -45,7 +47,44 @@ which you should use as a model for any plugins that you create. See `example.js` (it works). -## Overview +## Starter Template + +Here's what you could start with. + +```js +var tester = require("acme-challenge-test"); + +// 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"; + +tester.test("http-01", domain, { + + // Should set a TXT record for opts.dnsHost with opts.dnsAuthorization for opts.ttl || 300 + set: function (opts) { + console.log("set opts:", opts); + throw new Error("set not implemented"); + }, + + // Should remove the *one* TXT record for opts.dnsHost with opts.dnsAuthorization + // Should NOT remove otherrecords for opts.dnsHost (wildcard shares dnsHost with non-wildcard) + remove: function (opts) { + console.log("remove opts:", opts); + throw new Error("remove not implemented"); + }, + + // Should get the record via the DNS server's API + get: function (opts) { + console.log("get opts:", opts); + throw new Error("get not implemented"); + } + +}).then(function() { + console.info("PASS"); +}); +``` + +## Detailed Overview Here's a quick pseudo stub-out of what a test-passing plugin object might look like: From 2b51651e6f45df49522140269cc35e50b36a3800 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 6 Jun 2019 06:07:08 +0000 Subject: [PATCH 2/8] more notes --- README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f16807c..d1c1a60 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,19 @@ tester.test("http-01", domain, { }); ``` +## dns-01 vs http-01 + +For `type` http-01: + + // `altname` is the name of the domain + // `token` is the name of the file ( .well-known/acme-challenge/`token` ) + // `keyAuthorization` is the contents of the file + +For `type` dns-01: + + // `dnsHost` is the domain/subdomain/host + // `dnsAuthorization` is the value of the TXT record + ## Detailed Overview Here's a quick pseudo stub-out of what a test-passing plugin object might look like: @@ -133,5 +146,17 @@ tester.test('http-01', 'example.com', { }); ``` -Note: The `API.get()`, `API.set()`, and `API.remove()` is where you do your magic up to upload a file to the correct +### Two notes: + +Note 1: + +The `API.get()`, `API.set()`, and `API.remove()` is where you do your magic up to upload a file to the correct location on an http serever, set DNS records, or add the appropriate data to the database that handles such things. + +Note 2: + +When `altname` is `foo.example.com` the `dnsHost` will be `_acme-challenge.foo.example.com` + +When `altname` is `*.foo.example.com` the `dnsHost` will _still_ be `_acme-challenge.foo.example.com` + +When `altname` is `bar.foo.example.com` the `dnsHost` will be `_acme-challenge.bar.foo.example.com` From 331d370eaf6dee6ceadda669271658765a5d232a Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 6 Jun 2019 06:11:59 +0000 Subject: [PATCH 3/8] mention ACME.js --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d1c1a60..6bb492a 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # [acme-challenge-test](https://git.rootprojects.org/root/acme-challenge-test.js.git) | A [Root](https://rootprojects.org) Project The test harness you should use when writing an ACME challenge strategy -for [Greenlock](https://git.coolaj86.com/coolaj86/greenlock-express.js) v2.7+ (and v3). +for [ACME.js](https://git.coolaj86.com/coolaj86/acme-v2.js) and also [Greenlock](https://git.coolaj86.com/coolaj86/greenlock-express.js) v2.7+ (and v3). All implementations MUST pass these tests, which is a very easy thing to do (just `set()`, `get()`, and `remove()`). From 3db24ffeb585a2e8d6bfdefeb8d60d10ce8354bf Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 6 Jun 2019 06:15:51 +0000 Subject: [PATCH 4/8] update docs --- README.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 6bb492a..9cacfbc 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# [acme-challenge-test](https://git.rootprojects.org/root/acme-challenge-test.js.git) | A [Root](https://rootprojects.org) Project +# [acme-challenge-test](https://git.rootprojects.org/root/acme-challenge-test.js.git) | a [Root](https://rootprojects.org) project The test harness you should use when writing an ACME challenge strategy for [ACME.js](https://git.coolaj86.com/coolaj86/acme-v2.js) and also [Greenlock](https://git.coolaj86.com/coolaj86/greenlock-express.js) v2.7+ (and v3). @@ -6,8 +6,7 @@ for [ACME.js](https://git.coolaj86.com/coolaj86/acme-v2.js) and also [Greenlock] All implementations MUST pass these tests, which is a very easy thing to do (just `set()`, `get()`, and `remove()`). The tests account for single-domain certificates (`example.com`) as well as multiple domain certs (SAN / AltName), -wildcards (`*.example.com`), and valid private / localhost certificates. As someone creating a challenge strategy -that's not something you have to take special consideration for - just pass the tests. +wildcards (`*.example.com`), and valid private / localhost certificates. No worries on your end, just pass the tests. 👌 **Node v6 Support**: Please build community plugins using node v6 / vanillajs to ensure that all acme.js and greenlock.js users are fully supported. @@ -43,6 +42,8 @@ which you should use as a model for any plugins that you create. - [`acme-http-01-cli`](https://git.rootprojects.org/root/acme-http-01-cli.js) - [`acme-dns-01-cli`](https://git.rootprojects.org/root/acme-dns-01-cli.js) +You can find other implementations by searching npm for [acme-http-01-](https://www.npmjs.com/search?q=acme-http-01-) and [acme-dns-01-](https://www.npmjs.com/search?q=acme-dns-01-). + ## Example See `example.js` (it works). @@ -155,8 +156,6 @@ location on an http serever, set DNS records, or add the appropriate data to the Note 2: -When `altname` is `foo.example.com` the `dnsHost` will be `_acme-challenge.foo.example.com` - -When `altname` is `*.foo.example.com` the `dnsHost` will _still_ be `_acme-challenge.foo.example.com` - -When `altname` is `bar.foo.example.com` the `dnsHost` will be `_acme-challenge.bar.foo.example.com` +* When `altname` is `foo.example.com` the `dnsHost` will be `_acme-challenge.foo.example.com` +* When `altname` is `*.foo.example.com` the `dnsHost` will _still_ be `_acme-challenge.foo.example.com`!! +* When `altname` is `bar.foo.example.com` the `dnsHost` will be `_acme-challenge.bar.foo.example.com` From d2fca0eea70f9e66d2065112ffc3931ab082be51 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 6 Jun 2019 06:20:19 +0000 Subject: [PATCH 5/8] update docs --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9cacfbc..ad87cae 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,9 @@ var tester = require("acme-challenge-test"); //var challenger = require('acme-http-01-cli').create({}); //var challenger = require('acme-dns-01-cli').create({}); -var challenger = require("./YOUR-CHALLENGE-STRATEGY").create({}); +var challenger = require("./YOUR-CHALLENGE-STRATEGY").create({ + YOUR_TOKEN_OPTION: 'SOME_API_KEY' +}); // The dry-run tests can pass on, literally, 'example.com' // but the integration tests require that you have control over the domain From fa912800b41c659ac2d0608a79315df0508e57aa Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 6 Jun 2019 06:49:46 +0000 Subject: [PATCH 6/8] make Prettier --- README.md | 157 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 95 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index ad87cae..2d2f9c4 100644 --- a/README.md +++ b/README.md @@ -55,36 +55,37 @@ See `example.js` (it works). Here's what you could start with. ```js -var tester = require("acme-challenge-test"); +var tester = require('acme-challenge-test'); // 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, { +tester + .test('http-01', domain, { + // Should set a TXT record for dnsHost with dnsAuthorization and ttl || 300 + set: function(opts) { + console.log('set opts:', opts); + throw new Error('set not implemented'); + }, - // Should set a TXT record for opts.dnsHost with opts.dnsAuthorization for opts.ttl || 300 - set: function (opts) { - console.log("set opts:", opts); - throw new Error("set not implemented"); - }, - - // Should remove the *one* TXT record for opts.dnsHost with opts.dnsAuthorization - // Should NOT remove otherrecords for opts.dnsHost (wildcard shares dnsHost with non-wildcard) - remove: function (opts) { - console.log("remove opts:", opts); - throw new Error("remove not implemented"); - }, - - // Should get the record via the DNS server's API - get: function (opts) { - console.log("get opts:", opts); - throw new Error("get not implemented"); - } + // Should remove the *one* TXT record for dnsHost with dnsAuthorization + // Should NOT remove otherrecords for dnsHost (wildcard shares dnsHost with + // non-wildcard) + remove: function(opts) { + console.log('remove opts:', opts); + throw new Error('remove not implemented'); + }, -}).then(function() { - console.info("PASS"); -}); + // Should get the record via the DNS server's API + get: function(opts) { + console.log('get opts:', opts); + throw new Error('get not implemented'); + } + }) + .then(function() { + console.info('PASS'); + }); ``` ## dns-01 vs http-01 @@ -105,48 +106,80 @@ For `type` dns-01: Here's a quick pseudo stub-out of what a test-passing plugin object might look like: ```js -tester.test('http-01', 'example.com', { - set: function (opts) { - var ch = opts.challenge; - // { type: 'http-01' // or 'dns-01' - // , identifier: { type: 'dns', value: 'example.com' } - // , wildcard: false - // , token: 'xxxx' - // , keyAuthorization: 'xxxx.yyyy' - // , dnsHost: '_acme-challenge.example.com' - // , dnsAuthorization: 'zzzz' } +tester + .test('http-01', 'example.com', { + + set: function(opts) { + var ch = opts.challenge; + // { type: 'http-01' // or 'dns-01' + // , identifier: { type: 'dns', value: 'example.com' } + // , wildcard: false + // , token: 'xxxx' + // , keyAuthorization: 'xxxx.yyyy' + // , dnsHost: '_acme-challenge.example.com' + // , dnsAuthorization: 'zzzz' } - return API.set(...); - } -, get: function (query) { - var ch = query.challenge; - // { type: 'http-01' // or 'dns-01', 'tls-alpn-01', etc - // , identifier: { type: 'dns', value: 'example.com' } - // // http-01 only - // , token: 'xxxx' - // , url: '...' // for testing and debugging - // // dns-01 only, for testing / dubgging - // , altname: '...' - // , dnsHost: '...' - // , wildcard: false } - // Note: query.identifier.value is different for http-01 than for dns-01 + return YourApi('POST', 'https://example.com/api/dns/txt', { + host: ch.dnsHost, + record: ch.dnsAuthorization + }); + }, + + get: function(query) { + var ch = query.challenge; + // { type: 'http-01' // or 'dns-01', 'tls-alpn-01', etc + // , identifier: { type: 'dns', value: 'example.com' } + // // http-01 only + // , token: 'xxxx' + // , url: '...' // for testing and debugging + // // dns-01 only, for testing / dubgging + // , altname: '...' + // , dnsHost: '...' + // , wildcard: false } + // Note: query.identifier.value is different for http-01 than for dns-01 - return API.get(...).then(function (secret) { - // http-01 - return { keyAuthorization: secret }; - // dns-01 - //return { dnsAuthorization: secret }; + return YourApi('GET', 'https://example.com/api/dns/txt', { + host: ch.dnsHost + }).then(function(secret) { + // http-01 + return { keyAuthorization: secret }; + // dns-01 + //return { dnsAuthorization: secret }; + }); + }, + + remove: function(opts) { + var ch = opts.challenge; + // same options as in `set()` (which are not the same as `get()` + + return YourApi('DELETE', 'https://example.com/api/dns/txt/' + ch.dnsHost); + } + }) + .then(function() { + console.info('PASS'); + }); +``` + +Where `YourApi` might look something like this: + +```js +var YourApi = function createApi(config) { + var request = require('@root/request'); + request = require('util').promisify(request); + + return function (method, url, body) { + return request({ + method: method, + url: url, + json: body || true, + headers: { + Authorization: 'Bearer ' + config.apiToken + } + }).then(function(resp) { + return resp.body; }); } -, remove: function (opts) { - var ch = opts.challenge; - // same options as in `set()` (which are not the same as `get()` - - return API.remove(...); - } -}).then(function () { - console.info("PASS"); -}); +} ``` ### Two notes: From d3f958df9856716b1f207d00d8febd4da0d6a10b Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 6 Jun 2019 06:50:24 +0000 Subject: [PATCH 7/8] typo fix http-01 => dns-01 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2d2f9c4..0eefcf1 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ Here's a quick pseudo stub-out of what a test-passing plugin object might look l ```js tester - .test('http-01', 'example.com', { + .test('dns-01', 'example.com', { set: function(opts) { var ch = opts.challenge; From 595de158eede559661f5b6a49263ca134da7f1e9 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 6 Jun 2019 06:53:05 +0000 Subject: [PATCH 8/8] more http-01 => dns-01 --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0eefcf1..a017ce8 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ tester set: function(opts) { var ch = opts.challenge; - // { type: 'http-01' // or 'dns-01' + // { type: 'dns-01' // or 'http-01' // , identifier: { type: 'dns', value: 'example.com' } // , wildcard: false // , token: 'xxxx' @@ -127,7 +127,7 @@ tester get: function(query) { var ch = query.challenge; - // { type: 'http-01' // or 'dns-01', 'tls-alpn-01', etc + // { type: 'dns-01' // or 'http-01', 'tls-alpn-01', etc // , identifier: { type: 'dns', value: 'example.com' } // // http-01 only // , token: 'xxxx' @@ -142,9 +142,9 @@ tester host: ch.dnsHost }).then(function(secret) { // http-01 - return { keyAuthorization: secret }; + //return { keyAuthorization: secret }; // dns-01 - //return { dnsAuthorization: secret }; + return { dnsAuthorization: secret }; }); },