dmarcator 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfd0c6f8b9f84d311a49c5ad8a6b0e43618bd151ebd9cb7532a76486f4ea600a
-  data.tar.gz: 1b0eb0947c60844e369594d4c28e68510a91246faceb4a099f2c08dd7391a3fa
+  metadata.gz: f4c6e25ca7a0fc2d77204c72ebb01906fce1ac4b537b1e011e505ed2938dda2b
+  data.tar.gz: 36f390d4c0e42c5e938df0345e9d412de2b09aed29da9ca83a424414090b88f1
 SHA512:
-  metadata.gz: a151f9aabc45f12dc8107a0d4fb8c61bcb4f66880698045ba6df8dc97664f4840db0dc98af62fce3f2c77243f9250ee0df6d886908816a71b853d55f94d4ca8a
-  data.tar.gz: 7d7d50f10d95e4d762e8a8f3f1deb9fab301f690b942e65f77129f0ee633afa108281a86947ac6fe81a59e8062fe62f51e9b492ab0f2e08940b6483ad27f8248
+  metadata.gz: 8f3db5da3231a84613e3a938d3e294f01da16df7aee2e633ba321e0002a8278ec28755accb08a1db2e6c72f2d0424cb34ea019b3168b32872503f59dddb6eaa4
+  data.tar.gz: 28d72632daef6199571fd1cd461c112610ebd14bd45a03b48c6b9127f571e82f8431ad35331e4c05d52482b2b5d085bb973a51aa37a888ede498b8b7a85f4eac

data/ChangeLog.md

@@ -1,3 +1,14 @@
+### 0.9.0 / 2026-10-29
+
+* Add `DMARCator.txt_records`, which returns the TXT resource records instead of strings, so callers that cache lookups can read each record's `ttl`. `DMARCator.txt` is now defined in terms of it and behaves the same.
+
+### 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.

data/README.md

@@ -89,7 +89,7 @@ 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=[...], ...>
 ```
 
@@ -98,6 +98,85 @@ Domains must be ASCII (A-labels): pass punycode such as
 `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_records(name)` | `Array<Resolv::DNS::Resource::IN::TXT>` — the records themselves | one lookup |
+| `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
+```
+
+Use `DMARCator.txt_records` when you need the DNS TTL, for example to cache
+lookups in a database:
+
+```ruby
+records = DMARCator.txt_records("_dmarc.#{domain}")
+records.each do |record|
+  record.strings.join  # the TXT value
+  record.ttl           # seconds the answer may be cached
+end
+```
+
+All of these 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.txt_records("_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
@@ -164,7 +243,7 @@ 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
@@ -216,8 +295,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
@@ -227,6 +310,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,50 +139,151 @@ 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)
+    txt_records(name, resolver: resolver).map { |record| record.strings.join }
+  end
+
+  #
+  # Looks up every TXT record at a DNS name, returning the resource records
+  # themselves.
+  #
+  # Like {txt}, but without flattening to strings. The records expose
+  # `strings` and `ttl`, which matters when caching results: use
+  # `record.ttl` to decide how long an answer may be reused.
+  #
+  # @param [String] name
+  #   The DNS name to look up.
+  #
+  # @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<Resolv::DNS::Resource::IN::TXT>]
+  #   The 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.
+  #
+  # @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.9.0
+  #
+  def self.txt_records(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 the domain simply has none.
+  #   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 [ResolutionError]
-  #   The lookup failed. A failure is never reported as a missing record, so a
-  #   blocked or degraded resolver cannot silently enforce no policy.
+  #   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)}"
+
+    # 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).map do |record|
+      record.strings.join
+    end.select do |text|
+      text.start_with?('v=DMARC1')
+    end
 
-    resolver.timeouts = DNS_TIMEOUTS if resolver.respond_to?(:timeouts=)
+    dmarc_records.first if dmarc_records.one?
+  end
 
-    host = "_dmarc.#{domain}"
+  #
+  # @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}, {txt_records} and {dmarc} so they use one transport path.
+  #
+  # @param [String] name
+  #
+  # @param [Resolv::DNS, Resolver::DoH, Resolver::DoT] resolver
+  #
+  # @return [Array<Resolv::DNS::Resource::IN::TXT>]
+  #
+  # @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)
+      records = resolver.getresources(name, Resolv::DNS::Resource::IN::TXT)
     rescue Resolv::ResolvError => error
-      raise ResolutionError, "DNS lookup failed for #{host}: #{error.message}"
+      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
   end
+  private_class_method :lookup_txt
 end
 
 if DMARCator.vulnerable_resolv?

data/lib/dmarcator/record.rb

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

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '0.7.0'
+  VERSION = '0.9.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Noah Berman