philiprehberger-email_validator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 66d9d94a5c449968eb64ab42f3c2a852b71ad9730f8135d6a7d43a39382c5fdd
+  data.tar.gz: 4e949ee122c5a9b8feb40b0ad4c76f069c02d661b3b1dd0603bc1e2b1c7d85c6
+SHA512:
+  metadata.gz: a54fc05245f37e0f56e0f1477e856b2bf4beeb63e758f57e5e6b17f3b107df9be24911eca192002e9a42d300b8dff5825b0343e54acb3e170e4cd6b9209031b1
+  data.tar.gz: 67b174b8a5b4fe73ce3ef81498ebc8335b80f104b28bd99aed6c27884b277049a097d75220f45385a98a649c7324829f372692e77f6842b0a52ebb04f4224a00

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-26
+
+### Added
+- Initial release
+- RFC 5322 email syntax validation with local part and domain rules
+- MX record verification using Ruby stdlib Resolv
+- Disposable email domain detection with built-in list of ~50 providers
+- Role-based address detection (admin@, info@, support@, etc.)
+- Result value object with errors, warnings, and valid? predicate

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,112 @@
+# philiprehberger-email_validator
+
+[![Tests](https://github.com/philiprehberger/rb-email-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-email-validator/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-email_validator.svg)](https://rubygems.org/gems/philiprehberger-email_validator)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-email-validator)](LICENSE)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
+
+RFC-compliant email validation with MX record verification
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-email_validator"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-email_validator
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/email_validator"
+
+Philiprehberger::EmailValidator.valid?("user@example.com")
+# => true
+
+Philiprehberger::EmailValidator.valid?("not-an-email")
+# => false
+```
+
+### Full Validation
+
+```ruby
+result = Philiprehberger::EmailValidator.validate("user@example.com")
+result.valid?    # => true
+result.errors    # => []
+result.warnings  # => []
+
+result = Philiprehberger::EmailValidator.validate("admin@example.com")
+result.valid?    # => true
+result.warnings  # => ["address appears to be role-based"]
+```
+
+### MX Record Verification
+
+```ruby
+result = Philiprehberger::EmailValidator.validate("user@example.com", check_mx: true)
+result.valid?  # => true (if domain has MX/A records)
+
+Philiprehberger::EmailValidator.mx_valid?("example.com")
+# => true
+```
+
+### Disposable Domain Detection
+
+```ruby
+Philiprehberger::EmailValidator.disposable?("user@mailinator.com")
+# => true
+
+result = Philiprehberger::EmailValidator.validate("user@mailinator.com", allow_disposable: false)
+result.valid?  # => false
+result.errors  # => ["disposable email domains are not allowed"]
+```
+
+### Role-Based Address Detection
+
+```ruby
+Philiprehberger::EmailValidator.role_based?("info@example.com")
+# => true
+
+Philiprehberger::EmailValidator.role_based?("alice@example.com")
+# => false
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `EmailValidator.valid?(email)` | Quick syntax check, returns boolean |
+| `EmailValidator.validate(email, check_mx: false, allow_disposable: true)` | Full validation returning Result |
+| `EmailValidator.mx_valid?(domain)` | Check if domain has MX or A records |
+| `EmailValidator.disposable?(email)` | Check if email uses a disposable domain |
+| `EmailValidator.role_based?(email)` | Detect role-based addresses (info@, admin@, etc.) |
+
+### `Result`
+
+| Method | Description |
+|--------|-------------|
+| `#valid?` | True if no validation errors |
+| `#errors` | Array of error message strings |
+| `#warnings` | Array of warning message strings |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](LICENSE)

data/lib/philiprehberger/email_validator/disposable.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module EmailValidator
+    # Disposable (throwaway) email domain detection.
+    #
+    # Maintains a built-in list of commonly used disposable email providers.
+    # Useful for preventing sign-ups with temporary email addresses.
+    module Disposable
+      # Built-in list of common disposable email domains.
+      DOMAINS = Set.new(%w[
+                          mailinator.com
+                          guerrillamail.com
+                          guerrillamail.de
+                          guerrillamail.net
+                          guerrillamail.org
+                          tempmail.com
+                          temp-mail.org
+                          throwaway.email
+                          sharklasers.com
+                          guerrillamailblock.com
+                          grr.la
+                          dispostable.com
+                          yopmail.com
+                          yopmail.fr
+                          trashmail.com
+                          trashmail.me
+                          trashmail.net
+                          mailnesia.com
+                          maildrop.cc
+                          discard.email
+                          mailcatch.com
+                          fakeinbox.com
+                          mailnull.com
+                          tempail.com
+                          tempr.email
+                          einrot.com
+                          getnada.com
+                          jetable.org
+                          mohmal.com
+                          burpcollaborator.net
+                          mailsac.com
+                          harakirimail.com
+                          tmail.ws
+                          guerrillamail.info
+                          mytemp.email
+                          tempmailaddress.com
+                          mailforspam.com
+                          safetymail.info
+                          trashymail.com
+                          mailexpire.com
+                          tempinbox.com
+                          spamgourmet.com
+                          mintemail.com
+                          mailzilla.com
+                          anonbox.net
+                          binkmail.com
+                          bobmail.info
+                          chammy.info
+                          deadaddress.com
+                          despammed.com
+                          devnullmail.com
+                          dontreg.com
+                          e4ward.com
+                          emailigo.de
+                        ]).freeze
+
+      class << self
+        # Check if an email address uses a known disposable domain.
+        #
+        # @param email [String] the email address to check
+        # @return [Boolean] true if the domain is in the disposable list
+        def disposable?(email)
+          return false unless email.is_a?(String)
+
+          domain = extract_domain(email)
+          return false if domain.nil?
+
+          DOMAINS.include?(domain.downcase)
+        end
+
+        # Check if a domain is in the disposable list.
+        #
+        # @param domain [String] the domain to check
+        # @return [Boolean]
+        def domain_disposable?(domain)
+          return false unless domain.is_a?(String)
+
+          DOMAINS.include?(domain.strip.downcase)
+        end
+
+        private
+
+        # Extract the domain from an email address.
+        #
+        # @param email [String]
+        # @return [String, nil]
+        def extract_domain(email)
+          parts = email.strip.split('@', 2)
+          return nil if parts.length != 2
+
+          parts[1]&.downcase
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/email_validator/mx_check.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'resolv'
+
+module Philiprehberger
+  module EmailValidator
+    # MX record verification using Ruby's built-in Resolv library.
+    #
+    # Checks whether a domain has valid MX records, falling back to
+    # A record lookup as permitted by RFC 5321 section 5.1.
+    module MxCheck
+      # Default DNS timeout in seconds.
+      DEFAULT_TIMEOUT = 5
+
+      class << self
+        # Check if a domain has valid MX records.
+        #
+        # Falls back to checking A records if no MX records are found,
+        # as RFC 5321 permits mail delivery to the A record host.
+        #
+        # @param domain [String] the domain to check
+        # @param timeout [Integer] DNS query timeout in seconds
+        # @return [Boolean] true if the domain has MX or A records
+        def valid?(domain, timeout: DEFAULT_TIMEOUT)
+          return false if domain.nil? || domain.strip.empty?
+
+          resolver = Resolv::DNS.new
+          resolver.timeouts = timeout
+
+          mx_records = fetch_mx_records(resolver, domain)
+          return true unless mx_records.empty?
+
+          a_records = fetch_a_records(resolver, domain)
+          !a_records.empty?
+        rescue Resolv::ResolvError, Resolv::ResolvTimeout
+          false
+        ensure
+          resolver&.close
+        end
+
+        # Retrieve MX records for a domain.
+        #
+        # @param domain [String] the domain to look up
+        # @param timeout [Integer] DNS query timeout in seconds
+        # @return [Array<String>] list of MX hostnames sorted by preference
+        def mx_records(domain, timeout: DEFAULT_TIMEOUT)
+          return [] if domain.nil? || domain.strip.empty?
+
+          resolver = Resolv::DNS.new
+          resolver.timeouts = timeout
+
+          records = fetch_mx_records(resolver, domain)
+          records.sort_by(&:preference).map { |r| r.exchange.to_s }
+        rescue Resolv::ResolvError, Resolv::ResolvTimeout
+          []
+        ensure
+          resolver&.close
+        end
+
+        private
+
+        # @param resolver [Resolv::DNS]
+        # @param domain [String]
+        # @return [Array<Resolv::DNS::Resource::IN::MX>]
+        def fetch_mx_records(resolver, domain)
+          resolver.getresources(domain, Resolv::DNS::Resource::IN::MX)
+        rescue Resolv::ResolvError, Resolv::ResolvTimeout
+          []
+        end
+
+        # @param resolver [Resolv::DNS]
+        # @param domain [String]
+        # @return [Array<Resolv::DNS::Resource::IN::A>]
+        def fetch_a_records(resolver, domain)
+          resolver.getresources(domain, Resolv::DNS::Resource::IN::A)
+        rescue Resolv::ResolvError, Resolv::ResolvTimeout
+          []
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/email_validator/result.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module EmailValidator
+    # Value object representing the outcome of an email validation.
+    #
+    # @example
+    #   result = EmailValidator.validate("user@example.com")
+    #   result.valid?   # => true
+    #   result.errors   # => []
+    #   result.warnings # => []
+    class Result
+      # @return [Array<String>] list of validation error messages
+      attr_reader :errors
+
+      # @return [Array<String>] list of non-fatal warning messages
+      attr_reader :warnings
+
+      # @param errors [Array<String>] validation error messages
+      # @param warnings [Array<String>] non-fatal warning messages
+      def initialize(errors: [], warnings: [])
+        @errors = errors.freeze
+        @warnings = warnings.freeze
+        freeze
+      end
+
+      # Whether the email passed all validation checks.
+      #
+      # @return [Boolean]
+      def valid?
+        @errors.empty?
+      end
+
+      # String representation for debugging.
+      #
+      # @return [String]
+      def to_s
+        if valid?
+          '#<EmailValidator::Result valid>'
+        else
+          "#<EmailValidator::Result invalid errors=#{@errors}>"
+        end
+      end
+
+      alias inspect to_s
+    end
+  end
+end

data/lib/philiprehberger/email_validator/syntax.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module EmailValidator
+    # RFC 5322 compliant email syntax validation.
+    #
+    # Validates local part rules, domain rules, and length limits
+    # according to the relevant RFCs (5321, 5322).
+    module Syntax
+      # Maximum total length of an email address (RFC 5321).
+      MAX_EMAIL_LENGTH = 254
+
+      # Maximum length of the local part (RFC 5321).
+      MAX_LOCAL_LENGTH = 64
+
+      # Maximum length of the domain part (RFC 5321).
+      MAX_DOMAIN_LENGTH = 253
+
+      # Maximum length of a single domain label.
+      MAX_LABEL_LENGTH = 63
+
+      # Characters allowed in the local part without quoting (RFC 5322 dot-atom).
+      LOCAL_CHAR_PATTERN = %r{\A[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+\z}
+
+      # Pattern for a valid domain label.
+      LABEL_PATTERN = /\A[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\z/
+
+      class << self
+        # Validate the syntax of an email address.
+        #
+        # @param email [String] the email address to validate
+        # @return [Array<String>] list of error messages (empty if valid)
+        def validate(email)
+          errors = []
+
+          return ['email must be a string'] unless email.is_a?(String)
+
+          stripped = email.strip
+
+          return ['email must not be empty'] if stripped.empty?
+
+          if stripped.length > MAX_EMAIL_LENGTH
+            errors << "email exceeds maximum length of #{MAX_EMAIL_LENGTH} characters"
+          end
+
+          parts = stripped.split('@', -1)
+
+          return ['email must contain an @ symbol'] if parts.length < 2
+
+          return ['email must contain exactly one @ symbol'] if parts.length > 2
+
+          local, domain = parts
+
+          errors.concat(validate_local(local))
+          errors.concat(validate_domain(domain))
+
+          errors
+        end
+
+        # Check if an email address has valid syntax.
+        #
+        # @param email [String] the email address to check
+        # @return [Boolean]
+        def valid?(email)
+          validate(email).empty?
+        end
+
+        private
+
+        # Validate the local part of an email address.
+        #
+        # @param local [String] the local part (before @)
+        # @return [Array<String>] list of error messages
+        def validate_local(local)
+          errors = []
+
+          if local.empty?
+            errors << 'local part must not be empty'
+            return errors
+          end
+
+          if local.length > MAX_LOCAL_LENGTH
+            errors << "local part exceeds maximum length of #{MAX_LOCAL_LENGTH} characters"
+          end
+
+          errors << 'local part must not start with a dot' if local.start_with?('.')
+
+          errors << 'local part must not end with a dot' if local.end_with?('.')
+
+          errors << 'local part must not contain consecutive dots' if local.include?('..')
+
+          errors << 'local part contains invalid characters' unless local.match?(LOCAL_CHAR_PATTERN)
+
+          errors
+        end
+
+        # Validate the domain part of an email address.
+        #
+        # @param domain [String] the domain part (after @)
+        # @return [Array<String>] list of error messages
+        def validate_domain(domain)
+          errors = []
+
+          if domain.empty?
+            errors << 'domain must not be empty'
+            return errors
+          end
+
+          if domain.length > MAX_DOMAIN_LENGTH
+            errors << "domain exceeds maximum length of #{MAX_DOMAIN_LENGTH} characters"
+          end
+
+          errors << 'domain must not start with a hyphen' if domain.start_with?('-')
+
+          errors << 'domain must not end with a hyphen' if domain.end_with?('-')
+
+          labels = domain.split('.')
+
+          errors << 'domain must contain at least two labels' if labels.length < 2
+
+          labels.each do |label|
+            if label.empty?
+              errors << 'domain must not contain empty labels'
+              next
+            end
+
+            if label.length > MAX_LABEL_LENGTH
+              errors << "domain label '#{label}' exceeds maximum length of #{MAX_LABEL_LENGTH} characters"
+            end
+
+            errors << "domain label '#{label}' contains invalid characters" unless label.match?(LABEL_PATTERN)
+          end
+
+          tld = labels.last
+          errors << 'top-level domain must not be all numeric' if tld&.match?(/\A\d+\z/)
+
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/email_validator/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module EmailValidator
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/email_validator.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require_relative 'email_validator/version'
+require_relative 'email_validator/result'
+require_relative 'email_validator/syntax'
+require_relative 'email_validator/mx_check'
+require_relative 'email_validator/disposable'
+
+module Philiprehberger
+  module EmailValidator
+    class Error < StandardError; end
+
+    # Role-based local parts that typically represent groups, not individuals.
+    ROLE_BASED_LOCALS = Set.new(%w[
+                                  abuse admin billing contact dev devnull ftp help hostmaster
+                                  info mail mailer-daemon marketing noc noreply no-reply
+                                  office postmaster press registrar remove root sales security
+                                  spam subscribe support sysadmin tech undisclosed-recipients
+                                  unsubscribe usenet uucp webmaster www
+                                ]).freeze
+
+    class << self
+      # Quick syntax check for an email address.
+      #
+      # @param email [String] the email address to validate
+      # @return [Boolean] true if syntax is valid
+      def valid?(email)
+        Syntax.valid?(email)
+      end
+
+      # Full validation returning a Result object.
+      #
+      # @param email [String] the email address to validate
+      # @param check_mx [Boolean] whether to verify MX records (default: false)
+      # @param allow_disposable [Boolean] whether to allow disposable domains (default: true)
+      # @return [Result] validation result with errors and warnings
+      def validate(email, check_mx: false, allow_disposable: true)
+        errors = []
+        warnings = []
+
+        syntax_errors = Syntax.validate(email)
+        errors.concat(syntax_errors)
+
+        if syntax_errors.empty?
+          errors << 'disposable email domains are not allowed' if !allow_disposable && Disposable.disposable?(email)
+
+          warnings << 'address appears to be role-based' if role_based?(email)
+
+          if check_mx
+            domain = extract_domain(email)
+            errors << "domain '#{domain}' has no MX or A records" unless MxCheck.valid?(domain)
+          end
+        end
+
+        Result.new(errors: errors, warnings: warnings)
+      end
+
+      # Check if a domain has valid MX records.
+      #
+      # @param domain [String] the domain to check
+      # @return [Boolean] true if MX or A records exist
+      def mx_valid?(domain)
+        MxCheck.valid?(domain)
+      end
+
+      # Check if an email address uses a known disposable domain.
+      #
+      # @param email [String] the email address to check
+      # @return [Boolean] true if the domain is disposable
+      def disposable?(email)
+        Disposable.disposable?(email)
+      end
+
+      # Detect role-based email addresses (info@, admin@, support@, etc.).
+      #
+      # @param email [String] the email address to check
+      # @return [Boolean] true if the local part is role-based
+      def role_based?(email)
+        return false unless email.is_a?(String)
+
+        local = extract_local(email)
+        return false if local.nil?
+
+        ROLE_BASED_LOCALS.include?(local.downcase)
+      end
+
+      private
+
+      # Extract the domain part from an email address.
+      #
+      # @param email [String]
+      # @return [String, nil]
+      def extract_domain(email)
+        parts = email.strip.split('@', 2)
+        return nil if parts.length != 2
+
+        parts[1]
+      end
+
+      # Extract the local part from an email address.
+      #
+      # @param email [String]
+      # @return [String, nil]
+      def extract_local(email)
+        parts = email.strip.split('@', 2)
+        return nil if parts.length != 2
+
+        parts[0]
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-email_validator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-27 00:00:00.000000000 Z
+dependencies: []
+description: Validates email addresses with RFC 5322 syntax checking, MX record verification,
+  disposable domain detection, and role-based address identification.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/email_validator.rb
+- lib/philiprehberger/email_validator/disposable.rb
+- lib/philiprehberger/email_validator/mx_check.rb
+- lib/philiprehberger/email_validator/result.rb
+- lib/philiprehberger/email_validator/syntax.rb
+- lib/philiprehberger/email_validator/version.rb
+homepage: https://github.com/philiprehberger/rb-email-validator
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-email-validator
+  source_code_uri: https://github.com/philiprehberger/rb-email-validator
+  changelog_uri: https://github.com/philiprehberger/rb-email-validator/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-email-validator/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: RFC-compliant email validation with MX record verification
+test_files: []