dmarcator 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 689cd037f395f7803f4157fd148305f1d9d6c3dbb19fd42b61311b8e37d57124
-  data.tar.gz: 80518a23a140cb7102cb4d20a5fa896852ca8b104a3047939bcf4ba018e89699
+  metadata.gz: b6c289ca56b406c5f591f414ada16407028e732310ad9b4c784e2f231469828a
+  data.tar.gz: 24f260da56f98e045d262bd5fcbe3ee9d3f8be1b1bdd310e26e8b9b4b74f1021
 SHA512:
-  metadata.gz: c3b5f59702e05d0ffeeec17c9c3e7f8c1bd078448ba029fd4cf6bc8e6cbd8107dbda2e3633c228d1706f09832023a8a64b9806d6ee843b1fe13d449b19379e0c
-  data.tar.gz: de98c5111a0eb8023fa10807c7227d18bead12e17f2f43d084d8c5e3d27a2b1a4e86212c0c075fa2e75a97e5710e738de2baad45b833c31249d54a1abec80bb2
+  metadata.gz: f88871eab61d67fcccbe7ac0e6f0dfc8f97160592d97e69e58a69d9d99b069ec02e70b9126a0dc7ae114c9e50d599a0ca014ba9b02fc2514fab7db97c4bd4a08
+  data.tar.gz: 2d10f64bd4cd096f54ba2a6372a07c582dc3aad581fe556a3228be4378ba09bd9e3e5ba57c94a4cd98acc4b87899ded063ab9b886b73390267659754713297bb

data/ChangeLog.md

@@ -1,3 +1,25 @@
+### 0.12.0 / 2026-10-29
+
+Breaking changes, taken before 1.0:
+
+* `Report#version` returns the published value as a String instead of a `BigDecimal`, and the `bigdecimal` runtime dependency is gone. A non-numeric version still yields `nil`.
+* Parsed report objects (`Report::Metadata`, `Policy`, `Row`, `AuthResult`, `Reason`) are read-only. Their attributes were previously writable, which allowed a parsed report to be mutated into a state that never came from the document.
+* `Report.max_report_bytes` now delegates to `DMARCator.config.max_report_bytes`. The class-level accessors remain, so existing callers keep working; `Config#max_report_bytes` defaults to 25 MiB and rejects values that are not a positive Integer or nil.
+
+Other changes:
+
+* `DMARCator::XmlHelper` methods are private to including classes, `Record.truncate_error_message` is private, and `DMARCator::Parser` is documented as `@api private`.
+* Add an API-contract spec that pins the public surface of every public class, so additions and removals are deliberate.
+* Add `SECURITY.md` and document the stability, thread-safety and deprecation policies in the README.
+
+Migration:
+
+| Before | After |
+|---|---|
+| `report.version == BigDecimal("0.1")` | `report.version == "0.1"` |
+| `report.policy.pct = 50` | assign nothing; parsed values are read-only |
+| `Report.max_report_bytes = n` | `DMARCator.configure { |c| c.max_report_bytes = n }` |
+
 ### 0.11.0 / 2026-10-29
 
 * Add `DMARCator.configure` for process-wide defaults, so a resolver can be set from code instead of only through the `DMARCATOR_DNS` environment variables. A configured resolver takes precedence over the environment, and `DMARCator.reset_configuration!` discards it.

data/README.md

@@ -201,6 +201,7 @@ Process-wide defaults can be set from code, and take precedence over the
 ```ruby
 DMARCator.configure do |config|
   config.resolver = DMARCator::Resolver::DoH.new(url: "https://dns.example/dns-query")
+  config.max_report_bytes = 5 * 1024 * 1024
 end
 ```
 
@@ -236,7 +237,7 @@ Parse a DMARC aggregate/forensic report:
 report = DMARCator::Report.new(xml_string)
 
 report.version
-# => 0.1e0
+# => "0.1"
 
 report.metadata.org_name
 # => "google.com"
@@ -287,18 +288,44 @@ resolver = DMARCator::Resolver::DoH.new(url: "https://dns.example/dns-query")
 record   = DMARCator::Record.lookup("example.com", resolver: resolver)
 ```
 
+## Stability
+
+The public API is pinned by a contract spec in the test suite: the module
+methods, constants and per-class public methods it asserts are the supported
+surface. Anything marked `@api private` in the documentation — the parser, the
+XML helper, the internal resolver plumbing — may change in a minor release.
+
+### Thread safety
+
+* `DMARCator::Record`, `DMARCator::Report` and the parsed value objects are
+  read-only after construction and safe to share between threads.
+* The memoized parser and transform are shared, and safe for concurrent use.
+* Resolvers are not necessarily safe for concurrent lookups: `Resolv::DNS` does
+  not serialise queries. Use one resolver per thread, or configure a factory
+  with `DMARCator.configure` so each lookup builds its own.
+* `DMARCator.configure` mutates process-wide state. Call it during boot rather
+  than per request.
+
+### Deprecations
+
+A method is deprecated in a minor release by documentation only — no runtime
+warnings, so nothing is added to application logs. Deprecated methods are
+removed in the next major release.
+
 ## Security
 
-DMARC records and XML reports are treated as untrusted input:
+DMARC records and XML reports are treated as untrusted input. See
+[SECURITY.md](https://github.com/bermannoah/dmarcator/blob/main/SECURITY.md)
+for the reporting policy and scope.
 
 * XML reports are parsed with network access disabled (`NONET`), so external
   entities are never resolved or fetched.
-* Reports larger than `DMARCator::Report.max_report_bytes` (25 MiB by
+* Reports larger than `DMARCator.config.max_report_bytes` (25 MiB by
   default) are rejected before parsing. Parsing builds a DOM roughly 13× the
   input size, so lower the limit to bound memory:
 
   ```ruby
-  DMARCator::Report.max_report_bytes = 5 * 1024 * 1024
+  DMARCator.configure { |config| config.max_report_bytes = 5 * 1024 * 1024 }
   ```
 * A warning is emitted at load time if the bundled `resolv` gem is affected by
   CVE-2026-80212/CVE-2026-80213.
@@ -316,7 +343,6 @@ DMARC records and XML reports are treated as untrusted input:
 * [Ruby] >= 3.3.13
 * [parslet] >= 1.0.0, < 3.0.0
 * [nokogiri] >= 1.10
-* [bigdecimal] >= 1.0
 
 ## Testing
 
@@ -386,5 +412,4 @@ created by D Salko and released under the MIT License.
 [Ruby]: https://www.ruby-lang.org
 [parslet]: https://kschiess.github.io/parslet/
 [nokogiri]: https://nokogiri.org
-[bigdecimal]: https://github.com/ruby/bigdecimal
 [LICENSE.txt]: LICENSE.txt

data/lib/dmarcator/config.rb

@@ -7,6 +7,15 @@ module DMARCator
   # @since 0.11.0
   #
   class Config
+    # Default maximum accepted report size in bytes (25 MiB).
+    #
+    # Parsing a report builds a DOM roughly 13x the input size, so this bounds
+    # the memory a hostile report can cost.
+    #
+    # @since 0.12.0
+    #
+    DEFAULT_MAX_REPORT_BYTES = 25 * 1024 * 1024
+
     #
     # The default resolver used when a lookup is not given one.
     #
@@ -18,6 +27,36 @@ module DMARCator
     # @return [Object, #call, nil]
     #
     attr_accessor :resolver
+
+    #
+    # The maximum accepted report size in bytes.
+    #
+    # Defaults to {DEFAULT_MAX_REPORT_BYTES}. Lower it to bound memory for
+    # reports from untrusted sources.
+    #
+    # @return [Integer]
+    #
+    def max_report_bytes
+      @max_report_bytes || DEFAULT_MAX_REPORT_BYTES
+    end
+
+    #
+    # Sets the maximum accepted report size in bytes.
+    #
+    # @param [Integer, nil] value
+    #   A positive number of bytes, or `nil` to restore the default.
+    #
+    # @raise [ArgumentError]
+    #   The value is not a positive Integer or nil.
+    #
+    def max_report_bytes=(value)
+      unless value.nil? || (value.is_a?(Integer) && value.positive?)
+        raise ArgumentError,
+              "max_report_bytes must be a positive Integer or nil, got #{value.inspect}"
+      end
+
+      @max_report_bytes = value
+    end
   end
 
   #

data/lib/dmarcator/parser.rb

@@ -10,6 +10,10 @@ module DMARCator
   #
   # DMARC parser.
   #
+  # An implementation detail: use {Record.parse} rather than this class.
+  #
+  # @api private
+  #
   # @see https://tools.ietf.org/html/rfc7489#section-6.4
   #
   class Parser < Parslet::Parser

data/lib/dmarcator/record.rb

@@ -312,6 +312,8 @@ module DMARCator
       end
     end
 
+    private_class_method :truncate_error_message
+
     #
     # Looks up and parses the DMARC record for a domain.
     #

data/lib/dmarcator/report/auth_result.rb

@@ -13,32 +13,32 @@ module DMARCator
       # Attribute names exposed by this class.
       ATTRIBUTES = [:type, :domain, :result, :selector, :scope]
 
-      # @!attribute [rw] type
+      # @!attribute [r] type
       #   @return [String] the entry name (`dkim` or `spf`).
-      # @!attribute [rw] domain
+      # @!attribute [r] domain
       #   @return [String, nil] the authenticated domain.
-      # @!attribute [rw] result
+      # @!attribute [r] result
       #   @return [String, nil] the authentication result.
-      # @!attribute [rw] selector
+      # @!attribute [r] selector
       #   @return [String, nil] the DKIM selector.
-      # @!attribute [rw] scope
+      # @!attribute [r] scope
       #   @return [String, nil] the SPF scope.
-      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
+      ATTRIBUTES.each { |attribute| attr_reader(attribute) }
 
       def initialize(node)
         @node = node
-        self.type = node.name
+        @type = node.name
 
         node.element_children.each do |element|
           case element.name
           when 'domain'
-            self.domain ||= element.text
+            @domain ||= element.text
           when 'result'
-            self.result ||= element.text
+            @result ||= element.text
           when 'selector'
-            self.selector ||= element.text
+            @selector ||= element.text
           when 'scope'
-            self.scope ||= element.text
+            @scope ||= element.text
           end
         end
       end

data/lib/dmarcator/report/metadata.rb

@@ -16,25 +16,25 @@ module DMARCator
         :begin_at, :end_at, :errors
       ]
 
-      # @!attribute [rw] org_name
+      # @!attribute [r] org_name
       #   @return [String, nil] the reporting organization.
-      # @!attribute [rw] email
+      # @!attribute [r] email
       #   @return [String, nil] the reporting organization's contact address.
-      # @!attribute [rw] extra_contact_info
+      # @!attribute [r] extra_contact_info
       #   @return [String, nil] additional contact information.
-      # @!attribute [rw] report_id
+      # @!attribute [r] report_id
       #   @return [String, nil] the unique report identifier.
-      # @!attribute [rw] begin_at
+      # @!attribute [r] begin_at
       #   @return [Time, nil] the start of the reporting interval.
-      # @!attribute [rw] end_at
+      # @!attribute [r] end_at
       #   @return [Time, nil] the end of the reporting interval.
-      # @!attribute [rw] errors
+      # @!attribute [r] errors
       #   @return [Array<String>] errors reported by the reporting organization.
-      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
+      ATTRIBUTES.each { |attribute| attr_reader(attribute) }
 
       def initialize(node)
         @node = node
-        self.errors = []
+        @errors = []
 
         metadata = node.at_xpath('feedback/report_metadata')
         return unless metadata
@@ -42,13 +42,13 @@ module DMARCator
         metadata.element_children.each do |element|
           case element.name
           when 'org_name'
-            self.org_name ||= element.text
+            @org_name ||= element.text
           when 'email'
-            self.email ||= element.text
+            @email ||= element.text
           when 'extra_contact_info'
-            self.extra_contact_info ||= element.text
+            @extra_contact_info ||= element.text
           when 'report_id'
-            self.report_id ||= element.text
+            @report_id ||= element.text
           when 'error'
             errors << element.text
           when 'date_range'
@@ -63,9 +63,9 @@ module DMARCator
         date_range.element_children.each do |element|
           case element.name
           when 'begin'
-            self.begin_at ||= parse_timestamp(element.text)
+            @begin_at ||= parse_timestamp(element.text)
           when 'end'
-            self.end_at ||= parse_timestamp(element.text)
+            @end_at ||= parse_timestamp(element.text)
           end
         end
       end

data/lib/dmarcator/report/policy.rb

@@ -13,21 +13,21 @@ module DMARCator
       # Attribute names exposed by this class.
       ATTRIBUTES = [:domain, :adkim, :aspf, :p, :sp, :pct, :fo]
 
-      # @!attribute [rw] domain
+      # @!attribute [r] domain
       #   @return [String, nil] the domain the policy applies to.
-      # @!attribute [rw] adkim
+      # @!attribute [r] adkim
       #   @return [String, nil] the DKIM alignment mode (`r` or `s`).
-      # @!attribute [rw] aspf
+      # @!attribute [r] aspf
       #   @return [String, nil] the SPF alignment mode (`r` or `s`).
-      # @!attribute [rw] p
+      # @!attribute [r] p
       #   @return [String, nil] the requested policy.
-      # @!attribute [rw] sp
+      # @!attribute [r] sp
       #   @return [String, nil] the requested subdomain policy.
-      # @!attribute [rw] pct
+      # @!attribute [r] pct
       #   @return [Integer, nil] the percentage of messages the policy applied to.
-      # @!attribute [rw] fo
+      # @!attribute [r] fo
       #   @return [String, nil] the requested failure-reporting options.
-      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
+      ATTRIBUTES.each { |attribute| attr_reader(attribute) }
 
       def initialize(node)
         @node = node
@@ -38,19 +38,19 @@ module DMARCator
         policy.element_children.each do |element|
           case element.name
           when 'pct'
-            self.pct ||= parse_integer(element.text)
+            @pct ||= parse_integer(element.text)
           when 'domain'
-            self.domain ||= element.text
+            @domain ||= element.text
           when 'adkim'
-            self.adkim ||= element.text
+            @adkim ||= element.text
           when 'aspf'
-            self.aspf ||= element.text
+            @aspf ||= element.text
           when 'p'
-            self.p ||= element.text
+            @p ||= element.text
           when 'sp'
-            self.sp ||= element.text
+            @sp ||= element.text
           when 'fo'
-            self.fo ||= element.text
+            @fo ||= element.text
           end
         end
       end

data/lib/dmarcator/report/reason.rb

@@ -13,11 +13,11 @@ module DMARCator
       # Attribute names exposed by this class.
       ATTRIBUTES = [:type, :comment]
 
-      # @!attribute [rw] type
+      # @!attribute [r] type
       #   @return [String, nil] the reason type.
-      # @!attribute [rw] comment
+      # @!attribute [r] comment
       #   @return [String, nil] an optional explanatory comment.
-      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
+      ATTRIBUTES.each { |attribute| attr_reader(attribute) }
 
       def initialize(node)
         @node = node
@@ -25,9 +25,9 @@ module DMARCator
         node.element_children.each do |element|
           case element.name
           when 'type'
-            self.type ||= element.text
+            @type ||= element.text
           when 'comment'
-            self.comment ||= element.text
+            @comment ||= element.text
           end
         end
       end

data/lib/dmarcator/report/row.rb

@@ -21,24 +21,23 @@ module DMARCator
         :envelope_to, :envelope_from, :header_from
       ]
 
-      # @!attribute [rw] source_ip
+      # @!attribute [r] source_ip
       #   @return [String, nil] the sending IP address.
-      # @!attribute [rw] count
+      # @!attribute [r] count
       #   @return [Integer, nil] the number of messages from this source.
-      # @!attribute [rw] disposition
+      # @!attribute [r] disposition
       #   @return [String, nil] the action applied to the messages.
-      # @!attribute [rw] dkim
+      # @!attribute [r] dkim
       #   @return [String, nil] the DKIM evaluation result.
-      # @!attribute [rw] spf
+      # @!attribute [r] spf
       #   @return [String, nil] the SPF evaluation result.
-      # @!attribute [rw] envelope_to
+      # @!attribute [r] envelope_to
       #   @return [String, nil] the envelope recipient domain.
-      # @!attribute [rw] envelope_from
+      # @!attribute [r] envelope_from
       #   @return [String, nil] the envelope sender domain.
-      # @!attribute [rw] header_from
+      # @!attribute [r] header_from
       #   @return [String, nil] the `From` header domain.
-      ATTRIBUTES.each { |attribute| attr_accessor(attribute) }
-      attr_writer :auth_results, :reasons
+      ATTRIBUTES.each { |attribute| attr_reader(attribute) }
 
       def initialize(node)
         @node = node
@@ -87,9 +86,9 @@ module DMARCator
         row.element_children.each do |element|
           case element.name
           when 'source_ip'
-            self.source_ip ||= element.text
+            @source_ip ||= element.text
           when 'count'
-            self.count ||= parse_integer(element.text)
+            @count ||= parse_integer(element.text)
           when 'policy_evaluated'
             parse_policy_evaluated(element)
           end
@@ -100,11 +99,11 @@ module DMARCator
         policy_evaluated.element_children.each do |element|
           case element.name
           when 'disposition'
-            self.disposition ||= element.text
+            @disposition ||= element.text
           when 'dkim'
-            self.dkim ||= element.text
+            @dkim ||= element.text
           when 'spf'
-            self.spf ||= element.text
+            @spf ||= element.text
           when 'reason'
             @reason_nodes << element
           end
@@ -115,11 +114,11 @@ module DMARCator
         identifiers.element_children.each do |element|
           case element.name
           when 'envelope_to'
-            self.envelope_to ||= element.text
+            @envelope_to ||= element.text
           when 'envelope_from'
-            self.envelope_from ||= element.text
+            @envelope_from ||= element.text
           when 'header_from'
-            self.header_from ||= element.text
+            @header_from ||= element.text
           end
         end
       end

data/lib/dmarcator/report.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 require 'nokogiri'
-require 'bigdecimal'
-require 'bigdecimal/util'
 
+require_relative 'config'
 require_relative 'xml_helper'
 require_relative 'exceptions'
 require_relative 'report/metadata'
@@ -21,22 +20,35 @@ module DMARCator
     include XmlHelper
 
     # Default maximum accepted report size in bytes (25 MiB).
-    MAX_REPORT_BYTES = 25 * 1024 * 1024
+    #
+    # @deprecated Use {Config::DEFAULT_MAX_REPORT_BYTES}.
+    #
+    MAX_REPORT_BYTES = Config::DEFAULT_MAX_REPORT_BYTES
 
     class << self
       #
       # The maximum accepted report size in bytes.
       #
-      # Defaults to {MAX_REPORT_BYTES}. Parsing a report builds a DOM that is
-      # roughly 13x the input size, so lower this to bound memory for reports
-      # from untrusted sources.
+      # @deprecated Use {DMARCator.configure} with `config.max_report_bytes`.
       #
       # @return [Integer]
       #
-      attr_writer :max_report_bytes
-
       def max_report_bytes
-        @max_report_bytes || MAX_REPORT_BYTES
+        DMARCator.config.max_report_bytes
+      end
+
+      #
+      # Sets the maximum accepted report size in bytes.
+      #
+      # @deprecated Use {DMARCator.configure} with `config.max_report_bytes`.
+      #
+      # @param [Integer, nil] value
+      #
+      # @raise [ArgumentError]
+      #   The value is not a positive Integer or nil.
+      #
+      def max_report_bytes=(value)
+        DMARCator.config.max_report_bytes = value
       end
     end
 
@@ -47,8 +59,8 @@ module DMARCator
     #   The raw DMARC XML report.
     #
     # @raise [InvalidReport]
-    #   The report is not a String, exceeds {.max_report_bytes}, or is not
-    #   well-formed XML.
+    #   The report is not a String, exceeds
+    #   {Config#max_report_bytes}, or is not well-formed XML.
     #
     def initialize(xml)
       unless xml.is_a?(String)
@@ -57,7 +69,7 @@ module DMARCator
 
       @xml = xml
 
-      limit = self.class.max_report_bytes
+      limit = DMARCator.config.max_report_bytes
 
       if xml.bytesize > limit
         raise InvalidReport, "DMARC XML report exceeds maximum size of #{limit} bytes"
@@ -73,23 +85,22 @@ module DMARCator
     end
 
     #
-    # The report version.
+    # The report version, as published.
+    #
+    # Returned as a String because versions are opaque identifiers, not
+    # numbers to compute with.
     #
-    # @return [BigDecimal, nil]
+    # @return [String, nil]
+    #   The version, or `nil` when it is absent or not numeric.
     #
     def version
       return @version if defined?(@version)
 
       @version = begin
         value = get_text('feedback/version')
+        value = value.strip if value
 
-        if value && !value.empty?
-          begin
-            BigDecimal(value)
-          rescue ArgumentError
-            nil
-          end
-        end
+        value if value && value.match?(/\A\d+(?:\.\d+)*\z/)
       end
     end
 

data/lib/dmarcator/version.rb

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '0.11.0'
+  VERSION = '0.12.0'
 end

data/lib/dmarcator/xml_helper.rb

@@ -7,6 +7,8 @@ module DMARCator
   # Internal helper for extracting values from parsed DMARC XML reports.
   #
   module XmlHelper
+    private
+
     #
     # Returns the text of the first node matching the XPath expression.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Noah Berman
@@ -43,20 +43,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.10'
-- !ruby/object:Gem::Dependency
-  name: bigdecimal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.0'
 description: A hardened DMARC record parser and query client, forked from the Trail
   of Bits 'dmarc' gem.
 email: