@docusaurus/core 3.10.1-canary-6640 → 3.10.1-canary-6642

package/lib/commands/cli.js

@@ -109,6 +109,9 @@ async function createCLIProgram({ cli, cliArgs, siteDir, config, }) {
         .option('--no-open', 'do not open page in the browser (default: false)')
         .option('--poll [interval]', 'use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds', normalizePollValue)
         .option('--no-minify', 'build website without minimizing JS bundles (default: false)')
+        .option('--https', 'serve the dev site over HTTPS using a self-signed cert (default: false). Preferred over the HTTPS=true env var. Implied when both --ssl-cert and --ssl-key are provided.')
+        .option('--ssl-cert <path>', 'path to a TLS certificate file (implies HTTPS). Preferred over the SSL_CRT_FILE env var; CLI takes precedence if both are set.')
+        .option('--ssl-key <path>', 'path to a TLS private key file (implies HTTPS). Preferred over the SSL_KEY_FILE env var; CLI takes precedence if both are set.')
         .action(start_1.start);
     cli
         .command('serve [siteDir]')

package/lib/commands/start/start.d.ts

@@ -11,5 +11,8 @@ export type StartCLIOptions = HostPortOptions & Pick<LoadContextParams, 'locale'
     open?: boolean;
     poll?: boolean | number;
     minify?: boolean;
+    https?: true;
+    sslCert?: string;
+    sslKey?: string;
 };
 export declare function start(siteDirParam?: string, cliOptions?: Partial<StartCLIOptions>): Promise<void>;

package/lib/commands/start/webpack.js

