feat(v2): add support for key,cert in https (#3594)

* fix: add support for key,cert in https

* docs: add steps for using https with docusaurus

* improve https certs docs

* typo

* local https: add mkcert -install step

Co-authored-by: slorber <lorber.sebastien@gmail.com>

packages/docusaurus/src/commands/start.ts

@@ -23,7 +23,7 @@ import {load} from '../server';
 import {StartCLIOptions} from '@docusaurus/types';
 import {CONFIG_FILE_NAME, STATIC_DIR_NAME} from '../constants';
 import createClientConfig from '../webpack/client';
-import {applyConfigureWebpack} from '../webpack/utils';
+import {applyConfigureWebpack, getHttpsConfig} from '../webpack/utils';
 import {getCLIOptionHost, getCLIOptionPort} from './commandUtils';
 
 export default async function start(
@@ -144,7 +144,7 @@ export default async function start(
       // `webpackHotDevClient`.
       injectClient: false,
       quiet: true,
-      https: protocol === 'https',
+      https: getHttpsConfig(),
       headers: {
         'access-control-allow-origin': '*',
       },

packages/docusaurus/src/webpack/utils.ts

@@ -9,6 +9,10 @@ import MiniCssExtractPlugin from 'mini-css-extract-plugin';
 import env from 'std-env';
 import merge from 'webpack-merge';
 import webpack, {Configuration, Loader, RuleSetRule, Stats} from 'webpack';
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import chalk from 'chalk';
 import {TransformOptions} from '@babel/core';
 import {ConfigureWebpackFn} from '@docusaurus/types';
 import {version as cacheLoaderVersion} from 'cache-loader/package.json';
@@ -274,3 +278,61 @@ export function getFileLoaderUtils() {
 
   return {loaders, rules};
 }
+
+// Ensure the certificate and key provided are valid and if not
+// throw an easy to debug error
+function validateKeyAndCerts({cert, key, keyFile, crtFile}) {
+  let encrypted;
+  try {
+    // publicEncrypt will throw an error with an invalid cert
+    encrypted = crypto.publicEncrypt(cert, Buffer.from('test'));
+  } catch (err) {
+    throw new Error(
+      `The certificate "${chalk.yellow(crtFile)}" is invalid.\n${err.message}`,
+    );
+  }
+
+  try {
+    // privateDecrypt will throw an error with an invalid key
+    crypto.privateDecrypt(key, encrypted);
+  } catch (err) {
+    throw new Error(
+      `The certificate key "${chalk.yellow(keyFile)}" is invalid.\n${
+        err.message
+      }`,
+    );
+  }
+}
+
+// Read file and throw an error if it doesn't exist
+function readEnvFile(file, type) {
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `You specified ${chalk.cyan(
+        type,
+      )} in your env, but the file "${chalk.yellow(file)}" can't be found.`,
+    );
+  }
+  return fs.readFileSync(file);
+}
+
+const appDirectory = fs.realpathSync(process.cwd());
+// Get the https config
+// Return cert files if provided in env, otherwise just true or false
+export function getHttpsConfig(): boolean | {cert: Buffer; key: Buffer} {
+  const {SSL_CRT_FILE, SSL_KEY_FILE, HTTPS} = process.env;
+  const isHttps = HTTPS === 'true';
+
+  if (isHttps && SSL_CRT_FILE && SSL_KEY_FILE) {
+    const crtFile = path.resolve(appDirectory, SSL_CRT_FILE);
+    const keyFile = path.resolve(appDirectory, SSL_KEY_FILE);
+    const config = {
+      cert: readEnvFile(crtFile, 'SSL_CRT_FILE'),
+      key: readEnvFile(keyFile, 'SSL_KEY_FILE'),
+    };
+
+    validateKeyAndCerts({...config, keyFile, crtFile});
+    return config;
+  }
+  return isHttps;
+}

website/docs/cli.md

@@ -57,6 +57,22 @@ Please note that some functionality (for example, anchor links) will not work in
 
 :::
 
+#### Enabling HTTPS`
+
+There are multiple ways to obtain a certificate. We will use [mkcert](https://github.com/FiloSottile/mkcert) as an example.
+
+1. Run `mkcert localhost` to generate `localhost.pem` + `localhost-key.pem`
+
+2. Run `mkcert -install` to install the cert in your trust store, and restart your browser
+
+3. Start the app with Docusaurus HTTPS env variables:
+
+```shell
+HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
+```
+
+4. Open `https://localhost:3000/`
+
 ### `docusaurus build`
 
 Compiles your site for production.