mailertogo-spf 0.1.0

data/lib/mailertogo/spf/plan.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "mailertogo/spf/record"
+require "mailertogo/spf/authorization"
+
+module MailerToGo
+  module SPF
+    # What to tell a domain owner to publish, given what is already at that name.
+    #
+    # action:
+    #   :publish     — nothing SPF-shaped is published at this name: hand them
+    #                  the standalone record. Also the fallback when DNS did not
+    #                  answer (resolved? == false), because guessing is worse.
+    #   :merge       — one record is already there and does not authorize the
+    #                  sender: they must REPLACE it with merged_record.
+    #   :deduplicate — two or more v=spf1 records are already published (the
+    #                  RFC 7208 §3.2 violation): replace ALL of them with
+    #                  merged_record.
+    #   :satisfied   — a single record already reaches the sender. Nothing to say.
+    #
+    # over_lookup_limit is true only when the merged record was definitively
+    # measured past RFC 7208 §4.6.4's cap — never on an inconclusive DNS answer.
+    Plan = Struct.new(:action, :name, :record, :include_name, :existing_records,
+                      :merged_record, :all_qualifier, :lookups, :lookup_limit,
+                      :over_lookup_limit, :resolved, :notes, keyword_init: true) do
+      def publish? = action == :publish
+      def merge? = action == :merge
+      def deduplicate? = action == :deduplicate
+      def satisfied? = action == :satisfied
+
+      # Are we asking them to REPLACE an existing record rather than add one?
+      # The difference matters enormously in a UI: "add this TXT record" next to
+      # an existing SPF record is exactly the instruction that produces the
+      # two-record permerror in the first place.
+      def replacement? = merge? || deduplicate?
+
+      # Already in the RFC-violating two-record state right now.
+      def duplicated? = deduplicate?
+
+      def over_limit? = over_lookup_limit == true
+
+      def resolved? = resolved == true
+
+      # The line to actually put in front of them. Withheld when merging would
+      # blow the lookup budget: a record we know permerrors is worse than the
+      # standalone instruction plus an explanation of what has to go first.
+      def offered_record
+        return nil unless replacement?
+
+        over_limit? ? nil : merged_record
+      end
+
+      # Is this state something to ALERT them about, or just an instruction?
+      # Already-duplicated and over-the-cap are defects they are living with
+      # today; a plain merge is just telling them how to add the sender
+      # correctly the first time. A fact about the plan, not about the view —
+      # two surfaces must not have to agree on it independently.
+      def warning? = duplicated? || over_limit?
+      def severity = warning? ? :warning : :info
+
+      # ── What one row of a "publish these DNS records" table should show ──
+      #
+      # Asking the plan reconciles the row against the instruction in ONE place.
+      # A view doing it itself re-derives the decision to withhold
+      # (offered_record) that the plan has already made, and the two can drift.
+
+      # Does this row carry the merged replacement instead of its own value?
+      # Only the SPF row at the name we resolved, and only when a merged line is
+      # actually on offer (never when it is withheld for the lookup cap).
+      def replaces?(name:, value:)
+        offered = offered_record
+        return false if offered.nil? || offered.empty?
+        return false unless value.to_s.start_with?("v=spf1")
+
+        Record.normalize_name(name) == self.name
+      end
+
+      def value_for(name:, value:)
+        replaces?(name: name, value: value) ? offered_record : value
+      end
+
+      # The "no instruction beyond the standalone record" plan, so no caller has
+      # to nil-check before asking a question. It answers everything the way a
+      # real :publish plan does: nothing to replace, nothing to warn about.
+      def self.none(name: nil, record: nil)
+        new(action: :publish, name: name && Record.normalize_name(name), record: record,
+            existing_records: [], notes: [], resolved: false,
+            lookup_limit: Authorization::MAX_DNS_LOOKUPS, over_lookup_limit: false)
+      end
+    end
+  end
+end

data/lib/mailertogo/spf/record.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module MailerToGo
+  module SPF
+    # Reading and normalising the raw text of an SPF record. Everything here is
+    # pure: no DNS, no state, no opinions about who you are.
+    module Record
+      module_function
+
+      # A hostname as SPF compares them: case-insensitive, root dot optional
+      # (RFC 7208 §4.3 — the domain-spec is a DNS name, and DNS names are
+      # compared case-insensitively).
+      def normalize_name(name)
+        name.to_s.strip.downcase.chomp(".")
+      end
+
+      # A TXT answer as a single string.
+      #
+      # A TXT record is a sequence of character-strings, each capped at 255
+      # octets (RFC 1035 §3.3.14), so a long SPF record arrives as adjacent
+      # quoted chunks — `"v=spf1 include:_spf.mailer" "togo.net ~all"`. RFC 7208
+      # §3.3 says to concatenate them with no separator. SPF terms never contain
+      # a quote, so joining on quote boundaries is safe.
+      def normalize_txt(txt)
+        txt.to_s.strip.gsub(/"\s*"/, "").delete('"').strip
+      end
+
+      # Is this TXT string an SPF record? RFC 7208 §4.5: the version section is
+      # exactly "v=spf1", matched case-insensitively, followed by a space or the
+      # end of the record. A TXT record starting "v=spf10" is not SPF.
+      def spf_record?(txt)
+        txt.to_s.match?(/\Av=spf1(\s|\z)/i)
+      end
+
+      # The name an SPF record's `include:` mechanism points at
+      # ("v=spf1 include:X ~all" → "X"), so a caller can pass the record it wants
+      # published and let us derive the mechanism from it. nil when the record
+      # has no include.
+      def include_target(record)
+        term = record.to_s.split(/\s+/).find { |t| t.downcase.start_with?("include:") }
+        term&.split(":", 2)&.last
+      end
+
+      # The ip4:/ip6: terms of a term list, as IPAddr networks. Unparseable
+      # literals are dropped rather than raised on: a customer's malformed term
+      # is their record's problem, not a reason for us to blow up.
+      def ip_nets(terms)
+        terms.filter_map do |term|
+          t = strip_qualifier(term)
+          next unless t.downcase.start_with?("ip4:", "ip6:")
+
+          begin
+            IPAddr.new(t.split(":", 2).last)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      # RFC 7208 §4.6.2 — a mechanism may carry a leading qualifier
+      # (+ - ~ ?); "+" is the default when it is absent.
+      def strip_qualifier(term)
+        term.to_s.sub(/\A[+\-~?]/, "")
+      end
+
+      def qualifier_of(term)
+        term.to_s[/\A[+\-~?]/]
+      end
+
+      # The mechanism name of a term ("include:x" → "include", "ip4:1.2.3.4" →
+      # "ip4", "a/24" → "a"), or nil when the term is a modifier or junk.
+      def mechanism_of(term)
+        strip_qualifier(term)[%r{\A([a-z0-9]+)(?::|/|\z)}i, 1]&.downcase
+      end
+
+      # The terms of a record, without the leading "v=spf1".
+      def terms(record)
+        record.to_s.split(/\s+/).drop(1)
+      end
+    end
+  end
+end

