domain_sanity 0.1.0

data/lib/domain_sanity/name.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "set"
+require "public_suffix"
+require_relative "idn"
+require_relative "ip"
+require_relative "reason"
+require_relative "policy"
+
+module DomainSanity
+  # Fully-qualified domain name validation.
+  #
+  # The checks implement widely published standards, not any one vendor's
+  # code: RFC 1035 label syntax and length limits, RFC 5890/5891 for IDN,
+  # the Public Suffix List for TLD membership, and the CA/Browser Forum
+  # Baseline Requirements for wildcard issuance. Structural length checks run
+  # on the ASCII (punycode) form, since the DNS limits are octet limits on the
+  # wire format; TLD membership runs on the Unicode form, which is what the
+  # Public Suffix List expects.
+  #
+  # Every entry point funnels a subject through {normalize} exactly once, which
+  # classifies it (hostname / wildcard / ip / reverse_zone / empty) and does
+  # all IDN conversion and Public Suffix parsing up front. Downstream checks
+  # read the precomputed form instead of re-converting.
+  #
+  # What counts as invalid is governed by a {Policy}: underscores, single-label
+  # names, trailing dots, private Public Suffix List entries, and script
+  # mixing are all policy choices rather than hardcoded rules.
+  module Name
+    MAX_DOMAIN_LENGTH = 253
+    MAX_LABEL_LENGTH = 63
+    MAX_LABELS = 127
+
+    # Hard cap on the raw input, checked before any IDN conversion or Public
+    # Suffix parsing so untrusted callers can't force unbounded work with a huge
+    # string. No real name comes close: the ASCII form maxes out at 253 octets,
+    # and even a pathological all-multibyte IDN stays well under this in its
+    # Unicode form. This is a denial-of-service guard, not the DNS length rule
+    # (that is MAX_DOMAIN_LENGTH, enforced on the converted ASCII form).
+    MAX_INPUT_BYTES = 1024
+
+    LDH_LABEL = /\A[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\z/i
+    LDH_UNDERSCORE_LABEL = /\A[a-z0-9_](?:[a-z0-9_-]*[a-z0-9_])?\z/i
+
+    NUMERIC = /\A\d+\z/
+
+    # Special-use TLDs that are not delegated in the Public Suffix List but are
+    # legitimate in some contexts. Accepted only when a policy sets
+    # allow_reserved_tld (:lenient does). Sources: RFC 6761 (example, invalid,
+    # localhost, test), RFC 6762 (local), RFC 7686 (onion), and ICANN's
+    # private-use ".internal".
+    RESERVED_TLDS = Set[
+      "example", "invalid", "localhost", "test", "local", "onion", "internal"
+    ].freeze
+
+    # The one-pass normalized view of a subject. `kind` is always set; the
+    # remaining fields are populated only for the :hostname kind (the other
+    # kinds fail fast with a single reason and need no structural analysis).
+    #   input   - the original string (or nil)
+    #   name    - input with a single trailing "root" dot removed
+    #   ascii   - punycode form of name, or nil if unconvertible
+    #   unicode - Unicode form of name (falls back to name)
+    #   labels  - ascii split on ".", preserving empty edge labels
+    #   psl     - PublicSuffix::Domain, or nil if not registrable
+    Normalized = Struct.new(
+      :input, :name, :ascii, :unicode, :labels, :kind, :psl,
+      keyword_init: true
+    )
+
+    module_function
+
+    # Classify and pre-parse a subject exactly once. Cheap for the non-hostname
+    # kinds, which return early before any IDN/PSL work. `policy` only affects
+    # whether private Public Suffix List entries count as suffixes.
+    def normalize(subject, policy = Policy.ca_baseline)
+      return Normalized.new(input: subject, kind: :nil) if subject.nil?
+      return Normalized.new(input: subject, kind: :not_a_string) unless subject.is_a?(String)
+      return Normalized.new(input: subject, kind: :oversized) if subject.bytesize > MAX_INPUT_BYTES
+      return Normalized.new(input: subject, kind: :empty) if subject.empty?
+      return Normalized.new(input: subject, kind: :whitespace) if subject.match?(/\s/)
+
+      kind = classify(subject)
+      return Normalized.new(input: subject, kind: kind) unless kind == :hostname
+
+      name = subject.chomp(".") # a single trailing dot denotes the same FQDN
+      ascii = IDN.to_ascii(name)
+      unicode = IDN.to_unicode(name) || name
+      Normalized.new(
+        input: subject,
+        name: name,
+        ascii: ascii,
+        unicode: unicode,
+        labels: ascii ? ascii.split(".", -1) : [],
+        kind: :hostname,
+        psl: parse_psl(unicode, policy)
+      )
+    end
+
+    # True when subject is a structurally valid FQDN under the given policy.
+    # Wildcards, IP literals, and reverse-zone names are never valid here.
+    def valid?(subject, policy: :ca_baseline)
+      reasons(subject, policy: policy).empty?
+    end
+
+    # Structured reasons the subject is not a valid FQDN, as Reason objects.
+    # An empty array means valid. This is the single source of truth.
+    def reasons(subject, policy: :ca_baseline)
+      pol = Policy.coerce(policy)
+      reasons_for(normalize(subject, pol), policy: pol)
+    end
+
+    # Reasons for an already-normalized subject, so callers that hold a
+    # Normalized (such as a Subject) don't re-parse.
+    def reasons_for(norm, policy: :ca_baseline)
+      pol = Policy.coerce(policy)
+      case norm.kind
+      when :nil then [reason(:nil, "is nil")]
+      when :not_a_string then [reason(:not_a_string, "is not a string")]
+      when :oversized then [reason(:input_too_long, "exceeds the maximum input length of #{MAX_INPUT_BYTES} bytes")]
+      when :empty then [reason(:empty, "is empty")]
+      when :whitespace then [reason(:whitespace, "contains whitespace")]
+      when :wildcard then [reason(:wildcard, "is a wildcard (use valid_wildcard?)")]
+      when :ip then [reason(:ip_address, "is an IP address, not a host name")]
+      when :reverse_zone then [reason(:reverse_zone, "is a reverse-DNS zone name, not a host name")]
+      else hostname_reasons(norm, pol)
+      end
+    end
+
+    # True when subject is itself a recognized public suffix (eTLD), including
+    # multi-label suffixes like "co.uk". A full registrable name such as
+    # "example.com" is NOT a public suffix and returns false. ICANN suffixes
+    # only, unless a policy including private suffixes is passed.
+    def valid_tld?(subject, policy: :ca_baseline)
+      return false unless subject.is_a?(String)
+      return false if subject.empty?
+
+      pol = Policy.coerce(policy)
+      unicode = IDN.to_unicode(subject) || subject
+      PublicSuffix.parse(unicode, default_rule: nil, ignore_private: !pol.include_private_suffixes)
+      false # parsed as a registrable domain, so it is not a bare suffix
+    rescue PublicSuffix::DomainNotAllowed
+      true # only a bare public suffix parses to "not allowed"
+    rescue PublicSuffix::Error
+      false
+    end
+
+    # True when subject is a wildcard name of the form "*.something".
+    def wildcard?(subject)
+      subject.is_a?(String) && subject.start_with?("*.")
+    end
+
+    # True when subject is a wildcard the Baseline Requirements permit:
+    # the "*" is the entire leftmost label, appears exactly once, and the
+    # remainder is a valid domain that is NOT itself a bare public suffix.
+    def valid_wildcard?(subject, policy: :ca_baseline)
+      return false unless wildcard?(subject)
+      return false if subject.count("*") != 1
+
+      pol = Policy.coerce(policy)
+      valid_wildcard_remainder?(normalize(subject[2..], pol), policy: pol)
+    end
+
+    # Whether an already-normalized wildcard remainder is eligible to carry a
+    # "*." label: it must validate, and it must have something to the left of
+    # its public suffix. For PSL names that means an sld (registrable != tld);
+    # for policy-permitted names with no PSL entry (a reserved TLD under
+    # allow_reserved_tld) it means at least two labels. Shared so Subject and
+    # valid_wildcard? normalize the remainder only once.
+    def valid_wildcard_remainder?(norm, policy: :ca_baseline)
+      pol = Policy.coerce(policy)
+      return false unless reasons_for(norm, policy: pol).empty?
+
+      registrable = norm.psl&.domain
+      return registrable != norm.psl.tld unless registrable.nil?
+
+      norm.labels.size >= 2
+    end
+
+    # The registrable domain ("example.co.uk" from "www.example.co.uk"), or nil.
+    def registrable_domain(subject, policy: :ca_baseline)
+      normalize(subject, Policy.coerce(policy)).psl&.domain
+    end
+
+    # The public suffix ("co.uk" from "www.example.co.uk"), or nil.
+    def public_suffix(subject, policy: :ca_baseline)
+      normalize(subject, Policy.coerce(policy)).psl&.tld
+    end
+
+    # --- internals -------------------------------------------------------
+
+    def classify(subject)
+      if subject.start_with?("*.") then :wildcard
+      elsif IP.ip?(subject) then :ip
+      elsif IP.reverse_zone?(subject) then :reverse_zone
+      else :hostname
+      end
+    end
+
+    def parse_psl(unicode, policy)
+      PublicSuffix.parse(unicode, default_rule: nil, ignore_private: !policy.include_private_suffixes)
+    rescue PublicSuffix::Error
+      nil
+    end
+
+    def hostname_reasons(norm, policy)
+      errors = []
+      name = norm.name
+
+      # Dot-structure checks run on the pre-IDN name, because IDN conversion
+      # silently drops empty edge labels and would hide a leading dot.
+      errors << reason(:leading_dot, "starts with a dot") if name.start_with?(".")
+      errors << reason(:trailing_dot, "ends with a dot") if name.end_with?(".")
+      errors << reason(:empty_label, "has an empty label (consecutive or edge dots)") if name.include?("..")
+      if !policy.allow_trailing_dot && norm.input.end_with?(".")
+        errors << reason(:trailing_dot, "ends with a dot")
+      end
+
+      if norm.ascii.nil?
+        errors << reason(:not_convertible, "is not convertible to a valid ASCII form")
+        return errors.uniq
+      end
+
+      errors << reason(:too_long, "exceeds #{MAX_DOMAIN_LENGTH} characters") if norm.ascii.length > MAX_DOMAIN_LENGTH
+
+      labels = norm.labels
+      single_label = policy.allow_single_label && labels.size == 1
+      errors << reason(:too_few_labels, "must have at least two labels") if labels.size < 2 && !single_label
+      errors << reason(:too_many_labels, "exceeds #{MAX_LABELS} labels") if labels.size > MAX_LABELS
+
+      pattern = policy.allow_underscore ? LDH_UNDERSCORE_LABEL : LDH_LABEL
+      labels.each { |label| append_label_reason(errors, label, pattern) }
+
+      append_tld_reasons(errors, norm, single_label, policy)
+
+      if policy.require_single_script && IDN.mixed_script_unicode?(norm.unicode)
+        errors << reason(:mixed_script, "mixes scripts within a label (possible homograph)")
+      end
+
+      errors.uniq
+    end
+
+    # TLD-level checks only apply when there is a TLD (i.e. more than one label,
+    # or single-label names aren't permitted).
+    def append_tld_reasons(errors, norm, single_label, policy)
+      return if single_label
+
+      tld = norm.labels.last
+      errors << reason(:numeric_tld, "has an all-numeric TLD") if tld&.match?(NUMERIC)
+
+      return unless norm.psl.nil?
+      return if policy.allow_reserved_tld && reserved_tld?(tld)
+
+      errors << reason(:unknown_tld, "has a TLD that is not in the Public Suffix List")
+    end
+
+    def reserved_tld?(tld)
+      !tld.nil? && RESERVED_TLDS.include?(tld.downcase)
+    end
+
+    def append_label_reason(errors, label, pattern)
+      if label.empty?
+        errors << reason(:empty_label, "has an empty label (consecutive or edge dots)")
+      elsif label.length > MAX_LABEL_LENGTH
+        errors << reason(:label_too_long, "has a label longer than #{MAX_LABEL_LENGTH} characters: #{label.inspect}", label)
+      elsif !label.match?(pattern)
+        errors << reason(:label_invalid, "has an invalid label: #{label.inspect}", label)
+      end
+    end
+
+    def reason(code, message, label = nil)
+      Reason.new(code: code, message: message, label: label)
+    end
+  end
+end

data/lib/domain_sanity/policy.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module DomainSanity
+  # What counts as "valid" depends on who is asking. A certificate authority,
+  # a DNS zone editor, and a lenient form validator disagree about underscores,
+  # single-label names, private Public Suffix List entries, and script mixing.
+  #
+  # Policy captures those choices as data instead of letting them accrete as
+  # boolean keyword arguments on every method. Pass a preset symbol, a Hash of
+  # overrides, or a Policy instance anywhere a `policy:` argument is accepted;
+  # {coerce} turns all three into a Policy.
+  #
+  #   DomainSanity.valid?("_dmarc.example.com", policy: :dns_zone)
+  #   DomainSanity.valid?("host", policy: { allow_single_label: true })
+  #
+  # Policy only governs how a *host name* is judged; it never makes valid?
+  # accept an IP, wildcard, or reverse-zone subject (those are distinct kinds
+  # with their own predicates).
+  class Policy
+    # Each field defaults to the strict (CA-style) choice: false, except
+    # allow_trailing_dot, since a single root dot denotes the same name.
+    DEFAULTS = {
+      allow_underscore: false,         # permit "_" in labels (RFC 952/1123 forbid it)
+      allow_single_label: false,       # permit a bare host with no TLD ("intranet")
+      allow_trailing_dot: true,        # accept & normalize one trailing root dot
+      include_private_suffixes: false, # treat private PSL entries (github.io) as suffixes
+      allow_reserved_tld: false,       # accept RFC 6761/6762/7686 special-use TLDs (.test, .local, .onion, .internal)
+      require_single_script: false     # reject confusable mixed-script IDN labels
+    }.freeze
+
+    FIELDS = DEFAULTS.keys.freeze
+
+    # The names of the built-in presets.
+    PRESET_NAMES = %i[ca_baseline dns_zone lenient].freeze
+
+    attr_reader(*FIELDS)
+
+    def initialize(**opts)
+      unknown = opts.keys - FIELDS
+      raise ArgumentError, "unknown policy option(s): #{unknown.join(", ")}" unless unknown.empty?
+
+      DEFAULTS.each { |field, default| instance_variable_set(:"@#{field}", opts.fetch(field, default)) }
+      freeze
+    end
+
+    # A copy with some fields overridden.
+    def with(**overrides)
+      self.class.new(**to_h.merge(overrides))
+    end
+
+    def to_h
+      FIELDS.to_h { |field| [field, public_send(field)] }
+    end
+
+    def ==(other)
+      other.is_a?(Policy) && other.to_h == to_h
+    end
+    alias_method :eql?, :==
+
+    def hash
+      to_h.hash
+    end
+
+    class << self
+      # Strict, certificate-authority-style defaults.
+      def ca_baseline
+        new
+      end
+
+      # DNS zone editing: underscores, single-label hosts, and private suffixes
+      # are all fine here. Reserved special-use TLDs are still rejected - a real
+      # zone shouldn't contain them.
+      def dns_zone
+        new(allow_underscore: true, allow_single_label: true, include_private_suffixes: true)
+      end
+
+      # Everything permissive, including RFC 6761/6762/7686 special-use TLDs
+      # (.test, .local, .onion, .internal). Script safety stays off to avoid
+      # false positives.
+      def lenient
+        new(
+          allow_underscore: true,
+          allow_single_label: true,
+          include_private_suffixes: true,
+          allow_reserved_tld: true
+        )
+      end
+
+      def presets
+        PRESET_NAMES
+      end
+
+      def preset(name)
+        case name
+        when :ca_baseline then ca_baseline
+        when :dns_zone then dns_zone
+        when :lenient then lenient
+        else raise ArgumentError, "unknown policy preset: #{name.inspect}"
+        end
+      end
+
+      # Turn a Symbol preset, Hash of overrides, Policy, or nil into a Policy.
+      def coerce(arg)
+        case arg
+        when Policy then arg
+        when Symbol then preset(arg)
+        when Hash then ca_baseline.with(**arg)
+        when nil then ca_baseline
+        else raise ArgumentError, "cannot coerce #{arg.inspect} into a Policy"
+        end
+      end
+    end
+  end
+end

data/lib/domain_sanity/reason.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DomainSanity
+  # A single, structured reason a subject failed validation.
+  #
+  # `code` is a stable Symbol meant for programmatic branching (it does not
+  # change when the wording of a message is tweaked). `message` is the
+  # human-readable explanation. `label` is the specific offending DNS label
+  # when one applies (e.g. a label that is too long or malformed), and nil
+  # otherwise.
+  #
+  # Reason#to_s returns the message, so an array of reasons still interpolates
+  # and joins into readable text, while callers that need to react in code can
+  # switch on `code`.
+  Reason = Struct.new(:code, :message, :label, keyword_init: true) do
+    def to_s
+      message
+    end
+  end
+end

data/lib/domain_sanity/subject.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require_relative "name"
+require_relative "ip"
+require_relative "idn"
+require_relative "policy"
+
+module DomainSanity
+  # A classified view of one subject string. {Subject.for} inspects the input
+  # once and returns the concrete type that fits it - Hostname, Wildcard,
+  # IPSubject, ReverseZone, or MalformedSubject - so a method that only makes
+  # sense for one kind (registrable_domain for a host, public? for an IP) lives
+  # only on that type instead of returning nil on a god-object.
+  #
+  # Facts are computed lazily and memoized, so asking one question is cheap and
+  # asking many re-parses nothing. `valid?` means the same thing on every
+  # subject and matches DomainSanity.valid? exactly: true only for a
+  # structurally valid plain host name. Wildcards, IPs, and reverse zones are
+  # not "valid" in that sense and expose their own predicates instead.
+  class Subject
+    attr_reader :input, :policy
+
+    # Classify `input` under `policy` (a preset symbol, Hash, or Policy) and
+    # return the matching Subject subclass.
+    def self.for(input, policy: :ca_baseline)
+      pol = Policy.coerce(policy)
+      norm = Name.normalize(input, pol)
+      klass = TYPES.fetch(norm.kind, MalformedSubject)
+      klass.new(input, norm, pol)
+    end
+
+    def initialize(input, normalized, policy)
+      @input = input
+      @norm = normalized
+      @policy = policy
+    end
+
+    def kind
+      @norm.kind
+    end
+
+    # Only a structurally valid plain host name is "valid"; every other kind
+    # overrides nothing and stays false. See Hostname.
+    def valid?
+      false
+    end
+
+    def hostname?
+      false
+    end
+
+    def wildcard?
+      false
+    end
+
+    def valid_wildcard?
+      false
+    end
+
+    def ip?
+      false
+    end
+
+    def reverse_zone?
+      false
+    end
+
+    def reasons
+      @reasons ||= Name.reasons_for(@norm, policy: @policy).freeze
+    end
+
+    def punycode?
+      return @punycode if defined?(@punycode)
+
+      @punycode = IDN.punycode?(@input)
+    end
+
+    def ascii
+      return @ascii if defined?(@ascii)
+
+      @ascii = IDN.to_ascii(@input)
+    end
+
+    def unicode
+      return @unicode if defined?(@unicode)
+
+      @unicode = IDN.to_unicode(@input)
+    end
+
+    # A uniform snapshot: every subject exposes the same keys, with nil where a
+    # fact does not apply to this kind. (The typed *methods* stay kind-specific -
+    # an IPSubject still has no #registrable_domain - but the serialized shape is
+    # stable so downstream `present?`/`dig` checks work the same for any kind.)
+    # Subclasses fill the optional slots via {type_facts}.
+    def to_h
+      {
+        input: @input,
+        kind: kind,
+        valid: valid?,
+        wildcard: wildcard?,
+        valid_wildcard: valid_wildcard?,
+        ip: ip?,
+        reserved_ip: nil,
+        public_ip: nil,
+        reverse_zone: reverse_zone?,
+        punycode: punycode?,
+        ascii: ascii,
+        unicode: unicode,
+        registrable_domain: nil,
+        public_suffix: nil,
+        reasons: reasons.map(&:to_s)
+      }.merge(type_facts)
+    end
+
+    # Kind-specific overrides for the optional to_h slots. Base has none.
+    def type_facts
+      {}
+    end
+  end
+
+  # Shared to_h slots for the kinds that carry a registrable domain (Hostname
+  # and Wildcard). Each including class supplies its own registrable_domain /
+  # public_suffix; this just maps them into the uniform to_h shape.
+  module RegistrableTypeFacts
+    def type_facts
+      {registrable_domain: registrable_domain, public_suffix: public_suffix}
+    end
+  end
+
+  # A candidate fully-qualified host name.
+  class Hostname < Subject
+    include RegistrableTypeFacts
+
+    def hostname?
+      true
+    end
+
+    def valid?
+      reasons.empty?
+    end
+
+    def registrable_domain
+      @norm.psl&.domain
+    end
+
+    def public_suffix
+      @norm.psl&.tld
+    end
+  end
+
+  # A "*.something" wildcard name.
+  class Wildcard < Subject
+    include RegistrableTypeFacts
+
+    def wildcard?
+      true
+    end
+
+    # Baseline-Requirements-valid wildcard. A wildcard is never a plain
+    # host name, so #valid? stays false; this is the predicate to ask. Derived
+    # from the single normalized remainder, so nothing re-parses.
+    def valid_wildcard?
+      return @valid_wildcard if defined?(@valid_wildcard)
+
+      @valid_wildcard = @input.count("*") == 1 &&
+        Name.valid_wildcard_remainder?(remainder, policy: @policy)
+    end
+
+    # The registrable domain / public suffix of the wildcard's base name.
+    def registrable_domain
+      remainder.psl&.domain
+    end
+
+    def public_suffix
+      remainder.psl&.tld
+    end
+
+    private
+
+    def remainder
+      @remainder ||= Name.normalize(@input[2..], @policy)
+    end
+  end
+
+  # A single IPv4 or IPv6 host address.
+  class IPSubject < Subject
+    def ip?
+      true
+    end
+
+    def reserved?
+      return @reserved if defined?(@reserved)
+
+      @reserved = IP.reserved?(@input)
+    end
+    alias_method :reserved_ip?, :reserved?
+
+    def public?
+      return @public if defined?(@public)
+
+      @public = IP.public?(@input)
+    end
+    alias_method :public_ip?, :public?
+
+    def type_facts
+      {reserved_ip: reserved?, public_ip: public?}
+    end
+  end
+
+  # An in-addr.arpa / ip6.arpa reverse-DNS zone name.
+  class ReverseZone < Subject
+    def reverse_zone?
+      true
+    end
+  end
+
+  # nil, empty, or whitespace-bearing input - no meaningful structure.
+  class MalformedSubject < Subject
+  end
+
+  class Subject
+    TYPES = {
+      hostname: Hostname,
+      wildcard: Wildcard,
+      ip: IPSubject,
+      reverse_zone: ReverseZone
+    }.freeze
+  end
+end

data/lib/domain_sanity/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DomainSanity
+  VERSION = "0.1.0"
+end