mailertogo-spf 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a2e188c35f296a679f4be3be3e89c2a6c15a3b1bedd4a9f3c8f2fe0bd8480cf
-  data.tar.gz: '0359e4412f1c81bf20e71b99a088dcd60b58b6125abadae058a2f2990a808296'
+  metadata.gz: 316234e7966e3e895703bbabc960f8cda0b932d7348e654d7afaf1d97c3ee094
+  data.tar.gz: 3a20869ecc92f35b8780672af93e7d38223cbc7e6ae6ca7913b678fae541c37c
 SHA512:
-  metadata.gz: '038c312b2ad13a04b55953d61d129a9fd928dd09d4a6eaf38ace13f7b1bab26cfe963b9e04002480ad337e26e4ff1114625860de19775d9c19a023a1c3f7c320'
-  data.tar.gz: 9eecc4f061f6242edd06fc5fa083b95b16023047602d9515ab449121b718445b0e4222be3231fbfcb9e4c9f46bd5c059c0efd9d447435abba6b0b4d3b3db62eb
+  metadata.gz: d04d30b6ec8059c57d6231ffb786ffb4ce0ad8672b6faad7a29b8f215adbee0c97a3cbeb39078a24ac3988d25d273a6b05b77b02fff51a2be146110ee28927a1
+  data.tar.gz: 58c318462a651629b0cf7d2f11951dcb419486549a947e82fe5f6195c67f6fc694b636e66686bb87aa4b6aff2c13605f94749f3a6c754795a94f5bd15cdeadfb

data/CHANGELOG.md

@@ -4,6 +4,80 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-08-17
+
+Two `ChainAudit` results could be read as facts when they were really "we did
+not look". Both are corrected in the direction of admitting it.
+
+### Fixed
+
+- `ChainAudit#total` (and `#headroom`) are **`nil` rather than `0`** for a name
+  that publishes no record, or when DNS did not answer. `0` is a legitimate
+  total — `v=spf1 -all` costs exactly that — so a caller that skipped
+  `#published?` could report "this record costs 0 lookups" about a domain with
+  no record. A record that legitimately costs nothing still reports `0`.
+- Duplicate records **at the hostname itself** are reported by the new
+  `#apex_duplicated?` instead of being pushed onto `#duplicated_in_chain`. RFC
+  7208 §4.5 makes them a permerror either way, but the apex is not *in* the
+  chain — it is the record being priced. Folding them together made the same
+  domain audit differently depending on whether the caller supplied `record:` or
+  let the gem resolve the apex, and a caller raising its own duplicate-record
+  defect from the records it resolved would have raised it twice.
+
+### Added
+
+- `ChainAudit#apex_duplicated?` — `true`/`false` when the gem resolved the apex,
+  and `nil` ("cannot say") when the record was supplied or DNS did not answer.
+
+### Changed
+
+- `#duplicated_in_chain` no longer contains the audited hostname. Callers that
+  want that fact ask `#apex_duplicated?`.
+
+## [0.2.0] - 2026-08-17
+
+Answers a second question about a record: not only "does it authorize me, and
+what did that cost", but "what does it cost a receiver that has to evaluate all
+of it" — the number every other SPF checker reports, and the one a domain owner
+compares against.
+
+### Added
+
+- `MailerToGo::SPF.chain_audit` / `MailerToGo::SPF::ChainAudit` — prices a whole
+  record tree against the RFC 7208 §4.6.4 budget, term by term, with a running
+  total. Deliberately a different number from `Result#lookups`, which stops
+  where the receiver stops (§4.6.2): a record can authorize you at a cost of 10
+  while costing 11 overall and being broken for everyone listed after you.
+  Reports `over_limit?`, `headroom`, `partial?` (part of the chain did not
+  resolve, so the total is a floor) and `capped?` (past `CEILING`, where the
+  exact number stops changing what anyone should do), and names the chain
+  defects found on the way: `targets_without_spf` (§5.2) and
+  `duplicated_in_chain` (§4.5). Pass `record:` to price a record that is not
+  published yet, or omit it to have the apex resolved.
+- `MailerToGo::SPF::Term` — one term of a record as an immutable object that
+  answers questions (`include?`, `querying?`, `unreachable?`, `unknown?`,
+  `qualifier_meaning`, `all_suffix`, `kind`) instead of being re-matched at
+  every call site. Subclassable, and built through `term_class:` on both
+  `Record.parse_terms` and `ChainAudit`, so a consumer can hang its own
+  human-facing copy off a term without standing up a second parser behind it.
+- `Record.parse_terms(record, term_class:)` — a record's terms as `Term`s,
+  numbered from 1 in record order. `Record.terms` still returns strings.
+- `MailerToGo::SPF.normalize_hostname` / `.hostname?` (and
+  `MailerToGo::SPF::Hostname`) — the gate for untrusted input in front of
+  anything that resolves DNS on request. Forgiving about shape (a pasted URL,
+  an email address, a trailing dot), strict about the result: a syntactically
+  valid hostname, or nil. Distinct from `Record.normalize_name`, which
+  normalizes a name that came out of a record and never rejects.
+
+### Changed
+
+- The qualifier map, the querying-mechanism list, the modifier regex and the
+  `all`-with-junk regex are now defined once, on `Term`, and read from there by
+  `Authorization` and `MergePlan`. `Authorization::QUERYING_MECHANISMS` and
+  `ALL_QUALIFIERS` keep their names and values.
+- `MergePlan::ALL_TERM` and `MergePlan::MODIFIER_TERM` are removed; `MergePlan`
+  asks `Term` what a term is. Behaviour of the merge is unchanged.
+
 ## [0.1.0] - 2026-08-16
 
 First release. Extracted from the SPF engine MailerToGo runs behind its own
@@ -30,4 +104,5 @@ domain setup and monitoring.
   `Resolv::DNS` default and an optional `CachingResolver`. No runtime
   dependencies, no Rails.
 
+[0.2.0]: https://github.com/aluminumio/mailertogo-spf/releases/tag/v0.2.0
 [0.1.0]: https://github.com/aluminumio/mailertogo-spf/releases/tag/v0.1.0

data/README.md

@@ -23,6 +23,10 @@ stops at the first mechanism that matches (RFC 7208 §4.6.2), and counts
 DNS-querying terms against §4.6.4's cap of 10 — the same arithmetic a receiver
 does, so a record this gem passes is a record that passes in the wild.
 
+It answers three questions about a name: does its SPF **authorize** you, what
+should it **publish** given what is already there, and what does the record
+**cost** a receiver that evaluates all of it.
+
 No Rails. No runtime dependencies. DNS goes through an injectable resolver, so
 your test suite never touches the network.
 
@@ -173,6 +177,154 @@ plan.value_for(name: "example.com", value: "v=spf1 include:_spf.mailertogo.net ~
 # => "v=spf1 include:_spf.google.com include:_spf.mailertogo.net ~all"
 ```
 
+## What does this record cost?
+
+`authorize` counts the lookups spent up to the point where **you** match,
+because §4.6.2 ends a receiver's evaluation at the first matching mechanism.
+That is the right number for a gating decision and the wrong number for a page
+about the record itself, where the question is what the record costs a receiver
+that has to evaluate *all* of it — the number every other SPF checker reports.
+
+`chain_audit` walks the whole tree and prices it against the §4.6.4 budget of
+ten, attaching each cost to the term that incurred it:
+
+```ruby
+audit = MailerToGo::SPF.chain_audit("example.com")
+
+audit.total       # => 3
+audit.limit       # => 10
+audit.headroom    # => 7    — lookups still available before the cap
+audit.over_limit? # => false
+
+audit.terms.map { |t| [t.raw, t.lookups, t.running_total] }
+# => [["include:_spf.google.com", 3, 3],   # itself, plus the two includes inside it
+#     ["ip4:198.51.100.7",        0, 3],   # already an address; no DNS
+#     ["~all",                    0, 3]]
+```
+
+An `include:` costs one lookup **plus everything the record it pulls in costs**,
+which is why a record with three terms can be most of the way through the
+budget. That is the arithmetic people get wrong by hand, and the reason a
+domain that has added one provider too many cannot see it in the record.
+
+The two numbers can disagree about the same record, and both are right:
+
+```ruby
+# v=spf1 include:p1… ×8  include:relay.example.net  include:_spf.mailertogo.net ~all
+
+MailerToGo::SPF.authorize("example.com").lookups   # => 10 — a receiver matches you and stops
+MailerToGo::SPF.chain_audit("example.com").total   # => 11 — evaluating all of it costs 11
+```
+
+Your mail passes at every receiver today. The record is still over the cap, so
+everything listed *after* your include has already stopped passing, and the
+first person to add a provider breaks yours too. Report only the first number
+and you tell that domain owner their record is fine.
+
+The audit also names the defects it finds on the way down, each of which
+permerrors the whole evaluation rather than quietly doing nothing:
+
+```ruby
+audit.targets_without_spf  # => ["nothing.example.net"]  — include: of a name with no SPF (§5.2)
+audit.duplicated_in_chain  # => ["two.example.net"]      — two v=spf1 records in the chain (§4.5)
+audit.apex_duplicated?     # => false                    — two at the hostname itself (§4.5)
+```
+
+`apex_duplicated?` is deliberately separate from `duplicated_in_chain`: the
+hostname is not *in* the chain, it is the record being priced. It answers `nil`
+— "cannot say" — when you supplied the `record:` yourself, because then we never
+looked at the apex. A caller that resolved the apex already knows, and should
+report from what it saw rather than ask twice.
+
+A record that does not exist cannot be priced, so `total` and `headroom` are
+`nil` rather than `0`. Check `published?` first:
+
+```ruby
+audit = MailerToGo::SPF.chain_audit("no-spf.example.com")
+audit.published?  # => false
+audit.total       # => nil   — not 0; `v=spf1 -all` legitimately costs 0
+```
+
+Two honesty flags, because a count you could not finish must never read as "it
+fits": `partial?` (part of the chain did not resolve) and `capped?` (the record
+is so far past the cap that we stopped resolving — 20 lookups and 200 are the
+same record to a receiver). Either one makes `total` a floor, and `headroom`
+returns `nil` rather than a reassuring number.
+
+Pass `record:` to price a line that is not published yet, and omit it to have
+the apex resolved for you:
+
+```ruby
+MailerToGo::SPF.chain_audit("example.com", record: "v=spf1 include:a.example.net include:b.example.net -all")
+```
+
+### Terms
+
+A `Term` is one term of a record, asked questions instead of pattern-matched:
+
+```ruby
+terms = MailerToGo::SPF::Record.parse_terms("v=spf1 include:_spf.mailertogo.net ~all;google-site-verification=abc")
+
+terms.first.mechanism          # => "include"
+terms.first.target             # => "_spf.mailertogo.net"
+terms.first.querying?          # => true — it spends from the §4.6.4 budget
+
+terms.last.all?                # => true — still a terminal `all`, junk and all
+terms.last.qualifier_meaning   # => :softfail
+terms.last.all_suffix          # => ";google-site-verification=abc"
+```
+
+That last one is the case worth having: records ending
+`~all;google-site-verification=…` are real and not rare, and reading the whole
+token as junk loses the record's `all` — and with it the domain's entire policy
+for unauthorized mail.
+
+There is deliberately **no English sentence** on a term. A description of what a
+term means is product voice; it belongs to whoever is writing to their own
+customers, in their own words. What the gem gives you instead is somewhere to
+put it — subclass `Term`, and both `Record.parse_terms` and `ChainAudit` will
+build and price yours:
+
+```ruby
+class AnnotatedTerm < MailerToGo::SPF::Term
+  def meaning
+    return "Everything else is marked, not rejected." if all? && qualifier == "~"
+    return "Applies #{target}'s own SPF record here." if include?
+
+    …
+  end
+end
+
+MailerToGo::SPF.chain_audit("example.com", term_class: AnnotatedTerm).terms.map(&:meaning)
+```
+
+## Untrusted input
+
+If the hostname came from a form, an API parameter or an uploaded file rather
+than from your own database, check it before you resolve anything: an SPF walk
+is recursive DNS performed on request.
+
+```ruby
+MailerToGo::SPF.normalize_hostname("https://WWW.Example.com/pricing?x=1")  # => "www.example.com"
+MailerToGo::SPF.normalize_hostname("billing@example.com")                  # => "example.com"
+MailerToGo::SPF.normalize_hostname("example.com:5353")                     # => "example.com"
+MailerToGo::SPF.normalize_hostname("v=spf1")                               # => nil
+MailerToGo::SPF.hostname?("192.0.2.1")                                     # => false
+```
+
+Forgiving about shape — people paste URLs and email addresses into a box
+labelled "domain" and are not wrong to expect that to work — and strict about
+the result: a syntactically valid hostname, or `nil`. A scheme, a port, a path,
+a query string or an address literal is stripped or refused before any resolver
+sees it, and there is no way to name a resolver or a port through it.
+
+It is a separate call rather than something folded into `authorize`, on purpose.
+"That is not a hostname" is a fact about your **input**; the statuses on
+`Result` are facts about somebody's **DNS**, and conflating the two would mean
+inventing a sixth status for a mistake DNS had nothing to do with. It is also
+not `Record.normalize_name`, which lowercases a name that came out of a record
+and never rejects.
+
 ## DNS
 
 A resolver is anything that responds to `#call(name)` and returns:
@@ -239,7 +391,7 @@ zone = {
 MailerToGo::SPF.authorize("example.com", resolver: ->(name) { zone.fetch(name, []) })
 ```
 
-The gem's own suite is built that way: 95 examples, zero network access.
+The gem's own suite is built that way: 137 examples, zero network access.
 
 ## Configuration
 

data/lib/mailertogo/spf/authorization.rb

@@ -2,6 +2,7 @@
 
 require "set"
 require "mailertogo/spf/record"
+require "mailertogo/spf/term"
 require "mailertogo/spf/result"
 require "mailertogo/spf/sender"
 
@@ -49,12 +50,13 @@ module MailerToGo
       # record.
       MAX_DEPTH = 10
 
-      # Mechanisms that consume one DNS lookup from the budget above.
-      QUERYING_MECHANISMS = %w[include a mx ptr exists].freeze
-
-      # RFC 7208 §4.6.2 — the qualifier on a mechanism, here only ever read off
-      # the record's terminal `all`. See Result#all_qualifier.
-      ALL_QUALIFIERS = { "+" => :pass, "-" => :fail, "~" => :softfail, "?" => :neutral }.freeze
+      # Mechanisms that consume one DNS lookup from the budget above, and the
+      # §4.6.2 qualifier map (here only ever read off the record's terminal
+      # `all` — see Result#all_qualifier). Both are RFC anatomy and live on
+      # Term, which is where a caller goes to ask what a term IS; named here
+      # because this is where they are spent.
+      QUERYING_MECHANISMS = Term::QUERYING
+      ALL_QUALIFIERS = Term::QUALIFIERS
 
       # hostname  — the domain whose SPF we are reading.
       # sender    — a Sender: the names that mean "me".

data/lib/mailertogo/spf/chain_audit.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "set"
+require "mailertogo/spf/record"
+require "mailertogo/spf/term"
+require "mailertogo/spf/authorization"
+
+module MailerToGo
+  module SPF
+    # Prices a published SPF record against the RFC 7208 §4.6.4 lookup budget,
+    # term by term, and notes the chain defects found on the way.
+    #
+    # Why this is not Authorization. That class answers "does this record
+    # authorise ME?", and §4.6.2 ends a receiver's evaluation at the first
+    # mechanism that matches — so it deliberately counts only the lookups spent
+    # up to the match. That is the right number for a gating decision (a record
+    # whose match lands on term 10 of an 11-term record passes at every real
+    # receiver, and calling it a permerror would be wrong) and the wrong number
+    # for describing the record itself, where the question is what it costs a
+    # receiver that has to evaluate ALL of it. That second number is what every
+    # SPF checker reports and the one people compare against, and the two can
+    # legitimately disagree about the same record — one authorises you at a cost
+    # of 10 while itself costing 11 and being broken for everybody past your
+    # include.
+    #
+    # So: walk the whole tree, charge every querying term, and hand back the
+    # cost attached to the term that incurred it.
+    #
+    # Bounded three ways, because this is the sort of thing that ends up behind
+    # an unauthenticated "check my domain" box resolving whatever a stranger
+    # typed: the §4.6.4 cap itself, a depth limit, and a hard CEILING past which
+    # we stop resolving — once a record is over budget the exact number no
+    # longer changes what anyone should do about it.
+    #
+    # Reads DNS through the same injected resolver as everything else, so behind
+    # a CachingResolver an audit of a name you have already authorised is
+    # largely cache hits.
+    class ChainAudit
+      # RFC 7208 §4.6.4 — 10 is legal, 11 permerrors. The same cap Authorization
+      # enforces; named here because this class reports against it.
+      LIMIT = Authorization::MAX_DNS_LOOKUPS
+
+      # Belt-and-suspenders against a pathological tree, exactly as in the
+      # engine: the budget below is the real bound, this stops runaway recursion
+      # on a wide shallow record.
+      MAX_DEPTH = Authorization::MAX_DEPTH
+
+      # Stop resolving well past the cap. A record needing 20 lookups and one
+      # needing 200 are the same record to a receiver: permerror. Past this the
+      # total is reported as a floor (see #capped?) rather than chased.
+      CEILING = 2 * LIMIT
+
+      attr_reader :hostname, :record, :terms, :total, :targets_without_spf, :duplicated_in_chain
+
+      # record    — the record to price. Pass nil to have the apex resolved from
+      #             DNS at `hostname`, which is the whole question ("what does
+      #             this domain's SPF cost?") asked in one call.
+      # hostname  — the name the record is published at. Guards a record that
+      #             includes itself, and is where a nil record is resolved from.
+      # resolver  — anything responding to #call(name); see Resolver.
+      # term_class— a Term subclass to build the terms as, for a caller that
+      #             hangs its own copy off a term.
+      def self.call(hostname:, resolver:, record: nil, term_class: nil)
+        new(hostname: hostname, resolver: resolver, record: record, term_class: term_class).run
+      end
+
+      def initialize(hostname:, resolver:, record: nil, term_class: nil)
+        @record = record&.to_s
+        @hostname = Record.normalize_name(hostname)
+        @resolver = resolver
+        @term_class = term_class || Term
+        @spent = 0
+        @total = nil
+        @terms = []
+        @targets_without_spf = []
+        @duplicated_in_chain = []
+        # nil until we resolve the apex ourselves — "cannot say", not "no".
+        @apex_duplicated = nil
+        @resolved = true
+        @partial = false
+        @capped = false
+        # The queried name guards a record that includes itself.
+        @seen = Set.new([@hostname])
+      end
+
+      def run
+        resolve_apex if @record.nil?
+
+        parsed = Record.parse_terms(@record, term_class: @term_class)
+        # §6.1 — a record containing `all` ignores its redirect= outright,
+        # wherever in the record the redirect sits.
+        terminal = parsed.any?(&:all?)
+        seen_all = false
+
+        parsed.each do |term|
+          unreachable = seen_all || (term.redirect? && terminal)
+          # Rebuilt rather than mutated: unreachability is a fact about the
+          # term's POSITION, which only this loop knows, and a term is frozen.
+          term = @term_class.new(raw: term.raw, position: term.position, unreachable: unreachable)
+          cost = unreachable ? 0 : charge(term, depth: 0)
+          @terms << term.priced(lookups: cost, running_total: @spent)
+          seen_all ||= term.all?
+        end
+
+        # nil, not 0, when there is nothing to price. 0 is a legitimate total —
+        # `v=spf1 -all` costs exactly that — so using it for "no record" lets a
+        # caller that skipped #published? report "this record costs 0 lookups"
+        # about a domain with no record at all.
+        @total = published? ? @spent : nil
+        self
+      end
+
+      def limit = LIMIT
+
+      # Is there a record here at all? False when the name publishes no v=spf1
+      # record (or DNS did not answer — see #resolved?).
+      def published? = !@record.to_s.empty?
+
+      # Did DNS answer when we resolved the apex ourselves? Always true when the
+      # record was handed to us. A resolver hiccup is not "this domain has no
+      # SPF", and the two must never be reported as the same thing.
+      def resolved? = @resolved
+
+      # More than §4.6.4 allows: 10 is legal, 11 permerrors.
+      def over_limit? = @total.to_i > LIMIT
+
+      # Part of the chain did not resolve, so the total is a FLOOR. Never report
+      # "this fits" from a count we could not finish — the direction that is
+      # dangerous to get wrong is the reassuring one.
+      def partial? = @partial
+
+      # We stopped walking at CEILING: the record is far past the cap and the
+      # real total is higher than the one reported. Same treatment as partial —
+      # the number is a floor — for a different reason.
+      def capped? = @capped
+
+      # Was there more than one v=spf1 record at the hostname itself? §4.5 makes
+      # that a permerror just as surely as duplicates inside the chain.
+      #
+      # nil means "cannot say" rather than "no": the record was handed to us, so
+      # we never looked at the apex (or DNS did not answer). Only a caller that
+      # let us resolve the apex gets a true/false here — the one that resolved it
+      # already knows, and should report from what it saw rather than ask us.
+      def apex_duplicated? = @apex_duplicated
+
+      # How many lookups are still available before the cap, or nil when we
+      # cannot say (a floor cannot answer "how much room is left", and neither
+      # can a record that does not exist).
+      def headroom
+        return nil if partial? || capped? || !published?
+
+        [LIMIT - @total.to_i, 0].max
+      end
+
+      private
+
+      # No record was supplied: read the apex ourselves.
+      def resolve_apex
+        txts = @resolver.call(@hostname)
+        if txts.nil?
+          @resolved = false
+          @partial = true
+          @record = ""
+          return
+        end
+
+        records = Array(txts).map { |t| Record.normalize_txt(t) }.select { |t| Record.spf_record?(t) }
+        # §4.5 — two records at the apex permerror the evaluation just as surely
+        # as two anywhere else in the chain. It is reported SEPARATELY from
+        # `duplicated_in_chain` even so, because the apex is not *in* the chain:
+        # it is the record being priced. Folding it in made the same domain audit
+        # differently depending on whether the caller resolved the apex or we
+        # did, and a caller that raises its own duplicate-record defect from the
+        # records it resolved would then raise it twice.
+        @apex_duplicated = records.size > 1
+        # We price the first, because there has to be something to read.
+        @record = records.first.to_s
+      end
+
+      # Spend the budget this term costs and return the amount.
+      def charge(term, depth:)
+        before = @spent
+        if term.querying?
+          @spent += 1
+          # a / mx / ptr / exists cost exactly one query each and expand no
+          # further; include: and redirect= pull in another record, and
+          # everything in it.
+          descend(term.target, depth) if term.include? || term.redirect?
+        end
+        @spent - before
+      end
+
+      def descend(target, depth)
+        name = Record.normalize_name(target.to_s)
+        return if name.empty?
+        # Macros (%{i} etc., §7) are per-message: the lookup is charged, the
+        # branch cannot be followed.
+        return if name.include?("%")
+        return if depth >= MAX_DEPTH
+        return unless @seen.add?(name) # loop guard (§11.1)
+
+        if @spent > CEILING
+          @capped = true
+          return
+        end
+
+        txts = @resolver.call(name)
+        if txts.nil?
+          @partial = true
+          return
+        end
+
+        records = Array(txts).map { |t| Record.normalize_txt(t) }.select { |t| Record.spf_record?(t) }
+        # §5.2 — an include: whose target publishes no SPF record is a permerror
+        # for the whole evaluation, not a term that quietly does nothing.
+        return @targets_without_spf << name if records.empty?
+        # §4.5 — two records anywhere in the chain permerror the whole thing.
+        return @duplicated_in_chain << name if records.size > 1
+
+        walk(records.first, depth + 1)
+      end
+
+      def walk(record, depth)
+        parsed = Record.parse_terms(record, term_class: @term_class)
+        terminal = parsed.any?(&:all?)
+
+        parsed.each do |term|
+          break if term.all? # nothing after `all` is ever evaluated
+          next if term.redirect? && terminal # §6.1
+
+          charge(term, depth: depth)
+        end
+      end
+    end
+  end
+end

data/lib/mailertogo/spf/hostname.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module MailerToGo
+  module SPF
+    # Is this untrusted input a name we are willing to resolve?
+    #
+    # Everything else in this gem takes a hostname it trusts. This is the gate
+    # for the case where it did not come from your own database — a box on a
+    # page labelled "domain", an API parameter, a CSV somebody uploaded. Asking
+    # a resolver to walk an SPF chain is recursive DNS performed on request, so
+    # what gets handed to it should be a plausible DNS name and nothing else:
+    # anything that could steer the lookup somewhere unintended — a scheme, a
+    # port, a path, a query string, an address literal — is stripped or refused
+    # here, before any resolver sees it.
+    #
+    # It is forgiving about SHAPE, because people paste
+    # "https://www.example.com/pricing" or "billing@example.com" into a box
+    # labelled "domain" and are not wrong to expect that to work, and strict
+    # about the RESULT: a syntactically valid hostname, or nil.
+    #
+    # Distinct from Record.normalize_name, and deliberately so. That one
+    # lowercases a name that came out of an SPF record and drops its root dot;
+    # it never rejects, because a name inside a record is already as trusted as
+    # the record. This one is a gate, and its job is to say no.
+    module Hostname
+      module_function
+
+      # RFC 1035 §2.3.4 — 253 octets of presentation form, 63 per label.
+      MAX_LENGTH = 253
+
+      # A DNS label. Underscores are allowed because SPF names are real targets
+      # people check — `_spf.google.com` and `_spf.mailertogo.net` are the two
+      # most likely things anyone types into such a box after their own domain.
+      LABEL = /\A[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?\z/
+
+      # An address literal is not a name to resolve SPF at.
+      IPV4 = /\A\d{1,3}(\.\d{1,3}){3}\z/
+
+      # A TLD is alphabetic, so "1.2" and "v=spf1" never reach a resolver.
+      TLD = /\A[a-z]{2,}\z/
+
+      # The hostname to resolve, or nil when the input is not one.
+      def parse(input)
+        host = input.to_s.strip.downcase
+        return nil if host.empty?
+
+        host = host.sub(%r{\A[a-z][a-z0-9+.-]*://}, "")   # a pasted URL
+        host = host.split("@").last.to_s                  # an email address
+        host = host[%r{\A[^/?#]*}].to_s                   # path, query, fragment
+        host = host.split(":").first.to_s                 # never honour a supplied port
+        host = host.delete_prefix("[").delete_suffix("]") # an IPv6 literal in URL form
+        host = host.chomp(".")                            # the root dot is optional
+
+        return nil if host.empty? || host.length > MAX_LENGTH
+        return nil if host.match?(IPV4)
+
+        # No IDN here: resolvers speak ASCII, and guessing at an encoding for
+        # somebody's DNS name is worse than telling them to paste the A-label.
+        labels = host.split(".", -1)
+        return nil if labels.size < 2
+        return nil unless labels.all? { |label| label.match?(LABEL) }
+        return nil unless labels.last.match?(TLD)
+
+        host
+      end
+
+      def valid?(input)
+        !parse(input).nil?
+      end
+    end
+  end
+end

data/lib/mailertogo/spf/merge_plan.rb

@@ -43,17 +43,13 @@ module MailerToGo
     # standalone instruction rather than guessing — better to under-help than to
     # tell someone to replace a record we could not read.
     class MergePlan
-      # A term that ends evaluation: `all`, with its optional qualifier, plus
-      # any junk glued onto it. The junk is real and surprisingly common —
-      # records ending `~all;google-site-verification=…` exist in the wild,
-      # where the `;`-joined fragment is not a valid SPF term at all.
-      ALL_TERM = /\A([+\-~?])?all([^a-z0-9].*)?\z/i
-
-      # A modifier (`redirect=`, `exp=`, or an unknown one) rather than a
-      # mechanism. Modifiers are position-independent (§4.6.1), so they survive
-      # the merge even when they trail the record's `all`.
-      MODIFIER_TERM = /\A([a-z][a-z0-9\-_.]*)=/i
-
+      # What a term IS — is it the terminal `all` (with whatever junk is glued
+      # onto it), is it a modifier, does it name the sender — is asked of Term
+      # rather than re-matched here. There was a second, informal copy of that
+      # knowledge in this file; two readings of the same term is exactly how a
+      # record ending `~all;google-site-verification=…` ends up merged one way
+      # and described another.
+      #
       # name          — the DNS name the record goes at.
       # record        — the standalone record you would otherwise have told them
       #                 to publish, e.g. Sender#record. It is what a :publish
@@ -138,26 +134,25 @@ module MailerToGo
         (theirs + ours).each do |record|
           seen_all = false
 
-          Record.terms(record).each do |term|
-            if (m = ALL_TERM.match(term))
+          Record.parse_terms(record).each do |term|
+            if term.all?
               seen_all = true
               # First `all` across the ordered records wins — theirs, not ours.
               # A bare `all` is `+all` (§4.6.2); spell it out so the merged line
               # says plainly what it does.
-              @all_qualifier ||= m[1] || "+"
-              if m[2] && !m[2].strip.empty?
-                @notes << "Dropped #{m[2].strip.inspect}, which was glued onto your #{m[1]}all " \
+              @all_qualifier ||= term.qualifier || "+"
+              if (junk = term.all_suffix)
+                @notes << "Dropped #{junk.inspect}, which was glued onto your #{term.qualifier}all " \
                           "and isn't a valid SPF term — publish it as its own TXT record if you still need it."
               end
               next
             end
 
-            if MODIFIER_TERM.match?(term)
+            if term.modifier
               # redirect=/exp= are modifiers, not mechanisms: they apply to the
               # whole record wherever they sit, so keep them (deduped by
               # modifier name).
-              key = MODIFIER_TERM.match(term)[1].downcase
-              modifiers << term unless modifiers.any? { |t| MODIFIER_TERM.match(t)[1].casecmp?(key) }
+              modifiers << term unless modifiers.any? { |t| t.modifier == term.modifier }
               next
             end
 
@@ -165,13 +160,14 @@ module MailerToGo
               # Unreachable in the published record (nothing after `all` is ever
               # evaluated). Dropping it preserves the record's exact behavior;
               # keeping it would newly authorize a sender receivers ignore today.
-              @notes << "Dropped #{term.inspect}, which sat after your #{@all_qualifier}all and was never evaluated."
+              @notes << "Dropped #{term.raw.inspect}, which sat after your #{@all_qualifier}all " \
+                        "and was never evaluated."
               next
             end
 
             next if sender_term?(term)
 
-            mechanisms << term unless mechanisms.any? { |t| t.casecmp?(term) }
+            mechanisms << term.raw unless mechanisms.any? { |t| t.casecmp?(term.raw) }
           end
         end
 
@@ -179,7 +175,7 @@ module MailerToGo
         # everything and ends evaluation.
         terms = mechanisms + ["include:#{@include_name}"]
         terms << "#{@all_qualifier}all" if @all_qualifier
-        terms += modifiers
+        terms += modifiers.map(&:raw)
         "v=spf1 #{terms.join(" ")}"
       end
 
@@ -208,13 +204,16 @@ module MailerToGo
       # that reaches the sender through somebody else's include is still THEIR
       # policy record.
       def ours?(record)
-        Record.terms(record).any? { |term| sender_term?(term) }
+        Record.parse_terms(record).any? { |term| sender_term?(term) }
       end
 
+      # Takes a Term, not a string: "does this name us" is a question about the
+      # term's target, and Term already knows how to find one.
       def sender_term?(term)
-        t = Record.strip_qualifier(term)
-        target = t[/\Ainclude:(.+)\z/i, 1] || t[/\Aredirect=(.+)\z/i, 1]
-        !target.nil? && !target.empty? && @sender.covers?(target)
+        return false unless term.include? || term.redirect?
+
+        target = term.target
+        !target.nil? && @sender.covers?(target)
       end
 
       def same_terms?(a, b)

data/lib/mailertogo/spf/record.rb

@@ -76,9 +76,26 @@ module MailerToGo
       end
 
       # The terms of a record, without the leading "v=spf1".
+      #
+      # Strings, deliberately: this is the raw-text layer, and the engine walks
+      # terms in tight loops where a string is exactly what it wants. Ask for
+      # .parse_terms when you want to interrogate a term rather than match it.
       def terms(record)
         record.to_s.split(/\s+/).drop(1)
       end
+
+      # The same terms as Term objects, numbered from 1 in record order, so a
+      # caller can ask each one what it is instead of re-deriving that from the
+      # string. `term_class:` takes a Term subclass — that is the seam for
+      # hanging your own copy off a term without a parallel parser behind it.
+      #
+      # Term is resolved at call time rather than required at the top of this
+      # file: Term is built ON this module, and the raw-text layer should not
+      # have to know about the layer above it to hand one back.
+      def parse_terms(record, term_class: nil)
+        term_class ||= Term
+        terms(record).each_with_index.map { |raw, i| term_class.new(raw: raw, position: i + 1) }
+      end
     end
   end
 end

data/lib/mailertogo/spf/term.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "mailertogo/spf/record"
+
+module MailerToGo
+  module SPF
+    # One term of an SPF record: what it is, and what it costs.
+    #
+    # `Record` reads the raw text — split a record into terms, strip a
+    # qualifier, name a mechanism. This is the same knowledge asked as
+    # questions instead of pattern-matched at every call site: `term.include?`,
+    # `term.querying?`, `term.unreachable?`. Nothing here re-parses what
+    # `Record` already parses; it builds on it, which is the only way two
+    # readings of the same term cannot drift apart.
+    #
+    # Deliberately NOT here: any English sentence about what a term means to a
+    # human. A description is product voice — it belongs to whoever is writing
+    # to their own customers, in their own words, and no gem should be in the
+    # business of writing it. What a consumer wants is a place to hang that
+    # copy, so `Term` is designed to be subclassed: every predicate it answers
+    # is a predicate your sentence can switch on, and both #priced and
+    # `Record.parse_terms(record, term_class:)` build your subclass rather than
+    # this class.
+    #
+    #   class AnnotatedTerm < MailerToGo::SPF::Term
+    #     def meaning
+    #       return "Everything not matched above is marked, not rejected." if all? && qualifier == "~"
+    #       …
+    #     end
+    #   end
+    #
+    # Immutable, and frozen on construction: pricing a term builds a copy via
+    # #priced rather than mutating it, so a term can never be observed
+    # half-priced.
+    class Term
+      # RFC 7208 §4.6.4 — the mechanisms that cost a DNS query. The lookup
+      # budget is a count of these (plus the redirect= modifier).
+      QUERYING = %w[include a mx ptr exists].freeze
+
+      # §4.6.2 — the qualifier a mechanism may carry, and what a match under it
+      # means. "+" when absent.
+      QUALIFIERS = { "+" => :pass, "-" => :fail, "~" => :softfail, "?" => :neutral }.freeze
+
+      # Every mechanism SPF defines. Anything else in mechanism position is a
+      # syntax error (see #unknown?), not a term that quietly does nothing.
+      MECHANISMS = (QUERYING + %w[ip4 ip6 all]).freeze
+
+      # A modifier (`redirect=`, `exp=`, or an unknown one) rather than a
+      # mechanism. Modifiers are name=value and position-independent (§4.6.1).
+      MODIFIER = /\A([a-z][a-z0-9\-_.]*)=(.*)\z/i
+
+      # `all`, with whatever junk is glued onto it. The junk is real and
+      # surprisingly common — records ending `~all;google-site-verification=…`
+      # exist in the wild, where the `;`-joined fragment is not a valid SPF term
+      # at all. Matching it HERE is what keeps such a record's terminal term
+      # recognised as an `all` (which ends evaluation, and whose qualifier is
+      # the domain's policy) rather than filed as junk and the record read as
+      # having no `all` whatsoever.
+      ALL = /\Aall([^a-z0-9].*)?\z/i
+
+      attr_reader :raw, :position, :qualifier, :lookups, :running_total
+
+      # raw           — the term exactly as published.
+      # position      — 1-based index in the record; 0 when it was not parsed as
+      #                 part of one. For display, and for nothing else.
+      # unreachable   — the term is never evaluated: it sits after `all`, or it
+      #                 is a redirect= in a record that has an `all`
+      #                 (§5.1/§6.1). Such a term authorises nothing and costs
+      #                 nothing.
+      # lookups       — DNS lookups this term costs a receiver: itself, plus
+      #                 everything the record it pulls in costs. nil until
+      #                 priced by ChainAudit.
+      # running_total — the record's cumulative cost through this term.
+      def initialize(raw:, position: 0, unreachable: false, lookups: nil, running_total: nil)
+        @raw = raw.to_s
+        @position = position
+        @unreachable = unreachable
+        @lookups = lookups
+        @running_total = running_total
+        @bare = Record.strip_qualifier(@raw)
+        @qualifier = Record.qualifier_of(@raw)
+        @modifier_match = MODIFIER.match(@bare)
+        @all_match = ALL.match(@bare)
+        @mechanism = @modifier_match ? nil : Record.mechanism_of(@bare)
+        freeze
+      end
+
+      # A copy carrying the cost ChainAudit measured. `self.class` so a
+      # subclass that adds its own copy stays that subclass through pricing.
+      def priced(lookups:, running_total:)
+        self.class.new(raw: raw, position: position, unreachable: unreachable?,
+                       lookups: lookups, running_total: running_total)
+      end
+
+      # ── What it is ────────────────────────────────────────────────────────
+
+      # "include", "ip4", "all"… nil for a modifier or for junk.
+      def mechanism
+        return "all" if @all_match
+
+        @mechanism if MECHANISMS.include?(@mechanism)
+      end
+
+      # "redirect", "exp", or another modifier name; nil for a mechanism.
+      def modifier
+        @modifier_match && @modifier_match[1].downcase
+      end
+
+      # The value after the ":" or "=" — an include target, an IP range, an
+      # explanation name. nil for a bare `a`, `mx` or `all`.
+      def target
+        value = @modifier_match ? @modifier_match[2] : @bare.split(":", 2)[1]
+        value.to_s.empty? ? nil : value
+      end
+
+      # :pass | :fail | :softfail | :neutral — what a match under this
+      # qualifier means to a receiver (§4.6.2). On the terminal `all` this is
+      # the domain's whole policy for unauthorised mail (§5.1).
+      def qualifier_meaning = QUALIFIERS[@qualifier || "+"]
+
+      def all? = mechanism == "all"
+      def include? = mechanism == "include"
+      def redirect? = modifier == "redirect"
+      def ip? = %w[ip4 ip6].include?(mechanism)
+
+      # Does this term spend from the §4.6.4 budget at all?
+      def querying? = QUERYING.include?(mechanism) || redirect?
+
+      # Never evaluated by a receiver, so it authorises nothing and costs
+      # nothing. Set by whoever read the record in order (ChainAudit); a term
+      # on its own cannot know what precedes it.
+      def unreachable? = @unreachable == true
+
+      # Not a mechanism SPF defines and not a modifier: junk. Per §4.6 a syntax
+      # error in a record permits a receiver to permerror the whole thing, so
+      # this is never harmless.
+      def unknown? = mechanism.nil? && modifier.nil?
+
+      # Which of the three a term is: a named mechanism, "modifier", "unknown".
+      def kind
+        return "modifier" if modifier
+        return "unknown" if unknown?
+
+        mechanism
+      end
+
+      # The junk glued onto an `all` (`~all;google-site-verification=…`), or
+      # nil. Worth surfacing: it is inside the record rather than beside it, so
+      # it is not the second TXT record its author thought they were writing.
+      def all_suffix
+        suffix = @all_match && @all_match[1].to_s.strip
+        suffix.to_s.empty? ? nil : suffix
+      end
+
+      def to_s = raw
+    end
+  end
+end

data/lib/mailertogo/spf/version.rb

@@ -2,6 +2,6 @@
 
 module MailerToGo
   module SPF
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/mailertogo/spf.rb

@@ -2,10 +2,13 @@
 
 require "mailertogo/spf/version"
 require "mailertogo/spf/record"
+require "mailertogo/spf/term"
+require "mailertogo/spf/hostname"
 require "mailertogo/spf/sender"
 require "mailertogo/spf/resolver"
 require "mailertogo/spf/result"
 require "mailertogo/spf/authorization"
+require "mailertogo/spf/chain_audit"
 require "mailertogo/spf/plan"
 require "mailertogo/spf/merge_plan"
 
@@ -14,7 +17,7 @@ module MailerToGo
   # the include chain, stops where the receiver stops, and counts DNS lookups
   # against the RFC 7208 §4.6.4 cap.
   #
-  # Two questions, two entry points:
+  # Three questions, three entry points:
   #
   #   MailerToGo::SPF.authorize("example.com")
   #     → does this domain's published SPF authorize me?
@@ -22,6 +25,9 @@ module MailerToGo
   #   MailerToGo::SPF.merge_plan("example.com")
   #     → what should I tell them to publish, given what is already there?
   #
+  #   MailerToGo::SPF.chain_audit("example.com")
+  #     → what does this record cost a receiver, term by term?
+  #
   # Both take `include:` (the mechanism you want authorized) and `aliases:`
   # (other names that mean the same sender). Both default to MailerToGo's own
   # names, so the zero-argument form is the useful one for MailerToGo customers
@@ -106,6 +112,30 @@ module MailerToGo
         )
       end
 
+      # What does this record cost a receiver that evaluates all of it?
+      # Returns a ChainAudit (see chain_audit.rb).
+      #
+      # This is a different number from Result#lookups and is meant to be: the
+      # authorization walk stops where the receiver stops (§4.6.2), while this
+      # prices the whole tree against the §4.6.4 budget — the number other SPF
+      # checkers report. Notably sender-agnostic; there is no `include:` here,
+      # because the record's cost has nothing to do with who is asking.
+      #
+      # record: price this record instead of resolving one at `hostname`, which
+      # is how you price a record that is not published yet.
+      def chain_audit(hostname, record: nil, resolver: nil, term_class: nil)
+        ChainAudit.call(hostname: hostname, record: record, resolver: resolver || self.resolver,
+                        term_class: term_class)
+      end
+
+      # Is this untrusted input something we should resolve at all? Returns the
+      # normalized hostname, or nil. See hostname.rb — it is a gate, kept
+      # separate from the entry points above on purpose, because "that is not a
+      # hostname" is a fact about the INPUT and must not be dressed up as a fact
+      # about somebody's DNS.
+      def normalize_hostname(input) = Hostname.parse(input)
+      def hostname?(input) = Hostname.valid?(input)
+
       # The names that mean "me". Public because a caller that asks both
       # questions about the same sender should build it once.
       def sender(include: nil, aliases: nil)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailertogo-spf
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - MailerToGo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-15 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies: []
 description: |
   An SPF engine that follows include:/redirect= chains, stops at the first
@@ -16,8 +16,10 @@ description: |
   cap of 10 — so it agrees with what real receivers do instead of
   string-matching a token. It also plans the record a domain should publish:
   given what is already at the name, merge one include into the existing
-  record rather than adding a second v=spf1 record beside it. No Rails, no
-  runtime dependencies, injectable DNS resolver.
+  record rather than adding a second v=spf1 record beside it. And it prices a
+  record: what the whole tree costs a receiver that evaluates all of it, term
+  by term, against the same cap. No Rails, no runtime dependencies, injectable
+  DNS resolver.
 email:
 - support@mailertogo.com
 executables: []
@@ -29,12 +31,15 @@ files:
 - README.md
 - lib/mailertogo/spf.rb
 - lib/mailertogo/spf/authorization.rb
+- lib/mailertogo/spf/chain_audit.rb
+- lib/mailertogo/spf/hostname.rb
 - lib/mailertogo/spf/merge_plan.rb
 - lib/mailertogo/spf/plan.rb
 - lib/mailertogo/spf/record.rb
 - lib/mailertogo/spf/resolver.rb
 - lib/mailertogo/spf/result.rb
 - lib/mailertogo/spf/sender.rb
+- lib/mailertogo/spf/term.rb
 - lib/mailertogo/spf/version.rb
 homepage: https://github.com/aluminumio/mailertogo-spf
 licenses: