mailertogo-spf 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 316234e7966e3e895703bbabc960f8cda0b932d7348e654d7afaf1d97c3ee094
4
- data.tar.gz: 3a20869ecc92f35b8780672af93e7d38223cbc7e6ae6ca7913b678fae541c37c
3
+ metadata.gz: 515bf6379529600ad7beacc48556789e331c00a0366b86026bd10fe2669212b7
4
+ data.tar.gz: b34756b3f424528bcad6f0af09108901f899c19d9d2af28c643873b50d1814c1
5
5
  SHA512:
6
- metadata.gz: d04d30b6ec8059c57d6231ffb786ffb4ce0ad8672b6faad7a29b8f215adbee0c97a3cbeb39078a24ac3988d25d273a6b05b77b02fff51a2be146110ee28927a1
7
- data.tar.gz: 58c318462a651629b0cf7d2f11951dcb419486549a947e82fe5f6195c67f6fc694b636e66686bb87aa4b6aff2c13605f94749f3a6c754795a94f5bd15cdeadfb
6
+ metadata.gz: 5b477518e5e72d58fc8989729eed8cb649637eed89ea6490060d0705387f337e1c7869df6be25d0669a52b7006aaa4a215d96c33c97f01d2e25c8a66d9e0b19e
7
+ data.tar.gz: 479b604d111f491f5efa8c127e8ae8418772f62a6e19bdde28f1bb5e2f2cb3f9f6806c2c88bbc0580b61915aac0fd18880a70bcde13eb3072476bb472707442a
data/CHANGELOG.md CHANGED
@@ -4,6 +4,30 @@ All notable changes to this project are documented here. The format follows
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
5
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.3.0] - 2026-11-18
8
+
9
+ A hosted-SPF record that authorizes you per address was reported as `:fail`.
10
+ It now passes, when the resolver can answer A queries.
11
+
12
+ ### Added
13
+
14
+ - `exists:` terms that use `%{i}` are evaluated (RFC 7208 §5.7, §7). `%{i}`
15
+ expands to each of the sender's own addresses, one per net in its leaf record
16
+ (a single address is itself, a range is its first host), and the record
17
+ authorizes the sender only if it answers for all of them. `%{d}`, `%{o}`,
18
+ `%{v}`, digit and `r` transformers, and delimiters expand too. A macro that
19
+ needs a message (`%{s}`, `%{l}`, `%{h}`, `%{p}`) still leaves the term
20
+ unevaluated. The term still costs one lookup.
21
+ - Optional resolver method `#a(name)`: A records, with the same `[]` / `nil`
22
+ contract as `#call`. `Resolver` implements it, and `CachingResolver` passes it
23
+ through (and caches it) only when the resolver it wraps has it.
24
+ - `MailerToGo::SPF::Macro` — the §7 expansion above, as a pure function.
25
+
26
+ ### Unchanged
27
+
28
+ - A resolver without `#a` (a lambda, for instance) gets exactly the 0.2.1
29
+ results. A failed A lookup gives `:unknown`, never `:fail`.
30
+
7
31
  ## [0.2.1] - 2026-08-17
8
32
 
9
33
  Two `ChainAudit` results could be read as facts when they were really "we did
data/README.md CHANGED
@@ -343,6 +343,31 @@ gem has no runtime dependencies:
343
343
  MailerToGo::SPF::Resolver.new(timeout: 3, nameservers: %w[1.1.1.1 8.8.8.8])
344
344
  ```
345
345
 
346
+ A resolver may also answer A queries, through `#a(name)` with the same
347
+ three-way return (address strings, `[]`, or `nil`). The default resolver does.
348
+ That is what lets the gem evaluate an `exists:` term, which RFC 7208 §5.7
349
+ makes an A query. A resolver without `#a` is not wrong, only TXT-only:
350
+ `exists:` then costs a lookup and matches nothing, as before.
351
+
352
+ It matters for hosted SPF. Some services give each customer one include, and
353
+ that record answers per connecting address against the service's own zone,
354
+ so your include is never named anywhere:
355
+
356
+ ```
357
+ example.com TXT v=spf1 include:abc123.powerspf.com ~all
358
+ abc123.powerspf.com TXT v=spf1 exists:%{i}.abc123.macrospf.powerspf.com ~all
359
+ ```
360
+
361
+ Receivers pass you. With `#a`, the gem expands `%{i}` to your own sending
362
+ addresses (read from your leaf record, one per net: a single address is
363
+ itself, a range is its first host) and asks. The record authorizes you only if
364
+ it answers for **all** of them, because mail leaves from every one. `%{d}`,
365
+ `%{o}`, `%{v}` and the digit and `r` transformers expand too. A macro that needs
366
+ a message (`%{s}`, `%{l}`, `%{h}`, `%{p}`) cannot be expanded, and that term is
367
+ left as before. A failed A lookup gives `:unknown`, never `:fail`. Only a `+`
368
+ `exists:` that uses `%{i}` counts: one without `%{i}` answers the same for
369
+ every sender.
370
+
346
371
  Resolving a chain is up to ten serial round-trips, which is not something to do
347
372
  twice in a request path, so there is a TTL cache. Failures are deliberately not
348
373
  cached — caching a timeout would pin a healthy domain into `:unknown` for the
@@ -376,6 +401,7 @@ DOH = lambda do |name|
376
401
  rescue StandardError
377
402
  nil
378
403
  end
404
+ # For exists:, the same request with type=A, keeping type 1 answers, as DOH.a(name).
379
405
 
380
406
  MailerToGo::SPF.authorize("example.com", resolver: DOH)
381
407
  ```
@@ -391,7 +417,7 @@ zone = {
391
417
  MailerToGo::SPF.authorize("example.com", resolver: ->(name) { zone.fetch(name, []) })
392
418
  ```
393
419
 
394
- The gem's own suite is built that way: 137 examples, zero network access.
420
+ The gem's own suite is built that way: 160 examples, zero network access.
395
421
 
396
422
  ## Configuration
397
423
 
@@ -5,6 +5,7 @@ require "mailertogo/spf/record"
5
5
  require "mailertogo/spf/term"
6
6
  require "mailertogo/spf/result"
7
7
  require "mailertogo/spf/sender"
8
+ require "mailertogo/spf/macro"
8
9
 
9
10
  module MailerToGo
10
11
  module SPF
@@ -24,7 +25,9 @@ module MailerToGo
24
25
  # failure, and anything gated on the answer — verification state, drift
25
26
  # alerts, the ability to send — goes wrong with it. So we RESOLVE the chain:
26
27
  # follow `include:` (and the `redirect=` modifier) until we reach a name the
27
- # sender owns, or an ip4/ip6 mechanism covering the sender's addresses.
28
+ # sender owns, or an ip4/ip6 mechanism covering the sender's addresses —
29
+ # or, with a resolver that answers A queries, an `exists:` that says yes
30
+ # to the sender's addresses (see #exists!).
28
31
  #
29
32
  # RFC 7208 §4.6.4 caps an evaluation at 10 DNS-querying mechanisms; past
30
33
  # that a receiver returns PERMERROR and the record does NOT pass. We enforce
@@ -106,6 +109,8 @@ module MailerToGo
106
109
  @ip_coverage = nil
107
110
  @ip_match_at = nil
108
111
  @all_qualifier = nil
112
+ @matched_exists = nil
113
+ @exists_pending = nil
109
114
  end
110
115
 
111
116
  def run
@@ -126,7 +131,7 @@ module MailerToGo
126
131
  record = records.first
127
132
  return failure("No v=spf1 record on #{@host}") if record.nil?
128
133
 
129
- walk(record, depth: 0, authoritative: true)
134
+ walk(record, depth: 0, domain: @host, authoritative: true)
130
135
  match_by_ip! if @match_at.nil?
131
136
 
132
137
  # Over budget beats everything: receivers PERMERROR such a record, so it
@@ -178,7 +183,9 @@ module MailerToGo
178
183
  # `authoritative` marks the records whose `all` decides the domain's
179
184
  # answer — the apex and anything it redirect=s to, never an include's (an
180
185
  # included record's `all` never leaves that include, §5.2).
181
- def walk(record, depth:, authoritative: false)
186
+ #
187
+ # `domain` is the name the record was published at: %{d} (§7.2).
188
+ def walk(record, depth:, domain:, authoritative: false)
182
189
  terms = Record.terms(record)
183
190
  note_sender_names(terms, depth)
184
191
  redirect = nil
@@ -218,6 +225,10 @@ module MailerToGo
218
225
  # a sending service publishes an include target, never an a/mx
219
226
  # mechanism a customer would borrow.
220
227
  @lookups += 1
228
+ # A `+exists:` can still authorize the sender's ADDRESSES. Any
229
+ # other qualifier would end evaluation with a non-pass, which
230
+ # this walk does not model for any mechanism.
231
+ exists!(t.split(":", 2).last, domain, depth) if mechanism == "exists" && [nil, "+"].include?(qualifier)
221
232
  end
