mta_sts 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0de9b2cdb6adccb9fb59489860cebd39ea5ccd9b31bafad218d05334bbbd79c5
+  data.tar.gz: 4d4390e9071edf2f2ca6a1decbd32a8a862f24572d042464241cc11abb226594
+SHA512:
+  metadata.gz: 836678183d43c161fdff348dc1b6c466a485f071bfc2e6606b805631c89ddd6848dbe8f1e511219f6861a7e40df83c3197c1cacf70cca0f89062f9e4aa4cd12a
+  data.tar.gz: aeeadc31d4ccf52cbd5b54267050ea1fcb01b891e49a9295f7dbd19beff6ea64f064e6299ae3d11208c68c2ea30552b0e6be1eec05bb1b639fe7e9d49b938c6d

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- MTA-STS lookup (RFC 8461): discover, fetch, parse, MX match
+- `known:` refresh (§5.1) — required keyword; no in-library cache
+- Dual-axis `status` / `policy`; `"none"` is `no_record?`
+- TLSRPT discovery (RFC 8460) — `rua` only; no report submission
+- dnsruby resolver (SERVFAIL ≠ absence); DNSSEC and answer cache off
+- CLI with exit 0 / 1 / 2 for answered / refused / unknown

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PostRider
+
+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,274 @@
+# mta_sts
+
+🔒 SMTP MTA Strict Transport Security for Ruby
+
+Answers one question before a message goes out: **must this connection be encrypted, and to which servers?**
+
+Resolve a recipient domain's MTA-STS policy (RFC 8461) and find out which of its mail servers may be used and whether TLS is optional. Also discovers where the domain wants TLS failure reports sent (RFC 8460 TLSRPT) — discovery only; generating and submitting reports is yours.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "mta_sts"
+```
+
+And run:
+
+```sh
+bundle install
+```
+
+Look up your first policy with:
+
+```ruby
+require "mta_sts"
+
+result = MtaSts.lookup("gmail.com", known: nil)
+result.enforce? # => true
+```
+
+## How It Works
+
+### Looking Up a Policy
+
+```ruby
+result = MtaSts.lookup(domain, known:, resolver:, fetcher:, now:)
+# => #<MtaSts::Result status:, comment:, policy:>
+```
+
+- **domain** - the recipient domain, the part after the `@`
+- **known** - the policy this library returned last time, or `nil`. There's no cache here, so this is how a policy survives between calls. Required on purpose: `known: nil` should be a decision, not an omission
+- **resolver** - defaults to `MtaSts::Resolver.new`
+- **fetcher** - defaults to `MtaSts::Fetcher.new`
+- **now** - a `Time`, for expiry; defaults to `Time.now`
+
+```ruby
+result = MtaSts.lookup("gmail.com", known: store["gmail.com"])
+store["gmail.com"] = result.policy if result.policy
+
+if result.enforce? && !result.allows?(mx_host)
+  # the policy names which servers are legitimate, and this is not one of them
+end
+```
+
+Hand back what you kept, keep what comes back - both halves matter.
+
+### Results
+
+```ruby
+result.status              # => "found"
+result.policy.mode         # => :enforce
+result.policy.mx           # => ["gmail-smtp-in.l.google.com", "*.gmail-smtp-in.l.google.com"]
+result.policy.max_age      # => 86400
+result.policy.id           # => "20190429T010101"
+result.policy.domain       # => "gmail.com"
+result.policy.expires_at   # => 2026-07-29 14:03:11 UTC
+
+result.enforce?                                    # => true
+result.allows?("alt1.gmail-smtp-in.l.google.com")  # => true
+result.allows?("mx.attacker.example")              # => false
+```
+
+Two questions get asked at connect time: must TLS be verified and non-optional (`enforce?`), and is this hostname one the domain vouches for (`allows?`).
+
+### Status and Policy Are Separate Axes
+
+`status` describes what this lookup learned. `policy` describes what you must honor. Nothing raises - a result always comes back with a `comment`:
+
+```ruby
+result.status   # => "temperror"
+result.comment  # => "DNS didn't answer for _mta-sts.example.com"
+```
+
+Four statuses, each with a predicate:
+
+- `found` / `found?` - a policy was fetched, or renewed against an unchanged `id`
+- `none` / `no_record?` - no `_mta-sts` record seen
+- `temperror` / `temperror?` - DNS or the policy host didn't answer
+- `permerror` / `permerror?` - the record or policy file is broken
+
+`policy` is present whenever there's one to honor: fresh, renewed, or the `known` one you passed in that hasn't expired.
+
+
+| what happened                             | status      | policy  | `enforce?` |
+| ----------------------------------------- | ----------- | ------- | ---------- |
+| fresh fetch, `mode: enforce`              | `found`     | present | true       |
+| DNS timeout, held an enforcing policy     | `temperror` | held    | true       |
+| TXT record gone, held an enforcing policy | `none`      | held    | **true**   |
+| never had one, no TXT record              | `none`      | nil     | false      |
+
+
+The third row looks wrong and isn't. §5.1 keeps a policy in force for its `max_age` regardless of what DNS says now - deleting the TXT record does not withdraw enforcement, only serving `mode: none` does.
+
+Use `enforce?` and `allows?` for the connection decision, not `status`:
+
+```ruby
+if result.enforce? && !result.allows?(mx)
+  defer_or_fail
+elsif result.temperror? && !result.policy
+  defer # we don't know; don't downgrade
+end
+```
+
+`temperror` is not `none`. A resolver timeout means "we could not ask"; reading it as "no policy published" hands an attacker a downgrade for the cost of dropping a UDP packet.
+
+### Holding On to a Policy
+
+There's no cache in this library. `lookup` takes the policy you kept last time and hands one back.
+
+```ruby
+result = MtaSts.lookup("example.com", known: store["example.com"])
+store["example.com"] = result.policy if result.policy
+```
+
+Skip that round trip and §5.1 doesn't apply. Three rules govern what comes back:
+
+- A matching `id` renews the expiry without refetching
+- A temporary failure keeps a policy that hasn't expired
+- A fetched `mode: none` replaces it immediately
+
+A policy also carries the domain it was fetched for. Handing back another domain's policy under the wrong key is ignored rather than enforced. Store that too when you persist:
+
+```ruby
+row = { body: policy.to_s, id: policy.id, domain: policy.domain, fetched_at: policy.fetched_at }
+MtaSts::Policy.parse(row[:body], id: row[:id], domain: row[:domain], fetched_at: row[:fetched_at])
+```
+
+### TLSRPT Record Discovery
+
+Where a domain wants TLS failure reports sent (RFC 8460). One TXT lookup at `_smtp._tls.<domain>` — not report generation or submission.
+
+```ruby
+result = MtaSts.reporting("gmail.com")
+# => #<MtaSts::Report::Result status:, comment:, report:>
+
+result.status   # => "found"
+result.rua      # => ["mailto:tlsrpt@smtp.gmail.com"]
+result.report.mailto
+result.report.https
+result.report.ignored  # destinations that were named but are neither mailto: nor https:
+```
+
+Same status vocabulary as policy lookup (`found` / `none` / `temperror` / `permerror`), with `no_record?` for `"none"`. Unknown TXT fields on the name are ignored; only `mailto:` and `https:` destinations are kept.
+
+### Custom Resolver & Fetcher
+
+```ruby
+MtaSts.lookup("example.com", known: nil,
+  resolver: MyCachingResolver.new,  # DNS, for discovery
+  fetcher:  MyPolicyFetcher.new)    # the HTTPS GET
+```
+
+- **resolver** - needs one method, `txt`, over `dnsruby` by default. Covers discovery only (`_mta-sts` and `_smtp._tls`). Raise `NotFound` for no such record, `Timeout` or `ServerFailure` for no answer. The policy host itself is resolved by the HTTP stack inside the fetcher.
+- **fetcher** - one `GET`, over stdlib `Net::HTTP` by default, certificate verification on. Body size and a total wall-clock budget are capped so a hostile host cannot hold the thread forever.
+
+### Publishing a Policy
+
+```ruby
+policy = MtaSts::Policy.new(mode: :enforce, mx: ["mx.example.com"], max_age: 604800)
+puts policy.to_s
+```
+
+```
+version: STSv1
+mode: enforce
+mx: mx.example.com
+max_age: 604800
+```
+
+And read one back:
+
+```ruby
+MtaSts::Policy.parse(File.read("mta-sts.txt"))
+# => #<MtaSts::Policy mode: :enforce, mx: ["mx.example.com"], max_age: 604800>
+```
+
+## Command Line
+
+```sh
+mta-sts gmail.com alt1.gmail-smtp-in.l.google.com
+```
+
+```
+domain:  gmail.com
+status:  found
+comment: fetched policy id 20190429T010101 from mta-sts.gmail.com
+mode:    enforce
+id:      20190429T010101
+max_age: 86400
+expires: 2026-07-29 15:51:41 UTC
+mx:
+  smtp.google.com
+  gmail-smtp-in.l.google.com
+  *.gmail-smtp-in.l.google.com
+rua:
+  mailto:tlsrpt@smtp.gmail.com
+
+alt1.gmail-smtp-in.l.google.com: accepted
+```
+
+Exit codes answer the MTA-STS question only. TLSRPT is printed for diagnostics and never changes the exit:
+
+- `0` - answered, a policy vouches for the MX, or the domain publishes none
+- `1` - refused, a policy applies and does not name it
+- `2` - unknown, DNS or the policy host didn't answer, or what it served was broken
+- `64` - usage
+
+## What It Is Strict About
+
+- HTTP 3xx are never followed
+- HTTP caching (RFC 7234) is never used - freshness comes from the TXT `id` and `max_age` only
+- Only `200` is a policy
+- The certificate is verified against `mta-sts.<domain>`, the policy host name
+- The `_mta-sts` discovery record must match the ABNF (`v=STSv1;` case-sensitive, a single well-formed `id`)
+- Fetch body size and total time are capped
+
+## What It Is Not That Strict
+
+- `Content-Type: text/plain` is checked but not enforced - §3.2 says SHOULD, not MUST, and real policies in the wild omit it
+- Line terminators may be bare `LF` as well as `CRLF`
+
+## What It Does Not Check
+
+- **Certificate revocation.** `Net::HTTP` doesn't check it, and this library doesn't wire up OCSP or CRL. Pass your own `fetcher` if you need it.
+- **The address the policy host resolves to.** Fetched at whatever address DNS returns. The certificate check is what protects you here.
+- **DANE.** A separate mechanism needing DNSSEC validation and the peer certificate mid-handshake, which this library never sees.
+- **TLSRPT report generation or submission.** This library finds the `rua`; building and sending aggregate reports is the application's job.
+- **Anything about the SMTP connection.** This library opens one socket, to fetch a policy over HTTPS. It never speaks SMTP.
+
+## Testing
+
+```sh
+bundle install
+rake
+```
+
+Nothing leaves the machine. Every lookup takes a `resolver:` and a `fetcher:`, and the test doubles stand a hash in for DNS and a string in for the policy host.
+
+## History
+
+View the [changelog](https://github.com/mailpiece/mta_sts/blob/main/CHANGELOG.md)
+
+## Contributing
+
+Everyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/mailpiece/mta_sts/issues)
+- Fix bugs and [submit pull requests](https://github.com/mailpiece/mta_sts/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+To get started with development:
+
+```sh
+git clone https://github.com/mailpiece/mta_sts.git
+cd mta_sts
+bundle install
+bundle exec rakecl
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/mta-sts

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "mta_sts"
+
+exit MtaSts::Cli.new(ARGV).run

data/lib/mta_sts/cli.rb

@@ -0,0 +1,113 @@
+module MtaSts
+  # Exit: 0 answered, 1 refused, 2 unknown, 64 usage
+  class Cli
+    ANSWERED = 0
+    REFUSED = 1
+    UNKNOWN = 2
+    USAGE_ERROR = 64
+
+    USAGE = <<~TEXT.freeze
+      usage: mta-sts <domain> [mx-hostname]
+
+      exit: #{ANSWERED} answered, #{REFUSED} refused, #{UNKNOWN} unknown, #{USAGE_ERROR} usage
+    TEXT
+
+    def initialize(argv, resolver: Resolver.new, fetcher: Fetcher.new, out: $stdout, err: $stderr)
+      @domain, @mx_host, @extra = argv
+      @resolver, @fetcher = resolver, fetcher
+      @out, @err = out, err
+    end
+
+    def run
+      if usable_arguments?
+        answer
+      else
+        @err.puts USAGE
+        USAGE_ERROR
+      end
+    end
+
+    private
+      def usable_arguments?
+        !(@domain.nil? || @domain.empty? || @domain.start_with?("-") || @extra)
+      end
+
+      def answer
+        result = MtaSts.lookup(@domain, known: nil, resolver: @resolver, fetcher: @fetcher)
+
+        describe(result)
+        describe_reporting
+
+        if @mx_host
+          judge(result)
+        elsif answerable?(result)
+          ANSWERED
+        else
+          UNKNOWN
+        end
+      end
+
+      def describe(result)
+        @out.puts "domain:  #{@domain}"
+        @out.puts "status:  #{result.status}"
+        @out.puts "comment: #{result.comment}" if result.comment
+
+        if policy = result.policy
+          @out.puts "mode:    #{policy.mode}"
+          @out.puts "id:      #{policy.id}"
+          @out.puts "max_age: #{policy.max_age}"
+          @out.puts "expires: #{policy.expires_at.utc}"
+          @out.puts "mx:"
+          policy.mx.each { |pattern| @out.puts "  #{pattern}" }
+        end
+
+        if result.no_record? && result.policy.nil?
+          @out.puts "note:    holds no earlier policy, so this is only what DNS says now"
+        end
+      end
+
+      def describe_reporting
+        result = MtaSts.reporting(@domain, resolver: @resolver)
+
+        if result.found?
+          describe_destinations(result.report)
+        else
+          @out.puts "rua:     #{result.comment}"
+        end
+      end
+
+      def describe_destinations(report)
+        @out.puts "rua:"
+        report.rua.each { |destination| @out.puts "  #{destination}" }
+
+        describe_ignored(report)
+      end
+
+      def describe_ignored(report)
+        if report.ignored.any?
+          @out.puts "ignored: named in rua but neither mailto: nor https:, so no report goes there"
+          report.ignored.each { |destination| @out.puts "  #{destination}" }
+        end
+      end
+
+      def answerable?(result)
+        !result.policy.nil? || result.no_record?
+      end
+
+      def judge(result)
+        @out.puts
+
+        case
+        when !answerable?(result)
+          @out.puts "#{@mx_host}: unknown — no policy could be read, so this can't be answered"
+          UNKNOWN
+        when result.allows?(@mx_host)
+          @out.puts "#{@mx_host}: accepted"
+          ANSWERED
+        else
+          @out.puts "#{@mx_host}: refused — this policy does not name it"
+          REFUSED
+        end
+      end
+  end
+end

