dmarcator 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab57f0c6599df86ed3331199b84f0abdd9aae8876405e4205f2070b9e457b5ca
-  data.tar.gz: 5466098000ff91848f6cb8208606ed8b3312eb9b476763074d917b3f7f377aca
+  metadata.gz: f09058293dac6f0e31294f06182d69502ee06bc152aa3eb2ef06c07515f4363b
+  data.tar.gz: 6e3aee91c8c8d098c0f066a6b301ef9bc36f42018078769f15e65d695d35ba8a
 SHA512:
-  metadata.gz: 71c83a39fc17926997e43465ef07210a7a062a67b922462623e4d6c0daa617acefc4ec2546194ffa2f6755bf62321504134140b5e35813ac9e34b8ed43abbf89
-  data.tar.gz: ebdc8623cdba9d7632188a52fbdc203d7c1f85efed580f72ce5ceebeafd8a7c5eae4f5f0797d8960b1a6fb5e1b2af9aeb9d5484ffc74a5f8adc4942af4de286a
+  metadata.gz: dd47e82f78219d828832c95912a84581ad589efaec940bc25749a0a38b49692805f9afd8030e0f0bd01b2b611dd05a36fec474a8beb9866be340ba9a2e327f39
+  data.tar.gz: 973b12e73708b1540e912063db142ca91e07c5e29cca86e32481222e25334448b8efe754113bfeec6fae591c6411f8a82d796429c7ac36c26e4c22c8c3b714fa

data/ChangeLog.md

@@ -1,3 +1,20 @@
+### 0.8.0 / 2026-10-29
+
+* Add `DMARCator.txt`, which returns every TXT record at a name — unfiltered, in response order, with multi-chunk records joined. It accepts service labels such as `_dmarc` and `_domainkey` through a new relaxed `validate_txt_name`, and lets callers detect duplicate DMARC records that `dmarc` deliberately hides.
+* Rename the lookup methods after what they return: `DMARCator.dmarc` (was `DMARCator.query`) and `DMARCator::Record.lookup` (was `DMARCator::Record.query`). The old names remain as deprecated aliases and emit no runtime warnings.
+* Apply `DMARCATOR_DNS_TIMEOUTS` when the library builds a plaintext resolver, instead of on every lookup. An injected resolver now keeps its own configuration.
+* Document the lookup APIs, bulk-scan guidance and deprecations in the README.
+
+### 0.7.0 / 2026-10-29
+
+* Plaintext DNS lookups now fail closed: a lookup failure raises `DMARCator::ResolutionError` instead of being reported as a domain without a DMARC record. Previously a timeout or resolver failure looked like no policy, which failed open. This is a behavior change and applies to every transport.
+* DoH responses must use the `application/dns-message` content type (RFC 8484) and are capped at 65,535 bytes.
+* `DMARCator::Uri` no longer forwards calls to private methods of the wrapped `URI::MailTo`.
+* Remove the unused `XmlHelper#get_int`/`#get_timestamp` helpers and the deprecated `Record.from_txt`.
+* Memoize a missing report version instead of recomputing it, and scope spec constants under `DMARCator`.
+* Add `changelog_uri` and `documentation_uri` gem metadata, and document that domains must be passed as A-labels.
+* Add a CI workflow that runs the specs on the minimum supported Ruby and the current release, loads the gem with warnings enabled, fails on YARD warnings, and builds the gem.
+
 ### 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).

data/README.md

@@ -89,10 +89,82 @@ record.sp
 Query the DMARC record for a domain:
 
 ```ruby
-record = DMARCator::Record.query("twitter.com")
+record = DMARCator::Record.lookup("twitter.com")
 # => #<DMARCator::Record ... @p=:reject, @rua=[...], ...>
 ```
 
+Domains must be ASCII (A-labels): pass punycode such as
+`xn--mnchen-3ya.de` rather than `münchen.de`. A lookup failure raises
+`DMARCator::ResolutionError`; `nil` only means the domain genuinely has no
+DMARC record.
+
+## Lookup APIs
+
+The lookup methods are named after what they return:
+
+| Method | Returns | Cost |
+|---|---|---|
+| `DMARCator.txt(name)` | `Array<String>` — every TXT record at `name` | one lookup |
+| `DMARCator.dmarc(domain)` | `String` — the DMARC record text, or `nil` | one lookup |
+| `DMARCator::Record.lookup(domain)` | `Record` — parsed | one lookup + parse (~0.4 ms) |
+| `DMARCator::Record.parse(text)` | `Record` — parsed from a string | parse only |
+
+`DMARCator.txt` is the primitive: unfiltered, in response order, multi-chunk
+records joined. It works for any TXT name, including `_dmarc.` and
+`_domainkey.` labels, and leaves interpretation to the caller:
+
+```ruby
+DMARCator.txt("_dmarc.example.com")
+# => ["v=DMARC1; p=reject; rua=mailto:dmarc@example.com"]
+
+DMARCator.txt("example.com")
+# => ["v=spf1 include:_spf.example.com -all", "google-site-verification=abc"]
+
+DMARCator.txt("s1._domainkey.example.com")
+# => []
+```
+
+Because it returns every record, it is also how you detect misconfiguration
+that `DMARCator.dmarc` deliberately hides per RFC 7489 §6.6.3:
+
+```ruby
+records = DMARCator.txt("_dmarc.#{domain}").select { |t| t.start_with?("v=DMARC1") }
+case records.length
+when 0 then :none
+when 1 then :ok
+else :duplicate  # more than one DMARC record breaks enforcement
+end
+```
+
+All three methods accept an injected resolver, and an injected resolver keeps
+its own configuration (timeouts are only applied to resolvers the library
+builds):
+
+```ruby
+resolver = DMARCator::Resolver::DoH.new(url: "https://dns.example/dns-query")
+DMARCator.txt("_dmarc.example.com", resolver: resolver)
+DMARCator.dmarc("example.com", resolver: resolver)
+DMARCator::Record.lookup("example.com", resolver: resolver)
+```
+
+### Bulk lookups
+
+`DMARCator.dmarc` is the cheapest DMARC path — one lookup, no parsing. For a
+scan over many domains:
+
+```ruby
+resolver = DMARCator.default_resolver   # build once, not per domain
+domains.each do |domain|
+  record = DMARCator.dmarc(domain, resolver: resolver)
+  # parse only when you need the fields
+end
+```
+
+Notes for large scans: `Record.lookup` adds a parse per domain (~0.4 ms, far
+more than the lookup on a fast resolver); `Resolv::DNS` does not lock per query,
+so use one resolver per thread when parallelising; and DoT/DoH open a new TLS
+connection per lookup, so plaintext is the better choice for bulk work.
+
 ## Strict parsing
 
 By default, unknown tags and tags with invalid values are ignored. Pass
@@ -149,15 +221,17 @@ 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.
+DMARC record. This applies to every transport, including plaintext —
+`Resolv` returns an empty result for NXDOMAIN and raises for timeouts and
+other failures, so a failed lookup is never mistaken for an absent record.
+Plaintext remains 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)
+record   = DMARCator::Record.lookup("example.com", resolver: resolver)
 ```
 
 ## Security
@@ -181,7 +255,8 @@ DMARC records and XML reports are treated as untrusted input:
   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.
+  policy. Plaintext lookups fail closed the same way. DoH responses must be
+  `application/dns-message` and are capped at 65,535 bytes.
 
 ## Requirements
 
@@ -208,8 +283,12 @@ was built, so a gem can always be traced back to its source:
 # 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"
+# 3. Tag that commit before building anything, with release notes in the
+#    tag message. Repeating -m adds blank-line-separated paragraphs.
+git tag -a vX.Y.Z \
+    -m "dmarcator X.Y.Z" \
+    -m "Summary of the release, including behaviour changes and upgrade notes." \
+    -m "See ChangeLog.md for the itemized list."
 
 # 4. Push the commit and its tags.
 git push origin main --follow-tags
@@ -219,6 +298,10 @@ gem build dmarc.gemspec
 gem push dmarcator-X.Y.Z.gem
 ```
 
+The tag message is the release note: it is what `git show vX.Y.Z` prints, so
+put the highlight summary and any upgrade guidance there. Write it before step
+4, because a pushed tag message cannot be changed without force-pushing the tag.
+
 Tag before publishing, never after: a tag without a published gem, or a gem
 without a tag, makes the two hard to reconcile later.
 

data/lib/dmarcator/query.rb

@@ -17,8 +17,18 @@ module DMARCator
   #
   # DNS query timeouts in seconds, tried in order.
   #
+  # Applied when the library builds a plaintext resolver. Timeouts on an
+  # injected resolver are left alone.
+  #
   DNS_TIMEOUTS = [2, 4, 8].freeze
 
+  #
+  # The maximum length of a textual DNS name, in octets.
+  #
+  # @since 0.8.0
+  #
+  MAX_TXT_NAME_LENGTH = 253
+
   #
   # Determines the version of the loaded `resolv` gem, if available.
   #
@@ -57,6 +67,10 @@ module DMARCator
   #
   # Validates a domain before using it in a DNS query.
   #
+  # Rejects underscores and reserves room for the `_dmarc.` prefix, so this is
+  # the validator for registrable domains rather than arbitrary DNS names.
+  # Use {validate_txt_name} for service labels.
+  #
   # @param [String] domain
   #   The domain to validate.
   #
@@ -79,6 +93,37 @@ module DMARCator
     domain
   end
 
+  #
+  # Validates an arbitrary DNS name used for a TXT lookup.
+  #
+  # Unlike {validate_domain}, service labels such as `_dmarc` and `_domainkey`
+  # are allowed, so names may contain underscores. Length and label limits are
+  # still enforced so hostile input cannot reach the resolver unbounded.
+  #
+  # @param [String] name
+  #   The DNS name to validate.
+  #
+  # @return [String]
+  #   The validated name.
+  #
+  # @raise [ArgumentError]
+  #   The name is not a syntactically valid DNS name.
+  #
+  # @since 0.8.0
+  #
+  def self.validate_txt_name(name)
+    unless name.is_a?(String) && !name.empty? &&
+           name.length <= MAX_TXT_NAME_LENGTH &&
+           !name.start_with?('.') &&
+           !name.include?('..') &&
+           name.match?(/\A[A-Za-z0-9._-]+\z/) &&
+           name.split('.').all? { |label| label.length <= 63 && !label.start_with?('-') && !label.end_with?('-') }
+      raise ArgumentError, "invalid TXT name: #{name.inspect}"
+    end
+
+    name
+  end
+
   #
   # Builds the resolver configured by the environment.
   #
@@ -94,47 +139,116 @@ module DMARCator
   end
 
   #
-  # Queries a domain for the DMARC record.
+  # Looks up every TXT record published at a DNS name.
+  #
+  # Records are returned exactly as published: unfiltered, in response order,
+  # and with multi-chunk records joined. Interpreting them (SPF, DKIM, DMARC,
+  # domain verification) is left to the caller. Use this when the individual
+  # records matter, for example to detect that a domain publishes more than
+  # one DMARC record.
+  #
+  # @param [String] name
+  #   The DNS name to look up, such as `example.com`, `_dmarc.example.com`, or
+  #   `s1._domainkey.example.com`.
+  #
+  # @param [Resolv::DNS, Resolver::DoH, Resolver::DoT] resolver
+  #   The resolver to use. When omitted, one is built from `DMARCATOR_DNS`.
+  #   An injected resolver keeps its own configuration.
+  #
+  # @return [Array<String>]
+  #   The TXT records, or an empty array when the name has none. NXDOMAIN and
+  #   NODATA are indistinguishable here.
+  #
+  # @raise [ResolutionError]
+  #   The lookup failed. A failure is never reported as an empty result, so a
+  #   blocked or degraded resolver cannot be mistaken for an absent record.
+  #
+  # @raise [ArgumentError]
+  #   The name is not a syntactically valid DNS name.
+  #
+  # @note Names must be ASCII: pass punycode (A-labels) rather than Unicode.
+  #
+  # @since 0.8.0
+  #
+  def self.txt(name, resolver: default_resolver)
+    lookup_txt(validate_txt_name(name), resolver: resolver)
+  end
+
+  #
+  # Looks up the DMARC record text published for a domain.
+  #
+  # This is the lowest-cost DMARC path: one TXT lookup and no parsing. Use it
+  # for bulk scans, and call {Record.parse} only on records you care about.
   #
   # @param [String] domain
-  #   The domain to query DMARC for.
+  #   The domain to look up DMARC for.
   #
   # @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}.
+  #   The resolver to use. When omitted, one is built from `DMARCATOR_DNS`.
   #
   # @return [String, nil]
-  #   The domain's DMARC record or `nil` if none exists.
+  #   The DMARC record text, or `nil` when the domain publishes none or
+  #   publishes more than one (per RFC 7489 §6.6.3). Use {txt} to see every
+  #   record, including duplicates.
   #
-  # @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.
+  # @raise [ResolutionError]
+  #   The lookup failed.
   #
-  # @api semipublic
+  # @raise [ArgumentError]
+  #   The domain is not a syntactically valid DNS name.
   #
-  # @since 0.3.0
+  # @since 0.8.0
   #
-  def self.query(domain,resolver=default_resolver)
-    validate_domain(domain)
+  def self.dmarc(domain, resolver: default_resolver)
+    name = "_dmarc.#{validate_domain(domain)}"
 
-    resolver.timeouts = DNS_TIMEOUTS if resolver.respond_to?(:timeouts=)
+    # Per RFC 7489 §6.6.3, use the TXT record beginning with "v=DMARC1".
+    # If multiple DMARC records exist, treat the domain as having none.
+    dmarc_records = lookup_txt(name, resolver: resolver).select do |text|
+      text.start_with?('v=DMARC1')
+    end
 
-    host = "_dmarc.#{domain}"
+    dmarc_records.first if dmarc_records.one?
+  end
 
+  #
+  # @deprecated Use {dmarc}, which names what it returns. Kept for
+  #   compatibility; it will be removed in a future release.
+  #
+  # @see dmarc
+  #
+  def self.query(domain,resolver=default_resolver)
+    dmarc(domain, resolver: resolver)
+  end
+
+  #
+  # Looks up the TXT records at an already-validated name.
+  #
+  # Shared by {txt} and {dmarc} so both use one transport path.
+  #
+  # @param [String] name
+  #
+  # @param [Resolv::DNS, Resolver::DoH, Resolver::DoT] resolver
+  #
+  # @return [Array<String>]
+  #
+  # @raise [ResolutionError]
+  #
+  # @api private
+  #
+  def self.lookup_txt(name, resolver:)
+    # Resolv returns an empty result for NXDOMAIN and raises for timeouts and
+    # other failures, so any exception here is a transport failure, not an
+    # absent record.
     begin
-      records = resolver.getresources(host, Resolv::DNS::Resource::IN::TXT)
-    rescue Resolv::ResolvError
-      return nil
+      records = resolver.getresources(name, Resolv::DNS::Resource::IN::TXT)
+    rescue Resolv::ResolvError => error
+      raise ResolutionError, "DNS TXT lookup failed for #{name}: #{error.message}"
     end
 
-    # Per RFC 7489 §6.6.3, use the TXT record beginning with "v=DMARC1".
-    # If multiple DMARC records exist, treat the domain as having none.
-    dmarc_records = records.map { |record| record.strings.join }
-                           .select { |text| text.start_with?('v=DMARC1') }
-
-    return dmarc_records.first if dmarc_records.one?
-    nil
+    records.map { |record| record.strings.join }
   end
+  private_class_method :lookup_txt
 end
 
 if DMARCator.vulnerable_resolv?

data/lib/dmarcator/record.rb

@@ -288,13 +288,6 @@ module DMARCator
       raise InvalidRecord.new(truncate_error_message(error.message), error.cause)
     end
 
-    #
-    # @deprecated use {parse} instead.
-    #
-    def self.from_txt(rec)
-      parse(rec)
-    end
-
     # Maximum length of error messages echoed from parsing untrusted input.
     MAX_ERROR_MESSAGE_LENGTH = 500
 
@@ -319,31 +312,46 @@ module DMARCator
     end
 
     #
-    # Queries and parses the DMARC record for a domain.
+    # Looks up and parses the DMARC record for a domain.
+    #
+    # Prefer {DMARCator.dmarc} for bulk work: this method adds a parse
+    # (roughly 0.4 ms) on top of the lookup.
     #
     # @param [String] domain
-    #   The domain to query DMARC for.
+    #   The domain to look up DMARC for.
     #
-    # @param [Resolv::DNS] resolver
-    #   The resolver to use.
+    # @param [Resolv::DNS, DMARCator::Resolver::DoH, DMARCator::Resolver::DoT] resolver
+    #   The resolver to use. When omitted, one is built from `DMARCATOR_DNS`.
     #
     # @return [Record, nil]
-    #   The parsed DMARC record. If no DMARC record was found, `nil` will be
-    #   returned.
+    #   The parsed DMARC record, or `nil` when the domain publishes none.
     #
     # @raise [InvalidRecord]
     #   The DMARC record could not be parsed.
     #
-    # @since 0.3.0
+    # @raise [DMARCator::ResolutionError]
+    #   The lookup failed.
+    #
+    # @since 0.8.0
     #
     # @api public
     #
-    def self.query(domain,resolver=DMARCator.default_resolver)
-      if (dmarc = DMARCator.query(domain,resolver))
+    def self.lookup(domain, resolver: DMARCator.default_resolver)
+      if (dmarc = DMARCator.dmarc(domain, resolver: resolver))
         parse(dmarc)
       end
     end
 
+    #
+    # @deprecated Use {lookup}, which names what it returns. Kept for
+    #   compatibility; it will be removed in a future release.
+    #
+    # @see lookup
+    #
+    def self.query(domain,resolver=DMARCator.default_resolver)
+      lookup(domain, resolver: resolver)
+    end
+
     #
     # Converts the record to a Hash.
     #

data/lib/dmarcator/report.rb

@@ -78,7 +78,9 @@ module DMARCator
     # @return [BigDecimal, nil]
     #
     def version
-      @version ||= begin
+      return @version if defined?(@version)
+
+      @version = begin
         value = get_text('feedback/version')
 
         if value && !value.empty?

data/lib/dmarcator/resolver/doh.rb

@@ -25,6 +25,12 @@ module DMARCator
       # Default connect/read timeout in seconds.
       DEFAULT_TIMEOUT = 5
 
+      # Maximum accepted response body in bytes (the DNS message limit).
+      MAX_RESPONSE_BYTES = 65_535
+
+      # Media type RFC 8484 requires for DNS messages.
+      CONTENT_TYPE = 'application/dns-message'
+
       # @return [URI::HTTPS] the DoH endpoint.
       attr_reader :url
 
@@ -92,8 +98,8 @@ module DMARCator
         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['content-type'] = CONTENT_TYPE
+        request['accept'] = CONTENT_TYPE
         request.body = query.encode
 
         response = http.start { |connection| connection.request(request) }
@@ -104,7 +110,20 @@ module DMARCator
           raise ResolutionError, "DoH endpoint returned HTTP #{status}"
         end
 
-        response.body.to_s.b
+        content_type = response['content-type'].to_s
+
+        unless content_type.start_with?(CONTENT_TYPE)
+          raise ResolutionError, "DoH endpoint returned unexpected content-type: #{content_type.inspect}"
+        end
+
+        body = response.body.to_s.b
+
+        if body.bytesize > MAX_RESPONSE_BYTES
+          raise ResolutionError,
+                "DoH response exceeds maximum size of #{MAX_RESPONSE_BYTES} bytes"
+        end
+
+        body
       rescue ResolutionError
         raise
       rescue StandardError => error

data/lib/dmarcator/resolver.rb

@@ -61,7 +61,9 @@ module DMARCator
 
       case name
       when 'plaintext'
-        Resolv::DNS.new
+        resolver = Resolv::DNS.new
+        resolver.timeouts = DNS_TIMEOUTS
+        resolver
       when 'doh'
         DoH.from_env(env)
       when 'dot'

data/lib/dmarcator/uri.rb

@@ -118,19 +118,24 @@ module DMARCator
     private
 
     #
-    # Pass all missing methods to {#uri}.
+    # Pass public methods through to {#uri}.
+    #
+    # Private methods are not forwarded: delegation is limited to the wrapped
+    # URI's public interface.
     #
     def method_missing(name,*arguments,&block)
-      @uri.send(name,*arguments,&block)
+      return super unless @uri.respond_to?(name)
+
+      @uri.public_send(name,*arguments,&block)
     end
 
     #
-    # Indicates whether a missing method can be handled by {#uri}.
+    # Indicates whether a missing public method can be handled by {#uri}.
     #
     # @return [Boolean]
     #
     def respond_to_missing?(name, include_private = false)
-      @uri.respond_to?(name, include_private) || super
+      @uri.respond_to?(name) || super
     end
 
   end

data/lib/dmarcator/version.rb

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

data/lib/dmarcator/xml_helper.rb

@@ -20,30 +20,6 @@ module DMARCator
       @node.at_xpath(xpath)&.text
     end
 
-    #
-    # Returns a Unix timestamp as a `Time`.
-    #
-    # @param [String] xpath
-    #   The XPath expression to match.
-    #
-    # @return [Time, nil]
-    #
-    def get_timestamp(xpath)
-      parse_timestamp(get_text(xpath))
-    end
-
-    #
-    # Returns an integer value.
-    #
-    # @param [String] xpath
-    #   The XPath expression to match.
-    #
-    # @return [Integer, nil]
-    #
-    def get_int(xpath)
-      parse_integer(get_text(xpath))
-    end
-
     #
     # Parses a Unix timestamp from raw element text.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Noah Berman
@@ -92,6 +92,8 @@ licenses:
 metadata:
   source_code_uri: https://github.com/bermannoah/dmarcator
   bug_tracker_uri: https://github.com/bermannoah/dmarcator/issues
+  changelog_uri: https://github.com/bermannoah/dmarcator/blob/main/ChangeLog.md
+  documentation_uri: https://rubydoc.info/gems/dmarcator
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: