Local HTTPS dev

Required for bun run dev. The stack runs a cert preflight (devtools/setup-https.mjs) before anything spawns, and exits if mkcert is not installed or its local root CA is not in your trust store — that one-time setup is below. Once it passes, the preflight issues the cert itself and Vite serves HTTPS with no extra flags.

DEV_NO_HTTPS=1 bun run dev skips the preflight and serves plain HTTP. It is an escape hatch, not a supported mode: the admin SPA's auth bootstrap needs Web Crypto, which the browser blocks outside a secure context, so expect it to break.

Why it is required

• Web Crypto API — crypto.randomUUID(), crypto.subtle.* (encryption, signing, hashing) only run in secure contexts. Without HTTPS the browser blocks them.
• Service Workers + PWA features — required for offline modes, push notifications, background sync. Currently un-testable on plain HTTP.
• Clipboard API — navigator.clipboard.writeText / readText need a secure origin. Copy-link flows fail silently in non-Chromium browsers without it.
• Cookies that mirror prod — Secure and SameSite=None cookies don't work on plain HTTP. Auth/session bugs that only show in prod often reproduce locally once we go HTTPS.
• Mixed-content parity — prod blocks http:// subresources from https:// pages. Catching that locally avoids late-breaking surprises.
• OAuth / SSO redirect testing — most providers (Google, Microsoft, HubSpot, Salesforce) require HTTPS callback URLs even for dev.
• Realistic CORS + cookie behavior — third-party iframes and CRM webhooks behave differently under HTTPS.
• HTTP/2 — Vite's HTTPS mode enables HTTP/2 multiplexing, which trims dev-server overhead on pages with many module requests.

Setup (macOS)

1. brew install mkcert nss
2. mkcert -install (installs the local root CA into your system + Firefox trust stores)
3. Add to /etc/hosts:

   127.0.0.1  local.onramp.us portal.local.onramp.us customer.local.onramp.us

   The preflight reads this file and covers every hostname mapped to 127.0.0.1, so a host you add here is a host the cert will carry.
4. bun run dev → open https://local.onramp.us:3000

Generating the cert by hand is not a step. The preflight issues one into .dev-certs/ and re-issues whenever your loopback host list changes.

Setup (Linux)

Same flow. Install line is sudo apt install mkcert libnss3-tools (Debian/Ubuntu) or sudo dnf install mkcert nss-tools (Fedora).

Troubleshooting

• NET::ERR_CERT_AUTHORITY_INVALID — you skipped mkcert -install. Run it, then restart the browser.
• Firefox "Secure connection failed" — nss (or libnss3-tools) must be installed before mkcert -install. Reinstall in that order.
• "Wrong host" warning — the hostname is not in the cert. Add it to /etc/hosts on the 127.0.0.1 line and restart bun run dev; the preflight notices the changed host list and re-issues.
• ⚠ Local HTTPS setup required and the stack exits — mkcert is missing or mkcert -install never ran. The notice prints the exact install line for your platform.