The web UI's certificate from Let's Encrypt, through Jarl

tls.acme names the certificate and jarl: the Jarl server and a token that
may only write the challenge record. Steward gets the certificate with
DNS-01 (lego), writing the record through Jarl's API into every view that
has the zone, renews it with a third of its lifetime left and swaps it
in without a restart. A check runs before every order: Jarl, the zone,
the token's permission, a test record, the zone's name servers, public
resolvers, clean-up; each step says what to fix. Staging by default.

With a certificate, each listener serves HTTPS and plain HTTP on one port
(redirecting plain HTTP, except from the server itself).

steward cert / cert check / cert renew, Server -> Certificate in the web
UI, GET /certificate, POST /certificate/check|renew. docs/certificates.md
and docs/jarl.md (the Jarl user and the token's grant).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/server/h_cert.go

@@ -0,0 +1,94 @@
+package server
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"time"
+
+	"steward/internal/api"
+	"steward/internal/auth"
+	"steward/internal/certs"
+	"steward/internal/validate"
+)
+
+func (s *Server) certificate(w http.ResponseWriter, r *http.Request, p *auth.Principal) error {
+	if err := requireAdmin(p); err != nil {
+		return err
+	}
+	out := api.CertificateResponse{Source: "none"}
+	switch {
+	case s.cfg.ACME != nil:
+		st := s.cfg.ACME.Status()
+		out.Configured, out.Source, out.Status = true, "acme", &st
+	case s.cfg.TLSCertFile != "":
+		out.Source = "file"
+	}
+	writeJSON(w, http.StatusOK, out)
+	return nil
+}
+
+func (s *Server) acmeManager() (*certs.Manager, error) {
+	if s.cfg.ACME == nil {
+		return nil, conflict("stewardd doesn't obtain its certificate: set tls.acme and jarl in steward.yaml (docs/certificates.md)")
+	}
+	return s.cfg.ACME, nil
+}
+
+// certificateCheck: POST /certificate/check runs the preflight check now
+// (it takes up to a few minutes when the record is slow to appear).
+func (s *Server) certificateCheck(w http.ResponseWriter, r *http.Request, p *auth.Principal) error {
+	if err := requireAdmin(p); err != nil {
+		return err
+	}
+	m, err := s.acmeManager()
+	if err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 4*time.Minute)
+	defer cancel()
+	c := m.Preflight(ctx)
+	s.eng.Audit(r.Context(), p, "certificate.check", m.Status().Domain, map[bool]string{true: "success", false: "failure"}[c.OK], "")
+	writeJSON(w, http.StatusOK, c)
+	return nil
+}
+
+// certificateRenew: POST /certificate/renew gets a new certificate now, in
+// the background (GET /certificate follows it).
+func (s *Server) certificateRenew(w http.ResponseWriter, r *http.Request, p *auth.Principal) error {
+	if err := requireAdmin(p); err != nil {
+		return err
+	}
+	m, err := s.acmeManager()
+	if err != nil {
+		return err
+	}
+	m.Kick()
+	s.eng.Audit(r.Context(), p, "certificate.renew", m.Status().Domain, "success", "")
+	st := m.Status()
+	writeJSON(w, http.StatusAccepted, api.CertificateResponse{Configured: true, Source: "acme", Status: &st})
+	return nil
+}
+
+// certificateProblems are the certificate's problems for /status.
+func (s *Server) certificateProblems() []validate.Problem {
+	if s.cfg.ACME == nil {
+		return nil
+	}
+	st := s.cfg.ACME.Status()
+	obj := "certificate " + st.Domain
+	var out []validate.Problem
+	if st.LastError != "" {
+		out = append(out, validate.Problem{Severity: validate.Warning, Code: "certificate_failed", Object: obj,
+			Message: "getting the web UI's certificate failed: " + st.LastError})
+	}
+	if st.NotAfter != nil && time.Until(*st.NotAfter) < 14*24*time.Hour {
+		out = append(out, validate.Problem{Severity: validate.Warning, Code: "certificate_expiring", Object: obj,
+			Message: fmt.Sprintf("the certificate ends %s and hasn't been renewed", st.NotAfter.Local().Format("2006-01-02 15:04"))})
+	}
+	if st.State == "ok" && st.Staging {
+		out = append(out, validate.Problem{Severity: validate.Warning, Code: "certificate_staging", Object: obj,
+			Message: "the certificate is from Let's Encrypt's staging service, which browsers don't trust: once it works, set tls.acme.directory: letsencrypt and restart stewardd"})
+	}
+	return out
+}

