domain_sanity 0.1.0

data/lib/domain_sanity.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "domain_sanity/version"
+require_relative "domain_sanity/policy"
+require_relative "domain_sanity/reason"
+require_relative "domain_sanity/idn"
+require_relative "domain_sanity/ip"
+require_relative "domain_sanity/name"
+require_relative "domain_sanity/subject"
+require_relative "domain_sanity/data"
+
+# DomainSanity validates and inspects domain names the strict way a
+# certificate authority must: RFC 1035 label rules, IDN/punycode handling,
+# Public Suffix List and TLD checks, CA/Browser Forum aware wildcard rules,
+# and IP / reserved-range / reverse-zone detection.
+#
+# Scope: this is offline, structural validation only. It does NOT resolve DNS,
+# check CAA records, verify that a name exists, or enforce certificate field
+# lengths (e.g. CN <= 64). IDN conversion is IDNA2003-style punycode via
+# SimpleIDN, not full UTS-46 (see DomainSanity::IDN). Those remain the caller's
+# responsibility.
+#
+# What "valid" means is governed by a Policy; pass `policy:` a preset symbol
+# (:ca_baseline, :dns_zone, :lenient), a Hash of overrides, or a Policy. The
+# module-level methods are the friendly front door. For several questions about
+# one subject, build a typed Subject once with .analyze and reuse it.
+module DomainSanity
+  module_function
+
+  # Structurally valid FQDN with a real public TLD under the given policy.
+  # Wildcards, IP literals, and reverse-zone names are excluded here.
+  def valid?(subject, policy: :ca_baseline)
+    Name.valid?(subject, policy: policy)
+  end
+
+  # Structured reasons subject is not a valid FQDN, as Reason objects (code,
+  # message, label). Empty array means valid.
+  def reasons(subject, policy: :ca_baseline)
+    Name.reasons(subject, policy: policy)
+  end
+
+  def wildcard?(subject)
+    Name.wildcard?(subject)
+  end
+
+  # Baseline-Requirements-valid wildcard: "*" is the whole leftmost label and
+  # the remainder is not a bare public suffix.
+  def valid_wildcard?(subject, policy: :ca_baseline)
+    Name.valid_wildcard?(subject, policy: policy)
+  end
+
+  # True when subject is itself a recognized public suffix (eTLD), e.g. "com"
+  # or "co.uk". A full name like "example.com" is not a suffix and returns
+  # false.
+  def valid_tld?(subject, policy: :ca_baseline)
+    Name.valid_tld?(subject, policy: policy)
+  end
+
+  def registrable_domain(subject, policy: :ca_baseline)
+    Name.registrable_domain(subject, policy: policy)
+  end
+
+  def public_suffix(subject, policy: :ca_baseline)
+    Name.public_suffix(subject, policy: policy)
+  end
+
+  def ip?(subject)
+    IP.ip?(subject)
+  end
+
+  # Private or otherwise reserved (non-public) IP. The BRs forbid issuing for
+  # these.
+  def reserved_ip?(subject)
+    IP.reserved?(subject)
+  end
+
+  def public_ip?(subject)
+    IP.public?(subject)
+  end
+
+  def reverse_zone?(subject)
+    IP.reverse_zone?(subject)
+  end
+
+  def to_ascii(subject)
+    IDN.to_ascii(subject)
+  end
+
+  def to_unicode(subject)
+    IDN.to_unicode(subject)
+  end
+
+  # True when any label mixes scripts in a homograph-suspicious way (Latin with
+  # Cyrillic, etc.). Opt in to enforcing this during validation with a policy of
+  # { require_single_script: true }.
+  def mixed_script?(subject)
+    IDN.mixed_script?(subject)
+  end
+
+  # A typed, lazily-memoized Subject (Hostname / Wildcard / IPSubject /
+  # ReverseZone / MalformedSubject) exposing every fact about subject. Named
+  # .analyze (not .inspect) so it does not shadow Object#inspect.
+  def analyze(subject, policy: :ca_baseline)
+    Subject.for(subject, policy: policy)
+  end
+
+  # Provenance and staleness of the reference data (reserved-IP snapshot, PSL
+  # and IDNA gem versions).
+  def data_versions
+    Data.versions
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: domain_sanity
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Suleyman Musayev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: public_suffix
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: simpleidn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: 'A small, fast Ruby gem for validating and inspecting domain names the
+  way a certificate authority has to: RFC 1035 label rules, IDN/punycode round-tripping,
+  Public Suffix List and TLD checks, CA/Browser Forum aware wildcard rules, plus IP
+  address, private/reserved range, and reverse-zone detection. Two runtime dependencies,
+  both pure Ruby.'
+email:
+- slmusayev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/domain_sanity.rb
+- lib/domain_sanity/data.rb
+- lib/domain_sanity/idn.rb
+- lib/domain_sanity/ip.rb
+- lib/domain_sanity/name.rb
+- lib/domain_sanity/policy.rb
+- lib/domain_sanity/reason.rb
+- lib/domain_sanity/subject.rb
+- lib/domain_sanity/version.rb
+homepage: https://github.com/msuliq/domain_sanity
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/msuliq/domain_sanity
+  source_code_uri: https://github.com/msuliq/domain_sanity
+  changelog_uri: https://github.com/msuliq/domain_sanity/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/msuliq/domain_sanity/issues
+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: Strict, standards-based domain name validation for certificate and PKI workflows
+test_files: []