dmarcator 0.11.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 689cd037f395f7803f4157fd148305f1d9d6c3dbb19fd42b61311b8e37d57124
-  data.tar.gz: 80518a23a140cb7102cb4d20a5fa896852ca8b104a3047939bcf4ba018e89699
+  metadata.gz: 6f88c01ff39e839792769a66063bd78cd312f51d5fba6917acf6777d034e0269
+  data.tar.gz: 9b39f980958757f2a27718d157ad9925424a20da358a7100d3b87f9a3765af5f
 SHA512:
-  metadata.gz: c3b5f59702e05d0ffeeec17c9c3e7f8c1bd078448ba029fd4cf6bc8e6cbd8107dbda2e3633c228d1706f09832023a8a64b9806d6ee843b1fe13d449b19379e0c
-  data.tar.gz: de98c5111a0eb8023fa10807c7227d18bead12e17f2f43d084d8c5e3d27a2b1a4e86212c0c075fa2e75a97e5710e738de2baad45b833c31249d54a1abec80bb2
+  metadata.gz: 4c5aa75a034fedffc21ad9100de83b82f049dc08416f66cdcf2056ec6f76a8f28415ccfee012ea6432d4cbbbd760279c5a0dbce32d614f0932a0d8e9cd9efa3e
+  data.tar.gz: c1351578b215094ca74bb710725f2b66ad49f8e1c24ba14862ee32bc11099163f0d0e8cbb0736f5d23a614b6d1b801ea4fa9cd52e0a3f521f13ffffa21959897

data/ChangeLog.md

@@ -1,3 +1,36 @@
+### 1.0.0 / 2026-10-30
+
+The public API is now frozen.
+
+* The contract spec added in 0.12.0 defines the supported surface: the module methods, constants and per-class public methods it asserts. Anything documented as `@api private` may still change in a minor release.
+* Deprecations are documentation-only, and removals happen only in a major release. `Report.max_report_bytes`, `Report.max_report_bytes=` and `Report::MAX_REPORT_BYTES` are deprecated in favour of `DMARCator.configure` and `Config::DEFAULT_MAX_REPORT_BYTES`, and will be removed in 2.0.
+* Supported Ruby is `>= 3.3.13`. Dropping a Ruby series is the one documented exception to the no-breaking-changes promise: it is announced in a minor release and removed in the next major.
+* Parsed report values are now frozen, not merely reader-only: the strings taken from the document and the arrays holding records, errors, reasons, auth results and the parsed record's `rua`/`ruf`/`fo` cannot be mutated in place. `Record` and the report value objects are therefore safe to share between threads.
+* The parser and XML helper moved to `DMARCator::Internal`, so the public constants are only documented API and the parser can be replaced in a minor release.
+* Parsing, lookup and transport behaviour are unchanged from 0.12.0; the differences above are the freeze itself.
+
+### 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,51 @@ 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.
+
+### Ruby support
+
+The minimum is Ruby 3.3.13, the first release in that series with the regular
+expression fixes the library requires. Dropping support for a Ruby series is
+the one documented exception to the no-breaking-changes promise: it is announced
+in a minor release and removed in the next major.
+
 ## 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 +350,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 +419,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/internal/parser.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require_relative '../exceptions'
+require_relative '../uri'
+
+require 'parslet'
+require 'uri'
+
+module DMARCator
+  #
+  # Implementation details of the library. Nothing here is covered by the
+  # 1.0 compatibility promise.
+  #
+  # @api private
+  #
+  module Internal
+    #
+    # 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
+
+      # Maximum accepted DMARC record size in bytes. Real records are far
+      # smaller; the cap bounds parsing work on hostile input.
+      #
+      MAX_RECORD_BYTES = 4096
+
+      root :dmarc_record
+
+      rule(:dmarc_record) do
+        dmarc_version.repeat(1,1) >>
+        (dmarc_sep >> dmarc_tag).repeat >>
+        dmarc_sep.maybe >>
+        wsp?.maybe
+      end
+
+      rule(:dmarc_sep) { wsp? >> str(';') >> wsp? }
+
+      rule(:dmarc_version) do
+        str('v') >> wsp? >>
+        str('=') >> wsp? >>
+        str('DMARC1').as(:v)
+      end
+
+      rule(:dmarc_tag) do
+        dmarc_request   |
+        dmarc_srequest  |
+        dmarc_auri      |
+        dmarc_furi      |
+        dmarc_adkim     |
+        dmarc_aspf      |
+        dmarc_ainterval |
+        dmarc_fo        |
+        dmarc_rfmt      |
+        dmarc_percent   |
+        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
+          (
+            str(tag) >> wsp? >> str('=') >> wsp? >>
+            instance_eval(&block).as(tag.to_sym)
+          ) |
+          (
+            str(tag) >> wsp? >> str('=') >> wsp? >>
+            match["^; \t"].repeat(1)
+          ).as(:invalid_tag)
+        end
+      end
+
+      tag_rule(:request,'p') do
+        str('none') | str('quarantine') | str('reject')
+      end
+
+      tag_rule(:srequest,'sp') do
+        str('none') | str('quarantine') | str('reject')
+      end
+
+      tag_rule(:auri, 'rua') do
+        dmarc_uri >> (uri_list_sep.present? >> uri_list_sep).repeat >> (wsp? >> str(',')).absent?
+      end
+
+      tag_rule(:ainterval,'ri') { digit.repeat(1, 10) >> digit.absent? }
+
+      tag_rule(:furi,'ruf') do
+        dmarc_uri >> (uri_list_sep.present? >> uri_list_sep).repeat >> (wsp? >> str(',')).absent?
+      end
+
+      tag_rule(:fo,'fo') do
+        fo_opt >> (wsp? >> str(':') >> wsp? >> fo_opt).repeat
+      end
+
+      rule(:fo_opt) { match['01ds'].as(:fo_opt) }
+
+      tag_rule(:rfmt,'rf') { str('afrf') | str('iodef') }
+
+      tag_rule(:percent,'pct') { digit.repeat(1,3) >> digit.absent? }
+
+      tag_rule(:adkim, 'adkim') { match['rs'] }
+      tag_rule(:aspf, 'aspf')   { match['rs'] }
+
+      rule(:unknown_tag) { match["^; \t"].repeat(1).as(:unknown_tag) }
+
+      rule(:dmarc_uri) do
+        mailto_uri.as(:uri) >> (
+          str('!') >> digit.repeat(1, 10).as(:size) >> digit.absent? >> (
+            match['kmgt']
+          ).as(:unit).maybe
+        ).maybe >> str('!').absent?
+      end
+
+      rule(:uri_list_sep) { wsp? >> str(',') >> wsp? >> dmarc_uri }
+
+      rule(:mailto_uri) do
+        match['mM'] >> match['aA'] >> match['iI'] >> match['lL'] >> match['tT'] >> match['oO'] >>
+        str(':') >> mailto_address
+      end
+
+      rule(:mailto_address) do
+        mailto_local >> str('@') >> mailto_domain
+      end
+
+      rule(:mailto_local)  { mailto_char.repeat(1) }
+      rule(:mailto_domain) { mailto_char.repeat(1) }
+      rule(:mailto_char)   { match["A-Za-z0-9._%+-"] }
+
+      rule(:digit) { match('[0-9]') }
+      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 }
+        rule(fo: simple(:fo_opt)) { {fo: [fo_opt]} }
+
+        rule(v: simple(:version)) { {v: version.to_sym} }
+        rule(p:  simple(:p))  { {p:  p.to_sym } }
+        rule(sp: simple(:sp)) { {sp: sp.to_sym} }
+        rule(rf: simple(:rf)) { {rf: rf.to_sym} }
+        rule(adkim: simple(:adkim)) { {adkim: adkim.to_sym} }
+        rule(aspf:  simple(:aspf))  { {aspf: aspf.to_sym} }
+
+        rule(pct: simple(:pct)) { {pct: pct.to_i} }
+        rule(ri:  simple(:ri))  { {ri:  ri.to_i}  }
+
+        rule(uri: simple(:uri), size: simple(:size), unit: simple(:unit)) do
+          Uri.new(
+            Transform.parse_uri(uri),
+            size.to_i,
+            unit.to_sym
+          )
+        end
+        rule(uri: simple(:uri), size: simple(:size)) do
+          Uri.new(
+            Transform.parse_uri(uri),
+            size.to_i
+          )
+        end
+        rule(uri: simple(:uri)) { Uri.new(Transform.parse_uri(uri)) }
+        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
+
+          begin
+            parsed = URI.parse(uri)
+          rescue URI::Error => error
+            raise InvalidRecord, truncate(error.message)
+          end
+
+          unless parsed.is_a?(URI::MailTo)
+            raise InvalidRecord, "invalid DMARC report URI (expected mailto): #{truncate(uri)}"
+          end
+
+          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
+
+          if message.length > MAX_ERROR_MESSAGE_LENGTH
+            message[0, MAX_ERROR_MESSAGE_LENGTH] + "..."
+          else
+            message
+          end
+        end
+
+      end
+
+      #
+      # Parses a DMARC record.
+      #
+      # @param [String] record
+      #   The raw DMARC record to parse.
+      #
+      # @param [Boolean] strict (false)
+      #   When `true`, raise on unknown tags or invalid tag values instead of
+      #   silently ignoring them.
+      #
+      # @return [Hash{Symbol => Object}]
+      #   The Hash of tags within the record.
+      #
+      # @raise [InvalidRecord]
+      #   The record is not a String, is malformed, is too large, or (in strict
+      #   mode) contains an unknown tag or invalid tag value.
+      #
+      def self.parse(record, strict: false)
+        unless record.is_a?(String)
+          raise InvalidRecord, "DMARC record must be a String, got #{record.class}"
+        end
+
+        if record.bytesize > MAX_RECORD_BYTES
+          raise InvalidRecord, "DMARC record exceeds maximum size of #{MAX_RECORD_BYTES} bytes"
+        end
+
+        tree = parser.parse(record)
+
+        if strict
+          tree.each do |node|
+            next unless ignored?(node)
+
+            if node.key?(:unknown_tag)
+              raise InvalidRecord, "unknown DMARC tag: #{Transform.truncate(node[:unknown_tag].to_s).inspect}"
+            else
+              raise InvalidRecord, "invalid DMARC tag value: #{Transform.truncate(node[:invalid_tag].to_s).inspect}"
+            end
+          end
+        end
+
+        tags = transform.apply(tree.reject { |node| ignored?(node) })
+        hash = {}
+
+        tags.each do |tag|
+          tag.each_key do |key|
+            if hash.key?(key)
+              raise InvalidRecord, "duplicate DMARC tag: #{key}"
+            end
+          end
+
+          hash.merge!(tag)
+        end
+
+        validate!(hash)
+
+        return hash
+      end
+
+      #
+      # Determines whether a parse-tree node represents a tag that the lenient
+      # parser dropped because it was unknown or had an invalid value.
+      #
+      # @param [Object] node
+      #   The parse-tree node.
+      #
+      # @return [Boolean]
+      #
+      def self.ignored?(node)
+        node.is_a?(Hash) && (node.key?(:unknown_tag) || node.key?(:invalid_tag))
+      end
+
+      #
+      # The memoized parser instance. Parslet caches rules per instance, so
+      # reusing it avoids rebuilding the grammar on every call.
+      #
+      # @return [Parser]
+      #
+      # @api private
+      #
+      def self.parser
+        @parser ||= new
+      end
+
+      #
+      # The memoized transform instance.
+      #
+      # @return [Transform]
+      #
+      # @api private
+      #
+      def self.transform
+        @transform ||= Transform.new
+      end
+
+      #
+      # Validates the parsed tags.
+      #
+      # @param [Hash{Symbol => Object}] tags
+      #   The parsed tags.
+      #
+      # @raise [InvalidRecord]
+      #   One of the tags has an invalid value.
+      #
+      def self.validate!(tags)
+        if tags[:pct] && !(tags[:pct].is_a?(Integer) && tags[:pct].between?(0, 100))
+          raise InvalidRecord, "pct must be an integer between 0 and 100"
+        end
+
+        if tags[:ri] && !(tags[:ri].is_a?(Integer) && tags[:ri].between?(0, 2**32 - 1))
+          raise InvalidRecord, "ri must be an integer between 0 and 4294967295"
+        end
+      end
+
+    end
+  end
+end