222
233
  end
223
234
  end
@@ -255,10 +266,7 @@ module MailerToGo
255
266
  return if name.empty?
256
267
 
257
268
  if @sender.covers?(name)
258
- if @matched.nil?
259
- @matched = name
260
- @matched_directly = depth.zero?
261
- end
269
+ first_match(name, depth)
262
270
  # The mechanism that ended the evaluation, and the budget it had spent
263
271
  # by then — the only count §4.6.4 measures.
264
272
  @match_at = @lookups
@@ -287,7 +295,67 @@ module MailerToGo
287
295
 
288
296
  return if records.first.nil?
289
297
 
290
- walk(records.first, depth: depth + 1, authoritative: authoritative)
298
+ walk(records.first, depth: depth + 1, domain: name, authoritative: authoritative)
299
+ end
300
+
301
+ # An `exists:` whose name expands %{i} asks DNS "is THIS address allowed?".
302
+ # Hosted-SPF services work that way: the customer publishes one include
303
+ # per account, and that record answers per address against the service's
304
+ # own zone, so the sender is never named anywhere (§5.7, §7):
305
+ #
306
+ # example.com TXT v=spf1 include:abc123.powerspf.com ~all
307
+ # abc123.powerspf.com TXT v=spf1 exists:%{i}.abc123.macrospf.powerspf.com ~all
308
+ #
309
+ # We ask it about our own addresses, as a receiver would for mail from us.
310
+ #
311
+ # ALL of them, not any: mail leaves from every one of our nets, and a
312
+ # record that passes only some of it is not an authorization. Each
313
+ # address is settled by the first exists: that answers for it (§4.6.2
314
+ # stops there), so two terms that each cover half our nets still
315
+ # authorize us, and the match lands where the LAST address is settled —
316
+ # the most budget any one of our messages spends.
317
+ #
318
+ # Only %{i} makes a term about us; one with no %{i} answers the same for
319
+ # every sender. A macro that needs a message (%{s}, %{l}, %{h}, …) cannot
320
+ # be expanded, and the term is left exactly as before: counted, unmatched.
321
+ # A failed A lookup marks the walk partial, so it can end :unknown but
322
+ # never :fail.
323
+ def exists!(spec, domain, depth)
324
+ return unless @lookup.respond_to?(:a) && Macro.per_address?(spec)
325
+
326
+ pending = (@exists_pending ||= our_nets.map { |net| representative(net) })
327
+ names = pending.map { |ip| Macro.expand(spec, address: ip, domain: domain, sender_domain: @host) }
328
+ return if pending.empty? || names.include?(nil)
329
+
330
+ answers = names.map { |name| @lookup.a(name) }
331
+ @dns_error = true if answers.include?(nil)
332
+ @exists_pending = pending.zip(answers).select { |_ip, answer| Array(answer).empty? }.map(&:first)
333
+ return unless @exists_pending.empty?
334
+
335
+ first_match(spec, depth)
336
+ @matched_exists = spec
337
+ @match_at = @lookups
338
+ end
339
+
340
+ # One address to stand for a sending net when expanding %{i}: its first
341
+ # host. A receiver only ever sees a host address, and a network address
342
+ # never connects to anyone. A /32 (/128) is its own address, and a /31
343
+ # (/127) reserves nothing (RFC 3021), so its first address is a host.
344
+ def representative(net)
345
+ host_bits = (net.ipv4? ? 32 : 128) - net.prefix
346
+ IPAddr.new(net.to_i + (host_bits > 1 ? 1 : 0), net.family)
347
+ end
348
+
349
+ # The sender's nets, read once per evaluation and shared by the exists:
350
+ # and pinned checks.
351
+ def our_nets = @our_nets ||= self.class.sending_nets(@sender, @lookup)
352
+
353
+ # `matched` reports the FIRST name in the record that meant us.
354
+ def first_match(name, depth)
355
+ return unless @matched.nil?
356
+
357
+ @matched = name
358
+ @matched_directly = depth.zero?
291
359
  end
292
360
 
293
361
  # [records_array, error_or_nil] — error is :error when DNS itself failed.
@@ -312,7 +380,7 @@ module MailerToGo
312
380
  def match_by_ip!
313
381
  return if @customer_nets.empty?
314
382
 
315
- ours = self.class.sending_nets(@sender, @lookup)
383
+ ours = our_nets
316
384
  return if ours.empty?
317
385
 
318
386
  # "Covered" = the customer's term authorizes one of the sender's ranges
@@ -341,7 +409,10 @@ module MailerToGo
341
409
  end
342
410
 
343
411
  def pass
344
- detail = if @matched_directly
412
+ detail = if @matched_exists
413
+ "SPF authorizes #{@want}'s sending addresses through exists:#{@matched_exists} " \
414
+ "(#{pluralize(@lookups, "DNS lookup")})"
415
+ elsif @matched_directly
345
416
  "SPF includes #{@matched}"
346
417
  else
347
418
  "SPF reaches #{@matched} through its include chain (#{pluralize(@lookups, "DNS lookup")})"
@@ -0,0 +1,82 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ipaddr"
4
+
5
+ module MailerToGo
6
+ module SPF
7
+ # RFC 7208 §7 macro expansion — the part of it that does not need a message.
8
+ #
9
+ # A receiver expands macros from the SMTP session: the connecting address,
10
+ # the envelope sender, the HELO name. We have no session. But the
11
+ # authorization question is about one thing we DO know — the addresses we
12
+ # send from — so %{i} (and %{v}, which is only that address's family) can
13
+ # be expanded exactly as a receiver would for mail from us. %{d} (the
14
+ # domain whose record is being evaluated) and %{o} (the sender's domain)
15
+ # are known too.
16
+ #
17
+ # Everything else (%{s} %{l} %{h} %{p}) depends on a message we do not
18
+ # have. A string that uses any of them expands to nil — "cannot say" — and
19
+ # the caller treats the term exactly as it did before macros were read.
20
+ module Macro
21
+ # §7.1: %{ letter [digits] [r] [delimiters] }, the three escapes, a
22
+ # literal run, or a bare `%` (a syntax error, so: cannot say).
23
+ TOKEN = %r{%\{(?<letter>[a-z])(?<digits>\d*)(?<reverse>r?)(?<delims>[.\-+,/_=]*)\}|
24
+ %(?<escape>[%_-])|(?<literal>[^%]+)|%}xi
25
+ ESCAPES = { "%" => "%", "_" => " ", "-" => "%20" }.freeze
26
+
27
+ # §7.3: an expanded name longer than this loses labels from the left.
28
+ MAX_NAME = 253
29
+
30
+ module_function
31
+
32
+ # Does this domain-spec depend on the connecting address? Only such a term
33
+ # says anything about US rather than about every sender at once.
34
+ def per_address?(spec) = spec.to_s.match?(/%\{i/i)
35
+
36
+ # spec — a domain-spec from a record, e.g. "%{ir}.%{v}._spf.example.com"
37
+ # address — IPAddr: the connecting address %{i} stands for
38
+ # domain — %{d}, the domain whose record holds the term
39
+ # sender_domain — %{o}, the domain of the envelope sender
40
+ #
41
+ # Returns the expanded name, or nil when the spec uses a macro that needs
42
+ # a message (or is malformed).
43
+ def expand(spec, address:, domain:, sender_domain:)
44
+ values = {
45
+ "i" => dotted(address),
46
+ "v" => address.ipv4? ? "in-addr" : "ip6",
47
+ "d" => domain,
48
+ "o" => sender_domain,
49
+ }
50
+ name = spec.to_s.gsub(TOKEN) do
51
+ m = Regexp.last_match
52
+ next m[:literal] if m[:literal]
53
+ next ESCAPES.fetch(m[:escape]) if m[:escape]
54
+
55
+ # An upper-case letter asks for URL escaping (§7.3); every value we
56
+ # can supply is already URL-safe, so case does not matter here.
57
+ value = m[:letter] && values[m[:letter].downcase]
58
+ # §7.1: a DIGIT transformer of zero is invalid.
59
+ return nil if value.nil? || m[:digits] == "0"
60
+
61
+ transform(value, m[:digits], m[:reverse], m[:delims])
62
+ end
63
+ name = name.sub(/\A[^.]*\./, "") while name.length > MAX_NAME && name.include?(".")
64
+ name
65
+ end
66
+
67
+ # §7.3: split on the delimiters (default "."), reverse if asked, keep the
68
+ # rightmost N parts, rejoin with ".".
69
+ def transform(value, digits, reverse, delims)
70
+ parts = value.split(Regexp.union((delims.empty? ? "." : delims).chars))
71
+ parts.reverse! unless reverse.empty?
72
+ parts = parts.last(digits.to_i) unless digits.empty?
73
+ parts.join(".")
74
+ end
75
+
76
+ # §7.3: IPv4 is dotted-quad; IPv6 is 32 dot-separated nibbles.
77
+ def dotted(address)
78
+ address.ipv4? ? address.to_s : address.to_string.delete(":").chars.join(".")
79
+ end
80
+ end
81
+ end
82
+ end
@@ -20,6 +20,12 @@ module MailerToGo
20
20
  # authorise you". Everything in this gem funnels a nil into an :unknown
21
21
  # result rather than a :fail.
22
22
  #
23
+ # Optionally, a resolver may also respond to `#a(name)` with the same
24
+ # three-way return for A records (address strings). That is what lets an
25
+ # `exists:` term (§5.7, always an A query) be evaluated. A resolver without
26
+ # it is not wrong, only TXT-only: `exists:` then costs budget and matches
27
+ # nothing, as before `#a` existed.
28
+ #
23
29
  # A plain lambda satisfies the contract, which is how the test suite runs
24
30
  # with no network at all:
25
31
  #
@@ -40,13 +46,23 @@ module MailerToGo
40
46
  end
41
47
 
42
48
  def call(name)
49
+ resources(name, ::Resolv::DNS::Resource::IN::TXT)&.map { |r| r.strings.join }
50
+ end
51
+
52
+ def a(name)
53
+ resources(name, ::Resolv::DNS::Resource::IN::A)&.map { |r| r.address.to_s }
54
+ end
55
+
56
+ private
57
+
58
+ def resources(name, type)
43
59
  query = Record.normalize_name(name)
44
60
  return [] if query.empty?
45
61
 
46
62
  dns = @nameservers ? ::Resolv::DNS.new(nameserver: Array(@nameservers)) : ::Resolv::DNS.new
47
63
  dns.timeouts = @timeout
48
64
  begin
49
- dns.getresources(query, ::Resolv::DNS::Resource::IN::TXT).map { |r| r.strings.join }
65
+ dns.getresources(query, type)
50
66
  ensure
51
67
  dns.close
52
68
  end
@@ -79,19 +95,37 @@ module MailerToGo
79
95
  end
80
96
 
81
97
  def call(name)
98
+ fetch(Record.normalize_name(name)) { |key| @resolver.call(key) }
99
+ end
100
+
101
+ def a(name)
82
102
  key = Record.normalize_name(name)
103
+ fetch("A #{key}") { @resolver.a(key) }
104
+ end
105
+
106
+ # Answers A queries only when the resolver it wraps can, so wrapping a
107
+ # TXT-only resolver changes nothing about what `exists:` does.
108
+ def respond_to?(name, include_all = false) # rubocop:disable Style/OptionalBooleanParameter -- Object#respond_to? signature
109
+ return @resolver.respond_to?(:a) if name.to_sym == :a
110
+
111
+ super
112
+ end
113
+
114
+ def clear
115
+ @mutex.synchronize { @entries.clear }
116
+ end
117
+
118
+ private
119
+
120
+ def fetch(key)
83
121
  now = @clock.call
84
122
  cached = @mutex.synchronize { @entries[key] }
85
123
  return cached[1] if cached && cached[0] > now
86
124
 
87
- answer = @resolver.call(key)
125
+ answer = yield key
88
126
  @mutex.synchronize { @entries[key] = [now + @ttl, answer] } unless answer.nil?
89
127
  answer
90
128
  end
91
-
92
- def clear
93
- @mutex.synchronize { @entries.clear }
94
- end
95
129
  end
96
130
  end
97
131
  end
@@ -2,6 +2,6 @@
2
2
 
3
3
  module MailerToGo
4
4
  module SPF
5
- VERSION = "0.2.1"
5
+ VERSION = "0.3.0"
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: mailertogo-spf
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.1
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - MailerToGo
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-08-17 00:00:00.000000000 Z
11
+ date: 2026-11-18 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: |
14
14
  An SPF engine that follows include:/redirect= chains, stops at the first
@@ -33,6 +33,7 @@ files:
33
33
  - lib/mailertogo/spf/authorization.rb
34
34
  - lib/mailertogo/spf/chain_audit.rb
35
35
  - lib/mailertogo/spf/hostname.rb
36
+ - lib/mailertogo/spf/macro.rb
36
37
  - lib/mailertogo/spf/merge_plan.rb
37
38
  - lib/mailertogo/spf/plan.rb
38
39
  - lib/mailertogo/spf/record.rb