localca¶
A framework-free, mkcert-style local development CA for Go. Generate a
per-machine root, install it into the OS and browser trust stores, and mint
browser-trusted HTTPS certificates for localhost and LAN IPs — with zero manual
setup.
gitlab.com/phpboyscout/go/localca gives any Go tool trusted local HTTPS without the
"untrusted certificate" warning. On first run it mints a per-machine ECDSA root CA,
installs it into the system and NSS (Firefox/Chromium) trust stores, and issues
short-lived leaf certificates — surfaced as a
go/tls.Pair so any transport serves the
trusted cert unchanged.
It is Layer 1 of a two-layer TLS strategy for the phpboyscout tool family: a local CA that works offline forever, and the permanent CI / air-gapped fallback even once a public-ACME path exists.
Why¶
- One-liner first run.
EnsureServedensures the root exists and is trusted, then hands back a servablego/tls.Pair. Idempotent — an already-trusted root re-prompts nothing; a still-valid leaf is reused. - Never a shared key. Every install mints its own per-machine root, stored
0600. A bundled shared CA key would be a universal MITM key against every user, so one is never generated or shipped. See the trust model. - Framework-free. Typed
Config, an injectedafero.Fs, and an optional*slog.Logger— no config framework, no TUI, no OpenTelemetry. Adepfootprint_test.goguard keeps the dependency graph minimal.
What it does not do¶
Before building on an assumption: localca cannot install trust on Windows, has no
GUI password dialog, caches only one leaf per data directory, and issues server
certificates only — no client certificates, no RSA, no revocation. Each of those is stated
plainly, with the reasoning, in limitations.
Where next¶
- Serve trusted HTTPS from a Go program — the tutorial: from nothing to a padlock in about ten minutes.
- Serve your tool over HTTPS locally — LAN addresses, store scoping, CI, uninstall.
- Troubleshoot a certificate the browser will not trust — symptom by symptom.
- Reference — every config field, file, platform and error, with defaults and failure behaviour.
- Trust & security model — the per-machine-root trade-off, consent, and why NSS is best-effort.
- Why the certificates look the way they do — ECDSA, 90-day leaves, and the choices behind them.
- API signatures — godoc on pkg.go.dev.
Part of the phpboyscout Go toolkit — small, framework-free Go modules for the phpboyscout tool family.
Further reading¶
The blog carries a curated route through this subject: Building a web service in Go collects everything written about it, ordered so you can start at the beginning rather than newest-first.
Ask phpbotscout
He answers questions about the projects over on the Discord, citing the docs where they already cover it, and offering to raise an issue where they don't. Bring a bug, an idea, or a questionable engineering decision.