coppertone 0.0.1

data/lib/coppertone/record.rb

@@ -0,0 +1,86 @@
+module Coppertone
+  # Represents an SPF record.  Includes class level methods for parsing
+  # record from a text string.
+  class Record
+    VERSION_STR =  'v=spf1'
+    RECORD_REGEXP = /\A#{VERSION_STR}(\s|\z)/i
+    ALLOWED_CHARACTERS = /\A([\x21-\x7e ]+)\z/
+
+    attr_reader :text
+    def initialize(raw_text)
+      fail RecordParsingError if raw_text.blank?
+      fail RecordParsingError unless self.class.record?(raw_text)
+      fail RecordParsingError unless ALLOWED_CHARACTERS.match(raw_text)
+      @text = raw_text.dup
+      validate_and_parse
+    end
+
+    def self.record?(record_text)
+      return false if record_text.blank?
+      RECORD_REGEXP.match(record_text.strip) ? true : false
+    end
+
+    def self.parse(text)
+      return nil unless record?(text)
+      new(text)
+    end
+
+    def validate_and_parse
+      text_without_prefix = text[VERSION_STR.length..-1]
+      @term_tokens = text_without_prefix.strip.split(/ /)
+      parse_terms
+    end
+
+    def parse_terms
+      @terms = []
+      @term_tokens.each do |token|
+        term = Term.build_from_token(token)
+        fail RecordParsingError,
+             "Could not parse record with #{text}" unless term
+        @terms << term
+      end
+      normalize_terms
+    end
+
+    def normalize_terms
+      # Discard any redirects if there is a directive with an
+      # all mechanism present
+      # Section 6.1
+      # TODO: PMG
+      find_redirect # Checks for duplicate redirect modifiers
+      exp # Checks for duplicate exp modifiers
+    end
+
+    def directives
+      @directives ||= @terms.select { |t| t.is_a?(Coppertone::Directive) }
+    end
+
+    def include_all?
+      directives.any? { |d| d.mechanism.is_a?(Coppertone::Mechanism::All) }
+    end
+
+    def modifiers
+      @modifiers ||= @terms.select { |t| t.is_a?(Coppertone::Modifier) }
+    end
+
+    def find_redirect
+      find_modifier(Coppertone::Modifier::Redirect)
+    end
+
+    def redirect
+      # Ignore if an 'all' modifier is present
+      return nil if include_all?
+      @redirect ||= find_redirect
+    end
+
+    def exp
+      @exp ||= find_modifier(Coppertone::Modifier::Exp)
+    end
+
+    def find_modifier(klass)
+      arr = modifiers.select { |m| m.is_a?(klass) }
+      fail RecordParsingError if arr.size > 1
+      arr.first
+    end
+  end
+end

data/lib/coppertone/record_evaluator.rb

@@ -0,0 +1,63 @@
+module Coppertone
+  # A helper class for finding SPF records for a domain.
+  class RecordEvaluator
+    attr_reader :record
+    def initialize(record)
+      @record = record
+    end
+
+    def evaluate(macro_context, request_context)
+      result = directive_result(macro_context, request_context)
+      return result unless result.none? || result.fail?
+      if result.fail?
+        evaluate_fail_result(result, macro_context, request_context)
+      else
+        # Evaluate redirect
+        evaluate_none_result(result, macro_context, request_context)
+      end
+    end
+
+    def directive_result(macro_context, request_context)
+      record.directives.reduce(Result.none) do |memo, d|
+        memo.none? ? d.evaluate(macro_context, request_context) : memo
+      end
+    end
+
+    def evaluate_fail_result(result, macro_context, request_context)
+      add_exp_to_result(result, macro_context, request_context)
+    end
+
+    def add_exp_to_result(result, macro_context, request_context)
+      result = add_default_exp(result)
+      return result unless record.exp
+      computed_exp = record.exp.evaluate(macro_context, request_context)
+      result.explanation = computed_exp if computed_exp
+      result
+    rescue Coppertone::Error
+      result
+    end
+
+    def add_default_exp(result)
+      result.explanation = Coppertone.config.default_explanation
+      result
+    end
+
+    def follow_redirect?
+      # Ignore the redirect if there's an all
+      # mechanism in the record
+      record.redirect && !record.include_all?
+    end
+
+    def evaluate_none_result(result, macro_context, request_context)
+      return result unless follow_redirect?
+      redirect_target = record.redirect.evaluate(macro_context, request_context)
+      if redirect_target
+        redirect_record =
+          RecordFinder.new(request_context.dns_client, redirect_target).record
+      end
+      fail InvalidRedirectError unless redirect_record
+      rc = macro_context.with_domain(redirect_target)
+      RecordEvaluator.new(redirect_record).evaluate(rc, request_context)
+    end
+  end
+end

data/lib/coppertone/record_finder.rb

@@ -0,0 +1,34 @@
+module Coppertone
+  # A helper class for finding SPF records for a domain.
+  class RecordFinder
+    attr_reader :dns_client, :domain
+    def initialize(dns_client, domain)
+      @dns_client = dns_client
+      @domain = domain
+    end
+
+    def record
+      @record ||=
+        begin
+          validate_txt_records
+          Record.parse(txt_records.first)
+        end
+    end
+
+    def txt_records
+      @txt_records ||=
+        begin
+          if Coppertone::Utils::DomainUtils.valid?(domain)
+            dns_client.fetch_txt_records(domain).map { |r| r[:text] }
+              .select { |r| Record.record?(r) }
+          else
+            []
+          end
+        end
+    end
+
+    def validate_txt_records
+      fail AmbiguousSpfRecordError if txt_records.size > 1
+    end
+  end
+end

data/lib/coppertone/request.rb

@@ -0,0 +1,68 @@
+module Coppertone
+  # Represents an SPF request.
+  class Request
+    attr_reader :ip_as_s, :sender, :helo_domain, :options, :result
+    attr_reader :helo_result, :mailfrom_result
+    def initialize(ip_as_s, sender, helo_domain, options = {})
+      @ip_as_s = ip_as_s
+      @sender = sender
+      @helo_domain = helo_domain
+      @options = options
+    end
+
+    def authenticate
+      check_spf_for_helo
+      return helo_result if helo_result && !helo_result.none?
+
+      check_spf_for_mailfrom
+      return mailfrom_result if mailfrom_result && !mailfrom_result.none?
+
+      no_matching_record? ? Result.none : Result.new(:neutral)
+    end
+
+    def no_matching_record?
+      helo_result.nil? && mailfrom_result.nil?
+    end
+
+    def check_spf_for_helo
+      @helo_result ||= check_spf_for_context(helo_context, 'helo')
+    end
+
+    def check_spf_for_mailfrom
+      @mailfrom_result ||= check_spf_for_context(mailfrom_context, 'mailfrom')
+    end
+
+    def check_spf_for_context(macro_context, identity)
+      record = spf_record(macro_context)
+      @result = spf_request(macro_context, record, identity) if record
+    rescue Coppertone::TemperrorError => e
+      Result.temperror(e.message)
+    rescue Coppertone::PermerrorError => e
+      Result.permerror(e.message)
+    end
+
+    def request_context
+      @request_context ||= RequestContext.new(options)
+    end
+
+    def helo_context
+      MacroContext.new(helo_domain, ip_as_s, sender, helo_domain, options)
+    end
+
+    def mailfrom_context
+      MacroContext.new(nil, ip_as_s, sender, helo_domain, options)
+    end
+
+    def spf_record(macro_context)
+      RecordFinder.new(request_context.dns_client,
+                       macro_context.domain).record
+    end
+
+    def spf_request(macro_context, record, identity)
+      return Result.new(:none) if record.nil?
+      r = RecordEvaluator.new(record).evaluate(macro_context, request_context)
+      r.identity = identity
+      r
+    end
+  end
+end

data/lib/coppertone/request_context.rb

