Local HTTPS dev

Optional, but increasingly worth it. Vite auto-detects mkcert certs — once they exist, bun run dev serves HTTPS with no extra flags.

Why bother

• 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. Generate certs in the location Vite auto-detects:

   cd "$(mkcert -CAROOT)" && mkcert local.onramp.us portal.local.onramp.us customer.local.onramp.us

   mkcert -CAROOT resolves to something like ~/Library/Application Support/mkcert. The cd "$(...)" form just navigates there.
4. Add to /etc/hosts:

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

5. bun run dev → open https://local.onramp.us:3000

Setup (Linux)

Same flow. Install line is sudo apt install mkcert libnss3-tools (Debian/Ubuntu) or sudo dnf install mkcert nss-tools (Fedora). cd "$(mkcert -CAROOT)" resolves to ~/.local/share/mkcert on most distros.

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 — re-run the mkcert local.onramp.us portal.local.onramp.us customer.local.onramp.us line; the cert is per-hostname.