internal/server/h_leases.go

@@ -172,6 +172,9 @@ func (s *Server) status(w http.ResponseWriter, r *http.Request, p *auth.Principa
 	leases := s.dhcp.Leases()
 	out := api.Status{Build: version.Info(), Started: s.started, Interfaces: []api.InterfaceStatus{}, Subnets: []api.Subnet{},
 		Problems: s.eng.Problems(), Leases: map[string]int{}, Messages: s.dhcp.Counts(), Database: s.store.Path()}
+	if p.IsAdmin() {
+		out.Problems = append(out.Problems, s.certificateProblems()...)
+	}
 	if out.Problems == nil {
 		out.Problems = []validate.Problem{}
 	}

internal/server/routes.go

@@ -63,6 +63,9 @@ func (s *Server) routes() {
 	// Status and audit
 	m.HandleFunc("GET "+p+"/status", s.authed(s.status))
 	m.HandleFunc("GET "+p+"/audit", s.authed(s.listAudit))
+	m.HandleFunc("GET "+p+"/certificate", s.authed(s.certificate))
+	m.HandleFunc("POST "+p+"/certificate/check", s.authed(s.certificateCheck))
+	m.HandleFunc("POST "+p+"/certificate/renew", s.authed(s.certificateRenew))
 	m.HandleFunc(p+"/", func(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusNotFound, "not_found", "no such API endpoint: "+r.Method+" "+r.URL.Path)
 	})

internal/server/server.go

@@ -19,6 +19,7 @@ import (
 	"time"
 
 	"steward/internal/auth"
+	"steward/internal/certs"
 	"steward/internal/dhcpd"
 	"steward/internal/engine"
 	"steward/internal/store"
@@ -40,6 +41,9 @@ type Config struct {
 	Socket string
 	// PingProblem says why the ping check can't run (nil: always fine).
 	PingProblem func() string
+	// ACME keeps the certificate stewardd obtains itself (tls.acme; nil
+	// when off).
+	ACME *certs.Manager
 }
 
 // Interfaces lists the host's interfaces.
@@ -106,6 +110,9 @@ func (s *Server) Serve(ctx context.Context, ready func()) error {
 	if len(s.cfg.Listen) == 0 {
 		return errors.New("no listen addresses configured")
 	}
+	// With a certificate (tls.cert_file, or one stewardd obtains, which
+	// may turn up later), each listener serves HTTPS and plain HTTP side
+	// by side (sniff.go); plain HTTP is redirected once there is one.
 	var tlsCfg *tls.Config
 	if s.cfg.TLSCertFile != "" {
 		cr, err := newCertReloader(s.cfg.TLSCertFile, s.cfg.TLSKeyFile, s.log)
@@ -113,7 +120,9 @@ func (s *Server) Serve(ctx context.Context, ready func()) error {
 			return err
 		}
 		s.certs = cr
-		tlsCfg = &tls.Config{MinVersion: tls.VersionTLS12, GetCertificate: cr.get, NextProtos: []string{"h2", "http/1.1"}}
+	}
+	if s.certs != nil || s.cfg.ACME != nil {
+		tlsCfg = &tls.Config{MinVersion: tls.VersionTLS12, GetCertificate: s.webCertificate, NextProtos: []string{"h2", "http/1.1"}}
 	}
 	errc := make(chan error, len(s.cfg.Listen)+1)
 	var listeners []net.Listener
@@ -131,8 +140,12 @@ func (s *Server) Serve(ctx context.Context, ready func()) error {
 		listeners = append(listeners, ln)
 	}
 	for i, ln := range listeners {
+		handler := s.Handler()
+		if tlsCfg != nil {
+			handler = s.requireHTTPS(handler)
+		}
 		srv := &http.Server{
-			Handler:           s.Handler(),
+			Handler:           handler,
 			ReadHeaderTimeout: 10 * time.Second,
 			ReadTimeout:       2 * time.Minute,
 			WriteTimeout:      5 * time.Minute,
@@ -145,11 +158,16 @@ func (s *Server) Serve(ctx context.Context, ready func()) error {
 		s.mu.Unlock()
 		scheme := "http"
 		if tlsCfg != nil {
-			scheme = "https"
-			ln = tls.NewListener(ln, tlsCfg)
-		} else if host, _, err := net.SplitHostPort(s.cfg.Listen[i]); err == nil {
-			if ip, err := netip.ParseAddr(host); host == "" || err == nil && !ip.IsLoopback() {
-				s.log.Warn("serving plain HTTP on a non-loopback address: passwords and API tokens travel unencrypted; configure tls or a TLS reverse proxy", "addr", s.cfg.Listen[i])
+			if s.httpsAvailable() {
+				scheme = "https"
+			}
+			ln = newSniffListener(ln, tlsCfg)
+		}
+		if !s.httpsAvailable() && s.cfg.ACME == nil {
+			if host, _, err := net.SplitHostPort(s.cfg.Listen[i]); err == nil {
+				if ip, err := netip.ParseAddr(host); host == "" || err == nil && !ip.IsLoopback() {
+					s.log.Warn("serving plain HTTP on a non-loopback address: passwords and API tokens travel unencrypted; configure tls or a TLS reverse proxy", "addr", s.cfg.Listen[i])
+				}
 			}
 		}
 		s.log.Info("listening", "addr", s.cfg.Listen[i], "url", scheme+"://"+ln.Addr().String())

internal/server/sniff.go

@@ -0,0 +1,147 @@
+package server
+
+import (
+	"bufio"
+	"crypto/tls"
+	"errors"
+	"net"
+	"net/http"
+	"net/netip"
+	"strings"
+	"sync"
+	"time"
+)
+
+// sniffListener serves TLS and plain HTTP on the same port: it looks at a
+// connection's first byte and hands the server a *tls.Conn when it is a
+// TLS handshake (0x16), the plain connection otherwise. That way stewardd
+// can start serving HTTPS when a certificate turns up (one it obtains,
+// docs/certificates.md) without a restart, and a plain-HTTP bookmark gets
+// a redirect instead of an error.
+type sniffListener struct {
+	net.Listener
+	cfg  *tls.Config
+	ch   chan net.Conn
+	errc chan error
+	done chan struct{}
+	once sync.Once
+}
+
+func newSniffListener(ln net.Listener, cfg *tls.Config) *sniffListener {
+	l := &sniffListener{Listener: ln, cfg: cfg, ch: make(chan net.Conn), errc: make(chan error, 1), done: make(chan struct{})}
+	go l.loop()
+	return l
+}
+
+func (l *sniffListener) loop() {
+	for {
+		c, err := l.Listener.Accept()
+		if err != nil {
+			var ne net.Error
+			if errors.As(err, &ne) && ne.Timeout() {
+				time.Sleep(50 * time.Millisecond)
+				continue
+			}
+			select {
+			case l.errc <- err:
+			default:
+			}
+			return
+		}
+		go l.classify(c)
+	}
+}
+
+func (l *sniffListener) classify(c net.Conn) {
+	c.SetReadDeadline(time.Now().Add(10 * time.Second))
+	br := bufio.NewReader(c)
+	b, err := br.Peek(1)
+	c.SetReadDeadline(time.Time{})
+	if err != nil {
+		c.Close()
+		return
+	}
+	var out net.Conn = &peekedConn{Conn: c, r: br}
+	if b[0] == 0x16 {
+		out = tls.Server(out, l.cfg)
+	}
+	select {
+	case l.ch <- out:
+	case <-l.done:
+		c.Close()
+	}
+}
+
+func (l *sniffListener) Accept() (net.Conn, error) {
+	select {
+	case c := <-l.ch:
+		return c, nil
+	case err := <-l.errc:
+		return nil, err
+	case <-l.done:
+		return nil, net.ErrClosed
+	}
+}
+
+func (l *sniffListener) Close() error {
+	l.once.Do(func() { close(l.done) })
+	return l.Listener.Close()
+}
+
+// peekedConn reads through the buffer that holds the peeked byte.
+type peekedConn struct {
+	net.Conn
+	r *bufio.Reader
+}
+
+func (c *peekedConn) Read(p []byte) (int, error) { return c.r.Read(p) }
+
+// webCertificate is the certificate stewardd serves: tls.cert_file's, or
+// the one it obtains itself (tls.acme).
+func (s *Server) webCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {
+	if s.certs != nil {
+		return s.certs.get(hello)
+	}
+	if s.cfg.ACME != nil {
+		if c := s.cfg.ACME.Certificate(); c != nil {
+			return c, nil
+		}
+	}
+	return nil, errNoCertificate
+}
+
+var errNoCertificate = errors.New("no certificate for HTTPS yet")
+
+// httpsAvailable reports whether stewardd has a certificate to serve.
+func (s *Server) httpsAvailable() bool {
+	return s.certs != nil || s.cfg.ACME != nil && s.cfg.ACME.Certificate() != nil
+}
+
+// requireHTTPS sends plain-HTTP requests to HTTPS once there is a
+// certificate: browsers (GET and HEAD) get a redirect, anything else an
+// error, so tokens and passwords aren't sent in the clear. Requests from
+// loopback (tools on this server) and from trusted proxies (which
+// terminate TLS themselves) are served as they are.
+func (s *Server) requireHTTPS(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.TLS != nil || !s.httpsAvailable() {
+			next.ServeHTTP(w, r)
+			return
+		}
+		host, _, _ := net.SplitHostPort(r.RemoteAddr)
+		if a, err := netip.ParseAddr(host); err == nil && (a.Unmap().IsLoopback() || s.trusted(a.Unmap())) {
+			next.ServeHTTP(w, r)
+			return
+		}
+		target := "https://" + r.Host + r.URL.RequestURI()
+		if r.Method == http.MethodGet || r.Method == http.MethodHead {
+			http.Redirect(w, r, target, http.StatusPermanentRedirect)
+			return
+		}
+		msg := "stewardd serves HTTPS on this port; use " + strings.TrimSuffix(target, r.URL.RequestURI())
+		if r.Header.Get("Authorization") != "" {
+			msg += ". This request's token crossed the network unencrypted; if that network isn't trusted, rotate the token"
+		}
+		writeError(w, http.StatusBadRequest, "https_required", msg)
+	})
+}

internal/server/sniff_test.go

@@ -0,0 +1,58 @@
+package server
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/pem"
+	"io"
+	"math/big"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestHTTPSAndPlainOnOnePort serves a certificate file: the same port
+// answers HTTPS, and plain HTTP from loopback.
+func TestHTTPSAndPlainOnOnePort(t *testing.T) {
+	dir := t.TempDir()
+	key, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	tmpl := &x509.Certificate{SerialNumber: big.NewInt(1), Subject: pkix.Name{CommonName: "dhcp.test"}, DNSNames: []string{"dhcp.test"},
+		NotBefore: time.Now().Add(-time.Hour), NotAfter: time.Now().Add(time.Hour)}
+	der, _ := x509.CreateCertificate(rand.Reader, tmpl, tmpl, &key.PublicKey, key)
+	kd, _ := x509.MarshalPKCS8PrivateKey(key)
+	os.WriteFile(filepath.Join(dir, "c.pem"), pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}), 0o600)
+	os.WriteFile(filepath.Join(dir, "k.pem"), pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: kd}), 0o600)
+	ln, _ := net.Listen("tcp", "127.0.0.1:0")
+	addr := ln.Addr().String()
+	ln.Close()
+	e := newEnv(t)
+	e.srv.cfg.Listen, e.srv.cfg.TLSCertFile, e.srv.cfg.TLSKeyFile = []string{addr}, filepath.Join(dir, "c.pem"), filepath.Join(dir, "k.pem")
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	ready := make(chan struct{})
+	go e.srv.Serve(ctx, func() { close(ready) })
+	<-ready
+	pool := x509.NewCertPool()
+	pool.AddCert(func() *x509.Certificate { c, _ := x509.ParseCertificate(der); return c }())
+	hc := &http.Client{Timeout: 5 * time.Second, Transport: &http.Transport{TLSClientConfig: &tls.Config{RootCAs: pool, ServerName: "dhcp.test"}}}
+	for _, url := range []string{"https://" + addr + "/healthz", "http://" + addr + "/healthz"} {
+		resp, err := hc.Get(url)
+		if err != nil {
+			t.Fatalf("%s: %v", url, err)
+		}
+		b, _ := io.ReadAll(resp.Body)
+		resp.Body.Close()
+		if resp.StatusCode != 200 || !strings.Contains(string(b), `"ok":true`) {
+			t.Errorf("%s: %d %s", url, resp.StatusCode, b)
+		}
+	}
+}