@@ -0,0 +1,67 @@
+require 'active_support/core_ext/module/delegation'
+require 'coppertone/dns/resolv_client'
+
+module Coppertone
+  # A container for information that should span the lifetime of
+  # an SPF check.  This include the DNS client, the locale used
+  # for error messages, limits for DNS requests of different
+  # types, and limiters that ensure those limits are not exceeded
+  # across the lifetime of the request.
+  class RequestContext
+    def initialize(options = {})
+      @options = (options || {}).dup
+    end
+
+    def register_dns_lookup_term
+      dns_lookup_term_count_limiter.increment!
+    end
+
+    def register_void_dns_result
+      void_dns_result_count_limiter.increment!
+    end
+
+    def dns_lookups_per_mx_mechanism_limit
+      config_value(:dns_lookups_per_mx_mechanism_limit)
+    end
+
+    def dns_lookups_per_ptr_mechanism_limit
+      config_value(:dns_lookups_per_ptr_mechanism_limit)
+    end
+
+    def message_locale
+      config_value(:message_locale)
+    end
+
+    def dns_client
+      @dns_client ||=
+        if @options[:dns_client]
+          @options[:dns_client]
+        elsif @options[:dns_client_class]
+          @options[:dns_client_class].new
+        elsif Coppertone.config.dns_client_class
+          Coppertone.config.dns_client_class.new
+        else
+          Coppertone::DNS::ResolvClient.new
+        end
+    end
+
+    private
+
+    def dns_lookup_term_count_limiter
+      limit = config_value(:terms_requiring_dns_lookup_limit)
+      @dns_lookup_term_count_limiter ||=
+        Coppertone::RequestCountLimiter.new(limit, 'DNS lookup term')
+    end
+
+    def void_dns_result_count_limiter
+      limit = config_value(:void_dns_result_limit)
+      @void_dns_result_count_limiter ||=
+        Coppertone::RequestCountLimiter.new(limit, 'DNS lookup term')
+    end
+
+    def config_value(k)
+      return @options[k] if @options.key?(k)
+      Coppertone.config.send(k)
+    end
+  end
+end

data/lib/coppertone/request_count_limiter.rb

@@ -0,0 +1,36 @@
+module Coppertone
+  # A utility class that encapsulates counter and limit behavior.  Primarily
+  # used to track and limit the number of DNS queries of various types.
+  class RequestCountLimiter
+    attr_accessor :count, :limit, :counter_description
+    def initialize(limit = nil, counter_description = nil)
+      self.limit = limit
+      self.counter_description = counter_description
+      self.count = 0
+    end
+
+    def increment!(num = 1)
+      self.count += num
+      check_if_limit_exceeded
+      count
+    end
+
+    def check_if_limit_exceeded
+      return if limit.nil?
+      fail Coppertone::LimitExceededError, exception_message if exceeded?
+    end
+
+    def exception_message
+      "Maximum #{counter_description} limit of #{limit} exceeded."
+    end
+
+    def exceeded?
+      return false unless limited?
+      count > limit
+    end
+
+    def limited?
+      !limit.nil?
+    end
+  end
+end

data/lib/coppertone/result.rb

@@ -0,0 +1,50 @@
+module Coppertone
+  # The result of an SPF query.  Includes a code, which indicates the
+  # overall result (pass, fail, softfail, etc.).  For different
+  # results it may include the mechanism which led to the result,
+  # an error message, and/or an explanation string.
+  class Result
+    NONE = :none
+
+    PASS = :pass
+    FAIL = :fail
+    SOFTFAIL = :softfail
+    NEUTRAL = :neutral
+
+    TEMPERROR = :temperror
+    PERMERROR = :permerror
+
+    attr_reader :code, :mechanism
+    attr_accessor :explanation, :problem, :identity
+    def initialize(code, mechanism = nil)
+      @code = code
+      @mechanism = mechanism
+    end
+
+    def self.from_directive(directive, code)
+      new(code, directive.mechanism)
+    end
+
+    def self.permerror(message)
+      r = Result.new(:permerror)
+      r.problem = message
+      r
+    end
+
+    def self.temperror(message)
+      r = Result.new(:temperror)
+      r.problem = message
+      r
+    end
+
+    def self.none
+      Result.new(:none)
+    end
+
+    %w(none pass fail softfail neutral temperror permerror).each do |t|
+      define_method("#{t}?") do
+        self.class.const_get(t.upcase) == send(:code)
+      end
+    end
+  end
+end

data/lib/coppertone/sender_identity.rb

@@ -0,0 +1,39 @@
+module Coppertone
+  # A consolidated sender identity, suitable for use with an SPF request.
+  # Parses the identity and ensures validity.  Also has accessor methods
+  # for the macro letters.
+  class SenderIdentity
+    DEFAULT_LOCALPART = 'postmaster'
+    EMAIL_ADDRESS_SPLIT_REGEXP = /^(.*)@(.*?)$/
+
+    attr_reader :sender, :localpart, :domain
+    def initialize(sender)
+      @sender = sender
+      initialize_localpart_and_domain
+    end
+
+    alias_method :s, :sender
+    alias_method :l, :localpart
+    alias_method :o, :domain
+
+    private
+
+    def initialize_localpart(matches)
+      localpart_candidate = matches[1] if matches
+      @localpart =
+        localpart_candidate.blank? ? DEFAULT_LOCALPART : localpart_candidate
+    end
+
+    def initialize_domain(matches)
+      domain_candidate = matches[2] if matches
+      @domain =
+        domain_candidate.blank? ? sender : domain_candidate
+    end
+
+    def initialize_localpart_and_domain
+      matches = EMAIL_ADDRESS_SPLIT_REGEXP.match(sender)
+      initialize_localpart(matches)
+      initialize_domain(matches)
+    end
+  end
+end

data/lib/coppertone/spf_service.rb

@@ -0,0 +1,9 @@
+module Coppertone
+  # Service interface for SPF authentication
+  class SpfService
+    def self.authenticate_email(ip_as_s, sender, helo_domain, options = {})
+      req = Coppertone::Request.new(ip_as_s, sender, helo_domain, options)
+      req.authenticate
+    end
+  end
+end

data/lib/coppertone/term.rb

@@ -0,0 +1,13 @@
+module Coppertone
+  # Instances of this class represent terms as defined in section 4.6.1 of
+  # the specification.  The Term class should be considered abstract,
+  # and should only be instantiated as its concrete subclasses.  Terms
+  # are generally parsed from text tokens in an SPF TXT record using the
+  # factory method in this class.
+  class Term
+    def self.build_from_token(token)
+      return nil unless token
+      Directive.matching_term(token) || Modifier.matching_term(token)
+    end
+  end
+end

data/lib/coppertone/utils/domain_utils.rb

@@ -0,0 +1,59 @@
+require 'addressable/idna'
+
+module Coppertone
+  module Utils
+    # A utility class that includes methods for working with
+    # domain names.
+    class DomainUtils
+      def self.valid?(domain)
+        return false if domain.blank?
+        labels = to_labels(domain)
+        return false if labels.length <= 1
+        return false if domain.length > 253
+        return false if labels.any? { |l| !valid_label?(l) }
+        true
+      end
+
+      def self.to_labels(domain)
+        Addressable::IDNA.to_ascii(domain).split('.')
+      end
+
+      NO_DASH_REGEXP = /\A[a-zA-Z0-9]*[a-zA-Z]+[a-zA-Z0-9]*\z/
+      DASH_REGEXP = /\A[a-zA-Z0-9]+\-[a-zA-Z0-9\-]*[a-zA-Z0-9]+\z/
+
+      def self.valid_hostname_label?(l)
+        return false unless valid_label?(l)
+        NO_DASH_REGEXP.match(l) || DASH_REGEXP.match(l)
+      end
+
+      def self.valid_label?(l)
+        (l.length >= 0) && (l.length <= 63)
+      end
+
+      def self.macro_expanded_domain(domain)
+        return nil if domain.blank?
+        labels = to_labels(domain)
+        domain = labels.join('.')
+        while domain.length > 253
+          labels = labels.drop(1)
+          domain = labels.join('.')
+        end
+        domain
+      end
+
+      def self.subdomain_of?(subdomain_candidate, domain)
+        subdomain_labels = to_labels(subdomain_candidate)
+        domain_labels = to_labels(domain)
+        num_labels_in_domain = domain_labels.length
+        return false if subdomain_labels.length <= domain_labels.length
+        subdomain_labels.last(num_labels_in_domain) == domain_labels
+      end
+
+      def self.subdomain_or_same?(candidate, domain)
+        return false unless valid?(domain) && valid?(candidate)
+        return true if domain == candidate
+        subdomain_of?(candidate, domain)
+      end
+    end
+  end
+end

