spf 0.0.0

data/lib/spf/request.rb

@@ -0,0 +1,140 @@
+require 'ip'
+
+require 'spf/error'
+
+class SPF::Request
+
+  attr_reader :scope, :identity, :domain, :localpart, :ip_address, :ip_address_v6, :helo_identity, :versions
+  attr_accessor :record, :opt, :root_request, :super_request
+
+  VERSIONS_FOR_SCOPE = {
+    :helo  => [1   ],
+    :mfrom => [1, 2],
+    :pra   => [   2]
+  }
+
+  SCOPES_BY_VERSION = {
+    1      => [:helo, :mfrom      ],
+    2      => [       :mfrom, :pra]
+  }
+
+  DEFAULT_LOCALPART = 'postmaster'
+
+  def initialize(options = {})
+    @opt               = options
+    @state             = {}
+    @versions          = options[:versions]
+    @scope             = options[:scope]             || :mfrom
+    @scope             = @scope.to_sym if @scope.is_a?(String)
+    @_authority_domain = options[:authority_domain]
+    @identity          = options[:identity]
+    @ip_address        = options[:ip_address]
+    @helo_identity     = options[:helo_identity]
+    @root_request      = self
+    @super_request     = self
+    @record            = nil
+
+    # Scope:
+    versions_for_scope = VERSIONS_FOR_SCOPE[@scope] or
+      raise SPF::InvalidScopeError.new("Invalid scope '#{@scope}'")
+
+    # Versions:
+    if self.instance_variable_defined?(:@versions)
+      if @versions.is_a?(Symbol)
+        # Single version specified as a symbol:
+        @versions = [@versions]
+      elsif not @versions.is_a?(Array)
+        # Something other than symbol or array specified:
+        raise SPF::InvalidOptionValueError.new(
+          "'versions' option must be symbol or array")
+      end
+
+      # All requested record versions must be supported:
+      unsupported_versions = @versions.select { |x|
+        not SCOPES_BY_VERSION[x]
+      }
+      if unsupported_versions.any?
+        raise SPF::InvalidOptionValueError.new(
+          "Unsupported record version(s): " +
+          unsupported_versions.map { |x| "'#{x}'" }.join(', '))
+      end
+    else
+      # No versions specified, use all versions relevant to scope:
+      @versions = versions_for_scope
+    end
+
+    # Identity:
+    raise SPF::OptionRequiredError.new(
+      "Missing required 'identity' option") unless @identity
+    raise SPF::InvalidOptionValueError.new(
+      "'identity' option must not be empty") if @identity.empty?
+
+    # Extract domain and localpart from identity:
+    if ((@scope == :mfrom or @scope == :pra) and
+        @identity =~ /^(.*)@(.*?)$/)
+      @localpart = $1
+      @domain    = $2
+    else
+      @domain    = @identity
+    end
+    # Lower-case domain and removee eventual trailing dot.
+    @domain.downcase!
+    @domain.chomp!('.')
+    if (not self.instance_variable_defined?(:@localpart) or
+        not @localpart or not @localpart.length > 0)
+      @localpart = DEFAULT_LOCALPART
+    end
+
+    # HELO identity:
+    if @scope == :helo
+      @helo_identity ||= @identity
+    end
+
+    # IP address:
+    if [:helo, :mfrom, :pra].find(@scope) and not self.instance_variable_defined?(:@ip_address)
+      raise SPF::OptionRequiredError.new("Missing required 'ip_address' option")
+    end
+
+    # Ensure ip_address is an IP object:
+    unless @ip_address.is_a?(IP)
+      @ip_address = IP.new(@ip_address)
+    end
+
+    # Convert IPv4 address to IPv4-mapped IPv6 address:
+
+    if SPF::Util.ipv6_address_is_ipv4_mapped(self.ip_address)
+      @ip_address_v6 = @ip_address # Accept as IPv6 address as-is
+      @ip_address = SPF::Util.ipv6_address_to_ipv4(@ip_address)
+    elsif @ip_address.is_a?(IP::V4)
+      @ip_address_v6 = SPF::Util.ipv4_address_to_ipv6(@ip_address)
+    elsif @ip_address.is_a?(IP::V6)
+      @ip_address_v6 = @ip_address
+    else
+      raise SPF::InvalidOptionValueError.new("Unexpected IP address version");
+    end
+  end
+
+  def new_sub_request(options)
+    obj = self.class.new(opt.merge(options))
+    obj.super_request = self
+    obj.root_request  = super_request.root_request
+    return obj
+  end
+
+  def authority_domain
+    return (@_authority_domain or @domain)
+  end
+
+  def state(field, value = nil)
+    unless field
+      raise SPF::OptionRequiredError.new('Field name required')
+    end
+    if value and value === Fixnum
+      @state[field] = 0 unless @state[field]
+      @state[field] += value
+    else
+      @state[field] = value
+    end
+  end
+end
+

