root
/
greenlock.js
mirror of https://github.com/therootcompany/greenlock.js.git
2
0
Fork 0
Code Issues 27 Releases Wiki Activity

2.8.4: partial make Prettier, add campaign banner

This commit is contained in:
AJ ONeal 2019-08-24 12:54:23 -04:00
parent ac237148ba
commit 6650defebb
5 changed files with 426 additions and 327 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.prettierrc Normal file
View File

@ -0,0 +1,8 @@
{
"bracketSpacing": true,
"printWidth": 80,
"singleQuote": true,
"tabWidth": 4,
"trailingComma": "none",
"useTabs": true
}

228
README.md
View File

@ -1,6 +1,6 @@
!["Greenlock Logo"](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock lock logo and work mark") !["Greenlock Logo"](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png 'Greenlock lock logo and work mark')
!["Greenlock Function"](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/from-not-secure-to-secure-url-bar.png "from url bar showing not secure to url bar showing secure") !["Greenlock Function"](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/from-not-secure-to-secure-url-bar.png 'from url bar showing not secure to url bar showing secure')
# [Greenlock](https://git.rootprojects.org/root/greenlock.js)™ for node.js | a [Root](https://rootprojects.org) project # [Greenlock](https://git.rootprojects.org/root/greenlock.js)™ for node.js | a [Root](https://rootprojects.org) project
@ -12,7 +12,6 @@ Greenlock provides Free SSL, Free Wildcard SSL, and Fully Automated HTTPS <br>
!["Weekly Downloads"](https://img.shields.io/npm/dw/greenlock.svg "Weekly Download Count can't be shown") !["Weekly Downloads"](https://img.shields.io/npm/dw/greenlock.svg "Weekly Download Count can't be shown")
!["Stackoverflow Questions"](https://img.shields.io/stackexchange/stackoverflow/t/greenlock.svg "S.O. Question count can't be shown") !["Stackoverflow Questions"](https://img.shields.io/stackexchange/stackoverflow/t/greenlock.svg "S.O. Question count can't be shown")
Greenlock works Greenlock works
in the [Commandline](https://git.rootprojects.org/root/greenlock-cli.js) (cli), in the [Commandline](https://git.rootprojects.org/root/greenlock-cli.js) (cli),
as a [Web Server](https://git.rootprojects.org/root/greenlock-express.js), as a [Web Server](https://git.rootprojects.org/root/greenlock-express.js),
@ -57,14 +56,14 @@ Documentation for using Greenlock with
# Table of Contents # Table of Contents
* Install - Install
* **QuickStart** - **QuickStart**
* Simple Examples - Simple Examples
* Example with ALL OPTIONS - Example with ALL OPTIONS
* API - API
* Developer API - Developer API
* Change History - Change History
* License - License
# Install # Install
@ -72,10 +71,9 @@ Documentation for using Greenlock with
npm install --save greenlock@2.x npm install --save greenlock@2.x
``` ```
**Optional** for *more efficient* RSA key generation you must use node v10.12+ **Optional** for _more efficient_ RSA key generation you must use node v10.12+
<small>(important for those on ARM devices like Raspberry Pi)</small> <small>(important for those on ARM devices like Raspberry Pi)</small>
### Production vs Staging ### Production vs Staging
If at first you don't succeed, stop and switch to staging. If at first you don't succeed, stop and switch to staging.
@ -98,19 +96,18 @@ Watch the QuickStart demonstration: [https://youtu.be/e8vaR4CEZ5s](https://youtu
<a href="https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk"><img src="https://i.imgur.com/Y8ix6Ts.png" title="QuickStart Video" alt="YouTube Video Preview" /></a> <a href="https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk"><img src="https://i.imgur.com/Y8ix6Ts.png" title="QuickStart Video" alt="YouTube Video Preview" /></a>
* [0:00](https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk#t=0) - Intro - [0:00](https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk#t=0) - Intro
* [2:22](https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk#t=142) - Demonstrating QuickStart Example - [2:22](https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk#t=142) - Demonstrating QuickStart Example
* [6:37](https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk?t=397) - Troubleshooting / Gotchas - [6:37](https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk?t=397) - Troubleshooting / Gotchas
#### Production Configuration (Part 2) #### Production Configuration (Part 2)
* [1:00](https://www.youtube.com/watch?v=bTEn93gxY50&index=2&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk&t=60) - Bringing Greenlock into an Existing Express Project - [1:00](https://www.youtube.com/watch?v=bTEn93gxY50&index=2&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk&t=60) - Bringing Greenlock into an Existing Express Project
* [2:26](https://www.youtube.com/watch?v=bTEn93gxY50&index=2&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk&t=146) - The `approveDomains` callback - [2:26](https://www.youtube.com/watch?v=bTEn93gxY50&index=2&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk&t=146) - The `approveDomains` callback
#### Security Concerns (Part 3) #### Security Concerns (Part 3)
* [0:00](https://www.youtube.com/watch?v=aZgVqPzoZTY&index=3&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk) - Potential Attacks, and Mitigation - [0:00](https://www.youtube.com/watch?v=aZgVqPzoZTY&index=3&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk) - Potential Attacks, and Mitigation
# Easy as 1, 2, 3... 4 # Easy as 1, 2, 3... 4
@ -119,13 +116,12 @@ Greenlock is built to incredibly easy to use, without sacrificing customization
The following examples range from just a few lines of code for getting started, The following examples range from just a few lines of code for getting started,
to more robust examples that you might start with for an enterprise-grade use of the ACME api. to more robust examples that you might start with for an enterprise-grade use of the ACME api.
* Automatic HTTPS (for single sites) - Automatic HTTPS (for single sites)
* Fully Automatic HTTPS (for multi-domain vhosts) - Fully Automatic HTTPS (for multi-domain vhosts)
* Manual HTTPS (for API integration) - Manual HTTPS (for API integration)
## Automatic HTTPS ## Automatic HTTPS
**Note**: For (fully) automatic HTTPS you may prefer **Note**: For (fully) automatic HTTPS you may prefer
the [Express.js module](https://git.rootprojects.org/root/greenlock-express.js) the [Express.js module](https://git.rootprojects.org/root/greenlock-express.js)
@ -142,12 +138,12 @@ Great when
//////////////////// ////////////////////
var greenlock = require('greenlock').create({ var greenlock = require('greenlock').create({
email: 'user@example.com' // IMPORTANT: Change email and domains email: 'user@example.com', // IMPORTANT: Change email and domains
, agreeTos: true // Accept Let's Encrypt v2 Agreement agreeTos: true, // Accept Let's Encrypt v2 Agreement
, configDir: '~/.config/acme' // A writable folder (a non-fs plugin) configDir: '~/.config/acme', // A writable folder (a non-fs plugin)
, communityMember: true // Get (rare) non-mandatory updates about cool greenlock-related stuff (default false) communityMember: true, // Get (rare) non-mandatory updates about cool greenlock-related stuff (default false)
, securityUpdates: true // Important and mandatory notices related to security or breaking API changes (default true) securityUpdates: true // Important and mandatory notices related to security or breaking API changes (default true)
}); });
``` ```
@ -157,11 +153,15 @@ var greenlock = require('greenlock').create({
//////////////////// ////////////////////
var redir = require('redirect-https')(); var redir = require('redirect-https')();
require('http').createServer(greenlock.middleware(redir)).listen(80); require('http')
.createServer(greenlock.middleware(redir))
.listen(80);
require('spdy').createServer(greenlock.tlsOptions, function (req, res) { require('spdy')
.createServer(greenlock.tlsOptions, function(req, res) {
res.end('Hello, Secure World!'); res.end('Hello, Secure World!');
}).listen(443); })
.listen(443);
``` ```
## Fully Automatic HTTPS ## Fully Automatic HTTPS
@ -181,33 +181,34 @@ Great when
//////////////////// ////////////////////
var path = require('path'); var path = require('path');
var os = require('os') var os = require('os');
var Greenlock = require('greenlock'); var Greenlock = require('greenlock');
var greenlock = Greenlock.create({ var greenlock = Greenlock.create({
version: 'draft-12' version: 'draft-12',
, server: 'https://acme-v02.api.letsencrypt.org/directory' server: 'https://acme-v02.api.letsencrypt.org/directory',
// Use the approveDomains callback to set per-domain config // Use the approveDomains callback to set per-domain config
// (default: approve any domain that passes self-test of built-in challenges) // (default: approve any domain that passes self-test of built-in challenges)
, approveDomains: approveDomains approveDomains: approveDomains,
// the default servername to use when the client doesn't specify // the default servername to use when the client doesn't specify
, servername: 'example.com' servername: 'example.com',
// If you wish to replace the default account and domain key storage plugin // If you wish to replace the default account and domain key storage plugin
, store: require('le-store-fs').create({ store: require('le-store-fs').create({
configDir: path.join(os.homedir(), 'acme/etc') configDir: path.join(os.homedir(), 'acme/etc'),
, webrootPath: '/tmp/acme-challenges' webrootPath: '/tmp/acme-challenges'
}) })
}); });
///////////////////// /////////////////////
// APPROVE DOMAINS // // APPROVE DOMAINS //
///////////////////// /////////////////////
var http01 = require('le-challenge-fs').create({ webrootPath: '/tmp/acme-challenges' }); var http01 = require('le-challenge-fs').create({
webrootPath: '/tmp/acme-challenges'
});
function approveDomains(opts, certs, cb) { function approveDomains(opts, certs, cb) {
// This is where you check your database and associated // This is where you check your database and associated
// email addresses with domains and agreements and such // email addresses with domains and agreements and such
@ -232,17 +233,20 @@ function approveDomains(opts, certs, cb) {
cb(null, { options: opts, certs: certs }); cb(null, { options: opts, certs: certs });
} }
//////////////////// ////////////////////
// CREATE SERVERS // // CREATE SERVERS //
//////////////////// ////////////////////
var redir = require('redirect-https')(); var redir = require('redirect-https')();
require('http').createServer(greenlock.middleware(redir)).listen(80); require('http')
.createServer(greenlock.middleware(redir))
.listen(80);
require('https').createServer(greenlock.tlsOptions, function (req, res) { require('https')
.createServer(greenlock.tlsOptions, function(req, res) {
res.end('Hello, Secure World!'); res.end('Hello, Secure World!');
}).listen(443); })
.listen(443);
``` ```
## Manual HTTPS ## Manual HTTPS
@ -293,19 +297,24 @@ greenlock.register(opts).then(function (certs) {
The domain key and ssl certificates you get back can be used in a webserver like this: The domain key and ssl certificates you get back can be used in a webserver like this:
```js ```js
var tlsOptions = { key: certs.privkey, cert: certs.cert + '\r\n' + certs.chain }; var tlsOptions = {
require('https').createServer(tlsOptions, function (req, res) { key: certs.privkey,
cert: certs.cert + '\r\n' + certs.chain
};
require('https')
.createServer(tlsOptions, function(req, res) {
res.end('Hello, Secure World!'); res.end('Hello, Secure World!');
}).listen(443); })
.listen(443);
``` ```
# Example with ALL OPTIONS # Example with ALL OPTIONS
The configuration consists of 3 components: The configuration consists of 3 components:
* Storage Backend (search npm for projects starting with 'le-store-') - Storage Backend (search npm for projects starting with 'le-store-')
* ACME Challenge Handlers (search npm for projects starting with 'le-challenge-') - ACME Challenge Handlers (search npm for projects starting with 'le-challenge-')
* Letsencryt Config (this is all you) - Letsencryt Config (this is all you)
```javascript ```javascript
'use strict'; 'use strict';
@ -419,8 +428,7 @@ Here's what `results` looks like:
} }
``` ```
API ## API
---
The full end-user API is exposed in the example above and includes all relevant options. The full end-user API is exposed in the example above and includes all relevant options.
@ -433,7 +441,7 @@ greenlock.check(opts)
We do expose a few helper functions: We do expose a few helper functions:
* Greenlock.validDomain(hostname) // returns '' or the hostname string if it's a valid ascii or punycode domain name - Greenlock.validDomain(hostname) // returns '' or the hostname string if it's a valid ascii or punycode domain name
TODO fetch domain tld list TODO fetch domain tld list
@ -441,16 +449,16 @@ TODO fetch domain tld list
The following variables will be tempalted in any strings passed to the options object: The following variables will be tempalted in any strings passed to the options object:
* `~/` replaced with `os.homedir()` i.e. `/Users/aj` - `~/` replaced with `os.homedir()` i.e. `/Users/aj`
* `:hostname` replaced with the first domain in the list i.e. `example.com` - `:hostname` replaced with the first domain in the list i.e. `example.com`
### Dangerous Options ### Dangerous Options
By default SNI is made to lowercase and is automatically rejected if it contains invalid characters for a domain. By default SNI is made to lowercase and is automatically rejected if it contains invalid characters for a domain.
This behavior can be modified: This behavior can be modified:
* `__dns_allow_dangerous_names` allow SNI names like "Robert'); DROP TABLE Students;" - `__dns_allow_dangerous_names` allow SNI names like "Robert'); DROP TABLE Students;"
* `__dns_preserve_case` passes SNI names such as "ExAMpLE.coM" without converting to lower case - `__dns_preserve_case` passes SNI names such as "ExAMpLE.coM" without converting to lower case
## Developer API ## Developer API
@ -470,16 +478,16 @@ should be kept in sync.
See [greenlock-store-test](https://git.rootprojects.org/root/greenlock-store-test.js) See [greenlock-store-test](https://git.rootprojects.org/root/greenlock-store-test.js)
and [greenlock-store-fs](https://git.rootprojects.org/root/greenlock-store-fs.js) and [greenlock-store-fs](https://git.rootprojects.org/root/greenlock-store-fs.js)
* accounts. - accounts.
* checkKeypair(opts) - checkKeypair(opts)
* check(opts) - check(opts)
* setKeypair(opts) - setKeypair(opts)
* set(opts) - set(opts)
* certificates. - certificates.
* checkKeypair(opts) - checkKeypair(opts)
* check(opts) - check(opts)
* setKeypair(opts) - setKeypair(opts)
* set(opts) - set(opts)
### challenge implementation ### challenge implementation
@ -487,50 +495,52 @@ See [greenlock-challenge-test](https://git.rootprojects.org/root/greenlock-chall
[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),
and [acme-dns-01-cli](https://git.rootprojects.org/root/acme-dns-01-cli.js) and [acme-dns-01-cli](https://git.rootprojects.org/root/acme-dns-01-cli.js)
* `.set(opts);` - `.set(opts);`
* `.get(opts);` - `.get(opts);`
* `.remove(opts);` - `.remove(opts);`
# Change History # Change History
* v2.7
* API: transitional for v3 API (Promies, async/await) - v2.7
* Security: Zero external dependencies - API: transitional for v3 API (Promies, async/await)
* Plugins: `greenlock-store-fs` replaces `le-store-certbot` as the default storage plugin - Security: Zero external dependencies
* Features: Full wildcard support - Plugins: `greenlock-store-fs` replaces `le-store-certbot` as the default storage plugin
* Licensing: Commercial licensing and support plans now available - Features: Full wildcard support
* v2.6 - Licensing: Commercial licensing and support plans now available
* better defaults, fewer explicit options - v2.6
* better pre-flight self-tests, explicit domains not required - better defaults, fewer explicit options
* v2.5 - better pre-flight self-tests, explicit domains not required
* bugfix JWK (update rsa-compat) - v2.5
* eliminate all external non-optional dependencies - bugfix JWK (update rsa-compat)
* v2.4 - eliminate all external non-optional dependencies
* v2.4.3 - add security updates (default true) independent of community updates (default false) - v2.4
* v2.2 - Let's Encrypt v2 Support - v2.4.3 - add security updates (default true) independent of community updates (default false)
* v2.2.11 - documentation updates - v2.2 - Let's Encrypt v2 Support
* v2.2.10 - don't let SNICallback swallow approveDomains errors 6286883fc2a6ebfff711a540a2e4d92f3ac2907c - v2.2.11 - documentation updates
* v2.2.8 - communityMember option support - v2.2.10 - don't let SNICallback swallow approveDomains errors 6286883fc2a6ebfff711a540a2e4d92f3ac2907c
* v2.2.7 - bugfix for wildcard support - v2.2.8 - communityMember option support
* v2.2.5 - node v6.x compat - v2.2.7 - bugfix for wildcard support
* v2.2.4 - don't promisify all of `dns` - v2.2.5 - node v6.x compat
* v2.2.3 - `renewWithin` default to 14 days - v2.2.4 - don't promisify all of `dns`
* v2.2.2 - replace git dependency with npm - v2.2.3 - `renewWithin` default to 14 days
* v2.2.1 - April 2018 **Let's Encrypt v2** support - v2.2.2 - replace git dependency with npm
* v2.1.17 - Nov 5th 2017 migrate back to personal repo - v2.2.1 - April 2018 **Let's Encrypt v2** support
* v2.1.9 - Jan 18th 2017 renamed to greenlock - v2.1.17 - Nov 5th 2017 migrate back to personal repo
* v2.0.2 - Aug 9th 2016 update readme - v2.1.9 - Jan 18th 2017 renamed to greenlock
* v2.0.1 - Aug 9th 2016 - v2.0.2 - Aug 9th 2016 update readme
* major refactor - v2.0.1 - Aug 9th 2016
* simplified API - major refactor
* modular plugins - simplified API
* knock out bugs - modular plugins
* v1.5.0 now using letiny-core v2.0.0 and rsa-compat - knock out bugs
* v1.4.x I can't remember... but it's better! - v1.5.0 now using letiny-core v2.0.0 and rsa-compat
* v1.1.0 Added letiny-core, removed node-letsencrypt-python - v1.4.x I can't remember... but it's better!
* v1.0.2 Works with node-letsencrypt-python - v1.1.0 Added letiny-core, removed node-letsencrypt-python
* v1.0.0 Thar be dragons - v1.0.2 Works with node-letsencrypt-python
- v1.0.0 Thar be dragons
# Commercial Licensing # Commercial Licensing
As the number of businesses using Greenlock commercially has increased, we've become more aware of the need for quick-turnaround support and licenses that allow for local private modifications. Currently we offer LTS support and commercial licensing models for IoT, On-Prem, and Web Hosting. Please [contact us](mailto:support@rootprojects.org?subject=Greenlock%20Commercial%20Support) to learn more. As the number of businesses using Greenlock commercially has increased, we've become more aware of the need for quick-turnaround support and licenses that allow for local private modifications. Currently we offer LTS support and commercial licensing models for IoT, On-Prem, and Web Hosting. Please [contact us](mailto:support@rootprojects.org?subject=Greenlock%20Commercial%20Support) to learn more.
Our [trademark policy](https://therootcompany.com/legal/#trademark) is pretty much "attribute, but don't confuse". Your users should understand that your product _uses_ Greenlock and not be confused to think that it _is_ Greenlock. Our [trademark policy](https://therootcompany.com/legal/#trademark) is pretty much "attribute, but don't confuse". Your users should understand that your product _uses_ Greenlock and not be confused to think that it _is_ Greenlock.

2
package-lock.json generated
View File

@ -1,6 +1,6 @@
{ {
"name": "greenlock", "name": "greenlock",
"version": "2.8.2", "version": "2.8.4",
"lockfileVersion": 1, "lockfileVersion": 1,
"requires": true, "requires": true,
"dependencies": { "dependencies": {

6
package.json
View File

@ -1,13 +1,15 @@
{ {
"name": "greenlock", "name": "greenlock",
"version": "2.8.3", "version": "2.8.4",
"description": "Greenlock is Let's Encrypt (ACME) client for node.js", "description": "Greenlock is Let's Encrypt (ACME) client for node.js",
"homepage": "https://greenlock.domains/", "homepage": "https://greenlock.domains/",
"main": "index.js", "main": "index.js",
"files": [ "files": [
"lib" "lib",
"scripts"
], ],
"scripts": { "scripts": {
"postinstall": "node scripts/postinstall",
"test": "echo \"Error: no test specified\" && exit 1" "test": "echo \"Error: no test specified\" && exit 1"
}, },
"repository": { "repository": {

79
scripts/postinstall Executable file
View File

@ -0,0 +1,79 @@
#!/usr/bin/env node
'use strict';
// BG WH \u001b[47m
// BOLD \u001b[1m
// RED \u001b[31m
// GREEN \u001b[32m
// RESET \u001b[0m
var grabbers = [
[
'',
'================================================================================',
'',
' 🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥',
'🔥 🔥',
'🔥 Do you rely on Greenlock? 🔥',
'🔥 🔥',
' 🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥'
],
[
'',
'================================================================================',
'',
' 🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒',
'🍒 🍒',
'🍒 Do you rely on Greenlock? 🍒',
'🍒 🍒',
' 🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒🍒'
],
[
'',
'================================================================================',
'',
' 👇👇👇👇👇👇👇👇👇👇👇👇👇👇👇',
'👉 👈',
'👉 Do you rely on Greenlock? 👈',
'👉 👈',
' 👆👆👆👆👆👆👆👆👆👆👆👆👆👆👆 '
],
[
'',
'================================================================================',
'',
' 👀 👀 👀 👀 👀 👀 👀 👀 👀 👀 👀 ',
'👀 👀',
'👀 Do you rely on Greenlock? 👀',
'👀 👀',
' 👀 👀 👀 👀 👀 👀 👀 👀 👀 👀 👀 '
]
];
setTimeout(function() {
grabbers[Math.floor(Math.random() * grabbers.length)]
.concat([
'',
"Hey! Let's Encrypt will \u001b[31mSTOP WORKING\u001b[0m with Greenlock v2 at the end of October,",
"and \u001b[31mWITHOUT YOUR HELP\u001b[0m we won't get the next release out in time.",
'',
'If Greenlock has saved you time and money, and taken stress out of your life,',
'or you just love it, please reach out to return the favor today:',
'',
'\u001b[31mSAVE GREENLOCK:\u001b[0m',
'https://indiegogo.com/at/greenlock',
'',
'================================================================================',
''
])
.forEach(function(line) {
console.info(line);
});
}, 300);
setTimeout(function() {
// give time to read
}, 1500);