mailauth 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77dfb8831d86e9be13316fe465a7655bf0aedf4da6164cdd0d2c4ab51cb5f6a4
+  data.tar.gz: dd67a9d118d2410deeb00d57f907075c9d77e58637f69b2989ed7c1066e01fd8
+SHA512:
+  metadata.gz: 3ebf36b61620326e742d838d3472dc32f8e9fb43812126e27e00daed54e947711167ab42742622432f28344b5ceeeee3d1d2348f1187212a4708c2138a821770
+  data.tar.gz: c35623984649fb47802e1a61386bbb8cdb91f192b2597209d5556ccafba35c97099afc482fa531837d94e54ce29a72131b82f6f25fdb2f19e446bbe03b7effd9

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.3.0
+
+**A nameserver failing is no longer read as a domain publishing nothing.** Expect
+your verdict distribution to shift: lookups that failed against SERVFAIL or
+REFUSED previously returned `none` from SPF and DMARC and `permerror` from DKIM,
+and now return `temperror`. Nothing was wrong at the call sites — they always
+handled a server failure correctly — but the resolver beneath them could not
+raise one, so the branch never ran.
+
+The cause was in the standard library. `Resolv::DNS#getresources` turns an rcode
+into an exception and then discards it unless the failure was a timeout, so
+SERVFAIL and REFUSED came back as the same empty array as NXDOMAIN and NODATA. A
+domain publishing `p=reject` whose nameserver was unwell was reported as a domain
+publishing no DMARC policy at all, and SPF would state that it "does not
+designate permitted sender hosts" on the strength of an answer nobody gave.
+
+- Resolution moved from `Resolv` to [dnsruby](https://github.com/alexdalitz/dnsruby), which reports each rcode as a
+  distinct class, so the distinction is read off the wire rather than inferred.
+  This adds a runtime dependency; its own dependencies are `base64`, `logger`,
+  and `simpleidn`, all of them default gems and the last already ours
+- `temperror` for SERVFAIL and REFUSED, across SPF, DMARC, DKIM, and
+  `Authentication-Results`. NXDOMAIN and NOERROR-with-no-records still mean
+  absence, and still read `none`
+- An unrecognised resolver error now reports a server failure rather than a
+  missing record. "We could not tell" must not be delivered as "there is nothing
+  there"
+- DNS answers are no longer cached inside the library. Dnsruby caches by default
+  in a store shared across every resolver in the process; a caller who wants
+  caching has the `resolver:` seam to put it behind
+- Errors name the record type as DNS does. `Resolv` names some of its generated
+  classes after their type and class numbers, so a deferral could read "no
+  Type16_Class1 records for example.com"
+
+## 0.2.0
+
+- ARC verification (RFC 8617)
+
+## 0.1.0
+
+Initial release.
+
+- SPF verification (RFC 7208), checked against the official 200-case test suite
+- DKIM verification (RFC 6376), RSA and Ed25519 (RFC 8463), all four canonicalizations
+- DKIM signing, RSA and Ed25519, oversigning by default, checked byte-for-byte against the RFC 8463 sample signatures
+- DMARC verification (RFC 7489), strict and relaxed alignment, organizational domains via the Public Suffix List
+- `Authentication-Results` header generation (RFC 8601)
+- Injectable resolver with an error taxonomy that distinguishes a void lookup from a server failure

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,211 @@
+# mailauth
+
+✉️ Email authentication for Ruby
+
+**mailauth** verifies SPF, DKIM, DMARC, and ARC on received mail, and signs outgoing mail with DKIM. Pure Ruby, no dependencies beyond `dnsruby`.
+
+It answers one question about a message: is it really from who it says it's from?
+
+## Features
+
+- SPF verification (RFC 7208)
+- DKIM verification (RFC 6376), RSA and Ed25519
+- DKIM signing (RFC 6376), RSA and Ed25519, oversigning by default
+- DMARC verification (RFC 7489), strict and relaxed alignment
+- Authentication-Results header generation (RFC 8601)
+- ARC verification (RFC 8617), reporting what each hop sealed and left to you to trust
+- Injectable resolver, so tests run against a hash instead of a network
+
+Not planned: MTA-STS (outbound TLS policy, not message auth), `Received-SPF` (Authentication-Results already covers it), `%{p}` (RFC 7208 discourages PTR).
+
+> Not a spam filter.
+
+
+## Getting Started
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "mailauth"
+```
+
+Requires Ruby >= 3.3.4
+
+## Authentication
+
+```ruby
+result = MailAuth.authenticate(raw_message, ip:, helo:, mail_from:, mta:, resolver:, now:)
+# => #<MailAuth::Result spf:, dkim:, dmarc:, arc:, authentication_results:>
+```
+
+- **raw_message** - the RFC 822 bytes as they arrived
+- **ip** - IP address of the connecting client
+- **helo** - optional, hostname from the HELO/EHLO command
+- **mail_from** - optional, envelope sender; empty means `postmaster@helo` is checked
+- **mta** - optional, your authserv-id, for the generated header
+- **resolver** - optional, defaults to `MailAuth::Resolver.new`
+- **now** - optional `Time`, for signature expiry, defaults to `Time.now`
+
+```ruby
+require "mailauth"
+
+result = MailAuth.authenticate(raw_message,
+  ip: "209.85.220.41",
+  helo: "mail-sor-f41.google.com",
+  mail_from: "someone@gmail.com",
+  mta: "mx.example.com")
+
+puts result.authentication_results
+```
+
+```ruby
+mx.example.com;
+spf=pass
+(domain of someone@gmail.com designates 209.85.220.41 as permitted sender)
+smtp.mailfrom=gmail.com;
+dkim=pass header.d=gmail.com header.s=20251104 header.a=rsa-sha256;
+dmarc=pass (p=NONE) header.from=gmail.com
+```
+
+## Results
+
+```ruby
+result.spf.status      # => "pass"
+result.spf.domain      # => "gmail.com"
+
+result.dkim.status     # => "pass" - the best of every signature on the message
+result.dkim.signatures # => [#<MailAuth::Signature status: "pass", domain: "gmail.com", ...>]
+
+result.dmarc.status    # => "pass"
+result.dmarc.policy    # => "reject" - what the domain asked for
+result.dmarc.alignment # => { dkim: true, spf: false }
+```
+
+Every status is one of `pass`, `fail`, `softfail`, `neutral`, `none`, `temperror`, `permerror` - the RFC 8601 vocabulary as plain strings, so a verdict persists without translation.
+
+`status` and `policy` stay separate. A DMARC `fail` under `p=none` and one under `p=reject` are the same failure; only the second is a reason to refuse the mail.
+
+## Individual Checks
+
+Each protocol is usable on its own. SPF needs no message at all, so it can answer at `RCPT TO` time, before any data has arrived:
+
+```ruby
+MailAuth::Spf.check(ip: "209.85.220.41", helo: "mail-sor-f41.google.com",
+  mail_from: "someone@gmail.com")
+# => #<MailAuth::SpfResult status: "pass", domain: "gmail.com", lookups: 1, ...>
+
+message = MailAuth::Message.new(raw_message)
+
+MailAuth::Dkim.verify(message)
+# => #<MailAuth::DkimResult signatures: [...]>
+
+MailAuth::Dmarc.check(header_from: message.header_from_domain, spf: spf, dkim: dkim)
+# => #<MailAuth::DmarcResult status: "pass", policy: "none", ...>
+
+MailAuth::Arc.verify(message)
+# => #<MailAuth::ArcResult status: "pass", sets: [...], ...>
+```
+
+DMARC takes the SPF and DKIM results rather than recomputing them - alignment is a comparison, not a check of its own. ARC takes neither: a chain says what an earlier hop concluded, a separate question from what this one measured.
+
+## When It Doesn't Pass
+
+Nothing raises. A verdict is always returned, and the interesting ones carry a `comment`:
+
+```ruby
+result.dkim.signatures.each do |signature|
+  puts "#{signature.domain}: #{signature.status} #{signature.comment}"
+end
+# gmail.com: fail body hash did not verify
+# example.com: temperror DNS failure resolving sel._domainkey.example.com
+```
+
+- `fail` - the check ran and the message did not pass it
+- `temperror` - DNS didn't answer; the same message may well pass later, don't treat it as a failure
+- `permerror` - the record or signature is broken; retrying changes nothing
+- `none` - the domain published no policy, or the message carried no signature
+
+
+
+## Resolver
+
+Every lookup goes through one object with five methods - `txt`, `a`, `aaaa`, `mx`, `ptr`:
+
+```ruby
+MailAuth.authenticate(raw, ip: ip, resolver: MyCachingResolver.new)
+```
+
+Raise `NotFound` for a void lookup (SPF counts these against a limit), `Timeout` or `ServerFailure` for no answer, which produces a `temperror` that stops evaluation. Collapsing those into empty arrays loses a distinction SPF spends much of its rulebook on.
+
+The default resolver uses [dnsruby](https://github.com/alexdalitz/dnsruby) rather than `Resolv`, which collapses SERVFAIL/REFUSED into the same empty answer as NXDOMAIN. It caches nothing and does not validate DNSSEC.
+
+## ARC
+
+Forwarding breaks SPF, and mailing lists that rewrite a subject line break DKIM. An Authenticated Received Chain carries what each hop concluded before that happened, sealed against later editing:
+
+```ruby
+result.arc.status    # => "pass" - the chain is intact
+result.arc.sealers   # => ["lists.example.org"] - oldest hop first
+result.arc.newest.claimed
+# => { "spf" => "pass", "dkim" => "pass", "dmarc" => "pass" }
+```
+
+An intact chain is not a reason to believe it. Sealing a chain over a message of one's own costs nothing, so a `pass` from a sealer you've never heard of means only that they signed what they signed. This library reports who sealed and what they asserted; deciding whose word counts is yours:
+
+```ruby
+if result.arc.intact? && TRUSTED_SEALERS.include?(result.arc.newest.seal.domain)
+  result.arc.newest.claimed["dmarc"]
+end
+```
+
+For the same reason a chain never touches the DMARC verdict. `result.dmarc` is what this hop measured; letting a chain speak for it would sell a pass for the price of a signature.
+
+## Signing
+
+```ruby
+signed = MailAuth::Dkim.sign(raw_message,
+  domain: "example.com", selector: "mail",
+  key: OpenSSL::PKey.read(File.read("private.pem")))
+# => the message with a DKIM-Signature field prepended
+```
+
+The algorithm comes from the key: an RSA key signs `rsa-sha256`, an Ed25519 key `ed25519-sha256` (RFC 8463). Canonicalization is `relaxed/relaxed`.
+
+- **headers** - names to sign; defaults to the RFC 6376 §5.4.1 set
+- **oversign** - names listed in `h=` once more than they occur, so an instance added after signing breaks it. Defaults to `from`, `to`, `cc`, `subject`, `date`, `reply-to`, `message-id`. Pass `[]` to disable
+- **expires_in** - seconds, writes `x=`; omitted by default
+- **now** - the signing instant for `t=`, defaults to `Time.now`
+
+`MailAuth::Dkim::Signer#field` returns just the `DKIM-Signature` field, for callers assembling messages themselves.
+
+## Testing
+
+```sh
+bundle install
+rake
+```
+
+SPF runs against the [RFC 7208 test suite](http://www.openspf.org/Test_Suite) - 200 official cases covering every mechanism, the lookup limits, and the error semantics. One case is skipped: `p-macro-multiple`, which needs PTR forward-confirmation this library doesn't do.
+
+DKIM runs against the sample message in RFC 8463 Appendix A, which carries both an RSA and an Ed25519 signature over the same body. Signing is held to the same standard: both algorithms are deterministic, so signing the sample message with its published private keys must reproduce the published signatures byte for byte.
+
+ARC runs against the [ValiMail ARC test suite](https://github.com/ValiMail/arc_test_suite) - 171 cases over chain validation, header structure, tag grammar, and key strength.
+
+## History
+
+View the changelog
+
+## Contributing
+
+Everyone is encouraged to help improve this project:
+
+- [Report bugs](https://github.com/example/mailauth/issues)
+- Fix bugs and submit pull requests
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/mailauth/arc/chain.rb

@@ -0,0 +1,100 @@
+require "mailauth/arc/set"
+
+module MailAuth
+  module Arc
+    # Every ARC header on a message, grouped into the sets they claim to belong
+    # to, and held to the structure RFC 8617 §5.2 step 3 requires of them.
+    class Chain
+      KINDS = {
+        "arc-authentication-results" => :authentication_results,
+        "arc-message-signature" => :message_signature,
+        "arc-seal" => :seal
+      }.freeze
+
+      def initialize(message)
+        @message = message
+      end
+
+      def empty?
+        sets.empty?
+      end
+
+      # Instance values run 1..50 (§4.2.1), so a chain longer than that is over
+      # the ceiling however its instances are numbered.
+      def oversized?
+        sets.size > MAXIMUM_SETS
+      end
+
+      def sets
+        @sets ||= collect
+      end
+
+      def ordered
+        sets.values.sort_by(&:instance)
+      end
+
+      def newest
+        ordered.last
+      end
+
+      # Everything up to and including one instance — what that instance's seal
+      # signs (§5.1.1).
+      def through(instance)
+        ordered.take_while { |set| set.instance <= instance }
+      end
+
+      def structural_error
+        if incomplete = ordered.find { |set| !set.complete? }
+          "ARC set i=#{incomplete.instance} does not carry exactly one of each header"
+        elsif unreadable = ordered.find { |set| !set.readable? }
+          "ARC set i=#{unreadable.instance} carries an invalid tag list"
+        elsif ordered.map(&:instance) != (1..sets.size).to_a
+          "ARC instances are not a continuous sequence"
+        else
+          chain_status_error
+        end
+      end
+
+      private
+        # A header whose instance can't be read joins no set at all, which
+        # leaves the set it was meant for incomplete — the failure it deserves,
+        # without a rule of its own.
+        def collect
+          @message.fields.each_with_object({}) do |field, sets|
+            kind = KINDS[@message.field_name(field)]
+            instance = kind && instance_of(kind, field)
+
+            (sets[instance] ||= Set.new(instance)).add(kind, field) if instance
+          end
+        end
+
+        # Read before it is parsed: an instance runs to MAXIMUM_SETS, so a longer
+        # run of digits is no instance at all, and turning one into an integer to
+        # discover that is arbitrary work for whoever sent it.
+        INSTANCE = /\A0*[1-9]\d{0,2}\z/n
+
+        def instance_of(kind, field)
+          position = if kind == :authentication_results
+            Arc.value_of(field).to_s[INSTANCE_PREFIX, 1]
+          else
+            Arc.tags_in(field).to_h["i"]
+          end
+
+          Integer(position, 10) if position&.match?(INSTANCE)
+        end
+
+        # §5.2 step 3.3: instance 1 opens a chain and every hop above it says
+        # the chain was intact when it arrived. "fail" is caught earlier, at
+        # step 2, when the newest hop is the one saying it.
+        def chain_status_error
+          if wrong = ordered.find { |set| set.chain_status != expected_chain_status(set) }
+            "ARC set i=#{wrong.instance} reports cv=#{wrong.chain_status.inspect}"
+          end
+        end
+
+        def expected_chain_status(set)
+          set.instance == 1 ? "none" : "pass"
+        end
+    end
+  end
+end

data/lib/mailauth/arc/message_signature.rb

@@ -0,0 +1,158 @@
+require "openssl"
+
+module MailAuth
+  module Arc
+    # An ARC-Message-Signature (RFC 8617 §4.1.2): a DKIM signature over the
+    # message in all but name, differing in carrying no version tag, in taking
+    # i= as the instance rather than an identity, and in leaving From free —
+    # what it covers is the hop's business, not ours.
+    class MessageSignature
+      REQUIRED_TAGS = %w[ a b bh d h s ].freeze
+
+      # §4.1.2 gives the AMS DKIM's syntax and semantics bar three named
+      # differences, none of them canonicalization, which would leave an absent
+      # c= meaning simple/simple (RFC 6376 §3.5). Signers read it the other way
+      # and the conformance suite requires relaxed, so relaxed it is: simple
+      # canonicalization survives no intermediary, which is the one thing every
+      # message carrying this header has crossed.
+      DEFAULT_CANONICALIZATION = "relaxed/relaxed".freeze
+
+      def initialize(message, field, tags, resolver:)
+        @message, @field, @tags, @resolver = message, field, tags, resolver
+      end
+
+      def result
+        validate
+
+        if body_hash_matches?
+          verified? ? signature(Status::PASS) : failed("bad signature")
+        else
+          failed("body hash did not verify")
+        end
+      rescue Dkim::Malformed => error
+        signature Status::PERMERROR, comment: error.message
+      rescue Resolver::NotFound
+        signature Status::PERMERROR, comment: "no key for #{key_name}"
+      rescue Resolver::Timeout, Resolver::ServerFailure
+        signature Status::TEMPERROR, comment: "DNS failure resolving #{key_name}"
+      end
+
+      private
+        def validate
+          raise Dkim::Malformed, "invalid tag list" if @tags.nil?
+
+          if missing = REQUIRED_TAGS.find { |tag| !@tags.key?(tag) }
+            raise Dkim::Malformed, "missing #{missing}= tag"
+          end
+
+          raise Dkim::Malformed, "empty #{empty_tag}= tag" if empty_tag
+          raise Dkim::Malformed, "empty c= tag" if @tags.key?("c") && @tags["c"].strip.empty?
+          raise Dkim::Malformed, "unsupported algorithm #{@tags["a"]}" unless Arc.signing_algorithm?(@tags["a"])
+
+          # §4.1.2 bars an AMS from covering ARC header fields. The seal is the
+          # one that bites: it signs this signature, so a signature signing it
+          # back leaves each waiting on the other.
+          raise Dkim::Malformed, "h= covers the ARC-Seal" if signed_names.include?("arc-seal")
+
+          unless CANONICALIZATIONS.include?(header_canonicalization) && CANONICALIZATIONS.include?(body_canonicalization)
+            raise Dkim::Malformed, "unsupported canonicalization #{canonicalization}"
+          end
+
+          raise Dkim::Malformed, "invalid t= tag" if @tags["t"] && !@tags["t"].match?(/\A\d+\z/n)
+          raise Dkim::Malformed, "invalid l= tag" if @tags["l"] && !@tags["l"].match?(/\A\d+\z/n)
+        end
+
+        # h= may name nothing at all, but the tags carrying an identity or the
+        # maths cannot be present and blank.
+        def empty_tag
+          (REQUIRED_TAGS - %w[ h ]).find { |tag| @tags[tag].to_s.empty? }
+        end
+
+        def body_hash_matches?
+          digest.digest(signed_body) == unfolded("bh").unpack1("m")
+        end
+
+        def signed_body
+          body_limit ? canonical_body.byteslice(0, body_limit) : canonical_body
+        end
+
+        def body_limit
+          @tags["l"].to_i if @tags["l"]&.match?(/\A\d+\z/n)
+        end
+
+        def canonical_body
+          @canonical_body ||= Dkim::Canonicalization.body(@message.body, body_canonicalization)
+        end
+
+        def verified?
+          Dkim::Algorithm.verified?(canonical_headers, key: public_key, digest: digest,
+            signature: unfolded("b").unpack1("m"))
+        end
+
+        def public_key
+          Dkim::PublicKey.retrieve(selector: @tags["s"], domain: @tags["d"],
+            algorithm: Arc.signing_algorithm(@tags["a"]), resolver: @resolver)
+        end
+
+        def key_name
+          Dkim::PublicKey.name_for(selector: @tags["s"], domain: @tags["d"])
+        end
+
+        # The signature's own field closes the input with its b= emptied and no
+        # terminator, exactly as a DKIM signature does (RFC 6376 §3.7).
+        def canonical_headers
+          signed_fields.map { |field| canonicalize(field) + CRLF }.join +
+            canonicalize(@field).sub(/([;:\s]+b=)[^;]*/n, '\1')
+        end
+
+        # The last unused instance of each name, walking upward through
+        # duplicates (RFC 6376 §5.4.2).
+        def signed_fields
+          remaining = @message.fields.dup
+
+          signed_names.filter_map do |name|
+            if index = remaining.rindex { |field| @message.field_name(field) == name }
+              remaining.delete_at(index)
+            end
+          end
+        end
+
+        def signed_names
+          unfolded("h").to_s.downcase.split(":").reject(&:empty?)
+        end
+
+        def canonicalize(field)
+          Dkim::Canonicalization.field(field, header_canonicalization)
+        end
+
+        def digest
+          Dkim::HASHES.fetch(Arc.hash_algorithm(@tags["a"]))
+        end
+
+        def header_canonicalization
+          canonicalization.split("/").first
+        end
+
+        def body_canonicalization
+          canonicalization.split("/")[1] || "simple"
+        end
+
+        def canonicalization
+          @tags["c"].to_s.downcase.strip.empty? ? DEFAULT_CANONICALIZATION : @tags["c"].downcase.strip
+        end
+
+        def unfolded(tag)
+          @tags[tag]&.gsub(/[ \t\r\n]+/n, "")
+        end
+
+        def failed(comment)
+          signature(Status::FAIL, comment: comment)
+        end
+
+        def signature(status, comment: nil)
+          ArcSignature.new(status: status, domain: @tags&.[]("d")&.downcase, selector: @tags&.[]("s"),
+            algorithm: @tags&.[]("a"), comment: comment)
+        end
+    end
+  end
+end

data/lib/mailauth/arc/seal.rb

@@ -0,0 +1,97 @@
+require "openssl"
+
+module MailAuth
+  module Arc
+    # An ARC-Seal (RFC 8617 §4.1.3), which signs the chain rather than the
+    # message: no body, no h= naming what it covers — its scope is fixed by
+    # §5.1.1 — and relaxed header canonicalization only.
+    class Seal
+      REQUIRED_TAGS = %w[ i a b d s cv ].freeze
+
+      def initialize(sets, resolver:)
+        @sets, @resolver = sets, resolver
+        @set = sets.last
+        @tags = @set.seal_tags
+      end
+
+      def result
+        validate
+
+        verified? ? seal(Status::PASS) : seal(Status::FAIL, comment: "bad signature")
+      rescue Dkim::Malformed => error
+        seal Status::PERMERROR, comment: error.message
+      rescue Resolver::NotFound
+        seal Status::PERMERROR, comment: "no key for #{key_name}"
+      rescue Resolver::Timeout, Resolver::ServerFailure
+        seal Status::TEMPERROR, comment: "DNS failure resolving #{key_name}"
+      end
+
+      private
+        def validate
+          raise Dkim::Malformed, "invalid tag list" if @tags.nil?
+
+          # §4.1.3: a seal names no headers, and one that tries is fatal to the
+          # chain rather than merely ignored.
+          raise Dkim::Malformed, "h= is not allowed on an ARC-Seal" if @tags.key?("h")
+
+          if missing = REQUIRED_TAGS.find { |tag| @tags[tag].to_s.empty? }
+            raise Dkim::Malformed, "missing #{missing}= tag"
+          end
+
+          raise Dkim::Malformed, "unsupported algorithm #{@tags["a"]}" unless Arc.signing_algorithm?(@tags["a"])
+          raise Dkim::Malformed, "invalid cv= tag" unless CHAIN_STATUSES.include?(@tags["cv"].downcase)
+          raise Dkim::Malformed, "invalid t= tag" if @tags["t"] && !@tags["t"].match?(/\A\d+\z/n)
+        end
+
+        def verified?
+          Dkim::Algorithm.verified?(signed_headers, key: public_key, digest: digest,
+            signature: unfolded("b").unpack1("m"))
+        end
+
+        # §5.1.1: every set from instance 1 upward, each contributing its AAR,
+        # then its AMS, then its seal — this one's with b= emptied, and nothing
+        # terminating the last line.
+        def signed_headers
+          @sets.flat_map { |set| headers_of(set) }.join(CRLF)
+        end
+
+        def headers_of(set)
+          [ canonicalize(set.authentication_results), canonicalize(set.message_signature), canonical_seal(set) ]
+        end
+
+        def canonical_seal(set)
+          if set.equal?(@set)
+            canonicalize(set.seal).sub(/([;:\s]+b=)[^;]*/n, '\1')
+          else
+            canonicalize(set.seal)
+          end
+        end
+
+        def canonicalize(field)
+          Dkim::Canonicalization.field(field, "relaxed")
+        end
+
+        def public_key
+          Dkim::PublicKey.retrieve(selector: @tags["s"], domain: @tags["d"],
+            algorithm: Arc.signing_algorithm(@tags["a"]), resolver: @resolver)
+        end
+
+        def key_name
+          Dkim::PublicKey.name_for(selector: @tags["s"], domain: @tags["d"])
+        end
+
+        def digest
+          Dkim::HASHES.fetch(Arc.hash_algorithm(@tags["a"]))
+        end
+
+        def unfolded(tag)
+          @tags[tag]&.gsub(/[ \t\r\n]+/n, "")
+        end
+
+        def seal(status, comment: nil)
+          ArcSeal.new(status: status, domain: @tags&.[]("d")&.downcase, selector: @tags&.[]("s"),
+            algorithm: @tags&.[]("a"), comment: comment)
+        end
+    end
+  end
+end