data/lib/coppertone/utils/host_utils.rb

@@ -0,0 +1,22 @@
+require 'addressable/idna'
+
+module Coppertone
+  module Utils
+    # A utility class that includes methods for working with
+    # data about the host.
+    class HostUtils
+      def self.hostname
+        @hostname ||=
+          begin
+            Socket.gethostbyname(Socket.gethostname).first
+          rescue SocketError
+            Socket.gethostname
+          end
+      end
+
+      def self.clear_hostname
+        @hostname = nil
+      end
+    end
+  end
+end

data/lib/coppertone/utils/ip_in_domain_checker.rb

@@ -0,0 +1,53 @@
+module Coppertone
+  module Utils  # rubocop:disable Style/Documentation
+    class IPInDomainChecker
+      def initialize(macro_context, request_context)
+        @macro_context = macro_context
+        @request_context = request_context
+      end
+
+      def check(domain_name,
+                ip_v4_cidr_length = 32,
+                ip_v6_cidr_length = 128)
+        cidr_length = ip_v6? ? ip_v6_cidr_length : ip_v4_cidr_length
+        networks = ip_networks(domain_name, cidr_length)
+        @request_context.register_void_dns_result if networks.empty?
+
+        matching_network =
+          networks.find do |network|
+            network.include?(ip)
+          end
+        !matching_network.nil?
+      end
+
+      def ip_v6?
+        @macro_context.original_ipv6?
+      end
+
+      def ip
+        ip_v6? ? @macro_context.ip_v6 : @macro_context.ip_v4
+      end
+
+      def ip_networks(domain_name, cidr_length)
+        ip_records =
+          if ip_v6?
+            dns_client.fetch_aaaa_records(domain_name)
+          else
+            dns_client.fetch_a_records(domain_name)
+          end
+        filtered_records(ip_records, cidr_length)
+      end
+
+      def dns_client
+        @request_context.dns_client
+      end
+
+      def filtered_records(recs, cidr_length)
+        ips = recs.map do |r|
+          IPAddr.new(r[:address]).mask(cidr_length.to_i)
+        end
+        ips.select { |i| !i.nil? }
+      end
+    end
+  end
+end

data/lib/coppertone/utils/validated_domain_finder.rb

@@ -0,0 +1,40 @@
+module Coppertone
+  module Utils  # rubocop:disable Style/Documentation
+    # A class used to find validated domains as defined in
+    # section 5.5 of the RFC.
+    class ValidatedDomainFinder
+      def initialize(macro_context, request_context)
+        @mc = macro_context
+        @request_context = request_context
+      end
+
+      def find(target_name)
+        ip = @mc.original_ipv6? ? @mc.ip_v6 : @mc.ip_v4
+        ptr_names = fetch_ptr_names(ip)
+        ip_checker = IPInDomainChecker.new(@mc, @request_context)
+        ptr_names.find { |n| ptr_record_matches?(ip_checker, target_name, n) }
+      end
+
+      def fetch_ptr_names(ip)
+        dns_client = @request_context.dns_client
+        names = dns_client.fetch_ptr_records(ip.reverse).map do |ptr|
+          ptr[:name]
+        end
+        record_limit =
+          @request_context.dns_lookups_per_ptr_mechanism_limit
+        record_limit ? names.slice(0, record_limit) : names
+      end
+
+      def ptr_record_matches?(ip_checker,
+                              target_name, ptr_name)
+        is_candidate =
+          DomainUtils.subdomain_or_same?(ptr_name, target_name)
+        is_candidate && ip_checker.check(ptr_name)
+      rescue Coppertone::DNS::Error
+        # If a DNS error occurs when looking up a domain, treat it
+        # as a non match
+        false
+      end
+    end
+  end
+end

data/lib/coppertone/utils.rb

@@ -0,0 +1,4 @@
+require 'coppertone/utils/domain_utils'
+require 'coppertone/utils/host_utils'
+require 'coppertone/utils/ip_in_domain_checker'
+require 'coppertone/utils/validated_domain_finder'

data/lib/coppertone/version.rb

@@ -0,0 +1,3 @@
+module Coppertone  # rubocop:disable Style/Documentation
+  VERSION = '0.0.1'.freeze
+end