Local HTTPS for development: a private CA, trust stores and the localhost exception

Goal

Serve the application locally over HTTPS with a certificate that browsers and command-line tools accept, so that Secure cookies, mixed-content rules and OAuth redirect URIs behave as in production, without certificate warnings and without public certificates for names you do not own.

Prerequisites

Know when it is unnecessary: the Secure Contexts specification treats an origin as potentially trustworthy when its host is an address in 127.0.0.0/8 or ::1/128 and, for user agents that resolve localhost names to loopback as the specification requires, when it is localhost or ends in .localhost; plain http://localhost therefore already receives secure-context APIs in such browsers. Local HTTPS earns its cost when you test TLS-specific behaviour, use a non-loopback development hostname, or run several services under one wildcard name. Let's Encrypt's guidance for localhost is to generate your own certificate, self-signed or signed by a local root, and trust it in the operating system's trust store.

Steps

1. Create a private CA once per developer machine. mkcert -install creates a local CA and, according to its README, installs it in the system trust store and in the Firefox store where present. Never commit or share the CA key; the README warns that rootCA-key.pem gives complete power to intercept secure requests from your machine.
2. Issue leaf certificates for development names only, for example mkcert app.localhost "*.dev.example.test" 127.0.0.1; never production hostnames.
3. Configure the local server or reverse proxy with the certificate and key; the README states that mkcert does not configure servers for you. Keep the files out of version control and container images.
4. Make non-browser clients trust the CA. The README documents NODE_EXTRA_CA_CERTS for Node.js, pointing at the root file in the folder printed by mkcert -CAROOT; other runtimes read the system store or need their own variable. Record the variable per tool in the setup script.
5. On a second machine or in a dev container, repeat step 1; each machine has its own CA, so leaf certificates are regenerated, not copied.
6. Add a setup-script check: a request to the local HTTPS endpoint must succeed without disabling verification.

Expected result

The browser shows a valid certificate for the development origin, Secure cookies work, and nobody learns to click through certificate warnings.

Limits and test basis

A private CA in the system store is a security decision for that machine; keep the key readable only by its user. Mobile devices need a separate import of the root file, described in the mkcert README, which also lists Java (when JAVA_HOME is set) and the NSS store used by Firefox among its root stores, selectable with TRUST_STORES. Procedure synthesised from the cited documents; no measurements are claimed.