dmarcator 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50fb6579de6a2c481e5154bd28500cdb8c9800ba6897cd6aa76952c985531f22
-  data.tar.gz: d36d360f6d6cfe6e022cca51af4eec27c03349951c6259b486e178d31d2e32ad
+  metadata.gz: dfd0c6f8b9f84d311a49c5ad8a6b0e43618bd151ebd9cb7532a76486f4ea600a
+  data.tar.gz: 1b0eb0947c60844e369594d4c28e68510a91246faceb4a099f2c08dd7391a3fa
 SHA512:
-  metadata.gz: 8aaea7f0723b6a2eb070345ba516e09b0b6a0391d35c19349eab9791b72ddc06b90f149706c8bf988f3c80784cfe47319577f3c10d190592c482c84320e4962d
-  data.tar.gz: bafee6506fdd045ff918bcbb89a7553fd761bcbbdd91eb274d737dc02d87b14014a5011566799f570197dbc0ffd71cc37872f3cf915eadeda8022c591e594b97
+  metadata.gz: a151f9aabc45f12dc8107a0d4fb8c61bcb4f66880698045ba6df8dc97664f4840db0dc98af62fce3f2c77243f9250ee0df6d886908816a71b853d55f94d4ca8a
+  data.tar.gz: 7d7d50f10d95e4d762e8a8f3f1deb9fab301f690b942e65f77129f0ee633afa108281a86947ac6fe81a59e8062fe62f51e9b492ab0f2e08940b6483ad27f8248

data/ChangeLog.md

@@ -1,3 +1,21 @@
+### 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).
+* 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.

data/README.md

@@ -93,6 +93,11 @@ record = DMARCator::Record.query("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.
+
 ## Strict parsing
 
 By default, unknown tags and tags with invalid values are ignored. Pass
@@ -149,9 +154,11 @@ 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:
 
@@ -177,6 +184,12 @@ 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. Plaintext lookups fail closed the same way. DoH responses must be
+  `application/dns-message` and are capped at 65,535 bytes.
 
 ## Requirements
 

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
 

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

@@ -104,11 +104,11 @@ module DMARCator
   #   plaintext resolvers receive {DNS_TIMEOUTS}.
   #
   # @return [String, nil]
-  #   The domain's DMARC record or `nil` if none exists.
+  #   The domain's DMARC record, or `nil` if the domain simply has none.
   #
-  # @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. A failure is never reported as a missing record, so a
+  #   blocked or degraded resolver cannot silently enforce no policy.
   #
   # @api semipublic
   #
@@ -121,10 +121,13 @@ module DMARCator
 
     host = "_dmarc.#{domain}"
 
+    # 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
+    rescue Resolv::ResolvError => error
+      raise ResolutionError, "DNS lookup failed for #{host}: #{error.message}"
     end
 
     # Per RFC 7489 §6.6.3, use the TXT record beginning with "v=DMARC1".

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]
@@ -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
 

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/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/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.0'
+  VERSION = '0.7.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.
     #

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.6.0
+  version: 0.7.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: