domain_sanity 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 489db30b1ec1921a7fb3b1a44a99b893109ec8eed3aea29713204d21600a6678
+  data.tar.gz: 6a5d8a6e1fa962ea435d2c495290558c172071c9b94b6b00ff228bb576d3e0a7
+SHA512:
+  metadata.gz: 8cb2cd8da5067e0596f8b7447a45d6941fa60ada75188a046894e826038d9a9e850d5c4724a7ec3a6625cbe4ba4e82280b5ef31637ca6db5ff5a00d009029e6b
+  data.tar.gz: c7c9bb1b1b7b3a0b933e85e1697d7420862e5bf2488fe347c1598dc8bea46f0f4bba5e3b60d85b3e5c2b75bee34541db86ebccac370274ed8e6a8d7075b0cc06

data/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-13
+
+### Added
+
+- Initial release.
+- FQDN validation per RFC 1035 label and length rules.
+- IDN / punycode round-tripping via SimpleIDN.
+- TLD membership checks against the ICANN Public Suffix List.
+- CA/Browser Forum aware wildcard validation.
+- IP address, private/reserved range, and reverse-zone detection.
+- `reasons` returns structured `Reason` objects (stable `code`, human-readable
+  `message`, offending `label`) that still render to their message as strings.
+- A single trailing "root" dot (`example.com.`) is accepted and normalized.
+- `IP.public?` / `DomainSanity.public_ip?` parse the address only once.
+- **`Policy`** makes validation choices data instead of boolean flags: presets
+  `:ca_baseline` (default), `:dns_zone`, `:lenient`, plus per-field overrides
+  (`allow_underscore`, `allow_single_label`, `allow_trailing_dot`,
+  `include_private_suffixes`, `allow_reserved_tld`, `require_single_script`).
+  Every entry point takes a `policy:` argument (a Symbol, Hash, or `Policy`).
+- `allow_reserved_tld` accepts RFC 6761/6762/7686 special-use TLDs (`.test`,
+  `.local`, `.onion`, `.internal`, …) that are not in the Public Suffix List;
+  `:lenient` enables it, which is what distinguishes it from `:dns_zone`.
+- **Typed subjects.** `analyze` classifies the input once and returns a
+  `Hostname`, `Wildcard`, `IPSubject`, `ReverseZone`, or `MalformedSubject`.
+  Kind-specific methods live only on the type they apply to (an `IPSubject` has
+  no `registrable_domain`). Facts are computed lazily and memoized.
+- **Homograph guard.** `IDN.mixed_script?` / `DomainSanity.mixed_script?` flag
+  labels that combine scripts a Unicode registry would disallow (Latin with
+  Cyrillic, etc.), while permitting legitimate combinations (Japanese, Chinese,
+  Korean). Enforced during validation via `require_single_script`.
+- **Data provenance.** `DomainSanity.data_versions` reports the reserved-IP
+  snapshot date and PSL / IDNA gem versions; `rake data:check` fails when the
+  vendored IP snapshot is stale; `rake data:sync` documents the refresh steps.
+
+### Design decisions
+
+- `valid?` rejects IP literals and reverse-DNS zone names (`in-addr.arpa` /
+  `ip6.arpa`) as well as wildcards; `DomainSanity.valid?` and
+  `Subject#valid?` are guaranteed to agree for every input.
+- `valid_tld?` answers "is this argument itself a public suffix" (`com`,
+  `co.uk` → true; `example.com` → false), rather than validating a whole name.
+- Public-suffix treatment is policy-driven: ICANN-only by default, with private
+  entries (`github.io`) enabled via `include_private_suffixes`. Whichever is in
+  effect is applied consistently to validity, `registrable_domain`,
+  `public_suffix`, and wildcard checks.
+- The inspection entry point is `DomainSanity.analyze` (was `.inspect`, which
+  shadowed `Object#inspect`); it returns a `DomainSanity::Subject` subclass
+  (the earlier single `Analysis` / `Result` object is gone).
+- `ip?` accepts only single host addresses; prefix / CIDR notation such as
+  `10.0.0.0/8` returns false.
+- Reserved-range lists extended to match the current IANA special-purpose
+  registries (e.g. `192.31.196.0/24`, `3fff::/20`, `5f00::/16`).
+
+### Security
+
+- Input longer than `MAX_INPUT_BYTES` (1024) is rejected up front with an
+  `:input_too_long` reason, before any IDN conversion or Public Suffix parsing,
+  so an untrusted caller can't force unbounded CPU/memory with a huge string.
+- Documented that non-canonical IP encodings (`010.0.0.1`, `0x7f.0.0.1`,
+  `2130706433`) are treated as host names, not IPs; callers using
+  `reserved_ip?` for SSRF defense should canonicalize first.
+
+### Fixed
+
+- Non-String input (Integer, Symbol, Array, …) is now classified as
+  `:not_a_string` and reported invalid, instead of raising `NoMethodError` from
+  the validation path.
+- `valid_wildcard?` honors `allow_reserved_tld`: under `:lenient`, a wildcard on
+  a reserved-TLD name (`*.foo.test`) is permitted, matching `valid?("foo.test")`.
+  A bare reserved TLD (`*.test`) is still rejected.
+- `IP.parse` skips `IPAddr.new` for strings that can't be an address, avoiding a
+  raised-and-rescued exception on the hot path for every non-IP host name.
+- `Subject#to_h` exposes a uniform key set across all kinds (nil where a fact
+  does not apply), so serialized output has a stable shape; the typed methods
+  remain kind-specific.
+
+### Changed
+
+- `Policy.preset` dispatches via a case instead of rebuilding a hash of bound
+  methods on every call; `Policy.presets` now returns the preset names.
+- The wildcard remainder is normalized once (shared
+  `Name.valid_wildcard_remainder?`), and the mixed-script check reuses the
+  already-decoded Unicode form.
+
+### Scope
+
+- Offline, structural validation only: no DNS resolution, CAA, existence
+  checks, or certificate field-length enforcement. IDN conversion is IDNA2003
+  punycode (SimpleIDN), not full UTS-46 / IDNA2008.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleyman Musayev
+
+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,235 @@
+# DomainSanity
+
+[![CI](https://github.com/msuliq/domain_sanity/actions/workflows/pull_request.yml/badge.svg)](https://github.com/msuliq/domain_sanity/actions/workflows/pull_request.yml)
+[![Gem Version](https://badge.fury.io/rb/domain_sanity.svg)](https://rubygems.org/gems/domain_sanity)
+
+Strict, standards-based domain name validation and inspection for Ruby,
+written the way a certificate authority has to think about names.
+
+Most "is this a valid domain" helpers stop at a regex. A CA cannot. It has to
+know that a label may not exceed 63 octets, that the whole name may not exceed
+253, that `example.123` has an all-numeric TLD, that `*.co.uk` is a forbidden
+wildcard while `*.example.com` is fine, that `münchen.de` and its punycode
+form `xn--mnchen-3ya.de` are the same name, and that `10.0.0.1` and
+`1.2.0.192.in-addr.arpa` are not issuable host names at all.
+
+DomainSanity packages that judgment behind a small, fast API with two lean,
+pure-Ruby dependencies.
+
+## Why it exists
+
+- **Standards, not guesswork.** RFC 1035 label and length rules, RFC
+  5890/5891 for internationalized names, the ICANN Public Suffix List for TLD
+  membership, and CA/Browser Forum Baseline Requirements for wildcards.
+- **Small and fast.** Two runtime dependencies (`public_suffix`, `simpleidn`),
+  both pure Ruby. `IPAddr` comes from the standard library.
+- **Honest answers.** `reasons` tells you *why* a name failed, so you can show
+  a useful error instead of a shrug.
+- **Policy, not hardcoded rules.** "Valid" means different things to a CA, a
+  DNS zone editor, and a lenient form validator. Choose with a `policy:`.
+
+## Scope
+
+DomainSanity is **offline, structural validation only**. It does not resolve
+DNS, check CAA records, confirm a name exists, enforce certificate field
+lengths (e.g. `CN <= 64`), or perform full UTS-46 / IDNA2008 processing - IDN
+conversion is IDNA2003-style punycode via SimpleIDN (see [IDN and homographs](#idn-and-homographs)).
+Those remain the caller's responsibility. What it *does* do it does strictly
+and fast, with structured, machine-readable answers.
+
+Input longer than 1024 bytes is rejected up front (before any IDN or Public
+Suffix work) as a denial-of-service guard - no real domain name approaches that.
+
+**Using this for SSRF defense?** Non-canonical IP encodings (`010.0.0.1`,
+`0x7f.0.0.1`, `2130706433`) are *not* recognized as IPs - they're treated as
+(invalid) host names, so `reserved_ip?` / `public_ip?` return `false` for them.
+That means they can't bypass the reserved-range check *here*, but a downstream
+HTTP client or resolver might still interpret them as addresses. Canonicalize
+addresses yourself before trusting any allow/deny decision.
+
+## Installation
+
+```ruby
+gem "domain_sanity"
+```
+
+Then `bundle install`, or `gem install domain_sanity`.
+
+## Usage
+
+```ruby
+require "domain_sanity"
+
+DomainSanity.valid?("example.com")            # => true
+DomainSanity.valid?("www.example.co.uk")      # => true
+DomainSanity.valid?("münchen.de")             # => true (IDN)
+DomainSanity.valid?("example.123")            # => false (all-numeric TLD)
+DomainSanity.valid?("example.nope")           # => false (unknown TLD)
+DomainSanity.valid?("-bad.example.com")       # => false (leading hyphen)
+
+# Tell the user what went wrong. `reasons` returns structured Reason objects
+# (code, message, offending label); each renders to its message as a string.
+DomainSanity.reasons("-bad.example.123").map(&:message)
+# => ["has an invalid label: \"-bad\"", "has an all-numeric TLD",
+#     "has a TLD that is not in the Public Suffix List"]
+DomainSanity.reasons("-bad.example.123").map(&:code)
+# => [:label_invalid, :numeric_tld, :unknown_tld]
+
+# IP literals and reverse zones are not host names, so `valid?` rejects them.
+DomainSanity.valid?("192.0.2.10")                    # => false (IP, not a name)
+DomainSanity.valid?("1.2.0.192.in-addr.arpa")        # => false (reverse zone)
+
+# `valid_tld?` asks whether the argument is itself a public suffix (eTLD).
+DomainSanity.valid_tld?("com")                # => true
+DomainSanity.valid_tld?("co.uk")             # => true
+DomainSanity.valid_tld?("example.com")        # => false (a name, not a suffix)
+
+# Wildcards, per the Baseline Requirements
+DomainSanity.valid_wildcard?("*.example.com") # => true
+DomainSanity.valid_wildcard?("*.co.uk")       # => false (bare public suffix)
+DomainSanity.valid_wildcard?("ba*.example.com") # => false (embedded)
+
+# IP addresses and reverse zones
+DomainSanity.ip?("192.0.2.10")                # => true
+DomainSanity.reserved_ip?("10.0.0.1")         # => true  (RFC 1918)
+DomainSanity.public_ip?("1.1.1.1")            # => true
+DomainSanity.reverse_zone?("1.2.0.192.in-addr.arpa") # => true
+
+# Registrable domain and public suffix
+DomainSanity.registrable_domain("a.b.example.co.uk") # => "example.co.uk"
+DomainSanity.public_suffix("a.b.example.co.uk")      # => "co.uk"
+
+# IDN round-tripping
+DomainSanity.to_ascii("münchen.de")           # => "xn--mnchen-3ya.de"
+DomainSanity.to_unicode("xn--mnchen-3ya.de")  # => "münchen.de"
+```
+
+### Analyze once, ask many times
+
+When you have several questions about one name, `analyze` classifies it once and
+returns a **typed subject** - a `Hostname`, `Wildcard`, `IPSubject`,
+`ReverseZone`, or `MalformedSubject`. Facts are computed lazily and memoized, so
+one question is cheap and many re-parse nothing:
+
+```ruby
+r = DomainSanity.analyze("www.example.co.uk")   # => DomainSanity::Hostname
+r.valid?              # => true
+r.kind                # => :hostname
+r.registrable_domain  # => "example.co.uk"
+r.public_suffix       # => "co.uk"
+r.to_h                # => { input:, kind:, valid:, registrable_domain:, ... }
+
+ip = DomainSanity.analyze("10.0.0.1")           # => DomainSanity::IPSubject
+ip.reserved?          # => true
+ip.public?            # => false
+ip.registrable_domain # => NoMethodError - an IP has no registrable domain
+```
+
+Methods that only make sense for one kind live only on that type, so you can't
+ask an IP for its registrable domain. The entry point is `analyze` (not
+`inspect`, which would shadow `Object#inspect`). `Subject#valid?` means exactly
+what `DomainSanity.valid?` means: a structurally valid plain host name.
+Wildcards, IPs, and reverse zones are not "valid" in that sense and expose their
+own predicates (`valid_wildcard?`, `public?`).
+
+While the *methods* are kind-specific, `to_h` is uniform: every subject
+serializes the same key set, with `nil` where a fact does not apply to that kind,
+so downstream `dig`/`present?` checks work the same for any input.
+
+## Policies
+
+What counts as valid is a `Policy`. Pass `policy:` a preset symbol, a Hash of
+overrides, or a `Policy` instance; the default is `:ca_baseline`.
+
+```ruby
+DomainSanity.valid?("_dmarc.example.com")                          # => false
+DomainSanity.valid?("_dmarc.example.com", policy: :dns_zone)       # => true
+DomainSanity.valid?("_dmarc.example.com", policy: { allow_underscore: true })
+DomainSanity.valid?("intranet-host",       policy: :dns_zone)      # => true (single label)
+DomainSanity.public_suffix("foo.github.io", policy: :dns_zone)     # => "github.io"
+```
+
+| Field | `:ca_baseline` | Meaning |
+| --- | --- | --- |
+| `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 special-use TLDs (`.test`, `.local`, `.onion`, `.internal`) |
+| `require_single_script` | `false` | reject confusable mixed-script IDN labels |
+
+Presets: `:ca_baseline` (strict, the default), `:dns_zone` (underscores,
+single-label hosts, and private suffixes allowed), `:lenient` (all of that plus
+RFC 6761/6762/7686 special-use TLDs).
+
+`allow_reserved_tld` only affects validity - a reserved TLD is not in the Public
+Suffix List, so `registrable_domain` / `public_suffix` stay `nil` for names like
+`foo.test`.
+
+## IDN and homographs
+
+IDN conversion (`to_ascii` / `to_unicode`) uses SimpleIDN, which is IDNA2003
+punycode - **not** a full UTS-46 / IDNA2008 processor. Mapping of a few code
+points (final sigma, ß, ZWJ/ZWNJ) differs from the current standard; normalize
+upstream with a UTS-46 library if you need that exactness.
+
+`mixed_script?` is a lightweight homograph guard that flags labels combining
+scripts a Unicode registry would not allow (Latin with Cyrillic, etc.), while
+permitting legitimate combinations like Japanese (`例え.jp`):
+
+```ruby
+DomainSanity.mixed_script?("аpple.com")   # => true  (Cyrillic "а" + Latin)
+DomainSanity.mixed_script?("münchen.de")  # => false
+DomainSanity.valid?("аpple.com", policy: { require_single_script: true }) # => false
+```
+
+## Notes
+
+- **A single trailing dot is accepted** by default (`allow_trailing_dot`).
+  `example.com.` denotes the same name as `example.com`; a second trailing dot
+  (`example.com..`) is an empty label and is rejected.
+- **`valid?` is consistent everywhere.** `DomainSanity.valid?(x)` and
+  `analyze(x).valid?` always agree: both mean "a structurally valid plain host
+  name," so wildcards, IPs, and reverse zones return `false`.
+- **Data provenance.** `DomainSanity.data_versions` reports the reserved-IP
+  snapshot date and the PSL / IDNA gem versions; `rake data:check` fails when
+  the vendored IP snapshot goes stale.
+
+## What it checks
+
+| Rule | Source |
+| --- | --- |
+| Label 1-63 octets, name <= 253 octets, <= 127 labels | RFC 1035 |
+| Letter-digit-hyphen labels, no leading/trailing hyphen | RFC 952 / 1123 |
+| TLD not all-numeric | RFC 3696 |
+| TLD present in the ICANN Public Suffix List | Public Suffix List |
+| IDN normalized before suffix checks | RFC 5890 / 5891 |
+| Wildcard only as the whole leftmost label, never a bare suffix | CA/B Forum BR 3.2.2.6 |
+| Private / reserved IP detection | RFC 1918 / 4193 / 6890 |
+| Reverse-zone detection | RFC 1035 / 3596 |
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec          # run the test suite
+bundle exec standardrb         # lint (Standard Ruby)
+bundle exec rake data:check    # verify the vendored reserved-IP snapshot is current
+```
+
+The reserved-IP ranges are vendored by hand; `rake data:sync` prints the refresh
+steps, and `rake data:check` (also run in CI) fails when the snapshot goes stale.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+Please make sure `bundle exec rake spec` and `bundle exec standardrb` both pass.
+
+## License
+
+Available as open source under the [MIT License](LICENSE).

data/lib/domain_sanity/data.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "date"
+require "public_suffix"
+require "simpleidn"
+
+module DomainSanity
+  # A domain validator is only as correct as the reference data behind it, and
+  # that data drifts: IANA revises the special-purpose IP registries and the
+  # ICANN Public Suffix List changes constantly. Rather than let correctness rot
+  # silently, DomainSanity records where its data came from and how old it is,
+  # so callers can log it and CI can fail when it goes stale.
+  #
+  # The reserved-IP ranges in {IP} are vendored by hand; RESERVED_IP_SNAPSHOT is
+  # the date they were last reconciled with the IANA registries. The Public
+  # Suffix List and IDNA tables ship inside their respective gems, so their
+  # "version" is the gem version. Refresh the IP snapshot with `rake data:sync`
+  # (see the Rakefile) and bump the date below.
+  module Data
+    # Last time RESERVED_IPV4 / RESERVED_IPV6 were reconciled with
+    # https://www.iana.org/assignments/iana-ipv4-special-registry and its IPv6
+    # counterpart.
+    RESERVED_IP_SNAPSHOT = Date.new(2026, 7, 1)
+
+    # How old the IP snapshot may get before {stale?} reports true (~18 months).
+    MAX_SNAPSHOT_AGE_DAYS = 548
+
+    module_function
+
+    # A snapshot of every data source's provenance, safe to log or serialize.
+    def versions
+      {
+        reserved_ip_snapshot: RESERVED_IP_SNAPSHOT.iso8601,
+        reserved_ip_age_days: age_days,
+        public_suffix_gem: gem_version("PublicSuffix"),
+        simpleidn_gem: gem_version("SimpleIDN")
+      }
+    end
+
+    # True when the vendored IP snapshot is older than MAX_SNAPSHOT_AGE_DAYS.
+    def stale?(today = Date.today)
+      age_days(today) > MAX_SNAPSHOT_AGE_DAYS
+    end
+
+    def age_days(today = Date.today)
+      (today - RESERVED_IP_SNAPSHOT).to_i
+    end
+
+    def gem_version(mod_name)
+      mod = Object.const_get(mod_name)
+      mod.const_defined?(:VERSION) ? mod.const_get(:VERSION) : nil
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/domain_sanity/idn.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "set"
+require "simpleidn"
+
+module DomainSanity
+  # Internationalized Domain Name helpers.
+  #
+  # Conversion between the ASCII (A-label / punycode) and Unicode (U-label)
+  # forms is delegated to SimpleIDN, which implements IDNA2003-style punycode.
+  # It is NOT a full UTS-46 / IDNA2008 processor: mapping of a handful of code
+  # points (final sigma, ß, ZWJ/ZWNJ, deviation characters) differs from the
+  # current standard. If you need IDNA2008 exactness, normalize upstream with a
+  # UTS-46 library before handing names to DomainSanity. Length and label
+  # validation here operate on the ASCII form regardless, so the wire-format
+  # limits stay correct either way.
+  #
+  # Separately, {mixed_script?} provides a lightweight homograph guard: it flags
+  # labels that combine scripts in ways a Unicode registry would not allow
+  # (e.g. Latin mixed with Cyrillic). This is opt-in via Policy
+  # (require_single_script) because legitimate names occasionally trip it.
+  #
+  # None of these helpers raise: unconvertible input comes back as nil so
+  # callers can branch cleanly. Only SimpleIDN::ConversionError (a malformed
+  # A-label) is swallowed.
+  module IDN
+    # Script groups that legitimately co-occur within one label, per the spirit
+    # of UTS-39 "Highly Restrictive": a run may mix Latin with one East Asian
+    # script family, but not, say, Latin with Cyrillic.
+    ALLOWED_MULTI_SCRIPT = [
+      Set[:latin, :han, :hiragana, :katakana], # Japanese
+      Set[:latin, :han, :bopomofo],            # Chinese
+      Set[:latin, :han, :hangul]               # Korean
+    ].freeze
+
+    # Scripts we can name. Anything letter-like outside this list collapses to
+    # :other, which still participates in the "more than one script" test.
+    SCRIPT_PATTERNS = {
+      latin: /\p{Latin}/,
+      greek: /\p{Greek}/,
+      cyrillic: /\p{Cyrillic}/,
+      armenian: /\p{Armenian}/,
+      hebrew: /\p{Hebrew}/,
+      arabic: /\p{Arabic}/,
+      han: /\p{Han}/,
+      hiragana: /\p{Hiragana}/,
+      katakana: /\p{Katakana}/,
+      hangul: /\p{Hangul}/,
+      bopomofo: /\p{Bopomofo}/,
+      thai: /\p{Thai}/,
+      devanagari: /\p{Devanagari}/
+    }.freeze
+
+    module_function
+
+    # Convert a name to its ASCII/punycode form. Returns nil for non-strings,
+    # empty input, or input that cannot be encoded.
+    def to_ascii(name)
+      return nil unless name.is_a?(String)
+      return nil if name.empty?
+
+      SimpleIDN.to_ascii(name)
+    rescue SimpleIDN::ConversionError
+      nil
+    end
+
+    # Convert a name to its Unicode form. Returns nil for non-strings, empty
+    # input, or input that cannot be decoded.
+    def to_unicode(name)
+      return nil unless name.is_a?(String)
+      return nil if name.empty?
+
+      SimpleIDN.to_unicode(name)
+    rescue SimpleIDN::ConversionError
+      nil
+    end
+
+    # True when the name (or any of its labels) uses the xn-- ACE prefix.
+    def punycode?(name)
+      return false unless name.is_a?(String)
+
+      name.downcase.split(".").any? { |label| label.start_with?("xn--") }
+    end
+
+    # The set of scripts among the letters of a string (Common/Inherited and
+    # non-letters are ignored). Unknown letters collapse to :other.
+    def scripts(string)
+      return Set.new unless string.is_a?(String)
+
+      string.each_char.with_object(Set.new) do |char, found|
+        next unless char.match?(/\p{L}/)
+
+        name, = SCRIPT_PATTERNS.find { |_, pattern| char.match?(pattern) }
+        found << (name || :other)
+      end
+    end
+
+    # True when any label in the name mixes scripts in a way that reads as a
+    # homograph risk. Operates on the Unicode form; an unconvertible name is not
+    # flagged (there is nothing to compare). Mixing is judged per label, since
+    # cross-label mixing (e.g. an xn-- label beside an ASCII one) is normal.
+    def mixed_script?(name)
+      mixed_script_unicode?(to_unicode(name) || name)
+    end
+
+    # As {mixed_script?}, but for a name already decoded to its Unicode form.
+    # Callers that hold the U-label form (Name.normalize does) skip re-decoding.
+    def mixed_script_unicode?(unicode)
+      return false unless unicode.is_a?(String)
+
+      unicode.split(".").any? { |label| label_mixed_script?(label) }
+    end
+
+    def label_mixed_script?(label)
+      found = scripts(label)
+      return false if found.size <= 1
+
+      ALLOWED_MULTI_SCRIPT.none? { |allowed| found.subset?(allowed) }
+    end
+  end
+end

data/lib/domain_sanity/ip.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module DomainSanity
+  # IP address helpers.
+  #
+  # A certificate authority has to tell three things apart: a public IP that
+  # may be certifiable, a private or otherwise reserved IP that the CA/Browser
+  # Forum Baseline Requirements forbid issuing for, and a reverse-DNS zone name
+  # (in-addr.arpa / ip6.arpa) that is not an issuable host name at all. These
+  # helpers answer all three from the public IANA special-purpose registries.
+  #
+  # Only single host addresses count as IPs here: prefix / CIDR notation such
+  # as "10.0.0.0/8" is deliberately rejected, since a network block is not a
+  # host name or a certificate subject.
+  module IP
+    # IPv4 special-purpose ranges. These are not globally routable public
+    # addresses and must not appear in a public certificate.
+    #
+    # Source: IANA IPv4 Special-Purpose Address Registry
+    # (https://www.iana.org/assignments/iana-ipv4-special-registry). This list
+    # is maintained by hand and should be re-synced with the registry when
+    # IANA adds or removes a block.
+    RESERVED_IPV4 = [
+      "0.0.0.0/8",         # "This host on this network" (RFC 1122)
+      "10.0.0.0/8",        # Private-use (RFC 1918)
+      "100.64.0.0/10",     # Shared address space / CGN (RFC 6598)
+      "127.0.0.0/8",       # Loopback (RFC 1122)
+      "169.254.0.0/16",    # Link-local (RFC 3927)
+      "172.16.0.0/12",     # Private-use (RFC 1918)
+      "192.0.0.0/24",      # IETF protocol assignments (RFC 6890)
+      "192.0.2.0/24",      # Documentation TEST-NET-1 (RFC 5737)
+      "192.31.196.0/24",   # AS112-v4 (RFC 7535)
+      "192.52.193.0/24",   # AMT (RFC 7450)
+      "192.88.99.0/24",    # 6to4 relay anycast (RFC 3068, deprecated)
+      "192.168.0.0/16",    # Private-use (RFC 1918)
+      "192.175.48.0/24",   # Direct Delegation AS112 Service (RFC 7534)
+      "198.18.0.0/15",     # Benchmarking (RFC 2544)
+      "198.51.100.0/24",   # Documentation TEST-NET-2 (RFC 5737)
+      "203.0.113.0/24",    # Documentation TEST-NET-3 (RFC 5737)
+      "224.0.0.0/4",       # Multicast (RFC 5771)
+      "240.0.0.0/4",       # Reserved for future use (RFC 1112)
+      "255.255.255.255/32" # Limited broadcast (RFC 8190)
+    ].freeze
+
+    # IPv6 special-purpose ranges.
+    #
+    # Source: IANA IPv6 Special-Purpose Address Registry
+    # (https://www.iana.org/assignments/iana-ipv6-special-registry). Re-sync
+    # with the registry when IANA adds or removes a block. Note that 2001::/23
+    # is a superset covering several individually registered protocol blocks
+    # (Teredo, benchmarking, AMT, ORCHIDv2, and friends).
+    RESERVED_IPV6 = [
+      "::/128",            # Unspecified address (RFC 4291)
+      "::1/128",           # Loopback (RFC 4291)
+      "::ffff:0:0/96",     # IPv4-mapped (RFC 4291)
+      "64:ff9b::/96",      # IPv4/IPv6 translation (RFC 6052)
+      "64:ff9b:1::/48",    # Local-use IPv4/IPv6 translation (RFC 8215)
+      "100::/64",          # Discard-only (RFC 6666)
+      "2001::/23",         # IETF protocol assignments (RFC 2928)
+      "2001:db8::/32",     # Documentation (RFC 3849)
+      "2002::/16",         # 6to4 (RFC 3056, deprecated)
+      "2620:4f:8000::/48", # Direct Delegation AS112 Service (RFC 7534)
+      "3fff::/20",         # Documentation (RFC 9637)
+      "5f00::/16",         # Segment Routing (SRv6) SIDs (RFC 9602)
+      "fc00::/7",          # Unique local addresses (RFC 4193)
+      "fe80::/10",         # Link-local (RFC 4291)
+      "ff00::/8"           # Multicast (RFC 4291)
+    ].freeze
+
+    # Parse the CIDR strings once so membership checks don't reparse them on
+    # every call.
+    RESERVED_IPV4_NETS = RESERVED_IPV4.map { |cidr| IPAddr.new(cidr) }.freeze
+    RESERVED_IPV6_NETS = RESERVED_IPV6.map { |cidr| IPAddr.new(cidr) }.freeze
+
+    # Characters that can appear in an IPv4 or IPv6 literal. Anything else means
+    # the string can't be an address, so we skip IPAddr.new (which signals a
+    # non-address by raising) - most host names contain a letter outside a-f and
+    # never reach that hot-path exception.
+    IP_CHARS = /\A[0-9a-f:.]+\z/i
+
+    module_function
+
+    # True when subject parses as a single IPv4 or IPv6 host address. Prefix /
+    # CIDR notation and non-strings return false.
+    def ip?(subject)
+      !parse(subject).nil?
+    end
+
+    # True when subject is a private or otherwise reserved (non-public) IP.
+    # Non-IP input returns false.
+    def reserved?(subject)
+      addr = parse(subject)
+      return false if addr.nil?
+
+      reserved_address?(addr)
+    end
+
+    # True when subject is a routable, non-reserved public IP. Non-IP input
+    # returns false. Parses once, unlike ip? && !reserved?.
+    def public?(subject)
+      addr = parse(subject)
+      return false if addr.nil?
+
+      !reserved_address?(addr)
+    end
+
+    # True when subject is a reverse-DNS zone name rather than a host name.
+    def reverse_zone?(subject)
+      return false unless subject.is_a?(String)
+
+      normalized = subject.downcase.chomp(".")
+      normalized == "in-addr.arpa" || normalized == "ip6.arpa" ||
+        normalized.end_with?(".in-addr.arpa") || normalized.end_with?(".ip6.arpa")
+    end
+
+    # Parse to an IPAddr for a single host address, or nil when the input is
+    # not one (including CIDR / prefix notation and non-strings).
+    def parse(subject)
+      return nil unless subject.is_a?(String)
+      return nil if subject.include?("/")
+      return nil unless subject.match?(IP_CHARS)
+
+      IPAddr.new(subject)
+    rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+      nil
+    end
+
+    # Whether an already-parsed IPAddr falls in any reserved range.
+    def reserved_address?(addr)
+      nets = addr.ipv4? ? RESERVED_IPV4_NETS : RESERVED_IPV6_NETS
+      nets.any? { |net| net.include?(addr) }
+    end
+  end
+end