dmarcator 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d474c30401fa6eddca63e996bfbc7bf2726930386282d12aad8fbbe3f67353bf
-  data.tar.gz: eca8a030b0b6abf0a2ceeaa9c446843f502ec8132f4d409c386e639806e7db69
+  metadata.gz: ab57f0c6599df86ed3331199b84f0abdd9aae8876405e4205f2070b9e457b5ca
+  data.tar.gz: 5466098000ff91848f6cb8208606ed8b3312eb9b476763074d917b3f7f377aca
 SHA512:
-  metadata.gz: 0c20cb2c3576c6acce7619b5c20ac0ea3b335a0ae14c6e3f1cb0876f09eb232d559dad8ce9197923c1c0b33828ed1c8e3d63437c7ddc1670828bad8ae0fdf8cf
-  data.tar.gz: bf4fac1cb1c98fcd597424ad913b1e2eb02e5e1fb93f985b21c4a5cbbc8fae87b29aaa83ff73b6edc2c9c40f468be712554a3c6d61ff61e592cbe215d0188805
+  metadata.gz: 71c83a39fc17926997e43465ef07210a7a062a67b922462623e4d6c0daa617acefc4ec2546194ffa2f6755bf62321504134140b5e35813ac9e34b8ed43abbf89
+  data.tar.gz: ebdc8623cdba9d7632188a52fbdc203d7c1f85efed580f72ce5ceebeafd8a7c5eae4f5f0797d8960b1a6fb5e1b2af9aeb9d5484ffc74a5f8adc4942af4de286a

data/ChangeLog.md

@@ -1,3 +1,18 @@
+### 0.6.1 / 2026-10-29
+
+* Remove a redundant `attr_reader :sp` that `Record#sp` already overrode, fixing a `method redefined; discarding old sp` warning emitted under `-w` (as CI enables).
+* Add tests covering `Record#sp` falling back to `p` when `sp` is omitted.
+* Document every report accessor, constant, and public class that YARD previously omitted; documentation coverage is now 100% with no warnings.
+* Note the encrypted-transport guarantees in the README security section.
+* No functional changes.
+
+### 0.6.0 / 2026-10-28
+
+* Add DNS over HTTPS (RFC 8484) and DNS over TLS (RFC 7858) transports, selected with `DMARCATOR_DNS` (`doh` or `dot`). No provider is bundled and plaintext remains the default.
+* Encrypted transports verify TLS certificates, validate the response id, question and TC bit, and follow CNAMEs up to a bounded depth.
+* Add `DMARCator::ResolutionError`; encrypted transport failures raise instead of being reported as a missing record.
+* Add `DMARCator.default_resolver` and `DMARCator::Resolver.build` for explicit transport configuration.
+
 ### 0.5.1 / 2026-10-28
 
 * Point the gem metadata (`homepage`, `source_code_uri`, `bug_tracker_uri`) at the renamed GitHub repository (`dmarc` → `dmarcator`).

data/README.md