data/lib/mta_sts/fetcher.rb

@@ -0,0 +1,123 @@
+require "net/http"
+require "openssl"
+require "zlib"
+require "mta_sts/version"
+
+module MtaSts
+  # HTTPS GET of mta-sts.<domain>/.well-known/mta-sts.txt (RFC 8461 §3.3)
+  class Fetcher
+    class Error < StandardError; end
+    class HttpError < Error; end
+    class CertificateError < Error; end
+    class Timeout < Error; end
+
+    WELL_KNOWN_PATH = "/.well-known/mta-sts.txt"
+    PORT = 443
+    OPEN_TIMEOUT = 10
+    READ_TIMEOUT = 10
+    # read_timeout renews per read; this one does not — stops a slow-drip body
+    TOTAL_TIMEOUT = 30
+    MAX_BODY_BYTES = 64 * 1024
+    USER_AGENT = "mta_sts/#{VERSION} (+https://github.com/mailpiece/mta_sts)"
+
+    # RFC 8461 §3.2 SHOULD text/plain — reported, not enforced
+    class Body < String
+      attr_reader :content_type
+
+      def initialize(body, content_type: nil)
+        super(body)
+        @content_type = content_type
+      end
+
+      def text_plain?
+        content_type.to_s.split(";").first.to_s.strip.casecmp?("text/plain")
+      end
+    end
+
+    def initialize(open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT,
+                   total_timeout: TOTAL_TIMEOUT, max_body_bytes: MAX_BODY_BYTES)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @total_timeout = total_timeout
+      @max_body_bytes = max_body_bytes
+    end
+
+    def fetch(host)
+      get(normalize(host))
+    end
+
+    private
+      def normalize(host)
+        host.to_s.downcase.chomp(".")
+      end
+
+      def get(host)
+        deadline = monotonic_now + @total_timeout
+
+        with_response(host) do |response|
+          if response.is_a?(Net::HTTPOK)
+            body_from(response, host, deadline)
+          else
+            # RFC 8461 §3.3 MUST NOT follow redirects
+            raise HttpError, "#{host} answered #{response.code}"
+          end
+        end
+      end
+
+      def with_response(host)
+        result = nil
+
+        connection(host).start do |http|
+          http.request(policy_request) { |response| result = yield response }
+        end
+
+        result
+      rescue OpenSSL::SSL::SSLError => error
+        raise CertificateError, "#{host} presented a certificate that didn't verify: #{error.message}"
+      rescue Net::OpenTimeout, Net::ReadTimeout, ::Timeout::Error
+        raise Timeout, "timed out fetching the policy from #{host}"
+      rescue Net::HTTPBadResponse, Net::ProtocolError, Zlib::Error => error
+        raise HttpError, "#{host} answered with malformed HTTP: #{error.message}"
+      rescue SystemCallError, SocketError, IOError, EOFError => error
+        raise Error, "couldn't reach #{host}: #{error.message}"
+      end
+
+      def connection(host)
+        Net::HTTP.new(host, PORT).tap do |http|
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.verify_hostname = true
+          http.min_version = OpenSSL::SSL::TLS1_2_VERSION
+          http.open_timeout = @open_timeout
+          http.read_timeout = @read_timeout
+        end
+      end
+
+      # RFC 8461 §3.3 — no HTTP caching; freshness is TXT id + max_age
+      def policy_request
+        Net::HTTP::Get.new(WELL_KNOWN_PATH, "accept" => "text/plain", "user-agent" => USER_AGENT)
+      end
+
+      def body_from(response, host, deadline)
+        body = +""
+
+        response.read_body do |chunk|
+          body << chunk
+
+          if body.bytesize > @max_body_bytes
+            raise HttpError, "#{host} sent more than #{@max_body_bytes} bytes of policy"
+          end
+
+          if monotonic_now > deadline
+            raise Timeout, "#{host} took longer than #{@total_timeout} seconds to send the policy"
+          end
+        end
+
+        Body.new(body.force_encoding(Encoding::UTF_8), content_type: response["content-type"])
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+  end
+end