data/lib/mailertogo/spf/resolver.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "resolv"
+require "mailertogo/spf/record"
+
+module MailerToGo
+  module SPF
+    # The DNS seam.
+    #
+    # A resolver is anything that responds to `#call(name)` and returns:
+    #
+    #   [String, …] — the TXT strings published at that name
+    #   []          — the name exists but has no TXT (or does not exist at all):
+    #                 a definitive "nothing here"
+    #   nil         — DNS did not answer (timeout, SERVFAIL, refused):
+    #                 inconclusive, verdict withheld
+    #
+    # That three-way return is the whole contract, and the nil is the important
+    # part: a resolver hiccup must never be reported as "this domain does not
+    # authorise you". Everything in this gem funnels a nil into an :unknown
+    # result rather than a :fail.
+    #
+    # A plain lambda satisfies the contract, which is how the test suite runs
+    # with no network at all:
+    #
+    #   zone = { "example.com" => ["v=spf1 include:_spf.mailertogo.net ~all"] }
+    #   MailerToGo::SPF.authorize("example.com", resolver: ->(n) { zone.fetch(n, []) })
+    #
+    # The default below uses Ruby's stdlib Resolv::DNS, so the gem has no runtime
+    # dependencies. If you already speak DNS-over-HTTPS (or hold a resolver pool,
+    # or want per-request caching), pass your own — see the README.
+    class Resolver
+      DEFAULT_TIMEOUT = 3
+
+      # timeout      — seconds per nameserver attempt.
+      # nameservers  — override the system resolvers, e.g. %w[1.1.1.1 8.8.8.8].
+      def initialize(timeout: DEFAULT_TIMEOUT, nameservers: nil)
+        @timeout = timeout
+        @nameservers = nameservers
+      end
+
+      def call(name)
+        query = Record.normalize_name(name)
+        return [] if query.empty?
+
+        dns = @nameservers ? ::Resolv::DNS.new(nameserver: Array(@nameservers)) : ::Resolv::DNS.new
+        dns.timeouts = @timeout
+        begin
+          dns.getresources(query, ::Resolv::DNS::Resource::IN::TXT).map { |r| r.strings.join }
+        ensure
+          dns.close
+        end
+      rescue ::Resolv::ResolvError
+        # Resolv collapses NXDOMAIN and "no information" into one error, so this
+        # is the conservative reading: the name published nothing. A resolver
+        # that can see the rcode (DoH, for instance) should return nil for
+        # SERVFAIL and [] only for NXDOMAIN/NODATA — see the README.
+        []
+      rescue StandardError
+        # Timeouts (Resolv::ResolvTimeout) and everything else unexpected:
+        # inconclusive, never a failure.
+        nil
+      end
+    end
+
+    # Wraps any resolver in a small TTL cache.
+    #
+    # Resolving an SPF chain is up to ten serial round-trips, and this runs in
+    # request paths ("check my domain" pages) where that is not acceptable
+    # twice. Failures (nil) are deliberately NOT cached: caching a timeout would
+    # pin a healthy domain into :unknown for the whole TTL.
+    class CachingResolver
+      def initialize(resolver, ttl: 300, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @resolver = resolver
+        @ttl = ttl
+        @clock = clock
+        @entries = {}
+        @mutex = Mutex.new
+      end
+
+      def call(name)
+        key = Record.normalize_name(name)
+        now = @clock.call
+        cached = @mutex.synchronize { @entries[key] }
+        return cached[1] if cached && cached[0] > now
+
+        answer = @resolver.call(key)
+        @mutex.synchronize { @entries[key] = [now + @ttl, answer] } unless answer.nil?
+        answer
+      end
+
+      def clear
+        @mutex.synchronize { @entries.clear }
+      end
+    end
+  end
+end

data/lib/mailertogo/spf/result.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module MailerToGo
+  module SPF
+    # The answer to "does this domain's published SPF authorise me?", shaped so
+    # callers ask it questions rather than pattern-match a hash.
+    #
+    # status — :pass | :pinned | :fail | :permerror | :unknown
+    #
+    #   :pass      — the sender is reachable from the record, directly or
+    #                through its include chain: durable authorisation.
+    #   :pinned    — no include chain to the sender, but the record hardcodes
+    #                the sender's current sending addresses. Mail passes SPF
+    #                *today* and breaks silently the moment an address moves,
+    #                so this is deliberately NOT :pass. See #pinned?.
+    #   :fail      — the chain resolved fine; the sender simply is not in it.
+    #   :permerror — the record is broken (duplicate records, or past the
+    #                §4.6.4 lookup cap). Receivers reject it, so nothing passes.
+    #   :unknown   — DNS did not answer. Verdict withheld, NOT a failure.
+    #
+    # The four-valued status exists so a resolver hiccup can never be mistaken
+    # for "this domain removed my record". Anything that gates a customer on SPF
+    # has to be able to tell those apart.
+    #
+    # reason narrows :permerror (:duplicate_records | :lookup_limit) and :pinned
+    # (:pinned_full | :pinned_partial).
+    #
+    # all_qualifier (:pass | :fail | :softfail | :neutral | nil) is what the
+    # record tells receivers to do with mail it does NOT authorise — the
+    # qualifier on its terminal `all` (RFC 7208 §5.1). It is deliberately a
+    # FIELD rather than a fifth status: the yes/no decision ("is my include
+    # published?") is identical either way, but a `~all` domain's unauthorised
+    # mail is merely marked while a `-all` domain's is rejected outright, and
+    # the customer's remedy is far more urgent in the second case. Callers that
+    # write to humans need to say which one they published.
+    #
+    # partial is true when part of the chain did not resolve, which makes
+    # `lookups` a FLOOR rather than the real cost. Harmless for the verdict — a
+    # match is a match — but it matters to anyone pricing a record against the
+    # §4.6.4 budget, who must not report "this fits" from a count it could not
+    # finish.
+    Result = Struct.new(:status, :reason, :detail, :matched, :lookups,
+                        :all_qualifier, :partial, keyword_init: true) do
+      def pass? = status == :pass
+      def pinned? = status == :pinned
+      def permerror? = status == :permerror
+      def unknown? = status == :unknown
+      def failed? = %i[fail permerror].include?(status)
+      def partial? = partial == true
+
+      # Unauthorised, but under a `~all`: receivers mark the mail rather than
+      # rejecting it, so the domain is in a materially better position than a
+      # `-all` :fail. Same defect, different urgency.
+      def softfail? = status == :fail && all_qualifier == :softfail
+
+      # The record IS broken for receivers, but the sender's include is sitting
+      # in it. Gating callers use this to avoid treating "the customer's SPF has
+      # an unrelated RFC problem" as "the customer removed my record" — the
+      # remedy is completely different, and un-verifying them is wrong.
+      def permerror_with_sender_published? = permerror? && !matched.to_s.empty?
+
+      # Which defect to tell the customer about, or nil when the record is
+      # clean: :ip_pinned | :lookup_limit | :duplicate_records.
+      def defect
+        case status
+        when :pinned then :ip_pinned
+        when :permerror then reason == :lookup_limit ? :lookup_limit : :duplicate_records
+        end
+      end
+    end
+  end
+end

data/lib/mailertogo/spf/sender.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "mailertogo/spf/record"
+
+module MailerToGo
+  module SPF
+    # The sender you are asking about: "which names in a customer's SPF record
+    # mean *me*?"
+    #
+    # It is deliberately a set, not a single string. A sending service usually
+    # publishes a chain — an outer alias that customers are told to include, and
+    # a leaf that actually lists the addresses:
+    #
+    #   mailertogo.net       TXT  v=spf1 include:_spf.mailertogo.net ~all
+    #   _spf.mailertogo.net  TXT  v=spf1 ip4:… ip4:… ~all
+    #
+    # A customer who publishes `include:mailertogo.net` is authorised just as
+    # surely as one who publishes `include:_spf.mailertogo.net`; both must count,
+    # or you report a false failure against a domain that passes at every real
+    # receiver. Staging/regional spellings of the same zone belong here too.
+    class Sender
+      attr_reader :include_name, :names
+
+      # include_name — the mechanism you tell customers to publish.
+      # aliases      — any other name that is equally you (outer alias, staging
+      #                zone, a legacy name you still honour).
+      def initialize(include_name, aliases: [])
+        @include_name = Record.normalize_name(include_name)
+        raise ArgumentError, "include name is required" if @include_name.empty?
+
+        @names = ([@include_name] + Array(aliases).map { |n| Record.normalize_name(n) })
+                 .reject(&:empty?)
+                 .uniq
+                 .freeze
+        freeze
+      end
+
+      # Does this name in someone's record mean us?
+      def covers?(name)
+        names.include?(Record.normalize_name(name))
+      end
+
+      # The standalone record a domain with no SPF of its own should publish.
+      def record(all: "~all")
+        "v=spf1 include:#{include_name} #{all}"
+      end
+
+      def to_s
+        include_name
+      end
+    end
+  end
+end

data/lib/mailertogo/spf/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MailerToGo
+  module SPF
+    VERSION = "0.1.0"
+  end
+end

data/lib/mailertogo/spf.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "mailertogo/spf/version"
+require "mailertogo/spf/record"
+require "mailertogo/spf/sender"
+require "mailertogo/spf/resolver"
+require "mailertogo/spf/result"
+require "mailertogo/spf/authorization"
+require "mailertogo/spf/plan"
+require "mailertogo/spf/merge_plan"
+
+module MailerToGo
+  # An SPF engine that reads a record the way a receiving MTA does: it resolves
+  # 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:
+  #
+  #   MailerToGo::SPF.authorize("example.com")
+  #     → does this domain's published SPF authorize me?
+  #
+  #   MailerToGo::SPF.merge_plan("example.com")
+  #     → what should I tell them to publish, given what is already there?
+  #
+  # 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
+  # and one keyword makes it work for anybody else:
+  #
+  #   MailerToGo::SPF.authorize("example.com", include: "spf.example.net")
+  module SPF
+    # MailerToGo publishes an outer alias and a leaf. Customers are told to
+    # include the leaf, but either one authorizes us, so both count as "me".
+    DEFAULT_INCLUDE = "_spf.mailertogo.net"
+    DEFAULT_ALIASES = ["mailertogo.net"].freeze
+
+    class << self
+      # Process-wide defaults. Everything here can also be passed per call.
+      #
+      #   MailerToGo::SPF.configure do |c|
+      #     c.include  = "spf.example.net"
+      #     c.aliases  = ["example.net"]
+      #     c.resolver = MailerToGo::SPF::CachingResolver.new(MailerToGo::SPF::Resolver.new)
+      #     c.logger   = Logger.new($stdout)
+      #   end
+      attr_accessor :logger
+      attr_writer :include, :aliases, :resolver
+
+      def include_name
+        defined?(@include) && @include ? @include : DEFAULT_INCLUDE
+      end
+
+      def aliases
+        defined?(@aliases) && @aliases ? @aliases : DEFAULT_ALIASES
+      end
+
+      # Resolving is I/O, so the default is built once and shared. Pass your own
+      # (any object responding to #call(name)) to change how DNS happens.
+      def resolver
+        @resolver ||= Resolver.new
+      end
+
+      def configure
+        yield self
+        self
+      end
+
+      # Does <hostname>'s published SPF authorize the sender?
+      # Returns a Result (see result.rb) — never raises for a DNS failure.
+      #
+      # published: evaluates a supplied record as if it were published at
+      # <hostname>, which is how you price a record that does not exist yet.
+      def authorize(hostname, include: nil, aliases: nil, resolver: nil,
+                    sender: nil, published: nil, logger: nil)
+        sender ||= sender_for(include || include_name, aliases)
+        raise ArgumentError, "no include name given or configured" if sender.nil?
+
+        Authorization.call(
+          hostname,
+          sender: sender,
+          resolver: resolver || self.resolver,
+          published: published,
+          logger: logger || self.logger
+        )
+      end
+
+      # What should this domain publish, given what is already at that name?
+      # Returns a Plan (see plan.rb).
+      #
+      # record: the standalone record you would otherwise hand them; defaults to
+      # the sender's own `v=spf1 include:… ~all`.
+      def merge_plan(name, record: nil, include: nil, aliases: nil, resolver: nil,
+                     sender: nil, authorization: nil, logger: nil)
+        # A record with no include mechanism gives us no identity to merge in —
+        # hand back a null plan rather than inventing one.
+        sender ||= sender_for(include || (record.nil? ? include_name : Record.include_target(record)), aliases)
+        return Plan.none(name: name, record: record) if sender.nil?
+
+        MergePlan.call(
+          name,
+          record: record || sender.record,
+          sender: sender,
+          resolver: resolver || self.resolver,
+          authorization: authorization,
+          logger: logger || self.logger
+        )
+      end
+
+      # 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)
+        sender_for(include || include_name, aliases)
+      end
+
+      private
+
+      # nil when there is no name to build a sender out of.
+      #
+      # The alias default is deliberately narrow: the configured aliases belong
+      # to the configured include, so asking about somebody else's include with
+      # no aliases of its own gets exactly that one name, not ours.
+      def sender_for(name, aliases)
+        name = name.to_s.strip
+        return nil if name.empty?
+
+        if aliases.nil?
+          aliases = Record.normalize_name(name) == Record.normalize_name(include_name) ? self.aliases : []
+        end
+        Sender.new(name, aliases: aliases)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: mailertogo-spf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- MailerToGo
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-15 00:00:00.000000000 Z
+dependencies: []
+description: |
+  An SPF engine that follows include:/redirect= chains, stops at the first
+  matching mechanism, and counts DNS-querying terms against RFC 7208 §4.6.4's
+  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.
+email:
+- support@mailertogo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mailertogo/spf.rb
+- lib/mailertogo/spf/authorization.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/version.rb
+homepage: https://github.com/aluminumio/mailertogo-spf
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/aluminumio/mailertogo-spf
+  changelog_uri: https://github.com/aluminumio/mailertogo-spf/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/aluminumio/mailertogo-spf/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Resolve SPF records the way a receiving MTA does, and plan the record a domain
+  should publish.
+test_files: []