feat(agent): HAPROXY_AGENT_TLS_HOSTS for self-signed cert SANs (#110)

* feat(agent): HAPROXY_AGENT_TLS_HOSTS for self-signed cert SANs

The agent auto-generates a self-signed cert covering only localhost,
127.0.0.1, ::1 and a random container hostname. Clients reaching the
agent by a static container IP (e.g. the homelab gearbox-agent at
172.16.2.3) hit cert-verification failures — the previous workaround
was disabling TLS verification on the dashboard side.

HAPROXY_AGENT_TLS_HOSTS accepts a comma-separated list of extra SANs
that get baked into the auto-generated cert. LoadOrCreateTLSCert now
also regenerates the cert when an existing one is missing a requested
SAN, so adding a host to the env var takes effect on the next restart
with no manual cleanup. Dropped the os.Hostname() auto-SAN — in a
container it's a random short ID that changes per recreation and would
trigger needless regen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* address Copilot review: stale doc comment + case-insensitive DNS SAN match

- config.go: TLSHosts doc no longer claims os.Hostname() is auto-added;
  explains why we explicitly skip it (random container ID forces regen).
- tls.go: verifyCertCoversHosts now lowercases DNS SANs and strips a
  trailing dot on both sides before comparison. Per RFC 6125 §6.4 DNS
  host matching is case-insensitive, so "Example.COM." and "example.com"
  must compare equal — otherwise a casing-only env-var edit would force
  a spurious cert regeneration. IP comparison is unchanged.
- crypto_test.go: extends TestLoadOrCreateTLSCert_RegenOnMissingSAN with
  two new assertions covering the casing and trailing-dot equivalences.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sarg3nt

gearbox-agent/README.md

@@ -178,8 +178,19 @@ HAPROXY_AGENT_LOG_LEVEL=info  # debug, info, warn, error
 # TLS (optional - uses self-signed if not set)
 HAPROXY_AGENT_TLS_CERT=/etc/haproxy/certs/sarg3.net.fullchain.crt
 HAPROXY_AGENT_TLS_KEY=/etc/haproxy/certs/sarg3.net.key
+
+# Extra SANs for the auto-generated self-signed cert. Comma-separated list
+# of hostnames and/or IPs that clients will use to reach this agent. Ignored
+# when a custom cert is configured above. Loopback (localhost / 127.0.0.1 /
+# ::1) is always covered automatically.
+HAPROXY_AGENT_TLS_HOSTS=mjolnir,172.16.2.3,agent.example.com
 ```
 
+> [!NOTE]
+> The agent regenerates the self-signed cert automatically when
+> `HAPROXY_AGENT_TLS_HOSTS` changes (adding a SAN that the existing cert
+> does not cover). No manual cleanup required.
+
 ### Git Sync
 
 ```bash

gearbox-agent/cmd/gearbox-agent/main.go

@@ -219,20 +219,24 @@ func main() {
 		}
 		logger.Info("TLS: Using custom certificate", "path", tlsCfg.CertPath)
 	} else {
-		// Use self-signed certs (generate if needed)
-		hosts := []string{"localhost"}
-		if hostname, err := os.Hostname(); err == nil {
-			hosts = append(hosts, hostname)
-		}
-
+		// Use self-signed certs (generate if needed). The generator
+		// always covers loopback (localhost / 127.0.0.1 / ::1); anything
+		// else clients will dial — a static container IP, an FQDN, a
+		// LAN hostname — must come from HAPROXY_AGENT_TLS_HOSTS.
+		//
+		// We deliberately do NOT add os.Hostname() here: in a container
+		// it's a random short ID that changes on every recreation,
+		// which would force a cert regen each restart for no value.
+		// Operators who want a specific hostname pin it explicitly.
 		var isNewCert bool
-		tlsCfg, isNewCert, err = crypto.LoadOrCreateTLSCert(cfg.TLSCert, cfg.TLSKey, hosts)
+		tlsCfg, isNewCert, err = crypto.LoadOrCreateTLSCert(cfg.TLSCert, cfg.TLSKey, cfg.TLSHosts)
 		if err != nil {
 			logger.Error("Failed to initialize TLS", "error", err)
 			os.Exit(1)
 		}
 		if isNewCert {
-			logger.Info("TLS: Generated new self-signed certificate (valid for 1 year)")
+			logger.Info("TLS: Generated new self-signed certificate (valid for 1 year)",
+				"extra_sans", cfg.TLSHosts)
 		} else {
 			logger.Info("TLS: Using existing self-signed certificate", "path", tlsCfg.CertPath)
 		}

gearbox-agent/docs/docker.md

@@ -240,7 +240,19 @@ docker run -d \
 
 #### Option 1: Self-signed (Default)
 
-The agent automatically generates self-signed certificates on first run. No configuration needed.
+The agent automatically generates self-signed certificates on first run. The cert covers loopback (`localhost`, `127.0.0.1`, `::1`) out of the box, which is enough when clients reach the agent over `localhost` (e.g. host-network containers, or the host itself).
+
+If clients dial the agent by a static container IP, an FQDN, or a LAN hostname, add those as extra SANs via `HAPROXY_AGENT_TLS_HOSTS`:
+
+```yaml
+services:
+  gearbox-agent:
+    environment:
+      # Comma-separated list of hostnames and/or IPs to include as SANs.
+      - HAPROXY_AGENT_TLS_HOSTS=mjolnir,172.16.2.3,agent.example.com
+```
+
+The agent regenerates the self-signed cert automatically when this list changes (adding a SAN the existing cert does not cover).
 
 #### Option 2: Custom Certificates
 

gearbox-agent/internal/framework/config/config.go

@@ -18,6 +18,23 @@ type Config struct {
 	TLSKey     string
 	TLSCustom  bool // True if user provided custom TLS cert paths
 
+	// TLSHosts are additional hostnames / IPs to include as SANs in the
+	// auto-generated self-signed certificate. Ignored when TLSCustom is
+	// true (the user-provided cert is used verbatim).
+	//
+	// The cert generator always covers "localhost", "127.0.0.1", and
+	// "::1"; TLSHosts is for any other address clients will actually
+	// dial (e.g. a static container IP, an FQDN behind a reverse proxy,
+	// or both). The container's os.Hostname() is deliberately NOT added
+	// automatically — in a container it's a random short ID that
+	// changes per recreation, which would force needless cert
+	// regeneration since LoadOrCreateTLSCert regenerates when the
+	// existing cert is missing a requested SAN.
+	//
+	// Parsed from HAPROXY_AGENT_TLS_HOSTS as a comma-separated list;
+	// whitespace around each entry is trimmed, empty entries are dropped.
+	TLSHosts []string
+
 	// API key settings
 	APIKeyPath string
 
@@ -155,6 +172,7 @@ func Load() (*Config, error) {
 	} else {
 		cfg.TLSKey = cfg.DataDir + "/tls/server.key"
 	}
+	cfg.TLSHosts = parseCommaList(os.Getenv("HAPROXY_AGENT_TLS_HOSTS"))
 	cfg.APIKeyPath = getEnvOrDefault("HAPROXY_AGENT_API_KEY_PATH", cfg.DataDir+"/api-key")
 
 	// Logging
@@ -278,6 +296,26 @@ func (c *Config) Validate() error {
 	return nil
 }
 
+// parseCommaList splits a comma-separated env value into a clean slice:
+// each entry is trimmed of surrounding whitespace and empty entries are
+// dropped. Returns nil for an empty/whitespace-only input.
+func parseCommaList(raw string) []string {
+	if strings.TrimSpace(raw) == "" {
+		return nil
+	}
+	parts := strings.Split(raw, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if v := strings.TrimSpace(p); v != "" {
+			out = append(out, v)
+		}
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
 func getEnvOrDefault(key, defaultValue string) string {
 	if v := os.Getenv(key); v != "" {
 		return v

gearbox-agent/internal/framework/config/config_test.go

@@ -220,6 +220,55 @@ func TestLoad_CustomTLS(t *testing.T) {
 	}
 }
 
+func TestLoad_TLSHosts(t *testing.T) {
+	tests := []struct {
+		name     string
+		envValue string
+		want     []string
+	}{
+		{"unset", "", nil},
+		{"whitespace only", "   ", nil},
+		{"single host", "mjolnir", []string{"mjolnir"}},
+		{"comma separated", "mjolnir,10.0.0.1,agent.local", []string{"mjolnir", "10.0.0.1", "agent.local"}},
+		{"trims surrounding whitespace", " mjolnir , 10.0.0.1 ", []string{"mjolnir", "10.0.0.1"}},
+		{"drops empty entries", "mjolnir,,10.0.0.1,", []string{"mjolnir", "10.0.0.1"}},
+	}
+
+	saved := os.Getenv("HAPROXY_AGENT_TLS_HOSTS")
+	defer func() {
+		if saved != "" {
+			os.Setenv("HAPROXY_AGENT_TLS_HOSTS", saved)
+		} else {
+			os.Unsetenv("HAPROXY_AGENT_TLS_HOSTS")
+		}
+	}()
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.envValue == "" {
+				os.Unsetenv("HAPROXY_AGENT_TLS_HOSTS")
+			} else {
+				os.Setenv("HAPROXY_AGENT_TLS_HOSTS", tt.envValue)
+			}
+
+			cfg, err := Load()
+			if err != nil {
+				t.Fatalf("Load() error = %v", err)
+			}
+
+			if len(cfg.TLSHosts) != len(tt.want) {
+				t.Fatalf("TLSHosts = %v (len %d), want %v (len %d)",
+					cfg.TLSHosts, len(cfg.TLSHosts), tt.want, len(tt.want))
+			}
+			for i, v := range tt.want {
+				if cfg.TLSHosts[i] != v {
+					t.Errorf("TLSHosts[%d] = %q, want %q", i, cfg.TLSHosts[i], v)
+				}
+			}
+		})
+	}
+}
+
 func TestValidate(t *testing.T) {
 	tests := []struct {
 		name    string

gearbox-agent/internal/framework/crypto/crypto_test.go

@@ -1,6 +1,9 @@
 package crypto
 
 import (
+	"crypto/x509"
+	"encoding/pem"
+	"net"
 	"os"
 	"path/filepath"
 	"testing"
@@ -386,8 +389,134 @@ func TestGenerateSelfSignedCert_IncludesHosts(t *testing.T) {
 		t.Fatalf("LoadOrCreateTLSCert() error = %v", err)
 	}
 
-	// Verify the cert can be parsed (basic validation)
-	if err := verifyCertReadable(certPath); err != nil {
-		t.Errorf("Generated cert is not readable: %v", err)
+	cert := loadCertForTest(t, certPath)
+
+	// Requested SANs must be present.
+	if !containsString(cert.DNSNames, "example.com") {
+		t.Errorf("cert DNSNames missing example.com: %v", cert.DNSNames)
+	}
+	if !containsIPString(cert.IPAddresses, "192.168.1.1") {
+		t.Errorf("cert IPAddresses missing 192.168.1.1: %v", cert.IPAddresses)
+	}
+
+	// Loopback SANs are always added.
+	if !containsString(cert.DNSNames, "localhost") {
+		t.Errorf("cert DNSNames missing localhost: %v", cert.DNSNames)
+	}
+	if !containsIPString(cert.IPAddresses, "127.0.0.1") {
+		t.Errorf("cert IPAddresses missing 127.0.0.1: %v", cert.IPAddresses)
+	}
+	if !containsIPString(cert.IPAddresses, "::1") {
+		t.Errorf("cert IPAddresses missing ::1: %v", cert.IPAddresses)
+	}
+}
+
+// TestLoadOrCreateTLSCert_RegenOnMissingSAN verifies that a previously
+// generated cert is regenerated when LoadOrCreateTLSCert is called with a
+// host that the existing cert does not cover. Without this behaviour an
+// operator who adds a new entry to HAPROXY_AGENT_TLS_HOSTS would have to
+// manually wipe the cert file before the change takes effect.
+func TestLoadOrCreateTLSCert_RegenOnMissingSAN(t *testing.T) {
+	tmpDir := t.TempDir()
+	certPath := filepath.Join(tmpDir, "server.crt")
+	keyPath := filepath.Join(tmpDir, "server.key")
+
+	// Initial cert covers example.com only.
+	_, isNew, err := LoadOrCreateTLSCert(certPath, keyPath, []string{"example.com"})
+	if err != nil {
+		t.Fatalf("initial LoadOrCreateTLSCert() error = %v", err)
+	}
+	if !isNew {
+		t.Fatal("initial call should report isNew = true")
+	}
+	originalSerial := loadCertForTest(t, certPath).SerialNumber.String()
+
+	// Same hosts → reuse, no regen.
+	_, isNew, err = LoadOrCreateTLSCert(certPath, keyPath, []string{"example.com"})
+	if err != nil {
+		t.Fatalf("second LoadOrCreateTLSCert() error = %v", err)
+	}
+	if isNew {
+		t.Error("call with same hosts should report isNew = false")
+	}
+	if loadCertForTest(t, certPath).SerialNumber.String() != originalSerial {
+		t.Error("cert serial changed despite same hosts (unexpected regeneration)")
+	}
+
+	// New host added → regenerate.
+	_, isNew, err = LoadOrCreateTLSCert(certPath, keyPath, []string{"example.com", "172.16.2.3"})
+	if err != nil {
+		t.Fatalf("third LoadOrCreateTLSCert() error = %v", err)
+	}
+	if !isNew {
+		t.Fatal("call with added host should report isNew = true")
+	}
+	regenerated := loadCertForTest(t, certPath)
+	if regenerated.SerialNumber.String() == originalSerial {
+		t.Error("cert serial unchanged after adding new host (regeneration did not happen)")
+	}
+	if !containsIPString(regenerated.IPAddresses, "172.16.2.3") {
+		t.Errorf("regenerated cert missing 172.16.2.3 SAN: %v", regenerated.IPAddresses)
+	}
+	if !containsString(regenerated.DNSNames, "example.com") {
+		t.Errorf("regenerated cert lost example.com SAN: %v", regenerated.DNSNames)
+	}
+	regeneratedSerial := regenerated.SerialNumber.String()
+
+	// Casing change on the same DNS name → reuse, no spurious regen
+	// (RFC 6125 §6.4: DNS host matching is case-insensitive).
+	_, isNew, err = LoadOrCreateTLSCert(certPath, keyPath, []string{"EXAMPLE.com", "172.16.2.3"})
+	if err != nil {
+		t.Fatalf("fourth LoadOrCreateTLSCert() error = %v", err)
+	}
+	if isNew {
+		t.Error("call differing only in DNS casing should not regenerate")
+	}
+	if loadCertForTest(t, certPath).SerialNumber.String() != regeneratedSerial {
+		t.Error("cert serial changed across casing-only difference (unexpected regeneration)")
+	}
+
+	// Trailing-dot equivalence (example.com. == example.com per DNS).
+	_, isNew, err = LoadOrCreateTLSCert(certPath, keyPath, []string{"example.com.", "172.16.2.3"})
+	if err != nil {
+		t.Fatalf("fifth LoadOrCreateTLSCert() error = %v", err)
+	}
+	if isNew {
+		t.Error("trailing-dot variant should not regenerate")
+	}
+}
+
+func loadCertForTest(t *testing.T, certPath string) *x509.Certificate {
+	t.Helper()
+	data, err := os.ReadFile(certPath)
+	if err != nil {
+		t.Fatalf("read cert: %v", err)
+	}
+	block, _ := pem.Decode(data)
+	if block == nil {
+		t.Fatal("failed to decode cert PEM")
+	}
+	cert, err := x509.ParseCertificate(block.Bytes)
+	if err != nil {
+		t.Fatalf("parse cert: %v", err)
+	}
+	return cert
+}
+
+func containsString(haystack []string, needle string) bool {
+	for _, v := range haystack {
+		if v == needle {
+			return true
+		}
+	}
+	return false
+}
+
+func containsIPString(haystack []net.IP, needle string) bool {
+	for _, ip := range haystack {
+		if ip.String() == needle {
+			return true
+		}
 	}
+	return false
 }