root
/
acme-challenge-test.js
mirror of https://git.coolaj86.com/coolaj86/acme-challenge-test.js.git
2
0
Fork 0
Code Issues 1 Releases Wiki Activity

v3.1.0: update docs, default to testing full zones

This commit is contained in:
AJ ONeal 2019-06-06 23:04:51 -06:00
parent f2373a09de
commit 17e409b158
3 changed files with 117 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
README.md
View File

@ -19,20 +19,31 @@ npm install --save-dev acme-challenge-test@3.x
## Usage ## Usage
```js ```js
var tester = require("acme-challenge-test"); var tester = require('acme-challenge-test');
//var challenger = require('acme-http-01-cli').create({}); //var challenger = require('acme-http-01-cli').create({});
//var challenger = require('acme-dns-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' YOUR_TOKEN_OPTION: 'SOME_API_KEY'
}); });
// The dry-run tests can pass on, literally, 'example.com' // The dry-run tests can pass on, literally, 'example.com'
// but the integration tests require that you have control over the domain // but the integration tests require that you have control over the domain
var domain = "example.com"; var zone = 'example.com';
tester.test("http-01", domain, challenger).then(function() { tester.testZone('dns-01', zone, challenger).then(function() {
console.info("PASS"); console.info('PASS');
});
```
**Note**: If the service you are testing only handles individual records
(not multiple records in a zone), you can use `testRecord` instead:
```js
var record = 'foo.example.com';
tester.testRecord('dns-01', record, challenger).then(function() {
console.info('PASS');
}); });
``` ```
@ -44,7 +55,11 @@ 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-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) - [`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-). 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-).
If you are building a plugin, please let us know.
We would like to co-author and help maintain and promote your module.
## Example ## Example
@ -62,30 +77,30 @@ var tester = require('acme-challenge-test');
var domain = 'example.com'; var domain = 'example.com';
tester tester
.test('http-01', domain, { .testRecord('http-01', domain, {
// Should set a TXT record for dnsHost with dnsAuthorization and ttl || 300 // Should set a TXT record for dnsHost with dnsAuthorization and ttl || 300
set: function(opts) { set: function(opts) {
console.log('set opts:', opts); console.log('set opts:', opts);
throw new Error('set not implemented'); throw new Error('set not implemented');
}, },
// Should remove the *one* TXT record for dnsHost with dnsAuthorization // Should remove the *one* TXT record for dnsHost with dnsAuthorization
// Should NOT remove otherrecords for dnsHost (wildcard shares dnsHost with // Should NOT remove otherrecords for dnsHost (wildcard shares dnsHost with
// non-wildcard) // non-wildcard)
remove: function(opts) { remove: function(opts) {
console.log('remove opts:', opts); console.log('remove opts:', opts);
throw new Error('remove not implemented'); throw new Error('remove not implemented');
}, },
// Should get the record via the DNS server's API // Should get the record via the DNS server's API
get: function(opts) { get: function(opts) {
console.log('get opts:', opts); console.log('get opts:', opts);
throw new Error('get not implemented'); throw new Error('get not implemented');
} }
}) })
.then(function() { .then(function() {
console.info('PASS'); console.info('PASS');
}); });
``` ```
## dns-01 vs http-01 ## dns-01 vs http-01
@ -107,79 +122,78 @@ Here's a quick pseudo stub-out of what a test-passing plugin object might look l
```js ```js
tester tester
.test('dns-01', 'example.com', { .testZone('dns-01', 'example.com', {
set: function(opts) {
set: function(opts) { var ch = opts.challenge;
var ch = opts.challenge; // { type: 'dns-01' // or 'http-01'
// { type: 'dns-01' // or 'http-01' // , identifier: { type: 'dns', value: 'example.com' }
// , identifier: { type: 'dns', value: 'example.com' } // , wildcard: false
// , wildcard: false // , token: 'xxxx'
// , token: 'xxxx' // , keyAuthorization: 'xxxx.yyyy'
// , keyAuthorization: 'xxxx.yyyy' // , dnsHost: '_acme-challenge.example.com'
// , dnsHost: '_acme-challenge.example.com' // , dnsAuthorization: 'zzzz' }
// , dnsAuthorization: 'zzzz' }
return YourApi('POST', 'https://example.com/api/dns/txt', { return YourApi('POST', 'https://example.com/api/dns/txt', {
host: ch.dnsHost, host: ch.dnsHost,
record: ch.dnsAuthorization record: ch.dnsAuthorization
}); });
}, },
get: function(query) {
var ch = query.challenge;
// { type: 'dns-01' // or 'http-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('GET', 'https://example.com/api/dns/txt', { get: function(query) {
host: ch.dnsHost var ch = query.challenge;
}).then(function(secret) { // { type: 'dns-01' // or 'http-01', 'tls-alpn-01', etc
// http-01 // , identifier: { type: 'dns', value: 'example.com' }
//return { keyAuthorization: secret }; // // http-01 only
// dns-01 // , token: 'xxxx'
return { dnsAuthorization: secret }; // , url: '...' // for testing and debugging
}); // // dns-01 only, for testing / dubgging
}, // , altname: '...'
// , dnsHost: '...'
remove: function(opts) { // , wildcard: false }
var ch = opts.challenge; // Note: query.identifier.value is different for http-01 than for dns-01
// same options as in `set()` (which are not the same as `get()`
return YourApi('DELETE', 'https://example.com/api/dns/txt/' + ch.dnsHost); return YourApi('GET', 'https://example.com/api/dns/txt', {
} host: ch.dnsHost
}) }).then(function(secret) {
.then(function() { // http-01
console.info('PASS'); //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: Where `YourApi` might look something like this:
```js ```js
var YourApi = function createApi(config) { var YourApi = function createApi(config) {
var request = require('@root/request'); var request = require('@root/request');
request = require('util').promisify(request); request = require('util').promisify(request);
return function (method, url, body) { return function(method, url, body) {
return request({ return request({
method: method, method: method,
url: url, url: url,
json: body || true, json: body || true,
headers: { headers: {
Authorization: 'Bearer ' + config.apiToken Authorization: 'Bearer ' + config.apiToken
} }
}).then(function(resp) { }).then(function(resp) {
return resp.body; return resp.body;
}); });
} };
} };
``` ```
### Two notes: ### Two notes:
@ -191,6 +205,6 @@ location on an http serever, set DNS records, or add the appropriate data to the
Note 2: 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 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 `*.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 `bar.foo.example.com` the `dnsHost` will be `_acme-challenge.bar.foo.example.com`

10
index.js
View File

@ -179,7 +179,7 @@ function run(challenger, opts) {
}); });
} }
module.exports.test = function(type, zone, challenger) { function testZone(type, zone, challenger) {
var domains = [zone, 'foo.' + zone]; var domains = [zone, 'foo.' + zone];
if ('dns-01' === type) { if ('dns-01' === type) {
domains.push('*.foo.' + zone); domains.push('*.foo.' + zone);
@ -191,7 +191,7 @@ module.exports.test = function(type, zone, challenger) {
return; return;
} }
console.info("TEST '%s'", domain); console.info("TEST '%s'", domain);
return testOne(type, domain, challenger).then(function() { return testRecord(type, domain, challenger).then(function() {
console.info("PASS '%s'", domain); console.info("PASS '%s'", domain);
return next(); return next();
}); });
@ -208,7 +208,7 @@ module.exports.test = function(type, zone, challenger) {
}); });
}; };
function testOne(type, altname, challenger) { function testRecord(type, altname, challenger) {
var expires = new Date(Date.now() + 10 * 60 * 1000).toISOString(); 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');
@ -248,4 +248,6 @@ function testOne(type, altname, challenger) {
return run(challenger, { challenge: challenge }); return run(challenger, { challenge: challenge });
} }
module.exports._test = testOne; module.exports.testRecord = testRecord;
module.exports.testZone = testZone;
module.exports.test = testZone;

2
package.json
View File

@ -1,6 +1,6 @@
{ {
"name": "acme-challenge-test", "name": "acme-challenge-test",
"version": "3.0.5", "version": "3.1.0",
"description": "The base set of tests for all ACME challenge strategies. Any `acme-http-01-`, `acme-dns-01-`, `acme-challenge-`, or greenlock plugin should be able to pass these tests.", "description": "The base set of tests for all ACME challenge strategies. Any `acme-http-01-`, `acme-dns-01-`, `acme-challenge-`, or greenlock plugin should be able to pass these tests.",
"main": "index.js", "main": "index.js",
"homepage": "https://git.rootprojects.org/root/acme-challenge-test.js", "homepage": "https://git.rootprojects.org/root/acme-challenge-test.js",