fix(dev-server): for HTTPS, support non-RSA TLS certs

[bmaurer]

What got implemented:

• Support ECDSA certs
• Throw on cert/key mismatch
• Throw if only one of key/cert is provided
• Infer HTTPS mode if key/cert is provided: we don't really need explicit HTTPS env
• Support an extra DOCUSAURUS_ prefix for env variables (DOCUSAURUS_HTTPS=true), taking precedence over unprefixed env variables

Let's consider all this as a v3 bug fix, that will be backported and released in a patch release.

---

On v4, we'll:

• Add the new CLI args, as a new public api feature to document and mention in a release blog post => feat(dev-server): add dev-server CLI options for HTTPS support  #12082
• Think about deprecating env vars (?)

---

---

---

Original PR:

Two related fixes to getHttpsConfig in docusaurus start:

1. The validator in getHttpsConfig.ts used crypto.publicEncrypt / crypto.privateDecrypt to sanity-check the cert/key pair, but those APIs only work for RSA keys. Passing ECDSA (or EdDSA) certs — common in many corporate PKI setups — caused the dev server to throw operation not supported for this keytype even though the cert is fine.

   Replaced with crypto.X509Certificate + crypto.createPrivateKey, which work for any key type and additionally catch genuine cert/key-pair mismatches (the old code silently produced garbage in that case rather than throwing).

2. Certs could previously only be supplied via the SSL_CRT_FILE and SSL_KEY_FILE environment variables. Added matching --ssl-cert <path>, --ssl-key <path>, and --https CLI flags. CLI takes precedence; passing both --ssl-cert and --ssl-key implies HTTPS.

Test Plan

Unit tests

Extended getHttpsConfig.test.ts from 5 to 13 tests. The original 5 still pass (no behavior change for the RSA happy path). New coverage:

• ECDSA cert + key is accepted (would have thrown before this PR).
• Valid cert + valid-but-different key is rejected with a clear "do not match" error.
• getHttpsConfig({ sslCert, sslKey }) reads from CLI options when no env vars are set.
• CLI options take precedence over env vars when both are set.
• A missing CLI cert file produces a You specified --ssl-cert... error (the env-var path still reports SSL_CRT_FILE in your env...).
• --ssl-cert + --ssl-key together implies HTTPS without --https.
• --https alone returns true.

New ECDSA fixtures generated with openssl ecparam -name prime256v1 are committed alongside the existing RSA fixtures.

Test Files  1 passed (1)
     Tests  13 passed (13)

Manual

Generated a self-signed P-256 cert and ran:

docusaurus start --ssl-cert ./host.crt --ssl-key ./host.key --host 0.0.0.0

Server starts, curl --cacert ./host.crt https://localhost:3000/ returns 200 with verify=0. Without this PR the same invocation fails at startup with the unsupported keytype error from publicEncrypt.

Test links

https://deploy-preview-12065--docusaurus-2.netlify.app/

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	043e244
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/6a1988324f28fe0008e1a198
😎 Deploy Preview	https://deploy-preview-12065--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[slorber]

Thanks for the PR, that makes sense to me.

I've commented on a few things that could be improved/redesigned/simplified, and wonder if this should be a fix/feat/breaking change.

Please let me know how much you can help bring this PR to the finish line (I can do it)

If this is for Meta internal use, in what timeframe would you like to get this feature available? We have already released our last v3 planned minor version and respect semver.

• v3 (patch release) can be sooner to support ECDSA, but normally, we are not supposed to introduce new CLI options on patches.
• v4 (feat/breaking change) may take more time

An option could be to split this PR into 2:

• v3.10.x could fix support for ECDSA through env vars
• v4.0 could introduce new CLI flags

[bmaurer]

If you could bring it over the line I'd appreciate, you'll be more efficient than I will.

I appreciate the hesitance to add CLI flags in a patch release. I would point out that use of global environmental variables is often a direct cause of bugs. Passing something like SSL_KEY_FILE or HTTPS could impact subprocesses — in a complex environment like Meta, this can cause unpredictable behavior.

That said, if that's not compelling enough, i think a reasonable patch release approach could be to add a DOCUSAURUS_{HTTPS,...} env var that takes precedence over the generic one. That'd address my concern.

[slorber]

I see thanks

I'll bring this to the finish line and let you review before merging

[slorber]

I refactored/simplified the code, handled a few more edge cases.
It seems good to merge now.

For now, I only added secret DOCUSAURUS_ prefixed env vars.

We'll re-introduce the extra CLI options in Docusaurus v4 as a separate PR, and mention them in our upcoming blog post to ensure feature discoverability.

---

I'll test this locally and merge asap. I have a few other fixes to backport, so this should be released soon as a v3.10.2 patch release.

[slorber]

It works 👍

Here's how to validate locally on our own website, in addition to unit tests:

# RSA certs
DOCUSAURUS_SSL_CRT_FILE=../packages/docusaurus/src/webpack/utils/__tests__/__fixtures__/getHttpsConfig/host.crt DOCUSAURUS_SSL_KEY_FILE=../packages/docusaurus/src/webpack/utils/__tests__/__fixtures__/getHttpsConfig/host.key yarn start:website --host 0.0.0.0

# ECDSA certs
DOCUSAURUS_SSL_CRT_FILE=../packages/docusaurus/src/webpack/utils/__tests__/__fixtures__/getHttpsConfig/host-ec.crt DOCUSAURUS_SSL_KEY_FILE=../packages/docusaurus/src/webpack/utils/__tests__/__fixtures__/getHttpsConfig/host-ec.key yarn start:website --host 0.0.0.0

# Mismatch: throws
DOCUSAURUS_SSL_CRT_FILE=../packages/docusaurus/src/webpack/utils/__tests__/__fixtures__/getHttpsConfig/host-ec.crt DOCUSAURUS_SSL_KEY_FILE=../packages/docusaurus/src/webpack/utils/__tests__/__fixtures__/getHttpsConfig/host.key yarn start:website --host 0.0.0.0

[slorber]

Separate PR reintroducing the CLI args: #12082