data/lib/dmarcator/internal/xml_helper.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module DMARCator
+  #
+  # Implementation details of the library. Nothing here is covered by the
+  # 1.0 compatibility promise.
+  #
+  # @api private
+  #
+  module Internal
+    #
+    # Internal helper for extracting values from parsed DMARC XML reports.
+    #
+    module XmlHelper
+      private
+
+      #
+      # Returns the text of the first node matching the XPath expression.
+      #
+      # @param [String] xpath
+      #   The XPath expression to match.
+      #
+      # @return [String, nil]
+      #   The node text, or `nil` if no node matched.
+      #
+      def get_text(xpath)
+        @node.at_xpath(xpath)&.text
+      end
+
+      #
+      # Parses a Unix timestamp from raw element text.
+      #
+      # @param [String, nil] value
+      #   The element text.
+      #
+      # @return [Time, nil]
+      #
+      # @api private
+      #
+      def parse_timestamp(value)
+        seconds = parse_integer(value)
+
+        Time.at(seconds) if seconds
+      end
+
+      #
+      # Parses an integer from raw element text, returning `nil` for values that
+      # are not plain decimal digits.
+      #
+      # @param [String, nil] value
+      #   The element text.
+      #
+      # @return [Integer, nil]
+      #
+      # @api private
+      #
+      def parse_integer(value)
+        return nil if value.nil? || value.empty?
+
+        digits = value.strip
+        return nil unless digits.match?(/\A\d+\z/)
+
+        digits.to_i
+      end
+    end
+  end
+end

data/lib/dmarcator/record.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'dmarcator/query'
-require 'dmarcator/parser'
+require 'dmarcator/internal/parser'
 require 'dmarcator/exceptions'
 
 require 'resolv'
@@ -66,13 +66,13 @@ module DMARCator
       @v     = attributes.fetch(:v)
       @adkim = attributes[:adkim]
       @aspf  = attributes[:aspf]
-      @fo    = attributes[:fo]
+      @fo    = attributes[:fo]&.freeze
       @p     = attributes[:p]
       @pct   = attributes[:pct]
       @rf    = attributes[:rf]
       @ri    = attributes[:ri]
-      @rua   = attributes[:rua]
-      @ruf   = attributes[:ruf]
+      @rua   = attributes[:rua]&.freeze
+      @ruf   = attributes[:ruf]&.freeze
       @sp    = attributes[:sp]
     end
 
@@ -277,7 +277,7 @@ module DMARCator
     # @api public
     #
     def self.parse(record, strict: false)
-      attributes = Parser.parse(record, strict: strict)
+      attributes = Internal::Parser.parse(record, strict: strict)
 
       unless attributes[:p]
         raise InvalidRecord, "DMARC record is missing the required 'p' tag"
@@ -312,6 +312,8 @@ module DMARCator
       end
     end
 
+    private_class_method :truncate_error_message
+
     #
     # Looks up and parses the DMARC record for a domain.
     #