TLS & certificates
The edge terminates public TLS itself, using github.com/caddyserver/certmagic with a DNS-01 challenge to obtain and renew certificates automatically. There is no manual certbot dance and no reload step.
certmagic + DNS-01#
Wildcard certificates for *.example.comare only issuable via the DNS-01 challenge type — HTTP-01 and TLS-ALPN-01 can't issue wildcards at all. DNS-01 also means individual tunnel names never touch a Certificate Transparency log, since one wildcard cert covers every tunnel forever.
The DNS provider is chosen with -dns-provider — the only pluggable seam in the TLS stack. The default is cloudflare (github.com/libdns/cloudflare, with a scoped API token holding Zone:DNS:Edit on the single zone); route53, digitalocean, hetzner, vultr, ovh, desec, and bunny are also built in. Credentials come from the environment only. See Choosing a DNS provider for each provider's variables.
A provider is admitted only if its libdns module appends TXT values without replacing others at the same name and deletes by value, because the two certificates below publish their challenges at the same name concurrently. GoDaddy, Namecheap, Porkbun, IONOS, Azure, DNSimple, and netcup fail that test and are not supported.
Pin these dependencies
certmagic and every libdns provider to exact versions. The libdnsv1 interface migration is a live, recurring source of "it compiled last month" breakage — this is the one dependency pair in the project where a go get -u can take the edge down.Two certificates#
Calling certmagic.ManageSync with both *.example.com and example.comreads like one multi-SAN certificate. It isn't — certmagic does not obtain multi-SAN certificates, so that call places two independent ACME orders producing two certificates with two independent renewal schedules. This is forced anyway: a wildcard cert does not match SNI example.com, so the apex needs its own certificate regardless.
The apex can fail independently
ngstoned performs a startup check that a valid apex cert is loadable before :4443begins accepting, and exits loudly rather than listening with a cert it can't serve. /healthz reports both certs' NotAfter separately. Both names also validate through the same _acme-challenge.example.comTXT record. Only providers that delete by value are supported, so one order's cleanup cannot remove the other's in-flight record; staggering their renewal windows further reduces the overlap.Control-plane TLS#
Port :4443, the control plane agents dial into, is served by the apex certificate (example.com), a different certificate from the public wildcard, via tls.Config.GetCertificate. Agents connect to the bare domain, example.com:4443 — not a subdomain such as edge.example.com, which the apex certificate does not cover.
Agent verification & pinning#
The agent performs standard WebPKI validation against system roots. The ServerName it verifies defaults to the host part of --server, so --server example.com:4443 verifies example.com; --server-name overrides it. An optional SPKI pin (--pin sha256/BASE64) is checked in VerifyPeerCertificate in addition to chain validation. It is off by default, since pins combined with auto-renewing certs is a footgun unless you also reuse the same key across renewals.
Agent authentication is the bearer token, not client certificates. mTLS was rejected — it adds a private CA, issuance, and rotation ceremony for a single user with zero security gain over a 256-bit token carried inside TLS.
Storage#
Certificates are cached on disk via certmagic.FileStorageso an edge restart never blocks on Let's Encrypt:
FileStorage{Path: "/var/lib/private/ngstoned/certs"} # dir mode 0700This path is not arbitrary under systemd's DynamicUser — see Deployment & systemd.