feat: support DNS Stamp upstream format (#1922)

Author: 0xERR0R

.golangci.yml

@@ -78,6 +78,7 @@ linters:
     - forbidigo
     - gosmopolitan
     - recvcheck
+    - wrapcheck
   settings:
     ginkgolinter:
       forbid-focus-container: true
@@ -113,6 +114,7 @@ linters:
           - gosec
           - forcetypeassert
           - wrapcheck
+          - lll
         path: _test\.go
       - linters:
           - staticcheck

cache/stringcache/string_caches_benchmark_test.go

@@ -68,7 +68,6 @@ func init() {
 // Most memory efficient: Wildcard (blocky/trie    radix) because of peak
 // Fastest:               Wildcard (blocky/trie original)
 //
-//nolint:lll
 // BenchmarkRegexFactory-8                1     1 253 023 507 ns/op   430.60 fact_heap_MB   430.60 peak_heap_MB   1 792 669 024 B/op   9 826 986 allocs/op
 // BenchmarkStringFactory-8               7       163 969 933 ns/op    11.79 fact_heap_MB    26.91 peak_heap_MB      67 613 890 B/op       1 306 allocs/op
 // BenchmarkWildcardFactory-8            19        60 592 988 ns/op    16.60 fact_heap_MB    16.60 peak_heap_MB      26 740 317 B/op      92 245 allocs/op (original)
@@ -131,7 +130,6 @@ func benchmarkFactory(b *testing.B, data []string, newFactory func() cacheFactor
 // Most memory efficient: Wildcard (blocky/trie radix)
 // Fastest:               Wildcard (blocky/trie original)
 //
-//nolint:lll
 // BenchmarkStringCache-8                 6       204 754 798 ns/op    15.11 cache_heap_MB              0 B/op          0 allocs/op
 // BenchmarkWildcardCache-8              14        76 186 334 ns/op    16.61 cache_heap_MB              0 B/op          0 allocs/op (original)
 // BenchmarkWildcardCache-8              12        95 316 121 ns/op    14.91 cache_heap_MB              0 B/op          0 allocs/op (radix)

config/config_test.go

@@ -955,6 +955,163 @@ bootstrapDns:
 			Expect(hook.Messages).ShouldNot(ContainElement(ContainSubstring("deprecated")))
 		})
 	})
