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>

Author: sarg3nt

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

@@ -22,10 +22,14 @@ type Config struct {
 	// auto-generated self-signed certificate. Ignored when TLSCustom is
 	// true (the user-provided cert is used verbatim).
 	//
-	// The agent already includes "localhost", "127.0.0.1", "::1", and the
-	// container's os.Hostname() — TLSHosts is for the address the operator
-	// will actually point clients at (e.g. a static container IP, an FQDN
-	// behind a reverse proxy, or both).
+	// 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.

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

@@ -461,6 +461,29 @@ func TestLoadOrCreateTLSCert_RegenOnMissingSAN(t *testing.T) {
 	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 {

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

@@ -12,6 +12,7 @@ import (
 	"net"
 	"os"
 	"path/filepath"
+	"strings"
 	"time"
 )
 
@@ -130,6 +131,12 @@ func verifyCert(certPath string) error {
 // verifyCertCoversHosts loads the cert at certPath and confirms every entry
 // in `hosts` is present as a SAN (DNS name for hostnames, IPAddresses entry
 // for IPs). Returns nil if all hosts are covered.
+//
+// DNS comparison is case-insensitive per RFC 6125 §6.4 (TLS host matching),
+// so changing only the casing of an entry in HAPROXY_AGENT_TLS_HOSTS will
+// not force a spurious regeneration. A single trailing dot on FQDNs is also
+// stripped on both sides ("example.com." and "example.com" are equivalent
+// per DNS).
 func verifyCertCoversHosts(certPath string, hosts []string) error {
 	data, err := os.ReadFile(certPath)
 	if err != nil {
@@ -146,7 +153,7 @@ func verifyCertCoversHosts(certPath string, hosts []string) error {
 
 	dnsSet := make(map[string]struct{}, len(cert.DNSNames))
 	for _, d := range cert.DNSNames {
-		dnsSet[d] = struct{}{}
+		dnsSet[normaliseDNSName(d)] = struct{}{}
 	}
 	ipSet := make(map[string]struct{}, len(cert.IPAddresses))
 	for _, ip := range cert.IPAddresses {
@@ -160,13 +167,25 @@ func verifyCertCoversHosts(certPath string, hosts []string) error {
 			}
 			continue
 		}
-		if _, ok := dnsSet[h]; !ok {
+		if _, ok := dnsSet[normaliseDNSName(h)]; !ok {
 			return fmt.Errorf("certificate missing DNS SAN %s", h)
 		}
 	}
 	return nil
 }
 
+// normaliseDNSName lowercases and strips a single trailing dot so that
+// "Example.COM.", "example.com.", and "example.com" all compare equal.
+// DNS names are case-insensitive and the trailing dot is the
+// FQDN/relative distinction, not a real character.
+func normaliseDNSName(s string) string {
+	s = strings.ToLower(s)
+	if len(s) > 0 && s[len(s)-1] == '.' {
+		s = s[:len(s)-1]
+	}
+	return s
+}
+
 // generateSelfSignedCert creates a new self-signed TLS certificate and key.
 // The certificate is valid for 1 year and includes the specified hosts as SANs.
 func generateSelfSignedCert(certPath, keyPath string, hosts []string) error {