@@ -123,6 +123,43 @@ report.records.first.source_ip
 # => "209.85.220.69"
 ```
 
+## DNS transport
+
+By default, DMARC lookups use plain DNS through `Resolv`. Encrypted transports
+can be selected with environment variables; no DNS provider is baked in:
+
+```sh
+# DNS over HTTPS (RFC 8484)
+export DMARCATOR_DNS=doh
+export DMARCATOR_DOH_URL=https://cloudflare-dns.com/dns-query
+export DMARCATOR_DOH_IP=1.1.1.1          # optional: pin the endpoint
+
+# DNS over TLS (RFC 7858)
+export DMARCATOR_DNS=dot
+export DMARCATOR_DOT_SERVER=1.1.1.1:853
+export DMARCATOR_DOT_SNI=cloudflare-dns.com   # optional: name to verify
+
+# optional, both transports (seconds, default 5)
+export DMARCATOR_DNS_TIMEOUT=5
+```
+
+Certificates are always verified. `DMARCATOR_DOH_IP` pins the address so the
+DoH endpoint does not have to be resolved first; TLS still verifies the URL's
+hostname.
+
+Encrypted transports fail closed: a transport failure raises
+`DMARCator::ResolutionError` instead of being reported as a domain without a
+DMARC record. Plaintext is the default because forcing a public resolver breaks
+private and split-horizon zones, and some networks block port 853 or public
+resolvers.
+
+A resolver can also be built explicitly:
+
+```ruby
+resolver = DMARCator::Resolver::DoH.new(url: "https://dns.example/dns-query")
+record   = DMARCator::Record.query("example.com", resolver)
+```
+
 ## Security
 
 DMARC records and XML reports are treated as untrusted input:
@@ -140,6 +177,11 @@ DMARC records and XML reports are treated as untrusted input:
   CVE-2026-80212/CVE-2026-80213.
 * Domain names are validated before resolution (labels ≤ 63 octets, total ≤
   248 octets, no leading/trailing hyphens).
+* Optional [DNS over HTTPS and DNS over TLS](#dns-transport) transports verify
+  TLS certificates and fail closed: a transport failure raises
+  `DMARCator::ResolutionError` rather than being reported as a domain without a
+  DMARC record, so a blocked or downgraded lookup can never silently enforce no
+  policy.
 
 ## Requirements
 
@@ -156,6 +198,30 @@ To run the RSpec tests:
 rake spec
 ```
 
+## Releasing
+
+Every published version must have an annotated tag pointing at the commit that
+was built, so a gem can always be traced back to its source:
+
+```sh
+# 1. Bump VERSION in lib/dmarcator/version.rb and add a ChangeLog entry.
+# 2. Commit the release.
+git commit -am "Bump version to X.Y.Z"
+
+# 3. Tag that commit before building anything.
+git tag -a vX.Y.Z -m "dmarcator X.Y.Z"
+
+# 4. Push the commit and its tags.
+git push origin main --follow-tags
+
+# 5. Build and publish from the tagged checkout.
+gem build dmarc.gemspec
+gem push dmarcator-X.Y.Z.gem
+```
+
+Tag before publishing, never after: a tag without a published gem, or a gem
+without a tag, makes the two hard to reconcile later.
+
 ## License
 
 This project is released under the MIT License. See the [LICENSE.txt] file for

data/lib/dmarcator/exceptions.rb

@@ -3,6 +3,11 @@
 require 'parslet'
 
 module DMARCator
+  #
+  # Raised when a DMARC record cannot be parsed.
+  #
+  # @since 0.2.0
+  #
   class InvalidRecord < Parslet::ParseFailed
   end
 
@@ -11,4 +16,15 @@ module DMARCator
   #
   class InvalidReport < StandardError
   end
+
+  #
+  # Raised when an encrypted DNS transport fails to return a usable answer.
+  #
+  # This is deliberately distinct from a missing record: a failed lookup must
+  # not be mistaken for a domain without a DMARC policy.
+  #
+  # @since 0.6.0
+  #
+  class ResolutionError < StandardError
+  end
 end

data/lib/dmarcator/parser.rb

@@ -50,6 +50,21 @@ module DMARCator
       unknown_tag
     end
 
+    #
+    # Defines a rule for a `tag=value` DMARC tag, capturing values that do not
+    # match the rule as `:invalid_tag` so strict mode can reject them.
+    #
+    # @param [Symbol] name
+    #   The rule name, used as `dmarc_<name>`.
+    #
+    # @param [String] tag
+    #   The DMARC tag name.
+    #
+    # @yieldreturn [Parslet::Atoms::Base]
+    #   The parslet matching the tag's value.
+    #
+    # @api private
+    #
     def self.tag_rule(name,tag,&block)
       rule(:"dmarc_#{name}") do
         (
@@ -123,6 +138,11 @@ module DMARCator
     rule(:wsp) { str(' ') | str("\t") }
     rule(:wsp?) { wsp.repeat }
 
+    #
+    # Converts the raw parse tree into tag attributes.
+    #
+    # @api private
+    #
     class Transform < Parslet::Transform
 
       rule(fo_opt: simple(:fo_opt)) { fo_opt }
@@ -155,8 +175,21 @@ module DMARCator
       rule(rua: subtree(:uris)) { {rua: Array(uris)} }
       rule(ruf: subtree(:uris)) { {ruf: Array(uris)} }
 
+      # Maximum length of error messages echoed from untrusted input.
       MAX_ERROR_MESSAGE_LENGTH = 300
 
+      #
+      # Parses a `mailto:` URI from a parse tree slice.
+      #
+      # @param [Parslet::Slice] value
+      #
+      # @return [URI::MailTo]
+      #
+      # @raise [InvalidRecord]
+      #   The URI is not a valid `mailto:` URI.
+      #
+      # @api private
+      #
       def self.parse_uri(value)
         uri = value.to_s
 
@@ -173,6 +206,15 @@ module DMARCator
         parsed
       end
 
+      #
+      # Truncates an error message to a bounded length.
+      #
+      # @param [String] message
+      #
+      # @return [String]
+      #
+      # @api private
+      #
       def self.truncate(message)
         message = message.to_s
 

data/lib/dmarcator/query.rb

@@ -3,6 +3,8 @@
 require 'resolv'
 require 'rubygems'
 
+require_relative 'resolver'
+
 module DMARCator
   #
   # Resolv gem versions affected by CVE-2026-80212 and CVE-2026-80213.
@@ -77,26 +79,45 @@ module DMARCator
     domain
   end
 
+  #
+  # Builds the resolver configured by the environment.
+  #
+  # @return [Resolv::DNS, Resolver::DoH, Resolver::DoT]
+  #
+  # @raise [ArgumentError]
+  #   The configured transport or its settings are invalid.
+  #
+  # @since 0.6.0
+  #
+  def self.default_resolver
+    Resolver.build
+  end
+
   #
   # Queries a domain for the DMARC record.
   #
   # @param [String] domain
   #   The domain to query DMARC for.
   #
-  # @param [Resolv::DNS] resolver
-  #   The resolver to use. Its timeouts are set to {DNS_TIMEOUTS}.
+  # @param [Resolv::DNS, Resolver::DoH, Resolver::DoT] resolver
+  #   The resolver to use. When omitted, one is built from `DMARCATOR_DNS`;
+  #   plaintext resolvers receive {DNS_TIMEOUTS}.
   #
   # @return [String, nil]
   #   The domain's DMARC record or `nil` if none exists.
   #
+  # @raise [Resolver::DoH, Resolver::DoT] resolution errors
+  #   Encrypted transports raise {ResolutionError} when the lookup fails, so
+  #   a transport problem is never reported as a missing record.
+  #
   # @api semipublic
   #
   # @since 0.3.0
   #
-  def self.query(domain,resolver=Resolv::DNS.new)
+  def self.query(domain,resolver=default_resolver)
     validate_domain(domain)
 
-    resolver.timeouts = DNS_TIMEOUTS
+    resolver.timeouts = DNS_TIMEOUTS if resolver.respond_to?(:timeouts=)
 
     host = "_dmarc.#{domain}"
 

data/lib/dmarcator/record.rb

@@ -7,10 +7,15 @@ require 'dmarcator/exceptions'
 require 'resolv'
 
 module DMARCator
+  #
+  # A parsed DMARC record, as published in a `_dmarc.<domain>` TXT record.
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc7489
+  #
   class Record
 
     # `p` field.
-    # 
+    #
     # @return [:none, :quarantine, :reject]
     attr_reader :p
 
@@ -24,11 +29,6 @@ module DMARCator
     # @return [Array<Uri>]
     attr_reader :ruf
 
-    # `sp` field.
-    # 
-    # @return [:none, :quarantine, :reject]
-    attr_reader :sp
-
     # `v` field.
     #
     # @return [:DMARC1]
@@ -338,7 +338,7 @@ module DMARCator
     #
     # @api public
     #
-    def self.query(domain,resolver=Resolv::DNS.new)
+    def self.query(domain,resolver=DMARCator.default_resolver)
       if (dmarc = DMARCator.query(domain,resolver))
         parse(dmarc)
       end

data/lib/dmarcator/report/auth_result.rb

@@ -10,9 +10,20 @@ module DMARCator
     class AuthResult
       include XmlHelper
 
+      # Attribute names exposed by this class.
       ATTRIBUTES = [:type, :domain, :result, :selector, :scope]
 
-      attr_accessor(*ATTRIBUTES)
+      # @!attribute [rw] type
+      #   @return [String] the entry name (`dkim` or `spf`).
+      # @!attribute [rw] domain
+      #   @return [String, nil] the authenticated domain.
+      # @!attribute [rw] result
+      #   @return [String, nil] the authentication result.
+      # @!attribute [rw] selector
+      #   @return [String, nil] the DKIM selector.
+      # @!attribute [rw] scope
+      #   @return [String, nil] the SPF scope.
+      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
 
       def initialize(node)
         @node = node

data/lib/dmarcator/report/metadata.rb

@@ -10,12 +10,27 @@ module DMARCator
     class Metadata
       include XmlHelper
 
+      # Attribute names exposed by this class.
       ATTRIBUTES = [
         :org_name, :email, :extra_contact_info, :report_id,
         :begin_at, :end_at, :errors
       ]
 
-      attr_accessor(*ATTRIBUTES)
+      # @!attribute [rw] org_name
+      #   @return [String, nil] the reporting organization.
+      # @!attribute [rw] email
+      #   @return [String, nil] the reporting organization's contact address.
+      # @!attribute [rw] extra_contact_info
+      #   @return [String, nil] additional contact information.
+      # @!attribute [rw] report_id
+      #   @return [String, nil] the unique report identifier.
+      # @!attribute [rw] begin_at
+      #   @return [Time, nil] the start of the reporting interval.
+      # @!attribute [rw] end_at
+      #   @return [Time, nil] the end of the reporting interval.
+      # @!attribute [rw] errors
+      #   @return [Array<String>] errors reported by the reporting organization.
+      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
 
       def initialize(node)
         @node = node

data/lib/dmarcator/report/policy.rb

@@ -10,9 +10,24 @@ module DMARCator
     class Policy
       include XmlHelper
 
+      # Attribute names exposed by this class.
       ATTRIBUTES = [:domain, :adkim, :aspf, :p, :sp, :pct, :fo]
 
-      attr_accessor(*ATTRIBUTES)
+      # @!attribute [rw] domain
+      #   @return [String, nil] the domain the policy applies to.
+      # @!attribute [rw] adkim
+      #   @return [String, nil] the DKIM alignment mode (`r` or `s`).
+      # @!attribute [rw] aspf
+      #   @return [String, nil] the SPF alignment mode (`r` or `s`).
+      # @!attribute [rw] p
+      #   @return [String, nil] the requested policy.
+      # @!attribute [rw] sp
+      #   @return [String, nil] the requested subdomain policy.
+      # @!attribute [rw] pct
+      #   @return [Integer, nil] the percentage of messages the policy applied to.
+      # @!attribute [rw] fo
+      #   @return [String, nil] the requested failure-reporting options.
+      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
 
       def initialize(node)
         @node = node

data/lib/dmarcator/report/reason.rb

@@ -10,9 +10,14 @@ module DMARCator
     class Reason
       include XmlHelper
 
+      # Attribute names exposed by this class.
       ATTRIBUTES = [:type, :comment]
 
-      attr_accessor(*ATTRIBUTES)
+      # @!attribute [rw] type
+      #   @return [String, nil] the reason type.
+      # @!attribute [rw] comment
+      #   @return [String, nil] an optional explanatory comment.
+      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
 
       def initialize(node)
         @node = node

data/lib/dmarcator/report/record.rb

@@ -12,12 +12,29 @@ module DMARCator
     class Record
       include XmlHelper
 
+      # Attribute names exposed by this class.
       ATTRIBUTES = [
         :source_ip, :count, :disposition, :dkim, :spf,
         :envelope_to, :envelope_from, :header_from
       ]
 
-      attr_accessor(*ATTRIBUTES)
+      # @!attribute [rw] source_ip
+      #   @return [String, nil] the sending IP address.
+      # @!attribute [rw] count
+      #   @return [Integer, nil] the number of messages from this source.
+      # @!attribute [rw] disposition
+      #   @return [String, nil] the action applied to the messages.
+      # @!attribute [rw] dkim
+      #   @return [String, nil] the DKIM evaluation result.
+      # @!attribute [rw] spf
+      #   @return [String, nil] the SPF evaluation result.
+      # @!attribute [rw] envelope_to
+      #   @return [String, nil] the envelope recipient domain.
+      # @!attribute [rw] envelope_from
+      #   @return [String, nil] the envelope sender domain.
+      # @!attribute [rw] header_from
+      #   @return [String, nil] the `From` header domain.
+      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
       attr_writer :auth_results, :reasons
 
       def initialize(node)

data/lib/dmarcator/resolver/doh.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+require_relative '../exceptions'
+require_relative 'encrypted'
+
+module DMARCator
+  module Resolver
+    #
+    # DNS over HTTPS transport ([RFC 8484]).
+    #
+    # The endpoint is configured by the caller; no provider is assumed. To avoid
+    # needing DNS to reach the DNS server, pass `ipaddr:` (or set
+    # `DMARCATOR_DOH_IP`) to pin the connection while TLS still verifies the
+    # certificate against the URL's hostname.
+    #
+    # [RFC 8484]: https://www.rfc-editor.org/rfc/rfc8484
+    #
+    # @since 0.6.0
+    #
+    class DoH < Encrypted
+      # Default connect/read timeout in seconds.
+      DEFAULT_TIMEOUT = 5
+
+      # @return [URI::HTTPS] the DoH endpoint.
+      attr_reader :url
+
+      # @return [String, nil] the address to connect to instead of resolving
+      #   the endpoint hostname.
+      attr_reader :ipaddr
+
+      # @return [Integer] connect/read timeout in seconds.
+      attr_reader :timeout
+
+      #
+      # Builds a resolver from environment variables.
+      #
+      # @param [Hash] env
+      #
+      # @return [DoH]
+      #
+      # @raise [ArgumentError]
+      #   `DMARCATOR_DOH_URL` is missing or not an HTTPS URL.
+      #
+      def self.from_env(env = ENV)
+        url = env['DMARCATOR_DOH_URL']
+
+        if url.nil? || url.empty?
+          raise ArgumentError, 'DMARCATOR_DNS=doh requires DMARCATOR_DOH_URL'
+        end
+
+        new(
+          url: url,
+          ipaddr: presence(env['DMARCATOR_DOH_IP']),
+          timeout: timeout_from(env)
+        )
+      end
+
+      def self.presence(value)
+        value unless value.nil? || value.empty?
+      end
+
+      def self.timeout_from(env)
+        value = env['DMARCATOR_DNS_TIMEOUT']
+
+        value.nil? || value.empty? ? DEFAULT_TIMEOUT : Integer(value, 10)
+      end
+
+      def initialize(url:, ipaddr: nil, timeout: DEFAULT_TIMEOUT)
+        @url = URI.parse(url)
+
+        unless @url.is_a?(URI::HTTPS) && @url.host
+          raise ArgumentError, "DoH endpoint must be an https URL: #{url.inspect}"
+        end
+
+        @ipaddr = ipaddr
+        @timeout = timeout
+      end
+
+      private
+
+      def exchange(query)
+        http = Net::HTTP.new(@url.host, @url.port)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout
+        http.ipaddr = @ipaddr if @ipaddr
+
+        request = Net::HTTP::Post.new(@url.request_uri)
+        request['content-type'] = 'application/dns-message'
+        request['accept'] = 'application/dns-message'
+        request.body = query.encode
+
+        response = http.start { |connection| connection.request(request) }
+
+        status = response.code.to_i
+
+        unless status.between?(200, 299)
+          raise ResolutionError, "DoH endpoint returned HTTP #{status}"
+        end
+
+        response.body.to_s.b
+      rescue ResolutionError
+        raise
+      rescue StandardError => error
+        raise ResolutionError, "DoH request failed: #{error.message}"
+      end
+    end
+  end
+end

data/lib/dmarcator/resolver/dot.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'openssl'
+require 'socket'
+
+require_relative '../exceptions'
+require_relative 'encrypted'
+
+module DMARCator
+  module Resolver
+    #
+    # DNS over TLS transport ([RFC 7858]).
+    #
+    # The server is configured by the caller; no provider is assumed. When the
+    # server is an IP literal, TLS still verifies the certificate against that
+    # address, and `sni:` can name a hostname to verify instead.
+    #
+    # [RFC 7858]: https://www.rfc-editor.org/rfc/rfc7858
+    #
+    # @since 0.6.0
+    #
+    class DoT < Encrypted
+      # Default DoT port.
+      DEFAULT_PORT = 853
+
+      # Default connect/read timeout in seconds.
+      DEFAULT_TIMEOUT = 5
+
+      # @return [String] the server host or address.
+      attr_reader :host
+
+      # @return [Integer] the server port.
+      attr_reader :port
+
+      # @return [String] the name to verify the certificate against.
+      attr_reader :sni
+
+      # @return [Integer] connect/read timeout in seconds.
+      attr_reader :timeout
+
+      #
+      # Builds a resolver from environment variables.
+      #
+      # @param [Hash] env
+      #
+      # @return [DoT]
+      #
+      # @raise [ArgumentError]
+      #   `DMARCATOR_DOT_SERVER` is missing or malformed.
+      #
+      def self.from_env(env = ENV)
+        server = env['DMARCATOR_DOT_SERVER']
+
+        if server.nil? || server.empty?
+          raise ArgumentError, 'DMARCATOR_DNS=dot requires DMARCATOR_DOT_SERVER (host[:port])'
+        end
+
+        host, port = split_server(server)
+        sni = env['DMARCATOR_DOT_SNI']
+
+        new(
+          host: host,
+          port: port,
+          sni: sni.nil? || sni.empty? ? nil : sni,
+          timeout: timeout_from(env)
+        )
+      end
+
+      #
+      # Splits `host`, `host:port`, `[v6]`, or `[v6]:port`.
+      #
+      # @param [String] server
+      #
+      # @return [Array(String, Integer)]
+      #
+      # @raise [ArgumentError]
+      #   The value is malformed.
+      #
+      def self.split_server(server)
+        if (match = /\A\[(?<host>[^\]]+)\](?::(?<port>\d+))?\z/.match(server))
+          [match[:host], (match[:port] || DEFAULT_PORT).to_i]
+        elsif (match = /\A(?<host>[^:]+)(?::(?<port>\d+))?\z/.match(server))
+          [match[:host], (match[:port] || DEFAULT_PORT).to_i]
+        else
+          raise ArgumentError, "invalid DMARCATOR_DOT_SERVER: #{server.inspect}"
+        end
+      end
+
+      def self.timeout_from(env)
+        value = env['DMARCATOR_DNS_TIMEOUT']
+
+        value.nil? || value.empty? ? DEFAULT_TIMEOUT : Integer(value, 10)
+      end
+
+      def initialize(host:, port: DEFAULT_PORT, sni: nil, timeout: DEFAULT_TIMEOUT)
+        @host = host
+        @port = port
+        @sni = sni || host
+        @timeout = timeout
+      end
+
+      private
+
+      def exchange(query)
+        wire = query.encode
+
+        with_tls do |socket|
+          socket.write([wire.bytesize].pack('n') + wire)
+
+          header = socket.read(2)
+
+          raise ResolutionError, 'short DoT response' if header.nil? || header.bytesize < 2
+
+          body = socket.read(header.unpack1('n'))
+          raise ResolutionError, 'short DoT response' if body.nil?
+
+          body
+        end
+      rescue ResolutionError
+        raise
+      rescue StandardError => error
+        raise ResolutionError, "DoT request failed: #{error.message}"
+      end
+
+      def with_tls
+        tcp = Socket.tcp(@host, @port, connect_timeout: @timeout)
+        tcp.timeout = @timeout if tcp.respond_to?(:timeout=)
+
+        context = OpenSSL::SSL::SSLContext.new
+        context.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        context.set_params
+
+        socket = OpenSSL::SSL::SSLSocket.new(tcp, context)
+        socket.hostname = @sni unless ip_literal?(@sni)
+        socket.sync_close = true
+        socket.connect
+        socket.post_connection_check(@sni)
+
+        begin
+          yield socket
+        ensure
+          close_quietly(socket)
+          close_quietly(tcp)
+        end
+      end
+
+      def ip_literal?(value)
+        IPAddr.new(value.to_s)
+
+        true
+      rescue IPAddr::Error, ArgumentError
+        false
+      end
+
+      def close_quietly(io)
+        io.close
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/dmarcator/resolver/encrypted.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'resolv'
+
+require_relative '../exceptions'
+
+module DMARCator
+  module Resolver
+    #
+    # Base class for encrypted DNS transports (DoH and DoT).
+    #
+    # Subclasses implement {#exchange}, which sends one encoded DNS query and
+    # returns the encoded response. Everything else - query construction,
+    # response validation and CNAME following - is shared here.
+    #
+    # @abstract
+    #
+    # @since 0.6.0
+    #
+    # @api private
+    #
+    class Encrypted
+      # Maximum number of CNAME indirections to follow.
+      MAX_CNAME_DEPTH = 8
+
+      #
+      # Looks up resource records, matching `Resolv::DNS#getresources`.
+      #
+      # @param [String, Resolv::DNS::Name] name
+      #   The name to look up.
+      #
+      # @param [Class] type
+      #   The resource record type, e.g.
+      #   `Resolv::DNS::Resource::IN::TXT`.
+      #
+      # @return [Array<Resolv::DNS::Resource>]
+      #
+      # @raise [ResolutionError]
+      #   The transport failed or returned an unusable response.
+      #
+      def getresources(name, type)
+        fetch(dns_name(name), type, MAX_CNAME_DEPTH)
+      end
+
+      private
+
+      def dns_name(name)
+        return name if name.is_a?(Resolv::DNS::Name)
+
+        Resolv::DNS::Name.create(name.to_s)
+      end
+
+      def fetch(name, type, depth)
+        id = Random.rand(0x10000)
+        message = decode_response(exchange(build_query(id, name, type)), id, name, type)
+
+        case message.rcode
+        when Resolv::DNS::RCode::NoError
+          collect(message, name, type, depth)
+        when Resolv::DNS::RCode::NXDomain
+          []
+        else
+          raise ResolutionError, "DNS query failed with rcode #{message.rcode}"
+        end
+      end
+
+      def collect(message, name, type, depth)
+        matching = message.answer.select { |_name, _ttl, record| record.is_a?(type) }
+        return matching.map { |_name, _ttl, record| record } unless matching.empty?
+
+        cname = message.answer.find do |_name, _ttl, record|
+          record.is_a?(Resolv::DNS::Resource::IN::CNAME)
+        end
+
+        return fetch(cname[2].name, type, depth - 1) if cname && depth.positive?
+
+        []
+      end
+
+      def build_query(id, name, type)
+        message = Resolv::DNS::Message.new(id)
+        message.rd = 1
+        message.add_question(name, type)
+        message
+      end
+
+      def decode_response(wire, id, name, type)
+        raise ResolutionError, 'empty DNS response' if wire.nil? || wire.empty?
+
+        message = begin
+          Resolv::DNS::Message.decode(wire)
+        rescue StandardError => error
+          raise ResolutionError, "malformed DNS response: #{error.message}"
+        end
+
+        unless message.id == id
+          raise ResolutionError, 'unexpected DNS response (transaction mismatch)'
+        end
+
+        # `Message.decode` returns early for truncated responses, leaving the
+        # remaining header fields unset, so check the TC bit first.
+        raise ResolutionError, 'truncated DNS response' unless message.tc.to_i.zero?
+
+        unless message.qr == 1
+          raise ResolutionError, 'unexpected DNS response (not a response)'
+        end
+
+        question = message.question.first
+
+        unless question && same_name?(question[0], name) && question[1] == type
+          raise ResolutionError, 'unexpected DNS response (question mismatch)'
+        end
+
+        message
+      end
+
+      #
+      # Compares DNS names case-insensitively and ignoring a trailing root dot.
+      # `Resolv::DNS::Name#==` treats `example.com` and `example.com.` as
+      # different, but a decoded response always carries the absolute form.
+      #
+      def same_name?(left, right)
+        normalize_name(left) == normalize_name(right)
+      end
+
+      def normalize_name(value)
+        value.to_s.downcase.chomp('.')
+      end
+    end
+  end
+end

