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/config/config.go

@@ -6,7 +6,9 @@ package config
 import (
 	"bytes"
 	"fmt"
+	"net"
 	"net/netip"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
@@ -31,12 +33,86 @@ type Config struct {
 	Log      Log     `yaml:"log"`
 	Session  Session `yaml:"session"`
 	Backup   Backup  `yaml:"backup"`
+	// Jarl is the Jarl server Steward uses for DNS (docs/jarl.md).
+	Jarl Jarl `yaml:"jarl"`
 }
 
-// TLS is a certificate for HTTPS.
+// TLS is the web UI's certificate: from files, or obtained through ACME
+// with Jarl publishing the DNS-01 challenge (docs/certificates.md).
 type TLS struct {
 	CertFile string `yaml:"cert_file"`
 	KeyFile  string `yaml:"key_file"`
+	ACME     ACME   `yaml:"acme"`
+}
+
+// ACME obtains the web UI's certificate (docs/certificates.md).
+type ACME struct {
+	// Domain is the certificate's name ("" turns ACME off).
+	Domain string `yaml:"domain"`
+	Email  string `yaml:"email"`
+	// Directory is letsencrypt, letsencrypt-staging (the default, for a
+	// first certificate browsers don't trust) or an ACME directory URL.
+	Directory string `yaml:"directory"`
+	// AgreeTOS says you accept the CA's terms of service; no account is
+	// registered without it.
+	AgreeTOS bool `yaml:"agree_tos"`
+	// Resolvers are public recursive resolvers, to see the challenge as
+	// the CA would.
+	Resolvers []string `yaml:"resolvers"`
+	// CheckPropagation also asks each of the zone's public name servers
+	// directly before the CA is told to look.
+	CheckPropagation bool `yaml:"check_propagation"`
+	// CABundle is a PEM file of extra CAs to trust for the ACME server
+	// (a private CA such as step-ca, or Pebble in tests).
+	CABundle string `yaml:"ca_bundle"`
+}
+
+// Directory URLs for the names tls.acme.directory accepts.
+const (
+	LetsEncrypt        = "https://acme-v02.api.letsencrypt.org/directory"
+	LetsEncryptStaging = "https://acme-staging-v02.api.letsencrypt.org/directory"
+)
+
+// DirectoryURL is the ACME directory's URL.
+func (a ACME) DirectoryURL() string {
+	switch a.Directory {
+	case "", "letsencrypt-staging":
+		return LetsEncryptStaging
+	case "letsencrypt":
+		return LetsEncrypt
+	}
+	return a.Directory
+}
+
+// Staging reports whether the directory is Let's Encrypt's staging one.
+func (a ACME) Staging() bool { return a.DirectoryURL() == LetsEncryptStaging }
+
+// Jarl is a Jarl server and an API token for it.
+type Jarl struct {
+	// Server is Jarl's URL ("" when Steward doesn't use Jarl).
+	Server string `yaml:"server"`
+	// Token, or TokenFile holding it (better: the file can be readable by
+	// the steward user alone).
+	Token     string `yaml:"token"`
+	TokenFile string `yaml:"token_file"`
+	// CACert is a PEM file with a CA to trust for Jarl's certificate.
+	CACert   string `yaml:"ca_cert"`
+	Insecure bool   `yaml:"insecure"`
+}
+
+// Enabled reports whether a Jarl server is configured.
+func (j Jarl) Enabled() bool { return j.Server != "" }
+
+// ReadToken returns the token, from the setting or the file.
+func (j Jarl) ReadToken() (string, error) {
+	if j.TokenFile == "" {
+		return j.Token, nil
+	}
+	b, err := os.ReadFile(j.TokenFile)
+	if err != nil {
+		return "", fmt.Errorf("jarl.token_file: %w", err)
+	}
+	return strings.TrimSpace(string(b)), nil
 }
 
 // Log configures logging to stderr (the journal under systemd).
@@ -102,6 +178,7 @@ func Default() *Config {
 		Log:            Log{Level: "info", Format: "text"},
 		Session:        Session{Lifetime: Duration(12 * time.Hour), IdleTimeout: Duration(2 * time.Hour), CookieSecure: "auto"},
 		Backup:         Backup{Dir: "/var/backups/steward", Retention: Duration(30 * 24 * time.Hour), KeepAtLeast: 7},
+		TLS:            TLS{ACME: ACME{Directory: "letsencrypt-staging", Resolvers: []string{"1.1.1.1:53", "9.9.9.9:53", "8.8.8.8:53"}, CheckPropagation: true}},
 	}
 }
 
