update Koa docs

README.md

@@ -1,75 +1,72 @@
-# greenlock-koa
+# Greenlock™ for Koa
-(previously letsencrypt-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`)
+  * [x] Automatic Registration via SNI (`httpsOptions.SNICallback`)
-  * **registrations** require an **approval callback** in *production*
+  * [x] Secure domain approval callback
-* Automatic Renewal (around 80 days)
+  * [x] Automatic renewal between 10 and 14 days before expiration
-  * **renewals** are *fully automatic* and happen in the *background*, with **no downtime**
+  * [x] Virtual Hosting (vhost) with Multiple Domains & SAN
-* Automatic vhost / virtual hosting
+  * [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)
+QuickStart
-
+==========
-### Part 1: Setup
 
 ```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'
+, server: 'https://acme-staging-v02.api.letsencrypt.org/directory'
-, version: 'draft-11' // Let's Encrypt v2
+
-  
+, 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) {
+//, debug: true
-    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
 });
-```
 
-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 () {
+http.createServer(greenlock.middleware(redirectHttps)).listen(80, function () {
-  console.log('handle ACME http-01 challenge and redirect to https');
+  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 <https://git.coolaj86.com/coolaj86/greenlock-express.js>

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);
+};

package.json

@@ -1,14 +1,14 @@
 {
   "name": "greenlock-koa",
-  "version": "2.0.4",
+  "version": "2.1.2",
-  "description": "Free SSL and Automatic HTTPS for node.js with KOA and other middleware systems via ACME (Let's Encrypt)",
+  "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 <aj@daplie.com> (https://daplie.com/)",
+  "author": "AJ ONeal <coolaj86@gmail.com> (https://coolaj86.com/)",
   "license": "(MIT OR Apache-2.0)"
 }