data/lib/dmarcator/resolver.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'resolv'
+
+require_relative 'exceptions'
+require_relative 'resolver/encrypted'
+require_relative 'resolver/doh'
+require_relative 'resolver/dot'
+
+module DMARCator
+  #
+  # Selects the DNS transport used for DMARC lookups.
+  #
+  # The transport is chosen with the `DMARCATOR_DNS` environment variable, or
+  # explicitly via {.build}:
+  #
+  #   DMARCATOR_DNS=plaintext          # default: Resolv::DNS (UDP/TCP)
+  #   DMARCATOR_DNS=doh                # requires DMARCATOR_DOH_URL
+  #   DMARCATOR_DNS=dot                # requires DMARCATOR_DOT_SERVER
+  #
+  # Encrypted transports fail closed: a transport failure raises
+  # {ResolutionError} instead of being reported as "no DMARC record".
+  #
+  # @since 0.6.0
+  #
+  module Resolver
+    # Supported transport names.
+    MODES = %w[plaintext doh dot].freeze
+
+    # Transport used when `DMARCATOR_DNS` is unset.
+    DEFAULT_MODE = 'plaintext'
+
+    #
+    # Reads the configured transport name.
+    #
+    # @param [Hash] env
+    #
+    # @return [String]
+    #
+    def self.mode(env = ENV)
+      value = env['DMARCATOR_DNS']
+
+      value.nil? || value.empty? ? DEFAULT_MODE : value.to_s.strip.downcase
+    end
+
+    #
+    # Builds the configured resolver.
+    #
+    # @param [String, nil] mode
+    #   Overrides the `DMARCATOR_DNS` environment variable.
+    #
+    # @param [Hash] env
+    #
+    # @return [Resolv::DNS, DoH, DoT]
+    #
+    # @raise [ArgumentError]
+    #   The mode or its required settings are invalid.
+    #
+    def self.build(mode: nil, env: ENV)
+      name = (mode || self.mode(env)).to_s.strip.downcase
+
+      case name
+      when 'plaintext'
+        Resolv::DNS.new
+      when 'doh'
+        DoH.from_env(env)
+      when 'dot'
+        DoT.from_env(env)
+      else
+        raise ArgumentError,
+              "unknown DMARCATOR_DNS value: #{name.inspect} " \
+              "(expected one of #{MODES.join(', ')})"
+      end
+    end
+  end
+end

