roster-server 1.9.8 → 2.0.2

package/vendor/greenlock-express/WALKTHROUGH.md

@@ -0,0 +1,256 @@
+# Greenlock Express Walkthrough
+
+This will show you the basics of how to
+
+1. Create a node project
+2. Create an http app (i.e. express)
+3. Serve with Greenlock Express
+4. Manage SSL Certificates and Domains
+
+## 1. Create a node project
+
+Create an empty node project.
+
+Be sure to fill out the package name, version, and an author email.
+
+```bash
+mkdir ~/my-project
+pushd ~/my-project
+npm init
+```
+
+## 2. Create an http app (i.e. express)
+
+This example is shown with Express, but any node app will do. Greenlock
+works with everything.
+(or any node-style http app)
+
+`my-express-app.js`:
+
+```js
+"use strict";
+
+// A plain, node-style app
+
+function myPlainNodeHttpApp(req, res) {
+    res.end("Hello, Encrypted World!");
+}
+
+// Wrap that plain app in express,
+// because that's what you're used to
+
+var express = require("express");
+var app = express();
+app.get("/", myPlainNodeHttpApp);
+
+// export the app normally
+// do not .listen()
+
+module.exports = app;
+```
+
+## 3. Serve with Greenlock Express
+
+Greenlock Express is designed with these goals in mind:
+
+-   Simplicity and ease-of-use
+-   Performance and scalability
+-   Configurability and control
+
+You can start with **near-zero configuration** and
+slowly add options for greater performance and customization
+later, if you need them.
+
+`server.js`:
+
+```js
+"use strict";
+
+//var pkg = require("./package.json");
+var app = require("./app.js");
+
+require("greenlock-express")
+    .init({
+        // where to find .greenlockrc and set default paths
+        packageRoot: __dirname,
+
+        // where config and certificate stuff go
+        configDir: "./greenlock.d",
+
+        // contact for security and critical bug notices
+        maintainerEmail: pkg.author,
+
+        // name & version for ACME client user agent
+        //packageAgent: pkg.name + "/" + pkg.version,
+
+        // whether or not to run at cloudscale
+        cluster: false
+    })
+    .serve(app);
+```
+
+And start your server:
+
+```bash
+# Allow non-root node to use ports 80 (HTTP) and 443 (HTTPS)
+sudo setcap 'cap_net_bind_service=+ep' $(which node)
+```
+
+```bash
+# `npm start` will call `node ./server.js` by default
+npm start
+```
+
+```bash
+# use --staging to use the development API until you're ready to get real certificates
+npm start -- --staging
+```
+
+```txt
+Greenlock v4.0.0
+Greenlock Config Dir/File: ./greenlock.d/config.json
+
+Listening on 0.0.0.0:80 for ACME challenges and HTTPS redirects
+Listening on 0.0.0.0:443 for secure traffic
+```
+
+## 4. Manage SSL Certificates and Domains
+
+The management API is built to work with Databases, S3, etc.
+
+By default, it's just a simple config file and directory.
+
+```bash
+# see which manager and what options are in use
+cat .greenlockrc
+```
+
+<details>
+<summary>Example Output</summary>
+
+```json
+{
+    "manager": {
+        "module": "@greenlock/manager"
+    },
+    "configDir": "./greenlock.d"
+}
+```
+
+</details>
+
+```bash
+# show the global defaults with the CLI
+npx greenlock defaults
+```
+
+```js
+// show the global defaults with the API
+var defaults = await greenlock.defaults();
+```
+
+<details>
+<summary>Example Output</summary>
+
+```json
+{
+    "store": {
+        "module": "greenlock-store-fs",
+        "basePath": "./greenlock.d"
+    },
+    "challenges": {
+        "http-01": {
+            "module": "acme-http-01-standalone"
+        }
+    },
+    "renewOffset": "-45d",
+    "renewStagger": "3d",
+    "accountKeyType": "EC-P256",
+    "serverKeyType": "RSA-2048",
+    "subscriberEmail": "jon@example.com",
+    "agreeToTerms": true
+}
+```
+
+</details>
+
+```bash
+# show per-site configs with the CLI
+npx greenlock config --subject example.com
+```
+
+```js
+// show a site config with the API
+greenlock.sites.get({ subject: "example.com" });
+```
+
+<details>
+<summary>Example Output</summary>
+
+```json
+{
+    "subject": "example.com",
+    "altnames": ["example.com"],
+    "renewAt": 1576638107754,
+    "defaults": {
+        "store": {
+            "module": "greenlock-store-fs",
+            "basePath": "./greenlock.d"
+        },
+        "challenges": {
+            "http-01": {
+                "module": "acme-http-01-standalone"
+            }
+        }
+    }
+}
+```
+
+</details>
+
+Management can be done via the **CLI** or the JavaScript [**API**](https://git.rootprojects.org/root/greenlock.js).
+Since this is the QuickStart, we'll demo the **CLI**:
+
+You need to create a Let's Encrypt _subscriber account_, which can be done globally, or per-site.
+All individuals, and most businesses, should set this globally:
+
+```bash
+# Set a global subscriber account with the CLI
+npx greenlock defaults --subscriber-email 'mycompany@example.com' --agree-to-terms true
+```
+
+```js
+// set a global subscriber account with the API
+greenlock.manager.defaults({
+    subscriberEmail: "mycompany@example.com",
+    agreeToTerms: true
+});
+```
+
+<!-- todo print where the key was saved -->
+
+A Let's Encrypt SSL certificate has a "Subject" (Primary Domain) and up to 100 "Alternative Names"
+(of which the first _must_ be the subject).
+
+```bash
+# Add a certificate with specific domains with the CLI
+npx greenlock add --subject example.com --altnames example.com,www.example.com
+```
+
+```js
+// Add a certificate with specific domains with the API
+greenlock.sites.add({
+    subject: "example.com",
+    altnames: ["example.com"]
+});
+```
+
+<!-- todo print where the cert was saved -->
+
+Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require
+[**DNS validation**](https://git.rootprojects.org/root/greenlock-exp).
+
+-   DNS Validation
+    -   [**Wildcards**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/wildcards/) (coming soon)
+    -   [**Localhost**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/localhost/) (coming soon)
+    -   [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/) (coming soon)

package/vendor/greenlock-express/config.js

@@ -0,0 +1,20 @@
+"use strict";
+
+var path = require("path");
+module.exports = {
+    email: "jon.doe@example.com",
+    configDir: path.join(__dirname, "acme"),
+    srv: "/srv/www/",
+    api: "/srv/api/",
+    proxy: {
+        "example.com": "http://localhost:4080",
+        "*.example.com": "http://localhost:4080"
+    },
+
+    // DNS-01 challenges only
+    challenges: {
+        "*.example.com": require("acme-dns-01-YOUR_DNS_HOST").create({
+            token: "xxxx"
+        })
+    }
+};

package/vendor/greenlock-express/demo.js

@@ -0,0 +1,35 @@
+"use strict";
+
+require("./")
+    .init(initialize)
+    .serve(worker)
+    .master(function() {
+        console.log("Hello from master");
+    });
+
+function initialize() {
+    var pkg = require("./package.json");
+    var config = {
+        package: {
+            name: "Greenlock_Express_Demo",
+            version: pkg.version,
+            author: pkg.author
+        },
+        staging: true,
+        cluster: true,
+
+        notify: function(ev, params) {
+            console.info(ev, params);
+        }
+    };
+    return config;
+}
+
+function worker(glx) {
+    console.info();
+    console.info("Hello from worker #" + glx.id());
+
+    glx.serveApp(function(req, res) {
+        res.end("Hello, Encrypted World!");
+    });
+}

package/vendor/greenlock-express/examples/cluster/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "cluster-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "John Doe <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

package/vendor/greenlock-express/examples/express/my-express-app.js

@@ -0,0 +1,17 @@
+"use strict";
+
+var express = require("express");
+var app = express();
+
+app.use("/", function(req, res) {
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.end("Hello, World!\n\n💚 🔒.js");
+});
+
+// DO NOT DO app.listen() unless we're testing this directly
+if (require.main === module) {
+    app.listen(3000);
+}
+
+// Instead do export the app:
+module.exports = app;

package/vendor/greenlock-express/examples/express/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "express-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "John Doe <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

package/vendor/greenlock-express/examples/http/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "http-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "John Doe <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

package/vendor/greenlock-express/examples/http-proxy/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "http-proxy-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "John Doe <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

package/vendor/greenlock-express/examples/http2/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "http2-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "John Doe <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

package/vendor/greenlock-express/examples/https/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "https1-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "John Doe <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

package/vendor/greenlock-express/examples/quickstart/README.md

@@ -0,0 +1,22 @@
+# Quick Start for Let's Encrypt with Node.js
+
+```js
+npm install --save greenlock-express
+```
+
+Manage via API or the config file:
+
+`~/.config/greenlock/manage.json`: (default filesystem config)
+
+```json
+{
+    "subscriberEmail": "letsencrypt-test@therootcompany.com",
+    "agreeToTerms": true,
+    "sites": {
+        "example.com": {
+            "subject": "example.com",
+            "altnames": ["example.com", "www.example.com"]
+        }
+    }
+}
+```

package/vendor/greenlock-express/examples/quickstart/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "quickstart-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "John Doe <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

package/vendor/greenlock-express/examples/socket.io/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "socket-io-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "John Doe <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

package/vendor/greenlock-express/examples/websockets/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "websockets-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "John Doe <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

package/vendor/greenlock-express/greenlock-express.js

@@ -0,0 +1,48 @@
+"use strict";
+
+require("./lib/compat");
+var cluster = require("cluster");
+
+// Greenlock Express
+var GLE = module.exports;
+
+// Node's cluster is awesome, because it encourages writing scalable services.
+//
+// The point of this provide an API that is consistent between single-process
+// and multi-process services so that beginners can more easily take advantage
+// of what cluster has to offer.
+//
+// This API provides just enough abstraction to make it easy, but leaves just
+// enough hoopla so that there's not a large gap in understanding what happens
+// under the hood. That's the hope, anyway.
+
+GLE.init = function(fn) {
+    // See https://git.coolaj86.com/coolaj86/greenlock-express.js/issues/80
+    if (fn && false !== fn.cluster && cluster.isWorker) {
+        // ignore the init function and launch the worker
+        return require("./worker.js").create();
+    }
+
+    var opts;
+    if ("function" === typeof fn) {
+        opts = fn();
+    } else if ("object" === typeof fn) {
+        opts = fn;
+    }
+    if (!opts || "object" !== typeof opts) {
+        throw new Error("the `Greenlock.init(fn)` function should return an object `{ packageRoot, cluster }`");
+    }
+
+    // just for ironic humor
+    ["cloudnative", "cloudscale", "webscale", "distributed", "blockchain"].forEach(function(k) {
+        if (opts[k]) {
+            opts.cluster = true;
+        }
+    });
+
+    if (opts.cluster) {
+        return require("./master.js").create(opts);
+    }
+
+    return require("./single.js").create(opts);
+};

package/vendor/greenlock-express/greenlock-shim.js

@@ -0,0 +1,72 @@
+"use strict";
+
+module.exports.create = function(opts) {
+    var Greenlock = require("@root/greenlock");
+    //var Init = require("@root/greenlock/lib/init.js");
+    var greenlock = opts.greenlock;
+
+    /*
+    if (!greenlock && opts.packageRoot) {
+        try {
+            greenlock = require(path.resolve(opts.packageRoot, "greenlock.js"));
+        } catch (e) {
+            if ("MODULE_NOT_FOUND" !== e.code) {
+                throw e;
+            }
+        }
+    }
+    */
+
+    if (!greenlock) {
+        //opts = Init._init(opts);
+        greenlock = Greenlock.create(opts);
+    }
+    opts.packageAgent = addGreenlockAgent(opts);
+
+    try {
+        if (opts.notify) {
+            greenlock._defaults.notify = opts.notify;
+        }
+    } catch (e) {
+        console.error("Developer Error: notify not attached correctly");
+    }
+
+    // re-export as top-level function to simplify rpc with workers
+    greenlock.getAcmeHttp01ChallengeResponse = function(opts) {
+        return greenlock.challenges.get(opts);
+    };
+
+    greenlock._find({}).then(function(sites) {
+        if (sites.length <= 0) {
+            console.warn("Warning: `find({})` returned 0 sites.");
+            console.warn("         Does `" + greenlock.manager._modulename + "` implement `find({})`?");
+            console.warn("         Did you add sites?");
+            console.warn("         npx greenlock add --subject example.com --altnames example.com");
+            return;
+        }
+        // console.info("Ready to Serve:");
+
+        var max = 3;
+        if (sites.length >= 1) {
+            sites.slice(0, max).forEach(function(site) {
+                // console.info("\t", site.altnames.join(" "));
+            });
+        }
+        if (sites.length > max) {
+            // console.info("and %d others", sites.length - max);
+        }
+    });
+
+    return greenlock;
+};
+
+function addGreenlockAgent(opts) {
+    // Add greenlock as part of Agent, unless this is greenlock
+    var packageAgent = opts.packageAgent || "";
+    if (!/greenlock(-express|-pro)?/i.test(packageAgent)) {
+        var pkg = require("./package.json");
+        packageAgent += " Greenlock_Express/" + pkg.version;
+    }
+
+    return packageAgent.trim();
+}