+
+	Describe("DNS Stamp Upstreams", func() {
+		When("Config contains DNS stamps", func() {
+			It("should parse DNS stamp upstreams correctly", func() {
+				confFile := tmpDir.CreateStringFile("config.yml",
+					"upstreams:",
+					"  groups:",
+					"    default:",
+					"      - sdns://AgcAAAAAAAAABzEuMC4wLjGgENk8mGSlIfMGXMOlIlCcKvq7AVgcrZxtjon911-ep0cg63Ul-I8NlFj4GplQGb_TTLiczclX57DvMV8Q-JdjgRgSZG5zLmNsb3VkZmxhcmUuY29tCi9kbnMtcXVlcnk", // Cloudflare DoH
+					"      - sdns://AAcAAAAAAAAABzguOC44Ljg", // Google DNS Plain
+				)
+
+				c, err = LoadConfig(confFile.Path, true)
+				Expect(err).Should(Succeed())
+
+				// Verify default group
+				defaultUpstreams := c.Upstreams.Groups["default"]
+				Expect(defaultUpstreams).Should(HaveLen(2))
+
+				// Verify Cloudflare DoH
+				Expect(defaultUpstreams[0].Net).Should(Equal(NetProtocolHttps))
+				Expect(defaultUpstreams[0].Host).Should(Equal("dns.cloudflare.com"))
+				Expect(defaultUpstreams[0].Port).Should(Equal(uint16(443)))
+				Expect(defaultUpstreams[0].Path).Should(Equal("/dns-query"))
+				Expect(defaultUpstreams[0].CommonName).Should(Equal("dns.cloudflare.com"))
+				Expect(defaultUpstreams[0].CertificateFingerprints).ShouldNot(BeEmpty())
+
+				// Verify Google Plain DNS
+				Expect(defaultUpstreams[1].Net).Should(Equal(NetProtocolTcpUdp))
+				Expect(defaultUpstreams[1].Host).Should(Equal("8.8.8.8"))
+				Expect(defaultUpstreams[1].Port).Should(Equal(uint16(53)))
+			})
+
+			It("should support mixed DNS stamp and traditional format", func() {
+				confFile := tmpDir.CreateStringFile("config.yml",
+					"upstreams:",
+					"  groups:",
+					"    default:",
+					"      - 8.8.8.8",                        // Traditional
+					"      - https://dns.google/dns-query",   // Traditional DoH
+					"      - sdns://AAcAAAAAAAAABzguOC44Ljg", // DNS Stamp
+					"      - sdns://AgcAAAAAAAAABzEuMC4wLjGgENk8mGSlIfMGXMOlIlCcKvq7AVgcrZxtjon911-ep0cg63Ul-I8NlFj4GplQGb_TTLiczclX57DvMV8Q-JdjgRgSZG5zLmNsb3VkZmxhcmUuY29tCi9kbnMtcXVlcnk", // DNS Stamp DoH
+				)
+
+				c, err = LoadConfig(confFile.Path, true)
+				Expect(err).Should(Succeed())
+
+				defaultUpstreams := c.Upstreams.Groups["default"]
+				Expect(defaultUpstreams).Should(HaveLen(4))
+
+				// All should be parsed correctly
+				Expect(defaultUpstreams[0].Host).Should(Equal("8.8.8.8"))
+				Expect(defaultUpstreams[0].Net).Should(Equal(NetProtocolTcpUdp))
+
+				Expect(defaultUpstreams[1].Host).Should(Equal("dns.google"))
+				Expect(defaultUpstreams[1].Net).Should(Equal(NetProtocolHttps))
+
+				Expect(defaultUpstreams[2].Host).Should(Equal("8.8.8.8"))
+				Expect(defaultUpstreams[2].Net).Should(Equal(NetProtocolTcpUdp))
+
+				Expect(defaultUpstreams[3].Host).Should(Equal("dns.cloudflare.com"))
+				Expect(defaultUpstreams[3].Net).Should(Equal(NetProtocolHttps))
+			})
+
+			It("should reject unsupported protocol in DNS stamp", func() {
+				confFile := tmpDir.CreateStringFile("config.yml",
+					"upstreams:",
+					"  groups:",
+					"    default:",
+					"      - sdns://AQMAAAAAAAAAETk0Ljc2Ljc2LjE6ODQ0MyAK-Y3YBV0rO9yqiOWp6OMQNvPPRMfOqCvQV7C8BmOW6hnSZG5zY3J5cHQuZGU", // DNSCrypt
+				)
+
+				_, err = LoadConfig(confFile.Path, true)
+				Expect(err).Should(HaveOccurred())
+				// May fail with various error messages depending on stamp validity
+			})
+
+			It("should reject invalid DNS stamp", func() {
+				confFile := tmpDir.CreateStringFile("config.yml",
+					"upstreams:",
+					"  groups:",
+					"    default:",
+					"      - sdns://invalid!!!", // Invalid stamp
+				)
+
+				_, err = LoadConfig(confFile.Path, true)
+				Expect(err).Should(HaveOccurred())
+			})
+
+			It("should preserve certificate fingerprints from DNS stamps", func() {
+				confFile := tmpDir.CreateStringFile("config.yml",
+					"upstreams:",
+					"  groups:",
+					"    default:",
+					"      - sdns://AgcAAAAAAAAABzEuMC4wLjGgENk8mGSlIfMGXMOlIlCcKvq7AVgcrZxtjon911-ep0cg63Ul-I8NlFj4GplQGb_TTLiczclX57DvMV8Q-JdjgRgSZG5zLmNsb3VkZmxhcmUuY29tCi9kbnMtcXVlcnk", // Cloudflare with certs
+				)
+
+				c, err = LoadConfig(confFile.Path, true)
+				Expect(err).Should(Succeed())
+
+				upstream := c.Upstreams.Groups["default"][0]
+				Expect(upstream.CertificateFingerprints).Should(HaveLen(2))
+
+				// Each fingerprint should be 32 bytes (SHA256)
+				for _, fp := range upstream.CertificateFingerprints {
+					Expect(fp).Should(HaveLen(32))
+				}
+			})
+
+			It("should handle IPv6 in DNS stamps", func() {
+				confFile := tmpDir.CreateStringFile("config.yml",
+					"upstreams:",
+					"  groups:",
+					"    default:",
+					"      - sdns://AAcAAAAAAAAAKVsyMDAxOjBkYjg6ODVhMzowMDAwOjAwMDA6OGEyZTowMzcwOjczMzRd",
+				)
+
+				c, err = LoadConfig(confFile.Path, true)
+				Expect(err).Should(Succeed())
+
+				upstream := c.Upstreams.Groups["default"][0]
+
+				// All should be parsed correctly
+				Expect(upstream.Host).Should(Equal("2001:0db8:85a3:0000:0000:8a2e:0370:7334"))
+				Expect(upstream.Net).Should(Equal(NetProtocolTcpUdp))
+			})
+		})
+
+		When("Config uses conditional upstream with DNS stamps", func() {
+			It("should parse DNS stamps in conditional mapping", func() {
+				confFile := tmpDir.CreateStringFile("config.yml",
+					"upstreams:",
+					"  groups:",
+					"    default:",
+					"      - 8.8.8.8",
+					"conditional:",
+					"  mapping:",
+					"    example.com: sdns://AgcAAAAAAAAABzEuMC4wLjGgENk8mGSlIfMGXMOlIlCcKvq7AVgcrZxtjon911-ep0cg63Ul-I8NlFj4GplQGb_TTLiczclX57DvMV8Q-JdjgRgSZG5zLmNsb3VkZmxhcmUuY29tCi9kbnMtcXVlcnk",
+					"    test.com: 1.1.1.1", // Traditional format
+				)
+
+				c, err = LoadConfig(confFile.Path, true)
+				Expect(err).Should(Succeed())
+
+				// Verify conditional mapping parsed DNS stamp
+				exampleUpstreams := c.Conditional.Mapping.Upstreams["example.com"]
+				Expect(exampleUpstreams).Should(HaveLen(1))
+				Expect(exampleUpstreams[0].Host).Should(Equal("dns.cloudflare.com"))
+				Expect(exampleUpstreams[0].Net).Should(Equal(NetProtocolHttps))
+
+				// Verify traditional format still works
+				testUpstreams := c.Conditional.Mapping.Upstreams["test.com"]
+				Expect(testUpstreams).Should(HaveLen(1))
+				Expect(testUpstreams[0].Host).Should(Equal("1.1.1.1"))
+			})
+		})
+	})
 })
 
 func defaultTestFileConfig(config *Config) {

config/upstream.go

@@ -1,28 +1,38 @@
 package config
 
 import (
+	"errors"
 	"fmt"
 	"net"
 	"regexp"
 	"strconv"
 	"strings"
+
+	"github.com/jedisct1/go-dnsstamps"
 )
 
 var validDomain = regexp.MustCompile(
 	`^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])$`)
 
+// CertificateFingerprint represents a SHA256 fingerprint of a TLS certificate (32 bytes)
+type CertificateFingerprint []byte
+
 // Upstream is the definition of external DNS server
 type Upstream struct {
 	Net        NetProtocol
 	Host       string
 	Port       uint16
 	Path       string
 	CommonName string // Common Name to use for certificate verification; optional. "" uses .Host
+
+	// DNS stamp metadata (optional) - only populated when parsing DNS stamps
+	CertificateFingerprints []CertificateFingerprint // SHA256 fingerprints for TLS certificate pinning
 }
 
 // IsDefault returns true if u is the default value
 func (u *Upstream) IsDefault() bool {
-	return *u == Upstream{}
+	return u.Net == 0 && u.Host == "" && u.Port == 0 && u.Path == "" &&
+		u.CommonName == "" && len(u.CertificateFingerprints) == 0
 }
 
 // String returns the string representation of u
@@ -76,7 +86,14 @@ func (u *Upstream) UnmarshalText(data []byte) error {
 }
 
 // ParseUpstream creates new Upstream from passed string in format [net]:host[:port][/path][#commonname]
+// or DNS Stamp format: sdns://...
 func ParseUpstream(upstream string) (Upstream, error) {
+	// Check if it's a DNS stamp
+	if isDNSStamp(upstream) {
+		return parseStamp(upstream)
+	}
+
+	// Existing parsing logic for traditional format
 	var path string
 
 	var port uint16
@@ -163,3 +180,115 @@ func extractNet(upstream string) (NetProtocol, string) {
 
 	return NetProtocolTcpUdp, upstream
 }
+
+// isDNSStamp checks if a string is a DNS stamp format
+func isDNSStamp(s string) bool {
+	return strings.HasPrefix(s, "sdns://")
+}
+
+// parseStamp parses a DNS stamp and converts it to an Upstream
+func parseStamp(stampStr string) (Upstream, error) {
+	stamp, err := dnsstamps.NewServerStampFromString(stampStr)
+	if err != nil {
+		return Upstream{}, fmt.Errorf("invalid DNS stamp: %w", err)
+	}
+
+	// Map stamp protocol to NetProtocol
+	netProto, err := stampProtoToNetProtocol(stamp.Proto)
+	if err != nil {
+		return Upstream{}, err
+	}
+
+	// Extract host and port from ServerAddrStr
+	host, port, err := extractStampHostPort(stamp.ServerAddrStr, netProto)
+	if err != nil {
+		return Upstream{}, err
+	}
+
+	// Use provider name as hostname if available (for DoH/DoT)
+	hostname := host
+	if stamp.ProviderName != "" {
+		// Validate provider name is a valid hostname or IP
+		if ip := net.ParseIP(stamp.ProviderName); ip == nil {
+			// Not an IP, must be a valid hostname
+			if !validDomain.MatchString(stamp.ProviderName) {
+				return Upstream{}, fmt.Errorf("invalid provider name in DNS stamp: '%s'", stamp.ProviderName)
+			}
+		}
+
+		hostname = stamp.ProviderName
+	}
+
+	// Convert stamp hashes to CertificateFingerprint type
+	certFingerprints := make([]CertificateFingerprint, 0, len(stamp.Hashes))
+	for _, hash := range stamp.Hashes {
+		certFingerprints = append(certFingerprints, CertificateFingerprint(hash))
+	}
+
+	upstream := Upstream{
+		Net:                     netProto,
+		Host:                    hostname,
+		Port:                    port,
+		Path:                    stamp.Path,
+		CommonName:              stamp.ProviderName, // Use provider name for TLS verification
+		CertificateFingerprints: certFingerprints,   // SHA256 fingerprints for certificate pinning
+	}
+
+	return upstream, nil
+}
+
+// extractStampHostPort extracts host and port from a DNS stamp server address string
+func extractStampHostPort(serverAddr string, netProto NetProtocol) (string, uint16, error) {
+	if serverAddr == "" {
+		return "", netDefaultPort[netProto], nil
+	}
+
+	h, portStr, err := net.SplitHostPort(serverAddr)
+	if err != nil {
+		// SplitHostPort failed - could be missing port or raw IP/hostname
+		// This is not an error for our purposes, just means no port specified
+		// Strip IPv6 brackets if present (e.g., "[2001:db8::1]" -> "2001:db8::1")
+		host := serverAddr
+		if strings.HasPrefix(host, "[") && strings.HasSuffix(host, "]") {
+			host = host[1 : len(host)-1]
+		}
+
+		return host, netDefaultPort[netProto], nil
+	}
+
+	// Successfully split host and port
+	if portStr != "" {
+		p, err := ConvertPort(portStr)
+		if err != nil {
+			return "", 0, fmt.Errorf("invalid port in stamp: %w", err)
+		}
+
+		return h, p, nil
+	}
+
+	return h, netDefaultPort[netProto], nil
+}
+
+// stampProtoToNetProtocol maps DNS stamp protocol to Blocky's NetProtocol
+func stampProtoToNetProtocol(proto dnsstamps.StampProtoType) (NetProtocol, error) {
+	switch proto {
+	case dnsstamps.StampProtoTypePlain:
+		return NetProtocolTcpUdp, nil
+	case dnsstamps.StampProtoTypeDoH:
+		return NetProtocolHttps, nil
+	case dnsstamps.StampProtoTypeTLS:
+		return NetProtocolTcpTls, nil
+	case dnsstamps.StampProtoTypeDNSCrypt:
+		return NetProtocol(0), errors.New("DNSCrypt protocol not supported")
+	case dnsstamps.StampProtoTypeDoQ:
+		return NetProtocol(0), errors.New("DNS-over-QUIC protocol not supported")
+	case dnsstamps.StampProtoTypeODoHTarget:
+		return NetProtocol(0), errors.New("oblivious DoH target not supported")
+	case dnsstamps.StampProtoTypeDNSCryptRelay:
+		return NetProtocol(0), errors.New("DNSCrypt Relay not supported")
+	case dnsstamps.StampProtoTypeODoHRelay:
+		return NetProtocol(0), errors.New("ODoH Relay not supported")
+	default:
+		return NetProtocol(0), fmt.Errorf("unsupported DNS stamp protocol: %v", proto)
+	}
+}