data/lib/dmarcator/version.rb

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '0.5.1'
+  VERSION = '0.6.1'
 end

data/lib/dmarcator.rb

@@ -6,3 +6,15 @@ require 'dmarcator/record'
 require 'dmarcator/parser'
 require 'dmarcator/report'
 require 'dmarcator/version'
+
+#
+# Parses, queries, and validates DMARC records and aggregates.
+#
+# Use {DMARCator::Record} for `_dmarc.<domain>` TXT records, {DMARCator::Report}
+# for aggregate/forensic XML reports, and {DMARCator::Resolver} to choose the
+# DNS transport (plaintext, DNS over HTTPS, or DNS over TLS).
+#
+# @see https://www.rfc-editor.org/rfc/rfc7489
+#
+module DMARCator
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Noah Berman
@@ -79,6 +79,10 @@ files:
 - lib/dmarcator/report/policy.rb
 - lib/dmarcator/report/reason.rb
 - lib/dmarcator/report/record.rb
+- lib/dmarcator/resolver.rb
+- lib/dmarcator/resolver/doh.rb
+- lib/dmarcator/resolver/dot.rb
+- lib/dmarcator/resolver/encrypted.rb
 - lib/dmarcator/uri.rb
 - lib/dmarcator/version.rb
 - lib/dmarcator/xml_helper.rb