mta_sts 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9411774536a59bfad560263255edf3e3d7d72d79fb943a6033027de9288dc9f
+  data.tar.gz: 272a5f2abd617892cec5cd21279300fa00b52fbaec16686c977657d6b9a37ddc
+SHA512:
+  metadata.gz: a3c37c313c46186d4073cc8576ce88e588f3b02aaf35c1f9b305df98a6ca82111c78efdad642a5f2fa755f7a3e9e27590dcfa5f04c0068d70b9301e3a37c4840
+  data.tar.gz: 5edd1bc7ff60ea8d161a8627ac90ba8b50d44d8f6938787f3b3dbb16512c90b750ec682acc32177457c11d64617045bf2a18c15e9d9e196017b899d194389272

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.6.0
+
+- The fetch ignores a proxy from the environment.
+- The fetch's total timeout also bounds the response headers.
+
+## 0.5.0
+
+- Initial public release.

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,262 @@
+# mta_sts
+
+🔒 SMTP MTA Strict Transport Security for Ruby.
+
+Look up a recipient domain's MTA-STS policy before delivering a message, to know whether TLS must be enforced and which servers are legitimate.
+
+**mta_sts** resolves a recipient domain's MTA-STS policy (RFC 8461) and finds out which of its mail servers may be used and whether TLS is optional. It also discovers where the domain wants TLS failure reports sent (RFC 8460 TLSRPT).
+
+For outbound MTAs deciding how to deliver a message: mail servers refusing to downgrade to plaintext or connect to an unlisted host, senders discovering where to submit TLSRPT aggregate reports.
+
+**mta_sts** handles:
+
+- MTA-STS policy lookup (RFC 8461) - which mail servers a domain vouches for, and whether TLS is optional or must be enforced
+- status and policy kept as separate axes, so a DNS timeout can't be mistaken for a domain that dropped its policy
+- policy persistence handled by the caller - hand back what you kept last time, and get told what to keep next
+- TLSRPT record discovery (RFC 8460) - where a domain wants TLS failure reports sent
+- injectable resolver and fetcher, with the fetcher validating the resolved address before it dials, since the address is a stranger's choosing
+- policy publishing and parsing helpers, for domains serving their own policy
+
+> Resolves a policy and tells you whether to trust a server. What you do with that answer - defer, refuse, downgrade - stays in your code.
+
+## Contents
+
+- [Installation](#installation)
+- [Looking Up a Policy](#looking-up-a-policy)
+- [Results](#results)
+- [Status and Policy Are Separate Axes](#status-and-policy-are-separate-axes)
+- [Holding On to a Policy](#holding-on-to-a-policy)
+- [TLSRPT Record Discovery](#tlsrpt-record-discovery)
+- [Custom Resolver & Fetcher](#custom-resolver--fetcher)
+- [Publishing a Policy](#publishing-a-policy)
+- [What It Is Strict About](#what-it-is-strict-about)
+- [What It Is Not That Strict](#what-it-is-not-that-strict)
+- [What It Does Not Check](#what-it-does-not-check)
+- [Testing](#testing)
+- [History](#history)
+- [Contributing](#contributing)
+- [Acknowledgments](#acknowledgments)
+- [License](#license)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "mta_sts"
+```
+
+Requires Ruby >= 3.4
+
+## 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 `MailResolver::Resolver.new`, from the [mailresolver](https://github.com/mailpiece/mailresolver) gem
+- **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 [mailresolver](https://github.com/mailpiece/mailresolver) by default. Covers discovery only (`_mta-sts` and `_smtp._tls`). Raise `MailResolver::NotFound` for no such record, `MailResolver::Timeout` or `MailResolver::ServerFailure` for no answer. If your app also uses `mailauth` or talks to DNS itself, build one `MailResolver::Resolver` and pass it everywhere — see mailresolver's README for why.
+- **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.
+
+The fetcher resolves the policy host itself, so that the address it dials is one it has judged:
+
+```ruby
+MtaSts::Fetcher.new(
+  resolver:  MyResolver.new,                       # needs `addresses` as well as `txt`
+  permitted: ->(address) { my_own_opinion(address) })
+```
+
+- **permitted** - asked about each resolved address; each one admitted is dialled in turn until the host answers. Defaults to `MtaSts::Fetcher.public_address?`, which admits public unicast and refuses private, loopback, link-local, and other special-use addresses, including ones wrapped or reached through NAT64. A deployment serving policies from inside its own network passes something more permissive.
+
+The recipient domain names the policy host, so where it resolves is chosen by whoever is being sent mail — without this, that's a request to an address of a stranger's choosing.
+
+## 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>
+```
+
+## 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
+- Line terminators may be bare `LF` as well as `CRLF`
+- The policy file is read case-insensitively, so `version: stsv1` and `mode: ENFORCE` both parse, though the ABNF spells both case-sensitively. The discovery record is not read this way: strictness is worth more on the record that decides whether a policy exists at all than on the document it leads to
+
+## 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
+```
+
+## History
+
+View the [changelog](CHANGELOG.md).
+
+## Contributing
+
+Everyone is encouraged to help improve this project:
+
+- [Report bugs](https://github.com/mailpiece/mta_sts/issues)
+- Fix bugs and submit pull requests
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+## Acknowledgments
+
+View the [acknowledgments](ACKNOWLEDGMENTS.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/mta_sts/fetcher.rb

@@ -0,0 +1,262 @@
+require "ipaddr"
+require "net/http"
+require "openssl"
+require "zlib"
+require "mailresolver"
+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
+    # A temperror like any other failed fetch, so a policy already held stands.
+    class BlockedAddress < Error; end
+    class Timeout < Error; end
+
+    # A failure the policy host never answered through
+    class Unanswered < StandardError
+      attr_reader :failure
+
+      def initialize(failure)
+        super(failure.message)
+        @failure = failure
+      end
+    end
+    private_constant :Unanswered
+
+    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}"
+
+    # 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
+
+    # Special-use IPv4 no policy is published in. RFC 1918, loopback and
+    # link-local are left to the IPAddr predicates.
+    RESERVED_V4 = %w[
+      0.0.0.0/8 100.64.0.0/10 192.0.0.0/24 192.0.2.0/24 192.88.99.0/24
+      198.18.0.0/15 198.51.100.0/24 203.0.113.0/24 224.0.0.0/4 240.0.0.0/4
+    ].map { |range| IPAddr.new(range) }.freeze
+
+    RESERVED_V6 = %w[
+      ::/128 64:ff9b:1::/48 100::/64 2001::/32 2001:2::/48 2001:db8::/32
+      2002::/16 fec0::/10 ff00::/8
+    ].map { |range| IPAddr.new(range) }.freeze
+
+    # RFC 6052 §2.2 with a /96 prefix
+    NAT64 = IPAddr.new("64:ff9b::/96")
+
+    class << self
+      # The policy host is named by the domain being delivered to, so where it
+      # resolves is a stranger's to choose.
+      def public_address?(address)
+        ip = address.is_a?(IPAddr) ? address : IPAddr.new(address.to_s)
+
+        case
+        # No resolver legitimately answers with an address wrapped in another,
+        # whatever it wraps.
+        when ip.ipv4_mapped? || ipv4_compat?(ip) then false
+        when ip.ipv4?                           then public_v4?(ip)
+        when NAT64.include?(ip)                 then public_v4?(embedded_v4(ip))
+        else                                         public_v6?(ip)
+        end
+      rescue IPAddr::Error
+        false
+      end
+
+      private
+        # IPAddr#ipv4_compat? is obsolete; reimplemented since the check itself
+        # (the deprecated ::a.b.c.d form) is still one we need to catch.
+        def ipv4_compat?(ip)
+          if ip.ipv6?
+            low = ip.to_i & 0xffffffff
+            (ip.to_i >> 32).zero? && low != 0 && low != 1
+          else
+            false
+          end
+        end
+
+        def public_v4?(ip)
+          !(ip.private? || ip.loopback? || ip.link_local? || covered_by?(RESERVED_V4, ip))
+        end
+
+        def embedded_v4(ip)
+          IPAddr.new(ip.to_i & 0xffffffff, Socket::AF_INET)
+        end
+
+        def public_v6?(ip)
+          !(ip.private? || ip.loopback? || ip.link_local? || covered_by?(RESERVED_V6, ip))
+        end
+
+        def covered_by?(ranges, ip)
+          ranges.any? { |range| range.include?(ip) }
+        end
+    end
+
+    def initialize(open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT,
+                   total_timeout: TOTAL_TIMEOUT, max_body_bytes: MAX_BODY_BYTES,
+                   resolver: MailResolver::Resolver.new, permitted: Fetcher.method(:public_address?))
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @total_timeout = total_timeout
+      @max_body_bytes = max_body_bytes
+      @resolver = resolver
+      @permitted = permitted
+    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
+        failure = nil
+
+        # A policy host with several addresses isn't written off because the first
+        # is down — the domain published all of them, and any one serves.
+        permitted_addresses(host).each do |address|
+          remaining = deadline - monotonic_now
+          break unless remaining.positive?
+
+          begin
+            return policy_from(host, address, deadline, remaining)
+          rescue Unanswered => unanswered
+            failure = unanswered.failure
+          end
+        end
+
+        raise failure || Timeout.new("timed out fetching the policy from #{host}")
+      end
+
+      # Resolved once here and carried into every connection: resolving again to
+      # dial would leave the second answer free to differ from the one judged.
+      def permitted_addresses(host)
+        addresses = resolve(host).select { |address| @permitted.call(address) }
+        raise BlockedAddress, "#{host} resolves to no address a policy may be published at" if addresses.empty?
+
+        addresses
+      end
+
+      def resolve(host)
+        addresses = @resolver.addresses(host)
+        raise Error, "couldn't resolve #{host}" if addresses.empty?
+
+        addresses
+      rescue MailResolver::Error => error
+        raise Error, "couldn't resolve #{host}: #{error.message}"
+      end
+
+      def policy_from(host, address, deadline, remaining)
+        with_response(host, address, remaining) 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
+
+      # `answered` is the whole distinction the attempt loop turns on. read_timeout
+      # renews with every header line, so the deadline also bounds the headers.
+      def with_response(host, address, remaining)
+        answered = false
+        result = nil
+
+        ::Timeout.timeout(remaining) do
+          connection(host, address).start do |http|
+            http.request(policy_request) do |response|
+              answered = true
+              result = yield response
+            end
+          end
+        end
+
+        result
+      rescue OpenSSL::SSL::SSLError => error
+        raise attempt_failure(answered, CertificateError.new("#{host} presented a certificate that didn't verify: #{error.message}"))
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise attempt_failure(answered, Timeout.new("timed out fetching the policy from #{host}"))
+      rescue ::Timeout::Error
+        raise attempt_failure(answered, Timeout.new("#{host} took longer than #{@total_timeout} seconds to send the policy"))
+      rescue Net::HTTPBadResponse, Net::ProtocolError, Zlib::Error => error
+        raise attempt_failure(answered, HttpError.new("#{host} answered with malformed HTTP: #{error.message}"))
+      rescue SystemCallError, SocketError, IOError, EOFError => error
+        raise attempt_failure(answered, Error.new("couldn't reach #{host}: #{error.message}"))
+      end
+
+      def connection(host, address)
+        # The nil proxy ignores http_proxy: a proxy would resolve the name again,
+        # and the connection would no longer go to the address judged.
+        Net::HTTP.new(host, PORT, nil).tap do |http|
+          # Dial the address already judged; the name stays behind for SNI, the
+          # Host header, and the certificate the whole fetch rests on.
+          http.ipaddr = address
+          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 attempt_failure(answered, error)
+        if answered
+          error
+        else
+          Unanswered.new(error)
+        end
+      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,179 @@
+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
+
+        # RFC 8461 §3.2 - a duplicated non-mx field: keep the first, ignore the rest.
+        def single(fields, name)
+          fields.fetch(name, []).first
+        end
+
+        def validate_version(version)
+          unless version&.casecmp?(POLICY_VERSION)
+            raise Invalid, "version must be #{POLICY_VERSION}, not #{version.inspect}"
+          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
+    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,105 @@
+require "mta_sts/policy"
+require "mta_sts/report/result"
+
+module MtaSts
+  class Report
+    class Invalid < StandardError; end
+
+    REPORT_VERSION = "TLSRPTv1"
+    # RFC 8460 §3 has the same ABNF/prose contradiction as RFC 8461 §3.1 (see
+    # STS_RECORD) — the literal "v=TLSRPTv1;" prefix is what's enforced.
+    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/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.6.0"
+end

data/lib/mta_sts.rb

@@ -0,0 +1,153 @@
+require "mailresolver"
+require "mta_sts/version"
+require "mta_sts/fetcher"
+require "mta_sts/policy"
+require "mta_sts/result"
+require "mta_sts/report"
+require "mta_sts/report/result"
+
+module MtaSts
+  DISCOVERY_PREFIX = "_mta-sts."
+  POLICY_HOST_PREFIX = "mta-sts."
+  REPORTING_PREFIX = "_smtp._tls." # RFC 8460 §3
+
+  # RFC 8461 §3.1's ABNF would admit `v=STSv1 ; id=...`, but its prose discards
+  # anything not literally starting "v=STSv1;" — the prose is what everyone implements.
+  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: MailResolver::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: MailResolver::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 MailResolver::NotFound
+        :absent
+      rescue MailResolver::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,33 @@
+$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.4"
+  spec.authors = [ "Simon Lev" ]
+
+  spec.summary = "SMTP MTA Strict Transport Security for Ruby."
+  spec.description = "SMTP MTA Strict Transport Security for Ruby. Look up a recipient domain's MTA-STS policy before delivering a message, to know whether TLS must be enforced and which servers are legitimate."
+
+  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",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE",
+    "mta_sts.gemspec"
+  ]
+  spec.require_paths = [ "lib" ]
+
+  spec.add_dependency "mailresolver"
+  spec.add_dependency "simpleidn", "~> 0.2"
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: mta_sts
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: ruby
+authors:
+- Simon Lev
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mailresolver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '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: SMTP MTA Strict Transport Security for Ruby. Look up a recipient domain's
+  MTA-STS policy before delivering a message, to know whether TLS must be enforced
+  and which servers are legitimate.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mta_sts.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/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.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: SMTP MTA Strict Transport Security for Ruby.
+test_files: []