mailauth 0.3.0

data/lib/mailauth/resolver.rb

@@ -0,0 +1,92 @@
+require "dnsruby"
+require "ipaddr"
+
+module MailAuth
+  # DNS for authentication. Injectable so tests can stand a hash in for a network.
+  # NotFound vs Timeout/ServerFailure matters: SPF counts a void lookup against a
+  # limit but abandons evaluation when the server didn't answer. Dnsruby rather
+  # than Resolv, which discards non-timeout rcodes and collapses SERVFAIL/REFUSED
+  # into the same empty answer as NXDOMAIN.
+  class Resolver
+    class Error < StandardError; end
+    class NotFound < Error; end     # NXDOMAIN or NODATA
+    class Timeout < Error; end
+    class ServerFailure < Error; end # SERVFAIL, REFUSED, or anything else we couldn't tell
+
+    QUERY_TIMEOUT = 5
+
+    def initialize(timeout: QUERY_TIMEOUT)
+      @timeout = timeout
+    end
+
+    # TXT character-strings are joined into one value (RFC 7208 §3.3).
+    def txt(name)
+      records("TXT", name).map { |record| record.strings.join }
+    end
+
+    def a(name)
+      records("A", name).map { |record| record.address.to_s }
+    end
+
+    # Dnsruby prints IPv6 in capitals; RFC 5952 §4.3 asks for lower case.
+    def aaaa(name)
+      records("AAAA", name).map { |record| record.address.to_s.downcase }
+    end
+
+    def mx(name)
+      records("MX", name).sort_by(&:preference).map { |record| record.exchange.to_s }
+    end
+
+    # Dnsruby puts the question name in `name` and the host in `domainname`.
+    def ptr(address)
+      records("PTR", IPAddr.new(address).reverse).map { |record| record.domainname.to_s }
+    end
+
+    private
+      # Filter by type: a CNAME answer carries the alias beside the records it leads to.
+      def records(type, name)
+        answers = resolver.query(name.to_s, type).answer.select { |record| record.type == type }
+
+        if answers.any?
+          answers
+        else
+          raise NotFound, "no #{type} records for #{name}"
+        end
+      rescue Dnsruby::NXDomain
+        raise NotFound, "no such name #{name}"
+      rescue Dnsruby::ResolvTimeout
+        # Descends from Timeout::Error, not Dnsruby::ResolvError.
+        raise Timeout, "timed out resolving #{type} #{name}"
+      rescue Dnsruby::ResolvError => error
+        # Fall through to ServerFailure, never NotFound: "we could not tell"
+        # must not become "there is nothing there".
+        raise ServerFailure, "couldn't resolve #{type} #{name}: #{reason(error)}"
+      end
+
+      # Dnsruby rcode classes often carry no message (message == class name).
+      # `class.name` is nil on an anonymous class — don't call methods on that.
+      def reason(error)
+        rcode = error.class.name&.split("::")&.last
+
+        case
+        when rcode.nil?                        then error.message
+        when error.message == error.class.name then rcode
+        else                                        "#{rcode}, #{error.message}"
+        end
+      end
+
+      def resolver
+        @resolver ||= Dnsruby::Resolver.new(**options).tap do |dns|
+          dns.dnssec = false
+          # Dnsruby caches by default in a process-wide store.
+          dns.do_caching = false
+          dns.query_timeout = @timeout
+        end
+      end
+
+      # Override in tests to point at a loopback nameserver.
+      def options
+        {}
+      end
+  end
+end

data/lib/mailauth/result.rb

