Commit 322b147e authored by Aral Balkan's avatar Aral Balkan
Browse files

Update documentation

parent 1e781dc3
......@@ -4,7 +4,7 @@ Automatically provisions and installs locally-trusted TLS certificates for Node.
## How it works
Before creating your HTTPS server, uses mkcert to create a local certificate authority, adds it to the various trust stores, and uses it to create locally-trusted TLS certificates that are installed in your server.
Before creating your HTTPS server, Auto Encrypt Localhost uses mkcert to create a local certificate authority, adds it to the various trust stores, and uses it to create locally-trusted TLS certificates that are installed in your server.
You can reach your server via the local loopback addresses (localhost, 127.0.0.1) on the device itself and also from other devices on the local area network by using your device’s external IPv4 address.
......@@ -14,6 +14,10 @@ You can reach your server via the local loopback addresses (localhost, 127.0.0.1
npm i @small-tech/auto-encrypt-localhost
```
__Version 7.x+:__ As a post-install step, Auto Encrypt Localhost will install the correct mkcert binary for your machine in its _mkcert-bin_ folder and mark is as executable.
__Version 6.x and below:__ All mkcert binaries for all supported platforms are included in the package. This is to support use of Auto Encrypt Localhost in single binary deployments (e.g., using a binary compiler like [Nexe](https://github.com/nexe/nexe)). The 6.x branch will be maintained with new versions of mkcert for as long as maintain [Site.js](https://sitejs.org), which needs this feature. Also note that versions 6.x and below use CommonJS whereas version 7.x and above use ECMAScript Modules (ESM; es6 modules).
### On Linux
Make sure you disable privileged ports:
......@@ -31,7 +35,7 @@ sudo sysctl -w net.ipv4.ip_unprivileged_port_start=0
1. Import the module:
```js
const AutoEncryptLocalhost = require('@small-tech/auto-encrypt-localhost')
import AutoEncryptLocalhost from '@small-tech/auto-encrypt-localhost'
```
2. Prefix your server creation code with a reference to the Auto Encrypt Localhost class:
......@@ -48,7 +52,7 @@ sudo sysctl -w net.ipv4.ip_unprivileged_port_start=0
```js
// Create an https server using locally-trusted certificates.
const AutoEncryptLocalhost = require('@small-tech/auto-encrypt-localhost')
import AutoEncryptLocalhost from '@small-tech/auto-encrypt-localhost'
const server = AutoEncryptLocalhost.https.createServer((request, response) => {
response.end('Hello, world!')
......@@ -59,7 +63,7 @@ server.listen(() => {
})
```
You can now reach your server via https://localhost, https://127.0.0.1, and via its external IPv4 address on your local area network. To find out what that is, you can run the following in the Node interpreter:
You can now reach your server via https://localhost, https://127.0.0.1, and via its external IPv4 address(es) on your local area network. To find the list of IP addresses that your local server is reachable from, you can run the following code in the Node interpreter:
```js
Object.entries(os.networkInterfaces())
......@@ -91,15 +95,16 @@ The browser will download the local root certificate authority’s public key an
You can also transfer your key manually. You can find the key at `~/.small-tech/auto-encrypt-localhost/rootCA.pem` after you’ve created at least one server. For more details on transferring your key to other devices, please refer to [the relevant section in the mkcert documentation](https://github.com/FiloSottile/mkcert#mobile-devices).
## Configuration
You can specify a custom settings path for your local certificate authority and certificate data to be stored in by adding the Auto Encrypt Localhost-specific `settingsPath` option to the options object you pass to the Node `https` server. If not specified, the default settings path (_~/.small-tech.org/auto-encrypt-localhost/_) is used.
__Version 7.x+:__ Note that the mkcert binary will no longer be copied to your settings path. It is run from the _mkcert-bin_ folder in the installed npm package. If you need the binary copied to your settings path (e.g., so that it can be run from a Nexe binary), please use version 6.x.
### Example
```js
const AutoEncrypt = require('@small-tech/auto-encrypt-localhost')
import AutoEncryptLocalhost from '@small-tech/auto-encrypt-localhost'
const options = {
// Regular HTTPS server and TLS server options, if any, go here.
......@@ -151,20 +156,22 @@ Your certificates will be created in the _~/.small-tech.org/auto-encrypt-localho
Locally-trusted certificates do not work under Firefox. Please use Edge or Chrome on this platform. This is [a mkcert limitation](https://github.com/FiloSottile/mkcert#supported-root-stores).
__Version 7.x:__ currently not tested under Windows. May not be able to set the executable bit on the binary download if that’s necessary. TODO: remove this notice once it’s been tested.
## Related projects
From lower-level to higher-level:
### Auto Encrypt
- Source: https://source.small-tech.org/site.js/lib/auto-encrypt
- Source: https://github.com/small-tech/auto-encrypt
- Package: [@small-tech/auto-encrypt](https://www.npmjs.com/package/@small-tech/auto-encrypt)
Adds automatic provisioning and renewal of [Let’s Encrypt](https://letsencrypt.org) TLS certificates with [OCSP Stapling](https://letsencrypt.org/docs/integration-guide/#implement-ocsp-stapling) to [Node.js](https://nodejs.org) [https](https://nodejs.org/dist/latest-v12.x/docs/api/https.html) servers (including [Express.js](https://expressjs.com/), etc.)
### HTTPS
- Source: https://source.small-tech.org/site.js/lib/https
- Source: https://github.com/small-tech/https
- Package: [@small-tech/https](https://www.npmjs.com/package/@small-tech/https)
A drop-in replacement for the [standard Node.js HTTPS module](https://nodejs.org/dist/latest-v12.x/docs/api/https.html) with automatic development-time (localhost) certificates via Auto Encrypt Localhost and automatic production certificates via Auto Encrypt.
......@@ -172,9 +179,15 @@ A drop-in replacement for the [standard Node.js HTTPS module](https://nodejs.org
### Site.js
- Web site: https://sitejs.org
- Source: https://source.small-tech.org/site.js/app
- Source: https://github.com/small-tech/site.js
A tool for developing, testing, and deploying a secure static or dynamic personal web site or app with zero configuration.
### Place (work-in-progress)
Small Web Protocol Reference Server.
A complete [small technology](https://small-tech.org/about/#small-technology) tool for developing, testing, and deploying a secure static or dynamic personal web site or app with zero configuration.
- Source: https://github.com/small-tech/place
## A note on Linux and the security farce that is “privileged ports”
......@@ -207,7 +220,7 @@ We exist in part thanks to patronage by people like you. If you share [our visio
## Copyright
Copyright © [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org).
Copyright © 2019-2021 [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org).
## License
......
This diff is collapsed.
......@@ -14,7 +14,7 @@ We exist in part thanks to patronage by people like you. If you share [our visio
Auto Encrypt Localhost is supported on:
- __Node:__ LTS (currently 12.16.1).
- __Node:__ LTS (currently 14.16.0).
- __ECMAScript:__ [ES2019](https://node.green/#ES2019)
## Overview of relationships
......@@ -25,11 +25,13 @@ __Not shown (for clarity):__ third-party Node modules, the `util` namespace with
Generated using [dependency cruiser](https://github.com/sverweij/dependency-cruiser).
To run dependecy cruiser, you will need to [install Graphviz](https://graphviz.org/download/).
## How it works in more detail
Auto Encrypt Localhost is a Node.js wrapper for [mkcert](https://github.com/FiloSottile/mkcert/) that:
* Uses the 64-bit release binaries to support Linux, macOS, and Windows.
* Downloads and uses correct mkcert release binary for you machine on Linux, macOS, and Windows.
* Automatically installs the _certutil_ (nss) dependency on Linux on systems with apt, pacman, yum (untested) and and on macOS if you have [Homebrew](https://brew.sh) or [MacPorts](https://www.macports.org/) (untested).
......@@ -44,25 +46,25 @@ For more details on how Auto Encrypt Localhost works behind the scenes, please [
## Tests
```sh
npm test
npm -s test
```
To see debug output, run `npm run test-debug` instead.
To see debug output, run `npm -s run test-debug` instead.
## Coverage
```sh
npm run coverage
npm -s run coverage
```
To see debug output, run `npm run coverage-debug` instead.
To see debug output, run `npm -s run coverage-debug` instead.
## Documentation
To regenerate the dependency diagram and this documentation:
```sh
npm run generate-developer-documentation
npm -s run generate-developer-documentation
```
{{>main}}
......@@ -75,9 +77,7 @@ We exist in part thanks to patronage by people like you. If you share [our visio
## Copyright
© 2020 [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org).
Let’s Encrypt is a trademark of the Internet Security Research Group (ISRG). All rights reserved. Node.js is a trademark of Joyent, Inc. and is used with its permission. We are not endorsed by or affiliated with Joyent or ISRG.
© 2019-2021 [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org).
## License
......
......@@ -14,7 +14,7 @@ We exist in part thanks to patronage by people like you. If you share [our visio
Auto Encrypt Localhost is supported on:
- __Node:__ LTS (currently 12.16.1).
- __Node:__ LTS (currently 14.16.0).
- __ECMAScript:__ [ES2019](https://node.green/#ES2019)
## Overview of relationships
......@@ -25,11 +25,13 @@ __Not shown (for clarity):__ third-party Node modules, the `util` namespace with
Generated using [dependency cruiser](https://github.com/sverweij/dependency-cruiser).
To run dependecy cruiser, you will need to [install Graphviz](https://graphviz.org/download/).
## How it works in more detail
Auto Encrypt Localhost is a Node.js wrapper for [mkcert](https://github.com/FiloSottile/mkcert/) that:
* Uses the 64-bit release binaries to support Linux, macOS, and Windows.
* Downloads and uses correct mkcert release binary for you machine on Linux, macOS, and Windows.
* Automatically installs the _certutil_ (nss) dependency on Linux on systems with apt, pacman, yum (untested) and and on macOS if you have [Homebrew](https://brew.sh) or [MacPorts](https://www.macports.org/) (untested).
......@@ -44,25 +46,25 @@ For more details on how Auto Encrypt Localhost works behind the scenes, please [
## Tests
```sh
npm test
npm -s test
```
To see debug output, run `npm run test-debug` instead.
To see debug output, run `npm -s run test-debug` instead.
## Coverage
```sh
npm run coverage
npm -s run coverage
```
To see debug output, run `npm run coverage-debug` instead.
To see debug output, run `npm -s run coverage-debug` instead.
## Documentation
To regenerate the dependency diagram and this documentation:
```sh
npm run generate-developer-documentation
npm -s run generate-developer-documentation
```
<a name="module_@small-tech/auto-encrypt-localhost"></a>
......@@ -72,40 +74,40 @@ Automatically provisions and installs locally-trusted TLS certificates for Node.
(including Express.js, etc.) using mkcert.
**License**: AGPLv3 or later.
**Copyright**: © 2020 Aral Balkan, Small Technology Foundation.
**Copyright**: © 2020-2021 Aral Balkan, Small Technology Foundation.
* [@small-tech/auto-encrypt-localhost](#module_@small-tech/auto-encrypt-localhost)
* [AutoEncryptLocalhost](#exp_module_@small-tech/auto-encrypt-localhost--AutoEncryptLocalhost)
* [.https](#module_@small-tech/auto-encrypt-localhost--AutoEncryptLocalhost.https)
* [.createServer([options])](#module_@small-tech/auto-encrypt-localhost--AutoEncryptLocalhost.createServer)<code>https.Server</code>
* [module.exports](#exp_module_@small-tech/auto-encrypt-localhost--module.exports)
* [.https](#module_@small-tech/auto-encrypt-localhost--module.exports.https)
* [.createServer([options])](#module_@small-tech/auto-encrypt-localhost--module.exports.createServer)<code>https.Server</code>
<a name="exp_module_@small-tech/auto-encrypt-localhost--AutoEncryptLocalhost"></a>
<a name="exp_module_@small-tech/auto-encrypt-localhost--module.exports"></a>
### AutoEncryptLocalhost
### module.exports
Auto Encrypt Localhost is a static class. Please do not instantiate.
Use: AutoEncryptLocalhost.https.createServer(…)
**Kind**: Exported class
<a name="module_@small-tech/auto-encrypt-localhost--AutoEncryptLocalhost.https"></a>
<a name="module_@small-tech/auto-encrypt-localhost--module.exports.https"></a>
#### AutoEncryptLocalhost.https
#### module.exports.https
By aliasing the https property to the AutoEncryptLocalhost static class itself, we enable
people to add AutoEncryptLocalhost to their existing apps by requiring the module
and prefixing their https.createServer(…) line with AutoEncryptLocalhost:
**Kind**: static property of [<code>AutoEncryptLocalhost</code>](#exp_module_@small-tech/auto-encrypt-localhost--AutoEncryptLocalhost)
**Kind**: static property of [<code>module.exports</code>](#exp_module_@small-tech/auto-encrypt-localhost--module.exports)
**Example**
```js
const AutoEncryptLocalhost = require('@small-tech/auto-encrypt-localhost')
import AutoEncryptLocalhost from '@small-tech/auto-encrypt-localhost'
const server = AutoEncryptLocalhost.https.createServer()
```
<a name="module_@small-tech/auto-encrypt-localhost--AutoEncryptLocalhost.createServer"></a>
<a name="module_@small-tech/auto-encrypt-localhost--module.exports.createServer"></a>
#### AutoEncryptLocalhost.createServer([options]) ⇒ <code>https.Server</code>
#### module.exports.createServer([options]) ⇒ <code>https.Server</code>
Automatically provisions trusted development-time (localhost) certificates in Node.js via mkcert.
**Kind**: static method of [<code>AutoEncryptLocalhost</code>](#exp_module_@small-tech/auto-encrypt-localhost--AutoEncryptLocalhost)
**Kind**: static method of [<code>module.exports</code>](#exp_module_@small-tech/auto-encrypt-localhost--module.exports)
**Returns**: <code>https.Server</code> - The server instance returned by Node’s https.createServer() method.
| Param | Type | Default | Description |
......@@ -122,9 +124,7 @@ We exist in part thanks to patronage by people like you. If you share [our visio
## Copyright
&copy; 2020 [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org).
Let’s Encrypt is a trademark of the Internet Security Research Group (ISRG). All rights reserved. Node.js is a trademark of Joyent, Inc. and is used with its permission. We are not endorsed by or affiliated with Joyent or ISRG.
&copy; 2019-2021 [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org).
## License
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment