Skip to content

Latest commit

 

History

History
149 lines (91 loc) · 6.24 KB

developer-documentation.md

File metadata and controls

149 lines (91 loc) · 6.24 KB
Raw

Developer Documentation

This documentation includes the implementation details of Auto Encrypt Localhost and is intended to aid you if you’re trying to improve, debug, or get a deeper understanding of Auto Encrypt.

If you just want to use Auto Encrypt Localhost, please see the public API, as documented in the README.

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.

Requirements

Auto Encrypt Localhost is supported on:

  • Node: LTS (currently 14.16.0).
  • ECMAScript: ES2019

Overview of relationships

Dependency relationship diagram for Auto Correct

Not shown (for clarity): third-party Node modules, the util namespace with helper modules – for logging, error handling, and an async forEach implementation – and the typedefs namespace with JSDoc type definitions.

Generated using dependency cruiser.

To run dependency cruiser, you will need to install Graphviz.

How it works in more detail

Auto Encrypt Localhost is a Node.js wrapper for mkcert that, at the npm post-install stage:

  • Downloads and uses correct mkcert release binary for you machine on Linux, macOS, and Windows.

And, on first run (or if the root certificate authority or your TLS certificates are missing):

  • Automatically installs the certutil (nss) dependency on Linux on systems with apt, pacman, yum (untested) and and on macOS if you have Homebrew or MacPorts (untested).

  • Creates a root Certificate Authority.

  • Creates locally-trusted TLS certificates for localhost, 127.0.0.1, and ::1.

You can use these certificates for local development without triggering self-signed certificate errors.

At runtime, you can use the library to create your HTTPS servers instead of using the built-in Node.js https module.

For more details on how Auto Encrypt Localhost works behind the scenes, please see the mkcert README.

Tests

npm -s test

To see debug output, run npm -s run test-debug instead.

Note that npm cannot prompt for sudo passwords due to a bug so you will be prompted for your password prior to the running of the tests in order to unlock sudo while the tests are running.

On Windows, run the following command instead:

npm -s run test-on-windows

Coverage

npm -s run coverage

To see debug output, run npm -s run coverage-debug instead.

On Windows, run the following command instead:

npm -s run coverage-on-windows

Documentation

To regenerate the dependency diagram and this documentation:

npm -s run generate-developer-documentation

@small-tech/auto-encrypt-localhost

Automatically provisions and installs locally-trusted TLS certificates for Node.js® https servers (including Express.js, etc.) using mkcert.

License: AGPLv3 or later.
Copyright: © 2020-2021 Aral Balkan, Small Technology Foundation.

module.exports ⏏

Auto Encrypt Localhost is a static class. Please do not instantiate.

Use: AutoEncryptLocalhost.https.createServer(…)

Kind: Exported class

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 importing the module and prefixing their https.createServer(…) line with AutoEncryptLocalhost:

Kind: static property of module.exports
Example

import AutoEncryptLocalhost from '@small-tech/auto-encrypt-localhost'
const server = AutoEncryptLocalhost.https.createServer()

module.exports.createServer([options]) ⇒ https.Server

Automatically provisions trusted development-time (localhost) certificates in Node.js via mkcert.

Kind: static method of module.exports
Returns: https.Server - The server instance returned by Node’s https.createServer() method.

Param Type Default Description
[options] Object Optional HTTPS options object with optional additional Auto Encrypt-specific configuration settings.
[options.settingsPath] String ~/.small-tech.org/auto-encrypt-localhost/ Custom path to save the certificate and private key to.

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.

Copyright

© 2019-2021 Aral Balkan, Small Technology Foundation.

License

AGPL version 3.0 or later.