From e689306a77574c1600788893bf8a09e18a0e4035 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 10 May 2018 12:51:54 -0600 Subject: [PATCH] update Koa docs --- README.md | 151 +++++++++++++++++++++++++++++++++------------------ index.js | 8 +++ package.json | 12 ++-- 3 files changed, 113 insertions(+), 58 deletions(-) create mode 100644 index.js diff --git a/README.md b/README.md index 16634b5..d6adddf 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,72 @@ -# greenlock-koa -(previously letsencrypt-koa) +# Greenlock™ for Koa +An Automated HTTPS ACME client (Let's Encrypt v2) for Koa + +Greenlock™ for +[Browsers](https://git.coolaj86.com/coolaj86/greenlock.html), +[Node.js](https://git.coolaj86.com/coolaj86/greenlock.js), +[Commandline](https://git.coolaj86.com/coolaj86/greenlock-cli.js), +[Express.js](https://git.coolaj86.com/coolaj86/greenlock-express.js), +[Node.js Cluster](https://git.coolaj86.com/coolaj86/greenlock-cluster.js), +[hapi](https://git.coolaj86.com/coolaj86/greenlock-hapi.js), +**Koa**, +and [rill](https://git.coolaj86.com/coolaj86/greenlock-rill.js) | Sponsered by [ppl](https://ppl.family) -| [greenlock (lib)](https://git.coolaj86.com/coolaj86/greenlock.js) -| [greenlock-cli](https://git.coolaj86.com/coolaj86/greenlock-cli.js) -| [greenlock-express](https://git.coolaj86.com/coolaj86/greenlock-express.js) -| [greenlock-cluster](https://git.coolaj86.com/coolaj86/greenlock-cluster.js) -| **greenlock-koa** -| [greenlock-hapi](https://git.coolaj86.com/coolaj86/greenlock-hapi.js) -| -Free SSL and Automatic HTTPS for node.js with KOA and other middleware systems via Let's Encrypt +Features +======== -* Automatic Registration via SNI (`httpsOptions.SNICallback`) - * **registrations** require an **approval callback** in *production* -* Automatic Renewal (around 80 days) - * **renewals** are *fully automatic* and happen in the *background*, with **no downtime** -* Automatic vhost / virtual hosting + * [x] Automatic Registration via SNI (`httpsOptions.SNICallback`) + * [x] Secure domain approval callback + * [x] Automatic renewal between 10 and 14 days before expiration + * [x] Virtual Hosting (vhost) with Multiple Domains & SAN + * [x] and [more](https://git.coolaj86.com/coolaj86/greenlock-express.js) + * [x] plugins for AWS, redis, and more -All you have to do is start the webserver and then visit it at it's domain name. +This module is just an alias for greenlock-express.js, +which works with any middleware system. ## Install ``` -npm install --save greenlock-express@2.x +npm install --save greenlock-koa@2.x ``` -*Pay no attention to the man behind the curtain.* (just ignore that the name of the module is greenlock-express) - -### Part 1: Setup +QuickStart +========== ```javascript 'use strict'; -var le = require('greenlock-express').create({ +////////////////////// +// Greenlock Setup // +////////////////////// + +var greenlock = require('greenlock-koa').create({ + version: 'draft-11' // Let's Encrypt v2 // You MUST change this to 'https://acme-v02.api.letsencrypt.org/directory' in production - server: 'https://acme-staging-v02.api.letsencrypt.org/directory' -, version: 'draft-11' // Let's Encrypt v2 - +, server: 'https://acme-staging-v02.api.letsencrypt.org/directory' + +, email: 'jon@example.com' +, agreeTos: true +, approveDomains: [ 'example.com' ] + + // Join the community to get notified of important updates + // and help make greenlock better +, communityMember: true + , configDir: require('os').homedir() + '/acme/etc' -, approveDomains: function (opts, certs, cb) { - opts.domains = certs && certs.altnames || opts.domains; - opts.email = 'john.doe@example.com' // CHANGE ME - opts.agreeTos = true; - - cb(null, { options: opts, certs: certs }); - } - - , debug: true +//, debug: true }); -``` -WARNING: If you don't do any checks and simply complete `approveRegistration` callback, an attacker will spoof SNI packets with bad hostnames and that will cause you to be rate-limited and or blocked from the ACME server. Alternatively, You can run registration *manually*: -```bash -npm install -g greenlock-cli +////////////////// +// Just add Koa // +////////////////// -greenlock certonly --standalone \ - --server 'https://acme-v02.api.letsencrypt.org/directory' \ - --config-dir ~/letsencrypt/etc \ - --agree-tos --domains example.com --email user@example.com - -# Note: the '--webrootPath' option is also available if you don't want to shut down your webserver to get the cert. -``` - -### Part 2: Just add Koa - -```javascript var http = require('http'); -var https = require('spdy'); +var https = require('https'); var koa = require('koa'); var app = koa(); @@ -77,16 +74,66 @@ app.use(function *() { this.body = 'Hello World'; }); -var server = https.createServer(le.httpsOptions, le.middleware(app.callback())); +// https server +var server = https.createServer(greenlock.tlsOptions, greenlock.middleware(app.callback())); server.listen(443, function () { console.log('Listening at https://localhost:' + this.address().port); }); +// http redirect to https var http = require('http'); var redirectHttps = koa().use(require('koa-sslify')()).callback(); -http.createServer(le.middleware(redirectHttps)).listen(80, function () { - console.log('handle ACME http-01 challenge and redirect to https'); +http.createServer(greenlock.middleware(redirectHttps)).listen(80, function () { + console.log('Listening on port 80 to handle ACME http-01 challenge and redirect to https'); }); ``` + +Handling a dynamic list of domains +======================== + +If you handle multiple domains and you dynamically add new ones, +you'll want to replace the static list of domains in `approveDomains` +with a function like this: + +```js +function approveDomains(opts, certs, cb) { + // This is where you check your database and associated + // email addresses with domains and agreements and such + + // The domains being approved for the first time are listed in opts.domains + // Certs being renewed are listed in certs.altnames + if (certs) { + opts.domains = certs.altnames; + } + else { + // Do something to + opts.email = 'john.doe@example.com'; + opts.agreeTos = true; + } + + opts.communityMember = true; + + // NOTE: you can also change other options such as `challengeType` and `challenge` + // opts.challengeType = 'http-01'; + // opts.challenge = require('le-challenge-fs').create({}); + + cb(null, { options: opts, certs: certs }); +} +``` + +**SECURITY**: Be careful with this. +If you don't check that the domains being requested are the domains you +allow an attacker can make you hit your rate limit for failed verification +attempts. + +See the +[vhost example](https://git.coolaj86.com/coolaj86/greenlock-express.js/src/branch/master/examples/vhost.js) +for an idea of how this is done. + + +More Usage & Troubleshooting +============================ + +See diff --git a/index.js b/index.js new file mode 100644 index 0000000..9b00c5f --- /dev/null +++ b/index.js @@ -0,0 +1,8 @@ +'use strict'; + +module.exports = require('greenlock-express'); +module.exports._greenlockExpressCreate = module.exports.create; +module.create = function (opts) { + opts._communityPackage = opts._communityPackage || 'greenlock-koa'; + return module.exports._greenlockExpressCreate(opts); +}; diff --git a/package.json b/package.json index 28d31f4..038c0d7 100644 --- a/package.json +++ b/package.json @@ -1,14 +1,14 @@ { "name": "greenlock-koa", - "version": "2.0.4", - "description": "Free SSL and Automatic HTTPS for node.js with KOA and other middleware systems via ACME (Let's Encrypt)", + "version": "2.1.2", + "description": "An Automated HTTPS ACME client (Let's Encrypt v2) for Koa", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "repository": { "type": "git", - "url": "git+https://git.daplie.com/Daplie/greenlock-koa.git" + "url": "git+https://git.coolaj86.com/coolaj86/greenlock-koa.js.git" }, "keywords": [ "acme", @@ -16,17 +16,17 @@ "cluster", "free", "greenlock", + "freessl", + "free ssl", "https", "koa", "le", "letsencrypt", - "multi-core", "node", "node.js", - "scale", "ssl", "tls" ], - "author": "AJ ONeal (https://daplie.com/)", + "author": "AJ ONeal (https://coolaj86.com/)", "license": "(MIT OR Apache-2.0)" }