@@ -0,0 +1,100 @@
+module MailAuth
+  # The vocabulary, matching what RFC 8601 registers so a verdict travels
+  # without translation.
+  module Status
+    PASS = "pass"
+    FAIL = "fail"
+    SOFTFAIL = "softfail"
+    NEUTRAL = "neutral"
+    NONE = "none"
+    TEMPERROR = "temperror"
+    PERMERROR = "permerror"
+  end
+
+  # `fail` says the check failed; `policy` says what the domain asked us to do
+  # about it. Folding those together is a consumer's decision, not ours.
+  DmarcResult = Data.define(:status, :policy, :pct, :alignment, :record) do
+    def initialize(status:, policy: nil, pct: nil, alignment: nil, record: nil)
+      super
+    end
+  end
+
+  SpfResult = Data.define(:status, :domain, :comment, :lookups) do
+    def initialize(status:, domain: nil, comment: nil, lookups: 0)
+      super
+    end
+  end
+
+  # One per DKIM-Signature header, whatever each one's fate.
+  Signature = Data.define(:status, :domain, :selector, :algorithm, :canonicalization, :comment, :aligned, :under_sized) do
+    def initialize(status:, domain: nil, selector: nil, algorithm: nil, canonicalization: nil, comment: nil, aligned: false, under_sized: nil)
+      super
+    end
+  end
+
+  DkimResult = Data.define(:signatures) do
+    # Precedence, not position: one good signature vindicates a message however
+    # many broken ones travel beside it.
+    PRECEDENCE = [ Status::PASS, Status::FAIL, Status::TEMPERROR, Status::PERMERROR, Status::NEUTRAL, Status::NONE ].freeze
+
+    def status
+      PRECEDENCE.find { |status| signatures.any? { |signature| signature.status == status } } || Status::NONE
+    end
+
+    def passing_domains
+      signatures.select { |signature| signature.status == Status::PASS }.map(&:domain).compact
+    end
+  end
+
+  # One ARC-Seal and one ARC-Message-Signature, reported apart because RFC 8617
+  # places no requirement that a set sign both with the same domain or selector.
+  ArcSeal = Data.define(:status, :domain, :selector, :algorithm, :comment) do
+    def initialize(status:, domain: nil, selector: nil, algorithm: nil, comment: nil)
+      super
+    end
+  end
+
+  ArcSignature = Data.define(:status, :domain, :selector, :algorithm, :comment) do
+    def initialize(status:, domain: nil, selector: nil, algorithm: nil, comment: nil)
+      super
+    end
+  end
+
+  # One ARC Set (RFC 8617 §4.2): what one hop sealed, and what it asserted about
+  # the message when it did. `claimed` is that hop's own account of the message's
+  # authentication, which a valid chain proves unmodified since sealing and
+  # proves nothing else about.
+  ArcSet = Data.define(:instance, :chain_status, :seal, :message_signature, :authentication_results, :claimed) do
+    def initialize(instance:, chain_status: nil, seal: nil, message_signature: nil, authentication_results: nil, claimed: {})
+      super
+    end
+  end
+
+  # Whether the chain holds, and who sealed it — never whether any of them is to
+  # be believed. A chain is cheap to forge over a message of one's own, so trust
+  # is the caller's decision and deliberately has no answer here.
+  ArcResult = Data.define(:status, :sets, :oldest_pass, :comment) do
+    def initialize(status:, sets: [], oldest_pass: nil, comment: nil)
+      super
+    end
+
+    def newest
+      sets.max_by(&:instance)
+    end
+
+    # Oldest hop first, the order they sealed in.
+    def sealers
+      sets.sort_by(&:instance).filter_map { |set| set.seal&.domain }
+    end
+
+    def intact?
+      status == Status::PASS
+    end
+  end
+
+  Result = Data.define(:spf, :dkim, :dmarc, :arc, :authentication_results) do
+    def initialize(spf:, dkim:, dmarc:, authentication_results:, arc: nil)
+      super
+    end
+  end
+end

data/lib/mailauth/spf/budget.rb

@@ -0,0 +1,111 @@
+module MailAuth
+  module Spf
+    # RFC 7208 §4.6.4's allowance per evaluation, spent one query at a time.
+    # Ten lookups caps a stranger's record chaining `include`s forever; two
+    # voids catches a record whose targets mostly don't exist.
+    class Budget
+      MAX_LOOKUPS = 10
+      MAX_VOID_LOOKUPS = 2
+      MAX_NAME_LENGTH = 253
+      MAX_LABEL_LENGTH = 63
+
+      attr_reader :lookups
+
+      # `charging: false` lets the opening record fetch through free: it belongs
+      # to no mechanism, so nobody is billed for it.
+      def initialize(resolver, charging: true)
+        @resolver = resolver
+        @charging = charging
+        @lookups = 0
+        @voids = 0
+      end
+
+      def txt(name)
+        query(:txt, name)
+      end
+
+      def a(name)
+        query(:a, name)
+      end
+
+      def aaaa(name)
+        query(:aaaa, name)
+      end
+
+      def mx(name)
+        query(:mx, name)
+      end
+
+      # Takes the client address, not a name: the reverse zone is the
+      # resolver's business.
+      def ptr(address)
+        resolve(:ptr, address)
+      end
+
+      # `mx` and `ptr` fan out into an address lookup per name. RFC 7208 bounds
+      # that separately, so it gets its own allowance.
+      def branch
+        Budget.new(@resolver)
+      end
+
+      private
+        # A name that can't be put on the wire isn't an error — treated as a
+        # name that simply isn't there. Length alone doesn't make one: an
+        # over-long name is shortened and then asked for.
+        def query(type, name)
+          name = truncate(name)
+
+          if queryable?(name)
+            resolve(type, name)
+          else
+            spend
+            void
+          end
+        end
+
+        # RFC 7208 §7.3: a macro expansion past 253 octets loses whole labels
+        # from the left until it fits. The query is still made, so this costs a
+        # lookup and never a void.
+        def truncate(name)
+          name = name.to_s
+          name = name.split(".", 2).last while name.length > MAX_NAME_LENGTH && name.include?(".")
+          name
+        end
+
+        def resolve(type, name)
+          spend
+          @resolver.public_send(type, name)
+        rescue Resolver::NotFound
+          void
+        rescue Resolver::Timeout, Resolver::ServerFailure => error
+          raise TempError, error.message
+        end
+
+        def spend
+          if @charging
+            @lookups += 1
+            raise PermError, "more than #{MAX_LOOKUPS} DNS lookups" if @lookups > MAX_LOOKUPS
+          else
+            @charging = true
+          end
+        end
+
+        def void
+          @voids += 1
+
+          if @voids > MAX_VOID_LOOKUPS
+            raise PermError, "more than #{MAX_VOID_LOOKUPS} void DNS lookups"
+          else
+            []
+          end
+        end
+
+        def queryable?(name)
+          labels = name.to_s.chomp(".").split(".", -1)
+
+          name.to_s.length <= MAX_NAME_LENGTH && !labels.empty? &&
+            labels.all? { |label| (1..MAX_LABEL_LENGTH).cover?(label.length) }
+        end
+    end
+  end
+end

data/lib/mailauth/spf/macro.rb

@@ -0,0 +1,121 @@
+module MailAuth
+  module Spf
+    # RFC 7208 §7. The little templating language a record uses to build a name
+    # out of the message in front of it — `exists:%{ir}.%{d}` asks a question
+    # about this particular client rather than about the domain in general.
+    module Macro
+      # Whatever a transformer splits on, the pieces are rejoined with dots —
+      # the result is going into a domain name.
+      DELIMITERS = ".-+,/_="
+
+      # The expansion form, plus the three escapes, ordered so a lone `%` only
+      # matches once nothing legal does — exactly when it's a syntax error.
+      EXPANSION = /%\{([^}]*)\}|%%|%_|%-|%/
+
+      # macro-letter transformers *delimiter
+      BODY = /\A([a-z])(\d*)([r]?)([#{Regexp.escape(DELIMITERS)}]*)\z/i
+
+      # RFC 3986's unreserved set. An uppercase macro letter expands the same as
+      # its lowercase twin and then URL-escapes everything outside this.
+      RESERVED = /[^A-Za-z0-9\-._~]/
+
+      # toplabel = ( *alphanum ALPHA *alphanum ) / ( 1*alphanum "-" *( alphanum / "-" ) alphanum )
+      TOPLABEL = /(?:[a-z0-9]*[a-z][a-z0-9]*|[a-z0-9]+-[a-z0-9\-]*[a-z0-9])/i
+
+      # The tail of a domain-spec must be a real label rather than something a
+      # macro happened to produce, or a macro expansion standing alone.
+      DOMAIN_END = /\.#{TOPLABEL}\.?\z/o
+
+      class << self
+        # Raises PermError on anything the ABNF doesn't allow: a record that
+        # can't be parsed can't be obeyed.
+        def expand(string, context)
+          string.to_s.gsub(EXPANSION) do |match|
+            case match
+            when "%%" then "%"
+            when "%_" then " "
+            when "%-" then "%20"
+            when "%"  then raise PermError, "stray % in #{string}"
+            else expansion(Regexp.last_match(1), context)
+            end
+          end
+        end
+
+        # Checked before expansion, not after — a macro may expand into
+        # something no resolver will answer for, but that fails the
+        # mechanism, not the record.
+        def domain_spec(string, context)
+          if string.to_s.empty?
+            raise PermError, "empty domain-spec"
+          elsif !ends_well?(string)
+            raise PermError, "domain-spec #{string} does not end in a macro or a top-level label"
+          else
+            expand(string, context).downcase.chomp(".")
+          end
+        end
+
+        private
+          def ends_well?(string)
+            literal_tail = string.sub(/\A.*(?:%\{[^}]*\}|%%|%_|%-)/m, "")
+            literal_tail.empty? || literal_tail.match?(DOMAIN_END)
+          end
+
+          def expansion(body, context)
+            letter, digits, reverse, delimiters = body.match(BODY)&.captures
+
+            if letter
+              value = transform(value_for(letter.downcase, context), digits, !reverse.empty?, delimiters)
+              letter == letter.upcase ? escape(value) : value
+            else
+              raise PermError, "invalid macro %{#{body}}"
+            end
+          end
+
+          def value_for(letter, context)
+            case letter
+            when "s" then context.sender
+            when "l" then context.local
+            when "o" then context.sender_domain
+            when "d" then context.domain
+            when "i" then dotted(context.ip)
+            when "v" then context.ip.ipv4? ? "in-addr" : "ip6"
+            when "h" then context.helo.to_s
+            # %{p} needs the PTR lookup and forward confirmation of §5.5, which
+            # §7.2 discourages anyone from relying on and we don't do. "unknown"
+            # is what §7.2 prescribes when no name validates, and it matches
+            # nothing — where a real domain here would let `exists:%{p}.…` hit
+            # by accident.
+            when "p" then "unknown"
+            # c, r and t are legal in an explanation string and nowhere else,
+            # and we don't produce explanations.
+            else raise PermError, "macro letter %{#{letter}} is not allowed here"
+            end
+          end
+
+          # Dotted-quad for IPv4; one hex nibble per label for IPv6.
+          def dotted(ip)
+            if ip.ipv4?
+              ip.to_s
+            else
+              ip.to_string.delete(":").chars.join(".")
+            end
+          end
+
+          def transform(value, digits, reverse, delimiters)
+            if digits.empty? && !reverse && (delimiters.empty? || delimiters == ".")
+              value
+            else
+              parts = value.split(/[#{Regexp.escape(delimiters.empty? ? "." : delimiters)}]/)
+              parts = parts.reverse if reverse
+              parts = parts.last(digits.to_i) if digits.to_i > 0
+              parts.join(".")
+            end
+          end
+
+          def escape(value)
+            value.gsub(RESERVED) { |char| char.bytes.map { |byte| format("%%%02X", byte) }.join }
+          end
+      end
+    end
+  end
+end

data/lib/mailauth/spf/record.rb

@@ -0,0 +1,188 @@
+module MailAuth
+  module Spf
+    # `target` is already macro-expanded at parse time, so a broken macro is
+    # caught even when the mechanism it sits in is never reached.
+    Term = Data.define(:qualifier, :mechanism, :target, :network, :cidr4, :cidr6) do
+      def initialize(qualifier:, mechanism:, target: nil, network: nil, cidr4: nil, cidr6: nil)
+        super
+      end
+    end
+
+    # A `v=spf1` record, read and taken apart. Parsing is complete before
+    # evaluation begins, so `v=spf1 -all ip6` is a broken record — not a fail
+    # — even though nothing after `-all` can ever be evaluated.
+    class Record
+      VERSION = "v=spf1"
+
+      # A modifier is a name and an "=" reached before any ":" or "/".
+      # `redirect:example.com` therefore isn't one — it's a mechanism named
+      # "redirect", which is to say a typo. The name stops at the first "=":
+      # every one after it belongs to the macro-string, where "=" is both a
+      # legal delimiter and a legal literal.
+      MODIFIER = /\A(?<name>[^:\/=]*)=(?<value>.*)\z/
+      MODIFIER_NAME = /\A[a-z][a-z0-9\-_.]*\z/i
+
+      MECHANISM = /\A(?<qualifier>[+\-~?])?(?<name>[a-z0-9_.\-]+)(?<argument>[:\/].*)?\z/i
+
+      # domain-spec followed by an optional dual-cidr-length. The domain is
+      # matched lazily so that a trailing "/24" is read as a prefix length,
+      # while the slashes a domain-spec is allowed to contain stay in the name.
+      ARGUMENT = /\A(?<spec>.*?)(?:\/(?<cidr4>\d+))?(?:\/\/(?<cidr6>\d+))?\z/
+      DUAL_CIDR = /\A(?:\/(?<cidr4>\d+))?(?:\/\/(?<cidr6>\d+))?\z/
+      ADDRESS = /\A(?<address>.*?)(?:\/(?<length>\d+))?\z/
+
+      # SPF is defined over 7-bit ASCII, and a record carrying anything else has
+      # been mangled somewhere between its author and us.
+      PRINTABLE = /\A[\x20-\x7e]*\z/
+
+      # Zero is not an error but an answer — the domain publishes no policy.
+      # Two is: nothing chooses between them.
+      def self.fetch(domain, budget:, context:)
+        records = budget.txt(domain).select { |record| record.strip.split(/\s+/).first&.downcase == VERSION }
+
+        case records.length
+        when 0 then raise NoRecord, "no SPF record for #{domain}"
+        when 1 then new(records.first, context)
+        else raise PermError, "#{records.length} SPF records for #{domain}"
+        end
+      end
+
+      attr_reader :terms, :redirect
+
+      def initialize(text, context)
+        @text = text
+        @context = context
+        @terms = []
+        @modifiers = {}
+
+        parse
+      end
+
+      private
+        def parse
+          raise PermError, "non-ASCII characters in record" unless @text.match?(PRINTABLE)
+
+          @text.strip.split(/\s+/).drop(1).each do |term|
+            if modifier = term.match(MODIFIER)
+              parse_modifier(modifier[:name], modifier[:value])
+            else
+              @terms << parse_mechanism(term)
+            end
+          end
+
+          @redirect = @modifiers["redirect"]
+        end
+
+        def parse_modifier(name, value)
+          raise PermError, "invalid modifier name #{name}" unless name.match?(MODIFIER_NAME)
+
+          case name.downcase
+          when "redirect", "exp"
+            if @modifiers.key?(name.downcase)
+              raise PermError, "#{name} given more than once"
+            else
+              @modifiers[name.downcase] = Macro.domain_spec(value, @context)
+            end
+          else
+            # An unknown modifier does nothing, but its value is still a
+            # macro-string, and a record that can't state it correctly is
+            # broken however little we care about the answer.
+            Macro.expand(value, @context)
+          end
+        end
+
+        def parse_mechanism(term)
+          mechanism = term.match(MECHANISM)
+          raise PermError, "invalid term #{term}" unless mechanism
+
+          qualifier = mechanism[:qualifier] || "+"
+          argument = mechanism[:argument]
+
+          case name = mechanism[:name].downcase
+          when "all"                then all_term(qualifier, argument)
+          when "include", "exists"  then named_term(qualifier, name.to_sym, argument)
+          when "ptr"                then ptr_term(qualifier, argument)
+          when "a", "mx"            then address_term(qualifier, name.to_sym, argument)
+          when "ip4", "ip6"         then ip_term(qualifier, name.to_sym, argument)
+          else raise PermError, "unknown mechanism #{name}"
+          end
+        end
+
+        def all_term(qualifier, argument)
+          if argument
+            raise PermError, "all takes no argument"
+          else
+            Term.new(qualifier: qualifier, mechanism: :all)
+          end
+        end
+
+        def named_term(qualifier, mechanism, argument)
+          if argument&.start_with?(":")
+            Term.new(qualifier: qualifier, mechanism: mechanism, target: Macro.domain_spec(argument[1..], @context))
+          else
+            raise PermError, "#{mechanism} needs a domain"
+          end
+        end
+
+        # A bare `ptr` asks about the domain the record was found at.
+        def ptr_term(qualifier, argument)
+          if argument.nil?
+            Term.new(qualifier: qualifier, mechanism: :ptr, target: @context.domain)
+          elsif argument.start_with?(":")
+            Term.new(qualifier: qualifier, mechanism: :ptr, target: Macro.domain_spec(argument[1..], @context))
+          else
+            raise PermError, "ptr takes no prefix length"
+          end
+        end
+
+        def address_term(qualifier, mechanism, argument)
+          if argument.nil?
+            Term.new(qualifier: qualifier, mechanism: mechanism, target: @context.domain)
+          elsif argument.start_with?(":")
+            parsed = argument[1..].match(ARGUMENT)
+
+            Term.new(qualifier: qualifier, mechanism: mechanism, target: Macro.domain_spec(parsed[:spec], @context),
+              cidr4: prefix(parsed[:cidr4], 32), cidr6: prefix(parsed[:cidr6], 128))
+          else
+            parsed = argument.match(DUAL_CIDR) or raise PermError, "invalid prefix length #{argument}"
+
+            Term.new(qualifier: qualifier, mechanism: mechanism, target: @context.domain,
+              cidr4: prefix(parsed[:cidr4], 32), cidr6: prefix(parsed[:cidr6], 128))
+          end
+        end
+
+        def ip_term(qualifier, mechanism, argument)
+          raise PermError, "#{mechanism} needs an address" unless argument&.start_with?(":")
+
+          parsed = argument[1..].match(ADDRESS)
+          bits = mechanism == :ip4 ? 32 : 128
+          # We have taken the prefix length off ourselves; IPAddr would happily
+          # read a second one, and `ip4:1.2.3.4//32` is not a subtlety, it's a
+          # mistake.
+          raise PermError, "#{parsed[:address]} is not an address" if parsed[:address].include?("/")
+
+          network = IPAddr.new(parsed[:address])
+          raise PermError, "#{parsed[:address]} is not an #{mechanism} address" unless network.family == family(mechanism)
+
+          Term.new(qualifier: qualifier, mechanism: mechanism, network: network.mask(prefix(parsed[:length], bits) || bits))
+        rescue IPAddr::Error
+          raise PermError, "#{parsed[:address]} is not an address"
+        end
+
+        def family(mechanism)
+          mechanism == :ip4 ? Socket::AF_INET : Socket::AF_INET6
+        end
+
+        # Leading zeros and prefix lengths past the end of the address are
+        # both rejected.
+        def prefix(digits, limit)
+          if digits
+            raise PermError, "prefix length /#{digits} has a leading zero" if digits.length > 1 && digits.start_with?("0")
+            raise PermError, "prefix length /#{digits} is out of range" if digits.to_i > limit
+
+            digits.to_i
+          end
+        end
+    end
+  end
+end