data/lib/spf/result.rb

@@ -0,0 +1,218 @@
+require 'spf/model'
+require 'spf/util'
+
+class SPF::Result < Exception
+
+  attr_reader :server, :request
+
+  class SPF::Result::Pass < SPF::Result
+    def code
+      :pass
+    end
+  end
+
+  class SPF::Result::Fail < SPF::Result
+    def code
+      :fail
+    end
+
+    def authority_explanation
+      if self.instance_variable_defined?(:@authority_explanation)
+        return @authority_explanation
+      end
+
+      @authority_explanation = nil
+
+      server  = @server
+      request = @request
+
+      authority_explanation_macrostring = request.state('authority_explanation')
+
+      # If an explicit explanation was specified by the authority domain...
+      if authority_explanation_macrostring
+        begin
+          # ... then try to expand it:
+          @authority_explanation = authority_explanation_macrostring.expand
+        rescue SPF::InvalidMacroString
+          # Igonre expansion errors and leave authority explanation undefined.
+        end
+      end
+
+      # If no authority explanation could be determined so far...
+      unless @authority_explanation
+        @authority_explanation = server.default_authority_explanation.new({:request => request}).expand
+      end
+      return @authority_explanation
+    end
+  end
+
+  class SPF::Result::SoftFail < SPF::Result
+    def code
+      :softfail
+    end
+  end
+
+  class SPF::Result::Neutral < SPF::Result
+    def code
+      :neutral
+    end
+  end
+
+  class SPF::Result::NeutralByDefault < SPF::Result::Neutral
+    # This is a special-case of the Neutral result that is thrown as a default
+    # when "falling off" the end of the record.  See SPF::Record.eval().
+    NAME = :neutral_by_default
+    def code
+      :neutral_by_default
+    end
+  end
+
+  class SPF::Result::None < SPF::Result
+    def code
+      :none
+    end
+  end
+
+  class SPF::Result::Error < SPF::Result
+    def code
+      :error
+    end
+  end
+
+  class SPF::Result::TempError < SPF::Result::Error
+    def code
+      :temperror
+    end
+  end
+
+  class SPF::Result::PermError < SPF::Result::Error
+    def code
+      :permerror
+    end
+  end
+
+
+  RESULT_CLASSES = {
+    :pass       => SPF::Result::Pass,
+    :fail       => SPF::Result::Fail,
+    :softfail   => SPF::Result::SoftFail,
+    :neutral    => SPF::Result::Neutral,
+    :neutral_by_default => SPF::Result::NeutralByDefault,
+    :none       => SPF::Result::None,
+    :error      => SPF::Result::Error,
+    :permerror  => SPF::Result::PermError,
+    :temperror  => SPF::Result::TempError
+  }
+
+  RECEIVED_SPF_HEADER_NAME = 'Received-SPF'
+
+  RECEIVED_SPF_HEADER_SCOPE_NAMES_BY_SCOPE = {
+    :helo       => 'helo',
+    :mfrom      => 'envelope-from',
+    :pra        => 'pra'
+  }
+
+  RECEIVED_SPF_HEADER_IDENTITY_KEY_NAMES_BY_SCOPE = {
+    :helo       => 'helo',
+    :mfrom      => 'envelope-from',
+    :pra        => 'pra'
+  }
+
+  ATEXT_PATTERN     = /[[:alnum:]!#\$%&'*+\-\/=?^_`{|}~]/
+  DOT_ATOM_PATTERN  = /
+    (#{ATEXT_PATTERN})+ ( \. (#{ATEXT_PATTERN})+ )*
+  /x
+
+  def initialize(args = [])
+    @server = args.shift if args.any?
+    unless self.instance_variable_defined?(:@server)
+      raise SPF::OptionRequiredError.new('SPF server object required')
+    end
+    @request = args.shift if args.any?
+    unless self.instance_variable_defined?(:@request)
+      raise SPF::OptionRequiredError.new('Request object required')
+    end
+  end
+
+  def name
+    return self.code
+  end
+
+  def klass(name=nil)
+    if name
+      name = name.to_sym if name.is_a?(String)
+      return self.RESULT_CLASSES[name]
+    else
+      return name
+    end
+  end
+
+  def isa_by_name(name)
+    suspect_class = self.klass(name)
+    return false unless suspect_class
+    return self.is_a?(suspect_class)
+  end
+  
+  def is_code(code)
+    return self.isa_by_name(code)
+  end
+
+  def to_s
+    return sprintf('%s (%s)', self.name, SPF::Util.sanitize_string(super.to_s))
+  end
+
+  def local_explanation
+    return @local_explanation if self.instance_variable_defined?(:@local_explanation)
+
+    # Prepare local explanation:
+    request = self.request
+    local_explanation = request.state(:local_explanation)
+    if local_explanation
+      local_explanation = sprintf('%s (%s)', local_explanation.expand, @text)
+    else
+      local_explanation = @text
+    end
+
+    # Resolve authority domains of root-request and bottom sub-requests:
+    root_request = request.root_request
+    local_explanation = (request == root_request or not root_request) ?
+      sprintf('%s: %s', request.authority_domain, local_explanation) :
+      sprintf('%s ... %s: %s', root_request.authority_domain, request.authority_domain, local_explanation)
+
+    return @local_explanation = SPF::Util.sanitize_string(local_explanation)
+  end
+
+  def received_spf_header
+    return @received_spf_header if self.instance_variable_defined?(:@received_spf_header)
+    scope_name        = self.received_spf_header_scope_names_by_scope[@request.scope]
+    identify_key_name = self.received_spf_header_identity_key_names_by_scope[@request.scope]
+    info_pairs = [
+      :receiver                => @server.hostname || 'unknown',
+      :identity                => scope_name,
+      identity_key_name.to_sym => @request.identity,
+      :client_ip               => SPF::Util.ip_address_to_string(@request.ip_address)
+    ]
+    if @request.scope != :helo and @request.helo_identity
+      info_pairs[:helo] = @request.helo_identity
+    end
+    info_string = ''
+    while info_pairs.any?
+      key   = info_pairs.shift
+      value = info_pairs.shift
+      info_string += '; ' unless info_string.blank?
+      if value !~ /^#{DOT_ATOM_PATTERN}$/o
+        value.gsub!(/(["\\])/, "\\#{$1}") # Escape '\' and '"' characters.
+        value = "\"#{value}\""            # Double-quote value.
+      end
+      info_string += "#{key}=#{value}"
+    end
+    return @received_spf_header = sprintf(
+      '%s: %s (%s) %s',
+      @received_spf_header_name,
+      self.code,
+      self.local_explanation,
+      info_string
+    )
+  end
+
+end

data/lib/spf/util.rb

@@ -0,0 +1,110 @@
+require 'ip'
+require 'socket'
+
+require 'spf/error'
+
+#
+# == SPF utility class
+#
+
+# Interface:
+# ##############################################################################
+
+
+# == SYNOPSIS
+# 
+# require 'spf/util'
+#
+#
+# hostname              = SPF::Util.hostname
+#
+# ipv6_address_v4mapped = SPF::Util.ipv4_address_to_ipv6(ipv4_address)
+#
+# ipv4_address          = SPF::Util->ipv6_address_to_ipv4($ipv6_address_v4mapped)
+#
+# is_v4mapped           = SPF::Util->ipv6_address_is_ipv4_mapped(ipv6_address)
+#
+# ip_address_string     = SPF::Util->ip_address_to_string(ip_address)
+#
+# reverse_name          = SPF::Util->ip_address_reverse(ip_address)
+#
+# validated_domain      = SPF::Util->valid_domain_for_ip_address(
+#                           spf_server, request, ip_address, domain,
+#                           find_best_match,  # Defaults to false
+#                           accept_any_domain # Defaults to false
+#                         )
+# sanitized_string      = SPF::Util->sanitize_string(string)
+#
+
+module SPF
+  module Util
+
+  def self.ipv4_mapped_ipv6_address_pattern
+    /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})/i
+  end
+
+  def self.hostname
+    return @hostname ||= Socket.gethostbyname(Socket.gethostname).first
+  end
+
+  def self.ipv4_address_to_ipv6(ipv4_address)
+    unless IP::V4 === ipv4_address
+      raise SPF::InvalidOptionValueError.new('IP::V4 address expected')
+    end
+    return IP.new("::ffff:#{ipv4_address.to_addr}/#{ipv4_address.pfxlen - 32 + 128}")
+  end
+
+  def self.ipv6_address_to_ipv4(ipv6_address)
+    unless IP::V6 === ipv6_address and ipv6_address.ipv4_mapped?
+      raise SPF::InvalidOptionValueError, 'IPv4-mapped IP::V6 address expected'
+    end
+    return ipv6_address.native
+  end
+
+  def self.ipv6_address_is_ipv4_mapped(ipv6_address)
+    return ipv6_address.ipv4_mapped?
+  end
+
+  def self.ip_address_to_string(ip_address)
+    unless IP::V4 === ip_address or IP::V6 === ip_address
+      raise SPF::InvalidOptionValueError.new('IP::V4 or IP::V6 address expected')
+    end
+    return ip_address.to_addr
+  end
+
+  def self.ip_address_reverse(ip_address)
+    unless IP::V4 === ip_address or IP::V6 === ip_address
+      raise SPF::InvalidOptionValueError.new('IP::V4 or IP::V6 address expected')
+    end
+    # Treat IPv4-mapped IPv6 addresses as IPv4 addresses:
+    ip_address = ipv6_address_to_ipv4(ip_address) if ip_address.ipv4_mapped?
+    case ip_address
+    when IP::V4
+      octets  = ip_address.to_addr.split('.').first(ip_address.pfxlen / 8)
+      return "#{octets .reverse.join('.')}.in-addr.arpa."
+    when IP::V6
+      nibbles = ip_address.to_hex .split('') .first(ip_address.pfxlen / 4)
+      return "#{nibbles.reverse.join('.')}.ip6.arpa."
+    end
+  end
+
+  def self.valid_domain_for_ip_address(
+    sever, request, ip_address, domain,
+    find_best_match   = false,
+    accept_any_domain = false
+  )
+    # TODO
+  end
+
+  def self.sanitize_string(string)
+    return \
+      string &&
+      string.
+        gsub(/([\x00-\x1f\x7f-\xff])/) { |c| sprintf('\x%02x',   c.ord) }.
+        gsub(/([\u{0100}-\u{ffff}])/)  { |u| sprintf('\x{%04x}', u.ord) }
+  end
+
+  end
+end
+
+# vim:sw=2 sts=2

data/lib/spf/version.rb

@@ -0,0 +1,5 @@
+module SPF
+  VERSION = '0.0.0'
+end
+
+# vim:sw=2 sts=2

data/lib/spf.rb

@@ -0,0 +1,48 @@
+require 'spf/error'
+require 'spf/model'
+require 'spf/request'
+require 'spf/eval'
+require 'spf/macro_string'
+require 'spf/util'
+
+#
+# == SPF - An object-oriented implementation of Sender Policy Framework
+#
+# == SYNOPSIS
+#
+# <tt>
+# 
+# require 'spf'
+#
+# spf_server = SPF::Server.new
+#
+# request    = SPF::Request.new({
+#   :versions       => [1, 2],              # optional
+#   :scope          => 'mfrom',             # or 'helo', 'pra'
+#   :identity       => 'fred@example.com',
+#   :ip_address     => '192.168.0.1',
+#   :helo_identity  => 'mta.example.com'    # optional,
+#                                           # for %{h} macro expansion
+# })
+#
+# result     = spf_server.process(request)
+# puts result
+# result_code      = result.code
+# local_exp        = result.local_explanation
+# authority_exp    = result.authority_explanation
+#   if result.is_code(:fail)
+# spf_header       = result.received_spf_header
+#
+# </tt>
+#
+# == DESCRIPTION
+#
+# <b>SPF</b> is an object-oriented implementation of Sender Policy Framework
+# (SPF).  See http://www.openspf.org for more information about SPF.
+#
+# This class collection aims to fully conform to the SPF specification (RFC
+# 4408 so as to serve both as a production quality SPF implementation and as a
+# reference for other developers of SPF implementations.
+#
+#
+# vim:sw=2 sts=2

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'spf-ruby'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

data/spec/spf_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "SPF" do
+  it "fails" do
+    fail "hey buddy, you should probably rename this file and start specing for real"
+  end
+end

data/spf.gemspec

@@ -0,0 +1,66 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "spf"
+  s.version = "0.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Andrew Flury", "Julian Mehnle"]
+  s.date = "2013-10-14"
+  s.description = "    An object-oriented Ruby implementation of the Sender Policy Framework (SPF)\n    e-mail sender authentication system, fully compliant with RFC 4408.\n"
+  s.email = ["code@agari.com", "aflury@agari.com", "jmehnle@agari.com"]
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    ".ruby-version",
+    "Gemfile",
+    "Gemfile.lock",
+    "README.rdoc",
+    "Rakefile",
+    "lib/spf.rb",
+    "lib/spf/error.rb",
+    "lib/spf/eval.rb",
+    "lib/spf/macro_string.rb",
+    "lib/spf/model.rb",
+    "lib/spf/request.rb",
+    "lib/spf/result.rb",
+    "lib/spf/util.rb",
+    "lib/spf/version.rb",
+    "spec/spec_helper.rb",
+    "spec/spf_spec.rb",
+    "spf.gemspec"
+  ]
+  s.homepage = "https://github.com/agaridata/spf-ruby"
+  s.licenses = ["none (all rights reserved)"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.23"
+  s.summary = "Implementation of the Sender Policy Framework"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, ["~> 2.8.0"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8.7"])
+    else
+      s.add_dependency(%q<rspec>, ["~> 2.8.0"])
+      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8.7"])
+    end
+  else
+    s.add_dependency(%q<rspec>, ["~> 2.8.0"])
+    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<bundler>, ["~> 1.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8.7"])
+  end
+end
+