npm package: @getflywheel/localcert
Description: Generate and trust SSL certificates locally.
Author: Chris Wiegman
Latest version: 1.4.5

# localcert: SSL Certificate Generation and Trust

[![Build Status](https://travis-ci.com/getflywheel/localcert.svg?token=UCaL4raAFBRXqL64zpGQ&branch=master)](https://travis-ci.com/getflywheel/localcert)

Generates and trusts self-signed SSL certificates for local development. Based off the popular mkcert library for Go.

## Requirements

In order to install certificates in NSS browsers such as Firefox, the Mozilla certutil is required. You can install it with the following:

### Mac

```bash
brew install certutil
```

### Linux

```bash
sudo apt install libnss3-tools
    -or-
sudo yum install nss-tools
    -or-
sudo pacman -S nss
    -or-
sudo zypper install mozilla-nss-tools
```

### Windows

Installation to Firefox is not yet supported on Windows. Localcert will only install the certificate to the system store.

## Usage

Import and instantiate the the localcert module:

```javascript
var localcert = require('localcert')

var certgen = new localcert()
```

Generate the certificate:

```javascript
certgen.generate(['test.local'], 'US', 'FL', 'Sarasota', 'Acme Inc', '')

const certPaths = await certgen.saveCertificate();
```

Note, you can pass a "certPath" to the saveCertificate method. Without it, localcert will save certificates to ~/.localcert

You can also load an existing certificate with the following:

```javascript
const certPaths = certgen.loadCertificate(certPath,privateKeyPath);
```

Next, trust the certificate either in the system store, NSS browsers such as Firefox and Chrome, or both:

```javascript
certgen.trustCertificatePlatform();
certgen.trustCertificateNSS();
```

To remove the certificate trusts, locate the certificate to remove and run the following:

```javascript
certgen.removeCertificateTrustPlatform();
certgen.removeCertificateTrustNSS();
```

For the following functions, you can pass a second, optional, parameter of `execute` (bool) which defaults to true. If false, the command called will simply return the command parameters and not execute. Hopefully this will be handy in applications that may have wrapped sudo and/or other system calls.

### Some utility functions

Determine if the user has certutil installed:

```javascript
certgen.hasCertUtil();
```

Determine if the user has any NSS browsers that need to be trusted:

```javascript
certgen.hasNSS();
```

Verify if the current certificate has been trusted in the system store

```javascript
await verifyPlatformTrust();
```

## Changelog

### 1.4.5

* Bump `js-yaml` dependency from `3.13.1` to `3.14.2` for security and bug fixes.
* Add `.idea` in `.gitignore`.

### 1.4.4

* Added support for Apple Silicon in sudo-prompt applet.

### 1.4.3

* Added serialNumber prop to certificate object upon verification
* Updated trust verification on windows to use serialNumber and commonName
* Removed meaningless verification check

### 1.4.2

* Resolved missing 'certutil' command in windows truststore

### 1.4.0

* Update sha1 to sha256
* Have self-signed certs also be Certificate Authorities

### 1.3.0

* Fix issue with duplicate DNS names

### 1.2.8

* Fix inconsistencies with package-lock

### 1.2.7

* Move to getflywheel organization

### 1.2.6

* Remove dependencies on native node modules

### 1.2.5

* Ensure we're properly verifying the certificate to build NSS commands

### 1.2.4

* Fix default certPath when removing NSS trusts

### 1.2.3

* Improve readme documentation
* Fix bug where commands weren't returned from nss de-trust
* Make certPath optional on most functions

### 1.2.2

* Setup testing
* Use npm instead of yarn

### 1.2.1

* Fix filename when generating new key

### 1.2.0

* Minor refactor

### 1.1.6

* Savecertificate method is now properly async.

### 1.1.5

* Use which package to avoid errors.

### 1.1.4

* Add ability to verify system store on host machine has been trusted.

### 1.1.3

* We need to escape paths for the child_process.exec execution

### 1.1.2

* Send the correct database string to the NSS insert method.

### 1.1.1

* export NSS command paths without normalized paths

### 1.1.0

* Add helper function to retrieve NSS operations
* Add ability to not execute NSS trust commands

### 1.0.7

* Generated cert should not be listed as a CA.

### 1.0.6

* Properly escape spaces in all paths for NSS browser trust

### 1.0.5

* Don't escape Mac and Linux paths unless we have to

### 1.0.4

* Add ability to avoid direct execution of sudo commands with optional "execute" parameter.

### 1.0.3

* Ensure spaces are accounted for in Linux and Mac paths

### 1.0.2

* Ensure certutil path is populated in Linux
* Cleanout some unused variables after the port from mkcert

### 1.0.1

* Add ability to load an existing certificate for trusting

### 1.0.0

* Initial release