mailertogo-spf 0.2.0 → 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 +4 -4
- data/CHANGELOG.md +54 -0
- data/README.md +43 -1
- data/lib/mailertogo/spf/authorization.rb +81 -10
- data/lib/mailertogo/spf/chain_audit.rb +28 -7
- data/lib/mailertogo/spf/macro.rb +82 -0
- data/lib/mailertogo/spf/resolver.rb +40 -6
- data/lib/mailertogo/spf/version.rb +1 -1
- metadata +3 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 515bf6379529600ad7beacc48556789e331c00a0366b86026bd10fe2669212b7
|
|
4
|
+
data.tar.gz: b34756b3f424528bcad6f0af09108901f899c19d9d2af28c643873b50d1814c1
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 5b477518e5e72d58fc8989729eed8cb649637eed89ea6490060d0705387f337e1c7869df6be25d0669a52b7006aaa4a215d96c33c97f01d2e25c8a66d9e0b19e
|
|
7
|
+
data.tar.gz: 479b604d111f491f5efa8c127e8ae8418772f62a6e19bdde28f1bb5e2f2cb3f9f6806c2c88bbc0580b61915aac0fd18880a70bcde13eb3072476bb472707442a
|
data/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,60 @@ 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
|
+
|
|
31
|
+
## [0.2.1] - 2026-08-17
|
|
32
|
+
|
|
33
|
+
Two `ChainAudit` results could be read as facts when they were really "we did
|
|
34
|
+
not look". Both are corrected in the direction of admitting it.
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
|
|
38
|
+
- `ChainAudit#total` (and `#headroom`) are **`nil` rather than `0`** for a name
|
|
39
|
+
that publishes no record, or when DNS did not answer. `0` is a legitimate
|
|
40
|
+
total — `v=spf1 -all` costs exactly that — so a caller that skipped
|
|
41
|
+
`#published?` could report "this record costs 0 lookups" about a domain with
|
|
42
|
+
no record. A record that legitimately costs nothing still reports `0`.
|
|
43
|
+
- Duplicate records **at the hostname itself** are reported by the new
|
|
44
|
+
`#apex_duplicated?` instead of being pushed onto `#duplicated_in_chain`. RFC
|
|
45
|
+
7208 §4.5 makes them a permerror either way, but the apex is not *in* the
|
|
46
|
+
chain — it is the record being priced. Folding them together made the same
|
|
47
|
+
domain audit differently depending on whether the caller supplied `record:` or
|
|
48
|
+
let the gem resolve the apex, and a caller raising its own duplicate-record
|
|
49
|
+
defect from the records it resolved would have raised it twice.
|
|
50
|
+
|
|
51
|
+
### Added
|
|
52
|
+
|
|
53
|
+
- `ChainAudit#apex_duplicated?` — `true`/`false` when the gem resolved the apex,
|
|
54
|
+
and `nil` ("cannot say") when the record was supplied or DNS did not answer.
|
|
55
|
+
|
|
56
|
+
### Changed
|
|
57
|
+
|
|
58
|
+
- `#duplicated_in_chain` no longer contains the audited hostname. Callers that
|
|
59
|
+
want that fact ask `#apex_duplicated?`.
|
|
60
|
+
|
|
7
61
|
## [0.2.0] - 2026-08-17
|
|
8
62
|
|
|
9
63
|
Answers a second question about a record: not only "does it authorize me, and
|
data/README.md
CHANGED
|
@@ -227,6 +227,22 @@ permerrors the whole evaluation rather than quietly doing nothing:
|
|
|
227
227
|
```ruby
|
|
228
228
|
audit.targets_without_spf # => ["nothing.example.net"] — include: of a name with no SPF (§5.2)
|
|
229
229
|
audit.duplicated_in_chain # => ["two.example.net"] — two v=spf1 records in the chain (§4.5)
|
|
230
|
+
audit.apex_duplicated? # => false — two at the hostname itself (§4.5)
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
`apex_duplicated?` is deliberately separate from `duplicated_in_chain`: the
|
|
234
|
+
hostname is not *in* the chain, it is the record being priced. It answers `nil`
|
|
235
|
+
— "cannot say" — when you supplied the `record:` yourself, because then we never
|
|
236
|
+
looked at the apex. A caller that resolved the apex already knows, and should
|
|
237
|
+
report from what it saw rather than ask twice.
|
|
238
|
+
|
|
239
|
+
A record that does not exist cannot be priced, so `total` and `headroom` are
|
|
240
|
+
`nil` rather than `0`. Check `published?` first:
|
|
241
|
+
|
|
242
|
+
```ruby
|
|
243
|
+
audit = MailerToGo::SPF.chain_audit("no-spf.example.com")
|
|
244
|
+
audit.published? # => false
|
|
245
|
+
audit.total # => nil — not 0; `v=spf1 -all` legitimately costs 0
|
|
230
246
|
```
|
|
231
247
|
|
|
232
248
|
Two honesty flags, because a count you could not finish must never read as "it
|
|
@@ -327,6 +343,31 @@ gem has no runtime dependencies:
|
|
|
327
343
|
MailerToGo::SPF::Resolver.new(timeout: 3, nameservers: %w[1.1.1.1 8.8.8.8])
|
|
328
344
|
```
|
|
329
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
|
+
|
|
330
371
|
Resolving a chain is up to ten serial round-trips, which is not something to do
|
|
331
372
|
twice in a request path, so there is a TTL cache. Failures are deliberately not
|
|
332
373
|
cached — caching a timeout would pin a healthy domain into `:unknown` for the
|
|
@@ -360,6 +401,7 @@ DOH = lambda do |name|
|
|
|
360
401
|
rescue StandardError
|
|
361
402
|
nil
|
|
362
403
|
end
|
|
404
|
+
# For exists:, the same request with type=A, keeping type 1 answers, as DOH.a(name).
|
|
363
405
|
|
|
364
406
|
MailerToGo::SPF.authorize("example.com", resolver: DOH)
|
|
365
407
|
```
|
|
@@ -375,7 +417,7 @@ zone = {
|
|
|
375
417
|
MailerToGo::SPF.authorize("example.com", resolver: ->(name) { zone.fetch(name, []) })
|
|
376
418
|
```
|
|
377
419
|
|
|
378
|
-
The gem's own suite is built that way:
|
|
420
|
+
The gem's own suite is built that way: 160 examples, zero network access.
|
|
379
421
|
|
|
380
422
|
## Configuration
|
|
381
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
|
-
|
|
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
|
-
|
|
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 =
|
|
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 @
|
|
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")})"
|
|
@@ -70,10 +70,12 @@ module MailerToGo
|
|
|
70
70
|
@resolver = resolver
|
|
71
71
|
@term_class = term_class || Term
|
|
72
72
|
@spent = 0
|
|
73
|
-
@total =
|
|
73
|
+
@total = nil
|
|
74
74
|
@terms = []
|
|
75
75
|
@targets_without_spf = []
|
|
76
76
|
@duplicated_in_chain = []
|
|
77
|
+
# nil until we resolve the apex ourselves — "cannot say", not "no".
|
|
78
|
+
@apex_duplicated = nil
|
|
77
79
|
@resolved = true
|
|
78
80
|
@partial = false
|
|
79
81
|
@capped = false
|
|
@@ -100,7 +102,11 @@ module MailerToGo
|
|
|
100
102
|
seen_all ||= term.all?
|
|
101
103
|
end
|
|
102
104
|
|
|
103
|
-
|
|
105
|
+
# nil, not 0, when there is nothing to price. 0 is a legitimate total —
|
|
106
|
+
# `v=spf1 -all` costs exactly that — so using it for "no record" lets a
|
|
107
|
+
# caller that skipped #published? report "this record costs 0 lookups"
|
|
108
|
+
# about a domain with no record at all.
|
|
109
|
+
@total = published? ? @spent : nil
|
|
104
110
|
self
|
|
105
111
|
end
|
|
106
112
|
|
|
@@ -128,10 +134,20 @@ module MailerToGo
|
|
|
128
134
|
# the number is a floor — for a different reason.
|
|
129
135
|
def capped? = @capped
|
|
130
136
|
|
|
137
|
+
# Was there more than one v=spf1 record at the hostname itself? §4.5 makes
|
|
138
|
+
# that a permerror just as surely as duplicates inside the chain.
|
|
139
|
+
#
|
|
140
|
+
# nil means "cannot say" rather than "no": the record was handed to us, so
|
|
141
|
+
# we never looked at the apex (or DNS did not answer). Only a caller that
|
|
142
|
+
# let us resolve the apex gets a true/false here — the one that resolved it
|
|
143
|
+
# already knows, and should report from what it saw rather than ask us.
|
|
144
|
+
def apex_duplicated? = @apex_duplicated
|
|
145
|
+
|
|
131
146
|
# How many lookups are still available before the cap, or nil when we
|
|
132
|
-
# cannot say (a floor cannot answer "how much room is left"
|
|
147
|
+
# cannot say (a floor cannot answer "how much room is left", and neither
|
|
148
|
+
# can a record that does not exist).
|
|
133
149
|
def headroom
|
|
134
|
-
return nil if partial? || capped?
|
|
150
|
+
return nil if partial? || capped? || !published?
|
|
135
151
|
|
|
136
152
|
[LIMIT - @total.to_i, 0].max
|
|
137
153
|
end
|
|
@@ -150,9 +166,14 @@ module MailerToGo
|
|
|
150
166
|
|
|
151
167
|
records = Array(txts).map { |t| Record.normalize_txt(t) }.select { |t| Record.spf_record?(t) }
|
|
152
168
|
# §4.5 — two records at the apex permerror the evaluation just as surely
|
|
153
|
-
# as two anywhere else in the chain
|
|
154
|
-
#
|
|
155
|
-
|
|
169
|
+
# as two anywhere else in the chain. It is reported SEPARATELY from
|
|
170
|
+
# `duplicated_in_chain` even so, because the apex is not *in* the chain:
|
|
171
|
+
# it is the record being priced. Folding it in made the same domain audit
|
|
172
|
+
# differently depending on whether the caller resolved the apex or we
|
|
173
|
+
# did, and a caller that raises its own duplicate-record defect from the
|
|
174
|
+
# records it resolved would then raise it twice.
|
|
175
|
+
@apex_duplicated = records.size > 1
|
|
176
|
+
# We price the first, because there has to be something to read.
|
|
156
177
|
@record = records.first.to_s
|
|
157
178
|
end
|
|
158
179
|
|
|
@@ -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,
|
|
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 =
|
|
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
|
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.
|
|
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-
|
|
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
|