@@ -42,7 +42,11 @@ function registerWebpackE2ETestHook(compiler) {
 async function createDevServerConfig({ cliOptions, props, host, port, }) {
     const { baseUrl, siteDir, siteConfig } = props;
     const pollingOptions = (0, watcher_1.createPollingOptions)(cliOptions);
-    const httpsConfig = await (0, getHttpsConfig_1.default)();
+    const httpsConfig = await (0, getHttpsConfig_1.default)({
+        https: cliOptions.https,
+        sslCert: cliOptions.sslCert,
+        sslKey: cliOptions.sslKey,
+    });
     // https://webpack.js.org/configuration/dev-server
     return {
         hot: cliOptions.hotOnly ? 'only' : true,

package/lib/webpack/utils/getHttpsConfig.d.ts

@@ -4,7 +4,13 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export default function getHttpsConfig(): Promise<boolean | {
+type HttpsConfigOptions = {
+    https: boolean;
+    sslCert: string;
+    sslKey: string;
+};
+export default function getHttpsConfig(options?: Partial<HttpsConfigOptions>): Promise<boolean | {
     cert: Buffer;
     key: Buffer;
 }>;
+export {};

package/lib/webpack/utils/getHttpsConfig.js

@@ -13,48 +13,109 @@ const path_1 = tslib_1.__importDefault(require("path"));
 const crypto_1 = tslib_1.__importDefault(require("crypto"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 // 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;
+// throw an easy to debug error.
+//
+// Works for any key type (RSA, ECDSA, EdDSA, ...) — parses both PEMs and
+// checks that the public key embedded in the cert matches the public key
+// derived from the private key.
+function validateKeyAndCerts({ cert, key }) {
+    let certPublicKey;
     try {
-        // publicEncrypt will throw an error with an invalid cert
-        encrypted = crypto_1.default.publicEncrypt(cert, Buffer.from('test'));
+        certPublicKey = new crypto_1.default.X509Certificate(cert.content).publicKey;
     }
-    catch (err) {
-        logger_1.default.error `The certificate path=${crtFile} is invalid.`;
-        throw err;
+    catch (error) {
+        throw new Error(logger_1.default.interpolate `The certificate path=${cert.path} is invalid.`, { cause: error });
     }
+    let keyPublicKey;
     try {
-        // privateDecrypt will throw an error with an invalid key
-        crypto_1.default.privateDecrypt(key, encrypted);
+        keyPublicKey = crypto_1.default.createPublicKey(crypto_1.default.createPrivateKey(key.content));
     }
-    catch (err) {
-        logger_1.default.error `The certificate key path=${keyFile} is invalid.`;
-        throw err;
+    catch (error) {
+        throw new Error(logger_1.default.interpolate `The certificate key path=${key.path} is invalid.`, { cause: error });
     }
+    if (!certPublicKey.equals(keyPublicKey)) {
+        throw new Error(logger_1.default.interpolate `The certificate path=${cert.path} and key path=${key.path} do not match.`);
+    }
+}
+function getExplicitHttps(options) {
+    return (options.https ??
+        (typeof process.env.DOCUSAURUS_HTTPS !== 'undefined'
+            ? process.env.DOCUSAURUS_HTTPS == 'true'
+            : undefined) ??
+        (typeof process.env.HTTPS !== 'undefined'
+            ? process.env.HTTPS == 'true'
+            : undefined));
+}
+async function readCryptoFile(filepath, source) {
+    if (!(await fs_extra_1.default.pathExists(filepath))) {
+        throw new Error(logger_1.default.interpolate `You specified ${source}, but file at path path=${filepath} can't be found.`);
+    }
+    try {
+        return {
+            path: filepath,
+            source,
+            content: await fs_extra_1.default.readFile(filepath),
+        };
+    }
+    catch (error) {
+        throw new Error(logger_1.default.interpolate `You specified ${source}, but file at path path=${filepath} can't be read.`, { cause: error });
+    }
+}
+function getCert(options, cwd) {
+    if (options.sslCert) {
+        return readCryptoFile(path_1.default.resolve(cwd, options.sslCert), 'CLI arg --ssl-cert');
+    }
+    if (process.env.DOCUSAURUS_SSL_CRT_FILE) {
+        return readCryptoFile(path_1.default.resolve(cwd, process.env.DOCUSAURUS_SSL_CRT_FILE), 'env DOCUSAURUS_SSL_CRT_FILE');
+    }
+    if (process.env.SSL_CRT_FILE) {
+        return readCryptoFile(path_1.default.resolve(cwd, process.env.SSL_CRT_FILE), 'env SSL_CRT_FILE');
+    }
+    return null;
+}
+function getKeyFile(options, cwd) {
+    if (options.sslKey) {
+        return readCryptoFile(path_1.default.resolve(cwd, options.sslKey), 'CLI arg --ssl-key');
+    }
+    if (process.env.DOCUSAURUS_SSL_KEY_FILE) {
+        return readCryptoFile(path_1.default.resolve(cwd, process.env.DOCUSAURUS_SSL_KEY_FILE), 'env DOCUSAURUS_SSL_KEY_FILE');
+    }
+    if (process.env.SSL_KEY_FILE) {
+        return readCryptoFile(path_1.default.resolve(cwd, process.env.SSL_KEY_FILE), 'env SSL_KEY_FILE');
+    }
+    return null;
 }
-// Read file and throw an error if it doesn't exist
-async function readEnvFile(file, type) {
-    if (!(await fs_extra_1.default.pathExists(file))) {
-        throw new Error(`You specified ${type} in your env, but the file "${file}" can't be found.`);
+function ensureCertKeyBothProvided(cert, key) {
+    if ((cert || key) && !(cert && key)) {
+        const fileProvided = (cert ?? key);
+        throw new Error(logger_1.default.interpolate `HTTPS support require proving a certificate and key at the same time.
+You only provided a ${cert ? 'certificate' : 'key'} (with ${fileProvided.source}) at path path=${fileProvided.path}.`);
     }
-    return fs_extra_1.default.readFile(file);
 }
 // Get the https config
-// Return cert files if provided in env, otherwise just true or false
-async function getHttpsConfig() {
-    const appDirectory = await fs_extra_1.default.realpath(process.cwd());
-    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_1.default.resolve(appDirectory, SSL_CRT_FILE);
-        const keyFile = path_1.default.resolve(appDirectory, SSL_KEY_FILE);
-        const config = {
-            cert: await readEnvFile(crtFile, 'SSL_CRT_FILE'),
-            key: await readEnvFile(keyFile, 'SSL_KEY_FILE'),
+// Return cert files if provided via CLI or env, otherwise just true or false.
+// CLI options take precedence over env vars.
+async function getHttpsConfig(options = {}) {
+    const cwd = await fs_extra_1.default.realpath(process.cwd());
+    const [cert, key] = await Promise.all([
+        getCert(options, cwd),
+        getKeyFile(options, cwd),
+    ]);
+    // Providing both cert/key implies HTTPS
+    const inferredHttps = !!(cert && key);
+    const https = getExplicitHttps(options) ?? inferredHttps;
+    if (https && cert && key) {
+        validateKeyAndCerts({
+            cert,
+            key,
+        });
+        return {
+            cert: cert.content,
+            key: key.content,
         };
-        validateKeyAndCerts({ ...config, keyFile, crtFile });
-        return config;
     }
-    return isHttps;
+    ensureCertKeyBothProvided(cert, key);
+    // Apparently we can have https without cert/key (historical)
+    // although I don't know how this works 🤷‍♂️
+    return https;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "3.10.1-canary-6640",
+  "version": "3.10.1-canary-6642",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -33,13 +33,13 @@
     "url": "https://github.com/facebook/docusaurus/issues"
   },
   "dependencies": {
-    "@docusaurus/babel": "3.10.1-canary-6640",
-    "@docusaurus/bundler": "3.10.1-canary-6640",
-    "@docusaurus/logger": "3.10.1-canary-6640",
-    "@docusaurus/mdx-loader": "3.10.1-canary-6640",
-    "@docusaurus/utils": "3.10.1-canary-6640",
-    "@docusaurus/utils-common": "3.10.1-canary-6640",
-    "@docusaurus/utils-validation": "3.10.1-canary-6640",
+    "@docusaurus/babel": "3.10.1-canary-6642",
+    "@docusaurus/bundler": "3.10.1-canary-6642",
+    "@docusaurus/logger": "3.10.1-canary-6642",
+    "@docusaurus/mdx-loader": "3.10.1-canary-6642",
+    "@docusaurus/utils": "3.10.1-canary-6642",
+    "@docusaurus/utils-common": "3.10.1-canary-6642",
+    "@docusaurus/utils-validation": "3.10.1-canary-6642",
     "boxen": "^6.2.1",
     "chalk": "^4.1.2",
     "chokidar": "^3.5.3",
@@ -77,8 +77,8 @@
     "webpack-merge": "^6.0.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.10.1-canary-6640",
-    "@docusaurus/types": "3.10.1-canary-6640",
+    "@docusaurus/module-type-aliases": "3.10.1-canary-6642",
+    "@docusaurus/types": "3.10.1-canary-6642",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/detect-port": "^1.3.3",
     "@types/react-dom": "^19.2.3",
@@ -104,5 +104,5 @@
   "engines": {
     "node": ">=24.14"
   },
-  "gitHead": "cdd938e63e34bb1fb016ef7f9c25e01ab60bf6e4"
+  "gitHead": "07f8b9714f5a0c554a615d3d23e0e411ef4ef465"
 }