From 3a0af2c2e7f0748b098d8ef2c702d5bf2d8deb8a Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Mon, 4 Nov 2019 21:28:49 -0700 Subject: [PATCH] v3.0.0: @greenlock/manager --- .gitignore | 2 + .prettierrc | 8 ++++ README.md | 119 +++++++++++++++++++++++++++++++++++++++++++++- manager.js | 87 +++++++++++++++++++++++++++++++++ package-lock.json | 43 +++++++++++++++++ package.json | 30 ++++++++++++ tests/index.js | 25 ++++++++++ 7 files changed, 312 insertions(+), 2 deletions(-) create mode 100644 .prettierrc create mode 100644 manager.js create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 tests/index.js diff --git a/.gitignore b/.gitignore index 144585f..c161e1a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +*delete-me* + # ---> Node # Logs logs diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..2fc1676 --- /dev/null +++ b/.prettierrc @@ -0,0 +1,8 @@ +{ + "bracketSpacing": true, + "printWidth": 100, + "singleQuote": false, + "tabWidth": 4, + "trailingComma": "none", + "useTabs": false +} diff --git a/README.md b/README.md index cba44e0..59183f9 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,118 @@ -# greenlock-manager.js +# [Greenlock Manager](https://git.rootprojects.org/root/greenlock-manager.js) -FileSytem-based Manager with optional encrypted Cloud backup for Greenlock SSL \ No newline at end of file +Manages SSL Certificate issue and renewal for [Greenlock](https://git.rootprojects.org/root/greenlock-manager.js). + +Saves global and per-site config to a local File Sytem (current), with optional encrypted Cloud backup (coming soon). + +```bash +npm install --save greenlock@3 +npm install --save greenlock-manager@3 +``` + +# Greenlock Manager CLI & API + +All manager plugins have the **same API**. + +The manager-specific implementation is overlaid by Greenlock with error handling and common utilities, +and then exposed as documented here. + +**Note**: Most people do not need to (and should not) not use the JavaScript API. +Instead, use the CLI (current) or Web API (coming soon). + +## Initialize the Manager + +```bash +npx greenlock init --manager cloud --manager-token 'xxxx' --manager-config-file './greenlock.json' +``` + +Note: You **should not** initialize greenlock directly as +this may make it incompatible with the CLI and Web GUI. + +Instead use the file generated by the CLI `init` (shown above). + +```js +Greenlock.create({ + manager: "@greenlock/manager", + cloud: true, + token: "xxxx", + configFile: "./greenlock.json", + packageRoot: __dirname +}); +``` + +## Set Subscriber and other global Defaults + +```bash +npx greenlock defaults --subscriber-email jon@example.com --agree-to-terms true +``` + +```js +greenlock.manager.defaults({ + subscriberEmail: "jon@example.com", + agreeToTerms: true +}); +``` + +# Site Management + +By "site" we mean a primary domain and, optionally, secondary domains, to be listed on an ssl certificate, +along with any configuration that is necessary for getting and renewing those certificates. + +## Add a sites - domains and SSL certificates + +```bash +npx greenlock add --subject example.com --altnames 'example.com,www.example.com' +``` + +```js +greenlock.sites.add({ + subject: "example.com", + altnames: ["example.com", "www.example.com"] +}); +``` + +## View site config + +```bash +npx greenlock config --subject example.com +``` + +```js +greenlock.sites.get({ + servername: "www.example.com", + wildname: "*.example.com" +}); +``` + +## Update site config + +```bash +npx greenlock update --subject example.com --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxx +``` + +```js +greenlock.sites.update({ + subject: "www.example.com", + challenges: { + "dns-01": { + module: "acme-dns-01-ovh", + token: "xxxx" + } + } +}); +``` + +## Remove a site + +To stop automatic renewal of SSL certificates for a particular site. +You to restart renewal you must use `add()`. + +```bash +npx greenlock remove --subject example.com +``` + +```js +greenlock.sites.remove({ + subject: "example.com" +}); +``` diff --git a/manager.js b/manager.js new file mode 100644 index 0000000..36f466d --- /dev/null +++ b/manager.js @@ -0,0 +1,87 @@ +"use strict"; + +var MFS = require("greenlock-manager-fs"); +// TODO @greenlock/manager-cloud + +var Manager = module.exports; +Manager.create = function(opts) { + var mfs = MFS.create(opts); + var manager = {}; + + // + // REQUIRED (basic issuance) + // + if (mfs.get) { + manager.get = async function({ servername, wildname }) { + // (optional) `wildcard` may or may not exist + // if *you* support wildcard domains, *you* should handle them + return mfs.get({ servername, wildname }); + }; + } else { + // (optional) + // because the current version doesn't have get() + manager.get = createGetFromFind(); + } + + // + // REQUIRED (basic issuance) + // + manager.set = async function(opts) { + return mfs.set(opts); + }; + + // + // Optional (Fully Automatic Renewal) + // + manager.find = async function(opts) { + // { subject, servernames, altnames, renewBefore } + return mfs.find(opts); + }; + + // + // Optional (Special Remove Functionality) + // The default behavior is to set `deletedAt` + // + //manager.remove = async function(opts) { + // return mfs.remove(opts); + //}; + + // + // Optional (special settings save) + // Implemented here because this module IS the fallback + // + manager.defaults = async function(opts) { + return mfs.defaults(opts); + }; + + // + // Optional (for common deps and/or async initialization) + // + manager.init = async function(deps) { + return mfs.init(deps); + }; + + return manager; + + // + // IGNORE + // Backwards compat for the first versions of greenlock-manager-fs + // + function createGetFromFind() { + return async function({ servername, wildname }) { + var servernames = [servername]; + if (wildname) { + servernames.push(wildname); + } + return mfs + .find({ + servernames: servernames, + // because the original manager used altnames here + altnames: servernames + }) + .then(function(sites) { + return sites[0] || null; + }); + }; + } +}; diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..c3bee70 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,43 @@ +{ + "name": "@greenlock/manager", + "version": "3.0.0", + "lockfileVersion": 1, + "requires": true, + "dependencies": { + "@root/mkdirp": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/@root/mkdirp/-/mkdirp-1.0.0.tgz", + "integrity": "sha512-hxGAYUx5029VggfG+U9naAhQkoMSXtOeXtbql97m3Hi6/sQSRL/4khKZPyOF6w11glyCOU38WCNLu9nUcSjOfA==" + }, + "@root/request": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@root/request/-/request-1.4.2.tgz", + "integrity": "sha512-J8FM4+SJuc7WRC+Jz17m+VT2lgI7HtatHhxN1F2ck5aIKUAxJEaR4u/gLBsgT60mVHevKCjKN0O8115UtJjwLw==", + "dev": true + }, + "greenlock-manager-fs": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/greenlock-manager-fs/-/greenlock-manager-fs-3.0.5.tgz", + "integrity": "sha512-r/q+tEFuDwklfzPfiGhcIrHuJxMrppC+EseESpu5f0DMokh+1iZVm9nGC/VE7/7GETdOYfEYhhQkmspsi8Gr/A==", + "requires": { + "@root/mkdirp": "^1.0.0", + "safe-replace": "^1.1.0" + } + }, + "greenlock-manager-test": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/greenlock-manager-test/-/greenlock-manager-test-3.1.1.tgz", + "integrity": "sha512-wZ+Oxn5qTEoN+VDd3Y+kBYZ8MlaLlhm40KwIwfyR90bj08IZpfzE7zGY8SwBEbIx0wNSo6ztDku4Y0gVgxxwCA==", + "dev": true, + "requires": { + "@root/request": "^1.4.1", + "greenlock-manager-fs": "^3.0.0" + } + }, + "safe-replace": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/safe-replace/-/safe-replace-1.1.0.tgz", + "integrity": "sha512-9/V2E0CDsKs9DWOOwJH7jYpSl9S3N05uyevNjvsnDauBqRowBPOyot1fIvV5N2IuZAbYyvrTXrYFVG0RZInfFw==" + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..33bb131 --- /dev/null +++ b/package.json @@ -0,0 +1,30 @@ +{ + "name": "@greenlock/manager", + "version": "3.0.0", + "description": "FileSytem-based Manager with optional encrypted Cloud backup for Greenlock SSL", + "main": "manager.js", + "scripts": { + "test": "node tests" + }, + "repository": { + "type": "git", + "url": "https://git.rootprojects.org/root/greenlock-manager.js.git" + }, + "keywords": [ + "greenlock", + "manager", + "cloud", + "fs", + "ssl", + "file", + "system" + ], + "author": "AJ ONeal (https://coolaj86.com/)", + "license": "MPL-2.0", + "dependencies": { + "greenlock-manager-fs": "^3.0.5" + }, + "devDependencies": { + "greenlock-manager-test": "^3.1.1" + } +} diff --git a/tests/index.js b/tests/index.js new file mode 100644 index 0000000..048b627 --- /dev/null +++ b/tests/index.js @@ -0,0 +1,25 @@ +"use strict"; + +var Tester = require("greenlock-manager-test"); + +var Manager = require("./manager.js"); +var config = { + configFile: "greenlock-manager-test.delete-me.json" +}; + +Tester.test(Manager, config) + .then(function(features) { + console.info("PASS"); + console.info(); + console.info("Optional Feature Support:"); + features.forEach(function(feature) { + console.info(feature.supported ? "✓ (YES)" : "✘ (NO) ", feature.description); + }); + console.info(); + }) + .catch(function(err) { + console.error("Oops, you broke it. Here are the details:"); + console.error(err.stack); + console.error(); + console.error("That's all I know."); + });