data/lib/mta_sts/policy.rb

@@ -0,0 +1,184 @@
+require "simpleidn"
+
+module MtaSts
+  class Policy
+    class Invalid < StandardError; end
+
+    POLICY_VERSION = "STSv1"
+    MODES = %i[ none testing enforce ].freeze
+    MAX_AGE = (0..31_557_600) # RFC 8461 §3.2
+    WILDCARD = "*."
+    TERMINATOR = /\r?\n/ # RFC 8461 §3.2 ABNF: sts-policy-term = LF / CRLF
+    DIGITS = /\A\d+\z/
+
+    class << self
+      def parse(text, id: nil, domain: nil, fetched_at: Time.now)
+        fields = fields_in(text)
+
+        validate_version single(fields, "version")
+
+        new mode: single(fields, "mode"), mx: fields.fetch("mx", []), max_age: single(fields, "max_age"),
+          id: id, domain: domain, fetched_at: fetched_at
+      end
+
+      def normalize(name)
+        name = scrubbed(name).strip.chomp(".")
+
+        if name.start_with?(WILDCARD)
+          WILDCARD + ascii(name.delete_prefix(WILDCARD)).downcase
+        else
+          ascii(name).downcase
+        end
+      end
+
+      private
+        # RFC 8461 §3.2 — ignore unrecognized lines
+        def fields_in(text)
+          validated_document(text).split(TERMINATOR).each_with_object({}) do |line, fields|
+            name, value = line.split(":", 2)
+
+            (fields[name.strip.downcase] ||= []) << value.strip if value
+          end
+        end
+
+        def validated_document(text)
+          text = text.to_s
+
+          if text.valid_encoding?
+            text
+          else
+            raise Invalid, "policy is not valid #{text.encoding}"
+          end
+        end
+
+        def scrubbed(name)
+          name = name.to_s
+          name.valid_encoding? ? name : name.scrub
+        end
+
+        def ascii(name)
+          name.ascii_only? ? name : SimpleIDN.to_ascii(name)
+        rescue StandardError
+          name
+        end
+
+        def single(fields, name)
+          values = fields.fetch(name, [])
+
+          if values.size > 1
+            raise Invalid, "#{name} appears #{values.size} times; it may appear once"
+          else
+            values.first
+          end
+        end
+
+        def validate_version(version)
+          unless version&.casecmp?(POLICY_VERSION)
+            raise Invalid, "version must be #{POLICY_VERSION}, not #{version.inspect}"
+          end
+        end
+    end
+
+    attr_reader :mode, :mx, :max_age, :id, :domain, :fetched_at
+
+    def initialize(mode:, max_age:, mx: [], id: nil, domain: nil, fetched_at: Time.now)
+      @mode = validated_mode(mode)
+      @mx = validated_mx(mx)
+      @max_age = validated_max_age(max_age)
+      @domain = domain && self.class.normalize(domain)
+      @id, @fetched_at = id, fetched_at
+    end
+
+    def none?
+      mode == :none
+    end
+
+    def testing?
+      mode == :testing
+    end
+
+    def enforce?
+      mode == :enforce
+    end
+
+    def allows?(host)
+      if none?
+        true
+      else
+        host = self.class.normalize(host)
+
+        mx.any? { |pattern| matches?(pattern, host) }
+      end
+    end
+
+    def expires_at
+      fetched_at + max_age
+    end
+
+    def expired?(now = Time.now)
+      now >= expires_at
+    end
+
+    def to_s
+      lines = [ "version: #{POLICY_VERSION}", "mode: #{mode}" ]
+      lines.concat mx.map { |pattern| "mx: #{pattern}" }
+      lines << "max_age: #{max_age}"
+
+      lines.map { |line| "#{line}\r\n" }.join
+    end
+
+    def inspect
+      "#<#{self.class.name} mode: #{mode.inspect}, mx: #{mx.inspect}, max_age: #{max_age.inspect}>"
+    end
+
+    private
+      def validated_mode(mode)
+        if known = MODES.find { |candidate| candidate.to_s == mode.to_s.strip.downcase }
+          known
+        else
+          raise Invalid, "mode must be one of #{MODES.join(", ")}, not #{mode.inspect}"
+        end
+      end
+
+      # RFC 8461 §3.2 — at least one mx unless mode is none
+      def validated_mx(mx)
+        patterns = Array(mx).map { |pattern| validated_pattern(pattern) }.uniq
+
+        if patterns.empty? && !none?
+          raise Invalid, "mx must name at least one host unless mode is none"
+        else
+          patterns
+        end
+      end
+
+      def validated_pattern(pattern)
+        normalized = self.class.normalize(pattern)
+
+        if normalized.delete("*.").empty?
+          raise Invalid, "mx must name a host, not #{pattern.inspect}"
+        else
+          normalized
+        end
+      end
+
+      def validated_max_age(max_age)
+        # grammar is 1*DIGIT — not Integer(), which accepts 0x10 / 1_0
+        if max_age.to_s.match?(DIGITS) && MAX_AGE.cover?(seconds = max_age.to_i)
+          seconds
+        else
+          raise Invalid, "max_age must be a whole number of seconds in #{MAX_AGE}, not #{max_age.inspect}"
+        end
+      end
+
+      # RFC 8461 §4.1 — "*." covers exactly one label
+      def matches?(pattern, host)
+        if pattern.start_with?(WILDCARD)
+          label, _, parent = host.partition(".")
+
+          !label.empty? && parent == pattern.delete_prefix(WILDCARD)
+        else
+          pattern == host
+        end
+      end
+  end
+end

