Release v1.0.2: companion HTTPS records for Technitium

maxfield-allison · maxfield-allison · commit b6e084b1817e · 2026-03-31T14:56:24.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-03-31
+
+### Added
+- **Companion HTTPS Records (Technitium)**: Auto-creates HTTPS (SVCB Type 65)
+  companion records alongside A/AAAA/CNAME records to prevent ECH fallback
+  errors in split-horizon DNS environments (#158)
+  - Enabled by default (`AUTO_HTTPS_RECORDS=true`); set `false` to disable
+  - Configurable ALPN protocol via `AUTO_HTTPS_ALPN` (default: `h2`)
+  - Skips creation if HTTPS record already exists (safe for manual records)
+  - Lifecycle-managed: companion record deleted when parent record is removed
+- **HTTPS Record Type**: Added `RecordTypeHTTPS` with `HTTPSData` struct to
+  provider type system
+- **ECH Troubleshooting**: FAQ entry for Firefox/Chrome ECH connection failures
+
+### Documentation
+- **Companion HTTPS Guide**: Full section in Technitium provider docs with
+  Why/What/Behavior/Configuration subsections
+- **Split-Horizon Tip**: Added companion HTTPS recommendation to split-horizon
+  deployment guide
+- **Config Example**: Added `auto_https_records` and `auto_https_alpn` to
+  example configuration file
+
 ## [1.0.1] - 2026-03-30
 
 ### Documentation
diff --git a/docs/config.example.yml b/docs/config.example.yml
@@ -117,6 +117,8 @@ providers:
       url: http://dns.example.com:5380
       token: ${TECHNITIUM_TOKEN}        # env var interpolation
       zone: internal.example.com
+      # auto_https_records: true          # Companion HTTPS records (enabled by default)
+      # auto_https_alpn: h2               # ALPN protocol for companion records
 
   # Public DNS using Cloudflare
   - name: public
diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md
@@ -136,7 +136,7 @@ Replace `{NAME}` with your instance name. For example, instance `internal-dns` u
 
 See the individual provider documentation for complete settings:
 
-- [Technitium](../providers/technitium.md)
+- [Technitium](../providers/technitium.md) — includes companion HTTPS record options
 - [Cloudflare](../providers/cloudflare.md)
 - [RFC 2136](../providers/rfc2136.md)
 - [Pi-hole](../providers/pihole.md)
diff --git a/docs/deployment/split-horizon.md b/docs/deployment/split-horizon.md
@@ -54,6 +54,9 @@ When container `app.example.com` starts:
 - Internal DNS → `A` record → `192.0.2.100`
 - External DNS → `CNAME` record → `tunnel.example.com`
 
+!!! tip "Companion HTTPS Records"
+    When using Technitium for internal DNS, dnsweaver automatically creates companion HTTPS (SVCB) records alongside A/CNAME records. This prevents ECH (Encrypted Client Hello) fallback errors that commonly occur in split-horizon setups where external DNS (e.g., Cloudflare) provides HTTPS records but internal DNS doesn't. See [Technitium — Companion HTTPS Records](../providers/technitium.md#companion-https-records) for details.
+
 ## Internal-Only Services
 
 Some services should only be accessible internally. Use exclusion patterns:
diff --git a/docs/faq.md b/docs/faq.md
@@ -173,6 +173,18 @@ Changes are logged but not applied to DNS providers.
 
 ## Troubleshooting
 
+### Firefox or Chrome fails to connect to internal services (ECH errors)
+
+Modern browsers use ECH (Encrypted Client Hello) when HTTPS records exist in public DNS. If your internal DNS zone lacks matching HTTPS records, browsers may fail with connection errors or experience delays.
+
+**Solution:** dnsweaver's Technitium provider automatically creates companion HTTPS records by default. If you've disabled this, re-enable it:
+
+```yaml
+- DNSWEAVER_TECHNITIUM_AUTO_HTTPS_RECORDS=true
+```
+
+See [Technitium — Companion HTTPS Records](providers/technitium.md#companion-https-records) for details.
+
 ### "No matching providers for hostname"
 
 The extracted hostname doesn't match any provider's domain patterns. Check:
diff --git a/docs/providers/technitium.md b/docs/providers/technitium.md
@@ -37,6 +37,8 @@ environment:
 | `EXCLUDE_DOMAINS` | No | - | Patterns to exclude |
 | `TTL` | No | `300` | Record TTL in seconds |
 | `INSECURE_SKIP_VERIFY` | No | `false` | Skip TLS certificate verification |
+| `AUTO_HTTPS_RECORDS` | No | `true` | Auto-create companion HTTPS records (see below) |
+| `AUTO_HTTPS_ALPN` | No | `h2` | ALPN protocol for companion HTTPS records |
 
 ## Getting an API Token
 
@@ -144,3 +146,48 @@ For self-signed certificates, either:
 ```yaml
 - DNSWEAVER_TECHNITIUM_INSECURE_SKIP_VERIFY=true
 ```
+
+## Companion HTTPS Records
+
+By default, dnsweaver automatically creates companion HTTPS (SVCB Type 65) records whenever it creates an A, AAAA, or CNAME record in Technitium. This prevents **ECH (Encrypted Client Hello) fallback errors** that commonly affect split-horizon DNS environments.
+
+### Why This Exists
+
+Modern browsers (Firefox 128+, Chrome 131+) use ECH to encrypt the SNI during TLS handshakes. When a public domain has HTTPS records (provided by CDNs like Cloudflare), but your internal DNS zone doesn't, browsers may fail to connect or experience delays trying to use ECH parameters that don't apply internally.
+
+The companion HTTPS record tells browsers "this host speaks HTTP/2 over TLS" without ECH, preventing the fallback error.
+
+### What Gets Created
+
+For each A/AAAA/CNAME record, dnsweaver creates:
+
+```
+app.example.com  300  IN  HTTPS  1 . alpn="h2"
+```
+
+- **Priority 1** (ServiceMode) — overrides any inherited ECH parameters
+- **Target `.`** (self) — the record's own hostname, per RFC 9460
+- **ALPN `h2`** — HTTP/2 over TLS (configurable)
+
+### Behavior
+
+- **Enabled by default** — no configuration needed
+- **Safe** — skips creation if an HTTPS record already exists (won't overwrite manual records)
+- **Lifecycle-managed** — companion records are deleted when the parent record is removed
+- **Idempotent** — duplicate creation attempts are handled gracefully
+
+### Configuration
+
+```yaml
+# Disable companion HTTPS records (not recommended for split-horizon setups)
+- DNSWEAVER_TECHNITIUM_AUTO_HTTPS_RECORDS=false
+
+# Change the ALPN protocol (default: h2)
+- DNSWEAVER_TECHNITIUM_AUTO_HTTPS_ALPN=h2,h3
+```
+
+!!! tip
+    If you use Cloudflare for external DNS and Technitium for internal DNS (a common split-horizon setup), companion HTTPS records are essential. Cloudflare provides HTTPS records automatically on their side — Technitium needs them too.
+
+!!! note
+    This feature only applies to the Technitium provider. Other providers either handle HTTPS records automatically (Cloudflare) or don't support them (Pi-hole, dnsmasq).
diff --git a/internal/config/validate.go b/internal/config/validate.go
@@ -139,6 +139,8 @@ func validateTargetRecordType(inst *ProviderInstanceConfig) []*ConfigError {
 		}
 	case provider.RecordTypeTXT, provider.RecordTypeSRV:
 		// Flexible targets, no validation needed
+	case provider.RecordTypeHTTPS:
+		// HTTPS records are managed automatically as companion records; no target validation needed
 	}
 
 	return errs
diff --git a/internal/reconciler/cache.go b/internal/reconciler/cache.go
@@ -77,7 +77,7 @@ func (c *recordCache) getExistingRecords(providerName, hostname string) ([]provi
 	var filtered []provider.Record
 	for _, r := range records {
 		switch r.Type {
-		case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV:
+		case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV, provider.RecordTypeHTTPS:
 			filtered = append(filtered, r)
 		case provider.RecordTypeTXT:
 			// Skip TXT records (ownership markers)
@@ -106,7 +106,7 @@ func (c *recordCache) getAllRecordsForHostname(providerName, hostname string) ([
 	var filtered []provider.Record
 	for _, r := range records {
 		switch r.Type {
-		case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV:
+		case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV, provider.RecordTypeHTTPS:
 			filtered = append(filtered, r)
 		case provider.RecordTypeTXT:
 			// Skip TXT records (ownership markers)
diff --git a/internal/reconciler/orphan.go b/internal/reconciler/orphan.go
@@ -364,7 +364,7 @@ func (r *Reconciler) deleteManagedForProvider(ctx context.Context, hostname stri
 		for _, rec := range allRecords {
 			if rec.Hostname == hostname {
 				switch rec.Type {
-				case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV:
+				case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV, provider.RecordTypeHTTPS:
 					recordsToDelete = append(recordsToDelete, rec)
 				case provider.RecordTypeTXT:
 					// Skip TXT records (ownership markers handled separately)
@@ -478,7 +478,7 @@ func (r *Reconciler) deleteCacheOnlyForProvider(ctx context.Context, hostname st
 		for _, rec := range allRecords {
 			if rec.Hostname == hostname {
 				switch rec.Type {
-				case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV:
+				case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV, provider.RecordTypeHTTPS:
 					recordsToDelete = append(recordsToDelete, rec)
 				case provider.RecordTypeTXT:
 					// Skip TXT records
diff --git a/internal/reconciler/orphan_legacy_test.go b/internal/reconciler/orphan_legacy_test.go
@@ -72,7 +72,7 @@ func (r *Reconciler) deleteFromCache(ctx context.Context, hostname string, cache
 			for _, rec := range allRecords {
 				if rec.Hostname == hostname {
 					switch rec.Type {
-					case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV:
+					case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV, provider.RecordTypeHTTPS:
 						recordsToDelete = append(recordsToDelete, rec)
 					case provider.RecordTypeTXT:
 						// Skip TXT records (ownership markers)
@@ -228,7 +228,7 @@ func (r *Reconciler) deleteWithOwnership(ctx context.Context, hostname string, c
 			for _, rec := range allRecords {
 				if rec.Hostname == hostname {
 					switch rec.Type {
-					case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV:
+					case provider.RecordTypeA, provider.RecordTypeAAAA, provider.RecordTypeCNAME, provider.RecordTypeSRV, provider.RecordTypeHTTPS:
 						recordsToDelete = append(recordsToDelete, rec)
 					case provider.RecordTypeTXT:
 						// Skip TXT records (ownership markers)
diff --git a/pkg/provider/instance.go b/pkg/provider/instance.go
@@ -228,7 +228,7 @@ func (pi *ProviderInstance) GetExistingRecords(ctx context.Context, hostname str
 		// Case-insensitive hostname comparison per RFC 1035 Section 2.3.3
 		if strings.EqualFold(r.Hostname, hostname) {
 			switch r.Type {
-			case RecordTypeA, RecordTypeAAAA, RecordTypeCNAME, RecordTypeSRV:
+			case RecordTypeA, RecordTypeAAAA, RecordTypeCNAME, RecordTypeSRV, RecordTypeHTTPS:
 				matching = append(matching, r)
 			case RecordTypeTXT:
 				// Skip TXT records (ownership markers)
diff --git a/pkg/provider/provider.go b/pkg/provider/provider.go
@@ -16,6 +16,7 @@ const (
 	RecordTypeCNAME RecordType = "CNAME"
 	RecordTypeTXT   RecordType = "TXT"
 	RecordTypeSRV   RecordType = "SRV"
+	RecordTypeHTTPS RecordType = "HTTPS"
 )
 
 // OwnershipPrefix is the default prefix for ownership TXT records.
@@ -138,6 +139,23 @@ type SRVData struct {
 	Port     uint16 // TCP/UDP port number (1-65535)
 }
 
+// HTTPSData contains HTTPS (SVCB Type 65) record-specific fields.
+// Used when Type is RecordTypeHTTPS.
+// See RFC 9460 for the HTTPS/SVCB record specification.
+type HTTPSData struct {
+	// Priority is the SvcPriority value. 0 = AliasMode, 1+ = ServiceMode.
+	// For ECH override records, typically 1.
+	Priority uint16
+
+	// TargetName is the SvcTargetName. "." means the record's owner name (self-referential).
+	// For ECH override records, typically ".".
+	TargetName string
+
+	// ALPN is the application-layer protocol negotiation value (e.g., "h2", "h3").
+	// Sent as svcParams "alpn|h2" in Technitium's API format.
+	ALPN string
+}
+
 // Record represents a DNS record to be managed.
 type Record struct {
 	Hostname   string
@@ -147,6 +165,9 @@ type Record struct {
 	ProviderID string   // Provider-specific record identifier
 	SRV        *SRVData // SRV-specific data (only set when Type is SRV)
 
+	// HTTPS holds HTTPS/SVCB record-specific data (only set when Type is HTTPS).
+	HTTPS *HTTPSData
+
 	// Metadata carries provider-specific key-value pairs through the reconciliation pipeline.
 	// Providers read actionable keys (e.g., "proxied" for Cloudflare) during Create/Update.
 	// nil means no metadata (Go zero value, non-breaking addition).
@@ -246,6 +267,19 @@ func RecordEquals(a, b Record) bool {
 			a.SRV.Port == b.SRV.Port
 	}
 
+	// For HTTPS records, also compare HTTPS-specific data
+	if a.Type == RecordTypeHTTPS {
+		if a.HTTPS == nil && b.HTTPS == nil {
+			return true
+		}
+		if a.HTTPS == nil || b.HTTPS == nil {
+			return false
+		}
+		return a.HTTPS.Priority == b.HTTPS.Priority &&
+			a.HTTPS.TargetName == b.HTTPS.TargetName &&
+			a.HTTPS.ALPN == b.HTTPS.ALPN
+	}
+
 	return true
 }
 
diff --git a/providers/technitium/client.go b/providers/technitium/client.go
@@ -34,8 +34,14 @@ type apiRData struct {
 	Weight    int    `json:"weight,omitempty"`   // For SRV records
 	Port      int    `json:"port,omitempty"`     // For SRV records
 	SrvTarget string `json:"target,omitempty"`   // For SRV records
+	// HTTPS/SVCB record fields
+	SvcPriority   int    `json:"svcPriority,omitempty"`   // For HTTPS/SVCB records
+	SvcTargetName string `json:"svcTargetName,omitempty"` // For HTTPS/SVCB records ("." = self)
+	SvcParams     string `json:"svcParams,omitempty"`     // For HTTPS/SVCB records (e.g., "alpn|h2")
 }
 
+// Note: older Technitium versions might represent svcParams differently; keep parsing flexible.
+
 // apiResponse is the standard Technitium API response wrapper.
 type apiResponse struct {
 	Status       string          `json:"status"`
@@ -426,6 +432,82 @@ func (c *Client) DeleteSRVRecord(ctx context.Context, zone, hostname string, pri
 	return nil
 }
 
+// AddHTTPSRecord creates an HTTPS (SVCB Type 65) record in the specified zone.
+// The svcPriority controls record mode: 0 = AliasMode, 1+ = ServiceMode.
+// The svcTargetName uses "." to indicate the record's owner name (self-referential).
+// The svcParams is in Technitium's pipe-separated format (e.g., "alpn|h2").
+func (c *Client) AddHTTPSRecord(ctx context.Context, zone, hostname string, svcPriority int, svcTargetName, svcParams string, ttl int) error {
+	params := url.Values{}
+	params.Set("zone", zone)
+	params.Set("domain", hostname)
+	params.Set("type", "HTTPS")
+	params.Set("svcPriority", strconv.Itoa(svcPriority))
+	params.Set("svcTargetName", svcTargetName)
+	params.Set("svcParams", svcParams)
+	params.Set("ttl", strconv.Itoa(ttl))
+
+	_, err := c.doRequest(ctx, "/api/zones/records/add", params)
+	if err != nil {
+		return fmt.Errorf("adding HTTPS record for %s: %w", hostname, err)
+	}
+
+	c.logger.Info("added HTTPS record",
+		slog.String("hostname", hostname),
+		slog.Int("svc_priority", svcPriority),
+		slog.String("svc_target", svcTargetName),
+		slog.String("svc_params", svcParams),
+		slog.String("zone", zone),
+		slog.Int("ttl", ttl),
+	)
+
+	return nil
+}
+
+// DeleteHTTPSRecord removes an HTTPS (SVCB Type 65) record from the specified zone.
+// Note: implemented earlier; duplicate guard to ensure compile stability when patching.
+
+// parseSvcParams splits svcParams into key/value pairs for future use.
+// Input: "alpn|h2" → map{"alpn":"h2"}
+func parseSvcParams(s string) map[string]string {
+	out := make(map[string]string)
+	for _, part := range strings.Split(s, " ") {
+		if part == "" {
+			continue
+		}
+		kv := strings.SplitN(part, "|", 2)
+		if len(kv) == 2 {
+			out[kv[0]] = kv[1]
+		}
+	}
+	return out
+}
+
+// DeleteHTTPSRecord removes an HTTPS (SVCB Type 65) record from the specified zone.
+func (c *Client) DeleteHTTPSRecord(ctx context.Context, zone, hostname string, svcPriority int, svcTargetName, svcParams string) error {
+	params := url.Values{}
+	params.Set("zone", zone)
+	params.Set("domain", hostname)
+	params.Set("type", "HTTPS")
+	params.Set("svcPriority", strconv.Itoa(svcPriority))
+	params.Set("svcTargetName", svcTargetName)
+	params.Set("svcParams", svcParams)
+
+	_, err := c.doRequest(ctx, "/api/zones/records/delete", params)
+	if err != nil {
+		return fmt.Errorf("deleting HTTPS record for %s: %w", hostname, err)
+	}
+
+	c.logger.Info("deleted HTTPS record",
+		slog.String("hostname", hostname),
+		slog.Int("svc_priority", svcPriority),
+		slog.String("svc_target", svcTargetName),
+		slog.String("svc_params", svcParams),
+		slog.String("zone", zone),
+	)
+
+	return nil
+}
+
 // UpdateARecord updates an A record's target IP address in the specified zone.
 // The Technitium API requires the old IP to identify the record.
 func (c *Client) UpdateARecord(ctx context.Context, zone, hostname, oldIP, newIP string, ttl int) error {
diff --git a/providers/technitium/client_test.go b/providers/technitium/client_test.go
diff --git a/providers/technitium/companion.go b/providers/technitium/companion.go
diff --git a/providers/technitium/companion_test.go b/providers/technitium/companion_test.go
diff --git a/providers/technitium/config.go b/providers/technitium/config.go
diff --git a/providers/technitium/provider.go b/providers/technitium/provider.go

Original file line number	Diff line number	Diff line change
`@@ -139,6 +139,8 @@ func validateTargetRecordType(inst ProviderInstanceConfig) []ConfigError {`
`139`	`139`	`}`
`140`	`140`	`case provider.RecordTypeTXT, provider.RecordTypeSRV:`
`141`	`141`	`// Flexible targets, no validation needed`
	`142`	`+ case provider.RecordTypeHTTPS:`
	`143`	`+ // HTTPS records are managed automatically as companion records; no target validation needed`
`142`	`144`	`}`
`143`	`145`
`144`	`146`	`return errs`