dmarcator 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50fb6579de6a2c481e5154bd28500cdb8c9800ba6897cd6aa76952c985531f22
-  data.tar.gz: d36d360f6d6cfe6e022cca51af4eec27c03349951c6259b486e178d31d2e32ad
+  metadata.gz: ab57f0c6599df86ed3331199b84f0abdd9aae8876405e4205f2070b9e457b5ca
+  data.tar.gz: 5466098000ff91848f6cb8208606ed8b3312eb9b476763074d917b3f7f377aca
 SHA512:
-  metadata.gz: 8aaea7f0723b6a2eb070345ba516e09b0b6a0391d35c19349eab9791b72ddc06b90f149706c8bf988f3c80784cfe47319577f3c10d190592c482c84320e4962d
-  data.tar.gz: bafee6506fdd045ff918bcbb89a7553fd761bcbbdd91eb274d737dc02d87b14014a5011566799f570197dbc0ffd71cc37872f3cf915eadeda8022c591e594b97
+  metadata.gz: 71c83a39fc17926997e43465ef07210a7a062a67b922462623e4d6c0daa617acefc4ec2546194ffa2f6755bf62321504134140b5e35813ac9e34b8ed43abbf89
+  data.tar.gz: ebdc8623cdba9d7632188a52fbdc203d7c1f85efed580f72ce5ceebeafd8a7c5eae4f5f0797d8960b1a6fb5e1b2af9aeb9d5484ffc74a5f8adc4942af4de286a

data/ChangeLog.md

@@ -1,3 +1,11 @@
+### 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

@@ -177,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
 

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

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/version.rb

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '0.6.0'
+  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.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Noah Berman