data/lib/mta_sts/report/result.rb

@@ -0,0 +1,35 @@
+module MtaSts
+  class Report
+    class Result
+      attr_reader :status, :report, :comment
+
+      def initialize(status:, report: nil, comment: nil)
+        @status, @report, @comment = status, report, comment
+      end
+
+      def found?
+        status == "found"
+      end
+
+      def no_record?
+        status == "none"
+      end
+
+      def temperror?
+        status == "temperror"
+      end
+
+      def permerror?
+        status == "permerror"
+      end
+
+      def rua
+        report&.rua || []
+      end
+
+      def inspect
+        "#<#{self.class.name} status: #{status.inspect}, report: #{report.inspect}, comment: #{comment.inspect}>"
+      end
+    end
+  end
+end

data/lib/mta_sts/report.rb

@@ -0,0 +1,104 @@
+require "mta_sts/policy"
+require "mta_sts/report/result"
+
+module MtaSts
+  class Report
+    class Invalid < StandardError; end
+
+    REPORT_VERSION = "TLSRPTv1"
+    # RFC 8460 §3: tlsrpt-version = %s"v=TLSRPTv1", then 1*(field-delim tlsrpt-field)
+    REPORT_RECORD = /\Av=#{REPORT_VERSION};/
+    FIELD_DELIM = ";"
+    RUA_FIELD = "rua=" # RFC 8460 §3
+    URI_DELIM = ","
+    MAILTO = /\Amailto:/i # RFC 3986 §3.1 — scheme is case-insensitive
+    HTTPS = /\Ahttps:/i
+    SCHEMES = [ MAILTO, HTTPS ].freeze
+
+    class << self
+      def parse(text, domain: nil)
+        new rua: uris_in(fields_in(text)), domain: domain
+      end
+
+      private
+        def fields_in(text)
+          fields = validated_record(text).split(FIELD_DELIM).drop(1).map(&:strip)
+
+          if fields.empty?
+            raise Invalid, "record must carry at least one field after v=#{REPORT_VERSION}"
+          else
+            fields
+          end
+        end
+
+        def validated_record(text)
+          text = validated_encoding(text)
+
+          if text.match?(REPORT_RECORD)
+            text
+          else
+            raise Invalid, "record must begin with v=#{REPORT_VERSION};, not #{text.inspect}"
+          end
+        end
+
+        def validated_encoding(text)
+          text = text.to_s
+
+          if text.valid_encoding?
+            text
+          else
+            raise Invalid, "record is not valid #{text.encoding}"
+          end
+        end
+
+        # RFC 8460 §3 — unknown fields ignored; multiple rua fields allowed
+        def uris_in(fields)
+          rua_fields = fields.select { |field| field.start_with?(RUA_FIELD) }
+
+          rua_fields.flat_map { |field| destinations_in(field.delete_prefix(RUA_FIELD)) }
+        end
+
+        def destinations_in(value)
+          value.split(URI_DELIM, -1).map(&:strip)
+        end
+    end
+
+    attr_reader :rua, :ignored, :domain
+
+    def initialize(rua:, domain: nil)
+      @rua, @ignored = validated_destinations(rua)
+      @domain = domain && Policy.normalize(domain)
+    end
+
+    def mailto
+      rua.grep(MAILTO)
+    end
+
+    def https
+      rua.grep(HTTPS)
+    end
+
+    def to_s
+      "v=#{REPORT_VERSION}; #{RUA_FIELD}#{rua.join(", ")}"
+    end
+
+    def inspect
+      "#<#{self.class.name} rua: #{rua.inspect}, ignored: #{ignored.inspect}>"
+    end
+
+    private
+      def validated_destinations(uris)
+        usable, unusable = Array(uris).partition { |uri| supported?(uri) }
+
+        if usable.empty?
+          raise Invalid, "rua must name at least one mailto: or https: destination"
+        else
+          [ usable, unusable ]
+        end
+      end
+
+      def supported?(uri)
+        SCHEMES.any? { |scheme| uri.to_s.match?(scheme) }
+      end
+  end
+end

data/lib/mta_sts/resolver.rb

@@ -0,0 +1,74 @@
+require "dnsruby"
+
+module MtaSts
+  class Resolver
+    class Error < StandardError; end
+    class NotFound < Error; end      # NXDOMAIN / NODATA
+    class Timeout < Error; end
+    class ServerFailure < Error; end # SERVFAIL, REFUSED, transport failure
+
+    QUERY_TIMEOUT = 5
+
+    def initialize(timeout: QUERY_TIMEOUT)
+      @timeout = timeout
+    end
+
+    def txt(name)
+      records(name).map { |record| record.strings.join }
+    end
+
+    private
+      def records(name)
+        answer = resolver.query(name.to_s, "TXT").answer.grep(Dnsruby::RR::IN::TXT)
+
+        if answer.any?
+          answer
+        else
+          raise NotFound, "no TXT records for #{name}"
+        end
+      rescue Dnsruby::NXDomain
+        raise NotFound, "no such name #{name}"
+      rescue Dnsruby::ResolvTimeout
+        raise Timeout, "timed out resolving TXT #{name}"
+      # Fall through to ServerFailure, never NotFound — "couldn't ask" must not become "no policy"
+      rescue Dnsruby::ResolvError, IOError, SocketError, SystemCallError => error
+        raise ServerFailure, "couldn't resolve TXT #{name}: #{reason(error)}"
+      end
+
+      def reason(error)
+        if error.is_a?(Dnsruby::ResolvError)
+          rcode(error)
+        else
+          without_backtrace(error.message)
+        end
+      end
+
+      def rcode(error)
+        name = error.class.name&.split("::")&.last
+
+        case
+        when name.nil?                         then error.message
+        when error.message == error.class.name then name
+        else                                        "#{name}, #{error.message}"
+        end
+      end
+
+      def without_backtrace(message)
+        message.sub(/\s*\[".*\z/m, "")
+      end
+
+      # DNSSEC off: MTA-STS trusts the policy-host certificate, not DNS.
+      # Caching off: dnsruby's cache is process-global and would hide SERVFAIL behind a stale hit.
+      def resolver
+        @resolver ||= Dnsruby::Resolver.new(**config).tap do |dns|
+          dns.dnssec = false
+          dns.do_caching = false
+          dns.query_timeout = @timeout
+        end
+      end
+
+      def config
+        {}
+      end
+  end
+end

data/lib/mta_sts/result.rb

@@ -0,0 +1,47 @@
+module MtaSts
+  # status = what this lookup learned; policy = what to honour (§5.1)
+  class Result
+    attr_reader :status, :policy, :comment
+
+    def initialize(status:, policy: nil, comment: nil)
+      @status, @policy, @comment = status, policy, comment
+    end
+
+    def found?
+      status == "found"
+    end
+
+    # "no TXT this time" — not "no policy applies" (see Policy#none?)
+    def no_record?
+      status == "none"
+    end
+
+    def temperror?
+      status == "temperror"
+    end
+
+    def permerror?
+      status == "permerror"
+    end
+
+    def enforce?
+      policy&.enforce? || false
+    end
+
+    def testing?
+      policy&.testing? || false
+    end
+
+    def allows?(host)
+      if policy
+        policy.allows?(host)
+      else
+        true
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name} status: #{status.inspect}, policy: #{policy.inspect}, comment: #{comment.inspect}>"
+    end
+  end
+end

data/lib/mta_sts/version.rb

@@ -0,0 +1,3 @@
+module MtaSts
+  VERSION = "0.1.0"
+end

data/lib/mta_sts.rb

@@ -0,0 +1,153 @@
+require "mta_sts/version"
+require "mta_sts/resolver"
+require "mta_sts/fetcher"
+require "mta_sts/policy"
+require "mta_sts/result"
+require "mta_sts/report"
+require "mta_sts/report/result"
+require "mta_sts/cli"
+
+module MtaSts
+  DISCOVERY_PREFIX = "_mta-sts."
+  POLICY_HOST_PREFIX = "mta-sts."
+  REPORTING_PREFIX = "_smtp._tls." # RFC 8460 §3
+
+  # RFC 8461 §3.1 ABNF: sts-version = %s"v=STSv1", then sts-field-delim
+  STS_RECORD = /\Av=STSv1;/
+  FIELD_DELIM = ";"
+  ID_FIELD = /\Aid=(.*)\z/
+  # RFC 8461 §3.1 ABNF: sts-id = 1*32(ALPHA / DIGIT)
+  STS_ID = /\A[a-zA-Z0-9]{1,32}\z/
+
+  class << self
+    # `known:` is required so omitting it is a decision, not an accident (§5.1).
+    def lookup(domain, known:, resolver: Resolver.new, fetcher: Fetcher.new, now: Time.now)
+      domain = Policy.normalize(recipient_domain(domain))
+      held = usable(known, domain, now)
+      id = discover(domain, resolver)
+
+      case
+      when id == :unreachable    then unreachable(domain, held)
+      when id == :absent         then absent(domain, held)
+      when held && held.id == id then renewed(domain, held, now)
+      else                            fetched(domain, id, held, fetcher, now)
+      end
+    end
+
+    # RFC 8460 §3
+    def reporting(domain, resolver: Resolver.new)
+      domain = Policy.normalize(recipient_domain(domain))
+
+      case record = sole_record("#{REPORTING_PREFIX}#{domain}", matching: Report::REPORT_RECORD, resolver: resolver)
+      when :unreachable then unanswered(domain)
+      when :absent      then unpublished(domain)
+      else                   reported(domain, record)
+      end
+    end
+
+    private
+      def recipient_domain(domain)
+        domain.to_s.split("@").last.to_s
+      end
+
+      def usable(policy, domain, now)
+        policy if policy && !policy.expired?(now) && belongs_to?(policy, domain)
+      end
+
+      def belongs_to?(policy, domain)
+        policy.domain.nil? || policy.domain == domain
+      end
+
+      # RFC 8461 §3.1 — not exactly one usable record means the domain does not implement MTA-STS
+      def discover(domain, resolver)
+        case record = sole_record("#{DISCOVERY_PREFIX}#{domain}", matching: STS_RECORD, resolver: resolver)
+        when :absent, :unreachable then record
+        else                            policy_id(record) || :absent
+        end
+      end
+
+      def sole_record(name, matching:, resolver:)
+        records = resolver.txt(name).grep(matching)
+
+        if records.one?
+          records.first
+        else
+          :absent
+        end
+      rescue Resolver::NotFound
+        :absent
+      rescue Resolver::Error
+        :unreachable
+      end
+
+      def policy_id(record)
+        ids = record.split(FIELD_DELIM).map(&:strip).filter_map { |field| field[ID_FIELD, 1] }
+
+        ids.first if ids.one? && ids.first.match?(STS_ID)
+      end
+
+      def unreachable(domain, held)
+        outcome(held, status: "temperror",
+          comment: "DNS didn't answer for #{DISCOVERY_PREFIX}#{domain}")
+      end
+
+      def absent(domain, held)
+        outcome(held, status: "none",
+          comment: "#{domain} publishes no MTA-STS policy")
+      end
+
+      # RFC 8461 §5.1 — matching id renews without refetching
+      def renewed(domain, held, now)
+        policy = Policy.new(mode: held.mode, mx: held.mx, max_age: held.max_age,
+          id: held.id, domain: domain, fetched_at: now)
+
+        found(policy, "policy id #{policy.id} is unchanged; renewed until #{policy.expires_at} without refetching")
+      end
+
+      def fetched(domain, id, held, fetcher, now)
+        policy = Policy.parse(fetcher.fetch("#{POLICY_HOST_PREFIX}#{domain}"), id: id, domain: domain, fetched_at: now)
+
+        found(policy, "fetched policy id #{id} from #{POLICY_HOST_PREFIX}#{domain}")
+      rescue Fetcher::Error => error
+        outcome(held, status: "temperror",
+          comment: "couldn't fetch the policy for #{domain}: #{error.message}")
+      rescue Policy::Invalid => error
+        outcome(held, status: "permerror",
+          comment: "#{POLICY_HOST_PREFIX}#{domain} served a policy that isn't valid: #{error.message}")
+      end
+
+      # §5.1 — only an explicit successful answer may weaken a held policy; status still reports the failure
+      def outcome(held, status:, comment:)
+        if held
+          Result.new(status: status, policy: held,
+            comment: "#{comment}; the policy already held stands until #{held.expires_at}")
+        else
+          Result.new(status: status, comment: comment)
+        end
+      end
+
+      def found(policy, comment)
+        Result.new(status: "found", policy: policy, comment: comment)
+      end
+
+      def unanswered(domain)
+        Report::Result.new(status: "temperror",
+          comment: "DNS didn't answer for #{REPORTING_PREFIX}#{domain}")
+      end
+
+      def unpublished(domain)
+        Report::Result.new(status: "none",
+          comment: "#{domain} publishes no usable TLSRPT record at #{REPORTING_PREFIX}#{domain}")
+      end
+
+      def reported(domain, record)
+        report = Report.parse(record, domain: domain)
+
+        Report::Result.new(status: "found", report: report,
+          comment: "#{REPORTING_PREFIX}#{domain} asks for TLS reports at #{report.rua.join(", ")}")
+      rescue Report::Invalid => error
+        Report::Result.new(status: "permerror",
+          comment: "#{REPORTING_PREFIX}#{domain} isn't a usable TLSRPT record: #{error.message}")
+      end
+  end
+end

data/mta_sts.gemspec

@@ -0,0 +1,37 @@
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require_relative "lib/mta_sts/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "mta_sts"
+  spec.version = MtaSts::VERSION
+  spec.platform = Gem::Platform::RUBY
+  spec.required_ruby_version = ">= 3.3.4"
+  spec.authors = [ "PostRider" ]
+  spec.email = [ "support@postrider.dev" ]
+
+  spec.summary = "MTA-STS policy discovery and enforcement for outbound SMTP in Ruby."
+  spec.description = "Answers one question before delivering a message: must this connection be encrypted, and to which servers?"
+
+  spec.homepage = "https://github.com/mailpiece/mta_sts"
+  spec.license = "MIT"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "exe/**/*",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE",
+    "mta_sts.gemspec"
+  ]
+  spec.bindir = "exe"
+  spec.executables = [ "mta-sts" ]
+  spec.require_paths = [ "lib" ]
+
+  spec.add_dependency "dnsruby", "~> 1.74"
+  spec.add_dependency "simpleidn", "~> 0.2"
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: mta_sts
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- PostRider
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dnsruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.74'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.74'
+- !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: 'Answers one question before delivering a message: must this connection
+  be encrypted, and to which servers?'
+email:
+- support@postrider.dev
+executables:
+- mta-sts
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/mta-sts
+- lib/mta_sts.rb
+- lib/mta_sts/cli.rb
+- lib/mta_sts/fetcher.rb
+- lib/mta_sts/policy.rb
+- lib/mta_sts/report.rb
+- lib/mta_sts/report/result.rb
+- lib/mta_sts/resolver.rb
+- lib/mta_sts/result.rb
+- lib/mta_sts/version.rb
+- mta_sts.gemspec
+homepage: https://github.com/mailpiece/mta_sts
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mailpiece/mta_sts
+  changelog_uri: https://github.com/mailpiece/mta_sts/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mailpiece/mta_sts/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.4
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: MTA-STS policy discovery and enforcement for outbound SMTP in Ruby.
+test_files: []