@@ -140,6 +217,9 @@ func (c *Config) check() error {
 	if (c.TLS.CertFile == "") != (c.TLS.KeyFile == "") {
 		return fmt.Errorf("tls: set both cert_file and key_file")
 	}
+	if err := c.checkACME(); err != nil {
+		return err
+	}
 	for _, p := range c.TrustedProxies {
 		if _, err := ParsePrefix(p); err != nil {
 			return fmt.Errorf("trusted_proxies: %v", err)
@@ -169,6 +249,44 @@ func (c *Config) check() error {
 	return nil
 }
 
+func (c *Config) checkACME() error {
+	j := c.Jarl
+	if j.Server != "" {
+		if u, err := url.Parse(j.Server); err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
+			return fmt.Errorf("jarl.server %q: give Jarl's URL, e.g. https://dns.example.com:8053", j.Server)
+		}
+		if j.Token == "" && j.TokenFile == "" {
+			return fmt.Errorf("jarl: set token or token_file (a Jarl API token, docs/jarl.md)")
+		}
+		if j.Token != "" && j.TokenFile != "" {
+			return fmt.Errorf("jarl: set token or token_file, not both")
+		}
+	}
+	a := c.TLS.ACME
+	if a.Domain == "" {
+		return nil
+	}
+	if c.TLS.CertFile != "" {
+		return fmt.Errorf("tls: cert_file and acme can't both be set; choose one")
+	}
+	if !j.Enabled() {
+		return fmt.Errorf("tls.acme needs Jarl to publish the challenge: set jarl.server and its token (docs/certificates.md)")
+	}
+	d := strings.TrimSuffix(strings.ToLower(a.Domain), ".")
+	if strings.HasPrefix(d, "*.") || strings.Count(d, ".") < 1 || strings.ContainsAny(d, " /:") {
+		return fmt.Errorf("tls.acme.domain %q: give the full name the web UI is reached by, e.g. dhcp.example.com", a.Domain)
+	}
+	if u := a.DirectoryURL(); !strings.HasPrefix(u, "https://") {
+		return fmt.Errorf("tls.acme.directory %q: use letsencrypt, letsencrypt-staging or an https:// ACME directory URL", a.Directory)
+	}
+	for _, r := range a.Resolvers {
+		if _, _, err := net.SplitHostPort(r); err != nil {
+			return fmt.Errorf("tls.acme.resolvers: %q must be HOST:PORT, e.g. 1.1.1.1:53", r)
+		}
+	}
+	return nil
+}
+
 // ParsePrefix parses an address or a prefix.
 func ParsePrefix(s string) (netip.Prefix, error) {
 	if strings.Contains(s, "/") {
@@ -204,10 +322,37 @@ const Example = `# Steward daemon configuration (/etc/steward/steward.yaml).
 listen:
   - "127.0.0.1:8067"
 
-# HTTPS from a certificate you renew yourself (reread when it changes).
+# HTTPS for the web UI and API: a certificate from files you renew yourself
+# (reread when they change)...
 # tls:
 #   cert_file: /etc/steward/tls/fullchain.pem
 #   key_file: /etc/steward/tls/privkey.pem
+#
+# ...or one Steward obtains and renews itself from Let's Encrypt, with Jarl
+# publishing the DNS-01 challenge (needs jarl: below; docs/certificates.md).
+# Start with the staging directory: its certificate isn't trusted by
+# browsers, but it proves everything works without Let's Encrypt's rate
+# limits. Then set directory: letsencrypt.
+tls:
+  acme:
+    domain: ""                       # e.g. dhcp.example.com; "" is off
+    email: ""
+    directory: letsencrypt-staging   # letsencrypt, or an ACME directory URL
+    agree_tos: false                 # you accept the CA's terms of service
+    # Public resolvers, to see the challenge as the CA does.
+    resolvers: ["1.1.1.1:53", "9.9.9.9:53", "8.8.8.8:53"]
+    # Also ask the zone's public name servers directly.
+    check_propagation: true
+    ca_bundle: ""                    # extra CA for a private ACME server
+
+# Jarl, the BIND manager, for DNS records (docs/jarl.md). Give Steward a
+# token that may only write its challenge record; keep it in a file only
+# the steward user can read.
+# jarl:
+#   server: https://dns.example.com:8053
+#   token_file: /etc/steward/jarl.token
+#   ca_cert: ""                      # a CA to trust for Jarl's certificate
+#   insecure: false
 
 # Reverse proxies whose X-Forwarded-For and X-Forwarded-Proto are
 # believed.